frameshot-mcp 0.3.0 → 0.7.0

package/README.md

@@ -1,24 +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. Render UI components and get screenshots back — in 120ms.
+**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.
 
-<!-- TODO: demo GIF here -->
-<!-- ![demo](docs/demo.gif) -->
+<p align="center">
+  <img src="docs/demo.gif" alt="frameshot demo" width="720" />
+</p>
 
-```
-AI writes code → AI calls frameshot → AI sees the result → AI self-corrects
-```
-
-## Install
+**Claude Code**
 
 ```bash
 claude mcp add frameshot -- npx frameshot-mcp@latest
 ```
 
 <details>
-<summary>Cursor / VS Code / Other</summary>
+<summary>Cursor · VS Code · Windsurf · Cline</summary>
 
 ```json
 {
@@ -33,62 +30,175 @@ claude mcp add frameshot -- npx frameshot-mcp@latest
 
 </details>
 
+---
+
+## 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.
+
+---
+
+## Render
+
+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
 
 | Tool | What it does |
 |------|-------------|
-| `render_component` | Render React/Vue/Svelte/HTML → screenshot. Tailwind built-in. |
-| `render_responsive` | Render at mobile + tablet + desktop in one call. |
-| `render_variants` | Render multiple prop/state variants in one call. |
-| `screenshot_url` | Screenshot any URL (e.g. localhost:3000). |
-| `audit_a11y` | Run axe-core accessibility audit on your component. |
-| `diff_component` | Visual regression: compare before/after code, get pixel diff. |
-| `capture_animation` | Capture CSS animation frames over time (multi-screenshot). |
-
-### Example
-
-```typescript
-render_component({
-  code: `function App() {
-    return <div className="p-8 bg-blue-500 text-white rounded-xl">Hello</div>
-  }`,
-  framework: "react",
-  darkMode: true,
-  engines: ["chromium", "firefox", "webkit"]
-})
+| `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>
+
+---
+
+## CLI
+
+No AI client required. Use frameshot standalone:
+
+```bash
+npx frameshot render src/components/Button.tsx
+npx frameshot render src/Card.tsx --props '{"title":"Hello"}'
+npx frameshot catalog src/components/ --recursive
+npx frameshot diff src/components/Header.tsx
 ```
 
-## Why frameshot?
+Images display inline in iTerm2, Kitty, and Sixel terminals. Saved to `.frameshot/` by default.
+
+---
 
-| | Storybook | frameshot |
-|---|-----------|-----------|
-| Setup | .stories.tsx + addons + server | **Zero** |
-| Speed | Dev server startup | **~120ms** |
-| Cross-browser | Chromatic ($149+/mo) | **Free** |
-| AI-native | Needs pre-written stories | **Any code snippet** |
+## GitHub Action
+
+Free Chromatic alternative. Auto-posts before/after screenshots with diff on every PR:
+
+```yaml
+# .github/workflows/visual-preview.yml
+name: Visual Preview
+on: [pull_request]
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: kamegoro/frameshot@main
+        with:
+          paths: "./src/components/*.tsx"
+```
+
+---
 
 ## Performance
 
+Typical measured times (varies by machine and project size):
+
 | Scenario | Time |
 |----------|------|
-| Warm render | **~120ms** |
-| Cold start | ~4s |
-| 3 engines parallel | ~300ms |
+| 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.
 
-Browser pool stays warm. Tailwind pre-cached. Sub-200ms after first run.
+---
 
-## Recipes
+## vs. alternatives
 
-- [Claude Code skill setup](examples/claude-code-skill.md) — Auto-preview components with `/project:preview`
-- [Cursor rules](examples/cursor-rules.md) — Auto-verify UI on every edit
+| | 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** |
+
+---
 
 ## Development
 
 ```bash
