@libraz/libcantus 1.2.0 → 1.3.0

package/dist/generate/index.d.cts

@@ -1,15 +1,16 @@
+import { b as MeterLike } from '../index-BMweUlm5.cjs';
+export { M as MeterChange, c as MeterMap, T as TimeSignature } from '../index-BMweUlm5.cjs';
 import { h as NoteEvent, a as Articulation, b as IntervalLike } from '../index-Cy15oTvh.cjs';
 export { I as IntervalData, c as IntervalQualityLabel, e as KeyScale, g as NoteData, S as SpelledInterval } from '../index-Cy15oTvh.cjs';
 import { e as ChordSegment, c as ChordLike, K as KeyLike } from '../coerce-DRERzdve.cjs';
 export { b as ChordData, d as ChordQuality, g as ChordSpan, i as ChordToneRole, k as KeyVariant, l as PitchSpelling, m as ProfileWeights, n as ResolvedKey, r as SpelledKeyLike, s as SpelledKeyScale } from '../coerce-DRERzdve.cjs';
-export { B as BorrowedSource, e as ChordTimeline, H as HarmonicFunction } from '../index-BBWNZS0f.cjs';
+import { h as ChordTimeline } from '../types-D-XgxGvp.cjs';
+export { B as BarPositionProfile, b as BorrowedSource, e as CadenceType, F as FormSection, o as HarmonicFunction, v as MelodicContourShape, y as MotifGraph, z as MotifGraphEdge, G as MotifGraphNode, P as MotifRelationSummary, X as ReductionLevel, Y as ReferenceCadence, Z as ReferenceChord, _ as ReferenceForm, $ as ReferenceHarmony, a0 as ReferenceKeyRegion, a1 as ReferenceMelody, a2 as ReferenceMotif, a3 as ReferencePhrase, a4 as ReferencePhraseMelody, a5 as ReferenceProfile, a7 as RhythmAnalysis } from '../types-D-XgxGvp.cjs';
 import { f as StringedProfile, P as PercussionProfile, c as Limb } from '../positional-DMZer-FM.cjs';
 export { I as InstrumentProfile, a as InstrumentProfileCommon, d as PositionalRng, S as SeedPath } from '../positional-DMZer-FM.cjs';
-import { b as MeterLike } from '../index-BMweUlm5.cjs';
-export { M as MeterChange, c as MeterMap, T as TimeSignature } from '../index-BMweUlm5.cjs';
 export { H as HarmonyRole } from '../index-BL5N2Oyz.cjs';
