@libraz/libcantus 0.9.2 → 0.9.4

package/dist/core/index.d.ts

@@ -1,13 +1,154 @@
-export { B as BarPosition, T as TimeSignature, b as barPositionToBeat, a as beatToBarPosition, c as beatsPerBar, f as formatTimeSignature, i as isCompound, d as isStrongBeat, m as metricWeight, p as parseTimeSignature, e as pulsesPerBar, t as tuplet } from '../index-Cl7mhOFM.js';
-export { N as NoteData, S as SpelledInterval, f as formatNote, m as midiToNote, n as noteToMidi, a as noteToPitchClass, p as parseNote, s as spelledInterval } from '../index-CGMZNCx6.js';
-export { K as KeyScale, N as NoteEvent } from '../types-MGP29r3t.js';
+import { N as NoteEvent } from '../types-BN6_Q9Kl.js';
+export { K as KeyScale } from '../types-BN6_Q9Kl.js';
+import { T as TimeSignature } from '../index-DXd9JikN.js';
+export { B as BarPosition, b as barPositionToBeat, a as barPositionToPulse, c as beatToBarPosition, d as beatsPerBar, f as formatBarPosition, e as formatTimeSignature, i as isCompound, g as isStrongBeat, m as metricWeight, p as parseTimeSignature, h as pulseBeats, j as pulsesPerBar, t as tuplet } from '../index-DXd9JikN.js';
+export { I as IntervalQualityLabel, N as NoteData, S as SpelledInterval, d as diatonicLetterOf, f as formatNote, i as intervalSemitones, m as midiToNote, n as naturalPitchClassOf, a as noteToMidi, b as noteToPitchClass, p as parseInterval, c as parseNote, e as pitchClassOf, s as spelledInterval, t as transposeByInterval, g as transposeNote } from '../index-OG65ocOr.js';
 
 /**
- * Counterpoint classification of a harmonic interval.
+ * The library's error taxonomy.
  *
+ * Every failure this library raises falls into one of three kinds, and the kind
+ * decides what a caller can do about it. Batch-voicing a lead sheet, for
+ * instance, has to tell "fix the input" apart from "loosen the constraints",
+ * and a message string is not a contract.
+ *
+ * The classes extend the built-in error types a caller would otherwise catch —
+ * a rejected argument is still a `RangeError` — so the `code` narrows an
+ * existing category rather than replacing it.
+ */
+/**
+ * What kind of failure an error reports.
+ *
+ * - `INVALID_INPUT`: an argument is malformed or out of range. The caller's
+ *   input must change.
+ * - `NO_SOLUTION`: the input is valid but nothing satisfies the constraints.
+ *   The constraints must change, or the failure must be accepted.
+ * - `BUDGET_EXCEEDED`: the requested work is larger than the synchronous
+ *   generation budget. The request must be smaller, or the budget larger.
+ *
+ * @category Core
+ */
+type LibcantusErrorCode = 'INVALID_INPUT' | 'NO_SOLUTION' | 'BUDGET_EXCEEDED';
+/**
+ * A rejected argument: malformed, out of range, or naming something unknown.
+ *
+ * @category Core
+ */
+declare class InvalidInputError extends RangeError {
+    readonly code: "INVALID_INPUT";
+    readonly name = "InvalidInputError";
+}
+/**
+ * A valid request with no answer: no voicing fits the given ranges, no chord
+ * matches the pitches, no preset claims the style.
+ *
+ * @category Core
+ */
+declare class NoSolutionError extends Error {
+    readonly code: "NO_SOLUTION";
+    readonly name = "NoSolutionError";
+    /**
+     * Where in a sequence the failure occurred, when the operation was working
+     * through one — the chord index of a progression, say.
+     */
+    readonly at: number | undefined;
+    constructor(message: string, options?: {
+        at?: number;
+    });
+}
+/**
+ * Work that would exceed the synchronous generation budget.
+ *
+ * @category Core
+ */
+declare class BudgetExceededError extends RangeError {
+    readonly code: "BUDGET_EXCEEDED";
+    readonly name = "BudgetExceededError";
+}
+/**
+ * Whether a caught value is one of this library's coded errors.
+ *
+ * @param value The caught value.
+ * @returns True when it carries a {@link LibcantusErrorCode}.
+ * @example
+ * ```ts
+ * import { isLibcantusError, voiceChord, parseChordSymbol } from '@libraz/libcantus';
+ * try {
+ *   voiceChord(parseChordSymbol('C'), { ranges: [] });
+ * } catch (error) {
+ *   if (isLibcantusError(error) && error.code === 'NO_SOLUTION') {
+ *     // loosen the constraints rather than blaming the input
+ *   }
+ * }
+ * ```
+ * @category Core
+ */
+declare function isLibcantusError(value: unknown): value is InvalidInputError | NoSolutionError | BudgetExceededError;
+
+/**
+ * A validated note retaining its position in the caller's original array.
+ *
+ * @category Core
+ */
+type IndexedNoteEvent = {
+    note: NoteEvent;
+    originalIndex: number;
+    endBeat: number;
+};
+/**
+ * Which note wins when several sound from the same onset.
+ *
+ * `'highest'` and `'lowest'` name a voice, so the answer does not depend on the
+ * order the caller happened to store the chord in; `'last'` takes the one
+ * latest in the input array.
+ *
+ * @category Core
+ */
+type OnsetTieBreak = 'highest' | 'lowest' | 'last';
+/**
+ * Binary-searchable, stable-sorted index over note onsets and active spans.
+ *
+ * @category Core
+ */
+type NoteEventIndex = {
+    notes: IndexedNoteEvent[];
+    /**
+     * Latest-onset note sounding at `beat`. Simultaneous onsets are resolved by
+     * the index's {@link OnsetTieBreak}.
+     */
+    at: (beat: number) => IndexedNoteEvent | undefined;
+    /** Whether one or more sounding notes attack at `beat`. */
+    attacksAt: (beat: number) => boolean;
+    /** Unique sounding-note attack beats strictly inside `(startBeat, endBeat)`. */
+    onsetsBetween: (startBeat: number, endBeat: number) => number[];
+};
+/**
+ * Validate and stable-sort note events once, then expose logarithmic onset and
+ * active-note lookups. Non-positive-duration notes may be retained for callers
+ * that intentionally filter them later, but never count as sounding.
+ *
+ * @category Core
+ */
+declare function createNoteEventIndex(events: readonly NoteEvent[], options?: {
+    allowNonPositiveDuration?: boolean;
+    tieBreak?: OnsetTieBreak;
+    budget?: number;
+    /** What the events are, for the validation error message. */
+    name?: string;
+}): NoteEventIndex;
+
+/**
+ * Counterpoint classification of a harmonic interval by consonance.
+ *
+ * Distinct from a spelled interval's quality label — see
+ * {@link IntervalQualityLabel}, which names the `'P'` / `'M'` / `'m'` / `'A'` /
+ * `'d'` spelling of an interval rather than how it sounds against another
+ * voice.
+ *
+ * @see {@link IntervalQualityLabel}
  * @category Pitch & Intervals
  */
