snapdrift 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.0 - 2026-06-08
+
+### Features
+
+- **Snap local-capture hybrid** — when `provider: "snap"` and `baseUrl` resolves to a local address (localhost, `127.0.0.0/8`, `::1`, `0.0.0.0`), Playwright now runs on the runner to render the page, and the resulting PNG is uploaded to Snap via `POST /v1/visual/captures/:id/local-result`. This makes it possible to point SnapDrift at a server only the runner can reach — the common case — without exposing the server to Snap's render worker. Captures are flagged with `localCapture: true` so Snap keeps them out of the render queue, and the output `results.json` records `provider: "snap"` plus `captureMode: "local-upload"`.
+
+### Fixes
+
+- **Snap baseline run no longer diffs against an old baseline** — `publishBaseline` now sets `skipBaselineResolution: true` on baseline-publish runs and omits `baselineId` from run creation. Previously, publishing a fresh baseline would diff it against the prior baseline, which failed on dimension mismatch and burned an upload.
+- **`captureProfileJson` no longer sent on Snap run creation** — the render environment is owned by Snap's render worker, not the client, and the server dereferences nested fields (browser, platform, fonts, viewport) that SnapDrift's minimal profile doesn't populate, which crashed it with a 500. The render worker already defaults locale/timezone/viewport when no profile is present, so omitting it is behaviour-preserving.
+- **Run-creation includes `branch` and `baselineId`** — `branch` is sent from `GITHUB_HEAD_REF` (PR source) or `GITHUB_REF_NAME` (push); `baselineId` is the latest accepted baseline for the project, so the backend can diff every capture. Without `baselineId` Snap short-circuits to `diffed` with no comparison data.
+- **4xx never falls back, even with `onUnavailable` set** — clarifies the contract: `onUnavailable` is consulted only after 5xx/network retries are exhausted, never on a 4xx (which is a configuration error, not an outage).
+- **`actions/pr-diff` no longer installs Playwright when `provider: "snap"` and the run won't need it** — gated on the same `isLocalBaseUrl` check the `baseline` action uses.
+
+### Infrastructure
+
+- **`@snapdrift/manifest` v1.2.0** — added the `ProviderCaptureOptions.purpose` type contract for baseline-publish versus diff captures.
+
+## 0.4.0 - 2026-05-26
+
+### Features
+
+- **VisualProvider interface** — new `VisualProvider` interface (`capture`, `diff`, `publishBaseline`, `fetchLatestBaseline`, `buildCommentBody`) with `LocalProvider` and `SnapProvider` implementations. Config `provider` field (`"local"` | `"snap"`) selects the backend; defaults to `"local"` for zero-config backward compatibility.
+- **SnapProvider** — calls Snap's `/v1/visual/*` API for capture, diff, and baseline management. Retries on 5xx with exponential backoff (3 attempts, 30 s cap). Honors `snap.onUnavailable` (`"fail"` | `"warn-and-skip"` | `"fallback-local"`). 4xx errors never retry or fall back.
+- **Snap config** — new `snap` config block (`apiUrl`, `apiKeyEnv`/`apiKey`, `projectId`, `onUnavailable`) in `snapdrift.json`. Exactly one of `apiKeyEnv` or `apiKey` is required when `provider: "snap"`.
+- **PR comment unification** — both providers now produce identical PR comment markdown via a shared `buildCommentBody(summary, meta?)` method. `SnapProvider` appends a "View in dashboard →" link when `dashboardUrl` is present; `LocalProvider` omits it. Comment steps route through the provider instead of calling `buildReportCommentBody` directly, with a defensive fallback to `LocalProvider` if config loading fails.
+- **`migrate-baselines` command** — one-shot CLI command (`snapdrift migrate-baselines --to snap` / `--to local`) to upload local baselines to Snap or export Snap baselines back to a local directory. Supports `--accept-cross-engine` for engine-mismatch scenarios.
+- **`init --from-snap-action` codemod** — translates a Snap `github-action` workflow YAML into `snapdrift.json` with `provider: "snap"`. Emits structured warnings for features with no direct equivalent (jpeg format, baseline tags, single-shot artifact upload).
+
+### Infrastructure
+
+- **`@snapdrift/manifest` v1.1.0** — added `ProviderCommentMeta`, `dashboardUrl` on `VisualDiffSummary`, `buildCommentBody` on `VisualProvider`, `SnapConfig` re-export.
+- **`@snapdrift/adapter-report-md` v1.1.0** — `buildReportCommentBody` now accepts `dashboardUrl` in meta; renders "View in dashboard →" link when present and valid.
+- **Action contract tests** — `snapdrift-actions-contract` test suite now asserts that comment and pr-diff steps include `createProvider` and `buildCommentBody` calls.
+- **Provider unification tests** — new `buildCommentBody — provider unification` test block verifying identical markdown output across providers, dashboard link inclusion/exclusion, and URL validation.
+
 ## 0.3.0 - 2026-05-26
 
 ### Infrastructure

