@todoforai/figma-api 1.0.6 → 1.0.7

package/AGENTS.md

@@ -7,7 +7,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)? → REST can't. Use the
-  **plugin bridge** (step 2). Requires the Figma desktop app open.
+  **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)
 
@@ -45,11 +46,15 @@ Setup (do all three, in order):
    ```bash
    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, set URL `ws://localhost:3055` + channel
-   `figma-api`, click **Connect**.
+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
@@ -82,9 +87,16 @@ the plugin instead of localhost.
   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 (`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.
+- **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.

package/README.md

@@ -67,9 +67,14 @@ figma-api create-frame …  ──ws──▶  relay (figma-api bridge)  ◀─
 Setup:
 
 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, set URL `ws://localhost:3055` + channel
-   `figma-api`, click **Connect**.
+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
@@ -98,8 +103,11 @@ Cross-machine: `cloudflared tunnel --url http://localhost:3055` and paste the
 > 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?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@todoforai/figma-api",
-  "version": "1.0.6",
+  "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": {

package/src/bridge.ts

@@ -8,7 +8,8 @@
 //
 //   figma-api create-frame … ──ws──▶  relay (channel broadcast)  ◀──ws──  plugin
 //
-// Protocol (channel-scoped, broadcast to the *other* peer, never echoed):
+// Protocol (join/ack are channel-scoped; forwarding is cross-channel — see
+// startBridge — so a plugin on its own random channel still reaches the CLI):
 //   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 } }
@@ -33,6 +34,11 @@ function manifestPath(): string {
 
 export function startBridge(port: number): void {
   const channels = new Map<string, Set<ServerWebSocket<WsData>>>();
+  // Every connected peer, regardless of channel. The relay is single-user and
+  // local (one plugin + one CLI at a time), so we bridge across channels: the
+  // CLI joins "figma-api" while the community TTF plugin picks its own random
+  // channel — forwarding to all *other* peers spares the user copying it.
+  const all = new Set<ServerWebSocket<WsData>>();
 
   Bun.serve<WsData, undefined>({
     port,
@@ -45,6 +51,7 @@ export function startBridge(port: number): void {
       // drop-in: welcome on open, two-part join ack, peer notices, broadcasts
       // wrapped as {type:"broadcast", sender:"peer", message:<inner>}.
       open(ws) {
+        all.add(ws);
         ws.send(JSON.stringify({ type: "system", message: "Please join a channel to start chatting" }));
       },
       message(ws, raw) {
@@ -68,18 +75,21 @@ export function startBridge(port: number): void {
         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; }
 
+        // Forward across ALL peers (not just the sender's channel) so the CLI and
+        // the community plugin bridge even when their channel names differ.
         // 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));
+          for (const peer of all) if (peer !== ws) peer.send(JSON.stringify(msg));
           return;
         }
         if (msg.type !== "message") return;
 
         // 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);
+        for (const peer of all) if (peer !== ws) peer.send(out);
       },
       close(ws) {
+        all.delete(ws);
         const ch = ws.data.channel;
         if (!ch) return;
         const peers = channels.get(ch);
@@ -92,7 +102,7 @@ export function startBridge(port: number): void {
   });
 
   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.`);
+  console.log(`Open a plugin, click Connect (any channel — the relay bridges them), then run figma-api commands.`);
 }
 
 /** Setup instructions shown only when a canvas command can't reach the plugin. */
@@ -102,14 +112,25 @@ the plugin bridge, which the user must install.
 
 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):
+runs in THEIR Figma, you can't do the plugin step 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, set the URL to ws://localhost:${port} and channel "${DEFAULT_CHANNEL}", click Connect.
+
+  2. Install & connect a plugin — pick ONE:
+     EASY (recommended): install "Cursor Talk To Figma MCP" from the Figma
+       Community (figma.com/community/plugin/1485687494525374295), run it, set
+       port ${port}, click Connect. It picks its own random channel — that's fine,
+       the relay bridges channels so you do NOT need to copy it or pass --channel.
+     ADVANCED: in the Figma DESKTOP app, Plugins → Development → Import plugin
+       from manifest → ${manifestPath()}
+       run it, set URL ws://localhost:${port}, channel "${DEFAULT_CHANNEL}", Connect.
+
   3. Retry. Verify the round-trip with:  figma-api ping
-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.`;
+
+USE THE DESKTOP APP. Both plugins can be *opened* in browser Figma, but a browser
+tab can't reach ws://localhost:${port} (mixed-content: an https page blocks insecure
+ws), so it never reaches "Connected". Desktop has no such block. If desktop is truly
+impossible, expose the relay over TLS — 'cloudflared tunnel --url http://localhost:${port}'
+— and paste that wss:// URL into the plugin. (Dev-manifest import is desktop-only.)`;
 
 /** CLI peer: connect to the relay, send one command, return the plugin's result. */
 export function sendCommand(

package/src/index.ts

@@ -640,13 +640,19 @@ 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 →
-     plugin/manifest.json, run it, set URL ws://localhost:${DEFAULT_PORT} + channel
-     "${DEFAULT_CHANNEL}", click Connect.
+  2. Connect a plugin in the Figma DESKTOP app (pick one):
+       EASY: install "Cursor Talk To Figma MCP" from the Figma Community, run it,
+         set port ${DEFAULT_PORT}, Connect. Its random channel is fine — the relay
+         bridges channels, so no --channel needed.
+       ADVANCED: Plugins → Development → Import plugin from manifest →
+         plugin/manifest.json, set URL ws://localhost:${DEFAULT_PORT}, channel
+         "${DEFAULT_CHANNEL}", Connect.
   3. figma-api ping                         # verify; then create-frame / create-text / …
 
-Cross-machine: expose the relay with 'cloudflared tunnel --url http://localhost:${DEFAULT_PORT}'
-and paste the wss:// URL into the plugin.
+Use the DESKTOP app: a browser tab can't reach ws://localhost:${DEFAULT_PORT} (an https
+page blocks insecure ws), so it never connects. If desktop is impossible, expose the
+relay over TLS 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.`)
@@ -654,8 +660,10 @@ Figma document. Only run it on a trusted machine/network.`)
 
 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"));
+  .addHelpText("after", `\nReturns the current document info. Works with both the bundled plugin and the\ncommunity Cursor-Talk-To-Figma plugin.\nExample:\n  figma-api ping`)
+  // get_document_info exists in both the bundled and the community plugin (unlike
+  // "ping", which is bundled-only), so verification works whichever is connected.
+  .action((o: any) => drive(o, "get_document_info"));
 
 // ── canvas reads ──────────────────────────────────────────────────────────────
 canvas("get-document-info")