tonus 0.1.8 → 0.5.0

package/dist/engines/planet/planet.d.ts

@@ -1,4 +1,14 @@
 import type { Cosmos, CosmosQuery } from "./types.js";
+/** The twelve signs, in ecliptic order from the vernal point — the machine
+ * codes. Exported because a body's `sign` is one of these and a consumer
+ * drawing the zodiac needs the same twelve in the same order; copying them out
+ * is how a second, drifting list gets written. */
+export declare const SIGNS: readonly ["Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces"];
+/** The same twelve as the books name them. Eight are already their own Latin
+ * nominative; the four that differ are the ones English clipped — Scorpius for
+ * Scorpio, and the -us/-i endings the others dropped. Parallel to a body's
+ * `name`/`nomen` pair: the code stays English, the Latin rides beside it. */
+export declare const SIGNA: readonly ["Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo", "Libra", "Scorpius", "Sagittarius", "Capricornus", "Aquarius", "Pisces"];
 /**
  * Ephemeris lookup (`tonus.caelum`). Computes geocentric and heliocentric
  * positions, zodiac signs, retrogradation, and aspects for the classical

package/dist/engines/planet/planet.js

@@ -10,12 +10,25 @@ import { latinName } from "./types.js";
 import { DEFAULT_EPOCH } from "../epoch.js";
 const MS_PER_DAY = 86400000;
 const ALL_BODIES = ["Sun", "Moon", "Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn"];
-const SIGNS = [
+/** The twelve signs, in ecliptic order from the vernal point — the machine
+ * codes. Exported because a body's `sign` is one of these and a consumer
+ * drawing the zodiac needs the same twelve in the same order; copying them out
+ * is how a second, drifting list gets written. */
+export const SIGNS = [
     "Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo",
     "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces",
 ];
+/** The same twelve as the books name them. Eight are already their own Latin
+ * nominative; the four that differ are the ones English clipped — Scorpius for
+ * Scorpio, and the -us/-i endings the others dropped. Parallel to a body's
+ * `name`/`nomen` pair: the code stays English, the Latin rides beside it. */
+export const SIGNA = [
+    "Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo",
+    "Libra", "Scorpius", "Sagittarius", "Capricornus", "Aquarius", "Pisces",
+];
 const zodiac = (lon) => Math.floor(wrapAngle(lon) / 30) % 12;
 const sign = (lon) => SIGNS[zodiac(lon)];
+const signum = (lon) => SIGNA[zodiac(lon)];
 function computeSpeed(geoLon, name, ts) {
     const nextState = getState(ts + MS_PER_DAY);
     const nextSun = sunPos(nextState);
@@ -50,6 +63,7 @@ function buildSun(ts) {
         apparentDiameter: app.apparentDiameter,
         zodiac: zodiac(pos.geo.lon),
         sign: sign(pos.geo.lon),
+        signum: signum(pos.geo.lon),
     };
 }
 function buildMoon(ts) {
@@ -82,6 +96,7 @@ function buildMoon(ts) {
         apparentDiameter: app.apparentDiameter,
         zodiac: zodiac(pos.geo.lon),
         sign: sign(pos.geo.lon),
+        signum: signum(pos.geo.lon),
         distEarthRadii: pos.distEarthRadii,
     };
 }
@@ -115,8 +130,14 @@ function buildPlanet(name, ts) {
         elongation: app.elongation,
         phase: app.phase,
         apparentDiameter: app.apparentDiameter,
-        zodiac: zodiac(pos.helio.lon),
-        sign: sign(pos.helio.lon),
+        // GEOCENTRIC, as the Sun's and Moon's are: a sign placement says where a
+        // body appears from here, which is the only frame in which "Mars in
+        // Sagittarius" means anything. Reading the heliocentric longitude put a
+        // body's own sign at odds with its own geo.lon — Mercury reported in Aries
+        // while appearing in Taurus.
+        zodiac: zodiac(pos.geo.lon),
+        sign: sign(pos.geo.lon),
+        signum: signum(pos.geo.lon),
     };
 }
 function buildEarth(ts) {
@@ -142,6 +163,7 @@ function buildEarth(ts) {
         apparentDiameter: 0,
         zodiac: zodiac(pos.helio.lon),
         sign: sign(pos.helio.lon),
+        signum: signum(pos.helio.lon),
     };
 }
 const BODY_BUILDERS = {
@@ -192,7 +214,12 @@ export function getCosmos(query = {}) {
         }
         return frames;
     }
