@real-music-packages/web-core 0.43.0 → 0.44.1

package/dist/scene/index.d.ts

@@ -1773,4 +1773,29 @@ interface CompositeRhythmProps {
 }
 declare const compositeRhythmFactory: LayerFactory<CompositeRhythmProps>;
 
-export { type Affine, AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatPulseProps, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordRibbonProps, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type CompositeRhythmProps, type ContourPlot, type ContourPoint, type CountInOpts, type CountdownProps, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type EndCardProps, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, type FallingKeyboardDemoOpts, type FallingNotesProps, type FretboardProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type ImageRevealMode, type ImageRevealProps, type IntervalArcsProps, type KaraokeCaptionProps, type KaraokeWord, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type KineticMode, type KineticTextProps, type LabelMode, LayerFactory, type McqCardProps, type NotationEngraving, NotationLayout, type NotationProps, type OutputProbe, PIANO_HIGH, PIANO_LOW, type ParticleBurstProps, type PitchContourProps, type Placement, type PortraitProps, type ProgressRingProps, type PromoCardsDemoOpts, type PulseStyle, type Quiz, type QuizOption, type QuizPhase, type RadialSpectrumProps, type RayEndpoints, type RecordSceneSpecOpts, type Rect, RenderCtx, type ResolvedSegment, type RevealEasing, type RevealProps, SCALE_INTERVALS, type SafeGuidesProps, type ScaleHighlightProps, type SceneSpec, type ScheduleTarget, Score, ScoreFromMusicXMLOpts, ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type StaffKeyboardRayProps, type StatCounterProps, TempoMap, type TensionGraphProps, type TensionPoint, type TextureProps, type TimeAnchor, type TimelineSegment, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, ballArc, ballX, beatGrid, beatPhase, beatPulseFactory, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, chordRibbonFactory, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, compositeRhythmFactory, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownFactory, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, ctaFactory, cueOpacity, degreeLabel, degreeLabelsFactory, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, endCardFactory, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, followSrcBox, fracSlotPoint, frameRect, fretboardFactory, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, imageRevealFactory, inRange, intervalArcsFactory, invLerp, isBlackKey, karaokeCaptionFactory, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, kineticTextFactory, lerp, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureSpans, timeToX as minimapTimeToX, msPerBeat, notationFactory, noteColor, noteSetXRange, parseKey, parseTimeSig, particleBurstFactory, pcToSlot, pitchAt, pitchContourFactory, pitchRange, portraitFactory, progress01, progressRingFactory, projectPoint, promoCardsDemoSpec, pulseAt, quizPhase, radialSpectrumFactory, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scaleHighlightFactory, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, statCounterFactory, tensionGraphFactory, textureFactory, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, whiteKeys, worldToViewport };
+interface HandIndicatorProps {
+    /** Top of the hand band, world px. Required — the caller owns this route's
+     *  vertical layout; this layer only draws at the given y. */
+    y: number;
+    /** Band height, world px. Default 60. */
+    height?: number;
+    /** Hand colours — the SAME tokens the keyboard/composite-rhythm layers use.
+     *  Default R = theme.accent, L = theme.gold. */
+    handColors?: HandColors;
+    /** How fast a hand fades from lit back to its resting outline after its
+     *  last active note ends, ms. Default 200 (the "quickly" in ~150-250ms). */
+    fadeMs?: number;
+    /** Icon size, px (roughly the glyph's bounding box). Default height*0.78. */
+    size?: number;
+    /** LH icon x, fraction of safeBox width from its left edge. Default 0.26
+     *  (under the lower/bass register). */
+    leftXFrac?: number;
+    /** RH icon x, fraction of safeBox width from its left edge. Default 0.74
+     *  (under the upper/treble register). */
+    rightXFrac?: number;
+    /** Baseline (resting/unlit) outline alpha. Default 0.32. */
+    restAlpha?: number;
+}
+declare const handIndicatorFactory: LayerFactory<HandIndicatorProps>;
+
+export { type Affine, AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatPulseProps, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordRibbonProps, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type CompositeRhythmProps, type ContourPlot, type ContourPoint, type CountInOpts, type CountdownProps, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type EndCardProps, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, type FallingKeyboardDemoOpts, type FallingNotesProps, type FretboardProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HandIndicatorProps, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type ImageRevealMode, type ImageRevealProps, type IntervalArcsProps, type KaraokeCaptionProps, type KaraokeWord, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type KineticMode, type KineticTextProps, type LabelMode, LayerFactory, type McqCardProps, type NotationEngraving, NotationLayout, type NotationProps, type OutputProbe, PIANO_HIGH, PIANO_LOW, type ParticleBurstProps, type PitchContourProps, type Placement, type PortraitProps, type ProgressRingProps, type PromoCardsDemoOpts, type PulseStyle, type Quiz, type QuizOption, type QuizPhase, type RadialSpectrumProps, type RayEndpoints, type RecordSceneSpecOpts, type Rect, RenderCtx, type ResolvedSegment, type RevealEasing, type RevealProps, SCALE_INTERVALS, type SafeGuidesProps, type ScaleHighlightProps, type SceneSpec, type ScheduleTarget, Score, ScoreFromMusicXMLOpts, ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type StaffKeyboardRayProps, type StatCounterProps, TempoMap, type TensionGraphProps, type TensionPoint, type TextureProps, type TimeAnchor, type TimelineSegment, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, ballArc, ballX, beatGrid, beatPhase, beatPulseFactory, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, chordRibbonFactory, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, compositeRhythmFactory, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownFactory, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, ctaFactory, cueOpacity, degreeLabel, degreeLabelsFactory, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, endCardFactory, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, followSrcBox, fracSlotPoint, frameRect, fretboardFactory, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, handIndicatorFactory, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, imageRevealFactory, inRange, intervalArcsFactory, invLerp, isBlackKey, karaokeCaptionFactory, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, kineticTextFactory, lerp, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureSpans, timeToX as minimapTimeToX, msPerBeat, notationFactory, noteColor, noteSetXRange, parseKey, parseTimeSig, particleBurstFactory, pcToSlot, pitchAt, pitchContourFactory, pitchRange, portraitFactory, progress01, progressRingFactory, projectPoint, promoCardsDemoSpec, pulseAt, quizPhase, radialSpectrumFactory, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scaleHighlightFactory, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, statCounterFactory, tensionGraphFactory, textureFactory, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, whiteKeys, worldToViewport };

