@scenar/core 0.10.0 → 0.11.0

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);
+      }
+    });
+  });
+});

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

@@ -0,0 +1,141 @@
+/**
+ * Card synthesis: expand a scenario's steps (and narration manifest)
+ * with its configured intro/outro title cards.
+ *
+ * This is THE one place card steps are constructed. It runs exactly
+ * once per playback surface, at bundle assembly — the generated render
+ * and pack entries, the CLI's `loadBundle`, and (for direct React
+ * integrators) one documented call between `createScenario()` and the
+ * player. Authoring surfaces (`createScenario`, `loadScenarioFromProto`)
+ * carry the `titleCards` config through untouched, exactly like
+ * `soundtrack` — so expanded output never carries the config and double
+ * expansion is impossible by data flow.
+ *
+ * The positional manifests stay keyed to AUTHORED steps everywhere
+ * (`scenar narrate` and `scenar presenter` never see cards); this
+ * function pads `null` entries at the injected positions — narration
+ * and presenter in the same single pass — so the expanded manifests
+ * line up with the expanded steps. Existing manifests therefore stay
+ * valid when an author adds cards later — no regeneration required.
+ */
+
+import type { NarrationManifest } from "../narration/types.js";
+import type { PresenterManifest } from "../presenter/types.js";
+import { FINAL_DWELL_MS } from "../timeline/compute-step-timeline.js";
+import type { ScenarioStep } from "./types.js";
+import {
+  TITLE_CARD_DURATION_DEFAULT_MS,
+  type TitleCard,
+  type TitleCards,
+} from "./title-cards.js";
+
+/** The result of card expansion: steps and manifests, index-aligned. */
+export interface AppliedTitleCards<T> {
+  readonly steps: readonly ScenarioStep<T>[];
+  readonly narrationManifest: NarrationManifest | undefined;
+  readonly presenterManifest: PresenterManifest | undefined;
+}
+
+/**
+ * A card step's `data` placeholder. Card steps are rendered by the
+ * player's built-in card component — the integrator's render callback
+ * (the only reader of `data`) is never invoked for them, so no real
+ * `T` value is ever needed. See the `ScenarioStep.card` doc contract.
+ */
+function cardStepData<T>(): T {
+  return undefined as unknown as T;
+}
+
+/**
+ * Expand `steps` (and the index-parallel narration and presenter
+ * manifests, when they exist) with the configured intro/outro cards.
+ *
+ * - **Intro**: prepended at index 0 with `delayMs: 0`; the card's
+ *   visible time is encoded as the following step's transition delay
+ *   (`max(authored delayMs, card duration)`), which is exactly how
+ *   `computeStepTimeline` reads step 0's duration.
+ * - **Outro**: appended with `delayMs: FINAL_DWELL_MS`, so the last
+ *   authored step keeps precisely the closing dwell it has today (or
+ *   its narration, whichever is longer) before the card appears. The
+ *   card's own visible time is its `durationMs` — `computeStepTimeline`
+ *   reads a final card step's duration as the closing dwell. The outro
+ *   carries two housekeeping interactions at step entry (`clear_cursor`
+ *   and a viewport reset) so a scenario ending with a visible cursor or
+ *   an active zoom never leaks that state onto the card. Neither action
+ *   maps to a sound effect.
+ *
+ * Pure and non-mutating. When `titleCards` configures no card, the
+ * inputs are returned as-is (byte-identical no-op).
+ */
+export function applyTitleCards<T>(
+  steps: readonly ScenarioStep<T>[],
+  narrationManifest: NarrationManifest | undefined,
+  titleCards: TitleCards | undefined,
+  presenterManifest?: PresenterManifest,
+): AppliedTitleCards<T> {
+  const intro = titleCards?.intro;
+  const outro = titleCards?.outro;
+  if (!intro && !outro) {
+    return { steps, narrationManifest, presenterManifest };
+  }
+
+  const expandedSteps: ScenarioStep<T>[] = [...steps];
+  let manifestEntries = narrationManifest ? [...narrationManifest.steps] : undefined;
+  let presenterEntries = presenterManifest ? [...presenterManifest.steps] : undefined;
+
+  if (intro && expandedSteps.length > 0) {
+    const introDurationMs = intro.durationMs ?? TITLE_CARD_DURATION_DEFAULT_MS;
+    const firstAuthored = expandedSteps[0]!;
+    expandedSteps[0] = {
+      ...firstAuthored,
+      delayMs: Math.max(firstAuthored.delayMs, introDurationMs),
+    };
+    expandedSteps.unshift({
+      delayMs: 0,
+      data: cardStepData<T>(),
+      card: { kind: "intro", ...pickCardContent(intro) },
+    });
+    manifestEntries?.unshift(null);
+    presenterEntries?.unshift(null);
+  }
+
+  if (outro) {
+    expandedSteps.push({
+      delayMs: FINAL_DWELL_MS,
+      data: cardStepData<T>(),
+      card: { kind: "outro", ...pickCardContent(outro) },
+      interactions: [
+        { atPercent: 0, type: "clear_cursor" },
+        { atPercent: 0, type: "viewport_transition", viewportReset: true },
+      ],
+    });
+    manifestEntries?.push(null);
+    presenterEntries?.push(null);
+  }
+
+  return {
+    steps: expandedSteps,
+    narrationManifest: manifestEntries ? { steps: manifestEntries } : undefined,
+    presenterManifest: presenterEntries ? { steps: presenterEntries } : undefined,
+  };
+}
+
+/**
+ * Copy only the known card fields, so a config object carrying strays
+ * (e.g. a loosely-typed steps.ts export) never smuggles them into the
+ * step list.
+ */
+function pickCardContent(card: TitleCard): TitleCard {
+  const content: {
+    title: string;
+    subtitle?: string;
+    logoSrc?: string;
+    ctaText?: string;
+    durationMs?: number;
+  } = { title: card.title };
+  if (card.subtitle !== undefined) content.subtitle = card.subtitle;
+  if (card.logoSrc !== undefined) content.logoSrc = card.logoSrc;
+  if (card.ctaText !== undefined) content.ctaText = card.ctaText;
+  if (card.durationMs !== undefined) content.durationMs = card.durationMs;
+  return content;
+}

