@real-music-packages/web-core 0.45.2 → 0.47.0

package/dist/notationXml.d.ts

@@ -0,0 +1,175 @@
+declare function stampNoteIds(xml: string): string;
+/**
+ * Insert `<print new-system="yes"/>` as the FIRST child of the `<measure>`
+ * at each 0-based position in `breakBeforeBarIndexes`, in EVERY `<part>`
+ * (a score's parts share one measure timeline, so a break must be encoded
+ * once per part for Verovio to line the systems up across staves). A
+ * position that is ≤ 0 or ≥ that part's own measure count is silently
+ * ignored FOR THAT PART (0 is a no-op — a part already starts a new system
+ * at its own first measure). Idempotent: a measure that already carries a
+ * `<print>` element (from a prior call, or from the source data) gets
+ * `new-system="yes"` SET on that existing element rather than gaining a
+ * second one — calling this twice with the same positions serializes
+ * identically both times. Malformed input (fails to parse) is returned
+ * unchanged, same defensive style as `stampNoteIds` above. Only ever ADDS
+ * `<print>` elements — never touches a `<note>` — so `stampNoteIds`'s
+ * position-based id scheme is unaffected by a prior or subsequent call to
+ * this function (see this file's own tests for the pinned invariant).
+ */
+/**
+ * How many `<measure>` elements the FIRST `<part>` has — the `totalBars`
+ * that `barsPerLineBreaks`/`sectionAwareBreaks` plan against.
+ *
+ * The first part specifically, because that is the coordinate system
+ * `injectSystemBreaks` positions live in: a score's parts share one measure
+ * timeline, so the first part's ordinals index every part. And ORDINALS, not
+ * `<measure number>` attributes — scores skip and repeat bar numbers, so a
+ * count is the only safe answer. Malformed input, or a document with no
+ * part, returns 0 rather than throwing.
+ */
+declare function measureCount(xml: string): number;
+declare function injectSystemBreaks(xml: string, breakBeforeBarIndexes: readonly number[]): string;
+/**
+ * Evenly-spread system-break positions for `totalMeasures` measures across
+ * `systems` systems: `[per, 2·per, …]` (each strictly `< totalMeasures`),
+ * with `per = Math.ceil(totalMeasures / systems)` — `Math.ceil` naturally
+ * front-loads any remainder into the EARLIER systems (e.g. 7 measures / 2
+ * systems -> per=4 -> systems of 4+3, never 3+4), which is what keeps a
+ * later system from being the short/orphaned one. `systems <= 1` (nothing to
+ * break between) returns `[]`.
+ */
+declare function balancedSystemBreaks(totalMeasures: number, systems: number): number[];
+/**
+ * Balanced system-break positions for a target BARS-PER-LINE layout — the
+ * caller-facing sibling of `balancedSystemBreaks`, which takes a system
+ * COUNT. Rather than stepping `every` bars at a time from bar 0 (which
+ * strands a short remainder — a 5-bar excerpt at `every: 4` renders 4+1, a
+ * widow of our own making), this decides how many LINES the excerpt needs
+ * (`ceil(totalBars / every)`) and hands that count to
+ * `balancedSystemBreaks`. `(5, 4)` is `[3]` (3+2) instead of `[4]` (4+1);
+ * `(9, 4)` is `[3, 6]` (3+3+3) instead of `[4, 8]` (4+4+1).
+ *
+ * WIDOW BACK-OFF: a small `every` against a small `totalBars` can make the
+ * straight `ceil(totalBars / every)` line count land on a trailing line of
+ * exactly 1 bar — the same widow this function exists to remove, reappearing
+ * at a different total/every combination (`lines = 3` on 7 bars: `per = 3`
+ * fills two 3-bar lines and leaves 1 bar for the third). The line count is
+ * therefore backed down (never below 1) until the trailing line holds at
+ * least 2 bars — 7 bars lands on 2 lines (4+3) instead of 3 (3+3+1), which
+ * is the same "fewer, fuller lines" direction `every` already asks for.
+ * This never changes the result for any total/every whose straight `ceil`
+ * count already avoids a 1-bar trailing line.
+ *
+ * `every <= 0` (the "auto — no forced breaks" sentinel callers resolve to)
+ * or a non-positive/non-finite `totalBars` returns `[]`. Never throws.
+ *
+ * Ported from stave-web-sightread (`src/lib/bach/xmlTransforms.ts`), whose
+ * copy this replaces — see the CONTRACT DUPLICATION NOTICE above. Reached by
+ * consumers through `VerovioLayoutOptions.barsPerLine` rather than called
+ * directly, so the player owns both the plan and its interaction with the
+ * widow pass and the readability floor.
+ */
+declare function barsPerLineBreaks(totalBars: number, every: number): number[];
+/**
+ * Like `barsPerLineBreaks`, but each SECTION's span is balanced on its own
+ * instead of one balance running across the whole excerpt — so a line never
+ * ends part-way into a neighbouring section's opening bars, and a section's
+ * own bars are never split into a widowed last line either.
+ *
+ * `sectionStarts` are 0-BASED POSITIONS into the excerpt (the same
+ * coordinate `injectSystemBreaks` consumes), NOT MusicXML `<measure
+ * number>` attributes — scores skip bar numbers, so a caller holding
+ * bar-numbered section labels must convert first. `0` (the excerpt's own
+ * start) is never a break and is ignored if present.
+ *
+ * Every section start > 0 is a HARD break in its own right — a new section
+ * always begins its own line, not subject to balancing — unioned with
+ * `barsPerLineBreaks`' balanced positions computed WITHIN each section's
+ * span (its start up to the next section's start, or `totalBars` for the
+ * last) and offset back into excerpt-absolute positions.
+ *
+ * `every <= 0` suppresses the balanced component, matching
+ * `barsPerLineBreaks`, but section-start breaks still apply — that is the
+ * "sections only, otherwise let the engraver decide" mode. Out-of-range and
+ * non-integer starts are ignored. The result is sorted, de-duplicated, and
+ * every entry is a valid `injectSystemBreaks` position (integer, `> 0`,
+ * `< totalBars`). Never throws.
+ */
+declare function sectionAwareBreaks(totalBars: number, sectionStarts: readonly number[], every: number): number[];
+/** One `<note>`'s MODEL identity — the ground truth `EngravedNote`
+ *  (notationPlayerSvg.ts) needs that Verovio's rendered SVG cannot supply on
+ *  its own (a rendered `g.note`/`g.rest` carries geometry, not pitch/tie/
+ *  duration semantics). Keyed by the note's stamped `id` in
+ *  `notePositions()`'s return of `verovioEngravedNotes`
+ *  (notationPlayerVerovio.ts). */
+interface NoteModel {
+    /** `12*(octave+1) + stepSemitone + alter` — the standard MusicXML→MIDI
+     *  conversion (the same formula stave-web-sightread's own
+     *  `practice/probeInputs.ts:pitchMidi` uses — a universal formula, not app
+     *  logic, so this is not an owned-layer violation to restate here). `null`
+     *  for a rest or an `<unpitched>` note (no `<pitch>` child) — mirrors
+     *  `EngravedNote.midi`'s own "null covers both" contract. */
+    midi: number | null;
+    /** Has a `<rest/>` child. */
+    isRest: boolean;
+    /** True for the STOP half of a tie — a direct `<tie type="stop">` child OR
+     *  `<notations><tied type="stop">` (exporters vary on which they emit;
+     *  either counts) — matches `EngravedNote.tieContinuation`'s "continuation
+     *  note of a tie, not the struck start" contract. */
+    tieContinuation: boolean;
+    /** 0-based, matching `EngravedNote.staffIndex`'s "0 = top staff of the
+     *  system" contract: every `<part>` is walked in document order, and
+     *  every DISTINCT staff within it (by `<attributes><staves>` when
+     *  present, else the highest `<staff>` number any of its notes uses, else
+     *  1) is assigned the next index — so a single-part 2-staff piano score
+     *  numbers 0/1 by `<staff>`, and a 2-part 1-staff-per-part reduction (this
+     *  app's own chord+bass shape) numbers 0/1 by PART, with neither case
+     *  needing different code. */
+    staffIndex: number;
+    /** Whole-note fraction (0.25 = quarter) — `duration / divisions / 4`,
+     *  divisions tracked per-part from the LAST `<attributes><divisions>`
+     *  seen at or before this note (MusicXML: divisions persist until
+     *  overridden, default 1). 0 for a grace note (no `<duration>` child —
+     *  the true, spec-correct signal; never guessed from `<type>`). */
+    durationReal: number;
+    /** 0-based position of this note's `<measure>` among its OWN `<part>`'s
+     *  measure children, in document order. Informational only — the live
+     *  join (`verovioOnsetColumns`/`verovioEngravedNotes`, both in
+     *  notationPlayerVerovio.ts) resolves the note's RENDERED measure index
+     *  from the live SVG DOM independently (Verovio's own render order, which
+     *  is what geometry/hit-testing must agree with), never from this field. */
+    measureIndex: number;
+    /** `print-object="no"` on the source `<note>` (stave's `hideDoubledNotes`
+     *  sets this on editorially-doubled notes/rests before handing MusicXML to
+     *  this player). Verovio's importer HONORS this for `<note>` elements
+     *  carrying a `<pitch>` (renders `visibility="hidden"` on its own,
+     *  empirically confirmed against a real 6.2.0 render) but does NOT honor
+     *  it for `<rest>` notes (the `<g class="rest">` renders fully visible
+     *  regardless — same empirical check). `createVerovioNotationPlayer`
+     *  reads this field to force `visibility="hidden"` after every render for
+     *  ANY id where it's true — a no-op re-application on notes Verovio
+     *  already hid, and the actual fix on the rests it doesn't (see that
+     *  module's `applyPrintObjectHiding`). */
+    hidden: boolean;
+}
+/**
+ * Pure(ish) — MusicXML-in, `id → NoteModel`-out. Walks every `<part>` in
+ * document order, then every `<measure>` in document order, then every
+ * DIRECT child in document order — `<attributes>` updates the part's own
+ * `divisions` cursor; every other non-`<note>` child (`<backup>`,
+ * `<forward>`, `<direction>`, …) is a structural/timeline element this
+ * function has NO use for (it reads each note's OWN `<duration>` directly,
+ * never a cursor POSITION — see `durationReal`'s doc — so unlike
+ * `walkMeasureNotes`-style position walks, `<backup>`/`<forward>` need no
+ * special handling here beyond being correctly skipped, which plain
+ * tag-name filtering already does) — and every `<note>` becomes one model
+ * entry, keyed by its `id` attribute (a note with NO `id` — i.e. input that
+ * was never run through `stampNoteIds` — is silently skipped: it has no key
+ * to join the render against, so there is nothing useful to record).
+ *
+ * Never throws: malformed input (fails to parse, or no `<score-partwise>`
+ * root) returns an empty Map.
+ */
+declare function noteModelFromXml(stampedXml: string): Map<string, NoteModel>;
+
+export { type NoteModel, balancedSystemBreaks, barsPerLineBreaks, injectSystemBreaks, measureCount, noteModelFromXml, sectionAwareBreaks, stampNoteIds };

