frameshot-mcp 0.2.0 → 0.6.0

package/README.md

@@ -2,58 +2,34 @@
 
 [![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)
 
-> Instant cross-browser component preview for AI agents. One call, one screenshot — no dev server, no Storybook, no ceremony.
+> **Give your AI agent eyes.** One MCP call, one screenshot — 120ms. Stop coding blind.
 
-**Works with:** Claude Code · Cursor · Codex · Windsurf · any MCP-compatible tool
+<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
 
-You're building UI with an AI agent. The agent writes a component but can't see it. You have to:
-1. Start the dev server
-2. Log in
-3. Navigate to the right page
-4. Scroll to the component
-5. Tell the agent what's wrong
+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:
 
-**frameshot** skips all of that. The agent renders the component itself, sees the result, and fixes it.
+- Switching to the browser to check every change
+- Screenshotting and pasting back into chat
+- Burning tokens on fix loops that never converge
 
-## Quick Start
+**frameshot closes this loop.** The agent calls one tool, gets a screenshot back in 120ms, and self-corrects.
 
-### Claude Code
-
-```bash
-claude mcp add frameshot -- npx frameshot-mcp@latest
 ```
-
-That's it. Now your AI agent can see UI.
-
-### Cursor (`.cursor/mcp.json`)
-
-```json
-{
-  "mcpServers": {
-    "frameshot": {
-      "command": "npx",
-      "args": ["frameshot-mcp@latest"]
-    }
-  }
-}
+AI writes code → frameshot renders → AI sees result → AI self-corrects → ships
 ```
 
-### VS Code Copilot (`.vscode/mcp.json`)
+## Install
 
-```json
-{
-  "servers": {
-    "frameshot": {
-      "command": "npx",
-      "args": ["frameshot-mcp@latest"]
-    }
-  }
-}
+```bash
+claude mcp add frameshot -- npx frameshot-mcp@latest
 ```
 
-### Manual setup
+<details>
+<summary>Cursor / VS Code / Windsurf / Other MCP clients</summary>
 
 ```json
 {
@@ -66,117 +42,106 @@ That's it. Now your AI agent can see UI.
 }
 ```
 
-> **Note:** On first run, Playwright will download Chromium (~150MB). For additional engines: `npx playwright install firefox webkit`
-
-## Tools
-
-### `render_component`
-
-Render isolated component code → get screenshot back instantly.
+</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 rounded-xl">
-          <h1 className="text-4xl font-bold text-white">Hello World</h1>
-        </div>
-      )
-    }
-  `,
-  framework: "react",
-  engines: ["chromium", "firefox", "webkit"]
+  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"
 })
-// Returns 3 screenshots — one per browser engine
+// → Screenshot returned in 118ms. AI can see it looks correct.
 ```
 
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `code` | required | Component source code |
-| `framework` | `"react"` | `"react"` · `"vue"` · `"html"` |
-| `engines` | `["chromium"]` | Browser engines to render in |
-| `width` | `1280` | Viewport width |
-| `height` | `800` | Viewport height |
-| `fullPage` | `true` | Capture full scroll height |
-
-### `screenshot_url`
-
-Screenshot a running app (e.g. localhost) across browsers.
-
-```typescript
-screenshot_url({
-  url: "http://localhost:3000/components/button",
-  engines: ["chromium", "firefox", "webkit"]
-})
-```
+## Why frameshot?
 
-## Why Not Storybook?
-
-| | Storybook | frameshot |
-|---|-----------|-----------|
-| Setup | Write .stories.tsx, configure addons, run server | **Zero** — pass code, get image |
-| Speed | Heavy dev server startup | **~120ms** warm render |
-| Cross-browser | Chromatic ($149+/mo) | **Free** — Playwright built-in |
-| AI-native | Requires pre-written stories | **Works with any code snippet** |
-| Auth required? | Need full app context | **No** — isolated component render |
-
-frameshot is not a Storybook replacement. Storybook is for documentation and design systems. frameshot is for **seeing what you just wrote, right now**.
+| | 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 (browser reused) | **~120ms** |
-| Cold start (first render) | ~4s |
-| Cross-browser (3 engines parallel) | ~300ms warm |
-
-The browser pool stays warm with Tailwind pre-cached. After cold start, renders are **sub-200ms**.
-
-## Framework Support
-
-### React (JSX + Tailwind)
-```jsx
-function App() {
-  const [count, setCount] = React.useState(0)
-  return <button onClick={() => setCount(c => c+1)} className="btn">{count}</button>
-}
+| Warm render | **~120ms** |
+| 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
 ```
 
-### Vue 3 (Composition API + Tailwind)
-```javascript
-const App = {
-  setup() {
-    const count = ref(0)
-    return { count }
-  },
-  template: `<button @click="count++">{{ count }}</button>`
-}
-```
+Screenshots are posted as a PR comment automatically.
 
-### HTML (+ Tailwind)
-```html
-<div class="flex gap-4 p-8">
-  <button class="px-4 py-2 bg-blue-500 text-white rounded">Click me</button>
-</div>
-```
+## Recipes
 
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `FRAMESHOT_BROWSER_PATH` | Custom Chromium executable path |
+- [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
+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.
+
 ## 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,
+            });
+          }