@libraz/libcantus 0.9.3 → 0.9.4

package/dist/core/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/core/index.ts","../../src/core/validation/index.ts","../../src/core/event-index/index.ts","../../src/core/interval/index.ts","../../src/core/meter/index.ts","../../src/core/pitch/index.ts","../../src/core/random/index.ts","../../src/core/tuning/index.ts"],"sourcesContent":["/**\n * Public API of the core layer. Re-exports every core-layer module;\n * also available from the package root.\n */\n\nexport type { IndexedNoteEvent, NoteEventIndex } from './event-index/index.js';\nexport { createNoteEventIndex } from './event-index/index.js';\nexport {\n  classifyInterval,\n  IntervalQuality,\n  isConsonantInterval,\n  isPerfectInterval,\n} from './interval/index.js';\nexport type { BarPosition, TimeSignature } from './meter/index.js';\nexport {\n  barPositionToBeat,\n  beatsPerBar,\n  beatToBarPosition,\n  formatTimeSignature,\n  isCompound,\n  isStrongBeat,\n  metricWeight,\n  parseTimeSignature,\n  pulsesPerBar,\n  tuplet,\n} from './meter/index.js';\nexport type { Note as NoteData, SpelledInterval } from './pitch/index.js';\nexport {\n  formatNote,\n  midiToNote,\n  noteToMidi,\n  noteToPitchClass,\n  parseNote,\n  spelledInterval,\n} from './pitch/index.js';\nexport type { Rng } from './random/index.js';\nexport { createRng } from './random/index.js';\nexport type { Tuning } from './tuning/index.js';\nexport {\n  centsBetweenFreq,\n  centsOfSteps,\n  edo,\n  frequencyOf,\n  JUST_RATIOS,\n  justDeviationCents,\n  nearestStep,\n  ratioToCents,\n  TWELVE_TET,\n} from './tuning/index.js';\nexport type { KeyScale, NoteEvent } from './types.js';\nexport {\n  assertFiniteNumber,\n  assertGenerationBudget,\n  assertInteger,\n  assertNoteEvent,\n  assertNoteEvents,\n  assertPositiveInt,\n  assertRange,\n  assertTimeSignature,\n  DEFAULT_GENERATION_BUDGET,\n} from './validation/index.js';\n","import type { TimeSignature } from '../meter/index.js';\nimport type { NoteEvent } from '../types.js';\n\n/** Default upper bound for synchronous event/window/candidate generation. */\nexport const DEFAULT_GENERATION_BUDGET = 1_000_000;\n\n/** Require a finite JavaScript number and return it unchanged. */\nexport function assertFiniteNumber(value: number, name: string): number {\n  if (!Number.isFinite(value)) {\n    throw new RangeError(`${name} must be finite; received ${value}`);\n  }\n  return value;\n}\n\n/** Require an integer in the inclusive range `[min, max]`. */\nexport function assertInteger(\n  value: number,\n  name: string,\n  min = Number.MIN_SAFE_INTEGER,\n  max = Number.MAX_SAFE_INTEGER,\n): number {\n  assertFiniteNumber(value, name);\n  if (!Number.isSafeInteger(value) || value < min || value > max) {\n    throw new RangeError(`${name} must be an integer in [${min}, ${max}]; received ${value}`);\n  }\n  return value;\n}\n\n/** Require a positive safe integer, optionally capped by `max`. */\nexport function assertPositiveInt(\n  value: number,\n  name: string,\n  max = DEFAULT_GENERATION_BUDGET,\n): number {\n  return assertInteger(value, name, 1, max);\n}\n\n/** Require a finite number in the inclusive range `[min, max]`. */\nexport function assertRange(value: number, min: number, max: number, name: string): number {\n  assertFiniteNumber(value, name);\n  if (value < min || value > max) {\n    throw new RangeError(`${name} must be in [${min}, ${max}]; received ${value}`);\n  }\n  return value;\n}\n\n/** Reject work estimates that would exceed a synchronous generation budget. */\nexport function assertGenerationBudget(\n  estimated: number,\n  name: string,\n  limit = DEFAULT_GENERATION_BUDGET,\n): number {\n  assertFiniteNumber(estimated, name);\n  assertPositiveInt(limit, `${name} limit`, Number.MAX_SAFE_INTEGER);\n  if (estimated < 0 || estimated > limit) {\n    throw new RangeError(`${name} exceeds the generation budget ${limit}; received ${estimated}`);\n  }\n  return estimated;\n}\n\n/** Validate a time signature, including additive grouping, before any early return. */\nexport function assertTimeSignature(ts: TimeSignature, name = 'time signature'): TimeSignature {\n  assertPositiveInt(ts.numerator, `${name}.numerator`);\n  assertPositiveInt(ts.denominator, `${name}.denominator`);\n  if (ts.grouping !== undefined) {\n    if (ts.grouping.length === 0) {\n      throw new RangeError(`${name}.grouping must not be empty`);\n    }\n    let sum = 0;\n    for (let index = 0; index < ts.grouping.length; index += 1) {\n      sum += assertPositiveInt(ts.grouping[index] ?? Number.NaN, `${name}.grouping[${index}]`);\n    }\n    const compound = ts.numerator % 3 === 0 && ts.numerator > 3;\n    const pulses = compound ? ts.numerator / 3 : ts.numerator;\n    if (sum !== pulses) {\n      throw new RangeError(`${name}.grouping must sum to ${pulses}; received ${sum}`);\n    }\n  }\n  return ts;\n}\n\n/** Validate the finite fields of one timeline note event. */\nexport function assertNoteEvent(\n  event: NoteEvent,\n  name = 'note event',\n  options: { allowNonPositiveDuration?: boolean } = {},\n): NoteEvent {\n  assertFiniteNumber(event.pitch, `${name}.pitch`);\n  assertRange(event.startBeat, 0, Number.MAX_SAFE_INTEGER, `${name}.startBeat`);\n  assertRange(\n    event.durationBeat,\n    options.allowNonPositiveDuration ? -Number.MAX_SAFE_INTEGER : Number.MIN_VALUE,\n    Number.MAX_SAFE_INTEGER,\n    `${name}.durationBeat`,\n  );\n  if (!options.allowNonPositiveDuration && event.durationBeat <= 0) {\n    throw new RangeError(`${name}.durationBeat must be positive; received ${event.durationBeat}`);\n  }\n  if (event.velocity !== undefined) {\n    assertRange(event.velocity, 0, 127, `${name}.velocity`);\n  }\n  return event;\n}\n\n/** Validate an event array and its allocation budget without copying it. */\nexport function assertNoteEvents(\n  events: NoteEvent[],\n  name = 'note events',\n  options: { allowNonPositiveDuration?: boolean; budget?: number } = {},\n): NoteEvent[] {\n  assertGenerationBudget(events.length, `${name} count`, options.budget);\n  for (let index = 0; index < events.length; index += 1) {\n    const event = events[index];\n    if (event !== undefined) {\n      assertNoteEvent(event, `${name}[${index}]`, options);\n    }\n  }\n  return events;\n}\n","import type { NoteEvent } from '../types.js';\nimport { assertNoteEvents } from '../validation/index.js';\n\n/** A validated note retaining its position in the caller's original array. */\nexport type IndexedNoteEvent = {\n  note: NoteEvent;\n  originalIndex: number;\n  endBeat: number;\n};\n\n/** Binary-searchable, stable-sorted index over note onsets and active spans. */\nexport type NoteEventIndex = {\n  notes: IndexedNoteEvent[];\n  /** Latest-onset note sounding at `beat`, with later input order winning ties. */\n  at: (beat: number) => IndexedNoteEvent | undefined;\n  /** Whether one or more notes attack at `beat`. */\n  attacksAt: (beat: number) => boolean;\n  /** Unique attack beats strictly inside `(startBeat, endBeat)`. */\n  onsetsBetween: (startBeat: number, endBeat: number) => number[];\n};\n\nconst EPS = 1e-9;\n\nfunction upperBound(values: IndexedNoteEvent[], beat: number): number {\n  let low = 0;\n  let high = values.length;\n  while (low < high) {\n    const middle = Math.floor((low + high) / 2);\n    if ((values[middle]?.note.startBeat ?? Number.POSITIVE_INFINITY) <= beat) {\n      low = middle + 1;\n    } else {\n      high = middle;\n    }\n  }\n  return low;\n}\n\n/**\n * Validate and stable-sort note events once, then expose logarithmic onset and\n * active-note lookups. Non-positive-duration notes may be retained for callers\n * that intentionally filter them later, but never count as sounding.\n */\nexport function createNoteEventIndex(\n  events: NoteEvent[],\n  options: { allowNonPositiveDuration?: boolean } = {},\n): NoteEventIndex {\n  assertNoteEvents(events, 'note events', options);\n  const notes = events\n    .map((note, originalIndex) => ({\n      note,\n      originalIndex,\n      endBeat: note.startBeat + note.durationBeat,\n    }))\n    .sort((a, b) => a.note.startBeat - b.note.startBeat || a.originalIndex - b.originalIndex);\n  const prefixMaxEnd: number[] = [];\n  let maxEnd = Number.NEGATIVE_INFINITY;\n  for (const indexed of notes) {\n    maxEnd = Math.max(maxEnd, indexed.endBeat);\n    prefixMaxEnd.push(maxEnd);\n  }\n\n  return {\n    notes,\n    at(beat) {\n      let index = upperBound(notes, beat + EPS) - 1;\n      while (index >= 0) {\n        if ((prefixMaxEnd[index] ?? Number.NEGATIVE_INFINITY) <= beat + EPS) {\n          return undefined;\n        }\n        const indexed = notes[index];\n        if (\n          indexed &&\n          indexed.note.durationBeat > 0 &&\n          indexed.note.startBeat - EPS <= beat &&\n          beat < indexed.endBeat - EPS\n        ) {\n          return indexed;\n        }\n        index -= 1;\n      }\n      return undefined;\n    },\n    attacksAt(beat) {\n      const firstAfter = upperBound(notes, beat + EPS);\n      const candidate = notes[firstAfter - 1];\n      return candidate !== undefined && Math.abs(candidate.note.startBeat - beat) < EPS;\n    },\n    onsetsBetween(startBeat, endBeat) {\n      const result: number[] = [];\n      let index = upperBound(notes, startBeat + EPS);\n      while (index < notes.length) {\n        const onset = notes[index]?.note.startBeat;\n        if (onset === undefined || onset >= endBeat - EPS) {\n          break;\n        }\n        if (result[result.length - 1] !== onset) {\n          result.push(onset);\n        }\n        index += 1;\n      }\n      return result;\n    },\n  };\n}\n","/**\n * Counterpoint classification of a harmonic interval.\n *\n * @category Pitch & Intervals\n */\nexport enum IntervalQuality {\n  PerfectConsonance = 0,\n  ImperfectConsonance = 1,\n  Dissonance = 2,\n}\n\n/** Reduce an interval to a simple interval class in the range [0, 11]. */\nfunction simpleInterval(semitones: number): number {\n  return Math.abs(semitones) % 12;\n}\n\n/**\n * Classify an interval for counterpoint evaluation.\n *\n * The interval is reduced modulo 12, so compound intervals classify as their\n * simple equivalents. The perfect fourth (5) is context-dependent: with\n * `twoVoice` (the default) it classifies as a dissonance, matching\n * {@link isConsonantInterval}; otherwise it is an imperfect consonance.\n *\n * @param semitones Interval size in semitones (may be negative or compound).\n * @param twoVoice When true, the perfect fourth is treated as dissonant.\n * @returns The counterpoint quality of the interval.\n * @example\n * ```ts\n * import { classifyInterval, IntervalQuality } from '@libraz/libcantus';\n * classifyInterval(7); // IntervalQuality.PerfectConsonance\n * classifyInterval(5); // IntervalQuality.Dissonance (two-voice)\n * classifyInterval(5, false); // IntervalQuality.ImperfectConsonance\n * ```\n * @category Pitch & Intervals\n */\nexport function classifyInterval(semitones: number, twoVoice = true): IntervalQuality {\n  const pc = simpleInterval(semitones);\n  if (pc === 0 || pc === 7) {\n    return IntervalQuality.PerfectConsonance;\n  }\n  if (pc === 3 || pc === 4 || pc === 8 || pc === 9) {\n    return IntervalQuality.ImperfectConsonance;\n  }\n  if (pc === 5) {\n    return twoVoice ? IntervalQuality.Dissonance : IntervalQuality.ImperfectConsonance;\n  }\n  return IntervalQuality.Dissonance;\n}\n\n/**\n * Test whether an interval is a perfect interval (unison/octave or fifth).\n *\n * @param semitones Interval size in semitones (may be negative or compound).\n * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.\n * @category Pitch & Intervals\n */\nexport function isPerfectInterval(semitones: number): boolean {\n  const pc = simpleInterval(semitones);\n  return pc === 0 || pc === 7;\n}\n\n/**\n * Test whether an interval is consonant.\n *\n * The consonant set is {0, 3, 4, 5, 7, 8, 9} mod 12. In two-voice counterpoint\n * the perfect fourth (5) is treated as a dissonance, so `twoVoice` set to true\n * excludes it.\n *\n * @param semitones Interval size in semitones (may be negative or compound).\n * @param twoVoice When true, the perfect fourth is treated as dissonant.\n * @returns True if the interval is consonant in the given context.\n * @category Pitch & Intervals\n */\nexport function isConsonantInterval(semitones: number, twoVoice = true): boolean {\n  const pc = simpleInterval(semitones);\n  if (pc === 5) {\n    return !twoVoice;\n  }\n  return pc === 0 || pc === 3 || pc === 4 || pc === 7 || pc === 8 || pc === 9;\n}\n","/**\n * Meter and time signatures: bar/beat arithmetic, simple vs. compound meters,\n * metric-accent hierarchy, and tuplet subdivision.\n *\n * Positions and durations are measured in quarter-note beats, matching the rest\n * of the library's beat convention (four quarter-note beats per bar in 4/4).\n */\n\nimport {\n  assertFiniteNumber,\n  assertInteger,\n  assertPositiveInt,\n  assertRange,\n  assertTimeSignature,\n} from '../validation/index.js';\n\n/**\n * A time signature as a numerator over a note-value denominator.\n *\n * @category Rhythm & Meter\n */\nexport type TimeSignature = {\n  numerator: number;\n  denominator: number;\n  /**\n   * Optional additive grouping of the bar's main pulses, as the felt-beat\n   * lengths in pulses — e.g. `[2, 2, 3]` for a 2+2+3 reading of 7/8, or\n   * `[3, 2]` for 5/8. The entries must be positive integers summing to\n   * {@link pulsesPerBar}. When present, the head pulse of each group (other\n   * than the downbeat) is treated as a secondary strong pulse by\n   * {@link metricWeight}/{@link isStrongBeat}; when absent, all main pulses\n   * are weighted equally as flat, evenly divided pulses.\n   */\n  grouping?: number[];\n};\n\n/**\n * A position expressed as a bar index and a quarter-note offset within the bar.\n *\n * @category Rhythm & Meter\n */\nexport type BarPosition = {\n  bar: number;\n  /** Quarter-note offset from the start of the bar. */\n  beat: number;\n};\n\nconst EPS = 1e-9;\n\n/** Whether `value` is an integer multiple of `unit` (within a float tolerance). */\nfunction isMultiple(value: number, unit: number): boolean {\n  if (unit === 0) {\n    return false;\n  }\n  const ratio = value / unit;\n  return Math.abs(ratio - Math.round(ratio)) < EPS;\n}\n\n/**\n * Parse a time signature such as `\"4/4\"` or `\"6/8\"`.\n *\n * @param text The signature text.\n * @returns The parsed time signature.\n * @throws If the text is not `n/d` with positive integers.\n * @example\n * ```ts\n * import { parseTimeSignature } from '@libraz/libcantus';\n * parseTimeSignature('6/8'); // { numerator: 6, denominator: 8 }\n * ```\n * @category Rhythm & Meter\n */\nexport function parseTimeSignature(text: string): TimeSignature {\n  const match = /^\\s*(\\d+)\\s*\\/\\s*(\\d+)\\s*$/.exec(text);\n  if (!match) {\n    throw new Error(`Invalid time signature: ${text}`);\n  }\n  const numerator = Number.parseInt(match[1] ?? '', 10);\n  const denominator = Number.parseInt(match[2] ?? '', 10);\n  if (\n    !Number.isSafeInteger(numerator) ||\n    !Number.isSafeInteger(denominator) ||\n    numerator <= 0 ||\n    denominator <= 0\n  ) {\n    throw new Error(`Invalid time signature: ${text}`);\n  }\n  return { numerator, denominator };\n}\n\n/**\n * Render a time signature as `\"n/d\"`.\n *\n * @category Rhythm & Meter\n */\nexport function formatTimeSignature(ts: TimeSignature): string {\n  assertTimeSignature(ts);\n  return `${ts.numerator}/${ts.denominator}`;\n}\n\n/**\n * Whether a meter is compound: its main pulses each divide into three, as in\n * 6/8, 9/8, 12/8, or 6/4. Compound meters are those whose numerator is a\n * multiple of three greater than three, independent of the denominator. Meters\n * like 3/8 and 3/4 (simple triples, numerator 3) are not compound.\n *\n * @param ts The time signature.\n * @returns True for compound meters.\n * @category Rhythm & Meter\n */\nexport function isCompound(ts: TimeSignature): boolean {\n  assertTimeSignature(ts);\n  return ts.numerator % 3 === 0 && ts.numerator > 3;\n}\n\n/** Length of one denominator unit in quarter-note beats. */\nfunction unitBeats(ts: TimeSignature): number {\n  return 4 / ts.denominator;\n}\n\n/**\n * Length of a bar in quarter-note beats.\n *\n * @param ts The time signature.\n * @returns The bar length in quarter notes.\n * @category Rhythm & Meter\n */\nexport function beatsPerBar(ts: TimeSignature): number {\n  assertTimeSignature(ts);\n  return ts.numerator * unitBeats(ts);\n}\n\n/** Length of one main pulse (a dotted value in compound meters) in quarter notes. */\nfunction pulseBeats(ts: TimeSignature): number {\n  return isCompound(ts) ? 3 * unitBeats(ts) : unitBeats(ts);\n}\n\n/**\n * Number of main pulses (felt beats) per bar: the numerator for simple meters,\n * a third of it for compound meters.\n *\n * For additive/irregular meters such as 7/8 or 5/8 this counts the raw pulses\n * (7 and 5 respectively), which are otherwise felt as flat, evenly divided and\n * equally accented pulses. To recover a 2+2+3 or 3+2 felt-beat grouping, set\n * {@link TimeSignature.grouping}; {@link metricWeight} then accents each\n * group's head pulse.\n *\n * @param ts The time signature.\n * @returns The pulse count per bar.\n * @category Rhythm & Meter\n */\nexport function pulsesPerBar(ts: TimeSignature): number {\n  return beatsPerBar(ts) / pulseBeats(ts);\n}\n\n/**\n * Whether `grouping` is a valid additive grouping for a bar of `pulses` main\n * pulses: a non-empty list of positive integers summing to `pulses`.\n */\nfunction isValidGrouping(grouping: number[], pulses: number): boolean {\n  if (grouping.length === 0) {\n    return false;\n  }\n  let sum = 0;\n  for (const g of grouping) {\n    if (!Number.isInteger(g) || g <= 0) {\n      return false;\n    }\n    sum += g;\n  }\n  return sum === pulses;\n}\n\n/** Whether `pulseIndex` is the head pulse of one of the additive groups. */\nfunction isGroupHead(grouping: number[], pulseIndex: number): boolean {\n  let acc = 0;\n  for (const g of grouping) {\n    if (acc === pulseIndex) {\n      return true;\n    }\n    acc += g;\n  }\n  return false;\n}\n\n/**\n * Convert an absolute quarter-note position to a bar index and in-bar offset.\n *\n * @param beatInQuarters Absolute position in quarter-note beats.\n * @param ts The time signature.\n * @returns The bar and in-bar quarter-note offset.\n * @example\n * ```ts\n * import { parseTimeSignature, beatToBarPosition } from '@libraz/libcantus';\n * const ts = parseTimeSignature('4/4');\n * beatToBarPosition(5, ts); // { bar: 1, beat: 1 }\n * ```\n * @category Rhythm & Meter\n */\nexport function beatToBarPosition(beatInQuarters: number, ts: TimeSignature): BarPosition {\n  assertFiniteNumber(beatInQuarters, 'beat');\n  const barLen = beatsPerBar(ts);\n  const bar = Math.floor(beatInQuarters / barLen);\n  return { bar, beat: beatInQuarters - bar * barLen };\n}\n\n/**\n * Convert a bar index and in-bar offset back to an absolute quarter-note\n * position.\n *\n * @param pos The bar position.\n * @param ts The time signature.\n * @returns The absolute position in quarter-note beats.\n * @category Rhythm & Meter\n */\nexport function barPositionToBeat(pos: BarPosition, ts: TimeSignature): number {\n  assertInteger(pos.bar, 'bar position bar');\n  assertFiniteNumber(pos.beat, 'bar position beat');\n  return pos.bar * beatsPerBar(ts) + pos.beat;\n}\n\n/**\n * Metric weight of a position within its bar, on a 0–3 scale:\n * 3 the downbeat, 2 a secondary strong pulse, 1 any other main pulse, and 0 an\n * off-pulse subdivision.\n *\n * The secondary strong pulse is the bar's midpoint in even simple/compound\n * meters. For an additive/irregular meter with {@link TimeSignature.grouping}\n * set (e.g. `[2, 2, 3]` for 7/8), each group's head pulse other than the\n * downbeat is the secondary strong pulse instead; without a grouping every\n * non-downbeat main pulse of such a meter weighs 1 (flat, evenly divided\n * pulses).\n *\n * @param beatInQuarters Absolute or in-bar quarter-note position.\n * @param ts The time signature.\n * @returns The metric weight (0–3).\n * @throws If `ts.grouping` is present but is not a positive-integer list\n *   summing to {@link pulsesPerBar}.\n * @example\n * ```ts\n * import { parseTimeSignature, metricWeight } from '@libraz/libcantus';\n * const ts = parseTimeSignature('4/4');\n * metricWeight(0, ts); // 3 (the downbeat)\n * ```\n * @category Rhythm & Meter\n */\nexport function metricWeight(beatInQuarters: number, ts: TimeSignature): number {\n  assertFiniteNumber(beatInQuarters, 'beat');\n  assertTimeSignature(ts);\n  const { beat } = beatToBarPosition(beatInQuarters, ts);\n  const pulse = pulseBeats(ts);\n  if (!isMultiple(beat, pulse)) {\n    return 0;\n  }\n  const pulses = pulsesPerBar(ts);\n  const pulseIndex = Math.round(beat / pulse) % pulses;\n  if (pulseIndex === 0) {\n    return 3;\n  }\n  const grouping = ts.grouping;\n  if (grouping !== undefined) {\n    if (!isValidGrouping(grouping, pulses)) {\n      throw new Error(\n        `Invalid grouping [${grouping.join(', ')}] for ${formatTimeSignature(ts)}: ` +\n          `entries must be positive integers summing to ${pulses}`,\n      );\n    }\n    return isGroupHead(grouping, pulseIndex) ? 2 : 1;\n  }\n  if (pulses % 2 === 0 && pulseIndex === pulses / 2) {\n    return 2;\n  }\n  return 1;\n}\n\n/**\n * Whether a position is metrically accented (weight 2 or more — a downbeat or a\n * secondary strong pulse).\n *\n * @param beatInQuarters Absolute or in-bar quarter-note position.\n * @param ts The time signature.\n * @returns True on strong beats.\n * @category Rhythm & Meter\n */\nexport function isStrongBeat(beatInQuarters: number, ts: TimeSignature): boolean {\n  return metricWeight(beatInQuarters, ts) >= 2;\n}\n\n/**\n * Subdivide a span into `count` equal tuplet durations (e.g. an eighth-note\n * triplet is `tuplet(1, 3)`).\n *\n * @param totalBeats Total span in quarter-note beats.\n * @param count Number of equal parts.\n * @returns `count` equal durations summing to `totalBeats`.\n * @throws If `count` is not a positive integer.\n * @category Rhythm & Meter\n */\nexport function tuplet(totalBeats: number, count: number): number[] {\n  assertRange(totalBeats, 0, Number.MAX_SAFE_INTEGER, 'tuplet total beats');\n  assertPositiveInt(count, 'tuplet count');\n  return new Array<number>(count).fill(totalBeats / count);\n}\n","/**\n * Pitch spelling: letter-name notes, enharmonic-aware conversion, and spelled\n * intervals.\n *\n * The rest of the library works in pitch classes (0..11), which cannot tell a\n * G# from an Ab or an augmented fourth from a diminished fifth. This module adds\n * an explicit spelling layer — a note is a diatonic letter plus a chromatic\n * alteration — so interval quality (P/M/m/A/d) and enharmonic identity are\n * preserved.\n */\n\n/** Semitone offset of each natural letter above C: C D E F G A B. */\nconst LETTER_SEMITONES = [0, 2, 4, 5, 7, 9, 11] as const;\n\n/** Letter glyphs indexed by letter number (0 = C .. 6 = B). */\nconst LETTER_NAMES = ['C', 'D', 'E', 'F', 'G', 'A', 'B'] as const;\n\n/**\n * A spelled note: a diatonic letter, a chromatic alteration, and an optional\n * octave.\n *\n * - `letter` is 0..6 for C..B.\n * - `alter` is the number of semitones of alteration: -2 double-flat, -1 flat,\n *   0 natural, +1 sharp, +2 double-sharp.\n * - `octave` follows scientific pitch notation (middle C = C4 = MIDI 60). When\n *   absent, the note denotes a bare pitch class.\n *\n * @category Pitch & Intervals\n */\nexport type Note = {\n  letter: number;\n  alter: number;\n  octave?: number;\n};\n\n/**\n * A spelled interval: a diatonic number, a quality label, and its semitone span.\n *\n * @category Pitch & Intervals\n */\nexport type SpelledInterval = {\n  /** Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond. */\n  number: number;\n  /** Quality label: 'P', 'M', 'm', or repeated 'A'/'d' for (multiply) aug/dim. */\n  quality: string;\n  /** Signed semitone distance from the first note to the second. */\n  semitones: number;\n};\n\n/** Reduce any integer to a pitch class in [0, 11]. */\nfunction mod12(n: number): number {\n  return ((n % 12) + 12) % 12;\n}\n\n/** Reduce any integer to [0, 7). */\nfunction mod7(n: number): number {\n  return ((n % 7) + 7) % 7;\n}\n\n/**\n * Parse scientific pitch notation into a {@link Note}.\n *\n * Accepts a letter (case-insensitive) followed by any number of same-direction\n * accidentals and an optional octave, e.g. `\"C\"`, `\"C#4\"`, `\"Bb\"`, `\"F##3\"`,\n * `\"Ebb2\"`. Both `#` and `x` (double-sharp) are accepted for sharps; `b` for\n * flats. Mixing sharps and flats (e.g. `\"C#b\"`) is rejected.\n *\n * @param text The note text.\n * @returns The parsed note.\n * @throws If the text is not a valid note.\n * @example\n * ```ts\n * import { parseNote, noteToMidi } from '@libraz/libcantus';\n * const n = parseNote('C#4');\n * noteToMidi(n); // 61\n * ```\n * @category Pitch & Intervals\n */\nexport function parseNote(text: string): Note {\n  const match = /^([A-Ga-g])([#x]*|b*)(-?\\d+)?$/.exec(text.trim());\n  if (!match) {\n    throw new Error(`Invalid note: ${text}`);\n  }\n  const letterGlyph = (match[1] ?? '').toUpperCase();\n  const letter = LETTER_NAMES.indexOf(letterGlyph as (typeof LETTER_NAMES)[number]);\n  let alter = 0;\n  for (const ch of match[2] ?? '') {\n    if (ch === '#') {\n      alter += 1;\n    } else if (ch === 'x') {\n      alter += 2;\n    } else if (ch === 'b') {\n      alter -= 1;\n    }\n  }\n  const note: Note = { letter, alter };\n  if (match[3] !== undefined) {\n    note.octave = Number.parseInt(match[3], 10);\n  }\n  return note;\n}\n\n/** Render an alteration as accidental glyphs (`##`, `b`, empty for natural). */\nfunction formatAlter(alter: number): string {\n  if (alter > 0) {\n    return '#'.repeat(alter);\n  }\n  if (alter < 0) {\n    return 'b'.repeat(-alter);\n  }\n  return '';\n}\n\n/**\n * Render a {@link Note} as scientific pitch notation.\n *\n * @param note The note to format.\n * @returns The note text, including the octave when present.\n * @example\n * ```ts\n * import { formatNote, parseNote } from '@libraz/libcantus';\n * formatNote(parseNote('C#4')); // 'C#4'\n * ```\n * @category Pitch & Intervals\n */\nexport function formatNote(note: Note): string {\n  const glyph = LETTER_NAMES[mod7(note.letter)] ?? 'C';\n  const octave = note.octave === undefined ? '' : String(note.octave);\n  return `${glyph}${formatAlter(note.alter)}${octave}`;\n}\n\n/**\n * Pitch class (0..11) of a note, ignoring octave.\n *\n * @param note The note.\n * @returns The pitch class.\n * @example\n * ```ts\n * import { noteToPitchClass, parseNote } from '@libraz/libcantus';\n * noteToPitchClass(parseNote('Db')); // 1\n * ```\n * @category Pitch & Intervals\n */\nexport function noteToPitchClass(note: Note): number {\n  const natural = LETTER_SEMITONES[mod7(note.letter)] ?? 0;\n  return mod12(natural + note.alter);\n}\n\n/**\n * MIDI number of a note (middle C = C4 = 60).\n *\n * @param note The note; must carry an octave.\n * @returns The MIDI number.\n * @throws If the note has no octave.\n * @example\n * ```ts\n * import { noteToMidi, parseNote } from '@libraz/libcantus';\n * noteToMidi(parseNote('A4')); // 69\n * ```\n * @category Pitch & Intervals\n */\nexport function noteToMidi(note: Note): number {\n  if (note.octave === undefined) {\n    throw new Error('noteToMidi requires an octave');\n  }\n  const natural = LETTER_SEMITONES[mod7(note.letter)] ?? 0;\n  return (note.octave + 1) * 12 + natural + note.alter;\n}\n\n/** Preferred spelling when naming a black key from a bare MIDI number. */\nconst SHARP_SPELLING: readonly [number, number][] = [\n  [0, 0],\n  [0, 1],\n  [1, 0],\n  [1, 1],\n  [2, 0],\n  [3, 0],\n  [3, 1],\n  [4, 0],\n  [4, 1],\n  [5, 0],\n  [5, 1],\n  [6, 0],\n];\n\nconst FLAT_SPELLING: readonly [number, number][] = [\n  [0, 0],\n  [1, -1],\n  [1, 0],\n  [2, -1],\n  [2, 0],\n  [3, 0],\n  [4, -1],\n  [4, 0],\n  [5, -1],\n  [5, 0],\n  [6, -1],\n  [6, 0],\n];\n\n/**\n * Name a MIDI number as a {@link Note}, choosing sharp or flat spelling.\n *\n * The input is rounded to the nearest integer but is not clamped to the MIDI\n * range 0..127: out-of-range values extrapolate linearly (e.g. `-1` -> `B-2`,\n * `128` -> `G#9`) and remain an exact inverse of {@link noteToMidi}.\n *\n * @param midi The MIDI number.\n * @param spelling Whether to prefer sharps or flats for black keys.\n * @returns The spelled note, with octave.\n * @example\n * ```ts\n * import { midiToNote, formatNote } from '@libraz/libcantus';\n * formatNote(midiToNote(61)); // 'C#4'\n * formatNote(midiToNote(61, 'flat')); // 'Db4'\n * ```\n * @category Pitch & Intervals\n */\nexport function midiToNote(midi: number, spelling: 'sharp' | 'flat' = 'sharp'): Note {\n  const rounded = Math.round(midi);\n  const pc = mod12(rounded);\n  const octave = Math.floor(rounded / 12) - 1;\n  const table = spelling === 'sharp' ? SHARP_SPELLING : FLAT_SPELLING;\n  const entry = table[pc] ?? [0, 0];\n  return { letter: entry[0], alter: entry[1], octave };\n}\n\n/** Reference semitone span of a perfect/major simple interval by diatonic number. */\nconst SIMPLE_REFERENCE = [0, 0, 2, 4, 5, 7, 9, 11] as const;\n\n/** Whether a simple diatonic number (1..7 within an octave) is a perfect kind. */\nfunction isPerfectNumber(simpleNumber: number): boolean {\n  return simpleNumber === 1 || simpleNumber === 4 || simpleNumber === 5;\n}\n\n/** Quality label from a diatonic number and its actual semitone span. */\nfunction qualityFromSpan(numberValue: number, semitones: number): string {\n  const octaves = Math.floor((numberValue - 1) / 7);\n  const simple = numberValue - 7 * octaves;\n  const reference = (SIMPLE_REFERENCE[simple] ?? 0) + 12 * octaves;\n  const delta = semitones - reference;\n  if (isPerfectNumber(simple)) {\n    if (delta === 0) {\n      return 'P';\n    }\n    return delta > 0 ? 'A'.repeat(delta) : 'd'.repeat(-delta);\n  }\n  if (delta === 0) {\n    return 'M';\n  }\n  if (delta === -1) {\n    return 'm';\n  }\n  return delta > 0 ? 'A'.repeat(delta) : 'd'.repeat(-delta - 1);\n}\n\n/** Diatonic ladder index of a note (letter + 7 * octave when octave-bearing). */\nfunction diatonicIndex(note: Note): number {\n  return mod7(note.letter) + 7 * (note.octave ?? 0);\n}\n\n/**\n * The spelled interval from one note to another.\n *\n * When both notes carry octaves, the interval reflects their full signed\n * distance (so `C4 -> C5` is a perfect octave). When either lacks an octave the\n * interval is measured within a single ascending octave from `a` to `b`.\n *\n * @param a The lower/first note.\n * @param b The upper/second note.\n * @returns The diatonic number, quality, and semitone span.\n * @example\n * ```ts\n * import { spelledInterval, parseNote } from '@libraz/libcantus';\n * spelledInterval(parseNote('C4'), parseNote('G4'));\n * // { number: 5, quality: 'P', semitones: 7 }\n * ```\n * @category Pitch & Intervals\n */\nexport function spelledInterval(a: Note, b: Note): SpelledInterval {\n  const octaved = a.octave !== undefined && b.octave !== undefined;\n  let letterSteps: number;\n  let semitones: number;\n  if (octaved) {\n    letterSteps = diatonicIndex(b) - diatonicIndex(a);\n    // Signed pitch distance from a to b, so a note below a yields a negative span.\n    semitones = noteToMidi(b) - noteToMidi(a);\n  } else {\n    letterSteps = mod7(b.letter - a.letter);\n    let rawSemis = mod12(noteToPitchClass(b) - noteToPitchClass(a));\n    // Lift the chromatic span into the octave nearest the diatonic reference so\n    // wraparound intervals stay consistent with the diatonic number instead of\n    // collapsing modulo 12. The correction is bidirectional: an upward wrap\n    // (e.g. Ab -> G# = augmented seventh) adds an octave, while a same-letter or\n    // downward chromatic step (e.g. E -> Eb, F# -> F, C -> Cb = descending\n    // diminished/augmented unison) subtracts one so the sign follows pitch\n    // direction instead of returning a garbage stack of augmentations.\n    const reference = SIMPLE_REFERENCE[letterSteps + 1] ?? 0;\n    if (reference - rawSemis > 6) {\n      rawSemis += 12;\n    } else if (rawSemis - reference > 6) {\n      rawSemis -= 12;\n    }\n    semitones = rawSemis;\n  }\n  const absSteps = Math.abs(letterSteps);\n  const number = absSteps + 1;\n  // Quality comes from the absolute chromatic span; semitones keeps its sign.\n  const quality = qualityFromSpan(number, Math.abs(semitones));\n  return { number, quality, semitones };\n}\n","/**\n * Deterministic seeded pseudo-random number generation shared across the\n * generative modules (rhythm, drums, bass, groove, counter-melody). A single\n * mulberry32 core exposes the small set of samplers those modules need; given a\n * seed the stream is fully reproducible.\n */\n\nimport { assertFiniteNumber, assertInteger, assertRange } from '../validation/index.js';\n\n/**\n * A deterministic PRNG with the sampling helpers the generators need.\n *\n * @category Utilities\n */\nexport type Rng = {\n  /** Next float in [0, 1). */\n  next: () => number;\n  /** True with probability `p`. */\n  prob: (p: number) => boolean;\n  /** Integer in the inclusive range [lo, hi]. */\n  range: (lo: number, hi: number) => number;\n  /** Float in [lo, hi). */\n  float: (lo: number, hi: number) => number;\n};\n\n/**\n * Create a seeded PRNG (mulberry32) exposing the shared samplers.\n *\n * @param seed The 32-bit seed; the same seed always yields the same stream.\n * @returns The seeded generator.\n * @example\n * ```ts\n * import { createRng } from '@libraz/libcantus';\n * const rng = createRng(42);\n * rng.next(); // deterministic float in [0, 1)\n * rng.range(1, 6); // deterministic integer in [1, 6]\n * ```\n * @category Utilities\n */\nexport function createRng(seed: number): Rng {\n  assertFiniteNumber(seed, 'seed');\n  let state = seed >>> 0;\n  const next = () => {\n    state = (state + 0x6d2b79f5) >>> 0;\n    let t = state;\n    t = Math.imul(t ^ (t >>> 15), t | 1);\n    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n  };\n  return {\n    next,\n    prob: (p) => next() < assertRange(p, 0, 1, 'probability'),\n    range: (lo, hi) => {\n      assertInteger(lo, 'range lower bound');\n      assertInteger(hi, 'range upper bound');\n      if (lo > hi) {\n        throw new RangeError(\n          `range lower bound must not exceed upper bound; received ${lo} > ${hi}`,\n        );\n      }\n      assertInteger(hi - lo, 'range span', 0);\n      return lo + Math.floor(next() * (hi - lo + 1));\n    },\n    float: (lo, hi) => {\n      assertFiniteNumber(lo, 'float lower bound');\n      assertFiniteNumber(hi, 'float upper bound');\n      if (lo > hi) {\n        throw new RangeError(\n          `float lower bound must not exceed upper bound; received ${lo} > ${hi}`,\n        );\n      }\n      assertFiniteNumber(hi - lo, 'float span');\n      return lo + next() * (hi - lo);\n    },\n  };\n}\n","/**\n * Tuning and microtonality: frequency conversion, cents, arbitrary equal\n * temperaments (EDO), and just-intonation ratios.\n *\n * The rest of the library reasons in twelve-tone pitch classes, which is a\n * deliberate scope choice for tonal theory. This module is the escape hatch for\n * anyone who needs actual frequencies, cents, non-12 equal temperaments, or the\n * acoustic (just) tuning behind the tempered intervals.\n */\n\nimport {\n  assertFiniteNumber,\n  assertInteger,\n  assertPositiveInt,\n  assertRange,\n} from '../validation/index.js';\n\n/**\n * An equal-tempered tuning: a reference pitch and a number of equal divisions of\n * the octave. With `divisions === 12` a step index is an ordinary MIDI number.\n *\n * @category Pitch & Intervals\n */\nexport type Tuning = {\n  /** Step index (MIDI number when `divisions` is 12) whose frequency is `refFreq`. */\n  refStep: number;\n  /** Frequency in Hz of `refStep`. */\n  refFreq: number;\n  /** Equal divisions of the octave (12 standard; e.g. 19 or 31 for microtonal). */\n  divisions: number;\n};\n\n/**\n * Standard twelve-tone equal temperament, A4 (MIDI 69) = 440 Hz.\n *\n * @category Pitch & Intervals\n */\nexport const TWELVE_TET: Tuning = { refStep: 69, refFreq: 440, divisions: 12 };\n\nfunction assertTuning(tuning: Tuning): Tuning {\n  assertFiniteNumber(tuning.refStep, 'tuning.refStep');\n  assertRange(tuning.refFreq, Number.MIN_VALUE, Number.MAX_VALUE, 'tuning.refFreq');\n  assertPositiveInt(tuning.divisions, 'tuning.divisions');\n  return tuning;\n}\n\n/**\n * Build an equal temperament with `n` divisions of the octave.\n *\n * @param n Divisions of the octave (e.g. 19, 24, 31).\n * @param refFreq Reference frequency in Hz (default 440).\n * @param refStep Step index of the reference (default 69).\n * @returns The tuning.\n * @example\n * ```ts\n * import { edo, frequencyOf } from '@libraz/libcantus';\n * const et19 = edo(19); // { refStep: 69, refFreq: 440, divisions: 19 }\n * frequencyOf(70, et19); // one 19-EDO step above A4\n * ```\n * @category Pitch & Intervals\n */\nexport function edo(n: number, refFreq = 440, refStep = 69): Tuning {\n  assertPositiveInt(n, 'EDO divisions');\n  assertRange(refFreq, Number.MIN_VALUE, Number.MAX_VALUE, 'reference frequency');\n  assertFiniteNumber(refStep, 'reference step');\n  return { refStep, refFreq, divisions: n };\n}\n\n/**\n * Frequency in Hz of a step index under a tuning.\n *\n * @param step Step index (a MIDI number under 12-EDO).\n * @param tuning The tuning (default 12-TET).\n * @returns The frequency in Hz.\n * @example\n * ```ts\n * import { frequencyOf } from '@libraz/libcantus';\n * frequencyOf(69); // 440 (A4 in 12-TET)\n * frequencyOf(60); // middle C in Hz\n * ```\n * @category Pitch & Intervals\n */\nexport function frequencyOf(step: number, tuning: Tuning = TWELVE_TET): number {\n  assertFiniteNumber(step, 'step');\n  assertTuning(tuning);\n  const result = tuning.refFreq * 2 ** ((step - tuning.refStep) / tuning.divisions);\n  return assertRange(result, Number.MIN_VALUE, Number.MAX_VALUE, 'frequency result');\n}\n\n/**\n * Nearest step index to a frequency under a tuning (the inverse of\n * {@link frequencyOf}, rounded).\n *\n * @param freq Frequency in Hz.\n * @param tuning The tuning (default 12-TET).\n * @returns The nearest step index.\n * @category Pitch & Intervals\n */\nexport function nearestStep(freq: number, tuning: Tuning = TWELVE_TET): number {\n  assertRange(freq, Number.MIN_VALUE, Number.MAX_VALUE, 'frequency');\n  assertTuning(tuning);\n  return Math.round(tuning.refStep + tuning.divisions * Math.log2(freq / tuning.refFreq));\n}\n\n/**\n * Interval in cents between two frequencies.\n *\n * @param a Lower/first frequency in Hz.\n * @param b Upper/second frequency in Hz.\n * @returns Cents from `a` to `b` (negative if `b` is lower).\n * @category Pitch & Intervals\n */\nexport function centsBetweenFreq(a: number, b: number): number {\n  assertRange(a, Number.MIN_VALUE, Number.MAX_VALUE, 'first frequency');\n  assertRange(b, Number.MIN_VALUE, Number.MAX_VALUE, 'second frequency');\n  return 1200 * (Math.log2(b) - Math.log2(a));\n}\n\n/**\n * Cents spanned by a number of equal-temperament steps.\n *\n * @param steps Number of steps.\n * @param tuning The tuning (default 12-TET).\n * @returns The cents.\n * @category Pitch & Intervals\n */\nexport function centsOfSteps(steps: number, tuning: Tuning = TWELVE_TET): number {\n  assertFiniteNumber(steps, 'steps');\n  assertTuning(tuning);\n  return assertFiniteNumber((steps * 1200) / tuning.divisions, 'cents result');\n}\n\n/**\n * Cents of a frequency ratio, e.g. `ratioToCents(3, 2)` ≈ 701.955 for the just\n * perfect fifth.\n *\n * @param numerator Ratio numerator.\n * @param denominator Ratio denominator.\n * @returns The interval in cents.\n * @category Pitch & Intervals\n */\nexport function ratioToCents(numerator: number, denominator: number): number {\n  assertRange(numerator, Number.MIN_VALUE, Number.MAX_VALUE, 'ratio numerator');\n  assertRange(denominator, Number.MIN_VALUE, Number.MAX_VALUE, 'ratio denominator');\n  return 1200 * (Math.log2(numerator) - Math.log2(denominator));\n}\n\n/**\n * Five-limit just-intonation ratios for the twelve interval classes above a\n * unison, indexed by semitone class (0..12).\n *\n * @category Pitch & Intervals\n */\nexport const JUST_RATIOS: Record<number, [number, number]> = {\n  0: [1, 1],\n  1: [16, 15],\n  2: [9, 8],\n  3: [6, 5],\n  4: [5, 4],\n  5: [4, 3],\n  6: [45, 32],\n  7: [3, 2],\n  8: [8, 5],\n  9: [5, 3],\n  10: [9, 5],\n  11: [15, 8],\n  12: [2, 1],\n};\n\n/**\n * Cents by which a five-limit just interval departs from its 12-TET tempering\n * (positive means the just interval is wider).\n *\n * @param semitoneClass Semitone class in [0, 12].\n * @returns The deviation in cents.\n * @throws If `semitoneClass` is not an integer in [0, 12].\n * @category Pitch & Intervals\n */\nexport function justDeviationCents(semitoneClass: number): number {\n  assertInteger(semitoneClass, 'semitone class', 0, 12);\n  const ratio = JUST_RATIOS[semitoneClass];\n  if (!ratio) {\n    throw new RangeError(`semitone class has no just ratio: ${semitoneClass}`);\n  }\n  return ratioToCents(ratio[0], ratio[1]) - semitoneClass * 100;\n}\n"],"mappings":"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","names":["IntervalQuality","EPS"]}
+{"version":3,"sources":["/home/runner/work/libcantus/libcantus/dist/core/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,q/GAAC","file":"/home/runner/work/libcantus/libcantus/dist/core/index.cjs"}

package/dist/core/index.d.cts

@@ -1,40 +1,154 @@
-import { N as NoteEvent } from '../types-MGP29r3t.cjs';
-export { K as KeyScale } from '../types-MGP29r3t.cjs';
-import { T as TimeSignature } from '../index-Cl7mhOFM.cjs';
-export { B as BarPosition, 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.cjs';
-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.cjs';
+import { N as NoteEvent } from '../types-BN6_Q9Kl.cjs';
+export { K as KeyScale } from '../types-BN6_Q9Kl.cjs';
+import { T as TimeSignature } from '../index-DXd9JikN.cjs';
+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.cjs';
+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.cjs';
 
-/** A validated note retaining its position in the caller's original array. */
+/**
+ * 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;
 };
-/** Binary-searchable, stable-sorted index over note onsets and active spans. */
+/**
+ * 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`, with later input order winning ties. */
+    /**
+     * 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 notes attack at `beat`. */
+    /** Whether one or more sounding notes attack at `beat`. */
     attacksAt: (beat: number) => boolean;
-    /** Unique attack beats strictly inside `(startBeat, endBeat)`. */
+    /** 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: NoteEvent[], options?: {
+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.
+ * 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
@@ -52,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.
@@ -136,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.
@@ -189,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.
  *
@@ -223,7 +404,7 @@ 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).
@@ -235,28 +416,109 @@ declare const JUST_RATIOS: Record<number, [number, number]>;
  */
 declare function justDeviationCents(semitoneClass: number): number;
 
-/** Default upper bound for synchronous event/window/candidate generation. */
+/**
+ * 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. */
+/**
+ * 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]`. */
+/**
+ * Require an integer in the inclusive range `[min, max]`.
+ *
+ * @category Core
+ */
 declare function assertInteger(value: number, name: string, min?: number, max?: number): number;
-/** Require a positive safe integer, optionally capped by `max`. */
+/**
+ * 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]`. */
+/**
+ * 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. */
-declare function assertGenerationBudget(estimated: number, name: string, limit?: number): number;
-/** Validate a time signature, including additive grouping, before any early return. */
+/**
+ * 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;
-/** Validate the finite fields of one timeline note event. */
-declare function assertNoteEvent(event: NoteEvent, name?: string, options?: {
-    allowNonPositiveDuration?: boolean;
-}): NoteEvent;
-/** Validate an event array and its allocation budget without copying it. */
-declare function assertNoteEvents(events: NoteEvent[], name?: string, options?: {
+/**
+ * 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;
-}): NoteEvent[];
+};
+/**
+ * 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 { DEFAULT_GENERATION_BUDGET, type IndexedNoteEvent, IntervalQuality, JUST_RATIOS, NoteEvent, type NoteEventIndex, type Rng, TWELVE_TET, TimeSignature, type Tuning, assertFiniteNumber, assertGenerationBudget, assertInteger, assertNoteEvent, assertNoteEvents, assertPositiveInt, assertRange, assertTimeSignature, centsBetweenFreq, centsOfSteps, classifyInterval, createNoteEventIndex, createRng, edo, frequencyOf, isConsonantInterval, isPerfectInterval, justDeviationCents, nearestStep, ratioToCents };
+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 };