-declare enum IntervalQuality {
+declare enum ConsonanceClass {
     PerfectConsonance = 0,
     ImperfectConsonance = 1,
     Dissonance = 2
@@ -25,16 +166,22 @@ declare enum IntervalQuality {
  * @returns The counterpoint quality of the interval.
  * @example
  * ```ts
- * import { classifyInterval, IntervalQuality } from '@libraz/libcantus';
- * classifyInterval(7); // IntervalQuality.PerfectConsonance
- * classifyInterval(5); // IntervalQuality.Dissonance (two-voice)
- * classifyInterval(5, false); // IntervalQuality.ImperfectConsonance
+ * import { classifyInterval, ConsonanceClass } from '@libraz/libcantus';
+ * classifyInterval(7); // ConsonanceClass.PerfectConsonance
+ * classifyInterval(5); // ConsonanceClass.Dissonance (two-voice)
+ * classifyInterval(5, false); // ConsonanceClass.ImperfectConsonance
  * ```
  * @category Pitch & Intervals
  */
-declare function classifyInterval(semitones: number, twoVoice?: boolean): IntervalQuality;
+declare function classifyInterval(semitones: number, twoVoice?: boolean): ConsonanceClass;
 /**
- * Test whether an interval is a perfect interval (unison/octave or fifth).
+ * Test whether an interval is a perfect consonance: the unison/octave or the
+ * fifth.
+ *
+ * The perfect fourth is deliberately excluded. This is the predicate the
+ * parallel-motion rules are written against, where the fourth behaves as a
+ * dissonance between two voices; {@link classifyInterval} is the general
+ * classifier, and it treats the fourth as context-dependent.
  *
  * @param semitones Interval size in semitones (may be negative or compound).
  * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.
@@ -109,11 +256,11 @@ declare function createRng(seed: number): Rng;
  */
 type Tuning = {
     /** Step index (MIDI number when `divisions` is 12) whose frequency is `refFreq`. */
-    refStep: number;
+    readonly refStep: number;
     /** Frequency in Hz of `refStep`. */
-    refFreq: number;
+    readonly refFreq: number;
     /** Equal divisions of the octave (12 standard; e.g. 19 or 31 for microtonal). */
-    divisions: number;
+    readonly divisions: number;
 };
 /**
  * Standard twelve-tone equal temperament, A4 (MIDI 69) = 440 Hz.
@@ -162,6 +309,67 @@ declare function frequencyOf(step: number, tuning?: Tuning): number;
  * @category Pitch & Intervals
  */
 declare function nearestStep(freq: number, tuning?: Tuning): number;
+/**
+ * Step index of a frequency under a tuning, unrounded.
+ *
+ * The exact inverse of {@link frequencyOf}. {@link nearestStep} rounds it,
+ * which discards how far off the pitch actually is — the figure a tuner
+ * display, a pitch-bend amount, or an intonation check is built on.
+ *
+ * @param freq Frequency in Hz.
+ * @param tuning The tuning (default 12-TET).
+ * @returns The fractional step index.
+ * @example
+ * ```ts
+ * import { stepOf } from '@libraz/libcantus';
+ * stepOf(442); // slightly above 69, the step for A440
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function stepOf(freq: number, tuning?: Tuning): number;
+/**
+ * How far a frequency sits from its nearest step, in cents.
+ *
+ * Positive means sharp of the step, negative flat.
+ *
+ * @param freq Frequency in Hz.
+ * @param tuning The tuning (default 12-TET).
+ * @returns The signed deviation in cents.
+ * @example
+ * ```ts
+ * import { centsFromNearestStep } from '@libraz/libcantus';
+ * Math.round(centsFromNearestStep(442)); // 8
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function centsFromNearestStep(freq: number, tuning?: Tuning): number;
+/**
+ * Steps spanned by an interval in cents, unrounded — the inverse of
+ * {@link centsOfSteps}.
+ *
+ * @param cents The interval in cents.
+ * @param tuning The tuning (default 12-TET).
+ * @returns The fractional step count.
+ * @category Pitch & Intervals
+ */
+declare function stepsOfCents(cents: number, tuning?: Tuning): number;
+/**
+ * The frequency ratio an interval in cents spans — the inverse of
+ * {@link ratioToCents}.
+ *
+ * Multiply a frequency by this to move it by that many cents, which is how a
+ * cents offset (a pitch-bend spec, a tuning table entry) is applied.
+ *
+ * @param cents The interval in cents.
+ * @returns The frequency ratio.
+ * @example
+ * ```ts
+ * import { centsToRatio } from '@libraz/libcantus';
+ * 440 * centsToRatio(14); // A440 raised by 14 cents
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function centsToRatio(cents: number): number;
 /**
  * Interval in cents between two frequencies.
  *
@@ -196,15 +404,121 @@ declare function ratioToCents(numerator: number, denominator: number): number;
  *
  * @category Pitch & Intervals
  */
-declare const JUST_RATIOS: Record<number, [number, number]>;
+declare const JUST_RATIOS: Readonly<Record<number, readonly [number, number]>>;
 /**
  * Cents by which a five-limit just interval departs from its 12-TET tempering
  * (positive means the just interval is wider).
  *
  * @param semitoneClass Semitone class in [0, 12].
- * @returns The deviation in cents, or NaN if the class has no listed ratio.
+ * @returns The deviation in cents.
+ * @throws If `semitoneClass` is not an integer in [0, 12].
  * @category Pitch & Intervals
  */
 declare function justDeviationCents(semitoneClass: number): number;
 
-export { IntervalQuality, JUST_RATIOS, type Rng, TWELVE_TET, type Tuning, centsBetweenFreq, centsOfSteps, classifyInterval, createRng, edo, frequencyOf, isConsonantInterval, isPerfectInterval, justDeviationCents, nearestStep, ratioToCents };
+/**
+ * Default upper bound for synchronous event/window/candidate generation.
+ *
+ * @category Core
+ */
+declare const DEFAULT_GENERATION_BUDGET = 1000000;
+/**
+ * Require a finite JavaScript number and return it unchanged.
+ *
+ * @category Core
+ */
+declare function assertFiniteNumber(value: number, name: string): number;
+/**
+ * Require an integer in the inclusive range `[min, max]`.
+ *
+ * @category Core
+ */
+declare function assertInteger(value: number, name: string, min?: number, max?: number): number;
+/**
+ * Drop the notes that never sound.
+ *
+ * A MIDI or DAW import routinely carries zero-length artefacts. Every entry
+ * point in this library ignores them, but a caller holding such an array still
+ * has to decide what to do with it before comparing note counts or indices;
+ * this is the one filter to apply.
+ *
+ * @param events The note events to filter.
+ * @returns A new array containing only the notes with a positive duration.
+ * @example
+ * ```ts
+ * import { dropSilentNotes } from '@libraz/libcantus';
+ * dropSilentNotes([{ pitch: 60, startBeat: 0, durationBeat: 0 }]); // []
+ * ```
+ * @category Core
+ */
+declare function dropSilentNotes(events: readonly NoteEvent[]): NoteEvent[];
+/**
+ * Require a value to be one of a fixed set of names.
+ *
+ * TypeScript checks string-union options at compile time only, so a value that
+ * arrives from JSON, a config file, or a JavaScript caller reaches the engine
+ * unchecked and is then read against a table that has no entry for it —
+ * producing a silent `undefined`, a NaN velocity, or a crash far from the call.
+ *
+ * @param value The value to check.
+ * @param allowed Every accepted name.
+ * @param name What the value is, for the error message.
+ * @returns The value, narrowed to the allowed union.
+ * @throws If the value is not one of `allowed`.
+ *
+ * @category Core
+ */
+declare function assertOneOf<const T extends string>(value: unknown, allowed: readonly T[], name: string): T;
+/**
+ * Require a positive safe integer, optionally capped by `max`.
+ *
+ * @category Core
+ */
+declare function assertPositiveInt(value: number, name: string, max?: number): number;
+/**
+ * Require a finite number in the inclusive range `[min, max]`.
+ *
+ * @category Core
+ */
+declare function assertRange(value: number, min: number, max: number, name: string): number;
+/**
+ * Reject work estimates that would exceed a synchronous generation budget.
+ *
+ * @category Core
+ */
+declare function assertGenerationBudget(estimated: number, name: string, limit?: number | undefined): number;
+/**
+ * Validate a time signature, including additive grouping, before any early return.
+ *
+ * @category Core
+ */
+declare function assertTimeSignature(ts: TimeSignature, name?: string): TimeSignature;
+/**
+ * How strictly {@link assertNoteEvent} and {@link assertNoteEvents} read an
+ * event array.
+ *
+ * @category Core
+ */
+type NoteEventAssertOptions = {
+    /**
+     * Accept notes that never sound. The analysis side does, so an array from a
+     * MIDI import can be validated before the zero-length artefacts are dropped.
+     */
+    allowNonPositiveDuration?: boolean;
+    /** Upper bound on the event count; defaults to the generation budget. */
+    budget?: number;
+};
+/**
+ * Validate the finite fields of one timeline note event.
+ *
+ * @category Core
+ */
+declare function assertNoteEvent(event: NoteEvent, name?: string, options?: NoteEventAssertOptions): NoteEvent;
+/**
+ * Validate an event array and its allocation budget without copying it.
+ *
+ * @category Core
+ */
+declare function assertNoteEvents(events: readonly NoteEvent[], name?: string, options?: NoteEventAssertOptions): NoteEvent[];
+
+export { BudgetExceededError, ConsonanceClass, DEFAULT_GENERATION_BUDGET, type IndexedNoteEvent, InvalidInputError, JUST_RATIOS, type LibcantusErrorCode, NoSolutionError, NoteEvent, type NoteEventAssertOptions, type NoteEventIndex, type OnsetTieBreak, type Rng, TWELVE_TET, TimeSignature, type Tuning, assertFiniteNumber, assertGenerationBudget, assertInteger, assertNoteEvent, assertNoteEvents, assertOneOf, assertPositiveInt, assertRange, assertTimeSignature, centsBetweenFreq, centsFromNearestStep, centsOfSteps, centsToRatio, classifyInterval, createNoteEventIndex, createRng, dropSilentNotes, edo, frequencyOf, isConsonantInterval, isLibcantusError, isPerfectInterval, justDeviationCents, nearestStep, ratioToCents, stepOf, stepsOfCents };

package/dist/core/index.js

@@ -2,72 +2,130 @@ import {
   JUST_RATIOS,
   TWELVE_TET,
   centsBetweenFreq,
+  centsFromNearestStep,
   centsOfSteps,
+  centsToRatio,
   edo,
   frequencyOf,
   justDeviationCents,
   nearestStep,
-  ratioToCents
-} from "../chunk-ZXW5YIWK.js";
+  ratioToCents,
+  stepOf,
+  stepsOfCents
+} from "../chunk-I24MV65U.js";
 import {
   createRng
-} from "../chunk-BHUT2S5G.js";
+} from "../chunk-HKGYCQ34.js";
 import {
   barPositionToBeat,
+  barPositionToPulse,
   beatToBarPosition,
   beatsPerBar,
+  createNoteEventIndex,
+  formatBarPosition,
   formatTimeSignature,
   isCompound,
   isStrongBeat,
   metricWeight,
   parseTimeSignature,
+  pulseBeats,
   pulsesPerBar,
   tuplet
-} from "../chunk-MSWFZF7J.js";
+} from "../chunk-YLEMGEFH.js";
 import {
+  BudgetExceededError,
+  ConsonanceClass,
+  DEFAULT_GENERATION_BUDGET,
+  InvalidInputError,
+  NoSolutionError,
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertInteger,
+  assertNoteEvent,
+  assertNoteEvents,
+  assertOneOf,
+  assertPositiveInt,
+  assertRange,
+  assertTimeSignature,
+  classifyInterval,
+  diatonicLetterOf,
+  dropSilentNotes,
   formatNote,
+  intervalSemitones,
+  isConsonantInterval,
+  isLibcantusError,
+  isPerfectInterval,
   midiToNote,
+  naturalPitchClassOf,
   noteToMidi,
   noteToPitchClass,
+  parseInterval,
   parseNote,
-  spelledInterval
-} from "../chunk-DYWFNC4A.js";
-import {
-  IntervalQuality,
-  classifyInterval,
-  isConsonantInterval,
-  isPerfectInterval
-} from "../chunk-CCBLVAPK.js";
+  pitchClassOf,
+  spelledInterval,
+  transposeByInterval,
+  transposeNote
+} from "../chunk-XEBG3G53.js";
 export {
-  IntervalQuality,
+  BudgetExceededError,
+  ConsonanceClass,
+  DEFAULT_GENERATION_BUDGET,
+  InvalidInputError,
   JUST_RATIOS,
+  NoSolutionError,
   TWELVE_TET,
+  assertFiniteNumber,
+  assertGenerationBudget,
+  assertInteger,
+  assertNoteEvent,
+  assertNoteEvents,
+  assertOneOf,
+  assertPositiveInt,
+  assertRange,
+  assertTimeSignature,
   barPositionToBeat,
+  barPositionToPulse,
   beatToBarPosition,
   beatsPerBar,
   centsBetweenFreq,
+  centsFromNearestStep,
   centsOfSteps,
+  centsToRatio,
   classifyInterval,
+  createNoteEventIndex,
   createRng,
+  diatonicLetterOf,
+  dropSilentNotes,
   edo,
+  formatBarPosition,
   formatNote,
   formatTimeSignature,
   frequencyOf,
+  intervalSemitones,
   isCompound,
   isConsonantInterval,
+  isLibcantusError,
   isPerfectInterval,
   isStrongBeat,
   justDeviationCents,
   metricWeight,
   midiToNote,
+  naturalPitchClassOf,
   nearestStep,
   noteToMidi,
   noteToPitchClass,
+  parseInterval,
   parseNote,
   parseTimeSignature,
+  pitchClassOf,
+  pulseBeats,
   pulsesPerBar,
   ratioToCents,
   spelledInterval,
+  stepOf,
+  stepsOfCents,
+  transposeByInterval,
+  transposeNote,
   tuplet
 };
 //# sourceMappingURL=index.js.map

