@dannote/figma-use 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-01-18
+
+### Fixed
+
+- Multiplayer connection works with Figma's updated protocol (sessionID now from plugin API)
+- Proxy properly handles file switches (closes stale connections)
+- `figma-use status` now shows full connection diagnostics (proxy, plugin, DevTools, file)
+
+## [0.5.1] - 2026-01-18
+
+### Added
+
+- Package exports for `@dannote/figma-use/render` and `@dannote/figma-use/components`
+
+### Fixed
+
+- SKILL.md now starts with connection check instructions
+- Simplified SKILL.md for better AI agent comprehension
+
 ## [0.5.0] - 2026-01-18
 
 ### Added

package/SKILL.md

@@ -7,277 +7,156 @@ description: Control Figma via CLI — create shapes, frames, text, components,
 
 Full control over Figma from the command line.
 
-## Setup
+## Before You Start
 
-```bash
-bun install -g @dannote/figma-use
-figma-use plugin     # Install plugin (quit Figma first!)
-figma-use proxy      # Start proxy server
-# Open Figma → Plugins → Development → Figma Use
-```
-
-## Quick Reference
-
-### Create Shapes
+**Always check connection first:**
 
 ```bash
-figma-use create rect --x 0 --y 0 --width 100 --height 50 --fill "#FF0000" --radius 8
-figma-use create ellipse --x 0 --y 0 --width 80 --height 80 --fill "#00FF00"
-figma-use create line --x 0 --y 0 --length 100 --stroke "#000"
-figma-use create polygon --x 0 --y 0 --size 60 --sides 6 --fill "#F59E0B"
-figma-use create star --x 0 --y 0 --size 60 --points 5 --fill "#EF4444"
+figma-use status
 ```
 
-### Create Frames (with auto-layout)
-
+If not connected:
 ```bash
-figma-use create frame --x 0 --y 0 --width 400 --height 300 \
-  --fill "#FFF" --radius 12 --name "Card" \
-  --layout VERTICAL --gap 16 --padding "24,24,24,24"
+# 1. Start proxy (keep running in background)
+figma-use proxy &
 
-figma-use create frame --x 0 --y 0 --width 200 --height 48 \
-  --fill "#3B82F6" --radius 8 --name "Button" \
-  --layout HORIZONTAL --gap 8 --padding "12,24,12,24"
-```
+# 2. Start Figma with debug port (for render command)
+figma --remote-debugging-port=9222
 
-### Create Text
-
-```bash
-figma-use create text --x 0 --y 0 --text "Hello" \
-  --fontSize 24 --fontFamily "Inter" --fontStyle "Bold" --fill "#000"
+# 3. In Figma: Plugins → Development → Figma Use
 ```
 
-### Node Operations
-
+If plugin not installed:
 ```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 (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
-figma-use node rename <id> "New Name"
-figma-use node clone <id>
-figma-use node delete <id>
+# Quit Figma first, then:
+figma-use plugin
 ```
 
-`tree` output example:
-```
-[0] frame "Card" (1:23)
-    400×300 at (0, 0) | fill: #FFFFFF | layout: col gap=16
-  [0] text "Title" (1:24)
-      200×32 at (24, 24) | "Hello World" | font: 24px Inter
-```
+---
+
+## JSX Rendering (Fastest Way)
 
-### Set Properties
+For complex layouts, use `render --stdin` with pure JSX. No imports needed — elements are built-in:
 
 ```bash
-figma-use set fill <id> "#FF0000"
-figma-use set stroke <id> "#000" --weight 2
-figma-use set radius <id> --radius 12
-figma-use set radius <id> --topLeft 16 --bottomRight 16
-figma-use set opacity <id> 0.8
-figma-use set rotation <id> 45
-figma-use set text <id> "Updated text"
-figma-use set font <id> --family "Inter" --style "Bold" --size 20
-figma-use set layout <id> --mode HORIZONTAL --gap 8 --padding 16
-figma-use set effect <id> --type DROP_SHADOW --radius 10 --offsetY 4 --color "#00000040"
+echo '<Frame style={{padding: 24, gap: 16, flexDirection: "column", backgroundColor: "#FFF", borderRadius: 12}}>
+  <Text style={{fontSize: 24, fontWeight: "bold", color: "#000"}}>Card Title</Text>
+  <Text style={{fontSize: 14, color: "#666"}}>Description text here</Text>
+</Frame>' | figma-use render --stdin
 ```
 
