snapdrift 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.13.0 - 2026-09-19
+
+Workspace releases this version:
+
+- `@snapdrift/compare-core` 1.4.0 — the semantic diff palette (`addedColor`/`removedColor`
+  options and the orange default for changed pixels).
+- `@snapdrift/adapter-report-md` 1.3.0 — the exported `DIFF_IMAGE_LEGEND` constant rendered
+  alongside diff images.
+- `@snapdrift/adapter-fs` 1.4.0 — cross-route browser storage isolation (#171), capture
+  profile v2 validation and the compatibility-before-pixels gate (#172), and the semantic
+  diff image handoff to the reporting packages.
+- `@snapdrift/manifest` 1.5.0 — capture profile v2 schema, capture-profile helpers, and the
+  `captureCompatibility` summary types (#172).
+
+The root dependency floors move to `@snapdrift/adapter-fs ^1.4.0`,
+`@snapdrift/compare-core ^1.4.0`, and `@snapdrift/manifest ^1.5.0`; `adapter-fs` and
+`adapter-report-md` in turn require `compare-core ^1.4.0`, `adapter-report-md ^1.3.0`, and
+`manifest ^1.5.0`. The dispatcher pins 3967590 — the #174 merge commit on `main`, which
+contains the newest `actions/` implementation (#173) and the `lib/`/`packages/` runtime the
+wrappers load.
+
+### Features
+
+- Local manifests now persist capture profile v2: engine, browser/Playwright, OS,
+  locale/timezone, and rendering settings. Local comparison validates manifests,
+  requires exact v2 profile equality, and checks configured route paths and
+  normalized viewports before reading PNGs. Incompatibilities are
+  `incompatible_capture` errors, not product drift from changed image dimensions;
+  the summary's `captureCompatibility` status describes profiles only.
+- Legacy missing/v1 profiles remain unverified and pixel-comparable after route
+  checks unless shared metadata conflicts or an explicit foreign engine is found.
+  The unverified diagnostic appears in CLI, Markdown, and HTML reports as well as
+  JSON summaries and PR comments. Malformed or unsupported profiles are rejected.
+  Refresh using `snapdrift baseline`
+  (`provider: "local"`) or the existing baseline action; `report-only` acknowledges
+  incompatibility nonblockingly but never bypasses it to compare pixels.
+- Local diff images now use a semantic palette so the rendered PNG reflects the
+  kind of change, not just that pixels differ. `@snapdrift/compare-core` union-canvas
+  comparisons render pixels present only in the current capture in green (`addedColor`,
+  default `[0, 170, 0, 255]`), pixels present only in the baseline in red (`removedColor`,
+  default `[255, 0, 0, 255]`), and overlapping changed pixels in orange (`highlightColor`,
+  default `[255, 140, 0, 255]`). Metrics are unchanged — one-sided pixels still count as
+  changed under comparison policy v1. Strict same-dimension `generateDiffImage` diffs
+  switch their default highlight from red to orange for parity and cannot contain
+  added/removed pixels. Markdown, HTML, and PR-comment reports render a legend
+  ("orange = changed · green = added · red = removed") whenever a local diff image is
+  embedded. Consumers comparing diff-PNG bytes between versions will see different
+  output by design; the new options restore any previous palette.
+
+### Refactoring
+
+- GitHub-script steps in `actions/scope`, `actions/pr-diff` (scope and PR report),
+  and `actions/comment` now delegate to the shared, dependency-injected helpers in
+  `lib/github-requests.mjs` (`fetchPullRequestFiles`, `resolveScopeDecision`,
+  `resolvePullRequestScope`, `upsertPullRequestReportComment`), so the changed-file
+  selection and comment-upsert behavior is defined once and exercised by unit and
+  real-YAML parity tests. Outputs, reasons, warnings, markers, and fallback bodies
+  are byte-for-byte identical.
+- Providers and `captureWithPolicy`/`diffWithPolicy` results now include an explicit
+  `artifacts` descriptor (`describeCaptureArtifacts`: `localScreenshots` plus
+  `artifactsRoot` for local or hosted local-capture hybrid runs). Fallback decisions
+  prefer provider-returned capabilities, with provider-name/URL inference retained
+  for legacy results and explicit caller overrides taking precedence. Diff callers
+  without capability information or config retain the no-recapture legacy default.
+  `localScreenshots` remains, and
+  `hasLocalScreenshots` is kept as a thin wrapper. `lib/provider.mjs` exports
+  `PROVIDER_CAPABILITIES` and `providerSupports(provider, capability)` so the
+  unavailable `LocalProvider.fetchLatestBaseline` baseline-store capability is
+  discoverable without a runtime throw.
+
+### Behavior changes
+
+- Local capture explicitly sets `en-US` / `UTC`; localized text/date changes may
+  require baseline recapture. Fonts are not fingerprinted. See the
+  [capture profile contract](docs/contracts.md#local-capture-profile-v2) and
+  [baseline refresh guide](docs/local-cli.md#refreshing-or-acknowledging-local-baselines).
+
+### Fixes
+
+- Isolate each local route capture and retry in a fresh browser context, preventing
+  cookies and browser storage from leaking between routes sharing a viewport.
+  Per-viewport concurrency and result ordering are preserved. This also fixes
+  Snap local-capture hybrid runs; recapture baselines affected by leaked storage.
+
 ## 0.12.0 - 2026-09-16
 
 ### 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.12.0
+  uses: ranacseruet/snapdrift@v0.13.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.12.0
+  uses: ranacseruet/snapdrift@v0.13.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -110,6 +110,10 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 | `fail-on-incomplete` | Captures are missing or comparison errors occur |
 | `strict` | Any drift signal or incomplete comparison appears |
 
+Local comparisons check capture profiles and configured route/path/viewport identity
+before pixels. Incompatible captures produce incomplete errors, not product drift;
+`report-only` never bypasses these checks. See [compatibility and baseline refresh](docs/local-cli.md#refreshing-or-acknowledging-local-baselines).
+
 ## Current constraints
 
 - Ubuntu runners only (local CLI works on any OS Node 22+ supports)

package/action.yml

@@ -155,7 +155,7 @@ runs:
     - name: SnapDrift baseline
       id: baseline
       if: inputs.mode == 'baseline'
-      uses: ranacseruet/snapdrift/actions/baseline@e4b92c2243c6e69594cab7405f68eb58fe94587e # v0.12.0
+      uses: ranacseruet/snapdrift/actions/baseline@3967590687d420479ba5ec351e1394de174c1838 # v0.13.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@e4b92c2243c6e69594cab7405f68eb58fe94587e # v0.12.0
+      uses: ranacseruet/snapdrift/actions/pr-diff@3967590687d420479ba5ec351e1394de174c1838 # v0.13.0
       with:
         github-token: ${{ inputs.github-token }}
         repo-config-path: ${{ inputs.repo-config-path }}

package/actions/comment/action.yml

@@ -116,41 +116,12 @@ runs:
             maxErrorRows
           });
 
-          const comments = await github.paginate(github.rest.issues.listComments, {
-            owner: context.repo.owner,
-            repo: context.repo.repo,
-            issue_number: issueNumber,
-            per_page: 100
+          const requestsModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/github-requests.mjs');
+          const { upsertPullRequestReportComment } = await import(pathToFileURL(requestsModulePath));
+          await upsertPullRequestReportComment({
+            github,
+            ...context.repo,
+            issueNumber,
+            body,
+            markers: PR_COMMENT_MARKERS
           });
-          const matchingComments = comments
-            .filter((comment) => comment.body && PR_COMMENT_MARKERS.some((marker) => comment.body.includes(marker)))
-            .sort((left, right) => {
-              const leftTime = new Date(left.updated_at || left.created_at).getTime();
-              const rightTime = new Date(right.updated_at || right.created_at).getTime();
-              return rightTime - leftTime;
-            });
-          const existing = matchingComments[0];
-
-          if (existing) {
-            await github.rest.issues.updateComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              comment_id: existing.id,
-              body
-            });
-          } else {
-            await github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: issueNumber,
-              body
-            });
-          }
-
-          for (const duplicate of matchingComments.slice(1)) {
-            await github.rest.issues.deleteComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              comment_id: duplicate.id
-            });
-          }

package/actions/pr-diff/action.yml

@@ -137,91 +137,23 @@ runs:
           const { pathToFileURL } = require('url');
 
           const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
-          const { loadSnapdriftConfig, selectConfiguredRoutes, selectRoutesForChangedFiles, splitCommaList } = await import(pathToFileURL(configModulePath));
+          const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+          const requestsModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/github-requests.mjs');
+          const { resolvePullRequestScope } = await import(pathToFileURL(requestsModulePath));
           const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-          const allRouteIds = (config.routes || []).map((route) => route.id);
-          const explicitRouteIds = splitCommaList(process.env.ROUTE_IDS);
-
-          function setOutputs(scope) {
-            core.setOutput('should_run', scope.shouldRun ? 'true' : 'false');
-            core.setOutput('reason', scope.reason);
-            core.setOutput('selected_route_ids', (scope.selectedRouteIds || []).join(','));
-          }
-
-          if (explicitRouteIds.length > 0) {
-            const selected = selectConfiguredRoutes(config, explicitRouteIds);
-            setOutputs({
-              shouldRun: true,
-              reason: 'explicit_route_ids',
-              selectedRouteIds: selected.selectedRouteIds
-            });
-            return;
-          }
-
-          if (process.env.FORCE_RUN === 'true') {
-            setOutputs({
-              shouldRun: true,
-              reason: process.env.FORCE_RUN_REASON || 'forced',
-              selectedRouteIds: allRouteIds
-            });
-            return;
-          }
-
-          const prNumber = Number(process.env.INPUT_PR_NUMBER || context.payload.pull_request?.number || '');
-          if (!Number.isFinite(prNumber) || prNumber <= 0) {
-            setOutputs({
-              shouldRun: true,
-              reason: 'missing_pr_number',
-              selectedRouteIds: allRouteIds
-            });
-            return;
-          }
-
-          try {
-            const files = await github.paginate(github.rest.pulls.listFiles, {
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: prNumber,
-              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]
-                : [])
-            ]))];
-            setOutputs(
-              selectRoutesForChangedFiles(
-                config,
-                changedFiles
-              )
-            );
-          } catch (error) {
-            core.warning(`Unable to inspect PR files for SnapDrift scope; running all configured captures instead. ${error.message}`);
-            setOutputs({
-              shouldRun: true,
-              reason: 'snapdrift_scope_check_failed',
-              selectedRouteIds: allRouteIds
-            });
-          }
+          const scope = await resolvePullRequestScope({
+            github,
+            ...context.repo,
+            config,
+            pullNumber: Number(process.env.INPUT_PR_NUMBER || context.payload.pull_request?.number || ''),
+            routeIds: process.env.ROUTE_IDS || '',
+            forceRun: process.env.FORCE_RUN === 'true',
+            forceRunReason: process.env.FORCE_RUN_REASON || 'forced',
+            warning: (message) => core.warning(message)
+          });
+          core.setOutput('should_run', scope.shouldRun ? 'true' : 'false');
+          core.setOutput('reason', scope.reason);
+          core.setOutput('selected_route_ids', (scope.selectedRouteIds || []).join(','));
 
     - id: baseline
       if: steps.scope.outputs.should_run == 'true'
