Formats and Packages
Authorities for portable contracts consumed outside the editor runtime.
HEAD a63778e| Read this page when | A change affects a file format, protocol, package API, renderer, font asset, import, or export boundary. |
|---|---|
| First answer | Which portable contract owns the data or API shape? |
| Boundary | This page routes portable contracts; package READMEs, specifications, and format authorities remain authoritative. |
| Verification | Use the compatibility evidence in the table before changing a format or package boundary. |
| Follow-up | Select the contract below, then open its README or specification before changing implementation. |
| Contract | Authority | Compatibility evidence |
|---|---|---|
| Text source compilation | @chardesk/chargraph owns explicit chargraph, chardesk, ansi, and plain source kinds and Protocol row output | compiler.test.ts and External text rendering |
| Unicode, ANSI and ESC-less ANSI cells | Package API and v1 specification | Conformance fixtures executed by protocol.test.ts; Canvas round trip |
Canonical .chardesk envelope | @chardesk/document owns document/v1, mode, title, and body boundaries; mode codecs remain with their domains | Envelope tests and App round trips |
| Render model and Canvas 2D backend | @chardesk/rendering owns geometry, font routing, Canvas metrics, and cell painting consumed by the editor and Viewer | index.test.ts and canvas.test.ts verify model and pixel contracts |
| Retired package migration | Private compiler | Retirement contract |
| Local document preview | CLI preview server | Preview tests |
| Optional renderer font profile | Package API, profile, and asset manifest | index.test.ts and vendor-fonts.mjs verify mode |
Slide document body and legacy .slides.md | Slides parser and serializer | Parser tests, round trip, and browser exchange |
| Export capabilities and preparation | Registry and service | export-service.test.ts |
| Clipboard and download delivery | Browser adapter | Typed failure evidence and apps/canvas/e2e/app-menu.spec.ts |
.ans retains ESC for terminals. Canonical .chardesk is a UTF-8 text document:
Freeform bodies use visible ESC-less controls and Slide bodies use heading plus
fenced-page text. Retired Structured bodies remain import-only and flatten to
Freeform CellPlane content.
Standalone Slide fences omit size for the compatible 100x27 default, accept
explicit dimensions, or use size=auto to resolve page bounds with four
columns of horizontal and two rows of vertical padding on each side.
Panel Slide packages make auto size the manifest default: omit panels.<id>.size;
fixed pages set <columns>x<rows> explicitly.
parseDocumentSessionSource
is the import discriminator: document/v1 routes by mode, legacy slides/v1
routes to the Slides compatibility parser. Headerless imports use their file
suffix: .md is CharGraph, .txt is literal, .ans is ANSI, and an unknown
or absent suffix remains compiled CharDesk for compatibility.
A Panel package source tree is authoritative; its Canvas session is a lifecycle
shell and its Freeform or Slide surface is derived. Human actions are limited to
navigation, selection, copy, import, export, and playback. Only the source
projection runtime may replace content.
Change vendored fonts and generated Unicode width data through
vendor-fonts.mjs
and generate-character-data.mjs,
not their checked-in output. The root package.json
owns the commands.