frameshot-mcp 0.3.0 → 0.7.0

package/dist/renderer.d.ts

@@ -0,0 +1,297 @@
+import { Page } from 'playwright';
+
+type Engine = "chromium" | "firefox" | "webkit";
+type Framework = "html" | "react" | "vue" | "svelte";
+type Theme = "light" | "dark";
+interface Viewport {
+    width: number;
+    height: number;
+}
+interface RenderOptions {
+    viewport: Viewport;
+    deviceScaleFactor?: number;
+    engines: Engine[];
+    fullPage: boolean;
+    darkMode: boolean;
+    css: string;
+    tailwindVersion: "3" | "4";
+    waitFor: number;
+    autoFit: boolean;
+}
+interface ScreenshotResult {
+    engine: Engine;
+    image: string;
+    width: number;
+    height: number;
+    consoleErrors: string[];
+}
+interface DiffResult {
+    before: string;
+    after: string;
+    diff: string;
+    diffPixels: number;
+    totalPixels: number;
+    diffPercentage: number;
+}
+interface ReferenceDiffResult {
+    rendered: string;
+    diff: string;
+    diffPixels: number;
+    totalPixels: number;
+    diffPercentage: number;
+    passed: boolean;
+}
+interface A11yViolation {
+    id: string;
+    impact: string;
+    description: string;
+    helpUrl: string;
+    nodes: {
+        html: string;
+        target: string[];
+    }[];
+}
+interface A11yResult {
+    violations: A11yViolation[];
+    passes: number;
+    incomplete: number;
+}
+interface PerfMetrics {
+    renderTimeMs: number;
+    domElements: number;
+    domDepth: number;
+    scriptCount: number;
+    styleSheetCount: number;
+    imageCount: number;
+    totalDomSize: number;
+}
+interface AnimationFrame {
+    timestamp: number;
+    image: string;
+}
+interface Interaction {
+    action: "click" | "hover" | "focus" | "type" | "wait";
+    selector?: string;
+    value?: string;
+    ms?: number;
+}
+interface GridCell {
+    label: string;
+    code: string;
+}
+interface Snapshot {
+    image: string;
+    timestamp: number;
+}
+interface CatalogEntry {
+    path: string;
+    framework: Framework;
+    image: string;
+    width: number;
+    height: number;
+    consoleErrors: string[];
+}
+declare const DEVICE_PRESETS: Record<string, Viewport>;
+declare const EXT_TO_FRAMEWORK: Record<string, Framework>;
+interface FileRenderOptions extends RenderOptions {
+    props?: Record<string, unknown>;
+    projectRoot?: string;
+}
+interface ProjectConfig {
+    root: string;
+    viteConfigPath?: string;
+    framework: Framework;
+    hasVite: boolean;
+}
+
+declare class BrowserPool {
+    private pool;
+    warmup(engines: Engine[]): Promise<void>;
+    getPage(engine: Engine): Promise<Page>;
+    setViewport(engine: Engine, viewport: Viewport): Promise<void>;
+    shutdown(): Promise<void>;
+    private getSlot;
+}
+
+declare class HtmlBuilder {
+    build(code: string, framework: Framework, options: {
+        darkMode: boolean;
+        css: string;
+        tailwindVersion: "3" | "4";
+    }): string;
+}
+
+interface DiffComparison {
+    diff: string;
+    diffPixels: number;
+    totalPixels: number;
+    diffPercentage: number;
+}
+declare class ImageComparator {
+    diff(imageA: string, imageB: string, threshold?: number): DiffComparison;
+    composite(images: Buffer[], columns: number, labelHeight?: number): {
+        image: string;
+        width: number;
+        height: number;
+    };
+}
+
+declare class ProjectDetector {
+    detect(filePath: string): ProjectConfig;
+    private findProjectRoot;
+    private findViteConfig;
+    private detectFramework;
+    private checkViteAvailable;
+}
+
+declare class SnapshotStore {
+    private store;
+    save(key: string, image: string): void;
+    get(key: string): Snapshot | undefined;
+    list(): {
+        key: string;
+        timestamp: number;
+    }[];
+}
+
+declare class ViteBundler {
+    private servers;
+    private detector;
+    getUrl(filePath: string, options?: {
+        props?: Record<string, unknown>;
+        framework?: Framework;
+        projectRoot?: string;
+    }): Promise<{
+        url: string;
+        project: ProjectConfig;
+    }>;
+    shutdown(): Promise<void>;
+    private ensureServer;
+    private importVite;
+    private hasPackage;
+    private generateEntry;
+    private findGlobalCss;
+    private getOptimizeDepsInclude;
+}
+
+declare class AuditUseCase {
+    private readonly pool;
+    private readonly htmlBuilder;
+    constructor(pool: BrowserPool, htmlBuilder: HtmlBuilder);
+    auditA11y(code: string, framework: Framework, options?: Partial<RenderOptions>): Promise<A11yResult>;
+    perfAudit(code: string, framework: Framework, options?: Partial<RenderOptions>): Promise<PerfMetrics>;
+}
+
+declare class RenderUseCase {
+    private readonly pool;
+    private readonly htmlBuilder;
+    private readonly imageComparator;
+    private readonly viteBundler?;
+    constructor(pool: BrowserPool, htmlBuilder: HtmlBuilder, imageComparator: ImageComparator, viteBundler?: ViteBundler | undefined);
+    render(code: string, framework: Framework, options?: Partial<RenderOptions>): Promise<ScreenshotResult[]>;
+    renderFile(filePath: string, options?: Partial<FileRenderOptions>): Promise<{
+        results: ScreenshotResult[];
+        mode: "vite" | "cdn";
+    }>;
+    renderInteraction(code: string, framework: Framework, interactions: Interaction[], options?: Partial<RenderOptions>): Promise<{
+        image: string;
+        width: number;
+        height: number;
+    }>;
+    captureAnimation(code: string, framework: Framework, options?: Partial<RenderOptions> & {
+        frames?: number;
+        duration?: number;
+    }): Promise<AnimationFrame[]>;
+    renderGrid(cells: GridCell[], framework: Framework, options?: Partial<RenderOptions> & {
+        columns?: number;
+    }): Promise<{
+        image: string;
+        width: number;
+        height: number;
+        cells: number;
+    }>;
+    renderMatrix(code: string, framework: Framework, viewports: {
+        label: string;
+        width: number;
+        height: number;
+    }[], themes: Theme[], options?: Partial<Omit<RenderOptions, "viewport" | "darkMode">>): Promise<{
+        viewport: string;
+        theme: Theme;
+        image: string;
+        width: number;
+        height: number;
+        consoleErrors: string[];
+    }[]>;
+    private renderHtml;
+    private renderUrl;
+    private navigateAndWait;
+    private resolveAutoFitViewport;
+    private attachConsoleCapture;
+    private takeScreenshot;
+    private resolveOptions;
+}
+
+declare class CatalogUseCase {
+    private readonly renderUseCase;
+    constructor(renderUseCase: RenderUseCase);
+    renderCatalog(directory: string, options?: Partial<RenderOptions> & {
+        recursive?: boolean;
+    }): Promise<CatalogEntry[]>;
+    private scanDirectory;
+    private detectFramework;
+}
+
+interface Renderer {
+    render(code: string, framework: Framework, options?: Partial<RenderOptions>): Promise<ScreenshotResult[]>;
+}
+interface Comparator {
+    diff(a: string, b: string, threshold?: number): DiffComparison;
+}
+declare class DiffUseCase {
+    private readonly renderUseCase;
+    private readonly imageComparator;
+    constructor(renderUseCase: Renderer, imageComparator: Comparator);
+    diffComponent(before: string, after: string, framework: Framework, options?: Partial<RenderOptions>): Promise<DiffResult>;
+    diffFromReference(code: string, framework: Framework, referenceImage: string, options?: Partial<RenderOptions> & {
+        threshold?: number;
+    }): Promise<ReferenceDiffResult>;
+}
+
+interface ScreenshotUrlOptions {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    engines?: Engine[];
+    fullPage?: boolean;
+    waitFor?: number;
+    waitForSelector?: string;
+    waitForNetworkIdle?: boolean;
+}
+declare class ScreenshotUseCase {
+    private readonly pool;
+    constructor(pool: BrowserPool);
+    screenshotUrl(url: string, options?: ScreenshotUrlOptions): Promise<ScreenshotResult[]>;
+    screenshotUrlWithRetry(url: string, options?: ScreenshotUrlOptions & {
+        retryCount?: number;
+    }): Promise<ScreenshotResult[]>;
+}
+
+declare class SnapshotUseCase {
+    private readonly store;
+    private readonly renderUseCase;
+    private readonly diffUseCase;
+    constructor(store: SnapshotStore, renderUseCase: RenderUseCase, diffUseCase: DiffUseCase);
+    save(key: string, code: string, framework: Framework, options?: Partial<RenderOptions>): Promise<{
+        image: string;
+        width: number;
+        height: number;
+    }>;
+    check(key: string, code: string, framework: Framework, options?: Partial<RenderOptions>): Promise<ReferenceDiffResult | null>;
+    list(): {
+        key: string;
+        timestamp: number;
+    }[];
+}
+
+export { type A11yResult, type A11yViolation, type AnimationFrame, AuditUseCase, BrowserPool, type CatalogEntry, CatalogUseCase, DEVICE_PRESETS, type DiffResult, DiffUseCase, EXT_TO_FRAMEWORK, type Engine, type FileRenderOptions, type Framework, type GridCell, HtmlBuilder, ImageComparator, type Interaction, type PerfMetrics, type ProjectConfig, ProjectDetector, type ReferenceDiffResult, type RenderOptions, RenderUseCase, type ScreenshotResult, ScreenshotUseCase, type Snapshot, SnapshotStore, SnapshotUseCase, type Theme, type Viewport, ViteBundler };

