@libraz/libcantus 1.2.0 → 1.4.0

package/dist/{index-BJgP97N1.d.ts → index-jgeug9EA.d.ts}

@@ -1,9 +1,9 @@
-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';
+import { T as TimeSignature, b as MeterLike, c as MeterMap } from './index-Bf0Sv8a9.js';
+import { a as Articulation, h as NoteEvent } from './index-C9MYbuKS.js';
+import { S as SeedPath, d as PositionalRng, I as InstrumentProfile, f as StringedProfile } from './positional-DLnfUgqG.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-CUhHc3Tu.js';
+import { h as ChordTimeline, e as CadenceType, v as MelodicContourShape, P as MotifRelationSummary, a5 as ReferenceProfile, b as BorrowedSource, o as HarmonicFunction } from './types-7mGFwvMm.js';
+import { H as HarmonyRole } from './index-C7KCaTRz.js';
 
 /**
  * The samplers a generator needs, each addressed by the position it is drawing
@@ -547,8 +547,9 @@ declare function thin<T extends GridEvent>(events: readonly T[], amount: number,
  * Fill in the gaps of a figure, one note per gap.
  *
  * Doubling is what a player does when asked for more of the same rather than
- * for something different: the added note sits halfway between two the figure
- * already has, takes its predecessor's identity, and is played softer.
+ * for something different: the added note sits halfway between two onsets of
+ * one stream (the limb, else the voice), takes its predecessor's identity, and
+ * is played softer. A gap between two limbs is no gap for either of them.
  *
  * @param events The figure, which need not be sorted.
  * @param spanSteps Length of the figure in sixteenths.
@@ -574,6 +575,9 @@ 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.
  *
+ * A whole step halves onto the nearest sixteenth; an onset off the straight
+ * grid, a triplet, halves exactly and stays on its own grid.
+ *
  * 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
@@ -713,8 +717,8 @@ type DeformOptions = {
  * const busier = deform(figure, { rhythmic: 0.9 }, draw, 'bar', 0);
  * // Above the neutral middle the figure is syncopated: onsets are added off
  * // the beat, and the result comes back sorted by position.
- * busier.length; // 7
- * busier.map((event) => event.step); // [0, 3, 4, 7, 8, 11, 12]
+ * busier.length; // 6
+ * busier.map((event) => event.step); // [0, 3, 4, 8, 11, 12]
  * ```
  *
  * @category Composition
@@ -747,9 +751,12 @@ declare function withinCeiling(events: readonly GridEvent[], bpm: number | undef
  * Given a sequence of chord segments and a key, this builds a monophonic bass
  * line in a chosen low register. Several idiomatic styles are supported, from a
  * single held root per segment to a quarter-note walking line that leads by
- * step into each chord change. All pitches are kept in a narrow bass band and
- * consecutive notes move by small intervals; given a seed the output is fully
- * reproducible.
+ * step into each chord change. Root-position chord tones are kept in an
+ * octave-wide bass band `[low, low + 12]`. A slash chord's other tones sit up to
+ * an octave above its placed bass, so they can rise past the top of the band,
+ * and the `pop` octave pickup and the walking approach notes leave the band by
+ * design; consecutive notes can therefore lie more than an octave apart. Given
+ * a seed the output is fully reproducible.
  *
  * Positions and durations are measured in quarter-note beats, matching the
  * library-wide convention.
@@ -847,9 +854,12 @@ type BassLineOptions = {
  * Generate a bass line following a chord placement.
  *
  * Each segment contributes notes in the chosen bass register per the selected
- * style; consecutive notes are kept within roughly a fifth. Every note's
- * duration extends to the next onset (the final note extends to the last
- * segment's end). Given a seed the output is fully reproducible.
+ * style. Root-position chord tones lie in the `[low, low + 12]` band; a slash
+ * chord's other tones sit up to an octave above its placed bass, and the `pop`
+ * octave pickup and the walking approach notes leave the band, so consecutive
+ * notes can be more than an octave apart. Every note's duration extends to the
+ * next onset (the final note extends to the last segment's end). Given a seed
+ * the output is fully reproducible.
  *
  * The `pop` style's pickups are drawn per position, so raising
  * `complexity.rhythmic` adds pickups without moving the notes already written.
@@ -1247,6 +1257,8 @@ declare function generateDrums(opts: DrumsOptions): DrumHit[];
 type HumanizeOptions = {
     /**
      * Time signature used to derive metric accents, in any form that names one.
+     * A meter map is read bar by bar, so a note after a change is accented in the
+     * signature in force where it sounds.
      *
      * @defaultValue 4/4
      */
