faux-studio 0.4.5 → 0.5.0

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

@@ -10447,6 +10447,7 @@ function error(message) {
 
 // src/credential-store.ts
 import { readFile, writeFile, mkdir, unlink } from "fs/promises";
+import { execFile } from "child_process";
 import { join } from "path";
 import { homedir } from "os";
 var FAUX_DIR = join(homedir(), ".faux");
@@ -10480,7 +10481,89 @@ var FileCredentialStore = class {
     }
   }
 };
-var KeychainCredentialStore = class {
+function securityExec(...args) {
+  return new Promise((resolve, reject) => {
+    execFile("/usr/bin/security", args, { timeout: 1e4 }, (err, stdout, stderr) => {
+      if (err) return reject(err);
+      resolve({ stdout, stderr });
+    });
+  });
+}
+var SecurityCliKeychainStore = class {
+  name = "keychain";
+  cached = void 0;
+  async load() {
+    if (this.cached !== void 0) return this.cached;
+    try {
+      const { stdout } = await securityExec(
+        "find-generic-password",
+        "-s",
+        KEYCHAIN_SERVICE,
+        "-a",
+        KEYCHAIN_ACCOUNT,
+        "-w"
+      );
+      const raw = stdout.trim();
+      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) {
+    const value = JSON.stringify(creds);
+    try {
+      await securityExec(
+        "delete-generic-password",
+        "-s",
+        KEYCHAIN_SERVICE,
+        "-a",
+        KEYCHAIN_ACCOUNT
+      );
+    } catch {
+    }
+    try {
+      await securityExec(
+        "add-generic-password",
+        "-s",
+        KEYCHAIN_SERVICE,
+        "-a",
+        KEYCHAIN_ACCOUNT,
+        "-w",
+        value,
+        "-A",
+        "-U"
+      );
+      this.cached = creds;
+    } catch (err) {
+      warn(`Could not save to keychain: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  async clear() {
+    try {
+      await securityExec(
+        "delete-generic-password",
+        "-s",
+        KEYCHAIN_SERVICE,
+        "-a",
+        KEYCHAIN_ACCOUNT
+      );
+      this.cached = null;
+    } catch {
+    }
+  }
+};
+var KeyringCredentialStore = class {
   name = "keychain";
   entry;
   cached = void 0;
@@ -10524,11 +10607,28 @@ var KeychainCredentialStore = class {
   }
 };
 async function tryCreateKeychainStore() {
+  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] importing @napi-rs/keyring...");
+    const t0 = Date.now();
     const { AsyncEntry } = await import("@napi-rs/keyring");
     const entry = new AsyncEntry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
     await entry.getPassword();
-    return new KeychainCredentialStore(entry);
+    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}`
@@ -10544,9 +10644,12 @@ function createCredentialStore() {
   return initPromise;
 }
 async function initStore() {
+  log("[credential-store] initializing...");
+  const t0 = Date.now();
   const fileStore = new FileCredentialStore();
   const keychainStore = await tryCreateKeychainStore();
   if (!keychainStore) {
+    log(`[credential-store] using file store (${Date.now() - t0}ms)`);
     return fileStore;
   }
   const keychainCreds = await keychainStore.load();
@@ -10554,6 +10657,7 @@ async function initStore() {
     const fileCreds = await fileStore.load();
     if (fileCreds) {
       await keychainStore.save(fileCreds);
+      keychainStore.cached = void 0;
       const verified = await keychainStore.load();
       if (verified) {
         await fileStore.clear();
@@ -10564,6 +10668,7 @@ async function initStore() {
       }
     }
   }
+  log(`[credential-store] using keychain store (${Date.now() - t0}ms)`);
   return keychainStore;
 }
 
@@ -10660,6 +10765,8 @@ async function authenticate() {
   );
 }
 async function ensureAuth() {
+  log("[auth] ensureAuth() started");
+  const t0 = Date.now();
   const apiKey = process.env.FAUX_API_KEY;
   if (apiKey) {
     log("Using FAUX_API_KEY from environment");
@@ -10670,7 +10777,9 @@ async function ensureAuth() {
       source: "api-key"
     };
   }
+  log("[auth] creating credential store...");
   const credStore = await createCredentialStore();
+  log(`[auth] credential store ready (${credStore.name}) in ${Date.now() - t0}ms`);
   const saved = await credStore.load();
   if (saved) {
     if (!isExpiringSoon(saved)) {
@@ -10865,6 +10974,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);
@@ -11227,6 +11454,31 @@ async function probeCdpPorts() {
   }
   return null;
 }
+async function launchFigmaWithCdp() {
+  const figmaPath = findFigmaPath();
+  if (!figmaPath) {
+    throw new Error(
+      "Figma Desktop is not installed. Download from https://figma.com/downloads"
+    );
+  }
+  const port = await findAvailablePort();
+  log(`Launching Figma Desktop (port ${port})...`);
+  launchFigmaProcess(figmaPath, port);
+  const startTime = Date.now();
+  while (Date.now() - startTime < CDP_WAIT_TIMEOUT_MS) {
+    await new Promise((r) => setTimeout(r, CDP_POLL_INTERVAL_MS));
+    const { alive, isFigma } = await isCdpAlive(port);
+    if (alive && isFigma) {
+      await new Promise((r) => setTimeout(r, 2e3));
+      const targets = await listTargets(port);
+      log("Figma Desktop started");
+      return { port, targets };
+    }
+  }
+  throw new Error(
+    `Figma did not respond on port ${port} within ${CDP_WAIT_TIMEOUT_MS / 1e3}s. Try again.`
+  );
+}
 function launchFigmaProcess(figmaPath, port) {
   if (process.platform === "darwin") {
     const binary = `${figmaPath}/Contents/MacOS/Figma`;
@@ -11317,7 +11569,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();
@@ -11325,6 +11577,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
   // -------------------------------------------------------------------------
@@ -11343,6 +11606,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
   // -------------------------------------------------------------------------
@@ -11437,6 +11773,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) {
@@ -11497,6 +11834,7 @@ var PluginWsServer = class {
         const focusFileId = msg.fileId || fileId;
         if (this.connections.has(focusFileId)) {
           this._activeFileId = focusFileId;
+          this._lastFocusEventAt = Date.now();
         }
         break;
       }
@@ -25908,8 +26246,11 @@ 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 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.
+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.
@@ -25949,7 +26290,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.5" },
+    { name: "faux-studio", version: "0.5.0" },
     {
       capabilities: { tools: { listChanged: true }, resources: {}, logging: {} },
       instructions: INSTRUCTIONS
@@ -25964,7 +26305,7 @@ function createMcpServer(deps) {
       },
       {
         name: "setup_figma",
-        description: "Ensure Figma Desktop is running and connected. Call this before any design work. Launches Figma if needed, detects open files and the active tab, and provides setup guidance. Returns connection status, 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: {},
@@ -26051,6 +26392,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
@@ -26178,13 +26526,19 @@ function lazyInit() {
   return initPromise2;
 }
 async function doInit() {
+  log("[init] lazyInit triggered \u2014 starting auth + tool fetch");
+  const t0 = Date.now();
   auth = await ensureAuth();
+  log(`[init] auth complete in ${Date.now() - t0}ms`);
   try {
+    const t1 = Date.now();
     tools = await getTools(auth.jwt);
+    log(`[init] tools fetched (${tools.length}) in ${Date.now() - t1}ms`);
   } catch (err) {
     error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
+  log(`[init] full initialization complete in ${Date.now() - t0}ms`);
 }
 async function tryConnectCdp() {
   try {
@@ -26209,8 +26563,22 @@ 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"})`);
-    return pluginServer.executeScript(script, void 0, intents);
+    const result = await pluginServer.executeScript(script, void 0, intents);
+    pluginServer.acknowledgeActiveFile();
+    return result;
   }
   if (forceTransport !== "plugin") {
     const client = await tryConnectCdp();
@@ -26273,6 +26641,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);
@@ -26310,17 +26679,21 @@ 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 (pluginServer.hasConnections) {
+  if (forceTransport !== "cdp" && pluginServer.hasConnections) {
     return pluginReadyResult();
   }
   if (forceTransport !== "plugin" && cdpClient?.connected && cdpClient.hasContext) {
@@ -26340,6 +26713,73 @@ async function setupFigma(params) {
       message: "Connected via CDP. Ready to design."
     };
   }
+  if (!findFigmaPath()) {
+    return {
+      status: "not_installed",
+      transport: "none",
+      message: "Figma Desktop is not installed.\n\n1. Download Figma: https://figma.com/downloads\n2. Install and open it\n3. Call setup_figma again"
+    };
+  }
+  if (!isFigmaRunning()) {
+    if (forceTransport === "cdp") {
+      try {
+        const connection = await launchFigmaWithCdp();
+        const target = findFigmaDesignTarget(connection.targets);
+        if (target) {
+          const client = new CdpClient();
+          await client.connect(target.webSocketDebuggerUrl);
+          await client.discoverFigmaContext();
+          cdpClient = client;
+          log(`CDP connected after launch: ${target.title}`);
+          if (!fileTracker) {
+            fileTracker = new CdpFileTracker(connection.port);
+          }
+          const detection = await fileTracker.detectActiveFile();
+          fileTracker.acknowledgeActiveFile();
+          return {
+            status: "launched",
+            transport: "cdp",
+            message: `Launched Figma and 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: connection.port
+          };
+        }
+        return {
+          status: "launched",
+          transport: "cdp",
+          message: "Launched Figma with CDP enabled but no design file is open.\n\nOpen or create a design file in Figma, then call setup_figma again.",
+          port: connection.port
+        };
+      } catch (err) {
+        return {
+          status: "not_installed",
+          transport: "none",
+          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 !== "cdp") {
+    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) {
@@ -26371,37 +26811,6 @@ async function setupFigma(params) {
       }
     }
   }
-  if (!findFigmaPath()) {
-    return {
-      status: "not_installed",
-      transport: "none",
-      message: `Figma Desktop is not installed.
-
-1. Download Figma: https://figma.com/downloads
-2. Install and open it
-3. Install the faux-studio plugin: ${PLUGIN_URL}
-4. Call setup_figma again`
-    };
-  }
-  if (!isFigmaRunning()) {
-    try {
-      launchFigma();
-    } catch (err) {
-      return {
-        status: "not_installed",
-        transport: "none",
-        message: err instanceof Error ? err.message : "Failed to launch Figma."
-      };
-    }
-  }
-  log("Waiting for plugin connection...");
-  const connected = await waitForPlugin();
-  if (connected) {
-    return {
-      ...pluginReadyResult(),
-      status: isFigmaRunning() ? "ready" : "launched"
-    };
-  }
   return {
     status: "waiting_for_plugin",
     transport: "none",
@@ -26420,7 +26829,8 @@ Call setup_figma again once the plugin shows "Ready".`,
   };
 }
 async function main() {
-  log(`faux-studio v${"0.4.5"}`);
+  const startupT0 = Date.now();
+  log(`faux-studio v${"0.5.0"} \u2014 process started (PID ${process.pid}, PPID ${process.ppid})`);
   try {
     const port = await pluginServer.start();
     if (forceTransport === "plugin") {
@@ -26428,7 +26838,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 plugin WS on port ${port}, CDP on-demand`);
+      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}`);
@@ -26472,6 +26882,7 @@ async function main() {
   });
   await startServer(server2);
   setServer(server2);
+  log(`[startup] MCP server ready in ${Date.now() - startupT0}ms \u2014 handshake complete`);
   if (forceTransport !== "plugin") {
     try {
       await tryConnectCdp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faux-studio",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "AI-powered Figma design via MCP — connect any AI client to Figma Desktop",
   "type": "module",
   "bin": {
@@ -44,6 +44,11 @@
     "url": "https://github.com/uxfreak/faux-studio.git"
   },
   "homepage": "https://faux.design",
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
   "optionalDependencies": {
     "@napi-rs/keyring": "^1.2.0"
   }