package/README.md

@@ -8,15 +8,18 @@
 
 SnapDrift captures full-page application frames, compares them against a known baseline, and reports drift directly in GitHub Actions.
 
-SnapDrift is ready to integrate from public GitHub releases. Workflow examples below use the first public tag for readability; security-conscious consumers can pin the resolved commit SHA instead.
+SnapDrift is ready to integrate from public GitHub releases. Workflow examples below use the latest public tag for readability; security-conscious consumers can pin the resolved commit SHA instead.
 
 ## What SnapDrift handles
 
 - Baseline capture on `main`
 - Pull request drift detection against the latest successful baseline
 - Route scoping from changed files
-- PR report upserts
+- PR report upserts (with optional Snap dashboard link)
 - Drift enforcement through `diff.mode`
+- Pluggable backends: local filesystem (default) or hosted Snap (`provider: "snap"`)
+- One-shot baseline migration between backends
+- Codemod that translates an existing Snap `github-action` workflow to `snapdrift.json`
 
 You keep ownership of checkout, build, startup, readiness, and teardown. SnapDrift takes over once the app is reachable.
 
@@ -44,7 +47,7 @@ You keep ownership of checkout, build, startup, readiness, and teardown. SnapDri
 
 ```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
 ```
@@ -53,17 +56,17 @@ You keep ownership of checkout, build, startup, readiness, and teardown. SnapDri
 
 ```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
 ```
 
-That is the full integration. See the [Integration Guide](docs/integration-guide.md) for workflow examples, permissions, compatibility notes, and advanced overrides.
+That is the full integration. See the [Integration Guide](docs/integration-guide.md) for workflow examples, permissions, compatibility notes, advanced overrides, and the hosted Snap backend (`provider: "snap"`).
 
 ## Local CLI
 
-SnapDrift ships a `snapdrift` CLI for running captures and diffs 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 — no GitHub Actions required. Use it during development to validate UI changes before pushing.
 
 ```bash
 # Capture a baseline
@@ -71,6 +74,12 @@ snapdrift capture
 
 # Compare against it after making UI changes
 snapdrift diff --open
+
+# Migrate local baselines to the hosted Snap backend
+snapdrift migrate-baselines --to snap
+
+# Translate an existing Snap github-action workflow into snapdrift.json
+snapdrift init --from-snap-action .github/workflows/snap.yml
 ```
 
 See the [Local CLI guide](docs/local-cli.md) for installation, all flags, directory layout, and examples.
@@ -88,11 +97,12 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 
 ## Current constraints
 
-- Ubuntu runners only
+- Ubuntu runners only (local CLI works on any OS Node 22+ supports)
 - Full-page capture only
 - Viewport presets: `desktop` (1440×900) and `mobile` (390×844), or custom `{ "width": number, "height": number }`
 - 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))
 
 ## Docs
 

package/actions/baseline/action.yml

@@ -51,6 +51,10 @@ runs:
       with:
         node-version: '22'
 
+    - name: Install action dependencies
+      shell: bash
+      run: npm ci --prefix "$ACTION_ROOT"
+
     - id: config
       shell: bash
       env:
@@ -62,17 +66,22 @@ runs:
         import { pathToFileURL } from 'node:url';
 
         const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+        const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
         const { loadSnapdriftConfig } = await import(pathToFileURL(modulePath));
+        const { isLocalBaseUrl } = await import(pathToFileURL(providerModulePath));
         const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
 
-        await fs.appendFile(process.env.GITHUB_OUTPUT, `artifact_name=${config.baselineArtifactName}\n`);
+        const outputs = [
+          `artifact_name=${config.baselineArtifactName}`,
+          `provider=${config.provider || 'local'}`,
+          `on_unavailable=${config.snap?.onUnavailable || 'fail'}`,
+          `snap_local_capture=${(config.provider || 'local') === 'snap' && isLocalBaseUrl(config.baseUrl) ? 'true' : 'false'}`
+        ].join('\n') + '\n';
+        await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
         EOF
 
