snapdrift 0.8.1 → 0.8.2

package/docs/contracts.md

@@ -210,6 +210,12 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 | `fail-on-incomplete` | Errors, dimension shifts, or missing captures occur |
 | `strict` | Any drift or incomplete comparison appears |
 
+A summary with `status: "skipped"` — or any summary carrying no `diff.mode` —
+never stops the run, whichever mode is configured. A skipped run has no diff
+counters to enforce against, so `shouldFailDriftCheck` returns `false` for it
+before any mode branch is reached. This holds for `actions/enforce` invoked
+directly, not just for the guarded enforcement step inside `actions/pr-diff`.
+
 ## Viewport presets
 
 | Preset | Width | Height | Scale factor | Mobile | Touch |
@@ -316,6 +322,14 @@ Two files are written: `.github/snapdrift.json` and `.github/MIGRATION_NOTES.md`
 
 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.
 
+### Complete hosted baseline publication
+
+A hosted baseline is an authoritative complete snapshot. For `purpose: "baseline"`, `SnapProvider.capture()` requires the selected route ids to equal the complete configured route set; `route-ids`, `--routes`, and `SNAPDRIFT_ROUTE_IDS` may not reduce it. It requires a resolved branch, 40-character commit SHA, publication workflow ref, and positive publication sequence. GitHub Actions provides these as `GITHUB_REF_NAME`, `GITHUB_SHA`, `GITHUB_WORKFLOW_REF`, and `GITHUB_RUN_NUMBER`; other CI systems may set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`. Local-provider baselines, non-publishing hosted captures, and hosted PR-diff runs retain scoped behavior.
+
+The capture `results.json` records `configuredRouteIds`, `selectedRouteIds`, and `expectedCaptures` (route id, path, and viewport descriptor), plus one resolved `refBranch` / `refSha`, publication workflow ref, and publication sequence. The run-creation request sends the same immutable set and sequence as `capturePlan` and sends the ref as `branch` / `prHeadSha`. Before publication, SnapDrift requires the source run to belong to the configured project, settle to terminal `new`, and contain exactly one successful `new` capture with a non-empty `currentObjectKey` for every expected route/viewport identity. It keeps polling while any expected capture remains non-terminal, even when an older server reports the run itself as terminal, but fails fast after a stable incomplete capture set. Failed, missing, duplicate, extra, path-mismatched, or malformed captures abort before the baseline request. If another default-branch baseline wins first, Snap returns `409 baseline_stale_source`; rerun the current baseline job.
+
+Publication sends `publicationMode: "complete"` and the source run id both as top-level `sourceRunId` and as `manifest.sourceRunId`. The baseline id is deterministically derived from the run id, and manifest routes are sorted, so a retry sends the same identity and payload. Reusing that id with different persisted fields is rejected; rerun the baseline job to obtain a new source run. `refBranch` / `refSha` come from the persisted capture metadata rather than resolving git a second time. Snap accepts complete publication only from the project's default branch (effective default `main`).
+
 ### 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.
@@ -328,10 +342,10 @@ 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/projects/:id/runs` | Create a run; client passes `baseUrl`, `trigger`, optional `baselineId` and `branch`, plus the immutable configured/selected route and expected-capture plan; baseline runs also pass the resolved commit as `prHeadSha` |
 | `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) |
+| `POST /v1/visual/projects/:id/baselines` | Publish a complete default-branch baseline from a source run's validated captures |
 | `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`) |
 
@@ -352,6 +366,25 @@ The Snap HTTP client classifies responses and applies the following rules:
 - `"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`.
 