package/src/scenario/bundle.ts

@@ -8,6 +8,8 @@
  */
 
 import type { NarrationManifest } from "../narration/types.js";
+import type { PresenterManifest } from "../presenter/types.js";
+import type { Soundtrack } from "./soundtrack.js";
 import type { ScenarioStep } from "./types.js";
 
 /**
@@ -26,4 +28,17 @@ export interface ScenarioBundle<T> {
    * narration (timing is purely delay-based).
    */
   readonly narrationManifest?: NarrationManifest;
+  /**
+   * Audio treatment: background music with narration ducking and
+   * interaction sound effects.  When `undefined`, the scenario plays
+   * silent apart from narration.
+   */
+  readonly soundtrack?: Soundtrack;
+  /**
+   * Pre-built presenter manifest mapping step indices to avatar clip
+   * URLs and durations (generated by `scenar presenter`).  When
+   * `undefined`, the scenario plays without the presenter — zero
+   * presenter DOM, zero fetched bytes.
+   */
+  readonly presenterManifest?: PresenterManifest;
 }

package/src/scenario/soundtrack.ts

@@ -0,0 +1,47 @@
+/**
+ * The scenario's audio treatment beyond narration: optional background
+ * music with narration ducking, and optional interaction sound effects.
+ *
+ * Runtime mirror of the proto `SoundtrackConfig` (`ai.scenar.scenario.v1`),
+ * field for field, in camelCase — the same 1:1 relationship `StepAction`
+ * has with its proto message. Music and sound effects are independent:
+ * a scenario may use either without the other.
+ */
+export interface Soundtrack {
+  /**
+   * Background music asset reference. Like narration clip srcs, a
+   * relative path resolves against the scenario's own location; an
+   * absolute URL passes through unchanged. MP3 is the supported format.
+   * When `undefined`, the scenario has no music.
+   */
+  readonly musicSrc?: string;
+  /**
+   * Base music level while no narration is playing (0–1).
+   * Defaults to {@link MUSIC_VOLUME_DEFAULT}.
+   */
+  readonly musicVolume?: number;
+  /**
+   * Absolute music level while a narration clip plays (0–1) — the level
+   * the music ducks to, not a multiplier of {@link musicVolume}.
+   * Defaults to {@link DUCKING_VOLUME_DEFAULT}.
+   */
+  readonly duckingVolume?: number;
+  /**
+   * Enables the engine's built-in interaction sound effects (click and
+   * keystroke). Requires an explicit `true` — adding music alone never
+   * introduces sound effects.
+   */
+  readonly sfx?: boolean;
+}
+
+/**
+ * Default base music level. Clearly audible under silence without
+ * competing with interface sound effects.
+ */
+export const MUSIC_VOLUME_DEFAULT = 0.25;
+
+/**
+ * Default ducked music level while narration plays. Present but firmly
+ * under the voice.
+ */
+export const DUCKING_VOLUME_DEFAULT = 0.08;

