@scenar/cli 0.10.0 → 0.11.0

package/src/__tests__/load-bundle.test.ts

@@ -53,4 +53,71 @@ describe("loadBundle", () => {
     const bundle = await loadBundle("/fake/scenarios/no-audio-demo");
     expect(bundle.narrationManifest).toBeUndefined();
   });
+
+  it("loads the presenter manifest when one exists", async () => {
+    const presenterManifest = {
+      steps: [{ src: "./step-0.mp4", durationMs: 3000 }, null, null],
+    };
+    vi.mocked(loadTs.loadStepsFromTs).mockResolvedValue(mockSteps);
+    // Only the presenter manifest exists for this scenario.
+    vi.mocked(fs.access).mockImplementation((path) =>
+      String(path).includes(join("presenter", "manifest.json"))
+        ? Promise.resolve()
+        : Promise.reject(new Error("ENOENT")),
+    );
+    vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify(presenterManifest) as never);
+
+    const bundle = await loadBundle("/fake/scenarios/presented-demo");
+    expect(bundle.presenterManifest).toEqual(presenterManifest);
+    expect(bundle.narrationManifest).toBeUndefined();
+  });
+
+  it("leaves the presenter manifest undefined when none exists", async () => {
+    vi.mocked(loadTs.loadStepsFromTs).mockResolvedValue(mockSteps);
+    vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"));
+
+    const bundle = await loadBundle("/fake/scenarios/plain-demo");
+    expect(bundle.presenterManifest).toBeUndefined();
+  });
+
+  it("carries the authored soundtrack from the steps module", async () => {
+    const soundtrack = { musicSrc: "./soundtrack/music.mp3", sfx: true };
+    vi.mocked(loadTs.loadStepsFromTs).mockResolvedValue(mockSteps);
+    vi.mocked(loadTs.loadSoundtrackFromTs).mockResolvedValue(soundtrack);
+    vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"));
+
+    const bundle = await loadBundle("/fake/scenarios/scored-demo");
+    expect(bundle.soundtrack).toEqual(soundtrack);
+  });
+
+  it("leaves soundtrack undefined when the module authors none", async () => {
+    vi.mocked(loadTs.loadStepsFromTs).mockResolvedValue(mockSteps);
+    vi.mocked(loadTs.loadSoundtrackFromTs).mockResolvedValue(null);
+    vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"));
+
+    const bundle = await loadBundle("/fake/scenarios/silent-demo");
+    expect(bundle.soundtrack).toBeUndefined();
+  });
+
+  it("carries authored title cards without synthesizing card steps", async () => {
+    const titleCards = { intro: { title: "Acme" }, outro: { title: "Bye" } };
+    vi.mocked(loadTs.loadStepsFromTs).mockResolvedValue(mockSteps);
+    vi.mocked(loadTs.loadTitleCardsFromTs).mockResolvedValue(titleCards);
+    vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"));
+
+    const bundle = await loadBundle("/fake/scenarios/framed-demo");
+    expect(bundle.titleCards).toEqual(titleCards);
+    // The CLI bundle carries the AUTHORED shape — expansion happens in the
+    // generated entries, so the steps stay exactly as written.
+    expect(bundle.steps).toHaveLength(3);
+  });
+
+  it("leaves titleCards undefined when the module authors none", async () => {
+    vi.mocked(loadTs.loadStepsFromTs).mockResolvedValue(mockSteps);
+    vi.mocked(loadTs.loadTitleCardsFromTs).mockResolvedValue(null);
+    vi.mocked(fs.access).mockRejectedValue(new Error("ENOENT"));
+
+    const bundle = await loadBundle("/fake/scenarios/plain-demo");
+    expect(bundle.titleCards).toBeUndefined();
+  });
 });

package/src/__tests__/narrate-command.test.ts

@@ -25,10 +25,14 @@ const mockLoadTs = vi.mocked(loadStepsFromTs);
 const mockDiscover = vi.mocked(discoverScenarios);
 const mockResolveProvider = vi.mocked(resolveProvider);
 
