Chase CichorzandClaude Opus 5.5
551ef86d5f
A controlled reader renders accepted application frames in a new virtual-only cthulhu-braille mode at the controller's width and applies its pan and route gestures; reader UI, flashes and secure frames are never exported, and hidden frames are unroutable. A controller reader reports its display width, shows peer cells as an untranslated raw frame and forwards local pan and routing keys. The physical helper now reports its width and edge pans. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
64 lines
3.7 KiB
Markdown
64 lines
3.7 KiB
Markdown
# 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.
|