snapdrift 0.4.0 → 0.5.1

package/docs/contracts.md

@@ -41,7 +41,9 @@ SnapDrift reads runtime behavior from `.github/snapdrift.json` by default.
 | `snap.projectId` | `string` | Snap project ID or `"auto"` (default: `"auto"`, derives from `GITHUB_REPOSITORY`) |
 | `snap.onUnavailable` | `string` | Behavior when Snap is unreachable: `"fail"` (default), `"warn-and-skip"`, or `"fallback-local"` |
 
-### Example
+When `provider: "snap"` is set, the `snap` block is required. Exactly one of `snap.apiKeyEnv` or `snap.apiKey` must be present. `snap.apiKey` accepts `${VAR}` interpolation (for example `"${SNAP_API_KEY}"`); the referenced environment variable must be set at runtime or the config loader throws.
+
+### Example (local provider)
 
 ```json
 {
@@ -62,6 +64,33 @@ SnapDrift reads runtime behavior from `.github/snapdrift.json` by default.
 }
 ```
 
+### Example (Snap provider)
+
+```json
+{
+  "baselineArtifactName": "ui-foundation-snapdrift-baseline",
+  "workingDirectory": ".",
+  "baseUrl": "http://127.0.0.1:8080",
+  "resultsFile": "qa-artifacts/snapdrift/baseline/current/results.json",
+  "manifestFile": "qa-artifacts/snapdrift/baseline/current/manifest.json",
+  "screenshotsRoot": "qa-artifacts/snapdrift/baseline/current",
+  "routes": [
+    { "id": "root-index-desktop", "path": "/", "viewport": "desktop" },
+    { "id": "root-index-mobile", "path": "/", "viewport": "mobile" }
+  ],
+  "diff": {
+    "threshold": 0.01,
+    "mode": "report-only"
+  },
+  "provider": "snap",
+  "snap": {
+    "apiKeyEnv": "SNAP_API_KEY",
+    "projectId": "auto",
+    "onUnavailable": "fail"
+  }
+}
+```
+
 ## Baseline artifact
 
 The published baseline bundle contains:
@@ -224,7 +253,7 @@ All three directories can be overridden with `--baseline-dir`, `--current-dir`,
 
 ### migrate-baselines
 
-Migrate baselines between local storage and Snap.
+Migrate baselines between local storage and Snap. Both directions require a `snap` block in `snapdrift.json` (or `--to local` for the `snap → local` direction, since the export call still talks to Snap first).
 
 **Upload local baselines to Snap:**
 
