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

package/dist/scene/index.js

@@ -0,0 +1,3314 @@
+import {
+  ctaScene,
+  drawSafeGuides,
+  hookScene,
+  loadPortrait,
+  recordScenes,
+  revealScene,
+  safeBox
+} from "../chunk-HXTRNE74.js";
+
+// src/scene/score.ts
+var BEATS_PER_WHOLE_NOTE = 4;
+var MAX_ITERATOR_STEPS = 2e5;
+async function scoreFromMusicXML(xml, opts = {}) {
+  const osmd = opts.osmdFactory ? opts.osmdFactory() : await defaultOsmd();
+  let loadError = null;
+  try {
+    await osmd.load(xml);
+  } catch (e) {
+    loadError = e;
+  }
+  const sheet = osmd.sheet;
+  if (!sheet || !sheet.SourceMeasures?.length) {
+    throw new Error(
+      "scoreFromMusicXML: OSMD produced no source model" + (loadError ? `: ${loadError.message}` : "")
+    );
+  }
+  const tempoMap = resolveTempo(sheet, opts);
+  const wholeNoteToMs = makeWholeNoteToMs(tempoMap.segments[0].bpm);
+  const it = sheet.MusicPartManager.getIterator();
+  const notes = [];
+  let steps = 0;
+  while (!it.EndReached && steps++ < MAX_ITERATOR_STEPS) {
+    const enrolled = it.CurrentEnrolledTimestamp?.RealValue ?? 0;
+    const onsetMs = wholeNoteToMs(enrolled);
+    const voiceEntries = it.CurrentAudibleVoiceEntries?.() ?? [];
+    for (const ve of voiceEntries) {
+      const voiceId = ve.ParentVoice?.VoiceId ?? 1;
+      const sse = ve.ParentSourceStaffEntry;
+      const staffIdx = sse?.ParentStaff?.idInMusicSheet ?? 0;
+      const instrument = sse?.ParentStaff?.ParentInstrument;
+      const hand = inferHand(instrument, sse?.ParentStaff);
+      for (const n of ve.Notes ?? []) {
+        if (n.isRestFlag || n.IsRest) continue;
+        const pitch = n.Pitch;
+        if (!pitch) continue;
+        const tie = n.NoteTie;
+        if (tie && tie.StartNote && tie.StartNote !== n) continue;
+        const wholeNoteLen = tie && tie.StartNote === n && tie.Duration ? tie.Duration.RealValue : n.Length?.RealValue ?? 0;
+        const halfTone = pitch.getHalfTone?.();
+        const pitchMidi = halfTone == null ? NaN : halfTone + 12;
+        const note = {
+          pitchMidi,
+          step: fundamentalToStep(pitch.FundamentalNote),
+          alter: pitch.AccidentalHalfTones ?? 0,
+          octave: octaveFromMidi(pitchMidi),
+          onsetMs: Math.round(onsetMs),
+          durMs: Math.round(wholeNoteToMs(wholeNoteLen)),
+          staff: staffIdx,
+          voice: voiceId,
+          hand
+        };
+        const lyric = extractLyric(ve);
+        if (lyric != null) note.lyric = lyric;
+        const fingering = extractFingering(n);
+        if (fingering != null) note.fingering = fingering;
+        notes.push(note);
+      }
+    }
+    it.moveToNext();
+  }
+  notes.sort((a, b) => a.onsetMs - b.onsetMs || a.pitchMidi - b.pitchMidi);
+  const durationMs = notes.reduce((mx, n) => Math.max(mx, n.onsetMs + n.durMs), 0);
+  return {
+    notes,
+    tempoMap,
+    durationMs,
+    key: readKey(sheet),
+    timeSig: readTimeSig(sheet),
+    title: sheet.TitleString || void 0,
+    composer: sheet.ComposerString || void 0
+  };
+}
+function resolveTempo(sheet, opts) {
+  if (opts.tempoOverride && opts.tempoOverride > 0) {
+    return { source: "override", segments: [{ atMs: 0, bpm: opts.tempoOverride }] };
+  }
+  const xmlTempo = sheet.DefaultStartTempoInBpm;
+  if (xmlTempo && xmlTempo > 0) {
+    return { source: "xml", segments: [{ atMs: 0, bpm: xmlTempo }] };
+  }
+  return { source: "fallback", segments: [{ atMs: 0, bpm: opts.tempoFallback ?? 100 }] };
+}
+function makeWholeNoteToMs(bpm) {
+  const msPerBeat2 = 6e4 / bpm;
+  return (wholeNotes) => wholeNotes * BEATS_PER_WHOLE_NOTE * msPerBeat2;
+}
+function inferHand(instrument, staff) {
+  const staves = instrument?.Staves;
+  if (Array.isArray(staves) && staves.length >= 2 && staff) {
+    const local = staves.indexOf(staff);
+    if (local >= 0) return local === 0 ? "R" : "L";
+  }
+  return "R";
+}
+function fundamentalToStep(f) {
+  return { 0: "C", 2: "D", 4: "E", 5: "F", 7: "G", 9: "A", 11: "B" }[f] ?? "?";
+}
+function octaveFromMidi(midi) {
+  if (!Number.isFinite(midi)) return 0;
+  return Math.floor(midi / 12) - 1;
+}
+function extractLyric(ve) {
+  const dict = ve.LyricsEntries;
+  if (!dict || !dict.size) return void 0;
+  const first = [...dict.values()][0];
+  const text = first?.Text?.text ?? first?.Text;
+  return typeof text === "string" && text.length ? text : void 0;
+}
+function extractFingering(note) {
+  const raw = note?.Fingering?.value ?? note?.Fingering?.Value ?? note?.Fingering;
+  const n = typeof raw === "string" ? parseInt(raw, 10) : typeof raw === "number" ? raw : NaN;
+  return Number.isFinite(n) ? n : void 0;
+}
+var MAJOR_KEYS = ["Cb", "Gb", "Db", "Ab", "Eb", "Bb", "F", "C", "G", "D", "A", "E", "B", "F#", "C#"];
+var MINOR_KEYS = ["Ab", "Eb", "Bb", "F", "C", "G", "D", "A", "E", "B", "F#", "C#", "G#", "D#", "A#"];
+function readKey(sheet) {
+  for (const entry of sheet?.SourceMeasures?.[0]?.FirstInstructionsStaffEntries ?? []) {
+    for (const ins of entry?.Instructions ?? []) {
+      if (typeof ins?.keyType === "number") {
+        const fifths = ins.keyType;
+        const idx = fifths + 7;
+        if (idx < 0 || idx > 14) return void 0;
+        const isMinor = ins.mode === 2;
+        const name = (isMinor ? MINOR_KEYS : MAJOR_KEYS)[idx];
+        return name ? `${name} ${isMinor ? "minor" : "major"}` : void 0;
+      }
+    }
+  }
+  return void 0;
+}
+function readTimeSig(sheet) {
+  const ts = sheet?.SourceMeasures?.[0]?.ActiveTimeSignature;
+  if (ts && Number.isFinite(ts.Numerator) && Number.isFinite(ts.Denominator)) {
+    return `${ts.Numerator}/${ts.Denominator}`;
+  }
+  return void 0;
+}
+async function defaultOsmd() {
+  if (typeof document === "undefined") {
+    throw new Error(
+      "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");
+  const OpenSheetMusicDisplay = mod.OpenSheetMusicDisplay ?? mod.default?.OpenSheetMusicDisplay;
+  return new OpenSheetMusicDisplay(document.createElement("div"), {
+    backend: "svg",
+    autoResize: false
+  });
+}
+
+// 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;
+var invLerp = (a, b, x) => a === b ? 0 : clamp((x - a) / (b - a), 0, 1);
+var linear = (t) => t;
+var easeInOut = (t) => {
+  const c = clamp(t, 0, 1);
+  return c * c * (3 - 2 * c);
+};
+var easeIn = (t) => {
+  const c = clamp(t, 0, 1);
+  return c * c;
+};
+var easeOut = (t) => {
+  const c = clamp(t, 0, 1);
+  return 1 - (1 - c) * (1 - c);
+};
+
+// src/scene/caption.ts
+function activeCue(script, tMs) {
+  let found = null;
+  for (const cue of script) {
+    if (tMs >= cue.inMs && tMs < cue.outMs) found = cue;
+  }
+  return found;
+}
+function cueOpacity(cue, tMs, fadeMs = 150) {
+  if (tMs < cue.inMs || tMs >= cue.outMs) return 0;
+  const inA = invLerp(cue.inMs, cue.inMs + fadeMs, tMs);
+  const outA = 1 - invLerp(cue.outMs - fadeMs, cue.outMs, tMs);
+  return clamp(Math.min(inA, outA), 0, 1);
+}
+function wrap(ctx, text, maxW, maxLines) {
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines = [];
+  let cur = "";
+  for (const w of words) {
+    const next = cur ? `${cur} ${w}` : w;
+    if (ctx.measureText(next).width > maxW && cur) {
+      lines.push(cur);
+      cur = w;
+      if (lines.length === maxLines) break;
+    } else {
+      cur = next;
+    }
+  }
+  if (cur && lines.length < maxLines) lines.push(cur);
+  return lines;
+}
+function drawCaption(ctx, script, tMs, safe, theme, style = {}) {
+  const cue = activeCue(script, tMs);
+  if (!cue) return;
+  const alpha = cueOpacity(cue, tMs);
+  if (alpha <= 0) return;
+  const size = style.size ?? 44;
+  const yFrac = style.yFrac ?? 0.92;
+  const baseY = safe.top + safe.h * yFrac;
+  ctx.save();
+  ctx.globalAlpha = alpha;
+  ctx.textAlign = "center";
+  ctx.textBaseline = "middle";
+  ctx.font = `bold ${size}px ${theme.fontBody}`;
+  const lines = wrap(ctx, cue.text, safe.w * 0.92, 3);
+  const lineH = size * 1.2;
+  const blockH = lines.length * lineH;
+  const top = baseY - blockH;
+  if (style.pill !== false) {
+    let maxW = 0;
+    for (const ln of lines) maxW = Math.max(maxW, ctx.measureText(ln).width);
+    const padX = size * 0.5;
+    const padY = size * 0.3;
+    ctx.fillStyle = "rgba(0,0,0,0.55)";
+    const pillW = Math.min(safe.w, maxW + padX * 2);
+    ctx.fillRect(safe.cx - pillW / 2, top - padY, pillW, blockH + padY * 2);
+  }
+  ctx.fillStyle = "#ffffff";
+  lines.forEach((ln, i) => {
+    ctx.fillText(ln, safe.cx, top + lineH * (i + 0.5));
+  });
+  ctx.restore();
+}
+
+// src/scene/layers/demo.ts
+function backgroundLayer() {
+  let fill = "#000000";
+  return {
+    key: "background",
+    init(ctx, props) {
+      const s = props.style ?? "paper";
+      fill = s === "paper" ? ctx.theme.paper : s === "ink" ? ctx.theme.ink : s;
+    },
+    draw(ctx) {
+      const c = ctx.ctx2d;
+      c.save();
+      c.fillStyle = fill;
+      c.fillRect(0, 0, ctx.W, ctx.H);
+      c.restore();
+    }
+  };
+}
+var backgroundFactory = {
+  key: "background",
+  create: backgroundLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["background: props must be an object"];
+    const p = props;
+    if (p.style != null && typeof p.style !== "string") errs.push("background.style must be a string");
+    return errs;
+  }
+};
+function captionLayer() {
+  let script = [];
+  let size;
+  let yFrac;
+  return {
+    key: "caption",
+    init(_ctx, props) {
+      script = props.script ?? [];
+      size = props.size;
+      yFrac = props.yFrac;
+    },
+    draw(ctx, tMs) {
+      drawCaption(ctx.ctx2d, script, tMs, ctx.safeBox, ctx.theme, { size, yFrac });
+    }
+  };
+}
+var captionFactory = {
+  key: "caption",
+  create: captionLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["caption: props must be an object"];
+    const p = props;
+    if (!Array.isArray(p.script)) {
+      errs.push("caption.script must be an array of cues");
+    } else {
+      p.script.forEach((cue, i) => {
+        const c = cue;
+        if (typeof c?.text !== "string") errs.push(`caption.script[${i}].text must be a string`);
+        if (typeof c?.inMs !== "number" || typeof c?.outMs !== "number")
+          errs.push(`caption.script[${i}] needs numeric inMs/outMs`);
+        else if (c.outMs <= c.inMs) errs.push(`caption.script[${i}] outMs must be > inMs`);
+      });
+    }
+    if (p.size != null && typeof p.size !== "number") errs.push("caption.size must be a number");
+    if (p.yFrac != null && typeof p.yFrac !== "number") errs.push("caption.yFrac must be a number");
+    return errs;
+  }
+};
+
+// src/scene/notationGeometry.ts
+var FOLLOW_BARS = 2;
+var FOLLOW_PAD = 1.06;
+function cubicEaseInOut(t) {
+  if (t < 0.5) return 4 * t * t * t;
+  const f = 2 * t - 2;
+  return 0.5 * f * f * f + 1;
+}
+function lerpBox(a, b, e) {
+  return {
+    x: a.x + (b.x - a.x) * e,
+    y: a.y + (b.y - a.y) * e,
+    w: a.w + (b.w - a.w) * e,
+    h: a.h + (b.h - a.h) * e
+  };
+}
+function cropAroundBox(box, aspect, pad, cw, ch) {
+  const bw = box.w * pad;
+  const bh = box.h * pad;
+  let w = Math.max(bw, bh * aspect);
+  let h = w / aspect;
+  w = Math.min(w, cw);
+  h = Math.min(h, ch);
+  const ccx = box.x + box.w / 2;
+  const ccy = box.y + box.h / 2;
+  let x = ccx - w / 2;
+  let y = ccy - h / 2;
+  x = Math.max(0, Math.min(cw - w, x));
+  y = Math.max(0, Math.min(ch - h, y));
+  return { x, y, w, h };
+}
+function measureSpanBox(rn, lo, hi) {
+  const ms = (rn.measures ?? []).filter((m) => m.index >= lo && m.index < hi).map((m) => m.box);
+  if (!ms.length) return null;
+  const x0 = Math.min(...ms.map((b) => b.x));
+  const y0 = Math.min(...ms.map((b) => b.y));
+  const x1 = Math.max(...ms.map((b) => b.x + b.w));
+  const y1 = Math.max(...ms.map((b) => b.y + b.h));
+  return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+}
+function firstMeasureBox(rn) {
+  const first = (rn.measures ?? []).filter((m) => m.index === 0).map((m) => m.box);
+  if (!first.length) return rn.systems?.[0] ?? null;
+  const x0 = Math.min(...first.map((b) => b.x));
+  const y0 = Math.min(...first.map((b) => b.y));
+  const x1 = Math.max(...first.map((b) => b.x + b.w));
+  const y1 = Math.max(...first.map((b) => b.y + b.h));
+  return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+}
+function measureCount(rn) {
+  const idx = (rn.measures ?? []).map((m) => m.index);
+  return idx.length ? Math.max(...idx) + 1 : 0;
+}
+function followBoxAt(rn, posMeasures) {
+  const cur = Math.floor(posMeasures);
+  const frac = posMeasures - cur;
+  const a = measureSpanBox(rn, cur, cur + FOLLOW_BARS);
+  const b = measureSpanBox(rn, cur + 1, cur + 1 + FOLLOW_BARS) ?? a;
+  if (!a) return b;
+  if (!b) return a;
+  return lerpBox(a, b, frac);
+}
+function followWindowStart(nBars, camProgress01) {
+  const posBars = camProgress01 * nBars;
+  const curBar = Math.floor(posBars);
+  const frac = posBars - curBar;
+  const scrollFrac = cubicEaseInOut(Math.min(1, Math.max(0, (frac - 0.66) / 0.34)));
+  const maxStart = Math.max(0, nBars - FOLLOW_BARS);
+  return Math.max(0, Math.min(maxStart, curBar + scrollFrac));
+}
+function notationLayout(rn, W, H, boxTop, boxH, opts = {}) {
+  const { zoom01 = 1, focusBox = null } = opts;
+  const sb = safeBox(W, H);
+  const maxW = sb.centeredW;
+  const c = rn.content && rn.content.w > 0 && rn.content.h > 0 ? rn.content : { x: 0, y: 0, w: rn.canvas.width || 1400, h: rn.canvas.height || 300 };
+  let src;
+  if (focusBox) {
+    const px = focusBox.w * (FOLLOW_PAD - 1) / 2;
+    const py = focusBox.h * (FOLLOW_PAD - 1) / 2;
+    src = {
+      x: Math.max(0, focusBox.x - px),
+      y: Math.max(0, focusBox.y - py),
+      w: focusBox.w + 2 * px,
+      h: focusBox.h + 2 * py
+    };
+    src.w = Math.min(src.w, rn.canvas.width - src.x);
+    src.h = Math.min(src.h, rn.canvas.height - src.y);
+  } else {
+    src = c;
+    const focal = firstMeasureBox(rn);
+    if (zoom01 < 1 && focal) {
+      const start = cropAroundBox(focal, c.w / c.h, 1.25, rn.canvas.width, rn.canvas.height);
+      src = lerpBox(start, c, cubicEaseInOut(zoom01));
+    }
+  }
+  const srcAspect = src.w / src.h;
+  let dw = maxW;
+  let dh = dw / srcAspect;
+  if (dh > boxH) {
+    dh = boxH;
+    dw = dh * srcAspect;
+  }
+  const dx = (W - dw) / 2;
+  const dy = boxTop + (boxH - dh) / 2;
+  const fx = dw / src.w;
+  const fy = dh / src.h;
+  const map = (b) => ({
+    x: dx + (b.x - src.x) * fx,
+    y: dy + (b.y - src.y) * fy,
+    w: b.w * fx,
+    h: b.h * fy
+  });
+  const systems = (rn.systems ?? []).map(map);
+  const measures = (rn.measures ?? []).map((m) => ({
+    ...m,
+    box: map(m.box),
+    noteStartX: dx + (m.noteStartX - src.x) * fx
+  }));
+  return { src, rect: { dx, dy, dw, dh }, systems, measures };
+}
+function measureColumnsFromLayout(measures) {
+  const byIndex = /* @__PURE__ */ new Map();
+  for (const m of measures) {
+    const cur = byIndex.get(m.index);
+    if (!cur) {
+      byIndex.set(m.index, { ...m.box, noteStartX: m.noteStartX });
+    } else {
+      const x0 = Math.min(cur.x, m.box.x);
+      const y0 = Math.min(cur.y, m.box.y);
+      const x1 = Math.max(cur.x + cur.w, m.box.x + m.box.w);
+      const y1 = Math.max(cur.y + cur.h, m.box.y + m.box.h);
+      byIndex.set(m.index, {
+        x: x0,
+        y: y0,
+        w: x1 - x0,
+        h: y1 - y0,
+        noteStartX: Math.min(cur.noteStartX, m.noteStartX)
+      });
+    }
+  }
+  return [...byIndex.keys()].sort((a, b) => a - b).map((k) => byIndex.get(k));
+}
+function playheadLine(layout, t01) {
+  const tt = Math.max(0, Math.min(1, t01));
+  let alpha = 0.85;
+  if (tt < 0.03) alpha *= tt / 0.03;
+  if (tt > 0.94) alpha *= Math.max(0, (1 - tt) / 0.06);
+  if (alpha <= 0.02) return null;
+  const padV = 10;
+  let x, y0, y1;
+  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);
+    x = startX + (pos - i) * (m.x + m.w - startX);
+    y0 = m.y - padV;
+    y1 = m.y + m.h + padV;
+  } else 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];
+    x = s.x + (pos - row) * s.w;
+    y0 = s.y - padV;
+    y1 = s.y + s.h + padV;
+  } else {
+    const r = layout.rect;
+    x = r.dx + tt * r.dw;
+    y0 = r.dy - padV;
+    y1 = r.dy + r.dh + padV;
+  }
+  return { x, y0, y1, alpha };
+}
+
+// src/scene/engravingStore.ts
+var STORE = /* @__PURE__ */ new WeakMap();
+function keyFor(ctx) {
+  return ctx.audioClock;
+}
+function setNotationEngraving(ctx, eng) {
+  STORE.set(keyFor(ctx), eng);
+}
+function getNotationEngraving(ctx) {
+  return STORE.get(keyFor(ctx));
+}
+function setFollowLayoutProvider(ctx, fn) {
+  const e = STORE.get(keyFor(ctx));
+  if (e) e.followLayoutAt = fn;
+}
+
+// src/scene/layers/notation.ts
+function notationLayer() {
+  let rn = null;
+  let base = null;
+  let propScale = 1;
+  let propBandTop;
+  let propBandHeight;
+  function bandTop(_ctx, sb) {
+    return propBandTop ?? sb.top;
+  }
+  function bandHeight(ctx, sb) {
+    const top = bandTop(ctx, sb);
+    return (propBandHeight ?? sb.bottom - top) * propScale;
+  }
+  return {
+    key: "notation",
+    async init(ctx, props) {
+      propScale = props.scale ?? 1;
+      propBandTop = props.bandTop;
+      propBandHeight = props.bandHeight;
+      if (props.rendered) {
+        rn = props.rendered;
+      } else if (props.xml) {
+        const { renderNotation } = await import("../promo.js");
+        rn = await renderNotation(props.xml, { bars: props.bars, paper: ctx.theme.paper });
+      } else {
+        throw new Error("notation layer: provide `rendered` or `xml`");
+      }
+      const sb = safeBox(ctx.W, ctx.H);
+      const top = bandTop(ctx, sb);
+      const height = bandHeight(ctx, sb);
+      base = notationLayout(rn, ctx.W, ctx.H, top, height, {});
+      setNotationEngraving(ctx, { rendered: rn, base, bandTop: top, bandHeight: height });
+    },
+    draw(ctx, tMs) {
+      if (!rn || !base) return;
+      const eng = getNotationEngraving(ctx);
+      const l = eng?.followLayoutAt ? eng.followLayoutAt(ctx, tMs) : base;
+      const c = ctx.ctx2d;
+      c.drawImage(
+        rn.canvas,
+        l.src.x,
+        l.src.y,
+        l.src.w,
+        l.src.h,
+        l.rect.dx,
+        l.rect.dy,
+        l.rect.dw,
+        l.rect.dh
+      );
+    },
+    dispose() {
+      rn = null;
+      base = null;
+    }
+  };
+}
+var notationFactory = {
+  key: "notation",
+  create: notationLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["notation: props must be an object"];
+    const p = props;
+    if (p.system != null && p.system !== "grand" && p.system !== "single")
+      errs.push('notation.system must be "grand" | "single"');
+    if (p.scale != null && (typeof p.scale !== "number" || p.scale <= 0))
+      errs.push("notation.scale must be a positive number");
+    if (p.rendered == null && typeof p.xml !== "string")
+      errs.push("notation: provide `rendered` (RenderedNotation) or `xml` (string)");
+    if (p.bars != null && (!Array.isArray(p.bars) || p.bars.length !== 2))
+      errs.push("notation.bars must be [from,to]");
+    return errs;
+  }
+};
+
+// src/scene/layers/scrollCursor.ts
+function followLayoutFor(ctx, camProgress01) {
+  const eng = getNotationEngraving(ctx);
+  if (!eng) return null;
+  const nBars = measureCount(eng.rendered);
+  if (nBars <= 0) return eng.base;
+  const windowStart = followWindowStart(nBars, camProgress01);
+  const focusBox = followBoxAt(eng.rendered, windowStart);
+  return notationLayout(eng.rendered, ctx.W, ctx.H, eng.bandTop, eng.bandHeight, { focusBox });
+}
+function scrollCursorLayer() {
+  let musicMs = 0;
+  let openingZoomMs = 900;
+  let color;
+  function camProgress(tMs) {
+    const phMs = tMs - openingZoomMs;
+    if (phMs < 0 || musicMs <= 0) return 0;
+    return Math.min(1, phMs / musicMs);
+  }
+  function layoutAt(ctx, tMs) {
+    const eng = getNotationEngraving(ctx);
+    return followLayoutFor(ctx, camProgress(tMs)) ?? eng.base;
+  }
+  return {
+    key: "scroll-cursor",
+    init(ctx, props) {
+      musicMs = props.musicMs;
+      openingZoomMs = props.openingZoomMs ?? 900;
+      color = props.color;
+      setFollowLayoutProvider(ctx, layoutAt);
+    },
+    draw(ctx, tMs) {
+      const eng = getNotationEngraving(ctx);
+      if (!eng) return;
+      const p = camProgress(tMs);
+      const layout = layoutAt(ctx, tMs);
+      const line = playheadLine(layout, p);
+      if (!line) return;
+      const c = ctx.ctx2d;
+      c.save();
+      c.strokeStyle = color ?? ctx.theme.accent;
+      c.globalAlpha = line.alpha;
+      c.lineWidth = 4;
+      c.beginPath();
+      c.moveTo(line.x, line.y0);
+      c.lineTo(line.x, line.y1);
+      c.stroke();
+      c.restore();
+    }
+  };
+}
+var scrollCursorFactory = {
+  key: "scroll-cursor",
+  create: scrollCursorLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["scroll-cursor: props must be an object"];
+    const p = props;
+    if (typeof p.musicMs !== "number" || !(p.musicMs > 0))
+      errs.push("scroll-cursor.musicMs must be a positive number (total music length ms)");
+    if (p.followBars != null && (typeof p.followBars !== "number" || p.followBars < 1))
+      errs.push("scroll-cursor.followBars must be a number >= 1");
+    if (p.openingZoomMs != null && (typeof p.openingZoomMs !== "number" || p.openingZoomMs < 0))
+      errs.push("scroll-cursor.openingZoomMs must be a number >= 0");
+    if (p.color != null && typeof p.color !== "string") errs.push("scroll-cursor.color must be a string");
+    return errs;
+  }
+};
+
+// src/scene/keyboardGeometry.ts
+var BLACK_PC = /* @__PURE__ */ new Set([1, 3, 6, 8, 10]);
+function whiteIndexAtOrBelow(midi) {
+  const oct = Math.floor(midi / 12);
+  const pc = midi - oct * 12;
+  const WHITES_BELOW = [0, 1, 1, 2, 2, 3, 4, 4, 5, 5, 6, 6];
+  return oct * 7 + WHITES_BELOW[pc];
+}
+function isBlackKey(midi) {
+  return BLACK_PC.has((midi % 12 + 12) % 12);
+}
+var PIANO_LOW = 21;
+var PIANO_HIGH = 108;
+function snapDownToWhite(midi) {
+  let m = midi;
+  while (isBlackKey(m)) m--;
+  return m;
+}
+function snapUpToWhite(midi) {
+  let m = midi;
+  while (isBlackKey(m)) m++;
+  return m;
+}
+function keyboardLayout(opts) {
+  let low;
+  let high;
+  if (opts.range === "auto" && opts.span) {
+    low = snapDownToWhite(opts.span[0]);
+    high = snapUpToWhite(opts.span[1]);
+    low = snapDownToWhite(low - 1);
+    high = snapUpToWhite(high + 1);
+  } else {
+    low = PIANO_LOW;
+    high = PIANO_HIGH;
+  }
+  const firstWhiteIndex = whiteIndexAtOrBelow(low);
+  const lastWhiteIndex = whiteIndexAtOrBelow(high);
+  const whiteCount = lastWhiteIndex - firstWhiteIndex + 1;
+  const whiteW = opts.w / whiteCount;
+  return {
+    lowMidi: low,
+    highMidi: high,
+    x: opts.x,
+    w: opts.w,
+    top: opts.top,
+    height: opts.height,
+    whiteW,
+    firstWhiteIndex,
+    whiteCount
+  };
+}
+function scorePitchSpan(midis) {
+  if (!midis.length) return [PIANO_LOW, PIANO_HIGH];
+  return [Math.min(...midis), Math.max(...midis)];
+}
+function resolveKeyboardLayout(args) {
+  return keyboardLayout({
+    range: args.range,
+    span: args.range === "auto" ? scorePitchSpan(args.pitchMidis) : void 0,
+    x: args.left,
+    w: args.width,
+    top: args.bottomY - args.height,
+    height: args.height
+  });
+}
+function keyCenterX(layout, midi) {
+  const wIdx = whiteIndexAtOrBelow(midi) - layout.firstWhiteIndex;
+  const whiteCenter = layout.x + (wIdx + 0.5) * layout.whiteW;
+  if (!isBlackKey(midi)) return whiteCenter;
+  return whiteCenter + layout.whiteW / 2;
+}
+function keyColumnWidth(layout, midi) {
+  return isBlackKey(midi) ? layout.whiteW * 0.6 : layout.whiteW * 0.9;
+}
+function keyRect(layout, midi) {
+  const cx = keyCenterX(layout, midi);
+  if (isBlackKey(midi)) {
+    const w2 = layout.whiteW * 0.6;
+    return { x: cx - w2 / 2, y: layout.top, w: w2, h: layout.height * 0.62, black: true };
+  }
+  const w = layout.whiteW;
+  return { x: cx - w / 2, y: layout.top, w, h: layout.height, black: false };
+}
+function inRange(layout, midi) {
+  return midi >= layout.lowMidi && midi <= layout.highMidi;
+}
+function whiteKeys(layout) {
+  const out = [];
+  for (let m = layout.lowMidi; m <= layout.highMidi; m++) if (!isBlackKey(m)) out.push(m);
+  return out;
+}
+function blackKeys(layout) {
+  const out = [];
+  for (let m = layout.lowMidi; m <= layout.highMidi; m++) if (isBlackKey(m)) out.push(m);
+  return out;
+}
+var PC_COLORS = [
+  "#e64545",
+  "#e6803a",
+  "#e6c23a",
+  "#9bcf3a",
+  "#3acf6e",
+  "#3acfb0",
+  "#3aa6e6",
+  "#3a5fe6",
+  "#7a3ae6",
+  "#b03ae6",
+  "#e63ab0",
+  "#e63a6e"
+];
+function noteColor(midi, hand, colorBy, hands) {
+  if (colorBy === "pitch-class") return PC_COLORS[(midi % 12 + 12) % 12];
+  return hand === "L" ? hands.L : hands.R;
+}
+
+// src/scene/keyboardStore.ts
+var STORE2 = /* @__PURE__ */ new WeakMap();
+function keyFor2(ctx) {
+  return ctx.audioClock;
+}
+function setKeyboardLayout(ctx, layout) {
+  STORE2.set(keyFor2(ctx), layout);
+}
+function getKeyboardLayout(ctx) {
+  return STORE2.get(keyFor2(ctx));
+}
+
+// src/scene/layers/keyboard.ts
+function keyboardLayer() {
+  let layout = null;
+  let colorBy = "hand";
+  let hands = { R: "#7b2436", L: "#c8a55b" };
+  return {
+    key: "keyboard",
+    init(ctx, props) {
+      colorBy = props.colorBy ?? "hand";
+      hands = props.handColors ?? { R: ctx.theme.accent, L: ctx.theme.gold };
+      const sb = ctx.safeBox;
+      const height = props.height ?? 220;
+      const bottomY = props.bottomY ?? sb.bottom;
+      const midis = (ctx.score?.notes ?? []).map((n) => n.pitchMidi);
+      layout = resolveKeyboardLayout({
+        range: props.range ?? "auto",
+        pitchMidis: midis,
+        left: sb.left,
+        width: sb.w,
+        bottomY,
+        height
+      });
+      setKeyboardLayout(ctx, layout);
+    },
+    draw(ctx, tMs) {
+      if (!layout) return;
+      const c = ctx.ctx2d;
+      const L = layout;
+      const lit = /* @__PURE__ */ new Map();
+      for (const n of ctx.score?.notes ?? []) {
+        if (tMs >= n.onsetMs && tMs < n.onsetMs + n.durMs) lit.set(n.pitchMidi, n.hand);
+      }
+      c.save();
+      for (const m of whiteKeys(L)) {
+        const r = keyRect(L, m);
+        const onHand = lit.get(m);
+        c.fillStyle = onHand ? noteColor(m, onHand, colorBy, hands) : "#fbfbfb";
+        c.fillRect(r.x, r.y, r.w, r.h);
+        c.strokeStyle = "#b8b0a4";
+        c.lineWidth = 1;
+        c.strokeRect(r.x, r.y, r.w, r.h);
+      }
+      for (const m of blackKeys(L)) {
+        const r = keyRect(L, m);
+        const onHand = lit.get(m);
+        c.fillStyle = onHand ? noteColor(m, onHand, colorBy, hands) : "#1a1614";
+        c.fillRect(r.x, r.y, r.w, r.h);
+      }
+      c.restore();
+    },
+    dispose() {
+      layout = null;
+    }
+  };
+}
+var keyboardFactory = {
+  key: "keyboard",
+  create: keyboardLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["keyboard: props must be an object"];
+    const p = props;
+    if (p.range != null && p.range !== "88" && p.range !== "auto")
+      errs.push('keyboard.range must be "88" | "auto"');
+    if (p.colorBy != null && p.colorBy !== "hand" && p.colorBy !== "pitch-class")
+      errs.push('keyboard.colorBy must be "hand" | "pitch-class"');
+    if (p.height != null && (typeof p.height !== "number" || p.height <= 0))
+      errs.push("keyboard.height must be a positive number");
+    if (p.bottomY != null && typeof p.bottomY !== "number")
+      errs.push("keyboard.bottomY must be a number");
+    return errs;
+  }
+};
+
+// src/scene/layers/fallingNotes.ts
+var DEFAULT_LEAD_MS = 2e3;
+function fallingNotesLayer() {
+  let paired = true;
+  let colorBy = "hand";
+  let hands = { R: "#7b2436", L: "#c8a55b" };
+  let hitGlow = true;
+  let ownLayout = null;
+  let topY = 0;
+  let leadMsProp;
+  let speedProp;
+  function layoutFor(ctx) {
+    if (paired) return getKeyboardLayout(ctx) ?? ownLayout;
+    return ownLayout;
+  }
+  function hitLineY(layout) {
+    return layout.top;
+  }
+  function pxPerMs(fallHeight) {
+    if (leadMsProp != null) return fallHeight / leadMsProp;
+    if (speedProp != null) return speedProp / 1e3;
+    return fallHeight / DEFAULT_LEAD_MS;
+  }
+  return {
+    key: "falling-notes",
+    init(ctx, props) {
+      paired = props.keyboard ?? true;
+      colorBy = props.colorBy ?? "hand";
+      hands = props.handColors ?? { R: ctx.theme.accent, L: ctx.theme.gold };
+      hitGlow = props.hitGlow ?? true;
+      leadMsProp = props.leadMs;
+      speedProp = props.speed;
+      const sb = ctx.safeBox;
+      topY = props.topY ?? sb.top;
+      if (!paired) {
+        const hitLine = props.hitLineY ?? sb.bottom - 220;
+        const midis = (ctx.score?.notes ?? []).map((n) => n.pitchMidi);
+        ownLayout = resolveKeyboardLayout({
+          range: props.range ?? "auto",
+          pitchMidis: midis,
+          left: sb.left,
+          width: sb.w,
+          // top of the keyboard == hit-line; height below it is irrelevant here.
+          bottomY: hitLine + 1,
+          height: 1
+        });
+      }
+    },
+    draw(ctx, tMs) {
+      const layout = layoutFor(ctx);
+      if (!layout) return;
+      const c = ctx.ctx2d;
+      const hit = hitLineY(layout);
+      const fallH = Math.max(1, hit - topY);
+      const v = pxPerMs(fallH);
+      for (const n of ctx.score?.notes ?? []) {
+        if (!inRange(layout, n.pitchMidi)) continue;
+        const bottomY = hit - (n.onsetMs - tMs) * v;
+        const lenPx = Math.max(2, n.durMs * v);
+        const topEdge = bottomY - lenPx;
+        if (bottomY < topY) continue;
+        if (topEdge > hit) continue;
+        const cx = keyCenterX(layout, n.pitchMidi);
+        const w = keyColumnWidth(layout, n.pitchMidi);
+        const drawTop = Math.max(topY, topEdge);
+        const drawBottom = Math.min(hit, bottomY);
+        const fill = noteColor(n.pitchMidi, n.hand, colorBy, hands);
+        c.save();
+        c.fillStyle = fill;
+        c.globalAlpha = 0.92;
+        c.fillRect(cx - w / 2, drawTop, w, Math.max(1, drawBottom - drawTop));
+        c.restore();
+      }
+      if (hitGlow) {
+        for (const n of ctx.score?.notes ?? []) {
+          if (!(tMs >= n.onsetMs && tMs < n.onsetMs + n.durMs)) continue;
+          if (!inRange(layout, n.pitchMidi)) continue;
+          const cx = keyCenterX(layout, n.pitchMidi);
+          const w = keyColumnWidth(layout, n.pitchMidi);
+          c.save();
+          c.globalAlpha = 0.5;
+          c.fillStyle = noteColor(n.pitchMidi, n.hand, colorBy, hands);
+          c.fillRect(cx - w / 2, hit - 8, w, 8);
+          c.restore();
+        }
+      }
+    },
+    dispose() {
+      ownLayout = null;
+    }
+  };
+}
+var fallingNotesFactory = {
+  key: "falling-notes",
+  create: fallingNotesLayer,
+  validateProps(props) {
+    const errs = [];
+    if (props == null || typeof props !== "object") return ["falling-notes: props must be an object"];
+    const p = props;
+    if (p.keyboard != null && typeof p.keyboard !== "boolean")
+      errs.push("falling-notes.keyboard must be a boolean");
+    if (p.colorBy != null && p.colorBy !== "hand" && p.colorBy !== "pitch-class")
+      errs.push('falling-notes.colorBy must be "hand" | "pitch-class"');
+    if (p.leadMs != null && (typeof p.leadMs !== "number" || p.leadMs <= 0))
+      errs.push("falling-notes.leadMs must be a positive number");
+    if (p.speed != null && (typeof p.speed !== "number" || p.speed <= 0))
+      errs.push("falling-notes.speed must be a positive number");
+    if (p.hitGlow != null && typeof p.hitGlow !== "boolean")
+      errs.push("falling-notes.hitGlow must be a boolean");
+    if (p.range != null && p.range !== "88" && p.range !== "auto")
+      errs.push('falling-notes.range must be "88" | "auto"');
+    return errs;
+  }
+};
+
+// src/scene/layers/promoCards.ts
+function localT01(tMs, startMs, durationMs) {
+  if (durationMs <= 0) return 0;
+  const t = (tMs - startMs) / durationMs;
+  return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+function validateWindow(p, key) {
+  const errs = [];
+  if (p.startMs != null && (typeof p.startMs !== "number" || p.startMs < 0))
+    errs.push(`${key}.startMs must be a number >= 0`);
+  if (p.durationMs != null && (typeof p.durationMs !== "number" || !(p.durationMs > 0)))
+    errs.push(`${key}.durationMs must be a positive number`);
+  return errs;
+}
+function hookLayer() {
+  let scene = null;
+  let startMs = 0;
+  let durationMs = 0;
+  return {
+    key: "hook",
+    init(ctx, props) {
+      const opts = { lines: props.lines, brand: props.brand };
+      scene = hookScene(ctx.theme, opts);
+      startMs = props.startMs ?? 0;
+      durationMs = props.durationMs ?? scene.durationMs;
+    },
+    draw(ctx, tMs) {
+      if (!scene) return;
+      scene.draw(ctx.ctx2d, localT01(tMs, startMs, durationMs));
+    }
+  };
+}
+var hookFactory = {
+  key: "hook",
+  create: hookLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["hook: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (!Array.isArray(p.lines) || !p.lines.every((l) => typeof l === "string"))
+      errs.push("hook.lines must be an array of strings");
+    if (p.brand != null && typeof p.brand !== "string") errs.push("hook.brand must be a string");
+    return [...errs, ...validateWindow(p, "hook")];
+  }
+};
+function revealLayer() {
+  let scene = null;
+  let startMs = 0;
+  let durationMs = 0;
+  return {
+    key: "reveal",
+    init(ctx, props) {
+      const opts = {
+        title: props.title,
+        subtitle: props.subtitle,
+        initials: props.initials,
+        funFact: props.funFact,
+        portrait: null
+        // the `portrait` layer carries the medallion image; reveal
+        // here is the initials-fallback look. See portrait.ts.
+      };
+      scene = revealScene(ctx.theme, opts);
+      startMs = props.startMs ?? 0;
+      durationMs = props.durationMs ?? scene.durationMs;
+    },
+    draw(ctx, tMs) {
+      if (!scene) return;
+      scene.draw(ctx.ctx2d, localT01(tMs, startMs, durationMs));
+    }
+  };
+}
+var revealFactory = {
+  key: "reveal",
+  create: revealLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["reveal: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (typeof p.title !== "string") errs.push("reveal.title must be a string");
+    if (typeof p.subtitle !== "string") errs.push("reveal.subtitle must be a string");
+    if (p.initials != null && typeof p.initials !== "string") errs.push("reveal.initials must be a string");
+    if (p.funFact != null && typeof p.funFact !== "string") errs.push("reveal.funFact must be a string");
+    return [...errs, ...validateWindow(p, "reveal")];
+  }
+};
+function ctaLayer() {
+  let scene = null;
+  let startMs = 0;
+  let durationMs = 0;
+  return {
+    key: "cta",
+    init(ctx, props) {
+      const opts = { lines: props.lines };
+      scene = ctaScene(ctx.theme, opts);
+      startMs = props.startMs ?? 0;
+      durationMs = props.durationMs ?? scene.durationMs;
+    },
+    draw(ctx, tMs) {
+      if (!scene) return;
+      scene.draw(ctx.ctx2d, localT01(tMs, startMs, durationMs));
+    }
+  };
+}
+var ctaFactory = {
+  key: "cta",
+  create: ctaLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["cta: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (!Array.isArray(p.lines) || !p.lines.every((l) => typeof l === "string"))
+      errs.push("cta.lines must be an array of strings");
+    return [...errs, ...validateWindow(p, "cta")];
+  }
+};
+function portraitLayer() {
+  let scene = null;
+  let startMs = 0;
+  let durationMs = 0;
+  return {
+    key: "portrait",
+    async init(ctx, props) {
+      const portrait = await loadPortrait(props.url ?? null);
+      const opts = {
+        title: props.title,
+        subtitle: props.subtitle,
+        initials: props.initials,
+        funFact: props.funFact,
+        portrait
+      };
+      scene = revealScene(ctx.theme, opts);
+      startMs = props.startMs ?? 0;
+      durationMs = props.durationMs ?? scene.durationMs;
+    },
+    draw(ctx, tMs) {
+      if (!scene) return;
+      scene.draw(ctx.ctx2d, localT01(tMs, startMs, durationMs));
+    }
+  };
+}
+var portraitFactory = {
+  key: "portrait",
+  create: portraitLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["portrait: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (typeof p.title !== "string") errs.push("portrait.title must be a string");
+    if (typeof p.subtitle !== "string") errs.push("portrait.subtitle must be a string");
+    if (p.url != null && typeof p.url !== "string") errs.push("portrait.url must be a string or null");
+    if (p.initials != null && typeof p.initials !== "string") errs.push("portrait.initials must be a string");
+    if (p.funFact != null && typeof p.funFact !== "string") errs.push("portrait.funFact must be a string");
+    return [...errs, ...validateWindow(p, "portrait")];
+  }
+};
+
+// src/scene/layers/spectrum.ts
+var SPEC_BARS = 44;
+function lerpHex(a, b, f) {
+  const pa = parseInt(a.slice(1), 16);
+  const pb = parseInt(b.slice(1), 16);
+  const r = Math.round((pa >> 16 & 255) + ((pb >> 16 & 255) - (pa >> 16 & 255)) * f);
+  const g = Math.round((pa >> 8 & 255) + ((pb >> 8 & 255) - (pa >> 8 & 255)) * f);
+  const bl = Math.round((pa & 255) + ((pb & 255) - (pa & 255)) * f);
+  return `rgb(${r},${g},${bl})`;
+}
+function syntheticMagnitude(tSec, b, n) {
+  const phase = tSec * 5 + b * 0.45;
+  let m = 0.22 + 0.16 * Math.sin(phase) + 0.1 * Math.sin(phase * 1.7 + 1.2);
+  m *= 0.5 + 0.5 * Math.sin(b / (n - 1) * Math.PI);
+  return m;
+}
+function binByteFreq(freq, n) {
+  let peak = 0;
+  for (let i = 0; i < freq.length; i++) if (freq[i] > peak) peak = freq[i];
+  if (peak <= 4) return null;
+  const lo = 2, hi = 440;
+  const out = [];
+  for (let b = 0; b < n; b++) {
+    const f0 = lo * Math.pow(hi / lo, b / n);
+    const f1 = lo * Math.pow(hi / lo, (b + 1) / n);
+    const i0 = Math.floor(f0);
+    const i1 = Math.max(i0 + 1, Math.floor(f1));
+    let sum = 0, c = 0;
+    for (let i = i0; i < i1 && i < freq.length; i++) {
+      sum += freq[i];
+      c++;
+    }
+    let m = c ? sum / c / 255 : 0;
+    m = Math.pow(m, 0.78);
+    out.push(m);
+  }
+  return out;
+}
+function spectrumLayer() {
+  let n = SPEC_BARS;
+  let centerFrac = 0.46;
+  let maxHeightFrac = 0.135;
+  let colorLow;
+  let colorHigh;
+  let levelsFn;
+  function magnitudesAt(ctx, tMs) {
+    const fromProp = levelsFn?.(tMs, n);
+    const src = fromProp ?? resolveFromCtx(ctx, tMs);
+    if (src && src.length) {
+      const out = new Array(n);
+      for (let b = 0; b < n; b++) out[b] = clamp01(src[Math.min(src.length - 1, b)] ?? 0);
+      return out;
+    }
+    const tSec = tMs / 1e3;
+    return Array.from({ length: n }, (_, b) => clamp01(syntheticMagnitude(tSec, b, n)));
+  }
+  function resolveFromCtx(ctx, tMs) {
+    const sp = ctx.spectrum;
+    if (!sp) return null;
+    const lv = sp.levels?.(tMs, n);
+    if (lv && lv.length) return Array.from(lv);
+    const bf = sp.byteFreq?.(tMs);
+    if (bf && bf.length) return binByteFreq(bf, n);
+    return null;
+  }
+  return {
+    key: "spectrum",
+    init(_ctx, props) {
+      n = props.bars ?? SPEC_BARS;
+      centerFrac = props.centerFrac ?? 0.46;
+      maxHeightFrac = props.maxHeightFrac ?? 0.135;
+      colorLow = props.colorLow;
+      colorHigh = props.colorHigh;
+      levelsFn = props.levelsFn;
+    },
+    draw(ctx, tMs) {
+      const c = ctx.ctx2d;
+      const W = ctx.W, H = ctx.H;
+      const sb = ctx.safeBox;
+      const cy = H * centerFrac;
+      const left = Math.max(W * 0.1, sb.left);
+      const right = sb.right;
+      const span = right - left;
+      const slot = span / n;
+      const gap = slot * 0.34;
+      const barW = slot - gap;
+      const maxH = H * maxHeightFrac;
+      const lo = colorLow ?? ctx.theme.accent;
+      const hi = colorHigh ?? ctx.theme.gold;
+      c.save();
+      c.strokeStyle = lerpHex(ctx.theme.paper, ctx.theme.sepia, 0.28);
+      c.lineWidth = 2;
+      c.beginPath();
+      c.moveTo(left, cy);
+      c.lineTo(right, cy);
+      c.stroke();
+      const mags = magnitudesAt(ctx, tMs);
+      const useRound = typeof c.roundRect === "function";
+      for (let b = 0; b < n; b++) {
+        const m = mags[b];
+        const half = Math.max(barW * 0.5, m * maxH);
+        const x0 = left + b * slot + gap / 2;
+        c.fillStyle = lerpHex(lo, hi, m);
+        if (useRound) {
+          const r = Math.min(barW / 2, half);
+          c.beginPath();
+          c.roundRect(x0, cy - half, barW, half * 2, r);
+          c.fill();
+        } else {
+          c.fillRect(x0, cy - half, barW, half * 2);
+        }
+      }
+      c.restore();
+    }
+  };
+}
+function clamp01(x) {
+  return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+var spectrumFactory = {
+  key: "spectrum",
+  create: spectrumLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["spectrum: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.bars != null && (typeof p.bars !== "number" || p.bars < 2)) errs.push("spectrum.bars must be a number >= 2");
+    if (p.centerFrac != null && (typeof p.centerFrac !== "number" || p.centerFrac < 0 || p.centerFrac > 1))
+      errs.push("spectrum.centerFrac must be in [0,1]");
+    if (p.maxHeightFrac != null && (typeof p.maxHeightFrac !== "number" || p.maxHeightFrac <= 0))
+      errs.push("spectrum.maxHeightFrac must be a positive number");
+    if (p.colorLow != null && typeof p.colorLow !== "string") errs.push("spectrum.colorLow must be a string");
+    if (p.colorHigh != null && typeof p.colorHigh !== "string") errs.push("spectrum.colorHigh must be a string");
+    if (p.levelsFn != null && typeof p.levelsFn !== "function") errs.push("spectrum.levelsFn must be a function");
+    return errs;
+  }
+};
+
+// src/scene/layers/branding.ts
+function brandingLayer() {
+  let logo;
+  let safezone = false;
+  let yFrac = 1;
+  let size = 34;
+  let color;
+  return {
+    key: "branding",
+    init(_ctx, props) {
+      logo = props.logo;
+      safezone = props.safezone ?? false;
+      yFrac = props.yFrac ?? 1;
+      size = props.size ?? 34;
+      color = props.color;
+    },
+    draw(ctx) {
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const text = logo ?? ctx.theme.brand;
+      c.save();
+      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);
+      c.fillText(text, sb.cx, y);
+      c.restore();
+      if (safezone) drawSafeGuides(c);
+    }
+  };
+}
+var brandingFactory = {
+  key: "branding",
+  create: brandingLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["branding: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.logo != null && typeof p.logo !== "string") errs.push("branding.logo must be a string");
+    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");
+    if (p.color != null && typeof p.color !== "string") errs.push("branding.color must be a string");
+    return errs;
+  }
+};
+function safeGuidesLayer() {
+  return {
+    key: "safe-guides",
+    init() {
+    },
+    draw(ctx) {
+      drawSafeGuides(ctx.ctx2d);
+    }
+  };
+}
+var safeGuidesFactory = {
+  key: "safe-guides",
+  create: safeGuidesLayer,
+  validateProps(props) {
+    if (props != null && typeof props !== "object") return ["safe-guides: props must be an object"];
+    return [];
+  }
+};
+
+// 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) {
+  REGISTRY.set(factory.key, factory);
+}
+function getLayerFactory(key) {
+  return REGISTRY.get(key);
+}
+function registeredKeys() {
+  return [...REGISTRY.keys()];
+}
+registerLayer(backgroundFactory);
+registerLayer(captionFactory);
+registerLayer(notationFactory);
+registerLayer(scrollCursorFactory);
+registerLayer(keyboardFactory);
+registerLayer(fallingNotesFactory);
+registerLayer(hookFactory);
+registerLayer(revealFactory);
+registerLayer(ctaFactory);
+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) {
+  const s = cam.zoom;
+  return [s, 0, 0, s, W / 2 - cam.cx * s, H / 2 - cam.cy * s];
+}
+function worldToViewport(cam, W, H, x, y) {
+  const [a, , , d, e, f] = cameraTransform(cam, W, H);
+  return { x: a * x + e, y: d * y + f };
+}
+function frameRect(rect, W, H, pad = 0) {
+  const padded = 1 + Math.max(0, pad) * 2;
+  const zoom = Math.min(W / (rect.w * padded), H / (rect.h * padded));
+  return { cx: rect.x + rect.w / 2, cy: rect.y + rect.h / 2, zoom };
+}
+function lerpCamera(a, b, t01, ease = easeInOut) {
+  const k = ease(clamp(t01, 0, 1));
+  return { cx: lerp(a.cx, b.cx, k), cy: lerp(a.cy, b.cy, k), zoom: lerp(a.zoom, b.zoom, k) };
+}
+function kenBurns(from, to, at01) {
+  return lerpCamera(from, to, at01, easeInOut);
+}
+function applyToContext(ctx, cam, W, H) {
+  const m = cameraTransform(cam, W, H);
+  ctx.setTransform(m[0], m[1], m[2], m[3], m[4], m[5]);
+}
+function identityCamera(W, H) {
+  return { cx: W / 2, cy: H / 2, zoom: 1 };
+}
+
+// src/scene/runner.ts
+function resolveAnchor(anchor, totalSec) {
+  if (typeof anchor === "number") return anchor;
+  if (anchor === "end") return totalSec;
+  const m = /^end-(\d+(?:\.\d+)?)$/.exec(anchor);
+  if (m) return totalSec - parseFloat(m[1]);
+  throw new Error(`resolveAnchor: bad anchor "${anchor}"`);
+}
+function resolveTimeline(spec, totalSec) {
+  return spec.timeline.map((seg) => {
+    const startSec = resolveAnchor(seg.at[0], totalSec);
+    const endSec = resolveAnchor(seg.at[1], totalSec);
+    return { startMs: startSec * 1e3, endMs: endSec * 1e3, layers: seg.layers };
+  });
+}
+function visualTimelineMs(resolved) {
+  return resolved.reduce((mx, s) => Math.max(mx, s.endMs), 0);
+}
+var SCREEN_PINNED_KEYS = /* @__PURE__ */ new Set([
+  "caption",
+  "branding",
+  "cta",
+  "hook",
+  "reveal",
+  "portrait",
+  "safe-guides",
+  "mcq-card"
+]);
+async function buildScene(opts) {
+  const { spec, theme, score } = opts;
+  const [W, H] = spec.size;
+  const fps = spec.fps ?? 30;
+  const resolved = resolveTimeline(spec, opts.totalSec);
+  const safe = safeBox(W, H);
+  const camera = opts.camera ?? (() => identityCamera(W, H));
+  const clock = { nowMs: () => 0 };
+  const baseCtx = {
+    W,
+    H,
+    score,
+    audioClock: clock,
+    theme,
+    safeBox: safe,
+    fps
+  };
+  const bound = [];
+  for (const seg of resolved) {
+    for (const sl of seg.layers) {
+      const factory = getLayerFactory(sl.k);
+      if (!factory) {
+        throw new Error(`buildScene: unknown layer "${sl.k}" (registered: ${registeredKeys().join(", ")})`);
+      }
+      const errs = factory.validateProps(sl.p ?? {});
+      if (errs.length) {
+        throw new Error(`buildScene: invalid props for "${sl.k}": ${errs.join("; ")}`);
+      }
+      const layer = factory.create();
+      await layer.init({ ...baseCtx, ctx2d: null }, sl.p ?? {});
+      bound.push({
+        layer,
+        startMs: seg.startMs,
+        endMs: seg.endMs,
+        screenPinned: SCREEN_PINNED_KEYS.has(sl.k)
+      });
+    }
+  }
+  const durationMs = visualTimelineMs(resolved);
+  function renderFrame(ctx2d, tMs) {
+    clock.nowMs = () => tMs;
+    const ctx = { ...baseCtx, ctx2d };
+    const cam = camera(tMs);
+    ctx2d.save();
+    applyToContext(ctx2d, cam, W, H);
+    for (const b of bound) {
+      if (b.screenPinned) continue;
+      if (tMs < b.startMs || tMs >= b.endMs) continue;
+      b.layer.draw(ctx, tMs);
+    }
+    ctx2d.restore();
+    ctx2d.save();
+    ctx2d.setTransform(1, 0, 0, 1, 0, 0);
+    for (const b of bound) {
+      if (!b.screenPinned) continue;
+      if (tMs < b.startMs || tMs >= b.endMs) continue;
+      b.layer.draw(ctx, tMs);
+    }
+    ctx2d.restore();
+  }
+  return {
+    W,
+    H,
+    fps,
+    durationMs,
+    resolved,
+    renderFrame,
+    dispose() {
+      for (const b of bound) b.layer.dispose?.();
+    }
+  };
+}
+async function recordSceneSpec(opts) {
+  const { built } = opts;
+  const record = opts.record ?? recordScenes;
+  const composite = {
+    durationMs: built.durationMs,
+    draw: (ctx, t01) => built.renderFrame(ctx, t01 * built.durationMs)
+  };
+  return record([composite], {
+    audioStream: opts.audioStream,
+    width: built.W,
+    height: built.H,
+    fps: built.fps,
+    background: opts.background,
+    onProgress: opts.onProgress
+  });
+}
+
+// src/scene/audioLayers.ts
+function countInSchedule(opts) {
+  const beats = opts.beats ?? 4;
+  const accent = opts.accentDownbeat ?? true;
+  const beatSec = 60 / opts.bpm;
+  const events = [];
+  for (let i = 0; i < beats; i++) {
+    const isDownbeat = accent && i === 0;
+    events.push({
+      atSec: i * beatSec,
+      note: isDownbeat ? "C6" : "C5",
+      durSec: 0.05,
+      gain: isDownbeat ? 1 : 0.7,
+      kind: "count"
+    });
+  }
+  return events;
+}
+function countInLeadSec(opts) {
+  return (opts.beats ?? 4) * (60 / opts.bpm);
+}
+function clickTrackSchedule(opts) {
+  const beatSec = 60 / opts.bpm;
+  const bpb = opts.beatsPerBar ?? 4;
+  const start = opts.startSec ?? 0;
+  const events = [];
+  const n = Math.floor(opts.durationSec / beatSec);
+  for (let i = 0; i < n; i++) {
+    const isDownbeat = i % bpb === 0;
+    events.push({
+      atSec: start + i * beatSec,
+      note: isDownbeat ? "C6" : "C5",
+      durSec: 0.03,
+      gain: isDownbeat ? 0.6 : 0.4,
+      kind: "click"
+    });
+  }
+  return events;
+}
+function droneSchedule(opts) {
+  const gain = opts.gain ?? 0.15;
+  const events = [
+    { atSec: 0, note: opts.root, durSec: opts.durationSec, gain, kind: "drone" }
+  ];
+  if (opts.fifth ?? true) {
+    events.push({ atSec: 0, note: transposeFifth(opts.root), durSec: opts.durationSec, gain, kind: "drone" });
+  }
+  return events;
+}
+function transposeFifth(note) {
+  const m = /^([A-G])(#|b)?(\d)$/.exec(note);
+  if (!m) return note;
+  const order = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+  const pcMap = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+  let pc = pcMap[m[1]] + (m[2] === "#" ? 1 : m[2] === "b" ? -1 : 0);
+  let oct = parseInt(m[3], 10);
+  pc += 7;
+  if (pc >= 12) {
+    pc -= 12;
+    oct += 1;
+  }
+  return `${order[pc]}${oct}`;
+}
+function duckGainAt(windows, tSec, floor = 0.25, rampSec = 0.2) {
+  for (const w of windows) {
+    if (tSec >= w.startSec - rampSec && tSec <= w.endSec + rampSec) {
+      if (tSec < w.startSec) return lerpGain(1, floor, (tSec - (w.startSec - rampSec)) / rampSec);
+      if (tSec > w.endSec) return lerpGain(floor, 1, (tSec - w.endSec) / rampSec);
+      return floor;
+    }
+  }
+  return 1;
+}
+function lerpGain(a, b, t) {
+  const k = t < 0 ? 0 : t > 1 ? 1 : t;
+  return a + (b - a) * k;
+}
+function applySchedule(instrument, schedule, startTime) {
+  for (const ev of schedule) {
+    if (ev.note == null) continue;
+    instrument.triggerAttackRelease(
+      ev.note,
+      ev.durSec ?? 0.05,
+      startTime + ev.atSec,
+      ev.gain ?? 1
+    );
+  }
+  return schedule.length;
+}
+
+// src/scene/gate.ts
+var AV_TOLERANCE_MS = 60;
+async function runGate(input) {
+  const errors = [];
+  let resolved = [];
+  for (const seg of input.spec.timeline) {
+    for (const sl of seg.layers) {
+      const factory = getLayerFactory(sl.k);
+      if (!factory) {
+        errors.push({ check: "spec", message: `unknown layer "${sl.k}"` });
+        continue;
+      }
+      const errs = factory.validateProps(sl.p ?? {});
+      for (const e of errs) errors.push({ check: "spec", message: e });
+    }
+  }
+  try {
+    resolved = resolveTimeline(input.spec, input.totalSec);
+  } catch (e) {
+    errors.push({ check: "spec", message: `timeline: ${e.message}` });
+  }
+  if (resolved.length) {
+    const vis = visualTimelineMs(resolved);
+    if (!Number.isFinite(vis) || !Number.isFinite(input.audioMs)) {
+      errors.push({ check: "av-duration", message: "non-finite visual/audio duration" });
+    } else if (Math.abs(vis - input.audioMs) > AV_TOLERANCE_MS) {
+      errors.push({
+        check: "av-duration",
+        message: `|visual ${Math.round(vis)}ms \u2212 audio ${Math.round(input.audioMs)}ms| = ${Math.round(
+          Math.abs(vis - input.audioMs)
+        )}ms > ${AV_TOLERANCE_MS}ms`
+      });
+    }
+  }
+  for (const p of input.placements ?? []) {
+    if (!Number.isFinite(p.x) || !Number.isFinite(p.y)) {
+      errors.push({ check: "placement", message: `${p.label}: NaN/\u221E position` });
+      continue;
+    }
+    if (p.x < 0 || p.x > input.W || p.y < 0 || p.y > input.H) {
+      errors.push({ check: "placement", message: `${p.label}: (${p.x},${p.y}) outside ${input.W}\xD7${input.H}` });
+    }
+    if (input.safezone && p.mustBeSafe) {
+      const b = input.safeBox;
+      if (p.x < b.left || p.x > b.right || p.y < b.top || p.y > b.bottom) {
+        errors.push({ check: "placement", message: `${p.label}: outside safe box` });
+      }
+    }
+  }
+  const ready = input.fontsReady ? await input.fontsReady() : true;
+  if (!ready) errors.push({ check: "fonts", message: "fonts not loaded before first frame" });
+  if (input.output) {
+    const expectedFrames = Math.floor((input.fps ?? 30) * (input.audioMs / 1e3) * 0.5);
+    if (input.output.frames < expectedFrames) {
+      errors.push({
+        check: "output",
+        message: `only ${input.output.frames} frames (expected \u2265 ${expectedFrames})`
+      });
+    }
+    if (input.output.audioTracks < 1) {
+      errors.push({ check: "output", message: "no audio track in output" });
+    }
+    if (input.output.durationMs != null && Math.abs(input.output.durationMs - input.audioMs) > AV_TOLERANCE_MS) {
+      errors.push({
+        check: "output",
+        message: `output duration ${Math.round(input.output.durationMs)}ms vs audio ${Math.round(
+          input.audioMs
+        )}ms exceeds ${AV_TOLERANCE_MS}ms`
+      });
+    }
+  }
+  return errors;
+}
+async function assertGate(input) {
+  const errors = await runGate(input);
+  if (errors.length) {
+    throw new Error(
+      `pre-render gate failed (${errors.length}):
+` + errors.map((e) => `  [${e.check}] ${e.message}`).join("\n")
+    );
+  }
+}
+
+// src/scene/notationCamera.ts
+function mapBoxThroughLayout(base, b) {
+  const fx = base.rect.dw / base.src.w;
+  const fy = base.rect.dh / base.src.h;
+  return {
+    x: base.rect.dx + (b.x - base.src.x) * fx,
+    y: base.rect.dy + (b.y - base.src.y) * fy,
+    w: b.w * fx,
+    h: b.h * fy
+  };
+}
+function followSrcBox(rn, focusBoxCanvas) {
+  const px = focusBoxCanvas.w * (FOLLOW_PAD - 1) / 2;
+  const py = focusBoxCanvas.h * (FOLLOW_PAD - 1) / 2;
+  const src = {
+    x: Math.max(0, focusBoxCanvas.x - px),
+    y: Math.max(0, focusBoxCanvas.y - py),
+    w: focusBoxCanvas.w + 2 * px,
+    h: focusBoxCanvas.h + 2 * py
+  };
+  src.w = Math.min(src.w, rn.canvas.width - src.x);
+  src.h = Math.min(src.h, rn.canvas.height - src.y);
+  return src;
+}
+function cameraForFollow(rn, base, focusBoxCanvas, viewW, viewH) {
+  const src = followSrcBox(rn, focusBoxCanvas);
+  const world = mapBoxThroughLayout(base, src);
+  return frameRect(world, viewW, viewH, 0);
+}
+
+// src/scene/demos/fallingKeyboardDemo.ts
+function fallingKeyboardDemoSpec(opts = {}) {
+  const size = opts.size ?? [1080, 1920];
+  const leadMs = opts.leadMs ?? 2200;
+  const colorBy = opts.colorBy ?? "hand";
+  const range = opts.range ?? "auto";
+  return {
+    size,
+    theme: opts.theme ?? "rsr",
+    durationMode: "audio",
+    timeline: [
+      {
+        at: [0, "end"],
+        layers: [
+          { k: "background", p: { style: "ink" } },
+          // keyboard first so it publishes its layout before falling-notes inits;
+          // draw order: keyboard bed under the falling blocks would hide them, so
+          // we draw falling-notes ON TOP of the keyboard bed (falling listed last).
+          { k: "keyboard", p: { range, colorBy } },
+          { k: "falling-notes", p: { keyboard: true, colorBy, leadMs } }
+        ]
+      }
+    ]
+  };
+}
+async function fallingKeyboardDemoScore(xml, opts = {}) {
+  return scoreFromMusicXML(xml, opts.scoreOpts);
+}
+
+// src/scene/demos/promoCardsDemo.ts
+function promoCardsDemoSpec(opts = {}) {
+  const size = opts.size ?? [1080, 1920];
+  const totalSec = opts.totalSec ?? 12;
+  const hookSec = opts.hookSec ?? 2.2;
+  const revealSec = opts.revealSec ?? 4;
+  const ctaSec = opts.ctaSec ?? 3;
+  const hookLines = opts.hookLines ?? ["Can you", "name this?"];
+  const title = opts.title ?? "Claude Debussy";
+  const subtitle = opts.subtitle ?? "1862\u20131918";
+  const ctaLines = opts.ctaLines ?? ["Train your ear", "realeartrainer.com"];
+  const brand = opts.brand;
+  const ms = (s) => Math.round(s * 1e3);
+  const hookStart = 0;
+  const revealStart = hookSec;
+  const ctaStart = totalSec - ctaSec;
+  return {
+    size,
+    theme: opts.theme ?? "rsr",
+    durationMode: "fixed",
+    durationSec: totalSec,
+    timeline: [
+      // background spans the whole clip.
+      { at: [0, "end"], layers: [{ k: "background", p: { style: "paper" } }] },
+      // hook card.
+      {
+        at: [hookStart, hookSec],
+        layers: [{ k: "hook", p: { lines: hookLines, brand, startMs: ms(hookStart), durationMs: ms(hookSec) } }]
+      },
+      // reveal phase: audio-reactive spectrum + the portrait medallion.
+      {
+        at: [revealStart, revealStart + revealSec],
+        layers: [
+          { k: "spectrum", p: {} },
+          {
+            k: "portrait",
+            p: {
+              title,
+              subtitle,
+              url: opts.portraitUrl ?? null,
+              funFact: opts.funFact,
+              startMs: ms(revealStart),
+              durationMs: ms(revealSec)
+            }
+          }
+        ]
+      },
+      // end-card CTA.
+      {
+        at: [ctaStart, "end"],
+        layers: [{ k: "cta", p: { lines: ctaLines, startMs: ms(ctaStart), durationMs: ms(ctaSec) } }]
+      },
+      // persistent branding across the whole clip.
+      { at: [0, "end"], layers: [{ k: "branding", p: { logo: brand } }] }
+    ],
+    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,
+  duckGainAt,
+  easeIn,
+  easeInOut,
+  easeOut,
+  fallingKeyboardDemoScore,
+  fallingKeyboardDemoSpec,
+  fallingNotesFactory,
+  firstMeasureBox,
+  followBoxAt,
+  followSrcBox,
+  followWindowStart,
+  fracSlotPoint,
+  frameRect,
+  functionColor,
+  functionalHarmonyFactory,
+  getKeyboardLayout,
+  getLayerFactory,
+  getNotationEngraving,
+  harmonyDemoSpec,
+  highlightIntensity,
+  hookFactory,
+  identityCamera,
+  inRange,
+  invLerp,
+  isBlackKey,
+  kenBurns,
+  keyCenterX,
+  keyColumnWidth,
+  keyRect,
+  keySlot,
+  keyboardFactory,
+  keyboardLayout,
+  lerp,
+  lerpBox,
+  lerpCamera,
+  linear,
+  mapBoxThroughLayout,
+  mcqCardFactory,
+  mcqDemoSpec,
+  measureColumnsFromLayout,
+  measureCount,
+  measureSpanBox,
+  measureSpans,
+  timeToX as minimapTimeToX,
+  msPerBeat,
+  notationFactory,
+  notationLayout,
+  noteColor,
+  noteSetXRange,
+  parseKey,
+  parseTimeSig,
+  pcToSlot,
+  pitchAt,
+  pitchContourFactory,
+  pitchRange,
+  playheadLine,
+  portraitFactory,
+  progress01,
+  projectPoint,
+  promoCardsDemoSpec,
+  quizPhase,
+  rayEndpoints,
+  rayPointAt,
+  recordSceneSpec,
+  registerLayer,
+  registeredKeys,
+  resolveAnchor,
+  resolveKeyboardLayout,
+  resolveTimeline,
+  revealFactory,
+  revealProgress,
+  runGate,
+  safeGuidesFactory,
+  scoreFromMusicXML,
+  scorePitchSpan,
+  scrollCursorFactory,
+  sectionMinimapFactory,
+  setFollowLayoutProvider,
+  setKeyboardLayout,
+  setNotationEngraving,
+  slotAngle,
+  slotPc,
+  slotPoint,
+  spectrumFactory,
+  staffAnchor,
+  staffKeyboardRayFactory,
+  staffRayDemoSpec,
+  validateChordTrack,
+  validateQuiz,
+  validateSections,
+  visualTimelineMs,
+  whiteKeys,
+  worldToViewport
+};
+//# sourceMappingURL=index.js.map