snapdrift 0.8.2 → 0.9.0

package/docs/contracts.md

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

package/docs/integration-guide.md

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

package/docs/workflow-templates/refresh-baseline-on-merge.yml

@@ -82,7 +82,7 @@ jobs:
 
       - name: Publish SnapDrift baseline
         if: steps.baseline_candidate.outputs.current == 'true'
-        uses: ranacseruet/snapdrift@v0.8.2
+        uses: ranacseruet/snapdrift@v0.9.0
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json

package/lib/cli.mjs

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { execSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
@@ -49,6 +49,11 @@ export const LOCAL_DIFF_SUBDIR = 'diff';
  *   --accept-cross-engine  Allow importing baselines from a different capture engine
  *   --from-snap-action <path>  Snap action workflow YAML path (init command)
  *
+ * Values may be given inline as `--flag=value` (so values beginning with a hyphen,
+ * e.g. `--routes=-mobile`, work) or after the `--` end-of-options marker. Unknown
+ * flags and missing option values are rejected with a non-zero error; invalid
+ * *values* for --to/--from remain silently ignored (validated downstream).
+ *
  * @param {string[]} argv - process.argv
  * @returns {CliOptions}
  */
@@ -71,41 +76,105 @@ export function parseArgs(argv) {
   /** @type {string | undefined} */
   let fromSnapAction;
 
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '--open') {
-      open = true;
-    } else if (arg === '--config' && i + 1 < args.length) {
-      configPath = args[++i];
-    } else if (arg === '--routes' && i + 1 < args.length) {
-      routes.push(
-        ...args[++i]
-          .split(',')
-          .map((r) => r.trim())
-          .filter(Boolean)
-      );
-    } else if (arg === '--baseline-dir' && i + 1 < args.length) {
-      baselineDir = path.resolve(args[++i]);
-    } else if (arg === '--current-dir' && i + 1 < args.length) {
-      currentDir = path.resolve(args[++i]);
-    } else if (arg === '--diff-dir' && i + 1 < args.length) {
-      diffDir = path.resolve(args[++i]);
-    } else if (arg === '--to' && i + 1 < args.length) {
-      const toVal = args[++i];
-      if (toVal === 'snap' || toVal === 'local') {
-        to = toVal;
-      }
-    } else if (arg === '--from' && i + 1 < args.length) {
-      const fromVal = args[++i];
-      if (fromVal === 'snap') {
-        from = fromVal;
-      }
-    } else if (arg === '--accept-cross-engine') {
-      acceptCrossEngine = true;
-    } else if (arg === '--from-snap-action' && i + 1 < args.length) {
-      fromSnapAction = args[++i];
-    }
-  }
+   // Flags that consume the following token as their value. Unknown flags and
+   // missing option values are rejected rather than silently ignored, so a typo
+   // cannot fall back to the default config/directories. Invalid *values* for
+   // --to/--from stay silently ignored to preserve the migrate-baselines contract
+   // (their validation happens downstream). Values that begin with a hyphen (e.g.
+   // a route id like `-mobile`) may be supplied inline as `--flag=value` or bare.
+   const VALUE_FLAGS = new Set([
+     '--config',
+     '--routes',
+     '--baseline-dir',
+     '--current-dir',
+     '--diff-dir',
+     '--to',
+     '--from',
+     '--from-snap-action'
+   ]);
+   const BOOLEAN_FLAGS = new Set(['--open', '--accept-cross-engine']);
+
+   /**
+    * Assign a parsed value (from an inline `--flag=value` or a following token)
+    * to the option named by `flag`.
+    *
+    * @param {string} flag
+    * @param {string} value
+    */
+   function assignFlag(flag, value) {
+     if (flag === '--routes') {
+       routes.push(...value.split(',').map((r) => r.trim()).filter(Boolean));
+     } else if (flag === '--config') {
+       configPath = value;
+     } else if (flag === '--baseline-dir') {
+       baselineDir = path.resolve(value);
+     } else if (flag === '--current-dir') {
+       currentDir = path.resolve(value);
+     } else if (flag === '--diff-dir') {
+       diffDir = path.resolve(value);
+     } else if (flag === '--to') {
+       if (value === 'snap' || value === 'local') to = value;
+     } else if (flag === '--from') {
+       if (value === 'snap') from = value;
+     } else if (flag === '--from-snap-action') {
+       fromSnapAction = value;
+     }
+   }
+
+   let endOfOptions = false;
+
+   for (let i = 1; i < args.length; i++) {
+     const raw = args[i];
+
+     if (raw === '--') {
+       endOfOptions = true;
+       continue;
+     }
+
+     // End-of-options: after `--`, tokens are values/positionals, never flags.
+     if (endOfOptions) {
+       if (VALUE_FLAGS.has(raw)) {
+         const value = args[i + 1];
+         if (value === undefined) {
+           throw new Error(`Missing value for flag ${raw}`);
+         }
+         assignFlag(raw, value);
+         i++; // consume the following token so it is not reprocessed as a flag
+       }
+       continue;
+     }
+
+     // Inline `--flag=value` form (also handles values that begin with a hyphen).
+     const eq = raw.indexOf('=');
+     if (raw.startsWith('--') && eq > 0) {
+       const flag = raw.slice(0, eq);
+       if (!VALUE_FLAGS.has(flag)) {
+         throw new Error(`Unknown flag: ${flag}`);
+       }
+       assignFlag(flag, raw.slice(eq + 1));
+       continue;
+     }
+
+     if (BOOLEAN_FLAGS.has(raw)) {
+       if (raw === '--open') {
+         open = true;
+       } else if (raw === '--accept-cross-engine') {
+         acceptCrossEngine = true;
+       }
+     } else if (VALUE_FLAGS.has(raw)) {
+       const value = args[i + 1];
+       // A hyphenated following token (e.g. a route id like `-mobile`) is a
+       // legitimate value; only a missing token, the `--` end-of-options marker,
+       // or a following *recognized flag* means the value is absent.
+       if (value === undefined || value === '--' || VALUE_FLAGS.has(value) || BOOLEAN_FLAGS.has(value)) {
+         throw new Error(`Missing value for flag ${raw}`);
+       }
+       assignFlag(raw, value);
+       i++; // consume the following token so it is not reprocessed as a flag
+     } else if (raw.startsWith('-')) {
+       throw new Error(`Unknown flag: ${raw}`);
+     }
+   }
 
   return { command, open, configPath, routes, baselineDir, currentDir, diffDir, to, from, acceptCrossEngine, fromSnapAction };
 }