+    if (query.feast != null &&
+        (typeof query.feast !== "object" || !(query.feast.date instanceof Date)))
+        throw new Error("caelum: feast must be a Feast (from tonus.festum) — its date places the sky");
     const date = query.date ?? query.feast?.date ?? DEFAULT_EPOCH;
+    if (!(date instanceof Date) || Number.isNaN(date.getTime()))
+        throw new Error(`caelum: date must be a Date — e.g. new Date("2026-12-25") (UTC-canonical)`);
     return snapshotAt(date, requested, query.orbLimit);
 }
 //# sourceMappingURL=planet.js.map

package/dist/engines/planet/position.js

@@ -16,8 +16,8 @@
 // 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.
+// ../../../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;
@@ -157,18 +157,21 @@ export function planetPos(name, state, sun) {
         throw new Error(`Unknown body: ${name}`);
     const { J, T, eps } = state;
     const oe = body.datasets;
-    // 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];
+    // Two Standish element sets per body (see orbital.ts): [0] is Table 1, fitted
+    // tightly for 1800–2050; [1] is Table 2a, trading 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 — which is the set tonus's medieval epoch runs on.
+    const inWindow = J > -73048.5 && J < 18626.5;
+    const dataset = inWindow ? oe[0] : oe[1];
     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
     // 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]) {
+    // a secular b·T² plus a long-period cos/sin term at frequency f. Table 2b is
+    // defined for use with the Table 2a elements only, so it applies exactly when
+    // the long-range set is in play. [biblio: standish-jpl]
+    if (!inWindow && oe[2]) {
         const [b, c, s, f] = oe[2];
         M += b * T * T + c * cosDeg(f * T) + s * sinDeg(f * T);
     }

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

@@ -33,6 +33,7 @@ export interface Body {
     };
     zodiac: number;
     sign: string;
+    signum: string;
     distEarthRadii?: number;
 }
 export interface Aspect {

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

@@ -3,8 +3,6 @@ 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";
 import type { Chant } from "../chant/types.js";
 import type { Temperamentum } from "../temper/api.js";
 import type { ArticulationProfile, PhrasingProfile, ParseError, Phrase as IRPhrase } from "./types.js";
@@ -36,14 +34,6 @@ export interface Score {
     /** 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
-     * by default; `format: "json"` returns the event structure, `"both"` an
-     * object. The score's pondus/accentus reach the output via the tabula.
-     */
-    midi(opts?: MidiOpts): Uint8Array | MidiEmitResult;
-    /** Emit a MusicXML 4.0 partwise document from the score's tabula. */
-    musicxml(opts?: MusicXmlOpts): MusicXmlEmitResult;
 }
 /**
  * Score builder (`tonus.notatio`). Parses a chant's GABC into a musical
@@ -55,8 +45,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 { Cadence, CadenceTarget, CadenceApproach, CadenceKeyEvent } from "./cadence.js";
+export { cadenceKeys } 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

@@ -11,8 +11,7 @@ import { detectCadences } from "./cadence.js";
 import { detectModulations } from "./modulation.js";
 import { computeTabula } from "./tabula.js";
 import { MODES } from "../temper/modes.js";
-import { toMidi } from "./emitters/midi.js";
-import { toMusicXML } from "./emitters/musicxml.js";
+import { cadentiaFamilia } from "../../data/cadentiae.js";
 const PONDUS_TO_ARTICULATION = {
     restrained: "restrained",
     balanced: "balanced",
@@ -40,6 +39,8 @@ function resolveAccentus(input) {
  * @throws Error on invalid Chant input or unparseable GABC.
  */
 export function buildScore(chant, opts) {
+    if (!chant || typeof chant !== "object" || typeof chant.gabc !== "string")
+        throw new Error("notatio needs a Chant with a gabc string — build one with tonus.cantus({ gabc })");
     const pondus = resolvePondus(opts?.pondus);
     const accentus = resolveAccentus(opts?.accentus);
     const parsed = parseGABC(chant.gabc, {
@@ -62,10 +63,24 @@ 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);
+    // The corpus join, on the same footing as MODES above: a resolved table
+    // meeting detected data. The detector computes the signature and stops, so
+    // this is the one place a cadence learns how often its family closes.
+    // Below the catalogue's floor there is no family, and finality stays null —
+    // an uncatalogued close, not a close that never closes.
+    for (const cadence of cadences) {
+        cadence.finality = cadence.signature
+            ? (cadentiaFamilia(cadence.signature)?.finality ?? null)
+            : null;
+    }
     // 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,
+        // The office gate: a chant that names its liturgical type gets phrasing
+        // even when its mode must be inferred — the gate computeTabula always had,
+        // now actually fed.
+        office: chant.office,
         a4Hz: opts?.temperamentum?.a4,
         transpose: opts?.temperamentum?.transpose,
         cadences,
@@ -93,12 +108,10 @@ export function buildScore(chant, opts) {
                 return `${pi}:${si}:${ni}`;
             })),
         }),
