@scenar/core 0.10.0 → 0.11.0

package/index.d.ts

@@ -1,15 +1,31 @@
 export type { ScenarioStep } from "./scenario/types.js";
 export type { ScenarioBundle } from "./scenario/bundle.js";
 export type { ActionType, StepAction, UseStepInteractionsOptions, } from "./scenario/step-action.js";
+export type { Soundtrack } from "./scenario/soundtrack.js";
+export { MUSIC_VOLUME_DEFAULT, DUCKING_VOLUME_DEFAULT, } from "./scenario/soundtrack.js";
+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";
 export type { NarrationEntry, NarrationManifest } from "./narration/types.js";
+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";
 export type { ViewportTransform, ViewportCameraMove } from "./viewport/transform.js";
 export { VIEWPORT_TRANSFORM_IDENTITY, VIEWPORT_CAMERA_AT_REST, cameraEase, interpolateViewportTransform, } from "./viewport/transform.js";
 export type { Position } from "./cursor/compute-position.js";
 export { computeCursorPosition } from "./cursor/compute-position.js";
 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, collectScenarioShots, collectShotNames, } from "./timeline/collect-shots.js";
 export { CLICK_DELAY_MS, TYPE_CHAR_DELAY_MS, HOVER_HOLD_MS, DRAG_SETTLE_MS, CAMERA_TRANSITION_MS, VIEWPORT_SETTLE_MS, } from "./timing/constants.js";

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EACV,UAAU,EACV,UAAU,EACV,0BAA0B,GAC3B,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,UAAU,EACV,4BAA4B,GAC7B,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,YAAY,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EACV,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/index.js

@@ -1,10 +1,18 @@
 // @scenar/core — public API
 // Pure TypeScript types, timing, and utilities for scenario playback.
+export { MUSIC_VOLUME_DEFAULT, DUCKING_VOLUME_DEFAULT, } from "./scenario/soundtrack.js";
+export { TITLE_CARD_DURATION_DEFAULT_MS } from "./scenario/title-cards.js";
+export { applyTitleCards } from "./scenario/apply-title-cards.js";
+export { derivePresenterTimeline } from "./presenter/derive-presenter-timeline.js";
+export { PRESENTER_FADE_MS, presenterOpacityAt } from "./presenter/presenter-opacity.js";
 export { VIEWPORT_TRANSFORM_IDENTITY, VIEWPORT_CAMERA_AT_REST, cameraEase, interpolateViewportTransform, } from "./viewport/transform.js";
 export { computeCursorPosition } from "./cursor/compute-position.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 { deriveActionEvents } from "./timeline/derive-action-events.js";
+export { deriveSfxTimeline } from "./timeline/derive-sfx-timeline.js";
+export { MUSIC_FADE_IN_MS, MUSIC_FADE_OUT_MS, DUCKING_RAMP_MS, computeMusicEnvelope, musicGainAt, } from "./timeline/music-envelope.js";
 export { SHOT_NAME_PATTERN, collectScenarioShots, collectShotNames, } from "./timeline/collect-shots.js";
 // Timing constants
 export { CLICK_DELAY_MS, TYPE_CHAR_DELAY_MS, HOVER_HOLD_MS, DRAG_SETTLE_MS, CAMERA_TRANSITION_MS, VIEWPORT_SETTLE_MS, } from "./timing/constants.js";

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,sEAAsE;AAgBtE,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,UAAU,EACV,4BAA4B,GAC7B,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAIrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AAErC,mBAAmB;AACnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,uBAAuB;AACvB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,oCAAoC;AACpC,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAExC,0EAA0E;AAC1E,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAS7B,uEAAuE;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,sEAAsE;AAatE,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAIlC,OAAO,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAE3E,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAQlE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAIzF,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,UAAU,EACV,4BAA4B,GAC7B,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAIrE,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAExE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAEtE,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,WAAW,GACZ,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AAErC,mBAAmB;AACnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,uBAAuB;AACvB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,oCAAoC;AACpC,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAExC,0EAA0E;AAC1E,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAS7B,uEAAuE;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenar/core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Pure TypeScript types, timing, and utilities for the Scenar scenario engine.",
   "license": "Apache-2.0",
   "type": "module",

package/presenter/derive-presenter-timeline.d.ts

@@ -0,0 +1,36 @@
+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 declare function derivePresenterTimeline(presenterManifest: PresenterManifest | undefined, stepTimeline: StepTimeline): readonly PresenterWindow[];
+//# sourceMappingURL=derive-presenter-timeline.d.ts.map

package/presenter/derive-presenter-timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-presenter-timeline.d.ts","sourceRoot":"","sources":["../../src/presenter/derive-presenter-timeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,iBAAiB,EAAE,iBAAiB,GAAG,SAAS,EAChD,YAAY,EAAE,YAAY,GACzB,SAAS,eAAe,EAAE,CAc5B"}

package/presenter/derive-presenter-timeline.js