-### Variables (Design Tokens)
+**Elements:** `Frame`, `Rectangle`, `Ellipse`, `Text`, `Line`, `Star`, `Polygon`, `Vector`, `Group`
 
-```bash
-figma-use collection list
-figma-use collection create "Colors"
+**Style props:** `width`, `height`, `x`, `y`, `padding`, `paddingTop/Right/Bottom/Left`, `gap`, `flexDirection` (row|column), `justifyContent`, `alignItems`, `backgroundColor`, `borderColor`, `borderWidth`, `borderRadius`, `opacity`, `fontSize`, `fontFamily`, `fontWeight`, `color`, `textAlign`
 
-figma-use variable list --type COLOR
-figma-use variable create "Primary" --collection <collectionId> --type COLOR --value "#3B82F6"
-figma-use variable set <varId> --mode <modeId> --value "#1D4ED8"
-figma-use variable bind --node <nodeId> --field fills --variable <varId>
-```
-
-### Styles
+### Buttons Example (3 sizes)
 
 ```bash
-figma-use style list
-figma-use style create-paint "Brand/Primary" --color "#E11D48"
-figma-use style create-text "Heading/H1" --family "Inter" --style "Bold" --size 32
+echo '<Frame style={{gap: 16, flexDirection: "row", padding: 24}}>
+  <Frame name="Small" style={{paddingLeft: 12, paddingRight: 12, paddingTop: 6, paddingBottom: 6, backgroundColor: "#3B82F6", borderRadius: 6, flexDirection: "row", justifyContent: "center", alignItems: "center"}}>
+    <Text style={{fontSize: 12, color: "#FFF"}}>Button</Text>
+  </Frame>
+  <Frame name="Medium" style={{paddingLeft: 16, paddingRight: 16, paddingTop: 8, paddingBottom: 8, backgroundColor: "#3B82F6", borderRadius: 6, flexDirection: "row", justifyContent: "center", alignItems: "center"}}>
+    <Text style={{fontSize: 14, color: "#FFF"}}>Button</Text>
+  </Frame>
+  <Frame name="Large" style={{paddingLeft: 24, paddingRight: 24, paddingTop: 12, paddingBottom: 12, backgroundColor: "#3B82F6", borderRadius: 6, flexDirection: "row", justifyContent: "center", alignItems: "center"}}>
+    <Text style={{fontSize: 16, color: "#FFF"}}>Button</Text>
+  </Frame>
+</Frame>' | figma-use render --stdin
 ```
 
-### Export
+### Advanced: Components & Variants
 
-```bash
-figma-use export node <id> --format PNG --scale 2 --output design.png
-figma-use export screenshot --output viewport.png
-figma-use export selection --output selection.png
-```
+For `defineComponent`, `defineComponentSet`, `defineVars` — use files with imports:
 
-Heavy ops support `--timeout` (seconds):
 ```bash
-figma-use export node <id> --timeout 300
+figma-use render --examples  # Full API reference
+figma-use render ./MyComponent.figma.tsx
 ```
 
-### Selection & Navigation
+---
 
-```bash
-figma-use selection get
-figma-use selection set "1:2,1:3"
-figma-use page list
-figma-use page set "Page Name"
-figma-use viewport zoom-to-fit <ids...>
-```
+## CLI Commands
 
-### Find
+### Create
 
 ```bash
-figma-use find --name "Button"
-figma-use find --type FRAME
-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
+figma-use create frame --width 400 --height 300 --fill "#FFF" --radius 12 --layout VERTICAL --gap 16
+figma-use create rect --width 100 --height 50 --fill "#FF0000" --radius 8
+figma-use create ellipse --width 80 --height 80 --fill "#00FF00"
+figma-use create text --text "Hello" --fontSize 24 --fill "#000"
+figma-use create line --length 100 --stroke "#000"
 ```
 
