tonus 0.1.3 → 0.1.6

package/dist/engines/planet/position.js

@@ -1,12 +1,33 @@
 // ---------------------------------------------------------------------------
 // engines/planet/position — Julian date, astro state, helio/geo position engine
 // ---------------------------------------------------------------------------
+// Two source models sit side by side, and which one runs depends on the body:
+//
+//   • Planets — the JPL/Standish Keplerian element tables [biblio: standish-jpl]
+//     in orbital.ts, solved with the iterative Newton kepler() solver. See
+//     planetPos.
+//   • Sun and Moon — Paul Schlyter's tutorial formulae [biblio:
+//     schlyter-positions], a lighter model with its own constants, a one-step
+//     eccentric-anomaly approximation (the Sun), and a named perturbation series
+//     (the Moon). See sunPos / moonPos.
+//
+// The split is deliberate: the JPL tables don't include the Moon, and Schlyter's
+// Sun is accurate enough at the Sun's tiny eccentricity to skip Newton iteration.
+// So the reader should not expect the same constants or solver across bodies.
+//
+// A few time-scale models here are standard astronomy but not yet catalogued in
+// BIBLIOGRAPHY.md (marked "source TBD" at each): the ΔT (TT−UT) polynomial and
+// the mean-obliquity expansion.
 import { sinDeg, cosDeg, atan2Deg, kepler, wrapAngle, toAu, toCartesian, toSpherical, toEquatorial } from "./math.js";
 import { ORBITAL_ELEMENTS } from "./orbital.js";
 const MS_PER_DAY = 86400000;
 // Precomputed Earth radius in AU (used for Moon distance conversion)
 const EARTH_ELEM = ORBITAL_ELEMENTS.get("Earth");
 export const EARTH_RADIUS_AU = toAu(EARTH_ELEM.radius);