@@ -0,0 +1,31 @@
+/**
+ * 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, stepTimeline) {
+    if (!presenterManifest)
+        return [];
+    const windows = [];
+    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;
+}
+//# sourceMappingURL=derive-presenter-timeline.js.map

package/presenter/derive-presenter-timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-presenter-timeline.js","sourceRoot":"","sources":["../../src/presenter/derive-presenter-timeline.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CACrC,iBAAgD,EAChD,YAA0B;IAE1B,IAAI,CAAC,iBAAiB;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,OAAO,GAAsB,EAAE,CAAC;IACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9D,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,OAAO,CAAC,IAAI,CAAC;YACX,SAAS,EAAE,CAAC;YACZ,OAAO,EAAE,YAAY,CAAC,gBAAgB,CAAC,CAAC,CAAE;YAC1C,cAAc,EAAE,KAAK,CAAC,UAAU;SACjC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/presenter/presenter-opacity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare 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 declare function presenterOpacityAt(intraStepMs: number, clipDurationMs: number): number;
+//# sourceMappingURL=presenter-opacity.d.ts.map

package/presenter/presenter-opacity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presenter-opacity.d.ts","sourceRoot":"","sources":["../../src/presenter/presenter-opacity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GACrB,MAAM,CAOR"}

package/presenter/presenter-opacity.js

@@ -0,0 +1,40 @@
+/**
+ * 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, clipDurationMs) {
+    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);
+}
+//# sourceMappingURL=presenter-opacity.js.map

package/presenter/presenter-opacity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presenter-opacity.js","sourceRoot":"","sources":["../../src/presenter/presenter-opacity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,cAAsB;IAEtB,IAAI,cAAc,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,IAAI,WAAW,IAAI,CAAC,IAAI,WAAW,IAAI,cAAc;QAAE,OAAO,CAAC,CAAC;IAEhE,MAAM,MAAM,GAAG,WAAW,GAAG,iBAAiB,CAAC;IAC/C,MAAM,OAAO,GAAG,CAAC,cAAc,GAAG,WAAW,CAAC,GAAG,iBAAiB,CAAC;IACnE,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/presenter/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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)[];
+}
+//# sourceMappingURL=types.d.ts.map

package/presenter/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/presenter/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,EAAE,CAAC;CACpD"}

package/presenter/types.js

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/presenter/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/presenter/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

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

@@ -0,0 +1,53 @@
+/**
+ * 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 type { ScenarioStep } from "./types.js";
+import { 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;
+}
+/**
+ * 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 declare function applyTitleCards<T>(steps: readonly ScenarioStep<T>[], narrationManifest: NarrationManifest | undefined, titleCards: TitleCards | undefined, presenterManifest?: PresenterManifest): AppliedTitleCards<T>;
+//# sourceMappingURL=apply-title-cards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"apply-title-cards.d.ts","sourceRoot":"","sources":["../../src/scenario/apply-title-cards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAE1B,wEAAwE;AACxE,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3C,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,GAAG,SAAS,CAAC;CAC3D;AAYD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,EACjC,iBAAiB,EAAE,iBAAiB,GAAG,SAAS,EAChD,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,iBAAiB,CAAC,CAAC,CAAC,CA8CtB"}

package/scenario/apply-title-cards.js

@@ -0,0 +1,113 @@
+/**
+ * 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 { FINAL_DWELL_MS } from "../timeline/compute-step-timeline.js";
+import { TITLE_CARD_DURATION_DEFAULT_MS, } from "./title-cards.js";
+/**
+ * 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() {
+    return undefined;
+}
+/**
+ * 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(steps, narrationManifest, titleCards, presenterManifest) {
+    const intro = titleCards?.intro;
+    const outro = titleCards?.outro;
+    if (!intro && !outro) {
+        return { steps, narrationManifest, presenterManifest };
+    }
+    const expandedSteps = [...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(),
+            card: { kind: "intro", ...pickCardContent(intro) },
+        });
+        manifestEntries?.unshift(null);
+        presenterEntries?.unshift(null);
+    }
+    if (outro) {
+        expandedSteps.push({
+            delayMs: FINAL_DWELL_MS,
+            data: cardStepData(),
+            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) {
+    const content = { 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;
+}
+//# sourceMappingURL=apply-title-cards.js.map

package/scenario/apply-title-cards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-title-cards.js","sourceRoot":"","sources":["../../src/scenario/apply-title-cards.ts"],"names":[],"mappings":"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"}

package/scenario/bundle.d.ts

@@ -7,6 +7,8 @@
  * scenario into a single typed value.
  */
 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";
 /**
  * Everything the engine needs to play one scenario.
@@ -24,5 +26,18 @@ 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;
 }
 //# sourceMappingURL=bundle.d.ts.map

package/scenario/bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/scenario/bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD"}
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/scenario/bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD"}

package/scenario/soundtrack.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 declare const MUSIC_VOLUME_DEFAULT = 0.25;
+/**
+ * Default ducked music level while narration plays. Present but firmly
+ * under the voice.
+ */
+export declare const DUCKING_VOLUME_DEFAULT = 0.08;
+//# sourceMappingURL=soundtrack.d.ts.map

package/scenario/soundtrack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"soundtrack.d.ts","sourceRoot":"","sources":["../../src/scenario/soundtrack.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC"}

package/scenario/soundtrack.js

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

package/scenario/soundtrack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"soundtrack.js","sourceRoot":"","sources":["../../src/scenario/soundtrack.ts"],"names":[],"mappings":"AAoCA;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC"}