afterbefore 0.1.0 → 0.1.1

package/README.md

@@ -1,40 +1,30 @@
 # afterbefore
 
-Automatic before/after screenshot capture for pull requests. **The git diff is the config.**
+[![npm version](https://img.shields.io/npm/v/afterbefore)](https://www.npmjs.com/package/afterbefore)
+[![npm downloads](https://img.shields.io/npm/dm/afterbefore)](https://www.npmjs.com/package/afterbefore)
 
-Change code, run one command, get a visual comparison. No config files, no manual URL lists, no SaaS — `afterbefore` reads your diff, walks the import graph, and captures both versions automatically.
+Automatic before/after screenshot capture for Next.js pull requests. **The git diff is the config.**
+
+Change code, run one command, and get a visual report of only impacted routes.
 
 ```bash
 npx afterbefore
 ```
 
-## The Problem
-
-Visual PR reviews are painful:
-
-1. Switch to main, start the app, take screenshots
-2. Switch back to your branch, start the app, take more screenshots
-3. Crop, label, and paste into the PR description
-
-This takes 5-10 minutes. Most developers skip it. Reviewers approve visual changes blind.
-
-## How It Works
-
-```
-git diff → classify changed files → build import graph → BFS to find affected pages
-→ git worktree for base version → start 2 dev servers → Playwright capture
-→ pixelmatch diff → side-by-side comparison → HTML report + PR comment
-```
-
-1. **Diff** — reads `git diff --name-status` to find changed files
-2. **Classify** — categorizes as page, component, style, layout, utility, config, test
-3. **Import graph** — parses all imports with `es-module-lexer`, resolves `@/` tsconfig aliases
-4. **Impact analysis** — BFS traverses the reverse import graph (depth 3) to find affected pages
-5. **Worktree** — creates a git worktree for the base branch, installs deps
-6. **Dev servers** — starts two Next.js dev servers (before + after) on random ports
-7. **Capture** — Playwright takes full-page screenshots at 1280x720 for each affected route
-8. **Compare** — pixelmatch detects pixel-level differences, sharp generates side-by-side images
-9. **Report** — HTML card grid, drag-to-compare sliders, markdown summary, optional PR comment
+## What It Does
+
+1. Reads changed files from `git diff` against a base ref
+2. Builds an import graph and finds affected `app/**/page.*` routes
+3. Handles layout/global style changes that are not direct imports
+4. Creates a temporary git worktree for the base ref
+5. Starts two Next.js dev servers (before + after)
+6. Captures screenshots with Playwright
+7. Computes pixel diffs with `pixelmatch`
+8. Generates:
+   - `index.html` visual report
+   - per-route slider pages for changed routes
+   - `summary.md` for PR comments
+9. Optionally posts/updates a GitHub PR comment (`--post`)
 
 ## Installation
 
@@ -42,80 +32,109 @@ git diff → classify changed files → build import graph → BFS to find affec
 # npm
 npm install --save-dev afterbefore
 
-# From GitHub (builds automatically on install)
+# from GitHub
 npm install --save-dev github:kairevicius/afterbefore
 
-# Or run directly without installing
+# run without installing
 npx afterbefore
 ```
 
-Playwright's Chromium browser is required for screenshots:
-
-```bash
-npx playwright install chromium
-```
-
 ## Usage
 
 ```bash
-# Compare current branch against main
+# compare current branch vs main
 npx afterbefore
 
-# Compare against a different base
+# compare against a different base branch
 npx afterbefore --base develop
 
-# Capture and post results to the open PR
+# post/update comment on the open PR (requires gh auth)
 npx afterbefore --post
 ```
 
-### Options
+### CLI Options
 
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--base <ref>` | Base branch or ref to compare against | `main` |
-| `--output <dir>` | Output directory | `.afterbefore` |
-| `--post` | Post results as a PR comment via `gh` CLI | `false` |
+| `--output <dir>` | Output directory root | `.afterbefore` |
+| `--post` | Post/update results as a PR comment via `gh` CLI | `false` |
+| `--threshold <percent>` | Diff threshold percentage below which route is marked unchanged | `0.1` |
+| `--max-routes <count>` | Maximum routes to capture (`0` = unlimited) | `6` |
+| `--open` | Auto-open `index.html` after run | `false` |
+| `--width <pixels>` | Viewport width | `1280` |
+| `--height <pixels>` | Viewport height | `720` |
+| `--device <name>` | Playwright device preset (for example `iPhone 14`) | unset |
+| `--delay <ms>` | Extra wait after page load/actions | `0` |
+| `--no-auto-tabs` | Disable ARIA tab state auto-capture | auto-tabs enabled |
+| `--max-tabs <count>` | Max auto-detected inactive tabs per route | `5` |
+| `--auto-sections` | Auto-detect and capture heading-labeled sections | `false` |
+| `--max-sections <count>` | Max auto-detected sections per page/tab state | `10` |
+
+## Optional Scenario Config
+
+`afterbefore` can run scripted interactions before capture via config files:
+
+- `afterbefore.config.json`
+- `afterbefore.config.js`
+- `afterbefore.config.mjs`
+
+Example:
+
+```json
+{
+  "scenarios": {
+    "/pricing": [
+      {
+        "name": "annual-toggle",
+        "actions": [
+          { "click": "[data-testid='billing-toggle']" },
+          { "wait": 300 }
+        ]
+      },
+      {
+        "name": "plan-cards-only",
+        "selector": "[data-testid='plan-grid']",
+        "actions": []
+      }
+    ]
+  }
+}
+```
+
+When a route has manual scenarios, default auto tab/section expansion is skipped for that route.
 
 ## Output
 
-```
+Each run creates a dated session directory:
+
+```text
 .afterbefore/
-  summary.md              Markdown table (for PR comments)
-  index.html              HTML report with card grid
-  _root/
-    before.png             Screenshot of / on base branch
-    after.png              Screenshot of / on current branch
-    diff.png               Pixel diff overlay
-    side-by-side.png       Labeled comparison image
-    slider.html            Interactive drag-to-compare
-  about/
-    before.png
-    after.png
-    diff.png
-    side-by-side.png
-    slider.html
+  <branch>_YYYY-MM-DD/
+    index.html
+    summary.md
+    _root-before.png
+    _root-after.png
+    _root-diff.png
+    _root-compare.png       # only when changed
+    _root-slider.html       # only when changed
+    about-before.png
+    about-after.png
+    about-diff.png
+    about-compare.png
+    about-slider.html
 ```
 
-Open `index.html` in a browser to see all comparisons at a glance. Each changed route gets a card with before/after/diff images and a link to the interactive slider.
-
-## Requirements
-
-- Node.js 18+
-- Git
-- Next.js project using the app router
-- Playwright Chromium (`npx playwright install chromium`)
-
-## How It's Different
+Open `index.html` to review all captured states.
 
-Every visual regression tool either captures everything on every run (Chromatic, Lost Pixel) or requires manual URL configuration (Percy, BackstopJS). `afterbefore` is the only tool that figures out what to capture from the code diff.
+## Requirements And Limits
 
-| | Visual regression tools | afterbefore |
-|---|---|---|
-| Config | URL lists, story lists | Zero — reads git diff |
-| Scope | Everything, every run | Only affected pages |
-| Philosophy | "Did anything break?" | "Here's what changed" |
-| Hosting | Cloud SaaS | Local, nothing leaves your machine |
-| Cost | Per-snapshot pricing | Free, open source |
+- Node.js `>=18`
+- Git repository
+- Next.js App Router project (`app/` pages)
+- Dependencies installable in temporary worktree
+- `gh` CLI authenticated if using `--post`
+- Dynamic routes (for example `app/blog/[slug]/page.tsx`) are currently skipped
 
 ## License