Anton A S 0e8866265d Sync specs & docs with master: docs→packages/docs, Safari save, .fig export fix, LOC stats

2026-03-01 18:33:36 +03:00

18 KiB

Raw Blame History

`open-pencil eval` — Figma-like Plugin API for Headless Scripting

Overview

bun open-pencil eval <file> --code '<js>' executes JavaScript against a .fig file with a Figma-compatible figma global object. This enables headless scripting, batch operations, AI tool execution, and testing — all without the GUI.

The figma object mirrors Figma's Plugin API surface as closely as possible, so existing Figma plugin knowledge and code snippets transfer directly.

# Create a frame, set auto-layout, add children
bun open-pencil eval design.fig --code '
  const frame = figma.createFrame()
  frame.name = "Card"
  frame.resize(300, 200)
  frame.layoutMode = "VERTICAL"
  frame.itemSpacing = 12
  frame.paddingTop = frame.paddingBottom = 16
  frame.paddingLeft = frame.paddingRight = 16
  frame.fills = [{ type: "SOLID", color: { r: 1, g: 1, b: 1 } }]

  const title = figma.createText()
  title.characters = "Hello World"
  title.fontSize = 24
  frame.appendChild(title)

  return { id: frame.id, name: frame.name }
'

# Query nodes
bun open-pencil eval design.fig --code '
  const buttons = figma.currentPage.findAll(n => n.type === "FRAME" && n.name.includes("Button"))
  return buttons.map(b => ({ id: b.id, name: b.name, w: b.width, h: b.height }))
'

# Read from stdin (for multiline scripts / piping)
cat transform.js | bun open-pencil eval design.fig --stdin

# Write changes back
bun open-pencil eval design.fig --code '...' --write
bun open-pencil eval design.fig --code '...' -o modified.fig

Architecture

┌──────────────────────────────────────────────────────┐
│  CLI: `open-pencil eval <file> --code '...'`         │
│    ↓                                                 │
│  loadDocument(file) → SceneGraph                     │
│    ↓                                                 │
│  FigmaAPI(sceneGraph) → `figma` proxy object         │
│    ↓                                                 │
│  AsyncFunction('figma', wrappedCode)(figmaProxy)     │
│    ↓                                                 │
│  print result as JSON / agentfmt                     │
│  optionally: saveDocument(file) if --write           │
└──────────────────────────────────────────────────────┘

Key classes

Class	Location	Role
`FigmaAPI`	`packages/core/src/figma-api.ts`	Proxy object implementing `figma.*` methods against `SceneGraph`
`FigmaNode`	`packages/core/src/figma-api.ts`	Proxy wrapping `SceneNode` with Figma-style property access (`.fills`, `.resize()`, `.appendChild()`, etc.)
`eval` command	`packages/cli/src/commands/eval.ts`	CLI command that loads doc, creates API, executes code

Why in `@open-pencil/core`?

The FigmaAPI class lives in core (not CLI) because:

AI tools reuse it — the chat panel's render tool can execute JSX through the same API
Test scripts — unit tests can use the API to set up fixtures
No DOM deps — runs headless in Bun, no browser APIs needed

`FigmaAPI` — Phased Implementation

Phase 1: Core (MVP for eval command)

These cover ~80% of real plugin scripts:

Document & Page

Figma API	Our implementation	Notes
`figma.root`	Getter → proxy for root node	`.children` returns page proxies
`figma.currentPage`	Getter/setter → first page by default	Settable to any page proxy
`figma.currentPage.selection`	Get/set → tracked selection array
`figma.getNodeById(id)`	`graph.getNode(id)` wrapped in proxy	Sync, like Figma's deprecated version

Node Creation

Figma API	Maps to
`figma.createFrame()`	`graph.createNode('FRAME', currentPageId)`
`figma.createRectangle()`	`graph.createNode('RECTANGLE', ...)`
`figma.createEllipse()`	`graph.createNode('ELLIPSE', ...)`
`figma.createText()`	`graph.createNode('TEXT', ...)`
`figma.createLine()`	`graph.createNode('LINE', ...)`
`figma.createPolygon()`	`graph.createNode('POLYGON', ...)`
`figma.createStar()`	`graph.createNode('STAR', ...)`
`figma.createComponent()`	`graph.createNode('COMPONENT', ...)`
`figma.createPage()`	`graph.addPage(name)`
`figma.createSection()`	`graph.createNode('SECTION', ...)`

