git:20261026.76415fe to git:20261029.b8b54c3

---

name: figcraft

description: >

FigCraft is an open-source, pure-Rust, offline interface-design, prototyping and whiteboard app (a

clean-room reimplementation of the Figma Design workflow): frames, auto layout, components,

styles, variables, vector networks, prototyping, Dev Mode and board files, on macOS, Windows,

Linux, FreeBSD and the web. Trigger it whenever the user mentions FigCraft or a `.figcraft` file,

asks what it can or cannot do, which formats it opens or writes, how to script, automate, batch or

headlessly drive it (figcraft-cli, MCP, the JSON control channel), wants assets prepared for a

design file, needs output verified or repaired, or asks to troubleshoot it — and when the app is

not named but the job is one of its jobs: "make a mockup", "design a screen / landing page /

dashboard", "build a design system", "export these frames to PNG/PDF/SVG", "open this .fig or

---

**Verify against your installed version** if the ArtCraft Launcher has auto-updated since. Deep

operational detail — the full CLI, control-channel and MCP tables, live-session commands and the

server — is in `references/automation-surfaces.md`.

# FigCraft

## Overview

FigCraft is a native, offline interface-design and prototyping app written entirely in Rust

## Capabilities (verified)

**Model and editing**

- **Vector networks**: Pen/Pencil, vector edit mode (bend, paint bucket, lasso, cut), shape builder,

`crates/engine/src/vectoredit.rs`, `crates/pathops/src/lib.rs`, `crates/engine/src/shapebuilder.rs`).

- **Paint and effects**: solid and linear/radial/angular/diamond gradients, image fills with

(`crates/color/src/lib.rs`, `crates/render/src/image_profile.rs`).

- **Components and design systems**: mains, instances with per-layer overrides, sets and variants,

(`crates/doc/src/styles.rs`, `crates/engine/src/cmd/variables_io.rs`, `docs/components-parity.md`).

- **Handoff / Dev Mode**: ready-for-dev status with "Changed" detection and Compare against the

marked snapshot **or any saved version** (`dev.compare {version}`), annotations, measurements kept

- **In-file review**: comment threads (replies, @mentions, reactions, resolve), named versions with

- **Data pipelines**: `data.fill` repeats a frame once per data row, optionally per output size and

exporting each copy; with `text.fit` it is a carousel/social-post generator in one command

(`crates/engine/src/datafill.rs`, `docs/mcp.md` › Filling copies with data).

**Formats it opens (verified in code)**

- `.figcraft` — native zip, or a bare `document.json` (`crates/format/src/lib.rs`).

- `.json` — FigCraft document JSON, or the Figma REST API file response (`GET /v1/files/:key`), plus

an optional local-variables JSON and an `images/<imageRef>.*` folder (`crates/format/src/rest`).

- `.svg` — imported as an editable frame; unsupported filters are dropped with a warning

(`crates/svg`, `docs/file-format-parity.md`).

- Images: `.png`, `.jpg`/`.jpeg`, animated `.gif`, `.webp`, `.bmp`, `.tif`/`.tiff`, with embedded ICC

- PDF is **export-only**; there is no PDF import, no HEIC and no video decode.

**Formats it writes**

- `.figcraft` — native zip: `document.json`, `images/<sha256>`, optional `thumbnail.png`, `versions/`,

- `.svg`, `.png`, `.jpg`/`.jpeg`, `.webp`, `.pdf` (`crates/doc/src/props.rs`

`ExportFormat::from_ext`, `apps/figcraft-cli/src/files.rs` `write_doc`).

- `.pdf` — one page per top-level frame, real selectable text, clickable links, bleed/crop marks and

naive CMYK via `--bleed --crop-marks --bleed-marks --cmyk` (`docs/cli.md`, `crates/pdf`).

- `.json` — FigCraft JSON is written by `figcraft-cli convert`/`run --out`, **not** by the app's

Save (Save always writes the native archive; `crates/engine/src/cmd/file.rs` `save_to`).

**Automation surfaces (re-measured at this tag)**

- **`figcraft-cli`** — headless engine with **9 subcommands**: `info`, `export`, `convert`, `render`

(png/jpg/webp), `run` (JSON/JSONL command scripts), `commands`, `mcp`, `plugin publish`, `perf`

(`apps/figcraft-cli/src/main.rs` `USAGE`, `docs/cli.md`). Every subcommand takes

`--no-system-fonts`; `info`/`export`/`convert`/`render`/`run`/`mcp` also take

- **Control channel** — `figcraft --control <port>`, loopback-only, newline-delimited JSON with

**17 methods**: `engine.execute`, `engine.commands`, `document.inspect`, `node.get`, `ui.inspect`,

