@real-music-packages/web-core 0.20.0 → 0.22.0

package/dist/scene/index.d.ts

@@ -678,12 +678,11 @@ 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.
+     * DEPRECATED / back-compat only. The cursor is ALWAYS audio-onset locked now —
+     * driven note-by-note off the audio clock against each note's `onsetMs` (see
+     * `ctx.score`). Both `'audio'` and `'linear'` resolve to that single onset path;
+     * `'linear'` no longer re-enables the legacy measure-linear sweep (removed —
+     * that was the drift footgun). Prefer leaving this unset.
      */
     mode?: 'audio' | 'linear';
     /**
@@ -704,9 +703,9 @@ interface ScrollCursorProps {
     /** Opening-zoom duration in ms before the music/cursor start (RSR INTRO_MS=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 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. */
+    /** DEPRECATED. Total music length in ms (RSR musicMs). No longer used to
+     *  position the cursor (the onset clock drives all pacing); accepted for
+     *  back-compat and ignored. */
     musicMs?: number;
     /** Cursor stroke colour. Defaults to theme.accent. */
     color?: string;
@@ -731,29 +730,38 @@ declare function measureSpanBox(rn: RenderedNotation, lo: number, hi: number): B
 declare function firstMeasureBox(rn: RenderedNotation): Box | null;
 /** Number of distinct measures in the notation. (RSR measureCount) */
 declare function measureCount(rn: RenderedNotation): number;
+/** The DISTINCT measure indices present in the engraving, ASCENDING. For excerpts
+ *  these do NOT start at 0 (e.g. bars 5-8 → [4,5,6,7]) and may be non-contiguous,
+ *  so the follow window must scroll across THESE indices, not a 0..measureCount
+ *  range. (measureCount returns maxIndex+1 — a count valid only for 0-based scores.) */
+declare function distinctMeasureIndices(rn: RenderedNotation): number[];
 /** The follow window (canvas coords) for a continuous measure-start position,
  *  spanning FOLLOW_BARS and lerping between adjacent windows. (RSR followBoxAt) */
 declare function followBoxAt(rn: RenderedNotation, posMeasures: number): Box | null;
 /**
- * The continuous follow-window START measure for an audio-clock progress 0..1.
+ * The continuous follow-window START measure (ABSOLUTE index) for an hstack
+ * audio-clock progress 0..1.
  *
- * INVARIANT: the bar the playhead is in (`curBar`) is ALWAYS fully inside the
- * FOLLOW_BARS-wide window. We anchor `curBar` as the BOTTOM (last) visible bar —
- * with the preceding FOLLOW_BARS-1 bars above it for context — so the window
- * holds steady while the playhead works through the visible bars and only scrolls
- * once the playhead reaches the bottom bar. Concretely the resting window start is
- * `curBar - (FOLLOW_BARS - 1)`; over the tail of each bar we ease that forward by
- * one bar so the NEXT bar slides into the bottom slot just as the playhead crosses
- * into it. Because the eased start stays within `[curBar-(FOLLOW_BARS-1),
- * curBar-(FOLLOW_BARS-2)]`, `curBar` never leaves `[start, start+FOLLOW_BARS)` —
- * the current measure (and its playhead) can never ride off the top.
+ * hstack (single horizontal staffline): pan CONTINUOUSLY so the playhead sits at a
+ * stable fraction (`HSTACK_PLAYHEAD_LEAD`) from the LEFT of the window — the playing
+ * bar is always on screen with look-ahead to its right, and the cursor never drifts
+ * to the screen edge.
  *
- * The scroll is cubic-eased (smooth, no hard jump) over the last portion of each
- * bar; result is clamped to [0, nBars-FOLLOW_BARS]. (Replaces RSR's original
- * +page.svelte:738-744 logic, which advanced the window to the NEXT bar over the
- * last third of EVERY bar and so pushed the still-current bar off the top.)
+ * BUG FIX (web-core 0.21.0) — playhead pinned at the right edge for EXCERPTS. This
+ * used to take `nBars = measureCount(rn) = maxIndex+1` and pan progress across a
+ * 0..nBars range. That is only correct when measure indices are 0-based: RSR's
+ * excerpts engrave e.g. bars 5-8 → indices [4,5,6,7], so measureCount=8 but only 4
+ * measures exist. The window then panned a phantom 0..8 axis while the playhead
+ * (which steps over the 4 REAL columns) raced ahead — pinning the cursor at the far
+ * right while the music barely scrolled. We now pan across the ACTUAL distinct
+ * indices: progress 0..1 maps to absolute index `firstIndex .. firstIndex+nReal`,
+ * and `followBoxAt` (which already indexes absolute measures via measureSpanBox)
+ * frames the right bars. Clamped so the window never runs past the last measure.
+ *
+ * Pass the RenderedNotation so the real index range is known. (The legacy 0-based
+ * `nBars`-only call still works via the `firstIndex=0, nReal=nBars` fallback.)
  */
-declare function followWindowStart(nBars: number, camProgress01: number): number;
+declare function followWindowStart(rn: RenderedNotation | number, camProgress01: number): number;
 /** For each measure index, the system (row) it lives on — ordered by index.
  *  Empty when geometry is missing. */
 declare function measureSystemMap(rn: RenderedNotation): number[];
@@ -1620,4 +1628,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, 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, measureSystemMap, 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, systemBox, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, vstackAudioPlayheadLine, vstackFollowBox, 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, distinctMeasureIndices, 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, measureSystemMap, 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, systemBox, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, vstackAudioPlayheadLine, vstackFollowBox, whiteKeys, worldToViewport };

package/dist/scene/index.js

