frameshot-mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,57 +1,24 @@
 # frameshot
 
-> Instant cross-browser component preview for AI agents. One call, one screenshot — no dev server, no Storybook, no ceremony.
+[![npm version](https://img.shields.io/npm/v/frameshot-mcp)](https://www.npmjs.com/package/frameshot-mcp) [![npm downloads](https://img.shields.io/npm/dm/frameshot-mcp)](https://www.npmjs.com/package/frameshot-mcp) [![GitHub stars](https://img.shields.io/github/stars/kamegoro/frameshot)](https://github.com/kamegoro/frameshot) [![CI](https://github.com/kamegoro/frameshot/actions/workflows/ci.yml/badge.svg)](https://github.com/kamegoro/frameshot/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Works with:** Claude Code · Cursor · Codex · Windsurf · any MCP-compatible tool
+> Give your AI agent eyes. Render UI components and get screenshots back — in 120ms.
 
-## The Problem
+<!-- TODO: demo GIF here -->
+<!-- ![demo](docs/demo.gif) -->
 
-You're building UI with an AI agent. The agent writes a component but can't see it. You have to:
-1. Start the dev server
-2. Log in
-3. Navigate to the right page
-4. Scroll to the component
-5. Tell the agent what's wrong
-
-**frameshot** skips all of that. The agent renders the component itself, sees the result, and fixes it.
-
-## Quick Start
-
-### Claude Code
-
-```bash
-claude mcp add frameshot -- npx frameshot-mcp@latest
 ```
-
-That's it. Now your AI agent can see UI.
-
-### Cursor (`.cursor/mcp.json`)
-
-```json
-{
-  "mcpServers": {
-    "frameshot": {
-      "command": "npx",
-      "args": ["frameshot-mcp@latest"]
-    }
-  }
-}
+AI writes code → AI calls frameshot → AI sees the result → AI self-corrects
 ```
 
-### VS Code Copilot (`.vscode/mcp.json`)
+## Install
 
-```json
-{
-  "servers": {
-    "frameshot": {
-      "command": "npx",
-      "args": ["frameshot-mcp@latest"]
-    }
-  }
-}
+```bash
+claude mcp add frameshot -- npx frameshot-mcp@latest
 ```
 
-### Manual setup
+<details>
+<summary>Cursor / VS Code / Other</summary>
 
 ```json
 {
@@ -64,115 +31,62 @@ That's it. Now your AI agent can see UI.
 }
 ```
 
-> **Note:** On first run, Playwright will download Chromium (~150MB). For additional engines: `npx playwright install firefox webkit`
+</details>
 
 ## Tools
 
-### `render_component`
+| Tool | What it does |
+|------|-------------|
+| `render_component` | Render React/Vue/Svelte/HTML → screenshot. Tailwind built-in. |
+| `render_responsive` | Render at mobile + tablet + desktop in one call. |
+| `render_variants` | Render multiple prop/state variants in one call. |
+| `screenshot_url` | Screenshot any URL (e.g. localhost:3000). |
+| `audit_a11y` | Run axe-core accessibility audit on your component. |
+| `diff_component` | Visual regression: compare before/after code, get pixel diff. |
+| `capture_animation` | Capture CSS animation frames over time (multi-screenshot). |
 
-Render isolated component code → get screenshot back instantly.
+### Example
 
 ```typescript
 render_component({
-  code: `
-    function App() {
-      return (
-        <div className="p-8 bg-gradient-to-r from-blue-500 to-purple-600 rounded-xl">
-          <h1 className="text-4xl font-bold text-white">Hello World</h1>
-        </div>
-      )
-    }
-  `,
+  code: `function App() {
+    return <div className="p-8 bg-blue-500 text-white rounded-xl">Hello</div>
+  }`,
   framework: "react",
+  darkMode: true,
   engines: ["chromium", "firefox", "webkit"]
 })
-// Returns 3 screenshots — one per browser engine
 ```
 
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `code` | required | Component source code |
-| `framework` | `"react"` | `"react"` · `"vue"` · `"html"` |
-| `engines` | `["chromium"]` | Browser engines to render in |
-| `width` | `1280` | Viewport width |
-| `height` | `800` | Viewport height |
-| `fullPage` | `true` | Capture full scroll height |
-
-### `screenshot_url`
-
-Screenshot a running app (e.g. localhost) across browsers.
-
-```typescript
-screenshot_url({
-  url: "http://localhost:3000/components/button",
-  engines: ["chromium", "firefox", "webkit"]
-})
-```
-
-## Why Not Storybook?
+## Why frameshot?
 
 | | Storybook | frameshot |
 |---|-----------|-----------|
-| Setup | Write .stories.tsx, configure addons, run server | **Zero** — pass code, get image |
-| Speed | Heavy dev server startup | **~800ms** warm render |
-| Cross-browser | Chromatic ($149+/mo) | **Free** — Playwright built-in |
-| AI-native | Requires pre-written stories | **Works with any code snippet** |
-| Auth required? | Need full app context | **No** — isolated component render |
-
-frameshot is not a Storybook replacement. Storybook is for documentation and design systems. frameshot is for **seeing what you just wrote, right now**.
+| Setup | .stories.tsx + addons + server | **Zero** |
+| Speed | Dev server startup | **~120ms** |
+| Cross-browser | Chromatic ($149+/mo) | **Free** |
+| AI-native | Needs pre-written stories | **Any code snippet** |
 
 ## Performance
 
 | Scenario | Time |
 |----------|------|
-| Warm render (browser reused) | **~800ms** |
-| Cold start (first render) | ~3-5s |
-| Cross-browser (3 engines parallel) | ~1-2s warm |
-
-The browser stays warm between calls. Second render onwards is sub-second.
+| Warm render | **~120ms** |
+| Cold start | ~4s |
+| 3 engines parallel | ~300ms |
 
-## Framework Support
-
-### React (JSX + Tailwind)
-```jsx
-function App() {
-  const [count, setCount] = React.useState(0)
-  return <button onClick={() => setCount(c => c+1)} className="btn">{count}</button>
-}
-```
-
-### Vue 3 (Composition API + Tailwind)
-```javascript
-const App = {
-  setup() {
-    const count = ref(0)
-    return { count }
-  },
-  template: `<button @click="count++">{{ count }}</button>`
-}
-```
-
-### HTML (+ Tailwind)
-```html
-<div class="flex gap-4 p-8">
-  <button class="px-4 py-2 bg-blue-500 text-white rounded">Click me</button>
-</div>
-```
+Browser pool stays warm. Tailwind pre-cached. Sub-200ms after first run.
 
-## Environment Variables
+## Recipes
 
-| Variable | Description |
-|----------|-------------|
-| `FRAMESHOT_BROWSER_PATH` | Custom Chromium executable path |
+- [Claude Code skill setup](examples/claude-code-skill.md) — Auto-preview components with `/project:preview`
+- [Cursor rules](examples/cursor-rules.md) — Auto-verify UI on every edit
 
 ## Development
 
 ```bash
-git clone https://github.com/kamegoro/frameshot.git
-cd frameshot
-npm install
-npx playwright install chromium
-npm run build
+git clone https://github.com/kamegoro/frameshot.git && cd frameshot
+npm install && npx playwright install chromium && npm run build
 ```
 
 ## License

package/dist/index.js

@@ -6,6 +6,7 @@ var __export = (target, all) => {
 };
 
 // src/index.ts
+import { execSync } from "child_process";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -14524,7 +14525,9 @@ function date4(params) {
 config(en_default());
 
 // src/renderer.ts
+import pixelmatch from "pixelmatch";
 import { chromium, firefox, webkit } from "playwright";
+import { PNG } from "pngjs";
 var pool = /* @__PURE__ */ new Map();
 var ENGINES = ["chromium", "firefox", "webkit"];
 async function warmup(engines = ENGINES) {
@@ -14542,66 +14545,90 @@ async function getSlot(engine) {
       headless: true,
       ...engine === "chromium" ? { channel: "chrome" } : {}
     });
-  } catch (e) {
-    throw new Error(`${engine} is not installed. Run: npx playwright install ${engine}`);
+  } 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" }
+  );
   const slot = { browser, page, ready: true };
   pool.set(engine, slot);
   return slot;
 }
-function wrapComponent(code, framework) {
+function wrapComponent(code, framework, darkMode = false, css = "") {
   const tailwind = '<script src="https://cdn.tailwindcss.com?plugins=forms,typography,aspect-ratio"></script>';
+  const tailwindConfig = `<script>tailwind.config={darkMode:'class'}</script>`;
+  const customCss = css ? `<style>${css}</style>` : "";
   const baseStyle = `<style>*{margin:0;box-sizing:border-box}body{padding:16px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif}</style>`;
+  const htmlClass = darkMode ? ' class="dark"' : "";
   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>`;
+    return `<!DOCTYPE html><html${htmlClass}><head><meta charset="utf-8">${tailwind}${tailwindConfig}${baseStyle}${customCss}</head><body>${code}</body></html>`;
   }
   if (framework === "react") {
-    return `<!DOCTYPE html><html><head><meta charset="utf-8">${tailwind}
+    const cleanedCode = code.replace(/['"]use client['"];?\n?/g, "").replace(/['"]use server['"];?\n?/g, "").replace(/import\s+.*?\s+from\s+['"]next\/image['"];?\n?/g, "").replace(/import\s+.*?\s+from\s+['"]next\/link['"];?\n?/g, "");
+    return `<!DOCTYPE html><html${htmlClass}><head><meta charset="utf-8">${tailwind}${tailwindConfig}
 <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>
+${baseStyle}${customCss}</head><body><div id="root"></div>
 <script type="text/babel">
-${code}
+const Image = (props) => React.createElement('img', {...props, src: props.src?.src || props.src});
+const Link = ({href, children, ...props}) => React.createElement('a', {href, ...props}, children);
+${cleanedCode}
 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}
+    return `<!DOCTYPE html><html${htmlClass}><head><meta charset="utf-8">${tailwind}${tailwindConfig}
 <script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
-${baseStyle}</head><body><div id="app"></div>
+${baseStyle}${customCss}</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>`;
+  }
+  if (framework === "svelte") {
+    return `<!DOCTYPE html><html${htmlClass}><head><meta charset="utf-8">${tailwind}${tailwindConfig}
+<script src="https://unpkg.com/svelte@4/compiler.cjs"></script>
+${baseStyle}${customCss}</head><body><div id="app"></div>
+<script type="module">
+import "https://unpkg.com/svelte@4/internal/index.mjs";
+${code}
+const _C=typeof App!=='undefined'?App:typeof Component!=='undefined'?Component:null;
+if(_C)new _C({target:document.getElementById('app')});
 </script></body></html>`;
   }
   return code;
 }
 async function renderSingle(engine, html, options) {
-  const {
-    width = 1280,
-    height = 800,
-    fullPage = true,
-    waitFor = 0
-  } = options;
+  const { width = 1280, height = 800, fullPage = true, waitFor = 0 } = options;
   const slot = await getSlot(engine);
   const { page } = slot;
+  const consoleErrors = [];
+  const onError = (msg) => {
+    if (msg.type() === "error") {
+      consoleErrors.push(msg.text());
+    }
+  };
+  page.on("console", onError);
+  page.on("pageerror", (err) => consoleErrors.push(err.message));
   const currentViewport = page.viewportSize();
   if (currentViewport?.width !== width || currentViewport?.height !== height) {
     await page.setViewportSize({ width, height });
   }
-  await page.setContent(html, { waitUntil: "domcontentloaded", timeout: 1e4 });
-  await page.waitForLoadState("networkidle", { timeout: 5e3 }).catch(() => {
-  });
+  await page.setContent(html, { waitUntil: "load", timeout: 1e4 });
   if (waitFor > 0) {
     await page.waitForTimeout(waitFor);
   }
@@ -14610,16 +14637,23 @@ async function renderSingle(engine, html, options) {
     w: document.documentElement.scrollWidth,
     h: document.documentElement.scrollHeight
   }));
