npm - frameshot-mcp - Versions diffs - 0.2.0 → 0.6.0 - Mend

frameshot-mcp 0.2.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md +93 -128
package/action.yml +130 -0
package/dist/chunk-47YJG5HR.js +690 -0
package/dist/index.js +1091 -214
package/dist/renderer.d.ts +241 -0
package/dist/renderer.js +28 -0
package/package.json +28 -5
package/scripts/render-changed.mjs +90 -0
package/scripts/setup-labels.sh +48 -0

package/dist/index.js CHANGED Viewed

@@ -1,11 +1,22 @@
 #!/usr/bin/env node
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
+import {
+  AuditUseCase,
+  BrowserPool,
+  CatalogUseCase,
+  DEVICE_PRESETS,
+  DiffUseCase,
+  EXT_TO_FRAMEWORK,
+  HtmlBuilder,
+  ImageComparator,
+  RenderUseCase,
+  ScreenshotUseCase,
+  SnapshotStore,
+  SnapshotUseCase,
+  __export
+} from "./chunk-47YJG5HR.js";
 // src/index.ts
+import { execSync } from "child_process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -14523,232 +14534,1098 @@ function date4(params) {
 // node_modules/zod/v4/classic/external.js
 config(en_default());
-// src/renderer.ts
-import { chromium, firefox, webkit } from "playwright";
-var pool = /* @__PURE__ */ new Map();
-var ENGINES = ["chromium", "firefox", "webkit"];
-async function warmup(engines = ENGINES) {
-  await Promise.all(engines.map((e) => getSlot(e)));
-}
-async function getSlot(engine) {
-  const existing = pool.get(engine);
-  if (existing?.browser.isConnected() && existing.ready) {
-    return existing;
-  }
-  const launcher = { chromium, firefox, webkit }[engine];
-  let browser;
-  try {
-    browser = await launcher.launch({
-      headless: true,
-      ...engine === "chromium" ? { channel: "chrome" } : {}
-    });
-  } catch (e) {
-    throw new Error(`${engine} is not installed. Run: npx playwright install ${engine}`);
-  }
-  const context = await browser.newContext({
-    viewport: { width: 1280, height: 800 },
-    deviceScaleFactor: 2
-  });
-  const page = await context.newPage();
-  await page.setContent(
-    '<html><head><script src="https://cdn.tailwindcss.com?plugins=forms,typography,aspect-ratio"></script></head><body></body></html>',
-    { waitUntil: "networkidle" }
+// src/tools/audit-tools.ts
+function registerAuditTools(server2, useCase) {
+  server2.tool(
+    "audit_a11y",
+    "Run an accessibility audit (axe-core) on a rendered component. Returns WCAG violations with impact level, description, and affected HTML nodes. Use this to catch a11y issues before shipping.",
+    {
+      code: external_exports.string().describe("Component code to audit"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework: html, react, vue, or svelte"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)")
+    },
+    async ({ code, framework, width, height }) => {
+      try {
+        const result = await useCase.auditA11y(code, framework, {
+          viewport: { width, height }
+        });
+        if (result.violations.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `\u2705 No accessibility violations found. (${result.passes} rules passed, ${result.incomplete} need review)`
+              }
+            ]
+          };
+        }
+        const report = result.violations.map((v) => {
+          const nodes = v.nodes.slice(0, 3).map((n) => `    ${n.target.join(" > ")}
+    ${n.html}`).join("\n");
+          return `[${v.impact?.toUpperCase()}] ${v.id}
+  ${v.description}
+  ${v.helpUrl}
+${nodes}`;
+        }).join("\n\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Found ${result.violations.length} accessibility violation(s):
+${report}
+(${result.passes} rules passed, ${result.incomplete} need review)`
+            }
+          ]
+        };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            { type: "text", text: `A11y audit failed: ${msg}` }
+          ],
+          isError: true
+        };
+      }
+    }
   );
-  const slot = { browser, page, ready: true };
-  pool.set(engine, slot);
-  return slot;
-}
-function wrapComponent(code, framework) {
-  const tailwind = '<script src="https://cdn.tailwindcss.com?plugins=forms,typography,aspect-ratio"></script>';
-  const baseStyle = `<style>*{margin:0;box-sizing:border-box}body{padding:16px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif}</style>`;
-  if (framework === "html") {
-    if (code.includes("<html")) return code;
-    return `<!DOCTYPE html><html><head><meta charset="utf-8">${tailwind}${baseStyle}</head><body>${code}</body></html>`;
-  }
-  if (framework === "react") {
-    return `<!DOCTYPE html><html><head><meta charset="utf-8">${tailwind}
-<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
-<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
-<script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
-${baseStyle}</head><body><div id="root"></div>
-<script type="text/babel">
-${code}
-const _C = typeof App!=='undefined'?App:typeof Component!=='undefined'?Component:typeof Default!=='undefined'?Default:null;
-if(_C)ReactDOM.createRoot(document.getElementById('root')).render(React.createElement(_C));
-</script></body></html>`;
-  }
-  if (framework === "vue") {
-    return `<!DOCTYPE html><html><head><meta charset="utf-8">${tailwind}
-<script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
-${baseStyle}</head><body><div id="app"></div>
-<script>
-const{createApp,ref,reactive,computed,onMounted,watch,watchEffect}=Vue;
-${code}
-const _C=typeof App!=='undefined'?App:typeof Component!=='undefined'?Component:null;
-if(_C)createApp(_C).mount('#app');
-</script></body></html>`;
-  }
-  return code;
-}
-async function renderSingle(engine, html, options) {
-  const {
-    width = 1280,
-    height = 800,
-    fullPage = true,
-    waitFor = 0
-  } = options;
-  const slot = await getSlot(engine);
-  const { page } = slot;
-  const currentViewport = page.viewportSize();
-  if (currentViewport?.width !== width || currentViewport?.height !== height) {
-    await page.setViewportSize({ width, height });
-  }
-  await page.setContent(html, { waitUntil: "load", timeout: 1e4 });
-  if (waitFor > 0) {
-    await page.waitForTimeout(waitFor);
-  }
-  const screenshot = await page.screenshot({ type: "png", fullPage });
-  const metrics = await page.evaluate(() => ({
-    w: document.documentElement.scrollWidth,
-    h: document.documentElement.scrollHeight
-  }));
-  return {
-    engine,
-    image: screenshot.toString("base64"),
-    width: metrics.w,
-    height: metrics.h
-  };
-}
-async function render(code, framework, options = {}) {
-  const engines = options.engines ?? ["chromium"];
-  const html = wrapComponent(code, framework);
-  const results = await Promise.all(
-    engines.map((e) => renderSingle(e, html, options))
+  server2.tool(
+    "perf_audit",
+    "Analyze component performance: DOM element count, tree depth, render time, script/stylesheet count. Use this to catch bloated components before they ship.",
+    {
+      code: external_exports.string().describe("Component code to audit"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)")
+    },
+    async ({ code, framework, width, height }) => {
+      try {
+        const metrics = await useCase.perfAudit(code, framework, {
+          viewport: { width, height }
+        });
+        const lines = [
+          `\u23F1\uFE0F  Render time: ${metrics.renderTimeMs}ms`,
+          `\u{1F4E6} DOM elements: ${metrics.domElements}`,
+          `\u{1F333} DOM depth: ${metrics.domDepth}`,
+          `\u{1F4DC} Scripts: ${metrics.scriptCount}`,
+          `\u{1F3A8} Stylesheets: ${metrics.styleSheetCount}`,
+          `\u{1F5BC}\uFE0F  Images: ${metrics.imageCount}`,
+          `\u{1F4D0} Total DOM size: ${(metrics.totalDomSize / 1024).toFixed(1)}KB`
+        ];
+        return {
+          content: [{ type: "text", text: lines.join("\n") }]
+        };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            { type: "text", text: `Perf audit failed: ${msg}` }
+          ],
+          isError: true
+        };
+      }
+    }
   );
-  return results;
-}
-async function screenshotUrl(url2, options = {}) {
-  const engines = options.engines ?? ["chromium"];
-  const results = await Promise.all(
-    engines.map(async (engine) => {
-      const { width = 1280, height = 800, fullPage = true, waitFor = 0 } = options;
-      const slot = await getSlot(engine);
-      const { page } = slot;
-      const currentViewport = page.viewportSize();
-      if (currentViewport?.width !== width || currentViewport?.height !== height) {
-        await page.setViewportSize({ width, height });
-      }
-      await page.goto(url2, { waitUntil: "domcontentloaded", timeout: 15e3 });
-      await page.waitForLoadState("networkidle", { timeout: 5e3 }).catch(() => {
-      });
-      if (waitFor > 0) {
-        await page.waitForTimeout(waitFor);
-      }
-      const screenshot = await page.screenshot({ type: "png", fullPage });
-      const metrics = await page.evaluate(() => ({
-        w: document.documentElement.scrollWidth,
-        h: document.documentElement.scrollHeight
-      }));
-      return { engine, image: screenshot.toString("base64"), width: metrics.w, height: metrics.h };
-    })
+}
+// src/tools/catalog-tools.ts
+function registerCatalogTools(server2, useCase) {
+  server2.tool(
+    "render_catalog",
+    "Scan a directory for component files (.jsx/.tsx/.vue/.svelte/.html) and render a screenshot of each. Returns a visual catalog \u2014 like Storybook but zero-config. Use this to quickly audit all components in a folder.",
+    {
+      directory: external_exports.string().describe("Absolute path to the directory to scan"),
+      recursive: external_exports.boolean().optional().default(false).describe("Scan subdirectories recursively"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)"),
+      darkMode: external_exports.boolean().optional().default(false).describe("Render with dark mode"),
+      tailwindVersion: external_exports.enum(["3", "4"]).optional().default("3").describe("Tailwind CSS version (3 or 4)")
+    },
+    async ({
+      directory,
+      recursive,
+      width,
+      height,
+      darkMode,
+      tailwindVersion
+    }) => {
+      try {
+        const results = await useCase.renderCatalog(directory, {
+          recursive,
+          viewport: { width, height },
+          darkMode,
+          tailwindVersion
+        });
+        if (results.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No component files found in ${directory}`
+              }
+            ]
+          };
+        }
+        const content = results.flatMap((r) => {
+          if (!r.image) {
+            return [
+              {
+                type: "text",
+                text: `\u274C ${r.path} \u2014 failed to render`
+              }
+            ];
+          }
+          return [
+            {
+              type: "image",
+              data: r.image,
+              mimeType: "image/png"
+            },
+            {
+              type: "text",
+              text: `[${r.framework}] ${r.path} \u2014 ${r.width}x${r.height}${r.consoleErrors.length ? `
+\u26A0\uFE0F ${r.consoleErrors.join("\n")}` : ""}`
+            }
+          ];
+        });
+        content.unshift({
+          type: "text",
+          text: `\u{1F4E6} Component catalog: ${results.length} files from ${directory}`
+        });
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            { type: "text", text: `Catalog render failed: ${msg}` }
+          ],
+          isError: true
+        };
+      }
+    }
   );
