@real-music-packages/web-core 0.22.0 → 0.23.0

package/dist/scene/index.js

@@ -1,3 +1,6 @@
+import {
+  intervalBySemitones
+} from "../chunk-N56UTMWA.js";
 import {
   ctaScene,
   drawSafeGuides,
@@ -3003,6 +3006,657 @@ var sectionMinimapFactory = {
   }
 };
 
+// src/scene/layers/beatPulse.ts
+var DEFAULTS = {
+  styles: ["bloom"],
+  intensity: 0.42,
+  attackMs: 0,
+  decayMs: 170,
+  blend: "source-over"
+};
+function envAt(tMs, onsetMs, attackMs, decayMs) {
+  const dt = tMs - onsetMs;
+  if (dt < 0) return 0;
+  if (dt < attackMs) return attackMs <= 0 ? 1 : dt / attackMs;
+  return Math.exp(-(dt - attackMs) / decayMs);
+}
+function pulseAt(onsetsMs, tMs, attackMs = DEFAULTS.attackMs, decayMs = DEFAULTS.decayMs) {
+  let p = 0;
+  for (let i = onsetsMs.length - 1; i >= 0; i--) {
+    const on = onsetsMs[i];
+    if (on > tMs) continue;
+    const e = envAt(tMs, on, attackMs, decayMs);
+    if (e > p) p = e;
+    if (tMs - on > attackMs + decayMs * 6) break;
+  }
+  return p;
+}
+function rgba2(hex, a) {
+  const h = hex.replace("#", "");
+  const n = h.length === 3 ? parseInt(h.split("").map((c) => c + c).join(""), 16) : parseInt(h, 16);
+  const r = n >> 16 & 255, g = n >> 8 & 255, b = n & 255;
+  return `rgba(${r},${g},${b},${a})`;
+}
+function beatPulseLayer() {
+  let onsets = [];
+  let styles = DEFAULTS.styles;
+  let intensity = DEFAULTS.intensity;
+  let attackMs = DEFAULTS.attackMs;
+  let decayMs = DEFAULTS.decayMs;
+  let color;
+  let blend = DEFAULTS.blend;
+  return {
+    key: "beat-pulse",
+    init(ctx, props) {
+      onsets = props.onsetsMs ?? (ctx.score ? distinctOnsets(ctx.score.notes) : []);
+      onsets = [...onsets].sort((a, b) => a - b);
+      styles = props.styles ?? DEFAULTS.styles;
+      intensity = props.intensity ?? DEFAULTS.intensity;
+      attackMs = props.attackMs ?? DEFAULTS.attackMs;
+      decayMs = props.decayMs ?? DEFAULTS.decayMs;
+      color = props.color;
+      blend = props.blend ?? DEFAULTS.blend;
+    },
+    draw(ctx, tMs) {
+      if (!onsets.length) return;
+      const p = pulseAt(onsets, tMs, attackMs, decayMs);
+      if (p <= 4e-3) return;
+      const c = ctx.ctx2d;
+      const W = ctx.W, H = ctx.H;
+      const col = color ?? ctx.theme.accent;
+      const a = intensity * p;
+      c.save();
+      c.globalCompositeOperation = blend;
+      if (styles.includes("bloom")) {
+        const cx = W / 2, cy = H * 0.46;
+        const rad = Math.max(W, H) * (0.3 + 0.1 * p);
+        const g = c.createRadialGradient(cx, cy, 0, cx, cy, rad);
+        g.addColorStop(0, rgba2(col, a * 0.55));
+        g.addColorStop(0.55, rgba2(col, a * 0.18));
+        g.addColorStop(1, rgba2(col, 0));
+        c.fillStyle = g;
+        c.fillRect(0, 0, W, H);
+      }
+      if (styles.includes("vignette")) {
+        const cx = W / 2, cy = H / 2;
+        const inner = Math.min(W, H) * 0.42;
+        const outer = Math.max(W, H) * 0.72;
+        const g = c.createRadialGradient(cx, cy, inner, cx, cy, outer);
+        g.addColorStop(0, rgba2(col, 0));
+        g.addColorStop(1, rgba2(col, a * 0.6));
+        c.fillStyle = g;
+        c.fillRect(0, 0, W, H);
+      }
+      c.restore();
+    }
+  };
+}
+var beatPulseFactory = {
+  key: "beat-pulse",
+  create: beatPulseLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["beat-pulse: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.onsetsMs != null && (!Array.isArray(p.onsetsMs) || p.onsetsMs.some((x) => typeof x !== "number")))
+      errs.push("beat-pulse.onsetsMs must be a number[]");
+    if (p.styles != null) {
+      if (!Array.isArray(p.styles)) errs.push("beat-pulse.styles must be an array");
+      else if (p.styles.some((s) => s !== "bloom" && s !== "vignette"))
+        errs.push('beat-pulse.styles items must be "bloom" | "vignette"');
+    }
+    if (p.intensity != null && (typeof p.intensity !== "number" || p.intensity < 0 || p.intensity > 1))
+      errs.push("beat-pulse.intensity must be in [0,1]");
+    if (p.attackMs != null && (typeof p.attackMs !== "number" || p.attackMs < 0))
+      errs.push("beat-pulse.attackMs must be a number >= 0");
+    if (p.decayMs != null && (typeof p.decayMs !== "number" || p.decayMs <= 0))
+      errs.push("beat-pulse.decayMs must be a positive number");
+    if (p.color != null && typeof p.color !== "string") errs.push("beat-pulse.color must be a string");
+    if (p.blend != null && p.blend !== "source-over" && p.blend !== "lighter")
+      errs.push('beat-pulse.blend must be "source-over" | "lighter"');
+    return errs;
+  }
+};
+
+// src/scene/layers/chordRibbon.ts
+var DEFAULTS2 = { pxPerMs: 0.06, playheadFrac: 0.32, height: 84, showFunction: true };
+function rgba3(hex, a) {
+  const h = hex.replace("#", "");
+  const n = h.length === 3 ? parseInt(h.split("").map((c) => c + c).join(""), 16) : parseInt(h, 16);
+  return `rgba(${n >> 16 & 255},${n >> 8 & 255},${n & 255},${a})`;
+}
+function roundRectPath(c, x, y, w, h, r) {
+  if (typeof c.roundRect === "function") {
+    c.beginPath();
+    c.roundRect(x, y, w, h, r);
+    return;
+  }
+  const rr = Math.min(r, w / 2, h / 2);
+  c.beginPath();
+  c.moveTo(x + rr, y);
+  c.arcTo(x + w, y, x + w, y + h, rr);
+  c.arcTo(x + w, y + h, x, y + h, rr);
+  c.arcTo(x, y + h, x, y, rr);
+  c.arcTo(x, y, x + w, y, rr);
+  c.closePath();
+}
+function chordRibbonLayer() {
+  let track = [];
+  let pxPerMs = DEFAULTS2.pxPerMs;
+  let playheadFrac = DEFAULTS2.playheadFrac;
+  let yProp;
+  let height = DEFAULTS2.height;
+  let showFunction = DEFAULTS2.showFunction;
+  let colors = DEFAULT_FUNCTION_COLORS;
+  return {
+    key: "chord-ribbon",
+    init(_ctx, props) {
+      track = (props.chordTrack ?? []).slice().sort((a, b) => a.startMs - b.startMs);
+      pxPerMs = props.pxPerMs ?? DEFAULTS2.pxPerMs;
+      playheadFrac = props.playheadFrac ?? DEFAULTS2.playheadFrac;
+      yProp = props.y;
+      height = props.height ?? DEFAULTS2.height;
+      showFunction = props.showFunction ?? DEFAULTS2.showFunction;
+      colors = props.colors ?? DEFAULT_FUNCTION_COLORS;
+    },
+    draw(ctx, tMs) {
+      if (!track.length) return;
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const left = sb.left;
+      const right = sb.right;
+      const span = right - left;
+      const playX = left + span * playheadFrac;
+      const y = yProp ?? sb.bottom - 260;
+      const h = height;
+      const pad = 8;
+      c.save();
+      c.beginPath();
+      c.rect(left, y - pad, span, h + pad * 2);
+      c.clip();
+      for (const s of track) {
+        const x0 = playX + (s.startMs - tMs) * pxPerMs;
+        const w = Math.max(36, (s.endMs - s.startMs) * pxPerMs - 6);
+        if (x0 + w < left || x0 > right) continue;
+        const active = tMs >= s.startMs && tMs < s.endMs;
+        const played = tMs >= s.endMs;
+        const fnCol = showFunction ? functionColor(s.fn, colors) : ctx.theme.accent;
+        const chipAlpha = active ? 0.95 : played ? 0.28 : 0.55;
+        roundRectPath(c, x0, y, w, h, 14);
+        c.fillStyle = rgba3(fnCol, chipAlpha);
+        c.fill();
+        if (active) {
+          c.lineWidth = 3;
+          c.strokeStyle = rgba3(ctx.theme.paper ?? "#ffffff", 0.9);
+          c.stroke();
+        }
+        const label = s.label ?? "";
+        if (label) {
+          c.fillStyle = rgba3(ctx.theme.paper ?? "#ffffff", active ? 1 : 0.85);
+          c.font = `${active ? 700 : 600} ${Math.round(h * 0.42)}px ${ctx.theme.fontDisplay}`;
+          c.textAlign = "center";
+          c.textBaseline = "middle";
+          c.fillText(label, x0 + w / 2, y + h / 2);
+        }
+      }
+      c.strokeStyle = rgba3(ctx.theme.gold ?? "#d4af37", 0.95);
+      c.lineWidth = 3;
+      c.beginPath();
+      c.moveTo(playX, y - pad);
+      c.lineTo(playX, y + h + pad);
+      c.stroke();
+      c.restore();
+    }
+  };
+}
+var chordRibbonFactory = {
+  key: "chord-ribbon",
+  create: chordRibbonLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["chord-ribbon: props must be an object"];
+    const p = props;
+    const errs = validateChordTrack(p.chordTrack);
+    if (p.pxPerMs != null && (typeof p.pxPerMs !== "number" || p.pxPerMs <= 0))
+      errs.push("chord-ribbon.pxPerMs must be a positive number");
+    if (p.playheadFrac != null && (typeof p.playheadFrac !== "number" || p.playheadFrac < 0 || p.playheadFrac > 1))
+      errs.push("chord-ribbon.playheadFrac must be in [0,1]");
+    if (p.y != null && typeof p.y !== "number") errs.push("chord-ribbon.y must be a number");
+    if (p.height != null && (typeof p.height !== "number" || p.height <= 0))
+      errs.push("chord-ribbon.height must be a positive number");
+    if (p.showFunction != null && typeof p.showFunction !== "boolean")
+      errs.push("chord-ribbon.showFunction must be a boolean");
+    return errs;
+  }
+};
+
+// src/scene/layers/progressRing.ts
+var DEFAULTS3 = { radius: 46, thickness: 9, showCountdown: false };
+function rgba4(hex, a) {
+  const h = hex.replace("#", "");
+  const n = h.length === 3 ? parseInt(h.split("").map((c) => c + c).join(""), 16) : parseInt(h, 16);
+  return `rgba(${n >> 16 & 255},${n >> 8 & 255},${n & 255},${a})`;
+}
+function progressRingLayer() {
+  let totalMsProp;
+  let radius = DEFAULTS3.radius;
+  let thickness = DEFAULTS3.thickness;
+  let cxProp;
+  let cyProp;
+  let color;
+  let trackColor;
+  let showCountdown = DEFAULTS3.showCountdown;
+  return {
+    key: "progress-ring",
+    init(ctx, props) {
+      totalMsProp = props.totalMs ?? ctx.score?.durationMs;
+      radius = props.radius ?? DEFAULTS3.radius;
+      thickness = props.thickness ?? DEFAULTS3.thickness;
+      cxProp = props.cx;
+      cyProp = props.cy;
+      color = props.color;
+      trackColor = props.trackColor;
+      showCountdown = props.showCountdown ?? DEFAULTS3.showCountdown;
+    },
+    draw(ctx, tMs) {
+      const total = totalMsProp;
+      if (!total || total <= 0) return;
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const cx = cxProp ?? sb.right - radius - 16;
+      const cy = cyProp ?? sb.top + radius + 16;
+      const p = Math.min(1, Math.max(0, tMs / total));
+      const start = -Math.PI / 2;
+      const end = start + p * Math.PI * 2;
+      const fill = color ?? ctx.theme.gold;
+      const track = trackColor ?? rgba4(ctx.theme.paper, 0.22);
+      c.save();
+      c.lineCap = "round";
+      c.beginPath();
+      c.arc(cx, cy, radius, 0, Math.PI * 2);
+      c.strokeStyle = track;
+      c.lineWidth = thickness;
+      c.stroke();
+      if (p > 0) {
+        c.beginPath();
+        c.arc(cx, cy, radius, start, end);
+        c.strokeStyle = fill;
+        c.lineWidth = thickness;
+        c.stroke();
+      }
+      if (showCountdown) {
+        const remain = Math.max(0, Math.ceil((total - tMs) / 1e3));
+        c.fillStyle = ctx.theme.paper;
+        c.font = `700 ${Math.round(radius * 0.7)}px ${ctx.theme.fontDisplay}`;
+        c.textAlign = "center";
+        c.textBaseline = "middle";
+        c.fillText(String(remain), cx, cy + 1);
+      }
+      c.restore();
+    }
+  };
+}
+var progressRingFactory = {
+  key: "progress-ring",
+  create: progressRingLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["progress-ring: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.totalMs != null && (typeof p.totalMs !== "number" || p.totalMs <= 0))
+      errs.push("progress-ring.totalMs must be a positive number");
+    if (p.radius != null && (typeof p.radius !== "number" || p.radius <= 0))
+      errs.push("progress-ring.radius must be a positive number");
+    if (p.thickness != null && (typeof p.thickness !== "number" || p.thickness <= 0))
+      errs.push("progress-ring.thickness must be a positive number");
+    if (p.cx != null && typeof p.cx !== "number") errs.push("progress-ring.cx must be a number");
+    if (p.cy != null && typeof p.cy !== "number") errs.push("progress-ring.cy must be a number");
+    if (p.color != null && typeof p.color !== "string") errs.push("progress-ring.color must be a string");
+    if (p.trackColor != null && typeof p.trackColor !== "string") errs.push("progress-ring.trackColor must be a string");
+    if (p.showCountdown != null && typeof p.showCountdown !== "boolean")
+      errs.push("progress-ring.showCountdown must be a boolean");
+    return errs;
+  }
+};
+
+// src/scene/layers/radialSpectrum.ts
+var SPEC_BARS2 = 64;
+function clamp013(x) {
+  return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+function lerpHex2(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 syntheticMagnitude2(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 binByteFreq2(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, cnt = 0;
+    for (let i = i0; i < i1 && i < freq.length; i++) {
+      sum += freq[i];
+      cnt++;
+    }
+    let m = cnt ? sum / cnt / 255 : 0;
+    m = Math.pow(m, 0.78);
+    out.push(m);
+  }
+  return out;
+}
+function radialSpectrumLayer() {
+  let n = SPEC_BARS2;
+  let cxFrac = 0.5, cyFrac = 0.42, innerFrac = 0.2, maxLenFrac = 0.13;
+  let colorLow, 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] = clamp013(src[Math.min(src.length - 1, b)] ?? 0);
+      return out;
+    }
+    const tSec = tMs / 1e3;
+    return Array.from({ length: n }, (_, b) => clamp013(syntheticMagnitude2(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 binByteFreq2(bf, n);
+    return null;
+  }
+  return {
+    key: "radial-spectrum",
+    init(_ctx, props) {
+      n = props.bars ?? SPEC_BARS2;
+      cxFrac = props.cxFrac ?? 0.5;
+      cyFrac = props.cyFrac ?? 0.42;
+      innerFrac = props.innerFrac ?? 0.2;
+      maxLenFrac = props.maxLenFrac ?? 0.13;
+      colorLow = props.colorLow;
+      colorHigh = props.colorHigh;
+      levelsFn = props.levelsFn;
+    },
+    draw(ctx, tMs) {
+      const c = ctx.ctx2d;
+      const W = ctx.W, H = ctx.H;
+      const cx = W * cxFrac, cy = H * cyFrac;
+      const unit = Math.min(W, H);
+      const inner = unit * innerFrac;
+      const maxLen = unit * maxLenFrac;
+      const lo = colorLow ?? ctx.theme.accent;
+      const hi = colorHigh ?? ctx.theme.gold;
+      const mags = magnitudesAt(ctx, tMs);
+      const barW = Math.max(3, 2 * Math.PI * inner / n * 0.6);
+      c.save();
+      c.lineCap = "round";
+      for (let b = 0; b < n; b++) {
+        const m = mags[b];
+        const ang = b / n * Math.PI * 2 - Math.PI / 2;
+        const len = Math.max(barW * 0.5, m * maxLen);
+        const x0 = cx + Math.cos(ang) * inner;
+        const y0 = cy + Math.sin(ang) * inner;
+        const x1 = cx + Math.cos(ang) * (inner + len);
+        const y1 = cy + Math.sin(ang) * (inner + len);
+        c.strokeStyle = lerpHex2(lo, hi, m);
+        c.lineWidth = barW;
+        c.beginPath();
+        c.moveTo(x0, y0);
+        c.lineTo(x1, y1);
+        c.stroke();
+      }
+      c.restore();
+    }
+  };
+}
+var radialSpectrumFactory = {
+  key: "radial-spectrum",
+  create: radialSpectrumLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["radial-spectrum: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.bars != null && (typeof p.bars !== "number" || p.bars < 6)) errs.push("radial-spectrum.bars must be a number >= 6");
+    for (const k of ["cxFrac", "cyFrac", "innerFrac", "maxLenFrac"]) {
+      if (p[k] != null && (typeof p[k] !== "number" || p[k] < 0 || p[k] > 1))
+        errs.push(`radial-spectrum.${k} must be in [0,1]`);
+    }
+    if (p.colorLow != null && typeof p.colorLow !== "string") errs.push("radial-spectrum.colorLow must be a string");
+    if (p.colorHigh != null && typeof p.colorHigh !== "string") errs.push("radial-spectrum.colorHigh must be a string");
+    if (p.levelsFn != null && typeof p.levelsFn !== "function") errs.push("radial-spectrum.levelsFn must be a function");
+    return errs;
+  }
+};
+
+// src/scene/layers/karaokeCaption.ts
+var DEFAULTS4 = { centerFrac: 0.5, fontPx: 64, activeHoldMs: 320 };
+function rgba5(hex, a) {
+  const h = hex.replace("#", "");
+  const n = h.length === 3 ? parseInt(h.split("").map((ch) => ch + ch).join(""), 16) : parseInt(h, 16);
+  return `rgba(${n >> 16 & 255},${n >> 8 & 255},${n & 255},${a})`;
+}
+function karaokeCaptionLayer() {
+  let words = [];
+  let centerFrac = DEFAULTS4.centerFrac;
+  let fontPx = DEFAULTS4.fontPx;
+  let sungColor;
+  let upcomingColor;
+  let activeColor;
+  let activeHoldMs = DEFAULTS4.activeHoldMs;
+  return {
+    key: "karaoke-caption",
+    init(_ctx, props) {
+      words = (props.words ?? []).slice().sort((a, b) => a.atMs - b.atMs);
+      centerFrac = props.centerFrac ?? DEFAULTS4.centerFrac;
+      fontPx = props.fontPx ?? DEFAULTS4.fontPx;
+      sungColor = props.sungColor;
+      upcomingColor = props.upcomingColor;
+      activeColor = props.activeColor;
+      activeHoldMs = props.activeHoldMs ?? DEFAULTS4.activeHoldMs;
+    },
+    draw(ctx, tMs) {
+      if (!words.length) return;
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      c.save();
+      c.font = `700 ${fontPx}px ${ctx.theme.fontDisplay}`;
+      c.textBaseline = "middle";
+      c.textAlign = "left";
+      const spaceW = c.measureText(" ").width;
+      const maxW = sb.w;
+      const lines = [];
+      let cur = { items: [], width: 0 };
+      for (const w of words) {
+        const ww = c.measureText(w.text).width;
+        const add = cur.items.length ? spaceW + ww : ww;
+        if (cur.items.length && cur.width + add > maxW) {
+          lines.push(cur);
+          cur = { items: [], width: 0 };
+        }
+        cur.items.push({ w, width: ww });
+        cur.width += cur.items.length === 1 ? ww : spaceW + ww;
+      }
+      if (cur.items.length) lines.push(cur);
+      const lineH = fontPx * 1.3;
+      const totalH = lines.length * lineH;
+      let y = H_center(ctx, centerFrac) - totalH / 2 + lineH / 2;
+      const sung = sungColor ?? ctx.theme.ink;
+      const upcoming = upcomingColor ?? rgba5(ctx.theme.ink, 0.28);
+      const active = activeColor ?? ctx.theme.accent;
+      for (const line of lines) {
+        let x = sb.left + (maxW - line.width) / 2;
+        for (const it of line.items) {
+          const lit = tMs >= it.w.atMs;
+          const fresh = lit && tMs - it.w.atMs < activeHoldMs;
+          c.fillStyle = fresh ? active : lit ? sung : upcoming;
+          c.fillText(it.w.text, x, y);
+          x += it.width + spaceW;
+        }
+        y += lineH;
+      }
+      c.restore();
+    }
+  };
+}
+function H_center(ctx, frac) {
+  return ctx.H * frac;
+}
+var karaokeCaptionFactory = {
+  key: "karaoke-caption",
+  create: karaokeCaptionLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["karaoke-caption: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (!Array.isArray(p.words)) {
+      errs.push("karaoke-caption.words must be an array of {text, atMs}");
+    } else {
+      p.words.forEach((raw, i) => {
+        const w = raw;
+        if (typeof w?.text !== "string" || typeof w?.atMs !== "number")
+          errs.push(`karaoke-caption.words[${i}] must be {text:string, atMs:number}`);
+      });
+    }
+    if (p.centerFrac != null && (typeof p.centerFrac !== "number" || p.centerFrac < 0 || p.centerFrac > 1))
+      errs.push("karaoke-caption.centerFrac must be in [0,1]");
+    if (p.fontPx != null && (typeof p.fontPx !== "number" || p.fontPx <= 0))
+      errs.push("karaoke-caption.fontPx must be a positive number");
+    if (p.activeHoldMs != null && (typeof p.activeHoldMs !== "number" || p.activeHoldMs < 0))
+      errs.push("karaoke-caption.activeHoldMs must be a number >= 0");
+    for (const k of ["sungColor", "upcomingColor", "activeColor"]) {
+      if (p[k] != null && typeof p[k] !== "string") errs.push(`karaoke-caption.${k} must be a string`);
+    }
+    return errs;
+  }
+};
+
+// src/scene/layers/intervalArcs.ts
+function intervalLabel(deltaSemis) {
+  const semi = Math.abs(deltaSemis);
+  const within = semi % 12;
+  if (semi > 0 && within === 0) return "P8";
+  return intervalBySemitones(within)?.label ?? `${within}`;
+}
+function intervalArcsLayer() {
+  let topProp;
+  let heightProp;
+  let upColor;
+  let downColor;
+  let showLabels = true;
+  let fontPx = 30;
+  let dotRadius = 9;
+  let points = [];
+  return {
+    key: "interval-arcs",
+    init(ctx, props) {
+      topProp = props.top;
+      heightProp = props.height;
+      upColor = props.upColor;
+      downColor = props.downColor;
+      showLabels = props.showLabels ?? true;
+      fontPx = props.fontPx ?? 30;
+      dotRadius = props.dotRadius ?? 9;
+      points = contourPoints(ctx.score?.notes ?? []);
+    },
+    draw(ctx, tMs) {
+      if (points.length < 2) return;
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const top = topProp ?? sb.top + sb.h * 0.18;
+      const height = heightProp ?? sb.h * 0.34;
+      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 up = upColor ?? ctx.theme.accent;
+      const down = downColor ?? ctx.theme.sepia;
+      c.save();
+      c.lineCap = "round";
+      c.font = `700 ${fontPx}px ${ctx.theme.fontDisplay}`;
+      c.textAlign = "center";
+      c.textBaseline = "bottom";
+      for (let i = 1; i < points.length; i++) {
+        const b = points[i];
+        if (b.tMs > tMs) break;
+        const a = points[i - 1];
+        const pa = projectPoint(plot, a.tMs, a.pitchMidi);
+        const pb = projectPoint(plot, b.tMs, b.pitchMidi);
+        const delta = b.pitchMidi - a.pitchMidi;
+        const ascending = delta >= 0;
+        const col = ascending ? up : down;
+        const midX = (pa.x + pb.x) / 2;
+        const bow = Math.min(70, Math.max(28, Math.abs(pb.x - pa.x) * 0.4));
+        const ctrlY = Math.min(pa.y, pb.y) - bow;
+        c.strokeStyle = col;
+        c.lineWidth = 4;
+        c.globalAlpha = 0.9;
+        c.beginPath();
+        c.moveTo(pa.x, pa.y);
+        c.quadraticCurveTo(midX, ctrlY, pb.x, pb.y);
+        c.stroke();
+        if (showLabels && delta !== 0) {
+          c.globalAlpha = 1;
+          c.fillStyle = col;
+          c.fillText(intervalLabel(delta), midX, ctrlY - 2);
+        }
+      }
+      c.globalAlpha = 1;
+      c.fillStyle = ctx.theme.ink;
+      for (const p of points) {
+        if (p.tMs > tMs) break;
+        const pt = projectPoint(plot, p.tMs, p.pitchMidi);
+        c.beginPath();
+        c.arc(pt.x, pt.y, dotRadius, 0, Math.PI * 2);
+        c.fill();
+      }
+      c.restore();
+    }
+  };
+}
+var intervalArcsFactory = {
+  key: "interval-arcs",
+  create: intervalArcsLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["interval-arcs: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.top != null && typeof p.top !== "number") errs.push("interval-arcs.top must be a number");
+    if (p.height != null && (typeof p.height !== "number" || p.height <= 0))
+      errs.push("interval-arcs.height must be a positive number");
+    if (p.upColor != null && typeof p.upColor !== "string") errs.push("interval-arcs.upColor must be a string");
+    if (p.downColor != null && typeof p.downColor !== "string") errs.push("interval-arcs.downColor must be a string");
+    if (p.showLabels != null && typeof p.showLabels !== "boolean") errs.push("interval-arcs.showLabels must be a boolean");
+    if (p.fontPx != null && (typeof p.fontPx !== "number" || p.fontPx <= 0)) errs.push("interval-arcs.fontPx must be a positive number");
+    if (p.dotRadius != null && (typeof p.dotRadius !== "number" || p.dotRadius <= 0)) errs.push("interval-arcs.dotRadius must be a positive number");
+    return errs;
+  }
+};
+
 // src/scene/registry.ts
 var REGISTRY = /* @__PURE__ */ new Map();
 function registerLayer(factory) {
@@ -3035,6 +3689,12 @@ registerLayer(mcqCardFactory);
 registerLayer(circleOfFifthsFactory);
 registerLayer(pitchContourFactory);
 registerLayer(sectionMinimapFactory);
+registerLayer(beatPulseFactory);
+registerLayer(chordRibbonFactory);
+registerLayer(progressRingFactory);
+registerLayer(radialSpectrumFactory);
+registerLayer(karaokeCaptionFactory);
+registerLayer(intervalArcsFactory);
 
 // src/scene/audioLayers.ts
 function countInSchedule(opts) {
@@ -3187,7 +3847,11 @@ var SCREEN_PINNED_KEYS = /* @__PURE__ */ new Set([
   "reveal",
   "portrait",
   "safe-guides",
-  "mcq-card"
+  "mcq-card",
+  "beat-pulse",
+  "chord-ribbon",
+  "progress-ring",
+  "karaoke-caption"
 ]);
 function defaultBufferFactory() {
   const g = globalThis;
@@ -3786,12 +4450,14 @@ export {
   ballX,
   beatGrid,
   beatPhase,
+  beatPulseFactory,
   blackKeys,
   bpmOf,
   brandingFactory,
   buildScene,
   cameraForFollow,
   cameraTransform,
+  chordRibbonFactory,
   circleOfFifthsDemoSpec,
   circleOfFifthsFactory,
   clamp,
@@ -3840,8 +4506,10 @@ export {
   hookFactory,
   identityCamera,
   inRange,
+  intervalArcsFactory,
   invLerp,
   isBlackKey,
+  karaokeCaptionFactory,
   kenBurns,
   keyCenterX,
   keyColumnWidth,
@@ -3876,9 +4544,12 @@ export {
   playheadLine,
   portraitFactory,
   progress01,
+  progressRingFactory,
   projectPoint,
   promoCardsDemoSpec,
+  pulseAt,
   quizPhase,
+  radialSpectrumFactory,
   rayEndpoints,
   rayPointAt,
   recordSceneSpec,