snapdrift 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,42 @@
 # Changelog
 
-## Unreleased
+## 0.4.0 - 2026-05-26
+
+### Features
+
+- **VisualProvider interface** — new `VisualProvider` interface (`capture`, `diff`, `publishBaseline`, `fetchLatestBaseline`, `buildCommentBody`) with `LocalProvider` and `SnapProvider` implementations. Config `provider` field (`"local"` | `"snap"`) selects the backend; defaults to `"local"` for zero-config backward compatibility.
+- **SnapProvider** — calls Snap's `/v1/visual/*` API for capture, diff, and baseline management. Retries on 5xx with exponential backoff (3 attempts, 30 s cap). Honors `snap.onUnavailable` (`"fail"` | `"warn-and-skip"` | `"fallback-local"`). 4xx errors never retry or fall back.
+- **Snap config** — new `snap` config block (`apiUrl`, `apiKeyEnv`/`apiKey`, `projectId`, `onUnavailable`) in `snapdrift.json`. Exactly one of `apiKeyEnv` or `apiKey` is required when `provider: "snap"`.
+- **PR comment unification** — both providers now produce identical PR comment markdown via a shared `buildCommentBody(summary, meta?)` method. `SnapProvider` appends a "View in dashboard →" link when `dashboardUrl` is present; `LocalProvider` omits it. Comment steps route through the provider instead of calling `buildReportCommentBody` directly, with a defensive fallback to `LocalProvider` if config loading fails.
+- **`migrate-baselines` command** — one-shot CLI command (`snapdrift migrate-baselines --to snap` / `--to local`) to upload local baselines to Snap or export Snap baselines back to a local directory. Supports `--accept-cross-engine` for engine-mismatch scenarios.
+- **`init --from-snap-action` codemod** — translates a Snap `github-action` workflow YAML into `snapdrift.json` with `provider: "snap"`. Emits structured warnings for features with no direct equivalent (jpeg format, baseline tags, single-shot artifact upload).
+
+### Infrastructure
+
+- **`@snapdrift/manifest` v1.1.0** — added `ProviderCommentMeta`, `dashboardUrl` on `VisualDiffSummary`, `buildCommentBody` on `VisualProvider`, `SnapConfig` re-export.
+- **`@snapdrift/adapter-report-md` v1.1.0** — `buildReportCommentBody` now accepts `dashboardUrl` in meta; renders "View in dashboard →" link when present and valid.
+- **Action contract tests** — `snapdrift-actions-contract` test suite now asserts that comment and pr-diff steps include `createProvider` and `buildCommentBody` calls.
+- **Provider unification tests** — new `buildCommentBody — provider unification` test block verifying identical markdown output across providers, dashboard link inclusion/exclusion, and URL validation.
+
+## 0.3.0 - 2026-05-26
+
+### Infrastructure
+
+- **Package extraction (Phase 1a)** — extracted `@snapdrift/manifest` (schema, validation, indexing, viewport presets) and `@snapdrift/compare-core` (pure pixel comparison, ignore-region masking) as standalone npm packages with zero runtime deps beyond `pngjs`.
+- **Package extraction (Phase 1b)** — extracted `@snapdrift/adapter-fs` (all filesystem I/O: capture, compare, config, staging, drift report generation) and `@snapdrift/adapter-report-md` (pure markdown/HTML report generators, zero runtime deps) as standalone npm packages.
+- **Lib/ shim refactor** — all `lib/*.mjs` modules are now thin re-export shims that delegate to packages. `lib/report.mjs` wires the default filesystem `imageReader` for HTML reports. Backward-compatible — all export surfaces preserved.
+- **`generateDiffImage` ignore regions** — `@snapdrift/compare-core` now overlays ignored pixel regions with semi-transparent gray instead of skipping them.
+- **Publish workflow** — `.github/workflows/publish.yml` now publishes all four `@snapdrift/*` workspace packages in dependency order before the root `snapdrift` package.
+
+### Performance
+
+- **Faster screenshot capture** — navigation now waits for `load` instead of `networkidle`, removing a guaranteed ≥500 ms floor per route. A 20-route run saves ~10 s in navigation waits alone.
+- **Concurrent route capture** — routes within the same viewport are now captured in parallel (up to `SNAPDRIFT_CAPTURE_CONCURRENCY` at a time, default 5) rather than sequentially, giving a further 3–5× throughput improvement on multi-route suites.
+- **Deterministic animation handling** — screenshots are taken with `animations: 'disabled'` so Playwright finishes/cancels CSS animations before capture, replacing reliance on the settle delay for animation timing.
+
+### Features
+
+- **`SNAPDRIFT_CAPTURE_CONCURRENCY` env var** — controls the maximum number of routes captured concurrently within a viewport context (positive integer, default `5`). Set to `1` to restore serial-per-viewport behaviour for apps with shared session or auth state.
 
 ## 0.2.1 - 2026-04-13
 

