tonus 0.1.8 → 0.5.0

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

@@ -1,6 +1,6 @@
-import type { Score, Neume } from "./types.js";
+import type { ScoreIR, Neume, LyricRun } from "./types.js";
 import type { Cadence } from "./cadence.js";
-import type { ChantType, InterpretationOptions } from "./types.js";
+import type { ChantType, InterpretationOptions, WrittenShape } from "./types.js";
 export type NoteRole = "finalis" | "tenor" | "other" | null;
 export interface ChantTabulaRow {
     phraseIndex: number;
@@ -11,7 +11,25 @@ export interface ChantTabulaRow {
     /** 0-based position of this note within its neume figure. */
     neumeIndex: number;
     lyric: string;
+    /** Styled lyric spans; present only when GABC markup styled this syllable. */
+    runs?: LyricRun[];
     vowel: string;
+    /**
+     * The diphthong the sung vowel belongs to — `ae` · `oe` · `au`, and `ui` in the
+     * cui/hui stems — or null. `vowel` is its NUCLEUS (what the singer sustains);
+     * the second element is a late off-glide. Only the syllabifier can tell a
+     * diphthong from a hiatus, since the accent decides: `cae` is one syllable,
+     * `sa-é` is two.
+     */
+    diphthong: string | null;
+    /** True when this note's syllable bears the Latin tonic word-accent. */
+    accent: boolean;
+    /** True when this note's syllable is the first of its word. */
+    wordStart: boolean;
+    /** The engraver asked for a line break BEFORE this note (GABC `z`). */
+    lineBreak: boolean;
+    /** Inside `<nlba>` — the engraver forbade a break before this note. */
+    keepWithPrev: boolean;
     /** MIDI pitch number (after transpose, clamped 0–127) */
     midi: number;
     /** Pitch class 0–11 (C=0) */
@@ -22,8 +40,16 @@ export interface ChantTabulaRow {
     degree: number | null;
     hz: number;
     offset: number;
-    /** Scientific pitch name, e.g. "D4", "Bb3" — the MusicXML step + octave. */
+    /** Scientific pitch name, e.g. "D4", "Bb3" — the step + octave. */
     spn: string;
+    /** Raw GABC pitch letter a–m — the square-note staff slot. */
+    staffLetter: string;
+    /** Staff position in half-spaces from the bottom line (a=−2 … g=4 … m=10). */
+    staffPosition: number;
+    /** Active GABC clef when this note sounded, e.g. "c4", "fb3". */
+    clef: string;
+    /** Written note shape (punctum, virga, inclinatum, …). */
+    shape: WrittenShape;
     /** 14-bit MIDI pitch bend for this note's microtuning (8192 = center). */
     bend: number;
     /** Solesmes quality of this note's compound beat (shared across group). */
@@ -35,9 +61,15 @@ export interface ChantTabulaRow {
     velocity: number | null;
     shapedDuration: number;
     ictus: boolean;
+    /** Written vertical episema / ictus mark ('), distinct from the analytical `ictus`. */
+    ictusSign: boolean;
+    /** Written horizontal episema (_), distinct from `mora`. */
+    episema: boolean;
     accidental: -1 | 0 | 1;
     /** How this note's accidental arose — only "explicit" prints a glyph. */
     accidentalSource: "none" | "state" | "explicit";
+    /** The sign to draw before this note, if any. */
+    accidentalSign?: -1 | 0 | 1;
     quilisma: boolean;
     liquescent: boolean;
     strophicus: boolean;
@@ -47,7 +79,7 @@ export interface ChantTabulaRow {
     divisio: string | null;
     /** Index into score.cadences[] when this note forms a cadence; null otherwise. */
     cadenceRef: number | null;
-    /** Modal role: "final" | "tenor" | "mod" (modulation) | null if no mode or no match */
+    /** Modal role: "finalis" | "tenor" | "other" | null if no mode or no match */
     role: NoteRole;
     /** Guidonian short name (e.g. "g", "aa") — null for chromatic pitches with no gamut entry */
     name: string | null;
@@ -74,5 +106,5 @@ export interface TabulaOptions {
     /** Detected cadences; used to stamp each row's cadenceRef. */
     cadences?: Cadence[];
 }
-export declare function computeTabula(ir: Score, options?: TabulaOptions): ChantTabulaRow[];
+export declare function computeTabula(ir: ScoreIR, options?: TabulaOptions): ChantTabulaRow[];
 //# sourceMappingURL=tabula.d.ts.map

package/dist/engines/score/tabula.js

@@ -2,6 +2,7 @@ import { MODES } from "../temper/modes.js";
 import { buildPhrasing, shapePhrasingForMode, applyPhrasing, } from "./phrasing.js";
 import { inferMode } from "./infer.js";
 import { CHROMA_TO_SOLFEGE as SOLFEGE_BY_PC } from "../temper/data/constants.js";
+import { staffPositionForLetter } from "../../data/gabc-glyphs.js";
 export function computeTabula(ir, options = {}) {
     const modeNum = options.mode ?? inferMode(ir);
     const modeData = modeNum !== undefined ? MODES.get(modeNum) : undefined;
@@ -83,7 +84,17 @@ export function computeTabula(ir, options = {}) {
             neumeGroup: n.context.neumeGroup,
             neumeIndex: neumeIndices[i],
             lyric: n.context.lyric,
+            runs: n.context.runs,
             vowel: n.context.vowel,
+            diphthong: n.context.diphthong,
+            accent: n.context.accent,
+            // wordStart reads the note's CONTEXT syllable index (the parser's, which
+            // resets to 0 at each word boundary — so 0 = word start), NOT the row's
+            // own `syllableIndex` above (a global per-phrase counter). Two indices,
+            // two meanings; the per-word one is what marks words.
+            wordStart: n.context.syllableIndex === 0,
+            lineBreak: n.context.lineBreak === true,
+            keepWithPrev: n.context.keepWithPrev === true,
             midi: n.pitch.midi,
             pc: n.pitch.pc,
             octave: n.pitch.oct,
@@ -91,6 +102,10 @@ export function computeTabula(ir, options = {}) {
             hz: n.pitch.hz,
             offset: n.pitch.offset,
             spn: n.pitch.spn,
+            staffLetter: n.context.staffLetter,
+            staffPosition: staffPositionForLetter(n.context.staffLetter) ?? 0,
+            clef: n.context.clef,
+            shape: n.context.shape,
             bend: n.pitch.bend,
             rhythmicShape: n.performance.rhythmicShape,
             rhythmicIndex: n.performance.rhythmicIndex,
@@ -98,8 +113,11 @@ export function computeTabula(ir, options = {}) {
             velocity: velocities[i],
             shapedDuration: shapedDurations[i],
             ictus: n.context.ictus,
+            ictusSign: n.context.ictusSign,
+            episema: n.context.episema,
             accidental: n.pitch.acc,
             accidentalSource: n.context.accidentalSource,
+            accidentalSign: n.context.accidentalSign,
             quilisma: n.context.quilisma,
             liquescent: n.context.liquescent,
             strophicus: n.context.strophicus,

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

@@ -14,14 +14,59 @@ export interface Performance {
     rhythmicShape: ArsisThesis;
     rhythmicIndex: number;
 }
+export type WrittenShape = "punctum" | "inclinatum" | "virga" | "virgaReversa" | "quilisma" | "oriscus" | "strophicus" | "cavum" | "linea";
+/**
+ * One styled span of a syllable's lyric — the decoded form of GABC's text
+ * markup (<i>, <b>, <sc>, <c>, elisions). The spans concatenate to the
+ * syllable's `lyric`; style flags are absent when a span is plain.
+ */
+export interface LyricRun {
+    text: string;
+    italic?: boolean;
+    bold?: boolean;
+    smallCaps?: boolean;
+    /** Rendered in the rubric color (GABC's <c>). */
+    rubric?: boolean;
+}
 export interface Context {
     lyric: string;
+    /** Styled lyric spans; present only when GABC markup styled this syllable. */
+    runs?: LyricRun[];
     vowel: string;
+    /**
+     * The diphthong this syllable's sung vowel belongs to (`ae` · `oe` · `au`, and
+     * `ui` in the cui/hui stems), or null. `vowel` above is its NUCLEUS — what the
+     * singer sustains; the pair's second element is a late off-glide. Reported
+     * here because only the syllabifier can tell a diphthong from a hiatus: the
+     * accent decides (`cae` is one syllable, `sa-é` is two).
+     */
+    diphthong: string | null;
     syllableIndex: number;
+    /** True when this note's syllable bears the Latin tonic word-accent. */
+    accent: boolean;
     /** 0-based index of the neume figure within the syllable (GABC break markers). */
     neumeGroup: number;
+    /** The engraver asked for a line break BEFORE this note — GABC's `z` (and
+     *  `Z`, its page-break sibling, honoured the same way since tonus paginates
+     *  nothing). An editor who set a chant chose where its lines end, and that
+     *  choice carries information a width cannot: a break at the right place is
+     *  an editorial reading of the piece. Where it is absent the layout decides. */
+    lineBreak?: boolean;
+    keepWithPrev?: boolean;
+    /** Raw GABC pitch letter a–m — the staff slot for square-note rendering. */
+    staffLetter: string;
+    /** Active GABC clef when this note sounded, e.g. "c4", "fb3". */
+    clef: string;
+    /** Written note shape (punctum, virga, inclinatum, …). */
+    shape: WrittenShape;
     ictus: boolean;
+    /** Written vertical episema / ictus mark ('), distinct from the analytical `ictus`. */
+    ictusSign: boolean;
+    /** Written horizontal episema (_), distinct from `mora`. */
+    episema: boolean;
     accidentalSource: "none" | "state" | "explicit";
+    /** The sign to DRAW before this note (see parse.ts) — distinct from `accidental`. */
+    accidentalSign?: -1 | 0 | 1;
     quilisma: boolean;
     liquescent: boolean;
     strophicus: boolean;
@@ -116,14 +161,37 @@ export interface ParsedNote {
     type: "note";
     step: number;
     lyric: string;
+    /** Styled lyric spans; present only when GABC markup styled this syllable. */
+    runs?: LyricRun[];
     syllableIndex: number;
+    /** True when this note's syllable bears the Latin tonic word-accent. */
+    accent: boolean;
     /** 0-based index of the neume figure within the syllable (GABC break markers). */
     neumeGroup: number;
+    /** The engraver asked for a line break BEFORE this note — GABC's `z` (and
+     *  `Z`, its page-break sibling, honoured the same way since tonus paginates
+     *  nothing). An editor who set a chant chose where its lines end, and that
+     *  choice carries information a width cannot: a break at the right place is
+     *  an editorial reading of the piece. Where it is absent the layout decides. */
+    lineBreak?: boolean;
+    keepWithPrev?: boolean;
+    /** Raw GABC pitch letter a–m — the staff slot for square-note rendering. */
+    staffLetter: string;
+    /** Active GABC clef when this note sounded, e.g. "c4", "fb3". */
+    clef: string;
+    /** Written note shape (punctum, virga, inclinatum, …). */
+    shape: WrittenShape;
     ictus: boolean;
+    /** Written vertical episema / ictus mark ('), distinct from analytical `ictus`. */
+    ictusSign: boolean;
+    /** Written horizontal episema (_), distinct from `mora`. */
+    episema: boolean;
     weight: number;
     duration: number;
     accidental: -1 | 0 | 1;
     accidentalSource: "none" | "state" | "explicit";
+    /** The sign to DRAW before this note (see parse.ts) — distinct from `accidental`. */
+    accidentalSign?: -1 | 0 | 1;
     quilisma: boolean;
     liquescent: boolean;
     strophicus: boolean;
@@ -150,18 +218,37 @@ export interface Neume {
 }
 export interface Syllable {
     lyric: string;
+    /** Styled lyric spans; present only when GABC markup styled this syllable. */
+    runs?: LyricRun[];
     notes: Note[];
     neume: Neume;
+    /** Notes sung on this syllable — its melisma. 1 = syllabic, >1 = melismatic. */
+    melisma: number;
 }
 export interface Phrase {
     syllables: Syllable[];
     divisio?: RestEvent;
+    /** Total notes across this phrase's syllables. */
+    noteCount: number;
+    /** Sung syllables in this phrase (syllables carrying at least one note). */
+    syllableCount: number;
     /** The phrase's compound beats in order — the A/T sequence of the incise. */
     beats: CompoundBeat[];
     /** Le Guennant/Carroll rhythmic type of the incise; null if none fits. */
     rhythmicType: RhythmicType;
 }
-export interface Score {
+/**
+ * What `buildIR` returns: the parsed, phrased, rhythm-classified melody before
+ * any analysis rides on it. Every downstream pass (meta, infer, tabula) takes
+ * one of these and names its parameter `ir`.
+ *
+ * This was called `Score` and shadowed the real one in api.ts — same name, a
+ * strict subset of its fields, and a `chant` narrowed to three strings. Nothing
+ * distinguished them at an import site, so the wrong one could be imported and
+ * still typecheck against the fields it happened to share. The public Score is
+ * the nine-field record in api.ts; this is its input.
+ */
+export interface ScoreIR {
     chant: {
         incipit: string;
         mode: string | null;

package/dist/engines/temper/api.d.ts

@@ -1,4 +1,4 @@
-import type { Scale, ScaleOpts, ScalaFile, RatioResult } from "./scale.js";
+import type { Scale, ScaleOpts, ScalaFile, RatioResult, Lupus } from "./scale.js";
 import type { Pitch, PitchInput } from "./pitch.js";
 import type { Step, StepVariant, Finger, Region } from "./step.js";
 import type { Interval, IntervalDirection, IntervalQuality } from "./interval.js";
@@ -60,6 +60,9 @@ export interface Temperamentum {
     ratio(input: string): RatioResult & {
         step: Step | null;
     };
+    /** The wolf, or null when no fifths chain built this scale. UNDOCUMENTED:
+     *  the site is its only caller and the shape is still settling. */
+    lupus(): Lupus | null;
     gamut(opts?: GamutOptions): Pitch[];
     modus(mode: number): Modus;
     tonus(opts?: TonusOpts): Tonus;

package/dist/engines/temper/api.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
 // engines/temper/api — Temperamentum context builder
 // ---------------------------------------------------------------------------
-import { buildRatios, parseScala, getPtolemaicRatios, toRatio } from "./scale.js";
+import { buildRatios, parseScala, getPtolemaicRatios, toRatio, wolfOf } from "./scale.js";
 import { parsePitch, toPitch } from "./pitch.js";
 import { toStep } from "./step.js";
 import { classifyInterval } from "./interval.js";
@@ -10,11 +10,20 @@ import { buildGamut } from "./gamut.js";
 import { getMode } from "./modes.js";
 import { getTone, getDifferentia } from "./data/tones.js";
 function resolveOpts(input) {
-    if (!input)
+    if (input == null)
         return {};
     if (typeof input === "string")
         return { tuning: input };
-    return input;
+    if (typeof input !== "object")
+        throw new Error(`temperamentum input must be a tuning name or an options object, got ${typeof input}`);
+    const opts = input;
+    if (opts.tuning != null && typeof opts.tuning !== "string")
+        throw new Error(`tuning must be a string, got ${typeof opts.tuning}`);
+    if (opts.mode != null &&
+        opts.mode !== "auto" &&
+        (!Number.isInteger(opts.mode) || opts.mode < 1 || opts.mode > 8))
+        throw new RangeError(`Unknown mode: ${opts.mode}. Supported: 1–8 or "auto".`);
+    return opts;
 }
 function resolveScale(opts) {
     if (!opts.scale)
@@ -49,8 +58,10 @@ function tuningToScaleOpts(opts) {
                 break;
             default: {
                 const ptolemaic = getPtolemaicRatios(tuning);
-                if (ptolemaic)
-                    scalaOpts.steps = ptolemaic;
+                if (!ptolemaic)
+                    throw new Error(`Unknown tuning: "${tuning}". Built-ins: pythagorean, meantone, equal, ` +
+                        `ptolemy-intense, ptolemy-soft, ptolemy-equable — or pass a scale.`);
+                scalaOpts.steps = ptolemaic;
                 break;
             }
         }
@@ -93,6 +104,18 @@ export function buildTemper(input) {
         neuma(inputs) {
             return buildNeume(inputs, scala);
         },
+        /** The wolf of THIS temperament.
+         *
+         *  Null when the scale was supplied rather than stacked: a Ptolemaic
+         *  genus and a Scala list arrive as ratios, so there is no chain of
+         *  fifths and nothing is left over. Returning a number there would be
+         *  inventing one.
+         */
+        lupus() {
+            if (scalaOpts.steps != null)
+                return null;
+            return wolfOf(scala.comma);
+        },
         ratio(input) {
             const result = toRatio(input);
             const folded = result.ratio >= 2 ? result.ratio / Math.pow(2, Math.floor(Math.log2(result.ratio))) : result.ratio;

package/dist/engines/temper/data/guido.js

@@ -4,8 +4,12 @@
 // little→index, descend the index, then spiral inward; ee (76) floats above the
 // middle fingertip (region "super"). The two b/♮ pairs (58/59, 70/71) share a
 // locus by design — one joint, two readings (fa in molle, mi in durum), the
-// tradition, not a duplication to fix. After Suñol [biblio: sunol-textbook] and
-// Apel [biblio: apel-chant]; realized in working/diagram-hand-08.html.
+// tradition, not a duplication to fix. They are one distinction, named for the
+// two shapes of the letter: b rotundum (the round b) against b quadratum (the
+// square b), which is where ♭ and ♮ come from. A RENDERER may draw them with
+// the medieval glyphs (GLYPH.flat / GLYPH.natural); these names stay letters,
+// because this table names joints rather than drawing them. After Suñol
+// [biblio: sunol-textbook] and Apel [biblio: apel-chant].
 // prettier-ignore
 export const GUIDONIAN_DATA = new Map([
     [43, { hand: { finger: "thumb", region: "tip" }, name: ["Γ", "Gammaut"], variants: [{ hexachord: "durum", solmization: "UT" }] }],

package/dist/engines/temper/data/modes.d.ts

@@ -9,6 +9,11 @@ export interface CadenceFigure {
     id: string;
     steps: number[];
 }
+export interface RecitingNote {
+    pc: number;
+    rank: "principal" | "auxiliary" | "secondary" | "pseudo" | "rare";
+    label?: string;
+}
 export interface ModeData {
     mode: number;
     nomen: string;
@@ -17,6 +22,7 @@ export interface ModeData {
     type: "authentic" | "plagal";
     final: number;
     tenor: number;
+    recitingNotes: RecitingNote[];
     scalePcs: number[];
     hexachords: ("durum" | "naturale" | "molle")[];
     profile: ModeProfile;

package/dist/engines/temper/data/modes.js

@@ -12,6 +12,7 @@ export const MODES = new Map([
             type: "authentic",
             final: 2,
             tenor: 9,
+            recitingNotes: [{ pc: 9, rank: "principal", label: "psalmodic tenor" }],
             scalePcs: [2, 4, 5, 7, 9, 11, 0],
             hexachords: ["naturale"],
             profile: { mood: "serious", ethos: "gravis", phrasing: "lyrical", melodic: "falling", tendency: "melismatic" },
@@ -36,6 +37,11 @@ export const MODES = new Map([
             type: "plagal",
             final: 2,
             tenor: 5,
+            recitingNotes: [
+                { pc: 5, rank: "principal", label: "official dominant, psalmodic tenor, strong degree" },
+                { pc: 2, rank: "principal", label: "final; also a principal note of composition per prose" },
+                { pc: 7, rank: "secondary", label: "important; prose also names it a note of composition" },
+            ],
             scalePcs: [2, 4, 5, 7, 9, 11, 0],
             hexachords: ["naturale"],
             profile: { mood: "sad", ethos: "tristis", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
@@ -63,6 +69,12 @@ export const MODES = new Map([
             type: "authentic",
             final: 4,
             tenor: 0,
+            // No Degree Summary Table exists for mode III (prose only, see
+            // ../../../../BIBLIOGRAPHY.md [biblio: saulnier-modes]): "the primitive
+            // psalmodic tenor is b, but in numerous medieval manuscripts from northern Europe
+            // and in the modern editions, this tenor is raised to c." tonus already
+            // stored the raised/practical value; this just cites the confirmation.
+            recitingNotes: [{ pc: 0, rank: "principal", label: "historically raised from the primitive tenor b" }],
             scalePcs: [4, 5, 7, 9, 11, 0, 2],
             hexachords: ["naturale"],
             profile: { mood: "mystic", ethos: "mysticus", phrasing: "solemn", melodic: "falling", tendency: "melismatic" },
@@ -86,6 +98,12 @@ export const MODES = new Map([
             type: "plagal",
             final: 4,
             tenor: 9,
+            recitingNotes: [
+                { pc: 9, rank: "principal", label: "psalmodic tenor" },
+                { pc: 7, rank: "secondary", label: "note of composition for Responsory verses (deuterus-tritus)" },
+                { pc: 4, rank: "secondary", label: "final; also usable as a recitation note per prose" },
+                { pc: 5, rank: "pseudo", label: "pseudo-tenor; strong importance but not a true note of composition per prose" },
+            ],
             scalePcs: [4, 5, 7, 9, 11, 0, 2],
             hexachords: ["naturale"],
             profile: { mood: "harmonious", ethos: "harmonicus", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
@@ -109,6 +127,10 @@ export const MODES = new Map([
             type: "authentic",
             final: 5,
             tenor: 0,
+            recitingNotes: [
+                { pc: 0, rank: "principal", label: "official dominant, psalmodic tenor" },
+                { pc: 5, rank: "rare", label: "final; sometimes used as a recitation note" },
+            ],
             scalePcs: [5, 7, 9, 11, 0, 2, 4],
             hexachords: ["molle"],
             profile: { mood: "happy", ethos: "laetus", phrasing: "solemn", melodic: "rising", tendency: "melismatic" },
@@ -132,6 +154,11 @@ export const MODES = new Map([
             type: "plagal",
             final: 5,
             tenor: 9,
+            // Prose: "Mode VI possesses only one note of composition: f, the final
+            // of the pieces. For the psalmody, it resorts to a, even if it has been
+            // infrequently heard in the piece." So the reciting note is real but
+            // structurally secondary — hence "auxiliary," not "principal."
+            recitingNotes: [{ pc: 9, rank: "auxiliary", label: "psalmodic tenor; the mode's only note of composition is the final f, itself not used for recitation" }],
             scalePcs: [5, 7, 9, 11, 0, 2, 4],
             hexachords: ["molle"],
             profile: { mood: "devout", ethos: "devotus", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
@@ -155,6 +182,11 @@ export const MODES = new Map([
             type: "authentic",
             final: 7,
             tenor: 2,
+            recitingNotes: [
+                { pc: 2, rank: "principal", label: "psalmodic tenor" },
+                { pc: 0, rank: "auxiliary", label: "strong degree" },
+                { pc: 11, rank: "auxiliary" },
+            ],
             scalePcs: [7, 9, 11, 0, 2, 4, 5],
             hexachords: ["durum"],
             profile: { mood: "angelical", ethos: "angelicus", phrasing: "solemn", melodic: "rising", tendency: "melismatic" },
@@ -179,6 +211,16 @@ export const MODES = new Map([
             type: "plagal",
             final: 7,
             tenor: 0,
+            // Prose: "Mode VIII has two upper notes of recitation: c (psalmodic
+            // tenor) and b. The lower note of recitation, g, is also the final of
+            // the pieces. B and g are the notes of recitation for the verses of the
+            // Responsories." — the final doubling as a low reciting note is a real,
+            // distinct case (see also mode V's f).
+            recitingNotes: [
+                { pc: 0, rank: "principal", label: "psalmodic tenor" },
+                { pc: 11, rank: "auxiliary" },
+                { pc: 7, rank: "secondary", label: "final; the mode's lower recitation note, used for Responsory verses alongside b" },
+            ],
             scalePcs: [7, 9, 11, 0, 2, 4, 5],
             hexachords: ["durum"],
             profile: { mood: "perfect", ethos: "perfectus", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },

package/dist/engines/temper/data/tones.d.ts

@@ -4,7 +4,7 @@ export interface Differentia {
 }
 export interface PsalmTone {
     mode: number;
-    name: string;
+    nomen: string;
     tenor: number;
     intonation: number[];
     flex: number[];

package/dist/engines/temper/data/tones.js

@@ -1,4 +1,6 @@
-// temper/data/tones — psalm tones (Graduale Romanum appendix)
+// ---------------------------------------------------------------------------
+// engines/temper/data/tones — psalm tones (Graduale Romanum appendix)
+// ---------------------------------------------------------------------------
 // Pitches as MIDI numbers; tone codes follow DO convention: "1g", "6F", "4e".
 // c4 clef reference: f=53 g=55 h=57 i=59 j=60 k=62 l=64 (F3–F4)
 const f = 53, g = 55, h = 57, i = 59, j = 60, k = 62, l = 64;
@@ -6,7 +8,7 @@ const d3 = 50, e3 = 52; // below c4 clef range, needed for Tone II
 export const TONES = [
     {
         mode: 1,
-        name: "Tonus I",
+        nomen: "Tonus I",
         tenor: h, // A3
         intonation: [f, h, j], // F-A-C
         flex: [h, g], // A-G
@@ -22,7 +24,7 @@ export const TONES = [
     },
     {
         mode: 2,
-        name: "Tonus II",
+        nomen: "Tonus II",
         tenor: f, // F3
         intonation: [d3, f], // D3-F3
         flex: [f, e3], // F-E
@@ -37,7 +39,7 @@ export const TONES = [
     },
     {
         mode: 3,
-        name: "Tonus III",
+        nomen: "Tonus III",
         tenor: i, // B3
         intonation: [g, i, j], // G-B-C
         flex: [i, h], // B-A
@@ -51,7 +53,7 @@ export const TONES = [
     },
     {
         mode: 4,
-        name: "Tonus IV",
+        nomen: "Tonus IV",
         tenor: h, // A3
         intonation: [f, g, h], // F-G-A
         flex: [h, f], // A-F
@@ -66,7 +68,7 @@ export const TONES = [
     },
     {
         mode: 5,
-        name: "Tonus V",
+        nomen: "Tonus V",
         tenor: j, // C4
         intonation: [h, j], // A-C
         flex: [j, i], // C-B
@@ -80,7 +82,7 @@ export const TONES = [
     },
     {
         mode: 6,
-        name: "Tonus VI",
+        nomen: "Tonus VI",
         tenor: f, // F3
         intonation: [d3, e3, f], // D-E-F
         flex: [f, e3], // F-E
@@ -94,7 +96,7 @@ export const TONES = [
     },
     {
         mode: 7,
-        name: "Tonus VII",
+        nomen: "Tonus VII",
         tenor: j, // C4
         intonation: [h, i, j], // A-B-C
         flex: [j, i], // C-B
@@ -109,7 +111,7 @@ export const TONES = [
     },
     {
         mode: 8,
-        name: "Tonus VIII",
+        nomen: "Tonus VIII",
         tenor: j, // C4
         intonation: [h, j], // A-C
         flex: [j, h], // C-A
@@ -125,7 +127,7 @@ export const TONES = [
     // ── Tonus Peregrinus ── irregular: two different tenors
     {
         mode: 0,
-        name: "Tonus Peregrinus",
+        nomen: "Tonus Peregrinus",
         tenor: j, // C4 (first half tenor)
         intonation: [h, i, j], // A-B-C
         flex: [j, i],
@@ -138,7 +140,14 @@ export const TONES = [
 ];
 /** Look up a PsalmTone by mode number (1–8, or 0 for Peregrinus) */
 export function getTone(mode) {
-    return TONES.find(t => t.mode === mode) ?? TONES.find(t => t.mode === 8);
+    const tone = TONES.find(t => t.mode === mode);
+    // A bad mode throws rather than silently singing Tonus VIII: a
+    // plausible-looking wrong psalm tone is worse than no answer, and getMode
+    // (temper/modes.ts) already holds this line for the modes themselves.
+    if (!tone) {
+        throw new Error(`getTone: no psalm tone for mode ${mode} (expected 1–8, or 0 for the tonus peregrinus).`);
+    }
+    return tone;
 }
 /** Look up a differentia by code, falling back to the tone's defaultDiff */
 export function getDifferentia(tone, code) {

package/dist/engines/temper/interval.js

@@ -3,8 +3,8 @@
 // ---------------------------------------------------------------------------
 import { INTERVAL, UNISONUS } from "./data/constants.js";
 // The three-tier consonance taxonomy [biblio: schulter-harmony] (the same table
-// stated at docs/heavens.md and docs/tuning.md). Note that the perfect fourth is
-// deliberately NOT perfect here: in medieval counterpoint the P4 above the bass
+// stated at ../../../docs/api/heavens.md and ../../../docs/api/tuning.md).
+// Note that the perfect fourth is deliberately NOT perfect here: in medieval counterpoint the P4 above the bass
 // is treated as a dissonance, unlike the melodic P4. So P1/P5/P8 are perfect,
 // the thirds and sixths imperfect, and everything else — including P4 and the
 // tritone — dissonant.
@@ -35,7 +35,8 @@ export function classifyInterval(a, b) {
         semitones,
         // Nominal equal-tempered cents (100 per semitone), NOT the tuned distance —
         // the actual sounding interval depends on the temperament (see the ratio a
-        // temperamentum reports for a nota, and docs/tuning.md on nominal vs tuned).
+        // temperamentum reports for a nota, and ../../../docs/api/tuning.md on
+        // nominal vs tuned).
         cents: semitones * 100,
         consonance: classifyConsonance(entry.class),
     };

package/dist/engines/temper/modality.d.ts

@@ -3,9 +3,18 @@ export interface ModalAffinity {
     alias: string;
     score: number;
 }
+export interface ModalAffinityOpts {
+    /** The chant's opening pitch class — applies the rank-weighted initials bonus. */
+    firstNotePc?: number;
+    /** The chant's closing pitch class — applies the final-note and tessitura bonuses. */
+    lastNotePc?: number;
+    /** Mean note MIDI minus the last note's MIDI — the melody's height above its close. */
+    tessitura?: number;
+}
 /**
  * Rank a pitch-class distribution against the eight modes, best fit first.
- * `firstNotePc`, when given, applies the rank-weighted initials bonus.
+ * The optional signals sharpen the ranking: the opening note (initials bonus),
+ * the closing note (final-note bonus), and the tessitura (authentic/plagal).
  */
-export declare function computeModalAffinity(pcDistribution: Record<number, number>, firstNotePc?: number): ModalAffinity[];
+export declare function computeModalAffinity(pcDistribution: Record<number, number>, opts?: ModalAffinityOpts): ModalAffinity[];
 //# sourceMappingURL=modality.d.ts.map