@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