tonus 0.1.3 → 0.1.6

package/dist/engines/score/phrasing.js

@@ -62,6 +62,9 @@ export function buildPhrasing(type = "lyrical", options = {}) {
         ...(options.overrides ?? {}),
     };
 }
+// Authentic modes reach a fifth or more above the final and pull harder toward
+// their tenor/reciting note; plagal modes straddle the final and pull less
+// [biblio: sunol-textbook]. These nudge the tenor and cadence gains accordingly.
 const MODE_TYPE_TENOR_MULTIPLIER = {
     authentic: 1.08,
     plagal: 0.92,
@@ -70,12 +73,20 @@ const MODE_TYPE_CADENCE_MULTIPLIER = {
     authentic: 1.05,
     plagal: 0.95,
 };
+// A more melismatic mode leans into its cadences; a syllabic one under-plays them.
 const MODE_TENDENCY_CADENCE_MULTIPLIER = {
     melismatic: 1.06,
     neumatic: 1.0,
     syllabic: 0.96,
     neutral: 1.0,
 };
+// The modal ethos → performance mapping. Each mode carries a mood epithet (the
+// Niedermeyer & d'Ortigue tradition [biblio: niedermeyer-ortigue], stored on
+// ModeProfile in modes.ts); these translate that mood into small shaping deltas.
+// The interpretation is tonus's own — the epithets are sourced, these numbers
+// are a tuned editorial gesture, deliberately small. Note the coherence: sadder
+// moods drop the velocity floor AND deepen the phrase curve (below), so they
+// read quieter and more arched; brighter moods do the reverse.
 const MODE_MOOD_BASE_VELOCITY_DELTA = {
     neutral: 0,
     serious: -0.01,
@@ -144,9 +155,17 @@ const DURATION_ARCH_FACTOR = 0.2;
 const DURATION_MIN = 0.2;
 const DURATION_MAX = 4.0;
 const TENOR_GAIN = 0.05;
+// Tenor pull falls linearly with pitch-class distance from the reciting tone and
+// reaches zero at 6 semitones (a tritone) — the far side of the octave, past
+// which a note no longer reads as gravitating to the tenor.
 const TENOR_DISTANCE_DIVISOR = 6;
 const CADENCE_VELOCITY_FACTOR = 0.5;
 const CADENCE_DURATION_FACTOR = 0.6;
+// The phrasing-side reading of the divisio (bar-line) hierarchy. This is the same
+// bar hierarchy tabulated canonically in docs/score.md and weighted for analysis
+// by prosody.ts's cadenceWeight ladder — but here the weights differ on purpose:
+// this is a *shaping* factor, so the virgula (`) gets 0 (a breath, no cadential
+// stress), where the analytic ladder still counts it. Do not unify the three.
 const DIVISIO_STRENGTH = {
     "::": 1.0,
     ":": 0.7,
@@ -214,8 +233,15 @@ export function applyPhrasing(events, profile, tenorPc) {
             const arsis = note.context.weight;
             const arsisRelative = (arsis - minArsis) / arsisSpan;
             const contourRelative = (note.pitch.midi - minStep) / stepSpan;
+            // A raised-cosine (Hann) window over the phrase: 0 at the ends, 1 at the
+            // middle, so each phrase swells and subsides — the Solesmes grand rythme,
+            // the phrase-arch [biblio: mocquereau-nombre]. `t` is the note's fractional
+            // position through the phrase.
             const t = (order + 0.5) / (noteEntries.length + 0.0001);
             const arch = 0.5 - 0.5 * Math.cos(2 * Math.PI * t);
+            // Blend the note's intrinsic arsic weight against its positional arch;
+            // `curve` is the mix knob (0 = follow the note's own weight, 1 = follow the
+            // phrase arch). The result is then re-centred on 0.5 and spread by velSpread.
             let velocity = arsisRelative * (1 - profile.curve) + arch * profile.curve;
             velocity += (contourRelative - VELOCITY_CENTER) * profile.contourVel;
             velocity =

package/dist/engines/score/prosody.js

@@ -55,6 +55,11 @@ export function computeProsody(phrases) {
             }
         }
         if (phrase.divisio) {
+            // Analytic bar-importance weights, one rung per divisio in the bar-line
+            // hierarchy (the canonical table is in docs/score.md). These are a
+            // MEASUREMENT — every divisio counts, including the virgula (`) — distinct
+            // from phrasing.ts's DIVISIO_STRENGTH, which zeroes the virgula because it
+            // is a shaping factor, not a count.
             const d = phrase.divisio.divisio;
             if (d === "::") {
                 cadDist.doubleBar++;

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

@@ -42,6 +42,8 @@ export interface ChantTabulaRow {
     liquescent: boolean;
     strophicus: boolean;
     oriscus: boolean;
+    /** Mora vocis count: 0 none, 1 dot '.', 2 double dot '..' (a stronger cadential hold). */
+    mora: 0 | 1 | 2;
     divisio: string | null;
     /** Index into score.cadences[] when this note forms a cadence; null otherwise. */
     cadenceRef: number | null;

package/dist/engines/score/tabula.js

@@ -104,6 +104,7 @@ export function computeTabula(ir, options = {}) {
             liquescent: n.context.liquescent,
             strophicus: n.context.strophicus,
             oriscus: n.context.oriscus,
+            mora: n.context.mora,
             divisio: a.divisio,
             cadenceRef: cadenceRefByPos.get(`${a.phraseIndex}:${a.syllableIndex}:${a.noteIndex}`) ?? null,
             role: n.step.role,

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

@@ -3,6 +3,11 @@ import type { Step } from "../temper/step.js";
 import type { NeumeShape } from "../temper/neume.js";
 import type { OfficeCode, OrdinaryCode } from "../chant/types.js";
 export type ArsisThesis = "arsic" | "thetic";
+export type RhythmicType = "IV" | "V" | "VI" | "VII" | "VIII" | null;
+export interface CompoundBeat {
+    shape: ArsisThesis;
+    noteCount: number;
+}
 export interface Performance {
     velocity: number;
     duration: number;
@@ -21,7 +26,7 @@ export interface Context {
     liquescent: boolean;
     strophicus: boolean;
     oriscus: boolean;
-    doubleEpisema: boolean;
+    mora: 0 | 1 | 2;
     weight: number;
 }
 export interface Note {
@@ -123,7 +128,7 @@ export interface ParsedNote {
     liquescent: boolean;
     strophicus: boolean;
     oriscus: boolean;
-    doubleEpisema: boolean;
+    mora: 0 | 1 | 2;
 }
 export interface RestEvent {
     type: "rest";
@@ -151,6 +156,10 @@ export interface Syllable {
 export interface Phrase {
     syllables: Syllable[];
     divisio?: RestEvent;
+    /** 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 {
     chant: {

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

@@ -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;
 }
 /**

package/dist/engines/temper/api.js

@@ -8,7 +8,7 @@ import { classifyInterval } from "./interval.js";
 import { buildNeume } from "./neume.js";
 import { buildGamut } from "./gamut.js";
 import { getMode } from "./modes.js";
-import { getTone, getDifferentia } from "../../data/tones.js";
+import { getTone, getDifferentia } from "./data/tones.js";
 function resolveOpts(input) {
     if (!input)
         return {};
@@ -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/guido.d.ts

@@ -1,11 +1,12 @@
+import type { Finger, Region } from "../step.js";
 export interface GuidonianVariant {
     hexachord: "durum" | "naturale" | "molle";
     solmization: "UT" | "RE" | "MI" | "FA" | "SOL" | "LA";
 }
 export interface GuidonianEntry {
     hand: {
-        finger: string;
-        region: string;
+        finger: Finger;
+        region: Region;
     };
     name: [string, string];
     variants: GuidonianVariant[];

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

@@ -1,29 +1,34 @@
-// ---------------------------------------------------------------------------
-// engines/temper/data/guido — Guidonian gamut and hexachord variants
-// ---------------------------------------------------------------------------
+// The hand loci follow the CANONICAL Guidonian spiral, not a linear fill:
+// begin at the thumb tip, come down the thumb, cross the finger BASES
+// index→little, climb the little finger, return across the finger TIPS
+// 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.
 // prettier-ignore
 export const GUIDONIAN_DATA = new Map([
-    [43, { hand: { finger: "base", region: "palm" }, name: ["Γ", "Gammaut"], variants: [{ hexachord: "durum", solmization: "UT" }] }],
-    [45, { hand: { finger: "wrist", region: "center" }, name: ["A", "Are"], variants: [{ hexachord: "durum", solmization: "RE" }] }],
-    [47, { hand: { finger: "wrist", region: "inner" }, name: ["B", "Bemi"], variants: [{ hexachord: "durum", solmization: "MI" }] }],
-    [48, { hand: { finger: "palm", region: "base" }, name: ["C", "Cefaut"], variants: [{ hexachord: "durum", solmization: "FA" }, { hexachord: "naturale", solmization: "UT" }] }],
-    [50, { hand: { finger: "palm", region: "middle" }, name: ["D", "Desolre"], variants: [{ hexachord: "durum", solmization: "SOL" }, { hexachord: "naturale", solmization: "RE" }] }],
-    [52, { hand: { finger: "palm", region: "top" }, name: ["E", "Elami"], variants: [{ hexachord: "durum", solmization: "LA" }, { hexachord: "naturale", solmization: "MI" }] }],
-    [53, { hand: { finger: "thumb", region: "base" }, name: ["F", "Fefaut"], variants: [{ hexachord: "naturale", solmization: "FA" }, { hexachord: "molle", solmization: "UT" }] }],
-    [55, { hand: { finger: "thumb", region: "mid" }, name: ["G", "Gesolreut"], variants: [{ hexachord: "durum", solmization: "UT" }, { hexachord: "naturale", solmization: "SOL" }, { hexachord: "molle", solmization: "RE" }] }],
-    [57, { hand: { finger: "thumb", region: "tip" }, name: ["a", "Alamire"], variants: [{ hexachord: "durum", solmization: "RE" }, { hexachord: "naturale", solmization: "LA" }, { hexachord: "molle", solmization: "MI" }] }],
-    [58, { hand: { finger: "index", region: "base" }, name: ["b", "Befa"], variants: [{ hexachord: "molle", solmization: "FA" }] }],
-    [59, { hand: { finger: "index", region: "mid" }, name: ["♮", "Bemi"], variants: [{ hexachord: "durum", solmization: "MI" }] }],
-    [60, { hand: { finger: "index", region: "tip" }, name: ["c", "Cesolfaut"], variants: [{ hexachord: "durum", solmization: "FA" }, { hexachord: "naturale", solmization: "UT" }, { hexachord: "molle", solmization: "SOL" }] }],
-    [62, { hand: { finger: "middle", region: "base" }, name: ["d", "Delasolre"], variants: [{ hexachord: "durum", solmization: "SOL" }, { hexachord: "naturale", solmization: "RE" }, { hexachord: "molle", solmization: "LA" }] }],
-    [64, { hand: { finger: "middle", region: "mid" }, name: ["e", "Elami"], variants: [{ hexachord: "durum", solmization: "LA" }, { hexachord: "naturale", solmization: "MI" }] }],
-    [65, { hand: { finger: "middle", region: "tip" }, name: ["f", "Fefaut"], variants: [{ hexachord: "naturale", solmization: "FA" }, { hexachord: "molle", solmization: "UT" }] }],
-    [67, { hand: { finger: "ring", region: "base" }, name: ["g", "Gesolreut"], variants: [{ hexachord: "durum", solmization: "UT" }, { hexachord: "naturale", solmization: "SOL" }, { hexachord: "molle", solmization: "RE" }] }],
-    [69, { hand: { finger: "ring", region: "mid" }, name: ["aa", "Alamire"], variants: [{ hexachord: "durum", solmization: "RE" }, { hexachord: "naturale", solmization: "LA" }, { hexachord: "molle", solmization: "MI" }] }],
-    [70, { hand: { finger: "ring", region: "tip" }, name: ["bb", "Befa"], variants: [{ hexachord: "molle", solmization: "FA" }] }],
-    [71, { hand: { finger: "pinky", region: "base" }, name: ["♮♮", "Bemi"], variants: [{ hexachord: "durum", solmization: "MI" }] }],
-    [72, { hand: { finger: "pinky", region: "mid" }, name: ["cc", "Cesolfa"], variants: [{ hexachord: "durum", solmization: "FA" }, { hexachord: "naturale", solmization: "UT" }, { hexachord: "molle", solmization: "SOL" }] }],
-    [74, { hand: { finger: "pinky", region: "top" }, name: ["dd", "Delasol"], variants: [{ hexachord: "durum", solmization: "SOL" }, { hexachord: "naturale", solmization: "RE" }, { hexachord: "molle", solmization: "LA" }] }],
-    [76, { hand: { finger: "pinky", region: "tip" }, name: ["ee", "Ela"], variants: [{ hexachord: "durum", solmization: "LA" }, { hexachord: "naturale", solmization: "MI" }] }],
+    [43, { hand: { finger: "thumb", region: "tip" }, name: ["Γ", "Gammaut"], variants: [{ hexachord: "durum", solmization: "UT" }] }],
+    [45, { hand: { finger: "thumb", region: "mid" }, name: ["A", "Are"], variants: [{ hexachord: "durum", solmization: "RE" }] }],
+    [47, { hand: { finger: "thumb", region: "base" }, name: ["B", "Bemi"], variants: [{ hexachord: "durum", solmization: "MI" }] }],
+    [48, { hand: { finger: "index", region: "base" }, name: ["C", "Cefaut"], variants: [{ hexachord: "durum", solmization: "FA" }, { hexachord: "naturale", solmization: "UT" }] }],
+    [50, { hand: { finger: "middle", region: "base" }, name: ["D", "Desolre"], variants: [{ hexachord: "durum", solmization: "SOL" }, { hexachord: "naturale", solmization: "RE" }] }],
+    [52, { hand: { finger: "ring", region: "base" }, name: ["E", "Elami"], variants: [{ hexachord: "durum", solmization: "LA" }, { hexachord: "naturale", solmization: "MI" }] }],
+    [53, { hand: { finger: "pinky", region: "base" }, name: ["F", "Fefaut"], variants: [{ hexachord: "naturale", solmization: "FA" }, { hexachord: "molle", solmization: "UT" }] }],
+    [55, { hand: { finger: "pinky", region: "mid" }, name: ["G", "Gesolreut"], variants: [{ hexachord: "durum", solmization: "UT" }, { hexachord: "naturale", solmization: "SOL" }, { hexachord: "molle", solmization: "RE" }] }],
+    [57, { hand: { finger: "pinky", region: "top" }, name: ["a", "Alamire"], variants: [{ hexachord: "durum", solmization: "RE" }, { hexachord: "naturale", solmization: "LA" }, { hexachord: "molle", solmization: "MI" }] }],
+    [58, { hand: { finger: "pinky", region: "tip" }, name: ["b", "Befa"], variants: [{ hexachord: "molle", solmization: "FA" }] }],
+    [59, { hand: { finger: "pinky", region: "tip" }, name: ["♮", "Bemi"], variants: [{ hexachord: "durum", solmization: "MI" }] }],
+    [60, { hand: { finger: "ring", region: "tip" }, name: ["c", "Cesolfaut"], variants: [{ hexachord: "durum", solmization: "FA" }, { hexachord: "naturale", solmization: "UT" }, { hexachord: "molle", solmization: "SOL" }] }],
+    [62, { hand: { finger: "middle", region: "tip" }, name: ["d", "Delasolre"], variants: [{ hexachord: "durum", solmization: "SOL" }, { hexachord: "naturale", solmization: "RE" }, { hexachord: "molle", solmization: "LA" }] }],
+    [64, { hand: { finger: "index", region: "tip" }, name: ["e", "Elami"], variants: [{ hexachord: "durum", solmization: "LA" }, { hexachord: "naturale", solmization: "MI" }] }],
+    [65, { hand: { finger: "index", region: "top" }, name: ["f", "Fefaut"], variants: [{ hexachord: "naturale", solmization: "FA" }, { hexachord: "molle", solmization: "UT" }] }],
+    [67, { hand: { finger: "index", region: "mid" }, name: ["g", "Gesolreut"], variants: [{ hexachord: "durum", solmization: "UT" }, { hexachord: "naturale", solmization: "SOL" }, { hexachord: "molle", solmization: "RE" }] }],
+    [69, { hand: { finger: "middle", region: "mid" }, name: ["aa", "Alamire"], variants: [{ hexachord: "durum", solmization: "RE" }, { hexachord: "naturale", solmization: "LA" }, { hexachord: "molle", solmization: "MI" }] }],
+    [70, { hand: { finger: "ring", region: "mid" }, name: ["bb", "Befa"], variants: [{ hexachord: "molle", solmization: "FA" }] }],
+    [71, { hand: { finger: "ring", region: "mid" }, name: ["♮♮", "Bemi"], variants: [{ hexachord: "durum", solmization: "MI" }] }],
+    [72, { hand: { finger: "middle", region: "top" }, name: ["cc", "Cesolfa"], variants: [{ hexachord: "durum", solmization: "FA" }, { hexachord: "naturale", solmization: "UT" }, { hexachord: "molle", solmization: "SOL" }] }],
+    [74, { hand: { finger: "ring", region: "top" }, name: ["dd", "Delasol"], variants: [{ hexachord: "durum", solmization: "SOL" }, { hexachord: "naturale", solmization: "RE" }, { hexachord: "molle", solmization: "LA" }] }],
+    [76, { hand: { finger: "middle", region: "super" }, name: ["ee", "Ela"], variants: [{ hexachord: "durum", solmization: "LA" }, { hexachord: "naturale", solmization: "MI" }] }],
 ]);
 //# sourceMappingURL=guido.js.map

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

@@ -39,6 +39,9 @@ export const MODES = new Map([
             scalePcs: [2, 4, 5, 7, 9, 11, 0],
             hexachords: ["naturale"],
             profile: { mood: "sad", ethos: "tristis", phrasing: "lyrical", melodic: "arch", tendency: "neumatic" },
+            // Shared with mode 1 (both Protus). An earlier seed here was wrong — a copy
+            // of mode 5's figures, landing on F with an Ab outside hypodorian's scale;
+            // Suñol's tables surfaced it, and it was corrected to the Protus descent.
             cadences: [
                 { id: "mi-re", steps: [1, 0] },
                 { id: "ut-re", steps: [-1, 0] },

package/dist/{data → engines/temper/data}/tones.js

@@ -1,4 +1,4 @@
-// humana/data/tones — psalm tones (Graduale Romanum appendix)
+// 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;

package/dist/engines/temper/gabc.js

@@ -1,15 +1,35 @@
 // ---------------------------------------------------------------------------
 // engines/temper/gabc — GABC pitch letter utilities
 // ---------------------------------------------------------------------------
+// GABC pitch letters (a–m) are DIATONIC STAFF POSITIONS, not pitch classes: the
+// thirteen letters are the thirteen slots of the four-line staff and its ledger
+// space, spanning roughly two octaves of white-key steps [biblio: gregorio-gabc].
+// A letter has no fixed pitch on its own — the clef fixes it. So converting to
+// and from MIDI is staff-position arithmetic, done in two moduli: 7 for the
+// diatonic staff (steps per octave) and 12 for MIDI (semitones per octave).
+//
+// DIATONIC maps a diatonic step (0–6, do re mi fa sol la si) to its pitch class.
+// LETTERS is the staff-slot alphabet, low to high.
 const DIATONIC = [0, 2, 4, 5, 7, 9, 11];
 const LETTERS = "abcdefghijklm";
+// A GABC clef names the staff line that carries "do" (c-clefs) or "fa" (f-clefs)
+// and thereby anchors every letter. `doIdx` is the LETTERS slot that line falls
+// on; `doMidi` is the MIDI pitch of "do" there (60 = middle C; 53 = the F below).
+// A higher c-clef (c4 vs c1) moves "do" up the staff, so the same letter reads a
+// lower pitch — hence doIdx climbs 3→5→7→9 across c1→c4. The f-clefs anchor on
+// fa (MIDI 53) and are used for lower-tessitura chant.
 const CLEFS = {
     c1: { doMidi: 60, doIdx: 3 },
     c2: { doMidi: 60, doIdx: 5 },
     c3: { doMidi: 60, doIdx: 7 },
     c4: { doMidi: 60, doIdx: 9 },
-    f3: { doMidi: 53, doIdx: 5 },
-    f4: { doMidi: 53, doIdx: 3 },
+    // f-clefs anchor fa on the named line. Staff lines (bottom→top) sit at
+    // letters d/f/h/j (per the Gregorio spec: 2-line staff = a–i, 3-line = a–k,
+    // 4-line = a–m, pinning the lines at slots 3/5/7/9), so f3 puts fa at 'h'
+    // (7) and f4 at 'j' (9). Previous values (5 and 3) were off by a third and
+    // read every f-clef chant at the wrong staff position.
+    f3: { doMidi: 53, doIdx: 7 },
+    f4: { doMidi: 53, doIdx: 9 },
 };
 export function midiToGabc(midi, clef = "c4") {
     const def = CLEFS[clef];
@@ -34,6 +54,9 @@ export function gabcToMidi(letter, clef = "c4") {
     const staffPos = LETTERS.indexOf(letter.toLowerCase());
     if (staffPos === -1)
         throw new Error(`Unknown GABC letter: ${letter}`);
+    // Diatonic steps from "do", split into whole octaves (÷7) and the step within
+    // the octave. The `((x % 7) + 7) % 7` form keeps the step in 0–6 for letters
+    // below "do", where stepsFromDo is negative and JS `%` would return negative.
     const stepsFromDo = staffPos - def.doIdx;
     const octOffset = Math.floor(stepsFromDo / 7);
     const diatStep = ((stepsFromDo % 7) + 7) % 7;

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

@@ -1,3 +1,4 @@
+import type { Finger, Region } from "./step.js";
 export type { GuidonianVariant, GuidonianEntry } from "./data/guido.js";
 export declare function lookupGuido(midi: number, mode?: number): {
     name: string | null;
@@ -9,8 +10,8 @@ export declare function lookupGuido(midi: number, mode?: number): {
         solmization: string;
     }[];
     hand: {
-        finger: string;
-        region: string;
+        finger: Finger;
+        region: Region;
     } | null;
 };
 //# sourceMappingURL=guido.d.ts.map

package/dist/engines/temper/interval.js

@@ -2,6 +2,12 @@
 // engines/temper/interval — interval classification between pitches
 // ---------------------------------------------------------------------------
 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
+// 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.
 const PERFECT_CLASSES = new Set(["P1", "P5", "P8"]);
 const IMPERFECT_CLASSES = new Set(["m3", "M3", "m6", "M6"]);
 function classifyConsonance(intervalClass) {
@@ -16,6 +22,9 @@ export function classifyInterval(a, b) {
     const abs = Math.abs(semitones);
     const simple = abs % 12;
     const direction = semitones > 0 ? "up" : semitones < 0 ? "down" : "unison";
+    // A true zero-distance unison (abs === 0) is UNISONUS; a compound octave
+    // (simple === 0 but abs a nonzero multiple of 12) folds to INTERVAL[0], the
+    // octave entry. The two share simple === 0 but name different intervals.
     const entry = abs === 0 ? UNISONUS : (simple === 0 ? INTERVAL[0] : INTERVAL[simple]);
     return {
         nomen: entry.latin,
@@ -24,6 +33,9 @@ export function classifyInterval(a, b) {
         class: entry.class,
         direction,
         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).
         cents: semitones * 100,
         consonance: classifyConsonance(entry.class),
     };

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,58 @@
+// ---------------------------------------------------------------------------
+// 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, most characteristic first (Rockstro's Grove ordering
+// [biblio: rockstro-grove]). 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/scale.js

@@ -1,6 +1,24 @@
 // ---------------------------------------------------------------------------
 // engines/temper/scale — tuning ratio builder
 // ---------------------------------------------------------------------------
+// Builds the 12 pitch-class ratios for a temperament. The default is pure
+// Pythagorean — all intervals from the 3/2 fifth and the octave — because that
+// is the tuning of medieval theory from Boethius through the Guidonian gamut
+// [biblio: boethius-institutione, guidonian-gamut], and it is correct for
+// unaccompanied chant: melodic fifths/fourths are perfect, the narrow limma
+// (256/243) gives half-steps a keen leading quality, and the wide Pythagorean
+// third (81/64) never has to serve as a consonance.
+//
+// `comma` tempers the fifth toward meantone by narrowing it by a fraction of
+// the syntonic comma (81/80, the gap between the Pythagorean and pure 5/4
+// third): comma "1/4" stacks four fifths to a pure major third — quarter-comma
+// meantone, the 16th-century sound.
+//
+// The `steps` presets supply just-intonation genera in place of the tempered
+// fifth: the three Ptolemaic diatonics (intense/soft/equable, his χρόαι
+// "shades") come straight from Ptolemy's tetrachord divisions [biblio:
+// ptolemy-harmonics, Harmonics I.15–16]. See expandDiatonicSteps for how a
+// 7-ratio genus is laid onto the fixed gamut, and why.
 import { MODES } from "./modes.js";
 // Stern-Brocot rational approximation — finds nearest simple fraction
 function approximate(value, maxDen = 1000) {
@@ -110,7 +128,14 @@ export function parseScala(input) {
 }
 const PURE_FIFTH = 3 / 2;
 const SYNTONIC_COMMA = 81 / 80;
+// The circle of fifths, as chromatic pitch classes: C G D A E B F♯ … stacking
+// twelve 3/2s. buildPythagoreanRatios walks this and octave-folds each.
 const FIFTH_TO_CHROM = [0, 7, 2, 9, 4, 11, 6, 1, 8, 3, 10, 5];
+// Ptolemy's three diatonic genera [biblio: ptolemy-harmonics, Harmonics I.15–16],
+// each a tetrachord (1/1 … 4/3) doubled up a 3/2 to fill the octave:
+//   intense (syntonon)  — classical just intonation: pure 5/4 major, 6/5 minor.
+//   soft (malakon)      — septimal: the 7th harmonic gives a large 8/7 whole tone.
+//   equable (homalon)   — undecimal: near-equal ~150–182¢ steps.
 const PTOLEMAIC = {
     "ptolemy-intense": ["1/1", "9/8", "5/4", "4/3", "3/2", "5/3", "15/8"],
     "ptolemy-soft": ["1/1", "8/7", "80/63", "4/3", "3/2", "12/7", "40/21"],
@@ -143,8 +168,14 @@ const NATURAL_PCS = [0, 2, 4, 5, 7, 9, 11];
 // pitch order — NOT onto the mode's scalePcs. A church mode is an octave
 // species of this one gamut, so its interval qualities emerge from *where the
 // final sits within the fixed tuning*, handled downstream by normalizeToRoot.
-// (Mapping degree-per-mode instead would force major-scale qualities — e.g.
-// a 5/4 major third above every final — onto every mode; see docs/tuning.md.)
+// This yields the authentic per-mode qualities (a Dorian minor third, a
+// Mixolydian ♭7) and the honest syntonic wolf (D–A = 40/27 under
+// ptolemy-intense).
+//
+// Mapping the genus degree-per-mode onto scalePcs instead would force
+// major-scale qualities — a 5/4 major third above *every* final — onto every
+// mode. Re-deriving a per-mode just intonation would attribute a modern just
+// tuning to Ptolemy, who described tetrachord divisions, not modal scales.
 function expandDiatonicSteps(diatonic) {
     const base = buildPythagoreanRatios(0);
     const out = base.slice();

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

@@ -1,6 +1,6 @@
 import type { Scale } from "./scale.js";
-export type Finger = "wrist" | "palm" | "thumb" | "index" | "middle" | "ring" | "pinky";
-export type Region = "base" | "mid" | "tip" | "top";
+export type Finger = "thumb" | "index" | "middle" | "ring" | "pinky";
+export type Region = "base" | "mid" | "top" | "tip" | "super";
 export interface StepVariant {
     hexachord: "durum" | "naturale" | "molle";
     solmization: string;

package/dist/index.d.ts

@@ -9,16 +9,16 @@ import { buildScore } from "./engines/score/api.js";
 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, CadenceFigure, GamutOptions, Tonus, TonusOpts } from "./engines/temper/api.js";
-import type { Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, Cadence, CadenceTarget, CadenceApproach, MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent, MusicXmlOpts, MusicXmlEmitResult } from "./engines/score/api.js";
+import type { CantusQuery, Chant, OrdinaryChant, PropriumQuery, OrdinariumQuery, OfficiumQuery, PsalmusQuery, Rite } from "./engines/chant/types.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";
 import type { Harmony, HarmoniaOpts, VoicedBody, VoicedAspect, Frame, Author } from "./engines/harmonia/api.js";
 import type { HarmonyTabulaRow } from "./engines/harmonia/tabula.js";
 import type { PlanetVowel } from "./engines/harmonia/data/vowels.js";
-import type { Note, Performance, Phrase, Syllable, RestEvent, ParseError, ArsisThesis } from "./engines/score/types.js";
+import type { Note, Performance, Phrase, Syllable, RestEvent, ParseError, ArsisThesis, RhythmicType, CompoundBeat } from "./engines/score/types.js";
 import type { VoicedPitch } from "./engines/harmonia/voice.js";
 import type { Cosmos, CosmosQuery, Body, BodyName, Aspect } from "./engines/planet/types.js";
 declare const tonus: {
@@ -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, CadenceFigure, GamutOptions, Tonus, TonusOpts, Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, Cadence, CadenceTarget, CadenceApproach, 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, Rite, 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, RhythmicType, CompoundBeat, 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.3",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "description": "Medieval music analysis and performance: GABC plainchant exports, liturgical calendar, tuning systems, ephemeris, and the harmony of the spheres",
@@ -42,6 +42,7 @@
     "!dist/**/*.js.map",
     "!dist/**/*.d.ts.map",
     "LICENSE",
+    "CHANGELOG.md",
     "BIBLIOGRAPHY.md"
   ],
   "scripts": {

package/dist/data/office.d.ts

@@ -1,12 +0,0 @@
-export interface OfficeDay {
-    feastId: string;
-    doFile: string;
-    antLaudes: string[];
-    antBenedictus: string | null;
-    antVespera: string[];
-    antMagnificat: string | null;
-    hymnLaudes: string | null;
-    hymnVespera: string | null;
-}
-export declare const OFFICE: OfficeDay[];
-//# sourceMappingURL=office.d.ts.map