frameshot-mcp 0.3.0 → 0.6.0

package/README.md

@@ -2,13 +2,24 @@
 
 [![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)
 
-> Give your AI agent eyes. Render UI components and get screenshots back — in 120ms.
+> **Give your AI agent eyes.** One MCP call, one screenshot — 120ms. Stop coding blind.
 
-<!-- TODO: demo GIF here -->
-<!-- ![demo](docs/demo.gif) -->
+<p align="center">
+  <img src="docs/demo.svg" alt="frameshot demo — AI writes code, frameshot renders it, AI sees and self-corrects" 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 → AI calls frameshot → AI sees the result → AI self-corrects
+AI writes code → frameshot renders → AI sees result → AI self-corrects → ships
 ```
 
 ## Install
@@ -18,7 +29,7 @@ claude mcp add frameshot -- npx frameshot-mcp@latest
 ```
 
 <details>
-<summary>Cursor / VS Code / Other</summary>
+<summary>Cursor / VS Code / Windsurf / Other MCP clients</summary>
 
 ```json
 {
@@ -33,62 +44,104 @@ claude mcp add frameshot -- npx frameshot-mcp@latest
 
 </details>
 
-## 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). |
+## 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-blue-500 text-white rounded-xl">Hello</div>
+    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",
-  darkMode: true,
-  engines: ["chromium", "firefox", "webkit"]
+  framework: "react"
 })
+// → Screenshot returned in 118ms. AI can see it looks correct.
 ```
 
 ## Why frameshot?
 
-| | 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** |
+| | 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
 
 | Scenario | Time |
 |----------|------|
 | Warm render | **~120ms** |
-| Cold start | ~4s |
-| 3 engines parallel | ~300ms |
+| Cold start (first run) | ~4s |
+| 3 browsers in parallel | ~300ms |
+| Responsive (3 viewports) | ~350ms |
+
+Browser pool stays warm between calls. Tailwind CSS is pre-cached. Sub-200ms after first run.
+
+## GitHub Action
+
+Add visual previews to every PR — free Chromatic alternative:
+
+```yaml
+# .github/workflows/visual-preview.yml
+name: Visual Preview
+on: [pull_request]
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: kamegoro/frameshot@main
+        with:
+          paths: "./src/components/*.tsx"
+          framework: react
+```
 
-Browser pool stays warm. Tailwind pre-cached. Sub-200ms after first run.
+Screenshots are posted as a PR comment automatically.
 
 ## Recipes
 
-- [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
+- [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 install && npx playwright install chromium && npm run build && npm test
 ```
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
 ## License
 
 MIT

package/action.yml

@@ -0,0 +1,130 @@
+name: "frameshot — Visual Preview"
+description: "Render components and attach before/after screenshots to PRs. Free visual regression for every pull request."
+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"
+    required: false
+    default: "react"
+  width:
+    description: "Viewport width (px)"
+    required: false
+    default: "1280"
+  height:
+    description: "Viewport height (px)"
+    required: false
+    default: "800"
+  dark-mode:
+    description: "Render with dark mode"
+    required: false
+    default: "false"
+  tailwind-version:
+    description: "Tailwind CSS version (3 or 4)"
+    required: false
+    default: "3"
+  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@v4
+      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_FRAMEWORK: ${{ inputs.framework }}
+        INPUT_WIDTH: ${{ inputs.width }}
+        INPUT_HEIGHT: ${{ inputs.height }}
+        INPUT_DARK_MODE: ${{ inputs.dark-mode }}
+        INPUT_TAILWIND_VERSION: ${{ inputs.tailwind-version }}
+      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 files = fs.readdirSync(dir).filter(f => f.endsWith('.png'));
+          if (files.length === 0) {
+            console.log('No screenshot files found');
+            return;
+          }
+
+          // Upload screenshots as artifacts and build comment
+          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`;
+          }
+
+          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,
+            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,
+            });
+          }