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

package/dist/scene/index.d.ts

@@ -0,0 +1,950 @@
+import { PromoTheme, SafeBox, RecordOpts, Scene } from '../video.js';
+import { RenderedNotation, Box, StaffMeasureBox, MeasureColumnBox } from '../promo.js';
+
+interface ScoreNote {
+    /** MIDI note number (middle C = 60). */
+    pitchMidi: number;
+    /** Diatonic letter name: C D E F G A B. */
+    step: string;
+    /** Chromatic alteration in semitones: -1 flat, +1 sharp, 0 natural, ±2 double. */
+    alter: number;
+    /** Scientific octave (middle C = C4). */
+    octave: number;
+    /** Onset on the linear playback clock, in ms (repeats expanded). */
+    onsetMs: number;
+    /** Sounding duration in ms (tie chains merged). */
+    durMs: number;
+    /** Staff index within the whole sheet (0-based). */
+    staff: number;
+    /** Voice id within the part. */
+    voice: number;
+    /** Performing hand: grand-staff top -> "R", bottom -> "L" (see hand-inference stub). */
+    hand: 'L' | 'R';
+    /** Lyric syllable attached to this note, if any. */
+    lyric?: string;
+    /** Fingering digit attached to this note, if any. */
+    fingering?: number;
+}
+/**
+ * Tempo map. v1 is a single constant tempo (one segment at t=0). The piecewise
+ * shape is the documented seam for rubato / multiple `<sound tempo>` — see the
+ * tempo-map stub note in scoreFromMusicXML.
+ */
+interface TempoMap {
+    /** Where the tempo came from: the XML's notated tempo, the fallback, or an override. */
+    source: 'xml' | 'fallback' | 'override';
+    /** Piecewise-constant segments, ordered by onset. v1 always has exactly one (at 0). */
+    segments: Array<{
+        atMs: number;
+        bpm: number;
+    }>;
+}
+interface Score {
+    notes: ScoreNote[];
+    tempoMap: TempoMap;
+    /** End of the last sounding note, in ms. */
+    durationMs: number;
+    key?: string;
+    timeSig?: string;
+    title?: string;
+    composer?: string;
+}
+interface ScoreFromMusicXMLOpts {
+    /** bpm to use when the XML has no notated tempo (DefaultStartTempoInBpm === 0). Default 100. */
+    tempoFallback?: number;
+    /** Force this bpm regardless of the XML's notated tempo (per-recipe override). */
+    tempoOverride?: number;
+    /**
+     * Provide the OSMD instance. Defaults to a literal `import('opensheetmusicdisplay')`
+     * + a detached div (works in a browser, or in Node after `setupHeadlessDom()`).
+     * Inject for tests or non-DOM environments.
+     */
+    osmdFactory?: () => any;
+}
+/**
+ * Parse MusicXML into a timed, typed Score via OSMD's source model.
+ *
+ * @param xml  MusicXML document (uncompressed string; unzip .mxl first).
+ * @param opts tempoFallback / tempoOverride / osmdFactory.
+ */
+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
+ * offline/deterministic render the runner supplies the frame time directly, so
+ * `nowMs` and the `tMs` passed to `draw` agree.
+ */
+interface AudioClock {
+    /** Current playback position in ms. */
+    nowMs(): number;
+}
+/**
+ * Everything a layer needs to draw a frame. Constructed once per render and
+ * passed to every `init`/`draw`. World coordinates: layers draw in the frame's
+ * pixel space (0,0 top-left, W×H); the camera primitive (./camera) applies any
+ * pan/zoom transform to `ctx2d` BEFORE the layer's `draw` runs, so a layer never
+ * re-derives the viewport.
+ */
+interface RenderCtx {
+    /** The shared 2D context all layers draw onto. */
+    ctx2d: CanvasRenderingContext2D;
+    /** Frame width in px. */
+    W: number;
+    /** Frame height in px. */
+    H: number;
+    /** The parsed Score (timing/pitch/hands/lyrics). May be undefined for
+     *  non-musical scenes (a pure hook/CTA card). */
+    score?: Score;
+    /** Audio playback clock. */
+    audioClock: AudioClock;
+    /** Per-app theme tokens (colours/fonts/brand). */
+    theme: PromoTheme;
+    /** Phone-safe content rectangle (./video safeBox) — layers anchor to this
+     *  instead of re-deriving insets. */
+    safeBox: SafeBox;
+    /** Capture frame rate. */
+    fps: number;
+}
+/**
+ * A composable, time-synced render component.
+ *
+ * @typeParam P  the layer's prop type (what a SceneSpec passes as `p`).
+ */
+interface Layer<P = unknown> {
+    /** Stable identity, e.g. "notation" | "falling-notes" | "caption". */
+    readonly key: string;
+    /**
+     * One-time setup: load assets, lay out, rasterize an offscreen bitmap, etc.
+     * Runs before the first captured frame. May be async (e.g. font/IR load).
+     */
+    init(ctx: RenderCtx, props: P): void | Promise<void>;
+    /**
+     * Per-frame draw. MUST be cheap and a pure function of `tMs` (no rAF / wall
+     * clock). `tMs` is the absolute playback time in ms.
+     */
+    draw(ctx: RenderCtx, tMs: number): void;
+    /** Optional teardown (free bitmaps / audio nodes). */
+    dispose?(): void;
+}
+/**
+ * A layer factory keyed by name, with a runtime prop validator so the runner /
+ * pre-render gate can reject an unknown prop before capture (spec: "unknown
+ * layer/prop → fail fast"). `validateProps` returns an array of human-readable
+ * errors ([] = valid).
+ */
+interface LayerFactory<P = unknown> {
+    key: string;
+    create(): Layer<P>;
+    /** Validate a SceneSpec's `p` object. Return [] when valid. */
+    validateProps(props: unknown): string[];
+}
+
+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). */
+declare const invLerp: (a: number, b: number, x: number) => number;
+type Easing = (t: number) => number;
+declare const linear: Easing;
+/** Smoothstep ease-in-out. */
+declare const easeInOut: Easing;
+declare const easeIn: Easing;
+declare const easeOut: Easing;
+
+/** A rectangle in WORLD coordinates (the layers' natural pixel space). */
+interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A camera pose: which world point sits at the viewport centre, and the zoom. */
+interface CameraState {
+    /** World-space centre x. */
+    cx: number;
+    /** World-space centre y. */
+    cy: number;
+    /** Zoom factor (>1 = zoomed in). */
+    zoom: number;
+}
+/** A 2D affine transform `[a,b,c,d,e,f]` (matches CanvasRenderingContext2D.setTransform). */
+type Affine = [number, number, number, number, number, number];
+/**
+ * The world→viewport transform for a camera pose. We use a uniform scale = zoom
+ * and translate so (cx,cy) world maps to (W/2,H/2) viewport.
+ * world point (x,y) -> ( (x-cx)*zoom + W/2 , (y-cy)*zoom + H/2 ).
+ */
+declare function cameraTransform(cam: CameraState, W: number, H: number): Affine;
+/** Map a world point through a camera pose to viewport pixels. */
+declare function worldToViewport(cam: CameraState, W: number, H: number, x: number, y: number): {
+    x: number;
+    y: number;
+};
+/**
+ * The camera pose that frames `rect` to fill the W×H viewport (contain-fit:
+ * whole rect visible, uniform zoom). `pad` (0..1) leaves margin around the rect.
+ */
+declare function frameRect(rect: Rect, W: number, H: number, pad?: number): CameraState;
+/** Interpolate between two camera poses (for pan/zoom moves). */
+declare function lerpCamera(a: CameraState, b: CameraState, t01: number, ease?: Easing): CameraState;
+/**
+ * A Ken-Burns move: slow drift from `from` to `to` over a segment. `at` is the
+ * segment-relative position 0..1. Pure — returns the pose for that t.
+ */
+declare function kenBurns(from: CameraState, to: CameraState, at01: number): CameraState;
+/**
+ * Apply a camera pose to a 2D context (sets the transform). Layers drawn after
+ * this render in world coords and appear panned/zoomed. Pair with ctx.save()
+ * /ctx.restore() in the runner so layers can't leak the transform.
+ */
+declare function applyToContext(ctx: CanvasRenderingContext2D, cam: CameraState, W: number, H: number): void;
+/** The identity (no pan/zoom) camera: world == viewport. */
+declare function identityCamera(W: number, H: number): CameraState;
+
+/** A timeline endpoint: a number (ms? no — seconds), "end", or "end-N" (N s before end). */
+type TimeAnchor = number | 'end' | `end-${number}`;
+interface SpecLayer {
+    /** Registry key. */
+    k: string;
+    /** Props passed to the layer's init(). */
+    p?: unknown;
+}
+interface TimelineSegment {
+    /** [start, end] in SECONDS; end may be "end" / "end-N". */
+    at: [number, TimeAnchor];
+    layers: SpecLayer[];
+}
+interface SceneSpec {
+    /** [width, height] px. */
+    size: [number, number];
+    /** Theme key (resolved to a PromoTheme by the host) OR an inline theme. */
+    theme: string;
+    /** "audio" = clip length follows the audio; "fixed" = use `durationSec`. */
+    durationMode: 'audio' | 'fixed';
+    /** Required when durationMode === "fixed". */
+    durationSec?: number;
+    timeline: TimelineSegment[];
+    audio?: {
+        voicing?: string;
+        [k: string]: unknown;
+    };
+    /** Capture frame rate. Default 30. */
+    fps?: number;
+}
+/** Resolve a TimeAnchor to absolute seconds given the clip's total length. */
+declare function resolveAnchor(anchor: TimeAnchor, totalSec: number): number;
+interface ResolvedSegment {
+    startMs: number;
+    endMs: number;
+    layers: SpecLayer[];
+}
+/** Resolve every segment's [start,end] to ms against the total clip length. */
+declare function resolveTimeline(spec: SceneSpec, totalSec: number): ResolvedSegment[];
+/** The visual timeline length in ms = the latest resolved segment end. */
+declare function visualTimelineMs(resolved: ResolvedSegment[]): number;
+interface BuiltScene {
+    W: number;
+    H: number;
+    fps: number;
+    durationMs: number;
+    /** Draw the whole composite at absolute time `tMs` onto `ctx2d`. Deterministic
+     *  (pure fn of tMs). Used by tests, golden frames, and the recordScenes wrapper. */
+    renderFrame(ctx2d: CanvasRenderingContext2D, tMs: number): void;
+    /** Free every layer's resources. */
+    dispose(): void;
+    /** The resolved timeline (for the gate / diagnostics). */
+    resolved: ResolvedSegment[];
+}
+interface BuildSceneOpts {
+    spec: SceneSpec;
+    theme: PromoTheme;
+    /** The parsed Score (timing source). Optional for non-musical specs. */
+    score?: Score;
+    /** Total clip length in seconds. With durationMode "audio" pass the audio
+     *  length; with "fixed" it defaults to spec.durationSec. */
+    totalSec: number;
+    /** Override the camera pose per absolute tMs (pan/zoom director). Identity by
+     *  default. */
+    camera?: (tMs: number) => CameraState;
+}
+/**
+ * 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
+ * (so build failures surface before capture — the gate also re-checks).
+ */
+declare function buildScene(opts: BuildSceneOpts): Promise<BuiltScene>;
+interface RecordSceneSpecOpts {
+    built: BuiltScene;
+    audioStream: MediaStream;
+    background?: string;
+    onProgress?: RecordOpts['onProgress'];
+    /** Inject the recorder for tests. Defaults to recordScenes. */
+    record?: (scenes: Scene[], o: RecordOpts) => Promise<Blob>;
+}
+/**
+ * Capture a built scene to a Blob by wrapping the whole timeline as a SINGLE
+ * composite Scene and handing it to recordScenes — so audio sync, captureStream,
+ * and MediaRecorder all come from the existing, working path. recordScenes
+ * clears to `background` each frame and gives us a 0..1 t; we expand it back to
+ * absolute ms and call renderFrame.
+ */
+declare function recordSceneSpec(opts: RecordSceneSpecOpts): Promise<Blob>;
+
+/** Register (or replace) a layer factory under its key. */
+declare function registerLayer(factory: LayerFactory<any>): void;
+/** Look up a factory by key, or undefined if not registered. */
+declare function getLayerFactory(key: string): LayerFactory<any> | undefined;
+/** All registered layer keys (for diagnostics / gate messages). */
+declare function registeredKeys(): string[];
+
+interface HighlightRegion {
+    /** World x of the band's left edge. */
+    x: number;
+    /** World y of the band's top edge. */
+    y: number;
+    /** Band width (world px). */
+    w: number;
+    /** Band height (world px). */
+    h: number;
+    /** Show from this time (ms). */
+    inMs: number;
+    /** Hide after this time (ms). */
+    outMs: number;
+    /** Fade in/out duration (ms). Default 120. */
+    fadeMs?: number;
+    /** Fill colour (defaults to a translucent accent at draw time). */
+    color?: string;
+}
+/**
+ * Highlight intensity 0..1 at time `tMs`: 0 outside the window, ramping to 1
+ * across `fadeMs` at each edge, flat 1 in the middle. Pure.
+ */
+declare function highlightIntensity(region: HighlightRegion, tMs: number): number;
+/**
+ * Compute the world x-range covering a set of note onsets that fall inside a
+ * time window, given a time→x mapping. Returns null if none qualify. Useful for
+ * "spotlight the bar that's sounding now" without a layer re-deriving geometry.
+ */
+declare function noteSetXRange(onsetsMs: number[], windowMs: [number, number], timeToX: (ms: number) => number): {
+    x: number;
+    w: number;
+} | null;
+/**
+ * Draw a highlight band for the current time. No-op when intensity is 0, so it
+ * is safe to call every frame. Draws in WORLD coords (the camera transform, if
+ * any, is already on the context).
+ */
+declare function drawHighlight(ctx: CanvasRenderingContext2D, region: HighlightRegion, tMs: number, accent: string): void;
+
+interface CaptionCue {
+    text: string;
+    /** Show from this time (ms). */
+    inMs: number;
+    /** Hide after this time (ms). */
+    outMs: number;
+}
+type CaptionScript = CaptionCue[];
+/** The cue active at `tMs` (last one whose window contains t), or null. */
+declare function activeCue(script: CaptionScript, tMs: number): CaptionCue | null;
+/** Opacity 0..1 for a cue at `tMs` (short fade at both edges). */
+declare function cueOpacity(cue: CaptionCue, tMs: number, fadeMs?: number): number;
+interface CaptionStyle {
+    /** Font size in px. Default 44. */
+    size?: number;
+    /** Pinned vertical position as a fraction of the safe-box height from its
+     *  top. Default 0.92 (near the bottom of the safe area). */
+    yFrac?: number;
+    /** Draw a translucent backing pill for legibility. Default true. */
+    pill?: boolean;
+}
+/**
+ * Draw the active caption (if any) inside the safe box. Pure function of tMs.
+ * No-op when no cue is active. Drawn in VIEWPORT space (call after the camera
+ * transform has been reset to identity) so captions stay pinned to the screen.
+ */
+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;
+}
+/** A position a layer reports placing (for the placement-sanity check). */
+interface Placement {
+    /** Label for diagnostics (e.g. "note@1200ms"). */
+    label: string;
+    x: number;
+    y: number;
+    /** Whether this placement is REQUIRED to be inside the safe box. */
+    mustBeSafe?: boolean;
+}
+interface OutputProbe {
+    /** Frames the capture actually produced. */
+    frames: number;
+    /** Audio tracks present (ffprobe a:0…). */
+    audioTracks: number;
+    /** Optional measured duration in ms (ffprobe), for a secondary A/V check. */
+    durationMs?: number;
+}
+interface GateInput {
+    spec: SceneSpec;
+    /** Audio length in ms (the sounding length the capture targets). */
+    audioMs: number;
+    /** Total clip length in seconds used to resolve the timeline. */
+    totalSec: number;
+    /** Frame size for bounds + safe checks. */
+    W: number;
+    H: number;
+    safeBox: SafeBox;
+    /** Whether safezone enforcement is on for this clip. */
+    safezone: boolean;
+    /** Frame rate (for the expected-frame-count math). Default 30. */
+    fps?: number;
+    /** Required placements a layer reported (optional; pass [] if none). */
+    placements?: Placement[];
+    /**
+     * Font-readiness hook. The smvp recipe passes `() => document.fonts.ready
+     * .then(() => true)` (after loadBrandFonts). Default: assume loaded (true) so
+     * headless unit runs don't fail on a missing document.
+     */
+    fontsReady?: () => boolean | Promise<boolean>;
+    /**
+     * Output probe hook. The smvp recipe runs ffprobe on the produced file and
+     * passes the result. Omit to skip the output check (e.g. a pre-capture gate
+     * pass that only validates the spec).
+     */
+    output?: OutputProbe;
+}
+/**
+ * Run the gate. Returns the list of failures ([] = passes). Pure except for the
+ * optional async `fontsReady` hook. Call before capture (spec + A/V + placement)
+ * and again after capture with `output` set (real-output check).
+ */
+declare function runGate(input: GateInput): Promise<GateError[]>;
+/** Convenience: run the gate and throw a single aggregated error on failure. */
+declare function assertGate(input: GateInput): Promise<void>;
+
+interface BackgroundProps {
+    /** "paper" (theme.paper) | "ink" (theme.ink) | a literal CSS colour. */
+    style?: string;
+}
+interface CaptionProps {
+    /** Timed cues (in/out in ms relative to the clip start). */
+    script: CaptionScript;
+    size?: number;
+    yFrac?: number;
+}
+
+interface NotationProps {
+    /** Engraving system: "grand" (two staves) or "single". Informational for v1 —
+     *  the layout is driven by the rasterized bitmap's geometry either way. */
+    system?: 'grand' | 'single';
+    /** Extra scale applied to the band height the notation fits into. Default 1. */
+    scale?: number;
+    /**
+     * A pre-rendered notation (test/headless injection). When omitted, init()
+     * calls renderNotation(xml). One of `rendered` or `xml` is required.
+     */
+    rendered?: RenderedNotation;
+    /** MusicXML to engrave (browser path). Ignored when `rendered` is given. */
+    xml?: string;
+    /** Bar range [from,to] forwarded to renderNotation (RSR drawFrom/drawUpTo). */
+    bars?: [number, number];
+    /** Top y of the notation band (screen px). Default safeBox.top. */
+    bandTop?: number;
+    /** Height of the notation band (screen px). Default safeBox.bottom - bandTop. */
+    bandHeight?: number;
+}
+declare const notationFactory: LayerFactory<NotationProps>;
+
+interface ScrollCursorProps {
+    /** Bars visible in the follow window. Default 2 (RSR FOLLOW_BARS). Informational
+     *  for v1 — the geometry uses the module constant unless overridden here. */
+    followBars?: number;
+    /** Opening-zoom duration in ms before the music/cursor start (RSR INTRO_MS=900).
+     *  During this lead-in camProgress is held at 0. Default 900. */
+    openingZoomMs?: number;
+    /** Total music length in ms (RSR musicMs). Required to pace camProgress + the
+     *  cursor against the audio clock. */
+    musicMs: number;
+    /** Cursor stroke colour. Defaults to theme.accent. */
+    color?: string;
+}
+declare const scrollCursorFactory: LayerFactory<ScrollCursorProps>;
+
+/** measures (= rows) visible at once in the follow window. */
+declare const FOLLOW_BARS = 2;
+/** breathing room around the follow window. */
+declare const FOLLOW_PAD = 1.06;
+/** Cubic ease-in-out, t in [0,1] (RSR port of stave-video core/camera.py). */
+declare function cubicEaseInOut(t: number): number;
+/** Linear interpolation of two boxes. (RSR lerpBox) */
+declare function lerpBox(a: Box, b: Box, e: number): Box;
+/** Smallest crop of `aspect` containing `box` padded by `pad`, clamped to the
+ *  canvas. (RSR cropAroundBox) */
+declare function cropAroundBox(box: Box, aspect: number, pad: number, cw: number, ch: number): Box;
+/** Union (canvas coords) of all staff measure boxes with index in [lo,hi).
+ *  (RSR measureSpanBox) */
+declare function measureSpanBox(rn: RenderedNotation, lo: number, hi: number): Box | null;
+/** Union of the index-0 measure boxes — the opening focal. (RSR firstMeasureBox) */
+declare function firstMeasureBox(rn: RenderedNotation): Box | null;
+/** Number of distinct measures in the notation. (RSR measureCount) */
+declare function measureCount(rn: RenderedNotation): number;
+/** The follow window (canvas coords) for a continuous measure-start position,
+ *  spanning FOLLOW_BARS and lerping between adjacent windows. (RSR followBoxAt) */
+declare function followBoxAt(rn: RenderedNotation, posMeasures: number): Box | null;
+/**
+ * The continuous follow-window START measure for an audio-clock progress 0..1.
+ * (RSR +page.svelte:738-744 — hold the current pair, ease-scroll over the last
+ * third of each bar.) Returns the windowStart fed to followBoxAt.
+ */
+declare function followWindowStart(nBars: number, camProgress01: number): number;
+/** The dest rect a notation frame is drawn into, on screen. */
+interface NotationRect {
+    dx: number;
+    dy: number;
+    dw: number;
+    dh: number;
+}
+/** Geometry result of laying out the notation for one frame: which canvas `src`
+ *  rect is blitted to which screen `dest` rect, plus the mapped boxes. */
+interface NotationLayout {
+    /** Canvas-space crop blitted this frame. */
+    src: Box;
+    /** Screen-space dest rect. */
+    rect: NotationRect;
+    /** Per-row system boxes mapped into screen coords (for the playhead fallback). */
+    systems: Box[];
+    /** Per-(measure,staff) boxes mapped into screen coords (for highlights/cursor). */
+    measures: StaffMeasureBox[];
+}
+interface NotationLayoutOpts {
+    /** 0 = zoomed on bar 1, 1 = full excerpt (opening camera). Default 1. */
+    zoom01?: number;
+    /** Follow window (canvas coords); when set, overrides zoom and scrolls. */
+    focusBox?: Box | null;
+}
+/**
+ * Compute the notation layout (src crop + dest rect + mapped boxes) for one
+ * frame. This is RSR's `drawNotation` with the single `ctx.drawImage` call REMOVED
+ * — pure geometry, so it is testable headless and shared by the notation +
+ * scroll-cursor layers. The layer does the drawImage using `src` + `rect`.
+ */
+declare function notationLayout(rn: RenderedNotation, W: number, H: number, boxTop: number, boxH: number, opts?: NotationLayoutOpts): NotationLayout;
+/** Per-measure grand-staff column boxes (both staves unioned) from a frame's
+ *  mapped measures, in render order. (RSR measureColumns) */
+declare function measureColumnsFromLayout(measures: StaffMeasureBox[]): MeasureColumnBox[];
+/** The playhead line + alpha for progress `t01`. null when fully faded. (RSR
+ *  drawPlayhead, with the actual stroke factored out into the layer.) */
+interface PlayheadLine {
+    x: number;
+    y0: number;
+    y1: number;
+    alpha: number;
+}
+declare function playheadLine(layout: NotationLayout, t01: number): PlayheadLine | null;
+
+/** Map a canvas-space box through a base notation layout into world/screen coords. */
+declare function mapBoxThroughLayout(base: NotationLayout, b: Box): Box;
+/** RSR's per-frame `src` crop from a follow box (FOLLOW_PAD expand + clamp) —
+ *  the exact canvas window RSR's drawNotation blits (+page.svelte:289-298). */
+declare function followSrcBox(rn: RenderedNotation, focusBoxCanvas: Box): Box;
+/**
+ * The camera pose that scrolls/zooms the base (fixed) notation blit so the follow
+ * window fills a `viewW`×`viewH` viewport — the camera-primitive expression of
+ * RSR's per-frame re-crop. Composing this pose with the base blit reproduces RSR's
+ * `notationLayout({focusBox})` exactly (proven in scene-notation-camera.test.ts).
+ *
+ * We frame the SAME canvas window RSR crops (FOLLOW_PAD-expanded `src`), mapped
+ * into base-world coords, into the viewport. `viewW`/`viewH` are the dest-rect
+ * dimensions (so the contain-fit matches RSR's band-fit).
+ */
+declare function cameraForFollow(rn: RenderedNotation, base: NotationLayout, focusBoxCanvas: Box, viewW: number, viewH: number): CameraState;
+
+interface NotationEngraving {
+    rendered: RenderedNotation;
+    /** The base world layout (full content fitted to the band; zoom01=1). */
+    base: NotationLayout;
+    /** Notation band rect (screen px) the follow window fits into, per frame. */
+    bandTop: number;
+    bandHeight: number;
+    /**
+     * A pure follow-layout provider, published by scroll-cursor at init. notation
+     * calls it each frame to blit the SAME followed-bars window the cursor sweeps —
+     * so the two agree by construction AND z-order is correct (notation drawn first,
+     * cursor line on top), regardless of which layer the runner draws first.
+     * Absent when no scroll-cursor is in the scene (notation-only) -> base layout.
+     */
+    followLayoutAt?: (ctx: RenderCtx, tMs: number) => NotationLayout;
+}
+declare function setNotationEngraving(ctx: RenderCtx, eng: NotationEngraving): void;
+declare function getNotationEngraving(ctx: RenderCtx): NotationEngraving | undefined;
+/** scroll-cursor publishes its follow-layout provider; notation reads it. */
+declare function setFollowLayoutProvider(ctx: RenderCtx, fn: (ctx: RenderCtx, tMs: number) => NotationLayout): void;
+
+declare function isBlackKey(midi: number): boolean;
+/** A resolved keyboard layout: which keys, where, pinned to a world strip. */
+interface KeyboardLayout {
+    /** Lowest MIDI note drawn (inclusive). */
+    lowMidi: number;
+    /** Highest MIDI note drawn (inclusive). */
+    highMidi: number;
+    /** Strip left edge (world px). */
+    x: number;
+    /** Strip width (world px) — the white-key span. */
+    w: number;
+    /** Strip top edge (world px). */
+    top: number;
+    /** Strip height (world px) = white-key height. */
+    height: number;
+    /** White-key width (world px). */
+    whiteW: number;
+    /** First (leftmost) white key index, used to offset the white grid to x. */
+    firstWhiteIndex: number;
+    /** Count of white keys in [lowMidi, highMidi]. */
+    whiteCount: number;
+}
+/** Standard 88-key piano: A0 (21) .. C8 (108). */
+declare const PIANO_LOW = 21;
+declare const PIANO_HIGH = 108;
+interface KeyboardLayoutOpts {
+    /** "88" = full piano; "auto" = derive from a pitch span (padded to whites). */
+    range?: '88' | 'auto';
+    /** For "auto": the [lowMidi, highMidi] span to cover (snapped out to whites,
+     *  padded by one white each side so edge keys aren't flush). */
+    span?: [number, number];
+    /** Strip left/width/top/height in world px. */
+    x: number;
+    w: number;
+    top: number;
+    height: number;
+}
+/** Build a KeyboardLayout. Pure. */
+declare function keyboardLayout(opts: KeyboardLayoutOpts): KeyboardLayout;
+/** The pitch span [min,max] of a Score's notes (for "auto" range). */
+declare function scorePitchSpan(midis: number[]): [number, number];
+/**
+ * Resolve a KeyboardLayout from the shared keyboard placement props + the Score's
+ * pitch span. The `keyboard` and `falling-notes` layers BOTH call this with the
+ * same inputs in standalone mode, so they produce identical geometry even without
+ * the store (the store just covers props that differ). Pure.
+ *
+ * Placement: the strip spans the safe box horizontally; its bottom sits at
+ * `bottomY` (world px) with the given `height`.
+ */
+declare function resolveKeyboardLayout(args: {
+    range: '88' | 'auto';
+    pitchMidis: number[];
+    left: number;
+    width: number;
+    bottomY: number;
+    height: number;
+}): KeyboardLayout;
+/**
+ * Center x (world px) of a note's KEY on the keyboard. White keys sit on the
+ * even grid; black keys are nudged to sit between their two neighbouring whites
+ * (the canonical piano offset), so a falling block lands centered over the right
+ * key. This is the SINGLE source both layers use — they agree by construction.
+ */
+declare function keyCenterX(layout: KeyboardLayout, midi: number): number;
+/** Width (world px) a falling-note column should use for a pitch. Black keys are
+ *  drawn narrower (like the physical key); white keys ~ a white-key width. */
+declare function keyColumnWidth(layout: KeyboardLayout, midi: number): number;
+/** The drawable rectangle for a key on the keyboard strip (white or black). */
+interface KeyRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    black: boolean;
+}
+declare function keyRect(layout: KeyboardLayout, midi: number): KeyRect;
+/** Whether `midi` is within the layout's drawn range. */
+declare function inRange(layout: KeyboardLayout, midi: number): boolean;
+/** All white-key midis in the layout (low..high), for drawing the bed. */
+declare function whiteKeys(layout: KeyboardLayout): number[];
+/** All black-key midis in the layout (low..high), drawn on top of the whites. */
+declare function blackKeys(layout: KeyboardLayout): number[];
+type ColorBy = 'hand' | 'pitch-class';
+/** Right/left hand colours. R = theme accent (the lead colour); L = a cooler
+ *  contrast. Both passed in so a host theme can override. */
+interface HandColors {
+    R: string;
+    L: string;
+}
+/**
+ * Colour for a note. `hand` reads the Score's accurate hand (NOT a pitch
+ * threshold guess); `pitch-class` colours by chroma. Pure.
+ */
+declare function noteColor(midi: number, hand: 'L' | 'R', colorBy: ColorBy, hands: HandColors): string;
+
+interface KeyboardProps {
+    /** "88" = full piano; "auto" = fit the Score's pitch span. Default "auto". */
+    range?: '88' | 'auto';
+    /** Colour active keys by performing hand (Score-accurate) or by pitch class.
+     *  Default "hand". */
+    colorBy?: ColorBy;
+    /** Strip height in world px. Default 220. */
+    height?: number;
+    /** Strip bottom edge in world px. Default safeBox.bottom. */
+    bottomY?: number;
+    /** Right/left hand colours. Defaults: R = theme.accent, L = theme.gold. */
+    handColors?: HandColors;
+}
+declare const keyboardFactory: LayerFactory<KeyboardProps>;
+
+interface FallingNotesProps {
+    /** Pair with a `keyboard` layer (read its layout + hit-line). When false the
+     *  layer is standalone and builds its own layout from the props below.
+     *  Default true. */
+    keyboard?: boolean;
+    /** Colour by performing hand (Score-accurate) or by pitch class. Default "hand". */
+    colorBy?: ColorBy;
+    /** Lead time in ms a note is visible before landing. Default 2000. */
+    leadMs?: number;
+    /** Fall speed in px/sec. Alternative to leadMs (ignored when leadMs is given). */
+    speed?: number;
+    /** Glow flash at the hit-line while a note sounds. Default true. */
+    hitGlow?: boolean;
+    /** Standalone-only: keyboard range when `keyboard:false`. Default "auto". */
+    range?: '88' | 'auto';
+    /** Standalone-only: hit-line (world y). Default safeBox.bottom - 220. */
+    hitLineY?: number;
+    /** Top of the fall region (world y) — notes appear here. Default safeBox.top. */
+    topY?: number;
+    /** Right/left hand colours. Defaults: R = theme.accent, L = theme.gold. */
+    handColors?: HandColors;
+}
+declare const fallingNotesFactory: LayerFactory<FallingNotesProps>;
+
+declare function setKeyboardLayout(ctx: RenderCtx, layout: KeyboardLayout): void;
+declare function getKeyboardLayout(ctx: RenderCtx): KeyboardLayout | undefined;
+
+interface FallingKeyboardDemoOpts {
+    /** Frame size. Default phone-portrait 1080×1920. */
+    size?: [number, number];
+    /** Theme key for the spec. Default "rsr". */
+    theme?: string;
+    /** falling-notes lead time (ms). Default 2200. */
+    leadMs?: number;
+    /** Colour mode for both layers. Default "hand". */
+    colorBy?: 'hand' | 'pitch-class';
+    /** Keyboard range. Default "auto" (fit the piece's pitch span). */
+    range?: '88' | 'auto';
+    /** Forwarded to scoreFromMusicXML (tempo fallback/override/osmdFactory). */
+    scoreOpts?: ScoreFromMusicXMLOpts;
+}
+/** The SceneSpec for the demo (background + falling-notes + keyboard, full clip). */
+declare function fallingKeyboardDemoSpec(opts?: FallingKeyboardDemoOpts): SceneSpec;
+/** Parse the demo Score from MusicXML (the caller supplies the XML string so the
+ *  bundling/fixture path stays in the host/test, not in src). */
+declare function fallingKeyboardDemoScore(xml: string, opts?: FallingKeyboardDemoOpts): Promise<Score>;
+
+/** Common window props shared by every card wrapper. */
+interface WindowProps {
+    /** Absolute segment start (ms) — t01 is measured from here. Default 0. */
+    startMs?: number;
+    /** Segment length (ms) over which t01 sweeps 0..1. Default = scene's natural duration. */
+    durationMs?: number;
+}
+interface HookProps extends WindowProps {
+    /** Hook lines (wraps HookSceneOpts.lines). */
+    lines: string[];
+    /** Optional brand override (wraps HookSceneOpts.brand). */
+    brand?: string;
+}
+declare const hookFactory: LayerFactory<HookProps>;
+interface RevealProps extends WindowProps {
+    /** Title (wraps RevealSceneOpts.title). */
+    title: string;
+    /** Subtitle (wraps RevealSceneOpts.subtitle). */
+    subtitle: string;
+    /** Optional initials override (wraps RevealSceneOpts.initials). */
+    initials?: string;
+    /** Optional fun fact (wraps RevealSceneOpts.funFact). */
+    funFact?: string;
+}
+declare const revealFactory: LayerFactory<RevealProps>;
+interface CtaProps extends WindowProps {
+    /** End-card lines (wraps CtaSceneOpts.lines): [headline, ...accent lines]. */
+    lines: string[];
+}
+declare const ctaFactory: LayerFactory<CtaProps>;
+interface PortraitProps extends WindowProps {
+    /** Composer name → title + initials badge fallback (wraps RevealSceneOpts.title). */
+    title: string;
+    /** Subtitle line (e.g. dates / era). */
+    subtitle: string;
+    /** Portrait image URL (Wikimedia etc.); loaded crossOrigin in init. */
+    url?: string | null;
+    /** Optional initials override. */
+    initials?: string;
+    /** Optional fun fact (corpus fun_fact). */
+    funFact?: string;
+}
+declare const portraitFactory: LayerFactory<PortraitProps>;
+
+/** Host-provided level source attached to RenderCtx by the app/capture harness. */
+interface SpectrumInput {
+    /** Normalized 0..1 magnitudes for `bands` bars at time tMs (preferred). */
+    levels?(tMs: number, bands: number): Float32Array | number[] | null | undefined;
+    /** Raw byte-FFT (0..255), log-binned by the layer (AnalyserNode shape). */
+    byteFreq?(tMs: number): Uint8Array | null | undefined;
+}
+/** Augment RenderCtx with the optional spectrum input (declaration merging). */
+declare module '../layer' {
+    interface RenderCtx {
+        /** Optional audio-reactive level source for the spectrum layer (host-wired). */
+        spectrum?: SpectrumInput;
+    }
+}
+interface SpectrumProps {
+    /** Number of bars. Default 44 (whozart SPEC_BARS). */
+    bars?: number;
+    /** Vertical center as a fraction of H. Default 0.46 (whozart). */
+    centerFrac?: number;
+    /** Max half-height as a fraction of H. Default 0.135 (whozart). */
+    maxHeightFrac?: number;
+    /** Bar fill at low magnitude (wine). Default theme.accent. */
+    colorLow?: string;
+    /** Bar fill at high magnitude (gold). Default theme.gold. */
+    colorHigh?: string;
+    /** Per-frame level provider (overrides ctx.spectrum). Pure fn of t for tests. */
+    levelsFn?: (tMs: number, bands: number) => Float32Array | number[] | null;
+}
+declare const spectrumFactory: LayerFactory<SpectrumProps>;
+
+interface BrandingProps {
+    /** Wordmark to draw. Default theme.brand. */
+    logo?: string;
+    /** Show the safe-zone debug overlay on top (apps' ?safe=1). Default false. */
+    safezone?: boolean;
+    /** Vertical anchor as a fraction of safeBox height from its TOP. Default 1
+     *  (bottom edge of the safe box). */
+    yFrac?: number;
+    /** Font size in px. Default 34. */
+    size?: number;
+    /** Text colour. Default theme.sepia. */
+    color?: string;
+}
+declare const brandingFactory: LayerFactory<BrandingProps>;
+type SafeGuidesProps = Record<string, never>;
+declare const safeGuidesFactory: LayerFactory<SafeGuidesProps>;
+
+interface PromoCardsDemoOpts {
+    /** Frame size. Default phone-portrait 1080×1920. */
+    size?: [number, number];
+    /** Theme key. Default "rsr". */
+    theme?: string;
+    /** Total clip length (s). Default 12. */
+    totalSec?: number;
+    /** Hook segment length (s). Default 2.2. */
+    hookSec?: number;
+    /** Reveal/portrait segment length (s). Default 4. */
+    revealSec?: number;
+    /** CTA segment length (s) at the end. Default 3. */
+    ctaSec?: number;
+    /** Hook lines. */
+    hookLines?: string[];
+    /** Reveal/portrait title (composer). */
+    title?: string;
+    /** Reveal/portrait subtitle. */
+    subtitle?: string;
+    /** Optional portrait URL (loaded crossOrigin in init; null → initials badge). */
+    portraitUrl?: string | null;
+    /** Optional fun fact under the portrait. */
+    funFact?: string;
+    /** CTA lines. */
+    ctaLines?: string[];
+    /** Brand wordmark. Default theme.brand (resolved by the host). */
+    brand?: string;
+}
+/** 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 };