frameshot-mcp 0.7.0 → 0.8.0

package/README.md

@@ -46,6 +46,18 @@ Claude will automatically call `render_file`, `diff_component`, or `render_catal
 
 ---
 
+## 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.
+
+---
+
 ## Render
 
 Point to a file. Get a screenshot. All imports resolved.
@@ -83,6 +95,46 @@ diff_component("src/components/MetricCard.tsx")
 
 ## 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>
+
+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 |
@@ -122,24 +174,11 @@ diff_component("src/components/MetricCard.tsx")
 
 ---
 
-## 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
-```
-
-Images display inline in iTerm2, Kitty, and Sixel terminals. Saved to `.frameshot/` by default.
-
----
-
 ## GitHub Action
 
-Free Chromatic alternative. Auto-posts before/after screenshots with diff on every PR:
+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
@@ -149,14 +188,43 @@ jobs:
   preview:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: kamegoro/frameshot@main
-        with:
-          paths: "./src/components/*.tsx"
+      - 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

package/action.yml

@@ -6,8 +6,17 @@ branding:
 
 inputs:
   paths:
-    description: "Glob patterns for component files to render (newline or comma separated)"
-    required: true
+    description: "Glob patterns for component files to render. Leave empty to auto-detect changed component files."
+    required: false
+    default: ""
+  extensions:
+    description: "Comma-separated file extensions to treat as components. Default covers React, Vue, Svelte, Astro, MDX."
+    required: false
+    default: ".jsx,.tsx,.vue,.svelte,.astro,.mdx"
+  exclude:
+    description: "Patterns to exclude (comma-separated). Matches against full file path."
+    required: false
+    default: "*.test.*,*.spec.*,*.stories.*,*.story.*"
   width:
     description: "Viewport width in px. Leave empty for auto-fit (recommended)."
     required: false
@@ -35,22 +44,42 @@ runs:
 
     - 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_EXTENSIONS: ${{ inputs.extensions }}
+        INPUT_EXCLUDE: ${{ inputs.exclude }}
         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"
+        cd "${{ github.action_path }}"
+        node scripts/render-changed.mjs
 
     - name: Comment on PR
       if: inputs.comment == 'true' && github.event_name == 'pull_request'
@@ -81,9 +110,60 @@ runs:
             return;
           }
 
-          let body = '## 📸 frameshot — Visual Preview\n\n';
+          // 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';
 
           if (hasBeforeAfter) {
             body += '| Component | Before | After | Diff |\n|---|---|---|---|\n';
@@ -95,23 +175,32 @@ runs:
             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`
+              // 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}\` | ${beforeImg} | <img src="data:image/png;base64,${afterData}" width="250" /> | ${diffImg} |\n`;
+              body += `| \`${entry.name}\` | ${beforeCell} | ${afterCell} | ${diffCell} |\n`;
             } else {
-              body += `| \`${entry.name}\` | <img src="data:image/png;base64,${afterData}" width="400" /> |\n`;
+              const afterUrl = await uploadImageToGitHub(afterFile);
+              const afterCell = afterUrl
+                ? `<img src="${afterUrl}" width="360" />`
+                : '*(unavailable)*';
+              body += `| \`${entry.name}\` | ${afterCell} |\n`;
             }
           }