snapdrift 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # 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
+
+- **PR diff artifacts remain reviewable from GitHub comments** — generated local
+  diff paths are now linked to the authenticated Actions artifact (or workflow
+  run fallback) instead of being emitted as broken relative image URLs. Hosted
+  legacy captures also retain their reported dimensions and pixel denominator
+  when v1 comparison metadata is absent.
+
+### Features
+
+- **Unequal-dimension comparisons** — `@snapdrift/compare-core` now exposes
+  `compareImages()` for top-left-aligned union-canvas comparisons while the
+  existing strict APIs remain unchanged. Updated local and hosted providers
+  explicitly request comparison policy v1, record comparison dimensions and the
+  geometric union denominator, stage a generated diff PNG, and render it in
+  Markdown, HTML, and PR reports. Low-level public adapter calls remain strict
+  unless they opt in with `diff.comparisonPolicy`. Legacy dimension shifts remain
+  in `dimensionChanges[]`; completed v1 dimension changes are `changed[]` signals
+  and do not fail `fail-on-incomplete` alone.
+
+- **Workspace packages** — publish `@snapdrift/manifest` 1.4.0,
+  `@snapdrift/compare-core` 1.1.0, `@snapdrift/adapter-report-md` 1.2.0, and
+  `@snapdrift/adapter-fs` 1.2.0 before activating the updated hosted Snap client.
+
 ## 0.9.0 - 2026-09-09
 
 ### 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.9.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.9.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`
-- Dimension shifts are reported separately from pixel drift
+- 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@331e62a7db4b9e743922667adacfe8fd93e51bb2 # v0.9.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@331e62a7db4b9e743922667adacfe8fd93e51bb2 # v0.9.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/actions/comment/action.yml

@@ -24,6 +24,10 @@ inputs:
     description: Artifact label to include in the comment.
     required: false
     default: ''
+  artifact-url:
+    description: Authenticated URL to the uploaded report artifact.
+    required: false
+    default: ''
   repo-config-path:
     description: Path to the SnapDrift config file (needed for provider-aware comment rendering).
     required: false
@@ -58,6 +62,7 @@ runs:
         VISUAL_DIFF_SUMMARY_PATH: ${{ inputs.summary-path }}
         VISUAL_DIFF_RUN_URL: ${{ inputs.run-url }}
         VISUAL_DIFF_ARTIFACT_NAME: ${{ inputs.artifact-name }}
