@textmode/document 0.0.0-stage → 1.0.0

package/dist/types/wire.d.ts

@@ -0,0 +1,100 @@
+import type { TEXTMODE_DOCUMENT_FORMAT, TEXTMODE_DOCUMENT_FORMAT_VERSION, TEXTMODE_OBJECT_ROWS_ENCODING } from '../constants.js';
+/**
+ * Scope encoded by a textmode document.
+ *
+ * @category JSON document data
+ */
+export type TextmodeDocumentTarget = 'selected' | 'all';
+/** Format discriminator encoded in a document. */
+export type TextmodeDocumentFormat = typeof TEXTMODE_DOCUMENT_FORMAT;
+/** Current on-disk format version, independent of the npm package version. */
+export type TextmodeDocumentVersion = typeof TEXTMODE_DOCUMENT_FORMAT_VERSION;
+/** RGBA color channels, each an integer from 0 through 255. */
+export interface TextmodeDocumentRGBAColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** On-disk color notation; decoded colors use RGBA channels. */
+export type TextmodeDocumentColor = string | TextmodeDocumentRGBAColor;
+/** Per-cell transform in degrees. */
+export interface TextmodeDocumentCellTransform {
+    invert: boolean;
+    flipX: boolean;
+    flipY: boolean;
+    rotation: number;
+}
+/** Cell at its redundant row-major x/y coordinates. */
+export interface TextmodeDocumentCell {
+    x: number;
+    y: number;
+    character: string;
+    foreground: TextmodeDocumentColor;
+    background: TextmodeDocumentColor;
+    transform: TextmodeDocumentCellTransform;
+}
+/** Dense row-major cell collection. */
+export interface TextmodeDocumentCellCollection {
+    encoding: typeof TEXTMODE_OBJECT_ROWS_ENCODING;
+    rows: TextmodeDocumentCell[][];
+}
+/** Logical grid dimensions and pixel extent of each cell. */
+export interface TextmodeDocumentGrid {
+    cols: number;
+    rows: number;
+    cellWidth: number;
+    cellHeight: number;
+}
+/** Optional producer information; it does not control decoding behavior. */
+export interface TextmodeDocumentMetadata {
+    createdAt: string;
+    generator: {
+        name: string;
+        version: string;
+    };
+}
+export interface TextmodeSelectedDocumentLayer {
+    id: string;
+    cells: TextmodeDocumentCellCollection;
+}
+export interface TextmodeSelectedDocumentJSON {
+    format: TextmodeDocumentFormat;
+    formatVersion: TextmodeDocumentVersion;
+    target: 'selected';
+    metadata?: TextmodeDocumentMetadata;
+    canvas: {
+        width: number;
+        height: number;
+    };
+    grid: TextmodeDocumentGrid;
+    layer: TextmodeSelectedDocumentLayer;
+}
+export interface TextmodeDocumentLayer {
+    id: string;
+    visible: boolean;
+    opacity: number;
+    blendMode: string;
+    offsetX: number;
+    offsetY: number;
+    rotationZ: number;
+    grid: TextmodeDocumentGrid;
+    cells: TextmodeDocumentCellCollection;
+}
+export interface TextmodeAllDocumentJSON {
+    format: TextmodeDocumentFormat;
+    formatVersion: TextmodeDocumentVersion;
+    target: 'all';
+    metadata?: TextmodeDocumentMetadata;
+    canvas: {
+        width: number;
+        height: number;
+    };
+    layers: TextmodeDocumentLayer[];
+}
+/**
+ * JSON document produced by the selected-layer or layer-stack exporter.
+ *
+ * @category JSON document data
+ */
+export type TextmodeDocumentJSON = TextmodeSelectedDocumentJSON | TextmodeAllDocumentJSON;

