textmode.export.js 1.9.0-beta.1 → 1.9.0-beta.2

package/dist/types/exporters/video/types.d.ts

@@ -2,8 +2,6 @@ import type { FrameSequenceDriverLike, FrameSequenceRenderOptions, PrepareExport
 /**
  * High-level lifecycle state reported while a video export is captured, encoded, or completed.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoRecordingState | VideoRecordingState API reference}
  */
 export type VideoRecordingState = 'idle' | 'recording' | 'encoding' | 'completed' | 'error';
@@ -14,8 +12,6 @@ export type VideoRecordingState = 'idle' | 'recording' | 'encoding' | 'completed
  * for buffered output. `rendering`, `encoding`, and `draining` remain available for compatibility with older progress
  * producers.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportPhase | VideoExportPhase API reference}
  */
 export type VideoExportPhase = 'probing' | 'rendering' | 'capturing' | 'encoding' | 'draining' | 'writing' | 'finalizing';
@@ -26,8 +22,6 @@ export type VideoCodec = 'vp8' | 'vp9' | 'avc' | (string & {});
  * Higher levels generally preserve more detail and produce larger, content-dependent files. Mediabunny may use
  * quantizer-based encoding or a codec-adjusted bitrate, depending on codec and browser support.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoQualityLevel | VideoQualityLevel API reference}
  */
 export type VideoQualityLevel = 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
