@scenar/core 0.10.0 → 0.11.0

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

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