@libraz/libcantus 1.0.0 → 1.1.0

package/dist/core/index.d.cts

@@ -1,11 +1,11 @@
-export { D as DurationData, I as IndexedNoteEvent, J as JUST_RATIOS, N as NOTE_VALUES, a as NoteEventIndex, b as NoteEventIndexOptions, c as NotePlacement, d as NoteValue, O as OnsetTieBreak, P as PlayabilityIssue, e as PlayabilityIssueType, f as PlayabilityLayer, g as PlayabilityReport, S as SpelledDuration, T as TWELVE_TET, h as TempoEvent, i as TempoMap, j as TuningTable, k as Tuplet, l as beatsToDuration, m as beatsToSeconds, n as beatsToTicks, o as beatsToTiedDurations, p as centsBetweenFreq, q as centsFromNearestStep, r as centsOfSteps, s as centsToRatio, t as createNoteEventIndex, u as durationToBeats, v as durationToSeconds, w as edo, x as frequencyOf, y as justDeviationCents, z as nearestStep, A as playability, B as ratioToCents, C as secondsToBeats, E as stepOf, F as stepsOfCents, G as tempoAt, H as ticksToBeats } from '../index-CGpRv5sl.cjs';
-import { g as NoteEvent } from '../index-B9MNZboQ.cjs';
-export { A as ARTICULATIONS, a as Articulation, B as BudgetExceededError, I as IntervalLike, b as IntervalQualityLabel, c as InvalidInputError, K as KeyName, d as KeyScale, L as LibcantusError, e as LibcantusErrorCode, N as NoSolutionError, f as NoteData, h as NoteLike, i as NoteNameOptions, j as NoteNameSystem, P as ParseResult, S as SpelledInterval, k as detectNoteNameSystem, l as diatonicLetterOf, m as formatKeyName, n as formatNote, o as intervalSemitones, p as isLibcantusError, q as midiToNote, r as naturalPitchClassOf, s as noteToMidi, t as noteToPitchClass, u as parseInterval, v as parseKeyName, w as parseNote, x as pitchClassOf, y as spelledInterval, z as toNoteData, C as toSpelledInterval, D as transposeByInterval, E as transposeNote, F as tryParseInterval, G as tryParseKeyName, H as tryParseNote } from '../index-B9MNZboQ.cjs';
-import { f as StringedProfile } from '../positional-DvH_sd8u.cjs';
-export { I as InstrumentProfile, a as InstrumentProfileCommon, b as InstrumentProfileLike, L as LIMBS, c as Limb, P as PercussionProfile, d as PositionalRng, S as SeedPath, e as StringFingering, g as canSound, h as createPositionalRng, i as deriveSeed, j as fingeringsFor, k as foldIntoRange, l as includeAt, m as instrumentRange } from '../positional-DvH_sd8u.cjs';
+export { D as DurationData, I as IndexedNoteEvent, J as JUST_RATIOS, N as NOTE_VALUES, a as NoteEventIndex, b as NoteEventIndexOptions, c as NotePlacement, d as NoteValue, O as OnsetTieBreak, P as PlayabilityIssue, e as PlayabilityIssueType, f as PlayabilityLayer, g as PlayabilityReport, S as SpelledDuration, T as TWELVE_TET, h as TempoEvent, i as TempoMap, j as TuningTable, k as Tuplet, l as beatsToDuration, m as beatsToSeconds, n as beatsToTicks, o as beatsToTiedDurations, p as centsBetweenFreq, q as centsFromNearestStep, r as centsOfSteps, s as centsToRatio, t as createNoteEventIndex, u as durationToBeats, v as durationToSeconds, w as edo, x as frequencyOf, y as justDeviationCents, z as nearestStep, A as playability, B as ratioToCents, C as secondsToBeats, E as stepOf, F as stepsOfCents, G as tempoAt, H as ticksToBeats } from '../index-cHvbYgJI.cjs';
+import { h as NoteEvent } from '../index-Cy15oTvh.cjs';
+export { A as ARTICULATIONS, a as Articulation, B as BudgetExceededError, I as IntervalData, b as IntervalLike, c as IntervalQualityLabel, d as InvalidInputError, K as KeyName, e as KeyScale, L as LibcantusError, f as LibcantusErrorCode, N as NoSolutionError, g as NoteData, i as NoteLike, j as NoteNameOptions, k as NoteNameSystem, P as ParseResult, S as SpelledInterval, l as detectNoteNameSystem, m as diatonicLetterOf, n as formatKeyName, o as formatNote, p as intervalSemitones, q as isLibcantusError, r as midiToNote, s as naturalPitchClassOf, t as noteToMidi, u as noteToPitchClass, v as parseInterval, w as parseKeyName, x as parseNote, y as pitchClassOf, z as spelledInterval, C as toNoteData, D as toSpelledInterval, E as transposeByInterval, F as transposeNote, G as tryParseInterval, H as tryParseKeyName, J as tryParseNote } from '../index-Cy15oTvh.cjs';
+import { f as StringedProfile } from '../positional-DMZer-FM.cjs';
+export { I as InstrumentProfile, a as InstrumentProfileCommon, b as InstrumentProfileLike, L as LIMBS, c as Limb, P as PercussionProfile, d as PositionalRng, S as SeedPath, e as StringFingering, V as ValidatedPercussionProfile, g as ValidatedProfile, h as ValidatedStringedProfile, i as canSound, j as createPositionalRng, k as deriveSeed, l as fingeringsFor, m as foldIntoRange, n as includeAt, o as instrumentRange, t as toInstrumentProfile, p as toStringedProfile } from '../positional-DMZer-FM.cjs';
 export { C as ConsonanceClass, c as classifyInterval, i as isConsonantInterval, a as isPerfectInterval } from '../index-DInQqT8Q.cjs';
