snapdrift 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## 0.12.0 - 2026-09-16
+
+### Fixes
+
+- **PR comments no longer render `[object Object]` for a viewport.** A viewport is
+  either a preset name or a `{ width, height }` object, and the PR-comment renderer
+  stringified it directly. Hosted diff runs always build the object form, so every
+  hosted report printed the useless placeholder in its Error, Drift signals, and
+  Dimension shifts tables. All three report renderers now share one
+  `formatViewport` helper (exported from `@snapdrift/adapter-report-md`).
+
+### Features
+
+- **`compareImages` accepts a per-call `maxPixels` union-canvas ceiling.**
+  `MAX_COMPARISON_PIXELS` (32 Mi) is a *process memory* bound, not an algorithm
+  property, so callers with a larger envelope — a dedicated diff Lambda — can raise
+  it while callers sharing a small host keep the default. A missing, non-positive,
+  or non-finite value falls back to the default, so the guard cannot be removed by
+  accident. The `ComparisonTooLargeError` message now reports the ceiling that was
+  actually exceeded.
+
+### Documentation
+
+- Document that `migrate-baselines --to snap` is unsupported and point to
+  `snapdrift baseline` as the supported way to seed a hosted project. The
+  integration guide still described the retired upload direction as a working
+  one-shot command, and the contracts reference documented its request body,
+  idempotency, and storage behavior as if it succeeded. Both contradicted the
+  CLI, which has failed the direction since 0.7.0 with a pointer to
+  `snapdrift baseline`.
+- Document the screenshot size budget's memory cost for `maxPixels` callers: the
+  comparison retains both decoded RGBA inputs plus the optional diff canvas, so the
+  floor is roughly 12 bytes per union pixel before PNG overhead (~32-35 measured end
+  to end), and the ceiling should be sized against a measured peak rather than that
+  arithmetic.
+
+### Workspace packages
+
+- `@snapdrift/adapter-report-md` 1.2.1 publishes the `[object Object]` viewport fix;
+  `@snapdrift/compare-core` 1.3.0 publishes the per-call `maxPixels` option and the
+  new size-budget guidance.
+- The root package's dependency floors move to `^1.2.1` (adapter-report-md) and
+  `^1.3.0` (compare-core) so `snapdrift` 0.12.0 actually requires those fixes. A
+  retained lockfile resolution of adapter-report-md 1.2.0 still satisfies `^1.2.0`,
+  so without the floor bump an upgrade of `snapdrift` alone could install the
+  unfixed report renderer.
+
+## 0.11.0 - 2026-09-14
+
+### Behavior changes
+
+- **Local comparisons now always use comparison policy v1.** `generateDriftReport`
+  synthesizes `{ "version": 1, "threshold": diff.threshold }` when neither the
+  caller nor `diff.comparisonPolicy` supplies a policy, matching the CLI and both
+  providers. Dimension mismatches are now `changed[]` signals with union-canvas
+  metadata instead of `dimensionChanges[]` (which stays in the summary contract
+  but is empty for local comparisons). The strict same-dimension comparator
+  remains available to direct `@snapdrift/compare-core` / `comparePngs` callers
+  that pass no policy.
+
+### Performance
+
+- `compareImages` short-circuits byte-identical buffers and can skip rendering
+  the diff PNG via `renderDiffImage: false`; drift reports only render diff
+  images for changed routes and resolve/read route PNGs concurrently.
+- Union-canvas size limits are now checked against the PNG IHDR header before
+  decoding, so oversized images are rejected before allocating decoded buffers.
+
+### Fixes
+
+- `compareImages`, `generateDiffImage`, and `compareWithIgnoreRegions` now reject
+  malformed ignore regions and highlight colors instead of silently masking
+  nothing or coercing `undefined` channels.
+
+### Features
+
+- **Workspace packages** — publish `@snapdrift/compare-core` 1.2.0 and
+  `@snapdrift/adapter-fs` 1.3.0 with the new comparison options, validation, and
+  performance behavior. The new `renderDiffImage: false` option is surfaced
+  through a separate overload, so existing `compareImages` / `comparePngs`
+  callers keep a non-optional `diffImageBuffer` with no type or runtime change.
+
+### Documentation
+
+- Document the full-page screenshot pixel budget, viewport/device-scale
+  estimates, custom-viewport semantics, and remediation for
+  `comparison_too_large` failures.
+
 ## 0.10.0 - 2026-09-10
 
 ### Fixes

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.10.0
+  uses: ranacseruet/snapdrift@v0.12.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.10.0
+  uses: ranacseruet/snapdrift@v0.12.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -107,7 +107,7 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 |------|--------------------|
 | `report-only` | Never |
 | `fail-on-changes` | Any capture exceeds threshold |
