@libraz/libcantus 0.9.0 → 0.9.1

package/src/progression/index.ts

@@ -3,13 +3,25 @@ import { diatonicTriad } from '../chord/index.js';
 import { scaleTonesInDegreeOrder } from '../scale/index.js';
 import type { KeyScale } from '../types.js';
 
-/** Broad production style a progression preset suits. */
+/**
+ * Broad production style a progression preset suits.
+ *
+ * @category Composition
+ */
 export type ProgStyle = 'minimal' | 'dance' | 'idol' | 'rock';
 
-/** Harmonic-function role of a progression as a whole. */
+/**
+ * Harmonic-function role of a progression as a whole.
+ *
+ * @category Composition
+ */
 export type ProgFunction = 'loop' | 'tensionBuild' | 'cadenceStrong' | 'stable';
 
-/** A named chord-progression preset expressed in scale degrees. */
+/**
+ * A named chord-progression preset expressed in scale degrees.
+ *
+ * @category Composition
+ */
 export type ProgressionPreset = {
   id: string;
   name: string;
@@ -18,7 +30,11 @@ export type ProgressionPreset = {
   styles: ProgStyle[];
 };
 
-/** A chord placed on the timeline by {@link generateProgression}. */
+/**
+ * A chord placed on the timeline by {@link generateProgression}.
+ *
+ * @category Composition
+ */
 export type GeneratedChord = {
   rootPc: number;
   quality: ChordQuality;
@@ -30,7 +46,11 @@ export type GeneratedChord = {
   secondaryDominant?: boolean;
 };
 
-/** Options controlling {@link generateProgression}. */
+/**
+ * Options controlling {@link generateProgression}.
+ *
+ * @category Composition
+ */
 export type GenerateProgressionOptions = {
   key: KeyScale;
   style: ProgStyle;
@@ -38,6 +58,11 @@ export type GenerateProgressionOptions = {
   presetId?: string;
   ext?: ChordQuality | 'auto';
   reharmonize?: boolean;
+  /**
+   * Seed for the deterministic preset choice and reharmonization.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
 };
 
@@ -208,12 +233,20 @@ const BORROWED_OFFSET: Record<number, number> = {
   14: 6, // #IV
 };
 
-/** All built-in progression presets. */
+/**
+ * All built-in progression presets.
+ *
+ * @category Composition
+ */
 export function progressions(): ProgressionPreset[] {
   return PRESETS.map((p) => ({ ...p, degrees: [...p.degrees], styles: [...p.styles] }));
 }
 
-/** Presets whose style list includes the given style. */
+/**
+ * Presets whose style list includes the given style.
+ *
+ * @category Composition
+ */
 export function progressionsByStyle(style: ProgStyle): ProgressionPreset[] {
   return progressions().filter((p) => p.styles.includes(style));
 }
@@ -264,7 +297,9 @@ function autoQuality(degree: number, key: KeyScale): ChordQuality {
  * Generate a chord progression laid out one chord per bar.
  *
  * A preset is chosen by `presetId` when given, otherwise deterministically from
- * the presets matching `style`, seeded by `seed`. The preset's degrees cycle to
+ * the presets matching `style`, seeded by `seed`. An unknown `presetId` 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
  * roots come from the key's diatonic scale-degree mapping. When `ext` is
  * omitted or `'auto'`, each chord takes its diatonic triad quality; otherwise
@@ -274,12 +309,25 @@ function autoQuality(degree: number, key: KeyScale): ChordQuality {
  *
  * @param opts Generation options.
  * @returns One chord per bar in timeline order.
+ * @throws If `presetId` is given but does not match any built-in preset.
+ *
+ * @example
+ * ```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.
+ * ```
+ *
+ * @category Composition
  */
 export function generateProgression(opts: GenerateProgressionOptions): GeneratedChord[] {
   const seed = opts.seed ?? 0;
   let preset: ProgressionPreset | undefined;
   if (opts.presetId !== undefined) {
     preset = PRESETS.find((p) => p.id === opts.presetId);
+    if (preset === undefined) {
+      throw new Error(`Unknown progression preset: ${opts.presetId}`);
+    }
   }
   if (preset === undefined) {
     const pool = PRESETS.filter((p) => p.styles.includes(opts.style));

package/src/random/index.ts

@@ -5,7 +5,11 @@
  * seed the stream is fully reproducible.
  */
 
-/** A deterministic PRNG with the sampling helpers the generators need. */
+/**
+ * A deterministic PRNG with the sampling helpers the generators need.
+ *
+ * @category Utilities
+ */
 export type Rng = {
   /** Next float in [0, 1). */
   next: () => number;
@@ -22,6 +26,14 @@ export type Rng = {
  *
  * @param seed The 32-bit seed; the same seed always yields the same stream.
  * @returns The seeded generator.
+ * @example
+ * ```ts
+ * import { createRng } from '@libraz/libcantus';
+ * const rng = createRng(42);
+ * rng.next(); // deterministic float in [0, 1)
+ * rng.range(1, 6); // deterministic integer in [1, 6]
+ * ```
+ * @category Utilities
  */
 export function createRng(seed: number): Rng {
   let state = seed >>> 0;

package/src/reharmony/index.ts

@@ -32,7 +32,11 @@ function mod12(n: number): number {
   return ((n % 12) + 12) % 12;
 }
 
-/** The kind of substitution relationship a candidate realizes. */
+/**
+ * The kind of substitution relationship a candidate realizes.
+ *
+ * @category Reharmonization
+ */
 export type SubstitutionType =
   | 'tritone'
   | 'relative'
@@ -40,7 +44,11 @@ export type SubstitutionType =
   | 'chromatic-mediant'
   | 'secondary-dominant';
 
-/** A proposed chord substitution with its relationship, numeral, and function. */
+/**
+ * A proposed chord substitution with its relationship, numeral, and function.
+ *
+ * @category Reharmonization
+ */
 export type Substitution = {
   chord: Chord;
   type: SubstitutionType;
@@ -48,7 +56,11 @@ export type Substitution = {
   function: HarmonicFunction;
 };
 
-/** Options controlling which substitutions {@link substituteChord} returns. */
+/**
+ * Options controlling which substitutions {@link substituteChord} returns.
+ *
+ * @category Reharmonization
+ */
 export type SubstituteOptions = {
   /**
    * Melody pitch classes that must remain chord tones. When given, only
@@ -132,6 +144,13 @@ const THIRD_OFFSETS = [3, 4, 8, 9] as const;
  * @param key The prevailing key.
  * @param opts Optional melody-preservation constraint.
  * @returns The deduplicated substitution candidates.
+ * @example
+ * ```ts
+ * import { substituteChord, makeChord, majorKey } from '@libraz/libcantus';
+ * const subs = substituteChord(makeChord(7, 'dom7'), majorKey(0));
+ * // includes the tritone sub Db7 (rootPc 1, quality 'dom7')
+ * ```
+ * @category Reharmonization
  */
 export function substituteChord(
   chord: Chord,
@@ -214,7 +233,11 @@ export function substituteChord(
   return results;
 }
 
-/** A borrowed chord in the modal-interchange palette of a key. */
+/**
+ * A borrowed chord in the modal-interchange palette of a key.
+ *
+ * @category Reharmonization
+ */
 export type BorrowedChord = {
   chord: Chord;
   roman: string;
@@ -231,6 +254,7 @@ export type BorrowedChord = {
  *
  * @param key The prevailing key.
  * @returns The borrowed-chord palette.
+ * @category Reharmonization
  */
 export function modalInterchangePalette(key: KeyScale): BorrowedChord[] {
   const palette: BorrowedChord[] = [];
@@ -275,6 +299,13 @@ export function modalInterchangePalette(key: KeyScale): BorrowedChord[] {
  * @param chord The chord to reflect.
  * @param key The prevailing key.
  * @returns The negative-harmony counterpart of the chord.
+ * @example
+ * ```ts
+ * import { negativeHarmonyMirror, makeChord, majorKey } from '@libraz/libcantus';
+ * negativeHarmonyMirror(makeChord(7, 'maj'), majorKey(0));
+ * // G major reflected across C's axis => F minor (rootPc 5, quality 'min')
+ * ```
+ * @category Reharmonization
  */
 export function negativeHarmonyMirror(chord: Chord, key: KeyScale): Chord {
   const tonic = mod12(key.rootPc);

package/src/rhythm/index.ts

@@ -14,7 +14,11 @@
 import { beatsPerBar, metricWeight, type TimeSignature } from '../meter/index.js';
 import { createRng } from '../random/index.js';
 
-/** A single rhythmic note: an onset position and how long it sounds. */
+/**
+ * A single rhythmic note: an onset position and how long it sounds.
+ *
+ * @category Rhythm & Meter
+ */
 export type RhythmEvent = {
   /** Onset position in quarter-note beats, absolute from the start of the span. */
   position: number;
@@ -22,21 +26,38 @@ export type RhythmEvent = {
   duration: number;
 };
 
-/** Options controlling {@link generateRhythm}. */
+/**
+ * Options controlling {@link generateRhythm}.
+ *
+ * @category Rhythm & Meter
+ */
 export type RhythmOptions = {
-  /** Seed for the deterministic PRNG. Default 0. */
+  /**
+   * Seed for the deterministic PRNG.
+   *
+   * @defaultValue 0
+   */
   seed?: number;
-  /** Number of bars to generate. Default 1. */
+  /**
+   * Number of bars to generate.
+   *
+   * @defaultValue 1
+   */
   bars?: number;
   /**
    * Grid resolution as the number of equal grid steps per quarter-note beat.
    * The default of 2 yields an eighth-note grid; 4 yields a sixteenth-note
    * grid, 3 an eighth-note triplet grid, and so on.
+   *
+   * @defaultValue 2
    */
   subdivision?: number;
   /**
    * Overall onset density in [0, 1]. Scales the per-slot onset probability, so
-   * higher values fill more grid slots. Default 0.5.
+   * higher values fill more grid slots. Values outside [0, 1] are clamped into
+   * range.
+   *
+   * @defaultValue 0.5
    */
   density?: number;
 };
@@ -53,6 +74,7 @@ const DEFAULT_BARS = 1;
  *
  * @param weight The metric weight, 0 (off-pulse) to 3 (downbeat).
  * @returns A base onset probability in [0, 1].
+ * @category Rhythm & Meter
  */
 export function onsetWeightCurve(weight: number): number {
   switch (weight) {
@@ -71,29 +93,40 @@ export function onsetWeightCurve(weight: number): number {
  * Generate a deterministic rhythmic pattern over `bars` bars of a time
  * signature. A grid is built at the chosen subdivision; each slot becomes an
  * onset with a probability derived from its metric weight scaled by `density`
- * and sampled from the seeded PRNG. The first slot (the downbeat) is always an
- * onset. Each event's duration extends to the next onset, and the last event
- * extends to the end of the span.
+ * and sampled from the seeded PRNG. Every bar's downbeat is always an onset, so
+ * a pattern of any length has a reliable pulse independent of the seed. Each
+ * event's duration extends to the next onset, and the last event extends to the
+ * end of the span. `density` is clamped to [0, 1].
  *
  * @param ts The time signature.
  * @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, { seed: 42, density: 0.6 }); // onset events over one bar
+ * ```
+ * @category Rhythm & Meter
  */
 export function generateRhythm(ts: TimeSignature, opts: RhythmOptions = {}): RhythmEvent[] {
   const seed = opts.seed ?? 0;
   const bars = opts.bars ?? DEFAULT_BARS;
   const subdivision = opts.subdivision ?? DEFAULT_SUBDIVISION;
-  const density = opts.density ?? DEFAULT_DENSITY;
+  const density = Math.min(1, Math.max(0, opts.density ?? DEFAULT_DENSITY));
 
-  const spanBeats = beatsPerBar(ts) * bars;
+  const barBeats = beatsPerBar(ts);
+  const spanBeats = barBeats * bars;
   const step = 1 / subdivision;
   const slotCount = Math.round(spanBeats * subdivision);
+  const slotsPerBar = Math.round(barBeats * subdivision);
   const rng = createRng(seed);
 
   const positions: number[] = [];
   for (let i = 0; i < slotCount; i += 1) {
     const position = i * step;
-    if (i === 0) {
+    // Force every bar's downbeat so the pulse is reliable regardless of seed.
+    if (i % slotsPerBar === 0) {
       positions.push(position);
       continue;
     }
@@ -119,6 +152,7 @@ export function generateRhythm(ts: TimeSignature, opts: RhythmOptions = {}): Rhy
  * @param events Events from {@link generateRhythm}.
  * @param ts The time signature.
  * @returns The onset count divided by the number of bars the events span.
+ * @category Rhythm & Meter
  */
 export function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number {
   if (events.length === 0) {

package/src/safety/index.ts

@@ -2,7 +2,6 @@ import type { Chord } from '../chord/index.js';
 import { chordPitchClasses } from '../chord/index.js';
 import {
   createsHiddenParallelPerfect,
-  createsParallelOctave,
   createsParallelPerfect,
   createsVerticalDissonance,
   isForbiddenMelodicLeap,
@@ -10,17 +9,29 @@ import {
 import { isScaleTone } from '../scale/index.js';
 import type { KeyScale } from '../types.js';
 
-/** Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading. */
+/**
+ * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
+ *
+ * @category Arrangement & Analysis
+ */
 export type SafetyProfile = 'strict' | 'pop';
 
-/** Overall placeability verdict for a candidate pitch. */
+/**
+ * Overall placeability verdict for a candidate pitch.
+ *
+ * @category Arrangement & Analysis
+ */
 export enum NoteSafety {
   Safe = 0,
   Warning = 1,
   Dissonant = 2,
 }
 
-/** Bit flags describing why a pitch received its verdict. */
+/**
+ * Bit flags describing why a pitch received its verdict.
+ *
+ * @category Arrangement & Analysis
+ */
 export enum ReasonFlag {
   ChordTone = 1 << 0,
   Tension = 1 << 1,
@@ -40,13 +51,21 @@ export enum ReasonFlag {
   NeedsResolution = 1 << 15,
 }
 
-/** A neighbouring voice's current and previous pitch. */
+/**
+ * A neighbouring voice's current and previous pitch.
+ *
+ * @category Arrangement & Analysis
+ */
 export type VoiceSnapshot = {
   pitch: number;
   prevPitch?: number;
 };
 
-/** Everything needed to evaluate one candidate pitch. */
+/**
+ * Everything needed to evaluate one candidate pitch.
+ *
+ * @category Arrangement & Analysis
+ */
 export type SafetyQuery = {
   profile: SafetyProfile;
   candidatePitch: number;
@@ -59,7 +78,11 @@ export type SafetyQuery = {
   vocalHigh?: number;
 };
 
-/** The verdict, reason flags, and optional resolution guidance. */
+/**
+ * The verdict, reason flags, and optional resolution guidance.
+ *
+ * @category Arrangement & Analysis
+ */
 export type SafetyResult = {
   safety: NoteSafety;
   reasons: number;
@@ -115,6 +138,20 @@ function stepResolution(pitch: number, chord: Chord): number | undefined {
  *
  * @param q The candidate and its harmonic/voice-leading context.
  * @returns The verdict, reason bitmask, and optional resolution guidance.
+ * @example
+ * ```ts
+ * import { evaluateSafety, makeChord, majorKey, NoteSafety } from '@libraz/libcantus';
+ * const result = evaluateSafety({
+ *   profile: 'pop',
+ *   candidatePitch: 60, // C over a C major chord
+ *   chord: makeChord(0, 'maj'),
+ *   key: majorKey(0),
+ *   otherVoices: [],
+ *   strongBeat: true,
+ * });
+ * result.safety === NoteSafety.Safe; // true — C is a chord tone
+ * ```
+ * @category Arrangement & Analysis
  */
 export function evaluateSafety(q: SafetyQuery): SafetyResult {
   return evaluateInternal(q, true);
@@ -242,10 +279,9 @@ function evaluateInternal(q: SafetyQuery, collectSuggestions: boolean): SafetyRe
       if (ov.prevPitch === undefined) {
         continue;
       }
-      if (
-        createsParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch) ||
-        createsParallelOctave(prev, pitch, ov.prevPitch, ov.pitch)
-      ) {
+      // createsParallelPerfect covers every perfect class (unison/octave and
+      // fifth), so no separate octave check is needed.
+      if (createsParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch)) {
         reasons |= ReasonFlag.ParallelPerfect;
         raise(parallelSeverity);
       }
@@ -346,6 +382,17 @@ function describe(reasons: number, q: SafetyQuery): string {
  * @param pitchLow Lowest MIDI pitch to consider (inclusive).
  * @param pitchHigh Highest MIDI pitch to consider (inclusive).
  * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
+ * @example
+ * ```ts
+ * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';
+ * const pitches = enumerateSafePitches(
+ *   { profile: 'pop', chord: makeChord(0, 'maj'), key: majorKey(0), otherVoices: [], strongBeat: true },
+ *   60,
+ *   72,
+ * );
+ * pitches; // placeable pitches in [60, 72], chord tones first, each group descending
+ * ```
+ * @category Arrangement & Analysis
  */
 export function enumerateSafePitches(
   q: Omit<SafetyQuery, 'candidatePitch'>,