-    - name: Install shared action dependencies
-      shell: bash
-      run: npm ci --prefix "$ACTION_ROOT"
-
     - name: Install Playwright Chromium
+      if: steps.config.outputs.provider != 'snap' || steps.config.outputs.on_unavailable == 'fallback-local' || steps.config.outputs.snap_local_capture == 'true'
       shell: bash
       run: |
         "$ACTION_ROOT/node_modules/.bin/playwright" install --with-deps chromium
@@ -88,17 +97,51 @@ runs:
         import path from 'node:path';
         import { pathToFileURL } from 'node:url';
 
-        const captureModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/capture-routes.mjs');
+        const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
         const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
-        const { runBaselineCapture } = await import(pathToFileURL(captureModulePath));
-        const { splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { createProvider, SnapSkipError, SnapFallbackError } = await import(pathToFileURL(providerModulePath));
+        const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
 
-        const result = await runBaselineCapture({
-          configPath: process.env.REPO_CONFIG_PATH || undefined,
-          routeIds: splitCommaList(process.env.ROUTE_IDS)
-        });
+        const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+        const provider = createProvider(config.provider || 'local', config);
+
+        let result;
+        try {
+          result = await provider.capture({
+            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;
+          }
+        }
 
         const outputs = [
+          `provider=${config.provider || 'local'}`,
           `results_file=${result.resultsPath}`,
           `manifest_file=${result.manifestPath}`,
           `screenshots_root=${result.screenshotsRoot}`,
@@ -108,7 +151,34 @@ runs:
         await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
         EOF
 
+    - id: publish
+      if: steps.capture.outputs.provider == 'snap'
+      shell: bash
+      env:
+        REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
+        RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
+      run: |
+        node --input-type=module <<'EOF'
+        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 { createProvider } = await import(pathToFileURL(providerModulePath));
+        const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+
+        const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+        const provider = createProvider('snap', config);
+
+        await provider.publishBaseline({
+          resultsPath: process.env.RESULTS_PATH || undefined
+        });
+
+        process.stdout.write('[SnapDrift] Snap baseline published successfully.\n');
+        EOF
+
     - id: stage
+      if: steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped'
       shell: bash
       env:
         RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
@@ -133,7 +203,7 @@ runs:
         await fs.appendFile(process.env.GITHUB_OUTPUT, `bundle_dir=${result.bundleDir}\n`);
         EOF
 
-    - if: inputs.upload-artifact == 'true'
+    - if: inputs.upload-artifact == 'true' && steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped'
       uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
       with:
         name: ${{ steps.config.outputs.artifact_name }}

package/actions/comment/action.yml

@@ -20,6 +20,10 @@ inputs:
     description: Artifact label to include in the comment.
     required: false
     default: ''
+  repo-config-path:
+    description: Path to the SnapDrift config file (needed for provider-aware comment rendering).
+    required: false
+    default: .github/snapdrift.json
   max-changed-rows:
     description: Maximum number of changed-route rows shown in the PR comment before truncation.
     required: false
@@ -36,12 +40,22 @@ runs:
       shell: bash
       run: echo "ACTION_ROOT=$(cd "$GITHUB_ACTION_PATH/../.." && pwd)" >> "$GITHUB_ENV"
 
+    - name: Set up Node.js
+      uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      with:
+        node-version: '22'
+
+    - name: Install action dependencies
+      shell: bash
+      run: npm ci --prefix "$ACTION_ROOT"
+
     - uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
       env:
         VISUAL_DIFF_SUMMARY_PATH: ${{ inputs.summary-path }}
         VISUAL_DIFF_RUN_URL: ${{ inputs.run-url }}
         VISUAL_DIFF_ARTIFACT_NAME: ${{ inputs.artifact-name }}
         INPUT_PR_NUMBER: ${{ inputs.pr-number }}
+        REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
         MAX_ERROR_ROWS: ${{ inputs.max-error-rows }}
       with:
@@ -63,15 +77,29 @@ runs:
             return;
           }
 
-          const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
-          const { buildReportCommentBody, PR_COMMENT_MARKERS } = await import(pathToFileURL(modulePath));
+          const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
+          const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+          const prCommentModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
+          const { createProvider } = await import(pathToFileURL(providerModulePath));
+          const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+          const { PR_COMMENT_MARKERS } = await import(pathToFileURL(prCommentModulePath));
+
+          // Provider-loading block duplicated in actions/pr-diff/action.yml — keep in sync.
+          let provider;
+          try {
+            const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+            provider = createProvider(config.provider || 'local', config);
+          } catch (err) {
+            core.warning(`Could not load SnapDrift config; falling back to LocalProvider. ${err.message}`);
+            provider = createProvider('local');
+          }
 
           const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
           const runUrl = process.env.VISUAL_DIFF_RUN_URL || `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`;
 
           const maxChangedRows = Number(process.env.MAX_CHANGED_ROWS) || 20;
           const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
-          const body = buildReportCommentBody(summary, {
+          const body = provider.buildCommentBody(summary, {
             artifactName: process.env.VISUAL_DIFF_ARTIFACT_NAME || '',
             runUrl,
             maxChangedRows,

package/actions/pr-diff/action.yml

@@ -95,6 +95,10 @@ runs:
       with:
         node-version: '22'
 
+    - name: Install action dependencies
+      shell: bash
+      run: npm ci --prefix "$ACTION_ROOT"
+
     - id: context
       uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
       env:
@@ -289,13 +293,31 @@ runs:
           echo "screenshots_dir=$(dirname "$MANIFEST_FILE")/screenshots"
         } >> "$GITHUB_OUTPUT"
 
-    - name: Install shared action dependencies
+    - id: config
       if: steps.scope.outputs.should_run == 'true'
       shell: bash
-      run: npm ci --prefix "$ACTION_ROOT"
+      env:
+        REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
+      run: |
+        node --input-type=module <<'EOF'
+        import fs from 'node:fs/promises';
+        import path from 'node:path';
+        import { pathToFileURL } from 'node:url';
+        const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+        const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
+        const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+        const { isLocalBaseUrl } = await import(pathToFileURL(providerModulePath));
+        const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+        const outputs = [
+          `provider=${config.provider || 'local'}`,
+          `on_unavailable=${config.snap?.onUnavailable || 'fail'}`,
+          `snap_local_capture=${(config.provider || 'local') === 'snap' && isLocalBaseUrl(config.baseUrl) ? 'true' : 'false'}`
+        ].join('\n') + '\n';
+        await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
+        EOF
 
     - name: Install Playwright Chromium
-      if: steps.scope.outputs.should_run == 'true'
+      if: steps.scope.outputs.should_run == 'true' && (steps.config.outputs.provider != 'snap' || steps.config.outputs.on_unavailable == 'fallback-local' || steps.config.outputs.snap_local_capture == 'true')
       shell: bash
       run: |
         "$ACTION_ROOT/node_modules/.bin/playwright" install --with-deps chromium
@@ -312,17 +334,40 @@ runs:
         import path from 'node:path';
         import { pathToFileURL } from 'node:url';
 
-        const captureModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/capture-routes.mjs');
+        const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
         const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
-        const { runBaselineCapture } = await import(pathToFileURL(captureModulePath));
-        const { splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { createProvider, SnapSkipError, SnapFallbackError } = await import(pathToFileURL(providerModulePath));
+        const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
 
-        const result = await runBaselineCapture({
-          configPath: process.env.REPO_CONFIG_PATH || undefined,
-          routeIds: splitCommaList(process.env.ROUTE_IDS)
-        });
+        const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+        const provider = createProvider(config.provider || 'local', config);
+
+        let result;
+        try {
+          result = await provider.capture({
+            configPath: process.env.REPO_CONFIG_PATH || undefined,
+            routeIds: splitCommaList(process.env.ROUTE_IDS)
+          });
+        } 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 outputs = [
+          `provider=${config.provider || 'local'}`,
           `results_file=${result.resultsPath}`,
           `manifest_file=${result.manifestPath}`,
           `screenshots_root=${result.screenshotsRoot}`,
@@ -333,7 +378,7 @@ runs:
         EOF
 
     - id: compare
-      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found == 'true'
+      if: steps.scope.outputs.should_run == 'true' && steps.capture.outputs.provider != 'skipped' && (steps.baseline.outputs.found == 'true' || steps.capture.outputs.provider == 'snap')
       shell: bash
       env:
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
@@ -343,22 +388,27 @@ runs:
         BASELINE_RUN_DIR: ${{ steps.baseline_paths.outputs.run_dir }}
         BASELINE_ARTIFACT_NAME: ${{ steps.baseline.outputs.artifact_name }}
         BASELINE_SOURCE_SHA: ${{ steps.baseline.outputs.head_sha }}
+        CURRENT_RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
+        CURRENT_MANIFEST_PATH: ${{ steps.capture.outputs.manifest_file }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
         import path from 'node:path';
         import { pathToFileURL } from 'node:url';
 
-        const compareModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/compare-results.mjs');
+        const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
         const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
-        const { runDriftCheckCli } = await import(pathToFileURL(compareModulePath));
-        const { splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { createProvider, SnapSkipError, SnapFallbackError } = await import(pathToFileURL(providerModulePath));
+        const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
+
+        const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+        const provider = createProvider(config.provider || 'local', config);
 
         const resolvedOutDir = path.resolve('qa-artifacts/snapdrift/drift/current');
         const resolvedSummaryPath = path.join(resolvedOutDir, 'summary.json');
         const resolvedMarkdownPath = path.join(resolvedOutDir, 'summary.md');
 
-        await runDriftCheckCli({
+        const diffOptions = {
           configPath: process.env.REPO_CONFIG_PATH || undefined,
           baselineResultsPath: process.env.BASELINE_RESULTS_PATH || undefined,
           baselineManifestPath: process.env.BASELINE_MANIFEST_PATH || undefined,
@@ -366,10 +416,34 @@ runs:
           routeIds: splitCommaList(process.env.ROUTE_IDS),
           baselineArtifactName: process.env.BASELINE_ARTIFACT_NAME || undefined,
           baselineSourceSha: process.env.BASELINE_SOURCE_SHA || undefined,
-          enforceOutcome: false
-        });
+          currentResultsPath: process.env.CURRENT_RESULTS_PATH || undefined,
+          currentManifestPath: process.env.CURRENT_MANIFEST_PATH || 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 { summary, markdown } = diffResult;
+
+        await fs.mkdir(resolvedOutDir, { recursive: true });
+        await Promise.all([
+          fs.writeFile(resolvedSummaryPath, JSON.stringify(summary, null, 2)),
+          fs.writeFile(resolvedMarkdownPath, markdown)
+        ]);
 
-        const summary = JSON.parse(await fs.readFile(resolvedSummaryPath, 'utf8'));
         const outputs = [
           `summary_path=${resolvedSummaryPath}`,
           `markdown_path=${resolvedMarkdownPath}`,
@@ -408,7 +482,7 @@ runs:
         EOF
 
     - id: skipped_baseline
-      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found != 'true'
+      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found != 'true' && steps.capture.outputs.provider != 'snap'
       shell: bash
       env:
         MESSAGE: ${{ steps.baseline.outputs.message }}
@@ -498,6 +572,7 @@ runs:
         SUMMARY_PATH: ${{ steps.compare.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 }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
         MAX_ERROR_ROWS: ${{ inputs.max-error-rows }}
       with:
@@ -531,13 +606,25 @@ runs:
             return;
           }
 
-          const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
-          const { buildReportCommentBody } = await import(pathToFileURL(modulePath));
+          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 } = await import(pathToFileURL(providerModulePath));
+          const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+
+          // Provider-loading block duplicated in actions/comment/action.yml — keep in sync.
+          let provider;
+          try {
+            const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+            provider = createProvider(config.provider || 'local', config);
+          } catch (err) {
+            core.warning(`Could not load SnapDrift config; falling back to LocalProvider. ${err.message}`);
+            provider = createProvider('local');
+          }
 
           const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
           const maxChangedRows = Number(process.env.MAX_CHANGED_ROWS) || 20;
           const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
-          const body = buildReportCommentBody(summary, {
+          const body = provider.buildCommentBody(summary, {
             artifactName: process.env.ARTIFACT_NAME || '',
             runUrl: process.env.RUN_URL || '',
             maxChangedRows,
@@ -583,7 +670,7 @@ runs:
             });
           }
 
-    - if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found == 'true'
+    - if: steps.scope.outputs.should_run == 'true' && steps.capture.outputs.provider != 'skipped' && (steps.baseline.outputs.found == 'true' || steps.capture.outputs.provider == 'snap')
       shell: bash
       run: |
         node --input-type=module <<'EOF'

package/actions/scope/action.yml

@@ -40,6 +40,15 @@ runs:
       shell: bash
       run: echo "ACTION_ROOT=$(cd "$GITHUB_ACTION_PATH/../.." && pwd)" >> "$GITHUB_ENV"
 
+    - name: Set up Node.js
+      uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      with:
+        node-version: '22'
+
+    - name: Install action dependencies
+      shell: bash
+      run: npm ci --prefix "$ACTION_ROOT"
+
     - id: scope
       uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
       env: