npm - @real-music-packages/web-core - Versions diffs - 0.11.0 → 0.12.0 - Mend

@real-music-packages/web-core 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +25 -0
package/dist/scene/headless.d.ts +10 -0
package/dist/scene/headless.js +108 -0
package/dist/scene/headless.js.map +1 -0
package/dist/scene/index.d.ts +459 -10
package/dist/scene/index.js +1446 -140
package/dist/scene/index.js.map +1 -1
package/package.json +5 -1

package/dist/scene/index.js CHANGED Viewed

@@ -92,8 +92,8 @@ function resolveTempo(sheet, opts) {
   return { source: "fallback", segments: [{ atMs: 0, bpm: opts.tempoFallback ?? 100 }] };
 }
 function makeWholeNoteToMs(bpm) {
-  const msPerBeat = 6e4 / bpm;
-  return (wholeNotes) => wholeNotes * BEATS_PER_WHOLE_NOTE * msPerBeat;
+  const msPerBeat2 = 6e4 / bpm;
+  return (wholeNotes) => wholeNotes * BEATS_PER_WHOLE_NOTE * msPerBeat2;
 }
 function inferHand(instrument, staff) {
   const staves = instrument?.Staves;
@@ -149,7 +149,7 @@ function readTimeSig(sheet) {
 async function defaultOsmd() {
   if (typeof document === "undefined") {
     throw new Error(
-      "scoreFromMusicXML: no DOM. Call setupHeadlessDom() first (Node), or pass opts.osmdFactory."
+      "scoreFromMusicXML: no DOM. In Node, import setupHeadlessDom from '@real-music-packages/web-core/scene/headless' and call it first, or pass opts.osmdFactory."
     );
   }
   const mod = await import("opensheetmusicdisplay");
@@ -160,111 +160,6 @@ async function defaultOsmd() {
   });
 }
-// src/scene/headless.ts
-var installed = false;
-async function setupHeadlessDom() {
-  if (installed) return;
-  const g = globalThis;
-  if (typeof g.document !== "undefined" && typeof g.window !== "undefined") {
-    ensureFakeContext(g.window);
-    installed = true;
-    return;
-  }
-  const { JSDOM } = await import("jsdom");
-  const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>", {
-    pretendToBeVisual: true
-  });
-  const { window } = dom;
-  ensureFakeContext(window);
-  g.window = window;
-  g.document = window.document;
-  try {
-    g.navigator = window.navigator;
-  } catch {
-  }
-  g.HTMLElement = window.HTMLElement;
-  g.Node = window.Node;
-  g.DOMParser = window.DOMParser;
-  g.XMLSerializer = window.XMLSerializer;
-  g.requestAnimationFrame = (cb) => setTimeout(() => cb(Date.now()), 0);
-  g.cancelAnimationFrame = () => {
-  };
-  installed = true;
-}
-function ensureFakeContext(window) {
-  const proto = window.HTMLCanvasElement?.prototype;
-  if (!proto) return;
-  const fakeCtx = makeFakeContext();
-  proto.getContext = function() {
-    return fakeCtx;
-  };
-}
-function makeFakeContext() {
-  return {
-    font: "10px Arial",
-    fillStyle: "#000",
-    strokeStyle: "#000",
-    lineWidth: 1,
-    textAlign: "left",
-    textBaseline: "alphabetic",
-    globalAlpha: 1,
-    measureText: (s) => ({
-      width: (s ? s.length : 0) * 6,
-      actualBoundingBoxAscent: 8,
-      actualBoundingBoxDescent: 2
-    }),
-    save() {
-    },
-    restore() {
-    },
-    beginPath() {
-    },
-    closePath() {
-    },
-    moveTo() {
-    },
-    lineTo() {
-    },
-    bezierCurveTo() {
-    },
-    quadraticCurveTo() {
-    },
-    arc() {
-    },
-    rect() {
-    },
-    fill() {
-    },
-    stroke() {
-    },
-    fillRect() {
-    },
-    clearRect() {
-    },
-    fillText() {
-    },
-    strokeText() {
-    },
-    translate() {
-    },
-    rotate() {
-    },
-    scale() {
-    },
-    setTransform() {
-    },
-    transform() {
-    },
-    drawImage() {
-    },
-    clip() {
-    },
-    createLinearGradient: () => ({ addColorStop() {
-    } }),
-    getImageData: () => ({ data: new Uint8ClampedArray(4) })
-  };
-}
 // src/scene/math.ts
 var clamp = (x, lo, hi) => x < lo ? lo : x > hi ? hi : x;
 var lerp = (a, b, t) => a + (b - a) * t;
@@ -1427,6 +1322,1268 @@ var safeGuidesFactory = {
   }
 };
