@libraz/libcantus 0.9.4 → 0.9.5

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

@@ -1,5 +1,5 @@
 import { K as KeyScale } from './types-BN6_Q9Kl.cjs';
-import { C as Chord } from './index-y_ak9_Hi.cjs';
+import { C as Chord } from './index-oTQbYYIs.cjs';
 
 /**
  * Borrowed chords (modal interchange) and the Neapolitan.
@@ -22,7 +22,7 @@ type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
  * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy
  * tonic and major IV in a minor key. Two non-diatonic families are excluded:
  * chords diatonic to neither mode (they are chromatic, not borrowed), and, in
- * a minor key, chords explained by the harmonic minor scale (the major
+ * a minor key, chords explained by the altered minor forms (the major
  * dominant and raised-leading-tone chords), which are in-key alterations
  * rather than interchange even though they happen to fit the parallel major.
  *
@@ -37,7 +37,7 @@ declare function isBorrowedChord(chord: Chord, key: KeyScale): boolean;
  *
  * The Neapolitan (major triad on b2) is recognized first, since it sits
  * outside both parallel modes; parallel-mode borrowing follows the
- * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,
+ * {@link isBorrowedChord} rules. Diatonic chords and altered-minor chords,
  * and unrecognized chromatic chords all yield null.
  *
  * @param chord The chord to classify.
@@ -85,6 +85,96 @@ type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
  */
 declare function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence;
 
+/**
+ * Roman-numeral parsing and formatting.
+ *
+ * The {@link ROMAN_STYLE} table is the single source of truth for both
+ * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
+ * inverses by construction.
+ */
+
+/**
+ * Build the chord denoted by a Roman numeral in a key.
+ *
+ * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
+ * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
+ * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
+ * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
+ * whose root becomes a local major tonic for the applied chord. Inverted chords
+ * carry a `bassPc`.
+ *
+ * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
+ * `m7b5`), since no half-diminished triad exists. Extension and added-tone
+ * suffixes are the canonical case-sensitive forms emitted by
+ * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
+ * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
+ * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
+ * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
+ * A figure string that is neither a recognized inversion nor a supported
+ * quality suffix throws rather than silently degrading to a triad.
+ *
+ * @param text The Roman numeral.
+ * @param key The prevailing key.
+ * @returns The chord.
+ * @example
+ * ```ts
+ * import { romanToChord, majorKey } from '@libraz/libcantus';
+ * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
+ * ```
+ * @category Functional Harmony
+ */
+declare function romanToChord(text: string, key: KeyScale): Chord;
+/**
+ * Options for {@link chordToRoman}.
+ *
+ * @category Functional Harmony
+ */
+type ChordToRomanOptions = {
+    /**
+     * Render a tonicizing chord as an applied numeral (`V7/V`, `viio7/ii`)
+     * instead of naming its root against the home key (`II7`, `#ivo7`).
+     *
+     * Off by default: naming the root is always a correct spelling, whereas
+     * whether a chromatic dominant is genuinely applied is a reading only the
+     * caller can make. Turning it on makes {@link chordToRoman} the exact inverse
+     * of {@link romanToChord} for the chords {@link secondaryDominant} builds.
+     */
+    applied?: boolean;
+};
+/**
+ * Render a chord as a Roman numeral relative to a key.
+ *
+ * Diatonic roots take their scale-degree numeral directly, so numerals are
+ * correct in both major and minor keys (and any custom scale). The quality
+ * selects the case and suffix; chromatic roots receive a flat/sharp spelling by
+ * convention. A key that is not heptatonic has no numeral of its own for every
+ * degree, so its roots are named against its parallel major.
+ *
+ * When the chord carries a `bassPc` on a chord tone, a figured-bass inversion
+ * (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true seventh
+ * chords; added-tone and extended qualities have no lossless figure and render
+ * in root position instead (the bass is dropped, pitch classes are preserved).
+ *
+ * A `bassPc` that is *not* a chord tone — a pedal or passing bass such as
+ * `C/D` — is likewise dropped, and the numeral names the upper chord alone.
+ * Roman-numeral notation spends its slash on applied chords (`V7/V`), so there
+ * is no unambiguous way to write such a bass; a caller that must keep it should
+ * read `chord.bassPc` alongside the numeral.
+ *
+ * @param chord The chord to name.
+ * @param key The prevailing key.
+ * @param opts `applied` renders tonicizing chords as `V7/V`-style numerals.
+ * @returns The Roman numeral string.
+ * @example
+ * ```ts
+ * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
+ * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
+ * chordToRoman(makeChord(2, 'dom7'), majorKey(0), { applied: true }); // => 'V7/V'
+ * ```
+ * @category Functional Harmony
+ */
+declare function chordToRoman(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): string;
+
 /**
  * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
  * mirroring, and full chord analysis.
@@ -184,6 +274,7 @@ declare function parallelKey(key: KeyScale): KeyScale;
  *
  * @param chord The chord to analyze.
  * @param key The prevailing key.
+ * @param opts Options used when rendering the Roman numeral.
  * @returns The chord analysis.
  * @example
  * ```ts
@@ -193,16 +284,16 @@ declare function parallelKey(key: KeyScale): KeyScale;
  * ```
  * @category Functional Harmony
  */
