figrelay 0.0.0-stage → 0.8.1

package/bin/plugin/manifest.json

@@ -0,0 +1,14 @@
+{
+  "name": "Figma Relay",
+  "id": "figrelay-dev",
+  "api": "1.0.0",
+  "main": "code.js",
+  "ui": "ui.html",
+  "editorType": ["figma"],
+  "documentAccess": "dynamic-page",
+  "networkAccess": {
+    "allowedDomains": ["none"],
+    "devAllowedDomains": ["ws://localhost:2000"],
+    "reasoning": "Connects to a local MCP bridge server so AI assistants can read and edit this file."
+  }
+}

package/bin/plugin/ui.html

@@ -0,0 +1,559 @@
+<style>
+  * {
+    box-sizing: border-box;
+  }
+
+  html,
+  body {
+    height: 100%;
+  }
+
+  body {
+    font:
+      12px/1.5 -apple-system,
+      BlinkMacSystemFont,
+      "Segoe UI",
+      sans-serif;
+    margin: 0;
+    padding: 10px;
+    color: #2c2c34;
+    background: linear-gradient(160deg, #f6f7fb 0%, #eef0f7 100%);
+    display: flex;
+    flex-direction: column;
+  }
+
+  .card {
+    background: #fff;
+    border: 1px solid #e6e8f0;
+    border-radius: 9px;
+    padding: 7px 9px;
+    box-shadow: 0 1px 2px rgba(30, 34, 60, 0.04);
+  }
+
+  #status-row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    cursor: pointer;
+    font-weight: 600;
+    font-size: 13px;
+    color: #1f2330;
+  }
+
+  #dot {
+    flex: none;
+    width: 9px;
+    height: 9px;
+    border-radius: 50%;
+    background: #e0555b;
+    box-shadow: 0 0 0 3px rgba(224, 85, 91, 0.15);
+    transition:
+      background 0.2s,
+      box-shadow 0.2s;
+  }
+
+  #dot.on {
+    background: #22a06b;
+    box-shadow: 0 0 0 3px rgba(34, 160, 107, 0.15);
+  }
+
+  #hint {
+    color: #6b6f7d;
+    margin-top: 5px;
+    font-size: 10px;
+    line-height: 1.35;
+  }
+
+  #result {
+    display: none;
+    margin-top: 10px;
+    border-top: 1px solid #eceef5;
+    padding-top: 9px;
+  }
+
+  #result.show {
+    display: block;
+  }
+
+  .res-head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 6px;
+  }
+
+  .res-title {
+    font-weight: 600;
+    font-size: 11px;
+    color: #1f2330;
+  }
+
+  .res-list {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    max-height: 190px;
+    overflow: auto;
+  }
+
+  .res-row {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    padding: 5px 7px;
+    border: 1px solid #e6e8f0;
+    border-radius: 7px;
+    background: #fbfcfe;
+  }
+
+  .res-name {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: 11px;
+    color: #2c2c34;
+  }
+
+  .res-type {
+    flex: none;
+    font-size: 9px;
+    color: #a0a4b0;
+    text-transform: uppercase;
+    letter-spacing: 0.03em;
+  }
+
+  .copy-btn {
+    flex: none;
+    border: 1px solid #d6d9e6;
+    background: #fff;
+    color: #4b5168;
+    border-radius: 6px;
+    padding: 2px 8px;
+    font-size: 10px;
+    cursor: pointer;
+  }
+
+  .copy-btn:hover {
+    background: #f0f2f8;
+  }
+
+  .copy-btn.done {
+    color: #22a06b;
+    border-color: #bfe6d3;
+    background: #f0faf5;
+  }
+
+  .copy-all {
+    padding: 1px 6px;
+    font-size: 10px;
+  }
+
+  .filter-row {
+    display: flex;
+    gap: 4px;
+    margin-bottom: 8px;
+  }
+
+  .filter-btn {
+    flex: none;
+    border: 1px solid #d6d9e6;
+    background: #fff;
+    color: #6b6f7d;
+    border-radius: 6px;
+    padding: 3px 9px;
+    font-size: 10px;
+    cursor: pointer;
+  }
+
+  .filter-btn:hover {
+    background: #f0f2f8;
+  }
+
+  .filter-btn.on {
+    background: #2c2c34;
+    border-color: #2c2c34;
+    color: #fff;
+  }
+
+  .res-empty {
+    font-size: 11px;
+    color: #a0a4b0;
+    padding: 6px 2px;
+  }
+
+  .key-prompt {
+    margin-bottom: 8px;
+    padding: 7px 8px;
+    border: 1px solid #ffe0a6;
+    background: #fff9ec;
+    border-radius: 7px;
+  }
+
+  .key-note {
+    font-size: 10px;
+    color: #8a6d3b;
+    line-height: 1.4;
+    margin-bottom: 5px;
+  }
+
+  .key-input-row {
+    display: flex;
+    gap: 4px;
+  }
+
+  .key-input {
+    flex: 1;
+    min-width: 0;
+    border: 1px solid #d6d9e6;
+    border-radius: 6px;
+    padding: 3px 6px;
+    font-size: 10px;
+  }
+
+  .key-save {
+    flex: none;
+    border: 1px solid #d6d9e6;
+    background: #fff;
+    border-radius: 6px;
+    padding: 3px 10px;
+    font-size: 10px;
+    cursor: pointer;
+  }
+
+  .key-save:hover {
+    background: #f0f2f8;
+  }
+
+  #credit {
+    margin-top: auto;
+    padding-top: 7px;
+    text-align: center;
+    color: #a0a4b0;
+    font-size: 10px;
+  }
+
+  #version {
+    color: #8288a0;
+    margin-right: 4px;
+  }
+
+  #credit a {
+    color: #8288a0;
+    text-decoration: none;
+  }
+
+  #credit a:hover {
+    text-decoration: underline;
+  }
+</style>
+
+<div class="card">
+  <div id="status-row">
+    <span id="dot"></span><span id="status">Connecting…</span>
+  </div>
+  <div id="hint">Keep open while AI works · run it in every file.</div>
+  <div id="result"></div>
+</div>
+<div id="credit">
+  <span id="version"></span>
+  <a href="https://github.com/quannh287/figma-relay" target="_blank">@quannh287</a>
+</div>
+
+<script>
+  // Bridge UI: connect to the shared MCP bridge on localhost and relay
+  // frames between it and the plugin main thread.
+  //
+  // One bridge serves every plugin window and every MCP session, so there is
+  // a single well-known port (also the only one the manifest's
+  // devAllowedDomains permits). While disconnected we retry on a short loop;
+  // background tabs throttle timers, so a visibility change and a click on
+  // the status line also trigger an immediate attempt.
+  const PORT = 2000,
+    RETRY = 1000,
+    PROTOCOL = 4; // must match bridge.ProtocolVersion in the Go server
+  let ws = null; // open connection, null while disconnected
+  let attempt = null; // socket currently trying to connect
+  let reg = null; // {key, name} of this file, sent by the main thread
+  let protoWarning = null; // set when the server reports a newer protocol
+
+  function setStatus(connected, text) {
+    document.getElementById("dot").className = connected ? "on" : "";
+    document.getElementById("status").textContent = text;
+  }
+
+  function label() {
+    if (protoWarning) return protoWarning;
+    return reg ? "Connected · " + reg.name : "Connected (port " + PORT + ")";
+  }
+
+  function sendRegister() {
+    if (ws && ws.readyState === WebSocket.OPEN && reg) {
+      ws.send(JSON.stringify({ register: reg }));
+    }
+  }
+
+  function connect() {
+    if (ws || attempt) return;
+    let sock;
+    try {
+      sock = new WebSocket("ws://localhost:" + PORT + "/ws");
+    } catch (e) {
+      schedule();
+      return;
+    }
+    attempt = sock;
+    sock.onopen = () => {
+      attempt = null;
+      ws = sock;
+      sendRegister();
+      setStatus(true, label());
+    };
+    sock.onmessage = (e) => {
+      const msg = JSON.parse(e.data);
+      if (msg.hello) {
+        // Show which server build we are talking to; "dev" means a local
+        // go build rather than a release.
+        if (msg.hello.version) {
+          document.getElementById("version").textContent = "v" + msg.hello.version;
+        }
+        // Name the side that is behind: a stale server is just as common as
+        // a stale plugin, and blaming the plugin sends people re-importing
+        // a plugin that was already up to date.
+        protoWarning = null;
+        if (msg.hello.protocol && msg.hello.protocol !== PROTOCOL) {
+          // npx figrelay@latest only fetches the new server when the AI client restarts it.
+          protoWarning =
+            msg.hello.protocol < PROTOCOL
+              ? "⚠ Server outdated — restart your AI client"
+              : "⚠ Plugin outdated — re-import from the latest release";
+        }
+        setStatus(true, label());
+        return;
+      }
+      // Relay server request to the plugin main thread.
+      parent.postMessage({ pluginMessage: msg }, "*");
+    };
+    sock.onclose = () => {
+      if (attempt === sock) attempt = null;
+      if (ws === sock) ws = null;
+      if (!ws) {
+        setStatus(false, "Searching for MCP server…");
+        schedule();
+      }
+    };
+    sock.onerror = () => {
+      try {
+        sock.close();
+      } catch (e) { }
+    };
+  }
+
+  let retryTimer = null;
+  function schedule() {
+    if (retryTimer) return;
+    retryTimer = setTimeout(() => {
+      retryTimer = null;
+      connect();
+    }, RETRY);
+  }
+
+  // ---- live selection list (name + copyable link, filterable by type) ----
+  let selItems = []; // everything currently selected in Figma
+  let shownItems = []; // selItems after the active type filter
+  let selFilter = "all"; // all | frame | vector
+  let hasKey = false; // whether the main thread knows this file's key
+
+  // Pull the file key out of a pasted Figma URL (…/design/<key>/…), or accept
+  // a bare key. Returns "" when nothing usable is found.
+  function parseFileKey(s) {
+    s = (s || "").trim();
+    const m = s.match(/figma\.com\/(?:file|design|board|proto)\/([A-Za-z0-9]+)/i);
+    if (m) return m[1];
+    if (/^[A-Za-z0-9]{10,}$/.test(s)) return s;
+    return "";
+  }
+
+  const FILTERS = [
+    { key: "all", label: "All" },
+    { key: "frame", label: "Frame" },
+    { key: "vector", label: "Vector" },
+    { key: "instance", label: "Instance" },
+  ];
+
+  function esc(s) {
+    return String(s)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;");
+  }
+
+  function matches(it) {
+    if (selFilter === "frame") return it.type === "FRAME";
+    if (selFilter === "vector") return it.type === "VECTOR";
+    if (selFilter === "instance") return it.type === "INSTANCE";
+    return true;
+  }
+
+  // Frames copy as a link block; every other element copies its exported SVG.
+  function copyLabelFor(it) {
+    return it.type === "FRAME" ? "Copy" : "Copy SVG";
+  }
+
+  // Copyable text for one item. Frames use the requested link format:
+  //   # <name>:
+  //   <link>
+  // Other elements return their SVG (or the export error, so the click still
+  // gives feedback instead of silently copying nothing).
+  function copyValueForItem(it) {
+    if (it.type === "FRAME") return "# " + it.name + ":\n" + (it.link || "");
+    return it.svg || it.svgError || "";
+  }
+
+  function renderSelection(items) {
+    if (items) selItems = items;
+    drawSelection();
+  }
+
+  function drawSelection() {
+    const box = document.getElementById("result");
+    if (!selItems.length) {
+      box.className = "";
+      box.innerHTML = "";
+      return;
+    }
+    shownItems = selItems.filter(matches);
+
+    // Only frames need a link (and therefore the file key); a pure vector /
+    // instance selection copies SVG, so don't nag for a URL then.
+    const needsKey = !hasKey && selItems.some((it) => it.type === "FRAME");
+    const keyPrompt = !needsKey
+      ? ""
+      : '<div class="key-prompt">' +
+      '<div class="key-note">Links are empty: this file has no key yet. Paste the file URL once ' +
+      "(Share → Copy link, or the browser address bar):</div>" +
+      '<div class="key-input-row">' +
+      '<input class="key-input" id="key-input" placeholder="https://www.figma.com/design/…" />' +
+      '<button class="key-save" id="key-save">Save</button>' +
+      "</div></div>";
+
+    const filterBar =
+      '<div class="filter-row">' +
+      FILTERS.map(
+        (f) =>
+          '<button class="filter-btn' + (selFilter === f.key ? " on" : "") + '" data-f="' + f.key + '">' +
+          f.label + "</button>",
+      ).join("") +
+      "</div>";
+
+    const head =
+      '<div class="res-head"><span class="res-title">Selected (' + shownItems.length + ")</span>" +
+      (shownItems.length > 1 ? '<button class="copy-btn copy-all" data-all="1">Copy all</button>' : "") +
+      "</div>";
+
+    const body = shownItems.length
+      ? '<div class="res-list">' +
+      shownItems
+        .map(
+          (it, i) =>
+            '<div class="res-row">' +
+            '<span class="res-name" title="' + esc(it.name) + '">' + esc(it.name) + "</span>" +
+            '<span class="res-type">' + esc(it.type) + "</span>" +
+            '<button class="copy-btn" data-i="' + i + '">' + copyLabelFor(it) + "</button>" +
+            "</div>",
+        )
+        .join("") +
+      "</div>"
+      : '<div class="res-empty">No matching nodes selected.</div>';
+
+    box.innerHTML = keyPrompt + filterBar + head + body;
+    box.className = "show";
+  }
+
+  // What each button copies: a row copies its own value (link block for a
+  // frame, SVG otherwise); "Copy all" joins every shown item with a blank
+  // line between — filter to one type first for a homogeneous result.
+  function copyValueFor(btn) {
+    if (btn.hasAttribute("data-all")) {
+      return shownItems.map(copyValueForItem).join("\n\n");
+    }
+    const it = shownItems[+btn.getAttribute("data-i")];
+    return it ? copyValueForItem(it) : "";
+  }
+
+  // navigator.clipboard is often unavailable in the plugin iframe, so use the
+  // textarea + execCommand fallback which works reliably here.
+  function copyText(text) {
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.style.position = "fixed";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    try {
+      document.execCommand("copy");
+    } catch (e) { }
+    document.body.removeChild(ta);
+  }
+
+  document.getElementById("result").addEventListener("click", (e) => {
+    if (e.target.id === "key-save") {
+      const inp = document.getElementById("key-input");
+      const key = parseFileKey(inp ? inp.value : "");
+      if (key) {
+        parent.postMessage({ pluginMessage: { setFileKey: key } }, "*");
+      } else if (inp) {
+        inp.value = "";
+        inp.placeholder = "Couldn't read a file key from that — paste the full URL";
+      }
+      return;
+    }
+    const fb = e.target.closest(".filter-btn");
+    if (fb) {
+      selFilter = fb.getAttribute("data-f");
+      drawSelection();
+      return;
+    }
+    const btn = e.target.closest(".copy-btn");
+    if (!btn) return;
+    copyText(copyValueFor(btn));
+    const old = btn.textContent;
+    btn.textContent = "Copied";
+    btn.classList.add("done");
+    setTimeout(() => {
+      btn.textContent = old;
+      btn.classList.remove("done");
+    }, 1200);
+  });
+
+  // Relay plugin main-thread frames: the register frame is cached here and
+  // re-sent on every reconnect, the selection frame drives the list above, and
+  // everything else goes to the server.
+  window.onmessage = (e) => {
+    const msg = e.data.pluginMessage;
+    if (!msg) return;
+    if (msg.register) {
+      reg = msg.register;
+      sendRegister();
+      if (ws) setStatus(true, label());
+      return;
+    }
+    if (Array.isArray(msg.selection)) {
+      hasKey = !!msg.hasKey;
+      renderSelection(msg.selection);
+      return;
+    }
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  };
+
+  document.getElementById("status-row").onclick = () => connect();
+  document.addEventListener("visibilitychange", () => {
+    if (!document.hidden && !ws) connect();
+  });
+
+  connect();
+</script>

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "figrelay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1",
+  "scripts": {
+    "prepublishOnly": "cp ../README.md ./README.md"
+  },
+  "description": "Figma MCP server (fork of figma-mcp-console) for AI coding assistants — real-time read/write via a Figma Desktop plugin. No API token, no rate limits.",
+  "bin": {
+    "figrelay": "run.js"
+  },
+  "files": [
+    "run.js",
+    "bin/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quannh287/figma-relay.git"
+  },
+  "homepage": "https://github.com/quannh287/figma-relay#readme",
+  "bugs": {
+    "url": "https://github.com/quannh287/figma-relay/issues"
+  },
+  "keywords": [
+    "figma",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "figma-mcp-console",
+    "design"
+  ],
+  "license": "MIT"
+}

