snapdrift 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 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:
+
+- `@snapdrift/compare-core` 1.5.0 — bounded vertical row alignment and comparison
+  policy v2, with conservative coordinate fallbacks and resource limits.
+- `@snapdrift/manifest` 1.6.0 — policy v2 validation, constants, and comparison types.
+- `@snapdrift/adapter-fs` 1.5.0 — local policy v2 comparison and summary types.
+- `@snapdrift/adapter-report-md` 1.4.0 — alignment and fallback details in Markdown,
+  HTML, and bounded PR comments.
+
+Root and workspace dependency floors require these versions so upgrades receive
+all parts of the policy v2 implementation. The dispatcher pins `576e774`, the
+#176 merge commit on `main`, including the runtime loaded by both wrapper actions.
+
+### Features
+
+- Added opt-in comparison policy v2 with bounded vertical row alignment for
+  inserted and deleted page rows. Unchanged content that shifts after an
+  insertion remains matched; reports record aligned results and conservative
+  coordinate fallbacks. Deprecated policy v1 remains the compatibility default
+  so existing configurations are unchanged; new configurations should use v2.
+
+- Snap-provider requests forward policy v2 and validate hosted acknowledgements
+  and alignment metadata. Hosted use requires matching Snap service support;
+  publishing this library does not deploy the hosted service.
+
 ## 0.13.0 - 2026-09-19
 
 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.13.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.13.0