+// src/scene/staffKeyboardRay.ts
+function staffAnchor(layout, t01) {
+  const tt = Math.max(0, Math.min(1, t01));
+  const cols = measureColumnsFromLayout(layout.measures);
+  if (cols.length) {
+    const pos = tt * cols.length;
+    const i = Math.min(cols.length - 1, Math.floor(pos));
+    const m = cols[i];
+    const startX = Math.min(m.noteStartX, m.x + m.w);
+    const x = startX + (pos - i) * (m.x + m.w - startX);
+    return { x, y: m.y + m.h / 2 };
+  }
+  if (layout.systems.length) {
+    const pos = tt * layout.systems.length;
+    const row = Math.min(layout.systems.length - 1, Math.floor(pos));
+    const s = layout.systems[row];
+    return { x: s.x + (pos - row) * s.w, y: s.y + s.h / 2 };
+  }
+  const r = layout.rect;
+  return { x: r.dx + tt * r.dw, y: r.dy + r.dh / 2 };
+}
+function rayEndpoints(notation, keyboard, pitchMidi, t01) {
+  const staff = staffAnchor(notation, t01);
+  if (!staff) return null;
+  return {
+    staff,
+    keyboard: { x: keyCenterX(keyboard, pitchMidi), y: keyboard.top }
+  };
+}
+function rayPointAt(ends, u, bulge = 0.18) {
+  const { staff: a, keyboard: b } = ends;
+  const mx = (a.x + b.x) / 2;
+  const my = (a.y + b.y) / 2;
+  const span = Math.abs(b.y - a.y);
+  const cx = mx + bulge * span;
+  const cy = my;
+  const uu = u < 0 ? 0 : u > 1 ? 1 : u;
+  const inv = 1 - uu;
+  return {
+    x: inv * inv * a.x + 2 * inv * uu * cx + uu * uu * b.x,
+    y: inv * inv * a.y + 2 * inv * uu * cy + uu * uu * b.y
+  };
+}
+// src/scene/highlight.ts
+function highlightIntensity(region, tMs) {
+  const fade = region.fadeMs ?? 120;
+  if (tMs <= region.inMs - fade || tMs >= region.outMs + fade) return 0;
+  const rampIn = invLerp(region.inMs - fade, region.inMs, tMs);
+  const rampOut = 1 - invLerp(region.outMs, region.outMs + fade, tMs);
+  return clamp(Math.min(rampIn, rampOut), 0, 1);
+}
+function noteSetXRange(onsetsMs, windowMs, timeToX2) {
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const on of onsetsMs) {
+    if (on < windowMs[0] || on > windowMs[1]) continue;
+    const x = timeToX2(on);
+    if (x < lo) lo = x;
+    if (x > hi) hi = x;
+  }
+  if (lo === Infinity) return null;
+  return { x: lo, w: Math.max(0, hi - lo) };
+}
+function drawHighlight(ctx, region, tMs, accent) {
+  const a = highlightIntensity(region, tMs);
+  if (a <= 0) return;
+  ctx.save();
+  ctx.globalAlpha = a * 0.35;
+  ctx.fillStyle = region.color ?? accent;
+  ctx.fillRect(region.x, region.y, region.w, region.h);
+  ctx.restore();
+}
+// src/scene/layers/staffKeyboardRay.ts
+var DEFAULT_FADE = 180;
+var DEFAULT_WIDTH = 4;
+var DEFAULT_SEGMENTS = 24;
+function staffKeyboardRayLayer() {
+  let fadeMs = DEFAULT_FADE;
+  let width = DEFAULT_WIDTH;
+  let color;
+  let segments = DEFAULT_SEGMENTS;
+  return {
+    key: "staff-keyboard-ray",
+    init(_ctx, props) {
+      fadeMs = props.fadeMs ?? DEFAULT_FADE;
+      width = props.width ?? DEFAULT_WIDTH;
+      color = props.color;
+      segments = props.segments ?? DEFAULT_SEGMENTS;
+    },
+    draw(ctx, tMs) {
+      const eng = getNotationEngraving(ctx);
+      const kbd = getKeyboardLayout(ctx);
+      if (!eng || !kbd) return;
+      const layout = eng.followLayoutAt ? eng.followLayoutAt(ctx, tMs) : eng.base;
+      const dur = ctx.score?.durationMs ?? 0;
+      const t01 = dur > 0 ? tMs / dur : 0;
+      const c = ctx.ctx2d;
+      const accent = color ?? ctx.theme.accent;
+      for (const n of ctx.score?.notes ?? []) {
+        if (!(tMs >= n.onsetMs && tMs < n.onsetMs + n.durMs)) continue;
+        if (!inRange(kbd, n.pitchMidi)) continue;
+        const ends = rayEndpoints(layout, kbd, n.pitchMidi, t01);
+        if (!ends) continue;
+        if (!Number.isFinite(ends.staff.x) || !Number.isFinite(ends.keyboard.x)) continue;
+        const alpha = highlightIntensity(
+          { x: 0, y: 0, w: 0, h: 0, inMs: n.onsetMs, outMs: n.onsetMs + n.durMs, fadeMs },
+          tMs
+        );
+        if (alpha <= 0) continue;
+        const grow = Math.min(1, fadeMs > 0 ? (tMs - n.onsetMs) / fadeMs : 1);
+        c.save();
+        c.globalAlpha = alpha;
+        c.strokeStyle = accent;
+        c.lineWidth = width;
+        c.beginPath();
+        const steps = Math.max(2, segments);
+        for (let i = 0; i <= steps; i++) {
+          const u = i / steps * Math.max(0, grow);
+          const p = rayPointAt(ends, u);
+          if (i === 0) c.moveTo(p.x, p.y);
+          else c.lineTo(p.x, p.y);
+        }
+        c.stroke();
+        const head = rayPointAt(ends, Math.max(0, grow));
+        c.fillStyle = accent;
+        c.beginPath();
+        c.arc(ends.staff.x, ends.staff.y, width * 1.1, 0, Math.PI * 2);
+        c.fill();
+        c.beginPath();
+        c.arc(head.x, head.y, width * 1.1, 0, Math.PI * 2);
+        c.fill();
+        c.restore();
+      }
+    }
+  };
+}
+var staffKeyboardRayFactory = {
+  key: "staff-keyboard-ray",
+  create: staffKeyboardRayLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["staff-keyboard-ray: props must be an object"];
+    const p = props;
+    if (p.notationKey != null && typeof p.notationKey !== "string")
+      errs.push("staff-keyboard-ray.notationKey must be a string");
+    if (p.keyboardKey != null && typeof p.keyboardKey !== "string")
+      errs.push("staff-keyboard-ray.keyboardKey must be a string");
+    if (p.fadeMs != null && (typeof p.fadeMs !== "number" || p.fadeMs < 0))
+      errs.push("staff-keyboard-ray.fadeMs must be a non-negative number");
+    if (p.width != null && (typeof p.width !== "number" || p.width <= 0))
+      errs.push("staff-keyboard-ray.width must be a positive number");
+    if (p.color != null && typeof p.color !== "string")
+      errs.push("staff-keyboard-ray.color must be a string");
+    if (p.segments != null && (typeof p.segments !== "number" || p.segments < 2))
+      errs.push("staff-keyboard-ray.segments must be a number \u2265 2");
+    return errs;
+  }
+};
+// src/scene/countingGrid.ts
+var SUB4 = ["", "e", "&", "a"];
+function msPerBeat(bpm, beatUnit) {
+  return 6e4 / bpm * (4 / beatUnit);
+}
+function beatGrid(opts) {
+  const beatsPerBar = opts.beatsPerBar ?? 4;
+  const beatUnit = opts.beatUnit ?? 4;
+  const subdiv = opts.subdiv ?? 1;
+  const start = opts.startMs ?? 0;
+  const mpb = msPerBeat(opts.bpm, beatUnit);
+  const subMs = mpb / subdiv;
+  const ticks = [];
+  let beatIndex = 0;
+  for (let t = start; t <= start + opts.durationMs + 1e-6; t += mpb) {
+    const beatInBar = beatIndex % beatsPerBar + 1;
+    for (let s = 0; s < subdiv; s++) {
+      const tMs = t + s * subMs;
+      ticks.push({
+        tMs,
+        index: beatIndex,
+        beatInBar,
+        sub: s,
+        syllable: s === 0 ? String(beatInBar) : SUB4[s * (4 / subdiv) | 0] || "\xB7",
+        downbeat: beatInBar === 1 && s === 0
+      });
+    }
+    beatIndex++;
+  }
+  return ticks;
+}
+function bpmOf(tempoMap, fallback = 100) {
+  return tempoMap?.segments?.[0]?.bpm ?? fallback;
+}
+function beatPhase(bpm, beatUnit, tMs, startMs = 0) {
+  const mpb = msPerBeat(bpm, beatUnit);
+  const rel = tMs - startMs;
+  if (rel < 0) return 0;
+  const p = rel % mpb / mpb;
+  return p < 0 ? p + 1 : p;
+}
+function ballArc(phase01) {
+  const p = phase01 < 0 ? 0 : phase01 > 1 ? 1 : phase01;
+  return 4 * p * (1 - p);
+}
+function ballX(ticks, tMs, xOf) {
+  if (!ticks.length) return 0;
+  const beats = ticks.filter((t) => t.sub === 0);
+  if (tMs <= beats[0].tMs) return xOf(beats[0]);
+  for (let i = 0; i < beats.length - 1; i++) {
+    const a = beats[i];
+    const b = beats[i + 1];
+    if (tMs >= a.tMs && tMs < b.tMs) {
+      const f = (tMs - a.tMs) / (b.tMs - a.tMs);
+      return xOf(a) + (xOf(b) - xOf(a)) * f;
+    }
+  }
+  return xOf(beats[beats.length - 1]);
+}
+function parseTimeSig(ts) {
+  if (!ts) return [4, 4];
+  const m = /^(\d+)\s*\/\s*(\d+)$/.exec(ts.trim());
+  if (!m) return [4, 4];
+  return [parseInt(m[1], 10), parseInt(m[2], 10)];
+}
+// src/scene/layers/countingTrack.ts
+var DEFAULT_BOUNCE = 110;
+var DEFAULT_SIZE = 34;
+var DEFAULT_BALL = 22;
+function countingTrackLayer() {
+  let subdiv = 1;
+  let bpm = 100;
+  let beatUnit = 4;
+  let beatsPerBar = 4;
+  let trackYProp;
+  let bounce = DEFAULT_BOUNCE;
+  let size = DEFAULT_SIZE;
+  let ballRadius = DEFAULT_BALL;
+  let startMs = 0;
+  let legend = [];
+  let left = 0;
+  let width = 0;
+  function xOfTick(t) {
+    const idx = (t.beatInBar - 1) * subdiv + t.sub;
+    const slots = beatsPerBar * subdiv;
+    return left + (idx + 0.5) / slots * width;
+  }
+  return {
+    key: "counting-track",
+    init(ctx, props) {
+      subdiv = props.subdiv ?? 1;
+      const [num, den] = parseTimeSig(props.timeSig ?? ctx.score?.timeSig);
+      beatsPerBar = num;
+      beatUnit = den;
+      bpm = props.bpm ?? bpmOf(ctx.score?.tempoMap);
+      trackYProp = props.trackY;
+      bounce = props.bounce ?? DEFAULT_BOUNCE;
+      size = props.size ?? DEFAULT_SIZE;
+      ballRadius = props.ballRadius ?? DEFAULT_BALL;
+      startMs = props.startMs ?? 0;
+      const sb = ctx.safeBox;
+      left = sb.left;
+      width = sb.w;
+      legend = [];
+      for (let b = 0; b < beatsPerBar; b++) {
+        for (let s = 0; s < subdiv; s++) {
+          legend.push({
+            tMs: 0,
+            index: b,
+            beatInBar: b + 1,
+            sub: s,
+            syllable: s === 0 ? String(b + 1) : ["", "e", "&", "a"][s * (4 / subdiv) | 0] || "\xB7",
+            downbeat: b === 0 && s === 0
+          });
+        }
+      }
+    },
+    draw(ctx, tMs) {
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const trackY = trackYProp ?? sb.bottom - 120;
+      c.save();
+      c.strokeStyle = ctx.theme.sepia;
+      c.lineWidth = 2;
+      c.globalAlpha = 0.5;
+      c.beginPath();
+      c.moveTo(left, trackY);
+      c.lineTo(left + width, trackY);
+      c.stroke();
+      c.globalAlpha = 1;
+      const phase = beatPhase(bpm, beatUnit, tMs, startMs);
+      const mpb = 6e4 / bpm * (4 / beatUnit);
+      const rel = Math.max(0, tMs - startMs);
+      const beatIdx = Math.floor(rel / mpb);
+      const activeBeatInBar = beatIdx % beatsPerBar;
+      const activeSub = Math.floor(phase * subdiv) % subdiv;
+      const activeSlot = activeBeatInBar * subdiv + activeSub;
+      c.textAlign = "center";
+      c.textBaseline = "middle";
+      for (const t of legend) {
+        const x = xOfTick(t);
+        const slot = (t.beatInBar - 1) * subdiv + t.sub;
+        const active = slot === activeSlot;
+        c.font = `${t.sub === 0 ? "700" : "400"} ${t.sub === 0 ? size : size * 0.8}px ${ctx.theme.fontBody}`;
+        c.fillStyle = active ? ctx.theme.accent : ctx.theme.ink;
+        c.globalAlpha = active ? 1 : t.sub === 0 ? 0.85 : 0.55;
+        c.fillText(t.syllable, x, trackY + size * 0.95);
+        c.globalAlpha = active ? 0.9 : 0.4;
+        c.fillRect(x - 1, trackY - (t.sub === 0 ? 10 : 6), 2, t.sub === 0 ? 10 : 6);
+      }
+      c.globalAlpha = 1;
+      const beatPosInBar = beatIdx % beatsPerBar + phase;
+      const ballSlot = beatPosInBar * subdiv;
+      const slots = beatsPerBar * subdiv;
+      const bx = left + Math.min(slots, ballSlot + 0.5) / slots * width;
+      const arc = ballArc(phase);
+      const by = trackY - ballRadius - arc * bounce;
+      c.fillStyle = ctx.theme.accent;
+      c.beginPath();
+      c.arc(bx, by, ballRadius, 0, Math.PI * 2);
+      c.fill();
+      c.globalAlpha = 0.2 * (1 - arc);
+      c.fillStyle = ctx.theme.ink;
+      c.beginPath();
+      c.arc(bx, trackY, ballRadius * 0.8, 0, Math.PI * 2);
+      c.fill();
+      c.restore();
+    }
+  };
+}
+var countingTrackFactory = {
+  key: "counting-track",
+  create: countingTrackLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["counting-track: props must be an object"];
+    const p = props;
+    if (p.subdiv != null && p.subdiv !== 1 && p.subdiv !== 2 && p.subdiv !== 4)
+      errs.push("counting-track.subdiv must be 1 | 2 | 4");
+    if (p.timeSig != null && (typeof p.timeSig !== "string" || !/^\d+\s*\/\s*\d+$/.test(p.timeSig)))
+      errs.push('counting-track.timeSig must be "n/d"');
+    if (p.bpm != null && (typeof p.bpm !== "number" || p.bpm <= 0))
+      errs.push("counting-track.bpm must be a positive number");
+    if (p.trackY != null && typeof p.trackY !== "number")
+      errs.push("counting-track.trackY must be a number");
+    if (p.bounce != null && (typeof p.bounce !== "number" || p.bounce < 0))
+      errs.push("counting-track.bounce must be a non-negative number");
+    if (p.size != null && (typeof p.size !== "number" || p.size <= 0))
+      errs.push("counting-track.size must be a positive number");
+    if (p.ballRadius != null && (typeof p.ballRadius !== "number" || p.ballRadius <= 0))
+      errs.push("counting-track.ballRadius must be a positive number");
+    if (p.startMs != null && typeof p.startMs !== "number")
+      errs.push("counting-track.startMs must be a number");
+    return errs;
+  }
+};
+// src/scene/degreeLabels.ts
+var LETTERS = ["C", "D", "E", "F", "G", "A", "B"];
+var LETTER_PC = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+var MAJOR_OFFSETS = [0, 2, 4, 5, 7, 9, 11];
+var DIATONIC_SOLFEGE = ["do", "re", "mi", "fa", "sol", "la", "ti"];
+var RAISED_SOLFEGE = { 1: "di", 2: "ri", 4: "fi", 5: "si", 6: "li" };
+var LOWERED_SOLFEGE = { 2: "ra", 3: "me", 5: "se", 6: "le", 7: "te" };
+function parseKey(key) {
+  if (!key) return { tonicLetter: "C", tonicPc: 0, minor: false };
+  const m = /^([A-Ga-g])([#b]*)\s*(major|minor|maj|min|m)?/.exec(key.trim());
+  if (!m) return { tonicLetter: "C", tonicPc: 0, minor: false };
+  const letter = m[1].toUpperCase();
+  let pc = LETTER_PC[letter] ?? 0;
+  for (const ch of m[2]) pc += ch === "#" ? 1 : -1;
+  const modeTok = (m[3] ?? "").toLowerCase();
+  const minor = modeTok === "minor" || modeTok === "min" || modeTok === "m";
+  return { tonicLetter: letter, tonicPc: (pc % 12 + 12) % 12, minor };
+}
+function degreeLabel(step, alter, pitchMidi, key, mode) {
+  const { tonicLetter } = parseKey(key);
+  const noteLetterIdx = LETTERS.indexOf(step.toUpperCase());
+  const tonicLetterIdx = LETTERS.indexOf(tonicLetter);
+  const degIdx = noteLetterIdx < 0 || tonicLetterIdx < 0 ? 0 : ((noteLetterIdx - tonicLetterIdx) % 7 + 7) % 7;
+  const degree = degIdx + 1;
+  const { tonicPc } = parseKey(key);
+  const diatonicPc = (tonicPc + MAJOR_OFFSETS[degIdx]) % 12;
+  const letterPc = LETTER_PC[step.toUpperCase()];
+  const actualPc = letterPc != null ? ((letterPc + alter) % 12 + 12) % 12 : (pitchMidi % 12 + 12) % 12;
+  let chrom = actualPc - diatonicPc;
+  if (chrom > 6) chrom -= 12;
+  if (chrom < -6) chrom += 12;
+  const text = mode === "solfege" ? solfegeText(degree, chrom) : degreeText(degree, chrom);
+  return { degree, alter: chrom, text };
+}
+function degreeText(degree, chrom) {
+  const acc = chrom > 0 ? "\u266F".repeat(chrom) : chrom < 0 ? "\u266D".repeat(-chrom) : "";
+  return `${acc}${degree}`;
+}
+function solfegeText(degree, chrom) {
+  if (chrom === 0) return DIATONIC_SOLFEGE[degree - 1] ?? "?";
+  if (chrom > 0) return RAISED_SOLFEGE[degree] ?? `${DIATONIC_SOLFEGE[degree - 1]}\u266F`;
+  return LOWERED_SOLFEGE[degree] ?? `${DIATONIC_SOLFEGE[degree - 1]}\u266D`;
+}
+// src/scene/layers/degreeLabels.ts
+var DEFAULT_SIZE2 = 30;
+function degreeLabelsLayer() {
+  let mode = "degree";
+  let keyOverride;
+  let size = DEFAULT_SIZE2;
+  let fadeMs = 120;
+  let color;
+  return {
+    key: "degree-labels",
+    init(_ctx, props) {
+      mode = props.mode ?? "degree";
+      keyOverride = props.key;
+      size = props.size ?? DEFAULT_SIZE2;
+      fadeMs = props.fadeMs ?? 120;
+      color = props.color;
+    },
+    draw(ctx, tMs) {
+      const layout = getKeyboardLayout(ctx);
+      if (!layout) return;
+      const c = ctx.ctx2d;
+      const key = keyOverride ?? ctx.score?.key;
+      const ink = color ?? ctx.theme.ink;
+      for (const n of ctx.score?.notes ?? []) {
+        if (!inRange(layout, n.pitchMidi)) continue;
+        const a = highlightIntensity(
+          { x: 0, y: 0, w: 0, h: 0, inMs: n.onsetMs, outMs: n.onsetMs + n.durMs, fadeMs },
+          tMs
+        );
+        if (a <= 0) continue;
+        const label = degreeLabel(n.step, n.alter, n.pitchMidi, key, mode);
+        const cx = keyCenterX(layout, n.pitchMidi);
+        const cy = layout.top - (isBlackKey(n.pitchMidi) ? size * 1.6 : size * 0.6);
+        c.save();
+        c.globalAlpha = a;
+        c.textAlign = "center";
+        c.textBaseline = "middle";
+        c.font = `700 ${size}px ${ctx.theme.fontBody}`;
+        const w = c.measureText(label.text).width;
+        const padX = size * 0.35;
+        const padY = size * 0.22;
+        c.fillStyle = ctx.theme.paper;
+        c.globalAlpha = a * 0.92;
+        roundRect(c, cx - w / 2 - padX, cy - size / 2 - padY, w + 2 * padX, size + 2 * padY, size * 0.3);
+        c.fill();
+        c.globalAlpha = a;
+        c.fillStyle = ink;
+        c.fillText(label.text, cx, cy);
+        c.restore();
+      }
+    }
+  };
+}
+function roundRect(c, x, y, w, h, r) {
+  if (typeof c.roundRect === "function") {
+    c.beginPath();
+    c.roundRect(x, y, w, h, r);
+    return;
+  }
+  c.beginPath();
+  c.moveTo(x + r, y);
+  c.lineTo(x + w - r, y);
+  c.lineTo(x + w, y + h);
+  c.lineTo(x, y + h);
+  c.closePath();
+}
+var degreeLabelsFactory = {
+  key: "degree-labels",
+  create: degreeLabelsLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["degree-labels: props must be an object"];
+    const p = props;
+    if (p.mode != null && p.mode !== "degree" && p.mode !== "solfege")
+      errs.push('degree-labels.mode must be "degree" | "solfege"');
+    if (p.key != null && typeof p.key !== "string")
+      errs.push("degree-labels.key must be a string");
+    if (p.size != null && (typeof p.size !== "number" || p.size <= 0))
+      errs.push("degree-labels.size must be a positive number");
+    if (p.fadeMs != null && (typeof p.fadeMs !== "number" || p.fadeMs < 0))
+      errs.push("degree-labels.fadeMs must be a non-negative number");
+    if (p.color != null && typeof p.color !== "string")
+      errs.push("degree-labels.color must be a string");
+    return errs;
+  }
+};
+// src/scene/harmonyTrack.ts
+var DEFAULT_FUNCTION_COLORS = {
+  T: "#3a7d44",
+  // grounded green
+  S: "#3a6ea5",
+  // calm blue
+  D: "#c2502f",
+  // tense orange-red
+  other: "#7a7a7a"
+};
+function activeChord(track, tMs) {
+  for (const s of track) {
+    if (tMs >= s.startMs && tMs < s.endMs) return s;
+  }
+  return null;
+}
+function functionColor(fn, colors) {
+  return colors[fn] ?? colors.other;
+}
+function validateChordTrack(track) {
+  if (!Array.isArray(track)) return ["chordTrack must be an array of chord spans"];
+  const errs = [];
+  track.forEach((raw, i) => {
+    const s = raw;
+    if (typeof s?.startMs !== "number" || typeof s?.endMs !== "number")
+      errs.push(`chordTrack[${i}] needs numeric startMs/endMs`);
+    else if (s.endMs <= s.startMs) errs.push(`chordTrack[${i}].endMs must be > startMs`);
+    if (s?.fn !== "T" && s?.fn !== "S" && s?.fn !== "D" && s?.fn !== "other")
+      errs.push(`chordTrack[${i}].fn must be "T"|"S"|"D"|"other"`);
+    if (s?.label != null && typeof s.label !== "string")
+      errs.push(`chordTrack[${i}].label must be a string`);
+  });
+  return errs;
+}
+// src/scene/layers/functionalHarmony.ts
+var DEFAULT_BAND_H = 64;
+var DEFAULT_FADE2 = 200;
+function functionalHarmonyLayer() {
+  let track = [];
+  let modes = ["band"];
+  let colors = DEFAULT_FUNCTION_COLORS;
+  let bandHeight = DEFAULT_BAND_H;
+  let bandTopProp;
+  let fadeMs = DEFAULT_FADE2;
+  let washAlpha = 0.12;
+  return {
+    key: "functional-harmony",
+    init(_ctx, props) {
+      track = props.chordTrack ?? [];
+      modes = props.modes ?? ["band"];
+      colors = props.colors ?? DEFAULT_FUNCTION_COLORS;
+      bandHeight = props.bandHeight ?? DEFAULT_BAND_H;
+      bandTopProp = props.bandTop;
+      fadeMs = props.fadeMs ?? DEFAULT_FADE2;
+      washAlpha = props.washAlpha ?? 0.12;
+    },
+    draw(ctx, tMs) {
+      const span = activeChord(track, tMs);
+      if (!span) return;
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const col = functionColor(span.fn, colors);
+      const a = highlightIntensity(
+        { x: 0, y: 0, w: 0, h: 0, inMs: span.startMs, outMs: span.endMs, fadeMs },
+        tMs
+      );
+      if (a <= 0) return;
+      if (modes.includes("wash")) {
+        c.save();
+        c.globalAlpha = a * washAlpha;
+        c.fillStyle = col;
+        c.fillRect(0, 0, ctx.W, ctx.H);
+        c.restore();
+      }
+      if (modes.includes("keys")) {
+        const layout = getKeyboardLayout(ctx);
+        if (layout) {
+          c.save();
+          for (const n of ctx.score?.notes ?? []) {
+            if (!(tMs >= n.onsetMs && tMs < n.onsetMs + n.durMs)) continue;
+            if (!inRange(layout, n.pitchMidi)) continue;
+            const r = keyRect(layout, n.pitchMidi);
+            c.globalAlpha = a * 0.8;
+            c.fillStyle = col;
+            c.fillRect(r.x, r.y, r.w, r.h);
+          }
+          c.restore();
+        }
+      }
+      if (modes.includes("band")) {
+        const top = bandTopProp ?? sb.top;
+        c.save();
+        c.globalAlpha = a * 0.85;
+        c.fillStyle = col;
+        c.fillRect(sb.left, top, sb.w, bandHeight);
+        if (span.label) {
+          c.globalAlpha = a;
+          c.fillStyle = "#ffffff";
+          c.textAlign = "center";
+          c.textBaseline = "middle";
+          c.font = `700 ${Math.round(bandHeight * 0.5)}px ${ctx.theme.fontDisplay}`;
+          c.fillText(span.label, sb.left + sb.w / 2, top + bandHeight / 2);
+        }
+        c.restore();
+      }
+    }
+  };
+}
+var functionalHarmonyFactory = {
+  key: "functional-harmony",
+  create: functionalHarmonyLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["functional-harmony: props must be an object"];
+    const p = props;
+    errs.push(...validateChordTrack(p.chordTrack).map((e) => `functional-harmony.${e}`));
+    if (p.modes != null) {
+      if (!Array.isArray(p.modes)) errs.push("functional-harmony.modes must be an array");
+      else for (const m of p.modes)
+        if (m !== "band" && m !== "keys" && m !== "wash")
+          errs.push('functional-harmony.modes items must be "band"|"keys"|"wash"');
+    }
+    if (p.bandHeight != null && (typeof p.bandHeight !== "number" || p.bandHeight <= 0))
+      errs.push("functional-harmony.bandHeight must be a positive number");
+    if (p.bandTop != null && typeof p.bandTop !== "number")
+      errs.push("functional-harmony.bandTop must be a number");
+    if (p.fadeMs != null && (typeof p.fadeMs !== "number" || p.fadeMs < 0))
+      errs.push("functional-harmony.fadeMs must be a non-negative number");
+    if (p.washAlpha != null && (typeof p.washAlpha !== "number" || p.washAlpha < 0 || p.washAlpha > 1))
+      errs.push("functional-harmony.washAlpha must be in [0,1]");
+    return errs;
+  }
+};
+// src/scene/quizCard.ts
+function quizPhase(quiz, tMs) {
+  const ask = quiz.askMs ?? 0;
+  if (tMs < ask) return "before";
+  if (tMs < quiz.revealMs) return "question";
+  if (tMs < quiz.endMs) return "reveal";
+  return "after";
+}
+function countdownRemaining(quiz, tMs) {
+  const ask = quiz.askMs ?? 0;
+  const span = quiz.revealMs - ask;
+  if (span <= 0) return 0;
+  const elapsed = (tMs - ask) / span;
+  return elapsed <= 0 ? 1 : elapsed >= 1 ? 0 : 1 - elapsed;
+}
+function countdownSeconds(quiz, tMs) {
+  const ask = quiz.askMs ?? 0;
+  const remMs = Math.max(0, quiz.revealMs - Math.max(ask, tMs));
+  return Math.ceil(remMs / 1e3);
+}
+function revealProgress(quiz, tMs, windowMs = 350) {
+  if (tMs < quiz.revealMs) return 0;
+  if (windowMs <= 0) return 1;
+  const p = (tMs - quiz.revealMs) / windowMs;
+  return p >= 1 ? 1 : p;
+}
+function validateQuiz(quiz) {
+  if (quiz == null || typeof quiz !== "object") return ["quiz must be an object"];
+  const q = quiz;
+  const errs = [];
+  if (typeof q.question !== "string" || q.question.length === 0)
+    errs.push("quiz.question must be a non-empty string");
+  if (!Array.isArray(q.options) || q.options.length < 2 || q.options.length > 4)
+    errs.push("quiz.options must be an array of 2\u20134 options");
+  else {
+    q.options.forEach((o, i) => {
+      const opt = o;
+      if (opt == null || typeof opt.text !== "string" || opt.text.length === 0)
+        errs.push(`quiz.options[${i}].text must be a non-empty string`);
+    });
+  }
+  const nOpts = Array.isArray(q.options) ? q.options.length : 0;
+  if (typeof q.correctIndex !== "number" || !Number.isInteger(q.correctIndex) || q.correctIndex < 0 || nOpts > 0 && q.correctIndex >= nOpts)
+    errs.push("quiz.correctIndex must be an integer index into options");
+  if (typeof q.revealMs !== "number") errs.push("quiz.revealMs must be a number (ms)");
+  if (typeof q.endMs !== "number") errs.push("quiz.endMs must be a number (ms)");
+  if (typeof q.revealMs === "number" && typeof q.endMs === "number" && q.endMs <= q.revealMs)
+    errs.push("quiz.endMs must be > revealMs");
+  if (q.askMs != null && typeof q.askMs !== "number") errs.push("quiz.askMs must be a number (ms)");
+  if (typeof q.askMs === "number" && typeof q.revealMs === "number" && q.revealMs <= q.askMs)
+    errs.push("quiz.revealMs must be > askMs");
+  if (q.poll != null) {
+    if (!Array.isArray(q.poll) || nOpts > 0 && q.poll.length !== nOpts)
+      errs.push("quiz.poll, if given, must be an array matching options length");
+    else if (!q.poll.every((p) => typeof p === "number" && p >= 0 && p <= 100))
+      errs.push("quiz.poll entries must be numbers in [0,100]");
+  }
+  return errs;
+}
+// src/scene/layers/mcqCard.ts
+var CARD_RADIUS = 28;
+function roundRect2(c, x, y, w, h, r) {
+  const rr = Math.min(r, w / 2, h / 2);
+  const anyC = c;
+  if (typeof anyC.roundRect === "function") {
+    c.beginPath();
+    anyC.roundRect(x, y, w, h, rr);
+    return;
+  }
+  c.beginPath();
+  c.moveTo(x + rr, y);
+  c.lineTo(x + w - rr, y);
+  c.lineTo(x + w, y + rr);
+  c.lineTo(x + w, y + h - rr);
+  c.lineTo(x + w - rr, y + h);
+  c.lineTo(x + rr, y + h);
+  c.lineTo(x, y + h - rr);
+  c.lineTo(x, y + rr);
+  c.closePath();
+}
+function mcqCardLayer() {
+  let quiz = { question: "", options: [], correctIndex: 0, revealMs: 0, endMs: 0 };
+  let correctColor;
+  let showPoll = true;
+  return {
+    key: "mcq-card",
+    init(_ctx, props) {
+      quiz = props.quiz;
+      correctColor = props.correctColor;
+      showPoll = props.showPoll ?? true;
+    },
+    draw(ctx, tMs) {
+      const phase = quizPhase(quiz, tMs);
+      if (phase === "before" || phase === "after") return;
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const accent = correctColor ?? ctx.theme.accent;
+      const revealed = phase === "reveal";
+      const revP = easeOut(revealProgress(quiz, tMs));
+      const cardW = sb.w;
+      const n = quiz.options.length;
+      const optH = Math.min(120, sb.h * 0.5 / Math.max(1, n));
+      const gap = optH * 0.22;
+      const headH = optH * 1.3;
+      const cardH = headH + n * (optH + gap);
+      const cardX = sb.left;
+      const cardY = sb.top + (sb.h - cardH) / 2;
+      c.save();
+      c.fillStyle = ctx.theme.ink;
+      c.textAlign = "center";
+      c.textBaseline = "middle";
+      c.font = `700 ${Math.round(headH * 0.42)}px ${ctx.theme.fontDisplay}`;
+      c.fillText(quiz.question, cardX + cardW / 2, cardY + headH * 0.45);
+      if (!revealed) {
+        const rem = countdownRemaining(quiz, tMs);
+        const secs = countdownSeconds(quiz, tMs);
+        const cr = headH * 0.34;
+        const ccx = cardX + cardW - cr - 8;
+        const ccy = cardY + headH * 0.45;
+        c.lineWidth = Math.max(3, cr * 0.16);
+        c.strokeStyle = ctx.theme.sepia;
+        c.globalAlpha = 0.3;
+        c.beginPath();
+        c.arc(ccx, ccy, cr, 0, Math.PI * 2);
+        c.stroke();
+        c.globalAlpha = 1;
+        c.strokeStyle = accent;
+        c.beginPath();
+        c.arc(ccx, ccy, cr, -Math.PI / 2, -Math.PI / 2 + rem * Math.PI * 2);
+        c.stroke();
+        c.fillStyle = ctx.theme.ink;
+        c.font = `700 ${Math.round(cr * 0.9)}px ${ctx.theme.fontBody}`;
+        c.fillText(String(secs), ccx, ccy);
+      }
+      let oy = cardY + headH;
+      quiz.options.forEach((opt, i) => {
+        const isCorrect = i === quiz.correctIndex;
+        const x = cardX;
+        const y = oy;
+        let bg = ctx.theme.paper;
+        let alpha = 1;
+        if (revealed) {
+          if (isCorrect) bg = accent;
+          else alpha = 1 - 0.55 * revP;
+        }
+        c.globalAlpha = alpha;
+        c.fillStyle = bg;
+        roundRect2(c, x, y, cardW, optH, CARD_RADIUS);
+        c.fill();
+        c.globalAlpha = alpha;
+        c.lineWidth = isCorrect && revealed ? 4 : 2;
+        c.strokeStyle = isCorrect && revealed ? accent : ctx.theme.sepia;
+        roundRect2(c, x, y, cardW, optH, CARD_RADIUS);
+        c.stroke();
+        if (showPoll && quiz.poll && quiz.poll[i] != null) {
+          const pct = quiz.poll[i] / 100;
+          c.globalAlpha = alpha * 0.25;
+          c.fillStyle = isCorrect ? accent : ctx.theme.sepia;
+          roundRect2(c, x, y, cardW * pct * revP, optH, CARD_RADIUS);
+          c.fill();
+        }
+        c.globalAlpha = alpha;
+        const label = String.fromCharCode(65 + i);
+        c.fillStyle = isCorrect && revealed ? ctx.theme.paper : ctx.theme.ink;
+        c.textAlign = "left";
+        c.font = `700 ${Math.round(optH * 0.34)}px ${ctx.theme.fontBody}`;
+        c.fillText(`${label}.`, x + optH * 0.4, y + optH / 2);
+        c.fillText(opt.text, x + optH * 1.2, y + optH / 2);
+        if (showPoll && quiz.poll && quiz.poll[i] != null && revealed) {
+          c.textAlign = "right";
+          c.font = `600 ${Math.round(optH * 0.3)}px ${ctx.theme.fontBody}`;
+          c.fillText(`${Math.round(quiz.poll[i])}%`, x + cardW - optH * 0.4, y + optH / 2);
+        }
+        oy += optH + gap;
+      });
+      c.restore();
+    }
+  };
+}
+var mcqCardFactory = {
+  key: "mcq-card",
+  create: mcqCardLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["mcq-card: props must be an object"];
+    const p = props;
+    const errs = [];
+    errs.push(...validateQuiz(p.quiz).map((e) => `mcq-card.${e}`));
+    if (p.correctColor != null && typeof p.correctColor !== "string")
+      errs.push("mcq-card.correctColor must be a string");
+    if (p.showPoll != null && typeof p.showPoll !== "boolean")
+      errs.push("mcq-card.showPoll must be a boolean");
+    return errs;
+  }
+};
+// src/scene/circleOfFifths.ts
+var FIFTHS_MAJOR = ["C", "G", "D", "A", "E", "B", "F\u266F", "D\u266D", "A\u266D", "E\u266D", "B\u266D", "F"];
+var FIFTHS_MINOR = ["a", "e", "b", "f\u266F", "c\u266F", "g\u266F", "d\u266F", "b\u266D", "f", "c", "g", "d"];
+function slotPc(i) {
+  return 7 * i % 12;
+}
+function pcToSlot(pc) {
+  const p = (pc % 12 + 12) % 12;
+  for (let i = 0; i < 12; i++) if (slotPc(i) === p) return i;
+  return 0;
+}
+function keySlot(key) {
+  return pcToSlot(parseKey(key).tonicPc);
+}
+function slotAngle(i) {
+  return i / 12 * Math.PI * 2;
+}
+function slotPoint(cx, cy, r, i) {
+  const a = slotAngle(i) - Math.PI / 2;
+  return { x: cx + r * Math.cos(a), y: cy + r * Math.sin(a) };
+}
+function animatedSlot(fromSlot, toSlot, t01) {
+  let delta = toSlot - fromSlot;
+  if (delta > 6) delta -= 12;
+  if (delta < -6) delta += 12;
+  const t = t01 < 0 ? 0 : t01 > 1 ? 1 : t01;
+  const s = fromSlot + delta * t;
+  return (s % 12 + 12) % 12;
+}
+function fracSlotPoint(cx, cy, r, frac) {
+  const a = frac / 12 * Math.PI * 2 - Math.PI / 2;
+  return { x: cx + r * Math.cos(a), y: cy + r * Math.sin(a) };
+}
+// src/scene/layers/circleOfFifths.ts
+function circleOfFifthsLayer() {
+  let keyOverride;
+  let toKey;
+  let fromMs = 0;
+  let toMs = 0;
+  let centerProp;
+  let radiusProp;
+  let showMinor = true;
+  let color;
+  return {
+    key: "circle-of-fifths",
+    init(_ctx, props) {
+      keyOverride = props.key;
+      toKey = props.toKey;
+      fromMs = props.fromMs ?? 0;
+      toMs = props.toMs ?? 0;
+      centerProp = props.center;
+      radiusProp = props.radius;
+      showMinor = props.showMinor ?? true;
+      color = props.color;
+    },
+    draw(ctx, tMs) {
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const cx = centerProp?.[0] ?? sb.left + sb.w / 2;
+      const cy = centerProp?.[1] ?? sb.top + sb.h / 2;
+      const R = radiusProp ?? Math.min(sb.w, sb.h) * 0.32;
+      const accent = color ?? ctx.theme.accent;
+      const rMajor = R;
+      const rMinor = R * 0.66;
+      const fromSlot = keySlot(keyOverride ?? ctx.score?.key);
+      let hiSlot = fromSlot;
+      if (toKey) {
+        const t01 = easeInOut(invLerp(fromMs, toMs, tMs));
+        hiSlot = animatedSlot(fromSlot, keySlot(toKey), t01);
+      }
+      c.save();
+      c.lineWidth = 2;
+      c.strokeStyle = ctx.theme.sepia;
+      c.globalAlpha = 0.5;
+      c.beginPath();
+      c.arc(cx, cy, rMajor + R * 0.16, 0, Math.PI * 2);
+      c.stroke();
+      if (showMinor) {
+        c.beginPath();
+        c.arc(cx, cy, rMinor - R * 0.16, 0, Math.PI * 2);
+        c.stroke();
+      }
+      c.globalAlpha = 1;
+      const hp = fracSlotPoint(cx, cy, rMajor, hiSlot);
+      c.fillStyle = accent;
+      c.globalAlpha = 0.9;
+      c.beginPath();
+      c.arc(hp.x, hp.y, R * 0.2, 0, Math.PI * 2);
+      c.fill();
+      c.globalAlpha = 1;
+      c.textAlign = "center";
+      c.textBaseline = "middle";
+      for (let i = 0; i < 12; i++) {
+        const isHi = Math.round(hiSlot) % 12 === i;
+        const pm = slotPoint(cx, cy, rMajor, i);
+        c.fillStyle = isHi ? ctx.theme.paper : ctx.theme.ink;
+        c.font = `700 ${Math.round(R * 0.16)}px ${ctx.theme.fontBody}`;
+        c.fillText(FIFTHS_MAJOR[i], pm.x, pm.y);
+        if (showMinor) {
+          const pn = slotPoint(cx, cy, rMinor, i);
+          c.fillStyle = ctx.theme.sepia;
+          c.globalAlpha = isHi ? 1 : 0.8;
+          c.font = `400 ${Math.round(R * 0.12)}px ${ctx.theme.fontBody}`;
+          c.fillText(FIFTHS_MINOR[i], pn.x, pn.y);
+          c.globalAlpha = 1;
+        }
+      }
+      c.restore();
+    }
+  };
+}
+var circleOfFifthsFactory = {
+  key: "circle-of-fifths",
+  create: circleOfFifthsLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["circle-of-fifths: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.key != null && typeof p.key !== "string") errs.push("circle-of-fifths.key must be a string");
+    if (p.toKey != null) {
+      if (typeof p.toKey !== "string") errs.push("circle-of-fifths.toKey must be a string");
+      if (typeof p.fromMs !== "number" || typeof p.toMs !== "number")
+        errs.push("circle-of-fifths.toKey requires numeric fromMs and toMs");
+      else if (p.toMs <= p.fromMs) errs.push("circle-of-fifths.toMs must be > fromMs");
+    }
+    if (p.center != null && (!Array.isArray(p.center) || p.center.length !== 2 || !p.center.every((n) => typeof n === "number")))
+      errs.push("circle-of-fifths.center must be [x,y]");
+    if (p.radius != null && (typeof p.radius !== "number" || p.radius <= 0))
+      errs.push("circle-of-fifths.radius must be a positive number");
+    if (p.showMinor != null && typeof p.showMinor !== "boolean")
+      errs.push("circle-of-fifths.showMinor must be a boolean");
+    if (p.color != null && typeof p.color !== "string")
+      errs.push("circle-of-fifths.color must be a string");
+    return errs;
+  }
+};
+// src/scene/pitchContour.ts
+function contourPoints(notes) {
+  const byOnset = /* @__PURE__ */ new Map();
+  for (const n of notes) {
+    const cur = byOnset.get(n.onsetMs);
+    if (cur == null || n.pitchMidi > cur) byOnset.set(n.onsetMs, n.pitchMidi);
+  }
+  return [...byOnset.entries()].map(([tMs, pitchMidi]) => ({ tMs, pitchMidi })).sort((a, b) => a.tMs - b.tMs);
+}
+function pitchRange(points) {
+  if (!points.length) return { min: 60, max: 72 };
+  let min = Infinity;
+  let max = -Infinity;
+  for (const p of points) {
+    if (p.pitchMidi < min) min = p.pitchMidi;
+    if (p.pitchMidi > max) max = p.pitchMidi;
+  }
+  if (max - min < 2) {
+    min -= 1;
+    max += 1;
+  }
+  return { min: min - 1, max: max + 1 };
+}
+function projectPoint(plot, tMs, pitchMidi) {
+  const tx = plot.durationMs > 0 ? clamp(tMs / plot.durationMs, 0, 1) : 0;
+  const py = plot.maxPitch > plot.minPitch ? clamp((pitchMidi - plot.minPitch) / (plot.maxPitch - plot.minPitch), 0, 1) : 0.5;
+  return {
+    x: plot.left + tx * (plot.right - plot.left),
+    y: plot.bottom - py * (plot.bottom - plot.top)
+  };
+}
+function contourPolyline(points, plot) {
+  return points.map((p) => projectPoint(plot, p.tMs, p.pitchMidi));
+}
+function pitchAt(points, tMs) {
+  if (!points.length || tMs < points[0].tMs) return null;
+  let cur = points[0].pitchMidi;
+  for (const p of points) {
+    if (p.tMs <= tMs) cur = p.pitchMidi;
+    else break;
+  }
+  return cur;
+}
+function dotAt(points, plot, tMs) {
+  const pitch = pitchAt(points, tMs);
+  if (pitch == null) return null;
+  return projectPoint(plot, tMs, pitch);
+}
+// src/scene/layers/pitchContour.ts
+function pitchContourLayer() {
+  let topProp;
+  let heightProp;
+  let width = 5;
+  let color;
+  let dot = true;
+  let dotRadius = 14;
+  let points = [];
+  return {
+    key: "pitch-contour",
+    init(ctx, props) {
+      topProp = props.top;
+      heightProp = props.height;
+      width = props.width ?? 5;
+      color = props.color;
+      dot = props.dot ?? true;
+      dotRadius = props.dotRadius ?? 14;
+      points = contourPoints(ctx.score?.notes ?? []);
+    },
+    draw(ctx, tMs) {
+      if (points.length < 2) return;
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const accent = color ?? ctx.theme.accent;
+      const top = topProp ?? sb.top + sb.h * 0.15;
+      const height = heightProp ?? sb.h * 0.35;
+      const range = pitchRange(points);
+      const plot = {
+        left: sb.left,
+        right: sb.right,
+        top,
+        bottom: top + height,
+        minPitch: range.min,
+        maxPitch: range.max,
+        durationMs: ctx.score?.durationMs ?? points[points.length - 1].tMs
+      };
+      const poly = contourPolyline(points, plot);
+      const playX = projectPoint(plot, tMs, range.min).x;
+      c.save();
+      c.lineJoin = "round";
+      c.lineCap = "round";
+      c.globalAlpha = 0.22;
+      c.strokeStyle = ctx.theme.sepia;
+      c.lineWidth = width;
+      c.beginPath();
+      poly.forEach((p, i) => i === 0 ? c.moveTo(p.x, p.y) : c.lineTo(p.x, p.y));
+      c.stroke();
+      c.globalAlpha = 1;
+      c.strokeStyle = accent;
+      c.lineWidth = width;
+      c.beginPath();
+      let started = false;
+      for (let i = 0; i < poly.length; i++) {
+        const p = poly[i];
+        if (p.x <= playX) {
+          if (!started) {
+            c.moveTo(p.x, p.y);
+            started = true;
+          } else c.lineTo(p.x, p.y);
+        } else {
+          if (i > 0) {
+            const a = poly[i - 1];
+            const f = (playX - a.x) / (p.x - a.x || 1);
+            const y = a.y + (p.y - a.y) * f;
+            if (!started) {
+              c.moveTo(a.x, a.y);
+              started = true;
+            }
+            c.lineTo(playX, y);
+          }
+          break;
+        }
+      }
+      if (started) c.stroke();
+      if (dot) {
+        const d = dotAt(points, plot, tMs);
+        if (d && Number.isFinite(d.x) && Number.isFinite(d.y)) {
+          c.globalAlpha = 1;
+          c.fillStyle = accent;
+          c.beginPath();
+          c.arc(d.x, d.y, dotRadius, 0, Math.PI * 2);
+          c.fill();
+          c.globalAlpha = 0.3;
+          c.beginPath();
+          c.arc(d.x, d.y, dotRadius * 1.7, 0, Math.PI * 2);
+          c.fill();
+        }
+      }
+      c.restore();
+    }
+  };
+}
+var pitchContourFactory = {
+  key: "pitch-contour",
+  create: pitchContourLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["pitch-contour: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.top != null && typeof p.top !== "number") errs.push("pitch-contour.top must be a number");
+    if (p.height != null && (typeof p.height !== "number" || p.height <= 0))
+      errs.push("pitch-contour.height must be a positive number");
+    if (p.width != null && (typeof p.width !== "number" || p.width <= 0))
+      errs.push("pitch-contour.width must be a positive number");
+    if (p.color != null && typeof p.color !== "string") errs.push("pitch-contour.color must be a string");
+    if (p.dot != null && typeof p.dot !== "boolean") errs.push("pitch-contour.dot must be a boolean");
+    if (p.dotRadius != null && (typeof p.dotRadius !== "number" || p.dotRadius <= 0))
+      errs.push("pitch-contour.dotRadius must be a positive number");
+    return errs;
+  }
+};
+// src/scene/sectionMinimap.ts
+function progress01(durationMs, tMs) {
+  return durationMs > 0 ? clamp(tMs / durationMs, 0, 1) : 0;
+}
+function timeToX(left, width, durationMs, tMs) {
+  return left + progress01(durationMs, tMs) * width;
+}
+function activeSection(sections, tMs) {
+  for (const s of sections) if (tMs >= s.startMs && tMs < s.endMs) return s;
+  return null;
+}
+function measureSpans(measureCount2, durationMs) {
+  if (measureCount2 <= 0 || durationMs <= 0) return [];
+  const w = durationMs / measureCount2;
+  const out = [];
+  for (let i = 0; i < measureCount2; i++) {
+    out.push({ startMs: i * w, endMs: (i + 1) * w, label: String(i + 1) });
+  }
+  return out;
+}
+function validateSections(sections) {
+  if (!Array.isArray(sections)) return ["sections must be an array"];
+  const errs = [];
+  sections.forEach((raw, i) => {
+    const s = raw;
+    if (typeof s?.startMs !== "number" || typeof s?.endMs !== "number")
+      errs.push(`sections[${i}] needs numeric startMs/endMs`);
+    else if (s.endMs <= s.startMs) errs.push(`sections[${i}].endMs must be > startMs`);
+    if (s?.label != null && typeof s.label !== "string")
+      errs.push(`sections[${i}].label must be a string`);
+  });
+  return errs;
+}
+// src/scene/layers/sectionMinimap.ts
+function sectionMinimapLayer() {
+  let sectionsProp;
+  let measureCount2 = 0;
+  let barYProp;
+  let barHeight = 10;
+  let showLabel = true;
+  let color;
+  let sections = [];
+  return {
+    key: "section-minimap",
+    init(ctx, props) {
+      sectionsProp = props.sections;
+      measureCount2 = props.measureCount ?? 0;
+      barYProp = props.barY;
+      barHeight = props.barHeight ?? 10;
+      showLabel = props.showLabel ?? true;
+      color = props.color;
+      const dur = ctx.score?.durationMs ?? 0;
+      sections = sectionsProp ?? (measureCount2 > 0 ? measureSpans(measureCount2, dur) : []);
+    },
+    draw(ctx, tMs) {
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const accent = color ?? ctx.theme.accent;
+      const dur = ctx.score?.durationMs ?? 0;
+      if (dur <= 0) return;
+      const left = sb.left;
+      const width = sb.w;
+      const barY = barYProp ?? sb.bottom - 40;
+      c.save();
+      const round = barHeight / 2;
+      c.fillStyle = ctx.theme.sepia;
+      c.globalAlpha = 0.3;
+      drawBar(c, left, barY - round, width, barHeight, round);
+      if (sections.length) {
+        c.globalAlpha = 0.5;
+        sections.forEach((s, i) => {
+          const x0 = timeToX(left, width, dur, s.startMs);
+          const x1 = timeToX(left, width, dur, s.endMs);
+          c.fillStyle = i % 2 === 0 ? ctx.theme.sepia : ctx.theme.ink;
+          c.globalAlpha = i % 2 === 0 ? 0.18 : 0.1;
+          c.fillRect(x0, barY - round, Math.max(0, x1 - x0), barHeight);
+          c.globalAlpha = 0.4;
+          c.fillStyle = ctx.theme.ink;
+          c.fillRect(x0 - 1, barY - round - 3, 2, barHeight + 6);
+        });
+      }
+      const px = timeToX(left, width, dur, tMs);
+      c.globalAlpha = 0.85;
+      c.fillStyle = accent;
+      drawBar(c, left, barY - round, Math.max(0, px - left), barHeight, round);
+      c.globalAlpha = 1;
+      c.fillStyle = accent;
+      c.beginPath();
+      c.arc(px, barY, barHeight * 1.6, 0, Math.PI * 2);
+      c.fill();
+      c.fillStyle = ctx.theme.paper;
+      c.beginPath();
+      c.arc(px, barY, barHeight * 0.7, 0, Math.PI * 2);
+      c.fill();
+      if (showLabel) {
+        const act = activeSection(sections, tMs);
+        if (act?.label) {
+          c.globalAlpha = 1;
+          c.fillStyle = ctx.theme.ink;
+          c.textAlign = "center";
+          c.textBaseline = "bottom";
+          c.font = `700 ${Math.round(barHeight * 2.4)}px ${ctx.theme.fontBody}`;
+          c.fillText(act.label, px, barY - barHeight * 2.2);
+        }
+      }
+      c.restore();
+    }
+  };
+}
+function drawBar(c, x, y, w, h, r) {
+  const rr = Math.min(r, w / 2, h / 2);
+  const anyC = c;
+  if (typeof anyC.roundRect === "function") {
+    c.beginPath();
+    anyC.roundRect(x, y, w, h, rr);
+    c.fill();
+    return;
+  }
+  c.fillRect(x, y, w, h);
+}
+var sectionMinimapFactory = {
+  key: "section-minimap",
+  create: sectionMinimapLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["section-minimap: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.sections != null) errs.push(...validateSections(p.sections).map((e) => `section-minimap.${e}`));
+    if (p.measureCount != null && (typeof p.measureCount !== "number" || p.measureCount < 0 || !Number.isInteger(p.measureCount)))
+      errs.push("section-minimap.measureCount must be a non-negative integer");
+    if (p.barY != null && typeof p.barY !== "number") errs.push("section-minimap.barY must be a number");
+    if (p.barHeight != null && (typeof p.barHeight !== "number" || p.barHeight <= 0))
+      errs.push("section-minimap.barHeight must be a positive number");
+    if (p.showLabel != null && typeof p.showLabel !== "boolean")
+      errs.push("section-minimap.showLabel must be a boolean");
+    if (p.color != null && typeof p.color !== "string") errs.push("section-minimap.color must be a string");
+    return errs;
+  }
+};
 // src/scene/registry.ts
 var REGISTRY = /* @__PURE__ */ new Map();
 function registerLayer(factory) {
@@ -1451,6 +2608,14 @@ registerLayer(portraitFactory);
 registerLayer(spectrumFactory);
 registerLayer(brandingFactory);
 registerLayer(safeGuidesFactory);
+registerLayer(staffKeyboardRayFactory);
+registerLayer(countingTrackFactory);
+registerLayer(degreeLabelsFactory);
+registerLayer(functionalHarmonyFactory);
+registerLayer(mcqCardFactory);
+registerLayer(circleOfFifthsFactory);
+registerLayer(pitchContourFactory);
+registerLayer(sectionMinimapFactory);
 // src/scene/camera.ts
 function cameraTransform(cam, W, H) {
@@ -1506,7 +2671,8 @@ var SCREEN_PINNED_KEYS = /* @__PURE__ */ new Set([
   "hook",
   "reveal",
   "portrait",
-  "safe-guides"
+  "safe-guides",
+  "mcq-card"
 ]);
 async function buildScene(opts) {
   const { spec, theme, score } = opts;
@@ -1597,36 +2763,6 @@ async function recordSceneSpec(opts) {
   });
 }
-// src/scene/highlight.ts
-function highlightIntensity(region, tMs) {
-  const fade = region.fadeMs ?? 120;
-  if (tMs <= region.inMs - fade || tMs >= region.outMs + fade) return 0;
-  const rampIn = invLerp(region.inMs - fade, region.inMs, tMs);
-  const rampOut = 1 - invLerp(region.outMs, region.outMs + fade, tMs);
-  return clamp(Math.min(rampIn, rampOut), 0, 1);
-}
-function noteSetXRange(onsetsMs, windowMs, timeToX) {
-  let lo = Infinity;
-  let hi = -Infinity;
-  for (const on of onsetsMs) {
-    if (on < windowMs[0] || on > windowMs[1]) continue;
-    const x = timeToX(on);
-    if (x < lo) lo = x;
-    if (x > hi) hi = x;
-  }
-  if (lo === Infinity) return null;
-  return { x: lo, w: Math.max(0, hi - lo) };
-}
-function drawHighlight(ctx, region, tMs, accent) {
-  const a = highlightIntensity(region, tMs);
-  if (a <= 0) return;
-  ctx.save();
-  ctx.globalAlpha = a * 0.35;
-  ctx.fillStyle = region.color ?? accent;
-  ctx.fillRect(region.x, region.y, region.w, region.h);
-  ctx.restore();
-}
 // src/scene/audioLayers.ts
 function countInSchedule(opts) {
   const beats = opts.beats ?? 4;
@@ -1917,28 +3053,167 @@ function promoCardsDemoSpec(opts = {}) {
     audio: { voicing: "reading" }
   };
 }
+// src/scene/demos/extendedDemo.ts
+function countingDegreeDemoSpec(opts = {}) {
+  return {
+    size: opts.size ?? [1080, 1920],
+    theme: opts.theme ?? "rsr",
+    durationMode: "audio",
+    timeline: [
+      {
+        at: [0, "end"],
+        layers: [
+          { k: "background", p: { style: "paper" } },
+          { k: "keyboard", p: { range: opts.range ?? "auto" } },
+          { k: "degree-labels", p: { mode: opts.labelMode ?? "degree" } },
+          { k: "counting-track", p: { subdiv: opts.subdiv ?? 2 } }
+        ]
+      }
+    ]
+  };
+}
+function staffRayDemoSpec(rendered, opts = {}) {
+  return {
+    size: opts.size ?? [1080, 1920],
+    theme: opts.theme ?? "rsr",
+    durationMode: "audio",
+    timeline: [
+      {
+        at: [0, "end"],
+        layers: [
+          { k: "background", p: { style: "paper" } },
+          // notation in a top band; keyboard a short strip at the very bottom, so
+          // the rays span a clear vertical gap between staff and keys.
+          { k: "notation", p: { rendered, bandHeight: (opts.size?.[1] ?? 1920) * 0.28 } },
+          { k: "keyboard", p: { range: opts.range ?? "88", height: (opts.size?.[1] ?? 1920) * 0.16 } },
+          { k: "staff-keyboard-ray", p: {} }
+        ]
+      }
+    ]
+  };
+}
+function harmonyDemoSpec(chordTrack, opts = {}) {
+  return {
+    size: opts.size ?? [1080, 1920],
+    theme: opts.theme ?? "rsr",
+    durationMode: "audio",
+    timeline: [
+      {
+        at: [0, "end"],
+        layers: [
+          { k: "background", p: { style: "ink" } },
+          { k: "keyboard", p: { range: opts.range ?? "auto" } },
+          { k: "functional-harmony", p: { chordTrack, modes: ["band", "keys"] } }
+        ]
+      }
+    ]
+  };
+}
+function mcqDemoSpec(quiz, opts = {}) {
+  return {
+    size: opts.size ?? [1080, 1920],
+    theme: opts.theme ?? "rsr",
+    durationMode: "fixed",
+    durationSec: quiz.endMs / 1e3,
+    timeline: [
+      {
+        at: [0, "end"],
+        layers: [
+          { k: "background", p: { style: "paper" } },
+          { k: "mcq-card", p: { quiz } }
+        ]
+      }
+    ]
+  };
+}
+function circleOfFifthsDemoSpec(opts = {}) {
+  const p = {};
+  if (opts.toKey) {
+    p.toKey = opts.toKey;
+    p.fromMs = opts.fromMs ?? 0;
+    p.toMs = opts.toMs ?? 2e3;
+  }
+  return {
+    size: opts.size ?? [1080, 1920],
+    theme: opts.theme ?? "rsr",
+    durationMode: "audio",
+    timeline: [
+      {
+        at: [0, "end"],
+        layers: [
+          { k: "background", p: { style: "paper" } },
+          { k: "circle-of-fifths", p }
+        ]
+      }
+    ]
+  };
+}
+function contourMinimapDemoSpec(opts = {}) {
+  const mini = {};
+  if (opts.sections) mini.sections = opts.sections;
+  else if (opts.measureCount) mini.measureCount = opts.measureCount;
+  return {
+    size: opts.size ?? [1080, 1920],
+    theme: opts.theme ?? "rsr",
+    durationMode: "audio",
+    timeline: [
+      {
+        at: [0, "end"],
+        layers: [
+          { k: "background", p: { style: "paper" } },
+          { k: "pitch-contour", p: {} },
+          { k: "section-minimap", p: mini }
+        ]
+      }
+    ]
+  };
+}
 export {
+  DEFAULT_FUNCTION_COLORS,
+  FIFTHS_MAJOR,
+  FIFTHS_MINOR,
   FOLLOW_BARS,
   FOLLOW_PAD,
   PIANO_HIGH,
   PIANO_LOW,
+  activeChord,
   activeCue,
+  activeSection,
+  animatedSlot,
   applySchedule,
   applyToContext,
   assertGate,
+  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,
+  dotAt,
   drawCaption,
   drawHighlight,
   droneSchedule,
@@ -1953,10 +3228,14 @@ export {
   followBoxAt,
   followSrcBox,
   followWindowStart,
+  fracSlotPoint,
   frameRect,
+  functionColor,
+  functionalHarmonyFactory,
   getKeyboardLayout,
   getLayerFactory,
   getNotationEngraving,
+  harmonyDemoSpec,
   highlightIntensity,
   hookFactory,
   identityCamera,
@@ -1967,6 +3246,7 @@ export {
   keyCenterX,
   keyColumnWidth,
   keyRect,
+  keySlot,
   keyboardFactory,
   keyboardLayout,
   lerp,
@@ -1974,16 +3254,32 @@ export {
   lerpCamera,
   linear,
   mapBoxThroughLayout,
+  mcqCardFactory,
+  mcqDemoSpec,
   measureColumnsFromLayout,
   measureCount,
   measureSpanBox,
+  measureSpans,
+  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,
@@ -1991,16 +3287,26 @@ export {
   resolveKeyboardLayout,
   resolveTimeline,
   revealFactory,
+  revealProgress,
   runGate,
   safeGuidesFactory,
   scoreFromMusicXML,
   scorePitchSpan,
   scrollCursorFactory,
+  sectionMinimapFactory,
   setFollowLayoutProvider,
   setKeyboardLayout,
   setNotationEngraving,
-  setupHeadlessDom,
+  slotAngle,
+  slotPc,
+  slotPoint,
   spectrumFactory,
+  staffAnchor,
+  staffKeyboardRayFactory,
+  staffRayDemoSpec,
+  validateChordTrack,
+  validateQuiz,
+  validateSections,
   visualTimelineMs,
   whiteKeys,
   worldToViewport