package/src/scenario/title-cards.ts

@@ -0,0 +1,67 @@
+/**
+ * Intro and outro title cards framing a scenario.
+ *
+ * Runtime mirror of the proto `TitleCardsConfig` / `TitleCard`
+ * (`ai.scenar.scenario.v1`), field for field, in camelCase — the same
+ * 1:1 relationship `Soundtrack` has with its proto message.
+ *
+ * Cards are synthesized steps: {@link applyTitleCards} injects them
+ * into the step list at bundle assembly, so chapter markers, scrubbing,
+ * video duration, and the music envelope account for them with no
+ * card-specific timing code. The player renders card steps with its
+ * built-in card component — the scenario's render function is never
+ * called for them.
+ */
+
+/** One card's content — deliberately small; a card, not a page builder. */
+export interface TitleCard {
+  /** Headline text. The one required field. */
+  readonly title: string;
+  /** Supporting line rendered under the title. */
+  readonly subtitle?: string;
+  /**
+   * Logo image asset reference. Like narration and music srcs, a
+   * relative path resolves against the scenario's own location; an
+   * absolute URL passes through unchanged. Raster web formats only
+   * (png, jpg/jpeg, gif, webp, avif) — the deploy contract excludes
+   * svg as active content.
+   */
+  readonly logoSrc?: string;
+  /**
+   * Call-to-action text rendered as a distinct pill. Display-only —
+   * not a link. Typically used on the outro.
+   */
+  readonly ctaText?: string;
+  /**
+   * How long the card stays on screen, in milliseconds.
+   * Defaults to {@link TITLE_CARD_DURATION_DEFAULT_MS}.
+   */
+  readonly durationMs?: number;
+}
+
+/**
+ * The scenario-level card configuration: an intro card, an outro card,
+ * or both. Either field may be set independently; neither set is a no-op.
+ */
+export interface TitleCards {
+  /** Opening card shown before the first authored step. */
+  readonly intro?: TitleCard;
+  /** Closing card shown after the last authored step. */
+  readonly outro?: TitleCard;
+}
+
+/**
+ * The card marker carried by a synthesized card step
+ * ({@link ScenarioStep.card}). `kind` records which side of the
+ * scenario the card frames so the renderer can style intro and outro
+ * distinctly if it chooses.
+ */
+export interface StepCard extends TitleCard {
+  readonly kind: "intro" | "outro";
+}
+
+/**
+ * Default card visible time. Long enough to read a title and subtitle,
+ * short enough to not delay the content.
+ */
+export const TITLE_CARD_DURATION_DEFAULT_MS = 3_000;

