@scenar/core 0.9.1 → 0.11.0

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

@@ -0,0 +1,116 @@
+import {
+  CLICK_DELAY_MS,
+  DRAG_SETTLE_MS,
+  HOVER_HOLD_MS,
+  TYPE_CHAR_DELAY_MS,
+} from "../timing/constants.js";
+import type { StepAction } from "../scenario/step-action.js";
+
+/**
+ * The observable sub-events of a step interaction, in the vocabulary the
+ * engine's effect layer uses: a `click` action is a cursor move followed
+ * by a click dispatch; a `type` action is a cursor move followed by one
+ * keystroke per character; and so on.
+ */
+export type ActionEventKind =
+  | "cursor-move"
+  | "click-dispatch"
+  | "keystroke"
+  | "hover-enter"
+  | "hover-leave"
+  | "drag-press"
+  | "drag-move"
+  | "drag-release"
+  | "viewport-transition"
+  | "simple-dispatch";
+
+/** One timed sub-event of a step interaction. */
+export interface ActionEvent {
+  readonly kind: ActionEventKind;
+  /**
+   * When this event fires, in milliseconds relative to the step's entry,
+   * at playback rate 1. Consumers scale for playback rate (the browser
+   * scheduler divides by rate; video export always runs at rate 1).
+   */
+  readonly offsetMs: number;
+  /** Zero-based character index. Present only on `keystroke` events. */
+  readonly charIndex?: number;
+}
+
+/**
+ * Derive the timed sub-events of a single step interaction — the
+ * canonical statement of the engine's event-offset math.
+ *
+ * The offsets below are the exact times at which the interaction
+ * schedulers in `@scenar/react` (`useBrowserStepInteractions`,
+ * `useTimeSourceStepInteractions`) dispatch their effects; parity tests
+ * in that package pin the schedulers to this derivation. Sound-effect
+ * placement (`deriveSfxTimeline`) is built on it, so a sound can never
+ * drift from the visual it accompanies.
+ *
+ * Pure function of its arguments: same action and duration, same events,
+ * in both browser playback and video export.
+ *
+ * @param action - The interaction to derive events for.
+ * @param stepDurationMs - The step's effective duration (see
+ *   `getStepDurationMs`); `atPercent` anchors against it.
+ */
+export function deriveActionEvents(
+  action: StepAction,
+  stepDurationMs: number,
+): ActionEvent[] {
+  const fireAt = action.atPercent * stepDurationMs;
+
+  switch (action.type) {
+    case "click":
+      return [
+        { kind: "cursor-move", offsetMs: fireAt },
+        { kind: "click-dispatch", offsetMs: fireAt + CLICK_DELAY_MS },
+      ];
+
+    case "type": {
+      const text = action.text ?? "";
+      // An empty type action is a no-op in the schedulers (not even a
+      // cursor move), so it derives no events.
+      if (text.length === 0) return [];
+      const charDelay = action.typeDelay ?? TYPE_CHAR_DELAY_MS;
+      const typingStart = fireAt + CLICK_DELAY_MS;
+      const events: ActionEvent[] = [{ kind: "cursor-move", offsetMs: fireAt }];
+      for (let i = 0; i < text.length; i++) {
+        events.push({
+          kind: "keystroke",
+          offsetMs: typingStart + i * charDelay,
+          charIndex: i,
+        });
+      }
+      return events;
+    }
+
+    case "hover": {
+      const holdMs = action.hoverDuration ?? HOVER_HOLD_MS;
+      return [
+        { kind: "cursor-move", offsetMs: fireAt },
+        { kind: "hover-enter", offsetMs: fireAt + CLICK_DELAY_MS },
+        { kind: "hover-leave", offsetMs: fireAt + CLICK_DELAY_MS + holdMs },
+      ];
+    }
+
+    case "drag":
+      return [
+        { kind: "cursor-move", offsetMs: fireAt },
+        { kind: "drag-press", offsetMs: fireAt + CLICK_DELAY_MS },
+        { kind: "drag-move", offsetMs: fireAt + CLICK_DELAY_MS + DRAG_SETTLE_MS },
+        {
+          kind: "drag-release",
+          offsetMs: fireAt + CLICK_DELAY_MS + DRAG_SETTLE_MS + CLICK_DELAY_MS,
+        },
+      ];
+
+    case "viewport_transition":
+      return [{ kind: "viewport-transition", offsetMs: fireAt }];
+
+    // scroll_to, set_cursor, clear_cursor: a single dispatch at fireAt.
+    default:
+      return [{ kind: "simple-dispatch", offsetMs: fireAt }];
+  }
+}

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

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import type { NarrationManifest } from "../narration/types.js";
+import type { ScenarioStep } from "../scenario/types.js";
+import type { StepAction } from "../scenario/step-action.js";
+import { deriveSfxTimeline } from "./derive-sfx-timeline.js";
+import {
+  CLICK_DELAY_MS,
+  DRAG_SETTLE_MS,
+  TYPE_CHAR_DELAY_MS,
+} from "../timing/constants.js";
+
+function step(
+  delayMs: number,
+  interactions?: StepAction[],
+): ScenarioStep<Record<string, never>> {
+  return { delayMs, data: {}, interactions };
+}
+
+describe("deriveSfxTimeline", () => {
+  it("returns no events for a scenario without interactions", () => {
+    expect(deriveSfxTimeline([step(0), step(1000)], undefined)).toEqual([]);
+  });
+
+  it("click yields one click sound at the dispatch moment", () => {
+    const steps = [
+      step(0, [{ atPercent: 0.5, type: "click", target: "btn" }]),
+      step(2000),
+    ];
+    // Step 0's duration is the next step's delayMs (2000) — no narration.
+    expect(deriveSfxTimeline(steps, undefined)).toEqual([
+      { stepIndex: 0, offsetMs: 1000 + CLICK_DELAY_MS, sound: "click" },
+    ]);
+  });
+
+  it("typing yields one keystroke sound per character", () => {
+    const steps = [
+      step(0, [{ atPercent: 0, type: "type", target: "input", text: "hi" }]),
+      step(1000),
+    ];
+    expect(deriveSfxTimeline(steps, undefined)).toEqual([
+      { stepIndex: 0, offsetMs: CLICK_DELAY_MS, sound: "keystroke" },
+      { stepIndex: 0, offsetMs: CLICK_DELAY_MS + TYPE_CHAR_DELAY_MS, sound: "keystroke" },
+    ]);
+  });
+
+  it("drag yields click sounds at press and release, nothing between", () => {
+    const steps = [
+      step(0, [{ atPercent: 0, type: "drag", target: "card", dragTarget: "col" }]),
+      step(1000),
+    ];
+    expect(deriveSfxTimeline(steps, undefined)).toEqual([
+      { stepIndex: 0, offsetMs: CLICK_DELAY_MS, sound: "click" },
+      {
+        stepIndex: 0,
+        offsetMs: CLICK_DELAY_MS + DRAG_SETTLE_MS + CLICK_DELAY_MS,
+        sound: "click",
+      },
+    ]);
+  });
+
+  it.each([
+    ["hover", { atPercent: 0.5, type: "hover", target: "tip" } as StepAction],
+    ["scroll_to", { atPercent: 0.5, type: "scroll_to", target: "list" } as StepAction],
+    ["set_cursor", { atPercent: 0, type: "set_cursor", target: "btn" } as StepAction],
+    ["clear_cursor", { atPercent: 1, type: "clear_cursor" } as StepAction],
+    [
+      "viewport_transition",
+      { atPercent: 0.5, type: "viewport_transition", target: "hero" } as StepAction,
+    ],
+  ])("%s stays silent", (_name, action) => {
+    const steps = [step(0, [action]), step(1000)];
+    expect(deriveSfxTimeline(steps, undefined)).toEqual([]);
+  });
+
+  it("narration duration anchors offsets when a clip exists", () => {
+    const steps = [
+      step(0, [{ atPercent: 0.5, type: "click", target: "btn" }]),
+      step(500),
+    ];
+    const manifest: NarrationManifest = {
+      steps: [{ src: "./step-0.mp3", durationMs: 4000 }, null],
+    };
+    // Duration comes from the clip (4000), not the next delay (500).
+    expect(deriveSfxTimeline(steps, manifest)).toEqual([
+      { stepIndex: 0, offsetMs: 2000 + CLICK_DELAY_MS, sound: "click" },
+    ]);
+  });
+
+  it("orders events by step, then by offset within the step", () => {
+    const steps = [
+      step(0, [
+        // Authored out of time order within the step.
+        { atPercent: 0.8, type: "click", target: "b" },
+        { atPercent: 0.1, type: "click", target: "a" },
+      ]),
+      step(1000, [{ atPercent: 0, type: "click", target: "c" }]),
+      step(1000),
+    ];
+    const events = deriveSfxTimeline(steps, undefined);
+    expect(events.map((e) => [e.stepIndex, e.offsetMs])).toEqual([
+      [0, 100 + CLICK_DELAY_MS],
+      [0, 800 + CLICK_DELAY_MS],
+      [1, CLICK_DELAY_MS],
+    ]);
+  });
+
+  it("last step uses the engine's fallback duration", () => {
+    const steps = [step(0, [{ atPercent: 1, type: "click", target: "btn" }])];
+    // Single-step scenario: getStepDurationMs falls back to 3000.
+    expect(deriveSfxTimeline(steps, undefined)).toEqual([
+      { stepIndex: 0, offsetMs: 3000 + CLICK_DELAY_MS, sound: "click" },
+    ]);
+  });
+});

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