-declare function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis;
+declare function analyzeChord(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): ChordAnalysis;
 /**
  * The secondary dominant (V7) that tonicizes a scale degree.
  *
- * @param targetDegree 0-based scale degree to tonicize, in 0..6.
+ * @param targetDegree 0-based scale degree to tonicize.
  * @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.
+ * @throws If `targetDegree` is not an integer naming a degree in `key`.
  * @category Functional Harmony
  */
 declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord;
 
-export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, analyzeChord as b, borrowedSource as c, detectCadence as d, isDiatonic as e, functionOf as f, isMinorKey as g, isBorrowedChord as i, parallelKey as p, secondaryDominant as s };
+export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, type ChordToRomanOptions as b, analyzeChord as c, borrowedSource as d, chordToRoman as e, detectCadence as f, functionOf as g, isDiatonic as h, isBorrowedChord as i, isMinorKey as j, parallelKey as p, romanToChord as r, secondaryDominant as s };

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

@@ -1,5 +1,5 @@
 import { K as KeyScale } from './types-BN6_Q9Kl.js';
-import { C as Chord } from './index-C83mZI1P.js';
+import { C as Chord } from './index-COw1Ky9g.js';
 
 /**
  * Borrowed chords (modal interchange) and the Neapolitan.
@@ -22,7 +22,7 @@ type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
  * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy
  * tonic and major IV in a minor key. Two non-diatonic families are excluded:
  * chords diatonic to neither mode (they are chromatic, not borrowed), and, in
- * a minor key, chords explained by the harmonic minor scale (the major
+ * a minor key, chords explained by the altered minor forms (the major
  * dominant and raised-leading-tone chords), which are in-key alterations
  * rather than interchange even though they happen to fit the parallel major.
  *
@@ -37,7 +37,7 @@ declare function isBorrowedChord(chord: Chord, key: KeyScale): boolean;
  *
  * The Neapolitan (major triad on b2) is recognized first, since it sits
  * outside both parallel modes; parallel-mode borrowing follows the
- * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,
+ * {@link isBorrowedChord} rules. Diatonic chords and altered-minor chords,
  * and unrecognized chromatic chords all yield null.
  *
  * @param chord The chord to classify.
@@ -85,6 +85,96 @@ type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
  */
 declare function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence;
 