-        midi(emitOpts) {
-            return toMidi(tabula, emitOpts);
-        },
-        musicxml(emitOpts) {
-            return toMusicXML(tabula, chant, emitOpts);
-        },
     };
 }
+// THE cadence family key, exported as a FUNCTION and not only a type: the
+// census and the CADENTIAE miner need to key a flat tabula, and re-deriving
+// the algorithm is exactly the fork this shared export forbids.
+export { cadenceKeys } from "./cadence.js";
 //# sourceMappingURL=api.js.map

package/dist/engines/score/articulation.js

@@ -3,8 +3,8 @@
 // ---------------------------------------------------------------------------
 // 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
+// duration delta that the parser folds into a note's weight and duration (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

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

@@ -28,7 +28,83 @@ export interface Cadence {
     confidence: number;
     /** Note positions forming this cadence: [phraseIndex, syllableIndex, noteIndex]. */
     notes: Array<[number, number, number]>;
+    /**
+     * The corpus-catalogue key, "shape @arrival" (e.g. "2,0,-2 @0" — see
+     * CADENTIAE). A single-note phrase keys with an empty shape (" @0"):
+     * a landing with no gesture is still a cadence.
+     */
+    signature: string | null;
+    /** Interval signature of the closing tail (<=4 notes), in semitones. */
+    shape: number[];
+    /** Closing note minus the CHANT'S OWN closing note (its sounded final —
+     *  not the labeled mode's final, which may disagree on a transposed or
+     *  mislabeled chant), in SIGNED semitones — not octave-reduced. */
+    arrival: number;
+    /**
+     * The catalogued family's measured finality: the share of THIS FAMILY's
+     * corpus occurrences that fall at a final close. null when the signature is
+     * below the catalogue's floor (about a third of cadences), and null on a
+     * cadence taken straight from `detectCadences` — the join happens in the
+     * score builder, not the detector.
+     *
+     * A measurement, not a name, which is why it rides here while `familia`
+     * does not: the signature is already the family's name, but how often that
+     * family CLOSES cannot be read off the signature. Families landing on the
+     * final range from 0.054 to 1.000, so `arrival === 0` does not imply a close.
+     */
+    finality: number | null;
 }
