@scenar/cli 0.8.0 → 0.9.0

package/src/shoot/playwright-browser.ts

@@ -0,0 +1,121 @@
+import type { ShotBrowser, ShotCaptureInfo } from "./types.js";
+
+/**
+ * Chromium launch flags for byte-deterministic rasterization — every one
+ * proven necessary by the 2026-07-28 determinism spike (without them,
+ * ±1-LSB full-frame compositing jitter across sessions):
+ *
+ * - `--disable-gpu`: software rasterization, no GPU-dependent output.
+ * - `--force-color-profile=srgb`: pins color conversion.
+ * - `--disable-lcd-text`: subpixel AA depends on the (virtual) display.
+ * - `--hide-scrollbars`: platform scrollbar chrome is not content.
+ */
+const DETERMINISM_LAUNCH_FLAGS = [
+  "--disable-gpu",
+  "--force-color-profile=srgb",
+  "--disable-lcd-text",
+  "--hide-scrollbars",
+];
+
+const PLAYWRIGHT_INSTALL_HINT =
+  "Install it in your demos project: npm install -D playwright\n" +
+  "Then install the browser binary: npx playwright install chromium";
+
+/**
+ * The real {@link ShotBrowser}: Playwright Chromium with the full spike
+ * determinism recipe. Playwright is an optional peer dependency (the
+ * remotion/echogarden pattern) — loaded lazily so every other command works
+ * without it, and failing with install instructions when absent.
+ */
+export async function createPlaywrightShotBrowser(): Promise<ShotBrowser> {
+  const playwright = await import("playwright").catch(() => {
+    throw new Error(`Could not load playwright.\n${PLAYWRIGHT_INSTALL_HINT}`);
+  });
+
+  const browser = await playwright.chromium
+    .launch({ args: DETERMINISM_LAUNCH_FLAGS })
+    .catch((error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Could not launch Chromium.\n${message}\n\n${PLAYWRIGHT_INSTALL_HINT}`,
+      );
+    });
+
+  return {
+    async newSession({ theme, viewport }) {
+      // `reducedMotion: "reduce"` is safe under a TimeSource: step index
+      // derives from time, not from the reduced-motion shortcut — and it
+      // keeps framer-motion from animating on wall-clock time.
+      // `colorScheme` emulation resolves the stage backdrop's light-dark()
+      // colors; the `?theme=` param handles the scenar token class — both
+      // halves are required for a correct dark variant (DD-02 D2).
+      const context = await browser.newContext({
+        viewport,
+        deviceScaleFactor: 2,
+        reducedMotion: "reduce",
+        colorScheme: theme,
+      });
+      const page = await context.newPage();
+      let frameSelector = "";
+
+      return {
+        async open(url, timeoutMs) {
+          await page.goto(url, { waitUntil: "networkidle" });
+          await page.waitForFunction(
+            () =>
+              (window as { __scenarShot?: unknown }).__scenarShot !== undefined ||
+              (window as { __scenarShotError?: unknown }).__scenarShotError !== undefined,
+            undefined,
+            { timeout: timeoutMs },
+          );
+          const result: { error: string | null } & ShotCaptureInfo = await page.evaluate(() => {
+            const w = window as unknown as {
+              __scenarShot?: { shots: ShotCaptureInfo["shots"]; frameSelector: string };
+              __scenarShotError?: string;
+            };
+            if (w.__scenarShotError !== undefined) {
+              return { error: String(w.__scenarShotError), shots: [], frameSelector: "" };
+            }
+            const driver = w.__scenarShot!;
+            return { error: null, shots: driver.shots, frameSelector: driver.frameSelector };
+          });
+          if (result.error !== null) {
+            throw new Error(`the capture page reported: ${result.error}`);
+          }
+          // Webfont rasterization differs from the fallback font — never
+          // shoot before every declared font face has loaded.
+          await page.evaluate(() => document.fonts.ready.then(() => undefined));
+          frameSelector = result.frameSelector;
+          return { shots: result.shots, frameSelector: result.frameSelector };
+        },
+
+        async walkTo(timeMs) {
+          await page.evaluate(
+            (ms) =>
+              (
+                window as unknown as {
+                  __scenarShot: { walkTo: (t: number) => Promise<void> };
+                }
+              ).__scenarShot.walkTo(ms),
+            timeMs,
+          );
+        },
+
+        async screenshotFrame() {
+          // `animations: "disabled"` is load-bearing: the shells crossfade
+          // content on wall-clock CSS time, and this alone caused whole-pane
+          // noise in the spike until disabled at screenshot time.
+          return page.locator(frameSelector).screenshot({ animations: "disabled" });
+        },
+
+        async close() {
+          await context.close();
+        },
+      };
+    },
+
+    async close() {
+      await browser.close();
+    },
+  };
+}

package/src/shoot/run-shoot.d.ts

@@ -0,0 +1,52 @@
+import type { ShotBrowser, ShotCaptureInfo, ShotTheme } from "./types.js";
+/** Directory inside the bundle where stills land (and deploy from). */
+export declare const STILLS_DIR = "stills";
+/** Options for {@link runShoot}. Paths may be relative; they are resolved here. */
+export interface RunShootOptions {
+    /** A packed bundle directory (a `scenar pack` output with a ?shot entry). */
+    readonly bundleDir: string;
+    /** Themes to capture (default: both — DD-02 D2). */
+    readonly themes?: readonly ShotTheme[];
+    /**
+     * Capture everything twice in fresh browser sessions and byte-compare —
+     * the determinism gate. A mismatch means some component renders
+     * nondeterministically and the stills cannot be trusted.
+     */
+    readonly verify?: boolean;
+    /** Per-page readiness timeout in ms (default {@link DEFAULT_TIMEOUT_MS}). */
+    readonly timeoutMs?: number;
+    /** Progress sink for mid-operation messages. */
+    readonly onLog?: (message: string) => void;
+    /** Test seam: swap the real Playwright browser for a fake. */
+    readonly browserFactory?: () => Promise<ShotBrowser>;
+}
+/** The outcome of a successful shoot. */
+export interface ShootResult {
+    readonly scenarioId: string;
+    readonly bundleDir: string;
+    /** The bundle's declared shots, in timeline order (empty = nothing to do). */
+    readonly shots: ShotCaptureInfo["shots"];
+    /** Bundle-relative paths of the stills written, in write order. */
+    readonly files: readonly string[];
+    readonly themes: readonly ShotTheme[];
+    /** True when `verify` ran and every still was byte-identical. */
+    readonly verified: boolean;
+}
+/**
+ * Render a packed bundle's declared shots to still images — the pure
+ * orchestration behind `scenar shoot`, with no process/exit coupling so both
+ * the CLI command and the MCP server can call it.
+ *
+ * Bundle-centric by design: stills are captured from (and written into) the
+ * exact bundle that deploys, so they can never depict anything but what
+ * ships. The pack manifest is rebuilt afterwards so `publish`/deploy pick
+ * the stills up with zero pipeline changes.
+ *
+ * `stills/` is cleared up front, unconditionally — even when the scenario
+ * declares no shots — and the manifest is rebuilt in every path. A removed
+ * or renamed shot must never linger in a deployed bundle, and a manifest
+ * listing deleted files would fail its own existence check at the next
+ * publish.
+ */
+export declare function runShoot(options: RunShootOptions): Promise<ShootResult>;
+//# sourceMappingURL=run-shoot.d.ts.map

package/src/shoot/run-shoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-shoot.d.ts","sourceRoot":"","sources":["../../../src/shoot/run-shoot.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAe,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvF,uEAAuE;AACvE,eAAO,MAAM,UAAU,WAAW,CAAC;AAWnC,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;CACtD;AAED,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IACzC,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CA0E7E"}

package/src/shoot/run-shoot.js

@@ -0,0 +1,172 @@
+import { join, resolve } from "node:path";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { PACK_MANIFEST_FILE, SCENARIO_JSON_FILE, buildPackManifest, verifyManifestFilesExist, writePackManifest, } from "../pack/pack-manifest.js";
+import { readBundleViewport } from "../bundle/read-viewport.js";
+import { startBundleServer } from "../serve/static-server.js";
+import { createPlaywrightShotBrowser } from "./playwright-browser.js";
+/** Directory inside the bundle where stills land (and deploy from). */
+export const STILLS_DIR = "stills";
+/** How long to wait for the capture page's driver before failing. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Extra room around the canonical frame so the element screenshot never has
+ * to scroll-stitch (stitching re-rasterizes and would break byte-exactness).
+ */
+const VIEWPORT_MARGIN_PX = 64;
+/**
+ * Render a packed bundle's declared shots to still images — the pure
+ * orchestration behind `scenar shoot`, with no process/exit coupling so both
+ * the CLI command and the MCP server can call it.
+ *
+ * Bundle-centric by design: stills are captured from (and written into) the
+ * exact bundle that deploys, so they can never depict anything but what
+ * ships. The pack manifest is rebuilt afterwards so `publish`/deploy pick
+ * the stills up with zero pipeline changes.
+ *
+ * `stills/` is cleared up front, unconditionally — even when the scenario
+ * declares no shots — and the manifest is rebuilt in every path. A removed
+ * or renamed shot must never linger in a deployed bundle, and a manifest
+ * listing deleted files would fail its own existence check at the next
+ * publish.
+ */
+export async function runShoot(options) {
+    const onLog = options.onLog ?? (() => { });
+    const bundleDir = resolve(options.bundleDir);
+    const themes = options.themes ?? ["light", "dark"];
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const scenarioId = await validateBundle(bundleDir);
+    const { viewport } = await readBundleViewport(bundleDir);
+    onLog(`Scenario:  ${scenarioId}`);
+    onLog(`Bundle:    ${bundleDir}`);
+    onLog(`Viewport:  ${viewport.width}x${viewport.height} (DPR 2)`);
+    onLog(`Themes:    ${themes.join(", ")}`);
+    await rm(join(bundleDir, STILLS_DIR), { recursive: true, force: true });
+    const server = await startBundleServer({ rootDir: bundleDir, port: 0 });
+    let browser;
+    try {
+        browser = await (options.browserFactory ?? createPlaywrightShotBrowser)();
+        const sessionViewport = {
+            width: viewport.width + VIEWPORT_MARGIN_PX,
+            height: viewport.height + VIEWPORT_MARGIN_PX,
+        };
+        const captures = new Map();
+        for (const theme of themes) {
+            captures.set(theme, await captureTheme(browser, server.url, theme, sessionViewport, timeoutMs));
+        }
+        const first = captures.get(themes[0]).info;
+        assertShotsAgreeAcrossThemes(captures);
+        if (first.shots.length === 0) {
+            onLog("No steps declare a `shot` — nothing to capture.");
+            await rebuildManifest(bundleDir, scenarioId);
+            return { scenarioId, bundleDir, shots: [], files: [], themes, verified: false };
+        }
+        if (options.verify) {
+            onLog("Verifying determinism (second capture in fresh sessions)...");
+            for (const theme of themes) {
+                const rerun = await captureTheme(browser, server.url, theme, sessionViewport, timeoutMs);
+                assertByteIdentical(theme, captures.get(theme), rerun);
+            }
+            onLog(`Determinism verified: every still byte-identical across sessions.`);
+        }
+        await mkdir(join(bundleDir, STILLS_DIR), { recursive: true });
+        const files = [];
+        for (const theme of themes) {
+            const { info, images } = captures.get(theme);
+            for (const [i, shot] of info.shots.entries()) {
+                const relative = `${STILLS_DIR}/${shot.name}.${theme}.png`;
+                await writeFile(join(bundleDir, ...relative.split("/")), images[i]);
+                files.push(relative);
+                onLog(`Captured:  ${relative}`);
+            }
+        }
+        await rebuildManifest(bundleDir, scenarioId);
+        return {
+            scenarioId,
+            bundleDir,
+            shots: first.shots,
+            files,
+            themes,
+            verified: options.verify ?? false,
+        };
+    }
+    finally {
+        await browser?.close().catch(() => { });
+        await server.close().catch(() => { });
+    }
+}
+/** Walk one themed session through every shot, collecting screenshots. */
+async function captureTheme(browser, baseUrl, theme, viewport, timeoutMs) {
+    // `?shot` (bare) switches the packed entry into capture mode; the scenar
+    // token class needs `theme=dark` on top of the context's colorScheme
+    // emulation — both halves of a dark variant (DD-02 D2).
+    const url = `${baseUrl}?shot${theme === "dark" ? "&theme=dark" : ""}`;
+    const session = await browser.newSession({ theme, viewport });
+    try {
+        const info = await session.open(url, timeoutMs);
+        const images = [];
+        // Sequential walk in timeline order — never a cold jump (cross-step
+        // React state does not survive one; spike-proven, DD-02).
+        for (const shot of info.shots) {
+            await session.walkTo(shot.timeMs);
+            images.push(await session.screenshotFrame());
+        }
+        return { info, images };
+    }
+    finally {
+        await session.close().catch(() => { });
+    }
+}
+/** A bundle is shootable when it has the three files `scenar pack` writes. */
+async function validateBundle(bundleDir) {
+    const info = await stat(bundleDir).catch(() => null);
+    if (!info || !info.isDirectory()) {
+        throw new Error(`${bundleDir} is not a directory. Pass a bundle produced by \`scenar pack\`.`);
+    }
+    for (const required of ["index.html", SCENARIO_JSON_FILE, PACK_MANIFEST_FILE]) {
+        const fileInfo = await stat(join(bundleDir, required)).catch(() => null);
+        if (!fileInfo || !fileInfo.isFile()) {
+            throw new Error(`no ${required} in ${bundleDir}. Run \`scenar pack\` to produce a shootable bundle first.`);
+        }
+    }
+    const scenarioJson = JSON.parse(await readFile(join(bundleDir, SCENARIO_JSON_FILE), "utf-8"));
+    if (typeof scenarioJson.id !== "string" || scenarioJson.id.length === 0) {
+        throw new Error(`${SCENARIO_JSON_FILE} in ${bundleDir} has no scenario id.`);
+    }
+    return scenarioJson.id;
+}
+/**
+ * The shot list is derived from the bundled steps, so every theme must
+ * report the identical list — a divergence means the bundle itself renders
+ * nondeterministically and nothing downstream can be trusted.
+ */
+function assertShotsAgreeAcrossThemes(captures) {
+    const lists = [...captures.entries()].map(([theme, { info }]) => [theme, JSON.stringify(info.shots)]);
+    const [, reference] = lists[0];
+    for (const [theme, list] of lists) {
+        if (list !== reference) {
+            throw new Error(`internal error: the ${theme} capture reported a different shot list than ${lists[0][0]}`);
+        }
+    }
+}
+/** Byte-compare two capture passes of the same theme (the `--verify` gate). */
+function assertByteIdentical(theme, first, second) {
+    const differing = first.info.shots
+        .filter((_, i) => !first.images[i].equals(second.images[i]))
+        .map((shot) => shot.name);
+    if (differing.length > 0) {
+        throw new Error(`determinism check failed (${theme}): shot(s) ${differing.join(", ")} differed ` +
+            `across fresh sessions. Some component renders nondeterministically — ` +
+            `fix that before trusting these stills (see DD-02's determinism recipe).`);
+    }
+}
+/**
+ * Re-list the bundle after stills changed. `buildPackManifest` validates
+ * every file against the deploy allowlist, so a bad shot filename fails
+ * here, locally, rather than mid-upload.
+ */
+async function rebuildManifest(bundleDir, scenarioId) {
+    const manifest = await buildPackManifest(bundleDir, scenarioId);
+    await verifyManifestFilesExist(bundleDir, manifest);
+    await writePackManifest(bundleDir, manifest);
+}
+//# sourceMappingURL=run-shoot.js.map

