snapdrift 0.12.0 → 0.14.0

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,10 +155,12 @@ 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
 
+Minimal legacy example (new local captures also write `captureProfile`):
+
 ```json
 {
   "generatedAt": "2024-01-01T00:00:00.000Z",
@@ -176,6 +178,75 @@ The pull request drift bundle contains:
 }
 ```
 
+### Local capture profile v2
+
+New local captures persist `captureProfile` with `schemaVersion: 2`. This version
+is independent of the outer manifest schema (which defaults to 1 when omitted)
+and comparison policy v1. The profile records:
+
+| Field | Local capture value |
+|:------|:--------------------|
+| `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 |
+| `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` |
+| `settings.context` | `isolation: "fresh-context-per-attempt"`, `colorScheme: "light"`, `reducedMotion: "no-preference"`, `forcedColors: "none"`, `javaScriptEnabled: true`, `serviceWorkers: "allow"` |
+| `settings.launch` | `headless: true`, `args: ["--disable-gpu"]` |
+
+These are persisted metadata, not new configuration knobs. Local v2 requires
+all listed fields with valid types/settings and matching engine version fields.
+Fonts are **not fingerprinted**: local capture does not populate the optional
+`fontsHash`, so a verified profile is not proof of identical installed fonts.
+Explicit `en-US` / `UTC` replaces environment-dependent defaults and may change
+localized text or dates; recapture affected baselines after upgrading.
+
+### Local compatibility before pixels
+
+Both manifests are validated after loading and before manifest entries are
+indexed and PNGs are resolved.
+Malformed manifests/profiles and unsupported profile schema versions (anything
+other than omitted, 1, or 2) throw before a comparison summary is generated;
+`report-only` does not suppress these input errors.
+
+- Two local v2 profiles must match exactly across the full profile, including
+  extra fields. Object key order is ignored; array order and values matter.
+  There is no version tolerance: adapter, Playwright, browser, or OS updates can
+  require a baseline refresh. The reason identifies the first differing field.
+- For each selected configured route id present in both manifests, both entries
+  must have the exact configured `path` and the same normalized viewport as the
+  config: width, height, device scale factor, mobile, and touch. Paths are not
+  URL-normalized; `baseUrl` and timestamps are not compared. Custom viewports use
+  scale 1, mobile false, touch false: 1440×900 equals `desktop`, but 390×844 does
+  not equal `mobile`. Missing entries retain their missing/error classification.
+- A profile or route-identity mismatch adds an `errors[]` item with
+  `status: "error"` and `code: "incompatible_capture"`. That route's PNGs are
+  not resolved, read, or pixel-compared, even if they would be byte-identical.
+  The summary is `incomplete`, not product drift. With compatible identity,
+  changed full-page raster dimensions remain normal union-canvas `changed[]`
+  signals, independent of threshold.
+- Missing profiles or profiles with omitted/v1 schema remain usable but
+  `unverified`, with a warning in `summary.message`; pixels can still be compared
+  after route checks. If both profiles provide `browser`, `browserRevision`,
+  `fontsHash`, `timezone`, or `locale`, a difference in any shared field is
+  incompatible. An explicit foreign `engine.name` on either side is incompatible
+  even when the other profile is absent. Legacy engine versions alone do not
+  establish verified compatibility.
+
+`summary.captureCompatibility` contains profile-level `status` (`verified`,
+`unverified`, or `incompatible`) and an optional `reason`. It is **not** an
+aggregate route status: profiles can be `verified` while route path/viewport
+checks produce `incompatible_capture` errors. Unverified alone does not make a
+run incomplete or fail enforcement.
+
+Refresh the baseline using the [existing CLI or baseline action](local-cli.md#refreshing-or-acknowledging-local-baselines)
+in the intended capture environment. For intentional nonblocking acknowledgement,
+set `diff.mode` to `report-only`: it preserves incompatibility errors and never
+overrides compatibility to compare pixels. `fail-on-incomplete` and `strict`
+fail on those errors; `fail-on-changes` does not fail on incompatibility alone
+but still fails if other comparable routes changed.
+
 ## Summary shape
 
 ```json
@@ -209,15 +280,24 @@ The pull request drift bundle contains:
 
 | Field | Type | Description |
 |:------|:-----|:------------|