+  page.removeListener("console", onError);
   return {
     engine,
     image: screenshot.toString("base64"),
     width: metrics.w,
-    height: metrics.h
+    height: metrics.h,
+    consoleErrors
   };
 }
 async function render(code, framework, options = {}) {
   const engines = options.engines ?? ["chromium"];
-  const html = wrapComponent(code, framework);
+  const html = wrapComponent(
+    code,
+    framework,
+    options.darkMode ?? false,
+    options.css ?? ""
+  );
   const results = await Promise.all(
     engines.map((e) => renderSingle(e, html, options))
   );
@@ -14629,9 +14663,22 @@ 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 {
+        width = 1280,
+        height = 800,
+        fullPage = true,
+        waitFor = 0
+      } = options;
       const slot = await getSlot(engine);
       const { page } = slot;
+      const consoleErrors = [];
+      const onError = (msg) => {
+        if (msg.type() === "error") {
+          consoleErrors.push(msg.text());
+        }
+      };
+      page.on("console", onError);
+      page.on("pageerror", (err) => consoleErrors.push(err.message));
       const currentViewport = page.viewportSize();
       if (currentViewport?.width !== width || currentViewport?.height !== height) {
         await page.setViewportSize({ width, height });
@@ -14647,11 +14694,137 @@ async function screenshotUrl(url2, options = {}) {
         w: document.documentElement.scrollWidth,
         h: document.documentElement.scrollHeight
       }));