package/src/scenario/types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { StepAction } from "./step-action.js";
+import type { StepCard } from "./title-cards.js";
 
 /**
  * A single step in a scenario timeline.
@@ -18,8 +19,12 @@ export interface ScenarioStep<T> {
   /** Data snapshot at this point in the timeline. */
   readonly data: T;
   /**
-   * Narration script for TTS generation. Consumed by the build script
-   * to produce audio files — not rendered at runtime.
+   * Narration script for this step. Consumed by `scenar narrate` to
+   * produce audio files, and rendered at runtime as the step's caption
+   * when the player has captions enabled (a presentation preference —
+   * the `captions` player prop, the `?captions=1` embed param, or
+   * `scenar render --captions`). Steps without narration play
+   * uncaptioned.
    */
   readonly narration?: string;
   /**
@@ -31,6 +36,22 @@ export interface ScenarioStep<T> {
    * share the same atPercent, they fire in array order.
    */
   readonly interactions?: readonly StepAction[];
+  /**
+   * Marks this step for the presenter track. When true, `scenar presenter`
+   * generates an avatar clip lip-synced to this step's narration audio,
+   * and both outputs show the clip picture-in-picture while the step is
+   * active — the interactive embed and the exported video alike.
+   *
+   * Requires `narration`: the presenter clip is derived from the step's
+   * narration audio by definition, so a step without narration cannot
+   * opt in (validated at load time).
+   *
+   * Playback never calls an AI service. Like narration audio, presenter
+   * clips are generated at compile time by the CLI and consumed as fixed
+   * assets through a positional manifest; a scenario whose clips have
+   * not been generated yet simply plays without the presenter.
+   */
+  readonly presenter?: boolean;
   /**
    * Names this step as a still-capture point for `scenar shoot`.
    *
@@ -47,4 +68,17 @@ export interface ScenarioStep<T> {
    * bundle. Steps without a `shot` are simply walked through.
    */
   readonly shot?: string;
+  /**
+   * Marks this step as an engine-synthesized title card. Only
+   * `applyTitleCards` constructs card steps — authors configure cards
+   * through the scenario-level `titleCards` config, never by hand.
+   *
+   * The player renders card steps with its built-in card component and
+   * never calls the scenario's render function for them, so a card
+   * step's `data` is a placeholder that is never read. Card steps
+   * announce activation through the player's `onCardStepChange`
+   * callback instead of `onStepChange` — the engine cannot fabricate a
+   * real `T` for the latter.
+   */
+  readonly card?: StepCard;
 }

package/src/timeline/compute-step-timeline.test.ts

@@ -57,4 +57,25 @@ describe("computeStepTimeline", () => {
     expect(tl.stepStartTimesMs).toEqual([0]);
     expect(tl.totalDurationMs).toBe(3000);
   });
+
+  it("uses a final card step's duration as the closing dwell", () => {
+    const tl = computeStepTimeline(
+      [{ delayMs: 0 }, { delayMs: 3000, card: { durationMs: 5000 } }],
+      null,
+    );
+    expect(tl.totalDurationMs).toBe(3000 + 5000);
+  });
+
+  it("falls back to the default dwell for a final card step without a duration", () => {
+    const tl = computeStepTimeline([{ delayMs: 0 }, { delayMs: 3000, card: {} }], null);
+    expect(tl.totalDurationMs).toBe(3000 + 3000);
+  });
+
+  it("ignores a non-final card step's duration for the closing dwell", () => {
+    const tl = computeStepTimeline(
+      [{ delayMs: 0, card: { durationMs: 9000 } }, { delayMs: 2000 }],
+      null,
+    );
+    expect(tl.totalDurationMs).toBe(2000 + 3000);
+  });
 });