-### Boolean & Group
+### Query
 
 ```bash
-figma-use boolean union "1:2,1:3"
-figma-use boolean subtract "1:2,1:3"
-figma-use group create "1:2,1:3"
-figma-use group ungroup <id>
+figma-use node get <id>           # Node properties
+figma-use node tree               # Page structure
+figma-use node tree --depth 2     # Limit depth
+figma-use node children <id>      # Children list
+figma-use find --name "Button"    # Find by name
+figma-use find --type FRAME       # Find by type
+figma-use selection get           # Current selection
 ```
 
-### 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):
+### Modify
 
 ```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"
+figma-use set fill <id> "#FF0000"
+figma-use set stroke <id> "#000" --weight 2
+figma-use set radius <id> 12
+figma-use set opacity <id> 0.5
+figma-use set text <id> "New text"
+figma-use set font <id> --family "Inter" --style "Bold" --size 20
+figma-use set layout <id> --mode VERTICAL --gap 12 --padding 16
+figma-use node move <id> --x 100 --y 200
+figma-use node resize <id> --width 300 --height 200
+figma-use node delete <id>
 ```
 
-**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`
-
-#### Reusable Components
-
-**defineComponent** — simple reusable component:
-```tsx
-import { defineComponent, Frame, Text } from '@dannote/figma-use/render'
-
-const Button = defineComponent('Button',
-  <Frame style={{ padding: 12, backgroundColor: '#3B82F6', borderRadius: 8 }}>
-    <Text style={{ color: '#FFF' }}>Click me</Text>
-  </Frame>
-)
+### Export
 
-export default () => (
-  <Frame style={{ gap: 16, flexDirection: 'column' }}>
-    <Button />  {/* Creates Component */}
-    <Button />  {/* Creates Instance */}
-    <Button />  {/* Creates Instance */}
-  </Frame>
-)
+```bash
+figma-use export node <id> --output design.png
+figma-use export screenshot --output viewport.png
+figma-use export selection --output selection.png
 ```
 
-**defineComponentSet** — component with variants:
-```tsx
-import { defineComponentSet, Frame, Text } from '@dannote/figma-use/render'
-
-const Button = defineComponentSet('Button', {
-  variant: ['Primary', 'Secondary'] as const,
-  size: ['Small', 'Large'] as const,
-}, ({ variant, size }) => (
-  <Frame style={{ 
-    padding: size === 'Large' ? 16 : 8,
-    backgroundColor: variant === 'Primary' ? '#3B82F6' : '#E5E7EB',
-    borderRadius: 8,
-    flexDirection: 'row',
-    justifyContent: 'center',
-  }}>
-    <Text style={{ 
-      fontSize: size === 'Large' ? 16 : 14,
-      color: variant === 'Primary' ? '#FFF' : '#111',
-    }}>
-      {variant} Button
-    </Text>
-  </Frame>
-))
+### Navigate
 
-export default () => (
-  <Frame style={{ gap: 16, flexDirection: 'column' }}>
-    <Button variant="Primary" size="Large" />
-    <Button variant="Primary" size="Small" />
-    <Button variant="Secondary" size="Large" />
-  </Frame>
-)
+```bash
+figma-use page list
+figma-use page set "Page Name"
+figma-use viewport zoom-to-fit <ids...>
 ```
 
-Creates a real Figma ComponentSet with all variant combinations.
-
-#### Variable Bindings (Experimental)
-
-Bind Figma variables to colors by name with fallback values:
-
-```tsx
-import { defineVars, Frame } from '@dannote/figma-use'
+### Variables & Styles
 
-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 }} />
-)
+```bash
+figma-use variable list
+figma-use variable create "Primary" --collection <id> --type COLOR --value "#3B82F6"
+figma-use style list
+figma-use style create-paint "Brand/Primary" --color "#E11D48"
 ```
 
-Supports: `backgroundColor`, `borderColor`, text `color`.
-
-### Eval (Arbitrary Code)
+### Escape Hatch
 
 ```bash
 figma-use eval "return figma.currentPage.name"
-figma-use eval "const r = figma.createRectangle(); r.resize(100, 100); return r.id"
+figma-use eval "figma.createRectangle().resize(100, 100)"
 ```
 
