@real-music-packages/web-core 0.13.0 → 0.14.0

package/dist/scene/index.d.ts

@@ -227,6 +227,14 @@ declare const linear: Easing;
 declare const easeInOut: Easing;
 declare const easeIn: Easing;
 declare const easeOut: Easing;
+/**
+ * Eased 0..1 progress of a transition at absolute time `tMs`, given the incoming
+ * segment's `startMs` and the transition `durationMs`. Returns 0 at/before the
+ * start, 1 at/after start+durationMs, eased in between. Pure fn of t. Shared by
+ * the runner so the same envelope drives crossfade alpha, push translate, and
+ * wipe clip. `durationMs <= 0` → an instant 1 (degenerate hard-cut).
+ */
+declare const transitionProgress: (tMs: number, startMs: number, durationMs: number, easing?: Easing) => number;
 
 /** A rectangle in WORLD coordinates (the layers' natural pixel space). */
 interface Rect {
@@ -326,12 +334,52 @@ interface SegmentAudioCtx {
 interface ScheduleTarget {
     triggerAttackRelease: (note: unknown, dur: unknown, time?: unknown, velocity?: unknown) => void;
 }
+/**
+ * Optional ENTER transition for a segment — how it comes IN from the PREVIOUS
+ * segment (the one immediately before it in the timeline). Purely VISUAL and
+ * fully additive: a segment with no `transition` hard-cuts exactly as before
+ * (existing specs are byte-for-byte unchanged). The audio timeline / per-segment
+ * `audio` hook is unaffected (transitions are a visual envelope only).
+ *
+ * During the first `durationMs` of the incoming segment, the runner renders BOTH
+ * the previous segment (its last drawn state, held) AND the incoming segment,
+ * applying an eased envelope (`easeInOut` by default):
+ *  - `crossfade` — outgoing opacity 1→0, incoming 0→1 (the keystone; always on).
+ *  - `push`      — both slide along `direction`: incoming enters from off-frame
+ *                  while outgoing exits the opposite way (a hard slide, no fade).
+ *  - `wipe`      — incoming is revealed by a moving clip edge along `direction`;
+ *                  the outgoing shows through the un-wiped region (no fade).
+ *
+ * The overlap does NOT add time — the transition lives INSIDE the incoming
+ * segment's own window, so `visualTimelineMs` (and the gate's A/V-duration check)
+ * are unchanged. `durationMs` is clamped to the shorter of the two adjoining
+ * segment lengths so a transition can't run past either segment.
+ */
+interface SegmentTransition {
+    /** Transition style. Start with `crossfade`. */
+    type: 'crossfade' | 'push' | 'wipe';
+    /** Length of the enter window in ms (from the incoming segment's start). */
+    durationMs: number;
+    /**
+     * Slide / wipe direction for `push` and `wipe` (ignored by `crossfade`).
+     * Names the edge the INCOMING segment comes FROM. Default `left`.
+     */
+    direction?: 'left' | 'right' | 'up' | 'down';
+    /** Eased envelope, 0..1 → 0..1. Defaults to `easeInOut`. */
+    easing?: Easing;
+}
 interface TimelineSegment {
     /** [start, end] in SECONDS; end may be "end" / "end-N". */
     at: [number, TimeAnchor];
     layers: SpecLayer[];
     /** Optional sound scheduled at this segment's start (see SegmentAudio). */
     audio?: SegmentAudio;
+    /**
+     * Optional ENTER transition from the PREVIOUS segment (see SegmentTransition).
+     * Omit for today's hard cut. Has no effect on the first segment (nothing to
+     * transition from) unless `loop` is set on the spec.
+     */
+    transition?: SegmentTransition;
 }
 interface SceneSpec {
     /** [width, height] px. */
@@ -357,6 +405,7 @@ interface ResolvedSegment {
     endMs: number;
     layers: SpecLayer[];
     audio?: SegmentAudio;
+    transition?: SegmentTransition;
 }
 /** Resolve every segment's [start,end] to ms against the total clip length. */
 declare function resolveTimeline(spec: SceneSpec, totalSec: number): ResolvedSegment[];
@@ -397,7 +446,25 @@ interface BuildSceneOpts {
     /** Override the camera pose per absolute tMs (pan/zoom director). Identity by
      *  default. */
     camera?: (tMs: number) => CameraState;
+    /**
+     * Offscreen-buffer factory used ONLY by segment `transition`s (a segment's
+     * stack is rendered to a buffer, then composited onto the main canvas with the
+     * transition envelope — so the envelope is robust even when inner layers set
+     * their own `globalAlpha`). Unused when no segment has a transition.
+     *
+     * Default: `OffscreenCanvas` if available, else `document.createElement
+     * ('canvas')`. Node/headless callers (and the node-canvas golden tests) pass a
+     * factory backed by `createCanvas`. If no factory is resolvable AND a
+     * transition fires, the runner falls back to a direct `globalAlpha` envelope
+     * (crossfade only; degrades gracefully) rather than throwing.
+     */
+    bufferFactory?: BufferFactory;
 }
+/** Makes an offscreen drawing surface for transition compositing. */
+type BufferFactory = (w: number, h: number) => {
+    ctx: CanvasRenderingContext2D;
+    image: CanvasImageSource;
+};
 /**
  * Instantiate + init every layer in the spec and return a deterministic renderer.
  * Throws if a referenced layer key isn't registered or its props don't validate
@@ -1465,4 +1532,4 @@ interface SectionMinimapProps {
 }
 declare const sectionMinimapFactory: LayerFactory<SectionMinimapProps>;
 
-export { type Affine, type AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatTick, type BrandingProps, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type ContourPlot, type ContourPoint, type CountInOpts, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, 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 PitchContourProps, type Placement, type PlayheadLine, type PortraitProps, type PromoCardsDemoOpts, type Quiz, type QuizOption, type QuizPhase, type RayEndpoints, type RecordSceneSpecOpts, type Rect, type RenderCtx, type ResolvedSegment, type RevealProps, type SafeGuidesProps, type SceneSpec, type ScheduleTarget, type Score, type ScoreFromMusicXMLOpts, type ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SpecLayer, type SpectrumInput, type SpectrumProps, type StaffKeyboardRayProps, type TempoMap, type TimeAnchor, type TimelineSegment, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, ballArc, ballX, beatGrid, beatPhase, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, cropAroundBox, ctaFactory, cubicEaseInOut, cueOpacity, degreeLabel, degreeLabelsFactory, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, firstMeasureBox, followBoxAt, followSrcBox, followWindowStart, fracSlotPoint, frameRect, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, inRange, invLerp, isBlackKey, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, lerp, lerpBox, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureColumnsFromLayout, measureCount, measureSpanBox, measureSpans, timeToX as minimapTimeToX, msPerBeat, notationFactory, notationLayout, noteColor, noteSetXRange, parseKey, parseTimeSig, pcToSlot, pitchAt, pitchContourFactory, pitchRange, playheadLine, portraitFactory, progress01, projectPoint, promoCardsDemoSpec, quizPhase, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scoreFromMusicXML, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, spectrumFactory, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, whiteKeys, worldToViewport };
+export { type Affine, type AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type ContourPlot, type ContourPoint, type CountInOpts, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, 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 PitchContourProps, type Placement, type PlayheadLine, type PortraitProps, type PromoCardsDemoOpts, type Quiz, type QuizOption, type QuizPhase, type RayEndpoints, type RecordSceneSpecOpts, type Rect, type RenderCtx, type ResolvedSegment, type RevealProps, type SafeGuidesProps, 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 TempoMap, type TimeAnchor, type TimelineSegment, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, ballArc, ballX, beatGrid, beatPhase, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, cropAroundBox, ctaFactory, cubicEaseInOut, cueOpacity, degreeLabel, degreeLabelsFactory, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, firstMeasureBox, followBoxAt, followSrcBox, followWindowStart, fracSlotPoint, frameRect, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, inRange, invLerp, isBlackKey, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, lerp, lerpBox, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureColumnsFromLayout, measureCount, measureSpanBox, measureSpans, timeToX as minimapTimeToX, msPerBeat, notationFactory, notationLayout, noteColor, noteSetXRange, parseKey, parseTimeSig, pcToSlot, pitchAt, pitchContourFactory, pitchRange, playheadLine, portraitFactory, progress01, projectPoint, promoCardsDemoSpec, quizPhase, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scoreFromMusicXML, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, spectrumFactory, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, whiteKeys, worldToViewport };

package/dist/scene/index.js

@@ -177,6 +177,10 @@ var easeOut = (t) => {
   const c = clamp(t, 0, 1);
   return 1 - (1 - c) * (1 - c);
 };
+var transitionProgress = (tMs, startMs, durationMs, easing = easeInOut) => {
+  if (durationMs <= 0) return 1;
+  return easing(invLerp(startMs, startMs + durationMs, tMs));
+};
 
 // src/scene/caption.ts
 function activeCue(script, tMs) {
@@ -2748,7 +2752,13 @@ 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, audio: seg.audio };
+    return {
+      startMs: startSec * 1e3,
+      endMs: endSec * 1e3,
+      layers: seg.layers,
+      audio: seg.audio,
+      transition: seg.transition
+    };
   });
 }
 function visualTimelineMs(resolved) {
@@ -2764,6 +2774,24 @@ var SCREEN_PINNED_KEYS = /* @__PURE__ */ new Set([
   "safe-guides",
   "mcq-card"
 ]);
+function defaultBufferFactory() {
+  const g = globalThis;
+  if (typeof g.OffscreenCanvas === "function") {
+    return (w, h) => {
+      const c = new g.OffscreenCanvas(w, h);
+      return { ctx: c.getContext("2d"), image: c };
+    };
+  }
+  if (typeof g.document !== "undefined" && g.document?.createElement) {
+    return (w, h) => {
+      const c = g.document.createElement("canvas");
+      c.width = w;
+      c.height = h;
+      return { ctx: c.getContext("2d"), image: c };
+    };
+  }
+  return void 0;
+}
 async function buildScene(opts) {
   const { spec, theme, score } = opts;
   const [W, H] = spec.size;
@@ -2771,6 +2799,8 @@ async function buildScene(opts) {
   const resolved = resolveTimeline(spec, opts.totalSec);
   const safe = safeBox(W, H);
   const camera = opts.camera ?? (() => identityCamera(W, H));
+  const bufferFactory = opts.bufferFactory ?? defaultBufferFactory();
+  const hasTransitions = resolved.some((s) => s.transition && s.transition.durationMs > 0);
   const clock = { nowMs: () => 0 };
   const baseCtx = {
     W,
@@ -2782,7 +2812,8 @@ async function buildScene(opts) {
     fps
   };
   const bound = [];
-  for (const seg of resolved) {
+  for (let segIndex = 0; segIndex < resolved.length; segIndex++) {
+    const seg = resolved[segIndex];
     for (const sl of seg.layers) {
       const factory = getLayerFactory(sl.k);
       if (!factory) {
@@ -2798,32 +2829,160 @@ async function buildScene(opts) {
         layer,
         startMs: seg.startMs,
         endMs: seg.endMs,
+        segIndex,
         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);
+  function dirVec(dir) {
+    switch (dir) {
+      case "right":
+        return { x: 1, y: 0 };
+      case "up":
+        return { x: 0, y: -1 };
+      case "down":
+        return { x: 0, y: 1 };
+      case "left":
+      default:
+        return { x: -1, y: 0 };
+    }
+  }
+  function transitionEnvs(tr, p) {
+    if (tr.type === "push") {
+      const v = dirVec(tr.direction);
+      const span = Math.abs(v.x) ? W : H;
+      return {
+        incoming: { alpha: 1, dx: -v.x * span * (1 - p), dy: -v.y * span * (1 - p) },
+        outgoing: { alpha: 1, dx: v.x * span * p, dy: v.y * span * p }
+      };
+    }
+    if (tr.type === "wipe") {
+      const v = dirVec(tr.direction);
+      let inClip;
+      let outClip;
+      if (v.x !== 0) {
+        const w = W * p;
+        if (v.x < 0) {
+          inClip = { x: 0, y: 0, w, h: H };
+          outClip = { x: w, y: 0, w: W - w, h: H };
+        } else {
+          inClip = { x: W - w, y: 0, w, h: H };
+          outClip = { x: 0, y: 0, w: W - w, h: H };
+        }
+      } else {
+        const h = H * p;
+        if (v.y < 0) {
+          inClip = { x: 0, y: 0, w: W, h };
+          outClip = { x: 0, y: h, w: W, h: H - h };
+        } else {
+          inClip = { x: 0, y: H - h, w: W, h };
+          outClip = { x: 0, y: 0, w: W, h: H - h };
+        }
+      }
+      return {
+        incoming: { alpha: 1, dx: 0, dy: 0, clip: inClip },
+        outgoing: { alpha: 1, dx: 0, dy: 0, clip: outClip }
+      };
+    }
+    return {
+      incoming: { alpha: p, dx: 0, dy: 0 },
+      outgoing: { alpha: 1 - p, dx: 0, dy: 0 }
+    };
+  }
+  function frameplan(tMs) {
+    const plan = [];
+    for (let i = 0; i < resolved.length; i++) {
+      const seg = resolved[i];
+      if (tMs < seg.startMs || tMs >= seg.endMs) continue;
+      const tr = seg.transition;
+      const prev = i > 0 ? resolved[i - 1] : void 0;
+      const enterEnd = tr ? seg.startMs + Math.max(0, tr.durationMs) : seg.startMs;
+      const inEnter = tr && tr.durationMs > 0 && tMs < enterEnd && prev;
+      if (!inEnter) {
+        plan.push({ segIndex: i, drawTMs: tMs, env: null });
+        continue;
+      }
+      const p = transitionProgress(tMs, seg.startMs, tr.durationMs, tr.easing ?? easeInOut);
+      const { incoming, outgoing } = transitionEnvs(tr, p);
+      const heldTMs = clamp(tMs, prev.startMs, prev.endMs - 1);
+      plan.push({ segIndex: i - 1, drawTMs: heldTMs, env: outgoing });
+      plan.push({ segIndex: i, drawTMs: tMs, env: incoming });
+    }
+    return plan;
+  }
+  function drawSegmentInto(target, segIndex, drawTMs) {
+    const ctx = { ...baseCtx, ctx2d: target };
+    const cam = camera(drawTMs);
+    target.save();
+    applyToContext(target, 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);
+      if (b.segIndex !== segIndex || b.screenPinned) continue;
+      if (drawTMs < b.startMs || drawTMs >= b.endMs) continue;
+      b.layer.draw(ctx, drawTMs);
     }
-    ctx2d.restore();
+    target.restore();
+    target.save();
+    target.setTransform(1, 0, 0, 1, 0, 0);
+    for (const b of bound) {
+      if (b.segIndex !== segIndex || !b.screenPinned) continue;
+      if (drawTMs < b.startMs || drawTMs >= b.endMs) continue;
+      b.layer.draw(ctx, drawTMs);
+    }
+    target.restore();
+  }
+  function compositeEntry(ctx2d, e) {
+    if (e.env === null) {
+      drawSegmentInto(ctx2d, e.segIndex, e.drawTMs);
+      return;
+    }
+    const env = e.env;
+    if (!bufferFactory) {
+      ctx2d.save();
+      ctx2d.globalAlpha = ctx2d.globalAlpha * env.alpha;
+      drawSegmentInto(ctx2d, e.segIndex, e.drawTMs);
+      ctx2d.restore();
+      return;
+    }
+    const buf = bufferFactory(W, H);
+    drawSegmentInto(buf.ctx, e.segIndex, e.drawTMs);
     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);
+    if (env.alpha !== 1) ctx2d.globalAlpha = ctx2d.globalAlpha * env.alpha;
+    if (env.clip) {
+      ctx2d.beginPath();
+      ctx2d.rect(env.clip.x, env.clip.y, env.clip.w, env.clip.h);
+      ctx2d.clip();
     }
+    ctx2d.drawImage(buf.image, env.dx, env.dy, W, H);
     ctx2d.restore();
   }
+  function renderFrame(ctx2d, tMs) {
+    clock.nowMs = () => tMs;
+    const ctx = { ...baseCtx, ctx2d };
+    const cam = camera(tMs);
+    if (!hasTransitions) {
+      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;
+    }
+    const plan = frameplan(tMs);
+    for (const e of plan) compositeEntry(ctx2d, e);
+  }
   function scheduleAudio(instrument, baseSec) {
     let fired = 0;
     for (const seg of resolved) {
@@ -3327,6 +3486,7 @@ export {
   staffAnchor,
   staffKeyboardRayFactory,
   staffRayDemoSpec,
+  transitionProgress,
   validateChordTrack,
   validateQuiz,
   validateSections,