snapdrift 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## Unreleased
+
+## 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.14.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.14.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@576e774845c29288a0061365e4905009533e0e01 # v0.14.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@576e774845c29288a0061365e4905009533e0e01 # v0.14.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,22 @@ 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
+`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 +331,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. 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.
+- 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 +383,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.14.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.14.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.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` |
 
 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.14.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.14.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.14.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,66 @@ 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;
+    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 +273,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 +2304,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.14.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.5.0",
+    "@snapdrift/adapter-report-md": "^1.4.0",
+    "@snapdrift/compare-core": "^1.5.0",
+    "@snapdrift/manifest": "^1.6.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,22 @@ 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;
 }
 
 export interface VisualRegressionRouteConfig {
@@ -52,6 +76,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 +135,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 +219,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. */