tonus 0.1.8 → 0.5.0

package/dist/engines/score/infer.d.ts

@@ -1,4 +1,4 @@
-import type { ChantType, Score } from "./types.js";
-export declare function inferChantType(ir: Score): ChantType | undefined;
-export declare function inferMode(ir: Score): number | undefined;
+import type { ChantType, ScoreIR } from "./types.js";
+export declare function inferChantType(ir: ScoreIR): ChantType | undefined;
+export declare function inferMode(ir: ScoreIR): number | undefined;
 //# sourceMappingURL=infer.d.ts.map

package/dist/engines/score/infer.js

@@ -1,4 +1,4 @@
-import { OFFICE_LABELS } from "../chant/types.js";
+import { OFFICIA } from "../chant/types.js";
 import { MODES } from "../temper/modes.js";
 // Identify an ordinary chant by its opening words. Two movements have a second,
 // interior incipit because they are conventionally intoned from their second
@@ -15,7 +15,7 @@ const ORDINARY_INCIPITS = [
     [/^benedica/i, "be"],
     [/^ite/i, "it"],
 ];
-const OFFICE_CODES = new Set(Object.keys(OFFICE_LABELS));
+const OFFICE_CODES = new Set(Object.keys(OFFICIA));
 export function inferChantType(ir) {
     const officePart = ir.chant.office?.toLowerCase().trim();
     if (officePart && OFFICE_CODES.has(officePart))

package/dist/engines/score/inscriptio.d.ts

@@ -0,0 +1,69 @@
+import { type NoteGeometry, type Theme } from "./emitters/svg.js";
+import type { TrackName } from "./emitters/tracks.js";
+import type { Score } from "./api.js";
+export interface InscriptioOpts {
+    /** Notation species. Square-note by default; "moderna" is the modern transcription. */
+    notation?: "quadrata" | "moderna";
+    /** Accidental channel. "standard" performance accidentals by default. */
+    accidentals?: "standard" | "heji" | "cents";
+    /** Baseline for the cents channel; the chant's home intonation by default. */
+    centsBaseline?: "pythagorean" | "et";
+    /**
+     * Analysis tracks drawn beneath each system: "chironomia" — the rhythmic
+     * band (wave, Pierik letters) — and "tonarium" — the melodic band (maneriae
+     * rails, pressure sparkline, mode line, cadence nodes). Either rides either
+     * species, and both may ride one score; they stack in a fixed order, the
+     * chironomia above the tonarium, whichever order they are asked for.
+     *
+     * The two-register principle is the house pairing — the rhythmic band under
+     * the square notation (the body), the melodic band under the transcription
+     * (the mind). It is a default worth keeping, not a constraint enforced here.
+     */
+    tracks?: readonly TrackName[];
+    /** Wrap systems to this px width. Absent = a single system (current behaviour). */
+    width?: number;
+    /**
+     * How big the chant is drawn: `"small"`, `"normal"` (default), `"large"`, or
+     * a staff height in px for fitting a known column. Everything scales from it
+     * — notes, lyrics, the gap between systems — and it reflows the music, so a
+     * larger scale means fewer notes per line.
+     */
+    scale?: "small" | "normal" | "large" | number;
+    title?: string;
+    rubric?: string;
+    /** Derive the rubric block from chant meta (feast / genus / modus / source). */
+    annotation?: "auto";
+    /** Draw a rubricated initial from the first lyric; the first system indents. */
+    dropcap?: boolean;
+    /**
+     * Faces, ink, and measurements — the whole look in one object.
+     *
+     * `fonts` carries four roles (`dropcap`, `title`, `annotation`, `lyric`), each
+     * a family string or `{ family, weight?, scale?, embed? }`. Without `embed`
+     * the SVG carries a font-family REFERENCE and the host page supplies the face;
+     * with it the CALLER's bytes ride inside the SVG's own `<style>` and the file
+     * is self-contained. tonus bundles no font files — with `embed` it is a
+     * conduit for data the consumer supplies, and the consumer carries the face's
+     * license terms.
+     *
+     * `colors` reaches the SVG as CSS custom properties with the theme's value as
+     * the fallback, so a host stylesheet can retheme a drawn chant without
+     * re-rendering it. `metrics` cannot work that way: staff height and note scale
+     * are consumed by line breaking long before a stylesheet sees the output.
+     */
+    theme?: Theme;
+}
+export interface Inscriptio {
+    svg: string;
+    geometry: NoteGeometry[];
+}
+/**
+ * Render a `Score` as SVG. Returns the markup plus a geometry array (one entry
+ * per note, tabula order) for downstream analysis tracks.
+ * @throws Error when `score` is not a valid Score (a builder-function contract).
+ */
+export declare function inscriptio(score: Score, opts?: InscriptioOpts): Inscriptio;
+export type { NoteGeometry } from "./emitters/svg.js";
+export type { FontSpec, FontSlot, FontEmbed, Theme, ThemeColors } from "./emitters/svg.js";
+export type { TrackName, TrackData } from "./emitters/tracks.js";
+//# sourceMappingURL=inscriptio.d.ts.map

package/dist/engines/score/inscriptio.js

@@ -0,0 +1,138 @@
+// ---------------------------------------------------------------------------
+// engines/score/inscriptio — the score renderer (SVG + geometry contract)
+// ---------------------------------------------------------------------------
+// `inscriptio` (the inscribing) draws a Score. Per the rendering boundary
+// (CODE-STANDARDS → Boundaries), rendering is a standalone function that TAKES a
+// score — not a method on one. It inks the score itself; the analysis tracks
+// (chironomia, the rhythmic band; tonarium, the melodic one) ship with it as
+// opt-in bands (`tracks`), either riding either species, drawn from the same
+// placements the geometry contract exports — never by scraping the notation.
+// Custom tracks remain downstream consumers of that contract. One emitter
+// format: SVG.
+//
+// The result is `{ svg, geometry }`. The geometry array — one entry per note in
+// tabula order — is the TRACK CONTRACT: downstream consumers place marks against
+// notes by index and coordinate, never by scraping the SVG.
+//
+// This is the standalone shell over the species emitters: the square-note
+// renderer (emitters/svg.ts) and the modern transcription (emitters/moderna.ts).
+// The multi-system layout engine, front matter, and the accidental channels
+// are all wired in through InscriptioOpts.
+import { toSvg, } from "./emitters/svg.js";
+import { toModerna } from "./emitters/moderna.js";
+// Options handed through to the species emitters — everything but the species
+// selector itself.
+const EMITTER_KEYS = [
+    "width",
+    "title", "rubric", "annotation", "dropcap",
+    "accidentals", "centsBaseline", "tracks",
+];
+/**
+ * Flatten a `theme` into the keys the emitters consume.
+ *
+ * The emitters take a flat option bag — one field per measurement, one per
+ * colour — because that is the shape a render loop wants. The theme is the
+ * shape a CALLER wants: faces, ink, and metrics travel together, and a house
+ * style is worth naming once. Resolving between them is this function's whole
+ * job, and it is the only place that knows both shapes.
+ */
+function flattenTheme(theme) {
+    if (!theme)
+        return {};
+    const out = {};
+    if (theme.fonts)
+        out.fonts = theme.fonts;
+    const c = theme.colors;
+    if (c?.note !== undefined)
+        out.noteColor = c.note;
+    if (c?.staffLine !== undefined)
+        out.staffLineColor = c.staffLine;
+    if (c?.rubrica !== undefined)
+        out.rubricaColor = c.rubrica;
+    return out;
+}
+/** The named sizes, as staff heights in px. `normal` is the default 40. */
+const SCALES = {
+    small: 30,
+    normal: 40,
+    large: 56,
+};
+/**
+ * Resolve `scale` to the emitter's `staffHeight`.
+ *
+ * A caller decides how big the chant should be, not how tall its staff is in
+ * pixels — so the public option is a size and the staff height is what it
+ * resolves to. A raw number still works for the caller who is fitting a known
+ * column, and means exactly what `staffHeight` meant.
+ */
+function resolveScale(scale) {
+    if (scale === undefined)
+        return undefined;
+    if (typeof scale === "number")
+        return scale;
+    const px = SCALES[scale];
+    if (px === undefined) {
+        throw new Error(`inscriptio: unknown scale "${scale}" ` +
+            `(expected ${Object.keys(SCALES).join(", ")}, or a staff height in px)`);
+    }
+    return px;
+}
+/**
+ * Render a `Score` as SVG. Returns the markup plus a geometry array (one entry
+ * per note, tabula order) for downstream analysis tracks.
+ * @throws Error when `score` is not a valid Score (a builder-function contract).
+ */
+export function inscriptio(score, opts = {}) {
+    if (!score || !Array.isArray(score.tabula)) {
+        throw new Error("inscriptio: expected a Score (from notatio)");
+    }
+    if (opts.notation && opts.notation !== "quadrata" && opts.notation !== "moderna") {
+        throw new Error(`inscriptio: unknown notation "${opts.notation}"`);
+    }
+    // The HEJI and cents channels are modern analytical overlays; they belong on
+    // the modern staff, not on historical square notation. Quadrata carries only
+    // the accidentals GABC itself expresses (flat/natural/sharp).
+    if (opts.notation !== "moderna" &&
+        (opts.accidentals === "heji" || opts.accidentals === "cents")) {
+        throw new Error(`inscriptio: accidentals "${opts.accidentals}" is a moderna-only intonation ` +
+            `overlay; square notation (quadrata) carries only GABC accidentals. ` +
+            `Use notation: "moderna".`);
+    }
+    // Any track rides either species, and all may ride one score — the
+    // selection is independent of the notation, as the notation itself is. An
+    // unknown name is a caller bug and throws.
+    for (const track of opts.tracks ?? []) {
+        if (track !== "prosodia" && track !== "chironomia" && track !== "tonarium") {
+            throw new Error(`inscriptio: unknown track "${track}" — tracks are "prosodia" ` +
+                `(the word band), "chironomia" (the rhythmic band) and "tonarium" ` +
+                `(the melodic band)`);
+        }
+    }
+    // Pass through the options the emitters consume; the species selector stays
+    // here. A species ignores, not errors on, options that do not apply to it.
+    // Both species honour the front matter (title, rubric/annotation) — the
+    // official opening is `title` + `annotation: "auto"`, no dropcap.
+    const emitterOpts = flattenTheme(opts.theme);
+    const staffHeight = resolveScale(opts.scale);
+    if (staffHeight !== undefined)
+        emitterOpts.staffHeight = staffHeight;
+    for (const k of EMITTER_KEYS)
+        if (opts[k] !== undefined)
+            emitterOpts[k] = opts[k];
+    // The tracks consume score-level analysis the flat tabula does not carry;
+    // hand it through only when a track asked for it.
+    if (opts.tracks && opts.tracks.length > 0) {
+        const modeDigit = score.chant.mode ? parseInt(score.chant.mode) : NaN;
+        const trackData = {
+            cadences: score.cadences,
+            modulations: score.modulations,
+            mode: Number.isFinite(modeDigit) ? modeDigit : undefined,
+        };
+        emitterOpts["trackData"] = trackData;
+    }
+    // Dispatch to the species' own renderer — each owns its spacing pass.
+    const render = opts.notation === "moderna" ? toModerna : toSvg;
+    const result = render(score.tabula, score.chant, emitterOpts);
+    return { svg: result.svg, geometry: result.geometry };
+}
+//# sourceMappingURL=inscriptio.js.map

package/dist/engines/score/ir.d.ts

@@ -1,5 +1,5 @@
-import type { CompoundBeat, RhythmicType, Score, ParseResult } from "./types.js";
+import type { CompoundBeat, RhythmicType, ScoreIR, ParseResult } from "./types.js";
 import type { Scale } from "../temper/scale.js";
 export declare function classifyRhythmicType(beats: CompoundBeat[]): RhythmicType;
-export declare function buildIR(parsed: ParseResult, chant: Score["chant"], scale: Scale): Score;
+export declare function buildIR(parsed: ParseResult, chant: ScoreIR["chant"], scale: Scale): ScoreIR;
 //# sourceMappingURL=ir.d.ts.map

package/dist/engines/score/ir.js

@@ -4,8 +4,14 @@ import { selectVowel } from "../chant/syllabify.js";
 import { classifyNeume } from "./neume.js";
 function rawToNote(raw, scale) {
     const midi = raw.step;
+    // One read of the lyric: the nucleus and the diphthong it belongs to.
+    const sung = selectVowel(raw.lyric);
     return {
-        pitch: toPitch(midi, scale),
+        // Spell the note as the SOURCE wrote it: a GABC `x` is a flat, `#` a sharp.
+        // Without the hint the speller reads the pitch class alone and calls a
+        // written D-flat "C#" — the same note, the opposite spelling, and `acc`
+        // reported +1 for a source that wrote a flat.
+        pitch: toPitch(midi, scale, raw.accidental === -1 ? "flat" : raw.accidental === 1 ? "sharp" : undefined),
         step: toStep(midi, scale),
         performance: {
             velocity: 0,
@@ -15,11 +21,22 @@ function rawToNote(raw, scale) {
         },
         context: {
             lyric: raw.lyric,
-            vowel: selectVowel(raw.lyric).vowel,
+            runs: raw.runs,
+            vowel: sung.vowel,
+            diphthong: sung.diphthong,
             syllableIndex: raw.syllableIndex,
+            accent: raw.accent,
             neumeGroup: raw.neumeGroup,
+            lineBreak: raw.lineBreak,
+            keepWithPrev: raw.keepWithPrev,
+            staffLetter: raw.staffLetter,
+            clef: raw.clef,
+            shape: raw.shape,
             ictus: raw.ictus,
+            ictusSign: raw.ictusSign,
+            episema: raw.episema,
             accidentalSource: raw.accidentalSource,
+            accidentalSign: raw.accidentalSign,
             quilisma: raw.quilisma,
             liquescent: raw.liquescent,
             strophicus: raw.strophicus,
@@ -29,16 +46,33 @@ function rawToNote(raw, scale) {
         },
     };
 }
-// The salicus ictus note (its second-to-last ascending note) is prolonged
-// [biblio: sunol-textbook, Ch. V]. Modest, in the spirit of an episema.
+// The salicus's principal note is prolonged. Modest, in the spirit of an
+// episema.
+//
+// WHICH note is Cardine's correction [biblio: cardine-semiology, ch. 16 §II].
+// The printed editions mark the note bearing the oriscus and the current
+// practice lengthens it, treating it as principal "because of its special
+// sign"; the manuscripts show the principal note is the one IMMEDIATELY
+// FOLLOWING the oriscus — the summit — with §II.A proving it from the St Gall
+// signs and the melodic tension toward that summit. The oriscus is a note of
+// passage, not of rest. This is the one point where the rhythmic layer
+// departs from Mocquereau/Suñol, and it departs deliberately.
+//
+// The summit is the LAST note of the ascent, because a salicus is ascending
+// by definition and the oriscus is its next-to-last note — so the note after
+// the oriscus is the final one, at any length. The 4- and 5-note forms need no
+// separate rule.
 const SALICUS_PROLONGATION = 1.3;
 function makeSyllable(lyric, notes) {
     const neume = classifyNeume(notes);
     if (neume.type === "salicus" && notes.length >= 2) {
-        const ictic = notes[notes.length - 2];
-        ictic.performance.duration *= SALICUS_PROLONGATION;
+        const summit = notes[notes.length - 1];
+        summit.performance.duration *= SALICUS_PROLONGATION;
     }
-    return { lyric, notes, neume };
+    const runs = notes[0]?.context.runs;
+    return runs
+        ? { lyric, runs, notes, neume, melisma: notes.length }
+        : { lyric, notes, neume, melisma: notes.length };
 }
 function partitionByIctus(annotated) {
     const groups = [];
@@ -140,7 +174,8 @@ function classifyCompoundBeats(annotated) {
 // only when the sequence genuinely fits; ambiguous shapes stay null (a wrong
 // analytic label is worse than none). Contraction (Type VIII) is Suñol's local
 // reading [biblio: sunol-textbook]: a thesis immediately followed by an arsis
-// mid-incise means two simple rhythms overlap at a shared ictus.
+// mid-incise means two simple rhythms overlap at a shared ictus — and, being two
+// *complete* rhythms, the incise still resolves thetic; an unresolved seam is null.
 export function classifyRhythmicType(beats) {
     if (beats.length < 2)
         return null; // a lone beat has no chaining; needs ≥ A–T
@@ -163,8 +198,16 @@ export function classifyRhythmicType(beats) {
         return null;
     }
     // There is at least one thesis→arsis seam, so the incise chains multiple simple
-    // rhythms. Strict alternation A–T–A–T(…) is Carroll's Type VII; any other seam
-    // pattern is a contraction (Suñol) — Carroll's Type VIII.
+    // rhythms — and a chain of *complete* rhythms must still resolve (end thetic).
+    // In juxtaposition "each thesis marks the end of one and each arsis the
+    // beginning of another" [biblio: sunol-textbook], so a chain left hanging arsic
+    // (A–T–A, A–T–A–T–A) has opened a rhythm it never closes: null, whatever the
+    // seam pattern. This gate applies to VII exactly as to VIII.
+    if (seq[seq.length - 1] !== "thetic")
+        return null;
+    // Strict alternation A–T–A–T(…) is Carroll's Type VII; any other seam
+    // pattern is a contraction (Suñol) — Carroll's Type VIII, two (or more)
+    // complete rhythms overlapping at a shared ictus.
     const alternating = seq.every((s, i) => s === (i % 2 === 0 ? "arsic" : "thetic"));
     if (alternating && seq.length >= 4)
         return "VII";
@@ -180,11 +223,15 @@ function applyCompoundBeats(phrases) {
         }
         phrase.beats = classifyCompoundBeats(annotated);
         phrase.rhythmicType = classifyRhythmicType(phrase.beats);
+        // Phrase-level conveniences: a sung syllable carries at least one note.
+        const sung = phrase.syllables.filter((s) => s.notes.length > 0);
+        phrase.syllableCount = sung.length;
+        phrase.noteCount = sung.reduce((n, s) => n + s.notes.length, 0);
     }
 }
 export function buildIR(parsed, chant, scale) {
     const phrases = [];
-    let currentPhrase = { syllables: [], beats: [], rhythmicType: null };
+    let currentPhrase = { syllables: [], noteCount: 0, syllableCount: 0, beats: [], rhythmicType: null };
     let currentNotes = [];
     let currentLyric = null;
     for (const event of parsed.events) {
@@ -209,7 +256,7 @@ export function buildIR(parsed, chant, scale) {
             }
             currentPhrase.divisio = event;
             phrases.push(currentPhrase);
-            currentPhrase = { syllables: [], beats: [], rhythmicType: null };
+            currentPhrase = { syllables: [], noteCount: 0, syllableCount: 0, beats: [], rhythmicType: null };
         }
     }
     if (currentLyric !== null && currentNotes.length > 0) {

package/dist/engines/score/lyric.d.ts

@@ -0,0 +1,23 @@
+import type { LyricRun } from "./types.js";
+export interface DecodedLyric {
+    /** Clean display text — tags decoded, specials as real Unicode. */
+    text: string;
+    /** Styled spans covering `text`, present only when some style rides. */
+    runs?: LyricRun[];
+    /** Inside an open `<nlba>` — do not break a line before this syllable. */
+    keepWithPrev?: boolean;
+}
+/**
+ * One decoder per GABC source. Feed it each syllable's raw text in document
+ * order; open styles carry across calls.
+ */
+export declare function createLyricDecoder(): {
+    decode(raw: string): DecodedLyric;
+};
+/**
+ * Trim a syllable's edge hyphens/whitespace from its runs, mirroring the
+ * emitters' display trim of the plain text, so the runs' concatenation stays
+ * equal to what is drawn.
+ */
+export declare function trimRuns(runs: LyricRun[]): LyricRun[];
+//# sourceMappingURL=lyric.d.ts.map

package/dist/engines/score/lyric.js

@@ -0,0 +1,234 @@
+// Gregorio's <sp> shortcuts, as they occur in the corpus. The barred letters
+// ℟/℣ have codepoints; the antiphon A takes the combining solidus. Unmapped
+// content (‡, ¶, …) passes through literally — <sp> is "insert this symbol".
+const SP_MAP = {
+    "R/": "℟", // ℟ response
+    "V/": "℣", // ℣ versicle
+    "A/": "A̸", // barred A (antiphon)
+    "*": "*", // the raised star (schola entry)
+    "+": "†", // † the flex cross
+    "ae": "æ", // æ
+    "'ae": "ǽ", // ǽ
+    "'æ": "ǽ", // 'æ → ǽ
+    "oe": "œ", // œ
+    "'oe": "œ́", // œ́
+    "oe'": "œ́", // corpus typo for the same
+    "'œ": "œ́",
+};
+// Editorial markers, each normalized to ONE style however the source wrote
+// them (<i>, <c>, or plain text): the psalm incipit "Ps." rubric red, as the
+// books print it; the iterum "ij."/"iij." (almost) always italic.
+const PS_MARK = /^(\s*)(Ps\.)(?=\s|$)/;
+const IJ_MARK = /(^|\s)(i{1,3}j\.)(?=\s|$)/;
+/** Decode a <v> verbatim-TeX payload to display text (page refs vanish). */
+function decodeTex(buf) {
+    const italic = /\\itshape\b/.test(buf);
+    const text = buf
+        .replace(/\\pageref\{[^}]*\}/g, "") // cross-refs to the paper book
+        .replace(/\\greheightstar\b/g, "*")
+        .replace(/\\ddag\b/g, "‡")
+        .replace(/\\P\b/g, "¶")
+        .replace(/\\textup\{([^}]*)\}/g, "$1")
+        .replace(/\\ /g, " ") // control space
+        .replace(/\\[a-zA-Z]+\*?/g, "") // any remaining command
+        .replace(/[{}]/g, "");
+    return { text, italic };
+}
+/** Plain lyric characters: centering braces drop, ~ is a TeX placeholder. */
+function cleanText(s) {
+    return s.replace(/[{}~]/g, "");
+}
+/**
+ * One decoder per GABC source. Feed it each syllable's raw text in document
+ * order; open styles carry across calls.
+ */
+export function createLyricDecoder() {
+    const st = {
+        italic: 0, bold: 0, smallCaps: 0, rubric: 0, alt: 0, nlba: 0, capture: null,
+        pendingSpace: false,
+    };
+    return {
+        decode(raw) {
+            const runs = [];
+            let styled = false;
+            const nlbaAtEntry = st.nlba;
+            let openedHere = false;
+            const push = (text, extraItalic = false) => {
+                if (!text || st.alt > 0)
+                    return;
+                if (st.pendingSpace) {
+                    // "℣Jubilate" → "℣ Jubilate"; "℣." keeps its period tight.
+                    if (/^[A-Za-zÀ-ÿĀ-ž]/.test(text))
+                        text = " " + text;
+                    st.pendingSpace = false;
+                }
+                const run = { text };
+                if (st.italic > 0 || extraItalic)
+                    run.italic = true;
+                if (st.bold > 0)
+                    run.bold = true;
+                if (st.smallCaps > 0)
+                    run.smallCaps = true;
+                if (st.rubric > 0)
+                    run.rubric = true;
+                if (run.italic || run.bold || run.smallCaps || run.rubric)
+                    styled = true;
+                const prev = runs[runs.length - 1];
+                if (prev &&
+                    !prev.italic === !run.italic && !prev.bold === !run.bold &&
+                    !prev.smallCaps === !run.smallCaps && !prev.rubric === !run.rubric) {
+                    prev.text += text;
+                }
+                else {
+                    runs.push(run);
+                }
+            };
+            for (const part of raw.split(/(<[^<>]*>)/)) {
+                if (!part)
+                    continue;
+                if (part.startsWith("<") && part.endsWith(">")) {
+                    const tag = part.slice(1, -1).toLowerCase();
+                    switch (tag) {
+                        case "i":
+                        case "e":
+                            st.italic++;
+                            break; // elision renders italic
+                        case "/i":
+                        case "/e":
+                            st.italic = Math.max(0, st.italic - 1);
+                            break;
+                        case "b":
+                            st.bold++;
+                            break;
+                        case "/b":
+                            st.bold = Math.max(0, st.bold - 1);
+                            break;
+                        case "sc":
+                            st.smallCaps++;
+                            break;
+                        case "/sc":
+                            st.smallCaps = Math.max(0, st.smallCaps - 1);
+                            break;
+                        case "c":
+                            st.rubric++;
+                            break;
+                        case "/c":
+                            st.rubric = Math.max(0, st.rubric - 1);
+                            break;
+                        case "alt":
+                            st.alt++;
+                            break;
+                        // The one layout hint that survives decoding. <nlba> spans a group
+                        // the editor will not let a line break inside — "T. P. Allelúia"
+                        // and its verse, kept whole. It is a span like <i>, opening in one
+                        // syllable and closing several later, so it counts depth here and
+                        // is read per-syllable rather than resolved into the text.
+                        case "nlba":
+                            if (nlbaAtEntry === 0)
+                                openedHere = true;
+                            st.nlba++;
+                            break;
+                        case "/nlba":
+                            st.nlba = Math.max(0, st.nlba - 1);
+                            break;
+                        case "/alt":
+                            st.alt = Math.max(0, st.alt - 1);
+                            break;
+                        case "sp":
+                            st.capture = { kind: "sp", buf: "" };
+                            break;
+                        case "/sp": {
+                            const buf = (st.capture?.buf ?? "").trim();
+                            st.capture = null;
+                            if (buf) {
+                                const mapped = SP_MAP[buf] ?? buf;
+                                push(mapped);
+                                if (mapped === "℣" || mapped === "℟")
+                                    st.pendingSpace = true;
+                            }
+                            break;
+                        }
+                        case "v":
+                            st.capture = { kind: "v", buf: "" };
+                            break;
+                        case "/v": {
+                            const tex = decodeTex(st.capture?.buf ?? "");
+                            st.capture = null;
+                            if (tex.text)
+                                push(tex.text, tex.italic);
+                            break;
+                        }
+                        // Structural / layout markup with no display form: the euouae
+                        // marker (its text prints plain), no-line-break areas, above-lines
+                        // clears — and anything unrecognized drops its brackets, keeps its
+                        // content (the pre-decode behavior, minus the visible tag soup).
+                        default: break;
+                    }
+                }
+                else if (st.capture) {
+                    st.capture.buf += part;
+                }
+                else {
+                    push(cleanText(part));
+                }
+            }
+            const text = runs.map((r) => r.text).join("");
+            // Normalize the editorial markers: the marker's span takes EXACTLY its
+            // one style, clearing whatever markup the source happened to wrap it in.
+            let out = styled ? runs : null;
+            const sliceRuns = (from, a, b) => {
+                const acc = [];
+                let pos = 0;
+                for (const run of from) {
+                    const s = Math.max(a, pos);
+                    const e = Math.min(b, pos + run.text.length);
+                    if (e > s)
+                        acc.push({ ...run, text: run.text.slice(s - pos, e - pos) });
+                    pos += run.text.length;
+                }
+                return acc;
+            };
+            const restyle = (start, end, style) => {
+                const base = out ?? [{ text }];
+                out = [
+                    ...sliceRuns(base, 0, start),
+                    { text: text.slice(start, end), ...style },
+                    ...sliceRuns(base, end, text.length),
+                ];
+            };
+            const ps = PS_MARK.exec(text);
+            if (ps)
+                restyle(ps[1].length, ps[1].length + ps[2].length, { rubric: true });
+            const ij = IJ_MARK.exec(text);
+            if (ij) {
+                const start = ij.index + ij[1].length;
+                restyle(start, start + ij[2].length, { italic: true });
+            }
+            // Depth is read AFTER the syllable's own tags are applied. A group opens
+            // with `<nlba>` at the head of its first syllable, so that syllable is
+            // already inside the span and every later one is too — which is what the
+            // flag has to mean: no break BEFORE me. The first syllable of the group
+            // may still start a line; it is the seam inside the group that is sealed.
+            const keep = st.nlba > 0 && !openedHere;
+            const res = out ? { text, runs: out } : { text };
+            if (keep)
+                res.keepWithPrev = true;
+            return res;
+        },
+    };
+}
+/**
+ * Trim a syllable's edge hyphens/whitespace from its runs, mirroring the
+ * emitters' display trim of the plain text, so the runs' concatenation stays
+ * equal to what is drawn.
+ */
+export function trimRuns(runs) {
+    const out = runs.map((r) => ({ ...r }));
+    if (out.length > 0)
+        out[0].text = out[0].text.replace(/^-+/, "").replace(/^\s+/, "");
+    const last = out[out.length - 1];
+    if (last)
+        last.text = last.text.replace(/-+$/, "").replace(/\s+$/, "");
+    return out.filter((r) => r.text.length > 0);
+}
+//# sourceMappingURL=lyric.js.map

package/dist/engines/score/meta.d.ts

@@ -1,4 +1,4 @@
-import type { ChantType, Score } from "./types.js";
+import type { ChantType, ScoreIR } from "./types.js";
 export interface ChantMeta {
     mode: number | null;
     modeAlias: string | null;
@@ -15,5 +15,5 @@ export interface ChantMetaOptions {
     mode?: number;
     office?: ChantType;
 }
-export declare function computeMeta(ir: Score, options?: ChantMetaOptions): ChantMeta;
+export declare function computeMeta(ir: ScoreIR, options?: ChantMetaOptions): ChantMeta;
 //# sourceMappingURL=meta.d.ts.map

package/dist/engines/score/modulation.d.ts

@@ -8,6 +8,18 @@ export interface Modulation {
     toMode: number;
     /** 0–1: how strongly the foreign mode outscored the home mode, averaged. */
     confidence: number;
+    /**
+     * What the span is evidence of. "inflection" — a single phrase leaning away
+     * and back: passing colour, not a shift. "modulation" — a SUSTAINED internal
+     * excursion, two phrases or more, that returns. "transposition" — the whole
+     * chant sits in a foreign mode's frame
+     * (it does not close on its labeled final, and one foreign mode dominates
+     * most of its phrases), i.e. the melody is notated at a transposed position
+     * (the affinal) or the label disagrees with the notation. A transposed chant
+     * is not modulating: the displacement is global, and callers displaying
+     * "modulations" should treat these spans as a re-reading of the whole chant.
+     */
+    kind: "inflection" | "modulation" | "transposition";
 }
 /**
  * Detect tonal-centre shifts. For each phrase, score it against every mode; a