package/dist/{function-2bJW1Zp_.d.ts → function-BtiZb9i9.d.ts}

@@ -1,5 +1,5 @@
-import { K as KeyScale } from './types-MGP29r3t.js';
-import { C as Chord } from './index-CM5W4rcm.js';
+import { K as KeyScale } from './types-BN6_Q9Kl.js';
+import { C as Chord } from './index-C83mZI1P.js';
 
 /**
  * Borrowed chords (modal interchange) and the Neapolitan.
@@ -14,7 +14,7 @@ import { C as Chord } from './index-CM5W4rcm.js';
  *
  * @category Functional Harmony
  */
-type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
+type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
 /**
  * Whether a chord is borrowed from the parallel mode (modal interchange).
  *
@@ -107,13 +107,33 @@ type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
  */
 declare function isMinorKey(key: KeyScale): boolean;
 /**
- * The harmonic function of a chord in a key, from its root's offset above the
- * tonic. The mapping follows common-practice major-key function and is a useful
- * approximation in minor and for borrowed chords.
+ * The harmonic function of a chord in a key.
+ *
+ * The root's offset above the tonic gives the baseline mapping, which follows
+ * common-practice major-key function and is a useful approximation in minor and
+ * for borrowed chords. Chord quality then refines it where the sonority settles
+ * an ambiguity the root offset cannot:
+ *
+ * - A chord that *sounds* like a dominant — a major third with a minor seventh,
+ *   or a diminished-family chord — and is not diatonic to the key has dominant
+ *   function when its root resolves down a fifth or by a semitone onto a
+ *   diatonic degree. This is what makes an applied dominant (`A7` in C, which
+ *   tonicizes ii) and its tritone substitute (`Db7`) read as dominant rather
+ *   than inheriting the function of the degree they happen to sit on.
+ * - The Neapolitan is subdominant.
+ * - A major triad on bVI or bVII of a major key is subdominant — the borrowed
+ *   pop cadence chord, distinct from the bVII7 above, which has a seventh and
+ *   is a dominant sonority.
  *
  * @param chord The chord.
  * @param key The prevailing key.
  * @returns The harmonic function.
+ * @example
+ * ```ts
+ * import { functionOf, makeChord, majorKey } from '@libraz/libcantus';
+ * functionOf(makeChord(9, 'dom7'), majorKey(0)); // 'dominant' — A7 tonicizes ii
+ * functionOf(makeChord(10, 'maj'), majorKey(0)); // 'subdominant' — borrowed bVII
+ * ```
  * @category Functional Harmony
  */
 declare function functionOf(chord: Chord, key: KeyScale): HarmonicFunction;
