tonus 0.7.0 → 0.9.0

package/docs/api/score.md

@@ -2,7 +2,7 @@
 
 `tonus.notatio` renders a chant into a score: the analyzed, tuned, and
 rhythm-classified reading of one GABC melody. The score is data: `phrases`,
-`tabula`, `prosody`, `cadences`, `modulations`, and `imprint`. The
+`tabula`, `metrics`, `cadences`, `modulations`, and `imprint`. The
 standalone `tonus.inscriptio(score)` draws it to SVG.
 
 - [Score](#score)
@@ -15,7 +15,7 @@ standalone `tonus.inscriptio(score)` draws it to SVG.
     - [theme — faces and ink](#theme--faces-and-ink)
     - [The analysis tracks](#the-analysis-tracks)
   - [The imprint](#the-imprint)
-  - [Prosody](#prosody)
+  - [Metrics](#metrics)
   - [Cadences](#cadences)
     - [One spine, two annotations](#one-spine-two-annotations)
     - [`finality` — how often this family closes](#finality--how-often-this-family-closes)
@@ -54,7 +54,7 @@ notation, signs of punctuation rather than measure:
 | `::`    | divisio finalis (double bar) |
 
 This hierarchy is read three ways in the engine, each weighting the bars for its
-own end: an analytic cadence weight (prosody), a phrasing strength (which zeroes
+own end: an analytic cadence weight (metrics), a phrasing strength (which zeroes
 the virgula), and a rest duration (the divisio's pause length). Each weighting
 is documented at its table in the code.
 
@@ -64,7 +64,7 @@ interface Score {
   phrases: Phrase[];
   errors: ParseError[];
   tabula: ChantTabulaRow[];
-  prosody: Prosody;
+  metrics: Metrics;
   cadences: Cadence[];
   modulations: Modulation[];
   imprint: Imprint;
@@ -83,11 +83,20 @@ interface Syllable {
   lyric: string;
   runs?: LyricRun[];        // styled spans, present only when GABC markup styled this syllable
   notes: Note[];
-  neume: Neume;
+  neume: Neume;             // the syllable read as ONE figure
+  neumes: Neume[];          // its figures, as GABC groups them, each classified
   melisma: number;          // notes on this syllable (1 = syllabic, >1 melismatic)
 }
 ```
 
+A syllable carries neumes rather than being one. GABC marks the figures with
+`!`, `/` and `//`, and `neumes` names each; `neume` reads the whole syllable as
+a single figure, which for a melisma of several is usually `compound`. A
+syllable of one figure reports the same shape both ways. The salicus is the
+exception and reports at syllable scope: its rule reads the oriscus on the
+next-to-last note of an ascent, and the scribe may break the figure between
+that oriscus and the summit.
+
 GABC's lyric markup is decoded at parse, so `lyric` is always clean display
 text: the `<sp>` shortcuts arrive as real characters (`<sp>V/</sp>` → ℣,
 `<sp>R/</sp>` → ℟, `<sp>+</sp>` → the flex †, `<sp>'ae</sp>` → ǽ, the
@@ -504,20 +513,27 @@ between systems, the notehead calibration against the staff, and the line-end
 custos are constants. The custos appears whenever a system wraps, as it does in
 a chant book.
 
-**The geometry contract (public API).** `geometry` is one `NoteGeometry` per note,
-in tabula order — the interface analysis _tracks_ build on, so they place marks
-by index and coordinate instead of scraping the SVG. The library's own tracks
-(below) consume exactly these anchors; a custom track downstream does the same:
+**The geometry contract (public API).** `geometry` is one `NoteGeometry` per
+note, in tabula order, so `geometry[i]` and `tabula[i]` are the same note two
+ways. It says where each note landed on the drawn page, so a caller can put a
+playhead, a selection, or an overlay against a note without scraping the SVG.
 
 ```ts
 interface NoteGeometry {
-  phraseIndex: number; syllableIndex: number; neumeGroup: number; noteIndex: number;
+  phraseIndex: number; syllableIndex: number; neumeGroup: number;
+  noteIndex: number;   // position within the SYLLABLE — the tabula's own index
+  neumeIndex: number;  // position within the neume FIGURE
   system: number;      // which wrapped system the note landed in
   x: number; y: number; // notehead anchor, svg user units
+  inkLeft: number;      // the figure's measured ink extent. `x` is its LEFT
+  inkRight: number;     //   edge, so a mark that spans notes reaches for these
   systemY: number;      // the system's top offset within the svg
 }
 ```
 
+`y` is already absolute on the canvas; `systemY` reports which system a note
+is in, not an offset to add.
+
 ### The analysis tracks
 
 `tracks` draws an analysis band beneath every system. Any track rides either
@@ -536,74 +552,70 @@ tonus.inscriptio(score, { width: 680, tracks: ["chironomia", "tonarium"] });
 tonus.inscriptio(score, { width: 680, tracks: ["prosodia", "chironomia", "tonarium"] });
 ```
 
-The conventional pairing is the chironomia under `quadrata` and the tonarium
-under `moderna`; the prosodia, reading the text rather than the notation,
-rides either as naturally. The renderer enforces none of it.
-
-Requesting several stacks them in a fixed order — the prosodia first, directly
-under the lyric line it reads; the chironomia next; the tonarium below —
-whichever order they are asked for, and the page grows by the sum of the
-bands.
-
-- **`"prosodia"`** — how the melody treats the word, in two lanes. The upper
-  lane draws one **tent per word** — the hairpin pair's top edge, dynamics'
-  own mark for swell and release — its apex over the accented syllable, with
-  the accent's landing at the peak in the liturgical red: a **filled dot**
-  when the accent lands arsic (struck), an **open ring** when it lands thetic
-  (deferred). Accented words rise past the lane's single rule; unaccented
-  words crest on it. The lower lane is a fence on a rail, one mark per
-  syllable by how the melody treats it: a spoken syllable stands as a stem
-  (height, its notes), a syllable **recited on the tenor lies flat** — a
-  short dash floating above the rail — and a **melisma of four notes or more
-  becomes a block** as wide as its real extent and as tall as its count
-  (counts of eight or more print inside). Connected melismas join into one
-  ridge, each block's top sloping toward its neighbours, the line between
-  them crossing the gaps. A divisio drops a hairline through both lanes.
-  Accents are the book's written accents (the GABC accented vowels) — the
-  track derives none.
-- **`"chironomia"`** — the conducting hand as one continuous line:
-  arsic beats crest, thetic beats trough, single-note theses pass through
-  shallow, and the hand picks up between close arses in a small backward loop
-  [biblio: carroll-chironomy]. Pressure is the stroke's _weight_: each note's
-  `velocity` (the `accentus` shaping) becomes nib width over solid ink, so the
-  line presses where the voice does. Pierik letters (A · T · PT) name the
-  beats — the incise's rhythmic shape is read straight off them.
-- **`"tonarium"`** — the melodic-analysis lane, named for the book
-  that catalogued chants by mode. Four rails — the maneriae finals ladder, D on
-  the bottom (categories, not pitches) — carry the **mode line** in the
-  liturgical red: the governing mode of each phrase, its numeral above
-  (authentic-vs-plagal lives in the numeral). A modulation of kind
-  `"inflection"` steps the line solid; a `"transposition"` (the affinal frame
-  read as displacement) draws dashed. Through the rails runs the melody itself,
-  compressed to the chant's ambitus and wearing the same pressure grammar, a
-  lighter stratum — context, not message.
-  A **cadence is the melody's own ending re-inked black**: the same curve at
-  the same width turns pure black across the cadential figure and lands on a
-  terminal node — filled when the family's measured `finality` closes, open
-  when it suspends. Beneath the node, centred on it, sits the family's
-  **in-mode share**: `"3.9%"`, how often this close ends a chant in this
-  chant's mode — the frequency a singer actually meets it at. Where the chant
-  has no mode, or the family has too few occurrences in it to divide honestly,
-  the label falls back to the plain corpus share, which is the same kind of
-  number.
-
-  **Every inked cadence carries a label.** A close that does not join
-  [`CADENTIAE`](index.md#the-appendix) at all reads `"rara"` — not a gap but a
-  measurement: the catalogue holds the 110 families above fifty corpus
-  occurrences, so failing to join means rarer than anything it records. About
-  44% of cadences land there.
-
-  `rara` is a word rather than a number, so it is not read on the percentage
-  scale beside it.
-
-  The lift rides the group as `data-lift` for a caller who wants distinctiveness
-  rather than frequency, beside `data-cadentia` — the family key, which is the
-  join back to [`CADENTIAE`](index.md#the-appendix) and the provenance a margin
-  gloss can print. Crowded labels dodge to a second row.
+Several stack in a fixed order whatever order they are asked for: prosodia
+first, directly under the lyric line it reads; chironomia next; tonarium
+below. The page grows by the sum of the bands. The conventional pairing is the
+chironomia under `quadrata` and the tonarium under `moderna`; the renderer
+enforces none of it.
+
+**`"prosodia"`** draws how the melody treats the word, in two lanes.
+
+| mark | means |
+| --- | --- |
+| tent, one per word | apex over the accented syllable; accented words rise past the lane's rule, unaccented crest on it |
+| filled dot at the peak | the accent lands **arsic** (struck) |
+| open ring at the peak | the accent lands **thetic** (deferred) |
+| stem on the rail | a spoken syllable; height is its note count |
+| flat dash above the rail | the syllable is **recited on the tenor** |
+| block | a **melisma of 4+ notes**, as wide as its extent, as tall as its count (8+ prints the count inside) |
+| hairline through both lanes | a divisio |
+
+Connected melismas join into one ridge, blocks sloping toward their
+neighbours. Accents are the book's written accents (the GABC accented
+vowels); the track derives none.
+
+**`"chironomia"`** draws the conducting hand as one continuous line. Arsic
+beats crest, thetic beats trough, single-note theses pass through shallow, and
+the hand picks up between close arses in a small backward loop
+[biblio: carroll-chironomy]. Each note's `velocity` (the `accentus` shaping)
+becomes nib width, so the line presses where the voice does. Pierik letters
+(A · T · PT) name the beats.
+
+**`"tonarium"`** is the melodic-analysis lane, named for the book that
+catalogued chants by mode. Four rails carry the maneriae finals ladder, D on
+the bottom (categories, not pitches). Through them runs the melody itself,
+compressed to the chant's ambitus at a lighter stratum: context, not message.
+
+| mark | means |
+| --- | --- |
+| red line + numeral | the governing **mode** of each phrase (authentic vs plagal lives in the numeral) |
+| line steps solid | a modulation of kind `"inflection"` |
+| line dashed | a `"transposition"` (the affinal frame read as displacement) |
+| melody re-inked black | a **cadence**: the same curve at the same width, turned pure black across the figure |
+| filled terminal node | the family's measured `finality` **closes** |
+| open terminal node | it **suspends** |
+
+A wrapped cadence draws its node and label once, in the system holding the
+figure's last note.
+
+Every inked cadence carries a label beneath its node: the family's **in-mode
+share** (`"3.9%"`), how often this close ends a chant in this chant's mode.
+Where the chant has no mode, or the family has too few occurrences in it to
+divide, it falls back to the plain corpus share. A close that joins
+no [`CADENTIAE`](index.md#the-appendix) family reads **`rara`**. That is a
+measurement rather than a gap: the catalogue holds the 110 families above
+fifty corpus occurrences, so failing to join means rarer than anything it
+records. About 43% of the corpus's cadences join no family, though of the
+labels a page prints, about a third read `rara`. It is a word, not a number, so
+it is not read on the percentage scale beside it.
+
+Each cadence group carries `data-cadentia` (the family key, which joins back
+to [`CADENTIAE`](index.md#the-appendix) and carries the provenance a margin
+gloss can print) and `data-lift` (distinctiveness, for a caller who wants it
+rather than frequency). Crowded labels dodge to a second row.
 
 Everywhere, confidence is opacity, and a claim below confidence 0.45 draws
-nothing — weak claims are not inked. Every mark sits under the notation that
-would falsify it.
+nothing. Every mark sits under the notation that would falsify it.
 
 ## The imprint
 
@@ -665,16 +677,23 @@ interface ModalAffinity {
 }
 ```
 
-## Prosody
+## Metrics
+
+`score.metrics` measures the chant's shape — counts, range, melisma, melodic
+motion, contour, tessitura, rhythm, cadence. It is chant-specific; `Harmony`
+has no metrics.
+
+```js
+tonus.notatio(puerNatusEst).metrics;
+// { noteCount: 159, syllableCount: 78, phraseCount: 10,
+//   ambitus: 10, melismaRatio: 2.04, tessitura: 5.2, … }
+```
 
-`score.prosody` measures the chant's shape — counts, range, melisma,
-melodic motion, contour, tessitura, rhythm, cadence. It is chant-specific;
-`Harmony` has no prosody. For _Puer natus est_: ambitus 10 semitones, melisma
-ratio 2.04 notes per syllable, tessitura ~5 semitones above the final, a near-
-perfect melodic arch, mostly stepwise motion (leap rate ~5%).
+_Puer natus est_ spans ten semitones, sings a little over two notes to the
+syllable, and sits about five semitones above its final.
 
 ```ts
-interface Prosody {
+interface Metrics {
   noteCount: number;
   syllableCount: number;
   phraseCount: number;
@@ -691,12 +710,19 @@ interface Prosody {
   cadenceWeight: number;
   cadenceDistribution: CadenceDistribution;
 }
+```
 
-interface IntervalStats {
-  histogram: Record<number, number>; // signed semitone interval → count
-  maxLeap: number;                   // largest absolute interval (semitones)
-  leapRate: number;                  // fraction of motions that are leaps (a 4th+)
-  motus: { step: number; skip: number; leap: number }; // 1–2 st / 3–4 / 5+
+The five composite fields each answer one question about the chant.
+
+**Where the melody sits, and the shape it traces.** `noteRange` is the plain
+compass; `arcus` reads the classic chant arch — rise to a peak, return to the
+final.
+
+```ts
+interface NoteRange {
+  min: number;   // lowest note MIDI
+  max: number;   // highest note MIDI
+  span: number;  // max − min, in semitones (this is `ambitus`)
 }
 
 interface Arcus {
@@ -705,32 +731,59 @@ interface Arcus {
   final: number;     // last note MIDI
   archIndex: number; // signed: +1 rises and returns, 0 flat/monotonic
 }
+```
 
-interface NoteRange {
-  min: number;
-  max: number;
-  span: number;
+**How the melody moves.** Chant is overwhelmingly stepwise, so `motus` sorts
+every adjacent within-phrase motion by size — the three names are the tradition's
+own, and a chant whose skips and leaps outnumber its steps is unusual enough to
+question.
+
+```ts
+interface IntervalStats {
+  histogram: Record<number, number>; // signed semitone interval → count
+  maxLeap: number;                   // largest absolute interval (semitones)
+  leapRate: number;                  // fraction of motions that are leaps
+  motus: { step: number; skip: number; leap: number };
 }
+```
 
+| motion | semitones | interval          |
+| ------ | --------- | ----------------- |
+| `step` | 1–2       | a second          |
+| `skip` | 3–4       | a third           |
+| `leap` | 5+        | a fourth or wider |
+
+**How it is rhythmed.** Arsis and thesis across the score, and the size of the
+compound beats they group into.
+
+```ts
 interface RhythmicProfile {
-  arsic: number; // count of arsic notes across the score
-  thetic: number; // count of thetic notes across the score
+  arsic: number;        // arsic notes across the score
+  thetic: number;       // thetic notes across the score
   avgGroupSize: number; // mean notes per compound beat
   maxGroupSize: number; // largest compound beat observed
 }
-
-interface CadenceDistribution {
-  comma: number; // divisio minima
-  tick: number; // virgula
-  semicolon: number; // divisio minor
-  colon: number; // divisio maior
-  doubleBar: number; // divisio finalis
-}
 ```
 
+**How it comes to rest.** `cadenceDistribution` counts the divisiones the chant
+writes, one field per rung of the bar-line hierarchy. `cadenceWeight` sums the
+same bars by that rank, so a chant closing on full bars weighs more than one
+broken by breaths.
+
+| field       | GABC    | divisio         | weight |
+| ----------- | ------- | --------------- | -----: |
+| `tick`      | `` ` `` | virgula         |   0.25 |
+| `comma`     | `,`     | divisio minima  |    0.5 |
+| `semicolon` | `;`     | divisio minor   |   0.75 |
+| `colon`     | `:`     | divisio maior   |    1.0 |
+| `doubleBar` | `::`    | divisio finalis |    1.5 |
+
+This table is canonical — `metrics.ts` cites it rather than restating the
+weights.
+
 ## Cadences
 
-`score.cadences` names the melodic close of each phrase — where prosody
+`score.cadences` names the melodic close of each phrase — where metrics
 only counts the divisio bars, this identifies the figure. One `Cadence` per
 phrase-ending divisio: its resolution `target`, the melodic `approach`, and the
 `divisio` that tells medial from final (the double bar `::` is the final
@@ -756,9 +809,9 @@ this before deciding which field to use:
   so it is the one of the two that speaks about **medial** cadences.
 
 Measured over the cadences `notatio` reports across the shipped corpus — about
-20,500 of them — roughly 43% carry a formula, 56% join the catalogue, 31% carry
-both, and 44% fall outside it. Neither is derivable from the other, because the
-signature is mode-blind and the formula is mode-relative.
+26,800 of them — roughly 43% carry a formula, 57% join the catalogue, and 31%
+carry both, so about a third carry neither. Neither is derivable from the
+other, because the signature is mode-blind and the formula is mode-relative.
 
 ### `finality` — how often this family closes
 

package/docs/api/tuning.md

@@ -267,15 +267,23 @@ t.neuma(["D4", "F4", "E4"]);
 
 Shapes that match no simple figure classify as `"compound"`.
 
-| `shape`     | figure             | `shape`              | figure                      |
-| ----------- | ------------------ | -------------------- | --------------------------- |
-| `punctum`   | a single note      | `torculus resupinus` | torculus, then rising       |
-| `pes`       | two notes, rising  | `porrectus flexus`   | porrectus, then falling     |
-| `clivis`    | two notes, falling | `scandicus flexus`   | scandicus, then falling     |
-| `torculus`  | three: up, down    | `climacus resupinus` | climacus, then rising       |
-| `porrectus` | three: down, up    | `pes subpunctis`     | pes, then descending points |
-| `scandicus` | three, rising      | `compound`           | any figure not above        |
-| `climacus`  | three, falling     |                      |                             |
+| `shape`     | figure             | `shape`                | figure                          |
+| ----------- | ------------------ | ---------------------- | ------------------------------- |
+| `punctum`   | a single note      | `torculus resupinus`   | torculus, then rising           |
+| `pes`       | two notes, rising  | `porrectus flexus`     | porrectus, then falling         |
+| `clivis`    | two notes, falling | `scandicus flexus`     | scandicus, then falling         |
+| `torculus`  | three: up, down    | `climacus resupinus`   | climacus, then rising           |
+| `porrectus` | three: down, up    | `pes subpunctis`       | pes, then descending points     |
+| `scandicus` | three, rising      | `scandicus subpunctis` | two rising, then descending     |
+| `climacus`  | three, falling     | `salicus`              | rising, next-to-last an oriscus |
+
+The repercussive figures restate a pitch rather than leave it.
+
+| `shape`            | figure              | `shape`         | figure                 |
+| ------------------ | ------------------- | --------------- | ---------------------- |
+| `distropha`        | two on one pitch    | `pressus`       | restated, then falling |
+| `tristropha`       | three on one pitch  | `pressus maior` | falling in, then out   |
+| `tristropha flexa` | three, then falling | `compound`      | any figure not above   |
 
 ```ts
 interface Neume {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tonus",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Medieval music analysis and performance: GABC plainchant exports, liturgical calendar, tuning systems, ephemeris, and the harmony of the spheres",
   "author": "Jeffrey Pierce <jeffrey@jeffreypierce.net>",
@@ -9,7 +9,7 @@
     "type": "git",
     "url": "git+https://github.com/jeffreypierce/tonus.git"
   },
-  "homepage": "https://jeffreypierce.github.io/tonus/",
+  "homepage": "https://jeffreypierce.github.io/orreliquum/",
   "bugs": "https://github.com/jeffreypierce/tonus/issues",
   "keywords": [
     "gregorian-chant",