@textmode/document 1.0.0 → 1.1.0

package/docs/consumer-guide.md

@@ -2,10 +2,11 @@
 
 ## Choose a decoder
 
-Use `parseTextmodeDocumentJSON(text, options)` when you already know the file is a
-textmode document. Use `parseJSON(text)` when several formats share a `.json`
-extension, then route by the parsed object's `format` and pass it to
-`decodeTextmodeDocument(value, options)`. A filename or MIME type is only a hint.
+Use `parseTextmodeDocumentJSON(text, options)` when you know the file is a
+textmode document. If your app accepts several JSON formats, use `parseJSON(text)`
+first. Check the parsed object's `format`, then pass textmode documents to
+`decodeTextmodeDocument(value, options)`. A filename or MIME type alone cannot
+identify the format.
 
 ```js
 import { parseJSON, decodeTextmodeDocument } from '@textmode/document';
@@ -29,14 +30,14 @@ if (!parsed.ok) {
 }
 ```
 
-`parseJSON` uses native `JSON.parse`. It does not detect duplicate object keys;
-the last value wins. Avoid duplicate keys when producing files. Syntax success
-alone says nothing about whether a value is a valid textmode document.
+`parseJSON` uses JavaScript's `JSON.parse`. If an object repeats a key, the last
+value wins. Producers should use unique keys. Valid JSON is not necessarily a
+valid textmode document.
 
 ## Handle results and budgets
 
-Malformed input returns `{ ok: false, error }`. Errors contain `code`, `message`,
-and an optional JSON path such as `$.layer.cells.rows[0][0].foreground`.
+Invalid input returns `{ ok: false, error }`. The error includes a `code`,
+`message`, and sometimes a JSON path, such as `$.layer.cells.rows[0][0].foreground`.
 
 | Code                   | Meaning                                                           |
 | ---------------------- | ----------------------------------------------------------------- |
@@ -48,99 +49,111 @@ and an optional JSON path such as `$.layer.cells.rows[0][0].foreground`.
 | `UNSUPPORTED_ENCODING` | The cell encoding is unsupported.                                 |
 | `LIMIT_EXCEEDED`       | A resource budget or safe numeric range is exceeded.              |
 
-Successful results contain `document` and `warnings`. A migrated legacy file
-returns `LEGACY_DOCUMENT_MIGRATED`. `acceptLegacy` defaults to `true`; set it to
-`false` to accept only current documents. App-specific failures, such as a missing
-font or unsupported blend mode, belong to the app after protocol decoding.
+Successful results contain a canonical v3 `document` and a `warnings` array.
+Migrated `textmode.layer` v1 files return `LEGACY_DOCUMENT_MIGRATED`. Set
+`acceptLegacy: false` to reject them; the default is `true`. Supported v2 files
+remain readable and return `DOCUMENT_VERSION_MIGRATED`.
 