package/dist/renderer.js

@@ -0,0 +1,34 @@
+import {
+  AuditUseCase,
+  ScreenshotUseCase,
+  SnapshotStore,
+  SnapshotUseCase
+} from "./chunk-FTYTZW6D.js";
+import {
+  BrowserPool,
+  CatalogUseCase,
+  DEVICE_PRESETS,
+  DiffUseCase,
+  EXT_TO_FRAMEWORK,
+  HtmlBuilder,
+  ImageComparator,
+  ProjectDetector,
+  RenderUseCase,
+  ViteBundler
+} from "./chunk-Q7A3DLED.js";
+export {
+  AuditUseCase,
+  BrowserPool,
+  CatalogUseCase,
+  DEVICE_PRESETS,
+  DiffUseCase,
+  EXT_TO_FRAMEWORK,
+  HtmlBuilder,
+  ImageComparator,
+  ProjectDetector,
+  RenderUseCase,
+  ScreenshotUseCase,
+  SnapshotStore,
+  SnapshotUseCase,
+  ViteBundler
+};

package/package.json

@@ -1,25 +1,39 @@
 {
   "name": "frameshot-mcp",
-  "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.",
+  "version": "0.7.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",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./renderer": {
+      "import": "./dist/renderer.js",
+      "types": "./dist/renderer.d.ts"
+    }
+  },
   "bin": {
-    "frameshot-mcp": "dist/index.js"
+    "frameshot-mcp": "dist/index.js",
+    "frameshot": "dist/cli.js"
   },
   "files": [
     "dist",
+    "scripts",
+    "action.yml",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
-    "dev": "tsup src/index.ts --format esm --watch",
+    "build": "tsup src/index.ts src/renderer.ts src/cli.ts --format esm --dts --external vite",
+    "dev": "tsup src/index.ts src/renderer.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/",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -57,13 +71,24 @@
     "playwright": "^1.52.0",
     "pngjs": "^7.0.0"
   },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
