tonus 0.1.8 → 0.6.1

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,138 @@
 # tonus
 
-**tonus** is a medieval music and cosmology library. It covers:
+**tonus** is a JavaScript library for medieval music theory and chant
+analysis. It carries the Gregorian repertoire and the concepts it was built on.
 
-- 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"
+It tunes to scales medieval singers would have used, tells you which chants
+belong to which day and returns analysis and notation, and calculates the
+_music of the spheres_ proposed by Pythagoras, Boethius, and more as real
+intervals.
 
-**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.
+**[Interactive demo →](https://jeffreypierce.github.io/tonus/)**
 
-## Install
+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.
 
 ```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
-
-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:
+// 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
 
-```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, then draw it.
 const score = tonus.notatio(introit, { temperamentum: t });
-// phrases, syllables, tuned pitches, arsis/thesis rhythm, prosody, imprint
+const { svg, geometry } = tonus.inscriptio(score, { width: 680 });
 
+// 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.
+
+## The API
+
+Fourteen methods, each named for what it returns.
+
+| Method                        | Returns                                                           |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `festum({ date })`            | the feasts of a day, with rank, grade, and season                 |
+| `pascha(year)`                | Easter and the movable feasts reckoned from it                    |
+| `cantus({ … })`               | chants by id, incipit, mode, office, or source                    |
+| `proprium({ feast, office })` | the Mass propers for a feast                                      |
+| `ordinarium({ … })`           | the Kyriale — the Mass ordinary settings                          |
+| `officium({ feast, hora })`   | an Office hour, psalms and antiphons in order                     |
+| `psalmus({ psalm })`          | a psalm, pointed for its tone                                     |
+| `corpus()`                    | what ships: counts by book, genus, and mode                       |
+| `census({ id })`              | one chant measured against the corpus                             |
+| `temperamentum({ … })`        | a tuning — `nota`, `gradus`, `modus`, `intervallum`               |
+| `notatio(chant)`              | GABC parsed to phrases, syllables, and tuned notes                |
+| `inscriptio(score)`           | `{ svg, geometry }` — the score drawn, and where each note landed |
+| `caelum({ date })`            | the classical planets at a moment                                 |
+| `harmonia(caelum)`            | those positions voiced as pitch                                   |
+
+**Tuning** covers Pythagorean and meantone temperaments, just intonation and
+custom scales, the Guidonian gamut and hand, hexachords and their mutations,
+and intervals named as the treatises name them. Each of the eight modes carries
+its final, dominant, ambitus, and ethos, with its psalm tones.
+
+**The calendar** is Tridentine, resolved against Easter by
+the Julian or the Gregorian computus.
+
+**The repertoire** is 2,187 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.
+
+**Scores** are shaped by the Solesmes arsis/thesis rhythm, fingerprinted for
+melodic character, and drawn to a square-note or modern staff.
+
+## Concepts
+
+Boethius treated music as a branch of number theory, and divided it into the
+audible and the inaudible: instruments and voices, body and soul, the turning
+cosmos. Chant
+was composed inside that frame: pitch was ratio, the modes a received order,
+the heavens harmonic proportion. tonus takes those claims literally enough to
+compute them, which is why tuning is ratio arithmetic, why the calendar is a
+retrieval index, and why there is an ephemeris in a chant library at all.
+
+Where the sources run out or contradict one another, tonus makes an editorial
+call and records it in the code.
+
+## 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. The 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.
+
+## Sources
+
+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 notation is engraved in Daniel Spreadbury's
+[Bravura](https://github.com/steinbergmedia/bravura), the reference font for the
+SMuFL standard. Behind the rest stand Mocquereau and Suñol on rhythm, Rockstro
+and Apel on the modes, Boethius and Ptolemy on tuning, and Godwin on the
+Pythagorean planets.
+
+Every figure is cited in the code beside what it explains, and
+[BIBLIOGRAPHY.md](BIBLIOGRAPHY.md) is the complete list.
 
 ## 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.