@@ -177,9 +197,10 @@ declare function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis;
 /**
  * The secondary dominant (V7) that tonicizes a scale degree.
  *
- * @param targetDegree 0-based scale degree to tonicize.
+ * @param targetDegree 0-based scale degree to tonicize, in 0..6.
  * @param key The prevailing key.
  * @returns A dominant-seventh chord a fifth above the target's root.
+ * @throws If `targetDegree` is not an integer in 0..6.
  * @category Functional Harmony
  */
 declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord;

package/dist/{function-r2sh-jOO.d.cts → function-DNugAOrt.d.cts}

@@ -1,5 +1,5 @@
-import { K as KeyScale } from './types-MGP29r3t.cjs';
-import { C as Chord } from './index-BOBXBNwP.cjs';
+import { K as KeyScale } from './types-BN6_Q9Kl.cjs';
+import { C as Chord } from './index-y_ak9_Hi.cjs';
 
 /**
  * Borrowed chords (modal interchange) and the Neapolitan.
@@ -14,7 +14,7 @@ import { C as Chord } from './index-BOBXBNwP.cjs';
  *
  * @category Functional Harmony
  */
-type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
+type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
 /**
  * Whether a chord is borrowed from the parallel mode (modal interchange).
  *
@@ -107,13 +107,33 @@ type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
  */
 declare function isMinorKey(key: KeyScale): boolean;
 /**
- * The harmonic function of a chord in a key, from its root's offset above the
- * tonic. The mapping follows common-practice major-key function and is a useful
- * approximation in minor and for borrowed chords.
+ * The harmonic function of a chord in a key.
+ *
+ * The root's offset above the tonic gives the baseline mapping, which follows
+ * common-practice major-key function and is a useful approximation in minor and
+ * for borrowed chords. Chord quality then refines it where the sonority settles
+ * an ambiguity the root offset cannot:
+ *
+ * - A chord that *sounds* like a dominant — a major third with a minor seventh,
+ *   or a diminished-family chord — and is not diatonic to the key has dominant
+ *   function when its root resolves down a fifth or by a semitone onto a
+ *   diatonic degree. This is what makes an applied dominant (`A7` in C, which
+ *   tonicizes ii) and its tritone substitute (`Db7`) read as dominant rather
+ *   than inheriting the function of the degree they happen to sit on.
+ * - The Neapolitan is subdominant.
+ * - A major triad on bVI or bVII of a major key is subdominant — the borrowed
+ *   pop cadence chord, distinct from the bVII7 above, which has a seventh and
+ *   is a dominant sonority.
  *
  * @param chord The chord.
  * @param key The prevailing key.
  * @returns The harmonic function.
+ * @example
+ * ```ts
+ * import { functionOf, makeChord, majorKey } from '@libraz/libcantus';
+ * functionOf(makeChord(9, 'dom7'), majorKey(0)); // 'dominant' — A7 tonicizes ii
+ * functionOf(makeChord(10, 'maj'), majorKey(0)); // 'subdominant' — borrowed bVII
+ * ```
  * @category Functional Harmony
  */
 declare function functionOf(chord: Chord, key: KeyScale): HarmonicFunction;
@@ -177,9 +197,10 @@ declare function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis;
 /**
  * The secondary dominant (V7) that tonicizes a scale degree.
  *
- * @param targetDegree 0-based scale degree to tonicize.
+ * @param targetDegree 0-based scale degree to tonicize, in 0..6.
  * @param key The prevailing key.
  * @returns A dominant-seventh chord a fifth above the target's root.
+ * @throws If `targetDegree` is not an integer in 0..6.
  * @category Functional Harmony
  */
 declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord;