tonus 0.1.8 → 0.5.0

package/LICENSE

@@ -1,29 +1,133 @@
-MIT License
-
-Copyright (c) 2026 Jeffrey Pierce
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
----
-
-Data provenance: the chant corpora derive from GregoBase
-(https://gregobase.selapa.net/); the liturgical calendar, propers, office,
-and psalter derive from the Divinum Officium project
-(https://github.com/DivinumOfficium/divinum-officium); orbital elements from
-JPL/NASA (Standish 1992, DE430). See BIBLIOGRAPHY.md for full attribution.
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+Required Notice: Copyright (c) 2026 Jeffrey Pierce (jeffreypierce.net)

package/README.md

@@ -1,111 +1,134 @@
 # tonus
 
-**tonus** is a medieval music and cosmology library. It covers:
-
-- pitch, tuning, hexachords, and the eight church modes
-- the liturgical calendar, the feast of the day, and mass selection
-- the chant repertoire in GABC: propers, ordinary, office, and psalm tones
-- chant rhythm and performance shaping, rendered to MIDI or MusicXML
-- planetary positions voiced as tuned pitch across the classical theorists' "harmony of the spheres"
-
-**tonus** is implemented in TypeScript and its API is a single namespace of methods. Every result is deterministic: the same
-query returns the same answer, computed locally from data that ships with
-the package, with no network calls.
-
-## Install
+**tonus** is a JavaScript library for medieval music theory and chant
+analysis. It carries the Gregorian repertoire and the theory it was built on:
+it resolves what any day calls for, tunes chant in the ratios it was sung in,
+parses and draws the notation, voices the planets as pitch, and measures each
+chant in comparison.
+
+Everything is computed locally and deterministically: the same question always
+returns the same answer, from data that ships inside the package, with no network
+calls and no runtime dependencies.
+
+## What it covers
+
+- **Pitch and tuning.** The medieval pitch world: Pythagorean and meantone
+  temperaments, just intonation and custom scales, the Guidonian gamut and hand,
+  hexachords and their mutations, and interval analysis by name.
+- **The eight modes.** Each church mode with its final, dominant, ambitus, and
+  ethos, and the psalm tones that go with them.
+- **The liturgical calendar.** The Tridentine calendar of any year, resolved
+  against Easter (by the Julian or the Gregorian computus), with each feast's
+  rank, grade, and season.
+- **The chant repertoire.** About 2,200 chants across ten books (nine Solesmes
+  editions and the Nocturnale Romanum night office), in
+  [GABC](https://gregorio-project.github.io/) notation: Mass propers, the Kyriale,
+  the Office hours, the psalter, and the Matins nocturns, retrievable by feast,
+  season, mode, or office.
+- **Rhythm and notation.** GABC parsed into phrases, syllables, and tuned notes,
+  shaped by the Solesmes arsis/thesis rhythm, with an analytic fingerprint of a
+  chant's melodic character, and drawn to a square-note or modern staff.
+- **The harmony of the spheres.** An ephemeris of the classical planets, voiced
+  as tuned pitch after Boethius, Nicomachus, Pliny, and Ptolemy.
+- **The census.** Every shipped chant measured against the corpus that holds
+  it: how typical it is, where it is unusual, and its nearest neighbours by
+  melodic shape.
+
+## The ideas behind it
+
+Boethius's _De institutione musica_ carried Greek theory into the Latin
+Middle Ages, and it treats music as a branch of number, beside arithmetic,
+geometry, and astronomy. Its music runs from the audible to the inaudible:
+voices and instruments (_musica instrumentalis_), body and soul (_musica
+humana_), the turning cosmos (_musica mundana_). Chant was composed and
+copied inside that frame: pitch was ratio, the modes a received order, the
+heavens harmonic proportion.
+
+tonus takes those claims literally enough to compute them. It tunes pitch in
+the Pythagorean ratios of the treatises. It reads the calendar as the
+retrieval index it was for a millennium. It follows the Solesmes rhythm of
+arsis and thesis. And it computes _musica mundana_ as sounding pitch. Where
+the sources run out or contradict one another, tonus makes an editorial call
+and records it in the code.
+
+tonus is an instrument for study. It treats this repertoire as musical and
+historical material to be measured, queried, and understood; what it models is
+the sound and its structure.
+
+## Sources
+
+tonus is built on primary and scholarly sources, and it names them wherever it
+makes a choice. The chant and calendar data are the Solesmes editions, by way of
+[GregoBase](https://gregobase.selapa.net/),
+[Divinum Officium](https://divinumofficium.com/), and the community _Nocturnale
+Romanum_. The rhythm follows Mocquereau, Gajard, Suñol, and Daniel Saulnier; the
+modes and cadences follow Rockstro's _Grove_ article, Niedermeyer & d'Ortigue,
+and Apel; the tuning follows Boethius's _De institutione musica_ and Ptolemy's
+_Harmonics_; the notation is engraved in Daniel Spreadbury's
+[Bravura](https://github.com/steinbergmedia/bravura), the reference font for the
+SMuFL standard; the planetary doctrines follow Godwin's sourcebooks of the
+Pythagorean tradition.
+
+Every figure is cited in the code beside what it explains. The complete list is
+[BIBLIOGRAPHY.md](BIBLIOGRAPHY.md).
+
+## Example
 
 ```sh
 npm install tonus
 ```
 
-ESM only. Node ≥ 20; works in the browser through a bundler. No runtime
-dependencies. Roughly 5,500 chants and the full 642-entry calendar ship in
-the package — 6.5 MB unpacked, 1.5 MB packed.
-
-## Documentation
-
-One page per engine, in dependency order. Each page states its rules, then its theory and historical context, then its sources.
-
-- **[Index](docs/index.md)** — Table of contents and conventions.
-- **[Tuning](docs/tuning.md)** — `temperamentum`. The medieval pitch system:
-  temperaments, Guidonian gamut and hand,
-  hexachordal solmization and mutations, eight modes, and psalm
-  tones. Depends on nothing else in the library.
-- **[Calendar](docs/calendar.md)** — `festum`, `pascha`. The Tridentine
-  liturgical calendar resolved against dual-computus Easter: feasts with
-  their authentic ranks, grades, and seasons, and the movable anchors of
-  any year.
-- **[Chant](docs/chant.md)** — `cantus`, `proprium`, `ordinarium`,
-  `officium`, `psalmus`. The Solesmes books in GABC: Mass propers, the
-  Kyriale, the Office hours, the psalter.
-- **[Score](docs/score.md)** — `notatio`. GABC into tuned notes: phrases,
-  syllables, Solesmes arsis/thesis rhythm, prosody, the analytic imprint.
-- **[Heavens](docs/heavens.md)** — `caelum`, `harmonia`. An ephemeris
-  computed from JPL orbital elements, voiced through the planetary
-  doctrines of Boethius, Nicomachus, Pliny, and Ptolemy.
-
-These pages are the middle of a three-level ladder: the API docs here link down
-into the code, where the full theory, provenance, and editorial reasoning live in
-comments beside what they explain. Read as deep as you care to. Sources for
-concepts, scholarship, and data are listed in
-[BIBLIOGRAPHY.md](BIBLIOGRAPHY.md); where sources disagree or run out, **tonus**
-makes an editorial call, recorded in the code and glossed in the page's Theory &
-Context section.
-
-## The tuning engine
-
-The tuning engine is self-contained; every other engine resolves its pitches
-through it.
-
 ```js
 import tonus from "tonus";
 
-const t = tonus.temperamentum({ mode: 1 }); // Pythagorean, mode 1
-
-t.nota("D4");
-// 293.33 Hz — the final of mode 1, tuned through pure fifths
+// Build a tuning: Pythagorean, set to mode 1.
+const t = tonus.temperamentum({ mode: 1 });
+t.nota("D4"); // 293.33 Hz, the final of mode 1, through pure fifths
+t.gradus("D4"); // "Delasolre": RE of the natural hexachord, the finalis
 
-t.gradus("D4");
-// Delasolre: RE of the natural hexachord, role "finalis",
-// middle finger, base joint, on the Guidonian hand
-
-t.intervallum("D4", "A4");
-// Quinta (alias Diapente), perfect — final to tenor
-
-t.tonus();
-// psalm tone 1, differentia 1g:
-// intonatio F3–A3–C4, mediatio C4–A3–G3–A3, terminatio C4–A3–G3–A3–G3
-```
-
-## The liturgical stack
-
-The remaining engines compose:
-
-```js
+// Ask the calendar for a day, then pull the chant that belongs to it.
 const [feast] = tonus.festum({ date: new Date("2026-12-25") });
-// nomen: "In Nativitate Domini", ritus: "Duplex I classis",
-// grade: "duplex-i", tempus: "Tempus Nativitatis"
-
+// → "In Nativitate Domini", a Duplex I classis feast of Christmastide
 const [introit] = tonus.proprium({ feast, office: "in" });
-// "Puer natus est", mode 7, GABC from the Liber Usualis
+// → "Puer natus est", mode 7, from the Liber Usualis
 
+// Turn the chant into tuned, rhythmicized notes.
 const score = tonus.notatio(introit, { temperamentum: t });
-// phrases, syllables, tuned pitches, arsis/thesis rhythm, prosody, imprint
 
+// And voice the Christmas sky as pitch, after Boethius.
 const harmony = tonus.harmonia(tonus.caelum({ date: feast.date }));
-// each visible planet voiced as pitch and Greek vowel, after Boethius
 ```
 
-## Development
+The objects each call returns (`feast`, `t`) pass straight back into the next as
+filters.
+
+## Documentation
+
+The **[documentation index](docs/api/index.md)** is the technical center: the full
+API, the conventions, the error contract, and the code standards. From there,
+one page per engine, in dependency order:
+[tuning](docs/api/tuning.md), [calendar](docs/api/calendar.md), [chant](docs/api/chant.md),
+[score](docs/api/score.md), [heavens](docs/api/heavens.md), and
+[census](docs/api/census.md).
+
+## Install and run
+
+ESM only. Node ≥ 20; works in the browser through a bundler. No runtime
+dependencies. About 2,200 chants and the 650-entry calendar ship in the
+package.
 
 ```sh
 npm test          # builds and runs the suite (node --test)
 ```
 
-The data files in `src/data/` are generated by a separate extraction
-pipeline (tonus-corpus). Edits happen there, not here.
+The data files in `src/data/` are generated by a separate extraction pipeline
+(tonus-corpus). Edits happen there, not here.
 
 ## License
 
-[MIT](LICENSE). Chant and liturgical data derive from GregoBase and Divinum
+[PolyForm Noncommercial 1.0.0](LICENSE): free to use, study, modify, and
+share for any noncommercial purpose — personal projects, research,
+education, art, religious observance. Commercial use requires permission
+from the author. Versions through 0.1.x were published under MIT and
+remain so. Chant and liturgical data derive from GregoBase and Divinum
 Officium; see [BIBLIOGRAPHY.md](BIBLIOGRAPHY.md) for full attribution.