@@ -232,10 +261,10 @@ Migrate baselines between local storage and Snap.
 snapdrift migrate-baselines --to snap [--config <path>] [--baseline-dir <dir>]
 ```
 
-- Reads local manifest + baseline images from the baseline directory.
+- Reads `results.json`, `manifest.json`, and `screenshots/*.png` from the local baseline directory.
 - Uploads as the initial accepted baseline on Snap via `POST /v1/visual/projects/:id/baselines`.
-- Idempotent: skips upload if a baseline already exists with the matching commit SHA.
-- Requires snapdrift.json with `provider: "snap"` (or snap config).
+- Idempotent: if a baseline already exists for the same commit SHA (derived from `GITHUB_SHA` or `git rev-parse HEAD`), the upload is skipped.
+- Screenshots are base64-encoded in the request body; very large suites may want to migrate per-route.
 
 **Download Snap baselines to local:**
 
@@ -244,9 +273,11 @@ snapdrift migrate-baselines --to local --from snap [--accept-cross-engine] [--co
 ```
 
 - Downloads baselines from Snap's export endpoint.
-- Writes to the local baseline directory.
-- Without `--accept-cross-engine`: hard-errors if the exported baselines were captured by a different engine.
-- With `--accept-cross-engine`: overrides the engine name to `snapdrift-local` in the imported manifest (visual differences may occur).
+- Writes `results.json`, `manifest.json`, and `screenshots/*.png` to the local baseline directory.
+- Writes `.migration-metadata.json` next to the baseline recording `source`, `migratedAt`, and the engine that produced the export.
+- Without `--accept-cross-engine`: hard-errors if the exported manifest's engine name is not `snapdrift-local`.
+- With `--accept-cross-engine`: overrides the engine name to `snapdrift-local` in the imported manifest (visual differences may occur when the captures came from a different engine).
+- Requires the Snap export endpoint to be available; if it is not yet wired up, the command fails with an actionable message instead of producing a partial baseline.
 
 ### init
 
@@ -256,10 +287,93 @@ snapdrift migrate-baselines --to local --from snap [--accept-cross-engine] [--co
 snapdrift init --from-snap-action <workflow-yaml-path>
 ```
 
-- Reads an existing Snap `github-action/` workflow YAML.
-- Translates Snap action inputs into `.github/snapdrift.json`.
-- Emits `.github/MIGRATION_NOTES.md` listing warnings and deferred decisions.
-- Idempotent: refuses to overwrite an existing `snapdrift.json`.
+- Reads an existing `snap/github-action` workflow YAML.
+- Locates the step that uses `snap/github-action` (or any action whose `uses:` matches `snap/.../action`).
+- Translates known inputs into `.github/snapdrift.json`. Sets `provider: "snap"` (and the `snap` block) only when the source workflow declared `snap-api-key-env` or `snap-project-id`; workflows without Snap-specific inputs produce a local-provider config.
+- Emits `.github/MIGRATION_NOTES.md` grouped by severity (warnings first, then notes).
+- Idempotent against `snapdrift.json`: refuses to overwrite an existing file.
+
+The codemod maps fields one-to-one when it can. The full mapping is:
+
+| Snap action input | snapdrift config |
+|:------------------|:-----------------|
+| `threshold` / `diff-threshold` | `diff.threshold` |
+| `fail-on-changes` | `diff.mode: "fail-on-changes"` |
+| `fail-on-incomplete` | `diff.mode: "fail-on-incomplete"` |
+| (no enforcement flag) | `diff.mode: "report-only"` |
+| `snap-api-key-env` | `snap.apiKeyEnv` |
+| `snap-api-url` | `snap.apiUrl` |
+| `snap-project-id` | `snap.projectId` |
+| `format` | dropped (warning — SnapDrift is PNG-only) |
+| `baseline_tag` | dropped (warning — SnapDrift uses commit-based baselines) |
+| `routes` / page list | left empty (warning — fill in `routes[]` manually) |
+| `baseUrl` | placeholder `http://localhost:3000` (warning — update to your real app) |
+
+Two files are written: `.github/snapdrift.json` and `.github/MIGRATION_NOTES.md`.
+
+## Snap provider
+
+When `provider: "snap"`, every `capture` / `diff` / `publishBaseline` call goes through `SnapProvider`, which talks to Snap's hosted `/v1/visual/*` API instead of writing to the runner filesystem. The local provider keeps working exactly as before.
+
+### Local-capture hybrid
+
+If `baseUrl` resolves to a local address (see [`isLocalBaseUrl`](#islocalbaseurl-detection) below), SnapDrift runs Playwright on the runner to render the page and uploads the resulting screenshots to Snap. This is necessary whenever your `baseUrl` is a server only the runner can reach (the common case) — Snap's render worker cannot reach a `127.0.0.1` or `localhost` server.
+
+The hybrid path is transparent to the user: the same provider factory picks it, and the output `results.json` carries `provider: "snap"` plus `captureMode: "local-upload"` so downstream consumers can tell which path produced the run. The action's `Install Playwright Chromium` step is gated on this hybrid, so a `provider: "snap"` config with a remote `baseUrl` will not download Playwright Chromium.
+
+### API contract
+
+SnapDrift uses a small, stable subset of the Snap API:
+
+| Endpoint | Used by |
+|:---------|:--------|
+| `POST /v1/visual/projects/:id/runs` | Create a run; client passes `baseUrl`, `trigger`, optional `baselineId` and `branch` |
+| `POST /v1/visual/runs/:run_id/captures` | Submit each route as a capture; client passes `routeId`, `routePath`, `viewportDescriptorJson` |
+| `POST /v1/visual/captures/:capture_id/local-result` | Hybrid path: upload the locally rendered PNG and its dimensions |
+| `POST /v1/visual/projects/:id/baselines` | Publish a baseline from a run's rendered captures (primary path) or upload a pre-built local baseline (migration path) |
+| `GET /v1/visual/projects/:id/baselines/latest` | Resolve the latest accepted baseline for diff runs |
+| `GET /v1/visual/runs/:run_id` | Poll a run until it reaches a terminal state (`pass`, `fail`, `error`, or `new`) |
+
+`new` is a terminal state for baseline runs: a fresh capture with no baseline to diff against settles to `new` and `publishBaseline` harvests its object keys. Treating `new` as in-flight (the natural reading) would have the client poll forever.
+
+### Retry and fallback
+
+The Snap HTTP client classifies responses and applies the following rules:
+
+- **2xx** — success, return the parsed body.
+- **4xx** — non-retryable. The client throws `SnapApiError(status, message, path)` immediately. `onUnavailable` is **not** consulted for 4xx — a 404 from `/baselines/latest` is a "no baseline yet" signal, but a 4xx from `/runs` is a configuration error that retrying won't fix.
+- **5xx** — retryable up to 3 attempts with exponential backoff (`1 s` → `2 s` → `4 s`, capped at `30 s` total). If the final attempt still returns 5xx, the client falls through to the `onUnavailable` handler.
+- **Network errors** — same retry/backoff behavior as 5xx. After exhaustion, falls through to the `onUnavailable` handler.
+
+`onUnavailable` is consulted once retries are exhausted:
+
+- `"fail"` (default) — throw the underlying error to fail the action.
+- `"warn-and-skip"` — log a warning, throw `SnapSkipError`. The wrapper actions catch this and write a skipped summary, exiting 0.
+- `"fallback-local"` — log a warning, throw `SnapFallbackError`. The wrapper actions catch this and continue the pipeline with `LocalProvider`.
+
+### `isLocalBaseUrl` detection
+
+`isLocalBaseUrl(baseUrl)` returns `true` when the URL hostname is:
+
+- `localhost` or any subdomain ending in `.localhost`
+- `0.0.0.0`
+- `::1`
+- Any IPv4 address in `127.0.0.0/8` (for example `127.0.0.1`)
+
+The function is intentionally permissive about bracketed IPv6 (`[::1]`) and case (`LocalHost`). It returns `false` on any URL that fails to parse.
+
+### Error classes
+
+All four error classes are exported from `lib/provider.mjs` and `lib/snap-provider.mjs`. They are the contract for "Snap cannot proceed" — wrapper actions and CLI commands handle them as a group.
+
+| Class | Thrown when | Typical handler |
+|:------|:------------|:----------------|
+| `SnapApiError` | A 4xx response was received, or a 5xx/network error was retried to exhaustion. Carries `status` and `path` properties. | Surface the message; do not retry. |
+| `SnapUnavailableError` | A network error or 5xx was retried to exhaustion (used internally; usually re-wrapped as `SnapApiError`). | Treat as a temporary outage. |
+| `SnapFallbackError` | `onUnavailable: "fallback-local"` is set and Snap could not be reached. | Catch and switch to `LocalProvider` for the rest of the pipeline. |
+| `SnapSkipError` | `onUnavailable: "warn-and-skip"` is set and Snap could not be reached. | Catch and exit cleanly with a skipped summary. |
+
+The wrapper actions (`actions/baseline`, `actions/pr-diff`) catch `SnapSkipError` and `SnapFallbackError` themselves. Custom orchestrations that call `provider.capture()` or `provider.diff()` directly should do the same.
 
 ## Primary entrypoints
 

package/docs/integration-guide.md

@@ -46,13 +46,13 @@ SnapDrift owns route selection, capture, comparison, skipped-report generation,
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift/actions/baseline@v0.2.1
+  uses: ranacseruet/snapdrift/actions/baseline@v0.4.0
   with:
     repo-config-path: .github/snapdrift.json
     artifact-retention-days: '30'
 ```
 
-If you want only part of the route set, pass `route-ids`.
+If you want only part of the route set, pass `route-ids`. If you don't want to upload the artifact (for example when using the Snap provider, which uploads via its own API), set `upload-artifact: 'false'`.
 
 ## Step 3: Run the pull request report
 
@@ -70,7 +70,7 @@ Then add SnapDrift after the app is running:
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
+  uses: ranacseruet/snapdrift/actions/pr-diff@v0.4.0
   with:
     github-token: ${{ secrets.GITHUB_TOKEN }}
     repo-config-path: .github/snapdrift.json
@@ -111,7 +111,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
+        uses: ranacseruet/snapdrift/actions/pr-diff@v0.4.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repo-config-path: .github/snapdrift.json
@@ -150,7 +150,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift/actions/pr-diff@v0.2.1
+        uses: ranacseruet/snapdrift/actions/pr-diff@v0.4.0
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repo-config-path: .github/snapdrift.json
@@ -169,33 +169,89 @@ jobs:
 
 ## Useful overrides
 
-| Input | Purpose |
-|-------|---------|
-| `pr-number` | Explicit PR number override |
-| `route-ids` | Bypass scope detection and capture named routes |
-| `force-run` | Run the full route set |
-| `baseline-repository` | Read baselines from another repo |
-| `baseline-workflow-id` | Override the baseline workflow id |
-| `baseline-branch` | Override the baseline branch |
-| `comment-on-pr` | Set to `false` to suppress the PR report |
-| `max-changed-rows` | Max changed-route rows shown before truncation (default: `20`) |
-| `max-error-rows` | Max error rows shown before truncation (default: `10`) |
+| Input | Default | Purpose |
+|-------|---------|---------|
+| `repo-config-path` | `.github/snapdrift.json` | Override the config file path |
+| `pr-number` | inferred from event | Explicit PR number override |
+| `route-ids` | scope-derived | Bypass scope detection and capture named routes (comma-separated) |
+| `force-run` | `false` | Run the full route set instead of using changed-file scope |
+| `force-run-reason` | `forced` | Reason string emitted to scope outputs when `force-run: true` |
+| `baseline-repository` | current repo | Read baselines from another repo (`owner/name`) |
+| `baseline-workflow-id` | `ci.yml` | Override the baseline workflow id or filename |
+| `baseline-branch` | `main` | Override the branch the baseline was published from |
+| `artifact-retention-days` | `30` | Retention period for the uploaded diff artifact |
+| `comment-on-pr` | `true` | Set to `false` to suppress the PR report upsert |
+| `max-changed-rows` | `20` | Max changed-route rows shown in the PR comment before truncation |
+| `max-error-rows` | `10` | Max error rows shown in the PR comment before truncation |
+
+The `pr-diff` action also exposes outputs you can use in subsequent steps: `should-run`, `scope-reason`, `selected-route-ids`, `baseline-found`, `status`, `summary-path`, `markdown-path`, `artifact-name`, `bundle-dir`. See the wrapper action's `outputs:` block for the canonical list.
+
+## Hosted Snap provider
+
+By default SnapDrift writes baselines and reports to the runner filesystem (`provider: "local"`). For a hosted backend with a shared baseline store and a run-detail dashboard, configure `provider: "snap"` in `snapdrift.json`:
+
+```json
+{
+  "provider": "snap",
+  "snap": {
+    "apiKeyEnv": "SNAP_API_KEY",
+    "projectId": "auto",
+    "onUnavailable": "fail"
+  }
+}
+```
+
+- `apiKeyEnv` — name of an environment variable holding the Snap API key. Mutually exclusive with `apiKey`. Exactly one of `apiKeyEnv` or `apiKey` is required.
+- `apiKey` — inline API key with `${VAR}` interpolation (e.g. `"${SNAP_API_KEY}"`). Mutually exclusive with `apiKeyEnv`.
+- `projectId` — Snap project id, or `"auto"` to derive it from `GITHUB_REPOSITORY` (default).
+- `onUnavailable` — behavior when the Snap API cannot be reached:
+  - `"fail"` (default) — fail the action with a non-retryable error.
+  - `"warn-and-skip"` — log a warning, write a skipped summary, and exit 0.
+  - `"fallback-local"` — log a warning and run the rest of the pipeline with `LocalProvider`.
+
+The Snap API client retries 5xx and network errors with exponential backoff (3 attempts, 1 s → 2 s → 4 s, capped at 30 s). 4xx errors never retry and never fall back.
+
+When `provider: "snap"` and `baseUrl` points to a local address (localhost, `127.0.0.0/8`, `::1`, or `0.0.0.0`), SnapDrift uses a **local-capture hybrid**: Playwright runs on the runner to render the page, then SnapDrift uploads the resulting screenshots to Snap. This makes it possible to point SnapDrift at a server that only the runner can reach (a typical case) without exposing the server to Snap's render worker.
+
+With the Snap provider, the PR comment includes a **"View in dashboard →"** link that points to `${apiUrl}/dashboard/visual/${projectId}/runs/${runId}`. The local provider omits the link.
+
+Migrating an existing local repo to the Snap provider is a one-shot CLI command:
+
+```bash
+snapdrift migrate-baselines --to snap
+```
+
+Conversely, downloading a Snap baseline back to a local directory (useful for reproducible local debugging) is:
+
+```bash
+snapdrift migrate-baselines --to local --from snap
+```
+
+The reverse direction requires the Snap export endpoint to be available; if it isn't, the command fails with an actionable error. See the [Contracts reference](contracts.md#migration-commands) for the full flag set, the engine-compatibility check, and the metadata file written for idempotency.
+
+If you're adopting SnapDrift as a replacement for the upstream `snap/github-action`, the `init` codemod translates the workflow YAML and emits a `MIGRATION_NOTES.md` with everything that couldn't be auto-translated:
+
+```bash
+snapdrift init --from-snap-action .github/workflows/snap.yml
+```
 
 ## Low-level actions
 
-For custom orchestration:
+The `pr-diff` wrapper composes the following low-level steps. They're still available for custom orchestration but most consumers don't need to reach for them:
 
-- `actions/capture`
-- `actions/compare`
-- `actions/scope`
-- `actions/enforce`
-- `actions/comment`
-- `actions/resolve-baseline`
-- `actions/stage`
+- `actions/capture` — capture routes and emit `results.json` + `manifest.json`
+- `actions/compare` — diff current capture against a baseline
+- `actions/scope` — decide whether to run and which routes to select from changed files
+- `actions/resolve-baseline` — find and download the latest successful baseline artifact
+- `actions/stage` — assemble the baseline or diff bundle for upload
+- `actions/enforce` — evaluate the summary against `diff.mode` and fail when required
+- `actions/comment` — upsert a PR comment from a summary (provider-aware)
+
+The two wrapper actions that orchestrate the full pipeline are `actions/baseline` (publish) and `actions/pr-diff` (drift detection). They are the primary integration points.
 
 ## Local development
 
-The `snapdrift` CLI lets you run captures and diffs locally against a running app. Use it to validate UI changes on your machine before pushing — the same capture and comparison engine is used in both contexts.
+The `snapdrift` CLI lets you run captures, diffs, migrations, and config initialization locally against a running app. Use it to validate UI changes on your machine before pushing — the same capture and comparison engine is used in both contexts.
 
 ```bash
 # Establish a baseline before making UI changes
@@ -203,6 +259,12 @@ snapdrift capture
 
 # After making changes, compare and open the HTML report
 snapdrift diff --open
+
+# Migrate an established local baseline to the hosted Snap backend
+snapdrift migrate-baselines --to snap
+
+# Translate a snap/github-action workflow into snapdrift.json
+snapdrift init --from-snap-action .github/workflows/snap.yml
 ```
 
 The CLI reads the same `.github/snapdrift.json` config used by the Actions workflow. Local outputs land in `.snapdrift/` by default and can be overridden with `--baseline-dir`, `--current-dir`, and `--diff-dir`.
@@ -226,13 +288,19 @@ If you don't want to republish the baseline on every push, the template includes
 ## Troubleshooting
 
 **"No non-expired SnapDrift baseline artifact was found"**  
-The baseline workflow has not completed successfully on `main`, or the artifact expired.
+The baseline workflow has not completed successfully on `main`, or the artifact expired. With the Snap provider, the equivalent situation is a 404 from `/v1/visual/projects/:id/baselines/latest`; `SnapProvider` swallows that 404 and proceeds without a baseline — `onUnavailable` is **not** consulted for this case (a 404 is the legitimate "no baseline yet" signal, not a Snap outage). If you want the PR pipeline to tolerate the first-run case, set `diff.mode: "report-only"`; `onUnavailable: "warn-and-skip"` will not help here.
 
 **403 when posting the PR report**  
 Grant `issues: write` and `pull-requests: write` to the job.
 
+**Snap API request keeps failing with 4xx**  
+The Snap client never retries 4xx and never falls back, even when `onUnavailable` is set. Inspect the response body — the most common cause is a project-id mismatch between `GITHUB_REPOSITORY` (auto-derived) and the project's id on Snap.
+
 **Screenshots have different dimensions**  
 SnapDrift reports this as a dimension shift and skips pixel comparison for that route. Refresh the baseline after the change lands.
 
 **A route appears in `errors[]`**  
 Capture failed before comparison. Confirm the app is fully ready and reachable before SnapDrift runs.
+
+**Playwright install runs even though `provider: "snap"`**  
+That's expected for the Snap local-capture hybrid. Playwright runs locally to render the page, then the resulting screenshot is uploaded to Snap. The hybrid kicks in only when `baseUrl` points to a local address; for remote `baseUrl` Snap's render worker captures directly.

package/docs/local-cli.md

@@ -80,6 +80,75 @@ snapdrift diff --baseline-dir snapshots/baseline --diff-dir snapshots/diff
 
 ---
 
+### `snapdrift migrate-baselines`
+
+Move baselines between the local filesystem and the hosted Snap backend. Requires a config with `provider: "snap"` (or a `snap` block) for the direction being targeted.
+
+**Upload local baselines to Snap:**
+
+```bash
+snapdrift migrate-baselines --to snap
+```
+
+Reads `results.json`, `manifest.json`, and `screenshots/*.png` from the local baseline directory, then POSTs them to Snap as the initial accepted baseline for the current commit. Idempotent: if a baseline already exists for the same commit SHA the upload is skipped.
+
+**Download Snap baselines to a local directory:**
+
+```bash
+snapdrift migrate-baselines --to local --from snap
+```
+
+Snap must expose its export endpoint for this direction to succeed. If it doesn't, the command fails with an actionable error. By default the engine name on the exported manifest must be `snapdrift-local`; pass `--accept-cross-engine` to override the engine name in the imported manifest (visual differences may occur).
+
+**Options**
+
+| Flag | Default | Description |
+|:-----|:--------|:------------|
+| `--to <snap\|local>` | — | Migration target (required) |
+| `--from <snap>` | — | Migration source (required when `--to local`) |
+| `--accept-cross-engine` | off | Override the engine-name check when importing from Snap |
+| `--config <path>` | `.github/snapdrift.json` | Path to the config file |
+| `--baseline-dir <path>` | `.snapdrift/baseline` | Local baseline directory to read from or write to |
+
+**Side effects**
+
+A `.migration-metadata.json` file is written next to the local baseline after a successful download — it records the source engine, the migration timestamp, and a stable id used for idempotency on re-runs.
+
+---
+
+### `snapdrift init`
+
+Translate an existing `snap/github-action` workflow into `snapdrift.json` with `provider: "snap"`. Use this when migrating an existing consumer repo from the upstream Snap action to SnapDrift.
+
+```
+snapdrift init --from-snap-action <workflow-yaml-path>
+```
+
+Reads the workflow YAML, locates the step that uses the Snap action, and translates its inputs:
+
+| Snap action input | snapdrift config |
+|:------------------|:-----------------|
+| `threshold` / `diff-threshold` | `diff.threshold` |
+| `fail-on-changes` | `diff.mode` (`"fail-on-changes"`) |
+| `fail-on-incomplete` | `diff.mode` (`"fail-on-incomplete"`) |
+| (none of the above) | `diff.mode` (`"report-only"`) |
+| `snap-api-key-env` | `snap.apiKeyEnv` |
+| `snap-api-url` | `snap.apiUrl` |
+| `snap-project-id` | `snap.projectId` |
+| `format` | (warning — PNG-only, format dropped) |
+| `baseline_tag` | (warning — commit-based only) |
+| `routes` / page list | (warning — fill in `routes[]` manually) |
+| `baseUrl` | placeholder `http://localhost:3000` (warning — update to your real app) |
+
+The codemod writes two files:
+
+- `.github/snapdrift.json` — the translated config
+- `.github/MIGRATION_NOTES.md` — every warning and deferred decision, grouped by severity
+
+The command is **idempotent against `snapdrift.json`**: if the file already exists, the command refuses to overwrite and tells you to remove it manually.
+
+---
+
 ## Typical local workflow
 
 ```bash
@@ -131,8 +200,8 @@ Add `.snapdrift/` to your `.gitignore` to keep local run output out of version c
 
 | Code | Meaning |
 |:-----|:--------|
-| `0` | Clean — no drift above threshold, or `diff.mode` is `report-only` |
-| `1` | Drift enforced — `diff.mode` caused the run to fail (see [Drift modes](../README.md#drift-modes)) |
+| `0` | Clean — no drift above threshold, `diff.mode` is `report-only`, the diff was intentionally skipped (e.g. `SnapSkipError` from `onUnavailable: "warn-and-skip"`), or the command was a `capture` / `migrate-baselines` / `init` that completed |
+| `1` | Drift enforced — `diff.mode` caused the run to fail, a required command argument was missing, or the `--to local` engine-name check failed (see [Drift modes](../README.md#drift-modes)) |
 
 Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. Set `"mode": "report-only"` during local development to always get a report without a failing exit code.
 
@@ -140,7 +209,9 @@ Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. S
 
 ## Console output
 
-`snapdrift diff` prints a summary to stdout:
+`snapdrift diff` prints a summary to stdout.
+
+**Clean run:**
 
 ```
 Capturing current screenshots to .snapdrift/current ...
@@ -151,7 +222,7 @@ Comparing against baseline ...
    Matched:  2
 ```
 
-When drift is detected:
+**Drift detected** (one or more routes changed):
 
 ```
 🟡  SnapDrift — Drift detected
@@ -165,6 +236,36 @@ When drift is detected:
 Report: .snapdrift/diff/report.html
 ```
 
+**Incomplete run** (errors, missing captures, or dimension shifts):
+
+```
+❌  SnapDrift — incomplete
+   Routes:   4
+   Matched:   2
+   Changed:   0
+   Missing:   1
+   Errors:    1
+   Dim diff:  1
+
+Report: .snapdrift/diff/report.html
+```
+
+The `Missing`, `Errors`, and `Dim diff` lines only print when their count is greater than zero. `summary.status` is the unstyled value from the run (`clean`, `changes-detected`, `incomplete`, or `skipped`).
+
+The `report.html` path is printed whenever the status is anything other than `clean`; pass `--open` to also launch it in your default browser.
+
+---
+
+## Environment variables
+
+| Variable | Applies to | Description |
+|:---------|:-----------|:------------|
+| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture`, `diff` | Max concurrent route captures per viewport context (positive integer, default `5`). Set to `1` to restore serial behavior for apps with shared session or auth state. |
+| `SNAPDRIFT_CONFIG_PATH` | `capture`, `diff`, `migrate-baselines` | Override the config file path. Equivalent to `--config`. |
+| `SNAPDRIFT_ROUTE_IDS` | `capture`, `diff` | Comma-separated route ids to scope to. Equivalent to `--routes`. |
+
+`SNAPDRIFT_CAPTURE_CONCURRENCY` is the same env var consumed by the GitHub Actions wrapper; tweak it the same way for both environments.
+
 ---
 
 ## Tips
@@ -172,3 +273,5 @@ Report: .snapdrift/diff/report.html
 - **Partial runs**: use `--routes` to capture or compare only the routes you are actively changing.
 - **Multiple baselines**: use `--baseline-dir` to maintain separate baselines per branch or feature.
 - **CI parity**: the CLI uses the same capture and comparison engine as the GitHub Actions workflow, so results are comparable.
+- **Self-contained HTML report**: `report.html` embeds baseline, current, and diff images as base64. Open it from any machine — no server required, and no relative-path resolution surprises. (The HTML report is a local-CLI feature; the GitHub Actions wrapper ships only `summary.json` + `summary.md` in its artifact bundle.)
+- **Provider-aware behavior**: with `provider: "snap"`, the `capture` and `diff` commands will hit the Snap API. The `--open` flag still opens the locally generated `report.html`; the Snap dashboard link lives in the PR comment, not the local output.

package/docs/workflow-templates/refresh-baseline-on-merge.yml

@@ -70,7 +70,7 @@ jobs:
       # ────────────────────────────────────────────────────────────────────────
 
       - name: Publish SnapDrift baseline
-        uses: ranacseruet/snapdrift/actions/baseline@v0.2.1
+        uses: ranacseruet/snapdrift/actions/baseline@v0.4.0
         with:
           repo-config-path: .github/snapdrift.json
           artifact-retention-days: '30'

package/lib/cli.mjs

@@ -185,7 +185,8 @@ export async function runCaptureCommand(opts) {
     const { selectedRouteIds } = await provider.capture({
       configPath: opts.configPath,
       routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-      outDir: opts.baselineDir
+      outDir: opts.baselineDir,
+      purpose: 'baseline'
     });
     process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
   } catch (error) {

package/lib/init-from-action.mjs

@@ -2,7 +2,7 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 /** @typedef {import('../types/visual-diff-types').InitWarning} InitWarning */
 

package/lib/provider.mjs

@@ -2,7 +2,7 @@
 
 import { runBaselineCapture, generateDriftReport, stageArtifacts } from '@snapdrift/adapter-fs';
 import { buildReportCommentBody } from '@snapdrift/adapter-report-md';
-import { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError } from './snap-provider.mjs';
+import { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError, isLocalBaseUrl } from './snap-provider.mjs';
 
 /** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
 /** @typedef {import('../types/visual-diff-types').ProviderCaptureOptions} CaptureOptions */
@@ -103,4 +103,4 @@ export function createProvider(providerName, config) {
   return factory(config);
 }
 
-export { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError };
+export { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError, isLocalBaseUrl };