+// Mean obliquity of the ecliptic (the tilt used to rotate ecliptic → equatorial
+// coordinates), in degrees. eps0 is the J2000 value 23°26′21.406″; the arcsecond
+// series is the standard IAU 2006 expansion in Julian centuries T from J2000.
+// (Standard astronomy; source not yet catalogued — TBD.)
 function meanObliquity(T) {
     const eps0 = 23 + 26 / 60 + 21.406 / 3600;
     const sec = -46.836769 * T -
@@ -17,8 +38,14 @@ function meanObliquity(T) {
     return eps0 + sec / 3600;
 }
 export function getState(ts) {
+    // 2440587.5 is the Julian Date of the Unix epoch; 2451545 is J2000.0 and 36525
+    // days is a Julian century — so _T is centuries from J2000 in UT.
     const JD = 2440587.5 + ts / MS_PER_DAY;
     const _T = (JD - 2451545) / 36525;
+    // ΔT (TT − UT), in seconds: the drift between civil UT and the uniform
+    // Terrestrial Time the ephemerides are reckoned in. This is a coarse local fit
+    // valid near the present, not a long-baseline model — a limitation for deep
+    // medieval dates. (Standard-form polynomial; source not yet catalogued — TBD.)
     const dT = 64.7 + 64.7 * _T - 0.6 * _T * _T; // seconds
     const TT = JD + dT / 86400;
     const J = TT - 2451545.0;
@@ -26,12 +53,16 @@ export function getState(ts) {
     const eps = meanObliquity(T);
     return { JD, TT, TS: ts, J, T, eps };
 }
-// ── Sun position ──
+// ── Sun position ── (Schlyter's solar elements [biblio: schlyter-positions])
 export function sunPos(state) {
     const { J, eps } = state;
+    // omega = longitude of perihelion, e = eccentricity, M = mean anomaly, all as
+    // Schlyter's linear-in-J elements (J = days from J2000).
     const omega = 282.9404 + 4.70935e-5 * J;
     const e = 0.016709 - 1.151e-9 * J;
     const M = 356.047 + 0.9856002585 * J;
+    // Eccentric anomaly by a single first-order step, not Newton iteration: the
+    // Sun's eccentricity is small enough (~0.017) that one correction suffices.
     const E = M + (180 / Math.PI) * e * sinDeg(M) * (1 + e * cosDeg(M));
     const xp = cosDeg(E) - e;
     const yp = Math.sqrt(1 - e * e) * sinDeg(E);
@@ -54,9 +85,13 @@ export function sunPos(state) {
         },
     };
 }
-// ── Moon position ──
+// ── Moon position ── (Schlyter's lunar elements [biblio: schlyter-positions])
 export function moonPos(state, sun) {
     const { J, eps } = state;
+    // Orbital elements (J = days from J2000): Omega = ascending node, I =
+    // inclination, omega = argument of perigee, a = semi-major axis IN EARTH RADII
+    // (not AU — the Moon is measured from Earth; the AU conversion happens at the
+    // end via EARTH_RADIUS_AU), e = eccentricity, M = mean anomaly.
     const Omega = wrapAngle(125.1228 - 0.0529538083 * J);
     const I = 5.1454;
     const omega = wrapAngle(318.0634 + 0.1643573223 * J);
@@ -73,12 +108,18 @@ export function moonPos(state, sun) {
     const y = (cw * sO + sw * cO * cI) * xh + (-sw * sO + cw * cO * cI) * yh;
     const z = sw * sI * xh + cw * sI * yh;
     const [lonE, latE, distE] = toSpherical(x, y, z);
+    // The perturbation arguments: Lm = Moon's mean longitude, Ms/Ls = Sun's mean
+    // anomaly/longitude, D = mean elongation (Moon − Sun), F = argument of latitude
+    // (Moon − node). The Sun's disturbing pull is expressed as sines of these.
     const Lm = wrapAngle(Omega + omega + M);
     const Ms = sun.orbit.M;
     const Ls = sun.orbit.L;
     const D = wrapAngle(Lm - Ls);
     const F = wrapAngle(Lm - Omega);
-    // Lunar perturbations
+    // Lunar perturbations, in degrees — Schlyter's truncated series of the classical
+    // named terms. The three largest in longitude are the evection (−1.274·sin(M−2D),
+    // the Sun stretching the Moon's ellipse), the variation (+0.658·sin(2D)), and
+    // the annual equation (−0.186·sin Ms); the remainder are smaller corrections.
     const lonPerturb = -1.274 * sinDeg(M - 2 * D) + 0.658 * sinDeg(2 * D) - 0.186 * sinDeg(Ms) -
         0.059 * sinDeg(2 * M - 2 * D) - 0.057 * sinDeg(M - 2 * D + Ms) +
         0.053 * sinDeg(M + 2 * D) + 0.046 * sinDeg(2 * D - Ms) +
@@ -116,12 +157,17 @@ export function planetPos(name, state, sun) {
         throw new Error(`Unknown body: ${name}`);
     const { J, T, eps } = state;
     const oe = body.datasets;
-    // Use higher-precision dataset (1800–2050) if in range, otherwise long-range dataset
+    // Two Standish element sets per body (see orbital.ts): [1] is fitted tightly
+    // for 1800–2050, [0] trades accuracy for 3000 BC–3000 AD coverage. The bounds
+    // are J (days from J2000): −73048.5 ≈ 1800, 18626.5 ≈ 2050. Inside the window
+    // use the precise set, outside fall back to the long-range one.
     const dataset = J > -73048.5 && J < 18626.5 ? oe[1] : oe[0];
     const [a, e, I, L, wBar, Omega] = dataset.map(([x0, x1]) => x0 + x1 * T);
     const omega = wBar - Omega; // argument of periapsis
     let M = L - wBar; // mean anomaly
-    // Perturbation correction for outer planets
+    // Standish's great-inequality correction for the outer planets (Jupiter–Neptune):
+    // a secular b·T² plus a long-period cos/sin term at frequency f. Only bodies
+    // that carry a datasets[2] (see orbital.ts) get it. [biblio: standish-jpl]
     if (oe[2]) {
         const [b, c, s, f] = oe[2];
         M += b * T * T + c * cosDeg(f * T) + s * sinDeg(f * T);

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

@@ -1,6 +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";
@@ -32,6 +33,8 @@ export interface Score {
     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
@@ -53,6 +56,7 @@ 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

@@ -8,6 +8,7 @@ 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";
@@ -61,6 +62,8 @@ export function buildScore(chant, opts) {
     // 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,
@@ -82,7 +85,14 @@ export function buildScore(chant, opts) {
         tabula,
         prosody: computeProsody(ir.phrases),
         cadences,
-        imprint: computeImprint(ir.phrases, scale),
+        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

@@ -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.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 [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) {
+    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/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;