@dannote/figma-use 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-01-18
+
+### Added
+
+- **`defineVars` API for Figma variables** — bind colors to variables by name
+  ```tsx
+  const colors = defineVars({
+    primary: { name: 'Colors/Gray/50', value: '#F8FAFC' },
+    accent: { name: 'Colors/Blue/500', value: '#3B82F6' },
+  })
+  <Frame style={{ backgroundColor: colors.primary }} />
+  ```
+- Variable binding for `backgroundColor`, `borderColor`, and text `color`
+- Variables resolved by name at render time (no more magic IDs)
+- `defineVars` support in stdin snippets
+- Explicit fallback values in `defineVars` for proper color display
+
+### Fixed
+
+- Auto-layout now works correctly via `trigger-layout` post-render
+- Nested auto-layout frames trigger recursively
+- Variable binding encoding matches Figma's exact wire format
+
+### Changed
+
+- Marked React render and variable bindings as **experimental** in docs
+
+## [0.3.1] - 2026-01-18
+
+### Added
+
+- **Variable binding via multiplayer protocol** — bind fill colors to Figma variables without plugin API
+  - `encodePaintWithVariableBinding()` — encode Paint with color variable binding
+  - `encodeNodeChangeWithVariables()` — encode NodeChange with variable-bound paints  
+  - `parseVariableId()` — parse "VariableID:sessionID:localID" strings
+- New exports: `VariableBinding`, `encodePaintWithVariableBinding`, `encodeNodeChangeWithVariables`, `parseVariableId`
+- `bind-fill-variable` plugin command — bind fill color to variable
+- `bind-stroke-variable` plugin command — bind stroke color to variable
+
+### Fixed
+
+- Message field mapping: nodeChanges is field 4, reconnectSequenceNumber is field 25
+- Paint variable binding format now matches Figma's exact wire format
+
+### Technical
+
+- Discovered Figma's variable binding wire format via WebSocket traffic analysis
+- Created capture/diff tools for binary protocol analysis (`scripts/capture.ts`, `scripts/diff-hex.ts`)
+- 142 tests passing
+
+## [0.3.0] - 2025-01-17
+
+### Added
+
+- **`render` command** — render React/TSX components directly to Figma
+  - From file: `figma-use render ./Card.figma.tsx`
+  - From stdin: `echo '<Frame style={{...}} />' | figma-use render --stdin`
+  - With props: `--props '{"title": "Hello"}'`
+  - Into parent: `--parent "1:23"`
+  - Dry run: `--dryRun` outputs NodeChanges JSON
+- **Multiplayer WebSocket connection pooling** in proxy
+  - First render: ~4s (establishes connection)
+  - Subsequent renders: ~0.4s (10x faster!)
+  - Connections auto-close after 5min idle
+- **React components** — `Frame`, `Text`, `Rectangle`, `Ellipse`, `Line`, `Star`, `Polygon`, `Vector`, `Component`, `Instance`, `Group`, `Page`, `View`
+- **JSX intrinsic elements** — PascalCase in JSX, lowercase in output
+- **culori integration** — robust color parsing (hex, rgb(), hsl(), named colors)
+- `/render` endpoint in proxy for direct NodeChanges submission
+- `/status` endpoint now shows multiplayer connection pool
+
+### Changed
+
+- Proxy now holds persistent WebSocket connections to Figma multiplayer
+- Architecture diagram updated to show dual communication paths
+- 143 tests passing
+
+### Fixed
+
+- TypeScript strict mode errors in tests
+- NodeChanges validation before sending (must have guid)
+
 ## [0.2.1] - 2025-01-17
 
 ### Added
@@ -137,7 +218,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Export commands: PNG/SVG/PDF export, screenshot
 - Inline styling: `--fill`, `--stroke`, `--radius` etc. on create commands
 
-[unreleased]: https://github.com/dannote/figma-use/compare/v0.2.1...HEAD
+[unreleased]: https://github.com/dannote/figma-use/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/dannote/figma-use/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/dannote/figma-use/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/dannote/figma-use/compare/v0.1.5...v0.2.0
 [0.1.5]: https://github.com/dannote/figma-use/compare/v0.1.4...v0.1.5

package/README.md

