snapdrift 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.8.0 - 2026-08-06
+
+### Features
+
+- **Root `action.yml` for the GitHub Marketplace** — SnapDrift's nine composite actions all live under `actions/*`, and Marketplace lists exactly one action per repository whose metadata file must sit at the repository root, so none of them were publishable. `ranacseruet/snapdrift@vX` is now a dispatcher action that runs the baseline pipeline with `mode: baseline` and the pull request pipeline with `mode: pr-diff`, forwarding every input and output of the corresponding wrapper. Existing `ranacseruet/snapdrift/actions/*@vX` references are unaffected and stay supported. The dispatcher pins absolute inner refs rather than `uses: ./actions/...`, because a relative `uses:` inside a composite action resolves against the caller's workspace; `tests/marketplace-metadata.test.js` fails the build if those pins drift from the package version. Released versions pin the inner ref to a commit SHA so that a consumer pinning the dispatcher to a SHA gets an immutable chain rather than a mutable tag one level down.
+- **`branding` on every action** — required for the Marketplace listing, and applied to all nine sub-actions so the metadata stays consistent if any of them is ever split into its own repository. `npm run validate:actions` now rejects a missing icon or a color outside GitHub's allowed set, and covers the root action.
+
+### Documentation
+
+- Updated the README, Integration Guide, and baseline workflow template action examples to use the current release.
+- Documented the root action as the primary entry point across the README quickstart, the Integration Guide, and the baseline workflow template, with a new "Choosing an entry point" section mapping each `mode` to its equivalent wrapper action. The documentation version contract test now covers root-action references and prose references, not just `uses:` lines for the two wrappers.
+
+## 0.7.0 - 2026-07-26
+
+### Features
+
+- **`snapdrift baseline` command** — establishes a baseline for the configured provider. With `provider: "snap"` it captures each route through Snap, waits for the hosted renders, and then publishes a baseline from the stored object keys. Previously `publishBaseline()` was reachable only from `actions/baseline`, so anyone not running GitHub Actions had **no supported way to seed a hosted project** — `snapdrift capture` submits a run but never creates a baseline from it. With `provider: "local"` the command behaves like `capture`, since the captured files are themselves the baseline. Honours `onUnavailable: fallback-local` by skipping the publish step when the capture falls back locally. (ranacseruet/snapdrift#106)
+
+### Fixes
+
+- **`publishBaseline()` fails with the real cause instead of a doomed request** — when `results.json` was missing, unparseable, or carried no `runId`, it fell through to a legacy branch that POSTed `manifest`/`results` as objects. Snap has never read those fields, so that request could only fail — with an opaque 500 before, and `400 unsupported_baseline_body` since i2Dev-com/snap#653 — while a bare `catch {}` hid the underlying read error. The legacy branch is removed; the method now reports that no run id was found, including the read error when there was one. Reached whenever a non-Snap `results.json` (for example one written by the local provider) was passed in. (#109)
+- **`snapdrift capture` honours `onUnavailable: "warn-and-skip"`** — the mode makes `#handleUnavailable` throw `SnapSkipError`, which `diff` and `baseline` catch and turn into a clean exit. `capture` let it propagate to the CLI entry point, which writes the error to stderr and exits 1 — failing the build the user explicitly configured *not* to fail when Snap is unavailable. (#108)
+- **Baselines published outside GitHub Actions are attributed correctly** — `publishBaseline()` read the branch and commit only from `GITHUB_REF_NAME` / `GITHUB_HEAD_REF` / `GITHUB_SHA`, so a baseline published from a terminal was recorded as branch `main` at SHA `unknown`, making baselines cut from different commits indistinguishable in the dashboard and in exported metadata. It now falls back to `git rev-parse` when those variables are absent (and to `main` / `unknown` only outside a git repository). Previously unreachable, since there was no CLI publish path.
+
+### Breaking changes
+
+- **`migrate-baselines --to snap` now fails with a pointer to `snapdrift baseline`**, and `SnapProvider.migrateBaselineFromLocal()` has been removed. The body it posted (`manifest`/`results`/`screenshots` as objects) was never read by Snap's baseline endpoint: the PNGs were never uploaded to storage and the manifest referenced local filenames rather than Snap object keys, so the call could only ever create a baseline with no images behind it — one that `migrate-baselines --to local --from snap` would then refuse to export. The request previously failed with an opaque 500 and is now rejected with `400 unsupported_baseline_body` (i2Dev-com/snap#653). The reverse direction, `--to local --from snap`, is unaffected.
+
 ## 0.6.0 - 2026-07-17
 
 ### Features

package/README.md

@@ -3,6 +3,7 @@
 ![SnapDrift](assets/snapdrift-logo-banner.png)
 
 ![CI](https://github.com/ranacseruet/snapdrift/actions/workflows/ci.yml/badge.svg)
+[![GitHub Marketplace](https://img.shields.io/badge/marketplace-SnapDrift-purple?logo=github)](https://github.com/marketplace/actions/snapdrift)
 ![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)
 ![License: MIT](https://img.shields.io/badge/license-MIT-blue)
 
@@ -47,8 +48,9 @@ You keep ownership of checkout, build, startup, readiness, and teardown. SnapDri
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift/actions/baseline@v0.4.0
+  uses: ranacseruet/snapdrift@v0.8.0
   with:
+    mode: baseline
     repo-config-path: .github/snapdrift.json
 ```
 
@@ -56,27 +58,33 @@ You keep ownership of checkout, build, startup, readiness, and teardown. SnapDri
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift/actions/pr-diff@v0.4.0
+  uses: ranacseruet/snapdrift@v0.8.0
   with:
+    mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
     repo-config-path: .github/snapdrift.json
 ```
 
 That is the full integration. See the [Integration Guide](docs/integration-guide.md) for workflow examples, permissions, compatibility notes, advanced overrides, and the hosted Snap backend (`provider: "snap"`).
 
+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.
+
 ## Local CLI
 
 SnapDrift ships a `snapdrift` CLI for running captures, diffs, migrations, and config initialization locally against a running app — no GitHub Actions required. Use it during development to validate UI changes before pushing.
 
 ```bash
-# Capture a baseline
+# Establish a baseline — for provider "snap" this also publishes it
+snapdrift baseline
+
+# Capture screenshots without publishing anything
 snapdrift capture
 
-# Compare against it after making UI changes
+# Compare against the baseline after making UI changes
 snapdrift diff --open
 
-# Migrate local baselines to the hosted Snap backend
-snapdrift migrate-baselines --to snap
+# Export hosted baselines back to the local layout
+snapdrift migrate-baselines --to local --from snap
 
 # Translate an existing Snap github-action workflow into snapdrift.json
 snapdrift init --from-snap-action .github/workflows/snap.yml
@@ -104,6 +112,12 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 - Dimension shifts are reported separately from pixel drift
 - 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))
 
+## Outgrew GitHub artifacts?
+
+Baselines live as GitHub Actions artifacts by default — quick to start, but they expire (30 days by default), are scoped to one repo, and every PR re-renders on your CI runner. When visual regression becomes load-bearing, `provider: "snap"` moves baselines into durable, shared storage with a review dashboard — and, when `baseUrl` points at a public preview URL Snap can reach, renders on Snap's hosted fleet instead of your runner (with a localhost `baseUrl`, capture stays a local-Playwright-and-upload hybrid). Same routes, same diff config; add a `snap` config block and API key per the [hosted-provider setup](docs/integration-guide.md#hosted-snap-provider). Snap's hosted Visual CI is built for small teams (plans from $9.99/mo).
+
+→ **[Hosted Visual CI with Snap](https://snap.i2dev.com/ci)**
+
 ## Docs
 
 - [Integration Guide](docs/integration-guide.md)

package/action.yml

@@ -0,0 +1,173 @@
+name: SnapDrift
+description: Capture, compare, and report UI drift for Playwright-based apps — baseline publishing and pull request visual diffs in one action.
+author: CodeSamplez
+
+branding:
+  icon: eye
+  color: purple
+
+# GitHub Marketplace lists exactly one action per repository, and its metadata file must live at
+# the repository root. This dispatcher is that entry point: it forwards to the wrapper actions
+# under `actions/`, which remain directly usable (and unchanged) for custom orchestration.
+#
+# The inner `uses:` refs are pinned to the current release rather than a relative path because
+# `uses: ./path` inside a composite action resolves against the *caller's* workspace, not the
+# action's own directory. `tests/marketplace-metadata.test.js` fails the build if those pins drift
+# from the root `package.json` version.
+#
+# The pins are commit SHAs carrying the version in a trailing comment, so that a consumer pinning
+# this action to a SHA gets an immutable chain rather than a mutable tag one level down. The SHA is
+# the commit that introduced the release's wrapper actions; the release commit cannot reference its
+# own SHA. The test accepts a plain `@vX.Y.Z` tag too, for unreleased refs.
+
+inputs:
+  mode:
+    description: Which SnapDrift pipeline to run — `pr-diff` for pull request drift detection, or `baseline` to publish a baseline.
+    required: false
+    default: pr-diff
+  repo-config-path:
+    description: Path to the SnapDrift config file.
+    required: false
+    default: .github/snapdrift.json
+  route-ids:
+    description: Optional comma-separated route ids. In `pr-diff` mode, providing these skips changed-file scope detection.
+    required: false
+    default: ''
+  artifact-retention-days:
+    description: Retention period for the uploaded artifact.
+    required: false
+    default: '30'
+  github-token:
+    description: Token used to inspect pull request files, fetch baselines, and publish SnapDrift PR reports. Used in `pr-diff` mode only.
+    required: false
+    default: ${{ github.token }}
+
+  # `baseline` mode only.
+  upload-artifact:
+    description: Whether to upload the staged baseline artifact. Used in `baseline` mode only.
+    required: false
+    default: 'true'
+
+  # `pr-diff` mode only.
+  pr-number:
+    description: Optional pull request number override.
+    required: false
+    default: ''
+  force-run:
+    description: Whether to force a full run when route ids are not explicitly provided.
+    required: false
+    default: 'false'
+  force-run-reason:
+    description: Reason to report when force-run is enabled.
+    required: false
+    default: forced
+  baseline-repository:
+    description: Repository in owner/name format that publishes the baseline.
+    required: false
+    default: ''
+  baseline-workflow-id:
+    description: Workflow id or filename to search for the baseline.
+    required: false
+    default: ci.yml
+  baseline-branch:
+    description: Branch that publishes the baseline.
+    required: false
+    default: main
+  comment-on-pr:
+    description: Whether to publish the SnapDrift PR report.
+    required: false
+    default: 'true'
+  max-changed-rows:
+    description: Maximum number of changed-route rows shown in the PR comment before truncation.
+    required: false
+    default: '20'
+  max-error-rows:
+    description: Maximum number of error rows shown in the PR comment before truncation.
+    required: false
+    default: '10'
+
+outputs:
+  # Shared across both modes.
+  artifact-name:
+    description: Name of the uploaded artifact.
+    value: ${{ steps.baseline.outputs.artifact-name || steps.pr-diff.outputs.artifact-name }}
+  bundle-dir:
+    description: Staged artifact bundle directory.
+    value: ${{ steps.baseline.outputs.bundle-dir || steps.pr-diff.outputs.bundle-dir }}
+  selected-route-ids:
+    description: Comma-separated route ids selected for the run.
+    value: ${{ steps.baseline.outputs.selected-route-ids || steps.pr-diff.outputs.selected-route-ids }}
+
+  # `baseline` mode only.
+  results-file:
+    description: Absolute path to the generated baseline results file.
+    value: ${{ steps.baseline.outputs.results-file }}
+  manifest-file:
+    description: Absolute path to the generated baseline manifest file.
+    value: ${{ steps.baseline.outputs.manifest-file }}
+  screenshots-root:
+    description: Absolute path to the generated screenshots root.
+    value: ${{ steps.baseline.outputs.screenshots-root }}
+
+  # `pr-diff` mode only.
+  should-run:
+    description: Whether the SnapDrift flow ran or intentionally skipped due to scope.
+    value: ${{ steps.pr-diff.outputs.should-run }}
+  scope-reason:
+    description: Reason for the final scope decision.
+    value: ${{ steps.pr-diff.outputs.scope-reason }}
+  baseline-found:
+    description: Whether a usable baseline was found.
+    value: ${{ steps.pr-diff.outputs.baseline-found }}
+  status:
+    description: Final SnapDrift status.
+    value: ${{ steps.pr-diff.outputs.status }}
+  summary-path:
+    description: Path to the final summary JSON file.
+    value: ${{ steps.pr-diff.outputs.summary-path }}
+  markdown-path:
+    description: Path to the final summary markdown file.
+    value: ${{ steps.pr-diff.outputs.markdown-path }}
+
+runs:
+  using: composite
+  steps:
+    - name: Validate mode
+      shell: bash
+      env:
+        MODE: ${{ inputs.mode }}
+      run: |
+        set -euo pipefail
+        if [ "$MODE" != "pr-diff" ] && [ "$MODE" != "baseline" ]; then
+          echo "::error::Unsupported SnapDrift mode '$MODE'. Expected 'pr-diff' or 'baseline'."
+          exit 1
+        fi
+
+    - name: SnapDrift baseline
+      id: baseline
+      if: inputs.mode == 'baseline'
+      uses: ranacseruet/snapdrift/actions/baseline@539953ab07065be805be393d69bd3c9b6d53cf6e # v0.8.0
+      with:
+        repo-config-path: ${{ inputs.repo-config-path }}
+        route-ids: ${{ inputs.route-ids }}
+        artifact-retention-days: ${{ inputs.artifact-retention-days }}
+        upload-artifact: ${{ inputs.upload-artifact }}
+
+    - name: SnapDrift pull request diff
+      id: pr-diff
+      if: inputs.mode == 'pr-diff'
+      uses: ranacseruet/snapdrift/actions/pr-diff@539953ab07065be805be393d69bd3c9b6d53cf6e # v0.8.0
+      with:
+        github-token: ${{ inputs.github-token }}
+        repo-config-path: ${{ inputs.repo-config-path }}
+        pr-number: ${{ inputs.pr-number }}
+        route-ids: ${{ inputs.route-ids }}
+        force-run: ${{ inputs.force-run }}
+        force-run-reason: ${{ inputs.force-run-reason }}
+        baseline-repository: ${{ inputs.baseline-repository }}
+        baseline-workflow-id: ${{ inputs.baseline-workflow-id }}
+        baseline-branch: ${{ inputs.baseline-branch }}
+        artifact-retention-days: ${{ inputs.artifact-retention-days }}
+        comment-on-pr: ${{ inputs.comment-on-pr }}
+        max-changed-rows: ${{ inputs.max-changed-rows }}
+        max-error-rows: ${{ inputs.max-error-rows }}

package/actions/baseline/action.yml

@@ -1,6 +1,10 @@
 name: SnapDrift Baseline
 description: Capture configured routes, stage a SnapDrift baseline, and upload it with the configured artifact name.
 
+branding:
+  icon: camera
+  color: purple
+
 inputs:
   repo-config-path:
     description: Path to the SnapDrift config file.

package/actions/capture/action.yml

@@ -1,6 +1,10 @@
 name: SnapDrift Capture
 description: Capture configured SnapDrift routes and emit the standard results and manifest files.
 
+branding:
+  icon: camera
+  color: purple
+
 inputs:
   repo-config-path:
     description: Path to the SnapDrift config file.

package/actions/comment/action.yml

@@ -1,6 +1,10 @@
 name: SnapDrift Comment
 description: Upsert a PR comment with the SnapDrift report.
 
+branding:
+  icon: message-square
+  color: purple
+
 inputs:
   github-token:
     description: Token used to update the pull request comment.

package/actions/compare/action.yml

@@ -1,6 +1,10 @@
 name: SnapDrift Compare
 description: Compare the current capture against a baseline and emit the SnapDrift report files.
 
+branding:
+  icon: layers
+  color: purple
+
 inputs:
   repo-config-path:
     description: Path to the SnapDrift config file.

package/actions/enforce/action.yml

@@ -1,6 +1,10 @@
 name: SnapDrift Enforce
 description: Evaluate the SnapDrift summary against diff.mode and fail when required.
 
+branding:
+  icon: shield
+  color: purple
+
 inputs:
   summary-path:
     description: Path to the SnapDrift summary JSON.

package/actions/pr-diff/action.yml

@@ -1,6 +1,10 @@
 name: SnapDrift PR Diff
 description: Run the end-to-end SnapDrift pull request pipeline, including scope resolution, skipped-report handling, artifact upload, PR reporting, and enforcement.
 
+branding:
+  icon: eye
+  color: purple
+
 inputs:
   github-token:
     description: Token used to inspect pull request files, fetch baselines, and publish SnapDrift PR reports.

package/actions/resolve-baseline/action.yml

@@ -1,6 +1,10 @@
 name: SnapDrift Resolve Baseline
 description: Resolve and download the latest successful SnapDrift baseline from main.
 
+branding:
+  icon: download-cloud
+  color: purple
+
 inputs:
   github-token:
     description: Token used to query workflow runs and download artifacts.

package/actions/scope/action.yml

@@ -1,6 +1,10 @@
 name: SnapDrift Scope
 description: Determine whether SnapDrift should run and which configured routes should be selected for the current change set.
 
+branding:
+  icon: filter
+  color: purple
+
 inputs:
   github-token:
     description: Token used to query pull request changed files.

package/actions/stage/action.yml

@@ -1,6 +1,10 @@
 name: SnapDrift Stage
 description: Stage baseline or drift artifacts into the SnapDrift bundle structure before upload.
 
+branding:
+  icon: package
+  color: purple
+
 inputs:
   artifact-type:
     description: Either baseline or diff.

package/docs/integration-guide.md

@@ -46,8 +46,9 @@ SnapDrift owns route selection, capture, comparison, skipped-report generation,
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift/actions/baseline@v0.4.0
+  uses: ranacseruet/snapdrift@v0.8.0
   with:
+    mode: baseline
     repo-config-path: .github/snapdrift.json
     artifact-retention-days: '30'
 ```
@@ -70,12 +71,30 @@ Then add SnapDrift after the app is running:
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift/actions/pr-diff@v0.4.0
+  uses: ranacseruet/snapdrift@v0.8.0
   with:
+    mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
     repo-config-path: .github/snapdrift.json
 ```
 
+## Choosing an entry point
+
+`ranacseruet/snapdrift` is the GitHub Marketplace entry point. It is a thin dispatcher: `mode: baseline` runs the baseline pipeline and `mode: pr-diff` runs the pull request pipeline, forwarding every input and output of the underlying wrapper action.
+
+The wrappers remain published in their own right, and are equivalent to the dispatcher:
+
+| Entry point | Equivalent to |
+|-------------|---------------|
+| `ranacseruet/snapdrift@v0.8.0` with `mode: baseline` | `ranacseruet/snapdrift/actions/baseline@v0.8.0` |
+| `ranacseruet/snapdrift@v0.8.0` with `mode: pr-diff` | `ranacseruet/snapdrift/actions/pr-diff@v0.8.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.
+
+### Pinning
+
+The dispatcher loads its wrapper from a pinned ref of this same repository. Released versions pin that ref to a commit SHA, so resolving `ranacseruet/snapdrift` to a SHA freezes the whole chain. If you are consuming an unreleased ref (`@main`, or a branch), the inner ref is a tag instead, and a SHA pin on the dispatcher does not freeze what it delegates to — pin the wrapper actions directly if that matters to you.
+
 ## Example workflow (Node app)
 
 ```yaml
@@ -111,8 +130,9 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift/actions/pr-diff@v0.4.0
+        uses: ranacseruet/snapdrift@v0.8.0
         with:
+          mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repo-config-path: .github/snapdrift.json
 ```
@@ -150,8 +170,9 @@ jobs:
           done
 
       - name: SnapDrift Report
-        uses: ranacseruet/snapdrift/actions/pr-diff@v0.4.0
+        uses: ranacseruet/snapdrift@v0.8.0
         with:
+          mode: pr-diff
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repo-config-path: .github/snapdrift.json
 ```

package/docs/local-cli.md

@@ -22,6 +22,40 @@ npx snapdrift <command>
 
 ## Commands
 
+### `snapdrift baseline`
+
+Establishes the baseline for whichever provider the config selects. This is the command to reach for when seeding a project.
+
+```
+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.
+
+`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.
+
+**`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.
+
+**Options**
+
+| Flag | Default | Description |
+|:-----|:--------|:------------|
+| `--config <path>` | `.github/snapdrift.json` | Path to the config file |
+| `--routes <ids>` | all routes | Comma-separated route IDs to capture |
+| `--baseline-dir <path>` | `.snapdrift/baseline` | Directory to write baseline screenshots and metadata (local provider) |
+
+**Example**
+
+```bash
+snapdrift baseline
+snapdrift baseline --routes home-desktop,home-mobile
+```
+
+---
+
 ### `snapdrift capture`
 
 Captures full-page screenshots of all configured routes and saves them as a local baseline.
@@ -82,15 +116,15 @@ snapdrift diff --baseline-dir snapshots/baseline --diff-dir snapshots/diff
 
 ### `snapdrift migrate-baselines`
 
-Move baselines between the local filesystem and the hosted Snap backend. Requires a config with `provider: "snap"` (or a `snap` block) for the direction being targeted.
+Export baselines from the hosted Snap backend to the local filesystem. Requires a config with `provider: "snap"` (or a `snap` block).
 
-**Upload local baselines to Snap:**
+**`--to snap` is not supported (removed in 0.7.0).**
 
 ```bash
-snapdrift migrate-baselines --to snap
+snapdrift migrate-baselines --to snap   # always fails
 ```
 
-Reads `results.json`, `manifest.json`, and `screenshots/*.png` from the local baseline directory, then POSTs them to Snap as the initial accepted baseline for the current commit. Idempotent: if a baseline already exists for the same commit SHA the upload is skipped.
+Snap cannot accept a pre-built local baseline bundle: the screenshots it carries are never uploaded to Snap storage, and its manifest references local filenames rather than Snap object keys, so the result would be a baseline with no pixels behind it. The endpoint rejects the request with `400 unsupported_baseline_body`. Use [`snapdrift baseline`](#snapdrift-baseline) instead — it captures each route through Snap so the images actually land in storage, then publishes a manifest that points at them.
 
 **Download Snap baselines to a local directory:**
 
@@ -200,7 +234,7 @@ Add `.snapdrift/` to your `.gitignore` to keep local run output out of version c
 
 | Code | Meaning |
 |:-----|:--------|
-| `0` | Clean — no drift above threshold, `diff.mode` is `report-only`, the diff was intentionally skipped (e.g. `SnapSkipError` from `onUnavailable: "warn-and-skip"`), or the command was a `capture` / `migrate-baselines` / `init` that completed |
+| `0` | Clean — no drift above threshold, `diff.mode` is `report-only`, the command was intentionally skipped under `onUnavailable: "warn-and-skip"` (`diff`, `capture` and `baseline` all exit 0 in that case), or the command was a `capture` / `baseline` / `migrate-baselines --to local` / `init` that completed |
 | `1` | Drift enforced — `diff.mode` caused the run to fail, a required command argument was missing, or the `--to local` engine-name check failed (see [Drift modes](../README.md#drift-modes)) |
 
 Enforcement follows the same `diff.mode` rules as the GitHub Actions workflow. Set `"mode": "report-only"` during local development to always get a report without a failing exit code.

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

@@ -70,8 +70,9 @@ jobs:
       # ────────────────────────────────────────────────────────────────────────
 
       - name: Publish SnapDrift baseline
-        uses: ranacseruet/snapdrift/actions/baseline@v0.4.0
+        uses: ranacseruet/snapdrift@v0.8.0
         with:
+          mode: baseline
           repo-config-path: .github/snapdrift.json
           artifact-retention-days: '30'
 

package/lib/cli.mjs

@@ -35,7 +35,7 @@ export const LOCAL_DIFF_SUBDIR = 'diff';
 
 /**
  * Parse CLI arguments from process.argv (or a provided argv array).
- * Supported commands: capture, diff, migrate-baselines, init
+ * Supported commands: capture, baseline, diff, migrate-baselines, init
  * Supported flags:
  *   --open              Open the HTML report after diff
  *   --config <path>     Path to snapdrift.json (default: .github/snapdrift.json)
@@ -190,6 +190,13 @@ export async function runCaptureCommand(opts) {
     });
     process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
   } catch (error) {
+    // onUnavailable: warn-and-skip — the user asked not to fail the build when
+    // Snap is down. `diff` and `baseline` both honour this; `capture` used to
+    // let SnapSkipError reach bin/snapdrift.mjs, which exits 1. See #108.
+    if (error instanceof SnapSkipError) {
+      process.stdout.write('Capture skipped (Snap unavailable, warn-and-skip mode).\n');
+      return;
+    }
     if (error instanceof SnapFallbackError) {
       process.stdout.write('Falling back to local provider for capture...\n');
       const localProvider = createProvider('local');
@@ -205,6 +212,110 @@ export async function runCaptureCommand(opts) {
   }
 }
 
+/**
+ * Run the `baseline` command — establish a baseline for the configured provider.
+ *
+ * For `provider: "local"` this is `capture`: the screenshots written to
+ * `--baseline-dir` *are* the baseline, and there is nothing to publish.
+ *
+ * For `provider: "snap"` the capture step only submits a run; the baseline is
+ * not created until `publishBaseline()` harvests the rendered object keys. That
+ * call previously existed only inside `actions/baseline`, which left anyone not
+ * running GitHub Actions with no supported way to seed a hosted project — see
+ * ranacseruet/snapdrift#106.
+ *
+ * Mirrors the two provider-conditional steps of `actions/baseline/action.yml`.
+ *
+ * @param {CliOptions} opts
+ * @returns {Promise<void>}
+ */
+export async function runBaselineCommand(opts) {
+  const { config } = await loadSnapdriftConfig(opts.configPath);
+  const providerName = config.provider ?? 'local';
+  const provider = createProvider(providerName, config);
+
+  process.stdout.write(
+    providerName === 'snap'
+      ? 'Establishing baseline via Snap ...\n'
+      : `Capturing baseline to ${opts.baselineDir} ...\n`
+  );
+
+  /** Capture locally so `fallback-local` still leaves the user with a baseline. */
+  async function captureLocalFallback() {
+    process.stdout.write('Falling back to local provider for capture...\n');
+    const localProvider = createProvider('local');
+    const { selectedRouteIds } = await localProvider.capture({
+      configPath: opts.configPath,
+      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+      outDir: opts.baselineDir
+    });
+    process.stdout.write(
+      `Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir} (local fallback — nothing published to Snap)\n`
+    );
+  }
+
+  /**
+   * Apply the configured `onUnavailable` behaviour. Snap can go down during
+   * *either* phase — the capture submission or the publish that follows it — and
+   * the user's choice must hold for both, otherwise `warn-and-skip` still exits 1
+   * and `fallback-local` still leaves them with no baseline.
+   *
+   * @param {unknown} error
+   * @param {string} skipMessage
+   * @returns {Promise<boolean>} true when the error was absorbed
+   */
+  async function handleUnavailable(error, skipMessage) {
+    if (error instanceof SnapSkipError) {
+      process.stdout.write(skipMessage);
+      return true;
+    }
+    if (error instanceof SnapFallbackError) {
+      await captureLocalFallback();
+      return true;
+    }
+    return false;
+  }
+
+  /** @type {{ resultsPath?: string, selectedRouteIds: string[] }} */
+  let captured;
+  try {
+    captured = await provider.capture({
+      configPath: opts.configPath,
+      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+      outDir: opts.baselineDir,
+      purpose: 'baseline'
+    });
+  } catch (error) {
+    if (await handleUnavailable(error, 'Baseline skipped (Snap unavailable, warn-and-skip mode).\n')) {
+      return;
+    }
+    throw error;
+  }
+
+  if (providerName !== 'snap') {
+    process.stdout.write(`Captured ${captured.selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
+    return;
+  }
+
+  process.stdout.write(
+    `Captured ${captured.selectedRouteIds.length} route(s); waiting for Snap to finish rendering ...\n`
+  );
+  try {
+    await provider.publishBaseline({ resultsPath: captured.resultsPath });
+  } catch (error) {
+    if (
+      await handleUnavailable(
+        error,
+        'Baseline publish skipped (Snap unavailable, warn-and-skip mode).\n'
+      )
+    ) {
+      return;
+    }
+    throw error;
+  }
+  process.stdout.write('Snap baseline published successfully.\n');
+}
+
 /**
  * Run the `diff` command — capture current screenshots, compare against the local baseline,
  * write a summary + HTML report, and optionally open it.
@@ -360,6 +471,8 @@ export async function main(argv) {
 
   if (opts.command === 'capture') {
     await runCaptureCommand(opts);
+  } else if (opts.command === 'baseline') {
+    await runBaselineCommand(opts);
   } else if (opts.command === 'diff') {
     await runDiffCommand(opts);
   } else if (opts.command === 'migrate-baselines') {
@@ -368,7 +481,7 @@ export async function main(argv) {
     await runInitCommand(opts);
   } else {
     process.stderr.write(
-      `Unknown command: ${opts.command}\nUsage: snapdrift <capture|diff|migrate-baselines|init> [options]\n`
+      `Unknown command: ${opts.command}\nUsage: snapdrift <capture|baseline|diff|migrate-baselines|init> [options]\n`
     );
     process.exitCode = 1;
   }

package/lib/init-from-action.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import * as yaml from 'js-yaml';
 
 /** @typedef {import('../types/visual-diff-types').InitWarning} InitWarning */
+/** @typedef {import('../types/visual-diff-types').JsonObject} JsonObject */
 
 const DEFAULT_OUTPUT_DIR = '.github';
 const DEFAULT_CONFIG_FILENAME = 'snapdrift.json';
@@ -13,8 +14,8 @@ const MIGRATION_NOTES_FILENAME = 'MIGRATION_NOTES.md';
 /**
  * Find the step that uses the Snap visual testing action.
  *
- * @param {object} workflow - Parsed YAML workflow
- * @returns {{ step: object, jobName: string, stepIndex: number } | null}
+ * @param {JsonObject} workflow - Parsed YAML workflow
+ * @returns {{ step: JsonObject, jobName: string, stepIndex: number } | null}
  */
 function findSnapActionStep(workflow) {
   const jobs = workflow.jobs || {};
@@ -34,7 +35,7 @@ function findSnapActionStep(workflow) {
 /**
  * Map Snap action enforcement mode to snapdrift diff.mode.
  *
- * @param {object} inputs
+ * @param {JsonObject} inputs
  * @returns {string}
  */
 function mapDiffMode(inputs) {
@@ -52,7 +53,7 @@ function mapDiffMode(inputs) {
 /**
  * Extract Snap action inputs and translate to snapdrift config fields.
  *
- * @param {object} step - The workflow step using the Snap action
+ * @param {JsonObject} step - The workflow step using the Snap action
  * @returns {{ config: object, warnings: InitWarning[] }}
  */
 function translateStepToConfig(step) {
@@ -87,7 +88,7 @@ function translateStepToConfig(step) {
   }
 
   // Snap provider config (if present in inputs)
-  /** @type {object | undefined} */
+  /** @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;
@@ -195,10 +196,11 @@ export async function runInitFromAction(actionYamlPath) {
     throw new Error(`Cannot read workflow file: ${actionYamlPath}`);
   }
 
-  const workflow = yaml.load(workflowContent);
-  if (!workflow || typeof workflow !== 'object') {
+  const parsedWorkflow = yaml.load(workflowContent);
+  if (!parsedWorkflow || typeof parsedWorkflow !== 'object') {
     throw new Error(`Invalid workflow YAML: ${actionYamlPath}`);
   }
+  const workflow = /** @type {JsonObject} */ (parsedWorkflow);
 
   // Find the Snap action step
   const snapStep = findSnapActionStep(workflow);

package/lib/migrate-baselines.mjs

@@ -6,6 +6,8 @@ import path from 'node:path';
 
 import { createProvider } from './provider.mjs';
 
+/** @typedef {import('../types/visual-diff-types').JsonObject} JsonObject */
+
 /**
  * Resolve the current commit HEAD SHA.
  * Tries GITHUB_SHA first, then git rev-parse HEAD.
@@ -28,7 +30,7 @@ function resolveHeadSha() {
  * Read local baseline files from a directory.
  *
  * @param {string} baselineDir
- * @returns {Promise<{ results: object, manifest: object, screenshots: Array<{ filename: string, data: string }>, headSha: string }>}
+ * @returns {Promise<{ results: JsonObject, manifest: JsonObject, screenshots: Array<{ filename: string, data: string }>, headSha: string }>}
  */
 export async function readLocalBaselines(baselineDir) {
   const resultsPath = path.join(baselineDir, 'results.json');
@@ -86,39 +88,33 @@ function requireSnapConfig(config) {
 }
 
 /**
- * Run the migrate-to-snap direction.
- * Reads local baselines and uploads them to Snap.
+ * Run the migrate-to-snap direction — retired.
  *
- * @param {import('../types/visual-diff-types').VisualRegressionConfig} config
- * @param {import('../types/visual-diff-types').CliOptions} opts
- * @returns {Promise<void>}
+ * This uploaded a pre-built local baseline bundle to
+ * `POST /v1/visual/projects/:id/baselines`, but the server has never read the
+ * `manifest`/`results`/`screenshots` fields that body carries: the PNGs were
+ * never stored, and the manifest referenced local filenames rather than Snap
+ * object keys. The request used to fail with an opaque 500 and, since
+ * i2Dev-com/snap#653, is rejected outright with `400 unsupported_baseline_body`.
+ *
+ * `snapdrift baseline` is the supported replacement — it captures each route
+ * through Snap so the pixels actually land in storage, then publishes a manifest
+ * that references them (and that `--to local --from snap` can export back out).
+ *
+ * @param {import('../types/visual-diff-types').VisualRegressionConfig} _config
+ * @param {import('../types/visual-diff-types').CliOptions} _opts
+ * @returns {Promise<never>}
+ * @throws {Error} Always — the direction is not supported by the Snap API.
  */
-export async function runMigrateToSnap(config, opts) {
-  process.stdout.write(`Migrating baselines to Snap ...\n`);
-
-  requireSnapConfig(config);
-  const provider = createProvider('snap', config);
-  const baselineDir = opts.baselineDir;
-
-  const { results, manifest, screenshots, headSha } = await readLocalBaselines(baselineDir);
-
-  process.stdout.write(`Found ${screenshots.length} screenshot(s) for commit ${headSha.substring(0, 8)}\n`);
-
-  // Check idempotency — skip if baseline already exists
-  const existing = await provider.checkBaselineExists(headSha);
-  if (existing) {
-    process.stdout.write(`Baseline already exists for commit ${headSha.substring(0, 8)}. Skipping upload.\n`);
-    return;
-  }
-
-  const { uploaded, baselineId } = await provider.migrateBaselineFromLocal({
-    results,
-    manifest,
-    screenshots,
-    headSha
-  });
-
-  process.stdout.write(`Uploaded ${uploaded} screenshot(s) as baseline ${baselineId}\n`);
+export async function runMigrateToSnap(_config, _opts) {
+  throw new Error(
+    'migrate-baselines --to snap is no longer supported: Snap cannot accept a pre-built local ' +
+    'baseline bundle, because its screenshots are never uploaded to Snap storage and its manifest ' +
+    'references local filenames rather than Snap object keys.\n' +
+    'Run `snapdrift baseline` instead — it captures each route through Snap and publishes a ' +
+    'baseline from the stored objects.\n' +
+    'Migration in the other direction (`migrate-baselines --to local --from snap`) is unaffected.'
+  );
 }
 
 /**
@@ -136,7 +132,7 @@ export async function runMigrateToLocal(config, opts) {
   const provider = createProvider('snap', config);
   const baselineDir = opts.baselineDir;
 
-  /** @type {{ results: object, manifest: object, screenshots: Array<{ filename: string, data: Buffer }>, engine: { name: string, version: string } }} */
+  /** @type {{ results: JsonObject, manifest: JsonObject, screenshots: Array<{ filename: string, data: Buffer }>, engine: { name: string, version: string } }} */
   let exported;
   try {
     exported = await provider.exportBaselines();

package/lib/snap-provider.mjs

@@ -1,5 +1,6 @@
 // @ts-check
 
+import { execFileSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
@@ -22,6 +23,7 @@ import { selectConfiguredRoutes, splitCommaList, determineDriftStatus, VIEWPORT_
 /** @typedef {import('../types/visual-diff-types').ProviderBaselineData} BaselineData */
 /** @typedef {import('../types/visual-diff-types').SnapConfig} SnapConfig */
 /** @typedef {import('../types/visual-diff-types').VisualRegressionConfig} VisualRegressionConfig */
+/** @typedef {import('../types/visual-diff-types').JsonObject} JsonObject */
 
 const DEFAULT_API_URL = 'https://snap.i2dev.com';
 const MAX_RETRIES = 3;
@@ -71,6 +73,47 @@ function repoSlugToProjectId(repoSlug) {
   return repoSlug.replace(/[/.]/g, '--');
 }
 
+/**
+ * Run a git command, returning undefined outside a repository or when git is
+ * unavailable. execFileSync (not execSync) so no argument reaches a shell.
+ *
+ * @param {string[]} args
+ * @returns {string | undefined}
+ */
+function gitOutput(args) {
+  try {
+    const out = execFileSync('git', args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const trimmed = out.trim();
+    return trimmed === '' ? undefined : trimmed;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the branch and commit a baseline should be attributed to.
+ *
+ * GitHub Actions exports these; a developer running `snapdrift baseline` from a
+ * terminal does not. Without the git fallback every locally seeded baseline was
+ * recorded as branch `main` at SHA `unknown`, which misattributes it in the
+ * dashboard and in exported metadata — and makes two baselines cut from
+ * different commits indistinguishable. Detached HEAD yields no branch name, so
+ * `main` remains the last resort.
+ *
+ * @returns {{ refBranch: string, refSha: string }}
+ */
+export function resolveGitRef() {
+  const branch = gitOutput(['rev-parse', '--abbrev-ref', 'HEAD']);
+  return {
+    refBranch:
+      process.env.GITHUB_REF_NAME ||
+      process.env.GITHUB_HEAD_REF ||
+      (branch && branch !== 'HEAD' ? branch : undefined) ||
+      'main',
+    refSha: process.env.GITHUB_SHA || gitOutput(['rev-parse', 'HEAD']) || 'unknown'
+  };
+}
+
 /**
  * Read the package version from package.json.
  * @returns {string}
@@ -431,11 +474,30 @@ export class SnapProvider {
     // create a baseline from the rendered S3 keys.
     if (resultsPath) {
       let metadata;
+      /** @type {unknown} */
+      let readError;
       try {
         metadata = JSON.parse(await fs.readFile(resultsPath, 'utf-8'));
-      } catch { /* fall through to legacy path */ }
+      } catch (error) {
+        readError = error;
+      }
 
-      if (metadata?.runId) {
+      if (!metadata?.runId) {
+        // Previously this fell through to a "legacy" branch that POSTed
+        // `manifest`/`results` as objects. Snap has never read those fields, so
+        // the request could only ever fail — with an opaque 500 before, and with
+        // `400 unsupported_baseline_body` since i2Dev-com/snap#653. Reporting the
+        // real problem (no run id) beats emitting a request guaranteed to fail
+        // and surfacing its body-shape error. See #109.
+        throw new Error(
+          `Cannot publish a Snap baseline: no run id found in ${resultsPath}. ` +
+          'A baseline is created from the object keys of a completed Snap run, so the capture step ' +
+          'must have recorded one. Run `snapdrift baseline` (or actions/baseline) with ' +
+          `provider "snap".${readError ? ` Could not read that file: ${readError instanceof Error ? readError.message : String(readError)}` : ''}`
+        );
+      }
+
+      {
         const { runId } = metadata;
         const idempotencyKey = `baseline-${runId}`;
 
@@ -487,8 +549,7 @@ export class SnapProvider {
           `/v1/visual/projects/${this.#projectId}/baselines`,
           {
             id: baselineId,
-            refBranch: process.env.GITHUB_REF_NAME || process.env.GITHUB_HEAD_REF || 'main',
-            refSha: process.env.GITHUB_SHA || 'unknown',
+            ...resolveGitRef(),
             manifestJson,
             captureProfileJson: JSON.stringify(this.#buildCaptureProfile())
           },
@@ -500,37 +561,12 @@ export class SnapProvider {
       }
     }
 
-    // Legacy / migration path: bundle dir with pre-built results/manifest
-    const idempotencyKey = this.#generateIdempotencyKey();
-    const body = { idempotencyKey };
-
-    if (options.bundleDir) {
-      const bundleDir = path.resolve(options.bundleDir);
-      const bResultsPath = options.resultsPath || path.join(bundleDir, 'results.json');
-      const manifestPath = options.manifestPath || path.join(bundleDir, 'manifest.json');
-
-      try {
-        const results = JSON.parse(await fs.readFile(bResultsPath, 'utf-8'));
-        body.results = results;
-      } catch { /* results.json may not exist */ }
-
-      try {
-        const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
-        body.manifest = manifest;
-      } catch { /* manifest.json may not exist */ }
-
-      if (body.results?.runId) {
-        body.idempotencyKey = `baseline-${body.results.runId}`;
-      }
-    }
-
-    await this.#request('POST', `/v1/visual/projects/${this.#projectId}/baselines`, body, idempotencyKey);
-
-    const bundleDir = options.bundleDir
-      ? path.resolve(options.bundleDir)
-      : await fs.mkdtemp(path.join(os.tmpdir(), 'snapdrift-snap-baseline-'));
-
-    return { bundleDir };
+    // No resultsPath and no bundleDir: there is no run to build a baseline from.
+    throw new Error(
+      'Cannot publish a Snap baseline: neither resultsPath nor bundleDir was provided, so there ' +
+      'is no Snap run to harvest object keys from. Run `snapdrift baseline` (or actions/baseline) ' +
+      'with provider "snap", which captures first and passes the run results through.'
+    );
   }
 
   /**
@@ -609,44 +645,14 @@ export class SnapProvider {
     }
   }
 
-  /**
-   * Upload local baselines to Snap as the initial accepted baseline.
-   * Used by `snapdrift migrate-baselines --to snap`.
-   *
-   * Reads local baseline files and POSTs them to the Snap baselines API.
-   * Screenshots are base64-encoded and included in the request body.
-   * Idempotent: uses a commit-SHA-derived idempotency key.
-   *
-   * @param {{
-   *   results: object,
-   *   manifest: object,
-   *   screenshots: Array<{ filename: string, data: string }>,
-   *   headSha: string
-   * }} options
-   * @returns {Promise<{ uploaded: number, skipped: number, baselineId: string }>}
-   */
-  async migrateBaselineFromLocal(options) {
-    const { results, manifest, screenshots, headSha } = options;
-    const idempotencyKey = `baseline-migrate-${headSha}`;
-
-    const body = {
-      idempotencyKey,
-      results,
-      manifest,
-      screenshots,
-      headSha,
-      captureProfile: this.#buildCaptureProfile()
-    };
-
-    const response = await this.#request('POST', `/v1/visual/projects/${this.#projectId}/baselines`, body, idempotencyKey);
-
-    const screenshotCount = screenshots?.length ?? 0;
-    return {
-      uploaded: screenshotCount,
-      skipped: 0,
-      baselineId: response.id || idempotencyKey
-    };
-  }
+  // `migrateBaselineFromLocal()` was removed in 0.7.0. It POSTed a pre-built
+  // local bundle (`manifest`/`results`/`screenshots` as objects) to the
+  // baselines API, but the server never read those fields — the PNGs were never
+  // stored and the manifest referenced local filenames rather than Snap object
+  // keys, so the call could only ever produce an unexportable baseline. Snap now
+  // rejects that body with `400 unsupported_baseline_body` (i2Dev-com/snap#653).
+  // Use `publishBaseline()` after `capture()` — or the `snapdrift baseline`
+  // command, which wires both together. See ranacseruet/snapdrift#106.
 
   /**
    * Export baselines from Snap for local import.
@@ -662,8 +668,8 @@ export class SnapProvider {
    *
    * @param {{ tag?: string }} [_options]
    * @returns {Promise<{
-   *   results: object,
-   *   manifest: object,
+   *   results: JsonObject,
+   *   manifest: JsonObject,
    *   screenshots: Array<{ filename: string, data: Buffer }>,
    *   engine: { name: string, version: string }
    * }>}
@@ -746,7 +752,7 @@ export class SnapProvider {
 
     /** @type {Array<{ filename: string, data: Buffer }>} */
     const screenshots = [];
-    /** @type {Array<object>} */
+    /** @type {JsonObject[]} */
     const manifestEntries = [];
 
     for (const route of routes) {
@@ -1204,7 +1210,7 @@ export class SnapProvider {
   /**
    * Poll a run until it reaches a terminal state.
    * @param {string} runId
-   * @returns {Promise<object>}
+   * @returns {Promise<JsonObject>}
    */
   async #pollRun(runId) {
     const startTime = Date.now();
@@ -1224,7 +1230,7 @@ export class SnapProvider {
 
   /**
    * Map a Snap run result to a VisualDiffSummary.
-   * @param {object} run
+   * @param {JsonObject} run
    * @param {VisualRegressionConfig} config
    * @returns {import('../types/visual-diff-types').VisualDiffSummary}
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",
@@ -46,7 +46,7 @@
     "eslint": "^10.2.0",
     "globals": "^17.4.0",
     "jest": "^30.3.0",
-    "typescript": "^6.0.2"
+    "typescript": "^7.0.2"
   },
   "jest": {
     "testEnvironment": "node",
@@ -82,6 +82,7 @@
     "./lib/init-from-action.mjs": "./lib/init-from-action.mjs"
   },
   "files": [
+    "action.yml",
     "actions/",
     "bin/",
     "lib/",

package/types/visual-diff-types.d.ts

@@ -1,3 +1,6 @@
+/** Object-shaped data decoded from an external JSON or YAML boundary. */
+export type JsonObject = Record<string, any>;
+
 export type VisualViewportPreset = 'desktop' | 'mobile';
 export interface VisualCustomViewport { width: number; height: number; }
 export type VisualViewport = VisualViewportPreset | VisualCustomViewport;
@@ -166,8 +169,8 @@ export interface MigrateToSnapResult {
 }
 
 export interface ExportedBaseline {
-  results: object;
-  manifest: object;
+  results: JsonObject;
+  manifest: JsonObject;
   screenshots: Array<{ filename: string; data: Buffer }>;
   engine: { name: string; version: string };
 }