frameshot-mcp 0.11.0 → 0.12.0

package/README.md

@@ -53,7 +53,7 @@ Two lines. Auto-detects changed components. Posts before/after/diff screenshots
 - uses: actions/checkout@v7
   with:
     fetch-depth: 0
-- uses: kamegoro/frameshot@v0.8.0
+- uses: kamegoro/frameshot@v0.11.0
 ```
 
 <p align="center">
@@ -70,7 +70,7 @@ Changed `.tsx`, `.jsx`, `.vue`, `.svelte`, `.astro`, `.mdx` files detected autom
 <summary>Options</summary>
 
 ```yaml
-- uses: kamegoro/frameshot@v0.8.0
+- uses: kamegoro/frameshot@v0.11.0
   with:
     paths: "./src/components/*.tsx"       # default: auto-detect
     extensions: ".jsx,.tsx,.vue"          # default: .jsx,.tsx,.vue,.svelte,.astro,.mdx
@@ -95,6 +95,32 @@ render_file("src/components/Dashboard.tsx")
 
 Resolves your project's real imports, Tailwind config, CSS Modules, and path aliases — not a CDN polyfill.
 
+### Works out of the box with 16 frameworks
+
+| Meta-frameworks | Core libraries |
+|---|---|
+| Next.js, Nuxt, SvelteKit, SolidStart | React, Vue, Svelte |
+| Remix / React Router 7, Gatsby | Solid, Preact |
+| Qwik, Astro, Vike | Lit / Web Components |
+
+Auto-detected from `package.json`. No config needed for the common case. Framework-specific imports (`next/navigation`, `$app/stores`, `useLoaderData`, …) are stubbed automatically so components render in isolation.
+
+### Mock API calls
+
+Components that fetch data from `/api/...` render in their loaded state instead of showing a spinner:
+
+```
+render_file({
+  path: "src/components/UserList.tsx",
+  mock: {
+    "/api/users": [{ id: 1, name: "Alice" }],
+    "/api/posts/*": { status: 200, body: { data: [] } },
+  },
+})
+```
+
+Pattern syntax: path (`/api/users`), glob (`**/api/*`), or full URL.
+
 ---
 
 ## Using with Claude

package/dist/{chunk-FQ3BVCX7.js → chunk-J5JI2IC5.js}

