tonus 0.1.4 → 0.1.6

package/dist/engines/score/articulation.js

@@ -1,35 +1,92 @@
 // ---------------------------------------------------------------------------
 // engines/score/articulation — note-level articulation profiles
 // ---------------------------------------------------------------------------
+// The pondus ("weight") tables. Each GABC performance mark — episema, quilisma,
+// liquescent, strophicus, oriscus, ictus — carries a weight delta and a
+// duration delta that the parser folds into a note's rhythmicShape (see the
+// tanh compressor in parse.ts). The signs encode the semiological reading of
+// the mark [biblio: cardine-semiology], and the durational values the Solesmes
+// rhythmic tradition [biblio: desrocquettes-values, liber-usualis]: POSITIVE
+// lengthens/stresses, NEGATIVE lightens/shortens. So an episema lengthens
+// (+0.9 duration), a liquescent is a passing lightening (−0.4 weight), an
+// uppercase-syllable note is de-stressed (−0.7).
+//
+// Four profiles select how strongly those rules speak, from a semiological
+// restraint to full Solesmes-rule fidelity:
+//   restrained — Cardine's semiological reading: rules present but soft-spoken.
+//   balanced   — the default; BASE_WEIGHTS unaltered.
+//   expressive — rules pushed (stronger ictus and accent, wider contour).
+//   strict     — maximal Solesmes-rule fidelity (episema to a full double, a
+//                sharper quilisma). The differences live in the per-profile
+//                weight overrides below.
+// The curve params (weightBase/Gain/Saturation) shape the tanh knee, not the
+// marks; they are documented at the profile block. These magnitudes are tuned
+// by ear, not taken from a table — the sources fix the direction, not the value.
 const BASE_WEIGHTS = {
+    // Ictus — the rhythmic footfall (parse.ts's three-rule assignment): a stress
+    // and a slight broadening.
     ictusWeight: 0.9,
     ictusDuration: 0.35,
+    // Episema — the horizontal episema is the Solesmes lengthening mark; the note
+    // is broadened but only lightly stressed. Double episema broadens further.
     episemaWeight: 0.6,
     episemaDuration: 0.9,
     episemaDoubleDuration: 0.6,
+    // Strophicus — repeated notes (distropha/tristropha); a soft repercussion
+    // that broadens; the triple adds duration.
     strophicusWeight: 0.4,
     strophicusDuration: 0.8,
     strophicusTripleDuration: 0.6,
+    // Quilisma — the mark itself is a light, tremulous passing note (−0.3), but
+    // the rule is that the *preceding* note receives the stress and lengthening.
+    // Hence prev is positive and the quilisma negative — not a sign error.
     quilismaPrevWeight: 0.6,
     quilismaWeight: -0.3,
+    // Liquescent — a diminished, half-voiced note easing a consonant cluster:
+    // lighter and shorter.
     liquescentWeight: -0.4,
     liquescentDuration: -0.35,
+    // Initio — the first note of a group/melisma gets a gentle onset stress.
     initioWeight: 0.6,
     initioMelismaWeight: 0.3,
     initioMelismaDuration: 0.1,
+    // Accent — a tonic word-accent lands a stress.
     accentWeight: 0.4,
+    // Uppercase — an emphasized-capital syllable in GABC is conventionally the
+    // quiet incipit letter of a chant, so it is de-stressed and slightly quickened.
     uppercaseWeight: -0.7,
     uppercaseDuration: -0.2,
+    // Repercussion (pressus) — like the quilisma, the weight falls on the note
+    // *before* the repercussed unison; the oriscus element itself is light.
     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
+    // Oriscus — a soft, light note taken slightly faster (accelerando); its
+    // rhythmic support sits on the preceding note.
+    oriscusWeight: -0.3,
+    oriscusDuration: -0.15,
+    oriscusPrevWeight: 0.3,
+    // Break (a neume-internal division `!`/`/`) marks a fresh onset → a stress;
+    // dash (a bare context, e.g. an unaccented syllable) lightens and quickens.
     breakWeight: 0.6,
     dashWeight: -0.8,
     dashDuration: -0.2,
 };
