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

package/dist/scene/index.d.ts

@@ -834,6 +834,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 +1620,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, 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,7 +384,7 @@ 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);
@@ -421,7 +443,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 +639,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();
@@ -783,7 +868,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));
       }
@@ -3822,6 +3911,7 @@ export {
   validateQuiz,
   validateSections,
   visualTimelineMs,
+  vstackAudioPlayheadLine,
   vstackFollowBox,
   whiteKeys,
   worldToViewport