Vectorcraft

VectorCraft

Audit basis: this checkout is tag v0.20.0, commit 5628de96f866185d8eb289b167b89691f213c0c3 ("Release 0.20.0", 2026-11-01; the v0.19.0 ref was fetched for id diffs). The installed /Applications/VectorCraft.app matches this tag (CFBundleIdentifier ai.storyteller.vectorcraft, binary prints vectorcraft 0.20.0). Verify against your installed version before relying on behaviour added in 0.20.x.

v0.19.0 → v0.20.0 grows the registry by 20 commands, zero removed (multiline non-test extract 861 → 881): Add-ons ▸ Arrange gains addon.arrange.grid, addon.arrange.groupOverlapping, addon.arrange.randomizeOpacity, addon.arrange.replace, addon.arrange.size, addon.arrange.sort, addon.arrange.swap; Add-ons ▸ Cleanup gains addon.cleanup.joinText; addon.color.nearestSwatch / addon.color.applyNearestSwatch (snap a fill to the nearest catalogued swatch); addon.document.exportAllOpen, addon.document.saveTimestampedCopy, addon.document.symbolsFromLayers; addon.pathtools.expandDashes / addon.pathtools.divideDashes; symbol.exitEditing, symbol.instance.reset, symbol.instance.setAppearance, symbol.unused; and view.capsLock. The MCP tool set is unchanged (the only headless doc-string change: document.exportForScreens gained an includeArtboardFill option). Fix wave: DXF export writes an open one-segment path as a LINE and ellipses/unevenly-scaled circles as ELLIPSE, and Alter Paths for Appearance only outlines what a CAD line cannot draw (#4839/#4841/#4840); a gradient mesh from a file is budgeted at about a million quads (#4876) and SVG mesh patches are cut no finer than their colour changes (#4811); Make Opacity Mask over several layers masks their art (#4853) and an object used as an opacity mask keeps its own (#4789); opacity masks on art-brush pieces bend with the art (#4828); Blob Brush Tool Options set Angle and Roundness (#4838); Select Same Fill Color from a Live Paint face stays in its group (#4859); Convert to Smooth/Corner converts a selected blend's spine (#4857); Find Font leaves hidden and locked text alone (#4843/#4852) and Outline Stroke/Expand keep them hidden/locked (#4842); Perspective Selection's Shift constrains to plane axes/diagonals (#4804) and an overflowing perspective point maps to nothing (#4846); setting type in an unavailable font or style warns (#4866); Add New Fill copies the selected row (#4863); Grid Repeat Options has a Preview checkbox (#4875); a width-profile stroke keeps its shape when zooming out (#4871); Windows: render workers start only for the allowed cores (#4874), a device-named swatch library saves under another name (#3602/#4802) and automation file access refuses NTFS alternate-data-stream names (#3604/#4868); Direct Selection line-end snapping is square-to-straight, tangent-to-curves (#4850); and the saved color scheme, accent and canvas colour show at launch (#4848).

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

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 VariableKinds 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):

shCopy code
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.20.0, commit 5628de96f866185d8eb289b167b89691f213c0c3 ("Release 0.20.0", 2026-11-01), shallow clone at the tag, clean tree. Installed app matches the tag (vectorcraft 0.20.0); CFBundleIdentifier ai.storyteller.vectorcraft; date of audit 2026-11-02.
• 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.20.0, 5628de9…, inspected 2026-11-02); cmd!/tool(/t(/UI_COMMANDS entries and format arrays parsed from source with multiline-aware extracts; the v0.19.0 ref was fetched for set diffs (registry +20 ids, zero removed — all named in the delta above; several ids re-wrapped multiline). No build, no test run, no GUI launch; the installed bundle (matches the tag) was only read (Info.plist, --version).
• Companion file: evidence.md (claim → evidence path → tier).