snapdrift 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 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.11.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.11.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@799cfb16ff9d51e57d515cdddd4b329950574ef2 # v0.11.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@799cfb16ff9d51e57d515cdddd4b329950574ef2 # v0.11.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,45 @@ 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. 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 |

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.11.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.11.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.11.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.11.0` |
+| `ranacseruet/snapdrift@v0.11.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.11.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.11.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.11.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -311,11 +311,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 +342,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.11.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.10.0",
+  "version": "0.11.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-fs": "^1.3.0",
     "@snapdrift/adapter-report-md": "^1.2.0",
-    "@snapdrift/compare-core": "^1.1.0",
+    "@snapdrift/compare-core": "^1.2.0",
     "@snapdrift/manifest": "^1.4.0",
     "js-yaml": "^5.4.0",
     "playwright": "^1.59.1",