+| `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
@@ -247,11 +327,14 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 
 ## Drift semantics
 
-- Screenshots are matched by `id`
+- Screenshots are matched by `id`; local profile and configured path/normalized viewport compatibility are checked before pixels (see [Local compatibility before pixels](#local-compatibility-before-pixels))
 - 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.
+- 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
@@ -260,7 +343,7 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 
 | Mode | Stops the run when |
 |:-----|:-------------------|
-| `report-only` | Never |
+| `report-only` | Never from summary enforcement; validation/capture failures still fail |
 | `fail-on-changes` | `changedScreenshots > 0` |
 | `fail-on-incomplete` | Errors or missing captures occur; a completed v1 dimension comparison alone does not fail |
 | `strict` | Any drift or incomplete comparison appears |
@@ -300,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
@@ -349,6 +437,14 @@ that matches the product behavior. Do not resize or crop screenshots, or lower
 | Screenshot animations | `disabled` (Playwright finishes/cancels CSS animations before capture) |
 | Capture concurrency | 5 routes per viewport (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,
+even when routes share a viewport or run serially. This also applies to Snap's
+local-capture hybrid, not to rendering performed by the hosted service. Viewport
+groups still run concurrently, with the configured limit applied per group.
+Previously leaked storage may have affected existing baselines; recapture them
+after upgrading if storage-dependent UI produces a one-time change.
+
 ## Local CLI directory layout
 
 When using the `snapdrift` CLI, outputs are written to `.snapdrift/` by default:
@@ -541,6 +637,50 @@ The wrapper actions (`actions/baseline`, `actions/pr-diff`) and the CLI both han
 request or response body is being bounded. It is not an additional public
 error class; callers should handle the exported error classes above.
 
+## Shared orchestration
+
+GitHub-facing request handling is shared between the wrapper and standalone
+actions through `lib/github-requests.mjs`. The github-script steps stay as thin
+adapters that load the module, inject `{ github, owner, repo, context }`-style
+inputs, and map the returned decision to step outputs:
+
+- `fetchPullRequestFiles` paginates `pulls.listFiles` (100 per page) and
+  validates each record's `filename` before any scope decision is made.
+- `resolveScopeDecision` is pure: renamed files contribute
+  `previous_filename`, paths are deduplicated, 3000+ records short-circuit to
+  running all routes (`changed_files_truncated`), and an empty list maps to
+  `no_changed_files`. Other reasons come from
+  `selectRoutesForChangedFiles`.
+- `resolvePullRequestScope` composes the above with the
+  explicit-route/force-run/missing-PR shortcuts and the
+  `snapdrift_scope_check_failed` fallback warning.
+- `upsertPullRequestReportComment` performs the marker-filtered, newest-first
+  comment upsert with duplicate deletion used by `actions/comment` and the
+  `actions/pr-diff` report step. The create-only "Capture Failed" /
+  "Baseline Lookup Failed" fallback body remains inline in `actions/pr-diff`.
+
+The baseline resolver keeps its own module (`lib/resolve-baseline-artifact.mjs`)
+because both actions already share it verbatim.
+
+### Capture artifact capabilities
+
+Providers now return `artifacts` on capture results, attached in the provider layer
+rather than adapter-fs:
+
+- `localScreenshots`: whether PNGs are available locally for pixel comparison.
+- `artifactsRoot`: the capture's `screenshotsRoot` for local and Snap hybrid
+  captures (`localScreenshots: true`); `undefined` for hosted remote captures
+  (`localScreenshots: false`), even though their metadata has a local path.
+
+`captureWithPolicy` prefers `result.artifacts` over provider-name/base-URL inference.
+For `diffWithPolicy`, pass the capture as `captureResult` or forward its `artifacts`.
+Precedence is the legacy `options.localScreenshots` boolean (if supplied), then
+`options.artifacts`, then `captureResult.artifacts`, then provider/config inference.
+The boolean overrides only `localScreenshots`; false clears `artifactsRoot`.
+Inference remains for legacy results without a descriptor when config is supplied.
+If no capability arguments, result descriptor, or config are supplied to
+`diffWithPolicy`, it preserves the legacy local-screenshots default without recapture.
+
 ## Primary entrypoints
 
 - `actions/baseline`
@@ -567,7 +707,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 context (positive integer, default `5`). Set to `1` to restore serial behaviour for apps with shared session/auth state. |
+| `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. |
 
 ## PR comment markdown shape
 

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.12.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.12.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.12.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.12.0` |
-| `ranacseruet/snapdrift@v0.12.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.12.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.12.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.12.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

@@ -203,6 +203,61 @@ The `--open` flag opens the HTML report in your default browser when the diff is
 
 ---
 