+### Outage policy
+
+Snap can go down at any phase of a run, and the configured `onUnavailable`
+behavior has to hold for all of them. `lib/outage-policy.mjs` is the single
+implementation, used by `lib/cli.mjs`, `actions/baseline` and `actions/pr-diff`
+alike:
+
+| Phase | `warn-and-skip` | `fallback-local` |
+|:------|:----------------|:-----------------|
+| Capture | Write a skipped `summary.json`/`summary.md` with reason `snap_unavailable`, expose the summary outputs, stage the report, exit 0. | Capture with `LocalProvider` and report the **effective** provider (`local`) so the rest of the pipeline uses local artifacts and the local pixel engine. |
+| Diff | Same skipped summary, exit 0. | Diff with `LocalProvider`. A capture that Snap rendered server-side has no PNGs on the runner, so the routes are **recaptured locally first**; the recaptured paths replace the Snap ones in the staged bundle. If no baseline artifact was resolved, the run reports `missing_main_baseline_artifact` instead of crashing the local diff. |
+| Baseline publish | Skip the publish and exit 0 without an artifact. | Capture locally and stage/upload that bundle, so the run still leaves a usable baseline. |
+
+Enforcement of `diff.mode` never runs against a skipped summary — a skipped run
+carries no diff counters, and `warn-and-skip` means "do not fail my build".
+
+A `fallback-local` capture leaves nothing on Snap: no run is published and no
+baseline is created. The fallback is a local run, not a deferred hosted one.
+
 ### `isLocalBaseUrl` detection
 
 `isLocalBaseUrl(baseUrl)` returns `true` when the URL hostname is:
@@ -374,7 +407,7 @@ All four error classes are exported from `lib/provider.mjs` and `lib/snap-provid
 | `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.
+The wrapper actions (`actions/baseline`, `actions/pr-diff`) and the CLI both handle `SnapSkipError` and `SnapFallbackError` through `lib/outage-policy.mjs` (`captureWithPolicy`, `diffWithPolicy`, `publishBaselineWithPolicy`). Custom orchestrations that call `provider.capture()`, `provider.diff()` or `provider.publishBaseline()` directly should use those helpers rather than re-implementing the matrix.
 
 ## Primary entrypoints
 

package/docs/integration-guide.md

@@ -46,14 +46,14 @@ SnapDrift owns route selection, capture, comparison, skipped-report generation,
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift@v0.8.1
+  uses: ranacseruet/snapdrift@v0.8.2
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
     artifact-retention-days: '30'
 ```
 
-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'`.
+For a local-provider baseline, `route-ids` may select part of the route set. A hosted Snap baseline is authoritative and must run in GitHub Actions on the project default branch with every configured route, so a partial `route-ids` value or unresolved CI commit fails before a run is created. Route scoping remains supported in `pr-diff` mode. 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
 
@@ -71,7 +71,7 @@ Then add SnapDrift after the app is running:
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.8.1
+  uses: ranacseruet/snapdrift@v0.8.2
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -86,8 +86,8 @@ The wrappers remain published in their own right, and are equivalent to the disp
 
 | Entry point | Equivalent to |
 |-------------|---------------|
-| `ranacseruet/snapdrift@v0.8.1` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.8.1` |
-| `ranacseruet/snapdrift@v0.8.1` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.8.1` |
+| `ranacseruet/snapdrift@v0.8.2` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.8.2` |
+| `ranacseruet/snapdrift@v0.8.2` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.8.2` |
 
 Use the wrappers directly when you want to skip the dispatcher's input indirection, and the lower-level `capture`, `compare`, `scope`, `resolve-baseline`, `stage`, `comment`, and `enforce` actions when you need to orchestrate the stages yourself.
 
