snapdrift 0.8.2 → 0.10.0

package/actions/scope/action.yml

@@ -105,9 +105,32 @@ runs:
               per_page: 100
             });
 
+            if (!Array.isArray(files)) {
+              throw new Error('Malformed GitHub changed-file response: expected an array of file records.');
+            }
+            for (const [index, file] of files.entries()) {
+              if (!file || typeof file !== 'object' || typeof file.filename !== 'string' || file.filename.length === 0) {
+                throw new Error(`Malformed GitHub changed-file response: file record ${index} must include a non-empty string filename.`);
+              }
+            }
+            if (files.length >= 3000) {
+              core.warning('GitHub returned the maximum 3000 changed-file records; the list may be truncated, so running all configured captures.');
+              setOutputs({
+                shouldRun: true,
+                reason: 'changed_files_truncated',
+                selectedRouteIds: allRouteIds
+              });
+              return;
+            }
+            const changedFiles = [...new Set(files.flatMap((file) => [
+              file.filename,
+              ...(file.status === 'renamed' && typeof file.previous_filename === 'string' && file.previous_filename
+                ? [file.previous_filename]
+                : [])
+            ]))];
             const scope = selectRoutesForChangedFiles(
               config,
-              files.map((file) => file.filename)
+              changedFiles
             );
             setOutputs(scope);
           } catch (error) {

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/bin/snapdrift.mjs

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 // @ts-check
 
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 // Resolve cli.mjs relative to this file so the bin entry works regardless of
-// where the consumer installs the package.
-const cliPath = new URL('../lib/cli.mjs', import.meta.url).pathname;
+// where the consumer installs the package. Use fileURLToPath(new URL(...)) rather
+// than URL.pathname so paths containing spaces or Windows drive letters survive
+// the conversion (URL.pathname percent-encodes them, then pathToFileURL re-encodes
+// the result, producing a path that does not exist).
+const cliPath = fileURLToPath(new URL('../lib/cli.mjs', import.meta.url));
 const { main } = await import(pathToFileURL(cliPath).href);
 
 main(process.argv).catch((error) => {

package/docs/contracts.md

@@ -22,7 +22,7 @@ SnapDrift reads runtime behavior from `.github/snapdrift.json` by default.
 
 | Field | Type | Description |
 |:------|:-----|:------------|
-| `id` | `string` | Unique route identifier across runs |
+| `id` | `string` | Unique route identifier across runs. Its sanitized screenshot filename must also be unique across the full configured route set. |
 | `path` | `string` | URL path appended to `baseUrl` |
 | `viewport` | `string` or `object` | Preset name (`"desktop"`, `"mobile"`) or a custom object `{ "width": number, "height": number }` |
 | `changePaths` | `string[]` | Optional prefixes used for changed-file scoping |
@@ -40,9 +40,28 @@ 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.
 
+Changed-file scoping treats a GitHub `renamed` record as both the current
+`filename` and its nonempty `previous_filename`. This keeps a route selected
+when a watched file moves out of its configured `changePaths`, and also detects
+renames into watched or shared paths. Duplicate paths are ignored; other change
+statuses use only their current filename. The `pr-diff` wrapper's explicit
+`route-ids` and `force-run` inputs take precedence over this lookup; the
+standalone `scope` action supports `force-run` and otherwise derives its
+selection from the changed files. If GitHub returns the maximum 3,000 file
+records, both actions run all configured routes with reason
+`changed_files_truncated` because the list may be incomplete.
+
+Route ids are sanitized before local captures and Snap baseline exports write
+`screenshots/<route-id>.png`: `..` becomes `_`, path separators become `_`, and
+control characters are removed. Distinct route ids that produce the same
+sanitized filename are rejected before capture starts. Rename one of the route
+ids and recapture the affected baseline; existing screenshot filenames remain
+unchanged for noncolliding ids.
+
 ### Example (local provider)
 
 ```json
@@ -101,6 +120,27 @@ The published baseline bundle contains:
 | `manifest.json` | Screenshot manifest with ids, paths, and dimensions |
 | `screenshots/*.png` | Captured screenshot images |
 
+Every manifest entry must use a unique staged screenshot filename (the basename
+of `imagePath`). Duplicate paths or paths that flatten to the same filename are
+rejected before comparison, even when the run selects only one of the affected
+route ids, because they can point two logical screenshots at the same pixels.
+Rename the conflicting route ids and recapture the baseline and current bundle.
+
+### Baseline resolution
+
+The `actions/resolve-baseline` action and the `actions/pr-diff` wrapper distinguish three lookup
+outcomes: `found` means a successful search selected a non-expired artifact, `missing` means a
+successful search found no usable artifact, and `error` means GitHub returned an API, network, or
+malformed-response failure. The boolean `found` output remains available for compatibility; use
+`resolution-status` on `resolve-baseline` or `baseline-resolution-status` on `pr-diff` when the
+reason matters. A missing baseline may produce the intentional first-run skipped summary. A lookup
+error fails local comparisons and local Snap fallbacks, so infrastructure failures cannot be
+reported as a clean or intentional missing-baseline result. Healthy hosted Snap diffs may continue
+using their hosted baseline path after a GitHub artifact lookup error.
+The standalone `actions/resolve-baseline` action fails its step for `error`; custom workflows
+should branch on `resolution-status` rather than treating `found: false` as proof that no baseline
+exists.
+
 ## Drift artifact
 
 The pull request drift bundle contains:
@@ -115,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
 
@@ -169,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
 
@@ -198,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
@@ -207,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` —
@@ -328,6 +383,8 @@ A hosted baseline is an authoritative complete snapshot. For `purpose: "baseline
 
 The capture `results.json` records `configuredRouteIds`, `selectedRouteIds`, and `expectedCaptures` (route id, path, and viewport descriptor), plus one resolved `refBranch` / `refSha`, publication workflow ref, and publication sequence. The run-creation request sends the same immutable set and sequence as `capturePlan` and sends the ref as `branch` / `prHeadSha`. Before publication, SnapDrift requires the source run to belong to the configured project, settle to terminal `new`, and contain exactly one successful `new` capture with a non-empty `currentObjectKey` for every expected route/viewport identity. It keeps polling while any expected capture remains non-terminal, even when an older server reports the run itself as terminal, but fails fast after a stable incomplete capture set. Failed, missing, duplicate, extra, path-mismatched, or malformed captures abort before the baseline request. If another default-branch baseline wins first, Snap returns `409 baseline_stale_source`; rerun the current baseline job.
 
+Hosted PR diffs use the same persisted `expectedCaptures` identities. `SnapProvider.diff()` requires `purpose: "diff"` plus a nonempty, unique expected set consistent with `selectedRouteIds`; results written by older SnapDrift versions without that set must be recaptured. It polls until the expected capture count is available, verifies the returned run id, and reconciles every returned capture by route id, path, and normalized viewport descriptor. Missing expected captures, duplicate or unexpected identities, pending or unknown statuses, run or capture errors, missing current objects, and invalid `diffPct` values produce an `incomplete` summary and are never counted as clean matches. A valid comparison requires a current object, a baseline object, and a finite numeric mismatch ratio from 0 through 1. The `diff.mode` setting then controls whether that incomplete summary fails the check.
+
 Publication sends `publicationMode: "complete"` and the source run id both as top-level `sourceRunId` and as `manifest.sourceRunId`. The baseline id is deterministically derived from the run id, and manifest routes are sorted, so a retry sends the same identity and payload. Reusing that id with different persisted fields is rejected; rerun the baseline job to obtain a new source run. `refBranch` / `refSha` come from the persisted capture metadata rather than resolving git a second time. Snap accepts complete publication only from the project's default branch (effective default `main`).
 
 ### Local-capture hybrid
@@ -356,9 +413,21 @@ SnapDrift uses a small, stable subset of the Snap API:
 The Snap HTTP client classifies responses and applies the following rules:
 
 - **2xx** — success, return the parsed body.
-- **4xx** — non-retryable. The client throws `SnapApiError(status, message, path)` immediately. `onUnavailable` is **not** consulted for 4xx — a 404 from `/baselines/latest` is a "no baseline yet" signal, but a 4xx from `/runs` is a configuration error that retrying won't fix.
-- **5xx** — retryable up to 3 attempts with exponential backoff (`1 s` → `2 s` → `4 s`, capped at `30 s` total). If the final attempt still returns 5xx, the client falls through to the `onUnavailable` handler.
-- **Network errors** — same retry/backoff behavior as 5xx. After exhaustion, falls through to the `onUnavailable` handler.
+- **4xx** — non-retryable. The client throws `SnapApiError(status, message, path)` immediately. `onUnavailable` is **not** consulted for 4xx — a 404 from `/baselines/latest` is a "no baseline yet" signal, but a 4xx from `/runs` is a configuration error that retrying won't fix. If the diagnostic body itself stalls or is unavailable, the same `SnapApiError` retains the HTTP status and includes that diagnostic failure.
+- **5xx** — retryable up to 3 attempts with exponential backoff (`1 s` → `2 s` → `4 s`, with each delay capped at `30 s`). If the final attempt still returns 5xx, the client falls through to the `onUnavailable` handler.
+- **Network errors and transport timeouts** — same retry/backoff behavior as 5xx. After exhaustion, falls through to the `onUnavailable` handler.
+
+Every JSON request attempt has a 30-second limit; binary export attempts have a
+120-second limit. Headers and response bodies share the applicable attempt
+limit, and each public Snap operation has one 10-minute deadline covering all
+of its requests, retries, backoff, and polling. The client passes an
+`AbortSignal` to fetch and aborts/cancels stalled bodies; injected transports
+that ignore cancellation are still released by the client-side deadline.
+Retry and poll waits are clipped to the remaining operation time, so no new
+request starts after the operation deadline. Deadline exhaustion is treated as
+Snap unavailability and follows `onUnavailable`; received 4xx responses keep
+their immediate non-retryable behavior, and a stalled 4xx diagnostic body
+retains its HTTP status with a timeout diagnostic.
 
 `onUnavailable` is consulted once retries are exhausted:
 
@@ -376,7 +445,7 @@ alike:
 | Phase | `warn-and-skip` | `fallback-local` |
 |:------|:----------------|:-----------------|
 | Capture | Write a skipped `summary.json`/`summary.md` with reason `snap_unavailable`, expose the summary outputs, stage the report, exit 0. | Capture with `LocalProvider` and report the **effective** provider (`local`) so the rest of the pipeline uses local artifacts and the local pixel engine. |
-| Diff | Same skipped summary, exit 0. | Diff with `LocalProvider`. A capture that Snap rendered server-side has no PNGs on the runner, so the routes are **recaptured locally first**; the recaptured paths replace the Snap ones in the staged bundle. If no baseline artifact was resolved, the run reports `missing_main_baseline_artifact` instead of crashing the local diff. |
+| Diff | Same skipped summary, exit 0. | Diff with `LocalProvider`. A capture that Snap rendered server-side has no PNGs on the runner, so the routes are **recaptured locally first**; the recaptured paths replace the Snap ones in the staged bundle. If baseline resolution succeeded but no artifact was found, the run reports `missing_main_baseline_artifact`; a lookup error fails instead of entering the missing-baseline path. |
 | Baseline publish | Skip the publish and exit 0 without an artifact. | Capture locally and stage/upload that bundle, so the run still leaves a usable baseline. |
 
 Enforcement of `diff.mode` never runs against a skipped summary — a skipped run
@@ -402,13 +471,17 @@ All four error classes are exported from `lib/provider.mjs` and `lib/snap-provid
 
 | Class | Thrown when | Typical handler |
 |:------|:------------|:----------------|
-| `SnapApiError` | A 4xx response was received, or a 5xx/network error was retried to exhaustion. Carries `status` and `path` properties. | Surface the message; do not retry. |
-| `SnapUnavailableError` | A network error or 5xx was retried to exhaustion (used internally; usually re-wrapped as `SnapApiError`). | Treat as a temporary outage. |
+| `SnapApiError` | A 4xx response was received, including a response whose diagnostic body stalled. Carries `status` and `path` properties. A final 5xx response also retains its status when it reaches the outage handler. | Surface the message; do not retry. |
+| `SnapUnavailableError` | A retryable network error, transport timeout, or operation deadline was exhausted. In fail mode this may be surfaced directly; skip and fallback modes wrap it in their policy error. | Treat as a temporary outage. |
 | `SnapFallbackError` | `onUnavailable: "fallback-local"` is set and Snap could not be reached. | Catch and switch to `LocalProvider` for the rest of the pipeline. |
 | `SnapSkipError` | `onUnavailable: "warn-and-skip"` is set and Snap could not be reached. | Catch and exit cleanly with a skipped summary. |
 
 The wrapper actions (`actions/baseline`, `actions/pr-diff`) and the CLI both handle `SnapSkipError` and `SnapFallbackError` through `lib/outage-policy.mjs` (`captureWithPolicy`, `diffWithPolicy`, `publishBaselineWithPolicy`). Custom orchestrations that call `provider.capture()`, `provider.diff()` or `provider.publishBaseline()` directly should use those helpers rather than re-implementing the matrix.
 
+`SnapTransportTimeoutError` is an internal diagnostic name used while a
+request or response body is being bounded. It is not an additional public
+error class; callers should handle the exported error classes above.
+
 ## Primary entrypoints
 
 - `actions/baseline`
@@ -490,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) |
@@ -505,3 +579,45 @@ The `VisualProvider` interface requires `buildCommentBody(summary, meta?)`:
 
 - **`LocalProvider`** — delegates to `buildReportCommentBody` without a `dashboardUrl`.
 - **`SnapProvider`** — constructs `dashboardUrl` from `{apiUrl}/projects/{projectId}/runs/{lastRunId}` and passes it through.
+
+
+## Workspace TypeScript contracts
+
+The four `@snapdrift/*` workspace packages expose their declarations through a
+`types` export condition before the existing JavaScript entrypoint. ESM consumers
+can use Bundler, Node16, or NodeNext module resolution with `strict: true` and
+`skipLibCheck: false`; Node16/NodeNext consumers should use an ESM package or an
+`.mts` entrypoint. The top-level `types` field remains for older tooling.
+
+Install `typescript` and `@types/node` in the consuming development environment
+for APIs that use Node buffers. Cross-package declaration dependencies are
+declared by the package that needs them. `npm run check:package-types` packs the
+workspace packages and checks isolated consumers in all three resolution modes,
+including rejected invalid calls. `npm run typecheck` also checks declaration
+bodies without skipping library checks.
+
+These guarantees cover the workspace package entrypoints. They do not add type
+entrypoints for the root `snapdrift` package's JavaScript subpaths. Package release
+publication is required before existing registry consumers receive these fixes.
+
+Comment renderers accept `VisualReportSummary`: a complete comparison summary or
+a `VisualDriftStatusSummary` with a required status and reason. `buildDriftSummary`
+and `writeDriftSummary` return the latter, preserving their supported non-skipped
+statuses as well as intentional skips. Unrelated object literals are rejected.
+Known viewport presets have complete descriptors; arbitrary string lookups may
+return `undefined` and must be checked by consumers.
+
+The packed type gate runs in PR CI and before release publication. It validates
+the candidate workspace tarballs together, not already-published registry
+versions. Release preparation must bump every changed published package and
+raise sibling dependency floors to the versions that contain these type fixes
+before publication; the gate alone does not validate that release-version step.
+
+Each workspace package also declares every runtime package it imports. In
+particular, `@snapdrift/adapter-fs` declares `@snapdrift/adapter-report-md`, so
+it can be installed and imported without the SnapDrift repository or a sibling
+workspace masking a missing dependency. `npm run check:package-runtime` packs
+each workspace package, installs it in an isolated temporary consumer together
+with only its declared local workspace dependency closure, and imports its
+public entrypoint. The gate runs in pull-request and release workflows; publish
+the updated package before registry consumers can receive a dependency fix.

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.8.2
+  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.8.2
+  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.8.2` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.8.2` |
-| `ranacseruet/snapdrift@v0.8.2` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.8.2` |
+| `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.8.2
+        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.8.2
+        uses: ranacseruet/snapdrift@v0.10.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -188,6 +188,15 @@ jobs:
 - Upserts the PR report
 - Enforces `diff.mode` after publication completes
 
+When the wrapper scopes a pull request from GitHub's changed-file list, a
+renamed file contributes both its new and previous paths. A move out of a
+watched directory therefore still selects the route that owned the old path,
+while a move into a watched or shared path selects the new scope as well.
+Repeated paths are deduplicated, and `route-ids` or `force-run` keep their
+existing precedence. GitHub caps this file listing at 3,000 records; if that
+limit is reached, the actions run all configured routes with scope reason
+`changed_files_truncated` instead of trusting a potentially incomplete list.
+
 ## Useful overrides
 
 | Input | Default | Purpose |
@@ -205,7 +214,7 @@ jobs:
 | `max-changed-rows` | `20` | Max changed-route rows shown in the PR comment before truncation |
 | `max-error-rows` | `10` | Max error rows shown in the PR comment before truncation |
 
-The `pr-diff` action also exposes outputs you can use in subsequent steps: `should-run`, `scope-reason`, `selected-route-ids`, `baseline-found`, `status`, `summary-path`, `markdown-path`, `artifact-name`, `bundle-dir`. See the wrapper action's `outputs:` block for the canonical list.
+The `pr-diff` action also exposes outputs you can use in subsequent steps: `should-run`, `scope-reason`, `selected-route-ids`, `baseline-found`, `baseline-resolution-status`, `status`, `summary-path`, `markdown-path`, `artifact-name`, `bundle-dir`. `baseline-resolution-status` is `found`, `missing`, or `error`; `missing` is the intentional first-baseline case, while `error` means the GitHub lookup failed and causes local comparisons or local Snap fallbacks to fail. Healthy hosted Snap diffs can continue without the downloaded GitHub artifact. See the wrapper action's `outputs:` block for the canonical list.
 
 ## Hosted Snap provider
 
@@ -234,7 +243,7 @@ Both behaviors apply at every phase of a run — capture, diff, and baseline pub
 
 Hosted baseline publication is complete and default-branch-only. SnapDrift rejects scoped baseline capture before creating the run, records the configured/selected route ids and exact route/viewport identities, and publishes only when every expected capture finishes successfully with a stored image. The run records one resolved branch and commit (`branch` / `prHeadSha`) plus a publication workflow ref and monotonic sequence. GitHub Actions provides these automatically; other CI systems may set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`. Snap uses the sequence for same-workflow ordering and source-run timestamps for cross-workflow freshness. Missing, failed, duplicate, or unexpected captures abort publication without replacing the accepted baseline. If a source run loses the race to a newer candidate, the API returns `409 baseline_stale_source`; an inconsistent manifest/source workflow identity returns `409 baseline_source_run_mismatch` with `details.reason = "workflow_mismatch"`. Workflow-ref rotation itself is supported. This restriction does not apply to non-publishing hosted captures, hosted PR-diff runs, or local-provider baselines.
 
-The Snap API client retries 5xx and network errors with exponential backoff (3 attempts, 1 s → 2 s → 4 s, capped at 30 s). 4xx errors never retry and never fall back.
+The Snap API client retries 5xx, network errors, and transport timeouts with exponential backoff (3 attempts, 1 s → 2 s → 4 s, with each delay capped at 30 s). JSON request attempts are limited to 30 seconds and binary baseline exports to 120 seconds. Each Snap operation has a 10-minute deadline covering its requests, retries, backoff, and polling; stalled headers and response bodies are aborted and cannot keep the workflow waiting indefinitely. Retry and poll waits are clipped to the remaining operation time. Received 4xx errors never retry or fall back; if a 4xx diagnostic body stalls, the response remains a non-retryable error with its HTTP status and timeout diagnostic. When a deadline or other retryable transport failure is exhausted, `onUnavailable` controls fail, warn-and-skip, or fallback-local behavior.
 
 When `provider: "snap"` and `baseUrl` points to a local address (localhost, `127.0.0.0/8`, `::1`, or `0.0.0.0`), SnapDrift uses a **local-capture hybrid**: Playwright runs on the runner to render the page, then SnapDrift uploads the resulting screenshots to Snap. This makes it possible to point SnapDrift at a server that only the runner can reach (a typical case) without exposing the server to Snap's render worker.
 
@@ -267,10 +276,13 @@ The `pr-diff` wrapper composes the following low-level steps. They're still avai
 - `actions/capture` — capture routes and emit `results.json` + `manifest.json`
 - `actions/compare` — diff current capture against a baseline
 - `actions/scope` — decide whether to run and which routes to select from changed files
-- `actions/resolve-baseline` — find and download the latest successful baseline artifact
+- `actions/resolve-baseline` — find and download the latest successful baseline artifact; its
+  `resolution-status` output distinguishes `found`, `missing`, and `error`; the action fails for
+  `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.
 
@@ -298,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):
 
@@ -313,6 +330,12 @@ Run this job after every successful default-branch build. Hosted publication is
 **"No non-expired SnapDrift baseline artifact was found"**  
 The baseline workflow has not completed successfully on `main`, or the artifact expired. With the Snap provider, the equivalent situation is a 404 from `/v1/visual/projects/:id/baselines/latest`; `SnapProvider` swallows that 404 and proceeds without a baseline — `onUnavailable` is **not** consulted for this case (a 404 is the legitimate "no baseline yet" signal, not a Snap outage). If you want the PR pipeline to tolerate the first-run case, set `diff.mode: "report-only"`; `onUnavailable: "warn-and-skip"` will not help here.
 
+**"Unable to resolve the SnapDrift baseline artifact"**
+GitHub failed while listing workflow runs or artifacts. Check the job's `actions: read` permission,
+repository/workflow/branch inputs, and GitHub API availability. Snap hosted diffs can still use the
+hosted comparison path, but local comparisons and `fallback-local` require a successful GitHub
+artifact lookup.
+
 **403 when posting the PR report**  
 Grant `issues: write` and `pull-requests: write` to the job.
 
@@ -320,10 +343,36 @@ 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.
 
 **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.
+
+
+## TypeScript package consumers
+
+Import APIs and types from the public `@snapdrift/*` package names. Their export
+maps support Bundler, Node16, and NodeNext resolution; enable `strict: true` and
+`skipLibCheck: false` to validate the contracts in your project. For Node16 or
+NodeNext, use `"type": "module"` or an `.mts` entrypoint. Install `typescript` and
+`@types/node` as development dependencies when using the Node buffer APIs.
+
+No TypeScript path aliases or imports into workspace source directories are
+needed. Root `snapdrift/lib/*` subpath typing is separate from these workspace
+contracts. The fixes become available to registry consumers after the packages
+are released and their installed versions are updated.
+
+The workspace packages are independently installable runtime packages. Install
+the package you use from the registry and let npm resolve its declared runtime
+dependencies; do not rely on a repository checkout or workspace links. The
+filesystem adapter includes its reporting dependency, so `@snapdrift/adapter-fs`
+can load config, capture, comparison, and report entrypoints from an isolated
+consumer. Release a new adapter version before expecting an existing registry
+installation to include a dependency correction.

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.8.2
+        uses: ranacseruet/snapdrift@v0.10.0
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json