-    "@types/node": "^22.0.0",
+    "@types/node": "^26.0.0",
     "@types/pngjs": "^6.0.5",
     "tsup": "^8.0.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vitest": "^4.1.9"
   },
+  "mcpName": "io.github.kamegoro/frameshot-mcp",
   "engines": {
     "node": ">=20.0.0"
   }

package/scripts/render-changed.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, extname, join, relative } from "node:path";
+
+const {
+  INPUT_PATHS = "",
+  INPUT_WIDTH = "",
+  INPUT_HEIGHT = "",
+  INPUT_BASE_REF = "",
+  GITHUB_WORKSPACE = process.cwd(),
+  GITHUB_OUTPUT = "/dev/null",
+} = process.env;
+
+const outputDir = join(GITHUB_WORKSPACE, ".frameshot-screenshots");
+mkdirSync(outputDir, { recursive: true });
+
+const patterns = INPUT_PATHS.split(/[,\n]/)
+  .map((p) => p.trim())
+  .filter(Boolean);
+
+const COMPONENT_EXTS = new Set([
+  ".jsx",
+  ".tsx",
+  ".vue",
+  ".svelte",
+]);
+
+function findFiles(workspace, patterns) {
+  const allFiles = [];
+  for (const pattern of patterns) {
+    try {
+      const result = execSync(
+        `find ${workspace} -path '${pattern}' -type f 2>/dev/null`,
+        { encoding: "utf-8" },
+      );
+      allFiles.push(...result.split("\n").filter(Boolean));
+    } catch {
+      // Pattern didn't match
+    }
+  }
+  return allFiles.filter((f) => COMPONENT_EXTS.has(extname(f).toLowerCase()));
+}
+
+function getChangedFiles(baseRef) {
+  if (!baseRef) return null;
+  try {
+    const result = execSync(`git diff --name-only ${baseRef}...HEAD`, {
+      encoding: "utf-8",
+      cwd: GITHUB_WORKSPACE,
+    });
+    return new Set(result.split("\n").filter(Boolean));
+  } catch {
+    return null;
+  }
+}
+
+function checkoutFileAtRef(filePath, ref) {
+  const relativePath = relative(GITHUB_WORKSPACE, filePath);
+  try {
+    execSync(`git checkout ${ref} -- ${relativePath}`, {
+      cwd: GITHUB_WORKSPACE,
+      stdio: "pipe",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function restoreFile(filePath) {
+  const relativePath = relative(GITHUB_WORKSPACE, filePath);
+  execSync(`git checkout HEAD -- ${relativePath}`, {
+    cwd: GITHUB_WORKSPACE,
+    stdio: "pipe",
+  });
+}
+
+async function main() {
+  const { BrowserPool, HtmlBuilder, ImageComparator, RenderUseCase, ViteBundler } =
+    await import("frameshot-mcp/renderer");
+
+  const browserPool = new BrowserPool();
+  const htmlBuilder = new HtmlBuilder();
+  const imageComparator = new ImageComparator();
+  const viteBundler = new ViteBundler();
+  const renderUseCase = new RenderUseCase(
+    browserPool,
+    htmlBuilder,
+    imageComparator,
+    viteBundler,
+  );
+
+  await browserPool.warmup(["chromium"]);
+
+  const allFiles = findFiles(GITHUB_WORKSPACE, patterns);
+
+  if (allFiles.length === 0) {
+    console.log("No component files found matching the specified patterns.");
+    await viteBundler.shutdown();
+    await browserPool.shutdown();
+    process.exit(0);
+  }
+
+  const changedFiles = getChangedFiles(INPUT_BASE_REF);
+  const filesToRender = changedFiles
+    ? allFiles.filter((f) => {
+        const rel = relative(GITHUB_WORKSPACE, f);
+        return changedFiles.has(rel);
+      })
+    : allFiles;
+
+  if (filesToRender.length === 0) {
+    console.log("No changed component files to render.");
+    await viteBundler.shutdown();
+    await browserPool.shutdown();
+    process.exit(0);
+  }
+
+  console.log(`Found ${filesToRender.length} component file(s) to render...`);
+
+  const autoFit = !INPUT_WIDTH || !INPUT_HEIGHT;
+  const renderOpts = {
+    viewport: {
+      width: INPUT_WIDTH ? parseInt(INPUT_WIDTH) : 1280,
+      height: INPUT_HEIGHT ? parseInt(INPUT_HEIGHT) : 800,
+    },
+    autoFit,
+    fullPage: true,
+    engines: ["chromium"],
+  };
+
+  const results = [];
+
+  for (const filePath of filesToRender) {
+    const name = basename(filePath, extname(filePath));
+    const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+
+    try {
+      // Render current (after) version
+      console.log(`  Rendering (after): ${filePath}`);
+      const { results: afterResults, mode } = await renderUseCase.renderFile(
+        filePath,
+        renderOpts,
+      );
+      const afterResult = afterResults[0];
+
+      const afterPath = join(outputDir, `${safeName}_after.png`);
+      writeFileSync(afterPath, Buffer.from(afterResult.image, "base64"));
+
+      const entry = {
+        name: safeName,
+        after: afterResult.image,
+        before: null,
+        diff: null,
+        diffPercentage: 0,
+        mode,
+      };
+
+      // Render base (before) version if base_ref is provided
+      if (INPUT_BASE_REF) {
+        const checkedOut = checkoutFileAtRef(filePath, INPUT_BASE_REF);
+        if (checkedOut) {
+          try {
+            console.log(`  Rendering (before): ${filePath}`);
+            const { results: beforeResults } = await renderUseCase.renderFile(
+              filePath,
+              renderOpts,
+            );
+            const beforeResult = beforeResults[0];
+            entry.before = beforeResult.image;
+
+            const beforePath = join(outputDir, `${safeName}_before.png`);
+            writeFileSync(
+              beforePath,
+              Buffer.from(beforeResult.image, "base64"),
+            );
+
+            const diffResult = imageComparator.diff(
+              beforeResult.image,
+              afterResult.image,
+            );
+            entry.diff = diffResult.diff;
+            entry.diffPercentage = diffResult.diffPercentage;
+
+            if (diffResult.diffPercentage > 0) {
+              const diffPath = join(outputDir, `${safeName}_diff.png`);
+              writeFileSync(diffPath, Buffer.from(diffResult.diff, "base64"));
+            }
+          } finally {
+            restoreFile(filePath);
+          }
+        }
+      }
+
+      results.push(entry);
+      console.log(
+        `  ✓ ${safeName} (${afterResult.width}x${afterResult.height}, ${mode})${entry.diffPercentage > 0 ? ` — ${entry.diffPercentage.toFixed(1)}% changed` : ""}`,
+      );
+    } catch (error) {
+      console.error(`  ✗ Failed: ${filePath} — ${error.message}`);
+    }
+  }
+
+  await viteBundler.shutdown();
+  await browserPool.shutdown();
+
+  const manifest = JSON.stringify(
+    results.map((r) => ({
+      name: r.name,
+      hasBefore: r.before !== null,
+      diffPercentage: r.diffPercentage,
+      mode: r.mode,
+    })),
+  );
+  writeFileSync(join(outputDir, "manifest.json"), manifest);
+
+  const hasChanges = results.some((r) => r.diffPercentage > 0 || !r.before);
+  try {
+    const outputContent = `has_changes=${hasChanges}\ncount=${results.length}\n`;
+    writeFileSync(GITHUB_OUTPUT, outputContent, { flag: "a" });
+  } catch {
+    // Not in GitHub Actions
+  }
+
+  console.log(`\nDone. ${results.length} screenshot(s) saved to ${outputDir}`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/scripts/setup-labels.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Setup GitHub labels for the frameshot repository.
+# Usage: ./scripts/setup-labels.sh [owner/repo]
+# Requires: gh CLI authenticated
+
+set -euo pipefail
+
+REPO="${1:-kamegoro/frameshot}"
+
+# Delete default labels that add noise
+for label in "invalid" "wontfix" "help wanted" "question"; do
+  gh label delete "$label" --repo "$REPO" --yes 2>/dev/null || true
+done
+
+# --- Status labels (S-) ---
+gh label create "S-needs triage"    --color "D93F0B" --description "Awaiting maintainer review"        --repo "$REPO" --force
+gh label create "S-accepted"        --color "0E8A16" --description "Confirmed and ready for work"      --repo "$REPO" --force
+gh label create "S-in progress"     --color "1D76DB" --description "Currently being worked on"         --repo "$REPO" --force
+gh label create "S-blocked"         --color "B60205" --description "Waiting on external dependency"    --repo "$REPO" --force
+
+# --- Priority labels (P-) ---
+gh label create "P0-critical"       --color "B60205" --description "Production broken, fix immediately"  --repo "$REPO" --force
+gh label create "P1-high"           --color "D93F0B" --description "Important, fix this week"            --repo "$REPO" --force
+gh label create "P2-medium"         --color "FBCA04" --description "Normal priority"                     --repo "$REPO" --force
+gh label create "P3-low"            --color "0075CA" --description "Nice to have, no urgency"            --repo "$REPO" --force
+
+# --- Type labels ---
+gh label create "bug"               --color "D73A4A" --description "Something isn't working"             --repo "$REPO" --force
+gh label create "enhancement"       --color "A2EEEF" --description "New feature or improvement"          --repo "$REPO" --force
+gh label create "documentation"     --color "0075CA" --description "Documentation improvements"          --repo "$REPO" --force
+gh label create "performance"       --color "F9D0C4" --description "Performance improvement"             --repo "$REPO" --force
+gh label create "breaking change"   --color "B60205" --description "Introduces a breaking change"        --repo "$REPO" --force
+
+# --- Area labels (A-) ---
+gh label create "A-rendering"       --color "C5DEF5" --description "Component rendering pipeline"        --repo "$REPO" --force
+gh label create "A-screenshot"      --color "C5DEF5" --description "URL screenshot capture"              --repo "$REPO" --force
+gh label create "A-diff"            --color "C5DEF5" --description "Visual regression diffing"           --repo "$REPO" --force
+gh label create "A-audit"           --color "C5DEF5" --description "Accessibility & performance audits"  --repo "$REPO" --force
+gh label create "A-mcp-protocol"    --color "C5DEF5" --description "MCP transport & tool definitions"    --repo "$REPO" --force
+gh label create "A-github-action"   --color "C5DEF5" --description "GitHub Action integration"           --repo "$REPO" --force
+gh label create "A-config"          --color "C5DEF5" --description "Configuration & setup"               --repo "$REPO" --force
+
+# --- Community labels ---
+gh label create "good first issue"  --color "7057FF" --description "Good for newcomers"                  --repo "$REPO" --force
+gh label create "help wanted"       --color "008672" --description "Extra attention is needed"            --repo "$REPO" --force
+gh label create "duplicate"         --color "CFD3D7" --description "This issue already exists"           --repo "$REPO" --force
+
+echo "Labels setup complete for $REPO"