@textmode/document 1.0.0 → 1.1.0

package/docs/specification-2.0.md

@@ -1,19 +1,19 @@
 # Textmode document format 2.0
 
-## Status
+> 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.
 
-This document defines `textmode.document` version `2.0.0`. The canonical
-specification, schema, and decoder are maintained by `textmode-document` and
-published as `@textmode/document`. The raw schema is available from
-`@textmode/document/schema/2.0` and [the repository](../schemas/2.0/schema.json).
-The schema's `$id` is a stable identifier, not a hosted download URL.
+## Status
 
-The ESM-only package root exposes the decoder and types. Package version `1.0.0`
-is independent of file version `2.0.0`. Test fixtures are private repository data;
-complete public documents appear in the [consumer guide](consumer-guide.md).
+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.
 
-The format represents editable cell data. It does not represent final rendered
-pixels, post-processing, an editor project, or authored animation.
+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
 
@@ -25,9 +25,8 @@ profile in RFC 7493:
 - non-finite numbers are not emitted;
 - timestamps use an uppercase, timezone-qualified RFC 3339 representation.
 
-These are producer requirements and recommendations. The JavaScript parser uses
-native `JSON.parse`, which does not detect duplicate object keys and retains the
-last value. No duplicate-key detection is claimed by this codec.
+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
@@ -57,16 +56,15 @@ container format.
 
 ## Version compatibility
 
-The version is SemVer-shaped for release communication. Version 2 does not
-define reader negotiation or a formal extension mechanism. Consumers therefore
-accept only explicitly tested versions and migrations; they must not assume an
-unknown `2.x` version is compatible.
+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 object members.
-The canonical decoder omits these members from its new output object; it does
-not preserve them for reserialization.
-They reject unknown values of tagged members such as `format`, `target`, and
-`encoding` because those values change interpretation.
+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
@@ -128,8 +126,7 @@ 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.
 
-A future major format may replace this legacy name with `gridPixelSize`; v2
-semantics must not be changed in place.
+The meaning of this field must not change within version 2.
 
 ## Cell encoding
 
