@ttsalpha/mirra 1.1.0 → 1.3.0

package/README.md

@@ -1,4 +1,8 @@
-# Mirra
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ttsalpha/mirra/refs/heads/main/assets/icon.png" width="96" height="96" alt="" />
+</p>
+
+<h1 align="center">Mirra</h1>
 
 Two-way MCP server for Figma: an agent reads a design and renders one back through the
 Figma Plugin API, so it needs no REST token and has no per-month call limit.
@@ -61,11 +65,13 @@ skips all of it. The command is written with the real path of the Node binary th
 because a version manager puts `node` behind a path that changes with every shell and a
 GUI client never sees it.
 
-Then, by hand:
+It also registers the plugin with Figma Desktop by writing into Figma's own settings,
+which only works while Figma is **closed** — that file is rewritten from memory on quit.
+If Figma is running, or the format turns out to be one Mirra does not recognise, `init` says
+so and falls back to the manual route: Figma Desktop → Plugins → Development → Import plugin
+from manifest… → `~/.mirra/plugin/manifest.json`.
 
-1. Figma Desktop → Plugins → Development → Import plugin from manifest… →
-   `~/.mirra/plugin/manifest.json`
-2. **Restart the clients**, or they will not see the tools
+Either way, **restart the clients**, or they will not see the tools.
 
 And once per working session: open a file in Figma, run the Mirra plugin, leave its panel
 open. Figma has no background plugins, so closing the panel ends the connection.
@@ -104,7 +110,7 @@ the tool when `MIRRA_ALLOW_EXEC` is set, and the plugin only runs it while **All
 execution** is ticked in its panel. The tick resets every time the plugin runs.
 
 ```sh
-claude mcp add -s user mirra-exec -e MIRRA_ALLOW_EXEC=1 -- npx -y @ttsalpha/mirra serve
+claude mcp add -s user Mirra-exec -e MIRRA_ALLOW_EXEC=1 -- npx -y @ttsalpha/mirra serve
 ```
 
 The socket listens on loopback and refuses any browser origin other than Figma's, so a page

package/dist/index.js

@@ -32495,15 +32495,19 @@ var PatchResult = external_exports.object({
   keys: external_exports.record(external_exports.string(), external_exports.string())
 });
 var ScreenshotParams = external_exports.object({
-  /** Defaults to the current selection, or the page if nothing is selected. */
+  /** Defaults to the current selection. */
   target: Target.optional(),
-  scale: external_exports.number().min(0.1).max(4).optional()
+  scale: external_exports.number().min(0.1).max(4).optional(),
+  /** Longest edge in pixels; the scale is lowered to fit, not refused. */
+  maxEdge: external_exports.number().int().min(64).max(4096).optional()
 });
 var ScreenshotResult = external_exports.object({
   id: external_exports.string(),
   name: external_exports.string(),
   width: external_exports.number(),
   height: external_exports.number(),
+  /** What the export used, once maxEdge had its say. */
+  scale: external_exports.number(),
   /** base64 PNG. */
   png: external_exports.string()
 });