@@ -130,7 +130,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.8.1
+        uses: ranacseruet/snapdrift@v0.8.2
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -170,7 +170,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.8.1
+        uses: ranacseruet/snapdrift@v0.8.2
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -230,6 +230,10 @@ By default SnapDrift writes baselines and reports to the runner filesystem (`pro
   - `"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`.
 
+Both behaviors apply at every phase of a run — capture, diff, and baseline publish. `fallback-local` switches the whole remainder of the pipeline to local artifacts and the local pixel engine; if Snap had already rendered the current capture server-side, the routes are recaptured on the runner first, so `actions/pr-diff` needs Playwright available (the wrapper installs it whenever `onUnavailable` is `fallback-local`). Nothing is published to Snap on a fallback run. See [Outage policy](contracts.md#outage-policy) for the full matrix.
+
+Hosted baseline publication is complete and default-branch-only. SnapDrift rejects scoped baseline capture before creating the run, records the configured/selected route ids and exact route/viewport identities, and publishes only when every expected capture finishes successfully with a stored image. The run records one resolved branch and commit (`branch` / `prHeadSha`) plus a publication workflow ref and monotonic sequence. GitHub Actions provides these automatically; other CI systems may set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`. Snap uses the sequence for same-workflow ordering and source-run timestamps for cross-workflow freshness. Missing, failed, duplicate, or unexpected captures abort publication without replacing the accepted baseline. If a source run loses the race to a newer candidate, the API returns `409 baseline_stale_source`; an inconsistent manifest/source workflow identity returns `409 baseline_source_run_mismatch` with `details.reason = "workflow_mismatch"`. Workflow-ref rotation itself is supported. This restriction does not apply to non-publishing hosted captures, hosted PR-diff runs, or local-provider baselines.
+
 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.
@@ -302,9 +306,7 @@ Use the provided workflow template to refresh the baseline automatically on ever
 
 Drop a copy into your repo at `.github/workflows/snapdrift-refresh-baseline.yml`, then fill in the `TODO` blocks with your app's build and start steps — the same steps you use in your PR workflow. The template uses a `push` trigger on the default branch so published artifacts are discoverable by the baseline resolver in `actions/pr-diff`.
 
-### Label-gated refreshes
-
-If you don't want to republish the baseline on every push, the template includes a commented `if` condition that gates on a label (e.g. `snapdrift:refresh-baseline`). A preceding job can check the most recent merged PR for the label and set an output to control whether the baseline refresh runs.
+Run this job after every successful default-branch build. Hosted publication is the only operation that may intentionally remove a configured route from the canonical baseline, so skipping merges can leave later PRs comparing against stale route configuration.
 
 ## Troubleshooting
 

package/docs/local-cli.md

@@ -31,11 +31,11 @@ snapdrift baseline [options]
 ```
 
 - **`provider: "local"`** — identical to `snapdrift capture`: the screenshots written to the baseline directory *are* the baseline.
-- **`provider: "snap"`** — captures each route through Snap, waits for the hosted renders to finish, then publishes a baseline referencing the stored objects. `snapdrift capture` alone does **not** do this: it submits the run and stops, leaving the project with no baseline.
+- **`provider: "snap"`** — canonical baseline publication is CI-only. Run it on the Snap project's default branch; GitHub Actions supplies the publication metadata automatically, while another CI system may set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`. It captures every configured route, waits for the complete hosted run, then publishes a baseline referencing the stored objects. A local checkout without those metadata values fails before creating a hosted run, and partial `--routes` selection is rejected. `snapdrift capture` may still be used locally for non-publishing diagnostics.
 
 `snap.onUnavailable` is honoured across both phases — the capture *and* the publish that follows it. `warn-and-skip` exits 0 without a baseline; `fallback-local` captures locally so you still end up with one.
 
-**Baseline attribution.** The published baseline records the branch and commit it was cut from. Inside GitHub Actions these come from `GITHUB_REF_NAME` / `GITHUB_HEAD_REF` and `GITHUB_SHA`; run locally, they are read from git (`rev-parse --abbrev-ref HEAD` and `rev-parse HEAD`). Outside a git repository they fall back to `main` and `unknown`, so run the command from your checkout if you want the baseline attributed correctly.
+**Baseline attribution.** A hosted publication records a 40-character commit and branch from GitHub Actions or the current git checkout, plus a publication workflow identity and sequence. Outside GitHub Actions, set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`; without them SnapDrift refuses to create a canonical hosted baseline.
 
 **`snap.projectId` must be an explicit `prj_...` id** for local runs. `"auto"` derives the id from `GITHUB_REPOSITORY`, which is not set outside Actions — the command fails early telling you to set an explicit id.
 
@@ -44,13 +44,14 @@ snapdrift baseline [options]
 | Flag | Default | Description |
 |:-----|:--------|:------------|
 | `--config <path>` | `.github/snapdrift.json` | Path to the config file |
-| `--routes <ids>` | all routes | Comma-separated route IDs to capture |
+| `--routes <ids>` | all routes | Comma-separated route IDs for a local-provider baseline; hosted baselines require all configured routes |
 | `--baseline-dir <path>` | `.snapdrift/baseline` | Directory to write baseline screenshots and metadata (local provider) |
 
 **Example**
 
 ```bash
 snapdrift baseline
+# Scoped baseline capture remains available with provider: "local"
 snapdrift baseline --routes home-desktop,home-mobile
 ```
 
@@ -296,7 +297,7 @@ The `report.html` path is printed whenever the status is anything other than `cl
 |:---------|:-----------|:------------|
 | `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_ROUTE_IDS` | `capture`, `baseline`, `diff` | Comma-separated route ids to scope to. Equivalent to `--routes`; it may not reduce a hosted baseline's complete route set. |
 
 `SNAPDRIFT_CAPTURE_CONCURRENCY` is the same env var consumed by the GitHub Actions wrapper; tweak it the same way for both environments.
 
@@ -304,7 +305,7 @@ The `report.html` path is printed whenever the status is anything other than `cl
 
 ## Tips
 
-- **Partial runs**: use `--routes` to capture or compare only the routes you are actively changing.
+- **Partial runs**: use `--routes` to capture or compare only the routes you are actively changing. A hosted baseline is the exception: its GitHub Actions run always requires the complete configured route set.
 - **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.)

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

@@ -17,12 +17,6 @@
 # resolver in actions/pr-diff (which filters on event: 'push'). A merge into
 # the default branch produces a push event, so this fires exactly when needed.
 #
-# Optional — refresh only on a specific label:
-#   If you don't want to refresh on every push, you can gate on a label applied
-#   before merging. Use the pull_request: labeled event in a separate workflow to
-#   set an output, or simply restrict this workflow to specific paths.
-#   See the commented block below for a label-based gate using a preceding job.
-
 name: SnapDrift Refresh Baseline
 
 on:
@@ -35,12 +29,12 @@ permissions:
 
 jobs:
   refresh-baseline:
-    # Optional: gate on a label to avoid refreshing on every push.
-    # Requires a preceding job that checks for the label on the most recent
-    # merged PR and sets an output. Replace "snapdrift:refresh-baseline" with
-    # your label name.
-    # if: needs.check-label.outputs.refresh == 'true'
-
+    # Preserve the in-flight publisher and queue the next merge behind it. This
+    # keeps older SnapDrift clients safe during a rolling release; SnapDrift's
+    # workflow-scoped sequence is an additional stale-source guard.
+    concurrency:
+      group: snapdrift-baseline-${{ github.repository }}-${{ github.ref }}
+      cancel-in-progress: false
     runs-on: ubuntu-latest
 
     steps:
@@ -69,8 +63,26 @@ jobs:
       #     done
       # ────────────────────────────────────────────────────────────────────────
 
+      - name: Verify current default-branch candidate
+        id: baseline_candidate
+        shell: bash
+        run: |
+          set -euo pipefail
+          latest_sha="$(git ls-remote origin "refs/heads/${GITHUB_REF_NAME}" | cut -f1)"
+          if [ -z "$latest_sha" ]; then
+            echo "::error::Could not resolve the current default-branch commit."
+            exit 1
+          fi
+          if [ "$GITHUB_SHA" = "$latest_sha" ]; then
+            echo "current=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "current=false" >> "$GITHUB_OUTPUT"
+            echo "Skipping stale baseline candidate $GITHUB_SHA; current branch head is $latest_sha."
+          fi
+
       - name: Publish SnapDrift baseline
-        uses: ranacseruet/snapdrift@v0.8.1
+        if: steps.baseline_candidate.outputs.current == 'true'
+        uses: ranacseruet/snapdrift@v0.8.2
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json

package/lib/cli.mjs

@@ -7,7 +7,7 @@ import path from 'node:path';
 import { loadSnapdriftConfig } from '@snapdrift/adapter-fs';
 import { shouldFailDriftCheck } from '@snapdrift/manifest';
 import { createProvider } from './provider.mjs';
-import { SnapFallbackError, SnapSkipError } from './snap-provider.mjs';
+import { captureWithPolicy, diffWithPolicy, publishBaselineWithPolicy } from './outage-policy.mjs';
 import { generateHtmlReport } from './report.mjs';
 
 /** @typedef {import('../types/visual-diff-types').VisualDiffSummary} DriftSummary */
@@ -39,7 +39,8 @@ export const LOCAL_DIFF_SUBDIR = 'diff';
  * Supported flags:
  *   --open              Open the HTML report after diff
  *   --config <path>     Path to snapdrift.json (default: .github/snapdrift.json)
- *   --routes <ids>      Comma-separated route IDs to run
+ *   --routes <ids>      Comma-separated route IDs (diff/capture/local baseline;
+ *                       hosted baselines require the complete configured set)
  *   --baseline-dir <p>  Override local baseline directory (default: .snapdrift/baseline)
  *   --current-dir <p>   Override local current-capture directory (default: .snapdrift/current)
  *   --diff-dir <p>      Override local diff-output directory (default: .snapdrift/diff)
@@ -180,36 +181,33 @@ function openFile(filePath) {
 export async function runCaptureCommand(opts) {
   process.stdout.write(`Capturing baseline to ${opts.baselineDir} ...\n`);
   const { config } = await loadSnapdriftConfig(opts.configPath);
-  const provider = createProvider(config.provider ?? 'local', config);
-  try {
-    const { selectedRouteIds } = await provider.capture({
+  const providerName = config.provider ?? 'local';
+  const provider = createProvider(providerName, config);
+
+  // onUnavailable: warn-and-skip — the user asked not to fail the build when
+  // Snap is down. `diff` and `baseline` both honour this; `capture` used to
+  // let SnapSkipError reach bin/snapdrift.mjs, which exits 1. See #108.
+  const captured = await captureWithPolicy({
+    provider,
+    providerName,
+    config,
+    captureOptions: {
       configPath: opts.configPath,
       routeIds: opts.routes.length > 0 ? opts.routes : undefined,
       outDir: opts.baselineDir,
-      purpose: 'baseline'
-    });
-    process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
-  } catch (error) {
-    // onUnavailable: warn-and-skip — the user asked not to fail the build when
-    // Snap is down. `diff` and `baseline` both honour this; `capture` used to
-    // let SnapSkipError reach bin/snapdrift.mjs, which exits 1. See #108.
-    if (error instanceof SnapSkipError) {
-      process.stdout.write('Capture skipped (Snap unavailable, warn-and-skip mode).\n');
-      return;
-    }
-    if (error instanceof SnapFallbackError) {
-      process.stdout.write('Falling back to local provider for capture...\n');
-      const localProvider = createProvider('local');
-      const { selectedRouteIds } = await localProvider.capture({
-        configPath: opts.configPath,
-        routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-        outDir: opts.baselineDir
-      });
-      process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
-      return;
-    }
-    throw error;
+      purpose: 'capture'
+    },
+    onSkip: () => process.stdout.write('Capture skipped (Snap unavailable, warn-and-skip mode).\n'),
+    onFallback: () => process.stdout.write('Falling back to local provider for capture...\n')
+  });
+
+  if (captured.outcome === 'skipped') {
+    return;
   }
+
+  process.stdout.write(
+    `Captured ${captured.result.selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`
+  );
 }
 
 /**
@@ -240,79 +238,65 @@ export async function runBaselineCommand(opts) {
       : `Capturing baseline to ${opts.baselineDir} ...\n`
   );
 
-  /** Capture locally so `fallback-local` still leaves the user with a baseline. */
-  async function captureLocalFallback() {
-    process.stdout.write('Falling back to local provider for capture...\n');
-    const localProvider = createProvider('local');
-    const { selectedRouteIds } = await localProvider.capture({
-      configPath: opts.configPath,
-      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-      outDir: opts.baselineDir
-    });
+  /** @type {import('../types/visual-diff-types').ProviderCaptureOptions} */
+  const captureOptions = {
+    configPath: opts.configPath,
+    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+    outDir: opts.baselineDir,
+    purpose: 'baseline'
+  };
+
+  const onFallback = () => process.stdout.write('Falling back to local provider for capture...\n');
+
+  // Snap can go down during *either* phase — the capture submission or the
+  // publish that follows it — and the user's `onUnavailable` choice must hold
+  // for both, otherwise `warn-and-skip` still exits 1 and `fallback-local`
+  // still leaves them with no baseline.
+  const captured = await captureWithPolicy({
+    provider,
+    providerName,
+    config,
+    captureOptions,
+    onSkip: () => process.stdout.write('Baseline skipped (Snap unavailable, warn-and-skip mode).\n'),
+    onFallback
+  });
+
+  if (captured.outcome === 'skipped') {
+    return;
+  }
+
+  if (captured.providerName !== 'snap') {
+    const suffix = providerName === 'snap' ? ' (local fallback — nothing published to Snap)' : '';
     process.stdout.write(
-      `Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir} (local fallback — nothing published to Snap)\n`
+      `Captured ${captured.result.selectedRouteIds.length} route(s) to ${opts.baselineDir}${suffix}\n`
     );
+    return;
   }
 
-  /**
-   * Apply the configured `onUnavailable` behaviour. Snap can go down during
-   * *either* phase — the capture submission or the publish that follows it — and
-   * the user's choice must hold for both, otherwise `warn-and-skip` still exits 1
-   * and `fallback-local` still leaves them with no baseline.
-   *
-   * @param {unknown} error
-   * @param {string} skipMessage
-   * @returns {Promise<boolean>} true when the error was absorbed
-   */
-  async function handleUnavailable(error, skipMessage) {
-    if (error instanceof SnapSkipError) {
-      process.stdout.write(skipMessage);
-      return true;
-    }
-    if (error instanceof SnapFallbackError) {
-      await captureLocalFallback();
-      return true;
-    }
-    return false;
-  }
+  process.stdout.write(
+    `Captured ${captured.result.selectedRouteIds.length} route(s); waiting for Snap to finish rendering ...\n`
+  );
 
-  /** @type {{ resultsPath?: string, selectedRouteIds: string[] }} */
-  let captured;
-  try {
-    captured = await provider.capture({
-      configPath: opts.configPath,
-      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-      outDir: opts.baselineDir,
-      purpose: 'baseline'
-    });
-  } catch (error) {
-    if (await handleUnavailable(error, 'Baseline skipped (Snap unavailable, warn-and-skip mode).\n')) {
-      return;
-    }
-    throw error;
-  }
+  const published = await publishBaselineWithPolicy({
+    provider,
+    publishOptions: { resultsPath: captured.result.resultsPath },
+    captureOptions,
+    onSkip: () =>
+      process.stdout.write('Baseline publish skipped (Snap unavailable, warn-and-skip mode).\n'),
+    onFallback
+  });
 
-  if (providerName !== 'snap') {
-    process.stdout.write(`Captured ${captured.selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
+  if (published.outcome === 'skipped') {
     return;
   }
 
-  process.stdout.write(
-    `Captured ${captured.selectedRouteIds.length} route(s); waiting for Snap to finish rendering ...\n`
-  );
-  try {
-    await provider.publishBaseline({ resultsPath: captured.resultsPath });
-  } catch (error) {
-    if (
-      await handleUnavailable(
-        error,
-        'Baseline publish skipped (Snap unavailable, warn-and-skip mode).\n'
-      )
-    ) {
-      return;
-    }
-    throw error;
+  if (published.outcome === 'fell-back') {
+    process.stdout.write(
+      `Captured ${published.recapture?.selectedRouteIds.length ?? 0} route(s) to ${opts.baselineDir} (local fallback — nothing published to Snap)\n`
+    );
+    return;
   }
+
   process.stdout.write('Snap baseline published successfully.\n');
 }
 
@@ -326,31 +310,32 @@ export async function runBaselineCommand(opts) {
 export async function runDiffCommand(opts) {
   process.stdout.write(`Capturing current screenshots to ${opts.currentDir} ...\n`);
   const { config } = await loadSnapdriftConfig(opts.configPath);
-  const provider = createProvider(config.provider ?? 'local', config);
+  const providerName = config.provider ?? 'local';
+  const provider = createProvider(providerName, config);
 
-  let currentCapture;
-  let usedLocalFallback = false;
-  try {
-    currentCapture = await provider.capture({
-      configPath: opts.configPath,
-      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-      outDir: opts.currentDir
-    });
-  } catch (error) {
-    if (error instanceof SnapFallbackError) {
-      process.stdout.write('Falling back to local provider for capture...\n');
-      const localProvider = createProvider('local');
-      currentCapture = await localProvider.capture({
-        configPath: opts.configPath,
-        routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-        outDir: opts.currentDir
-      });
-      usedLocalFallback = true;
-    } else {
-      throw error;
-    }
+  /** @type {import('../types/visual-diff-types').ProviderCaptureOptions} */
+  const captureOptions = {
+    configPath: opts.configPath,
+    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+    outDir: opts.currentDir
+  };
+
+  const captured = await captureWithPolicy({
+    provider,
+    providerName,
+    config,
+    captureOptions,
+    onSkip: () =>
+      process.stdout.write('Visual regression skipped (Snap unavailable, warn-and-skip mode).\n'),
+    onFallback: () => process.stdout.write('Falling back to local provider for capture...\n')
+  });
+
+  if (captured.outcome === 'skipped') {
+    return;
   }
 
+  const currentCapture = captured.result;
+
   process.stdout.write('Comparing against baseline ...\n');
 
   const baselineResultsPath = path.join(opts.baselineDir, path.basename(config.resultsFile));
@@ -361,10 +346,12 @@ export async function runDiffCommand(opts) {
   const markdownPath = path.join(opts.diffDir, 'summary.md');
   const htmlPath = path.join(opts.diffDir, 'report.html');
 
-  const diffProvider = usedLocalFallback ? createProvider('local') : provider;
-  let diffResult;
-  try {
-    diffResult = await diffProvider.diff({
+  const diffed = await diffWithPolicy({
+    provider: captured.providerName === 'local' ? createProvider('local') : provider,
+    providerName: captured.providerName,
+    localScreenshots: captured.localScreenshots,
+    captureOptions,
+    diffOptions: {
       configPath: opts.configPath,
       routeIds: opts.routes.length > 0 ? opts.routes : undefined,
       baselineResultsPath,
@@ -373,20 +360,24 @@ export async function runDiffCommand(opts) {
       currentManifestPath: currentCapture.manifestPath,
       baselineRunDir: opts.baselineDir,
       currentRunDir: currentCapture.screenshotsRoot
-    });
-  } catch (error) {
-    if (error instanceof SnapSkipError) {
-      process.stdout.write('Visual regression skipped (Snap unavailable, warn-and-skip mode).\n');
-      return;
-    }
-    throw error;
+    },
+    onSkip: () =>
+      process.stdout.write('Visual regression skipped (Snap unavailable, warn-and-skip mode).\n'),
+    onFallback: () => process.stdout.write('Falling back to local provider for the diff...\n'),
+    onRecapture: () =>
+      process.stdout.write('Recapturing locally so the local diff has screenshots to compare...\n')
+  });
+
+  if (diffed.outcome !== 'diffed') {
+    return;
   }
 
-  const { summary, markdown } = diffResult;
+  const { summary, markdown } = diffed.result;
+  const currentRunDir = diffed.recapture?.screenshotsRoot ?? currentCapture.screenshotsRoot;
 
   const html = await generateHtmlReport(summary, {
     baselineRunDir: opts.baselineDir,
-    currentRunDir: currentCapture.screenshotsRoot
+    currentRunDir
   });
 
   await Promise.all([
@@ -485,4 +476,4 @@ export async function main(argv) {
     );
     process.exitCode = 1;
   }
-}
+}