@libraz/libcantus 1.0.1 → 1.2.0

package/dist/{index-BGFW-8P2.d.cts → index-BJgP97N1.d.ts}

@@ -1,9 +1,9 @@
-import { a as Articulation, g as NoteEvent, d as KeyScale } from './index-B9MNZboQ.cjs';
-import { S as SeedPath, d as PositionalRng, I as InstrumentProfile, f as StringedProfile } from './positional-DvH_sd8u.cjs';
-import { T as TimeSignature } from './index-BkGmlyI3.cjs';
-import { d as ChordQuality, e as ChordSegment, c as ChordLike, K as KeyLike, b as Chord, m as ProfileWeights, g as ChordSpan } from './index-C_8o--VE.cjs';
-import { e as ChordTimeline, B as BorrowedSource, H as HarmonicFunction } from './index-Dzr13q3d.cjs';
-import { H as HarmonyRole } from './index-B4o55NDr.cjs';
+import { T as TimeSignature, b as MeterLike } from './index-CL4b4gUQ.js';
+import { a as Articulation, h as NoteEvent } from './index-Cy15oTvh.js';
+import { S as SeedPath, d as PositionalRng, I as InstrumentProfile, f as StringedProfile } from './positional-DJgs6ltD.js';
+import { d as ChordQuality, e as ChordSegment, c as ChordLike, K as KeyLike, b as Chord, m as ProfileWeights, g as ChordSpan, n as ResolvedKey, r as SpelledKeyLike } from './coerce-DP0vYu-x.js';
+import { e as ChordTimeline, B as BorrowedSource, H as HarmonicFunction } from './index-CJBBiAmU.js';
+import { H as HarmonyRole } from './index-Dw2DP7vm.js';
 
 /**
  * The samplers a generator needs, each addressed by the position it is drawing
@@ -98,11 +98,17 @@ type Section = (typeof PUBLIC_SECTIONS)[number];
  */
 
 /**
- * Every genre the built-in dictionaries name, in declaration order.
+ * Every genre name a vocabulary entry may carry, in declaration order.
+ *
+ * Each built-in dictionary stocks part of the list, not all of it: the drum
+ * patterns carry `motown`, `funk`, `blues`, `bossa`, `samba`, `gospel` and
+ * `dnb`; the bass licks carry `motown`, `soul`, `funk`, `blues`, `jazz`,
+ * `bossa`, `gospel`, `country` and `reggae`. Asking a dictionary for a genre it
+ * has nothing for selects nothing rather than failing.
  *
  * The list is open in spirit even though the type is closed: a caller with a
- * genre of its own supplies entries through the generation context rather than
- * waiting for this list to grow.
+ * genre of its own — or one the built-ins do not stock — supplies entries
+ * through the generation context rather than waiting for this list to grow.
  *
  * @category Composition
  */
