LLM–Human Text Protocol
ANSI and Unicode text conversion through deterministic Canvas cells.
HEAD a63778eCharDesk uses one rendering-neutral cell protocol as the text boundary between LLMs, humans, and Canvas:
Unicode + ANSI/ESC-less ANSI -> protocol cells -> Canvas grid -> ANSI output
The v1 specification owns syntax, layout, diagnostics, and compatibility. The agent authoring reference owns the concise form an LLM should emit.
| Boundary | Project invariant | Authority and evidence |
|---|---|---|
| Recognition | auto consumes standard ANSI and only supported ESC-less controls, so ordinary bracket text remains visible. plain disables controls; ansi consumes numeric ESC-less SGR and reports unknown codes. | parser.ts and conformance fixtures |
| Cell layout | Newlines, tabs, preserved spaces, grapheme boundaries, and Unicode 17 cell width determine stable (x, y, width) records. Wide graphemes advance two columns while retaining one editable value. | graphemes.ts and protocol.test.ts |
| Style state | SGR persists until changed; reset restores caller defaults. Inverse remains an attribute. OSC 8 produces an untrusted href that renderers must allowlist. | Text Protocol v1 |
| Compiler boundary | CharGraph selects an explicit source kind and produces protocol-laid-out rows before host mutation. The protocol does not recognize Markdown or block layout. | External text rendering and compiler.test.ts |
| ANSI serialization | Grid traversal skips the second column of wide graphemes, emits the shorter reset-or-diff SGR transition, and preserves trailing spaces only when their background, link, or attributes are visible. | text.ts and clipboardActions.test.ts |
| LLM styling | The Agent edits canonical .chardesk or package-local .panel source and may combine structured content, spatial composition, and visible style controls before materialization. | Authoring reference and check.ts |
| Agent execution | Native read and apply_patch are the write path. chardesk inspect delegates Panel acceptance to this protocol; the read-only HTTP Reader transports either raw single-file source or a flattened package projection without storing another revision. | command.ts, server.ts, and their nearest tests |
| Exchange forms | Canonical .chardesk uses a document/v1 envelope; its Freeform and Slide bodies use visible ESC-less controls, while .ans retains ESC for terminals. | @chardesk/document, text.ts, and format boundaries |
Compatibility is semantic, not byte-for-byte: parsing serialized output must preserve visible graphemes, cell coordinates, styles, links, and significant spaces. Changing those results requires a new protocol version.
Canvas/Yjs ownership, history, and persistence remain owned by State and data flows.