+## Refreshing or acknowledging local baselines
+
+New local manifests record a [v2 capture profile](contracts.md#local-capture-profile-v2)
+with exact engine, Playwright/browser, OS, locale/timezone, and rendering settings.
+Manifests are validated after loading; then, before resolving PNGs, comparison
+checks the profiles and each selected route's id, exact configured path, and
+normalized viewport. A mismatch produces an
+`incompatible_capture` error and an `incomplete` summary, not a pixel drift
+signal. Matching profiles can still have route-identity errors:
+`summary.captureCompatibility.status` describes profiles only.
+
+To refresh, serve the intended accepted application state using the same capture
+environment and route config as future diffs. With `provider: "local"`, run:
+
+```bash
+snapdrift baseline --config .github/snapdrift.json --baseline-dir .snapdrift/baseline
+```
+
+This overwrites baseline metadata and captured screenshots; `snapdrift capture`
+with the same options is equivalent for the local provider. Capture all routes
+for a complete replacement, without `--routes` or `SNAPDRIFT_ROUTE_IDS` scoping.
+Then serve the candidate application state and run:
+
+```bash
+snapdrift diff --config .github/snapdrift.json --baseline-dir .snapdrift/baseline --open
+```
+
+In CI, run the existing default-branch baseline workflow using the root action's
+`mode: baseline` ([Quickstart](../README.md#quickstart)) or `actions/baseline`.
+Use the same upgraded SnapDrift/action revision and runner environment for
+baseline and PR captures, with artifact upload enabled; then rerun the PR diff.
+A baseline captured on a different OS is not interchangeable merely because
+both commands use Playwright.
+
+For intentional nonblocking acknowledgement, set `diff.mode` to `report-only`
+in the config and rerun `snapdrift diff --open`. This keeps the incompatibility
+errors visible and **never overrides compatibility to compare pixels**; there
+is no diff acceptance flag. `fail-on-incomplete` and `strict` fail on these
+errors; `fail-on-changes` fails only if other comparable routes changed. Once
+identity is compatible, a changed full-page PNG size is normal product drift,
+not incompatibility, and fails `fail-on-changes` / `strict` even below threshold.
+
+Legacy manifests with missing profiles or omitted/v1 profile schema remain
+pixel-comparable after route checks, but report `unverified` with a warning.
+Conflicting shared browser/revision, fonts hash, locale, or timezone fields, or
+an explicit foreign engine on either side, are still incompatible. Malformed
+manifests/profiles and unsupported profile schema versions abort comparison,
+even in `report-only`; refresh rather than editing metadata to force a match.
+
+Local capture now explicitly uses `en-US` and `UTC`; localized text/date changes
+may require recapture after upgrading. Fonts are not fingerprinted, so keep
+installed fonts consistent even when profiles are verified.
+
+---
+
 ## Local directory layout
 
 After running `capture` and `diff` with default paths:
@@ -239,7 +294,7 @@ Add `.snapdrift/` to your `.gitignore` to keep local run output out of version c
 | `0` | Clean — no drift above threshold, `diff.mode` is `report-only`, the command was intentionally skipped under `onUnavailable: "warn-and-skip"` (`diff`, `capture` and `baseline` all exit 0 in that case), or the command was a `capture` / `baseline` / `migrate-baselines --to local` / `init` that completed |
 | `1` | Drift enforced — `diff.mode` caused the run to fail, a required command argument was missing, or the `--to local` engine-name check failed (see [Drift modes](../README.md#drift-modes)) |
 
-Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. Set `"mode": "report-only"` during local development to always get a report without a failing exit code.
+Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. Set `"mode": "report-only"` for nonblocking report inspection; capture, input-validation, and other command failures still exit 1 and can prevent report generation.
 
 ---
 
@@ -290,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
@@ -310,7 +372,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 context, and per-route resolve/compare during `diff`. Set to `1` to restore serial behavior for apps with shared session or auth state. |
+| `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_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

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

package/lib/cli.mjs

@@ -214,6 +214,10 @@ export function printSummary(summary) {
   if (errors > 0) process.stdout.write(`   Errors:   ${errors}\n`);
   if (dimensionChanges > 0) process.stdout.write(`   Dim diff: ${dimensionChanges}\n`);
 
+  if (summary.captureCompatibility?.status === 'unverified' && summary.message) {
+    process.stdout.write(`   Note: ${summary.message}\n`);
+  }
+
   if (summary.changed?.length) {
     process.stdout.write('\n   Changed routes:\n');
     for (const item of summary.changed) {

package/lib/github-requests.mjs

@@ -0,0 +1,134 @@
+// @ts-check
+
+import { selectConfiguredRoutes, selectRoutesForChangedFiles, splitCommaList } from './snapdrift-config.mjs';
+
+/** @typedef {import('../types/visual-diff-types').VisualRegressionConfig} VisualRegressionConfig */
+/** @typedef {{ filename: string, status?: string, previous_filename?: string }} PullRequestFile */
+/** @typedef {ReturnType<typeof selectRoutesForChangedFiles>} ScopeDecision */
+/** @typedef {{ paginate: Function, rest: { pulls: { listFiles: Function } } }} ScopeGitHubClient */
+/**
+ * @typedef {{
+ *   paginate: Function,
+ *   rest: { issues: {
+ *     listComments: Function,
+ *     createComment: Function,
+ *     updateComment: Function,
+ *     deleteComment: Function
+ *   } }
+ * }} CommentGitHubClient
+ */
+
+/**
+ * @param {{ github: ScopeGitHubClient, owner: string, repo: string, pullNumber: number }} options
+ * @returns {Promise<PullRequestFile[]>}
+ */
+export async function fetchPullRequestFiles({ github, owner, repo, pullNumber }) {
+  const files = await github.paginate(github.rest.pulls.listFiles, {
+    owner,
+    repo,
+    pull_number: pullNumber,
+    per_page: 100
+  });
+  if (!Array.isArray(files)) {
+    throw new Error('Malformed GitHub changed-file response: expected an array of file records.');
+  }
+  for (const [index, file] of files.entries()) {
+    if (!file || typeof file !== 'object' || typeof file.filename !== 'string' || file.filename.length === 0) {
+      throw new Error(`Malformed GitHub changed-file response: file record ${index} must include a non-empty string filename.`);
+    }
+  }
+  return files;
+}
+
+/**
+ * @param {{ config: VisualRegressionConfig, files: PullRequestFile[] }} options
+ * @returns {ScopeDecision}
+ */
+export function resolveScopeDecision({ config, files }) {
+  if (files.length >= 3000) {
+    return { shouldRun: true, reason: 'changed_files_truncated', selectedRouteIds: (config.routes || []).map((route) => route.id) };
+  }
+  const changedFiles = [...new Set(files.flatMap((file) => [
+    file.filename,
+    ...(file.status === 'renamed' && typeof file.previous_filename === 'string' && file.previous_filename
+      ? [file.previous_filename]
+      : [])
+  ]))];
+  return selectRoutesForChangedFiles(config, changedFiles);
+}
+
+/**
+ * @param {{
+ *   github: ScopeGitHubClient,
+ *   owner: string,
+ *   repo: string,
+ *   config: VisualRegressionConfig,
+ *   pullNumber: number,
+ *   routeIds?: string,
+ *   forceRun?: boolean,
+ *   forceRunReason?: string,
+ *   warning?: (message: string) => void
+ * }} options
+ * @returns {Promise<ScopeDecision>}
+ */
+export async function resolvePullRequestScope({ github, owner, repo, config, pullNumber, routeIds = '', forceRun = false, forceRunReason = 'forced', warning = (_message) => {} }) {
+  const allRouteIds = (config.routes || []).map((route) => route.id);
+  const explicitRouteIds = splitCommaList(routeIds);
+  if (explicitRouteIds.length > 0) {
+    const selected = selectConfiguredRoutes(config, explicitRouteIds);
+    return { shouldRun: true, reason: 'explicit_route_ids', selectedRouteIds: selected.selectedRouteIds };
+  }
+  if (forceRun) {
+    return { shouldRun: true, reason: forceRunReason || 'forced', selectedRouteIds: allRouteIds };
+  }
+  if (!Number.isFinite(pullNumber) || pullNumber <= 0) {
+    return { shouldRun: true, reason: 'missing_pr_number', selectedRouteIds: allRouteIds };
+  }
+  try {
+    const files = await fetchPullRequestFiles({ github, owner, repo, pullNumber });
+    const scope = resolveScopeDecision({ config, files });
+    if (scope.reason === 'changed_files_truncated') {
+      warning('GitHub returned the maximum 3000 changed-file records; the list may be truncated, so running all configured captures.');
+    }
+    return scope;
+  } catch (error) {
+    warning(`Unable to inspect PR files for SnapDrift scope; running all configured captures instead. ${error.message}`);
+    return { shouldRun: true, reason: 'snapdrift_scope_check_failed', selectedRouteIds: allRouteIds };
+  }
+}
+
+/**
+ * @param {{
+ *   github: CommentGitHubClient,
+ *   owner: string,
+ *   repo: string,
+ *   issueNumber: number,
+ *   body: string,
+ *   markers: readonly string[]
+ * }} options
+ * @returns {Promise<void>}
+ */
+export async function upsertPullRequestReportComment({ github, owner, repo, issueNumber, body, markers }) {
+  const comments = await github.paginate(github.rest.issues.listComments, {
+    owner,
+    repo,
+    issue_number: issueNumber,
+    per_page: 100
+  });
+  const matchingComments = comments
+    .filter((comment) => comment.body && markers.some((marker) => comment.body.includes(marker)))
+    .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();
+      return rightTime - leftTime;
+    });
+  const existing = matchingComments[0];
+  if (existing) {
+    await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+  } else {
+    await github.rest.issues.createComment({ owner, repo, issue_number: issueNumber, body });
+  }
+  for (const duplicate of matchingComments.slice(1)) {
+    await github.rest.issues.deleteComment({ owner, repo, comment_id: duplicate.id });
+  }
+}