@real-music-packages/web-core 0.42.2 → 0.44.0

package/dist/scene/index.d.ts

@@ -891,10 +891,23 @@ declare const portraitFactory: LayerFactory<PortraitProps>;
 interface BrandingProps {
     /** Wordmark to draw. Default theme.brand. */
     logo?: string;
+    /** Optional second line under the wordmark (e.g. a domain) — the brand-card
+     *  form used for an end-of-clip mark: wordmark + URL, nothing else. Omit
+     *  for the original single-line chrome mark. */
+    sub?: string;
+    /** Sub-line font size in px. Default size*0.5. */
+    subSize?: number;
+    /** Sub-line colour. Default color/theme.sepia at reduced alpha handled by
+     *  the caller's theme choice (no alpha applied here so callers stay in
+     *  control of exact tone). */
+    subColor?: string;
+    /** Gap between wordmark baseline and sub-line baseline, px. Default size*0.85. */
+    gap?: number;
     /** Show the safe-zone debug overlay on top (apps' ?safe=1). Default false. */
     safezone?: boolean;
     /** Vertical anchor as a fraction of safeBox height from its TOP. Default 1
-     *  (bottom edge of the safe box). */
+     *  (bottom edge of the safe box). With `sub` set, this anchors the WORDMARK
+     *  line and the sub-line is drawn `gap` px below it. */
     yFrac?: number;
     /** Font size in px. Default 34. */
     size?: number;
@@ -1731,10 +1744,15 @@ interface CompositeRhythmProps {
     tickH?: number;
     /** Merged-mark radius (world px). Default 12. */
     mergeR?: number;
-    /** Reference subdivision counts, drawn as faint rows ABOVE the LH row (e.g.
-     *  [3,2] for a 3-against-2 bar) — each divides `windowMs` into N equal
-     *  ticks. Default none. */
-    grids?: number[];
+    /** Reference subdivision rows, drawn as faint rows ABOVE the LH row. Two
+     *  forms per entry: a plain number N divides `windowMs` into N EQUAL ticks
+     *  (e.g. `3` for a triplet feel, `2` for straight eighths — a 3-against-2
+     *  bar is `grids: [3, 2]`); an array of positive weights draws ticks at
+     *  each GROUP's start per those relative durations (e.g. `[3, 3, 2]` for a
+     *  3-3-2 clave bar — ticks at fractions 0, 3/8, 6/8, labeled "3+3+2") — for
+     *  asymmetric groupings the rhythm montage needs that an equal-N grid can't
+     *  represent. Default none. */
+    grids?: Array<number | number[]>;
     /** Onsets within this many ms of each other collapse into ONE composite
      *  mark. Default 60. */
     mergeWindowMs?: number;
@@ -1755,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.85. */
+    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

@@ -1245,6 +1245,10 @@ var spectrumFactory = {
 // src/scene/layers/branding.ts
 function brandingLayer() {
   let logo;
+  let sub;
+  let subSize = 0;
+  let subColor;
+  let gap = 0;
   let safezone = false;
   let yFrac = 1;
   let size = 34;
@@ -1253,10 +1257,14 @@ function brandingLayer() {
     key: "branding",
     init(_ctx, props) {
       logo = props.logo;
+      sub = props.sub;
       safezone = props.safezone ?? false;
       yFrac = props.yFrac ?? 1;
       size = props.size ?? 34;
+      subSize = props.subSize ?? size * 0.5;
+      gap = props.gap ?? size * 0.85;
       color = props.color;
+      subColor = props.subColor;
     },
     draw(ctx) {
       const c = ctx.ctx2d;
@@ -1266,8 +1274,14 @@ function brandingLayer() {
       c.textAlign = "center";
       c.font = `italic ${size}px ${ctx.theme.fontBody}`;
       c.fillStyle = color ?? ctx.theme.sepia;
-      const y = sb.top + sb.h * yFrac - (yFrac >= 1 ? size * 0.3 : 0);
+      const pairShift = sub ? gap / 2 : 0;
+      const y = sb.top + sb.h * yFrac - (yFrac >= 1 ? size * 0.3 : 0) - pairShift;
       c.fillText(text, sb.cx, y);
+      if (sub) {
+        c.font = `${subSize}px ${ctx.theme.fontBody}`;
+        c.fillStyle = subColor ?? color ?? ctx.theme.sepia;
+        c.fillText(sub, sb.cx, y + gap);
+      }
       c.restore();
       if (safezone) drawSafeGuides(c);
     }
@@ -1281,6 +1295,10 @@ var brandingFactory = {
     const p = props;
     const errs = [];
     if (p.logo != null && typeof p.logo !== "string") errs.push("branding.logo must be a string");
+    if (p.sub != null && typeof p.sub !== "string") errs.push("branding.sub must be a string");
+    if (p.subSize != null && (typeof p.subSize !== "number" || p.subSize <= 0)) errs.push("branding.subSize must be a positive number");
+    if (p.subColor != null && typeof p.subColor !== "string") errs.push("branding.subColor must be a string");
+    if (p.gap != null && typeof p.gap !== "number") errs.push("branding.gap must be a number");
     if (p.safezone != null && typeof p.safezone !== "boolean") errs.push("branding.safezone must be a boolean");
     if (p.yFrac != null && typeof p.yFrac !== "number") errs.push("branding.yFrac must be a number");
     if (p.size != null && (typeof p.size !== "number" || p.size <= 0)) errs.push("branding.size must be a positive number");
@@ -4416,8 +4434,11 @@ function compositeRhythmLayer() {
       const lhY = yCenter - rowGap;
       const rhY = yCenter + rowGap;
       c.save();
-      grids.forEach((n, gi) => {
-        if (n <= 0) return;
+      grids.forEach((entry, gi) => {
+        const isGrouping = Array.isArray(entry);
+        const weights = isGrouping ? entry.filter((w) => w > 0) : [];
+        if (isGrouping && weights.length === 0) return;
+        if (!isGrouping && entry <= 0) return;
         const gy = lhY - rowGap * (grids.length - gi);
         c.strokeStyle = "rgba(26,22,20,0.22)";
         c.lineWidth = 2;
@@ -4425,8 +4446,20 @@ function compositeRhythmLayer() {
         c.moveTo(sb.left, gy);
         c.lineTo(sb.left + sb.w, gy);
         c.stroke();
-        for (let i = 0; i < n; i++) {
-          const t = w0 + (w1 - w0) * i / n;
+        const starts = [];
+        if (isGrouping) {
+          const total = weights.reduce((a, b) => a + b, 0);
+          let acc = 0;
+          for (const w of weights) {
+            starts.push(acc / total);
+            acc += w;
+          }
+        } else {
+          const n = entry;
+          for (let i = 0; i < n; i++) starts.push(i / n);
+        }
+        for (const f of starts) {
+          const t = w0 + (w1 - w0) * f;
           if (!revealed(t)) continue;
           const gx = x(t);
           c.strokeStyle = "rgba(26,22,20,0.38)";
@@ -4440,7 +4473,7 @@ function compositeRhythmLayer() {
         c.font = "600 22px system-ui, sans-serif";
         c.textAlign = "right";
         c.textBaseline = "middle";
-        c.fillText(String(n), sb.left - 10, gy);
+        c.fillText(isGrouping ? weights.join("+") : String(entry), sb.left - 10, gy);
       });
       const drawTicks = (ticks, y, color) => {
         c.fillStyle = color;
@@ -4532,8 +4565,14 @@ var compositeRhythmFactory = {
     if (p.rowGap != null && (typeof p.rowGap !== "number" || p.rowGap <= 0)) errs.push("composite-rhythm.rowGap must be a positive number");
     if (p.tickH != null && (typeof p.tickH !== "number" || p.tickH <= 0)) errs.push("composite-rhythm.tickH must be a positive number");
     if (p.mergeR != null && (typeof p.mergeR !== "number" || p.mergeR <= 0)) errs.push("composite-rhythm.mergeR must be a positive number");
-    if (p.grids != null && (!Array.isArray(p.grids) || p.grids.some((v) => typeof v !== "number" || v <= 0)))
-      errs.push("composite-rhythm.grids must be an array of positive numbers");
+    if (p.grids != null) {
+      const gridsValid = Array.isArray(p.grids) && p.grids.every((v) => {
+        if (typeof v === "number") return v > 0;
+        if (Array.isArray(v)) return v.length > 0 && v.every((w) => typeof w === "number" && w > 0);
+        return false;
+      });
+      if (!gridsValid) errs.push("composite-rhythm.grids must be an array of positive numbers or arrays of positive-number weights");
+    }
     if (p.mergeWindowMs != null && (typeof p.mergeWindowMs !== "number" || p.mergeWindowMs < 0))
       errs.push("composite-rhythm.mergeWindowMs must be a non-negative number");
     if (p.mergeColor != null && typeof p.mergeColor !== "string") errs.push("composite-rhythm.mergeColor must be a string");
@@ -4546,6 +4585,131 @@ 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.85;
+      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.shadowColor = color;
+          c.shadowBlur = 16 * 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) {
@@ -4596,6 +4760,7 @@ registerLayer(statCounterFactory);
 registerLayer(endCardFactory);
 registerLayer(imageRevealFactory);
 registerLayer(compositeRhythmFactory);
+registerLayer(handIndicatorFactory);
 
 // src/scene/audioLayers.ts
 function countInSchedule(opts) {
@@ -5413,6 +5578,7 @@ export {
   getKeyboardLayout,
   getLayerFactory,
   getNotationEngraving,
+  handIndicatorFactory,
   harmonyDemoSpec,
   highlightIntensity,
   hookFactory,