package/src/shoot/run-shoot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-shoot.js","sourceRoot":"","sources":["../../../src/shoot/run-shoot.ts"],"names":[],"mappings":"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"}

package/src/shoot/run-shoot.ts

@@ -0,0 +1,251 @@
+import { join, resolve } from "node:path";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import {
+  PACK_MANIFEST_FILE,
+  SCENARIO_JSON_FILE,
+  buildPackManifest,
+  verifyManifestFilesExist,
+  writePackManifest,
+} from "../pack/pack-manifest.js";
+import { readBundleViewport } from "../bundle/read-viewport.js";
+import { startBundleServer } from "../serve/static-server.js";
+import { createPlaywrightShotBrowser } from "./playwright-browser.js";
+import type { ShotBrowser, ShotCaptureInfo, ShotSession, ShotTheme } from "./types.js";
+
+/** Directory inside the bundle where stills land (and deploy from). */
+export const STILLS_DIR = "stills";
+
+/** How long to wait for the capture page's driver before failing. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Extra room around the canonical frame so the element screenshot never has
+ * to scroll-stitch (stitching re-rasterizes and would break byte-exactness).
+ */
+const VIEWPORT_MARGIN_PX = 64;
+
+/** Options for {@link runShoot}. Paths may be relative; they are resolved here. */
+export interface RunShootOptions {
+  /** A packed bundle directory (a `scenar pack` output with a ?shot entry). */
+  readonly bundleDir: string;
+  /** Themes to capture (default: both — DD-02 D2). */
+  readonly themes?: readonly ShotTheme[];
+  /**
+   * Capture everything twice in fresh browser sessions and byte-compare —
+   * the determinism gate. A mismatch means some component renders
+   * nondeterministically and the stills cannot be trusted.
+   */
+  readonly verify?: boolean;
+  /** Per-page readiness timeout in ms (default {@link DEFAULT_TIMEOUT_MS}). */
+  readonly timeoutMs?: number;
+  /** Progress sink for mid-operation messages. */
+  readonly onLog?: (message: string) => void;
+  /** Test seam: swap the real Playwright browser for a fake. */
+  readonly browserFactory?: () => Promise<ShotBrowser>;
+}
+
+/** The outcome of a successful shoot. */
+export interface ShootResult {
+  readonly scenarioId: string;
+  readonly bundleDir: string;
+  /** The bundle's declared shots, in timeline order (empty = nothing to do). */
+  readonly shots: ShotCaptureInfo["shots"];
+  /** Bundle-relative paths of the stills written, in write order. */
+  readonly files: readonly string[];
+  readonly themes: readonly ShotTheme[];
+  /** True when `verify` ran and every still was byte-identical. */
+  readonly verified: boolean;
+}
+
+/**
+ * Render a packed bundle's declared shots to still images — the pure
+ * orchestration behind `scenar shoot`, with no process/exit coupling so both
+ * the CLI command and the MCP server can call it.
+ *
+ * Bundle-centric by design: stills are captured from (and written into) the
+ * exact bundle that deploys, so they can never depict anything but what
+ * ships. The pack manifest is rebuilt afterwards so `publish`/deploy pick
+ * the stills up with zero pipeline changes.
+ *
+ * `stills/` is cleared up front, unconditionally — even when the scenario
+ * declares no shots — and the manifest is rebuilt in every path. A removed
+ * or renamed shot must never linger in a deployed bundle, and a manifest
+ * listing deleted files would fail its own existence check at the next
+ * publish.
+ */
+export async function runShoot(options: RunShootOptions): Promise<ShootResult> {
+  const onLog = options.onLog ?? (() => {});
+  const bundleDir = resolve(options.bundleDir);
+  const themes = options.themes ?? (["light", "dark"] as const);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  const scenarioId = await validateBundle(bundleDir);
+  const { viewport } = await readBundleViewport(bundleDir);
+
+  onLog(`Scenario:  ${scenarioId}`);
+  onLog(`Bundle:    ${bundleDir}`);
+  onLog(`Viewport:  ${viewport.width}x${viewport.height} (DPR 2)`);
+  onLog(`Themes:    ${themes.join(", ")}`);
+
+  await rm(join(bundleDir, STILLS_DIR), { recursive: true, force: true });
+
+  const server = await startBundleServer({ rootDir: bundleDir, port: 0 });
+  let browser: ShotBrowser | undefined;
+  try {
+    browser = await (options.browserFactory ?? createPlaywrightShotBrowser)();
+
+    const sessionViewport = {
+      width: viewport.width + VIEWPORT_MARGIN_PX,
+      height: viewport.height + VIEWPORT_MARGIN_PX,
+    };
+
+    const captures = new Map<ShotTheme, { info: ShotCaptureInfo; images: Buffer[] }>();
+    for (const theme of themes) {
+      captures.set(theme, await captureTheme(browser, server.url, theme, sessionViewport, timeoutMs));
+    }
+
+    const first = captures.get(themes[0]!)!.info;
+    assertShotsAgreeAcrossThemes(captures);
+
+    if (first.shots.length === 0) {
+      onLog("No steps declare a `shot` — nothing to capture.");
+      await rebuildManifest(bundleDir, scenarioId);
+      return { scenarioId, bundleDir, shots: [], files: [], themes, verified: false };
+    }
+
+    if (options.verify) {
+      onLog("Verifying determinism (second capture in fresh sessions)...");
+      for (const theme of themes) {
+        const rerun = await captureTheme(browser, server.url, theme, sessionViewport, timeoutMs);
+        assertByteIdentical(theme, captures.get(theme)!, rerun);
+      }
+      onLog(`Determinism verified: every still byte-identical across sessions.`);
+    }
+
+    await mkdir(join(bundleDir, STILLS_DIR), { recursive: true });
+    const files: string[] = [];
+    for (const theme of themes) {
+      const { info, images } = captures.get(theme)!;
+      for (const [i, shot] of info.shots.entries()) {
+        const relative = `${STILLS_DIR}/${shot.name}.${theme}.png`;
+        await writeFile(join(bundleDir, ...relative.split("/")), images[i]!);
+        files.push(relative);
+        onLog(`Captured:  ${relative}`);
+      }
+    }
+
+    await rebuildManifest(bundleDir, scenarioId);
+    return {
+      scenarioId,
+      bundleDir,
+      shots: first.shots,
+      files,
+      themes,
+      verified: options.verify ?? false,
+    };
+  } finally {
+    await browser?.close().catch(() => {});
+    await server.close().catch(() => {});
+  }
+}
+
+/** Walk one themed session through every shot, collecting screenshots. */
+async function captureTheme(
+  browser: ShotBrowser,
+  baseUrl: string,
+  theme: ShotTheme,
+  viewport: { width: number; height: number },
+  timeoutMs: number,
+): Promise<{ info: ShotCaptureInfo; images: Buffer[] }> {
+  // `?shot` (bare) switches the packed entry into capture mode; the scenar
+  // token class needs `theme=dark` on top of the context's colorScheme
+  // emulation — both halves of a dark variant (DD-02 D2).
+  const url = `${baseUrl}?shot${theme === "dark" ? "&theme=dark" : ""}`;
+  const session: ShotSession = await browser.newSession({ theme, viewport });
+  try {
+    const info = await session.open(url, timeoutMs);
+    const images: Buffer[] = [];
+    // Sequential walk in timeline order — never a cold jump (cross-step
+    // React state does not survive one; spike-proven, DD-02).
+    for (const shot of info.shots) {
+      await session.walkTo(shot.timeMs);
+      images.push(await session.screenshotFrame());
+    }
+    return { info, images };
+  } finally {
+    await session.close().catch(() => {});
+  }
+}
+
+/** A bundle is shootable when it has the three files `scenar pack` writes. */
+async function validateBundle(bundleDir: string): Promise<string> {
+  const info = await stat(bundleDir).catch(() => null);
+  if (!info || !info.isDirectory()) {
+    throw new Error(`${bundleDir} is not a directory. Pass a bundle produced by \`scenar pack\`.`);
+  }
+  for (const required of ["index.html", SCENARIO_JSON_FILE, PACK_MANIFEST_FILE]) {
+    const fileInfo = await stat(join(bundleDir, required)).catch(() => null);
+    if (!fileInfo || !fileInfo.isFile()) {
+      throw new Error(
+        `no ${required} in ${bundleDir}. Run \`scenar pack\` to produce a shootable bundle first.`,
+      );
+    }
+  }
+  const scenarioJson = JSON.parse(
+    await readFile(join(bundleDir, SCENARIO_JSON_FILE), "utf-8"),
+  ) as { id?: unknown };
+  if (typeof scenarioJson.id !== "string" || scenarioJson.id.length === 0) {
+    throw new Error(`${SCENARIO_JSON_FILE} in ${bundleDir} has no scenario id.`);
+  }
+  return scenarioJson.id;
+}
+
+/**
+ * The shot list is derived from the bundled steps, so every theme must
+ * report the identical list — a divergence means the bundle itself renders
+ * nondeterministically and nothing downstream can be trusted.
+ */
+function assertShotsAgreeAcrossThemes(
+  captures: Map<ShotTheme, { info: ShotCaptureInfo; images: Buffer[] }>,
+): void {
+  const lists = [...captures.entries()].map(
+    ([theme, { info }]) => [theme, JSON.stringify(info.shots)] as const,
+  );
+  const [, reference] = lists[0]!;
+  for (const [theme, list] of lists) {
+    if (list !== reference) {
+      throw new Error(
+        `internal error: the ${theme} capture reported a different shot list than ${lists[0]![0]}`,
+      );
+    }
+  }
+}
+
+/** Byte-compare two capture passes of the same theme (the `--verify` gate). */
+function assertByteIdentical(
+  theme: ShotTheme,
+  first: { info: ShotCaptureInfo; images: Buffer[] },
+  second: { info: ShotCaptureInfo; images: Buffer[] },
+): void {
+  const differing = first.info.shots
+    .filter((_, i) => !first.images[i]!.equals(second.images[i]!))
+    .map((shot) => shot.name);
+  if (differing.length > 0) {
+    throw new Error(
+      `determinism check failed (${theme}): shot(s) ${differing.join(", ")} differed ` +
+        `across fresh sessions. Some component renders nondeterministically — ` +
+        `fix that before trusting these stills (see DD-02's determinism recipe).`,
+    );
+  }
+}
+
+/**
+ * Re-list the bundle after stills changed. `buildPackManifest` validates
+ * every file against the deploy allowlist, so a bad shot filename fails
+ * here, locally, rather than mid-upload.
+ */
+async function rebuildManifest(bundleDir: string, scenarioId: string): Promise<void> {
+  const manifest = await buildPackManifest(bundleDir, scenarioId);
+  await verifyManifestFilesExist(bundleDir, manifest);
+  await writePackManifest(bundleDir, manifest);
+}

