9dce9fdcbc
* fix: stop ancestor walks from hanging on a parent cycle A collaborator's concurrent reparent can leave two layers as each other's parent. isDescendant, the design check's pageOf, and component sync walked parentId without a bound, so applying such a change froze the editor. Add SceneGraph.closest(), a bounded nearest-ancestor lookup, and use it for these walks so bad data ends the walk instead of the tab. * fix(collab): sync layer moves without parent cycles or stale child lists Remote changes assigned each layer's synced parentId and childIds as plain properties. Two peers moving layers into each other made them each other's parent, a moved layer stayed listed under its old parent, reorders never synced, and concurrent additions ended up in different orders or missing from the parent's list. Apply the tree after a change's properties: move layers to their synced parents, skip a move that would make a layer its own ancestor and write the layer's current parent and position back so every peer settles on it, and derive each touched parent's childIds from its synced order followed by unlisted children by id. Locally, a parent's child list syncs once after each edit that adds, removes, moves, or reorders its children. Fixes #888 Fixes #889 * refactor(scene-graph)!: move sibling order keys to scene-graph Collaboration needs the same fractional keys as .fig export to order siblings, and the app must not depend on @open-pencil/fig for them. Move fractionalPosition, orderKeyBetween, and siblingOrderKeys to @open-pencil/scene-graph/order-keys. orderKeyBetween now always returns a key: when no printable key fits it returns one above lo, which hasOrderKeyBetween detects, so callers no longer branch on null. It takes an optional suffix, and siblingOrderKeys can request one per key, so two peers inserting at one spot get distinct keys. .fig export keeps its keys. * fix(scene-graph): report instance child reorders as graph events Instance sync sorted an instance's children in place, so nothing that listens to graph events saw the new order; in a shared room the order never reached other peers. Move each child that changes position with insertChildAt, which reports the reorder. * feat(collab): resolve the layer tree from each layer's parent history Add a pure LayerTree for the shared document: each layer records every parent it was moved under with a move counter and an order key. A layer sits under its newest parent, ties broken by parent id; when concurrent moves close a loop, the latest move in the loop falls back to the layer's next entry until none is left, and a layer no parent can take goes to its page (Evan Wallace's mutable tree hierarchy CRDT). The result depends only on the entries, and resolution revisits only changed, orphaned, and displaced layers. Seeded random runs check that peers converge and that the incremental result matches a full one. * fix(collab): sync layer moves as parent history and order keys Each layer's shared map now records every parent it was moved under with a move counter from a document-wide Lamport clock, and its order key among siblings, instead of parentId and childIds. Every peer derives parentId and childIds from these with LayerTree, so concurrent moves, reorders, and additions merge, a loop from concurrent moves undoes its latest move, and a layer whose new parent was deleted meanwhile returns to its previous one. A local edit's graph events are written once after the edit, in one transaction. It records a parent entry for each layer whose parent changed, a new entry for displaced layers on the touched paths so a move cannot pull them back, and keys between the moved layers' neighbours with a random suffix, so concurrent inserts at one spot get distinct keys. Remote changes find their layers through each event's path, resolve only what they touch, and move and sort layers through insertChildAt. This replaces the childIds merge and the write-back of rejected moves: a rejected move now resolves the same way on every peer from the shared history, so nothing needs to be written back. Fixes #888 Fixes #889 * feat(collab)!: convert saved rooms and keep mismatched builds apart A room saved by an earlier build records parentId and childIds. When a change brings in such layers, from this browser's storage or a peer, convert them in one transaction: each layer's synced parent becomes its only entry with counter 0, its position in the parent's synced childIds becomes an order key, and the old fields go. The result depends only on the document, so two peers converting at once write the same values, and converting again writes nothing. The document's meta map records treeFormat 2. Builds that record the tree differently would corrupt each other's rooms, so the collaboration namespace becomes openpencil/2 for Trystero and the test relay alike, and each peer publishes its treeFormat in awareness for future version messages. * fix(collab): send a layer whose parents were all deleted back to its own page Each layer's shared map records the page it was last placed on, and the layers under a frame moved to another page are re-recorded. A layer whose parent chain was deleted goes back to that page, falling back to the first page only when the recorded one is gone. Saved rooms record pages when they are converted. * fix(collab): keep one root per room when peers edit their own documents Joining a room keeps the joiner's earlier document in its graph, and an undo or an edit made before the room arrived could still reach it. That edit shared the joiner's root, every peer adopted it, and the room's pages disappeared. The room now records its root as claims in meta, each with the time it was made, and every peer follows the earliest. Sharing claims the room, and so does the first edit in a room nobody has shared, which now shares the whole document as Share does. A peer shares only layers under the room's root. Converted rooms claim the root with the most children. Move counters must also be safe integers, so an oversized counter from another peer cannot stop the move clock from advancing. * fix(collab): rank root claims by how they were made, not by clocks Root claims carried the claiming peer's wall-clock time, so a guest whose clock ran behind the sharer's could still win the room with an edit made before the room reached them. A claim now records whether it came from Share or a converted room, or from the first edit in an unshared room; a shared root outranks an edited one, and the lower id breaks a tie. A claim also replaces an invalid value already stored for its root. * fix(collab): keep every root claim through concurrent writes A root claim was one key per root holding its kind, so two peers claiming the same root by Share and by an edit at once kept only one of the two values, and the shared claim could be lost. Each kind of claim on a root is now its own key. Converting a saved room also claims its root unless a shared claim exists, so a guest's earlier edited claim no longer keeps the converted room from outranking it. * fix(collab): mint layer IDs under a session of each editor window Every editor window started its IDs at 0:1 from the same counter, so two people adding layers to a shared room at once could mint the same IDs, and one person's layers replaced the other's in the room. A joiner's starting page also took the sharer's page ID and stayed in their list. SceneGraph's default IDs now carry a session set with setIdSession, as in Figma's sessionID:localID GUIDs. The editor picks a random 32-bit session at startup, as Yjs does for each document's clientID; headless tools keep session 0, so the CLI and MCP server give a file's layers the same IDs on every run. * fix(collab): let only Share set a room's root A guest's first edit in a room whose contents had not arrived claimed the room and wrote the guest's whole open document into it, images included, and adopting the sharer's root later only hid it. Every room starts with someone sharing a document, so a guest has nothing to claim: only Share, or converting a saved room, now sets the room's root, as a single value in meta, and a peer writes nothing until the root is known. Unbinding a room also writes an edit still waiting to be sent, so a move or deletion made just before leaving reaches the room. * feat(collab)!: open each room in a tab of its own Joining a room bound it to whatever tab was active, so a pasted link could turn a saved file into the room's document, and a share link first showed an editable blank document. A room is now a document: joining always opens it in a new tab, or switches to the tab already showing it, and only Share puts an existing tab's document into a room. Every room tab owns its session (src/app/collab/rooms.ts and session.ts), so several rooms can be live at once and keep syncing in the background. The collaboration panel, presence, following, and the /share/<id> address follow the active tab, and a canvas publishes its cursor and selection only to its own tab's room. A room tab derives its state: joining while its saved copy loads, then waiting, with an explanation, while nobody who has the file is online; live with others, or alone on this device's copy. Until the document arrives the room's screen replaces the editor. Reloading a share link rejoins it; leaving a room you joined keeps its file as a local unsaved copy. "Connected" now means another peer answered. Pasted links and IDs are normalised and validated, and invalid ones say so. People join right away under a generated name such as "Teal Fox", with a hint to set one; the one app-wide name is set in the share panel or in Settings. On a phone, Share copies the room's link instead of making a new room, and the presence popover shows the room's state. * feat(desktop): open rooms from openpencil://join links and Home The desktop app could not receive a share link: links point at the web app, and openpencil:// only opened files. openpencil://join?room=<id> now opens the room in a tab of its own. The native parser refuses anything but a room ID, queues rooms for the frontend through take_pending_rooms, and a second launch on Windows and Linux forwards its link through the single-instance handler. In a browser on a computer, the room's screen and the share panel offer Open in desktop app, a link the browser hands to the app on click; it never opens the app by itself. Home gains Join room…, which takes a pasted room link or ID and opens the room in a new tab. * feat(collab): set your name on the room screen The room screen told someone joining under a generated name to set their name but offered nowhere to do it before the file arrived. It now has the same name field as the room panel. * feat(collab): offer the desktop download beside Open in desktop app A browser on a computer offers a room's openpencil://join link, which does nothing where the app is not installed. The room screen and panel now link to the latest release beside it. * docs: describe joining rooms in the German, Polish, and Russian guides Bring the translated collaboration pages up to the English one: Share as the only way into a room, joining in a tab of its own, the waiting screen, leaving with a local copy, and how layer moves merge. The English page now names the panel's Leave room button. * fix(collab): lay out the room screens like the app's empty states The joining and waiting screens were a left-aligned card with a stray spinner, a primary Copy link button beside an outline button and a bare link, and a name field on a screen that lasts seconds. They now use AppPlaceholder, centred over the tab: a heading, the explanation, the two hints, secondary Copy link and Leave, a 'You'll appear as' line whose Change opens a small rename popover, and the desktop handoff on one muted line. The room panel lines its status dot up with wrapped text, no longer selects the room link when it opens, and puts the desktop links and Leave room on one footer line. * fix(collab): show what a room tab is doing instead of a timed guess A joined tab said nobody with the file was online five seconds after it opened, whether or not it had reached the signaling service or met the people already in the room. Its state now follows what the tab can observe: connecting until the service answers, looking for people for as long as that transport takes to introduce everyone, getting the file from someone who says they have it, waiting when nobody who has it showed up (naming other guests waiting too), and a can't-connect screen when the service cannot be reached. Each peer says in its presence whether it has the room's file. * fix(collab): list other waiting guests with the explanation The line naming other guests who are waiting too is information, not an action, so it follows the hints above the buttons. Peers' hasFile flag is optional, as older builds do not send it. * fix(collab): send a canvas's cursor and selection to its tab's room again Canvases read the editor through a proxy that follows the active tab, and the room lookup by store never matched it, so pointer moves and selections stopped reaching the room: collaborators lost each other's cursors, selections, and page markers. The canvas now looks up its room by its tab's own store, and its selection listener ends when the canvas unmounts instead of piling up across tab switches. * feat(collab): one avatar stack for the toolbar, the mobile pill, and pages The toolbar, the page list, and the mobile HUD each drew the people in a room their own way, and the mobile pill read 'Online: 3' in hard-coded English beside a status dot too small to render. AvatarStack now draws people overlapping with their agent counts and '+N', and every place uses it: the toolbar wraps each avatar in its menu or hover card, the mobile pill shows the room's state dot and the stack with a translated name, and hovering a page with people on it opens a card with the stack and who is there, with their agents, to follow. The mobile list is the shared presence list, so it is translated and can follow agents too. * docs: note the page hover card and mobile avatars in the changelog * fix(collab): stop listening to a room once its tab leaves it A session left its Yjs observers and its awareness listener attached after dispose, relying on destroy() and the order of teardown not to touch the tab again. It now removes them explicitly and clears its peer list. Also fix a missing comma in the Polish collaboration guide. |
||
|---|---|---|
| .claude | ||
| .devcontainer | ||
| .github | ||
| .storybook | ||
| .vscode | ||
| assets/brand | ||
| desktop | ||
| lint | ||
| packages | ||
| public | ||
| skills/open-pencil | ||
| src | ||
| tests | ||
| tools | ||
| vite | ||
| .coderabbit.yaml | ||
| .gitattributes | ||
| .gitignore | ||
| .gitleaks.toml | ||
| .lfsconfig | ||
| .oxfmtrc.json | ||
| AGENTS.md | ||
| bun.lock | ||
| bunfig.toml | ||
| CHANGELOG.md | ||
| commitlint.config.ts | ||
| CONTRIBUTING.md | ||
| index.html | ||
| knip.json | ||
| LICENSE | ||
| oxlint.json | ||
| package.json | ||
| playwright.config.ts | ||
| portless.json | ||
| README.md | ||
| SECURITY.md | ||
| steiger.config.ts | ||
| tsconfig.json | ||
| tsconfig.node.json | ||
| tsconfig.tests.json | ||
| vite.config.ts | ||
| wdio.conf.ts | ||
OpenPencil
Open-source design editor. Opens .fig and .pen design files, includes built-in AI, and ships as a programmable toolkit with a headless Vue SDK for building custom editors.
Status: Active development. Usable today, with some rough edges as features evolve.
Try it online → · Download · Documentation · Roadmap · llms.txt
Installation
macOS (Homebrew):
brew install --cask openpencil
Or download from the releases page, or use the web app — no install needed.
Requires macOS 13 or later with current Safari updates, Windows 10 or later, or Linux with WebKitGTK 2.40+; the web app needs Chrome 111, Edge 111, Firefox 128, or Safari 16.4 or later. See system requirements.
What it does
- Opens
.figand.penfiles — read and write native Figma files, open supported Pencil documents from the app or OS file browser, copy & paste nodes between apps - AI builds designs — describe what you want in chat, 100+ tools create and modify nodes. Connect OpenRouter, Anthropic, OpenAI, Google AI, DeepSeek, Z.ai, MiniMax, or compatible endpoints
- Fully programmable — headless CLI, XPath queries, Figma Plugin API via
eval, MCP server for AI agents, and desktop agent integrations for Claude Code, Codex, and Gemini CLI - Lint, convert, and extract tokens — inspect documents, lint naming/layout/accessibility, convert between supported formats, analyze colors/typography/spacing/clusters, and extract design tokens
- Components and variants — create reusable components, group variants into component sets, insert local assets as instances, and switch variants from the inspector
- Image vectorization — convert image layers into editable vector layers with Recraft or fal.ai
- Design-to-code export — export selections as JSX/Tailwind, generate token outputs, and map designs into component-oriented code workflows
- Vue SDK for custom editors — headless components and composables for embedding OpenPencil into other apps or building workflow-specific editing surfaces. Read the SDK docs →
- Real-time collaboration — P2P via WebRTC, no server, no account. Cursors, presence, follow mode
- Auto layout & CSS Grid — flex and grid layout via Yoga WASM, with gap, padding, alignment, track sizing
- ~15 MB desktop app — Tauri v2 for macOS, Windows, Linux. Also runs in the browser as a PWA
CLI
npm install -g @open-pencil/cli
# or: bun add -g @open-pencil/cli
Inspect design files
Browse node trees, search by name or type, dig into properties — all without opening the editor:
openpencil tree design.fig
openpencil find design.pen --type TEXT
openpencil node design.fig --id 1:23
openpencil info design.fig
[0] [page] "Getting started" (0:46566)
[0] [section] "" (0:46567)
[0] [frame] "Body" (0:46568)
[0] [frame] "Introduction" (0:46569)
[0] [frame] "Introduction Card" (0:46570)
[0] [frame] "Guidance" (0:46571)
Query with XPath
Find nodes by type, attributes, and structure:
openpencil query design.fig "//FRAME[@width < 300]" # Frames under 300px
openpencil query design.fig "//SECTION//TEXT" # Text inside sections
Export, convert, and import
Render to PNG, JPG, WEBP, SVG, PDF, PPTX, HTML, JSX, Storybook stories, or .fig, convert between document formats, and turn HTML/CSS into editable layers:
openpencil export design.fig # PNG
openpencil export design.fig -f jpg -s 2 # JPG at 2x
openpencil export design.fig -f tailwind-jsx # Tailwind JSX
openpencil export design.fig -f storybook # Storybook stories per component
openpencil convert design.pen design.fig # Between document formats
openpencil import card.html --css card.css # HTML/CSS → editable .fig
Lint and analyze
Catch naming, layout, and accessibility issues, and audit a design system's real palette, type scale, spacing, and repeated components:
openpencil lint design.fig --preset strict # Naming, layout, accessibility
openpencil analyze colors design.fig # Also typography, spacing, clusters
openpencil variables design.fig # Variables and collections
#1d1b20 ██████████████████████████████ 17155×
#49454f ██████████████████████████████ 9814×
#ffffff ██████████████████████████████ 8620×
#6750a4 ██████████████████████████████ 3967×
Script with the Figma Plugin API
eval runs JavaScript against the document with Figma's Plugin API; -w writes the result back:
openpencil eval design.fig -c "figma.currentPage.selection.forEach(n => n.opacity = 0.5)" -w
Control the running app
Omit the file argument and the CLI works on the document open in the editor:
openpencil tree # Inspect the live document
openpencil documents list # Also open, new, save, close, activate
openpencil tool call get_selection # Run any MCP tool
openpencil undo # Undo the newest automation change
openpencil settings set appearance.theme light # Change editor settings
Every command supports --json. See the CLI reference for all commands and options.
AI & MCP
Built-in chat
Press ⌘J (CtrlJ on Windows and Linux) to open the AI assistant. It has 100+ tools that can create shapes, set fills and strokes, manage auto-layout, work with components and variables, run boolean operations, analyze design tokens, and export assets. Bring your own API key for OpenRouter, Anthropic, OpenAI, Google AI, DeepSeek, Z.ai, MiniMax, or compatible endpoints. No backend, no account.
Not every provider works in the browser, and not every model streams tool calls correctly. See BYOK provider & model compatibility for measured results — contributions welcome.
Coding agents (desktop)
Use Claude Code, Codex, or Gemini CLI directly in the chat panel. The agent connects to the editor's MCP server and uses all 100+ design tools. Requires the desktop app and the agent CLI installed locally.
Pi works too: install @open-pencil/harness globally, then add a Pi model profile in Settings → AI & agents.
Setup (Claude Code):
- Install the ACP adapter:
npm install -g @agentclientprotocol/claude-agent-acp - Add MCP permission to
~/.claude/settings.json:{ "permissions": { "allow": ["mcp__open-pencil__*"] } } - Open the desktop app → ⌘J → select Claude Code from the provider dropdown
MCP server
Connect Claude Code, Cursor, Windsurf, or any MCP client to inspect, modify, and export design documents headlessly. 100+ tools. Full docs →
Stdio (Claude Code, Cursor, Windsurf):
npm install -g @open-pencil/mcp
claude mcp add --scope user open-pencil -- openpencil-mcp
For other MCP clients:
{
"mcpServers": {
"open-pencil": {
"command": "openpencil-mcp"
}
}
}
HTTP (scripts, CI):
openpencil-mcp-http # Unix socket on macOS/Linux + http://127.0.0.1:7600/mcp
Set OPENPENCIL_MCP_ROOT to limit file access to one directory; it defaults to the current working directory.
AI agent skill
Teach your AI coding agent to use OpenPencil — inspect designs, export assets, analyze tokens, modify .fig files:
npx skills add open-pencil/open-pencil
Works with Claude Code, Cursor, Windsurf, Codex, and any agent that supports skills.
For documentation-aware agents, the docs site publishes llms.txt, llms-full.txt, and per-page Markdown files generated from the VitePress docs.
Collaboration
Share a link to co-edit in real time. No server, no account — peers connect directly via WebRTC.
- Click the share button in the top-right panel
- Share the generated link (
app.openpencil.dev/share/<room-id>) - Collaborators see your cursor, selection, and edits in real time
- Click a peer's avatar to follow their viewport
Why
Figma is a closed platform that actively fights programmatic access. Their MCP server is read-only. figma-use added full read/write automation via CDP — then Figma 126 killed CDP. Your design files are in a proprietary binary format that only their software can fully read. Your workflows break when they decide to ship a point release.
OpenPencil is the alternative: open source (MIT), reads .fig files natively, every operation is scriptable, and your data never leaves your machine.
See the roadmap for product direction and current Figma compatibility gaps.
Community
- Discord — chat, quick questions, and showing a problem live
- GitHub Discussions — Q&A for help, Ideas for feature proposals, Show and tell for what you built; maintainers post Announcements there
- Issues — reproducible bugs; report security problems through a private advisory
Contributing
bun install
bun run dev:portless # Web editor at https://open-pencil.localhost
bun run tauri dev # Desktop app (requires Rust)
CONTRIBUTING.md covers setup, quality gates, pull requests, and commits. AGENTS.md maps the repository and links the guide inside each package. Desktop builds need Rust and the Tauri v2 prerequisites; run bun run tauri build.
Tech stack
| Layer | Tech |
|---|---|
| Rendering | Skia (CanvasKit WASM) |
| Layout | Yoga WASM (flex + grid via fork) |
| UI | Vue 3, Reka UI, Tailwind CSS 4 |
| File format | Kiwi binary + Zstd + ZIP |
| Collaboration | Trystero (WebRTC P2P) + Yjs (CRDT) |
| Desktop | Tauri v2 |
| AI/MCP | Vercel AI SDK (multi-provider BYOK), MCP SDK, Hono |
Acknowledgments
Thanks to @sld0Ant (Anton Soldatov) for creating and maintaining the documentation site.
License
OpenPencil is licensed under the MIT License.
Copyright (c) 2026 Danila Poyarkov and OpenPencil contributors.