+/**
+ * Roman-numeral parsing and formatting.
+ *
+ * The {@link ROMAN_STYLE} table is the single source of truth for both
+ * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
+ * inverses by construction.
+ */
+
+/**
+ * Build the chord denoted by a Roman numeral in a key.
+ *
+ * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
+ * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
+ * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
+ * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
+ * whose root becomes a local major tonic for the applied chord. Inverted chords
+ * carry a `bassPc`.
+ *
+ * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
+ * `m7b5`), since no half-diminished triad exists. Extension and added-tone
+ * suffixes are the canonical case-sensitive forms emitted by
+ * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
+ * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
+ * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
+ * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
+ * A figure string that is neither a recognized inversion nor a supported
+ * quality suffix throws rather than silently degrading to a triad.
+ *
+ * @param text The Roman numeral.
+ * @param key The prevailing key.
+ * @returns The chord.
+ * @example
+ * ```ts
+ * import { romanToChord, majorKey } from '@libraz/libcantus';
+ * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
+ * ```
+ * @category Functional Harmony
+ */
+declare function romanToChord(text: string, key: KeyScale): Chord;
+/**
+ * Options for {@link chordToRoman}.
+ *
+ * @category Functional Harmony
+ */
+type ChordToRomanOptions = {
+    /**
+     * Render a tonicizing chord as an applied numeral (`V7/V`, `viio7/ii`)
+     * instead of naming its root against the home key (`II7`, `#ivo7`).
+     *
+     * Off by default: naming the root is always a correct spelling, whereas
+     * whether a chromatic dominant is genuinely applied is a reading only the
+     * caller can make. Turning it on makes {@link chordToRoman} the exact inverse
+     * of {@link romanToChord} for the chords {@link secondaryDominant} builds.
+     */
+    applied?: boolean;
+};
+/**
+ * Render a chord as a Roman numeral relative to a key.
+ *
+ * Diatonic roots take their scale-degree numeral directly, so numerals are
+ * correct in both major and minor keys (and any custom scale). The quality
+ * selects the case and suffix; chromatic roots receive a flat/sharp spelling by
+ * convention. A key that is not heptatonic has no numeral of its own for every
+ * degree, so its roots are named against its parallel major.
+ *
+ * When the chord carries a `bassPc` on a chord tone, a figured-bass inversion
+ * (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true seventh
+ * chords; added-tone and extended qualities have no lossless figure and render
+ * in root position instead (the bass is dropped, pitch classes are preserved).
+ *
+ * A `bassPc` that is *not* a chord tone — a pedal or passing bass such as
+ * `C/D` — is likewise dropped, and the numeral names the upper chord alone.
+ * Roman-numeral notation spends its slash on applied chords (`V7/V`), so there
+ * is no unambiguous way to write such a bass; a caller that must keep it should
+ * read `chord.bassPc` alongside the numeral.
+ *
+ * @param chord The chord to name.
+ * @param key The prevailing key.
+ * @param opts `applied` renders tonicizing chords as `V7/V`-style numerals.
+ * @returns The Roman numeral string.
+ * @example
+ * ```ts
+ * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
+ * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
+ * chordToRoman(makeChord(2, 'dom7'), majorKey(0), { applied: true }); // => 'V7/V'
+ * ```
+ * @category Functional Harmony
+ */
+declare function chordToRoman(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): string;
+
 /**
  * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
  * mirroring, and full chord analysis.
@@ -184,6 +274,7 @@ declare function parallelKey(key: KeyScale): KeyScale;
  *
  * @param chord The chord to analyze.
  * @param key The prevailing key.
+ * @param opts Options used when rendering the Roman numeral.
  * @returns The chord analysis.
  * @example
  * ```ts
@@ -193,16 +284,16 @@ declare function parallelKey(key: KeyScale): KeyScale;
  * ```
  * @category Functional Harmony
  */
-declare function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis;
+declare function analyzeChord(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): ChordAnalysis;
 /**
  * The secondary dominant (V7) that tonicizes a scale degree.
  *
- * @param targetDegree 0-based scale degree to tonicize, in 0..6.
+ * @param targetDegree 0-based scale degree to tonicize.
  * @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.
+ * @throws If `targetDegree` is not an integer naming a degree in `key`.
  * @category Functional Harmony
  */
 declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord;
 
-export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, analyzeChord as b, borrowedSource as c, detectCadence as d, isDiatonic as e, functionOf as f, isMinorKey as g, isBorrowedChord as i, parallelKey as p, secondaryDominant as s };
+export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, type ChordToRomanOptions as b, analyzeChord as c, borrowedSource as d, chordToRoman as e, detectCadence as f, functionOf as g, isDiatonic as h, isBorrowedChord as i, isMinorKey as j, parallelKey as p, romanToChord as r, secondaryDominant as s };

