# 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

```sh
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](LICENSE).