Documentation

This directory is the authoritative index for project documentation. The repository README is a short introduction; design reasoning and research live here.

For an introduction and grouped reading entry points, start with the documentation home.

Current documents

Document	Kind	Status
Building the documentation website	Documentation tooling	Local preview and GitHub Pages
RFC 0001: Mutable Terminal History and Reading Anchors	Requirements RFC	Draft
Operation semantics	Protocol draft	Draft
Capability negotiation	Protocol draft	Draft
Wire format requirements	Protocol draft	Draft
Logical wire message model	Protocol draft	Draft
Concrete message schemas	Protocol draft	Draft
Error codes	Protocol draft	Draft
JSON serialization	Protocol draft	Draft
OSC carrier and framing	Protocol draft	Draft
Content representation	Protocol draft	Draft
Plain text content	Protocol draft	Draft
Protocol Context semantics	Protocol draft	Draft
Terminal-native behavior	Protocol draft	Draft
First prototype design notes	Design note	Working note
Next-stage validation plan	Engineering assessment and priorities	Working plan; completed checkpoints and remaining trial work
Pi rendering architecture	Upstream architecture research and integration assessment	Read-only source trace; trial evidence linked separately
Pi session integration	Application integration experiment	Local fixtures and finite OpenAI subscription trial through ConPTY/xterm; completion, search, cancellation, and recorded transport failure
Pi reading UX comparison	Paired application/renderer experiment	Three fixed scenarios; regular Pi vs experimental protocol frontend, captured before PTY
Pi entered-prompt multi-round trial	Interactive application experiment	Finite supporting-host trial: local native/lifecycle checks and a separate four-prompt subscription checkpoint
Pi coding trial	Coding workflow experiment	Generated project: read, reproduce, edit, test, and follow up through the supporting terminal
Block model prototype	Executable prototype	Experimental
TypeScript TUI SDK	Application-facing API	Experimental; local JavaScript build, unpublished
Streaming text example	SDK application example	Experimental; built JavaScript and application-owned fallback
Terminal host example	Terminal integration example	Experimental; depends on prototype xterm adapter
Multi-round application example	Interactive SDK application example	Experimental; three simulated rounds through bundled ConPTY
Ingress pressure experiment	Integration measurement	Experimental; in-process backlog under a controlled render stall
PTY pressure experiment	Transport integration measurement	Experimental; browser byte credits and bundled-ConPTY pause/resume
Producer-side ConPTY waiting	Transport isolation measurement	Experimental; normal versus paused reads with independent producer timing
Browser hold and producer waiting	Transport integration measurement	Experimental; larger browser workload with overlapping producer write delay
Stalled browser consumption	Transport failure experiment	Experimental; local consumption timeout and child shutdown
Trial resource budgets	Implementation policy	Experimental; retained-state and pending-input accounting
Trial content samples	Integration evidence	Experimental; fixed text corpus, resize, and safe rejection boundaries
Terminal protocol module	Terminal-facing execution	Experimental; local JavaScript build, unpublished
Terminal protocol endpoint	Experiment record	Implementation and tests moved to terminal/
PTY transport probe	Transport integration probe	Experimental; tested system/bundled ConPTY outcomes recorded
Real PTY demonstration	Process-to-browser integration prototype	Experimental; fixed Windows bundled-ConPTY scenario
xterm protocol endpoint	Integration prototype	Experimental
xterm browser protocol endpoint	Browser integration prototype	Experimental
xterm browser selection and copy	Browser integration prototype	Experimental
xterm browser search	Browser integration prototype	Experimental
xterm browser content metadata	Browser integration prototype	Experimental
xterm browser active input state	Browser integration prototype	Experimental
Protocol session prototype	Experiment record	Implementation and tests moved to terminal/
Shared TypeScript protocol code	Shared implementation	Experimental; included in SDK build, unpublished
xterm-headless OSC spike	Feasibility spike	Experimental
Prior art and project evidence	Research note	Living document
RFC process	Project policy	Active

RFC 0001 is the current foundation of the project. It defines the problem, project goals, initial responsibility boundaries, and the minimal Block and Operation model. Detailed agreed semantics are consolidated under docs/protocol/ while they remain drafts.

Repository layout

The three reusable TypeScript modules are private pnpm workspace packages: @tui-protocol/protocol, @tui-protocol/sdk, and @tui-protocol/terminal. Run pnpm install at the root before using source commands. Cross-module imports use those public entries; local imports stay relative. Source entries resolve to TypeScript, while the SDK and terminal build commands produce self-contained JavaScript distributions. These names do not imply publication.

The current top-level layout is:

docs/
  index.md        Documentation home and grouped reading entry points
  README.md       Documentation index
  design/         Working design notes for experiments
  prior-art.md    Verified related work and project evidence
  protocol/       Draft consolidated protocol semantics
  rfcs/           Numbered design proposals and decisions

protocol/         Shared Message validation, serialization, and framing
sdk/              Application-facing client and local build
terminal/         Terminal Session, Endpoint, and host adapter contract
examples/         Runnable application and terminal-host examples
prototypes/       Executable semantic and implementation experiments
scripts/          Shared build tooling and repository checks
  docs/           Website build commands, checks, and tooling tests

prototypes/ contains semantic models, xterm.js integration experiments, and retained experiment records. Shared codec and terminal execution code now live in protocol/ and terminal/. Module tests live with their modules; composed experiments live under prototypes/integration/. A future spec/ or top-level tests/ directory needs actual normative documents or reusable conformance fixtures; neither exists today.

Document authority

Documents have different roles:

1. An accepted specification under spec/ will define normative protocol behavior.

2. Drafts under docs/protocol/ consolidate currently agreed semantics but remain non-normative.

3. RFCs record why a design was proposed, accepted, rejected, or replaced.

4. Research notes summarize evidence and may evolve as new sources appear.

5. The root README is informative and must point to the deeper documents rather than duplicate them.

Until a specification exists, RFC 0001 is the primary statement of the project’s motivation and goals. Its Draft status means that its contents can still change.