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

package/dist/scene/index.js

@@ -1,6 +1,10 @@
 import {
   intervalBySemitones
 } from "../chunk-N56UTMWA.js";
+import {
+  noteNameToIndex,
+  pitchClass
+} from "../chunk-25RUSM2X.js";
 import {
   ctaScene,
   drawSafeGuides,
@@ -3657,6 +3661,415 @@ var intervalArcsFactory = {
   }
 };
 
+// src/scene/layers/kineticText.ts
+var DEFAULTS5 = { mode: "word-pop", startMs: 0, revealMs: 1400, fontPx: 88, centerFrac: 0.42, cursor: true };
+function clamp014(x) {
+  return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+function wrap2(c, words, maxW) {
+  const lines = [];
+  let cur = [];
+  let curW = 0;
+  const spaceW = c.measureText(" ").width;
+  for (const w of words) {
+    const ww = c.measureText(w).width;
+    const add = cur.length ? spaceW + ww : ww;
+    if (cur.length && curW + add > maxW) {
+      lines.push(cur);
+      cur = [];
+      curW = 0;
+    }
+    cur.push(w);
+    curW += cur.length === 1 ? ww : spaceW + ww;
+  }
+  if (cur.length) lines.push(cur);
+  return lines;
+}
+function kineticTextLayer() {
+  let text = "";
+  let mode = DEFAULTS5.mode;
+  let startMs = DEFAULTS5.startMs;
+  let revealMs = DEFAULTS5.revealMs;
+  let fontPx = DEFAULTS5.fontPx;
+  let color;
+  let centerFrac = DEFAULTS5.centerFrac;
+  let cursor = DEFAULTS5.cursor;
+  return {
+    key: "kinetic-text",
+    init(_ctx, props) {
+      text = props.text ?? "";
+      mode = props.mode ?? DEFAULTS5.mode;
+      startMs = props.startMs ?? DEFAULTS5.startMs;
+      revealMs = props.revealMs ?? DEFAULTS5.revealMs;
+      fontPx = props.fontPx ?? DEFAULTS5.fontPx;
+      color = props.color;
+      centerFrac = props.centerFrac ?? DEFAULTS5.centerFrac;
+      cursor = props.cursor ?? DEFAULTS5.cursor;
+    },
+    draw(ctx, tMs) {
+      if (!text) return;
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const col = color ?? ctx.theme.ink;
+      c.save();
+      c.font = `700 ${fontPx}px ${ctx.theme.fontDisplay}`;
+      c.textBaseline = "middle";
+      const rawLines = text.split("\n");
+      const lines = [];
+      for (const rl of rawLines) lines.push(...wrap2(c, rl.split(/\s+/).filter(Boolean), sb.w));
+      const lineH = fontPx * 1.25;
+      const totalH = lines.length * lineH;
+      const top = ctx.H * centerFrac - totalH / 2 + lineH / 2;
+      const p = clamp014((tMs - startMs) / Math.max(1, revealMs));
+      if (mode === "typewriter") {
+        const full = lines.map((l) => l.join(" "));
+        const totalChars = full.reduce((n, l) => n + l.length, 0);
+        let shown = Math.floor(p * totalChars);
+        c.textAlign = "center";
+        c.fillStyle = col;
+        let y = top;
+        let lastDrawn = { x: 0, y: 0, end: false };
+        for (const line of full) {
+          const take = Math.max(0, Math.min(line.length, shown));
+          const sub = line.slice(0, take);
+          if (sub) c.fillText(sub, ctx.W / 2, y);
+          shown -= line.length;
+          if (take < line.length && take >= 0 && !lastDrawn.end) {
+            lastDrawn = { x: ctx.W / 2 + c.measureText(sub).width / 2, y, end: true };
+          }
+          y += lineH;
+        }
+        if (cursor && p < 1 && Math.floor(tMs / 450) % 2 === 0) {
+          c.fillRect(lastDrawn.x + 6, lastDrawn.y - fontPx * 0.42, 6, fontPx * 0.8);
+        }
+      } else {
+        const allWords = lines.flat();
+        const n = allWords.length || 1;
+        const stagger = revealMs / n;
+        const POP = 280;
+        c.textAlign = "left";
+        const spaceW = c.measureText(" ").width;
+        let wi = 0;
+        let y = top;
+        for (const line of lines) {
+          const lineW = line.reduce((w, word, i) => w + c.measureText(word).width + (i ? spaceW : 0), 0);
+          let x = sb.left + (sb.w - lineW) / 2;
+          for (const word of line) {
+            const ww = c.measureText(word).width;
+            const wp = clamp014((tMs - startMs - wi * stagger) / POP);
+            if (wp > 0) {
+              const scale = 0.7 + 0.3 * wp;
+              c.save();
+              c.globalAlpha = wp;
+              c.translate(x + ww / 2, y);
+              c.scale(scale, scale);
+              c.fillStyle = col;
+              c.fillText(word, -ww / 2, 0);
+              c.restore();
+            }
+            x += ww + spaceW;
+            wi++;
+          }
+          y += lineH;
+        }
+      }
+      c.restore();
+    }
+  };
+}
+var kineticTextFactory = {
+  key: "kinetic-text",
+  create: kineticTextLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["kinetic-text: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (typeof p.text !== "string" || !p.text) errs.push("kinetic-text.text must be a non-empty string");
+    if (p.mode != null && p.mode !== "typewriter" && p.mode !== "word-pop") errs.push('kinetic-text.mode must be "typewriter" | "word-pop"');
+    if (p.startMs != null && typeof p.startMs !== "number") errs.push("kinetic-text.startMs must be a number");
+    if (p.revealMs != null && (typeof p.revealMs !== "number" || p.revealMs <= 0)) errs.push("kinetic-text.revealMs must be a positive number");
+    if (p.fontPx != null && (typeof p.fontPx !== "number" || p.fontPx <= 0)) errs.push("kinetic-text.fontPx must be a positive number");
+    if (p.color != null && typeof p.color !== "string") errs.push("kinetic-text.color must be a string");
+    if (p.centerFrac != null && (typeof p.centerFrac !== "number" || p.centerFrac < 0 || p.centerFrac > 1)) errs.push("kinetic-text.centerFrac must be in [0,1]");
+    if (p.cursor != null && typeof p.cursor !== "boolean") errs.push("kinetic-text.cursor must be a boolean");
+    return errs;
+  }
+};
+
+// src/scene/layers/countdown.ts
+var DEFAULTS6 = { from: 3, startMs: 0, durationMs: 3e3, fontPx: 280, centerFrac: 0.46, ring: true };
+function rgba6(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 countdownLayer() {
+  let from = DEFAULTS6.from;
+  let startMs = DEFAULTS6.startMs;
+  let durationMs = DEFAULTS6.durationMs;
+  let color;
+  let fontPx = DEFAULTS6.fontPx;
+  let centerFrac = DEFAULTS6.centerFrac;
+  let ring = DEFAULTS6.ring;
+  return {
+    key: "countdown",
+    init(_ctx, props) {
+      from = props.from ?? DEFAULTS6.from;
+      startMs = props.startMs ?? DEFAULTS6.startMs;
+      durationMs = props.durationMs ?? DEFAULTS6.durationMs;
+      color = props.color;
+      fontPx = props.fontPx ?? DEFAULTS6.fontPx;
+      centerFrac = props.centerFrac ?? DEFAULTS6.centerFrac;
+      ring = props.ring ?? DEFAULTS6.ring;
+    },
+    draw(ctx, tMs) {
+      const elapsed = tMs - startMs;
+      if (elapsed < 0 || elapsed >= durationMs) return;
+      const perTick = durationMs / from;
+      const idx = Math.floor(elapsed / perTick);
+      const n = from - idx;
+      if (n < 1 || n > from) return;
+      const tickElapsed = elapsed - idx * perTick;
+      const tickFrac = tickElapsed / perTick;
+      const c = ctx.ctx2d;
+      const cx = ctx.W / 2;
+      const cy = ctx.H * centerFrac;
+      const col = color ?? ctx.theme.accent;
+      const pop = 1 + 0.28 * Math.exp(-tickElapsed / 120);
+      const fade = 1 - Math.max(0, (tickFrac - 0.7) / 0.3) * 0.85;
+      c.save();
+      if (ring) {
+        const r = fontPx * 0.62;
+        c.lineWidth = 10;
+        c.lineCap = "round";
+        c.strokeStyle = rgba6(col, 0.18 * fade);
+        c.beginPath();
+        c.arc(cx, cy, r, 0, Math.PI * 2);
+        c.stroke();
+        c.strokeStyle = rgba6(col, 0.9 * fade);
+        c.beginPath();
+        c.arc(cx, cy, r, -Math.PI / 2, -Math.PI / 2 + (1 - tickFrac) * Math.PI * 2);
+        c.stroke();
+      }
+      c.globalAlpha = fade;
+      c.fillStyle = col;
+      c.font = `800 ${Math.round(fontPx * pop)}px ${ctx.theme.fontDisplay}`;
+      c.textAlign = "center";
+      c.textBaseline = "middle";
+      c.fillText(String(n), cx, cy + 2);
+      c.restore();
+    }
+  };
+}
+var countdownFactory = {
+  key: "countdown",
+  create: countdownLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["countdown: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.from != null && (typeof p.from !== "number" || p.from < 1 || !Number.isInteger(p.from))) errs.push("countdown.from must be an integer >= 1");
+    if (p.startMs != null && typeof p.startMs !== "number") errs.push("countdown.startMs must be a number");
+    if (p.durationMs != null && (typeof p.durationMs !== "number" || p.durationMs <= 0)) errs.push("countdown.durationMs must be a positive number");
+    if (p.color != null && typeof p.color !== "string") errs.push("countdown.color must be a string");
+    if (p.fontPx != null && (typeof p.fontPx !== "number" || p.fontPx <= 0)) errs.push("countdown.fontPx must be a positive number");
+    if (p.centerFrac != null && (typeof p.centerFrac !== "number" || p.centerFrac < 0 || p.centerFrac > 1)) errs.push("countdown.centerFrac must be in [0,1]");
+    if (p.ring != null && typeof p.ring !== "boolean") errs.push("countdown.ring must be a boolean");
+    return errs;
+  }
+};
+
+// src/scene/layers/waveform.ts
+var SAMPLES = 128;
+function clampUnit(x) {
+  return x < -1 ? -1 : x > 1 ? 1 : x;
+}
+function syntheticSample(tSec, u) {
+  const phase = u * Math.PI * 2;
+  return 0.55 * Math.sin(phase * 3 + tSec * 6) + 0.28 * Math.sin(phase * 5 + tSec * 9 + 1.1) + 0.14 * Math.sin(phase * 8 + tSec * 4 + 2.3);
+}
+function waveformLayer() {
+  let n = SAMPLES;
+  let centerFrac = 0.46;
+  let amplitudeFrac = 0.1;
+  let lineWidth = 5;
+  let color;
+  let samplesFn;
+  function samplesAt(ctx, tMs) {
+    const fromProp = samplesFn?.(tMs, n);
+    if (fromProp && fromProp.length) {
+      return Array.from({ length: n }, (_, i) => clampUnit(fromProp[Math.min(fromProp.length - 1, i)] ?? 0));
+    }
+    const bt = ctx.waveform?.byteTime?.(tMs);
+    if (bt && bt.length) {
+      return Array.from({ length: n }, (_, i) => clampUnit((bt[Math.floor(i / n * bt.length)] - 128) / 128));
+    }
+    const tSec = tMs / 1e3;
+    return Array.from({ length: n }, (_, i) => clampUnit(syntheticSample(tSec, i / (n - 1))));
+  }
+  return {
+    key: "waveform",
+    init(_ctx, props) {
+      n = props.samples ?? SAMPLES;
+      centerFrac = props.centerFrac ?? 0.46;
+      amplitudeFrac = props.amplitudeFrac ?? 0.1;
+      lineWidth = props.lineWidth ?? 5;
+      color = props.color;
+      samplesFn = props.samplesFn;
+    },
+    draw(ctx, tMs) {
+      const c = ctx.ctx2d;
+      const sb = ctx.safeBox;
+      const left = sb.left, right = sb.right;
+      const cy = ctx.H * centerFrac;
+      const amp = ctx.H * amplitudeFrac;
+      const s = samplesAt(ctx, tMs);
+      c.save();
+      c.lineJoin = "round";
+      c.lineCap = "round";
+      c.strokeStyle = color ?? ctx.theme.accent;
+      c.lineWidth = lineWidth;
+      c.beginPath();
+      for (let i = 0; i < n; i++) {
+        const x = left + (right - left) * (i / (n - 1));
+        const y = cy + s[i] * amp;
+        if (i === 0) c.moveTo(x, y);
+        else c.lineTo(x, y);
+      }
+      c.stroke();
+      c.restore();
+    }
+  };
+}
+var waveformFactory = {
+  key: "waveform",
+  create: waveformLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["waveform: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.samples != null && (typeof p.samples !== "number" || p.samples < 8)) errs.push("waveform.samples must be a number >= 8");
+    if (p.centerFrac != null && (typeof p.centerFrac !== "number" || p.centerFrac < 0 || p.centerFrac > 1)) errs.push("waveform.centerFrac must be in [0,1]");
+    if (p.amplitudeFrac != null && (typeof p.amplitudeFrac !== "number" || p.amplitudeFrac <= 0)) errs.push("waveform.amplitudeFrac must be a positive number");
+    if (p.lineWidth != null && (typeof p.lineWidth !== "number" || p.lineWidth <= 0)) errs.push("waveform.lineWidth must be a positive number");
+    if (p.color != null && typeof p.color !== "string") errs.push("waveform.color must be a string");
+    if (p.samplesFn != null && typeof p.samplesFn !== "function") errs.push("waveform.samplesFn must be a function");
+    return errs;
+  }
+};
+
+// src/scene/layers/scaleHighlight.ts
+var SCALE_INTERVALS = {
+  major: [0, 2, 4, 5, 7, 9, 11],
+  ionian: [0, 2, 4, 5, 7, 9, 11],
+  minor: [0, 2, 3, 5, 7, 8, 10],
+  aeolian: [0, 2, 3, 5, 7, 8, 10],
+  dorian: [0, 2, 3, 5, 7, 9, 10],
+  phrygian: [0, 1, 3, 5, 7, 8, 10],
+  lydian: [0, 2, 4, 6, 7, 9, 11],
+  mixolydian: [0, 2, 4, 5, 7, 9, 10],
+  locrian: [0, 1, 3, 5, 6, 8, 10],
+  harmonicMinor: [0, 2, 3, 5, 7, 8, 11],
+  melodicMinor: [0, 2, 3, 5, 7, 9, 11],
+  pentatonicMajor: [0, 2, 4, 7, 9],
+  pentatonicMinor: [0, 3, 5, 7, 10],
+  blues: [0, 3, 5, 6, 7, 10],
+  chromatic: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+};
+var PRETTY = {
+  major: "Major",
+  ionian: "Ionian",
+  minor: "Minor",
+  aeolian: "Aeolian",
+  dorian: "Dorian",
+  phrygian: "Phrygian",
+  lydian: "Lydian",
+  mixolydian: "Mixolydian",
+  locrian: "Locrian",
+  harmonicMinor: "Harmonic Minor",
+  melodicMinor: "Melodic Minor",
+  pentatonicMajor: "Pentatonic",
+  pentatonicMinor: "Minor Pentatonic",
+  blues: "Blues",
+  chromatic: "Chromatic"
+};
+function rootPc(root) {
+  if (typeof root === "number") return (root % 12 + 12) % 12;
+  return noteNameToIndex(root);
+}
+function scaleHighlightLayer() {
+  let rootProp = "C";
+  let scaleKey = "major";
+  let scaleColor;
+  let tonicColor;
+  let alpha = 0.55;
+  let label = true;
+  let labelTextProp;
+  return {
+    key: "scale-highlight",
+    init(_ctx, props) {
+      rootProp = props.root ?? "C";
+      scaleKey = props.scale ?? "major";
+      scaleColor = props.scaleColor;
+      tonicColor = props.tonicColor;
+      alpha = props.alpha ?? 0.55;
+      label = props.label ?? true;
+      labelTextProp = props.labelText;
+    },
+    draw(ctx, _tMs) {
+      const c = ctx.ctx2d;
+      const intervals = SCALE_INTERVALS[scaleKey] ?? SCALE_INTERVALS.major;
+      const root = rootPc(rootProp);
+      const inScale = new Set(intervals.map((iv) => (root + iv) % 12));
+      const sc = scaleColor ?? ctx.theme.accent;
+      const tc = tonicColor ?? ctx.theme.gold;
+      const layout = getKeyboardLayout(ctx);
+      if (layout) {
+        c.save();
+        c.globalAlpha = alpha;
+        for (let m = layout.lowMidi; m <= layout.highMidi; m++) {
+          if (!inRange(layout, m)) continue;
+          const pc = pitchClass(m);
+          if (!inScale.has(pc)) continue;
+          const r = keyRect(layout, m);
+          c.fillStyle = pc === root ? tc : sc;
+          c.fillRect(r.x, r.y, r.w, r.h);
+        }
+        c.restore();
+      }
+      if (label) {
+        const sb = ctx.safeBox;
+        const name = typeof rootProp === "string" ? rootProp : ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"][root];
+        const text = labelTextProp ?? `${name} ${PRETTY[scaleKey] ?? scaleKey}`;
+        c.save();
+        c.fillStyle = ctx.theme.ink;
+        c.font = `700 ${Math.round(ctx.H * 0.03)}px ${ctx.theme.fontDisplay}`;
+        c.textAlign = "center";
+        c.textBaseline = "top";
+        c.fillText(text, ctx.W / 2, sb.top + sb.h * 0.04);
+        c.restore();
+      }
+    }
+  };
+}
+var scaleHighlightFactory = {
+  key: "scale-highlight",
+  create: scaleHighlightLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["scale-highlight: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p.root != null && typeof p.root !== "string" && typeof p.root !== "number") errs.push("scale-highlight.root must be a note name or pitch-class number");
+    if (p.scale != null && (typeof p.scale !== "string" || !(p.scale in SCALE_INTERVALS))) errs.push(`scale-highlight.scale must be one of: ${Object.keys(SCALE_INTERVALS).join(", ")}`);
+    if (p.scaleColor != null && typeof p.scaleColor !== "string") errs.push("scale-highlight.scaleColor must be a string");
+    if (p.tonicColor != null && typeof p.tonicColor !== "string") errs.push("scale-highlight.tonicColor must be a string");
+    if (p.alpha != null && (typeof p.alpha !== "number" || p.alpha < 0 || p.alpha > 1)) errs.push("scale-highlight.alpha must be in [0,1]");
+    if (p.label != null && typeof p.label !== "boolean") errs.push("scale-highlight.label must be a boolean");
+    if (p.labelText != null && typeof p.labelText !== "string") errs.push("scale-highlight.labelText must be a string");
+    return errs;
+  }
+};
+
 // src/scene/registry.ts
 var REGISTRY = /* @__PURE__ */ new Map();
 function registerLayer(factory) {
@@ -3695,6 +4108,10 @@ registerLayer(progressRingFactory);
 registerLayer(radialSpectrumFactory);
 registerLayer(karaokeCaptionFactory);
 registerLayer(intervalArcsFactory);
+registerLayer(kineticTextFactory);
+registerLayer(countdownFactory);
+registerLayer(waveformFactory);
+registerLayer(scaleHighlightFactory);
 
 // src/scene/audioLayers.ts
 function countInSchedule(opts) {
@@ -3851,7 +4268,9 @@ var SCREEN_PINNED_KEYS = /* @__PURE__ */ new Set([
   "beat-pulse",
   "chord-ribbon",
   "progress-ring",
-  "karaoke-caption"
+  "karaoke-caption",
+  "kinetic-text",
+  "countdown"
 ]);
 function defaultBufferFactory() {
   const g = globalThis;
@@ -4438,6 +4857,7 @@ export {
   FOLLOW_PAD,
   PIANO_HIGH,
   PIANO_LOW,
+  SCALE_INTERVALS,
   activeChord,
   activeCue,
   activeSection,
@@ -4467,6 +4887,7 @@ export {
   contourPolyline,
   countInLeadSec,
   countInSchedule,
+  countdownFactory,
   countdownRemaining,
   countdownSeconds,
   countingDegreeDemoSpec,
@@ -4517,6 +4938,7 @@ export {
   keySlot,
   keyboardFactory,
   keyboardLayout,
+  kineticTextFactory,
   lerp,
   lerpBox,
   lerpCamera,
@@ -4562,6 +4984,7 @@ export {
   revealProgress,
   runGate,
   safeGuidesFactory,
+  scaleHighlightFactory,
   scoreFromMusicXML,
   scorePitchSpan,
   scrollCursorFactory,
@@ -4584,6 +5007,7 @@ export {
   visualTimelineMs,
   vstackAudioPlayheadLine,
   vstackFollowBox,
+  waveformFactory,
   whiteKeys,
   worldToViewport
 };