tonus 0.1.8 → 0.5.0

package/dist/engines/score/emitters/tracks.d.ts

@@ -0,0 +1,104 @@
+import type { ChantTabulaRow } from "../tabula.js";
+import type { Cadence } from "../cadence.js";
+import type { Modulation } from "../modulation.js";
+export type TrackName = "prosodia" | "chironomia" | "tonarium";
+/** Analysis fields inscriptio hands the emitters when tracks are requested —
+ * the score-level data the flat tabula does not carry. */
+export interface TrackData {
+    /**
+     * Normally `score.cadences`, whose `finality` the score builder has already
+     * joined from the catalogue. Cadences taken straight from `detectCadences`
+     * carry `finality: null` everywhere, and the terminal node quietly falls
+     * back to the modal target — a close on the finalis reads as closing, and
+     * everything else as suspending. Correct behaviour, but coarser than the
+     * measured answer, so pass the built score's cadences unless you mean it.
+     */
+    cadences: Cadence[];
+    modulations: Modulation[];
+    /** Mode digit parsed from the chant's label; absent = no mode line. */
+    mode?: number;
+}
+/** One placed note as the emitters record it — the tracks' working unit.
+ * The same anchors the geometry contract exports, with the row attached. */
+export interface TrackNote {
+    row: ChantTabulaRow;
+    /** The note's anchor — where the emitter placed it. */
+    x: number;
+    y: number;
+    system: number;
+    systemY: number;
+    /** The figure's measured ink edges. A track that SPANS notes — the cadence
+     *  bracket, an arc over a neume — must reach the ink, not the anchors: a
+     *  span drawn anchor-to-anchor is narrower than the notes it names and sits
+     *  left of their centre, because an anchor is where a glyph starts rather
+     *  than where it sits. The emitters have measured these all along and the
+     *  mapping into TrackNote used to drop them. */
+    inkLeft: number;
+    inkRight: number;
+}
+/** One track's room within the band a system reserves below its lyric line. */
+export interface TrackBand {
+    /** This band's top, offset from the start of the track region. */
+    top: number;
+    /** The room this band takes. */
+    height: number;
+}
+/** THE STACK. Every track rides either species and all may ride one score
+ * together, so the band room is the sum of what each asks for. The order is
+ * fixed here, not by the caller's array: the prosodia rides FIRST, directly
+ * under the lyric line — it reads the text itself, so it stays closest to
+ * it; the chironomia next, its wave an extension of the lyric line's
+ * rhythm; the tonarium below, a panel whose label row is its bottom edge
+ * and wants nothing under it. Requesting ["tonarium", "chironomia"]
+ * therefore draws exactly what ["chironomia", "tonarium"] draws. */
+export declare function trackBands(tracks: readonly TrackName[] | undefined, k: number): {
+    prosodia: TrackBand | null;
+    chironomia: TrackBand | null;
+    tonarium: TrackBand | null;
+    extra: number;
+};
+export interface ProsodiaConfig {
+    /** Scale factor: staffInterval / (40/6) — 1 at the default staffHeight. */
+    k: number;
+    /** Band top within a system (system-local): the lyric baseline plus the
+     *  band's offset in the stack. */
+    laneTop: number;
+    /** Right edge available to the band, per system (page x). */
+    rightFor: (system: number) => number;
+    /** The liturgical red for the accent dots (the 2026-08-11 amendment). */
+    rubricaColor: string;
+}
+/** Band room the prosodia reserves below each system's lyric line. The 8
+ *  beyond the band's own ink is AIR: without it the chironomia's crest
+ *  letters sat visibly tighter to this band than the tonarium sits to the
+ *  wave's troughs, and the stack read as unevenly spaced. */
+export declare function prosodiaExtra(k: number): number;
+/** The prosodia track, every system. */
+export declare function buildProsodia(notes: TrackNote[], cfg: ProsodiaConfig): string;
+export interface ChironomiaConfig {
+    /** Scale factor: staffInterval / (40/6) — 1 at the default staffHeight. */
+    k: number;
+    /** y of the wave's midline within a system (system-local). */
+    waveMidY: number;
+}
+/** Band room the chironomia reserves below each system's lyric line. */
+export declare function chironomiaExtra(k: number): number;
+/** The chironomy track: wave + letters, every system. */
+export declare function buildChironomia(notes: TrackNote[], cfg: ChironomiaConfig): string;
+export interface TonariumConfig {
+    /** Scale factor: staffInterval / (40/6) — 1 at the default staffHeight. */
+    k: number;
+    /** Lane top within a system (system-local). */
+    laneTop: number;
+    /** Right edge available to the lane, per system (page x). */
+    rightFor: (system: number) => number;
+    /** Serif family for the mode numerals (the lyric/annotation face). */
+    serifFamily: string;
+    /** The liturgical red for the mode line. */
+    rubricaColor: string;
+}
+/** Band room the tonarium reserves below each system's lyric line. */
+export declare function tonariumExtra(k: number): number;
+/** The tonarium track, every system. */
+export declare function buildTonarium(notes: TrackNote[], data: TrackData, cfg: TonariumConfig): string;
+//# sourceMappingURL=tracks.d.ts.map