-| `fail-on-incomplete` | Captures are missing, dimensions shift, or comparison errors occur |
+| `fail-on-incomplete` | Captures are missing or comparison errors occur |
 | `strict` | Any drift signal or incomplete comparison appears |
 
 ## Current constraints
@@ -115,8 +115,9 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 - Ubuntu runners only (local CLI works on any OS Node 22+ supports)
 - Full-page capture only
 - 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 remain strict by default; local updated clients may opt in with `diff.comparisonPolicy: { "version": 1, "threshold": number }`
+- 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)
 - 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@80d61b668942dd87c33cf51598623a904becf82f # v0.10.0
+      uses: ranacseruet/snapdrift/actions/baseline@e4b92c2243c6e69594cab7405f68eb58fe94587e # v0.12.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@80d61b668942dd87c33cf51598623a904becf82f # v0.10.0
+      uses: ranacseruet/snapdrift/actions/pr-diff@e4b92c2243c6e69594cab7405f68eb58fe94587e # v0.12.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 }` | Optional local opt-in to top-left-aligned unequal-dimension comparison; absent preserves strict legacy dimension handling |
+| `diff.comparisonPolicy` | `{ "version": 1, "threshold": number }` | Accepted for compatibility; comparison policy v1 is always applied when absent. `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.
 
@@ -210,9 +210,9 @@ The pull request drift bundle contains:
 | Field | Type | Description |
 |:------|:-----|:------------|
 | `dashboardUrl` | `string?` | Snap dashboard URL for the run (set by `SnapProvider`; omitted by `LocalProvider`) |
-| `comparisonPolicy` | `{ "version": 1, "threshold": number }?` | Exact v1 comparison policy used by the local adapter when opted in |
+| `comparisonPolicy` | `{ "version": 1, "threshold": number }?` | Effective v1 comparison policy used by the local adapter (synthesized from `diff.threshold` when not configured) |
 
-When v1 comparison is enabled, each affected `changed[]` item may also contain
+When v1 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
@@ -229,7 +229,7 @@ path as a GitHub-hosted image URL.
 |:-------|:--------|
 | `clean` | All captures matched within threshold |
 | `changes-detected` | One or more captures exceeded threshold |
-| `incomplete` | Missing captures, dimension shifts, or comparison errors occurred |
+| `incomplete` | Missing captures or comparison errors occurred |
 | `skipped` | The report was intentionally skipped |
 
 ### Skipped summary
@@ -251,9 +251,9 @@ 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
-- Without `diff.comparisonPolicy`, dimension mismatches skip pixel comparison and land in `dimensionChanges[]`.
-- With the exact v1 policy `{ "version": 1, "threshold": number }`, 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.
-- For v1, `diff.comparisonPolicy.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.
+- 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.
+- `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
 
 ## Drift modes
@@ -278,6 +278,67 @@ directly, not just for the guarded enforcement step inside `actions/pr-diff`.
 | `desktop` | 1440 | 900 | 1 | No | No |
 | `mobile` | 390 | 844 | 3 | Yes | Yes |
 
+## Screenshot size budget
+
+SnapDrift compares full-page screenshots using their rendered raster dimensions.
+The unequal-dimension comparator bounds the union canvas at `32 × 1024 × 1024`
+pixels (`33,554,432` pixels). A comparison is oversized when:
+
+```text
+max(baselineWidth, currentWidth) × max(baselineHeight, currentHeight) > 33,554,432
+```
+
+This is a raster-pixel limit, not a direct CSS viewport limit. Full-page capture
+height is the document height, and `deviceScaleFactor` increases both raster
+width and raster height. The baseline/current union also means that a dimension
+change can make an otherwise valid image exceed the budget. Leave headroom for
+horizontal overflow or other layout changes that increase the rendered image
+dimensions.
+
+The comparator reports this condition with the stable error code
+`comparison_too_large` and includes the baseline, current, and union-canvas
+dimensions in the error message. The ceiling that was exceeded is included too,
+since a caller may raise it per call.
+
+`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
+canvas — at least ~12 bytes per union pixel when both inputs approach the union
+dimensions, before PNG decode/encode overhead. Measured end-to-end RSS on real
+full-page captures is ~32-35 bytes per union pixel (~1.16 GB at 33.8 M pixels,
+~3.37 GB at 103.9 M), so the default bounds a comparison to a process with a few
+GB of headroom.
+
+Direct `@snapdrift/compare-core` callers running in a larger memory envelope can
+pass `compareImages(..., { maxPixels })` to raise it for that call. **Size
+`maxPixels` against your own measured peak**, not against the byte-per-pixel
+arithmetic: PNG decode and encode overhead, GC, and concurrency all add to it. A
+missing, non-finite, or sub-1 `maxPixels` falls back to the default; fractions are
+floored (`16.9` becomes `16`). The sub-1 rule matters because a positive fraction
+such as `0.5` floors to `0`, which would otherwise reject every comparison.
+SnapDrift's own local and hosted paths keep the default, because the host process
+— not the image — decides how much memory is actually safe.
+
+Approximate maximum full-page CSS heights below
+assume that the raster width remains equal to the configured CSS width and that
+the document height scales by the same device scale factor:
+
+| Configuration | CSS viewport | Scale factor | Approx. maximum full-page CSS height |
+|:--------------|:-------------|-------------:|-------------------------------------:|
+| `desktop` preset | 1440 × 900 | 1 | 23,301 px |
+| `mobile` preset | 390 × 844 | 3 | 9,559 px |
+| Custom 390 × 844 viewport | 390 × 844 | 1 | 86,037 px |
+
+These are planning estimates, not guarantees. Check the actual `width` and
+`height` recorded in the capture results or screenshot manifest, then apply the
+union-canvas formula above. A custom viewport object currently uses scale factor
+1 with `isMobile: false` and `hasTouch: false`; it is therefore not equivalent
+to the named `mobile` preset. Use it to avoid unnecessary raster inflation only
+when the route does not require mobile device emulation. Otherwise, reduce the
+captured document or fixture height, or split the coverage across routes when
+that matches the product behavior. Do not resize or crop screenshots, or lower
+`diff.threshold`, to work around this limit.
+
 ## Capture defaults
 
 | Setting | Value |