-import { r as Genre, q as GenerationContextInput, a4 as Vocabulary, s as GridEvent, m as DrumStyle, $ as Section, n as DrumVoice, t as GrooveFeel, k as DrumHit, H as HarmonizeOptions, y as HarmonizeResult } from '../index-BNSM-DSk.cjs';
-export { B as BAR_STEPS, a as BASS_STYLES, b as BEAT_STEPS, c as BORROWED_DEGREES, d as BassLineOptions, e as BassSegment, f as BassStyle, g as BorrowedChord, C as Complexity, h as CounterMelodyOptions, D as DRUM_NOTES, i as DeformOptions, j as Draw, l as DrumRole, o as DrumsOptions, E as EuclideanKick, G as GENRES, p as GenerationContext, u as GrooveSlot, v as GrooveStyle, w as GrooveTemplate, x as HarmonizePlacement, z as HumanizeOptions, M as MelodyNote, A as MotifCell, F as MotifContour, I as MotifNote, J as MotifOptions, K as MotifTransform, O as ORNAMENT_STYLES, L as OrnamentOptions, N as OrnamentStyle, P as PROVENANCE_BASES, Q as ProgFunction, R as ProgStyle, S as ProgressionDegree, T as ProgressionOptions, U as ProgressionPreset, V as Provenance, W as ProvenanceBasis, X as ResolvedContext, Y as RhythmEvent, Z as RhythmOptions, _ as STEP_BEATS, a0 as SubstituteOptions, a1 as Substitution, a2 as SubstitutionType, a3 as SyncopateOptions, a5 as VocabularyQuery, a6 as applyGrooveTemplate, a7 as assertVocabulary, a8 as deform, a9 as developMotif, aa as double, ab as doubleTime, ac as drumVoiceOf, ad as extractGrooveTemplate, ae as fitsQuery, af as generateBassLine, ag as generateCounterMelody, ah as generateDrums, ai as generateMotif, aj as generateProgression, ak as generateRhythm, al as gridMetricWeight, am as halfTime, an as humanize, ao as mergeVocabulary, ap as modalInterchangePalette, aq as motifToNoteEvents, ar as negativeHarmonyMirror, as as onsetWeightCurve, at as ornament, au as ornamentBy, av as pickProgressionPreset, aw as pickVocabulary, ax as progressions, ay as progressionsByStyle, az as resolveContext, aA as rhythmDensity, aB as rhythmToNoteEvents, aC as selectVocabulary, aD as substituteChord, aE as syncopate, aF as thin, aG as transformMotif, aH as vocabularyOfKind, aI as withinCeiling } from '../index-BNSM-DSk.cjs';
+import { x as Genre, w as GenerationContextInput, ah as Vocabulary, y as GridEvent, r as DrumStyle, ac as Section, s as DrumVoice, z as GrooveFeel, p as DrumHit, I as HarmonizeOptions, K as HarmonizeResult, j as CompositionPlan } from '../index-CY-3NVfy.cjs';
+export { B as BAR_STEPS, a as BASS_STYLES, b as BEAT_STEPS, c as BORROWED_DEGREES, d as BassLineOptions, e as BassSegment, f as BassStyle, g as BorrowedChord, C as COMPOSITION_PLAN_VERSION, h as Complexity, i as CompositionEvaluation, k as CompositionPlanOptions, l as CompositionViolation, m as CounterMelodyOptions, D as DRUM_NOTES, n as DeformOptions, o as Draw, q as DrumRole, t as DrumsOptions, E as EuclideanKick, u as EvaluateCompositionOptions, G as GENRES, v as GenerationContext, A as GrooveSlot, F as GrooveStyle, H as GrooveTemplate, J as HarmonizePlacement, L as HumanizeOptions, M as MelodyNote, N as MelodyOptions, O as MotifCell, P as MotifContour, Q as MotifNote, R as MotifOptions, S as MotifTransform, T as ORNAMENT_STYLES, U as OrnamentOptions, V as OrnamentStyle, W as PROVENANCE_BASES, X as PlannedChord, Y as PlannedMotif, Z as PlannedPhrase, _ as PlannedRhythm, $ as PlannedSection, a0 as PreserveWeights, a1 as ProgFunction, a2 as ProgStyle, a3 as ProgressionDegree, a4 as ProgressionOptions, a5 as ProgressionPreset, a6 as Provenance, a7 as ProvenanceBasis, a8 as ResolvedContext, a9 as RhythmEvent, aa as RhythmOptions, ab as STEP_BEATS, ad as SubstituteOptions, ae as Substitution, af as SubstitutionType, ag as SyncopateOptions, ai as VocabularyQuery, aj as applyGrooveTemplate, ak as assertVocabulary, al as deform, am as deriveCompositionPlan, an as developMotif, ao as double, ap as doubleTime, aq as drumVoiceOf, ar as evaluateComposition, as as extractGrooveTemplate, at as fitsQuery, au as generateBassLine, av as generateCounterMelody, aw as generateDrums, ax as generateMelody, ay as generateMotif, az as generateProgression, aA as generateRhythm, aB as gridMetricWeight, aC as halfTime, aD as humanize, aE as mergeVocabulary, aF as modalInterchangePalette, aG as motifToNoteEvents, aH as negativeHarmonyMirror, aI as onsetWeightCurve, aJ as ornament, aK as ornamentBy, aL as pickProgressionPreset, aM as pickVocabulary, aN as progressions, aO as progressionsByStyle, aP as resolveContext, aQ as rhythmDensity, aR as rhythmToNoteEvents, aS as selectVocabulary, aT as substituteChord, aU as syncopate, aV as thin, aW as transformMotif, aX as vocabularyOfKind, aY as withinCeiling } from '../index-CY-3NVfy.cjs';
 
 /**
  * The playing-difficulty ceiling, as the generators apply it.
@@ -717,4 +718,81 @@ declare function classifyMelodyTones(melody: readonly NoteEvent[], ts: MeterLike
  */
 declare function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult;
 