@@ -27,16 +27,28 @@ figma-use gives AI agents **full read/write control** over Figma.
 ## How it works
 
 ```
-┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│                 │     │                 │     │                 │
-│   AI Agent /    │────▶│   figma-use     │────▶│     Figma       │
-│   CLI           │ HTTP│   proxy         │ WS  │     Plugin      │
-│                 │◀────│   :38451        │◀────│                 │
-│                 │     │                 │     │                 │
-└─────────────────┘     └─────────────────┘     └─────────────────┘
+┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
+│                 │      │                 │      │                 │
+│   AI Agent /    │─────▶│   figma-use     │─────▶│     Figma       │
+│   CLI           │ HTTP │   proxy         │  WS  │     Plugin      │
+│                 │◀─────│   :38451        │◀─────│                 │
+│                 │      │                 │      │                 │
+└─────────────────┘      └────────┬────────┘      └─────────────────┘
+                                  │
+                                  │ WebSocket (persistent)
+                                  ▼
+                         ┌─────────────────┐
+                         │     Figma       │
+                         │   Multiplayer   │
+                         │     Server      │
+                         └─────────────────┘
 ```
 
-The CLI sends commands to a local proxy server, which forwards them via WebSocket to a Figma plugin. The plugin executes commands using the Figma API and returns results.
+Two communication paths:
+- **Plugin API** — most commands go through the Figma plugin for full API access
+- **Multiplayer WebSocket** — the `render` command writes directly to Figma's multiplayer server for ~100x faster node creation
+
+The proxy maintains persistent connections for fast repeated operations.
 
 ## Installation
 
@@ -226,10 +238,10 @@ figma-use viewport zoom-to-fit <ids...>
 ```bash
 figma-use find --name "Button"
 figma-use find --name "Icon" --type FRAME
-figma-use find --type INSTANCE              # Find all instances on current page
+figma-use find --type INSTANCE --limit 50   # Limit results (default: 100)
 figma-use get pages
 figma-use get components --name "Button"    # Filter by name
-figma-use get components --limit 50         # Limit results (default: 100)
+figma-use get components --limit 50         # Limit results (default: 50)
 figma-use get styles
 ```
 
@@ -246,6 +258,82 @@ figma-use group ungroup <id>
 figma-use group flatten "1:2,1:3"
 ```
 
+### Render React Components (Experimental)
+
+> ⚠️ **Experimental**: The React render feature uses Figma's internal multiplayer protocol, which is undocumented and may change without notice. Use for prototyping and automation, not production workflows.
+
+Render TSX/JSX components directly to Figma via WebSocket (bypasses plugin API for ~100x speed):
+
+```bash
+# From file
+figma-use render ./Card.figma.tsx
+
+# With props
+figma-use render ./Card.figma.tsx --props '{"title": "Hello", "items": ["A", "B"]}'
+
+# JSX snippet from stdin
+echo '<Frame style={{width: 200, height: 100, backgroundColor: "#FF0000"}} />' | figma-use render --stdin
+
+# Nested elements
+echo '<Frame style={{padding: 20, gap: 10}}>
+  <Text style={{fontSize: 24}}>Title</Text>
+  <Rectangle style={{width: 100, height: 50, backgroundColor: "#3B82F6"}} />
+</Frame>' | figma-use render --stdin
+
+# Full component from stdin (with imports/exports)
+cat component.tsx | figma-use render --stdin
+
+# Into specific parent
+figma-use render ./Card.figma.tsx --parent "1:23"
+
+# Dry run (output NodeChanges JSON without sending)
+figma-use render ./Card.figma.tsx --dryRun
+```
+
+**Important:** The `render` command requires:
+1. Figma running with remote debugging: `figma --remote-debugging-port=9222`
+2. Proxy server running: `figma-use proxy`
+
+The proxy maintains persistent WebSocket connections for fast repeated renders:
+- First render: ~4s (establishes connection)
+- Subsequent renders: ~0.4s (reuses connection)
+
+Example component (`Card.figma.tsx`):
+
+```tsx
+import * as React from 'react'
+import { Frame, Text, Rectangle } from '@dannote/figma-use/components'
+
+interface CardProps {
+  title: string
+  items: string[]
+}
+
+export default function Card({ title, items }: CardProps) {
+  return (
+    <Frame name="Card" style={{
+      width: 300,
+      flexDirection: 'column',
+      padding: 24,
+      gap: 16,
+      backgroundColor: '#FFFFFF',
+      borderRadius: 12,
+    }}>
+      <Text name="Title" style={{ fontSize: 24, fontWeight: 'bold', color: '#000' }}>
+        {title}
+      </Text>
+      <Frame name="Items" style={{ flexDirection: 'column', gap: 8 }}>
+        {items.map((item, i) => (
+          <Text key={i} style={{ fontSize: 16, color: '#666' }}>{item}</Text>
+        ))}
+      </Frame>
+    </Frame>
+  )
+}
+```
+
+Available elements: `Frame`, `Rectangle`, `Ellipse`, `Text`, `Line`, `Star`, `Polygon`, `Vector`, `Component`, `Instance`, `Group`, `Page`, `View`
+
 ### Advanced
 
 ```bash
