@scenar/core 0.9.1 → 0.11.0

package/src/index.ts

@@ -10,9 +10,28 @@ export type {
   UseStepInteractionsOptions,
 } from "./scenario/step-action.js";
 
+// Soundtrack
+export type { Soundtrack } from "./scenario/soundtrack.js";
+export {
+  MUSIC_VOLUME_DEFAULT,
+  DUCKING_VOLUME_DEFAULT,
+} from "./scenario/soundtrack.js";
+
+// Title cards
+export type { TitleCard, TitleCards, StepCard } from "./scenario/title-cards.js";
+export { TITLE_CARD_DURATION_DEFAULT_MS } from "./scenario/title-cards.js";
+export type { AppliedTitleCards } from "./scenario/apply-title-cards.js";
+export { applyTitleCards } from "./scenario/apply-title-cards.js";
+
 // Narration types
 export type { NarrationEntry, NarrationManifest } from "./narration/types.js";
 
+// Presenter track
+export type { PresenterEntry, PresenterManifest } from "./presenter/types.js";
+export type { PresenterWindow } from "./presenter/derive-presenter-timeline.js";
+export { derivePresenterTimeline } from "./presenter/derive-presenter-timeline.js";
+export { PRESENTER_FADE_MS, presenterOpacityAt } from "./presenter/presenter-opacity.js";
+
 // Viewport types
 export type { ViewportTransform, ViewportCameraMove } from "./viewport/transform.js";
 export {
@@ -28,9 +47,21 @@ export { computeCursorPosition } from "./cursor/compute-position.js";
 
 // Timeline
 export type { StepTimeline } from "./timeline/compute-step-timeline.js";
-export { computeStepTimeline } from "./timeline/compute-step-timeline.js";
+export { FINAL_DWELL_MS, computeStepTimeline } from "./timeline/compute-step-timeline.js";
 export { deriveStepFromTime } from "./timeline/derive-step.js";
 export { getStepDurationMs } from "./timeline/step-duration.js";
+export type { ActionEvent, ActionEventKind } from "./timeline/derive-action-events.js";
+export { deriveActionEvents } from "./timeline/derive-action-events.js";
+export type { SfxEvent, SfxSound } from "./timeline/derive-sfx-timeline.js";
+export { deriveSfxTimeline } from "./timeline/derive-sfx-timeline.js";
+export type { DuckingWindow, MusicEnvelope } from "./timeline/music-envelope.js";
+export {
+  MUSIC_FADE_IN_MS,
+  MUSIC_FADE_OUT_MS,
+  DUCKING_RAMP_MS,
+  computeMusicEnvelope,
+  musicGainAt,
+} from "./timeline/music-envelope.js";
 export type { ScenarioShot } from "./timeline/collect-shots.js";
 export {
   SHOT_NAME_PATTERN,
@@ -79,6 +110,7 @@ export type {
   ScenarEmbedCommand,
   ScenarEmbedEventMessage,
   ScenarEmbedCommandMessage,
+  ScenarEmbedViewport,
 } from "./embed/protocol.js";
 
 // Embed host controller — framework-free driver for an embedded player

package/src/presenter/derive-presenter-timeline.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest";
+import { computeStepTimeline } from "../timeline/compute-step-timeline.js";
+import { deriveStepFromTime } from "../timeline/derive-step.js";
+import { applyTitleCards } from "../scenario/apply-title-cards.js";
+import type { ScenarioStep } from "../scenario/types.js";
+import { derivePresenterTimeline } from "./derive-presenter-timeline.js";
+import type { PresenterManifest } from "./types.js";
+
+const step = (delayMs: number): ScenarioStep<null> => ({ delayMs, data: null });
+
+const entry = (index: number, durationMs: number) => ({
+  src: `./step-${index}.mp4`,
+  durationMs,
+});
+
+describe("derivePresenterTimeline", () => {
+  it("returns no windows without a manifest", () => {
+    const timeline = computeStepTimeline([step(0), step(1000)], undefined);
+    expect(derivePresenterTimeline(undefined, timeline)).toEqual([]);
+  });
+
+  it("returns no windows for an all-null manifest", () => {
+    const timeline = computeStepTimeline([step(0), step(1000)], undefined);
+    const manifest: PresenterManifest = { steps: [null, null] };
+    expect(derivePresenterTimeline(manifest, timeline)).toEqual([]);
+  });
+
+  it("windows a clip on step 0 at time 0", () => {
+    const timeline = computeStepTimeline([step(0), step(1000)], undefined);
+    const manifest: PresenterManifest = { steps: [entry(0, 2500), null] };
+
+    expect(derivePresenterTimeline(manifest, timeline)).toEqual([
+      { stepIndex: 0, startMs: 0, clipDurationMs: 2500 },
+    ]);
+  });
+
+  it("windows a clip on the last step at its start time", () => {
+    const steps = [step(0), step(1000), step(800)];
+    const manifest: PresenterManifest = { steps: [null, null, entry(2, 1500)] };
+    // Step starts derive from narration-compatible durations too; keep
+    // this delay-only so startMs is the plain prefix sum: 0, 1000, 1800.
+    const timeline = computeStepTimeline(steps, undefined);
+
+    expect(derivePresenterTimeline(manifest, timeline)).toEqual([
+      { stepIndex: 2, startMs: 1800, clipDurationMs: 1500 },
+    ]);
+  });
+
+  it("handles a single-step scenario", () => {
+    const timeline = computeStepTimeline([step(0)], undefined);
+    const manifest: PresenterManifest = { steps: [entry(0, 900)] };
+
+    expect(derivePresenterTimeline(manifest, timeline)).toEqual([
+      { stepIndex: 0, startMs: 0, clipDurationMs: 900 },
+    ]);
+  });
+
+  it("windows every opted-in step and skips the rest", () => {
+    const steps = [step(0), step(1000), step(1000), step(1000)];
+    const manifest: PresenterManifest = {
+      steps: [entry(0, 500), null, entry(2, 700), null],
+    };
+    const timeline = computeStepTimeline(steps, undefined);
+
+    expect(derivePresenterTimeline(manifest, timeline)).toEqual([
+      { stepIndex: 0, startMs: 0, clipDurationMs: 500 },
+      { stepIndex: 2, startMs: 2000, clipDurationMs: 700 },
+    ]);
+  });
+
+  it("ignores manifest entries beyond the timeline's steps (stale manifest degrades)", () => {
+    const timeline = computeStepTimeline([step(0)], undefined);
+    const manifest: PresenterManifest = {
+      steps: [entry(0, 500), entry(1, 700)],
+    };
+
+    expect(derivePresenterTimeline(manifest, timeline)).toEqual([
+      { stepIndex: 0, startMs: 0, clipDurationMs: 500 },
+    ]);
+  });
+
+  it("aligns with card-padded manifests from applyTitleCards", () => {
+    const authored: ScenarioStep<null>[] = [step(0), step(1500)];
+    const narration = {
+      steps: [
+        { src: "./step-0.mp3", durationMs: 2000 },
+        { src: "./step-1.mp3", durationMs: 1200 },
+      ],
+    };
+    const presenter: PresenterManifest = {
+      steps: [entry(0, 2000), null],
+    };
+
+    const applied = applyTitleCards(authored, narration, {
+      intro: { title: "Acme", durationMs: 4000 },
+      outro: { title: "Try it" },
+    }, presenter);
+    const timeline = computeStepTimeline(applied.steps, applied.narrationManifest);
+
+    // The one opted-in authored step is now index 1 (after the intro),
+    // starting when the intro's 4000ms card time elapses.
+    expect(derivePresenterTimeline(applied.presenterManifest, timeline)).toEqual([
+      { stepIndex: 1, startMs: 4000, clipDurationMs: 2000 },
+    ]);
+  });
+
+  it("agrees with deriveStepFromTime: a window is active exactly while its step is", () => {
+    const steps = [step(0), step(1000), step(3000)];
+    const narration = {
+      steps: [
+        { src: "./step-0.mp3", durationMs: 2000 },
+        null,
+        { src: "./step-2.mp3", durationMs: 1500 },
+      ],
+    };
+    // Presenter durations mirror narration durations (the CLI writes
+    // them from the narration manifest), so windows fit their steps.
+    const presenter: PresenterManifest = {
+      steps: [entry(0, 2000), null, entry(2, 1500)],
+    };
+    const timeline = computeStepTimeline(steps, narration);
+    const windows = derivePresenterTimeline(presenter, timeline);
+    const lastIndex = steps.length - 1;
+
+    for (const window of windows) {
+      const samples = [
+        window.startMs,
+        window.startMs + window.clipDurationMs / 2,
+        window.startMs + window.clipDurationMs - 1,
+      ];
+      for (const t of samples) {
+        expect(deriveStepFromTime(t, timeline.stepStartTimesMs, lastIndex)).toBe(
+          window.stepIndex,
+        );
+      }
+    }
+  });
+});

package/src/presenter/derive-presenter-timeline.ts

@@ -0,0 +1,54 @@
+import type { StepTimeline } from "../timeline/compute-step-timeline.js";
+import type { PresenterManifest } from "./types.js";
+
+/**
+ * One presenter clip's place on the scenario timeline: when it becomes
+ * visible (its step's start) and how long it plays.
+ *
+ * A window never outlives its step — `scenar presenter` writes clip
+ * durations from the narration manifest, and step timing already waits
+ * for narration (`max(delayMs, narration duration)`), so the clip fits
+ * by construction. When the step outlives the clip (a long `delayMs`),
+ * the frame fades out at clip end (see `presenterOpacityAt`).
+ */
+export interface PresenterWindow {
+  /** Index into the EXPANDED step list (same domain as `stepTimeline`). */
+  readonly stepIndex: number;
+  /** Clip start in scenario time — the step's start, in milliseconds. */
+  readonly startMs: number;
+  /** Clip length in milliseconds. */
+  readonly clipDurationMs: number;
+}
+
+/**
+ * Derive every presenter clip's timeline window from the (expanded,
+ * card-padded) presenter manifest and the step timeline computed over
+ * the same expanded steps.
+ *
+ * This is the one implementation both outputs consume: the browser
+ * player uses windows for expected-position math in its drift
+ * corrections; the video export converts `startMs` to frames for
+ * Sequence placement. Pure function — same inputs, same windows, in
+ * both time domains.
+ *
+ * Manifest entries beyond the timeline's step count are ignored (a
+ * stale manifest degrades, exactly as narration does).
+ */
+export function derivePresenterTimeline(
+  presenterManifest: PresenterManifest | undefined,
+  stepTimeline: StepTimeline,
+): readonly PresenterWindow[] {
+  if (!presenterManifest) return [];
+
+  const windows: PresenterWindow[] = [];
+  for (let i = 0; i < stepTimeline.stepStartTimesMs.length; i++) {
+    const entry = presenterManifest.steps[i];
+    if (!entry) continue;
+    windows.push({
+      stepIndex: i,
+      startMs: stepTimeline.stepStartTimesMs[i]!,
+      clipDurationMs: entry.durationMs,
+    });
+  }
+  return windows;
+}

package/src/presenter/presenter-opacity.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { PRESENTER_FADE_MS, presenterOpacityAt } from "./presenter-opacity.js";
+
+describe("presenterOpacityAt", () => {
+  const CLIP_MS = 5000;
+
+  it.each([
+    ["before the clip", -1, 0],
+    ["at clip start (first frame of the fade-in)", 0, 0],
+    ["mid fade-in", PRESENTER_FADE_MS / 2, 0.5],
+    ["at fade-in end", PRESENTER_FADE_MS, 1],
+    ["mid-clip", CLIP_MS / 2, 1],
+    ["at fade-out start", CLIP_MS - PRESENTER_FADE_MS, 1],
+    ["mid fade-out", CLIP_MS - PRESENTER_FADE_MS / 2, 0.5],
+    ["at clip end", CLIP_MS, 0],
+    ["after the clip (step outlives it)", CLIP_MS + 1000, 0],
+  ])("is %s → %d", (_label, intraStepMs, expected) => {
+    expect(presenterOpacityAt(intraStepMs, CLIP_MS)).toBeCloseTo(expected, 5);
+  });
+
+  it("keeps a clip shorter than two fades continuous, peaking at its midpoint", () => {
+    const shortClip = PRESENTER_FADE_MS; // 200ms: ramps intersect at 100ms
+    expect(presenterOpacityAt(0, shortClip)).toBe(0);
+    expect(presenterOpacityAt(shortClip / 2, shortClip)).toBeCloseTo(0.5, 5);
+    expect(presenterOpacityAt(shortClip, shortClip)).toBe(0);
+    // Monotonic up to the midpoint, down after it.
+    expect(presenterOpacityAt(40, shortClip)).toBeLessThan(
+      presenterOpacityAt(80, shortClip),
+    );
+    expect(presenterOpacityAt(160, shortClip)).toBeLessThan(
+      presenterOpacityAt(120, shortClip),
+    );
+  });
+
+  it("never exceeds 1 or drops below 0 across the whole clip", () => {
+    for (let t = -100; t <= CLIP_MS + 100; t += 25) {
+      const opacity = presenterOpacityAt(t, CLIP_MS);
+      expect(opacity).toBeGreaterThanOrEqual(0);
+      expect(opacity).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it("is 0 for a zero-duration clip", () => {
+    expect(presenterOpacityAt(0, 0)).toBe(0);
+    expect(presenterOpacityAt(100, 0)).toBe(0);
+  });
+});

package/src/presenter/presenter-opacity.ts

@@ -0,0 +1,43 @@
+/**
+ * The presenter frame's fade treatment, as a pure function of time —
+ * so the browser player and the video export render the identical
+ * fade from the same math (one implementation, both time domains).
+ */
+
+/**
+ * Fade length at each end of a presenter clip, in milliseconds.
+ *
+ * The fade-in doubles as the swap treatment: it absorbs the measured
+ * src-swap pop-in (≤133 ms worst case across browsers), so no
+ * double-buffering machinery is needed. The fade-out is the exit
+ * grammar — the presenter finishes and steps aside, rather than
+ * freezing mid-gesture when the step outlives the clip.
+ */
+export const PRESENTER_FADE_MS = 200;
+
+/**
+ * The presenter frame's opacity at `intraStepMs` milliseconds into its
+ * step, for a clip of `clipDurationMs`.
+ *
+ * Ramps 0→1 over the first {@link PRESENTER_FADE_MS}, holds 1, ramps
+ * 1→0 over the last {@link PRESENTER_FADE_MS}, and is 0 outside the
+ * clip (before its start, and for the remainder of a step that
+ * outlives it). Clips shorter than two fades never reach full
+ * opacity — the ramps intersect at the midpoint, keeping the curve
+ * continuous.
+ *
+ * Reduced-motion is a consumer concern: the browser player hides the
+ * presenter entirely under `prefers-reduced-motion`, and the export
+ * has no such media query — neither needs a flag here.
+ */
+export function presenterOpacityAt(
+  intraStepMs: number,
+  clipDurationMs: number,
+): number {
+  if (clipDurationMs <= 0) return 0;
+  if (intraStepMs <= 0 || intraStepMs >= clipDurationMs) return 0;
+
+  const fadeIn = intraStepMs / PRESENTER_FADE_MS;
+  const fadeOut = (clipDurationMs - intraStepMs) / PRESENTER_FADE_MS;
+  return Math.min(fadeIn, fadeOut, 1);
+}

package/src/presenter/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Runtime presenter clip data produced by `scenar presenter`.
+ *
+ * The presenter track is structurally a second narration pipeline:
+ * generation happens at compile time (the CLI calls the avatar
+ * provider once and stores the result), and playback consumes fixed
+ * assets through a positional manifest. Playback never calls an AI
+ * service — a scenario whose clips have not been generated yet simply
+ * plays without the presenter.
+ *
+ * Deliberately its own type, not a generic "clip manifest" shared with
+ * narration: the two are structurally identical today, but their doc
+ * contracts differ, and that difference IS the domain knowledge.
+ */
+
+/** A single presenter clip for one scenario step. */
+export interface PresenterEntry {
+  /**
+   * URL of the clip, relative to the manifest's own location
+   * (e.g. "./step-2.mp4") — the same convention narration uses.
+   */
+  readonly src: string;
+  /**
+   * Duration of the clip in milliseconds. Written from the narration
+   * manifest's duration for the same step (the clip is lip-synced to
+   * that audio and matches it exactly), so presenter timing and
+   * narration timing can never disagree.
+   */
+  readonly durationMs: number;
+}
+
+/**
+ * Per-scenario manifest mapping step indices to presenter clips.
+ *
+ * Array position corresponds to the AUTHORED step index — like the
+ * narration manifest, it never knows about synthesized title-card
+ * steps. Bundle assembly (`applyTitleCards`) pads `null` entries at
+ * injected card positions so the expanded manifest lines up with the
+ * expanded steps; cards never show the presenter.
+ *
+ * Steps without a presenter (not opted in, or generation failed and
+ * playback degrades per-step) use `null`.
+ */
+export interface PresenterManifest {
+  readonly steps: readonly (PresenterEntry | null)[];
+}

package/src/scenario/apply-title-cards.test.ts

@@ -0,0 +1,268 @@
+import { describe, expect, it } from "vitest";
+import type { NarrationManifest } from "../narration/types.js";
+import type { PresenterManifest } from "../presenter/types.js";
+import { FINAL_DWELL_MS, computeStepTimeline } from "../timeline/compute-step-timeline.js";
+import { deriveStepFromTime } from "../timeline/derive-step.js";
+import { applyTitleCards } from "./apply-title-cards.js";
+import { TITLE_CARD_DURATION_DEFAULT_MS } from "./title-cards.js";
+import type { ScenarioStep } from "./types.js";
+
+interface Data {
+  screen: string;
+}
+
+const step = (delayMs: number, screen: string): ScenarioStep<Data> => ({
+  delayMs,
+  data: { screen },
+});
+
+const authored: ScenarioStep<Data>[] = [step(0, "login"), step(1500, "dashboard")];
+
+const manifest: NarrationManifest = {
+  steps: [
+    { src: "./step-0.mp3", durationMs: 2000 },
+    { src: "./step-1.mp3", durationMs: 1200 },
+  ],
+};
+
+describe("applyTitleCards", () => {
+  describe("no-op cases", () => {
+    it("returns the inputs untouched when titleCards is undefined", () => {
+      const result = applyTitleCards(authored, manifest, undefined);
+      expect(result.steps).toBe(authored);
+      expect(result.narrationManifest).toBe(manifest);
+    });
+
+    it("returns the inputs untouched when neither intro nor outro is set", () => {
+      const result = applyTitleCards(authored, manifest, {});
+      expect(result.steps).toBe(authored);
+      expect(result.narrationManifest).toBe(manifest);
+    });
+  });
+
+  describe("intro", () => {
+    it("prepends an intro card step with the card content", () => {
+      const { steps } = applyTitleCards(authored, undefined, {
+        intro: { title: "Acme", subtitle: "Ship fast", logoSrc: "./logo.png" },
+      });
+      expect(steps).toHaveLength(3);
+      expect(steps[0]!.delayMs).toBe(0);
+      expect(steps[0]!.card).toEqual({
+        kind: "intro",
+        title: "Acme",
+        subtitle: "Ship fast",
+        logoSrc: "./logo.png",
+      });
+    });
+
+    it("encodes the card duration as the following step's transition delay", () => {
+      const { steps } = applyTitleCards(authored, undefined, {
+        intro: { title: "Acme", durationMs: 4500 },
+      });
+      expect(steps[1]!.delayMs).toBe(4500);
+      expect(steps[1]!.data).toEqual({ screen: "login" });
+    });
+
+    it("defaults the card duration when unset", () => {
+      const { steps } = applyTitleCards(authored, undefined, { intro: { title: "Acme" } });
+      expect(steps[1]!.delayMs).toBe(TITLE_CARD_DURATION_DEFAULT_MS);
+    });
+
+    it("keeps a larger authored first-step delay over the card duration", () => {
+      const slowStart = [step(8000, "login"), step(1500, "dashboard")];
+      const { steps } = applyTitleCards(slowStart, undefined, {
+        intro: { title: "Acme", durationMs: 3000 },
+      });
+      expect(steps[1]!.delayMs).toBe(8000);
+    });
+
+    it("pads the narration manifest with a leading null", () => {
+      const { narrationManifest } = applyTitleCards(authored, manifest, {
+        intro: { title: "Acme" },
+      });
+      expect(narrationManifest!.steps).toEqual([null, ...manifest.steps]);
+    });
+
+    it("leaves an absent manifest absent", () => {
+      const { narrationManifest } = applyTitleCards(authored, undefined, {
+        intro: { title: "Acme" },
+      });
+      expect(narrationManifest).toBeUndefined();
+    });
+
+    it("does not prepend a card to an empty steps array", () => {
+      const { steps } = applyTitleCards<Data>([], undefined, { intro: { title: "Acme" } });
+      expect(steps).toHaveLength(0);
+    });
+  });
+
+  describe("outro", () => {
+    it("appends an outro card step that preserves the last authored step's dwell", () => {
+      const { steps } = applyTitleCards(authored, undefined, {
+        outro: { title: "Try it", ctaText: "acme.dev" },
+      });
+      expect(steps).toHaveLength(3);
+      const outro = steps[2]!;
+      expect(outro.delayMs).toBe(FINAL_DWELL_MS);
+      expect(outro.card).toEqual({ kind: "outro", title: "Try it", ctaText: "acme.dev" });
+    });
+
+    it("clears the cursor and resets the viewport at card entry", () => {
+      const { steps } = applyTitleCards(authored, undefined, { outro: { title: "Try it" } });
+      expect(steps[2]!.interactions).toEqual([
+        { atPercent: 0, type: "clear_cursor" },
+        { atPercent: 0, type: "viewport_transition", viewportReset: true },
+      ]);
+    });
+
+    it("pads the narration manifest with a trailing null", () => {
+      const { narrationManifest } = applyTitleCards(authored, manifest, {
+        outro: { title: "Try it" },
+      });
+      expect(narrationManifest!.steps).toEqual([...manifest.steps, null]);
+    });
+  });
+
+  describe("intro and outro together", () => {
+    it("frames the authored steps and pads the manifest on both ends", () => {
+      const { steps, narrationManifest } = applyTitleCards(authored, manifest, {
+        intro: { title: "Acme" },
+        outro: { title: "Try it" },
+      });
+      expect(steps).toHaveLength(4);
+      expect(steps[0]!.card?.kind).toBe("intro");
+      expect(steps[1]!.data).toEqual({ screen: "login" });
+      expect(steps[2]!.data).toEqual({ screen: "dashboard" });
+      expect(steps[3]!.card?.kind).toBe("outro");
+      expect(narrationManifest!.steps).toEqual([null, ...manifest.steps, null]);
+    });
+
+    it("copies only known card fields from a loosely-typed config", () => {
+      const stray = {
+        title: "Acme",
+        clickHandler: () => {},
+      } as unknown as { title: string };
+      const { steps } = applyTitleCards(authored, undefined, { intro: stray });
+      expect(steps[0]!.card).toEqual({ kind: "intro", title: "Acme" });
+    });
+
+    it("does not mutate the input steps or manifest", () => {
+      const stepsBefore = [...authored];
+      const manifestBefore = [...manifest.steps];
+      applyTitleCards(authored, manifest, {
+        intro: { title: "Acme" },
+        outro: { title: "Try it" },
+      });
+      expect(authored).toEqual(stepsBefore);
+      expect(manifest.steps).toEqual(manifestBefore);
+    });
+  });
+
+  describe("presenter manifest padding", () => {
+    const presenterManifest: PresenterManifest = {
+      steps: [{ src: "./step-0.mp4", durationMs: 2000 }, null],
+    };
+
+    it("pads narration and presenter manifests at identical positions", () => {
+      const result = applyTitleCards(authored, manifest, {
+        intro: { title: "Acme" },
+        outro: { title: "Try it" },
+      }, presenterManifest);
+
+      expect(result.narrationManifest!.steps).toEqual([null, ...manifest.steps, null]);
+      expect(result.presenterManifest!.steps).toEqual([
+        null,
+        ...presenterManifest.steps,
+        null,
+      ]);
+      // Index-aligned by construction: same length as the expanded steps.
+      expect(result.presenterManifest!.steps).toHaveLength(result.steps.length);
+      expect(result.narrationManifest!.steps).toHaveLength(result.steps.length);
+    });
+
+    it("returns the presenter manifest untouched when no card is configured", () => {
+      const result = applyTitleCards(authored, manifest, undefined, presenterManifest);
+      expect(result.presenterManifest).toBe(presenterManifest);
+    });
+
+    it("leaves an absent presenter manifest absent", () => {
+      const result = applyTitleCards(authored, manifest, { intro: { title: "Acme" } });
+      expect(result.presenterManifest).toBeUndefined();
+    });
+
+    it("pads the presenter manifest even when narration is absent", () => {
+      const result = applyTitleCards(authored, undefined, {
+        outro: { title: "Try it" },
+      }, presenterManifest);
+      expect(result.narrationManifest).toBeUndefined();
+      expect(result.presenterManifest!.steps).toEqual([...presenterManifest.steps, null]);
+    });
+
+    it("does not mutate the input presenter manifest", () => {
+      const entriesBefore = [...presenterManifest.steps];
+      applyTitleCards(authored, manifest, {
+        intro: { title: "Acme" },
+        outro: { title: "Try it" },
+      }, presenterManifest);
+      expect(presenterManifest.steps).toEqual(entriesBefore);
+    });
+  });
+
+  describe("timeline integration", () => {
+    it("gives the intro exactly its duration and the outro exactly its dwell", () => {
+      const { steps, narrationManifest } = applyTitleCards(authored, manifest, {
+        intro: { title: "Acme", durationMs: 4000 },
+        outro: { title: "Try it", durationMs: 5000 },
+      });
+      const tl = computeStepTimeline(steps, narrationManifest);
+      // Intro visible 0..4000 (card duration beats step-0 narration? No —
+      // the manifest is padded, so the intro has no narration entry).
+      expect(tl.stepStartTimesMs).toEqual([
+        0,
+        4000, // login enters after the intro's 4000ms
+        4000 + 2000, // dashboard after max(1500, login narration 2000)
+        6000 + Math.max(FINAL_DWELL_MS, 1200), // outro after the authored closing dwell
+      ]);
+      // The outro dwells for its configured 5000ms.
+      expect(tl.totalDurationMs).toBe(9000 + 5000);
+    });
+
+    it("changes nothing about the authored steps' relative timing", () => {
+      const bare = computeStepTimeline(authored, manifest);
+      const { steps, narrationManifest } = applyTitleCards(authored, manifest, {
+        intro: { title: "Acme" },
+      });
+      const framed = computeStepTimeline(steps, narrationManifest);
+      // Every authored boundary shifts by exactly the intro duration.
+      const shifted = bare.stepStartTimesMs.map((ms) => ms + TITLE_CARD_DURATION_DEFAULT_MS);
+      expect(framed.stepStartTimesMs.slice(1)).toEqual(shifted);
+      expect(framed.totalDurationMs).toBe(bare.totalDurationMs + TITLE_CARD_DURATION_DEFAULT_MS);
+    });
+
+    it("derives the same active step in both time domains across card boundaries", () => {
+      const fps = 30;
+      const msToFrame = (ms: number) => Math.round((ms * fps) / 1000);
+      const frameToMs = (frame: number) => (frame * 1000) / fps;
+
+      const { steps, narrationManifest } = applyTitleCards(authored, manifest, {
+        intro: { title: "Acme" },
+        outro: { title: "Try it" },
+      });
+      const tl = computeStepTimeline(steps, narrationManifest);
+      const lastIndex = steps.length - 1;
+
+      // Sample densely around every boundary plus mid-step points.
+      const samples = tl.stepStartTimesMs.flatMap((ms) => [ms - 34, ms, ms + 34]);
+      samples.push(tl.totalDurationMs - 34, tl.totalDurationMs);
+      for (const t of samples.filter((ms) => ms >= 0)) {
+        const browserStep = deriveStepFromTime(t, tl.stepStartTimesMs, lastIndex);
+        const frameStep = deriveStepFromTime(
+          frameToMs(msToFrame(t)),
+          tl.stepStartTimesMs,
+          lastIndex,
+        );
+        expect(frameStep).toBe(browserStep);
+      }
+    });
+  });
+});