frameshot-mcp 0.2.0 → 0.6.0

package/dist/renderer.d.ts

@@ -0,0 +1,241 @@
+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;
+}
+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>;
+
+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;
+}
+
+declare class ImageComparator {
+    diff(imageA: string, imageB: string, threshold?: number): {
+        diff: string;
+        diffPixels: number;
+        totalPixels: number;
+        diffPercentage: number;
+    };
+    composite(images: Buffer[], columns: number, labelHeight?: number): {
+        image: string;
+        width: number;
+        height: number;
+    };
+}
+
+declare class SnapshotStore {
+    private store;
+    save(key: string, image: string): void;
+    get(key: string): Snapshot | undefined;
+    list(): {
+        key: string;
+        timestamp: number;
+    }[];
+}
+
+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;
+    constructor(pool: BrowserPool, htmlBuilder: HtmlBuilder, imageComparator: ImageComparator);
+    render(code: string, framework: Framework, options?: Partial<RenderOptions>): Promise<ScreenshotResult[]>;
+    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 resolveOptions;
+}
+
+declare class CatalogUseCase {
+    private readonly renderUseCase;
+    constructor(renderUseCase: RenderUseCase);
+    renderCatalog(directory: string, options?: Partial<RenderOptions> & {
+        recursive?: boolean;
+    }): Promise<CatalogEntry[]>;
+    private scanDirectory;
+    private detectFramework;
+}
+
+declare class DiffUseCase {
+    private readonly renderUseCase;
+    private readonly imageComparator;
+    constructor(renderUseCase: RenderUseCase, imageComparator: ImageComparator);
+    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 Framework, type GridCell, HtmlBuilder, ImageComparator, type Interaction, type PerfMetrics, type ReferenceDiffResult, type RenderOptions, RenderUseCase, type ScreenshotResult, ScreenshotUseCase, type Snapshot, SnapshotStore, SnapshotUseCase, type Theme, type Viewport };

package/dist/renderer.js

@@ -0,0 +1,28 @@
+import {
+  AuditUseCase,
+  BrowserPool,
+  CatalogUseCase,
+  DEVICE_PRESETS,
+  DiffUseCase,
+  EXT_TO_FRAMEWORK,
+  HtmlBuilder,
+  ImageComparator,
+  RenderUseCase,
+  ScreenshotUseCase,
+  SnapshotStore,
+  SnapshotUseCase
+} from "./chunk-47YJG5HR.js";
+export {
+  AuditUseCase,
+  BrowserPool,
+  CatalogUseCase,
+  DEVICE_PRESETS,
+  DiffUseCase,
+  EXT_TO_FRAMEWORK,
+  HtmlBuilder,
+  ImageComparator,
+  RenderUseCase,
+  ScreenshotUseCase,
+  SnapshotStore,
+  SnapshotUseCase
+};

package/package.json

@@ -1,22 +1,38 @@
 {
   "name": "frameshot-mcp",
-  "version": "0.2.0",
+  "version": "0.6.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",
+  "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"
   },
   "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 --format esm --dts",
+    "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": [
@@ -49,13 +65,20 @@
   },
   "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"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.9"
   },
+  "mcpName": "io.github.kamegoro/frameshot-mcp",
   "engines": {
     "node": ">=20.0.0"
   }

package/scripts/render-changed.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+
+const {
+  INPUT_PATHS = "",
+  INPUT_FRAMEWORK = "react",
+  INPUT_WIDTH = "1280",
+  INPUT_HEIGHT = "800",
+  INPUT_DARK_MODE = "false",
+  INPUT_TAILWIND_VERSION = "3",
+  GITHUB_WORKSPACE = process.cwd(),
+} = 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 EXT_TO_FRAMEWORK = {
+  ".jsx": "react",
+  ".tsx": "react",
+  ".vue": "vue",
+  ".svelte": "svelte",
+  ".html": "html",
+  ".htm": "html",
+};
+
+async function main() {
+  const { render, warmup, shutdown } = await import("frameshot-mcp/renderer");
+
+  await warmup(["chromium"]);
+
+  const allFiles = [];
+  for (const pattern of patterns) {
+    try {
+      const result = execSync(
+        `find ${GITHUB_WORKSPACE} -path '${pattern}' -type f 2>/dev/null`,
+        { encoding: "utf-8" },
+      );
+      allFiles.push(...result.split("\n").filter(Boolean));
+    } catch {
+      // Pattern didn't match
+    }
+  }
+
+  if (allFiles.length === 0) {
+    console.log("No component files found matching the specified patterns.");
+    await shutdown();
+    process.exit(0);
+  }
+
+  console.log(`Found ${allFiles.length} component file(s) to render...`);
+
+  for (const filePath of allFiles) {
+    const ext = extname(filePath).toLowerCase();
+    const framework = EXT_TO_FRAMEWORK[ext] || INPUT_FRAMEWORK;
+    const name = basename(filePath, extname(filePath));
+    const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+
+    try {
+      console.log(`  Rendering: ${filePath}`);
+      const code = readFileSync(filePath, "utf-8");
+      const [result] = await render(code, framework, {
+        width: parseInt(INPUT_WIDTH),
+        height: parseInt(INPUT_HEIGHT),
+        darkMode: INPUT_DARK_MODE === "true",
+        tailwindVersion: INPUT_TAILWIND_VERSION,
+        engines: ["chromium"],
+      });
+      const outPath = join(outputDir, `${safeName}.png`);
+      writeFileSync(outPath, Buffer.from(result.image, "base64"));
+      console.log(`  ✓ ${safeName}.png (${result.width}x${result.height})`);
+    } catch (error) {
+      console.error(`  ✗ Failed: ${filePath} — ${error.message}`);
+    }
+  }
+
+  await shutdown();
+  console.log(`\nDone. Screenshots 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"