LLM–Human Text Protocol
ANSI and Unicode text conversion through deterministic Canvas cells.
HEAD a63778e| Read this page when | You change the text boundary between an Agent, a human, and Canvas cells. |
|---|---|
| First answer | One rendering-neutral cell protocol carries Unicode and ANSI input through Canvas and back to ANSI output. |
| Boundary | Syntax, layout, diagnostics, and compatibility belong to the v1 specification; authoring guidance belongs to the CharDesk skill. |
| Follow-up | Read the v1 specification, then the package tests. |
CharDesk 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. | 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 source and may combine structured content, spatial composition, and visible style controls before materialization. | Materials and CLI inspection |
| Agent execution | Native read and apply_patch are the write path. chardesk inspect consumes this protocol; the read-only HTTP Reader transports a native single-file document without storing another revision. | command.ts, preview-server.ts, and their nearest tests |
| Exchange forms | Canonical .chardesk uses a versioned envelope: v1 carries text; opt-in v2 adds Freeform page metadata. Bodies use visible ESC-less controls; .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.