@real-music-packages/web-core 0.31.0 → 0.32.0

package/dist/scene/index.d.ts

@@ -1020,7 +1020,8 @@ declare const keyboardFactory: LayerFactory<KeyboardProps>;
 interface FretboardProps {
     /** Highest fret drawn. Default: auto-fit the excerpt (min 5, max 15), padded. */
     visibleFrets?: number;
-    /** Board height in world px. Default 220. */
+    /** Board height in world px. Default 360 — 6 strings need more vertical room
+     *  than the piano strip (220 cramped them to ~37px each). */
     height?: number;
     /** Board bottom edge in world px. Default safeBox.bottom. */
     bottomY?: number;
@@ -1988,4 +1989,24 @@ interface EndCardProps {
 }
 declare const endCardFactory: LayerFactory<EndCardProps>;
 
-export { type Affine, type AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatPulseProps, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordRibbonProps, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type ContourPlot, type ContourPoint, type CountInOpts, type CountdownProps, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type EndCardProps, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type FretboardProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type IntervalArcsProps, type KaraokeCaptionProps, type KaraokeWord, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type KineticMode, type KineticTextProps, type LabelMode, type Layer, type LayerFactory, type McqCardProps, type NotationEngraving, type NotationLayout, type NotationLayoutOpts, type NotationProps, type NotationRect, type OutputProbe, PIANO_HIGH, PIANO_LOW, type ParticleBurstProps, type PitchContourProps, type Placement, type PlayheadLine, type PortraitProps, type ProgressRingProps, type PromoCardsDemoOpts, type PulseStyle, type Quiz, type QuizOption, type QuizPhase, type RadialSpectrumProps, type RayEndpoints, type RecordSceneSpecOpts, type Rect, type RenderCtx, type ResolvedSegment, type RevealProps, SCALE_INTERVALS, type SafeGuidesProps, type ScaleHighlightProps, type SceneSpec, type ScheduleTarget, type Score, type ScoreFromMusicXMLOpts, type ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type SpectrumInput, type SpectrumProps, type StaffKeyboardRayProps, type StatCounterProps, type TempoMap, type TensionGraphProps, type TensionPoint, type TextureProps, type TimeAnchor, type TimelineSegment, type WaveformInput, type WaveformProps, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, audioPlayheadLine, ballArc, ballX, beatGrid, beatPhase, beatPulseFactory, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, chordRibbonFactory, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownFactory, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, cropAroundBox, ctaFactory, cubicEaseInOut, cueOpacity, degreeLabel, degreeLabelsFactory, distinctMeasureIndices, distinctOnsets, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, endCardFactory, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, firstMeasureBox, followBoxAt, followSrcBox, followWindowStart, fracSlotPoint, frameRect, fretboardFactory, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, inRange, intervalArcsFactory, invLerp, isBlackKey, karaokeCaptionFactory, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, kineticTextFactory, lerp, lerpBox, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureColumnsFromLayout, measureCount, measureSpanBox, measureSpans, measureSystemMap, timeToX as minimapTimeToX, msPerBeat, notationFactory, notationLayout, noteColor, noteSetXRange, parseKey, parseTimeSig, particleBurstFactory, pcToSlot, pitchAt, pitchContourFactory, pitchRange, playheadLine, portraitFactory, progress01, progressRingFactory, projectPoint, promoCardsDemoSpec, pulseAt, quizPhase, radialSpectrumFactory, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scaleHighlightFactory, scoreFromMusicXML, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, spectrumFactory, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, statCounterFactory, systemBox, tensionGraphFactory, textureFactory, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, vstackAudioPlayheadLine, vstackFollowBox, waveformFactory, whiteKeys, worldToViewport };
+type ImageRevealMode = 'pixelate' | 'shuffle' | 'blur';
+interface ImageRevealProps {
+    /** The image to reveal. Any CanvasImageSource (HTMLImageElement, OffscreenCanvas, …). */
+    image: CanvasImageSource;
+    /** Reveal mode. Default 'pixelate'. */
+    mode?: ImageRevealMode;
+    /** When the reveal starts (ms). Default 0. */
+    startMs?: number;
+    /** How long the full reveal takes (ms). Default 6000. */
+    durationMs?: number;
+    /**
+     * Difficulty scalar 0..1.
+     * - pixelate: controls maximum block size (0→small, 1→large; default 0.5 ≈ 1/8 width).
+     * - shuffle:  controls maximum tile offset fraction (default 0.5).
+     * - blur:     controls maximum blur radius in px (0→mild, 1→extreme; default 0.5 ≈ 40px).
+     */
+    difficulty?: number;
+}
+declare const imageRevealFactory: LayerFactory<ImageRevealProps>;
+
+export { type Affine, type AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatPulseProps, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordRibbonProps, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type ContourPlot, type ContourPoint, type CountInOpts, type CountdownProps, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type EndCardProps, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type FretboardProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type ImageRevealMode, type ImageRevealProps, type IntervalArcsProps, type KaraokeCaptionProps, type KaraokeWord, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type KineticMode, type KineticTextProps, type LabelMode, type Layer, type LayerFactory, type McqCardProps, type NotationEngraving, type NotationLayout, type NotationLayoutOpts, type NotationProps, type NotationRect, type OutputProbe, PIANO_HIGH, PIANO_LOW, type ParticleBurstProps, type PitchContourProps, type Placement, type PlayheadLine, type PortraitProps, type ProgressRingProps, type PromoCardsDemoOpts, type PulseStyle, type Quiz, type QuizOption, type QuizPhase, type RadialSpectrumProps, type RayEndpoints, type RecordSceneSpecOpts, type Rect, type RenderCtx, type ResolvedSegment, type RevealProps, SCALE_INTERVALS, type SafeGuidesProps, type ScaleHighlightProps, type SceneSpec, type ScheduleTarget, type Score, type ScoreFromMusicXMLOpts, type ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type SpectrumInput, type SpectrumProps, type StaffKeyboardRayProps, type StatCounterProps, type TempoMap, type TensionGraphProps, type TensionPoint, type TextureProps, type TimeAnchor, type TimelineSegment, type WaveformInput, type WaveformProps, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, audioPlayheadLine, ballArc, ballX, beatGrid, beatPhase, beatPulseFactory, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, chordRibbonFactory, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownFactory, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, cropAroundBox, ctaFactory, cubicEaseInOut, cueOpacity, degreeLabel, degreeLabelsFactory, distinctMeasureIndices, distinctOnsets, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, endCardFactory, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, firstMeasureBox, followBoxAt, followSrcBox, followWindowStart, fracSlotPoint, frameRect, fretboardFactory, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, imageRevealFactory, inRange, intervalArcsFactory, invLerp, isBlackKey, karaokeCaptionFactory, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, kineticTextFactory, lerp, lerpBox, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureColumnsFromLayout, measureCount, measureSpanBox, measureSpans, measureSystemMap, timeToX as minimapTimeToX, msPerBeat, notationFactory, notationLayout, noteColor, noteSetXRange, parseKey, parseTimeSig, particleBurstFactory, pcToSlot, pitchAt, pitchContourFactory, pitchRange, playheadLine, portraitFactory, progress01, progressRingFactory, projectPoint, promoCardsDemoSpec, pulseAt, quizPhase, radialSpectrumFactory, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scaleHighlightFactory, scoreFromMusicXML, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, spectrumFactory, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, statCounterFactory, systemBox, tensionGraphFactory, textureFactory, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, vstackAudioPlayheadLine, vstackFollowBox, waveformFactory, whiteKeys, worldToViewport };

package/dist/scene/index.js

@@ -1318,7 +1318,7 @@ function fretboardLayer() {
       for (const p of placement.values()) maxFret = Math.max(maxFret, p.fret);
       visibleFrets = props.visibleFrets ?? Math.min(15, Math.max(5, maxFret + 1));
       const sb = ctx.safeBox;
-      const height = props.height ?? 220;
+      const height = props.height ?? 360;
       const bottomY = props.bottomY ?? sb.bottom;
       rect = { x: sb.left, y: bottomY - height, w: sb.w, h: height };
     },
@@ -4765,6 +4765,212 @@ var endCardFactory = {
   }
 };
 