package/actions/comment/action.yml

@@ -20,6 +20,10 @@ inputs:
     description: Artifact label to include in the comment.
     required: false
     default: ''
+  repo-config-path:
+    description: Path to the SnapDrift config file (needed for provider-aware comment rendering).
+    required: false
+    default: .github/snapdrift.json
   max-changed-rows:
     description: Maximum number of changed-route rows shown in the PR comment before truncation.
     required: false
@@ -42,6 +46,7 @@ runs:
         VISUAL_DIFF_RUN_URL: ${{ inputs.run-url }}
         VISUAL_DIFF_ARTIFACT_NAME: ${{ inputs.artifact-name }}
         INPUT_PR_NUMBER: ${{ inputs.pr-number }}
+        REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
         MAX_ERROR_ROWS: ${{ inputs.max-error-rows }}
       with:
@@ -63,15 +68,29 @@ runs:
             return;
           }
 
-          const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
-          const { buildReportCommentBody, PR_COMMENT_MARKERS } = await import(pathToFileURL(modulePath));
+          const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
+          const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+          const prCommentModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
+          const { createProvider } = await import(pathToFileURL(providerModulePath));
+          const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+          const { PR_COMMENT_MARKERS } = await import(pathToFileURL(prCommentModulePath));
+
+          // Provider-loading block duplicated in actions/pr-diff/action.yml — keep in sync.
+          let provider;
+          try {
+            const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+            provider = createProvider(config.provider || 'local', config);
+          } catch (err) {
+            core.warning(`Could not load SnapDrift config; falling back to LocalProvider. ${err.message}`);
+            provider = createProvider('local');
+          }
 
           const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
           const runUrl = process.env.VISUAL_DIFF_RUN_URL || `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`;
 
           const maxChangedRows = Number(process.env.MAX_CHANGED_ROWS) || 20;
           const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