-export { Articulation, BASS_LICKS, type BassLick, ChordLike, ChordSegment, type ClassifiedMelodyTone, DRUM_KIT, DRUM_PATTERNS, DrumHit, type DrumPattern, type DrumPatternOptions, type DrumStroke, DrumStyle, type DrumVocabulary, DrumVoice, FILL_ARCHETYPES, FILL_TYPES, type FillArchetype, type FillStroke, type FillType, type FillVelocity, GenerationContextInput, Genre, GridEvent, GrooveFeel, HarmonizeOptions, HarmonizeResult, type ImitationAnswer, type ImitationOptions, IntervalLike, KICK_FIGURES, KICK_STEPS, KeyLike, type KickFigure, type KickPattern, type KickSlot, type LickMaterial, type LickNote, Limb, MAX_DIFFICULTY, MIN_DIFFICULTY, type MelodyToneRole, MeterLike, NoteEvent, PercussionProfile, type PlaceLicksOptions, Section, StringedProfile, Vocabulary, classifyMelodyTones, harmonizeMelody, imitate, isDrumPattern, isFillArchetype, isLickMaterial, placeDrumPattern, placeLicks, sustainsShift, sustainsStrokes };
+/**
+ * Reading a {@link CompositionPlan}'s harmony as a chord timeline.
+ *
+ * Kept apart from the plan types so the public reader can validate its plan
+ * without the types module importing the validator that imports it.
+ */
+
+/**
+ * Read a plan's harmony as a chord timeline.
+ *
+ * The one way a generator or an evaluator reads chords out of a plan: each
+ * entry in `plan.harmony` is resolved against its key and placed at its own
+ * beat, so the timeline this returns always agrees with the plan it was built
+ * from.
+ *
+ * @param plan The plan to read harmony from.
+ * @returns A chord timeline spanning `plan.span`.
+ * @throws {InvalidInputError} If the plan is not a valid composition plan.
+ * @example
+ * ```ts
+ * import { planTimeline, resolveKey } from '@libraz/libcantus';
+ * const plan = {
+ *   planVersion: 1, seed: 0, algorithmVersion: 1,
+ *   keys: [resolveKey('C major')], meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
+ *   span: { startBeat: 0, endBeat: 4, bars: 1 }, sections: [], phrases: [],
+ *   harmony: [{ startBeat: 0, endBeat: 4, key: 0, roman: 'I' }], motifs: [],
+ *   rhythm: { onsetLevels: [1, 0, 0, 0, 0, 0], interOnsetShares: new Array(17).fill(0).fill(1, 8, 9), syncopation: 0 },
+ * };
+ * planTimeline(plan).at(0); // the I chord in C major
+ * ```
+ * @category Composition
+ */
+declare function planTimeline(plan: CompositionPlan): ChordTimeline;
+
+/**
+ * Boundary validation for {@link CompositionPlan}: a caller can hand this a
+ * value restored from JSON, a config file, or a plugin host, and every field
+ * is checked before a generator or evaluator reads it. A violation names the
+ * path to the offending field, so a malformed document is diagnosed at the
+ * field that is wrong rather than wherever the first bad read happens to land.
+ */
+
+/**
+ * Reject a value that is not a {@link CompositionPlan}.
+ *
+ * A plan is the shape a caller's stored JSON, a config file, or a plugin host
+ * most plausibly hands back malformed: a missing field, a distribution that no
+ * longer sums to 1, an index a later edit left dangling, a numeral no reader
+ * can parse, a derivation that points at itself or at a later motif. Every
+ * field is checked before a generator or evaluator reads it, and a violation
+ * names the path to the field that is wrong.
+ *
+ * @param value The value to check.
+ * @param name What the value is, for the error message.
+ * @returns The same plan.
+ * @throws {InvalidInputError} If the value is not a valid composition plan.
+ * @example
+ * ```ts
+ * import { assertCompositionPlan } from '@libraz/libcantus';
+ * import { resolveKey } from '@libraz/libcantus';
+ * const plan = {
+ *   planVersion: 1, seed: 0, algorithmVersion: 1,
+ *   keys: [resolveKey('C major')],
+ *   meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
+ *   span: { startBeat: 0, endBeat: 4, bars: 1 },
+ *   sections: [{ label: 'A', startBeat: 0, endBeat: 4 }],
+ *   phrases: [],
+ *   harmony: [{ startBeat: 0, endBeat: 4, key: 0, roman: 'I' }],
+ *   motifs: [],
+ *   rhythm: { onsetLevels: [1, 0, 0, 0, 0, 0], interOnsetShares: new Array(17).fill(0).fill(1, 8, 9), syncopation: 0 },
+ * };
+ * assertCompositionPlan(plan); // the plan, unchanged
+ * ```
+ * @category Composition
+ */
+declare function assertCompositionPlan(value: unknown, name?: string): CompositionPlan;
+
+export { Articulation, BASS_LICKS, type BassLick, ChordLike, ChordSegment, ChordTimeline, type ClassifiedMelodyTone, CompositionPlan, DRUM_KIT, DRUM_PATTERNS, DrumHit, type DrumPattern, type DrumPatternOptions, type DrumStroke, DrumStyle, type DrumVocabulary, DrumVoice, FILL_ARCHETYPES, FILL_TYPES, type FillArchetype, type FillStroke, type FillType, type FillVelocity, GenerationContextInput, Genre, GridEvent, GrooveFeel, HarmonizeOptions, HarmonizeResult, type ImitationAnswer, type ImitationOptions, IntervalLike, KICK_FIGURES, KICK_STEPS, KeyLike, type KickFigure, type KickPattern, type KickSlot, type LickMaterial, type LickNote, Limb, MAX_DIFFICULTY, MIN_DIFFICULTY, type MelodyToneRole, MeterLike, NoteEvent, PercussionProfile, type PlaceLicksOptions, Section, StringedProfile, Vocabulary, assertCompositionPlan, classifyMelodyTones, harmonizeMelody, imitate, isDrumPattern, isFillArchetype, isLickMaterial, placeDrumPattern, placeLicks, planTimeline, sustainsShift, sustainsStrokes };

