snapdrift 0.8.2 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 0.10.0 - 2026-09-10
+
+### Fixes
+
+- **PR diff artifacts remain reviewable from GitHub comments** — generated local
+  diff paths are now linked to the authenticated Actions artifact (or workflow
+  run fallback) instead of being emitted as broken relative image URLs. Hosted
+  legacy captures also retain their reported dimensions and pixel denominator
+  when v1 comparison metadata is absent.
+
+### Features
+
+- **Unequal-dimension comparisons** — `@snapdrift/compare-core` now exposes
+  `compareImages()` for top-left-aligned union-canvas comparisons while the
+  existing strict APIs remain unchanged. Updated local and hosted providers
+  explicitly request comparison policy v1, record comparison dimensions and the
+  geometric union denominator, stage a generated diff PNG, and render it in
+  Markdown, HTML, and PR reports. Low-level public adapter calls remain strict
+  unless they opt in with `diff.comparisonPolicy`. Legacy dimension shifts remain
+  in `dimensionChanges[]`; completed v1 dimension changes are `changed[]` signals
+  and do not fail `fail-on-incomplete` alone.
+
+- **Workspace packages** — publish `@snapdrift/manifest` 1.4.0,
+  `@snapdrift/compare-core` 1.1.0, `@snapdrift/adapter-report-md` 1.2.0, and
+  `@snapdrift/adapter-fs` 1.2.0 before activating the updated hosted Snap client.
+
+## 0.9.0 - 2026-09-09
+
+### Fixes
+
+- **Workspace packages now declare their runtime dependency boundaries** (#148).
+  `@snapdrift/adapter-fs` declares `@snapdrift/adapter-report-md`, and an isolated
+  packed-consumer gate imports every workspace package with only its declared
+  local dependency closure. Repository workspaces can no longer mask a missing
+  runtime dependency.
+
+- **Published workspace TypeScript contracts resolve under modern module resolution** (#135, #129). All four `@snapdrift/*` packages expose declarations through their export maps, include signatures for every public runtime export, and correct stale declaration references. Strict declaration checks and isolated packed-package consumer fixtures now run in CI.
+
+- **Snap transport now has enforceable request and operation deadlines** (#150). JSON requests
+  settle stalled headers or bodies within 30 seconds, binary exports within 120 seconds, and each
+  Snap operation shares a 10-minute budget across requests, retries, backoff, and polling. Aborted
+  or otherwise exhausted transport operations now reach the configured `onUnavailable` policy;
+  received 4xx responses remain immediate and non-retryable, while stalled 4xx diagnostics retain
+  their HTTP status with a timeout diagnostic.
+- **Renamed files now retain both paths during route scoping** (#149). The
+  `scope` and `pr-diff` actions include a nonempty `previous_filename` for
+  GitHub rename records, deduplicate the combined paths, and preserve the
+  existing force-run and lookup-fallback behavior (with explicit route ids
+  still taking precedence in `pr-diff`). If GitHub returns its 3,000-record
+  cap, both actions run all configured routes with reason
+  `changed_files_truncated` rather than trust an incomplete list. A file moved
+  out of a watched directory can no longer silently skip its route.
+- **Sanitized route-id collisions are rejected before writing screenshots** (#126). Local capture now fails before browser work, while Snap baseline export validates every source route after downloading the archive and before returning or writing screenshot files. Both paths share the same route-id sanitizer when distinct ids would map to one filename. Existing manifests with duplicate or flattening `imagePath` values also fail closed, including scoped comparisons; rename the conflicting ids and recapture the affected baseline. The published package floors move `@snapdrift/manifest` to 1.3.0 and `@snapdrift/adapter-fs` to 1.1.0 so consumers receive the shared helper.
+- **Baseline lookup failures no longer masquerade as missing artifacts** (#147). The baseline
+  resolver now reports `found`, `missing`, or `error`, fails standalone resolution on API/network/
+  malformed responses, and keeps the PR wrapper's hosted Snap path available while failing local
+  comparisons and local fallbacks when GitHub cannot provide the baseline. The existing intentional
+  first-run skipped summary remains limited to a successful lookup with no non-expired artifact.
+- **Hosted Snap diffs now fail closed on incomplete results** (#146). Hosted comparison now validates `purpose: "diff"`, the persisted run metadata, and expected route/viewport identities, polls until the expected capture set is available, verifies the returned run id and paths, and rejects duplicate, missing, pending, malformed, or invalid captures as `incomplete`. A diffed capture is counted only when both image objects and a finite numeric `diffPct` are present; older results without expected capture identities must be recaptured instead of being treated as clean.
+
+### Changed
+
+- **Standalone baseline resolution now fails on lookup errors** (#147). Consumers orchestrating
+  `actions/resolve-baseline` should handle its `resolution-status` output: `missing` is the
+  intentional first-baseline case, while `error` means the GitHub lookup could not be trusted and
+  fails the action. The PR wrapper keeps hosted Snap comparisons available and reports the status
+  through `baseline-resolution-status`.
+
+### Chore
+
+- **The release workflow now fails when the root dispatcher's immutable pin predates wrapper changes** (#133). The Marketplace `action.yml` pins its inner `baseline` / `pr-diff` refs to an immutable commit SHA, but nothing detected when that pin went stale: between releases every change to `actions/baseline` or `actions/pr-diff` stayed invisible to consumers of the root action, so a release could ship bumped wrapper code while the dispatcher still executed old wrapper code at the pinned SHA. `npm run check:pin-stale` (new `scripts/check-pin-stale.mjs`) fails when the pinned SHA is older than the newest commit touching `actions/`. It runs in `publish.yml` (gated on a published release) rather than on every PR, because the pin is expected to lag wrapper changes on feature branches. The currently-stale pin in `action.yml` (which predated the #136 hosted-baseline fix) has been bumped to the latest `main` commit.
+
+- **Workspace patch releases ship previously-unpublished fixes.** `@snapdrift/compare-core` 1.0.1 and `@snapdrift/adapter-report-md` 1.1.1 publish the #154 and #158 changes that landed after 1.0.0 / 1.1.0 were already on npm; without new versions those fixes would not have shipped. `@snapdrift/manifest` 1.3.0 and `@snapdrift/adapter-fs` 1.1.0 publish for the first time in this release. Workflow examples in the README, Integration Guide, and baseline template now reference `@v0.9.0`.
+
 ## 0.8.2 - 2026-08-24
 
 ### 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.8.2
+  uses: ranacseruet/snapdrift@v0.10.0
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
@@ -60,7 +60,7 @@ With `provider: "snap"`, baseline publication is a complete, fail-closed snapsho
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.8.2
+  uses: ranacseruet/snapdrift@v0.10.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -71,6 +71,11 @@ That is the full integration. See the [Integration Guide](docs/integration-guide
 
 The root action dispatches on `mode`. The same pipelines are also published as standalone actions — `ranacseruet/snapdrift/actions/baseline` and `ranacseruet/snapdrift/actions/pr-diff` — along with the lower-level `capture`, `compare`, `scope`, `resolve-baseline`, `stage`, `comment`, and `enforce` actions for custom orchestration.
 
+The lower-level `resolve-baseline` action reports `resolution-status` as `found`, `missing`, or
+`error`. A successful lookup with no non-expired artifact is `missing`; GitHub API, permission,
+network, or malformed-response failures are `error` and fail the standalone action so custom
+workflows do not mistake an unavailable baseline for a first-run skip.
+
 ## Local CLI
 
 SnapDrift ships a `snapdrift` CLI for running captures, diffs, migrations, and config initialization locally against a running app. Use it during development to validate UI changes before pushing. Canonical hosted baseline publication is the exception: `provider: "snap"` baselines require the project default branch plus explicit CI publication metadata; GitHub Actions provides that metadata automatically.
@@ -111,7 +116,7 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 - Full-page capture only
 - Viewport presets: `desktop` (1440×900) and `mobile` (390×844), or custom `{ "width": number, "height": number }`
 - One global `diff.threshold`
-- Dimension shifts are reported separately from pixel drift
+- Unequal dimensions remain strict by default; local updated clients may opt in with `diff.comparisonPolicy: { "version": 1, "threshold": number }`
 - Local provider writes artifacts to the runner filesystem; for a hosted backend with a dashboard and a shared baseline store, configure `provider: "snap"` (see the [Integration Guide](docs/integration-guide.md#hosted-snap-provider))
 - Hosted Snap baselines publish only from the default branch and always include the complete configured route set
 

package/action.yml

@@ -20,6 +20,11 @@ branding:
 # version uses its upcoming `@vX.Y.Z` tag; the release process replaces it with the commit that holds
 # the wrapper content. The contract test accepts either form and requires the declared version to
 # match package.json.
+#
+# The release workflow also runs `npm run check:pin-stale`, which fails when the pinned SHA predates
+# the newest commit touching `actions/`; that keeps a stale pin from silently serving old wrapper code
+# to Marketplace consumers. The check is release-time only, since the pin is expected to lag wrapper
+# changes on feature branches.
 
 inputs:
   mode:
@@ -120,6 +125,9 @@ outputs:
   baseline-found:
     description: Whether a usable baseline was found.
     value: ${{ steps.pr-diff.outputs.baseline-found }}
+  baseline-resolution-status:
+    description: 'Baseline lookup status: found, missing, or error.'
+    value: ${{ steps.pr-diff.outputs.baseline-resolution-status }}
   status:
     description: Final SnapDrift status.
     value: ${{ steps.pr-diff.outputs.status }}
@@ -147,7 +155,7 @@ runs:
     - name: SnapDrift baseline
       id: baseline
       if: inputs.mode == 'baseline'
-      uses: ranacseruet/snapdrift/actions/baseline@f1ded4c7c0eb944b35eb8f70f8711f4f84397813 # v0.8.2
+      uses: ranacseruet/snapdrift/actions/baseline@80d61b668942dd87c33cf51598623a904becf82f # v0.10.0
       with:
         repo-config-path: ${{ inputs.repo-config-path }}
         route-ids: ${{ inputs.route-ids }}
@@ -157,7 +165,7 @@ runs:
     - name: SnapDrift pull request diff
       id: pr-diff
       if: inputs.mode == 'pr-diff'
-      uses: ranacseruet/snapdrift/actions/pr-diff@f1ded4c7c0eb944b35eb8f70f8711f4f84397813 # v0.8.2
+      uses: ranacseruet/snapdrift/actions/pr-diff@80d61b668942dd87c33cf51598623a904becf82f # v0.10.0
       with:
         github-token: ${{ inputs.github-token }}
         repo-config-path: ${{ inputs.repo-config-path }}

package/actions/comment/action.yml

@@ -24,6 +24,10 @@ inputs:
     description: Artifact label to include in the comment.
     required: false
     default: ''
+  artifact-url:
+    description: Authenticated URL to the uploaded report artifact.
+    required: false
+    default: ''
   repo-config-path:
     description: Path to the SnapDrift config file (needed for provider-aware comment rendering).
     required: false
@@ -58,6 +62,7 @@ runs:
         VISUAL_DIFF_SUMMARY_PATH: ${{ inputs.summary-path }}
         VISUAL_DIFF_RUN_URL: ${{ inputs.run-url }}
         VISUAL_DIFF_ARTIFACT_NAME: ${{ inputs.artifact-name }}
+        VISUAL_DIFF_ARTIFACT_URL: ${{ inputs.artifact-url }}
         INPUT_PR_NUMBER: ${{ inputs.pr-number }}
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
@@ -105,6 +110,7 @@ runs:
           const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
           const body = provider.buildCommentBody(summary, {
             artifactName: process.env.VISUAL_DIFF_ARTIFACT_NAME || '',
+            artifactUrl: process.env.VISUAL_DIFF_ARTIFACT_URL || '',
             runUrl,
             maxChangedRows,
             maxErrorRows

package/actions/compare/action.yml

@@ -67,6 +67,9 @@ outputs:
   markdown-path:
     description: Absolute path to the generated summary markdown file.
     value: ${{ steps.compare.outputs.markdown_path }}
+  diff-images-dir:
+    description: Absolute path to generated local diff PNGs.
+    value: ${{ steps.compare.outputs.diff_images_dir }}
   status:
     description: Computed SnapDrift status.
     value: ${{ steps.compare.outputs.status }}
@@ -133,6 +136,7 @@ runs:
         const resolvedOutDir = path.resolve(process.env.OUT_DIR || 'qa-artifacts/snapdrift/drift/current');
         const resolvedSummaryPath = path.resolve(process.env.SUMMARY_PATH || path.join(resolvedOutDir, 'summary.json'));
         const resolvedMarkdownPath = path.resolve(process.env.MARKDOWN_PATH || path.join(resolvedOutDir, 'summary.md'));
+        const resolvedDiffImagesDir = path.join(resolvedOutDir, 'diffs');
 
         await runDriftCheckCli({
           configPath: process.env.REPO_CONFIG_PATH || undefined,
@@ -143,6 +147,7 @@ runs:
           baselineRunDir: process.env.BASELINE_RUN_DIR || undefined,
           currentRunDir: process.env.CURRENT_RUN_DIR || undefined,
           outDir: resolvedOutDir,
+          diffImagesDir: resolvedDiffImagesDir,
           summaryPath: resolvedSummaryPath,
           markdownPath: resolvedMarkdownPath,
           routeIds: splitCommaList(process.env.ROUTE_IDS),
@@ -155,6 +160,7 @@ runs:
         const outputs = [
           `summary_path=${resolvedSummaryPath}`,
           `markdown_path=${resolvedMarkdownPath}`,
+          `diff_images_dir=${resolvedDiffImagesDir}`,
           `status=${summary.status || ''}`,
           `changed_screenshots=${summary.changedScreenshots || 0}`,
           `matched_screenshots=${summary.matchedScreenshots || 0}`,

package/actions/pr-diff/action.yml

@@ -71,6 +71,9 @@ outputs:
   baseline-found:
     description: Whether a usable baseline was found.
     value: ${{ steps.finalize.outputs.baseline_found }}
+  baseline-resolution-status:
+    description: 'Baseline lookup status: found, missing, or error.'
+    value: ${{ steps.finalize.outputs.baseline_resolution_status }}
   status:
     description: Final SnapDrift status.
     value: ${{ steps.finalize.outputs.status }}
@@ -182,10 +185,33 @@ runs:
               per_page: 100
             });
 
+            if (!Array.isArray(files)) {
+              throw new Error('Malformed GitHub changed-file response: expected an array of file records.');
+            }
+            for (const [index, file] of files.entries()) {
+              if (!file || typeof file !== 'object' || typeof file.filename !== 'string' || file.filename.length === 0) {
+                throw new Error(`Malformed GitHub changed-file response: file record ${index} must include a non-empty string filename.`);
+              }
+            }
+            if (files.length >= 3000) {
+              core.warning('GitHub returned the maximum 3000 changed-file records; the list may be truncated, so running all configured captures.');
+              setOutputs({
+                shouldRun: true,
+                reason: 'changed_files_truncated',
+                selectedRouteIds: allRouteIds
+              });
+              return;
+            }
+            const changedFiles = [...new Set(files.flatMap((file) => [
+              file.filename,
+              ...(file.status === 'renamed' && typeof file.previous_filename === 'string' && file.previous_filename
+                ? [file.previous_filename]
+                : [])
+            ]))];
             setOutputs(
               selectRoutesForChangedFiles(
                 config,
-                files.map((file) => file.filename)
+                changedFiles
               )
             );
           } catch (error) {
@@ -212,61 +238,40 @@ runs:
           const { pathToFileURL } = require('url');
 
           const repository = process.env.INPUT_REPOSITORY || `${context.repo.owner}/${context.repo.repo}`;
-          const [owner, repo] = repository.split('/');
           const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+          const resolverModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/resolve-baseline-artifact.mjs');
           const { loadSnapdriftConfig } = await import(pathToFileURL(modulePath));
-          const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-          const artifactName = config.baselineArtifactName;
+          const { resolveBaselineArtifact } = await import(pathToFileURL(resolverModulePath));
+          let artifactName = '';
+
+          const setLookupError = (error) => {
+            const detail = error instanceof Error ? error.message : String(error);
+            const message = `Unable to resolve the SnapDrift baseline artifact: ${detail}`;
+            core.setOutput('found', 'false');
+            core.setOutput('resolution_status', 'error');
+            core.setOutput('artifact_name', artifactName);
+            core.setOutput('message', message);
+            core.warning(message);
+          };
 
           try {
-            const runs = await github.paginate(github.rest.actions.listWorkflowRuns, {
-              owner,
-              repo,
-              workflow_id: process.env.INPUT_WORKFLOW_ID || 'ci.yml',
+            const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+            artifactName = config.baselineArtifactName;
+            const result = await resolveBaselineArtifact({
+              github,
+              repository,
+              workflowId: process.env.INPUT_WORKFLOW_ID || 'ci.yml',
               branch: process.env.INPUT_BRANCH || 'main',
-              event: 'push',
-              per_page: 20
+              artifactName
             });
-
-            let selectedRun = null;
-            let selectedArtifact = null;
-
-            for (const run of runs) {
-              if (run.status !== 'completed' || run.conclusion !== 'success') {
-                continue;
-              }
-
-              const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
-                owner,
-                repo,
-                run_id: run.id,
-                per_page: 100
-              });
-
-              const match = artifacts.data.artifacts.find((artifact) => artifact.name === artifactName && !artifact.expired);
-              if (match) {
-                selectedRun = run;
-                selectedArtifact = match;
-                break;
-              }
-            }
-
-            if (!selectedRun || !selectedArtifact) {
-              core.setOutput('found', 'false');
-              core.setOutput('artifact_name', artifactName);
-              core.setOutput('message', `No non-expired SnapDrift baseline artifact named ${artifactName} was found.`);
-              return;
-            }
-
-            core.setOutput('found', 'true');
-            core.setOutput('artifact_name', selectedArtifact.name);
-            core.setOutput('head_sha', selectedRun.head_sha);
-            core.setOutput('run_id', String(selectedRun.id));
-            core.setOutput('message', '');
+            core.setOutput('found', String(result.found));
+            core.setOutput('resolution_status', result.resolutionStatus);
+            core.setOutput('artifact_name', result.artifactName);
+            core.setOutput('head_sha', result.headSha || '');
+            core.setOutput('run_id', result.runId || '');
+            core.setOutput('message', result.message);
           } catch (error) {
-            core.setOutput('found', 'false');
-            core.setOutput('artifact_name', artifactName);
-            core.setOutput('message', `Unable to resolve the SnapDrift baseline artifact: ${error.message}`);
+            setLookupError(error);
           }
 
     - if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found == 'true'
@@ -320,6 +325,16 @@ runs:
         await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
         EOF
 
+    - id: baseline_resolution_guard
+      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.resolution_status == 'error' && steps.config.outputs.provider != 'snap'
+      shell: bash
+      env:
+        BASELINE_MESSAGE: ${{ steps.baseline.outputs.message }}
+      run: |
+        set -euo pipefail
+        printf 'SnapDrift baseline lookup failed. %s\n' "$BASELINE_MESSAGE" >&2
+        exit 1
+
     - name: Install Playwright Chromium
       if: steps.scope.outputs.should_run == 'true' && (steps.config.outputs.provider != 'snap' || steps.config.outputs.on_unavailable == 'fallback-local' || steps.config.outputs.snap_local_capture == 'true')
       shell: bash
@@ -332,6 +347,8 @@ runs:
       env:
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         ROUTE_IDS: ${{ steps.scope.outputs.selected_route_ids }}
+        BASELINE_RESOLUTION_STATUS: ${{ steps.baseline.outputs.resolution_status }}
+        BASELINE_RESOLUTION_MESSAGE: ${{ steps.baseline.outputs.message }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -359,6 +376,8 @@ runs:
             configPath: process.env.REPO_CONFIG_PATH || undefined,
             routeIds
           },
+          baselineResolutionStatus: process.env.BASELINE_RESOLUTION_STATUS,
+          baselineResolutionMessage: process.env.BASELINE_RESOLUTION_MESSAGE,
           onSkip: () => process.stderr.write('[SnapDrift] Snap unavailable — skipping visual regression (warn-and-skip).\n'),
           onFallback: () => process.stderr.write('[SnapDrift] Snap unavailable — falling back to local provider.\n')
         });
@@ -414,6 +433,8 @@ runs:
         CAPTURE_PROVIDER: ${{ steps.capture.outputs.provider }}
         LOCAL_SCREENSHOTS: ${{ steps.capture.outputs.local_screenshots }}
         BASELINE_FOUND: ${{ steps.baseline.outputs.found }}
+        BASELINE_RESOLUTION_STATUS: ${{ steps.baseline.outputs.resolution_status }}
+        BASELINE_RESOLUTION_MESSAGE: ${{ steps.baseline.outputs.message }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -438,6 +459,7 @@ runs:
         const resolvedOutDir = path.resolve('qa-artifacts/snapdrift/drift/current');
         const resolvedSummaryPath = path.join(resolvedOutDir, 'summary.json');
         const resolvedMarkdownPath = path.join(resolvedOutDir, 'summary.md');
+        const resolvedDiffImagesDir = path.join(resolvedOutDir, 'diffs');
 
         const captureOptions = {
           configPath: process.env.REPO_CONFIG_PATH || undefined,
@@ -454,7 +476,8 @@ runs:
           baselineSourceSha: process.env.BASELINE_SOURCE_SHA || undefined,
           currentResultsPath: process.env.CURRENT_RESULTS_PATH || undefined,
           currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined,
-          currentRunDir: process.env.CURRENT_SCREENSHOTS_ROOT || undefined
+          currentRunDir: process.env.CURRENT_SCREENSHOTS_ROOT || undefined,
+          diffImagesDir: resolvedDiffImagesDir
         };
 
         const diffed = await diffWithPolicy({
@@ -464,10 +487,18 @@ runs:
           captureOptions,
           localScreenshots: process.env.LOCAL_SCREENSHOTS !== 'false',
           baselineAvailable: process.env.BASELINE_FOUND === 'true',
+          baselineResolutionStatus: process.env.BASELINE_RESOLUTION_STATUS,
+          baselineResolutionMessage: process.env.BASELINE_RESOLUTION_MESSAGE,
           onSkip: () => process.stderr.write('[SnapDrift] Snap unavailable during diff — skipping (warn-and-skip).\n'),
           onFallback: () => process.stderr.write('[SnapDrift] Snap unavailable during diff — falling back to local provider.\n'),
           onRecapture: () => process.stderr.write('[SnapDrift] The current capture was rendered by Snap, so it has no local screenshots — recapturing locally before diffing.\n'),
-          onBaselineUnavailable: () => process.stderr.write('[SnapDrift] No baseline artifact is available, so the local diff cannot run.\n')
+          onBaselineUnavailable: () => {
+            if (process.env.BASELINE_RESOLUTION_STATUS === 'error') {
+              process.stderr.write(`[SnapDrift] ${process.env.BASELINE_RESOLUTION_MESSAGE || 'The GitHub baseline lookup failed before local diff fallback.'}\n`);
+              return;
+            }
+            process.stderr.write('[SnapDrift] No baseline artifact is available, so the local diff cannot run.\n');
+          }
         });
 
         // Every non-throwing outcome writes a summary. A wrapper run that ends
@@ -543,7 +574,7 @@ runs:
         EOF
 
     - id: skipped_baseline
-      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found != 'true' && steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped'
+      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.resolution_status == 'missing' && steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped'
       shell: bash
       env:
         MESSAGE: ${{ steps.baseline.outputs.message }}
@@ -586,6 +617,7 @@ runs:
         CURRENT_MANIFEST_PATH: ${{ steps.compare.outputs.current_manifest_file || steps.capture.outputs.manifest_file }}
         BASELINE_SCREENSHOTS_DIR: ${{ steps.baseline_paths.outputs.screenshots_dir }}
         CURRENT_SCREENSHOTS_ROOT: ${{ steps.compare.outputs.current_screenshots_root || steps.capture.outputs.screenshots_root }}
+        DIFF_IMAGES_DIR: ${{ steps.compare.outputs.diff_images_dir }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -606,13 +638,15 @@ runs:
           baselineManifestPath: process.env.BASELINE_MANIFEST_PATH || undefined,
           currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined,
           baselineScreenshotsDir: process.env.BASELINE_SCREENSHOTS_DIR || undefined,
-          currentScreenshotsDir: currentScreenshotsRoot ? path.join(currentScreenshotsRoot, 'screenshots') : undefined
+          currentScreenshotsDir: currentScreenshotsRoot ? path.join(currentScreenshotsRoot, 'screenshots') : undefined,
+          diffImagesDir: process.env.DIFF_IMAGES_DIR || undefined
         });
 
         await fs.appendFile(process.env.GITHUB_OUTPUT, `bundle_dir=${result.bundleDir}\n`);
         EOF
 
-    - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+    - id: upload
+      uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
       with:
         name: ${{ steps.context.outputs.artifact_name }}
         retention-days: ${{ inputs.artifact-retention-days }}
@@ -634,10 +668,13 @@ runs:
         PR_NUMBER: ${{ steps.context.outputs.pr_number }}
         SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.capture.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
         ARTIFACT_NAME: ${{ steps.context.outputs.artifact_name }}
+        ARTIFACT_URL: ${{ steps.upload.outputs.artifact-url }}
         RUN_URL: ${{ steps.context.outputs.run_url }}
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
         MAX_ERROR_ROWS: ${{ inputs.max-error-rows }}
+        BASELINE_RESOLUTION_STATUS: ${{ steps.baseline.outputs.resolution_status }}
+        BASELINE_RESOLUTION_MESSAGE: ${{ steps.baseline.outputs.message }}
       with:
         github-token: ${{ inputs.github-token }}
         script: |
@@ -649,6 +686,8 @@ runs:
           const PR_COMMENT_MARKERS = [PR_COMMENT_MARKER];
           const iconUrl = 'https://raw.githubusercontent.com/ranacseruet/snapdrift/main/assets/snapdrift-logo-icon.png';
           const repoUrl = 'https://github.com/ranacseruet/snapdrift';
+          const prCommentModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
+          const { escapeMarkdown } = await import(pathToFileURL(prCommentModulePath));
 
           const summaryPath = process.env.SUMMARY_PATH;
           const issueNumber = Number(process.env.PR_NUMBER || context.payload.pull_request?.number || context.issue?.number || '');
@@ -659,7 +698,12 @@ runs:
 
           if (!summaryPath || !fs.existsSync(summaryPath)) {
             const runUrl = process.env.RUN_URL || '';
-            const body = `${PR_COMMENT_MARKER}\n<img src="${iconUrl}" alt="SnapDrift" width="20" height="20" />\n\n### ⚠️ SnapDrift Report — Capture Failed\n\nSnapDrift did not produce a summary. This usually means capture failed before the report could be assembled.\n\n[View run](${runUrl}) for details.\n\n<div align="right"><sub>Powered by <a href="${repoUrl}">SnapDrift</a></sub></div>`;
+            const lookupFailure = process.env.BASELINE_RESOLUTION_STATUS === 'error';
+            const heading = lookupFailure ? 'Baseline Lookup Failed' : 'Capture Failed';
+            const detail = escapeMarkdown(lookupFailure
+              ? process.env.BASELINE_RESOLUTION_MESSAGE || 'The GitHub baseline lookup failed before comparison could run.'
+              : 'SnapDrift did not produce a summary. This usually means capture failed before the report could be assembled.');
+            const body = `${PR_COMMENT_MARKER}\n<img src="${iconUrl}" alt="SnapDrift" width="20" height="20" />\n\n### ⚠️ SnapDrift Report — ${heading}\n\n${detail}\n\n[View run](${runUrl}) for details.\n\n<div align="right"><sub>Powered by <a href="${repoUrl}">SnapDrift</a></sub></div>`;
             await github.rest.issues.createComment({
               owner: context.repo.owner,
               repo: context.repo.repo,
@@ -689,6 +733,7 @@ runs:
           const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
           const body = provider.buildCommentBody(summary, {
             artifactName: process.env.ARTIFACT_NAME || '',
+            artifactUrl: process.env.ARTIFACT_URL || '',
             runUrl: process.env.RUN_URL || '',
             maxChangedRows,
             maxErrorRows
@@ -761,6 +806,7 @@ runs:
         SCOPE_REASON: ${{ steps.scope.outputs.reason }}
         SELECTED_ROUTE_IDS: ${{ steps.scope.outputs.selected_route_ids }}
         BASELINE_FOUND: ${{ steps.baseline.outputs.found || 'false' }}
+        BASELINE_RESOLUTION_STATUS: ${{ steps.baseline.outputs.resolution_status || '' }}
         STATUS: ${{ steps.compare.outputs.status || steps.capture.outputs.status || steps.skipped_baseline.outputs.status || steps.skipped_scope.outputs.status || '' }}
         SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.capture.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path || '' }}
         MARKDOWN_PATH: ${{ steps.compare.outputs.markdown_path || steps.capture.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path || '' }}
@@ -771,6 +817,7 @@ runs:
           echo "scope_reason=${SCOPE_REASON:-}"
           echo "selected_route_ids=${SELECTED_ROUTE_IDS:-}"
           echo "baseline_found=${BASELINE_FOUND:-false}"
+          echo "baseline_resolution_status=${BASELINE_RESOLUTION_STATUS:-}"
           echo "status=${STATUS:-}"
           echo "summary_path=${SUMMARY_PATH:-}"
           echo "markdown_path=${MARKDOWN_PATH:-}"

package/actions/resolve-baseline/action.yml

@@ -38,6 +38,9 @@ outputs:
   found:
     description: Whether a non-expired baseline was found.
     value: ${{ steps.resolve.outputs.found }}
+  resolution-status:
+    description: 'Baseline lookup status: found, missing, or error.'
+    value: ${{ steps.resolve.outputs.resolution_status }}
   artifact-name:
     description: Resolved artifact name.
     value: ${{ steps.resolve.outputs.artifact_name }}
@@ -48,7 +51,7 @@ outputs:
     description: Workflow run id that produced the baseline.
     value: ${{ steps.resolve.outputs.run_id }}
   message:
-    description: Informational message when no artifact was found.
+    description: Resolution message for a missing or failed lookup.
     value: ${{ steps.resolve.outputs.message }}
   results-file:
     description: Path to the downloaded baseline results JSON.
@@ -81,61 +84,40 @@ runs:
           const { pathToFileURL } = require('url');
 
           const repository = process.env.INPUT_REPOSITORY || `${context.repo.owner}/${context.repo.repo}`;
-          const [owner, repo] = repository.split('/');
           const modulePath = path.resolve(process.env.GITHUB_WORKSPACE, process.env.GITHUB_ACTION_PATH, '..', '..', 'lib', 'snapdrift-config.mjs');
+          const resolverModulePath = path.resolve(process.env.GITHUB_WORKSPACE, process.env.GITHUB_ACTION_PATH, '..', '..', 'lib', 'resolve-baseline-artifact.mjs');
           const { loadSnapdriftConfig } = await import(pathToFileURL(modulePath));
-          const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-          const artifactName = process.env.INPUT_ARTIFACT_NAME || config.baselineArtifactName;
+          const { resolveBaselineArtifact } = await import(pathToFileURL(resolverModulePath));
+          let artifactName = process.env.INPUT_ARTIFACT_NAME || '';
+
+          const setLookupError = (error) => {
+            const detail = error instanceof Error ? error.message : String(error);
+            const message = `Unable to resolve the SnapDrift baseline artifact: ${detail}`;
+            core.setOutput('found', 'false');
+            core.setOutput('resolution_status', 'error');
+            core.setOutput('artifact_name', artifactName);
+            core.setOutput('message', message);
+            core.setFailed(message);
+          };
 
           try {
-            const runs = await github.paginate(github.rest.actions.listWorkflowRuns, {
-              owner,
-              repo,
-              workflow_id: process.env.INPUT_WORKFLOW_ID || 'ci.yml',
+            const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+            artifactName = process.env.INPUT_ARTIFACT_NAME || config.baselineArtifactName;
+            const result = await resolveBaselineArtifact({
+              github,
+              repository,
+              workflowId: process.env.INPUT_WORKFLOW_ID || 'ci.yml',
               branch: process.env.INPUT_BRANCH || 'main',
-              event: 'push',
-              per_page: 20
+              artifactName
             });
-
-            let selectedRun = null;
-            let selectedArtifact = null;
-
-            for (const run of runs) {
-              if (run.status !== 'completed' || run.conclusion !== 'success') {
-                continue;
-              }
-
-              const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
-                owner,
-                repo,
-                run_id: run.id,
-                per_page: 100
-              });
-
-              const match = artifacts.data.artifacts.find((artifact) => artifact.name === artifactName && !artifact.expired);
-              if (match) {
-                selectedRun = run;
-                selectedArtifact = match;
-                break;
-              }
-            }
-
-            if (!selectedRun || !selectedArtifact) {
-              core.setOutput('found', 'false');
-              core.setOutput('artifact_name', artifactName);
-              core.setOutput('message', `No non-expired SnapDrift baseline artifact named ${artifactName} was found.`);
-              return;
-            }
-
-            core.setOutput('found', 'true');
-            core.setOutput('artifact_name', selectedArtifact.name);
-            core.setOutput('head_sha', selectedRun.head_sha);
-            core.setOutput('run_id', String(selectedRun.id));
-            core.setOutput('message', '');
+            core.setOutput('found', String(result.found));
+            core.setOutput('resolution_status', result.resolutionStatus);
+            core.setOutput('artifact_name', result.artifactName);
+            core.setOutput('head_sha', result.headSha || '');
+            core.setOutput('run_id', result.runId || '');
+            core.setOutput('message', result.message);
           } catch (error) {
-            core.setOutput('found', 'false');
-            core.setOutput('artifact_name', artifactName);
-            core.setOutput('message', `Unable to resolve the SnapDrift baseline artifact: ${error.message}`);
+            setLookupError(error);
           }
 
     - if: steps.resolve.outputs.found == 'true'
@@ -164,6 +146,10 @@ runs:
         {
           echo "results_file=$RESULTS_FILE"
           echo "manifest_file=$MANIFEST_FILE"
-          echo "run_dir=${GITHUB_WORKSPACE}/${DOWNLOAD_PATH}"
+          case "$DOWNLOAD_PATH" in
+            /*) RUN_DIR="$DOWNLOAD_PATH" ;;
+            *) RUN_DIR="${GITHUB_WORKSPACE}/${DOWNLOAD_PATH}" ;;
+          esac
+          echo "run_dir=$RUN_DIR"
           echo "screenshots_dir=$(dirname "$MANIFEST_FILE")/screenshots"
         } >> "$GITHUB_OUTPUT"