@todoforai/figma-api 1.0.4 → 1.0.6

package/AGENTS.md

@@ -6,9 +6,8 @@ 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 the Figma desktop app open.
 
 ## 1. Auth (always required)
 
@@ -28,46 +27,61 @@ 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**:
+   `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.
+  Use the bridge (`create-frame`/`create-text`/…).
 - **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.
@@ -75,7 +89,7 @@ the plugin instead of localhost.
   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 +97,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,33 +53,46 @@ 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).
+1. `figma-api bridge` — start the WebSocket 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:
+   `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
@@ -95,7 +108,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 +115,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.4",
+  "version": "1.0.6",
   "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."
   }
 }

package/plugin/ui.html

@@ -3,62 +3,74 @@
 <head><meta charset="utf-8" /></head>
 <body style="font:13px -apple-system,Segoe UI,Roboto,sans-serif;margin:0;padding:14px;color:#1a1a1a">
   <h3 style="margin:0 0 6px">figma-api bridge</h3>
-  <p style="margin:0 0 10px;color:#666">Connect to the relay, then drive drawing from the <code>figma-api</code> CLI.</p>
+  <p style="margin:0 0 10px;color:#666">Joins the relay's WebSocket channel, then drive it from the <code>figma-api</code> CLI (or any cursor-talk-to-figma client).</p>
 
-  <label style="display:block;margin:6px 0 2px;font-weight:600">Relay URL</label>
-  <input id="relay" value="http://localhost:8917" style="width:100%;box-sizing:border-box;padding:7px;border:1px solid #ccc;border-radius:6px" />
+  <label style="display:block;margin:6px 0 2px;font-weight:600">Relay WebSocket URL</label>
+  <input id="url" value="ws://localhost:3055" style="width:100%;box-sizing:border-box;padding:7px;border:1px solid #ccc;border-radius:6px" />
+
+  <label style="display:block;margin:8px 0 2px;font-weight:600">Channel</label>
+  <input id="channel" value="figma-api" style="width:100%;box-sizing:border-box;padding:7px;border:1px solid #ccc;border-radius:6px" />
 
   <div style="display:flex;gap:8px;margin-top:10px">
     <button id="connect" style="flex:1;padding:9px;background:#1F6FEB;color:#fff;border:0;border-radius:8px;font-weight:600;cursor:pointer">Connect</button>
-    <button id="stop" style="flex:1;padding:9px;background:#eee;color:#333;border:0;border-radius:8px;font-weight:600;cursor:pointer">Stop</button>
+    <button id="stop" style="flex:1;padding:9px;background:#eee;color:#333;border:0;border-radius:8px;font-weight:600;cursor:pointer">Disconnect</button>
   </div>
 
   <div id="status" style="margin-top:10px;color:#666;min-height:18px">Idle.</div>
-  <pre id="log" style="margin-top:8px;background:#0d1117;color:#8b949e;padding:8px;border-radius:6px;height:120px;overflow:auto;font-size:11px"></pre>
+  <pre id="log" style="margin-top:8px;background:#0d1117;color:#8b949e;padding:8px;border-radius:6px;height:110px;overflow:auto;font-size:11px"></pre>
 
   <script>
     const $ = (id) => document.getElementById(id);
-    let running = false;
     const log = (m) => { const l = $("log"); l.textContent += m + "\n"; l.scrollTop = l.scrollHeight; };
+    let socket = null, channel = null;
 
-    let resolveResult = null;
-    // plugin code → result → resolve the pending exec
+    // plugin code → command result → relay (cursor-talk-to-figma envelope)
     onmessage = (e) => {
       const m = e.data.pluginMessage;
-      if (m && m.type === "result" && resolveResult) { const r = resolveResult; resolveResult = null; r(m); }
+      if (!m || !socket || socket.readyState !== 1) return;
+      if (m.type === "command-result") {
+        log("▶ " + m.id + " ok");
+        socket.send(JSON.stringify({ id: m.id, type: "message", channel, message: { id: m.id, result: m.result } }));
+      } else if (m.type === "command-error") {
+        log("▶ " + m.id + " ✗ " + m.error);
+        socket.send(JSON.stringify({ id: m.id, type: "message", channel, message: { id: m.id, error: m.error } }));
+      }
     };
 