-      return { engine, image: screenshot.toString("base64"), width: metrics.w, height: metrics.h };
+      page.removeListener("console", onError);
+      return {
+        engine,
+        image: screenshot.toString("base64"),
+        width: metrics.w,
+        height: metrics.h,
+        consoleErrors
+      };
     })
   );
   return results;
 }
+async function auditA11y(code, framework, options = {}) {
+  const html = wrapComponent(
+    code,
+    framework,
+    options.darkMode ?? false,
+    options.css ?? ""
+  );
+  const slot = await getSlot("chromium");
+  const { page } = slot;
+  const { width = 1280, height = 800 } = options;
+  const currentViewport = page.viewportSize();
+  if (currentViewport?.width !== width || currentViewport?.height !== height) {
+    await page.setViewportSize({ width, height });
+  }
+  await page.setContent(html, { waitUntil: "load", timeout: 1e4 });
+  const axeSource = await import("axe-core").then((m) => m.source);
+  await page.addScriptTag({ content: axeSource });
+  const results = await page.evaluate(() => {
+    return window.axe.run();
+  });
+  return {
+    violations: results.violations.map(
+      (v) => ({
+        id: v.id,
+        impact: v.impact,
+        description: v.description,
+        helpUrl: v.helpUrl,
+        nodes: v.nodes.map((n) => ({
+          html: n.html,
+          target: n.target
+        }))
+      })
+    ),
+    passes: results.passes.length,
+    incomplete: results.incomplete.length
+  };
+}
+async function diffComponent(before, after, framework, options = {}) {
+  const [beforeResults, afterResults] = await Promise.all([
+    render(before, framework, { ...options, engines: ["chromium"] }),
+    render(after, framework, { ...options, engines: ["chromium"] })
+  ]);
+  const beforeBuf = Buffer.from(beforeResults[0].image, "base64");
+  const afterBuf = Buffer.from(afterResults[0].image, "base64");
+  const beforePng = PNG.sync.read(beforeBuf);
+  const afterPng = PNG.sync.read(afterBuf);
+  const width = Math.max(beforePng.width, afterPng.width);
+  const height = Math.max(beforePng.height, afterPng.height);
+  const normalizedBefore = new PNG({ width, height });
+  const normalizedAfter = new PNG({ width, height });
+  PNG.bitblt(
+    beforePng,
+    normalizedBefore,
+    0,
+    0,
+    beforePng.width,
+    beforePng.height,
+    0,
+    0
+  );
+  PNG.bitblt(
+    afterPng,
+    normalizedAfter,
+    0,
+    0,
+    afterPng.width,
+    afterPng.height,
+    0,
+    0
+  );
+  const diffPng = new PNG({ width, height });
+  const diffPixels = pixelmatch(
+    normalizedBefore.data,
+    normalizedAfter.data,
+    diffPng.data,
+    width,
+    height,
+    { threshold: 0.1 }
+  );
+  const totalPixels = width * height;
+  return {
+    before: beforeResults[0].image,
+    after: afterResults[0].image,
+    diff: PNG.sync.write(diffPng).toString("base64"),
+    diffPixels,
+    totalPixels,
+    diffPercentage: Math.round(diffPixels / totalPixels * 1e4) / 100
+  };
+}
+async function captureAnimation(code, framework, options = {}) {
+  const { frames = 5, duration: duration3 = 1e3 } = options;
+  const html = wrapComponent(
+    code,
+    framework,
+    options.darkMode ?? false,
+    options.css ?? ""
+  );
+  const slot = await getSlot("chromium");
+  const { page } = slot;
+  const { width = 1280, height = 800 } = options;
+  const currentViewport = page.viewportSize();
+  if (currentViewport?.width !== width || currentViewport?.height !== height) {
+    await page.setViewportSize({ width, height });
+  }
+  await page.setContent(html, { waitUntil: "load", timeout: 1e4 });
+  const interval = duration3 / (frames - 1);
+  const results = [];
+  for (let i = 0; i < frames; i++) {
+    if (i > 0) {
+      await page.waitForTimeout(interval);
+    }
+    const screenshot = await page.screenshot({ type: "png", fullPage: false });
+    results.push({
+      timestamp: Math.round(i * interval),
+      image: screenshot.toString("base64")
+    });
+  }
+  return results;
+}
 async function shutdown() {
   for (const slot of pool.values()) {
     await slot.browser.close().catch(() => {
@@ -14661,6 +14834,18 @@ async function shutdown() {
 }
 
 // src/index.ts
+async function ensureBrowser() {
+  try {
+    await warmup(["chromium"]);
+  } catch {
+    try {
+      execSync("npx playwright install chromium", { stdio: "pipe" });
+      await warmup(["chromium"]);
+    } catch {
+    }
+  }
+}
+await ensureBrowser();
 var server = new McpServer({
   name: "frameshot",
   version: "0.1.0"
@@ -14670,20 +14855,47 @@ server.tool(
   "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.'),
+    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")
+    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)")
   },
-  async ({ code, framework, engines, width, height, fullPage }) => {
+  async ({
+    code,
+    framework,
+    engines,
+    width,
+    height,
+    fullPage,
+    darkMode,
+    colorSchemes,
+    css
+  }) => {
     try {
-      const results = await render(code, framework, {
-        width,
-        height,
-        fullPage,
-        engines
-      });
+      const start = performance.now();
+      const schemes = colorSchemes ?? (darkMode ? ["dark"] : ["light"]);
+      const allResults = await Promise.all(
+        schemes.map(
+          (scheme) => render(code, framework, {
+            width,
+            height,
+            fullPage,
+            engines,
+            darkMode: scheme === "dark",
+            css
+          })
+        )
+      );
+      const elapsed = Math.round(performance.now() - start);
+      const results = allResults.flat();
       const content = results.flatMap((r) => [
         {
           type: "image",
@@ -14692,13 +14904,18 @@ server.tool(
         },
         {
           type: "text",
-          text: `[${r.engine}] ${r.width}x${r.height}`
+          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 };
+      return {
+        content: [{ type: "text", text: `Render failed: ${msg}` }],
+        isError: true
+      };
     }
   }
 );
@@ -14728,19 +14945,276 @@ server.tool(
         },
         {
           type: "text",
-          text: `[${r.engine}] ${r.width}x${r.height}`
+          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);
-      return { content: [{ type: "text", text: `Screenshot failed: ${msg}` }], isError: true };
+      return {
+        content: [{ type: "text", text: `Screenshot failed: ${msg}` }],
+        isError: true
+      };
+    }
+  }
+);
+var DEVICE_PRESETS = {
+  mobile: { width: 375, height: 667 },
+  tablet: { width: 768, height: 1024 },
+  desktop: { width: 1280, height: 800 }
+};
+server.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 render(code, framework, {
+            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
+      };
+    }
+  }
+);
+server.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 render(overrideCode, renderFramework, {
+            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
+      };
+    }
+  }
+);
+server.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 auditA11y(code, framework, { 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
+      };
+    }
+  }
+);
+server.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 diffComponent(before, after, framework, {
+        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
+      };
+    }
+  }
+);
+server.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 captureAnimation(code, framework, {
+        frames,
+        duration: duration3,
+        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
+      };
     }
   }
 );
 var transport = new StdioServerTransport();
-warmup(["chromium"]).catch(() => {
-});
 await server.connect(transport);
 process.on("SIGINT", async () => {
   await shutdown();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frameshot-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Instant cross-browser component preview for AI agents. One MCP call, one screenshot — no dev server, no Storybook, no ceremony.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,6 +17,9 @@
     "dev": "tsup src/index.ts --format esm --watch",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "format": "biome format --write src/",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -49,10 +52,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "playwright": "^1.52.0"
+    "axe-core": "^4.12.1",
+    "pixelmatch": "^7.2.0",
+    "playwright": "^1.52.0",
+    "pngjs": "^7.0.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
     "@types/node": "^22.0.0",
+    "@types/pngjs": "^6.0.5",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0"
   },