package/dist/generate/index.cjs

@@ -22,19 +22,19 @@
 
 
 
-var _chunk4HLLZPXTcjs = require('../chunk-4HLLZPXT.cjs');
-require('../chunk-RUMU3UA6.cjs');
-require('../chunk-36N73KZ3.cjs');
+var _chunkMPTVJIVGcjs = require('../chunk-MPTVJIVG.cjs');
+require('../chunk-MTMZTMWM.cjs');
+require('../chunk-2A2QMA74.cjs');
 
 
 
 
-var _chunkZEJR4TKLcjs = require('../chunk-ZEJR4TKL.cjs');
-require('../chunk-CAN76NCU.cjs');
-require('../chunk-FCANXBAT.cjs');
-require('../chunk-Q6OP4U43.cjs');
-require('../chunk-FNDWXRRI.cjs');
-require('../chunk-7MGZ7D62.cjs');
+var _chunk357ZDPVUcjs = require('../chunk-357ZDPVU.cjs');
+require('../chunk-KQN2ZYND.cjs');
+require('../chunk-YFJXS3AU.cjs');
+require('../chunk-WFDXOLUB.cjs');
+require('../chunk-BSLTLGM3.cjs');
+require('../chunk-PI3UXRWK.cjs');
 
 
 
@@ -62,5 +62,5 @@ require('../chunk-7MGZ7D62.cjs');
 
 
 
-exports.BASS_STYLES = _chunk4HLLZPXTcjs.BASS_STYLES; exports.BORROWED_DEGREES = _chunk4HLLZPXTcjs.BORROWED_DEGREES; exports.DRUM_NOTES = _chunk4HLLZPXTcjs.DRUM_NOTES; exports.applyGrooveTemplate = _chunk4HLLZPXTcjs.applyGrooveTemplate; exports.developMotif = _chunk4HLLZPXTcjs.developMotif; exports.drumVoiceOf = _chunk4HLLZPXTcjs.drumVoiceOf; exports.extractGrooveTemplate = _chunk4HLLZPXTcjs.extractGrooveTemplate; exports.generateBassLine = _chunk4HLLZPXTcjs.generateBassLine; exports.generateCounterMelody = _chunk4HLLZPXTcjs.generateCounterMelody; exports.generateDrums = _chunk4HLLZPXTcjs.generateDrums; exports.generateMotif = _chunk4HLLZPXTcjs.generateMotif; exports.generateProgression = _chunk4HLLZPXTcjs.generateProgression; exports.generateRhythm = _chunk4HLLZPXTcjs.generateRhythm; exports.harmonizeMelody = _chunk4HLLZPXTcjs.harmonizeMelody; exports.humanize = _chunk4HLLZPXTcjs.humanize; exports.modalInterchangePalette = _chunkZEJR4TKLcjs.modalInterchangePalette; exports.motifToNoteEvents = _chunk4HLLZPXTcjs.motifToNoteEvents; exports.negativeHarmonyMirror = _chunkZEJR4TKLcjs.negativeHarmonyMirror; exports.onsetWeightCurve = _chunk4HLLZPXTcjs.onsetWeightCurve; exports.pickProgressionPreset = _chunk4HLLZPXTcjs.pickProgressionPreset; exports.progressions = _chunk4HLLZPXTcjs.progressions; exports.progressionsByStyle = _chunk4HLLZPXTcjs.progressionsByStyle; exports.rhythmDensity = _chunk4HLLZPXTcjs.rhythmDensity; exports.rhythmToNoteEvents = _chunk4HLLZPXTcjs.rhythmToNoteEvents; exports.substituteChord = _chunkZEJR4TKLcjs.substituteChord; exports.transformMotif = _chunk4HLLZPXTcjs.transformMotif;
+exports.BASS_STYLES = _chunkMPTVJIVGcjs.BASS_STYLES; exports.BORROWED_DEGREES = _chunkMPTVJIVGcjs.BORROWED_DEGREES; exports.DRUM_NOTES = _chunkMPTVJIVGcjs.DRUM_NOTES; exports.applyGrooveTemplate = _chunkMPTVJIVGcjs.applyGrooveTemplate; exports.developMotif = _chunkMPTVJIVGcjs.developMotif; exports.drumVoiceOf = _chunkMPTVJIVGcjs.drumVoiceOf; exports.extractGrooveTemplate = _chunkMPTVJIVGcjs.extractGrooveTemplate; exports.generateBassLine = _chunkMPTVJIVGcjs.generateBassLine; exports.generateCounterMelody = _chunkMPTVJIVGcjs.generateCounterMelody; exports.generateDrums = _chunkMPTVJIVGcjs.generateDrums; exports.generateMotif = _chunkMPTVJIVGcjs.generateMotif; exports.generateProgression = _chunkMPTVJIVGcjs.generateProgression; exports.generateRhythm = _chunkMPTVJIVGcjs.generateRhythm; exports.harmonizeMelody = _chunkMPTVJIVGcjs.harmonizeMelody; exports.humanize = _chunkMPTVJIVGcjs.humanize; exports.modalInterchangePalette = _chunk357ZDPVUcjs.modalInterchangePalette; exports.motifToNoteEvents = _chunkMPTVJIVGcjs.motifToNoteEvents; exports.negativeHarmonyMirror = _chunk357ZDPVUcjs.negativeHarmonyMirror; exports.onsetWeightCurve = _chunkMPTVJIVGcjs.onsetWeightCurve; exports.pickProgressionPreset = _chunkMPTVJIVGcjs.pickProgressionPreset; exports.progressions = _chunkMPTVJIVGcjs.progressions; exports.progressionsByStyle = _chunkMPTVJIVGcjs.progressionsByStyle; exports.rhythmDensity = _chunkMPTVJIVGcjs.rhythmDensity; exports.rhythmToNoteEvents = _chunkMPTVJIVGcjs.rhythmToNoteEvents; exports.substituteChord = _chunk357ZDPVUcjs.substituteChord; exports.transformMotif = _chunkMPTVJIVGcjs.transformMotif;
 //# sourceMappingURL=index.cjs.map