@@ -0,0 +1,79 @@
+import type { NarrationManifest } from "../narration/types.js";
+import type { ScenarioStep } from "../scenario/types.js";
+import { getStepDurationMs } from "./step-duration.js";
+import { deriveActionEvents, type ActionEventKind } from "./derive-action-events.js";
+
+/**
+ * The engine's built-in sound-effect vocabulary. Deliberately minimal:
+ * a click sound and a keystroke sound sell realism; everything else
+ * (hover, scroll, camera moves) stays silent.
+ */
+export type SfxSound = "click" | "keystroke";
+
+/** One sound effect placed on the scenario timeline. */
+export interface SfxEvent {
+  /** The step during which this sound fires. */
+  readonly stepIndex: number;
+  /**
+   * When the sound fires, in milliseconds relative to the step's entry,
+   * at playback rate 1 — the same time base as `ActionEvent.offsetMs`,
+   * so the sound and the visual it accompanies share one clock.
+   */
+  readonly offsetMs: number;
+  readonly sound: SfxSound;
+}
+
+/**
+ * Which action sub-events make a sound. Click dispatches and drag
+ * press/release share the click sound (a drag is a press and a release);
+ * each typed character gets a keystroke sound.
+ */
+const SOUND_BY_EVENT_KIND: Partial<Record<ActionEventKind, SfxSound>> = {
+  "click-dispatch": "click",
+  "drag-press": "click",
+  "drag-release": "click",
+  keystroke: "keystroke",
+};
+
+/**
+ * Derive every sound effect in the scenario from its interactions —
+ * placement is computed, never authored.
+ *
+ * Built on `deriveActionEvents`, so each sound fires at the exact moment
+ * its interaction dispatches: the click sound when the DOM click fires
+ * (after the cursor's travel window), one keystroke sound per typed
+ * character at the typing cadence, click sounds at drag press and
+ * release. Consumers place the events: video export converts offsets to
+ * absolute frames via the step timeline; browser playback schedules them
+ * on step entry, exactly like the interaction schedulers.
+ *
+ * Events are ordered by step, then by offset within the step.
+ */
+export function deriveSfxTimeline<T>(
+  steps: readonly ScenarioStep<T>[],
+  manifest: NarrationManifest | undefined,
+): SfxEvent[] {
+  const events: SfxEvent[] = [];
+
+  for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
+    const actions = steps[stepIndex]?.interactions;
+    if (!actions || actions.length === 0) continue;
+
+    const duration = getStepDurationMs(stepIndex, manifest, steps);
+    const stepEvents: SfxEvent[] = [];
+
+    for (const action of actions) {
+      for (const event of deriveActionEvents(action, duration)) {
+        const sound = SOUND_BY_EVENT_KIND[event.kind];
+        if (sound) {
+          stepEvents.push({ stepIndex, offsetMs: event.offsetMs, sound });
+        }
+      }
+    }
+
+    stepEvents.sort((a, b) => a.offsetMs - b.offsetMs);
+    events.push(...stepEvents);
+  }
+
+  return events;
+}

