@textmode/document 0.0.0-stage → 1.1.0

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,87 @@
 {
-  "name": "@textmode/document",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@textmode/document",
+	"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)",
+	"type": "module",
+	"sideEffects": false,
+	"devEngines": {
+		"runtime": {
+			"name": "node",
+			"version": ">=24.0.0",
+			"onFail": "error"
+		},
+		"packageManager": {
+			"name": "npm",
+			"version": "^11.0.0",
+			"onFail": "error"
+		}
+	},
+	"engines": {
+		"node": ">=24"
+	},
+	"packageManager": "npm@11.16.0",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./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": [
+		"dist/**/*.js",
+		"dist/**/*.d.ts",
+		"schemas/2.0/schema.json",
+		"schemas/2.0/schema.d.ts",
+		"docs/*.md",
+		"schemas/3.0/schema.json",
+		"schemas/3.0/schema.d.ts"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/humanbydefinition/textmode-document.git"
+	},
+	"bugs": {
+		"url": "https://github.com/humanbydefinition/textmode-document/issues"
+	},
+	"homepage": "https://github.com/humanbydefinition/textmode-document#readme",
+	"scripts": {
+		"clean": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\"",
+		"build": "npm run clean && tsc -p tsconfig.build.json",
+		"format": "textmode-lint format",
+		"format:check": "textmode-lint format:check",
+		"lint": "textmode-lint lint src tests && node --check scripts/check-package.mjs",
+		"lint:markdown": "textmode-lint lint:markdown",
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"docs:check": "textmode-docs check",
+		"docs:build": "textmode-docs build",
+		"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",
+		"prepare": "npm run build"
+	},
+	"devDependencies": {
+		"@textmode/docs": "^0.3.0",
+		"@textmode/lint": "^0.1.2",
+		"@textmode/tsconfig": "^0.2.2",
+		"@types/node": "^26.4.1",
+		"ajv": "^8.20.0",
+		"ajv-formats": "^3.0.1",
+		"typescript": "^6.0.3",
+		"vitest": "^5.0.0"
+	},
+	"prettier": "@textmode/lint/prettier"
+}

package/schemas/2.0/schema.d.ts

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

package/schemas/2.0/schema.json

@@ -0,0 +1,357 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://textmode.art/schemas/textmode-document-2.0.schema.json",
+	"title": "Textmode document 2.0",
+	"description": "Editable textmode cell snapshots and layer stacks.",
+	"oneOf": [
+		{
+			"$ref": "#/$defs/selectedDocument"
+		},
+		{
+			"$ref": "#/$defs/allDocument"
+		}
+	],
+	"$defs": {
+		"positiveSafeInteger": {
+			"type": "integer",
+			"minimum": 1,
+			"maximum": 9007199254740991,
+			"description": "Positive integer in the interoperable JavaScript safe range."
+		},
+		"canvas": {
+			"type": "object",
+			"required": ["width", "height"],
+			"properties": {
+				"width": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Width in pixels; the decoder checks equality with the corresponding grid product."
+				},
+				"height": {
+					"$ref": "#/$defs/positiveSafeInteger",
+					"description": "Height in pixels; the decoder checks equality with the corresponding grid product."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Legacy grid pixel extent. For selected documents this equals the grid extent; for all documents it equals the first layer grid extent. It is not a composite viewport. See docs/specification-2.0.md#canvas-field."
+		},
+		"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-2.0.md#cell-encoding."
+		},
+		"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."
+		},
+		"selectedLayer": {
+			"type": "object",
+			"required": ["id", "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."
+				},
+				"cells": {
+					"$ref": "#/$defs/cells",
+					"description": "Complete dense cell rows."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Informational source ID and cells. A selected snapshot does not carry layer presentation or font identity."
+		},
+		"stackLayer": {
+			"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 ordered layer with independent grid, cells, and presentation values."
+		},
+		"selectedDocument": {
+			"type": "object",
+			"required": ["format", "formatVersion", "target", "canvas", "grid", "layer"],
+			"properties": {
+				"format": {
+					"const": "textmode.document",
+					"description": "Required format discriminator."
+				},
+				"formatVersion": {
+					"const": "2.0.0",
+					"description": "On-disk format version, independent of package versions."
+				},
+				"target": {
+					"const": "selected",
+					"description": "Shape discriminator: selected uses layer and root grid; all uses layers."
+				},
+				"metadata": {
+					"$ref": "#/$defs/metadata",
+					"description": "metadata"
+				},
+				"canvas": {
+					"$ref": "#/$defs/canvas",
+					"description": "Legacy grid pixel extent, not the final canvas or a composite viewport."
+				},
+				"grid": {
+					"$ref": "#/$defs/grid",
+					"description": "Grid dimensions and cell metrics."
+				},
+				"layer": {
+					"$ref": "#/$defs/selectedLayer",
+					"description": "One cell snapshot."
+				}
+			},
+			"additionalProperties": true,
+			"description": "Selected cell snapshot. All listed properties except metadata are required."
+		},
+		"allDocument": {
+			"type": "object",
+			"required": ["format", "formatVersion", "target", "canvas", "layers"],
+			"properties": {
+				"format": {
+					"const": "textmode.document",
+					"description": "Required format discriminator."
+				},
+				"formatVersion": {
+					"const": "2.0.0",
+					"description": "On-disk format version, independent of package versions."
+				},
+				"target": {
+					"const": "all",
+					"description": "Shape discriminator: selected uses layer and root grid; all uses layers."
+				},
+				"metadata": {
+					"$ref": "#/$defs/metadata",
+					"description": "metadata"
+				},
+				"canvas": {
+					"$ref": "#/$defs/canvas",
+					"description": "Legacy grid pixel extent, not the final canvas or a composite viewport."
+				},
+				"layers": {
+					"type": "array",
+					"minItems": 1,
+					"items": {
+						"$ref": "#/$defs/stackLayer"
+					},
+					"description": "Nonempty ordered layer stack, bottom first."
+				}
+			},
+			"additionalProperties": true,
+			"description": "One or more layers in bottom-to-top order. The decoder applies cumulative cell and layer budgets."
+		}
+	}
+}

package/schemas/3.0/schema.d.ts

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