package/dist/generate/index.d.cts

@@ -1,10 +1,10 @@
-import { B as BorrowedSource, H as HarmonicFunction } from '../function-DNugAOrt.cjs';
+import { B as BorrowedSource, H as HarmonicFunction } from '../function-CxixTB02.cjs';
 import { K as KeyScale, N as NoteEvent } from '../types-BN6_Q9Kl.cjs';
-import { b as ChordSegment, C as Chord, a as ChordQuality, c as ChordSpan } from '../index-y_ak9_Hi.cjs';
-export { d as ChordToneRole, P as PitchSpelling } from '../index-y_ak9_Hi.cjs';
-import { a as ChordTimeline } from '../index-Be74mcon.cjs';
+import { b as ChordSegment, C as Chord, a as ChordQuality, c as ChordSpan } from '../index-oTQbYYIs.cjs';
+export { d as ChordToneRole, P as PitchSpelling } from '../index-oTQbYYIs.cjs';
+import { a as ChordTimeline } from '../index-BkYJ0xMq.cjs';
 import { T as TimeSignature } from '../index-DXd9JikN.cjs';
-import { H as HarmonyRole } from '../index-D6b6na69.cjs';
+import { H as HarmonyRole } from '../index-x2vcsduE.cjs';
 
 /**
  * Deterministic bass-line generation over a chord placement.
@@ -224,7 +224,7 @@ declare function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[];
  * ```
  * @category Composition
  */
