snapdrift 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,6 +1,30 @@
 # Changelog
 
-## Unreleased
+## 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
+
+- **`migrate-baselines --to local --from snap` is now functional** — `SnapProvider.exportBaselines` downloads the project's export archive from Snap's `GET /v1/visual/projects/:id/export` endpoint (requires an API key with the `visual:export` scope), parses the tar in pure JS, selects the most recent accepted baseline, and maps it back to the local baseline layout (`results.json`, `manifest.json`, `screenshots/<routeId>.png`). The imported engine name is passed through truthfully — baselines rendered by Snap's hosted worker report their own engine (falling back to `snap-hosted`) and require `--accept-cross-engine` to import, while baselines originally published by SnapDrift report `snapdrift-local` and import cleanly. Clear errors cover a missing `visual:export` scope (403), an unknown project (404), oversized exports (413), projects with no accepted baselines, and legacy baselines that predate manifest tracking. Previously this command failed with a "Snap export endpoint is not yet available" stub error.
+
+### Fixes
+
+- **Reject error pages during capture** — `runBaselineCapture` now checks the HTTP status of each route navigation and fails the route if it resolves to a 4xx/5xx. `page.goto` resolves even on a 404/500 (the error body still loads), so previously a broken route — wrong slug, misconfigured `baseUrl`, or an outage — would silently screenshot its error page and upload it as a valid baseline. The failure flows into the existing retry-then-fail path, so a genuinely broken capture now fails loudly instead of poisoning the baseline. Complements the 0% -drift heuristic guard from #93 with a direct status check. Redirects (3xx) still pass, since Playwright follows them and reports the final status; `null` responses (non-navigation schemes) are treated as fine.
 
 ## 0.5.1 - 2026-07-14
 

package/README.md

@@ -69,14 +69,17 @@ That is the full integration. See the [Integration Guide](docs/integration-guide
 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 +107,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/docs/contracts.md

@@ -272,12 +272,13 @@ snapdrift migrate-baselines --to snap [--config <path>] [--baseline-dir <dir>]
 snapdrift migrate-baselines --to local --from snap [--accept-cross-engine] [--config <path>] [--baseline-dir <dir>]
 ```
 
-- Downloads baselines from Snap's export endpoint.
-- Writes `results.json`, `manifest.json`, and `screenshots/*.png` to the local baseline directory.
+- Downloads the project's export archive from Snap's export endpoint (`GET /v1/visual/projects/:id/export`, a tar containing every accepted baseline's screenshots, capture profile, and source manifest). Requires an API key with the `visual:export` scope.
+- Imports the **most recent accepted baseline** (by `createdAt`) from the archive; older accepted baselines in the export are ignored.
+- Writes `results.json`, `manifest.json`, and `screenshots/*.png` to the local baseline directory. Screenshot filenames are derived from the baseline's route ids (`screenshots/<routeId>.png`), matching what a local capture would produce.
 - Writes `.migration-metadata.json` next to the baseline recording `source`, `migratedAt`, and the engine that produced the export.
-- Without `--accept-cross-engine`: hard-errors if the exported manifest's engine name is not `snapdrift-local`.
+- Without `--accept-cross-engine`: hard-errors if the exported baseline's engine name is not `snapdrift-local` (e.g. `snap-hosted` for baselines rendered by Snap's worker).
 - With `--accept-cross-engine`: overrides the engine name to `snapdrift-local` in the imported manifest (visual differences may occur when the captures came from a different engine).
-- Requires the Snap export endpoint to be available; if it is not yet wired up, the command fails with an actionable message instead of producing a partial baseline.
+- Fails with an actionable message — instead of producing a partial baseline — when the project has no accepted baselines, when the selected baseline predates manifest tracking (no source manifest recorded at publish time), when the key lacks the `visual:export` scope (403), or when the export exceeds Snap's size caps (413).
 
 ### init
 

package/docs/integration-guide.md

@@ -227,7 +227,7 @@ Conversely, downloading a Snap baseline back to a local directory (useful for re
 snapdrift migrate-baselines --to local --from snap
 ```
 
-The reverse direction requires the Snap export endpoint to be available; if it isn't, the command fails with an actionable error. See the [Contracts reference](contracts.md#migration-commands) for the full flag set, the engine-compatibility check, and the metadata file written for idempotency.
+The reverse direction downloads the project's export archive from Snap (`GET /v1/visual/projects/:id/export`, which requires an API key with the `visual:export` scope) and imports the most recent accepted baseline into the local baseline directory. See the [Contracts reference](contracts.md#migration-commands) for the full flag set, the engine-compatibility check, and the metadata file written for idempotency.
 
 If you're adopting SnapDrift as a replacement for the upstream `snap/github-action`, the `init` codemod translates the workflow YAML and emits a `MIGRATION_NOTES.md` with everything that couldn't be auto-translated:
 

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/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/migrate-baselines.mjs

@@ -86,39 +86,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.'
+  );
 }
 
 /**

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';
@@ -9,7 +10,7 @@ import path from 'node:path';
 
 import { makeMarkdown, buildReportCommentBody } from '@snapdrift/adapter-report-md';
 import { loadSnapdriftConfig, runBaselineCapture } from '@snapdrift/adapter-fs';
-import { selectConfiguredRoutes, splitCommaList, determineDriftStatus, VIEWPORT_PRESETS } from '@snapdrift/manifest';
+import { selectConfiguredRoutes, splitCommaList, determineDriftStatus, VIEWPORT_PRESETS, viewportHash } from '@snapdrift/manifest';
 
 /** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
 /** @typedef {import('../types/visual-diff-types').ProviderCaptureOptions} CaptureOptions */
@@ -71,6 +72,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}
@@ -85,6 +127,146 @@ function getPackageVersion() {
   }
 }
 