Node Properties (via `FigmaNode` proxy)

Read/write on any node proxy. Property access maps to SceneNode fields:

// Geometry
node.x, node.y              // direct
node.width, node.height      // read-only, use node.resize(w, h)
node.rotation                // direct
node.resize(w, h)            // updates width + height
node.resizeWithoutConstraints(w, h) // same (no constraint engine yet)

// Visual
node.fills                   // get/set Fill[]
node.strokes                 // get/set Stroke[]
node.effects                 // get/set Effect[]
node.opacity                 // get/set number
node.visible                 // get/set boolean
node.locked                  // get/set boolean
node.blendMode               // get/set BlendMode
node.clipsContent            // get/set boolean

// Corner radius
node.cornerRadius            // get/set (number or figma.mixed)
node.topLeftRadius           // get/set
node.topRightRadius          // get/set
node.bottomLeftRadius        // get/set
node.bottomRightRadius       // get/set
node.cornerSmoothing         // get/set

// Identity
node.id                      // read-only
node.name                    // get/set
node.type                    // read-only
node.parent                  // read-only → FigmaNode | null
node.removed                 // read-only boolean

Tree Operations

node.children                // read-only FigmaNode[]
node.appendChild(child)      // reparent to end
node.insertChild(index, child) // reparent at index
node.remove()                // graph.deleteNode(id)

// Traversal
node.findAll(callback?)      // recursive find
node.findOne(callback)       // first match
node.findChild(callback)     // direct children only
node.findChildren(callback?) // direct children only

Auto-layout

node.layoutMode              // 'NONE' | 'HORIZONTAL' | 'VERTICAL'
node.primaryAxisAlignItems   // 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN'
node.counterAxisAlignItems   // 'MIN' | 'CENTER' | 'MAX' | 'BASELINE'
node.itemSpacing             // number
node.counterAxisSpacing      // number | null
node.paddingTop / Right / Bottom / Left  // number
node.layoutWrap              // 'NO_WRAP' | 'WRAP'

// Child sizing
node.layoutPositioning       // 'AUTO' | 'ABSOLUTE'
node.layoutGrow              // 0 | 1
node.layoutSizingHorizontal  // 'FIXED' | 'HUG' | 'FILL'
node.layoutSizingVertical    // 'FIXED' | 'HUG' | 'FILL'

Text

node.characters              // get/set (maps to node.text)
node.fontSize                // get/set
node.fontName                // get/set { family, style }
node.fontWeight              // get/set
node.textAlignHorizontal     // get/set
node.textAlignVertical       // get/set
node.textAutoResize          // get/set
node.letterSpacing           // get/set
node.lineHeight              // get/set
node.maxLines                // get/set
node.textCase                // get/set
node.textDecoration          // get/set

Stroke details

node.strokeWeight            // get/set (maps to strokes[0].weight)
node.strokeAlign             // get/set (maps to strokes[0].align)
node.dashPattern             // get/set

Misc

figma.mixed                  // Symbol sentinel for mixed values
figma.group(nodes, parent)   // creates GROUP with given children
figma.ungroup(node)          // ungroups, reparents children
figma.flatten(nodes)         // NOT IMPLEMENTED YET — returns first node

Export

node.exportAsync(settings?)  // only works if CanvasKit is loaded
                             // settings: { format: 'PNG'|'JPG'|'SVG', constraint? }

Phase 2: Components & Instances

API	Maps to
`figma.createComponent()`	`graph.createNode('COMPONENT', ...)`
`figma.createComponentFromNode(node)`	Convert existing frame to component
`figma.combineAsVariants(components, parent)`	Create COMPONENT_SET
Node: `node.createInstance()`	`graph.createInstance(componentId, parentId)`
Node: `node.detachInstance()`	`graph.detachInstance(id)`
`figma.getNodeById(id).mainComponent`	`graph.getMainComponent(id)`

Phase 3: Variables