@@ -390,6 +390,11 @@ function measureCount(rn) {
   const idx = (rn.measures ?? []).map((m) => m.index);
   return idx.length ? Math.max(...idx) + 1 : 0;
 }
+function distinctMeasureIndices(rn) {
+  const set = /* @__PURE__ */ new Set();
+  for (const m of rn.measures ?? []) set.add(m.index);
+  return [...set].sort((a, b) => a - b);
+}
 function followBoxAt(rn, posMeasures) {
   const cur = Math.floor(posMeasures);
   const frac = posMeasures - cur;
@@ -399,14 +404,25 @@ function followBoxAt(rn, posMeasures) {
   if (!b) return a;
   return lerpBox(a, b, frac);
 }
-function followWindowStart(nBars, camProgress01) {
-  const posBars = camProgress01 * nBars;
-  const curBar = Math.floor(posBars);
-  const frac = posBars - curBar;
-  const scrollFrac = cubicEaseInOut(Math.min(1, Math.max(0, (frac - 0.66) / 0.34)));
-  const restStart = curBar - (FOLLOW_BARS - 1);
-  const maxStart = Math.max(0, nBars - FOLLOW_BARS);
-  return Math.max(0, Math.min(maxStart, restStart + scrollFrac));
+var HSTACK_PLAYHEAD_LEAD = 0.35;
+function followWindowStart(rn, camProgress01) {
+  let firstIndex;
+  let nReal;
+  if (typeof rn === "number") {
+    firstIndex = 0;
+    nReal = rn;
+  } else {
+    const idx = distinctMeasureIndices(rn);
+    firstIndex = idx.length ? idx[0] : 0;
+    nReal = idx.length;
+  }
+  const p = Math.max(0, Math.min(1, camProgress01));
+  const posBars = firstIndex + p * nReal;
+  const start = posBars - HSTACK_PLAYHEAD_LEAD * FOLLOW_BARS;
+  const lastIndex = firstIndex + Math.max(0, nReal - 1);
+  const minStart = firstIndex;
+  const maxStart = Math.max(minStart, lastIndex - (FOLLOW_BARS - 1));
+  return Math.max(minStart, Math.min(maxStart, start));
 }
 function systemIndexOfBox(systems, box) {
   if (!systems.length) return 0;
@@ -802,25 +818,18 @@ var notationFactory = {
 };
 
 // src/scene/layers/scrollCursor.ts
-function followLayoutFor(ctx, camProgress01, scrollMode) {
+function followLayoutFor(ctx, progress012, scrollMode) {
   const eng = getNotationEngraving(ctx);
   if (!eng) return null;
   const nBars = measureCount(eng.rendered);
   if (nBars <= 0) return eng.base;
-  const focusBox = scrollMode === "vstack" ? vstackFollowBox(eng.rendered, camProgress01) : followBoxAt(eng.rendered, followWindowStart(nBars, camProgress01));
+  const focusBox = scrollMode === "vstack" ? vstackFollowBox(eng.rendered, progress012) : followBoxAt(eng.rendered, followWindowStart(eng.rendered, progress012));
   return notationLayout(eng.rendered, ctx.W, ctx.H, eng.bandTop, eng.bandHeight, { focusBox });
 }
 function scrollCursorLayer() {
-  let mode = "audio";
   let scrollMode = "hstack";
-  let musicMs = 0;
   let openingZoomMs = 900;
   let color;
-  function camProgress(tMs) {
-    const phMs = tMs - openingZoomMs;
-    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) : [];
@@ -843,9 +852,7 @@ function scrollCursorLayer() {
     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);
+    return notesProgress(onsetsFor(ctx), tMs);
   }
   function layoutAt(ctx, tMs) {
     const eng = getNotationEngraving(ctx);
@@ -854,9 +861,7 @@ function scrollCursorLayer() {
   return {
     key: "scroll-cursor",
     init(ctx, props) {
-      mode = props.mode ?? "audio";
       scrollMode = props.scrollMode ?? "hstack";
-      musicMs = props.musicMs ?? 0;
       openingZoomMs = props.openingZoomMs ?? 900;
       color = props.color;
       setFollowLayoutProvider(ctx, layoutAt);
@@ -865,16 +870,12 @@ function scrollCursorLayer() {
       const eng = getNotationEngraving(ctx);
       if (!eng) return;
       const layout = layoutAt(ctx, tMs);
+      const onsets = onsetsFor(ctx);
       let line;
-      const onsets = mode === "audio" ? onsetsFor(ctx) : [];
-      if (mode === "audio" && onsets.length) {
-        if (scrollMode === "vstack") {
-          line = vstackAudioPlayheadLine(layout, onsets, tMs, measureCount(eng.rendered));
-        } else {
-          line = audioPlayheadLine(layout, onsets, tMs);
-        }
+      if (scrollMode === "vstack") {
+        line = vstackAudioPlayheadLine(layout, onsets, tMs, measureCount(eng.rendered));
       } else {
-        line = playheadLine(layout, camProgress(tMs));
+        line = audioPlayheadLine(layout, onsets, tMs);
       }
       if (!line) return;
       const c = ctx.ctx2d;
@@ -901,8 +902,6 @@ var scrollCursorFactory = {
       errs.push('scroll-cursor.mode must be "audio" | "linear"');
     if (p.scrollMode != null && p.scrollMode !== "hstack" && p.scrollMode !== "vstack")
       errs.push('scroll-cursor.scrollMode must be "hstack" | "vstack"');
-    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))
@@ -3812,6 +3811,7 @@ export {
   cueOpacity,
   degreeLabel,
   degreeLabelsFactory,
+  distinctMeasureIndices,
   distinctOnsets,
   dotAt,
   drawCaption,