snapdrift 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.8.2 - 2026-08-24
+
+### Fixes
+
+- **Hosted baseline publication is now complete and fail-closed** — a scoped `route-ids` / `--routes` baseline run could publish only the changed routes and replace a larger accepted baseline, causing every omitted route to appear missing on the next PR (i2Dev-com/snap#720). `provider: "snap"` baseline capture now requires every configured route (local baselines, non-publishing captures, and hosted PR diffs remain scopeable), records the exact configured/selected route and viewport set plus one resolved branch/commit and publication workflow identity/sequence, and publishes only when the source run contains a successful stored capture for every expected identity. Complete requests send `publicationMode: "complete"` and `sourceRunId`, reuse the run's `branch` / `prHeadSha` as publication `refBranch` / `refSha`, and derive the baseline id deterministically from the run id so retries are stable. GitHub Actions supplies publication metadata automatically; other CI systems may set the explicit publication metadata variables. Missing, failed, duplicate, unexpected, or stale captures abort without publishing.
+- **Snap outage handling is consistent across the CLI and both wrapper actions** — `warn-and-skip` and `fallback-local` were re-implemented independently in `lib/cli.mjs`, `actions/pr-diff` and `actions/baseline`, and the copies had drifted. `lib/outage-policy.mjs` now holds the single implementation (`captureWithPolicy`, `diffWithPolicy`, `publishBaselineWithPolicy`) that all three call, and the following are fixed as a result (#125):
+  - A `fallback-local` capture in `actions/pr-diff` captured locally but still emitted `provider=snap`, so the compare step rebuilt `SnapProvider` and handed it local results carrying no run id. The steps now receive the *effective* provider.
+  - A `fallback-local` diff swapped only the diff provider. A capture Snap had rendered server-side has a manifest but no PNGs on the runner, so the local pixel engine produced a dimension-only result rather than a comparison. The routes are now recaptured locally first, and the recaptured artifacts are what get staged and uploaded. When no baseline artifact was resolved, the run reports `missing_main_baseline_artifact` instead of crashing the local diff on a missing results file.
+  - `warn-and-skip` exited the wrapper without writing the documented skipped summary, so the PR comment fell through to its "Capture Failed" body. Capture-time and diff-time skips now write a skipped `summary.json`/`summary.md` with reason `snap_unavailable`, expose the summary outputs, stage the report, and exit 0. `diff.mode` is not enforced against a skipped summary.
+  - `actions/baseline` applied no policy at all to `publishBaseline()`. `warn-and-skip` now exits 0 without an artifact, and `fallback-local` captures locally and stages/uploads that bundle, so the run still leaves a usable baseline.
+  - `snapdrift diff` let a capture-time `SnapSkipError` reach the CLI entry point, which exits 1 — the opposite of what `warn-and-skip` is configured to do.
+- **`shouldFailDriftCheck` no longer throws on a skipped summary** — it assumed every summary carried the full diff shape, so the final branch dereferenced `summaryData.errors.length` on `undefined` for the `{ status, reason, message, selectedRoutes }` shape a skipped run writes. `actions/enforce` defaults `summary-path` to exactly where those summaries land, so anyone orchestrating with the low-level actions rather than `actions/pr-diff` got a raw `TypeError` instead of a clean pass whenever a run was skipped for scope, a missing baseline, or a Snap outage. A summary with `status: "skipped"` or no `diff.mode` now returns `false` before any mode branch, and both `shouldFailDriftCheck` and `determineDriftStatus` default their array and counter reads (#132).
+
+## 0.8.1 - 2026-08-06
+
+### Fixes
+
+- **The root action can actually be published to the Marketplace** — its description was 130 characters, and GitHub rejects the listing at 125 or more, so ticking "Publish this Action to the GitHub Marketplace" on the `v0.8.0` release failed validation. Shortened to 115 characters, leading with "visual regression" so the listing matches what people search for. `npm run validate:actions` and `tests/marketplace-metadata.test.js` now enforce the limit against the root action; the sub-action descriptions are unaffected, since the rule only applies to the published entry point.
+
 ## 0.8.0 - 2026-08-06
 
 ### Features

package/README.md

@@ -48,17 +48,19 @@ You keep ownership of checkout, build, startup, readiness, and teardown. SnapDri
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift@v0.8.0
+  uses: ranacseruet/snapdrift@v0.8.2
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
 ```
 
+With `provider: "snap"`, baseline publication is a complete, fail-closed snapshot: it must run from the project's default branch and capture every configured route. Snap records the publication workflow identity plus a monotonic sequence so the API can reject stale overlapping publishers. GitHub Actions supplies these values automatically; other CI systems can provide `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`. Route scoping remains available for pull request diffs, non-publishing `snapdrift capture`, and local-provider baselines.
+
 **3. Run SnapDrift on pull requests:**
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.8.0
+  uses: ranacseruet/snapdrift@v0.8.2
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -71,10 +73,10 @@ The root action dispatches on `mode`. The same pipelines are also published as s
 
 ## Local CLI
 
-SnapDrift ships a `snapdrift` CLI for running captures, diffs, migrations, and config initialization locally against a running app — no GitHub Actions required. Use it during development to validate UI changes before pushing.
+SnapDrift ships a `snapdrift` CLI for running captures, diffs, migrations, and config initialization locally against a running app. Use it during development to validate UI changes before pushing. Canonical hosted baseline publication is the exception: `provider: "snap"` baselines require the project default branch plus explicit CI publication metadata; GitHub Actions provides that metadata automatically.
 
 ```bash
-# Establish a baseline — for provider "snap" this also publishes it
+# Establish a local-provider baseline
 snapdrift baseline
 
 # Capture screenshots without publishing anything
@@ -111,6 +113,7 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 - One global `diff.threshold`
 - Dimension shifts are reported separately from pixel drift
 - Local provider writes artifacts to the runner filesystem; for a hosted backend with a dashboard and a shared baseline store, configure `provider: "snap"` (see the [Integration Guide](docs/integration-guide.md#hosted-snap-provider))
+- Hosted Snap baselines publish only from the default branch and always include the complete configured route set
 
 ## Outgrew GitHub artifacts?
 

package/action.yml

@@ -1,5 +1,5 @@
 name: SnapDrift
-description: Capture, compare, and report UI drift for Playwright-based apps — baseline publishing and pull request visual diffs in one action.
+description: Visual regression for Playwright apps — capture routes, diff against a baseline, and report drift on pull requests.
 author: CodeSamplez
 
 branding:
@@ -15,10 +15,11 @@ branding:
 # action's own directory. `tests/marketplace-metadata.test.js` fails the build if those pins drift
 # from the root `package.json` version.
 #
-# The pins are commit SHAs carrying the version in a trailing comment, so that a consumer pinning
-# this action to a SHA gets an immutable chain rather than a mutable tag one level down. The SHA is
-# the commit that introduced the release's wrapper actions; the release commit cannot reference its
-# own SHA. The test accepts a plain `@vX.Y.Z` tag too, for unreleased refs.
+# Released versions use commit SHAs, so a consumer pinning this action to a SHA gets an immutable
+# chain rather than a mutable tag one level down. Before that release commit exists, an unreleased
+# version uses its upcoming `@vX.Y.Z` tag; the release process replaces it with the commit that holds
+# the wrapper content. The contract test accepts either form and requires the declared version to
+# match package.json.
 
 inputs:
   mode:
@@ -30,7 +31,7 @@ inputs:
     required: false
     default: .github/snapdrift.json
   route-ids:
-    description: Optional comma-separated route ids. In `pr-diff` mode, providing these skips changed-file scope detection.
+    description: Optional comma-separated route ids for PR diffs or local baselines. Hosted baselines must capture every configured route.
     required: false
     default: ''
   artifact-retention-days:
@@ -146,7 +147,7 @@ runs:
     - name: SnapDrift baseline
       id: baseline
       if: inputs.mode == 'baseline'
-      uses: ranacseruet/snapdrift/actions/baseline@539953ab07065be805be393d69bd3c9b6d53cf6e # v0.8.0
+      uses: ranacseruet/snapdrift/actions/baseline@f1ded4c7c0eb944b35eb8f70f8711f4f84397813 # v0.8.2
       with:
         repo-config-path: ${{ inputs.repo-config-path }}
         route-ids: ${{ inputs.route-ids }}
@@ -156,7 +157,7 @@ runs:
     - name: SnapDrift pull request diff
       id: pr-diff
       if: inputs.mode == 'pr-diff'
-      uses: ranacseruet/snapdrift/actions/pr-diff@539953ab07065be805be393d69bd3c9b6d53cf6e # v0.8.0
+      uses: ranacseruet/snapdrift/actions/pr-diff@f1ded4c7c0eb944b35eb8f70f8711f4f84397813 # v0.8.2
       with:
         github-token: ${{ inputs.github-token }}
         repo-config-path: ${{ inputs.repo-config-path }}

package/actions/baseline/action.yml

@@ -11,7 +11,7 @@ inputs:
     required: false
     default: .github/snapdrift.json
   route-ids:
-    description: Optional comma-separated route ids to capture.
+    description: Optional comma-separated route ids for local-provider baselines. Hosted Snap baselines must capture every configured route.
     required: false
     default: ''
   artifact-retention-days:
@@ -32,16 +32,16 @@ outputs:
     value: ${{ steps.stage.outputs.bundle_dir }}
   results-file:
     description: Absolute path to the generated baseline results file.
-    value: ${{ steps.capture.outputs.results_file }}
+    value: ${{ steps.publish.outputs.results_file || steps.capture.outputs.results_file }}
   manifest-file:
     description: Absolute path to the generated baseline manifest file.
-    value: ${{ steps.capture.outputs.manifest_file }}
+    value: ${{ steps.publish.outputs.manifest_file || steps.capture.outputs.manifest_file }}
   screenshots-root:
     description: Absolute path to the generated screenshots root.
-    value: ${{ steps.capture.outputs.screenshots_root }}
+    value: ${{ steps.publish.outputs.screenshots_root || steps.capture.outputs.screenshots_root }}
   selected-route-ids:
     description: Comma-separated route ids captured in this run.
-    value: ${{ steps.capture.outputs.selected_route_ids }}
+    value: ${{ steps.publish.outputs.selected_route_ids || steps.capture.outputs.selected_route_ids }}
 
 runs:
   using: composite
@@ -103,49 +103,37 @@ runs:
 
         const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
         const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
-        const { createProvider, SnapSkipError, SnapFallbackError } = await import(pathToFileURL(providerModulePath));
+        const policyModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/outage-policy.mjs');
+        const { createProvider } = await import(pathToFileURL(providerModulePath));
         const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { captureWithPolicy } = await import(pathToFileURL(policyModulePath));
 
         const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-        const provider = createProvider(config.provider || 'local', config);
+        const providerName = config.provider || 'local';
 
-        let result;
-        try {
-          result = await provider.capture({
+        const captured = await captureWithPolicy({
+          provider: createProvider(providerName, config),
+          providerName,
+          config,
+          captureOptions: {
             configPath: process.env.REPO_CONFIG_PATH || undefined,
             routeIds: splitCommaList(process.env.ROUTE_IDS),
             purpose: 'baseline'
-          });
-        } catch (err) {
-          if (err instanceof SnapSkipError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable — skipping baseline capture (warn-and-skip).\n`);
-            await fs.appendFile(process.env.GITHUB_OUTPUT, `provider=skipped\n`);
-            process.exit(0);
-          }
-          if (err instanceof SnapFallbackError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable — falling back to local provider.\n`);
-            const { createProvider: cp2 } = await import(pathToFileURL(providerModulePath));
-            result = await cp2('local', config).capture({
-              configPath: process.env.REPO_CONFIG_PATH || undefined,
-              routeIds: splitCommaList(process.env.ROUTE_IDS)
-            });
-            // Report as local so publish is skipped and stage/upload run instead
-            const outputs = [
-              `provider=local`,
-              `results_file=${result.resultsPath}`,
-              `manifest_file=${result.manifestPath}`,
-              `screenshots_root=${result.screenshotsRoot}`,
-              `selected_route_ids=${result.selectedRouteIds.join(',')}`
-            ].join('\n') + '\n';
-            await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
-            process.exit(0);
-          } else {
-            throw err;
-          }
+          },
+          onSkip: () => process.stderr.write('[SnapDrift] Snap unavailable — skipping baseline capture (warn-and-skip).\n'),
+          onFallback: () => process.stderr.write('[SnapDrift] Snap unavailable — falling back to local provider.\n')
+        });
+
+        if (captured.outcome === 'skipped') {
+          await fs.appendFile(process.env.GITHUB_OUTPUT, `provider=skipped\n`);
+          process.exit(0);
         }
 
+        const result = captured.result;
         const outputs = [
-          `provider=${config.provider || 'local'}`,
+          // The effective provider: reporting "local" after a fallback-local
+          // capture is what makes publish skip and stage/upload run instead.
+          `provider=${captured.providerName}`,
           `results_file=${result.resultsPath}`,
           `manifest_file=${result.manifestPath}`,
           `screenshots_root=${result.screenshotsRoot}`,
@@ -160,34 +148,67 @@ runs:
       shell: bash
       env:
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
+        ROUTE_IDS: ${{ inputs.route-ids }}
         RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
       run: |
         node --input-type=module <<'EOF'
+        import fs from 'node:fs/promises';
         import path from 'node:path';
         import { pathToFileURL } from 'node:url';
 
         const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
         const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+        const policyModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/outage-policy.mjs');
         const { createProvider } = await import(pathToFileURL(providerModulePath));
-        const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+        const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { publishBaselineWithPolicy } = await import(pathToFileURL(policyModulePath));
 
         const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-        const provider = createProvider('snap', config);
 
-        await provider.publishBaseline({
-          resultsPath: process.env.RESULTS_PATH || undefined
+        // Snap can go down after the capture submission succeeds — while polling
+        // the render or posting the baseline. onUnavailable has to cover that
+        // window too, or warn-and-skip still fails the build and fallback-local
+        // still leaves the repo with no baseline artifact. See #125.
+        const published = await publishBaselineWithPolicy({
+          provider: createProvider('snap', config),
+          publishOptions: { resultsPath: process.env.RESULTS_PATH || undefined },
+          captureOptions: {
+            configPath: process.env.REPO_CONFIG_PATH || undefined,
+            routeIds: splitCommaList(process.env.ROUTE_IDS),
+            purpose: 'baseline'
+          },
+          onSkip: () => process.stderr.write('[SnapDrift] Snap unavailable — skipping baseline publish (warn-and-skip).\n'),
+          onFallback: () => process.stderr.write('[SnapDrift] Snap unavailable during publish — capturing locally so the run still produces a baseline artifact.\n')
         });
 
+        if (published.outcome === 'skipped') {
+          await fs.appendFile(process.env.GITHUB_OUTPUT, `provider=skipped\n`);
+          process.exit(0);
+        }
+
+        if (published.outcome === 'fell-back') {
+          const recapture = published.recapture;
+          const outputs = [
+            `provider=local`,
+            `results_file=${recapture.resultsPath}`,
+            `manifest_file=${recapture.manifestPath}`,
+            `screenshots_root=${recapture.screenshotsRoot}`,
+            `selected_route_ids=${recapture.selectedRouteIds.join(',')}`
+          ].join('\n') + '\n';
+          await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
+          process.exit(0);
+        }
+
         process.stdout.write('[SnapDrift] Snap baseline published successfully.\n');
         EOF
 
     - id: stage
-      if: steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped'
+      if: (steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped') || steps.publish.outputs.provider == 'local'
       shell: bash
       env:
-        RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
-        MANIFEST_PATH: ${{ steps.capture.outputs.manifest_file }}
-        SCREENSHOTS_DIR: ${{ steps.capture.outputs.screenshots_root }}/screenshots
+        RESULTS_PATH: ${{ steps.publish.outputs.results_file || steps.capture.outputs.results_file }}
+        MANIFEST_PATH: ${{ steps.publish.outputs.manifest_file || steps.capture.outputs.manifest_file }}
+        SCREENSHOTS_DIR: ${{ steps.publish.outputs.screenshots_root || steps.capture.outputs.screenshots_root }}/screenshots
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -207,7 +228,7 @@ runs:
         await fs.appendFile(process.env.GITHUB_OUTPUT, `bundle_dir=${result.bundleDir}\n`);
         EOF
 
-    - if: inputs.upload-artifact == 'true' && steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped'
+    - if: inputs.upload-artifact == 'true' && ((steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped') || steps.publish.outputs.provider == 'local')
       uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
       with:
         name: ${{ steps.config.outputs.artifact_name }}

package/actions/pr-diff/action.yml

@@ -340,38 +340,54 @@ runs:
 
         const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
         const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
-        const { createProvider, SnapSkipError, SnapFallbackError } = await import(pathToFileURL(providerModulePath));
+        const policyModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/outage-policy.mjs');
+        const summaryModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/drift-summary.mjs');
+        const { createProvider } = await import(pathToFileURL(providerModulePath));
         const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { captureWithPolicy, SNAP_UNAVAILABLE_REASON } = await import(pathToFileURL(policyModulePath));
+        const { writeDriftSummary } = await import(pathToFileURL(summaryModulePath));
 
         const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-        const provider = createProvider(config.provider || 'local', config);
-
-        let result;
-        try {
-          result = await provider.capture({
+        const providerName = config.provider || 'local';
+        const routeIds = splitCommaList(process.env.ROUTE_IDS);
+
+        const captured = await captureWithPolicy({
+          provider: createProvider(providerName, config),
+          providerName,
+          config,
+          captureOptions: {
             configPath: process.env.REPO_CONFIG_PATH || undefined,
-            routeIds: splitCommaList(process.env.ROUTE_IDS)
+            routeIds
+          },
+          onSkip: () => process.stderr.write('[SnapDrift] Snap unavailable — skipping visual regression (warn-and-skip).\n'),
+          onFallback: () => process.stderr.write('[SnapDrift] Snap unavailable — falling back to local provider.\n')
+        });
+
+        if (captured.outcome === 'skipped') {
+          // warn-and-skip is documented as "write a skipped summary and exit 0".
+          // Without the summary the report step falls through to its
+          // "Capture Failed" body, which is not what happened. See #125.
+          const skipped = await writeDriftSummary({
+            reason: SNAP_UNAVAILABLE_REASON,
+            selectedRouteIds: routeIds
           });
-        } catch (err) {
-          if (err instanceof SnapSkipError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable — skipping visual regression (warn-and-skip).\n`);
-            await fs.appendFile(process.env.GITHUB_OUTPUT, `provider=skipped\n`);
-            process.exit(0);
-          }
-          if (err instanceof SnapFallbackError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable — falling back to local provider.\n`);
-            const { createProvider: cp2 } = await import(pathToFileURL(providerModulePath));
-            result = await cp2('local', config).capture({
-              configPath: process.env.REPO_CONFIG_PATH || undefined,
-              routeIds: splitCommaList(process.env.ROUTE_IDS)
-            });
-          } else {
-            throw err;
-          }
+          const skipOutputs = [
+            `provider=skipped`,
+            `summary_path=${skipped.summaryPath}`,
+            `markdown_path=${skipped.markdownPath}`,
+            `status=${skipped.summary.status || ''}`
+          ].join('\n') + '\n';
+          await fs.appendFile(process.env.GITHUB_OUTPUT, skipOutputs);
+          process.exit(0);
         }
 
+        const result = captured.result;
         const outputs = [
-          `provider=${config.provider || 'local'}`,
+          // The *effective* provider, not the configured one: after a
+          // fallback-local capture the compare step must not rebuild
+          // SnapProvider around local results that carry no run id.
+          `provider=${captured.providerName}`,
+          `local_screenshots=${captured.localScreenshots ? 'true' : 'false'}`,
           `results_file=${result.resultsPath}`,
           `manifest_file=${result.manifestPath}`,
           `screenshots_root=${result.screenshotsRoot}`,
@@ -394,6 +410,10 @@ runs:
         BASELINE_SOURCE_SHA: ${{ steps.baseline.outputs.head_sha }}
         CURRENT_RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
         CURRENT_MANIFEST_PATH: ${{ steps.capture.outputs.manifest_file }}
+        CURRENT_SCREENSHOTS_ROOT: ${{ steps.capture.outputs.screenshots_root }}
+        CAPTURE_PROVIDER: ${{ steps.capture.outputs.provider }}
+        LOCAL_SCREENSHOTS: ${{ steps.capture.outputs.local_screenshots }}
+        BASELINE_FOUND: ${{ steps.baseline.outputs.found }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -402,45 +422,75 @@ runs:
 
         const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
         const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
-        const { createProvider, SnapSkipError, SnapFallbackError } = await import(pathToFileURL(providerModulePath));
+        const policyModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/outage-policy.mjs');
+        const summaryModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/drift-summary.mjs');
+        const { createProvider } = await import(pathToFileURL(providerModulePath));
         const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { diffWithPolicy, MISSING_BASELINE_REASON, SNAP_UNAVAILABLE_REASON } = await import(pathToFileURL(policyModulePath));
+        const { writeDriftSummary } = await import(pathToFileURL(summaryModulePath));
 
         const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-        const provider = createProvider(config.provider || 'local', config);
+        // The capture step reports the provider that actually ran, which is
+        // "local" once a fallback-local capture has happened.
+        const providerName = process.env.CAPTURE_PROVIDER || config.provider || 'local';
+        const routeIds = splitCommaList(process.env.ROUTE_IDS);
 
         const resolvedOutDir = path.resolve('qa-artifacts/snapdrift/drift/current');
         const resolvedSummaryPath = path.join(resolvedOutDir, 'summary.json');
         const resolvedMarkdownPath = path.join(resolvedOutDir, 'summary.md');
 
+        const captureOptions = {
+          configPath: process.env.REPO_CONFIG_PATH || undefined,
+          routeIds
+        };
+
         const diffOptions = {
           configPath: process.env.REPO_CONFIG_PATH || undefined,
           baselineResultsPath: process.env.BASELINE_RESULTS_PATH || undefined,
           baselineManifestPath: process.env.BASELINE_MANIFEST_PATH || undefined,
           baselineRunDir: process.env.BASELINE_RUN_DIR || undefined,
-          routeIds: splitCommaList(process.env.ROUTE_IDS),
+          routeIds,
           baselineArtifactName: process.env.BASELINE_ARTIFACT_NAME || undefined,
           baselineSourceSha: process.env.BASELINE_SOURCE_SHA || undefined,
           currentResultsPath: process.env.CURRENT_RESULTS_PATH || undefined,
-          currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined
+          currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined,
+          currentRunDir: process.env.CURRENT_SCREENSHOTS_ROOT || undefined
         };
 
-        let diffResult;
-        try {
-          diffResult = await provider.diff(diffOptions);
-        } catch (err) {
-          if (err instanceof SnapSkipError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable during diff — skipping (warn-and-skip).\n`);
-            process.exit(0);
-          }
-          if (err instanceof SnapFallbackError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable during diff — falling back to local provider.\n`);
-            const { createProvider: cp2 } = await import(pathToFileURL(providerModulePath));
-            diffResult = await cp2('local', config).diff(diffOptions);
-          } else {
-            throw err;
-          }
+        const diffed = await diffWithPolicy({
+          provider: createProvider(providerName, config),
+          providerName,
+          diffOptions,
+          captureOptions,
+          localScreenshots: process.env.LOCAL_SCREENSHOTS !== 'false',
+          baselineAvailable: process.env.BASELINE_FOUND === 'true',
+          onSkip: () => process.stderr.write('[SnapDrift] Snap unavailable during diff — skipping (warn-and-skip).\n'),
+          onFallback: () => process.stderr.write('[SnapDrift] Snap unavailable during diff — falling back to local provider.\n'),
+          onRecapture: () => process.stderr.write('[SnapDrift] The current capture was rendered by Snap, so it has no local screenshots — recapturing locally before diffing.\n'),
+          onBaselineUnavailable: () => process.stderr.write('[SnapDrift] No baseline artifact is available, so the local diff cannot run.\n')
+        });
+
+        // Every non-throwing outcome writes a summary. A wrapper run that ends
+        // without one makes the report step claim "Capture Failed". See #125.
+        if (diffed.outcome !== 'diffed') {
+          const skipped = await writeDriftSummary({
+            reason: diffed.outcome === 'skipped' ? SNAP_UNAVAILABLE_REASON : MISSING_BASELINE_REASON,
+            baselineAvailable: diffed.outcome === 'skipped' ? undefined : false,
+            currentResultsPath: process.env.CURRENT_RESULTS_PATH || undefined,
+            selectedRouteIds: routeIds,
+            outDir: resolvedOutDir
+          });
+          const skipOutputs = [
+            `skipped=true`,
+            `summary_path=${skipped.summaryPath}`,
+            `markdown_path=${skipped.markdownPath}`,
+            `status=${skipped.summary.status || ''}`
+          ].join('\n') + '\n';
+          await fs.appendFile(process.env.GITHUB_OUTPUT, skipOutputs);
+          process.exit(0);
         }
-        const { summary, markdown } = diffResult;
+
+        const { summary, markdown } = diffed.result;
 
         await fs.mkdir(resolvedOutDir, { recursive: true });
         await Promise.all([
@@ -449,9 +499,16 @@ runs:
         ]);
 
         const outputs = [
+          `skipped=false`,
           `summary_path=${resolvedSummaryPath}`,
           `markdown_path=${resolvedMarkdownPath}`,
-          `status=${summary.status || ''}`
+          `status=${summary.status || ''}`,
+          // A fallback-local diff of a remote Snap capture recaptures on the
+          // runner; the staged bundle has to carry those PNGs, not the empty
+          // placeholder paths the Snap capture step emitted.
+          `current_results_file=${diffed.recapture?.resultsPath || ''}`,
+          `current_manifest_file=${diffed.recapture?.manifestPath || ''}`,
+          `current_screenshots_root=${diffed.recapture?.screenshotsRoot || ''}`
         ].join('\n') + '\n';
 
         await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
@@ -486,7 +543,7 @@ runs:
         EOF
 
     - id: skipped_baseline
-      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found != 'true' && steps.capture.outputs.provider != 'snap'
+      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found != 'true' && steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped'
       shell: bash
       env:
         MESSAGE: ${{ steps.baseline.outputs.message }}
@@ -521,14 +578,14 @@ runs:
     - id: stage
       shell: bash
       env:
-        SUMMARY_JSON_PATH: ${{ steps.compare.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
-        SUMMARY_MARKDOWN_PATH: ${{ steps.compare.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path }}
+        SUMMARY_JSON_PATH: ${{ steps.compare.outputs.summary_path || steps.capture.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
+        SUMMARY_MARKDOWN_PATH: ${{ steps.compare.outputs.markdown_path || steps.capture.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path }}
         BASELINE_RESULTS_PATH: ${{ steps.baseline_paths.outputs.results_file }}
-        CURRENT_RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
+        CURRENT_RESULTS_PATH: ${{ steps.compare.outputs.current_results_file || steps.capture.outputs.results_file }}
         BASELINE_MANIFEST_PATH: ${{ steps.baseline_paths.outputs.manifest_file }}
-        CURRENT_MANIFEST_PATH: ${{ steps.capture.outputs.manifest_file }}
+        CURRENT_MANIFEST_PATH: ${{ steps.compare.outputs.current_manifest_file || steps.capture.outputs.manifest_file }}
         BASELINE_SCREENSHOTS_DIR: ${{ steps.baseline_paths.outputs.screenshots_dir }}
-        CURRENT_SCREENSHOTS_DIR: ${{ steps.capture.outputs.screenshots_root != '' && format('{0}/screenshots', steps.capture.outputs.screenshots_root) || '' }}
+        CURRENT_SCREENSHOTS_ROOT: ${{ steps.compare.outputs.current_screenshots_root || steps.capture.outputs.screenshots_root }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -538,6 +595,8 @@ runs:
         const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/stage-artifacts.mjs');
         const { stageArtifacts } = await import(pathToFileURL(modulePath));
 
+        const currentScreenshotsRoot = process.env.CURRENT_SCREENSHOTS_ROOT || '';
+
         const result = await stageArtifacts({
           artifactType: 'diff',
           summaryJsonPath: process.env.SUMMARY_JSON_PATH || undefined,
@@ -547,7 +606,7 @@ runs:
           baselineManifestPath: process.env.BASELINE_MANIFEST_PATH || undefined,
           currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined,
           baselineScreenshotsDir: process.env.BASELINE_SCREENSHOTS_DIR || undefined,
-          currentScreenshotsDir: process.env.CURRENT_SCREENSHOTS_DIR || undefined
+          currentScreenshotsDir: currentScreenshotsRoot ? path.join(currentScreenshotsRoot, 'screenshots') : undefined
         });
 
         await fs.appendFile(process.env.GITHUB_OUTPUT, `bundle_dir=${result.bundleDir}\n`);
@@ -563,7 +622,7 @@ runs:
     - if: always()
       shell: bash
       env:
-        SUMMARY_FILE: ${{ steps.compare.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path }}
+        SUMMARY_FILE: ${{ steps.compare.outputs.markdown_path || steps.capture.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path }}
       run: |
         if [ -f "$SUMMARY_FILE" ]; then
           cat "$SUMMARY_FILE" >> "$GITHUB_STEP_SUMMARY"
@@ -573,7 +632,7 @@ runs:
       uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
       env:
         PR_NUMBER: ${{ steps.context.outputs.pr_number }}
-        SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
+        SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.capture.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
         ARTIFACT_NAME: ${{ steps.context.outputs.artifact_name }}
         RUN_URL: ${{ steps.context.outputs.run_url }}
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
@@ -674,7 +733,9 @@ runs:
             });
           }
 
-    - if: steps.scope.outputs.should_run == 'true' && steps.capture.outputs.provider != 'skipped' && (steps.baseline.outputs.found == 'true' || steps.capture.outputs.provider == 'snap')
+    # A skipped compare writes a summary with no diff counters, so enforcement
+    # has nothing to evaluate — `warn-and-skip` means "do not fail my build".
+    - if: steps.scope.outputs.should_run == 'true' && steps.capture.outputs.provider != 'skipped' && steps.compare.outputs.skipped != 'true' && (steps.baseline.outputs.found == 'true' || steps.capture.outputs.provider == 'snap')
       shell: bash
       run: |
         node --input-type=module <<'EOF'
@@ -700,9 +761,9 @@ runs:
         SCOPE_REASON: ${{ steps.scope.outputs.reason }}
         SELECTED_ROUTE_IDS: ${{ steps.scope.outputs.selected_route_ids }}
         BASELINE_FOUND: ${{ steps.baseline.outputs.found || 'false' }}
-        STATUS: ${{ steps.compare.outputs.status || steps.skipped_baseline.outputs.status || steps.skipped_scope.outputs.status || '' }}
-        SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path || '' }}
-        MARKDOWN_PATH: ${{ steps.compare.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path || '' }}
+        STATUS: ${{ steps.compare.outputs.status || steps.capture.outputs.status || steps.skipped_baseline.outputs.status || steps.skipped_scope.outputs.status || '' }}
+        SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.capture.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path || '' }}
+        MARKDOWN_PATH: ${{ steps.compare.outputs.markdown_path || steps.capture.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path || '' }}
         BUNDLE_DIR: ${{ steps.stage.outputs.bundle_dir }}
       run: |
         {