package/run.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Run the Go binary bundled in the npm package — NO network/GitHub download.
+// stdout is the MCP transport → all wrapper logs go to stderr.
+"use strict";
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const plat = process.platform === "win32" ? "windows" : process.platform; // darwin|linux|windows
+const arch = { x64: "amd64", arm64: "arm64" }[process.arch];
+function fail(m) {
+  process.stderr.write(`figrelay: ${m}\n`);
+  process.exit(1);
+}
+if (!arch || !["darwin", "linux", "windows"].includes(plat))
+  fail(`unsupported platform: ${process.platform}/${process.arch}`);
+
+const exe = plat === "windows" ? ".exe" : "";
+const binPath = path.join(
+  __dirname,
+  "bin",
+  `${plat}-${arch}`,
+  `figma-mcp${exe}`,
+);
+
+// Subcommand: install-plugin — extract the plugin into a VISIBLE folder (no leading dot)
+// and open that folder so the user sees manifest.json right away.
+if (process.argv[2] === "install-plugin") {
+  const srcDir = path.join(__dirname, "bin", "plugin");
+  const destDir = path.join(os.homedir(), "figrelay-plugin");
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const f of ["code.js", "ui.html", "manifest.json"])
+    fs.copyFileSync(path.join(srcDir, f), path.join(destDir, f));
+
+  process.stdout.write(
+    "\n✅ Figma plugin ready.\n\n" +
+      "In Figma Desktop → Plugins → Development → Import plugin from manifest…\n" +
+      "and select this file:\n\n" +
+      "   " +
+      path.join(destDir, "manifest.json") +
+      "\n\n",
+  );
+
+  // Open the folder in the file manager (best-effort; ignore errors).
+  const opener =
+    plat === "darwin" ? "open" : plat === "windows" ? "explorer" : "xdg-open";
+  try {
+    spawnSync(opener, [destDir], { stdio: "ignore", detached: true });
+  } catch (_) {}
+  process.exit(0);
+}
+
+if (!fs.existsSync(binPath)) fail(`binary not found for ${plat}-${arch}`);
+try {
+  fs.chmodSync(binPath, 0o755);
+} catch (_) {}
+const r = spawnSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+if (r.error) fail(`failed to start server: ${r.error.message}`);
+process.exit(r.status === null ? 1 : r.status);