snapdrift 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,24 @@
 # Changelog
 
-## Unreleased
+## 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/docs/contracts.md

@@ -180,9 +180,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
 
@@ -232,3 +234,4 @@ 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. |

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';

package/lib/cli.mjs

@@ -4,10 +4,9 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { runBaselineCapture } from './capture-routes.mjs';
-import { generateDriftReport, shouldFailDriftCheck } from './compare-results.mjs';
+import { runBaselineCapture, generateDriftReport, loadSnapdriftConfig } from '@snapdrift/adapter-fs';
+import { shouldFailDriftCheck } from '@snapdrift/manifest';
 import { generateHtmlReport } from './report.mjs';
-import { loadSnapdriftConfig } from './snapdrift-config.mjs';
 
 /** @typedef {import('../types/visual-diff-types').VisualDiffSummary} DriftSummary */
 
@@ -95,10 +94,10 @@ export function printSummary(summary) {
 
   const statusIcon =
     summary.status === 'clean'
-      ? '\u2705' // ✅
+      ? '✅' // ✅
       : summary.status === 'changes-detected'
-        ? '\uD83D\uDFE1' // 🟡
-        : '\u274C'; // ❌
+        ? '🟡' // 🟡
+        : '❌'; // ❌
   const statusLabel =
     summary.status === 'clean'
       ? 'Clean'
@@ -106,7 +105,7 @@ export function printSummary(summary) {
         ? 'Drift detected'
         : summary.status ?? 'Unknown';
 
-  process.stdout.write(`\n${statusIcon}  SnapDrift \u2014 ${statusLabel}\n`);
+  process.stdout.write(`\n${statusIcon}  SnapDrift — ${statusLabel}\n`);
   process.stdout.write(`   Routes:   ${total}\n`);
   process.stdout.write(`   Matched:  ${matched}\n`);
   if (changed > 0) process.stdout.write(`   Changed:  ${changed}\n`);
@@ -118,7 +117,7 @@ export function printSummary(summary) {
     process.stdout.write('\n   Changed routes:\n');
     for (const item of summary.changed) {
       const pct = ((item.mismatchRatio ?? 0) * 100).toFixed(2);
-      process.stdout.write(`     \u2022 ${item.id} (${pct}% diff)\n`);
+      process.stdout.write(`     • ${item.id} (${pct}% diff)\n`);
     }
   }
 
@@ -238,4 +237,4 @@ export async function main(argv) {
     );
     process.exitCode = 1;
   }
-}
+}