@@ -231,10 +228,9 @@ throws `TypeError`. Invalid document data instead returns a typed failure.
 | `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 bound file bytes or parser
-memory. The schema's fixed glyph `maxLength` remains 64 even when an app raises
-the decoder's glyph budget. Product-specific policy belongs to the product. For example,
-`create.textmode.art` may accept fewer cells than another document consumer.
+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:
 
@@ -254,14 +250,14 @@ The compatibility decoder recognizes:
 - `textmode.layer@1.0.0` as a selected cell snapshot;
 - `textmode.layer@1.1.0` as a layer stack.
 
-Both migrate to the canonical v2 union and return a migration warning. Callers
-may disable legacy decoding.
+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 the portable structure and is suitable for
-documentation and general tooling. The runtime decoder remains authoritative
-for:
+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;

package/docs/specification-3.0.md

@@ -0,0 +1,134 @@
+# Textmode document format 3.0
+
+## Status and scope
+
+This specification defines `textmode.document@3.0.0`. The npm package version
+is independent of the document version. The [JSON Schema](../schemas/3.0/schema.json)
+uses Draft 2020-12 and is available as `@textmode/document/schema/3.0`. Its `$id`
+is an identifier and does not guarantee a hosted download.
+
+A document stores editable cells in ordered layers. It does not store font identity
+or assets, a viewport, animation, editor project state, history, or post-processing.
+
+## Encoding and root
+
+Files are UTF-8 JSON objects. Producers should use unique keys, safe integers,
+finite numbers, and uppercase, timezone-qualified timestamps. JavaScript's
+`JSON.parse` keeps the last value when a key is repeated; it does not report
+duplicates. The `.textmode.json` suffix and `application/json` MIME type are hints.
+Readers identify the format using `format` and `formatVersion`.
+
+The root requires `format: "textmode.document"`, `formatVersion: "3.0.0"`, and
+`layers`. Optional `metadata` is defined below. `layers` is a nonempty array in
+bottom-to-top order; there is no separate single-layer shape. Root `target`,
+`layer`, `grid`, and `canvas` are obsolete and invalid, including when null.
+
+Unknown ordinary fields are allowed, except for the reserved root fields above.
+The decoder omits unknown fields from its canonical output, so decoding and
+reserializing does not preserve extensions. Readers reject unknown `format`,
+`formatVersion`, and cell `encoding` values. Accept only explicitly supported
+versions: v3 does not define version negotiation, required extensions, an
+extension registry, or automatic compatibility with future 3.x versions.
+
+## Layer structure and presentation
+
+Every layer requires all fields below, including when it is the only layer:
+
+| Field                | Meaning                                                                                                                                                           |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                 | Nonempty informational source ID; not a cross-file identity. Uniqueness is not enforced.                                                                          |
+| `visible`            | Boolean; hidden cells remain stored.                                                                                                                              |
+| `opacity`            | Number in [0, 1], independent of cell alpha.                                                                                                                      |
+| `blendMode`          | Nonempty bounded name; unknown names are preserved. Apps choose which names they support.                                                                         |
+| `offsetX`, `offsetY` | Finite pixel offsets; positive x is right and positive y is down in textmode.js.                                                                                  |
+| `rotationZ`          | Finite degrees, clockwise about the layer's rectangular center in textmode.js. Offset does not change the local rotation origin. Preserved without normalization. |
+| `grid`               | Independent logical dimensions and cell pixel metrics.                                                                                                            |
+| `cells`              | Complete dense row-major cell data.                                                                                                                               |
+
+The textmode.js producer names are `normal`, `additive`, `multiply`, `screen`,
+`subtract`, `darken`, `lighten`, `overlay`, `softLight`, `hardLight`,
+`colorDodge`, `colorBurn`, `difference`, and `exclusion`. These are not an enum
+in the portable schema. Apps must not silently replace an unsupported meaningful
+mode with `normal`.
+
+Each `grid` requires positive safe integers for `cols`, `rows`, `cellWidth`, and
+`cellHeight`. The cell count and pixel products must also be safe integers. Layers
+can have different grids. A layer's pixel extent is `cols × cellWidth` by
+`rows × cellHeight`. Do not infer a root grid or viewport.
+
+## Cells and coordinates
+
+Every `cells` object requires `encoding: "object-rows-v1"` and `rows`.
+`rows.length` equals `grid.rows`; each row length equals `grid.cols`. Every cell,
+including transparent cells, is present. A cell requires `x`, `y`, `character`,
+`foreground`, `background`, and `transform`.
+
+Coordinates are zero-based nonnegative safe integers. In `rows[y][x]`, the
+cell's stored `x` and `y` must match its array position. Consumers must reject a
+mismatch without repairing or reordering cells. The decoder enforces this rule.
+
+## Glyphs, colors, and transforms
+
+`character` is a nonempty, well-formed Unicode glyph string. It may contain
+multiple scalar values, such as a combining sequence or joined emoji. Preserve it
+without Unicode normalization. Unpaired surrogates are invalid. The schema uses
+`minLength: 1` and `maxLength: 64`; the default decoder limit is 64 Unicode scalar
+values. Changing a decoder limit does not change the published schema.
+
+Each color is `#RRGGBB`, `#RRGGBBAA`, or an object with required integer `r`, `g`,
+`b`, and `a` channels in [0, 255]. Six-digit notation implies alpha 255. Channels
+are unpremultiplied; alpha 0 is transparent and 255 is opaque. Canonical output
+uses RGBA channel objects. A space with visible background remains meaningful;
+a cell is visually empty only when both foreground and background alpha are zero.
+
+Each transform requires boolean `invert`, `flipX`, and `flipY` values and a finite
+`rotation` in degrees. The decoder normalizes cell rotation to [0, 360): -90
+becomes 270 and 360 becomes 0. Layer rotation is separate. Swapping colors is
+not a general replacement for inversion when alpha is present. Consumers must
+reject unsupported meaningful transforms rather than approximate them without an
+explicit product operation.
+
+## Metadata
+
+Optional root `metadata`, when present, requires `createdAt` and `generator`.
+`generator` requires nonempty bounded `name` and `version` strings and can
+identify any producer. It does not select executable behavior.
+
+`createdAt` is a real calendar date and time with uppercase T, required seconds,
+a timezone, optional fractional seconds, and no leap seconds. Valid timestamps
+are preserved as written. Enable date-time format assertions in JSON Schema
+validators; format annotations alone are insufficient.
+
+## Validation, budgets, and compatibility
+
+The schema defines structure and local constraints. This specification defines
+meaning. The decoder also checks row sizes, coordinates, safe products, Unicode,
+and caller limits, and normalizes output. A schema-valid document may still fail
+decoding.
+
+| Decoder limit             |    Default | Counting rule                                              |
+| ------------------------- | ---------: | ---------------------------------------------------------- |
+| `maxCells`                | 16,777,216 | Cumulative across all layers.                              |
+| `maxLayers`               |      4,096 | Layer count.                                               |
+| `maxLayerIdLength`        |      1,024 | UTF-16 code units per ID.                                  |
+| `maxCharacterLength`      |         64 | Unicode scalar values per glyph.                           |
+| `maxMetadataStringLength` |      4,096 | UTF-16 code units per metadata string and blend-mode name. |
+
+Every override must be a positive safe integer. Invalid configuration throws
+`TypeError`; invalid document input returns a failure result. Budgets apply
+after parsing and do not bound input bytes or parser memory. Apps must apply
+appropriate byte caps before reading/parsing and their own font and feature
+policy after protocol decoding. Documents do not authorize fetching resources,
+font installation, or code execution.
+
+Supported v2 files are validated under their original rules, including canvas
+extent checks, before conversion. Selected v2 snapshots move their root grid
+into one layer and receive visible=true, opacity=1, normal blending, and zero
+offsets/rotation. V2 stacks preserve their layers. Both return
+`DOCUMENT_VERSION_MIGRATED` and canonical v3 output.
+
+Legacy `textmode.layer@1.0.0` and `textmode.layer@1.1.0` migrate to one or more
+layers and return `LEGACY_DOCUMENT_MIGRATED`. `acceptLegacy: false` rejects these
+textmode.layer files but still accepts supported textmode.document v2 files.
+The [v2 specification](specification-2.0.md) and schema remain available; their
+wire-format constraints are unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@textmode/document",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "Portable textmode document format, JSON Schema, types, and dependency-free decoder.",
 	"license": "CC0-1.0",
 	"author": "humanbydefinition <hello@textmode.art> (https://code.textmode.art)",
