@dannote/figma-use 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ 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
@@ -137,7 +168,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,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

package/SKILL.md

@@ -148,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"}} />)