io-grida

# Grida I/O — `.grida` Format & Loading (TS side) ## Format Overview Grida uses **FlatBuffers** as the canonical binary format. File identifier: `"GRID"`. Two on-disk variants: | Variant | Detection | Notes | | --------------- | --------------------- | ---------------------------------------------- | | Raw FlatBuffers | `"GRID"` at bytes 4–7 | Bare document, no images | | ZIP archive | ZIP magic bytes | `manifest.json` + `document.grida` + `images/` | **Document model**: Flat node repository (not nested). Nodes reference parents via ID + fractional-index position strings. Multi-scene: each Figma page → a `SceneNode`. ## Key Locations | Path | Role | | --------------------------------------- | -------------------------------------------------------- | | `packages/grida-canvas-schema/grida.ts` | TS runtime types (`grida` namespace) + `SCHEMA_VERSION` | | `packages/grida-canvas-io/` | TS file loading, archive pack/unpack, clipboard protocol | | `packages/grida-format/src/` | **FROZEN** flatc TS bindings (tombstone — see below) | The **schema source of truth and the Rust decoder** live in the engine repo: [`format/grida.fbs`](https://github.com/gridaco/nothing/blob/main/format/grida.fbs) · [`crates/grida/src/io/`](https://github.com/gridaco/nothing/tree/main/crates/grida/src/io). ## TS Side — `packages/grida-canvas-io/` - **`io.load(file)`** — auto-detects format, decodes, extracts images → `LoadedDocument` - **`io.is_grid(bytes)`** — checks `"GRID"` identifier - **`io.archive.pack/unpack`** — ZIP with `manifest.json` - **`io.clipboard.encode/decode`** — Grida clipboard protocol ## The tombstone — `packages/grida-format` The generated TS FlatBuffers bindings are **committed and frozen**: the flatc generator wiring was deleted at the engine split (this repo has no `format/grida.fbs` and no `bin/activate-flatc`). The bindings are byte-identical to pinned flatc v25.12.19 output and the formatter/linter ignore them to keep it that way. **Do not edit them.** If the schema evolves in the engine repo and this reader should follow, re-snapshot deliberately from a gridaco/nothing checkout. ## Verification ```sh pnpm turbo test --filter='@grida/io' pnpm turbo typecheck --filter='@grida/io' --filter='@grida/canvas-schema' ``` ## Schema Changes Schema evolution happens **in the engine repo** (see its io-grida skill and [`format/AGENTS.md`](https://github.com/gridaco/nothing/blob/main/format/AGENTS.md)). What this repo owes on a breaking change — **a cross-REPO lockstep**: 1. TS: bump `grida.program.document.SCHEMA_VERSION` in `packages/grida-canvas-schema/grida.ts` to match the engine's `SCHEMA_VERSION` in [`crates/grida/src/io/io_grida_fbs.rs`](https://github.com/gridaco/nothing/blob/main/crates/grida/src/io/io_grida_fbs.rs) — **exactly in sync**; both writers must emit the same version string. 2. Re-snapshot the frozen bindings from the new schema (deliberate act, see above). 3. Old files are **rejected** by the TS reader (`format.ts` calls `isSchemaCompatible()` and throws on mismatch). **Version compatibility logic** (`isSchemaCompatible` in `grida-canvas-schema/grida.ts`): - While MAJOR=0: same `MAJOR.MINOR` required (e.g. `0.91.*` accepts `0.91.*`, rejects `0.90.*`) - Once MAJOR≥1: same MAJOR required (standard semver) Format: `MAJOR.MINOR.PATCH-prerelease+build` (e.g. `"0.91.0-beta+20260311"`). Note: the TS FlatBuffers decoder is more lenient than the Rust verifier — a TS-side round-trip may pass on structurally invalid bytes. For byte-level verification, use the engine repo's Rust verifier.