snapdrift 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 ## Unreleased
 
+## 0.16.0 - 2026-10-05
+
+Workspace releases this version:
+
+- `@snapdrift/manifest` 1.8.0 — capture engine configuration (`capture: "playwright" | "snap"`) under `provider: "local"`, export `isLocalBaseUrl`, and recognize `snap-batch` capture profile engine.
+- `@snapdrift/adapter-fs` 1.7.0 — Snap Cloud batch screenshot capture engine (`runSnapBatchCapture`) using POST `/v1/screenshots`, capture engine delegation in `runBaselineCapture`, and `isLocalBaseUrl` re-export.
+
+`@snapdrift/compare-core` stays 1.6.0 and `@snapdrift/adapter-report-md` stays 1.4.0. Root floors move to `@snapdrift/manifest ^1.8.0` and `@snapdrift/adapter-fs ^1.7.0`. The dispatcher pins `8e82795`, the #191 merge commit on `main`, which includes skipping Playwright installation in composite actions when `capture: "snap"` with a remote `baseUrl`.
+
+### Features
+
+- Added Snap Cloud batch screenshot capture engine (`capture: "snap"`) under `provider: "local"`. Dispatches route screenshots concurrently to Snap Cloud's batch screenshot API (`POST /v1/screenshots`), saving significant CI run time by offloading browser execution.
+- Added automatic Playwright setup skipping in composite actions (`actions/baseline` and `actions/pr-diff`) when `capture: "snap"` is configured with a remote `baseUrl`, avoiding unnecessary browser binary downloads.
+- Supported `SNAPDRIFT_CAPTURE_ENGINE` environment variable (`playwright` | `snap`) to override the configured capture engine at runtime.
+- Added actionable validation rejecting loopback and local `baseUrl` (`localhost`, `127.0.0.1`, `::1`) when `capture: "snap"` is used, directing users to use `playwright` or tunnel services.
+- Added capture profile engine validation in `@snapdrift/manifest` to recognize `snap-batch` and prevent comparing local Playwright captures against Snap Cloud batch captures.
+- Added resilient batch capture polling with retries on transient errors (HTTP 429, 5xx on GET status polls, network errors) while safely avoiding POST retries on 5xx to prevent duplicate jobs.
+
+## 0.15.0 - 2026-09-22
+
+Workspace releases this version:
+
+- `@snapdrift/compare-core` 1.6.0 — vertical-offset alignment when exact row
+  matching hits its edit cap, including alpha-aware highlighting and the
+  search memory caps.
+- `@snapdrift/manifest` 1.7.0 — `comparedOffset` on comparison row mappings.
+- `@snapdrift/adapter-fs` 1.6.0 — depends on that compare-core so local policy
+  v2 comparisons use the offset-run engine.
+
+`@snapdrift/adapter-report-md` stays 1.4.0. Root floors move to
+`@snapdrift/compare-core ^1.6.0`, `@snapdrift/manifest ^1.7.0`, and
+`@snapdrift/adapter-fs ^1.6.0`. The dispatcher pins `7b7b913`, the #179 merge
+commit on `main`, which contains the offset-run runtime loaded by both wrapper
+actions.
+
+### Features
+
+- Comparison policy v2, after exact row alignment hits its edit cap, maps long
+  vertical-offset runs so an insertion does not highlight the rest of a shifted
+  page. A matched row on that path was mapped and fell below the highlight
+  rule; it does not have to be byte-identical. When the compared row is one
+  pixel above or below the recorded current row, the mapping includes
+  `comparedOffset` (`-1` or `1`).
+- Offset highlighting includes alpha. Scoring ignores fully transparent pixels
+  and treats a large opacity change as a structured mismatch, so a small alpha
+  delta stays on the offset path.
+- The offset search rejects a page before allocating its score matrices when
+  those matrices would exceed 64 MB. It also samples every 32nd row first and
+  stops that sample once the page cannot be a correspondence, so a dissimilar
+  page falls back without scoring every offset. A dissimilar 1440×5622 pair
+  fell back in about 0.9s; scoring every offset on that pair took about 3.5s.
+- An offset canvas that would exceed `maxPixels` falls back to coordinate
+  comparison instead of throwing. The coordinate union can still throw when it
+  itself exceeds the limit.
+
 ## 0.14.0 - 2026-09-21
 
 Workspace releases this version:

package/README.md

