@libraz/libcantus 1.0.0 → 1.1.0

package/dist/generate/index.d.ts

@@ -1,14 +1,15 @@
-import { a as Articulation, g as NoteEvent, I as IntervalLike } from '../index-B9MNZboQ.js';
-export { b as IntervalQualityLabel, d as KeyScale, S as SpelledInterval } from '../index-B9MNZboQ.js';
-import { e as ChordSegment, c as ChordLike, K as KeyLike } from '../index-szBv3496.js';
-export { b as ChordData, d as ChordQuality, g as ChordSpan, j as ChordToneRole, l as PitchSpelling, m as ProfileWeights } from '../index-szBv3496.js';
-export { B as BorrowedSource, e as ChordTimeline, H as HarmonicFunction } from '../index-Chbst3Jx.js';
-import { f as StringedProfile, P as PercussionProfile, c as Limb } from '../positional-Cptlj-xs.js';
-export { I as InstrumentProfile, a as InstrumentProfileCommon, d as PositionalRng, S as SeedPath } from '../positional-Cptlj-xs.js';
-import { T as TimeSignature } from '../index-Cj49F892.js';
-export { H as HarmonyRole } from '../index-CunYKLiu.js';
-import { a3 as Vocabulary, s as GridEvent, r as Genre, q as GenerationContextInput, m as DrumStyle, $ as Section, n as DrumVoice, t as GrooveFeel, k as DrumHit } from '../index-CgHqxdps.js';
-export { B as BAR_STEPS, a as BASS_STYLES, b as BEAT_STEPS, c as BORROWED_DEGREES, d as BassLineOptions, e as BassSegment, f as BassStyle, g as BorrowedChord, C as Complexity, h as CounterMelodyOptions, D as DRUM_NOTES, i as DeformOptions, j as Draw, l as DrumRole, o as DrumsOptions, E as EuclideanKick, G as GENRES, p as GenerationContext, u as GrooveSlot, v as GrooveStyle, w as GrooveTemplate, H as HarmonizeOptions, x as HarmonizePlacement, y as HarmonizeResult, z as HumanizeOptions, M as MelodyNote, A as MotifCell, F as MotifContour, I as MotifNote, J as MotifOptions, K as MotifTransform, O as ORNAMENT_STYLES, L as OrnamentOptions, N as OrnamentStyle, P as PROVENANCE_BASES, Q as ProgFunction, R as ProgStyle, S as ProgressionDegree, T as ProgressionOptions, U as ProgressionPreset, V as Provenance, W as ProvenanceBasis, X as ResolvedContext, Y as RhythmEvent, Z as RhythmOptions, _ as STEP_BEATS, a0 as SubstituteOptions, a1 as Substitution, a2 as SubstitutionType, a4 as VocabularyQuery, a5 as applyGrooveTemplate, a6 as assertVocabulary, a7 as deform, a8 as developMotif, a9 as double, aa as doubleTime, ab as drumVoiceOf, ac as extractGrooveTemplate, ad as fitsQuery, ae as generateBassLine, af as generateCounterMelody, ag as generateDrums, ah as generateMotif, ai as generateProgression, aj as generateRhythm, ak as gridMetricWeight, al as halfTime, am as harmonizeMelody, an as humanize, ao as mergeVocabulary, ap as modalInterchangePalette, aq as motifToNoteEvents, ar as negativeHarmonyMirror, as as onsetWeightCurve, at as ornament, au as ornamentBy, av as pickProgressionPreset, aw as pickVocabulary, ax as progressions, ay as progressionsByStyle, az as resolveContext, aA as rhythmDensity, aB as rhythmToNoteEvents, aC as selectVocabulary, aD as substituteChord, aE as syncopate, aF as thin, aG as transformMotif, aH as vocabularyOfKind, aI as withinCeiling } from '../index-CgHqxdps.js';
+import { h as NoteEvent, a as Articulation, b as IntervalLike } from '../index-Cy15oTvh.js';
+export { I as IntervalData, c as IntervalQualityLabel, e as KeyScale, g as NoteData, S as SpelledInterval } from '../index-Cy15oTvh.js';
+import { e as ChordSegment, c as ChordLike, K as KeyLike } from '../coerce-wwdELNYS.js';
+export { b as ChordData, d as ChordQuality, g as ChordSpan, i as ChordToneRole, k as KeyVariant, l as PitchSpelling, m as ProfileWeights, n as ResolvedKey, q as SpelledKeyLike, r as SpelledKeyScale } from '../coerce-wwdELNYS.js';
+export { B as BorrowedSource, e as ChordTimeline, H as HarmonicFunction } from '../index-BpWOhkkE.js';
+import { f as StringedProfile, P as PercussionProfile, c as Limb } from '../positional-DJgs6ltD.js';
+export { I as InstrumentProfile, a as InstrumentProfileCommon, d as PositionalRng, S as SeedPath } from '../positional-DJgs6ltD.js';
+import { b as MeterLike } from '../index-Ci3xyows.js';
+export { M as MeterChange, c as MeterMap, T as TimeSignature } from '../index-Ci3xyows.js';
+export { H as HarmonyRole } from '../index-CnIdP4EZ.js';
+import { r as Genre, q as GenerationContextInput, a4 as Vocabulary, s as GridEvent, m as DrumStyle, $ as Section, n as DrumVoice, t as GrooveFeel, k as DrumHit, H as HarmonizeOptions, y as HarmonizeResult } from '../index-DpC-mDlV.js';
+export { B as BAR_STEPS, a as BASS_STYLES, b as BEAT_STEPS, c as BORROWED_DEGREES, d as BassLineOptions, e as BassSegment, f as BassStyle, g as BorrowedChord, C as Complexity, h as CounterMelodyOptions, D as DRUM_NOTES, i as DeformOptions, j as Draw, l as DrumRole, o as DrumsOptions, E as EuclideanKick, G as GENRES, p as GenerationContext, u as GrooveSlot, v as GrooveStyle, w as GrooveTemplate, x as HarmonizePlacement, z as HumanizeOptions, M as MelodyNote, A as MotifCell, F as MotifContour, I as MotifNote, J as MotifOptions, K as MotifTransform, O as ORNAMENT_STYLES, L as OrnamentOptions, N as OrnamentStyle, P as PROVENANCE_BASES, Q as ProgFunction, R as ProgStyle, S as ProgressionDegree, T as ProgressionOptions, U as ProgressionPreset, V as Provenance, W as ProvenanceBasis, X as ResolvedContext, Y as RhythmEvent, Z as RhythmOptions, _ as STEP_BEATS, a0 as SubstituteOptions, a1 as Substitution, a2 as SubstitutionType, a3 as SyncopateOptions, a5 as VocabularyQuery, a6 as applyGrooveTemplate, a7 as assertVocabulary, a8 as deform, a9 as developMotif, aa as double, ab as doubleTime, ac as drumVoiceOf, ad as extractGrooveTemplate, ae as fitsQuery, af as generateBassLine, ag as generateCounterMelody, ah as generateDrums, ai as generateMotif, aj as generateProgression, ak as generateRhythm, al as gridMetricWeight, am as halfTime, an as humanize, ao as mergeVocabulary, ap as modalInterchangePalette, aq as motifToNoteEvents, ar as negativeHarmonyMirror, as as onsetWeightCurve, at as ornament, au as ornamentBy, av as pickProgressionPreset, aw as pickVocabulary, ax as progressions, ay as progressionsByStyle, az as resolveContext, aA as rhythmDensity, aB as rhythmToNoteEvents, aC as selectVocabulary, aD as substituteChord, aE as syncopate, aF as thin, aG as transformMotif, aH as vocabularyOfKind, aI as withinCeiling } from '../index-DpC-mDlV.js';
 
 /**
  * The playing-difficulty ceiling, as the generators apply it.
@@ -47,65 +48,15 @@ declare function sustainsStrokes(stepBeats: number, bpm: number | undefined, dif
 declare function sustainsShift(semitones: number, stepBeats: number, bpm: number | undefined, difficulty: number | undefined): boolean;
 
 /**
- * The bass lick dictionary: the figures a bass player reaches for, held as
- * chord-relative degrees and beat positions and deformed to fit the progression
- * actually in front of them.
+ * Lay the figures of the dictionary over a chord progression.
  *
- * Provenance: no entry reproduces a bass line from a particular song. Each is a
- * figure that belongs to nobody — the descending soul walk-down, the octave
- * slap, the boogie shuffle — of the kind every player of that music already
- * plays, and each records the ground it qualifies under.
+ * A segment takes a figure its genre plays, chosen by a draw addressed to that
+ * segment, and the figure's degrees are read against the chord sounding under
+ * it. What the figures are is `licks-data.ts`; which pitch a degree asks for is
+ * `degrees.ts`. This module is what places them: which segment takes one, how
+ * it is fitted to the span, and how one figure leads into the next.
  */
 
