snapdrift 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,118 @@
 # Changelog
 
+## Unreleased
+
+## 0.14.0 - 2026-09-21
+
+Workspace releases this version:
+
+- `@snapdrift/compare-core` 1.5.0 — bounded vertical row alignment and comparison
+  policy v2, with conservative coordinate fallbacks and resource limits.
+- `@snapdrift/manifest` 1.6.0 — policy v2 validation, constants, and comparison types.
+- `@snapdrift/adapter-fs` 1.5.0 — local policy v2 comparison and summary types.
+- `@snapdrift/adapter-report-md` 1.4.0 — alignment and fallback details in Markdown,
+  HTML, and bounded PR comments.
+
+Root and workspace dependency floors require these versions so upgrades receive
+all parts of the policy v2 implementation. The dispatcher pins `576e774`, the
+#176 merge commit on `main`, including the runtime loaded by both wrapper actions.
+
+### Features
+
+- Added opt-in comparison policy v2 with bounded vertical row alignment for
+  inserted and deleted page rows. Unchanged content that shifts after an
+  insertion remains matched; reports record aligned results and conservative
+  coordinate fallbacks. Deprecated policy v1 remains the compatibility default
+  so existing configurations are unchanged; new configurations should use v2.
+
+- Snap-provider requests forward policy v2 and validate hosted acknowledgements
+  and alignment metadata. Hosted use requires matching Snap service support;
+  publishing this library does not deploy the hosted service.
+
+## 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.14.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.14.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)
@@ -117,7 +121,7 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 - Viewport presets: `desktop` (1440×900) and `mobile` (390×844), or custom `{ "width": number, "height": number }`
 - Full-page comparisons are bounded to a 32 Mi-pixel union canvas; see the [screenshot size budget](docs/contracts.md#screenshot-size-budget) for viewport, device-scale, and remediation guidance
 - One global `diff.threshold`
-- Unequal dimensions compare on a top-left-aligned union canvas via comparison policy v1, which is always applied (synthesized from `diff.threshold` when `diff.comparisonPolicy` is absent)
+- Unequal dimensions use deprecated top-left union comparison policy v1 by default for compatibility; new configurations should opt into policy v2 with `{ "version": 2, "threshold": number }` for bounded vertical row alignment of inserted/deleted content
 - Local provider writes artifacts to the runner filesystem; for a hosted backend with a dashboard and a shared baseline store, configure `provider: "snap"` (see the [Integration Guide](docs/integration-guide.md#hosted-snap-provider))
 - Hosted Snap baselines publish only from the default branch and always include the complete configured route set
 

package/action.yml

@@ -155,7 +155,7 @@ runs:
     - name: SnapDrift baseline
       id: baseline
       if: inputs.mode == 'baseline'
-      uses: ranacseruet/snapdrift/actions/baseline@e4b92c2243c6e69594cab7405f68eb58fe94587e # v0.12.0
+      uses: ranacseruet/snapdrift/actions/baseline@576e774845c29288a0061365e4905009533e0e01 # v0.14.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@576e774845c29288a0061365e4905009533e0e01 # v0.14.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(','));