package/src/timeline/music-envelope.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import type { NarrationManifest } from "../narration/types.js";
+import { MUSIC_VOLUME_DEFAULT, DUCKING_VOLUME_DEFAULT } from "../scenario/soundtrack.js";
+import {
+  DUCKING_RAMP_MS,
+  MUSIC_FADE_IN_MS,
+  MUSIC_FADE_OUT_MS,
+  computeMusicEnvelope,
+  musicGainAt,
+} from "./music-envelope.js";
+
+/**
+ * Two steps: step 0 narrated for 5 s, step 1 silent. Timeline:
+ * step 0 at 0, step 1 at 5000 (narration outlasts its 1000 delay),
+ * total 5000 + FINAL_DWELL(3000) = 8000. Ducking window [0, 5000].
+ */
+const STEPS = [{ delayMs: 0 }, { delayMs: 1000 }];
+const MANIFEST: NarrationManifest = {
+  steps: [{ src: "./step-0.mp3", durationMs: 5000 }, null],
+};
+
+describe("computeMusicEnvelope", () => {
+  it("derives one ducking window per narrated step from the shared timeline", () => {
+    const envelope = computeMusicEnvelope(STEPS, MANIFEST, {});
+    expect(envelope.duckingWindows).toEqual([{ startMs: 0, endMs: 5000 }]);
+    expect(envelope.totalDurationMs).toBe(8000);
+  });
+
+  it("resolves unset volumes to the engine defaults", () => {
+    const envelope = computeMusicEnvelope(STEPS, MANIFEST, {});
+    expect(envelope.musicVolume).toBe(MUSIC_VOLUME_DEFAULT);
+    expect(envelope.duckingVolume).toBe(DUCKING_VOLUME_DEFAULT);
+  });
+
+  it("honors explicit volumes, including 0.0", () => {
+    const envelope = computeMusicEnvelope(STEPS, MANIFEST, {
+      musicVolume: 0.6,
+      duckingVolume: 0,
+    });
+    expect(envelope.musicVolume).toBe(0.6);
+    expect(envelope.duckingVolume).toBe(0);
+  });
+
+  it("no narration manifest means no ducking windows", () => {
+    const envelope = computeMusicEnvelope(STEPS, undefined, {});
+    expect(envelope.duckingWindows).toEqual([]);
+  });
+
+  it("skips zero-duration narration entries", () => {
+    const manifest: NarrationManifest = {
+      steps: [{ src: "./step-0.mp3", durationMs: 0 }, null],
+    };
+    expect(computeMusicEnvelope(STEPS, manifest, {}).duckingWindows).toEqual([]);
+  });
+});
+
+describe("musicGainAt", () => {
+  // A silent-scenario envelope isolates fades from ducking:
+  // no manifest, total 1000(delay) + 3000(dwell) = 4000.
+  const noDuckEnvelope = computeMusicEnvelope(STEPS, undefined, { musicVolume: 0.5 });
+
+  it("is 0 outside the scenario", () => {
+    expect(musicGainAt(noDuckEnvelope, -1)).toBe(0);
+    expect(musicGainAt(noDuckEnvelope, noDuckEnvelope.totalDurationMs + 1)).toBe(0);
+  });
+
+  it("fades in from silence to the base level", () => {
+    expect(musicGainAt(noDuckEnvelope, 0)).toBe(0);
+    expect(musicGainAt(noDuckEnvelope, MUSIC_FADE_IN_MS / 2)).toBeCloseTo(0.25, 10);
+    expect(musicGainAt(noDuckEnvelope, MUSIC_FADE_IN_MS)).toBeCloseTo(0.5, 10);
+  });
+
+  it("fades out to silence over the closing window", () => {
+    const total = noDuckEnvelope.totalDurationMs;
+    expect(musicGainAt(noDuckEnvelope, total - MUSIC_FADE_OUT_MS / 2)).toBeCloseTo(0.25, 10);
+    expect(musicGainAt(noDuckEnvelope, total)).toBe(0);
+  });
+
+  it("holds the base level on the plateau between fades", () => {
+    expect(musicGainAt(noDuckEnvelope, 1000)).toBeCloseTo(0.5, 10);
+  });
+
+  // Ducking assertions use a window clear of both fades: step 1 narrated
+  // 2000 → window [4000, 6000]; the trailing 8000-delay step pushes the
+  // total to 15000, so the fade-out ([12000, 15000]) can't overlap it.
+  const duckSteps = [{ delayMs: 0 }, { delayMs: 4000 }, { delayMs: 8000 }];
+  const duckManifest: NarrationManifest = {
+    steps: [null, { src: "./step-1.mp3", durationMs: 2000 }, null],
+  };
+  const duckEnvelope = computeMusicEnvelope(duckSteps, duckManifest, {
+    musicVolume: 0.5,
+    duckingVolume: 0.1,
+  });
+
+  it("is fully ducked while the narration clip plays", () => {
+    expect(musicGainAt(duckEnvelope, 4000)).toBeCloseTo(0.1, 10);
+    expect(musicGainAt(duckEnvelope, 5000)).toBeCloseTo(0.1, 10);
+    expect(musicGainAt(duckEnvelope, 6000)).toBeCloseTo(0.1, 10);
+  });
+
+  it("completes the down-ramp at voice onset (pre-duck)", () => {
+    const rampStart = 4000 - DUCKING_RAMP_MS;
+    expect(musicGainAt(duckEnvelope, rampStart)).toBeCloseTo(0.5, 10);
+    expect(musicGainAt(duckEnvelope, rampStart + DUCKING_RAMP_MS / 2)).toBeCloseTo(0.3, 10);
+  });
+
+  it("ramps back to the base level after the clip ends", () => {
+    expect(musicGainAt(duckEnvelope, 6000 + DUCKING_RAMP_MS / 2)).toBeCloseTo(0.3, 10);
+    expect(musicGainAt(duckEnvelope, 6000 + DUCKING_RAMP_MS)).toBeCloseTo(0.5, 10);
+  });
+
+  it("overlapping windows take the deepest duck", () => {
+    // Two narrated steps whose windows adjoin: the boundary sample sits in
+    // window 0's up-ramp AND window 1's plateau — the plateau (deeper) wins.
+    const steps = [{ delayMs: 0 }, { delayMs: 0 }, { delayMs: 4000 }];
+    const manifest: NarrationManifest = {
+      steps: [
+        { src: "./step-0.mp3", durationMs: 3000 },
+        { src: "./step-1.mp3", durationMs: 3000 },
+        null,
+      ],
+    };
+    const envelope = computeMusicEnvelope(steps, manifest, {
+      musicVolume: 0.5,
+      duckingVolume: 0.1,
+    });
+    // Windows: [0, 3000] and [3000, 6000] — inside window 0's up-ramp zone.
+    expect(musicGainAt(envelope, 3000 + DUCKING_RAMP_MS / 2)).toBeCloseTo(0.1, 10);
+  });
+
+  it("a ducking window during the fade-in multiplies both factors", () => {
+    // duckEnvelope's fade-in covers [0, 1000]; window starts at 4000 — use
+    // an envelope whose narration starts at 0 instead.
+    const envelope = computeMusicEnvelope(STEPS, MANIFEST, {
+      musicVolume: 0.5,
+      duckingVolume: 0.1,
+    });
+    // At 500ms: ducked level 0.1 × fade-in factor 0.5.
+    expect(musicGainAt(envelope, MUSIC_FADE_IN_MS / 2)).toBeCloseTo(0.05, 10);
+  });
+});