package/dist/scene/index.js

@@ -4585,6 +4585,129 @@ var compositeRhythmFactory = {
   }
 };
 
+// src/scene/layers/handIndicator.ts
+function activeOpacity(notes, tMs, fadeMs) {
+  let lastEnd = -Infinity;
+  for (const n of notes) {
+    const end = n.onsetMs + n.durMs;
+    if (tMs >= n.onsetMs && tMs < end) return 1;
+    if (end <= tMs && end > lastEnd) lastEnd = end;
+  }
+  if (lastEnd === -Infinity) return 0;
+  const dt = tMs - lastEnd;
+  if (dt >= fadeMs) return 0;
+  return 1 - dt / fadeMs;
+}
+function roundedPath2(c, x, y, w, h, r) {
+  c.beginPath();
+  const rr = c.roundRect;
+  if (typeof rr === "function") {
+    rr.call(c, x, y, w, h, r);
+    return;
+  }
+  c.rect(x, y, w, h);
+}
+function drawHandGlyph(c, cx, cy, size, mirror, mode) {
+  const paint = () => {
+    if (mode === "fill") c.fill();
+    else c.stroke();
+  };
+  const palmW = size * 0.66, palmH = size * 0.56;
+  const px0 = cx - palmW / 2, py0 = cy - palmH * 0.1;
+  roundedPath2(c, px0, py0, palmW, palmH, palmW * 0.32);
+  paint();
+  const fingerW = palmW * 0.17;
+  const lens = [0.36, 0.46, 0.42, 0.32];
+  for (let i = 0; i < 4; i++) {
+    const fx = px0 + palmW * (0.12 + i * 0.25) - fingerW / 2;
+    const fLen = size * lens[i];
+    const fy = py0 - fLen + size * 0.06;
+    roundedPath2(c, fx, fy, fingerW, fLen, fingerW / 2);
+    paint();
+  }
+  const thumbW = palmW * 0.24, thumbLen = size * 0.3;
+  const sign = mirror ? -1 : 1;
+  c.save();
+  c.translate(cx + sign * palmW * 0.42, py0 + palmH * 0.32);
+  c.rotate(sign * 0.55);
+  roundedPath2(c, -thumbW / 2, 0, thumbW, thumbLen, thumbW / 2);
+  paint();
+  c.restore();
+}
+function handIndicatorLayer() {
+  let y = 0;
+  let height = 60;
+  let hands = { R: "#7b2436", L: "#c8a55b" };
+  let fadeMs = 200;
+  let size = 0;
+  let leftXFrac = 0.26;
+  let rightXFrac = 0.74;
+  let restAlpha = 0.32;
+  let lNotes = [];
+  let rNotes = [];
+  return {
+    key: "hand-indicator",
+    init(ctx, props) {
+      y = props.y;
+      height = props.height ?? 60;
+      hands = props.handColors ?? { R: ctx.theme.accent, L: ctx.theme.gold };
+      fadeMs = props.fadeMs ?? 200;
+      size = props.size ?? height * 0.78;
+      leftXFrac = props.leftXFrac ?? 0.26;
+      rightXFrac = props.rightXFrac ?? 0.74;
+      restAlpha = props.restAlpha ?? 0.32;
+      const notes = ctx.score?.notes ?? [];
+      lNotes = notes.filter((n) => n.hand === "L").map((n) => ({ onsetMs: n.onsetMs, durMs: n.durMs }));
+      rNotes = notes.filter((n) => n.hand === "R").map((n) => ({ onsetMs: n.onsetMs, durMs: n.durMs }));
+    },
+    draw(ctx, tMs) {
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const cy = y + height / 2;
+      const drawHand = (frac, color, notes, mirror) => {
+        const cx = sb.left + sb.w * frac;
+        const op = activeOpacity(notes, tMs, fadeMs);
+        c.save();
+        c.globalAlpha = restAlpha;
+        c.strokeStyle = color;
+        c.lineWidth = Math.max(1.5, size * 0.035);
+        drawHandGlyph(c, cx, cy, size, mirror, "stroke");
+        c.restore();
+        if (op > 0.01) {
+          c.save();
+          c.globalAlpha = op;
+          c.fillStyle = color;
+          drawHandGlyph(c, cx, cy, size, mirror, "fill");
+          c.restore();
+        }
+      };
+      drawHand(leftXFrac, hands.L, lNotes, true);
+      drawHand(rightXFrac, hands.R, rNotes, false);
+    },
+    dispose() {
+      lNotes = [];
+      rNotes = [];
+    }
+  };
+}
+var handIndicatorFactory = {
+  key: "hand-indicator",
+  create: handIndicatorLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["hand-indicator: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (typeof p.y !== "number") errs.push("hand-indicator.y is required and must be a number");
+    if (p.height != null && (typeof p.height !== "number" || p.height <= 0)) errs.push("hand-indicator.height must be a positive number");
+    if (p.fadeMs != null && (typeof p.fadeMs !== "number" || p.fadeMs <= 0)) errs.push("hand-indicator.fadeMs must be a positive number");
+    if (p.size != null && (typeof p.size !== "number" || p.size <= 0)) errs.push("hand-indicator.size must be a positive number");
+    if (p.leftXFrac != null && typeof p.leftXFrac !== "number") errs.push("hand-indicator.leftXFrac must be a number");
+    if (p.rightXFrac != null && typeof p.rightXFrac !== "number") errs.push("hand-indicator.rightXFrac must be a number");
+    if (p.restAlpha != null && (typeof p.restAlpha !== "number" || p.restAlpha < 0 || p.restAlpha > 1)) errs.push("hand-indicator.restAlpha must be a number in [0,1]");
+    return errs;
+  }
+};
+
 // src/scene/registry.ts
 var REGISTRY = /* @__PURE__ */ new Map();
 function registerLayer(factory) {
@@ -4635,6 +4758,7 @@ registerLayer(statCounterFactory);
 registerLayer(endCardFactory);
 registerLayer(imageRevealFactory);
 registerLayer(compositeRhythmFactory);
+registerLayer(handIndicatorFactory);
 
 // src/scene/audioLayers.ts
 function countInSchedule(opts) {
@@ -5452,6 +5576,7 @@ export {
   getKeyboardLayout,
   getLayerFactory,
   getNotationEngraving,
+  handIndicatorFactory,
   harmonyDemoSpec,
   highlightIntensity,
   hookFactory,