@scenar/cli 0.8.0 → 0.9.1

package/src/shoot/run-shoot.ts

@@ -0,0 +1,270 @@
+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";
+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.
+ *
+ * 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: 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 });
+
+  // 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: 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":""}

package/src/shoot/types.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>;
+}

package/src/util/load-ts.d.ts

@@ -7,10 +7,20 @@ export interface ImportedStep {
     delayMs: number;
     narration?: string;
 }
+/**
+ * Find the steps array in a loaded module's exports by duck-typing: the
+ * first exported array whose first element has a `delayMs` property.
+ * Returns null when the module exports no such array.
+ *
+ * This is THE steps-discovery rule, shared by every Node-side loader and
+ * mirrored verbatim by the browser-side `_findSteps` in the generated
+ * pack entry (see generate-embed-entry.ts) — the mirrors must agree, or
+ * pack-time tooling would see different steps than the packed bundle.
+ */
+export declare function findStepsArray(exports: Record<string, unknown>): ImportedStep[] | null;
 /**
  * Dynamically import a TypeScript steps file and extract the
- * steps array by duck-typing (looks for the first exported array
- * whose elements have a `delayMs` property).
+ * steps array by duck-typing ({@link findStepsArray}).
  *
  * Requires the caller's Node process to have a TypeScript loader
  * active (e.g. running via `tsx`). The CLI itself does not depend

package/src/util/load-ts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-ts.d.ts","sourceRoot":"","sources":["../../../src/util/load-ts.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAiB/E"}
+{"version":3,"file":"load-ts.d.ts","sourceRoot":"","sources":["../../../src/util/load-ts.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,EAAE,GAAG,IAAI,CAatF;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAO/E"}

package/src/util/load-ts.js

@@ -1,16 +1,15 @@
 import { pathToFileURL } from "node:url";
 /**
- * Dynamically import a TypeScript steps file and extract the
- * steps array by duck-typing (looks for the first exported array
- * whose elements have a `delayMs` property).
+ * Find the steps array in a loaded module's exports by duck-typing: the
+ * first exported array whose first element has a `delayMs` property.
+ * Returns null when the module exports no such array.
  *
- * Requires the caller's Node process to have a TypeScript loader
- * active (e.g. running via `tsx`). The CLI itself does not depend
- * on any TS compilation tool.
+ * This is THE steps-discovery rule, shared by every Node-side loader and
+ * mirrored verbatim by the browser-side `_findSteps` in the generated
+ * pack entry (see generate-embed-entry.ts) — the mirrors must agree, or
+ * pack-time tooling would see different steps than the packed bundle.
  */
-export async function loadStepsFromTs(filePath) {
-    const mod = await import(pathToFileURL(filePath).href);
-    const exports = mod.default ?? mod;
+export function findStepsArray(exports) {
     for (const value of Object.values(exports)) {
         if (Array.isArray(value) &&
             value.length > 0 &&
@@ -20,6 +19,22 @@ export async function loadStepsFromTs(filePath) {
             return value;
         }
     }
-    throw new Error(`No steps array found in ${filePath}`);
+    return null;
+}
+/**
+ * Dynamically import a TypeScript steps file and extract the
+ * steps array by duck-typing ({@link findStepsArray}).
+ *
+ * Requires the caller's Node process to have a TypeScript loader
+ * active (e.g. running via `tsx`). The CLI itself does not depend
+ * on any TS compilation tool.
+ */
+export async function loadStepsFromTs(filePath) {
+    const mod = await import(pathToFileURL(filePath).href);
+    const steps = findStepsArray(mod.default ?? mod);
+    if (steps === null) {
+        throw new Error(`No steps array found in ${filePath}`);
+    }
+    return steps;
 }
 //# sourceMappingURL=load-ts.js.map

package/src/util/load-ts.js.map

@@ -1 +1 @@
-{"version":3,"file":"load-ts.js","sourceRoot":"","sources":["../../../src/util/load-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAYzC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC;IAEnC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,IACE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACpB,KAAK,CAAC,MAAM,GAAG,CAAC;YAChB,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;YAC5B,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;YACjB,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,EACrB,CAAC;YACD,OAAO,KAAuB,CAAC;QACjC,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"load-ts.js","sourceRoot":"","sources":["../../../src/util/load-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAYzC;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgC;IAC7D,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,IACE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACpB,KAAK,CAAC,MAAM,GAAG,CAAC;YAChB,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;YAC5B,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;YACjB,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,EACrB,CAAC;YACD,OAAO,KAAuB,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,CAAC;IACjD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/src/util/load-ts.ts

@@ -11,18 +11,16 @@ export interface ImportedStep {
 }
 
 /**
- * Dynamically import a TypeScript steps file and extract the
- * steps array by duck-typing (looks for the first exported array
- * whose elements have a `delayMs` property).
+ * Find the steps array in a loaded module's exports by duck-typing: the
+ * first exported array whose first element has a `delayMs` property.
+ * Returns null when the module exports no such array.
  *
- * Requires the caller's Node process to have a TypeScript loader
- * active (e.g. running via `tsx`). The CLI itself does not depend
- * on any TS compilation tool.
+ * This is THE steps-discovery rule, shared by every Node-side loader and
+ * mirrored verbatim by the browser-side `_findSteps` in the generated
+ * pack entry (see generate-embed-entry.ts) — the mirrors must agree, or
+ * pack-time tooling would see different steps than the packed bundle.
  */
-export async function loadStepsFromTs(filePath: string): Promise<ImportedStep[]> {
-  const mod = await import(pathToFileURL(filePath).href);
-  const exports = mod.default ?? mod;
-
+export function findStepsArray(exports: Record<string, unknown>): ImportedStep[] | null {
   for (const value of Object.values(exports)) {
     if (
       Array.isArray(value) &&
@@ -34,6 +32,22 @@ export async function loadStepsFromTs(filePath: string): Promise<ImportedStep[]>
       return value as ImportedStep[];
     }
   }
+  return null;
+}
 
-  throw new Error(`No steps array found in ${filePath}`);
+/**
+ * Dynamically import a TypeScript steps file and extract the
+ * steps array by duck-typing ({@link findStepsArray}).
+ *
+ * Requires the caller's Node process to have a TypeScript loader
+ * active (e.g. running via `tsx`). The CLI itself does not depend
+ * on any TS compilation tool.
+ */
+export async function loadStepsFromTs(filePath: string): Promise<ImportedStep[]> {
+  const mod = await import(pathToFileURL(filePath).href);
+  const steps = findStepsArray(mod.default ?? mod);
+  if (steps === null) {
+    throw new Error(`No steps array found in ${filePath}`);
+  }
+  return steps;
 }