Plan: eval command with Figma-compatible plugin API
This commit is contained in:
Danila Poyarkov
Anton A S
parent
96d8ab5789
commit
7ff37dc240
437
docs/eval-command.md
Normal file
437
docs/eval-command.md
Normal file
|
|
@ -0,0 +1,437 @@
|
|||
# `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.
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```ts
|
||||
// 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
|
||||
|
||||
```ts
|
||||
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
|
||||
|
||||
```ts
|
||||
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
|
||||
|
||||
```ts
|
||||
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
|
||||
|
||||
```ts
|
||||
node.strokeWeight // get/set (maps to strokes[0].weight)
|
||||
node.strokeAlign // get/set (maps to strokes[0].align)
|
||||
node.dashPattern // get/set
|
||||
```
|
||||
|
||||
#### Misc
|
||||
|
||||
```ts
|
||||
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
|
||||
|
||||
```ts
|
||||
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:
|
||||
|
||||
```ts
|
||||
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:
|
||||
|
||||
```ts
|
||||
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
|
||||
|
||||
1. Load `.fig` → `SceneGraph`
|
||||
2. Create `FigmaAPI(graph)` → `figma` proxy
|
||||
3. Wrap user code in async function: `return (async () => { <code> })()`
|
||||
4. Execute with `figma` as sole argument
|
||||
5. Print return value (JSON or agentfmt)
|
||||
6. 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`:
|
||||
|
||||
```ts
|
||||
// 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`)
|
||||
|
||||
1. **Node creation** — each `createX()` creates correct type, added to current page
|
||||
2. **Property access** — `.fills`, `.x`, `.width`, `.name`, `.characters` read/write correctly
|
||||
3. **Resize** — `.resize(w, h)` updates width/height
|
||||
4. **Tree operations** — `.appendChild()`, `.insertChild()`, `.remove()`, `.parent`, `.children`
|
||||
5. **Traversal** — `.findAll()`, `.findOne()`, `.findChild()`, `.findChildren()` with callbacks
|
||||
6. **Auto-layout** — `.layoutMode`, `.itemSpacing`, `.paddingTop`, etc.
|
||||
7. **Text** — `.characters` maps to `.text`, `.fontName` maps to `{ family, style }`
|
||||
8. **Mixed values** — `.cornerRadius` returns `figma.mixed` when corners differ
|
||||
9. **Selection** — `figma.currentPage.selection` get/set
|
||||
10. **Page switching** — `figma.currentPage = page2` works
|
||||
11. **Group/ungroup** — `figma.group()` creates group, `figma.ungroup()` dissolves it
|
||||
12. **Clone** — node creation produces independent copies
|
||||
|
||||
### CLI integration tests (`packages/cli/src/commands/eval.test.ts`)
|
||||
|
||||
1. **Basic eval** — `eval test.fig --code 'return figma.currentPage.name'` → page name
|
||||
2. **Create + read** — create a frame, return its properties
|
||||
3. **Query nodes** — `findAll` returns correct nodes
|
||||
4. **Write back** — `--write` saves changes, reloading shows them
|
||||
5. **Stdin** — `echo 'return 42' | bun open-pencil eval test.fig --stdin` → `42`
|
||||
6. **JSON output** — `--json` returns valid JSON
|
||||
7. **Error handling** — syntax errors, runtime errors reported cleanly
|
||||
|
||||
## Implementation Order
|
||||
|
||||
1. **`FigmaNode` proxy** — property mapping, `.resize()`, `.remove()`, tree methods
|
||||
2. **`FigmaAPI` class** — `createFrame/Rectangle/...`, `.root`, `.currentPage`, `.getNodeById()`, `.mixed`, `.group()`
|
||||
3. **CLI `eval` command** — argument parsing, code wrapping, output formatting
|
||||
4. **Unit tests** — all 12 test groups above
|
||||
5. **CLI integration tests** — all 7 test groups above
|
||||
6. **Wire to AI tools** — refactor `src/ai/tools.ts` to use `FigmaAPI` where possible
|
||||
7. **Phase 2** — components & instances
|
||||
8. **Phase 3** — variables
|
||||
9. **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
|
||||
|
||||
1. **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.
|
||||
|
||||
2. **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.
|
||||
|
||||
3. **`figma.mixed` symbol**: Should we use the actual Figma symbol or our own?
|
||||
→ **Decision: Our own `Symbol('mixed')`.** Exposed as `figma.mixed`.
|
||||
|
||||
4. **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.
|
||||
|
||||
5. **Write format**: Should `--write` produce `.fig` (Kiwi binary) or also support `.json`?
|
||||
→ **Decision: `.fig` only for now.** JSON export is a separate feature.
|
||||
Loading…
Reference in a new issue