-/**
- * One note of a lick, relative to the chord it is played over.
- *
- * A degree is 1-based and counts up from the chord's root: 1 is the root, 3 the
- * third, 8 the octave. Degrees the chord itself names — the third, fifth and
- * seventh — are taken from the chord, so the same figure comes out major over a
- * major chord and minor over a minor one; the rest are taken from the key. That
- * is what lets a figure be written once and fit a whole progression.
- *
- * @category Composition
- */
-type LickNote = GridEvent & {
-    /** Chord degree, 1-based; 8 is the octave above the root. */
-    degree: number;
-    /** Chromatic alteration in semitones, for a flattened or raised degree. */
-    alter?: number;
-    /** Sounding length in sixteenths; one step when absent. */
-    lengthSteps?: number;
-    /** How the note is played, when it is more than a plain note. */
-    articulation?: Articulation;
-};
-/**
- * A lick: its notes and how long the whole figure lasts.
- *
- * @category Composition
- */
-type LickMaterial = {
-    /** Length of the figure in sixteenths. */
-    lengthSteps: number;
-    notes: LickNote[];
-};
-/**
- * A lick with the conditions it fits.
- *
- * @category Composition
- */
-type BassLick = Vocabulary<LickMaterial>;
-/**
- * Whether a caller's material is a bass lick.
- *
- * @category Composition
- */
-declare function isLickMaterial(material: unknown): material is LickMaterial;
-/**
- * The built-in bass licks, in declaration order.
- *
- * @category Composition
- */
-declare const BASS_LICKS: readonly BassLick[];
 /**
  * Options controlling {@link placeLicks}.
  *
@@ -122,8 +73,8 @@ type PlaceLicksOptions = {
      * `ctx: { complexity: { difficulty } }`; the context wins over both.
      */
     difficulty?: number;