-    async function loop() {
-      const relay = $("relay").value.replace(/\/$/, "");
-      $("status").textContent = "🟢 Connected — polling " + relay;
-      while (running) {
-        let cmd;
-        try {
-          cmd = await (await fetch(relay + "/poll")).json();
-        } catch (_) {
-          $("status").textContent = "🔴 Relay unreachable — retrying";
-          await new Promise((res) => setTimeout(res, 1500));
-          continue;
+    function connect() {
+      const url = $("url").value.trim();
+      channel = $("channel").value.trim();
+      $("status").textContent = "Connecting to " + url + " …";
+      socket = new WebSocket(url);
+
+      socket.onopen = () => {
+        const id = Date.now().toString(36) + Math.random().toString(36).slice(2, 7);
+        socket.send(JSON.stringify({ id, type: "join", channel }));
+        log("joining channel: " + channel);
+      };
+      socket.onmessage = (event) => {
+        let data; try { data = JSON.parse(event.data); } catch (_) { return; }
+        if (data.type === "system") {
+          const sm = data.message;
+          // structured join ack, or "Joined channel: …" — not the "please join" welcome
+          if ((sm && typeof sm === "object" && sm.result) || (typeof sm === "string" && sm.indexOf("Joined channel") === 0)) {
+            $("status").textContent = "🟢 Connected — channel: " + channel;
+          } else if (typeof sm === "string") log("· " + sm);
+          return;
         }
-        if (!cmd || !cmd.op) continue;
-        log("◀ " + cmd.op + " (" + cmd.id + ")");
-        // Run one command at a time and wait for its result (no overlap).
-        const m = await new Promise((resolve) => {
-          resolveResult = resolve;
-          parent.postMessage({ pluginMessage: { type: "exec", cmd } }, "*");
-        });
-        let bodyResult = m.result;
-        try { JSON.stringify(bodyResult); } catch (_) { bodyResult = { error: "result not serializable" }; }
-        log("▶ " + m.id + " " + JSON.stringify(bodyResult).slice(0, 60));
-        try {
-          await fetch(relay + "/result", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ id: m.id, result: bodyResult }) });
-        } catch (_) { log("⚠ result POST failed"); }
-      }
-      $("status").textContent = "⏹ Stopped.";
+        // commands arrive as a "broadcast" event from the other peer; data.message is the payload
+        const payload = data.message;
+        if (payload && payload.command) {
+          log("◀ " + payload.command + " (" + payload.id + ")");
+          parent.postMessage({ pluginMessage: { type: "execute-command", id: payload.id, command: payload.command, params: payload.params } }, "*");
+        }
+      };
+      socket.onclose = () => { $("status").textContent = "⏹ Disconnected."; socket = null; };
+      socket.onerror = () => { $("status").textContent = "🔴 WebSocket error — is the relay running? (figma-api bridge)"; };
     }
 
-    $("connect").onclick = () => { if (!running) { running = true; loop(); } };
-    $("stop").onclick = () => { running = false; };
+    $("connect").onclick = () => { if (!socket) connect(); };
+    $("stop").onclick = () => { if (socket) socket.close(); };
   </script>
 </body>
 </html>

package/src/bridge.ts

@@ -1,15 +1,27 @@
-// Relay/bridge between the figma-api CLI and the Figma plugin.
-// The plugin can't be addressed directly, but it can poll over HTTP — so the CLI
-// enqueues commands here, the plugin long-polls /poll, executes them on the
-// canvas, and posts the result back to /result.
+// WebSocket relay + CLI peer for the Figma plugin bridge.
 //
-//   figma-api draw-* ──POST /cmd──▶  relay  ◀──GET /poll──  plugin
-//                                          ──POST /result─▶ (draws, returns ids)
+// The Figma REST API can't create canvas nodes (frames/text/shapes) — the Plugin
+// API can. The plugin can't be addressed directly, so a relay sits between it and
+// the CLI. We speak the cursor-talk-to-figma WebSocket protocol, so this relay is
+// a drop-in for that ecosystem: its MCP server can drive our plugin, and our CLI
+// can drive theirs.
+//
+//   figma-api create-frame … ──ws──▶  relay (channel broadcast)  ◀──ws──  plugin
+//
+// Protocol (channel-scoped, broadcast to the *other* peer, never echoed):
+//   join:    { type:"join", channel }   → { type:"system", message:{ id, result } }
+//   command: { type:"message", channel, message:{ id, command, params } }
+//   result:  { type:"message", channel, message:{ id, result } | { id, error } }
+//   each is delivered to the other peer wrapped as { type:"broadcast", message }.
 
 import { resolve } from "path";
 import { existsSync } from "fs";
+import type { ServerWebSocket } from "bun";
+
+export const DEFAULT_PORT = 3055;
+export const DEFAULT_CHANNEL = "figma-api";
 
-interface Cmd { id: string; op: string; [k: string]: unknown }
+interface WsData { channel?: string }
 
 /** Absolute path to the bundled plugin/manifest.json, or a clone hint if missing. */
 function manifestPath(): string {
@@ -19,109 +31,147 @@ function manifestPath(): string {
     : `${p} (missing — clone it: git clone https://github.com/todoforai/figma-api)`;
 }
 
-const queue: Cmd[] = [];
-const resultWaiters = new Map<string, (v: unknown) => void>();
-const pollWaiters: ((c: Cmd | null) => void)[] = [];
-let lastSeen = 0;
-
-function json(body: unknown, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { "content-type": "application/json", "access-control-allow-origin": "*", "access-control-allow-headers": "*" },
-  });
-}
-
 export function startBridge(port: number): void {
-  Bun.serve({
+  const channels = new Map<string, Set<ServerWebSocket<WsData>>>();
+
+  Bun.serve<WsData, undefined>({
     port,
-    async fetch(req) {
-      const url = new URL(req.url);
-      if (req.method === "OPTIONS") return json({}, 204);
+    fetch(req, server) {
+      if (server.upgrade(req, { data: {} })) return;
+      return new Response("figma-api bridge: WebSocket only", { status: 426 });
+    },
+    websocket: {
+      // Match cursor-talk-to-figma's relay (src/socket.ts) so either side is a
+      // drop-in: welcome on open, two-part join ack, peer notices, broadcasts
+      // wrapped as {type:"broadcast", sender:"peer", message:<inner>}.
+      open(ws) {
+        ws.send(JSON.stringify({ type: "system", message: "Please join a channel to start chatting" }));
+      },
+      message(ws, raw) {
+        let msg: any;
+        try { msg = JSON.parse(String(raw)); } catch { return; }
 
-      // Health / status
-      if (url.pathname === "/health") {
-        return json({ ok: true, queued: queue.length, pluginSeenMsAgo: lastSeen ? Date.now() - lastSeen : null });
-      }
+        if (msg.type === "join") {
+          const ch = typeof msg.channel === "string" && msg.channel ? msg.channel : DEFAULT_CHANNEL;
+          if (ws.data.channel && ws.data.channel !== ch) channels.get(ws.data.channel)?.delete(ws);
+          let peers = channels.get(ch);
+          if (!peers) channels.set(ch, (peers = new Set()));
+          ws.data.channel = ch;
+          ws.send(JSON.stringify({ type: "system", message: `Joined channel: ${ch}`, channel: ch }));
+          ws.send(JSON.stringify({ type: "system", message: { id: msg.id, result: `Connected to channel: ${ch}` }, channel: ch }));
+          for (const peer of peers) if (peer !== ws) peer.send(JSON.stringify({ type: "system", message: "A new user has joined the channel", channel: ch }));
+          peers.add(ws);
+          console.log(`peer joined channel "${ch}" (${peers.size} in channel)`);
+          return;
+        }
 
-      // CLI → enqueue a command and wait for the plugin's result
-      if (url.pathname === "/cmd" && req.method === "POST") {
-        const body = (await req.json()) as Record<string, unknown>;
-        const id = crypto.randomUUID().slice(0, 8);
-        const cmd: Cmd = { id, op: String(body.op), ...body };
-        const waiter = pollWaiters.shift();
-        if (waiter) waiter(cmd);
-        else queue.push(cmd);
-        const result = await new Promise((resolve) => {
-          resultWaiters.set(id, resolve);
-          setTimeout(() => { if (resultWaiters.delete(id)) resolve({ timeout: true }); }, 30000);
-        });
-        return json({ id, result });
-      }
+        const ch = ws.data.channel;
+        if (!ch || !channels.get(ch)?.has(ws)) { ws.send(JSON.stringify({ type: "error", message: "You must join the channel first" })); return; }
 
-      // Plugin → long-poll for the next command
-      if (url.pathname === "/poll") {
-        lastSeen = Date.now();
-        const next = queue.shift();
-        if (next) return json(next);
-        const cmd = await new Promise<Cmd | null>((resolve) => {
-          pollWaiters.push(resolve);
-          setTimeout(() => {
-            const i = pollWaiters.indexOf(resolve);
-            if (i >= 0) { pollWaiters.splice(i, 1); resolve(null); }
-          }, 25000);
-        });
-        return json(cmd ?? {});
-      }
+        // Forward progress updates verbatim to the other peers (upstream parity).
+        if (msg.type === "progress_update") {
+          for (const peer of channels.get(ch) ?? []) if (peer !== ws) peer.send(JSON.stringify(msg));
+          return;
+        }
+        if (msg.type !== "message") return;
 
-      // Plugin → post a command result
-      if (url.pathname === "/result" && req.method === "POST") {
-        const body = (await req.json()) as { id: string; result: unknown };
-        const w = resultWaiters.get(body.id);
-        if (w) { resultWaiters.delete(body.id); w(body.result); }
-        return json({ ok: true });
-      }
-
-      return json({ error: "not found" }, 404);
+        // Broadcast the inner message to the OTHER peers (sender never gets its own).
+        const out = JSON.stringify({ type: "broadcast", sender: "peer", channel: ch, message: msg.message });
+        for (const peer of channels.get(ch) ?? []) if (peer !== ws) peer.send(out);
+      },
+      close(ws) {
+        const ch = ws.data.channel;
+        if (!ch) return;
+        const peers = channels.get(ch);
+        if (!peers) return;
+        peers.delete(ws);
+        for (const peer of peers) peer.send(JSON.stringify({ type: "system", message: "A user has left the channel", channel: ch }));
+        if (peers.size === 0) channels.delete(ch);
+      },
     },
   });
-  console.log(`figma-api bridge listening on http://localhost:${port}`);
-  console.log("Endpoints: POST /cmd  GET /poll  POST /result  GET /health");
-  console.log("Point the plugin at this URL (or a cloudflared tunnel of it), then run draw-* commands.");
+
+  console.log(`figma-api bridge (WebSocket) listening on ws://localhost:${port}`);
+  console.log(`Default channel: "${DEFAULT_CHANNEL}". Open the plugin, click Connect, then run figma-api commands.`);
 }
 
-/** Setup instructions shown only when a canvas-write command can't reach the plugin. */
-const setup = () => `
-Canvas writes (create frames/text/shapes, edit variables off-Enterprise) aren't in
-the Figma REST API — they need the plugin bridge, which the user must install.
+/** Setup instructions shown only when a canvas command can't reach the plugin. */
+const setup = (port: number) => `
+Canvas writes (create frames/text/shapes) aren't in the Figma REST API — they need
+the plugin bridge, which the user must install.
 
-AGENT: be explicit with the user about this. Explain that the bridge plugin grants
-write access to their Figma documents, confirm they want to install it, then walk
-them through these steps (the plugin runs in THEIR Figma, you can't do step 2 for
-them):
+AGENT: be explicit with the user about this. The bridge plugin grants write access
+to their Figma documents — confirm they want it, then walk them through (the plugin
+runs in THEIR Figma, you can't do step 2 for them):
   1. Start the relay (keep running):   figma-api bridge
   2. In the Figma DESKTOP app: Plugins → Development → Import plugin from manifest
      → ${manifestPath()}
-     Run it, paste the relay URL (default http://localhost:8917), click Connect.
+     Run it, set the URL to ws://localhost:${port} and channel "${DEFAULT_CHANNEL}", click Connect.
   3. Retry. Verify the round-trip with:  figma-api ping
-Cross-machine: expose the relay via 'cloudflared tunnel --url http://localhost:8917'
-and paste that https URL into the plugin. Browser-only Figma can't load dev plugins.`;
-
-/** CLI helper: push a command to a running bridge and return the plugin's result. */
-export async function sendCommand(relay: string, op: string, params: Record<string, unknown>): Promise<void> {
-  const res = await fetch(`${relay.replace(/\/$/, "")}/cmd`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ op, ...params }),
-  }).catch((e) => {
-    console.error(`Bridge relay not reachable at ${relay} (${e.message}).${setup()}`);
-    process.exit(1);
+Cross-machine: expose the relay via 'cloudflared tunnel --url http://localhost:${port}'
+and paste the wss:// URL into the plugin. Browser-only Figma can't load dev plugins.`;
+
+/** CLI peer: connect to the relay, send one command, return the plugin's result. */
+export function sendCommand(
+  wsUrl: string,
+  channel: string,
+  command: string,
+  params: Record<string, unknown>,
+  timeoutMs = 30000,
+): Promise<unknown> {
+  const port = Number(new URL(wsUrl).port) || DEFAULT_PORT;
+  return new Promise((resolveP, rejectP) => {
+    const ws = new WebSocket(wsUrl);
+    const id = crypto.randomUUID().slice(0, 8);
+    let joined = false;
+
+    const timer = setTimeout(() => {
+      ws.close();
+      rejectP(new Error(`Timed out waiting for the plugin — relay is up but no plugin is Connected.${setup(port)}`));
+    }, timeoutMs);
+
+    ws.addEventListener("open", () => ws.send(JSON.stringify({ id, type: "join", channel })));
+    ws.addEventListener("error", () => {
+      clearTimeout(timer);
+      rejectP(new Error(`Bridge relay not reachable at ${wsUrl}.${setup(port)}`));
+    });
+    ws.addEventListener("message", (ev) => {
+      let data: any;
+      try { data = JSON.parse(String(ev.data)); } catch { return; }
+      // Wait for the structured join ack (ignore string system notices / welcome)
+      // before sending the command, else the relay rejects it as "not in channel".
+      if (data.type === "system") {
+        const sm = data.message;
+        if (!joined && sm && typeof sm === "object" && sm.result === `Connected to channel: ${channel}`) {
+          joined = true;
+          ws.send(JSON.stringify({ id, type: "message", channel, message: { id, command, params } }));
+        }
+        return;
+      }
+      // The plugin's result arrives as a "broadcast" event; data.message is the payload.
+      const m = data.message;
+      if (m && m.id === id) {
+        clearTimeout(timer);
+        ws.close();
+        if (m.error) rejectP(new Error(m.error));
+        else resolveP(m.result);
+      }
+    });
   });
-  const data = (await (res as Response).json()) as { result?: { timeout?: boolean; error?: string } };
-  const result = data.result;
-  if (result?.timeout) {
-    console.error(`Timed out waiting for the plugin — the relay is up but no plugin is Connected.${setup()}`);
+}
+
+/** Run a command and print its result; exit non-zero on failure. */
+export async function runCommand(
+  wsUrl: string,
+  channel: string,
+  command: string,
+  params: Record<string, unknown>,
+): Promise<void> {
+  try {
+    const result = await sendCommand(wsUrl, channel, command, params);
+    console.log(JSON.stringify(result ?? null, null, 2));
+  } catch (e) {
+    console.error((e as Error).message);
     process.exit(1);
   }
-  console.log(JSON.stringify(result ?? data, null, 2));
-  if (result?.error) process.exit(1);
 }

package/src/index.ts

@@ -5,9 +5,44 @@ import {
   saveCredentials, loadCredentials,
   get, post, put, del, output, parseFigmaTarget, readJsonArg,
 } from "./api";
-import { startBridge, sendCommand } from "./bridge";
-
-const DEFAULT_RELAY = process.env.FIGMA_RELAY || "http://localhost:8917";
+import { startBridge, runCommand, DEFAULT_PORT, DEFAULT_CHANNEL } from "./bridge";
+
+const DEFAULT_RELAY = process.env.FIGMA_RELAY || `ws://localhost:${DEFAULT_PORT}`;
+const DEFAULT_CH = process.env.FIGMA_CHANNEL || DEFAULT_CHANNEL;
+
+/** Parse "r,g,b[,a]" (0–255 or 0–1) or "#rgb[a]" / "#rrggbb[aa]" into Figma's 0–1 {r,g,b,a}. */
+function parseColor(s: string): { r: number; g: number; b: number; a: number } {
+  if (s.startsWith("#")) {
+    let h = s.slice(1);
+    if (h.length === 3 || h.length === 4) h = h.split("").map((c) => c + c).join(""); // #rgb → #rrggbb
+    if ((h.length !== 6 && h.length !== 8) || /[^0-9a-fA-F]/.test(h)) {
+      console.error(`Invalid hex color: ${s}`); process.exit(1);
+    }
+    const n = (i: number) => parseInt(h.slice(i, i + 2), 16) / 255;
+    return { r: n(0), g: n(2), b: n(4), a: h.length === 8 ? n(6) : 1 };
+  }
+  const p = s.split(",").map(Number);
+  const bad = (p.length !== 3 && p.length !== 4) || p.some((v) => !Number.isFinite(v) || v < 0);
+  const rgb255 = p.slice(0, 3).some((v) => v > 1);
+  if (bad || p.slice(0, 3).some((v) => v > (rgb255 ? 255 : 1)) || (p[3] !== undefined && p[3] > 1)) {
+    console.error(`Invalid color: ${s} (use r,g,b[,a] as 0–1 or 0–255 RGB, alpha 0–1; or #hex)`);
+    process.exit(1);
+  }
+  const d = rgb255 ? 255 : 1;
+  return { r: p[0] / d, g: p[1] / d, b: p[2] / d, a: p[3] ?? 1 };
+}
+
+/** Common flags for every canvas command + a thin sender. */
+function canvas(name: string) {
+  return program
+    .command(name)
+    .option("--relay <url>", "relay WebSocket URL", DEFAULT_RELAY)
+    .option("--channel <name>", "relay channel", DEFAULT_CH);
+}
+const drive = (o: any, command: string, params: Record<string, unknown> = {}) =>
+  runCommand(o.relay, o.channel, command, params);
+/** Number(v) when the option is present (incl. "0"), else undefined. */
+const num = (v: unknown) => (v === undefined ? undefined : Number(v));
 
 program
   .name("figma-api")
@@ -17,9 +52,11 @@ program
     "Auth: figma-api auth <personal-access-token>   (or FIGMA_TOKEN env var)\n" +
     "Token: create at https://www.figma.com/settings → Personal access tokens\n" +
     "Most commands accept a file URL or a raw file key. node-id is read from the URL too.\n\n" +
-    "NOTE: Creating canvas layers (frames/shapes/text) is NOT in the REST API — that\n" +
-    "lives in the Figma plugin/MCP runtime. Writable here: comments, reactions,\n" +
-    "variables, dev resources and webhooks (token needs the matching write scopes)."
+    "NOTE: Creating canvas layers (frames/shapes/text) is NOT in the REST API — those\n" +
+    "go through the plugin bridge (create-frame, create-text, set-fill-color, …). It\n" +
+    "speaks the cursor-talk-to-figma WebSocket protocol, so any client in that\n" +
+    "ecosystem is interchangeable. REST-writable here: comments, reactions, variables,\n" +
+    "dev resources and webhooks (token needs the matching write scopes)."
   )
   .version("1.0.0")
   .addHelpText("after", `
@@ -589,57 +626,196 @@ program
   .action(async (url: string) => output(await get(`/v1/oembed`, { url })));
 
 // ── plugin bridge (canvas writes the REST API can't do) ───────────────────────
+// The relay + plugin speak the cursor-talk-to-figma WebSocket protocol, so these
+// commands are interchangeable with that ecosystem's MCP server / plugin.
 program
   .command("bridge")
-  .description("Start the relay that lets the figma-api CLI drive the Figma plugin (canvas writes)")
-  .option("--port <n>", "port to listen on", "8917")
+  .description("Start the WebSocket relay that lets the CLI drive the Figma plugin (canvas writes)")
+  .option("--port <n>", "port to listen on", String(DEFAULT_PORT))
   .addHelpText("after", `
-The Figma REST API cannot create canvas nodes (frames/text/shapes) or edit
-variables off-Enterprise. This relay bridges the CLI and the companion Figma
-plugin (see plugin/ folder), which can.
+The Figma REST API cannot create canvas nodes (frames/text/shapes). This relay
+bridges the CLI and the companion Figma plugin (see plugin/ folder), which can.
+It speaks the cursor-talk-to-figma WebSocket protocol — compatible with that
+ecosystem's MCP server / plugin.
 
 Flow:
   1. figma-api bridge                       # start this relay (keep running)
   2. In Figma desktop: Plugins → Development → Import plugin from manifest →
-     api-apps/figma-api/plugin/manifest.json, run it, Connect to the relay URL.
-  3. figma-api run '...'                     # CLI → relay → plugin runs it
+     plugin/manifest.json, run it, set URL ws://localhost:${DEFAULT_PORT} + channel
+     "${DEFAULT_CHANNEL}", click Connect.
+  3. figma-api ping                         # verify; then create-frame / create-text / …
 
-Cross-machine: expose the relay with 'cloudflared tunnel --url http://localhost:8917'
-and paste that https URL into the plugin's Relay field.
+Cross-machine: expose the relay with 'cloudflared tunnel --url http://localhost:${DEFAULT_PORT}'
+and paste the wss:// URL into the plugin.
 
 ⚠️  Security: the relay has no auth and 'run' executes arbitrary code in your
-Figma document. Only run it on a trusted machine/network; do not expose the
-tunnel URL publicly or run code you don't trust.`)
+Figma document. Only run it on a trusted machine/network.`)
   .action((o: any) => startBridge(Number(o.port)));
 
-program
-  .command("run <code-or-@file>")
-  .description("Run arbitrary Figma Plugin API code in the connected plugin (full canvas + variables write)")
-  .option("--relay <url>", "relay URL", DEFAULT_RELAY)
+canvas("ping")
+  .description("Ping the connected plugin to verify the bridge round-trip")
+  .addHelpText("after", `\nReturns the plugin's current page name and selection.\nExample:\n  figma-api ping`)
+  .action((o: any) => drive(o, "ping"));
+
+// ── canvas reads ──────────────────────────────────────────────────────────────
+canvas("get-document-info")
+  .description("Get the current page and its top-level children (via plugin)")
+  .action((o: any) => drive(o, "get_document_info"));
+
+canvas("get-selection")
+  .description("Get the current selection on the canvas (via plugin)")
+  .action((o: any) => drive(o, "get_selection"));
+
+canvas("get-node-info <node-id>")
+  .description("Get full info for one node (via plugin)")
+  .action((id: string, o: any) => drive(o, "get_node_info", { nodeId: id }));
+
+canvas("get-nodes-info <ids>")
+  .description("Get full info for several nodes (comma-separated ids, via plugin)")
+  .action((ids: string, o: any) => drive(o, "get_nodes_info", { nodeIds: ids.split(",") }));
+
+canvas("get-styles")
+  .description("List local paint/text/effect/grid styles (via plugin)")
+  .action((o: any) => drive(o, "get_styles"));
+
+canvas("get-components")
+  .description("List local components in the document (via plugin)")
+  .action((o: any) => drive(o, "get_local_components"));
+
+canvas("export-image <node-id>")
+  .description("Export a node as a base64 PNG (via plugin)")
+  .option("--scale <n>", "scale factor", "1")
+  .action((id: string, o: any) => drive(o, "export_node_as_image", { nodeId: id, scale: Number(o.scale) }));
+
+// ── canvas creation ───────────────────────────────────────────────────────────
+canvas("create-frame")
+  .description("Create a frame on the canvas (via plugin)")
+  .option("--x <n>", "x", "0").option("--y <n>", "y", "0")
+  .option("--width <n>", "width", "100").option("--height <n>", "height", "100")
+  .option("--name <name>", "layer name")
+  .option("--parent <id>", "parent node id (defaults to current page)")
+  .option("--fill <color>", "fill color: r,g,b[,a] or #hex")
+  .option("--stroke <color>", "stroke color: r,g,b[,a] or #hex")
+  .option("--stroke-weight <n>", "stroke weight")
+  .option("--layout <mode>", "auto layout: NONE | HORIZONTAL | VERTICAL")
+  .option("--item-spacing <n>", "item spacing (auto layout)")
+  .addHelpText("after", `\nExample:\n  figma-api create-frame --width 320 --height 200 --fill "#1F6FEB" --name Card`)
+  .action((o: any) => drive(o, "create_frame", {
+    x: Number(o.x), y: Number(o.y), width: Number(o.width), height: Number(o.height),
+    name: o.name, parentId: o.parent,
+    fillColor: o.fill ? parseColor(o.fill) : undefined,
+    strokeColor: o.stroke ? parseColor(o.stroke) : undefined,
+    strokeWeight: num(o.strokeWeight),
+    layoutMode: o.layout, itemSpacing: num(o.itemSpacing),
+  }));
+
+canvas("create-rectangle")
+  .description("Create a rectangle on the canvas (via plugin)")
+  .option("--x <n>", "x", "0").option("--y <n>", "y", "0")
+  .option("--width <n>", "width", "100").option("--height <n>", "height", "100")
+  .option("--name <name>", "layer name").option("--parent <id>", "parent node id")
+  .addHelpText("after", `\nExample:\n  figma-api create-rectangle --width 80 --height 80 --name Box`)
+  .action((o: any) => drive(o, "create_rectangle", {
+    x: Number(o.x), y: Number(o.y), width: Number(o.width), height: Number(o.height), name: o.name, parentId: o.parent,
+  }));
+
+canvas("create-text <text>")
+  .description("Create a text node on the canvas (via plugin)")
+  .option("--x <n>", "x", "0").option("--y <n>", "y", "0")
+  .option("--size <n>", "font size", "14").option("--weight <n>", "font weight (100–900)", "400")
+  .option("--color <color>", "font color: r,g,b[,a] or #hex")
+  .option("--name <name>", "layer name").option("--parent <id>", "parent node id")
+  .addHelpText("after", `\nExample:\n  figma-api create-text "Hello" --size 24 --weight 700 --color "#111"`)
+  .action((text: string, o: any) => drive(o, "create_text", {
+    text, x: Number(o.x), y: Number(o.y), fontSize: Number(o.size), fontWeight: Number(o.weight),
+    fontColor: o.color ? parseColor(o.color) : undefined, name: o.name, parentId: o.parent,
+  }));
+
+canvas("create-instance <component-key>")
+  .description("Create an instance of a published component (via plugin)")
+  .option("--x <n>", "x", "0").option("--y <n>", "y", "0").option("--parent <id>", "parent node id")
+  .action((key: string, o: any) => drive(o, "create_component_instance", { componentKey: key, x: Number(o.x), y: Number(o.y), parentId: o.parent }));
+
+// ── canvas edits ──────────────────────────────────────────────────────────────
+canvas("set-fill-color <node-id> <color>")
+  .description("Set a node's solid fill (color: r,g,b[,a] or #hex, via plugin)")
+  .action((id: string, color: string, o: any) => drive(o, "set_fill_color", { nodeId: id, color: parseColor(color) }));
+
+canvas("set-stroke-color <node-id> <color>")
+  .description("Set a node's solid stroke (via plugin)")
+  .option("--weight <n>", "stroke weight", "1")
+  .action((id: string, color: string, o: any) => drive(o, "set_stroke_color", { nodeId: id, color: parseColor(color), weight: Number(o.weight) }));
+
+canvas("set-corner-radius <node-id> <radius>")
+  .description("Set a node's corner radius (via plugin)")
+  .action((id: string, radius: string, o: any) => drive(o, "set_corner_radius", { nodeId: id, radius: Number(radius) }));
+
+canvas("set-text <node-id> <text>")
+  .description("Replace a text node's content (via plugin)")
+  .action((id: string, text: string, o: any) => drive(o, "set_text_content", { nodeId: id, text }));
+
+canvas("move-node <node-id> <x> <y>")
+  .description("Move a node to (x, y) (via plugin)")
+  .action((id: string, x: string, y: string, o: any) => drive(o, "move_node", { nodeId: id, x: Number(x), y: Number(y) }));
+
+canvas("resize-node <node-id> <width> <height>")
+  .description("Resize a node (via plugin)")
+  .action((id: string, w: string, h: string, o: any) => drive(o, "resize_node", { nodeId: id, width: Number(w), height: Number(h) }));
+
+canvas("clone-node <node-id>")
+  .description("Clone a node (via plugin)")
+  .option("--x <n>", "x of the clone").option("--y <n>", "y of the clone").option("--parent <id>", "parent node id")
+  .action((id: string, o: any) => drive(o, "clone_node", { nodeId: id, x: num(o.x), y: num(o.y), parentId: o.parent }));
+
+canvas("delete-node <node-id>")
+  .description("Delete a node (via plugin)")
+  .action((id: string, o: any) => drive(o, "delete_node", { nodeId: id }));
+
+canvas("delete-nodes <ids>")
+  .description("Delete several nodes (comma-separated ids, via plugin)")
+  .action((ids: string, o: any) => drive(o, "delete_multiple_nodes", { nodeIds: ids.split(",") }));
+
+canvas("set-layout <node-id> <mode>")
+  .description("Set auto layout mode: NONE | HORIZONTAL | VERTICAL (via plugin)")
+  .action((id: string, mode: string, o: any) => drive(o, "set_layout_mode", { nodeId: id, layoutMode: mode }));
+
+canvas("set-padding <node-id>")
+  .description("Set auto-layout padding (via plugin)")
+  .option("--top <n>").option("--right <n>").option("--bottom <n>").option("--left <n>")
+  .action((id: string, o: any) => drive(o, "set_padding", {
+    nodeId: id, paddingTop: num(o.top), paddingRight: num(o.right),
+    paddingBottom: num(o.bottom), paddingLeft: num(o.left),
+  }));
+
+canvas("set-item-spacing <node-id> <spacing>")
+  .description("Set auto-layout item spacing (via plugin)")
+  .action((id: string, s: string, o: any) => drive(o, "set_item_spacing", { nodeId: id, itemSpacing: Number(s) }));
+
+canvas("focus <node-id>")
+  .description("Select a node and zoom the viewport to it (via plugin)")
+  .action((id: string, o: any) => drive(o, "set_focus", { nodeId: id }));
+
+canvas("select <ids>")
+  .description("Set the selection (comma-separated ids) and zoom to it (via plugin)")
+  .action((ids: string, o: any) => drive(o, "set_selections", { nodeIds: ids.split(",") }));
+
+// ── escape hatch: arbitrary Plugin API code ──────────────────────────────────
+canvas("run <code-or-@file>")
+  .description("Run arbitrary Figma Plugin API code in the connected plugin (escape hatch)")
   .addHelpText("after", `
-Whatever the Figma Plugin API can do, this can do — create frames/text/shapes,
-edit variables (no Enterprise paywall, unlike REST), read selection, etc.
-\`figma\` is in scope; you may use await and \`return\` a value (nodes come back as
-{id,type,name}).
-
-Pass code inline or as @file.js. Requires a running bridge + Connected plugin.
+Whatever the Figma Plugin API can do, this can do. \`figma\` is in scope; you may
+use await and \`return\` a value (nodes come back as {id,type,name}). Prefer the
+named create-*/set-* commands; reach for 'run' only for things they don't cover.
+Pass code inline or as @file.js.
 
 ⚠️  Executes arbitrary code in your Figma document — only run code you trust.
 
 Examples:
-  figma-api run 'return figma.currentPage.selection.map(n => ({id:n.id, type:n.type, name:n.name}))'
-  figma-api run 'const t = figma.createText(); await figma.loadFontAsync({family:"Inter",style:"Regular"}); t.characters="Hi from CLI"; figma.currentPage.appendChild(t); return t'
+  figma-api run 'return figma.currentPage.selection.map(n => n.name)'
   figma-api run @make-card.js`)
-  .action(async (codeArg: string, o: any) => {
+  .action((codeArg: string, o: any) => {
     const code = codeArg.startsWith("@") ? readFileSync(codeArg.slice(1), "utf-8") : codeArg;
-    await sendCommand(o.relay, "eval", { code });
+    return drive(o, "eval", { code });
   });
 
-program
-  .command("ping")
-  .description("Ping the connected plugin to verify the bridge round-trip")
-  .option("--relay <url>", "relay URL", DEFAULT_RELAY)
-  .addHelpText("after", `\nReturns the plugin's current page name and selection.\nExample:\n  figma-api ping`)
-  .action(async (o: any) => sendCommand(o.relay, "ping", {}));
-
 program.parse();