package/src/timeline/music-envelope.ts

@@ -0,0 +1,131 @@
+import type { NarrationManifest } from "../narration/types.js";
+import {
+  DUCKING_VOLUME_DEFAULT,
+  MUSIC_VOLUME_DEFAULT,
+  type Soundtrack,
+} from "../scenario/soundtrack.js";
+import { computeStepTimeline } from "./compute-step-timeline.js";
+
+/**
+ * Milliseconds over which the music fades in from silence at scenario
+ * start. Long enough to feel intentional, short enough that the opening
+ * step is never dry.
+ */
+export const MUSIC_FADE_IN_MS = 1_000;
+
+/**
+ * Milliseconds over which the music fades out at the end of the
+ * scenario. Matches the final-dwell window the timeline already reserves
+ * after the last step, so the video never ends on a hard musical cut.
+ */
+export const MUSIC_FADE_OUT_MS = 3_000;
+
+/**
+ * Milliseconds the music takes to ramp between its base level and its
+ * ducked level at each narration boundary. The ramp completes as the
+ * voice starts (pre-duck) so narration onset is never fighting the ramp;
+ * felt, not heard as a cut.
+ */
+export const DUCKING_RAMP_MS = 300;
+
+/** A span of the scenario timeline during which a narration clip plays. */
+export interface DuckingWindow {
+  readonly startMs: number;
+  readonly endMs: number;
+}
+
+/**
+ * Everything needed to compute the music level at any point on the
+ * scenario timeline. Precomputed once per scenario; `musicGainAt` reads
+ * it per sample/frame without allocating.
+ */
+export interface MusicEnvelope {
+  /** Resolved base music level (0–1). */
+  readonly musicVolume: number;
+  /** Resolved ducked music level while narration plays (0–1). */
+  readonly duckingVolume: number;
+  /** Total scenario duration, from `computeStepTimeline`. */
+  readonly totalDurationMs: number;
+  /** Narration clip spans on the timeline, in step order. */
+  readonly duckingWindows: readonly DuckingWindow[];
+}
+
+/**
+ * Precompute the music envelope for a scenario: resolved volume levels
+ * plus the narration windows the music ducks under.
+ *
+ * The windows derive from the same `computeStepTimeline` both output
+ * paths already share — a clip for step N spans from that step's start
+ * for the clip's duration — so ducking agrees with narration placement
+ * by construction, in browser playback and video export alike.
+ */
+export function computeMusicEnvelope(
+  steps: readonly { delayMs: number }[],
+  manifest: NarrationManifest | null | undefined,
+  soundtrack: Soundtrack,
+): MusicEnvelope {
+  const { stepStartTimesMs, totalDurationMs } = computeStepTimeline(steps, manifest);
+
+  const duckingWindows: DuckingWindow[] = [];
+  if (manifest) {
+    for (let i = 0; i < steps.length; i++) {
+      const durationMs = manifest.steps[i]?.durationMs ?? 0;
+      if (durationMs > 0) {
+        const startMs = stepStartTimesMs[i] ?? 0;
+        duckingWindows.push({ startMs, endMs: startMs + durationMs });
+      }
+    }
+  }
+
+  return {
+    musicVolume: soundtrack.musicVolume ?? MUSIC_VOLUME_DEFAULT,
+    duckingVolume: soundtrack.duckingVolume ?? DUCKING_VOLUME_DEFAULT,
+    totalDurationMs,
+    duckingWindows,
+  };
+}
+
+/**
+ * The music level at a point on the scenario timeline (0–1).
+ *
+ * Composed of three factors:
+ * - a fade-in from silence over {@link MUSIC_FADE_IN_MS} at the start,
+ * - a fade-out to silence over {@link MUSIC_FADE_OUT_MS} at the end,
+ * - narration ducking: at the base level away from narration, at the
+ *   ducked level while a clip plays, ramping over {@link DUCKING_RAMP_MS}
+ *   into each window (completing at voice onset) and out after it ends.
+ *
+ * Pure and allocation-free: the browser applies it through Web Audio
+ * gain automation, video export as a per-frame volume function. Outside
+ * the scenario ([0, totalDurationMs]) the level is 0.
+ */
+export function musicGainAt(envelope: MusicEnvelope, timeMs: number): number {
+  const { musicVolume, duckingVolume, totalDurationMs, duckingWindows } = envelope;
+  if (timeMs < 0 || timeMs > totalDurationMs) return 0;
+
+  // Ducked-ness in [0, 1]: 0 at the base level, 1 fully ducked. Overlapping
+  // windows take the deepest value.
+  let ducked = 0;
+  for (const window of duckingWindows) {
+    const rampInStart = window.startMs - DUCKING_RAMP_MS;
+    if (timeMs < rampInStart || timeMs > window.endMs + DUCKING_RAMP_MS) continue;
+
+    let d: number;
+    if (timeMs < window.startMs) {
+      d = (timeMs - rampInStart) / DUCKING_RAMP_MS;
+    } else if (timeMs <= window.endMs) {
+      d = 1;
+    } else {
+      d = 1 - (timeMs - window.endMs) / DUCKING_RAMP_MS;
+    }
+    if (d > ducked) ducked = d;
+    if (ducked === 1) break;
+  }
+
+  const level = musicVolume + (duckingVolume - musicVolume) * ducked;
+
+  const fadeIn = Math.min(1, timeMs / MUSIC_FADE_IN_MS);
+  const fadeOut = Math.min(1, (totalDurationMs - timeMs) / MUSIC_FADE_OUT_MS);
+
+  return level * fadeIn * fadeOut;
+}

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

