frameshot-mcp 0.9.7 → 0.11.0

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

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

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

@@ -264,6 +264,7 @@ var SnapshotStore = class {
 // src/infrastructure/project-detector.ts
 import { existsSync, readFileSync } from "fs";
 import { dirname, join, resolve } from "path";
+import { parseTsconfig } from "get-tsconfig";
 var VITE_CONFIG_NAMES = [
   "vite.config.ts",
   "vite.config.js",
@@ -274,9 +275,10 @@ var ProjectDetector = class {
   detect(filePath) {
     const root = this.findProjectRoot(filePath);
     const viteConfigPath = this.findViteConfig(root);
-    const framework = this.detectFramework(root);
+    const pkg = this.readPackageJson(root);
+    const framework = this.detectFramework(pkg);
     const hasVite = this.checkViteAvailable(root);
-    const isNextJs = this.checkIsNextJs(root);
+    const isNextJs = this.checkIsNextJs(pkg);
     const pathAliases = this.readTsconfigAliases(root);
     return { root, viteConfigPath, framework, hasVite, isNextJs, pathAliases };
   }
@@ -299,48 +301,41 @@ var ProjectDetector = class {
     }
     return void 0;
   }
-  detectFramework(root) {
+  readPackageJson(root) {
     const pkgPath = join(root, "package.json");
-    if (!existsSync(pkgPath)) return "html";
+    if (!existsSync(pkgPath)) return null;
     try {
-      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-      const allDeps = {
-        ...pkg.dependencies,
-        ...pkg.devDependencies
-      };
-      if (allDeps["solid-js"]) return "solid";
-      if (allDeps.preact) return "preact";
-      if (allDeps.react || allDeps["react-dom"]) return "react";
-      if (allDeps.vue) return "vue";
-      if (allDeps.svelte) return "svelte";
+      return JSON.parse(readFileSync(pkgPath, "utf-8"));
     } catch {
+      return null;
     }
+  }
+  detectFramework(pkg) {
+    if (!pkg) return "html";
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (allDeps["solid-js"]) return "solid";
+    if (allDeps.preact) return "preact";
+    if (allDeps.react || allDeps["react-dom"]) return "react";
+    if (allDeps.vue) return "vue";
+    if (allDeps.svelte) return "svelte";
     return "html";
   }
   checkViteAvailable(root) {
     const vitePkgPath = join(root, "node_modules", "vite", "package.json");
     return existsSync(vitePkgPath);
   }
-  checkIsNextJs(root) {
-    const pkgPath = join(root, "package.json");
-    if (!existsSync(pkgPath)) return false;
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-      return !!allDeps.next;
-    } catch {
-      return false;
-    }
+  checkIsNextJs(pkg) {
+    if (!pkg) return false;
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return !!allDeps.next;
   }
   readTsconfigAliases(root) {
     const tscPath = join(root, "tsconfig.json");
     if (!existsSync(tscPath)) return {};
     try {
-      const content = readFileSync(tscPath, "utf-8");
-      const stripped = content.replace(/^\s*\/\/[^\n]*/gm, "");
-      const tsc = JSON.parse(stripped);
-      const paths = tsc.compilerOptions?.paths ?? {};
-      const baseUrl = tsc.compilerOptions?.baseUrl ?? ".";
+      const tsconfig = parseTsconfig(tscPath);
+      const paths = tsconfig.compilerOptions?.paths ?? {};
+      const baseUrl = tsconfig.compilerOptions?.baseUrl ?? ".";
       const result = {};
       for (const [alias, targets] of Object.entries(paths)) {
         const key = alias.replace(/\/\*$/, "");
@@ -1378,6 +1373,7 @@ import { readFileSync as readFileSync3 } from "fs";
 import { extname as extname2 } from "path";
 
 // src/infrastructure/page-utils.ts
+import picomatch from "picomatch";
 function attachConsoleCapture(page) {
   const errors = [];
   const onMessage = (msg) => {
@@ -1394,6 +1390,46 @@ function attachConsoleCapture(page) {
     }
   };
 }
+function normalizeResponse(value) {
+  if (value && typeof value === "object" && "body" in value) {
+    return value;
+  }
+  return { body: value };
+}
+async function attachMocks(page, mocks) {
+  const matchers = Object.entries(mocks).map(([pattern, value]) => ({
+    pattern,
+    isMatch: pattern.startsWith("http") ? (url) => url === pattern : picomatch(pattern, { dot: true }),
+    response: normalizeResponse(value)
+  }));
+  if (matchers.length === 0) return;
+  await page.route("**/*", async (route) => {
+    const url = route.request().url();
+    const pathname = (() => {
+      try {
+        return new URL(url).pathname;
+      } catch {
+        return url;
+      }
+    })();
+    const hit = matchers.find((m) => m.isMatch(url)) ?? matchers.find((m) => m.isMatch(pathname));
+    if (!hit) {
+      await route.continue();
+      return;
+    }
+    const spec = hit.response;
+    const isString = typeof spec.body === "string";
+    const isBinary = spec.body instanceof Uint8Array || spec.body instanceof ArrayBuffer;
+    const body = isString ? spec.body : isBinary ? Buffer.from(spec.body) : JSON.stringify(spec.body ?? null);
+    const contentType = spec.contentType ?? (isString ? "text/plain" : "application/json");
+    await route.fulfill({
+      status: spec.status ?? 200,
+      contentType,
+      body,
+      headers: spec.headers
+    });
+  });
+}
 async function takeScreenshot(page, engine, fullPage, errors, cleanup) {
   const screenshot = await page.screenshot({ type: "png", fullPage });
   const metrics = await page.evaluate(() => ({
@@ -1440,6 +1476,7 @@ var RenderUseCase = class {
     const opts = this.resolveOptions(options);
     const ext = extname2(filePath).toLowerCase();
     const framework = EXT_TO_FRAMEWORK[ext] ?? "react";
+    let fallbackReason;
     if (this.viteBundler) {
       try {
         const { url } = await this.viteBundler.getUrl(filePath, {
@@ -1452,16 +1489,18 @@ var RenderUseCase = class {
         );
         return { results: results2, mode: "vite" };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        fallbackReason = err instanceof Error ? err.message : String(err);
         process.stderr.write(
-          `[frameshot] Vite pipeline failed (${msg}), falling back to CDN
+          `[frameshot] Vite pipeline failed (${fallbackReason}), falling back to CDN
 `
         );
       }
+    } else {
+      fallbackReason = "Vite bundler not available";
     }
     const code = readFileSync3(filePath, "utf-8");
     const results = await this.render(code, framework, options);
-    return { results, mode: "cdn" };
+    return { results, mode: "cdn", fallbackReason };
   }
   async renderInteraction(code, framework, interactions, options = {}) {
     const opts = this.resolveOptions(options);
@@ -1578,6 +1617,7 @@ var RenderUseCase = class {
     const page = await this.pool.getPage(engine);
     await page.setViewportSize(options.viewport);
     const { errors, cleanup } = attachConsoleCapture(page);
+    if (options.mock) await attachMocks(page, options.mock);
     await page.setContent(html, { waitUntil: "load", timeout: 1e4 });
     if (options.waitFor > 0) await page.waitForTimeout(options.waitFor);
     const result = await takeScreenshot(
@@ -1593,6 +1633,7 @@ var RenderUseCase = class {
   async renderUrl(engine, url, options) {
     const page = await this.pool.getPage(engine);
     const { errors, cleanup } = attachConsoleCapture(page);
+    if (options.mock) await attachMocks(page, options.mock);
     const viewport = options.autoFit ? await this.resolveAutoFitViewport(page, url, options) : options.viewport;
     await page.setViewportSize(viewport);
     await this.navigateAndWait(page, url, options.waitFor);

package/dist/cli.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 import {
   createContainer
-} from "./chunk-VUYZHZBH.js";
+} from "./chunk-AF64XFKX.js";
 import {
   EXT_TO_FRAMEWORK
-} from "./chunk-MEBQ7ZWA.js";
+} from "./chunk-FQ3BVCX7.js";
 
 // src/cli.ts
 import { mkdirSync } from "fs";
 import { resolve as resolve2 } from "path";
+import mri from "mri";
 
 // src/cli/commands.ts
 import { execSync } from "child_process";
@@ -16,6 +17,7 @@ import { readFileSync, writeFileSync } from "fs";
 import { basename, extname, relative, resolve } from "path";
 
 // src/cli/display.ts
+import { createSpinner } from "nanospinner";
 var c = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -50,18 +52,13 @@ function info(label, value) {
   log(`  ${c.gray}${label.padEnd(6)}${c.reset} ${value}`);
 }
 function spinner(text) {
-  let i = 0;
-  const interval = setInterval(() => {
-    process.stderr.write(
-      `\r  ${c.purple}${FRAMES[i % FRAMES.length]}${c.reset} ${c.dim}${text}${c.reset}`
-    );
-    i++;
-  }, 80);
+  const s = createSpinner(`${c.dim}${text}${c.reset}`, {
+    color: "magenta",
+    frames: FRAMES
+  }).start();
   return {
     stop(finalText) {
-      clearInterval(interval);
-      process.stderr.write(`\r  ${c.green}\u2713${c.reset} ${finalText}\x1B[K
-`);
+      s.success({ text: finalText });
     }
   };
 }
@@ -300,39 +297,27 @@ async function cmdDiff(useCase, filePath, flags, outDir) {
 
 // src/cli.ts
 function parseArgs(args) {
-  const command = args[0] ?? "help";
-  const positional = args[1] ?? "";
+  const parsed = mri(args, {
+    alias: { o: "out", r: "recursive", h: "help" },
+    boolean: ["recursive", "help"],
+    string: ["out", "props"],
+    default: { out: ".frameshot", recursive: false }
+  });
+  const [command = "help", positional = ""] = parsed._;
   const flags = {
-    out: ".frameshot",
-    recursive: false
+    out: parsed.out,
+    recursive: parsed.recursive,
+    width: parsed.width ? Number(parsed.width) : void 0,
+    height: parsed.height ? Number(parsed.height) : void 0
   };
-  for (let i = 2; i < args.length; i++) {
-    const arg = args[i];
-    switch (arg) {
-      case "--props":
-        try {
-          flags.props = JSON.parse(args[++i]);
-        } catch {
-          error("Invalid --props JSON");
-        }
-        break;
-      case "--out":
-      case "-o":
-        flags.out = args[++i];
-        break;
-      case "--recursive":
-      case "-r":
-        flags.recursive = true;
-        break;
-      case "--width":
-        flags.width = Number.parseInt(args[++i], 10);
-        break;
-      case "--height":
-        flags.height = Number.parseInt(args[++i], 10);
-        break;
+  if (parsed.props) {
+    try {
+      flags.props = JSON.parse(parsed.props);
+    } catch {
+      error("Invalid --props JSON");
     }
   }
-  return { command, positional, flags };
+  return { command: String(command), positional: String(positional), flags };
 }
 var HELP = `
   ${brand()} ${c.dim}v0.7.0${c.reset}
@@ -362,7 +347,7 @@ var HELP = `
 `;
 async function main() {
   const { command, positional, flags } = parseArgs(process.argv.slice(2));
-  if (command === "help" || command === "--help" || command === "-h") {
+  if (command === "help") {
     process.stdout.write(HELP);
     return;
   }

package/dist/index.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   createContainer
-} from "./chunk-VUYZHZBH.js";
+} from "./chunk-AF64XFKX.js";
 import {
   DEVICE_PRESETS,
   EXT_TO_FRAMEWORK,
   __export
-} from "./chunk-MEBQ7ZWA.js";
+} from "./chunk-FQ3BVCX7.js";
 
 // src/index.ts
 import { execSync } from "child_process";
@@ -14528,6 +14528,9 @@ function date4(params) {
 config(en_default());
 
 // src/tools/tool-utils.ts
+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 }."
+);
 function wrapHandler(handler) {
   return async (args) => {
     try {
@@ -14889,7 +14892,8 @@ function registerRenderFileTools(server2, useCase) {
       tailwindVersion: external_exports.enum(["3", "4"]).optional().default("3").describe("Tailwind CSS version (3 or 4)"),
       projectRoot: external_exports.string().optional().describe(
         "Project root directory override (defaults to auto-detect from file path)"
-      )
+      ),
+      mock: mockSchema
     },
     wrapHandler(
       async ({
@@ -14899,21 +14903,29 @@ function registerRenderFileTools(server2, useCase) {
         height,
         darkMode,
         tailwindVersion,
-        projectRoot
+        projectRoot,
+        mock
       }) => {
         const start = performance.now();
-        const { results, mode } = await useCase.renderFile(path, {
-          props,
-          viewport: { width, height },
-          fullPage: true,
-          engines: ["chromium"],
-          darkMode,
-          tailwindVersion,
-          projectRoot
-        });
+        const { results, mode, fallbackReason } = await useCase.renderFile(
+          path,
+          {
+            props,
+            viewport: { width, height },
+            fullPage: true,
+            engines: ["chromium"],
+            darkMode,
+            tailwindVersion,
+            projectRoot,
+            mock
+          }
+        );
         const elapsed = Math.round(performance.now() - start);
         const ext = extname(path).toLowerCase();
         const framework = EXT_TO_FRAMEWORK[ext] ?? "react";
+        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",
@@ -14924,7 +14936,7 @@ function registerRenderFileTools(server2, useCase) {
             type: "text",
             text: `[${mode}/${framework}] ${r.width}x${r.height} (${elapsed}ms)${r.consoleErrors.length ? `
 \u26A0\uFE0F Console errors:
-${r.consoleErrors.join("\n")}` : ""}`
+${r.consoleErrors.join("\n")}` : ""}${fallbackNote}`
           }
         ]);
         return { content };
@@ -14948,7 +14960,8 @@ ${r.consoleErrors.join("\n")}` : ""}`
         '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)")
+      tailwindVersion: external_exports.enum(["3", "4"]).optional().default("3").describe("Tailwind CSS version (3 or 4)"),
+      mock: mockSchema
     },
     wrapHandler(
       async ({
@@ -14961,7 +14974,8 @@ ${r.consoleErrors.join("\n")}` : ""}`
         darkMode,
         colorSchemes,
         css,
-        tailwindVersion
+        tailwindVersion,
+        mock
       }) => {
         const start = performance.now();
         const schemes = colorSchemes ?? (darkMode ? ["dark"] : ["light"]);
@@ -14973,7 +14987,8 @@ ${r.consoleErrors.join("\n")}` : ""}`
               engines,
               darkMode: scheme === "dark",
               css,
-              tailwindVersion
+              tailwindVersion,
+              mock
             })
           )
         );
@@ -15560,21 +15575,9 @@ function registerAllTools(server2, useCases) {
 
 // src/index.ts
 var container = createContainer();
-async function ensureBrowser() {
-  try {
-    await container.pool.warmup(["chromium"]);
-  } catch {
-    try {
-      execSync("npx playwright install chromium", { stdio: "pipe" });
-      await container.pool.warmup(["chromium"]);
-    } catch {
-    }
-  }
-}
-await ensureBrowser();
 var server = new McpServer({
   name: "frameshot",
-  version: "0.8.0"
+  version: "0.10.0"
 });
 registerAllTools(server, {
   render: container.renderUseCase,
@@ -15587,6 +15590,18 @@ registerAllTools(server, {
 });
 var transport = new StdioServerTransport();
 await server.connect(transport);
+void (async () => {
+  try {
+    await container.pool.warmup(["chromium"]);
+  } catch {
+    try {
+      execSync("npx playwright install chromium", { stdio: "pipe" });
+      await container.pool.warmup(["chromium"]).catch(() => {
+      });
+    } catch {
+    }
+  }
+})();
 process.on("SIGINT", async () => {
   await container.shutdown();
   process.exit(0);

package/dist/renderer.d.ts

@@ -17,6 +17,19 @@ interface RenderOptions {
     tailwindVersion: "3" | "4";
     waitFor: number;
     autoFit: boolean;
+    /**
+     * Mock network requests. Keys are URL patterns (path like `/api/users`,
+     * glob like `**\/api/*`, or full URLs); values are the response body
+     * (auto-serialized as JSON) or a {@link MockResponse} for full control.
+     *
+     * @example
+     * mock: {
+     *   '/api/users': [{ id: 1, name: 'Alice' }],
+     *   '/api/posts/*': { status: 200, body: { data: [] } },
+     *   'https://api.example.com/x': 'plain text body',
+     * }
+     */
+    mock?: Record<string, unknown>;
 }
 interface ScreenshotResult {
     engine: Engine;
@@ -150,6 +163,7 @@ declare class ProjectDetector {
     detect(filePath: string): ProjectConfig;
     private findProjectRoot;
     private findViteConfig;
+    private readPackageJson;
     private detectFramework;
     private checkViteAvailable;
     private checkIsNextJs;
@@ -204,6 +218,8 @@ declare class RenderUseCase {
     renderFile(filePath: string, options?: Partial<FileRenderOptions>): Promise<{
         results: ScreenshotResult[];
         mode: "vite" | "cdn";
+        /** If we fell back to CDN, the reason the Vite pipeline was skipped. */
+        fallbackReason?: string;
     }>;
     renderInteraction(code: string, framework: Framework, interactions: Interaction[], options?: Partial<RenderOptions>): Promise<{
         image: string;

package/dist/renderer.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frameshot-mcp",
-  "version": "0.9.7",
+  "version": "0.11.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",
@@ -72,6 +72,11 @@
     "@vitejs/plugin-vue": "^6.0.7",
     "axe-core": "^4.12.1",
     "chokidar": "^5.0.0",
+    "get-tsconfig": "^4.14.0",
+    "mri": "^1.2.0",
+    "nanospinner": "^1.2.2",
+    "picocolors": "^1.1.1",
+    "picomatch": "^4.0.4",
     "pixelmatch": "^7.2.0",
     "playwright": "^1.52.0",
     "pngjs": "^7.0.0",
@@ -88,6 +93,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
     "@types/node": "^26.0.0",
+    "@types/picomatch": "^4.0.3",
     "@types/pngjs": "^6.0.5",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",

package/scripts/render-changed.mjs

@@ -3,6 +3,7 @@
 import { execSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { basename, extname, join, relative } from "node:path";
+import picomatch from "picomatch";
 
 const {
   INPUT_PATHS = "",
@@ -26,14 +27,13 @@ const COMPONENT_EXTS = new Set(
   INPUT_EXTENSIONS.split(",").map((e) => e.trim().toLowerCase()).filter(Boolean),
 );
 
-const EXCLUDE_PATTERNS = INPUT_EXCLUDE.split(",")
+// Compile exclude globs once via picomatch — handles `*`, `**`, `?`, `[abc]`,
+// brace expansion, and negation properly. Match against the file basename.
+const excludeGlobs = INPUT_EXCLUDE.split(",")
   .map((p) => p.trim())
-  .filter(Boolean)
-  .map((p) => {
-    // Convert glob pattern to regex: *.test.* → /[^/]*\.test\.[^/]*/
-    const escaped = p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*");
-    return new RegExp(escaped);
-  });
+  .filter(Boolean);
+const isExcludedGlob =
+  excludeGlobs.length > 0 ? picomatch(excludeGlobs) : () => false;
 
 /**
  * Derive a human-friendly display label from a file path.
@@ -80,8 +80,7 @@ function safeFileId(label) {
 }
 
 function isExcluded(filePath) {
-  const base = filePath.split("/").pop() ?? "";
-  return EXCLUDE_PATTERNS.some((re) => re.test(base));
+  return isExcludedGlob(basename(filePath));
 }
 
 function findFiles(workspace, patterns) {
@@ -260,12 +259,17 @@ async function main() {
     try {
       // Render current (after) version
       console.log(`  Rendering (after): ${filePath}`);
-      const { results: afterResults, mode } = await renderUseCase.renderFile(
-        filePath,
-        renderOpts,
-      );
+      const {
+        results: afterResults,
+        mode,
+        fallbackReason,
+      } = await renderUseCase.renderFile(filePath, renderOpts);
       const afterResult = afterResults[0];
 
+      if (mode === "cdn" && fallbackReason) {
+        console.log(`    ℹ️  CDN fallback: ${fallbackReason}`);
+      }
+
       const afterPath = join(outputDir, `${safeName}_after.png`);
       writeFileSync(afterPath, Buffer.from(afterResult.image, "base64"));