package/dist/generate/index.d.ts

@@ -1,15 +1,16 @@
+import { b as MeterLike } from '../index-CL4b4gUQ.js';
+export { M as MeterChange, c as MeterMap, T as TimeSignature } from '../index-CL4b4gUQ.js';
 import { h as NoteEvent, a as Articulation, b as IntervalLike } from '../index-Cy15oTvh.js';
 export { I as IntervalData, c as IntervalQualityLabel, e as KeyScale, g as NoteData, S as SpelledInterval } from '../index-Cy15oTvh.js';
 import { e as ChordSegment, c as ChordLike, K as KeyLike } from '../coerce-DP0vYu-x.js';
 export { b as ChordData, d as ChordQuality, g as ChordSpan, i as ChordToneRole, k as KeyVariant, l as PitchSpelling, m as ProfileWeights, n as ResolvedKey, r as SpelledKeyLike, s as SpelledKeyScale } from '../coerce-DP0vYu-x.js';
-export { B as BorrowedSource, e as ChordTimeline, H as HarmonicFunction } from '../index-CJBBiAmU.js';
+import { h as ChordTimeline } from '../types-Dh7C064C.js';
+export { B as BarPositionProfile, b as BorrowedSource, e as CadenceType, F as FormSection, o as HarmonicFunction, v as MelodicContourShape, y as MotifGraph, z as MotifGraphEdge, G as MotifGraphNode, P as MotifRelationSummary, X as ReductionLevel, Y as ReferenceCadence, Z as ReferenceChord, _ as ReferenceForm, $ as ReferenceHarmony, a0 as ReferenceKeyRegion, a1 as ReferenceMelody, a2 as ReferenceMotif, a3 as ReferencePhrase, a4 as ReferencePhraseMelody, a5 as ReferenceProfile, a7 as RhythmAnalysis } from '../types-Dh7C064C.js';
 import { f as StringedProfile, P as PercussionProfile, c as Limb } from '../positional-DJgs6ltD.js';
 export { I as InstrumentProfile, a as InstrumentProfileCommon, d as PositionalRng, S as SeedPath } from '../positional-DJgs6ltD.js';
