@scenar/cli 0.8.0 → 0.9.1

package/src/shoot/playwright-browser.js

@@ -0,0 +1,92 @@
+/**
+ * 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() {
+    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) => {
+        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.__scenarShot !== undefined ||
+                        window.__scenarShotError !== undefined, undefined, { timeout: timeoutMs });
+                    const result = await page.evaluate(() => {
+                        const w = window;
+                        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.__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();
+        },
+    };
+}
+//# sourceMappingURL=playwright-browser.js.map

package/src/shoot/playwright-browser.js.map

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

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,58 @@
+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.
+ *
+ * When scenario.json records an authoritatively empty shot list (pack ≥
+ * generator 0.0.2), the whole server + browser boot is skipped — both
+ * invariants above still hold on that path. A recorded non-empty list does
+ * NOT bypass the capture page: the running bundle stays the runtime truth
+ * for what gets shot; the record only proves there is something to boot for.
+ */
+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":"AAaA,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;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAsF7E"}

package/src/shoot/run-shoot.js

@@ -0,0 +1,190 @@
+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 { readBundleShots } from "../bundle/read-shots.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.
+ *
+ * When scenario.json records an authoritatively empty shot list (pack ≥
+ * generator 0.0.2), the whole server + browser boot is skipped — both
+ * invariants above still hold on that path. A recorded non-empty list does
+ * NOT bypass the capture page: the running bundle stays the runtime truth
+ * for what gets shot; the record only proves there is something to boot for.
+ */
+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 });
+    // Short-circuit on pack's authority: a recorded-and-empty shot list means
+    // there is provably nothing to capture, so don't pay for a static server
+    // and a Chromium launch just to learn that. Absent record = unknown — fall
+    // through and let the capture page answer, exactly as before the record
+    // existed.
+    const recordedShots = await readBundleShots(bundleDir);
+    if (recordedShots.recorded && recordedShots.shots.length === 0) {
+        onLog("No steps declare a `shot` — nothing to capture.");
+        await rebuildManifest(bundleDir, scenarioId);
+        return { scenarioId, bundleDir, shots: [], files: [], themes, verified: false };
+    }
+    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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"}