snapdrift 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## Unreleased
 
+## 0.15.0 - 2026-09-22
+
+Workspace releases this version:
+
+- `@snapdrift/compare-core` 1.6.0 — vertical-offset alignment when exact row
+  matching hits its edit cap, including alpha-aware highlighting and the
+  search memory caps.
+- `@snapdrift/manifest` 1.7.0 — `comparedOffset` on comparison row mappings.
+- `@snapdrift/adapter-fs` 1.6.0 — depends on that compare-core so local policy
+  v2 comparisons use the offset-run engine.
+
+`@snapdrift/adapter-report-md` stays 1.4.0. Root floors move to
+`@snapdrift/compare-core ^1.6.0`, `@snapdrift/manifest ^1.7.0`, and
+`@snapdrift/adapter-fs ^1.6.0`. The dispatcher pins `7b7b913`, the #179 merge
+commit on `main`, which contains the offset-run runtime loaded by both wrapper
+actions.
+
+### Features
+
+- Comparison policy v2, after exact row alignment hits its edit cap, maps long
+  vertical-offset runs so an insertion does not highlight the rest of a shifted
+  page. A matched row on that path was mapped and fell below the highlight
+  rule; it does not have to be byte-identical. When the compared row is one
+  pixel above or below the recorded current row, the mapping includes
+  `comparedOffset` (`-1` or `1`).
+- Offset highlighting includes alpha. Scoring ignores fully transparent pixels
+  and treats a large opacity change as a structured mismatch, so a small alpha
+  delta stays on the offset path.
+- The offset search rejects a page before allocating its score matrices when
+  those matrices would exceed 64 MB. It also samples every 32nd row first and
+  stops that sample once the page cannot be a correspondence, so a dissimilar
+  page falls back without scoring every offset. A dissimilar 1440×5622 pair
+  fell back in about 0.9s; scoring every offset on that pair took about 3.5s.
+- An offset canvas that would exceed `maxPixels` falls back to coordinate
+  comparison instead of throwing. The coordinate union can still throw when it
+  itself exceeds the limit.
+
 ## 0.14.0 - 2026-09-21
 
 Workspace releases this version:

package/README.md

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

package/action.yml

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

package/docs/contracts.md

@@ -293,10 +293,14 @@ the diff output bundle (for example `diffs/home.png`).
 Policy v2 comparison metadata additionally includes `policyVersion: 2` and
 `mode`. An aligned result has `mode: "vertical-aligned"` and a compact
 `rowMapping` describing matched, changed, inserted, and deleted row runs. A
