@todoforai/figma-api 1.0.5 → 1.0.7

package/AGENTS.md

@@ -6,9 +6,9 @@ Read this before using `figma-api`. It tells you exactly what to set up.
 
 - Need to **read** designs, or **write** comments / dev-resources / webhooks?
   → REST is enough. Just set a token (step 1). Works headless / in CI.
-- Need to **create canvas nodes** (frames, text, shapes) or **edit variables**
-  off-Enterprise? → REST can't. Use the **plugin bridge** (step 2). Requires the
-  Figma desktop app open.
+- Need to **create canvas nodes** (frames, text, shapes)? → REST can't. Use the
+  **plugin bridge** (step 2). Requires a plugin connected in the Figma **desktop**
+  app (browser can't reach the localhost relay — see gotchas).
 
 ## 1. Auth (always required)
 
@@ -28,54 +28,80 @@ FIGMA_TOKEN=<token> figma-api me
 - File commands accept a raw file key **or** a Figma URL; `node-id` is parsed from
   the URL automatically.
 
-## 2. Plugin bridge (only for canvas writes / variables off-Enterprise)
+## 2. Plugin bridge (only for canvas writes)
 
 The Figma REST API has **no endpoint** to create canvas nodes. The Figma Plugin
-API does. The bridge lets the CLI drive a companion plugin:
+API does. The bridge is a **WebSocket relay** that drives a companion plugin. It
+speaks the **cursor-talk-to-figma** protocol, so it's interchangeable with that
+ecosystem (their MCP server can drive our plugin and vice versa).
 
 ```
-figma-api run '<code>'  ──POST──▶  relay  ◀──poll──  Figma plugin  → runs on canvas
+figma-api create-frame …  ──ws──▶  relay  ◀──ws──  Figma plugin  → runs on canvas
+                          (join channel, broadcast)
 ```
 
 Setup (do all three, in order):
 
 1. **Start the relay** (keep it running, background it):
    ```bash
-   figma-api bridge          # listens on http://localhost:8917
+   figma-api bridge          # WebSocket relay on ws://localhost:3055
    ```
-2. **Load the plugin** — this is a human step, you cannot automate it:
-   In the **Figma desktop app** (browser can't import dev plugins):
-   Plugins → Development → Import plugin from manifest → pick this package's
-   `plugin/manifest.json`. Run it, paste the relay URL, click **Connect**.
-3. **Drive it**:
+2. **Connect a plugin** — a human step, you cannot automate it. Pick ONE:
+   - **Easy (recommended):** install **"Cursor Talk To Figma MCP"** from the
+     Figma Community (figma.com/community/plugin/1485687494525374295), run it in
+     the **desktop** app, set port `3055`, click **Connect**. It auto-picks a
+     random channel — that's fine: the relay bridges channels, so you do **not**
+     copy it or pass `--channel`.
+   - **Advanced:** in the Figma **desktop** app, Plugins → Development → Import
+     plugin from manifest → this package's `plugin/manifest.json`. Run it, set URL
+     `ws://localhost:3055`, channel `figma-api`, click **Connect**.
+3. **Drive it** with named commands:
    ```bash
    figma-api ping            # round-trip check; prints page + selection
-   figma-api run 'const t=figma.createText(); await figma.loadFontAsync({family:"Inter",style:"Regular"}); t.characters="Hi"; figma.currentPage.appendChild(t); return t'
-   figma-api run @script.js  # or load code from a file
+   figma-api create-frame --width 320 --height 200 --fill "#1F6FEB" --name Card
+   figma-api create-text "Hi" --size 24 --parent 10:5
+   figma-api set-fill-color 10:5 "#FF0044"
+   figma-api get-selection
    ```
 
-`run` executes arbitrary Plugin API code (`figma` in scope, `await` + `return`
-supported; returned nodes come back as `{id,type,name}`). It subsumes any
-draw/create helper — prefer it over inventing new commands.
+Every canvas command takes `--relay <ws-url>` / `--channel <name>` (defaults
+`ws://localhost:3055` / `figma-api`; or `FIGMA_RELAY` / `FIGMA_CHANNEL` env).
+
+**Escape hatch:** for anything the named commands don't cover, `run` executes
+arbitrary Plugin API code (`figma` in scope, `await` + `return` supported;
+returned nodes come back as `{id,type,name}`):
+```bash
+figma-api run 'return figma.currentPage.selection.map(n => n.name)'
+figma-api run @script.js
+```
+Prefer the named `create-*`/`set-*`/`get-*` commands; reach for `run` only for
+gaps they don't fill.
 
 Cross-machine (CLI and Figma on different hosts): expose the relay publicly with
-`cloudflared tunnel --url http://localhost:8917` and paste that https URL into
+`cloudflared tunnel --url http://localhost:3055` and paste that `wss://` URL into
 the plugin instead of localhost.
 
 ## Gotchas an agent will hit
 
 - **REST `variables-modify` → 403** on non-Enterprise tokens. Don't retry; switch
-  to `figma-api run` with `figma.variables.*`.
+  to `figma-api run` with `figma.variables.*` (off-Enterprise, via the bridge).
 - **"create a frame/text/shape via REST"** is impossible — there is no endpoint.
-  Use the bridge.
-- **Browser-only Figma can't load the dev plugin.** Needs the desktop app, or a
-  published plugin. If the user is browser-only and refuses desktop, canvas
-  writes are not available — say so plainly.
+  Use the bridge (`create-frame`/`create-text`/…).
+- **Use the DESKTOP app for canvas writes.** Both plugins can be *opened* in
+  browser Figma, but a browser tab can't connect to `ws://localhost:3055`
+  (mixed-content: an https page blocks insecure `ws`), so it never reaches
+  "Connected" — this is the usual "plugin won't connect on Linux/browser" cause.
+  Desktop has no such block. Dev-manifest import is desktop-only regardless. If
+  desktop is truly impossible, expose the relay over TLS (`cloudflared tunnel
+  --url http://localhost:3055`) and paste the `wss://` URL into the plugin.
+- **Channel names don't need to match.** The relay bridges across channels, so the
+  community plugin's random channel and the CLI's `figma-api` default interoperate
+  with no `--channel` flag.
 - **`figma-api run` / the relay have no auth** and execute arbitrary code in the
   user's document. Only run on a trusted machine; don't expose the tunnel URL
   publicly; don't run untrusted code.
 - The bridge handles **one command at a time, one connected plugin**. Don't fan
-  out parallel `run` calls.
+  out parallel canvas calls.
 - The CLI exits non-zero on plugin error/timeout — check exit codes.
 
 ## Quick reference
@@ -83,4 +109,7 @@ the plugin instead of localhost.
 `figma-api --help` lists every command; `figma-api <cmd> --help` has params,
 scopes and examples. Read = me/file/nodes/images/comments/components/styles/
 variables-*/dev-resources/webhooks/… Write (REST) = comment-add/reaction-add/
-variables-modify/dev-resource-*/webhook-*. Canvas write = bridge + run.
+variables-modify/dev-resource-*/webhook-*. Canvas (bridge) = create-frame/
+create-rectangle/create-text/set-fill-color/set-text/move-node/resize-node/
+clone-node/delete-node/get-selection/get-node-info/export-image/focus/select/…
++ `run` escape hatch.

package/README.md

@@ -53,40 +53,61 @@ Run `figma-api <command> --help` for parameters, scopes and examples.
 
 ## Plugin bridge — canvas writes
 
-The REST API **cannot create canvas nodes** (frames/text/shapes) or edit variables
-off-Enterprise. The Figma **Plugin API** can. The bridge lets the CLI drive a small
-companion plugin:
+The REST API **cannot create canvas nodes** (frames/text/shapes). The Figma
+**Plugin API** can. The bridge lets the CLI drive a small companion plugin over a
+WebSocket relay. It speaks the **[cursor-talk-to-figma](https://github.com/grab/cursor-talk-to-figma-mcp)
+protocol**, so the pieces are interchangeable: that ecosystem's MCP server can
+drive our plugin, and our CLI can drive theirs.
 
 ```
-figma-api run '...'  ──POST──▶  relay (figma-api bridge)  ◀──poll──  Figma plugin
-                                                          ──result─▶  (runs on canvas)
+figma-api create-frame …  ──ws──▶  relay (figma-api bridge)  ◀──ws──  Figma plugin
+                          (join channel, broadcast)          ──result─▶ (runs on canvas)
 ```
 
 Setup:
 
-1. `figma-api bridge` — start the relay (keep it running).
-2. Figma **desktop** → Plugins → Development → **Import plugin from manifest** →
-   `plugin/manifest.json`. Run it, paste the relay URL, click **Connect**.
-3. Drive it from the CLI:
+1. `figma-api bridge` — start the WebSocket relay (keep it running).
+2. Connect a plugin in the Figma **desktop** app — pick one:
+   - **Easy (recommended):** install [**Cursor Talk To Figma MCP**](https://www.figma.com/community/plugin/1485687494525374295)
+     from the Figma Community, run it, set port `3055`, click **Connect**. It picks
+     a random channel — that's fine, the relay bridges channels so you don't copy
+     it or pass `--channel`.
+   - **Advanced:** Plugins → Development → **Import plugin from manifest** →
+     `plugin/manifest.json`. Run it, set URL `ws://localhost:3055`, channel
+     `figma-api`, click **Connect**.
+3. Drive it from the CLI with named commands:
 
 ```bash
 figma-api ping
-figma-api run 'const t = figma.createText(); await figma.loadFontAsync({family:"Inter",style:"Regular"}); t.characters="Hi from the CLI"; figma.currentPage.appendChild(t); return t'
-figma-api run @make-card.js
+figma-api create-frame --width 320 --height 200 --fill "#1F6FEB" --name Card
+figma-api create-text "Hello" --size 24 --weight 700 --color "#111" --parent 10:5
+figma-api set-fill-color 10:5 "#FF0044"
+figma-api get-selection
 ```
 
-`run` executes arbitrary Figma Plugin API code (`figma` in scope, `await` and
-`return` supported), so it subsumes any draw/create helper.
+All commands take `--relay <ws-url>` and `--channel <name>` (defaults
+`ws://localhost:3055` / `figma-api`; override via `FIGMA_RELAY` / `FIGMA_CHANNEL`).
+
+Escape hatch — for anything the named commands don't cover, `run` executes
+arbitrary Plugin API code (`figma` in scope, `await`/`return` supported):
+
+```bash
+figma-api run 'return figma.currentPage.selection.map(n => n.name)'
+figma-api run @make-card.js
+```
 
-Cross-machine: `cloudflared tunnel --url http://localhost:8917` and paste that
-https URL into the plugin.
+Cross-machine: `cloudflared tunnel --url http://localhost:3055` and paste the
+`wss://` URL into the plugin.
 
 > ⚠️ **Security:** the relay has no auth and `run` executes arbitrary code in your
 > Figma document. Only use it on a trusted machine/network; don't expose the tunnel
 > URL publicly or run code you don't trust.
 
-> Note: development (unpublished) plugins can only be imported in the **Figma
-> desktop app**, not the browser. Once published, the browser works too.
+> Note: use the **Figma desktop app**. A browser tab can't reach `ws://localhost:3055`
+> (an https page blocks insecure `ws` as mixed content), so the plugin never reaches
+> "Connected" — the usual "won't connect in the browser" cause. Dev-manifest import
+> is desktop-only regardless. If desktop is impossible, expose the relay over TLS
+> (`cloudflared tunnel --url http://localhost:3055`) and paste the `wss://` URL in.
 
 ## Why both REST and a plugin?
 
@@ -95,7 +116,6 @@ https URL into the plugin.
 | Files / nodes / images (read) | ✅ | ✅ |
 | Comments, dev resources, webhooks | ✅ | — |
 | Create frames / text / shapes | ❌ (no endpoint) | ✅ |
-| Edit variables off-Enterprise | ❌ (403) | ✅ |
 | Works headless / CI | ✅ | needs Figma open |
 
 ## Reference
@@ -103,8 +123,8 @@ https URL into the plugin.
 - [figma/rest-api-spec](https://github.com/figma/rest-api-spec) — authoritative endpoint list.
 - [GLips/Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) — read design-context MCP.
 - [Official Figma MCP](https://help.figma.com/hc/en-us/articles/32132100833559) — `mcp.figma.com`.
-- The bridge mirrors the architecture of community plugin bridges (e.g.
-  southleft/figma-console-mcp) but driven by a plain CLI instead of MCP.
+- [grab/cursor-talk-to-figma-mcp](https://github.com/grab/cursor-talk-to-figma-mcp) —
+  the WebSocket bridge protocol this plugin implements (interchangeable clients).
 
 ## Dev
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@todoforai/figma-api",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Figma CLI — full REST API wrapper (files, comments, variables, webhooks…) plus a plugin bridge for canvas writes.",
   "type": "module",
   "bin": {
@@ -20,7 +20,9 @@
     "rest",
     "design",
     "plugin",
-    "mcp"
+    "mcp",
+    "cursor-talk-to-figma",
+    "websocket"
   ],
   "repository": {
     "type": "git",

package/plugin/code.js

@@ -1,10 +1,14 @@
-// figma-api bridge plugin. The UI (ui.html) long-polls the relay, forwards each
-// command here, this runs it and returns the result. The REST API can't create
-// canvas nodes or edit variables off-Enterprise — the Plugin API can, and the
-// figma-api CLI drives it through `figma-api run`.
+// figma-api bridge plugin — talks the cursor-talk-to-figma WebSocket protocol so
+// it's a drop-in for that ecosystem (its MCP server can drive this plugin), while
+// staying small. The UI (ui.html) joins a WS channel on the relay, forwards each
+// {command,params} here, this runs it and returns the result.
+//
+// Two ways to drive it:
+//   • named commands (create_frame, set_fill_color, …) — cursor-talk-to-figma compatible
+//   • "eval" — run arbitrary Plugin API code (our extra; droppable, but handy)
 
-// Serialize a value for JSON transport: Figma nodes → {id,type,name}, recurse
-// plain objects/arrays, guard against cycles and unstringifiable values.
+// ── serialization ────────────────────────────────────────────────────────────
+// Figma nodes → {id,type,name}; recurse plain objects/arrays; guard cycles/bigints.
 function serialize(v, seen) {
   if (v == null || typeof v === "boolean" || typeof v === "number" || typeof v === "string") return v;
   if (typeof v === "bigint") return v.toString();
@@ -19,29 +23,278 @@ function serialize(v, seen) {
   return o;
 }
 
-async function exec(cmd) {
-  if (cmd.op === "ping") {
-    return { pong: true, page: figma.currentPage.name, selection: figma.currentPage.selection.map((n) => n.id) };
+// ── small helpers ────────────────────────────────────────────────────────────
+async function byId(id) {
+  if (!id) throw new Error("Missing nodeId parameter");
+  const n = await figma.getNodeByIdAsync(id);
+  if (!n) throw new Error(`Node not found with ID: ${id}`);
+  return n;
+}
+async function appendTo(node, parentId) {
+  if (parentId) {
+    const p = await byId(parentId);
+    if (!("appendChild" in p)) throw new Error(`Parent node does not support children: ${parentId}`);
+    p.appendChild(node);
+  } else figma.currentPage.appendChild(node);
+}
+const solid = (c) => ({ type: "SOLID", color: { r: +c.r || 0, g: +c.g || 0, b: +c.b || 0 }, opacity: c.a === undefined ? 1 : +c.a });
+const box = (n) => ({ id: n.id, name: n.name, x: n.x, y: n.y, width: n.width, height: n.height, parentId: n.parent ? n.parent.id : undefined });
+const fontStyle = (w) => ({ 100: "Thin", 200: "Extra Light", 300: "Light", 400: "Regular", 500: "Medium", 600: "Semi Bold", 700: "Bold", 800: "Extra Bold", 900: "Black" }[w] || "Regular");
+
+function b64(bytes) {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i], b = bytes[i + 1], c = bytes[i + 2];
+    const ng = i + 1 < bytes.length, nh = i + 2 < bytes.length;
+    out += chars[a >> 2] + chars[((a & 3) << 4) | (ng ? b >> 4 : 0)] +
+      (ng ? chars[((b & 15) << 2) | (nh ? c >> 6 : 0)] : "=") + (nh ? chars[c & 63] : "=");
   }
-  if (cmd.op === "eval") {
-    // Run arbitrary Plugin API code. `figma` is in scope; code may use await
-    // and `return` a value. WARNING: this executes whatever the relay delivers.
+  return out;
+}
+
+// ── command handlers (cursor-talk-to-figma compatible) ───────────────────────
+const handlers = {
+  async ping() {
+    return { pong: true, page: figma.currentPage.name, selection: figma.currentPage.selection.map((n) => n.id) };
+  },
+
+  // arbitrary Plugin API code — `figma` in scope, may await and return a value.
+  // WARNING: executes whatever the relay delivers. Run only on trusted machines.
+  async eval(p) {
     const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
-    const out = await new AsyncFunction("figma", cmd.code || "")(figma);
-    return { value: serialize(out) };
-  }
-  return { error: "unknown op: " + cmd.op };
+    return { value: serialize(await new AsyncFunction("figma", p.code || "")(figma)) };
+  },
+
+  async get_document_info() {
+    await figma.currentPage.loadAsync();
+    const pg = figma.currentPage;
+    return { id: pg.id, name: pg.name, type: pg.type, childCount: pg.children.length,
+      children: pg.children.map((n) => ({ id: n.id, name: n.name, type: n.type })) };
+  },
+  async get_selection() {
+    return { selectionCount: figma.currentPage.selection.length,
+      selection: figma.currentPage.selection.map((n) => ({ id: n.id, name: n.name, type: n.type, visible: n.visible })) };
+  },
+  async get_node_info(p) {
+    const n = await byId(p.nodeId);
+    return serialize((await n.exportAsync({ format: "JSON_REST_V1" })).document);
+  },
+  async get_nodes_info(p) {
+    const nodes = await Promise.all((p.nodeIds || []).map((id) => byId(id)));
+    return Promise.all(nodes.map(async (n) => ({ nodeId: n.id, document: serialize((await n.exportAsync({ format: "JSON_REST_V1" })).document) })));
+  },
+  read_my_design() { return handlers.get_selection(); },
+
+  async create_rectangle(p = {}) {
+    const r = figma.createRectangle();
+    r.x = p.x ?? 0; r.y = p.y ?? 0; r.resize(p.width ?? 100, p.height ?? 100); r.name = p.name || "Rectangle";
+    await appendTo(r, p.parentId);
+    return box(r);
+  },
+  async create_frame(p = {}) {
+    const f = figma.createFrame();
+    f.x = p.x ?? 0; f.y = p.y ?? 0; f.resize(p.width ?? 100, p.height ?? 100); f.name = p.name || "Frame";
+    if (p.layoutMode && p.layoutMode !== "NONE") {
+      f.layoutMode = p.layoutMode; f.layoutWrap = p.layoutWrap || "NO_WRAP";
+      f.paddingTop = p.paddingTop ?? 10; f.paddingRight = p.paddingRight ?? 10;
+      f.paddingBottom = p.paddingBottom ?? 10; f.paddingLeft = p.paddingLeft ?? 10;
+      f.primaryAxisAlignItems = p.primaryAxisAlignItems || "MIN";
+      f.counterAxisAlignItems = p.counterAxisAlignItems || "MIN";
+      f.layoutSizingHorizontal = p.layoutSizingHorizontal || "FIXED";
+      f.layoutSizingVertical = p.layoutSizingVertical || "FIXED";
+      f.itemSpacing = p.itemSpacing ?? 0;
+    }
+    if (p.fillColor) f.fills = [solid(p.fillColor)];
+    if (p.strokeColor) f.strokes = [solid(p.strokeColor)];
+    if (p.strokeWeight !== undefined) f.strokeWeight = p.strokeWeight;
+    await appendTo(f, p.parentId);
+    return Object.assign(box(f), { fills: f.fills, strokes: f.strokes, layoutMode: f.layoutMode });
+  },
+  async create_text(p = {}) {
+    const t = figma.createText();
+    t.x = p.x ?? 0; t.y = p.y ?? 0;
+    const text = p.text ?? "Text"; t.name = p.name || text;
+    const style = fontStyle(p.fontWeight ?? 400);
+    await figma.loadFontAsync({ family: "Inter", style });
+    t.fontName = { family: "Inter", style };
+    t.fontSize = parseInt(p.fontSize ?? 14);
+    t.characters = text;
+    t.fills = [solid(p.fontColor || { r: 0, g: 0, b: 0, a: 1 })];
+    await appendTo(t, p.parentId);
+    return Object.assign(box(t), { characters: t.characters, fontSize: t.fontSize, fontName: t.fontName });
+  },
+
+  async set_fill_color(p = {}) {
+    const n = await byId(p.nodeId);
+    if (!("fills" in n)) throw new Error(`Node does not support fills: ${p.nodeId}`);
+    n.fills = [solid(p.color || {})];
+    return { id: n.id, name: n.name, fills: n.fills };
+  },
+  async set_stroke_color(p = {}) {
+    const n = await byId(p.nodeId);
+    if (!("strokes" in n)) throw new Error(`Node does not support strokes: ${p.nodeId}`);
+    n.strokes = [solid(p.color || {})];
+    if ("strokeWeight" in n) n.strokeWeight = p.weight ?? 1;
+    return { id: n.id, name: n.name, strokes: n.strokes, strokeWeight: "strokeWeight" in n ? n.strokeWeight : undefined };
+  },
+  async set_corner_radius(p = {}) {
+    const n = await byId(p.nodeId);
+    if (p.radius === undefined) throw new Error("Missing radius parameter");
+    if (!("cornerRadius" in n)) throw new Error(`Node does not support corner radius: ${p.nodeId}`);
+    const c = p.corners;
+    if (Array.isArray(c) && c.length === 4 && "topLeftRadius" in n) {
+      if (c[0]) n.topLeftRadius = p.radius; if (c[1]) n.topRightRadius = p.radius;
+      if (c[2]) n.bottomRightRadius = p.radius; if (c[3]) n.bottomLeftRadius = p.radius;
+    } else n.cornerRadius = p.radius;
+    return { id: n.id, name: n.name, cornerRadius: n.cornerRadius };
+  },
+  async set_text_content(p = {}) {
+    const n = await byId(p.nodeId);
+    if (p.text === undefined) throw new Error("Missing text parameter");
+    if (n.type !== "TEXT") throw new Error(`Node is not a text node: ${p.nodeId}`);
+    await figma.loadFontAsync(n.fontName);
+    n.characters = p.text;
+    return { id: n.id, name: n.name, characters: n.characters, fontName: n.fontName };
+  },
+
+  async move_node(p = {}) {
+    const n = await byId(p.nodeId);
+    if (p.x === undefined || p.y === undefined) throw new Error("Missing x or y parameters");
+    if (!("x" in n)) throw new Error(`Node does not support position: ${p.nodeId}`);
+    n.x = p.x; n.y = p.y;
+    return { id: n.id, name: n.name, x: n.x, y: n.y };
+  },
+  async resize_node(p = {}) {
+    const n = await byId(p.nodeId);
+    if (p.width === undefined || p.height === undefined) throw new Error("Missing width or height parameters");
+    if (!("resize" in n)) throw new Error(`Node does not support resizing: ${p.nodeId}`);
+    n.resize(p.width, p.height);
+    return { id: n.id, name: n.name, width: n.width, height: n.height };
+  },
+  async clone_node(p = {}) {
+    const n = await byId(p.nodeId);
+    const c = n.clone();
+    if (p.x !== undefined) c.x = p.x; if (p.y !== undefined) c.y = p.y;
+    await appendTo(c, p.parentId);
+    return box(c);
+  },
+  async delete_node(p = {}) {
+    const n = await byId(p.nodeId);
+    const info = { id: n.id, name: n.name, type: n.type };
+    n.remove();
+    return info;
+  },
+  async delete_multiple_nodes(p = {}) {
+    const deleted = [];
+    for (const id of p.nodeIds || []) {
+      try { const n = await byId(id); deleted.push({ id: n.id, name: n.name, type: n.type }); n.remove(); }
+      catch (e) { deleted.push({ id, error: String(e.message || e) }); }
+    }
+    return { deleted };
+  },
+
+  async set_focus(p = {}) {
+    const n = await byId(p.nodeId);
+    figma.currentPage.selection = [n];
+    figma.viewport.scrollAndZoomIntoView([n]);
+    return { id: n.id, name: n.name };
+  },
+  async set_selections(p = {}) {
+    const nodes = await Promise.all((p.nodeIds || []).map((id) => byId(id)));
+    figma.currentPage.selection = nodes;
+    figma.viewport.scrollAndZoomIntoView(nodes);
+    return { selection: nodes.map((n) => ({ id: n.id, name: n.name })) };
+  },
+
+  async get_styles() {
+    const [colors, texts, effects, grids] = await Promise.all([
+      figma.getLocalPaintStylesAsync(), figma.getLocalTextStylesAsync(),
+      figma.getLocalEffectStylesAsync(), figma.getLocalGridStylesAsync()]);
+    return {
+      colors: colors.map((s) => ({ id: s.id, name: s.name, key: s.key, paint: s.paints[0] })),
+      texts: texts.map((s) => ({ id: s.id, name: s.name, key: s.key })),
+      effects: effects.map((s) => ({ id: s.id, name: s.name, key: s.key })),
+      grids: grids.map((s) => ({ id: s.id, name: s.name, key: s.key })),
+    };
+  },
+  async get_local_components() {
+    await figma.loadAllPagesAsync();
+    const comps = figma.root.findAllWithCriteria({ types: ["COMPONENT"] });
+    return { count: comps.length, components: comps.map((c) => ({ id: c.id, name: c.name, key: c.key })) };
+  },
+  async create_component_instance(p = {}) {
+    if (!p.componentKey) throw new Error("Missing componentKey parameter");
+    const comp = await figma.importComponentByKeyAsync(p.componentKey);
+    const inst = comp.createInstance();
+    inst.x = p.x ?? 0; inst.y = p.y ?? 0;
+    await appendTo(inst, p.parentId);
+    return box(inst);
+  },
+  async export_node_as_image(p = {}) {
+    const n = await byId(p.nodeId);
+    if (!("exportAsync" in n)) throw new Error(`Node does not support exporting: ${p.nodeId}`);
+    const scale = p.scale ?? 1;
+    const bytes = await n.exportAsync({ format: "PNG", constraint: { type: "SCALE", value: scale } });
+    return { nodeId: p.nodeId, format: "PNG", scale, mimeType: "image/png", imageData: b64(bytes) };
+  },
+
+  async set_layout_mode(p = {}) {
+    const n = await byId(p.nodeId);
+    if (!("layoutMode" in n)) throw new Error(`Node does not support auto layout: ${p.nodeId}`);
+    n.layoutMode = p.layoutMode || "NONE";
+    if (p.layoutWrap !== undefined) n.layoutWrap = p.layoutWrap;
+    return { id: n.id, name: n.name, layoutMode: n.layoutMode };
+  },
+  async set_padding(p = {}) {
+    const n = await byId(p.nodeId);
+    if (!("paddingTop" in n)) throw new Error(`Node does not support padding: ${p.nodeId}`);
+    if (p.paddingTop !== undefined) n.paddingTop = p.paddingTop;
+    if (p.paddingRight !== undefined) n.paddingRight = p.paddingRight;
+    if (p.paddingBottom !== undefined) n.paddingBottom = p.paddingBottom;
+    if (p.paddingLeft !== undefined) n.paddingLeft = p.paddingLeft;
+    return { id: n.id, name: n.name };
+  },
+  async set_item_spacing(p = {}) {
+    const n = await byId(p.nodeId);
+    if (!("itemSpacing" in n)) throw new Error(`Node does not support item spacing: ${p.nodeId}`);
+    n.itemSpacing = p.itemSpacing ?? 0;
+    return { id: n.id, name: n.name, itemSpacing: n.itemSpacing };
+  },
+  async set_axis_align(p = {}) {
+    const n = await byId(p.nodeId);
+    if (p.primaryAxisAlignItems !== undefined) n.primaryAxisAlignItems = p.primaryAxisAlignItems;
+    if (p.counterAxisAlignItems !== undefined) n.counterAxisAlignItems = p.counterAxisAlignItems;
+    return { id: n.id, name: n.name };
+  },
+  async set_layout_sizing(p = {}) {
+    const n = await byId(p.nodeId);
+    if (p.layoutSizingHorizontal !== undefined) n.layoutSizingHorizontal = p.layoutSizingHorizontal;
+    if (p.layoutSizingVertical !== undefined) n.layoutSizingVertical = p.layoutSizingVertical;
+    return { id: n.id, name: n.name };
+  },
+};
+
+async function exec(command, params) {
+  const h = handlers[command];
+  if (!h) throw new Error(`Unknown command: ${command}`);
+  return h(params || {});
 }
 
-figma.showUI(__html__, { width: 340, height: 320 });
+// ── plugin ↔ UI wiring ───────────────────────────────────────────────────────
+figma.showUI(__html__, { width: 340, height: 360 });
 
 figma.ui.onmessage = async (msg) => {
-  if (msg.type === "exec") {
-    let result;
-    try { result = await exec(msg.cmd); }
-    catch (e) { result = { error: String((e && e.message) || e) }; }
-    figma.ui.postMessage({ type: "result", id: msg.cmd.id, result });
-    figma.notify(result.error ? "⚠️ " + result.error : "✅ " + msg.cmd.op);
+  if (msg.type === "execute-command") {
+    try {
+      const result = await exec(msg.command, msg.params);
+      figma.ui.postMessage({ type: "command-result", id: msg.id, result });
+      figma.notify("✅ " + msg.command);
+    } catch (e) {
+      const error = String((e && e.message) || e);
+      figma.ui.postMessage({ type: "command-error", id: msg.id, error });
+      figma.notify("⚠️ " + error);
+    }
   } else if (msg.type === "close") {
     figma.closePlugin();
   }

package/plugin/manifest.json

@@ -8,6 +8,6 @@
   "documentAccess": "dynamic-page",
   "networkAccess": {
     "allowedDomains": ["*"],
-    "reasoning": "Long-polls the local figma-api relay to receive drawing commands from the CLI."
+    "reasoning": "Connects to the local figma-api relay over WebSocket to receive drawing commands from the CLI."
   }
 }