`ui.pointer`, `ui.key`, `ui.type`, `ui.input`, `ui.menu.invoke`, `ui.set`, `ui.screenshot`,

`ui.render`, `window.new/list/focus`, `app.quit` (`crates/ui-egui/src/control.rs`,

`docs/control-protocol.md`). State methods answer while the window is minimised; methods that need

a drawn frame (`ui.screenshot`, `ui.input`, `window.new`) fail fast (`NEEDS_FRAME`). `ui.set`

- **MCP server** — `figcraft-cli mcp` (headless) or `--attach <port>` (drives the running app);

**18 tools**: `list_commands`, `run_command`, `batch`, `create_node`, `set_properties`,

`inspect_document`, `get_node`, `select`, `export`, `screenshot`, `open_file`, `save_file`,

`undo`, `redo`, `pointer`, `key`, `type_text`, `inspect_ui`; **2 resources + 2 templates**

(`figcraft://document`, `figcraft://commands`, `figcraft://node/{id}`, `figcraft://command/{id}`)

and **4 prompts** (`mobile_screen`, `design_system`, `landing_page`, `prototype_flow`)

- **Live sessions from a script** — **21 `collab.*` commands** cover host/join/share/publish, cursors,

- **Plugins** — sandboxed WebAssembly (wasmi, metered fuel, memory cap, no fs/net/clock), manifest

`design-system`, `wireframe-kit`, `social-posts`, `slides`, `icon-set`) via `template.list` and

- **Discovery is a command**: `figcraft-cli commands --json` (or MCP `list_commands`) prints every

**Platform and runtime facts**

- WebAssembly build: **yes** (`cargo xtask wasm`, `apps/figcraft-web`); the browser build can join but

- Releases package macOS universal, Windows x64/x86/arm64, Linux (AppImage, deb, rpm, Flatpak,

- Crash discipline: no `unwrap`/`expect`/`panic` in shipped code (clippy denies them), a command guard

rolls a panicking command back, and recovery copies are written every 10 s (`Cargo.toml`,

`crates/engine/src/guard.rs`, `apps/figcraft/src/recovery.rs` `INTERVAL`).

- Accessibility: AccessKit names/roles on desktop, F6 cycles toolbar → layers → canvas → properties,

reduced motion honoured (`crates/ui-egui/src/a11y.rs`).

- One process shows several **windows**, each with tabs, panels and canvas; a first run opens the home

## Known limitations and not-implemented

Treat these as hard constraints: **partial** means it exists but is visibly incomplete; the rest are

- **No real-Figma-file validation.** Every `.fig` corpus in the repo is synthetic; import is "best

effort" and nothing has been checked against real documents (`docs/gaps.md` 1 and 3) — do not

promise fidelity. Missing formats: HEIC images and video fills/triggers (no Rust decoder), `.jam`

(FigJam) and `.deck` (Slides) out of scope (`docs/file-format-parity.md`).

- **No AI features at all** and **no spell check** (`docs/gaps.md` 11 and 19).

- **Multiplayer is a preview**: live sessions with sync, cursors, selections, text carets, cursor

- **Prototype tail**: no media triggers/actions; controller buttons are read on Windows and in the

browser but not on macOS, Linux or FreeBSD (`docs/prototyping-parity.md`).

- **Dev Mode tail**: publishing mappings from a code repository and the editor extension are missing;

the component playground has no slot control (`docs/dev-mode-parity.md`, `docs/gaps.md` 16).

- **CPU canvas, sRGB screen**: Display P3 documents show sRGB-clipped with a gamut warning and

soft-proof striping (true P3 is blocked upstream in egui-wgpu) (`docs/hardware-parity.md`).

- **Export limits**: SVG and PDF refuse a tree deeper than 256 descendant levels rather than writing

an incomplete file, and `--cmyk` is the naive `K = 1 − max(R,G,B)` conversion — DeviceCMYK without

an output intent, so proof against your printer's profile (`docs/file-format-parity.md` › Export,

`docs/gaps.md` 23).

- **Screen readers have never been run** against the app; the browser build has no accessibility

tree, and Linux/browser platform QA is still open (`docs/gaps.md` 22 and 8).

- **Bounds worth knowing**: ≤100 versions and ≤100 branches per file; `document.json` is capped by a

16× compression-ratio rule within 512 MiB per zip member (4 GiB unpacked on 64-bit, 1 GiB on

32-bit) (`crates/format/src/lib.rs` `MAX_VERSIONS`, `MAX_BRANCHES`, `DOCUMENT_RATIO`, `MAX_MEMBER`).

## How to operate

**Launch.** Installed app: `/Applications/FigCraft.app`; `open -a FigCraft [file.figcraft]` opens a