-Every configured limit must be a positive safe integer. Invalid configuration
-throws `TypeError`; it is a programming error rather than a document failure.
-Limits and their defaults are listed in the [specification](specification-2.0.md#safety-limits).
+After decoding, your app must check its own requirements, such as available fonts
+and supported blend modes. The decoder normalizes known values and omits unknown
+properties, so decoding and serializing does not preserve extensions. The format
+does not store font identity or post-processing.
 
-Check file bytes before reading. Parsing occurs before decoded-cell budgets can
-apply, so `maxCells` does not cap JSON parsing memory or input bytes. Use lower
-app-specific budgets and check cancellation between file read, decode, and import.
-Large files can be decoded in a worker; the library itself is synchronous.
+Set limits to positive safe integers. Invalid limit configuration throws
+`TypeError`. See the [default limits](specification-3.0.md#validation-budgets-and-compatibility).
 
-Decoding preserves known values subject to normalization. It omits unknown
-properties, so decode-and-serialize is not a lossless round trip for extensions.
-It also cannot add missing font identity or recreate post-processing.
+Check file size before reading: decoder limits apply after JSON parsing and do not
+limit input bytes or parser memory. Choose budgets for your app and check for
+cancellation between reading, decoding, and importing. The library is synchronous;
+you can decode large files in a worker.
 
 ## Use JSON Schema
 
 Node 24 can import the schema with an import attribute:
 
 ```js
-import schema from '@textmode/document/schema/2.0' with { type: 'json' };
+import schema from '@textmode/document/schema/3.0' with { type: 'json' };
 ```
 
-Bundlers may use their own JSON import syntax. A filesystem-based tool can resolve
-the same package subpath and read it locally. All schema references are local.
+Bundlers may use different JSON import syntax. Tools that read files can resolve
+the same package subpath. All references within the schema are local.
 
 For example, with Ajv installed in the consumer:
 
 ```js
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
-import schema from '@textmode/document/schema/2.0' with { type: 'json' };
+import schema from '@textmode/document/schema/3.0' with { type: 'json' };
 
 const ajv = new Ajv2020({ validateFormats: true });
 addFormats(ajv, { mode: 'full' });
 const validate = ajv.compile(schema);
 ```
 
-Enable date-time format assertions to check timestamps. Schema validation checks
-structure and local constraints; decoding also checks row/grid agreement,
-coordinates, pixel extents, Unicode well-formedness, and resource budgets. A
-schema-valid document can fail decoding. Configurable decoder budgets can also
-differ from schema constraints: for example, a glyph limit above 64 does not
-change the published schema's `maxLength: 64`.
+Enable date-time format assertions to check timestamps. The schema checks
+structure and local constraints. The decoder also checks relationships such as
+row sizes and coordinates, plus Unicode and resource limits. A schema-valid file
+can still fail decoding. Changing a decoder limit does not change the published
+schema; for example, the schema's glyph `maxLength` remains 64.
 
-## Complete selected document
+## Complete single-layer document
 
-A selected document contains cell data and grid metrics. It carries no layer
-presentation or font identity.
+A single-layer document uses the same structure as a layer stack. The receiving
+application chooses the font.
 
 ```json
 {
 	"format": "textmode.document",
-	"formatVersion": "2.0.0",
-	"target": "selected",
-	"canvas": { "width": 8, "height": 16 },
-	"grid": { "cols": 1, "rows": 1, "cellWidth": 8, "cellHeight": 16 },
-	"layer": {
-		"id": "base",
-		"cells": {
-			"encoding": "object-rows-v1",
-			"rows": [
-				[
-					{
-						"x": 0,
-						"y": 0,
-						"character": "A",
-						"foreground": "#ffffffff",
-						"background": "#00000000",
-						"transform": { "invert": false, "flipX": false, "flipY": false, "rotation": 0 }
-					}
+	"formatVersion": "3.0.0",
+	"layers": [
+		{
+			"visible": true,
+			"opacity": 1,
+			"blendMode": "normal",
+			"offsetX": 0,
+			"offsetY": 0,
+			"rotationZ": 0,
+			"grid": {
+				"cols": 1,
+				"rows": 1,
+				"cellWidth": 8,
+				"cellHeight": 16
+			},
+			"id": "base",
+			"cells": {
+				"encoding": "object-rows-v1",
+				"rows": [
+					[
+						{
+							"x": 0,
+							"y": 0,
+							"character": "A",
+							"foreground": "#ffffffff",
+							"background": "#00000000",
+							"transform": {
+								"invert": false,
+								"flipX": false,
+								"flipY": false,
+								"rotation": 0
+							}
+						}
+					]
 				]
-			]
+			}
 		}
-	}
+	]
 }
 ```
 
 ## Complete layer stack
 
-An `all` document contains one or more layers in stack order, bottom first.
-Each layer has its own grid and presentation values. The first grid determines
-the legacy root pixel extent; that extent does not specify a composite viewport.
+Layers appear in stack order, with the bottom layer first. Each layer has its own
+grid and presentation values. The document has no root canvas or viewport.
 
 ```json
 {
 	"format": "textmode.document",
-	"formatVersion": "2.0.0",
-	"target": "all",
-	"canvas": { "width": 8, "height": 16 },
+	"formatVersion": "3.0.0",
 	"layers": [
 		{
 			"id": "base",
@@ -150,7 +163,12 @@ the legacy root pixel extent; that extent does not specify a composite viewport.
 			"offsetX": 0,
 			"offsetY": 0,
 			"rotationZ": 0,
-			"grid": { "cols": 1, "rows": 1, "cellWidth": 8, "cellHeight": 16 },
+			"grid": {
+				"cols": 1,
+				"rows": 1,
+				"cellWidth": 8,
+				"cellHeight": 16
+			},
 			"cells": {
 				"encoding": "object-rows-v1",
 				"rows": [
@@ -161,7 +179,12 @@ the legacy root pixel extent; that extent does not specify a composite viewport.
 							"character": "A",
 							"foreground": "#ffffffff",
 							"background": "#000000ff",
-							"transform": { "invert": false, "flipX": false, "flipY": false, "rotation": 0 }
+							"transform": {
+								"invert": false,
+								"flipX": false,
+								"flipY": false,
+								"rotation": 0
+							}
 						}
 					]
 				]
@@ -175,7 +198,12 @@ the legacy root pixel extent; that extent does not specify a composite viewport.
 			"offsetX": 4,
 			"offsetY": 0,
 			"rotationZ": 15,
-			"grid": { "cols": 1, "rows": 1, "cellWidth": 8, "cellHeight": 16 },
+			"grid": {
+				"cols": 1,
+				"rows": 1,
+				"cellWidth": 8,
+				"cellHeight": 16
+			},
 			"cells": {
 				"encoding": "object-rows-v1",
 				"rows": [
@@ -186,7 +214,12 @@ the legacy root pixel extent; that extent does not specify a composite viewport.
 							"character": "*",
 							"foreground": "#ff000080",
 							"background": "#00000000",
-							"transform": { "invert": false, "flipX": true, "flipY": false, "rotation": 90 }
+							"transform": {
+								"invert": false,
+								"flipX": true,
+								"flipY": false,
+								"rotation": 90
+							}
 						}
 					]
 				]

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.