snapdrift 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 ## Unreleased
 
+## 0.16.1 - 2026-10-27
+
+Workspace releases this version:
+
+- `@snapdrift/compare-core` 1.7.0 — new public `readPngDimensions` export (PNG IHDR width/height without decoding pixels).
+- `@snapdrift/adapter-fs` 1.7.1 — local capture reads screenshot dimensions from the PNG header instead of fully decoding every PNG, and now depends on `@snapdrift/compare-core ^1.7.0` for that reader.
+
+`@snapdrift/manifest` stays 1.8.0 and `@snapdrift/adapter-report-md` stays 1.4.0. Root floors move to `@snapdrift/compare-core ^1.7.0` and `@snapdrift/adapter-fs ^1.7.1`; the previous `adapter-fs` 1.7.0 and `compare-core` 1.6.0 do not satisfy them, so installing `snapdrift` 0.16.1 always gets the shared reader. The dispatcher pins `1cbf629`, the #195 merge commit on `main`, which is the newest commit touching `actions/` and includes the shell-only Playwright install.
+
+### Performance
+
+- Hybrid (`provider: "snap"` with a local `baseUrl`) capture uploads screenshots to Snap with up to 4 routes in flight instead of one at a time, and stops starting new uploads after the first failure.
+- The latest-baseline lookup for hybrid diff runs now starts before local capture and overlaps with it.
+- Local Playwright capture reads screenshot width/height from the PNG header instead of fully decoding every PNG, which no longer blocks the event loop for all in-flight routes. A corrupt PNG body is no longer detected at capture time; a buffer without a valid PNG signature or IHDR chunk still fails the route.
+- GitHub Actions install only Playwright's Chromium headless shell (`playwright install --with-deps --only-shell chromium`) instead of full Chromium plus the shell. Capture already launches with `headless: true`, which uses the shell, so rendering is unchanged. Measured on `node:22-bookworm` with Playwright 1.63.0: install 22s -> 15s, browser cache 662 MB -> 269 MB, identical browser version and screenshot bytes.
+- Capture and upload phases log their duration (`Captured N route(s) in Xs`, `Uploaded N screenshot(s) to Snap in Xs`).
+
+### Features
+
+- `@snapdrift/compare-core` exports `readPngDimensions(buffer)`, which reads width/height from a PNG's IHDR chunk without decoding pixels and returns `undefined` for a buffer that is too short, lacks the PNG signature, does not start with IHDR, or declares a zero or above-2^31-1 dimension.
+
+### Refactors
+
+- Local capture (`@snapdrift/adapter-fs`) and the Snap baseline export (`lib/snap-provider.mjs`) now use the shared `readPngDimensions` instead of their own copies. The Snap baseline export is slightly stricter than before: an exported image whose header is not a valid IHDR (or declares a zero dimension) falls back to the viewport descriptor's dimensions instead of being recorded with the header's values. Requires the `@snapdrift/compare-core` release that adds the export; dependency floors are raised at release time. Closes #194.
+
+## 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:

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.15.0
+  uses: ranacseruet/snapdrift@v0.16.1
   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.15.0
+  uses: ranacseruet/snapdrift@v0.16.1
   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@7b7b9138416fd16631c5d648b2ddfa9fe4a6a783 # v0.15.0
+      uses: ranacseruet/snapdrift/actions/baseline@1cbf62965475bc856218ce46eb46dccf7c05326f # v0.16.1
       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@7b7b9138416fd16631c5d648b2ddfa9fe4a6a783 # v0.15.0
+      uses: ranacseruet/snapdrift/actions/pr-diff@1cbf62965475bc856218ce46eb46dccf7c05326f # v0.16.1
       with:
         github-token: ${{ inputs.github-token }}
         repo-config-path: ${{ inputs.repo-config-path }}

package/actions/baseline/action.yml

@@ -78,17 +78,19 @@ 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
+        "$ACTION_ROOT/node_modules/.bin/playwright" install --with-deps --only-shell chromium
 
     - id: capture
       shell: bash

package/actions/capture/action.yml

@@ -48,7 +48,7 @@ runs:
     - name: Install Playwright Chromium
       shell: bash
       run: |
