@wasao/kagemusha 0.1.1 → 0.3.4

package/README.md

@@ -5,123 +5,212 @@ The shadow warrior for your documentation.
 
 ## What it does
 
-When you push code, Kagemusha automatically captures screenshots of your app and uploads them to S3. No more manually taking screenshots and updating help articles.
+`kagemusha capture` walks your app with Playwright, diffs each screenshot against the canonical version on S3, and pushes only what changed. Your help articles embed a stable URL once and the image refreshes itself on every merge to main.
 
-- **Auto-discover pages** — Crawls your app to find pages, select which ones to capture
-- **Playwright-powered** — Supports login, click actions, element selection, and full-page capture
-- **Annotations** — Add arrows, rectangles, and labels to screenshots
-- **S3 upload** — Screenshots are uploaded with stable URLs for embedding in help centers
-- **Local mode** — Save screenshots locally for review before uploading
-- **GitHub Actions ready** — Runs on every merge to main
+- **One verb (`capture`)** — capture → diff → push, all in one command
+- **S3-first** — `<id>/latest.png` is the canonical, embedded directly into help articles
+- **Component-level capture** — Playwright-powered, full-page / crop, pre-capture actions, element hiding
+- **Visual editor** — draw rectangles, arrows, labels; pick crop range by drag (`kagemusha edit`)
+- **Login once** — store `storageState` locally, or run a scripted login on every CI run
+- **Slack-ready** — `reports/summary.json` ships before/after URLs so notifications include image previews
 
 ## Quick Start
 
 ```bash
-# Install
 npm install -D @wasao/kagemusha
 
-# Interactive setup (generates config, discovers pages, creates workflow)
+# Interactive setup: config → login → discover pages → workflow
 npx kagemusha init
 
-# Preview screenshots locally
-npx kagemusha preview
+# Capture, diff vs canonical, publish what changed
+npx kagemusha capture
 
-# Run full pipeline (capture → upload)
-npx kagemusha run
+# Preview only — no canonical update
+npx kagemusha capture --dry-run
 ```
 
-## How it works
-
-1. `npx kagemusha init` scans your app and lets you pick which pages to screenshot
-2. Config and definition files are generated in your repo
-3. On every merge to main, GitHub Actions runs `npx kagemusha run`
-4. Screenshots are captured and uploaded to S3
-5. Help center articles reference the S3 URLs — images stay up to date automatically
-
 ## Commands
 
 | Command | Description |
-|---------|-------------|
-| `kagemusha init` | Interactive setup |
-| `kagemusha run` | Full pipeline: capture + upload |
-| `kagemusha capture` | Capture screenshots only |
-| `kagemusha preview` | Preview in browser |
-| `kagemusha validate` | Validate config files |
-| `kagemusha compare` | VRT diff detection (coming soon) |
-| `kagemusha publish` | Publish to Intercom/Zendesk (coming soon) |
+|---|---|
+| `kagemusha init` | Interactive setup (config + login + discover + workflow) |
+| `kagemusha login` | Refresh the saved login session (interactive or scripted) |
+| `kagemusha discover` | Re-crawl the app and add newly-found pages to definitions |
+| `kagemusha add <path>` | Add a single screenshot definition |
+| `kagemusha list` | List all definitions |
+| `kagemusha edit --id <id>` | Open the visual editor (crop range + annotations) |
+| `kagemusha capture` | Capture → diff → publish (use `--dry-run` to preview) |
+| `kagemusha validate` | Validate config and definition files |
+
+## Configuration
+
+`init` generates these files:
+
+```
+kagemusha.config.yaml         # base URL, viewport, publish destination
+.kagemusha/definitions.json   # one entry per screenshot
+.kagemusha/login.mjs          # optional scripted login (CI-friendly)
+.github/workflows/kagemusha.yml
+```
+
+`kagemusha.config.yaml`:
+
+```yaml
+app:
+  baseUrl: https://your-app.example.com
+screenshot:
+  defaultViewport: { width: 1440, height: 900, deviceScaleFactor: 2 }
+  defaultDiffThreshold: 0.005   # 0.5% pixel diff = flagged
+publish:
+  destination: s3               # or "local" for testing
+  cdnBucket: your-bucket
+  cdnBaseUrl: https://your-bucket.s3.ap-northeast-1.amazonaws.com
+```
+
+Definition (`.kagemusha/definitions.json`):
+
+```json
+[
+  {
+    "id": "dashboard",
+    "url": "/dashboard",
+    "capture": { "mode": "fullPage" },
+    "hideElements": [".intercom-launcher"],
+    "decorations": [
+      { "type": "rect", "target": { "x": 32, "y": 120, "width": 310, "height": 120 } }
+    ]
+  }
+]
+```
 