@@ -739,44 +671,15 @@ runs:
             maxErrorRows
           });
 
-          const comments = await github.paginate(github.rest.issues.listComments, {
-            owner: context.repo.owner,
-            repo: context.repo.repo,
-            issue_number: issueNumber,
-            per_page: 100
+          const requestsModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/github-requests.mjs');
+          const { upsertPullRequestReportComment } = await import(pathToFileURL(requestsModulePath));
+          await upsertPullRequestReportComment({
+            github,
+            ...context.repo,
+            issueNumber,
+            body,
+            markers: PR_COMMENT_MARKERS
           });
-          const matchingComments = comments
-            .filter((comment) => comment.body && PR_COMMENT_MARKERS.some((marker) => comment.body.includes(marker)))
-            .sort((left, right) => {
-              const leftTime = new Date(left.updated_at || left.created_at).getTime();
-              const rightTime = new Date(right.updated_at || right.created_at).getTime();
-              return rightTime - leftTime;
-            });
-          const existing = matchingComments[0];
-
-          if (existing) {
-            await github.rest.issues.updateComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              comment_id: existing.id,
-              body
-            });
-          } else {
-            await github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: issueNumber,
-              body
-            });
-          }
-
-          for (const duplicate of matchingComments.slice(1)) {
-            await github.rest.issues.deleteComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              comment_id: duplicate.id
-            });
-          }
 
     # A skipped compare writes a summary with no diff counters, so enforcement
     # has nothing to evaluate — `warn-and-skip` means "do not fail my build".

