@textmode/document 4.0.0

This release defines textmode.document@4.0.0 and updates @textmode/document to package version 4.0.0. The package and document format versions now align.

Highlights

• Adds complete, ordered frame snapshots for still artwork and animation. Each frame has a positive duration in milliseconds and a complete bottom-to-top layer stack. A frame with no layers represents a blank interval.
• Adds the v4 specification, JSON Schema, TypeScript types, decoder support, and consumer documentation.
• Returns one canonical v4 shape for every supported input. The decoder reads textmode.document versions 2.0, 3.0, and 3.1, plus textmode.layer versions 1.0 and 1.1. Older documents migrate to one 100 ms frame and return migration warnings.
• Enforces frame, per-frame layer, total layer, cell, and cumulative duration limits. It rejects duplicate IDs in native v4 frames and repairs duplicate IDs in historical inputs with LAYER_ID_REASSIGNED warnings.
• Adds the schema package subpath @textmode/document/schema/4.0. The v2, v3.0, and v3.1 schema exports remain available.
• Keeps optional font references and the font identity helper at @textmode/document/font. Font references identify a font; they do not embed font data.

Compatibility note

This release changes the decoder result shape. Read result.document.frames instead of result.document.layers. There is no root layers alias. A still document has one frame. Historical inputs decode as one 100 ms frame.

Animation consumers must handle frame-local layer stacks, blank frames, changing layer order, fractional millisecond durations, and grids or fonts that can change between frames. maxLayers now applies to each frame. Set maxFrames and maxTotalLayers to configure the new frame and document-wide layer budgets. Handle LAYER_ID_REASSIGNED warnings when importing older files.

Update and deploy compatible readers before you enable v4 writers. Do not silently drop frames, round durations, or change unsupported presentation data. See the migration guide for consumer-specific requirements and the recommended rollout order. The package does not rewrite files on disk.

Install

npm install @textmode/document@4.0.0

The package requires Node.js 24 or later and uses ESM.

Documentation

• Consumer guide
• Format 4.0 specification
• Format 4.0 visual guide
• Format 4.0 migration and release guide
• Format 3.1 specification
• Format 2.0 reference
• CC0 1.0 Universal license

@textmode/document 2.0.0

The package now defines textmode.document@3.1.0, with optional font references on layers and a stable way to identify supported SFNT fonts. Package versions and document format versions are independent.

Highlights

• Adds the format 3.1 specification, JSON Schema, TypeScript declarations, and consumer documentation.
• Adds an optional font reference to each layer. The reference stores a normalized font identity and may include a display name. It does not embed font data or require a local font match during decoding.
• Adds identifySfntFont(bytes) from @textmode/document/font. It identifies standalone TTF and OTF data with a full SHA-256 identity. It validates SFNT table bounds and applies size and table-count limits. WOFF decoding is not included.
• Keeps decoding support for format 3.0, format 2.0, and textmode.layer@1.0.0 / textmode.layer@1.1.0 inputs. Older documents migrate to canonical format 3.1 data and return migration warnings.
• Adds the schema package subpath @textmode/document/schema/3.1. The format 3.0 schema remains unchanged.

Compatibility note

The decoder now returns canonical documents with formatVersion: "3.1.0". If your application checks this value or depends on the exact shape of decoder output, update that code. Format 3.0 input remains supported and is migrated to 3.1. The package does not rewrite files on disk.

The font identity helper is an optional entry point. The root decoder remains independent of font hashing code; importing @textmode/document/font uses the @noble/hashes runtime dependency.

Install

npm install @textmode/document@2.0.0

The package requires Node.js 24 or later and uses ESM.

Documentation

• Consumer guide
• Format 3.1 specification
• Format 3.1 visual guide
• Format 2.0 reference
• CC0 1.0 Universal license

@textmode/document 1.1.0

This is the first public GitHub release of @textmode/document.

The npm package version is 1.1.0. The document format defined by this package is textmode.document@3.0.0; package and format versions are independent.

Highlights

• Defines a portable, versioned JSON format for textmode artwork.
• Includes the v3 specification, versioned JSON Schemas, TypeScript types, and a dependency-free ESM decoder for browsers and Node.js.
• Decodes v3 documents, supported v2 documents, and textmode.layer@1.0.0 and textmode.layer@1.1.0 files into canonical v3 data.
• Reports structured validation errors and migration warnings, and supports configurable resource limits.

Install

npm install @textmode/document@1.1.0

The package requires Node.js 24 or later. Its ESM decoder has no runtime dependencies.

Documentation

• Consumer guide
• Format 3.0 specification
• Format 2.0 reference
• CC0 1.0 Universal license