id(ssh): input and presentation designs #535

What and why

Designs for how SSH (and other terminal) sessions take input and present worlds, beyond the raw default and cmd: line mode that shipped in #211. Each needs a design, or a research package where marked, before implementation. Ticked when its design is committed and an implementation issue exists. Not tracked: D1-049 (two SSH channels on one connection), which both reports say not to build until a real client exists.

Items

Each box is done when the design (or research package) is committed and an implementation issue is linked here.

• D1-040 — Documents as a session frame pair (web/CLI parity) (M, design)
  Move /documents and /document from an SSH-local blob read to a documents/document ClientFrame/ServerFrame pair in world_session.rs, like records, so web and CLI clients can read world documents too.
  • Status: not started. grep -n '"documents"\|"document"' pkgs/id/src/world_session.rs finds nothing; documents exist only in world_ssh.rs (:455).
  • Source: RPT §7 Step 1 'Decision to record'; RPT §16 Q3; RPT §12 Later
  • Prerequisites: id(ssh): fix #211 reconciliation gaps: total records cap, document output through send, per-world document store #548 — D1-039 Fix feat(ssh): add chat and document viewing to worlds #211 reconciliation gaps: total records cap, document output through send, per-world document store
  • Design: doc/2026-11-01T16-05-00Z_design_documents_session_frames/ (PR docs(id): D1-040 documents frame-pair design + D1-045 command-toggle research (#535) #3760, merged 2026-11-01); implementation: id(session): implement the documents/document frame pair (D1-040, from #535) #3762
• D1-045 — In-session command toggle (prefix key + visible mode indicator) (M, research package)
  While in raw mode, a prefix key (Ctrl-P or ~ Enter) opens a command prompt line with a visible indicator; /quit or the prefix returns to raw. Only if users ask for it.
  • Status: not started. The raw arm of SshIo::recv forwards bytes unconditionally (pkgs/id/src/world_ssh.rs:421-424); there is no prefix handling.
  • Source: REF:106-112, 135-149 (shape 3, triggers); RPT §7 Step 3.1; RPT §16 Q4
  • Prerequisites: id: one line grammar for SSH command mode, the id world join pump and CLI verbs (--command-mode) #546 — D1-041 One line grammar shared by SSH command mode, id world join pump and CLI verbs (+ --command-mode)
• D1-046 — Split UI on one PTY (world grid + pinned command row, focus routing) (L, research package)
  The server draws the world region plus a pinned bottom command row, and keystrokes route by focus; buffered output to the command region enables server-side autocomplete mid-game. The web client already has this shape (separate chat form).
  • Status: not started. No region or focus state in pkgs/id/src/world_ssh.rs; the web split exists (RPT cites pkgs/id/web/src/world.ts:524-533 chat form).
  • Source: REF:88-93 (shape 1); RPT §5 shape 1; RPT §7 Step 3.2
  • Prerequisites: id(ssh): incremental (diff) ANSI renderer instead of full clear-repaint #562 — D1-044 Incremental (diff) ANSI renderer instead of full clear-repaint, D1-045 In-session command toggle (prefix key + visible mode indicator) (in this list)
• D1-048 — Roc partial-line surface: non-journaled 'viewer is typing' notification to guests (L, design)
  Pass the viewer's partial line to the program so a Roc app can render live autocomplete or a validating form. It is a new guest-facing surface and needs its own design: which event carries it, that it is never journaled, and its bounds.
  • Status: not started. Guests receive only committed Input bytes and System events (RPT cites sandbox.rs:677-685); no typing event kind exists in WorldEventKind.
  • Source: REF:161-164; RPT §5 'Extended to Roc apps'; RPT §7 Step 3.4
  • Prerequisites: D1-046 Split UI on one PTY (world grid + pinned command row, focus routing) (in this list), id: Phase 12 designs to run through the research workflow #534 (tracking issue) — D1-025 F12.7 Versioned guest ABI spec, plaza_abi_version export, conformance suite
• D1-052 — Presentation capability tiers with in-band terminal detection (ghostty-class default) (XL, design)
  Target ghostty/kitty/wezterm as tier 1 (kitty keyboard protocol, kitty graphics or sixel, synchronized output DEC 2026, high fps), xterm-class as tier 2 (escape-timeout keys, cell grid, batching and diff rendering), and line mode as tier 3. Detection is in-band (XTGETTCAP, CSI ? u, DECRQM), so it works the same over SSH and iroh.
  • Status: not started. grep -rn -i 'kitty\|XTGETTCAP\|DECRQM\|2026h\|sixel' pkgs/id/src pkgs/id/examples finds nothing; key parsing is legacy-byte heuristics in pkgs/id/examples/roc-world/Key.roc.
  • Source: RPT §14 (all); RPT §16 Q6
  • Prerequisites: id(ssh): use the alternate screen for raw interactive SSH sessions #545 — D1-042 Alternate screen for the raw interactive SSH session, id: server-side redraw batching (few-ms frame coalescing) for all presentations #561 — D1-043 Server-side redraw batching (few-ms frame coalescing) for all presentations, id(ssh): incremental (diff) ANSI renderer instead of full clear-repaint #562 — D1-044 Incremental (diff) ANSI renderer instead of full clear-repaint
• D1-053 — Kitty keyboard protocol on the raw input path (M, design)
  Negotiate the kitty keyboard protocol (CSI > u) where supported, so Escape vs Alt is unambiguous and key events go beyond the legacy byte stream; extend Key.parse and the browser encoder to match.
  • Status: not started. Key.parse decodes legacy sequences only (pkgs/id/examples/roc-world/Key.roc; RPT §2 lists the tag union). No negotiation in world_ssh.rs.
  • Source: RPT §14 Tier 1 and last paragraph
  • Prerequisites: D1-052 Presentation capability tiers with in-band terminal detection (ghostty-class default) (in this list)

Source

• REF:106-112, 135-149 (shape 3, triggers)
• REF:161-164
• REF:88-93 (shape 1)
• RPT §12 Later
• RPT §14 (all)
• RPT §14 Tier 1 and last paragraph
• RPT §16 Q3
• RPT §16 Q4
• RPT §16 Q6
• RPT §5 'Extended to Roc apps'
• RPT §5 shape 1
• RPT §7 Step 1 'Decision to record'
• RPT §7 Step 3.1
• RPT §7 Step 3.2
• RPT §7 Step 3.4

RPT = doc/2026-10-18T18-40-00Z_report_platform_world_state/2026-10-18T18-40-00Z_report_platform_world_state.md, REF = doc/2026-10-18T00-00-00Z_reference_platform_state/2026-10-18T00-00-00Z_reference_platform_state.md. Both are uncommitted reports in the platform-world-apps-migration worktree.

Size

XL overall (items M to XL)

Prerequisites

Listed per item above.

Acceptance criteria

• Every item listed above has its design (or research package, where marked) committed to the repo
• Every item has a linked implementation issue, and its checkbox above is ticked only once both are true
• No item is closed out on the basis of a plan or report reference alone — the committed artifact is the evidence