+/**
+ * Octave-reduce a semitone offset to [-5..+6].
+ *
+ * NOT part of the family key — kept because the folded value is still worth
+ * reporting (it is the scale DEGREE, mode-theoretically real). As a key the
+ * fold made a fifth ABOVE the final share a family with a fourth BELOW:
+ * measured over 27,985 phrase ends, 3,499 landed on @-5, of which 2,427 were
+ * really +7 and 1,072 really -5. Two opposite gestures, one key. Arrival in
+ * the key is therefore the SIGNED offset; see cadenceKeys().
+ */
+export declare function reduceArrival(semitones: number): number;
+/** One phrase-end event: the family key, and whether it closes the chant. */
+export interface CadenceKeyEvent {
+    /** `"<interval,interval,…> @<signed arrival>"` — empty shape for a 1-note phrase. */
+    key: string;
+    /** Shape only: the tail's successive semitone intervals. */
+    shape: number[];
+    /** Signed semitone offset of the landing note from the chant's closing note. */
+    arrival: number;
+    /** The arrival octave-reduced to [-5..+6] — the scale degree, not the key. */
+    degree: number;
+    /** A chant end, or a full-bar "::" — as opposed to an interior phrase end. */
+    isFinal: boolean;
+    /** Index of the phrase this closes. */
+    phraseIndex: number;
+}
+/**
+ * THE cadence family key — one implementation, shared by every consumer.
+ *
+ * This once existed three times: here (keyed off the Phrase tree), in
+ * tonus-corpus `census/_shared.mjs` (keyed off flat tabula rows), and in the
+ * CADENTIAE miner (a character-for-character copy of the census one). They
+ * agreed — measured corpus-wide, 28,051 engine cadences against 27,985 census
+ * phrase ends with ZERO key disagreements — but agreement by luck across three
+ * copies is what "no second parser, no drift" forbids; hence this one shared
+ * function.
+ *
+ * Takes the FLAT shape, because that is what the census and the miner have; the
+ * engine's own detection flattens into it. A phrase end is a `phraseIndex`
+ * transition or the last row.
+ *
+ * A ONE-NOTE PHRASE IS A CADENCE — it has a landing but no gesture, so it is
+ * emitted with an empty shape rather than skipped. (The census once dropped
+ * these — 68 corpus-wide, all real phrases carrying a real divisio, mostly
+ * "::" at the chant end — a hole this shared key closes.)
+ */
+export declare function cadenceKeys(rows: readonly {
+    phraseIndex: number;
+    midi: number;
+    divisio: string | null;
+}[], finalMidi?: number): CadenceKeyEvent[];
 /**
  * Detect the cadence closing each phrase. One Cadence per phrase that carries a
  * divisio. With no mode, targets/approach are still classified but no figure is

package/dist/engines/score/cadence.js

@@ -125,6 +125,84 @@ function bestFigure(observed, figures) {
     }
     return best;
 }
+// ── The corpus catalogue (CADENTIAE) ────────────────────────────────────────
+// The mining keyed tails by their last <=4 notes; the classifier reads the same
+// span out of the (longer) formula window.
+const TAIL = 4;
+/**
+ * Octave-reduce a semitone offset to [-5..+6].
+ *
+ * NOT part of the family key — kept because the folded value is still worth
+ * reporting (it is the scale DEGREE, mode-theoretically real). As a key the
+ * fold made a fifth ABOVE the final share a family with a fourth BELOW:
+ * measured over 27,985 phrase ends, 3,499 landed on @-5, of which 2,427 were
+ * really +7 and 1,072 really -5. Two opposite gestures, one key. Arrival in
+ * the key is therefore the SIGNED offset; see cadenceKeys().
+ */
+export function reduceArrival(semitones) {
+    let a = semitones % 12;
+    if (a > 6)
+        a -= 12;
+    if (a < -5)
+        a += 12;
+    return a;
+}
+/**
+ * THE cadence family key — one implementation, shared by every consumer.
+ *
+ * This once existed three times: here (keyed off the Phrase tree), in
+ * tonus-corpus `census/_shared.mjs` (keyed off flat tabula rows), and in the
+ * CADENTIAE miner (a character-for-character copy of the census one). They
+ * agreed — measured corpus-wide, 28,051 engine cadences against 27,985 census
+ * phrase ends with ZERO key disagreements — but agreement by luck across three
+ * copies is what "no second parser, no drift" forbids; hence this one shared
+ * function.
+ *
+ * Takes the FLAT shape, because that is what the census and the miner have; the
+ * engine's own detection flattens into it. A phrase end is a `phraseIndex`
+ * transition or the last row.
+ *
+ * A ONE-NOTE PHRASE IS A CADENCE — it has a landing but no gesture, so it is
+ * emitted with an empty shape rather than skipped. (The census once dropped
+ * these — 68 corpus-wide, all real phrases carrying a real divisio, mostly
+ * "::" at the chant end — a hole this shared key closes.)
+ */
+export function cadenceKeys(rows, finalMidi) {
+    if (!rows.length)
+        return [];
+    const final = finalMidi ?? rows[rows.length - 1].midi;
+    const events = [];
+    for (let i = 0; i < rows.length; i++) {
+        const next = rows[i + 1];
+        if (next && next.phraseIndex === rows[i].phraseIndex)
+            continue; // not a phrase end
+        // The last <=TAIL rows of this phrase, ending at row i.
+        const seg = [];
+        for (let j = i; j >= 0 && seg.length < TAIL && rows[j].phraseIndex === rows[i].phraseIndex; j--) {
+            seg.unshift(rows[j]);
+        }
+        const shape = seg.slice(1).map((r, k) => r.midi - seg[k].midi);
+        const arrival = seg[seg.length - 1].midi - final;
+        events.push({
+            key: `${shape.join(",")} @${arrival}`,
+            shape,
+            arrival,
+            degree: reduceArrival(arrival),
+            isFinal: rows[i].divisio === "::" || !next,
+            phraseIndex: rows[i].phraseIndex,
+        });
+    }
+    return events;
+}
+/** The chant's closing note — the reference every arrival is measured from. */
+function chantFinalMidi(phrases) {
+    for (let pi = phrases.length - 1; pi >= 0; pi--) {
+        const w = phraseFinalWindow(phrases[pi]);
+        if (w.length > 0)
+            return w[w.length - 1].midi;
+    }
+    return undefined;
+}
 /**
  * Detect the cadence closing each phrase. One Cadence per phrase that carries a
  * divisio. With no mode, targets/approach are still classified but no figure is
@@ -132,6 +210,7 @@ function bestFigure(observed, figures) {
  */
 export function detectCadences(phrases, modeData) {
     const cadences = [];
+    const finalMidi = chantFinalMidi(phrases);
     for (let pi = 0; pi < phrases.length; pi++) {
         const phrase = phrases[pi];
         if (!phrase.divisio)
@@ -162,6 +241,15 @@ export function detectCadences(phrases, modeData) {
                 }
             }
         }