-## Config
+Run `kagemusha edit --id dashboard` to set the crop range and add decorations visually.
 
-`kagemusha init` generates these files:
+## Avoiding loading-state screenshots
 
+After `page.goto` kagemusha waits for `load` event + 3s of best-effort `networkidle` + 500ms hydration buffer. This handles most pages; SPAs with component-level skeletons may still capture mid-loading. Add a `beforeCapture` step per definition:
+
+```json
+{
+  "id": "analytics-overview",
+  "url": "/analytics/overview",
+  "beforeCapture": [
+    { "action": "waitForSelector", "selector": "text=Overview", "timeout": 15000 },
+    { "action": "wait", "ms": 3000 }
+  ]
+}
 ```
-kagemusha.config.yaml          # App URL, auth, save destination
-.kagemusha/definitions/*.json  # One file per screenshot
+
+Wait for a known page-specific element (page title, chart canvas, first table row, etc.), then a short buffer. Playwright's `text=` selector matches any rendered text.
+
+## Authentication
+
+If your app needs login, `init` generates a `.kagemusha/login.mjs` skeleton:
+
+```js
+/** @param {import('playwright-chromium').Page} page */
+export const login = async (page) => {
+  await page.goto("/login");
+  // Pick env names that fit your project (NOT EMAIL/PASSWORD, NOT KAGEMUSHA_*).
+  await page.fill('input[name="email"]', process.env.MY_APP_EMAIL ?? "");
+  await page.fill('input[name="password"]', process.env.MY_APP_PASSWORD ?? "");
+  await page.click('button[type="submit"]');
+  await page.waitForURL((url) => !url.pathname.startsWith("/login"));
+};
 ```
 
-### Screenshot definition example
+`kagemusha capture` auto-runs this on first invocation when no saved session exists, so CI just needs `npx kagemusha capture` — no separate login step. `baseURL` is set from your config, so relative paths work.
+
+For SSO / MFA / OAuth where scripting is impossible: run `kagemusha login` locally to save `.kagemusha/auth-state.json`, then `base64 -i .kagemusha/auth-state.json | pbcopy` and store the result as a `KAGEMUSHA_STORAGE_STATE` GitHub Secret. The generated workflow shows the restore step (commented out).
+
+## Deploying to GitHub Actions
+
+`init` generates `.github/workflows/kagemusha.yml`. Required secrets:
+
+- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` — IAM with `s3:GetObject` and `s3:PutObject` on your bucket, or use OIDC with `aws-actions/configure-aws-credentials@v4`
+- Login credentials (named whatever your `login.mjs` reads)
+- `SLACK_WEBHOOK_URL` — optional, see Notifications below
+
+Region is auto-detected from `publish.cdnBaseUrl` (`*.s3.<region>.amazonaws.com`), so no `AWS_REGION` env needed.
+
+The workflow triggers on `push: main` and runs `kagemusha capture` automatically.
+
+## Notifications
+
+`kagemusha capture` writes `reports/summary.json` with before/after URLs (when destination is S3 and a real push happened):
 
 ```json
 {
-  "id": "dashboard",
-  "name": "dashboard",
-  "url": "/dashboard",
-  "capture": { "mode": "fullPage" },
-  "hideElements": [".intercom-launcher"],
-  "decorations": [
+  "schemaVersion": "1",
+  "timestamp": "2026-05-15T12:34:56.789Z",
+  "dryRun": false,
+  "canonical": "https://your-bucket.s3.ap-northeast-1.amazonaws.com",
+  "counts": { "changed": 1, "unchanged": 5, "new": 2, "missing": 0 },
+  "results": [
     {
-      "type": "rect",
-      "target": { "x": 32, "y": 120, "width": 310, "height": 120 },
-      "style": { "color": "#FF0000", "strokeWidth": 2 }
-    }
+      "id": "engagements-overview",
+      "status": "changed",
+      "reason": "pixel-diff",
+      "diffPercentage": 2.34,
+      "urls": {
+        "before": "https://.../engagements-overview/previous.png",
+        "after": "https://.../engagements-overview/latest.png"
+      }
+    },
+    { "id": "new-page", "status": "new", "urls": { "after": "https://.../new-page/latest.png" } },
+    { "id": "dashboard", "status": "unchanged" }
   ]
 }
 ```
 