@@ -314,18 +375,16 @@ All three directories can be overridden with `--baseline-dir`, `--current-dir`,
 
 ### migrate-baselines
 
-Migrate baselines between local storage and Snap. Both directions require a `snap` block in `snapdrift.json` (or `--to local` for the `snap → local` direction, since the export call still talks to Snap first).
+Move baselines between local storage and Snap. Only the `snap → local` direction is supported; it requires a `snap` block in `snapdrift.json` (the export call talks to Snap).
 
-**Upload local baselines to Snap:**
+**Upload local baselines to Snap — not supported:**
 
 ```
-snapdrift migrate-baselines --to snap [--config <path>] [--baseline-dir <dir>]
+snapdrift migrate-baselines --to snap   # always fails
 ```
 
-- Reads `results.json`, `manifest.json`, and `screenshots/*.png` from the local baseline directory.
-- Uploads as the initial accepted baseline on Snap via `POST /v1/visual/projects/:id/baselines`.
-- Idempotent: if a baseline already exists for the same commit SHA (derived from `GITHUB_SHA` or `git rev-parse HEAD`), the upload is skipped.
-- Screenshots are base64-encoded in the request body; very large suites may want to migrate per-route.
+- The command exits with an error. Snap cannot accept a pre-built local baseline bundle: the screenshots it carries are never uploaded to Snap storage, and its manifest references local filenames rather than Snap object keys, so the call could only ever create a baseline with no pixels behind it. Snap rejects the request with `400 unsupported_baseline_body` (i2Dev-com/snap#653); the legacy `SnapProvider.migrateBaselineFromLocal()` path was removed in 0.7.0.
+- **Use `snapdrift baseline` instead** — with `provider: "snap"` it captures each route through Snap so the images actually land in storage, then publishes a baseline referencing the stored objects. Canonical hosted publication is CI-only (default-branch job); see [`snapdrift baseline`](local-cli.md#snapdrift-baseline).
 
 **Download Snap baselines to local:**
 

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.10.0
+  uses: ranacseruet/snapdrift@v0.12.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.10.0
+  uses: ranacseruet/snapdrift@v0.12.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.10.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.10.0` |
-| `ranacseruet/snapdrift@v0.10.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.10.0` |
+| `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` |
 
 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.10.0
+        uses: ranacseruet/snapdrift@v0.12.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -170,7 +170,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.10.0
+        uses: ranacseruet/snapdrift@v0.12.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -249,10 +249,11 @@ When `provider: "snap"` and `baseUrl` points to a local address (localhost, `127
 
 With the Snap provider, the PR comment includes a **"View in dashboard →"** link that points to `${apiUrl}/dashboard/visual/${projectId}/runs/${runId}`. The local provider omits the link.
 
-Migrating an existing local repo to the Snap provider is a one-shot CLI command:
+To adopt the hosted provider, seed the project with a hosted baseline. `migrate-baselines --to snap` is **not** the way to do it — Snap cannot accept a pre-built local baseline bundle, because the screenshots it carries are never uploaded to Snap storage and its manifest references local filenames rather than Snap object keys. Use `snapdrift baseline` with `provider: "snap"` instead: it captures each route through Snap so the pixels actually land in storage before the baseline manifest is published. Canonical hosted publication is CI-only — run it from your default-branch job, where GitHub Actions supplies the publication metadata automatically (other CI systems set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`); a plain local checkout fails before creating a hosted run.
 
 ```bash
-snapdrift migrate-baselines --to snap
+# In CI, on the default branch, with provider: "snap"
+snapdrift baseline
 ```
 
 Conversely, downloading a Snap baseline back to a local directory (useful for reproducible local debugging) is:
@@ -297,9 +298,6 @@ snapdrift capture
 # After making changes, compare and open the HTML report
 snapdrift diff --open
 
-# Migrate an established local baseline to the hosted Snap backend
-snapdrift migrate-baselines --to snap
-
 # Translate a snap/github-action workflow into snapdrift.json
 snapdrift init --from-snap-action .github/workflows/snap.yml
 ```
@@ -311,11 +309,10 @@ 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. Legacy local comparisons still require like-for-like dimensions; an
-updated local client may opt into the exact
-`diff.comparisonPolicy: { "version": 1, "threshold": number }` contract to
-compare unequal frames on a union canvas and keep the dimension metadata in the
-report.
+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.
 
 Use the provided workflow template to refresh the baseline automatically on every push to your default branch (i.e. every merge):
 
@@ -343,15 +340,31 @@ 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**  
-Without `diff.comparisonPolicy`, SnapDrift reports this as a legacy dimension
-shift and skips pixel comparison. With the exact v1 policy, it compares the
-top-left-aligned union canvas, records the route in `changed[]`, and writes a
-local diff PNG; refresh the baseline after an intentional change when you want
-future runs to return to equal-size comparisons.
+SnapDrift compares the top-left-aligned union canvas, records the route in
+`changed[]`, and writes a local diff PNG. Refresh the baseline after an
+intentional change when you want future runs to return to equal-size
+comparisons.
 
 **A route appears in `errors[]`**  
 Capture failed before comparison. Confirm the app is fully ready and reachable before SnapDrift runs.
 
+**`comparison_too_large` or `union canvas ... exceeds the maximum`**
+
+The baseline/current screenshot union is larger than the 33,554,432-pixel
+comparison budget. Because captures are full-page, a short configured viewport
+can still produce an oversized image when the document is tall; the named
+`mobile` preset also renders at device scale factor 3. Inspect the actual image
+dimensions in the capture results or manifest and calculate
+`max(baselineWidth, currentWidth) × max(baselineHeight, currentHeight)`.
+
+If the route does not need mobile device emulation, a custom viewport object uses
+scale factor 1 and can avoid unnecessary raster inflation. Otherwise reduce the
+captured content or fixture height, or split the coverage across routes when
+appropriate. Do not resize/crop images or lower `diff.threshold`; neither changes
+the capture budget and either can hide a layout regression. See the [screenshot
+size budget](contracts.md#screenshot-size-budget) for the preset estimates and
+custom-viewport semantics.
+
 **Playwright install runs even though `provider: "snap"`**  
 That's expected for the Snap local-capture hybrid. Playwright runs locally to render the page, then the resulting screenshot is uploaded to Snap. The hybrid kicks in only when `baseUrl` points to a local address; for remote `baseUrl` Snap's render worker captures directly.
 

package/docs/local-cli.md

@@ -225,7 +225,7 @@ After running `capture` and `diff` with default paths:
     summary.json          # structured drift summary
     summary.md            # human-readable markdown report
     report.html           # self-contained HTML report with side-by-side images
-    diffs/                # v1 generated diff PNGs, when comparisonPolicy is enabled
+    diffs/                # generated diff PNGs for changed routes
 ```
 
 Add `.snapdrift/` to your `.gitignore` to keep local run output out of version control.
@@ -272,7 +272,7 @@ Comparing against baseline ...
 Report: .snapdrift/diff/report.html
 ```
 
-**Incomplete run** (errors, missing captures, or legacy dimension shifts):
+**Incomplete run** (errors or missing captures):
 
 ```
 ❌  SnapDrift — incomplete
@@ -281,7 +281,7 @@ Report: .snapdrift/diff/report.html
    Changed:   0
    Missing:   1
    Errors:    1
-   Dim diff:  1
+   Dim diff:  0
 
 Report: .snapdrift/diff/report.html
 ```
@@ -290,14 +290,15 @@ 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.
 
-To compare unequal local screenshot dimensions, add the exact opt-in policy to
-`diff`:
+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:
 
 ```json
 "comparisonPolicy": { "version": 1, "threshold": 0.01 }
 ```
 
-The v1 report includes the baseline, current, and union-canvas dimensions in
+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
 signal, so `fail-on-incomplete` does not fail solely because its dimensions
@@ -309,7 +310,7 @@ differ; `fail-on-changes` and `strict` still enforce it.
 
 | Variable | Applies to | Description |
 |:---------|:-----------|:------------|
-| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture`, `diff` | Max concurrent route captures per viewport context (positive integer, default `5`). 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 context, and per-route resolve/compare during `diff`. Set to `1` to restore serial behavior for apps with shared session or auth state. |
 | `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.10.0
+        uses: ranacseruet/snapdrift@v0.12.0
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json

package/lib/provider.mjs

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { loadSnapdriftConfig, runBaselineCapture, generateDriftReport, stageArtifacts } from '@snapdrift/adapter-fs';
+import { runBaselineCapture, generateDriftReport, stageArtifacts } from '@snapdrift/adapter-fs';
 import { buildReportCommentBody } from '@snapdrift/adapter-report-md';
 import {
   SnapProvider,
@@ -43,12 +43,7 @@ export class LocalProvider {
    * @returns {Promise<DiffResult>}
    */
   async diff(options) {
-    const { config } = await loadSnapdriftConfig(options.configPath);
-    const comparisonPolicy = config.diff.comparisonPolicy ?? {
-      version: 1,
-      threshold: config.diff.threshold
-    };
-    return generateDriftReport({ ...options, comparisonPolicy });
+    return generateDriftReport(options);
   }
 
   /**

package/lib/snap-provider.mjs

@@ -46,7 +46,6 @@ const BINARY_REQUEST_TIMEOUT_MS = 120 * 1000;
 const POLL_INTERVAL_MS = 2000;
 const MAX_OPERATION_DURATION_MS = 10 * 60 * 1000;
 const MAX_STABLE_INCOMPLETE_POLLS = 30;
-const MAX_COMPARISON_PIXELS = 32 * 1024 * 1024;
 const BASELINE_RUN_SUCCESS_STATUS = 'new';
 const BASELINE_CAPTURE_SUCCESS_STATUS = 'new';
 const TERMINAL_CAPTURE_STATUSES = new Set(['new', 'diffed', 'error']);
@@ -178,8 +177,7 @@ function isComparisonMetadata(value) {
     canvas.height === Math.max(baseline.height, current.height) &&
     Number.isInteger(comparison.totalPixels) &&
     comparison.totalPixels >= 0 &&
-    comparison.totalPixels <= canvas.width * canvas.height &&
-    canvas.width * canvas.height <= MAX_COMPARISON_PIXELS
+    comparison.totalPixels <= canvas.width * canvas.height
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",
@@ -102,9 +102,9 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@snapdrift/adapter-fs": "^1.2.0",
-    "@snapdrift/adapter-report-md": "^1.2.0",
-    "@snapdrift/compare-core": "^1.1.0",
+    "@snapdrift/adapter-fs": "^1.3.0",
+    "@snapdrift/adapter-report-md": "^1.2.1",
+    "@snapdrift/compare-core": "^1.3.0",
     "@snapdrift/manifest": "^1.4.0",
     "js-yaml": "^5.4.0",
     "playwright": "^1.59.1",