-import { c as MeterMap, T as TimeSignature } from '../index-BkGmlyI3.cjs';
-export { B as BarPosition, M as MeterChange, a as MeterData, b as MeterLike, d as barIndexAt, e as barPositionToBeat, f as barPositionToPulse, g as barStartBeat, h as beatToBarPosition, i as beatsPerBar, j as beatsPerBarAt, k as formatBarPosition, l as formatTimeSignature, m as isCompound, n as isStrongBeat, o as meterAt, p as metricWeight, q as parseTimeSignature, r as pulseBeats, s as pulsesPerBar, t as resolveMeters, u as toMeterData, v as tryParseTimeSignature, w as tuplet } from '../index-BkGmlyI3.cjs';
+import { c as MeterMap, T as TimeSignature } from '../index-D_hzxD8w.cjs';
+export { B as BarPosition, M as MeterChange, a as MeterData, b as MeterLike, d as barIndexAt, e as barPositionToBeat, f as barPositionToPulse, g as barStartBeat, h as beatToBarPosition, i as beatsPerBar, j as beatsPerBarAt, k as formatBarPosition, l as formatTimeSignature, m as isCompound, n as isStrongBeat, o as meterAt, p as metricWeight, q as parseTimeSignature, r as pulseBeats, s as pulsesPerBar, t as resolveMeters, u as toMeterData, v as tryParseTimeSignature, w as tuplet } from '../index-D_hzxD8w.cjs';
 
 /**
  * Electric bass in standard tuning: E1 A1 D2 G2 over a 24-fret neck.
@@ -34,105 +34,6 @@ declare const GUITAR_STANDARD: StringedProfile;
  */
 declare const GUITAR_DROP_D: StringedProfile;
 