package/actions/scope/action.yml

@@ -67,77 +67,19 @@ runs:
           const { pathToFileURL } = require('url');
 
           const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
-          const { loadSnapdriftConfig, selectRoutesForChangedFiles } = await import(pathToFileURL(configModulePath));
+          const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+          const requestsModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/github-requests.mjs');
+          const { resolvePullRequestScope } = await import(pathToFileURL(requestsModulePath));
           const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-
-          const allRouteIds = (config.routes || []).map((route) => route.id);
-          const resolvedPrNumber = Number(process.env.INPUT_PR_NUMBER || context.payload.pull_request?.number || '');
-
-          function setOutputs(scope) {
-            core.setOutput('should_run', scope.shouldRun ? 'true' : 'false');
-            core.setOutput('reason', scope.reason);
-            core.setOutput('selected_route_ids', (scope.selectedRouteIds || []).join(','));
-          }
-
-          if (process.env.FORCE_RUN === 'true') {
-            setOutputs({
-              shouldRun: true,
-              reason: process.env.FORCE_RUN_REASON || 'forced',
-              selectedRouteIds: allRouteIds
-            });
-            return;
-          }
-
-          if (!Number.isFinite(resolvedPrNumber) || resolvedPrNumber <= 0) {
-            setOutputs({
-              shouldRun: true,
-              reason: 'missing_pr_number',
-              selectedRouteIds: allRouteIds
-            });
-            return;
-          }
-
-          try {
-            const files = await github.paginate(github.rest.pulls.listFiles, {
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: resolvedPrNumber,
-              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,
-              changedFiles
-            );
-            setOutputs(scope);
-          } catch (error) {
-            core.warning(`Unable to inspect PR files for SnapDrift scope; running all configured captures instead. ${error.message}`);
-            setOutputs({
-              shouldRun: true,
-              reason: 'snapdrift_scope_check_failed',
-              selectedRouteIds: allRouteIds
-            });
-          }
+          const scope = await resolvePullRequestScope({
+            github,
+            ...context.repo,
+            config,
+            pullNumber: Number(process.env.INPUT_PR_NUMBER || context.payload.pull_request?.number || ''),
+            forceRun: process.env.FORCE_RUN === 'true',
+            forceRunReason: process.env.FORCE_RUN_REASON || 'forced',
+            warning: (message) => core.warning(message)
+          });
+          core.setOutput('should_run', scope.shouldRun ? 'true' : 'false');
+          core.setOutput('reason', scope.reason);
+          core.setOutput('selected_route_ids', (scope.selectedRouteIds || []).join(','));

package/docs/contracts.md

@@ -159,6 +159,8 @@ The pull request drift bundle contains:
 
 ## Screenshot manifest shape
 
+Minimal legacy example (new local captures also write `captureProfile`):
+
 ```json
 {
   "generatedAt": "2024-01-01T00:00:00.000Z",
@@ -176,6 +178,75 @@ The pull request drift bundle contains:
 }
 ```
 
+### Local capture profile v2
+
+New local captures persist `captureProfile` with `schemaVersion: 2`. This version
+is independent of the outer manifest schema (which defaults to 1 when omitted)
+and comparison policy v1. The profile records:
+
+| Field | Local capture value |
+|:------|:--------------------|
+| `engine`, `engineVersion` | `{ "name": "snapdrift-local", "version": "<adapter-fs version>" }`; `engineVersion` equals `engine.version` |
+| `browser`, `browserRevision`, `playwrightVersion` | `chromium`, the running browser's `browser.version()` string, and the installed Playwright version |
+| `platform` | `name`, `architecture`, `release`, `version` from Node's OS APIs |
+| `locale`, `timezone` | `en-US`, `UTC` |
+| `settings.screenshot` | `fullPage: true`, `animations: "disabled"`, `caret: "hide"`, `scale: "device"`, `omitBackground: false`, `type: "png"` |
+| `settings.readiness` | `waitUntil: "load"`, `settleDelayMs: 300` |
+| `settings.context` | `isolation: "fresh-context-per-attempt"`, `colorScheme: "light"`, `reducedMotion: "no-preference"`, `forcedColors: "none"`, `javaScriptEnabled: true`, `serviceWorkers: "allow"` |
+| `settings.launch` | `headless: true`, `args: ["--disable-gpu"]` |
+
+These are persisted metadata, not new configuration knobs. Local v2 requires
+all listed fields with valid types/settings and matching engine version fields.
+Fonts are **not fingerprinted**: local capture does not populate the optional
+`fontsHash`, so a verified profile is not proof of identical installed fonts.
+Explicit `en-US` / `UTC` replaces environment-dependent defaults and may change
+localized text or dates; recapture affected baselines after upgrading.
+
+### Local compatibility before pixels
+
+Both manifests are validated after loading and before manifest entries are
+indexed and PNGs are resolved.
+Malformed manifests/profiles and unsupported profile schema versions (anything
+other than omitted, 1, or 2) throw before a comparison summary is generated;
+`report-only` does not suppress these input errors.
+
+- Two local v2 profiles must match exactly across the full profile, including
+  extra fields. Object key order is ignored; array order and values matter.
+  There is no version tolerance: adapter, Playwright, browser, or OS updates can
+  require a baseline refresh. The reason identifies the first differing field.
+- For each selected configured route id present in both manifests, both entries
+  must have the exact configured `path` and the same normalized viewport as the
+  config: width, height, device scale factor, mobile, and touch. Paths are not
+  URL-normalized; `baseUrl` and timestamps are not compared. Custom viewports use
+  scale 1, mobile false, touch false: 1440×900 equals `desktop`, but 390×844 does
+  not equal `mobile`. Missing entries retain their missing/error classification.
+- A profile or route-identity mismatch adds an `errors[]` item with
+  `status: "error"` and `code: "incompatible_capture"`. That route's PNGs are
+  not resolved, read, or pixel-compared, even if they would be byte-identical.
+  The summary is `incomplete`, not product drift. With compatible identity,
+  changed full-page raster dimensions remain normal union-canvas `changed[]`
+  signals, independent of threshold.
+- Missing profiles or profiles with omitted/v1 schema remain usable but
+  `unverified`, with a warning in `summary.message`; pixels can still be compared
+  after route checks. If both profiles provide `browser`, `browserRevision`,
+  `fontsHash`, `timezone`, or `locale`, a difference in any shared field is
+  incompatible. An explicit foreign `engine.name` on either side is incompatible
+  even when the other profile is absent. Legacy engine versions alone do not
+  establish verified compatibility.
+
+`summary.captureCompatibility` contains profile-level `status` (`verified`,
+`unverified`, or `incompatible`) and an optional `reason`. It is **not** an
+aggregate route status: profiles can be `verified` while route path/viewport
+checks produce `incompatible_capture` errors. Unverified alone does not make a
+run incomplete or fail enforcement.
+
+Refresh the baseline using the [existing CLI or baseline action](local-cli.md#refreshing-or-acknowledging-local-baselines)
+in the intended capture environment. For intentional nonblocking acknowledgement,
+set `diff.mode` to `report-only`: it preserves incompatibility errors and never
+overrides compatibility to compare pixels. `fail-on-incomplete` and `strict`
+fail on those errors; `fail-on-changes` does not fail on incompatibility alone
+but still fails if other comparable routes changed.
+
 ## Summary shape
 
 ```json
@@ -209,6 +280,7 @@ The pull request drift bundle contains:
 
 | Field | Type | Description |
 |:------|:-----|:------------|
+| `captureCompatibility` | `{ status, reason? }?` | Local profile-level compatibility: `verified`, `unverified`, or `incompatible`; route identity errors are separate |
 | `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) |
 
@@ -247,11 +319,12 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 
 ## Drift semantics
 
-- Screenshots are matched by `id`
+- Screenshots are matched by `id`; local profile and configured path/normalized viewport compatibility are checked before pixels (see [Local compatibility before pixels](#local-compatibility-before-pixels))
 - Mismatch ratio is `different_pixels / total_pixels`
 - `diff.threshold` applies per screenshot
 - Missing captures are counted separately from drift signals
 - 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.
+- Local diff images are rendered with a semantic palette: orange = pixels that differ between baseline and current, green = pixels present only in the current capture (added), red = pixels present only in the baseline (removed). The palette is a rendering detail of `@snapdrift/compare-core` (`addedColor`/`removedColor`/`highlightColor` options); the frozen v1 comparison metrics are unaffected. Equal-dimension strict diffs (`generateDiffImage`) use orange for changed pixels and cannot contain added/removed pixels. Reports render a legend whenever a local diff image is embedded; summaries that carry only comparison metadata (Snap provider runs, which render diffs hosted-side) render no legend.
 - `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
@@ -260,7 +333,7 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 
 | Mode | Stops the run when |
 |:-----|:-------------------|
-| `report-only` | Never |
+| `report-only` | Never from summary enforcement; validation/capture failures still fail |
 | `fail-on-changes` | `changedScreenshots > 0` |
 | `fail-on-incomplete` | Errors or missing captures occur; a completed v1 dimension comparison alone does not fail |
 | `strict` | Any drift or incomplete comparison appears |
@@ -349,6 +422,14 @@ that matches the product behavior. Do not resize or crop screenshots, or lower
 | Screenshot animations | `disabled` (Playwright finishes/cancels CSS animations before capture) |
 | Capture concurrency | 5 routes per viewport (overridable via `SNAPDRIFT_CAPTURE_CONCURRENCY`)|
 
+Local Playwright captures use a fresh browser context for every route attempt,
+including retries. Cookies and browser storage are not shared between routes,
+even when routes share a viewport or run serially. This also applies to Snap's
+local-capture hybrid, not to rendering performed by the hosted service. Viewport
+groups still run concurrently, with the configured limit applied per group.
+Previously leaked storage may have affected existing baselines; recapture them
+after upgrading if storage-dependent UI produces a one-time change.
+
 ## Local CLI directory layout
 
 When using the `snapdrift` CLI, outputs are written to `.snapdrift/` by default:
@@ -541,6 +622,50 @@ The wrapper actions (`actions/baseline`, `actions/pr-diff`) and the CLI both han
 request or response body is being bounded. It is not an additional public
 error class; callers should handle the exported error classes above.
 
+## Shared orchestration
+
+GitHub-facing request handling is shared between the wrapper and standalone
+actions through `lib/github-requests.mjs`. The github-script steps stay as thin
+adapters that load the module, inject `{ github, owner, repo, context }`-style
+inputs, and map the returned decision to step outputs:
+
+- `fetchPullRequestFiles` paginates `pulls.listFiles` (100 per page) and
+  validates each record's `filename` before any scope decision is made.
+- `resolveScopeDecision` is pure: renamed files contribute
+  `previous_filename`, paths are deduplicated, 3000+ records short-circuit to
+  running all routes (`changed_files_truncated`), and an empty list maps to
+  `no_changed_files`. Other reasons come from
+  `selectRoutesForChangedFiles`.
+- `resolvePullRequestScope` composes the above with the
+  explicit-route/force-run/missing-PR shortcuts and the
+  `snapdrift_scope_check_failed` fallback warning.
+- `upsertPullRequestReportComment` performs the marker-filtered, newest-first
+  comment upsert with duplicate deletion used by `actions/comment` and the
+  `actions/pr-diff` report step. The create-only "Capture Failed" /
+  "Baseline Lookup Failed" fallback body remains inline in `actions/pr-diff`.
+
+The baseline resolver keeps its own module (`lib/resolve-baseline-artifact.mjs`)
+because both actions already share it verbatim.
+
+### Capture artifact capabilities
+
+Providers now return `artifacts` on capture results, attached in the provider layer
+rather than adapter-fs:
+
+- `localScreenshots`: whether PNGs are available locally for pixel comparison.
+- `artifactsRoot`: the capture's `screenshotsRoot` for local and Snap hybrid
+  captures (`localScreenshots: true`); `undefined` for hosted remote captures
+  (`localScreenshots: false`), even though their metadata has a local path.
+
+`captureWithPolicy` prefers `result.artifacts` over provider-name/base-URL inference.
+For `diffWithPolicy`, pass the capture as `captureResult` or forward its `artifacts`.
+Precedence is the legacy `options.localScreenshots` boolean (if supplied), then
+`options.artifacts`, then `captureResult.artifacts`, then provider/config inference.
+The boolean overrides only `localScreenshots`; false clears `artifactsRoot`.
+Inference remains for legacy results without a descriptor when config is supplied.
+If no capability arguments, result descriptor, or config are supplied to
+`diffWithPolicy`, it preserves the legacy local-screenshots default without recapture.
+
 ## Primary entrypoints
 
 - `actions/baseline`
@@ -567,7 +692,7 @@ These are for custom orchestration only. Wrapper actions set them automatically.
 | `SNAPDRIFT_BASELINE_ARTIFACT_NAME` | `compare-results.mjs` | Baseline artifact label to embed in the report |
 | `SNAPDRIFT_BASELINE_SOURCE_SHA` | `compare-results.mjs` | Baseline source SHA to embed in the report |
 | `SNAPDRIFT_ENFORCE_OUTCOME` | `compare-results.mjs` | Set to `0` to disable enforcement in direct CLI usage |
-| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture-routes.mjs` | Max concurrent route captures per viewport context (positive integer, default `5`). Set to `1` to restore serial behaviour for apps with shared session/auth state. |
+| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture-routes.mjs` | Max concurrent route captures per viewport group (positive integer, default `5`). Each local attempt uses a fresh browser context. Set to `1` to serialize each group without sharing storage. |
 
 ## PR comment markdown shape
 

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.12.0
+  uses: ranacseruet/snapdrift@v0.13.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.12.0
+  uses: ranacseruet/snapdrift@v0.13.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.12.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.12.0` |
-| `ranacseruet/snapdrift@v0.12.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.12.0` |
+| `ranacseruet/snapdrift@v0.13.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.13.0` |
+| `ranacseruet/snapdrift@v0.13.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.13.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.12.0
+        uses: ranacseruet/snapdrift@v0.13.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -170,7 +170,7 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift@v0.12.0
+        uses: ranacseruet/snapdrift@v0.13.0
         with:
           mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/docs/local-cli.md

@@ -203,6 +203,61 @@ The `--open` flag opens the HTML report in your default browser when the diff is
 
 ---
 
+## Refreshing or acknowledging local baselines
+
+New local manifests record a [v2 capture profile](contracts.md#local-capture-profile-v2)
+with exact engine, Playwright/browser, OS, locale/timezone, and rendering settings.
+Manifests are validated after loading; then, before resolving PNGs, comparison
+checks the profiles and each selected route's id, exact configured path, and
+normalized viewport. A mismatch produces an
+`incompatible_capture` error and an `incomplete` summary, not a pixel drift
+signal. Matching profiles can still have route-identity errors:
+`summary.captureCompatibility.status` describes profiles only.
+
+To refresh, serve the intended accepted application state using the same capture
+environment and route config as future diffs. With `provider: "local"`, run:
+
+```bash
+snapdrift baseline --config .github/snapdrift.json --baseline-dir .snapdrift/baseline
+```
+
+This overwrites baseline metadata and captured screenshots; `snapdrift capture`
+with the same options is equivalent for the local provider. Capture all routes
+for a complete replacement, without `--routes` or `SNAPDRIFT_ROUTE_IDS` scoping.
+Then serve the candidate application state and run:
+
+```bash
+snapdrift diff --config .github/snapdrift.json --baseline-dir .snapdrift/baseline --open
+```
+
+In CI, run the existing default-branch baseline workflow using the root action's
+`mode: baseline` ([Quickstart](../README.md#quickstart)) or `actions/baseline`.
+Use the same upgraded SnapDrift/action revision and runner environment for
+baseline and PR captures, with artifact upload enabled; then rerun the PR diff.
+A baseline captured on a different OS is not interchangeable merely because
+both commands use Playwright.
+
+For intentional nonblocking acknowledgement, set `diff.mode` to `report-only`
+in the config and rerun `snapdrift diff --open`. This keeps the incompatibility
+errors visible and **never overrides compatibility to compare pixels**; there
+is no diff acceptance flag. `fail-on-incomplete` and `strict` fail on these
+errors; `fail-on-changes` fails only if other comparable routes changed. Once
+identity is compatible, a changed full-page PNG size is normal product drift,
+not incompatibility, and fails `fail-on-changes` / `strict` even below threshold.
+
+Legacy manifests with missing profiles or omitted/v1 profile schema remain
+pixel-comparable after route checks, but report `unverified` with a warning.
+Conflicting shared browser/revision, fonts hash, locale, or timezone fields, or
+an explicit foreign engine on either side, are still incompatible. Malformed
+manifests/profiles and unsupported profile schema versions abort comparison,
+even in `report-only`; refresh rather than editing metadata to force a match.
+
+Local capture now explicitly uses `en-US` and `UTC`; localized text/date changes
+may require recapture after upgrading. Fonts are not fingerprinted, so keep
+installed fonts consistent even when profiles are verified.
+
+---
+
 ## Local directory layout
 
 After running `capture` and `diff` with default paths:
@@ -239,7 +294,7 @@ Add `.snapdrift/` to your `.gitignore` to keep local run output out of version c
 | `0` | Clean — no drift above threshold, `diff.mode` is `report-only`, the command was intentionally skipped under `onUnavailable: "warn-and-skip"` (`diff`, `capture` and `baseline` all exit 0 in that case), or the command was a `capture` / `baseline` / `migrate-baselines --to local` / `init` that completed |
 | `1` | Drift enforced — `diff.mode` caused the run to fail, a required command argument was missing, or the `--to local` engine-name check failed (see [Drift modes](../README.md#drift-modes)) |
 
-Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. Set `"mode": "report-only"` during local development to always get a report without a failing exit code.
+Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. Set `"mode": "report-only"` for nonblocking report inspection; capture, input-validation, and other command failures still exit 1 and can prevent report generation.
 
 ---
 
@@ -310,7 +365,7 @@ differ; `fail-on-changes` and `strict` still enforce it.
 
 | Variable | Applies to | Description |
 |:---------|:-----------|:------------|
-| `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_CAPTURE_CONCURRENCY` | `capture`, `diff` | Max concurrent route operations (positive integer, default `5`): route captures per viewport group, and per-route resolve/compare during `diff`. Each local capture attempt uses isolated browser storage. Set to `1` to serialize captures within each viewport group, without sharing storage. |
 | `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.12.0
+        uses: ranacseruet/snapdrift@v0.13.0
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json

package/lib/cli.mjs

@@ -214,6 +214,10 @@ export function printSummary(summary) {
   if (errors > 0) process.stdout.write(`   Errors:   ${errors}\n`);
   if (dimensionChanges > 0) process.stdout.write(`   Dim diff: ${dimensionChanges}\n`);
 
+  if (summary.captureCompatibility?.status === 'unverified' && summary.message) {
+    process.stdout.write(`   Note: ${summary.message}\n`);
+  }
+
   if (summary.changed?.length) {
     process.stdout.write('\n   Changed routes:\n');
     for (const item of summary.changed) {

package/lib/github-requests.mjs

@@ -0,0 +1,134 @@
+// @ts-check
+
+import { selectConfiguredRoutes, selectRoutesForChangedFiles, splitCommaList } from './snapdrift-config.mjs';
+
+/** @typedef {import('../types/visual-diff-types').VisualRegressionConfig} VisualRegressionConfig */
+/** @typedef {{ filename: string, status?: string, previous_filename?: string }} PullRequestFile */
+/** @typedef {ReturnType<typeof selectRoutesForChangedFiles>} ScopeDecision */
+/** @typedef {{ paginate: Function, rest: { pulls: { listFiles: Function } } }} ScopeGitHubClient */
+/**
+ * @typedef {{
+ *   paginate: Function,
+ *   rest: { issues: {
+ *     listComments: Function,
+ *     createComment: Function,
+ *     updateComment: Function,
+ *     deleteComment: Function
+ *   } }
+ * }} CommentGitHubClient
+ */
+
+/**
+ * @param {{ github: ScopeGitHubClient, owner: string, repo: string, pullNumber: number }} options
+ * @returns {Promise<PullRequestFile[]>}
+ */
+export async function fetchPullRequestFiles({ github, owner, repo, pullNumber }) {
+  const files = await github.paginate(github.rest.pulls.listFiles, {
+    owner,
+    repo,
+    pull_number: pullNumber,
+    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.`);
+    }
+  }
+  return files;
+}
+
+/**
+ * @param {{ config: VisualRegressionConfig, files: PullRequestFile[] }} options
+ * @returns {ScopeDecision}
+ */
+export function resolveScopeDecision({ config, files }) {
+  if (files.length >= 3000) {
+    return { shouldRun: true, reason: 'changed_files_truncated', selectedRouteIds: (config.routes || []).map((route) => route.id) };
+  }
+  const changedFiles = [...new Set(files.flatMap((file) => [
+    file.filename,
+    ...(file.status === 'renamed' && typeof file.previous_filename === 'string' && file.previous_filename
+      ? [file.previous_filename]
+      : [])
+  ]))];
+  return selectRoutesForChangedFiles(config, changedFiles);
+}
+
+/**
+ * @param {{
+ *   github: ScopeGitHubClient,
+ *   owner: string,
+ *   repo: string,
+ *   config: VisualRegressionConfig,
+ *   pullNumber: number,
+ *   routeIds?: string,
+ *   forceRun?: boolean,
+ *   forceRunReason?: string,
+ *   warning?: (message: string) => void
+ * }} options
+ * @returns {Promise<ScopeDecision>}
+ */
+export async function resolvePullRequestScope({ github, owner, repo, config, pullNumber, routeIds = '', forceRun = false, forceRunReason = 'forced', warning = (_message) => {} }) {
+  const allRouteIds = (config.routes || []).map((route) => route.id);
+  const explicitRouteIds = splitCommaList(routeIds);
+  if (explicitRouteIds.length > 0) {
+    const selected = selectConfiguredRoutes(config, explicitRouteIds);
+    return { shouldRun: true, reason: 'explicit_route_ids', selectedRouteIds: selected.selectedRouteIds };
+  }
+  if (forceRun) {
+    return { shouldRun: true, reason: forceRunReason || 'forced', selectedRouteIds: allRouteIds };
+  }
+  if (!Number.isFinite(pullNumber) || pullNumber <= 0) {
+    return { shouldRun: true, reason: 'missing_pr_number', selectedRouteIds: allRouteIds };
+  }
+  try {
+    const files = await fetchPullRequestFiles({ github, owner, repo, pullNumber });
+    const scope = resolveScopeDecision({ config, files });
+    if (scope.reason === 'changed_files_truncated') {
+      warning('GitHub returned the maximum 3000 changed-file records; the list may be truncated, so running all configured captures.');
+    }
+    return scope;
+  } catch (error) {
+    warning(`Unable to inspect PR files for SnapDrift scope; running all configured captures instead. ${error.message}`);
+    return { shouldRun: true, reason: 'snapdrift_scope_check_failed', selectedRouteIds: allRouteIds };
+  }
+}
+
+/**
+ * @param {{
+ *   github: CommentGitHubClient,
+ *   owner: string,
+ *   repo: string,
+ *   issueNumber: number,
+ *   body: string,
+ *   markers: readonly string[]
+ * }} options
+ * @returns {Promise<void>}
+ */
+export async function upsertPullRequestReportComment({ github, owner, repo, issueNumber, body, markers }) {
+  const comments = await github.paginate(github.rest.issues.listComments, {
+    owner,
+    repo,
+    issue_number: issueNumber,
+    per_page: 100
+  });
+  const matchingComments = comments
+    .filter((comment) => comment.body && markers.some((marker) => comment.body.includes(marker)))
+    .sort((left, right) => {
+      const leftTime = new Date(left.updated_at || left.created_at).getTime();
+      const rightTime = new Date(right.updated_at || right.created_at).getTime();
+      return rightTime - leftTime;
+    });
+  const existing = matchingComments[0];
+  if (existing) {
+    await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+  } else {
+    await github.rest.issues.createComment({ owner, repo, issue_number: issueNumber, body });
+  }
+  for (const duplicate of matchingComments.slice(1)) {
+    await github.rest.issues.deleteComment({ owner, repo, comment_id: duplicate.id });
+  }
+}

package/lib/outage-policy.mjs

@@ -73,10 +73,21 @@ function createBaselineLookupFallbackError(outageError, phase, lookupMessage) {
  * @returns {boolean}
  */
 export function hasLocalScreenshots(providerName, config) {
-  if (providerName !== 'snap') {
-    return true;
-  }
-  return isLocalBaseUrl(config?.baseUrl);
+  return describeCaptureArtifacts(providerName, undefined, config).localScreenshots;
+}
+
+/**
+ * Prefer provider-returned artifacts; infer capabilities only for legacy results.
+ *
+ * @param {string} providerName
+ * @param {Partial<CaptureResult>} [result]
+ * @param {VisualRegressionConfig} [config]
+ * @returns {{ localScreenshots: boolean, artifactsRoot?: string }}
+ */
+export function describeCaptureArtifacts(providerName, result, config) {
+  if (result?.artifacts) return result.artifacts;
+  const localScreenshots = providerName !== 'snap' || isLocalBaseUrl(config?.baseUrl);
+  return { localScreenshots, artifactsRoot: localScreenshots ? result?.screenshotsRoot : undefined };
 }
 
 /**
@@ -97,7 +108,8 @@ export function hasLocalScreenshots(providerName, config) {
  *   outcome: 'captured' | 'skipped',
  *   providerName: string,
  *   result?: CaptureResult,
- *   localScreenshots: boolean
+ *   localScreenshots: boolean,
+ *   artifacts: ReturnType<typeof describeCaptureArtifacts>
  * }>}
  */
 export async function captureWithPolicy(options) {
@@ -108,16 +120,18 @@ export async function captureWithPolicy(options) {
 
   try {
     const result = await options.provider.capture(options.captureOptions);
+    const artifacts = describeCaptureArtifacts(providerName, result, options.config);
     return {
       outcome: 'captured',
       providerName,
       result,
-      localScreenshots: hasLocalScreenshots(providerName, options.config)
+      artifacts,
+      localScreenshots: artifacts.localScreenshots
     };
   } catch (error) {
     if (error instanceof SnapSkipError) {
       onSkip(error);
-      return { outcome: 'skipped', providerName, localScreenshots: false };
+      return { outcome: 'skipped', providerName, localScreenshots: false, artifacts: { localScreenshots: false } };
     }
     if (error instanceof SnapFallbackError) {
       onFallback(error);
@@ -127,7 +141,8 @@ export async function captureWithPolicy(options) {
       const result = await createLocalProvider().capture(options.captureOptions);
       // The rest of the pipeline must be told the *effective* provider, not the
       // configured one — otherwise it rebuilds SnapProvider around local output.
-      return { outcome: 'captured', providerName: 'local', result, localScreenshots: true };
+      const artifacts = describeCaptureArtifacts('local', result, options.config);
+      return { outcome: 'captured', providerName: 'local', result, localScreenshots: artifacts.localScreenshots, artifacts };
     }
     throw error;
   }
@@ -147,12 +162,19 @@ export async function captureWithPolicy(options) {
  *    does not, so we recapture locally first rather than diffing a manifest of
  *    zero-dimension placeholders.
  *
+ * Capability precedence: legacy `localScreenshots` overrides `artifacts`, then
+ * `captureResult.artifacts`, then provider/config inference. Without any of those
+ * inputs (including config), preserve the legacy local-screenshots default.
+ *
  * @param {{
  *   provider: VisualProvider,
  *   providerName?: string,
  *   diffOptions: DiffOptions,
+ *   captureResult?: CaptureResult,
  *   captureOptions?: CaptureOptions,
  *   localScreenshots?: boolean,
+ *   artifacts?: ReturnType<typeof describeCaptureArtifacts>,
+ *   config?: VisualRegressionConfig,
  *   baselineAvailable?: boolean,
  *   createLocalProvider?: () => VisualProvider,
  *   onSkip?: (error: SnapSkipError) => void,
@@ -166,11 +188,23 @@ export async function captureWithPolicy(options) {
  *   outcome: 'diffed' | 'skipped' | 'baseline-unavailable',
  *   providerName: string,
  *   result?: DiffResult,
- *   recapture?: CaptureResult
+ *   recapture?: CaptureResult,
+ *   localScreenshots: boolean,
+ *   artifacts: ReturnType<typeof describeCaptureArtifacts>
  * }>}
  */
 export async function diffWithPolicy(options) {
   const providerName = options.providerName || 'local';
+  /** @type {Partial<CaptureResult>} */
+  const captureResult = options.captureResult || { screenshotsRoot: options.diffOptions.currentRunDir };
+  const described = options.artifacts || (captureResult.artifacts || options.config
+    ? describeCaptureArtifacts(providerName, captureResult, options.config)
+    : { localScreenshots: true, artifactsRoot: captureResult.screenshotsRoot });
+  let artifacts = {
+    ...described,
+    localScreenshots: options.localScreenshots ?? described.localScreenshots
+  };
+  if (!artifacts.localScreenshots) artifacts.artifactsRoot = undefined;
   const createLocalProvider = options.createLocalProvider || (() => createProvider('local'));
   const onSkip = options.onSkip || noop;
   const onFallback = options.onFallback || noop;
@@ -179,11 +213,11 @@ export async function diffWithPolicy(options) {
 
   try {
     const result = await options.provider.diff(options.diffOptions);
-    return { outcome: 'diffed', providerName, result };
+    return { outcome: 'diffed', providerName, result, artifacts, localScreenshots: artifacts.localScreenshots };
   } catch (error) {
     if (error instanceof SnapSkipError) {
       onSkip(error);
-      return { outcome: 'skipped', providerName };
+      return { outcome: 'skipped', providerName, artifacts, localScreenshots: artifacts.localScreenshots };
     }
     if (!(error instanceof SnapFallbackError)) {
       throw error;
@@ -199,7 +233,7 @@ export async function diffWithPolicy(options) {
       if (options.baselineResolutionStatus === 'error') {
         throw createBaselineLookupFallbackError(error, 'diff', options.baselineResolutionMessage);
       }
-      return { outcome: 'baseline-unavailable', providerName: 'local' };
+      return { outcome: 'baseline-unavailable', providerName: 'local', artifacts, localScreenshots: artifacts.localScreenshots };
     }
 
     if (options.baselineResolutionStatus === 'error') {
@@ -211,7 +245,7 @@ export async function diffWithPolicy(options) {
     /** @type {CaptureResult | undefined} */
     let recapture;
 
-    if (options.localScreenshots === false) {
+    if (!artifacts.localScreenshots) {
       if (!options.captureOptions) {
         throw new Error(
           'Cannot fall back to a local diff: the current capture has no screenshots on disk ' +
@@ -221,6 +255,7 @@ export async function diffWithPolicy(options) {
       }
       onRecapture();
       recapture = await localProvider.capture(options.captureOptions);
+      artifacts = describeCaptureArtifacts('local', recapture, options.config);
       diffOptions = {
         ...options.diffOptions,
         currentResultsPath: recapture.resultsPath,
@@ -230,7 +265,7 @@ export async function diffWithPolicy(options) {
     }
 
     const result = await localProvider.diff(diffOptions);
-    return { outcome: 'diffed', providerName: 'local', result, recapture };
+    return { outcome: 'diffed', providerName: 'local', result, recapture, artifacts, localScreenshots: artifacts.localScreenshots };
   }
 }
 

package/lib/provider.mjs

@@ -35,7 +35,8 @@ export class LocalProvider {
    * @returns {Promise<CaptureResult>}
    */
   async capture(options) {
-    return runBaselineCapture(options);
+    const result = await runBaselineCapture(options);
+    return { ...result, artifacts: { localScreenshots: true, artifactsRoot: result.screenshotsRoot } };
   }
 
   /**
@@ -58,6 +59,7 @@ export class LocalProvider {
   /**
    * @param {FetchBaselineOptions} _options
    * @returns {Promise<never>}
+   * Guard with providerSupports(providerName, 'fetchLatestBaseline') before calling.
    * @throws {Error} Not yet implemented for LocalProvider.
    *   Use the pr-diff action for baseline resolution, or wait for a future release.
    */
@@ -80,6 +82,22 @@ export class LocalProvider {
   }
 }
 
+export const PROVIDER_CAPABILITIES = Object.freeze({
+  local: Object.freeze({ capture: true, diff: true, publishBaseline: true, fetchLatestBaseline: false, buildCommentBody: true }),
+  snap: Object.freeze({ capture: true, diff: true, publishBaseline: true, fetchLatestBaseline: true, buildCommentBody: true })
+});
+
+/**
+ * @param {string} providerName
+ * @param {string} capability
+ * @returns {boolean}
+ */
+export function providerSupports(providerName, capability) {
+  return Object.hasOwn(PROVIDER_CAPABILITIES, providerName) &&
+    Object.hasOwn(PROVIDER_CAPABILITIES[providerName], capability) &&
+    PROVIDER_CAPABILITIES[providerName][capability] === true;
+}
+
 /** @type {{ local: (config?: VisualRegressionConfig) => LocalProvider, snap: (config: VisualRegressionConfig) => SnapProvider }} */
 const PROVIDER_FACTORIES = {
   local: () => new LocalProvider(),

package/lib/snap-provider.mjs

@@ -948,6 +948,7 @@ export class SnapProvider {
       resultsPath,
       manifestPath,
       screenshotsRoot: outDir,
+      artifacts: { localScreenshots: false, artifactsRoot: undefined },
       selectedRouteIds
     };
   }
@@ -1963,7 +1964,7 @@ export class SnapProvider {
     };
     await fs.writeFile(localCapture.resultsPath, JSON.stringify(snapResults, null, 2));
 
-    return localCapture;
+    return { ...localCapture, artifacts: { localScreenshots: true, artifactsRoot: localCapture.screenshotsRoot } };
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",
@@ -81,6 +81,7 @@
     "./lib/cli.mjs": "./lib/cli.mjs",
     "./lib/provider.mjs": "./lib/provider.mjs",
     "./lib/outage-policy.mjs": "./lib/outage-policy.mjs",
+    "./lib/github-requests.mjs": "./lib/github-requests.mjs",
     "./lib/snap-provider.mjs": "./lib/snap-provider.mjs",
      "./lib/migrate-baselines.mjs": "./lib/migrate-baselines.mjs",
      "./lib/init-from-action.mjs": "./lib/init-from-action.mjs",
@@ -102,10 +103,10 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@snapdrift/adapter-fs": "^1.3.0",
-    "@snapdrift/adapter-report-md": "^1.2.1",
-    "@snapdrift/compare-core": "^1.3.0",
-    "@snapdrift/manifest": "^1.4.0",
+    "@snapdrift/adapter-fs": "^1.4.0",
+    "@snapdrift/adapter-report-md": "^1.3.0",
+    "@snapdrift/compare-core": "^1.4.0",
+    "@snapdrift/manifest": "^1.5.0",
     "js-yaml": "^5.4.0",
     "playwright": "^1.59.1",
     "pngjs": "^7.0.0"

package/types/visual-diff-types.d.ts

@@ -192,6 +192,7 @@ export interface VisualDiffSummary {
   changed: VisualDiffChangedItem[];
   missing: VisualDiffMissingItem[];
   errors: VisualDiffErrorItem[];
+  captureCompatibility?: import('@snapdrift/manifest').CaptureCompatibility;
   dimensionChanges: VisualDiffDimensionItem[];
   comparisonPolicy?: ComparisonPolicy;
   message?: string;