@@ -163,15 +232,30 @@ export function printSummary(summary) {
  * @returns {void}
  */
 function openFile(filePath) {
-  const cmd =
-    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-  try {
-    execSync(`${cmd} "${filePath}"`);
-  } catch {
+  const { cmd, args } = buildOpenCommand(filePath);
+  const result = spawnSync(cmd, args);
+  if (result.error) {
     process.stderr.write(`Could not open file: ${filePath}\n`);
   }
 }
 
+/**
+ * Build the platform-correct invocation to open a file with the OS default
+ * viewer. The path is passed as a separate argument (never shell-interpolated)
+ * so metacharacters in a local path cannot execute commands. On Windows, `start`
+ * is a cmd.exe built-in rather than an executable, so spawnSync (which does not
+ * use a shell by default) returns ENOENT; open the registered handler through
+ * rundll32, a real executable, keeping the path as a separate argument.
+ *
+ * @param {string} filePath
+ * @returns {{ cmd: string, args: string[] }}
+ */
+export function buildOpenCommand(filePath, platform = process.platform) {
+  if (platform === 'darwin') return { cmd: 'open', args: [filePath] };
+  if (platform === 'linux') return { cmd: 'xdg-open', args: [filePath] };
+  return { cmd: 'rundll32', args: ['url.dll,FileProtocolHandler', filePath] };
+}
+
 /**
  * Run the `capture` command — capture screenshots to a local baseline directory.
  *

package/lib/init-from-action.mjs

@@ -87,19 +87,30 @@ function translateStepToConfig(step) {
     });
   }
 
-  // Snap provider config (if present in inputs)
-  /** @type {JsonObject | undefined} */
-  let snap;
-  const snapApiUrl = inputs['snap-api-url'] || inputs.snap_api_url;
-  const snapApiKeyEnv = inputs['snap-api-key-env'] || inputs.snap_api_key_env;
-  const snapProjectId = inputs['snap-project-id'] || inputs.snap_project_id;
-
-  if (snapApiKeyEnv || snapProjectId) {
-    snap = {};
-    if (snapApiUrl) snap.apiUrl = snapApiUrl;
-    if (snapApiKeyEnv) snap.apiKeyEnv = snapApiKeyEnv;
-    if (snapProjectId) snap.projectId = snapProjectId;
-  }
+   // Snap provider config (if present in inputs). A hosted Snap provider requires
+   // an API-key source; only enable provider: "snap" when one is present. When a
+   // project ID exists without an API-key source, keep a valid (local) config and
+   // emit a clear migration warning rather than emitting provider: "snap" with no
+   // API-key source, which later fails validation.
+   /** @type {JsonObject | undefined} */
+   let snap;
+   const snapApiUrl = inputs['snap-api-url'] || inputs.snap_api_url;
+   const snapApiKeyEnv = inputs['snap-api-key-env'] || inputs.snap_api_key_env;
+   const snapProjectId = inputs['snap-project-id'] || inputs.snap_project_id;
+
+   if (snapApiKeyEnv) {
+     snap = {};
+     if (snapApiUrl) snap.apiUrl = snapApiUrl;
+     snap.apiKeyEnv = snapApiKeyEnv;
+     if (snapProjectId) snap.projectId = snapProjectId;
+   } else if (snapProjectId) {
+     warnings.push({
+       field: 'snap.projectId',
+       originalValue: snapProjectId,
+       message: `Snap project ID "${snapProjectId}" is present but no API-key source (snap-api-key-env) was configured. SnapDrift keeps the local provider; add a Snap API key source to enable hosted baselines.`,
+       severity: 'warning'
+     });
+   }
 
   const config = {
     baselineArtifactName: 'snapdrift-baseline',

package/lib/outage-policy.mjs

@@ -41,6 +41,25 @@ export const MISSING_BASELINE_REASON = 'missing_main_baseline_artifact';
 /** @returns {void} */
 function noop() {}
 
+/**
+ * @param {unknown} outageError
+ * @param {'capture' | 'diff'} phase
+ * @param {string | undefined} lookupMessage
+ * @returns {Error}
+ */
+function createBaselineLookupFallbackError(outageError, phase, lookupMessage) {
+  const lookupDetail = typeof lookupMessage === 'string' && lookupMessage.trim().length > 0
+    ? ` ${lookupMessage.trim()}`
+    : '';
+  const outageDetail = outageError instanceof Error && outageError.message
+    ? ` Snap fallback reason: ${outageError.message}`
+    : '';
+  return new Error(
+    `Cannot fall back to a local ${phase} because the GitHub baseline lookup failed.${lookupDetail}${outageDetail}`,
+    { cause: outageError }
+  );
+}
+
 /**
  * Whether the current capture leaves real PNGs on the runner's filesystem.
  *
@@ -70,7 +89,9 @@ export function hasLocalScreenshots(providerName, config) {
  *   config?: VisualRegressionConfig,
  *   createLocalProvider?: () => VisualProvider,
  *   onSkip?: (error: SnapSkipError) => void,
- *   onFallback?: (error: SnapFallbackError) => void
+ *   onFallback?: (error: SnapFallbackError) => void,
+ *   baselineResolutionStatus?: string,
+ *   baselineResolutionMessage?: string
  * }} options
  * @returns {Promise<{
  *   outcome: 'captured' | 'skipped',
@@ -100,6 +121,9 @@ export async function captureWithPolicy(options) {
     }
     if (error instanceof SnapFallbackError) {
       onFallback(error);
+      if (options.baselineResolutionStatus === 'error') {
+        throw createBaselineLookupFallbackError(error, 'capture', options.baselineResolutionMessage);
+      }
       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.
@@ -134,7 +158,9 @@ export async function captureWithPolicy(options) {
  *   onSkip?: (error: SnapSkipError) => void,
  *   onFallback?: (error: SnapFallbackError) => void,
  *   onRecapture?: () => void,
- *   onBaselineUnavailable?: () => void
+ *   onBaselineUnavailable?: () => void,
+ *   baselineResolutionStatus?: string,
+ *   baselineResolutionMessage?: string
  * }} options
  * @returns {Promise<{
  *   outcome: 'diffed' | 'skipped' | 'baseline-unavailable',
@@ -170,9 +196,16 @@ export async function diffWithPolicy(options) {
       : Boolean(options.diffOptions.baselineResultsPath);
     if (!baselineAvailable) {
       onBaselineUnavailable();
+      if (options.baselineResolutionStatus === 'error') {
+        throw createBaselineLookupFallbackError(error, 'diff', options.baselineResolutionMessage);
+      }
       return { outcome: 'baseline-unavailable', providerName: 'local' };
     }
 
+    if (options.baselineResolutionStatus === 'error') {
+      throw createBaselineLookupFallbackError(error, 'diff', options.baselineResolutionMessage);
+    }
+
     const localProvider = createLocalProvider();
     let diffOptions = options.diffOptions;
     /** @type {CaptureResult | undefined} */