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

package/dist/scene/index.d.ts

@@ -670,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;
 }
@@ -755,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;
@@ -1532,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 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, 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, transitionProgress, 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

@@ -489,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();
@@ -593,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;
@@ -601,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);
@@ -616,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();
@@ -640,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))
@@ -1173,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;
@@ -1239,7 +1344,7 @@ function spectrumLayer() {
     }
   };
 }
-function clamp01(x) {
+function clamp012(x) {
   return x < 0 ? 0 : x > 1 ? 1 : x;
 }
 var spectrumFactory = {
@@ -3366,6 +3471,7 @@ export {
   applySchedule,
   applyToContext,
   assertGate,
+  audioPlayheadLine,
   ballArc,
   ballX,
   beatGrid,
@@ -3395,6 +3501,7 @@ export {
   cueOpacity,
   degreeLabel,
   degreeLabelsFactory,
+  distinctOnsets,
   dotAt,
   drawCaption,
   drawHighlight,