@@ -32,6 +32,10 @@
 		"./schema/2.0": {
 			"types": "./schemas/2.0/schema.d.ts",
 			"default": "./schemas/2.0/schema.json"
+		},
+		"./schema/3.0": {
+			"types": "./schemas/3.0/schema.d.ts",
+			"default": "./schemas/3.0/schema.json"
 		}
 	},
 	"files": [
@@ -39,7 +43,9 @@
 		"dist/**/*.d.ts",
 		"schemas/2.0/schema.json",
 		"schemas/2.0/schema.d.ts",
-		"docs/*.md"
+		"docs/*.md",
+		"schemas/3.0/schema.json",
+		"schemas/3.0/schema.d.ts"
 	],
 	"publishConfig": {
 		"access": "public"
@@ -62,10 +68,9 @@
 		"typecheck": "tsc --noEmit -p tsconfig.json",
 		"docs:check": "textmode-docs check",
 		"docs:build": "textmode-docs build",
-		"test": "vitest run",
+		"test": "vitest run --dir tests",
 		"check:package": "node scripts/check-package.mjs",
 		"check": "npm run format:check && npm run lint && npm run lint:markdown && npm run typecheck && npm run docs:check && npm test && npm run build && npm run check:package",
-		"prepack": "npm run build",
 		"prepare": "npm run build"
 	},
 	"devDependencies": {

package/schemas/3.0/schema.d.ts

@@ -0,0 +1,3 @@
+declare const schema: Readonly<Record<string, unknown>>;
+
+export default schema;

package/schemas/3.0/schema.json

@@ -0,0 +1,267 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://textmode.art/schemas/textmode-document-3.0.schema.json",
+	"title": "Textmode document 3.0",
+	"description": "One or more portable textmode layers in bottom-to-top order. See docs/specification-3.0.md.",
+	"$defs": {
+		"positiveSafeInteger": {
+			"type": "integer",
+			"minimum": 1,
+			"maximum": 9007199254740991,
+			"description": "Positive integer in the interoperable JavaScript safe range."
+		},
+		"grid": {
+			"type": "object",
+			"required": ["cols", "rows", "cellWidth", "cellHeight"],
+			"properties": {
+				"cols": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Positive number of columns."
+				},
+				"rows": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Positive number of rows."
+				},
+				"cellWidth": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Positive cell width in pixels."
+				},
+				"cellHeight": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Positive cell height in pixels."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Logical cell count and pixel dimensions of each cell. Products must remain safe integers."
+		},
+		"rgba": {
+			"type": "object",
+			"required": ["r", "g", "b", "a"],
+			"properties": {
+				"r": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 255,
+					"description": "Red channel."
+				},
+				"g": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 255,
+					"description": "Green channel."
+				},
+				"b": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 255,
+					"description": "Blue channel."
+				},
+				"a": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 255,
+					"description": "Alpha: 0 is transparent and 255 is opaque."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Unpremultiplied RGBA integer channels from 0 through 255."
+		},
+		"color": {
+			"oneOf": [
+				{
+					"type": "string",
+					"pattern": "^#[0-9A-Fa-f]{6}(?:[0-9A-Fa-f]{2})?$"
+				},
+				{
+					"$ref": "#/$defs/rgba"
+				}
+			],
+			"description": "RGB or RGBA hexadecimal notation, or explicit RGBA channels. Six-digit notation implies alpha 255."
+		},
+		"transform": {
+			"type": "object",
+			"required": ["invert", "flipX", "flipY", "rotation"],
+			"properties": {
+				"invert": {
+					"type": "boolean",
+					"description": "Glyph inversion; alpha means this cannot generally be replaced by swapping colors."
+				},
+				"flipX": {
+					"type": "boolean",
+					"description": "Mirror the glyph horizontally."
+				},
+				"flipY": {
+					"type": "boolean",
+					"description": "Mirror the glyph vertically."
+				},
+				"rotation": {
+					"type": "number",
+					"description": "Cell rotation in degrees; normalized by the decoder to [0, 360)."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Per-cell glyph transforms. Rotation is finite degrees; decoding normalizes it to [0, 360)."
+		},
+		"cell": {
+			"type": "object",
+			"required": ["x", "y", "character", "foreground", "background", "transform"],
+			"properties": {
+				"x": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 9007199254740991,
+					"description": "Zero-based column index; must equal the position within its row."
+				},
+				"y": {
+					"type": "integer",
+					"minimum": 0,
+					"maximum": 9007199254740991,
+					"description": "Zero-based row index; must equal the row position."
+				},
+				"character": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64,
+					"description": "Nonempty Unicode glyph string, preserved without normalization. The decoder rejects unpaired surrogates and enforces a scalar-count budget."
+				},
+				"foreground": {
+					"$ref": "#/$defs/color",
+					"description": "Glyph color with alpha."
+				},
+				"background": {
+					"$ref": "#/$defs/color",
+					"description": "Cell background color with alpha. A space with a visible background remains meaningful."
+				},
+				"transform": {
+					"$ref": "#/$defs/transform",
+					"description": "Per-cell glyph inversion, flips, and rotation."
+				}
+			},
+			"additionalProperties": true,
+			"description": "One cell at its redundant zero-based row and column. Coordinates must match array position; this cross-field rule is checked by the decoder."
+		},
+		"cells": {
+			"type": "object",
+			"required": ["encoding", "rows"],
+			"properties": {
+				"encoding": {
+					"const": "object-rows-v1",
+					"description": "Tagged cell encoding; v2 supports only object-rows-v1."
+				},
+				"rows": {
+					"type": "array",
+					"items": {
+						"type": "array",
+						"items": {
+							"$ref": "#/$defs/cell"
+						}
+					},
+					"description": "Dense row-major arrays; row count and lengths must equal the owning grid. The decoder checks this invariant."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Dense row-major cells, including transparent cells. Row count and lengths must equal the grid. See docs/specification-3.0.md#cells-and-coordinates."
+		},
+		"metadata": {
+			"type": "object",
+			"required": ["createdAt", "generator"],
+			"properties": {
+				"createdAt": {
+					"type": "string",
+					"format": "date-time",
+					"pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]+)?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])$",
+					"description": "Real calendar date and time with uppercase T and timezone, required seconds, optional fractional seconds, and no leap seconds. Enable date-time format assertions in validators."
+				},
+				"generator": {
+					"type": "object",
+					"required": ["name", "version"],
+					"properties": {
+						"name": {
+							"type": "string",
+							"minLength": 1
+						},
+						"version": {
+							"type": "string",
+							"minLength": 1
+						}
+					},
+					"additionalProperties": true,
+					"description": "Producer identity; it does not select executable behavior."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Optional informational creation and generator metadata. When present, both members are required."
+		},
+		"layer": {
+			"type": "object",
+			"required": ["id", "visible", "opacity", "blendMode", "offsetX", "offsetY", "rotationZ", "grid", "cells"],
+			"properties": {
+				"id": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Nonempty informational source identifier. It is not a persistent cross-document identity; the decoder does not enforce uniqueness."
+				},
+				"visible": {
+					"type": "boolean",
+					"description": "Whether the layer participates in presentation. Hidden cells are still stored."
+				},
+				"opacity": {
+					"type": "number",
+					"minimum": 0,
+					"maximum": 1,
+					"description": "Layer opacity from 0 through 1, separate from cell alpha."
+				},
+				"blendMode": {
+					"type": "string",
+					"minLength": 1,
+					"description": "Nonempty blend mode name. The decoder preserves unknown names; apps decide which they can present."
+				},
+				"offsetX": { "type": "number", "description": "Horizontal compositing offset in pixels." },
+				"offsetY": { "type": "number", "description": "Vertical compositing offset in pixels." },
+				"rotationZ": {
+					"type": "number",
+					"description": "Layer rotation in degrees, clockwise about the layer center in textmode.js; preserved by the decoder."
+				},
+				"grid": {
+					"$ref": "#/$defs/grid",
+					"description": "Grid dimensions and cell metrics."
+				},
+				"cells": {
+					"$ref": "#/$defs/cells",
+					"description": "Complete dense cell rows."
+				}
+			},
+			"additionalProperties": true,
+			"description": "One complete layer, including for documents containing a single layer."
+		}
+	},
+	"type": "object",
+	"required": ["format", "formatVersion", "layers"],
+	"properties": {
+		"format": {
+			"const": "textmode.document",
+			"description": "Required portable document format discriminator."
+		},
+		"formatVersion": {
+			"const": "3.0.0",
+			"description": "On-disk format version, independent of package versions."
+		},
+		"metadata": {
+			"$ref": "#/$defs/metadata",
+			"description": "Optional informational timestamp and producer identity."
+		},
+		"layers": {
+			"type": "array",
+			"minItems": 1,
+			"items": {
+				"$ref": "#/$defs/layer"
+			},
+			"description": "Nonempty ordered layer stack, bottom first."
+		},
+		"target": false,
+		"layer": false,
+		"grid": false,
+		"canvas": false
+	},
+	"additionalProperties": true
+}

package/docs/maintenance.md

@@ -1,56 +0,0 @@
-# Maintaining the document contract
-
-## Ownership
-
-This repository owns the format specification, versioned JSON Schema, portable
-types, decoder, and protocol checks. `textmode.export.js` owns renderer extraction,
-selection, generator metadata, serialization options, and downloads. Apps own
-placement, history, font selection, and supported-feature decisions.
-
-The schema describes portable structure and local constraints. The specification
-defines meaning and cross-field rules. The decoder implements these rules plus
-normalization and caller budgets. Keep all three consistent through contract
-tests; do not generate competing schemas or copy protocol logic into callers.
-
-## Compatibility
-
-Package releases and on-disk versions are independent. Preserve the meaning of
-`textmode.document@2.0.0`, including its selected/all distinction and legacy
-`canvas` field. A new document version needs an explicit reader, specification,
-schema, and compatibility tests before it is accepted. Do not infer support for
-future `2.x` files. Namespaced or required extensions need a future design.
-
-Keep published versioned schemas stable. Documentation annotations may improve;
-constraint or semantic changes require a compatibility review and explicit
-versioning. Changes to normalized results, error codes, paths, migration warnings,
-or default limits are also public behavior. Deprecate a JavaScript interface before
-removing it from a stable package major.
-
-## Tests and documentation
-
-Fixtures are fixed test inputs. They protect legacy migration and edge cases and
-are neither demos nor supported package imports. Keep them in `tests/fixtures`,
-out of the package allowlist. Read the fixture README before changing their data.
-
-Validate every complete `json` block in the consumer guide against the schema
-and decoder. Keep syntax fragments in the specification clearly labeled. Run
-`npm run check` for formatting, lint, Markdown, types, API docs, tests, build, and
-an isolated packed-package check. The docs build disables browser sketch checks
-because this package has no browser gallery.
-
-## npm releases
-
-The package is prepared for npm as `@textmode/document`. Its package version is
-independent of the on-disk `textmode.document@2.0.0` format version. A package
-release does not change the document format.
-
-Before publishing, run `npm run check` and inspect `npm pack --dry-run`. Confirm
-that the archive contains the runtime, declarations, schemas, and consumer docs,
-and excludes fixtures and tests. This repository has no automated npm publish
-workflow.
-
-The exporter currently pins this repository at an exact Git commit. When the
-registry release is ready for consumer adoption, update the exporter to the exact
-published version and regenerate its lockfile with npm. The source repository is
-private, so Git-based installs require authenticated read access until consumers
-move to the public npm package.