snapdrift 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 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.10.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.10.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -116,7 +116,7 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 - Full-page capture only
 - Viewport presets: `desktop` (1440×900) and `mobile` (390×844), or custom `{ "width": number, "height": number }`
 - One global `diff.threshold`
-- Dimension shifts are reported separately from pixel drift
+- Unequal dimensions remain strict by default; local updated clients may opt in with `diff.comparisonPolicy: { "version": 1, "threshold": number }`
 - 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@80d61b668942dd87c33cf51598623a904becf82f # v0.10.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@80d61b668942dd87c33cf51598623a904becf82f # v0.10.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 }` | Optional local opt-in to top-left-aligned unequal-dimension comparison; absent preserves strict legacy dimension handling |
 
 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 }?` | Exact v1 comparison policy used by the local adapter when opted in |
+
+When v1 comparison is enabled, 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
 
@@ -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[]`
+- 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.
 - `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` —
@@ -547,6 +563,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.10.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.10.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.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` |
 
 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.10.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.10.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,12 @@ 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. 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.
 
 Use the provided workflow template to refresh the baseline automatically on every push to your default branch (i.e. every merge):
 
@@ -337,7 +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 reports this as a dimension shift and skips pixel comparison for that route. Refresh the baseline after the change lands.
+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.
 
 **A route appears in `errors[]`**  
 Capture failed before comparison. Confirm the app is fully ready and reachable before SnapDrift runs.

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/                # v1 generated diff PNGs, when comparisonPolicy is enabled
 ```
 
 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, missing captures, or legacy dimension shifts):
 
 ```
 ❌  SnapDrift — incomplete
@@ -289,6 +290,19 @@ 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`:
+
+```json
+"comparisonPolicy": { "version": 1, "threshold": 0.01 }
+```
+
+The v1 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

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.10.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

@@ -1,8 +1,16 @@
 // @ts-check
 
-import { runBaselineCapture, generateDriftReport, stageArtifacts } from '@snapdrift/adapter-fs';
+import { loadSnapdriftConfig, 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 */
@@ -35,7 +43,12 @@ export class LocalProvider {
    * @returns {Promise<DiffResult>}
    */
   async diff(options) {
-    return generateDriftReport(options);
+    const { config } = await loadSnapdriftConfig(options.configPath);
+    const comparisonPolicy = config.diff.comparisonPolicy ?? {
+      version: 1,
+      threshold: config.diff.threshold
+    };
+    return generateDriftReport({ ...options, comparisonPolicy });
   }
 
   /**
@@ -55,8 +68,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 +125,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 };

package/lib/report.mjs

@@ -26,14 +26,15 @@ async function defaultImageReader(runDir, imagePath) {
  * @param {{
  *   baselineRunDir?: string,
  *   currentRunDir?: string,
+ *   diffRunDir?: string,
  *   imageReader?: (runDir: string, imagePath: string) => Promise<string | null>
  * }} [options]
  * @returns {Promise<string>}
  */
 export async function generateHtmlReport(summary, options = {}) {
   const enrichedOptions = { ...options };
-  if (!enrichedOptions.imageReader && (options.baselineRunDir || options.currentRunDir)) {
+  if (!enrichedOptions.imageReader && (options.baselineRunDir || options.currentRunDir || options.diffRunDir)) {
     enrichedOptions.imageReader = defaultImageReader;
   }
   return _generateHtmlReport(summary, enrichedOptions);
-}
+}