@libraz/libcantus 1.2.0 → 1.4.0

package/dist/model/index.d.ts

@@ -1,23 +1,23 @@
-import { R as ReduceProgressionOptions, v as ReducedChord, D as DetectChordOptions, C as ChordMatch, h as DetectKeyOptions, K as KeyMatch, d as AugmentedSixthKind, t as PhraseOptions, P as Phrase, S as StructuralCadence, i as FormSectionOptions, F as FormSection, j as HypermeterOptions, H as Hypermeter, E as ExtractMotifsOptions, p as MotifData, k as MelodicContour, c as ArrangementTrack, a as ArrangementOptions, A as ArrangementAnalysis, e as Conflict, z as TrackEdit, T as TensionPoint, r as MotifRelation } from '../index-BRMbPkHE.js';
-export { b as ArrangementSession, f as ConflictPartner, g as ContourDirection, l as MelodicContourShape, o as ModalScaleName, q as MotifOccurrence, s as MotifRelationKind, u as PhraseSignal, w as ReductionBasis, x as ReductionLevel, y as TrackAnalysis, B as TrackRole } from '../index-BRMbPkHE.js';
-import { k as KeyRegion, f as ChordTimelineOptions, C as CadenceHit, l as KeyTimelineOptions, h as ChordToRomanOptions, e as ChordTimeline, H as HarmonicFunction, A as AnalyzeChordOptions, D as DetectCadenceOptions, c as ChordAnalysis, b as CadenceResult, E as ExplainRomanOptions, m as RomanExplanation, B as BorrowedSource, a as AnalyzedNote, I as IdentifiedVoiceNote } from '../index-CJBBiAmU.js';
-export { d as ChordSegmentation, g as ChordTimelineResult, K as KeyContext, i as KeyProfileName, j as KeyProfilePair, P as PivotChord, R as RejectedCandidate, S as SuspensionFigure, T as TheoryLabel, V as VoiceNote } from '../index-CJBBiAmU.js';
-import { c as IntervalQualityLabel, I as IntervalData, P as ParseResult, S as SpelledInterval, g as Note$1, j as NoteNameOptions, b as IntervalLike, h as NoteEvent, i as NoteLike, e as KeyScale, a as Articulation } from '../index-Cy15oTvh.js';
-export { B as BudgetExceededError, d as InvalidInputError, L as LibcantusError, N as NoSolutionError, k as NoteNameSystem } from '../index-Cy15oTvh.js';
-import { K as KeyLike, e as ChordSegment, g as ChordSpan, b as Chord$1, d as ChordQuality, h as ChordSpec, i as ChordToneRole, n as ResolvedKey, k as KeyVariant, j as KeyRelation, c as ChordLike, r as SpelledKeyLike, p as SafetyQuery, E as EvaluateSafetyOptions, q as SafetyResult } from '../coerce-DP0vYu-x.js';
-export { A as Alteration, a as AlteredDegree, C as ChordBase, f as ChordSeventh, N as NoteSafety, l as PitchSpelling, m as ProfileWeights, S as SafetyPartner, o as SafetyProfile, s as SpelledKeyScale, V as VoiceSnapshot } from '../coerce-DP0vYu-x.js';
-import { j as TuningTable, i as TempoMap, g as PlayabilityReport, b as NoteEventIndexOptions, a as NoteEventIndex, d as NoteValue, k as Tuplet, D as DurationData, S as SpelledDuration } from '../index-9eoQs2C1.js';
-export { I as IndexedNoteEvent, c as NotePlacement, O as OnsetTieBreak, P as PlayabilityIssue, e as PlayabilityIssueType, f as PlayabilityLayer, h as TempoEvent } from '../index-9eoQs2C1.js';
-import { b as InstrumentProfileLike, d as PositionalRng, I as InstrumentProfile, e as StringFingering } from '../positional-DJgs6ltD.js';
-export { a as InstrumentProfileCommon, c as Limb, P as PercussionProfile, S as SeedPath, f as StringedProfile, V as ValidatedPercussionProfile, g as ValidatedProfile, h as ValidatedStringedProfile } from '../positional-DJgs6ltD.js';
-import { c as MeterMap, b as MeterLike, B as BarPosition, T as TimeSignature } from '../index-CL4b4gUQ.js';
-export { M as MeterChange } from '../index-CL4b4gUQ.js';
-import { s as ScaleNameInput, r as ScaleName } from '../masks-Cc7-MzzY.js';
-import { n as TransposingInstrument, r as VoicingOptions, h as ScaleChoice, d as ChordSymbolOptions, m as StyledVoicingOptions, C as ChordScaleMatch, c as ChordScaleReportEntry, A as AvailableTensionsOptions, b as AvoidNotesOptions, K as KeyMode, i as ScaleSystem, q as VoiceRange, P as PartWritingOptions, e as PartWritingViolation, j as Species, k as SpeciesOptions, V as VoiceIndependenceOptions, p as VoiceIndependenceReport } from '../index-BHIUyjhZ.js';
-export { a as AvoidNoteUse, f as PartWritingViolationKind, o as TransposingInstrumentName, s as VoicingStyle } from '../index-BHIUyjhZ.js';
-import { a2 as SubstitutionType, a0 as SubstituteOptions, a1 as Substitution, g as BorrowedChord, z as HumanizeOptions, L as OrnamentOptions, w as GrooveTemplate, d as BassLineOptions, C as Complexity, a4 as Vocabulary, T as ProgressionOptions, o as DrumsOptions, e as BassSegment, h as CounterMelodyOptions, H as HarmonizeOptions, p as GenerationContext, A as MotifCell, F as MotifContour, q as GenerationContextInput, I as MotifNote, K as MotifTransform, Y as RhythmEvent, Z as RhythmOptions } from '../index-BJgP97N1.js';
-export { f as BassStyle, l as DrumRole, E as EuclideanKick, r as Genre, s as GridEvent, t as GrooveFeel, u as GrooveSlot, v as GrooveStyle, x as HarmonizePlacement, M as MelodyNote, N as OrnamentStyle, Q as ProgFunction, R as ProgStyle, S as ProgressionDegree, U as ProgressionPreset, V as Provenance, W as ProvenanceBasis, $ as Section } from '../index-BJgP97N1.js';
-import '../index-Dw2DP7vm.js';
+import { D as DetectChordOptions, C as ChordMatch, g as DetectKeyOptions, K as KeyMatch, d as AugmentedSixthKind, k as PhraseOptions, P as Phrase, S as StructuralCadence, h as HypermeterOptions, H as Hypermeter, R as ReferenceProfileOptions, c as ArrangementTrack, a as ArrangementOptions, A as ArrangementAnalysis, e as Conflict, n as TrackEdit, T as TensionPoint } from '../profile-B4WqcM4H.js';
+export { b as ArrangementSession, f as ConflictPartner, j as ModalScaleName, l as PhraseSignal, m as TrackAnalysis, o as TrackRole } from '../profile-B4WqcM4H.js';
+import { r as KeyRegion, i as ChordTimelineOptions, U as ReduceProgressionOptions, V as ReducedChord, c as CadenceHit, s as KeyTimelineOptions, k as ChordToRomanOptions, h as ChordTimeline, o as HarmonicFunction, A as AnalyzeChordOptions, D as DetectCadenceOptions, f as ChordAnalysis, d as CadenceResult, E as ExplainRomanOptions, a9 as RomanExplanation, b as BorrowedSource, n as FormSectionOptions, F as FormSection, m as ExtractMotifsOptions, x as MotifData, u as MelodicContour, a5 as ReferenceProfile, a8 as RhythmAnalysisOptions, a7 as RhythmAnalysis, J as MotifGraphOptions, y as MotifGraph, a as AnalyzedNote, I as IdentifiedVoiceNote, N as MotifRelation } from '../types-7mGFwvMm.js';
+export { B as BarPositionProfile, e as CadenceType, g as ChordSegmentation, j as ChordTimelineResult, l as ContourDirection, K as KeyContext, p as KeyProfileName, q as KeyProfilePair, v as MelodicContourShape, z as MotifGraphEdge, G as MotifGraphNode, L as MotifOccurrence, O as MotifRelationKind, P as MotifRelationSummary, Q as PivotChord, W as ReductionBasis, 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, a6 as RejectedCandidate, aa as SuspensionFigure, ab as TheoryLabel, ac as VoiceNote } from '../types-7mGFwvMm.js';
+import { c as IntervalQualityLabel, I as IntervalData, P as ParseResult, S as SpelledInterval, g as Note$1, j as NoteNameOptions, b as IntervalLike, h as NoteEvent, i as NoteLike, e as KeyScale, a as Articulation } from '../index-C9MYbuKS.js';
+export { B as BudgetExceededError, d as InvalidInputError, L as LibcantusError, N as NoSolutionError, k as NoteNameSystem } from '../index-C9MYbuKS.js';
+import { K as KeyLike, e as ChordSegment, g as ChordSpan, b as Chord$1, d as ChordQuality, h as ChordSpec, i as ChordToneRole, n as ResolvedKey, k as KeyVariant, j as KeyRelation, c as ChordLike, r as SpelledKeyLike, p as SafetyQuery, E as EvaluateSafetyOptions, q as SafetyResult } from '../coerce-CUhHc3Tu.js';
+export { A as Alteration, a as AlteredDegree, C as ChordBase, f as ChordSeventh, N as NoteSafety, l as PitchSpelling, m as ProfileWeights, S as SafetyPartner, o as SafetyProfile, s as SpelledKeyScale, V as VoiceSnapshot } from '../coerce-CUhHc3Tu.js';
+import { j as TuningTable, i as TempoMap, g as PlayabilityReport, b as NoteEventIndexOptions, a as NoteEventIndex, d as NoteValue, k as Tuplet, D as DurationData, S as SpelledDuration } from '../index-Dg-SAfhz.js';
+export { I as IndexedNoteEvent, c as NotePlacement, O as OnsetTieBreak, P as PlayabilityIssue, e as PlayabilityIssueType, f as PlayabilityLayer, h as TempoEvent } from '../index-Dg-SAfhz.js';
+import { b as InstrumentProfileLike, d as PositionalRng, I as InstrumentProfile, e as StringFingering } from '../positional-DLnfUgqG.js';
+export { a as InstrumentProfileCommon, c as Limb, P as PercussionProfile, S as SeedPath, f as StringedProfile, V as ValidatedPercussionProfile, g as ValidatedProfile, h as ValidatedStringedProfile } from '../positional-DLnfUgqG.js';
+import { c as MeterMap, b as MeterLike, B as BarPosition, T as TimeSignature } from '../index-Bf0Sv8a9.js';
+export { M as MeterChange } from '../index-Bf0Sv8a9.js';
+import { s as ScaleNameInput, r as ScaleName } from '../masks-tycmkrgs.js';
+import { n as TransposingInstrument, r as VoicingOptions, h as ScaleChoice, d as ChordSymbolOptions, m as StyledVoicingOptions, C as ChordScaleMatch, c as ChordScaleReportEntry, A as AvailableTensionsOptions, b as AvoidNotesOptions, K as KeyMode, i as ScaleSystem, q as VoiceRange, P as PartWritingOptions, e as PartWritingViolation, j as Species, k as SpeciesOptions, V as VoiceIndependenceOptions, p as VoiceIndependenceReport } from '../index-BLuDesVG.js';
+export { a as AvoidNoteUse, f as PartWritingViolationKind, o as TransposingInstrumentName, s as VoicingStyle } from '../index-BLuDesVG.js';
+import { af as SubstitutionType, ad as SubstituteOptions, ae as Substitution, g as BorrowedChord, L as HumanizeOptions, U as OrnamentOptions, H as GrooveTemplate, j as CompositionPlan, u as EvaluateCompositionOptions, i as CompositionEvaluation, d as BassLineOptions, h as Complexity, ah as Vocabulary, a4 as ProgressionOptions, t as DrumsOptions, e as BassSegment, m as CounterMelodyOptions, I as HarmonizeOptions, k as CompositionPlanOptions, N as MelodyOptions, v as GenerationContext, O as MotifCell, P as MotifContour, w as GenerationContextInput, Q as MotifNote, S as MotifTransform, a9 as RhythmEvent, aa as RhythmOptions } from '../index-jgeug9EA.js';
+export { f as BassStyle, l as CompositionViolation, q as DrumRole, E as EuclideanKick, x as Genre, y as GridEvent, z as GrooveFeel, A as GrooveSlot, F as GrooveStyle, J as HarmonizePlacement, M as MelodyNote, V as OrnamentStyle, 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, a5 as ProgressionPreset, a6 as Provenance, a7 as ProvenanceBasis, ac as Section } from '../index-jgeug9EA.js';
+import '../index-C7KCaTRz.js';
 
 /**
  * An immutable spelled interval value: a diatonic number, a quality label, and
@@ -160,6 +160,9 @@ declare class Interval {
     /**
      * Whether the interval is consonant.
      *
+     * The spelling decides, not the span: a diminished fourth is a dissonance
+     * though it sounds like a major third.
+     *
      * @param twoVoice When true, the perfect fourth counts as a dissonance,
      *   matching two-voice counterpoint.
      * @returns True if the interval is consonant in that context.
@@ -609,8 +612,9 @@ declare class Timeline {
      *
      * @param data The segments and the span they cover; copied, never retained.
      * @throws If the span, a segment, or a key region carries a number it cannot
-     *   hold — a beat that is not finite, a mode mask that names no scale — or if
-     *   the confidences do not run one per segment.
+     *   hold — a beat that is not finite, a mode mask that names no scale — if
+     *   the segments or the key regions are not disjoint, in beat order and of
+     *   positive length, or if the confidences do not run one per segment.
      */
     constructor(data: TimelineData);
     /**
@@ -619,7 +623,8 @@ declare class Timeline {
      * @param spans The chords with their onsets, in any order.
      * @param totalBeats Where the last chord stops sounding.
      * @param key The key the chords are read in, when it is already known. It
-     *   becomes the one key region under the whole span; without it the timeline
+     *   becomes the one key region from the first chord to the end of the span;
+     *   without it, or without a chord for it to be in force over, the timeline
      *   carries no key, and the members that need one say so.
      * @returns The timeline.
      */
