vectorcraft · git:20261101.18741c7 · 2026-11-01 · sha256 2594bf1b3eec8b9e
vectorcraft git:20261101.18741c7A
Immutable. This exact content never changes and is served at /api/v1/blob/2594bf1b3eec8b9e.
---
name: vectorcraft
description: >-
VectorCraft is a free, open-source, pure-Rust vector illustration app — a clean-room
reimplementation of Adobe Illustrator for macOS, Windows, Linux, FreeBSD and the web (WASM) —
with an MCP server (33 tools), a JSON control channel (29 methods), a browser JS API (9 calls)
and a headless CLI (7 subcommands). Use this skill whenever the user mentions VectorCraft (or
"the vector app", a `.vectorcraft` / `.drawcraft` / `.vctemplate` file, or the ArtCraft vector
tool), asks what it can do, which formats it opens/saves/exports, its CLI flags, control or MCP
tools, or its keyboard shortcuts; wants to create, edit, automate, script, batch-convert or
export vector art with it; needs assets prepared for it (SVG/PDF/EPS/DXF/PSD/rasters/fonts/
`.wasm` plug-ins); wants its output verified or repaired; or troubleshoots it — even when the
app is not named but the job is Illustrator-style vector work ("draw a logo", "make an SVG",
"edit this .ai", "trace this bitmap", "convert this DXF"). Not for Adobe Illustrator itself.
---
# VectorCraft
Audit basis: this checkout is tag `v0.19.0`, commit `bcebabe3f8c23a376ac68e9e6726590af278f7bb` ("Release 0.19.0", 2026-10-31). The installed `/Applications/VectorCraft.app` still reports version `0.18.0` (`CFBundleIdentifier ai.storyteller.vectorcraft`) and its binary prints `vectorcraft 0.18.0` — **the installed bundle lags this tag.** **Verify against your installed version** before relying on behaviour added in 0.19.x.
v0.18.0 → v0.19.0 is a **large UX/parity wave with no registry change** (control methods still 25; `object.showAll`/`object.unlockAll` merely re-wrapped to multiline registrations; MCP tools unchanged). Highlights: **Add-ons ▸ Arrange Tools** — Arrange in Grid, Swap, Replace with Top Object, Set Size of Each, Zoom to Selection; **Smooth: the slider smooths bumps and jags into curves, and smooths only a direct-selected section**; **Optical kerning** spaces characters by their shapes; **JPEG 2000 images open and place**; **Export for Screens: Export PDFs As Single file** writes artboards as one PDF's pages and the dialog is laid out as Illustrator's; **Intertwine** arranges by id without a selection and a right-click where 3+ objects overlap arranges the nearest one; **Eyedropper Shift-click samples a pattern's or gradient mesh's colour**; Symbols and Brushes **Delete asks first, Alt-click deletes without asking** (plural forms per language); **PDF/EPS export flattens pattern tile images** (see-through/colorized tiles, object limits respected, spot inks preserved in gradient mixes); Batch **data-set naming** by File + Number / File + Data Set Name / Data Set Name; Objects on Path gained an options dialog with Pivot/Rotate; the Mesh tool adds lines from just outside on an edge; Caps Lock gives drawing tools the crosshair; Tab skips window/dialog/panel-grip/ruler drag regions; and the brush warp engine grew substantially (`crates/brush/src/warp.rs`). No `references/` directory ships with this skill: everything below is cited inline to the repo, and `evidence.md` holds the claim → path map.
## Overview
VectorCraft is a clean-room, open-source reimplementation of the Adobe Illustrator workflow, written from scratch in pure Rust (`README.md`). It runs natively on macOS, Windows, Linux and FreeBSD and in the browser via WebAssembly (`apps/vectorcraft-web/`). Maturity: **alpha** — the parity doc self-assesses ~88% feature breadth (353/375 menu items wired, 89/92 tools, 44/50 Illustrator effects, 57/57 Photoshop-style effects, 4/4 initial 3D types), ~75% depth and ~62% ready for real work; `ROADMAP.md` still prints older counts (348/375, 46/50), so treat percentages as self-assessed and the code as authoritative. Source: GitHub `storytold/vectorcraft`. Every user-visible action is a command reachable over MCP, the JSON control channel, the browser API and the CLI (`AGENTS.md`; `docs/mcp.md`; `docs/control-protocol.md`). The UI migrated to egui 0.37 with craft-ui's shared docking in this release (floating panels live in OS windows).
Project rules that bind anyone working in or around the repo: never run, script or copy from Adobe applications (clean-room, `AGENTS.md`); no panics in shipped code (clippy-denied, plus `crates/engine/src/guard.rs`); every bundled asset is attributed in `ASSETS.md`.
## Capabilities (verified)
### Automation surface at a glance
| Surface | Count at v0.18.0 | Change vs the v0.17.0 skill |
|---|---|---|
| Engine command specs | **801** `cmd!` entries (the 16 table-built character/paragraph-style specs unchanged) | was 789; **+12** |
| UI commands | **374** entries in `UI_COMMANDS`, all ids unique | was 343; **+31** (saved views, brush libraries, artboard lock/unlock, Transform panel items, …) |
| CLI subcommands | **7**: `mcp`, `run`, `commands`, `convert`, `info`, `bench`, `perf` | unchanged |
| MCP tools | **33** definitions (`undo`/`redo` are single-line entries; **`answer_dialog` is new**) | was 32; **+1** |
| MCP prompts / resources | **5** prompts (`poster, brief, palette, text, subject`); **3** fixed resources + **5** URI templates (+`vectorcraft://object/{lid}`) | +1 template |
| Control-channel methods | **29** canonical names (**30** accepted strings with the `command` alias; `ui.docking` is new) | was 28/29; **+1** |
| Browser JS API | **9** calls on `window.vectorcraft` | unchanged |
| Open extensions | **31** in `OPEN_EXTS`; Place additionally reads `.txt`/`.rtf`/`.docx` (**34**) | unchanged |
| Save formats | **6**: `vectorcraft`, `template`, `pdf`, `svg`, `svgz`, `ai` | unchanged |
| Writable formats | **20** formats → **19** export extensions + `plugin.<id>`; catalogue holds **24** formats (22 readable) | unchanged |
| Photoshop-style filters | **57** = 56 `PIXEL_EFFECTS` + `blur.gaussian` | unchanged |
| Effect catalogue | **116** entries: 86 literal + 15 warps + 12 Pathfinder + Trap + Crop Marks + Rasterize | unchanged |
| Tools | **94** ids in the tool catalogue (`t(` entries in `crates/tools/src/catalog.rs`) | was 92; **+2** |
| Panels | Panels dock on craft-ui's shared docking: **36** icon-panel entries in `ICON_PANELS` (`crates/ui-egui/src/state.rs:160`) plus dock tabs; floating panels are OS windows | reorganized |
| Interface languages | **25** = 24 `.tsv` catalogues + English | unchanged |
Never quote a count from memory: `vectorcraft-cli commands`, MCP `command_list` / `list_commands`, or control `engine.commands` return the live catalogue with shortcuts and params. Unknown param keys are rejected with a did-you-mean before anything runs (`crates/ui-egui/src/menus.rs::check_params`), and an unknown *command* id is answered with the nearest real id.
### Documents and UI
- Native format `.vectorcraft` (legacy `.drawcraft` still opens): versioned JSON, `VERSION = 4`, down-saves to v1/v2 as `drawcraft`, optional gzip (capped at 256 MB of JSON on wasm32), embedded PNG preview, atomic saves, unknown keys from newer versions preserved (`crates/format/src/lib.rs:53`; `docs/mcp.md` › Native files).
- Multiple documents open as **tabs** in one window, each with **artboards**, layers and sublayers; panels dock on craft-ui's shared docking (floating panels in OS windows, collapse to tabs); workspaces keep layout changes (`crates/ui-egui/src/state.rs`; `crates/ui-egui/src/panel_docking.rs`; `docs/ui-parity.md`).
- Export bytes are reproducible: `SOURCE_DATE_EPOCH` replaces the wall clock in PNG, PDF, EPS, legacy `.ai`, packaged zips and `.vectorcraft` saves; a malformed value is ignored (`crates/doc/src/metadata.rs`).
- Artboard guides (center mark / cross hairs / video safe areas / video ruler PAR) per artboard via `artboard.setProps`/`artboard.new`; Distance Guides on Alt/Option hover; a Constrain Angle preference. **New at this tag**: artboard lock/unlock from the canvas menu and the Artboards panel's **Delete Empty Artboards** (one undo step); the tab-overflow list scrolls to any open document.
- **25 saved views** now all list in the View menu with Edit Views… (`crates/ui-egui/src/menus.rs`).
### Drawing, paths and paint
- Tool set (94 ids in `crates/tools/src/catalog.rs`): Pen, Curvature, selection/anchor tools, shapes, pencil/brush/blob brush, eraser, lasso, magic wand, scissors, shape builder, live paint, width tool, symbol tools, Dimension tool, Perspective Selection, Touch Type… Tools never mutate the document directly — they emit commands, which makes gestures replayable by agents (`crates/tools/src/lib.rs`; `AGENTS.md`).
- Exact curve-preserving Pathfinder booleans, Shape Builder regions with Gap Detection, Live Paint, offset, outline stroke, simplify, join/average (`crates/pathops/src/lib.rs`; `crates/engine/src/cmd/buildcmds.rs`). **New at this tag**: the Pen tool and `path.join` continue, close and join **compound paths**; `Ctrl+J` joins the selected end points of two paths; the Join tool connects endpoints near scrub-line ends; the Pathfinder panel's **Pathfinder Options…** (Precision, Remove Redundant Points, Divide/Outline removes unpainted artwork) works.
- Appearance stacks (multiple fills/strokes, per-item effects), transparency, blob/opacity masks, clipping masks, graphic styles, global/spot swatches, gradients (linear/radial/freeform, mesh) with **Method Classic/Perceptual** (OKLab) and **Dither** (fills only), patterns, recolor (double-click a new color picks it in the Color Picker in the model it was picked in); a mixed selection now lists the attributes its objects share (`crates/engine/src/cmd/appearance.rs`, `paint.rs`, `gradient.rs`, `patterncmds.rs`, `recolor.rs`, `opacitymask.rs`).
- Brushes: calligraphic, scatter, art, pattern, bristle with a default library and expansion to real objects; **new**: Window › **Brush Libraries** (libraries whose brushes click/drag into the document), New Brush from the art its options opened with, Art Brush Options' Width can follow pen pressure, Eraser tip Angle/Roundness (`crates/brush/src/lib.rs`; `crates/ui-egui/src/panels/brushes/`).
- Symbols, blends, envelopes, radial/grid/mirror Repeat (**Grid Repeat now has on-canvas handles** for rows/columns/spacing), perspective grid, Intertwine, Objects on Path, 9 graph types with graph designs, Variables/data sets (4 kinds: text, visibility, image, graph) (`crates/engine/src/cmd/graph.rs`, `variablecmds.rs`, `perspgrid.rs`, `intertwine.rs`, `objects_on_path.rs`; `crates/doc/src/variables.rs`).
- Transform Each reopens on the values it was last confirmed with and has a Copy button; the Transform panel menu's Object Only / Pattern Only / Both / Use Registration Point for Symbol act; unit fields accept a decimal comma; Scribble effect Settings presets.
### Type
- Point, area and type-on-a-path type, threading across frames (visible in/out ports, **double-click a port to break the thread there**), character/paragraph styles, OpenType features, vertical type with initial CJK support, Hebrew/Arabic bidirectional layout, Thai/Lao/Khmer/Myanmar word breaking, Touch Type, Hyphenation…/Justification…, Roman Hanging Punctuation, Optical Margin Alignment, No Break, System Layout, Fractional Widths, Snap to Glyph (`crates/text/`; `docs/type-parity.md`).
- **Auto lists (new)**: typing `1. `, `A) ` or `* ` at a paragraph start starts a list; **Convert to Text** turns a list's bullets/numbers into characters; exported PDF list markers are selectable text (`crates/engine/src/cmd/typecmd.rs`; PRs #4192, #4093, #4098).
- **Ruby (ふりがな)**: `type.ruby` sets/removes a reading over a byte range — above/below, aligned, sized, overhanging or squeezed; saved natively, laid out with line growth, drawn and exported in SVG/PDF, and kept through Create Outlines, EPS, EMF/WMF and legacy `.ai`. No UI panel or type-on-a-path ruby yet.
- **Colour fonts**: `sbix`/`CBDT` bitmap emoji, **COLR v0/v1** (`crates/text/src/colr.rs`) and **OpenType SVG glyphs** (`crates/text/src/svg_glyph.rs`) draw and export as vector art; bitmap glyphs survive effects, Expand Appearance and EMF/WMF. Still open: CPAL palette variables, scripts/text inside SVG glyph documents.
- Type on a path: joined scripts bend along the path so their joins stay connected; a Direct-Selection drag of an on-path anchor reflows the type. Mixed Small Caps with super/subscript in the Character panel; Highlight Substituted Fonts moved to Preferences › Type and applies to every document. Text placed from `.txt`, `.rtf` and Word `.docx` as area type with formatting (`crates/engine/src/cmd/place/`).
### Effects and 3D
- **All 57 Photoshop-style raster filters** ship live and editable, plus **Effect › Effect Gallery…** (`ui.effectGalleryDialog`): six raster submenus, Add to Stack, reorder/remove, per-effect params, live canvas preview, OK applies the stack as separate appearance effects in one undo step (`crates/effects/src/pixel.rs` — `pixel/mod.rs` split into `pixel.rs` in v0.19.0; `crates/ui-egui/src/dialogs/effect_gallery.rs`). The gallery does not list the Blur, Pixelate, Sharpen or Video groups (those stay in the Effect menu).
- Illustrator-style effects catalogue: `crates/effects/src/catalog.rs` (`effect_catalog()`, 116 entries = 86 literal + 15 `WARP_STYLES` + 12 `PATHFINDER_EFFECTS` + Trap + Crop Marks + Rasterize). Remaining hole: **Apply SVG Filter** (menu stub only).
- Initial 3D: live **Revolve, Extrude & Bevel, Inflate, Rotate** with caps, bevels, twist/taper, perspective and **1–10 coloured lights** (`MAX_LIGHTS = 10`); four lighting presets via `effect.lightingPreset`; faces export as vector art. **No materials** — the 3D and Materials submenu's `Materials…` entry is a placeholder (`crates/three-d/src/lights.rs`; `docs/three-d.md`).
- Image Trace (raster → vector) with presets, Shapes/Auto-Grouping/Gradients options, Flat Logo refinements (2-px bars found, kept outlines only toward the anchor limit, unused palette colours dropped), Document Library traces with a Swatches colour group, and measured quality (`crates/trace/src/lib.rs`; `docs/image-trace-quality.md`).
### Files — open / read (implemented)
`document.open` / File › Open reads 31 extensions — authoritative list `OPEN_EXTS` in `crates/engine/src/cmd/fileio/formats.rs:473`: `.vectorcraft`, `.drawcraft`, `.svg`, `.svgz`, `.pdf`, `.ai`, `.ait`, `.png`, `.jpg/.jpeg`, `.gif`, `.webp`, `.tif/.tiff`, `.bmp`, `.tga/.vda/.icb/.vst`, `.psd`, `.psb`, `.vctemplate`, `.dxf`, `.emf`, `.wmf`, `.eps/.epsf`, `.ps`, `.af`, `.afdesign`, `.afpub`. File › Place additionally reads `.txt`, `.rtf`, `.docx` (`TEXT_EXTS`/`RTF_EXTS`/`DOCX_EXTS`).
- **SVG/SVGZ** — strongest interchange both ways; symbols, patterns, CSS (declaration splitting respects quotes/parentheses), filters mapped to live effects, Inkscape extensions, multi-page artboards; unsupported filters are named in `warnings`; foreign XML namespaces round-trip (`crates/svg/src/export.rs`; `docs/file-format-parity.md`).
- **PDF and `.ai`** — own reader; PDF opens with layers, editable text, masks, security, overprint; `.ai` reads Illustrator's private editing-data structure (up to **512 MiB** on 64-bit builds, so card files with embedded rasters keep layers and text) and legacy PostScript-form `.ai` via a PostScript Level 3 interpreter; **Illustrator blends import as live blends**; a multi-page `.ai` can open a named page from its editing data (`docs/file-format-parity.md`).
- **EPS/PS** — own PostScript L2/L3 interpreter and editing-data reader (`crates/eps/`); `.ps` opens (the file-format summary's "PS missing" row is stale).
- **Affinity** `.af` (Affinity 3), `.afdesign`, `.afpub` and, by content, `.afphoto` — native **read-only** import (no write); 51 pinned corpus documents, 33 current `.af` (`crates/affinity/README.md`; `docs/affinity-validation.md`).
- **PSD/PSB** open as their **merged image only**; placing as layers is not implemented (`FORMATS` in `crates/engine/src/cmd/fileio/formats.rs`).
- **DXF** (R12–2018), **EMF/WMF** (a file's bitmaps share one decoded-pixel budget), rasters incl. TIFF with CCITT Group 3/4 (`crates/cad/`, `crates/metafile/`).
### Files — save / export (implemented)
`SAVE_FORMATS` = `vectorcraft`, `template` (`.vctemplate`), `pdf`, `svg`, `svgz`, `ai` (`crates/engine/src/cmd/fileio/save.rs`); `TEMPLATE_FORMATS` = `template`, `ait`. Save As `.ai` writes a **PDF-compatible** file by default (carrying the native document when every artboard is written in order), or **legacy version 7** (`aiVersion: "7"` / `convert --ai-version 7`) which keeps layers, groups, compound paths and editable type, one artboard per file; transparency, live effects and object names don't survive it, and Illustrator's private editing data is never written; `convert` to PDF omits editing data by default.
Extension-driven `document.export` (`export_extensions()`): `.vectorcraft`, `.vctemplate`, `.svg`, `.svgz`, `.pdf` (presets, PDF/A-2b, PDF/X-1a/3/4, layers, marks/bleed, ICC, security, `/DisplayDocTitle`), `.ai`, `.eps`, `.dxf` (R12–2018), `.emf`, `.wmf`, `.png`, `.png8` (indexed), `.jpg`, `.webp` (**lossless only** — a lossy request is written lossless with a warning), `.gif`, `.tif`, `.bmp`, `.tga`, `.psd` (**layered**), `.txt`. Exporter **plug-ins** add their own formats (`plugin.<id>`). Pattern fills/strokes are written as real PDF tiling patterns. Plus Export for Screens / Asset Export (`<filename>` takes the saved document's file name; sizes refuse signs/exponents/non-numeric text), Export Selection, Export As with `rect` page-area rasters, CSS Properties export, Save for Office, Print/Print Tiling and Package (`crates/engine/src/cmd/print.rs`, `css.rs`, `package.rs`, `printtiling.rs`, `fileio/screens.rs`).
### Automation and extensions (implemented)
- **MCP server** (stdio, newline JSON-RPC 2.0): `vectorcraft-cli mcp` — remote backend (default: connect to `127.0.0.1:7979`, fall back to headless) or `--headless`. **33 tools** (`crates/mcp/src/tools/definitions.rs`): `command_list`, `command_run`, `run_command`, `command_batch` (≤256 steps, `atomic`, `$N.path`), `doc_inspect`, `inspect_document`, `ui_inspect`, `inspect_ui`, `ui_screenshot`, `list_commands`, `select_tool`, `pointer_gesture`, `draw_path`, `draw_shape`, `set_paint` (reports how many objects it painted), `press_key`, `type_text`, `answer_dialog` (**new** — sets the fields of the app's open dialog, then confirms or cancels it), `invoke_menu`, `open_panel`, `screenshot`, `open_file`, `save_file`, `export`, `add_text`, `apply_effect`, `pathfinder`, `transform`, `create_graph`, `text_wrap`, `render_preview`, `undo`, `redo`. `screenshot`/`render_preview` can draw the Image Trace view; `doc_inspect` reports `opacityPct` on the percent scale the drawing tools take; headless file tools pass relative paths to the engine as given. Plus **5 prompts**, **3 fixed resources** (`document`, `commands`, `document/json`) **+ 5 URI templates** (`object/{id}`, `object/{lid}`, `command/{id}`, `effect/{id}`, `swatch/{name}`), completions, logging, cancellation and a 2 s busy guard (only `%` + two hex digits is treated as an escape in resource URIs). Caps: 16 MiB lines, 64-message batches, 8 MiB kept step results, 256 MiB app replies. Protocol `2025-06-18`; clients asking for `2026-07-28` also get `resultType: complete`, `ttlMs` and `cacheScope` (`crates/mcp/src/server.rs`; `crates/mcp/src/prompts.rs`; `crates/mcp/src/resources.rs`; `docs/mcp.md`).
- **Control channel** — `vectorcraft --control <port>` listens on `127.0.0.1` only, one JSON request per line. **29 methods**: `engine.execute`, `engine.commands`, `document.inspect`, `ui.inspect`, `ui.menu.list`/`ui.menu.invoke`, `ui.contextMenu.list`, `ui.tool.select`/`ui.tool.list`, `ui.pointer`, `ui.key`/`ui.text`/`ui.move`/`ui.click`/`ui.drag`/`ui.wheel`, `ui.set`, `ui.dialog.set`/`confirm`/`cancel`, `ui.resize`, `ui.focus`, `ui.screenshot`, `ui.render`, `ui.docking` (**new** — drives the shared dock layout), `app.open`/`save`/`export`/`quit` (`crates/ui-egui/src/control.rs`; `docs/control-protocol.md`). No authentication — loopback only; 4 MiB request line, 16 connections, 60 s reply wait, 300 s idle. `ui.dialog.set` returns an error for a field the open dialog does not read. Confine reads/writes with repeatable `--automation-read-root`/`--automation-write-root`.
- **Browser API** — the web build exposes 9 calls as promises on `window.vectorcraft`: `request`, `execute`, `commands`, `inspect`, `screenshot`, `openFile`, `captureDownloads`, `files`, `readFile` (`apps/vectorcraft-web/src/api.rs::install`). Browser-reserved shortcuts now run only in the app.
- **CLI** `vectorcraft-cli` (`apps/vectorcraft-cli/src/main.rs`): `mcp` (`--connect ADDR | --headless`, repeatable `--automation-read-root`/`--automation-write-root`, also `--flag=DIR`), `run` (headless batch; `--in FILE`, repeatable `--cmd ID --params JSON`, repeatable `--export FILE`, `--scale`; `--commands FILE|-` reads a JSON array or JSON Lines, 64 MiB/100,000 steps; a step's result is referencable as `$N.path`), `commands` (full catalogue as JSON), `convert IN OUT` (`--artboard/--range/--outline-text/--decimals/--replace-lossy/--editing-data/--ai-version 7|pdf/--hidden-objects layer|omit|visible/--transparent-images flatten|omit`; refuses to overwrite its input when reading it left things out unless `--replace-lossy`; reports `importWarnings`), `info FILE`, `bench FILE [--size WxH] [--iters N]`, `perf [--paths N] [--deep]`. `--help` after a subcommand prints that subcommand's usage.
- **Plug-ins**: sandboxed WebAssembly modules (ABI v1, no host imports, fuel + memory caps; compiling a plug-in takes none of a run's instruction budget) as object **filters**, live **effects**, or **exporters** that add formats; up to **256** typed parameters (`crates/plugins/src/manifest.rs`; `docs/plugins.md`).
- **Actions** record/play through the Actions panel and `command.batch`; the Batch… dialog (`ui.batchDialog`) runs an action over files or data sets (`action.batch`); datasets via `dataset.import` (CSV/TSV; header cells define text/visibility/image/graph variables) (`crates/engine/src/cmd/variablecmds.rs`; `crates/doc/src/variables.rs`).
- **Script checking**: `script.check` statically analyses reference-app scripts and never runs them — `EXTS` = `.jsx`, `.jsxinc`, `.jsxbin`, and its documentation also covers plain `.js` text (`crates/engine/src/cmd/scripts.rs`; `crates/scriptcheck/src/`).
### Platform
- Web build: `apps/vectorcraft-web/` (Trunk; `cargo xtask wasm` gates it). Wasm aborts on panic — the native `guard` safety net does not apply there (`crates/engine/src/guard.rs`).
- Localized UI: 25 interface languages (24 `.tsv` catalogues + English) under `crates/ui-egui/src/i18n/`; **12-key-language score ~82% measured** (`docs/localization-parity.md`; `ROADMAP.md` still says 74% — stale). Only Georgian has had a native-speaker review; Hindi and Arabic have no catalogue (no right-to-left interface). macOS declares the UI languages so open/save panels translate.
- macOS pen pressure and the pen's eraser end read AppKit tablet events (`apps/vectorcraft/src/mac_tablet.rs`); the eraser end also selects the Eraser on Windows and in the web build. Windows lists only GDI-loaded fonts (so Creative Cloud's Adobe Fonts appear). The experimental 64-bit Windows 7 build and its `docs/windows7.md` and `printing/windows7.rs` were removed in v0.19.0; Linux Wayland drag-and-drop and pen caveats in `README.md`; maximized Windows windows respect top/side and auto-hidden taskbars.
- **Startup update prompt modal with direct self-updating** (craft-update crate, `Cargo.toml`); Windows installs per-user by default. Hostile-input hardening landed across EPS/legacy-`.ai` parsing, document-model bounds, planar-map budgets (booleans, Live Paint, Offset Path, 3D), raster decode caps (2 GiB allowance → reduced-size draw instead of a failure), and the wasm JSON cap.
## Known limitations and not-implemented
Label guide: repo-admitted gaps (`docs/gaps.md` ranked G1–G19, `README.md`) — treat them as work the app cannot be assigned yet. Where docs and code disagree, code wins; the main disagreements are listed at the end.
- **Stage alpha; not a daily driver yet** (~62% ready for real work; ~65% mainstream, ~75% essentials; ~170–270 h to beta). The ranked gaps: #1 **G1** interaction-fidelity pass over every tool modifier — **never** checked side by side with Illustrator (clean-room forbids it, so "done" means "matches the documentation"); #2 **G9** Illustrator `.ai`/EPS exchange — faithful layer/group structure from the editing data in real files (#951), guides (#779), open speed on large files (#758), and live effects/brushes/symbols as live objects (blends now import live; the rest partly improved), and Illustrator's own editing data is never written; #3 **G10** launch/stability on some Windows 11 and Linux machines; #4 **G8** hardening at scale; #5 **G11** correctness bugs in core tools (the live list is `docs/gaps.md` › G11).
- **3D and Materials**: four initial live types, **no materials, shadows or ray tracing** (~25% depth; painter's algorithm, not solid modelling). The `Materials…` menu entry is a placeholder (`docs/gaps.md` G3).
- **Illustrator effects**: only the **SVG Filters** submenu (Apply SVG Filter) is missing now — it is a menu stub (`crates/ui-egui/src/menus.rs`). Pathfinder Trap, Hard Mix and Soft Mix all exist (13/13 per `docs/effects-parity.md`); the parity docs disagree on the vector-effect total (`44/50` in `docs/target-app-parity.md`; `46/50` and `49/50` also appear in `docs/effects-parity.md`) — check the catalogue, not the count.
- **Formats not supported at all**: FreeHand, CorelDRAW, DWG (use DXF), HEIC/HEIF, JPEG 2000, PICT/PCX/Pixar, Word `.doc`, and 3D export (OBJ/USDA/glTF). No Affinity **write**. PSD/PSB open as merged images only (PSD export is layered). `document.export` writes no `.ps` (PostScript is print-only output).
- **Type still partial**: CJK vertical composition (Mojikumi Settings dialog, custom kinsoku sets), spell check (menu stubs only), Retype, CPAL palette variables, and preserving font sizes while scaling a group; Ruby has no UI panel or type-on-a-path (`docs/type-parity.md`; `docs/gaps.md` G4).
- **Scripting**: reference-app scripting does **not** run — VectorCraft has no script engine (`README.md` "What's missing"). `.jsx` files can only be statically checked (`crates/scriptcheck`). Automation is MCP/control-channel/CLI instead.
- **Generative AI features**: none (0%, `docs/gaps.md` G18).
- **MCP limits**: stdio only — no Streamable HTTP/SSE, no `resources/subscribe`, no `sampling/createMessage` or `elicitation/create`; document reads are refused as busy while a long call runs (`docs/mcp.md` › Not implemented).
- **Control port has no authentication** — loopback only; disable it when not in use (`docs/control-protocol.md`).
- **Artboard background colours** draw on the canvas but are left out of exports and print (documented in the `artboard.setProps` param doc, `crates/engine/src/cmd/layer.rs`).
- **Accessibility** is limited: AccessKit reaches egui widgets, but the canvas/custom panels are not described and nothing is tested with VoiceOver/Narrator/Orca (`docs/gaps.md` G19).
- **Claimed but unverified in this pass**: parity percentages, "done" checklist rows and hours are self-assessments from code against public documentation, never measured against Illustrator; localization catalogues other than Georgian have had no native review; the README's "20,000 shapes in ~27 ms" is a project self-report — measure with `vectorcraft-cli perf` on your machine; macOS pen pressure is implemented but untried on hardware.
- **Doc/code contradictions found at this tag** (code treated as authoritative): (a) `README.md` "What's missing" still lists "scripting, and the rest of Variables" although `dataset.import` and all four `VariableKind`s exist, and still lists 3D beyond Revolve although Extrude & Bevel/Inflate/Rotate ship (materials genuinely do not); (b) `ROADMAP.md` prints 348/375, 46/50 and 74% localization where `docs/target-app-parity.md` says 353/375 and 44/50 and `docs/localization-parity.md` measures ~82%; (c) `docs/file-format-parity.md` lists PS as missing while `OPEN_EXTS` reads `.ps`; (d) `docs/effects-parity.md` carries several conflicting vector-effect totals.
## How to operate
**Launch (macOS):**
```sh
open -a VectorCraft # or: open -a VectorCraft --args --control 7979
open -a VectorCraft --args --control 7979 --automation-read-root DIR --automation-write-root DIR
```
Desktop flags (`apps/vectorcraft/src/main.rs`; `apps/vectorcraft/src/automation_args.rs`): `--control <port>` (or `VECTORCRAFT_CONTROL_PORT`; a bad port stops the app with an error), repeatable `--automation-read-root <dir>` / `--automation-write-root <dir>` (confine everything an agent reads/writes; `--flag=DIR` also works, and the roots are ignored with a warning when `--control` is absent), `--in-window-menus` (`VECTORCRAFT_IN_WINDOW_MENUS=1`), `--version`, `-h/--help`; extra arguments are files to open as tabs. Env: `VECTORCRAFT_CONFIG_DIR` (isolated profile — use this for agent runs), `VECTORCRAFT_NO_PREFS` (no preference reads/writes), `WGPU_POWER_PREF=high|low` / `WGPU_ADAPTER_NAME=<substr>` to pick the GPU (`README.md`).
**The CLI is not inside the `.app` on macOS.** It ships as a separate release asset (`docs/mcp.md` › From an installed release); the bundle holds only the desktop binary, and `vectorcraft-cli` is not installed on a stock launcher install. Build with `cargo build --release -p vectorcraft-cli`, `cargo install --path apps/vectorcraft-cli --locked`, or unzip the asset. Update the app only **between** projects.
**Core workflow concepts:** one document per tab (`ui.inspect` lists `documents`/`activeDocument`); each document has artboards, layers, objects addressed by stable ids (layer/sublayer objects addressable as `object/{lid}` over MCP); units are points, y down, origin at the first artboard's top-left; a new document is 612 × 792 (`docs/mcp.md`). Selection plus a key object drive most commands; most commands accept explicit `ids`. Artboards carry per-artboard options (background colour, lock, center mark, video safe areas) through `artboard.setProps`.
**Open → edit → save/export:** open with File › Open / `app.open` / `open_file` (any `OPEN_EXTS`); save with Save/Save As (`SAVE_FORMATS` above) — a document opened from or saved as SVG/PDF keeps that format on Save, and the result's `warnings` say what the format loses. Export with `document.export` (extension or `format` picks the format; PDF/`.ai` write one page per artboard, SVG/SVGZ/EPS one file per chosen artboard, rasters one artboard unless `useArtboards`, with optional `rect` crops). **Always read `warnings`** — on import (EPS preview fallback, unsupported SVG filters, Affinity losses…) and on export: they are the loss report.
**Keyboard shortcuts:** never guess them. The command catalogue carries each command's shortcut: `vectorcraft-cli commands`, MCP `list_commands`, control `engine.commands` (`crates/ui-egui/src/shortcuts.rs` resolves them). Shortcut sets import/export as `.kys` (`shortcutset` commands).
**Preferences / agent-visible folders (macOS):** `Application Support/VectorCraft/` under the user's home (`ui.json` plus sibling folders Swatches, Graphic Styles, Fonts, Plug-ins, PDF Presets, Color Profiles, Data Recovery, logs) (`apps/vectorcraft/src/prefs_dir.rs`; `apps/vectorcraft/src/profile.rs`).
## Working with an AI agent
Prefer the automation surfaces over GUI automation; they are the same engine the UI uses.
- **Live session:** start the app with `--control 7979 [--automation-read-root DIR --automation-write-root DIR]` (each root may repeat), then either talk the control protocol directly or register the MCP bridge: `claude mcp add vectorcraft -- vectorcraft-cli mcp --connect 127.0.0.1:7979` (the bridge forwards each tool call as one control request, so you watch changes live).
- **Headless:** `vectorcraft-cli mcp --headless` or `vectorcraft-cli run --in FILE --cmd … --export OUT`; for long step lists use `run --in FILE --commands steps.json --export OUT` (stdin with `-`). The confinement flags imply `--headless` and refuse `--connect`, so a live app must confine itself with the same flags.
- **Inspect before editing:** `doc_inspect {depth: 0}` for the skeleton, then scope with `ids`/`kind`/`limit`/`offset`; `document.find` locates nodes (name/kind/text plus `within`, `intersects`, size, thickness, area and anchor-count filters) and `document.node {id, summary: true}` slices one; read paint with `paint.proxies`; list formats and their options with `document.formats`. On large documents drill — never dump `document.json`.
- **Draw/edit:** `draw_path` (SVG `d` or points), `draw_shape`, `add_text` (point/area/path, `vertical`, `justify`), `set_paint` (reports the painted count), `apply_effect`, `pathfinder`, `transform`, `text_wrap`, `create_graph`, or any command id via `command_run`. `draw_path`/`draw_shape` style and apply effects in the same atomic batch: a refused paint leaves no object and no undo step. Group edits with `command_batch {atomic: true}` so one undo step is recorded. Get exact ids/params from `commands`/`list_commands` — unknown param keys are rejected with a did-you-mean before anything runs.
- **Drive dialogs headlessly or live with `answer_dialog`**: set the fields of the app's open dialog, then `{"action": "confirm"}` or `{"action": "cancel"}` — the MCP twin of `ui.dialog.set`/`confirm`/`cancel` (which now errors on a field the dialog does not read).
- **Use the newest commands:** `pathfinder.trap` for print traps, `select.globalEdit` for appearance/size-matched edits, `window.symbolLibrary` / `ui.saveSymbolLibrary` for symbol libraries, `artboard.setProps {showCenterMark|showCrossHairs|showVideoSafeAreas}` for canvas-only artboard guides, `type.ruby` for furigana, `effect.lightingPreset` after a 3D effect, `paint.editGradient {method: "perceptual"}` / `{dither: true}` for print-safe ramps (SVG/PDF rasterise those fills), `ui.effectGalleryDialog` + `ui.dialog.set {field: "stack", value: [...]}` + `ui.dialog.confirm` to apply a stack of raster filters in one undo step (live app only), and `ui.docking` to arrange panels over the control channel.
- **Prepare inputs for the app:** SVG (cleanest interchange), PDF, EPS, DXF, PNG/JPEG/WebP/TIFF/BMP/Targa, PSD/PSB merged images, CSV/TSV for graphs and Variables data sets, `.rtf`/`.docx` for area type. Fonts: `text.addFontFiles` copies files into the app's Fonts folder; Japanese/Chinese/Arabic faces also come from the optional craft-fonts build input (`README.md`). Reusable logic can ship as a `.wasm` plug-in (ABI v1, no imports; `docs/plugins.md`).
- **Inspect/repair native files:** `.vectorcraft` is documented, versioned JSON (v4; optional gzip detected by content; unknown keys from newer versions are preserved by save). Prefer `document.save {version: 1|2, compress}` for downgrades over hand-editing; for repairs, open → inspect → command → save, and round-trip verify.
- **Verify outputs:** render previews (`render_preview`, `ui.render`, `screenshot`), reopen the export (`app.open`, `vectorcraft-cli info`) and diff warnings; `vectorcraft-cli bench`/`perf` for timings. Never trust a silent export.
- **Must NOT:** drive the GUI blind (use control/MCP; `ui.screenshot` needs a presented frame and fails after ~8 s when the screen is locked, the window is minimized or covered; window geometry is not stable across machines); write `.ai` private editing data or Affinity files (not implemented — don't promise them); assume PSD opens with layers; run reference-app scripts (not supported); use Adobe apps to create or verify anything (repo clean-room rule; produce test art in-repo instead, `AGENTS.md`).
## Verification protocol
Alpha software: verify by round-trip, never by assumption.
1. **Throwaway round-trip test** before any real job: new document → one edit per feature you plan to use (including ruby, colour-font type, auto lists, perceptual/dithered gradients, a 3D lighting preset, a live imported blend and a Pathfinder Trap if relevant) → save `.vectorcraft` → export the target format → reopen the export in VectorCraft *and* in the consuming app (browser for SVG, reader for PDF) → compare. Check `warnings` on open **and** export at every step (`convert` returns `importWarnings` beside export warnings).
2. **Master in native, deliver in exchange formats.** Keep the working file as `.vectorcraft` and treat SVG/PDF/EPS/`.ai` as deliverables: formats lose data (PDF-compatible `.ai` carries no Illustrator editing data; legacy v7 loses transparency/effects/names; EPS flattens opacity; DXF approximates gradients/patterns; perceptual/dithered gradients become images in SVG/PDF).
3. **Version and back up per session.** Saves are atomic and failed saves keep the old file, but a format conversion rewrites your project — keep a dated copy of the native file. `convert` refuses to overwrite its input when reading it left things out unless `--replace-lossy`; take that gate seriously.
4. **Pin versions per project.** The launcher auto-updates the app; alpha behaviour changes between releases (this skill covers v0.19.0 only). Update only between projects, and re-run your round-trip before trusting a pipeline after an update.
5. **Guard automation:** run agent sessions with `--automation-read-root/--automation-write-root` (repeatable; both MCP and app), `VECTORCRAFT_CONFIG_DIR` for an isolated profile, and the control port on loopback only while in use (it has no authentication).
6. **Reproducible comparisons:** set `SOURCE_DATE_EPOCH` when diffing exported bytes; without it PNG/PDF/EPS/`.ai`/zips/native saves record the wall clock.
7. **Re-measure counts, don't trust this file's:** `vectorcraft-cli commands | jq length`, MCP `tools/list`, control `engine.commands` give the live registry for whatever build you actually run.
## Sources & evidence
- Repo: https://github.com/storytold/vectorcraft — inspected at tag **v0.19.0**, commit `bcebabe3f8c23a376ac68e9e6726590af278f7bb` ("Release 0.19.0", 2026-10-31), shallow clone at the tag, clean tree. Installed app still 0.18.0 (`vectorcraft 0.18.0`, bundle lags the tag); `CFBundleIdentifier` `ai.storyteller.vectorcraft`; date of audit **2026-11-01**.
- Docs read: `README.md`, `ROADMAP.md`, `AGENTS.md`, `Cargo.toml`, `docs/gaps.md`, `docs/target-app-parity.md`, `docs/file-format-parity.md`, `docs/mcp.md`, `docs/control-protocol.md`, `docs/plugins.md`, `docs/ui-parity.md`, `docs/type-parity.md`, `docs/effects-parity.md`, `docs/localization-parity.md`, `docs/three-d.md`, `docs/image-trace-quality.md`, `docs/affinity-validation.md`, `crates/affinity/README.md` (`docs/windows7.md` removed in v0.19.0).
- Code read: `apps/vectorcraft-cli/src/main.rs`, `apps/vectorcraft/src/{main,automation_args,control_server,prefs_dir,profile,mac_tablet}.rs`, `apps/vectorcraft-web/src/api.rs`, `crates/mcp/src/{server,prompts,resources,backend}.rs`, `crates/mcp/src/tools/{definitions,dispatch,handlers}.rs`, `crates/engine/src/cmd.rs`, `crates/engine/src/cmd/{fileio,fileio/formats,fileio/save,typecmd,layer,pathops,gradient,effectcmd,globaledit,variablecmds,scripts,prefscmds}.rs` (file layout after the shared-module refactor), `crates/ui-egui/src/{control,menus,menus/ui_commands,shortcuts,state,panel_docking}.rs`, `crates/ui-egui/src/i18n/`, `crates/ui-egui/src/dialogs/effect_gallery.rs`, `crates/format/src/lib.rs`, `crates/doc/src/{metadata,variables}.rs`, `crates/effects/src/{catalog,group,pixel}.rs`, `crates/text/src/{colr,svg_glyph,bitmap}.rs`, `crates/three-d/src/lights.rs`, `crates/tools/src/{catalog,lib}.rs`, `crates/plugins/src/manifest.rs`, `crates/scriptcheck/src/`, `crates/pdf/src/export.rs`, `crates/svg/src/export.rs`, `crates/affinity/`.
- Method: `git rev-parse HEAD` for the pin (v0.19.0, `bcebabe3…`, inspected 2026-11-01); `cmd!`/`tool(`/`t(`/`UI_COMMANDS` entries and format arrays parsed from source with greps; the v0.18.0 ref was fetched for set diffs (registry set unchanged, several ids re-wrapped multiline). No build, no test run, no GUI launch; the installed bundle (still 0.18.0) was only read (`Info.plist`, `--version`).
- Companion file: `evidence.md` (claim → evidence path → tier).