Repository navigation
id: idea — native TUI client (ratatui) on the shell contract #1071
Description
Idea: native TUI client (ratatui)
From pkgs/id/TODO.md:
A high-performance TUI (ratatui or the best-performing Rust TUI stack) that works locally without a server, or connects to a local/remote server over iroh (not SSH). Custom efficient protocol: the server sends intents and bytes (e.g. 'draw this blob at 64x,16y at 256x256', kitty image protocol) instead of a raw terminal stream, with thought given to avoiding a second round trip for uncached blobs. Roughly three panels: room/object selector + search + pinned favourites | the interactive room/document or meta pages | a chatroom for the room/topic. Should cover what the website does, with native filesystem access and full control of the box.
Long-term idea, filed so it is tracked. Related: Phase 13 shell contract (#783, done) is the contract a TUI shell would implement.
Coordination (2026-10-26 reprioritization, per Drew): every id roadmap item now has its own GitHub issue, and priority encodes the order: (1) the path to Phase 12 — now + priority/high; (2) Phase 12 itself — next; (3) Phase 13 and long-term ideas — priority/low. The dashboard mirrors this list (org Project "Developing Today" #4, Area id-train; Grist Program roadmap, Area id). If this item turns out to be blocked, wrong, or superseded, park or close it with a note rather than letting it stall the queue — dropping an issue is always allowed; silently stalling is not.
Acceptance criteria
- A design note is recorded on this issue covering: the intent/byte protocol (incl. blob caching / no-second-round-trip), the three-panel layout, and local vs iroh-remote modes.
- The relationship to the Phase 13 shell contract (id: Phase 13 F13.1 versioned shell contract (client-server frame spec + conformance check) #783) is stated — what the TUI implements vs. what it adds.
- If adopted, a first implementation step is filed as its own issue; if dropped, the reason is recorded here.
Activity
developing-today commentedon Oct 27, 2026
CODE-215
dezren39 commentedon Oct 27, 2026
Intake review
Related: Phase 13 shell contract: #783 · sibling idea: native GUI client #1072 · source:
pkgs/id/TODO.mdNotes: Long-term, priority/low. The shell contract it would implement is done (#783), so the design note can be concrete about the contract surface rather than speculative.
Risks: Designing a custom protocol without the round-trip analysis the TODO asks for would bake in the latency the idea exists to avoid.
Suggested approach: Start from the shell contract's operations and map each to the intent protocol; call out where server-side state (blob cache) is required.
Labels were already normalized by the filer (kind, source/human, status/needs-triage, priority, effort, app/id all present); this pass appended the acceptance criteria above and adds
meta/enriched.🤖 Agent note · filed
dezren39 commentedon Oct 28, 2026
🤖 Agent note · picked up
dezren39 commentedon Oct 28, 2026
🤖 Agent note · done
e561ab58ff76ea8e84f2b9a1f108770ebe44a734Premise check (fresh reads at HEAD): no native TUI client exists —
ratatuiappears only inpkgs/id/TODO.md, planning/roadmap docs, and the unrelatedpkgs/screenroguelike-tutorial README; nothing inpkgs/idimplements a terminal-UI shell. The contract it would build on is real and finished: #783 (F13.1) is CLOSED, andpkgs/id/src/shell_contract.rsis in main.Design note (acceptance items 1–2)
Relationship to the Phase 13 shell contract (#783). The TUI is another shell, not a new protocol:
shell_contract.rsopens by naming its audience — "Every shell (the SSH terminal,id world join, the browser, a native client) speaks the same frame protocol to a world host" — with the contract as data (contract/shell-contract.v1.json, wire version 1,/id-world/1ALPN), frames classed as journaled event / ephemeral context / query / control / admin / delegation, and transports (iroh, WebSocket, SSH exec) that "only move these frames." What the TUI implements: the client half of that contract, proven by the same conformance check the module provides (a frame/field/phase the contract doesn't name is a violation; unknown server frames are ignored at runtime). What it adds is purely local: a renderer, a blob cache, and a local mode — none of which change the wire.Intent/byte protocol + blob caching. The server already sends structured intent, not a raw terminal stream: world programs emit validated presentations (
world_presentation.rs,kind: screendocuments), and the shell renders them with its own trusted code. The TUI renderer maps presentation cells/spans to ratatui buffers, and image intents ("draw this blob at x,y,w,h") to the kitty graphics protocol. For blobs, the no-second-round-trip rule: blob references ride in the presentation frame with their content hashes; the client keeps a hash-keyed local cache — a hit renders immediately, a miss renders a placeholder and fetches the blob over the existing blob path in parallel, repainting on arrival, rather than blocking the frame pipeline on a request/response round trip. Prefetch follows the room/object the selector is hovering, where the next navigation is predictable.Three-panel layout. Left: room/object selector with search and pinned favourites. Centre: the interactive room/document surface (the presentation renderer) or meta pages. Right: the room/topic chatroom. Panels map onto the contract's frame classes — selector/search are queries, the centre surface is the presentation stream, chat is journaled events — so no panel needs a side channel.
Local vs iroh-remote modes. Local mode: no server — the client hosts the world in-process (or against a loopback host) with native filesystem access. Remote mode: the identical frame protocol over iroh (explicitly not SSH — the SSH shell already covers that transport), so mode is a transport choice under the contract, not a second client.
Decision state (acceptance item 3): neither adopted nor dropped in this triage. Per the 2026-10-26 reprioritization recorded on this issue, Phase 13 / long-term ideas sit in the
priority/lowbucket, which is where this issue already is (effort/l). No implementation issue is filed now; the first step, when the bucket is picked up, is a conformance-checked ratatui shell skeleton (local mode, centre panel only) filed as its own issue referencing this note. The issue stays open as the tracked idea, with its queue labels cleared so it stops cycling through triage; this task completes astriaged.dezren39 commentedon Nov 3, 2026
agent-note:v1
state: triaged (coverage pass)
Coverage pass 2026-11-03: reviewed in the fleet-wide per-issue pass (drift / overlap / already-handled / stale / blockers / ordering). Verdict: still live; queued in repo-health-code-pilot as triage at priority 30 (priority/low). If this is already handled at current main, the triage closes it with evidence; if it needs splitting, the triage files the split.
Found via: coverage pass 2026-11-03
dezren39 commentedon Nov 3, 2026
🤖 Agent note · done (triaged — design note already complete)
02cafe76repo-health-code-pilot(coverage pass 2026-11-03)Verdict: still live as a tracked idea; triage is complete, no new work to file
Re-verified at main
9d1464c05(2026-11-03):ratatuistill appears only inpkgs/id/TODO.md:59insidepkgs/id; there is no TUI crate anywhere underpkgs/, and no open PR implements one (the only search hit, feat(mcpx): cli.Run in-process entrypoint, slim main (#1980 stage 1) #2714, is an mcpx CLI entrypoint).pkgs/id/src/shell_contract.rspluspkgs/id/contract/shell-contract.v1.json(wire version 1,/id-world/1) are in main and already name "a native client" among the shells that speak the frame protocol.Item 3 (adopt / drop)
Neither, deliberately: this is a
priority/lowPhase 13 / long-term idea under the 2026-10-26 reprioritization (now+high = path to Phase 12,next= Phase 12, low = Phase 13 + long-term). It is not blocked and not wrong, so closing it would discard a tracked idea rather than resolve one. The first implementation step is already pre-scoped in the note: a conformance-checked ratatui shell skeleton (local mode, centre panel only) as its own issue, referencing this note — to be filed when the low-priority bucket is picked up.Why this issue came back to triage, and what I changed
The 2026-10-28 triage cleared the queue labels, but this coverage pass re-created a triage task purely because no live queue task existed — the design note was not consulted. To make the state durable I am setting
status/triagedon the issue and removingtask/triage,status/needs-triageandqueue/queued. Re-triage only if the low-priority bucket is picked up, the shell contract version changes, or a TUI implementation appears. Sibling idea #1072 (native GUI client) is in the same state and needs the same treatment on its next pass.