@@ -49,8 +43,6 @@ export type VideoQualityLevel = 'very-low' | 'low' | 'medium' | 'high' | 'very-h
  * await t.saveVideo({ quality: { bitrate: 8_000_000, bitrateMode: 'constant' } });
  * ```
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoQuality | VideoQuality API reference}
  */
 export type VideoQuality = VideoQualityLevel | {
@@ -66,8 +58,6 @@ export type VideoQuality = VideoQualityLevel | {
  *
  * This setting does not affect `toVideoBlob()`, which always returns an in-memory `Blob`.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoSaveDestination | VideoSaveDestination API reference}
  */
 export type VideoSaveDestination = 'download' | 'file-system';
@@ -77,8 +67,6 @@ export type VideoSaveDestination = 'download' | 'file-system';
  * MP4 uses AVC/H.264 and requires even coded dimensions. WebM selects VP9 when available and falls back to VP8; it
  * is the only format that can be requested with transparency.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportFormat | VideoExportFormat API reference}
  */
 export type VideoExportFormat = 'webm' | 'mp4';
@@ -92,8 +80,6 @@ export type VideoExportFormat = 'webm' | 'mp4';
  *
  * If omitted for an explicit target bitrate, Mediabunny uses `'variable'`.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoBitrateMode | VideoBitrateMode API reference}
  */
 export type VideoBitrateMode = 'variable' | 'constant';
@@ -106,8 +92,6 @@ export type VideoBitrateMode = 'variable' | 'constant';
  *   availability and output characteristics vary by device.
  * - `'prefer-software'`: prefer CPU encoding, often more consistent across machines, but usually slower.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoHardwareAcceleration | VideoHardwareAcceleration API reference}
  */
 export type VideoHardwareAcceleration = 'no-preference' | 'prefer-hardware' | 'prefer-software';
@@ -115,8 +99,6 @@ export type VideoExportErrorCode = 'VIDEO_EXPORT_UNSUPPORTED' | 'VIDEO_CODEC_UNS
 /**
  * Progress information emitted while a deterministic video is probed, captured, and written.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportProgress | VideoExportProgress API reference}
  */
 export type VideoExportProgress = {
@@ -192,8 +174,6 @@ export type VideoExportProgress = {
 /**
  * Options for capturing deterministic textmode frames as MP4 or WebM video.
  *
- * @category Video export
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoExportOptions | VideoExportOptions API reference}
  */
 export type VideoExportOptions = {

package/dist/types/exporters/zip/errors.d.ts

@@ -2,7 +2,6 @@ import type { ZIPExportErrorCode } from './types';
 /**
  * Error raised by ZIP frame-sequence validation, capture, or archive creation.
  *
- * @category ZIP frame-sequence export
  * @see {@link https://code.textmode.art/api/textmode.export.js/classes/ZIPExportError | ZIPExportError API reference}
  */
 export declare class ZIPExportError extends Error {

package/dist/types/exporters/zip/types.d.ts

@@ -6,28 +6,24 @@ import type { TXTExportOptions } from '../txt';
 /**
  * File format used for every frame in a ZIP frame-sequence export.
  *
- * @category ZIP frame-sequence export
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ZIPFrameFormat | ZIPFrameFormat API reference}
  */
 export type ZIPFrameFormat = 'png' | 'jpg' | 'webp' | 'svg' | 'json' | 'txt';
 /**
  * Lifecycle state reported by a ZIP frame-sequence export.
  *
- * @category ZIP frame-sequence export
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ZIPExportState | ZIPExportState API reference}
  */
 export type ZIPExportState = 'capturing' | 'finalizing' | 'completed' | 'error';
 /**
  * Machine-readable ZIP export failure category.
  *
- * @category ZIP frame-sequence export
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ZIPExportErrorCode | ZIPExportErrorCode API reference}
  */
 export type ZIPExportErrorCode = 'ZIP_EXPORT_INVALID_OPTIONS' | 'ZIP_EXPORT_ENCODING_UNSUPPORTED' | 'ZIP_EXPORT_TOO_LARGE' | 'ZIP_EXPORT_ABORTED' | 'ZIP_EXPORT_TIMEOUT' | 'ZIP_EXPORT_BUSY' | 'ZIP_EXPORT_DISPOSED' | 'ZIP_EXPORT_FAILED';
 /**
  * Progress information emitted while ZIP frames are captured and archived.
  *
- * @category ZIP frame-sequence export
  * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPExportProgress | ZIPExportProgress API reference}
  */
 export interface ZIPExportProgress {
@@ -65,7 +61,6 @@ export interface ZIPExportProgress {
 /**
  * Options shared by all ZIP frame formats.
  *
- * @category ZIP frame-sequence export
  * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPCaptureOptions | ZIPCaptureOptions API reference}
  */
 export interface ZIPCaptureOptions {
@@ -109,7 +104,6 @@ export interface ZIPCaptureOptions {
 /**
  * Format-specific options forwarded to each existing still exporter.
  *
- * @category ZIP frame-sequence export
  * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ZIPFrameOptionsMap | ZIPFrameOptionsMap API reference}
  */
 export interface ZIPFrameOptionsMap {
@@ -123,7 +117,6 @@ export interface ZIPFrameOptionsMap {
 /**
  * Discriminated options for a deterministic ZIP frame-sequence export.
  *
- * @category ZIP frame-sequence export
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ZIPExportOptions | ZIPExportOptions API reference}
  */
 export type ZIPExportOptions = {

package/dist/types/index.d.ts

@@ -15,30 +15,6 @@
  * or use the built-in export overlay. For recipes and format trade-offs, read
  * the [Exporting guide](/docs/exporting).
  *
- * @categoryDescription Workflow
- * Install the plugin and use the export helpers added to a textmode.js sketch.
- *
- * @categoryDescription Canvas capture
- * Export a still image from the rendered canvas.
- *
- * @categoryDescription GIF export
- * Capture deterministic frames and encode an animated GIF.
- *
- * @categoryDescription Video export
- * Capture deterministic frames and encode MP4 or WebM video with Mediabunny.
- *
- * @categoryDescription ZIP frame-sequence export
- * Capture deterministic PNG, JPEG, WebP, SVG, JSON, or TXT frames in a code-only ZIP archive.
- *
- * @categoryDescription Layer data export
- * Export selected-layer text or vector data as TXT or SVG.
- *
- * @categoryDescription JSON document data
- * Export selected-layer or full-stack document data as JSON.
- *
- * @categoryDescription Overlay
- * Configure and control the built-in export overlay.
- *
  * @showCategories
  */
 import type { TextmodePlugin } from 'textmode.js';
@@ -48,7 +24,9 @@ export type { TextmodeExportAPI, ExportOverlayController } from './types';
 export type { ImageExportOptions } from './exporters/image';
 export type { SVGExportOptions } from './exporters/svg';
 export type { TXTExportOptions } from './exporters/txt';
-export type { JSONExportColorMode, JSONExportOptions, JSONExportTarget, TextmodeDocumentJSON } from './exporters/json';
+export { TEXTMODE_DOCUMENT_FORMAT, TEXTMODE_DOCUMENT_FORMAT_VERSION, TEXTMODE_OBJECT_ROWS_ENCODING } from './document';
+export type { JSONExportTarget, TextmodeDocumentJSON, TextmodeDocumentTarget } from './document';
+export type { JSONExportColorMode, JSONExportOptions } from './exporters/json';
 export type { GIFExportOptions, GIFExportProgress } from './exporters/gif';
 export { ZIPExportError } from './exporters/zip';
 export type { ZIPCaptureOptions, ZIPExportErrorCode, ZIPExportOptions, ZIPExportProgress, ZIPExportState, ZIPFrameFormat, ZIPFrameOptionsMap, } from './exporters/zip';
@@ -57,8 +35,6 @@ export type { LayerExportOptions } from './exporters/base';
 /**
  * Default export plugin instance for the standard textmode.js workflow.
  *
- * @category Workflow
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/variables/ExportPlugin | ExportPlugin API reference}
  */
 export declare const ExportPlugin: TextmodePlugin;

package/dist/types/types.d.ts

@@ -8,48 +8,36 @@ import type { ZIPExportOptions } from './exporters/zip';
 /**
  * Default TXT export fields controlled by the export overlay.
  *
- * @category Overlay
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/TXTOverlayDefaults | TXTOverlayDefaults API reference}
  */
 export type TXTOverlayDefaults = Pick<TXTExportOptions, 'preserveTrailingSpaces' | 'emptyCharacter'>;
 /**
  * Default JSON export fields controlled by the export overlay.
  *
- * @category Overlay
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/JSONOverlayDefaults | JSONOverlayDefaults API reference}
  */
 export type JSONOverlayDefaults = Pick<JSONExportOptions, 'target' | 'pretty' | 'includeMetadata' | 'colorMode'>;
 /**
  * Default image export fields controlled by the export overlay.
  *
- * @category Overlay
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ImageOverlayDefaults | ImageOverlayDefaults API reference}
  */
 export type ImageOverlayDefaults = Pick<ImageExportOptions, 'format' | 'scale'>;
 /**
  * Default SVG export fields controlled by the export overlay.
  *
- * @category Overlay
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/SVGOverlayDefaults | SVGOverlayDefaults API reference}
  */
 export type SVGOverlayDefaults = Pick<SVGExportOptions, 'includeBackgroundRectangles' | 'drawMode' | 'strokeWidth'>;
 /**
  * Default GIF export fields controlled by the export overlay.
  *
- * @category Overlay
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/GIFOverlayDefaults | GIFOverlayDefaults API reference}
  */
 export type GIFOverlayDefaults = Pick<GIFExportOptions, 'frameCount' | 'frameRate' | 'scale' | 'repeat'>;
 /**
  * Default video export fields controlled by the export overlay.
  *
- * @category Overlay
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/VideoOverlayDefaults | VideoOverlayDefaults API reference}
  */
 export type VideoOverlayDefaults = Pick<VideoExportOptions, 'format' | 'frameCount' | 'frameRate' | 'quality' | 'hardwareAcceleration' | 'keyFrameInterval' | 'transparent'>;
@@ -63,8 +51,6 @@ export type VideoOverlayDefaults = Pick<VideoExportOptions, 'format' | 'frameCou
  * {@link ExportOverlayController.getDefaults} and
  * {@link ExportOverlayController.setDefaults}.
  *
- * @category Overlay
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/type-aliases/ExportDefaults | ExportDefaults API reference}
  */
 export type ExportDefaults = {
@@ -88,8 +74,6 @@ export type ExportDefaults = {
  * format's curated defaults. Top-level `format` changes the overlay's selected
  * format. Omitted keys keep their current value.
  *
- * @category Overlay
- *
  * @example
  * ```ts
  * t.exportOverlay.setDefaults({ format: 'image', image: { scale: 2 }, gif: { frameRate: 30 } });
