@scenar/cli 0.8.0 → 0.9.1

package/src/index.ts

@@ -4,6 +4,7 @@ import { registerNarrateCommand } from "./commands/narrate.js";
 import { registerInstallCommand } from "./commands/install.js";
 import { registerRenderCommand } from "./commands/render.js";
 import { registerPackCommand } from "./commands/pack.js";
+import { registerShootCommand } from "./commands/shoot.js";
 import { registerServeCommand } from "./commands/serve.js";
 import { registerTryCommand } from "./commands/try.js";
 import { registerPublishCommand } from "./commands/publish.js";
@@ -21,6 +22,7 @@ export function createProgram(): Command {
   registerRenderCommand(program);
   registerInstallCommand(program);
   registerPackCommand(program);
+  registerShootCommand(program);
   registerServeCommand(program);
   registerTryCommand(program);
   registerPublishCommand(program);

package/src/pack/build.d.ts

@@ -1,10 +1,41 @@
 /**
- * Vite build invocation for `scenar pack`.
+ * Vite loading + build invocation for `scenar pack`.
  *
  * Vite is loaded dynamically (like the Remotion bundler in `render`) so the CLI
  * stays lean for users who only validate/narrate. The build runs in "app mode"
  * from a generated index.html, producing a self-contained static bundle.
+ *
+ * The load and the resolution config are exported separately because pack has
+ * a second Vite consumer: `collect-pack-shots` SSR-loads the scenario's steps
+ * module to record its shot names in scenario.json. Both consumers must
+ * resolve the scenario's imports identically — what pack records may never
+ * disagree with what the bundle contains — so they share one config source.
+ */
+/** The subset of Vite's module surface pack uses (typed loosely — Vite is an optional peer). */
+interface ViteModule {
+    build: (config: Record<string, unknown>) => Promise<unknown>;
+    createServer: (config: Record<string, unknown>) => Promise<ViteDevServer>;
+}
+/** The subset of Vite's dev-server surface `collect-pack-shots` uses. */
+export interface ViteDevServer {
+    ssrLoadModule: (specifier: string) => Promise<Record<string, unknown>>;
+    close: () => Promise<void>;
+}
+/** Vite + the React plugin factory, dynamically loaded as a pair. */
+export interface ViteToolkit {
+    readonly vite: ViteModule;
+    readonly react: (...args: unknown[]) => unknown;
+}
+/**
+ * Dynamically import Vite and @vitejs/plugin-react, with an actionable
+ * install hint when either is missing (they are optional peers).
+ */
+export declare function loadViteToolkit(): Promise<ViteToolkit>;
+/**
+ * The resolution config shared by the pack build and the pack-time steps
+ * load — the parts that decide WHICH files an import specifier reaches.
  */
+export declare function sharedViteConfig(toolkit: ViteToolkit): Record<string, unknown>;
 export interface ViteBuildInput {
     /** Build root — the temp dir holding index.html + the generated entry. */
     root: string;
@@ -14,4 +45,5 @@ export interface ViteBuildInput {
     entryHtmlPath: string;
 }
 export declare function runViteBuild(input: ViteBuildInput): Promise<void>;
+export {};
 //# sourceMappingURL=build.d.ts.map

package/src/pack/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/pack/build.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCvE"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/pack/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,gGAAgG;AAChG,UAAU,UAAU;IAClB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3E;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CACjD;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC,CAsB5D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ9E;AAED,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBvE"}

package/src/pack/build.js

@@ -1,29 +1,54 @@
 /**
- * Vite build invocation for `scenar pack`.
+ * Vite loading + build invocation for `scenar pack`.
  *
  * Vite is loaded dynamically (like the Remotion bundler in `render`) so the CLI
  * stays lean for users who only validate/narrate. The build runs in "app mode"
  * from a generated index.html, producing a self-contained static bundle.
+ *
+ * The load and the resolution config are exported separately because pack has
+ * a second Vite consumer: `collect-pack-shots` SSR-loads the scenario's steps
+ * module to record its shot names in scenario.json. Both consumers must
+ * resolve the scenario's imports identically — what pack records may never
+ * disagree with what the bundle contains — so they share one config source.
  */
-export async function runViteBuild(input) {
-    const vite = await import("vite").catch(() => {
+/**
+ * Dynamically import Vite and @vitejs/plugin-react, with an actionable
+ * install hint when either is missing (they are optional peers).
+ */
+export async function loadViteToolkit() {
+    const vite = await import("vite").catch((error) => {
         throw new Error("Could not load vite.\n" +
             "scenar pack bundles the embed with Vite. Install it:\n" +
-            "  pnpm add -D vite @vitejs/plugin-react");
+            "  pnpm add -D vite @vitejs/plugin-react\n" +
+            `(import failed with: ${error instanceof Error ? error.message : String(error)})`);
     });
-    const reactPluginMod = await import("@vitejs/plugin-react").catch(() => {
+    const reactPluginMod = await import("@vitejs/plugin-react").catch((error) => {
         throw new Error("Could not load @vitejs/plugin-react.\n" +
-            "Install it: pnpm add -D vite @vitejs/plugin-react");
+            "Install it: pnpm add -D vite @vitejs/plugin-react\n" +
+            `(import failed with: ${error instanceof Error ? error.message : String(error)})`);
     });
     const react = (reactPluginMod.default ?? reactPluginMod);
-    await vite.build({
-        root: input.root,
-        base: "./", // relative asset URLs: the bundle is served from a per-deploy origin root.
+    return { vite: vite, react };
+}
+/**
+ * The resolution config shared by the pack build and the pack-time steps
+ * load — the parts that decide WHICH files an import specifier reaches.
+ */
+export function sharedViteConfig(toolkit) {
+    return {
         configFile: false, // never pick up a vite.config.* from the consumer project.
         logLevel: "warn",
-        plugins: [react()],
+        plugins: [toolkit.react()],
         // A single React copy — the scenario, @scenar/react, and react-dom must agree.
         resolve: { dedupe: ["react", "react-dom"] },
+    };
+}
+export async function runViteBuild(input) {
+    const toolkit = await loadViteToolkit();
+    await toolkit.vite.build({
+        ...sharedViteConfig(toolkit),
+        root: input.root,
+        base: "./", // relative asset URLs: the bundle is served from a per-deploy origin root.
         build: {
             outDir: input.outDir,
             emptyOutDir: true,

package/src/pack/build.js.map

@@ -1 +1 @@
-{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/pack/build.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAqB;IACtD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;QAC3C,MAAM,IAAI,KAAK,CACb,wBAAwB;YACtB,wDAAwD;YACxD,yCAAyC,CAC5C,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;QACrE,MAAM,IAAI,KAAK,CACb,wCAAwC;YACtC,mDAAmD,CACtD,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,CAAC,cAAc,CAAC,OAAO,IAAI,cAAc,CAE3C,CAAC;IAEb,MAAO,IAAI,CAAC,KAA+D,CAAC;QAC1E,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,IAAI,EAAE,2EAA2E;QACvF,UAAU,EAAE,KAAK,EAAE,2DAA2D;QAC9E,QAAQ,EAAE,MAAM;QAChB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC;QAClB,+EAA+E;QAC/E,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE;QAC3C,KAAK,EAAE;YACL,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,KAAK,EAAE,iDAAiD;YACtE,SAAS,EAAE,KAAK,EAAE,uCAAuC;YACzD,mFAAmF;YACnF,qFAAqF;YACrF,gFAAgF;YAChF,QAAQ,EAAE,KAAK,EAAE,wDAAwD;YACzE,gFAAgF;YAChF,aAAa,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE;YAClC,aAAa,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,aAAa,EAAE;SAC9C;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/pack/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACzD,MAAM,IAAI,KAAK,CACb,wBAAwB;YACtB,wDAAwD;YACxD,2CAA2C;YAC3C,wBAAwB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CACpF,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACnF,MAAM,IAAI,KAAK,CACb,wCAAwC;YACtC,qDAAqD;YACrD,wBAAwB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CACpF,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,CAAC,cAAc,CAAC,OAAO,IAAI,cAAc,CAE3C,CAAC;IAEb,OAAO,EAAE,IAAI,EAAE,IAA6B,EAAE,KAAK,EAAE,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAoB;IACnD,OAAO;QACL,UAAU,EAAE,KAAK,EAAE,2DAA2D;QAC9E,QAAQ,EAAE,MAAM;QAChB,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC1B,+EAA+E;QAC/E,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE;KAC5C,CAAC;AACJ,CAAC;AAWD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAqB;IACtD,MAAM,OAAO,GAAG,MAAM,eAAe,EAAE,CAAC;IAExC,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QACvB,GAAG,gBAAgB,CAAC,OAAO,CAAC;QAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,IAAI,EAAE,2EAA2E;QACvF,KAAK,EAAE;YACL,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,KAAK,EAAE,iDAAiD;YACtE,SAAS,EAAE,KAAK,EAAE,uCAAuC;YACzD,mFAAmF;YACnF,qFAAqF;YACrF,gFAAgF;YAChF,QAAQ,EAAE,KAAK,EAAE,wDAAwD;YACzE,gFAAgF;YAChF,aAAa,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE;YAClC,aAAa,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,aAAa,EAAE;SAC9C;KACF,CAAC,CAAC;AACL,CAAC"}

package/src/pack/build.ts

@@ -1,47 +1,93 @@
 /**
- * Vite build invocation for `scenar pack`.
+ * Vite loading + build invocation for `scenar pack`.
  *
  * Vite is loaded dynamically (like the Remotion bundler in `render`) so the CLI
  * stays lean for users who only validate/narrate. The build runs in "app mode"
  * from a generated index.html, producing a self-contained static bundle.
+ *
+ * The load and the resolution config are exported separately because pack has
+ * a second Vite consumer: `collect-pack-shots` SSR-loads the scenario's steps
+ * module to record its shot names in scenario.json. Both consumers must
+ * resolve the scenario's imports identically — what pack records may never
+ * disagree with what the bundle contains — so they share one config source.
  */
 
-export interface ViteBuildInput {
-  /** Build root — the temp dir holding index.html + the generated entry. */
-  root: string;
-  /** Absolute output directory for the static bundle. */
-  outDir: string;
-  /** Absolute path to the generated index.html (the Rollup input). */
-  entryHtmlPath: string;
+/** The subset of Vite's module surface pack uses (typed loosely — Vite is an optional peer). */
+interface ViteModule {
+  build: (config: Record<string, unknown>) => Promise<unknown>;
+  createServer: (config: Record<string, unknown>) => Promise<ViteDevServer>;
 }
 
-export async function runViteBuild(input: ViteBuildInput): Promise<void> {
-  const vite = await import("vite").catch(() => {
+/** The subset of Vite's dev-server surface `collect-pack-shots` uses. */
+export interface ViteDevServer {
+  ssrLoadModule: (specifier: string) => Promise<Record<string, unknown>>;
+  close: () => Promise<void>;
+}
+
+/** Vite + the React plugin factory, dynamically loaded as a pair. */
+export interface ViteToolkit {
+  readonly vite: ViteModule;
+  readonly react: (...args: unknown[]) => unknown;
+}
+
+/**
+ * Dynamically import Vite and @vitejs/plugin-react, with an actionable
+ * install hint when either is missing (they are optional peers).
+ */
+export async function loadViteToolkit(): Promise<ViteToolkit> {
+  const vite = await import("vite").catch((error: unknown) => {
     throw new Error(
       "Could not load vite.\n" +
         "scenar pack bundles the embed with Vite. Install it:\n" +
-        "  pnpm add -D vite @vitejs/plugin-react",
+        "  pnpm add -D vite @vitejs/plugin-react\n" +
+        `(import failed with: ${error instanceof Error ? error.message : String(error)})`,
     );
   });
 
-  const reactPluginMod = await import("@vitejs/plugin-react").catch(() => {
+  const reactPluginMod = await import("@vitejs/plugin-react").catch((error: unknown) => {
     throw new Error(
       "Could not load @vitejs/plugin-react.\n" +
-        "Install it: pnpm add -D vite @vitejs/plugin-react",
+        "Install it: pnpm add -D vite @vitejs/plugin-react\n" +
+        `(import failed with: ${error instanceof Error ? error.message : String(error)})`,
     );
   });
   const react = (reactPluginMod.default ?? reactPluginMod) as (
     ...args: unknown[]
   ) => unknown;
 
-  await (vite.build as (config: Record<string, unknown>) => Promise<unknown>)({
-    root: input.root,
-    base: "./", // relative asset URLs: the bundle is served from a per-deploy origin root.
+  return { vite: vite as unknown as ViteModule, react };
+}
+
+/**
+ * The resolution config shared by the pack build and the pack-time steps
+ * load — the parts that decide WHICH files an import specifier reaches.
+ */
+export function sharedViteConfig(toolkit: ViteToolkit): Record<string, unknown> {
+  return {
     configFile: false, // never pick up a vite.config.* from the consumer project.
     logLevel: "warn",
-    plugins: [react()],
+    plugins: [toolkit.react()],
     // A single React copy — the scenario, @scenar/react, and react-dom must agree.
     resolve: { dedupe: ["react", "react-dom"] },
+  };
+}
+
+export interface ViteBuildInput {
+  /** Build root — the temp dir holding index.html + the generated entry. */
+  root: string;
+  /** Absolute output directory for the static bundle. */
+  outDir: string;
+  /** Absolute path to the generated index.html (the Rollup input). */
+  entryHtmlPath: string;
+}
+
+export async function runViteBuild(input: ViteBuildInput): Promise<void> {
+  const toolkit = await loadViteToolkit();
+
+  await toolkit.vite.build({
+    ...sharedViteConfig(toolkit),
+    root: input.root,
+    base: "./", // relative asset URLs: the bundle is served from a per-deploy origin root.
     build: {
       outDir: input.outDir,
       emptyOutDir: true,

package/src/pack/collect-pack-shots.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The outcome of pack-time shot discovery.
+ *
+ * `recorded: true` is authoritative — `shots` is exactly what the packed
+ * capture page will report (possibly empty, which lets `scenar shoot` skip
+ * the browser entirely). `recorded: false` means the steps module could not
+ * be loaded under Node, so the shots are unknown and scenario.json must omit
+ * the key: absent = "boot a browser to find out".
+ */
+export type CollectedPackShots = {
+    readonly recorded: true;
+    readonly shots: readonly string[];
+} | {
+    readonly recorded: false;
+    readonly reason: string;
+};
+/**
+ * Discover a scenario's declared shot names at pack time, so they can be
+ * recorded in the bundle's scenario.json.
+ *
+ * The steps module is loaded through Vite's SSR pipeline using the exact
+ * specifier the generated browser entry imports ({@link stepsModuleSpecifier})
+ * and the same resolution config as the pack build ({@link sharedViteConfig}) —
+ * so what pack records and what the bundle contains agree by construction.
+ * This is runtime truth, not source-text approximation: a shot name built
+ * from a constant is discovered just like a literal one.
+ *
+ * Failure semantics split by who is at fault:
+ * - *Environmental* — the module fails to import under Node's SSR runtime
+ *   (e.g. it touches `window` at import time). Returns `recorded: false`
+ *   with the reason; the caller packs on without a `shots` record. Anything
+ *   that packs today still packs.
+ * - *Authoring* — the module imports but is broken: no `delayMs`-bearing
+ *   steps array (the packed embed would throw the same error in the browser
+ *   the moment it loads), or an invalid/duplicate shot name (the capture
+ *   page would throw at shoot time). Throws, failing the pack — these
+ *   bundles must not ship, and the error is most fixable right here.
+ */
+export declare function collectPackShots(scenarioDir: string): Promise<CollectedPackShots>;
+//# sourceMappingURL=collect-pack-shots.d.ts.map

package/src/pack/collect-pack-shots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-pack-shots.d.ts","sourceRoot":"","sources":["../../../src/pack/collect-pack-shots.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAmCvF"}

package/src/pack/collect-pack-shots.js

@@ -0,0 +1,59 @@
+import { collectShotNames } from "@scenar/core";
+import { findStepsArray } from "../util/load-ts.js";
+import { loadViteToolkit, sharedViteConfig } from "./build.js";
+import { stepsModuleSpecifier } from "./generate-embed-entry.js";
+/**
+ * Discover a scenario's declared shot names at pack time, so they can be
+ * recorded in the bundle's scenario.json.
+ *
+ * The steps module is loaded through Vite's SSR pipeline using the exact
+ * specifier the generated browser entry imports ({@link stepsModuleSpecifier})
+ * and the same resolution config as the pack build ({@link sharedViteConfig}) —
+ * so what pack records and what the bundle contains agree by construction.
+ * This is runtime truth, not source-text approximation: a shot name built
+ * from a constant is discovered just like a literal one.
+ *
+ * Failure semantics split by who is at fault:
+ * - *Environmental* — the module fails to import under Node's SSR runtime
+ *   (e.g. it touches `window` at import time). Returns `recorded: false`
+ *   with the reason; the caller packs on without a `shots` record. Anything
+ *   that packs today still packs.
+ * - *Authoring* — the module imports but is broken: no `delayMs`-bearing
+ *   steps array (the packed embed would throw the same error in the browser
+ *   the moment it loads), or an invalid/duplicate shot name (the capture
+ *   page would throw at shoot time). Throws, failing the pack — these
+ *   bundles must not ship, and the error is most fixable right here.
+ */
+export async function collectPackShots(scenarioDir) {
+    const specifier = stepsModuleSpecifier(scenarioDir);
+    const toolkit = await loadViteToolkit();
+    const server = await toolkit.vite.createServer({
+        ...sharedViteConfig(toolkit),
+        root: scenarioDir,
+        // A transform-only server: no HTTP listener, no HMR websocket, and no
+        // dependency pre-bundling scan — ssrLoadModule is the only consumer.
+        server: { middlewareMode: true, hmr: false },
+        optimizeDeps: { noDiscovery: true },
+    });
+    let stepsModule;
+    try {
+        stepsModule = await server.ssrLoadModule(specifier);
+    }
+    catch (error) {
+        return {
+            recorded: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        await server.close();
+    }
+    const steps = findStepsArray(stepsModule);
+    if (steps === null) {
+        throw new Error(`No steps array found in ${specifier} — expected an exported array whose ` +
+            `first element has a delayMs property. The packed embed would throw this ` +
+            `same error in the browser the moment it loads, so pack refuses to ship it.`);
+    }
+    return { recorded: true, shots: collectShotNames(steps) };
+}
+//# sourceMappingURL=collect-pack-shots.js.map

package/src/pack/collect-pack-shots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-pack-shots.js","sourceRoot":"","sources":["../../../src/pack/collect-pack-shots.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAejE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,WAAmB;IACxD,MAAM,SAAS,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAEpD,MAAM,OAAO,GAAG,MAAM,eAAe,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC;QAC7C,GAAG,gBAAgB,CAAC,OAAO,CAAC;QAC5B,IAAI,EAAE,WAAW;QACjB,sEAAsE;QACtE,qEAAqE;QACrE,MAAM,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE;QAC5C,YAAY,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;KACpC,CAAC,CAAC;IAEH,IAAI,WAAoC,CAAC;IACzC,IAAI,CAAC;QACH,WAAW,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC/D,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,MAAM,KAAK,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,2BAA2B,SAAS,sCAAsC;YACxE,0EAA0E;YAC1E,4EAA4E,CAC/E,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;AAC5D,CAAC"}

package/src/pack/collect-pack-shots.ts

@@ -0,0 +1,76 @@
+import { collectShotNames } from "@scenar/core";
+import { findStepsArray } from "../util/load-ts.js";
+import { loadViteToolkit, sharedViteConfig } from "./build.js";
+import { stepsModuleSpecifier } from "./generate-embed-entry.js";
+
+/**
+ * The outcome of pack-time shot discovery.
+ *
+ * `recorded: true` is authoritative — `shots` is exactly what the packed
+ * capture page will report (possibly empty, which lets `scenar shoot` skip
+ * the browser entirely). `recorded: false` means the steps module could not
+ * be loaded under Node, so the shots are unknown and scenario.json must omit
+ * the key: absent = "boot a browser to find out".
+ */
+export type CollectedPackShots =
+  | { readonly recorded: true; readonly shots: readonly string[] }
+  | { readonly recorded: false; readonly reason: string };
+
+/**
+ * Discover a scenario's declared shot names at pack time, so they can be
+ * recorded in the bundle's scenario.json.
+ *
+ * The steps module is loaded through Vite's SSR pipeline using the exact
+ * specifier the generated browser entry imports ({@link stepsModuleSpecifier})
+ * and the same resolution config as the pack build ({@link sharedViteConfig}) —
+ * so what pack records and what the bundle contains agree by construction.
+ * This is runtime truth, not source-text approximation: a shot name built
+ * from a constant is discovered just like a literal one.
+ *
+ * Failure semantics split by who is at fault:
+ * - *Environmental* — the module fails to import under Node's SSR runtime
+ *   (e.g. it touches `window` at import time). Returns `recorded: false`
+ *   with the reason; the caller packs on without a `shots` record. Anything
+ *   that packs today still packs.
+ * - *Authoring* — the module imports but is broken: no `delayMs`-bearing
+ *   steps array (the packed embed would throw the same error in the browser
+ *   the moment it loads), or an invalid/duplicate shot name (the capture
+ *   page would throw at shoot time). Throws, failing the pack — these
+ *   bundles must not ship, and the error is most fixable right here.
+ */
+export async function collectPackShots(scenarioDir: string): Promise<CollectedPackShots> {
+  const specifier = stepsModuleSpecifier(scenarioDir);
+
+  const toolkit = await loadViteToolkit();
+  const server = await toolkit.vite.createServer({
+    ...sharedViteConfig(toolkit),
+    root: scenarioDir,
+    // A transform-only server: no HTTP listener, no HMR websocket, and no
+    // dependency pre-bundling scan — ssrLoadModule is the only consumer.
+    server: { middlewareMode: true, hmr: false },
+    optimizeDeps: { noDiscovery: true },
+  });
+
+  let stepsModule: Record<string, unknown>;
+  try {
+    stepsModule = await server.ssrLoadModule(specifier);
+  } catch (error) {
+    return {
+      recorded: false,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    await server.close();
+  }
+
+  const steps = findStepsArray(stepsModule);
+  if (steps === null) {
+    throw new Error(
+      `No steps array found in ${specifier} — expected an exported array whose ` +
+        `first element has a delayMs property. The packed embed would throw this ` +
+        `same error in the browser the moment it loads, so pack refuses to ship it.`,
+    );
+  }
+
+  return { recorded: true, shots: collectShotNames(steps) };
+}

package/src/pack/generate-embed-entry.d.ts

@@ -47,8 +47,26 @@ export interface EmbedEntryInput {
  * selector). The default is light, so existing embeds are unaffected; a host can
  * theme-sync simply by framing `…/?theme=dark`.
  *
+ * Capture (`?shot`): with a `shot` query param present, the entry mounts
+ * `ScenarioCaptureMount` instead of the playback tree — the TimeSource-driven
+ * catch-up mount behind `scenar shoot` (DD-02). The driver installs on
+ * `window.__scenarShot`; failures surface on `window.__scenarShotError`.
+ * `?shot=<name>` additionally auto-walks to that shot, so an author can
+ * eyeball any still in a plain browser. When the scenario has narration, the
+ * capture branch fetches the manifest itself and fails LOUDLY on error —
+ * step durations are narration-driven, so a silent fallback would capture
+ * every shot at the wrong time (which is why it must not reuse
+ * `useNarrationManifest`, whose fetch failure is silent by design).
+ *
  * Pure function, no side effects — the caller writes the result to disk.
  */
+/**
+ * The import specifier the generated entry uses for the scenario's steps
+ * module (extensionless — Vite resolves .ts/.tsx). Exported so pack-time
+ * tooling (`collect-pack-shots`) loads the very same module the bundle bakes
+ * in, rather than re-deriving a path that could drift from it.
+ */
+export declare function stepsModuleSpecifier(scenarioDir: string): string;
 export declare function generateEmbedEntry(input: EmbedEntryInput): string;
 /**
  * Staged pre-paint backdrop — a hand-maintained mirror of the

package/src/pack/generate-embed-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-embed-entry.d.ts","sourceRoot":"","sources":["../../../src/pack/generate-embed-entry.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,YAAY,EAAE,OAAO,CAAC;IACtB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAkLjE;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAMA,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAKhD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,KAAK,UAAQ,GACZ,MAAM,CAmCR"}
+{"version":3,"file":"generate-embed-entry.d.ts","sourceRoot":"","sources":["../../../src/pack/generate-embed-entry.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,YAAY,EAAE,OAAO,CAAC;IACtB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAwPjE;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAMA,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAKhD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,KAAK,UAAQ,GACZ,MAAM,CAmCR"}

package/src/pack/generate-embed-entry.js

@@ -20,11 +20,30 @@ import { posix } from "node:path";
  * selector). The default is light, so existing embeds are unaffected; a host can
  * theme-sync simply by framing `…/?theme=dark`.
  *
+ * Capture (`?shot`): with a `shot` query param present, the entry mounts
+ * `ScenarioCaptureMount` instead of the playback tree — the TimeSource-driven
+ * catch-up mount behind `scenar shoot` (DD-02). The driver installs on
+ * `window.__scenarShot`; failures surface on `window.__scenarShotError`.
+ * `?shot=<name>` additionally auto-walks to that shot, so an author can
+ * eyeball any still in a plain browser. When the scenario has narration, the
+ * capture branch fetches the manifest itself and fails LOUDLY on error —
+ * step durations are narration-driven, so a silent fallback would capture
+ * every shot at the wrong time (which is why it must not reuse
+ * `useNarrationManifest`, whose fetch failure is silent by design).
+ *
  * Pure function, no side effects — the caller writes the result to disk.
  */
+/**
+ * The import specifier the generated entry uses for the scenario's steps
+ * module (extensionless — Vite resolves .ts/.tsx). Exported so pack-time
+ * tooling (`collect-pack-shots`) loads the very same module the bundle bakes
+ * in, rather than re-deriving a path that could drift from it.
+ */
+export function stepsModuleSpecifier(scenarioDir) {
+    return `${toPosix(scenarioDir)}/steps`;
+}
 export function generateEmbedEntry(input) {
-    const scenarioPath = toPosix(input.scenarioDir);
-    const stepsImport = `${scenarioPath}/steps`;
+    const stepsImport = stepsModuleSpecifier(input.scenarioDir);
     const renderImport = toPosix(input.renderFilePath).replace(/\.[^.]+$/, "");
     const lines = [];
     // --- Imports ---
@@ -42,6 +61,7 @@ export function generateEmbedEntry(input) {
         "useStepInteractions",
         "ViewportTransformLayer",
         "VIEWPORT_TRANSFORM_IDENTITY",
+        "ScenarioCaptureMount",
     ];
     if (input.stage)
         reactImports.push("ScenarioStage");
@@ -90,6 +110,15 @@ export function generateEmbedEntry(input) {
     lines.push(`  catch { return null; }`);
     lines.push(`})();`);
     lines.push(`const _rootClass = _theme === "dark" ? SCENAR_CLASS + " dark" : SCENAR_CLASS;`);
+    // --- Capture mode: ?shot (bare = driver only; ?shot=<name> = auto-walk) ---
+    // Read the same way as _theme: once, at module load, outside React. A null
+    // value (param absent) means normal playback; "" (bare ?shot) means capture
+    // mode without an auto-walk target.
+    lines.push(``);
+    lines.push(`const _shotParam = (() => {`);
+    lines.push(`  try { return new URLSearchParams(window.location.search).get("shot"); }`);
+    lines.push(`  catch { return null; }`);
+    lines.push(`})();`);
     // --- Page canvas: transparent when framed, theme surface when top-level ---
     // The static HTML keeps html/body transparent (see generateEmbedHtml): a
     // framed embed's canvas then shows the *host page's* background through any
@@ -183,11 +212,71 @@ export function generateEmbedEntry(input) {
     lines.push(`    </div>`);
     lines.push(`  );`);
     lines.push(`}`);
+    // --- Capture mount (?shot) ---
+    // The whole capture tree lives in @scenar/react (ScenarioCaptureMount);
+    // this branch only feeds it the same inputs the playback tree gets and
+    // wires the window contract `scenar shoot` consumes: the driver on
+    // `window.__scenarShot`, failures on `window.__scenarShotError`. The
+    // narration manifest is fetched HERE, before mounting, and errors are
+    // fatal — shot times are narration-driven, so capturing without the
+    // manifest would silently shoot every frame at the wrong moment.
+    lines.push(``);
+    lines.push(`async function _mountCapture(rootEl: HTMLElement) {`);
+    if (input.hasNarration) {
+        lines.push(`  const _manifestResponse = await fetch("./narration/manifest.json");`);
+        lines.push(`  if (!_manifestResponse.ok) {`);
+        lines.push(`    throw new Error(`);
+        lines.push(`      "capture: failed to fetch ./narration/manifest.json (HTTP " +`);
+        lines.push(`        _manifestResponse.status + ") — shot times are narration-driven, refusing to capture without it",`);
+        lines.push(`    );`);
+        lines.push(`  }`);
+        lines.push(`  const _captureManifest = await _manifestResponse.json();`);
+    }
+    else {
+        lines.push(`  const _captureManifest = undefined;`);
+    }
+    lines.push(`  createRoot(rootEl).render(`);
+    lines.push(`    <div className={_rootClass}>`);
+    lines.push(`      <ScenarioCaptureMount`);
+    lines.push(`        scenarioId={${JSON.stringify(input.scenarioId)}}`);
+    lines.push(`        steps={_steps}`);
+    lines.push(`        renderStep={renderStep}`);
+    lines.push(`        canonicalWidth={${input.canonicalWidth}}`);
+    lines.push(`        shellHeight={${input.shellHeight}}`);
+    lines.push(`        narrationManifest={_captureManifest}`);
+    lines.push(`        stage={${input.stage ? "true" : "false"}}`);
+    lines.push(`        providers={${input.providersPath ? "_Providers" : "undefined"}}`);
+    lines.push(`        onReady={(driver: any) => {`);
+    lines.push(`          (window as any).__scenarShot = driver;`);
+    lines.push(`          if (_shotParam) {`);
+    lines.push(`            const _target = driver.shots.find((s: any) => s.name === _shotParam);`);
+    lines.push(`            if (!_target) {`);
+    lines.push(`              (window as any).__scenarShotError =`);
+    lines.push(`                'no shot named "' + _shotParam + '" — declared: ' +`);
+    lines.push(`                (driver.shots.map((s: any) => s.name).join(", ") || "(none)");`);
+    lines.push(`              return;`);
+    lines.push(`            }`);
+    lines.push(`            void driver.walkTo(_target.timeMs);`);
+    lines.push(`          }`);
+    lines.push(`        }}`);
+    lines.push(`        onError={(error: any) => {`);
+    lines.push(`          (window as any).__scenarShotError = error?.message ?? String(error);`);
+    lines.push(`        }}`);
+    lines.push(`      />`);
+    lines.push(`    </div>,`);
+    lines.push(`  );`);
+    lines.push(`}`);
     // --- Mount ---
     lines.push(``);
     lines.push(`const _rootEl = document.getElementById("root");`);
     lines.push(`if (!_rootEl) throw new Error("Embed root element #root not found");`);
-    lines.push(`createRoot(_rootEl).render(<_App />);`);
+    lines.push(`if (_shotParam !== null) {`);
+    lines.push(`  _mountCapture(_rootEl).catch((error) => {`);
+    lines.push(`    (window as any).__scenarShotError = error instanceof Error ? error.message : String(error);`);
+    lines.push(`  });`);
+    lines.push(`} else {`);
+    lines.push(`  createRoot(_rootEl).render(<_App />);`);
+    lines.push(`}`);
     lines.push(``);
     return lines.join("\n");
 }