@scenar/core 0.10.0 → 0.11.0

package/scenario/title-cards.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 declare const TITLE_CARD_DURATION_DEFAULT_MS = 3000;
+//# sourceMappingURL=title-cards.d.ts.map

package/scenario/title-cards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"title-cards.d.ts","sourceRoot":"","sources":["../../src/scenario/title-cards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,SAAS;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;CAClC;AAED;;;GAGG;AACH,eAAO,MAAM,8BAA8B,OAAQ,CAAC"}

package/scenario/title-cards.js

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+//# sourceMappingURL=title-cards.js.map

package/scenario/title-cards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"title-cards.js","sourceRoot":"","sources":["../../src/scenario/title-cards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiDH;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,KAAK,CAAC"}

package/scenario/types.d.ts

@@ -5,6 +5,7 @@
  * playback engine. They are framework-agnostic — no React, no DOM.
  */
 import type { StepAction } from "./step-action.js";
+import type { StepCard } from "./title-cards.js";
 /**
  * A single step in a scenario timeline.
  *
@@ -16,8 +17,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;
     /**
@@ -29,6 +34,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`.
      *
@@ -45,5 +66,18 @@ 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;
 }
 //# sourceMappingURL=types.d.ts.map

package/scenario/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scenario/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scenario/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;CAC1B"}

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,

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