@@ -357,3 +445,33 @@ Workflow:
 ## License
 
 MIT
+
+### Variable Bindings (Experimental)
+
+> ⚠️ **Experimental**: Variable binding uses reverse-engineered protocol. Supports `backgroundColor`, `borderColor`, and text `color`.
+
+Bind Figma variables to colors using human-readable names:
+
+```tsx
+// tokens.figma.ts
+import { defineVars } from '@dannote/figma-use'
+
+export const colors = defineVars({
+  primary: { name: 'Colors/Gray/50', value: '#F8FAFC' },
+  accent: { name: 'Colors/Blue/500', value: '#3B82F6' },
+  text: { name: 'Colors/Gray/900', value: '#0F172A' },
+})
+
+// Card.figma.tsx
+import { colors } from './tokens.figma'
+
+export function Card({ title }: { title: string }) {
+  return (
+    <Frame style={{ backgroundColor: colors.primary }}>
+      <Text style={{ color: colors.text }}>{title}</Text>
+    </Frame>
+  )
+}
+```
+
+The `value` field provides a fallback color for display. Variables are bound at the protocol level — no plugin API calls needed.

package/SKILL.md

@@ -148,6 +148,57 @@ figma-use group create "1:2,1:3"
 figma-use group ungroup <id>
 ```
 
+### Render React Components (Experimental)
+
+> ⚠️ Uses Figma's internal multiplayer protocol — may break without notice.
+
+Render TSX/JSX directly to Figma (~100x faster than plugin API):
+
+```bash
+# From file
+figma-use render ./Card.figma.tsx
+
+# JSX snippet from stdin
+echo '<Frame style={{width: 200, height: 100, backgroundColor: "#FF0000"}} />' | figma-use render --stdin
+
+# Nested elements
+echo '<Frame style={{padding: 20, gap: 10, flexDirection: "column"}}>
+  <Text style={{fontSize: 24, color: "#000"}}>Title</Text>
+  <Rectangle style={{width: 100, height: 50, backgroundColor: "#3B82F6"}} />
+</Frame>' | figma-use render --stdin
+
+# With props
+figma-use render ./Card.figma.tsx --props '{"title": "Hello"}'
+
+# Into specific parent
+figma-use render ./Card.figma.tsx --parent "1:23"
+```
+
+**Requires:**
+1. Figma with `figma --remote-debugging-port=9222`
+2. Proxy running: `figma-use proxy`
+
+Available elements: `Frame`, `Rectangle`, `Ellipse`, `Text`, `Line`, `Star`, `Polygon`, `Vector`, `Component`, `Instance`, `Group`
+
+#### Variable Bindings (Experimental)
+
+Bind Figma variables to colors by name with fallback values:
+
+```tsx
+import { defineVars, Frame } from '@dannote/figma-use'
+
+const colors = defineVars({
+  primary: { name: 'Colors/Gray/50', value: '#F8FAFC' },
+  border: { name: 'Colors/Gray/500', value: '#64748B' },
+})
+
+export default () => (
+  <Frame style={{ backgroundColor: colors.primary, borderColor: colors.border }} />
+)
+```
+
+Supports: `backgroundColor`, `borderColor`, text `color`.
+
 ### Eval (Arbitrary Code)
 
 ```bash

package/dist/.figma-render-1768690678858.tsx

@@ -0,0 +1,3 @@
+import * as React from 'react'
+const Frame: React.FC<any> = ({ children, ...props }) => React.createElement('frame', props, children)
+export default () => (<Frame style={{width: 200, height: 100, backgroundColor: "#FF0000"}} />)

package/dist/.figma-render-1768690686527.tsx

@@ -0,0 +1,3 @@
+import * as React from 'react'
+const Frame: React.FC<any> = ({ children, ...props }) => React.createElement('frame', props, children)
+export default () => (<Frame style={{width: 200, height: 100, backgroundColor: "#FF0000"}} />)