@libraz/libcantus 0.9.0 → 0.9.2

package/src/{drums → generate/drums}/index.ts

@@ -7,6 +7,7 @@ import {
   generateSnareForBeat,
   type SectionCtx,
 } from './beat.js';
+import { euclideanRhythm, patternToMask } from './euclid.js';
 import { type FillType, generateFill, getFillStartBeat, selectFillType } from './fills.js';
 import {
   footHiHatVelocity,
@@ -34,28 +35,106 @@ import {
   sectionDensityMultiplier,
   sectionEnergy,
 } from './internal.js';
-import { getKickPattern, isInPreChorusLift, type KickPattern } from './kick.js';
+import {
+  euclideanToKickPattern,
+  getKickPattern,
+  isInPreChorusLift,
+  type KickPattern,
+} from './kick.js';
 import { generateAuxPercussionForBar, getPercussionConfig } from './percussion.js';
 import { createRng } from './rng.js';
 
+/**
+ * A single drum onset emitted by {@link generateDrums}.
+ *
+ * @category Composition
+ */
 export type { DrumHit } from './hit.js';
+
+/**
+ * Groove feel (the swing/straight rhythmic character) for {@link generateDrums}.
+ *
+ * @category Composition
+ */
 export type GrooveFeel = Feel;
+
+/**
+ * Drum voicing role and groove style identifiers for {@link generateDrums}.
+ *
+ * @category Composition
+ */
 export type { DrumRole, GrooveStyle } from './internal.js';
 
-/** Public section identifiers for {@link generateDrums}. */
+/**
+ * Public section identifiers for {@link generateDrums}.
+ *
+ * @category Composition
+ */
 export type Section = PublicSection;
 
-/** Options controlling {@link generateDrums}. */
-export type DrumGenOptions = {
+/**
+ * A Euclidean (Bjorklund) kick pattern for {@link generateDrums}.
+ *
+ * @category Composition
+ */
+export type EuclideanKick = {
+  /** Number of kick onsets, clamped to `[0, steps]`. */
+  pulses: number;
+  /**
+   * Total steps in the bar (1..16).
+   *
+   * @defaultValue 16
+   */
+  steps?: number;
+  /**
+   * Steps to rotate the onsets toward later positions.
+   *
+   * @defaultValue 0
+   */
+  rotation?: number;
+};
+
+/**
+ * Options controlling {@link generateDrums}.
+ *
+ * @category Composition
+ */
+export type DrumsOptions = {
   bars: number;
   bpm: number;
   style: GrooveStyle;
   section: Section;
   density: number;
+  /**
+   * Replace the final bar with a fill.
+   *
+   * @defaultValue false
+   */
   fills?: boolean;
   feel?: GrooveFeel;
+  /**
+   * Voicing role; `'fxOnly'` suppresses the main kick/snare/ghost/fill voices.
+   *
+   * @defaultValue `'full'`
+   */
   role?: DrumRole;
+  /**
+   * Seed for the deterministic PRNG.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
+  /**
+   * Section the final-bar fill leads into. Shapes which fill archetype is
+   * chosen (into-chorus and out-of-intro fills differ from generic ones).
+   * Defaults to `section`, i.e. a within-section fill.
+   */
+  nextSection?: Section;
+  /**
+   * When set, the kick follows this Euclidean rhythm instead of the
+   * style/section pattern, giving direct access to evenly spread onsets.
+   */
+  euclideanKick?: EuclideanKick;
 };
 
 /**
@@ -66,13 +145,25 @@ export type DrumGenOptions = {
  * by its General MIDI pitch. Groove style selects an internal style and feel;
  * `density` sets the backing-density level; `section` shapes kick, hi-hat, ghost,
  * and percussion density. 16th-note hi-hats drop to 8ths at or above 150 BPM.
- * When `fills` is true the final bar is replaced with a fill. Output is fully
+ * When `fills` is true the final bar is replaced with a fill whose archetype is
+ * shaped by `nextSection`; a fill that would emit nothing on its beat falls back
+ * to the normal groove so the phrase end is never silent. `euclideanKick`
+ * overrides the kick with an evenly-spread Euclidean pattern. Output is fully
  * determined by the options plus `seed`.
  *
  * @param opts Generation options.
  * @returns Percussion onsets in bar order.
+ *
+ * @example
+ * ```ts
+ * import { generateDrums } from '@libraz/libcantus';
+ * const hits = generateDrums({ bars: 4, bpm: 120, style: 'standard', section: 'chorus', density: 0.6, fills: true });
+ * // Fully determined by the options plus seed (defaults to 0).
+ * ```
+ *
+ * @category Composition
  */
-export function generateDrums(opts: DrumGenOptions): DrumHit[] {
+export function generateDrums(opts: DrumsOptions): DrumHit[] {
   const track = new HitList();
   const rng = createRng(opts.seed ?? 0);
   const mapping = mapStyle(opts.style);
@@ -114,6 +205,23 @@ export function generateDrums(opts: DrumGenOptions): DrumHit[] {
   const fillStartBeat = getFillStartBeat(energy);
   const percMood = percMoodCategory(style);
 
+  // The final-bar fill is shaped by the section it leads into. When no next
+  // section is given the fill is treated as within-section (from === to).
+  const nextSection = opts.nextSection ? mapSection(opts.nextSection) : section;
+  const nextEnergy = sectionEnergy(nextSection);
+
+  const euclidKick: KickPattern | undefined = opts.euclideanKick
+    ? euclideanToKickPattern(
+        patternToMask(
+          euclideanRhythm(
+            opts.euclideanKick.pulses,
+            opts.euclideanKick.steps ?? 16,
+            opts.euclideanKick.rotation ?? 0,
+          ),
+        ),
+      )
+    : undefined;
+
   const reuseSectionKick = (section === 'b' || section === 'chorus') && style !== 'sparse';
   let sectionKick: KickPattern | undefined;
 
@@ -133,7 +241,9 @@ export function generateDrums(opts: DrumGenOptions): DrumHit[] {
     }
 
     let kick: KickPattern;
-    if (reuseSectionKick) {
+    if (euclidKick) {
+      kick = euclidKick;
+    } else if (reuseSectionKick) {
       sectionKick ??= getKickPattern(section, style, 0, rng);
       kick = sectionKick;
     } else {
@@ -149,12 +259,20 @@ export function generateDrums(opts: DrumGenOptions): DrumHit[] {
 
       if (opts.fills && isLastBar && !inLift && beat >= fillStartBeat) {
         if (beat === fillStartBeat) {
-          currentFill = selectFillType(section, section, style, energy, rng);
+          currentFill = selectFillType(section, nextSection, style, nextEnergy, rng);
         }
         if (playMainVoices) {
+          const before = track.hits.length;
           generateFill(track, beatTick, beat, currentFill, velocity);
+          if (track.hits.length > before) {
+            continue;
+          }
+          // Safety net: an archetype that contributes nothing on this beat would
+          // leave a silent phrase end, so fall through to the normal groove.
+        } else {
+          // fxOnly deliberately emits no main voices on the fill beats.
+          continue;
         }
-        continue;
       }
 
       const ctx: BeatCtx = {

package/src/{drums → generate/drums}/internal.ts

@@ -67,7 +67,9 @@ export type GrooveStyle =
   | 'bossa'
   | 'trap'
   | 'halftime'
-  | 'breakbeat';
+  | 'breakbeat'
+  | 'house'
+  | 'synthpop';
 
 /** Public role identifiers gating which voices are present. */
 export type DrumRole = 'full' | 'ambient' | 'minimal' | 'fxOnly';
@@ -92,6 +94,10 @@ const STYLE_MAP: Record<GrooveStyle, StyleMapping> = {
   trap: { style: 'trap', feel: 'straight', ghostBoost: false, snareBeat3: true },
   halftime: { style: 'sparse', feel: 'straight', ghostBoost: false, snareBeat3: true },
   breakbeat: { style: 'rock', feel: 'straight', ghostBoost: false, snareBeat3: false },
+  // Four-on-the-floor dance kick with idol-style auxiliary percussion.
+  house: { style: 'fourOnFloor', feel: 'straight', ghostBoost: false, snareBeat3: false },
+  // Synth-pop pulse with denser 16th hi-hats and busy kick syncopation.
+  synthpop: { style: 'synth', feel: 'straight', ghostBoost: true, snareBeat3: false },
 };
 
 /** Resolve the internal style/feel parameters for a public groove style. */

package/src/{drums → generate/drums}/rng.ts

@@ -3,5 +3,5 @@
  * `DrumRng` is retained as the drum-facing name of the shared {@link Rng} type.
  */
 
-export type { Rng as DrumRng } from '../random/index.js';
-export { createRng } from '../random/index.js';
+export type { Rng as DrumRng } from '../../core/random/index.js';
+export { createRng } from '../../core/random/index.js';

package/src/{drums → generate/drums}/swing.ts

@@ -53,8 +53,13 @@ export function quantizeSwing(
       return base + EIGHTH + DELTA_8 * clamped;
     }
     if (offset >= EIGHTH + HALF_16TH && offset < 3 * SIXTEENTH + HALF_16TH) {
-      const result = base + EIGHTH + DELTA_8 * clamped + SIXTEENTH + DELTA_16 * clamped;
-      return Math.min(result, base + 1 - 1 / 480);
+      // The "a" 16th is the midpoint of the compressed second half of the beat
+      // (between the swung "and" and the next downbeat), mirroring the "e" 16th
+      // in the first half. Because DELTA_8 = 2 * DELTA_16, that midpoint reduces
+      // to a single DELTA_16 delay off the straight position, so the "a" never
+      // overshoots the downbeat and needs no clamp. At the default shuffle feel
+      // (swing 0.75) this lands near 0.8125 rather than the doubly-swung 0.9375.
+      return base + 3 * SIXTEENTH + DELTA_16 * clamped;
     }
     return startBeat;
   }

package/src/{groove → generate/groove}/index.ts

@@ -8,23 +8,56 @@
  * seeded PRNG from the `random` module so results are fully reproducible.
  */
 
-import { beatsPerBar, metricWeight, type TimeSignature } from '../meter/index.js';
-import { createRng } from '../random/index.js';
-import type { NoteEvent } from '../types.js';
+import {
+  beatsPerBar,
+  formatTimeSignature,
+  metricWeight,
+  type TimeSignature,
+} from '../../core/meter/index.js';
+import { createRng } from '../../core/random/index.js';
+import type { NoteEvent } from '../../core/types.js';
 
-/** Options controlling {@link humanize}. */
+/**
+ * Options controlling {@link humanize}.
+ *
+ * @category Rhythm & Meter
+ */
 export type HumanizeOptions = {
-  /** Time signature used to derive metric accents. Default 4/4. */
+  /**
+   * Time signature used to derive metric accents.
+   *
+   * @defaultValue 4/4
+   */
   ts?: TimeSignature;
-  /** Maximum timing jitter in quarter-note beats, applied as ±this value. Default 0.02. */
+  /**
+   * Maximum timing jitter in quarter-note beats, applied as ±this value.
+   *
+   * @defaultValue 0.02
+   */
   timing?: number;
-  /** Maximum velocity jitter (MIDI units), applied as ±this value. Default 8. */
+  /**
+   * Maximum velocity jitter (MIDI units), applied as ±this value.
+   *
+   * @defaultValue 8
+   */
   velocity?: number;
-  /** How much louder strong beats get relative to weak ones, in MIDI velocity units. Default 12. */
+  /**
+   * How much louder strong beats get relative to weak ones, in MIDI velocity units.
+   *
+   * @defaultValue 12
+   */
   accent?: number;
-  /** Velocity assumed for events with no `velocity` of their own. Default 80. */
+  /**
+   * Velocity assumed for events with no `velocity` of their own.
+   *
+   * @defaultValue 80
+   */
   baseVelocity?: number;
-  /** Seed for the deterministic PRNG. Default 0. */
+  /**
+   * Seed for the deterministic PRNG.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
 };
 
@@ -56,6 +89,13 @@ const MAX_VELOCITY = 127;
  * @param events The events to humanize.
  * @param opts Humanization options.
  * @returns Humanized copies of `events`, in input order.
+ * @example
+ * ```ts
+ * import { humanize } from '@libraz/libcantus';
+ * const events = [{ pitch: 60, startBeat: 0, durationBeat: 1, velocity: 80 }];
+ * humanize(events, { seed: 1, timing: 0.03 }); // copies with jittered timing and accented velocity
+ * ```
+ * @category Rhythm & Meter
  */
 export function humanize(events: NoteEvent[], opts: HumanizeOptions = {}): NoteEvent[] {
   const ts = opts.ts ?? DEFAULT_TS;
@@ -84,15 +124,27 @@ export function humanize(events: NoteEvent[], opts: HumanizeOptions = {}): NoteE
   });
 }
 
-/** The recorded feel at a single grid slot: an average timing deviation and velocity. */
+/**
+ * The recorded feel at a single grid slot: an average timing deviation and velocity.
+ *
+ * @category Rhythm & Meter
+ */
 export type GrooveSlot = {
   /** Average `actualStartBeat - quantizedBeat` (in quarter-note beats) for events landing on this slot. */
   timingOffset: number;
-  /** Average velocity of events landing on this slot; 0 if none did. */
-  velocity: number;
+  /**
+   * Average velocity of events landing on this slot, or `null` if no event
+   * with a velocity did. `null` (not 0) is the "unrecorded" sentinel so that a
+   * genuine velocity of 0 is preserved and applied like any other value.
+   */
+  velocity: number | null;
 };
 
-/** A per-bar grid of timing and velocity deviations captured from a performance. */
+/**
+ * A per-bar grid of timing and velocity deviations captured from a performance.
+ *
+ * @category Rhythm & Meter
+ */
 export type GrooveTemplate = {
   /** Grid resolution: equal grid steps per quarter-note beat. */
   subdivision: number;
@@ -100,6 +152,13 @@ export type GrooveTemplate = {
   slotsPerBar: number;
   /** One entry per grid slot, in slot-index order (slot 0 is the downbeat). */
   slots: GrooveSlot[];
+  /**
+   * The time signature the template was extracted under. {@link applyGrooveTemplate}
+   * requires the apply-time meter to match this so the per-bar grid lines up
+   * instead of silently drifting. Optional for backward compatibility with
+   * templates constructed without it (in which case no check is performed).
+   */
+  ts?: TimeSignature;
 };
 
 /**
@@ -137,13 +196,16 @@ function quantizeToGrid(
 /**
  * Extract a groove template from a set of note events: for each grid slot,
  * the average timing deviation from the quantized grid and the average
- * velocity of events landing on it. Slots with no events default to
- * `{ timingOffset: 0, velocity: 0 }`.
+ * velocity of events landing on it. Slots with no velocity-carrying event
+ * record `velocity: null` (the "unrecorded" sentinel); empty slots default to
+ * `{ timingOffset: 0, velocity: null }`. The time signature is stored on the
+ * 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 subdivision Grid resolution: equal grid steps per quarter-note beat.
  * @returns The extracted groove template.
+ * @category Rhythm & Meter
  */
 export function extractGrooveTemplate(
   events: NoteEvent[],
@@ -178,36 +240,67 @@ export function extractGrooveTemplate(
   for (let i = 0; i < slotsPerBar; i += 1) {
     const count = counts[i] ?? 0;
     if (count === 0) {
-      slots.push({ timingOffset: 0, velocity: 0 });
+      slots.push({ timingOffset: 0, velocity: null });
       continue;
     }
     const velocityCount = velocityCounts[i] ?? 0;
     slots.push({
       timingOffset: (offsetSums[i] ?? 0) / count,
-      velocity: velocityCount > 0 ? (velocitySums[i] ?? 0) / velocityCount : 0,
+      velocity: velocityCount > 0 ? (velocitySums[i] ?? 0) / velocityCount : null,
     });
   }
 
-  return { subdivision, slotsPerBar, slots };
+  return { subdivision, slotsPerBar, slots, ts };
 }
 
 /**
  * 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
  * timing deviation, pushing stiff timing toward the template's feel.
- * Velocity is set to the slot's recorded average when it recorded any
- * (`velocity > 0`); otherwise the event's own velocity is left untouched.
+ * Velocity is set to the slot's recorded average when it recorded one (a
+ * non-`null` velocity, including a genuine 0); otherwise the event's own
+ * velocity is left untouched.
+ *
+ * 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.
  *
  * @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`.
+ * @example
+ * ```ts
+ * import { extractGrooveTemplate, applyGrooveTemplate, parseTimeSignature } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * // Learn the feel from a loosely played performance...
+ * const groovy = [
+ *   { pitch: 36, startBeat: 0.02, durationBeat: 1, velocity: 100 },
+ *   { pitch: 38, startBeat: 1.06, durationBeat: 1, velocity: 70 },
+ * ];
+ * const template = extractGrooveTemplate(groovy, ts, 4);
+ * // ...then impose it on stiff, quantized events.
+ * const quantized = [{ pitch: 36, startBeat: 0, durationBeat: 1, velocity: 80 }];
+ * applyGrooveTemplate(quantized, template, ts); // events nudged toward the captured feel
+ * ```
+ * @category Rhythm & Meter
  */
 export function applyGrooveTemplate(
   events: NoteEvent[],
   template: GrooveTemplate,
   ts: TimeSignature,
 ): NoteEvent[] {
+  if (
+    template.ts &&
+    (template.ts.numerator !== ts.numerator || template.ts.denominator !== ts.denominator)
+  ) {
+    throw new Error(
+      `Groove template meter ${formatTimeSignature(template.ts)} does not match ` +
+        `apply-time meter ${formatTimeSignature(ts)}`,
+    );
+  }
   const barBeats = beatsPerBar(ts);
   return events.map((event) => {
     const { quantizedBeat, slotIndex } = quantizeToGrid(
@@ -218,7 +311,10 @@ export function applyGrooveTemplate(
     );
     const slot = template.slots[slotIndex];
     const startBeat = quantizedBeat + (slot?.timingOffset ?? 0);
-    const velocity = slot && slot.velocity > 0 ? Math.round(slot.velocity) : event.velocity;
+    const velocity =
+      slot && slot.velocity !== null && slot.velocity !== undefined
+        ? Math.round(slot.velocity)
+        : event.velocity;
 
     return {
       pitch: event.pitch,

package/src/{harmonize → generate/harmonize}/index.ts

@@ -1,31 +1,54 @@
-import type { Chord, ChordQuality } from '../chord/index.js';
-import { chordPitchClasses, diatonicTriad, makeChord } from '../chord/index.js';
-import type { HarmonyRole } from '../harmony/index.js';
-import { roleOf } from '../harmony/index.js';
-import type { TimeSignature } from '../meter/index.js';
-import { isStrongBeat } from '../meter/index.js';
-import type { GeneratedChord } from '../progression/index.js';
-import { isScaleTone, majorKey, scaleTonesInDegreeOrder } from '../scale/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
+import type { TimeSignature } from '../../core/meter/index.js';
+import { isStrongBeat } from '../../core/meter/index.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import type { Chord, ChordQuality } from '../../theory/chord/index.js';
+import { chordPitchClasses, diatonicTriad, makeChord } from '../../theory/chord/index.js';
+import type { HarmonyRole } from '../../theory/harmony/index.js';
+import { roleOf } from '../../theory/harmony/index.js';
+import {
+  isScaleTone,
+  majorKey,
+  minorKey,
+  NATURAL_MINOR_MASK,
+  scaleTonesInDegreeOrder,
+} from '../../theory/scale/index.js';
+import type { ChordSpan } from '../progression/index.js';
 
-/** A melody note supplied to the harmonizer: a {@link NoteEvent}. */
+/**
+ * A melody note supplied to the harmonizer: a {@link NoteEvent}.
+ *
+ * @category Reharmonization
+ */
 export type MelodyNote = NoteEvent;
 
-/** Options controlling {@link harmonizeMelody}. */
+/**
+ * Options controlling {@link harmonizeMelody}.
+ *
+ * @category Reharmonization
+ */
 export type HarmonizeOptions = {
   melody: MelodyNote[];
   key: KeyScale | 'infer';
   harmonicRhythm: number;
   reharmonize: 'diatonic' | 'secondaryDominant' | 'borrowed';
   placement: { transposeSearch: boolean; octaveSearch: boolean };
+  /**
+   * Seed for the deterministic tie-break perturbation.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
 };
 
-/** The chosen transpose, key, chord path, and per-note roles. */
+/**
+ * The chosen transpose, key, chord path, and per-note roles.
+ *
+ * @category Reharmonization
+ */
 export type HarmonizeResult = {
   transposeSemitones: number;
   key: KeyScale;
-  chords: GeneratedChord[];
+  chords: ChordSpan[];
   melodyRoles: { noteIndex: number; role: HarmonyRole }[];
 };
 
@@ -50,6 +73,15 @@ const COMFORT_LOW = 55;
 const COMFORT_HIGH = 79;
 const TESSITURA_WEIGHT = 0.001;
 
+/**
+ * Magnitude of the seed-driven per-candidate perturbation. Kept far below the
+ * smallest real cost difference (transition/emission terms are on the order of
+ * 0.3 and up), so it can only decide between candidates or paths whose costs are
+ * otherwise exactly equal. The seed therefore breaks ties deterministically and
+ * never overrides melody fit or functional flow.
+ */
+const TIE_BREAK_JITTER = 1e-6;
+
 function pitchClass(pitch: number): number {
   return ((Math.trunc(pitch) % 12) + 12) % 12;
 }
@@ -65,28 +97,47 @@ function mulberry32(seed: number): () => number {
   };
 }
 
-/** Estimate the best-fit major key from a melody's pitch-class weighting. */
+/**
+ * Estimate the best-fit key from a melody's pitch-class weighting.
+ *
+ * Both major and natural-minor tonics are scored, so a minor melody is
+ * recognized as its own minor key rather than being folded into the relative
+ * major (which shares identical pitch-class content). Each in-scale note adds
+ * its duration weight; notes matching the candidate tonic add a further
+ * half-weight, and that tonic emphasis is what separates a minor key from its
+ * relative major. For minor candidates the raised leading tone (the
+ * harmonic-minor seventh) also counts as in-scale, so cadential leading tones do
+ * not penalize the true minor key. Ties are broken toward the earlier candidate,
+ * and major is scored before minor at each tonic.
+ */
 function inferKey(melody: MelodyNote[]): KeyScale {
-  let best = 0;
+  let best: KeyScale = majorKey(0);
   let bestScore = Number.NEGATIVE_INFINITY;
+  const candidates: KeyScale[] = [];
   for (let tonic = 0; tonic < 12; tonic += 1) {
-    const key = majorKey(tonic);
+    candidates.push(majorKey(tonic), minorKey(tonic));
+  }
+  for (const key of candidates) {
+    const tonic = pitchClass(key.rootPc);
+    const isMinor = key.modeMask12 === NATURAL_MINOR_MASK;
+    const leadingTone = (tonic + 11) % 12;
     let score = 0;
     for (const n of melody) {
       const w = Math.max(0.25, n.durationBeat);
-      if (isScaleTone(n.pitch, key)) {
+      const pc = pitchClass(n.pitch);
+      if (isScaleTone(n.pitch, key) || (isMinor && pc === leadingTone)) {
         score += w;
       }
-      if (pitchClass(n.pitch) === tonic) {
+      if (pc === tonic) {
         score += 0.5 * w;
       }
     }
     if (score > bestScore) {
       bestScore = score;
-      best = tonic;
+      best = key;
     }
   }
-  return majorKey(best);
+  return best;
 }
 
 /** Enumerate candidate chords for the key, gated by reharmonization strength. */
@@ -283,16 +334,38 @@ function harmonizeOnce(
  * `(transpose, progression)` pair is returned; a small tessitura cost breaks
  * ties toward placements that keep the melody in a comfortable register.
  *
+ * The `seed` drives a deterministic tie-break only: it perturbs candidates by a
+ * magnitude far below any real cost difference (see {@link 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 Melody, key (or `'infer'`), harmonic rhythm, reharmonization
  *   strength, height-search flags, and seed.
  * @returns The chosen transpose, key, chord path, and per-note roles.
+ * @example
+ * ```ts
+ * import { harmonizeMelody, majorKey } from '@libraz/libcantus';
+ * const result = harmonizeMelody({
+ *   melody: [
+ *     { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *     { pitch: 64, startBeat: 1, durationBeat: 1 },
+ *   ],
+ *   key: majorKey(0),
+ *   harmonicRhythm: 1,
+ *   reharmonize: 'diatonic',
+ *   placement: { transposeSearch: false, octaveSearch: false },
+ * });
+ * result.chords; // one ChordSpan per harmonic-rhythm segment
+ * ```
+ * @category Reharmonization
  */
 export function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult {
   const key = opts.key === 'infer' ? inferKey(opts.melody) : opts.key;
   const candidates = buildCandidates(key, opts.reharmonize);
   const candAt = (i: number): Candidate => candidates[i] ?? FALLBACK;
   const rng = mulberry32(opts.seed ?? 0);
-  const jitter = candidates.map(() => rng() * 1e-6);
+  const jitter = candidates.map(() => rng() * TIE_BREAK_JITTER);
 
   const melodyEnd = opts.melody.reduce((m, n) => Math.max(m, n.startBeat + n.durationBeat), 0);
   const hr = Math.max(0.25, opts.harmonicRhythm);
@@ -340,9 +413,9 @@ export function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult {
     }
   }
 
-  const chords: GeneratedChord[] = bestPath.map((ci, s) => {
+  const chords: ChordSpan[] = bestPath.map((ci, s) => {
     const cand = candAt(ci);
-    const chord: GeneratedChord = {
+    const chord: ChordSpan = {
       rootPc: cand.rootPc,
       quality: cand.quality,
       startBeat: segments[s]?.startBeat ?? s * hr,