@textmode/document 0.0.0-stage → 1.1.0

package/docs/schema-2.0.md

@@ -0,0 +1,236 @@
+# Visual guide to document format 2.0
+
+> Versioned v2 reference. Current v3 documentation is in the
+> [v3 specification](specification-3.0.md) and [visual guide](schema-3.0.md).
+> The current decoder validates these older shapes and migrates them to v3.
+
+These diagrams show the structure of `textmode.document@2.0.0`. For the complete
+rules, see the [v2 specification](specification-2.0.md) and [JSON Schema](../schemas/2.0/schema.json).
+For decoding examples and error handling, see the [consumer guide](consumer-guide.md).
+
+## Document shapes
+
+A v2 document has one of two shapes. Both include the format, version, and
+`canvas` extent; metadata is optional. The `target` field selects the shape.
+
+```mermaid
+flowchart TD
+    Root["Root object"] --> Format["format = textmode.document<br/>required"]
+    Root --> Version["formatVersion = 2.0.0<br/>required"]
+    Root --> Target{"target<br/>required; oneOf"}
+    Root --> Canvas["canvas: pixel extent<br/>required in both shapes"]
+    Root -. "optional" .-> Metadata["metadata"]
+
+    Target -->|selected| Selected["Selected snapshot"]
+    Selected --> SelectedGrid["grid: dimensions + cell metrics"]
+    Selected --> SelectedLayer["layer: id + cells"]
+
+    Target -->|all| All["Layer stack"]
+    All --> Layers["layers: one or more stack layers"]
+```
+
+### Root fields
+
+| Field           | Required      | Meaning                                                                              |
+| --------------- | ------------- | ------------------------------------------------------------------------------------ |
+| `format`        | Yes           | Must be `textmode.document`.                                                         |
+| `formatVersion` | Yes           | Must be `2.0.0`. This file-format version is independent of the npm package version. |
+| `target`        | Yes           | Must be `selected` or `all`; selects the matching shape.                             |
+| `canvas`        | Yes           | Legacy pixel extent. It is not necessarily the final or composite viewport.          |
+| `grid`          | Selected only | Grid metrics shared by the selected snapshot's cells.                                |
+| `layer`         | Selected only | One selected cell snapshot with an informational ID.                                 |
+| `layers`        | All only      | Nonempty ordered stack of layers, bottom first.                                      |
+| `metadata`      | No            | Creation timestamp and producer identity. If present, both members are required.     |
+
+Ordinary objects allow unknown fields. The decoder omits them from canonical
+output, so decoding and reserializing does not preserve them.
+
+## Selected snapshot and layer stack
+
+The selected shape stores one cell snapshot. It has no layer visibility,
+opacity, blend mode, offsets, rotation, or font identity. The `all` shape stores
+one or more independently measured layers and preserves their stack order.
+
+```mermaid
+flowchart LR
+    subgraph Selected["target: selected"]
+        SCanvas["canvas<br/>width, height in pixels"]
+        SGrid["grid<br/>cols, rows<br/>cellWidth, cellHeight"]
+        SLayer["layer<br/>id + cells"]
+        SGrid --> SLayer
+        SCanvas -. "width = cols × cellWidth<br/>height = rows × cellHeight" .-> SGrid
+    end
+
+    subgraph All["target: all"]
+        ACanvas["canvas<br/>first layer's pixel extent"]
+        Stack["layers[]<br/>one or more; bottom to top"]
+        L0["first stack layer"]
+        L1["next layer"]
+        More["zero or more further layers"]
+        ACanvas -. "legacy extent follows first layer grid" .-> L0
+        Stack --> L0 --> L1 --> More
+    end
+```
+
+For a selected document, `canvas.width` and `canvas.height` equal the grid's
+pixel extent. For a stack document, root `canvas` follows the **first layer's**
+grid. It does not describe the combined bounds, placement, or clipping of the
+stack. Every stack layer has its own grid, cell metrics, and cells.
+
+| Object           | Required fields                           | Local constraints                                                                                             |
+| ---------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `canvas`         | `width`, `height`                         | Positive safe integers in pixels.                                                                             |
+| `grid`           | `cols`, `rows`, `cellWidth`, `cellHeight` | Positive safe integers. Pixel products must remain safe integers; the decoder checks the extent relationship. |
+| Selected `layer` | `id`, `cells`                             | `id` is a nonempty string.                                                                                    |
+| Cell collection  | `encoding`, `rows`                        | `encoding` is exactly `object-rows-v1`; `rows` is an array.                                                   |
+
+In a selected document, `grid` is at the root. In a stack, each layer has a
+grid and the root `canvas` is checked against the first layer's grid.
+
+Each stack layer requires all of the following fields:
+
+| Field                | Constraint or meaning                                                                                                    |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `id`                 | Nonempty, informational source ID. It is not a persistent identity and need not be unique.                               |
+| `visible`            | Boolean presentation state. Hidden layer cells remain in the document.                                                   |
+| `opacity`            | Number from `0` to `1`, separate from cell alpha.                                                                        |
+| `blendMode`          | Nonempty mode name. The decoder preserves names it does not recognize; consumers decide what they can render.            |
+| `offsetX`, `offsetY` | Pixel offsets. In the textmode.js compositor, positive x moves right and positive y moves down.                          |
+| `rotationZ`          | Layer rotation in degrees. In textmode.js it is clockwise around the rectangular layer center; the decoder preserves it. |
+| `grid`               | This layer's columns, rows, and cell pixel dimensions.                                                                   |
+| `cells`              | This layer's complete dense cell data.                                                                                   |
+
+The textmode.js exporter writes `normal`, `additive`, `multiply`, `screen`,
+`subtract`, `darken`, `lighten`, `overlay`, `softLight`, `hardLight`,
+`colorDodge`, `colorBurn`, `difference`, and `exclusion`. These are producer
+values, not an exhaustive enum in the schema.
+
+## Grid and dense cell storage
+
+Both shapes store cells in `object-rows-v1` encoding. The row and column arrays
+are dense and row-major. Every grid position has a cell, including cells with
+transparent foreground and background colors.
+
+```mermaid
+flowchart TD
+    Grid["grid<br/>cols × rows"] --> Enc["cells.encoding<br/>object-rows-v1"]
+    Enc --> Rows["cells.rows[]<br/>row-major"]
+    Rows --> Row["rows[y]"]
+    Row --> Cell["rows[y][x]"]
+    Cell --> Coord["cell.x = x<br/>cell.y = y"]
+    Grid -. "rows.length = rows" .-> Rows
+    Grid -. "each row length = cols" .-> Row
+    Grid -. "all coordinates are present" .-> Cell
+```
+
+Coordinates are zero-based. Each cell's `x` and `y` must match its position in
+`rows[y][x]`. Consumers must reject a mismatch instead of reordering or repairing
+cells.
+
+| Cell field                 | Required | Schema-level shape                                                                                                                                           |
+| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `x`, `y`                   | Yes      | Nonnegative safe-range integers; decoder requires them to match array positions.                                                                             |
+| `character`                | Yes      | String constrained by `minLength: 1` and `maxLength: 64`; decoder rejects unpaired surrogates and counts Unicode scalar values against its configured limit. |
+| `foreground`, `background` | Yes      | Each is a six/eight digit hex color or an RGBA object.                                                                                                       |
+| `transform`                | Yes      | Object with `invert`, `flipX`, `flipY`, and `rotation`.                                                                                                      |
+
+An RGBA color object requires integer `r`, `g`, `b`, and `a` channels. Each
+channel is between `0` and `255`. The schema permits additional properties in
+these objects, as it does for the other ordinary objects in the format.
+
+The decoder checks row sizes, coordinates, and canvas dimensions against the
+grid. The schema alone does not check these relationships.
+
+## Cell, color, and transform structure
+
+Each cell requires coordinates, a glyph string, foreground and background
+colors, and all four transform values.
+
+```mermaid
+flowchart TD
+    Cell["Cell"] --> X["x: zero-based column"]
+    Cell --> Y["y: zero-based row"]
+    Cell --> Character["character: nonempty Unicode string"]
+    Cell --> Foreground["foreground"]
+    Cell --> Background["background"]
+    Cell --> Transform["transform"]
+
+    Foreground --> Color["Color"]
+    Background --> Color
+    Color --> Hex6["#RRGGBB<br/>alpha defaults to 255"]
+    Color --> Hex8["#RRGGBBAA"]
+    Color --> RGBA["RGBA object"]
+    RGBA --> Channels["r, g, b, a<br/>integers 0–255"]
+
+    Transform --> Invert["invert: boolean"]
+    Transform --> FlipX["flipX: boolean"]
+    Transform --> FlipY["flipY: boolean"]
+    Transform --> Rotation["rotation: finite degrees<br/>canonical range [0, 360)"]
+```
+
+The decoder converts colors to RGBA objects and normalizes cell rotation to
+`[0, 360)`. It preserves Unicode strings without normalization. A glyph can
+contain multiple scalar values, such as a combining sequence or joined emoji;
+unpaired surrogates are invalid. The decoder also applies a scalar-count limit.
+
+Cell alpha and layer opacity are separate. A cell is visually empty only when
+both foreground and background alpha are zero. A space glyph with a visible
+background remains meaningful. Inversion cannot generally be implemented by
+swapping colors when alpha is present.
+
+## Metadata
+
+Metadata is optional at the root. If the `metadata` object exists, it requires
+both `createdAt` and `generator`. The generator requires a nonempty `name` and
+`version`.
+
+```mermaid
+flowchart LR
+    Root["Document"] -. "optional" .-> Metadata["metadata"]
+    Metadata --> CreatedAt["createdAt<br/>date-time string"]
+    Metadata --> Generator["generator"]
+    Generator --> Name["name: nonempty string"]
+    Generator --> Version["version: nonempty string"]
+```
+
+`createdAt` uses the format's timestamp profile: uppercase `T`, seconds,
+timezone, optional fractional seconds, and no leap seconds. Validators must
+enable date-time format assertions to validate the `date-time` format keyword.
+Metadata is informational. Consumers must not use it to choose executable
+behavior, fetch resources, or bypass validation.
+
+## Validation and decoding boundaries
+
+The schema describes structure and local constraints. The specification defines
+field meaning and relationships. The decoder checks documents, applies limits,
+and migrates supported older formats to canonical v3 output.
+
+```mermaid
+flowchart LR
+    Input["v2 or supported legacy JSON"] --> Decoder["Decoder<br/>validation, limits,<br/>migration, normalization"]
+    Decoder --> Canonical["Canonical v3 document<br/>with migration warning"]
+    Decoder --> Error["Failure result"]
+    Schema["JSON Schema<br/>structure and local constraints"] -. "v2 structure" .-> Input
+    Spec["Format specification<br/>meaning and relationships"] -. "v2 rules" .-> Decoder
+```
+
+A schema-valid document can still fail decoding. For example, the schema does
+not check row sizes against the grid or enforce a caller's total cell budget.
+See the [consumer guide](consumer-guide.md#use-json-schema) for validator setup
+and the [v2 specification](specification-2.0.md#safety-limits) for decoder limits.
+
+## Scope and compatibility
+
+Version 2 stores editable cell snapshots and layer stacks. It does not store
+font identity or font assets, editor project state, authored animation,
+post-processing, or final rendered pixels. Importers apply their own font,
+feature-support, and placement policies.
+
+The current decoder migrates v2 documents and supported `textmode.layer` files
+to canonical v3 layers. It reports a migration warning and can be configured to
+reject legacy `textmode.layer` input. The v2 JSON Schema describes the v2 wire
+shapes; it is not a schema for the legacy formats or current v3 output.
+
+For the exact normative rules, including unknown properties, timestamp
+requirements, blend-mode behavior, and safety guidance, see the
+[Format 2.0 specification](specification-2.0.md).

package/docs/schema-3.0.md

@@ -0,0 +1,117 @@
+# Visual guide to document format 3.0
+
+These diagrams show the structure of `textmode.document@3.0.0`. For the complete
+rules, see the [specification](specification-3.0.md) and [JSON Schema](../schemas/3.0/schema.json).
+The [consumer guide](consumer-guide.md) includes complete example documents.
+
+## One shape for any layer count
+
+```mermaid
+flowchart TD
+    Document["Document object"] --> Format["format = textmode.document"]
+    Document --> Version["formatVersion = 3.0.0"]
+    Document --> Layers["layers[]: at least one; bottom to top"]
+    Document -. optional .-> Metadata["metadata: createdAt + generator"]
+    Layers --> Layer["Same complete layer structure for every entry"]
+    Layer --> Identity["id: informational string"]
+    Layer --> Presentation["visible, opacity, blendMode<br/>offsetX, offsetY, rotationZ"]
+    Layer --> Grid["grid: cols, rows, cellWidth, cellHeight"]
+    Layer --> Cells["cells: encoding + dense rows"]
+```
+
+All shown fields are required except metadata. A document with one layer has one
+array entry. Root `target`, `layer`, `grid`, and `canvas` fields are rejected.
+Other unknown fields are accepted and omitted from canonical output. IDs need not
+be unique. The format does not define a font, viewport, or animation.
+
+## Grids and storage
+
+```mermaid
+flowchart TD
+    Grid["Layer grid: positive safe integers"] --> Extent["Derived pixel extent<br/>cols × cellWidth; rows × cellHeight"]
+    Grid --> Encoding["cells.encoding = object-rows-v1"]
+    Encoding --> Rows["cells.rows: grid.rows rows"]
+    Rows --> Row["rows[y]: grid.cols cells"]
+    Row --> Cell["rows[y][x]"]
+    Cell --> Coordinates["cell.x = x; cell.y = y<br/>zero-based, redundant checks"]
+    Grid -. "decoder checks safe products and array agreement" .-> Coordinates
+```
+
+Every grid position is stored, including transparent cells. Layers can have
+different dimensions and cell sizes. The decoder checks row sizes and coordinates
+against each layer's grid.
+
+## Layer presentation
+
+```mermaid
+flowchart LR
+    Layer["Layer"] --> Visible["visible: boolean"]
+    Layer --> Opacity["opacity: 0 to 1"]
+    Layer --> Blend["blendMode: nonempty name"]
+    Layer --> Offset["offsetX / offsetY: pixels<br/>positive right / down"]
+    Layer --> Rotation["rotationZ: finite degrees<br/>clockwise about center in textmode.js"]
+    Opacity --> Alpha["Multiplies layer appearance<br/>separate from cell alpha"]
+    Blend --> Support["Unknown names preserved<br/>consumer checks support"]
+```
+
+Hidden layers keep their cells. Layer rotation is preserved without canonical
+normalization. Stack order is bottom first. Every presentation field is explicit;
+JSON Schema defaults are not used to supply missing values.
+
+## Complete cell payload
+
+```mermaid
+flowchart TD
+    Cell["Cell: all fields required"] --> XY["x / y: nonnegative safe integers"]
+    Cell --> Glyph["character: nonempty Unicode glyph string"]
+    Cell --> FG["foreground"]
+    Cell --> BG["background"]
+    FG --> Color{"Color representation"}
+    BG --> Color
+    Color --> RGB["#RRGGBB: alpha 255"]
+    Color --> RGBAHex["#RRGGBBAA"]
+    Color --> Channels["Object: integer r, g, b, a<br/>each 0 to 255"]
+    Cell --> Transform["transform"]
+    Transform --> Booleans["invert / flipX / flipY: booleans"]
+    Transform --> Rotation["rotation: finite degrees<br/>canonical [0, 360)"]
+```
+
+Canonical colors use RGBA objects. Unicode is preserved without normalization;
+unpaired surrogates fail. The schema's minLength/maxLength are 1/64; decoder
+scalar-count budgets are configurable. A visible background on a space matters.
+Only cells whose foreground and background alpha are both zero are visually
+empty. Inversion cannot generally be replaced by swapping colors.
+
+## Metadata
+
+```mermaid
+flowchart LR
+    Document["Document"] -. optional .-> Metadata["metadata"]
+    Metadata --> Date["createdAt: real date-time<br/>uppercase T + timezone + seconds"]
+    Metadata --> Generator["generator"]
+    Generator --> Name["name: nonempty producer string"]
+    Generator --> Version["version: nonempty producer string"]
+```
+
+All children are required when metadata is present. Fractional seconds are
+optional; leap seconds are unsupported. Enable date-time format assertions in
+validators. Metadata is informational and never authorizes code or resource loads.
+
+## Readers and canonical output
+
+```mermaid
+flowchart TD
+    V3["v3: unified layers"] --> Decoder["Decode known fields<br/>enforce budgets + cross-field rules"]
+    V2["v2: selected or all<br/>original validation including canvas"] --> Migration["Convert structure<br/>neutral presentation for selected snapshots"]
+    V1["Legacy textmode.layer v1<br/>when acceptLegacy is true"] --> Migration
+    Migration --> Decoder
+    Decoder --> Success["Success: canonical v3 layers<br/>RGBA colors; normalized cell rotation"]
+    Decoder --> Failure["Failure: code, message, optional path"]
+    Success --> Warnings["Migration warnings for older input"]
+```
+
+The decoder checks documents directly; a separate schema validation pass is
+optional. It omits unknown fields from canonical output. Applications must check
+input size before parsing and apply their own font, feature, and placement rules.
+See the [specification](specification-3.0.md#validation-budgets-and-compatibility)
+for default limits and the [v2 visual guide](schema-2.0.md) for older shapes.

package/docs/specification-2.0.md

@@ -0,0 +1,294 @@
+# Textmode document format 2.0
+
+> Versioned v2 reference. Current v3 documentation is in the
+> [v3 specification](specification-3.0.md) and [visual guide](schema-3.0.md).
+> The current decoder validates these older shapes and migrates them to v3.
+
+## Status
+
+This specification defines `textmode.document@2.0.0`. Its [JSON Schema](../schemas/2.0/schema.json)
+is also available as `@textmode/document/schema/2.0`. The schema's `$id` is an
+identifier and does not guarantee a hosted download. Package and document versions
+are independent.
+
+Version 2 stores editable cell data. It does not store final rendered pixels,
+post-processing, an editor project, or authored animation. For complete examples
+of the current format, see the [consumer guide](consumer-guide.md).
+
+## Encoding
+
+A textmode document is a UTF-8 JSON object. Producers should follow the I-JSON
+profile in RFC 7493:
+
+- object member names are unique;
+- integers remain within the interoperable safe range;
+- non-finite numbers are not emitted;
+- timestamps use an uppercase, timezone-qualified RFC 3339 representation.
+
+The JavaScript parser uses `JSON.parse`, which keeps the last value for a
+repeated key. It does not report duplicate keys.
+
+The media type is `application/json`. `.textmode.json` is a suggested filename
+suffix; existing exporter downloads use `.json` by default. Extensions and
+media types are discovery hints; consumers must route a decoded object using
+its `format` member.
+
+## Root discriminator
+
+Every v2 document contains:
+
+```json
+{
+	"format": "textmode.document",
+	"formatVersion": "2.0.0",
+	"target": "selected"
+}
+```
+
+`target` is an on-disk shape discriminator:
+
+- `selected` contains one cell snapshot in `layer`;
+- `all` contains a layer stack in `layers`.
+
+It is not an instruction to an exporter and must not be extended with temporal
+values such as `animation`. Authored animation requires a distinct document or
+container format.
+
+## Version compatibility
+
+The version uses a SemVer-shaped identifier. Version 2 does not define reader
+negotiation or a formal extension mechanism. Consumers must accept only explicitly
+tested versions and migrations; an unknown `2.x` version is not automatically
+compatible.
+
+For a supported version, consumers ignore unknown ordinary fields. The decoder
+omits them from canonical output, so reserialization does not preserve them.
+Consumers reject unknown `format`, `target`, and `encoding` values because those
+values change how to read the document.
+
+Version 2 does not define `extensionsUsed`, `extensionsRequired`, extension
+namespacing, or an extension registry. A later revision must define those
+rules before claiming extension compatibility.
+
+## Selected cell snapshot
+
+The `selected` shape contains:
+
+- legacy grid pixel extent in `canvas`;
+- logical grid dimensions and cell metrics in `grid`;
+- an informational source ID and complete cell rows in `layer`.
+
+This shape is a cell snapshot, not a lossless layer document. It does not carry
+visibility, opacity, blend mode, offsets, layer rotation, or font identity.
+
+## Layer stack
+
+The `all` shape contains one or more layers. Each layer includes:
+
+- informational ID;
+- visibility and opacity;
+- blend mode name;
+- x/y offsets and z rotation;
+- logical grid and cell metrics;
+- complete cell rows.
+
+The order of `layers` is bottom-to-top stack order. The exporter emits the base
+layer first, followed by user layers. There is no fixed format-level layer count;
+the decoder enforces the configurable budget.
+
+`id` is informational source identity, scoped to the source snapshot. It is not a
+persistent identity across files. The v2 decoder does not require IDs to be unique;
+consumers must not infer reference semantics from them.
+
+Offsets are compositing offsets in pixels. In the textmode.js compositor, positive
+x moves right and positive y moves down. `rotationZ` is clockwise degrees about
+the layer's rectangular center; the center remains the rotation origin when an
+offset is applied. The decoder preserves layer rotation without normalization.
+Opacity is from 0 through 1 and multiplies the layer presentation independently
+of cell alpha. Invisible layers retain their cell data.
+
+The textmode.js exporter writes `normal`, `additive`, `multiply`, `screen`,
+`subtract`, `darken`, `lighten`, `overlay`, `softLight`, `hardLight`, `colorDodge`,
+`colorBurn`, `difference`, or `exclusion`. The wire schema and decoder accept any
+nonempty bounded blend-mode name. Consumers must decide whether they support it
+before presentation; unknown names are not silently converted to `normal`.
+
+## Canvas field
+
+The v2 field named `canvas` is the grid pixel extent, not necessarily the HTML
+canvas or final output surface. Its values obey:
+
+```text
+canvas.width  = grid.cols × grid.cellWidth
+canvas.height = grid.rows × grid.cellHeight
+```
+
+For an `all` document, the root extent is derived from the first layer's grid.
+Consumers must not infer composite placement or clipping from this field.
+
+The meaning of this field must not change within version 2.
+
+## Cell encoding
+
+Version 2 defines one encoding:
+
+```json
+{
+	"encoding": "object-rows-v1",
+	"rows": []
+}
+```
+
+The encoding is dense and row-major:
+
+- `rows.length` equals `grid.rows`;
+- every row length equals `grid.cols`;
+- a cell's `x` equals its array index within the row;
+- a cell's `y` equals the row index;
+- every grid coordinate is present, including transparent cells.
+
+Consumers reject coordinate disagreement rather than silently repairing or
+reordering cells.
+
+## Glyph identity
+
+`character` contains a non-empty, bounded, well-formed Unicode glyph string.
+Vector fonts commonly use one Unicode scalar, while tileset maps may use an
+extended grapheme cluster containing combining marks, variation selectors, or
+zero-width joiners. Unpaired surrogates are invalid. The default codec budget
+is 64 Unicode scalar values per glyph string.
+
+No Unicode normalization is implied. Consumers preserve the string exactly and
+apply product-specific representability rules after protocol decoding.
+
+## Colors
+
+Foreground and background colors use either:
+
+- `#RRGGBB`, whose alpha is implicitly 255;
+- `#RRGGBBAA`;
+- `{ "r": 0, "g": 0, "b": 0, "a": 255 }` with integer channels from
+  0 through 255.
+
+The canonical decoder normalizes colors to RGBA channel objects.
+
+A cell is visually empty only when both foreground and background alpha are
+zero. A space with a visible background remains meaningful cell data.
+
+## Transforms
+
+Every cell contains:
+
+- `invert`: boolean;
+- `flipX`: boolean;
+- `flipY`: boolean;
+- `rotation`: finite degrees.
+
+The canonical decoder normalizes rotation into `[0, 360)`. It therefore
+normalizes both `360` and `-360` to `0` and `-90` to `270`.
+
+Consumers must reject unsupported meaningful transforms instead of
+approximating them. In particular, swapping foreground and background is not a
+general replacement for inversion when alpha is present.
+
+## Metadata
+
+Metadata is optional and informational:
+
+```json
+{
+	"createdAt": "2026-08-28T12:00:00.000Z",
+	"generator": {
+		"name": "textmode.export.js",
+		"version": "1.8.1"
+	}
+}
+```
+
+`generator.name` identifies the producer and is not restricted to
+`textmode.export.js`. If metadata is present, `createdAt` must be a real
+calendar date and time in the uppercase, timezone-qualified RFC 3339 profile:
+seconds are required, fractional seconds are optional, and leap seconds are
+not supported in version 2. The decoder preserves valid timestamps as written.
+
+Consumers must not use metadata to select executable behavior, fetch resources,
+or bypass document validation.
+
+## Safety limits
+
+The shared codec enforces structural safety limits and accepts caller-supplied
+budgets. Every override must be a positive safe integer; invalid configuration
+throws `TypeError`. Invalid document data instead returns a typed failure.
+
+| Limit                     | Default    | Counting rule                                              |
+| ------------------------- | ---------- | ---------------------------------------------------------- |
+| `maxCells`                | 16,777,216 | Cumulative cells across the document.                      |
+| `maxLayers`               | 4,096      | Layers in an `all` document; selected has one snapshot.    |
+| `maxLayerIdLength`        | 1,024      | UTF-16 code units per identifier.                          |
+| `maxCharacterLength`      | 64         | Unicode scalar values per glyph string.                    |
+| `maxMetadataStringLength` | 4,096      | UTF-16 code units per metadata string and blend-mode name. |
+
+These budgets apply after JSON parsing and do not limit file bytes or parser
+memory. The schema's glyph `maxLength` remains 64 even when an app raises the
+decoder limit. Applications can also enforce their own feature and size limits.
+
+Consumers should:
+
+- check file bytes before reading;
+- cap total layers and total decoded cells;
+- use checked multiplication for grid dimensions;
+- bound identifiers and metadata strings;
+- parse large files away from latency-sensitive UI work;
+- abort work when the owning import session is cancelled.
+
+Documents never authorize URL fetching, font installation, or code execution.
+
+## Legacy migration
+
+The compatibility decoder recognizes:
+
+- `textmode.layer@1.0.0` as a selected cell snapshot;
+- `textmode.layer@1.1.0` as a layer stack.
+
+The current decoder migrates both to canonical v3 output and returns
+`LEGACY_DOCUMENT_MIGRATED`. Set `acceptLegacy: false` to reject these legacy files;
+this does not disable v2 document support.
+
+## JSON Schema and runtime decoder
+
+The specification defines meaning and cross-field rules. The JSON Schema describes
+structure for general tooling. The decoder also checks or applies:
+
+- cross-field row and grid invariants;
+- grid pixel extent equality;
+- total resource budgets;
+- well-formed and bounded glyph-string validation;
+- rotation and color normalization;
+- legacy migration;
+- stable error codes and JSON paths.
+
+## Required fields
+
+| Object          | Required fields                                                                             | Optional fields |
+| --------------- | ------------------------------------------------------------------------------------------- | --------------- |
+| Selected root   | `format`, `formatVersion`, `target`, `canvas`, `grid`, `layer`                              | `metadata`      |
+| All root        | `format`, `formatVersion`, `target`, `canvas`, `layers`                                     | `metadata`      |
+| Canvas          | `width`, `height`                                                                           | None            |
+| Grid            | `cols`, `rows`, `cellWidth`, `cellHeight`                                                   | None            |
+| Selected layer  | `id`, `cells`                                                                               | None            |
+| Stack layer     | `id`, `visible`, `opacity`, `blendMode`, `offsetX`, `offsetY`, `rotationZ`, `grid`, `cells` | None            |
+| Cell collection | `encoding`, `rows`                                                                          | None            |
+| Cell            | `x`, `y`, `character`, `foreground`, `background`, `transform`                              | None            |
+| Transform       | `invert`, `flipX`, `flipY`, `rotation`                                                      | None            |
+| Metadata        | `createdAt`, `generator`                                                                    | None            |
+| Generator       | `name`, `version`                                                                           | None            |
+
+Unknown ordinary members are allowed in all these objects but omitted by the
+canonical decoder. All schema references are local. Timestamp validation needs
+`date-time` format assertions enabled in the selected schema validator. The
+schema alone does not enforce every decoder rule or configurable budget.
+
+Version 2 has no font identity or embedded font assets. Glyph strings and cell
+metrics cannot identify an exact font. It also has no editor history, project
+preferences, authored frame timeline, or post-processing representation. An
+importer must apply its own font and supported-feature policy.