@dannote/figma-use 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **`profile` command** — performance profiling via Chrome DevTools Protocol
+  - Profile any command: `figma-use profile "get components --limit 20"`
+  - Shows time breakdown (Figma WASM vs JS vs GC)
+  - Lists top functions by CPU time
+  - Requires Figma with `--remote-debugging-port=9222`
+- `get components --name` — filter components by name
+- `get components --limit` — limit results (default 50)
+- `get components --page` — filter by page
+- `find --type` now works without `--name`
+
+### Changed
+
+- `get components` uses early-exit recursion for better performance on large files
+- `node tree --depth` now affects node count check (won't block with high depth limit)
+
+### Fixed
+
+- Variant components no longer crash when accessing `componentPropertyDefinitions`
+- 86 tests passing
+
 ## [0.2.0] - 2025-01-17
 
 ### Added
@@ -113,7 +168,9 @@ 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.0...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
 [0.1.4]: https://github.com/dannote/figma-use/compare/v0.1.3...v0.1.4

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
 
@@ -93,8 +105,9 @@ All create commands support inline styling — no need for separate `set` calls.
 ```bash
 figma-use node get <id>                    # Get node properties
 figma-use node tree [id]                   # Get formatted tree (default: current page)
-figma-use node tree --depth 2              # Limit tree depth
+figma-use node tree --depth 2              # Limit tree depth (also limits node count check)
 figma-use node tree -i                     # Only interactive elements
+figma-use node tree --force                # Skip 500 node limit
 figma-use node children <id>               # Get child nodes
 figma-use node delete <id>                 # Delete node
 figma-use node clone <id>                  # Clone node
@@ -225,8 +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 --limit 50   # Limit results (default: 100)
 figma-use get pages
-figma-use get components
+figma-use get components --name "Button"    # Filter by name
+figma-use get components --limit 50         # Limit results (default: 50)
 figma-use get styles
 ```
 
@@ -243,6 +258,80 @@ figma-use group ungroup <id>
 figma-use group flatten "1:2,1:3"
 ```
 
+### Render React Components
+
+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
@@ -255,6 +344,22 @@ figma-use eval "await figma.loadFontAsync({family: 'Inter', style: 'Bold'})"
 figma-use import --svg "<svg>...</svg>" --x 0 --y 0
 ```
 
+### Performance Profiling
+
+Profile any command using Chrome DevTools Protocol:
+
+```bash
+# Start Figma with debug port
+/Applications/Figma.app/Contents/MacOS/Figma --remote-debugging-port=9222
+
+# Profile a command
+figma-use profile "get components --limit 20"
+figma-use profile "node tree --depth 2"
+figma-use profile "find --type INSTANCE"
+```
+
+Output shows time breakdown (Figma WASM vs JS vs GC) and top functions by CPU time.
+
 ## Output Format
 
 Human-readable by default:

package/SKILL.md

@@ -52,8 +52,9 @@ figma-use create text --x 0 --y 0 --text "Hello" \
 ```bash
 figma-use node get <id>                      # Get properties
 figma-use node tree [id]                     # Get formatted tree (see structure at a glance)
-figma-use node tree --depth 2                # Limit tree depth
+figma-use node tree --depth 2                # Limit tree depth (also limits node count)
 figma-use node tree -i                       # Only interactive elements
+figma-use node tree --force                  # Skip 500 node limit
 figma-use node children <id>                 # List children
 figma-use node move <id> --x 100 --y 200
 figma-use node resize <id> --width 300 --height 200
@@ -133,7 +134,9 @@ figma-use viewport zoom-to-fit <ids...>
 ```bash
 figma-use find --name "Button"
 figma-use find --type FRAME
-figma-use get components
+figma-use find --type INSTANCE              # All instances on page
+figma-use get components --name "Button"    # Filter components by name
+figma-use get components --limit 50         # Limit results
 ```
 
 ### Boolean & Group
@@ -145,6 +148,36 @@ figma-use group create "1:2,1:3"
 figma-use group ungroup <id>
 ```
 
+### Render React Components
+
+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`
+
 ### 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"}} />)