@@ -48,7 +48,7 @@ You keep ownership of checkout, build, startup, readiness, and teardown. SnapDri
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift@v0.14.0
+  uses: ranacseruet/snapdrift@v0.16.0
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
@@ -60,7 +60,7 @@ With `provider: "snap"`, baseline publication is a complete, fail-closed snapsho
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.14.0
+  uses: ranacseruet/snapdrift@v0.16.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}

package/action.yml

@@ -155,7 +155,7 @@ runs:
     - name: SnapDrift baseline
       id: baseline
       if: inputs.mode == 'baseline'
-      uses: ranacseruet/snapdrift/actions/baseline@576e774845c29288a0061365e4905009533e0e01 # v0.14.0
+      uses: ranacseruet/snapdrift/actions/baseline@8e827952c33415ba2d8f1fdab944d519534013a6 # v0.16.0
       with:
         repo-config-path: ${{ inputs.repo-config-path }}
         route-ids: ${{ inputs.route-ids }}
@@ -165,7 +165,7 @@ runs:
     - name: SnapDrift pull request diff
       id: pr-diff
       if: inputs.mode == 'pr-diff'
-      uses: ranacseruet/snapdrift/actions/pr-diff@576e774845c29288a0061365e4905009533e0e01 # v0.14.0
+      uses: ranacseruet/snapdrift/actions/pr-diff@8e827952c33415ba2d8f1fdab944d519534013a6 # v0.16.0
       with:
         github-token: ${{ inputs.github-token }}
         repo-config-path: ${{ inputs.repo-config-path }}

package/actions/baseline/action.yml

@@ -78,14 +78,16 @@ runs:
         const outputs = [
           `artifact_name=${config.baselineArtifactName}`,
           `provider=${config.provider || 'local'}`,
+          `capture_engine=${process.env.SNAPDRIFT_CAPTURE_ENGINE || config.capture || 'playwright'}`,
           `on_unavailable=${config.snap?.onUnavailable || 'fail'}`,
-          `snap_local_capture=${(config.provider || 'local') === 'snap' && isLocalBaseUrl(config.baseUrl) ? 'true' : 'false'}`
+          `snap_local_capture=${(config.provider || 'local') === 'snap' && isLocalBaseUrl(config.baseUrl) ? 'true' : 'false'}`,
+          `is_local_base_url=${isLocalBaseUrl(config.baseUrl) ? 'true' : 'false'}`
         ].join('\n') + '\n';
         await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
         EOF
 
     - name: Install Playwright Chromium
-      if: steps.config.outputs.provider != 'snap' || steps.config.outputs.on_unavailable == 'fallback-local' || steps.config.outputs.snap_local_capture == 'true'
+      if: (steps.config.outputs.provider != 'snap' && (steps.config.outputs.capture_engine != 'snap' || steps.config.outputs.is_local_base_url == 'true')) || 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

package/actions/pr-diff/action.yml

@@ -251,8 +251,10 @@ runs:
         const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
         const outputs = [
           `provider=${config.provider || 'local'}`,
+          `capture_engine=${process.env.SNAPDRIFT_CAPTURE_ENGINE || config.capture || 'playwright'}`,
           `on_unavailable=${config.snap?.onUnavailable || 'fail'}`,
-          `snap_local_capture=${(config.provider || 'local') === 'snap' && isLocalBaseUrl(config.baseUrl) ? 'true' : 'false'}`
+          `snap_local_capture=${(config.provider || 'local') === 'snap' && isLocalBaseUrl(config.baseUrl) ? 'true' : 'false'}`,
+          `is_local_base_url=${isLocalBaseUrl(config.baseUrl) ? 'true' : 'false'}`
         ].join('\n') + '\n';
         await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
         EOF
@@ -268,7 +270,7 @@ runs:
         exit 1
 
     - name: Install Playwright Chromium