-function createMockProvider(responses: Array<{ audio: Buffer; durationMs: number }>): TtsProvider {
+function createMockProvider(
+  responses: Array<{ audio: Buffer; durationMs: number }>,
+  fingerprint = "test-tts/default-config",
+): TtsProvider {
   let callIndex = 0;
   return {
     name: "test-tts",
+    fingerprint,
     synthesize: vi.fn(async () => {
       const response = responses[callIndex];
       if (!response) throw new Error("unexpected synthesize call");
@@ -108,6 +112,7 @@ describe("scenar narrate — runtime manifest format", () => {
     expect(manifest).not.toHaveProperty("ttsProvider");
 
     const cache = JSON.parse(readFileSync(join(outDir, "my-demo", ".narration-cache.json"), "utf-8"));
+    expect(cache.fingerprint).toBe("test-tts/default-config");
     expect(cache.steps).toHaveLength(3);
     expect(cache.steps[0]).toHaveProperty("hash");
     expect(cache.steps[0]).toHaveProperty("durationMs", 2340);
@@ -163,6 +168,65 @@ describe("scenar narrate — runtime manifest format", () => {
     expect(stderrData).toContain("cached");
   });
 
+  it("regenerates on second run when the provider fingerprint changes", async () => {
+    const scenariosDir = join(tempDir, "scenarios");
+    mkdirSync(join(scenariosDir, "switch-demo"), { recursive: true });
+    writeFileSync(join(scenariosDir, "switch-demo", "steps.ts"), "");
+
+    mockDiscover.mockResolvedValue([
+      { id: "switch-demo", stepsPath: join(scenariosDir, "switch-demo", "steps.ts") },
+    ]);
+
+    mockLoadTs.mockResolvedValue([
+      { delayMs: 0, narration: "Hello world." },
+    ]);
+
+    const outDir = join(tempDir, "out");
+
+    const { registerNarrateCommand } = await import("../commands/narrate.js");
+    const { Command } = await import("commander");
+
+    const openaiLike = createMockProvider(
+      [{ audio: Buffer.from("openai-audio"), durationMs: 1200 }],
+      "openai/tts-1/alloy",
+    );
+    mockResolveProvider.mockResolvedValue(openaiLike);
+
+    const program1 = new Command();
+    registerNarrateCommand(program1);
+    await program1.parseAsync([
+      "node", "scenar", "narrate", scenariosDir, "--out", outDir,
+    ]);
+
+    expect(openaiLike.synthesize).toHaveBeenCalledTimes(1);
+
+    // Same text, same voice — but a different provider configuration.
+    // The old audio must NOT be served as a cache hit.
+    const elevenlabsLike = createMockProvider(
+      [{ audio: Buffer.from("elevenlabs-audio"), durationMs: 1350 }],
+      "elevenlabs/eleven_multilingual_v2/21m00Tcm4TlvDq8ikWAM",
+    );
+    mockResolveProvider.mockResolvedValue(elevenlabsLike);
+
+    const program2 = new Command();
+    registerNarrateCommand(program2);
+    await program2.parseAsync([
+      "node", "scenar", "narrate", scenariosDir, "--out", outDir,
+    ]);
+
+    expect(elevenlabsLike.synthesize).toHaveBeenCalledTimes(1);
+
+    const manifest = JSON.parse(
+      readFileSync(join(outDir, "switch-demo", "manifest.json"), "utf-8"),
+    );
+    expect(manifest.steps[0].durationMs).toBe(1350);
+
+    const cache = JSON.parse(
+      readFileSync(join(outDir, "switch-demo", ".narration-cache.json"), "utf-8"),
+    );
+    expect(cache.fingerprint).toBe("elevenlabs/eleven_multilingual_v2/21m00Tcm4TlvDq8ikWAM");
+  });
+
   it("warns when no scenarios have narration", async () => {
     const scenariosDir = join(tempDir, "scenarios");
     mkdirSync(join(scenariosDir, "empty-demo"), { recursive: true });

package/src/__tests__/narration-cache.test.ts

@@ -0,0 +1,134 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  computeHash,
+  isCached,
+  buildCacheFile,
+  loadCache,
+  saveCache,
+} from "../util/narration-cache.js";
+
+const FINGERPRINT_A = "openai/tts-1/alloy";
+const FINGERPRINT_B = "elevenlabs/eleven_multilingual_v2/21m00Tcm4TlvDq8ikWAM";
+
+describe("computeHash", () => {
+  it("is deterministic for identical inputs", () => {
+    expect(computeHash("hello", "nova", FINGERPRINT_A)).toBe(
+      computeHash("hello", "nova", FINGERPRINT_A),
+    );
+  });
+
+  it("changes when the text changes", () => {
+    expect(computeHash("hello", "nova", FINGERPRINT_A)).not.toBe(
+      computeHash("goodbye", "nova", FINGERPRINT_A),
+    );
+  });
+
+  it("changes when the voice changes", () => {
+    expect(computeHash("hello", "nova", FINGERPRINT_A)).not.toBe(
+      computeHash("hello", "alloy", FINGERPRINT_A),
+    );
+  });
+
+  it("changes when the provider fingerprint changes", () => {
+    // The bug this guards against: same text and voice narrated by a
+    // different provider/model must never collide to the same cache key.
+    expect(computeHash("hello", "", FINGERPRINT_A)).not.toBe(
+      computeHash("hello", "", FINGERPRINT_B),
+    );
+  });
+
+  it("does not collide when a field boundary shifts", () => {
+    // Delimited hashing: ("ab", "c") and ("a", "bc") must differ.
+    expect(computeHash("ab", "c", FINGERPRINT_A)).not.toBe(
+      computeHash("a", "bc", FINGERPRINT_A),
+    );
+  });
+});
+
+describe("isCached", () => {
+  const hash = computeHash("hello", "nova", FINGERPRINT_A);
+  const cache = buildCacheFile(
+    FINGERPRINT_A,
+    "nova",
+    2,
+    new Map([[0, { hash, durationMs: 1200 }]]),
+  );
+
+  it("hits when fingerprint, voice, and hash all match", () => {
+    expect(isCached(cache, 0, hash, "nova", FINGERPRINT_A)).toBe(true);
+  });
+
+  it("misses when the provider fingerprint differs", () => {
+    expect(isCached(cache, 0, hash, "nova", FINGERPRINT_B)).toBe(false);
+  });
+
+  it("misses when the voice differs", () => {
+    expect(isCached(cache, 0, hash, "echo", FINGERPRINT_A)).toBe(false);
+  });
+
+  it("misses when the step hash differs", () => {
+    const otherHash = computeHash("changed text", "nova", FINGERPRINT_A);
+    expect(isCached(cache, 0, otherHash, "nova", FINGERPRINT_A)).toBe(false);
+  });
+
+  it("misses for a step with no cache entry", () => {
+    expect(isCached(cache, 1, hash, "nova", FINGERPRINT_A)).toBe(false);
+  });
+
+  it("misses when there is no cache file", () => {
+    expect(isCached(null, 0, hash, "nova", FINGERPRINT_A)).toBe(false);
+  });
+});
+
+describe("cache file round-trip and legacy handling", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "scenar-cache-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("persists the fingerprint through save and load", async () => {
+    const hash = computeHash("hello", "", FINGERPRINT_B);
+    const cache = buildCacheFile(
+      FINGERPRINT_B,
+      "",
+      1,
+      new Map([[0, { hash, durationMs: 900 }]]),
+    );
+
+    await saveCache(tempDir, cache);
+    const loaded = await loadCache(tempDir);
+
+    expect(loaded).not.toBeNull();
+    expect(isCached(loaded, 0, hash, "", FINGERPRINT_B)).toBe(true);
+    expect(isCached(loaded, 0, hash, "", FINGERPRINT_A)).toBe(false);
+  });
+
+  it("treats a legacy cache file without a fingerprint as stale", async () => {
+    // Cache files written before the fingerprint field existed must
+    // regenerate once rather than serve audio of unknown provenance.
+    const legacyHash = computeHash("hello", "", FINGERPRINT_A);
+    writeFileSync(
+      join(tempDir, ".narration-cache.json"),
+      JSON.stringify({
+        voice: "",
+        steps: [{ hash: legacyHash, durationMs: 900 }],
+      }),
+    );
+
+    const loaded = await loadCache(tempDir);
+    expect(loaded).not.toBeNull();
+    expect(isCached(loaded, 0, legacyHash, "", FINGERPRINT_A)).toBe(false);
+  });
+
+  it("returns null when no cache file exists", async () => {
+    expect(await loadCache(tempDir)).toBeNull();
+  });
+});

package/src/__tests__/pack-bundle-contract.test.ts

@@ -29,6 +29,7 @@ describe("bundle-contract: validateRelativePath", () => {
     expect(validateRelativePath("assets/index-abc.css")).toBeNull();
     expect(validateRelativePath("scenario.json")).toBeNull();
     expect(validateRelativePath("narration/0.mp3")).toBeNull();
+    expect(validateRelativePath("presenter/step-0.mp4")).toBeNull();
   });
 
   it("accepts raster images and modern fonts (the Vite asset case)", () => {
@@ -122,6 +123,7 @@ describe("bundle-contract: content types", () => {
       css: "text/css",
       json: "application/json",
       mp3: "audio/mpeg",
+      mp4: "video/mp4",
       png: "image/png",
       jpg: "image/jpeg",
       jpeg: "image/jpeg",

package/src/__tests__/pack-generate-embed-entry.test.ts

@@ -14,8 +14,37 @@ const BASE = {
   scenarioId: "welcome-tour",
   canonicalWidth: 896,
   shellHeight: 480,
+  hasPresenter: false,
 } as const;
 
+describe("generateEmbedEntry presenter", () => {
+  it("fetches the presenter manifest at runtime and pads it through card synthesis", () => {
+    const src = generateEmbedEntry({
+      ...BASE,
+      hasNarration: false,
+      hasPresenter: true,
+      providersPath: null,
+    });
+    expect(src).toContain("usePresenterManifest");
+    expect(src).toContain('const _resolvePresenterManifestUrl = () => "./presenter/manifest.json";');
+    expect(src).toContain(
+      'const _presenterManifest = usePresenterManifest("welcome-tour", _resolvePresenterManifestUrl);',
+    );
+    expect(src).toContain(
+      "applyTitleCards(_steps as any, undefined, _titleCards, _presenterManifest)",
+    );
+    expect(src).toContain("presenterManifest: _applied.presenterManifest,");
+  });
+
+  it("emits no presenter wiring when the scenario has none", () => {
+    const src = generateEmbedEntry({ ...BASE, hasNarration: false, providersPath: null });
+    expect(src).not.toContain("usePresenterManifest");
+    expect(src).toContain(
+      "applyTitleCards(_steps as any, undefined, _titleCards, undefined)",
+    );
+  });
+});
+
 describe("generateEmbedEntry", () => {
   it("mounts ScenarioPlayer into #root with the renderStep contract", () => {
     const src = generateEmbedEntry({ ...BASE, hasNarration: false, providersPath: null });
@@ -24,7 +53,7 @@ describe("generateEmbedEntry", () => {
     // embedViewport mirrors the DemoViewport numbers so the ready handshake
     // announces the exact canonical size the bundle lays out at.
     expect(src).toContain(
-      "<ScenarioPlayer bundle={_bundle} embed embedViewport={{ widthPx: 896, heightPx: 480 }} onStepChange={_handleStepChange}>",
+      "<ScenarioPlayer bundle={_bundle} embed embedViewport={{ widthPx: 896, heightPx: 480 }} captions={_captions} soundtrackSources={_soundtrackSources} onStepChange={_handleStepChange} onCardStepChange={_handleStepChange}>",
     );
     expect(src).toContain("renderStep(data, stepIndex)");
     expect(src).toContain('getElementById("root")');
@@ -50,12 +79,13 @@ describe("generateEmbedEntry", () => {
 
   it("imports the interaction primitives + React hooks the embed wiring needs", () => {
     const src = generateEmbedEntry({ ...BASE, hasNarration: false, providersPath: null });
-    expect(src).toContain('import { useCallback, useRef, useState } from "react";');
+    expect(src).toContain('import { useCallback, useMemo, useRef, useState } from "react";');
     // ScenarioPlayer/DemoViewport/SCENAR_CLASS plus Cursor, useStepInteractions,
-    // ViewportTransformLayer, VIEWPORT_TRANSFORM_IDENTITY (playback) and
-    // ScenarioCaptureMount (the ?shot capture branch) all come from @scenar/react.
+    // ViewportTransformLayer, VIEWPORT_TRANSFORM_IDENTITY (playback),
+    // ScenarioCaptureMount (the ?shot capture branch), and applyTitleCards
+    // (card synthesis at bundle assembly) all come from @scenar/react.
     expect(src).toContain(
-      'import { ScenarioPlayer, DemoViewport, SCENAR_CLASS, Cursor, useStepInteractions, ViewportTransformLayer, VIEWPORT_TRANSFORM_IDENTITY, ScenarioCaptureMount } from "@scenar/react";',
+      'import { ScenarioPlayer, DemoViewport, SCENAR_CLASS, Cursor, useStepInteractions, ViewportTransformLayer, VIEWPORT_TRANSFORM_IDENTITY, ScenarioCaptureMount, applyTitleCards } from "@scenar/react";',
     );
   });
 
@@ -64,13 +94,17 @@ describe("generateEmbedEntry", () => {
     // A shared container ref flows to DemoViewport, useStepInteractions, and Cursor.
     expect(src).toContain("const _containerRef = useRef<HTMLDivElement>(null);");
     expect(src).toContain("<DemoViewport containerRef={_containerRef}");
-    // Step index is tracked from the player and fed to the interaction scheduler.
+    // Step index is tracked from the player and fed to the interaction
+    // scheduler — from BOTH step-change callbacks, so card-step
+    // interactions (the outro's housekeeping) reach it too.
     expect(src).toContain("onStepChange={_handleStepChange}");
+    expect(src).toContain("onCardStepChange={_handleStepChange}");
     expect(src).toContain("useStepInteractions({");
     expect(src).toContain("setCursorTarget: _setCursorTarget,");
     expect(src).toContain("setViewportTransform: _setViewport,");
     expect(src).toContain("cameraRef: _cameraRef,");
-    expect(src).toContain("steps: _steps,");
+    // The scheduler sees the card-expanded step list, not the authored one.
+    expect(src).toContain("steps: _applied.steps,");
     // The cursor lives INSIDE the camera layer with the camera's contentRef as
     // its container, so it scales and pans with the content during viewport
     // transitions — the documented contract on ViewportTransformLayer.
@@ -86,16 +120,58 @@ describe("generateEmbedEntry", () => {
     expect(cursorIndex).toBeLessThan(layerCloseIndex);
   });
 
+  it("reads ?captions once at module load and forwards it as the player prop", () => {
+    const src = generateEmbedEntry({ ...BASE, hasNarration: false, providersPath: null });
+    // Same frame-time-preference family as ?theme: module-load read, and
+    // absent/other values keep captions off — prior embed behavior.
+    expect(src).toContain('new URLSearchParams(window.location.search).get("captions")');
+    expect(src).toContain('return v === "1" || v === "true";');
+    expect(src).toContain("captions={_captions}");
+  });
+
+  it("discovers the soundtrack at runtime and points its sources at the bundle copies", () => {
+    const src = generateEmbedEntry({ ...BASE, hasNarration: false, providersPath: null });
+    // Runtime mirror of the CLI's findAuthoredSoundtrack — read from the very
+    // module the bundle bakes in, so the embed can never disagree with the
+    // authored config. Absent soundtrack yields undefined: prior behavior.
+    expect(src).toContain("function _findSoundtrack(");
+    expect(src).toContain("soundtrack: _soundtrack,");
+    // The SFX sources point at the files pack copies into the bundle.
+    expect(src).toContain('click: "./soundtrack/sfx/click.mp3"');
+    expect(src).toContain('keystroke: "./soundtrack/sfx/keystroke.mp3"');
+    expect(src).toContain("soundtrackSources={_soundtrackSources}");
+  });
+
   it("feeds the narration manifest into the interaction scheduler when present", () => {
     const without = generateEmbedEntry({ ...BASE, hasNarration: false, providersPath: null });
-    // No narration: interactions are timed by step delays only.
-    expect(without).toContain("narrationManifest: undefined,");
+    // No narration: card synthesis pads nothing and interactions are
+    // timed by step delays only.
+    expect(without).toContain("applyTitleCards(_steps as any, undefined, _titleCards, undefined)");
 
     const withNarration = generateEmbedEntry({ ...BASE, hasNarration: true, providersPath: null });
-    // With narration: both the bundle and useStepInteractions receive _manifest,
-    // so interaction timing tracks the spoken-clip durations.
-    expect(withNarration).toContain("narrationManifest: _manifest,");
-    expect(withNarration).not.toContain("narrationManifest: undefined,");
+    // With narration: _manifest flows through card synthesis (which pads
+    // it in lockstep with any injected card steps) into both the bundle
+    // and useStepInteractions, so interaction timing tracks the
+    // spoken-clip durations.
+    expect(withNarration).toContain("applyTitleCards(_steps as any, _manifest, _titleCards, undefined)");
+    expect(withNarration).toContain("narrationManifest: _applied.narrationManifest,");
+  });
+
+  it("discovers title cards at runtime and synthesizes card steps inside _App", () => {
+    const src = generateEmbedEntry({ ...BASE, hasNarration: true, providersPath: null });
+    // Runtime mirror of the CLI's findAuthoredTitleCards, same as soundtrack.
+    expect(src).toContain("function _findTitleCards(");
+    expect(src).toContain(
+      "const _titleCards: any = _findTitleCards(_stepsModule as unknown as Record<string, unknown>);",
+    );
+    // Applied inside _App (the manifest arrives asynchronously), memoized so
+    // the steps identity stays stable and the scheduler is not re-armed.
+    expect(src).toContain("const _applied = useMemo(");
+    expect(src).toContain("applyTitleCards(_steps as any, _manifest, _titleCards, undefined)");
+    expect(src).toContain("steps: _applied.steps as any,");
+    // Capture mode (?shot) deliberately stays on the AUTHORED steps: shots
+    // live on authored steps and cards declare none.
+    expect(src).toContain("steps={_steps}");
   });
 
   it("imports the @scenar/react theme + styles so the bundle is self-contained", () => {
@@ -137,7 +213,7 @@ describe("generateEmbedEntry", () => {
 
   it("fetches the narration manifest at runtime only when present", () => {
     const without = generateEmbedEntry({ ...BASE, hasNarration: false, providersPath: null });
-    expect(without).toContain("narrationManifest: undefined,");
+    expect(without).toContain("applyTitleCards(_steps as any, undefined, _titleCards, undefined)");
     expect(without).not.toContain("useNarrationManifest");
     expect(without).not.toContain("import _manifest");
 
@@ -148,13 +224,16 @@ describe("generateEmbedEntry", () => {
     // the manifest from its own relative location, so clip src values resolve
     // against ./narration/ at runtime.
     expect(withNarration).toContain(
-      'import { ScenarioPlayer, DemoViewport, SCENAR_CLASS, Cursor, useStepInteractions, ViewportTransformLayer, VIEWPORT_TRANSFORM_IDENTITY, ScenarioCaptureMount, useNarrationManifest } from "@scenar/react";',
+      'import { ScenarioPlayer, DemoViewport, SCENAR_CLASS, Cursor, useStepInteractions, ViewportTransformLayer, VIEWPORT_TRANSFORM_IDENTITY, ScenarioCaptureMount, applyTitleCards, useNarrationManifest } from "@scenar/react";',
     );
     expect(withNarration).toContain('const _resolveManifestUrl = () => "./narration/manifest.json";');
     expect(withNarration).toContain(
       'const _manifest = useNarrationManifest("welcome-tour", _resolveManifestUrl);',
     );
-    expect(withNarration).toContain("narrationManifest: _manifest,");
+    // The fetched manifest flows through card synthesis (which pads it in
+    // lockstep with any injected card steps) into the bundle.
+    expect(withNarration).toContain("applyTitleCards(_steps as any, _manifest, _titleCards, undefined)");
+    expect(withNarration).toContain("narrationManifest: _applied.narrationManifest,");
   });
 
   it("wraps in PreviewProviders only when a providers file exists", () => {