@@ -1,11 +1,36 @@
-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;
+    };
 }
+/**
+ * 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 declare const FINAL_DWELL_MS = 3000;
 export interface StepTimeline {
     /** Start time of each step in milliseconds (index 0 is always 0). */
     stepStartTimesMs: number[];
@@ -22,6 +47,6 @@ export interface StepTimeline {
  * Shared between browser ScenarioPlayer (progress bar) and Remotion
  * video export (frame-based timeline).
  */
-export declare function computeStepTimeline(steps: readonly StepTiming[], manifest: NarrationManifest | null | undefined): StepTimeline;
+export declare function computeStepTimeline(steps: readonly StepTiming[], manifest: ManifestTiming | null | undefined): StepTimeline;
 export {};
 //# sourceMappingURL=compute-step-timeline.d.ts.map

package/timeline/compute-step-timeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compute-step-timeline.d.ts","sourceRoot":"","sources":["../../src/timeline/compute-step-timeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D;;;GAGG;AACH,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,QAAQ,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAC7C,YAAY,CAed"}
+{"version":3,"file":"compute-step-timeline.d.ts","sourceRoot":"","sources":["../../src/timeline/compute-step-timeline.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,UAAU,cAAc;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;CACjF;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,OAAQ,CAAC;AAEpC,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAC1C,YAAY,CAmBd"}

package/timeline/compute-step-timeline.js

@@ -1,5 +1,9 @@
-/** Dwell time on the final step so viewers can absorb the result. */
-const FINAL_DWELL_MS = 3_000;
+/**
+ * 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;
 /**
  * Pre-compute step start times and total duration from step definitions
  * and an optional narration manifest.
@@ -20,7 +24,11 @@ export function computeStepTimeline(steps, manifest) {
     }
     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 };
 }
 //# sourceMappingURL=compute-step-timeline.js.map

package/timeline/compute-step-timeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"compute-step-timeline.js","sourceRoot":"","sources":["../../src/timeline/compute-step-timeline.ts"],"names":[],"mappings":"AAUA,qEAAqE;AACrE,MAAM,cAAc,GAAG,KAAK,CAAC;AAS7B;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA4B,EAC5B,QAA8C;IAE9C,MAAM,gBAAgB,GAAa,CAAC,CAAC,CAAC,CAAC;IAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;QAC3C,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC;QACpC,MAAM,WAAW,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC;QAC5D,gBAAgB,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,aAAa,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IACzE,MAAM,eAAe,GAAG,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC;IAC3E,MAAM,eAAe,GAAG,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;IAElF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"compute-step-timeline.js","sourceRoot":"","sources":["../../src/timeline/compute-step-timeline.ts"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC;AASpC;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA4B,EAC5B,QAA2C;IAE3C,MAAM,gBAAgB,GAAa,CAAC,CAAC,CAAC,CAAC;IAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;QAC3C,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC;QACpC,MAAM,WAAW,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC;QAC5D,gBAAgB,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,aAAa,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IACzE,MAAM,eAAe,GAAG,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC;IAC3E,oEAAoE;IACpE,mEAAmE;IACnE,6DAA6D;IAC7D,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACnF,MAAM,eAAe,GAAG,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;IAElF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAC/C,CAAC"}