+        VISUAL_DIFF_ARTIFACT_URL: ${{ inputs.artifact-url }}
         INPUT_PR_NUMBER: ${{ inputs.pr-number }}
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
@@ -105,6 +110,7 @@ runs:
           const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
           const body = provider.buildCommentBody(summary, {
             artifactName: process.env.VISUAL_DIFF_ARTIFACT_NAME || '',
+            artifactUrl: process.env.VISUAL_DIFF_ARTIFACT_URL || '',
             runUrl,
             maxChangedRows,
             maxErrorRows

package/actions/compare/action.yml

@@ -67,6 +67,9 @@ outputs:
   markdown-path:
     description: Absolute path to the generated summary markdown file.
     value: ${{ steps.compare.outputs.markdown_path }}
+  diff-images-dir:
+    description: Absolute path to generated local diff PNGs.
+    value: ${{ steps.compare.outputs.diff_images_dir }}
   status:
     description: Computed SnapDrift status.
     value: ${{ steps.compare.outputs.status }}
@@ -133,6 +136,7 @@ runs:
         const resolvedOutDir = path.resolve(process.env.OUT_DIR || 'qa-artifacts/snapdrift/drift/current');
         const resolvedSummaryPath = path.resolve(process.env.SUMMARY_PATH || path.join(resolvedOutDir, 'summary.json'));
         const resolvedMarkdownPath = path.resolve(process.env.MARKDOWN_PATH || path.join(resolvedOutDir, 'summary.md'));
+        const resolvedDiffImagesDir = path.join(resolvedOutDir, 'diffs');
 
         await runDriftCheckCli({
           configPath: process.env.REPO_CONFIG_PATH || undefined,
@@ -143,6 +147,7 @@ runs:
           baselineRunDir: process.env.BASELINE_RUN_DIR || undefined,
           currentRunDir: process.env.CURRENT_RUN_DIR || undefined,
           outDir: resolvedOutDir,
+          diffImagesDir: resolvedDiffImagesDir,
           summaryPath: resolvedSummaryPath,
           markdownPath: resolvedMarkdownPath,
           routeIds: splitCommaList(process.env.ROUTE_IDS),
@@ -155,6 +160,7 @@ runs:
         const outputs = [
           `summary_path=${resolvedSummaryPath}`,
           `markdown_path=${resolvedMarkdownPath}`,
+          `diff_images_dir=${resolvedDiffImagesDir}`,
           `status=${summary.status || ''}`,
           `changed_screenshots=${summary.changedScreenshots || 0}`,
           `matched_screenshots=${summary.matchedScreenshots || 0}`,

package/actions/pr-diff/action.yml

@@ -459,6 +459,7 @@ runs:
         const resolvedOutDir = path.resolve('qa-artifacts/snapdrift/drift/current');
         const resolvedSummaryPath = path.join(resolvedOutDir, 'summary.json');
         const resolvedMarkdownPath = path.join(resolvedOutDir, 'summary.md');
+        const resolvedDiffImagesDir = path.join(resolvedOutDir, 'diffs');
 
         const captureOptions = {
           configPath: process.env.REPO_CONFIG_PATH || undefined,
@@ -475,7 +476,8 @@ runs:
           baselineSourceSha: process.env.BASELINE_SOURCE_SHA || undefined,
           currentResultsPath: process.env.CURRENT_RESULTS_PATH || undefined,
           currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined,
-          currentRunDir: process.env.CURRENT_SCREENSHOTS_ROOT || undefined
+          currentRunDir: process.env.CURRENT_SCREENSHOTS_ROOT || undefined,
+          diffImagesDir: resolvedDiffImagesDir
         };
 
         const diffed = await diffWithPolicy({
@@ -615,6 +617,7 @@ runs:
         CURRENT_MANIFEST_PATH: ${{ steps.compare.outputs.current_manifest_file || steps.capture.outputs.manifest_file }}
         BASELINE_SCREENSHOTS_DIR: ${{ steps.baseline_paths.outputs.screenshots_dir }}
         CURRENT_SCREENSHOTS_ROOT: ${{ steps.compare.outputs.current_screenshots_root || steps.capture.outputs.screenshots_root }}
+        DIFF_IMAGES_DIR: ${{ steps.compare.outputs.diff_images_dir }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -635,13 +638,15 @@ runs:
           baselineManifestPath: process.env.BASELINE_MANIFEST_PATH || undefined,
           currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined,
           baselineScreenshotsDir: process.env.BASELINE_SCREENSHOTS_DIR || undefined,
-          currentScreenshotsDir: currentScreenshotsRoot ? path.join(currentScreenshotsRoot, 'screenshots') : undefined
+          currentScreenshotsDir: currentScreenshotsRoot ? path.join(currentScreenshotsRoot, 'screenshots') : undefined,
+          diffImagesDir: process.env.DIFF_IMAGES_DIR || undefined
         });
 
         await fs.appendFile(process.env.GITHUB_OUTPUT, `bundle_dir=${result.bundleDir}\n`);
         EOF
 
-    - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+    - id: upload
+      uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
       with:
         name: ${{ steps.context.outputs.artifact_name }}
         retention-days: ${{ inputs.artifact-retention-days }}
@@ -663,6 +668,7 @@ runs:
         PR_NUMBER: ${{ steps.context.outputs.pr_number }}
         SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.capture.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
         ARTIFACT_NAME: ${{ steps.context.outputs.artifact_name }}
+        ARTIFACT_URL: ${{ steps.upload.outputs.artifact-url }}
         RUN_URL: ${{ steps.context.outputs.run_url }}
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
@@ -727,6 +733,7 @@ runs:
           const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
           const body = provider.buildCommentBody(summary, {
             artifactName: process.env.ARTIFACT_NAME || '',
+            artifactUrl: process.env.ARTIFACT_URL || '',
             runUrl: process.env.RUN_URL || '',
             maxChangedRows,
             maxErrorRows

package/actions/stage/action.yml

@@ -57,6 +57,10 @@ inputs:
     description: Current screenshots dir for diff artifact staging.
     required: false
     default: ''
+  diff-images-dir:
+    description: Local diff PNG directory for diff artifact staging.
+    required: false
+    default: ''
 
 outputs:
   bundle-dir:
@@ -91,6 +95,7 @@ runs:
         CURRENT_MANIFEST_PATH: ${{ inputs.current-manifest-path }}
         BASELINE_SCREENSHOTS_DIR: ${{ inputs.baseline-screenshots-dir }}
         CURRENT_SCREENSHOTS_DIR: ${{ inputs.current-screenshots-dir }}
+        DIFF_IMAGES_DIR: ${{ inputs.diff-images-dir }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -113,7 +118,8 @@ runs:
           baselineManifestPath: process.env.BASELINE_MANIFEST_PATH || undefined,
           currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined,
           baselineScreenshotsDir: process.env.BASELINE_SCREENSHOTS_DIR || undefined,
-          currentScreenshotsDir: process.env.CURRENT_SCREENSHOTS_DIR || undefined
+          currentScreenshotsDir: process.env.CURRENT_SCREENSHOTS_DIR || undefined,
+          diffImagesDir: process.env.DIFF_IMAGES_DIR || undefined
         });
 
         await fs.appendFile(process.env.GITHUB_OUTPUT, `bundle_dir=${result.bundleDir}\n`);

package/docs/contracts.md

@@ -40,6 +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` |
 
 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.
 
@@ -154,6 +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 |
 
 ## Screenshot manifest shape
 
@@ -208,6 +210,18 @@ 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 }?` | Effective v1 comparison policy used by the local adapter (synthesized from `diff.threshold` when not configured) |
+
+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
+the diff output bundle (for example `diffs/home.png`).
+
+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
+path as a GitHub-hosted image URL.
 
 ### Status values
 
@@ -215,7 +229,7 @@ The pull request drift bundle contains:
 |:-------|:--------|
 | `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
@@ -237,7 +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
-- Dimension mismatches skip pixel comparison and land in `dimensionChanges[]`
+- 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
@@ -246,7 +262,7 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 |:-----|:-------------------|
 | `report-only` | Never |
 | `fail-on-changes` | `changedScreenshots > 0` |
-| `fail-on-incomplete` | Errors, dimension shifts, or missing captures occur |
+| `fail-on-incomplete` | Errors or missing captures occur; a completed v1 dimension comparison alone does not fail |
 | `strict` | Any drift or incomplete comparison appears |
 
 A summary with `status: "skipped"` — or any summary carrying no `diff.mode` —
@@ -262,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 |
@@ -547,6 +602,7 @@ Snap's server-side notification posting should render the same template from the
 | Field | Type | Description |
 |:------|:-----|:------------|
 | `artifactName` | `string?` | PR diff artifact label |
+| `artifactUrl` | `string?` | Authenticated GitHub Actions artifact URL for diff links |
 | `runUrl` | `string?` | GitHub Actions run URL (adds `[View run]` link) |
 | `dashboardUrl` | `string?` | Snap dashboard URL (adds `[View in dashboard →]` link; SnapProvider only) |
 | `maxChangedRows` | `number` | Max drift-signal rows before truncation (default 20) |

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.9.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.9.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.9.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.9.0` |
-| `ranacseruet/snapdrift@v0.9.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.9.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.9.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.9.0
+        uses: ranacseruet/snapdrift@v0.11.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -281,7 +281,8 @@ The `pr-diff` wrapper composes the following low-level steps. They're still avai
   `error`, while `missing` remains the intentional first-baseline result
 - `actions/stage` — assemble the baseline or diff bundle for upload
 - `actions/enforce` — evaluate the summary against `diff.mode` and fail when required
-- `actions/comment` — upsert a PR comment from a summary (provider-aware)
+- `actions/comment` — upsert a PR comment from a summary (provider-aware); pass
+  `artifact-url` from `upload-artifact` when local diff PNGs are present
 
 The two wrapper actions that orchestrate the full pipeline are `actions/baseline` (publish) and `actions/pr-diff` (drift detection). They are the primary integration points.
 
@@ -309,7 +310,11 @@ See the [Local CLI guide](local-cli.md) for full command reference, flags, direc
 
 ## Refresh the baseline automatically
 
-After an intentional layout change or dimension shift merges, the baseline must be republished before SnapDrift can compare like-for-like frames again. Without automation, this is a manual step.
+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.
 
 Use the provided workflow template to refresh the baseline automatically on every push to your default branch (i.e. every merge):
 
@@ -337,11 +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**  
-SnapDrift reports this as a dimension shift and skips pixel comparison for that route. Refresh the baseline after the change lands.
+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,6 +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/                # generated diff PNGs for changed routes
 ```
 
 Add `.snapdrift/` to your `.gitignore` to keep local run output out of version control.
@@ -271,7 +272,7 @@ Comparing against baseline ...
 Report: .snapdrift/diff/report.html
 ```
 
-**Incomplete run** (errors, missing captures, or dimension shifts):
+**Incomplete run** (errors or missing captures):
 
 ```
 ❌  SnapDrift — incomplete
@@ -280,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
 ```
@@ -289,13 +290,27 @@ 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:
+
+```json
+"comparisonPolicy": { "version": 1, "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
+signal, so `fail-on-incomplete` does not fail solely because its dimensions
+differ; `fail-on-changes` and `strict` still enforce it.
+
 ---
 
 ## Environment variables
 
 | 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.9.0
+        uses: ranacseruet/snapdrift@v0.11.0
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json

package/lib/cli.mjs

@@ -430,21 +430,24 @@ export async function runDiffCommand(opts) {
   const markdownPath = path.join(opts.diffDir, 'summary.md');
   const htmlPath = path.join(opts.diffDir, 'report.html');
 
+  const diffOptions = /** @type {import('../types/visual-diff-types').ProviderDiffOptions & { diffImagesDir: string }} */ ({
+    configPath: opts.configPath,
+    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+    baselineResultsPath,
+    baselineManifestPath,
+    currentResultsPath: currentCapture.resultsPath,
+    currentManifestPath: currentCapture.manifestPath,
+    baselineRunDir: opts.baselineDir,
+    currentRunDir: currentCapture.screenshotsRoot,
+    diffImagesDir: path.join(opts.diffDir, 'diffs')
+  });
+
   const diffed = await diffWithPolicy({
     provider: captured.providerName === 'local' ? createProvider('local') : provider,
     providerName: captured.providerName,
     localScreenshots: captured.localScreenshots,
     captureOptions,
-    diffOptions: {
-      configPath: opts.configPath,
-      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-      baselineResultsPath,
-      baselineManifestPath,
-      currentResultsPath: currentCapture.resultsPath,
-      currentManifestPath: currentCapture.manifestPath,
-      baselineRunDir: opts.baselineDir,
-      currentRunDir: currentCapture.screenshotsRoot
-    },
+    diffOptions,
     onSkip: () =>
       process.stdout.write('Visual regression skipped (Snap unavailable, warn-and-skip mode).\n'),
     onFallback: () => process.stdout.write('Falling back to local provider for the diff...\n'),
@@ -461,7 +464,8 @@ export async function runDiffCommand(opts) {
 
   const html = await generateHtmlReport(summary, {
     baselineRunDir: opts.baselineDir,
-    currentRunDir
+    currentRunDir,
+    diffRunDir: opts.diffDir
   });
 
   await Promise.all([

package/lib/provider.mjs

@@ -2,7 +2,15 @@
 
 import { runBaselineCapture, generateDriftReport, stageArtifacts } from '@snapdrift/adapter-fs';
 import { buildReportCommentBody } from '@snapdrift/adapter-report-md';
-import { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError, isLocalBaseUrl } from './snap-provider.mjs';
+import {
+  SnapProvider,
+  SnapApiError,
+  SnapUpgradeRequiredError,
+  SnapUnavailableError,
+  SnapFallbackError,
+  SnapSkipError,
+  isLocalBaseUrl
+} from './snap-provider.mjs';
 
 /** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
 /** @typedef {import('../types/visual-diff-types').ProviderCaptureOptions} CaptureOptions */
@@ -55,8 +63,7 @@ export class LocalProvider {
    */
   async fetchLatestBaseline(_options) {
     throw new Error(
-      'LocalProvider.fetchLatestBaseline is not yet implemented. ' +
-      'Use the pr-diff action for baseline resolution, or wait for a future release.'
+      'LocalProvider.fetchLatestBaseline is not yet implemented. ' + 'Use the pr-diff action for baseline resolution, or wait for a future release.'
     );
   }
 
@@ -113,12 +120,9 @@ const PROVIDER_FACTORIES = {
 export function createProvider(providerName, config) {
   const factory = PROVIDER_FACTORIES[providerName];
   if (!factory) {
-    throw new Error(
-      `Unknown SnapDrift provider: "${providerName}". ` +
-      `Available providers: ${Object.keys(PROVIDER_FACTORIES).join(', ')}.`
-    );
+    throw new Error(`Unknown SnapDrift provider: "${providerName}". ` + `Available providers: ${Object.keys(PROVIDER_FACTORIES).join(', ')}.`);
   }
   return factory(config);
 }
 
-export { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError, isLocalBaseUrl };
+export { SnapProvider, SnapApiError, SnapUpgradeRequiredError, SnapUnavailableError, SnapFallbackError, SnapSkipError, isLocalBaseUrl };