+// src/scene/layers/imageReveal.ts
+var DEFAULTS11 = {
+  mode: "pixelate",
+  startMs: 0,
+  durationMs: 6e3,
+  difficulty: 0.5
+};
+function clamp017(x) {
+  return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+function fitRect(iW, iH, bx, by, bw, bh) {
+  const scale = Math.min(bw / iW, bh / iH);
+  const dw = iW * scale;
+  const dh = iH * scale;
+  return { dx: bx + (bw - dw) / 2, dy: by + (bh - dh) / 2, dw, dh };
+}
+function blockSizeAt(p, maxBlock) {
+  return Math.max(1, Math.round(maxBlock * (1 - p) + 1 * p));
+}
+function tileHash(i) {
+  let x = i * 2654435761 >>> 0;
+  x ^= x << 13;
+  x ^= x >>> 17;
+  x ^= x << 5;
+  return (x >>> 0) / 4294967295;
+}
+function tileHashSigned(i, salt) {
+  return tileHash(i * 1013904223 + salt * 22695477 | 0) * 2 - 1;
+}
+function imageRevealLayer() {
+  let mode = DEFAULTS11.mode;
+  let startMs = DEFAULTS11.startMs;
+  let durationMs = DEFAULTS11.durationMs;
+  let difficulty = DEFAULTS11.difficulty;
+  let image = null;
+  let offscreen = null;
+  let offCtx = null;
+  let imgW = 0;
+  let imgH = 0;
+  function ensureOffscreen(w, h) {
+    const needNew = !offscreen || offscreen.width !== w || offscreen.height !== h;
+    if (needNew) {
+      if (typeof OffscreenCanvas !== "undefined") {
+        offscreen = new OffscreenCanvas(w, h);
+        offCtx = offscreen.getContext("2d");
+      } else {
+        const el = typeof document !== "undefined" ? document.createElement("canvas") : null;
+        if (!el) {
+          offscreen = null;
+          offCtx = null;
+          return null;
+        }
+        el.width = w;
+        el.height = h;
+        offscreen = el;
+        offCtx = el.getContext("2d");
+      }
+    }
+    return offCtx;
+  }
+  return {
+    key: "image-reveal",
+    init(_ctx, props) {
+      mode = props.mode ?? DEFAULTS11.mode;
+      startMs = props.startMs ?? DEFAULTS11.startMs;
+      durationMs = props.durationMs ?? DEFAULTS11.durationMs;
+      difficulty = props.difficulty ?? DEFAULTS11.difficulty;
+      image = props.image;
+      const src = props.image;
+      imgW = src["naturalWidth"] ?? src["displayWidth"] ?? src["width"] ?? 0;
+      imgH = src["naturalHeight"] ?? src["displayHeight"] ?? src["height"] ?? 0;
+    },
+    draw(ctx, tMs) {
+      if (!image || imgW === 0 || imgH === 0) return;
+      const p = clamp017((tMs - startMs) / (durationMs > 0 ? durationMs : 1));
+      const sb = ctx.safeBox;
+      const fit = fitRect(imgW, imgH, sb.left, sb.top, sb.w, sb.h);
+      const c = ctx.ctx2d;
+      c.save();
+      c.beginPath();
+      c.rect(fit.dx, fit.dy, fit.dw, fit.dh);
+      c.clip();
+      if (mode === "pixelate") {
+        drawPixelate(c, image, fit, p, difficulty, imgW, imgH, ensureOffscreen);
+      } else if (mode === "blur") {
+        drawBlur(c, image, fit, p, difficulty, imgW, imgH, ensureOffscreen);
+      } else {
+        drawShuffle(c, image, fit, p, difficulty, imgW, imgH);
+      }
+      c.restore();
+    },
+    dispose() {
+      image = null;
+      offscreen = null;
+      offCtx = null;
+    }
+  };
+}
+function drawPixelate(c, image, fit, p, difficulty, imgW, imgH, getOffCtx) {
+  const maxBlock = Math.max(2, Math.round(fit.dw * (0.03125 + difficulty * 0.21875)));
+  const blockSize = blockSizeAt(p, maxBlock);
+  if (blockSize <= 1) {
+    c.drawImage(image, 0, 0, imgW, imgH, fit.dx, fit.dy, fit.dw, fit.dh);
+    return;
+  }
+  const smallW = Math.max(1, Math.ceil(fit.dw / blockSize));
+  const smallH = Math.max(1, Math.ceil(fit.dh / blockSize));
+  const oc = getOffCtx(smallW, smallH);
+  if (!oc) {
+    c.drawImage(image, 0, 0, imgW, imgH, fit.dx, fit.dy, fit.dw, fit.dh);
+    return;
+  }
+  oc.clearRect(0, 0, smallW, smallH);
+  oc.drawImage(image, 0, 0, imgW, imgH, 0, 0, smallW, smallH);
+  const prev = c.imageSmoothingEnabled;
+  c.imageSmoothingEnabled = false;
+  const off = oc.canvas;
+  c.drawImage(off, 0, 0, smallW, smallH, fit.dx, fit.dy, fit.dw, fit.dh);
+  c.imageSmoothingEnabled = prev;
+}
+function drawBlur(c, image, fit, p, difficulty, imgW, imgH, getOffCtx) {
+  const maxBlur = 8 + difficulty * 72;
+  const blurPx = maxBlur * (1 - p);
+  const cAny = c;
+  const hasFilter = "filter" in c && cAny["filter"] !== void 0;
+  if (hasFilter && blurPx > 0) {
+    const prev = cAny["filter"];
+    cAny["filter"] = `blur(${blurPx.toFixed(1)}px)`;
+    c.drawImage(image, 0, 0, imgW, imgH, fit.dx, fit.dy, fit.dw, fit.dh);
+    cAny["filter"] = prev ?? "none";
+  } else if (blurPx > 0) {
+    const passes = Math.min(6, Math.round(blurPx / 8));
+    if (passes > 0) {
+      let w = Math.max(1, Math.round(fit.dw / Math.pow(2, passes)));
+      let h = Math.max(1, Math.round(fit.dh / Math.pow(2, passes)));
+      const oc = getOffCtx(w, h);
+      if (oc) {
+        oc.clearRect(0, 0, w, h);
+        oc.drawImage(image, 0, 0, imgW, imgH, 0, 0, w, h);
+        c.drawImage(oc.canvas, 0, 0, w, h, fit.dx, fit.dy, fit.dw, fit.dh);
+      } else {
+        c.drawImage(image, 0, 0, imgW, imgH, fit.dx, fit.dy, fit.dw, fit.dh);
+      }
+    } else {
+      c.drawImage(image, 0, 0, imgW, imgH, fit.dx, fit.dy, fit.dw, fit.dh);
+    }
+  } else {
+    c.drawImage(image, 0, 0, imgW, imgH, fit.dx, fit.dy, fit.dw, fit.dh);
+  }
+}
+function drawShuffle(c, image, fit, p, difficulty, imgW, imgH) {
+  const cols = 8;
+  const rows = 14;
+  const tileW = fit.dw / cols;
+  const tileH = fit.dh / rows;
+  const srcTileW = imgW / cols;
+  const srcTileH = imgH / rows;
+  const maxOffX = tileW * difficulty * 1.5;
+  const maxOffY = tileH * difficulty * 1.5;
+  const ease = 1 - (1 - p) * (1 - p);
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < cols; col++) {
+      const i = row * cols + col;
+      const offX = tileHashSigned(i, 0) * maxOffX * (1 - ease);
+      const offY = tileHashSigned(i, 1) * maxOffY * (1 - ease);
+      const sx = col * srcTileW;
+      const sy = row * srcTileH;
+      const dxHome = fit.dx + col * tileW;
+      const dyHome = fit.dy + row * tileH;
+      const dx = dxHome + offX;
+      const dy = dyHome + offY;
+      c.drawImage(
+        image,
+        sx,
+        sy,
+        srcTileW,
+        srcTileH,
+        dx,
+        dy,
+        tileW,
+        tileH
+      );
+    }
+  }
+}
+var VALID_MODES = ["pixelate", "shuffle", "blur"];
+var imageRevealFactory = {
+  key: "image-reveal",
+  create: imageRevealLayer,
+  validateProps(props) {
+    if (props == null || typeof props !== "object") return ["image-reveal: props must be an object"];
+    const p = props;
+    const errs = [];
+    if (p["image"] == null) errs.push("image-reveal.image is required");
+    if (p["mode"] != null && !VALID_MODES.includes(p["mode"]))
+      errs.push(`image-reveal.mode must be one of: ${VALID_MODES.join(", ")}`);
+    if (p["startMs"] != null && typeof p["startMs"] !== "number")
+      errs.push("image-reveal.startMs must be a number");
+    if (p["durationMs"] != null && (typeof p["durationMs"] !== "number" || p["durationMs"] <= 0))
+      errs.push("image-reveal.durationMs must be a positive number");
+    if (p["difficulty"] != null && (typeof p["difficulty"] !== "number" || p["difficulty"] < 0 || p["difficulty"] > 1))
+      errs.push("image-reveal.difficulty must be a number in [0, 1]");
+    return errs;
+  }
+};
+
 // src/scene/registry.ts
 var REGISTRY = /* @__PURE__ */ new Map();
 function registerLayer(factory) {
@@ -4813,6 +5019,7 @@ registerLayer(tensionGraphFactory);
 registerLayer(textureFactory);
 registerLayer(statCounterFactory);
 registerLayer(endCardFactory);
+registerLayer(imageRevealFactory);
 
 // src/scene/audioLayers.ts
 function countInSchedule(opts) {
@@ -5633,6 +5840,7 @@ export {
   highlightIntensity,
   hookFactory,
   identityCamera,
+  imageRevealFactory,
   inRange,
   intervalArcsFactory,
   invLerp,