-## GitHub Actions
+The schema is **part of kagemusha's public API** — additive changes stay on `schemaVersion: "1"`, removals/renames bump it. kagemusha intentionally does not publish a pre-rendered diff image; consumers compare `before` vs `after` raw images (= Slack auto-unfurls both side by side).
+
+Slack notification (the generated workflow includes this; just set `SLACK_WEBHOOK_URL`):
 
 ```yaml
-name: Kagemusha
-on:
-  pull_request:
-    types: [closed]
-    branches: [main]
-
-jobs:
-  screenshots:
-    if: github.event.pull_request.merged == true
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npm ci
-      - run: npx kagemusha run
-        env:
-          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+- name: Slack notify
+  env:
+    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+  run: |
+    [ -n "$SLACK_WEBHOOK_URL" ] || exit 0
+    jq -c -f .kagemusha/notify-slack.jq reports/summary.json | while IFS= read -r payload; do
+      [ -z "$payload" ] && continue
+      curl -sS -X POST "$SLACK_WEBHOOK_URL" \
+        -H 'Content-Type: application/json' \
+        --data "$payload"
+    done
 ```
 
-## Try it locally
+One message per changed/new screenshot — Slack unfurls the `before`/`after` URLs per-message, so each post shows its own image previews instead of a single message that just lists URLs as plain text.
+
+The message format is defined in `.kagemusha/notify-slack.jq` (generated by `kagemusha init`). Each line of jq output becomes one Slack `chat.postMessage` body, so you can customize freely (add `blocks`, override `channel`, etc). Test locally:
 
 ```bash
-cd example
-bun install
-bun run serve          # Start sample app
-bunx kagemusha init    # Set up kagemusha
-bunx kagemusha preview # See screenshots
+jq -c -f .kagemusha/notify-slack.jq reports/summary.json
 ```
 