+        // The corpus classification, from THE shared key function — the engine does
+        // not compute this itself. `cadenceKeys` takes flat rows, so the window is
+        // projected into that shape; one phrase in, one event out.
+        const ev = cadenceKeys(window.map((w) => ({ phraseIndex: 0, midi: w.midi, divisio: null })), finalMidi)[0];
+        const shape = ev?.shape ?? [];
+        const arrival = ev?.arrival ?? 0;
+        // A 1-note phrase has a landing but no gesture: a real cadence with an
+        // empty shape, which is why `signature` is the key rather than null.
+        const signature = ev?.key ?? null;
         cadences.push({
             phraseIndex: pi,
             divisio,
@@ -172,6 +260,14 @@ export function detectCadences(phrases, modeData) {
             steps,
             confidence: Math.round(confidence * 100) / 100,
             notes: window.map((w) => [pi, w.syllableIndex, w.noteIndex]),
+            signature,
+            shape,
+            arrival,
+            // Left null here on purpose. Detection is a pure pass over the phrase
+            // tree; the corpus catalogue is generated data, and reaching for it from
+            // inside the detector would put a baked artifact in the detection path.
+            // buildScore joins it, where MODES is already joined.
+            finality: null,
         });
     }
     return cadences;

package/dist/engines/score/emitters/accidentals.d.ts

@@ -0,0 +1,21 @@
+import type { ChantTabulaRow } from "../tabula.js";
+export type AccidentalMode = "standard" | "heji" | "cents";
+export type CentsBaseline = "pythagorean" | "et";
+/** One note's intonation mark, for the emitter to place before/above the head. */
+export interface AccidentalMark {
+    /** "glyph" → a notehead-preceding accidental; "cents" → a label floating above the staff. */
+    kind: "glyph" | "cents";
+    /** Glyph codepoint (kind "glyph") — a standard or HEJI accidental. */
+    glyph?: string;
+    /** Text label (kind "cents") — e.g. "−3.9". */
+    label?: string;
+}
+export type AccidentalGlyphSet = "modern" | "medieval";
+/**
+ * Compute the intonation mark for each tabula row, or null where none applies.
+ * Repeat-suppression (standard mode) and per-phrase pitch-class suppression
+ * (cents mode) keep the staff from being carpeted.
+ * @throws Error when `heji` is asked of a non-just (meantone) tuning.
+ */
+export declare function computeAccidentals(rows: ChantTabulaRow[], mode: AccidentalMode, centsBaseline?: CentsBaseline, glyphSet?: AccidentalGlyphSet): (AccidentalMark | null)[];
+//# sourceMappingURL=accidentals.d.ts.map

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