-        "$ACTION_ROOT/node_modules/.bin/playwright" install --with-deps chromium
+        "$ACTION_ROOT/node_modules/.bin/playwright" install --with-deps --only-shell chromium
 
     - id: capture
       shell: bash

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,10 +270,10 @@ 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
+        "$ACTION_ROOT/node_modules/.bin/playwright" install --with-deps --only-shell chromium
 
     - id: capture
       if: steps.scope.outputs.should_run == 'true'

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 --only-shell 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
@@ -550,6 +553,8 @@ Publication sends `publicationMode: "complete"` and the source run id both as to
 
 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.
 
+In the hybrid path, the latest-baseline lookup for diff runs starts before local capture so it overlaps with rendering, and the per-route capture-create and `local-result` uploads run with up to 4 routes in flight. The first failed upload stops further uploads and fails the capture. Local screenshot dimensions come from the PNG header (signature and IHDR are validated; pixel data is not decoded at capture time).
+
 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

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.15.0
+  uses: ranacseruet/snapdrift@v0.16.1
   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.15.0
+  uses: ranacseruet/snapdrift@v0.16.1
   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.15.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.15.0` |
-| `ranacseruet/snapdrift@v0.15.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.15.0` |
+| `ranacseruet/snapdrift@v0.16.1` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.16.1` |
+| `ranacseruet/snapdrift@v0.16.1` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.16.1` |
 
 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.15.0
+        uses: ranacseruet/snapdrift@v0.16.1
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -170,7 +170,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.15.0
+        uses: ranacseruet/snapdrift@v0.16.1
         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 --only-shell 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.15.0
+        uses: ranacseruet/snapdrift@v0.16.1
         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,13 +4,12 @@ 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';
 
 import { makeMarkdown, buildReportCommentBody } from '@snapdrift/adapter-report-md';
 import { loadSnapdriftConfig, runBaselineCapture } from '@snapdrift/adapter-fs';
-import { COMPARISON_FALLBACK_REASONS, COMPARISON_ROW_KINDS } from '@snapdrift/compare-core';
+import { COMPARISON_FALLBACK_REASONS, COMPARISON_ROW_KINDS, readPngDimensions } from '@snapdrift/compare-core';
 import {
   selectConfiguredRoutes,
   splitCommaList,
@@ -18,7 +17,8 @@ import {
   VIEWPORT_PRESETS,
   viewportHash,
   assertUniqueRouteIdFilenames,
-  sanitizeRouteId
+  sanitizeRouteId,
+  isLocalBaseUrl
 } from '@snapdrift/manifest';
 
 /** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
@@ -47,6 +47,9 @@ const BINARY_REQUEST_TIMEOUT_MS = 120 * 1000;
 const POLL_INTERVAL_MS = 2000;
 const MAX_OPERATION_DURATION_MS = 10 * 60 * 1000;
 const MAX_STABLE_INCOMPLETE_POLLS = 30;
+// Local-capture uploads are independent per route; a small pool hides round-trip
+// latency without flooding the API or holding many base64 images in memory.
+const LOCAL_UPLOAD_CONCURRENCY = 4;
 const BASELINE_RUN_SUCCESS_STATUS = 'new';
 const BASELINE_CAPTURE_SUCCESS_STATUS = 'new';
 const TERMINAL_CAPTURE_STATUSES = new Set(['new', 'diffed', 'error']);
@@ -64,6 +67,35 @@ function formatDuration(milliseconds) {
   return `${seconds} seconds`;
 }
 
+/**
+ * Runs `task` over `items` with at most `limit` in flight. Stops starting new
+ * work after the first failure and rejects with that first error, so a failed
+ * upload does not keep fanning requests out to Snap.
+ *
+ * @template T
+ * @param {T[]} items
+ * @param {number} limit
+ * @param {(item: T) => Promise<void>} task
+ * @returns {Promise<void>}
+ */
+async function runWithConcurrency(items, limit, task) {
+  let next = 0;
+  /** @type {{ error: unknown } | undefined} */
+  let failure;
+  const worker = async () => {
+    while (!failure && next < items.length) {
+      const item = items[next++];
+      try {
+        await task(item);
+      } catch (error) {
+        failure ??= { error };
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  if (failure) throw failure.error;
+}
+
 const OPERATION_LIMIT_TEXT = formatDuration(MAX_OPERATION_DURATION_MS);
 
 /** @returns {number} A monotonic timestamp in milliseconds. */
@@ -565,31 +597,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
@@ -677,7 +685,6 @@ function getPackageVersion() {
 }
 
 const TAR_BLOCK_SIZE = 512;
-const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 
 /**
  * Parse a plain ustar-style tar archive (512-byte headers, bodies padded to
@@ -720,20 +727,6 @@ function parseTarEntries(archive) {
   return entries;
 }
 
-/**
- * Read the pixel dimensions from a PNG's IHDR chunk. Returns null when the
- * bytes are not a PNG (e.g. a JPEG export) or are too short.
- *
- * @param {Buffer} bytes
- * @returns {{ width: number, height: number } | null}
- */
-function readPngDimensions(bytes) {
-  if (bytes.length < 24 || !bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) {
-    return null;
-  }
-  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
-}
-
 /**
  * @param {string | undefined} json
  * @returns {any}
@@ -1910,6 +1903,14 @@ export class SnapProvider {
    * @returns {Promise<CaptureResult>}
    */
   async #captureLocalAndUpload(options) {
+    // The latest-baseline lookup is read-only and independent of the screenshots,
+    // so start it now and let it overlap with local capture. Its own deadline keeps
+    // capture time out of the Snap operation budget. A rejection is held until we
+    // await it below, so a capture failure first never leaves an unhandled one.
+    const baselineLookup =
+      options.purpose === 'diff' ? this.#resolveLatestBaselineId() : Promise.resolve(/** @type {string | null} */ (null));
+    baselineLookup.catch(() => {});
+
     const localCapture = await this.#localCaptureFn({
       configPath: options.configPath,
       routeIds: options.routeIds,
@@ -1939,7 +1940,7 @@ export class SnapProvider {
     // omit the baselineId. Captures then settle to "new" server-side (no
     // comparison), and publishBaseline harvests their object keys. A diff run
     // attaches the latest baseline so the backend can compare against it.
-    const baselineId = options.purpose === 'diff' ? await this.#resolveLatestBaselineId(operation) : null;
+    const baselineId = await baselineLookup;
 
     const runResponse = await this.#request(
       'POST',
@@ -1974,7 +1975,8 @@ export class SnapProvider {
       assertComparisonPolicyAcknowledged(runResponse?.comparisonPolicy, options.comparisonPolicy, 'Snap local-upload run creation');
     }
 
-    for (const { route, manifestEntry } of uploads) {
+    const uploadStartedAt = Date.now();
+    await runWithConcurrency(uploads, LOCAL_UPLOAD_CONCURRENCY, async ({ route, manifestEntry }) => {
       const captureId = `cap_${crypto.randomUUID().replace(/-/g, '').slice(0, 24)}`;
       const viewportDescriptor = resolveViewportDescriptor(route.viewport);
 
@@ -2010,7 +2012,8 @@ export class SnapProvider {
         this.#generateIdempotencyKey(),
         operation
       );
-    }
+    });
+    process.stderr.write(`[SnapDrift] Uploaded ${uploads.length} screenshot(s) to Snap in ${((Date.now() - uploadStartedAt) / 1000).toFixed(1)}s.\n`);
 
     const snapResults = {
       ...localResults,

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.15.0",
+  "version": "0.16.1",
   "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.6.0",
+    "@snapdrift/adapter-fs": "^1.7.1",
     "@snapdrift/adapter-report-md": "^1.4.0",
-    "@snapdrift/compare-core": "^1.6.0",
-    "@snapdrift/manifest": "^1.7.0",
+    "@snapdrift/compare-core": "^1.7.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

@@ -87,6 +87,7 @@ export interface VisualRegressionConfig {
   };
   selection?: VisualRegressionSelectionConfig;
   provider?: 'local' | 'snap';
+  capture?: 'playwright' | 'snap';
   snap?: SnapConfig;
 }
 
@@ -127,6 +128,7 @@ export interface VisualBaselineResults {
   screenshotsRoot?: string;
   routes: VisualBaselineRouteResult[];
   passed?: boolean;
+  engine?: string;
 }
 
 /** Exact route/viewport capture identity persisted for hosted baseline validation. */