faux-studio 0.3.12 → 0.4.1

package/README.md

@@ -67,6 +67,27 @@ faux-studio runs locally and bridges your AI client to Figma Desktop:
 - Setup guide: [faux.design/docs/setup](https://faux.design/docs/setup)
 - Issues: [github.com/uxfreak/faux-studio/issues](https://github.com/uxfreak/faux-studio/issues)
 
+## Publishing a New Version
+
+To publish a new version to npm:
+
+1. Bump the version in `package.json`:
+   ```bash
+   npm version patch   # 0.4.0 → 0.4.1
+   npm version minor   # 0.4.0 → 0.5.0
+   npm version major   # 0.4.0 → 1.0.0
+   ```
+   This updates `package.json` and creates a git commit + tag automatically.
+
+2. Push the commit and tag:
+   ```bash
+   git push && git push --tags
+   ```
+
+3. The [publish workflow](.github/workflows/publish.yml) will build and publish to npm automatically on any `v*` tag push.
+
+> **Note:** Ensure the `NPM_TOKEN` secret is configured in the repo's GitHub Settings → Secrets and variables → Actions.
+
 ## License
 
 MIT

package/dist/index.js

@@ -10414,9 +10414,6 @@ var require_dist = __commonJS({
 });
 
 // src/auth.ts
-import { readFile, writeFile, mkdir } from "fs/promises";
-import { join } from "path";
-import { homedir } from "os";
 import { spawn } from "child_process";
 
 // src/logger.ts
@@ -10448,31 +10445,129 @@ function error(message) {
   send("error", message);
 }
 
-// src/auth.ts
+// src/credential-store.ts
+import { readFile, writeFile, mkdir, unlink } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
 var FAUX_DIR = join(homedir(), ".faux");
 var CREDENTIALS_PATH = join(FAUX_DIR, "credentials.json");
-var AUTH_BASE = "https://auth.faux.design";
-var POLL_INTERVAL_MS = 2e3;
-var POLL_TIMEOUT_MS = 5 * 60 * 1e3;
-var REFRESH_BUFFER_MS = 5 * 60 * 1e3;
-async function loadCredentials() {
+var KEYCHAIN_SERVICE = "faux-studio";
+var KEYCHAIN_ACCOUNT = "credentials";
+var FileCredentialStore = class {
+  name = "file";
+  async load() {
+    try {
+      const raw = await readFile(CREDENTIALS_PATH, "utf-8");
+      const creds = JSON.parse(raw);
+      if (!creds.jwt || !creds.refreshToken || !creds.user) return null;
+      return creds;
+    } catch {
+      return null;
+    }
+  }
+  async save(creds) {
+    try {
+      await mkdir(FAUX_DIR, { recursive: true });
+      await writeFile(CREDENTIALS_PATH, JSON.stringify(creds, null, 2), { mode: 384 });
+    } catch (err) {
+      warn(`Could not save credentials: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  async clear() {
+    try {
+      await unlink(CREDENTIALS_PATH);
+    } catch {
+    }
+  }
+};
+var KeychainCredentialStore = class {
+  name = "keychain";
+  entry;
+  constructor(entry) {
+    this.entry = entry;
+  }
+  async load() {
+    try {
+      const raw = await this.entry.getPassword();
+      if (!raw) return null;
+      const creds = JSON.parse(raw);
+      if (!creds.jwt || !creds.refreshToken || !creds.user) return null;
+      return creds;
+    } catch {
+      return null;
+    }
+  }
+  async save(creds) {
+    try {
+      await this.entry.setPassword(JSON.stringify(creds));
+    } catch (err) {
+      warn(`Could not save to keychain: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  async clear() {
+    try {
+      await this.entry.deletePassword();
+    } catch {
+    }
+  }
+};
+async function tryCreateKeychainStore() {
   try {
-    const raw = await readFile(CREDENTIALS_PATH, "utf-8");
-    const creds = JSON.parse(raw);
-    if (!creds.jwt || !creds.refreshToken || !creds.user) return null;
-    return creds;
-  } catch {
+    const { AsyncEntry } = await import("@napi-rs/keyring");
+    const probe = new AsyncEntry(KEYCHAIN_SERVICE, "__probe__");
+    await probe.setPassword("probe");
+    try {
+      const val = await probe.getPassword();
+      if (val !== "probe") throw new Error("Keychain probe read-back mismatch");
+    } finally {
+      await probe.deletePassword().catch(() => {
+      });
+    }
+    const entry = new AsyncEntry(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+    return new KeychainCredentialStore(entry);
+  } catch (err) {
+    warn(
+      `OS keychain not available, using file-based credential storage: ${err instanceof Error ? err.message : err}`
+    );
     return null;
   }
 }
-async function saveCredentials(creds) {
-  try {
-    await mkdir(FAUX_DIR, { recursive: true });
-    await writeFile(CREDENTIALS_PATH, JSON.stringify(creds, null, 2), { mode: 384 });
-  } catch (err) {
-    warn(`Could not save credentials: ${err instanceof Error ? err.message : err}`);
+var initPromise = null;
+function createCredentialStore() {
+  if (!initPromise) {
+    initPromise = initStore();
+  }
+  return initPromise;
+}
+async function initStore() {
+  const fileStore = new FileCredentialStore();
+  const keychainStore = await tryCreateKeychainStore();
+  if (!keychainStore) {
+    return fileStore;
+  }
+  const keychainCreds = await keychainStore.load();
+  if (!keychainCreds) {
+    const fileCreds = await fileStore.load();
+    if (fileCreds) {
+      await keychainStore.save(fileCreds);
+      const verified = await keychainStore.load();
+      if (verified) {
+        await fileStore.clear();
+        log("Credentials migrated to OS keychain");
+      } else {
+        warn("Keychain migration could not be verified \u2014 keeping file-based credentials");
+        return fileStore;
+      }
+    }
   }
+  return keychainStore;
 }
+
+// src/auth.ts
+var AUTH_BASE = process.env.FAUX_AUTH_URL || "https://auth.faux.design";
+var POLL_INTERVAL_MS = 2e3;
+var POLL_TIMEOUT_MS = 5 * 60 * 1e3;
+var REFRESH_BUFFER_MS = 5 * 60 * 1e3;
 function isExpiringSoon(creds) {
   const expiresAt = new Date(creds.expiresAt).getTime();
   return Date.now() > expiresAt - REFRESH_BUFFER_MS;
@@ -10543,7 +10638,7 @@ async function authenticate() {
           expiresAt: new Date(Date.now() + 3600 * 1e3).toISOString(),
           user: data.user
         };
-        await saveCredentials(creds);
+        await (await createCredentialStore()).save(creds);
         return creds;
       }
       if (data.status === "error") {
@@ -10570,7 +10665,8 @@ async function ensureAuth() {
       source: "api-key"
     };
   }
-  const saved = await loadCredentials();
+  const credStore = await createCredentialStore();
+  const saved = await credStore.load();
   if (saved) {
     if (!isExpiringSoon(saved)) {
       log(`Authenticated as ${saved.user.handle}`);
@@ -10584,7 +10680,7 @@ async function ensureAuth() {
     try {
       log("Refreshing authentication...");
       const refreshed = await refreshJwt(saved);
-      await saveCredentials(refreshed);
+      await credStore.save(refreshed);
       log(`Authenticated as ${refreshed.user.handle}`);
       return {
         jwt: refreshed.jwt,
@@ -10607,12 +10703,13 @@ async function ensureAuth() {
 }
 async function refreshIfNeeded(current, force = false) {
   if (current.source === "api-key") return current;
-  const saved = await loadCredentials();
+  const credStore = await createCredentialStore();
+  const saved = await credStore.load();
   if (!saved) return current;
   if (!force && !isExpiringSoon(saved)) return current;
   try {
     const refreshed = await refreshJwt(saved);
-    await saveCredentials(refreshed);
+    await credStore.save(refreshed);
     return {
       jwt: refreshed.jwt,
       refreshToken: refreshed.refreshToken,
@@ -10628,9 +10725,34 @@ async function refreshIfNeeded(current, force = false) {
 import { readFile as readFile2, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
 import { join as join2 } from "path";
 import { homedir as homedir2 } from "os";
+import { subtle } from "crypto";
 var FAUX_DIR2 = join2(homedir2(), ".faux");
 var CACHE_PATH = join2(FAUX_DIR2, "tool-cache.json");
-var API_BASE = "https://mcp.faux.design";
+var API_BASE = process.env.FAUX_API_URL || "https://api.faux.design";
+var _publicKey = null;
+var _cachedVerifyKey = null;
+var _cachedKeyInput = null;
+function getVerifyKey() {
+  return _publicKey;
+}
+async function importPublicKey(jwkJson) {
+  if (_cachedVerifyKey && _cachedKeyInput === jwkJson) return _cachedVerifyKey;
+  const jwk = JSON.parse(jwkJson);
+  _cachedVerifyKey = await subtle.importKey("jwk", jwk, { name: "Ed25519" }, false, ["verify"]);
+  _cachedKeyInput = jwkJson;
+  return _cachedVerifyKey;
+}
+async function verifyScriptSignature(script, signature, keyJwk) {
+  if (signature.length !== 128) return false;
+  try {
+    const key = await importPublicKey(keyJwk);
+    const sigBytes = Uint8Array.from(signature.match(/.{2}/g).map((h) => parseInt(h, 16)));
+    const scriptBytes = new TextEncoder().encode(script);
+    return await subtle.verify("Ed25519", key, sigBytes, scriptBytes);
+  } catch {
+    return false;
+  }
+}
 async function loadCachedTools() {
   try {
     const raw = await readFile2(CACHE_PATH, "utf-8");
@@ -10679,6 +10801,9 @@ async function fetchRemoteTools(jwt2) {
     throw new Error(`Failed to fetch tools (HTTP ${res.status})`);
   }
   const data = await res.json();
+  if (data.signingKey) {
+    _publicKey = data.signingKey;
+  }
   return sanitizeTools(data.tools);
 }
 async function getTools(jwt2) {
@@ -10732,7 +10857,7 @@ async function generateScript(jwt2, toolName, params) {
     throw new Error(body.error || `Script generation failed (HTTP ${res.status})`);
   }
   const data = await res.json();
-  return data.script;
+  return { script: data.script, signature: data.signature };
 }
 
 // node_modules/ws/wrapper.mjs
@@ -10756,10 +10881,12 @@ var CdpClient = class {
   pending = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
   figmaContextId = null;
+  _targetWsUrl = null;
   // -------------------------------------------------------------------------
   // Connection
   // -------------------------------------------------------------------------
   async connect(wsUrl) {
+    this._targetWsUrl = wsUrl;
     return new Promise((resolve, reject) => {
       const ws = new wrapper_default(wsUrl);
       const timeout = setTimeout(() => {
@@ -10865,7 +10992,7 @@ var CdpClient = class {
     this.on("Runtime.executionContextCreated", handler);
     try {
       await this.send("Runtime.enable");
-      await new Promise((r) => setTimeout(r, 500));
+      await new Promise((r) => setTimeout(r, 150));
     } finally {
       this.off("Runtime.executionContextCreated", handler);
     }
@@ -10928,6 +11055,15 @@ ${script}
 })()`);
   }
   // -------------------------------------------------------------------------
+  // Reconnection
+  // -------------------------------------------------------------------------
+  /** Close current connection and reconnect to a different CDP target. */
+  async reconnectToTarget(wsUrl) {
+    this.close();
+    await this.connect(wsUrl);
+    await this.discoverFigmaContext();
+  }
+  // -------------------------------------------------------------------------
   // State
   // -------------------------------------------------------------------------
   get connected() {
@@ -10936,6 +11072,10 @@ ${script}
   get hasContext() {
     return this.figmaContextId !== null;
   }
+  /** The WebSocket URL this client is currently connected to. */
+  get targetWsUrl() {
+    return this._targetWsUrl;
+  }
   resetContext() {
     this.figmaContextId = null;
   }
@@ -10946,6 +11086,7 @@ ${script}
     this.ws?.close();
     this.ws = null;
     this.figmaContextId = null;
+    this._targetWsUrl = null;
   }
 };
 
@@ -11057,10 +11198,20 @@ async function listTargets(port) {
   if (!res.ok) throw new Error(`Failed to list CDP targets (HTTP ${res.status})`);
   return await res.json();
 }
-var FIGMA_DESIGN_URL_RE = /figma\.com\/(file|design)\//;
+var FIGMA_DESIGN_URL_RE = /figma\.com\/(file|design)\/([a-zA-Z0-9]+)/;
 function findFigmaDesignTarget(targets) {
   return targets.find((t) => t.type === "page" && FIGMA_DESIGN_URL_RE.test(t.url)) || targets.find((t) => t.type === "page") || null;
 }
+function findShellTarget(targets) {
+  return targets.find((t) => t.type === "page" && t.url?.includes("shell.html")) || null;
+}
+function listDesignTargets(targets) {
+  return targets.filter((t) => t.type === "page" && FIGMA_DESIGN_URL_RE.test(t.url)).map((t) => {
+    const fileKey = t.url.match(FIGMA_DESIGN_URL_RE)[2];
+    const fileName = t.title.replace(/\s[–—-]\s*Figma\s*$/u, "").trim();
+    return { ...t, fileKey, fileName };
+  });
+}
 async function probeCdpPorts() {
   for (const port of KNOWN_CDP_PORTS) {
     const { alive, isFigma } = await isCdpAlive(port);
@@ -11438,6 +11589,229 @@ var PluginWsServer = class {
   }
 };
 
+// src/file-tracker.ts
+var FileChangedError = class extends Error {
+  previousFileName;
+  currentFileName;
+  currentFileKey;
+  allFiles;
+  constructor(previousFileName, currentFileName, currentFileKey, allFiles) {
+    super(`Active Figma file changed from "${previousFileName}" to "${currentFileName}".`);
+    this.name = "FileChangedError";
+    this.previousFileName = previousFileName;
+    this.currentFileName = currentFileName;
+    this.currentFileKey = currentFileKey;
+    this.allFiles = allFiles;
+  }
+};
+var FileUnknownError = class extends Error {
+  allFiles;
+  constructor(allFiles) {
+    super("Cannot detect which Figma file is active. Please confirm the target file.");
+    this.name = "FileUnknownError";
+    this.allFiles = allFiles;
+  }
+};
+var LAST_KNOWN_STALE_MS = 5 * 6e4;
+var SHELL_DETECT_TIMEOUT_MS = 500;
+var CdpFileTracker = class {
+  cdpPort;
+  shellWsUrl = null;
+  _activeFileKey = null;
+  _lastKnownFileKey = null;
+  _lastKnownFileName = null;
+  _lastAcknowledgedAt = 0;
+  _files = /* @__PURE__ */ new Map();
+  _lastDetectTime = 0;
+  _cachedResult = null;
+  constructor(cdpPort) {
+    this.cdpPort = cdpPort;
+  }
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+  /**
+   * Detect the currently active file. Uses cached result if fresh.
+   * @param cacheTtlMs How long to trust cached results (0 = always re-detect).
+   */
+  async detectActiveFile(cacheTtlMs = 2e3) {
+    if (this._cachedResult && cacheTtlMs > 0 && Date.now() - this._lastDetectTime < cacheTtlMs) {
+      return this._cachedResult;
+    }
+    const result = await this.detect();
+    this._cachedResult = result;
+    this._lastDetectTime = Date.now();
+    if (result.activeFile) {
+      this._activeFileKey = result.activeFile.fileKey;
+    }
+    return result;
+  }
+  /** List all open design files from /json/list. */
+  async listOpenFiles() {
+    try {
+      const targets = await listTargets(this.cdpPort);
+      return this.parseDesignTargets(targets);
+    } catch {
+      return Array.from(this._files.values());
+    }
+  }
+  /** Get cached file info by fileKey. */
+  getFileTarget(fileKey) {
+    return this._files.get(fileKey) || null;
+  }
+  /** Whether the detected active file differs from the last acknowledged file. */
+  hasFileChanged() {
+    return this._activeFileKey !== null && this._lastKnownFileKey !== null && this._activeFileKey !== this._lastKnownFileKey;
+  }
+  /**
+   * Acknowledge the current active file as the intended target.
+   * Call AFTER successful execution (AR-3).
+   */
+  acknowledgeActiveFile() {
+    if (this._activeFileKey) {
+      this._lastKnownFileKey = this._activeFileKey;
+      this._lastKnownFileName = this._files.get(this._activeFileKey)?.fileName ?? null;
+      this._lastAcknowledgedAt = Date.now();
+    }
+  }
+  get activeFileKey() {
+    return this._activeFileKey;
+  }
+  get lastKnownFileKey() {
+    return this._lastKnownFileKey;
+  }
+  get lastKnownFileName() {
+    return this._lastKnownFileName;
+  }
+  get activeFileName() {
+    return this._activeFileKey ? this._files.get(this._activeFileKey)?.fileName ?? null : null;
+  }
+  // -------------------------------------------------------------------------
+  // Private: Core Detection
+  // -------------------------------------------------------------------------
+  async detect() {
+    let targets;
+    try {
+      targets = await listTargets(this.cdpPort);
+      if (!Array.isArray(targets)) targets = [];
+    } catch {
+      return this.fallbackToLastKnown([]);
+    }
+    const designFiles = this.parseDesignTargets(targets);
+    this._files.clear();
+    for (const f of designFiles) {
+      this._files.set(f.fileKey, f);
+    }
+    if (designFiles.length === 0) {
+      return { activeFile: null, allFiles: [], method: "none", confidence: "none" };
+    }
+    if (designFiles.length === 1) {
+      this._activeFileKey = designFiles[0].fileKey;
+      return { activeFile: designFiles[0], allFiles: designFiles, method: "single-file", confidence: "high" };
+    }
+    const shellTabName = await this.detectViaShellTabBar(targets);
+    if (shellTabName) {
+      const matched = this.matchTabNameToFile(shellTabName, designFiles);
+      if (matched) {
+        this._activeFileKey = matched.fileKey;
+        log(`File tracker: active file "${matched.fileName}" (${matched.fileKey}) via shell tab bar`);
+        return { activeFile: matched, allFiles: designFiles, method: "shell-tab-bar", confidence: "high" };
+      }
+    }
+    return this.fallbackToLastKnown(designFiles);
+  }
+  // -------------------------------------------------------------------------
+  // Private: Shell.html Tab Bar Detection (PRIMARY)
+  // -------------------------------------------------------------------------
+  /**
+   * Read the active tab name from Figma's shell.html tab bar.
+   * Security: uses a fixed literal expression — never interpolate user input (SR-1).
+   */
+  async detectViaShellTabBar(targets) {
+    if (!this.shellWsUrl) {
+      const shell = findShellTarget(targets);
+      if (!shell?.webSocketDebuggerUrl) return null;
+      if (!shell.webSocketDebuggerUrl.startsWith("ws://127.0.0.1:")) return null;
+      this.shellWsUrl = shell.webSocketDebuggerUrl;
+    }
+    const client = new CdpClient();
+    try {
+      const connectPromise = client.connect(this.shellWsUrl);
+      const timeoutPromise = new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("shell detect timeout")), SHELL_DETECT_TIMEOUT_MS)
+      );
+      await Promise.race([connectPromise, timeoutPromise]);
+      const result = await client.send("Runtime.evaluate", {
+        expression: `document.querySelector('[role="tab"][aria-selected="true"]')?.getAttribute('aria-label')`,
+        returnByValue: true
+      });
+      const raw = result?.result?.value;
+      return this.parseTabNameFromCdpResult(raw);
+    } catch {
+      this.shellWsUrl = null;
+      return null;
+    } finally {
+      client.close();
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Private: Fallback — Last Known
+  // -------------------------------------------------------------------------
+  fallbackToLastKnown(designFiles) {
+    if (this._lastKnownFileKey && !this.isLastKnownStale()) {
+      const existing = designFiles.find((f) => f.fileKey === this._lastKnownFileKey);
+      if (existing) {
+        this._activeFileKey = existing.fileKey;
+        log(`File tracker: using last-known file "${existing.fileName}" (low confidence)`);
+        return { activeFile: existing, allFiles: designFiles, method: "last-known", confidence: "low" };
+      }
+    }
+    log("File tracker: cannot detect active file \u2014 shell detection failed and last-known is stale or missing");
+    return { activeFile: null, allFiles: designFiles, method: "none", confidence: "none" };
+  }
+  /** True if the last acknowledged execution was more than 5 minutes ago. */
+  isLastKnownStale() {
+    if (this._lastAcknowledgedAt === 0) return false;
+    return Date.now() - this._lastAcknowledgedAt > LAST_KNOWN_STALE_MS;
+  }
+  // -------------------------------------------------------------------------
+  // Private: Matching & Validation
+  // -------------------------------------------------------------------------
+  /**
+   * Match a tab name from shell.html against design file targets.
+   * Returns null if ambiguous (multiple files with same name) — AR-9.
+   */
+  matchTabNameToFile(tabName, designFiles) {
+    const matches = designFiles.filter((f) => f.fileName === tabName);
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1) {
+      warn(`File tracker: ${matches.length} files named "${tabName}" \u2014 cannot disambiguate`);
+      return null;
+    }
+    return null;
+  }
+  /**
+   * Validate and clean the CDP result from shell.html evaluation (SR-3).
+   * Rejects non-string, empty, oversized, or control-character values.
+   */
+  parseTabNameFromCdpResult(raw) {
+    if (typeof raw !== "string") return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0 || trimmed.length > 512) return null;
+    if (/[\x00-\x1f\x7f]/.test(trimmed)) return null;
+    return trimmed;
+  }
+  /** Parse design targets from /json/list into FigmaFileInfo[]. */
+  parseDesignTargets(targets) {
+    return listDesignTargets(targets).map((t) => ({
+      fileKey: t.fileKey,
+      fileName: t.fileName,
+      targetId: t.id,
+      wsUrl: t.webSocketDebuggerUrl
+    }));
+  }
+};
+
 // node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
@@ -25570,7 +25944,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.3.12" },
+    { name: "faux-studio", version: "0.4.1" },
     {
       capabilities: { tools: { listChanged: true }, resources: {}, logging: {} },
       instructions: INSTRUCTIONS
@@ -25585,7 +25959,7 @@ function createMcpServer(deps) {
       },
       {
         name: "setup_figma",
-        description: "Ensure Figma Desktop is running and the plugin is connected. Call this before any design work. Launches Figma if needed, waits for the plugin to connect, and provides setup guidance. Idempotent \u2014 safe to call multiple times. Returns connection status and active file info.",
+        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.",
         inputSchema: {
           type: "object",
           properties: {},
@@ -25635,11 +26009,13 @@ function createMcpServer(deps) {
               }) }]
             };
           } catch (err) {
+            const transport = deps.getTransport();
+            const restartHint = transport === "cdp" ? "Please disable and re-enable the faux-studio MCP server in your MCP client settings, then try again." : transport === "plugin" ? "Please close and reopen the faux-studio plugin in Figma, then try again." : "Please restart faux-studio and try again.";
             return {
               content: [{ type: "text", text: JSON.stringify({
                 authenticated: false,
                 error: err instanceof Error ? err.message : "Re-authentication failed",
-                message: "Could not authenticate. Please restart faux-studio."
+                message: `Could not authenticate. ${restartHint}`
               }) }],
               isError: true
             };
@@ -25675,7 +26051,10 @@ function createMcpServer(deps) {
         macro: typeof params._intent_macro === "string" ? params._intent_macro : void 0
       };
       const script = await deps.generateScript(name, params);
-      const result = await deps.executeScript(script, intents);
+      const annotation = TOOL_ANNOTATIONS[name];
+      const isReadOnly = annotation?.readOnlyHint === true;
+      const cacheTtlMs = isReadOnly ? 2e3 : 0;
+      const result = await deps.executeScript(script, intents, { cacheTtlMs });
       const imageData = extractImageData(result);
       if (imageData) {
         const content = [
@@ -25691,14 +26070,56 @@ function createMcpServer(deps) {
         content: [{ type: "text", text }]
       };
     } catch (err) {
+      if (err instanceof FileChangedError) {
+        const annotation = TOOL_ANNOTATIONS[name];
+        const isReadOnly = annotation?.readOnlyHint === true;
+        const payload = JSON.stringify({
+          status: "confirmation_required",
+          reason: "ACTIVE_FILE_CHANGED",
+          previousFile: err.previousFileName,
+          currentFile: err.currentFileName,
+          currentFileKey: err.currentFileKey,
+          message: `The active Figma file changed from "${err.previousFileName}" to "${err.currentFileName}". Please confirm which file you want to work on.`,
+          availableFiles: err.allFiles.map((f) => ({ fileKey: f.fileKey, fileName: f.fileName }))
+        }, null, 2);
+        if (isReadOnly) {
+          return { content: [{ type: "text", text: payload }] };
+        }
+        return { content: [{ type: "text", text: payload }], isError: true };
+      }
+      if (err instanceof FileUnknownError) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: "confirmation_required",
+              reason: "ACTIVE_FILE_UNKNOWN",
+              message: "Cannot detect which Figma file is active. Please confirm the target file.",
+              availableFiles: err.allFiles.map((f) => ({ fileKey: f.fileKey, fileName: f.fileName }))
+            }, null, 2)
+          }],
+          isError: true
+        };
+      }
       const message = err instanceof Error ? err.message : String(err);
       const isAuthError = message.includes("auth") || message.includes("401") || message.includes("AUTH_EXPIRED");
+      if (isAuthError) {
+        const transport = deps.getTransport();
+        const reconnectHint = transport === "cdp" ? "If the `login` tool fails, ask the user to disable and re-enable the faux-studio MCP server in their MCP client settings, then try again." : transport === "plugin" ? "If the `login` tool fails, ask the user to close and reopen the faux-studio plugin in Figma, then try again." : "If the `login` tool fails, ask the user to restart faux-studio and try again.";
+        return {
+          content: [{
+            type: "text",
+            text: `Error: ${message}
+
+Run the \`login\` tool to re-authenticate. ${reconnectHint}`
+          }],
+          isError: true
+        };
+      }
       return {
         content: [{
           type: "text",
-          text: isAuthError ? `Error: ${message}
-
-Run the \`login\` tool to re-authenticate.` : `Error: ${message}`
+          text: `Error: ${message}`
         }],
         isError: true
       };
@@ -25740,6 +26161,7 @@ async function startServer(server2) {
 // src/index.ts
 var auth;
 var cdpClient = null;
+var fileTracker = null;
 var pluginServer = new PluginWsServer();
 var forceTransport = process.env.FAUX_TRANSPORT;
 async function tryConnectCdp() {
@@ -25747,20 +26169,23 @@ async function tryConnectCdp() {
     if (cdpClient?.connected && cdpClient.hasContext) return cdpClient;
     cdpClient?.close();
     cdpClient = null;
-    const { targets } = await ensureFigma();
-    const target = findFigmaDesignTarget(targets);
+    const connection = await ensureFigma();
+    const target = findFigmaDesignTarget(connection.targets);
     if (!target) return null;
     const client = new CdpClient();
     await client.connect(target.webSocketDebuggerUrl);
     await client.discoverFigmaContext();
     log(`CDP connected: ${target.title}`);
     cdpClient = client;
+    if (!fileTracker) {
+      fileTracker = new CdpFileTracker(connection.port);
+    }
     return client;
   } catch {
     return null;
   }
 }
-async function executeScript(script, intents) {
+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);
@@ -25768,12 +26193,34 @@ async function executeScript(script, intents) {
   if (forceTransport !== "plugin") {
     const client = await tryConnectCdp();
     if (client) {
+      if (fileTracker) {
+        const detection = await fileTracker.detectActiveFile(opts?.cacheTtlMs);
+        if (!detection.activeFile && detection.allFiles.length > 1) {
+          throw new FileUnknownError(detection.allFiles);
+        }
+        if (fileTracker.hasFileChanged()) {
+          throw new FileChangedError(
+            fileTracker.lastKnownFileName,
+            fileTracker.activeFileName,
+            fileTracker.activeFileKey,
+            detection.allFiles
+          );
+        }
+        if (detection.activeFile && client.targetWsUrl !== detection.activeFile.wsUrl) {
+          log(`Switching CDP target to "${detection.activeFile.fileName}" (${detection.activeFile.fileKey})`);
+          await client.reconnectToTarget(detection.activeFile.wsUrl);
+        }
+      }
       log("Executing via CDP");
       try {
-        return await client.executeScript(script);
+        const result = await client.executeScript(script);
+        fileTracker?.acknowledgeActiveFile();
+        return result;
       } catch (err) {
         if (err instanceof ContextDestroyedError) {
-          return await recoverCdp(client, script);
+          const result = await recoverCdp(client, script);
+          fileTracker?.acknowledgeActiveFile();
+          return result;
         }
         throw err;
       }
@@ -25803,16 +26250,29 @@ async function recoverCdp(client, script) {
 }
 async function generateWithAuth(toolName, params) {
   auth = await refreshIfNeeded(auth);
+  let result;
   try {
-    return await generateScript(auth.jwt, toolName, params);
+    result = await generateScript(auth.jwt, toolName, params);
   } catch (err) {
     if (err instanceof Error && err.message === "AUTH_EXPIRED") {
       warn("JWT expired during request, refreshing...");
       auth = await refreshIfNeeded(auth, true);
-      return await generateScript(auth.jwt, toolName, params);
+      result = await generateScript(auth.jwt, toolName, params);
+    } else {
+      throw err;
     }
-    throw err;
   }
+  const verifyKey = getVerifyKey();
+  if (verifyKey && result.signature) {
+    if (!await verifyScriptSignature(result.script, result.signature, verifyKey)) {
+      throw new Error("Script signature verification failed \u2014 possible tampering");
+    }
+  } else if (verifyKey && !result.signature) {
+    throw new Error("Signing key is configured but response is missing a signature \u2014 possible signature stripping attack");
+  } else if (!verifyKey) {
+    warn("No signing key available \u2014 skipping script signature verification");
+  }
+  return result.script;
 }
 var PLUGIN_URL = "https://faux.design/plugin";
 var PLUGIN_WAIT_MS = 1e4;
@@ -25841,6 +26301,16 @@ async function setupFigma(params) {
     return pluginReadyResult();
   }
   if (forceTransport !== "plugin" && cdpClient?.connected && cdpClient.hasContext) {
+    if (fileTracker) {
+      const detection = await fileTracker.detectActiveFile();
+      return {
+        status: "ready",
+        transport: "cdp",
+        message: `Connected via CDP. Active file: "${detection.activeFile?.fileName ?? "unknown"}". ${detection.allFiles.length} file(s) open. Ready to design.`,
+        activeFile: detection.activeFile?.fileName,
+        openFiles: detection.allFiles.map((f) => ({ fileKey: f.fileKey, fileName: f.fileName }))
+      };
+    }
     return {
       status: "ready",
       transport: "cdp",
@@ -25860,11 +26330,17 @@ async function setupFigma(params) {
           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: ${target.title}. Ready to design.`,
-            activeFile: target.title,
+            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 {
@@ -25978,6 +26454,11 @@ async function main() {
       source: auth.source,
       isApiKey: auth.source === "api-key"
     }),
+    getTransport: () => {
+      if (pluginServer.hasConnections) return "plugin";
+      if (cdpClient?.connected) return "cdp";
+      return "none";
+    },
     setupFigma
   });
   await startServer(server2);
@@ -26000,10 +26481,31 @@ async function main() {
 function shutdown() {
   pluginServer.close();
   cdpClient?.close();
+  fileTracker = null;
   process.exit(0);
 }
 process.on("SIGINT", shutdown);
 process.on("SIGTERM", shutdown);
+var ORPHAN_CHECK_MS = 5e3;
+var originalPpid = process.ppid;
+function isParentAlive() {
+  try {
+    process.kill(originalPpid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+process.stdin.on("end", () => {
+  log("stdin closed \u2014 parent process gone, shutting down");
+  shutdown();
+});
+setInterval(() => {
+  if (!isParentAlive()) {
+    log(`Parent process (PID ${originalPpid}) gone \u2014 shutting down`);
+    shutdown();
+  }
+}, ORPHAN_CHECK_MS).unref();
 main().catch((err) => {
   error(err instanceof Error ? err.message : String(err));
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faux-studio",
-  "version": "0.3.12",
+  "version": "0.4.1",
   "description": "AI-powered Figma design via MCP — connect any AI client to Figma Desktop",
   "type": "module",
   "bin": {
@@ -10,13 +10,15 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "tsup",
+    "build:staging": "tsup --env.FAUX_API_URL https://staging-api.faux.design --env.FAUX_AUTH_URL https://staging-auth.faux.design",
     "build:plugin": "cd plugin && npm run build",
     "build:all": "npm run build && npm run build:plugin",
     "dev": "tsup --watch",
+    "test": "npx tsx --test test/*.test.ts",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
@@ -25,6 +27,7 @@
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.0",
     "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
     "typescript": "^5.8.0"
   },
   "keywords": [
@@ -40,5 +43,8 @@
     "type": "git",
     "url": "https://github.com/uxfreak/faux-studio.git"
   },
-  "homepage": "https://faux.design"
+  "homepage": "https://faux.design",
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.2.0"
+  }
 }