@scenar/remotion 0.10.0 → 0.11.0

package/ScenarioComposition.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { ScenarioBundle } from "@scenar/core";
+import { type ScenarioBundle, type SfxSound } from "@scenar/core";
 interface ScenarioCompositionProps<T> {
     /** Self-contained scenario bundle with steps and optional narration. */
     bundle: ScenarioBundle<T>;
@@ -14,6 +14,20 @@ interface ScenarioCompositionProps<T> {
      * Defaults to true.
      */
     useStaticFile?: boolean;
+    /**
+     * Burn step captions into the video: each step's `narration` text
+     * renders as a subtitle-style overlay. Forwarded to `ScenarioPlayer` —
+     * the same overlay the interactive embed shows, so both outputs caption
+     * identically. Defaults to false.
+     */
+    captions?: boolean;
+    /**
+     * Asset paths for the built-in SFX set when `bundle.soundtrack.sfx` is
+     * enabled, resolved like every other audio src (through `staticFile`
+     * when `useStaticFile` is on). Defaults to the locations `scenar
+     * render` stages them at (`soundtrack/sfx/<name>.mp3`).
+     */
+    sfxSrcs?: Record<SfxSound, string>;
 }
 /**
  * Root component for rendering a Scenar scenario as a Remotion video.
@@ -57,6 +71,6 @@ interface ScenarioCompositionProps<T> {
  * );
  * ```
  */
-export declare function ScenarioComposition<T>({ bundle, children, fps: fpsProp, useStaticFile: useStaticFileProp, }: ScenarioCompositionProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function ScenarioComposition<T>({ bundle, children, fps: fpsProp, useStaticFile: useStaticFileProp, captions, sfxSrcs, }: ScenarioCompositionProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=ScenarioComposition.d.ts.map

package/ScenarioComposition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScenarioComposition.d.ts","sourceRoot":"","sources":["../src/ScenarioComposition.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAQvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAMnD,UAAU,wBAAwB,CAAC,CAAC;IAClC,wEAAwE;IACxE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,KAAK,SAAS,CAAC;IACpD,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,EACrC,MAAM,EACN,QAAQ,EACR,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,iBAAwB,GACxC,EAAE,wBAAwB,CAAC,CAAC,CAAC,2CAqC7B"}
+{"version":3,"file":"ScenarioComposition.d.ts","sourceRoot":"","sources":["../src/ScenarioComposition.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAW,MAAM,OAAO,CAAC;AAShD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,QAAQ,EAId,MAAM,cAAc,CAAC;AA4BtB,UAAU,wBAAwB,CAAC,CAAC;IAClC,wEAAwE;IACxE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1B,mEAAmE;IACnE,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,KAAK,SAAS,CAAC;IACpD,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,EACrC,MAAM,EACN,QAAQ,EACR,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,iBAAwB,EACvC,QAAgB,EAChB,OAA0B,GAC3B,EAAE,wBAAwB,CAAC,CAAC,CAAC,2CA6I7B"}

package/ScenarioComposition.js

@@ -1,8 +1,25 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { Audio, Sequence, staticFile, useCurrentFrame, useVideoConfig, } from "remotion";
-import { TimeSourceProvider, VideoExportProvider, ScenarioPlayer } from "@scenar/react";
-import { useScenarioTimeline } from "./useScenarioTimeline.js";
+import { useMemo } from "react";
+import { Audio, OffthreadVideo, Sequence, staticFile, useCurrentFrame, useVideoConfig, } from "remotion";
+import { computeMusicEnvelope, deriveSfxTimeline, musicGainAt, } from "@scenar/core";
+import { TimeSourceProvider, VideoExportProvider, ScenarioPlayer, } from "@scenar/react";
+import { msToFrames, useScenarioTimeline } from "./useScenarioTimeline.js";
 const DEFAULT_FPS = 30;
+/**
+ * Frame window an SFX `<Sequence>` stays mounted. Comfortably longer than
+ * the ~35 ms synthesized ticks (plus MP3 encoder padding), short enough
+ * that rapid typing never accumulates hundreds of live audio tags.
+ */
+const SFX_WINDOW_MS = 500;
+/**
+ * Default staged locations of the built-in SFX set, mirroring where
+ * `scenar render` stages `@scenar/react`'s assets in the public dir.
+ * Resolved through the same `staticFile` path as every other audio src.
+ */
+const DEFAULT_SFX_SRCS = {
+    click: "soundtrack/sfx/click.mp3",
+    keystroke: "soundtrack/sfx/keystroke.mp3",
+};
 /**
  * Root component for rendering a Scenar scenario as a Remotion video.
  *
@@ -45,23 +62,83 @@ const DEFAULT_FPS = 30;
  * );
  * ```
  */
-export function ScenarioComposition({ bundle, children, fps: fpsProp, useStaticFile: useStaticFileProp = true, }) {
+export function ScenarioComposition({ bundle, children, fps: fpsProp, useStaticFile: useStaticFileProp = true, captions = false, sfxSrcs = DEFAULT_SFX_SRCS, }) {
     const videoConfig = useVideoConfig();
     const fps = fpsProp ?? videoConfig.fps ?? DEFAULT_FPS;
     const frame = useCurrentFrame();
     const timeline = useScenarioTimeline(bundle.steps, bundle.narrationManifest, fps);
     const currentTimeMs = (frame / fps) * 1000;
-    return (_jsxs(_Fragment, { children: [_jsx(TimeSourceProvider, { currentTimeMs: currentTimeMs, stepStartTimesMs: timeline.stepStartTimesMs, children: _jsx(VideoExportProvider, { children: _jsx(ScenarioPlayer, { bundle: bundle, children: children }) }) }), timeline.audioClips.map((clip) => (_jsx(Sequence, { from: clip.startFrame, durationInFrames: clip.durationFrames, children: _jsx(Audio, { src: resolveAudioSrc(clip, useStaticFileProp) }) }, clip.stepIndex)))] }));
+    // Synthesized card steps may carry a logo asset. Like every audio src,
+    // the authored path (e.g. "./logo.png") points at a file `scenar render`
+    // stages into the public dir, so it resolves through the same
+    // staticFile path before the player renders it.
+    const playerBundle = useMemo(() => {
+        if (!bundle.steps.some((step) => step.card?.logoSrc))
+            return bundle;
+        return {
+            ...bundle,
+            steps: bundle.steps.map((step) => step.card?.logoSrc
+                ? {
+                    ...step,
+                    card: {
+                        ...step.card,
+                        logoSrc: resolveAssetSrc(step.card.logoSrc, useStaticFileProp),
+                    },
+                }
+                : step),
+        };
+    }, [bundle, useStaticFileProp]);
+    const soundtrack = bundle.soundtrack;
+    // Music level per frame — the same pure @scenar/core envelope the
+    // browser player automates through its gain node, evaluated here as a
+    // Remotion volume function so both outputs duck identically.
+    const musicEnvelope = useMemo(() => soundtrack?.musicSrc
+        ? computeMusicEnvelope(bundle.steps, bundle.narrationManifest, soundtrack)
+        : null, [soundtrack, bundle.steps, bundle.narrationManifest]);
+    const musicVolume = useMemo(() => musicEnvelope
+        ? (f) => musicGainAt(musicEnvelope, (f / fps) * 1000)
+        : undefined, [musicEnvelope, fps]);
+    // The presenter media slot for the export time domain (T02 decision
+    // G2-5): the player owns the PiP frame and its fade; this renderer
+    // fills the frame with a frame-locked clip. `layout="none"` nests the
+    // Sequence inside the player's DOM without an absolute-fill wrapper;
+    // `from` is composition-absolute because the player tree sits outside
+    // any other Sequence. Muted — narration remains the only audio.
+    const presenterMedia = useMemo(() => {
+        if (!bundle.presenterManifest)
+            return undefined;
+        const renderer = ({ src, window: clipWindow }) => (_jsx(Sequence, { layout: "none", from: msToFrames(clipWindow.startMs, fps), durationInFrames: Math.max(1, msToFrames(clipWindow.clipDurationMs, fps)), children: _jsx(OffthreadVideo, { muted: true, src: resolveAssetSrc(src, useStaticFileProp), style: { width: "100%", height: "100%", objectFit: "cover" } }) }));
+        return renderer;
+    }, [bundle.presenterManifest, fps, useStaticFileProp]);
+    // Derived SFX events converted from step-relative offsets to absolute
+    // frames via the shared step starts — the export-side consumer of the
+    // same `deriveSfxTimeline` the browser scheduler plays.
+    const sfxClips = useMemo(() => {
+        if (soundtrack?.sfx !== true)
+            return [];
+        return deriveSfxTimeline(bundle.steps, bundle.narrationManifest).map((event, index) => ({
+            key: `sfx-${index}`,
+            startFrame: msToFrames((timeline.stepStartTimesMs[event.stepIndex] ?? 0) + event.offsetMs, fps),
+            src: sfxSrcs[event.sound],
+        }));
+    }, [soundtrack, bundle.steps, bundle.narrationManifest, timeline, fps, sfxSrcs]);
+    return (_jsxs(_Fragment, { children: [_jsx(TimeSourceProvider, { currentTimeMs: currentTimeMs, stepStartTimesMs: timeline.stepStartTimesMs, children: _jsx(VideoExportProvider, { presenterMedia: presenterMedia, children: _jsx(ScenarioPlayer, { bundle: playerBundle, captions: captions, children: children }) }) }), timeline.audioClips.map((clip) => (_jsx(Sequence, { from: clip.startFrame, durationInFrames: clip.durationFrames, children: _jsx(Audio, { src: resolveAssetSrc(clip.src, useStaticFileProp) }) }, clip.stepIndex))), soundtrack?.musicSrc && (
+            // The music spans the whole composition: `loop` folds a shorter
+            // asset seamlessly; the volume function carries fade-in, ducking,
+            // and the closing fade-out, so no trim math is needed here.
+            _jsx(Audio, { loop: true, src: resolveAssetSrc(soundtrack.musicSrc, useStaticFileProp), volume: musicVolume })), sfxClips.map((clip) => (_jsx(Sequence, { from: clip.startFrame, durationInFrames: msToFrames(SFX_WINDOW_MS, fps), children: _jsx(Audio, { src: resolveAssetSrc(clip.src, useStaticFileProp) }) }, clip.key)))] }));
 }
 /**
- * Resolve audio source URL.  When `useStaticFile` is true, paths are
- * resolved through Remotion's `staticFile()` (strips leading `/`).
- * This matches Stigmer's pattern: `staticFile(clip.src.replace(/^\//, ""))`.
+ * Resolve a staged asset URL (audio clips, card logos).  When
+ * `useStaticFile` is true, paths are resolved through Remotion's
+ * `staticFile()`, stripping a leading `/` (Stigmer's original pattern)
+ * or `./` (the form `scenar narrate`, soundtrack, and title-card
+ * configs write) so the path lands inside the staged public dir.
  */
-function resolveAudioSrc(clip, useStaticFileFn) {
+function resolveAssetSrc(src, useStaticFileFn) {
     if (useStaticFileFn) {
-        return staticFile(clip.src.replace(/^\//, ""));
+        return staticFile(src.replace(/^(\.\/|\/)/, ""));
     }
-    return clip.src;
+    return src;
 }
 //# sourceMappingURL=ScenarioComposition.js.map

package/ScenarioComposition.js.map

@@ -1 +1 @@
-{"version":3,"file":"ScenarioComposition.js","sourceRoot":"","sources":["../src/ScenarioComposition.tsx"],"names":[],"mappings":";AACA,OAAO,EACL,KAAK,EACL,QAAQ,EACR,UAAU,EACV,eAAe,EACf,cAAc,GACf,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAkB,MAAM,0BAA0B,CAAC;AAE/E,MAAM,WAAW,GAAG,EAAE,CAAC;AAkBvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,mBAAmB,CAAI,EACrC,MAAM,EACN,QAAQ,EACR,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,iBAAiB,GAAG,IAAI,GACX;IAC5B,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,OAAO,IAAI,WAAW,CAAC,GAAG,IAAI,WAAW,CAAC;IACtD,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;IAEhC,MAAM,QAAQ,GAAG,mBAAmB,CAClC,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,iBAAiB,EACxB,GAAG,CACJ,CAAC;IAEF,MAAM,aAAa,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC;IAE3C,OAAO,CACL,8BACE,KAAC,kBAAkB,IACjB,aAAa,EAAE,aAAa,EAC5B,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB,YAE3C,KAAC,mBAAmB,cAClB,KAAC,cAAc,IAAC,MAAM,EAAE,MAAM,YAC3B,QAAQ,GACM,GACG,GACH,EAEpB,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CACjC,KAAC,QAAQ,IAEP,IAAI,EAAE,IAAI,CAAC,UAAU,EACrB,gBAAgB,EAAE,IAAI,CAAC,cAAc,YAErC,KAAC,KAAK,IAAC,GAAG,EAAE,eAAe,CAAC,IAAI,EAAE,iBAAiB,CAAC,GAAI,IAJnD,IAAI,CAAC,SAAS,CAKV,CACZ,CAAC,IACD,CACJ,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,IAAe,EAAE,eAAwB;IAChE,IAAI,eAAe,EAAE,CAAC;QACpB,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC;AAClB,CAAC"}
+{"version":3,"file":"ScenarioComposition.js","sourceRoot":"","sources":["../src/ScenarioComposition.tsx"],"names":[],"mappings":"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"}

package/index.d.ts

@@ -1,5 +1,6 @@
-export type { ScenarioBundle, NarrationManifest, ScenarioStep, StepTimeline } from "@scenar/core";
+export type { ScenarioBundle, NarrationManifest, ScenarioStep, StepTimeline, TitleCard, TitleCards, StepCard, AppliedTitleCards, } from "@scenar/core";
+export { applyTitleCards } from "@scenar/core";
 export { ScenarioComposition } from "./ScenarioComposition.js";
 export type { ScenarioTimeline, AudioClip } from "./useScenarioTimeline.js";
-export { useScenarioTimeline, calculateScenarioTimeline, } from "./useScenarioTimeline.js";
+export { useScenarioTimeline, calculateScenarioTimeline, msToFrames, } from "./useScenarioTimeline.js";
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGlG,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EACL,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,UAAU,EACV,QAAQ,EACR,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAItB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,UAAU,GACX,MAAM,0BAA0B,CAAC"}

package/index.js

@@ -1,6 +1,10 @@
 // @scenar/remotion — public API
 // Remotion integration for rendering Scenar scenarios as videos.
+// Card synthesis is re-exported so the generated render entry — which
+// already imports this package — never needs @scenar/core as a direct
+// dependency of the scenario project.
+export { applyTitleCards } from "@scenar/core";
 // Composition
 export { ScenarioComposition } from "./ScenarioComposition.js";
-export { useScenarioTimeline, calculateScenarioTimeline, } from "./useScenarioTimeline.js";
+export { useScenarioTimeline, calculateScenarioTimeline, msToFrames, } from "./useScenarioTimeline.js";
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,iEAAiE;AAKjE,cAAc;AACd,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAI/D,OAAO,EACL,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,iEAAiE;AAajE,sEAAsE;AACtE,sEAAsE;AACtE,sCAAsC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,cAAc;AACd,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAI/D,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,UAAU,GACX,MAAM,0BAA0B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenar/remotion",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Remotion integration for Scenar — render scenario demos as pixel-perfect MP4 videos.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
     }
   },
   "dependencies": {
-    "@scenar/core": "0.10.0",
-    "@scenar/react": "0.10.0"
+    "@scenar/core": "0.11.0",
+    "@scenar/react": "0.11.0"
   },
   "peerDependencies": {
     "@remotion/renderer": "4.0.448",

package/src/ScenarioComposition.tsx

@@ -1,17 +1,46 @@
-import { type ReactNode } from "react";
+import { type ReactNode, useMemo } from "react";
 import {
   Audio,
+  OffthreadVideo,
   Sequence,
   staticFile,
   useCurrentFrame,
   useVideoConfig,
 } from "remotion";
-import type { ScenarioBundle } from "@scenar/core";
-import { TimeSourceProvider, VideoExportProvider, ScenarioPlayer } from "@scenar/react";
-import { useScenarioTimeline, type AudioClip } from "./useScenarioTimeline.js";
+import {
+  type ScenarioBundle,
+  type SfxSound,
+  computeMusicEnvelope,
+  deriveSfxTimeline,
+  musicGainAt,
+} from "@scenar/core";
+import {
+  type PresenterMediaRenderer,
+  TimeSourceProvider,
+  VideoExportProvider,
+  ScenarioPlayer,
+} from "@scenar/react";
+import { msToFrames, useScenarioTimeline } from "./useScenarioTimeline.js";
 
 const DEFAULT_FPS = 30;
 
+/**
+ * Frame window an SFX `<Sequence>` stays mounted. Comfortably longer than
+ * the ~35 ms synthesized ticks (plus MP3 encoder padding), short enough
+ * that rapid typing never accumulates hundreds of live audio tags.
+ */
+const SFX_WINDOW_MS = 500;
+
+/**
+ * Default staged locations of the built-in SFX set, mirroring where
+ * `scenar render` stages `@scenar/react`'s assets in the public dir.
+ * Resolved through the same `staticFile` path as every other audio src.
+ */
+const DEFAULT_SFX_SRCS: Record<SfxSound, string> = {
+  click: "soundtrack/sfx/click.mp3",
+  keystroke: "soundtrack/sfx/keystroke.mp3",
+};
+
 interface ScenarioCompositionProps<T> {
   /** Self-contained scenario bundle with steps and optional narration. */
   bundle: ScenarioBundle<T>;
@@ -26,6 +55,20 @@ interface ScenarioCompositionProps<T> {
    * Defaults to true.
    */
   useStaticFile?: boolean;
+  /**
+   * Burn step captions into the video: each step's `narration` text
+   * renders as a subtitle-style overlay. Forwarded to `ScenarioPlayer` —
+   * the same overlay the interactive embed shows, so both outputs caption
+   * identically. Defaults to false.
+   */
+  captions?: boolean;
+  /**
+   * Asset paths for the built-in SFX set when `bundle.soundtrack.sfx` is
+   * enabled, resolved like every other audio src (through `staticFile`
+   * when `useStaticFile` is on). Defaults to the locations `scenar
+   * render` stages them at (`soundtrack/sfx/<name>.mp3`).
+   */
+  sfxSrcs?: Record<SfxSound, string>;
 }
 
 /**
@@ -75,6 +118,8 @@ export function ScenarioComposition<T>({
   children,
   fps: fpsProp,
   useStaticFile: useStaticFileProp = true,
+  captions = false,
+  sfxSrcs = DEFAULT_SFX_SRCS,
 }: ScenarioCompositionProps<T>) {
   const videoConfig = useVideoConfig();
   const fps = fpsProp ?? videoConfig.fps ?? DEFAULT_FPS;
@@ -88,14 +133,97 @@ export function ScenarioComposition<T>({
 
   const currentTimeMs = (frame / fps) * 1000;
 
+  // Synthesized card steps may carry a logo asset. Like every audio src,
+  // the authored path (e.g. "./logo.png") points at a file `scenar render`
+  // stages into the public dir, so it resolves through the same
+  // staticFile path before the player renders it.
+  const playerBundle = useMemo(() => {
+    if (!bundle.steps.some((step) => step.card?.logoSrc)) return bundle;
+    return {
+      ...bundle,
+      steps: bundle.steps.map((step) =>
+        step.card?.logoSrc
+          ? {
+              ...step,
+              card: {
+                ...step.card,
+                logoSrc: resolveAssetSrc(step.card.logoSrc, useStaticFileProp),
+              },
+            }
+          : step,
+      ),
+    };
+  }, [bundle, useStaticFileProp]);
+
+  const soundtrack = bundle.soundtrack;
+
+  // Music level per frame — the same pure @scenar/core envelope the
+  // browser player automates through its gain node, evaluated here as a
+  // Remotion volume function so both outputs duck identically.
+  const musicEnvelope = useMemo(
+    () =>
+      soundtrack?.musicSrc
+        ? computeMusicEnvelope(bundle.steps, bundle.narrationManifest, soundtrack)
+        : null,
+    [soundtrack, bundle.steps, bundle.narrationManifest],
+  );
+  const musicVolume = useMemo(
+    () =>
+      musicEnvelope
+        ? (f: number) => musicGainAt(musicEnvelope, (f / fps) * 1000)
+        : undefined,
+    [musicEnvelope, fps],
+  );
+
+  // The presenter media slot for the export time domain (T02 decision
+  // G2-5): the player owns the PiP frame and its fade; this renderer
+  // fills the frame with a frame-locked clip. `layout="none"` nests the
+  // Sequence inside the player's DOM without an absolute-fill wrapper;
+  // `from` is composition-absolute because the player tree sits outside
+  // any other Sequence. Muted — narration remains the only audio.
+  const presenterMedia = useMemo<PresenterMediaRenderer | undefined>(() => {
+    if (!bundle.presenterManifest) return undefined;
+    const renderer: PresenterMediaRenderer = ({ src, window: clipWindow }) => (
+      <Sequence
+        layout="none"
+        from={msToFrames(clipWindow.startMs, fps)}
+        durationInFrames={Math.max(1, msToFrames(clipWindow.clipDurationMs, fps))}
+      >
+        <OffthreadVideo
+          muted
+          src={resolveAssetSrc(src, useStaticFileProp)}
+          style={{ width: "100%", height: "100%", objectFit: "cover" }}
+        />
+      </Sequence>
+    );
+    return renderer;
+  }, [bundle.presenterManifest, fps, useStaticFileProp]);
+
+  // Derived SFX events converted from step-relative offsets to absolute
+  // frames via the shared step starts — the export-side consumer of the
+  // same `deriveSfxTimeline` the browser scheduler plays.
+  const sfxClips = useMemo(() => {
+    if (soundtrack?.sfx !== true) return [];
+    return deriveSfxTimeline(bundle.steps, bundle.narrationManifest).map(
+      (event, index) => ({
+        key: `sfx-${index}`,
+        startFrame: msToFrames(
+          (timeline.stepStartTimesMs[event.stepIndex] ?? 0) + event.offsetMs,
+          fps,
+        ),
+        src: sfxSrcs[event.sound],
+      }),
+    );
+  }, [soundtrack, bundle.steps, bundle.narrationManifest, timeline, fps, sfxSrcs]);
+
   return (
     <>
       <TimeSourceProvider
         currentTimeMs={currentTimeMs}
         stepStartTimesMs={timeline.stepStartTimesMs}
       >
-        <VideoExportProvider>
-          <ScenarioPlayer bundle={bundle}>
+        <VideoExportProvider presenterMedia={presenterMedia}>
+          <ScenarioPlayer bundle={playerBundle} captions={captions}>
             {children}
           </ScenarioPlayer>
         </VideoExportProvider>
@@ -107,7 +235,28 @@ export function ScenarioComposition<T>({
           from={clip.startFrame}
           durationInFrames={clip.durationFrames}
         >
-          <Audio src={resolveAudioSrc(clip, useStaticFileProp)} />
+          <Audio src={resolveAssetSrc(clip.src, useStaticFileProp)} />
+        </Sequence>
+      ))}
+
+      {soundtrack?.musicSrc && (
+        // The music spans the whole composition: `loop` folds a shorter
+        // asset seamlessly; the volume function carries fade-in, ducking,
+        // and the closing fade-out, so no trim math is needed here.
+        <Audio
+          loop
+          src={resolveAssetSrc(soundtrack.musicSrc, useStaticFileProp)}
+          volume={musicVolume}
+        />
+      )}
+
+      {sfxClips.map((clip) => (
+        <Sequence
+          key={clip.key}
+          from={clip.startFrame}
+          durationInFrames={msToFrames(SFX_WINDOW_MS, fps)}
+        >
+          <Audio src={resolveAssetSrc(clip.src, useStaticFileProp)} />
         </Sequence>
       ))}
     </>
@@ -115,13 +264,15 @@ export function ScenarioComposition<T>({
 }
 
 /**
- * Resolve audio source URL.  When `useStaticFile` is true, paths are
- * resolved through Remotion's `staticFile()` (strips leading `/`).
- * This matches Stigmer's pattern: `staticFile(clip.src.replace(/^\//, ""))`.
+ * Resolve a staged asset URL (audio clips, card logos).  When
+ * `useStaticFile` is true, paths are resolved through Remotion's
+ * `staticFile()`, stripping a leading `/` (Stigmer's original pattern)
+ * or `./` (the form `scenar narrate`, soundtrack, and title-card
+ * configs write) so the path lands inside the staged public dir.
  */
-function resolveAudioSrc(clip: AudioClip, useStaticFileFn: boolean): string {
+function resolveAssetSrc(src: string, useStaticFileFn: boolean): string {
   if (useStaticFileFn) {
-    return staticFile(clip.src.replace(/^\//, ""));
+    return staticFile(src.replace(/^(\.\/|\/)/, ""));
   }
-  return clip.src;
+  return src;
 }

package/src/__tests__/ScenarioComposition.test.tsx

@@ -1,13 +1,30 @@
-import { describe, it, expect, vi } from "vitest";
+import { beforeEach, describe, it, expect, vi } from "vitest";
 import { render } from "@testing-library/react";
 
+/** Props of every rendered Remotion `Audio`, in render order — lets tests
+ * inspect the `volume` function and `loop` flag the DOM cannot carry.
+ * `frame` drives the mocked `useCurrentFrame` so tests can position the
+ * composition mid-timeline. */
+const captured = vi.hoisted(() => ({
+  audios: [] as Array<{ src: string; loop?: boolean; volume?: (f: number) => number }>,
+  frame: 0,
+}));
+
 vi.mock("remotion", () => ({
-  useCurrentFrame: () => 0,
+  useCurrentFrame: () => captured.frame,
   useVideoConfig: () => ({ fps: 30, width: 1920, height: 1080, durationInFrames: 300 }),
   AbsoluteFill: ({ children }: { children: React.ReactNode }) => <div>{children}</div>,
-  Audio: ({ src }: { src: string }) => (
-    <audio data-testid="remotion-audio" data-remotion-audio="true" src={src} />
-  ),
+  Audio: (props: { src: string; loop?: boolean; volume?: (f: number) => number }) => {
+    captured.audios.push(props);
+    return (
+      <audio
+        data-testid="remotion-audio"
+        data-remotion-audio="true"
+        data-loop={props.loop ? "true" : undefined}
+        src={props.src}
+      />
+    );
+  },
   Sequence: ({
     from,
     durationInFrames,
@@ -25,12 +42,30 @@ vi.mock("remotion", () => ({
       {children}
     </div>
   ),
+  OffthreadVideo: (props: { src: string; muted?: boolean }) => (
+    <div
+      data-testid="remotion-offthread-video"
+      data-muted={props.muted ? "true" : undefined}
+      data-src={props.src}
+    />
+  ),
   staticFile: (path: string) => `/static/${path}`,
 }));
 
-import type { ScenarioBundle, NarrationManifest } from "@scenar/core";
+import {
+  type NarrationManifest,
+  type ScenarioBundle,
+  CLICK_DELAY_MS,
+  computeMusicEnvelope,
+  musicGainAt,
+} from "@scenar/core";
 import { ScenarioComposition } from "../ScenarioComposition.js";
 
+beforeEach(() => {
+  captured.audios = [];
+  captured.frame = 0;
+});
+
 type StepData = { view: string };
 
 const bundle: ScenarioBundle<StepData> = {
@@ -126,3 +161,209 @@ describe("ScenarioComposition", () => {
     expect(remotionAudios[1]!.getAttribute("src")).toBe("/audio/step-2.mp3");
   });
 });
+
+// --- Soundtrack ---
+
+const bundleWithMusic: ScenarioBundle<StepData> = {
+  ...bundleWithNarration,
+  soundtrack: { musicSrc: "./soundtrack/music.mp3", musicVolume: 0.5, duckingVolume: 0.1 },
+};
+
+const bundleWithSfx: ScenarioBundle<StepData> = {
+  ...bundle,
+  soundtrack: { sfx: true },
+  steps: [
+    {
+      delayMs: 0,
+      data: { view: "intro" },
+      interactions: [{ atPercent: 0, type: "click", target: "btn" }],
+    },
+    { delayMs: 2000, data: { view: "body" } },
+  ],
+};
+
+describe("ScenarioComposition soundtrack", () => {
+  it("renders a looping music track resolved through staticFile", () => {
+    render(
+      <ScenarioComposition bundle={bundleWithMusic}>
+        {(data: StepData) => <div>{data.view}</div>}
+      </ScenarioComposition>,
+    );
+
+    const music = captured.audios.find((a) => a.loop);
+    expect(music).toBeDefined();
+    // "./soundtrack/music.mp3" strips its leading "./" before staticFile.
+    expect(music!.src).toBe("/static/soundtrack/music.mp3");
+    expect(typeof music!.volume).toBe("function");
+  });
+
+  it("drives the music volume from the shared core envelope (parity)", () => {
+    render(
+      <ScenarioComposition bundle={bundleWithMusic}>
+        {(data: StepData) => <div>{data.view}</div>}
+      </ScenarioComposition>,
+    );
+
+    const volume = captured.audios.find((a) => a.loop)!.volume!;
+    const envelope = computeMusicEnvelope(
+      bundleWithMusic.steps,
+      bundleWithMusic.narrationManifest,
+      bundleWithMusic.soundtrack!,
+    );
+    // Sample across fade-in, ducked narration, and the plateau: the frame
+    // function must agree with the pure envelope at the frame's time.
+    for (const frame of [0, 15, 30, 90, 100, 135, 150]) {
+      expect(volume(frame)).toBe(musicGainAt(envelope, (frame / 30) * 1000));
+    }
+  });
+
+  it("is deterministic: two renders produce identical volume samples", () => {
+    render(
+      <ScenarioComposition bundle={bundleWithMusic}>
+        {(data: StepData) => <div>{data.view}</div>}
+      </ScenarioComposition>,
+    );
+    const first = captured.audios.find((a) => a.loop)!.volume!;
+    const firstSamples = [0, 10, 50, 120, 149].map((f) => first(f));
+
+    captured.audios = [];
+    render(
+      <ScenarioComposition bundle={bundleWithMusic}>
+        {(data: StepData) => <div>{data.view}</div>}
+      </ScenarioComposition>,
+    );
+    const second = captured.audios.find((a) => a.loop)!.volume!;
+    expect([0, 10, 50, 120, 149].map((f) => second(f))).toEqual(firstSamples);
+  });
+
+  it("places SFX sequences at the derived frame offsets", () => {
+    const { container } = render(
+      <ScenarioComposition bundle={bundleWithSfx}>
+        {(data: StepData) => <div>{data.view}</div>}
+      </ScenarioComposition>,
+    );
+
+    // One click at atPercent 0 in a 2000ms step: dispatch at 450ms
+    // (CLICK_DELAY_MS) → frame round(450 * 30 / 1000) = 14.
+    const sequences = container.querySelectorAll("[data-testid='remotion-sequence']");
+    expect(sequences).toHaveLength(1);
+    expect(sequences[0]!.getAttribute("data-from")).toBe(
+      String(Math.round((CLICK_DELAY_MS * 30) / 1000)),
+    );
+
+    const sfxAudio = captured.audios.find((a) => a.src.includes("sfx"));
+    expect(sfxAudio!.src).toBe("/static/soundtrack/sfx/click.mp3");
+  });
+
+  it("renders no soundtrack audio when the bundle has none", () => {
+    render(
+      <ScenarioComposition bundle={bundleWithNarration}>
+        {(data: StepData) => <div>{data.view}</div>}
+      </ScenarioComposition>,
+    );
+    expect(captured.audios.some((a) => a.loop)).toBe(false);
+    expect(captured.audios.some((a) => a.src.includes("sfx"))).toBe(false);
+  });
+});
+
+// --- Presenter track ---
+
+// Clip on step 0 (2000ms) — active at frame 0. Duration mirrors the
+// narration entry, as `scenar presenter` writes it.
+const bundleWithPresenter: ScenarioBundle<StepData> = {
+  ...bundle,
+  narrationManifest: {
+    steps: [{ src: "/audio/step-0.mp3", durationMs: 2000 }, null, null],
+  },
+  presenterManifest: {
+    steps: [{ src: "./step-0.mp4", durationMs: 2000 }, null, null],
+  },
+};
+
+function renderPresenterComposition() {
+  return render(
+    <ScenarioComposition bundle={bundleWithPresenter}>
+      {(data: StepData) => <div>{data.view}</div>}
+    </ScenarioComposition>,
+  );
+}
+
+describe("ScenarioComposition presenter", () => {
+  it("fills the presenter frame with a muted frame-locked clip via staticFile", () => {
+    const { container } = renderPresenterComposition();
+
+    const media = container.querySelector("[data-testid='remotion-offthread-video']")!;
+    expect(media).not.toBeNull();
+    expect(media.getAttribute("data-muted")).toBe("true");
+    // "./step-0.mp4" strips its leading "./" before staticFile.
+    expect(media.getAttribute("data-src")).toBe("/static/step-0.mp4");
+    // The export path renders no browser <video>.
+    expect(container.querySelector("video")).toBeNull();
+  });
+
+  it("places the clip Sequence at the window's frame offsets", () => {
+    const { container } = renderPresenterComposition();
+
+    const frame = container.querySelector("[data-scenar-presenter]")!;
+    const sequence = frame.querySelector("[data-testid='remotion-sequence']")!;
+    // Window: step 0 starts at 0ms, clip 2000ms → 60 frames at 30fps.
+    expect(sequence.getAttribute("data-from")).toBe("0");
+    expect(sequence.getAttribute("data-duration")).toBe("60");
+  });
+
+  it("renders the fade from frame time through the shared pure function", () => {
+    // Frame 30 = 1000ms: mid-clip, fully opaque.
+    captured.frame = 30;
+    const mid = renderPresenterComposition();
+    const midFrame = mid.container.querySelector("[data-scenar-presenter]") as HTMLElement;
+    expect(Number(midFrame.style.opacity)).toBe(1);
+    mid.unmount();
+
+    // Frame 3 = 100ms: half-way through the 200ms fade-in.
+    captured.frame = 3;
+    const fading = renderPresenterComposition();
+    const fadingFrame = fading.container.querySelector(
+      "[data-scenar-presenter]",
+    ) as HTMLElement;
+    expect(Number(fadingFrame.style.opacity)).toBeCloseTo(0.5, 5);
+  });
+
+  it("is deterministic: the same bundle at the same frame renders identical presenter state, twice", () => {
+    captured.frame = 30;
+
+    const first = renderPresenterComposition();
+    const firstFrame = first.container.querySelector("[data-scenar-presenter]") as HTMLElement;
+    const firstState = {
+      opacity: firstFrame.style.opacity,
+      src: first.container
+        .querySelector("[data-testid='remotion-offthread-video']")!
+        .getAttribute("data-src"),
+      from: firstFrame
+        .querySelector("[data-testid='remotion-sequence']")!
+        .getAttribute("data-from"),
+    };
+    first.unmount();
+
+    const second = renderPresenterComposition();
+    const secondFrame = second.container.querySelector("[data-scenar-presenter]") as HTMLElement;
+    expect({
+      opacity: secondFrame.style.opacity,
+      src: second.container
+        .querySelector("[data-testid='remotion-offthread-video']")!
+        .getAttribute("data-src"),
+      from: secondFrame
+        .querySelector("[data-testid='remotion-sequence']")!
+        .getAttribute("data-from"),
+    }).toEqual(firstState);
+  });
+
+  it("renders no presenter DOM when the bundle has no presenter manifest", () => {
+    const { container } = render(
+      <ScenarioComposition bundle={bundleWithNarration}>
+        {(data: StepData) => <div>{data.view}</div>}
+      </ScenarioComposition>,
+    );
+    expect(container.querySelector("[data-scenar-presenter]")).toBeNull();
+    expect(container.querySelector("[data-testid='remotion-offthread-video']")).toBeNull();
+  });
+});

package/src/index.ts

@@ -2,7 +2,20 @@
 // Remotion integration for rendering Scenar scenarios as videos.
 
 // Re-export core types for consumer convenience
-export type { ScenarioBundle, NarrationManifest, ScenarioStep, StepTimeline } from "@scenar/core";
+export type {
+  ScenarioBundle,
+  NarrationManifest,
+  ScenarioStep,
+  StepTimeline,
+  TitleCard,
+  TitleCards,
+  StepCard,
+  AppliedTitleCards,
+} from "@scenar/core";
+// Card synthesis is re-exported so the generated render entry — which
+// already imports this package — never needs @scenar/core as a direct
+// dependency of the scenario project.
+export { applyTitleCards } from "@scenar/core";
 
 // Composition
 export { ScenarioComposition } from "./ScenarioComposition.js";
@@ -12,4 +25,5 @@ export type { ScenarioTimeline, AudioClip } from "./useScenarioTimeline.js";
 export {
   useScenarioTimeline,
   calculateScenarioTimeline,
+  msToFrames,
 } from "./useScenarioTimeline.js";

package/src/useScenarioTimeline.ts

@@ -28,7 +28,12 @@ export interface ScenarioTimeline extends StepTimeline {
   fps: number;
 }
 
-function msToFrames(ms: number, fps: number): number {
+/**
+ * THE ms → frame conversion for the export path — every frame offset in
+ * the composition (steps, narration, soundtrack SFX) goes through this
+ * one rounding so nothing can drift by a frame against anything else.
+ */
+export function msToFrames(ms: number, fps: number): number {
   return Math.round((ms * fps) / 1000);
 }
 

package/useScenarioTimeline.d.ts

@@ -19,6 +19,12 @@ export interface ScenarioTimeline extends StepTimeline {
     /** Frames per second used for the conversion. */
     fps: number;
 }
+/**
+ * THE ms → frame conversion for the export path — every frame offset in
+ * the composition (steps, narration, soundtrack SFX) goes through this
+ * one rounding so nothing can drift by a frame against anything else.
+ */
+export declare function msToFrames(ms: number, fps: number): number;
 /**
  * Convert Scenar's millisecond-based step timeline into Remotion frame
  * counts.  The returned values are stable across renders for the same

package/useScenarioTimeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useScenarioTimeline.d.ts","sourceRoot":"","sources":["../src/useScenarioTimeline.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,YAAY,EAElB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,mEAAmE;IACnE,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;CACb;AAmDD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,YAAY,CAAC,OAAO,CAAC,EAAE,EACvC,iBAAiB,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EACvD,GAAG,EAAE,MAAM,GACV,gBAAgB,CAKlB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,YAAY,CAAC,OAAO,CAAC,EAAE,EACvC,iBAAiB,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EACvD,GAAG,EAAE,MAAM,GACV,gBAAgB,CAElB"}
+{"version":3,"file":"useScenarioTimeline.d.ts","sourceRoot":"","sources":["../src/useScenarioTimeline.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,YAAY,EAElB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,mEAAmE;IACnE,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AA+CD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,YAAY,CAAC,OAAO,CAAC,EAAE,EACvC,iBAAiB,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EACvD,GAAG,EAAE,MAAM,GACV,gBAAgB,CAKlB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,YAAY,CAAC,OAAO,CAAC,EAAE,EACvC,iBAAiB,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EACvD,GAAG,EAAE,MAAM,GACV,gBAAgB,CAElB"}

package/useScenarioTimeline.js

@@ -1,6 +1,11 @@
 import { useMemo } from "react";
 import { computeStepTimeline, } from "@scenar/core";
-function msToFrames(ms, fps) {
+/**
+ * THE ms → frame conversion for the export path — every frame offset in
+ * the composition (steps, narration, soundtrack SFX) goes through this
+ * one rounding so nothing can drift by a frame against anything else.
+ */
+export function msToFrames(ms, fps) {
     return Math.round((ms * fps) / 1000);
 }
 /**

package/useScenarioTimeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"useScenarioTimeline.js","sourceRoot":"","sources":["../src/useScenarioTimeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAIL,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAwBtB,SAAS,UAAU,CAAC,EAAU,EAAE,GAAW;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CACpB,KAAuC,EACvC,iBAAuD,EACvD,GAAW;IAEX,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,GAAG,mBAAmB,CAC/D,KAAK,EACL,iBAAiB,CAClB,CAAC;IAEF,MAAM,eAAe,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1E,MAAM,gBAAgB,GAAG,UAAU,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;IAE1D,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,IAAI,iBAAiB,EAAE,CAAC;QACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,iBAAiB,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxD,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzC,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,UAAU,CAAC,IAAI,CAAC;gBACd,SAAS,EAAE,CAAC;gBACZ,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC;gBACnC,cAAc,EAAE,UAAU,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC;aAClD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO;QACL,gBAAgB;QAChB,eAAe;QACf,UAAU;QACV,eAAe;QACf,gBAAgB;QAChB,GAAG;KACJ,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAuC,EACvC,iBAAuD,EACvD,GAAW;IAEX,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,CAAC,EAClD,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,CAAC,CAChC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAuC,EACvC,iBAAuD,EACvD,GAAW;IAEX,OAAO,aAAa,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,CAAC,CAAC;AACtD,CAAC"}
+{"version":3,"file":"useScenarioTimeline.js","sourceRoot":"","sources":["../src/useScenarioTimeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAIL,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAwBtB;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU,EAAE,GAAW;IAChD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CACpB,KAAuC,EACvC,iBAAuD,EACvD,GAAW;IAEX,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,GAAG,mBAAmB,CAC/D,KAAK,EACL,iBAAiB,CAClB,CAAC;IAEF,MAAM,eAAe,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1E,MAAM,gBAAgB,GAAG,UAAU,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;IAE1D,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,IAAI,iBAAiB,EAAE,CAAC;QACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,iBAAiB,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxD,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACzC,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,UAAU,CAAC,IAAI,CAAC;gBACd,SAAS,EAAE,CAAC;gBACZ,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC;gBACnC,cAAc,EAAE,UAAU,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC;aAClD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO;QACL,gBAAgB;QAChB,eAAe;QACf,UAAU;QACV,eAAe;QACf,gBAAgB;QAChB,GAAG;KACJ,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAuC,EACvC,iBAAuD,EACvD,GAAW;IAEX,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,CAAC,EAClD,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,CAAC,CAChC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAuC,EACvC,iBAAuD,EACvD,GAAW;IAEX,OAAO,aAAa,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,CAAC,CAAC;AACtD,CAAC"}