snapdrift 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,136 @@
 # 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
+
+- **PR comments no longer render `[object Object]` for a viewport.** A viewport is
+  either a preset name or a `{ width, height }` object, and the PR-comment renderer
+  stringified it directly. Hosted diff runs always build the object form, so every
+  hosted report printed the useless placeholder in its Error, Drift signals, and
+  Dimension shifts tables. All three report renderers now share one
+  `formatViewport` helper (exported from `@snapdrift/adapter-report-md`).
+
+### Features
+
+- **`compareImages` accepts a per-call `maxPixels` union-canvas ceiling.**
+  `MAX_COMPARISON_PIXELS` (32 Mi) is a *process memory* bound, not an algorithm
+  property, so callers with a larger envelope — a dedicated diff Lambda — can raise
+  it while callers sharing a small host keep the default. A missing, non-positive,
+  or non-finite value falls back to the default, so the guard cannot be removed by
+  accident. The `ComparisonTooLargeError` message now reports the ceiling that was
+  actually exceeded.
+
+### Documentation
+
+- Document that `migrate-baselines --to snap` is unsupported and point to
+  `snapdrift baseline` as the supported way to seed a hosted project. The
+  integration guide still described the retired upload direction as a working
+  one-shot command, and the contracts reference documented its request body,
+  idempotency, and storage behavior as if it succeeded. Both contradicted the
+  CLI, which has failed the direction since 0.7.0 with a pointer to
+  `snapdrift baseline`.
+- Document the screenshot size budget's memory cost for `maxPixels` callers: the
+  comparison retains both decoded RGBA inputs plus the optional diff canvas, so the
+  floor is roughly 12 bytes per union pixel before PNG overhead (~32-35 measured end
+  to end), and the ceiling should be sized against a measured peak rather than that
+  arithmetic.
+
+### Workspace packages
+
+- `@snapdrift/adapter-report-md` 1.2.1 publishes the `[object Object]` viewport fix;
+  `@snapdrift/compare-core` 1.3.0 publishes the per-call `maxPixels` option and the
+  new size-budget guidance.
+- The root package's dependency floors move to `^1.2.1` (adapter-report-md) and
+  `^1.3.0` (compare-core) so `snapdrift` 0.12.0 actually requires those fixes. A
+  retained lockfile resolution of adapter-report-md 1.2.0 still satisfies `^1.2.0`,
+  so without the floor bump an upgrade of `snapdrift` alone could install the
+  unfixed report renderer.
+
 ## 0.11.0 - 2026-09-14
 
 ### Behavior changes

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.11.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.11.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@799cfb16ff9d51e57d515cdddd4b329950574ef2 # v0.11.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@799cfb16ff9d51e57d515cdddd4b329950574ef2 # v0.11.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(','));