+// Curve params (same fields on every profile below). They shape how the summed
+// weight becomes a velocity, not what each mark contributes:
+//   weightBase       — the velocity a note centres on; the tanh term swings ±gain
+//                      around it, so output sits roughly in [base−gain, base+gain].
+//   weightGain       — how loudly the rules speak: scales the tanh output (also
+//                      multiplied by ruleGain). Rises restrained→expressive as rules
+//                      gain authority (2.3 → 3 → 3.5), strict slightly under expressive.
+//   weightSaturation — the tanh knee divisor: larger = later compression, so louder
+//                      peaks survive; expressive lowers it (2.8) for a sharper dynamic.
+//   durationBase/Gain/Min/Max — the same shape applied to duration deltas, clamped.
+//   ruleGain         — global authority of the mark rules vs. positional shaping.
+//   contourScale     — how much melodic contour (rise/fall) colours velocity.
+//   neumeArch/durArch— the within-neume rise-and-fall (see phrasing.ts's arch).
+//   ictusBoost       — a final multiplier on ictus notes.
+// All tuned by ear; the ordering across profiles is the doctrine, the values are not.
 const ARTICULATION_PROFILES = {
     restrained: {
         weights: { ...BASE_WEIGHTS, accentWeight: 0.25, ictusDuration: 0.2 },

package/dist/engines/score/cadence.js

@@ -1,6 +1,6 @@
-// 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.
+// Cadence formulae run four to ten notes [biblio: homan-cadence, 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) {

package/dist/engines/score/emitters/midi.js

@@ -1,5 +1,9 @@
-// Divisio → rest duration (in the same beat units as note durations). Mirrors
-// DIVISIO_DURATIONS in parse.ts; a phrase's terminal divisio becomes a rest.
+// Divisio → rest duration (in the same beat units as note durations); a phrase's
+// terminal divisio becomes a rest of this length. This is the *durational*
+// reading of the divisio hierarchy (canonical table in docs/score.md), distinct
+// from prosody.ts's analytic weights and phrasing.ts's shaping strengths — three
+// readings of the same bar-lines, each for its own purpose. Values mirror
+// DIVISIO_DURATIONS in parse.ts (the source of the fractional beat lengths).
 const DIVISIO_REST = {
     ",": 0.54, "`": 0.33, ";": 0.8, ":": 1.1, "::": 1.8,
 };

package/dist/engines/score/infer.js

@@ -1,5 +1,9 @@
 import { OFFICE_LABELS } from "../chant/types.js";
 import { MODES } from "../temper/modes.js";
+// Identify an ordinary chant by its opening words. Two movements have a second,
+// interior incipit because they are conventionally intoned from their second
+// phrase: the Gloria's "Et in terra pax" (the celebrant sings "Gloria in
+// excelsis") and the Credo's "Patrem omnipotentem" ("Credo in unum Deum").
 const ORDINARY_INCIPITS = [
     [/^kyrie/i, "ky"],
     [/^gloria/i, "gl"],
@@ -38,6 +42,9 @@ export function inferMode(ir) {
     }
     if (midis.length === 0)
         return undefined;
+    // The finalis is the last note of the chant — the fundamental assumption of
+    // modal analysis: a chant comes to rest on its mode's final [biblio:
+    // liber-usualis]. That pitch class picks the maneria (mode pair).
     const finalisPc = ((midis[midis.length - 1] % 12) + 12) % 12;
     const candidates = [];
     for (const [num, data] of MODES) {
@@ -48,7 +55,12 @@ export function inferMode(ir) {
         return undefined;
     if (candidates.length === 1)
         return candidates[0];
-    // Authentic vs plagal: melody mean above finalis → authentic
+    // Within a maneria the authentic mode ranges a fifth-and-more ABOVE the final,
+    // the plagal one straddles it (roughly a fourth below to a fifth above) [biblio:
+    // sunol-textbook]. So the mean pitch's height above the final separates them.
+    // The thresholds are asymmetric and tuned: a melody must sit a clear +3
+    // semitones above the final to read authentic, but only dip −1 below to read
+    // plagal (plagal melodies dip under the final; authentic ones rarely do).
     const finalisStep = midis[midis.length - 1];
     const mean = midis.reduce((s, v) => s + v, 0) / midis.length;
     const offset = mean - finalisStep;

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

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

package/dist/engines/score/ir.js

@@ -24,13 +24,13 @@ function rawToNote(raw, scale) {
             liquescent: raw.liquescent,
             strophicus: raw.strophicus,
             oriscus: raw.oriscus,
-            doubleEpisema: raw.doubleEpisema,
+            mora: raw.mora,
             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.
+// The salicus ictus note (its second-to-last ascending note) is prolonged
+// [biblio: sunol-textbook, Ch. V]. Modest, in the spirit of an episema.
 const SALICUS_PROLONGATION = 1.3;
 function makeSyllable(lyric, notes) {
     const neume = classifyNeume(notes);
@@ -46,16 +46,16 @@ function partitionByIctus(annotated) {
     let currentIctusMidi;
     const closeGroup = (items, ictusMidi) => {
         const neumeTypes = new Set();
-        let hasDoubleEpisema = false;
+        let hasDoubleMora = false;
         for (const a of items) {
             neumeTypes.add(a.neumeType);
-            if (a.note.context.doubleEpisema)
-                hasDoubleEpisema = true;
+            if (a.note.context.mora === 2)
+                hasDoubleMora = true;
         }
         return {
             notes: items.map((a) => a.note),
             neumeTypes,
-            hasDoubleEpisema,
+            hasDoubleMora,
             ictusMidi,
             shape: "arsic",
         };
@@ -85,7 +85,7 @@ function classifyGroup(group, prev, apexMidi) {
     // regardless of melodic context.
     if (group.neumeTypes.has("salicus"))
         return "arsic";
-    if (group.hasDoubleEpisema && group.neumeTypes.has("clivis"))
+    if (group.hasDoubleMora && group.neumeTypes.has("clivis"))
         return "thetic";
     const groupIctusMidi = group.ictusMidi ?? group.notes[0].pitch.midi;
     // Rule 1: incise unity — at or after the apex, everything thetic.
@@ -111,14 +111,18 @@ function classifyGroup(group, prev, apexMidi) {
     // Tie-breaker: alternate from previous.
     return prev.shape === "arsic" ? "thetic" : "arsic";
 }
+// Classify each compound beat, stamp its notes, and return the beat sequence —
+// the A/T shape of the incise, which the rhythmic-type classifier and (later)
+// the chironomy renderer both read.
 function classifyCompoundBeats(annotated) {
     if (annotated.length === 0)
-        return;
+        return [];
     const groups = partitionByIctus(annotated);
     // Apex = highest-pitched ictus in the incise.
     const apexMidi = annotated
         .filter((a) => a.note.context.ictus)
         .reduce((max, a) => Math.max(max, a.note.pitch.midi), -Infinity);
+    const beats = [];
     for (let gi = 0; gi < groups.length; gi++) {
         const group = groups[gi];
         const prev = gi > 0 ? groups[gi - 1] : null;
@@ -127,7 +131,44 @@ function classifyCompoundBeats(annotated) {
             group.notes[ni].performance.rhythmicShape = group.shape;
             group.notes[ni].performance.rhythmicIndex = ni + 1;
         }
+        beats.push({ shape: group.shape, noteCount: group.notes.length });
     }
+    return beats;
+}
+// Le Guennant's rhythmic types (IV–VIII) from the beat sequence — how the incise's
+// compound beats chain [biblio: carroll-chironomy, pp. 22–26]. A type is emitted
+// only when the sequence genuinely fits; ambiguous shapes stay null (a wrong
+// analytic label is worse than none). Contraction (Type VIII) is Suñol's local
+// reading [biblio: sunol-textbook]: a thesis immediately followed by an arsis
+// mid-incise means two simple rhythms overlap at a shared ictus.
+export function classifyRhythmicType(beats) {
+    if (beats.length < 2)
+        return null; // a lone beat has no chaining; needs ≥ A–T
+    const seq = beats.map((b) => b.shape);
+    if (seq[0] !== "arsic")
+        return null; // an incise never begins thetic (Carroll p. 43)
+    const hasSeam = seq.some((s, i) => i > 0 && seq[i - 1] === "thetic" && s === "arsic");
+    if (!hasSeam) {
+        // A single rise-and-fall: arses, then theses, no interior thesis→arsis.
+        const arses = seq.filter((s) => s === "arsic").length;
+        const theses = seq.length - arses;
+        if (theses === 0)
+            return null; // all arsic, no resolution
+        if (arses === 1 && theses === 1)
+            return "IV"; // A–T
+        if (arses >= 2 && theses === 1)
+            return "V"; // A–A…–T
+        if (arses === 1 && theses >= 2)
+            return "VI"; // A–T–T…
+        return null;
+    }
+    // There is at least one thesis→arsis seam, so the incise chains multiple simple
+    // rhythms. Strict alternation A–T–A–T(…) is Carroll's Type VII; any other seam
+    // pattern is a contraction (Suñol) — Carroll's Type VIII.
+    const alternating = seq.every((s, i) => s === (i % 2 === 0 ? "arsic" : "thetic"));
+    if (alternating && seq.length >= 4)
+        return "VII";
+    return "VIII";
 }
 function applyCompoundBeats(phrases) {
     for (const phrase of phrases) {
@@ -137,12 +178,13 @@ function applyCompoundBeats(phrases) {
                 annotated.push({ note, neumeType: syl.neume.type });
             }
         }
-        classifyCompoundBeats(annotated);
+        phrase.beats = classifyCompoundBeats(annotated);
+        phrase.rhythmicType = classifyRhythmicType(phrase.beats);
     }
 }
 export function buildIR(parsed, chant, scale) {
     const phrases = [];
-    let currentPhrase = { syllables: [] };
+    let currentPhrase = { syllables: [], beats: [], rhythmicType: null };
     let currentNotes = [];
     let currentLyric = null;
     for (const event of parsed.events) {
@@ -167,7 +209,7 @@ export function buildIR(parsed, chant, scale) {
             }
             currentPhrase.divisio = event;
             phrases.push(currentPhrase);
-            currentPhrase = { syllables: [] };
+            currentPhrase = { syllables: [], beats: [], rhythmicType: null };
         }
     }
     if (currentLyric !== null && currentNotes.length > 0) {

package/dist/engines/score/modulation.js

@@ -1,8 +1,8 @@
 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.
+// examples [biblio: sunol-textbook]: at 0.25 the modulations he names in Christus
+// resurgens (to mode 3) register, while incidental 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) {

package/dist/engines/score/parse.js

@@ -5,6 +5,11 @@ const DEFAULT_OPTIONS = {
     oct: 3,
     useVowelAccent: true,
 };
+// Per-clef diatonic-step offset. A GABC clef names the staff line it sits on
+// (c1–c4, f1–f4; the `b` variants also declare a flat), which fixes which pitch
+// the letters a–m read as. The value is subtracted from the letter's position
+// when anchoring it onto the gamut (see `pos` below), so the same letter reads
+// higher or lower depending on the clef in force.
 const CLEF_OFFSETS = new Map([
     ["c1", -3],
     ["c2", -1],
@@ -84,7 +89,7 @@ function parseNeume(notation, context) {
         let isLiquescent = false;
         let isStrophicus = false;
         let isOriscus = false;
-        let isDoubleEpisema = false;
+        let mora = 0;
         // Dash prefix (weak note)
         if (token[0] === "-") {
             token = token.slice(1);
@@ -143,16 +148,19 @@ function parseNeume(notation, context) {
             durWeight += weights.ictusDuration;
             ictus = true;
         }
-        // Episema (horizontal lengthening '.')
+        // Mora vocis — the GABC dot '.' lengthens THIS note (a held note before a
+        // pause). A double dot '..' is the double mora (a stronger lengthening at a
+        // major cadence); it adds to this note's duration, not the neume's first
+        // note — the dots belong to the note that carries them. (The horizontal
+        // episema is '_', handled with the ictus markers above.)
         if (modifiers.includes(".")) {
             w += weights.episemaWeight;
             durWeight += weights.episemaDuration;
             ictus = true;
-            // Double episema '..' — boost first note of neume
+            mora = 1;
             if (modifiers.includes("..")) {
-                isDoubleEpisema = true;
-                if (intermed[0])
-                    intermed[0]._durWeight += weights.episemaDoubleDuration;
+                mora = 2;
+                durWeight += weights.episemaDoubleDuration;
             }
         }
         // Strophicus (ss or vv = repeated/tremolo notes)
@@ -233,7 +241,7 @@ function parseNeume(notation, context) {
             liquescent: isLiquescent,
             strophicus: isStrophicus,
             oriscus: isOriscus,
-            doubleEpisema: isDoubleEpisema,
+            mora,
             _weight: w,
             _durWeight: durWeight,
         });
@@ -288,7 +296,7 @@ function parseNeume(notation, context) {
             liquescent: note.liquescent,
             strophicus: note.strophicus,
             oriscus: note.oriscus,
-            doubleEpisema: note.doubleEpisema,
+            mora: note.mora,
         };
     });
     return result;

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.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 {};

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;