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

package/dist/scene/index.js

@@ -0,0 +1,2008 @@
+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 msPerBeat = 6e4 / bpm;
+  return (wholeNotes) => wholeNotes * BEATS_PER_WHOLE_NOTE * msPerBeat;
+}
+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. Call setupHeadlessDom() first (Node), 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/headless.ts
+var installed = false;
+async function setupHeadlessDom() {
+  if (installed) return;
+  const g = globalThis;
+  if (typeof g.document !== "undefined" && typeof g.window !== "undefined") {
+    ensureFakeContext(g.window);
+    installed = true;
+    return;
+  }
+  const { JSDOM } = await import("jsdom");
+  const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>", {
+    pretendToBeVisual: true
+  });
+  const { window } = dom;
+  ensureFakeContext(window);
+  g.window = window;
+  g.document = window.document;
+  try {
+    g.navigator = window.navigator;
+  } catch {
+  }
+  g.HTMLElement = window.HTMLElement;
+  g.Node = window.Node;
+  g.DOMParser = window.DOMParser;
+  g.XMLSerializer = window.XMLSerializer;
+  g.requestAnimationFrame = (cb) => setTimeout(() => cb(Date.now()), 0);
+  g.cancelAnimationFrame = () => {
+  };
+  installed = true;
+}
+function ensureFakeContext(window) {
+  const proto = window.HTMLCanvasElement?.prototype;
+  if (!proto) return;
+  const fakeCtx = makeFakeContext();
+  proto.getContext = function() {
+    return fakeCtx;
+  };
+}
+function makeFakeContext() {
+  return {
+    font: "10px Arial",
+    fillStyle: "#000",
+    strokeStyle: "#000",
+    lineWidth: 1,
+    textAlign: "left",
+    textBaseline: "alphabetic",
+    globalAlpha: 1,
+    measureText: (s) => ({
+      width: (s ? s.length : 0) * 6,
+      actualBoundingBoxAscent: 8,
+      actualBoundingBoxDescent: 2
+    }),
+    save() {
+    },
+    restore() {
+    },
+    beginPath() {
+    },
+    closePath() {
+    },
+    moveTo() {
+    },
+    lineTo() {
+    },
+    bezierCurveTo() {
+    },
+    quadraticCurveTo() {
+    },
+    arc() {
+    },
+    rect() {
+    },
+    fill() {
+    },
+    stroke() {
+    },
+    fillRect() {
+    },
+    clearRect() {
+    },
+    fillText() {
+    },
+    strokeText() {
+    },
+    translate() {
+    },
+    rotate() {
+    },
+    scale() {
+    },
+    setTransform() {
+    },
+    transform() {
+    },
+    drawImage() {
+    },
+    clip() {
+    },
+    createLinearGradient: () => ({ addColorStop() {
+    } }),
+    getImageData: () => ({ data: new Uint8ClampedArray(4) })
+  };
+}
+
+// src/scene/math.ts
+var clamp = (x, lo, hi) => x < lo ? lo : x > hi ? hi : x;
+var lerp = (a, b, t) => a + (b - a) * t;
+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/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);
+
+// 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"
+]);
+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/highlight.ts
+function highlightIntensity(region, tMs) {
+  const fade = region.fadeMs ?? 120;
+  if (tMs <= region.inMs - fade || tMs >= region.outMs + fade) return 0;
+  const rampIn = invLerp(region.inMs - fade, region.inMs, tMs);
+  const rampOut = 1 - invLerp(region.outMs, region.outMs + fade, tMs);
+  return clamp(Math.min(rampIn, rampOut), 0, 1);
+}
+function noteSetXRange(onsetsMs, windowMs, timeToX) {
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const on of onsetsMs) {
+    if (on < windowMs[0] || on > windowMs[1]) continue;
+    const x = timeToX(on);
+    if (x < lo) lo = x;
+    if (x > hi) hi = x;
+  }
+  if (lo === Infinity) return null;
+  return { x: lo, w: Math.max(0, hi - lo) };
+}
+function drawHighlight(ctx, region, tMs, accent) {
+  const a = highlightIntensity(region, tMs);
+  if (a <= 0) return;
+  ctx.save();
+  ctx.globalAlpha = a * 0.35;
+  ctx.fillStyle = region.color ?? accent;
+  ctx.fillRect(region.x, region.y, region.w, region.h);
+  ctx.restore();
+}
+
+// src/scene/audioLayers.ts
+function countInSchedule(opts) {
+  const beats = opts.beats ?? 4;
+  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" }
+  };
+}
+export {
+  FOLLOW_BARS,
+  FOLLOW_PAD,
+  PIANO_HIGH,
+  PIANO_LOW,
+  activeCue,
+  applySchedule,
+  applyToContext,
+  assertGate,
+  blackKeys,
+  brandingFactory,
+  buildScene,
+  cameraForFollow,
+  cameraTransform,
+  clamp,
+  clickTrackSchedule,
+  countInLeadSec,
+  countInSchedule,
+  cropAroundBox,
+  ctaFactory,
+  cubicEaseInOut,
+  cueOpacity,
+  drawCaption,
+  drawHighlight,
+  droneSchedule,
+  duckGainAt,
+  easeIn,
+  easeInOut,
+  easeOut,
+  fallingKeyboardDemoScore,
+  fallingKeyboardDemoSpec,
+  fallingNotesFactory,
+  firstMeasureBox,
+  followBoxAt,
+  followSrcBox,
+  followWindowStart,
+  frameRect,
+  getKeyboardLayout,
+  getLayerFactory,
+  getNotationEngraving,
+  highlightIntensity,
+  hookFactory,
+  identityCamera,
+  inRange,
+  invLerp,
+  isBlackKey,
+  kenBurns,
+  keyCenterX,
+  keyColumnWidth,
+  keyRect,
+  keyboardFactory,
+  keyboardLayout,
+  lerp,
+  lerpBox,
+  lerpCamera,
+  linear,
+  mapBoxThroughLayout,
+  measureColumnsFromLayout,
+  measureCount,
+  measureSpanBox,
+  notationFactory,
+  notationLayout,
+  noteColor,
+  noteSetXRange,
+  playheadLine,
+  portraitFactory,
+  promoCardsDemoSpec,
+  recordSceneSpec,
+  registerLayer,
+  registeredKeys,
+  resolveAnchor,
+  resolveKeyboardLayout,
+  resolveTimeline,
+  revealFactory,
+  runGate,
+  safeGuidesFactory,
+  scoreFromMusicXML,
+  scorePitchSpan,
+  scrollCursorFactory,
+  setFollowLayoutProvider,
+  setKeyboardLayout,
+  setNotationEngraving,
+  setupHeadlessDom,
+  spectrumFactory,
+  visualTimelineMs,
+  whiteKeys,
+  worldToViewport
+};
+//# sourceMappingURL=index.js.map