@@ -201,7 +207,8 @@ type VocabularyQuery = {
     section?: Section;
     /** Tempo in BPM, matched against each entry's band. */
     bpm?: number;
-    ts?: TimeSignature;
+    /** The meter in force, matched against each entry's own signature. */
+    ts?: MeterLike;
     /** The difficulty ceiling: entries above it are rejected. */
     difficulty?: number;
     /** The chord in force, matched against each entry's `fitsOver`. */
@@ -499,16 +506,24 @@ type GridEvent = {
  *
  * This is the ranking the thinning rule works down: the notes a player drops
  * first when asked for something easier are the ones carrying the least of the
- * metre. It is named for the grid it reads because the analysis layer has a
- * metric weight of its own, on another scale and against a time signature; the
- * two answer different questions and are deliberately not the same function.
- *
- * @param step Sixteenth index within the bar.
+ * metre. The ranking is the meter's own — {@link metricWeight} says which
+ * positions are the downbeat, a secondary strong pulse, and a plain main pulse,
+ * and the two ranks below them are the pulse's first subdivision and everything
+ * off it. In 4/4 that is the downbeat, the half bar, the other quarters, the
+ * quavers and the semiquavers; in 6/8 it is the two dotted-quarter pulses, then
+ * the quavers, and the quarter-note positions a 4/4 reading would rank above
+ * them fall where they belong, between the beats.
+ *
+ * @param step Sixteenth index from the start of the figure.
+ * @param ts The meter the figure is counted in, in any form that names one.
+ *   Asked for rather than defaulted: the built-in figures are written on a 4/4
+ *   grid, but a caller working in 7/8 who leaves it out has no way to hear that
+ *   the ranking they got was somebody else's bar.
  * @returns The weight, 0 to 4.
  *
  * @category Composition
  */
-declare function gridMetricWeight(step: number): number;
+declare function gridMetricWeight(step: number, ts: MeterLike): number;
 /**
  * Drop the notes carrying the least of the metre.
  *
@@ -519,11 +534,15 @@ declare function gridMetricWeight(step: number): number;
  *
  * @param events The figure.
  * @param amount How much to thin, in [0, 1].
+ * @param ts The meter the figure is counted in, in any form that names one.
+ *   The ranks are the meter's, so a full turn of the dial leaves the downbeats
+ *   of the bar the figure is actually in — which is why it is asked for rather
+ *   than assumed.
  * @returns The surviving events, in the order given.
  *
  * @category Composition
  */
-declare function thin<T extends GridEvent>(events: readonly T[], amount: number): T[];
+declare function thin<T extends GridEvent>(events: readonly T[], amount: number, ts: MeterLike): T[];
 /**
  * Fill in the gaps of a figure, one note per gap.
  *
@@ -555,13 +574,35 @@ declare function halfTime<T extends GridEvent>(events: readonly T[], spanSteps?:
  * The repeat is what makes this the mirror of {@link halfTime} rather than a
  * figure with a hole in it: the bar stays full.
  *
+ * Halving brings positions together, and two onsets of one stream landing on
+ * the same step are one stroke played louder rather than two: a drum struck
+ * twice at the same instant is a pair of note-ons a reader turns into a hung or
+ * cut note, so the pair is merged and the louder of the two is what sounds.
+ * Streams stay apart, since two limbs striking together is a chord and not a
+ * repeat.
+ *
  * @param events The figure.
  * @param spanSteps Length of the figure in sixteenths.
- * @returns The compressed figure, repeated to fill the span.
+ * @returns The compressed figure, repeated to fill the span, at most one event
+ *   per stream and step.
  *
  * @category Composition
  */
 declare function doubleTime<T extends GridEvent>(events: readonly T[], spanSteps?: number): T[];
+/**
+ * How much a figure is syncopated, and the meter it is felt in.
+ *
+ * @category Composition
+ */
+type SyncopateOptions = {
+    /** How much syncopation, in [0, 1]. */
+    amount: number;
+    /**
+     * The meter the figure is counted in, in any form that names one; 4/4 when
+     * none is named.
+     */
+    ts?: MeterLike;
+};
 /**
  * Anticipate beats, one sixteenth early.
  *
@@ -583,14 +624,17 @@ declare function doubleTime<T extends GridEvent>(events: readonly T[], spanSteps
  * than this one's.
  *
  * @param events The figure.
- * @param amount How much syncopation, in [0, 1].
+ * @param amount How much syncopation, in [0, 1], or the amount together with
+ *   the meter the figure is counted in. The path is variadic, so the meter is
+ *   named here rather than after it; naming none reads the figure in 4/4, as
+ *   every built-in figure is written.
  * @param draw The position-addressed sampler.
  * @param path Where the figure sits, so the same bar always syncopates alike.
  * @returns The figure with its anticipations, sorted by position.
  *
  * @category Composition
  */
-declare function syncopate<T extends GridEvent>(events: readonly T[], amount: number, draw: Draw, ...path: readonly (string | number)[]): T[];
+declare function syncopate<T extends GridEvent>(events: readonly T[], amount: number | SyncopateOptions, draw: Draw, ...path: readonly (string | number)[]): T[];
 /**
  * How much decoration a figure keeps.
  *
@@ -634,6 +678,15 @@ type DeformOptions = {
     rate?: 'straight' | 'half' | 'double';
     /** Length of the figure in sixteenths. */
     spanSteps?: number;
+    /**
+     * The meter the figure is counted in, in any form that names one; 4/4 when
+     * none is named, which is the bar every built-in figure is written on.
+     *
+     * The dials rank a figure's positions by how much of the metre each carries,
+     * so a figure written in another meter has to name it or it is thinned and
+     * syncopated against accents its own bar does not have.
+     */
+    ts?: MeterLike;
 };
 /**
  * Apply the complexity dials to a figure.
@@ -746,7 +799,7 @@ type BassLineOptions = {
      *
      * @defaultValue `{ numerator: 4, denominator: 4 }`
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * Bass-line idiom.
      *
@@ -756,7 +809,8 @@ type BassLineOptions = {
     /**
      * Target register as a base MIDI octave; roots land around `octave*12+12`.
      * An octave pickup in the `pop` style may drop a note into the octave below
-     * that band, which is where such a pickup belongs.
+     * that band, which is where such a pickup belongs, or take the octave above
+     * instead on an instrument with nothing below the band to drop into.
      *
      * @defaultValue 2
      */
@@ -859,11 +913,11 @@ type CounterMelodyOptions = {
      */
     key: KeyLike;
     /**
-     * Meter used for strong-beat decisions.
+     * Meter used for strong-beat decisions, in any form that names one.
      *
      * @defaultValue 4/4
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * Which side of the melody the counter line occupies.
      *
@@ -890,7 +944,8 @@ type CounterMelodyOptions = {
     /**
      * Per-field overrides of the profile's ranking weights, for a preference the
      * two stock profiles do not express — a line that should leap more freely, or
-     * one that should hold a pedal wherever it can.
+     * one that should hold a pedal wherever it can. Every field named must be a
+     * finite number.
      */
     weights?: Partial<ProfileWeights>;
     /** Lowest MIDI pitch the counter line may use (default derived from `register`). */
@@ -931,6 +986,9 @@ type CounterMelodyOptions = {
  *
  * @param opts The lead line, chord context callback, key, and generation knobs.
  * @returns The counter line as note events sorted by onset; `[]` for an empty melody.
+ * @throws If an option names a value outside its range — including a weight
+ *   override that is not a finite number, which is rejected before any
+ *   candidate is scored rather than absorbed into the ranking.
  * @example
  * ```ts
  * import { generateCounterMelody, majorKey, parseChordSymbol } from '@libraz/libcantus';
@@ -1056,12 +1114,14 @@ type DrumsOptions = {
      * hi-hat subdivisions, the open-hat and crash beats, the beat a fill starts on
      * — is written against a four-beat bar, so another meter would come back with
      * 4/4 accents in a bar of the wrong length and no sign that anything was
-     * wrong. A meter it cannot place is refused rather than mis-placed. Use
-     * {@link generateRhythm} or {@link placeDrumPattern} for other meters.
+     * wrong. A meter it cannot place is refused rather than mis-placed, and a
+     * meter map is read whole: one that opens in 4/4 and changes later is refused
+     * for the change, not accepted for the opening. Use {@link generateRhythm} or
+     * {@link placeDrumPattern} for other meters.
      *
      * @defaultValue `{ numerator: 4, denominator: 4 }`
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * Replace the final bar with a fill.
      *
@@ -1186,11 +1246,11 @@ declare function generateDrums(opts: DrumsOptions): DrumHit[];
  */
 type HumanizeOptions = {
     /**
-     * Time signature used to derive metric accents.
+     * Time signature used to derive metric accents, in any form that names one.
      *
      * @defaultValue 4/4
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * Maximum timing jitter in quarter-note beats, applied as ±this value.
      *
@@ -1321,7 +1381,7 @@ type GrooveTemplate = {
  * @returns The extracted groove template.
  * @category Rhythm & Meter
  */
-declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: TimeSignature, subdivision?: number): GrooveTemplate;
+declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: MeterLike, subdivision?: number): GrooveTemplate;
 /**
  * Apply a groove template to a set of (typically quantized) note events: each
  * event is snapped to its grid slot and then offset by that slot's recorded
@@ -1335,13 +1395,19 @@ declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: TimeSig
  * If the template carries a time signature (see {@link GrooveTemplate.ts}) it
  * must match `ts`, since a differing bar length would misalign the per-bar
  * grid and drift the feel; a mismatch throws rather than corrupting timing
- * silently.
+ * silently. `slotsPerBar` is held to the same standard, since it is what the
+ * grid is read through: a template built by hand whose count does not match the
+ * bar would send a note past the end of the grid and land it on the next bar's
+ * downbeat. What the slots carry is checked too, so nothing this returns is a
+ * note event the rest of the library would refuse.
  *
  * @param events The events to reshape.
  * @param template The groove template, from {@link extractGrooveTemplate}.
  * @param ts The time signature, used to compute the bar length.
  * @returns Reshaped copies of `events`, in input order.
- * @throws If `template.ts` is set and does not match `ts`.
+ * @throws If `template.ts` is set and does not match `ts`, if `slotsPerBar` is
+ *   not the number of slots a bar of `ts` holds at the template's subdivision,
+ *   or if a slot carries a non-finite offset or a velocity outside [0, 127].
  * @example
  * ```ts
  * import { extractGrooveTemplate, applyGrooveTemplate, parseTimeSignature } from '@libraz/libcantus';
@@ -1358,14 +1424,22 @@ declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: TimeSig
  * ```
  * @category Rhythm & Meter
  */
-declare function applyGrooveTemplate(events: readonly NoteEvent[], template: GrooveTemplate, ts: TimeSignature): NoteEvent[];
+declare function applyGrooveTemplate(events: readonly NoteEvent[], template: GrooveTemplate, ts: MeterLike): NoteEvent[];
 
+/**
+ * Every production style a preset may suit, in declaration order.
+ *
+ * Written as a table rather than only as a union so the names exist at run time:
+ * a union is checked when the caller compiles, and a style arriving from a
+ * config file or a JavaScript caller is checked against this.
+ */
+declare const PROG_STYLES: readonly ["minimal", "dance", "idol", "rock"];
 /**
  * Broad production style a progression preset suits.
  *
  * @category Composition
  */
-type ProgStyle = 'minimal' | 'dance' | 'idol' | 'rock';
+type ProgStyle = (typeof PROG_STYLES)[number];
 /**
  * Harmonic-function role of a progression as a whole.
  *
@@ -1381,8 +1455,9 @@ type ProgressionPreset = {
     id: string;
     name: string;
     /**
-     * The chord roots, in order, as {@link ProgressionDegree} codes: 0..6 for the
-     * key's own scale degrees and {@link BORROWED_DEGREES} for the borrowed ones.
+     * The chord roots, in order, as {@link ProgressionDegree} codes: 1..7 for the
+     * key's own scale degrees, counted as a musician counts them, and
+     * {@link BORROWED_DEGREES} for the borrowed ones.
      */
     degrees: ProgressionDegree[];
     functional: ProgFunction;
@@ -1447,6 +1522,16 @@ type ProgressionOptions = {
      */
     style: ProgStyle;
     bars: number;
+    /**
+     * The meter the bars are counted in, in any form that names one; a meter map
+     * is read as the signature it opens in. One chord is laid out per bar, so this
+     * is what the chords are spaced by — a chord every three beats in 3/4, every
+     * three in 6/8 — and a progression written against another bar length drifts
+     * off the bar lines of the part it is played under.
+     *
+     * @defaultValue `4/4`
+     */
+    ts?: MeterLike;
     /** Pick a specific built-in preset by id instead of choosing one by style. */
     presetId?: string;
     /**
@@ -1490,8 +1575,8 @@ declare function progressionsByStyle(style: ProgStyle): ProgressionPreset[];
  * no way to name it.
  *
  * @param style The style pool to choose from.
- * @param seed The same seed the generator would be given.
- * @returns The preset that seed selects.
+ * @param ctx The same context the generator would be given, or the seed alone.
+ * @returns The preset that context selects.
  * @throws If no preset claims the style.
  * @example
  * ```ts
@@ -1500,7 +1585,7 @@ declare function progressionsByStyle(style: ProgStyle): ProgressionPreset[];
  * ```
  * @category Composition
  */
-declare function pickProgressionPreset(style: ProgStyle, seed?: number): ProgressionPreset;
+declare function pickProgressionPreset(style: ProgStyle, ctx?: GenerationContextInput): ProgressionPreset;
 /**
  * Generate a chord progression laid out one chord per bar.
  *
@@ -1508,14 +1593,17 @@ declare function pickProgressionPreset(style: ProgStyle, seed?: number): Progres
  * the presets matching `style`, seeded by the context's `seed`. An unknown
  * `presetId`, or a `style` no preset claims, is a caller error and throws rather
  * than silently falling back to a random preset. The preset's degrees cycle to
- * fill `bars`; each bar is four beats, so `startBeat` is `barIndex * 4`. Chord
+ * fill `bars`; a bar is one bar of `ts`, so `startBeat` is `barIndex` bars of
+ * it — four beats apart in 4/4, three in 3/4 and in 6/8 alike. Chord
  * roots come from the key's diatonic scale-degree mapping. When `ext` is
  * omitted or `'auto'`, each chord takes its diatonic triad quality; otherwise
  * `ext` is forced on every chord — except a reharmonized chord, which is a
  * secondary dominant and is therefore always a `dom7`. With
  * `complexity.harmonic` above 0, some chords are deterministically replaced with
  * the secondary dominant (V7) of the following chord, flagged with
- * `secondaryDominant`.
+ * `secondaryDominant`. Only a chord the key can make a local tonic is given one:
+ * nothing tonicizes a diminished triad, so the supertonic of a minor key takes
+ * no dominant of its own.
  *
  * @param opts Generation options.
  * @returns One chord per bar in timeline order.
@@ -1539,6 +1627,12 @@ declare function pickProgressionPreset(style: ProgStyle, seed?: number): Progres
  */
 declare function generateProgression(opts: ProgressionOptions): ChordSpan[];
 
+/**
+ * What the stages of the harmonizer share: the shapes they pass between them,
+ * the defaults they fall back on, and the two questions about a key that more
+ * than one of them asks.
+ */
+
 /**
  * A melody note supplied to the harmonizer: a {@link NoteEvent}.
  *
@@ -1612,7 +1706,7 @@ type HarmonizeOptions = {
      *
      * @defaultValue `4/4`
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * How far beyond the key's own triads the chord vocabulary reaches:
      * `'diatonic'` uses only them, `'secondaryDominant'` adds the dominants that
@@ -1672,6 +1766,14 @@ type HarmonizeOptions = {
      * @defaultValue `{ seed: 0 }`
      */
     ctx?: GenerationContextInput;
+    /**
+     * Upper bound on the work this call may do. The search is one pass per
+     * placement over every pair of candidate chords in every slot, so a long line
+     * harmonized with `placement.transposeSearch` on is what needs this raised.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
 };
 /**
  * The chosen transpose, key, chord path, and per-note roles.
@@ -1684,7 +1786,16 @@ type HarmonizeResult = {
      * much puts it in `key`, which is the key the chords are in.
      */
     transposeSemitones: number;
-    key: KeyScale;
+    /**
+     * The key the chords are in, whole.
+     *
+     * A key/scale alone says nothing about how it is written, so a result
+     * carrying one would report whichever spelling its pitch classes read best
+     * from, and an Ab minor handed in would come back out a G# minor. It matters
+     * most under `key: 'infer'`, where this is the only account of which key was
+     * chosen and a caller has nothing else to spell the chord spans from.
+     */
+    key: ResolvedKey;
     /** One span per chord change, each starting on a harmonic-rhythm boundary. */
     chords: ChordSpan[];
     /** Each melody note's role in the chord sounding under it, once chosen. */
@@ -1693,60 +1804,22 @@ type HarmonizeResult = {
         role: HarmonyRole;
     }[];
 };
-/**
- * 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;
 
 /**
  * A transformation applicable to a motif cell.
  *
  * @category Composition
  */
-type MotifTransform = 'transposeDiatonic' | 'transposeChromatic' | 'invert' | 'retrograde' | 'augment' | 'diminish' | 'sequence';
+declare const MOTIF_TRANSFORMS: readonly ["transposeDiatonic", "transposeChromatic", "invert", "retrograde", "augment", "diminish", "sequence"];
+/**
+ * The name of a transformation {@link transformMotif} can apply to a cell.
+ *
+ * Derived from the table the transforms are dispatched from, so a transform
+ * added to one is named by the other on the same commit.
+ *
+ * @category Composition
+ */
+type MotifTransform = (typeof MOTIF_TRANSFORMS)[number];
 /**
  * A single note within a motif cell.
  *
@@ -1792,7 +1865,7 @@ type MotifOptions = {
      *
      * @defaultValue 4/4
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * Melodic contour shape the line follows.
      *
@@ -1864,7 +1937,10 @@ declare function motifToNoteEvents(cell: MotifCell): NoteEvent[];
 /**
  * Apply a transformation to a motif cell.
  *
- * `invert` reflects pitches about the first note (chromatic, self-inverse);
+ * Every transform hands the cell back in onset order, so the note a later
+ * transform reads as the first one is the note that sounds first.
+ *
+ * `invert` reflects pitches about the earliest note (chromatic, self-inverse);
  * `retrograde` mirrors onsets about the cell span, preserving rests (self-inverse);
  * `augment`/`diminish` scale time by `amount ?? 2` and its reciprocal;
  * `transposeChromatic` adds `amount` semitones; `transposeDiatonic` shifts by
@@ -1879,7 +1955,8 @@ declare function motifToNoteEvents(cell: MotifCell): NoteEvent[];
  * @param key Key context for the diatonic transforms, as a key name such as
  *   `'C major'` or as a key/scale; without it, `transposeDiatonic` and
  *   `sequence` shift chromatically by semitones.
- * @returns The transformed cell.
+ * @returns The transformed cell, its notes in time order whatever order the
+ *   source cell was written in, so it can be read as a line.
  * @throws If a transformed pitch would fall outside the MIDI range 0..127.
  *
  * @example
@@ -1908,21 +1985,23 @@ declare function transformMotif(cell: MotifCell, t: MotifTransform, amount?: num
  * @param key Key context, as a key name such as `'C major'` or as a key/scale;
  *   the notes off the structural positions are kept in it.
  * @param bars Number of bars to fill.
- * @param ts Meter the bars are counted in; defaults to 4/4.
- * @returns The developed, harmony-aware cell.
+ * @param ts Meter the bars are counted in. Asked for rather than defaulted: a
+ *   development laid on the wrong bar length drifts off the part it plays
+ *   under, and a caller who leaves it out has no way to hear that.
+ * @returns The developed, harmony-aware cell, its notes in time order.
  *
  * @example
  * ```ts
  * import { chordTimelineFromChords, developMotif, generateMotif, majorKey } from '@libraz/libcantus';
  * const key = majorKey(0);
  * const timeline = chordTimelineFromChords([{ rootPc: 0, quality: 'maj', startBeat: 0 }], 8);
- * const developed = developMotif(generateMotif({ key, bars: 1 }), timeline, key, 2);
+ * const developed = developMotif(generateMotif({ key, bars: 1 }), timeline, key, 2, '4/4');
  * developed.notes.map((n) => n.pitch); // [60, 62, 60, 60, 62, 60] — the C-D-C cell, twice
  * ```
  *
  * @category Composition
  */
-declare function developMotif(cell: MotifCell, timeline: ChordTimeline, key: KeyLike, bars: number, ts?: TimeSignature): MotifCell;
+declare function developMotif(cell: MotifCell, timeline: ChordTimeline, key: KeyLike, bars: number, ts: MeterLike): MotifCell;
 
 /**
  * Ornaments applied to material that already exists.
@@ -1952,7 +2031,8 @@ declare const ORNAMENT_STYLES: readonly ["ghost", "flam", "drag", "slide", "acce
  *   also takes, voiced as a grace stroke instead of a velocity lift.
  * - `'drag'`: mark notes leading into a strong position as dragged. A weak-position
  *   note qualifies only when the next onset in the material falls on a strong one.
- * - `'slide'`: mark a note reached by a step or a leap as slid into.
+ * - `'slide'`: mark a note reached by a step or a leap as slid into. A repeated
+ *   pitch is not: a slide is the move between two pitches, and there is none.
  * - `'accent'`: mark strong-position notes as accented, and lift their velocity.
  *
  * @category Composition
@@ -1977,11 +2057,12 @@ type OrnamentOptions = {
      */
     amount?: number;
     /**
-     * Time signature, used to tell strong positions from weak ones.
+     * Time signature, in any form that names one, used to tell strong positions
+     * from weak ones.
      *
      * @defaultValue 4/4
      */
-    ts?: TimeSignature;
+    ts?: MeterLike;
     /**
      * The generation context. Its `complexity.ornament` sets the amount, its
      * `complexity.difficulty` — with a tempo — keeps ornaments off passages too
@@ -1996,7 +2077,8 @@ type OrnamentOptions = {
  *
  * Which notes are eligible follows from the style and the meter — ghosts fall on
  * weak positions, drags on the weak position before a strong one, flams and
- * accents on strong ones, slides on notes reached by a leap — and `amount`
+ * accents on strong ones, slides on notes the line moves to, by a step or by a
+ * leap — and `amount`
  * decides how many of those eligible notes are taken. The choice is addressed by
  * each note's own position, so raising `amount` adds ornaments without moving the
  * ones already there, and no onset is ever added or shifted: a decorated note is
@@ -2117,7 +2199,7 @@ type SubstituteOptions = {
  * ```
  * @category Reharmonization
  */
-declare function substituteChord(chord: ChordLike, key: KeyLike, opts?: SubstituteOptions): Substitution[];
+declare function substituteChord(chord: ChordLike, key: SpelledKeyLike, opts?: SubstituteOptions): Substitution[];
 /**
  * A borrowed chord in the modal-interchange palette of a key.
  *
@@ -2155,7 +2237,7 @@ type BorrowedChord = {
  * ```
  * @category Reharmonization
  */
-declare function modalInterchangePalette(key: KeyLike): BorrowedChord[];
+declare function modalInterchangePalette(key: SpelledKeyLike): BorrowedChord[];
 /**
  * Reflect a chord across the tonic–dominant axis of a key (negative harmony).
  *
@@ -2180,7 +2262,7 @@ declare function modalInterchangePalette(key: KeyLike): BorrowedChord[];
  * ```
  * @category Reharmonization
  */
-declare function negativeHarmonyMirror(chord: ChordLike, key: KeyLike): Chord;
+declare function negativeHarmonyMirror(chord: ChordLike, key: SpelledKeyLike): Chord;
 
 /**
  * Deterministic rhythm generation over a metric grid.
@@ -2218,6 +2300,7 @@ type RhythmEvent = {
  * @param pitch The MIDI pitch to give every note.
  * @param velocity Velocity for every note; defaults to a mezzo-forte 96.
  * @returns The note events, in the order given.
+ * @throws If the pitch or the velocity is not a whole MIDI value in [0, 127].
  * @example
  * ```ts
  * import { generateRhythm, humanize, rhythmToNoteEvents } from '@libraz/libcantus';
@@ -2281,27 +2364,26 @@ declare function onsetWeightCurve(weight: number): number;
  * seed. Each event's duration extends to the next onset, and the last event
  * extends to the end of the span.
  *
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one.
  * @param opts Generation options.
  * @returns Onset events sorted by position, non-overlapping, covering the span.
  * @example
  * ```ts
- * import { parseTimeSignature, generateRhythm } from '@libraz/libcantus';
- * const ts = parseTimeSignature('4/4');
- * generateRhythm(ts, { ctx: { seed: 42, complexity: { rhythmic: 0.6 } } });
+ * import { generateRhythm } from '@libraz/libcantus';
+ * generateRhythm('4/4', { ctx: { seed: 42, complexity: { rhythmic: 0.6 } } });
  * // onset events over one bar
  * ```
  * @category Rhythm & Meter
  */
-declare function generateRhythm(ts: TimeSignature, opts?: RhythmOptions): RhythmEvent[];
+declare function generateRhythm(ts: MeterLike, opts?: RhythmOptions): RhythmEvent[];
 /**
  * Onset density of a generated pattern: the mean number of onsets per bar.
  *
  * @param events Events from {@link generateRhythm}.
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one.
  * @returns The onset count divided by the number of bars the events span.
  * @category Rhythm & Meter
  */
-declare function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number;
+declare function rhythmDensity(events: RhythmEvent[], ts: MeterLike): number;
 
-export { type Section as $, type MotifCell as A, BAR_STEPS as B, type Complexity as C, DRUM_NOTES as D, type EuclideanKick as E, type MotifContour as F, GENRES as G, type HarmonizeOptions as H, type MotifNote as I, type MotifOptions as J, type MotifTransform as K, type OrnamentOptions as L, type MelodyNote as M, type OrnamentStyle as N, ORNAMENT_STYLES as O, PROVENANCE_BASES as P, type ProgFunction as Q, type ProgStyle as R, type ProgressionDegree as S, type ProgressionOptions as T, type ProgressionPreset as U, type Provenance as V, type ProvenanceBasis as W, type ResolvedContext as X, type RhythmEvent as Y, type RhythmOptions as Z, STEP_BEATS as _, BASS_STYLES as a, type SubstituteOptions as a0, type Substitution as a1, type SubstitutionType as a2, type Vocabulary as a3, type VocabularyQuery as a4, applyGrooveTemplate as a5, assertVocabulary as a6, deform as a7, developMotif as a8, double as a9, rhythmDensity as aA, rhythmToNoteEvents as aB, selectVocabulary as aC, substituteChord as aD, syncopate as aE, thin as aF, transformMotif as aG, vocabularyOfKind as aH, withinCeiling as aI, doubleTime as aa, drumVoiceOf as ab, extractGrooveTemplate as ac, fitsQuery as ad, generateBassLine as ae, generateCounterMelody as af, generateDrums as ag, generateMotif as ah, generateProgression as ai, generateRhythm as aj, gridMetricWeight as ak, halfTime as al, harmonizeMelody as am, humanize as an, mergeVocabulary as ao, modalInterchangePalette as ap, motifToNoteEvents as aq, negativeHarmonyMirror as ar, onsetWeightCurve as as, ornament as at, ornamentBy as au, pickProgressionPreset as av, pickVocabulary as aw, progressions as ax, progressionsByStyle as ay, resolveContext as az, BEAT_STEPS as b, BORROWED_DEGREES as c, type BassLineOptions as d, type BassSegment as e, type BassStyle as f, type BorrowedChord as g, type CounterMelodyOptions as h, type DeformOptions as i, type Draw as j, type DrumHit as k, type DrumRole as l, type DrumStyle as m, type DrumVoice as n, type DrumsOptions as o, type GenerationContext as p, type GenerationContextInput as q, type Genre as r, type GridEvent as s, type GrooveFeel as t, type GrooveSlot as u, type GrooveStyle as v, type GrooveTemplate as w, type HarmonizePlacement as x, type HarmonizeResult as y, type HumanizeOptions as z };
+export { type Section as $, type MotifCell as A, BAR_STEPS as B, type Complexity as C, DRUM_NOTES as D, type EuclideanKick as E, type MotifContour as F, GENRES as G, type HarmonizeOptions as H, type MotifNote as I, type MotifOptions as J, type MotifTransform as K, type OrnamentOptions as L, type MelodyNote as M, type OrnamentStyle as N, ORNAMENT_STYLES as O, PROVENANCE_BASES as P, type ProgFunction as Q, type ProgStyle as R, type ProgressionDegree as S, type ProgressionOptions as T, type ProgressionPreset as U, type Provenance as V, type ProvenanceBasis as W, type ResolvedContext as X, type RhythmEvent as Y, type RhythmOptions as Z, STEP_BEATS as _, BASS_STYLES as a, type SubstituteOptions as a0, type Substitution as a1, type SubstitutionType as a2, type SyncopateOptions as a3, type Vocabulary as a4, type VocabularyQuery as a5, applyGrooveTemplate as a6, assertVocabulary as a7, deform as a8, developMotif as a9, rhythmDensity as aA, rhythmToNoteEvents as aB, selectVocabulary as aC, substituteChord as aD, syncopate as aE, thin as aF, transformMotif as aG, vocabularyOfKind as aH, withinCeiling as aI, double as aa, doubleTime as ab, drumVoiceOf as ac, extractGrooveTemplate as ad, fitsQuery as ae, generateBassLine as af, generateCounterMelody as ag, generateDrums as ah, generateMotif as ai, generateProgression as aj, generateRhythm as ak, gridMetricWeight as al, halfTime as am, humanize as an, mergeVocabulary as ao, modalInterchangePalette as ap, motifToNoteEvents as aq, negativeHarmonyMirror as ar, onsetWeightCurve as as, ornament as at, ornamentBy as au, pickProgressionPreset as av, pickVocabulary as aw, progressions as ax, progressionsByStyle as ay, resolveContext as az, BEAT_STEPS as b, BORROWED_DEGREES as c, type BassLineOptions as d, type BassSegment as e, type BassStyle as f, type BorrowedChord as g, type CounterMelodyOptions as h, type DeformOptions as i, type Draw as j, type DrumHit as k, type DrumRole as l, type DrumStyle as m, type DrumVoice as n, type DrumsOptions as o, type GenerationContext as p, type GenerationContextInput as q, type Genre as r, type GridEvent as s, type GrooveFeel as t, type GrooveSlot as u, type GrooveStyle as v, type GrooveTemplate as w, type HarmonizePlacement as x, type HarmonizeResult as y, type HumanizeOptions as z };