snapdrift 0.16.0 → 0.16.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## 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:

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.16.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.16.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@8e827952c33415ba2d8f1fdab944d519534013a6 # v0.16.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@8e827952c33415ba2d8f1fdab944d519534013a6 # v0.16.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

@@ -90,7 +90,7 @@ runs:
       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

@@ -273,7 +273,7 @@ runs:
       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

@@ -43,7 +43,7 @@ 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 `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.
 
@@ -553,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.16.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.16.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.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` |
+| `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.16.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.16.0
+        uses: ranacseruet/snapdrift@v0.16.1
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -289,7 +289,7 @@ When your application deploys preview URLs (e.g., Vercel, Netlify, Cloudflare Pa
 ```
 
 ### 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.
+- **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.
 

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.16.0
+        uses: ranacseruet/snapdrift@v0.16.1
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json

package/lib/snap-provider.mjs

@@ -9,7 +9,7 @@ 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,
@@ -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. */
@@ -653,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
@@ -696,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}
@@ -1886,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,
@@ -1915,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',
@@ -1950,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);
 
@@ -1986,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/package.json

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