-/**
- * The reproducibility contract for generated output.
- *
- * A saved project is a seed plus parameters, and it only reopens as the same
- * piece if the library still turns them into the same notes. Package versions
- * cannot carry that promise: a bug fix inside a generator is a patch release
- * and still moves every note. The algorithm version is the separate number
- * that does carry it, declared here and recorded by the caller alongside the
- * seed.
- */
-/**
- * The generator algorithm version this build produces by default.
- *
- * The guarantee it carries: for a fixed algorithm version, the same inputs —
- * seed, version and every documented parameter — produce the same generated
- * output from any build of this library that accepts that version. It covers
- * what the generators return, and nothing else: analysis results, error
- * messages and output taken under a different version are outside it.
- *
- * Changing what a generator returns for a version it already accepts is a
- * defect. New behaviour raises this constant instead, and the older version
- * keeps producing what it produced. Withdrawing an accepted version is a
- * breaking change, and a project pinned to a withdrawn or not-yet-known
- * version is rejected rather than reinterpreted.
- *
- * @category Utilities
- */
-declare const ALGORITHM_VERSION = 1;
-/**
- * The oldest algorithm version this build still produces.
- *
- * @category Utilities
- */
-declare const MIN_ALGORITHM_VERSION = 1;
-/**
- * Resolve the algorithm version a request runs under.
- *
- * An unpinned request runs at {@link ALGORITHM_VERSION}, which is what a
- * caller who wants the current behaviour means; a caller who wants the piece
- * back records the resolved number and passes it next time. A version this
- * build does not produce is rejected — a project saved by a newer build cannot
- * be reproduced by an older one, and quietly rendering it at another version
- * would return a different piece under the same name.
- *
- * @param requested The pinned version, or undefined for the current one.
- * @returns The version to generate under.
- * @throws If the version is not an integer this build produces.
- * @example
- * ```ts
- * import { ALGORITHM_VERSION, resolveAlgorithmVersion } from '@libraz/libcantus';
- * resolveAlgorithmVersion(undefined); // ALGORITHM_VERSION
- * resolveAlgorithmVersion(ALGORITHM_VERSION); // the pinned value, unchanged
- * ```
- * @category Utilities
- */
-declare function resolveAlgorithmVersion(requested?: number): number;
-
-/**
- * Deterministic seeded pseudo-random number generation shared across the
- * generative modules (rhythm, drums, bass, groove, counter-melody). A single
- * mulberry32 core exposes the small set of samplers those modules need; given a
- * seed the stream is fully reproducible.
- *
- * Around that core sit the pieces that make a whole project reproducible: seeds
- * derived hierarchically from one project number, draws addressed by position
- * rather than by call order, and the algorithm version the output is pinned to.
- */
-
-/**
- * A deterministic PRNG with the sampling helpers the generators need.
- *
- * @category Utilities
- */
-type Rng = {
-    /** Next float in [0, 1). */
-    next: () => number;
-    /** True with probability `p`. */
-    prob: (p: number) => boolean;
-    /** Integer in the inclusive range [lo, hi]. */
-    range: (lo: number, hi: number) => number;
-    /** Float in [lo, hi). */
-    float: (lo: number, hi: number) => number;
-};
-/**
- * Create a seeded PRNG (mulberry32) exposing the shared samplers.
- *
- * @param seed The 32-bit seed; the same seed always yields the same stream.
- * @returns The seeded generator.
- * @example
- * ```ts
- * import { createRng } from '@libraz/libcantus';
- * const rng = createRng(42);
- * rng.next(); // deterministic float in [0, 1)
- * rng.range(1, 6); // deterministic integer in [1, 6]
- * ```
- * @category Utilities
- */
-declare function createRng(seed: number): Rng;
-
 /**
  * Default upper bound for synchronous event/window/candidate generation.
  *
@@ -195,7 +96,10 @@ declare const soundingNotesOnly: typeof dropSilentNotes;
  * @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`.
+ * @throws If the value is not one of `allowed`. The message names the value by
+ *   its type unless it is a string, and echoes at most the head of that string,
+ *   so building it cannot itself fail on a circular object and cannot grow with
+ *   the size of what was pasted into the field.
  *
  * @category Core
  */
@@ -230,7 +134,13 @@ declare function assertTimeSignature(ts: TimeSignature, name?: string): TimeSign
  *
  * The first entry also governs everything before it, so a map need not start at
  * beat 0 — that is what lets a pickup at a negative beat be read in the
- * signature the piece opens in.
+ * signature the piece opens in. Where the first entry is written does not move
+ * the bar lines: the opening signature counts its bars from beat 0 either way,
+ * so beat 0 is the downbeat of bar 0 and the pickup before it is bar -1.
+ *
+ * The map is also bounded, the way an event array is: a map is consulted once
+ * per analysed slot, so its length is a per-slot cost and not only a one-time
+ * one.
  *
  * @category Core
  */
