snapdrift 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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

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

@@ -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"
+
     - uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
       env:
         VISUAL_DIFF_SUMMARY_PATH: ${{ inputs.summary-path }}

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 }}
@@ -596,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:

package/docs/contracts.md

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