frameshot-mcp 0.8.0 → 0.9.7

package/README.md

@@ -2,7 +2,7 @@
 
 [![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 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.
+**Give your AI agent eyes.** Render components with real Vite imports, Tailwind, and CSS Modules — right in your terminal or AI chat. No story files required.
 
 <p align="center">
   <img src="docs/demo.gif" alt="frameshot demo" width="720" />
@@ -32,51 +32,29 @@ claude mcp add frameshot -- npx frameshot-mcp@latest
 
 ---
 
-## Using with Claude
+## Watch mode — live AI feedback loop
 
-Once installed, just tell Claude what you want:
+The AI edits a file, saves it, and immediately sees how it looks — without you calling anything.
 
 ```
-"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"
+watch_start({ patterns: ["src/components/Button.tsx"] })
+→ renders on every save → call watch_get_latest("watch-1") to see it
 ```
 
-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
-```
-
-> First run installs Playwright's Chromium (~150MB). Subsequent renders are fast.
+The agent fixes → saves → sees → fixes again. You just watch.
 
 ---
 
-## Render
+## GitHub Action — free Chromatic alternative
 
-Point to a file. Get a screenshot. All imports resolved.
+Two lines. Auto-detects changed components. Posts before/after/diff screenshots directly in the PR comment.
 
+```yaml
+- uses: actions/checkout@v7
+  with:
+    fetch-depth: 0
+- uses: kamegoro/frameshot@v0.8.0
 ```
-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" />
@@ -86,68 +64,86 @@ Catch regressions before you ship. Before / after / changed pixels — all at on
   <img src="docs/diff-result.png" alt="Diff" width="210" />
 </p>
 
+Changed `.tsx`, `.jsx`, `.vue`, `.svelte`, `.astro`, `.mdx` files detected automatically. No Storybook. No signup. Free forever.
+
+<details>
+<summary>Options</summary>
+
+```yaml
+- uses: kamegoro/frameshot@v0.8.0
+  with:
+    paths: "./src/components/*.tsx"       # default: auto-detect
+    extensions: ".jsx,.tsx,.vue"          # default: .jsx,.tsx,.vue,.svelte,.astro,.mdx
+    exclude: "*.test.*,*.spec.*"          # default: *.test.*,*.spec.*,*.stories.*
 ```
-diff_component("src/components/MetricCard.tsx")
-→ 0.7% changed
-```
+
+</details>
 
 ---
 
-## Tools
+## Render any component
+
+Point to a file. Get a screenshot. Full Vite pipeline.
 
-### `render_file` — Render a component with full dependency resolution
+```
+render_file("src/components/Dashboard.tsx")
+```
 
 <p align="center">
-  <img src="docs/example-output.png" alt="Rendered PricingCard" width="280" />
+  <img src="docs/example-output.png" alt="Rendered PricingCard with full Tailwind styling" width="280" />
 </p>
 
-Real Tailwind. Real CSS Modules. Real imports — resolved by Vite.
+Resolves your project's real imports, Tailwind config, CSS Modules, and path aliases — not a CDN polyfill.
 
 ---
 
-### `diff_component` — Visual diff against git HEAD
+## Using with Claude
 
-<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>
+After installing, just describe what you want:
+
+```
+"Render src/components/PricingCard.tsx — does it look right?"
+"Refactor the layout to CSS grid and show me before/after"
+"Watch Button.tsx while I edit — tell me when something looks off"
+```
 
-Pixel-accurate before/after comparison. Returns diff percentage.
+Claude calls `render_file`, `diff_component`, `watch_start`, or any other tool automatically.
 
 ---
 
-### `render_catalog` — Screenshot every component in a directory
+## Try it without an AI client
+
+Works standalone on any React / Vue / Svelte project:
 
 ```bash
-npx frameshot catalog src/components/
+npx frameshot render src/components/Button.tsx
+npx frameshot diff src/components/Header.tsx
+npx frameshot catalog src/components/ --recursive
 ```
 
-Renders all components at once and saves PNGs to the output directory.
-
----
-
-### `audit_a11y` — Accessibility audit with axe-core
+Images display inline in iTerm2, Kitty, and Sixel terminals. Saved to `.frameshot/` by default.
 
-Returns WCAG violations with severity and selector. No browser extension needed.
+> First run installs Playwright's Chromium (~150MB). Subsequent renders are fast.
 
 ---
 
+## Tools
+
 | 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) |
+| `render_file` | Render a file via Vite — real imports, Tailwind, CSS Modules |
+| `diff_component` | Pixel diff before/after — % changed, highlighted pixels |
+| `watch_start` | Watch files — auto-render on every save |
+| `watch_get_latest` | Get the latest render from a watch session |
+| `render_catalog` | Render every component in a directory at once |
 | `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 |
+| `audit_a11y` | axe-core accessibility audit (WCAG violations) |
+| `render_component` | Render a self-contained code snippet |
 
 <details>
-<summary>All 18 tools</summary>
+<summary>All 22 tools</summary>
 
 | Tool | What it does |
 |------|-------------|
@@ -169,68 +165,17 @@ Returns WCAG violations with severity and selector. No browser extension needed.
 | `snapshot_save` | Save a render as named baseline |
 | `snapshot_check` | Compare current render against saved baseline |
 | `snapshot_list` | List all saved snapshots |
+| `watch_start` | Start watching files — renders on every save |
+| `watch_stop` | Stop a watch session |
+| `watch_get_latest` | Get the latest rendered screenshot from a session |
+| `watch_list` | List active watch sessions |
 
 </details>
 
 ---
 
-## GitHub Action
-
-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
-name: Visual Preview
-on: [pull_request]
-jobs:
-  preview:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-        with:
-          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
-```
-
-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** |
@@ -249,9 +194,10 @@ Vite server is cached per project root. Browser pool stays warm between MCP call
 | 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** |
+| Story files needed | Yes | Yes | No | **No** |
+| Real imports resolved | Via Storybook | Via Storybook | No | **Via Vite** |
 | Works offline | Yes | No | Yes | **Yes** |
+| Watch mode | No | No | No | **Yes** |
 | AI-native (MCP) | No | No | Full-page only | **Component-level** |
 
 ---

package/action.yml

@@ -46,7 +46,15 @@ runs:
       shell: bash
       run: |
         cd "${{ github.action_path }}"
-        npm install --prefer-offline frameshot-mcp@latest
+        # Install frameshot from the action's own checked-out source (this repo)
+        # so users get exactly the version pinned by their `uses:` tag,
+        # regardless of npm publish state.
+        if [ -f package.json ] && [ -d src ]; then
+          npm install --prefer-offline --no-audit --no-fund
+          npm run build
+        else
+          npm install --prefer-offline --no-audit --no-fund frameshot-mcp@latest
+        fi
 
     - name: Install Playwright Chromium
       shell: bash
@@ -57,10 +65,11 @@ runs:
     - name: Install project dependencies (for Vite pipeline)
       shell: bash
       run: |
-        # Install deps in any subdirectory that has vite as a dependency
+        # Install deps in any directory that has a package.json with a build framework
+        # Supports Vite, Next.js, Nuxt, SvelteKit, Astro, etc.
         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
+          if grep -qE '"vite"|"next"|"nuxt"|"@sveltejs/kit"|"astro"' "$pkg" 2>/dev/null; then
             echo "Installing deps in $dir"
             cd "$dir" && npm install --legacy-peer-deps 2>/dev/null || true
             cd "$GITHUB_WORKSPACE"
@@ -194,13 +203,13 @@ runs:
                 ? `<img src="${diffUrl}" width="240" /><br/>${entry.diffPercentage.toFixed(1)}% changed`
                 : entry.hasBefore ? '✅ No change' : '—';
 
-              body += `| \`${entry.name}\` | ${beforeCell} | ${afterCell} | ${diffCell} |\n`;
+              body += `| \`${entry.label ?? 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 += `| \`${entry.label ?? entry.name}\` | ${afterCell} |\n`;
             }
           }