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

package/dist/scene/index.d.ts

@@ -69,15 +69,6 @@ interface ScoreFromMusicXMLOpts {
  */
 declare function scoreFromMusicXML(xml: string, opts?: ScoreFromMusicXMLOpts): Promise<Score>;
 
-/**
- * Install jsdom globals + a fake 2D canvas context so OSMD can `load()` a score
- * headlessly. Idempotent. Call once before constructing an OSMD instance in Node.
- *
- * No-ops if `window`/`document` already exist (e.g. a real browser, or a vitest
- * jsdom environment), so it is safe to call unconditionally.
- */
-declare function setupHeadlessDom(): Promise<void>;
-
 /**
  * Audio clock the runner exposes to layers. `nowMs` is the current playback
  * position in milliseconds (audio-clock-driven, NOT wall-clock). During an
@@ -149,6 +140,83 @@ interface LayerFactory<P = unknown> {
     validateProps(props: unknown): string[];
 }
 
+/** One scheduled audio event, in seconds RELATIVE to the schedule start. */
+interface AudioEvent {
+    /** Offset from schedule start, seconds. */
+    atSec: number;
+    /** Pitch (note name or frequency) for tonal hits; omitted for noise clicks. */
+    note?: string | number;
+    /** Duration, seconds. Default short. */
+    durSec?: number;
+    /** Linear gain 0..1. Default 1. */
+    gain?: number;
+    /** Tag for tests/debugging: "count" | "click" | "drone". */
+    kind: 'count' | 'click' | 'drone';
+}
+interface CountInOpts {
+    /** Beats to count (default 4 — a full bar of 4/4). */
+    beats?: number;
+    /** Tempo for the count, bpm. */
+    bpm: number;
+    /** Accent the downbeat (beat 1) with a higher pitch. Default true. */
+    accentDownbeat?: boolean;
+}
+/**
+ * The count-in schedule: one click per beat, starting at t=0, ending exactly on
+ * the downbeat of bar 1 (i.e. the music starts at `beats * 60/bpm` seconds).
+ * Pure.
+ */
+declare function countInSchedule(opts: CountInOpts): AudioEvent[];
+/** Seconds after t=0 that the music should start, for a given count-in. */
+declare function countInLeadSec(opts: CountInOpts): number;
+interface ClickTrackOpts {
+    bpm: number;
+    /** Total duration to fill with clicks, seconds. */
+    durationSec: number;
+    /** Beats per bar, for downbeat accents. Default 4. */
+    beatsPerBar?: number;
+    /** Start offset, seconds. Default 0. */
+    startSec?: number;
+}
+/** A click on every beat across `durationSec`, accenting each bar's downbeat. */
+declare function clickTrackSchedule(opts: ClickTrackOpts): AudioEvent[];
+interface DroneOpts {
+    /** Root pitch of the pad (e.g. "C2"). */
+    root: string;
+    /** Pad duration, seconds. */
+    durationSec: number;
+    /** Add a perfect fifth above the root. Default true. */
+    fifth?: boolean;
+    /** Bed gain 0..1. Default 0.15 (sits well under the melody). */
+    gain?: number;
+}
+/** A sustained root (+fifth) pad for the whole clip. */
+declare function droneSchedule(opts: DroneOpts): AudioEvent[];
+interface DuckWindow {
+    /** Voice-over window start, seconds. */
+    startSec: number;
+    /** Voice-over window end, seconds. */
+    endSec: number;
+}
+/**
+ * Gain envelope for a music/bed bus that ducks under voice-over windows. Returns
+ * the linear gain 0..1 at time `tSec`: `floor` inside a window (after a short
+ * attack ramp), 1 outside (after a release ramp). Pure — feed it to a Tone
+ * Gain's `.gain.value` per frame, or sample it to build a ramp automation.
+ */
+declare function duckGainAt(windows: DuckWindow[], tSec: number, floor?: number, rampSec?: number): number;
+/**
+ * Trigger a computed schedule on a Tone instrument at `startTime` (audio-clock
+ * seconds, e.g. `Tone.now()` or sampler.audioNow()). Thin glue over the existing
+ * sampler/synth — no new mastering bus. Tonal events use triggerAttackRelease;
+ * the instrument is whatever the caller wires into the promo mastering chain.
+ *
+ * Returns the number of events fired (handy for tests/gate sanity).
+ */
+declare function applySchedule(instrument: {
+    triggerAttackRelease: (note: any, dur: any, time?: any, velocity?: any) => void;
+}, schedule: AudioEvent[], startTime: number): number;
+
 declare const clamp: (x: number, lo: number, hi: number) => number;
 declare const lerp: (a: number, b: number, t: number) => number;
 /** Inverse-lerp: where does `x` sit in [a,b] as 0..1 (clamped, a===b -> 0). */
@@ -218,10 +286,52 @@ interface SpecLayer {
     /** Props passed to the layer's init(). */
     p?: unknown;
 }
+/**
+ * Optional per-segment audio. Lets a segment SCHEDULE sound at its own start
+ * time during capture — the seam that lets per-scene / sequential-audio apps
+ * (RET templates schedule `engine.playNote` in a scene's `onEnter`; whozart's
+ * "listen" scenes play a phrase when the scene begins) run on the same runner
+ * instead of staying bespoke. Everything here is OPTIONAL and the runner stays
+ * pure-visual when it's absent (fully backward-compatible).
+ *
+ * Two complementary forms, both resolved against the CAPTURE clock (not
+ * wall-clock) so they fire at the right offset in an offline/deterministic
+ * render:
+ *  - `schedule`: declarative `AudioEvent`s whose `atSec` is relative to the
+ *    segment's start. Played through the same Tone sampler/mastering bus via the
+ *    existing `applySchedule` glue (so timing == captureStart + segStart + atSec).
+ *  - `onEnter(audioClock, ctx)`: an imperative escape hatch fired once at the
+ *    segment's start time, handed the audio clock anchored to that start (its
+ *    `nowMs()` returns the segment's absolute start ms) so the callback can do
+ *    its own `triggerAttackRelease(note, dur, audioClock.nowMs()/1000 + …)`.
+ */
+interface SegmentAudio {
+    /** Declarative events; `atSec` is relative to the segment's start. */
+    schedule?: AudioEvent[];
+    /** Imperative hook fired once at the segment's start during capture. */
+    onEnter?: (audioClock: AudioClock, ctx: SegmentAudioCtx) => void;
+}
+/** Context handed to a `SegmentAudio.onEnter` callback. */
+interface SegmentAudioCtx {
+    /** The Tone instrument wired into the promo mastering chain (has
+     *  `triggerAttackRelease`). Same target `applySchedule` plays through. */
+    instrument: ScheduleTarget;
+    /** Absolute capture-clock seconds at which this segment starts (= the audio
+     *  base time + the segment's resolved start). Add your own offsets to this. */
+    startSec: number;
+    /** The render Score, if any (timing/pitch source). */
+    score?: Score;
+}
+/** Minimal Tone-instrument surface the audio scheduler needs. */
+interface ScheduleTarget {
+    triggerAttackRelease: (note: unknown, dur: unknown, time?: unknown, velocity?: unknown) => void;
+}
 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;
 }
 interface SceneSpec {
     /** [width, height] px. */
@@ -246,6 +356,7 @@ interface ResolvedSegment {
     startMs: number;
     endMs: number;
     layers: SpecLayer[];
+    audio?: SegmentAudio;
 }
 /** Resolve every segment's [start,end] to ms against the total clip length. */
 declare function resolveTimeline(spec: SceneSpec, totalSec: number): ResolvedSegment[];
@@ -263,6 +374,17 @@ interface BuiltScene {
     dispose(): void;
     /** The resolved timeline (for the gate / diagnostics). */
     resolved: ResolvedSegment[];
+    /**
+     * Schedule every segment's optional audio against the CAPTURE clock. Call once
+     * at capture start, passing the Tone instrument (the promo sampler) and the
+     * audio-clock base time in SECONDS (e.g. `sampler.audioNow()` / `Tone.now()`).
+     * Each segment's events fire at `baseSec + segStartMs/1000 + atSec`; each
+     * `onEnter` fires once with an AudioClock anchored to its segment start.
+     * Deterministic w.r.t. the supplied base time (no wall-clock). No-op for specs
+     * that declare no segment audio. Returns the count of events scheduled (handy
+     * for tests/gate sanity).
+     */
+    scheduleAudio(instrument: ScheduleTarget, baseSec: number): number;
 }
 interface BuildSceneOpts {
     spec: SceneSpec;
@@ -289,6 +411,21 @@ interface RecordSceneSpecOpts {
     onProgress?: RecordOpts['onProgress'];
     /** Inject the recorder for tests. Defaults to recordScenes. */
     record?: (scenes: Scene[], o: RecordOpts) => Promise<Blob>;
+    /**
+     * OPTIONAL per-segment audio scheduling. When a spec declares segment audio
+     * (SegmentAudio), pass the Tone instrument (the promo sampler) and a clock so
+     * the runner can schedule each segment's sound against the capture timeline.
+     * `audioNow()` returns the audio-clock seconds at capture start (e.g.
+     * `sampler.audioNow()` / `Tone.now()`); `lookaheadSec` (default 0.1) shifts
+     * the whole schedule forward a touch so the first event isn't already in the
+     * past when the recorder spins up. Omit entirely → pure-visual capture
+     * (unchanged behavior).
+     */
+    segmentAudio?: {
+        instrument: ScheduleTarget;
+        audioNow: () => number;
+        lookaheadSec?: number;
+    };
 }
 /**
  * Capture a built scene to a Blob by wrapping the whole timeline as a SINGLE
@@ -373,83 +510,6 @@ interface CaptionStyle {
  */
 declare function drawCaption(ctx: CanvasRenderingContext2D, script: CaptionScript, tMs: number, safe: SafeBox, theme: PromoTheme, style?: CaptionStyle): void;
 
-/** One scheduled audio event, in seconds RELATIVE to the schedule start. */
-interface AudioEvent {
-    /** Offset from schedule start, seconds. */
-    atSec: number;
-    /** Pitch (note name or frequency) for tonal hits; omitted for noise clicks. */
-    note?: string | number;
-    /** Duration, seconds. Default short. */
-    durSec?: number;
-    /** Linear gain 0..1. Default 1. */
-    gain?: number;
-    /** Tag for tests/debugging: "count" | "click" | "drone". */
-    kind: 'count' | 'click' | 'drone';
-}
-interface CountInOpts {
-    /** Beats to count (default 4 — a full bar of 4/4). */
-    beats?: number;
-    /** Tempo for the count, bpm. */
-    bpm: number;
-    /** Accent the downbeat (beat 1) with a higher pitch. Default true. */
-    accentDownbeat?: boolean;
-}
-/**
- * The count-in schedule: one click per beat, starting at t=0, ending exactly on
- * the downbeat of bar 1 (i.e. the music starts at `beats * 60/bpm` seconds).
- * Pure.
- */
-declare function countInSchedule(opts: CountInOpts): AudioEvent[];
-/** Seconds after t=0 that the music should start, for a given count-in. */
-declare function countInLeadSec(opts: CountInOpts): number;
-interface ClickTrackOpts {
-    bpm: number;
-    /** Total duration to fill with clicks, seconds. */
-    durationSec: number;
-    /** Beats per bar, for downbeat accents. Default 4. */
-    beatsPerBar?: number;
-    /** Start offset, seconds. Default 0. */
-    startSec?: number;
-}
-/** A click on every beat across `durationSec`, accenting each bar's downbeat. */
-declare function clickTrackSchedule(opts: ClickTrackOpts): AudioEvent[];
-interface DroneOpts {
-    /** Root pitch of the pad (e.g. "C2"). */
-    root: string;
-    /** Pad duration, seconds. */
-    durationSec: number;
-    /** Add a perfect fifth above the root. Default true. */
-    fifth?: boolean;
-    /** Bed gain 0..1. Default 0.15 (sits well under the melody). */
-    gain?: number;
-}
-/** A sustained root (+fifth) pad for the whole clip. */
-declare function droneSchedule(opts: DroneOpts): AudioEvent[];
-interface DuckWindow {
-    /** Voice-over window start, seconds. */
-    startSec: number;
-    /** Voice-over window end, seconds. */
-    endSec: number;
-}
-/**
- * Gain envelope for a music/bed bus that ducks under voice-over windows. Returns
- * the linear gain 0..1 at time `tSec`: `floor` inside a window (after a short
- * attack ramp), 1 outside (after a release ramp). Pure — feed it to a Tone
- * Gain's `.gain.value` per frame, or sample it to build a ramp automation.
- */
-declare function duckGainAt(windows: DuckWindow[], tSec: number, floor?: number, rampSec?: number): number;
-/**
- * Trigger a computed schedule on a Tone instrument at `startTime` (audio-clock
- * seconds, e.g. `Tone.now()` or sampler.audioNow()). Thin glue over the existing
- * sampler/synth — no new mastering bus. Tonal events use triggerAttackRelease;
- * the instrument is whatever the caller wires into the promo mastering chain.
- *
- * Returns the number of events fired (handy for tests/gate sanity).
- */
-declare function applySchedule(instrument: {
-    triggerAttackRelease: (note: any, dur: any, time?: any, velocity?: any) => void;
-}, schedule: AudioEvent[], startTime: number): number;
-
 interface GateError {
     check: 'av-duration' | 'placement' | 'fonts' | 'spec' | 'output';
     message: string;
@@ -947,4 +1007,462 @@ interface PromoCardsDemoOpts {
 /** Build the demo SceneSpec wiring the S4 wrapper layers across a timeline. */
 declare function promoCardsDemoSpec(opts?: PromoCardsDemoOpts): SceneSpec;
 
-export { type Affine, type AudioClock, type AudioEvent, type BackgroundProps, type BrandingProps, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ClickTrackOpts, type ColorBy, type CountInOpts, type CtaProps, type DroneOpts, type DuckWindow, type Easing, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type GateError, type GateInput, type HandColors, type HighlightRegion, type HookProps, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type Layer, type LayerFactory, type NotationEngraving, type NotationLayout, type NotationLayoutOpts, type NotationProps, type NotationRect, type OutputProbe, PIANO_HIGH, PIANO_LOW, type Placement, type PlayheadLine, type PortraitProps, type PromoCardsDemoOpts, type RecordSceneSpecOpts, type Rect, type RenderCtx, type ResolvedSegment, type RevealProps, type SafeGuidesProps, type SceneSpec, type Score, type ScoreFromMusicXMLOpts, type ScoreNote, type ScrollCursorProps, type SpecLayer, type SpectrumInput, type SpectrumProps, type TempoMap, type TimeAnchor, type TimelineSegment, 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 };
+interface StaffKeyboardRayProps {
+    /** Layer key of the notation layer to link (forward-compat; v1 uses the single
+     *  published engraving). Default "notation". */
+    notationKey?: string;
+    /** Layer key of the keyboard layer to link. Default "keyboard". */
+    keyboardKey?: string;
+    /** Ray reveal/grow + fade duration, ms. Default 180. */
+    fadeMs?: number;
+    /** Line width, world px. Default 4. */
+    width?: number;
+    /** Ray colour (default per-note hand colour via the theme accent). */
+    color?: string;
+    /** Number of segments to approximate the curve. Default 24. */
+    segments?: number;
+}
+declare const staffKeyboardRayFactory: LayerFactory<StaffKeyboardRayProps>;
+
+interface RayEndpoints {
+    /** Staff-end point (screen px). */
+    staff: {
+        x: number;
+        y: number;
+    };
+    /** Keyboard-end point (screen px) = the top-centre of the key. */
+    keyboard: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * The staff-end anchor for an audio progress `t01` (0..1 over the clip), using the
+ * playhead sweep across the notation's mapped measure columns. Mirrors
+ * notationGeometry.playheadLine's x/y derivation so the ray starts exactly where
+ * the playhead is. Returns null when the layout has no measures/systems.
+ */
+declare function staffAnchor(layout: NotationLayout, t01: number): {
+    x: number;
+    y: number;
+} | null;
+/**
+ * Full ray endpoints for a note's pitch + an audio progress, given both layouts.
+ * The keyboard end is the top-centre of the note's key. Pure.
+ */
+declare function rayEndpoints(notation: NotationLayout, keyboard: KeyboardLayout, pitchMidi: number, t01: number): RayEndpoints | null;
+/**
+ * A point along a quadratic Bézier from staff→keyboard, bulged toward the side, at
+ * parameter `u` 0..1. Used to draw a gently curved ray (a straight line reads as a
+ * cursor; a curve reads as a connector). Pure.
+ */
+declare function rayPointAt(ends: RayEndpoints, u: number, bulge?: number): {
+    x: number;
+    y: number;
+};
+
+interface CountingTrackProps {
+    /** Subdivisions per beat shown: 1 (just numbers), 2 ("&"), 4 ("e & a"). Default 1. */
+    subdiv?: 1 | 2 | 4;
+    /** Override time signature (else Score.timeSig, else 4/4). */
+    timeSig?: string;
+    /** Override bpm (else Score.tempoMap, else 100). */
+    bpm?: number;
+    /** Track baseline (world y) the ball lands on. Default safeBox.bottom - 120. */
+    trackY?: number;
+    /** Bounce height in world px. Default 110. */
+    bounce?: number;
+    /** Syllable font size, world px. Default 34. */
+    size?: number;
+    /** Ball radius, world px. Default 22. */
+    ballRadius?: number;
+    /** Count-in offset, ms (first beat lands here). Default 0. */
+    startMs?: number;
+}
+declare const countingTrackFactory: LayerFactory<CountingTrackProps>;
+
+interface BeatGridOpts {
+    /** Constant bpm of the QUARTER-note beat (tempoMap.segments[0].bpm). */
+    bpm: number;
+    /** Beats per bar (time-sig numerator). Default 4. */
+    beatsPerBar?: number;
+    /** Time-sig denominator (note value of one beat). Default 4. */
+    beatUnit?: number;
+    /** Subdivisions per beat for the syllable row: 1, 2 ("&"), or 4 ("e & a"). Default 1. */
+    subdiv?: 1 | 2 | 4;
+    /** Total length to cover, ms. */
+    durationMs: number;
+    /** Count-in offset: first beat lands at this ms (default 0). */
+    startMs?: number;
+}
+interface BeatTick {
+    /** Onset time, ms. */
+    tMs: number;
+    /** 0-based beat index across the whole clip. */
+    index: number;
+    /** 1-based beat number within the bar (the big counted number). */
+    beatInBar: number;
+    /** Subdivision index within the beat (0 = on the beat). */
+    sub: number;
+    /** The counting syllable ("1","e","&","a", "2", …). */
+    syllable: string;
+    /** True on the downbeat (beatInBar === 1, sub === 0). */
+    downbeat: boolean;
+}
+/** ms between quarter beats; the beat-unit scales it (eighth beat = half a quarter). */
+declare function msPerBeat(bpm: number, beatUnit: number): number;
+/** Build the full beat+subdivision schedule across the clip. Pure. */
+declare function beatGrid(opts: BeatGridOpts): BeatTick[];
+/** The TempoMap's first-segment bpm (v1 single-tempo helper). */
+declare function bpmOf(tempoMap: TempoMap | undefined, fallback?: number): number;
+/**
+ * Phase 0..1 within the current beat at time `tMs` (0 = on the beat). Pure.
+ * Used by the bouncing ball's vertical position.
+ */
+declare function beatPhase(bpm: number, beatUnit: number, tMs: number, startMs?: number): number;
+/**
+ * The bouncing ball's vertical offset 0..1 (0 = at the track line / floor, 1 =
+ * top of the arc). A parabola that touches 0 exactly ON each beat and peaks at
+ * mid-beat — so the ball "lands" on the count. Pure.
+ */
+declare function ballArc(phase01: number): number;
+/** Horizontal x (world) of the ball at time t, sweeping left→right across the
+ *  counting track in step with the beats. Pure. */
+declare function ballX(ticks: BeatTick[], tMs: number, xOf: (tick: BeatTick) => number): number;
+/** Parse a "n/d" time signature string into [numerator, denominator]. */
+declare function parseTimeSig(ts: string | undefined): [number, number];
+
+type LabelMode = 'degree' | 'solfege';
+interface DegreeLabel {
+    /** Diatonic degree 1..7 (the letter-distance from the tonic letter). */
+    degree: number;
+    /** Chromatic inflection in semitones vs the diatonic degree (−1 flat, +1 sharp, 0 natural). */
+    alter: number;
+    /** The display text for the chosen mode. */
+    text: string;
+}
+/** Parse a key string ("Eb major" / "C# minor" / "F") into a tonic letter + mode. */
+declare function parseKey(key: string | undefined): {
+    tonicLetter: string;
+    tonicPc: number;
+    minor: boolean;
+};
+/**
+ * Compute the scale-degree label for a note, from its NOTATED spelling.
+ *
+ * `degree` = the letter distance (1..7) from the tonic letter to the note's
+ * letter, which is the enharmonically-correct diatonic degree. `alter` = how the
+ * note's actual pitch class differs from that degree's pitch in the key
+ * (so D♯ vs D♭ in C give the same degree 2 but +1 / −1). For MINOR keys the
+ * reference scale is natural minor (so the lowered 3/6/7 read as natural degrees,
+ * matching how movable-do "la-based minor" is taught only in MAJOR; here we use
+ * do-based, i.e. degrees relative to the major scale of the tonic — see note).
+ *
+ * Pure.
+ */
+declare function degreeLabel(step: string, alter: number, pitchMidi: number, key: string | undefined, mode: LabelMode): DegreeLabel;
+
+interface DegreeLabelsProps {
+    /** "degree" = scale-degree numbers (1..7, ♯/♭ chromatics); "solfege" =
+     *  movable-do syllables (do re mi …, di ra …). Default "degree". */
+    mode?: LabelMode;
+    /** Override the Score's key (e.g. for an excerpt in a different key). */
+    key?: string;
+    /** Label font size in world px. Default 30. */
+    size?: number;
+    /** Fade in/out of a label, ms. Default 120. */
+    fadeMs?: number;
+    /** Text colour. Default theme.ink on a translucent chip. */
+    color?: string;
+}
+declare const degreeLabelsFactory: LayerFactory<DegreeLabelsProps>;
+
+type HarmonicFunction = 'T' | 'S' | 'D' | 'other';
+interface ChordSpan {
+    /** Span start, ms. */
+    startMs: number;
+    /** Span end, ms. */
+    endMs: number;
+    /** Tonal function. */
+    fn: HarmonicFunction;
+    /** Optional display label (roman numeral / chord symbol), drawn by the layer. */
+    label?: string;
+}
+/** Default function colours (warm tonic / cool subdominant / tense dominant). */
+interface FunctionColors {
+    T: string;
+    S: string;
+    D: string;
+    other: string;
+}
+declare const DEFAULT_FUNCTION_COLORS: FunctionColors;
+/** The chord span active at time `tMs` (first whose [start,end) contains t), or null. */
+declare function activeChord(track: ChordSpan[], tMs: number): ChordSpan | null;
+/** Colour for a function. Pure. */
+declare function functionColor(fn: HarmonicFunction, colors: FunctionColors): string;
+/**
+ * Validate a chord track (used by the layer's prop validator). Returns []
+ * when valid, else human-readable errors. Exported so the gate message is precise.
+ */
+declare function validateChordTrack(track: unknown): string[];
+
+type HarmonyMode = 'band' | 'keys' | 'wash';
+interface FunctionalHarmonyProps {
+    /** REQUIRED: the timed chord spans (function + optional label). Host-supplied. */
+    chordTrack: ChordSpan[];
+    /** Which renderings to draw. Default ["band"]. */
+    modes?: HarmonyMode[];
+    /** Override the function→colour map. */
+    colors?: FunctionColors;
+    /** Band height (world px). Default 64. */
+    bandHeight?: number;
+    /** Band top (world y). Default safeBox.top. */
+    bandTop?: number;
+    /** Cross-fade between spans, ms. Default 200. */
+    fadeMs?: number;
+    /** Wash opacity at full intensity. Default 0.12. */
+    washAlpha?: number;
+}
+declare const functionalHarmonyFactory: LayerFactory<FunctionalHarmonyProps>;
+
+interface QuizOption {
+    /** Option text (e.g. "Major 3rd", "Beethoven"). */
+    text: string;
+}
+interface Quiz {
+    /** The prompt ("Which interval?" / "Name this piece"). */
+    question: string;
+    /** 2–4 options. */
+    options: QuizOption[];
+    /** Index into options of the correct answer (0-based). */
+    correctIndex: number;
+    /** When the card starts asking (absolute ms). Default 0. */
+    askMs?: number;
+    /** When the correct option is revealed (absolute ms). REQUIRED. */
+    revealMs: number;
+    /** When the card finishes (absolute ms). REQUIRED. */
+    endMs: number;
+    /** Optional per-option poll percentages (0..100), shown as bars. Length must
+     *  match options. Host-supplied (e.g. real community votes); not fabricated. */
+    poll?: number[];
+}
+type QuizPhase = 'before' | 'question' | 'reveal' | 'after';
+/** Resolve the card phase at time `tMs`. Pure. */
+declare function quizPhase(quiz: Quiz, tMs: number): QuizPhase;
+/**
+ * Countdown fraction remaining 0..1 across [askMs, revealMs] (1 at ask, 0 at
+ * reveal), clamped outside. Drives the countdown ring/bar. Pure.
+ */
+declare function countdownRemaining(quiz: Quiz, tMs: number): number;
+/**
+ * Integer seconds remaining on the countdown (ceil), for the big number. Pure.
+ */
+declare function countdownSeconds(quiz: Quiz, tMs: number): number;
+/**
+ * Reveal progress 0..1 across a short window after revealMs (for a pop/fade of
+ * the correct option). `windowMs` default 350. Pure.
+ */
+declare function revealProgress(quiz: Quiz, tMs: number, windowMs?: number): number;
+/**
+ * Validate a Quiz prop (used by the layer's validator + the pre-render gate).
+ * Returns [] when valid, else human-readable errors. The card REQUIRES this prop;
+ * it has no data otherwise.
+ */
+declare function validateQuiz(quiz: unknown): string[];
+
+interface Section {
+    /** Section start, ms. */
+    startMs: number;
+    /** Section end, ms. */
+    endMs: number;
+    /** Display label ("Verse", "A", "Exposition"). */
+    label?: string;
+}
+/** Progress 0..1 along the clip at time t. Pure. */
+declare function progress01(durationMs: number, tMs: number): number;
+/** x of a time on a [left, left+width] bar across [0, durationMs]. Pure. */
+declare function timeToX(left: number, width: number, durationMs: number, tMs: number): number;
+/** The section containing time t (first whose [start,end) holds t), or null. Pure. */
+declare function activeSection(sections: Section[], tMs: number): Section | null;
+/**
+ * Build uniform measure-span sections from a measure count + total duration (a
+ * fallback when no explicit sections are given but a measure count is). Each
+ * section is one measure, labelled by 1-based measure number. Pure.
+ */
+declare function measureSpans(measureCount: number, durationMs: number): Section[];
+/**
+ * Validate a sections array (used by the layer validator). Returns [] when valid.
+ */
+declare function validateSections(sections: unknown): string[];
+
+interface ExtendedDemoOpts {
+    size?: [number, number];
+    theme?: string;
+}
+/** Counting track + bouncing ball + scale-degree labels over a keyboard. */
+declare function countingDegreeDemoSpec(opts?: ExtendedDemoOpts & {
+    subdiv?: 1 | 2 | 4;
+    labelMode?: LabelMode;
+    range?: '88' | 'auto';
+}): SceneSpec;
+/** Staff↔keyboard ray over a (pre-rendered) notation + keyboard. */
+declare function staffRayDemoSpec(rendered: RenderedNotation, opts?: ExtendedDemoOpts & {
+    range?: '88' | 'auto';
+}): SceneSpec;
+/** Functional-harmony coloring (band + keys) over a keyboard, driven by a chord track. */
+declare function harmonyDemoSpec(chordTrack: ChordSpan[], opts?: ExtendedDemoOpts & {
+    range?: '88' | 'auto';
+}): SceneSpec;
+/** MCQ poll card over a plain background (RET quiz / whozart name-that-piece). */
+declare function mcqDemoSpec(quiz: Quiz, opts?: ExtendedDemoOpts): SceneSpec;
+/** Circle-of-fifths widget (optionally animating a modulation). */
+declare function circleOfFifthsDemoSpec(opts?: ExtendedDemoOpts & {
+    toKey?: string;
+    fromMs?: number;
+    toMs?: number;
+}): SceneSpec;
+/** Pitch-contour line over the melody (Score.notes) + a section minimap. */
+declare function contourMinimapDemoSpec(opts?: ExtendedDemoOpts & {
+    sections?: Section[];
+    measureCount?: number;
+}): SceneSpec;
+
+interface McqCardProps {
+    /** REQUIRED: the host-supplied quiz (question/options/correctIndex/timings). */
+    quiz: Quiz;
+    /** Accent for the correct reveal (default theme.accent). */
+    correctColor?: string;
+    /** Show the poll bars (only if quiz.poll is present). Default true. */
+    showPoll?: boolean;
+}
+declare const mcqCardFactory: LayerFactory<McqCardProps>;
+
+interface CircleOfFifthsProps {
+    /** Override the highlighted key (else Score.key, else C). */
+    key?: string;
+    /** Animate the highlight to this key (modulation target). Host-supplied. */
+    toKey?: string;
+    /** Modulation start time (ms). Required if toKey is set. */
+    fromMs?: number;
+    /** Modulation end time (ms). Required if toKey is set. */
+    toMs?: number;
+    /** Widget centre [x,y] (world). Default centred in the safe box. */
+    center?: [number, number];
+    /** Outer radius (world px). Default min(safe.w, safe.h) * 0.32. */
+    radius?: number;
+    /** Show the relative-minor inner ring. Default true. */
+    showMinor?: boolean;
+    /** Highlight colour (default theme.accent). */
+    color?: string;
+}
+declare const circleOfFifthsFactory: LayerFactory<CircleOfFifthsProps>;
+
+/** Major-key labels around the circle, clockwise from the top. */
+declare const FIFTHS_MAJOR: string[];
+/** Relative-minor labels (inner ring), aligned to the same slots. */
+declare const FIFTHS_MINOR: string[];
+/** Pitch class at circle slot i (0..11), clockwise fifths from C. */
+declare function slotPc(i: number): number;
+/** The circle slot (0..11) for a tonic pitch class. Pure. */
+declare function pcToSlot(pc: number): number;
+/** The circle slot for a key string ("G major" / "Eb"). Pure. */
+declare function keySlot(key: string | undefined): number;
+/** Angle (radians, 0 = up/12-o'clock, clockwise +) of circle slot i. Pure. */
+declare function slotAngle(i: number): number;
+interface CirclePoint {
+    x: number;
+    y: number;
+}
+/** Cartesian point for a slot on a circle of radius r centred at (cx,cy).
+ *  0 rad = straight up, increasing clockwise. Pure. */
+declare function slotPoint(cx: number, cy: number, r: number, i: number): CirclePoint;
+/**
+ * Animated highlight slot as a fractional position from a source slot to a target
+ * slot over progress `t01`, taking the SHORTEST way around the wheel. Returns a
+ * fractional slot (e.g. 1.5 = between G and D). Pure.
+ */
+declare function animatedSlot(fromSlot: number, toSlot: number, t01: number): number;
+/** Cartesian point for a FRACTIONAL slot (e.g. mid-modulation) on the circle.
+ *  Pure. */
+declare function fracSlotPoint(cx: number, cy: number, r: number, frac: number): CirclePoint;
+
+interface PitchContourProps {
+    /** Plot band top (world y). Default safeBox.top + safeBox.h * 0.15. */
+    top?: number;
+    /** Plot band height (world px). Default safeBox.h * 0.35. */
+    height?: number;
+    /** Line width (world px). Default 5. */
+    width?: number;
+    /** Line colour (default theme.accent). */
+    color?: string;
+    /** Show the moving dot at the current pitch. Default true. */
+    dot?: boolean;
+    /** Dot radius (world px). Default 14. */
+    dotRadius?: number;
+}
+declare const pitchContourFactory: LayerFactory<PitchContourProps>;
+
+interface ContourPoint {
+    /** Onset time, ms. */
+    tMs: number;
+    /** MIDI pitch of the melody note at that onset. */
+    pitchMidi: number;
+}
+interface ContourPlot {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    minPitch: number;
+    maxPitch: number;
+    durationMs: number;
+}
+/**
+ * Reduce notes to one melody point per distinct onset = the highest sounding
+ * pitch at that onset. Returns points sorted by time. Pure.
+ */
+declare function contourPoints(notes: ScoreNote[]): ContourPoint[];
+/** Pitch range [min,max] of the points (with a 1-semitone pad, min span 2). Pure. */
+declare function pitchRange(points: ContourPoint[]): {
+    min: number;
+    max: number;
+};
+/** Project a (time,pitch) onto plot pixels. y is inverted (high pitch = up). Pure. */
+declare function projectPoint(plot: ContourPlot, tMs: number, pitchMidi: number): {
+    x: number;
+    y: number;
+};
+/** The full pixel polyline for the contour. Pure. */
+declare function contourPolyline(points: ContourPoint[], plot: ContourPlot): {
+    x: number;
+    y: number;
+}[];
+/**
+ * The melody pitch sounding at time `tMs`: the pitch of the most recent onset
+ * at-or-before t (step interpolation — a melody holds until the next note). Returns
+ * null before the first onset. Pure.
+ */
+declare function pitchAt(points: ContourPoint[], tMs: number): number | null;
+/** The moving-dot position at time t (rides the contour at the current pitch). Pure. */
+declare function dotAt(points: ContourPoint[], plot: ContourPlot, tMs: number): {
+    x: number;
+    y: number;
+} | null;
+
+interface SectionMinimapProps {
+    /** Host-supplied section spans. Takes precedence over measureCount. */
+    sections?: Section[];
+    /** Fallback: split the clip into this many uniform measure bands. */
+    measureCount?: number;
+    /** Bar baseline (world y). Default safeBox.bottom - 40. */
+    barY?: number;
+    /** Bar thickness (world px). Default 10. */
+    barHeight?: number;
+    /** Show the active section's label above the bar. Default true. */
+    showLabel?: boolean;
+    /** Accent for the played portion + dot (default theme.accent). */
+    color?: string;
+}
+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 };