API	Maps to
`figma.variables.getLocalVariables(type?)`	`graph.variables` filtered
`figma.variables.getLocalVariableCollections()`	`graph.variableCollections`
`figma.variables.createVariable(name, collection, type)`	`graph.addVariable(...)`
`figma.variables.createVariableCollection(name)`	`graph.addCollection(...)`
`figma.variables.getVariableById(id)`	`graph.variables.get(id)`
`node.setBoundVariable(field, variable)`	`graph.bindVariable(...)`
`node.boundVariables`	getter from SceneNode

Phase 4: Styles & Advanced

API	Notes
`figma.createPaintStyle()`	Requires style storage in SceneGraph
`figma.createTextStyle()`	Requires style storage in SceneGraph
`figma.createEffectStyle()`	Requires style storage in SceneGraph
`figma.loadFontAsync(fontName)`	No-op (we don't have font loading constraints)
`figma.listAvailableFontsAsync()`	Return system fonts if available
Boolean operations (`union`, `subtract`, `intersect`, `exclude`)	Requires path boolean engine
`figma.createNodeFromJSXAsync(jsx)`	Port figma-use's JSX renderer

`FigmaNode` Proxy Design

The proxy wraps a SceneNode and translates Figma property names to our internal names. Key mappings:

const PROPERTY_MAP: Record<string, string> = {
  // Figma name → SceneNode field name (only where they differ)
  'characters': 'text',
  'strokeWeight': → computed from strokes[0].weight,
  'strokeAlign': → computed from strokes[0].align,
  'fontName': → computed from { family: fontFamily, style: ... },
  'primaryAxisAlignItems': 'primaryAxisAlign',
  'counterAxisAlignItems': 'counterAxisAlign',
  'primaryAxisSizingMode': 'primaryAxisSizing',    // value mapping: 'AUTO' → 'HUG', 'FIXED' → 'FIXED'
  'counterAxisSizingMode': 'counterAxisSizing',
  'layoutSizingHorizontal': → computed from primaryAxisSizing / counterAxisSizing depending on layoutMode
  'layoutSizingVertical': → computed
}

Methods on the proxy:

class FigmaNode {
  // The proxy is created via: new Proxy(target, handler)
  // where handler.get intercepts property reads and handler.set intercepts writes

  resize(width: number, height: number): void
  resizeWithoutConstraints(width: number, height: number): void
  remove(): void
  appendChild(child: FigmaNode): void
  insertChild(index: number, child: FigmaNode): void
  findAll(callback?: (node: FigmaNode) => boolean): FigmaNode[]
  findOne(callback: (node: FigmaNode) => boolean): FigmaNode | null
  findChild(callback: (node: FigmaNode) => boolean): FigmaNode | null
  findChildren(callback?: (node: FigmaNode) => boolean): FigmaNode[]
  exportAsync(settings?: ExportSettings): Promise<Uint8Array>

  // Components (Phase 2)
  createInstance(): FigmaNode
  detachInstance(): void
  get mainComponent(): FigmaNode | null
}

CLI Command

bun open-pencil eval <file> [options]

Arguments:
  file            .fig file to operate on

Options:
  --code, -c      JavaScript code to execute (has access to `figma` global)
  --stdin         Read code from stdin instead of --code
  --write, -w     Write changes back to the input file
  -o, --output    Write to a different file
  --json          Output result as JSON (default for non-TTY)
  --quiet, -q     Suppress output, only write file

Execution model

Load .fig → SceneGraph
Create FigmaAPI(graph) → figma proxy
Wrap user code in async function: return (async () => { <code> })()
Execute with figma as sole argument
Print return value (JSON or agentfmt)
If --write or -o: serialize SceneGraph back to .fig

Return value formatting

undefined / void → no output
Primitives → printed directly
Objects/arrays → JSON.stringify(result, null, 2) or agentfmt tables
FigmaNode → serialized as { id, type, name, x, y, width, height, fills, ... }
Arrays of FigmaNode → serialized as list

Shared with AI Tools

The FigmaAPI class is the same API surface that AI tools use. Currently src/ai/tools.ts calls store.createShape(), store.updateNodeWithUndo(), etc. — these should be refactored to go through FigmaAPI:

// Before (current AI tools)
execute: async ({ type, x, y, width, height }) => {
  const id = store.createShape(type, x, y, width, height)
  return { id }
}

// After (using FigmaAPI)
execute: async ({ type, x, y, width, height }) => {
  const frame = figma.createFrame()
  frame.resize(width, height)
  frame.x = x
  frame.y = y
  return { id: frame.id }
}

This ensures CLI scripts and AI tools behave identically.

File Layout

packages/core/src/
  figma-api.ts          # FigmaAPI class + FigmaNode proxy (Phase 1–4)
  figma-api.test.ts     # Unit tests against headless SceneGraph

packages/cli/src/commands/
  eval.ts               # CLI command

packages/cli/src/commands/eval.test.ts  # Integration tests

Test Plan

Unit tests (`packages/core/src/figma-api.test.ts`)

Node creation — each createX() creates correct type, added to current page
Property access — .fills, .x, .width, .name, .characters read/write correctly
Resize — .resize(w, h) updates width/height
Tree operations — .appendChild(), .insertChild(), .remove(), .parent, .children
Traversal — .findAll(), .findOne(), .findChild(), .findChildren() with callbacks
Auto-layout — .layoutMode, .itemSpacing, .paddingTop, etc.
Text — .characters maps to .text, .fontName maps to { family, style }
Mixed values — .cornerRadius returns figma.mixed when corners differ
Selection — figma.currentPage.selection get/set
Page switching — figma.currentPage = page2 works
Group/ungroup — figma.group() creates group, figma.ungroup() dissolves it
Clone — node creation produces independent copies

CLI integration tests (`packages/cli/src/commands/eval.test.ts`)

Basic eval — eval test.fig --code 'return figma.currentPage.name' → page name
Create + read — create a frame, return its properties
Query nodes — findAll returns correct nodes
Write back — --write saves changes, reloading shows them
Stdin — echo 'return 42' | bun open-pencil eval test.fig --stdin → 42
JSON output — --json returns valid JSON
Error handling — syntax errors, runtime errors reported cleanly

Implementation Order

FigmaNode proxy — property mapping, .resize(), .remove(), tree methods
FigmaAPI class — createFrame/Rectangle/..., .root, .currentPage, .getNodeById(), .mixed, .group()
CLI eval command — argument parsing, code wrapping, output formatting
Unit tests — all 12 test groups above
CLI integration tests — all 7 test groups above
Wire to AI tools — refactor src/ai/tools.ts to use FigmaAPI where possible
Phase 2 — components & instances
Phase 3 — variables
Phase 4 — styles, boolean ops, JSX renderer

Property Mapping Reference

Figma Property	SceneNode Field	Type	Notes
`characters`	`text`	`string`
`fontName`	`fontFamily` + `fontWeight` + `italic`	`{ family, style }`	Computed: `style` = "Bold Italic" etc.
`strokeWeight`	`strokes[0].weight`	`number`	Computed
`strokeAlign`	`strokes[0].align`	`string`	Computed
`primaryAxisAlignItems`	`primaryAxisAlign`	`string`
`counterAxisAlignItems`	`counterAxisAlign`	`string`
`layoutSizingHorizontal`	`primaryAxisSizing` or `counterAxisSizing`	`string`	Depends on `layoutMode`
`layoutSizingVertical`	(opposite of horizontal)	`string`
`absoluteTransform`	computed from `x`, `y`, `rotation`	`Transform`	Read-only
`absoluteBoundingBox`	`getAbsoluteBounds(id)`	`Rect`	Read-only
All others	Same name	Same type	Direct passthrough

Open Questions

Font loading: figma.loadFontAsync() — should it be a no-op (we don't have font gating) or should we track loaded fonts? → Decision: No-op that returns resolved Promise. We don't gate text editing on font loading.
Export in headless mode: node.exportAsync() requires CanvasKit. Should eval load CanvasKit? → Decision: Optional. If CanvasKit is available (via --with-canvaskit flag or env), enable export. Otherwise, throw "Export requires CanvasKit" error.
figma.mixed symbol: Should we use the actual Figma symbol or our own? → Decision: Our own Symbol('mixed'). Exposed as figma.mixed.
Undo: figma.commitUndo() / figma.triggerUndo() — relevant in headless? → Decision: No-op in CLI. Undo only matters in the live editor. The AI tools can add undo support separately via EditorStore.
Write format: Should --write produce .fig (Kiwi binary) or also support .json? → Decision: .fig only for now. JSON export is a separate feature.

18 KiB Raw Blame History Unescape Escape

open-pencil eval — Figma-like Plugin API for Headless Scripting