-`mode: "coordinate-fallback"` result includes `fallbackReason` when widths,
-ignore regions, ambiguity, or the alignment resource limit prevent safe row
-alignment. The aligned canvas may be taller than either source image because
-inserted and deleted rows each occupy an output row.
+matched offset-run was mapped and fell below the highlight rule, so its rows
+need not be byte-identical. A segment may include `comparedOffset` of `-1` or
+`1` when the compared current row is one pixel away from `currentStart`; output
+row `i` was compared to current row `currentStart + i + comparedOffset`. A `mode: "coordinate-fallback"` result
+includes `fallbackReason` when widths, ignore regions, ambiguity, or the
+alignment resource limit prevent safe row alignment. The aligned canvas may be
+taller than either source image because inserted and deleted rows each occupy
+an output row.
 
 When a changed item has a generated local `diffImagePath`, its PR comment cell
 links to the uploaded report artifact (or the workflow run when no artifact URL
@@ -332,7 +336,7 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 - `diff.threshold` applies per screenshot
 - Missing captures are counted separately from drift signals
 - Comparison policy v1 `{ "version": 1, "threshold": number }` is deprecated but remains the compatibility default. Images are top-left aligned on a max-dimension union canvas with no scaling. Overlap pixels are compared, one-sided pixels count as changed (including transparent pixels), and empty union corners do not enter the denominator.
-- Comparison policy v2 `{ "version": 2, "threshold": number }` is opt-in. When source widths match and no ignore regions are requested, rows are fingerprinted and aligned with a bounded Myers sequence diff. Unchanged content that moves after an insertion/deletion remains matched; inserted current rows are green, deleted baseline rows are red, and actual pixel edits are orange. Width changes, ignore regions, ambiguous row matches, and resource limits fall back to v1 coordinate comparison and record the fallback reason. This is a raster row alignment aid, not DOM or arbitrary component matching.
+- Comparison policy v2 `{ "version": 2, "threshold": number }` is opt-in. When source widths match and no ignore regions are requested, rows are fingerprinted and aligned with a bounded Myers sequence diff. If that search hits its edit cap, long vertical-offset runs are mapped instead. Inside a run, a row may be compared one pixel above or below the recorded current row when that neighbor matches. `currentStart` still consumes each current row once, so that neighbor is not a separate insertion or deletion. When the compared row differs, the segment includes `comparedOffset` of `-1` or `1`: output row `i` was compared to current row `currentStart + i + comparedOffset`. On that offset-run path, a pixel whose red, green, blue, or alpha channel differs by 32 or less stays unhighlighted, so rendering noise and soft edges remain matched. A short cluster of larger channel deltas is an orange edit. A wide band of those pixels is a local mismatch: it is highlighted in place and does not discard the rest of the page. Unmatched baseline rows are red deletions. Current rows with no baseline partner are green insertions. `matched` on this path means the row was mapped and fell below this highlight rule. Exact fingerprint matches remain byte-identical. Width changes, ignore regions, ambiguous exact-row matches, and resource limits fall back to v1 coordinate comparison and record the fallback reason. This is a raster row alignment aid, not DOM or arbitrary component matching.
 - Both policies preserve the explicit dimension-change signal: a source height/width change remains a changed route even when the aligned mismatch ratio is at or below the threshold. Empty output corners do not enter the denominator.
 - Local diff images are rendered with a semantic palette: orange = changed pixels, green = added or inserted pixels, red = removed or deleted pixels. Equal-dimension strict diffs (`generateDiffImage`) use orange for changed pixels and cannot contain added/removed pixels. Reports render a legend whenever a local diff image is embedded; summaries that carry only comparison metadata (Snap provider runs, which render diffs hosted-side) render no legend.
 - `dimensionChanges[]` remains part of the summary contract but is empty for local comparisons in v1. Strict same-dimension comparison (`compareBuffers`) remains available to direct `@snapdrift/compare-core`/`comparePngs` callers that pass no policy.

package/docs/integration-guide.md

@@ -46,7 +46,7 @@ SnapDrift owns route selection, capture, comparison, skipped-report generation,
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift@v0.14.0
+  uses: ranacseruet/snapdrift@v0.15.0
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
@@ -71,7 +71,7 @@ Then add SnapDrift after the app is running:
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.14.0
+  uses: ranacseruet/snapdrift@v0.15.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -86,8 +86,8 @@ The wrappers remain published in their own right, and are equivalent to the disp
 
 | Entry point | Equivalent to |
 |-------------|---------------|
-| `ranacseruet/snapdrift@v0.14.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.14.0` |
-| `ranacseruet/snapdrift@v0.14.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.14.0` |
+| `ranacseruet/snapdrift@v0.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` |
 
 Use the wrappers directly when you want to skip the dispatcher's input indirection, and the lower-level `capture`, `compare`, `scope`, `resolve-baseline`, `stage`, `comment`, and `enforce` actions when you need to orchestrate the stages yourself.
 
@@ -130,7 +130,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.14.0
+        uses: ranacseruet/snapdrift@v0.15.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -170,7 +170,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.14.0
+        uses: ranacseruet/snapdrift@v0.15.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}

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

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

package/lib/snap-provider.mjs

@@ -226,6 +226,13 @@ function isComparisonMetadata(value) {
     }
     if (hasBaseline && (segment.baselineStart < 0 || segment.baselineStart + segment.length > baseline.height)) return false;
     if (hasCurrent && (segment.currentStart < 0 || segment.currentStart + segment.length > current.height)) return false;
+    if (segment.comparedOffset !== undefined) {
+      if (!hasBaseline || !hasCurrent || (segment.comparedOffset !== -1 && segment.comparedOffset !== 0 && segment.comparedOffset !== 1)) {
+        return false;
+      }
+      const comparedStart = segment.currentStart + segment.comparedOffset;
+      if (comparedStart < 0 || comparedStart + segment.length > current.height) return false;
+    }
     outputStart += segment.length;
     if (hasBaseline) baselineStart += segment.length;
     if (hasCurrent) currentStart += segment.length;

package/package.json

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

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

@@ -55,6 +55,12 @@ export interface ComparisonRowMapping {
   kind: ComparisonRowKind;
   baselineStart?: number;
   currentStart?: number;
+  /**
+   * Present when an offset-run row was compared one pixel above or below the
+   * recorded current row. Output row i was compared to current row
+   * `currentStart + i + comparedOffset`.
+   */
+  comparedOffset?: -1 | 0 | 1;
 }
 
 export interface VisualRegressionRouteConfig {