tonus 0.1.4 → 0.1.6

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.js

@@ -13,10 +13,11 @@ const TENOR_WEIGHT = 2;
 const REGULAR_MOD_WEIGHT = 1;
 const CONCEDED_MOD_WEIGHT = 0.5;
 // A chant's opening note is a modal signal: each mode lists its valid initials
-// in rank order (the first is the most characteristic). Opening on a mode's
-// primary initial boosts it more than opening on a lower-ranked one — which is
-// what separates an authentic mode from its plagal partner, since the two share
-// a finalis but rank the same opening pitch differently.
+// 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.

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,7 +9,7 @@ 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 { 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";
@@ -18,7 +18,7 @@ import type { Prosody, RhythmicProfile, NoteRange, CadenceDistribution } from ".
 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, Modus, TunedNote, GamutOptions, Tonus, TonusOpts, Score, ScoreOpts, PondusInput, PondusOpts, AccentusInput, AccentusOpts, Cadence, CadenceTarget, CadenceApproach, Modulation, MidiOpts, MidiEmitResult, MidiJsonResult, MidiJsonEvent, MusicXmlOpts, MusicXmlEmitResult, ChantTabulaRow, Note, Performance, Phrase, Syllable, RestEvent, ParseError, ArsisThesis, VoicedPitch, Cosmos, CosmosQuery, Body, BodyName, Aspect, Imprint, Attractor, VowelAttractor, ModalAffinity, Prosody, RhythmicProfile, NoteRange, CadenceDistribution, Harmony, HarmoniaOpts, VoicedBody, VoicedAspect, Frame, Author, HarmonyTabulaRow, PlanetVowel, };
+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.4",
+  "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