@@ -351,7 +351,7 @@ var ProjectDetector = class {
 
 // src/infrastructure/vite-bundler.ts
 import { existsSync as existsSync4 } from "fs";
-import { createRequire } from "module";
+import { createRequire as createRequire2 } from "module";
 import { dirname as dirname2, join as join18, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 
@@ -360,6 +360,7 @@ import { join as join3 } from "path";
 
 // src/infrastructure/adapters/helpers.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { createRequire } from "module";
 import { join as join2 } from "path";
 function hasDep(pkgPath, names) {
   if (!existsSync2(pkgPath)) return false;
@@ -388,6 +389,20 @@ async function loadPlugin(pkg, fnName) {
   }
   return [];
 }
+async function loadPluginFromProject(projectRoot, pkg, fnName) {
+  try {
+    const require2 = createRequire(join2(projectRoot, "package.json"));
+    const resolvedPath = require2.resolve(pkg);
+    const mod = await import(`file://${resolvedPath}`);
+    const candidate = fnName ? mod[fnName] : mod.default ?? mod;
+    if (typeof candidate === "function") {
+      const result = candidate();
+      return Array.isArray(result) ? result : [result];
+    }
+  } catch {
+  }
+  return loadPlugin(pkg, fnName);
+}
 function loadReactPlugin() {
   return loadPlugin("@vitejs/plugin-react");
 }
@@ -417,13 +432,21 @@ var AstroAdapter = class {
     if (hasInstalled(projectRoot, "react"))
       plugins.push(...await loadReactPlugin());
     if (hasInstalled(projectRoot, "vue"))
-      plugins.push(...await loadPlugin("@vitejs/plugin-vue"));
+      plugins.push(
+        ...await loadPluginFromProject(projectRoot, "@vitejs/plugin-vue")
+      );
     if (hasInstalled(projectRoot, "svelte"))
       plugins.push(
-        ...await loadPlugin("@sveltejs/vite-plugin-svelte", "svelte")
+        ...await loadPluginFromProject(
+          projectRoot,
+          "@sveltejs/vite-plugin-svelte",
+          "svelte"
+        )
       );
     if (hasInstalled(projectRoot, "solid-js"))
-      plugins.push(...await loadPlugin("vite-plugin-solid"));
+      plugins.push(
+        ...await loadPluginFromProject(projectRoot, "vite-plugin-solid")
+      );
     return plugins;
   }
   useFrameshotVite() {
@@ -482,15 +505,25 @@ var GenericAdapter = class {
     if (hasInstalled(projectRoot, "react"))
       plugins.push(...await loadReactPlugin());
     if (hasInstalled(projectRoot, "vue"))
-      plugins.push(...await loadPlugin("@vitejs/plugin-vue"));
+      plugins.push(
+        ...await loadPluginFromProject(projectRoot, "@vitejs/plugin-vue")
+      );
     if (hasInstalled(projectRoot, "svelte"))
       plugins.push(
-        ...await loadPlugin("@sveltejs/vite-plugin-svelte", "svelte")
+        ...await loadPluginFromProject(
+          projectRoot,
+          "@sveltejs/vite-plugin-svelte",
+          "svelte"
+        )
       );
     if (hasInstalled(projectRoot, "solid-js"))
-      plugins.push(...await loadPlugin("vite-plugin-solid"));
+      plugins.push(
+        ...await loadPluginFromProject(projectRoot, "vite-plugin-solid")
+      );
     if (hasInstalled(projectRoot, "preact"))
-      plugins.push(...await loadPlugin("@preact/preset-vite"));
+      plugins.push(
+        ...await loadPluginFromProject(projectRoot, "@preact/preset-vite")
+      );
     return plugins;
   }
   useFrameshotVite() {
@@ -588,8 +621,8 @@ var NuxtAdapter = class {
   getOptimizeDeps(_root) {
     return ["vue"];
   }
-  async getPlugins(_root) {
-    return loadPlugin("@vitejs/plugin-vue");
+  async getPlugins(root) {
+    return loadPluginFromProject(root, "@vitejs/plugin-vue");
   }
   useFrameshotVite() {
     return true;
@@ -743,11 +776,15 @@ var SvelteAdapter = class {
   getOptimizeDeps() {
     return [];
   }
-  async getPlugins(_root) {
-    return loadPlugin("@sveltejs/vite-plugin-svelte", "svelte");
+  async getPlugins(root) {
+    return loadPluginFromProject(
+      root,
+      "@sveltejs/vite-plugin-svelte",
+      "svelte"
+    );
   }
-  useFrameshotVite() {
-    return true;
+  useFrameshotVite(projectRoot) {
+    return projectRoot ? !hasInstalled(projectRoot, "vite") : false;
   }
   skipProjectConfig() {
     return true;
@@ -771,11 +808,15 @@ var SvelteKitAdapter = class {
   getOptimizeDeps(_root) {
     return [];
   }
-  async getPlugins(_root) {
-    return loadPlugin("@sveltejs/vite-plugin-svelte", "svelte");
+  async getPlugins(root) {
+    return loadPluginFromProject(
+      root,
+      "@sveltejs/vite-plugin-svelte",
+      "svelte"
+    );
   }
-  useFrameshotVite() {
-    return true;
+  useFrameshotVite(projectRoot) {
+    return projectRoot ? !hasInstalled(projectRoot, "vite") : false;
   }
   skipProjectConfig() {
     return true;
@@ -861,8 +902,8 @@ var VueAdapter = class {
   getOptimizeDeps() {
     return ["vue"];
   }
-  async getPlugins(_root) {
-    return loadPlugin("@vitejs/plugin-vue");
+  async getPlugins(root) {
+    return loadPluginFromProject(root, "@vitejs/plugin-vue");
   }
   useFrameshotVite() {
     return true;
@@ -910,7 +951,7 @@ var ViteBundler = class {
     const absPath = resolve2(filePath);
     const project = options.projectRoot ? this.detector.detect(join18(options.projectRoot, "package.json")) : this.detector.detect(absPath);
     const adapter = selectAdapter(project.root);
-    if (!project.hasVite && !adapter.useFrameshotVite()) {
+    if (!project.hasVite && !adapter.useFrameshotVite(project.root)) {
       throw new Error(
         `Vite not found in ${project.root}. Install vite: npm install -D vite`
       );
@@ -988,9 +1029,10 @@ try {
       case "solid":
         return `${cssImport}
 import { render } from "solid-js/web";
+import { createComponent } from "solid-js";
 import Component from "${componentPath}";
 const props = ${propsJson};
-render(() => Component(props), document.getElementById("app"));
+render(() => createComponent(Component, props), document.getElementById("app"));
 `;
       case "preact":
         return `${cssImport}
@@ -1010,12 +1052,29 @@ document.getElementById("app").innerHTML = html;
   async ensureServer(project, adapter) {
     const existing = this.servers.get(project.root);
     if (existing) return existing;
-    const vite = adapter.useFrameshotVite() ? await this.importFrameshotVite() : await this.importVite(project.root);
+    const vite = adapter.useFrameshotVite(project.root) ? await this.importFrameshotVite() : await this.importVite(project.root);
     if (!vite) {
       throw new Error(`Failed to import vite for ${project.root}`);
     }
     const adapterPlugins = await adapter.getPlugins(project.root);
     const adapterAliases = adapter.getAliases(project.root, STUBS_DIR);
+    const ORM_PACKAGES = [
+      "@prisma/client",
+      "drizzle-orm",
+      "mongoose",
+      "typeorm",
+      "@mikro-orm/core",
+      "sequelize",
+      "knex",
+      "objection",
+      "bookshelf"
+    ];
+    const ormStub = join18(STUBS_DIR, "orm-proxy.js");
+    for (const pkg of ORM_PACKAGES) {
+      if (existsSync4(join18(project.root, "node_modules", ...pkg.split("/")))) {
+        adapterAliases[pkg] = ormStub;
+      }
+    }
     const aliasEntries = [];
     for (const [key, value] of Object.entries(project.pathAliases)) {
       aliasEntries.push({
@@ -1108,7 +1167,7 @@ document.getElementById("app").innerHTML = html;
   }
   async importFrameshotVite() {
     try {
-      const requireFromHere = createRequire(import.meta.url);
+      const requireFromHere = createRequire2(import.meta.url);
       const vitePath = requireFromHere.resolve("vite");
       const mod = await import(vitePath);
       if (mod && typeof mod === "object" && "createServer" in mod) {
@@ -1127,7 +1186,7 @@ document.getElementById("app").innerHTML = html;
   }
   async importVite(projectRoot) {
     try {
-      const require2 = createRequire(join18(projectRoot, "package.json"));
+      const require2 = createRequire2(join18(projectRoot, "package.json"));
       const vitePath = require2.resolve("vite");
       const mod = await import(vitePath);
       if (mod && typeof mod === "object" && "createServer" in mod) {
@@ -1139,7 +1198,7 @@ document.getElementById("app").innerHTML = html;
   }
   hasPackage(projectRoot, name) {
     try {
-      const require2 = createRequire(join18(projectRoot, "package.json"));
+      const require2 = createRequire2(join18(projectRoot, "package.json"));
       require2.resolve(name);
       return true;
     } catch {
@@ -1369,7 +1428,7 @@ var DiffUseCase = class {
 };
 
 // src/use-cases/render.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync3, writeFileSync } from "fs";
 import { extname as extname2 } from "path";
 
 // src/infrastructure/page-utils.ts
@@ -1468,26 +1527,26 @@ var RenderUseCase = class {
       css: opts.css,
       tailwindVersion: opts.tailwindVersion
     });
-    return Promise.all(
+    const results = await Promise.all(
       opts.engines.map((engine) => this.renderHtml(engine, html, opts))
     );
+    return this.maybeSave(results, opts.outputPath);
   }
   async renderFile(filePath, options = {}) {
     const opts = this.resolveOptions(options);
     const ext = extname2(filePath).toLowerCase();
-    const framework = EXT_TO_FRAMEWORK[ext] ?? "react";
+    const extFramework = EXT_TO_FRAMEWORK[ext] ?? "react";
     let fallbackReason;
     if (this.viteBundler) {
       try {
         const { url } = await this.viteBundler.getUrl(filePath, {
           props: options.props,
-          framework,
           projectRoot: options.projectRoot
         });
-        const results2 = await Promise.all(
+        const raw2 = await Promise.all(
           opts.engines.map((engine) => this.renderUrl(engine, url, opts))
         );
-        return { results: results2, mode: "vite" };
+        return { results: this.maybeSave(raw2, opts.outputPath), mode: "vite" };
       } catch (err) {
         fallbackReason = err instanceof Error ? err.message : String(err);
         process.stderr.write(
@@ -1499,8 +1558,12 @@ var RenderUseCase = class {
       fallbackReason = "Vite bundler not available";
     }
     const code = readFileSync3(filePath, "utf-8");
-    const results = await this.render(code, framework, options);
-    return { results, mode: "cdn", fallbackReason };
+    const raw = await this.render(code, extFramework, options);
+    return {
+      results: this.maybeSave(raw, opts.outputPath),
+      mode: "cdn",
+      fallbackReason
+    };
   }
   async renderInteraction(code, framework, interactions, options = {}) {
     const opts = this.resolveOptions(options);
@@ -1688,6 +1751,19 @@ var RenderUseCase = class {
       height: Math.max(measured.height + AUTO_FIT_PAD * 2, AUTO_FIT_MIN.height)
     };
   }
+  /**
+   * When outputPath is set, write the PNG to disk and replace the inline
+   * base64 with an empty string to keep the MCP response small.
+   */
+  maybeSave(results, outputPath) {
+    if (!outputPath) return results;
+    return results.map((r) => {
+      const filePath = results.length === 1 ? outputPath : outputPath.replace(/\.png$/i, `-${r.engine}.png`);
+      const buf = Buffer.from(r.image, "base64");
+      writeFileSync(filePath, buf);
+      return { ...r, image: "", savedPath: filePath };
+    });
+  }
   resolveOptions(partial) {
     return {
       viewport: partial.viewport ?? DEFAULT_RENDER_OPTIONS.viewport,
@@ -1697,7 +1773,9 @@ var RenderUseCase = class {
       css: partial.css ?? DEFAULT_RENDER_OPTIONS.css,
       tailwindVersion: partial.tailwindVersion ?? DEFAULT_RENDER_OPTIONS.tailwindVersion,
       waitFor: partial.waitFor ?? DEFAULT_RENDER_OPTIONS.waitFor,
-      autoFit: partial.autoFit ?? DEFAULT_RENDER_OPTIONS.autoFit
+      autoFit: partial.autoFit ?? DEFAULT_RENDER_OPTIONS.autoFit,
+      mock: partial.mock,
+      outputPath: partial.outputPath
     };
   }
 };

package/dist/{chunk-AF64XFKX.js → chunk-SPOPEVPM.js}

@@ -10,7 +10,7 @@ import {
   SnapshotStore,
   SnapshotUseCase,
   ViteBundler
-} from "./chunk-FQ3BVCX7.js";
+} from "./chunk-J5JI2IC5.js";
 
 // src/use-cases/watch.ts
 import { watch } from "chokidar";

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   createContainer
-} from "./chunk-AF64XFKX.js";
+} from "./chunk-SPOPEVPM.js";
 import {
   EXT_TO_FRAMEWORK
-} from "./chunk-FQ3BVCX7.js";
+} from "./chunk-J5JI2IC5.js";
 
 // src/cli.ts
 import { mkdirSync } from "fs";

package/dist/index.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   createContainer
-} from "./chunk-AF64XFKX.js";
+} from "./chunk-SPOPEVPM.js";
 import {
   DEVICE_PRESETS,
   EXT_TO_FRAMEWORK,
   __export
-} from "./chunk-FQ3BVCX7.js";
+} from "./chunk-J5JI2IC5.js";
 
 // src/index.ts
 import { execSync } from "child_process";
@@ -14531,6 +14531,9 @@ config(en_default());
 var mockSchema = external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe(
   "Mock network responses. Keys: URL pattern (path '/api/users', glob '**/api/*', or full URL). Values: response body (auto-serialized as JSON) or { status, contentType, body, headers }."
 );
+var outputPathSchema = external_exports.string().optional().describe(
+  "Absolute path to save the PNG (e.g. '/tmp/button.png'). When set, returns a text summary instead of base64 image data \u2014 use this in long agent sessions to avoid context bloat."
+);
 function wrapHandler(handler) {
   return async (args) => {
     try {
@@ -14893,7 +14896,8 @@ function registerRenderFileTools(server2, useCase) {
       projectRoot: external_exports.string().optional().describe(
         "Project root directory override (defaults to auto-detect from file path)"
       ),
-      mock: mockSchema
+      mock: mockSchema,
+      outputPath: outputPathSchema
     },
     wrapHandler(
       async ({
@@ -14904,7 +14908,8 @@ function registerRenderFileTools(server2, useCase) {
         darkMode,
         tailwindVersion,
         projectRoot,
-        mock
+        mock,
+        outputPath
       }) => {
         const start = performance.now();
         const { results, mode, fallbackReason } = await useCase.renderFile(
@@ -14917,7 +14922,8 @@ function registerRenderFileTools(server2, useCase) {
             darkMode,
             tailwindVersion,
             projectRoot,
-            mock
+            mock,
+            outputPath
           }
         );
         const elapsed = Math.round(performance.now() - start);
@@ -14926,19 +14932,29 @@ function registerRenderFileTools(server2, useCase) {
         const fallbackNote = mode === "cdn" && fallbackReason ? `
 \u2139\uFE0F Fell back to CDN pipeline: ${fallbackReason}
    Imports from node_modules may not resolve. To fix: install vite as a devDep and add a minimal vite.config.` : "";
-        const content = results.flatMap((r) => [
-          {
-            type: "image",
-            data: r.image,
-            mimeType: "image/png"
-          },
-          {
-            type: "text",
-            text: `[${mode}/${framework}] ${r.width}x${r.height} (${elapsed}ms)${r.consoleErrors.length ? `
+        const content = results.flatMap((r) => {
+          if (r.savedPath) {
+            return [
+              {
+                type: "text",
+                text: `\u2713 Saved to ${r.savedPath} (${r.width}\xD7${r.height}, ${elapsed}ms)${fallbackNote}`
+              }
+            ];
+          }
+          return [
+            {
+              type: "image",
+              data: r.image,
+              mimeType: "image/png"
+            },
+            {
+              type: "text",
+              text: `[${mode}/${framework}] ${r.width}x${r.height} (${elapsed}ms)${r.consoleErrors.length ? `
 \u26A0\uFE0F Console errors:
 ${r.consoleErrors.join("\n")}` : ""}${fallbackNote}`
-          }
-        ]);
+            }
+          ];
+        });
         return { content };
       }
     )

package/dist/renderer.d.ts

@@ -30,6 +30,15 @@ interface RenderOptions {
      * }
      */
     mock?: Record<string, unknown>;
+    /**
+     * Write the screenshot to disk instead of returning it inline as base64.
+     * When set, tools return a short text summary ("Saved to /path 400×300 12KB")
+     * instead of the full image data. This prevents large base64 blobs from
+     * filling the LLM's context window in multi-step agent workflows.
+     *
+     * @example outputPath: "/tmp/my-component.png"
+     */
+    outputPath?: string;
 }
 interface ScreenshotResult {
     engine: Engine;
@@ -37,6 +46,8 @@ interface ScreenshotResult {
     width: number;
     height: number;
     consoleErrors: string[];
+    /** Set when outputPath was provided — the image was saved here instead of inline. */
+    savedPath?: string;
 }
 interface DiffResult {
     before: string;
@@ -254,6 +265,11 @@ declare class RenderUseCase {
     private renderUrl;
     private navigateAndWait;
     private resolveAutoFitViewport;
+    /**
+     * When outputPath is set, write the PNG to disk and replace the inline
+     * base64 with an empty string to keep the MCP response small.
+     */
+    private maybeSave;
     private resolveOptions;
 }
 

package/dist/renderer.js

@@ -13,7 +13,7 @@ import {
   SnapshotStore,
   SnapshotUseCase,
   ViteBundler
-} from "./chunk-FQ3BVCX7.js";
+} from "./chunk-J5JI2IC5.js";
 export {
   AuditUseCase,
   BrowserPool,

package/dist/stubs/next-headers.js

@@ -1,4 +1,8 @@
-// Stub for next/headers — server-only APIs that must not crash during component preview
+// Stub for next/headers — server-only APIs that must not crash during component preview.
+//
+// Next.js 15 made headers()/cookies() async. We export both sync and async
+// variants so components compiled for either version work.
+
 const emptyMap = {
   get: () => undefined,
   getAll: () => [],
@@ -10,10 +14,23 @@ const emptyMap = {
   set: () => {},
   delete: () => {},
   toString: () => "",
+  toJSON: () => ({}),
+  append: () => {},
+  [Symbol.iterator]: () => [][Symbol.iterator](),
 };
-export const headers = () => emptyMap;
-export const cookies = () => emptyMap;
-export const draftMode = () => ({
+
+// Next.js 15+: headers() and cookies() are async
+export const headers = async () => emptyMap;
+export const cookies = async () => emptyMap;
+
+// Next.js 15 additions
+export const connection = async () => {};
+export const after = (fn) => {
+  if (typeof fn === "function") fn();
+};
+
+// Draft mode
+export const draftMode = async () => ({
   isEnabled: false,
   enable: () => {},
   disable: () => {},

package/dist/stubs/orm-proxy.js

@@ -0,0 +1,66 @@
+/**
+ * Universal stub for server-only ORM/database packages.
+ *
+ * Prisma, Drizzle, Mongoose, TypeORM etc. require a running database and
+ * Node.js-only modules (net, tls, dns) that break in a browser/Vite context.
+ *
+ * This stub returns a Proxy that:
+ * - Returns empty arrays for .findMany(), .find(), .all() style calls
+ * - Returns null for .findFirst(), .findOne() style calls
+ * - Returns the input for .create(), .update(), .save() style calls
+ * - Returns { count: 0 } for .count(), .deleteMany()
+ * - Chains infinitely (every property returns another proxy)
+ * - Never throws — components render in their "empty data" state
+ */
+
+function makeProxy(depth = 0) {
+  if (depth > 8) return undefined; // prevent infinite chain
+  return new Proxy(() => Promise.resolve([]), {
+    get(_, prop) {
+      if (prop === "then") return undefined; // not a thenable
+      if (prop === Symbol.toPrimitive) return () => "[ORM stub]";
+      if (prop === Symbol.iterator) return function* () {};
+      // Common result shapes
+      if (
+        typeof prop === "string" &&
+        /^(findMany|findAll|all|list|getAll|fetchAll)$/.test(prop)
+      )
+        return () => Promise.resolve([]);
+      if (
+        typeof prop === "string" &&
+        /^(findFirst|findOne|findUnique|get|fetch|findById)$/.test(prop)
+      )
+        return () => Promise.resolve(null);
+      if (
+        typeof prop === "string" &&
+        /^(count|countDocuments|estimatedDocumentCount)$/.test(prop)
+      )
+        return () => Promise.resolve(0);
+      if (
+        typeof prop === "string" &&
+        /^(create|insert|save|update|upsert|set)$/.test(prop)
+      )
+        return (data) => Promise.resolve(data ?? {});
+      if (
+        typeof prop === "string" &&
+        /^(delete|deleteMany|remove|destroy)$/.test(prop)
+      )
+        return () => Promise.resolve({ count: 0 });
+      return makeProxy(depth + 1);
+    },
+    apply() {
+      return Promise.resolve([]);
+    },
+    construct() {
+      return makeProxy(depth + 1);
+    },
+  });
+}
+
+// Default export and named exports both return a proxy
+export default makeProxy();
+export const PrismaClient = () => makeProxy();
+export const drizzle = () => makeProxy();
+export const createClient = () => makeProxy();
+export const getConnection = () => makeProxy();
+export const DataSource = () => makeProxy();

package/dist/stubs/stubs/next-headers.js

@@ -1,4 +1,8 @@
-// Stub for next/headers — server-only APIs that must not crash during component preview
+// Stub for next/headers — server-only APIs that must not crash during component preview.
+//
+// Next.js 15 made headers()/cookies() async. We export both sync and async
+// variants so components compiled for either version work.
+
 const emptyMap = {
   get: () => undefined,
   getAll: () => [],
@@ -10,10 +14,23 @@ const emptyMap = {
   set: () => {},
   delete: () => {},
   toString: () => "",
+  toJSON: () => ({}),
+  append: () => {},
+  [Symbol.iterator]: () => [][Symbol.iterator](),
 };
-export const headers = () => emptyMap;
-export const cookies = () => emptyMap;
-export const draftMode = () => ({
+
+// Next.js 15+: headers() and cookies() are async
+export const headers = async () => emptyMap;
+export const cookies = async () => emptyMap;
+
+// Next.js 15 additions
+export const connection = async () => {};
+export const after = (fn) => {
+  if (typeof fn === "function") fn();
+};
+
+// Draft mode
+export const draftMode = async () => ({
   isEnabled: false,
   enable: () => {},
   disable: () => {},

package/dist/stubs/stubs/orm-proxy.js

@@ -0,0 +1,66 @@
+/**
+ * Universal stub for server-only ORM/database packages.
+ *
+ * Prisma, Drizzle, Mongoose, TypeORM etc. require a running database and
+ * Node.js-only modules (net, tls, dns) that break in a browser/Vite context.
+ *
+ * This stub returns a Proxy that:
+ * - Returns empty arrays for .findMany(), .find(), .all() style calls
+ * - Returns null for .findFirst(), .findOne() style calls
+ * - Returns the input for .create(), .update(), .save() style calls
+ * - Returns { count: 0 } for .count(), .deleteMany()
+ * - Chains infinitely (every property returns another proxy)
+ * - Never throws — components render in their "empty data" state
+ */
+
+function makeProxy(depth = 0) {
+  if (depth > 8) return undefined; // prevent infinite chain
+  return new Proxy(() => Promise.resolve([]), {
+    get(_, prop) {
+      if (prop === "then") return undefined; // not a thenable
+      if (prop === Symbol.toPrimitive) return () => "[ORM stub]";
+      if (prop === Symbol.iterator) return function* () {};
+      // Common result shapes
+      if (
+        typeof prop === "string" &&
+        /^(findMany|findAll|all|list|getAll|fetchAll)$/.test(prop)
+      )
+        return () => Promise.resolve([]);
+      if (
+        typeof prop === "string" &&
+        /^(findFirst|findOne|findUnique|get|fetch|findById)$/.test(prop)
+      )
+        return () => Promise.resolve(null);
+      if (
+        typeof prop === "string" &&
+        /^(count|countDocuments|estimatedDocumentCount)$/.test(prop)
+      )
+        return () => Promise.resolve(0);
+      if (
+        typeof prop === "string" &&
+        /^(create|insert|save|update|upsert|set)$/.test(prop)
+      )
+        return (data) => Promise.resolve(data ?? {});
+      if (
+        typeof prop === "string" &&
+        /^(delete|deleteMany|remove|destroy)$/.test(prop)
+      )
+        return () => Promise.resolve({ count: 0 });
+      return makeProxy(depth + 1);
+    },
+    apply() {
+      return Promise.resolve([]);
+    },
+    construct() {
+      return makeProxy(depth + 1);
+    },
+  });
+}
+
+// Default export and named exports both return a proxy
+export default makeProxy();
+export const PrismaClient = () => makeProxy();
+export const drizzle = () => makeProxy();
+export const createClient = () => makeProxy();
+export const getConnection = () => makeProxy();
+export const DataSource = () => makeProxy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frameshot-mcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Zero-config visual testing for AI agents. Render project components with full Vite dependency resolution — no stories, no config.",
   "type": "module",
   "main": "dist/index.js",