@@ -272,4 +182,108 @@ declare function assertNoteEvent(event: NoteEvent, name?: string, options?: Note
  */
 declare function assertNoteEvents(events: readonly NoteEvent[], name?: string, options?: NoteEventAssertOptions): NoteEvent[];
 
+/**
+ * How generated output is pinned across builds.
+ *
+ * A saved project is a seed plus parameters, and it reopens as the same piece
+ * only while the library turns them into the same notes. The algorithm version
+ * is the number that says which reading of those parameters a project was
+ * written against. It is drawn into every seed, so two versions never draw the
+ * same stream, and a caller records it beside the seed.
+ */
+/**
+ * The generator algorithm version this build produces by default.
+ *
+ * What it carries: for a fixed algorithm version, the same inputs — seed,
+ * version and every documented parameter — produce the same generated output
+ * from a given build. It covers what the generators return, and nothing else:
+ * analysis results, error messages and output taken under a different version
+ * are outside it.
+ *
+ * What it does not carry is a reading frozen against correction. The
+ * generators hold one implementation rather than one per version, so pinning
+ * an older number selects a different draw of the current implementation and
+ * does not restore what that number produced before: a fix to output that was
+ * musically wrong moves the notes of a version already in use, ships as a
+ * patch, and is stated in the changelog. Reproducing a piece exactly therefore
+ * means recording the package version alongside the seed and this number.
+ *
+ * Raising this constant marks a deliberate change of approach rather than a
+ * correction. A project pinned to a version this build does not know is
+ * rejected rather than reinterpreted.
+ *
+ * @category Utilities
+ */
+declare const ALGORITHM_VERSION = 1;
+/**
+ * The oldest algorithm version this build still accepts.
+ *
+ * @category Utilities
+ */
+declare const MIN_ALGORITHM_VERSION = 1;
+/**
+ * Resolve the algorithm version a request runs under.
+ *
+ * An unpinned request runs at {@link ALGORITHM_VERSION}, which is what a
+ * caller who wants the current behaviour means; a caller who wants the piece
+ * back records the resolved number and passes it next time. A version this
+ * build does not produce is rejected — a project saved by a newer build cannot
+ * be reproduced by an older one, and quietly rendering it at another version
+ * would return a different piece under the same name.
+ *
+ * @param requested The pinned version, or undefined for the current one.
+ * @returns The version to generate under.
+ * @throws If the version is not an integer this build produces.
+ * @example
+ * ```ts
+ * import { ALGORITHM_VERSION, resolveAlgorithmVersion } from '@libraz/libcantus';
+ * resolveAlgorithmVersion(undefined); // ALGORITHM_VERSION
+ * resolveAlgorithmVersion(ALGORITHM_VERSION); // the pinned value, unchanged
+ * ```
+ * @category Utilities
+ */
+declare function resolveAlgorithmVersion(requested?: number): number;
+
+/**
+ * Deterministic seeded pseudo-random number generation shared across the
+ * generative modules (rhythm, drums, bass, groove, counter-melody). A single
+ * mulberry32 core exposes the small set of samplers those modules need; given a
+ * seed the stream is fully reproducible.
+ *
+ * Around that core sit the pieces that make a whole project reproducible: seeds
+ * derived hierarchically from one project number, draws addressed by position
+ * rather than by call order, and the algorithm version the output is pinned to.
+ */
+
+/**
+ * A deterministic PRNG with the sampling helpers the generators need.
+ *
+ * @category Utilities
+ */
+type Rng = {
+    /** Next float in [0, 1). */
+    next: () => number;
+    /** True with probability `p`. */
+    prob: (p: number) => boolean;
+    /** Integer in the inclusive range [lo, hi]. */
+    range: (lo: number, hi: number) => number;
+    /** Float in [lo, hi). */
+    float: (lo: number, hi: number) => number;
+};
+/**
+ * Create a seeded PRNG (mulberry32) exposing the shared samplers.
+ *
+ * @param seed The 32-bit seed; the same seed always yields the same stream.
+ * @returns The seeded generator.
+ * @example
+ * ```ts
+ * import { createRng } from '@libraz/libcantus';
+ * const rng = createRng(42);
+ * rng.next(); // deterministic float in [0, 1)
+ * rng.range(1, 6); // deterministic integer in [1, 6]
+ * ```
+ * @category Utilities
+ */
+declare function createRng(seed: number): Rng;
+
 export { ALGORITHM_VERSION, BASS_4_STRING, BASS_5_STRING, DEFAULT_GENERATION_BUDGET, GUITAR_DROP_D, GUITAR_STANDARD, MIN_ALGORITHM_VERSION, MeterMap, NoteEvent, type NoteEventAssertOptions, type Rng, StringedProfile, TimeSignature, assertDegree, assertFiniteNumber, assertFiniteSemitones, assertGenerationBudget, assertInteger, assertMeterMap, assertMidiPitch, assertNoteEvent, assertNoteEvents, assertOneOf, assertPositiveInt, assertRange, assertTimeSignature, clampToMidi, createRng, dropSilentNotes, resolveAlgorithmVersion, soundingNotesOnly };

package/dist/core/index.d.ts

@@ -1,11 +1,11 @@
-export { D as DurationData, I as IndexedNoteEvent, J as JUST_RATIOS, N as NOTE_VALUES, a as NoteEventIndex, b as NoteEventIndexOptions, c as NotePlacement, d as NoteValue, O as OnsetTieBreak, P as PlayabilityIssue, e as PlayabilityIssueType, f as PlayabilityLayer, g as PlayabilityReport, S as SpelledDuration, T as TWELVE_TET, h as TempoEvent, i as TempoMap, j as TuningTable, k as Tuplet, l as beatsToDuration, m as beatsToSeconds, n as beatsToTicks, o as beatsToTiedDurations, p as centsBetweenFreq, q as centsFromNearestStep, r as centsOfSteps, s as centsToRatio, t as createNoteEventIndex, u as durationToBeats, v as durationToSeconds, w as edo, x as frequencyOf, y as justDeviationCents, z as nearestStep, A as playability, B as ratioToCents, C as secondsToBeats, E as stepOf, F as stepsOfCents, G as tempoAt, H as ticksToBeats } from '../index-G1uwGGWQ.js';
-import { g as NoteEvent } from '../index-B9MNZboQ.js';
-export { A as ARTICULATIONS, a as Articulation, B as BudgetExceededError, I as IntervalLike, b as IntervalQualityLabel, c as InvalidInputError, K as KeyName, d as KeyScale, L as LibcantusError, e as LibcantusErrorCode, N as NoSolutionError, f as NoteData, h as NoteLike, i as NoteNameOptions, j as NoteNameSystem, P as ParseResult, S as SpelledInterval, k as detectNoteNameSystem, l as diatonicLetterOf, m as formatKeyName, n as formatNote, o as intervalSemitones, p as isLibcantusError, q as midiToNote, r as naturalPitchClassOf, s as noteToMidi, t as noteToPitchClass, u as parseInterval, v as parseKeyName, w as parseNote, x as pitchClassOf, y as spelledInterval, z as toNoteData, C as toSpelledInterval, D as transposeByInterval, E as transposeNote, F as tryParseInterval, G as tryParseKeyName, H as tryParseNote } from '../index-B9MNZboQ.js';
-import { f as StringedProfile } from '../positional-Cptlj-xs.js';
-export { I as InstrumentProfile, a as InstrumentProfileCommon, b as InstrumentProfileLike, L as LIMBS, c as Limb, P as PercussionProfile, d as PositionalRng, S as SeedPath, e as StringFingering, g as canSound, h as createPositionalRng, i as deriveSeed, j as fingeringsFor, k as foldIntoRange, l as includeAt, m as instrumentRange } from '../positional-Cptlj-xs.js';
+export { D as DurationData, I as IndexedNoteEvent, J as JUST_RATIOS, N as NOTE_VALUES, a as NoteEventIndex, b as NoteEventIndexOptions, c as NotePlacement, d as NoteValue, O as OnsetTieBreak, P as PlayabilityIssue, e as PlayabilityIssueType, f as PlayabilityLayer, g as PlayabilityReport, S as SpelledDuration, T as TWELVE_TET, h as TempoEvent, i as TempoMap, j as TuningTable, k as Tuplet, l as beatsToDuration, m as beatsToSeconds, n as beatsToTicks, o as beatsToTiedDurations, p as centsBetweenFreq, q as centsFromNearestStep, r as centsOfSteps, s as centsToRatio, t as createNoteEventIndex, u as durationToBeats, v as durationToSeconds, w as edo, x as frequencyOf, y as justDeviationCents, z as nearestStep, A as playability, B as ratioToCents, C as secondsToBeats, E as stepOf, F as stepsOfCents, G as tempoAt, H as ticksToBeats } from '../index-9eoQs2C1.js';
+import { h as NoteEvent } from '../index-Cy15oTvh.js';
+export { A as ARTICULATIONS, a as Articulation, B as BudgetExceededError, I as IntervalData, b as IntervalLike, c as IntervalQualityLabel, d as InvalidInputError, K as KeyName, e as KeyScale, L as LibcantusError, f as LibcantusErrorCode, N as NoSolutionError, g as NoteData, i as NoteLike, j as NoteNameOptions, k as NoteNameSystem, P as ParseResult, S as SpelledInterval, l as detectNoteNameSystem, m as diatonicLetterOf, n as formatKeyName, o as formatNote, p as intervalSemitones, q as isLibcantusError, r as midiToNote, s as naturalPitchClassOf, t as noteToMidi, u as noteToPitchClass, v as parseInterval, w as parseKeyName, x as parseNote, y as pitchClassOf, z as spelledInterval, C as toNoteData, D as toSpelledInterval, E as transposeByInterval, F as transposeNote, G as tryParseInterval, H as tryParseKeyName, J as tryParseNote } from '../index-Cy15oTvh.js';
+import { f as StringedProfile } from '../positional-DJgs6ltD.js';
+export { I as InstrumentProfile, a as InstrumentProfileCommon, b as InstrumentProfileLike, L as LIMBS, c as Limb, P as PercussionProfile, d as PositionalRng, S as SeedPath, e as StringFingering, V as ValidatedPercussionProfile, g as ValidatedProfile, h as ValidatedStringedProfile, i as canSound, j as createPositionalRng, k as deriveSeed, l as fingeringsFor, m as foldIntoRange, n as includeAt, o as instrumentRange, t as toInstrumentProfile, p as toStringedProfile } from '../positional-DJgs6ltD.js';
 export { C as ConsonanceClass, c as classifyInterval, i as isConsonantInterval, a as isPerfectInterval } from '../index-DInQqT8Q.js';
-import { c as MeterMap, T as TimeSignature } from '../index-Cj49F892.js';
-export { B as BarPosition, M as MeterChange, a as MeterData, b as MeterLike, d as barIndexAt, e as barPositionToBeat, f as barPositionToPulse, g as barStartBeat, h as beatToBarPosition, i as beatsPerBar, j as beatsPerBarAt, k as formatBarPosition, l as formatTimeSignature, m as isCompound, n as isStrongBeat, o as meterAt, p as metricWeight, q as parseTimeSignature, r as pulseBeats, s as pulsesPerBar, t as resolveMeters, u as toMeterData, v as tryParseTimeSignature, w as tuplet } from '../index-Cj49F892.js';
+import { c as MeterMap, T as TimeSignature } from '../index-Ci3xyows.js';
+export { B as BarPosition, M as MeterChange, a as MeterData, b as MeterLike, d as barIndexAt, e as barPositionToBeat, f as barPositionToPulse, g as barStartBeat, h as beatToBarPosition, i as beatsPerBar, j as beatsPerBarAt, k as formatBarPosition, l as formatTimeSignature, m as isCompound, n as isStrongBeat, o as meterAt, p as metricWeight, q as parseTimeSignature, r as pulseBeats, s as pulsesPerBar, t as resolveMeters, u as toMeterData, v as tryParseTimeSignature, w as tuplet } from '../index-Ci3xyows.js';
 
 /**
  * Electric bass in standard tuning: E1 A1 D2 G2 over a 24-fret neck.
@@ -34,105 +34,6 @@ declare const GUITAR_STANDARD: StringedProfile;
  */
 declare const GUITAR_DROP_D: StringedProfile;
 
-/**
- * The reproducibility contract for generated output.
- *
- * A saved project is a seed plus parameters, and it only reopens as the same
- * piece if the library still turns them into the same notes. Package versions
- * cannot carry that promise: a bug fix inside a generator is a patch release
- * and still moves every note. The algorithm version is the separate number
- * that does carry it, declared here and recorded by the caller alongside the
- * seed.
- */
-/**
- * The generator algorithm version this build produces by default.
- *
- * The guarantee it carries: for a fixed algorithm version, the same inputs —
- * seed, version and every documented parameter — produce the same generated
- * output from any build of this library that accepts that version. It covers
- * what the generators return, and nothing else: analysis results, error
- * messages and output taken under a different version are outside it.
- *
- * Changing what a generator returns for a version it already accepts is a
- * defect. New behaviour raises this constant instead, and the older version
- * keeps producing what it produced. Withdrawing an accepted version is a
- * breaking change, and a project pinned to a withdrawn or not-yet-known
- * version is rejected rather than reinterpreted.
- *
- * @category Utilities
- */
-declare const ALGORITHM_VERSION = 1;
-/**
- * The oldest algorithm version this build still produces.
- *
- * @category Utilities
- */
-declare const MIN_ALGORITHM_VERSION = 1;
-/**
- * Resolve the algorithm version a request runs under.
- *
- * An unpinned request runs at {@link ALGORITHM_VERSION}, which is what a
- * caller who wants the current behaviour means; a caller who wants the piece
- * back records the resolved number and passes it next time. A version this
- * build does not produce is rejected — a project saved by a newer build cannot
- * be reproduced by an older one, and quietly rendering it at another version
- * would return a different piece under the same name.
- *
- * @param requested The pinned version, or undefined for the current one.
- * @returns The version to generate under.
- * @throws If the version is not an integer this build produces.
- * @example
- * ```ts
- * import { ALGORITHM_VERSION, resolveAlgorithmVersion } from '@libraz/libcantus';
- * resolveAlgorithmVersion(undefined); // ALGORITHM_VERSION
- * resolveAlgorithmVersion(ALGORITHM_VERSION); // the pinned value, unchanged
- * ```
- * @category Utilities
- */
-declare function resolveAlgorithmVersion(requested?: number): number;
-
-/**
- * Deterministic seeded pseudo-random number generation shared across the
- * generative modules (rhythm, drums, bass, groove, counter-melody). A single
- * mulberry32 core exposes the small set of samplers those modules need; given a
- * seed the stream is fully reproducible.
- *
- * Around that core sit the pieces that make a whole project reproducible: seeds
- * derived hierarchically from one project number, draws addressed by position
- * rather than by call order, and the algorithm version the output is pinned to.
- */
-
-/**
- * A deterministic PRNG with the sampling helpers the generators need.
- *
- * @category Utilities
- */
-type Rng = {
-    /** Next float in [0, 1). */
-    next: () => number;
-    /** True with probability `p`. */
-    prob: (p: number) => boolean;
-    /** Integer in the inclusive range [lo, hi]. */
-    range: (lo: number, hi: number) => number;
-    /** Float in [lo, hi). */
-    float: (lo: number, hi: number) => number;
-};
-/**
- * Create a seeded PRNG (mulberry32) exposing the shared samplers.
- *
- * @param seed The 32-bit seed; the same seed always yields the same stream.
- * @returns The seeded generator.
- * @example
- * ```ts
- * import { createRng } from '@libraz/libcantus';
- * const rng = createRng(42);
- * rng.next(); // deterministic float in [0, 1)
- * rng.range(1, 6); // deterministic integer in [1, 6]
- * ```
- * @category Utilities
- */
-declare function createRng(seed: number): Rng;
-
 /**
  * Default upper bound for synchronous event/window/candidate generation.
  *
@@ -195,7 +96,10 @@ declare const soundingNotesOnly: typeof dropSilentNotes;
  * @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`.
+ * @throws If the value is not one of `allowed`. The message names the value by
+ *   its type unless it is a string, and echoes at most the head of that string,
+ *   so building it cannot itself fail on a circular object and cannot grow with
+ *   the size of what was pasted into the field.
  *
  * @category Core
  */
@@ -230,7 +134,13 @@ declare function assertTimeSignature(ts: TimeSignature, name?: string): TimeSign
  *
  * The first entry also governs everything before it, so a map need not start at
  * beat 0 — that is what lets a pickup at a negative beat be read in the
- * signature the piece opens in.
+ * signature the piece opens in. Where the first entry is written does not move
+ * the bar lines: the opening signature counts its bars from beat 0 either way,
+ * so beat 0 is the downbeat of bar 0 and the pickup before it is bar -1.
+ *
+ * The map is also bounded, the way an event array is: a map is consulted once
+ * per analysed slot, so its length is a per-slot cost and not only a one-time
+ * one.
  *
  * @category Core
  */
@@ -272,4 +182,108 @@ declare function assertNoteEvent(event: NoteEvent, name?: string, options?: Note
  */
 declare function assertNoteEvents(events: readonly NoteEvent[], name?: string, options?: NoteEventAssertOptions): NoteEvent[];
 
+/**
+ * How generated output is pinned across builds.
+ *
+ * A saved project is a seed plus parameters, and it reopens as the same piece
+ * only while the library turns them into the same notes. The algorithm version
+ * is the number that says which reading of those parameters a project was
+ * written against. It is drawn into every seed, so two versions never draw the
+ * same stream, and a caller records it beside the seed.
+ */
+/**
+ * The generator algorithm version this build produces by default.
+ *
+ * What it carries: for a fixed algorithm version, the same inputs — seed,
+ * version and every documented parameter — produce the same generated output
+ * from a given build. It covers what the generators return, and nothing else:
+ * analysis results, error messages and output taken under a different version
+ * are outside it.
+ *
+ * What it does not carry is a reading frozen against correction. The
+ * generators hold one implementation rather than one per version, so pinning
+ * an older number selects a different draw of the current implementation and
+ * does not restore what that number produced before: a fix to output that was
+ * musically wrong moves the notes of a version already in use, ships as a
+ * patch, and is stated in the changelog. Reproducing a piece exactly therefore
+ * means recording the package version alongside the seed and this number.
+ *
+ * Raising this constant marks a deliberate change of approach rather than a
+ * correction. A project pinned to a version this build does not know is
+ * rejected rather than reinterpreted.
+ *
+ * @category Utilities
+ */
+declare const ALGORITHM_VERSION = 1;
+/**
+ * The oldest algorithm version this build still accepts.
+ *
+ * @category Utilities
+ */
+declare const MIN_ALGORITHM_VERSION = 1;
+/**
+ * Resolve the algorithm version a request runs under.
+ *
+ * An unpinned request runs at {@link ALGORITHM_VERSION}, which is what a
+ * caller who wants the current behaviour means; a caller who wants the piece
+ * back records the resolved number and passes it next time. A version this
+ * build does not produce is rejected — a project saved by a newer build cannot
+ * be reproduced by an older one, and quietly rendering it at another version
+ * would return a different piece under the same name.
+ *
+ * @param requested The pinned version, or undefined for the current one.
+ * @returns The version to generate under.
+ * @throws If the version is not an integer this build produces.
+ * @example
+ * ```ts
+ * import { ALGORITHM_VERSION, resolveAlgorithmVersion } from '@libraz/libcantus';
+ * resolveAlgorithmVersion(undefined); // ALGORITHM_VERSION
+ * resolveAlgorithmVersion(ALGORITHM_VERSION); // the pinned value, unchanged
+ * ```
+ * @category Utilities
+ */
+declare function resolveAlgorithmVersion(requested?: number): number;
+
+/**
+ * Deterministic seeded pseudo-random number generation shared across the
+ * generative modules (rhythm, drums, bass, groove, counter-melody). A single
+ * mulberry32 core exposes the small set of samplers those modules need; given a
+ * seed the stream is fully reproducible.
+ *
+ * Around that core sit the pieces that make a whole project reproducible: seeds
+ * derived hierarchically from one project number, draws addressed by position
+ * rather than by call order, and the algorithm version the output is pinned to.
+ */
+
+/**
+ * A deterministic PRNG with the sampling helpers the generators need.
+ *
+ * @category Utilities
+ */
+type Rng = {
+    /** Next float in [0, 1). */
+    next: () => number;
+    /** True with probability `p`. */
+    prob: (p: number) => boolean;
+    /** Integer in the inclusive range [lo, hi]. */
+    range: (lo: number, hi: number) => number;
+    /** Float in [lo, hi). */
+    float: (lo: number, hi: number) => number;
+};
+/**
+ * Create a seeded PRNG (mulberry32) exposing the shared samplers.
+ *
+ * @param seed The 32-bit seed; the same seed always yields the same stream.
+ * @returns The seeded generator.
+ * @example
+ * ```ts
+ * import { createRng } from '@libraz/libcantus';
+ * const rng = createRng(42);
+ * rng.next(); // deterministic float in [0, 1)
+ * rng.range(1, 6); // deterministic integer in [1, 6]
+ * ```
+ * @category Utilities
+ */
+declare function createRng(seed: number): Rng;
+
 export { ALGORITHM_VERSION, BASS_4_STRING, BASS_5_STRING, DEFAULT_GENERATION_BUDGET, GUITAR_DROP_D, GUITAR_STANDARD, MIN_ALGORITHM_VERSION, MeterMap, NoteEvent, type NoteEventAssertOptions, type Rng, StringedProfile, TimeSignature, assertDegree, assertFiniteNumber, assertFiniteSemitones, assertGenerationBudget, assertInteger, assertMeterMap, assertMidiPitch, assertNoteEvent, assertNoteEvents, assertOneOf, assertPositiveInt, assertRange, assertTimeSignature, clampToMidi, createRng, dropSilentNotes, resolveAlgorithmVersion, soundingNotesOnly };

package/dist/core/index.js

@@ -23,10 +23,9 @@ import {
   stepsOfCents,
   tempoAt,
   ticksToBeats
-} from "../chunk-YH3BIKHH.js";
+} from "../chunk-HOHFYGKW.js";
 import {
   ALGORITHM_VERSION,
-  ARTICULATIONS,
   BASS_4_STRING,
   BASS_5_STRING,
   GUITAR_DROP_D,
@@ -42,32 +41,15 @@ import {
   includeAt,
   instrumentRange,
   playability,
-  resolveAlgorithmVersion
-} from "../chunk-FVSI36UV.js";
+  resolveAlgorithmVersion,
+  toInstrumentProfile,
+  toStringedProfile
+} from "../chunk-X6RJAHII.js";
 import {
-  barIndexAt,
-  barPositionToBeat,
-  barPositionToPulse,
-  barStartBeat,
-  beatToBarPosition,
-  beatsPerBar,
-  beatsPerBarAt,
-  createNoteEventIndex,
-  formatBarPosition,
-  formatTimeSignature,
-  isCompound,
-  isStrongBeat,
-  meterAt,
-  metricWeight,
-  parseTimeSignature,
-  pulseBeats,
-  pulsesPerBar,
-  resolveMeters,
-  toMeterData,
-  tryParseTimeSignature,
-  tuplet
-} from "../chunk-ELCTZUJJ.js";
+  createNoteEventIndex
+} from "../chunk-7GOKQJTQ.js";
 import {
+  ARTICULATIONS,
   BudgetExceededError,
   ConsonanceClass,
   DEFAULT_GENERATION_BUDGET,
@@ -86,17 +68,30 @@ import {
   assertPositiveInt,
   assertRange,
   assertTimeSignature,
+  barIndexAt,
+  barPositionToBeat,
+  barPositionToPulse,
+  barStartBeat,
+  beatToBarPosition,
+  beatsPerBar,
+  beatsPerBarAt,
   clampToMidi,
   classifyInterval,
   detectNoteNameSystem,
   diatonicLetterOf,
   dropSilentNotes,
+  formatBarPosition,
   formatKeyName,
   formatNote,
+  formatTimeSignature,
   intervalSemitones,
+  isCompound,
   isConsonantInterval,
   isLibcantusError,
   isPerfectInterval,
+  isStrongBeat,
+  meterAt,
+  metricWeight,
   midiToNote,
   naturalPitchClassOf,
   noteToMidi,
@@ -104,17 +99,24 @@ import {
   parseInterval,
   parseKeyName,
   parseNote,
+  parseTimeSignature,
   pitchClassOf,
+  pulseBeats,
+  pulsesPerBar,
+  resolveMeters,
   soundingNotesOnly,
   spelledInterval,
+  toMeterData,
   toNoteData,
   toSpelledInterval,
   transposeByInterval,
   transposeNote,
   tryParseInterval,
   tryParseKeyName,
-  tryParseNote
-} from "../chunk-VTI6FOLB.js";
+  tryParseNote,
+  tryParseTimeSignature,
+  tuplet
+} from "../chunk-PQL7E5F6.js";
 export {
   ALGORITHM_VERSION,
   ARTICULATIONS,
@@ -214,9 +216,11 @@ export {
   stepsOfCents,
   tempoAt,
   ticksToBeats,
+  toInstrumentProfile,
   toMeterData,
   toNoteData,
   toSpelledInterval,
+  toStringedProfile,
   transposeByInterval,
   transposeNote,
   tryParseInterval,