# 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.