-declare const DRUM_NOTES: {
+declare const DRUM_NOTES: Readonly<{
     readonly kick: 36;
     readonly snare: 38;
     readonly sideStick: 37;
@@ -239,7 +239,7 @@ declare const DRUM_NOTES: {
     readonly midTom: 47;
     readonly lowTom: 45;
     readonly shaker: 82;
-};
+}>;
 /**
  * A percussion voice name, one key of {@link DRUM_NOTES}.
  *
@@ -336,16 +336,15 @@ type EuclideanKick = {
  */
 type DrumsOptions = {
     /**
-     * Number of bars to generate. Bars are four quarter-note beats long: the
-     * patterns are written for 4/4 and there is no meter option, so a `bars`
-     * count shared with a meter-aware generator such as
-     * {@link generateRhythm} only lines up when that generator is also in 4/4.
+     * Number of bars to generate.
      */
     bars: number;
     bpm: number;
     style: GrooveStyle;
     section: Section;
     density: number;
+    /** Time signature; defaults to 4/4. */
+    ts?: TimeSignature;
     /**
      * Replace the final bar with a fill.
      *
@@ -367,8 +366,9 @@ type DrumsOptions = {
      * - `'fxOnly'`: no kick, snare, ghost notes, timekeeping hi-hat, or fills —
      *   only the fx and auxiliary voices.
      *
-     * The ordering holds in every style and section: a busier role never emits
-     * fewer or quieter voices than a sparser one.
+     * Roles express orchestration priority and peak dynamics, not a strict hit
+     * count: style-specific ride, foot-hi-hat, and auxiliary patterns may make a
+     * sparser role emit more individual onsets in a particular bar.
      *
      * @defaultValue `'full'`
      */
@@ -565,6 +565,8 @@ declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: TimeSig
  * 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.
+ * Non-positive-duration input artefacts are omitted, so output positions do
+ * not retain a one-to-one correspondence with the input array.
  *
  * 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
@@ -624,7 +626,8 @@ type ProgressionPreset = {
 };
 /**
  * The borrowed (non-diatonic) chord roots a preset can name, as their semitone
- * offset above the tonic.
+ * code for a borrowed degree. These are stable identifiers, not semitone
+ * offsets: their pitch-class offsets are resolved internally.
  *
  * Scale degrees 0..6 address the key's own chords; these codes continue the
  * numbering for the chromatic chords a pop progression borrows, so a preset is
@@ -642,7 +645,7 @@ type ProgressionPreset = {
  * ```
  * @category Composition
  */
-declare const BORROWED_DEGREES: {
+declare const BORROWED_DEGREES: Readonly<{
     /** Flat submediant: bVI. */
     readonly bVI: 8;
     /** Flat subtonic: bVII. */
@@ -655,7 +658,7 @@ declare const BORROWED_DEGREES: {
     readonly bII: 13;
     /** Sharp subdominant, the diminished #IV. */
     readonly sharpIV: 14;
-};
+}>;
 /**
  * A chord root in a preset: a scale degree 0..6, or one of
  * {@link BORROWED_DEGREES}.
@@ -1100,8 +1103,6 @@ type SubstituteOptions = {
  * original chord and each other:
  *
  * - `tritone`: for a dominant-type chord, the dominant seventh a tritone away.
- * - `secondaryDominant`: for a stable target, the dominant seventh a fifth
- *   above its root (tonicizing it).
  * - `relative`: a diatonic triad a third away that shares two common tones.
  * - `borrowed`: a triad from the parallel mode with the same harmonic function.
  * - `chromaticMediant`: a major/minor triad a third away sharing one common
@@ -1242,8 +1243,7 @@ type RhythmOptions = {
     subdivision?: number;
     /**
      * Overall onset density in [0, 1]. Scales the per-slot onset probability, so
-     * higher values fill more grid slots. Values outside [0, 1] are clamped into
-     * range.
+     * higher values fill more grid slots. Values outside [0, 1] are rejected.
      *
      * @defaultValue 0.5
      */
@@ -1267,7 +1267,7 @@ declare function onsetWeightCurve(weight: number): number;
  * 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].
+ * end of the span. `density` must be in [0, 1].
  *
  * @param ts The time signature.
  * @param opts Generation options.

package/dist/generate/index.d.ts

@@ -1,10 +1,10 @@
-import { B as BorrowedSource, H as HarmonicFunction } from '../function-BtiZb9i9.js';
+import { B as BorrowedSource, H as HarmonicFunction } from '../function-DTCt675z.js';
 import { K as KeyScale, N as NoteEvent } from '../types-BN6_Q9Kl.js';
-import { b as ChordSegment, C as Chord, a as ChordQuality, c as ChordSpan } from '../index-C83mZI1P.js';
-export { d as ChordToneRole, P as PitchSpelling } from '../index-C83mZI1P.js';
-import { a as ChordTimeline } from '../index-C5UBbQ4G.js';
+import { b as ChordSegment, C as Chord, a as ChordQuality, c as ChordSpan } from '../index-COw1Ky9g.js';
+export { d as ChordToneRole, P as PitchSpelling } from '../index-COw1Ky9g.js';
+import { a as ChordTimeline } from '../index-DRtIhlJj.js';
 import { T as TimeSignature } from '../index-DXd9JikN.js';
-import { H as HarmonyRole } from '../index-tSQh-xwY.js';
+import { H as HarmonyRole } from '../index-Cfx8xgH0.js';
 
 /**
  * Deterministic bass-line generation over a chord placement.
@@ -224,7 +224,7 @@ declare function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[];
  * ```
  * @category Composition
  */
-declare const DRUM_NOTES: {
+declare const DRUM_NOTES: Readonly<{
     readonly kick: 36;
     readonly snare: 38;
     readonly sideStick: 37;
@@ -239,7 +239,7 @@ declare const DRUM_NOTES: {
     readonly midTom: 47;
     readonly lowTom: 45;
     readonly shaker: 82;
-};
+}>;
 /**
  * A percussion voice name, one key of {@link DRUM_NOTES}.
  *
@@ -336,16 +336,15 @@ type EuclideanKick = {
  */
 type DrumsOptions = {
     /**
-     * Number of bars to generate. Bars are four quarter-note beats long: the
-     * patterns are written for 4/4 and there is no meter option, so a `bars`
-     * count shared with a meter-aware generator such as
-     * {@link generateRhythm} only lines up when that generator is also in 4/4.
+     * Number of bars to generate.
      */
     bars: number;
     bpm: number;
     style: GrooveStyle;
     section: Section;
     density: number;
+    /** Time signature; defaults to 4/4. */
+    ts?: TimeSignature;
     /**
      * Replace the final bar with a fill.
      *
@@ -367,8 +366,9 @@ type DrumsOptions = {
      * - `'fxOnly'`: no kick, snare, ghost notes, timekeeping hi-hat, or fills —
      *   only the fx and auxiliary voices.
      *
-     * The ordering holds in every style and section: a busier role never emits
-     * fewer or quieter voices than a sparser one.
+     * Roles express orchestration priority and peak dynamics, not a strict hit
+     * count: style-specific ride, foot-hi-hat, and auxiliary patterns may make a
+     * sparser role emit more individual onsets in a particular bar.
      *
      * @defaultValue `'full'`
      */
@@ -565,6 +565,8 @@ declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: TimeSig
  * 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.
+ * Non-positive-duration input artefacts are omitted, so output positions do
+ * not retain a one-to-one correspondence with the input array.
  *
  * 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
@@ -624,7 +626,8 @@ type ProgressionPreset = {
 };
 /**
  * The borrowed (non-diatonic) chord roots a preset can name, as their semitone
- * offset above the tonic.
+ * code for a borrowed degree. These are stable identifiers, not semitone
+ * offsets: their pitch-class offsets are resolved internally.
  *
  * Scale degrees 0..6 address the key's own chords; these codes continue the
  * numbering for the chromatic chords a pop progression borrows, so a preset is
@@ -642,7 +645,7 @@ type ProgressionPreset = {
  * ```
  * @category Composition
  */
-declare const BORROWED_DEGREES: {
+declare const BORROWED_DEGREES: Readonly<{
     /** Flat submediant: bVI. */
     readonly bVI: 8;
     /** Flat subtonic: bVII. */
@@ -655,7 +658,7 @@ declare const BORROWED_DEGREES: {
     readonly bII: 13;
     /** Sharp subdominant, the diminished #IV. */
     readonly sharpIV: 14;
-};
+}>;
 /**
  * A chord root in a preset: a scale degree 0..6, or one of
  * {@link BORROWED_DEGREES}.
@@ -1100,8 +1103,6 @@ type SubstituteOptions = {
  * original chord and each other:
  *
  * - `tritone`: for a dominant-type chord, the dominant seventh a tritone away.
- * - `secondaryDominant`: for a stable target, the dominant seventh a fifth
- *   above its root (tonicizing it).
  * - `relative`: a diatonic triad a third away that shares two common tones.
  * - `borrowed`: a triad from the parallel mode with the same harmonic function.
  * - `chromaticMediant`: a major/minor triad a third away sharing one common
@@ -1242,8 +1243,7 @@ type RhythmOptions = {
     subdivision?: number;
     /**
      * Overall onset density in [0, 1]. Scales the per-slot onset probability, so
-     * higher values fill more grid slots. Values outside [0, 1] are clamped into
-     * range.
+     * higher values fill more grid slots. Values outside [0, 1] are rejected.
      *
      * @defaultValue 0.5
      */
@@ -1267,7 +1267,7 @@ declare function onsetWeightCurve(weight: number): number;
  * 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].
+ * end of the span. `density` must be in [0, 1].
  *
  * @param ts The time signature.
  * @param opts Generation options.

package/dist/generate/index.js

@@ -22,19 +22,19 @@ import {
   rhythmDensity,
   rhythmToNoteEvents,
   transformMotif
-} from "../chunk-7NKDPF74.js";
-import "../chunk-HKGYCQ34.js";
-import "../chunk-YLEMGEFH.js";
+} from "../chunk-AID75RN3.js";
+import "../chunk-ZGLJM4A4.js";
+import "../chunk-2PTFGVD7.js";
 import {
   modalInterchangePalette,
   negativeHarmonyMirror,
   substituteChord
-} from "../chunk-GQSGS2N4.js";
-import "../chunk-KMHOICIY.js";
-import "../chunk-NKIBQ6PT.js";
-import "../chunk-NYYWMV2C.js";
-import "../chunk-D2FAJBYL.js";
-import "../chunk-XEBG3G53.js";
+} from "../chunk-7JEP3MFY.js";
+import "../chunk-NNB67XA2.js";
+import "../chunk-HN2OEUN2.js";
+import "../chunk-DZMHIGI4.js";
+import "../chunk-KBTTEX7Q.js";
+import "../chunk-R2VVFAIN.js";
 export {
   BASS_STYLES,
   BORROWED_DEGREES,

package/dist/{index-tJhkmQgE.d.cts → index-B2Ulxxpo.d.cts}

@@ -1,5 +1,5 @@
 import { K as KeyScale } from './types-BN6_Q9Kl.cjs';
-import { C as Chord } from './index-y_ak9_Hi.cjs';
+import { C as Chord } from './index-oTQbYYIs.cjs';
 
 /**
  * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
@@ -38,7 +38,8 @@ declare enum ReasonFlag {
     HiddenParallel = 4096,
     VoiceCrossing = 8192,
     Suspension = 16384,
-    NeedsResolution = 32768
+    NeedsResolution = 32768,
+    MelodicTritone = 65536
 }
 /**
  * A neighbouring voice's current and previous pitch.

package/dist/{index-Be74mcon.d.cts → index-BkYJ0xMq.d.cts}

@@ -1,7 +1,7 @@
 import { T as TimeSignature } from './index-DXd9JikN.cjs';
 import { K as KeyScale, N as NoteEvent } from './types-BN6_Q9Kl.cjs';
-import { C as Chord, b as ChordSegment, c as ChordSpan } from './index-y_ak9_Hi.cjs';
-import { C as Cadence } from './function-DNugAOrt.cjs';
+import { C as Chord, b as ChordSegment, c as ChordSpan } from './index-oTQbYYIs.cjs';
+import { C as Cadence } from './function-CxixTB02.cjs';
 
 /**
  * A beat-indexed sequence of chord segments.