+---
+
 ## Output
 
-Human-readable by default. Add `--json` for machine parsing:
-```bash
-figma-use node get <id> --json
-```
+Human-readable by default. Add `--json` for machine parsing.
 
 ## Colors
 
-Hex format: `#RGB`, `#RRGGBB`, or `#RRGGBBAA`
+Hex format: `#RGB`, `#RRGGBB`, `#RRGGBBAA`
 
 ## Node IDs
 
-Format: `pageIndex:nodeIndex` (e.g., `1:2`, `45:123`)
-
-Get IDs from:
-- `figma-use selection get`
-- `figma-use node children <parentId>`
-- Figma → right-click → Copy link → ID in URL
+Format: `sessionID:localID` (e.g., `1:2`, `45:123`). Get from `figma-use selection get` or `figma-use node tree`.

package/dist/cli/index.js

@@ -22839,16 +22839,49 @@ async function getParentGUID() {
 
 // packages/cli/src/commands/status.ts
 var status_default = defineCommand({
-  meta: { description: "Check if plugin is connected" },
+  meta: { description: "Check connection status (plugin, DevTools, multiplayer)" },
   args: { json: { type: "boolean", description: "Output as JSON" } },
   async run({ args }) {
+    const result = {
+      proxy: false,
+      plugin: false,
+      devtools: false,
+      fileKey: null,
+      multiplayer: false
+    };
     try {
       const status = await getStatus();
-      console.log(status.pluginConnected ? "\u2713 Plugin connected" : "\u2717 Plugin not connected");
-    } catch {
-      console.log("\u2717 Proxy not running");
-      process.exit(1);
+      result.proxy = true;
+      result.plugin = status.pluginConnected;
+    } catch {}
+    try {
+      result.fileKey = await getFileKey();
+      result.devtools = true;
+      result.multiplayer = true;
+    } catch {}
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
     }
+    console.log(result.proxy ? "\u2713 Proxy running" : "\u2717 Proxy not running (run: figma-use proxy)");
+    console.log(result.plugin ? "\u2713 Plugin connected" : "\u2717 Plugin not connected (open plugin in Figma)");
+    console.log(result.devtools ? "\u2713 DevTools available" : "\u2717 DevTools not available (run: figma --remote-debugging-port=9222)");
+    if (result.devtools) {
+      if (result.fileKey) {
+        console.log(`\u2713 Figma file ready (${result.fileKey})`);
+      } else {
+        console.log("\u2717 No Figma file open (open a file from figma.com, not local)");
+      }
+    }
+    if (result.proxy && result.plugin && result.multiplayer) {
+      console.log(`
+\u2713 Ready for render command`);
+    } else if (result.proxy && result.plugin) {
+      console.log(`
+\u26A0 CLI commands work, but render requires DevTools + Figma file`);
+    }
+    if (!result.proxy)
+      process.exit(1);
   }
 });
 // packages/cli/src/commands/proxy.ts

package/dist/proxy/index.js

@@ -4637,22 +4637,6 @@ var init_prompt = __esm(() => {
 });
 
 // packages/cli/src/multiplayer/protocol.ts
-function parseVarint(data, pos) {
-  let value = 0;
-  let shift = 0;
-  while (pos < data.length) {
-    const byte2 = data[pos];
-    if (byte2 === undefined)
-      break;
-    pos++;
-    value |= (byte2 & KIWI.VARINT_VALUE_MASK) << shift;
-    if (!(byte2 & KIWI.VARINT_CONTINUE_BIT)) {
-      break;
-    }
-    shift += KIWI.VARINT_BITS_PER_BYTE;
-  }
-  return [value, pos];
-}
 function isKiwiMessage(data) {
   return data.length >= 2 && data[0] === KIWI.MESSAGE_MARKER;
 }
@@ -4684,7 +4668,7 @@ function buildMultiplayerUrl(fileKey, trackingId) {
   });
   return `wss://www.figma.com/api/multiplayer/${fileKey}?${params}`;
 }