file. The bundle declares the `figcraft` document type, SVG, PNG and JPEG types and the

`figcraft://` URL scheme; identifier `ai.storyteller.figcraft` (`packaging/macos/Info.plist.in`,

`/Applications/FigCraft.app/Contents/Info.plist`). To pass flags, run the binary directly:

```sh

"/Applications/FigCraft.app/Contents/MacOS/FigCraft" --control 7979 WORK/project/app.figcraft

"/Applications/FigCraft.app/Contents/MacOS/FigCraft" --control 7979 \

--automation-read-root WORK/project --automation-write-root WORK/project/out

```

`--control <port>` starts the loopback JSON-lines control server (or set

`FIGCRAFT_CONTROL_PORT`); `--automation-read-root` / `--automation-write-root` (repeatable) confine

every file the channel and windows may read or write; any unknown option — including a mistyped root

flag — stops the app at startup instead of running unconfined (`apps/figcraft/src/args.rs`,

`apps/figcraft/src/main.rs`, `docs/control-protocol.md`). An invite link (`figcraft://join?…`) or a

`file://` URL on the command line opens or joins it.

**There is no CLI inside the macOS bundle.** The GUI app is the only binary in

`/Applications/FigCraft.app/Contents/MacOS/`. Build it with `cargo build --release -p figcraft-cli` →

`target/release/figcraft-cli`; macOS releases ship a separate `figcraft-cli-<version>-macos-<arch>.zip`

(`packaging/macos/package.sh`). On Linux only, `FigCraft.AppImage cli <args>` runs it (`packaging/linux/AppRun`).

**CLI surface** (verified in `apps/figcraft-cli/src/main.rs`, `docs/cli.md`):

```sh

figcraft-cli info app.figcraft [--json] # + missingFonts per file

figcraft-cli export app.figcraft -o exports/ --scale 2 # one file per top-level frame

figcraft-cli export app.figcraft -o hero.svg --node "Hero"

figcraft-cli export app.figcraft -o screens.pdf --page "Screens"

figcraft-cli render app.figcraft -o page.png --scale 2 # png, jpg or webp out

figcraft-cli run build.json --in base.figcraft --out result.figcraft

figcraft-cli commands --filter autoLayout [--json]

```

Every subcommand takes `--no-system-fonts` (or `FIGCRAFT_NO_SYSTEM_FONTS=1`) for reproducible

renders. Exit codes: bad arguments 2, failures 1, success 0 (`--help`/`-h` 0). `--scale` ≤64; pages

shrink to fit 16384 px on `render`; PDF bleed ≤2 in. `export` to a directory writes one file per

top-level frame; an image extension, or `--node`, writes one file. PDF print options

(`--bleed 3mm --crop-marks --bleed-marks --cmyk`) also work.

**Document model.** One process shows several **windows**, each with its own **tabs**, panels and

canvas (`window.new`); a first run opens the **home screen** (Recents, Online, Templates, search).

Files are documents with pages and per-tab unsaved changes. A `.figcraft` also carries a **kind**:

`design` (default) or `board` (`crates/doc/src/board.rs` `FileKind`). Boards get a bottom toolbar,

no Design panel by default and a contextual bar above the selection, and refuse prototyping/Dev

Mode; design files refuse the `board.*` commands.

(`crates/engine/src/cmd/file.rs`); `pref.autoSave` also auto-saves files that have a path.

