tonus 0.1.2 → 0.1.4

package/BIBLIOGRAPHY.md

@@ -35,6 +35,17 @@ section of the relevant page.
   semiological approach → [docs/score.md](docs/score.md#sources)
 - **Desrocquettes, "Gregorian Musical Values"** — Solesmes rhythmic
   values → [docs/score.md](docs/score.md#sources)
+- **Niedermeyer & d'Ortigue, _Gregorian Accompaniment_ (trans. Goodrich)** —
+  the per-mode cadence figures → [docs/tuning.md](docs/tuning.md#sources)
+- **Bragers, _A Short Treatise on Gregorian Accompaniment_ (1934)** —
+  cadence figures, cross-check → [docs/tuning.md](docs/tuning.md#sources)
+- **Homan, _Cadence in Gregorian Chant_ (1961)** — analytic study of
+  cadences → [docs/score.md](docs/score.md#sources)
+- **Murray, "Accentual Cadences in Gregorian Chant" (1958)** — spondaic and
+  dactylic verbal cadences → [docs/score.md](docs/score.md#sources)
+- **Suñol, _Textbook of Gregorian Chant According to the Solesmes Method_
+  (1930)** — modes, dominants, psalmody, the Solesmes rhythm doctrine →
+  [docs/tuning.md](docs/tuning.md#sources)
 - **Apel, _Gregorian Chant_ (1958)** — analytic study of the repertoire →
   [docs/chant.md](docs/chant.md#sources)
 - **Hiley, _Western Plainchant_ (1993)** — the standard reference →

package/README.md

@@ -93,6 +93,11 @@ const harmony = tonus.harmonia(tonus.caelum({ date: feast.date }));
 // each visible planet voiced as pitch and Greek vowel, after Boethius
 ```
 
+## Roadmap
+
+SVG chant engraving, an interactive documentation site,
+and cadence detection is laid out in [ROADMAP.md](ROADMAP.md).
+
 ## Development
 
 ```sh

package/dist/data/tones.d.ts

@@ -9,6 +9,7 @@ export interface PsalmTone {
     intonation: number[];
     flex: number[];
     mediant: number[];
+    solemnMediant?: number[];
     defaultDiff: string;
     differentiae: Differentia[];
 }

package/dist/engines/chant/intone.d.ts

@@ -3,6 +3,10 @@ export interface IntoneOpts {
     mode?: number;
     differentia?: string;
     intonation?: boolean;
+    /** Sing in directum: recite straight through to the termination, no mediant. */
+    inDirectum?: boolean;
+    /** Use the tone's ornamented mediant for solemn occasions, where it has one. */
+    solemn?: boolean;
 }
 export declare function intone(text: string | PsalmVerse, opts?: IntoneOpts): string;
 //# sourceMappingURL=intone.d.ts.map

package/dist/engines/chant/intone.js

@@ -63,12 +63,16 @@ export function intone(text, opts = {}) {
     const tone = getTone(mode);
     const diff = getDifferentia(tone, opts.differentia);
     const tenorLetter = midiToGabc(tone.tenor, clef);
-    const mediantLetters = midiListToLetters(tone.mediant, clef);
+    const mediant = opts.solemn && tone.solemnMediant ? tone.solemnMediant : tone.mediant;
+    const mediantLetters = midiListToLetters(mediant, clef);
     const terminationLetters = midiListToLetters(diff.termination, clef);
     const intonationLetters = midiListToLetters(tone.intonation, clef);
-    const starIdx = rawText.indexOf(" * ");
+    // In directum ignores the verse's mediant split: the whole verse recites to
+    // the termination as one phrase (a psalm sung with no antiphon framing).
+    const starIdx = opts.inDirectum ? -1 : rawText.indexOf(" * ");
     if (starIdx === -1) {
-        const syllables = syllabifyPhrase(rawText.trim());
+        const text = opts.inDirectum ? rawText.replace(" * ", " ") : rawText;
+        const syllables = syllabifyPhrase(text.trim());
         const body = buildHalf(syllables, tenorLetter, terminationLetters);
         return CLEF + body + "(::)";
     }

package/dist/engines/chant/psalm.js

@@ -27,8 +27,8 @@ function lookupVerses(psalm, verse) {
         results = results.filter((v) => v.verse === verse);
     return results;
 }
-function verseToChant(v, mode, differentia, intonation) {
-    const gabc = intone(v, { mode, differentia, intonation });
+function verseToChant(v, mode, differentia, intonation, inDirectum, solemn) {
+    const gabc = intone(v, { mode, differentia, intonation, inDirectum, solemn });
     return {
         id: `psalm:${v.psalm}:${v.verse}`,
         incipit: v.half1.slice(0, 40),
@@ -56,7 +56,7 @@ export function getPsalm(query) {
     if (!verses.length)
         return [];
     const mode = query.mode ?? 8;
-    return verses.map((v) => verseToChant(v, mode, query.differentia, query.intonatio));
+    return verses.map((v) => verseToChant(v, mode, query.differentia, query.intonatio, query.inDirectum, query.solemn));
 }
 /**
  * A contiguous verse range of one psalm, intoned — e.g. `getPsalmRange(30, 2, 6)`

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

@@ -64,6 +64,10 @@ export interface PsalmusQuery {
     mode?: number;
     differentia?: string;
     intonatio?: boolean;
+    /** Sing in directum: straight through to the termination, no mediant. */
+    inDirectum?: boolean;
+    /** Use the ornamented solemn mediant, where the tone has one. */
+    solemn?: boolean;
 }
 export interface PsalmVerse {
     psalm: number;

package/dist/engines/imprint.d.ts

@@ -1,7 +1,9 @@
 import type { Phrase } from "./score/types.js";
 import type { Pitch } from "./temper/pitch.js";
 import type { Scale } from "./temper/scale.js";
+import { type ModalAffinity } from "./temper/modality.js";
 import type { VoicedBody } from "./harmonia/voice.js";
+export type { ModalAffinity };
 export interface Attractor {
     pc: number;
     weight: number;
@@ -12,19 +14,18 @@ export interface VowelAttractor {
     weight: number;
     pitch: Pitch;
 }
-export interface ModalAffinity {
-    mode: number;
-    alias: string;
-    score: number;
-}
 export interface Imprint {
     pcDistribution: Record<number, number>;
     attractors: Attractor[];
     vowelAttractors: VowelAttractor[];
     modalAffinity: ModalAffinity[];
 }
-/** Build an Imprint from chant phrases (unweighted pc counts). */
-export declare function computeImprint(phrases: Phrase[], scale: Scale): Imprint;
+export interface ImprintOptions {
+    /** Positions "phrase:syllable:note" of cadence resolution notes, weighted up. */
+    cadenceNotes?: Set<string>;
+}
+/** Build an Imprint from chant phrases, weighting structural notes more. */
+export declare function computeImprint(phrases: Phrase[], scale: Scale, opts?: ImprintOptions): Imprint;
 /** Build an Imprint from voiced planetary bodies (presence-weighted pc counts). */
 export declare function computeImprintFromBodies(bodies: VoicedBody[], scale: Scale): Imprint;
 //# sourceMappingURL=imprint.d.ts.map

package/dist/engines/imprint.js

@@ -1,5 +1,5 @@
 import { toPitch } from "./temper/pitch.js";
-import { MODES } from "./temper/modes.js";
+import { computeModalAffinity } from "./temper/modality.js";
 const DEFAULT_TOP = 5;
 const DEFAULT_MIDI_OCTAVE = 4;
 const VOWELS = ["a", "e", "i", "o", "u"];
@@ -22,24 +22,6 @@ function computeAttractors(pcDistribution, scale, topN = DEFAULT_TOP) {
         pitch: pitchForPc(pc, scale),
     }));
 }
-function computeModalAffinity(pcDistribution) {
-    const results = [];
-    for (let m = 1; m <= 8; m++) {
-        const data = MODES.get(m);
-        if (!data)
-            continue;
-        const structural = new Set([
-            data.final,
-            data.tenor,
-            ...data.modulations.regular,
-        ]);
-        let score = 0;
-        for (const pc of structural)
-            score += pcDistribution[pc] ?? 0;
-        results.push({ mode: m, alias: data.alias, score });
-    }
-    return results.sort((a, b) => b.score - a.score);
-}
 function computeVowelAttractors(phrases, scale) {
     const vowelPcMap = new Map();
     for (const v of VOWELS)
@@ -85,15 +67,30 @@ function computeVowelAttractors(phrases, scale) {
     }
     return results.sort((a, b) => b.weight - a.weight);
 }
-/** Build an Imprint from chant phrases (unweighted pc counts). */
-export function computeImprint(phrases, scale) {
+// A note's contribution to the pc-distribution is raised where it carries more
+// structural weight: on an ictus (the rhythmic footfall) and, above all, when it
+// is a cadence's resolution. Cadence notes are passed in — the imprint sits below
+// the score engine, so it cannot detect them itself.
+const ICTUS_WEIGHT = 1.5;
+const CADENCE_WEIGHT = 2;
+/** Build an Imprint from chant phrases, weighting structural notes more. */
+export function computeImprint(phrases, scale, opts = {}) {
+    const cadenceNotes = opts.cadenceNotes;
     const pcCounts = new Array(12).fill(0);
     let total = 0;
-    for (const phrase of phrases) {
-        for (const syl of phrase.syllables) {
-            for (const note of syl.notes) {
-                pcCounts[note.pitch.pc]++;
-                total++;
+    for (let pi = 0; pi < phrases.length; pi++) {
+        const phrase = phrases[pi];
+        for (let si = 0; si < phrase.syllables.length; si++) {
+            const notes = phrase.syllables[si].notes;
+            for (let ni = 0; ni < notes.length; ni++) {
+                const note = notes[ni];
+                let w = 1;
+                if (note.context.ictus)
+                    w *= ICTUS_WEIGHT;
+                if (cadenceNotes?.has(`${pi}:${si}:${ni}`))
+                    w *= CADENCE_WEIGHT;
+                pcCounts[note.pitch.pc] += w;
+                total += w;
             }
         }
     }
@@ -101,11 +98,12 @@ export function computeImprint(phrases, scale) {
     for (let pc = 0; pc < 12; pc++) {
         pcDistribution[pc] = total > 0 ? pcCounts[pc] / total : 0;
     }
+    const firstNotePc = phrases[0]?.syllables[0]?.notes[0]?.pitch.pc;
     return {
         pcDistribution,
         attractors: computeAttractors(pcDistribution, scale),
         vowelAttractors: computeVowelAttractors(phrases, scale),
-        modalAffinity: computeModalAffinity(pcDistribution),
+        modalAffinity: computeModalAffinity(pcDistribution, firstNotePc),
     };
 }
 /** Build an Imprint from voiced planetary bodies (presence-weighted pc counts). */

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

@@ -1,5 +1,7 @@
 import { type Imprint } from "../imprint.js";
 import { type Prosody } from "./prosody.js";
+import { type Cadence } from "./cadence.js";
+import { type Modulation } from "./modulation.js";
 import { type ChantTabulaRow } from "./tabula.js";
 import { type MidiOpts, type MidiEmitResult } from "./emitters/midi.js";
 import { type MusicXmlOpts, type MusicXmlEmitResult } from "./emitters/musicxml.js";
@@ -29,6 +31,10 @@ export interface Score {
     errors: ParseError[];
     tabula: ChantTabulaRow[];
     prosody: Prosody;
+    /** Mode-specific cadence at each phrase-ending divisio. */
+    cadences: Cadence[];
+    /** Passages where the tonal centre leans away from the home mode. */
+    modulations: Modulation[];
     imprint: Imprint;
     /**
      * Emit a Standard MIDI File from the score's tabula. Returns the file bytes
@@ -49,6 +55,8 @@ export interface Score {
  */
 export declare function buildScore(chant: Chant, opts?: ScoreOpts): Score;
 export type { ParseError };
+export type { Cadence, CadenceTarget, CadenceApproach } from "./cadence.js";
+export type { Modulation } from "./modulation.js";
 export type { MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent } from "./emitters/midi.js";
 export type { MusicXmlOpts, MusicXmlEmitResult } from "./emitters/musicxml.js";
 //# sourceMappingURL=api.d.ts.map

package/dist/engines/score/api.js

@@ -7,7 +7,10 @@ import { buildRatios } from "../temper/scale.js";
 import { computeMeta } from "./meta.js";
 import { computeImprint } from "../imprint.js";
 import { computeProsody } from "./prosody.js";
+import { detectCadences } from "./cadence.js";
+import { detectModulations } from "./modulation.js";
 import { computeTabula } from "./tabula.js";
+import { MODES } from "../temper/modes.js";
 import { toMidi } from "./emitters/midi.js";
 import { toMusicXML } from "./emitters/musicxml.js";
 const PONDUS_TO_ARTICULATION = {
@@ -56,10 +59,16 @@ export function buildScore(chant, opts) {
     });
     const ir = buildIR(parsed, chant, scale);
     const meta = computeMeta(ir, { mode: modeNum });
+    // Cadence detection runs here, where the resolved mode (and its cadence
+    // figures) is in hand. Pure data — mirrors the arsis/thesis pass in ir.ts.
+    const cadences = detectCadences(ir.phrases, meta.mode != null ? MODES.get(meta.mode) : undefined);
+    // Modulation: where the tonal centre leans away from the home mode.
+    const modulations = detectModulations(ir.phrases, meta.mode ?? undefined);
     const tabula = computeTabula(ir, {
         mode: meta.mode ?? undefined,
         a4Hz: opts?.temperamentum?.a4,
         transpose: opts?.temperamentum?.transpose,
+        cadences,
         // Only pass phrasing when the caller asked for it, so the default
         // tabula shaping (mode-gated) is unchanged.
         interpretation: opts?.accentus
@@ -75,7 +84,15 @@ export function buildScore(chant, opts) {
         errors: ir.errors,
         tabula,
         prosody: computeProsody(ir.phrases),
-        imprint: computeImprint(ir.phrases, scale),
+        cadences,
+        modulations,
+        imprint: computeImprint(ir.phrases, scale, {
+            // Each cadence's resolution note (its last) is the strongest modal anchor.
+            cadenceNotes: new Set(cadences.map((c) => {
+                const [pi, si, ni] = c.notes[c.notes.length - 1];
+                return `${pi}:${si}:${ni}`;
+            })),
+        }),
         midi(emitOpts) {
             return toMidi(tabula, emitOpts);
         },

package/dist/engines/score/articulation.js

@@ -23,6 +23,9 @@ const BASE_WEIGHTS = {
     repercussionPrevWeight: 0.5,
     repercussionPrevDuration: 0.4,
     repercussionOriscusWeight: -0.5,
+    oriscusWeight: -0.3, // soft, light note
+    oriscusDuration: -0.15, // taken slightly faster (accelerando)
+    oriscusPrevWeight: 0.3, // rhythmic support on the preceding note
     breakWeight: 0.6,
     dashWeight: -0.8,
     dashDuration: -0.2,

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

@@ -0,0 +1,38 @@
+import type { Phrase } from "./types.js";
+import type { ModeData } from "../temper/data/modes.js";
+export type CadenceTarget = "finalis" | "tenor" | "other";
+export type CadenceApproach = "descending" | "ascending" | "unison";
+export interface Cadence {
+    /** Index of the phrase this cadence closes. */
+    phraseIndex: number;
+    /** The divisio bar that ends the phrase: "," "`" ";" ":" "::". */
+    divisio: string;
+    /**
+     * Where the phrase came to rest, from the final note's modal role. Medial
+     * cadences often rest on the tenor or elsewhere
+     */
+    target: CadenceTarget;
+    /** Melodic contour into the resolution, across the observed window. */
+    approach: CadenceApproach;
+    /** Matched finalis-cadence figure id (e.g. "mi-re"), or null. */
+    formula: string | null;
+    /** The observed final pitch-class run — the evidence, resolution note last. */
+    pcs: number[];
+    /**
+     * The window as diatonic steps relative to the resolution target (0 = target,
+     * -1 = the note below), resolution last — the surface the catalog matches on.
+     * Empty when there is no mode/target; null entries are notes off the scale.
+     */
+    steps: Array<number | null>;
+    /** 0–1: how cleanly the ending lands, raised by a catalog match. */
+    confidence: number;
+    /** Note positions forming this cadence: [phraseIndex, syllableIndex, noteIndex]. */
+    notes: Array<[number, number, number]>;
+}
+/**
+ * Detect the cadence closing each phrase. One Cadence per phrase that carries a
+ * divisio. With no mode, targets/approach are still classified but no figure is
+ * named (formula: null), matching the score's graceful-degradation convention.
+ */
+export declare function detectCadences(phrases: Phrase[], modeData: ModeData | undefined): Cadence[];
+//# sourceMappingURL=cadence.d.ts.map

package/dist/engines/score/cadence.js

@@ -0,0 +1,179 @@
+// Cadence formulae run four to ten notes (Homan, Cadence in Gregorian Chant,
+// 1961, p. xiii). Take a window at the upper end so the longest figures fit,
+// with room for the approach; tail-matching ignores the extra leading notes.
+const WINDOW = 8;
+/** Last up-to-WINDOW notes of a phrase, resolution note last. */
+function phraseFinalWindow(phrase) {
+    const window = [];
+    outer: for (let si = phrase.syllables.length - 1; si >= 0; si--) {
+        const notes = phrase.syllables[si].notes;
+        for (let ni = notes.length - 1; ni >= 0; ni--) {
+            const note = notes[ni];
+            window.push({
+                pc: note.step.pc,
+                midi: note.pitch.midi,
+                role: note.step.role,
+                syllableIndex: si,
+                noteIndex: ni,
+            });
+            if (window.length >= WINDOW)
+                break outer;
+        }
+    }
+    window.reverse();
+    return window;
+}
+function classifyTarget(final) {
+    if (!final)
+        return "other";
+    if (final.role === "finalis")
+        return "finalis";
+    if (final.role === "tenor")
+        return "tenor";
+    return "other";
+}
+function classifyApproach(window) {
+    if (window.length < 2)
+        return "unison";
+    const slope = window[window.length - 1].midi - window[0].midi;
+    if (slope < 0)
+        return "descending";
+    if (slope > 0)
+        return "ascending";
+    return "unison";
+}
+/**
+ * Signed diatonic step of pitch class `pc` relative to target pc `on`, within
+ * the mode's 7-note scale: 0 = the target, +1 = one scale step above, -1 = the
+ * note below, wrapping by octave so it stays in a small signed range. Returns
+ * null for a pc outside the mode's scale (e.g. a chromatic inflection).
+ */
+function diatonicStep(pc, on, scalePcs) {
+    const iPc = scalePcs.indexOf(((pc % 12) + 12) % 12);
+    const iOn = scalePcs.indexOf(((on % 12) + 12) % 12);
+    if (iPc === -1 || iOn === -1)
+        return null;
+    const n = scalePcs.length;
+    let d = iPc - iOn;
+    // Fold to the nearest octave so a cadence's small leaps read as small steps.
+    while (d > n / 2)
+        d -= n;
+    while (d < -n / 2)
+        d += n;
+    return d;
+}
+/**
+ * Collapse consecutive equal steps to one. A chant that lands on the final and
+ * repeats it (a final distropha, say) should still match the plain figure the
+ * treatises write with one note per pitch. Figures have no adjacent repeats, so
+ * collapsing is a no-op on them.
+ */
+function collapseRepeats(steps) {
+    const out = [];
+    for (const s of steps) {
+        if (out.length === 0 || out[out.length - 1] !== s)
+            out.push(s);
+    }
+    return out;
+}
+/**
+ * Match a collapsed step-run against a catalog figure. Both end on the
+ * resolution (0), so compare from the tail backward. Returns a fraction in
+ * 0..1: how much of the figure the ending realises (0 = no tail match).
+ */
+function figureMatch(observed, figure) {
+    if (figure.length === 0 || observed.length === 0)
+        return 0;
+    let matched = 0;
+    for (let k = 1; k <= figure.length && k <= observed.length; k++) {
+        if (observed[observed.length - k] === figure[figure.length - k])
+            matched++;
+        else
+            break;
+    }
+    return matched / figure.length;
+}
+/**
+ * The best catalog figure for an ending. A figure the ending realises in full
+ * (frac === 1) is preferred, and among those the longest — the most specific
+ * description — wins, so e.g. sol-fa-mi beats its own fa-mi suffix. Failing a
+ * full match, the highest partial fraction is kept (a weaker signal).
+ */
+function bestFigure(observed, figures) {
+    const collapsed = collapseRepeats(observed);
+    let best = null;
+    for (const figure of figures) {
+        const frac = figureMatch(collapsed, figure.steps);
+        if (frac === 0)
+            continue;
+        if (!best) {
+            best = { figure, frac };
+            continue;
+        }
+        // Rank: a full match outranks any partial; among full matches the longer
+        // figure wins; otherwise the higher fraction.
+        const bestFull = best.frac === 1;
+        const thisFull = frac === 1;
+        if (thisFull && !bestFull)
+            best = { figure, frac };
+        else if (thisFull &&
+            bestFull &&
+            figure.steps.length > best.figure.steps.length)
+            best = { figure, frac };
+        else if (!thisFull && !bestFull && frac > best.frac)
+            best = { figure, frac };
+    }
+    return best;
+}
+/**
+ * Detect the cadence closing each phrase. One Cadence per phrase that carries a
+ * divisio. With no mode, targets/approach are still classified but no figure is
+ * named (formula: null), matching the score's graceful-degradation convention.
+ */
+export function detectCadences(phrases, modeData) {
+    const cadences = [];
+    for (let pi = 0; pi < phrases.length; pi++) {
+        const phrase = phrases[pi];
+        if (!phrase.divisio)
+            continue;
+        const window = phraseFinalWindow(phrase);
+        if (window.length === 0)
+            continue;
+        const divisio = phrase.divisio.divisio;
+        const finalNote = window[window.length - 1];
+        const target = classifyTarget(finalNote);
+        const approach = classifyApproach(window);
+        const pcs = window.map((w) => w.pc);
+        // A clean landing on finalis/tenor is confident on its own; a catalog match
+        // raises it further. No modal role → a weak baseline.
+        let confidence = target === "other" ? 0.3 : 0.6;
+        let formula = null;
+        let steps = [];
+        if (modeData && (target === "finalis" || target === "tenor")) {
+            // Express the window as diatonic steps relative to the note it resolved
+            // onto. The catalogue holds final cadences, so only match on the finalis.
+            const onPc = target === "finalis" ? modeData.final : modeData.tenor;
+            steps = window.map((w) => diatonicStep(w.pc, onPc, modeData.scalePcs));
+            if (target === "finalis") {
+                const match = bestFigure(steps, modeData.cadences);
+                if (match) {
+                    formula = match.figure.id;
+                    confidence = Math.min(1, confidence + 0.4 * match.frac);
+                }
+            }
+        }
+        cadences.push({
+            phraseIndex: pi,
+            divisio,
+            target,
+            approach,
+            formula,
+            pcs,
+            steps,
+            confidence: Math.round(confidence * 100) / 100,
+            notes: window.map((w) => [pi, w.syllableIndex, w.noteIndex]),
+        });
+    }
+    return cadences;
+}
+//# sourceMappingURL=cadence.js.map

package/dist/engines/score/ir.js

@@ -23,13 +23,22 @@ function rawToNote(raw, scale) {
             quilisma: raw.quilisma,
             liquescent: raw.liquescent,
             strophicus: raw.strophicus,
+            oriscus: raw.oriscus,
             doubleEpisema: raw.doubleEpisema,
             weight: raw.weight,
         },
     };
 }
+// The salicus ictus note (its second-to-last ascending note) is prolonged —
+// Suñol, Textbook Ch. V. Modest, in the spirit of an episema lengthening.
+const SALICUS_PROLONGATION = 1.3;
 function makeSyllable(lyric, notes) {
-    return { lyric, notes, neume: classifyNeume(notes) };
+    const neume = classifyNeume(notes);
+    if (neume.type === "salicus" && notes.length >= 2) {
+        const ictic = notes[notes.length - 2];
+        ictic.performance.duration *= SALICUS_PROLONGATION;
+    }
+    return { lyric, notes, neume };
 }
 function partitionByIctus(annotated) {
     const groups = [];

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

@@ -0,0 +1,20 @@
+import type { Phrase } from "./types.js";
+export interface Modulation {
+    /** Phrase index where the modulation begins (inclusive). */
+    startPhrase: number;
+    /** Phrase index where it ends (inclusive). */
+    endPhrase: number;
+    /** The mode the passage leans toward (1–8). */
+    toMode: number;
+    /** 0–1: how strongly the foreign mode outscored the home mode, averaged. */
+    confidence: number;
+}
+/**
+ * Detect tonal-centre shifts. For each phrase, score it against every mode; a
+ * phrase whose top mode is not the home mode, and beats the home mode by MARGIN,
+ * "leans" toward that foreign mode. Consecutive phrases leaning to the same mode
+ * merge into one modulation span. `homeMode` is the chant's own mode (1–8); with
+ * no mode, nothing is detected.
+ */
+export declare function detectModulations(phrases: Phrase[], homeMode: number | undefined): Modulation[];
+//# sourceMappingURL=modulation.d.ts.map

package/dist/engines/score/modulation.js

@@ -0,0 +1,74 @@
+import { computeModalAffinity } from "../temper/modality.js";
+// How much a foreign mode must outscore the home mode (in normalised affinity)
+// before a phrase counts as leaning away. Calibrated against Suñol's worked
+// examples: at 0.25 the modulations he names in Christus resurgens (to mode 3)
+// register, while incidental modal colouring below that does not.
+const MARGIN = 0.25;
+/** The pitch-class distribution of one phrase's notes (fractions summing to 1). */
+function phrasePcDistribution(phrase) {
+    const counts = new Array(12).fill(0);
+    let total = 0;
+    for (const syl of phrase.syllables) {
+        for (const note of syl.notes) {
+            counts[note.pitch.pc]++;
+            total++;
+        }
+    }
+    const dist = {};
+    for (let pc = 0; pc < 12; pc++)
+        dist[pc] = total > 0 ? counts[pc] / total : 0;
+    return dist;
+}
+/**
+ * Detect tonal-centre shifts. For each phrase, score it against every mode; a
+ * phrase whose top mode is not the home mode, and beats the home mode by MARGIN,
+ * "leans" toward that foreign mode. Consecutive phrases leaning to the same mode
+ * merge into one modulation span. `homeMode` is the chant's own mode (1–8); with
+ * no mode, nothing is detected.
+ */
+export function detectModulations(phrases, homeMode) {
+    if (homeMode == null)
+        return [];
+    // Per-phrase lean: the foreign mode a phrase favours, with its margin over
+    // the home mode — or null if the phrase stays home.
+    const leans = phrases.map((phrase) => {
+        if (phrase.syllables.every((s) => s.notes.length === 0))
+            return null;
+        const affinity = computeModalAffinity(phrasePcDistribution(phrase));
+        const top = affinity[0];
+        if (!top || top.mode === homeMode)
+            return null;
+        const home = affinity.find((a) => a.mode === homeMode);
+        const margin = top.score - (home?.score ?? 0);
+        return margin >= MARGIN ? { mode: top.mode, margin } : null;
+    });
+    // Merge consecutive phrases leaning to the same foreign mode into spans.
+    const modulations = [];
+    let run = null;
+    const flush = () => {
+        if (!run)
+            return;
+        const avg = run.margins.reduce((s, m) => s + m, 0) / run.margins.length;
+        modulations.push({
+            startPhrase: run.start,
+            endPhrase: run.start + run.margins.length - 1,
+            toMode: run.mode,
+            confidence: Math.min(1, Math.round(avg * 100) / 100),
+        });
+        run = null;
+    };
+    for (let i = 0; i < leans.length; i++) {
+        const lean = leans[i];
+        if (lean && run && lean.mode === run.mode) {
+            run.margins.push(lean.margin);
+        }
+        else {
+            flush();
+            if (lean)
+                run = { mode: lean.mode, start: i, margins: [lean.margin] };
+        }
+    }
+    flush();
+    return modulations;
+}
+//# sourceMappingURL=modulation.js.map

package/dist/engines/score/neume.js

@@ -14,11 +14,13 @@ export function classifyNeume(notes) {
     for (let i = 1; i < notes.length; i++) {
         intervals.push(notes[i].pitch.midi - notes[i - 1].pitch.midi);
     }
-    let type = classifyShape(intervals.map(toDirection));
-    // Salicus: three ascending notes with ictus on the middle note (distinguishes
-    // from scandicus, which has no middle ictus). GABC marks it with `'` on the
-    // middle note.
-    if (type === "scandicus" && notes.length === 3 && notes[1].context.ictus) {
+    const dirs = intervals.map(toDirection);
+    let type = classifyShape(dirs);
+    // Salicus: an ascending run whose ictus (GABC `'`) marks it apart from a plain
+    // scandicus. The ictus sits on the second-to-last ascending note — the middle
+    // note of a three-note salicus, the penultimate of a longer one (Suñol).
+    const allAscending = dirs.length >= 2 && dirs.every((d) => d === "up");
+    if (allAscending && notes[notes.length - 2].context.ictus) {
         type = "salicus";
     }
     return { type, intervals, hasQuilisma, hasLiquescent, hasStrophicus };

package/dist/engines/score/parse.js

@@ -83,6 +83,7 @@ function parseNeume(notation, context) {
         let isQuilisma = false;
         let isLiquescent = false;
         let isStrophicus = false;
+        let isOriscus = false;
         let isDoubleEpisema = false;
         // Dash prefix (weak note)
         if (token[0] === "-") {
@@ -200,6 +201,16 @@ function parseNeume(notation, context) {
             w += weights.uppercaseWeight;
             durWeight += weights.uppercaseDuration;
         }
+        // Oriscus (o = soft, light note taken slightly faster; the rhythmic
+        // support falls on the note before it). Suñol, Textbook Ch. V.
+        if (modifiers.includes("o")) {
+            w += weights.oriscusWeight;
+            durWeight += weights.oriscusDuration;
+            isOriscus = true;
+            const before = intermed.length > 0 ? intermed[intermed.length - 1] : null;
+            if (before)
+                before._weight += weights.oriscusPrevWeight;
+        }
         // Repercussion (same pitch as previous note)
         const prev = intermed.length > 0 ? intermed[intermed.length - 1] : null;
         if (prev && step === prev.step) {
@@ -221,6 +232,7 @@ function parseNeume(notation, context) {
             quilisma: isQuilisma,
             liquescent: isLiquescent,
             strophicus: isStrophicus,
+            oriscus: isOriscus,
             doubleEpisema: isDoubleEpisema,
             _weight: w,
             _durWeight: durWeight,
@@ -275,6 +287,7 @@ function parseNeume(notation, context) {
             quilisma: note.quilisma,
             liquescent: note.liquescent,
             strophicus: note.strophicus,
+            oriscus: note.oriscus,
             doubleEpisema: note.doubleEpisema,
         };
     });

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

@@ -1,4 +1,5 @@
 import type { Score, Neume } from "./types.js";
+import type { Cadence } from "./cadence.js";
 import type { ChantType, InterpretationOptions } from "./types.js";
 export type NoteRole = "finalis" | "tenor" | "other" | null;
 export interface ChantTabulaRow {
@@ -40,7 +41,10 @@ export interface ChantTabulaRow {
     quilisma: boolean;
     liquescent: boolean;
     strophicus: boolean;
+    oriscus: boolean;
     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 */
     role: NoteRole;
     /** Guidonian short name (e.g. "g", "aa") — null for chromatic pitches with no gamut entry */
@@ -65,6 +69,8 @@ export interface TabulaOptions {
     interpretation?: InterpretationOptions;
     a4Hz?: number;
     transpose?: number;
+    /** Detected cadences; used to stamp each row's cadenceRef. */
+    cadences?: Cadence[];
 }
 export declare function computeTabula(ir: Score, options?: TabulaOptions): ChantTabulaRow[];
 //# sourceMappingURL=tabula.d.ts.map

package/dist/engines/score/tabula.js

@@ -54,6 +54,15 @@ export function computeTabula(ir, options = {}) {
             shapedDurations[i] = shaped[i].shapedDuration;
         }
     }
+    // Map each cadence's constituent notes back to its index, keyed by position.
+    const cadenceRefByPos = new Map();
+    if (options.cadences) {
+        for (let ci = 0; ci < options.cadences.length; ci++) {
+            for (const [pi, si, ni] of options.cadences[ci].notes) {
+                cadenceRefByPos.set(`${pi}:${si}:${ni}`, ci);
+            }
+        }
+    }
     // Position of each note within its neume figure — resets when the
     // (syllableIndex, neumeGroup) pair changes.
     const neumeIndices = [];
@@ -94,7 +103,9 @@ export function computeTabula(ir, options = {}) {
             quilisma: n.context.quilisma,
             liquescent: n.context.liquescent,
             strophicus: n.context.strophicus,
+            oriscus: n.context.oriscus,
             divisio: a.divisio,
+            cadenceRef: cadenceRefByPos.get(`${a.phraseIndex}:${a.syllableIndex}:${a.noteIndex}`) ?? null,
             role: n.step.role,
             name: n.step.name,
             nomen: n.step.nomen,

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

@@ -20,6 +20,7 @@ export interface Context {
     quilisma: boolean;
     liquescent: boolean;
     strophicus: boolean;
+    oriscus: boolean;
     doubleEpisema: boolean;
     weight: number;
 }
@@ -55,6 +56,9 @@ export interface ArticulationWeights {
     repercussionPrevWeight: number;
     repercussionPrevDuration: number;
     repercussionOriscusWeight: number;
+    oriscusWeight: number;
+    oriscusDuration: number;
+    oriscusPrevWeight: number;
     breakWeight: number;
     dashWeight: number;
     dashDuration: number;
@@ -118,6 +122,7 @@ export interface ParsedNote {
     quilisma: boolean;
     liquescent: boolean;
     strophicus: boolean;
+    oriscus: boolean;
     doubleEpisema: boolean;
 }
 export interface RestEvent {

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

@@ -4,7 +4,7 @@ import type { Step, StepVariant, Finger, Region } from "./step.js";
 import type { Interval, IntervalDirection, IntervalQuality } from "./interval.js";
 import type { Neume, NeumeShape } from "./neume.js";
 import type { GamutOptions } from "./gamut.js";
-import type { ModeData, ModeProfile } from "./modes.js";
+import type { ModeData, ModeProfile, CadenceFigure } from "./modes.js";
 import type { GuidonianEntry, GuidonianVariant } from "./guido.js";
 export type BuiltinTuning = "pythagorean" | "meantone" | "equal" | "ptolemy-intense" | "ptolemy-soft" | "ptolemy-equable";
 export type Tuning = BuiltinTuning | string;
@@ -28,6 +28,22 @@ export interface Tonus {
     mediatio: Pitch[];
     terminatio: Pitch[];
 }
+/** A pitch resolved through the tuning, with its Guidonian annotation. */
+export interface TunedNote {
+    pitch: Pitch;
+    step: Step;
+}
+/**
+ * A mode's reference data (ModeData), enriched with its structural pitches
+ * tuned through the temperamentum that returned it. `modus()`. Cadence figures
+ * stay in their diatonic-step form on `cadences` — they are transposition-
+ * relative by design.
+ */
+export interface Modus extends ModeData {
+    finalis: TunedNote;
+    reciting: TunedNote;
+    ambitusNotes: TunedNote[];
+}
 export interface Temperamentum {
     tuning: Tuning;
     mode: number | "auto";
@@ -45,7 +61,7 @@ export interface Temperamentum {
         step: Step | null;
     };
     gamut(opts?: GamutOptions): Pitch[];
-    modus(mode: number): ModeData;
+    modus(mode: number): Modus;
     tonus(opts?: TonusOpts): Tonus;
 }
 /**
@@ -56,5 +72,5 @@ export interface Temperamentum {
  * @throws Error on invalid tuning, scale, or mode input.
  */
 export declare function buildTemper(input?: TemperamentumInput): Temperamentum;
-export type { Scale, ScaleOpts, ScalaFile, RatioResult, Pitch, PitchInput, Step, StepVariant, Finger, Region, Neume, NeumeShape, Interval, IntervalDirection, IntervalQuality, ModeData, ModeProfile, GamutOptions, GuidonianEntry, GuidonianVariant, };
+export type { Scale, ScaleOpts, ScalaFile, RatioResult, Pitch, PitchInput, Step, StepVariant, Finger, Region, Neume, NeumeShape, Interval, IntervalDirection, IntervalQuality, ModeData, ModeProfile, CadenceFigure, GamutOptions, GuidonianEntry, GuidonianVariant, };
 //# sourceMappingURL=api.d.ts.map

package/dist/engines/temper/api.js

@@ -110,7 +110,25 @@ export function buildTemper(input) {
             return buildGamut(scala, gamutOpts);
         },
         modus(mode) {
-            return getMode(mode);
+            const data = getMode(mode);
+            // The mode's degrees are stored as semitone offsets from C (pc 0), with
+            // values past 12 in the upper octave. Anchor them at C4 (MIDI 60).
+            const tuned = (offset) => ({
+                pitch: toPitch(60 + offset, scala),
+                step: toStep(60 + offset, scala),
+            });
+            const scaleSet = new Set(data.scalePcs);
+            const ambitusNotes = [];
+            for (let off = data.ambitus.lowest; off <= data.ambitus.highest; off++) {
+                if (scaleSet.has(((off % 12) + 12) % 12))
+                    ambitusNotes.push(tuned(off));
+            }
+            return {
+                ...data,
+                finalis: tuned(data.final),
+                reciting: tuned(data.tenor),
+                ambitusNotes,
+            };
         },
         tonus(tonusOpts) {
             if (modeVal === "auto")

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

@@ -1,9 +1,14 @@
 export interface ModeProfile {
     mood: string;
+    ethos: string;
     phrasing: "recitative" | "lyrical" | "hymnic" | "solemn";
     melodic: "rising" | "falling" | "arch" | "neutral";
     tendency: "melismatic" | "neumatic" | "syllabic" | "neutral";
 }
+export interface CadenceFigure {
+    id: string;
+    steps: number[];
+}
 export interface ModeData {
     mode: number;
     nomen: string;
@@ -15,10 +20,7 @@ export interface ModeData {
     scalePcs: number[];
     hexachords: ("durum" | "naturale" | "molle")[];
     profile: ModeProfile;
-    cadences: {
-        final: number[];
-        tenor: number[];
-    };
+    cadences: CadenceFigure[];
     modulations: {
         regular: number[];
         conceded: number[];

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

@@ -14,8 +14,13 @@ export const MODES = new Map([
             tenor: 9,
             scalePcs: [2, 4, 5, 7, 9, 11, 0],
             hexachords: ["naturale"],
-            profile: { mood: "serious", phrasing: "lyrical", melodic: "falling", tendency: "melismatic" },
-            cadences: { final: [5, 4, 2], tenor: [9, 2] },
+            profile: { mood: "serious", ethos: "gravis", phrasing: "lyrical", melodic: "falling", tendency: "melismatic" },
+            cadences: [
+                { id: "mi-re", steps: [1, 0] },
+                { id: "ut-re", steps: [-1, 0] },
+                { id: "sol-fa-re", steps: [3, 2, 0] },
+                { id: "mi-fa-re", steps: [1, 2, 0] },
+            ],
             modulations: { regular: [2, 9, 5, 7], conceded: [12, 4], initials: [2, 5, 7, 9, 14] },
             ambitus: { lowest: 2, highest: 21, span: 19 },
             species: { fifth: [2, 9], fourth: [9, 2] },
@@ -33,8 +38,13 @@ export const MODES = new Map([
             tenor: 5,
             scalePcs: [2, 4, 5, 7, 9, 11, 0],
             hexachords: ["naturale"],
-            profile: { mood: "sad", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
-            cadences: { final: [8, 7, 5], tenor: [0, 5] },
+            profile: { mood: "sad", ethos: "tristis", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
+            cadences: [
+                { id: "mi-re", steps: [1, 0] },
+                { id: "ut-re", steps: [-1, 0] },
+                { id: "sol-fa-re", steps: [3, 2, 0] },
+                { id: "mi-fa-re", steps: [1, 2, 0] },
+            ],
             modulations: { regular: [2, 5, 7, 9], conceded: [0, 4], initials: [0, 2, 4, 5, 7, 9] },
             ambitus: { lowest: 0, highest: 17, span: 17 },
             species: { fifth: [2, 9], fourth: [9, 2] },
@@ -52,8 +62,12 @@ export const MODES = new Map([
             tenor: 0,
             scalePcs: [4, 5, 7, 9, 11, 0, 2],
             hexachords: ["naturale"],
-            profile: { mood: "mystic", phrasing: "solemn", melodic: "falling", tendency: "melismatic" },
-            cadences: { final: [7, 6, 4], tenor: [0, 4] },
+            profile: { mood: "mystic", ethos: "mysticus", phrasing: "solemn", melodic: "falling", tendency: "melismatic" },
+            cadences: [
+                { id: "fa-mi", steps: [1, 0] },
+                { id: "re-mi", steps: [-1, 0] },
+                { id: "sol-fa-mi", steps: [2, 1, 0] },
+            ],
             modulations: { regular: [4, 0, 7, 9], conceded: [5, 11], initials: [0, 2, 4, 7, 9] },
             ambitus: { lowest: 4, highest: 16, span: 12 },
             species: { fifth: [4, 11], fourth: [11, 4] },
@@ -71,8 +85,12 @@ export const MODES = new Map([
             tenor: 9,
             scalePcs: [4, 5, 7, 9, 11, 0, 2],
             hexachords: ["naturale"],
-            profile: { mood: "harmonious", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
-            cadences: { final: [7, 6, 4], tenor: [9, 4] },
+            profile: { mood: "harmonious", ethos: "harmonicus", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
+            cadences: [
+                { id: "fa-mi", steps: [1, 0] },
+                { id: "re-mi", steps: [-1, 0] },
+                { id: "sol-fa-mi", steps: [2, 1, 0] },
+            ],
             modulations: { regular: [4, 9, 7, 0], conceded: [11], initials: [0, 4, 7, 9] },
             ambitus: { lowest: 2, highest: 21, span: 19 },
             species: { fifth: [4, 11], fourth: [11, 4] },
@@ -90,8 +108,12 @@ export const MODES = new Map([
             tenor: 0,
             scalePcs: [5, 7, 9, 11, 0, 2, 4],
             hexachords: ["molle"],
-            profile: { mood: "happy", phrasing: "solemn", melodic: "rising", tendency: "melismatic" },
-            cadences: { final: [8, 7, 5], tenor: [0, 5] },
+            profile: { mood: "happy", ethos: "laetus", phrasing: "solemn", melodic: "rising", tendency: "melismatic" },
+            cadences: [
+                { id: "mi-fa", steps: [-1, 0] },
+                { id: "fa-mi-fa", steps: [0, -1, 0] },
+                { id: "la-sol-fa", steps: [2, 1, 0] },
+            ],
             modulations: { regular: [5, 0, 7, 12], conceded: [9, 2], initials: [5, 7, 9, 0, 12] },
             ambitus: { lowest: 5, highest: 17, span: 12 },
             species: { fifth: [5, 0], fourth: [0, 5] },
@@ -109,8 +131,12 @@ export const MODES = new Map([
             tenor: 9,
             scalePcs: [5, 7, 9, 11, 0, 2, 4],
             hexachords: ["molle"],
-            profile: { mood: "devout", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
-            cadences: { final: [8, 7, 5], tenor: [9, 5] },
+            profile: { mood: "devout", ethos: "devotus", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
+            cadences: [
+                { id: "mi-fa", steps: [-1, 0] },
+                { id: "fa-mi-fa", steps: [0, -1, 0] },
+                { id: "la-sol-fa", steps: [2, 1, 0] },
+            ],
             modulations: { regular: [5, 9, 0, 7], conceded: [2, 12], initials: [0, 2, 4, 5, 7, 9] },
             ambitus: { lowest: 3, highest: 21, span: 18 },
             species: { fifth: [5, 0], fourth: [0, 5] },
@@ -128,8 +154,13 @@ export const MODES = new Map([
             tenor: 2,
             scalePcs: [7, 9, 11, 0, 2, 4, 5],
             hexachords: ["durum"],
-            profile: { mood: "angelical", phrasing: "solemn", melodic: "rising", tendency: "melismatic" },
-            cadences: { final: [10, 9, 7], tenor: [2, 7] },
+            profile: { mood: "angelical", ethos: "angelicus", phrasing: "solemn", melodic: "rising", tendency: "melismatic" },
+            cadences: [
+                { id: "la-sol", steps: [1, 0] },
+                { id: "fa-sol", steps: [-1, 0] },
+                { id: "ut-sol", steps: [3, 0] },
+                { id: "ut-ti-sol", steps: [3, 2, 0] },
+            ],
             modulations: { regular: [7, 2, 9, 14], conceded: [5, 0], initials: [7, 9, 11, 2, 14] },
             ambitus: { lowest: 7, highest: 19, span: 12 },
             species: { fifth: [7, 2], fourth: [2, 7] },
@@ -147,8 +178,13 @@ export const MODES = new Map([
             tenor: 0,
             scalePcs: [7, 9, 11, 0, 2, 4, 5],
             hexachords: ["durum"],
-            profile: { mood: "perfect", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
-            cadences: { final: [10, 9, 7], tenor: [0, 7] },
+            profile: { mood: "perfect", ethos: "perfectus", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
+            cadences: [
+                { id: "la-sol", steps: [1, 0] },
+                { id: "fa-sol", steps: [-1, 0] },
+                { id: "ut-sol", steps: [3, 0] },
+                { id: "ut-ti-sol", steps: [3, 2, 0] },
+            ],
             modulations: { regular: [7, 0, 9, 14], conceded: [2, 5], initials: [0, 2, 4, 7, 9, 12, 14] },
             ambitus: { lowest: 5, highest: 19, span: 14 },
             species: { fifth: [7, 2], fourth: [2, 7] },

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

@@ -0,0 +1,11 @@
+export interface ModalAffinity {
+    mode: number;
+    alias: string;
+    score: number;
+}
+/**
+ * Rank a pitch-class distribution against the eight modes, best fit first.
+ * `firstNotePc`, when given, applies the rank-weighted initials bonus.
+ */
+export declare function computeModalAffinity(pcDistribution: Record<number, number>, firstNotePc?: number): ModalAffinity[];
+//# sourceMappingURL=modality.d.ts.map

package/dist/engines/temper/modality.js

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// engines/temper/modality — how well pitch content fits each church mode
+// ---------------------------------------------------------------------------
+// Modal theory, not tied to any one caller: the imprint uses it to fingerprint a
+// whole chant, modulation detection to read each phrase. A pure function of a
+// pitch-class distribution (and, optionally, the chant's opening note).
+import { MODES } from "./modes.js";
+// A mode's structural degrees are not equal: the finalis defines it, the tenor
+// anchors its recitation, and modulation degrees are only secondary colour. Time
+// spent on each pitch counts toward the mode in that proportion.
+const FINALIS_WEIGHT = 3;
+const TENOR_WEIGHT = 2;
+const REGULAR_MOD_WEIGHT = 1;
+const CONCEDED_MOD_WEIGHT = 0.5;
+// A chant's opening note is a modal signal: each mode lists its valid initials
+// in rank order (the first is the most characteristic). Opening on a mode's
+// primary initial boosts it more than opening on a lower-ranked one — which is
+// what separates an authentic mode from its plagal partner, since the two share
+// a finalis but rank the same opening pitch differently.
+const INITIAL_BONUS = 0.3;
+/**
+ * Rank a pitch-class distribution against the eight modes, best fit first.
+ * `firstNotePc`, when given, applies the rank-weighted initials bonus.
+ */
+export function computeModalAffinity(pcDistribution, firstNotePc) {
+    const results = [];
+    for (let m = 1; m <= 8; m++) {
+        const data = MODES.get(m);
+        if (!data)
+            continue;
+        // Weight each degree by its modal role; a pc that fills more than one role
+        // (e.g. a modulation degree that is also the tenor) takes the strongest.
+        const degreeWeight = new Map();
+        const set = (pc, w) => {
+            degreeWeight.set(pc, Math.max(degreeWeight.get(pc) ?? 0, w));
+        };
+        for (const pc of data.modulations.conceded)
+            set(pc % 12, CONCEDED_MOD_WEIGHT);
+        for (const pc of data.modulations.regular)
+            set(pc % 12, REGULAR_MOD_WEIGHT);
+        set(data.tenor, TENOR_WEIGHT);
+        set(data.final, FINALIS_WEIGHT);
+        let score = 0;
+        for (const [pc, w] of degreeWeight)
+            score += (pcDistribution[pc] ?? 0) * w;
+        // Initials bonus, scaled by how highly the mode ranks the opening pitch.
+        if (firstNotePc != null) {
+            const initials = data.modulations.initials;
+            const rank = initials.findIndex((pc) => pc % 12 === firstNotePc);
+            if (rank !== -1)
+                score += (INITIAL_BONUS * (initials.length - rank)) / initials.length;
+        }
+        results.push({ mode: m, alias: data.alias, score });
+    }
+    return results.sort((a, b) => b.score - a.score);
+}
+//# sourceMappingURL=modality.js.map

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

@@ -1,5 +1,5 @@
 import type { ModeData } from "./data/modes.js";
-export type { ModeProfile, ModeData } from "./data/modes.js";
+export type { ModeProfile, ModeData, CadenceFigure } from "./data/modes.js";
 export { MODES } from "./data/modes.js";
 /** Return ModeData for mode 1–8. Throws on unknown mode. */
 export declare function getMode(mode: number): ModeData;

package/dist/index.d.ts

@@ -10,8 +10,8 @@ import { getCosmos } from "./engines/planet/planet.js";
 import { buildHarmonia } from "./engines/harmonia/api.js";
 import type { FeastQuery, Feast, Pascha, Season, Grade } from "./engines/cal/types.js";
 import type { CantusQuery, Chant, OrdinaryChant, PropriumQuery, OrdinariumQuery, OfficiumQuery, PsalmusQuery } from "./engines/chant/types.js";
-import type { TemperamentumInput, Temperamentum, Tuning, TemperamentumOpts, Pitch, PitchInput, Step, Neume, NeumeShape, Interval, ModeData, GamutOptions, Tonus, TonusOpts } from "./engines/temper/api.js";
-import type { Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent, MusicXmlOpts, MusicXmlEmitResult } from "./engines/score/api.js";
+import type { TemperamentumInput, Temperamentum, Tuning, TemperamentumOpts, Pitch, PitchInput, Step, Neume, NeumeShape, Interval, ModeData, CadenceFigure, Modus, TunedNote, GamutOptions, Tonus, TonusOpts } from "./engines/temper/api.js";
+import type { Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, Cadence, CadenceTarget, CadenceApproach, Modulation, MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent, MusicXmlOpts, MusicXmlEmitResult } from "./engines/score/api.js";
 import type { ChantTabulaRow } from "./engines/score/tabula.js";
 import type { Imprint, Attractor, VowelAttractor, ModalAffinity } from "./engines/imprint.js";
 import type { Prosody, RhythmicProfile, NoteRange, CadenceDistribution } from "./engines/score/prosody.js";
@@ -36,5 +36,5 @@ declare const tonus: {
 };
 export default tonus;
 export { SEASON_LABELS, TEMPUS_NAMES, GRADE_ORDER, GRADE_NAMES, gradeOrder, compareGrade, ritusToGrade, } from "./engines/cal/types.js";
-export type { Feast, FeastQuery, Pascha, Season, Grade, Chant, CantusQuery, OrdinaryChant, PropriumQuery, OrdinariumQuery, OfficiumQuery, PsalmusQuery, Temperamentum, TemperamentumInput, TemperamentumOpts, Tuning, Pitch, PitchInput, Step, Neume, NeumeShape, Interval, ModeData, GamutOptions, Tonus, TonusOpts, Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent, MusicXmlOpts, MusicXmlEmitResult, ChantTabulaRow, Note, Performance, Phrase, Syllable, RestEvent, ParseError, ArsisThesis, VoicedPitch, Cosmos, CosmosQuery, Body, BodyName, Aspect, Imprint, Attractor, VowelAttractor, ModalAffinity, Prosody, RhythmicProfile, NoteRange, CadenceDistribution, Harmony, HarmoniaOpts, VoicedBody, VoicedAspect, Frame, Author, HarmonyTabulaRow, PlanetVowel, };
+export type { Feast, FeastQuery, Pascha, Season, Grade, Chant, CantusQuery, OrdinaryChant, PropriumQuery, OrdinariumQuery, OfficiumQuery, PsalmusQuery, Temperamentum, TemperamentumInput, TemperamentumOpts, Tuning, Pitch, PitchInput, Step, Neume, NeumeShape, Interval, ModeData, CadenceFigure, Modus, TunedNote, GamutOptions, Tonus, TonusOpts, Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, Cadence, CadenceTarget, CadenceApproach, Modulation, MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent, MusicXmlOpts, MusicXmlEmitResult, ChantTabulaRow, Note, Performance, Phrase, Syllable, RestEvent, ParseError, ArsisThesis, VoicedPitch, Cosmos, CosmosQuery, Body, BodyName, Aspect, Imprint, Attractor, VowelAttractor, ModalAffinity, Prosody, RhythmicProfile, NoteRange, CadenceDistribution, Harmony, HarmoniaOpts, VoicedBody, VoicedAspect, Frame, Author, HarmonyTabulaRow, PlanetVowel, };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tonus",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "description": "Medieval music analysis and performance: GABC plainchant exports, liturgical calendar, tuning systems, ephemeris, and the harmony of the spheres",