snapdrift 0.8.1 → 0.9.0

package/actions/scope/action.yml

@@ -105,9 +105,32 @@ 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]
+                : [])
+            ]))];
             const scope = selectRoutesForChangedFiles(
               config,
-              files.map((file) => file.filename)
+              changedFiles
             );
             setOutputs(scope);
           } catch (error) {

package/bin/snapdrift.mjs

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 // @ts-check
 
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 // Resolve cli.mjs relative to this file so the bin entry works regardless of
-// where the consumer installs the package.
-const cliPath = new URL('../lib/cli.mjs', import.meta.url).pathname;
+// where the consumer installs the package. Use fileURLToPath(new URL(...)) rather
+// than URL.pathname so paths containing spaces or Windows drive letters survive
+// the conversion (URL.pathname percent-encodes them, then pathToFileURL re-encodes
+// the result, producing a path that does not exist).
+const cliPath = fileURLToPath(new URL('../lib/cli.mjs', import.meta.url));
 const { main } = await import(pathToFileURL(cliPath).href);
 
 main(process.argv).catch((error) => {

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:
@@ -210,6 +249,12 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 | `fail-on-incomplete` | Errors, dimension shifts, or missing captures occur |
 | `strict` | Any drift or incomplete comparison appears |
 
+A summary with `status: "skipped"` — or any summary carrying no `diff.mode` —
+never stops the run, whichever mode is configured. A skipped run has no diff
+counters to enforce against, so `shouldFailDriftCheck` returns `false` for it
+before any mode branch is reached. This holds for `actions/enforce` invoked
+directly, not just for the guarded enforcement step inside `actions/pr-diff`.
+
 ## Viewport presets
 
 | Preset | Width | Height | Scale factor | Mobile | Touch |
@@ -316,6 +361,16 @@ Two files are written: `.github/snapdrift.json` and `.github/MIGRATION_NOTES.md`
 
 When `provider: "snap"`, every `capture` / `diff` / `publishBaseline` call goes through `SnapProvider`, which talks to Snap's hosted `/v1/visual/*` API instead of writing to the runner filesystem. The local provider keeps working exactly as before.
 
+### Complete hosted baseline publication
+
+A hosted baseline is an authoritative complete snapshot. For `purpose: "baseline"`, `SnapProvider.capture()` requires the selected route ids to equal the complete configured route set; `route-ids`, `--routes`, and `SNAPDRIFT_ROUTE_IDS` may not reduce it. It requires a resolved branch, 40-character commit SHA, publication workflow ref, and positive publication sequence. GitHub Actions provides these as `GITHUB_REF_NAME`, `GITHUB_SHA`, `GITHUB_WORKFLOW_REF`, and `GITHUB_RUN_NUMBER`; other CI systems may set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`. Local-provider baselines, non-publishing hosted captures, and hosted PR-diff runs retain scoped behavior.
+
+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
 
 If `baseUrl` resolves to a local address (see [`isLocalBaseUrl`](#islocalbaseurl-detection) below), SnapDrift runs Playwright on the runner to render the page and uploads the resulting screenshots to Snap. This is necessary whenever your `baseUrl` is a server only the runner can reach (the common case) — Snap's render worker cannot reach a `127.0.0.1` or `localhost` server.
@@ -328,10 +383,10 @@ SnapDrift uses a small, stable subset of the Snap API:
 
 | Endpoint | Used by |
 |:---------|:--------|
-| `POST /v1/visual/projects/:id/runs` | Create a run; client passes `baseUrl`, `trigger`, optional `baselineId` and `branch` |
+| `POST /v1/visual/projects/:id/runs` | Create a run; client passes `baseUrl`, `trigger`, optional `baselineId` and `branch`, plus the immutable configured/selected route and expected-capture plan; baseline runs also pass the resolved commit as `prHeadSha` |
 | `POST /v1/visual/runs/:run_id/captures` | Submit each route as a capture; client passes `routeId`, `routePath`, `viewportDescriptorJson` |
 | `POST /v1/visual/captures/:capture_id/local-result` | Hybrid path: upload the locally rendered PNG and its dimensions |
-| `POST /v1/visual/projects/:id/baselines` | Publish a baseline from a run's rendered captures (primary path) or upload a pre-built local baseline (migration path) |
+| `POST /v1/visual/projects/:id/baselines` | Publish a complete default-branch baseline from a source run's validated captures |
 | `GET /v1/visual/projects/:id/baselines/latest` | Resolve the latest accepted baseline for diff runs |
 | `GET /v1/visual/runs/:run_id` | Poll a run until it reaches a terminal state (`pass`, `fail`, `error`, or `new`) |
 
@@ -342,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:
 
@@ -352,6 +419,25 @@ The Snap HTTP client classifies responses and applies the following rules:
 - `"warn-and-skip"` — log a warning, throw `SnapSkipError`. The wrapper actions catch this and write a skipped summary, exiting 0.
 - `"fallback-local"` — log a warning, throw `SnapFallbackError`. The wrapper actions catch this and continue the pipeline with `LocalProvider`.
 
+### Outage policy
+
+Snap can go down at any phase of a run, and the configured `onUnavailable`
+behavior has to hold for all of them. `lib/outage-policy.mjs` is the single
+implementation, used by `lib/cli.mjs`, `actions/baseline` and `actions/pr-diff`
+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 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
+carries no diff counters, and `warn-and-skip` means "do not fail my build".
+
+A `fallback-local` capture leaves nothing on Snap: no run is published and no
+baseline is created. The fallback is a local run, not a deferred hosted one.
+
 ### `isLocalBaseUrl` detection
 
 `isLocalBaseUrl(baseUrl)` returns `true` when the URL hostname is:
@@ -369,12 +455,16 @@ 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`) catch `SnapSkipError` and `SnapFallbackError` themselves. Custom orchestrations that call `provider.capture()` or `provider.diff()` directly should do the same.
+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
 
@@ -472,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,14 +46,14 @@ SnapDrift owns route selection, capture, comparison, skipped-report generation,
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift@v0.8.1
+  uses: ranacseruet/snapdrift@v0.9.0
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
     artifact-retention-days: '30'
 ```
 
-If you want only part of the route set, pass `route-ids`. If you don't want to upload the artifact (for example when using the Snap provider, which uploads via its own API), set `upload-artifact: 'false'`.
+For a local-provider baseline, `route-ids` may select part of the route set. A hosted Snap baseline is authoritative and must run in GitHub Actions on the project default branch with every configured route, so a partial `route-ids` value or unresolved CI commit fails before a run is created. Route scoping remains supported in `pr-diff` mode. If you don't want to upload the artifact (for example when using the Snap provider, which uploads via its own API), set `upload-artifact: 'false'`.
 
 ## Step 3: Run the pull request report
 
@@ -71,7 +71,7 @@ Then add SnapDrift after the app is running:
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.8.1
+  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.1` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.8.1` |
-| `ranacseruet/snapdrift@v0.8.1` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.8.1` |
+| `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.1
+        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.1
+        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
 
@@ -230,7 +239,11 @@ By default SnapDrift writes baselines and reports to the runner filesystem (`pro
   - `"warn-and-skip"` — log a warning, write a skipped summary, and exit 0.
   - `"fallback-local"` — log a warning and run the rest of the pipeline with `LocalProvider`.
 
-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.
+Both behaviors apply at every phase of a run — capture, diff, and baseline publish. `fallback-local` switches the whole remainder of the pipeline to local artifacts and the local pixel engine; if Snap had already rendered the current capture server-side, the routes are recaptured on the runner first, so `actions/pr-diff` needs Playwright available (the wrapper installs it whenever `onUnavailable` is `fallback-local`). Nothing is published to Snap on a fallback run. See [Outage policy](contracts.md#outage-policy) for the full matrix.
+
+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, 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.
 
@@ -263,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)
@@ -302,15 +317,19 @@ Use the provided workflow template to refresh the baseline automatically on ever
 
 Drop a copy into your repo at `.github/workflows/snapdrift-refresh-baseline.yml`, then fill in the `TODO` blocks with your app's build and start steps — the same steps you use in your PR workflow. The template uses a `push` trigger on the default branch so published artifacts are discoverable by the baseline resolver in `actions/pr-diff`.
 
-### Label-gated refreshes
-
-If you don't want to republish the baseline on every push, the template includes a commented `if` condition that gates on a label (e.g. `snapdrift:refresh-baseline`). A preceding job can check the most recent merged PR for the label and set an output to control whether the baseline refresh runs.
+Run this job after every successful default-branch build. Hosted publication is the only operation that may intentionally remove a configured route from the canonical baseline, so skipping merges can leave later PRs comparing against stale route configuration.
 
 ## Troubleshooting
 
 **"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.
 
@@ -325,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/local-cli.md

@@ -31,11 +31,11 @@ snapdrift baseline [options]
 ```
 
 - **`provider: "local"`** — identical to `snapdrift capture`: the screenshots written to the baseline directory *are* the baseline.
-- **`provider: "snap"`** — captures each route through Snap, waits for the hosted renders to finish, then publishes a baseline referencing the stored objects. `snapdrift capture` alone does **not** do this: it submits the run and stops, leaving the project with no baseline.
+- **`provider: "snap"`** — canonical baseline publication is CI-only. Run it on the Snap project's default branch; GitHub Actions supplies the publication metadata automatically, while another CI system may set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`. It captures every configured route, waits for the complete hosted run, then publishes a baseline referencing the stored objects. A local checkout without those metadata values fails before creating a hosted run, and partial `--routes` selection is rejected. `snapdrift capture` may still be used locally for non-publishing diagnostics.
 
 `snap.onUnavailable` is honoured across both phases — the capture *and* the publish that follows it. `warn-and-skip` exits 0 without a baseline; `fallback-local` captures locally so you still end up with one.
 
-**Baseline attribution.** The published baseline records the branch and commit it was cut from. Inside GitHub Actions these come from `GITHUB_REF_NAME` / `GITHUB_HEAD_REF` and `GITHUB_SHA`; run locally, they are read from git (`rev-parse --abbrev-ref HEAD` and `rev-parse HEAD`). Outside a git repository they fall back to `main` and `unknown`, so run the command from your checkout if you want the baseline attributed correctly.
+**Baseline attribution.** A hosted publication records a 40-character commit and branch from GitHub Actions or the current git checkout, plus a publication workflow identity and sequence. Outside GitHub Actions, set `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`; without them SnapDrift refuses to create a canonical hosted baseline.
 
 **`snap.projectId` must be an explicit `prj_...` id** for local runs. `"auto"` derives the id from `GITHUB_REPOSITORY`, which is not set outside Actions — the command fails early telling you to set an explicit id.
 
@@ -44,13 +44,14 @@ snapdrift baseline [options]
 | Flag | Default | Description |
 |:-----|:--------|:------------|
 | `--config <path>` | `.github/snapdrift.json` | Path to the config file |
-| `--routes <ids>` | all routes | Comma-separated route IDs to capture |
+| `--routes <ids>` | all routes | Comma-separated route IDs for a local-provider baseline; hosted baselines require all configured routes |
 | `--baseline-dir <path>` | `.snapdrift/baseline` | Directory to write baseline screenshots and metadata (local provider) |
 
 **Example**
 
 ```bash
 snapdrift baseline
+# Scoped baseline capture remains available with provider: "local"
 snapdrift baseline --routes home-desktop,home-mobile
 ```
 
@@ -296,7 +297,7 @@ The `report.html` path is printed whenever the status is anything other than `cl
 |:---------|:-----------|:------------|
 | `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture`, `diff` | Max concurrent route captures per viewport context (positive integer, default `5`). Set to `1` to restore serial behavior for apps with shared session or auth state. |
 | `SNAPDRIFT_CONFIG_PATH` | `capture`, `diff`, `migrate-baselines` | Override the config file path. Equivalent to `--config`. |
-| `SNAPDRIFT_ROUTE_IDS` | `capture`, `diff` | Comma-separated route ids to scope to. Equivalent to `--routes`. |
+| `SNAPDRIFT_ROUTE_IDS` | `capture`, `baseline`, `diff` | Comma-separated route ids to scope to. Equivalent to `--routes`; it may not reduce a hosted baseline's complete route set. |
 
 `SNAPDRIFT_CAPTURE_CONCURRENCY` is the same env var consumed by the GitHub Actions wrapper; tweak it the same way for both environments.
 
@@ -304,7 +305,7 @@ The `report.html` path is printed whenever the status is anything other than `cl
 
 ## Tips
 
-- **Partial runs**: use `--routes` to capture or compare only the routes you are actively changing.
+- **Partial runs**: use `--routes` to capture or compare only the routes you are actively changing. A hosted baseline is the exception: its GitHub Actions run always requires the complete configured route set.
 - **Multiple baselines**: use `--baseline-dir` to maintain separate baselines per branch or feature.
 - **CI parity**: the CLI uses the same capture and comparison engine as the GitHub Actions workflow, so results are comparable.
 - **Self-contained HTML report**: `report.html` embeds baseline, current, and diff images as base64. Open it from any machine — no server required, and no relative-path resolution surprises. (The HTML report is a local-CLI feature; the GitHub Actions wrapper ships only `summary.json` + `summary.md` in its artifact bundle.)

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

@@ -17,12 +17,6 @@
 # resolver in actions/pr-diff (which filters on event: 'push'). A merge into
 # the default branch produces a push event, so this fires exactly when needed.
 #
-# Optional — refresh only on a specific label:
-#   If you don't want to refresh on every push, you can gate on a label applied
-#   before merging. Use the pull_request: labeled event in a separate workflow to
-#   set an output, or simply restrict this workflow to specific paths.
-#   See the commented block below for a label-based gate using a preceding job.
-
 name: SnapDrift Refresh Baseline
 
 on:
@@ -35,12 +29,12 @@ permissions:
 
 jobs:
   refresh-baseline:
-    # Optional: gate on a label to avoid refreshing on every push.
-    # Requires a preceding job that checks for the label on the most recent
-    # merged PR and sets an output. Replace "snapdrift:refresh-baseline" with
-    # your label name.
-    # if: needs.check-label.outputs.refresh == 'true'
-
+    # Preserve the in-flight publisher and queue the next merge behind it. This
+    # keeps older SnapDrift clients safe during a rolling release; SnapDrift's
+    # workflow-scoped sequence is an additional stale-source guard.
+    concurrency:
+      group: snapdrift-baseline-${{ github.repository }}-${{ github.ref }}
+      cancel-in-progress: false
     runs-on: ubuntu-latest
 
     steps:
@@ -69,8 +63,26 @@ jobs:
       #     done
       # ────────────────────────────────────────────────────────────────────────
 
+      - name: Verify current default-branch candidate
+        id: baseline_candidate
+        shell: bash
+        run: |
+          set -euo pipefail
+          latest_sha="$(git ls-remote origin "refs/heads/${GITHUB_REF_NAME}" | cut -f1)"
+          if [ -z "$latest_sha" ]; then
+            echo "::error::Could not resolve the current default-branch commit."
+            exit 1
+          fi
+          if [ "$GITHUB_SHA" = "$latest_sha" ]; then
+            echo "current=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "current=false" >> "$GITHUB_OUTPUT"
+            echo "Skipping stale baseline candidate $GITHUB_SHA; current branch head is $latest_sha."
+          fi
+
       - name: Publish SnapDrift baseline
-        uses: ranacseruet/snapdrift@v0.8.1
+        if: steps.baseline_candidate.outputs.current == 'true'
+        uses: ranacseruet/snapdrift@v0.9.0
         with:
           mode: baseline
           repo-config-path: .github/snapdrift.json