+const TAR_BLOCK_SIZE = 512;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * Strips characters that could cause path traversal or produce invalid
+ * filenames when a route id is used as a screenshot filename. Mirrors the
+ * sanitisation applied by `@snapdrift/adapter-fs` during local capture so
+ * imported baselines land on the same filenames a local capture would produce.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+function sanitizeRouteId(id) {
+  return id
+    .replace(/\.\./g, '_')
+    .replace(/[/\\]/g, '_')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f]/g, '');
+}
+
+/**
+ * Parse a plain ustar-style tar archive (512-byte headers, bodies padded to
+ * 512-byte blocks, terminated by zero blocks) into a map of entry name →
+ * entry bytes. This is the exact layout Snap's export endpoint produces;
+ * long-name extensions (GNU/pax) are not needed and not supported.
+ *
+ * @param {Buffer} archive
+ * @returns {Map<string, Buffer>}
+ */
+function parseTarEntries(archive) {
+  /** @type {Map<string, Buffer>} */
+  const entries = new Map();
+  let offset = 0;
+
+  while (offset + TAR_BLOCK_SIZE <= archive.length) {
+    const header = archive.subarray(offset, offset + TAR_BLOCK_SIZE);
+    if (header.every((byte) => byte === 0)) {
+      break; // end-of-archive marker
+    }
+
+    const nameField = header.subarray(0, 100);
+    const nameEnd = nameField.indexOf(0);
+    const name = nameField.toString('utf-8', 0, nameEnd === -1 ? 100 : nameEnd);
+    const size = parseInt(header.toString('ascii', 124, 136).replace(/\0/g, '').trim(), 8);
+
+    if (!name || !Number.isFinite(size) || size < 0) {
+      throw new Error(`Snap export archive is corrupt: invalid tar header at offset ${offset}.`);
+    }
+
+    const bodyStart = offset + TAR_BLOCK_SIZE;
+    if (bodyStart + size > archive.length) {
+      throw new Error(`Snap export archive is truncated: entry "${name}" extends past the end of the archive.`);
+    }
+
+    entries.set(name, archive.subarray(bodyStart, bodyStart + size));
+    offset = bodyStart + Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;
+  }
+
+  return entries;
+}
+
+/**
+ * Read the pixel dimensions from a PNG's IHDR chunk. Returns null when the
+ * bytes are not a PNG (e.g. a JPEG export) or are too short.
+ *
+ * @param {Buffer} bytes
+ * @returns {{ width: number, height: number } | null}
+ */
+function readPngDimensions(bytes) {
+  if (bytes.length < 24 || !bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) {
+    return null;
+  }
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+
+/**
+ * @param {string | undefined} json
+ * @returns {any}
+ */
+function safeJsonParse(json) {
+  if (!json) return null;
+  try {
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sort key for picking the newest baseline. Snap serialises createdAt as an
+ * ISO string, but tolerate epoch numbers and treat unparsable values as
+ * oldest so a legacy row never shadows a well-formed one.
+ *
+ * @param {{ createdAt?: unknown }} baseline
+ * @returns {number}
+ */
+function baselineTimestamp(baseline) {
+  const createdAt = baseline?.createdAt;
+  if (typeof createdAt === 'number') return createdAt;
+  const parsed = Date.parse(typeof createdAt === 'string' ? createdAt : '');
+  return Number.isNaN(parsed) ? -Infinity : parsed;
+}
+
+/**
+ * Derive the capture engine from a baseline's capture profile. A baseline
+ * published by SnapDrift records `{ engine: { name: "snapdrift-local" } }`;
+ * a baseline rendered by Snap's hosted worker records Snap's own engine.
+ * When nothing is recorded (legacy hosted baselines export `{}`), fall back
+ * to "snap-hosted" so the CLI's cross-engine flow engages truthfully.
+ *
+ * @param {any} captureProfile
+ * @returns {{ name: string, version: string }}
+ */
+function resolveExportEngine(captureProfile) {
+  const engine = captureProfile?.engine;
+  if (engine && typeof engine.name === 'string' && engine.name) {
+    return {
+      name: engine.name,
+      version: typeof engine.version === 'string' && engine.version ? engine.version : 'unknown'
+    };
+  }
+  return { name: 'snap-hosted', version: 'unknown' };
+}
+
+/**
+ * Extract a human-readable detail string from a Snap API error response.
+ *
+ * @param {{ text: () => Promise<string> }} response
+ * @returns {Promise<string>}
+ */
+async function readErrorDetail(response) {
+  const errorBody = await response.text().catch(() => '');
+  try {
+    const parsed = JSON.parse(errorBody);
+    return parsed.error || parsed.message || '';
+  } catch {
+    return '';
+  }
+}
+
 /**
  * SnapProvider — VisualProvider that delegates capture + diff to Snap's
  * hosted /v1/visual/* API.
@@ -291,11 +473,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) {
+        // 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)}` : ''}`
+        );
+      }
 
-      if (metadata?.runId) {
+      {
         const { runId } = metadata;
         const idempotencyKey = `baseline-${runId}`;
 
@@ -347,8 +548,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())
           },
@@ -360,37 +560,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.'
+    );
   }
 
   /**
@@ -469,64 +644,198 @@ 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.
    * Used by `snapdrift migrate-baselines --to local --from snap`.
    *
-   * @param {{ tag?: string }} _options
+   * Downloads the project's export archive from
+   * `GET /v1/visual/projects/:id/export` (a plain ustar tar containing a
+   * `manifest.json`, per-baseline screenshot images, and per-baseline
+   * capture profiles; requires an API key with the `visual:export` scope),
+   * selects the most recent accepted baseline, and maps it back to the
+   * local baseline layout (`results.json` + `manifest.json` +
+   * `screenshots/<routeId>.png`) that `LocalProvider` reads.
+   *
+   * @param {{ tag?: string }} [_options]
    * @returns {Promise<{
    *   results: object,
    *   manifest: object,
    *   screenshots: Array<{ filename: string, data: Buffer }>,
    *   engine: { name: string, version: string }
    * }>}
-   * @throws {Error} The Snap export endpoint is not yet available.
+   * @throws {Error} When the project has no accepted baselines, the selected
+   *   baseline predates manifest tracking, or the export request fails.
    */
   async exportBaselines(_options) {
-    throw new Error(
-      'The Snap export endpoint is not yet available. ' +
-      'This command will be functional once the Snap API adds GET /v1/visual/projects/:id/export. ' +
-      'See Snap repo issue #482 for tracking.'
+    const exportPath = `/v1/visual/projects/${this.#projectId}/export`;
+    let archive;
+    try {
+      archive = await this.#requestBinary('GET', exportPath);
+    } catch (error) {
+      if (error instanceof SnapApiError) {
+        if (error.status === 403) {
+          throw new Error(
+            `Snap refused the export (403): the API key does not have the "visual:export" scope. ` +
+            `Issue a key with visual:export access for project "${this.#projectId}" and retry.`,
+            { cause: error }
+          );
+        }
+        if (error.status === 404) {
+          throw new Error(
+            `Snap project "${this.#projectId}" was not found (404). ` +
+            `Check snap.projectId in snapdrift.json (or GITHUB_REPOSITORY when projectId is "auto").`,
+            { cause: error }
+          );
+        }
+        if (error.status === 413) {
+          throw new Error(
+            `Snap export for project "${this.#projectId}" is too large (413): ${error.message}. ` +
+            `The export endpoint caps the number of accepted baselines and total archive bytes.`,
+            { cause: error }
+          );
+        }
+      }
+      throw error;
+    }
+
+    const entries = parseTarEntries(archive);
+    const manifestBytes = entries.get('manifest.json');
+    if (!manifestBytes) {
+      throw new Error('Snap export archive is missing manifest.json.');
+    }
+    const exportManifest = JSON.parse(manifestBytes.toString('utf-8'));
+    const baselines = Array.isArray(exportManifest.baselines) ? exportManifest.baselines : [];
+    if (baselines.length === 0) {
+      throw new Error(
+        `Snap project "${this.#projectId}" has no accepted baselines to export. ` +
+        `Publish a baseline first (snapdrift baseline with provider: "snap").`
+      );
+    }
+
+    // Most recent accepted baseline wins; `>=` makes the later array entry win
+    // a createdAt tie (the server appends newer rows last).
+    let baseline = baselines[0];
+    for (const candidate of baselines.slice(1)) {
+      if (baselineTimestamp(candidate) >= baselineTimestamp(baseline)) {
+        baseline = candidate;
+      }
+    }
+
+    if (!baseline.sourceManifest) {
+      throw new Error(
+        `Snap baseline "${baseline.id}" predates manifest tracking (no source manifest was recorded ` +
+        `at publish time) and cannot be migrated. Publish a fresh baseline with a current SnapDrift ` +
+        `version, then re-run the migration.`
+      );
+    }
+    const routes = Array.isArray(baseline.sourceManifest.routes) ? baseline.sourceManifest.routes : null;
+    if (!routes) {
+      throw new Error(
+        `Snap baseline "${baseline.id}" has an unrecognised source manifest format ` +
+        `(expected a "routes" array) and cannot be migrated.`
+      );
+    }
+
+    const archivePathByKey = new Map(
+      (baseline.objects || []).map((object) => [object.sourceKey, object.archivePath])
     );
+
+    /** @type {Array<{ filename: string, data: Buffer }>} */
+    const screenshots = [];
+    /** @type {Array<object>} */
+    const manifestEntries = [];
+
+    for (const route of routes) {
+      const archivePath = route.objectKey ? archivePathByKey.get(route.objectKey) : undefined;
+      const bytes = archivePath ? entries.get(archivePath) : undefined;
+      if (!bytes) {
+        process.stderr.write(
+          `[SnapDrift] Warning: Snap export has no image for route "${route.routeId}" ` +
+          `in baseline ${baseline.id}. Skipping the route.\n`
+        );
+        continue;
+      }
+
+      const descriptor = safeJsonParse(route.viewportDescriptorJson) ?? {};
+      const hasDescriptorDims = typeof descriptor.width === 'number' && typeof descriptor.height === 'number';
+      // Map the viewport descriptor back to a preset name when it matches one
+      // exactly; otherwise keep custom dimensions. This round-trips with the
+      // descriptor expansion capture() applies on the way up.
+      const presetName = hasDescriptorDims ? viewportHash(descriptor) : null;
+      const dimensions = readPngDimensions(bytes)
+        ?? (hasDescriptorDims ? { width: descriptor.width, height: descriptor.height } : { width: 1, height: 1 });
+      const viewport = presetName && VIEWPORT_PRESETS[presetName]
+        ? presetName
+        : hasDescriptorDims
+          ? { width: descriptor.width, height: descriptor.height }
+          : { width: dimensions.width, height: dimensions.height };
+
+      const extension = path.extname(archivePath) || '.png';
+      const filename = `${sanitizeRouteId(route.routeId)}${extension}`;
+      screenshots.push({ filename, data: Buffer.from(bytes) });
+      manifestEntries.push({
+        id: route.routeId,
+        path: route.routePath ?? '',
+        viewport,
+        imagePath: `screenshots/${filename}`,
+        width: dimensions.width,
+        height: dimensions.height
+      });
+    }
+
+    if (screenshots.length === 0) {
+      throw new Error(
+        `Snap baseline "${baseline.id}" contained no exportable screenshots — ` +
+        `the export archive had no image bytes for any of its routes.`
+      );
+    }
+
+    const captureProfile = safeJsonParse(
+      entries.get(`${baseline.id}/capture_profile.json`)?.toString('utf-8')
+    ) ?? {};
+    const engine = resolveExportEngine(captureProfile);
+
+    const generatedAt = new Date().toISOString();
+    const manifest = {
+      schemaVersion: 1,
+      generatedAt,
+      baseUrl: typeof baseline.sourceManifest.baseUrl === 'string' ? baseline.sourceManifest.baseUrl : '',
+      screenshots: manifestEntries,
+      captureProfile: { ...captureProfile, engine }
+    };
+
+    const results = {
+      startedAt: typeof baseline.createdAt === 'string' ? baseline.createdAt : generatedAt,
+      suite: 'snap-export',
+      provider: 'snap',
+      projectId: this.#projectId,
+      baselineId: baseline.id,
+      refBranch: baseline.refBranch,
+      // readLocalBaselines() picks this up as the commit SHA if the baseline is
+      // ever migrated back to Snap, keeping the idempotency key stable.
+      headSha: baseline.refSha,
+      routes: manifestEntries.map((entry) => ({
+        id: entry.id,
+        path: entry.path,
+        viewport: entry.viewport,
+        status: 'passed',
+        durationMs: 0,
+        imagePath: entry.imagePath,
+        width: entry.width,
+        height: entry.height
+      }))
+    };
+
+    return { results, manifest, screenshots, engine };
   }
 
   // ---------------------------------------------------------------------------
@@ -811,6 +1120,67 @@ export class SnapProvider {
     return this.#handleUnavailable(new SnapUnavailableError('Max retries exceeded'));
   }
 
+  /**
+   * Make an HTTP request to the Snap API that returns a binary body (e.g. the
+   * export tar). Mirrors #request's retry and error semantics — 4xx never
+   * retries and throws SnapApiError, 5xx/network errors retry with backoff and
+   * consult onUnavailable when exhausted — but returns the raw bytes instead
+   * of parsed JSON.
+   *
+   * @param {string} method
+   * @param {string} path
+   * @returns {Promise<any>} Raw response bytes as a Buffer
+   */
+  async #requestBinary(method, path) {
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        const response = await this.#fetchFn(`${this.#apiUrl}${path}`, {
+          method,
+          headers: { 'Authorization': `Bearer ${this.#apiKey}` }
+        });
+
+        if (response.ok) {
+          return Buffer.from(await response.arrayBuffer());
+        }
+
+        // 4xx — never retry
+        if (response.status >= 400 && response.status < 500) {
+          const detail = await readErrorDetail(response);
+          const errorMessage = detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`;
+          throw new SnapApiError(response.status, errorMessage, path);
+        }
+
+        // 5xx — retry with backoff (unless this is the last attempt)
+        if (attempt < MAX_RETRIES) {
+          const delay = Math.min(INITIAL_RETRY_DELAY_MS * (RETRY_MULTIPLIER ** (attempt - 1)), MAX_RETRY_TOTAL_MS);
+          await this.#sleepFn(delay);
+          continue;
+        }
+
+        // Exhausted retries
+        const detail = await readErrorDetail(response);
+        const errorMessage = detail ? `Snap API ${response.status}: ${detail}` : `Snap API ${response.status}`;
+        return this.#handleUnavailable(new SnapApiError(response.status, errorMessage, path));
+      } catch (error) {
+        if (error instanceof SnapApiError) {
+          throw error;
+        }
+
+        // Network error — retry
+        if (attempt < MAX_RETRIES) {
+          const delay = Math.min(INITIAL_RETRY_DELAY_MS * (RETRY_MULTIPLIER ** (attempt - 1)), MAX_RETRY_TOTAL_MS);
+          await this.#sleepFn(delay);
+          continue;
+        }
+
+        return this.#handleUnavailable(new SnapUnavailableError(error instanceof Error ? error.message : String(error)));
+      }
+    }
+
+    // Unreachable, but satisfies the type checker
+    return this.#handleUnavailable(new SnapUnavailableError('Max retries exceeded'));
+  }
+
   /**
    * Handle unavailable behavior based on onUnavailable config.
    * @param {Error} error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapdrift",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "description": "SnapDrift captures, compares, and reports UI drift for Playwright-based app checks.",