-      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')
+      if: steps.scope.outputs.should_run == 'true' && ((steps.config.outputs.provider != 'snap' && (steps.config.outputs.capture_engine != 'snap' || steps.config.outputs.is_local_base_url == 'true')) || 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

package/docs/contracts.md

@@ -32,6 +32,7 @@ SnapDrift reads runtime behavior from `.github/snapdrift.json` by default.
 
 | Field | Type | Description |
 |:------|:-----|:------------|
+| `capture` | `string` | Capture engine for `provider: "local"`: `"playwright"` (default) or `"snap"` (Snap Cloud batch screenshot API) |
 | `selection.sharedPrefixes` | `string[]` | Prefixes that force the full route set |
 | `selection.sharedExact` | `string[]` | Exact files that force the full route set |
 | `provider` | `string` | `"local"` (default) or `"snap"` for hosted backend |
@@ -42,6 +43,8 @@ SnapDrift reads runtime behavior from `.github/snapdrift.json` by default.
 | `snap.onUnavailable` | `string` | Behavior when Snap is unreachable: `"fail"` (default), `"warn-and-skip"`, or `"fallback-local"` |
 | `diff.comparisonPolicy` | `{ "version": 1 \| 2, "threshold": number }` | Optional explicit comparison policy. Deprecated v1 remains the compatibility default; new configurations should use v2 for bounded vertical row alignment. `threshold` must match `diff.threshold` |
 
+When `capture: "snap"` is set (or overridden via `SNAPDRIFT_CAPTURE_ENGINE=snap`), SnapDrift routes baseline and diff captures to Snap Cloud's batch screenshot API (`POST /v1/screenshots`) instead of launching local Chromium via Playwright. Rendered PNGs are downloaded in parallel and diffed locally via `@snapdrift/compare-core`. This requires a public or preview `baseUrl` (loopback and private network URLs like `localhost`, `127.0.0.1`, `::1` are rejected) and an API key (configured in `snap.apiKeyEnv` / `snap.apiKey` or via `SNAP_API_KEY`). When `capture: "snap"` is used with a remote `baseUrl`, GitHub Actions wrapper actions (`actions/baseline`, `actions/pr-diff`) skip the `playwright install --with-deps chromium` step, accelerating CI workflows.
+
 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.
 
 Changed-file scoping treats a GitHub `renamed` record as both the current
@@ -293,10 +296,14 @@ the diff output bundle (for example `diffs/home.png`).
 Policy v2 comparison metadata additionally includes `policyVersion: 2` and
 `mode`. An aligned result has `mode: "vertical-aligned"` and a compact
 `rowMapping` describing matched, changed, inserted, and deleted row runs. A
-`mode: "coordinate-fallback"` result includes `fallbackReason` when widths,
-ignore regions, ambiguity, or the alignment resource limit prevent safe row
-alignment. The aligned canvas may be taller than either source image because
-inserted and deleted rows each occupy an output row.
+matched offset-run was mapped and fell below the highlight rule, so its rows
+need not be byte-identical. A segment may include `comparedOffset` of `-1` or
+`1` when the compared current row is one pixel away from `currentStart`; output
+row `i` was compared to current row `currentStart + i + comparedOffset`. A `mode: "coordinate-fallback"` result
+includes `fallbackReason` when widths, ignore regions, ambiguity, or the
+alignment resource limit prevent safe row alignment. The aligned canvas may be
+taller than either source image because inserted and deleted rows each occupy
+an output row.
 
 When a changed item has a generated local `diffImagePath`, its PR comment cell
 links to the uploaded report artifact (or the workflow run when no artifact URL
@@ -332,7 +339,7 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 - `diff.threshold` applies per screenshot
 - Missing captures are counted separately from drift signals
 - Comparison policy v1 `{ "version": 1, "threshold": number }` is deprecated but remains the compatibility default. Images are top-left aligned on a max-dimension union canvas with no scaling. Overlap pixels are compared, one-sided pixels count as changed (including transparent pixels), and empty union corners do not enter the denominator.
-- Comparison policy v2 `{ "version": 2, "threshold": number }` is opt-in. When source widths match and no ignore regions are requested, rows are fingerprinted and aligned with a bounded Myers sequence diff. Unchanged content that moves after an insertion/deletion remains matched; inserted current rows are green, deleted baseline rows are red, and actual pixel edits are orange. Width changes, ignore regions, ambiguous row matches, and resource limits fall back to v1 coordinate comparison and record the fallback reason. This is a raster row alignment aid, not DOM or arbitrary component matching.
+- Comparison policy v2 `{ "version": 2, "threshold": number }` is opt-in. When source widths match and no ignore regions are requested, rows are fingerprinted and aligned with a bounded Myers sequence diff. If that search hits its edit cap, long vertical-offset runs are mapped instead. Inside a run, a row may be compared one pixel above or below the recorded current row when that neighbor matches. `currentStart` still consumes each current row once, so that neighbor is not a separate insertion or deletion. When the compared row differs, the segment includes `comparedOffset` of `-1` or `1`: output row `i` was compared to current row `currentStart + i + comparedOffset`. On that offset-run path, a pixel whose red, green, blue, or alpha channel differs by 32 or less stays unhighlighted, so rendering noise and soft edges remain matched. A short cluster of larger channel deltas is an orange edit. A wide band of those pixels is a local mismatch: it is highlighted in place and does not discard the rest of the page. Unmatched baseline rows are red deletions. Current rows with no baseline partner are green insertions. `matched` on this path means the row was mapped and fell below this highlight rule. Exact fingerprint matches remain byte-identical. Width changes, ignore regions, ambiguous exact-row matches, and resource limits fall back to v1 coordinate comparison and record the fallback reason. This is a raster row alignment aid, not DOM or arbitrary component matching.
 - Both policies preserve the explicit dimension-change signal: a source height/width change remains a changed route even when the aligned mismatch ratio is at or below the threshold. Empty output corners do not enter the denominator.
 - Local diff images are rendered with a semantic palette: orange = changed pixels, green = added or inserted pixels, red = removed or deleted pixels. Equal-dimension strict diffs (`generateDiffImage`) use orange for changed pixels and cannot contain added/removed pixels. Reports render a legend whenever a local diff image is embedded; summaries that carry only comparison metadata (Snap provider runs, which render diffs hosted-side) render no legend.
 - `dimensionChanges[]` remains part of the summary contract but is empty for local comparisons in v1. Strict same-dimension comparison (`compareBuffers`) remains available to direct `@snapdrift/compare-core`/`comparePngs` callers that pass no policy.

package/docs/integration-guide.md

@@ -46,7 +46,7 @@ SnapDrift owns route selection, capture, comparison, skipped-report generation,
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift@v0.14.0
+  uses: ranacseruet/snapdrift@v0.16.0
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
@@ -71,7 +71,7 @@ Then add SnapDrift after the app is running:
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.14.0
+  uses: ranacseruet/snapdrift@v0.16.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -86,8 +86,8 @@ The wrappers remain published in their own right, and are equivalent to the disp
 
 | Entry point | Equivalent to |
 |-------------|---------------|
-| `ranacseruet/snapdrift@v0.14.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.14.0` |
-| `ranacseruet/snapdrift@v0.14.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.14.0` |
+| `ranacseruet/snapdrift@v0.16.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.16.0` |
+| `ranacseruet/snapdrift@v0.16.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.16.0` |
 
 Use the wrappers directly when you want to skip the dispatcher's input indirection, and the lower-level `capture`, `compare`, `scope`, `resolve-baseline`, `stage`, `comment`, and `enforce` actions when you need to orchestrate the stages yourself.
 
@@ -130,7 +130,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.14.0
+        uses: ranacseruet/snapdrift@v0.16.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -170,7 +170,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.14.0
+        uses: ranacseruet/snapdrift@v0.16.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -270,6 +270,32 @@ If you're adopting SnapDrift as a replacement for the upstream `snap/github-acti
 snapdrift init --from-snap-action .github/workflows/snap.yml
 ```
 
+## Fast CI with Snap Cloud Batch Screenshots (`capture: "snap"`)
+
+When your application deploys preview URLs (e.g., Vercel, Netlify, Cloudflare Pages, AWS Amplify) or runs on a publicly accessible staging server during CI, you can offload screenshot rendering to Snap Cloud while keeping comparison and artifact management local (`provider: "local"`):
+
+```json
+{
+  "baseUrl": "https://preview-pr-123.example.com",
+  "capture": "snap",
+  "snap": {
+    "apiKeyEnv": "SNAP_API_KEY"
+  },
+  "routes": [
+    { "id": "home-desktop", "path": "/", "viewport": "desktop" },
+    { "id": "pricing-desktop", "path": "/pricing", "viewport": "desktop" }
+  ]
+}
+```
+
+### Why use `capture: "snap"`?
+- **Skips Playwright Installation in CI:** The GitHub Actions wrapper actions (`actions/baseline` and `actions/pr-diff`) detect `capture: "snap"` with a remote `baseUrl` and skip `playwright install --with-deps chromium`, saving 45–90 seconds per workflow run.
+- **Parallel Cloud Rendering:** Snap Cloud renders full-page screenshots concurrently via its batch API (`POST /v1/screenshots`).
+- **Local Diff Engine:** Screenshots are downloaded and diffed locally on the runner with `@snapdrift/compare-core`, keeping full artifact bundles and PR comments in GitHub Actions without requiring hosted project configuration.
+
+> [!NOTE]
+> `capture: "snap"` requires a public or preview URL reachable by Snap Cloud. If `baseUrl` points to `localhost` or `127.0.0.1`, SnapDrift will fail with a clear configuration error because Snap Cloud cannot access loopback addresses. For local development or local dev servers, use `capture: "playwright"` (the default).
+
 ## Low-level actions
 
 The `pr-diff` wrapper composes the following low-level steps. They're still available for custom orchestration but most consumers don't need to reach for them:

package/docs/plans/2026-10-05-snap-cloud-batch-capture-design.md

@@ -0,0 +1,147 @@
+# Design Specification: Snap Cloud Batch Screenshot Capture Engine
+
+**Date:** 2026-10-05  
+**Status:** Approved  
+**Author:** Pair programming session (Antigravity & Rana)
+
+---
+
+## 1. Context & Motivation
+
+SnapDrift currently offers two provider workflows:
+1. **`provider: "local"`**: Executes Playwright locally on the runner to capture screenshots into PNGs, then runs pure-JS pixel comparison (`@snapdrift/compare-core`) and stores baselines in GitHub Actions artifacts.
+2. **`provider: "snap"`**: Connects to Snap Cloud's Visual Regression service (`/v1/visual/*`), requiring a Snap project ID and hosted baseline management.
+
+In CI workflows using `provider: "local"`, the primary speed bottleneck is running Playwright on the runner:
+- Downloading and installing Chromium and OS dependencies (`playwright install --with-deps chromium`) adds 45–90 seconds per CI job.
+- Headless rendering on limited CI runner CPU/RAM slows down capture of multi-route configurations.
+
+Snap Cloud provides a public Batch Screenshot API (`POST /v1/screenshots` with `items: [...]`) capable of asynchronously capturing up to 50 URLs in parallel on hosted render workers and returning signed image URLs.
+
+By adding a pluggable **Snap Cloud batch capture engine** to `provider: "local"`, repositories with public or preview URLs can offload screenshot rendering to Snap Cloud, skip Playwright installation in CI entirely, and continue using GitHub Actions for zero-setup baseline storage, diffing, and PR commenting.
+
+---
+
+## 2. Configuration Contract
+
+In `.github/snapdrift.json` (or inline config):
+
+```json
+{
+  "provider": "local",
+  "capture": "snap",
+  "baseUrl": "https://preview.example.com",
+  "routes": [
+    { "id": "home", "path": "/", "viewport": "desktop" },
+    { "id": "pricing", "path": "/pricing", "viewport": "mobile" }
+  ]
+}
+```
+
+### Schema Rules
+- **`capture`**: Optional string. Allowed values: `"playwright"` (default) | `"snap"`. Overridable via `SNAPDRIFT_CAPTURE_ENGINE` environment variable.
+- **Authentication**: When `capture: "snap"`, authentication uses `process.env.SNAP_API_KEY`. No project ID is required.
+- **API URL**: Defaults internally to `https://snap.i2dev.com`.
+- **Base URL Validation**:
+  - `isLocalBaseUrl(config.baseUrl)` evaluates loopback addresses (`localhost`, `127.0.0.1`, `::1`, `0.0.0.0`).
+  - If `baseUrl` is local and `capture: "snap"` is configured:
+    - In CLI/local development, if Playwright is available, it gracefully falls back to local Playwright with a notice, or errors if unresolvable.
+    - In CI workflows targeting public preview deployments, `baseUrl` is remote and Snap Cloud batch capture executes.
+
+---
+
+## 3. Data Flow & Batch Lifecycle
+
+```
+[Selected Routes]
+       │
+       ▼
+1. Map routes to batch items (url, viewport)
+       │
+       ▼
+2. POST https://snap.i2dev.com/v1/screenshots (Bearer SNAP_API_KEY)
+   Body: { format: "png", fullPage: true, items: [...] }
+       │
+       ▼ Returns { batchId, status: "queued", statusUrl }
+3. Poll GET /v1/screenshots/:batchId every 1.5s
+       │
+       ▼ status: "completed"
+4. Download PNGs in parallel from item.imageUrl -> screenshots/<sanitizedRouteId>.png
+       │
+       ▼
+5. Inspect image dimensions and write results.json & manifest.json
+       │
+       ▼
+6. Run local pixel comparison (@snapdrift/compare-core)
+```
+
+### Route & Viewport Mapping
+- Viewports are resolved via `@snapdrift/manifest` presets:
+  - `"desktop"` → `{ width: 1440, height: 900 }`
+  - `"mobile"` → `{ width: 390, height: 844 }`
+  - Custom objects `{ width, height }` are passed directly.
+- Full target URLs are constructed via `new URL(route.path, config.baseUrl).href`.
+
+### Polling & Timeout
+- Poll interval: 1.5 seconds.
+- Monotonic operation deadline: 5 minutes.
+- Stops when `status === "completed"`.
+
+### Artifact Generation
+- Downloaded PNGs are written to `<screenshotsRoot>/screenshots/<sanitizedRouteId>.png`.
+- Output structure matches `runBaselineCapture`:
+  - `manifest.json`: lists screenshots with route id, path, viewport, relative imagePath, and dimensions.
+  - `results.json`: records capture metadata with engine `snap-batch`.
+
+---
+
+## 4. Error Handling & Resilience
+
+1. **Individual Route Failure in Batch**:
+   - Snap Cloud returns batches even if some URLs fail (`status: "failed"` on specific items).
+   - SnapDrift adheres to its strict baseline contract: any navigation error or HTTP failure rejects the capture to prevent committing broken states.
+   - Halts immediately with: `Route "<id>" failed cloud capture: <error.message> (<error.code>)`.
+2. **Authentication (401)**:
+   - Fails fast with: `Missing or invalid SNAP_API_KEY for Snap Cloud batch screenshot capture.`
+3. **Transient Server Errors (5xx)**:
+   - Retries up to 3 times with exponential backoff (1s, 2s, 4s).
+4. **Rate Limits (429)**:
+   - Honors `Retry-After` header when available. Surfaces quota exhaustion errors clearly.
+5. **Private Addresses (400 `unsafe_url`)**:
+   - Prevented ahead of time via early `isLocalBaseUrl` check.
+
+---
+
+## 5. GitHub Actions Optimization
+
+In `actions/baseline/action.yml` and `actions/pr-diff/action.yml`:
+Playwright installation is skipped when `capture: "snap"` and `baseUrl` is remote:
+
+```yaml
+- name: Install Playwright Chromium
+  if: >
+    steps.scope.outputs.should_run == 'true' &&
+    (
+      (steps.config.outputs.provider == 'local' && steps.config.outputs.capture_engine != 'snap') ||
+      steps.config.outputs.snap_local_capture == 'true' ||
+      steps.config.outputs.on_unavailable == 'fallback-local'
+    )
+```
+
+This cuts CI setup time by 45–90 seconds per run on pull requests.
+
+---
+
+## 6. Testing Strategy
+
+1. **`@snapdrift/manifest` Tests**:
+   - Validate `capture` field (`"playwright"`, `"snap"`).
+   - Rejection of invalid capture engine strings.
+2. **`@snapdrift/adapter-fs` Tests**:
+   - Unit tests for `runSnapBatchCapture` with mocked HTTP responses:
+     - Successful batch submission, polling cycle, and image download.
+     - Propagation of single-item failure in batch.
+     - Handling 401, 429, and 5xx retries.
+     - Verification of output `manifest.json`, `results.json`, and file paths.
+3. **Action Contract Tests**:
+   - Verify composite action YAML outputs and Playwright installation condition logic.

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

@@ -82,7 +82,7 @@ jobs:
 
       - name: Publish SnapDrift baseline
         if: steps.baseline_candidate.outputs.current == 'true'
-        uses: ranacseruet/snapdrift@v0.14.0
+        uses: ranacseruet/snapdrift@v0.16.0
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json

package/lib/capture-routes.mjs

@@ -1,4 +1,4 @@
 // @ts-check
 // Re-exports from packages — this module is a thin shim.
 
-export { runBaselineCapture } from '@snapdrift/adapter-fs';
+export { runBaselineCapture, runSnapBatchCapture } from '@snapdrift/adapter-fs';

package/lib/snap-provider.mjs

@@ -4,7 +4,6 @@ import { execFileSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
-import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -18,7 +17,8 @@ import {
   VIEWPORT_PRESETS,
   viewportHash,
   assertUniqueRouteIdFilenames,
-  sanitizeRouteId
+  sanitizeRouteId,
+  isLocalBaseUrl
 } from '@snapdrift/manifest';
 
 /** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
@@ -226,6 +226,13 @@ function isComparisonMetadata(value) {
     }
     if (hasBaseline && (segment.baselineStart < 0 || segment.baselineStart + segment.length > baseline.height)) return false;
     if (hasCurrent && (segment.currentStart < 0 || segment.currentStart + segment.length > current.height)) return false;
+    if (segment.comparedOffset !== undefined) {
+      if (!hasBaseline || !hasCurrent || (segment.comparedOffset !== -1 && segment.comparedOffset !== 0 && segment.comparedOffset !== 1)) {
+        return false;
+      }
+      const comparedStart = segment.currentStart + segment.comparedOffset;
+      if (comparedStart < 0 || comparedStart + segment.length > current.height) return false;
+    }
     outputStart += segment.length;
     if (hasBaseline) baselineStart += segment.length;
     if (hasCurrent) currentStart += segment.length;
@@ -558,31 +565,7 @@ function baselineIdForRun(runId) {
   return `bsl_${crypto.createHash('sha256').update(runId).digest('hex').slice(0, 24)}`;
 }
 
-/**
- * @param {string | undefined} baseUrl
- * @returns {boolean}
- */
-export function isLocalBaseUrl(baseUrl) {
-  if (!baseUrl) {
-    return false;
-  }
-
-  let hostname;
-  try {
-    hostname = new URL(baseUrl).hostname.toLowerCase();
-  } catch {
-    return false;
-  }
-
-  const normalized = hostname.replace(/^\[/, '').replace(/\]$/, '');
-  if (normalized === 'localhost' || normalized.endsWith('.localhost')) {
-    return true;
-  }
-  if (normalized === '::1' || normalized === '0.0.0.0') {
-    return true;
-  }
-  return net.isIP(normalized) === 4 && normalized.startsWith('127.');
-}
+export { isLocalBaseUrl };
 
 /**
  * @param {string} repoSlug

package/lib/snapdrift-config.mjs

@@ -12,7 +12,9 @@ export {
   splitCommaList,
   VALID_DIFF_MODES,
   VALID_PROVIDER_VALUES,
-  VALID_ON_UNAVAILABLE_MODES
+  VALID_CAPTURE_ENGINES,
+  VALID_ON_UNAVAILABLE_MODES,
+  isLocalBaseUrl
 } from '@snapdrift/manifest';
 
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",
@@ -103,10 +103,10 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@snapdrift/adapter-fs": "^1.5.0",
+    "@snapdrift/adapter-fs": "^1.7.0",
     "@snapdrift/adapter-report-md": "^1.4.0",
-    "@snapdrift/compare-core": "^1.5.0",
-    "@snapdrift/manifest": "^1.6.0",
+    "@snapdrift/compare-core": "^1.6.0",
+    "@snapdrift/manifest": "^1.8.0",
     "js-yaml": "^5.4.0",
     "playwright": "^1.59.1",
     "pngjs": "^7.0.0"

package/types/visual-diff-types.d.ts

@@ -55,6 +55,12 @@ export interface ComparisonRowMapping {
   kind: ComparisonRowKind;
   baselineStart?: number;
   currentStart?: number;
+  /**
+   * Present when an offset-run row was compared one pixel above or below the
+   * recorded current row. Output row i was compared to current row
+   * `currentStart + i + comparedOffset`.
+   */
+  comparedOffset?: -1 | 0 | 1;
 }
 
 export interface VisualRegressionRouteConfig {
@@ -81,6 +87,7 @@ export interface VisualRegressionConfig {
   };
   selection?: VisualRegressionSelectionConfig;
   provider?: 'local' | 'snap';
+  capture?: 'playwright' | 'snap';
   snap?: SnapConfig;
 }
 
@@ -121,6 +128,7 @@ export interface VisualBaselineResults {
   screenshotsRoot?: string;
   routes: VisualBaselineRouteResult[];
   passed?: boolean;
+  engine?: string;
 }
 
 /** Exact route/viewport capture identity persisted for hosted baseline validation. */