@@ -844,6 +849,12 @@ declare class Timeline {
 type ProgressionData = {
     chords: Chord$1[];
     key: KeyData | undefined;
+    /**
+     * Each chord's own key by position, null for a chord without one. Written
+     * only when the progression carries no key and some chord does; read only
+     * when `key` is absent, since a progression key reaches every chord.
+     */
+    chordKeys?: (KeyData | null)[];
 };
 /**
  * An immutable ordered sequence of chords, optionally carrying a {@link Key}
@@ -907,10 +918,12 @@ declare class Progression {
      */
     static fromSpans(spans: readonly ChordSpan[], key?: KeyLike): Progression;
     /**
-     * Rebuild a progression from its {@link Progression.toJSON} output.
+     * Rebuild a progression from its {@link Progression.toJSON} output, with the
+     * carried key or, without one, each chord's own key.
      *
-     * @param data The serialized chords and key.
+     * @param data The serialized chords and keys.
      * @returns The progression.
+     * @throws If `chordKeys` does not hold one entry per chord.
      */
     static fromJSON(data: ProgressionData): Progression;
     /**
@@ -1284,10 +1297,12 @@ declare class Progression {
     /**
      * The plain progression data, for JSON serialization.
      *
-     * Private class fields do not serialize, so this preserves both the chord
-     * data and any carried key in `JSON.stringify(progression)`.
+     * Private class fields do not serialize, so this preserves the chord data,
+     * any carried key, and — for a progression with no key of its own — each
+     * chord's own key in `JSON.stringify(progression)`.
      *
-     * @returns The chord data sequence and the carried key, if any.
+     * @returns The chord data sequence, the carried key, if any, and the
+     *   per-chord keys when they are what spells the chords.
      */
     toJSON(): ProgressionData;
 }
