@libraz/libcantus 0.9.1 → 0.9.3

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

@@ -1,18 +1,22 @@
-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 { isDiatonic, parallelKey } from '../../analyze/functional/index.js';
+import { createNoteEventIndex } from '../../core/event-index/index.js';
+import type { TimeSignature } from '../../core/meter/index.js';
+import { isStrongBeat } from '../../core/meter/index.js';
+import { createRng } from '../../core/random/index.js';
+import type { KeyScale, NoteEvent } from '../../core/types.js';
+import { assertGenerationBudget, assertRange } from '../../core/validation/index.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 '../scale/index.js';
-import type { KeyScale, NoteEvent } from '../types.js';
+} from '../../theory/scale/index.js';
+import type { ChordSpan } from '../progression/index.js';
 
 /**
  * A melody note supplied to the harmonizer: a {@link NoteEvent}.
@@ -48,7 +52,7 @@ export type HarmonizeOptions = {
 export type HarmonizeResult = {
   transposeSemitones: number;
   key: KeyScale;
-  chords: GeneratedChord[];
+  chords: ChordSpan[];
   melodyRoles: { noteIndex: number; role: HarmonyRole }[];
 };
 
@@ -86,17 +90,6 @@ function pitchClass(pitch: number): number {
   return ((Math.trunc(pitch) % 12) + 12) % 12;
 }
 
-function mulberry32(seed: number): () => number {
-  let state = seed >>> 0;
-  return () => {
-    state = (state + 0x6d2b79f5) >>> 0;
-    let t = state;
-    t = Math.imul(t ^ (t >>> 15), t | 1);
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
 /**
  * Estimate the best-fit key from a melody's pitch-class weighting.
  *
@@ -151,7 +144,6 @@ function buildCandidates(key: KeyScale, reharmonize: HarmonizeOptions['reharmoni
     base: 0,
   }));
 
-  const tonic = tones[0] ?? 0;
   if (reharmonize !== 'diatonic') {
     for (const target of [1, 3, 4, 5]) {
       const targetRoot = tones[target] ?? 0;
@@ -166,27 +158,30 @@ function buildCandidates(key: KeyScale, reharmonize: HarmonizeOptions['reharmoni
   }
 
   if (reharmonize === 'borrowed') {
-    candidates.push({
-      rootPc: (tonic + 10) % 12,
-      quality: 'maj',
-      secondaryDominant: false,
-      base: 2,
-    }); // bVII
-    candidates.push({
-      rootPc: (tonic + 8) % 12,
-      quality: 'maj',
-      secondaryDominant: false,
-      base: 2,
-    }); // bVI
-    candidates.push({
-      rootPc: (tonic + 5) % 12,
-      quality: 'min',
-      secondaryDominant: false,
-      base: 2,
-    }); // iv
+    const parallel = parallelKey(key);
+    const parallelTones = scaleTonesInDegreeOrder(parallel);
+    for (let degree = 0; degree < parallelTones.length; degree += 1) {
+      const chord = diatonicTriad(degree, parallel);
+      if (!isDiatonic(chord, key)) {
+        candidates.push({
+          rootPc: chord.rootPc,
+          quality: chord.quality,
+          secondaryDominant: false,
+          base: 1.25,
+        });
+      }
+    }
   }
 
-  return candidates;
+  const seen = new Set<string>();
+  return candidates.filter((candidate) => {
+    const id = `${candidate.rootPc}:${candidate.quality}`;
+    if (seen.has(id)) {
+      return false;
+    }
+    seen.add(id);
+    return true;
+  });
 }
 
 /**
@@ -356,29 +351,45 @@ function harmonizeOnce(
  *   reharmonize: 'diatonic',
  *   placement: { transposeSearch: false, octaveSearch: false },
  * });
- * result.chords; // one GeneratedChord per harmonic-rhythm segment
+ * result.chords; // one ChordSpan per harmonic-rhythm segment
  * ```
  * @category Reharmonization
  */
 export function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult {
+  const noteIndex = createNoteEventIndex(opts.melody);
   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() * TIE_BREAK_JITTER);
