faux-studio 0.4.7 → 0.5.1

package/README.md

@@ -14,10 +14,17 @@ On first run, a browser window opens for Figma OAuth. After authentication, the
 
 ### Claude Code
 
+```bash
+claude mcp add --scope user faux-studio -- npx faux-studio@latest
+```
+
+Or manually add to your MCP settings:
+
 ```json
 {
   "mcpServers": {
     "faux-studio": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "faux-studio"]
     }
@@ -25,21 +32,38 @@ On first run, a browser window opens for Figma OAuth. After authentication, the
 }
 ```
 
-### Cursor / Windsurf
+### OpenCode
 
-Add to your MCP settings:
+manually add to your MCP settings (~/.config/opencode/opencode.json):
 
 ```json
 {
-  "mcpServers": {
+  "mcp": {
     "faux-studio": {
-      "command": "npx",
-      "args": ["-y", "faux-studio"]
+      "type": "local",
+      "command": [
+        "npx",
+        "faux-studio@latest"
+      ]
     }
   }
 }
 ```
 
+### Codex
+
+```bash
+codex mcp add faux-studio -- npx -y faux-studio@latest
+```
+
+Or manually add to your MCP settings (~/.codex/config.toml):
+
+```yml
+[mcp_servers.faux-studio]
+command = "npx"
+args = ["-y", "faux-studio@latest"]
+```
+
 ## How It Works
 
 faux-studio runs locally and bridges your AI client to Figma Desktop:
@@ -58,7 +82,6 @@ faux-studio runs locally and bridges your AI client to Figma Desktop:
 
 | Variable | Description |
 |----------|-------------|
-| `FAUX_API_KEY` | Skip OAuth — use an API key instead |
 | `FAUX_TRANSPORT` | Force transport: `cdp` or `plugin` |
 
 ## Links

package/dist/index.js

@@ -10563,17 +10563,72 @@ var SecurityCliKeychainStore = class {
     }
   }
 };
