frameshot-mcp 0.6.0 → 0.8.0

package/README.md

@@ -1,35 +1,21 @@
 # frameshot
 
-[![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)
+[![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) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Give your AI agent eyes.** One MCP call, one screenshot — 120ms. Stop coding blind.
+**Give your AI agent eyes.** Render any component — with real imports, Tailwind, and CSS Modules resolved via Vite — directly in your terminal or AI chat. No stories. No config. Just point at a file.
 
 <p align="center">
-  <img src="docs/demo.svg" alt="frameshot demo — AI writes code, frameshot renders it, AI sees and self-corrects" width="720" />
+  <img src="docs/demo.gif" alt="frameshot demo" width="720" />
 </p>
 
-## The Problem
-
-AI coding agents (Claude Code, Cursor, Copilot, Cline) write UI code **blind**. They generate HTML/CSS/React but never see the rendered result. You end up:
-
-- Switching to the browser to check every change
-- Screenshotting and pasting back into chat
-- Burning tokens on fix loops that never converge
-
-**frameshot closes this loop.** The agent calls one tool, gets a screenshot back in 120ms, and self-corrects.
-
-```
-AI writes code → frameshot renders → AI sees result → AI self-corrects → ships
-```
-
-## Install
+**Claude Code**
 
 ```bash
 claude mcp add frameshot -- npx frameshot-mcp@latest
 ```
 
 <details>
-<summary>Cursor / VS Code / Windsurf / Other MCP clients</summary>
+<summary>Cursor · VS Code · Windsurf · Cline</summary>
 
 ```json
 {
@@ -44,72 +30,155 @@ claude mcp add frameshot -- npx frameshot-mcp@latest
 
 </details>
 
-## What it does
-
-| Tool | Purpose |
-|------|---------|
-| `render_component` | Render React/Vue/Svelte/HTML code → screenshot. Tailwind built-in. |
-| `render_file` | Render a file from disk (auto-detects framework from extension). |
-| `screenshot_url` | Screenshot any URL (localhost:3000, staging, prod). |
-| `render_responsive` | Mobile + tablet + desktop in one call. |
-| `render_variants` | Multiple prop/state variants at once. |
-| `render_theme` | Light + dark mode side-by-side. |
-| `render_interaction` | Simulate click/hover/type, then screenshot result. |
-| `render_grid` | Multiple snippets in a labeled grid image. |
-| `diff_component` | Before/after pixel diff with % changed. |
-| `audit_a11y` | axe-core accessibility audit (WCAG violations). |
-| `perf_audit` | DOM element count, depth, render timing. |
-| `render_matrix` | Viewport × theme matrix in one call. |
-| `capture_animation` | Multi-frame CSS animation capture. |
-| `diff_reference` | Compare render against a reference image (Figma QA). |
-| `render_catalog` | Render all components in a directory (zero-config Storybook). |
-| `snapshot_save` | Save render as named baseline snapshot. |
-| `snapshot_check` | Compare current render against saved snapshot. |
-| `snapshot_list` | List all saved snapshots. |
-
-### Example
-
-```typescript
-// AI renders its own output to verify
-render_component({
-  code: `function App() {
-    return (
-      <div className="p-8 bg-gradient-to-r from-blue-500 to-purple-600 text-white rounded-2xl shadow-xl">
-        <h1 className="text-3xl font-bold">Pricing</h1>
-        <p className="text-5xl mt-4">$29<span className="text-lg">/mo</span></p>
-      </div>
-    )
-  }`,
-  framework: "react"
-})
-// → Screenshot returned in 118ms. AI can see it looks correct.
+---
+
+## Using with Claude
+
+Once installed, just tell Claude what you want:
+
+```
+"Render src/components/PricingCard.tsx and check the layout looks right"
+"Refactor the dashboard to use CSS grid — render it before and after and make sure nothing broke"
+"Show me all components in src/components/ as screenshots"
+```
+
+Claude will automatically call `render_file`, `diff_component`, or `render_catalog` as needed. No manual tool calls required.
+
+---
+
+## Try it now
+
+No AI client required. Works with any React / Vue / Svelte project:
+
+```bash
+npx frameshot render src/components/Button.tsx
 ```
 
-## Why frameshot?
+> First run installs Playwright's Chromium (~150MB). Subsequent renders are fast.
 
-| | Storybook | Chromatic/Percy | Browser MCP | **frameshot** |
-|---|-----------|-----------------|-------------|---------------|
-| Setup | stories + addons + server | SaaS signup + billing | Browser install | **`npx` — done** |
-| Speed | Dev server startup | Cloud round-trip | 2-5s | **~120ms** |
-| Cost | Free (stories = labor) | $149-800+/mo | Free | **Free forever** |
-| AI-native | Needs pre-written stories | No MCP support | Full-page only | **Any code snippet** |
-| Frameworks | React (+ addons) | Whatever Storybook supports | HTML only | **React/Vue/Svelte/HTML** |
-| Cross-browser | Chromatic ($$$) | Per-snapshot pricing | Single browser | **3 engines, free** |
+---
 
-## Performance
+## Render
 
-| Scenario | Time |
-|----------|------|
-| Warm render | **~120ms** |
-| Cold start (first run) | ~4s |
-| 3 browsers in parallel | ~300ms |
-| Responsive (3 viewports) | ~350ms |
+Point to a file. Get a screenshot. All imports resolved.
+
+```
+render_file("src/components/Dashboard.tsx")
+```
+
+<p align="center">
+  <img src="docs/example-output.png" alt="Rendered PricingCard with full Tailwind styling" width="280" />
+</p>
+
+Real Tailwind. Real CSS Modules. Real dependencies — not a CDN polyfill.
+
+---
+
+## Visual diff
+
+Catch regressions before you ship. Before / after / changed pixels — all at once.
+
+<p align="center">
+  <img src="docs/diff-before.png" alt="Before" width="210" />
+  &nbsp;
+  <img src="docs/diff-after.png" alt="After" width="210" />
+  &nbsp;
+  <img src="docs/diff-result.png" alt="Diff" width="210" />
+</p>
+
+```
+diff_component("src/components/MetricCard.tsx")
+→ 0.7% changed
+```
+
+---
+
+## Tools
+
+### `render_file` — Render a component with full dependency resolution
+
+<p align="center">
+  <img src="docs/example-output.png" alt="Rendered PricingCard" width="280" />
+</p>
 
-Browser pool stays warm between calls. Tailwind CSS is pre-cached. Sub-200ms after first run.
+Real Tailwind. Real CSS Modules. Real imports — resolved by Vite.
+
+---
+
+### `diff_component` — Visual diff against git HEAD
+
+<p align="center">
+  <img src="docs/diff-before.png" alt="Before" width="200" />
+  &nbsp;
+  <img src="docs/diff-after.png" alt="After" width="200" />
+  &nbsp;
+  <img src="docs/diff-result.png" alt="Diff" width="200" />
+</p>
+
+Pixel-accurate before/after comparison. Returns diff percentage.
+
+---
+
+### `render_catalog` — Screenshot every component in a directory
+
+```bash
+npx frameshot catalog src/components/
+```
+
+Renders all components at once and saves PNGs to the output directory.
+
+---
+
+### `audit_a11y` — Accessibility audit with axe-core
+
+Returns WCAG violations with severity and selector. No browser extension needed.
+
+---
+
+| Tool | What it does |
+|------|-------------|
+| `render_file` | **Render a file via Vite** — full dep resolution, props support |
+| `render_component` | Render a self-contained snippet (React / Vue / Svelte / HTML) |
+| `screenshot_url` | Screenshot any URL — localhost, staging, prod |
+| `diff_component` | Pixel diff before/after with % changed |
+| `render_responsive` | Mobile + tablet + desktop in one call |
+| `render_theme` | Light + dark mode side by side |
+| `audit_a11y` | axe-core accessibility audit (WCAG) |
+| `render_catalog` | Render every component in a directory |
+
+<details>
+<summary>All 18 tools</summary>
+
+| Tool | What it does |
+|------|-------------|
+| `render_file` | Render a project file with full Vite dependency resolution |
+| `render_component` | Render a self-contained snippet → screenshot |
+| `screenshot_url` | Screenshot any URL with retry and network idle wait |
+| `render_responsive` | Mobile + tablet + desktop in one call |
+| `render_variants` | Multiple prop/state variants at once |
+| `render_theme` | Light + dark mode side by side |
+| `render_interaction` | Simulate click/hover/type, then screenshot |
+| `render_grid` | Multiple snippets in a labeled grid |
+| `render_matrix` | Viewport × theme matrix in one call |
+| `capture_animation` | Multi-frame CSS animation capture |
+| `diff_component` | Before/after pixel diff with % changed |
+| `diff_reference` | Compare render against a reference image (Figma QA) |
+| `audit_a11y` | axe-core accessibility audit |
+| `perf_audit` | DOM count, depth, render timing |
+| `render_catalog` | Render all components in a directory |
+| `snapshot_save` | Save a render as named baseline |
+| `snapshot_check` | Compare current render against saved baseline |
+| `snapshot_list` | List all saved snapshots |
+
+</details>
+
+---
 
 ## GitHub Action
 
-Add visual previews to every PR — free Chromatic alternative:
+Free Chromatic alternative. Auto-detects changed components and posts before/after screenshots on every PR.
+
+Add this file to your repo:
 
 ```yaml
 # .github/workflows/visual-preview.yml
@@ -119,29 +188,85 @@ jobs:
   preview:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: kamegoro/frameshot@main
+      - uses: actions/checkout@v7
         with:
-          paths: "./src/components/*.tsx"
-          framework: react
+          fetch-depth: 0
+      - uses: kamegoro/frameshot@v0.8.0
+```
+
+That's it. No config needed — changed `.tsx`, `.jsx`, `.vue`, `.svelte` files are detected automatically.
+
+Optionally scope to specific paths or customize which files are included:
+
+```yaml
+- uses: kamegoro/frameshot@v0.8.0
+  with:
+    # Render only these files (default: auto-detect changed components)
+    paths: "./src/components/*.tsx"
+
+    # File extensions to treat as components
+    # Default: .jsx,.tsx,.vue,.svelte,.astro,.mdx
+    extensions: ".jsx,.tsx,.vue"
+
+    # Patterns to exclude (matched against filename)
+    # Default: *.test.*,*.spec.*,*.stories.*,*.story.*
+    exclude: "*.test.*,*.spec.*,*.stories.*"
+```
+
+---
+
+## CLI — advanced usage
+
+```bash
+npx frameshot render src/Card.tsx --props '{"title":"Hello"}'
+npx frameshot catalog src/components/ --recursive
+npx frameshot diff src/components/Header.tsx
 ```
 
-Screenshots are posted as a PR comment automatically.
+Images display inline in iTerm2, Kitty, and Sixel terminals. Saved to `.frameshot/` by default.
+
+---
+
+## Performance
+
+Typical measured times (varies by machine and project size):
+
+| Scenario | Time |
+|----------|------|
+| Warm render (Vite server cached) | **~200–500ms** |
+| CDN fallback (no Vite) | **~120ms** |
+| Cold start (first render) | ~1–3s |
+| Subsequent renders (same session) | ~200ms |
+
+Vite server is cached per project root. Browser pool stays warm between MCP calls.
+
+---
+
+## vs. alternatives
 
-## Recipes
+| | Storybook | Chromatic | Browser MCP | **frameshot** |
+|---|-----------|-----------|-------------|---------------|
+| Setup | Stories + config | SaaS signup | Browser install | **`npx` — done** |
+| Speed | Dev server startup | Cloud round-trip | 2–5s | **~200ms warm** |
+| Cost | Free (labor cost) | $149–800+/mo | Free | **Free forever** |
+| Stories needed | Yes | Yes | No | **No** |
+| Real imports | Via Storybook | Via Storybook | No | **Via Vite** |
+| Works offline | Yes | No | Yes | **Yes** |
+| AI-native (MCP) | No | No | Full-page only | **Component-level** |
 
-- [Claude Code skill](examples/claude-code-skill.md) — Auto-preview on `/project:preview`
-- [Cursor rules](examples/cursor-rules.md) — 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 && npm test
+git clone https://github.com/kamegoro/frameshot.git
+cd frameshot && npm install
+npx playwright install chromium
+npm run build && npm test
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for architecture details.
 
-## License
+---
 
-MIT
+MIT © [kamegoro](https://github.com/kamegoro)

package/action.yml

@@ -1,33 +1,30 @@
 name: "frameshot — Visual Preview"
-description: "Render components and attach before/after screenshots to PRs. Free visual regression for every pull request."
+description: "Render changed components with full Vite dependency resolution and attach before/after screenshots to PRs."
 branding:
   icon: "camera"
   color: "blue"
 
 inputs:
   paths:
-    description: "Glob patterns for component files to render (newline or comma separated)"
-    required: true
-  framework:
-    description: "Framework: react, vue, svelte, or html"
+    description: "Glob patterns for component files to render. Leave empty to auto-detect changed component files."
     required: false
-    default: "react"
-  width:
-    description: "Viewport width (px)"
+    default: ""
+  extensions:
+    description: "Comma-separated file extensions to treat as components. Default covers React, Vue, Svelte, Astro, MDX."
     required: false
-    default: "1280"
-  height:
-    description: "Viewport height (px)"
+    default: ".jsx,.tsx,.vue,.svelte,.astro,.mdx"
+  exclude:
+    description: "Patterns to exclude (comma-separated). Matches against full file path."
     required: false
-    default: "800"
-  dark-mode:
-    description: "Render with dark mode"
+    default: "*.test.*,*.spec.*,*.stories.*,*.story.*"
+  width:
+    description: "Viewport width in px. Leave empty for auto-fit (recommended)."
     required: false
-    default: "false"
-  tailwind-version:
-    description: "Tailwind CSS version (3 or 4)"
+    default: ""
+  height:
+    description: "Viewport height in px. Leave empty for auto-fit (recommended)."
     required: false
-    default: "3"
+    default: ""
   comment:
     description: "Post a PR comment with screenshots"
     required: false
@@ -41,30 +38,48 @@ runs:
   using: "composite"
   steps:
     - name: Setup Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v6
       with:
         node-version: "20"
 
     - name: Install frameshot
       shell: bash
-      run: npm install -g frameshot-mcp@latest
+      run: |
+        cd "${{ github.action_path }}"
+        npm install --prefer-offline frameshot-mcp@latest
 
     - name: Install Playwright Chromium
       shell: bash
-      run: npx playwright install chromium
+      run: |
+        cd "${{ github.action_path }}"
+        npx playwright install chromium
+
+    - name: Install project dependencies (for Vite pipeline)
+      shell: bash
+      run: |
+        # Install deps in any subdirectory that has vite as a dependency
+        for pkg in $(find "$GITHUB_WORKSPACE" -name "package.json" -not -path "*/node_modules/*" -maxdepth 3); do
+          dir=$(dirname "$pkg")
+          if grep -q '"vite"' "$pkg" 2>/dev/null; then
+            echo "Installing deps in $dir"
+            cd "$dir" && npm install --legacy-peer-deps 2>/dev/null || true
+            cd "$GITHUB_WORKSPACE"
+          fi
+        done
 
     - name: Render changed components
       id: render
       shell: bash
       env:
         INPUT_PATHS: ${{ inputs.paths }}
-        INPUT_FRAMEWORK: ${{ inputs.framework }}
+        INPUT_EXTENSIONS: ${{ inputs.extensions }}
+        INPUT_EXCLUDE: ${{ inputs.exclude }}
         INPUT_WIDTH: ${{ inputs.width }}
         INPUT_HEIGHT: ${{ inputs.height }}
-        INPUT_DARK_MODE: ${{ inputs.dark-mode }}
-        INPUT_TAILWIND_VERSION: ${{ inputs.tailwind-version }}
+        INPUT_BASE_REF: ${{ github.event.pull_request.base.sha }}
       run: |
-        node "${{ github.action_path }}/scripts/render-changed.mjs"
+        cd "${{ github.action_path }}"
+        node scripts/render-changed.mjs
 
     - name: Comment on PR
       if: inputs.comment == 'true' && github.event_name == 'pull_request'
@@ -83,26 +98,114 @@ runs:
             return;
           }
 
-          const files = fs.readdirSync(dir).filter(f => f.endsWith('.png'));
-          if (files.length === 0) {
-            console.log('No screenshot files found');
+          const manifestPath = path.join(dir, 'manifest.json');
+          if (!fs.existsSync(manifestPath)) {
+            console.log('No manifest found');
+            return;
+          }
+
+          const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+          if (manifest.length === 0) {
+            console.log('No components rendered');
             return;
           }
 
-          // Upload screenshots as artifacts and build comment
+          // Store image in repo on a dedicated branch and return raw URL.
+          // Uses a special orphan branch "frameshot-previews" as image storage.
+          async function uploadImageToGitHub(filePath) {
+            const bytes = fs.readFileSync(filePath);
+            const base64 = bytes.toString('base64');
+            const filename = `pr-${context.issue.number}-${path.basename(filePath)}-${Date.now()}.png`;
+            const BRANCH = 'frameshot-previews';
+
+            // Ensure branch exists
+            try {
+              await github.rest.repos.getBranch({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                branch: BRANCH,
+              });
+            } catch {
+              // Branch doesn't exist — create it from main
+              try {
+                const { data: ref } = await github.rest.git.getRef({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  ref: 'heads/main',
+                });
+                await github.rest.git.createRef({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  ref: `refs/heads/${BRANCH}`,
+                  sha: ref.object.sha,
+                });
+              } catch (e) {
+                console.log('Failed to create branch:', e.message);
+                return null;
+              }
+            }
+
+            // Commit the image file
+            try {
+              await github.rest.repos.createOrUpdateFileContents({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                path: filename,
+                message: `Add PR #${context.issue.number} preview image`,
+                content: base64,
+                branch: BRANCH,
+              });
+              return `https://raw.githubusercontent.com/${context.repo.owner}/${context.repo.repo}/${BRANCH}/${filename}`;
+            } catch (e) {
+              console.log('Failed to commit image:', e.message);
+              return null;
+            }
+          }
+
+          const hasBeforeAfter = manifest.some(m => m.hasBefore);
           let body = '## 📸 frameshot — Visual Preview\n\n';
-          body += '| Component | Screenshot |\n|---|---|\n';
 
-          for (const file of files) {
-            const name = file.replace('.png', '').replace(/_/g, '/');
-            const imgPath = path.join(dir, file);
-            const imgData = fs.readFileSync(imgPath, 'base64');
-            body += `| \`${name}\` | <img src="data:image/png;base64,${imgData}" width="400" /> |\n`;
+          if (hasBeforeAfter) {
+            body += '| Component | Before | After | Diff |\n|---|---|---|---|\n';
+          } else {
+            body += '| Component | Screenshot |\n|---|---|\n';
+          }
+
+          for (const entry of manifest) {
+            const afterFile = path.join(dir, `${entry.name}_after.png`);
+            if (!fs.existsSync(afterFile)) continue;
+
+            if (hasBeforeAfter) {
+              const beforeFile = path.join(dir, `${entry.name}_before.png`);
+              const diffFile = path.join(dir, `${entry.name}_diff.png`);
+
+              // Upload sequentially to avoid commit conflicts
+              const afterUrl = await uploadImageToGitHub(afterFile);
+              const beforeUrl = fs.existsSync(beforeFile) ? await uploadImageToGitHub(beforeFile) : null;
+              const diffUrl = fs.existsSync(diffFile) ? await uploadImageToGitHub(diffFile) : null;
+
+              const beforeCell = beforeUrl
+                ? `<img src="${beforeUrl}" width="240" />`
+                : entry.hasBefore ? '*(before unavailable)*' : '*(new)*';
+              const afterCell = afterUrl
+                ? `<img src="${afterUrl}" width="240" />`
+                : '*(after unavailable)*';
+              const diffCell = diffUrl && entry.diffPercentage > 0
+                ? `<img src="${diffUrl}" width="240" /><br/>${entry.diffPercentage.toFixed(1)}% changed`
+                : entry.hasBefore ? '✅ No change' : '—';
+
+              body += `| \`${entry.name}\` | ${beforeCell} | ${afterCell} | ${diffCell} |\n`;
+            } else {
+              const afterUrl = await uploadImageToGitHub(afterFile);
+              const afterCell = afterUrl
+                ? `<img src="${afterUrl}" width="360" />`
+                : '*(unavailable)*';
+              body += `| \`${entry.name}\` | ${afterCell} |\n`;
+            }
           }
 
           body += '\n---\n*Generated by [frameshot](https://github.com/kamegoro/frameshot)*';
 
-          // Find existing comment
           const { data: comments } = await github.rest.issues.listComments({
             owner: context.repo.owner,
             repo: context.repo.repo,