snapdrift 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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

@@ -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/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';
@@ -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}
@@ -431,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}`;
 
@@ -487,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())
           },
@@ -500,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.'
+    );
   }
 
   /**
@@ -609,44 +644,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.

package/package.json

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