-var MESSAGE_TYPES, ZSTD_MAGIC, KIWI, SESSION_ID, FIG_WIRE_MAGIC = "fig-wire", PROTOCOL_VERSION = 151;
+var MESSAGE_TYPES, ZSTD_MAGIC, KIWI, FIG_WIRE_MAGIC = "fig-wire", PROTOCOL_VERSION = 151;
 var init_protocol = __esm(() => {
   MESSAGE_TYPES = {
     JOIN_START: 0,
@@ -4711,10 +4695,6 @@ var init_protocol = __esm(() => {
     VARINT_VALUE_MASK: 127,
     VARINT_BITS_PER_BYTE: 7
   };
-  SESSION_ID = {
-    MIN: 1e4,
-    MAX: 1e6
-  };
 });
 
 // node_modules/kiwi-schema/kiwi-esm.js
@@ -11868,12 +11848,6 @@ class FigmaMultiplayerClient {
           if (!isKiwiMessage(decompressed))
             return;
           const msgType = getKiwiMessageType(decompressed);
-          if (msgType === MESSAGE_TYPES.JOIN_START && decompressed[2] === KIWI.SESSION_ID_FIELD) {
-            const [val] = parseVarint(decompressed, 3);
-            if (val > SESSION_ID.MIN && val < SESSION_ID.MAX) {
-              sessionID = val;
-            }
-          }
           if (msgType === MESSAGE_TYPES.JOIN_END) {
             joinEndReceived = true;
           }
@@ -11890,10 +11864,10 @@ class FigmaMultiplayerClient {
               this.options.onMessage(message);
             } catch {}
           }
-          if (sessionID && reconnectSequenceNumber && joinEndReceived && (this.state === "connecting" || this.state === "connected")) {
+          if (joinEndReceived && (this.state === "connecting" || this.state === "connected")) {
             clearTimeout(timeout);
             this.state = "ready";
-            this.sessionInfo = { sessionID, reconnectSequenceNumber };
+            this.sessionInfo = { sessionID: sessionID || 0, reconnectSequenceNumber };
             resolve(this.sessionInfo);
           }
         } catch {}
@@ -11967,6 +11941,9 @@ class FigmaMultiplayerClient {
   isReady() {
     return this.state === "ready";
   }
+  isConnected() {
+    return this.state === "connected" && this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
   close() {
     if (this.ws) {
       this.ws.close();
@@ -26821,11 +26798,23 @@ function cleanupIdleConnections() {
 }
 async function getMultiplayerConnection(fileKey) {
   await ensureInitialized();
+  for (const [key, conn] of connectionPool) {
+    if (key !== fileKey) {
+      consola.info(`Closing stale connection to ${key} (switched to ${fileKey})`);
+      conn.client.close();
+      connectionPool.delete(key);
+    }
+  }
   const existing = connectionPool.get(fileKey);
   if (existing) {
-    existing.lastUsed = Date.now();
-    consola.debug(`Reusing multiplayer connection for ${fileKey}`);
-    return { client: existing.client, sessionID: existing.sessionID };
+    if (existing.client.isConnected()) {
+      existing.lastUsed = Date.now();
+      consola.debug(`Reusing multiplayer connection for ${fileKey}`);
+      return { client: existing.client, sessionID: existing.sessionID };
+    } else {
+      consola.warn(`Multiplayer connection to ${fileKey} died, reconnecting...`);
+      connectionPool.delete(fileKey);
+    }
   }
   consola.info(`Creating multiplayer connection for ${fileKey}`);
   const cookies = await getCookiesFromDevTools2();

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@dannote/figma-use",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Control Figma from the command line. Full read/write access for AI agents.",
   "type": "module",
   "bin": {
     "figma-use": "bin/figma-use.js"
   },
+  "exports": {
+    ".": "./dist/cli/index.js",
+    "./render": "./packages/cli/src/render/index.ts",
+    "./components": "./packages/cli/src/render/components.tsx"
+  },
   "scripts": {
     "build": "bun run build:proxy && bun run build:cli && bun run build:plugin",
     "build:proxy": "bun build packages/proxy/src/index.ts --outdir dist/proxy --target bun",
@@ -18,6 +23,7 @@
   "files": [
     "bin",
     "dist",
+    "packages/cli/src/render",
     "packages/plugin/dist",
     "README.md",
     "CHANGELOG.md",