package/dist/types/wire.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,37 @@
+import type { TextmodeDocumentMetadata, TextmodeDocumentGrid, TextmodeDocumentRGBAColor, TextmodeDocumentDecodeResult, TextmodeDocumentError, TextmodeDocumentErrorCode, TextmodeDocumentLimits } from './types/index.js';
+export type UnknownRecord = Record<string, unknown>;
+export type ResolvedLimits = Required<TextmodeDocumentLimits>;
+export type DecodeContext = {
+    limits: ResolvedLimits;
+    remainingCells: number;
+};
+export declare class DocumentDecodeFailure extends Error {
+    readonly detail: TextmodeDocumentError;
+    constructor(detail: TextmodeDocumentError);
+}
+export declare function decodeColor(value: unknown, path: string): TextmodeDocumentRGBAColor;
+export declare function decodeCanvas(value: unknown, path: string): {
+    width: number;
+    height: number;
+};
+export declare function decodeGrid(value: unknown, path: string): TextmodeDocumentGrid;
+export declare function decodeMetadata(value: unknown, path: string, limits: ResolvedLimits): TextmodeDocumentMetadata;
+export declare function decodeLayerId(value: unknown, path: string, limits: ResolvedLimits): string;
+export declare function assertCanvasMatchesGrid(canvas: {
+    width: number;
+    height: number;
+}, grid: TextmodeDocumentGrid, path: string): void;
+export declare function resolveLimits(limits: TextmodeDocumentLimits | undefined): ResolvedLimits;
+export declare function checkedProduct(left: number, right: number, path: string): number;
+export declare function normalizeRotation(rotation: number): number;
+export declare function requireRecord(value: unknown, path: string): UnknownRecord;
+export declare function requireArray(value: unknown, path: string): unknown[];
+export declare function requireString(value: unknown, path: string): string;
+export declare function requireBoundedString(value: unknown, path: string, maxLength: number): string;
+export declare function requireCharacter(value: unknown, path: string, limits: ResolvedLimits): string;
+export declare function requireBoolean(value: unknown, path: string): boolean;
+export declare function requireFiniteNumber(value: unknown, path: string): number;
+export declare function requireNumberInRange(value: unknown, path: string, minimum: number, maximum: number): number;
+export declare function requireSafeInteger(value: unknown, path: string): number;
+export declare function failure(code: TextmodeDocumentErrorCode, message: string, path?: string): TextmodeDocumentDecodeResult;
+export declare function fail(code: TextmodeDocumentErrorCode, message: string, path?: string): never;

package/dist/validation.js