-          const body = buildReportCommentBody(summary, {
+          const body = provider.buildCommentBody(summary, {
             artifactName: process.env.VISUAL_DIFF_ARTIFACT_NAME || '',
             runUrl,
             maxChangedRows,

package/actions/pr-diff/action.yml

@@ -498,6 +498,7 @@ runs:
         SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
         ARTIFACT_NAME: ${{ steps.context.outputs.artifact_name }}
         RUN_URL: ${{ steps.context.outputs.run_url }}
+        REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
         MAX_ERROR_ROWS: ${{ inputs.max-error-rows }}
       with:
@@ -531,13 +532,25 @@ runs:
             return;
           }
 
-          const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
-          const { buildReportCommentBody } = await import(pathToFileURL(modulePath));
+          const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
+          const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+          const { createProvider } = await import(pathToFileURL(providerModulePath));
+          const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+
+          // Provider-loading block duplicated in actions/comment/action.yml — keep in sync.
+          let provider;
+          try {
+            const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+            provider = createProvider(config.provider || 'local', config);
+          } catch (err) {
+            core.warning(`Could not load SnapDrift config; falling back to LocalProvider. ${err.message}`);
+            provider = createProvider('local');
+          }
 
           const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
           const maxChangedRows = Number(process.env.MAX_CHANGED_ROWS) || 20;
           const maxErrorRows = Number(process.env.MAX_ERROR_ROWS) || 10;
-          const body = buildReportCommentBody(summary, {
+          const body = provider.buildCommentBody(summary, {
             artifactName: process.env.ARTIFACT_NAME || '',
             runUrl: process.env.RUN_URL || '',
             maxChangedRows,

package/docs/contracts.md

@@ -34,6 +34,12 @@ SnapDrift reads runtime behavior from `.github/snapdrift.json` by default.
 |:------|:-----|:------------|
 | `selection.sharedPrefixes` | `string[]` | Prefixes that force the full route set |
 | `selection.sharedExact` | `string[]` | Exact files that force the full route set |
+| `provider` | `string` | `"local"` (default) or `"snap"` for hosted backend |
+| `snap.apiUrl` | `string` | Snap API base URL (default: `https://snap.i2dev.com`) |
+| `snap.apiKeyEnv` | `string` | Env var name for API key (mutually exclusive with `snap.apiKey`) |
+| `snap.apiKey` | `string` | Inline API key with `${VAR}` interpolation (mutually exclusive with `snap.apiKeyEnv`) |
+| `snap.projectId` | `string` | Snap project ID or `"auto"` (default: `"auto"`, derives from `GITHUB_REPOSITORY`) |
+| `snap.onUnavailable` | `string` | Behavior when Snap is unreachable: `"fail"` (default), `"warn-and-skip"`, or `"fallback-local"` |
 
 ### Example
 
@@ -129,6 +135,12 @@ The pull request drift bundle contains:
 }
 ```
 
+### Optional summary fields
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `dashboardUrl` | `string?` | Snap dashboard URL for the run (set by `SnapProvider`; omitted by `LocalProvider`) |
+
 ### Status values
 
 | Status | Meaning |
@@ -180,9 +192,11 @@ Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
 
 | Setting | Value |
 |:--------|:------|
-| Navigation wait | `networkidle` |
+| Navigation wait | `load` |
 | Navigation timeout | 30000ms |
 | Settle delay | 300ms |
+| Screenshot animations | `disabled` (Playwright finishes/cancels CSS animations before capture) |
+| Capture concurrency | 5 routes per viewport (overridable via `SNAPDRIFT_CAPTURE_CONCURRENCY`)|
 
 ## Local CLI directory layout
 
@@ -206,6 +220,47 @@ When using the `snapdrift` CLI, outputs are written to `.snapdrift/` by default:
 
 All three directories can be overridden with `--baseline-dir`, `--current-dir`, and `--diff-dir`. See the [Local CLI guide](local-cli.md) for details.
 
+## Migration commands
+
+### migrate-baselines
+
+Migrate baselines between local storage and Snap.
+
+**Upload local baselines to Snap:**
+
+```
+snapdrift migrate-baselines --to snap [--config <path>] [--baseline-dir <dir>]
+```
+
+- Reads local manifest + baseline images from the baseline directory.
+- Uploads as the initial accepted baseline on Snap via `POST /v1/visual/projects/:id/baselines`.
+- Idempotent: skips upload if a baseline already exists with the matching commit SHA.
+- Requires snapdrift.json with `provider: "snap"` (or snap config).
+
+**Download Snap baselines to local:**
+
+```
+snapdrift migrate-baselines --to local --from snap [--accept-cross-engine] [--config <path>] [--baseline-dir <dir>]
+```
+
+- Downloads baselines from Snap's export endpoint.
+- Writes to the local baseline directory.
+- Without `--accept-cross-engine`: hard-errors if the exported baselines were captured by a different engine.
+- With `--accept-cross-engine`: overrides the engine name to `snapdrift-local` in the imported manifest (visual differences may occur).
+
+### init
+
+**Translate a Snap action workflow to snapdrift.json:**
+
+```
+snapdrift init --from-snap-action <workflow-yaml-path>
+```
+
+- Reads an existing Snap `github-action/` workflow YAML.
+- Translates Snap action inputs into `.github/snapdrift.json`.
+- Emits `.github/MIGRATION_NOTES.md` listing warnings and deferred decisions.
+- Idempotent: refuses to overwrite an existing `snapdrift.json`.
+
 ## Primary entrypoints
 
 - `actions/baseline`
@@ -232,3 +287,73 @@ These are for custom orchestration only. Wrapper actions set them automatically.
 | `SNAPDRIFT_BASELINE_ARTIFACT_NAME` | `compare-results.mjs` | Baseline artifact label to embed in the report |
 | `SNAPDRIFT_BASELINE_SOURCE_SHA` | `compare-results.mjs` | Baseline source SHA to embed in the report |
 | `SNAPDRIFT_ENFORCE_OUTCOME` | `compare-results.mjs` | Set to `0` to disable enforcement in direct CLI usage |
+| `SNAPDRIFT_CAPTURE_CONCURRENCY` | `capture-routes.mjs` | Max concurrent route captures per viewport context (positive integer, default `5`). Set to `1` to restore serial behaviour for apps with shared session/auth state. |
+
+## PR comment markdown shape
+
+The canonical PR comment is produced by `provider.buildCommentBody(summary, meta)` in `@snapdrift/adapter-report-md`. Both `LocalProvider` and `SnapProvider` emit byte-identical markdown for the same summary — the only provider-specific difference is the optional **"View in dashboard →"** link appended by `SnapProvider`.
+
+Snap's server-side notification posting should render the same template from the run summary JSON so that reviewers see a consistent format regardless of which provider produced the run.
+
+### Structure
+
+```
+<!-- snapdrift-report -->
+## {status-icon} SnapDrift Report — {status-label}
+
+| Signal | Count |
+|:-------|------:|
+| Drift signals | N |
+| Missing in baseline | N |
+| Missing in current capture | N |
+| Dimension shifts | N |
+
+> **Note:** {message}                           ← optional, when summary.message is set
+
+<details><summary>Error details</summary>       ← collapsible, only when errors exist
+| Route | Viewport | Error |
+|:------|:---------|:------|
+| route-id | viewport | error message |
+*...and N more* — [View full report →]({runUrl})  ← when errors exceed maxErrorRows
+</details>
+
+<details><summary>Drift signals</summary>       ← collapsible, only when changed routes exist
+| Route | Viewport | Mismatch |
+|:------|:---------|:---------|
+| route-id | viewport | X.XX% |
+*...and N more* — [View full report →]({runUrl})  ← when routes exceed maxChangedRows
+</details>
+
+<details open><summary>Dimension shifts — comparison skipped</summary>  ← auto-expanded, only when dimension shifts exist
+> SnapDrift detected a dimension shift …
+| Route | Viewport | Baseline | Current |
+|:------|:---------|:---------|:--------|
+| route-id | viewport | WxH | WxH |
+</details>
+
+<sub>SnapDrift · artifact `name` · baseline `name` · sha `abc1234` · [View run](url) · [View in dashboard →](url)</sub>
+                                                  ↑ LocalProvider omits "View in dashboard"
+
+<div align="right"><sub>Powered by <a href="…">SnapDrift</a></sub></div>
+```
+
+### Meta parameters
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `artifactName` | `string?` | PR diff artifact label |
+| `runUrl` | `string?` | GitHub Actions run URL (adds `[View run]` link) |
+| `dashboardUrl` | `string?` | Snap dashboard URL (adds `[View in dashboard →]` link; SnapProvider only) |
+| `maxChangedRows` | `number` | Max drift-signal rows before truncation (default 20) |
+| `maxErrorRows` | `number` | Max error rows before truncation (default 10) |
+
+### Update-in-place semantics
+
+Comments are identified by the `<!-- snapdrift-report -->` HTML marker. On re-run, the action finds the most recent matching comment and updates it in place. Duplicate markers from earlier runs are deleted.
+
+### Provider contract
+
+The `VisualProvider` interface requires `buildCommentBody(summary, meta?)`:
+
+- **`LocalProvider`** — delegates to `buildReportCommentBody` without a `dashboardUrl`.
+- **`SnapProvider`** — constructs `dashboardUrl` from `{apiUrl}/projects/{projectId}/runs/{lastRunId}` and passes it through.

package/lib/capture-routes.mjs

@@ -1,370 +1,4 @@
 // @ts-check
+// Re-exports from packages — this module is a thin shim.
 
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { chromium } from 'playwright';
-import pngjs from 'pngjs';
-
-import {
-  loadSnapdriftConfig,
-  readFirstDefinedEnv,
-  resolveFromWorkingDirectory,
-  selectConfiguredRoutes,
-  splitCommaList,
-  SNAPDRIFT_VIEWPORT_PRESETS,
-  SNAPDRIFT_NAVIGATION_TIMEOUT_MS,
-  SNAPDRIFT_SETTLE_DELAY_MS
-} from './snapdrift-config.mjs';
-
-const { PNG } = pngjs;
-
-/** @typedef {import('../types/visual-diff-types').VisualBaselineResults} BaselineResults */
-/** @typedef {import('../types/visual-diff-types').VisualBaselineRouteResult} BaselineRouteResult */
-/** @typedef {import('../types/visual-diff-types').VisualRegressionRouteConfig} SnapdriftRouteConfig */
-/** @typedef {import('../types/visual-diff-types').VisualScreenshotManifest} ScreenshotManifest */
-
-/**
- * @param {string} targetPath
- * @returns {Promise<void>}
- */
-async function ensureParentDirectory(targetPath) {
-  await fs.mkdir(path.dirname(targetPath), { recursive: true });
-}
-
-/**
- * @param {string} targetPath
- * @returns {Promise<void>}
- */
-async function ensureDirectory(targetPath) {
-  await fs.mkdir(targetPath, { recursive: true });
-}
-
-/**
- * Strips characters that could cause path traversal or produce invalid filenames.
- * @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, '');
-}
-
-/** @typedef {import('../types/visual-diff-types').VisualViewport} VisualViewport */
-
-/**
- * Returns a stable string key for a viewport value (preset name or custom dimensions).
- * @param {VisualViewport} viewport
- * @returns {string}
- */
-function viewportKey(viewport) {
-  return typeof viewport === 'string' ? viewport : `custom:${viewport.width}x${viewport.height}`;
-}
-
-/**
- * Returns a human-readable label for a viewport.
- * @param {VisualViewport} viewport
- * @returns {string}
- */
-function viewportLabel(viewport) {
-  return typeof viewport === 'string' ? viewport : `${viewport.width}x${viewport.height}`;
-}
-
-/**
- * Returns Playwright context options for a viewport.
- * @param {VisualViewport} viewport
- * @returns {import('playwright').BrowserContextOptions}
- */
-function viewportContextOptions(viewport) {
-  if (typeof viewport === 'string') {
-    const preset = SNAPDRIFT_VIEWPORT_PRESETS[viewport];
-    return {
-      viewport: { width: preset.width, height: preset.height },
-      deviceScaleFactor: preset.deviceScaleFactor,
-      isMobile: preset.isMobile,
-      hasTouch: preset.hasTouch
-    };
-  }
-  return {
-    viewport: { width: viewport.width, height: viewport.height },
-    deviceScaleFactor: 1,
-    isMobile: false,
-    hasTouch: false
-  };
-}
-
-/**
- * @param {import('playwright').Browser} browser
- * @returns {Promise<Map<'desktop' | 'mobile', import('playwright').BrowserContext>>}
- */
-async function createViewportContexts(browser) {
-  return new Map([
-    ['desktop', await browser.newContext({
-      viewport: { width: SNAPDRIFT_VIEWPORT_PRESETS.desktop.width, height: SNAPDRIFT_VIEWPORT_PRESETS.desktop.height },
-      deviceScaleFactor: SNAPDRIFT_VIEWPORT_PRESETS.desktop.deviceScaleFactor,
-      isMobile: SNAPDRIFT_VIEWPORT_PRESETS.desktop.isMobile,
-      hasTouch: SNAPDRIFT_VIEWPORT_PRESETS.desktop.hasTouch
-    })],
-    ['mobile', await browser.newContext({
-      viewport: { width: SNAPDRIFT_VIEWPORT_PRESETS.mobile.width, height: SNAPDRIFT_VIEWPORT_PRESETS.mobile.height },
-      deviceScaleFactor: SNAPDRIFT_VIEWPORT_PRESETS.mobile.deviceScaleFactor,
-      isMobile: SNAPDRIFT_VIEWPORT_PRESETS.mobile.isMobile,
-      hasTouch: SNAPDRIFT_VIEWPORT_PRESETS.mobile.hasTouch
-    })]
-  ]);
-}
-
-/**
- * @param {import('playwright').BrowserContext} context
- * @param {SnapdriftRouteConfig} route
- * @param {string} baseUrl
- * @param {string} screenshotsRoot
- * @returns {Promise<BaselineRouteResult & { manifestEntry?: ScreenshotManifest['screenshots'][number] }>}
- */
-async function captureRoute(context, route, baseUrl, screenshotsRoot) {
-  const startedAt = Date.now();
-
-  const page = await context.newPage();
-  try {
-    const targetUrl = new URL(route.path, baseUrl).toString();
-    await page.goto(targetUrl, {
-      waitUntil: 'networkidle',
-      timeout: route.navigationTimeout ?? SNAPDRIFT_NAVIGATION_TIMEOUT_MS
-    });
-    await page.waitForTimeout(SNAPDRIFT_SETTLE_DELAY_MS);
-
-    const imagePath = path.join('screenshots', `${sanitizeRouteId(route.id)}.png`);
-    const absoluteImagePath = path.join(screenshotsRoot, imagePath);
-    await ensureParentDirectory(absoluteImagePath);
-    const screenshotBuffer = await page.screenshot({
-      path: absoluteImagePath,
-      fullPage: true
-    });
-    const screenshot = PNG.sync.read(screenshotBuffer);
-
-    return {
-      id: route.id,
-      path: route.path,
-      viewport: route.viewport,
-      status: 'passed',
-      durationMs: Date.now() - startedAt,
-      imagePath,
-      width: screenshot.width,
-      height: screenshot.height,
-      manifestEntry: {
-        id: route.id,
-        path: route.path,
-        viewport: route.viewport,
-        imagePath,
-        width: screenshot.width,
-        height: screenshot.height
-      }
-    };
-  } catch (error) {
-    return {
-      id: route.id,
-      path: route.path,
-      viewport: route.viewport,
-      status: 'failed',
-      durationMs: Date.now() - startedAt,
-      error: error instanceof Error ? error.message : String(error)
-    };
-  } finally {
-    await page.close();
-  }
-}
-
-const CAPTURE_MAX_RETRIES = 1;
-
-/**
- * @param {import('playwright').BrowserContext} context
- * @param {SnapdriftRouteConfig} route
- * @param {string} baseUrl
- * @param {string} screenshotsRoot
- * @returns {Promise<BaselineRouteResult & { manifestEntry?: ScreenshotManifest['screenshots'][number] }>}
- */
-async function captureRouteWithRetry(context, route, baseUrl, screenshotsRoot) {
-  let result = await captureRoute(context, route, baseUrl, screenshotsRoot);
-  for (let attempt = 1; attempt <= CAPTURE_MAX_RETRIES && result.status !== 'passed'; attempt++) {
-    console.log(`[SnapDrift] Retrying route ${route.id} (attempt ${attempt + 1}/${CAPTURE_MAX_RETRIES + 1})...`);
-    result = await captureRoute(context, route, baseUrl, screenshotsRoot);
-  }
-  return result;
-}
-
-/**
- * Captures all routes for a single viewport context sequentially, logging progress.
- *
- * @param {import('playwright').BrowserContext} context
- * @param {Array<{ route: SnapdriftRouteConfig, originalIndex: number }>} entries
- * @param {string} baseUrl
- * @param {string} screenshotsRoot
- * @param {number} totalRoutes
- * @param {Array<BaselineRouteResult & { manifestEntry?: ScreenshotManifest['screenshots'][number] }>} out
- * @returns {Promise<void>}
- */
-async function captureViewportRoutes(context, entries, baseUrl, screenshotsRoot, totalRoutes, out) {
-  for (const { route, originalIndex } of entries) {
-    console.log(`[SnapDrift] Capturing route ${originalIndex + 1}/${totalRoutes}: ${route.id} (${viewportLabel(route.viewport)})`);
-    out[originalIndex] = await captureRouteWithRetry(context, route, baseUrl, screenshotsRoot);
-  }
-}
-
-/**
- * @param {{
- *   configPath?: string,
- *   routeIds?: Iterable<string>,
- *   outDir?: string
- * }} [options]
- * @returns {Promise<{ resultsPath: string, manifestPath: string, screenshotsRoot: string, selectedRouteIds: string[] }>}
- */
-export async function runBaselineCapture(options = {}) {
-  const requestedRouteIds = [...(
-    options.routeIds || splitCommaList(readFirstDefinedEnv(['SNAPDRIFT_ROUTE_IDS']))
-  )];
-  const { config, configPath } = await loadSnapdriftConfig(options.configPath);
-  const { routes, selectedRouteIds } = selectConfiguredRoutes(config, requestedRouteIds);
-
-  // When outDir is provided (e.g. by the local CLI), store all outputs flat inside that directory
-  // using just the basename of each configured path.  Otherwise, use the config-resolved paths.
-  const localOutDir = options.outDir ? path.resolve(options.outDir) : null;
-  const resultsPath = localOutDir
-    ? path.join(localOutDir, path.basename(config.resultsFile))
-    : resolveFromWorkingDirectory(config, config.resultsFile);
-  const manifestPath = localOutDir
-    ? path.join(localOutDir, path.basename(config.manifestFile))
-    : resolveFromWorkingDirectory(config, config.manifestFile);
-  const screenshotsRoot = localOutDir || resolveFromWorkingDirectory(config, config.screenshotsRoot);
-
-  // Screenshots are written to a `screenshots/` subdirectory inside screenshotsRoot,
-  // i.e. the actual PNG files land at `{screenshotsRoot}/screenshots/{id}.png`.
-  await Promise.all([
-    ensureParentDirectory(resultsPath),
-    ensureParentDirectory(manifestPath),
-    ensureDirectory(path.join(screenshotsRoot, 'screenshots'))
-  ]);
-
-  /** @type {BaselineResults} */
-  const results = {
-    startedAt: new Date().toISOString(),
-    baseUrl: config.baseUrl,
-    suite: 'snapdrift-capture',
-    configPath: path.relative(path.resolve('.'), configPath),
-    manifestPath: path.relative(path.resolve('.'), manifestPath),
-    screenshotsRoot: path.relative(path.resolve('.'), screenshotsRoot),
-    routes: []
-  };
-
-  /** @type {ScreenshotManifest} */
-  const manifest = {
-    generatedAt: new Date().toISOString(),
-    baseUrl: config.baseUrl,
-    screenshots: []
-  };
-
-  const browser = await chromium.launch({ headless: true });
-  // Pre-create contexts for the two standard presets; custom viewports are created on demand below.
-  const presetContexts = await createViewportContexts(browser);
-  /** @type {Map<string, import('playwright').BrowserContext>} */
-  const allContexts = new Map(presetContexts);
-  let failures = 0;
-
-  try {
-    // Group routes by viewport key, preserving each route's original index for result ordering.
-    /** @type {Map<string, Array<{ route: SnapdriftRouteConfig, originalIndex: number }>>} */
-    const byViewport = new Map();
-    for (const [i, route] of routes.entries()) {
-      const key = viewportKey(route.viewport);
-      const existing = byViewport.get(key);
-      if (existing) {
-        existing.push({ route, originalIndex: i });
-      } else {
-        byViewport.set(key, [{ route, originalIndex: i }]);
-      }
-    }
-
-    // Create browser contexts for any custom viewports not covered by presets.
-    for (const [key, entries] of byViewport) {
-      if (!allContexts.has(key)) {
-        try {
-          allContexts.set(key, await browser.newContext(viewportContextOptions(entries[0].route.viewport)));
-        } catch (err) {
-          const message = `Failed to create browser context: ${err instanceof Error ? err.message : String(err)}`;
-          for (const { route } of entries) {
-            results.routes.push({ id: route.id, path: route.path, viewport: route.viewport, status: 'failed', durationMs: 0, error: message });
-            failures += 1;
-          }
-          throw err;
-        }
-      }
-    }
-
-    // Pre-allocate results array; captureViewportRoutes fills slots by originalIndex.
-    /** @type {Array<BaselineRouteResult & { manifestEntry?: ScreenshotManifest['screenshots'][number] }>} */
-    const captureResults = new Array(routes.length);
-
-    // Run each viewport group concurrently; routes within a group stay sequential.
-    await Promise.all([...byViewport.entries()].map(([key, entries]) => {
-      const context = allContexts.get(key);
-      if (!context) {
-        throw new Error(`No browser context for viewport: ${key}`);
-      }
-      return captureViewportRoutes(context, entries, config.baseUrl, screenshotsRoot, routes.length, captureResults);
-    }));
-
-    // Merge results in original route order.
-    for (const capture of captureResults) {
-      results.routes.push({
-        id: capture.id,
-        path: capture.path,
-        viewport: capture.viewport,
-        status: capture.status,
-        durationMs: capture.durationMs,
-        imagePath: capture.imagePath,
-        width: capture.width,
-        height: capture.height,
-        error: capture.error
-      });
-      if (capture.manifestEntry) {
-        manifest.screenshots.push(capture.manifestEntry);
-      }
-      if (capture.status !== 'passed') {
-        failures += 1;
-      }
-    }
-  } finally {
-    await Promise.all([...allContexts.values()].map((context) => context.close()));
-    await browser.close();
-    results.finishedAt = new Date().toISOString();
-    results.passed = failures === 0;
-    manifest.generatedAt = new Date().toISOString();
-
-    await Promise.all([
-      fs.writeFile(resultsPath, JSON.stringify(results, null, 2)),
-      fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2))
-    ]);
-  }
-
-  if (failures > 0) {
-    throw new Error(`SnapDrift capture failed for ${failures} route(s).`);
-  }
-
-  return {
-    resultsPath,
-    manifestPath,
-    screenshotsRoot,
-    selectedRouteIds
-  };
-}
-
-const isDirectRun = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
-
-if (isDirectRun) {
-  runBaselineCapture().catch((error) => {
-    console.error(error);
-    process.exitCode = 1;
-  });
-}
+export { runBaselineCapture } from '@snapdrift/adapter-fs';