@@ -0,0 +1,88 @@
+import { pythagoreanCentsByPc } from "../../temper/scale.js";
+// The Pythagorean chain's ET-cents deviation per pitch class, derived from the
+// SAME E♭–G♯ chain the engine tunes with (temper/scale.ts) so baseline and
+// engine can never disagree — a hardcoded copy once drifted and broke the
+// heji channel for every flatted chant under the default tuning.
+const PYTH_BASELINE = pythagoreanCentsByPc();
+const GLYPHS_BY_SET = {
+    modern: { [-1]: "E260", 0: "E261", 1: "E262" },
+    medieval: { [-1]: "E9E0", 0: "E9E1", 1: "E9E3" },
+};
+// HEJI comma glyphs (Extended Helmholtz–Ellis, U+E2C0–). The syntonic-comma
+// arrows: one comma down / up. Higher-order commas are out of scope for 0.2.
+const HEJI_COMMA_DOWN = "E2C2"; // one syntonic comma lower
+const HEJI_COMMA_UP = "E2C7"; // one syntonic comma higher
+/** Deviation of a note from the Pythagorean chain, in cents. */
+function fromPythagorean(row) {
+    return row.offset - (PYTH_BASELINE[row.pc] ?? 0);
+}
+/**
+ * Compute the intonation mark for each tabula row, or null where none applies.
+ * Repeat-suppression (standard mode) and per-phrase pitch-class suppression
+ * (cents mode) keep the staff from being carpeted.
+ * @throws Error when `heji` is asked of a non-just (meantone) tuning.
+ */
+export function computeAccidentals(rows, mode, centsBaseline = "pythagorean", glyphSet = "modern") {
+    if (mode === "standard") {
+        // A glyph before any note whose pitch is explicitly inflected — but not on
+        // an immediately-repeated same pitch (restate only after another pitch).
+        let prevPc = null;
+        return rows.map((row) => {
+            const repeat = row.pc === prevPc;
+            prevPc = row.pc;
+            if (row.accidentalSource !== "explicit" || repeat)
+                return null;
+            // Draw the SIGN the source wrote, not this note's own alteration. In
+            // `fe(jx)cit(ih)` the flat is printed before the I while it governs J —
+            // where a sign is printed and which degree it alters are different facts.
+            // Reading `row.accidental` here drew nothing in that case, because the I
+            // is unaltered.
+            const sign = row.accidentalSign ?? row.accidental;
+            return { kind: "glyph", glyph: GLYPHS_BY_SET[glyphSet][sign] };
+        });
+    }
+    if (mode === "heji") {
+        // A tuning is just-expressible when its departures from Pythagorean are
+        // whole syntonic commas (±21.5¢). An irrational tempering (meantone) leaves
+        // fractional deviations everywhere — heji cannot notate it. Detect that.
+        const devs = rows.map(fromPythagorean);
+        const SYNTONIC = 21.506;
+        const tempered = devs.some((d) => {
+            if (Math.abs(d) < 0.5)
+                return false; // on the pure-fifth chain
+            const commas = d / SYNTONIC;
+            return Math.abs(commas - Math.round(commas)) > 0.1; // not a whole comma
+        });
+        if (tempered) {
+            throw new Error("inscriptio: accidentals \"heji\" needs a just-expressible tuning; the " +
+                "current temperament tempers by fractional commas (e.g. meantone). Use " +
+                "accidentals: \"cents\" for tempered tunings.");
+        }
+        return rows.map((row) => {
+            const d = fromPythagorean(row);
+            if (Math.abs(d) < 0.5)
+                return null; // Pythagorean baseline — no arrow
+            const commas = Math.round(d / SYNTONIC);
+            if (commas === 0)
+                return null;
+            return { kind: "glyph", glyph: commas < 0 ? HEJI_COMMA_DOWN : HEJI_COMMA_UP };
+        });
+    }
+    // cents — signed deviation label, stated once per pitch class PER PHRASE.
+    // A deviating pitch is labelled at its first appearance in each phrase and
+    // rides silently through the phrase's repeats; the next phrase restates it
+    // (the reader's memory is the phrase, and chant has no measures to carry it).
+    const seen = new Set();
+    return rows.map((row) => {
+        const value = centsBaseline === "et" ? row.offset : fromPythagorean(row);
+        if (Math.abs(value) < 0.5)
+            return null; // effectively in tune
+        const key = `${row.phraseIndex}:${row.pc}`;
+        if (seen.has(key))
+            return null; // already labelled in this phrase
+        seen.add(key);
+        const sign = value < 0 ? "−" : "+"; // real minus sign
+        return { kind: "cents", label: `${sign}${Math.abs(value).toFixed(1)}` };
+    });
+}
+//# sourceMappingURL=accidentals.js.map