@@ -2225,7 +2240,7 @@ declare class Key {
     get scaleName(): ScaleName | undefined;
     /** A copy of the underlying plain key data. */
     get data(): KeyData;
-    /** The detected scale form, when this key came from key detection. */
+    /** The scale form this key stands in: natural, harmonic or melodic, read from the mask unless named. */
     get variant(): KeyVariant;
     /**
      * The scale's pitch classes.
@@ -2516,7 +2531,7 @@ declare class Key {
      *
      * Unlike {@link Key.transpose}, which picks a letter from the semitone count,
      * the interval's diatonic number decides the tonic's letter: G# minor down an
-     * augmented fourth is D minor, while down a diminished fifth it is Dbb minor.
+     * augmented fourth is D minor, while down a diminished fifth it is C## minor.
      * The mode mask is unchanged, so the scale keeps its shape.
      *
      * @param interval The interval to apply, as a name (`'A4'`, `'-A4'`), plain
@@ -2790,12 +2805,11 @@ declare class Key {
      *
      * Private class fields do not serialize, so an explicit `toJSON` keeps
      * `JSON.stringify(key)` from collapsing to `{}`. The result pairs the
-     * `KeyScale` with the spelled tonic and, for a detected harmonic or melodic
-     * minor, the scale form — everything {@link Key.fromJSON} needs to rebuild a
-     * key that reads and prints as this one.
+     * `KeyScale` with the spelled tonic and the scale form — everything
+     * {@link Key.fromJSON} needs to rebuild a key that reads and prints as this
+     * one.
      *
-     * @returns The key/scale, its spelled tonic, and its scale form when it has
-     *   one.
+     * @returns The key/scale, its spelled tonic, and its scale form.
      */
     toJSON(): KeyData;
     /**
@@ -3033,9 +3047,8 @@ declare class Score {
     /**
      * The notes pushed off the grid the way a player would.
      *
-     * The metric accents are read from the score's opening signature, since
-     * {@link HumanizeOptions} names one signature rather than a map; pass `ts`
-     * to read a later stretch of a score that changes meter.
+     * The metric accents are read against the score's meter map, exactly as
+     * {@link humanize} reads that map; pass `ts` to read against another meter.
      *
      * @param opts Jitter amounts, accent depth and the seed; see
      *   {@link HumanizeOptions}.
@@ -3045,8 +3058,8 @@ declare class Score {
     /**
      * The notes with ornaments added.
      *
-     * Strong positions are read from the score's opening signature, since
-     * {@link OrnamentOptions} names one signature rather than a map.
+     * Strong positions are read against the score's meter map, exactly as
+     * {@link ornament} reads that map.
      *
      * @param opts The ornament style, how much is decorated, and the seed; see
      *   {@link OrnamentOptions}.
@@ -3056,9 +3069,9 @@ declare class Score {
     /**
      * The notes placed on a groove template's slots.
      *
-     * The template's per-bar grid is laid out against the score's opening
-     * signature, which is the signature the template must have been extracted
-     * under; a template carrying a different one is refused rather than drifting.
+     * The template's per-bar grid is laid out against the score's meter map,
+     * exactly as {@link applyGrooveTemplate} reads that map; a template extracted
+     * under another meter is refused rather than drifting.
      *
      * @param template The groove template, from `extractGrooveTemplate`.
      * @returns The score with the template's feel imposed.
@@ -3072,8 +3085,8 @@ declare class Score {
      * slot by slot for how far ahead of or behind the grid it sits and how hard
      * it is struck, and the reading is handed back as a template. Only the
      * subdivision is named, because the score already holds the meter the grid is
-     * laid out against — its opening signature, which is the one the template
-     * records and the one an apply-time meter is checked against.
+     * laid out against — its meter map, read exactly as
+     * {@link extractGrooveTemplate} reads that map.
      *
      * @param subdivision Grid steps per quarter-note beat; a sixteenth-note grid
      *   by default, which is where swing, push and drag are audible.
@@ -3202,8 +3215,9 @@ declare class Score {
      *
      * A melody is one line, so a score holding several is read as its top voice:
      * notes struck together are one event and the highest of them stands for it.
-     * A piano part read whole therefore answers for the voice a listener follows
-     * rather than for a line assembled from the insides of its chords. Split the
+     * A block-chord part read whole therefore answers for its top voice rather
+     * than for a line assembled from the insides of its chords; a lower note
+     * struck while a higher one still sounds stays in the line, though. Split the
      * score into lines first to have each of them answered for.
      *
      * @param opts Cell-length bounds and the recurrence threshold; see
@@ -3236,6 +3250,113 @@ declare class Score {
      * answered for; {@link Score.voices} is what reads the polyphony as polyphony.
      */
     contour(): MelodicContour;
+    /**
+     * The score's structural fingerprint: form, phrase shape, harmonic function
+     * and rhythm, and how its motifs derive from one another.
+     *
+     * The harmony is the score's own kept chord analysis, read once whether this
+     * is asked before or after {@link Score.timeline} — unless `opts.timeline`
+     * gives the harmony directly, in which case the reading runs fresh through
+     * {@link analyzeReference} rather than the harmony this score already holds.
+     * The meter, the key and the span are the score's own and are not on offer
+     * here: a caller wanting another meter reads through {@link
+     * Score.withMeters}, and one wanting another key or span calls {@link
+     * analyzeReference} directly.
+     *
+     * Asked with no options, the answer is kept and a copy of it handed back, as
+     * {@link Score.timeline} keeps its own reading; asked with options, the
+     * answer is read afresh and not kept.
+     *
+     * @param opts The harmony, the melody, and the budget; see {@link
+     *   ReferenceProfileOptions}. Meter, key and span are the score's own.
+     * @returns The profile.
+     * @example
+     * ```ts
+     * import { Score } from '@libraz/libcantus';
+     * const triad = (pitches: number[], startBeat: number) =>
+     *   pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
+     * const score = Score.of(
+     *   [
+     *     ...triad([60, 64, 67], 0),
+     *     ...triad([65, 69, 72], 4),
+     *     ...triad([67, 71, 74], 8),
+     *     ...triad([60, 64, 67], 12),
+     *   ],
+     *   { key: 'C major' },
+     * );
+     * score.reference().harmony.chords.map((chord) => chord.roman); // ['I', 'IV', 'V', 'I']
+     * ```
+     */
+    reference(opts?: Omit<ReferenceProfileOptions, 'ts' | 'meters' | 'key' | 'totalBeats'>): ReferenceProfile;
+    /**
+     * The onset placement of the score's melodic line.
+     *
+     * A melody is one line, so a score holding several is read as its top voice,
+     * as {@link Score.motifs} and {@link Score.contour} are.
+     *
+     * @param opts The span's end and the budget; see {@link
+     *   RhythmAnalysisOptions}. The meter is the score's own.
+     * @returns The rhythm reading.
+     * @example
+     * ```ts
+     * import { Score } from '@libraz/libcantus';
+     * const score = Score.of([
+     *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+     *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+     *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+     *   { pitch: 65, startBeat: 3, durationBeat: 1 },
+     * ]);
+     * score.rhythm().onsetDensity; // 4
+     * ```
+     */
+    rhythm(opts?: Omit<RhythmAnalysisOptions, 'ts' | 'meters'>): RhythmAnalysis;
+    /**
+     * How the score's motifs derive from one another: which statement grew out
+     * of which, and by what transformation.
+     *
+     * {@link Score.motifs} finds the cells; this reads across their occurrences
+     * and names, for every statement after the first, the earlier one it most
+     * plausibly grew out of. A melody is one line, so a score holding several is
+     * read as its top voice, as {@link Score.motifs} is.
+     *
+     * @param opts Cell-length bounds and the recurrence threshold {@link
+     *   Score.motifs} takes, plus the variation threshold and the budget; see
+     *   {@link MotifGraphOptions} and {@link ExtractMotifsOptions}.
+     * @returns The derivation forest.
+     * @example
+     * ```ts
+     * import { Score } from '@libraz/libcantus';
+     * const score = Score.of([
+     *   { pitch: 60, startBeat: 0, durationBeat: 1 },
+     *   { pitch: 62, startBeat: 1, durationBeat: 1 },
+     *   { pitch: 64, startBeat: 2, durationBeat: 1 },
+     *   { pitch: 60, startBeat: 3, durationBeat: 1 },
+     *   { pitch: 62, startBeat: 4, durationBeat: 1 },
+     *   { pitch: 64, startBeat: 5, durationBeat: 1 },
+     * ]);
+     * score.motifGraph().edges.length; // 1
+     * ```
+     */
+    motifGraph(opts?: MotifGraphOptions & ExtractMotifsOptions): MotifGraph;
+    /**
+     * How this score, read as a melody, keeps to a composition plan.
+     *
+     * @param plan The plan the melody was written for.
+     * @param opts The budget; see {@link EvaluateCompositionOptions}.
+     * @returns The violations found and the fit reading; see {@link
+     *   evaluateComposition}.
+     * @example
+     * ```ts
+     * import { Composer, Score } from '@libraz/libcantus';
+     * const notes = [60, 62, 64, 65, 67, 65, 64, 62, 60, 62, 64, 65, 67, 65, 64, 60].map(
+     *   (pitch, startBeat) => ({ pitch, startBeat, durationBeat: 1 }),
+     * );
+     * const composer = Composer.of({ key: 'C major', seed: 5 });
+     * const plan = composer.plan(Score.of(notes, { key: 'C major' }).reference());
+     * composer.melody(plan).evaluate(plan).violations.some((v) => v.severity === 'error'); // false
+     * ```
+     */
+    evaluate(plan: CompositionPlan, opts?: EvaluateCompositionOptions): CompositionEvaluation;
     /**
      * Each note's role in the harmony sounding under it.
      *
@@ -3577,6 +3698,47 @@ declare class Arrangement {
      *   found under it.
      */
     timeline(): Timeline;
+    /**
+     * The arrangement's structural fingerprint: form, phrase shape, harmonic
+     * function and rhythm, and how its melody's motifs derive from one another.
+     *
+     * The harmony reads the arrangement's own session analysis directly — the
+     * tracks `settings.harmonyTracks` names, or else every track but the
+     * percussion ones — so the harmony is never inferred a second time. The
+     * melody is the notes of the tracks played with `role: 'melody'`, joined in
+     * the order the tracks were given; an arrangement naming none reads the top
+     * line of the harmony notes instead, as {@link analyzeReference} does
+     * without a `melody` option. Meter, key, harmony and melody are the
+     * arrangement's own and are not on offer here: a caller wanting others calls
+     * {@link analyzeReference} directly, with the same notes {@link
+     * Arrangement.tracks} hands out.
+     *
+     * @param opts The budget; see {@link ReferenceProfileOptions}.
+     * @returns The profile.
+     * @example
+     * ```ts
+     * import { Arrangement } from '@libraz/libcantus';
+     * const triad = (pitches: number[], startBeat: number) =>
+     *   pitches.map((pitch) => ({ pitch, startBeat, durationBeat: 4 }));
+     * const arrangement = Arrangement.of(
+     *   [
+     *     {
+     *       name: 'lead',
+     *       role: 'melody',
+     *       notes: [
+     *         ...triad([60, 64, 67], 0),
+     *         ...triad([65, 69, 72], 4),
+     *         ...triad([67, 71, 74], 8),
+     *         ...triad([60, 64, 67], 12),
+     *       ],
+     *     },
+     *   ],
+     *   { key: 'C major' },
+     * );
+     * arrangement.reference().harmony.chords.map((chord) => chord.roman); // ['I', 'IV', 'V', 'I']
+     * ```
+     */
+    reference(opts?: Omit<ReferenceProfileOptions, 'ts' | 'meters' | 'key' | 'melody' | 'timeline' | 'totalBeats'>): ReferenceProfile;
     /**
      * Whether another arrangement holds the same tracks under the same settings.
      *
@@ -3844,6 +4006,54 @@ declare class Composer {
      * ```
      */
     harmonize(melody: Score, opts?: Omit<HarmonizeOptions, 'melody' | 'key' | 'ts' | 'ctx'>): HarmonizedMelody;
+    /**
+     * A composition plan derived from a reference profile.
+     *
+     * The composer's key is the plan's home key unless `opts.key` names another,
+     * and its seed and algorithm version are the ones the plan records, so the
+     * plan is written under the same recipe as the composer's other parts.
+     *
+     * @param reference The reference profile to derive from.
+     * @param opts Everything {@link deriveCompositionPlan} takes but the context,
+     *   which is the composer's.
+     * @returns The plan.
+     * @throws If the composer draws from a caller-held `rng`: a plan records its
+     *   seed, and a source cannot be written into it.
+     * @example
+     * ```ts
+     * import { Composer, Score } from '@libraz/libcantus';
+     * const notes = [60, 62, 64, 65, 67, 65, 64, 62, 60, 62, 64, 65, 67, 65, 64, 60].map(
+     *   (pitch, startBeat) => ({ pitch, startBeat, durationBeat: 1 }),
+     * );
+     * const reference = Score.of(notes, { key: 'C major' }).reference();
+     * const plan = Composer.of({ key: 'D major', seed: 5 }).plan(reference);
+     * plan.seed; // 5
+     * plan.keys[0].scale.rootPc; // 2
+     * ```
+     */
+    plan(reference: ReferenceProfile, opts?: Omit<CompositionPlanOptions, 'ctx'>): CompositionPlan;
+    /**
+     * A melody written to a composition plan.
+     *
+     * The plan is the reproduction recipe, so its seed and algorithm version are
+     * the ones the melody is drawn under, not the composer's. The score is read
+     * in the plan's meter and home key, at the composer's tempo.
+     *
+     * @param plan The plan to follow.
+     * @param opts The budget; see {@link MelodyOptions}.
+     * @returns The melody, as a score.
+     * @example
+     * ```ts
+     * import { Composer, Score } from '@libraz/libcantus';
+     * const notes = [60, 62, 64, 65, 67, 65, 64, 62, 60, 62, 64, 65, 67, 65, 64, 60].map(
+     *   (pitch, startBeat) => ({ pitch, startBeat, durationBeat: 1 }),
+     * );
+     * const composer = Composer.of({ key: 'C major', seed: 5 });
+     * const plan = composer.plan(Score.of(notes, { key: 'C major' }).reference());
+     * composer.melody(plan).notes.length > 0; // true
+     * ```
+     */
+    melody(plan: CompositionPlan, opts?: Omit<MelodyOptions, 'ctx'>): Score;
     /**
      * Whether another composer holds the same settings.
      *
@@ -5750,4 +5960,5 @@ declare class Voicing {
     toString(): string;
 }
 
-export { AnalyzeChordOptions, AnalyzedNote, Arrangement, ArrangementAnalysis, type ArrangementData, ArrangementOptions, type ArrangementSettings, type ArrangementSetup, type ArrangementTensionOptions, ArrangementTrack, Articulation, AugmentedSixthKind, AvailableTensionsOptions, AvoidNotesOptions, BarPosition, BassLineOptions, type BassLineSettings, BassSegment, BorrowedChord, BorrowedSource, CadenceHit, CadenceResult, Chord, ChordAnalysis, Chord$1 as ChordData, ChordLike, ChordMatch, ChordQuality, ChordScaleMatch, ChordScaleReportEntry, ChordSegment, ChordSpan, ChordSpec, ChordSymbolOptions, ChordTimeline, ChordTimelineOptions, ChordToRomanOptions, ChordToneRole, Complexity, Composer, type ComposerOptions, Conflict, CounterMelodyOptions, type CounterMelodySettings, DetectCadenceOptions, DetectChordOptions, DetectKeyOptions, type DetectedKeyMatch, DrumsOptions, Duration, DurationData, EvaluateSafetyOptions, ExplainRomanOptions, ExtractMotifsOptions, FormSection, FormSectionOptions, GenerationContext, GenerationContextInput, GrooveTemplate, HarmonicFunction, HarmonizeOptions, type HarmonizedMelody, HumanizeOptions, Hypermeter, HypermeterOptions, IdentifiedVoiceNote, Instrument, InstrumentProfile, InstrumentProfileLike, Interval, IntervalData, IntervalLike, IntervalQualityLabel, Key, type KeyData, KeyLike, KeyMatch, KeyMode, KeyRegion, KeyRelation, KeyScale, KeyTimelineOptions, KeyVariant, MelodicContour, Meter, MeterLike, MeterMap, Motif, MotifCell, MotifContour, MotifData, type MotifGenerateOptions, MotifNote, MotifRelation, MotifTransform, Note, Note$1 as NoteData, NoteEvent, NoteEventIndex, NoteEventIndexOptions, NoteLike, NoteNameOptions, NoteValue, OrnamentOptions, ParseResult, PartWritingOptions, PartWritingViolation, Phrase, PhraseOptions, PlayabilityReport, PositionalRng, Progression, type ProgressionData, ProgressionOptions, ReduceProgressionOptions, ReducedChord, ResolvedKey, Rhythm, type RhythmData, type RhythmDeformOptions, RhythmEvent, RhythmOptions, RomanExplanation, SafetyQuery, SafetyResult, ScaleChoice, ScaleName, ScaleNameInput, ScaleSystem, Score, type ScoreData, type ScoreOptions, Species, SpeciesOptions, SpelledDuration, SpelledInterval, SpelledKeyLike, StringFingering, StructuralCadence, StyledVoicingOptions, SubstituteOptions, Substitution, SubstitutionType, Tempo, type TempoData, TempoMap, TensionPoint, TimeSignature, Timeline, type TimelineData, type TimelineRoman, TrackEdit, TransposingInstrument, Tuning, TuningTable, Tuplet, Vocabulary, VoiceIndependenceOptions, VoiceIndependenceReport, VoiceRange, Voicing, type VoicingData, type VoicingIndependenceOptions, VoicingOptions, type VoicingSafetyQuery };
+export { AnalyzeChordOptions, AnalyzedNote, Arrangement, ArrangementAnalysis, ArrangementOptions, ArrangementTrack, Articulation, AugmentedSixthKind, AvailableTensionsOptions, AvoidNotesOptions, BarPosition, BassLineOptions, BassSegment, BorrowedChord, BorrowedSource, CadenceHit, CadenceResult, Chord, ChordAnalysis, Chord$1 as ChordData, ChordLike, ChordMatch, ChordQuality, ChordScaleMatch, ChordScaleReportEntry, ChordSegment, ChordSpan, ChordSpec, ChordSymbolOptions, ChordTimeline, ChordTimelineOptions, ChordToRomanOptions, ChordToneRole, Complexity, Composer, CompositionEvaluation, CompositionPlan, CompositionPlanOptions, Conflict, CounterMelodyOptions, DetectCadenceOptions, DetectChordOptions, DetectKeyOptions, DrumsOptions, Duration, DurationData, EvaluateCompositionOptions, EvaluateSafetyOptions, ExplainRomanOptions, ExtractMotifsOptions, FormSection, FormSectionOptions, GenerationContext, GenerationContextInput, GrooveTemplate, HarmonicFunction, HarmonizeOptions, HumanizeOptions, Hypermeter, HypermeterOptions, IdentifiedVoiceNote, Instrument, InstrumentProfile, InstrumentProfileLike, Interval, IntervalData, IntervalLike, IntervalQualityLabel, Key, KeyLike, KeyMatch, KeyMode, KeyRegion, KeyRelation, KeyScale, KeyTimelineOptions, KeyVariant, MelodicContour, MelodyOptions, Meter, MeterLike, MeterMap, Motif, MotifCell, MotifContour, MotifData, MotifGraph, MotifGraphOptions, MotifNote, MotifRelation, MotifTransform, Note, Note$1 as NoteData, NoteEvent, NoteEventIndex, NoteEventIndexOptions, NoteLike, NoteNameOptions, NoteValue, OrnamentOptions, ParseResult, PartWritingOptions, PartWritingViolation, Phrase, PhraseOptions, PlayabilityReport, PositionalRng, Progression, ProgressionOptions, ReduceProgressionOptions, ReducedChord, ReferenceProfile, ReferenceProfileOptions, ResolvedKey, Rhythm, RhythmAnalysis, RhythmAnalysisOptions, RhythmEvent, RhythmOptions, RomanExplanation, SafetyQuery, SafetyResult, ScaleChoice, ScaleName, ScaleNameInput, ScaleSystem, Score, Species, SpeciesOptions, SpelledDuration, SpelledInterval, SpelledKeyLike, StringFingering, StructuralCadence, StyledVoicingOptions, SubstituteOptions, Substitution, SubstitutionType, Tempo, TempoMap, TensionPoint, TimeSignature, Timeline, TrackEdit, TransposingInstrument, Tuning, TuningTable, Tuplet, Vocabulary, VoiceIndependenceOptions, VoiceIndependenceReport, VoiceRange, Voicing, VoicingOptions };
+export type { ArrangementData, ArrangementSettings, ArrangementSetup, ArrangementTensionOptions, BassLineSettings, ComposerOptions, CounterMelodySettings, DetectedKeyMatch, HarmonizedMelody, KeyData, MotifGenerateOptions, ProgressionData, RhythmData, RhythmDeformOptions, ScoreData, ScoreOptions, TempoData, TimelineData, TimelineRoman, VoicingData, VoicingIndependenceOptions, VoicingSafetyQuery };

package/dist/model/index.js

@@ -16,23 +16,23 @@ import {
   Timeline,
   Tuning,
   Voicing
-} from "../chunk-FBH75DAY.js";
-import "../chunk-HYJJ2V2I.js";
-import "../chunk-UMWZ4ZET.js";
-import "../chunk-Q6LFSAKV.js";
-import "../chunk-H2KJHBW4.js";
-import "../chunk-7KG3RTYS.js";
-import "../chunk-PUKJP2Z5.js";
-import "../chunk-M5RYMAFI.js";
-import "../chunk-NB25P3EH.js";
+} from "../chunk-5MWRBYAT.js";
+import "../chunk-UTE5A36R.js";
+import "../chunk-7NQ6AL3H.js";
+import "../chunk-FK3DGAIZ.js";
+import "../chunk-FJFULJZE.js";
+import "../chunk-VL5NXVCN.js";
+import "../chunk-TXFWSU5D.js";
+import "../chunk-ZLNSH4UL.js";
+import "../chunk-2G5MCGYU.js";
 import {
   NoteSafety
-} from "../chunk-RFIBF2RR.js";
+} from "../chunk-H7FVMBUC.js";
 import {
   BudgetExceededError,
   InvalidInputError,
   NoSolutionError
-} from "../chunk-AGOVW7U6.js";
+} from "../chunk-YYVXRV3V.js";
 export {
   Arrangement,
   BudgetExceededError,

package/dist/{positional-DJgs6ltD.d.ts → positional-CscpxtlE.d.cts}

@@ -1,4 +1,4 @@
-import { a as Articulation } from './index-Cy15oTvh.js';
+import { a as Articulation } from './index-C9MYbuKS.cjs';
 
 /**
  * Every limb a percussionist strikes with, in declaration order.
@@ -361,4 +361,5 @@ declare function createPositionalRng(seed: number): PositionalRng;
  */
 declare function includeAt(rng: PositionalRng, complexity: number, ...path: SeedPath): boolean;
 
-export { type InstrumentProfile as I, LIMBS as L, type PercussionProfile as P, type SeedPath as S, type ValidatedPercussionProfile as V, type InstrumentProfileCommon as a, type InstrumentProfileLike as b, type Limb as c, type PositionalRng as d, type StringFingering as e, type StringedProfile as f, type ValidatedProfile as g, type ValidatedStringedProfile as h, canSound as i, createPositionalRng as j, deriveSeed as k, fingeringsFor as l, foldIntoRange as m, includeAt as n, instrumentRange as o, toStringedProfile as p, toInstrumentProfile as t };
+export { LIMBS as L, canSound as i, createPositionalRng as j, deriveSeed as k, fingeringsFor as l, foldIntoRange as m, includeAt as n, instrumentRange as o, toStringedProfile as p, toInstrumentProfile as t };
+export type { InstrumentProfile as I, PercussionProfile as P, SeedPath as S, ValidatedPercussionProfile as V, InstrumentProfileCommon as a, InstrumentProfileLike as b, Limb as c, PositionalRng as d, StringFingering as e, StringedProfile as f, ValidatedProfile as g, ValidatedStringedProfile as h };

package/dist/{positional-DMZer-FM.d.cts → positional-DLnfUgqG.d.ts}

@@ -1,4 +1,4 @@
-import { a as Articulation } from './index-Cy15oTvh.cjs';
+import { a as Articulation } from './index-C9MYbuKS.js';
 
 /**
  * Every limb a percussionist strikes with, in declaration order.
@@ -361,4 +361,5 @@ declare function createPositionalRng(seed: number): PositionalRng;
  */
 declare function includeAt(rng: PositionalRng, complexity: number, ...path: SeedPath): boolean;
 
-export { type InstrumentProfile as I, LIMBS as L, type PercussionProfile as P, type SeedPath as S, type ValidatedPercussionProfile as V, type InstrumentProfileCommon as a, type InstrumentProfileLike as b, type Limb as c, type PositionalRng as d, type StringFingering as e, type StringedProfile as f, type ValidatedProfile as g, type ValidatedStringedProfile as h, canSound as i, createPositionalRng as j, deriveSeed as k, fingeringsFor as l, foldIntoRange as m, includeAt as n, instrumentRange as o, toStringedProfile as p, toInstrumentProfile as t };
+export { LIMBS as L, canSound as i, createPositionalRng as j, deriveSeed as k, fingeringsFor as l, foldIntoRange as m, includeAt as n, instrumentRange as o, toStringedProfile as p, toInstrumentProfile as t };
+export type { InstrumentProfile as I, PercussionProfile as P, SeedPath as S, ValidatedPercussionProfile as V, InstrumentProfileCommon as a, InstrumentProfileLike as b, Limb as c, PositionalRng as d, StringFingering as e, StringedProfile as f, ValidatedProfile as g, ValidatedStringedProfile as h };