cthulhu/docs/tentacle-remote-braille.md

Remote Braille IPC

Protocol 1.1 carries Remote Braille through one child-to-host method, remote.braille, and one host-to-child event kind of the same name. Both need the current process session's live lease with the separately approved braille-stream grant; requests share the operation sequence. Every message carries one braille object whose op selects its form:

op	Direction and role	Fields
size	controlled child to host	width 0–4,096: the controller's display; 0 stops export
gesture	controlled child to host; host to controller child	gesture pan-left, pan-right or route, with index for route
cells	host to controlled child; controller child to host	cells: 1–4,096 final dot values 0–255, never text
geometry	controller child to host (no width); host reply event with width	0 means no local display

The request reply acknowledges admission into a 16-item reader mailbox; a full mailbox revokes the lease. Without an attached reader owner the method returns owner-unavailable. No AT-SPI identity, object path, routing map or native handle crosses this boundary: routes are cell indexes into the latest exported frame only. Session.EnableRemoteBraille, PublishRemoteBraille, the Go RemoteBraille types and validators and the Python valid_remote_braille and valid_remote_braille_request validators implement the contract. Go/Python SDK-process tests cover each direction, role denial, invalid values, saturation and revocation.

Reader owners

start_remote_braille attaches an owner for sessions installed with braille-stream, from local launch and managed startup.

Controlled computer. A size request starts cthulhu-braille --virtual, a helper mode that opens no display and reuses the physical helper's viewport, liblouis translation, wrapping, panning and routing maps. The owner installs an exporter on the Braille worker that receives only accepted application frames. Reader UI, flashed messages and secure-input frames are never exported. A frame stored while reader UI, a protected confirmation or a peer's cells hide it is exported with ID 0 so it cannot be routed. Rendered cells become cells events. Gestures pan the virtual viewport or route a cell; a route reaches the application only if it names the frame currently shown here, so a stale or hidden frame is ignored.

Ordinary frames have no BRLTTY to translate them, so the virtual helper uses an explicit table, en-us-comp8.ctb (computer Braille); contracted frames keep the user's configured table. The cursor is a static dots-7-8 overlay, not BRLTTY's configured cursor shape or blink.

Controller. The physical helper now reports its width in its ready line (ready N; a bare ready is still accepted), answering geometry. Peer cells are shown as Unicode Braille runes in a raw frame, sent without contraction or word wrap so the helper writes the exact dots. They take the place of the application frame, which keeps updating underneath; reader UI and flashed messages still take precedence and restore to the peer's cells. The helper now also reports a pan key that cannot move the local viewport; on a peer frame that, and a routing key, become gesture events. Revocation, lock or handoff restores the application frame.

Tests: liblouis-backed virtual helper tests (computer Braille, cursor overlay, pan and pan-back, routing, contracted table, invalid input); a smoke run of the built helper; and app tests with a fake helper and a real Go SDK child for both roles: application-only export, unroutable frames under reader UI, routing to the application, gesture forwarding, peer cells overriding local frames, stale-route rejection and restoration on revocation. No physical display was used.