@real-music-packages/web-core 0.13.0 → 0.15.0

package/dist/scene/index.d.ts

@@ -227,6 +227,14 @@ declare const linear: Easing;
 declare const easeInOut: Easing;
 declare const easeIn: Easing;
 declare const easeOut: Easing;
+/**
+ * Eased 0..1 progress of a transition at absolute time `tMs`, given the incoming
+ * segment's `startMs` and the transition `durationMs`. Returns 0 at/before the
+ * start, 1 at/after start+durationMs, eased in between. Pure fn of t. Shared by
+ * the runner so the same envelope drives crossfade alpha, push translate, and
+ * wipe clip. `durationMs <= 0` → an instant 1 (degenerate hard-cut).
+ */
+declare const transitionProgress: (tMs: number, startMs: number, durationMs: number, easing?: Easing) => number;
 
 /** A rectangle in WORLD coordinates (the layers' natural pixel space). */
 interface Rect {
@@ -326,12 +334,52 @@ interface SegmentAudioCtx {
 interface ScheduleTarget {
     triggerAttackRelease: (note: unknown, dur: unknown, time?: unknown, velocity?: unknown) => void;
 }
+/**
+ * Optional ENTER transition for a segment — how it comes IN from the PREVIOUS
+ * segment (the one immediately before it in the timeline). Purely VISUAL and
+ * fully additive: a segment with no `transition` hard-cuts exactly as before
+ * (existing specs are byte-for-byte unchanged). The audio timeline / per-segment
+ * `audio` hook is unaffected (transitions are a visual envelope only).
+ *
+ * During the first `durationMs` of the incoming segment, the runner renders BOTH
+ * the previous segment (its last drawn state, held) AND the incoming segment,
+ * applying an eased envelope (`easeInOut` by default):
+ *  - `crossfade` — outgoing opacity 1→0, incoming 0→1 (the keystone; always on).
+ *  - `push`      — both slide along `direction`: incoming enters from off-frame
+ *                  while outgoing exits the opposite way (a hard slide, no fade).
+ *  - `wipe`      — incoming is revealed by a moving clip edge along `direction`;
+ *                  the outgoing shows through the un-wiped region (no fade).
+ *
+ * The overlap does NOT add time — the transition lives INSIDE the incoming
+ * segment's own window, so `visualTimelineMs` (and the gate's A/V-duration check)
+ * are unchanged. `durationMs` is clamped to the shorter of the two adjoining
+ * segment lengths so a transition can't run past either segment.
+ */
+interface SegmentTransition {
+    /** Transition style. Start with `crossfade`. */
+    type: 'crossfade' | 'push' | 'wipe';
+    /** Length of the enter window in ms (from the incoming segment's start). */
+    durationMs: number;
+    /**
+     * Slide / wipe direction for `push` and `wipe` (ignored by `crossfade`).
+     * Names the edge the INCOMING segment comes FROM. Default `left`.
+     */
+    direction?: 'left' | 'right' | 'up' | 'down';
+    /** Eased envelope, 0..1 → 0..1. Defaults to `easeInOut`. */
+    easing?: Easing;
+}
 interface TimelineSegment {
     /** [start, end] in SECONDS; end may be "end" / "end-N". */
     at: [number, TimeAnchor];
     layers: SpecLayer[];
     /** Optional sound scheduled at this segment's start (see SegmentAudio). */
     audio?: SegmentAudio;
+    /**
+     * Optional ENTER transition from the PREVIOUS segment (see SegmentTransition).
+     * Omit for today's hard cut. Has no effect on the first segment (nothing to
+     * transition from) unless `loop` is set on the spec.
+     */
+    transition?: SegmentTransition;
 }
 interface SceneSpec {
     /** [width, height] px. */
@@ -357,6 +405,7 @@ interface ResolvedSegment {
     endMs: number;
     layers: SpecLayer[];
     audio?: SegmentAudio;
+    transition?: SegmentTransition;
 }
 /** Resolve every segment's [start,end] to ms against the total clip length. */
 declare function resolveTimeline(spec: SceneSpec, totalSec: number): ResolvedSegment[];
@@ -397,7 +446,25 @@ interface BuildSceneOpts {
     /** Override the camera pose per absolute tMs (pan/zoom director). Identity by
      *  default. */
     camera?: (tMs: number) => CameraState;
+    /**
+     * Offscreen-buffer factory used ONLY by segment `transition`s (a segment's
+     * stack is rendered to a buffer, then composited onto the main canvas with the
+     * transition envelope — so the envelope is robust even when inner layers set
+     * their own `globalAlpha`). Unused when no segment has a transition.
+     *
+     * Default: `OffscreenCanvas` if available, else `document.createElement
+     * ('canvas')`. Node/headless callers (and the node-canvas golden tests) pass a
+     * factory backed by `createCanvas`. If no factory is resolvable AND a
+     * transition fires, the runner falls back to a direct `globalAlpha` envelope
+     * (crossfade only; degrades gracefully) rather than throwing.
+     */
+    bufferFactory?: BufferFactory;
 }
+/** Makes an offscreen drawing surface for transition compositing. */
+type BufferFactory = (w: number, h: number) => {
+    ctx: CanvasRenderingContext2D;
+    image: CanvasImageSource;
+};
 /**
  * Instantiate + init every layer in the spec and return a deterministic renderer.
  * Throws if a referenced layer key isn't registered or its props don't validate
@@ -603,15 +670,25 @@ interface NotationProps {
 declare const notationFactory: LayerFactory<NotationProps>;
 
 interface ScrollCursorProps {
+    /**
+     * Cursor pacing mode. Default `'audio'` (foolproof): the cursor is driven
+     * note-by-note off the audio clock against each note's `onsetMs`, so it lands
+     * on every note as it sounds and can never race/desync the full score width —
+     * correct by construction regardless of timeline. `'linear'` is the legacy
+     * measure-linear sweep paced over `musicMs` (RSR's original behaviour) — kept
+     * for back-compat; prefer leaving this unset.
+     */
+    mode?: 'audio' | 'linear';
     /** Bars visible in the follow window. Default 2 (RSR FOLLOW_BARS). Informational
      *  for v1 — the geometry uses the module constant unless overridden here. */
     followBars?: number;
     /** Opening-zoom duration in ms before the music/cursor start (RSR INTRO_MS=900).
-     *  During this lead-in camProgress is held at 0. Default 900. */
+     *  During this lead-in the follow window is held at the start. Default 900. */
     openingZoomMs?: number;
-    /** Total music length in ms (RSR musicMs). Required to pace camProgress + the
-     *  cursor against the audio clock. */
-    musicMs: number;
+    /** Total music length in ms (RSR musicMs). Required by `'linear'` to pace
+     *  camProgress; in `'audio'` mode it is optional (the onset clock drives pacing)
+     *  and used only as a fallback when the score has no notes. */
+    musicMs?: number;
     /** Cursor stroke colour. Defaults to theme.accent. */
     color?: string;
 }
@@ -688,6 +765,24 @@ interface PlayheadLine {
     alpha: number;
 }
 declare function playheadLine(layout: NotationLayout, t01: number): PlayheadLine | null;
+/** Distinct, sorted note onsets from a Score's notes. */
+declare function distinctOnsets(notes: {
+    onsetMs: number;
+}[]): number[];
+/**
+ * The FOOLPROOF audio-driven playhead line for absolute audio time `tMs`.
+ *
+ * `tMs` is the audio clock; `onsetsMs` are the score's distinct note onsets
+ * (sorted). The cursor is the time-lerp of the two anchors bracketing `tMs`:
+ * before the first onset it holds on anchor 0; after the last it holds on the
+ * last; in a gap it eases between the bracketing onsets. Pure function of
+ * (layout, onsetsMs, tMs). Returns null only when there is no geometry to anchor
+ * to (falls back to the rect sweep in the layer, same as `playheadLine`).
+ *
+ * Fade in/out mirrors `playheadLine` but is keyed on position in the ONSET span
+ * (first→last onset), not on musicMs — so the fade tracks the notes too.
+ */
+declare function audioPlayheadLine(layout: NotationLayout, onsetsMs: number[], tMs: number): PlayheadLine | null;
 
 /** Map a canvas-space box through a base notation layout into world/screen coords. */
 declare function mapBoxThroughLayout(base: NotationLayout, b: Box): Box;
@@ -1465,4 +1560,4 @@ interface SectionMinimapProps {
 }
 declare const sectionMinimapFactory: LayerFactory<SectionMinimapProps>;
 
-export { type Affine, type AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatTick, type BrandingProps, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type ContourPlot, type ContourPoint, type CountInOpts, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type LabelMode, type Layer, type LayerFactory, type McqCardProps, type NotationEngraving, type NotationLayout, type NotationLayoutOpts, type NotationProps, type NotationRect, type OutputProbe, PIANO_HIGH, PIANO_LOW, type PitchContourProps, type Placement, type PlayheadLine, type PortraitProps, type PromoCardsDemoOpts, type Quiz, type QuizOption, type QuizPhase, type RayEndpoints, type RecordSceneSpecOpts, type Rect, type RenderCtx, type ResolvedSegment, type RevealProps, type SafeGuidesProps, type SceneSpec, type ScheduleTarget, type Score, type ScoreFromMusicXMLOpts, type ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SpecLayer, type SpectrumInput, type SpectrumProps, type StaffKeyboardRayProps, type TempoMap, type TimeAnchor, type TimelineSegment, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, ballArc, ballX, beatGrid, beatPhase, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, cropAroundBox, ctaFactory, cubicEaseInOut, cueOpacity, degreeLabel, degreeLabelsFactory, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, firstMeasureBox, followBoxAt, followSrcBox, followWindowStart, fracSlotPoint, frameRect, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, inRange, invLerp, isBlackKey, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, lerp, lerpBox, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureColumnsFromLayout, measureCount, measureSpanBox, measureSpans, timeToX as minimapTimeToX, msPerBeat, notationFactory, notationLayout, noteColor, noteSetXRange, parseKey, parseTimeSig, pcToSlot, pitchAt, pitchContourFactory, pitchRange, playheadLine, portraitFactory, progress01, projectPoint, promoCardsDemoSpec, quizPhase, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scoreFromMusicXML, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, spectrumFactory, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, whiteKeys, worldToViewport };
+export { type Affine, type AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type ContourPlot, type ContourPoint, type CountInOpts, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type LabelMode, type Layer, type LayerFactory, type McqCardProps, type NotationEngraving, type NotationLayout, type NotationLayoutOpts, type NotationProps, type NotationRect, type OutputProbe, PIANO_HIGH, PIANO_LOW, type PitchContourProps, type Placement, type PlayheadLine, type PortraitProps, type PromoCardsDemoOpts, type Quiz, type QuizOption, type QuizPhase, type RayEndpoints, type RecordSceneSpecOpts, type Rect, type RenderCtx, type ResolvedSegment, type RevealProps, type SafeGuidesProps, type SceneSpec, type ScheduleTarget, type Score, type ScoreFromMusicXMLOpts, type ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type SpectrumInput, type SpectrumProps, type StaffKeyboardRayProps, type TempoMap, type TimeAnchor, type TimelineSegment, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, audioPlayheadLine, ballArc, ballX, beatGrid, beatPhase, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, cropAroundBox, ctaFactory, cubicEaseInOut, cueOpacity, degreeLabel, degreeLabelsFactory, distinctOnsets, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, firstMeasureBox, followBoxAt, followSrcBox, followWindowStart, fracSlotPoint, frameRect, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, inRange, invLerp, isBlackKey, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, lerp, lerpBox, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureColumnsFromLayout, measureCount, measureSpanBox, measureSpans, timeToX as minimapTimeToX, msPerBeat, notationFactory, notationLayout, noteColor, noteSetXRange, parseKey, parseTimeSig, pcToSlot, pitchAt, pitchContourFactory, pitchRange, playheadLine, portraitFactory, progress01, projectPoint, promoCardsDemoSpec, quizPhase, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scoreFromMusicXML, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, spectrumFactory, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, whiteKeys, worldToViewport };

package/dist/scene/index.js

@@ -177,6 +177,10 @@ var easeOut = (t) => {
   const c = clamp(t, 0, 1);
   return 1 - (1 - c) * (1 - c);
 };
+var transitionProgress = (tMs, startMs, durationMs, easing = easeInOut) => {
+  if (durationMs <= 0) return 1;
+  return easing(invLerp(startMs, startMs + durationMs, tMs));
+};
 
 // src/scene/caption.ts
 function activeCue(script, tMs) {
@@ -485,6 +489,74 @@ function playheadLine(layout, t01) {
   }
   return { x, y0, y1, alpha };
 }
+var clamp01 = (x) => x < 0 ? 0 : x > 1 ? 1 : x;
+function anchorAtColumnPos(cols, pos, padV) {
+  const i = Math.min(cols.length - 1, Math.max(0, Math.floor(pos)));
+  const m = cols[i];
+  const startX = Math.min(m.noteStartX, m.x + m.w);
+  const frac = Math.min(1, Math.max(0, pos - i));
+  return {
+    onsetMs: 0,
+    x: startX + frac * (m.x + m.w - startX),
+    y0: m.y - padV,
+    y1: m.y + m.h + padV
+  };
+}
+function noteAnchors(layout, onsetsMs, padV) {
+  const cols = measureColumnsFromLayout(layout.measures);
+  if (!cols.length || !onsetsMs.length) return [];
+  const n = onsetsMs.length;
+  return onsetsMs.map((onsetMs, k) => {
+    const frac = n === 1 ? 0 : k / (n - 1);
+    const a = anchorAtColumnPos(cols, frac * cols.length, padV);
+    return { ...a, onsetMs };
+  });
+}
+function distinctOnsets(notes) {
+  const set = /* @__PURE__ */ new Set();
+  for (const n of notes) set.add(n.onsetMs);
+  return [...set].sort((a, b) => a - b);
+}
+function audioPlayheadLine(layout, onsetsMs, tMs) {
+  const padV = 10;
+  const anchors = noteAnchors(layout, onsetsMs, padV);
+  if (!anchors.length) return null;
+  const first = anchors[0].onsetMs;
+  const last = anchors[anchors.length - 1].onsetMs;
+  const span = last - first;
+  let a, b, frac;
+  if (tMs <= first || anchors.length === 1) {
+    a = b = anchors[0];
+    frac = 0;
+  } else if (tMs >= last) {
+    a = b = anchors[anchors.length - 1];
+    frac = 0;
+  } else {
+    let lo = 0;
+    let hi = anchors.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if (anchors[mid].onsetMs <= tMs) lo = mid;
+      else hi = mid - 1;
+    }
+    a = anchors[lo];
+    b = anchors[lo + 1];
+    const dt = b.onsetMs - a.onsetMs;
+    frac = dt > 0 ? cubicEaseInOut((tMs - a.onsetMs) / dt) : 0;
+  }
+  const x = a.x + (b.x - a.x) * frac;
+  const y0 = a.y0 + (b.y0 - a.y0) * frac;
+  const y1 = a.y1 + (b.y1 - a.y1) * frac;
+  let alpha = 0.85;
+  if (span > 0) {
+    const fadeIn = Math.min(250, span * 0.5);
+    const fadeOut = Math.min(400, span * 0.5);
+    if (tMs < first + fadeIn) alpha *= clamp01((tMs - (first - fadeIn)) / (2 * fadeIn));
+    if (tMs > last - fadeOut) alpha *= clamp01((last + fadeOut - tMs) / (2 * fadeOut));
+  }
+  if (alpha <= 0.02) return null;
+  return { x, y0, y1, alpha };
+}
 
 // src/scene/engravingStore.ts
 var STORE = /* @__PURE__ */ new WeakMap();
@@ -589,6 +661,7 @@ function followLayoutFor(ctx, camProgress01) {
   return notationLayout(eng.rendered, ctx.W, ctx.H, eng.bandTop, eng.bandHeight, { focusBox });
 }
 function scrollCursorLayer() {
+  let mode = "audio";
   let musicMs = 0;
   let openingZoomMs = 900;
   let color;
@@ -597,14 +670,41 @@ function scrollCursorLayer() {
     if (phMs < 0 || musicMs <= 0) return 0;
     return Math.min(1, phMs / musicMs);
   }
+  function onsetsFor(ctx) {
+    const notes = ctx.score?.notes;
+    return notes && notes.length ? distinctOnsets(notes) : [];
+  }
+  function notesProgress(onsetsMs, tMs) {
+    if (tMs < openingZoomMs) return 0;
+    const n = onsetsMs.length;
+    if (n <= 1) return 0;
+    const first = onsetsMs[0];
+    const last = onsetsMs[n - 1];
+    if (tMs <= first) return 0;
+    if (tMs >= last || last <= first) return 1;
+    let lo = 0, hi = n - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if (onsetsMs[mid] <= tMs) lo = mid;
+      else hi = mid - 1;
+    }
+    const segFrac = (tMs - onsetsMs[lo]) / (onsetsMs[lo + 1] - onsetsMs[lo]);
+    return (lo + segFrac) / (n - 1);
+  }
+  function followProgress(ctx, tMs) {
+    if (mode === "linear") return camProgress(tMs);
+    const onsets = onsetsFor(ctx);
+    return onsets.length ? notesProgress(onsets, tMs) : camProgress(tMs);
+  }
   function layoutAt(ctx, tMs) {
     const eng = getNotationEngraving(ctx);
-    return followLayoutFor(ctx, camProgress(tMs)) ?? eng.base;
+    return followLayoutFor(ctx, followProgress(ctx, tMs)) ?? eng.base;
   }
   return {
     key: "scroll-cursor",
     init(ctx, props) {
-      musicMs = props.musicMs;
+      mode = props.mode ?? "audio";
+      musicMs = props.musicMs ?? 0;
       openingZoomMs = props.openingZoomMs ?? 900;
       color = props.color;
       setFollowLayoutProvider(ctx, layoutAt);
@@ -612,9 +712,14 @@ function scrollCursorLayer() {
     draw(ctx, tMs) {
       const eng = getNotationEngraving(ctx);
       if (!eng) return;
-      const p = camProgress(tMs);
       const layout = layoutAt(ctx, tMs);
-      const line = playheadLine(layout, p);
+      let line;
+      const onsets = mode === "audio" ? onsetsFor(ctx) : [];
+      if (mode === "audio" && onsets.length) {
+        line = audioPlayheadLine(layout, onsets, tMs);
+      } else {
+        line = playheadLine(layout, camProgress(tMs));
+      }
       if (!line) return;
       const c = ctx.ctx2d;
       c.save();
@@ -636,8 +741,12 @@ var scrollCursorFactory = {
     const errs = [];
     if (props == null || typeof props !== "object") return ["scroll-cursor: props must be an object"];
     const p = props;
-    if (typeof p.musicMs !== "number" || !(p.musicMs > 0))
-      errs.push("scroll-cursor.musicMs must be a positive number (total music length ms)");
+    if (p.mode != null && p.mode !== "audio" && p.mode !== "linear")
+      errs.push('scroll-cursor.mode must be "audio" | "linear"');
+    if (p.mode === "linear" && (typeof p.musicMs !== "number" || !(p.musicMs > 0)))
+      errs.push('scroll-cursor.musicMs must be a positive number for mode:"linear"');
+    if (p.musicMs != null && (typeof p.musicMs !== "number" || !(p.musicMs > 0)))
+      errs.push("scroll-cursor.musicMs must be a positive number");
     if (p.followBars != null && (typeof p.followBars !== "number" || p.followBars < 1))
       errs.push("scroll-cursor.followBars must be a number >= 1");
     if (p.openingZoomMs != null && (typeof p.openingZoomMs !== "number" || p.openingZoomMs < 0))
@@ -1169,11 +1278,11 @@ function spectrumLayer() {
     const src = fromProp ?? resolveFromCtx(ctx, tMs);
     if (src && src.length) {
       const out = new Array(n);
-      for (let b = 0; b < n; b++) out[b] = clamp01(src[Math.min(src.length - 1, b)] ?? 0);
+      for (let b = 0; b < n; b++) out[b] = clamp012(src[Math.min(src.length - 1, b)] ?? 0);
       return out;
     }
     const tSec = tMs / 1e3;
-    return Array.from({ length: n }, (_, b) => clamp01(syntheticMagnitude(tSec, b, n)));
+    return Array.from({ length: n }, (_, b) => clamp012(syntheticMagnitude(tSec, b, n)));
   }
   function resolveFromCtx(ctx, tMs) {
     const sp = ctx.spectrum;
@@ -1235,7 +1344,7 @@ function spectrumLayer() {
     }
   };
 }
-function clamp01(x) {
+function clamp012(x) {
   return x < 0 ? 0 : x > 1 ? 1 : x;
 }
 var spectrumFactory = {
@@ -2748,7 +2857,13 @@ function resolveTimeline(spec, totalSec) {
   return spec.timeline.map((seg) => {
     const startSec = resolveAnchor(seg.at[0], totalSec);
     const endSec = resolveAnchor(seg.at[1], totalSec);
-    return { startMs: startSec * 1e3, endMs: endSec * 1e3, layers: seg.layers, audio: seg.audio };
+    return {
+      startMs: startSec * 1e3,
+      endMs: endSec * 1e3,
+      layers: seg.layers,
+      audio: seg.audio,
+      transition: seg.transition
+    };
   });
 }
 function visualTimelineMs(resolved) {
@@ -2764,6 +2879,24 @@ var SCREEN_PINNED_KEYS = /* @__PURE__ */ new Set([
   "safe-guides",
   "mcq-card"
 ]);
+function defaultBufferFactory() {
+  const g = globalThis;
+  if (typeof g.OffscreenCanvas === "function") {
+    return (w, h) => {
+      const c = new g.OffscreenCanvas(w, h);
+      return { ctx: c.getContext("2d"), image: c };
+    };
+  }
+  if (typeof g.document !== "undefined" && g.document?.createElement) {
+    return (w, h) => {
+      const c = g.document.createElement("canvas");
+      c.width = w;
+      c.height = h;
+      return { ctx: c.getContext("2d"), image: c };
+    };
+  }
+  return void 0;
+}
 async function buildScene(opts) {
   const { spec, theme, score } = opts;
   const [W, H] = spec.size;
@@ -2771,6 +2904,8 @@ async function buildScene(opts) {
   const resolved = resolveTimeline(spec, opts.totalSec);
   const safe = safeBox(W, H);
   const camera = opts.camera ?? (() => identityCamera(W, H));
+  const bufferFactory = opts.bufferFactory ?? defaultBufferFactory();
+  const hasTransitions = resolved.some((s) => s.transition && s.transition.durationMs > 0);
   const clock = { nowMs: () => 0 };
   const baseCtx = {
     W,
@@ -2782,7 +2917,8 @@ async function buildScene(opts) {
     fps
   };
   const bound = [];
-  for (const seg of resolved) {
+  for (let segIndex = 0; segIndex < resolved.length; segIndex++) {
+    const seg = resolved[segIndex];
     for (const sl of seg.layers) {
       const factory = getLayerFactory(sl.k);
       if (!factory) {
@@ -2798,32 +2934,160 @@ async function buildScene(opts) {
         layer,
         startMs: seg.startMs,
         endMs: seg.endMs,
+        segIndex,
         screenPinned: SCREEN_PINNED_KEYS.has(sl.k)
       });
     }
   }
   const durationMs = visualTimelineMs(resolved);
-  function renderFrame(ctx2d, tMs) {
-    clock.nowMs = () => tMs;
-    const ctx = { ...baseCtx, ctx2d };
-    const cam = camera(tMs);
-    ctx2d.save();
-    applyToContext(ctx2d, cam, W, H);
+  function dirVec(dir) {
+    switch (dir) {
+      case "right":
+        return { x: 1, y: 0 };
+      case "up":
+        return { x: 0, y: -1 };
+      case "down":
+        return { x: 0, y: 1 };
+      case "left":
+      default:
+        return { x: -1, y: 0 };
+    }
+  }
+  function transitionEnvs(tr, p) {
+    if (tr.type === "push") {
+      const v = dirVec(tr.direction);
+      const span = Math.abs(v.x) ? W : H;
+      return {
+        incoming: { alpha: 1, dx: -v.x * span * (1 - p), dy: -v.y * span * (1 - p) },
+        outgoing: { alpha: 1, dx: v.x * span * p, dy: v.y * span * p }
+      };
+    }
+    if (tr.type === "wipe") {
+      const v = dirVec(tr.direction);
+      let inClip;
+      let outClip;
+      if (v.x !== 0) {
+        const w = W * p;
+        if (v.x < 0) {
+          inClip = { x: 0, y: 0, w, h: H };
+          outClip = { x: w, y: 0, w: W - w, h: H };
+        } else {
+          inClip = { x: W - w, y: 0, w, h: H };
+          outClip = { x: 0, y: 0, w: W - w, h: H };
+        }
+      } else {
+        const h = H * p;
+        if (v.y < 0) {
+          inClip = { x: 0, y: 0, w: W, h };
+          outClip = { x: 0, y: h, w: W, h: H - h };
+        } else {
+          inClip = { x: 0, y: H - h, w: W, h };
+          outClip = { x: 0, y: 0, w: W, h: H - h };
+        }
+      }
+      return {
+        incoming: { alpha: 1, dx: 0, dy: 0, clip: inClip },
+        outgoing: { alpha: 1, dx: 0, dy: 0, clip: outClip }
+      };
+    }
+    return {
+      incoming: { alpha: p, dx: 0, dy: 0 },
+      outgoing: { alpha: 1 - p, dx: 0, dy: 0 }
+    };
+  }
+  function frameplan(tMs) {
+    const plan = [];
+    for (let i = 0; i < resolved.length; i++) {
+      const seg = resolved[i];
+      if (tMs < seg.startMs || tMs >= seg.endMs) continue;
+      const tr = seg.transition;
+      const prev = i > 0 ? resolved[i - 1] : void 0;
+      const enterEnd = tr ? seg.startMs + Math.max(0, tr.durationMs) : seg.startMs;
+      const inEnter = tr && tr.durationMs > 0 && tMs < enterEnd && prev;
+      if (!inEnter) {
+        plan.push({ segIndex: i, drawTMs: tMs, env: null });
+        continue;
+      }
+      const p = transitionProgress(tMs, seg.startMs, tr.durationMs, tr.easing ?? easeInOut);
+      const { incoming, outgoing } = transitionEnvs(tr, p);
+      const heldTMs = clamp(tMs, prev.startMs, prev.endMs - 1);
+      plan.push({ segIndex: i - 1, drawTMs: heldTMs, env: outgoing });
+      plan.push({ segIndex: i, drawTMs: tMs, env: incoming });
+    }
+    return plan;
+  }
+  function drawSegmentInto(target, segIndex, drawTMs) {
+    const ctx = { ...baseCtx, ctx2d: target };
+    const cam = camera(drawTMs);
+    target.save();
+    applyToContext(target, cam, W, H);
     for (const b of bound) {
-      if (b.screenPinned) continue;
-      if (tMs < b.startMs || tMs >= b.endMs) continue;
-      b.layer.draw(ctx, tMs);
+      if (b.segIndex !== segIndex || b.screenPinned) continue;
+      if (drawTMs < b.startMs || drawTMs >= b.endMs) continue;
+      b.layer.draw(ctx, drawTMs);
     }
-    ctx2d.restore();
+    target.restore();
+    target.save();
+    target.setTransform(1, 0, 0, 1, 0, 0);
+    for (const b of bound) {
+      if (b.segIndex !== segIndex || !b.screenPinned) continue;
+      if (drawTMs < b.startMs || drawTMs >= b.endMs) continue;
+      b.layer.draw(ctx, drawTMs);
+    }
+    target.restore();
+  }
+  function compositeEntry(ctx2d, e) {
+    if (e.env === null) {
+      drawSegmentInto(ctx2d, e.segIndex, e.drawTMs);
+      return;
+    }
+    const env = e.env;
+    if (!bufferFactory) {
+      ctx2d.save();
+      ctx2d.globalAlpha = ctx2d.globalAlpha * env.alpha;
+      drawSegmentInto(ctx2d, e.segIndex, e.drawTMs);
+      ctx2d.restore();
+      return;
+    }
+    const buf = bufferFactory(W, H);
+    drawSegmentInto(buf.ctx, e.segIndex, e.drawTMs);
     ctx2d.save();
     ctx2d.setTransform(1, 0, 0, 1, 0, 0);
-    for (const b of bound) {
-      if (!b.screenPinned) continue;
-      if (tMs < b.startMs || tMs >= b.endMs) continue;
-      b.layer.draw(ctx, tMs);
+    if (env.alpha !== 1) ctx2d.globalAlpha = ctx2d.globalAlpha * env.alpha;
+    if (env.clip) {
+      ctx2d.beginPath();
+      ctx2d.rect(env.clip.x, env.clip.y, env.clip.w, env.clip.h);
+      ctx2d.clip();
     }
+    ctx2d.drawImage(buf.image, env.dx, env.dy, W, H);
     ctx2d.restore();
   }
+  function renderFrame(ctx2d, tMs) {
+    clock.nowMs = () => tMs;
+    const ctx = { ...baseCtx, ctx2d };
+    const cam = camera(tMs);
+    if (!hasTransitions) {
+      ctx2d.save();
+      applyToContext(ctx2d, cam, W, H);
+      for (const b of bound) {
+        if (b.screenPinned) continue;
+        if (tMs < b.startMs || tMs >= b.endMs) continue;
+        b.layer.draw(ctx, tMs);
+      }
+      ctx2d.restore();
+      ctx2d.save();
+      ctx2d.setTransform(1, 0, 0, 1, 0, 0);
+      for (const b of bound) {
+        if (!b.screenPinned) continue;
+        if (tMs < b.startMs || tMs >= b.endMs) continue;
+        b.layer.draw(ctx, tMs);
+      }
+      ctx2d.restore();
+      return;
+    }
+    const plan = frameplan(tMs);
+    for (const e of plan) compositeEntry(ctx2d, e);
+  }
   function scheduleAudio(instrument, baseSec) {
     let fired = 0;
     for (const seg of resolved) {
@@ -3207,6 +3471,7 @@ export {
   applySchedule,
   applyToContext,
   assertGate,
+  audioPlayheadLine,
   ballArc,
   ballX,
   beatGrid,
@@ -3236,6 +3501,7 @@ export {
   cueOpacity,
   degreeLabel,
   degreeLabelsFactory,
+  distinctOnsets,
   dotAt,
   drawCaption,
   drawHighlight,
@@ -3327,6 +3593,7 @@ export {
   staffAnchor,
   staffKeyboardRayFactory,
   staffRayDemoSpec,
+  transitionProgress,
   validateChordTrack,
   validateQuiz,
   validateSections,