package/dist/notationXml.js

@@ -0,0 +1,19 @@
+import {
+  balancedSystemBreaks,
+  barsPerLineBreaks,
+  injectSystemBreaks,
+  measureCount,
+  noteModelFromXml,
+  sectionAwareBreaks,
+  stampNoteIds
+} from "./chunk-JCDNEJBT.js";
+export {
+  balancedSystemBreaks,
+  barsPerLineBreaks,
+  injectSystemBreaks,
+  measureCount,
+  noteModelFromXml,
+  sectionAwareBreaks,
+  stampNoteIds
+};
+//# sourceMappingURL=notationXml.js.map

package/dist/notationXml.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/scene/index.d.ts

@@ -2,7 +2,7 @@ import { S as Score, a as ScoreFromMusicXMLOpts, T as TempoMap, b as ScoreNote }
 export { s as scoreFromMusicXML } from '../score-CLwSiAjn.js';
 import { A as AudioClock, a as LayerFactory, R as RenderCtx } from '../waveform-CdulBoeO.js';
 export { L as Layer, S as SpectrumInput, b as SpectrumProps, W as WaveformInput, c as WaveformProps, s as spectrumFactory, w as waveformFactory } from '../waveform-CdulBoeO.js';
-import { PromoTheme, RecordOpts, Scene, SafeBox } from '../video.js';
+import { SafeBox, PromoTheme, RecordOpts, Scene } from '../video.js';
 import { RenderedNotation, Box } from '../promo.js';
 import { N as NotationLayout } from '../notationGeometry-DqVBgL7F.js';
 export { F as FOLLOW_BARS, a as FOLLOW_PAD, b as NotationLayoutOpts, c as NotationRect, P as PlayheadLine, d as audioPlayheadLine, e as cropAroundBox, f as cubicEaseInOut, g as distinctMeasureIndices, h as distinctOnsets, i as firstMeasureBox, j as followBoxAt, k as followWindowStart, m as lerpBox, n as measureColumnsFromLayout, o as measureCount, p as measureSpanBox, q as measureSystemMap, r as notationLayout, s as playheadLine, t as systemBox, v as vstackAudioPlayheadLine, u as vstackFollowBox } from '../notationGeometry-DqVBgL7F.js';