-git clone https://github.com/kamegoro/frameshot.git && cd frameshot
-npm install && npx playwright install chromium && npm run build
+git clone https://github.com/kamegoro/frameshot.git
+cd frameshot && npm install
+npx playwright install chromium
+npm run build && npm test
 ```
 
-## License
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for architecture details.
+
+---
 
-MIT
+MIT © [kamegoro](https://github.com/kamegoro)

package/action.yml

@@ -0,0 +1,144 @@
+name: "frameshot — Visual Preview"
+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
+  width:
+    description: "Viewport width in px. Leave empty for auto-fit (recommended)."
+    required: false
+    default: ""
+  height:
+    description: "Viewport height in px. Leave empty for auto-fit (recommended)."
+    required: false
+    default: ""
+  comment:
+    description: "Post a PR comment with screenshots"
+    required: false
+    default: "true"
+  token:
+    description: "GitHub token for PR comments"
+    required: false
+    default: ${{ github.token }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v6
+      with:
+        node-version: "20"
+
+    - name: Install frameshot
+      shell: bash
+      run: npm install -g frameshot-mcp@latest
+
+    - name: Install Playwright Chromium
+      shell: bash
+      run: npx playwright install chromium
+
+    - name: Render changed components
+      id: render
+      shell: bash
+      env:
+        INPUT_PATHS: ${{ inputs.paths }}
+        INPUT_WIDTH: ${{ inputs.width }}
+        INPUT_HEIGHT: ${{ inputs.height }}
+        INPUT_BASE_REF: ${{ github.event.pull_request.base.sha }}
+      run: |
+        node "${{ github.action_path }}/scripts/render-changed.mjs"
+
+    - name: Comment on PR
+      if: inputs.comment == 'true' && github.event_name == 'pull_request'
+      uses: actions/github-script@v9
+      env:
+        SCREENSHOTS_DIR: ${{ github.workspace }}/.frameshot-screenshots
+      with:
+        github-token: ${{ inputs.token }}
+        script: |
+          const fs = require('fs');
+          const path = require('path');
+          const dir = process.env.SCREENSHOTS_DIR;
+
+          if (!fs.existsSync(dir)) {
+            console.log('No screenshots generated');
+            return;
+          }
+
+          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;
+          }
+
+          let body = '## 📸 frameshot — Visual Preview\n\n';
+
+          const hasBeforeAfter = manifest.some(m => m.hasBefore);
+
+          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;
+
+            const afterData = fs.readFileSync(afterFile, 'base64');
+
+            if (hasBeforeAfter) {
+              const beforeFile = path.join(dir, `${entry.name}_before.png`);
+              const diffFile = path.join(dir, `${entry.name}_diff.png`);
+
+              const beforeImg = fs.existsSync(beforeFile)
+                ? `<img src="data:image/png;base64,${fs.readFileSync(beforeFile, 'base64')}" width="250" />`
+                : '*(new)*';
+
+              const diffImg = fs.existsSync(diffFile) && entry.diffPercentage > 0
+                ? `<img src="data:image/png;base64,${fs.readFileSync(diffFile, 'base64')}" width="250" /><br/>${entry.diffPercentage.toFixed(1)}% changed`
+                : entry.hasBefore ? '✅ No change' : '—';
+
+              body += `| \`${entry.name}\` | ${beforeImg} | <img src="data:image/png;base64,${afterData}" width="250" /> | ${diffImg} |\n`;
+            } else {
+              body += `| \`${entry.name}\` | <img src="data:image/png;base64,${afterData}" width="400" /> |\n`;
+            }
+          }
+
+          body += '\n---\n*Generated by [frameshot](https://github.com/kamegoro/frameshot)*';
+
+          const { data: comments } = await github.rest.issues.listComments({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            issue_number: context.issue.number,
+          });
+
+          const existing = comments.find(c =>
+            c.body?.includes('📸 frameshot — Visual Preview')
+          );
+
+          if (existing) {
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: existing.id,
+              body,
+            });
+          } else {
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body,
+            });
+          }