snapdrift 0.17.0 → 0.18.1

package/CHANGELOG.md

@@ -1,6 +1,53 @@
 # Changelog
 
-## Unreleased
+## 0.18.1 - 2026-11-03
+
+Workspace releases this version:
+
+- `@snapdrift/compare-core` 1.8.1 — a pixel that is fully transparent on both sides (alpha `0` on each side) is now visually equal regardless of its hidden RGB, in local comparison policy v1 and v2 (details under Fixes). This is the version the hosted Snap comparator must bump to for #224 parity.
+- `snapdrift` 0.18.1 — root floor for `@snapdrift/compare-core` moves to `^1.8.1`; the previous `^1.8.0` floor still resolves the unfixed 1.8.0 engine. The Marketplace dispatcher pin moves to `2ac911f`, the #227 merge commit on `main`, which includes both the newest commit touching `actions/` (`82e2578`, the #226 action hardening) and the #223 comparator fix, so wrapper-action diffs get the fixed engine too.
+- `@snapdrift/manifest` stays 1.8.0, `@snapdrift/adapter-fs` stays 1.8.0 (its `^1.8.0` compare-core range already resolves 1.8.1), and `@snapdrift/adapter-report-md` stays 1.4.0.
+
+### Fixes
+
+- `lib/snap-provider.mjs` (`provider: "snap"`): HTTP `429` (rate limit) and `408` (request timeout) are now treated as transient. They retry with exponential backoff — honoring a `Retry-After` delta-seconds or HTTP-date header, clamped to the existing 30s cap — and, once retries are exhausted, route through the configured `onUnavailable` policy like 5xx do, instead of throwing a raw `SnapApiError` with no retry and no policy routing. A quota-exhausted `429` (body code `quota_exceeded`) stays a hard `SnapApiError`: it is not retried and is not masked by `warn-and-skip`/`fallback-local`, so users still learn the quota is spent. Permanent 4xx behavior is unchanged.
+- `@snapdrift/adapter-report-md`: report markdown now escapes every interpolated string field. `makeMarkdown` escapes route ids, capture-gap reasons, error messages, viewports, and diff-image paths (the PR-comment surface already escaped). `escapeMarkdown` additionally escapes backslashes first, parentheses, emphasis characters (`*`, `_`, `~`, `#`, `!`), `@` (mentions), collapses `\r?\n` to a space (a raw newline inside a table cell ends the row), and neutralizes GFM autolinks by escaping `://` — a hostile capture target could otherwise inject markdown links or break tables via error messages that quote page content. Escaped bare URLs render identically but are no longer clickable. **Output change:** `escapeMarkdown` is re-exported publicly (`lib/pr-comment.mjs`, the package index), so external callers see the new output; values destined for code spans should use the new `formatCodeSpan` (backslash escapes render literally inside code spans). Diff-image destinations are now angle-bracketed with `%`/`<`/`>`/`&` percent-encoded, so paths with spaces survive CommonMark link parsing.
+- `@snapdrift/manifest`: `checkCaptureProfileCompatibility` no longer compares the `platform` block when both profiles are `snap-batch` (cloud-rendered). Snap-batch pixels render cloud-side, so the submitting runner's OS metadata says nothing about the images — without this, each GitHub runner image refresh would mark every stored snap-batch baseline `incompatible_capture` and force a mass re-baselining unrelated to real drift. Rendering-relevant fields (engine, browser, playwrightVersion, locale, timezone, settings) are still compared, and `snapdrift-local` captures keep the strict platform comparison.
+- `@snapdrift/adapter-fs`: `SNAPDRIFT_CAPTURE_CONCURRENCY` is now one run-wide limit shared across all viewport groups, instead of a per-group limit. Per-group limiters multiplied effective concurrency by the number of distinct viewports (e.g. 4 viewports × default 5 = 20 concurrent contexts on one shared chromium), an OOM/timeout risk on small runners. Multi-viewport captures may be slightly slower at the same setting; the documented limit is now the actual maximum.
+
+- `@snapdrift/compare-core`: a pixel that is fully transparent on both sides (alpha `0` on each side) is now visually equal regardless of its hidden RGB, in local comparison policy v1 and v2. This covers the strict comparators (`compareBuffers`, `compareWithIgnoreRegions`, `generateDiffImage`), v1 coordinate overlap, v2 exact row fingerprints and Myers verification, v2 offset-run paired rows and displacement evidence, and offset highlighting. One-sided transparent pixels still count as changed in strict, coordinate, and v2 exact-row comparisons, and an opacity change between alpha `0` and nonzero alpha still counts; the pre-existing v2 offset blank-padding rule is unchanged. The change lowers `differentPixels` only for overlapping alpha-0 pairs whose hidden RGB differs; no config, schema, or policy version changed. Hosted Snap `provider: "snap"` diffs reuse `@snapdrift/compare-core` pinned at `1.8.0` in `i2Dev-com/snap`, so hosted parity requires a Snap dependency bump and redeploy there (tracked in #224). Closes #201.
+
+- `lib/snap-provider.mjs` / `lib/cli.mjs`: `resolveGitRef` now prefers `GITHUB_HEAD_REF` over `GITHUB_REF_NAME` for branch attribution — on `pull_request` events `GITHUB_REF_NAME` is `<pr>/merge`, which misattributed baselines published from PR-context workflows. The CLI `diff` command now checks the baseline `results.json`/`manifest.json` on disk and reports the documented baseline-unavailable outcome (with a message) instead of recapturing locally and failing with a raw `ENOENT`; `diffWithPolicy` documents its inference as a path-string check only. Local-capture JSON parse failures inside the Snap local-upload path now name the unreadable file and suggest recapturing. A body-read timeout that fires after the attempt deadline no longer reports the request limit as elapsed time. The `comparisonPolicy` doc comment now describes the real fail-closed behavior (policy always sent, server acknowledgment required), and the locally-guaranteed dead truthiness guards are removed.
+- `@snapdrift/adapter-fs`: `stageArtifacts` preserves screenshot subdirectory structure instead of flattening, so same-named PNGs from different subdirectories can no longer silently overwrite each other in the uploaded bundle; symlinked PNGs are staged (stat-resolved) instead of dropped. Local capture records a per-route `Browser launch failed` error and still writes `results.json`/`manifest.json` when `chromium.launch` rejects (previously the most common CI capture failure left no artifacts at all), writes artifacts before `browser.close()`, and logs (rather than propagates) a close failure. Snap batch capture fails fast on a terminal `failed` poll status instead of spinning until the 5-minute timeout, bounds concurrent screenshot downloads (`downloadConcurrency` option, default `SNAPDRIFT_CAPTURE_CONCURRENCY`), and reads PNG dimensions header-only instead of fully decoding every image. `resolveImagePath` refuses manifest image paths that resolve outside the run directory. Capture retries are skipped for deterministic HTTP failures (4xx except 408/429).
+- `@snapdrift/manifest`: `normalizedViewportIdentity` preserves `deviceScaleFactor`/`isMobile`/`hasTouch` on custom viewports (a custom 1440×900 viewport at DSF 3 previously tested as identical to the desktop preset, letting 3×-different-sized images compare instead of reporting `incompatible_capture`). `validateManifest` no longer mutates its input when defaulting `schemaVersion`, rejects a `generatedAt` that fails `Date.parse`, and validates device-characteristic flags on custom viewports. `isLocalBaseUrl` recognizes loopback spellings URL canonicalization hides (`127.1`, `0177.0.0.1`, IPv4-mapped IPv6 loopback `::ffff:127.0.0.1`), which were previously sent to Snap Cloud as if remote.
+- `@snapdrift/compare-core`: the offset-align preflight early-exit bound is documented and guarded by a regression test: the mid-scan mean divides by the full planned sample count, so a costly early row cannot reject a pair whose remaining sampled rows align — the bound only triggers rejection the final sampled-mean verdict would reach anyway.
+- `@snapdrift/adapter-report-md`: the HTML report renders numeric summary fields (dimensions, pixel counts) through a finite-number guard — summaries can arrive from downloaded CI artifacts, so malformed fields no longer interpolate markup into the HTML. The package's `@snapdrift/manifest` floor is raised to `^1.8.0` to match the API it consumes.
+- Actions: baseline and pr-diff artifact uploads use `if-no-files-found: error` (an empty artifact was previously uploaded with a warning and later misread by the resolver). `actions/resolve-baseline` resolves its lib modules against the action checkout without the redundant `GITHUB_WORKSPACE` prefix. The pr-diff enforce step consumes the compare step's `summary_path` output instead of a hardcoded `qa-artifacts` path, so a repo-level output override no longer enforces against a stale or missing summary. The comment action guards an unset `summary-path` input with a warning instead of a `TypeError` from `existsSync(undefined)`.
+- CI (`publish.yml`): new `npm audit --omit=dev --audit-level=high` step runs before install, and the npm upgrade for trusted publishing is pinned to the exact `11.5.1` version.
+- CLI/lib: `openFile` reports a non-zero opener exit status (previously silent). `upsertPullRequestReportComment` sorts unparseable comment timestamps to the end deterministically instead of letting `NaN` pick an arbitrary comment to update. `init --from-snap-action` no longer overwrites an existing `MIGRATION_NOTES.md`.
+
+### Removals
+
+- **`SnapProvider.fetchLatestBaseline()` and `SnapProvider.checkBaselineExists()` are removed**, along with the `fetchLatestBaseline` member of the `VisualProvider` interface (both `@snapdrift/manifest` types and the root re-export), the `LocalProvider.fetchLatestBaseline` not-implemented stub, and the `fetchLatestBaseline` capability from `PROVIDER_CAPABILITIES`/`providerSupports`. None had a production caller: baseline resolution goes through the `actions/resolve-baseline` artifact download, and the by-SHA lookup belonged to migration workflows retired with `migrate-baselines`. `#resolveLatestBaselineId` (the internal `baselines/latest` GET used by `capture()`/`diff()`) is unchanged. The `snapdrift baseline` command and both wrapper actions are unaffected. Add-back is a small, isolated change if a hosted baseline-store consumer appears.
+- **`lib/resolve-baseline-paths.mjs` is removed**, including its `./lib/resolve-baseline-paths.mjs` exports-map entry and test. It was superseded by the path computation inside `actions/resolve-baseline` itself and had no importer.
+
+## 0.18.0 - 2026-11-02
+
+Workspace releases this version:
+
+- `@snapdrift/adapter-fs` 1.8.0 — local capture now requires Playwright `^1.64.1`, which installs Chromium `156.0.8078.4` (revision `1248`) instead of Chromium `153.0.8010.12` (revision `1243`). Existing local baselines captured with Playwright 1.63.x persist a different `captureProfile.browserRevision` / `playwrightVersion`, so comparison reports `incompatible_capture` and does not compare pixels until the baseline is refreshed in the upgraded environment. Pixel rendering may still be byte-identical; the capture-profile contract has no version tolerance.
+
+`@snapdrift/manifest` stays 1.8.0, `@snapdrift/compare-core` stays 1.8.0, and `@snapdrift/adapter-report-md` stays 1.4.0. Root floors move to `@snapdrift/adapter-fs ^1.8.0` and `playwright ^1.64.1`; the previous `adapter-fs` 1.7.2 and the Playwright 1.63 floor do not satisfy them. The dispatcher pins `3831623`, the #216 merge commit on `main`, which includes the newest commit touching `actions/` (`1cbf629`, the shell-only Playwright install).
+
+### Changes
+
+- Local capture raises the Playwright floor to `^1.64.1`; installs now provision Chromium `156.0.8078.4` (revision `1248`). GitHub Actions keep the shell-only Chromium install (`playwright install --with-deps --only-shell chromium`).
+- **Baseline refresh required:** local baselines captured under the previous Playwright floor (`1.63.x`, Chromium `153.0.8010.12`, revision `1243`) are incompatible until recaptured. A real local-capture verification on a deterministic page produced byte-identical desktop (1440×900) and mobile (1170×2955) PNGs across both versions, but diffing the old baseline against a 1.64.1 current capture returned `incomplete` with two `incompatible_capture` errors (reason: `captureProfile.browserRevision differs between baseline and current capture`); recapturing on 1.64.1 then diffing returned `clean` with `captureCompatibility: verified`.
+
+### Documentation
+
+- `docs/local-cli.md` now states the upgrade path explicitly: refresh every local baseline in the upgraded Playwright/Chromium environment before expecting PR diffs to compare pixels, even when rendering is byte-identical.
+- Existing guidance on refreshing or acknowledging local baselines remains unchanged; `report-only` keeps incompatibility visible and never forces pixel comparison.
 
 ## 0.17.0 - 2026-10-28
 

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.17.0
+  uses: ranacseruet/snapdrift@v0.18.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.17.0
+  uses: ranacseruet/snapdrift@v0.18.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@2d93a5499daf6e0273ed11da69b364d33dc8d4d2 # v0.17.0
+      uses: ranacseruet/snapdrift/actions/baseline@2ac911f8def2b8df61f015837d01555f04b68c99 # v0.18.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@2d93a5499daf6e0273ed11da69b364d33dc8d4d2 # v0.17.0
+      uses: ranacseruet/snapdrift/actions/pr-diff@2ac911f8def2b8df61f015837d01555f04b68c99 # v0.18.1
       with:
         github-token: ${{ inputs.github-token }}
         repo-config-path: ${{ inputs.repo-config-path }}

package/actions/baseline/action.yml

@@ -235,5 +235,7 @@ runs:
       with:
         name: ${{ steps.config.outputs.artifact_name }}
         retention-days: ${{ inputs.artifact-retention-days }}
-        if-no-files-found: warn
+        # A baseline upload that contains no files would publish an artifact
+        # the resolver later "finds" but cannot use; fail instead of warn.
+        if-no-files-found: error
         path: ${{ steps.stage.outputs.bundle_dir }}

package/actions/comment/action.yml

@@ -75,6 +75,12 @@ runs:
           const { pathToFileURL } = require('url');
 
           const summaryPath = process.env.VISUAL_DIFF_SUMMARY_PATH;
+          if (!summaryPath) {
+            // existsSync(undefined) throws a TypeError; an unset summary-path
+            // input means there is no report to post, not a crash.
+            core.warning('SnapDrift summary-path input was not set; skipping PR comment.');
+            return;
+          }
           if (!fs.existsSync(summaryPath)) {
             core.warning(`SnapDrift summary not found at ${summaryPath}`);
             return;

package/actions/pr-diff/action.yml

@@ -584,7 +584,10 @@ runs:
       with:
         name: ${{ steps.context.outputs.artifact_name }}
         retention-days: ${{ inputs.artifact-retention-days }}
-        if-no-files-found: warn
+        # A drift upload that contains no files means staging ran but produced
+        # nothing; downstream consumers would download an empty artifact and
+        # misread it as "no drift". Fail instead of warn.
+        if-no-files-found: error
         path: ${{ steps.stage.outputs.bundle_dir }}
 
     - if: always()
@@ -687,6 +690,13 @@ runs:
     # has nothing to evaluate — `warn-and-skip` means "do not fail my build".
     - if: steps.scope.outputs.should_run == 'true' && steps.capture.outputs.provider != 'skipped' && steps.compare.outputs.skipped != 'true' && (steps.baseline.outputs.found == 'true' || steps.capture.outputs.provider == 'snap')
       shell: bash
+      env:
+        # Consume the compare step's summary_path output rather than hardcoding
+        # the default drift directory: a repo-level workingDirectory or
+        # outDir override moves the summary, and the hardcoded path then read
+        # a stale file (or failed with ENOENT) while the real summary said
+        # something different.
+        SUMMARY_JSON_PATH: ${{ steps.compare.outputs.summary_path }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -695,7 +705,7 @@ runs:
 
         const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/compare-results.mjs');
         const { shouldFailDriftCheck, formatDriftFailureMessage } = await import(pathToFileURL(modulePath));
-        const summaryModulePath = path.resolve('qa-artifacts/snapdrift/drift/current/summary.json');
+        const summaryModulePath = path.resolve(process.env.SUMMARY_JSON_PATH);
         const summary = JSON.parse(await fs.readFile(summaryModulePath, 'utf8'));
 
         if (shouldFailDriftCheck(summary)) {

package/actions/resolve-baseline/action.yml

@@ -84,8 +84,13 @@ runs:
           const { pathToFileURL } = require('url');
 
           const repository = process.env.INPUT_REPOSITORY || `${context.repo.owner}/${context.repo.repo}`;
-          const modulePath = path.resolve(process.env.GITHUB_WORKSPACE, process.env.GITHUB_ACTION_PATH, '..', '..', 'lib', 'snapdrift-config.mjs');
-          const resolverModulePath = path.resolve(process.env.GITHUB_WORKSPACE, process.env.GITHUB_ACTION_PATH, '..', '..', 'lib', 'resolve-baseline-artifact.mjs');
+          // Resolve against the action's own checkout, not GITHUB_WORKSPACE:
+          // this composite action may be consumed from a repo whose working
+          // directory does not contain the snapdrift checkout, and
+          // GITHUB_ACTION_PATH already points inside the action.
+          const actionRoot = path.resolve(process.env.GITHUB_ACTION_PATH, '..', '..');
+          const modulePath = path.resolve(actionRoot, 'lib', 'snapdrift-config.mjs');
+          const resolverModulePath = path.resolve(actionRoot, 'lib', 'resolve-baseline-artifact.mjs');
           const { loadSnapdriftConfig } = await import(pathToFileURL(modulePath));
           const { resolveBaselineArtifact } = await import(pathToFileURL(resolverModulePath));
           let artifactName = process.env.INPUT_ARTIFACT_NAME || '';

package/docs/contracts.md

@@ -191,7 +191,7 @@ and comparison policy v1. The profile records:
 |:------|:--------------------|
 | `engine`, `engineVersion` | `{ "name": "snapdrift-local", "version": "<adapter-fs version>" }`; `engineVersion` equals `engine.version` |
 | `browser`, `browserRevision`, `playwrightVersion` | `chromium`, the running browser's `browser.version()` string, and the installed Playwright version |
-| `platform` | `name`, `architecture`, `release`, `version` from Node's OS APIs |
+| `platform` | `name`, `architecture`, `release`, `version` from Node's OS APIs. Compared strictly for `snapdrift-local` captures (rendering happens on the submitting machine); ignored for `snap-batch` captures, whose pixels are rendered cloud-side, so GitHub runner image refreshes do not invalidate stored baselines |
 | `locale`, `timezone` | `en-US`, `UTC` |
 | `settings.screenshot` | `fullPage: true`, `animations: "disabled"`, `caret: "hide"`, `scale: "device"`, `omitBackground: false`, `type: "png"` |
 | `settings.readiness` | `waitUntil: "load"`, `settleDelayMs: 300` |
@@ -297,8 +297,8 @@ Policy v2 comparison metadata additionally includes `policyVersion: 2`,
 `mode`, and, for aligned results, `alignmentStrategy`. An aligned result has
 `mode: "vertical-aligned"` and a compact `rowMapping` describing matched,
 changed, inserted, and deleted row runs. `alignmentStrategy: "exact"` records
-the Myers fingerprint path: matched rows are byte-identical and `tolerance` is
-absent. `alignmentStrategy: "offset"` records the piecewise vertical-offset
+the Myers fingerprint path: matched rows are visually identical (fully
+transparent pairs may differ in hidden RGB) and `tolerance` is absent. `alignmentStrategy: "offset"` records the piecewise vertical-offset
 fallback: `tolerance` is the maximum per-channel delta that stays unhighlighted
 on stable offset-run rows (`STRUCTURED_DELTA`, 32). Local-mismatch residual
 bands between stable runs instead highlight deltas above `NOISE_DELTA` (2), so
@@ -345,11 +345,11 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 - Mismatch ratio is `different_pixels / total_pixels`
 - `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. If that search hits its edit cap, long vertical-offset runs are mapped instead. Inside a run, a row is compared one pixel above or below the recorded current row only when the row's own recorded-offset ink cost exceeds `LOCAL_MISMATCH_COST` (0.5) and a ±1 neighbor matches; a stable row with a smaller residual keeps its own offset, so its nominal current row is still compared instead of being consumed without comparison. `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 stable offset-run rows, 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 local-mismatch residual band between stable runs is stricter: a pixel there is highlighted when any channel differs by more than `NOISE_DELTA` (2). A short cluster of such 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. Aligned metadata records which strategy applied: exact Myers results carry `alignmentStrategy: "exact"` and no `tolerance`; offset-run results carry `alignmentStrategy: "offset"` and the stable-run `tolerance: 32`, while residual local-mismatch bands are not covered by `tolerance`. An unmatched row that also occurs on the opposite side is ambiguous only when its repeat count on either side stays below `MIN_STRUCTURAL_ROW_REPEATS` (16): such a row could be moved content. Ambiguous exact alignment first tries the offset-run mapping; when that mapping succeeds, the result is `vertical-aligned` with `alignmentStrategy: "offset"`, and only an unsuccessful mapping falls back to v1 coordinate comparison as `ambiguous`. A row that repeats at least 16 times on either side (page background, card padding, borders) is structural and does not count: where it lands inside a run of identical rows makes no visible difference. Offset-run plans treat blank structural padding as matched rather than painting it green or red: a one-sided row carries content only when at least `CONTENT_INK_MIN` (16) full-width ink pixels are present. A one-sided content row that duplicates a claimed row in the other image within `STRUCTURAL_DUPLICATE_COST` (0.05 row ink cost) at an offset within `STRUCTURAL_DUPLICATE_WINDOW` (3) of the neighboring stable runs is a compensating rendering band, not a new or deleted line, and stays matched. An unresolved band at a shift boundary splits into changed-ink rows and padding: a baseline ink row pairs with the current row at the preceding stable offset when that row carries ink and is free, otherwise with its best evidence offset when that offset sits within the duplicate window of the neighboring runs, otherwise it is a red deletion. Leading blank rows stay with the preceding offset only when every candidate current row is free; trailing blank rows follow the last paired content offset when free, otherwise they are the deleted region's blank tail. A candidate current row already claimed by a stable run is never a free partner. Inside a paired row, a mismatch set with fewer than `CONTENT_INK_MIN` mismatched pixels is a localized rendering displacement (a glyph or badge edge drawn a few rows off its text) only when every mismatch has both background evidence — the baseline pixel exists in a claimed current row — and foreground evidence — the current pixel exists in a claimed baseline row — at one common non-zero relative offset within the duplicate window; inserted current rows and deleted baseline rows count as claimed rows on their respective sides. A mismatch with only one side's duplicate, such as a new small mark on a uniform background whose old background has a neighboring current copy but whose foreground exists nowhere in the baseline, is content and stays orange. A contiguous displaced run is suppressed only when it borders matched rows or blank structural one-sided rows; a run bordering unexplained mismatched content or content-carrying one-sided rows stays painted as part of that edit. A mismatch set reaching `CONTENT_INK_MIN` is a structured glyph or region recolor and stays orange. Width changes, ignore regions, resource limits, and ambiguous exact-row matches whose offset-run mapping also fails fall back to v1 coordinate comparison and record the fallback reason; coordinate-fallback metadata carries neither `alignmentStrategy` nor `tolerance`. This is a raster row alignment aid, not DOM or arbitrary component matching.
+- 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, and a two-sided overlap pixel is equal when both alphas are 0 regardless of hidden RGB. 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. Fingerprinting and Myers verification treat a pixel that is fully transparent on both sides as zero RGBA regardless of hidden RGB. If that search hits its edit cap, long vertical-offset runs are mapped instead. Inside a run, a row is compared one pixel above or below the recorded current row only when the row's own recorded-offset ink cost exceeds `LOCAL_MISMATCH_COST` (0.5) and a ±1 neighbor matches; a stable row with a smaller residual keeps its own offset, so its nominal current row is still compared instead of being consumed without comparison. `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 stable offset-run rows, a pixel transparent on both sides is equal regardless of hidden RGB, and 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 local-mismatch residual band between stable runs is stricter: a pixel there is highlighted when any channel differs by more than `NOISE_DELTA` (2), except that a pair transparent on both sides remains equal regardless of hidden RGB. A short cluster of such 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 visually identical; a fully transparent pair may differ in hidden RGB. Aligned metadata records which strategy applied: exact Myers results carry `alignmentStrategy: "exact"` and no `tolerance`; offset-run results carry `alignmentStrategy: "offset"` and the stable-run `tolerance: 32`, while residual local-mismatch bands are not covered by `tolerance`. An unmatched row that also occurs on the opposite side is ambiguous only when its repeat count on either side stays below `MIN_STRUCTURAL_ROW_REPEATS` (16): such a row could be moved content. Ambiguous exact alignment first tries the offset-run mapping; when that mapping succeeds, the result is `vertical-aligned` with `alignmentStrategy: "offset"`, and only an unsuccessful mapping falls back to v1 coordinate comparison as `ambiguous`. A row that repeats at least 16 times on either side (page background, card padding, borders) is structural and does not count: where it lands inside a run of identical rows makes no visible difference. Offset-run plans treat blank structural padding as matched rather than painting it green or red: a one-sided row carries content only when at least `CONTENT_INK_MIN` (16) full-width ink pixels are present. A one-sided content row that duplicates a claimed row in the other image within `STRUCTURAL_DUPLICATE_COST` (0.05 row ink cost) at an offset within `STRUCTURAL_DUPLICATE_WINDOW` (3) of the neighboring stable runs is a compensating rendering band, not a new or deleted line, and stays matched. An unresolved band at a shift boundary splits into changed-ink rows and padding: a baseline ink row pairs with the current row at the preceding stable offset when that row carries ink and is free, otherwise with its best evidence offset when that offset sits within the duplicate window of the neighboring runs, otherwise it is a red deletion. Leading blank rows stay with the preceding offset only when every candidate current row is free; trailing blank rows follow the last paired content offset when free, otherwise they are the deleted region's blank tail. A candidate current row already claimed by a stable run is never a free partner. Inside a paired row, a mismatch set with fewer than `CONTENT_INK_MIN` mismatched pixels is a localized rendering displacement (a glyph or badge edge drawn a few rows off its text) only when every mismatch has both background evidence — the baseline pixel exists in a claimed current row — and foreground evidence — the current pixel exists in a claimed baseline row — at one common non-zero relative offset within the duplicate window; inserted current rows and deleted baseline rows count as claimed rows on their respective sides. A mismatch with only one side's duplicate, such as a new small mark on a uniform background whose old background has a neighboring current copy but whose foreground exists nowhere in the baseline, is content and stays orange. A contiguous displaced run is suppressed only when it borders matched rows or blank structural one-sided rows; a run bordering unexplained mismatched content or content-carrying one-sided rows stays painted as part of that edit. A mismatch set reaching `CONTENT_INK_MIN` is a structured glyph or region recolor and stays orange. Width changes, ignore regions, resource limits, and ambiguous exact-row matches whose offset-run mapping also fails fall back to v1 coordinate comparison and record the fallback reason; coordinate-fallback metadata carries neither `alignmentStrategy` nor `tolerance`. 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.
+- `dimensionChanges[]` remains part of the summary contract but is empty for local comparisons in v1. Strict same-dimension comparison (`compareBuffers`, `compareWithIgnoreRegions`, `generateDiffImage`) remains available to direct `@snapdrift/compare-core`/`comparePngs` callers that pass no policy; its pixel equality uses the same two-sided alpha-0 rule as v1.
 - Threshold is applied after pixel aggregation. A mismatch exactly equal to the threshold is matched; a dimension change is still a changed signal independent of ratio.
 - `diff.mode` controls enforcement, not summary generation
 
@@ -461,7 +461,7 @@ that matches the product behavior. Do not resize or crop screenshots, or lower
 | Navigation timeout | 30000ms |
 | Settle delay | 300ms |
 | Screenshot animations | `disabled` (Playwright finishes/cancels CSS animations before capture) |
-| Capture concurrency | 5 routes per viewport (overridable via `SNAPDRIFT_CAPTURE_CONCURRENCY`)|
+| Capture concurrency | 5 routes in total across all viewport groups (overridable via `SNAPDRIFT_CAPTURE_CONCURRENCY`)|
 
 Local Playwright captures use a fresh browser context for every route attempt,
 including retries. Cookies and browser storage are not shared between routes,
@@ -735,7 +735,7 @@ These are for custom orchestration only. Wrapper actions set them automatically.
 | `SNAPDRIFT_BASELINE_ARTIFACT_NAME` | `compare-results.mjs` | Baseline artifact label to embed in the report |
 | `SNAPDRIFT_BASELINE_SOURCE_SHA` | `compare-results.mjs` | Baseline source SHA to embed in the report |
 | `SNAPDRIFT_ENFORCE_OUTCOME` | `compare-results.mjs` | Set to `0` to disable enforcement in direct CLI usage |
-| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture-routes.mjs` | Max concurrent route captures per viewport group (positive integer, default `5`). Each local attempt uses a fresh browser context. Set to `1` to serialize each group without sharing storage. |
+| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture-routes.mjs` | Max concurrent route captures across all viewport groups combined (positive integer, default `5`). Each local attempt uses a fresh browser context. Set to `1` to fully serialize captures without sharing storage. |
 
 ## PR comment markdown shape
 

package/docs/integration-guide.md

@@ -8,7 +8,7 @@ Examples use the public release tag for readability. If your organization requir
 
 - SnapDrift provisions Node 22 internally.
 - The consumer app can use any stack as long as it can be started and reached at `baseUrl`.
-- The runner must be Ubuntu-compatible because Playwright Chromium is installed with system dependencies.
+- The runner must be pinned to a stable Ubuntu-compatible image (for example `ubuntu-24.04`) because Playwright Chromium is installed with system dependencies and local capture profiles fingerprint the OS. Avoid a moving `ubuntu-latest` label between baseline and PR captures.
 - The runner must have outbound network access to fetch Playwright Chromium.
 
 Your repository still owns:
@@ -46,7 +46,7 @@ SnapDrift owns route selection, capture, comparison, skipped-report generation,
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift@v0.17.0
+  uses: ranacseruet/snapdrift@v0.18.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.17.0
+  uses: ranacseruet/snapdrift@v0.18.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.17.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.17.0` |
-| `ranacseruet/snapdrift@v0.17.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.17.0` |
+| `ranacseruet/snapdrift@v0.18.1` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.18.1` |
+| `ranacseruet/snapdrift@v0.18.1` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.18.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.
 
@@ -112,7 +112,7 @@ permissions:
 
 jobs:
   snapdrift:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -130,7 +130,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.17.0
+        uses: ranacseruet/snapdrift@v0.18.1
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -154,7 +154,7 @@ permissions:
 
 jobs:
   snapdrift:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -170,7 +170,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.17.0
+        uses: ranacseruet/snapdrift@v0.18.1
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/docs/local-cli.md

@@ -214,6 +214,13 @@ normalized viewport. A mismatch produces an
 signal. Matching profiles can still have route-identity errors:
 `summary.captureCompatibility.status` describes profiles only.
 
+SnapDrift 0.18.0 raises the Playwright floor to 1.64.1, which installs Chromium
+156 (`156.0.8078.4`, revision 1248) instead of Chromium 153 (`153.0.8010.12`,
+revision 1243). Every local baseline captured with Playwright 1.63.x is
+incompatible until refreshed, even when the rendered pixels are byte-identical;
+the profile check has no version tolerance. Refresh on the upgraded environment
+before expecting PR diffs to compare pixels.
+
 To refresh, serve the intended accepted application state using the same capture
 environment and route config as future diffs. With `provider: "local"`, run:
 
@@ -372,7 +379,7 @@ differ; `fail-on-changes` and `strict` still enforce it.
 
 | Variable | Applies to | Description |
 |:---------|:-----------|:------------|
-| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture`, `diff` | Max concurrent route operations (positive integer, default `5`): route captures per viewport group, and per-route resolve/compare during `diff`. Each local capture attempt uses isolated browser storage. Set to `1` to serialize captures within each viewport group, without sharing storage. |
+| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture`, `diff` | Max concurrent route operations (positive integer, default `5`): route captures in total across all viewport groups during `capture`, and per-route resolve/compare during `diff`. Each local capture attempt uses isolated browser storage. Set to `1` to fully serialize captures, without sharing storage. |
 | `SNAPDRIFT_CONFIG_PATH` | `capture`, `diff`, `migrate-baselines` | Override the config file path. Equivalent to `--config`. |
 | `SNAPDRIFT_ROUTE_IDS` | `capture`, `baseline`, `diff` | Comma-separated route ids to scope to. Equivalent to `--routes`; it may not reduce a hosted baseline's complete route set. |
 

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

@@ -35,7 +35,7 @@ jobs:
     concurrency:
       group: snapdrift-baseline-${{ github.repository }}-${{ github.ref }}
       cancel-in-progress: false
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     steps:
       - uses: actions/checkout@v4
@@ -82,7 +82,7 @@ jobs:
 
       - name: Publish SnapDrift baseline
         if: steps.baseline_candidate.outputs.current == 'true'
-        uses: ranacseruet/snapdrift@v0.17.0
+        uses: ranacseruet/snapdrift@v0.18.1
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json

package/lib/cli.mjs

@@ -50,7 +50,8 @@ export const LOCAL_DIFF_SUBDIR = 'diff';
  *   --from-snap-action <path>  Snap action workflow YAML path (init command)
  *
  * Values may be given inline as `--flag=value` (so values beginning with a hyphen,
- * e.g. `--routes=-mobile`, work) or after the `--` end-of-options marker. Unknown
+ * e.g. `--routes=-mobile`, work) or after the `--` end-of-options marker (where
+ * known value flags are still honored, so `-- --routes -mobile` works). Unknown
  * flags and missing option values are rejected with a non-zero error; invalid
  * *values* for --to/--from remain silently ignored (validated downstream).
  *
@@ -131,7 +132,11 @@ export function parseArgs(argv) {
        continue;
      }
 
-     // End-of-options: after `--`, tokens are values/positionals, never flags.
+      // After `--`, tokens are still matched against known value flags so a
+     // hyphenated value can be passed as `-- --routes -mobile`. The inline
+     // comment below previously claimed tokens become positionals, which the
+     // code (and tests) never did — this comment now describes the actual
+     // contract.
      if (endOfOptions) {
        if (VALUE_FLAGS.has(raw)) {
          const value = args[i + 1];
@@ -230,16 +235,22 @@ export function printSummary(summary) {
 }
 
 /**
- * Open a file with the OS default viewer.
+ * Open a file with the OS default viewer. Exported for testing.
  *
  * @param {string} filePath
  * @returns {void}
  */
-function openFile(filePath) {
+export function openFile(filePath) {
   const { cmd, args } = buildOpenCommand(filePath);
   const result = spawnSync(cmd, args);
   if (result.error) {
     process.stderr.write(`Could not open file: ${filePath}\n`);
+  } else if (result.status !== 0) {
+    // A non-zero exit (e.g. xdg-open without a registered handler) previously
+    // passed silently; report it so the user knows the report was not opened.
+    process.stderr.write(
+      `Could not open file: ${filePath} (${cmd} exited with status ${result.status})\n`
+    );
   }
 }
 
@@ -452,11 +463,23 @@ export async function runDiffCommand(opts) {
     localScreenshots: captured.localScreenshots,
     captureOptions,
     diffOptions,
+    // Explicit, because the policy's inference only checks that a baseline
+    // path string was supplied — a stale baselineDir without results.json
+    // must produce the documented baseline-unavailable outcome, not a raw
+    // ENOENT from the local diff engine.
+    baselineAvailable: await Promise.all([
+      fs.access(baselineResultsPath),
+      fs.access(baselineManifestPath)
+    ]).then(() => true, () => false),
     onSkip: () =>
       process.stdout.write('Visual regression skipped (Snap unavailable, warn-and-skip mode).\n'),
     onFallback: () => process.stdout.write('Falling back to local provider for the diff...\n'),
     onRecapture: () =>
-      process.stdout.write('Recapturing locally so the local diff has screenshots to compare...\n')
+      process.stdout.write('Recapturing locally so the local diff has screenshots to compare...\n'),
+    onBaselineUnavailable: () =>
+      process.stdout.write(
+        `No baseline found at ${baselineResultsPath}; the local fallback has nothing to diff.\n`
+      )
   });
 
   if (diffed.outcome !== 'diffed') {

package/lib/github-requests.mjs

@@ -120,6 +120,15 @@ export async function upsertPullRequestReportComment({ github, owner, repo, issu
     .sort((left, right) => {
       const leftTime = new Date(left.updated_at || left.created_at).getTime();
       const rightTime = new Date(right.updated_at || right.created_at).getTime();
+      // NaN (unparseable timestamps) makes the comparator's contract
+      // unreliable: subtracting NaN yields NaN, and V8 treats an unsorted
+      // NaN result as "keep order", which would pick an arbitrary comment
+      // to update. Send non-finite timestamps to the end deterministically.
+      const leftFinite = Number.isFinite(leftTime);
+      const rightFinite = Number.isFinite(rightTime);
+      if (!leftFinite && !rightFinite) return 0;
+      if (!leftFinite) return 1;
+      if (!rightFinite) return -1;
       return rightTime - leftTime;
     });
   const existing = matchingComments[0];

package/lib/init-from-action.mjs

@@ -242,13 +242,19 @@ export async function runInitFromAction(actionYamlPath) {
 
   // Write snapdrift.json
   await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+  process.stdout.write(`Created ${configPath}\n`);
 
-  // Write MIGRATION_NOTES.md
+  // Write MIGRATION_NOTES.md, but never overwrite an existing one: unlike
+  // the generated config, the notes file is meant to be edited by the user
+  // during migration, and re-running init must not silently clobber it.
   const notesContent = generateMigrationNotes(warnings, actionYamlPath);
-  await fs.writeFile(notesPath, notesContent);
-
-  process.stdout.write(`Created ${configPath}\n`);
-  process.stdout.write(`Created ${notesPath}\n`);
+  const notesExist = await fs.access(notesPath).then(() => true, () => false);
+  if (notesExist) {
+    process.stdout.write(`Kept existing ${notesPath} (not overwritten)\n`);
+  } else {
+    await fs.writeFile(notesPath, notesContent);
+    process.stdout.write(`Created ${notesPath}\n`);
+  }
   if (warnings.length > 0) {
     process.stdout.write(`${warnings.length} warning(s)/note(s) — review ${notesPath}\n`);
   }

package/lib/outage-policy.mjs

@@ -157,7 +157,10 @@ export async function captureWithPolicy(options) {
  *
  * 1. A baseline must exist on disk. Without one the local diff throws on a
  *    missing results file, so we report `baseline-unavailable` and let the
- *    caller write the documented missing-baseline summary instead.
+ *    caller write the documented missing-baseline summary instead. Callers
+ *    should pass `baselineAvailable` explicitly (the CLI checks the file);
+ *    the fallback inference only tests that `diffOptions.baselineResultsPath`
+ *    is a non-empty string, which is weaker than existence on disk.
  * 2. The current capture must have local screenshots. A remote Snap capture
  *    does not, so we recapture locally first rather than diffing a manifest of
  *    zero-dimension placeholders.

package/lib/pr-comment.mjs

@@ -1,4 +1,4 @@
 // @ts-check
 // Re-exports from packages — this module is a thin shim.
 
-export { buildReportCommentBody, PR_COMMENT_MARKER, PR_COMMENT_MARKERS, escapeMarkdown } from '@snapdrift/adapter-report-md';
+export { buildReportCommentBody, PR_COMMENT_MARKER, PR_COMMENT_MARKERS, escapeMarkdown, formatCodeSpan } from '@snapdrift/adapter-report-md';

package/lib/provider.mjs

@@ -19,8 +19,6 @@ import {
 /** @typedef {import('../types/visual-diff-types').ProviderDiffResult} DiffResult */
 /** @typedef {import('../types/visual-diff-types').ProviderPublishBaselineOptions} PublishBaselineOptions */
 /** @typedef {import('../types/visual-diff-types').ProviderPublishBaselineResult} PublishBaselineResult */
-/** @typedef {import('../types/visual-diff-types').ProviderFetchBaselineOptions} FetchBaselineOptions */
-/** @typedef {import('../types/visual-diff-types').ProviderBaselineData} BaselineData */
 /** @typedef {import('../types/visual-diff-types').SnapConfig} SnapConfig */
 /** @typedef {import('../types/visual-diff-types').VisualRegressionConfig} VisualRegressionConfig */
 
@@ -56,19 +54,6 @@ export class LocalProvider {
     return stageArtifacts({ artifactType: 'baseline', ...stageOpts });
   }
 
-  /**
-   * @param {FetchBaselineOptions} _options
-   * @returns {Promise<never>}
-   * Guard with providerSupports(providerName, 'fetchLatestBaseline') before calling.
-   * @throws {Error} Not yet implemented for LocalProvider.
-   *   Use the pr-diff action for baseline resolution, or wait for a future release.
-   */
-  async fetchLatestBaseline(_options) {
-    throw new Error(
-      'LocalProvider.fetchLatestBaseline is not yet implemented. ' + 'Use the pr-diff action for baseline resolution, or wait for a future release.'
-    );
-  }
-
   /**
    * Build a PR comment body from a diff summary.
    * LocalProvider omits the dashboard link (no dashboard exists).
@@ -83,8 +68,8 @@ export class LocalProvider {
 }
 
 export const PROVIDER_CAPABILITIES = Object.freeze({
-  local: Object.freeze({ capture: true, diff: true, publishBaseline: true, fetchLatestBaseline: false, buildCommentBody: true }),
-  snap: Object.freeze({ capture: true, diff: true, publishBaseline: true, fetchLatestBaseline: true, buildCommentBody: true })
+  local: Object.freeze({ capture: true, diff: true, publishBaseline: true, buildCommentBody: true }),
+  snap: Object.freeze({ capture: true, diff: true, publishBaseline: true, buildCommentBody: true })
 });
 
 /**

package/lib/snap-provider.mjs

@@ -28,8 +28,6 @@ import {
 /** @typedef {import('../types/visual-diff-types').ProviderDiffResult} DiffResult */
 /** @typedef {import('../types/visual-diff-types').ProviderPublishBaselineOptions} PublishBaselineOptions */
 /** @typedef {import('../types/visual-diff-types').ProviderPublishBaselineResult} PublishBaselineResult */
-/** @typedef {import('../types/visual-diff-types').ProviderFetchBaselineOptions} FetchBaselineOptions */
-/** @typedef {import('../types/visual-diff-types').ProviderBaselineData} BaselineData */
 /** @typedef {import('../types/visual-diff-types').SnapConfig} SnapConfig */
 /** @typedef {import('../types/visual-diff-types').VisualRegressionConfig} VisualRegressionConfig */
 /** @typedef {import('../types/visual-diff-types').ComparisonPolicy} ComparisonPolicy */
@@ -42,6 +40,28 @@ const MAX_RETRIES = 3;
 const INITIAL_RETRY_DELAY_MS = 1000;
 const RETRY_MULTIPLIER = 2;
 const RETRY_DELAY_CAP_MS = 30000;
+/**
+ * Transient 4xx statuses that are retryable and routed through the
+ * `onUnavailable` availability policy instead of failing outright. 429
+ * (rate limited) and 408 (request timeout) describe a temporary server-side
+ * condition, not a permanent client error, so they get the same retry +
+ * availability semantics as 5xx.
+ * @type {Set<number>}
+ */
+const TRANSIENT_RETRYABLE_4XX = new Set([408, 429]);
+/**
+ * Snap reports exhausted account quota as a 429 carrying a quota body code
+ * (e.g. `quota_exceeded`). Unlike a rate limit, exhausted quota does not
+ * recover by waiting, so those 429s must stay hard, non-retryable
+ * `SnapApiError`s instead of being retried and then masked by the
+ * availability policy (warn-and-skip would exit 0 and never tell the user
+ * the quota is spent).
+ * @param {SnapApiError} error
+ * @returns {boolean}
+ */
+function isQuotaExhaustedError(error) {
+  return /quota/i.test(error.code || '');
+}
 const JSON_REQUEST_TIMEOUT_MS = 30 * 1000;
 const BINARY_REQUEST_TIMEOUT_MS = 120 * 1000;
 const POLL_INTERVAL_MS = 2000;
@@ -328,10 +348,12 @@ function assertComparisonPolicyAcknowledged(actual, expected, context) {
 }
 
 /**
- * Updated SnapDrift clients explicitly opt into the union-canvas comparison.
- * Keep the config override for callers that want the policy visible in their
- * config, but derive it from the existing diff threshold by default so a
- * normal v1 client does not need to repeat that value.
+ * The comparison policy is fail-closed by default: every client sends a policy
+ * derived from the existing `diff.threshold` (or the explicit
+ * `diff.comparisonPolicy` config override), and requires the Snap server to
+ * acknowledge it. A server that does not echo the policy back raises
+ * `SnapUpgradeRequiredError` for every operation — an unacknowledging server
+ * cannot silently get different comparison semantics.
  *
  * @param {VisualRegressionConfig} config
  * @returns {ComparisonPolicy}
@@ -639,7 +661,11 @@ function gitOutput(args) {
 export function resolveGitRef() {
   const branch = gitOutput(['rev-parse', '--abbrev-ref', 'HEAD']);
   return {
-    refBranch: process.env.GITHUB_REF_NAME || process.env.GITHUB_HEAD_REF || (branch && branch !== 'HEAD' ? branch : undefined) || 'main',
+    // Prefer GITHUB_HEAD_REF: on pull_request events GITHUB_REF_NAME is
+    // "<pr>/merge", which would misattribute the baseline branch in the
+    // dashboard and exported metadata. On push events GITHUB_HEAD_REF is
+    // unset, so GITHUB_REF_NAME (the pushed branch) applies.
+    refBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || (branch && branch !== 'HEAD' ? branch : undefined) || 'main',
     refSha: process.env.GITHUB_SHA || gitOutput(['rev-parse', 'HEAD']) || 'unknown'
   };
 }
@@ -930,14 +956,12 @@ export class SnapProvider {
           expectedCaptures
         },
         ...runContext,
-        ...(comparisonPolicy ? { comparisonPolicy } : {})
+        comparisonPolicy
       },
       idempotencyKey,
       operation
     );
-    if (comparisonPolicy) {
-      assertComparisonPolicyAcknowledged(runResponse?.comparisonPolicy, comparisonPolicy, 'Snap run creation');
-    }
+    assertComparisonPolicyAcknowledged(runResponse?.comparisonPolicy, comparisonPolicy, 'Snap run creation');
 
     // Submit each route as a capture with its own idempotency key
     for (const route of routes) {
@@ -1181,44 +1205,6 @@ export class SnapProvider {
     );
   }
 
-  /**
-   * Fetch the latest baseline from Snap.
-   *
-   * @param {FetchBaselineOptions} _options
-   * @returns {Promise<BaselineData | null>}
-   */
-  async fetchLatestBaseline(_options) {
-    const operation = this.#createOperationDeadline('baseline lookup');
-    try {
-      const baseline = await this.#request('GET', `/v1/visual/projects/${this.#projectId}/baselines/latest`, undefined, undefined, operation);
-
-      const runDir = await fs.mkdtemp(path.join(os.tmpdir(), 'snapdrift-snap-baseline-'));
-      const resultsPath = path.join(runDir, 'results.json');
-      const manifestPath = path.join(runDir, 'manifest.json');
-
-      if (baseline.results) {
-        await fs.writeFile(resultsPath, JSON.stringify(baseline.results, null, 2));
-      }
-      if (baseline.manifest) {
-        await fs.writeFile(manifestPath, JSON.stringify(baseline.manifest, null, 2));
-      }
-
-      return {
-        resultsPath,
-        manifestPath,
-        runDir,
-        screenshotsDir: path.join(runDir, 'screenshots'),
-        artifactName: baseline.artifactName || 'snap-baseline',
-        headSha: baseline.headSha || ''
-      };
-    } catch (error) {
-      if (error instanceof SnapApiError && error.status === 404) {
-        return null;
-      }
-      throw error;
-    }
-  }
-
   // ---------------------------------------------------------------------------
   // PR comment
   // ---------------------------------------------------------------------------
@@ -1238,42 +1224,23 @@ export class SnapProvider {
 
   // ---------------------------------------------------------------------------
   // Migration methods
+  //
+  // Removed:
+  // - `checkBaselineExists()` in 0.8.x — no production caller: the migration
+  //   workflows that queried baselines by SHA were retired with
+  //   `migrate-baselines`, and baseline resolution goes through the
+  //   `actions/resolve-baseline` artifact download instead of the API.
+  // - `migrateBaselineFromLocal()` in 0.7.0 — it POSTed a pre-built local
+  //   bundle (`manifest`/`results`/`screenshots` as objects) to the baselines
+  //   API, but the server never read those fields — the PNGs were never stored
+  //   and the manifest referenced local filenames rather than Snap object
+  //   keys, so the call could only ever produce an unexportable baseline. Snap
+  //   now rejects that body with `400 unsupported_baseline_body`
+  //   (i2Dev-com/snap#653). Use `publishBaseline()` after `capture()` — or the
+  //   `snapdrift baseline` command, which wires both together. See
+  //   ranacseruet/snapdrift#106.
   // ---------------------------------------------------------------------------
 
-  /**
-   * Check whether a baseline already exists for a given commit SHA.
-   *
-   * @param {string} headSha
-   * @returns {Promise<object | null>} Baseline data if found, null on 404
-   */
-  async checkBaselineExists(headSha) {
-    const operation = this.#createOperationDeadline('baseline existence check');
-    try {
-      const baseline = await this.#request(
-        'GET',
-        `/v1/visual/projects/${this.#projectId}/baselines/latest?sha=${encodeURIComponent(headSha)}`,
-        undefined,
-        undefined,
-        operation
-      );
-      return baseline;
-    } catch (error) {
-      if (error instanceof SnapApiError && error.status === 404) {
-        return null;
-      }
-      throw error;
-    }
-  }
-
-  // `migrateBaselineFromLocal()` was removed in 0.7.0. It POSTed a pre-built
-  // local bundle (`manifest`/`results`/`screenshots` as objects) to the
-  // baselines API, but the server never read those fields — the PNGs were never
-  // stored and the manifest referenced local filenames rather than Snap object
-  // keys, so the call could only ever produce an unexportable baseline. Snap now
-  // rejects that body with `400 unsupported_baseline_body` (i2Dev-com/snap#653).
-  // Use `publishBaseline()` after `capture()` — or the `snapdrift baseline`
-  // command, which wires both together. See ranacseruet/snapdrift#106.
-
   /**
    * Export baselines from Snap for local import.
    * Used by `snapdrift migrate-baselines --to local --from snap`.
@@ -1605,8 +1572,30 @@ export class SnapProvider {
     return error;
   }
 
-  /** @param {number} attempt @returns {number} */
-  #retryDelay(attempt) {
+  /**
+ * Compute the delay before the next retry attempt.
+ *
+ * When the server supplies a `Retry-After` header, that value is honored and
+ * clamped to the retry delay cap: delta-seconds are used as-is (including a
+ * deliberate immediate retry for `Retry-After: 0`), and RFC 9110 HTTP-date
+ * values are converted to a delay relative to the current clock. When the
+ * header is absent or malformed, exponential backoff applies.
+ *
+ * @param {number} attempt
+ * @param {string|number|null|undefined} [retryAfterHeader]
+ * @returns {number}
+ */
+  #retryDelay(attempt, retryAfterHeader) {
+    if (retryAfterHeader !== undefined && retryAfterHeader !== null && retryAfterHeader !== '') {
+      const retryAfterSeconds = Number(retryAfterHeader);
+      if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds >= 0) {
+        return Math.min(retryAfterSeconds * 1000, RETRY_DELAY_CAP_MS);
+      }
+      const retryAfterDate = Date.parse(String(retryAfterHeader));
+      if (!Number.isNaN(retryAfterDate)) {
+        return Math.min(Math.max(0, retryAfterDate - this.#nowFn()), RETRY_DELAY_CAP_MS);
+      }
+    }
     return Math.min(INITIAL_RETRY_DELAY_MS * RETRY_MULTIPLIER ** (attempt - 1), RETRY_DELAY_CAP_MS);
   }
 
@@ -1620,8 +1609,10 @@ export class SnapProvider {
   /**
    * Read and classify an HTTP error response under the current deadline.
    *
-   * A received 4xx remains non-retryable even when its diagnostic body cannot
-   * be read. Retryable 5xx body failures are returned to the transport loop so
+   * Most received 4xx remain non-retryable even when their diagnostic body
+   * cannot be read; transient statuses (429, 408) are retried by the caller
+   * and routed to the availability policy once retries are exhausted.
+   * Retryable 5xx body failures are returned to the transport loop so
    * they retain the normal availability semantics.
    *
    * @param {any} response
@@ -1647,13 +1638,19 @@ export class SnapProvider {
     }
 
     let detail = '';
+    let code;
     try {
       const parsed = JSON.parse(errorBody);
-      detail = parsed?.error || parsed?.message || '';
+      if (typeof parsed?.error === 'string') {
+        code = parsed.error;
+        detail = parsed.error;
+      } else if (typeof parsed?.message === 'string') {
+        detail = parsed.message;
+      }
     } catch {
       /* use default message */
     }
-    return new SnapApiError(response.status, detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`, requestPath);
+    return new SnapApiError(response.status, detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`, requestPath, code);
   }
 
   /**
@@ -1681,7 +1678,15 @@ export class SnapProvider {
     if (attemptRemaining <= 0) {
       controller.abort();
       cancelResponseBody(response);
-      throw this.#requestTimeoutError(requestPath, requestLimitMs, operation, requestLimitMs);
+      // The attempt deadline was already exhausted by the fetch phase, so no
+      // honest elapsed time is attributable to this body read. Say that,
+      // rather than reporting the request limit as if it had elapsed here.
+      const timeoutError = new SnapUnavailableError(
+        `Snap ${operation.label} request ${requestPath} attempt deadline elapsed before the response body could be read ` +
+          `(request limit ${requestLimitMs}ms; operation limit ${OPERATION_LIMIT_TEXT})`
+      );
+      timeoutError.name = 'SnapTransportTimeoutError';
+      throw timeoutError;
     }
     const remaining = Math.min(attemptRemaining, operationRemaining);
     return runWithTimeout(
@@ -1782,18 +1787,36 @@ export class SnapProvider {
           return await options.decode(response, controller, attemptDeadline, options.operation, options.requestTimeoutMs);
         }
 
-        // 4xx — non-retryable when the diagnostic body is available. A body
-        // read timeout still preserves the received HTTP status, rather than
-        // turning an already-classified API response into an availability retry.
+        // 4xx — non-retryable when the diagnostic body is available, except for
+        // transient statuses (429 rate limit, 408 request timeout) which retry
+        // with backoff and, once retries are exhausted, fall through to the
+        // onUnavailable availability policy like 5xx do. A quota-exhausted 429
+        // is permanent and stays a hard SnapApiError so the user learns the
+        // quota is spent. A body read timeout still preserves the received
+        // HTTP status, rather than turning an already-classified API response
+        // into an availability retry.
         if (response.status >= 400 && response.status < 500) {
-          throw await this.#readApiError(response, options.requestPath, controller, attemptDeadline, options.operation, options.requestTimeoutMs);
+          const apiError = await this.#readApiError(response, options.requestPath, controller, attemptDeadline, options.operation, options.requestTimeoutMs);
+          if (TRANSIENT_RETRYABLE_4XX.has(apiError.status) && !isQuotaExhaustedError(apiError)) {
+            if (attempt < MAX_RETRIES) {
+              cancelResponseBody(response);
+              await this.#sleepWithinOperation(
+                this.#retryDelay(attempt, response.headers?.get?.('retry-after')),
+                options.operation,
+                options.requestPath
+              );
+              continue;
+            }
+            return this.#handleUnavailable(apiError);
+          }
+          throw apiError;
         }
 
         // 5xx — retry with backoff unless this is the last attempt. Cancel
         // discarded response bodies so a slow server cannot retain a stream.
         if (attempt < MAX_RETRIES) {
           cancelResponseBody(response);
-          await this.#sleepWithinOperation(this.#retryDelay(attempt), options.operation, options.requestPath);
+          await this.#sleepWithinOperation(this.#retryDelay(attempt, response.headers?.get?.('retry-after')), options.operation, options.requestPath);
           continue;
         }
 
@@ -1917,8 +1940,28 @@ export class SnapProvider {
       outDir: options.outDir
     });
 
-    const localResults = JSON.parse(await fs.readFile(localCapture.resultsPath, 'utf-8'));
-    const manifest = JSON.parse(await fs.readFile(localCapture.manifestPath, 'utf-8'));
+    /** @type {any} */
+    let localResults;
+    try {
+      localResults = JSON.parse(await fs.readFile(localCapture.resultsPath, 'utf-8'));
+    } catch (error) {
+      throw new Error(
+        `Local capture results are unreadable at "${localCapture.resultsPath}"; recapture locally before uploading to Snap. ` +
+          `${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
+    /** @type {any} */
+    let manifest;
+    try {
+      manifest = JSON.parse(await fs.readFile(localCapture.manifestPath, 'utf-8'));
+    } catch (error) {
+      throw new Error(
+        `Local capture manifest is unreadable at "${localCapture.manifestPath}"; recapture locally before uploading to Snap. ` +
+          `${error instanceof Error ? error.message : String(error)}`,
+        { cause: error }
+      );
+    }
     // Route ids are unique per the v1 schema (one viewport per route), so keying
     // the manifest by id is an unambiguous join against the configured routes.
     const manifestById = new Map((manifest.screenshots || []).map((entry) => [entry.id, entry]));
@@ -2450,17 +2493,21 @@ export class SnapApiError extends Error {
   status;
   /** @type {string} */
   path;
+  /** Machine-readable error code from the API diagnostic body, when present. @type {string | undefined} */
+  code;
 
   /**
    * @param {number} status
    * @param {string} message
    * @param {string} path
+   * @param {string | undefined} [code]
    */
-  constructor(status, message, path) {
+  constructor(status, message, path, code) {
     super(message);
     this.name = 'SnapApiError';
     this.status = status;
     this.path = path;
+    this.code = code;
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",
@@ -85,7 +85,6 @@
     "./lib/snap-provider.mjs": "./lib/snap-provider.mjs",
      "./lib/migrate-baselines.mjs": "./lib/migrate-baselines.mjs",
      "./lib/init-from-action.mjs": "./lib/init-from-action.mjs",
-     "./lib/resolve-baseline-paths.mjs": "./lib/resolve-baseline-paths.mjs",
      "./lib/resolve-baseline-artifact.mjs": "./lib/resolve-baseline-artifact.mjs"
    },
   "files": [
@@ -103,12 +102,15 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@snapdrift/adapter-fs": "^1.7.2",
+    "@snapdrift/adapter-fs": "^1.8.0",
     "@snapdrift/adapter-report-md": "^1.4.0",
-    "@snapdrift/compare-core": "^1.8.0",
+    "@snapdrift/compare-core": "^1.8.1",
     "@snapdrift/manifest": "^1.8.0",
     "js-yaml": "^5.4.0",
-    "playwright": "^1.59.1",
+    "playwright": "^1.64.1",
     "pngjs": "^7.0.0"
+  },
+  "overrides": {
+    "brace-expansion@5": "^5.0.12"
   }
 }

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

@@ -257,8 +257,6 @@ export type {
   ProviderDiffResult,
   ProviderPublishBaselineOptions,
   ProviderPublishBaselineResult,
-  ProviderFetchBaselineOptions,
-  ProviderBaselineData,
   ProviderCommentMeta,
   VisualProvider,
   SnapConfig

package/lib/resolve-baseline-paths.mjs

@@ -1,40 +0,0 @@
-// @ts-check
-
-import path from 'node:path';
-
-/**
- * @typedef {{
- *   runDir: string,
- *   resultsFile: string,
- *   manifestFile: string,
- *   screenshotsDir: string,
- * }} BaselinePaths
- */
-
-/**
- * @typedef {{
- *   workspace: string,
- *   downloadPath?: string,
- * }} ResolveBaselinePathsParams
- */
-
-const DEFAULT_DOWNLOAD_PATH = 'snapdrift-baseline-download';
-
-/**
- * Resolve the baseline download paths for the resolve-baseline composite action.
- *
- * `downloadPath` may be absolute (used directly) or relative to the Actions
- * workspace (prefixed with `workspace`). Returns the run dir plus the results,
- * manifest, and screenshots paths derived from it.
- *
- * @param {ResolveBaselinePathsParams} params
- * @returns {BaselinePaths}
- */
-export function resolveBaselinePaths({ workspace, downloadPath }) {
-  const rel = downloadPath || DEFAULT_DOWNLOAD_PATH;
-  const runDir = path.isAbsolute(rel) ? rel : path.join(workspace, rel);
-  const resultsFile = path.join(runDir, 'results.json');
-  const manifestFile = path.join(runDir, 'manifest.json');
-  const screenshotsDir = path.join(path.dirname(manifestFile), 'screenshots');
-  return { runDir, resultsFile, manifestFile, screenshotsDir };
-}