+  uses: ranacseruet/snapdrift@v0.15.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -121,7 +121,7 @@ before pixels. Incompatible captures produce incomplete errors, not product drif
 - Viewport presets: `desktop` (1440×900) and `mobile` (390×844), or custom `{ "width": number, "height": number }`
 - Full-page comparisons are bounded to a 32 Mi-pixel union canvas; see the [screenshot size budget](docs/contracts.md#screenshot-size-budget) for viewport, device-scale, and remediation guidance
 - One global `diff.threshold`
-- Unequal dimensions compare on a top-left-aligned union canvas via comparison policy v1, which is always applied (synthesized from `diff.threshold` when `diff.comparisonPolicy` is absent)
+- Unequal dimensions use deprecated top-left union comparison policy v1 by default for compatibility; new configurations should opt into policy v2 with `{ "version": 2, "threshold": number }` for bounded vertical row alignment of inserted/deleted content
 - Local provider writes artifacts to the runner filesystem; for a hosted backend with a dashboard and a shared baseline store, configure `provider: "snap"` (see the [Integration Guide](docs/integration-guide.md#hosted-snap-provider))
 - Hosted Snap baselines publish only from the default branch and always include the complete configured route set
 

package/action.yml

@@ -155,7 +155,7 @@ runs:
     - name: SnapDrift baseline
       id: baseline
       if: inputs.mode == 'baseline'
-      uses: ranacseruet/snapdrift/actions/baseline@3967590687d420479ba5ec351e1394de174c1838 # v0.13.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@3967590687d420479ba5ec351e1394de174c1838 # v0.13.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

@@ -40,7 +40,7 @@ SnapDrift reads runtime behavior from `.github/snapdrift.json` by default.
 | `snap.apiKey` | `string` | Inline API key with `${VAR}` interpolation (mutually exclusive with `snap.apiKeyEnv`) |
 | `snap.projectId` | `string` | Snap project ID or `"auto"` (default: `"auto"`, derives from `GITHUB_REPOSITORY`) |
 | `snap.onUnavailable` | `string` | Behavior when Snap is unreachable: `"fail"` (default), `"warn-and-skip"`, or `"fallback-local"` |
-| `diff.comparisonPolicy` | `{ "version": 1, "threshold": number }` | Accepted for compatibility; comparison policy v1 is always applied when absent. `threshold` must match `diff.threshold` |
+| `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 `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.
 
@@ -155,7 +155,7 @@ The pull request drift bundle contains:
 | `current/results.json` | Current capture results |
 | `current/manifest.json` | Current manifest |
 | `current/screenshots/*.png` | Current images |
-| `diffs/*.png` | Generated v1 diff images for changed screenshots |
+| `diffs/*.png` | Generated v1 union or v2 aligned/fallback diff images for changed screenshots |
 
 ## Screenshot manifest shape
 
@@ -282,14 +282,26 @@ but still fails if other comparable routes changed.
 |:------|:-----|:------------|
 | `captureCompatibility` | `{ status, reason? }?` | Local profile-level compatibility: `verified`, `unverified`, or `incompatible`; route identity errors are separate |
 | `dashboardUrl` | `string?` | Snap dashboard URL for the run (set by `SnapProvider`; omitted by `LocalProvider`) |
-| `comparisonPolicy` | `{ "version": 1, "threshold": number }?` | Effective v1 comparison policy used by the local adapter (synthesized from `diff.threshold` when not configured) |
+| `comparisonPolicy` | `{ "version": 1 \| 2, "threshold": number }?` | Effective comparison policy used by the adapter (deprecated v1 is synthesized from `diff.threshold` when not configured) |
 
-When v1 comparison is applied, each affected `changed[]` item may also contain
+When a policy comparison is applied, each affected `changed[]` item may also contain
 `comparison` with `baseline`, `current`, and `canvas` `{ width, height }`
 objects, `dimensionsChanged`, and the effective `totalPixels` denominator. A
 local changed item with a generated image contains `diffImagePath`, relative to
 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
+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
 was supplied) and shows the bundle-relative path. It does not use that relative
@@ -323,8 +335,10 @@ 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 always applied. When `diff.comparisonPolicy` is absent, SnapDrift synthesizes it from `diff.threshold`. 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. Dimension changes land in `changed[]` with comparison metadata and a generated local diff image.
-- Local diff images are rendered with a semantic palette: orange = pixels that differ between baseline and current, green = pixels present only in the current capture (added), red = pixels present only in the baseline (removed). The palette is a rendering detail of `@snapdrift/compare-core` (`addedColor`/`removedColor`/`highlightColor` options); the frozen v1 comparison metrics are unaffected. 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.
+- 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 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.
 - 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
@@ -373,6 +387,11 @@ The comparator reports this condition with the stable error code
 dimensions in the error message. The ceiling that was exceeded is included too,
 since a caller may raise it per call.
 
+Policy v2 uses the aligned output height for this same budget. Because an
+inserted row and a deleted row each occupy an output row, that height can be up
+to the sum of the baseline and current heights. If the aligned canvas exceeds
+the budget, v2 returns `comparison_too_large` before allocating a diff image.
+
 `32 × 1024 × 1024` is the *default* ceiling, not an algorithm property. The cost
 is dominated by the decoded images: both RGBA inputs (4 bytes per pixel each) are
 retained plus, when the diff image is rendered (the default), a union-sized diff

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.13.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.13.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.13.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.13.0` |
-| `ranacseruet/snapdrift@v0.13.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.13.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.13.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.13.0
+        uses: ranacseruet/snapdrift@v0.15.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -309,10 +309,13 @@ See the [Local CLI guide](local-cli.md) for full command reference, flags, direc
 ## Refresh the baseline automatically
 
 After an intentional layout change merges, the baseline can be republished as
-usual. Local comparisons always apply comparison policy v1
-(`{ "version": 1, "threshold": number }`) — synthesized from `diff.threshold`
-when not configured — so unequal frames are compared on a union canvas and
-dimension metadata stays in the report.
+usual. Local comparisons retain deprecated policy v1
+(`{ "version": 1, "threshold": number }`) as the compatibility default —
+synthesized from `diff.threshold` when not configured — so unequal frames are
+compared on a union canvas and dimension metadata stays in the report. New
+configurations should set `diff.comparisonPolicy.version` to `2` to opt into
+bounded vertical row alignment; the report records aligned results and
+coordinate fallbacks.
 
 Use the provided workflow template to refresh the baseline automatically on every push to your default branch (i.e. every merge):
 
@@ -340,8 +343,11 @@ Grant `issues: write` and `pull-requests: write` to the job.
 The Snap client never retries 4xx and never falls back, even when `onUnavailable` is set. Inspect the response body — the most common cause is a project-id mismatch between `GITHUB_REPOSITORY` (auto-derived) and the project's id on Snap.
 
 **Screenshots have different dimensions**  
-SnapDrift compares the top-left-aligned union canvas, records the route in
-`changed[]`, and writes a local diff PNG. Refresh the baseline after an
+SnapDrift compares the top-left-aligned union canvas by default. Policy v2 can
+align equal-width rows so unchanged content after an insertion is not painted
+as drift; width changes, ignored regions, ambiguous rows, and resource limits
+fall back to coordinate comparison. Either policy records the route in
+`changed[]`, and local runs write a diff PNG. Refresh the baseline after an
 intentional change when you want future runs to return to equal-size
 comparisons.
 

package/docs/local-cli.md

@@ -345,14 +345,21 @@ The `Missing`, `Errors`, and `Dim diff` lines only print when their count is gre
 
 The `report.html` path is printed whenever the status is anything other than `clean`; pass `--open` to also launch it in your default browser.
 
-SnapDrift always applies comparison policy v1. It synthesizes the policy from
-`diff.threshold` when `diff` does not declare one, so the explicit opt-in is only
-needed to pin a non-default threshold:
+SnapDrift retains deprecated comparison policy v1 for compatibility unless an
+explicit v2 policy is configured. It synthesizes v1 from `diff.threshold` when
+`diff` does not declare one. New configurations should use v2:
 
 ```json
 "comparisonPolicy": { "version": 1, "threshold": 0.01 }
 ```
 
+Set `version` to `2` to enable bounded vertical row alignment for equal-width
+captures. Reports record aligned results and conservative coordinate fallbacks:
+
+```json
+"comparisonPolicy": { "version": 2, "threshold": 0.01 }
+```
+
 The report includes the baseline, current, and union-canvas dimensions in
 `summary.md` and `report.html`, and stores changed-route diff PNGs under
 `.snapdrift/diff/diffs/`. A completed dimension comparison is a normal changed

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

package/lib/snap-provider.mjs

@@ -10,6 +10,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 {
   selectConfiguredRoutes,
   splitCommaList,
@@ -148,7 +149,7 @@ function hostedDiffError(detail) {
 function isComparisonPolicy(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
   const policy = /** @type {Record<string, any>} */ (value);
-  return policy.version === 1 && typeof policy.threshold === 'number' && Number.isFinite(policy.threshold) && policy.threshold >= 0 && policy.threshold <= 1;
+  return (policy.version === 1 || policy.version === 2) && typeof policy.threshold === 'number' && Number.isFinite(policy.threshold) && policy.threshold >= 0 && policy.threshold <= 1;
 }
 
 /** @param {unknown} value @returns {value is ComparisonMetadata} */
@@ -170,15 +171,73 @@ function isComparisonMetadata(value) {
     return false;
   }
   const [baseline, current, canvas] = dimensions;
-  return (
+  const baseMetadataValid = (
     typeof comparison.dimensionsChanged === 'boolean' &&
     comparison.dimensionsChanged === (baseline.width !== current.width || baseline.height !== current.height) &&
-    canvas.width === Math.max(baseline.width, current.width) &&
-    canvas.height === Math.max(baseline.height, current.height) &&
     Number.isInteger(comparison.totalPixels) &&
-    comparison.totalPixels >= 0 &&
-    comparison.totalPixels <= canvas.width * canvas.height
+    comparison.totalPixels >= 0
   );
+  if (!baseMetadataValid) return false;
+  if (comparison.policyVersion !== undefined && comparison.policyVersion !== 2) return false;
+
+  if (comparison.policyVersion !== 2) {
+    if (comparison.mode !== undefined || comparison.rowMapping !== undefined || comparison.fallbackReason !== undefined) {
+      return false;
+    }
+    return (
+      canvas.width === Math.max(baseline.width, current.width) &&
+      canvas.height === Math.max(baseline.height, current.height) &&
+      comparison.totalPixels <= canvas.width * canvas.height
+    );
+  }
+
+  if (comparison.mode === 'coordinate-fallback') {
+    return (
+      comparison.rowMapping === undefined &&
+      COMPARISON_FALLBACK_REASONS.includes(comparison.fallbackReason) &&
+      canvas.width === Math.max(baseline.width, current.width) &&
+      canvas.height === Math.max(baseline.height, current.height) &&
+      comparison.totalPixels <= canvas.width * canvas.height
+    );
+  }
+
+  if (comparison.mode !== 'vertical-aligned' || comparison.fallbackReason !== undefined || !Array.isArray(comparison.rowMapping) || baseline.width !== current.width || canvas.width !== baseline.width) {
+    return false;
+  }
+  let outputStart = 0;
+  let baselineStart = 0;
+  let currentStart = 0;
+  for (const segment of comparison.rowMapping) {
+    if (!segment || !COMPARISON_ROW_KINDS.includes(segment.kind) || !Number.isInteger(segment.outputStart) || segment.outputStart !== outputStart || !Number.isInteger(segment.length) || segment.length <= 0) {
+      return false;
+    }
+    const hasBaseline = segment.kind === 'matched' || segment.kind === 'changed' || segment.kind === 'deleted';
+    const hasCurrent = segment.kind === 'matched' || segment.kind === 'changed' || segment.kind === 'inserted';
+    if (hasBaseline !== (Number.isInteger(segment.baselineStart)) || hasCurrent !== (Number.isInteger(segment.currentStart))) {
+      return false;
+    }
+    if (
+      (hasBaseline && segment.baselineStart !== baselineStart) ||
+      (!hasBaseline && segment.baselineStart !== undefined) ||
+      (hasCurrent && segment.currentStart !== currentStart) ||
+      (!hasCurrent && segment.currentStart !== undefined)
+    ) {
+      return false;
+    }
+    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;
+  }
+  return canvas.height === outputStart && baselineStart === baseline.height && currentStart === current.height && canvas.height >= Math.max(baseline.height, current.height) && canvas.height <= baseline.height + current.height && comparison.totalPixels === canvas.width * canvas.height;
 }
 
 /**
@@ -221,12 +280,17 @@ function comparisonFromCapture(capture) {
   return isComparisonMetadata(candidate) ? candidate : undefined;
 }
 
+/** @param {ComparisonMetadata} comparison @param {ComparisonPolicy} expected */
+function comparisonMatchesPolicy(comparison, expected) {
+  return expected.version === 2 ? comparison.policyVersion === 2 : comparison.policyVersion === undefined;
+}
+
 /** @param {unknown} actual @param {ComparisonPolicy} expected @param {string} context */
 function assertComparisonPolicyAcknowledged(actual, expected, context) {
-  if (!isComparisonPolicy(actual) || actual.threshold !== expected.threshold) {
+  if (!isComparisonPolicy(actual) || actual.version !== expected.version || actual.threshold !== expected.threshold) {
     throw new SnapUpgradeRequiredError(
-      `${context} did not acknowledge comparisonPolicy v1 with threshold ${expected.threshold}. ` +
-        'Upgrade the Snap server before enabling unequal-dimension comparisons.'
+      `${context} did not acknowledge comparisonPolicy v${expected.version} with threshold ${expected.threshold}. ` +
+        'Upgrade the Snap server before enabling this comparison policy.'
     );
   }
 }
@@ -2247,7 +2311,18 @@ export class SnapProvider {
           expected.routePath,
           expected.viewport,
           `Snap capture "${expected.routeId}" is missing complete comparison metadata; ` +
-            'upgrade the Snap server and diff Lambda before enabling comparisonPolicy v1.'
+            `upgrade the Snap server and diff Lambda before enabling comparisonPolicy v${comparisonPolicy.version}.`
+        );
+        continue;
+      }
+
+      if (comparisonPolicy && comparison && !comparisonMatchesPolicy(comparison, comparisonPolicy)) {
+        addError(
+          expected.routeId,
+          expected.routePath,
+          expected.viewport,
+          `Snap capture "${expected.routeId}" returned comparison metadata for a different policy than v${comparisonPolicy.version}; ` +
+            'upgrade the Snap server and diff Lambda before enabling this comparison policy.'
         );
         continue;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.13.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.4.0",
-    "@snapdrift/adapter-report-md": "^1.3.0",
-    "@snapdrift/compare-core": "^1.4.0",
-    "@snapdrift/manifest": "^1.5.0",
+    "@snapdrift/adapter-fs": "^1.6.0",
+    "@snapdrift/adapter-report-md": "^1.4.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

@@ -15,11 +15,19 @@ export interface VisualRegressionSelectionConfig {
   sharedExact?: string[];
 }
 
-export interface ComparisonPolicy {
+/** @deprecated Coordinate-based comparison policy. Retained for existing configurations; use `ComparisonPolicyV2` for new configurations. */
+export interface ComparisonPolicyV1 {
   version: 1;
   threshold: number;
 }
 
+export interface ComparisonPolicyV2 {
+  version: 2;
+  threshold: number;
+}
+
+export type ComparisonPolicy = ComparisonPolicyV1 | ComparisonPolicyV2;
+
 export interface ComparisonDimensions {
   width: number;
   height: number;
@@ -31,6 +39,28 @@ export interface ComparisonMetadata {
   canvas: ComparisonDimensions;
   dimensionsChanged: boolean;
   totalPixels: number;
+  policyVersion?: 2;
+  mode?: 'vertical-aligned' | 'coordinate-fallback';
+  rowMapping?: ComparisonRowMapping[];
+  fallbackReason?: ComparisonFallbackReason;
+}
+
+export type ComparisonFallbackReason = 'width-mismatch' | 'alignment-limit' | 'ambiguous' | 'verification-failed' | 'ignore-regions';
+export const COMPARISON_FALLBACK_REASONS: readonly ['width-mismatch', 'alignment-limit', 'ambiguous', 'verification-failed', 'ignore-regions'];
+export type ComparisonRowKind = 'matched' | 'changed' | 'inserted' | 'deleted';
+export const COMPARISON_ROW_KINDS: readonly ['matched', 'changed', 'inserted', 'deleted'];
+export interface ComparisonRowMapping {
+  outputStart: number;
+  length: number;
+  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 {
@@ -52,6 +82,7 @@ export interface VisualRegressionConfig {
   diff: {
     threshold: number;
     mode: 'report-only' | 'fail-on-changes' | 'fail-on-incomplete' | 'strict';
+    /** Deprecated v1 remains the compatibility default; new configurations should use v2. */
     comparisonPolicy?: ComparisonPolicy;
   };
   selection?: VisualRegressionSelectionConfig;
@@ -110,7 +141,7 @@ export interface SnapRunMetadata {
   runId: string;
   projectId: string;
   purpose: 'baseline' | 'capture' | 'diff';
-  /** Exact comparison policy acknowledged by Snap for updated clients. */
+  /** Exact comparison policy acknowledged by Snap; v1 is deprecated for compatibility. */
   comparisonPolicy?: ComparisonPolicy;
   /** CI source branch for hosted baseline runs; omitted for ordinary diff runs. */
   refBranch?: string;
@@ -194,6 +225,7 @@ export interface VisualDiffSummary {
   errors: VisualDiffErrorItem[];
   captureCompatibility?: import('@snapdrift/manifest').CaptureCompatibility;
   dimensionChanges: VisualDiffDimensionItem[];
+  /** The exact policy used for the comparison; v1 is deprecated and retained for compatibility. */
   comparisonPolicy?: ComparisonPolicy;
   message?: string;
   /** Link to the provider's run detail page. Set by SnapProvider during diff(); undefined for LocalProvider. */