-## Roadmap
+The same `summary.json` works for Discord (swap `text` → `content`) or PR comments via `actions/github-script` — copy the jq file and tweak.
+
+## Positioning
+
+**kagemusha is NOT a PR-gating VRT tool.** For per-commit baselines and PR diff review with hosted HTML reports, use [reg-suit](https://github.com/reg-viz/reg-suit), [Chromatic](https://www.chromatic.com/), or [Percy](https://percy.io/).
+
+kagemusha is for **post-merge auto-update of help center screenshots**, where stable embeddable URLs matter more than per-commit baseline correctness.
+
+## Releasing
+
+Automated via [release-please](https://github.com/googleapis/release-please).
+
+1. **Write PRs with [Conventional Commits](https://www.conventionalcommits.org/) titles**:
+   - `feat: ...` → minor bump (= 0.2.0 → 0.3.0)
+   - `fix: ...` → patch bump (= 0.2.0 → 0.2.1)
+   - `feat!: ...` or `BREAKING CHANGE:` in body → major (= 1.0.0+)
+   - `chore: ...` / `docs: ...` → no version bump
+   - Squash merge propagates the PR title as the commit on `main`.
+2. **release-please opens a "Release PR" automatically** whenever there's anything to release. It bumps `package.json`, updates `.release-please-manifest.json`, and regenerates `CHANGELOG.md`.
+3. **Merge the Release PR** → release-please tags `v0.X.Y` and publishes a GitHub Release.
+4. **`release.yml` triggers on `release: published`** → builds and runs `pnpm publish --provenance` to npm. Requires the `NPM_TOKEN` secret.
 
-- [x] Screenshot capture with Playwright
-- [x] Annotations (rect, arrow, label)
-- [x] S3 upload
-- [x] Auto-discover pages
-- [ ] Visual regression testing (VRT)
-- [ ] Intercom / Zendesk integration
-- [ ] AI-powered text updates
+The `kagemusha` CLI reads its version from `package.json` at runtime, so release-please only needs to touch one file.
 
 ## License
 

package/dist/commands/add.d.ts

@@ -0,0 +1,6 @@
+interface AddOptions {
+    id?: string;
+}
+export declare const addCommand: (pagePath: string, options: AddOptions) => Promise<void>;
+export {};
+//# sourceMappingURL=add.d.ts.map

package/dist/commands/add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/commands/add.ts"],"names":[],"mappings":"AAQA,UAAU,UAAU;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,eAAO,MAAM,UAAU,GACtB,UAAU,MAAM,EAChB,SAAS,UAAU,KACjB,OAAO,CAAC,IAAI,CAyBd,CAAC"}

package/dist/commands/add.js

@@ -0,0 +1,26 @@
+import chalk from "chalk";
+import { findProjectRoot, loadDefinitions, saveDefinitions, } from "../lib/config.js";
+import { deriveIdFromPath } from "../lib/definition.js";
+export const addCommand = async (pagePath, options) => {
+    const projectRoot = findProjectRoot();
+    const definitions = loadDefinitions(projectRoot);
+    const baseId = options.id ?? deriveIdFromPath(pagePath);
+    // If ID already exists, append a suffix
+    let id = baseId;
+    let suffix = 2;
+    while (definitions.some((d) => d.id === id)) {
+        id = `${baseId}-${suffix}`;
+        suffix++;
+    }
+    definitions.push({
+        id,
+        name: id,
+        url: pagePath,
+        capture: { mode: "fullPage" },
+        hideElements: [],
+        decorations: [],
+    });
+    saveDefinitions(definitions, projectRoot);
+    console.log(chalk.green(`\n✅ Added ${id}\n`));
+};
+//# sourceMappingURL=add.js.map

package/dist/commands/add.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.js","sourceRoot":"","sources":["../../src/commands/add.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EACN,eAAe,EACf,eAAe,EACf,eAAe,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAMxD,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAC9B,QAAgB,EAChB,OAAmB,EACH,EAAE;IAClB,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC;IACtC,MAAM,WAAW,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAEjD,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,IAAI,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAExD,wCAAwC;IACxC,IAAI,EAAE,GAAG,MAAM,CAAC;IAChB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAC7C,EAAE,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,EAAE,CAAC;IACV,CAAC;IAED,WAAW,CAAC,IAAI,CAAC;QAChB,EAAE;QACF,IAAI,EAAE,EAAE;QACR,GAAG,EAAE,QAAQ;QACb,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE;QAC7B,YAAY,EAAE,EAAE;QAChB,WAAW,EAAE,EAAE;KACf,CAAC,CAAC;IAEH,eAAe,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IAC1C,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC,CAAC"}

package/dist/commands/capture.d.ts

@@ -1,8 +1,9 @@
 interface CaptureOptions {
     ids?: string;
-    all?: boolean;
+    dryRun?: boolean;
     open?: boolean;
+    threshold?: string;
 }
-export declare function captureCommand(options: CaptureOptions): Promise<void>;
+export declare const captureCommand: (options: CaptureOptions) => Promise<void>;
 export {};
 //# sourceMappingURL=capture.d.ts.map

package/dist/commands/capture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/commands/capture.ts"],"names":[],"mappings":"AAKA,UAAU,cAAc;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAkD3E"}
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../src/commands/capture.ts"],"names":[],"mappings":"AAsBA,UAAU,cAAc;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AA+CD,eAAO,MAAM,cAAc,GAC1B,SAAS,cAAc,KACrB,OAAO,CAAC,IAAI,CAUd,CAAC"}

package/dist/commands/capture.js

@@ -1,9 +1,56 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
 import chalk from "chalk";
-import { annotateScreenshots } from "../lib/annotate.js";
+import { hasAuthState, resolveLoginScriptPath } from "../lib/auth.js";
+import { handleAwsError } from "../lib/aws-error.js";
+import { createS3Canonical, getCanonicalPath, getOutputDir, } from "../lib/canonical.js";
 import { findProjectRoot, loadConfig, loadDefinitions } from "../lib/config.js";
+import { diffImages } from "../lib/diff.js";
 import { captureScreenshots } from "../lib/screenshot.js";
-export async function captureCommand(options) {
-    console.log(chalk.bold("\n🥷 Kagemusha — Capture screenshots\n"));
+import { cleanupStaging, ensureStagingDirs, getStagingDir, getStagingPath, } from "../lib/staging.js";
+// Schema version of `reports/summary.json`. Bump on any breaking change.
+const SUMMARY_SCHEMA_VERSION = "1";
+const writeSummaryReport = (projectRoot, report) => {
+    const reportPath = path.join(projectRoot, "reports", "summary.json");
+    fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+    fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+};
+// Open a file with the OS's default viewer (Preview on macOS, etc.).
+// `detached + unref` lets the kagemusha process exit while the viewer keeps
+// running. We deliberately avoid `shell: true` so paths with spaces don't get
+// re-split — argv is passed straight through to the program.
+const openInDefaultApp = (filePath) => {
+    if (process.platform === "darwin") {
+        spawn("open", [filePath], { detached: true, stdio: "ignore" }).unref();
+    }
+    else if (process.platform === "win32") {
+        // `start` is a cmd.exe builtin; we invoke cmd directly. The empty
+        // string after `start` is the (required) window title placeholder.
+        spawn("cmd", ["/c", "start", "", filePath], {
+            detached: true,
+            stdio: "ignore",
+        }).unref();
+    }
+    else {
+        spawn("xdg-open", [filePath], { detached: true, stdio: "ignore" }).unref();
+    }
+};
+export const captureCommand = async (options) => {
+    try {
+        await runCapture(options);
+    }
+    catch (e) {
+        if (handleAwsError(e)) {
+            process.exitCode = 1;
+            return;
+        }
+        throw e;
+    }
+};
+const runCapture = async (options) => {
+    const dryRun = options.dryRun === true;
+    console.log(chalk.bold(`\n🥷 Kagemusha — Capture${dryRun ? " (dry-run)" : ""}\n`));
     const projectRoot = findProjectRoot();
     const config = loadConfig(projectRoot);
     let definitions = loadDefinitions(projectRoot);
@@ -12,27 +59,216 @@ export async function captureCommand(options) {
         definitions = definitions.filter((d) => ids.includes(d.id));
     }
     if (definitions.length === 0) {
-        console.log(chalk.yellow("No screenshot definitions found."));
+        console.log(chalk.yellow("No screenshot definitions to capture.\n"));
         return;
     }
-    console.log(chalk.blue(`📸 Capturing ${definitions.length} screenshot(s)...`));
-    const results = await captureScreenshots(config, definitions, projectRoot);
-    console.log(chalk.blue("🎨 Drawing annotations..."));
-    const annotated = await annotateScreenshots(definitions, results, projectRoot);
-    console.log(chalk.bold.green(`\n✅ Done! Screenshots saved to screenshots/\n`));
-    for (const r of annotated) {
-        console.log(chalk.gray(`  ${r.id} → ${r.annotatedPath}`));
+    // Auto-login: if a login script exists (auth.scriptPath, or default
+    // .kagemusha/login.mjs) but no saved session is on disk, run it before
+    // capturing. This is what makes CI work with no pre-baked storage state.
+    if (!hasAuthState(projectRoot) &&
+        resolveLoginScriptPath(config, projectRoot)) {
+        console.log(chalk.blue("🔐 No saved session found, running login script...\n"));
+        const { loginCommand } = await import("./login.js");
+        await loginCommand();
+        // loginCommand absorbs LoginError and sets exitCode internally.
+        // If no auth-state was produced, abort capture so we don't screenshot
+        // the login screen.
+        if (!hasAuthState(projectRoot)) {
+            process.exitCode = 1;
+            return;
+        }
     }
+    ensureStagingDirs(projectRoot);
+    const threshold = options.threshold
+        ? Number.parseFloat(options.threshold)
+        : (config.screenshot.defaultDiffThreshold ?? 0.005);
+    const remote = createS3Canonical(config);
+    const outputDir = getOutputDir(config, projectRoot);
+    const stagingDir = getStagingDir(projectRoot);
+    if (remote) {
+        console.log(chalk.gray(`  canonical: ${remote.label()}`));
+    }
+    else {
+        console.log(chalk.gray(`  canonical: ${outputDir} (local)`));
+    }
+    // 1. Capture into staging (annotated)
+    console.log(chalk.blue(`\n📸 Capturing ${definitions.length} screenshot(s) to staging...\n`));
+    const failures = await captureScreenshots(config, definitions, projectRoot, {
+        outputDir: stagingDir,
+    });
+    const failureReasons = new Map(failures.map((f) => [f.id, f.reason]));
+    const results = [];
+    // Track final paths (where the user can find each capture after the run)
+    const finalPathFor = new Map();
+    const pendingPushes = [];
+    for (const def of definitions) {
+        const canonicalPath = getCanonicalPath(config, projectRoot, def.id);
+        const stagingPath = getStagingPath(projectRoot, def.id);
+        if (!fs.existsSync(stagingPath)) {
+            results.push({
+                id: def.id,
+                status: "missing",
+                reason: failureReasons.get(def.id),
+            });
+            continue;
+        }
+        // Pull canonical from remote (S3) into outputDir; for local mode just check existence
+        const fetchResult = remote
+            ? await remote.fetch(def.id, canonicalPath)
+            : fs.existsSync(canonicalPath)
+                ? "ok"
+                : "not-found";
+        const queuePush = (push) => {
+            if (dryRun) {
+                finalPathFor.set(def.id, push.stagingPath);
+            }
+            else {
+                pendingPushes.push(push);
+            }
+        };
+        // New: no canonical yet — adopt staging as canonical (unless dry-run)
+        if (fetchResult === "not-found") {
+            const result = { id: def.id, status: "new" };
+            results.push(result);
+            queuePush({
+                id: def.id,
+                stagingPath,
+                canonicalPath,
+                onUrls: (urls) => {
+                    if (urls)
+                        result.urls = urls;
+                },
+            });
+            continue;
+        }
+        const result = await diffImages(canonicalPath, stagingPath);
+        if (result.match) {
+            results.push({ id: def.id, status: "unchanged" });
+            fs.rmSync(stagingPath, { force: true });
+            finalPathFor.set(def.id, canonicalPath);
+        }
+        else if (result.reason === "layout-diff") {
+            const item = {
+                id: def.id,
+                status: "changed",
+                reason: "layout-diff",
+                canonical: result.canonical,
+                staging: result.staging,
+            };
+            results.push(item);
+            queuePush({
+                id: def.id,
+                stagingPath,
+                canonicalPath,
+                onUrls: (urls) => {
+                    if (urls)
+                        item.urls = urls;
+                },
+            });
+        }
+        else {
+            const item = {
+                id: def.id,
+                status: "changed",
+                reason: "pixel-diff",
+                diffPercentage: result.diffPercentage,
+            };
+            results.push(item);
+            queuePush({
+                id: def.id,
+                stagingPath,
+                canonicalPath,
+                onUrls: (urls) => {
+                    if (urls)
+                        item.urls = urls;
+                },
+            });
+        }
+    }
+    // Parallel promote — push to remote + copy to local outputDir.
+    // Promise.all keeps S3 throughput high while node manages local fs serially.
+    if (pendingPushes.length > 0) {
+        fs.mkdirSync(outputDir, { recursive: true });
+        await Promise.all(pendingPushes.map(async ({ id, stagingPath, canonicalPath, onUrls }) => {
+            // Push to remote first so a failure doesn't leave local ahead of S3
+            const urls = remote ? await remote.push(id, stagingPath) : undefined;
+            fs.copyFileSync(stagingPath, canonicalPath);
+            fs.rmSync(stagingPath, { force: true });
+            finalPathFor.set(id, canonicalPath);
+            onUrls(urls);
+        }));
+    }
+    // 3. Print summary
+    const changed = results.filter((r) => r.status === "changed");
+    const unchanged = results.filter((r) => r.status === "unchanged");
+    const newly = results.filter((r) => r.status === "new");
+    const missing = results.filter((r) => r.status === "missing");
+    for (const r of results) {
+        if (r.status === "unchanged") {
+            console.log(chalk.gray(`  ✓ ${r.id}`));
+        }
+        else if (r.status === "new") {
+            const action = dryRun ? "would be added" : "added to canonical";
+            console.log(chalk.cyan(`  + ${r.id} (${action})`));
+        }
+        else if (r.status === "missing") {
+            const detail = r.reason ? `: ${r.reason}` : "";
+            console.log(chalk.red(`  ✗ ${r.id} (capture failed${detail})`));
+        }
+        else if (r.status === "changed") {
+            const detail = r.reason === "pixel-diff"
+                ? `${r.diffPercentage.toFixed(2)}%`
+                : `layout-diff: ${r.canonical.width}×${r.canonical.height} → ${r.staging.width}×${r.staging.height}`;
+            const action = dryRun ? "→ would update" : "→ updated";
+            console.log(chalk.yellow(`  ~ ${r.id} (${detail}) ${chalk.gray(action)}`));
+        }
+    }
+    // 4. Cleanup staging — applied entries are already removed individually,
+    // so this only matters when nothing changed (everything was unchanged).
+    if (changed.length === 0 && newly.length === 0) {
+        cleanupStaging(projectRoot);
+    }
+    console.log("");
+    console.log(chalk.bold(`changed: ${changed.length} / unchanged: ${unchanged.length} / new: ${newly.length}` +
+        (missing.length > 0 ? ` / missing: ${missing.length}` : "")));
+    if (dryRun && (changed.length > 0 || newly.length > 0)) {
+        console.log(chalk.gray(`\nDrop --dry-run to update canonical${remote ? ` (${remote.label()})` : ""}.`));
+    }
+    // 5. Write the structured report.
+    // `reports/summary.json` is part of kagemusha's PUBLIC API — see README
+    // "Notifications" section. Bump `schemaVersion` (or kagemusha major) on
+    // breaking changes to the shape.
+    writeSummaryReport(projectRoot, {
+        schemaVersion: SUMMARY_SCHEMA_VERSION,
+        timestamp: new Date().toISOString(),
+        dryRun,
+        canonical: remote ? remote.label() : `${outputDir} (local)`,
+        counts: {
+            changed: changed.length,
+            unchanged: unchanged.length,
+            new: newly.length,
+            missing: missing.length,
+        },
+        results,
+    });
+    // 6. Open changed/new results in default viewer
     if (options.open) {
-        const { chromium } = await import("playwright-chromium");
-        const browser = await chromium.launch({ headless: false });
-        const context = await browser.newContext();
-        for (const result of annotated) {
-            const page = await context.newPage();
-            await page.goto(`file://${result.annotatedPath}`);
+        for (const r of [...changed, ...newly]) {
+            const p = finalPathFor.get(r.id);
+            if (p && fs.existsSync(p)) {
+                openInDefaultApp(p);
+            }
+        }
+    }
+    // Exit code: 1 if dry-run found pixel diffs over threshold (CI gate use case)
+    if (dryRun) {
+        const overThreshold = changed.filter((r) => r.status === "changed" &&
+            r.reason === "pixel-diff" &&
+            r.diffPercentage / 100 > threshold);
+        if (overThreshold.length > 0) {
+            process.exitCode = 1;
         }
-        console.log(chalk.gray("\nPress Ctrl+C to close preview.\n"));
-        await new Promise(() => { });
     }
-}
+    console.log("");
+};
 //# sourceMappingURL=capture.js.map