figma-pixel-kit 0.9.0

package/src/cli.js

@@ -0,0 +1,3042 @@
+#!/usr/bin/env node
+import { readFile, writeFile, mkdir, copyFile } from "node:fs/promises";
+import { existsSync, readdirSync, statSync, realpathSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { pathToFileURL } from "node:url";
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { chromium } from "playwright";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+
+const ROOT = process.cwd();
+
+// Figma reference PNGs are exported at this scale. The compare step must capture
+// the implemented app at the same deviceScaleFactor so pixelmatch compares
+// like-for-like. This is persisted into spec.json so compare stays in sync.
+const REFERENCE_SCALE = 2;
+
+async function loadDotEnv() {
+  const envPath = path.join(ROOT, ".env");
+  if (!existsSync(envPath)) return;
+
+  const content = await readFile(envPath, "utf8");
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+
+    const key = trimmed.slice(0, eqIndex).trim();
+    const value = trimmed.slice(eqIndex + 1).trim().replace(/^["']|["']$/g, "");
+    if (!process.env[key]) process.env[key] = value;
+  }
+}
+
+function usage() {
+  console.log(`
+figma-pixel-kit
+
+Main usage:
+  figma-pixel-kit "<figma-node-url>"
+  # If the node contains multiple same-width frames (1440px desktop by default), screens are auto-detected.
+
+One-time setup (pick one auth method):
+  figma-pixel-kit token "figd_xxxxxxxxxxxxxxxxx"   # Personal Access Token (simplest)
+  figma-pixel-kit login                            # OAuth via browser (needs oauth-setup first)
+  figma-pixel-kit doctor                           # verify the active credential against /v1/me
+  figma-pixel-kit init
+
+OAuth (browser sign-in) setup:
+  # 1) Create an app at https://www.figma.com/developers/apps
+  # 2) Add redirect URL exactly: http://localhost:7113/callback
+  figma-pixel-kit oauth-setup <client_id> <client_secret>
+  figma-pixel-kit login            # opens the browser, captures the token automatically
+  figma-pixel-kit logout           # clear stored OAuth tokens
+
+Advanced usage:
+  figma-pixel-kit inspect "<figma-node-url>"
+  figma-pixel-kit analyze "<board-url>" [detection options]
+  figma-pixel-kit implement "<figma-node-url>" [detection options]
+  figma-pixel-kit export "<figma-node-url>" [detection options]
+  figma-pixel-kit compare "<screen-id-or-output-folder>" --url "http://localhost:3000" [compare options]
+
+Examples:
+  figma-pixel-kit "https://www.figma.com/design/FILE_KEY/File-Name?node-id=21886-287699&m=dev"
+  figma-pixel-kit "<board-url>" --mobile
+  figma-pixel-kit compare "file-name-21886-287699" --url "http://localhost:3000" --selector "[data-figma-screen='21886:287699']"
+
+Export/detection options (export / analyze / implement / main):
+  --mobile                       Preset for mobile boards (screen-width 390, tolerance 60, min-height 400).
+  --screen-width <px>            Expected screen frame width. Default: 1440
+  --width-tolerance <px>         Allowed width deviation. Default: 12
+  --min-height <px>              Minimum screen height. Default: 500
+  --max-height <px>              Maximum screen height. Default: 4000
+  --scale <1-4>                  reference.png export scale (stored in spec.json). Default: 2
+
+Compare options:
+  --url <url>                    Required. Local page URL to capture.
+  --selector <css>               Optional. Capture only this element instead of the viewport.
+  --threshold <number>           Pixelmatch threshold. Default: 0.12
+  --max-diff-ratio <number>      Pass/fail ratio. Default: 0.03
+  --wait <ms>                    Wait before screenshot. Default: 1000
+  --wait-until <state>           Playwright nav wait: load | domcontentloaded | networkidle. Default: load
+  --full-page                    Capture full page instead of viewport. Use carefully.
+  --ignore-text                  Mask text regions so font rendering differences don't count (layout/color only).
+  # The app is captured at the reference scale stored in spec.json so pixels match 1:1.
+
+Debug:
+  FIGMA_PIXEL_KIT_DEBUG=1        Print full stack traces on error.
+
+Token lookup order:
+  1. FIGMA_TOKEN environment variable
+  2. .env file in the current project
+  3. ~/.figma-pixel-kit/config.json created by: figma-pixel-kit token "figd_xxx"
+`);
+}
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const item = argv[i];
+    if (!item.startsWith("--")) {
+      args._.push(item);
+      continue;
+    }
+
+    const key = item.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+
+    args[key] = next;
+    i++;
+  }
+  return args;
+}
+
+
+// Figma OAuth2 endpoints/scope. Centralized so they're a one-line fix if Figma changes them.
+// Personal Access Tokens use the X-Figma-Token header; OAuth tokens use Authorization: Bearer.
+const OAUTH_AUTHORIZE_URL = "https://www.figma.com/oauth";
+const OAUTH_TOKEN_URL = "https://api.figma.com/v1/oauth/token";
+const OAUTH_REFRESH_URL = "https://api.figma.com/v1/oauth/refresh";
+const OAUTH_SCOPE = "files:read";
+const OAUTH_PORT = 7113; // redirect_uri must be registered EXACTLY as http://localhost:7113/callback
+const OAUTH_REDIRECT_URI = `http://localhost:${OAUTH_PORT}/callback`;
+
+// The header style depends on which credential resolveFigmaToken() selected this run.
+let CURRENT_AUTH_TYPE = "pat";
+
+function getHomeConfigPath() {
+  return path.join(os.homedir(), ".figma-pixel-kit", "config.json");
+}
+
+async function loadHomeConfig() {
+  const configPath = getHomeConfigPath();
+  if (!existsSync(configPath)) return {};
+  try {
+    return JSON.parse(await readFile(configPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// Merge-and-save so writing a PAT doesn't wipe OAuth creds (and vice versa).
+async function saveHomeConfig(patch) {
+  const configPath = getHomeConfigPath();
+  const current = await loadHomeConfig();
+  const next = { ...current, ...patch };
+  await mkdir(path.dirname(configPath), { recursive: true });
+  await writeFile(configPath, JSON.stringify(next, null, 2), { encoding: "utf8", mode: 0o600 });
+  return next;
+}
+
+async function saveTokenCommand(token) {
+  if (!token || token === true) {
+    throw new Error('Missing token. Example: figma-pixel-kit token "figd_xxxxxxxxx"');
+  }
+  await saveHomeConfig({ FIGMA_TOKEN: token });
+  console.log(`Saved Figma token to ${getHomeConfigPath()}`);
+  console.log('From now on you can run: figma-pixel-kit "<figma-node-url>"');
+}
+
+function resolveOAuthClient(homeConfig) {
+  const clientId = process.env.FIGMA_OAUTH_CLIENT_ID || homeConfig.FIGMA_OAUTH_CLIENT_ID;
+  const clientSecret = process.env.FIGMA_OAUTH_CLIENT_SECRET || homeConfig.FIGMA_OAUTH_CLIENT_SECRET;
+  return clientId && clientSecret ? { clientId, clientSecret } : null;
+}
+
+// Refresh an expiring OAuth access token (Figma access tokens are short-lived; refresh tokens persist).
+async function refreshOAuthToken(oauth, client) {
+  const body = new URLSearchParams({
+    client_id: client.clientId,
+    client_secret: client.clientSecret,
+    refresh_token: oauth.refresh_token
+  });
+  const res = await fetch(OAUTH_REFRESH_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`OAuth refresh failed ${res.status}: ${text}`);
+  const data = JSON.parse(text);
+  const updated = {
+    access_token: data.access_token,
+    refresh_token: data.refresh_token || oauth.refresh_token,
+    expires_at: Date.now() + Number(data.expires_in || 0) * 1000
+  };
+  await saveHomeConfig({ FIGMA_OAUTH: updated });
+  return updated;
+}
+
+// Token lookup order:
+//   1. FIGMA_TOKEN env / .env            (PAT — explicit override always wins)
+//   2. ~/.figma-pixel-kit FIGMA_OAUTH    (OAuth — deliberate `login`, auto-refreshed)
+//   3. ~/.figma-pixel-kit FIGMA_TOKEN    (PAT saved via `token`)
+async function resolveFigmaToken() {
+  await loadDotEnv();
+  if (process.env.FIGMA_TOKEN) {
+    CURRENT_AUTH_TYPE = "pat";
+    return process.env.FIGMA_TOKEN;
+  }
+
+  const homeConfig = await loadHomeConfig();
+
+  if (homeConfig.FIGMA_OAUTH?.access_token) {
+    let oauth = homeConfig.FIGMA_OAUTH;
+    const client = resolveOAuthClient(homeConfig);
+    // Refresh slightly early to avoid mid-run expiry.
+    if (oauth.expires_at && Date.now() >= oauth.expires_at - 60_000 && oauth.refresh_token && client) {
+      try {
+        oauth = await refreshOAuthToken(oauth, client);
+      } catch (e) {
+        console.error(`Warning: OAuth token refresh failed (${e.message.split("\n")[0]}). Re-run: figma-pixel-kit login`);
+      }
+    }
+    CURRENT_AUTH_TYPE = "oauth";
+    return oauth.access_token;
+  }
+
+  if (homeConfig.FIGMA_TOKEN) {
+    CURRENT_AUTH_TYPE = "pat";
+    return homeConfig.FIGMA_TOKEN;
+  }
+
+  return null;
+}
+
+async function doctorCommand() {
+  const token = await resolveFigmaToken();
+
+  if (!token) {
+    throw new Error('No Figma credential found. Run: figma-pixel-kit token "figd_xxxxxxxxx"  (or: figma-pixel-kit login)');
+  }
+
+  console.log(`Auth method: ${CURRENT_AUTH_TYPE === "oauth" ? "OAuth (Bearer)" : "Personal Access Token"}`);
+  console.log("Testing credential with /v1/me ...");
+
+  const me = await figmaFetch("https://api.figma.com/v1/me", token);
+
+  console.log("Figma credential is valid.");
+  if (me.handle) console.log(`Handle: ${me.handle}`);
+  if (me.email) console.log(`Email: ${me.email}`);
+}
+
+function openBrowser(url) {
+  // Best-effort cross-platform "open this URL". Failure is non-fatal (we print the URL too).
+  const cmd = process.platform === "darwin" ? "open"
+    : process.platform === "win32" ? "cmd"
+    : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // ignore — the URL is printed for manual opening
+  }
+}
+
+async function oauthSetupCommand(clientId, clientSecret) {
+  if (!clientId || clientId === true || !clientSecret || clientSecret === true) {
+    throw new Error(
+      "Usage: figma-pixel-kit oauth-setup <client_id> <client_secret>\n" +
+      "Create an app at https://www.figma.com/developers/apps, add redirect URL " +
+      `${OAUTH_REDIRECT_URI} , then run this with its client id/secret.`
+    );
+  }
+  await saveHomeConfig({ FIGMA_OAUTH_CLIENT_ID: clientId, FIGMA_OAUTH_CLIENT_SECRET: clientSecret });
+  console.log(`Saved OAuth client credentials to ${getHomeConfigPath()}`);
+  console.log("Next: figma-pixel-kit login");
+}
+
+async function logoutCommand() {
+  await saveHomeConfig({ FIGMA_OAUTH: undefined });
+  console.log("Cleared stored OAuth tokens. (Client credentials and any PAT are kept.)");
+}
+
+async function exchangeOAuthCode(code, client) {
+  const body = new URLSearchParams({
+    client_id: client.clientId,
+    client_secret: client.clientSecret,
+    redirect_uri: OAUTH_REDIRECT_URI,
+    code,
+    grant_type: "authorization_code"
+  });
+  const res = await fetch(OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`OAuth token exchange failed ${res.status}: ${text}`);
+  return JSON.parse(text);
+}
+
+async function loginCommand() {
+  const homeConfig = await loadHomeConfig();
+  const client = resolveOAuthClient(homeConfig);
+  if (!client) {
+    throw new Error(
+      "No OAuth client configured.\n" +
+      "1. Create an app at https://www.figma.com/developers/apps\n" +
+      `2. Add redirect URL exactly: ${OAUTH_REDIRECT_URI}\n` +
+      "3. Run: figma-pixel-kit oauth-setup <client_id> <client_secret>\n" +
+      "Then: figma-pixel-kit login\n" +
+      '(Or skip OAuth entirely and use: figma-pixel-kit token "figd_xxx")'
+    );
+  }
+
+  const state = randomBytes(16).toString("hex");
+  const authUrl = new URL(OAUTH_AUTHORIZE_URL);
+  authUrl.searchParams.set("client_id", client.clientId);
+  authUrl.searchParams.set("redirect_uri", OAUTH_REDIRECT_URI);
+  authUrl.searchParams.set("scope", OAUTH_SCOPE);
+  authUrl.searchParams.set("state", state);
+  authUrl.searchParams.set("response_type", "code");
+
+  const tokenData = await new Promise((resolve, reject) => {
+    const server = createServer(async (req, res) => {
+      try {
+        const reqUrl = new URL(req.url, OAUTH_REDIRECT_URI);
+        if (reqUrl.pathname !== "/callback") {
+          res.writeHead(404).end("Not found");
+          return;
+        }
+        const err = reqUrl.searchParams.get("error");
+        const code = reqUrl.searchParams.get("code");
+        const returnedState = reqUrl.searchParams.get("state");
+        const finish = (status, html) => {
+          res.writeHead(status, { "Content-Type": "text/html" }).end(html);
+        };
+        if (err) {
+          finish(400, `<h2>Authorization failed</h2><p>${err}</p><p>You can close this tab.</p>`);
+          server.close();
+          reject(new Error(`Authorization denied: ${err}`));
+          return;
+        }
+        if (!code || returnedState !== state) {
+          finish(400, "<h2>Invalid callback</h2><p>State mismatch. Close this tab and retry.</p>");
+          server.close();
+          reject(new Error("OAuth state mismatch — aborting for safety."));
+          return;
+        }
+        const data = await exchangeOAuthCode(code, client);
+        finish(200, "<h2>✓ figma-pixel-kit is now connected</h2><p>You can close this tab and return to the terminal.</p>");
+        server.close();
+        resolve(data);
+      } catch (e) {
+        try { res.writeHead(500).end("Error"); } catch {}
+        server.close();
+        reject(e);
+      }
+    });
+    server.on("error", (e) => {
+      reject(new Error(
+        e.code === "EADDRINUSE"
+          ? `Port ${OAUTH_PORT} is in use. Free it and retry (the redirect URL must be ${OAUTH_REDIRECT_URI}).`
+          : `Local callback server error: ${e.message}`
+      ));
+    });
+    server.listen(OAUTH_PORT, () => {
+      console.log("Opening Figma authorization in your browser...");
+      console.log(`If it doesn't open, visit:\n${authUrl.toString()}`);
+      openBrowser(authUrl.toString());
+    });
+  });
+
+  const oauth = {
+    access_token: tokenData.access_token,
+    refresh_token: tokenData.refresh_token,
+    expires_at: Date.now() + Number(tokenData.expires_in || 0) * 1000
+  };
+  await saveHomeConfig({ FIGMA_OAUTH: oauth });
+  console.log(`\nConnected. Saved OAuth tokens to ${getHomeConfigPath()}`);
+  console.log('You can now run: figma-pixel-kit "<figma-node-url>"');
+}
+
+async function writeFileIfMissing(filePath, content) {
+  if (existsSync(filePath)) return false;
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content, "utf8");
+  return true;
+}
+
+function buildVSCodeInstructions() {
+  return `# Figma Pixel Kit — VS Code Workflow
+
+Use this project with VS Code and any AI coding assistant by giving it the generated file:
+
+\`design-ai/<screen-id>/prompt-for-claude.md\`
+
+## Standard flow
+
+1. Export a Figma node:
+
+\`\`\`bash
+figma-pixel-kit "<figma-node-url>"
+\`\`\`
+
+2. Open the generated folder under \`design-ai/<screen-id>/\`.
+
+3. Ask the AI assistant to implement using:
+
+- \`reference.png\` as visual truth
+- \`inventory.md\` as the complete element checklist
+- \`spec.json\` as exact bounds/style data
+- \`index.html\` only as a pixel-preview reference
+
+4. Add the generated selector to your implemented root element:
+
+\`\`\`tsx
+<section data-figma-screen="NODE_ID_HERE">
+  ...
+</section>
+\`\`\`
+
+5. Run visual compare:
+
+\`\`\`bash
+figma-pixel-kit compare "<screen-id>" --url "http://localhost:3000" --selector "[data-figma-screen='NODE_ID_HERE']"
+\`\`\`
+
+6. Give \`visual-report/fix-prompt.md\`, \`reference.png\`, \`actual.png\`, and \`diff.png\` back to the AI assistant.
+`;
+}
+
+function buildVSCodeTasks() {
+  return JSON.stringify({
+    version: "2.0.0",
+    tasks: [
+      {
+        label: "figma-pixel-kit: compare screen",
+        type: "shell",
+        command: "figma-pixel-kit compare ${input:screenId} --url ${input:localUrl} --selector ${input:selector}",
+        problemMatcher: []
+      },
+      {
+        label: "figma-pixel-kit: export node",
+        type: "shell",
+        command: "figma-pixel-kit ${input:figmaUrl}",
+        problemMatcher: []
+      }
+    ],
+    inputs: [
+      {
+        id: "figmaUrl",
+        type: "promptString",
+        description: "Figma selected node URL"
+      },
+      {
+        id: "screenId",
+        type: "promptString",
+        description: "design-ai screen id, for example: procright-web-1-21886-287699"
+      },
+      {
+        id: "localUrl",
+        type: "promptString",
+        description: "Local app URL",
+        default: "http://localhost:3000"
+      },
+      {
+        id: "selector",
+        type: "promptString",
+        description: "CSS selector to capture",
+        default: "[data-figma-screen='NODE_ID_HERE']"
+      }
+    ]
+  }, null, 2);
+}
+
+function buildRootRules() {
+  return `# Figma Pixel Kit Rules
+
+This project uses Figma Pixel Kit for Figma implementation QA.
+
+## Main rule
+
+Do not implement directly from a Figma URL alone. Use the generated implementation package under \`design-ai/<screen-id>/\`.
+
+## Source priority
+
+1. \`reference.png\` is the visual truth.
+2. \`inventory.md\` is the no-missing-elements checklist.
+3. \`spec.json\` contains exact bounds, text and styles.
+4. \`index.html\` is only a pixel preview, not production code.
+
+## Implementation rules
+
+- Do not redesign.
+- Do not simplify.
+- Do not skip visible elements.
+- Do not create duplicate primitive components if the app already has Button/Card/Input/Badge/Modal/Container.
+- Implement section by section.
+- Add \`data-figma-screen="<node-id>"\` to the implemented root element.
+- After implementation, run \`figma-pixel-kit compare\` and fix from \`visual-report/fix-prompt.md\`.
+`;
+}
+
+function buildClaudeSkill() {
+  return `---
+name: figma-pixel-perfect
+description: Implements read-only Figma screens from figma-pixel-kit output with visual regression validation.
+---
+
+# Figma Pixel Perfect Skill
+
+Use this skill when a task references a \`design-ai/<screen-id>/\` folder created by Figma Pixel Kit.
+
+## Required behavior
+
+1. Read \`prompt-for-claude.md\` first.
+2. Use \`reference.png\` as visual truth.
+3. Use \`inventory.md\` as the complete checklist.
+4. Use \`spec.json\` for exact bounds, text and style data.
+5. Use \`index.html\` only as a pixel preview, not production code.
+6. Do not skip visible elements.
+7. Do not redesign.
+8. Reuse existing project components.
+9. Add \`data-figma-screen\` to the implemented root.
+10. After coding, run visual compare and fix from \`visual-report/fix-prompt.md\`.
+
+## Final response checklist
+
+Always report:
+
+- Files changed
+- Components reused
+- New components created, if any
+- Visual compare result
+- Missing/approximate elements, if any
+`;
+}
+
+async function initCommand({ silent = false } = {}) {
+  const created = [];
+
+  if (await writeFileIfMissing(path.join(ROOT, "FIGMA_PIXEL_KIT.md"), buildRootRules())) created.push("FIGMA_PIXEL_KIT.md");
+  if (await writeFileIfMissing(path.join(ROOT, ".vscode", "figma-pixel-kit.instructions.md"), buildVSCodeInstructions())) created.push(".vscode/figma-pixel-kit.instructions.md");
+
+  const tasksPath = path.join(ROOT, ".vscode", "tasks.json");
+  const taskExamplePath = path.join(ROOT, ".vscode", "figma-pixel-kit.tasks.example.json");
+  if (await writeFileIfMissing(tasksPath, buildVSCodeTasks())) {
+    created.push(".vscode/tasks.json");
+  } else if (await writeFileIfMissing(taskExamplePath, buildVSCodeTasks())) {
+    created.push(".vscode/figma-pixel-kit.tasks.example.json");
+  }
+
+  if (await writeFileIfMissing(path.join(ROOT, ".claude", "skills", "figma-pixel-perfect", "SKILL.md"), buildClaudeSkill())) {
+    created.push(".claude/skills/figma-pixel-perfect/SKILL.md");
+  }
+
+  if (!silent) {
+    if (created.length) {
+      console.log("Created project integration files:");
+      for (const file of created) console.log(`- ${file}`);
+    } else {
+      console.log("Project integration files already exist. Nothing changed.");
+    }
+  }
+
+  return created;
+}
+
+function looksLikeFigmaUrl(value) {
+  return typeof value === "string" && /^https?:\/\/(www\.)?figma\.com\//.test(value);
+}
+
+function parseFigmaUrl(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error(`Invalid URL: ${rawUrl}`);
+  }
+
+  if (!/(^|\.)figma\.com$/.test(url.hostname)) {
+    throw new Error(`Not a figma.com URL: ${rawUrl}`);
+  }
+
+  const parts = url.pathname.split("/").filter(Boolean);
+
+  // Supported: /design/:fileKey/:fileName and /file/:fileKey/:fileName
+  // Branch:    /design/:fileKey/branch/:branchKey/:fileName  (node lives in the branch file)
+  const fileTypeIndex = parts.findIndex((p) => ["design", "file"].includes(p));
+  if (fileTypeIndex === -1) {
+    if (parts.includes("proto")) {
+      throw new Error("Prototype URLs (/proto/) are not supported. Open the file in design mode (/design/) and copy the node link.");
+    }
+    if (parts.includes("community")) {
+      throw new Error("Community URLs are not supported. Duplicate the file to your drafts, then copy a /design/ node link.");
+    }
+    throw new Error("Unsupported Figma URL. Expected a /design/ or /file/ URL containing node-id=...");
+  }
+
+  let fileKey = parts[fileTypeIndex + 1];
+  let fileNameIndex = fileTypeIndex + 2;
+
+  // Branch URLs address the branch by its own key, not the parent file key.
+  if (parts[fileTypeIndex + 2] === "branch" && parts[fileTypeIndex + 3]) {
+    fileKey = parts[fileTypeIndex + 3];
+    fileNameIndex = fileTypeIndex + 4;
+  }
+
+  // node-id may live in the query string or in the URL fragment.
+  const rawNodeId =
+    url.searchParams.get("node-id") ||
+    new URLSearchParams(url.hash.replace(/^#/, "")).get("node-id");
+
+  if (!fileKey || !rawNodeId) {
+    throw new Error("Invalid Figma URL. Could not parse fileKey or node-id. Select a node in Figma and copy its link (it must contain node-id=...).");
+  }
+
+  return {
+    fileKey,
+    nodeId: rawNodeId.replaceAll("-", ":"),
+    rawNodeId,
+    fileName: decodeURIComponent(parts[fileNameIndex] || fileKey)
+      .replace(/[^a-z0-9-_]+/gi, "-")
+      .replace(/^-+|-+$/g, "")
+      .toLowerCase() || fileKey
+  };
+}
+
+async function figmaFetch(url, token, { retries = 2 } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    let response;
+    try {
+      // PATs use X-Figma-Token; OAuth access tokens use Authorization: Bearer.
+      // Using the wrong header returns 403 Invalid token.
+      const headers = CURRENT_AUTH_TYPE === "oauth"
+        ? { Authorization: `Bearer ${token}` }
+        : { "X-Figma-Token": token };
+      response = await fetch(url, { headers });
+    } catch (networkError) {
+      if (attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, (attempt + 1) * 1000));
+        continue;
+      }
+      throw new Error(`Network error reaching Figma API: ${networkError.message}\nCheck your internet connection.`);
+    }
+
+    if (response.ok) return response.json();
+
+    // Retry transient throttling / server errors with simple backoff.
+    if ((response.status === 429 || response.status >= 500) && attempt < retries) {
+      const retryAfter = Number(response.headers.get("retry-after")) || (attempt + 1) * 2;
+      console.log(`Figma API ${response.status}; retrying in ${retryAfter}s (attempt ${attempt + 1}/${retries})...`);
+      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
+      continue;
+    }
+
+    const text = await response.text().catch(() => "");
+    let hint = "";
+    if (response.status === 403) hint = "\nHint: token invalid or no access to this file. Verify with: figma-pixel-kit doctor";
+    if (response.status === 404) hint = "\nHint: file or node not found. Branch URLs must use the branch key — re-copy the link from the branch.";
+    if (response.status === 429) hint = "\nHint: rate limited by Figma. Wait a moment and retry.";
+    throw new Error(`Figma API error ${response.status}: ${response.statusText}\n${text}${hint}`);
+  }
+}
+
+async function fetchImageFillUrls(fileKey, token) {
+  // Returns { <imageRef>: <temporary S3 url> } for every image fill in the file.
+  try {
+    const data = await figmaFetch(`https://api.figma.com/v1/files/${fileKey}/images`, token);
+    return data?.meta?.images || {};
+  } catch {
+    // Image fills are a best-effort enhancement for the debug renderer; never fail export over them.
+    return {};
+  }
+}
+
+function resolveExportScale(value) {
+  // Figma's images API supports scales between 0.01 and 4; we restrict to integer 1–4.
+  const n = Number(value);
+  if (Number.isFinite(n) && n >= 1 && n <= 4) return Math.round(n);
+  return REFERENCE_SCALE;
+}
+
+async function fetchRenderedImageUrls(fileKey, ids, token, scale) {
+  // Render one /v1/images call for the given ids. Returns { nodeId: pngUrl }.
+  if (!ids.length) return {};
+  const url = new URL(`https://api.figma.com/v1/images/${fileKey}`);
+  url.searchParams.set("ids", ids.join(","));
+  url.searchParams.set("format", "png");
+  url.searchParams.set("scale", String(scale));
+  url.searchParams.set("use_absolute_bounds", "true");
+  const data = await figmaFetch(url.toString(), token);
+  if (data.err) throw new Error(`Figma image render failed: ${data.err}`);
+  return data.images || {};
+}
+
+// Render nodes as SVG (for custom/non-library icons). Returns { nodeId: svgUrl }.
+async function fetchRenderedSvgUrls(fileKey, ids, token) {
+  if (!ids.length) return {};
+  const url = new URL(`https://api.figma.com/v1/images/${fileKey}`);
+  url.searchParams.set("ids", ids.join(","));
+  url.searchParams.set("format", "svg");
+  url.searchParams.set("use_absolute_bounds", "true");
+  const data = await figmaFetch(url.toString(), token);
+  if (data.err) throw new Error(`Figma SVG render failed: ${data.err}`);
+  return data.images || {};
+}
+
+// Render many screens with fewer round-trips than one-call-per-screen, while staying under Figma's
+// per-request render-time budget (large 2x screens make a single all-ids call return
+// "Render timeout, try requesting fewer or smaller images"). Renders in small chunks and, if a chunk
+// times out, splits it down to single ids. Any id that still fails is left out and rendered later
+// per-screen by exportScreenFromNode.
+async function renderReferenceImages(fileKey, ids, token, scale, { chunkSize = 2 } = {}) {
+  const urls = {};
+  for (let i = 0; i < ids.length; i += chunkSize) {
+    const chunk = ids.slice(i, i + chunkSize);
+    try {
+      Object.assign(urls, await fetchRenderedImageUrls(fileKey, chunk, token, scale));
+    } catch (e) {
+      if (chunk.length > 1) {
+        // Too much rendered at once (render timeout) — retry each id on its own.
+        for (const id of chunk) {
+          try {
+            Object.assign(urls, await fetchRenderedImageUrls(fileKey, [id], token, scale));
+          } catch {
+            // leave missing; exportScreenFromNode renders it individually as a last resort
+          }
+        }
+      }
+      // single-id chunk failed: leave missing for the per-screen fallback
+    }
+  }
+  return urls;
+}
+
+async function downloadFile(url, outputPath) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Download failed ${response.status}: ${url}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await writeFile(outputPath, buffer);
+}
+
+function getNodeBounds(node) {
+  return node.absoluteBoundingBox || node.absoluteRenderBounds || null;
+}
+
+function isVisible(node) {
+  return node.visible !== false && (node.opacity ?? 1) > 0;
+}
+
+function flattenNodes(node, result = []) {
+  if (!node || !isVisible(node)) return result;
+  result.push(node);
+
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) {
+      flattenNodes(child, result);
+    }
+  }
+
+  return result;
+}
+
+function rgbaToCss(color, opacity = 1) {
+  if (!color) return "transparent";
+
+  const r = Math.round((color.r ?? 0) * 255);
+  const g = Math.round((color.g ?? 0) * 255);
+  const b = Math.round((color.b ?? 0) * 255);
+  const a = Number(((color.a ?? 1) * opacity).toFixed(3));
+
+  if (a >= 1) return `rgb(${r}, ${g}, ${b})`;
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}
+
+function firstSolidFill(node) {
+  const fills = Array.isArray(node.fills) ? node.fills : [];
+  return fills.find((fill) => fill.visible !== false && fill.type === "SOLID");
+}
+
+function firstImageFill(node) {
+  const fills = Array.isArray(node.fills) ? node.fills : [];
+  return fills.find((fill) => fill.visible !== false && fill.type === "IMAGE" && fill.imageRef);
+}
+
+function nodeCss(node, rootBounds, imageRefMap = {}) {
+  const bounds = getNodeBounds(node);
+  if (!bounds) return "";
+
+  const left = Math.round(bounds.x - rootBounds.x);
+  const top = Math.round(bounds.y - rootBounds.y);
+  const width = Math.round(bounds.width);
+  const height = Math.round(bounds.height);
+
+  const parts = [
+    "position:absolute",
+    `left:${left}px`,
+    `top:${top}px`,
+    `width:${width}px`,
+    `height:${height}px`
+  ];
+
+  // Solid background only for non-text nodes; for TEXT the solid fill is the glyph color (handled below).
+  const fill = firstSolidFill(node);
+  if (fill && node.type !== "TEXT") {
+    parts.push(`background-color:${rgbaToCss(fill.color, fill.opacity ?? node.opacity ?? 1)}`);
+  }
+
+  // Image fills: reference the asset downloaded into ./assets during export.
+  const imageFill = firstImageFill(node);
+  if (imageFill && imageRefMap[imageFill.imageRef]) {
+    parts.push(`background-image:url(${JSON.stringify(imageRefMap[imageFill.imageRef])})`);
+    parts.push(`background-size:${imageFill.scaleMode === "FIT" ? "contain" : "cover"}`);
+    parts.push("background-position:center");
+    parts.push("background-repeat:no-repeat");
+  }
+
+  if (node.type === "ELLIPSE") {
+    parts.push("border-radius:50%"); // circles/avatars/status dots, not square boxes
+  } else if (typeof node.cornerRadius === "number") {
+    parts.push(`border-radius:${Math.round(node.cornerRadius)}px`);
+  }
+
+  if (Array.isArray(node.strokes) && node.strokes.length > 0) {
+    const stroke = node.strokes.find((s) => s.visible !== false && s.type === "SOLID");
+    if (stroke) {
+      const weight = node.strokeWeight || 1;
+      parts.push(`border:${weight}px solid ${rgbaToCss(stroke.color, stroke.opacity ?? 1)}`);
+    }
+  }
+
+  if (node.type === "TEXT") {
+    const style = node.style || {};
+    parts.push("white-space:pre-wrap");
+    parts.push("overflow:hidden");
+    if (style.fontFamily) parts.push(`font-family:${JSON.stringify(style.fontFamily)}, sans-serif`);
+    if (style.fontSize) parts.push(`font-size:${style.fontSize}px`);
+    if (style.fontWeight) parts.push(`font-weight:${style.fontWeight}`);
+    if (style.lineHeightPx) parts.push(`line-height:${style.lineHeightPx}px`);
+    if (style.letterSpacing) parts.push(`letter-spacing:${style.letterSpacing}px`);
+
+    const textFill = firstSolidFill(node);
+    if (textFill) parts.push(`color:${rgbaToCss(textFill.color, textFill.opacity ?? 1)}`);
+
+    const align = style.textAlignHorizontal?.toLowerCase();
+    if (align) parts.push(`text-align:${align}`);
+  }
+
+  if (Array.isArray(node.effects)) {
+    const shadows = node.effects
+      .filter((effect) => effect.visible !== false && effect.type === "DROP_SHADOW")
+      .map((effect) => {
+        const x = Math.round(effect.offset?.x ?? 0);
+        const y = Math.round(effect.offset?.y ?? 0);
+        const blur = Math.round(effect.radius ?? 0);
+        const color = rgbaToCss(effect.color, effect.color?.a ?? 1);
+        return `${x}px ${y}px ${blur}px ${color}`;
+      });
+
+    if (shadows.length) parts.push(`box-shadow:${shadows.join(",")}`);
+  }
+
+  return parts.join(";");
+}
+
+function classifyElement(node) {
+  if (node.type === "TEXT") return "text";
+  if (firstImageFill(node)) return "image-fill";
+  if (["RECTANGLE", "ELLIPSE", "VECTOR", "STAR", "POLYGON", "LINE"].includes(node.type)) return "shape";
+  if (["INSTANCE", "COMPONENT", "COMPONENT_SET"].includes(node.type)) return "component";
+  if (["FRAME", "GROUP", "SECTION"].includes(node.type)) return "container";
+  return "other";
+}
+
+function nodeHasVisiblePaint(node) {
+  if (firstSolidFill(node) || firstImageFill(node)) return true;
+  if (Array.isArray(node.strokes) && node.strokes.some((s) => s.visible !== false && s.type === "SOLID")) return true;
+  return false;
+}
+
+// --- Icon library detection -------------------------------------------------
+// Figma icons are usually instances named "<Set> / <icon-name>" (e.g. "Lucide Icons / chevron-right").
+// We map the set to the npm package a codebase typically uses and the icon name to its PascalCase
+// component, so the implementer imports it directly instead of redrawing the glyph as inline SVG.
+const ICON_SETS = [
+  { test: /^lucide(\s*icons?)?\s*[/:>-]/i, set: "lucide", pkg: "lucide-react" },
+  { test: /^(font\s*awesome|fa)\s*[/:>-]/i, set: "font-awesome", pkg: "@fortawesome/react-fontawesome" },
+  { test: /^feather\s*[/:>-]/i, set: "feather", pkg: "react-feather" },
+  { test: /^(heroicons?|hero)\s*[/:>-]/i, set: "heroicons", pkg: "@heroicons/react" },
+  { test: /^(material\s*(symbols|icons)|mui)\s*[/:>-]/i, set: "material", pkg: "@mui/icons-material" },
+  { test: /^phosphor\s*[/:>-]/i, set: "phosphor", pkg: "@phosphor-icons/react" },
+  { test: /^tabler\s*[/:>-]/i, set: "tabler", pkg: "@tabler/icons-react" },
+];
+
+function pascalFromIconName(s) {
+  return String(s).trim().split(/[^a-z0-9]+/i).filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1).toLowerCase()).join("");
+}
+
+// Returns { set, pkg, iconName, component, figmaName } for a known icon-set name, else null.
+function detectIconLibrary(rawName) {
+  const name = String(rawName || "").trim();
+  if (!name) return null;
+  for (const entry of ICON_SETS) {
+    if (entry.test.test(name)) {
+      const iconName = (name.split("/").pop() || name).trim();
+      return { set: entry.set, pkg: entry.pkg, iconName, component: pascalFromIconName(iconName), figmaName: name };
+    }
+  }
+  return null;
+}
+
+function isIconSized(b) {
+  if (!b || b.width <= 0 || b.height <= 0) return false;
+  if (b.width > 64 || b.height > 64) return false;
+  const ar = b.width / b.height;
+  return ar >= 0.4 && ar <= 2.5;
+}
+
+// Classify a screen's nodes into: library icons (import from a package), custom icons (download SVG),
+// and images (raster fills already downloaded to ./assets). Best-effort, never throws on bad nodes.
+function collectScreenAssets(rootNode, nodes, componentNameById = {}, imageRefMap = {}) {
+  const libraryIcons = new Map(); // component -> { set, pkg, component, iconName, count, sizes:Set }
+  const customIcons = new Map();  // slug -> { id, name, slug, bounds }
+  const images = [];
+  const GENERIC = /^(vector|rectangle|ellipse|line|union|subtract|group|frame|polygon|star|shape|mask|image)\b/i;
+
+  for (const node of nodes) {
+    if (!node || node.id === rootNode.id) continue;
+    const b = getNodeBounds(node);
+    if (!b) continue;
+    const displayName = (node.componentId && componentNameById[node.componentId]) || node.name || "";
+
+    const imgFill = firstImageFill(node);
+    if (imgFill && imageRefMap[imgFill.imageRef]) {
+      images.push({
+        id: node.id, name: node.name || "image", assetPath: imageRefMap[imgFill.imageRef],
+        bounds: { width: Math.round(b.width), height: Math.round(b.height) },
+      });
+      continue;
+    }
+
+    const lib = detectIconLibrary(displayName);
+    if (lib) {
+      const cur = libraryIcons.get(lib.component) || { ...lib, count: 0, sizes: new Set() };
+      cur.count += 1;
+      cur.sizes.add(`${Math.round(b.width)}×${Math.round(b.height)}`);
+      libraryIcons.set(lib.component, cur);
+      continue;
+    }
+
+    // A custom icon is real vector/graphic content — NOT a plain RECTANGLE/ELLIPSE/LINE
+    // (those are background plates, dividers, image frames; e.g. a 57×57 white "image 18"
+    // badge plate must not be reported as an asset to supply).
+    const kind = classifyElement(node);
+    const vectorish =
+      ["VECTOR", "BOOLEAN_OPERATION", "STAR", "POLYGON"].includes(node.type) ||
+      (kind === "component" && (!node.children || node.children.length === 0));
+    if (vectorish && isIconSized(b) && displayName && !GENERIC.test(displayName)) {
+      const slug = slugifyName(displayName);
+      if (!customIcons.has(slug)) {
+        customIcons.set(slug, {
+          id: node.id, name: displayName, slug,
+          bounds: { width: Math.round(b.width), height: Math.round(b.height) },
+        });
+      }
+    }
+  }
+
+  return {
+    libraryIcons: [...libraryIcons.values()].map((i) => ({ ...i, sizes: [...i.sizes] })),
+    customIcons: [...customIcons.values()],
+    images,
+  };
+}
+
+const GENERIC_VECTOR_NAME = /^(vector|rectangle|ellipse|line|union|subtract|group|frame|polygon|star|shape|mask)\b/i;
+
+// An "icon root" is the node we render as ONE SVG so the debug preview shows the real glyph.
+// It's the named icon (instance/component named e.g. "Lucide Icons / chevron-right"), or an
+// icon-sized standalone vector — NOT the inner "Vector" leaves (those would all collapse together).
+function isIconRoot(node, componentNameById = {}) {
+  if (!node || node.type === "TEXT") return false;
+  if (firstImageFill(node)) return false; // image fills are drawn as background already
+  const name = (node.componentId && componentNameById[node.componentId]) || node.name || "";
+  const b = getNodeBounds(node);
+  if (!b) return false;
+  // Named library icon (any size) — render the whole instance.
+  if (detectIconLibrary(name)) return true;
+  // Icon-sized GRAPHIC (instance/component/vector) with a meaningful name. FRAME/GROUP are
+  // excluded on purpose — small named frames like "Container"/"Header" are layout, not icons.
+  if (isIconSized(b) && name && !GENERIC_VECTOR_NAME.test(name) &&
+      ["INSTANCE", "COMPONENT", "VECTOR", "BOOLEAN_OPERATION"].includes(node.type)) {
+    return true;
+  }
+  // Icon-sized standalone vector with no meaningful name — still render it (keyed by id).
+  if (isIconSized(b) && ["VECTOR", "BOOLEAN_OPERATION", "STAR", "POLYGON", "LINE"].includes(node.type)) {
+    return true;
+  }
+  return false;
+}
+
+// Walk the FULL tree (including hidden subtrees that flattenNodes prunes) to find icon roots
+// that are hidden in the resting frame — i.e. hover-state icons (the "…" / "+" that appear on
+// hover). We surface these dimmed in the debug preview and list them in inventory.md so the
+// resting frame can still be compared while knowing which elements are hover-only.
+function collectHiddenIconRoots(root, componentNameById = {}) {
+  const out = [];
+  const walk = (node, hiddenAncestor) => {
+    if (!node) return;
+    const selfHidden = node.visible === false || (node.opacity ?? 1) === 0;
+    // A hover affordance is a node toggled OFF inside an otherwise-visible container.
+    // Only collect those (selfHidden but NO hidden ancestor) — this excludes the hundreds of
+    // deep variant-internal layers that live hidden inside component instances.
+    if (selfHidden && !hiddenAncestor && getNodeBounds(node) && isIconRoot(node, componentNameById)) {
+      const name = (node.componentId && componentNameById[node.componentId]) || node.name || "";
+      const lib = detectIconLibrary(name);
+      out.push({ id: node.id, name, lucide: lib ? lib.iconName : null, bounds: getNodeBounds(node) });
+    }
+    if (Array.isArray(node.children)) for (const c of node.children) walk(c, hiddenAncestor || selfHidden);
+  };
+  walk(root, false);
+  return out;
+}
+
+// Stable key so identical icons (e.g. every chevron-right instance) share ONE downloaded SVG file;
+// generic/unnamed vectors key by node id so they never collapse onto each other.
+function svgKeyFor(node, componentNameById = {}) {
+  const name = (node.componentId && componentNameById[node.componentId]) || node.name || "";
+  const lib = detectIconLibrary(name);
+  if (lib) return `lib-${lib.component}`;
+  if (name && !GENERIC_VECTOR_NAME.test(name)) return `cus-${slugifyName(name)}`;
+  return `id-${String(node.id).replace(/[^a-z0-9]/gi, "-")}`;
+}
+
+function shouldRenderNode(node, rootNode) {
+  if (node.id === rootNode.id) return false;
+  const bounds = getNodeBounds(node);
+  if (!bounds || bounds.width <= 0 || bounds.height <= 0) return false;
+
+  const kind = classifyElement(node);
+
+  // Render visible leaf-like nodes and text.
+  if (kind === "text" || kind === "shape" || kind === "image-fill") return true;
+
+  // Render component instances only if they do not have children.
+  if (kind === "component" && (!node.children || node.children.length === 0)) return true;
+
+  // Render container (FRAME/GROUP/SECTION) backgrounds only when they actually paint something,
+  // so section/card background colors and images appear without flooding the DOM with empty wrappers.
+  // Containers come before their children in preorder, so they sit behind child content.
+  if (kind === "container" && nodeHasVisiblePaint(node)) return true;
+
+  return false;
+}
+
+function escapeHtml(value = "") {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function buildHtml(rootNode, nodes, imageRefMap = {}, nodeIconMap = {}, hoverIcons = []) {
+  const rootBounds = getNodeBounds(rootNode);
+  const width = Math.round(rootBounds.width);
+  const height = Math.round(rootBounds.height);
+
+  const rootFill = firstSolidFill(rootNode);
+  const frameBg = rootFill ? rgbaToCss(rootFill.color, rootFill.opacity ?? 1) : "#fff";
+
+  // Render normal nodes plus any library-icon root (often instances-with-children that
+  // shouldRenderNode skips) so we can drop the library glyph in via the icon library.
+  const elements = nodes.filter(
+    (node) => shouldRenderNode(node, rootNode) || nodeIconMap[node.id]
+  );
+
+  let usesLucide = false;
+  const htmlElements = elements.map((node, index) => {
+    const className = `node-${index}`;
+    const text = node.type === "TEXT" ? escapeHtml(node.characters || "") : "";
+    const label = escapeHtml(`${node.type}: ${node.name}`);
+    // Library icons → render live from the icon library's CDN (e.g. lucide <i data-lucide>).
+    // Custom/unknown vectors are left as boxes (their own fill color), to be supplied by hand.
+    const icon = nodeIconMap[node.id];
+    let inner = text;
+    if (icon && icon.set === "lucide") {
+      usesLucide = true;
+      inner = `<i data-lucide="${escapeHtml(icon.name)}"></i>`;
+    }
+    return `<div class="figma-node ${className}" data-figma-id="${escapeHtml(node.id)}" title="${label}">${inner}</div>`;
+  }).join("\n      ");
+
+  const cssRules = elements.map((node, index) => {
+    return `.node-${index}{${nodeCss(node, rootBounds, imageRefMap)}}`;
+  }).join("\n");
+
+  // Hover-state icons (hidden in the resting frame) rendered dimmed + dashed so they're
+  // distinguishable from always-visible content.
+  const hoverHtml = hoverIcons.map((h, i) => {
+    let inner = "";
+    if (h.lucide) { usesLucide = true; inner = `<i data-lucide="${escapeHtml(h.lucide)}"></i>`; }
+    return `<div class="figma-node figma-hover hovernode-${i}" data-figma-hover="true" title="HOVER: ${escapeHtml(h.name)}">${inner}</div>`;
+  }).join("\n      ");
+  const hoverCss = hoverIcons.map((h, i) => {
+    const b = h.bounds;
+    return `.hovernode-${i}{position:absolute;left:${Math.round(b.x - rootBounds.x)}px;top:${Math.round(b.y - rootBounds.y)}px;width:${Math.round(b.width)}px;height:${Math.round(b.height)}px}`;
+  }).join("\n");
+
+  const iconRuntime = usesLucide
+    ? `
+  <script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
+  <script>window.lucide && lucide.createIcons();</script>`
+    : "";
+
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <title>${escapeHtml(rootNode.name)} - Figma Pixel Preview</title>
+  <link rel="stylesheet" href="./styles.css" />
+</head>
+<body>
+  <main class="preview-shell">
+    <div class="toolbar">
+      <strong>${escapeHtml(rootNode.name)}</strong>
+      <span>${width} × ${height}</span>
+      <span>${elements.length} rendered elements</span>
+    </div>
+
+    <section class="figma-frame" data-figma-root="${escapeHtml(rootNode.id)}" data-figma-screen="${escapeHtml(rootNode.id)}">
+      ${htmlElements}
+      ${hoverHtml}
+    </section>
+  </main>${iconRuntime}
+</body>
+</html>`;
+
+  const css = `*{box-sizing:border-box}
+body{
+  margin:0;
+  font-family:Inter,Arial,sans-serif;
+  background:#111;
+  color:#fff;
+}
+.preview-shell{
+  padding:24px;
+}
+.toolbar{
+  display:flex;
+  gap:16px;
+  align-items:center;
+  margin-bottom:16px;
+  font-size:14px;
+  color:#ddd;
+}
+.toolbar span{
+  opacity:.75;
+}
+.figma-frame{
+  position:relative;
+  width:${width}px;
+  height:${height}px;
+  overflow:hidden;
+  background:${frameBg};
+  box-shadow:0 20px 80px rgba(0,0,0,.45);
+}
+.figma-node{
+  overflow:hidden;
+}
+/* Hover-state (normally hidden) icons: dimmed + dashed so they read as "appears on hover". */
+.figma-hover{
+  opacity:.45;
+  outline:1px dashed #f59e0b;
+  outline-offset:1px;
+}
+${hoverCss}
+/* Library icons rendered by the icon library fill their Figma box. */
+/* lucide draws with stroke:currentColor; the shell sets color:#fff, so without an
+   explicit dark color the icons would be white-on-white (invisible "empty boxes"). */
+.figma-frame{
+  color:#3f3f46;
+}
+.figma-node [data-lucide], .figma-node svg{
+  width:100%;
+  height:100%;
+  display:block;
+  color:#3f3f46;
+}
+${cssRules}
+`;
+
+  return { html, css };
+}
+
+function buildInventoryMarkdown(rootNode, nodes, componentNameById = {}, hoverIcons = []) {
+  const rootBounds = getNodeBounds(rootNode);
+  const sorted = nodes
+    .filter((node) => node.id !== rootNode.id && getNodeBounds(node))
+    .map((node) => {
+      const b = getNodeBounds(node);
+      return {
+        id: node.id,
+        name: node.name,
+        type: node.type,
+        kind: classifyElement(node),
+        x: Math.round(b.x - rootBounds.x),
+        y: Math.round(b.y - rootBounds.y),
+        width: Math.round(b.width),
+        height: Math.round(b.height),
+        text: node.type === "TEXT" ? node.characters || "" : "",
+        fontSize: node.style?.fontSize ?? null,
+        fontWeight: node.style?.fontWeight ?? null,
+        componentName: node.componentId ? (componentNameById[node.componentId] || node.name) : null,
+        layoutCss: autoLayoutToCss(node)?.css || null
+      };
+    })
+    .sort((a, b) => a.y - b.y || a.x - b.x);
+
+  const instanceCount = sorted.filter((item) => item.componentName).length;
+
+  const lines = [];
+  lines.push(`# Element Inventory`);
+  lines.push("");
+  lines.push(`Frame: **${rootNode.name}**`);
+  lines.push(`Node ID: \`${rootNode.id}\``);
+  lines.push(`Size: **${Math.round(rootBounds.width)} × ${Math.round(rootBounds.height)}**`);
+  lines.push(`Total bounded nodes: **${sorted.length}**`);
+  if (instanceCount) lines.push(`Component instances (reuse, do not rebuild): **${instanceCount}** — see \`component-library.md\``);
+  lines.push("");
+
+  for (const [index, item] of sorted.entries()) {
+    const heading = item.componentName
+      ? `## ${index + 1}. ↻ COMPONENT INSTANCE — ${item.name}`
+      : `## ${index + 1}. ${item.kind.toUpperCase()} — ${item.name}`;
+    lines.push(heading);
+    lines.push("");
+    if (item.componentName) {
+      lines.push(`- ↻ Shared component: \`${pascalCase(item.componentName)}\` — reuse the existing component, do NOT re-implement.`);
+    }
+    lines.push(`- Figma ID: \`${item.id}\``);
+    lines.push(`- Type: \`${item.type}\``);
+    lines.push(`- Bounds: x=${item.x}, y=${item.y}, width=${item.width}, height=${item.height}`);
+    if (item.layoutCss) lines.push(`- Auto Layout: \`${item.layoutCss}\``);
+    if (item.text) lines.push(`- Text: ${JSON.stringify(item.text)}`);
+    if (item.fontSize) lines.push(`- Font size: ${item.fontSize}`);
+    if (item.fontWeight) lines.push(`- Font weight: ${item.fontWeight}`);
+    lines.push("");
+  }
+
+  // Hover / hidden-state elements — present in the design but hidden (visible:false) in the
+  // resting frame (e.g. the row "…" / "+" that appear on hover). Listed for comparison: they
+  // are NOT in reference.png, and show dimmed + dashed in debug-render.html.
+  if (Array.isArray(hoverIcons) && hoverIcons.length) {
+    const seen = new Set();
+    const uniq = hoverIcons.filter((h) => {
+      const k = h.lucide || h.name;
+      if (seen.has(k)) return false;
+      seen.add(k);
+      return true;
+    });
+    lines.push("## Hover / hidden-state elements (görünmez — karşılaştırma için)", "");
+    lines.push(
+      "Bu öğeler tasarımda var ama durağan frame'de `visible:false` (hover'da çıkar). " +
+        "`reference.png`'de YOKtur; `debug-render.html`'de soluk + turuncu kesik çerçeveyle gösterilir.",
+      ""
+    );
+    lines.push("| Element | Library icon | Count (instances) |", "|---|---|---:|");
+    for (const h of uniq) {
+      const count = hoverIcons.filter((x) => (x.lucide || x.name) === (h.lucide || h.name)).length;
+      lines.push(`| ${h.name || "(unnamed)"} | ${h.lucide || "—"} | ${count} |`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// Figma Auto Layout → a CSS-flexbox-shaped block the implementer can apply directly,
+// instead of inferring flex from absolute pixel positions.
+function autoLayoutToCss(node) {
+  if (!node.layoutMode || node.layoutMode === "NONE") return null;
+  const justify = { MIN: "flex-start", CENTER: "center", MAX: "flex-end", SPACE_BETWEEN: "space-between" };
+  const align = { MIN: "flex-start", CENTER: "center", MAX: "flex-end", BASELINE: "baseline" };
+  const layout = {
+    display: "flex",
+    flexDirection: node.layoutMode === "HORIZONTAL" ? "row" : "column",
+    gap: Math.round(node.itemSpacing ?? 0),
+    padding: {
+      top: Math.round(node.paddingTop ?? 0),
+      right: Math.round(node.paddingRight ?? 0),
+      bottom: Math.round(node.paddingBottom ?? 0),
+      left: Math.round(node.paddingLeft ?? 0)
+    },
+    justifyContent: justify[node.primaryAxisAlignItems] || "flex-start",
+    alignItems: align[node.counterAxisAlignItems] || "flex-start",
+    flexWrap: node.layoutWrap === "WRAP" ? "wrap" : "nowrap"
+  };
+  // One-line CSS the AI can paste.
+  const p = layout.padding;
+  const pad = (p.top === p.bottom && p.left === p.right)
+    ? (p.top === p.left ? `${p.top}px` : `${p.top}px ${p.left}px`)
+    : `${p.top}px ${p.right}px ${p.bottom}px ${p.left}px`;
+  layout.css = `display:flex;flex-direction:${layout.flexDirection};gap:${layout.gap}px;padding:${pad};justify-content:${layout.justifyContent};align-items:${layout.alignItems}` +
+    (layout.flexWrap === "wrap" ? ";flex-wrap:wrap" : "");
+  return layout;
+}
+
+// How a node sizes inside its auto-layout parent (FILL = stretch/flex:1, HUG = fit-content, FIXED = px).
+function layoutChildInfo(node) {
+  const info = {};
+  if (node.layoutSizingHorizontal) info.horizontal = node.layoutSizingHorizontal; // FIXED | HUG | FILL
+  if (node.layoutSizingVertical) info.vertical = node.layoutSizingVertical;
+  if (node.layoutGrow) info.grow = node.layoutGrow;
+  if (node.layoutAlign && node.layoutAlign !== "INHERIT") info.align = node.layoutAlign; // STRETCH ...
+  return Object.keys(info).length ? info : null;
+}
+
+function buildSpecJson(rootNode, nodes, source, componentNameById = {}, scale = REFERENCE_SCALE) {
+  const rootBounds = getNodeBounds(rootNode);
+  const width = Math.round(rootBounds.width);
+  const height = Math.round(rootBounds.height);
+
+  return {
+    source,
+    frame: {
+      id: rootNode.id,
+      name: rootNode.name,
+      // Logical (CSS px) size — implement against these dimensions.
+      width,
+      height,
+      // reference.png is rendered at this scale, so its pixel size is width*scale × height*scale.
+      // `compare` reads this to capture the app at the matching deviceScaleFactor.
+      scale,
+      exportWidth: width * scale,
+      exportHeight: height * scale
+    },
+    visualTesting: {
+      recommendedSelector: `[data-figma-screen='${rootNode.id}']`,
+      referenceScale: scale,
+      defaultThreshold: 0.12,
+      defaultMaxDiffRatio: 0.03
+    },
+    elements: nodes
+      .filter((node) => node.id !== rootNode.id && getNodeBounds(node))
+      .map((node) => {
+        const b = getNodeBounds(node);
+        const entry = {
+          id: node.id,
+          name: node.name,
+          type: node.type,
+          kind: classifyElement(node),
+          bounds: {
+            x: Math.round(b.x - rootBounds.x),
+            y: Math.round(b.y - rootBounds.y),
+            width: Math.round(b.width),
+            height: Math.round(b.height)
+          },
+          text: node.type === "TEXT" ? node.characters || "" : undefined,
+          style: node.style || undefined,
+          fills: node.fills || undefined,
+          strokes: node.strokes || undefined,
+          effects: node.effects || undefined,
+          cornerRadius: node.cornerRadius
+        };
+        // Auto Layout (flex intent) — far better than guessing flex from coordinates.
+        const layout = autoLayoutToCss(node);
+        if (layout) entry.layout = layout;
+        const childInfo = layoutChildInfo(node);
+        if (childInfo) entry.layoutChild = childInfo;
+        // Constraints (responsive pin/stretch). Mostly relevant for non-auto-layout children.
+        if (node.constraints) entry.constraints = node.constraints;
+        if (node.componentId) {
+          entry.isInstance = true;
+          entry.componentId = node.componentId;
+          entry.componentName = componentNameById[node.componentId] || node.name;
+          entry.suggestedComponentName = pascalCase(entry.componentName);
+        }
+        return entry;
+      })
+  };
+}
+
+
+function buildReferencePreviewHtml(rootNode) {
+  const rootBounds = getNodeBounds(rootNode);
+  const width = Math.round(rootBounds.width);
+  const height = Math.round(rootBounds.height);
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <title>${escapeHtml(rootNode.name)} - Reference Preview</title>
+  <style>
+    *{box-sizing:border-box}
+    body{margin:0;min-height:100vh;background:#111;color:#fff;font-family:Inter,Arial,sans-serif;padding:24px}
+    .toolbar{display:flex;gap:16px;align-items:center;margin-bottom:16px;font-size:14px;color:#ddd}
+    .toolbar span{opacity:.75}
+    .frame{width:${width}px;height:${height}px;position:relative;overflow:hidden;background:#fff;box-shadow:0 20px 80px rgba(0,0,0,.45)}
+    .frame img{display:block;width:${width}px;height:${height}px;object-fit:cover}
+  </style>
+</head>
+<body>
+  <div class="toolbar">
+    <strong>${escapeHtml(rootNode.name)}</strong>
+    <span>${width} × ${height}</span>
+    <span>Pixel-perfect reference preview</span>
+  </div>
+  <main class="frame" data-figma-root="${escapeHtml(rootNode.id)}" data-figma-screen="${escapeHtml(rootNode.id)}">
+    <img src="./reference.png" alt="${escapeHtml(rootNode.name)} Figma reference" />
+  </main>
+</body>
+</html>`;
+}
+
+function summarizeNodeTypes(nodes, rootNode) {
+  const summary = new Map();
+  const rendered = new Map();
+  const skipped = new Map();
+
+  for (const node of nodes) {
+    const type = node.type || "UNKNOWN";
+    summary.set(type, (summary.get(type) || 0) + 1);
+
+    if (node.id !== rootNode.id && getNodeBounds(node)) {
+      if (shouldRenderNode(node, rootNode)) rendered.set(type, (rendered.get(type) || 0) + 1);
+      else skipped.set(type, (skipped.get(type) || 0) + 1);
+    }
+  }
+
+  const toObject = (map) => Object.fromEntries([...map.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])));
+  return {
+    totalNodes: nodes.length,
+    boundedNodes: nodes.filter((node) => getNodeBounds(node)).length,
+    byType: toObject(summary),
+    renderedByCurrentHtmlRenderer: toObject(rendered),
+    skippedByCurrentHtmlRenderer: toObject(skipped)
+  };
+}
+
+function buildInspectMarkdown(rootNode, nodes, source) {
+  const rootBounds = getNodeBounds(rootNode);
+  const summary = summarizeNodeTypes(nodes, rootNode);
+  const lines = [];
+  lines.push("# Figma Inspect Report", "");
+  lines.push(`Source: ${source.figmaUrl}`);
+  lines.push(`Frame: **${rootNode.name}**`);
+  lines.push(`Node ID: \`${rootNode.id}\``);
+  lines.push(`Size: **${Math.round(rootBounds.width)} × ${Math.round(rootBounds.height)}**`, "");
+  lines.push("## Summary", "");
+  lines.push(`- Total nodes: **${summary.totalNodes}**`);
+  lines.push(`- Bounded nodes: **${summary.boundedNodes}**`, "");
+  lines.push("## Node types", "");
+  for (const [type, count] of Object.entries(summary.byType)) lines.push(`- ${type}: ${count}`);
+  lines.push("", "## Rendered by current debug HTML renderer", "");
+  for (const [type, count] of Object.entries(summary.renderedByCurrentHtmlRenderer)) lines.push(`- ${type}: ${count}`);
+  lines.push("", "## Skipped by current debug HTML renderer", "");
+  for (const [type, count] of Object.entries(summary.skippedByCurrentHtmlRenderer)) lines.push(`- ${type}: ${count}`);
+  lines.push("", "## Important note", "");
+  lines.push("`index.html` uses the Figma-exported `reference.png` for a pixel-perfect preview.");
+  lines.push("`debug-render.html` is the experimental node-to-div renderer. It now draws container/frame background fills, strokes and image fills (downloaded to `assets/`), but remains approximate for fonts and vector/icon geometry.", "");
+  return lines.join("\n");
+}
+
+async function getFigmaRootNode(figmaUrl, token) {
+  const source = parseFigmaUrl(figmaUrl);
+  const nodeUrl = new URL(`https://api.figma.com/v1/files/${source.fileKey}/nodes`);
+  nodeUrl.searchParams.set("ids", source.nodeId);
+  console.log(`Fetching node JSON: ${source.fileKey} / ${source.nodeId}`);
+  const nodeResponse = await figmaFetch(nodeUrl.toString(), token);
+  const entry = nodeResponse.nodes?.[source.nodeId];
+  const rootNode = entry?.document;
+  if (!rootNode) throw new Error(`Could not find node ${source.nodeId} in Figma response.`);
+  // The /nodes endpoint nests component metadata per requested node.
+  const componentsMeta = entry.components || {};
+  const componentSetsMeta = entry.componentSets || {};
+  return { source, nodeResponse, rootNode, componentsMeta, componentSetsMeta };
+}
+
+async function inspectCommand(figmaUrl) {
+  if (!figmaUrl) throw new Error("Missing Figma URL.");
+  const token = await resolveFigmaToken();
+  if (!token) throw new Error('Missing Figma token. Run: figma-pixel-kit token "figd_xxxxxxxxx"');
+
+  const { rootNode } = await getFigmaRootNode(figmaUrl, token);
+  const allNodes = flattenNodes(rootNode);
+  const summary = summarizeNodeTypes(allNodes, rootNode);
+  const rootBounds = getNodeBounds(rootNode);
+
+  console.log("");
+  console.log("Inspect summary");
+  console.log("---------------");
+  console.log(`Frame: ${rootNode.name}`);
+  console.log(`Node ID: ${rootNode.id}`);
+  console.log(`Size: ${Math.round(rootBounds.width)} × ${Math.round(rootBounds.height)}`);
+  console.log(`Total nodes: ${summary.totalNodes}`);
+  console.log(`Bounded nodes: ${summary.boundedNodes}`);
+  console.log("");
+  console.log("Node types:");
+  for (const [type, count] of Object.entries(summary.byType)) console.log(`  ${type}: ${count}`);
+  console.log("");
+  console.log("Rendered by debug HTML renderer:");
+  for (const [type, count] of Object.entries(summary.renderedByCurrentHtmlRenderer)) console.log(`  ${type}: ${count}`);
+  console.log("");
+  console.log("Skipped by debug HTML renderer:");
+  for (const [type, count] of Object.entries(summary.skippedByCurrentHtmlRenderer)) console.log(`  ${type}: ${count}`);
+}
+
+function buildAssetsMarkdown(assets, rootNode) {
+  const a = assets || { libraryIcons: [], customIcons: [], images: [] };
+  const lines = [];
+  lines.push(`# Icons & Assets — ${rootNode.name}`, "");
+  lines.push(
+    "Implement icons/images from here instead of redrawing them.",
+    "- **Library icons** → import from the project's icon package (map to its equivalent if it differs). In the debug preview these render live from the library CDN.",
+    "- **Custom icons** → NOT downloaded. They appear as a placeholder box (their own fill color) in the preview — export/supply the asset yourself.",
+    "- **Images** → reference the file in `assets/` (`<img>`/background), do not re-create.",
+    ""
+  );
+
+  lines.push("## Library icons", "");
+  if (a.libraryIcons.length) {
+    lines.push("| Icon | Set | Suggested import | Count | Sizes |", "|---|---|---|---:|---|");
+    for (const i of a.libraryIcons) {
+      lines.push(`| ${i.component} | ${i.set} | \`import { ${i.component} } from "${i.pkg}"\` | ${i.count} | ${i.sizes.join(", ")} |`);
+    }
+  } else lines.push("_None detected._");
+
+  lines.push("", "## Custom icons (placeholder box — supply your own asset)", "");
+  if (a.customIcons.length) {
+    lines.push("| Name | Size | Note |", "|---|---|---|");
+    for (const c of a.customIcons) {
+      lines.push(`| ${c.name} | ${c.bounds.width}×${c.bounds.height} | not a known library — export from Figma and reference under \`assets/\` |`);
+    }
+  } else lines.push("_None detected._");
+
+  lines.push("", "## Images", "");
+  if (a.images.length) {
+    lines.push("| Name | Asset | Size |", "|---|---|---|");
+    for (const im of a.images) {
+      lines.push(`| ${im.name} | \`${im.assetPath}\` | ${im.bounds.width}×${im.bounds.height} |`);
+    }
+  } else lines.push("_None detected._");
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+function buildClaudePrompt(rootNode, assets) {
+  const a = assets || { libraryIcons: [], customIcons: [], images: [] };
+  const libList = a.libraryIcons.slice(0, 24).map((i) => i.component).join(", ");
+  const iconLine = a.libraryIcons.length
+    ? `${a.libraryIcons.length} library icon(s) detected (${libList}${a.libraryIcons.length > 24 ? ", …" : ""}). Import each from the project's icon package (e.g. \`${a.libraryIcons[0].pkg}\`) — see \`assets.md\`. Do NOT redraw glyphs as inline SVG/paths.`
+    : "No known-library icons auto-detected; check `assets.md` for custom SVGs.";
+  const customLine = a.customIcons.length
+    ? ` ${a.customIcons.length} custom (non-library) icon(s) appear as placeholder boxes — export/supply those assets yourself.`
+    : "";
+  const imageLine = a.images.length
+    ? `${a.images.length} image(s) downloaded to \`assets/\` — reference them (\`<img>\`/background); do not re-create.`
+    : "No raster images detected for this screen.";
+
+  return `# Figma Implementation Task
+
+You are implementing a read-only Figma design in an existing frontend project.
+
+## Source files
+
+Use these files from this folder:
+
+- \`reference.png\` — visual truth exported from Figma
+- \`index.html\` — absolute-positioned pixel preview draft
+- \`styles.css\` — CSS generated from Figma node bounds/styles
+- \`inventory.md\` — complete element checklist
+- \`spec.json\` — structured element data (elements with \`isInstance:true\` are shared components — reuse, do not rebuild)
+- \`component-library.md\` — shared components for this screen/board (build once, reuse). Present only when instances exist.
+- \`assets.md\` — icons (library imports + custom SVGs) and images for this screen
+- \`figma-node.json\` — original Figma node response
+- \`visual-test.spec.ts\` — optional Playwright test template
+
+## Figma frame
+
+- Name: ${rootNode.name}
+- Node ID: ${rootNode.id}
+
+## Icons, images & reuse
+
+- Icons: ${iconLine}${customLine}
+- Images: ${imageLine}
+- Reuse: elements with \`isInstance:true\` in \`spec.json\` (and \`component-library.md\`) are SHARED design-system components — implement each ONCE as a reusable component and import it on every screen. Do NOT re-code shared chrome (left nav/sidebar, header, breadcrumb, toolbar) per screen; build it once and reuse. Prefer the project's existing components over new primitives.
+
+## Hard rules
+
+1. Do not redesign the screen.
+2. Do not simplify the UI.
+3. Do not skip visible elements.
+4. Before coding, read \`inventory.md\`.
+5. Every visible element in \`inventory.md\` must be represented in JSX/CSS or explicitly listed as intentionally omitted.
+6. Use \`reference.png\` as the visual source of truth.
+7. Use \`index.html\` only as a layout/positioning reference, not as production code.
+8. Convert absolute positioning to semantic flex/grid where possible, but preserve the visual composition. When an element in \`spec.json\` has a \`layout\` block (parsed Figma Auto Layout), implement it with exactly those flex properties (\`layout.css\` is ready to paste) instead of guessing from coordinates; honor \`layoutChild\` (FILL→flex:1/stretch, HUG→fit-content, FIXED→px) and \`constraints\` for responsive pin/stretch.
+9. Do not create duplicate primitive components if the project already has Button, Card, Badge, Input, Modal, Container, etc. Elements marked \`isInstance\` in \`spec.json\` (or listed in \`component-library.md\`) are shared Figma components — implement each as ONE reusable component and reuse it; never copy-paste the same markup per screen.
+10. Do not refactor unrelated files.
+11. Work section by section.
+12. Add a stable selector to the implemented root element, for example: \`data-figma-screen="${rootNode.id}"\`.
+13. The element carrying that selector MUST render at the exact frame size in \`spec.json\` (\`frame.width\` × \`frame.height\`) when captured. If your layout is responsive, set the capture container to that fixed width — otherwise the visual diff compares mismatched sizes and is meaningless.
+14. After coding, run visual comparison with \`figma-pixel-kit compare\`.
+15. If visual diff is above threshold, fix spacing, typography, dimensions, colors and missing elements only.
+16. Preview artifacts (\`index.html\`, \`debug-render.html\`, \`styles.css\`) are references for you — do NOT import or ship them. (\`assets/\` IS shippable: real images and custom icon SVGs live there.)
+17. Icons: for every icon in \`assets.md\` "Library icons", import the named component from the project's icon package (map to the project's equivalent package if it differs) — never hand-draw it as inline SVG. "Custom icons" are NOT downloaded (they show as placeholder boxes) — export them from Figma and reference under \`assets/\`.
+18. Images: reference files from \`assets/\` (do not re-create or inline base64).
+19. Reuse: build each shared component (especially left nav/sidebar, header, breadcrumb, toolbar) ONCE and import it on every screen — never re-code shared chrome per screen.
+20. After coding, produce a checklist table:
+
+| Figma element | Implemented? | File/component | Notes |
+|---|---:|---|---|
+
+## Visual QA command
+
+After the page is implemented and your dev server is running, run:
+
+\`\`\`bash
+figma-pixel-kit compare "<this-output-folder>" --url "http://localhost:3000" --selector "[data-figma-screen='${rootNode.id}']"
+\`\`\`
+
+If the implementation is page-level and no selector is available yet, run without \`--selector\`.
+Text-heavy screen failing only on font rendering? Add \`--ignore-text\` to focus the diff on layout/color/spacing.
+
+## Task
+
+Implement this screen/section in the existing project using the project stack and components.
+`;
+}
+
+function buildVisualTest(rootNode, outDirName, scale = REFERENCE_SCALE) {
+  const rootBounds = getNodeBounds(rootNode);
+  const width = Math.round(rootBounds.width);
+  const height = Math.round(rootBounds.height);
+  const selector = `[data-figma-screen='${rootNode.id}']`;
+
+  return `import { test, expect } from "@playwright/test";
+
+// ⚠ WHAT THIS TEST DOES — READ BEFORE TRUSTING IT
+// This is a SELF-baseline regression test. Playwright's toHaveScreenshot() captures the page
+// on the FIRST run, stores it under its own __snapshots__ folder, and on later runs compares
+// against THAT self-made image — NOT against the Figma reference.png in this folder.
+//
+// => Passing here means "the page has not changed since the first run".
+// => It does NOT mean "the page matches the Figma design".
+//
+// For real Figma validation (diff against reference.png), use the CLI instead:
+//   figma-pixel-kit compare "${outDirName}" --url "http://localhost:3000" --selector "${selector}"
+//
+// The viewport + deviceScaleFactor below match the reference export scale so, if you DO replace the
+// generated baseline with reference.png, the pixel dimensions line up.
+
+test.use({
+  viewport: { width: ${width}, height: ${height} },
+  deviceScaleFactor: ${scale}
+});
+
+test("${rootNode.name} self-baseline regression", async ({ page }) => {
+  await page.goto("http://localhost:3000");
+  // "load" avoids hangs on dev servers with long-lived sockets (HMR); switch to "networkidle" if needed.
+  await page.waitForLoadState("load");
+
+  const target = page.locator(${JSON.stringify(selector)});
+
+  await expect(target).toHaveScreenshot("${outDirName}.png", {
+    threshold: 0.12,
+    maxDiffPixelRatio: 0.03,
+    animations: "disabled"
+  });
+});
+`;
+}
+
+function findDirByName(baseDir, name, depth = 4) {
+  // Breadth-limited recursive search for a directory named `name` under baseDir.
+  const matches = [];
+  const walk = (dir, remaining) => {
+    if (remaining < 0) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.name === name) matches.push(full);
+      else walk(full, remaining - 1);
+    }
+  };
+  walk(baseDir, depth);
+  return matches;
+}
+
+function resolveOutputDir(input) {
+  if (!input) throw new Error("Missing output folder/screen id.");
+
+  const direct = path.resolve(ROOT, input);
+  if (existsSync(direct) && statSync(direct).isDirectory()) return direct;
+
+  const underDesignAi = path.resolve(ROOT, "design-ai", input);
+  if (existsSync(underDesignAi) && statSync(underDesignAi).isDirectory()) return underDesignAi;
+
+  // Board screens live at design-ai/<board>/screens/<slug>; resolve by bare slug too.
+  const designAiRoot = path.resolve(ROOT, "design-ai");
+  if (existsSync(designAiRoot)) {
+    const matches = findDirByName(designAiRoot, path.basename(input));
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1) {
+      throw new Error(`Ambiguous screen id "${input}" matches multiple folders:\n${matches.map((m) => `  ${path.relative(ROOT, m)}`).join("\n")}\nPass the full design-ai-relative path instead.`);
+    }
+  }
+
+  throw new Error(`Output folder not found: ${input}`);
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await readFile(filePath, "utf8"));
+}
+
+async function readPng(filePath) {
+  const buffer = await readFile(filePath);
+  return PNG.sync.read(buffer);
+}
+
+async function writePng(filePath, png) {
+  await writeFile(filePath, PNG.sync.write(png));
+}
+
+function normalizePng(source, width, height, background = { r: 255, g: 255, b: 255, a: 255 }) {
+  const target = new PNG({ width, height });
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const idx = (width * y + x) << 2;
+      target.data[idx] = background.r;
+      target.data[idx + 1] = background.g;
+      target.data[idx + 2] = background.b;
+      target.data[idx + 3] = background.a;
+    }
+  }
+
+  const copyWidth = Math.min(width, source.width);
+  const copyHeight = Math.min(height, source.height);
+
+  for (let y = 0; y < copyHeight; y++) {
+    for (let x = 0; x < copyWidth; x++) {
+      const sourceIdx = (source.width * y + x) << 2;
+      const targetIdx = (width * y + x) << 2;
+      target.data[targetIdx] = source.data[sourceIdx];
+      target.data[targetIdx + 1] = source.data[sourceIdx + 1];
+      target.data[targetIdx + 2] = source.data[sourceIdx + 2];
+      target.data[targetIdx + 3] = source.data[sourceIdx + 3];
+    }
+  }
+
+  return target;
+}
+
+// Paint the given rectangles a uniform color in-place (used by --ignore-text to neutralize
+// text regions identically in both images so font rendering differences don't count as diff).
+function maskRegions(png, rects, color = { r: 128, g: 128, b: 128, a: 255 }) {
+  for (const rect of rects) {
+    const x0 = Math.max(0, Math.floor(rect.x));
+    const y0 = Math.max(0, Math.floor(rect.y));
+    const x1 = Math.min(png.width, Math.ceil(rect.x + rect.width));
+    const y1 = Math.min(png.height, Math.ceil(rect.y + rect.height));
+    for (let y = y0; y < y1; y++) {
+      for (let x = x0; x < x1; x++) {
+        const idx = (png.width * y + x) << 2;
+        png.data[idx] = color.r;
+        png.data[idx + 1] = color.g;
+        png.data[idx + 2] = color.b;
+        png.data[idx + 3] = color.a;
+      }
+    }
+  }
+  return png;
+}
+
+// Text element bounds (logical px) scaled into the device-px space of the compared rasters.
+function textMaskRects(spec, scale) {
+  return (spec.elements || [])
+    .filter((e) => (e.kind === "text" || e.type === "TEXT") && e.bounds)
+    .map((e) => ({
+      x: e.bounds.x * scale,
+      y: e.bounds.y * scale,
+      width: e.bounds.width * scale,
+      height: e.bounds.height * scale
+    }));
+}
+
+function detectHotspots(diffPng, gridColumns = 4, gridRows = 4, scale = 1) {
+  const cells = [];
+  const cellWidth = Math.ceil(diffPng.width / gridColumns);
+  const cellHeight = Math.ceil(diffPng.height / gridRows);
+
+  for (let row = 0; row < gridRows; row++) {
+    for (let col = 0; col < gridColumns; col++) {
+      cells.push({
+        row,
+        col,
+        x: col * cellWidth,
+        y: row * cellHeight,
+        width: Math.min(cellWidth, diffPng.width - col * cellWidth),
+        height: Math.min(cellHeight, diffPng.height - row * cellHeight),
+        diffPixels: 0
+      });
+    }
+  }
+
+  for (let y = 0; y < diffPng.height; y++) {
+    for (let x = 0; x < diffPng.width; x++) {
+      const idx = (diffPng.width * y + x) << 2;
+      const r = diffPng.data[idx];
+      const g = diffPng.data[idx + 1];
+      const b = diffPng.data[idx + 2];
+      const a = diffPng.data[idx + 3];
+
+      // Pixelmatch writes diff pixels as colored values. Treat non-white opaque pixels as hotspots.
+      const isDifferent = a > 0 && !(r > 245 && g > 245 && b > 245);
+      if (!isDifferent) continue;
+
+      const col = Math.min(gridColumns - 1, Math.floor(x / cellWidth));
+      const row = Math.min(gridRows - 1, Math.floor(y / cellHeight));
+      cells[row * gridColumns + col].diffPixels++;
+    }
+  }
+
+  const s = scale > 0 ? scale : 1;
+  return cells
+    .filter((cell) => cell.diffPixels > 0)
+    .sort((a, b) => b.diffPixels - a.diffPixels)
+    .slice(0, 8)
+    // Report coordinates in logical/design px (divide out the reference scale) so they map to CSS.
+    .map((cell) => ({
+      x: Math.round(cell.x / s),
+      y: Math.round(cell.y / s),
+      width: Math.round(cell.width / s),
+      height: Math.round(cell.height / s),
+      diffPixels: cell.diffPixels
+    }));
+}
+
+function buildFixPrompt({ report, outputDir }) {
+  const hotspots = report.hotspots.length
+    ? report.hotspots.map((spot, index) => `${index + 1}. x=${spot.x}, y=${spot.y}, width=${spot.width}, height=${spot.height}, diffPixels=${spot.diffPixels}`).join("\n")
+    : "No major hotspot detected.";
+
+  return `# Visual Fix Task
+
+The implementation was compared against the Figma reference.
+
+## Files
+
+- Reference: \`${path.relative(outputDir, path.join(outputDir, "visual-report", "reference.png"))}\`
+- Actual: \`${path.relative(outputDir, path.join(outputDir, "visual-report", "actual.png"))}\`
+- Diff: \`${path.relative(outputDir, path.join(outputDir, "visual-report", "diff.png"))}\`
+- Report: \`${path.relative(outputDir, path.join(outputDir, "visual-report", "report.json"))}\`
+
+## Result
+
+- Status: **${report.passed ? "PASS" : "FAIL"}**
+- Diff ratio: **${(report.diffRatio * 100).toFixed(3)}%**
+- Max allowed diff ratio: **${(report.maxDiffRatio * 100).toFixed(3)}%**
+- Diff pixels: **${report.diffPixels} / ${report.totalPixels}**
+- Reference size: **${report.reference.width} × ${report.reference.height}** px (exported at ${report.designScale ?? 1}x)
+- Actual size: **${report.actual.width} × ${report.actual.height}** px
+${report.dimensionMismatch ? "- ⚠ **Size mismatch**: reference and actual differ in pixel size. Fix this FIRST — the diff is padded with white in the non-overlapping area and the ratio is only partially meaningful. Check the captured element/selector size or root container dimensions." : ""}
+${report.ignoreText ? `- ℹ **Text ignored**: ${report.textRegionsMasked} text region(s) were masked out (\`--ignore-text\`). This diff reflects layout/color/spacing only — text content/typography is NOT validated here.` : ""}
+
+## Diff hotspots
+
+Coordinates are in logical/design px (CSS px), top-left origin.
+
+${hotspots}
+
+## Fix rules
+
+1. Fix only visual differences.
+2. Do not refactor unrelated code.
+3. Do not redesign.
+4. Do not remove elements that exist in \`inventory.md\`.
+5. Prefer small changes to spacing, sizing, typography, colors, borders, shadows and asset placement.
+6. After changes, run the same compare command again.
+7. If actual size differs from reference size, fix root container width/height or selector capture first.
+
+## Task
+
+Use \`reference.png\`, \`actual.png\`, and \`diff.png\` to reduce the visual diff below the configured threshold.
+`;
+}
+
+function numOr(value, fallback) {
+  if (value === undefined || value === true) return fallback;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+async function compareCommand(input, options) {
+  const outputDir = resolveOutputDir(input);
+  const specPath = path.join(outputDir, "spec.json");
+  const referencePath = path.join(outputDir, "reference.png");
+
+  if (!existsSync(specPath)) throw new Error(`Missing spec.json in ${outputDir}`);
+  if (!existsSync(referencePath)) throw new Error(`Missing reference.png in ${outputDir}`);
+
+  const targetUrl = options.url;
+  if (!targetUrl || targetUrl === true) {
+    throw new Error("Missing --url. Example: --url http://localhost:3000");
+  }
+
+  const spec = await readJson(specPath);
+  const width = numOr(spec.frame?.width, 1440);
+  const height = numOr(spec.frame?.height, 900);
+  // Capture at the same scale the reference.png was exported with, so pixelmatch compares like-for-like.
+  // Older specs without a scale field default to 1 (matching their 1x reference).
+  const scale = numOr(spec.frame?.scale ?? spec.visualTesting?.referenceScale, 1) || 1;
+  const selector = typeof options.selector === "string" ? options.selector : null;
+  const threshold = numOr(options.threshold ?? spec.visualTesting?.defaultThreshold, 0.12);
+  const maxDiffRatio = numOr(options["max-diff-ratio"] ?? spec.visualTesting?.defaultMaxDiffRatio, 0.03);
+  const waitMs = numOr(options.wait, 1000);
+  const fullPage = Boolean(options["full-page"]);
+  const waitUntil = typeof options["wait-until"] === "string" ? options["wait-until"] : "load";
+  const ignoreText = Boolean(options["ignore-text"]);
+
+  const reportDir = path.join(outputDir, "visual-report");
+  await mkdir(reportDir, { recursive: true });
+
+  const actualPath = path.join(reportDir, "actual.png");
+  const reportReferencePath = path.join(reportDir, "reference.png");
+  const diffPath = path.join(reportDir, "diff.png");
+  const reportPath = path.join(reportDir, "report.json");
+  const fixPromptPath = path.join(reportDir, "fix-prompt.md");
+
+  console.log(`Opening ${targetUrl}`);
+  console.log(`Viewport: ${width} × ${height} @ ${scale}x (capture ${width * scale} × ${height * scale}px)`);
+  if (selector) console.log(`Capturing selector: ${selector}`);
+
+  let browser;
+  try {
+    browser = await chromium.launch({ headless: true });
+  } catch (launchError) {
+    throw new Error(`Could not launch Chromium: ${launchError.message}\nInstall the browser once with: npm run install:browsers (or: npx playwright install chromium)`);
+  }
+
+  try {
+    const page = await browser.newPage({
+      viewport: { width, height },
+      deviceScaleFactor: scale
+    });
+
+    try {
+      await page.goto(targetUrl, { waitUntil, timeout: 30000 });
+    } catch (gotoError) {
+      // networkidle/long-lived connections (HMR sockets, polling) can stall; fall back and continue.
+      console.log(`Navigation wait "${waitUntil}" did not settle (${gotoError.message.split("\n")[0]}); continuing with current DOM.`);
+      await page.goto(targetUrl, { waitUntil: "domcontentloaded", timeout: 30000 }).catch(() => {});
+    }
+    if (waitMs > 0) await page.waitForTimeout(waitMs);
+
+    if (selector) {
+      const target = page.locator(selector).first();
+      try {
+        await target.waitFor({ state: "visible", timeout: 15000 });
+      } catch {
+        throw new Error(`Selector not found/visible: ${selector}\nMake sure the implemented root has data-figma-screen and the dev server is serving the page at ${targetUrl}.`);
+      }
+      await target.screenshot({ path: actualPath, animations: "disabled" });
+    } else {
+      await page.screenshot({ path: actualPath, fullPage, animations: "disabled" });
+    }
+  } finally {
+    await browser.close();
+  }
+
+  await copyFile(referencePath, reportReferencePath);
+
+  const reference = await readPng(referencePath);
+  const actual = await readPng(actualPath);
+  const compareWidth = Math.max(reference.width, actual.width);
+  const compareHeight = Math.max(reference.height, actual.height);
+
+  // After the scale fix the two rasters should match; flag if they still differ materially
+  // (e.g. selector element is taller/shorter than the frame), since pixelmatch then pads with white.
+  const dimMismatch = Math.abs(reference.width - actual.width) > 2 || Math.abs(reference.height - actual.height) > 2;
+  if (dimMismatch) {
+    console.log(`\n⚠  Size mismatch: reference ${reference.width}×${reference.height}px vs actual ${actual.width}×${actual.height}px.`);
+    console.log("   The diff will be padded with white in the non-overlapping area and is only partially meaningful.");
+    console.log("   Check the captured element size / selector, or pass --full-page, before trusting the ratio.");
+  }
+
+  const normalizedReference = normalizePng(reference, compareWidth, compareHeight);
+  const normalizedActual = normalizePng(actual, compareWidth, compareHeight);
+
+  // --ignore-text: neutralize text regions identically in both images so font rendering
+  // differences (the browser vs Figma's rasterizer never match exactly) don't dominate the diff.
+  // Trade-off: this also hides genuine text bugs, so it's opt-in and focuses the diff on layout/color/spacing.
+  let textMasked = 0;
+  if (ignoreText) {
+    const rects = textMaskRects(spec, scale);
+    maskRegions(normalizedReference, rects);
+    maskRegions(normalizedActual, rects);
+    textMasked = rects.length;
+    console.log(`Masked ${textMasked} text region(s) (--ignore-text).`);
+  }
+
+  const diff = new PNG({ width: compareWidth, height: compareHeight });
+
+  const diffPixels = pixelmatch(
+    normalizedReference.data,
+    normalizedActual.data,
+    diff.data,
+    compareWidth,
+    compareHeight,
+    { threshold }
+  );
+
+  await writePng(diffPath, diff);
+
+  const totalPixels = compareWidth * compareHeight;
+  const diffRatio = diffPixels / totalPixels;
+  const hotspots = detectHotspots(diff, 4, 4, scale);
+
+  const report = {
+    passed: diffRatio <= maxDiffRatio && !dimMismatch,
+    diffRatio,
+    maxDiffRatio,
+    diffPixels,
+    totalPixels,
+    threshold,
+    designScale: scale,
+    dimensionMismatch: dimMismatch,
+    ignoreText,
+    textRegionsMasked: textMasked,
+    reference: {
+      width: reference.width,
+      height: reference.height
+    },
+    actual: {
+      width: actual.width,
+      height: actual.height
+    },
+    compared: {
+      width: compareWidth,
+      height: compareHeight
+    },
+    selector,
+    url: targetUrl,
+    hotspots,
+    files: {
+      reference: reportReferencePath,
+      actual: actualPath,
+      diff: diffPath,
+      report: reportPath,
+      fixPrompt: fixPromptPath
+    }
+  };
+
+  await writeFile(reportPath, JSON.stringify(report, null, 2), "utf8");
+  await writeFile(fixPromptPath, buildFixPrompt({ report, outputDir }), "utf8");
+
+  console.log("\nVisual comparison complete.");
+  console.log(`Status: ${report.passed ? "PASS" : "FAIL"}`);
+  console.log(`Diff:   ${(diffRatio * 100).toFixed(3)}% (${diffPixels}/${totalPixels})`);
+  console.log(`Report: ${reportPath}`);
+  console.log(`Diff:   ${diffPath}`);
+  console.log(`Fix:    ${fixPromptPath}`);
+
+  if (!report.passed) {
+    process.exitCode = 1;
+  }
+}
+
+
+function slugifyName(value = "screen") {
+  return String(value)
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/ı/g, "i")
+    .replace(/İ/g, "i")
+    .replace(/ş/g, "s")
+    .replace(/Ş/g, "s")
+    .replace(/ğ/g, "g")
+    .replace(/Ğ/g, "g")
+    .replace(/ü/g, "u")
+    .replace(/Ü/g, "u")
+    .replace(/ö/g, "o")
+    .replace(/Ö/g, "o")
+    .replace(/ç/g, "c")
+    .replace(/Ç/g, "c")
+    .replace(/[^a-z0-9-_]+/gi, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase() || "screen";
+}
+
+function countDescendants(node) {
+  if (!node?.children?.length) return 0;
+  return node.children.reduce((total, child) => total + 1 + countDescendants(child), 0);
+}
+
+function isLikelyScreen(node, options = {}) {
+  const bounds = getNodeBounds(node);
+  if (!bounds) return false;
+
+  const targetWidth = Number(options.screenWidth || 1440);
+  const tolerance = Number(options.widthTolerance || 12);
+  const minHeight = Number(options.minHeight || 500);
+  const maxHeight = Number(options.maxHeight || 4000);
+
+  if (node.type !== "FRAME") return false;
+  if (Math.abs(bounds.width - targetWidth) > tolerance) return false;
+  if (bounds.height < minHeight || bounds.height > maxHeight) return false;
+
+  return true;
+}
+
+function detectScreens(rootNode, options = {}) {
+  const allNodes = flattenNodes(rootNode);
+  const screenCandidates = [];
+
+  for (const node of allNodes) {
+    if (!isLikelyScreen(node, options)) continue;
+    const bounds = getNodeBounds(node);
+    const descendantCount = countDescendants(node);
+
+    // Skip empty wrappers unless root itself is the only candidate.
+    if (descendantCount < 3 && node.id !== rootNode.id) continue;
+
+    screenCandidates.push({
+      id: node.id,
+      name: node.name,
+      type: node.type,
+      width: Math.round(bounds.width),
+      height: Math.round(bounds.height),
+      x: Math.round(bounds.x),
+      y: Math.round(bounds.y),
+      descendants: descendantCount
+    });
+  }
+
+  // If the selected node itself is a screen and there are no nested screens, keep it as single screen.
+  // If it is a board containing many screens, remove the board/root from the list when there are nested screens.
+  const nested = screenCandidates.filter((candidate) => candidate.id !== rootNode.id);
+  const chosen = nested.length ? nested : screenCandidates;
+
+  return chosen
+    .sort((a, b) => a.y - b.y || a.x - b.x)
+    .map((screen, index) => ({
+      ...screen,
+      index: index + 1,
+      slug: `${String(index + 1).padStart(2, "0")}-${slugifyName(screen.name)}-${screen.id.replaceAll(":", "-")}`
+    }));
+}
+
+function pascalCase(name = "") {
+  return String(name)
+    .split("/").map((s) => s.trim()).filter(Boolean).join(" ") // flatten "Group/Button" paths
+    .replace(/=.*$/, "")                                        // drop variant value "State=Hover" -> "State"
+    .normalize("NFKD").replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/gi, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("") || "Component";
+}
+
+function collectInstances(rootNode) {
+  return flattenNodes(rootNode).filter((node) => node.type === "INSTANCE" && node.componentId);
+}
+
+// Builds a map of nodeId -> screen for every node inside each detected screen subtree,
+// so we can tell which screens a given component instance appears in.
+function buildScreenMembership(rootNode, screens) {
+  const idToNode = new Map(flattenNodes(rootNode).map((node) => [node.id, node]));
+  const membership = new Map();
+  for (const screen of screens) {
+    const screenNode = idToNode.get(screen.id);
+    if (!screenNode) continue;
+    for (const node of flattenNodes(screenNode)) {
+      if (!membership.has(node.id)) membership.set(node.id, screen);
+    }
+  }
+  return membership;
+}
+
+function camelProp(name) {
+  const parts = String(name).replace(/[^a-z0-9]+/gi, " ").trim().split(/\s+/).filter(Boolean);
+  if (!parts.length) return "prop";
+  return parts.map((w, i) => (i === 0 ? w.toLowerCase() : w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())).join("");
+}
+
+// Turn variant names ("Type=Primary, Size=sm") + non-variant component properties into a structured
+// prop API: enum axes, booleans, text and instance-swap slots.
+function buildPropSchema(variants, propTypes = new Map()) {
+  const axes = {};
+  for (const v of variants) {
+    for (const part of String(v.name || "").split(",")) {
+      const eq = part.indexOf("=");
+      if (eq === -1) continue;
+      const key = part.slice(0, eq).trim();
+      const val = part.slice(eq + 1).trim();
+      if (key && val) (axes[key] ||= new Set()).add(val);
+    }
+  }
+  const props = [];
+  const seen = new Set();
+  for (const [key, set] of Object.entries(axes)) {
+    const vals = [...set];
+    const isBool = vals.length > 0 && vals.every((x) => /^(true|false|yes|no|on|off)$/i.test(x));
+    const cp = camelProp(key);
+    seen.add(cp);
+    props.push(isBool ? { name: cp, figmaName: key, type: "boolean" } : { name: cp, figmaName: key, type: "enum", values: vals });
+  }
+  for (const [name, t] of propTypes) {
+    if (t === "VARIANT") continue; // covered by axes above
+    const cp = camelProp(name);
+    if (seen.has(cp)) continue;
+    seen.add(cp);
+    props.push({ name: cp, figmaName: name, type: t === "BOOLEAN" ? "boolean" : t === "INSTANCE_SWAP" ? "slot" : "string" });
+  }
+  return props;
+}
+
+function propsToTs(componentName, props) {
+  if (!props.length) return "";
+  const body = props.map((p) => {
+    const t = p.type === "enum" ? p.values.map((v) => JSON.stringify(v)).join(" | ")
+      : p.type === "boolean" ? "boolean"
+      : p.type === "slot" ? "React.ReactNode"
+      : "string";
+    return `  ${p.name}: ${t};`;
+  }).join("\n");
+  return `type ${componentName}Props = {\n${body}\n}`;
+}
+
+// Structural fingerprint of a container: type + rounded size + child count + sorted child types.
+// Two nodes with the same signature are very likely copy-pasted duplicates of the same UI block.
+function nodeSignature(node) {
+  const b = getNodeBounds(node);
+  const w = b ? Math.round(b.width) : 0;
+  const h = b ? Math.round(b.height) : 0;
+  const childTypes = Array.isArray(node.children) ? node.children.map((c) => c.type).sort().join(",") : "";
+  const childCount = node.children?.length || 0;
+  return `${node.type}|${w}x${h}|n${childCount}|[${childTypes}]`;
+}
+
+// Heuristic: find repeated identical container subtrees that are NOT Figma components/instances
+// (i.e. copy-pasted groups). These are componentization candidates the instance-based library can't see.
+function detectRepeatedPatterns(rootNode, { minCount = 3, minChildren = 2 } = {}) {
+  const groups = new Map();
+  for (const node of flattenNodes(rootNode)) {
+    if (node.id === rootNode.id) continue;
+    if (!["FRAME", "GROUP"].includes(node.type)) continue; // skip INSTANCE/COMPONENT (already detected) and leaves
+    const childCount = node.children?.length || 0;
+    if (childCount < minChildren) continue;
+    const b = getNodeBounds(node);
+    if (!b || b.width < 8 || b.height < 8) continue;
+    const sig = nodeSignature(node);
+    if (!groups.has(sig)) groups.set(sig, { count: 0, sample: node, names: new Set() });
+    const g = groups.get(sig);
+    g.count++;
+    g.names.add(node.name);
+  }
+  return [...groups.values()]
+    .filter((g) => g.count >= minCount)
+    .map((g) => {
+      const b = getNodeBounds(g.sample);
+      return {
+        count: g.count,
+        sampleName: g.sample.name,
+        suggestedComponentName: pascalCase([...g.names][0] || g.sample.name),
+        type: g.sample.type,
+        childCount: g.sample.children?.length || 0,
+        size: b ? { width: Math.round(b.width), height: Math.round(b.height) } : null,
+        names: [...g.names].slice(0, 5)
+      };
+    })
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 15);
+}
+
+// Groups component instances across all screens by their underlying component (or variant set),
+// so the implementer can build each shared component once and reuse it everywhere.
+function extractComponentLibrary({ rootNode, componentsMeta = {}, componentSetsMeta = {}, screens = [] }) {
+  const instances = collectInstances(rootNode);
+  const membership = screens.length ? buildScreenMembership(rootNode, screens) : new Map();
+
+  const families = new Map();
+  const componentNameById = {};
+
+  for (const inst of instances) {
+    const meta = componentsMeta[inst.componentId] || {};
+    const setId = meta.componentSetId || null;
+    const setMeta = setId ? componentSetsMeta[setId] : null;
+    const displayName = setMeta?.name || meta.name || inst.name;
+    componentNameById[inst.componentId] = displayName;
+
+    // Variants of one COMPONENT_SET collapse into a single family with a `variant` prop.
+    const familyKey = setId || inst.componentId;
+    if (!families.has(familyKey)) {
+      families.set(familyKey, {
+        name: displayName,
+        suggestedComponentName: pascalCase(displayName),
+        isVariantSet: Boolean(setId),
+        description: setMeta?.description || meta.description || "",
+        usageCount: 0,
+        screens: new Set(),
+        variants: new Map(),
+        propTypes: new Map(),
+        sampleBounds: null
+      });
+    }
+
+    const family = families.get(familyKey);
+    family.usageCount++;
+    const variantName = meta.name || inst.name;
+    const variant = family.variants.get(inst.componentId) || { name: variantName, count: 0 };
+    variant.count++;
+    family.variants.set(inst.componentId, variant);
+
+    const screen = membership.get(inst.id);
+    if (screen) family.screens.add(screen.name);
+
+    if (!family.sampleBounds) {
+      const b = getNodeBounds(inst);
+      if (b) family.sampleBounds = { width: Math.round(b.width), height: Math.round(b.height) };
+    }
+
+    for (const [propKey, propVal] of Object.entries(inst.componentProperties || {})) {
+      const name = propKey.replace(/#\d+.*$/, ""); // strip Figma's internal "#123:456" suffix
+      family.propTypes.set(name, propVal?.type || "TEXT");
+    }
+  }
+
+  const list = [...families.values()]
+    .map((family) => {
+      const variants = [...family.variants.values()].sort((a, b) => b.count - a.count);
+      const propSchema = buildPropSchema(variants, family.propTypes);
+      return {
+        name: family.name,
+        suggestedComponentName: family.suggestedComponentName,
+        isVariantSet: family.isVariantSet,
+        description: family.description,
+        usageCount: family.usageCount,
+        screenCount: family.screens.size,
+        screens: [...family.screens],
+        variants,
+        props: propSchema.map((p) => p.name),
+        propSchema,
+        propsType: propsToTs(family.suggestedComponentName, propSchema),
+        sampleBounds: family.sampleBounds
+      };
+    })
+    .sort((a, b) => b.usageCount - a.usageCount || b.screenCount - a.screenCount);
+
+  const repeatedPatterns = detectRepeatedPatterns(rootNode);
+
+  return { list, componentNameById, totalInstances: instances.length, repeatedPatterns };
+}
+
+function buildComponentLibraryMarkdown(library, { title = "Shared Component Library", scope = "" } = {}) {
+  const lines = [];
+  const repeated = library.repeatedPatterns || [];
+  lines.push(`# ${title}`, "");
+  if (scope) lines.push(scope, "");
+
+  if (library.list.length) {
+    const reusedAcrossScreens = library.list.filter((c) => c.screenCount >= 2);
+    const reusedMultiple = library.list.filter((c) => c.usageCount >= 2);
+
+    lines.push(`Total instances: **${library.totalInstances}** across **${library.list.length}** distinct components.`);
+    lines.push(`Reused on 2+ screens: **${reusedAcrossScreens.length}** · Used 2+ times: **${reusedMultiple.length}**`, "");
+    lines.push("## Reuse rule", "");
+    lines.push("Build each component below **once** as a reusable component in the project, then import it in every screen.");
+    lines.push("Do not re-implement these per screen. Variant sets become a single component with a `variant` prop.", "");
+
+    lines.push("## Components (by usage)", "");
+    lines.push("| Suggested name | Figma name | Uses | Screens | Variants | Props | Sample size |");
+    lines.push("|---|---|---:|---:|---|---|---|");
+    for (const c of library.list) {
+      const variants = c.isVariantSet ? c.variants.map((v) => `${v.name}×${v.count}`).join(", ") : "—";
+      const props = c.props.length ? c.props.join(", ") : "—";
+      const size = c.sampleBounds ? `${c.sampleBounds.width}×${c.sampleBounds.height}` : "—";
+      lines.push(`| \`${c.suggestedComponentName}\` | ${c.name} | ${c.usageCount} | ${c.screenCount || "—"} | ${variants} | ${props} | ${size} |`);
+    }
+    lines.push("");
+
+    lines.push("## Suggested build order", "");
+    lines.push("Highest reuse first — these save the most duplicate code:", "");
+    for (const c of library.list.slice(0, 20)) {
+      const where = c.screens.length ? ` (screens: ${c.screens.join(", ")})` : "";
+      lines.push(`- \`${c.suggestedComponentName}\` — used ${c.usageCount}×${where}`);
+    }
+    lines.push("");
+
+    // Variant Mapping → a ready prop API per component, so the AI builds the right interface once.
+    const withProps = library.list.filter((c) => c.propSchema && c.propSchema.length);
+    if (withProps.length) {
+      lines.push("## Component prop APIs (from Figma variants & properties)", "");
+      lines.push("Suggested prop interface for each component. Enums come from variant axes; booleans/text/slots from component properties.", "");
+      for (const c of withProps.slice(0, 30)) {
+        lines.push("```ts");
+        lines.push(c.propsType);
+        lines.push("```");
+      }
+      lines.push("");
+    }
+  } else {
+    lines.push("No Figma component instances detected in this selection.", "");
+  }
+
+  // Heuristic section: copy-pasted (non-component) blocks that repeat — strong componentization candidates.
+  if (repeated.length) {
+    lines.push("## Repeated patterns (heuristic — not Figma components)", "");
+    lines.push("These identical-looking blocks are **not** Figma components but repeat in the design (likely copy-pasted).");
+    lines.push("Strongly consider building each as a reusable component instead of duplicating markup:", "");
+    lines.push("| Suggested name | Repeats | Type | Children | Size |");
+    lines.push("|---|---:|---|---:|---|");
+    for (const p of repeated) {
+      const size = p.size ? `${p.size.width}×${p.size.height}` : "—";
+      lines.push(`| \`${p.suggestedComponentName}\` | ${p.count} | ${p.type} | ${p.childCount} | ${size} |`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function detectComponents(rootNode, screens = []) {
+  const screenIds = new Set(screens.map((screen) => screen.id));
+  const allNodes = flattenNodes(rootNode);
+  const components = [];
+
+  for (const node of allNodes) {
+    if (screenIds.has(node.id)) continue;
+    const bounds = getNodeBounds(node);
+    if (!bounds) continue;
+
+    if (["COMPONENT", "COMPONENT_SET", "INSTANCE"].includes(node.type)) {
+      components.push({
+        id: node.id,
+        name: node.name,
+        type: node.type,
+        width: Math.round(bounds.width),
+        height: Math.round(bounds.height),
+        x: Math.round(bounds.x),
+        y: Math.round(bounds.y)
+      });
+    }
+  }
+
+  return components.sort((a, b) => a.y - b.y || a.x - b.x);
+}
+
+function buildBoardMarkdown({ rootNode, source, screens, components }) {
+  const rootBounds = getNodeBounds(rootNode);
+  const lines = [];
+  lines.push("# Figma Board Analysis", "");
+  lines.push(`Board: **${rootNode.name}**`);
+  lines.push(`Node ID: \`${rootNode.id}\``);
+  if (rootBounds) lines.push(`Size: **${Math.round(rootBounds.width)} × ${Math.round(rootBounds.height)}**`);
+  lines.push(`Source: ${source.figmaUrl}`, "");
+  lines.push("## Detected screens", "");
+  if (!screens.length) {
+    lines.push("No screens detected at the configured width (see `board-analysis.json` → detection; try `--mobile` or `--screen-width`).");
+  } else {
+    lines.push("| # | Name | Node ID | Size | Descendants | Output folder |");
+    lines.push("|---:|---|---|---:|---:|---|");
+    for (const screen of screens) {
+      lines.push(`| ${screen.index} | ${screen.name} | \`${screen.id}\` | ${screen.width}×${screen.height} | ${screen.descendants} | \`${screen.slug}\` |`);
+    }
+  }
+  lines.push("", "## Detected components / instances", "");
+  const maxComponents = 120;
+  if (!components.length) {
+    lines.push("No component-like nodes detected.");
+  } else {
+    lines.push(`Showing first ${Math.min(maxComponents, components.length)} of ${components.length}.`);
+    lines.push("");
+    lines.push("| # | Name | Type | Node ID | Size |");
+    lines.push("|---:|---|---|---|---:|");
+    for (const [index, component] of components.slice(0, maxComponents).entries()) {
+      lines.push(`| ${index + 1} | ${component.name} | ${component.type} | \`${component.id}\` | ${component.width}×${component.height} |`);
+    }
+  }
+  lines.push("");
+  lines.push("## Implementation strategy", "");
+  lines.push("Do not implement the full board as one screen.");
+  lines.push("Implement screens one by one using each generated `prompt-for-claude.md`.");
+  lines.push("Use shared components/instances as a design-system reference, not as standalone pages.");
+  return lines.join("\n");
+}
+
+async function exportScreenFromNode({
+  figmaUrl, source, rootNode, nodeResponse, outDir, outDirName,
+  isImplementMode = false, componentNameById = {}, imageFillUrls = null, componentLibrary = null,
+  scale = REFERENCE_SCALE, referenceImageUrl = null, iconCache = new Map()
+}) {
+  await mkdir(outDir, { recursive: true });
+  await writeFile(path.join(outDir, "figma-node.json"), JSON.stringify(nodeResponse, null, 2), "utf8");
+
+  // Board exports pre-render all screens in one batch call and pass referenceImageUrl in.
+  // Single-node exports render here.
+  let renderedUrl = referenceImageUrl;
+  if (!renderedUrl) {
+    const imageUrl = new URL(`https://api.figma.com/v1/images/${source.fileKey}`);
+    imageUrl.searchParams.set("ids", source.nodeId);
+    imageUrl.searchParams.set("format", "png");
+    imageUrl.searchParams.set("scale", String(scale));
+    imageUrl.searchParams.set("use_absolute_bounds", "true");
+
+    console.log(`Exporting reference PNG: ${rootNode.name}`);
+    const imageResponse = await figmaFetch(imageUrl.toString(), source.token);
+    if (imageResponse.err) {
+      throw new Error(`Figma image render failed: ${imageResponse.err}`);
+    }
+    renderedUrl = imageResponse.images?.[source.nodeId];
+    if (!renderedUrl) {
+      throw new Error(`Could not render node image (no URL returned). Response: ${JSON.stringify(imageResponse, null, 2)}`);
+    }
+  } else {
+    console.log(`Exporting reference PNG: ${rootNode.name}`);
+  }
+
+  await downloadFile(renderedUrl, path.join(outDir, "reference.png"));
+
+  const allNodes = flattenNodes(rootNode);
+  const boundedNodes = allNodes.filter((node) => getNodeBounds(node));
+
+  // Download image fills used in this screen so the debug renderer can show real images.
+  const imageRefMap = {};
+  const usedRefs = [...new Set(boundedNodes.map((node) => firstImageFill(node)?.imageRef).filter(Boolean))];
+  if (usedRefs.length && imageFillUrls) {
+    const assetsDir = path.join(outDir, "assets");
+    await mkdir(assetsDir, { recursive: true });
+    for (const ref of usedRefs) {
+      const remote = imageFillUrls[ref];
+      if (!remote) continue;
+      try {
+        const localName = `${ref.replace(/[^a-z0-9]/gi, "_")}.png`;
+        await downloadFile(remote, path.join(assetsDir, localName));
+        imageRefMap[ref] = `./assets/${localName}`;
+      } catch {
+        // best-effort: a missing image fill should not fail the export
+      }
+    }
+  }
+
+  // Classify assets (library icons / custom icons / images) for assets.md + spec.
+  // NO SVG downloads: library icons are rendered live from the icon library's CDN in the
+  // debug preview; custom/unknown vectors stay as boxes (their own fill color) for you to supply.
+  let assetManifest = { libraryIcons: [], customIcons: [], images: [] };
+  const nodeIconMap = {}; // nodeId -> { set, name } for library icon roots (e.g. lucide chevron-right)
+  try {
+    assetManifest = collectScreenAssets(rootNode, boundedNodes, componentNameById, imageRefMap);
+    for (const node of boundedNodes) {
+      if (!isIconRoot(node, componentNameById)) continue;
+      const name = (node.componentId && componentNameById[node.componentId]) || node.name || "";
+      const lib = detectIconLibrary(name);
+      if (lib) nodeIconMap[node.id] = { set: lib.set, name: lib.iconName };
+    }
+    if (assetManifest.libraryIcons.length || assetManifest.customIcons.length || assetManifest.images.length) {
+      console.log(`Assets: ${assetManifest.libraryIcons.length} library icon(s) (rendered via CDN), ${assetManifest.customIcons.length} custom icon box(es), ${assetManifest.images.length} image(s).`);
+    }
+  } catch (e) {
+    console.log(`Note: asset/icon resolution skipped (${(e.message || String(e)).split("\n")[0]}).`);
+  }
+
+  const spec = buildSpecJson(rootNode, boundedNodes, {
+    figmaUrl,
+    fileKey: source.fileKey,
+    nodeId: source.nodeId
+  }, componentNameById, scale);
+  spec.assets = assetManifest;
+
+  // Hover-state (hidden) icons: shown dimmed in the debug preview + listed in inventory.md.
+  let hoverIcons = [];
+  try {
+    hoverIcons = collectHiddenIconRoots(rootNode, componentNameById);
+  } catch {
+    // best-effort
+  }
+
+  await writeFile(path.join(outDir, "spec.json"), JSON.stringify(spec, null, 2), "utf8");
+  await writeFile(path.join(outDir, "assets.md"), buildAssetsMarkdown(assetManifest, rootNode), "utf8");
+  await writeFile(path.join(outDir, "inventory.md"), buildInventoryMarkdown(rootNode, boundedNodes, componentNameById, hoverIcons), "utf8");
+
+  const { html, css } = buildHtml(rootNode, boundedNodes, imageRefMap, nodeIconMap, hoverIcons);
+  await writeFile(path.join(outDir, "index.html"), buildReferencePreviewHtml(rootNode), "utf8");
+  await writeFile(path.join(outDir, "debug-render.html"), html, "utf8");
+  await writeFile(path.join(outDir, "styles.css"), css, "utf8");
+  await writeFile(path.join(outDir, "inspect.md"), buildInspectMarkdown(rootNode, boundedNodes, {
+    figmaUrl,
+    fileKey: source.fileKey,
+    nodeId: source.nodeId
+  }), "utf8");
+  await writeFile(path.join(outDir, "prompt-for-claude.md"), buildClaudePrompt(rootNode, assetManifest), "utf8");
+  await writeFile(path.join(outDir, "visual-test.spec.ts"), buildVisualTest(rootNode, outDirName, scale), "utf8");
+
+  // For single-node exports, write a screen-scoped component library so reuse is visible even without a board.
+  if (componentLibrary && (componentLibrary.list.length || componentLibrary.repeatedPatterns?.length)) {
+    await writeFile(path.join(outDir, "component-library.md"),
+      buildComponentLibraryMarkdown(componentLibrary, { scope: `Components used in **${rootNode.name}**.` }), "utf8");
+    await writeFile(path.join(outDir, "components.json"), JSON.stringify(componentLibrary, null, 2), "utf8");
+  }
+
+  if (isImplementMode) {
+    console.log("");
+    console.log(`Implementation handoff: ${rootNode.name}`);
+    console.log("----------------------");
+    console.log(`Prompt: ${path.join(outDir, "prompt-for-claude.md")}`);
+    console.log(`Selector: data-figma-screen="${rootNode.id}"`);
+    console.log(`Compare: figma-pixel-kit compare "${outDirName}" --url "http://localhost:3000" --selector "[data-figma-screen='${rootNode.id}']"`);
+  }
+
+  return { outDir, outDirName, rootNode };
+}
+
+async function exportSingleNodeCommand(figmaUrl, options = {}) {
+  const isImplementMode = options.mode === "implement";
+  await initCommand({ silent: true });
+
+  const token = await resolveFigmaToken();
+  if (!token) {
+    throw new Error('Missing Figma token. Run once: figma-pixel-kit token "figd_xxxxxxxxx"');
+  }
+
+  const { source, nodeResponse, rootNode, componentsMeta, componentSetsMeta } = await getFigmaRootNode(figmaUrl, token);
+  const safeNodeId = source.nodeId.replaceAll(":", "-");
+  const outDir = path.join(ROOT, "design-ai", `${source.fileName}-${safeNodeId}`);
+  const outDirName = path.basename(outDir);
+
+  const componentLibrary = extractComponentLibrary({ rootNode, componentsMeta, componentSetsMeta, screens: [] });
+  const imageFillUrls = await fetchImageFillUrls(source.fileKey, token);
+  const scale = resolveExportScale(options.scale);
+
+  const result = await exportScreenFromNode({
+    figmaUrl,
+    source: { ...source, token },
+    rootNode,
+    nodeResponse,
+    outDir,
+    outDirName,
+    isImplementMode,
+    componentNameById: componentLibrary.componentNameById,
+    componentLibrary,
+    imageFillUrls,
+    scale
+  });
+
+  if (componentLibrary.list.length) {
+    console.log(`Components: ${componentLibrary.list.length} reusable component(s) detected → ${path.join(outDir, "component-library.md")}`);
+  }
+  console.log("\nDone.");
+  console.log(`Output: ${outDir}`);
+  console.log(`Open:   ${path.join(outDir, "index.html")}`);
+  console.log(`Debug:  ${path.join(outDir, "debug-render.html")}`);
+  console.log(`Inspect:${path.join(outDir, "inspect.md")}`);
+  console.log(`Prompt: ${path.join(outDir, "prompt-for-claude.md")}`);
+  console.log(`Visual: figma-pixel-kit compare "${outDirName}" --url "http://localhost:3000" --selector "[data-figma-screen='${rootNode.id}']"`);
+
+  return result;
+}
+
+async function analyzeBoardCommand(figmaUrl, options = {}) {
+  await initCommand({ silent: true });
+
+  const token = await resolveFigmaToken();
+  if (!token) {
+    throw new Error('Missing Figma token. Run once: figma-pixel-kit token "figd_xxxxxxxxx"');
+  }
+
+  const { source, nodeResponse, rootNode, componentsMeta, componentSetsMeta } = await getFigmaRootNode(figmaUrl, token);
+  const screens = detectScreens(rootNode, options);
+  const components = detectComponents(rootNode, screens);
+  const componentLibrary = extractComponentLibrary({ rootNode, componentsMeta, componentSetsMeta, screens });
+
+  const safeNodeId = source.nodeId.replaceAll(":", "-");
+  const boardDirName = `${source.fileName}-${safeNodeId}-board`;
+  const boardDir = path.join(ROOT, "design-ai", boardDirName);
+  await mkdir(boardDir, { recursive: true });
+
+  const analysis = {
+    source: {
+      figmaUrl,
+      fileKey: source.fileKey,
+      nodeId: source.nodeId,
+      name: rootNode.name
+    },
+    detection: {
+      screenWidth: Number(options.screenWidth || 1440),
+      widthTolerance: Number(options.widthTolerance || 12),
+      minHeight: Number(options.minHeight || 500),
+      maxHeight: Number(options.maxHeight || 4000)
+    },
+    screens,
+    components
+  };
+
+  await writeFile(path.join(boardDir, "board-analysis.json"), JSON.stringify(analysis, null, 2), "utf8");
+  await writeFile(path.join(boardDir, "screens.md"), buildBoardMarkdown({ rootNode, source: { ...source, figmaUrl }, screens, components }), "utf8");
+  await writeFile(path.join(boardDir, "figma-board-node.json"), JSON.stringify(nodeResponse, null, 2), "utf8");
+  await writeFile(path.join(boardDir, "component-library.md"),
+    buildComponentLibraryMarkdown(componentLibrary, { scope: `Shared components across **${screens.length}** screen(s) in **${rootNode.name}**.` }), "utf8");
+  await writeFile(path.join(boardDir, "components.json"), JSON.stringify(componentLibrary, null, 2), "utf8");
+
+  console.log("");
+  console.log(`Detected ${screens.length} screen(s), ${components.length} component-like node(s), ${componentLibrary.list.length} reusable component(s).`);
+  console.log(`Board output: ${boardDir}`);
+  console.log(`Screens: ${path.join(boardDir, "screens.md")}`);
+  console.log(`Components: ${path.join(boardDir, "component-library.md")}`);
+
+  return { token, source, nodeResponse, rootNode, screens, components, boardDir, boardDirName, componentLibrary, componentsMeta, componentSetsMeta };
+}
+
+async function exportBoardCommand(figmaUrl, options = {}) {
+  const board = await analyzeBoardCommand(figmaUrl, options);
+
+  if (!board.screens.length) {
+    console.log("");
+    console.log("No board screens detected. Falling back to single-node export.");
+    return exportSingleNodeCommand(figmaUrl, options);
+  }
+
+  // Flatten the board once; reuse the lookup for every screen instead of re-flattening per screen.
+  const idToNode = new Map(flattenNodes(board.rootNode).map((node) => [node.id, node]));
+  const componentNameById = board.componentLibrary?.componentNameById || {};
+  const imageFillUrls = await fetchImageFillUrls(board.source.fileKey, board.token);
+  const scale = resolveExportScale(options.scale);
+
+  // Pre-render screen references in small chunks (Figma render-timeouts if too many large images
+  // are requested at once). Anything that fails here is rendered per-screen below.
+  console.log(`Pre-rendering ${board.screens.length} screen reference image(s) at ${scale}x ...`);
+  let referenceUrls = {};
+  try {
+    referenceUrls = await renderReferenceImages(board.source.fileKey, board.screens.map((s) => s.id), board.token, scale);
+  } catch (e) {
+    console.log(`Pre-render skipped (${e.message.split("\n")[0]}); rendering per-screen.`);
+  }
+
+  const outputs = [];
+  const iconCache = new Map(); // board-wide: each distinct icon SVG is rendered once, then copied.
+  for (const screen of board.screens) {
+    console.log("");
+    console.log(`Exporting screen ${screen.index}/${board.screens.length}: ${screen.name}`);
+
+    const screenUrl = figmaUrl.replace(/node-id=[^&]+/, `node-id=${screen.id.replaceAll(":", "-")}`);
+    const screenRootNode = idToNode.get(screen.id);
+
+    if (!screenRootNode) {
+      console.log(`Skipping missing screen node: ${screen.id}`);
+      continue;
+    }
+
+    const screenNodeResponse = {
+      ...board.nodeResponse,
+      nodes: { [screen.id]: { document: screenRootNode } }
+    };
+
+    const outDir = path.join(board.boardDir, "screens", screen.slug);
+    const outDirName = path.relative(path.join(ROOT, "design-ai"), outDir);
+
+    const result = await exportScreenFromNode({
+      figmaUrl: screenUrl,
+      source: { ...board.source, token: board.token, nodeId: screen.id },
+      rootNode: screenRootNode,
+      nodeResponse: screenNodeResponse,
+      outDir,
+      outDirName,
+      isImplementMode: options.mode === "implement",
+      componentNameById,
+      imageFillUrls,
+      scale,
+      referenceImageUrl: referenceUrls[screen.id] || null,
+      iconCache
+    });
+
+    outputs.push({
+      index: screen.index,
+      name: screen.name,
+      nodeId: screen.id,
+      folder: outDir,
+      prompt: path.join(outDir, "prompt-for-claude.md"),
+      selector: `[data-figma-screen='${screen.id}']`
+    });
+  }
+
+  await writeFile(path.join(board.boardDir, "implementation-plan.md"), buildImplementationPlan(outputs, board), "utf8");
+
+  console.log("");
+  console.log("Board export complete.");
+  console.log(`Implementation plan: ${path.join(board.boardDir, "implementation-plan.md")}`);
+  console.log("");
+  console.log("Next step for VS Code AI:");
+  console.log(`Read and follow: ${path.join(board.boardDir, "implementation-plan.md")}`);
+
+  return { ...board, outputs };
+}
+
+function buildImplementationPlan(outputs, board) {
+  const lines = [];
+  lines.push("# Board Implementation Plan", "");
+  lines.push(`Board: **${board.rootNode.name}**`);
+  lines.push(`Detected screens: **${outputs.length}**`, "");
+  lines.push("## Rule", "");
+  lines.push("Implement one screen at a time. Do not merge all screens into one task.");
+  lines.push("Use each screen's `reference.png`, `inventory.md`, `spec.json`, and `prompt-for-claude.md`.");
+  lines.push("");
+
+  const library = board.componentLibrary;
+  if (library && library.list.length) {
+    const buildFirst = library.list.filter((c) => c.usageCount >= 2 || c.screenCount >= 2);
+    lines.push("## Phase 0 — Build shared components first", "");
+    lines.push("These components repeat across screens. Build each **once** as a reusable component, then import it everywhere.");
+    lines.push("Full details: `component-library.md`. Each screen's `inventory.md`/`spec.json` marks where instances appear.", "");
+    if (buildFirst.length) {
+      lines.push("| Order | Component | Build as | Uses | Screens | Variants |");
+      lines.push("|---:|---|---|---:|---:|---|");
+      buildFirst.forEach((c, i) => {
+        const variants = c.isVariantSet ? c.variants.map((v) => v.name).join(", ") : "—";
+        lines.push(`| ${i + 1} | ${c.name} | \`${c.suggestedComponentName}\` | ${c.usageCount} | ${c.screenCount || "—"} | ${variants} |`);
+      });
+    } else {
+      lines.push("_No component is reused across 2+ screens; build components inline per screen as needed._");
+    }
+    lines.push("");
+    lines.push("After Phase 0, implement screens below and reuse the components above instead of re-coding them.", "");
+  }
+
+  lines.push("## Screens", "");
+  lines.push("| # | Screen | Prompt | Selector |");
+  lines.push("|---:|---|---|---|");
+  for (const output of outputs) {
+    lines.push(`| ${output.index} | ${output.name} | \`${output.prompt}\` | \`${output.selector}\` |`);
+  }
+  lines.push("");
+  lines.push("## Suggested VS Code AI workflow", "");
+  for (const output of outputs) {
+    lines.push(`### ${output.index}. ${output.name}`, "");
+    lines.push(`Read and follow: ${output.prompt}`);
+    lines.push(`After implementation, add selector: \`data-figma-screen="${output.nodeId}"\``);
+    lines.push(`Compare command:`);
+    lines.push("");
+    lines.push("```bash");
+    lines.push(`figma-pixel-kit compare "${path.relative(path.join(ROOT, "design-ai"), output.folder)}" --url "http://localhost:3000" --selector "${output.selector}"`);
+    lines.push("```", "");
+  }
+  return lines.join("\n");
+}
+
+
+
+async function exportCommand(figmaUrl, options = {}) {
+  await initCommand({ silent: true });
+
+  const token = await resolveFigmaToken();
+  if (!token) {
+    throw new Error('Missing Figma token. Run once: figma-pixel-kit token "figd_xxxxxxxxx"');
+  }
+
+  const { rootNode } = await getFigmaRootNode(figmaUrl, token);
+  const screens = detectScreens(rootNode, options);
+
+  // Primary UX: if the selected node contains multiple 1440px frames, treat it as a board.
+  if (screens.length > 1) {
+    console.log(`Auto-detected board: ${screens.length} screen(s) found.`);
+    return exportBoardCommand(figmaUrl, options);
+  }
+
+  return exportSingleNodeCommand(figmaUrl, options);
+}
+
+// Turn parsed CLI flags into screen-detection options (with the --mobile preset).
+function normalizeDetectionOptions(parsed = {}, extra = {}) {
+  const options = { ...extra };
+  if (parsed.mobile) {
+    options.screenWidth = 390;
+    options.widthTolerance = 60;
+    options.minHeight = 400;
+  }
+  if (parsed["screen-width"] !== undefined) options.screenWidth = Number(parsed["screen-width"]);
+  if (parsed["width-tolerance"] !== undefined) options.widthTolerance = Number(parsed["width-tolerance"]);
+  if (parsed["min-height"] !== undefined) options.minHeight = Number(parsed["min-height"]);
+  if (parsed["max-height"] !== undefined) options.maxHeight = Number(parsed["max-height"]);
+  if (parsed.scale !== undefined) options.scale = parsed.scale; // validated by resolveExportScale
+  return options;
+}
+
+function firstUrlArg(parsed) {
+  return parsed._.find((value) => looksLikeFigmaUrl(value)) || parsed._[0];
+}
+
+async function main() {
+  const [, , command, ...rest] = process.argv;
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    usage();
+    return;
+  }
+
+  // Primary UX: figma-pixel-kit "https://www.figma.com/..." [--mobile] [--screen-width 390] ...
+  if (looksLikeFigmaUrl(command)) {
+    const parsed = parseArgs(rest);
+    await exportCommand(command, normalizeDetectionOptions(parsed));
+    return;
+  }
+
+  if (command === "token") {
+    const [token] = rest;
+    await saveTokenCommand(token);
+    return;
+  }
+
+  if (command === "doctor") {
+    await doctorCommand();
+    return;
+  }
+
+  if (command === "login") {
+    await loginCommand();
+    return;
+  }
+
+  if (command === "oauth-setup") {
+    const [clientId, clientSecret] = rest;
+    await oauthSetupCommand(clientId, clientSecret);
+    return;
+  }
+
+  if (command === "logout") {
+    await logoutCommand();
+    return;
+  }
+
+  if (command === "init") {
+    await initCommand();
+    return;
+  }
+
+  if (["inspect", "analyze", "implement", "export"].includes(command)) {
+    const parsed = parseArgs(rest);
+    const figmaUrl = firstUrlArg(parsed);
+    if (!figmaUrl) {
+      usage();
+      throw new Error("Missing Figma URL.");
+    }
+    if (command === "inspect") {
+      await inspectCommand(figmaUrl);
+    } else if (command === "analyze") {
+      await analyzeBoardCommand(figmaUrl, normalizeDetectionOptions(parsed));
+    } else if (command === "implement") {
+      await exportCommand(figmaUrl, normalizeDetectionOptions(parsed, { mode: "implement" }));
+    } else {
+      await exportCommand(figmaUrl, normalizeDetectionOptions(parsed));
+    }
+    return;
+  }
+
+  if (command === "compare") {
+    const parsed = parseArgs(rest);
+    const [input] = parsed._;
+    if (!input) {
+      usage();
+      throw new Error("Missing output folder/screen id.");
+    }
+    await compareCommand(input, parsed);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+// Only run the CLI when this file is the entry point, so the pure helpers can be imported in tests.
+// Compare realpaths: the global `figma-pixel-kit` bin is a symlink, so the raw argv[1] URL
+// never matches import.meta.url (which is already symlink-resolved). Resolve both before comparing.
+function isEntryPoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  }
+}
+const invokedDirectly = isEntryPoint();
+if (invokedDirectly) {
+  main().catch((error) => {
+    console.error("\nError:");
+    console.error(error?.message || String(error));
+    // Set FIGMA_PIXEL_KIT_DEBUG=1 to see the full stack trace.
+    if (process.env.FIGMA_PIXEL_KIT_DEBUG && error?.stack) {
+      console.error("\n" + error.stack);
+    }
+    process.exit(1);
+  });
+}
+
+export {
+  REFERENCE_SCALE,
+  parseFigmaUrl,
+  pascalCase,
+  slugifyName,
+  classifyElement,
+  detectIconLibrary,
+  collectScreenAssets,
+  shouldRenderNode,
+  nodeHasVisiblePaint,
+  flattenNodes,
+  detectScreens,
+  detectComponents,
+  extractComponentLibrary,
+  detectRepeatedPatterns,
+  autoLayoutToCss,
+  layoutChildInfo,
+  buildPropSchema,
+  propsToTs,
+  camelProp,
+  buildSpecJson,
+  buildInventoryMarkdown,
+  buildComponentLibraryMarkdown,
+  buildHtml,
+  buildReferencePreviewHtml,
+  buildVisualTest,
+  detectHotspots,
+  normalizePng,
+  maskRegions,
+  textMaskRects,
+  resolveExportScale
+};