+  const rng = createRng(opts.seed ?? 0);
+  const jitter = candidates.map(() => rng.next() * 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);
+  const melodyEnd = noteIndex.notes.reduce((m, n) => Math.max(m, n.endBeat), 0);
+  const requestedHr = assertRange(
+    opts.harmonicRhythm,
+    Number.MIN_VALUE,
+    Number.MAX_SAFE_INTEGER,
+    'harmonic rhythm',
+  );
+  const hr = Math.max(0.25, requestedHr);
   const segCount = Math.max(1, Math.ceil(melodyEnd / hr));
-  const segments: Segment[] = [];
-  for (let s = 0; s < segCount; s += 1) {
-    const startBeat = s * hr;
-    const endBeat = startBeat + hr;
-    const noteIndices = opts.melody
-      .map((n, i) => ({ n, i }))
-      .filter(({ n }) => n.startBeat < endBeat && n.startBeat + n.durationBeat > startBeat)
-      .map(({ i }) => i);
-    segments.push({ startBeat, endBeat, noteIndices });
+  assertGenerationBudget(segCount, 'harmonic segments');
+  assertGenerationBudget(segCount * candidates.length * candidates.length, 'harmonization search');
+  const segments: Segment[] = Array.from({ length: segCount }, (_, s) => ({
+    startBeat: s * hr,
+    endBeat: (s + 1) * hr,
+    noteIndices: [],
+  }));
+  // Associate each note only with the windows it actually spans. This replaces
+  // the former per-window full melody scan and creates no temporary note objects.
+  let memberships = 0;
+  for (const indexed of noteIndex.notes) {
+    const first = Math.max(0, Math.floor(indexed.note.startBeat / hr));
+    const lastExclusive = Math.min(segCount, Math.ceil(indexed.endBeat / hr - Number.EPSILON));
+    memberships += Math.max(0, lastExclusive - first);
+    assertGenerationBudget(memberships, 'note-to-segment memberships');
+    for (let segment = first; segment < lastExclusive; segment += 1) {
+      segments[segment]?.noteIndices.push(indexed.originalIndex);
+    }
   }
 
   const transposes: number[] = [0];
@@ -413,9 +424,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,

package/src/generate/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Public API of the generate layer. Re-exports every generate-layer module;
+ * also available from the package root.
+ */
+export type { BassLineOptions, BassSegment, BassStyle } from './bass/index.js';
+export { generateBassLine } from './bass/index.js';
+export type { CounterMelodyOptions } from './countermelody/index.js';
+export { generateCounterMelody } from './countermelody/index.js';
+export type {
+  DrumHit,
+  DrumRole,
+  DrumsOptions,
+  EuclideanKick,
+  GrooveFeel,
+  GrooveStyle,
+  Section,
+} from './drums/index.js';
+export { generateDrums } from './drums/index.js';
+export type { GrooveSlot, GrooveTemplate, HumanizeOptions } from './groove/index.js';
+export { applyGrooveTemplate, extractGrooveTemplate, humanize } from './groove/index.js';
+export type {
+  HarmonizeOptions,
+  HarmonizeResult,
+  MelodyNote,
+} from './harmonize/index.js';
+export { harmonizeMelody } from './harmonize/index.js';
+export type {
+  MotifCell,
+  MotifContour,
+  MotifNote,
+  MotifOptions,
+  MotifTransform,
+} from './motif/index.js';
+export { developMotif, generateMotif, transformMotif } from './motif/index.js';
+export type {
+  ProgFunction,
+  ProgressionOptions,
+  ProgressionPreset,
+  ProgStyle,
+} from './progression/index.js';
+export {
+  generateProgression,
+  progressions,
+  progressionsByStyle,
+} from './progression/index.js';
+export type {
+  BorrowedChord,
+  SubstituteOptions,
+  Substitution,
+  SubstitutionType,
+} from './reharmony/index.js';
+export {
+  modalInterchangePalette,
+  negativeHarmonyMirror,
+  substituteChord,
+} from './reharmony/index.js';
+export type { RhythmEvent, RhythmOptions } from './rhythm/index.js';
+export { generateRhythm, onsetWeightCurve, rhythmDensity } from './rhythm/index.js';

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

@@ -1,8 +1,16 @@
-import type { Chord } from '../chord/index.js';
-import { chordPitchClasses } from '../chord/index.js';
-import { isScaleTone, nearestScaleTone } from '../scale/index.js';
-import type { ChordTimeline } from '../timeline/index.js';
-import type { KeyScale } from '../types.js';
+import type { ChordTimeline } from '../../analyze/timeline/index.js';
+import { createRng } from '../../core/random/index.js';
+import type { KeyScale } from '../../core/types.js';
+import {
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertInteger,
+  assertNoteEvents,
+  assertPositiveInt,
+} from '../../core/validation/index.js';
+import type { Chord } from '../../theory/chord/index.js';
+import { chordPitchClasses } from '../../theory/chord/index.js';
+import { isScaleTone, nearestScaleTone } from '../../theory/scale/index.js';
 
 /**
  * A transformation applicable to a motif cell.
@@ -50,7 +58,7 @@ export type MotifContour = 'arch' | 'ascending' | 'descending' | 'wave';
  *
  * @category Composition
  */
-export type GenerateMotifOptions = {
+export type MotifOptions = {
   key: KeyScale;
   chord?: Chord | null;
   bars: number;
@@ -133,7 +141,20 @@ function nearestChordTone(pitch: number, chord: Chord): number {
 
 /** Earliest onset in a cell; the time origin for timing transforms. */
 function cellOrigin(notes: MotifNote[]): number {
-  return notes.length === 0 ? 0 : Math.min(...notes.map((n) => n.startBeat));
+  let origin = Number.POSITIVE_INFINITY;
+  for (const note of notes) {
+    origin = Math.min(origin, note.startBeat);
+  }
+  return Number.isFinite(origin) ? origin : 0;
+}
+
+/** Latest offset in a cell, without spreading an unbounded caller array. */
+function cellEnd(notes: MotifNote[]): number {
+  let end = Number.NEGATIVE_INFINITY;
+  for (const note of notes) {
+    end = Math.max(end, note.startBeat + note.durationBeat);
+  }
+  return Number.isFinite(end) ? end : 0;
 }
 
 /** Total beat span covered by a cell (from first onset to last offset). */
@@ -142,7 +163,7 @@ function cellSpan(cell: MotifCell): number {
     return 0;
   }
   const start = cellOrigin(cell.notes);
-  const end = Math.max(...cell.notes.map((n) => n.startBeat + n.durationBeat));
+  const end = cellEnd(cell.notes);
   return end - start;
 }
 
@@ -150,18 +171,6 @@ function clone(cell: MotifCell): MotifCell {
   return { notes: cell.notes.map((n) => ({ ...n })) };
 }
 
-/** Deterministic 32-bit PRNG in [0, 1). */
-function mulberry32(seed: number): () => number {
-  let state = seed >>> 0;
-  return () => {
-    state = (state + 0x6d2b79f5) >>> 0;
-    let t = state;
-    t = Math.imul(t ^ (t >>> 15), t | 1);
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
 /** Diatonic scale-degree offsets shaping a contour of `count` notes. */
 function contourOffsets(contour: MotifContour, count: number): number[] {
   const offsets: number[] = [];
@@ -207,14 +216,16 @@ function contourOffsets(contour: MotifContour, count: number): number[] {
  *
  * @category Composition
  */
-export function generateMotif(opts: GenerateMotifOptions): MotifCell {
+export function generateMotif(opts: MotifOptions): MotifCell {
   const contour = opts.contour ?? 'arch';
-  const bars = Math.max(1, Math.trunc(opts.bars));
+  const bars = assertPositiveInt(opts.bars, 'motif bars');
   const totalBeats = bars * 4;
   const noteCount = Math.max(3, bars * 2);
+  assertGenerationBudget(noteCount, 'motif notes');
   const beatsPerNote = totalBeats / noteCount;
-  const rng = mulberry32(opts.seed ?? 0);
-  const jitterProb = Math.min(1, Math.max(0, opts.jitter ?? 0));
+  const rng = createRng(opts.seed ?? 0);
+  const requestedJitter = assertFiniteNumber(opts.jitter ?? 0, 'motif jitter');
+  const jitterProb = Math.min(1, Math.max(0, requestedJitter));
   const tonic = pitchClass(opts.key.rootPc) + 60;
   const offsets = contourOffsets(contour, noteCount);
 
@@ -224,8 +235,8 @@ export function generateMotif(opts: GenerateMotifOptions): MotifCell {
     // preserved exactly. When enabled it nudges up or down with equal odds,
     // avoiding the upward bias that used to drift arch/wave tails off the tonic.
     let jitter = 0;
-    if (jitterProb > 0 && rng() < jitterProb) {
-      jitter = rng() < 0.5 ? 1 : -1;
+    if (jitterProb > 0 && rng.next() < jitterProb) {
+      jitter = rng.next() < 0.5 ? 1 : -1;
     }
     let pitch = stepDiatonic(tonic, (offsets[i] ?? 0) + jitter, opts.key);
     const startBeat = i * beatsPerNote;
@@ -271,6 +282,16 @@ export function transformMotif(
   amount?: number,
   key?: KeyScale,
 ): MotifCell {
+  assertNoteEvents(cell.notes, 'motif notes');
+  if (amount !== undefined) {
+    assertFiniteNumber(amount, 'motif transform amount');
+  }
+  if ((t === 'transposeDiatonic' || t === 'sequence') && amount !== undefined) {
+    assertInteger(amount, 'diatonic transform amount');
+  }
+  if ((t === 'augment' || t === 'diminish') && amount !== undefined && amount <= 0) {
+    throw new RangeError('time transform amount must be positive');
+  }
   const notes = cell.notes;
   switch (t) {
     case 'transposeChromatic': {
@@ -297,7 +318,7 @@ export function transformMotif(
         return { notes: [] };
       }
       const start = cellOrigin(notes);
-      const end = Math.max(...notes.map((n) => n.startBeat + n.durationBeat));
+      const end = cellEnd(notes);
       return {
         notes: notes.map((n) => ({
           pitch: n.pitch,
@@ -363,8 +384,10 @@ export function developMotif(
   key: KeyScale,
   bars: number,
 ): MotifCell {
+  assertPositiveInt(bars, 'development bars');
+  assertNoteEvents(cell.notes, 'motif notes');
   const span = cellSpan(cell);
-  const totalBeats = Math.max(1, Math.trunc(bars)) * 4;
+  const totalBeats = bars * 4;
   const origin = cellOrigin(cell.notes);
   const out: MotifNote[] = [];
 
@@ -376,6 +399,7 @@ export function developMotif(
   // the offset multiplicatively so rounding error cannot accumulate over tiles.
   const tileSpan = Math.max(span, MIN_TILE_SPAN);
   const tileCount = Math.ceil(totalBeats / tileSpan);
+  assertGenerationBudget(tileCount * cell.notes.length, 'developed motif notes');
   for (let k = 0; k < tileCount; k += 1) {
     const offset = k * tileSpan;
     for (const n of cell.notes) {

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

@@ -1,7 +1,11 @@
-import type { ChordQuality } from '../chord/index.js';
-import { diatonicTriad } from '../chord/index.js';
-import { scaleTonesInDegreeOrder } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
+import { createRng } from '../../core/random/index.js';
+import type { KeyScale } from '../../core/types.js';
+import { assertGenerationBudget, assertPositiveInt } from '../../core/validation/index.js';
+import type { ChordQuality, ChordSpan } from '../../theory/chord/index.js';
+import { diatonicTriad } from '../../theory/chord/index.js';
+import { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';
+
+export type { ChordSpan } from '../../theory/chord/index.js';
 
 /**
  * Broad production style a progression preset suits.
@@ -30,28 +34,12 @@ export type ProgressionPreset = {
   styles: ProgStyle[];
 };
 
-/**
- * A chord placed on the timeline by {@link generateProgression}.
- *
- * @category Composition
- */
-export type GeneratedChord = {
-  rootPc: number;
-  quality: ChordQuality;
-  startBeat: number;
-  bassPc?: number;
-  /** 0-based scale degree of the chord root, when known. */
-  degree?: number;
-  /** True when the chord is a secondary dominant tonicizing another degree. */
-  secondaryDominant?: boolean;
-};
-
 /**
  * Options controlling {@link generateProgression}.
  *
  * @category Composition
  */
-export type GenerateProgressionOptions = {
+export type ProgressionOptions = {
   key: KeyScale;
   style: ProgStyle;
   bars: number;
@@ -251,18 +239,6 @@ export function progressionsByStyle(style: ProgStyle): ProgressionPreset[] {
   return progressions().filter((p) => p.styles.includes(style));
 }
 
-/** Deterministic 32-bit PRNG producing a float in [0, 1). */
-function mulberry32(seed: number): () => number {
-  let state = seed >>> 0;
-  return () => {
-    state = (state + 0x6d2b79f5) >>> 0;
-    let t = state;
-    t = Math.imul(t ^ (t >>> 15), t | 1);
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
 /** Root pitch class of a scale degree in the given key, including borrowed degrees. */
 function degreeToRootPc(degree: number, key: KeyScale): number {
   if (degree >= 0 && degree <= 6) {
@@ -315,12 +291,14 @@ function autoQuality(degree: number, key: KeyScale): ChordQuality {
  * ```ts
  * import { generateProgression, majorKey } from '@libraz/libcantus';
  * const chords = generateProgression({ key: majorKey(0), style: 'dance', bars: 4 });
- * // Deterministic for a given seed (defaults to 0); one GeneratedChord per bar.
+ * // Deterministic for a given seed (defaults to 0); one ChordSpan per bar.
  * ```
  *
  * @category Composition
  */
-export function generateProgression(opts: GenerateProgressionOptions): GeneratedChord[] {
+export function generateProgression(opts: ProgressionOptions): ChordSpan[] {
+  assertPositiveInt(opts.bars, 'progression bars');
+  assertGenerationBudget(opts.bars, 'progression chords');
   const seed = opts.seed ?? 0;
   let preset: ProgressionPreset | undefined;
   if (opts.presetId !== undefined) {
@@ -332,17 +310,17 @@ export function generateProgression(opts: GenerateProgressionOptions): Generated
   if (preset === undefined) {
     const pool = PRESETS.filter((p) => p.styles.includes(opts.style));
     const candidates = pool.length > 0 ? pool : PRESETS;
-    const rng = mulberry32(seed);
-    const index = Math.floor(rng() * candidates.length) % candidates.length;
+    const rng = createRng(seed);
+    const index = Math.floor(rng.next() * candidates.length) % candidates.length;
     preset = candidates[index] ?? PRESETS[0];
   }
   const degrees = preset?.degrees ?? [0];
-  const chords: GeneratedChord[] = [];
+  const chords: ChordSpan[] = [];
   for (let bar = 0; bar < opts.bars; bar += 1) {
     const degree = degrees[bar % degrees.length] ?? 0;
     const quality =
       opts.ext !== undefined && opts.ext !== 'auto' ? opts.ext : autoQuality(degree, opts.key);
-    const chord: GeneratedChord = {
+    const chord: ChordSpan = {
       rootPc: degreeToRootPc(degree, opts.key),
       quality,
       startBeat: bar * 4,
@@ -353,7 +331,7 @@ export function generateProgression(opts: GenerateProgressionOptions): Generated
 
   if (opts.reharmonize) {
     const tonicPc = (((opts.key.rootPc % 12) + 12) % 12) as number;
-    const rrng = mulberry32((seed ^ 0x9e3779b9) >>> 0);
+    const rrng = createRng((seed ^ 0x9e3779b9) >>> 0);
     for (let i = 0; i < chords.length - 1; i += 1) {
       const cur = chords[i];
       const next = chords[i + 1];
@@ -369,7 +347,7 @@ export function generateProgression(opts: GenerateProgressionOptions): Generated
       if (targetsTonic || alreadySecondary || isResolutionTarget) {
         continue;
       }
-      if (rrng() < 0.5) {
+      if (rrng.next() < 0.5) {
         chords[i] = {
           rootPc: domRoot,
           quality: 'dom7',

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

@@ -7,14 +7,7 @@
  * Roots are pitch classes (0..11); no spelled key signature is required.
  */
 
-import {
-  type Chord,
-  type ChordQuality,
-  chordPitchClasses,
-  diatonicTriad,
-  makeChord,
-} from '../chord/index.js';
-import { detectChordBest } from '../detect/index.js';
+import { detectChordBest } from '../../analyze/detect/index.js';
 import {
   type BorrowedSource,
   borrowedSource,
@@ -23,9 +16,16 @@ import {
   type HarmonicFunction,
   isDiatonic,
   parallelKey,
-} from '../functional/index.js';
-import { scaleTonesInDegreeOrder } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
+} from '../../analyze/functional/index.js';
+import type { KeyScale } from '../../core/types.js';
+import {
+  type Chord,
+  type ChordQuality,
+  chordPitchClasses,
+  diatonicTriad,
+  makeChord,
+} from '../../theory/chord/index.js';
+import { scaleTonesInDegreeOrder } from '../../theory/scale/index.js';
 
 /** Reduce a value to a pitch class in [0, 11]. */
 function mod12(n: number): number {
@@ -91,13 +91,6 @@ function isStableTarget(chord: Chord): boolean {
   return hasFifth && hasThird && !isDominantType(chord);
 }
 
-/** The triad pitch classes (root, third, fifth) implied by a chord's template. */
-function triadPitchClasses(chord: Chord): number[] {
-  const third = hasInterval(chord, 4) ? 4 : hasInterval(chord, 3) ? 3 : 4;
-  const fifth = hasInterval(chord, 8) ? 8 : hasInterval(chord, 6) ? 6 : 7;
-  return [mod12(chord.rootPc), mod12(chord.rootPc + third), mod12(chord.rootPc + fifth)];
-}
-
 /** Count the pitch classes shared between two pitch-class sets. */
 function commonToneCount(a: number[], b: number[]): number {
   const set = new Set(b);
@@ -157,7 +150,7 @@ export function substituteChord(
   key: KeyScale,
   opts?: SubstituteOptions,
 ): Substitution[] {
-  const original = triadPitchClasses(chord);
+  const original = chordPitchClasses(chord);
   const candidates: { chord: Chord; type: SubstitutionType }[] = [];
 
   // Tritone substitution: only for dominant-type chords.

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

@@ -11,8 +11,13 @@
  * library-wide convention.
  */
 
-import { beatsPerBar, metricWeight, type TimeSignature } from '../meter/index.js';
-import { createRng } from '../random/index.js';
+import { beatsPerBar, metricWeight, type TimeSignature } from '../../core/meter/index.js';
+import { createRng } from '../../core/random/index.js';
+import {
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertPositiveInt,
+} from '../../core/validation/index.js';
 
 /**
  * A single rhythmic note: an onset position and how long it sounds.
@@ -113,12 +118,17 @@ export function generateRhythm(ts: TimeSignature, opts: RhythmOptions = {}): Rhy
   const seed = opts.seed ?? 0;
   const bars = opts.bars ?? DEFAULT_BARS;
   const subdivision = opts.subdivision ?? DEFAULT_SUBDIVISION;
-  const density = Math.min(1, Math.max(0, opts.density ?? DEFAULT_DENSITY));
+  const requestedDensity = assertFiniteNumber(opts.density ?? DEFAULT_DENSITY, 'rhythm density');
+  const density = Math.min(1, Math.max(0, requestedDensity));
+
+  assertPositiveInt(bars, 'rhythm bars');
+  assertPositiveInt(subdivision, 'rhythm subdivision');
 
   const barBeats = beatsPerBar(ts);
   const spanBeats = barBeats * bars;
   const step = 1 / subdivision;
   const slotCount = Math.round(spanBeats * subdivision);
+  assertGenerationBudget(slotCount, 'rhythm grid slots');
   const slotsPerBar = Math.round(barBeats * subdivision);
   const rng = createRng(seed);