@real-music-packages/web-core 0.19.0 → 0.21.0

package/dist/scene/index.d.ts

@@ -731,29 +731,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[];
@@ -834,6 +843,7 @@ declare function distinctOnsets(notes: {
  * (first→last onset), not on musicMs — so the fade tracks the notes too.
  */
 declare function audioPlayheadLine(layout: NotationLayout, onsetsMs: number[], tMs: number): PlayheadLine | null;
+declare function vstackAudioPlayheadLine(layout: NotationLayout, onsetsMs: number[], tMs: number, nBars: 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;
@@ -1619,4 +1629,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, 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

@@ -323,6 +323,28 @@ function cubicEaseInOut(t) {
   const f = 2 * t - 2;
   return 0.5 * f * f * f + 1;
 }
+function staffSpacePx(rn) {
+  const hs = (rn.measures ?? []).map((m) => m.box.h).filter((h) => h > 1).sort((a, b) => a - b);
+  if (!hs.length) return 14;
+  const med = hs[Math.floor(hs.length / 2)];
+  return Math.max(6, med / 4);
+}
+function withLedgerHeadroom(rn, box, spaces, unionInk) {
+  const pad = staffSpacePx(rn) * spaces;
+  const ch = rn.canvas.height || box.y + box.h;
+  let y0 = box.y - pad;
+  let y1 = box.y + box.h + pad;
+  if (unionInk) {
+    const c = rn.content;
+    if (c && c.h > 0) {
+      y0 = Math.min(y0, c.y);
+      y1 = Math.max(y1, c.y + c.h);
+    }
+  }
+  y0 = Math.max(0, y0);
+  y1 = Math.min(ch, y1);
+  return { x: box.x, y: y0, w: box.w, h: Math.max(1, y1 - y0) };
+}
 function lerpBox(a, b, e) {
   return {
     x: a.x + (b.x - a.x) * e,
@@ -353,7 +375,7 @@ function measureSpanBox(rn, lo, hi) {
   const y0 = Math.min(...ms.map((b) => b.y));
   const x1 = Math.max(...ms.map((b) => b.x + b.w));
   const y1 = Math.max(...ms.map((b) => b.y + b.h));
-  return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+  return withLedgerHeadroom(rn, { x: x0, y: y0, w: x1 - x0, h: y1 - y0 }, 6, true);
 }
 function firstMeasureBox(rn) {
   const first = (rn.measures ?? []).filter((m) => m.index === 0).map((m) => m.box);
@@ -362,12 +384,17 @@ function firstMeasureBox(rn) {
   const y0 = Math.min(...first.map((b) => b.y));
   const x1 = Math.max(...first.map((b) => b.x + b.w));
   const y1 = Math.max(...first.map((b) => b.y + b.h));
-  return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+  return withLedgerHeadroom(rn, { x: x0, y: y0, w: x1 - x0, h: y1 - y0 }, 6, false);
 }
 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;
@@ -377,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;
@@ -421,7 +459,7 @@ function systemBox(rn, sys, sysMap) {
   const y0 = Math.min(...boxes.map((b) => b.y));
   const x1 = Math.max(...boxes.map((b) => b.x + b.w));
   const y1 = Math.max(...boxes.map((b) => b.y + b.h));
-  return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+  return withLedgerHeadroom(rn, { x: x0, y: y0, w: x1 - x0, h: y1 - y0 }, 8, false);
 }
 function vstackFollowBox(rn, camProgress01) {
   const sysMap = measureSystemMap(rn);
@@ -617,6 +655,69 @@ function audioPlayheadLine(layout, onsetsMs, tMs) {
   if (alpha <= 0.02) return null;
   return { x, y0, y1, alpha };
 }
+function vstackAudioPlayheadLine(layout, onsetsMs, tMs, nBars) {
+  const padV = 10;
+  const cols = measureColumnsFromLayout(layout.measures);
+  if (!cols.length || !onsetsMs.length || nBars <= 0) return null;
+  const n = onsetsMs.length;
+  const first = onsetsMs[0];
+  const last = onsetsMs[n - 1];
+  const span = last - first;
+  let progress;
+  if (tMs <= first || n === 1) progress = 0;
+  else if (tMs >= last || last <= first) progress = 1;
+  else {
+    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 = cubicEaseInOut((tMs - onsetsMs[lo]) / (onsetsMs[lo + 1] - onsetsMs[lo]));
+    progress = (lo + segFrac) / (n - 1);
+  }
+  const colX = (m2, f) => {
+    const sx = Math.min(m2.noteStartX, m2.x + m2.w);
+    return sx + Math.min(1, Math.max(0, f)) * (m2.x + m2.w - sx);
+  };
+  const posBars = Math.min(nBars - 1e-6, Math.max(0, progress * nBars));
+  const i = Math.min(cols.length - 1, Math.floor(posBars));
+  const barFrac = posBars - i;
+  const m = cols[i];
+  let x = colX(m, barFrac);
+  let y0 = m.y - padV;
+  let y1 = m.y + m.h + padV;
+  if (i + 1 < cols.length) {
+    const nxt = cols[i + 1];
+    const crossesSystem = Math.abs(nxt.y - m.y) > m.h * 1.5;
+    if (crossesSystem) {
+      const s = cubicEaseInOut(Math.min(1, Math.max(0, (barFrac - 0.66) / 0.34)));
+      x = x + (colX(nxt, 0) - x) * s;
+      y0 = y0 + (nxt.y - padV - y0) * s;
+      y1 = y1 + (nxt.y + nxt.h + padV - y1) * s;
+    }
+  }
+  const bandY0 = layout.rect.dy;
+  const bandY1 = layout.rect.dy + layout.rect.dh;
+  const h = Math.max(1, y1 - y0);
+  if (y0 < bandY0) {
+    y0 = bandY0;
+    y1 = bandY0 + h;
+  }
+  if (y1 > bandY1) {
+    y1 = bandY1;
+    y0 = bandY1 - h;
+  }
+  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();
@@ -722,7 +823,7 @@ function followLayoutFor(ctx, camProgress01, scrollMode) {
   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, camProgress01) : followBoxAt(eng.rendered, followWindowStart(eng.rendered, camProgress01));
   return notationLayout(eng.rendered, ctx.W, ctx.H, eng.bandTop, eng.bandHeight, { focusBox });
 }
 function scrollCursorLayer() {
@@ -783,7 +884,11 @@ function scrollCursorLayer() {
       let line;
       const onsets = mode === "audio" ? onsetsFor(ctx) : [];
       if (mode === "audio" && onsets.length) {
-        line = audioPlayheadLine(layout, onsets, tMs);
+        if (scrollMode === "vstack") {
+          line = vstackAudioPlayheadLine(layout, onsets, tMs, measureCount(eng.rendered));
+        } else {
+          line = audioPlayheadLine(layout, onsets, tMs);
+        }
       } else {
         line = playheadLine(layout, camProgress(tMs));
       }
@@ -3723,6 +3828,7 @@ export {
   cueOpacity,
   degreeLabel,
   degreeLabelsFactory,
+  distinctMeasureIndices,
   distinctOnsets,
   dotAt,
   drawCaption,
@@ -3822,6 +3928,7 @@ export {
   validateQuiz,
   validateSections,
   visualTimelineMs,
+  vstackAudioPlayheadLine,
   vstackFollowBox,
   whiteKeys,
   worldToViewport