package/src/shoot/types.d.ts

@@ -0,0 +1,40 @@
+import type { ScenarioShot } from "@scenar/core";
+/** The two capture themes — every shot is rendered once per theme (DD-02 D2). */
+export type ShotTheme = "light" | "dark";
+/** What the capture page reports once its driver is ready. */
+export interface ShotCaptureInfo {
+    /** The bundle's declared shots, validated and in timeline order. */
+    readonly shots: readonly ScenarioShot[];
+    /** Selector for the element to screenshot (owned by the capture mount). */
+    readonly frameSelector: string;
+}
+/**
+ * One themed browser page driving a capture — the narrow seam between
+ * run-shoot's orchestration (unit-tested against a fake) and Playwright
+ * (exercised by the real end-to-end capture, not by unit tests).
+ */
+export interface ShotSession {
+    /**
+     * Navigate to the capture URL and wait for the page to report either a
+     * ready driver or an error (`window.__scenarShot` / `__scenarShotError`).
+     * Throws with the page's own message on a reported error or on timeout.
+     */
+    open(url: string, timeoutMs: number): Promise<ShotCaptureInfo>;
+    /** Advance the page's TimeSource walk to `timeMs` (sequential, never back). */
+    walkTo(timeMs: number): Promise<void>;
+    /** Screenshot the capture frame, animations disabled. */
+    screenshotFrame(): Promise<Buffer>;
+    close(): Promise<void>;
+}
+/** A launched capture browser that can open themed sessions. */
+export interface ShotBrowser {
+    newSession(options: {
+        theme: ShotTheme;
+        viewport: {
+            width: number;
+            height: number;
+        };
+    }): Promise<ShotSession>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/src/shoot/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/shoot/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAEzC,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC/D,+EAA+E;IAC/E,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,yDAAyD;IACzD,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,OAAO,EAAE;QAClB,KAAK,EAAE,SAAS,CAAC;QACjB,QAAQ,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;KAC7C,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/src/shoot/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/src/shoot/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/shoot/types.ts"],"names":[],"mappings":""}