-import { b as MeterLike } from '../index-CL4b4gUQ.js';
-export { M as MeterChange, c as MeterMap, T as TimeSignature } from '../index-CL4b4gUQ.js';
 export { H as HarmonyRole } from '../index-Dw2DP7vm.js';
-import { r as Genre, q as GenerationContextInput, a4 as Vocabulary, s as GridEvent, m as DrumStyle, $ as Section, n as DrumVoice, t as GrooveFeel, k as DrumHit, H as HarmonizeOptions, y as HarmonizeResult } from '../index-BJgP97N1.js';
-export { B as BAR_STEPS, a as BASS_STYLES, b as BEAT_STEPS, c as BORROWED_DEGREES, d as BassLineOptions, e as BassSegment, f as BassStyle, g as BorrowedChord, C as Complexity, h as CounterMelodyOptions, D as DRUM_NOTES, i as DeformOptions, j as Draw, l as DrumRole, o as DrumsOptions, E as EuclideanKick, G as GENRES, p as GenerationContext, u as GrooveSlot, v as GrooveStyle, w as GrooveTemplate, x as HarmonizePlacement, z as HumanizeOptions, M as MelodyNote, A as MotifCell, F as MotifContour, I as MotifNote, J as MotifOptions, K as MotifTransform, O as ORNAMENT_STYLES, L as OrnamentOptions, N as OrnamentStyle, P as PROVENANCE_BASES, Q as ProgFunction, R as ProgStyle, S as ProgressionDegree, T as ProgressionOptions, U as ProgressionPreset, V as Provenance, W as ProvenanceBasis, X as ResolvedContext, Y as RhythmEvent, Z as RhythmOptions, _ as STEP_BEATS, a0 as SubstituteOptions, a1 as Substitution, a2 as SubstitutionType, a3 as SyncopateOptions, a5 as VocabularyQuery, a6 as applyGrooveTemplate, a7 as assertVocabulary, a8 as deform, a9 as developMotif, aa as double, ab as doubleTime, ac as drumVoiceOf, ad as extractGrooveTemplate, ae as fitsQuery, af as generateBassLine, ag as generateCounterMelody, ah as generateDrums, ai as generateMotif, aj as generateProgression, ak as generateRhythm, al as gridMetricWeight, am as halfTime, an as humanize, ao as mergeVocabulary, ap as modalInterchangePalette, aq as motifToNoteEvents, ar as negativeHarmonyMirror, as as onsetWeightCurve, at as ornament, au as ornamentBy, av as pickProgressionPreset, aw as pickVocabulary, ax as progressions, ay as progressionsByStyle, az as resolveContext, aA as rhythmDensity, aB as rhythmToNoteEvents, aC as selectVocabulary, aD as substituteChord, aE as syncopate, aF as thin, aG as transformMotif, aH as vocabularyOfKind, aI as withinCeiling } from '../index-BJgP97N1.js';
+import { x as Genre, w as GenerationContextInput, ah as Vocabulary, y as GridEvent, r as DrumStyle, ac as Section, s as DrumVoice, z as GrooveFeel, p as DrumHit, I as HarmonizeOptions, K as HarmonizeResult, j as CompositionPlan } from '../index-zaZdmnU4.js';
+export { B as BAR_STEPS, a as BASS_STYLES, b as BEAT_STEPS, c as BORROWED_DEGREES, d as BassLineOptions, e as BassSegment, f as BassStyle, g as BorrowedChord, C as COMPOSITION_PLAN_VERSION, h as Complexity, i as CompositionEvaluation, k as CompositionPlanOptions, l as CompositionViolation, m as CounterMelodyOptions, D as DRUM_NOTES, n as DeformOptions, o as Draw, q as DrumRole, t as DrumsOptions, E as EuclideanKick, u as EvaluateCompositionOptions, G as GENRES, v as GenerationContext, A as GrooveSlot, F as GrooveStyle, H as GrooveTemplate, J as HarmonizePlacement, L as HumanizeOptions, M as MelodyNote, N as MelodyOptions, O as MotifCell, P as MotifContour, Q as MotifNote, R as MotifOptions, S as MotifTransform, T as ORNAMENT_STYLES, U as OrnamentOptions, V as OrnamentStyle, W as PROVENANCE_BASES, X as PlannedChord, Y as PlannedMotif, Z as PlannedPhrase, _ as PlannedRhythm, $ as PlannedSection, a0 as PreserveWeights, a1 as ProgFunction, a2 as ProgStyle, a3 as ProgressionDegree, a4 as ProgressionOptions, a5 as ProgressionPreset, a6 as Provenance, a7 as ProvenanceBasis, a8 as ResolvedContext, a9 as RhythmEvent, aa as RhythmOptions, ab as STEP_BEATS, ad as SubstituteOptions, ae as Substitution, af as SubstitutionType, ag as SyncopateOptions, ai as VocabularyQuery, aj as applyGrooveTemplate, ak as assertVocabulary, al as deform, am as deriveCompositionPlan, an as developMotif, ao as double, ap as doubleTime, aq as drumVoiceOf, ar as evaluateComposition, as as extractGrooveTemplate, at as fitsQuery, au as generateBassLine, av as generateCounterMelody, aw as generateDrums, ax as generateMelody, ay as generateMotif, az as generateProgression, aA as generateRhythm, aB as gridMetricWeight, aC as halfTime, aD as humanize, aE as mergeVocabulary, aF as modalInterchangePalette, aG as motifToNoteEvents, aH as negativeHarmonyMirror, aI as onsetWeightCurve, aJ as ornament, aK as ornamentBy, aL as pickProgressionPreset, aM as pickVocabulary, aN as progressions, aO as progressionsByStyle, aP as resolveContext, aQ as rhythmDensity, aR as rhythmToNoteEvents, aS as selectVocabulary, aT as substituteChord, aU as syncopate, aV as thin, aW as transformMotif, aX as vocabularyOfKind, aY as withinCeiling } from '../index-zaZdmnU4.js';
 
 /**
  * The playing-difficulty ceiling, as the generators apply it.
@@ -717,4 +718,81 @@ declare function classifyMelodyTones(melody: readonly NoteEvent[], ts: MeterLike
  */
 declare function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult;
 