@@ -1374,11 +1386,13 @@ type GrooveTemplate = {
  * template so {@link applyGrooveTemplate} can verify the meter matches.
  *
  * @param events The (typically "groovy", human-played) events to analyze.
- * @param ts The time signature, used to compute the bar length.
+ * @param ts The time signature, used to compute the bar length. A meter map
+ *   is accepted while it keeps one signature throughout.
  * @param subdivision Grid resolution: equal grid steps per quarter-note beat.
  *   Defaults to a sixteenth-note grid, which is where the timing deviations a
  *   template records — swing, push, drag — are audible.
  * @returns The extracted groove template.
+ * @throws If `ts` changes signature.
  * @category Rhythm & Meter
  */
 declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: MeterLike, subdivision?: number): GrooveTemplate;
@@ -1403,11 +1417,13 @@ declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: MeterLi
  *
  * @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.
+ * @param ts The time signature, used to compute the bar length. A meter map
+ *   is accepted while it keeps one signature throughout.
  * @returns Reshaped copies of `events`, in input order.
- * @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].
+ * @throws If `ts` changes signature, 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';
@@ -1603,7 +1619,10 @@ declare function pickProgressionPreset(style: ProgStyle, ctx?: GenerationContext
  * the secondary dominant (V7) of the following chord, flagged with
  * `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.
+ * no dominant of its own, and a dominant seventh the key already contains
+ * (the tonic seventh of mixolydian) is a native chord rather than an applied
+ * one, so it is not inserted. A chord that already sounds a dominant seventh
+ * onto the next one is left as written.
  *
  * @param opts Generation options.
  * @returns One chord per bar in timeline order.
@@ -1674,7 +1693,7 @@ type HarmonizePlacement = {
  * @category Reharmonization
  */
 type HarmonizeOptions = {
-    /** The melody to harmonize, in ascending onset order. */
+    /** The melody to harmonize, in any order; it is read in onset order. */
     melody: readonly MelodyNote[];
     /**
      * The key to harmonize in, or `'infer'` to estimate it from the melody's
@@ -1805,6 +1824,267 @@ type HarmonizeResult = {
     }[];
 };
 
+/**
+ * A composition plan: what a piece is going to be, before any note is chosen.
+ *
+ * Where a {@link ReferenceProfile} records what an existing piece did, a plan
+ * records what a new one will do — the same structural dimensions (form,
+ * harmony, motif derivation, rhythm), stated as targets a generator can hit
+ * exactly rather than as a reading to approximate. A plan is plain data,
+ * JSON-serializable end to end, and it carries the seed and algorithm version
+ * a generator needs to reproduce the piece it describes: the plan is the
+ * recipe, not a cache of one run of it.
+ */
+
+/**
+ * Schema version {@link CompositionPlan} is written at.
+ *
+ * {@link assertCompositionPlan} rejects any other value outright rather than
+ * guess at an older shape a caller's stored JSON might be in.
+ *
+ * @category Composition
+ */
+declare const COMPOSITION_PLAN_VERSION = 1;
+/**
+ * What a new piece is going to be: its keys, meter and span, the sections and
+ * phrases it is built from, the harmony and motif derivations a generator
+ * fills those phrases with, and the rhythmic target it aims for.
+ *
+ * @category Composition
+ */
+type CompositionPlan = {
+    /** Schema version this record is written at; see {@link COMPOSITION_PLAN_VERSION}. */
+    planVersion: number;
+    /** The project seed a generator following this plan draws from. */
+    seed: number;
+    /** The algorithm version a generator following this plan runs under. */
+    algorithmVersion: number;
+    /** Keys the piece passes through; index 0 is the home key harmony is read against by default. */
+    keys: ResolvedKey[];
+    /** The piece's meter across the planned span. */
+    meters: MeterMap;
+    /** The planned span. */
+    span: {
+        startBeat: number;
+        endBeat: number;
+        bars: number;
+    };
+    /** Sections, in time order. */
+    sections: PlannedSection[];
+    /** Phrases, in time order. */
+    phrases: PlannedPhrase[];
+    /** The harmonic progression, as a partition of the span. */
+    harmony: PlannedChord[];
+    /** Motifs and how they derive from one another. */
+    motifs: PlannedMotif[];
+    /** The rhythmic target a generator's onset placement aims for. */
+    rhythm: PlannedRhythm;
+};
+/**
+ * One planned section: a labelled span of the piece.
+ *
+ * @category Composition
+ */
+type PlannedSection = {
+    /** The section's label. */
+    label: string;
+    /** First beat of the section. */
+    startBeat: number;
+    /** End of the section, exclusive. */
+    endBeat: number;
+};
+/**
+ * One planned phrase: its span, the section it opens in, the cadence and
+ * melodic shape it targets, and the motifs it carries.
+ *
+ * @category Composition
+ */
+type PlannedPhrase = {
+    /** First beat of the phrase. */
+    startBeat: number;
+    /** End of the phrase, exclusive. */
+    endBeat: number;
+    /** Index into `plan.sections` of the section this phrase's start beat falls in. */
+    section: number | null;
+    /** The cadence the phrase is to end on, or null for none. */
+    cadence: CadenceType | null;
+    /** The phrase's targeted melodic shape. */
+    shape: MelodicContourShape;
+    /** Onset of the phrase's targeted peak, as a fraction of the phrase's length, in [0, 1]. */
+    peakPosition: number;
+    /** The phrase's targeted pitch range and mean, as absolute MIDI pitches. */
+    register: {
+        low: number;
+        high: number;
+        mean: number;
+    };
+    /** Targeted onsets per bar within the phrase; see {@link RhythmAnalysis.onsetDensity}. */
+    onsetDensity: number;
+    /** Indices into `plan.motifs` of every motif statement placed in this phrase. */
+    motifs: number[];
+};
+/**
+ * One planned chord, placed against one of the plan's keys.
+ *
+ * @category Composition
+ */
+type PlannedChord = {
+    /** First beat of the chord. */
+    startBeat: number;
+    /** End of the chord, exclusive. */
+    endBeat: number;
+    /** Index into `plan.keys` of the key this chord is named against. */
+    key: number;
+    /** The chord, as a Roman numeral in that key. */
+    roman: string;
+};
+/**
+ * One planned motif statement: a root the generator writes new notes for, or a
+ * derivation the generator obtains from an earlier statement by a named
+ * transformation.
+ *
+ * @category Composition
+ */
+type PlannedMotif = {
+    /** Index into `plan.phrases` of the phrase this statement is placed in. */
+    phrase: number;
+    /** First beat of the statement. */
+    startBeat: number;
+    /** End of the statement, exclusive. */
+    endBeat: number;
+    /** How many notes the statement carries; a root's generated length, a derivation's inherited from its source. */
+    notes: number;
+    /**
+     * A root's onset-to-onset gaps in beats, `notes - 1` of them, summing to
+     * less than the statement's length: its reference motif's ratios times
+     * {@link ReferenceMotif.unitBeats}. The first note sounds at `startBeat`
+     * and the last lasts to `endBeat`. Null for a root whose onsets a generator
+     * draws from `plan.rhythm`; always null for a derivation, whose rhythm is
+     * its source's under the named transformation.
+     */
+    rhythm: number[] | null;
+    /** Index into `plan.motifs` of the statement this one derives from; null for a root. Always less than this statement's own index. */
+    from: number | null;
+    /**
+     * The named transformation from `from`, or null for a root, or for a
+     * derivation with no named transformation (a variation). Its `semitones`
+     * and `degrees` are the preferred pitch level: a generator may place the
+     * derivation at another level to keep it inside the register and the harmony.
+     */
+    relation: MotifRelationSummary | null;
+};
+/**
+ * The rhythmic target a generator's onset placement aims for.
+ *
+ * @category Composition
+ */
+type PlannedRhythm = {
+    /** Targeted distribution of onsets across metric levels; see {@link RhythmAnalysis.onsetLevels}. */
+    onsetLevels: number[];
+    /** Targeted distribution of inter-onset intervals; see {@link RhythmAnalysis.interOnsetShares}. */
+    interOnsetShares: number[];
+    /** Targeted syncopation, in [0, 1]; see {@link RhythmAnalysis.syncopation}. */
+    syncopation: number;
+};
+
+/**
+ * Melody generation from a {@link CompositionPlan}.
+ *
+ * The plan is a hard constraint where the generator is free: every root, every
+ * span no motif covers and every closing note keeps its phrase's register and
+ * offers only the pitches its position class admits — a chord tone on a strong
+ * pulse, a scale tone on a weak one or on a strong one where no chord is
+ * planned, anything in the register off the pulses.
+ * A derived statement is its source replayed through the named relation at the
+ * pitch level that suits its phrase best; there the transformation outranks
+ * the harmony, and the register outranks both. A root takes its plan's onset
+ * gaps, or onsets drawn toward the plan's onset levels and gap shares, and pitches from a
+ * chain search toward the phrase's target curve; each phrase closes on a note
+ * held from its final bar to its end, bent onto its cadence.
+ *
+ * Every draw is addressed by phrase index and absolute beat, and a phrase
+ * reads only its own plan entries and the statements its derivations lead
+ * back to, so changing one phrase's plan leaves every phrase that does not
+ * derive from it sounding as it did.
+ */
+
+/**
+ * Options controlling {@link generateMelody}.
+ *
+ * @category Composition
+ */
+type MelodyOptions = {
+    /**
+     * The generation context. Its `seed` and `algorithmVersion` take precedence
+     * over the plan's; whatever it leaves out is read from the plan. A supplied
+     * `rng` is rejected: every onset and tie-break is drawn at an address of
+     * phrase and beat under a seed, which a caller-held source cannot provide.
+     *
+     * @defaultValue the plan's seed and algorithm version
+     */
+    ctx?: GenerationContextInput;
+    /** Upper bound on the onset grid and on the pitch search. */
+    budget?: number;
+};
+/**
+ * Write a melody that follows a composition plan.
+ *
+ * Each phrase is written inside its planned register, and every note the
+ * generator chooses freely takes a pitch its position class admits: a chord
+ * tone on a strong pulse, a scale tone on a weak one, any pitch off the pulses.
+ * A root motif takes the onset gaps its plan carries from its start, its last
+ * note lasting to its end, or onsets drawn one after another on the sixteenth
+ * grid toward the plan's onset levels and gap shares; its pitches come from a chain
+ * search that moves by step, recovers from leaps and follows the phrase's
+ * target shape. A derived motif replays its planned relation on the statement
+ * it derives from, starting on its planned beat, at the pitch level inside the
+ * register that best fits the harmony, the target curve and the planned level;
+ * a harmony misfit it keeps is left, and only notes no level brings inside the
+ * register are replaced. A variation keeps its source's rhythm and outer
+ * pitches. The spans no motif covers get drawn onsets at the phrase's density
+ * and searched pitches. In each phrase's final bar, the note sounding at the
+ * downbeat (or the first onset after it) is held to the phrase's end, later
+ * onsets are dropped, and that note is bent onto the tones the phrase's
+ * cadence asks for; a note sounding across the downbeat is cut there, and the
+ * downbeat becomes the held onset, re-chosen from the pitches the downbeat
+ * admits unless a cadence or a derived statement decides it. Onsets fall on the sixteenth grid only, so
+ * triplets never appear.
+ *
+ * Harmony is read from the plan alone, through {@link planTimeline}.
+ *
+ * @param plan The plan to follow; validated first.
+ * @param opts Context and budget.
+ * @returns The melody, in time order.
+ * @throws {InvalidInputError} If the plan, the options or the context are
+ *   malformed, or the context supplies an `rng`.
+ * @throws {NoSolutionError} If a phrase's register admits no line, no pitch a
+ *   position asks for, no pitch that ends its cadence, or a span more onsets
+ *   than its grid holds; `at` is the phrase's start beat.
+ * @throws {BudgetExceededError} If the onset grid or the pitch search would
+ *   exceed the budget.
+ * @example
+ * ```ts
+ * import { generateMelody, resolveKey } from '@libraz/libcantus';
+ * import type { CompositionPlan } from '@libraz/libcantus';
+ * const plan: CompositionPlan = {
+ *   planVersion: 1, seed: 7, algorithmVersion: 1,
+ *   keys: [resolveKey('C major')], meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
+ *   span: { startBeat: 0, endBeat: 8, bars: 2 },
+ *   sections: [{ label: 'A', startBeat: 0, endBeat: 8 }],
+ *   phrases: [{
+ *     startBeat: 0, endBeat: 8, section: 0, cadence: 'authentic', shape: 'arch', peakPosition: 0.6,
+ *     register: { low: 60, high: 72, mean: 66 }, onsetDensity: 4, motifs: [0],
+ *   }],
+ *   harmony: [{ startBeat: 0, endBeat: 4, key: 0, roman: 'V' }, { startBeat: 4, endBeat: 8, key: 0, roman: 'I' }],
+ *   motifs: [{ phrase: 0, startBeat: 0, endBeat: 4, notes: 4, rhythm: [1, 1, 1], from: null, relation: null }],
+ *   rhythm: { onsetLevels: [0, 0, 0, 0, 0, 1], interOnsetShares: new Array(17).fill(0).fill(1, 8, 9), syncopation: 0 },
+ * };
+ * generateMelody(plan); // the same notes on every call
+ * ```
+ * @category Composition
+ */
+declare function generateMelody(plan: CompositionPlan, opts?: MelodyOptions): NoteEvent[];
+
 /**
  * A transformation applicable to a motif cell.
  *
@@ -2058,7 +2338,8 @@ type OrnamentOptions = {
     amount?: number;
     /**
      * Time signature, in any form that names one, used to tell strong positions
-     * from weak ones.
+     * from weak ones. A meter map is read bar by bar, so a note after a change
+     * is weighed in the signature in force where it sounds.
      *
      * @defaultValue 4/4
      */
@@ -2109,6 +2390,227 @@ type OrnamentOptions = {
  */
 declare function ornament(notes: readonly NoteEvent[], opts?: OrnamentOptions): NoteEvent[];
 
+/**
+ * Deriving a {@link CompositionPlan} from a {@link ReferenceProfile}.
+ *
+ * Each structural dimension of the reference is either carried into the plan
+ * or replaced, weighted per dimension by {@link PreserveWeights}. A discrete
+ * item (a section label, a phrase length, a structural chord, a motif
+ * derivation) is kept or replaced whole by a positional draw addressed by that
+ * item's index, so changing one weight or one item never redraws another; a
+ * replacement follows a fixed rule. A continuous item (harmonic rhythm,
+ * register and contour, onset placement) is interpolated between the
+ * reference's value and a neutral one.
+ *
+ * The reference's melodic surface — its motif intervals and phrase outlines —
+ * never reaches the plan: a plan says how motifs derive from one another and
+ * carries a root's onset gaps, not the pitches it sounds.
+ */
+
+/**
+ * How much of each structural dimension of a reference a derived plan keeps,
+ * each in [0, 1]; an omitted weight is 1.
+ *
+ * @category Composition
+ */
+type PreserveWeights = {
+    /** Section labels; a replaced section takes its neighbour's label. */
+    form?: number;
+    /** Phrase lengths; a replaced phrase is rounded to a power-of-two bar count. */
+    phraseLengths?: number;
+    /** Structural chords; a replaced chord is another numeral of the same function. */
+    harmonicFunction?: number;
+    /** Where the chords change, interpolated toward one change per bar line. */
+    harmonicRhythm?: number;
+    /** Motif derivations; a replaced derivation becomes a variation of the same source. */
+    motifRelations?: number;
+    /** Phrase contour, peak and register, interpolated toward a neutral arch. */
+    registerShape?: number;
+    /**
+     * Each root's onset gaps, kept per root by a positional draw, and the
+     * onset placement, interpolated toward a level-proportional distribution
+     * without syncopation.
+     */
+    rhythm?: number;
+};
+/**
+ * Options for {@link deriveCompositionPlan}.
+ *
+ * @category Composition
+ */
+type CompositionPlanOptions = {
+    /**
+     * The home key of the plan. Every reference key moves by the interval from
+     * the reference's home tonic to this one, keeping its own variant. Defaults
+     * to the reference's home key; a key of another variant is rejected.
+     */
+    key?: KeyLike;
+    /**
+     * The melody range the plan's phrase registers are mapped onto. Defaults to
+     * the reference's melody range, moved by the nearest shift to the new key.
+     */
+    register?: {
+        low: number;
+        high: number;
+    };
+    /** How much of each dimension of the reference to keep; see {@link PreserveWeights}. */
+    preserve?: PreserveWeights;
+    /**
+     * The seed and algorithm version the plan records. A caller-supplied `rng`
+     * is rejected: a plan has to carry its source as a seed to be reproducible.
+     */
+    ctx?: GenerationContextInput;
+    /** Upper bound on the motif selection. */
+    budget?: number;
+};
+/**
+ * Derive a composition plan from a reference profile.
+ *
+ * The plan keeps the reference's meter and span. Its keys are the reference's,
+ * moved to `opts.key` with each key's variant kept, and its phrase registers
+ * are the reference's mapped onto `opts.register`. Each dimension named in
+ * `opts.preserve` is kept, replaced or interpolated by its weight; a draw for
+ * a discrete item is addressed by the dimension and the item's index, so the
+ * same reference, options and seed always give the same plan. The resolved
+ * seed and algorithm version are recorded in the plan.
+ *
+ * @param reference The reference profile to derive from.
+ * @param opts The key, register, preserve weights, generation context and budget.
+ * @returns A plan that passes {@link assertCompositionPlan}.
+ * @throws {InvalidInputError} If the reference is not a valid profile or has
+ *   no melody onsets, an option is out of range, `opts.key` is of another
+ *   variant than the reference's home key, `opts.ctx` carries an `rng`, or the
+ *   default register moved to the new key leaves the MIDI range.
+ * @throws {BudgetExceededError} If the motif selection would exceed the budget.
+ * @category Composition
+ */
+declare function deriveCompositionPlan(reference: ReferenceProfile, opts?: CompositionPlanOptions): CompositionPlan;
+
+/**
+ * Checking a candidate melody against the plan it was written for.
+ *
+ * The candidate is read against the plan itself, never re-analyzed: its
+ * phrases are the plan's phrases, its harmony is the plan's through
+ * `planTimeline`, and its derivations are replayed from the candidate's own
+ * source statements. What comes back is never one score: a list of concrete
+ * violations (which are errors and which are only warnings), and a fit reading
+ * per dimension, each measured the way {@link compareReferences} measures two
+ * profiles against each other. Whether the piece is any good is left to the ear.
+ */
+
+/**
+ * One way a candidate melody departs from its plan.
+ *
+ * @category Composition
+ */
+type CompositionViolation = {
+    /** What kind of departure this is. */
+    kind: 'span' | 'phraseBoundary' | 'cadence' | 'harmony' | 'motifDerivation' | 'motifDisplaced' | 'register' | 'peakPosition';
+    /** Whether this rules the candidate out, or only flags it. */
+    severity: 'error' | 'warning';
+    /** Where in the candidate this was found. */
+    atBeat: number;
+    /** What the plan called for. */
+    expected: string;
+    /** What the candidate did instead. */
+    actual: string;
+    /** Why this counts as a departure. */
+    rationale: string;
+};
+/**
+ * How a candidate melody measures up against its plan: violations that judge
+ * it, and a fit reading per structural dimension.
+ *
+ * There is no aggregate: the fields never fold into one score, the same way
+ * {@link ReferenceComparison} does not.
+ *
+ * @category Composition
+ */
+type CompositionEvaluation = {
+    /** Concrete departures from the plan, error and warning alike. */
+    violations: CompositionViolation[];
+    /** Likeness of the candidate to the plan, one field per dimension, each phrase read over its planned span. */
+    fit: {
+        /** Likeness of the phrases' melodic outlines to their planned shapes. */
+        contour: number | null;
+        /** Likeness of the phrases' registers to the planned ones. */
+        register: number | null;
+        /** Likeness of where the melody's onsets fall. */
+        onset: number | null;
+        /** Likeness of the melody's inter-onset-interval distribution. */
+        duration: number | null;
+        /** Likeness of the melody's syncopation. */
+        syncopation: number | null;
+        /** Likeness of the melody's onsets per bar to the phrases' planned densities. */
+        density: number | null;
+    };
+};
+/** Options for {@link evaluateComposition}. */
+type EvaluateCompositionOptions = {
+    /**
+     * Upper bound on the work each analysis may do.
+     *
+     * @defaultValue {@link DEFAULT_GENERATION_BUDGET}
+     */
+    budget?: number;
+};
+/**
+ * Check a candidate melody against the plan it was written for.
+ *
+ * The candidate is read against the plan itself — its phrases, its harmony
+ * through {@link planTimeline}, its derivations — rather than re-analyzed into
+ * a profile, so every violation and fit reading judges the melody against what
+ * the plan actually calls for.
+ *
+ * Violations name concrete departures at a beat. `span`, `phraseBoundary`,
+ * `cadence`, `register` and `motifDerivation` are errors. `harmony` is an
+ * error, or a warning for a note inside a derived statement, where the
+ * transformation takes precedence. A derived statement passes at any pitch
+ * level its relation admits, with its durations free and its closing and
+ * out-of-register notes excused; `motifDisplaced` warns when that level is not
+ * the planned one or a note was excused. `peakPosition` is a warning. The fit
+ * fields, one per dimension, read each planned phrase of the candidate the way
+ * a reference profile reads its phrases and measure it as
+ * {@link compareReferences} would — never folded into one score.
+ *
+ * @param melody The candidate melody.
+ * @param plan The plan it was written for.
+ * @param opts The work budget.
+ * @returns The violations found and the fit reading.
+ * @throws {InvalidInputError} If the plan or the melody cannot be read.
+ * @throws {BudgetExceededError} If an analysis would exceed the budget.
+ * @example
+ * ```ts
+ * import { evaluateComposition, planTimeline, resolveKey } from '@libraz/libcantus';
+ * import type { CompositionPlan } from '@libraz/libcantus';
+ * const plan: CompositionPlan = {
+ *   planVersion: 1, seed: 0, algorithmVersion: 1,
+ *   keys: [resolveKey('C major')],
+ *   meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
+ *   span: { startBeat: 0, endBeat: 4, bars: 1 },
+ *   sections: [{ label: 'A', startBeat: 0, endBeat: 4 }],
+ *   phrases: [
+ *     {
+ *       startBeat: 0, endBeat: 4, section: 0, cadence: null, shape: 'ascending',
+ *       peakPosition: 0.5, register: { low: 60, high: 67, mean: 64 }, onsetDensity: 4, motifs: [],
+ *     },
+ *   ],
+ *   harmony: [{ startBeat: 0, endBeat: 4, key: 0, roman: 'I' }],
+ *   motifs: [],
+ *   rhythm: { onsetLevels: [0, 0, 0, 1, 0, 0], interOnsetShares: new Array(17).fill(0).fill(1, 8, 9), syncopation: 0 },
+ * };
+ * const melody = [
+ *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *   { pitch: 64, startBeat: 1, durationBeat: 1 },
+ *   { pitch: 67, startBeat: 2, durationBeat: 1 },
+ *   { pitch: 60, startBeat: 3, durationBeat: 1 },
+ * ];
+ * evaluateComposition(melody, plan).violations; // []
+ * ```
+ * @category Composition
+ */
+declare function evaluateComposition(melody: readonly NoteEvent[], plan: CompositionPlan, opts?: EvaluateCompositionOptions): CompositionEvaluation;
+
 /**
  * Reharmonization: chord substitution, modal-interchange palettes, and negative
  * harmony. These transforms take an existing chord (or a key) and propose
@@ -2182,8 +2684,9 @@ type SubstituteOptions = {
  * tritone substitute of G7 formats as `Db7` and its chromatic mediants as `Bb`
  * and `Eb`. Where the substitution's function and the bare pitch class disagree,
  * the function decides — a tritone substitute is a bII7 and so is written on the
- * flattened supertonic of the chord it resolves to, and a borrowed chord takes
- * the spelling of the mode it is borrowed from.
+ * flattened supertonic of the chord it resolves to, a borrowed chord takes the
+ * spelling of the mode it is borrowed from, and a chromatic mediant is written
+ * on the letter a third from the source root (E's mediants are G#, not Ab).
  *
  * @param chord The chord to reharmonize, as a chord symbol or as chord data.
  * @param key The prevailing key, as a key name or as a key/scale.
@@ -2300,7 +2803,8 @@ 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].
+ * @throws If the pitch or the velocity is not a whole MIDI value in [0, 127], or an event is not
+ *   a record with a finite position and duration.
  * @example
  * ```ts
  * import { generateRhythm, humanize, rhythmToNoteEvents } from '@libraz/libcantus';
@@ -2386,4 +2890,5 @@ declare function generateRhythm(ts: MeterLike, opts?: RhythmOptions): RhythmEven
  */
 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 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 };