-    /** Time signature; defaults to 4/4. */
-    ts?: TimeSignature;
+    /** Time signature, in any form that names one; defaults to 4/4. */
+    ts?: MeterLike;
     /**
      * Target register as a base MIDI octave; roots land around `octave*12+12`.
      *
@@ -147,9 +98,10 @@ type PlaceLicksOptions = {
      */
     ctx?: GenerationContextInput;
     /**
-     * Maximum number of segments {@link placeLicks} may lay figures over. One
-     * figure is placed per segment, so this is the guard against an unbounded
-     * caller rather than a limit on any search.
+     * Maximum number of segments {@link placeLicks} may lay figures over, and of
+     * bars those segments span. One figure is placed per bar of a segment, so
+     * both are counted: this is the guard against an unbounded caller — a segment
+     * running to a beat far past the music — rather than a limit on any search.
      *
      * @defaultValue 1000000
      */
@@ -171,8 +123,10 @@ type PlaceLicksOptions = {
  *   key name such as `'C major'` is read as that key.
  * @param opts Genre, density, ceiling and seed.
  * @returns Bass notes sorted by onset, non-overlapping.
- * @throws If a segment has a non-positive duration, or the genre is not one
- *   this library names.
+ * @throws If a segment has a non-positive duration, two segments overlap, or
+ *   the genre is not one this library names. A bass part is monophonic, so
+ *   overlapping segments are refused here exactly as {@link generateBassLine}
+ *   refuses them rather than being laid over each other.
  *
  * @example
  * ```ts
@@ -190,6 +144,74 @@ declare function placeLicks(timeline: readonly (Omit<ChordSegment, 'chord'> & {
     chord: ChordLike;
 })[], key: KeyLike, opts: PlaceLicksOptions): NoteEvent[];
 
+/**
+ * The bass lick dictionary: the figures a bass player reaches for, held as
+ * chord-relative degrees and beat positions and deformed to fit the progression
+ * actually in front of them.
+ *
+ * Provenance: no entry reproduces a bass line from a particular song. Each is a
+ * figure that belongs to nobody — the descending soul walk-down, the octave
+ * slap, the boogie shuffle — of the kind every player of that music already
+ * plays, and each records the ground it qualifies under.
+ */
+
+/**
+ * One note of a lick, relative to the chord it is played over.
+ *
+ * A degree is 1-based and counts up from the chord's root: 1 is the root, 3 the
+ * third, 8 the octave. Degrees the chord itself names — the third, fifth and
+ * seventh — are taken from the chord, so the same figure comes out major over a
+ * major chord and minor over a minor one. A degree the chord's quality settles
+ * without stating it follows the quality: the third of a suspended chord is the
+ * tone the suspension put there, and a seventh chord's remaining degrees are
+ * its own chord scale's. Only what the harmony leaves open is taken from the
+ * key. That is what lets a figure be written once and fit a whole progression.
+ *
+ * @category Composition
+ */
+type LickNote = GridEvent & {
+    /** Chord degree, 1-based; 8 is the octave above the root. */
+    degree: number;
+    /** Chromatic alteration in semitones, for a flattened or raised degree. */
+    alter?: number;
+    /**
+     * Sounding length in sixteenths. Absent, the note sounds to the next onset,
+     * as a line written by {@link generateBassLine} does: the built-in figures
+     * name no length, so a figure is legato unless it says otherwise.
+     */
+    lengthSteps?: number;
+    /** How the note is played, when it is more than a plain note. */
+    articulation?: Articulation;
+};
+/**
+ * A lick: its notes and how long the whole figure lasts.
+ *
+ * @category Composition
+ */
+type LickMaterial = {
+    /** Length of the figure in sixteenths. */
+    lengthSteps: number;
+    notes: LickNote[];
+};
+/**
+ * A lick with the conditions it fits.
+ *
+ * @category Composition
+ */
+type BassLick = Vocabulary<LickMaterial>;
+/**
+ * Whether a caller's material is a bass lick.
+ *
+ * @category Composition
+ */
+declare function isLickMaterial(material: unknown): material is LickMaterial;
+/**
+ * The built-in bass licks, in declaration order.
+ *
+ * @category Composition
+ */
+declare const BASS_LICKS: readonly BassLick[];
+
 /**
  * Imitative entries: a second voice restating what the first has just sung.
  *
@@ -207,8 +229,10 @@ declare const IMITATION_ANSWERS: readonly ["real", "tonal"];
  *
  * A `real` answer transposes literally, keeping every interval of the subject
  * and leaving the key where the interval puts it. A `tonal` answer counts scale
- * degrees instead, so the answer stays in the key and adjusts an interval or two
- * to do it — the fifth of a subject answered by a fourth.
+ * degrees instead, so the answer stays in the key: every interval keeps the
+ * number of degrees it spanned in the subject, and only its quality changes as
+ * the key's own pattern of steps and half steps asks — a major third answered by
+ * a minor one.
  *
  * @category Composition
  */
@@ -280,7 +304,9 @@ type ImitationOptions = {
  * @param opts Where the answer enters, at what interval, and in what key.
  * @returns The imitation as note events sorted by onset; `[]` when the chosen
  *   span holds no sounding notes. Notes with a zero or negative duration never
- *   sound and are not copied, so the answer can be shorter than the span.
+ *   sound and are not copied, so the answer can be shorter than the span. Every
+ *   other field of a copied note — its articulation, and its velocity through
+ *   `velocityScale` — comes across with it.
  * @throws If the span is reversed, the answer is not a known kind, or a
  *   transposed pitch leaves the MIDI range.
  * @example
@@ -344,9 +370,14 @@ type FillArchetype = {
     /** Strokes per beat of the bar, indexed 0..3. */
     atBeat: readonly (readonly FillStroke[])[];
     /**
-     * Whether a bar longer than four beats keeps playing the last beat's strokes.
-     * The archetypes are written against a four-beat bar; most read naturally when
-     * extended, but the half-time figure is a bar-long gesture and stops there.
+     * Whether the archetype stops where its own strokes stop, rather than holding
+     * its last beat over the beats of the bar it does not write.
+     *
+     * It answers for an archetype shorter than the bar it is placed in, so the
+     * built-in archetypes — written beat by beat against the four-beat bar
+     * {@link generateDrums} accepts — are unaffected by it; a caller's archetype
+     * that writes fewer beats is where it decides anything. Most figures read
+     * naturally when held, but a half-time gesture is bar-long and stops there.
      */
     boundToBar?: boolean;
 };
@@ -425,6 +456,11 @@ declare const KICK_FIGURES: Readonly<Record<DrumStyle, KickFigure>>;
  * hand at the same instant is what makes a pattern unplayable, and a voice no
  * limb reaches is not on the kit at all.
  *
+ * The auxiliary percussion — hand-claps, tambourine, shaker — is dubbed over
+ * the kit on a pass of its own, so it sounds through a backbeat whose snare and
+ * hi-hat already take both hands, and the four limbs stay the bound on the
+ * groove itself.
+ *
  * @example
  * ```ts
  * import { DRUM_KIT, generateDrums, playability } from '@libraz/libcantus';
@@ -511,8 +547,8 @@ type DrumPatternOptions = {
     genre: Genre;
     /** Section the pattern plays in, matched against each entry's own sections. */
     section?: Section;
-    /** Time signature; defaults to 4/4. */
-    ts?: TimeSignature;
+    /** Time signature, in any form that names one; defaults to 4/4. */
+    ts?: MeterLike;
     /**
      * The generation context. `bpm` is the tempo, `complexity.rhythmic` thins the
      * figure below its middle setting and syncopates it above,
@@ -631,6 +667,54 @@ type ClassifiedMelodyTone = {
  * ```
  * @category Reharmonization
  */
-declare function classifyMelodyTones(melody: readonly NoteEvent[], ts: TimeSignature): ClassifiedMelodyTone[];
+declare function classifyMelodyTones(melody: readonly NoteEvent[], ts: MeterLike): ClassifiedMelodyTone[];
+
+/**
+ * Harmonize a melody with a min-cost chord progression.
+ *
+ * The melody's ornaments are classified first, from the melody and the metre
+ * alone (see {@link classifyMelodyTones}); the chords then have to explain the
+ * structural tones only, so a passing tone no longer buys itself a chord. The
+ * melody is segmented by `harmonicRhythm`; each segment is scored against the
+ * candidate chords the harmonic dial opens — the key's own triads, then the
+ * secondary dominants, then the parallel mode's chords, one at a time as
+ * `ctx.complexity.harmonic` rises from 0 to 1 — by the fit of those structural
+ * tones, and a Viterbi search picks the lowest-cost path using a
+ * functional-flow transition cost and a cadence bonus at the end of the melody
+ * it is given — one cadence, at the close, unless `phraseEnds` names the closes
+ * inside a longer line, and then one at each of them as well. Runs of the same
+ * chord are reported once, so the chord count follows the harmony rather than
+ * the grid.
+ *
+ * With `placement.transposeSearch` the melody is moved into the key it is
+ * harmonized in, and `transposeSemitones` reports how far; with
+ * `placement.octaveSearch` it is moved by octaves into a comfortable register,
+ * which leaves the key and the chords untouched. Both may be set, and the
+ * reported shift is their sum.
+ *
+ * The `seed` drives a deterministic tie-break only: it perturbs candidates by a
+ * magnitude far below any real cost difference (see `TIE_BREAK_JITTER`),
+ * so it can decide between chords or paths of otherwise-equal cost but never
+ * overrides melody fit or functional flow. For a well-determined melody the
+ * result is identical across seeds; the same seed always yields the same result.
+ *
+ * @param opts The melody and, optionally, the generation context, key, harmonic
+ *   rhythm, reharmonization strength, placement search, meter, and seed. Only
+ *   `melody` is required.
+ * @returns The chosen transpose, key, chord path, and per-note roles.
+ * @example
+ * ```ts
+ * import { harmonizeMelody } from '@libraz/libcantus';
+ * const result = harmonizeMelody({
+ *   melody: [
+ *     { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *     { pitch: 64, startBeat: 1, durationBeat: 1 },
+ *   ],
+ * });
+ * result.chords; // one ChordSpan per chord change, on the harmonic-rhythm grid
+ * ```
+ * @category Reharmonization
+ */
+declare function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult;
 
-export { Articulation, BASS_LICKS, type BassLick, ChordLike, ChordSegment, type ClassifiedMelodyTone, DRUM_KIT, DRUM_PATTERNS, DrumHit, type DrumPattern, type DrumPatternOptions, type DrumStroke, DrumStyle, type DrumVocabulary, DrumVoice, FILL_ARCHETYPES, FILL_TYPES, type FillArchetype, type FillStroke, type FillType, type FillVelocity, GenerationContextInput, Genre, GridEvent, GrooveFeel, type ImitationAnswer, type ImitationOptions, IntervalLike, KICK_FIGURES, KICK_STEPS, KeyLike, type KickFigure, type KickPattern, type KickSlot, type LickMaterial, type LickNote, Limb, MAX_DIFFICULTY, MIN_DIFFICULTY, type MelodyToneRole, NoteEvent, PercussionProfile, type PlaceLicksOptions, Section, StringedProfile, TimeSignature, Vocabulary, classifyMelodyTones, imitate, isDrumPattern, isFillArchetype, isLickMaterial, placeDrumPattern, placeLicks, sustainsShift, sustainsStrokes };
+export { Articulation, BASS_LICKS, type BassLick, ChordLike, ChordSegment, type ClassifiedMelodyTone, DRUM_KIT, DRUM_PATTERNS, DrumHit, type DrumPattern, type DrumPatternOptions, type DrumStroke, DrumStyle, type DrumVocabulary, DrumVoice, FILL_ARCHETYPES, FILL_TYPES, type FillArchetype, type FillStroke, type FillType, type FillVelocity, GenerationContextInput, Genre, GridEvent, GrooveFeel, HarmonizeOptions, HarmonizeResult, type ImitationAnswer, type ImitationOptions, IntervalLike, KICK_FIGURES, KICK_STEPS, KeyLike, type KickFigure, type KickPattern, type KickSlot, type LickMaterial, type LickNote, Limb, MAX_DIFFICULTY, MIN_DIFFICULTY, type MelodyToneRole, MeterLike, NoteEvent, PercussionProfile, type PlaceLicksOptions, Section, StringedProfile, Vocabulary, classifyMelodyTones, harmonizeMelody, imitate, isDrumPattern, isFillArchetype, isLickMaterial, placeDrumPattern, placeLicks, sustainsShift, sustainsStrokes };

package/dist/generate/index.js

@@ -66,13 +66,13 @@ import {
   transformMotif,
   vocabularyOfKind,
   withinCeiling
-} from "../chunk-VOHZB45S.js";
-import "../chunk-H42UHPYW.js";
-import "../chunk-FVSI36UV.js";
-import "../chunk-ELCTZUJJ.js";
-import "../chunk-KNJEKLKV.js";
-import "../chunk-INHVXP6Z.js";
-import "../chunk-VTI6FOLB.js";
+} from "../chunk-R5VUXQMP.js";
+import "../chunk-VLE5R7PF.js";
+import "../chunk-X6RJAHII.js";
+import "../chunk-7GOKQJTQ.js";
+import "../chunk-H66ARFU5.js";
+import "../chunk-FPBZFNCD.js";
+import "../chunk-PQL7E5F6.js";
 export {
   BAR_STEPS,
   BASS_LICKS,

package/dist/{index-CGpRv5sl.d.cts → index-9eoQs2C1.d.ts}

@@ -1,5 +1,5 @@
-import { g as NoteEvent } from './index-B9MNZboQ.cjs';
-import { e as StringFingering, c as Limb, I as InstrumentProfile } from './positional-DvH_sd8u.cjs';
+import { h as NoteEvent } from './index-Cy15oTvh.js';
+import { e as StringFingering, c as Limb, b as InstrumentProfileLike } from './positional-DJgs6ltD.js';
 
 /**
  * What makes a passage hard or impossible on an instrument.
@@ -89,6 +89,9 @@ type PlayabilityReport = {
  * @param profile The instrument to play it on.
  * @param bpm Tempo in quarter-note beats per minute; enables the third layer.
  * @returns Difficulty, the issues found, and each note's string/fret or limb.
+ * @throws If the notes are not note events, the tempo is not a finite positive
+ *   number of beats per minute, or the profile describes no instrument — a neck
+ *   with no strings or a kit no limb reaches, whatever the passage holds.
  *
  * @example
  * ```ts
@@ -98,7 +101,7 @@ type PlayabilityReport = {
  * ```
  * @category Core
  */
-declare function playability(notes: readonly NoteEvent[], profile: InstrumentProfile, bpm?: number): PlayabilityReport;
+declare function playability(notes: readonly NoteEvent[], profile: InstrumentProfileLike, bpm?: number): PlayabilityReport;
 
 /**
  * Note values: the written durations a score shows — a base value, its
@@ -176,7 +179,8 @@ type SpelledDuration = {
  * import { durationToBeats } from '@libraz/libcantus';
  * durationToBeats('quarter'); // 1
  * durationToBeats({ base: 'quarter', dots: 1 }); // 1.5
- * durationToBeats({ base: 'eighth', tuplet: { actual: 3, normal: 2 } }); // 1/3
+ * durationToBeats({ base: 'eighth', tuplet: { actual: 3, normal: 2 } }) * 3; // 1 — three
+ * // eighth-note triplets fill the beat two eighths would
  * ```
  * @category Rhythm & Meter
  */
@@ -192,8 +196,10 @@ declare function durationToBeats(duration: NoteValue | DurationData, options?: {
  * values are preferred to dotted ones and both to tuplets, and within the
  * tuplets triplets come before quintuplets and septuplets.
  *
- * Lengths are matched within 1e-6 beats, so a rounded decimal such as 0.3333333
- * still reads as a triplet.
+ * Lengths are matched within 1e-6 quarter notes, so a rounded decimal such as
+ * 0.3333333 still reads as a triplet. The tolerance is measured in quarter
+ * notes whatever `beatUnit` names, so a longer beat unit narrows it in
+ * proportion: under `{ beatUnit: 'whole' }` it is 2.5e-7 of a beat.
  *
  * @param beats The length in beats.
  * @param options `beatUnit` sets what one beat is; a quarter note by default.
@@ -219,9 +225,12 @@ declare function beatsToDuration(beats: number, options?: {
  * else is broken into undotted values, longest first, and a value immediately
  * followed by its own half is then written as a dot instead: 5 beats reads as a
  * whole note tied to a quarter, and 1.9375 beats as a double-dotted quarter tied
- * to a dotted thirty-second. The chain knows nothing of barlines or beat
- * grouping — an engraver splits further at those — and it uses no tuplets, so a
- * length off the plain grid and with no single spelling has no chain either.
+ * to a dotted thirty-second. The dot is only written where it leaves the chain
+ * in longest-first order, so 10 beats reads as two whole notes tied to a half
+ * rather than as a whole note tied to a longer dotted whole. The chain knows
+ * nothing of barlines or beat grouping — an engraver splits further at those —
+ * and it uses no tuplets, so a length off the plain grid and with no single
+ * spelling has no chain either.
  *
  * @param beats The length in beats.
  * @param options `beatUnit` sets what one beat is; a quarter note by default.
@@ -246,16 +255,18 @@ declare function beatsToTiedDurations(beats: number, options?: {
  * @category Core
  */
 type IndexedNoteEvent = {
-    note: Readonly<NoteEvent>;
-    originalIndex: number;
-    endBeat: number;
+    readonly note: Readonly<NoteEvent>;
+    readonly originalIndex: number;
+    readonly endBeat: number;
 };
 /**
  * Which note wins when several sound from the same onset.
  *
  * `'highest'` and `'lowest'` name a voice, so the answer does not depend on the
  * order the caller happened to store the chord in; `'last'` takes the one
- * latest in the input array.
+ * latest in the input array. Two notes of the same pitch name no voice apart,
+ * so both voice tie-breaks settle a unison on the lower `originalIndex` and
+ * name the same note.
  *
  * @category Core
  */
@@ -300,9 +311,10 @@ type NoteEventIndexOptions = {
     name?: string;
 };
 /**
- * Validate and stable-sort note events once, then expose logarithmic onset and
- * active-note lookups. Non-positive-duration notes may be retained for callers
- * that intentionally filter them later, but never count as sounding.
+ * Validate and stable-sort note events once, then expose onset and active-note
+ * lookups that cost `O(log n + k)`, where `k` is how many notes share the onset
+ * the answer comes from. Non-positive-duration notes may be retained for
+ * callers that intentionally filter them later, but never count as sounding.
  *
  * @category Core
  */
@@ -356,7 +368,8 @@ type TempoMap = readonly TempoEvent[];
  * @param beat Position in quarter-note beats.
  * @param map The tempo map; its first event is the time origin.
  * @returns Elapsed seconds, 0 at the map's first event and negative before it.
- * @throws If the map is empty, unsorted, or carries a non-positive tempo.
+ * @throws If the map is empty, unsorted, or carries a tempo outside 0.1..1000
+ *   quarter-note beats per minute.
  * @example
  * ```ts
  * import { beatsToSeconds } from '@libraz/libcantus';
@@ -433,7 +446,9 @@ declare function tempoAt(beat: number, map: TempoMap): number;
  * back quantized.
  *
  * A position before the first downbeat is a negative tick count, which is how a
- * pickup crosses the MIDI boundary and comes back.
+ * pickup crosses the MIDI boundary and comes back. A position that rounds to
+ * the downbeat from below comes back as positive zero: `-0` and `0` are the
+ * same tick, and only one of them keys as it under `Object.is`.
  *
  * @param beat Position or length in quarter-note beats.
  * @param ppq Pulses (ticks) per quarter note, e.g. 96, 480, or 960.
@@ -628,7 +643,7 @@ declare function ratioToCents(numerator: number, denominator: number): number;
  *
  * @category Pitch & Intervals
  */
-declare const JUST_RATIOS: Readonly<Record<number, readonly [number, number]>>;
+declare const JUST_RATIOS: Readonly<Record<0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12, readonly [number, number]>>;
 /**
  * Cents by which a five-limit just interval departs from its 12-TET tempering
  * (positive means the just interval is wider).