@libraz/libcantus 0.9.0 → 0.9.1

package/src/functional/index.ts

@@ -19,10 +19,18 @@ import {
 } from '../scale/index.js';
 import type { KeyScale } from '../types.js';
 
-/** The three broad harmonic functions of tonal music. */
+/**
+ * The three broad harmonic functions of tonal music.
+ *
+ * @category Functional Harmony
+ */
 export type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
 
-/** A recognized cadence type, or null when a chord pair forms none. */
+/**
+ * A recognized cadence type, or null when a chord pair forms none.
+ *
+ * @category Functional Harmony
+ */
 export type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
 
 /** Roman numeral glyphs indexed by degree number - 1. */
@@ -75,7 +83,11 @@ function mod12(n: number): number {
   return ((n % 12) + 12) % 12;
 }
 
-/** Whether a key's scale has a minor third and no major third (a minor key). */
+/**
+ * Whether a key's scale has a minor third and no major third (a minor key).
+ *
+ * @category Functional Harmony
+ */
 export function isMinorKey(key: KeyScale): boolean {
   const hasMinorThird = (key.modeMask12 >> 3) & 1;
   const hasMajorThird = (key.modeMask12 >> 4) & 1;
@@ -108,13 +120,56 @@ function seventhQuality(base: 'maj' | 'min' | 'dim' | 'aug', halfDim: boolean):
 /** Figure strings that denote a recognized figured-bass inversion. */
 const INVERSION_FIGURES = new Set(['6', '64', '65', '43', '42', '2', '7']);
 
-/** Figure strings that denote a fixed root-position extension quality. */
-const EXTENSION_FIGURES: Record<string, ChordQuality> = {
-  '9': 'dom9',
-  '11': '11',
-  '13': '13',
+/**
+ * Canonical Roman-numeral rendering (numeral case and quality suffix) for every
+ * supported chord quality. The table is the single source of truth for both
+ * directions: {@link chordToRoman} renders from it and {@link romanToChord}
+ * recognizes its exact case-sensitive suffixes, so the two stay mutual
+ * inverses by construction. Suffixes are chosen to never collide with
+ * figured-bass inversion digits (`6`, `64`, `65`, `43`, `42`, `2`) — the added
+ * sixth is `add6`, the six-nine chord is `69` — and each (case, suffix) pair is
+ * unique.
+ */
+const ROMAN_STYLE: Record<ChordQuality, { lower: boolean; suffix: string }> = {
+  maj: { lower: false, suffix: '' },
+  min: { lower: true, suffix: '' },
+  dim: { lower: true, suffix: 'o' },
+  aug: { lower: false, suffix: '+' },
+  maj7: { lower: false, suffix: 'maj7' },
+  min7: { lower: true, suffix: '7' },
+  dom7: { lower: false, suffix: '7' },
+  dim7: { lower: true, suffix: 'o7' },
+  m7b5: { lower: true, suffix: 'ø7' },
+  minMaj7: { lower: true, suffix: 'maj7' },
+  aug7: { lower: false, suffix: '+7' },
+  augMaj7: { lower: false, suffix: '+maj7' },
+  majb5: { lower: false, suffix: 'b5' },
+  '6': { lower: false, suffix: 'add6' },
+  min6: { lower: true, suffix: 'add6' },
+  '6/9': { lower: false, suffix: '69' },
+  sus2: { lower: false, suffix: 'sus2' },
+  sus4: { lower: false, suffix: 'sus4' },
+  add9: { lower: false, suffix: 'add9' },
+  add11: { lower: false, suffix: 'add11' },
+  maj9: { lower: false, suffix: 'maj9' },
+  min9: { lower: true, suffix: '9' },
+  dom9: { lower: false, suffix: '9' },
+  '7b9': { lower: false, suffix: '7b9' },
+  '7#9': { lower: false, suffix: '7#9' },
+  '7#11': { lower: false, suffix: '7#11' },
+  '7b13': { lower: false, suffix: '7b13' },
+  '11': { lower: false, suffix: '11' },
+  '13': { lower: false, suffix: '13' },
+  '5': { lower: false, suffix: '5' },
 };
 
+/** Reverse lookup of {@link ROMAN_STYLE}: `(case, exact suffix) -> quality`. */
+const SUFFIX_QUALITY: ReadonlyMap<string, ChordQuality> = new Map(
+  (Object.entries(ROMAN_STYLE) as [ChordQuality, { lower: boolean; suffix: string }][]).map(
+    ([quality, style]) => [`${style.lower ? 'l' : 'u'}:${style.suffix}`, quality],
+  ),
+);
+
 /** Read figured-bass digits into a chord inversion and whether a seventh is implied. */
 function parseInversion(figures: string): { inversion: number; seventh: boolean } {
   if (figures === '65') {
@@ -157,20 +212,24 @@ function parseSimpleRoman(
   const suffix = match[3] ?? '';
   const rootPc = mod12(degreeRootPc(degreeNumber, key) + accidental);
 
+  // Canonical quality suffixes (exact match, case-sensitive on the numeral)
+  // come first so every chordToRoman rendering re-parses to the same quality:
+  // `V9` -> dom9 but `ii9` -> min9 and `Imaj9` -> maj9, and added-tone suffixes
+  // whose digits would otherwise be misread as figured bass (`Iadd6`, `I69`,
+  // `Isus2`, `Iadd11`) resolve to their qualities in root position.
+  const canonical = SUFFIX_QUALITY.get(`${isUpper ? 'u' : 'l'}:${suffix}`);
+  if (canonical !== undefined) {
+    return { rootPc, quality: canonical, inversion: 0 };
+  }
+
   const isDim = /o|°|dim/.test(suffix);
   const isAug = /\+|aug/.test(suffix);
   const isHalfDim = /ø/.test(suffix);
   const explicitMaj7 = /maj7|M7/.test(suffix);
   const figures = suffix.replace(/maj7|M7/g, '').replace(/[^0-9]/g, '');
 
-  // Extension figures (9/11/13) denote a fixed root-position tension quality,
-  // not a figured-bass inversion, so they short-circuit the case/quality logic.
-  const extension = EXTENSION_FIGURES[figures];
-  if (extension !== undefined) {
-    return { rootPc, quality: extension, inversion: 0 };
-  }
   // Reject figure strings that are neither a known figured-bass inversion nor a
-  // supported extension rather than silently degrading to a root triad.
+  // canonical quality suffix rather than silently degrading to a root triad.
   if (figures !== '' && !INVERSION_FIGURES.has(figures)) {
     throw new Error(`Unsupported figured-bass or extension "${figures}" in Roman numeral: ${text}`);
   }
@@ -191,7 +250,7 @@ function parseSimpleRoman(
 
   let quality: ChordQuality;
   if (explicitMaj7) {
-    quality = base === 'min' ? 'minMaj7' : 'maj7';
+    quality = base === 'min' ? 'minMaj7' : base === 'aug' ? 'augMaj7' : 'maj7';
   } else if (hasSeventh) {
     quality = seventhQuality(base, isHalfDim);
   } else if (base === 'dim') {
@@ -228,14 +287,24 @@ function chordFromParsed(parsed: {
  * carry a `bassPc`.
  *
  * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
- * `m7b5`), since no half-diminished triad exists. Root-position extension
- * figures map to fixed qualities (`V9` -> `dom9`, `V11` -> `11`, `V13` -> `13`).
+ * `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
- * extension throws rather than silently degrading to a triad.
+ * 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
  */
 export function romanToChord(text: string, key: KeyScale): Chord {
   const trimmed = text.trim();
@@ -252,30 +321,7 @@ export function romanToChord(text: string, key: KeyScale): Chord {
 
 /** Case and suffix for rendering a chord quality as a Roman numeral. */
 function romanStyle(quality: ChordQuality): { lower: boolean; suffix: string } {
-  switch (quality) {
-    case 'min':
-      return { lower: true, suffix: '' };
-    case 'dim':
-      return { lower: true, suffix: 'o' };
-    case 'aug':
-      return { lower: false, suffix: '+' };
-    case 'maj7':
-      return { lower: false, suffix: 'maj7' };
-    case 'dom7':
-      return { lower: false, suffix: '7' };
-    case 'min7':
-      return { lower: true, suffix: '7' };
-    case 'm7b5':
-      return { lower: true, suffix: 'ø7' };
-    case 'dim7':
-      return { lower: true, suffix: 'o7' };
-    case 'minMaj7':
-      return { lower: true, suffix: 'maj7' };
-    case 'maj':
-      return { lower: false, suffix: '' };
-    default:
-      return { lower: false, suffix: quality };
-  }
+  return ROMAN_STYLE[quality];
 }
 
 /** Choose the degree number and accidental to spell a root as a Roman numeral. */
@@ -323,6 +369,9 @@ function baseMarker(quality: ChordQuality): string {
   if (quality === 'aug' || quality === 'aug7') {
     return '+';
   }
+  if (quality === 'augMaj7') {
+    return '+maj7';
+  }
   if (quality === 'maj7' || quality === 'minMaj7') {
     return 'maj7';
   }
@@ -332,6 +381,26 @@ function baseMarker(quality: ChordQuality): string {
 const TRIAD_FIGURES: Record<number, string> = { 1: '6', 2: '64' };
 const SEVENTH_FIGURES: Record<number, string> = { 1: '65', 2: '43', 3: '42' };
 
+/** Qualities whose inversions render as lossless triad figures (6, 64). */
+const TRIAD_FIGURE_QUALITIES: ReadonlySet<ChordQuality> = new Set(['maj', 'min', 'dim', 'aug']);
+
+/**
+ * Qualities carrying a chordal seventh, whose inversions render as seventh
+ * figures (65, 43, 42). Membership is decided by the quality itself — a 7th
+ * above the root (10 or 11 semitones, or the diminished 7th of `dim7`) — never
+ * by interval count, which would turn added-tone chords into false sevenths.
+ */
+const SEVENTH_FIGURE_QUALITIES: ReadonlySet<ChordQuality> = new Set([
+  'maj7',
+  'min7',
+  'dom7',
+  'dim7',
+  'm7b5',
+  'minMaj7',
+  'aug7',
+  'augMaj7',
+]);
+
 /**
  * Render a chord as a Roman numeral relative to a key.
  *
@@ -339,11 +408,20 @@ const SEVENTH_FIGURES: Record<number, string> = { 1: '65', 2: '43', 3: '42' };
  * 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. When the chord carries a `bassPc` on a chord tone, a figured-bass
- * inversion (`6`, `64`, `65`, `43`, `42`) is emitted.
+ * 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).
  *
  * @param chord The chord to name.
  * @param key The prevailing key.
  * @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)
+ * ```
+ * @category Functional Harmony
  */
 export function chordToRoman(chord: Chord, key: KeyScale): string {
   const { degreeNumber, accidental } = romanSpelling(chord.rootPc, key);
@@ -359,14 +437,18 @@ export function chordToRoman(chord: Chord, key: KeyScale): string {
     }
   }
   if (inversion > 0) {
-    const isSeventh = chord.intervals.length >= 4;
-    const figure = (isSeventh ? SEVENTH_FIGURES : TRIAD_FIGURES)[inversion];
+    const figure = SEVENTH_FIGURE_QUALITIES.has(chord.quality)
+      ? SEVENTH_FIGURES[inversion]
+      : TRIAD_FIGURE_QUALITIES.has(chord.quality)
+        ? TRIAD_FIGURES[inversion]
+        : undefined;
     if (figure !== undefined) {
       return `${accidental}${cased}${baseMarker(chord.quality)}${figure}`;
     }
-    // The bass falls on a tension beyond the seventh (e.g. a ninth in the bass);
-    // no figured-bass symbol exists for it, so fall back to root-position
-    // rendering with the quality suffix rather than emitting a bare numeral.
+    // No lossless figured-bass symbol exists — the quality is an added-tone or
+    // extended chord, or the bass falls on a tension beyond the seventh — so
+    // fall back to root-position rendering with the quality suffix rather than
+    // emitting a figure that would re-parse as a different chord.
   }
   return `${accidental}${cased}${suffix}`;
 }
@@ -379,15 +461,24 @@ export function chordToRoman(chord: Chord, key: KeyScale): string {
  * @param chord The chord.
  * @param key The prevailing key.
  * @returns The harmonic function.
+ * @category Functional Harmony
  */
 export function functionOf(chord: Chord, key: KeyScale): HarmonicFunction {
   return FUNCTION_BY_OFFSET[mod12(chord.rootPc - key.rootPc)] ?? 'tonic';
 }
 
-/** The origin of a recognized non-diatonic chord, or null when none applies. */
+/**
+ * The origin of a recognized non-diatonic chord, or null when none applies.
+ *
+ * @category Functional Harmony
+ */
 export type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
 
-/** The result of {@link analyzeChord}: function, borrowing, and Roman numeral. */
+/**
+ * The result of {@link analyzeChord}: function, borrowing, and Roman numeral.
+ *
+ * @category Functional Harmony
+ */
 export type ChordAnalysis = {
   function: HarmonicFunction;
   borrowed: boolean;
@@ -406,6 +497,7 @@ export type ChordAnalysis = {
  * @param chord The chord to test.
  * @param key The prevailing key.
  * @returns True if all chord pitch classes are scale tones.
+ * @category Functional Harmony
  */
 export function isDiatonic(chord: Chord, key: KeyScale): boolean {
   return chordPitchClasses(chord).every((pc) => isScaleTone(pc, key));
@@ -419,6 +511,7 @@ export function isDiatonic(chord: Chord, key: KeyScale): boolean {
  *
  * @param key The key to mirror.
  * @returns The parallel major or natural-minor key on the same tonic.
+ * @category Functional Harmony
  */
 export function parallelKey(key: KeyScale): KeyScale {
   return {
@@ -458,6 +551,7 @@ function isNeapolitan(chord: Chord, key: KeyScale): boolean {
  * @param chord The chord to test.
  * @param key The prevailing key.
  * @returns True if the chord is borrowed from the parallel mode.
+ * @category Functional Harmony
  */
 export function isBorrowedChord(chord: Chord, key: KeyScale): boolean {
   if (isDiatonic(chord, key)) {
@@ -480,6 +574,7 @@ export function isBorrowedChord(chord: Chord, key: KeyScale): boolean {
  * @param chord The chord to classify.
  * @param key The prevailing key.
  * @returns The borrowing source, or null.
+ * @category Functional Harmony
  */
 export function borrowedSource(chord: Chord, key: KeyScale): BorrowedSource {
   if (isDiatonic(chord, key)) {
@@ -537,6 +632,13 @@ function qualityAwareFunction(chord: Chord, key: KeyScale): HarmonicFunction {
  * @param chord The chord to analyze.
  * @param key The prevailing key.
  * @returns The chord analysis.
+ * @example
+ * ```ts
+ * import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';
+ * analyzeChord(makeChord(7, 'dom7'), majorKey(0));
+ * // { function: 'dominant', borrowed: false, source: null, roman: 'V7' }
+ * ```
+ * @category Functional Harmony
  */
 export function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis {
   const source = borrowedSource(chord, key);
@@ -563,6 +665,12 @@ export function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis {
  * @param to The final chord.
  * @param key The prevailing key.
  * @returns The cadence type, or null.
+ * @example
+ * ```ts
+ * import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';
+ * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0)); // => 'authentic'
+ * ```
+ * @category Functional Harmony
  */
 export function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence {
   const tonic = mod12(key.rootPc);
@@ -595,6 +703,7 @@ export function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence {
  * @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.
+ * @category Functional Harmony
  */
 export function secondaryDominant(targetDegree: number, key: KeyScale): Chord {
   const targetRoot = degreeRootPc(targetDegree + 1, key);

package/src/groove/index.ts

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