-export { Articulation, BASS_LICKS, type BassLick, ChordLike, ChordSegment, type ClassifiedMelodyTone, DRUM_KIT, DRUM_PATTERNS, DrumHit, type DrumPattern, type DrumPatternOptions, type DrumStroke, DrumStyle, type DrumVocabulary, DrumVoice, FILL_ARCHETYPES, FILL_TYPES, type FillArchetype, type FillStroke, type FillType, type FillVelocity, GenerationContextInput, Genre, GridEvent, GrooveFeel, HarmonizeOptions, HarmonizeResult, type ImitationAnswer, type ImitationOptions, IntervalLike, KICK_FIGURES, KICK_STEPS, KeyLike, type KickFigure, type KickPattern, type KickSlot, type LickMaterial, type LickNote, Limb, MAX_DIFFICULTY, MIN_DIFFICULTY, type MelodyToneRole, MeterLike, NoteEvent, PercussionProfile, type PlaceLicksOptions, Section, StringedProfile, Vocabulary, classifyMelodyTones, harmonizeMelody, imitate, isDrumPattern, isFillArchetype, isLickMaterial, placeDrumPattern, placeLicks, sustainsShift, sustainsStrokes };
+/**
+ * Reading a {@link CompositionPlan}'s harmony as a chord timeline.
+ *
+ * Kept apart from the plan types so the public reader can validate its plan
+ * without the types module importing the validator that imports it.
+ */
+
+/**
+ * Read a plan's harmony as a chord timeline.
+ *
+ * The one way a generator or an evaluator reads chords out of a plan: each
+ * entry in `plan.harmony` is resolved against its key and placed at its own
+ * beat, so the timeline this returns always agrees with the plan it was built
+ * from.
+ *
+ * @param plan The plan to read harmony from.
+ * @returns A chord timeline spanning `plan.span`.
+ * @throws {InvalidInputError} If the plan is not a valid composition plan.
+ * @example
+ * ```ts
+ * import { planTimeline, resolveKey } from '@libraz/libcantus';
+ * const plan = {
+ *   planVersion: 1, seed: 0, algorithmVersion: 1,
+ *   keys: [resolveKey('C major')], meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
+ *   span: { startBeat: 0, endBeat: 4, bars: 1 }, sections: [], phrases: [],
+ *   harmony: [{ startBeat: 0, endBeat: 4, key: 0, roman: 'I' }], motifs: [],
+ *   rhythm: { onsetLevels: [1, 0, 0, 0, 0, 0], interOnsetShares: new Array(17).fill(0).fill(1, 8, 9), syncopation: 0 },
+ * };
+ * planTimeline(plan).at(0); // the I chord in C major
+ * ```
+ * @category Composition
+ */
+declare function planTimeline(plan: CompositionPlan): ChordTimeline;
+
+/**
+ * Boundary validation for {@link CompositionPlan}: a caller can hand this a
+ * value restored from JSON, a config file, or a plugin host, and every field
+ * is checked before a generator or evaluator reads it. A violation names the
+ * path to the offending field, so a malformed document is diagnosed at the
+ * field that is wrong rather than wherever the first bad read happens to land.
+ */
+
+/**
+ * Reject a value that is not a {@link CompositionPlan}.
+ *
+ * A plan is the shape a caller's stored JSON, a config file, or a plugin host
+ * most plausibly hands back malformed: a missing field, a distribution that no
+ * longer sums to 1, an index a later edit left dangling, a numeral no reader
+ * can parse, a derivation that points at itself or at a later motif. Every
+ * field is checked before a generator or evaluator reads it, and a violation
+ * names the path to the field that is wrong.
+ *
+ * @param value The value to check.
+ * @param name What the value is, for the error message.
+ * @returns The same plan.
+ * @throws {InvalidInputError} If the value is not a valid composition plan.
+ * @example
+ * ```ts
+ * import { assertCompositionPlan } from '@libraz/libcantus';
+ * import { resolveKey } from '@libraz/libcantus';
+ * const plan = {
+ *   planVersion: 1, seed: 0, algorithmVersion: 1,
+ *   keys: [resolveKey('C major')],
+ *   meters: [{ startBeat: 0, ts: { numerator: 4, denominator: 4 } }],
+ *   span: { startBeat: 0, endBeat: 4, bars: 1 },
+ *   sections: [{ label: 'A', startBeat: 0, endBeat: 4 }],
+ *   phrases: [],
+ *   harmony: [{ startBeat: 0, endBeat: 4, key: 0, roman: 'I' }],
+ *   motifs: [],
+ *   rhythm: { onsetLevels: [1, 0, 0, 0, 0, 0], interOnsetShares: new Array(17).fill(0).fill(1, 8, 9), syncopation: 0 },
+ * };
+ * assertCompositionPlan(plan); // the plan, unchanged
+ * ```
+ * @category Composition
+ */
+declare function assertCompositionPlan(value: unknown, name?: string): CompositionPlan;
+
+export { Articulation, BASS_LICKS, type BassLick, ChordLike, ChordSegment, ChordTimeline, type ClassifiedMelodyTone, CompositionPlan, DRUM_KIT, DRUM_PATTERNS, DrumHit, type DrumPattern, type DrumPatternOptions, type DrumStroke, DrumStyle, type DrumVocabulary, DrumVoice, FILL_ARCHETYPES, FILL_TYPES, type FillArchetype, type FillStroke, type FillType, type FillVelocity, GenerationContextInput, Genre, GridEvent, GrooveFeel, HarmonizeOptions, HarmonizeResult, type ImitationAnswer, type ImitationOptions, IntervalLike, KICK_FIGURES, KICK_STEPS, KeyLike, type KickFigure, type KickPattern, type KickSlot, type LickMaterial, type LickNote, Limb, MAX_DIFFICULTY, MIN_DIFFICULTY, type MelodyToneRole, MeterLike, NoteEvent, PercussionProfile, type PlaceLicksOptions, Section, StringedProfile, Vocabulary, assertCompositionPlan, classifyMelodyTones, harmonizeMelody, imitate, isDrumPattern, isFillArchetype, isLickMaterial, placeDrumPattern, placeLicks, planTimeline, sustainsShift, sustainsStrokes };