+export { BAR_STEPS as B, COMPOSITION_PLAN_VERSION as C, DRUM_NOTES as D, GENRES as G, ORNAMENT_STYLES as T, PROVENANCE_BASES as W, BASS_STYLES as a, generateRhythm as aA, gridMetricWeight as aB, halfTime as aC, humanize as aD, mergeVocabulary as aE, modalInterchangePalette as aF, motifToNoteEvents as aG, negativeHarmonyMirror as aH, onsetWeightCurve as aI, ornament as aJ, ornamentBy as aK, pickProgressionPreset as aL, pickVocabulary as aM, progressions as aN, progressionsByStyle as aO, resolveContext as aP, rhythmDensity as aQ, rhythmToNoteEvents as aR, selectVocabulary as aS, substituteChord as aT, syncopate as aU, thin as aV, transformMotif as aW, vocabularyOfKind as aX, withinCeiling as aY, STEP_BEATS as ab, applyGrooveTemplate as aj, assertVocabulary as ak, deform as al, deriveCompositionPlan as am, developMotif as an, double as ao, doubleTime as ap, drumVoiceOf as aq, evaluateComposition as ar, extractGrooveTemplate as as, fitsQuery as at, generateBassLine as au, generateCounterMelody as av, generateDrums as aw, generateMelody as ax, generateMotif as ay, generateProgression as az, BEAT_STEPS as b, BORROWED_DEGREES as c };
+export type { PlannedSection as $, GrooveSlot as A, EuclideanKick as E, GrooveStyle as F, GrooveTemplate as H, HarmonizeOptions as I, HarmonizePlacement as J, HarmonizeResult as K, HumanizeOptions as L, MelodyNote as M, MelodyOptions as N, MotifCell as O, MotifContour as P, MotifNote as Q, MotifOptions as R, MotifTransform as S, OrnamentOptions as U, OrnamentStyle as V, PlannedChord as X, PlannedMotif as Y, PlannedPhrase as Z, PlannedRhythm as _, PreserveWeights as a0, ProgFunction as a1, ProgStyle as a2, ProgressionDegree as a3, ProgressionOptions as a4, ProgressionPreset as a5, Provenance as a6, ProvenanceBasis as a7, ResolvedContext as a8, RhythmEvent as a9, RhythmOptions as aa, Section as ac, SubstituteOptions as ad, Substitution as ae, SubstitutionType as af, SyncopateOptions as ag, Vocabulary as ah, VocabularyQuery as ai, BassLineOptions as d, BassSegment as e, BassStyle as f, BorrowedChord as g, Complexity as h, CompositionEvaluation as i, CompositionPlan as j, CompositionPlanOptions as k, CompositionViolation as l, CounterMelodyOptions as m, DeformOptions as n, Draw as o, DrumHit as p, DrumRole as q, DrumStyle as r, DrumVoice as s, DrumsOptions as t, EvaluateCompositionOptions as u, GenerationContext as v, GenerationContextInput as w, Genre as x, GridEvent as y, GrooveFeel as z };