Skip to content

AI-native design editor. Open-source Figma alternative.

4.3 KB
Raw Blame

Fig and Kiwi

@open-pencil/kiwi owns Kiwi schema, runtime, codecs, containers, and parse helpers without SceneGraph knowledge. @open-pencil/fig owns complete .fig archive parsing, SceneGraph conversion, metadata policy, component/instance interpretation, and the Figma clipboard format. Core owns format-neutral orchestration, runtime fonts and workers, and thumbnails.

  • Keep Kiwi runtime changes minimal; put project policy in wrappers, not in the runtime.
  • A schema is compiled once into tables, compileSchema(schema).schema, and decoding, skipping, encoding, the page manifest scan, and record patching all read fields through them; do not add another type switch or name lookup over Kiwi values (packages/kiwi/tests/compiled-schema.test.ts).
  • Figma clipboard envelope encoding, decoding, and bounds belong to @open-pencil/fig/clipboard; converting those records to a SceneGraph is materializeFigFragment in packages/fig/src/document/fragment.ts, which Core drives from packages/core/src/clipboard/fig-import.ts. Core prepares runtime fonts and text and owns editor placement and history; browser and Tauri adapters own system clipboard I/O. Do not add platform clipboard APIs here.
  • One reader serves every .fig path — parse, worker, page population, session recovery, export, and paste — through the document sessions in packages/fig/src/document/. Read what it could not resolve with readerDiagnostics(graph) from packages/core/src/kiwi/fig/session/document-state.ts; do not add a second import path.
  • A generated frame's .fig record carries its sublayers as nodeGenerationData and their derived geometry. Each generated type registers a GeneratedFrameCodec that reads and writes them in packages/fig/src/node-change/generated/codecs.ts; the import and export dispatch through it and never test node types (packages/fig/tests/node-change/generated/codecs.test.ts).
  • .fig document data is written with Zstd at the document's figCompression level: build_fig_file in desktop/ on Tauri, loadFigDataCompressor from @open-pencil/kiwi/fig/container elsewhere, which is Bun's Zstd or a WebAssembly build. Figma rejects a Zstd frame that does not declare its decompressed size, so every encoder must write it (packages/kiwi/tests/container.test.ts).
  • Reading uses the same Zstd through the synchronous decompressFigKiwiData, which needs loadFigDataDecompressor awaited once per thread outside Bun: parseFigFile and the session worker do that, so page recovery and archive patches on either thread never wait (packages/kiwi/tests/container.test.ts).
  • Saving a document opened from a .fig writes only the fields its edits changed, merged into the archive's records, and copies the rest as bytes (packages/core/src/io/formats/fig/export/patch/, patchFigMessage in packages/fig/src/record-patch/); the full export remains for documents with no archive. A change is what the archive tracker sees outside page loads and outside applyDerivedLayoutDuring, which wraps layout derived from the file or its fonts; layout an edit causes counts, and the tracker keeps each edited layer as it was so the fields are found by comparing records (packages/core/tests/io/formats/fig/export/patch/).
  • Changes to .fig behavior require round-trip validation in Figma. packages/docs/development/roadmap.md tracks raw metadata coverage and the code map for import/export mapping and schema files.
  • Measure a reader change over a whole archive, not one frame: capture before and after with visual-oracles compare digest --file F --out baseline.json then --baseline baseline.json, and account for every node it reports. compare interpreted-document checks one frame against live Figma and will report no change while a rule breaks pages it does not cover.
  • A rule about Figma's override or binding semantics holds only where it was observed. Before encoding one, find a second archive or frame that exercises it and confirm the outcome in live Figma; several plausible rules here fit one file and are contradicted by the next.
  • Fixtures under tests/fixtures/*.fig use Git LFS; use a normal git push when they change, and git push --no-verify to skip the LFS hook otherwise.
  • Tests address the package by alias rather than drilling: #fig/* for source, #fig-tests/* for shared test helpers, both registered in tools/checks/architecture/src/steiger-rules/support.ts.