@@ -108,8 +92,6 @@ export type ExportDefaultsPatch = {
  * `auto` means the overlay is using the library default offset from the
  * textmode canvas. `custom` means the user or runtime API has moved it.
  *
- * @category Overlay
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ExportOverlayPosition | ExportOverlayPosition API reference}
  */
 export interface ExportOverlayPosition {
@@ -120,8 +102,6 @@ export interface ExportOverlayPosition {
 /**
  * Canvas-relative placement coordinates for the export overlay UI.
  *
- * @category Overlay
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ExportOverlayPositionInput | ExportOverlayPositionInput API reference}
  */
 export interface ExportOverlayPositionInput {
@@ -131,8 +111,6 @@ export interface ExportOverlayPositionInput {
 /**
  * Controller for managing the export overlay UI visibility at runtime.
  *
- * @category Overlay
- *
  * @see {@link https://code.textmode.art/api/textmode.export.js/interfaces/ExportOverlayController | ExportOverlayController API reference}
  */
 export interface ExportOverlayController {
@@ -282,8 +260,6 @@ export interface ExportOverlayController {
 /**
  * Runtime export helpers that `ExportPlugin` attaches to the `Textmodifier` instance.
  *
- * @category Workflow
- *
  * @example
  * {@includeCode ../examples/ExportPlugin/layerTargets/sketch.js}
  *
@@ -514,8 +490,6 @@ export interface TextmodeExportAPI {
      * @returns A promise that resolves after the archive download is initiated.
      * @throws {Error} When validation, capture, serialization, archive writing, or download fails.
      *
-     * @category ZIP frame-sequence export
-     *
      * @example
      * ```ts
      * await t.saveZip({
@@ -540,8 +514,6 @@ export interface TextmodeExportAPI {
      * @returns The completed `application/zip` blob.
      * @throws {Error} When validation, capture, serialization, archive writing, or cancellation fails.
      *
-     * @category ZIP frame-sequence export
-     *
      * @example
      * ```ts
      * const archive = await t.toZipBlob({ format: 'svg', frameCount: 60, frameRate: 24 });

package/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "textmode.export.js",
-	"version": "1.9.0-beta.1",
+	"version": "1.9.0-beta.2",
 	"description": "Export plugin for textmode.js - Save images, GIFs, videos, SVG, JSON, text, and ZIP frame sequences.",
 	"type": "module",
 	"devEngines": {
 		"runtime": {
 			"name": "node",
-			"version": "^24.0.0",
+			"version": ">=24.0.0",
 			"onFail": "error"
 		},
 		"packageManager": {
@@ -23,6 +23,38 @@
 			"types": "./dist/types/index.d.ts",
 			"import": "./dist/textmode.export.esm.js",
 			"require": "./dist/textmode.export.umd.js"
+		},
+		"./document": {
+			"types": "./dist/types/document/index.d.ts",
+			"import": "./dist/textmode.document.esm.js"
+		},
+		"./schema": {
+			"types": "./protocol/textmode-document/2.0/textmode-document-2.0.schema.d.ts",
+			"default": "./protocol/textmode-document/2.0/textmode-document-2.0.schema.json"
+		},
+		"./document/schema/2.0": {
+			"types": "./protocol/textmode-document/2.0/textmode-document-2.0.schema.d.ts",
+			"default": "./protocol/textmode-document/2.0/textmode-document-2.0.schema.json"
+		},
+		"./document/fixtures/2.0/textmode-document-selected-v2.json": {
+			"types": "./protocol/textmode-document/2.0/fixture.d.ts",
+			"default": "./protocol/textmode-document/2.0/fixtures/textmode-document-selected-v2.json"
+		},
+		"./document/fixtures/2.0/textmode-document-all-v2.json": {
+			"types": "./protocol/textmode-document/2.0/fixture.d.ts",
+			"default": "./protocol/textmode-document/2.0/fixtures/textmode-document-all-v2.json"
+		},
+		"./document/fixtures/2.0/textmode-document-create-integration-v2.json": {
+			"types": "./protocol/textmode-document/2.0/fixture.d.ts",
+			"default": "./protocol/textmode-document/2.0/fixtures/textmode-document-create-integration-v2.json"
+		},
+		"./document/fixtures/2.0/textmode-layer-selected-v1.json": {
+			"types": "./protocol/textmode-document/2.0/fixture.d.ts",
+			"default": "./protocol/textmode-document/2.0/fixtures/textmode-layer-selected-v1.json"
+		},
+		"./document/fixtures/2.0/textmode-layer-all-v1.1.json": {
+			"types": "./protocol/textmode-document/2.0/fixture.d.ts",
+			"default": "./protocol/textmode-document/2.0/fixtures/textmode-layer-all-v1.1.json"
 		}
 	},
 	"sideEffects": [
@@ -30,15 +62,17 @@
 		"./dist/textmode.export.umd.js"
 	],
 	"files": [
-		"dist"
+		"dist",
+		"protocol/textmode-document/2.0"
 	],
 	"scripts": {
 		"prebuild": "npm run clean",
 		"clean": "rm -rf dist",
 		"dev": "textmode-build dev --port 5174 --host",
 		"build:bundle": "textmode-build build",
+		"build:document": "vite build --config vite.document.config.ts",
 		"build:types": "textmode-types build",
-		"build": "npm run build:bundle && npm run build:types",
+		"build": "npm run build:bundle && npm run build:document && npm run build:types",
 		"check": "npm run format:check && npm run lint && npm run lint:markdown && npm run typecheck && npm run docs:check && npm run test && npm run build && npm run types:verify",
 		"docs:links:add": "textmode-docs links add",
 		"docs:api:check": "textmode-docs api-check",
@@ -65,19 +99,21 @@
 	"dependencies": {
 		"fflate": "0.8.3",
 		"gifenc": "^1.0.1",
-		"mediabunny": "1.55.2"
+		"mediabunny": "1.56.1"
 	},
 	"devDependencies": {
-		"@textmode/build": "^0.1.0",
+		"@textmode/build": "^0.1.1",
 		"@textmode/docs": "^0.3.0",
-		"@textmode/lint": "^0.1.0",
+		"@textmode/lint": "^0.1.2",
 		"@textmode/release": "^0.2.0",
-		"@textmode/tsconfig": "^0.2.1",
-		"@types/node": "^24.0.0",
+		"@textmode/tsconfig": "^0.2.2",
+		"@types/node": "^26.4.1",
+		"ajv": "^8.20.0",
+		"ajv-formats": "^3.0.1",
 		"textmode.js": "^0.18.0",
 		"typescript": "^6.0.3",
 		"vite-plugin-css-injected-by-js": "^5.0.2",
-		"vitest": "^4.1.10"
+		"vitest": "^5.0.0"
 	},
 	"keywords": [
 		"textmode",

package/protocol/textmode-document/2.0/SPECIFICATION.md

@@ -0,0 +1,233 @@
+# Textmode document format 2.0
+
+## Status
+
+This document defines `textmode.document` version `2.0.0`. The JSON Schema is
+published beside this specification and through the `textmode.export.js/schema`
+and `textmode.export.js/document/schema/2.0` package subpaths. The schema's
+`$id` is a stable identifier, not a hosted download URL. The runtime codec is
+available from the ESM-only `textmode.export.js/document` subpath. The five
+canonical JSON fixtures in this directory are available through subpaths such
+as `textmode.export.js/document/fixtures/2.0/textmode-document-selected-v2.json`.
+Use the JSON import mechanism required by your runtime or bundler.
+
+The format represents editable cell data. It does not represent final rendered
+pixels, post-processing, an editor project, or authored animation.
+
+## 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 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 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.
+
+For a supported version, consumers ignore unknown ordinary object members.
+They reject unknown values of tagged members such as `format`, `target`, and
+`encoding` because those values change interpretation.
+
+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 the stack order emitted by the producer.
+
+## 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.
+
+A future major format may replace this legacy name with `gridPixelSize`; v2
+semantics must not be changed in place.
+
+## 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. Product-specific policy belongs to the product. For example,
+`create.textmode.art` may accept fewer cells than another document consumer.
+
+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.
+
+Both migrate to the canonical v2 union and return a migration warning. Callers
+may disable legacy decoding.
+
+## JSON Schema and runtime decoder
+
+The JSON Schema describes the portable structure and is suitable for
+documentation and general tooling. The runtime decoder remains authoritative
+for:
+
+- 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.

package/protocol/textmode-document/2.0/fixture.d.ts

@@ -0,0 +1,3 @@
+declare const fixture: unknown;
+
+export default fixture;