+var KeyringCredentialStore = class {
+  name = "keychain";
+  entry;
+  cached = void 0;
+  constructor(entry) {
+    this.entry = entry;
+  }
+  async load() {
+    if (this.cached !== void 0) return this.cached;
+    try {
+      const raw = await this.entry.getPassword();
+      if (!raw) {
+        this.cached = null;
+        return null;
+      }
+      const creds = JSON.parse(raw);
+      if (!creds.jwt || !creds.refreshToken || !creds.user) {
+        this.cached = null;
+        return null;
+      }
+      this.cached = creds;
+      return creds;
+    } catch {
+      this.cached = null;
+      return null;
+    }
+  }
+  async save(creds) {
+    try {
+      await this.entry.setPassword(JSON.stringify(creds));
+      this.cached = creds;
+    } catch (err) {
+      warn(`Could not save to keychain: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  async clear() {
+    try {
+      await this.entry.deletePassword();
+      this.cached = null;
+    } catch {
+    }
+  }
+};
 async function tryCreateKeychainStore() {
-  if (process.platform !== "darwin") {
-    log("[keychain] not macOS \u2014 skipping keychain");
-    return null;
+  if (process.platform === "darwin") {
+    try {
+      log("[keychain] probing macOS security CLI...");
+      const t0 = Date.now();
+      await securityExec("help");
+      log(`[keychain] security CLI available (${Date.now() - t0}ms)`);
+      return new SecurityCliKeychainStore();
+    } catch (err) {
+      warn(
+        `OS keychain not available, using file-based credential storage: ${err instanceof Error ? err.message : err}`
+      );
+      return null;
+    }
   }
   try {
-    log("[keychain] probing macOS security CLI...");
+    log("[keychain] importing @napi-rs/keyring...");
     const t0 = Date.now();
-    await securityExec("help");
-    log(`[keychain] security CLI available (${Date.now() - t0}ms)`);
-    return new SecurityCliKeychainStore();
+    const { AsyncEntry } = await import("@napi-rs/keyring");
+    const entry = new AsyncEntry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+    await entry.getPassword();
+    log(`[keychain] keyring available (${Date.now() - t0}ms)`);
+    return new KeyringCredentialStore(entry);
   } catch (err) {
     warn(
       `OS keychain not available, using file-based credential storage: ${err instanceof Error ? err.message : err}`
@@ -10602,7 +10657,7 @@ async function initStore() {
     const fileCreds = await fileStore.load();
     if (fileCreds) {
       await keychainStore.save(fileCreds);
-      keychainStore["cached"] = void 0;
+      keychainStore.cached = void 0;
       const verified = await keychainStore.load();
       if (verified) {
         await fileStore.clear();
@@ -10626,24 +10681,33 @@ function isExpiringSoon(creds) {
   const expiresAt = new Date(creds.expiresAt).getTime();
   return Date.now() > expiresAt - REFRESH_BUFFER_MS;
 }
+var inflightRefresh = null;
 async function refreshJwt(creds) {
-  const res = await fetch(`${AUTH_BASE}/auth/refresh`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ refreshToken: creds.refreshToken })
-  });
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(`Token refresh failed (HTTP ${res.status})${text ? ": " + text : ""}`);
+  if (inflightRefresh) {
+    return inflightRefresh;
   }
-  const data = await res.json();
-  return {
-    jwt: data.jwt,
-    refreshToken: data.refreshToken,
-    expiresAt: new Date(Date.now() + data.expiresIn * 1e3).toISOString(),
-    user: creds.user
-    // Refresh endpoint doesn't return user info — keep existing
+  const doRefresh = async () => {
+    const res = await fetch(`${AUTH_BASE}/auth/refresh`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refreshToken: creds.refreshToken })
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new Error(`Token refresh failed (HTTP ${res.status})${text ? ": " + text : ""}`);
+    }
+    const data = await res.json();
+    return {
+      jwt: data.jwt,
+      refreshToken: data.refreshToken,
+      expiresAt: new Date(Date.now() + data.expiresIn * 1e3).toISOString(),
+      user: creds.user
+    };
   };
+  inflightRefresh = doRefresh().finally(() => {
+    inflightRefresh = null;
+  });
+  return inflightRefresh;
 }
 function openBrowser(url2) {
   let child;
@@ -10919,6 +10983,124 @@ async function generateScript(jwt2, toolName, params) {
   return { script: data.script, signature: data.signature };
 }
 
+// src/icons.ts
+function parseIconName(iconName) {
+  if (iconName.includes(":")) {
+    const [prefix, name] = iconName.split(":");
+    return { prefix, name };
+  }
+  const parts = iconName.split("-");
+  if (parts.length > 1) {
+    return { prefix: parts[0], name: parts.slice(1).join("-") };
+  }
+  return { prefix: "lucide", name: iconName };
+}
+async function fetchIconSvg(iconName, size = 24) {
+  const { prefix, name } = parseIconName(iconName);
+  const url2 = `https://api.iconify.design/${prefix}/${name}.svg?width=${size}&height=${size}`;
+  const response = await fetch(url2);
+  if (!response.ok) {
+    if (response.status === 404) throw new Error(`Icon not found: ${iconName}`);
+    throw new Error(`Failed to fetch icon: HTTP ${response.status}`);
+  }
+  return await response.text();
+}
+function detectIconType(svgContent) {
+  if (svgContent.includes('stroke="currentColor"') || svgContent.includes("stroke='currentColor'")) {
+    return "stroke";
+  }
+  if (svgContent.includes('opacity="0.') || svgContent.includes("opacity='0.")) {
+    return "duotone";
+  }
+  return "fill";
+}
+async function searchSingleQuery(query, limit, prefix, category) {
+  let url2 = `https://api.iconify.design/search?query=${encodeURIComponent(query)}&limit=${limit}`;
+  if (prefix) url2 += `&prefix=${encodeURIComponent(prefix)}`;
+  if (category) url2 += `&category=${encodeURIComponent(category)}`;
+  const response = await fetch(url2);
+  if (!response.ok) {
+    if (response.status === 404) throw new Error("Icon search is currently disabled");
+    throw new Error(`Search failed: HTTP ${response.status}`);
+  }
+  const data = await response.json();
+  const icons = data.icons || [];
+  return { query, total: icons.length, icons };
+}
+async function searchIcons(params) {
+  const { limit = 3, prefix, category } = params;
+  const effectiveLimit = Math.min(limit, 100);
+  if (params.queries && params.queries.length > 0) {
+    const results = await Promise.all(
+      params.queries.map((q) => searchSingleQuery(q.trim(), effectiveLimit, prefix, category))
+    );
+    return { results, totalQueries: results.length };
+  }
+  const query = params.query;
+  if (!query || query.trim().length === 0) {
+    throw new Error("Search query is required (provide `query` or `queries`)");
+  }
+  return searchSingleQuery(query.trim(), effectiveLimit, prefix, category);
+}
+async function resolveIconsInNode(node) {
+  if (node.$icon && typeof node.$icon === "string") {
+    const searchTerm = node.$icon;
+    const size = typeof node.size === "number" ? node.size : 24;
+    try {
+      const searchResult = await searchIcons({ query: searchTerm, limit: 1 });
+      if (searchResult.icons.length === 0) {
+        warn(`No icons found for: ${searchTerm}`);
+        const { $icon: $icon2, ...rest2 } = node;
+        return { ...rest2, $iconError: `No icons found for: ${searchTerm}` };
+      }
+      const iconName = searchResult.icons[0];
+      const svgContent = await fetchIconSvg(iconName, size);
+      const iconType = detectIconType(svgContent);
+      const { $icon, ...rest } = node;
+      return {
+        ...rest,
+        $iconResolved: { svgContent, iconType, iconName, searchTerm }
+      };
+    } catch (error3) {
+      error(`Failed to resolve icon "${searchTerm}": ${error3 instanceof Error ? error3.message : String(error3)}`);
+      const { $icon, ...rest } = node;
+      return { ...rest, $iconError: `Failed to load icon: ${error3 instanceof Error ? error3.message : "Unknown error"}` };
+    }
+  }
+  let result = { ...node };
+  if (node.children && Array.isArray(node.children)) {
+    result.children = await Promise.all(
+      node.children.map(async (child) => {
+        if (child && typeof child === "object") {
+          return resolveIconsInNode(child);
+        }
+        return child;
+      })
+    );
+  }
+  if (node.template && typeof node.template === "object") {
+    result.template = await resolveIconsInNode(node.template);
+  }
+  return result;
+}
+var ICON_TOOLS = /* @__PURE__ */ new Set(["create_from_schema", "modify_via_schema"]);
+async function preprocessIconsInParams(toolName, params) {
+  if (!ICON_TOOLS.has(toolName)) return params;
+  const result = { ...params };
+  if (result.schema && typeof result.schema === "object") {
+    result.schema = await resolveIconsInNode(result.schema);
+  }
+  if (result.modifications && Array.isArray(result.modifications)) {
+    result.modifications = await Promise.all(
+      result.modifications.map(async (mod) => ({
+        ...mod,
+        schema: await resolveIconsInNode(mod.schema)
+      }))
+    );
+  }
+  return result;
+}
+
 // node_modules/ws/wrapper.mjs
 var import_stream = __toESM(require_stream(), 1);
 var import_receiver = __toESM(require_receiver(), 1);
@@ -11396,7 +11578,7 @@ var PORT_RANGE = 8;
 var SCRIPT_TIMEOUT_MS = 6e4;
 var CONNECT_WAIT_MS = 3e4;
 var FAUX_DIR3 = join4(homedir3(), ".faux");
-var PluginWsServer = class {
+var PluginWsServer = class _PluginWsServer {
   name = "plugin-ws";
   wss = null;
   connections = /* @__PURE__ */ new Map();
@@ -11404,6 +11586,17 @@ var PluginWsServer = class {
   connectWaiters = [];
   _activeFileId = null;
   _port = 0;
+  // File tracking state (mirrors CdpFileTracker API)
+  _lastAcknowledgedFileId = null;
+  _lastAcknowledgedFileName = null;
+  _lastAcknowledgedAt = 0;
+  _lastFocusEventAt = 0;
+  /** How long before focus events are considered stale for high-confidence detection. */
+  static FOCUS_FRESH_MS = 12e4;
+  // 2 minutes
+  /** How long before last-known file is considered stale and untrusted (matches CDP). */
+  static LAST_KNOWN_STALE_MS = 5 * 6e4;
+  // 5 minutes
   // -------------------------------------------------------------------------
   // Public Getters
   // -------------------------------------------------------------------------
@@ -11422,6 +11615,79 @@ var PluginWsServer = class {
   get hasConnections() {
     return this.connections.size > 0;
   }
+  get activeFileName() {
+    if (!this._activeFileId) return null;
+    return this.connections.get(this._activeFileId)?.fileName ?? null;
+  }
+  get lastAcknowledgedFileName() {
+    return this._lastAcknowledgedFileName;
+  }
+  // -------------------------------------------------------------------------
+  // File Tracking
+  // -------------------------------------------------------------------------
+  /**
+   * Detect the active file for the plugin transport.
+   * Unlike CDP (which introspects shell.html), this is synchronous — the
+   * plugin tells us via file-focus events. The cacheTtlMs parameter is
+   * accepted for API compatibility but detection is always in-memory.
+   */
+  detectActiveFile(_cacheTtlMs = 2e3) {
+    const allFiles = this.getAllFileInfos();
+    if (this.connections.size === 0) {
+      return { activeFile: null, allFiles, method: "none", confidence: "none" };
+    }
+    if (this.connections.size === 1) {
+      const conn = this.connections.values().next().value;
+      return { activeFile: this.connToFileInfo(conn), allFiles, method: "single-file", confidence: "high" };
+    }
+    if (this._activeFileId && this.connections.has(this._activeFileId)) {
+      const conn = this.connections.get(this._activeFileId);
+      const info = this.connToFileInfo(conn);
+      const focusAge = Date.now() - this._lastFocusEventAt;
+      if (this._lastFocusEventAt > 0 && focusAge < _PluginWsServer.FOCUS_FRESH_MS) {
+        return { activeFile: info, allFiles, method: "focus-event", confidence: "high" };
+      }
+      if (this.isLastKnownStale()) {
+        log("File tracker: focus and acknowledgment both stale \u2014 cannot detect active file");
+        return { activeFile: null, allFiles, method: "none", confidence: "none" };
+      }
+      return { activeFile: info, allFiles, method: "last-known", confidence: "low" };
+    }
+    return { activeFile: null, allFiles, method: "none", confidence: "none" };
+  }
+  /** Whether the active file has changed since the last acknowledged execution. */
+  hasFileChanged() {
+    return this._activeFileId !== null && this._lastAcknowledgedFileId !== null && this._activeFileId !== this._lastAcknowledgedFileId;
+  }
+  /**
+   * Acknowledge the current active file as the intended target.
+   * Call AFTER successful script execution.
+   */
+  acknowledgeActiveFile() {
+    if (this._activeFileId) {
+      this._lastAcknowledgedFileId = this._activeFileId;
+      this._lastAcknowledgedFileName = this.connections.get(this._activeFileId)?.fileName ?? null;
+      this._lastAcknowledgedAt = Date.now();
+    }
+  }
+  /** True if the last acknowledged execution was more than 5 minutes ago. */
+  isLastKnownStale() {
+    if (this._lastAcknowledgedAt === 0) return false;
+    return Date.now() - this._lastAcknowledgedAt > _PluginWsServer.LAST_KNOWN_STALE_MS;
+  }
+  /** All connected files as FigmaFileInfo[]. */
+  getAllFileInfos() {
+    return Array.from(this.connections.values()).map((c) => this.connToFileInfo(c));
+  }
+  /** Build FigmaFileInfo from a PluginConnection. */
+  connToFileInfo(conn) {
+    return {
+      fileKey: conn.fileId,
+      fileName: conn.fileName,
+      targetId: conn.fileId,
+      wsUrl: ""
+    };
+  }
   // -------------------------------------------------------------------------
   // Server Lifecycle
   // -------------------------------------------------------------------------
@@ -11516,6 +11782,7 @@ var PluginWsServer = class {
         this.connections.set(fileId, { ws, fileId, fileName, connectedAt: Date.now() });
         if (this.connections.size === 1 || !this._activeFileId) {
           this._activeFileId = fileId;
+          this._lastFocusEventAt = Date.now();
         }
         log(`Plugin connected: "${fileName}" (${fileId}) [${this.connections.size} file(s)]`);
         for (const waiter of this.connectWaiters) {
@@ -11576,6 +11843,7 @@ var PluginWsServer = class {
         const focusFileId = msg.fileId || fileId;
         if (this.connections.has(focusFileId)) {
           this._activeFileId = focusFileId;
+          this._lastFocusEventAt = Date.now();
         }
         break;
       }
@@ -25988,10 +26256,10 @@ var RESOURCES = [
 var INSTRUCTIONS = `You are connected to Figma Desktop via faux-studio. You can create, modify, and inspect designs using the tools below.
 
 ## Transport
-faux-studio connects to Figma Desktop via **CDP (Chrome DevTools Protocol)** by default \u2014 no plugin needed. It launches Figma with a debug port and communicates directly. If the Figma plugin is installed and running, it can also connect via plugin WebSocket as a fallback. CDP is the preferred zero-setup transport.
+faux-studio connects to Figma Desktop via the **faux-studio plugin** by default \u2014 install and run the plugin from Figma's Plugins menu. The plugin communicates via local WebSocket with real-time file focus tracking. If the plugin is not available, faux-studio falls back to CDP (Chrome DevTools Protocol) which requires launching Figma with a debug port. The plugin is the preferred transport.
 
 ## Workflow
-1. Call \`setup_figma\` first to ensure Figma is running and connected (via CDP or plugin).
+1. Call \`setup_figma\` first to ensure Figma is running and connected (via plugin or CDP).
 2. Call \`get_page_structure\` or \`get_screenshot\` to understand what's on the canvas.
 3. Use \`create_from_schema\` for all creation \u2014 it accepts declarative JSON schemas.
 4. Use \`modify_via_schema\` to change existing nodes.
@@ -26031,7 +26299,7 @@ Resources provide quick read-only access to Figma state without tool calls:
 - Create components for reusable UI patterns.`;
 function createMcpServer(deps) {
   const server2 = new Server(
-    { name: "faux-studio", version: "0.4.7" },
+    { name: "faux-studio", version: "0.5.1" },
     {
       capabilities: { tools: { listChanged: true }, resources: {}, logging: {} },
       instructions: INSTRUCTIONS
@@ -26046,7 +26314,7 @@ function createMcpServer(deps) {
       },
       {
         name: "setup_figma",
-        description: "Ensure Figma Desktop is running and connected via CDP (preferred) or plugin WebSocket. Call this before any design work. Launches Figma with CDP debug port if needed, detects open files and the active tab. Returns connection status, transport mode, active file, and list of all open design files. Idempotent \u2014 safe to call multiple times.",
+        description: "Ensure Figma Desktop is running and connected via plugin WebSocket (preferred) or CDP (fallback). Call this before any design work. Detects open files and the active tab. Returns connection status, transport mode, active file, and list of all open design files. Idempotent \u2014 safe to call multiple times.",
         inputSchema: {
           type: "object",
           properties: {},
@@ -26133,6 +26401,13 @@ function createMcpServer(deps) {
           throw err;
         }
       }
+      if (name === "search_icons") {
+        log("search_icons called (server-side)");
+        const result2 = await searchIcons(params);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result2, null, 2) }]
+        };
+      }
       const intents = {
         meso: typeof params._intent_meso === "string" ? params._intent_meso : void 0,
         macro: typeof params._intent_macro === "string" ? params._intent_macro : void 0
@@ -26296,6 +26571,24 @@ async function tryConnectCdp() {
   }
 }
 async function executeScript(script, intents, opts) {
+  if (forceTransport !== "cdp" && pluginServer.hasConnections) {
+    const detection = pluginServer.detectActiveFile(opts?.cacheTtlMs);
+    if (!detection.activeFile && detection.allFiles.length > 1) {
+      throw new FileUnknownError(detection.allFiles);
+    }
+    if (pluginServer.hasFileChanged()) {
+      throw new FileChangedError(
+        pluginServer.lastAcknowledgedFileName,
+        pluginServer.activeFileName,
+        pluginServer.activeFileId,
+        detection.allFiles
+      );
+    }
+    log(`Executing via plugin (file: ${pluginServer.activeFileId || "active"})`);
+    const result = await pluginServer.executeScript(script, void 0, intents);
+    pluginServer.acknowledgeActiveFile();
+    return result;
+  }
   if (forceTransport !== "plugin") {
     const client = await tryConnectCdp();
     if (client) {
@@ -26332,10 +26625,6 @@ async function executeScript(script, intents, opts) {
       }
     }
   }
-  if (forceTransport !== "cdp" && pluginServer.hasConnections) {
-    log(`Executing via plugin (file: ${pluginServer.activeFileId || "active"})`);
-    return pluginServer.executeScript(script, void 0, intents);
-  }
   log("No transport available, waiting for plugin...");
   return pluginServer.executeScript(script, void 0, intents);
 }
@@ -26361,6 +26650,7 @@ async function recoverCdp(client, script) {
 async function generateWithAuth(toolName, params) {
   await lazyInit();
   auth = await refreshIfNeeded(auth);
+  params = await preprocessIconsInParams(toolName, params);
   let result;
   try {
     result = await generateScript(auth.jwt, toolName, params);
@@ -26398,16 +26688,23 @@ async function waitForPlugin() {
   return false;
 }
 function pluginReadyResult() {
+  const detection = pluginServer.detectActiveFile();
+  const activeName = detection.activeFile?.fileName;
+  const fileCount = detection.allFiles.length;
   return {
     status: "ready",
     transport: "plugin",
-    message: `Connected via plugin.${pluginServer.activeFileId ? ` Active file: ${pluginServer.activeFileId}` : ""} Ready to design.`,
-    activeFile: pluginServer.activeFileId || void 0,
+    message: `Connected via plugin.${activeName ? ` Active file: "${activeName}".` : ""} ${fileCount} file(s) open. Ready to design.`,
+    activeFile: activeName || void 0,
     pluginFiles: pluginServer.connectedFiles,
+    openFiles: detection.allFiles.map((f) => ({ fileKey: f.fileKey, fileName: f.fileName })),
     port: pluginServer.port
   };
 }
 async function setupFigma(params) {
+  if (forceTransport !== "cdp" && pluginServer.hasConnections) {
+    return pluginReadyResult();
+  }
   if (forceTransport !== "plugin" && cdpClient?.connected && cdpClient.hasContext) {
     if (fileTracker) {
       const detection = await fileTracker.detectActiveFile();
@@ -26425,40 +26722,6 @@ async function setupFigma(params) {
       message: "Connected via CDP. Ready to design."
     };
   }
-  if (forceTransport !== "cdp" && pluginServer.hasConnections) {
-    return pluginReadyResult();
-  }
-  if (forceTransport !== "plugin") {
-    const existing = await probeCdpPorts();
-    if (existing) {
-      const target = findFigmaDesignTarget(existing.targets);
-      if (target) {
-        try {
-          cdpClient?.close();
-          cdpClient = null;
-          const client = new CdpClient();
-          await client.connect(target.webSocketDebuggerUrl);
-          await client.discoverFigmaContext();
-          cdpClient = client;
-          log(`CDP connected: ${target.title}`);
-          if (!fileTracker) {
-            fileTracker = new CdpFileTracker(existing.port);
-          }
-          const detection = await fileTracker.detectActiveFile();
-          fileTracker.acknowledgeActiveFile();
-          return {
-            status: "ready",
-            transport: "cdp",
-            message: `Connected via CDP. Active file: "${detection.activeFile?.fileName ?? target.title}". ${detection.allFiles.length} file(s) open. Ready to design.`,
-            activeFile: detection.activeFile?.fileName ?? target.title,
-            openFiles: detection.allFiles.map((f) => ({ fileKey: f.fileKey, fileName: f.fileName })),
-            port: existing.port
-          };
-        } catch {
-        }
-      }
-    }
-  }
   if (!findFigmaPath()) {
     return {
       status: "not_installed",
@@ -26467,17 +26730,7 @@ async function setupFigma(params) {
     };
   }
   if (!isFigmaRunning()) {
-    if (forceTransport === "plugin") {
-      try {
-        launchFigma();
-      } catch (err) {
-        return {
-          status: "not_installed",
-          transport: "none",
-          message: err instanceof Error ? err.message : "Failed to launch Figma."
-        };
-      }
-    } else {
+    if (forceTransport === "cdp") {
       try {
         const connection = await launchFigmaWithCdp();
         const target = findFigmaDesignTarget(connection.targets);
@@ -26514,33 +26767,58 @@ async function setupFigma(params) {
           message: err instanceof Error ? err.message : "Failed to launch Figma."
         };
       }
+    } else {
+      try {
+        launchFigma();
+      } catch (err) {
+        return {
+          status: "not_installed",
+          transport: "none",
+          message: err instanceof Error ? err.message : "Failed to launch Figma."
+        };
+      }
     }
   }
-  if (forceTransport !== "plugin") {
-    return {
-      status: "waiting_for_plugin",
-      transport: "none",
-      message: `Figma is running but the CDP debug port is not enabled.
-
-To fix this:
-  1. Quit Figma completely (Cmd+Q / Alt+F4)
-  2. Call setup_figma again \u2014 it will relaunch Figma with CDP enabled
-
-Alternatively, install the faux-studio plugin:
-  1. Download: ${PLUGIN_URL}
-  2. In Figma: Plugins \u2192 Development \u2192 Import plugin from manifest
-  3. Run: Plugins \u2192 Development \u2192 faux-studio
-  4. Call setup_figma again once the plugin shows "Ready".`,
-      port: pluginServer.port
-    };
+  if (forceTransport !== "cdp") {
+    log("Waiting for plugin connection...");
+    const connected = await waitForPlugin();
+    if (connected) {
+      return {
+        ...pluginReadyResult(),
+        status: isFigmaRunning() ? "ready" : "launched"
+      };
+    }
   }
-  log("Waiting for plugin connection...");
-  const connected = await waitForPlugin();
-  if (connected) {
-    return {
-      ...pluginReadyResult(),
-      status: isFigmaRunning() ? "ready" : "launched"
-    };
+  if (forceTransport !== "plugin") {
+    const existing = await probeCdpPorts();
+    if (existing) {
+      const target = findFigmaDesignTarget(existing.targets);
+      if (target) {
+        try {
+          cdpClient?.close();
+          cdpClient = null;
+          const client = new CdpClient();
+          await client.connect(target.webSocketDebuggerUrl);
+          await client.discoverFigmaContext();
+          cdpClient = client;
+          log(`CDP connected: ${target.title}`);
+          if (!fileTracker) {
+            fileTracker = new CdpFileTracker(existing.port);
+          }
+          const detection = await fileTracker.detectActiveFile();
+          fileTracker.acknowledgeActiveFile();
+          return {
+            status: "ready",
+            transport: "cdp",
+            message: `Connected via CDP. Active file: "${detection.activeFile?.fileName ?? target.title}". ${detection.allFiles.length} file(s) open. Ready to design.`,
+            activeFile: detection.activeFile?.fileName ?? target.title,
+            openFiles: detection.allFiles.map((f) => ({ fileKey: f.fileKey, fileName: f.fileName })),
+            port: existing.port
+          };
+        } catch {
+        }
+      }
+    }
   }
   return {
     status: "waiting_for_plugin",
@@ -26561,7 +26839,7 @@ Call setup_figma again once the plugin shows "Ready".`,
 }
 async function main() {
   const startupT0 = Date.now();
-  log(`faux-studio v${"0.4.7"} \u2014 process started (PID ${process.pid}, PPID ${process.ppid})`);
+  log(`faux-studio v${"0.5.1"} \u2014 process started (PID ${process.pid}, PPID ${process.ppid})`);
   try {
     const port = await pluginServer.start();
     if (forceTransport === "plugin") {
@@ -26569,7 +26847,7 @@ async function main() {
     } else if (forceTransport === "cdp") {
       log(`Transport: CDP-only mode (FAUX_TRANSPORT=cdp) \u2014 plugin WS on port ${port} (standby)`);
     } else {
-      log(`Transport: auto \u2014 CDP preferred, plugin WS on port ${port} (fallback)`);
+      log(`Transport: auto \u2014 plugin preferred (port ${port}), CDP fallback`);
     }
   } catch (err) {
     warn(`Plugin WS server failed to start: ${err instanceof Error ? err.message : err}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faux-studio",
-  "version": "0.4.7",
+  "version": "0.5.1",
   "description": "AI-powered Figma design via MCP — connect any AI client to Figma Desktop",
   "type": "module",
   "bin": {
@@ -48,5 +48,8 @@
     "darwin",
     "linux",
     "win32"
-  ]
+  ],
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.2.0"
+  }
 }