format-lab/README.md

Format Lab

Explore conversion paths, state the expected preservation boundary, and measure what a representative round trip actually changes. Format Lab is a local-first module in the add·ideas Toolbox.

v0.2.0 capabilities

• Browse directed format graphs for structured data, images, audio/video, and subtitles
• Choose the properties that matter and rank bounded paths by expected loss, conditional behaviour, unknowns, and conversion count
• Inspect every edge's availability and explicit caveat; routes are never called lossless merely because no catalog loss is known
• Execute JSON, NDJSON, CSV, and a typed XML record-dialect conversion path over a bounded canonical dataset
• Convert back to the source format and measure record/field order, names, scalar types, nulls, nested values, numbers, and Unicode text
• Display catalog expectations beside measured evidence and mark metadata as untested when it is outside the canonical model
• Export the target data and a deterministic evidence report containing the catalog version, exact path, expectations, measurements, and notices
• Export a versioned portable evidence contract shared with other audit tools, inspect a broad masked-offset file-signature catalog, and download a deterministic edge-case corpus as individually named fixtures plus manifest

Honest scope

The image, audio/video, and subtitle graphs are planning contracts linked to the specialized Toolbox apps; v0.2.0 does not duplicate their codec or renderer engines. Catalog statuses are conservative expectations, not measurements of a particular file or encoder. The executable data lab supports records only—not arbitrary JSON documents, XML mixed content/namespaces, or an external CSV type schema. Its typed XML output is a documented lab interchange dialect.

Inputs are capped at 2 MiB, 10,000 records, 200 fields per record, 500,000 top-level values, and 8 MiB output. CSV cells are strings and spreadsheet-formula prefixes are neutralized; the resulting semantic change is visible in the round-trip measurement. Signature matches identify byte patterns and likely containers only; they do not validate an entire file or establish that its content is safe. Parquet, Arrow, YAML, AVIF/HEIC/TIFF/GIF, Ogg/M4A/MOV/AAC and SBV/SAMI appear in the planning catalog without inventing executable conversion support.

Development

npm ci
npm run check
npm run test:browser

npm run release:artifact produces a deterministic ZIP and SHA-256 sidecar.

License

GPL-3.0-or-later. See LICENSE.