@scenar/core 0.9.1 → 0.11.0

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

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

@@ -1,15 +1,34 @@
-import type { NarrationManifest } from "../narration/types.js";
-
 /**
  * Minimal step shape for timeline computation. Accepts any
- * ScenarioStep<T> without caring about the data payload.
+ * ScenarioStep<T> without caring about the data payload. The optional
+ * `card` marker participates because a synthesized outro card's
+ * duration IS the closing dwell (see below).
  */
 interface StepTiming {
   delayMs: number;
+  card?: { durationMs?: number };
 }
 
-/** Dwell time on the final step so viewers can absorb the result. */
-const FINAL_DWELL_MS = 3_000;
+/**
+ * Minimal manifest shape for timeline computation: any positional
+ * manifest whose entries carry a duration. Accepts the narration
+ * manifest, and — while the player is muted with a presenter track —
+ * the presenter manifest, whose clip durations equal the narration's
+ * for the same steps (the clip is derived from that audio). Feeding
+ * the presenter manifest to the muted timeline keeps the progress
+ * bar, scrubbing, and step advancement in agreement on presenter
+ * steps, and converges muted timing on the export timeline there.
+ */
+interface ManifestTiming {
+  readonly steps: readonly ({ readonly durationMs: number } | null | undefined)[];
+}
+
+/**
+ * Dwell time on the final step so viewers can absorb the result.
+ * Also the delay `applyTitleCards` gives a synthesized outro card, so
+ * the last authored step keeps exactly this dwell before the card.
+ */
+export const FINAL_DWELL_MS = 3_000;
 
 export interface StepTimeline {
   /** Start time of each step in milliseconds (index 0 is always 0). */
@@ -30,7 +49,7 @@ export interface StepTimeline {
  */
 export function computeStepTimeline(
   steps: readonly StepTiming[],
-  manifest: NarrationManifest | null | undefined,
+  manifest: ManifestTiming | null | undefined,
 ): StepTimeline {
   const stepStartTimesMs: number[] = [0];
 
@@ -43,7 +62,11 @@ export function computeStepTimeline(
 
   const lastStepStart = stepStartTimesMs[stepStartTimesMs.length - 1] ?? 0;
   const lastNarrationMs = manifest?.steps[steps.length - 1]?.durationMs ?? 0;
-  const totalDurationMs = lastStepStart + Math.max(FINAL_DWELL_MS, lastNarrationMs);
+  // A final card step (a synthesized outro) dwells for its configured
+  // duration instead of the fixed default — cards are silent, so the
+  // narration max is a no-op for them but kept for uniformity.
+  const closingDwellMs = steps[steps.length - 1]?.card?.durationMs ?? FINAL_DWELL_MS;
+  const totalDurationMs = lastStepStart + Math.max(closingDwellMs, lastNarrationMs);
 
   return { stepStartTimesMs, totalDurationMs };
 }

package/src/timeline/derive-action-events.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import type { StepAction } from "../scenario/step-action.js";
+import { deriveActionEvents, type ActionEvent } from "./derive-action-events.js";
+import {
+  CLICK_DELAY_MS,
+  DRAG_SETTLE_MS,
+  HOVER_HOLD_MS,
+  TYPE_CHAR_DELAY_MS,
+} from "../timing/constants.js";
+
+const DURATION = 2000;
+
+function offsets(events: ActionEvent[]): Record<string, number[]> {
+  const byKind: Record<string, number[]> = {};
+  for (const e of events) {
+    (byKind[e.kind] ??= []).push(e.offsetMs);
+  }
+  return byKind;
+}
+
+describe("deriveActionEvents", () => {
+  it("click: cursor move at fireAt, dispatch after the travel window", () => {
+    const action: StepAction = { atPercent: 0.5, type: "click", target: "btn" };
+    expect(offsets(deriveActionEvents(action, DURATION))).toEqual({
+      "cursor-move": [1000],
+      "click-dispatch": [1000 + CLICK_DELAY_MS],
+    });
+  });
+
+  it("type: one keystroke per character at the typing cadence", () => {
+    const action: StepAction = { atPercent: 0, type: "type", target: "input", text: "abc" };
+    const events = deriveActionEvents(action, DURATION);
+    const keystrokes = events.filter((e) => e.kind === "keystroke");
+
+    expect(events[0]).toEqual({ kind: "cursor-move", offsetMs: 0 });
+    expect(keystrokes).toEqual([
+      { kind: "keystroke", offsetMs: CLICK_DELAY_MS, charIndex: 0 },
+      { kind: "keystroke", offsetMs: CLICK_DELAY_MS + TYPE_CHAR_DELAY_MS, charIndex: 1 },
+      { kind: "keystroke", offsetMs: CLICK_DELAY_MS + 2 * TYPE_CHAR_DELAY_MS, charIndex: 2 },
+    ]);
+  });
+
+  it("type: honors a per-action typeDelay override", () => {
+    const action: StepAction = {
+      atPercent: 0,
+      type: "type",
+      target: "input",
+      text: "ab",
+      typeDelay: 120,
+    };
+    const keystrokes = deriveActionEvents(action, DURATION).filter(
+      (e) => e.kind === "keystroke",
+    );
+    expect(keystrokes.map((e) => e.offsetMs)).toEqual([
+      CLICK_DELAY_MS,
+      CLICK_DELAY_MS + 120,
+    ]);
+  });
+
+  it("type: empty text is a no-op, exactly like the schedulers", () => {
+    const action: StepAction = { atPercent: 0.5, type: "type", target: "input", text: "" };
+    expect(deriveActionEvents(action, DURATION)).toEqual([]);
+  });
+
+  it("type: unicode text counts UTF-16 code units, matching substring typing", () => {
+    // The schedulers type text.substring(0, i + 1) for i < text.length, so
+    // the derivation must count the same units — an emoji surrogate pair
+    // yields two keystrokes, one per code unit.
+    const action: StepAction = { atPercent: 0, type: "type", target: "input", text: "é🙂" };
+    const keystrokes = deriveActionEvents(action, DURATION).filter(
+      (e) => e.kind === "keystroke",
+    );
+    expect(keystrokes).toHaveLength("é🙂".length);
+  });
+
+  it("hover: enter after travel, leave after the hold", () => {
+    const action: StepAction = { atPercent: 0.25, type: "hover", target: "tip" };
+    expect(offsets(deriveActionEvents(action, DURATION))).toEqual({
+      "cursor-move": [500],
+      "hover-enter": [500 + CLICK_DELAY_MS],
+      "hover-leave": [500 + CLICK_DELAY_MS + HOVER_HOLD_MS],
+    });
+  });
+
+  it("hover: honors a per-action hoverDuration override", () => {
+    const action: StepAction = {
+      atPercent: 0,
+      type: "hover",
+      target: "tip",
+      hoverDuration: 200,
+    };
+    const leave = deriveActionEvents(action, DURATION).find((e) => e.kind === "hover-leave");
+    expect(leave?.offsetMs).toBe(CLICK_DELAY_MS + 200);
+  });
+
+  it("drag: press, move, release along the settle chain", () => {
+    const action: StepAction = {
+      atPercent: 0.1,
+      type: "drag",
+      target: "card",
+      dragTarget: "column",
+    };
+    expect(offsets(deriveActionEvents(action, DURATION))).toEqual({
+      "cursor-move": [200],
+      "drag-press": [200 + CLICK_DELAY_MS],
+      "drag-move": [200 + CLICK_DELAY_MS + DRAG_SETTLE_MS],
+      "drag-release": [200 + CLICK_DELAY_MS + DRAG_SETTLE_MS + CLICK_DELAY_MS],
+    });
+  });
+
+  it.each([
+    ["scroll_to", "list"],
+    ["set_cursor", "btn"],
+    ["clear_cursor", undefined],
+  ] as const)("%s: a single dispatch at fireAt", (type, target) => {
+    const action: StepAction = { atPercent: 0.5, type, target };
+    expect(deriveActionEvents(action, DURATION)).toEqual([
+      { kind: "simple-dispatch", offsetMs: 1000 },
+    ]);
+  });
+
+  it("viewport_transition: fires at fireAt with no travel delay", () => {
+    const action: StepAction = { atPercent: 0.5, type: "viewport_transition", target: "hero" };
+    expect(deriveActionEvents(action, DURATION)).toEqual([
+      { kind: "viewport-transition", offsetMs: 1000 },
+    ]);
+  });
+
+  it.each([
+    ["atPercent 0.0 anchors at step start", 0.0, 0],
+    ["atPercent 1.0 anchors at step end", 1.0, DURATION],
+  ])("%s", (_name, atPercent, expected) => {
+    const action: StepAction = { atPercent, type: "click", target: "btn" };
+    expect(deriveActionEvents(action, DURATION)[0]?.offsetMs).toBe(expected);
+  });
+
+  it("zero-duration step: every anchor collapses to the fixed offsets", () => {
+    const action: StepAction = { atPercent: 0.7, type: "click", target: "btn" };
+    expect(offsets(deriveActionEvents(action, 0))).toEqual({
+      "cursor-move": [0],
+      "click-dispatch": [CLICK_DELAY_MS],
+    });
+  });
+});