-  return results;
 }
-async function shutdown() {
-  for (const slot of pool.values()) {
-    await slot.browser.close().catch(() => {
-    });
-  }
-  pool.clear();
+// src/tools/diff-tools.ts
+function registerDiffTools(server2, useCase) {
+  server2.tool(
+    "diff_component",
+    "Visual regression test: render before/after code and return a pixel diff image with percentage changed. Use this during refactoring to catch unintended visual changes.",
+    {
+      before: external_exports.string().describe("Component code BEFORE the change"),
+      after: external_exports.string().describe("Component code AFTER the change"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework: html, react, vue, or svelte"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)")
+    },
+    async ({ before, after, framework, width, height }) => {
+      try {
+        const result = await useCase.diffComponent(before, after, framework, {
+          viewport: { width, height }
+        });
+        const content = [
+          {
+            type: "text",
+            text: `Visual diff: ${result.diffPercentage}% pixels changed (${result.diffPixels}/${result.totalPixels})`
+          },
+          { type: "text", text: "Before:" },
+          {
+            type: "image",
+            data: result.before,
+            mimeType: "image/png"
+          },
+          { type: "text", text: "After:" },
+          {
+            type: "image",
+            data: result.after,
+            mimeType: "image/png"
+          },
+          { type: "text", text: "Diff (red = changed pixels):" },
+          {
+            type: "image",
+            data: result.diff,
+            mimeType: "image/png"
+          }
+        ];
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [{ type: "text", text: `Diff failed: ${msg}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "diff_reference",
+    "Compare rendered component output against a reference image (e.g. from Figma export or previous snapshot). Returns pixel diff percentage and pass/fail status. Use this for design QA \u2014 verify your component matches the design.",
+    {
+      code: external_exports.string().describe("Component code to render and compare"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework: html, react, vue, or svelte"),
+      referenceImage: external_exports.string().describe("Reference image as base64-encoded PNG"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)"),
+      threshold: external_exports.number().optional().default(0.1).describe(
+        "Pixel matching threshold (0-1). Lower = stricter. Default 0.1."
+      ),
+      darkMode: external_exports.boolean().optional().default(false).describe("Render with dark mode"),
+      tailwindVersion: external_exports.enum(["3", "4"]).optional().default("3").describe("Tailwind CSS version (3 or 4)")
+    },
+    async ({
+      code,
+      framework,
+      referenceImage,
+      width,
+      height,
+      threshold,
+      darkMode,
+      tailwindVersion
+    }) => {
+      try {
+        const result = await useCase.diffFromReference(
+          code,
+          framework,
+          referenceImage,
+          {
+            viewport: { width, height },
+            threshold,
+            darkMode,
+            tailwindVersion
+          }
+        );
+        const status = result.passed ? "PASS" : "FAIL";
+        const content = [
+          {
+            type: "text",
+            text: `${status}: ${result.diffPercentage}% pixels differ (${result.diffPixels}/${result.totalPixels})`
+          },
+          { type: "text", text: "Rendered:" },
+          {
+            type: "image",
+            data: result.rendered,
+            mimeType: "image/png"
+          },
+          { type: "text", text: "Diff (red = changed pixels):" },
+          {
+            type: "image",
+            data: result.diff,
+            mimeType: "image/png"
+          }
+        ];
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            { type: "text", text: `Reference diff failed: ${msg}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
 }
-// src/index.ts
-var server = new McpServer({
-  name: "frameshot",
-  version: "0.1.0"
-});
-server.tool(
-  "render_component",
-  "Instantly render a React/Vue/HTML component and return screenshots across browser engines. Zero setup needed \u2014 just pass your code. Tailwind CSS is built-in. Use this to visually verify UI code without starting a dev server.",
-  {
-    code: external_exports.string().describe("Component code to render"),
-    framework: external_exports.enum(["html", "react", "vue"]).default("react").describe("Framework: html, react, or vue"),
-    engines: external_exports.array(external_exports.enum(["chromium", "firefox", "webkit"])).optional().default(["chromium"]).describe('Browser engines to render in. Use ["chromium","firefox","webkit"] for cross-browser check.'),
-    width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
-    height: external_exports.number().optional().default(800).describe("Viewport height (px)"),
-    fullPage: external_exports.boolean().optional().default(true).describe("Capture full scroll height")
-  },
-  async ({ code, framework, engines, width, height, fullPage }) => {
-    try {
-      const results = await render(code, framework, {
-        width,
-        height,
-        fullPage,
-        engines
-      });
-      const content = results.flatMap((r) => [
-        {
-          type: "image",
-          data: r.image,
-          mimeType: "image/png"
-        },
-        {
+// src/tools/render-tools.ts
+import { readFileSync } from "fs";
+import { extname } from "path";
+function registerRenderTools(server2, useCase) {
+  server2.tool(
+    "render_file",
+    "Read a component file from disk and render it. Auto-detects framework from file extension (.jsx/.tsx=react, .vue=vue, .svelte=svelte, .html=html).",
+    {
+      path: external_exports.string().describe("Absolute path to the component file"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)"),
+      darkMode: external_exports.boolean().optional().default(false).describe("Render with dark mode"),
+      tailwindVersion: external_exports.enum(["3", "4"]).optional().default("3").describe("Tailwind CSS version (3 or 4)")
+    },
+    async ({ path, width, height, darkMode, tailwindVersion }) => {
+      try {
+        const code = readFileSync(path, "utf-8");
+        const ext = extname(path).toLowerCase();
+        const framework = EXT_TO_FRAMEWORK[ext] ?? "react";
+        const start = performance.now();
+        const results = await useCase.render(code, framework, {
+          viewport: { width, height },
+          fullPage: true,
+          engines: ["chromium"],
+          darkMode,
+          tailwindVersion
+        });
+        const elapsed = Math.round(performance.now() - start);
+        const content = results.flatMap((r) => [
+          {
+            type: "image",
+            data: r.image,
+            mimeType: "image/png"
+          },
+          {
+            type: "text",
+            text: `[${framework}] ${r.width}x${r.height} (${elapsed}ms)${r.consoleErrors.length ? `
+\u26A0\uFE0F Console errors:
+${r.consoleErrors.join("\n")}` : ""}`
+          }
+        ]);
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            { type: "text", text: `File render failed: ${msg}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "render_component",
+    "Instantly render a React/Vue/HTML component and return screenshots across browser engines. Zero setup needed \u2014 just pass your code. Tailwind CSS is built-in. Use this to visually verify UI code without starting a dev server.",
+    {
+      code: external_exports.string().describe("Component code to render"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework: html, react, vue, or svelte"),
+      engines: external_exports.array(external_exports.enum(["chromium", "firefox", "webkit"])).optional().default(["chromium"]).describe(
+        'Browser engines to render in. Use ["chromium","firefox","webkit"] for cross-browser check.'
+      ),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)"),
+      fullPage: external_exports.boolean().optional().default(true).describe("Capture full scroll height"),
+      darkMode: external_exports.boolean().optional().default(false).describe("Render with Tailwind dark mode (adds 'dark' class to html)"),
+      colorSchemes: external_exports.array(external_exports.enum(["light", "dark"])).optional().describe(
+        'Render both: ["light","dark"] returns 2 screenshots for comparison'
+      ),
+      css: external_exports.string().optional().describe("Custom CSS to inject (design tokens, variables, etc)"),
+      tailwindVersion: external_exports.enum(["3", "4"]).optional().default("3").describe("Tailwind CSS version (3 or 4)")
+    },
+    async ({
+      code,
+      framework,
+      engines,
+      width,
+      height,
+      fullPage,
+      darkMode,
+      colorSchemes,
+      css,
+      tailwindVersion
+    }) => {
+      try {
+        const start = performance.now();
+        const schemes = colorSchemes ?? (darkMode ? ["dark"] : ["light"]);
+        const allResults = await Promise.all(
+          schemes.map(
+            (scheme) => useCase.render(code, framework, {
+              viewport: { width, height },
+              fullPage,
+              engines,
+              darkMode: scheme === "dark",
+              css,
+              tailwindVersion
+            })
+          )
+        );
+        const elapsed = Math.round(performance.now() - start);
+        const results = allResults.flat();
+        const content = results.flatMap((r) => [
+          {
+            type: "image",
+            data: r.image,
+            mimeType: "image/png"
+          },
+          {
+            type: "text",
+            text: `[${r.engine}] ${r.width}x${r.height} (${elapsed}ms)${r.consoleErrors.length ? `
+\u26A0\uFE0F Console errors:
+${r.consoleErrors.join("\n")}` : ""}`
+          }
+        ]);
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [{ type: "text", text: `Render failed: ${msg}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "render_responsive",
+    "Render a component at mobile, tablet, and desktop sizes in one call. Returns 3 screenshots for responsive verification.",
+    {
+      code: external_exports.string().describe("Component code to render"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework: html, react, vue, or svelte"),
+      devices: external_exports.array(external_exports.enum(["mobile", "tablet", "desktop"])).optional().default(["mobile", "tablet", "desktop"]).describe("Device sizes to render")
+    },
+    async ({ code, framework, devices }) => {
+      try {
+        const results = await Promise.all(
+          devices.map(async (device) => {
+            const preset = DEVICE_PRESETS[device];
+            const [result] = await useCase.render(code, framework, {
+              viewport: { width: preset.width, height: preset.height },
+              fullPage: true,
+              engines: ["chromium"]
+            });
+            return { device, ...result };
+          })
+        );
+        const content = results.flatMap((r) => [
+          {
+            type: "image",
+            data: r.image,
+            mimeType: "image/png"
+          },
+          {
+            type: "text",
+            text: `[${r.device}] ${r.width}x${r.height}`
+          }
+        ]);
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Responsive render failed: ${msg}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "render_variants",
+    "Render multiple variants of a component (different props/states) in one call. Returns a screenshot for each variant. Use this to verify buttons in all states, theme variations, etc.",
+    {
+      code: external_exports.string().describe("Component code (must export a function that accepts props)"),
+      variants: external_exports.array(
+        external_exports.object({
+          label: external_exports.string().describe("Label for this variant (e.g. 'disabled', 'loading')"),
+          props: external_exports.string().describe("Props as JSON string to pass to the component")
+        })
+      ).describe("Array of variants to render"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework: html, react, vue, or svelte"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)")
+    },
+    async ({ code, variants, framework, width, height }) => {
+      try {
+        const results = await Promise.all(
+          variants.map(async (variant) => {
+            const wrappedCode = framework === "react" ? `${code}
+const _VARIANT_PROPS = ${variant.props};
+function _VariantWrapper() { return <App {..._VARIANT_PROPS} />; }` : code;
+            const renderFramework = framework;
+            const overrideCode = framework === "react" ? wrappedCode.replace(
+              /const _C = typeof App/,
+              "const _C = typeof _VariantWrapper!=='undefined'?_VariantWrapper:typeof App"
+            ) : wrappedCode;
+            const [result] = await useCase.render(
+              overrideCode,
+              renderFramework,
+              {
+                viewport: { width, height },
+                fullPage: true,
+                engines: ["chromium"]
+              }
+            );
+            return { label: variant.label, ...result };
+          })
+        );
+        const content = results.flatMap((r) => [
+          {
+            type: "image",
+            data: r.image,
+            mimeType: "image/png"
+          },
+          {
+            type: "text",
+            text: `[${r.label}] ${r.width}x${r.height}${r.consoleErrors.length ? `
+\u26A0\uFE0F Console errors:
+${r.consoleErrors.join("\n")}` : ""}`
+          }
+        ]);
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Variants render failed: ${msg}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "render_interaction",
+    "Render a component, simulate user interactions (click, hover, focus, type), then screenshot the result. Use this to verify hover states, dropdowns, modals, form inputs.",
+    {
+      code: external_exports.string().describe("Component code to render"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework"),
+      interactions: external_exports.array(
+        external_exports.object({
+          action: external_exports.enum(["click", "hover", "focus", "type", "wait"]).describe("Interaction type"),
+          selector: external_exports.string().optional().describe("CSS selector for the target element"),
+          value: external_exports.string().optional().describe("Text to type (for 'type' action)"),
+          ms: external_exports.number().optional().describe("Wait duration in ms (for 'wait' action)")
+        })
+      ).describe("Sequence of interactions to perform"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)")
+    },
+    async ({ code, framework, interactions, width, height }) => {
+      try {
+        const result = await useCase.renderInteraction(
+          code,
+          framework,
+          interactions,
+          {
+            viewport: { width, height }
+          }
+        );
+        const content = [
+          {
+            type: "image",
+            data: result.image,
+            mimeType: "image/png"
+          },
+          {
+            type: "text",
+            text: `After ${interactions.length} interaction(s) \u2014 ${result.width}x${result.height}`
+          }
+        ];
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Interaction render failed: ${msg}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "render_grid",
+    "Render multiple code snippets in a grid layout and return a single combined image. Use this to compare components side-by-side (e.g. design system overview, theme comparison).",
+    {
+      cells: external_exports.array(
+        external_exports.object({
+          label: external_exports.string().describe("Label for this cell"),
+          code: external_exports.string().describe("Component code for this cell")
+        })
+      ).describe("Array of cells to render in the grid"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework"),
+      columns: external_exports.number().optional().default(3).describe("Number of columns in the grid"),
+      cellWidth: external_exports.number().optional().default(400).describe("Width of each cell (px)"),
+      cellHeight: external_exports.number().optional().default(300).describe("Height of each cell (px)")
+    },
+    async ({ cells, framework, columns, cellWidth, cellHeight }) => {
+      try {
+        const result = await useCase.renderGrid(cells, framework, {
+          columns,
+          viewport: { width: cellWidth, height: cellHeight }
+        });
+        const content = [
+          {
+            type: "image",
+            data: result.image,
+            mimeType: "image/png"
+          },
+          {
+            type: "text",
+            text: `Grid: ${result.cells} cells, ${columns} columns \u2014 ${result.width}x${result.height}`
+          }
+        ];
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            { type: "text", text: `Grid render failed: ${msg}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "render_theme",
+    "Render a component in both light and dark mode side-by-side. Returns 2 labeled screenshots for quick theme verification.",
+    {
+      code: external_exports.string().describe("Component code to render"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)")
+    },
+    async ({ code, framework, width, height }) => {
+      try {
+        const start = performance.now();
+        const [lightResults, darkResults] = await Promise.all([
+          useCase.render(code, framework, {
+            viewport: { width, height },
+            fullPage: true,
+            engines: ["chromium"],
+            darkMode: false
+          }),
+          useCase.render(code, framework, {
+            viewport: { width, height },
+            fullPage: true,
+            engines: ["chromium"],
+            darkMode: true
+          })
+        ]);
+        const elapsed = Math.round(performance.now() - start);
+        const content = [
+          { type: "text", text: "\u2600\uFE0F Light mode:" },
+          {
+            type: "image",
+            data: lightResults[0].image,
+            mimeType: "image/png"
+          },
+          { type: "text", text: "\u{1F319} Dark mode:" },
+          {
+            type: "image",
+            data: darkResults[0].image,
+            mimeType: "image/png"
+          },
+          {
+            type: "text",
+            text: `${lightResults[0].width}x${lightResults[0].height} (${elapsed}ms)`
+          }
+        ];
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            { type: "text", text: `Theme render failed: ${msg}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "render_matrix",
+    "Render a component across multiple viewports AND themes in one call. Returns a grid of screenshots (viewports x themes) for comprehensive responsive + theme verification.",
+    {
+      code: external_exports.string().describe("Component code to render"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework: html, react, vue, or svelte"),
+      viewports: external_exports.array(
+        external_exports.union([
+          external_exports.enum(["mobile", "tablet", "desktop"]),
+          external_exports.object({
+            width: external_exports.number().describe("Viewport width (px)"),
+            height: external_exports.number().describe("Viewport height (px)")
+          })
+        ])
+      ).default(["mobile", "tablet", "desktop"]).describe(
+        "Viewports to render: preset names ('mobile','tablet','desktop') or custom {width, height}"
+      ),
+      themes: external_exports.array(external_exports.enum(["light", "dark"])).default(["light", "dark"]).describe("Themes to render for each viewport"),
+      css: external_exports.string().optional().describe("Custom CSS to inject (design tokens, variables, etc)"),
+      tailwindVersion: external_exports.enum(["3", "4"]).optional().default("3").describe("Tailwind CSS version (3 or 4)")
+    },
+    async ({ code, framework, viewports, themes, css, tailwindVersion }) => {
+      try {
+        const start = performance.now();
+        const resolvedViewports = viewports.map((v) => {
+          if (typeof v === "string") {
+            const preset = DEVICE_PRESETS[v];
+            return { label: v, width: preset.width, height: preset.height };
+          }
+          return {
+            label: `${v.width}x${v.height}`,
+            width: v.width,
+            height: v.height
+          };
+        });
+        const results = await useCase.renderMatrix(
+          code,
+          framework,
+          resolvedViewports,
+          themes,
+          {
+            css,
+            tailwindVersion
+          }
+        );
+        const elapsed = Math.round(performance.now() - start);
+        const content = results.flatMap((r) => [
+          {
+            type: "image",
+            data: r.image,
+            mimeType: "image/png"
+          },
+          {
+            type: "text",
+            text: `[${r.viewport}/${r.theme}] ${r.width}x${r.height}${r.consoleErrors.length ? `
+\u26A0\uFE0F Console errors:
+${r.consoleErrors.join("\n")}` : ""}`
+          }
+        ]);
+        content.push({
           type: "text",
-          text: `[${r.engine}] ${r.width}x${r.height}`
-        }
-      ]);
-      return { content };
-    } catch (error51) {
-      const msg = error51 instanceof Error ? error51.message : String(error51);
-      return { content: [{ type: "text", text: `Render failed: ${msg}` }], isError: true };
+          text: `Matrix: ${resolvedViewports.length} viewports x ${themes.length} themes = ${results.length} renders (${elapsed}ms)`
+        });
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            { type: "text", text: `Matrix render failed: ${msg}` }
+          ],
+          isError: true
+        };
+      }
     }
-  }
+  );
+  server2.tool(
+    "capture_animation",
+    "Capture multiple frames of a CSS animation or transition over time. Returns sequential screenshots to verify animation behavior, timing, and smoothness.",
+    {
+      code: external_exports.string().describe("Component code with CSS animations/transitions"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework: html, react, vue, or svelte"),
+      frames: external_exports.number().optional().default(5).describe("Number of frames to capture"),
+      duration: external_exports.number().optional().default(1e3).describe("Total capture duration in ms"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)")
+    },
+    async ({ code, framework, frames, duration: duration3, width, height }) => {
+      try {
+        const results = await useCase.captureAnimation(code, framework, {
+          frames,
+          duration: duration3,
+          viewport: { width, height }
+        });
+        const content = results.flatMap((r) => [
+          {
+            type: "image",
+            data: r.image,
+            mimeType: "image/png"
+          },
+          {
+            type: "text",
+            text: `[${r.timestamp}ms]`
+          }
+        ]);
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Animation capture failed: ${msg}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+// src/tools/screenshot-tools.ts
+function registerScreenshotTools(server2, useCase) {
+  server2.tool(
+    "screenshot_url",
+    "Take a screenshot of a URL (e.g. localhost:3000) across multiple browser engines in parallel. Supports waiting for specific elements and retry with exponential backoff for dev servers that may be slow to start.",
+    {
+      url: external_exports.string().url().describe("URL to screenshot"),
+      engines: external_exports.array(external_exports.enum(["chromium", "firefox", "webkit"])).optional().default(["chromium"]).describe("Browser engines"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)"),
+      fullPage: external_exports.boolean().optional().default(true).describe("Capture full scroll height"),
+      waitForSelector: external_exports.string().optional().describe(
+        "Wait for a specific CSS selector to appear before capturing (e.g. '#app', '.loaded')"
+      ),
+      waitForNetworkIdle: external_exports.boolean().optional().default(true).describe("Wait for network to settle before capturing"),
+      retryOnError: external_exports.number().optional().default(0).describe(
+        "Number of retries with exponential backoff (300ms, 600ms, 1200ms...) if the page fails to load"
+      )
+    },
+    async ({
+      url: url2,
+      engines,
+      width,
+      height,
+      fullPage,
+      waitForSelector,
+      waitForNetworkIdle,
+      retryOnError
+    }) => {
+      try {
+        const results = await useCase.screenshotUrlWithRetry(url2, {
+          viewport: { width, height },
+          engines,
+          fullPage,
+          waitForSelector,
+          waitForNetworkIdle,
+          retryCount: retryOnError
+        });
+        const content = results.flatMap((r) => [
+          {
+            type: "image",
+            data: r.image,
+            mimeType: "image/png"
+          },
+          {
+            type: "text",
+            text: `[${r.engine}] ${r.width}x${r.height}${r.consoleErrors.length ? `
+\u26A0\uFE0F Console errors:
+${r.consoleErrors.join("\n")}` : ""}`
+          }
+        ]);
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        const retryInfo = retryOnError > 0 ? ` (after ${retryOnError + 1} attempts)` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Screenshot failed${retryInfo}: ${msg}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+// src/tools/snapshot-tools.ts
+function registerSnapshotTools(server2, useCase) {
+  server2.tool(
+    "snapshot_save",
+    "Render a component and save the screenshot as a named snapshot. Use this to establish a baseline before making changes. Later use snapshot_check to detect visual regressions.",
+    {
+      name: external_exports.string().describe(
+        "Unique name for this snapshot (e.g. 'header-desktop', 'button-hover')"
+      ),
+      code: external_exports.string().describe("Component code to render and snapshot"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)"),
+      darkMode: external_exports.boolean().optional().default(false).describe("Render with dark mode"),
+      tailwindVersion: external_exports.enum(["3", "4"]).optional().default("3").describe("Tailwind CSS version (3 or 4)")
+    },
+    async ({
+      name,
+      code,
+      framework,
+      width,
+      height,
+      darkMode,
+      tailwindVersion
+    }) => {
+      try {
+        const result = await useCase.save(name, code, framework, {
+          viewport: { width, height },
+          darkMode,
+          tailwindVersion
+        });
+        return {
+          content: [
+            {
+              type: "image",
+              data: result.image,
+              mimeType: "image/png"
+            },
+            {
+              type: "text",
+              text: `Snapshot "${name}" saved (${result.width}x${result.height})`
+            }
+          ]
+        };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            { type: "text", text: `Snapshot save failed: ${msg}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "snapshot_check",
+    "Render a component and compare against a previously saved snapshot. Returns pixel diff and pass/fail. Use this after making changes to verify no visual regression.",
+    {
+      name: external_exports.string().describe("Name of the snapshot to compare against"),
+      code: external_exports.string().describe("Current component code to render and compare"),
+      framework: external_exports.enum(["html", "react", "vue", "svelte"]).default("react").describe("Framework"),
+      width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
+      height: external_exports.number().optional().default(800).describe("Viewport height (px)"),
+      darkMode: external_exports.boolean().optional().default(false).describe("Render with dark mode"),
+      tailwindVersion: external_exports.enum(["3", "4"]).optional().default("3").describe("Tailwind CSS version (3 or 4)")
+    },
+    async ({
+      name,
+      code,
+      framework,
+      width,
+      height,
+      darkMode,
+      tailwindVersion
+    }) => {
+      try {
+        const result = await useCase.check(name, code, framework, {
+          viewport: { width, height },
+          darkMode,
+          tailwindVersion
+        });
+        if (!result) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No snapshot found with name "${name}". Use snapshot_save first.`
+              }
+            ],
+            isError: true
+          };
+        }
+        const status = result.passed ? "PASS" : "FAIL";
+        const content = [
+          {
+            type: "text",
+            text: `${status}: ${result.diffPercentage}% pixels differ vs snapshot "${name}"`
+          },
+          {
+            type: "image",
+            data: result.rendered,
+            mimeType: "image/png"
+          },
+          { type: "text", text: "Diff:" },
+          {
+            type: "image",
+            data: result.diff,
+            mimeType: "image/png"
+          }
+        ];
+        return { content };
+      } catch (error51) {
+        const msg = error51 instanceof Error ? error51.message : String(error51);
+        return {
+          content: [
+            { type: "text", text: `Snapshot check failed: ${msg}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.tool(
+    "snapshot_list",
+    "List all saved snapshots with their names and timestamps.",
+    {},
+    async () => {
+      const snapshots = useCase.list();
+      if (snapshots.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No snapshots saved. Use snapshot_save to create one."
+            }
+          ]
+        };
+      }
+      const lines = snapshots.map(
+        (s) => `\u2022 ${s.key} (saved ${new Date(s.timestamp).toLocaleTimeString()})`
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Saved snapshots (${snapshots.length}):
+${lines.join("\n")}`
+          }
+        ]
+      };
+    }
+  );
+}
+// src/tools/register.ts
+function registerAllTools(server2, useCases) {
+  registerRenderTools(server2, useCases.render);
+  registerScreenshotTools(server2, useCases.screenshot);
+  registerDiffTools(server2, useCases.diff);
+  registerAuditTools(server2, useCases.audit);
+  registerSnapshotTools(server2, useCases.snapshot);
+  registerCatalogTools(server2, useCases.catalog);
+}
+// src/index.ts
+var browserPool = new BrowserPool();
+var htmlBuilder = new HtmlBuilder();
+var imageComparator = new ImageComparator();
+var snapshotStore = new SnapshotStore();
+var renderUseCase = new RenderUseCase(
+  browserPool,
+  htmlBuilder,
+  imageComparator
+);
+var screenshotUseCase = new ScreenshotUseCase(browserPool);
+var diffUseCase = new DiffUseCase(renderUseCase, imageComparator);
+var auditUseCase = new AuditUseCase(browserPool, htmlBuilder);
+var snapshotUseCase = new SnapshotUseCase(
+  snapshotStore,
+  renderUseCase,
+  diffUseCase
 );
-server.tool(
-  "screenshot_url",
-  "Take a screenshot of a URL (e.g. localhost:3000) across multiple browser engines in parallel.",
-  {
-    url: external_exports.string().url().describe("URL to screenshot"),
-    engines: external_exports.array(external_exports.enum(["chromium", "firefox", "webkit"])).optional().default(["chromium"]).describe("Browser engines"),
-    width: external_exports.number().optional().default(1280).describe("Viewport width (px)"),
-    height: external_exports.number().optional().default(800).describe("Viewport height (px)"),
-    fullPage: external_exports.boolean().optional().default(true).describe("Capture full scroll height")
-  },
-  async ({ url: url2, engines, width, height, fullPage }) => {
+var catalogUseCase = new CatalogUseCase(renderUseCase);
+async function ensureBrowser() {
+  try {
+    await browserPool.warmup(["chromium"]);
+  } catch {
     try {
-      const results = await screenshotUrl(url2, {
-        width,
-        height,
-        fullPage,
-        engines
-      });
-      const content = results.flatMap((r) => [
-        {
-          type: "image",
-          data: r.image,
-          mimeType: "image/png"
-        },
-        {
-          type: "text",
-          text: `[${r.engine}] ${r.width}x${r.height}`
-        }
-      ]);
-      return { content };
-    } catch (error51) {
-      const msg = error51 instanceof Error ? error51.message : String(error51);
-      return { content: [{ type: "text", text: `Screenshot failed: ${msg}` }], isError: true };
+      execSync("npx playwright install chromium", { stdio: "pipe" });
+      await browserPool.warmup(["chromium"]);
+    } catch {
     }
   }
-);
-var transport = new StdioServerTransport();
-warmup(["chromium"]).catch(() => {
+}
+await ensureBrowser();
+var server = new McpServer({
+  name: "frameshot",
+  version: "0.5.0"
+});
+registerAllTools(server, {
+  render: renderUseCase,
+  screenshot: screenshotUseCase,
+  diff: diffUseCase,
+  audit: auditUseCase,
+  snapshot: snapshotUseCase,
+  catalog: catalogUseCase
 });
+var transport = new StdioServerTransport();
 await server.connect(transport);
 process.on("SIGINT", async () => {
-  await shutdown();
+  await browserPool.shutdown();
   process.exit(0);
 });
 process.on("SIGTERM", async () => {
-  await shutdown();
+  await browserPool.shutdown();
   process.exit(0);
 });