**Keyboard shortcuts**: do not invent them. The machine-readable list is `figcraft-cli commands

--json` (each command's `shortcut`) or MCP `list_commands`, generated from

`crates/engine/src/keymap.rs` — **159 default bindings in 12 groups** (Essential, Tools, View, Zoom,

Text, Shape, Selection, Edit, Transform, Arrange, Components, Prototype) with macOS and, where they

## Working with an AI agent

What an agent can legitimately do:

- **Drive the app headlessly.** `figcraft-cli run` a JSON array (or `.jsonl`) of

- **Drive the running app** so the user watches: start it with `--control PORT`, then

`figcraft-cli mcp --attach PORT` (MCP tools) or speak the JSON-lines protocol directly. Attached

calls are **never replayed** after a transport failure — inspect before retrying an edit

- **Confine it.** Pass `--automation-read-root` / `--automation-write-root` to the app, `figcraft-cli

mcp`, or any `info`/`export`/`convert`/`render`/`run` run. Writes need a write root; reads need

either; `--attach` plus roots is a usage error (`docs/mcp.md` › Confining file access).

- **Prepare inputs.** Generate or convert assets into formats FigCraft reads: SVG (best editable

import), PNG/JPG/WebP/GIF/TIFF/BMP. For real Figma work the highest-fidelity path is the REST API

file JSON plus its local-variables JSON plus an `images/<imageRef>.png` folder — the importer reads

- **Generate batches.** `data.fill` + `text.fit` turn one frame and a JSON list of rows into a

carousel or a set of post sizes with the text fitted — no per-copy editing loop

(`crates/engine/src/datafill.rs`, `docs/mcp.md` › Filling copies with data).

- **Inspect and repair native files** (cautiously). A `.figcraft` is a plain zip:

`unzip -p f.figcraft document.json` reads the whole model, `images/<sha256>` holds raw image bytes,

and `versions/index.json` / `branches/index.json` hold history. Reading is lenient (structural

problems are repaired and reported) but a newer format version is refused

(`FormatError::Newer`). Prefer repairing through commands (`document.inspect`, `node.set`,

`node.get`); if you must hand-edit, keep `format`/`version` and re-zip the *entire* member set.

- **Verify output.** `figcraft-cli info <file> --json` for structure, notes and missing fonts;

re-open an export (`convert` back to `.figcraft`) to prove it decodes; compare a PNG export at a

known `--scale` against a `ui.render`; for `.fig` output, re-open it in FigCraft and read the

`warnings` list.

- **Contribute safely**: FigCraft forbids third-party product iconography or images — never add or

redraw Figma/Adobe assets, and every asset needs a row in `ATTRIBUTION.md` (`AGENTS.md`).

What an agent must **not** do:

- Do not automate the GUI by clicking blind: use the control channel (`ui.pointer`, `ui.key`,

`ui.input`, `ui.menu.invoke`, `ui.set`) or commands; programmatic calls never open dialogs.

`ui.screenshot`, `ui.input` and `window.new` need a visible window (`docs/control-protocol.md`).

- Do not assume a Figma format or feature works. No video fills, no HEIC, no `.jam`/`.deck`, no Figma

- Do not treat the browser build as equivalent: it can join but not host sessions, keeps one window,

has no system fonts and no accessibility tree; Display P3 is sRGB-clipped on screen.

- Do not put prototyping or board work in the wrong file kind: `proto.*`/`dev.*` refuse on boards and

- Do not share to a server uninvited: `collab.share` with `via: "online"` (its default) **publishes

the document to a server other people run** — only call it when sharing is the request.

- Do not send huge inspection results: MCP responses are capped at 8 MiB by default (`maxBytes`); ask

for a shallower `depth`, a `get_node` `offset`, or read the document in pieces

(`crates/mcp/src/tools.rs` `MAX_RESPONSE`).

## Verification protocol

FigCraft is alpha; treat every automated run as untrusted until checked:

1. **Throwaway round trip per session.** From a template (`file.newFromTemplate`) or a copy: create →

edit → `save_file`/`--out` to `.figcraft` → reopen → export PNG/PDF. Compare `info` node counts

before and after; a decoder that only reads what it wrote is how the repo tests `.fig` export.

2. **Never trust a silent export.** Watch stderr: exports and imports print `note:` lines for what was

3. **Version and back up project files.** Ask for the user's document to be committed or copied before

a batch of automated edits; version history (≤100 versions), branches, auto-save and 10-second

recovery copies are safety nets, not backups.

4. **Update between projects.** A `.figcraft` written by a newer format version is refused by an older

one, and a board relies on the `kind` field that older builds do not know — verify the file's kind

and boards after any downgrade, before trusting a batch run on it.

5. **Scope credentials and sharing.** Live sessions and servers are previews with code/link access and

no accounts; don't put confidential work on a server you don't run, and the public server keeps the

file until removed or 30 days unopened (`README.md` › Privacy and online sharing).

## References

- `references/automation-surfaces.md` — command/MCP/control-channel/CLI detail for large jobs: tool and

## Sources & evidence

- Key files read: `README.md`, `Cargo.toml`, `ROADMAP.md`, `AGENTS.md`; `crates/doc/src/` (`node.rs`,

`props.rs`, `proto.rs`, `styles.rs`, `board.rs`, `lib.rs`); `crates/{color,layout}/src/lib.rs`;

`crates/format/src/{lib,library}.rs` and `crates/format/src/fig/{export,kiwi}.rs`;

`apps/figcraft/src/{main,args,recovery}.rs`; `apps/figcraft-server/src/{cli,config}.rs`;

`crates/ui-egui/src/{control,windows,home,a11y,board_bar,present}.rs`;

- Docs read (counts re-checked against code where stated): `docs/{cli,mcp,control-protocol,file-format-parity,gaps,target-app-parity,boards-parity,dev-mode-parity,prototyping-parity,components-parity,collaboration-parity,localization-parity,hardware-parity,ui-parity,auto-layout-parity,plugins,parity-checklist,architecture}.md`.