package/dist/generate/index.js

@@ -4,6 +4,7 @@ import {
   BASS_STYLES,
   BEAT_STEPS,
   BORROWED_DEGREES,
+  COMPOSITION_PLAN_VERSION,
   DRUM_KIT,
   DRUM_NOTES,
   DRUM_PATTERNS,
@@ -18,18 +19,22 @@ import {
   PROVENANCE_BASES,
   STEP_BEATS,
   applyGrooveTemplate,
+  assertCompositionPlan,
   assertVocabulary,
   classifyMelodyTones,
   deform,
+  deriveCompositionPlan,
   developMotif,
   double,
   doubleTime,
   drumVoiceOf,
+  evaluateComposition,
   extractGrooveTemplate,
   fitsQuery,
   generateBassLine,
   generateCounterMelody,
   generateDrums,
+  generateMelody,
   generateMotif,
   generateProgression,
   generateRhythm,
@@ -52,6 +57,7 @@ import {
   pickVocabulary,
   placeDrumPattern,
   placeLicks,
+  planTimeline,
   progressions,
   progressionsByStyle,
   resolveContext,
@@ -66,8 +72,8 @@ import {
   transformMotif,
   vocabularyOfKind,
   withinCeiling
-} from "../chunk-Q6LFSAKV.js";
-import "../chunk-H2KJHBW4.js";
+} from "../chunk-CPMB7P75.js";
+import "../chunk-GNVN4PPJ.js";
 import "../chunk-7KG3RTYS.js";
 import "../chunk-PUKJP2Z5.js";
 import "../chunk-NB25P3EH.js";
@@ -79,6 +85,7 @@ export {
   BASS_STYLES,
   BEAT_STEPS,
   BORROWED_DEGREES,
+  COMPOSITION_PLAN_VERSION,
   DRUM_KIT,
   DRUM_NOTES,
   DRUM_PATTERNS,
@@ -93,18 +100,22 @@ export {
   PROVENANCE_BASES,
   STEP_BEATS,
   applyGrooveTemplate,
+  assertCompositionPlan,
   assertVocabulary,
   classifyMelodyTones,
   deform,
+  deriveCompositionPlan,
   developMotif,
   double,
   doubleTime,
   drumVoiceOf,
+  evaluateComposition,
   extractGrooveTemplate,
   fitsQuery,
   generateBassLine,
   generateCounterMelody,
   generateDrums,
+  generateMelody,
   generateMotif,
   generateProgression,
   generateRhythm,
@@ -127,6 +138,7 @@ export {
   pickVocabulary,
   placeDrumPattern,
   placeLicks,
+  planTimeline,
   progressions,
   progressionsByStyle,
   resolveContext,