@@ -0,0 +1,205 @@
+import { DEFAULT_TEXTMODE_DOCUMENT_LIMITS } from './constants.js';
+export class DocumentDecodeFailure extends Error {
+    constructor(detail) {
+        super(detail.message);
+        this.detail = detail;
+    }
+}
+export function decodeColor(value, path) {
+    if (typeof value === 'string') {
+        const match = /^#([0-9a-f]{6}|[0-9a-f]{8})$/i.exec(value);
+        if (!match) {
+            fail('INVALID_DOCUMENT', 'Expected #RRGGBB or #RRGGBBAA color notation.', path);
+        }
+        const hex = match[1];
+        return {
+            r: Number.parseInt(hex.slice(0, 2), 16),
+            g: Number.parseInt(hex.slice(2, 4), 16),
+            b: Number.parseInt(hex.slice(4, 6), 16),
+            a: hex.length === 8 ? Number.parseInt(hex.slice(6, 8), 16) : 255,
+        };
+    }
+    const color = requireRecord(value, path);
+    return {
+        r: requireByte(color.r, `${path}.r`),
+        g: requireByte(color.g, `${path}.g`),
+        b: requireByte(color.b, `${path}.b`),
+        a: requireByte(color.a, `${path}.a`),
+    };
+}
+export function decodeCanvas(value, path) {
+    const canvas = requireRecord(value, path);
+    return {
+        width: requirePositiveSafeInteger(canvas.width, `${path}.width`),
+        height: requirePositiveSafeInteger(canvas.height, `${path}.height`),
+    };
+}
+export function decodeGrid(value, path) {
+    const grid = requireRecord(value, path);
+    return {
+        cols: requirePositiveSafeInteger(grid.cols, `${path}.cols`),
+        rows: requirePositiveSafeInteger(grid.rows, `${path}.rows`),
+        cellWidth: requirePositiveSafeInteger(grid.cellWidth, `${path}.cellWidth`),
+        cellHeight: requirePositiveSafeInteger(grid.cellHeight, `${path}.cellHeight`),
+    };
+}
+export function decodeMetadata(value, path, limits) {
+    const metadata = requireRecord(value, path);
+    const generator = requireRecord(metadata.generator, `${path}.generator`);
+    const generatorName = requireBoundedString(generator.name, `${path}.generator.name`, limits.maxMetadataStringLength);
+    const createdAt = requireBoundedString(metadata.createdAt, `${path}.createdAt`, limits.maxMetadataStringLength);
+    assertTimestamp(createdAt, `${path}.createdAt`);
+    return {
+        createdAt,
+        generator: {
+            name: generatorName,
+            version: requireBoundedString(generator.version, `${path}.generator.version`, limits.maxMetadataStringLength),
+        },
+    };
+}
+const TIMESTAMP_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])$/;
+function assertTimestamp(value, path) {
+    const match = TIMESTAMP_PATTERN.exec(value);
+    if (!match)
+        fail('INVALID_DOCUMENT', 'Expected an uppercase RFC 3339 timestamp with seconds and a timezone.', path);
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const daysInMonth = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    if (day > daysInMonth[month - 1])
+        fail('INVALID_DOCUMENT', 'Timestamp contains an invalid calendar date.', path);
+}
+export function decodeLayerId(value, path, limits) {
+    return requireBoundedString(value, path, limits.maxLayerIdLength);
+}
+export function assertCanvasMatchesGrid(canvas, grid, path) {
+    const expectedWidth = checkedProduct(grid.cols, grid.cellWidth, `${path}.width`);
+    const expectedHeight = checkedProduct(grid.rows, grid.cellHeight, `${path}.height`);
+    if (canvas.width !== expectedWidth || canvas.height !== expectedHeight) {
+        fail('INVALID_DOCUMENT', `Canvas must equal the grid pixel extent ${expectedWidth}x${expectedHeight}.`, path);
+    }
+}
+export function resolveLimits(limits) {
+    return {
+        maxCells: resolveLimit(limits?.maxCells, DEFAULT_TEXTMODE_DOCUMENT_LIMITS.maxCells, 'maxCells'),
+        maxLayers: resolveLimit(limits?.maxLayers, DEFAULT_TEXTMODE_DOCUMENT_LIMITS.maxLayers, 'maxLayers'),
+        maxLayerIdLength: resolveLimit(limits?.maxLayerIdLength, DEFAULT_TEXTMODE_DOCUMENT_LIMITS.maxLayerIdLength, 'maxLayerIdLength'),
+        maxCharacterLength: resolveLimit(limits?.maxCharacterLength, DEFAULT_TEXTMODE_DOCUMENT_LIMITS.maxCharacterLength, 'maxCharacterLength'),
+        maxMetadataStringLength: resolveLimit(limits?.maxMetadataStringLength, DEFAULT_TEXTMODE_DOCUMENT_LIMITS.maxMetadataStringLength, 'maxMetadataStringLength'),
+    };
+}
+function resolveLimit(value, fallback, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer.`);
+    }
+    return value;
+}
+export function checkedProduct(left, right, path) {
+    const product = left * right;
+    if (!Number.isSafeInteger(product)) {
+        fail('LIMIT_EXCEEDED', 'Numeric dimensions exceed the safe integer range.', path);
+    }
+    return product;
+}
+export function normalizeRotation(rotation) {
+    const normalized = ((rotation % 360) + 360) % 360;
+    return Object.is(normalized, -0) ? 0 : normalized;
+}
+export function requireRecord(value, path) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        fail('INVALID_DOCUMENT', 'Expected an object.', path);
+    }
+    return value;
+}
+export function requireArray(value, path) {
+    if (!Array.isArray(value))
+        fail('INVALID_DOCUMENT', 'Expected an array.', path);
+    return value;
+}
+export function requireString(value, path) {
+    if (typeof value !== 'string')
+        fail('INVALID_DOCUMENT', 'Expected a string.', path);
+    return value;
+}
+export function requireBoundedString(value, path, maxLength) {
+    const text = requireString(value, path);
+    if (text.length === 0)
+        fail('INVALID_DOCUMENT', 'Expected a non-empty string.', path);
+    if (text.length > maxLength) {
+        fail('LIMIT_EXCEEDED', `String length exceeds the configured limit ${maxLength}.`, path);
+    }
+    return text;
+}
+export function requireCharacter(value, path, limits) {
+    const character = requireString(value, path);
+    if (character.length === 0) {
+        fail('INVALID_DOCUMENT', 'Expected a non-empty glyph string.', path);
+    }
+    assertWellFormedUnicode(character, path);
+    if (Array.from(character).length > limits.maxCharacterLength) {
+        fail('LIMIT_EXCEEDED', `Glyph string scalar count exceeds the configured limit ${limits.maxCharacterLength}.`, path);
+    }
+    return character;
+}
+function assertWellFormedUnicode(value, path) {
+    for (let index = 0; index < value.length; index++) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!Number.isInteger(next) || next < 0xdc00 || next > 0xdfff) {
+                fail('INVALID_DOCUMENT', 'Glyph strings must not contain unpaired surrogates.', path);
+            }
+            index++;
+            continue;
+        }
+        if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+            fail('INVALID_DOCUMENT', 'Glyph strings must not contain unpaired surrogates.', path);
+        }
+    }
+}
+export function requireBoolean(value, path) {
+    if (typeof value !== 'boolean')
+        fail('INVALID_DOCUMENT', 'Expected a boolean.', path);
+    return value;
+}
+export function requireFiniteNumber(value, path) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        fail('INVALID_DOCUMENT', 'Expected a finite number.', path);
+    }
+    return value;
+}
+export function requireNumberInRange(value, path, minimum, maximum) {
+    const number = requireFiniteNumber(value, path);
+    if (number < minimum || number > maximum) {
+        fail('INVALID_DOCUMENT', `Expected a number from ${minimum} through ${maximum}.`, path);
+    }
+    return number;
+}
+export function requireSafeInteger(value, path) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+        fail('INVALID_DOCUMENT', 'Expected a safe integer.', path);
+    }
+    return value;
+}
+function requirePositiveSafeInteger(value, path) {
+    const integer = requireSafeInteger(value, path);
+    if (integer <= 0)
+        fail('INVALID_DOCUMENT', 'Expected a positive safe integer.', path);
+    return integer;
+}
+function requireByte(value, path) {
+    const integer = requireSafeInteger(value, path);
+    if (integer < 0 || integer > 255) {
+        fail('INVALID_DOCUMENT', 'Expected an integer from 0 through 255.', path);
+    }
+    return integer;
+}
+export function failure(code, message, path) {
+    return { ok: false, error: { code, message, ...(path ? { path } : {}) } };
+}
+export function fail(code, message, path) {
+    throw new DocumentDecodeFailure({ code, message, ...(path ? { path } : {}) });
+}

package/docs/consumer-guide.md

@@ -0,0 +1,197 @@
+# Consumer guide
+
+## 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.
+
+```js
+import { parseJSON, decodeTextmodeDocument } from '@textmode/document';
+
+const parsed = parseJSON(jsonText);
+if (!parsed.ok) {
+	console.error(parsed.error);
+} else if (
+	parsed.value !== null &&
+	typeof parsed.value === 'object' &&
+	!Array.isArray(parsed.value) &&
+	['textmode.document', 'textmode.layer'].includes(parsed.value.format)
+) {
+	const result = decodeTextmodeDocument(parsed.value, {
+		acceptLegacy: true,
+		limits: { maxCells: 16384, maxLayers: 64 },
+	});
+	console.log(result);
+} else {
+	// Route other supported formats to the app's other decoders.
+}
+```
+
+`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.
+
+## 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`.
+
+| Code                   | Meaning                                                           |
+| ---------------------- | ----------------------------------------------------------------- |
+| `INVALID_JSON`         | The input is not valid JSON syntax.                               |
+| `INVALID_DOCUMENT`     | A value or cross-field invariant is invalid.                      |
+| `UNSUPPORTED_FORMAT`   | The discriminator is unsupported, or legacy decoding is disabled. |
+| `UNSUPPORTED_VERSION`  | The format version is not explicitly supported.                   |
+| `UNSUPPORTED_TARGET`   | The document shape is unsupported.                                |
+| `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.
+
+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).
+
+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.
+
+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.
+
+## 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' };
+```
+
+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.
+
+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' };
+
+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`.
+
+## Complete selected document
+
+A selected document contains cell data and grid metrics. It carries no layer
+presentation or font identity.
+
+```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 }
+					}
+				]
+			]
+		}
+	}
+}
+```
+
+## 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.
+
+```json
+{
+	"format": "textmode.document",
+	"formatVersion": "2.0.0",
+	"target": "all",
+	"canvas": { "width": 8, "height": 16 },
+	"layers": [
+		{
+			"id": "base",
+			"visible": true,
+			"opacity": 1,
+			"blendMode": "normal",
+			"offsetX": 0,
+			"offsetY": 0,
+			"rotationZ": 0,
+			"grid": { "cols": 1, "rows": 1, "cellWidth": 8, "cellHeight": 16 },
+			"cells": {
+				"encoding": "object-rows-v1",
+				"rows": [
+					[
+						{
+							"x": 0,
+							"y": 0,
+							"character": "A",
+							"foreground": "#ffffffff",
+							"background": "#000000ff",
+							"transform": { "invert": false, "flipX": false, "flipY": false, "rotation": 0 }
+						}
+					]
+				]
+			}
+		},
+		{
+			"id": "accent",
+			"visible": true,
+			"opacity": 0.5,
+			"blendMode": "screen",
+			"offsetX": 4,
+			"offsetY": 0,
+			"rotationZ": 15,
+			"grid": { "cols": 1, "rows": 1, "cellWidth": 8, "cellHeight": 16 },
+			"cells": {
+				"encoding": "object-rows-v1",
+				"rows": [
+					[
+						{
+							"x": 0,
+							"y": 0,
+							"character": "*",
+							"foreground": "#ff000080",
+							"background": "#00000000",
+							"transform": { "invert": false, "flipX": true, "flipY": false, "rotation": 90 }
+						}
+					]
+				]
+			}
+		}
+	]
+}
+```

package/docs/maintenance.md

@@ -0,0 +1,56 @@
+# 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.