@@ -32620,7 +32624,9 @@ var ReadParams = external_exports.object({
   /** Defaults to the current selection. */
   nodeId: external_exports.string().optional(),
   /** How many levels of children to walk. */
-  depth: external_exports.number().int().min(0).max(20).optional()
+  depth: external_exports.number().int().min(0).max(20).optional(),
+  /** Most nodes to return, so one call cannot fill the context. */
+  limit: external_exports.number().int().min(1).max(2e3).optional()
 });
 var ReadResult = external_exports.object({
   nodes: external_exports.array(external_exports.object({ id: external_exports.string(), tree: UINode })),
@@ -32631,7 +32637,8 @@ var PingResult = external_exports.object({
   fileName: external_exports.string(),
   fileKey: external_exports.string().nullable(),
   currentPage: external_exports.string(),
-  selectionCount: external_exports.number()
+  selectionCount: external_exports.number(),
+  pluginVersion: external_exports.string()
 });
 
 // src/clients.ts
@@ -32640,7 +32647,8 @@ import { access, copyFile, readFile, rename, writeFile } from "node:fs/promises"
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { realpath } from "node:fs/promises";
-var SERVER_NAME = "mirra";
+var SERVER_NAME = "Mirra";
+var LEGACY_NAME = "mirra";
 async function stableNodePath() {
   try {
     return await realpath(process.execPath);
@@ -32684,6 +32692,7 @@ async function writeEntry(target, node2, entryPoint) {
     const raw = await readFile(target.file, "utf8");
     const config2 = JSON.parse(raw);
     const servers = config2[target.key] ?? {};
+    delete servers[LEGACY_NAME];
     servers[SERVER_NAME] = {
       ...target.typed ? { type: "stdio" } : {},
       command: node2,
@@ -32708,6 +32717,7 @@ function claudeCode(node2, entryPoint) {
   const probe = spawnSync("claude", ["--version"], { stdio: "ignore" });
   if (probe.error)
     return { client: "Claude Code", status: "skipped", detail: "claude not on PATH" };
+  spawnSync("claude", ["mcp", "remove", "-s", "user", LEGACY_NAME], { stdio: "ignore" });
   const result = spawnSync(
     "claude",
     ["mcp", "add", "-s", "user", SERVER_NAME, "--", node2, entryPoint, "serve"],
@@ -32722,9 +32732,16 @@ function claudeCode(node2, entryPoint) {
   };
 }
 
+// src/figma-settings.ts
+import { execFile } from "node:child_process";
+import { readFile as readFile3, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname2, join as join3, sep as sep2 } from "node:path";
+import { promisify } from "node:util";
+
 // src/install.ts
 import { spawn } from "node:child_process";
-import { access as access2, cp, mkdir, readFile as readFile2 } from "node:fs/promises";
+import { access as access2, cp, mkdir, readFile as readFile2, rm } from "node:fs/promises";
 import { homedir as homedir2, platform } from "node:os";
 import { join as join2, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -32733,9 +32750,9 @@ var PLUGIN_HOME = join2(MIRRA_HOME, "plugin");
 var SERVER_HOME = join2(MIRRA_HOME, "server");
 var DIST = fileURLToPath(new URL(".", import.meta.url));
 var BUNDLED_PLUGIN = resolve(DIST, "plugin");
-async function installPlugin() {
+async function installPlugin(from = BUNDLED_PLUGIN) {
   await mkdir(PLUGIN_HOME, { recursive: true });
-  await cp(BUNDLED_PLUGIN, PLUGIN_HOME, { recursive: true });
+  await cp(from, PLUGIN_HOME, { recursive: true });
   const manifest = join2(PLUGIN_HOME, "manifest.json");
   return { manifest, version: await installedVersion() };
 }
@@ -32755,11 +32772,18 @@ async function isInstalled() {
     return false;
   }
 }
-async function installServer() {
-  const running = resolve(DIST, "index.js");
-  if (!DIST.includes(`${sep}_npx${sep}`)) return running;
+function isTransientInstall(directory) {
+  return directory.includes(`${sep}_npx${sep}`);
+}
+async function installServer(from = DIST) {
+  if (!isTransientInstall(from)) return resolve(from, "index.js");
+  const plugin = resolve(from, "plugin");
+  await rm(SERVER_HOME, { recursive: true, force: true });
   await mkdir(SERVER_HOME, { recursive: true });
-  await cp(DIST, SERVER_HOME, { recursive: true });
+  await cp(from, SERVER_HOME, {
+    recursive: true,
+    filter: (source) => source !== plugin && !source.startsWith(plugin + sep)
+  });
   return join2(SERVER_HOME, "index.js");
 }
 function reveal(path) {
@@ -32767,6 +32791,106 @@ function reveal(path) {
   spawn("open", ["-R", path], { stdio: "ignore", detached: true }).unref();
 }
 
+// src/figma-settings.ts
+var FIGMA_SETTINGS = settingsPath();
+function settingsPath() {
+  if (process.platform === "darwin") {
+    return join3(homedir3(), "Library/Application Support/Figma/settings.json");
+  }
+  if (process.platform === "win32") {
+    const local = process.env["LOCALAPPDATA"] ?? join3(homedir3(), "AppData/Local");
+    return join3(local, "Figma/settings.json");
+  }
+  return join3(homedir3(), ".config/Figma/settings.json");
+}
+var PLUGIN_ID = "mirra-figma-bridge";
+async function registerPluginWithFigma(pluginDir) {
+  if (await isFigmaRunning()) {
+    return { status: "skipped", reason: "Figma Desktop is running; quit it first" };
+  }
+  let raw;
+  try {
+    raw = await readFile3(FIGMA_SETTINGS, "utf8");
+  } catch {
+    return { status: "skipped", reason: `no settings file at ${FIGMA_SETTINGS}` };
+  }
+  try {
+    const settings = JSON.parse(raw);
+    const entries = settings["localFileExtensions"];
+    if (!Array.isArray(entries)) {
+      return { status: "skipped", reason: "unfamiliar settings format" };
+    }
+    const next = rebuild(entries, pluginDir);
+    if (!next) return { status: "already" };
+    settings["localFileExtensions"] = next;
+    const temporary = join3(dirname2(FIGMA_SETTINGS), `.mirra-${process.pid}.json`);
+    await writeFile2(temporary, JSON.stringify(settings, null, 2));
+    await rename2(temporary, FIGMA_SETTINGS);
+    return { status: "registered" };
+  } catch (error62) {
+    return { status: "skipped", reason: error62 instanceof Error ? error62.message : String(error62) };
+  }
+}
+function rebuild(entries, pluginDir) {
+  const mine = entries.filter((entry) => isMine(entry, entries));
+  if (isCleanTrio(mine, pluginDir)) return null;
+  const others = entries.filter((entry) => !mine.includes(entry));
+  return [...others, ...entriesFor(pluginDir, nextId(others))];
+}
+function isCleanTrio(mine, pluginDir) {
+  const manifest = mine.find((entry) => entry.fileMetadata.type === "manifest");
+  if (mine.length !== 3 || !manifest || manifest.fileMetadata.type !== "manifest") return false;
+  if (manifest.manifestPath !== join3(pluginDir, "manifest.json")) return false;
+  const { codeFileId, uiFileIds } = manifest.fileMetadata;
+  const paths = new Map(mine.map((entry) => [entry.id, entry.manifestPath]));
+  return paths.get(codeFileId) === join3(pluginDir, "main.js") && uiFileIds.length === 1 && paths.get(uiFileIds[0]) === join3(pluginDir, "ui.html");
+}
+function isMine(entry, all) {
+  if (entry.lastKnownPluginId === PLUGIN_ID) return true;
+  if (entry.manifestPath.startsWith(`${MIRRA_HOME}${sep2}`)) return true;
+  const metadata = entry.fileMetadata;
+  return metadata.type !== "manifest" && !all.some((e) => e.id === metadata.manifestFileId);
+}
+async function isFigmaRunning() {
+  const run = promisify(execFile);
+  try {
+    if (process.platform === "win32") {
+      const { stdout } = await run("tasklist", ["/fi", "imagename eq Figma.exe", "/nh"]);
+      return stdout.includes("Figma.exe");
+    }
+    await run("pgrep", ["-x", "Figma"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function nextId(entries) {
+  return entries.reduce((highest, entry) => Math.max(highest, entry.id), 0) + 1;
+}
+function entriesFor(pluginDir, first) {
+  const [manifestId, codeId, uiId] = [first, first + 1, first + 2];
+  return [
+    {
+      id: manifestId,
+      manifestPath: join3(pluginDir, "manifest.json"),
+      lastKnownName: "Mirra",
+      lastKnownPluginId: PLUGIN_ID,
+      cachedContainsWidget: false,
+      fileMetadata: { type: "manifest", codeFileId: codeId, uiFileIds: [uiId] }
+    },
+    {
+      id: codeId,
+      manifestPath: join3(pluginDir, "main.js"),
+      fileMetadata: { type: "code", manifestFileId: manifestId }
+    },
+    {
+      id: uiId,
+      manifestPath: join3(pluginDir, "ui.html"),
+      fileMetadata: { type: "ui", manifestFileId: manifestId }
+    }
+  ];
+}
+
 // ../../node_modules/.pnpm/zod@4.6.7/node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
@@ -40803,6 +40927,22 @@ var EMPTY_COMPLETION_RESULT = {
   }
 };
 
+// src/version.ts
+var SERVER_VERSION = "1.3.0";
+
+// src/tools/annotations.ts
+var READS = { readOnlyHint: true, openWorldHint: false };
+var ADDS = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  openWorldHint: false
+};
+var CHANGES = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  openWorldHint: false
+};
+
 // src/errors.ts
 var MirraError = class extends Error {
   constructor(message, code, hint) {
@@ -40833,7 +40973,12 @@ value keyed by mode name sets one value per mode. Both halves are optional.`;
 function registerDefine(server, bridge) {
   server.registerTool(
     "mirra_define_tokens",
-    { title: "Define Figma variables", description: DESCRIPTION, inputSchema: DefineParams.shape },
+    {
+      annotations: CHANGES,
+      title: "Define Figma variables",
+      description: DESCRIPTION,
+      inputSchema: DefineParams.shape
+    },
     async (params) => {
       try {
         const result = DefineResult.parse(await bridge.request("define", params));
@@ -40859,7 +41004,12 @@ The body is an async function receiving \`figma\`; use it only for what the type
 function registerExec(server, bridge) {
   server.registerTool(
     "mirra_exec",
-    { title: "Run Plugin API code", description: DESCRIPTION2, inputSchema: ExecParams.shape },
+    {
+      annotations: CHANGES,
+      title: "Run Plugin API code",
+      description: DESCRIPTION2,
+      inputSchema: ExecParams.shape
+    },
     async (params) => {
       try {
         const result = ExecResult.parse(await bridge.request("exec", params));
@@ -40872,11 +41022,11 @@ function registerExec(server, bridge) {
 }
 
 // src/tools/export.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
+import { mkdir as mkdir2, writeFile as writeFile3 } from "node:fs/promises";
 import { resolve as resolve3 } from "node:path";
 
 // src/tools/paths.ts
-import { resolve as resolve2, sep as sep2 } from "node:path";
+import { resolve as resolve2, sep as sep3 } from "node:path";
 function rootDirectory() {
   const configured = process.env["MIRRA_ROOT"];
   return configured ? resolve2(configured) : process.cwd();
@@ -40885,7 +41035,7 @@ function resolveInRoot(path) {
   const root = rootDirectory();
   const full = resolve2(root, path);
   if (!process.env["MIRRA_ROOT"]) return full;
-  if (full !== root && !full.startsWith(root + sep2)) {
+  if (full !== root && !full.startsWith(root + sep3)) {
     throw new MirraError(
       `${path} is outside MIRRA_ROOT`,
       "outside_root",
@@ -40902,6 +41052,7 @@ function registerExport(server, bridge) {
   server.registerTool(
     "mirra_export_assets",
     {
+      annotations: CHANGES,
       title: "Export Figma layers to files",
       description: DESCRIPTION3,
       inputSchema: ExportParams.shape
@@ -40914,7 +41065,7 @@ function registerExport(server, bridge) {
         const written = [];
         for (const asset2 of result.assets) {
           const file2 = resolve3(directory, `${slug(asset2.name)}.${asset2.extension}`);
-          await writeFile2(file2, Buffer.from(asset2.data, "base64"));
+          await writeFile3(file2, Buffer.from(asset2.data, "base64"));
           written.push(file2);
         }
         return text([`wrote ${written.length} file(s):`, ...written]);
@@ -40937,7 +41088,12 @@ tool works on the current page, so start here when the layer you want is elsewhe
 function registerFind(server, bridge) {
   server.registerTool(
     "mirra_find",
-    { title: "Find Figma layers", description: FIND, inputSchema: FindParams.shape },
+    {
+      annotations: READS,
+      title: "Find Figma layers",
+      description: FIND,
+      inputSchema: FindParams.shape
+    },
     async (params) => {
       try {
         const result = FindResult.parse(await bridge.request("find", params));
@@ -40955,7 +41111,13 @@ function registerFind(server, bridge) {
   );
   server.registerTool(
     "mirra_pages",
-    { title: "List or switch Figma pages", description: PAGES, inputSchema: PagesParams.shape },
+    {
+      // Not read-only: it can add a page and change which one is current.
+      annotations: ADDS,
+      title: "List, add or switch Figma pages",
+      description: PAGES,
+      inputSchema: PagesParams.shape
+    },
     async (params) => {
       try {
         const result = PagesResult.parse(await bridge.request("pages", params));
@@ -40970,7 +41132,7 @@ function registerFind(server, bridge) {
 }
 
 // src/tools/assets.ts
-import { readFile as readFile3 } from "node:fs/promises";
+import { readFile as readFile4 } from "node:fs/promises";
 import { extname } from "node:path";
 var MIME = /* @__PURE__ */ new Map([
   [".png", "image/png"],
@@ -41000,13 +41162,13 @@ function isPath(src) {
   return true;
 }
 async function readSvg(path) {
-  return readFile3(resolveInRoot(path), "utf8");
+  return readFile4(resolveInRoot(path), "utf8");
 }
 async function readImage(path) {
   const file2 = resolveInRoot(path);
   const type = MIME.get(extname(file2).toLowerCase());
   if (!type) throw new Error(`Unsupported image type: ${extname(file2) || file2}`);
-  return `data:${type};base64,${(await readFile3(file2)).toString("base64")}`;
+  return `data:${type};base64,${(await readFile4(file2)).toString("base64")}`;
 }
 
 // src/tools/patch.ts
@@ -41018,6 +41180,7 @@ function registerPatch(server, bridge) {
   server.registerTool(
     "mirra_patch",
     {
+      annotations: CHANGES,
       title: "Patch existing Figma layers",
       description: DESCRIPTION4,
       inputSchema: PatchParams.shape
@@ -41042,17 +41205,25 @@ function registerPing(server, bridge) {
   server.registerTool(
     "mirra_ping",
     {
+      annotations: READS,
       title: "Ping the Figma plugin",
       description: "Check that the Mirra plugin is connected, and report the open file, current page and selection size."
     },
     async () => {
       try {
         const result = PingResult.parse(await bridge.request("ping"));
+        const drifted = result.pluginVersion !== SERVER_VERSION;
         return text([
           `file: ${result.fileName}${result.fileKey ? ` (${result.fileKey})` : ""}`,
           `page: ${result.currentPage}`,
           `selection: ${result.selectionCount} node(s)`,
-          `port: ${bridge.status.port}`
+          `port: ${bridge.status.port}`,
+          `server ${SERVER_VERSION}, plugin ${result.pluginVersion}`,
+          ...drifted ? [
+            "",
+            "The two halves are different versions. Run `npx @ttsalpha/mirra init`, then run",
+            "the plugin again in Figma so both come from the same release."
+          ] : []
         ]);
       } catch (error62) {
         return text([describeError(error62)], true);
@@ -41064,11 +41235,13 @@ function registerPing(server, bridge) {
 // src/tools/read.ts
 var DESCRIPTION5 = `Read layers out of the open Figma file as the same tree mirra_render takes,
 so a design can be edited or turned into code without learning a second format.
-Reads the current selection unless a nodeId is given.`;
+Reads the current selection unless a nodeId is given, and at most 200 nodes unless limit
+says otherwise, so a large design cannot fill the context in one call.`;
 function registerRead(server, bridge) {
   server.registerTool(
     "mirra_read",
     {
+      annotations: READS,
       title: "Read Figma layers as a UI tree",
       description: DESCRIPTION5,
       inputSchema: ReadParams.shape
@@ -41076,7 +41249,9 @@ function registerRead(server, bridge) {
     async (params) => {
       try {
         const result = ReadResult.parse(await bridge.request("read", params));
-        const note = result.skipped ? [`${result.skipped} node(s) left out: unsupported type, or past the depth limit`] : [];
+        const note = result.skipped ? [
+          `${result.skipped} node(s) left out: unsupported type, or past the depth or node limit`
+        ] : [];
         return text([...note, JSON.stringify(result.nodes, null, 2)]);
       } catch (error62) {
         return text([describeError(error62)], true);
@@ -41096,6 +41271,7 @@ function registerRender(server, bridge) {
   server.registerTool(
     "mirra_render",
     {
+      annotations: ADDS,
       title: "Render a UI tree into Figma",
       description: DESCRIPTION6,
       inputSchema: RenderParams.shape
@@ -41119,11 +41295,13 @@ function registerRender(server, bridge) {
 
 // src/tools/screenshot.ts
 var DESCRIPTION7 = `Export a layer as a PNG and return the image, so the rendered result can be
-checked by eye and corrected with mirra_patch. Defaults to the current selection.`;
+checked by eye and corrected with mirra_patch. Defaults to the current selection. The scale
+is lowered when it has to be, so the longest edge stays within maxEdge, 1200px by default.`;
 function registerScreenshot(server, bridge) {
   server.registerTool(
     "mirra_screenshot",
     {
+      annotations: READS,
       title: "Screenshot a Figma layer",
       description: DESCRIPTION7,
       inputSchema: ScreenshotParams.shape
@@ -41135,7 +41313,7 @@ function registerScreenshot(server, bridge) {
           content: [
             {
               type: "text",
-              text: `${shot.name} (${shot.width}x${shot.height}, ${shot.id})`
+              text: `${shot.name} (${shot.width}x${shot.height}, ${shot.id})` + (shot.scale === 1 ? "" : ` at ${shot.scale.toFixed(2)}x`)
             },
             { type: "image", data: shot.png, mimeType: "image/png" }
           ]
@@ -41154,7 +41332,7 @@ bound to the design system instead of to a hardcoded value.`;
 function registerTokens(server, bridge) {
   server.registerTool(
     "mirra_tokens",
-    { title: "List design tokens", description: DESCRIPTION8 },
+    { annotations: READS, title: "List design tokens", description: DESCRIPTION8 },
     async () => {
       try {
         const result = TokensResult.parse(await bridge.request("tokens"));
@@ -41167,9 +41345,8 @@ function registerTokens(server, bridge) {
 }
 
 // src/mcp.ts
-var SERVER_VERSION = "1.1.0";
 function createMcpServer(bridge) {
-  const server = new McpServer({ name: "mirra", version: SERVER_VERSION });
+  const server = new McpServer({ name: "Mirra", version: SERVER_VERSION });
   registerPing(server, bridge);
   registerRender(server, bridge);
   registerRead(server, bridge);
@@ -41203,6 +41380,15 @@ var import_websocket_server = __toESM(require_websocket_server(), 1);
 // src/transport.ts
 var HOSTS = ["127.0.0.1", "::1"];
 var DEFAULT_TIMEOUT_MS = 3e4;
+var TIMEOUT_MS = {
+  ping: 5e3,
+  pages: 1e4,
+  render: 12e4,
+  patch: 12e4,
+  export: 12e4,
+  define: 6e4,
+  exec: 12e4
+};
 function originAllowed(origin) {
   if (!origin || origin === "null") return true;
   if (process.env["MIRRA_ALLOW_ORIGIN"] === origin) return true;
@@ -41213,16 +41399,22 @@ function originAllowed(origin) {
     return false;
   }
 }
+var UPDATE_HINT = "Run `npx @ttsalpha/mirra init` to install both halves from the same version, then run the plugin again in Figma.";
 var OPEN_PLUGIN_HINT = "Open the file in Figma Desktop, then Plugins -> Development -> Mirra, and keep the panel open.";
 var PluginBridge = class {
   #servers = [];
   #socket = null;
   #hello = null;
+  #protocolMismatch = null;
   #port = null;
   #pending = /* @__PURE__ */ new Map();
   get status() {
     return { port: this.#port, connected: this.#socket !== null, hello: this.#hello };
   }
+  /** Set while a connected plugin speaks a protocol this server does not. */
+  get protocolMismatch() {
+    return this.#protocolMismatch;
+  }
   async listen(preferredPort2) {
     const first = preferredPort2 ?? DEFAULT_PORT;
     const last = preferredPort2 ?? PORT_RANGE_END;
@@ -41265,11 +41457,14 @@ var PluginBridge = class {
     this.#servers = [];
     this.#port = null;
   }
-  async request(op, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  async request(op, params, timeoutMs = TIMEOUT_MS[op] ?? DEFAULT_TIMEOUT_MS) {
     const socket = this.#socket;
     if (!socket) {
       throw new MirraError("No Figma plugin is connected", "plugin_offline", OPEN_PLUGIN_HINT);
     }
+    if (this.#protocolMismatch && op !== "ping") {
+      throw new MirraError(this.#protocolMismatch, "protocol_mismatch", UPDATE_HINT);
+    }
     const id = randomUUID();
     const envelope = { id, op, params };
     return new Promise((resolve4, reject) => {
@@ -41313,11 +41508,8 @@ var PluginBridge = class {
     if ("type" in data) {
       if (data.type === "log") return log(`[plugin:${data.level}] ${data.message}`);
       this.#hello = data;
-      if (data.protocolVersion !== PROTOCOL_VERSION) {
-        log(
-          `protocol mismatch: plugin speaks v${data.protocolVersion}, server speaks v${PROTOCOL_VERSION}. Rebuild and re-import the plugin.`
-        );
-      }
+      this.#protocolMismatch = data.protocolVersion === PROTOCOL_VERSION ? null : `The plugin speaks protocol v${data.protocolVersion}, this server speaks v${PROTOCOL_VERSION}`;
+      if (this.#protocolMismatch) log(this.#protocolMismatch);
       return log(`plugin connected: ${data.fileName} (plugin v${data.pluginVersion})`);
     }
     const pending = this.#pending.get(data.id);
@@ -41377,7 +41569,7 @@ var USAGE = `mirra <command>
   doctor   Bind the plugin port and wait for the Figma plugin to connect
 
 Flags:
-  --no-reveal   init: do not open the folder in Finder
+  --no-reveal   init: do not open the folder in Finder on a manual import
   --no-config   init: do not touch any client's configuration
 
 Environment:
@@ -41433,14 +41625,26 @@ async function init() {
     }
     lines.push("", "A client that was already running has to be restarted to see the tools.", "");
   }
-  lines.push(
-    "Then, in Figma Desktop:",
-    "  1. Plugins -> Development -> Import plugin from manifest...",
-    `     and choose ${manifest}`,
-    "  2. Open a file, run Mirra, and leave the panel open",
-    "  3. Ask the agent for mirra_ping; the panel badge should turn green"
-  );
-  if (!process.argv.includes("--no-reveal")) reveal(manifest);
+  const figma = await registerPluginWithFigma(PLUGIN_HOME);
+  const manual = figma.status === "skipped";
+  if (manual) {
+    lines.push(
+      `Could not register the plugin with Figma Desktop: ${figma.reason}`,
+      "Then, in Figma Desktop:",
+      "  1. Plugins -> Development -> Import plugin from manifest...",
+      `     and choose ${manifest}`,
+      "  2. Open a file, run Mirra, and leave the panel open",
+      "  3. Ask the agent for mirra_ping; the panel badge should turn green"
+    );
+  } else {
+    lines.push(
+      figma.status === "registered" ? "Registered the plugin with Figma Desktop." : "Figma Desktop already knows the plugin.",
+      "Then, in Figma Desktop:",
+      "  1. Open a file, run Plugins -> Development -> Mirra, and leave the panel open",
+      "  2. Ask the agent for mirra_ping; the panel badge should turn green"
+    );
+  }
+  if (manual && !process.argv.includes("--no-reveal")) reveal(manifest);
   console.log(lines.join("\n"));
 }
 async function doctor() {

package/dist/plugin/main.js

@@ -949,30 +949,39 @@
     return node;
   }
 
+  // src/version.ts
+  var PLUGIN_VERSION = "1.3.0";
+
   // src/ops/ping.ts
   function ping() {
     return {
       fileName: figma.root.name,
       fileKey: readFileKey(),
       currentPage: figma.currentPage.name,
-      selectionCount: figma.currentPage.selection.length
+      selectionCount: figma.currentPage.selection.length,
+      pluginVersion: PLUGIN_VERSION
     };
   }
 
   // src/figma/read.ts
-  function readNode(node, depth, names = EMPTY_NAMES) {
-    const skipped = { count: 0 };
-    const tree = toSpec(node, depth, skipped, names);
-    return { tree, skipped: skipped.count };
-  }
-  function toSpec(node, depth, skipped, names) {
+  function readNode(node, depth, names = EMPTY_NAMES, limit = Number.MAX_SAFE_INTEGER) {
+    const budget = { count: 0, left: limit };
+    const tree = toSpec(node, depth, budget, names);
+    return { tree, skipped: budget.count };
+  }
+  function toSpec(node, depth, budget, names) {
+    if (budget.left <= 0) {
+      budget.count += 1;
+      return null;
+    }
+    budget.left -= 1;
     const svg = node.getPluginData(SVG_FIELD);
     if (svg) return { type: "svg", ...common(node), src: svg };
     const src = node.getPluginData(SRC_FIELD);
     if (src) return { type: "image", ...common(node), ...painted(node, names), src };
     switch (node.type) {
       case "FRAME":
-        return frameSpec(node, depth, skipped, names);
+        return frameSpec(node, depth, budget, names);
       case "TEXT":
         return textSpec(node, names);
       case "RECTANGLE":
@@ -982,19 +991,19 @@
       case "INSTANCE":
         return instanceSpec(node);
       default:
-        skipped.count += 1;
+        budget.count += 1;
         return null;
     }
   }
-  function frameSpec(node, depth, skipped, names) {
+  function frameSpec(node, depth, budget, names) {
     const children = [];
     if (depth > 0) {
       for (const child of node.children) {
-        const spec = toSpec(child, depth - 1, skipped, names);
+        const spec = toSpec(child, depth - 1, budget, names);
         if (spec) children.push(spec);
       }
     } else if (node.children.length) {
-      skipped.count += node.children.length;
+      budget.count += node.children.length;
     }
     return {
       type: "frame",
@@ -1151,6 +1160,7 @@
 
   // src/ops/read.ts
   var DEFAULT_DEPTH = 6;
+  var DEFAULT_LIMIT2 = 200;
   async function read(params) {
     const targets = params.nodeId ? [await resolve(params.nodeId)] : [...figma.currentPage.selection];
     if (!targets.length) {
@@ -1160,10 +1170,14 @@
     const nodes = [];
     let skipped = 0;
     for (const target of targets) {
-      const outcome = readNode(target, params.depth ?? DEFAULT_DEPTH, names);
+      const outcome = readNode(
+        target,
+        params.depth ?? DEFAULT_DEPTH,
+        names,
+        params.limit ?? DEFAULT_LIMIT2
+      );
       skipped += outcome.skipped;
       if (outcome.tree) nodes.push({ id: target.id, tree: outcome.tree });
-      else skipped += 1;
     }
     return { nodes, skipped };
   }
@@ -1211,21 +1225,29 @@
   }
 
   // src/ops/screenshot.ts
+  var DEFAULT_MAX_EDGE = 1200;
+  function fittingScale(wanted, box, maxEdge) {
+    const longest = Math.max(box.width, box.height) * wanted;
+    if (longest <= maxEdge) return wanted;
+    return Math.max(0.01, wanted * maxEdge / longest);
+  }
   async function screenshot(params) {
     const node = params.target ? await new NodeIndex().resolve(params.target) : figma.currentPage.selection[0];
     if (!node) {
       throw new Error("Nothing is selected: select a layer in Figma, or pass a target");
     }
+    const box = node;
+    const scale = fittingScale(params.scale ?? 1, box, params.maxEdge ?? DEFAULT_MAX_EDGE);
     const bytes = await node.exportAsync({
       format: "PNG",
-      constraint: { type: "SCALE", value: params.scale ?? 1 }
+      constraint: { type: "SCALE", value: scale }
     });
-    const box = node;
     return {
       id: node.id,
       name: node.name,
-      width: Math.round(box.width),
-      height: Math.round(box.height),
+      width: Math.round(box.width * scale),
+      height: Math.round(box.height * scale),
+      scale,
       png: figma.base64Encode(bytes)
     };
   }
@@ -1269,7 +1291,6 @@
   }
 
   // src/main.ts
-  var PLUGIN_VERSION = "1.1.0";
   figma.showUI(__html__, { width: 300, height: 300, themeColors: true });
   var queue = Promise.resolve();
   figma.ui.onmessage = (message2) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsalpha/mirra",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Two-way MCP server for Figma: read a design and render one back through the Figma Plugin API",
   "keywords": [
     "figma",