@@ -153,6 +153,52 @@ declare function applyToContext(ctx: CanvasRenderingContext2D, cam: CameraState,
 /** The identity (no pan/zoom) camera: world == viewport. */
 declare function identityCamera(W: number, H: number): CameraState;
 
+/** A sub-rect of the frame, in fractions of W/H (0..1, top-left origin). */
+interface Region {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** The whole frame. A layer with this region renders exactly as an unregioned one. */
+declare const FULL_REGION: Region;
+/** True when `r` covers the entire frame (the runner then skips the transform). */
+declare function isFullRegion(r: Region): boolean;
+/** A region's pixel rect in FRAME space. */
+declare function regionRect(r: Region, W: number, H: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Structural validation for a region (used by buildScene + the gate so a bad
+ * pane fails before capture rather than rendering off-frame).
+ * Returns [] when valid.
+ */
+declare function validateRegion(r: unknown): string[];
+/**
+ * The usable content rect for a layer drawing inside `r`, in PANE-LOCAL px.
+ *
+ * This is `safeBox(W, H)` clipped to the pane and shifted into pane
+ * coordinates — NOT `safeBox(r.w*W, r.h*H)`, which re-applies the frame's
+ * percentage insets to the pane and silently invents room that phone chrome
+ * covers.
+ *
+ * Worked example, 1080x1920, bottom pane {y:0.42, h:0.58} (pane top 806.4,
+ * pane height 1113.6):
+ *   naive safeBox(1080, 1113.6).bottom = 801.8 pane-local = 1608.2 frame-space
+ *   paneSafeBox(...).bottom            = 576.0 pane-local = 1382.4 frame-space
+ * The frame's real bottom-safe line is 0.72*1920 = 1382.4, so the naive value
+ * hands the layer ~226px of content area underneath TikTok's caption + action
+ * rail. The top pane fails inverted (naive top-safe 121 vs the real 288),
+ * putting a title under the search bar.
+ *
+ * A pane that misses the frame safe box entirely yields a zero-size box (w/h 0)
+ * anchored at the clamped edge, rather than a negative-size one.
+ */
+declare function paneSafeBox(r: Region, W: number, H: number): SafeBox;
+
 /** A timeline endpoint: a number (ms? no — seconds), "end", or "end-N" (N s before end). */
 type TimeAnchor = number | 'end' | `end-${number}`;
 interface SpecLayer {
@@ -160,6 +206,19 @@ interface SpecLayer {
     k: string;
     /** Props passed to the layer's init(). */
     p?: unknown;
+    /**
+     * Optional sub-rect of the frame to draw this layer into (fractions of W/H).
+     * The layer is clipped + translated into the pane and sees a RenderCtx whose
+     * `W`/`H` are the PANE's size and whose `safeBox` is `paneSafeBox` (the frame
+     * safe box intersected with the pane) — so any existing layer composites into
+     * a split-screen pane unchanged. Omit (or pass the full frame) for today's
+     * behavior; a full-frame region is detected and short-circuited so the op
+     * stream stays byte-for-byte identical.
+     *
+     * The camera transform is FRAME-space and is applied before the region
+     * transform, so the camera pans a pane's CONTENTS, not the pane itself.
+     */
+    region?: Region;
 }
 /**
  * Optional per-segment audio. Lets a segment SCHEDULE sound at its own start
@@ -374,6 +433,355 @@ interface RecordSceneSpecOpts {
  */
 declare function recordSceneSpec(opts: RecordSceneSpecOpts): Promise<Blob>;
 
+type VideoFit = 'cover' | 'contain';
+type VideoClockMode = 'play' | 'seek';
+interface VideoSourceProps {
+    /** A URL (loaded + awaited in init) or any ready CanvasImageSource. */
+    src: string | CanvasImageSource;
+    /** How the source fills the box. Default 'cover'. */
+    fit?: VideoFit;
+    /**
+     * Focal point of the source for `cover` cropping, in source fractions.
+     * Default {x: 0.5, y: 0.38} — faces sit above the vertical centre, and a
+     * centred crop of a portrait clip cuts the forehead off.
+     */
+    focus?: {
+        x: number;
+        y: number;
+    };
+    /** Absolute clip time (ms) at which this source starts playing. Default 0. */
+    startMs?: number;
+    /** In-point within the SOURCE (ms). Default 0. */
+    sourceStartMs?: number;
+    /** Loop [sourceStartMs, duration) when the segment outlasts the source. Default true. */
+    loop?: boolean;
+    /** Playback rate. Default 1. */
+    rate?: number;
+    /** Mute the element. Default true — reaction audio is discarded in v1. */
+    mute?: boolean;
+    /** Constant alpha. Default 1. */
+    opacity?: number;
+    /** 'play' (real-time capture, default) or 'seek' (offline; not yet supported). */
+    clockMode?: VideoClockMode;
+    /** Drift past which `play` mode issues a corrective seek, ms. Default 120. */
+    driftTolMs?: number;
+    /**
+     * Source duration in ms. Read from the element when it can be; required when
+     * `src` is a bare CanvasImageSource AND `loop` is on (nothing to read it from).
+     */
+    durationMs?: number;
+}
+/** Source-crop + destination rects for one drawImage call. */
+interface FitBoxes {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+    dx: number;
+    dy: number;
+    dw: number;
+    dh: number;
+}
+/**
+ * Fit a source (iW×iH) into a box (bw×bh at the origin).
+ * - 'cover'   : fills the box, crops the source around `focus` (clamped so the
+ *               crop window never runs off the source).
+ * - 'contain' : whole source visible, letterboxed and centred in the box.
+ */
+declare function fitBoxes(iW: number, iH: number, bw: number, bh: number, mode: VideoFit, focus: {
+    x: number;
+    y: number;
+}): FitBoxes;
+/**
+ * The source position (ms) to show at absolute clip time `tMs`.
+ * Before `startMs` the in-point is held. When `loop`, playback wraps within
+ * [sourceStartMs, durationMs); otherwise the last frame is held.
+ */
+declare function sourceTimeMs(tMs: number, o: {
+    startMs: number;
+    sourceStartMs: number;
+    rate: number;
+    loop: boolean;
+    durationMs: number;
+}): number;
+/** Whether `play` mode should issue a corrective seek this frame. */
+declare function needsSeek(currentMs: number, wantMs: number, tolMs: number): boolean;
+/** Intrinsic size of any CanvasImageSource we might be handed. */
+declare function sourceSize(src: unknown): {
+    w: number;
+    h: number;
+};
+declare const videoSourceFactory: LayerFactory<VideoSourceProps>;
+
+type SeamStyle = 'line' | 'shadow';
+interface PaneSeamProps {
+    /** Where the seam sits, as a fraction of the frame (H for 'h', W for 'v'). */
+    atFrac: number;
+    /** Seam axis. 'h' = a horizontal rule between stacked panes. Default 'h'. */
+    orientation?: 'h' | 'v';
+    /** 'line' = a hard rule; 'shadow' = a rule plus a soft falloff either side. */
+    style?: SeamStyle;
+    /** Rule colour. Default theme.ink. */
+    color?: string;
+    /** Rule thickness in px. Default 4. */
+    thicknessPx?: number;
+    /** Falloff depth either side for 'shadow', px. Default 28. */
+    shadowPx?: number;
+    /** Rule alpha. Default 0.9. */
+    opacity?: number;
+}
+declare const paneSeamFactory: LayerFactory<PaneSeamProps>;
+
+interface ReactionSplitOpts {
+    /** The top pane: a reaction clip. */
+    reaction: VideoSourceProps;
+    /**
+     * The bottom pane: ANY layers from the registry. A live music scene
+     * (`notation` + `scroll-cursor`, `falling-notes` + `keyboard`) and a
+     * pre-recorded app screen capture (another `video-source`) are both just
+     * SpecLayers — the region machinery does not care which.
+     */
+    app: SpecLayer[];
+    /** The text hook, drawn over BOTH panes and pinned to the frame. */
+    hook: string;
+    /** Top-pane height as a fraction of the frame. Default 0.42. */
+    split?: number;
+    /** Clip length. Default 8. */
+    durationSec?: number;
+    /** Divider treatment between the panes. Default 'line'. */
+    seam?: SeamStyle | 'none';
+    /** Optional follow/CTA card, entering at `atSec`. */
+    endCard?: {
+        text?: string;
+        handle?: string;
+        atSec: number;
+    };
+    /** Frame size. Default [1080, 1920]. */
+    size?: [number, number];
+    /** Theme key. Default 'default'. */
+    theme?: string;
+    /** Capture fps. Default 30. */
+    fps?: number;
+    /** Hook vertical centre as a fraction of the frame. Default just below the
+     *  frame's top-safe line, so it clears the platform's tabs/search row. */
+    hookCenterFrac?: number;
+    /** Hook font px. Default 84. */
+    hookFontPx?: number;
+    /** Hook colour. Default the theme's paper (hooks sit over footage). */
+    hookColor?: string;
+}
+/** Default hook centre: inside the safe area, high enough to read as a caption. */
+declare const DEFAULT_HOOK_CENTER_FRAC: number;
+/**
+ * The reaction-overlay short-form layout: a reaction clip above, the app doing
+ * one small thing below, a text hook over both.
+ *
+ * Throws on a structurally impossible split so the caller fails here rather
+ * than at buildScene.
+ */
+declare function reactionSplitSpec(o: ReactionSplitOpts): SceneSpec;
+
+/** The emotional register a clip reads as — the axis variants are drawn along. */
+type ReactionEmotion = 'confused' | 'shocked' | 'impressed' | 'delighted' | 'deadpan' | 'skeptical';
+declare const REACTION_EMOTIONS: readonly ReactionEmotion[];
+interface ReactionClip {
+    /** Stable id, unique within the manifest. */
+    id: string;
+    /** File name / path, resolved against the manifest's base URL. */
+    file: string;
+    emotion: ReactionEmotion;
+    durationMs: number;
+    /** [x, y, w, h] in source fractions — where the face sits. Drives the crop. */
+    faceBox?: [number, number, number, number];
+    /** REQUIRED provenance: where the footage came from (e.g. "envato-elements"). */
+    source: string;
+    /** REQUIRED provenance: the licence/receipt id proving the right to use it. */
+    licenseId: string;
+    /** ISO date the licence was obtained. */
+    acquiredAt?: string;
+    notes?: string;
+}
+interface ReactionManifest {
+    clips: ReactionClip[];
+}
+/** Focus used when a clip declares no faceBox — faces sit above centre. */
+declare const DEFAULT_FOCUS: {
+    x: number;
+    y: number;
+};
+/**
+ * Validate a parsed manifest. Returns [] when valid; every problem is reported,
+ * not just the first, so one audit run fixes the whole file.
+ */
+declare function validateReactionManifest(json: unknown): string[];
+/** Throwing form, for a build script. */
+declare function assertReactionManifest(json: unknown): ReactionManifest;
+/** The cover-crop focal point for a clip: its face centre, or the default. */
+declare function clipFocus(clip: Pick<ReactionClip, 'faceBox'>): {
+    x: number;
+    y: number;
+};
+interface ReactionPropsOpts {
+    /** Prefix joined to `clip.file` (e.g. "/assets/reactions/"). Default "". */
+    baseUrl?: string;
+    /** Absolute clip time the reaction starts at. Default 0. */
+    startMs?: number;
+    /** In-point within the source. Default 0. */
+    sourceStartMs?: number;
+    loop?: boolean;
+    rate?: number;
+}
+/** Turn a manifest entry into `video-source` props, focus already aimed. */
+declare function reactionProps(clip: ReactionClip, o?: ReactionPropsOpts): VideoSourceProps;
+/** Clips matching an emotion (all of them when `emotion` is omitted). */
+declare function pickClips(m: ReactionManifest, emotion?: ReactionEmotion): ReactionClip[];
+
+interface CheckFrame {
+    w: number;
+    h: number;
+    data: Uint8Array | Uint8ClampedArray | number[];
+}
+interface SampledFrames {
+    show: {
+        tSec: number;
+        f: CheckFrame;
+    }[];
+    /** Frame size the samples were decoded at (may differ from the source size). */
+    frameW: number;
+    frameH: number;
+}
+interface CheckResult {
+    name: string;
+    pass: boolean;
+    detail: string;
+}
+/** Luminance floor below which a pixel counts as ink on a paper background. */
+declare const PAPER_LUM_FLOOR = 200;
+/**
+ * Fraction of a row's [x0,x1) span that reads as content rather than paper:
+ * clearly darker than paper, or clearly chromatic. Mirrors the heuristic the
+ * existing promo checks use so thresholds carry over.
+ */
+declare function inkFractionInRow(f: CheckFrame, y: number, x0: number, x1: number): number;
+interface PaneSafetyOpts {
+    /** The content pane to enforce (usually the app pane). */
+    region: Region;
+    /** Source-space frame size the region fractions refer to. Default 1080x1920. */
+    srcW?: number;
+    srcH?: number;
+    /** Ink fraction tolerated in the unsafe strip. Default 0.08. */
+    maxInkFrac?: number;
+}
+/**
+ * The regression guard for the paneSafeBox trap: a layer handed a pane must not
+ * draw content BELOW the frame's bottom-safe line, where the platform's caption
+ * and action rail sit. Computing a pane's safe box as `safeBox(paneW, paneH)`
+ * instead of intersecting with the frame silently grants ~226px of that strip,
+ * and the resulting clip only looks wrong once it is posted.
+ *
+ * Only meaningful for panes whose content is meant to be READ (notation, text,
+ * a keyboard). A full-bleed footage pane fills its whole rect by design and
+ * should not be enforced.
+ */
+declare function checkPaneSafety(frames: SampledFrames, o: PaneSafetyOpts): CheckResult;
+interface SeamPresentOpts {
+    /** Where the seam should be, as a fraction of the frame height. */
+    splitFrac: number;
+    srcH?: number;
+    /** Rows either side to search for the rule. Default 6 (source px). */
+    tolPx?: number;
+    /** Minimum span of the row that must read as seam ink. Default 0.9. */
+    minSpan?: number;
+}
+/**
+ * A composition regression guard: if the split silently collapsed (one pane
+ * covering the frame, a preset emitting no seam), the divider row disappears.
+ * Cheap to check and it fails loudly on the whole-layout failure mode that the
+ * per-layer checks cannot see.
+ */
+declare function checkSeamPresent(frames: SampledFrames, o: SeamPresentOpts): CheckResult;
+interface FaceInPaneOpts {
+    /** [x, y, w, h] fractions of the SOURCE. */
+    faceBox: [number, number, number, number];
+    /** Intrinsic source size. */
+    srcW: number;
+    srcH: number;
+    /** The pane the source is drawn into. */
+    region: Region;
+    frameW?: number;
+    frameH?: number;
+    fit?: VideoFit;
+    focus: {
+        x: number;
+        y: number;
+    };
+}
+interface FaceInPaneResult {
+    ok: boolean;
+    /** How much of the declared face box survives the crop, 0..1. */
+    visibleFrac: number;
+    /** The face's rect in FRAME pixels (empty when fully cropped out). */
+    frameRect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    reason?: string;
+}
+/**
+ * Whether the face a clip declares actually lands inside its pane after the
+ * cover-crop. This is pure geometry, not pixel face detection — the manifest
+ * already states where the face is, so the honest check is "did our own crop
+ * math keep it", which is exact rather than heuristic.
+ */
+declare function faceLandsInPane(o: FaceInPaneOpts): FaceInPaneResult;
+
+/** One ending treatment. `null` means "no end card on this variant". */
+type VariantEnding = NonNullable<ReactionSplitOpts['endCard']> | null;
+interface ReactionVariantsOpts {
+    /** Text hooks to rotate through. At least one. */
+    hooks: string[];
+    /** Reaction clips to rotate through. At least one. */
+    clips: ReactionClip[];
+    /** Ending treatments. Default `[null]` (no end card). */
+    endings?: VariantEnding[];
+    /** Everything the layout needs that is NOT a variant axis (app layers, split…). */
+    base: Omit<ReactionSplitOpts, 'reaction' | 'hook' | 'endCard'>;
+    /** How many variants to emit. Default: the full product (every combination). */
+    n?: number;
+    /** Prefix joined to each clip's file. */
+    baseUrl?: string;
+    /** Deterministic starting offset — change it to get a different ordering. */
+    seed?: number;
+}
+interface ReactionVariant {
+    /** Stable id derived from the axis picks; the same picks always yield it. */
+    id: string;
+    hook: string;
+    clipId: string;
+    endingIndex: number;
+    spec: SceneSpec;
+}
+/**
+ * A step size co-prime to `total`, near the golden-ratio fraction of it so the
+ * walk spreads rather than marching. Co-primality is what guarantees the walk
+ * visits every index exactly once before repeating.
+ */
+declare function coprimeStride(total: number): number;
+/**
+ * `n` index tuples over axes of the given `sizes`, distinct until the product is
+ * exhausted. Exported so the decorrelation is testable without building specs.
+ */
+declare function variantIndices(n: number, sizes: number[], seed?: number): number[][];
+/** Lowercase, hyphenated, ascii-ish slug for a variant id. */
+declare function slugify(s: string, max?: number): string;
+/**
+ * Generate `n` distinct reaction-split clips across the hook / clip / ending
+ * axes. Throws on an empty axis rather than silently emitting nothing.
+ */
+declare function reactionVariants(o: ReactionVariantsOpts): ReactionVariant[];
+
 /** 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. */
@@ -1802,4 +2210,4 @@ interface HandIndicatorProps {
 }
 declare const handIndicatorFactory: LayerFactory<HandIndicatorProps>;
 
-export { type Affine, AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatPulseProps, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordRibbonProps, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type CompositeRhythmProps, type ContourPlot, type ContourPoint, type CountInOpts, type CountdownProps, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type EndCardProps, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, type FallingKeyboardDemoOpts, type FallingNotesProps, type FretboardProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HandIndicatorProps, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type ImageRevealMode, type ImageRevealProps, type IntervalArcsProps, type KaraokeCaptionProps, type KaraokeWord, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type KineticMode, type KineticTextProps, type LabelMode, LayerFactory, type McqCardProps, type NotationEngraving, NotationLayout, type NotationProps, type OutputProbe, PIANO_HIGH, PIANO_LOW, type ParticleBurstProps, type PitchContourProps, type Placement, type PortraitProps, type ProgressRingProps, type PromoCardsDemoOpts, type PulseStyle, type Quiz, type QuizOption, type QuizPhase, type RadialSpectrumProps, type RayEndpoints, type RecordSceneSpecOpts, type Rect, RenderCtx, type ResolvedSegment, type RevealEasing, type RevealProps, SCALE_INTERVALS, type SafeGuidesProps, type ScaleHighlightProps, type SceneSpec, type ScheduleTarget, Score, ScoreFromMusicXMLOpts, ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type StaffKeyboardRayProps, type StatCounterProps, TempoMap, type TensionGraphProps, type TensionPoint, type TextureProps, type TimeAnchor, type TimelineSegment, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, ballArc, ballX, beatGrid, beatPhase, beatPulseFactory, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, chordRibbonFactory, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, compositeRhythmFactory, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownFactory, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, ctaFactory, cueOpacity, degreeLabel, degreeLabelsFactory, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, endCardFactory, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, followSrcBox, fracSlotPoint, frameRect, fretboardFactory, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, handIndicatorFactory, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, imageRevealFactory, inRange, intervalArcsFactory, invLerp, isBlackKey, karaokeCaptionFactory, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, kineticTextFactory, lerp, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureSpans, timeToX as minimapTimeToX, msPerBeat, notationFactory, noteColor, noteSetXRange, parseKey, parseTimeSig, particleBurstFactory, pcToSlot, pitchAt, pitchContourFactory, pitchRange, portraitFactory, progress01, progressRingFactory, projectPoint, promoCardsDemoSpec, pulseAt, quizPhase, radialSpectrumFactory, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scaleHighlightFactory, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, statCounterFactory, tensionGraphFactory, textureFactory, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, whiteKeys, worldToViewport };
+export { type Affine, AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatPulseProps, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type CheckFrame, type CheckResult, type ChordRibbonProps, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type CompositeRhythmProps, type ContourPlot, type ContourPoint, type CountInOpts, type CountdownProps, type CountingTrackProps, type CtaProps, DEFAULT_FOCUS, DEFAULT_FUNCTION_COLORS, DEFAULT_HOOK_CENTER_FRAC, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type EndCardProps, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FULL_REGION, type FaceInPaneOpts, type FaceInPaneResult, type FallingKeyboardDemoOpts, type FallingNotesProps, type FitBoxes, type FretboardProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HandIndicatorProps, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type ImageRevealMode, type ImageRevealProps, type IntervalArcsProps, type KaraokeCaptionProps, type KaraokeWord, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type KineticMode, type KineticTextProps, type LabelMode, LayerFactory, type McqCardProps, type NotationEngraving, NotationLayout, type NotationProps, type OutputProbe, PAPER_LUM_FLOOR, PIANO_HIGH, PIANO_LOW, type PaneSafetyOpts, type PaneSeamProps, type ParticleBurstProps, type PitchContourProps, type Placement, type PortraitProps, type ProgressRingProps, type PromoCardsDemoOpts, type PulseStyle, type Quiz, type QuizOption, type QuizPhase, REACTION_EMOTIONS, type RadialSpectrumProps, type RayEndpoints, type ReactionClip, type ReactionEmotion, type ReactionManifest, type ReactionPropsOpts, type ReactionSplitOpts, type ReactionVariant, type ReactionVariantsOpts, type RecordSceneSpecOpts, type Rect, type Region, RenderCtx, type ResolvedSegment, type RevealEasing, type RevealProps, SCALE_INTERVALS, type SafeGuidesProps, type SampledFrames, type ScaleHighlightProps, type SceneSpec, type ScheduleTarget, Score, ScoreFromMusicXMLOpts, ScoreNote, type ScrollCursorProps, type SeamPresentOpts, type SeamStyle, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type StaffKeyboardRayProps, type StatCounterProps, TempoMap, type TensionGraphProps, type TensionPoint, type TextureProps, type TimeAnchor, type TimelineSegment, type VariantEnding, type VideoClockMode, type VideoFit, type VideoSourceProps, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, assertReactionManifest, ballArc, ballX, beatGrid, beatPhase, beatPulseFactory, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, checkPaneSafety, checkSeamPresent, chordRibbonFactory, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, clipFocus, compositeRhythmFactory, contourMinimapDemoSpec, contourPoints, contourPolyline, coprimeStride, countInLeadSec, countInSchedule, countdownFactory, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, ctaFactory, cueOpacity, degreeLabel, degreeLabelsFactory, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, endCardFactory, faceLandsInPane, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, fitBoxes, followSrcBox, fracSlotPoint, frameRect, fretboardFactory, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, handIndicatorFactory, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, imageRevealFactory, inRange, inkFractionInRow, intervalArcsFactory, invLerp, isBlackKey, isFullRegion, karaokeCaptionFactory, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, kineticTextFactory, lerp, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureSpans, timeToX as minimapTimeToX, msPerBeat, needsSeek, notationFactory, noteColor, noteSetXRange, paneSafeBox, paneSeamFactory, parseKey, parseTimeSig, particleBurstFactory, pcToSlot, pickClips, pitchAt, pitchContourFactory, pitchRange, portraitFactory, progress01, progressRingFactory, projectPoint, promoCardsDemoSpec, pulseAt, quizPhase, radialSpectrumFactory, rayEndpoints, rayPointAt, reactionProps, reactionSplitSpec, reactionVariants, recordSceneSpec, regionRect, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scaleHighlightFactory, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, slugify, sourceSize, sourceTimeMs, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, statCounterFactory, tensionGraphFactory, textureFactory, transitionProgress, validateChordTrack, validateQuiz, validateReactionManifest, validateRegion, validateSections, variantIndices, videoSourceFactory, visualTimelineMs, whiteKeys, worldToViewport };