@libraz/libcantus 1.0.1 → 1.2.0

package/dist/{chunk-PKFNUHDY.js → chunk-FBH75DAY.js}

@@ -1,26 +1,20 @@
 import {
   analyzeArrangement,
-  analyzeVoice,
-  chordTimelineFromChords,
-  chordTimelineFromNotes,
+  analyzePolyphony,
   createArrangementSession,
-  detectCadences,
   extractMotifs,
   hypermeter,
-  keyLookup,
-  keyTimelineFromNotes,
   melodicContour,
   melodicSimilarity,
   motifFromNotes,
   phrasesFromTimeline,
-  prevailingKeyOf,
   reduceProgression,
   relateMotifs,
   sectionsFromNotes,
   structuralCadences,
   tensionCurveFrom,
-  toVoiceNotes
-} from "./chunk-2LCPM3EG.js";
+  trackRoleOf
+} from "./chunk-HYJJ2V2I.js";
 import {
   TWELVE_TET,
   beatsToDuration,
@@ -42,11 +36,13 @@ import {
   stepOf,
   stepsOfCents,
   tempoAt,
+  tempoReader,
   ticksToBeats
-} from "./chunk-YH3BIKHH.js";
+} from "./chunk-UMWZ4ZET.js";
 import {
   STEP_BEATS,
   applyGrooveTemplate,
+  cellSpan,
   deform,
   developMotif,
   doubleTime,
@@ -73,67 +69,58 @@ import {
   thin,
   transformMotif,
   withinCeiling
-} from "./chunk-VOHZB45S.js";
+} from "./chunk-Q6LFSAKV.js";
 import {
   analyzeChord,
+  augmentedSixthChord,
   borrowedSource,
+  chordAtBeat,
+  chordTimelineFromChords,
+  chordTimelineFromNotes,
   chordToRoman,
   detectCadence,
+  detectCadences,
   detectChord,
   detectChordBest,
   detectKey,
   detectKeyBest,
   detectKeyFromNotes,
+  detectModulations,
   explainRoman,
   functionOf,
   isBorrowedChord,
   isMinorKey,
+  keyLookup,
+  keyTimelineFromNotes,
+  pivotChords,
+  prevailingKeyOf,
   romanToChord,
-  secondaryDominantOf
-} from "./chunk-H42UHPYW.js";
+  secondaryDominantOf,
+  toVoiceNotes
+} from "./chunk-H2KJHBW4.js";
 import {
   BASS_4_STRING,
   BASS_5_STRING,
   GUITAR_DROP_D,
   GUITAR_STANDARD,
-  canSound,
-  fingeringsFor,
-  foldIntoRange,
-  instrumentRange,
+  fingeringsIn,
+  foldIn,
   playability,
+  rangeIn,
+  soundsIn,
   toInstrumentProfile,
   toStringedProfile
-} from "./chunk-FVSI36UV.js";
+} from "./chunk-7KG3RTYS.js";
 import {
-  beatToBarPosition,
-  beatsPerBar,
-  createNoteEventIndex,
-  formatBarPosition,
-  formatTimeSignature,
-  isCompound,
-  isStrongBeat,
-  meterAt,
-  metricWeight,
-  parseTimeSignature,
-  pulseBeats,
-  pulsesPerBar,
-  resolveMeters,
-  toMeterData,
-  tryParseTimeSignature,
-  tuplet
-} from "./chunk-ELCTZUJJ.js";
+  createNoteEventIndex
+} from "./chunk-PUKJP2Z5.js";
 import {
   SATB_RANGES,
-  availableTensions,
-  avoidNotes,
   checkPartWriting,
   checkSpecies,
-  chordScaleReport,
-  chordScales,
   figuredBassOf,
   nextVoicing,
   realizeFiguredBass,
-  scalesForChanges,
   spellVoicing,
   toSoundingPitch,
   toWrittenPitch,
@@ -141,9 +128,18 @@ import {
   voiceChordStyled,
   voiceLeadingCost,
   voiceProgression
-} from "./chunk-H3VORETI.js";
+} from "./chunk-M5RYMAFI.js";
+import {
+  availableTensions,
+  avoidNotes,
+  chordScaleReport,
+  chordScales,
+  scalesForChanges
+} from "./chunk-NB25P3EH.js";
 import {
   NAMED_SCALES,
+  assertChordQuality,
+  assertKeyVariant,
   chordFromDegree,
   chordFromSpan,
   chordPitchClasses,
@@ -160,7 +156,7 @@ import {
   formatChordSymbol,
   isChordMember,
   isScaleTone,
-  isSignatureKey,
+  isWrittenTonic,
   keyFromFifths,
   keyRelationBetween,
   keySignatureFifths,
@@ -172,7 +168,10 @@ import {
   pitchToScaleDegree,
   relatedKeysOf,
   relativeKeyOf,
+  resolveKey,
   scaleByName,
+  scaleNameOfMask,
+  scaleOf,
   scaleSystemOf,
   scaleTonesInDegreeOrder,
   spanFromChord,
@@ -182,43 +181,61 @@ import {
   spellPitchClass,
   spellPitchClasses,
   spellScale,
-  spelledKeyOf,
   subdominantKeyOf,
   supportsFunctionalHarmony,
   toChordData,
   toKeyScale,
   transposeChord,
+  transposeChordSpellings,
   tryParseChordSymbol,
+  tryResolveKeyName,
+  variantOfMask,
   voiceIndependence
-} from "./chunk-INHVXP6Z.js";
+} from "./chunk-RFIBF2RR.js";
 import {
   InvalidInputError,
+  MAX_NAME_ACCIDENTALS,
   assertFiniteNumber,
   assertInteger,
   assertMidiPitch,
-  assertNoteEvent,
+  assertNoteEvents,
   assertOneOf,
   assertPositiveInt,
   assertRange,
   assertTimeSignature,
+  beatToBarPosition,
+  beatsPerBar,
+  describeRejected,
+  formatBarPosition,
   formatKeyName,
   formatNote,
+  formatTimeSignature,
   intervalSemitones,
+  isCompound,
   isConsonantInterval,
+  isStrongBeat,
+  meterAt,
+  metricWeight,
   midiToNote,
   noteToMidi,
   noteToPitchClass,
+  parseTimeSignature,
   pitchClassOf,
+  pulseBeats,
+  pulsesPerBar,
+  resolveMeters,
   spelledInterval,
+  toMeterData,
   toNoteData,
   toSpelledInterval,
   transposeByInterval,
   transposeNote,
   tryParseInterval,
-  tryParseKeyName,
   tryParseNote,
+  tryParseTimeSignature,
+  tuplet,
   unwrapParse
-} from "./chunk-VTI6FOLB.js";
+} from "./chunk-AGOVW7U6.js";
 
 // src/model/interval.ts
 var INVERSION_SUM = 9;
@@ -288,12 +305,7 @@ var Interval = class _Interval {
    */
   static fromData(data) {
     const checked = toSpelledInterval(data);
-    return new _Interval(
-      checked.number,
-      checked.quality,
-      checked.semitones,
-      checked.descending ?? false
-    );
+    return new _Interval(checked.number, checked.quality, checked.semitones, checked.descending);
   }
   /**
    * Rebuild an interval from its {@link Interval.toJSON} output.
@@ -357,9 +369,16 @@ var Interval = class _Interval {
   get isDescending() {
     return this.#descending;
   }
-  /** A readable label composed of quality and number, e.g. `'P5'` or `'M3'`. */
+  /**
+   * A readable label composed of quality and number, e.g. `'P5'` or `'M3'`,
+   * prefixed with `'-'` when the interval descends.
+   *
+   * The name is written in the grammar {@link Interval.parse} reads, so an
+   * interval that has been logged, written to a column, or interpolated into a
+   * template comes back as the same interval — direction included.
+   */
   get name() {
-    return `${this.#quality}${this.#number}`;
+    return `${this.#descending ? "-" : ""}${this.#quality}${this.#number}`;
   }
   /** A copy of the underlying plain interval data. */
   get data() {
@@ -397,7 +416,7 @@ var Interval = class _Interval {
    * @example
    * ```ts
    * import { Interval } from '@libraz/libcantus';
-   * Interval.parse('M3').negate().toString(); // 'M3', descending
+   * Interval.parse('M3').negate().toString(); // '-M3'
    * ```
    */
   negate() {
@@ -435,34 +454,168 @@ var Interval = class _Interval {
    *
    * Private class fields do not serialize, so an explicit `toJSON` keeps
    * `JSON.stringify(interval)` from collapsing to `{}`. The result is the
-   * canonical shape the pitch module produces: `descending` appears only on an
-   * interval that descends, so a measured interval, a parsed name, and this
-   * method all serialize to the same object.
+   * canonical shape the pitch module produces: `descending` is always there, so
+   * a measured interval, a parsed name, and this method all serialize to the
+   * same object and none of them leaves the direction to be guessed.
    *
-   * @returns The diatonic number, quality, and semitone span, with
-   *   `descending` when the interval descends.
+   * @returns The diatonic number, quality, and semitone span, with `descending`
+   *   telling which way the interval goes.
    */
   toJSON() {
-    return this.#descending ? {
+    return {
       number: this.#number,
       quality: this.#quality,
       semitones: this.#semitones,
-      descending: true
-    } : { number: this.#number, quality: this.#quality, semitones: this.#semitones };
+      descending: this.#descending
+    };
   }
   /**
    * The interval's name, so a template literal or a log line reads as the
    * interval.
    *
-   * @returns The name, e.g. `'M3'`.
+   * @returns The name, e.g. `'M3'` or `'-M3'` for the same third taken
+   *   downward.
    */
   toString() {
     return this.name;
   }
 };
 
+// src/model/shared.ts
+var STATED_KEY_CONFIDENCE = 1;
+function describeShape(value) {
+  if (value === null) {
+    return "null";
+  }
+  return Array.isArray(value) ? "an array" : typeof value;
+}
+function assertDataObject(value, name) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new InvalidInputError(`${name} must be an object; received ${describeShape(value)}`);
+  }
+  return value;
+}
+function assertDataArray(value, name) {
+  if (!Array.isArray(value)) {
+    throw new InvalidInputError(`${name} must be an array; received ${describeShape(value)}`);
+  }
+  return value;
+}
+function assertDataObjects(value, name) {
+  const items = assertDataArray(value, name);
+  for (let index = 0; index < items.length; index += 1) {
+    assertDataObject(items[index], `${name}[${index}]`);
+  }
+  return items;
+}
+function assertNoteEventArray(notes, name, options) {
+  return assertNoteEvents(assertDataArray(notes, name), name, options);
+}
+function assertKeyArgument(value, name) {
+  if (value === void 0 || typeof value === "string" || isKeyShaped(value)) {
+    return;
+  }
+  const received = value === null ? "null" : typeof value === "object" ? "an object" : `a ${typeof value}`;
+  throw new InvalidInputError(
+    `${name} must be a Key; received ${received}. A method that also takes options takes them after the key, not in its place`
+  );
+}
+function isKeyShaped(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return "scale" in value || "toJSON" in value || "rootPc" in value && "modeMask12" in value;
+}
+function withoutNegativeZero(value) {
+  return value === 0 ? 0 : value;
+}
+function spanEnd(...runs) {
+  let end = 0;
+  for (const run of runs) {
+    for (const span of run) {
+      end = Math.max(end, span.endBeat);
+    }
+  }
+  return end;
+}
+function copyNoteEvent(note) {
+  const copy = {
+    pitch: withoutNegativeZero(note.pitch),
+    startBeat: withoutNegativeZero(note.startBeat),
+    durationBeat: withoutNegativeZero(note.durationBeat)
+  };
+  if (note.velocity !== void 0) {
+    copy.velocity = withoutNegativeZero(note.velocity);
+  }
+  if (note.articulation !== void 0) {
+    copy.articulation = note.articulation;
+  }
+  return copy;
+}
+function copyTimeSignature(ts, name) {
+  assertDataObject(ts, name ?? "time signature");
+  assertTimeSignature(ts, name);
+  const copy = { numerator: ts.numerator, denominator: ts.denominator };
+  if (ts.grouping !== void 0) {
+    copy.grouping = [...ts.grouping];
+  }
+  return copy;
+}
+var MAX_PLAIN_DEPTH = 64;
+function copyPlain(value, name) {
+  return copyPlainAt(value, name, /* @__PURE__ */ new WeakSet(), 0);
+}
+function copyPlainAt(value, name, seen, depth) {
+  if (typeof value === "number") {
+    return assertFiniteNumber(value, name);
+  }
+  if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+    throw new InvalidInputError(`${name} must be plain data; received ${typeof value}`);
+  }
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  if (seen.has(value)) {
+    throw new InvalidInputError(`${name} must be plain data; received a value referring to itself`);
+  }
+  if (depth >= MAX_PLAIN_DEPTH) {
+    throw new InvalidInputError(
+      `${name} must be plain data; received a value nested more than ${MAX_PLAIN_DEPTH} levels deep`
+    );
+  }
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map(
+        (item, index) => copyPlainAt(item, `${name}[${index}]`, seen, depth + 1)
+      );
+    }
+    const copy = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (item !== void 0) {
+        copy[key] = copyPlainAt(item, `${name}.${key}`, seen, depth + 1);
+      }
+    }
+    return copy;
+  } finally {
+    seen.delete(value);
+  }
+}
+function samePlain(value, other) {
+  if (Array.isArray(value) || Array.isArray(other)) {
+    return Array.isArray(value) && Array.isArray(other) && value.length === other.length && value.every((item, index) => samePlain(item, other[index]));
+  }
+  if (typeof value === "object" && value !== null && typeof other === "object" && other !== null) {
+    const mine = Object.entries(value);
+    const theirs = other;
+    return mine.length === Object.keys(theirs).length && mine.every(([key, item]) => key in theirs && samePlain(item, theirs[key]));
+  }
+  return value === other;
+}
+
 // src/model/note.ts
 function copyNote(data) {
+  assertDataObject(data, "note data");
   if (!Number.isInteger(data.letter) || data.letter < 0 || data.letter > 6) {
     throw new InvalidInputError(
       `note letter must be an integer in [0, 6]; received ${data.letter}`
@@ -482,13 +635,17 @@ function letterNumberOf(letter) {
   }
   if (!NATURAL_LETTER.test(letter)) {
     throw new InvalidInputError(
-      `Note.of takes a letter number 0..6 or a bare letter name 'C'..'B'; received ${JSON.stringify(letter)}. Use Note.parse(${JSON.stringify(letter)}) to read a note name with an accidental or an octave.`
+      `Note.of takes a letter number 0..6 or a bare letter name 'C'..'B'; received ${describeRejected(letter)}. Use Note.parse(${describeRejected(letter)}) to read a note name with an accidental or an octave.`
     );
   }
   return unwrapParse(tryParseNote(letter)).letter;
 }
-var DOUBLE_ACCIDENTAL = 2;
-var DIMINISHED_SECOND = { number: 2, quality: "d", semitones: 0 };
+var DIMINISHED_SECOND = {
+  number: 2,
+  quality: "d",
+  semitones: 0,
+  descending: false
+};
 var DESCENDING_DIMINISHED_SECOND = {
   ...DIMINISHED_SECOND,
   descending: true
@@ -809,7 +966,7 @@ var Note = class _Note {
    * ```
    */
   enharmonic() {
-    return [DIMINISHED_SECOND, DESCENDING_DIMINISHED_SECOND].map((interval) => transposeByInterval(this.#data, interval)).filter((note) => Math.abs(note.alter) <= DOUBLE_ACCIDENTAL).map((note) => new _Note(note));
+    return [DIMINISHED_SECOND, DESCENDING_DIMINISHED_SECOND].map((interval) => transposeByInterval(this.#data, interval)).filter((note) => Math.abs(note.alter) <= MAX_NAME_ACCIDENTALS).map((note) => new _Note(note));
   }
   /**
    * The scale degree this note occupies in a key, counted from 1 at the tonic.
@@ -830,7 +987,7 @@ var Note = class _Note {
    * ```
    */
   degreeIn(key) {
-    const degree = pitchToScaleDegree(this.pitchClass, toKeyScale(key));
+    const degree = pitchToScaleDegree(this.pitchClass, key);
     return degree === -1 ? null : degree;
   }
   /**
@@ -907,65 +1064,9 @@ var Note = class _Note {
   }
 };
 
-// src/model/shared.ts
-function assertKeyArgument(value, name) {
-  if (value === void 0 || typeof value === "object" && value !== null && "scale" in value) {
-    return;
-  }
-  const received = typeof value === "object" && value !== null ? "an object" : `a ${typeof value}`;
-  throw new InvalidInputError(
-    `${name} must be a Key; received ${received}. A method that also takes options takes them after the key, not in its place`
-  );
-}
-function withoutNegativeZero(value) {
-  return value === 0 ? 0 : value;
-}
-function spanEnd(...runs) {
-  let end = 0;
-  for (const run of runs) {
-    for (const span of run) {
-      end = Math.max(end, span.endBeat);
-    }
-  }
-  return end;
-}
-function copyNoteEvent(note) {
-  const copy = {
-    pitch: withoutNegativeZero(note.pitch),
-    startBeat: withoutNegativeZero(note.startBeat),
-    durationBeat: withoutNegativeZero(note.durationBeat)
-  };
-  if (note.velocity !== void 0) {
-    copy.velocity = withoutNegativeZero(note.velocity);
-  }
-  if (note.articulation !== void 0) {
-    copy.articulation = note.articulation;
-  }
-  return copy;
-}
-function copyTimeSignature(ts, name) {
-  assertTimeSignature(ts, name);
-  const copy = { numerator: ts.numerator, denominator: ts.denominator };
-  if (ts.grouping !== void 0) {
-    copy.grouping = [...ts.grouping];
-  }
-  return copy;
-}
-function samePlain(value, other) {
-  if (Array.isArray(value) || Array.isArray(other)) {
-    return Array.isArray(value) && Array.isArray(other) && value.length === other.length && value.every((item, index) => samePlain(item, other[index]));
-  }
-  if (typeof value === "object" && value !== null && typeof other === "object" && other !== null) {
-    const mine = Object.entries(value);
-    const theirs = other;
-    return mine.length === Object.keys(theirs).length && mine.every(([key, item]) => key in theirs && samePlain(item, theirs[key]));
-  }
-  return value === other;
-}
-
 // src/model/timeline.ts
-var GIVEN_KEY_CONFIDENCE = 1;
 function copySegment(segment) {
+  assertDataObject(segment, "timeline segment");
   return {
     startBeat: assertFiniteNumber(segment.startBeat, "timeline segment startBeat"),
     endBeat: assertFiniteNumber(segment.endBeat, "timeline segment endBeat"),
@@ -976,16 +1077,20 @@ function copySegment(segment) {
   };
 }
 function copyKeyRegion(region) {
+  assertDataObject(region, "key region");
   const copy = {
     startBeat: assertFiniteNumber(region.startBeat, "key region startBeat"),
     endBeat: assertFiniteNumber(region.endBeat, "key region endBeat"),
-    key: toKeyScale(region.key),
+    // Read through the key itself, so a tonic that does not spell the region's
+    // own root is refused here rather than spelling later notes wrongly.
+    key: keyIdentity(toKey(region.key)),
     confidence: assertFiniteNumber(region.confidence, "key region confidence")
   };
   if (region.modulation !== void 0) {
     copy.modulation = region.modulation;
   }
   if (region.pivot !== void 0) {
+    assertDataObject(region.pivot, "key region pivot");
     copy.pivot = {
       chord: new Chord(region.pivot.chord).toJSON(),
       romanFrom: region.pivot.romanFrom,
@@ -998,6 +1103,7 @@ function copyConfidence(confidence, segments) {
   if (confidence === void 0) {
     return [];
   }
+  assertDataArray(confidence, "timeline segmentConfidence");
   if (confidence.length !== segments) {
     throw new InvalidInputError(
       `timeline segmentConfidence must hold one value per segment; received ${confidence.length} for ${segments}`
@@ -1007,21 +1113,6 @@ function copyConfidence(confidence, segments) {
     (value, index) => assertRange(value, 0, 1, `timeline segmentConfidence[${index}]`)
   );
 }
-function chordAtBeat(segments, beat) {
-  assertFiniteNumber(beat, "timeline query beat");
-  let low = 0;
-  let high = segments.length;
-  while (low < high) {
-    const middle = Math.floor((low + high) / 2);
-    if ((segments[middle]?.startBeat ?? Number.POSITIVE_INFINITY) <= beat) {
-      low = middle + 1;
-    } else {
-      high = middle;
-    }
-  }
-  const candidate = segments[low - 1];
-  return candidate !== void 0 && beat >= candidate.startBeat && beat < candidate.endBeat ? candidate.chord : null;
-}
 function clipSpan(span, fromBeat, toBeat) {
   const startBeat = Math.max(span.startBeat, fromBeat);
   const endBeat = Math.min(span.endBeat, toBeat);
@@ -1041,14 +1132,19 @@ var Timeline = class _Timeline {
    *   the confidences do not run one per segment.
    */
   constructor(data) {
-    this.#segments = Object.freeze(data.segments.map(copySegment));
+    assertDataObject(data, "timeline data");
+    this.#segments = Object.freeze(
+      assertDataArray(data.segments, "timeline segments").map(copySegment)
+    );
     this.#totalBeats = assertRange(
       data.totalBeats,
       0,
       Number.MAX_SAFE_INTEGER,
       "timeline totalBeats"
     );
-    this.#keys = Object.freeze((data.keys ?? []).map(copyKeyRegion));
+    this.#keys = Object.freeze(
+      assertDataArray(data.keys ?? [], "timeline keys").map(copyKeyRegion)
+    );
     this.#segmentConfidence = Object.freeze(
       copyConfidence(data.segmentConfidence, this.#segments.length)
     );
@@ -1073,8 +1169,8 @@ var Timeline = class _Timeline {
           // so a chord placed in a pickup is covered by the key it sounds in.
           startBeat: timeline.segments[0]?.startBeat ?? 0,
           endBeat: totalBeats,
-          key: toKeyScale(key),
-          confidence: GIVEN_KEY_CONFIDENCE
+          key: keyIdentity(toKey(key)),
+          confidence: STATED_KEY_CONFIDENCE
         }
       ];
     }
@@ -1096,8 +1192,10 @@ var Timeline = class _Timeline {
    * Place a progression's chords on a regular grid.
    *
    * The chords cross over as harmony alone: a spelling one of them carried is
-   * dropped, and a carried key becomes the plain key/scale of the one region
-   * under the span, without its spelled tonic or its detected scale form.
+   * dropped, since a chord placed on the grid is a `ChordSpan` and a span
+   * carries none. A carried key becomes the one key region under the span,
+   * spelled tonic and scale form included — an Ab minor comes back Ab minor,
+   * which is what the numerals over the region are read from.
    *
    * @param progression The chords, in order.
    * @param beatsEach How long each chord sounds.
@@ -1151,9 +1249,18 @@ var Timeline = class _Timeline {
   /** The key held longest across the span, when the analysis found one. */
   get key() {
     const prevailing = prevailingKeyOf(this.#keys);
-    return prevailing === null ? void 0 : Key.of(prevailing);
+    return prevailing === null ? void 0 : toKey(prevailing);
   }
-  /** Every key region under the span, in time order. */
+  /**
+   * Every key region under the span, in time order.
+   *
+   * These are the regions the timeline was built with: the ones
+   * {@link Timeline.fromNotes} read off the notes, or the single region a key
+   * given to {@link Timeline.fromChords} describes. A timeline holding chords
+   * alone carries none until it is asked to read them —
+   * {@link Timeline.modulations} is where the chords are searched for the keys
+   * they imply.
+   */
   get keys() {
     return this.#keys.map(copyKeyRegion);
   }
@@ -1228,6 +1335,38 @@ var Timeline = class _Timeline {
   cadences() {
     return detectCadences(this.chordTimeline, this.#keyContext());
   }
+  /**
+   * The keys the chords themselves imply, in time order.
+   *
+   * The chord route to key regions, for a timeline that holds harmony without
+   * the notes it was played from — a lead sheet, or a progression laid out in
+   * time. A chord argues for a key far more strongly than its three or four
+   * pitch classes do, so a modulation is read off the chords rather than off a
+   * pitch-class profile, and the chord that reads in both keys is reported as
+   * the pivot the modulation turned on.
+   *
+   * The regions are searched for here rather than kept on the timeline:
+   * {@link Timeline.keys} answers with what the timeline was built with, which
+   * for placed chords is the key the caller stated or nothing at all.
+   *
+   * @param opts Analysis options; see {@link KeyTimelineOptions}.
+   * @returns The key regions the chords imply; empty when there are no chords.
+   * @example
+   * ```ts
+   * import { Chord, Key, Progression, Timeline } from '@libraz/libcantus';
+   * const progression = new Progression(
+   *   [Chord.parse('C'), Chord.parse('G7'), Chord.parse('C')],
+   *   Key.major('C'),
+   * );
+   * Timeline.fromProgression(progression, 4).modulations().length; // 1
+   * ```
+   */
+  modulations(opts) {
+    return detectModulations(this.#copySegments(), {
+      totalBeats: this.#totalBeats,
+      ...opts
+    }).map(copyKeyRegion);
+  }
   /**
    * The chords as roman numerals in a key.
    *
@@ -1240,8 +1379,9 @@ var Timeline = class _Timeline {
    * @throws If no key is given and the timeline carries none.
    */
   roman(key, opts) {
-    const given = key === void 0 ? void 0 : toKeyScale(key);
-    const keyAt = given === void 0 ? this.#keyContext() : () => given;
+    assertKeyArgument(key, "timeline key");
+    const given = key === void 0 ? void 0 : resolveKey(key);
+    const keyAt = given === void 0 ? this.#resolvedKeyAt() : () => given;
     return this.#segments.map((segment) => ({
       startBeat: segment.startBeat,
       endBeat: segment.endBeat,
@@ -1369,16 +1509,19 @@ var Timeline = class _Timeline {
   /** The key in force at a beat, or undefined when the timeline knows none. */
   #keyAt(beat) {
     const prevailing = prevailingKeyOf(this.#keys);
-    return prevailing === null ? void 0 : Key.of(keyLookup(this.#keys, prevailing)(beat));
+    return prevailing === null ? void 0 : toKey(keyLookup(this.#keys, prevailing)(beat));
   }
   /**
-   * The key every beat of the timeline is read against.
+   * The key every beat of the timeline is read against, spelling and all.
    *
    * A lookup rather than one key, so a timeline that modulates has each chord
-   * analyzed in the key it sounds in; beats outside every region fall back to
-   * the prevailing key.
+   * read in the key it sounds in; beats outside every region fall back to the
+   * prevailing key. The regions carry a spelled tonic and a scale form, and
+   * this hands them on as they are: an Ab minor is where a German sixth is
+   * named from — `Fb Ab Cb D` — and reading it through its pitch classes alone
+   * would number it as the G# minor those read best as.
    */
-  #keyContext() {
+  #resolvedKeyAt() {
     const prevailing = prevailingKeyOf(this.#keys);
     if (prevailing === null) {
       throw new InvalidInputError(
@@ -1387,6 +1530,18 @@ var Timeline = class _Timeline {
     }
     return keyLookup(this.#keys, prevailing);
   }
+  /**
+   * The pitch classes of that key, for the readings that want them.
+   *
+   * A reduction and a cadence are read from which notes are in the key rather
+   * than from how the key is written, so they take the scale; the reduction is
+   * where the drop is stated rather than in the lookup, which is what let the
+   * numerals lose the spelling by sharing it.
+   */
+  #keyContext() {
+    const keyAt = this.#resolvedKeyAt();
+    return (beat) => scaleOf(keyAt(beat));
+  }
   /** Move every chord and every key region by the same step. */
   #moved(moveChord, moveKey) {
     const segments = this.#segments.map((segment) => ({
@@ -1395,7 +1550,10 @@ var Timeline = class _Timeline {
       chord: moveChord(new Chord(segment.chord)).toJSON()
     }));
     const keys = this.#keys.map((region) => {
-      const moved = { ...region, key: moveKey(Key.of(region.key)).scale };
+      const moved = {
+        ...region,
+        key: keyIdentity(moveKey(toKey(region.key)))
+      };
       if (region.pivot !== void 0) {
         moved.pivot = {
           ...region.pivot,
@@ -1420,11 +1578,14 @@ var Progression = class _Progression {
    * Wrap a chord sequence.
    *
    * @param chords The chords in order; the array is copied.
-   * @param key Optional key context for analysis methods.
+   * @param key Optional key context for analysis methods, in whatever form the
+   *   caller holds it: a key name, a plain key/scale, or a {@link Key}.
    */
   constructor(chords, key) {
-    this.#chords = Object.freeze(_Progression.#attachKey(chords, key));
-    this.#key = key;
+    assertKeyArgument(key, "progression key");
+    const resolved = key === void 0 ? void 0 : toKey(key);
+    this.#chords = Object.freeze(_Progression.#attachKey(chords, resolved));
+    this.#key = resolved;
   }
   /**
    * Attach the progression key to every chord member.
@@ -1437,7 +1598,8 @@ var Progression = class _Progression {
    * number of times a key was attached.
    */
   static #attachKey(chords, key) {
-    return key === void 0 ? [...chords] : chords.map((chord) => chord.withKey(key));
+    const given = assertDataObjects(chords, "progression chords");
+    return key === void 0 ? [...given] : given.map((chord) => chord.withKey(key));
   }
   /**
    * Start from a chord sequence, matching the `of` factory on the other
@@ -1474,12 +1636,14 @@ var Progression = class _Progression {
    * ```ts
    * import { generateProgression, Key, Progression } from '@libraz/libcantus';
    * const key = Key.major('C');
-   * const spans = generateProgression({ key: key.scale, style: 'dance', bars: 4 });
+   * const spans = generateProgression({ key, style: 'dance', bars: 4 });
    * Progression.fromSpans(spans, key).roman();
    * ```
    */
   static fromSpans(spans, key) {
-    const chords = spans.map((span) => Chord.fromData(chordFromSpan(span)));
+    const chords = assertDataObjects(spans, "progression spans").map(
+      (span) => Chord.fromData(chordFromSpan(span))
+    );
     return new _Progression(chords, key);
   }
   /**
@@ -1489,8 +1653,11 @@ var Progression = class _Progression {
    * @returns The progression.
    */
   static fromJSON(data) {
+    assertDataObject(data, "progression data");
     const key = data.key === void 0 ? void 0 : Key.fromJSON(data.key);
-    const chords = data.chords.map((chord) => Chord.fromJSON(chord));
+    const chords = assertDataArray(data.chords, "progression chords").map(
+      (chord) => Chord.fromJSON(chord)
+    );
     return key === void 0 ? new _Progression(chords) : new _Progression(chords, key);
   }
   /**
@@ -1687,7 +1854,8 @@ var Progression = class _Progression {
   /**
    * A copy of this progression carrying the given key context.
    *
-   * @param key The key context to attach.
+   * @param key The key context to attach; a key name, a plain key/scale, or a
+   *   {@link Key}.
    * @returns The new progression.
    */
   withKey(key) {
@@ -1701,7 +1869,7 @@ var Progression = class _Progression {
    * @throws If any chord admits no voicing within the given ranges.
    */
   voice(opts) {
-    const key = opts?.key ?? this.#key?.scale;
+    const key = opts?.key ?? this.#key;
     return voiceProgression(
       this.#chords.map((chord) => chord.data),
       key === void 0 ? opts : { ...opts, key }
@@ -1710,7 +1878,8 @@ var Progression = class _Progression {
   /**
    * The Roman numeral of each chord in a key.
    *
-   * @param key Key to analyze in; falls back to the carried context.
+   * @param key Key to analyze in, as a key name, a plain key/scale, or a
+   *   {@link Key}; falls back to the carried context.
    * @param opts Applied-numeral rendering options.
    * @returns One numeral per chord.
    * @throws If no key is given and none is carried.
@@ -1722,7 +1891,8 @@ var Progression = class _Progression {
   /**
    * The harmonic function of each chord in a key.
    *
-   * @param key Key to analyze in; falls back to the carried context.
+   * @param key Key to analyze in, as a key name, a plain key/scale, or a
+   *   {@link Key}; falls back to the carried context.
    * @returns One function per chord.
    * @throws If no key is given and none is carried.
    */
@@ -1737,12 +1907,15 @@ var Progression = class _Progression {
    * progression has fewer than two chords.
    *
    * The options reach both analyses: `applied` and `alternatives` go to every
-   * chord, and `voicing` — the pitches of the last two chords, as
-   * {@link Progression.voice} produces them — to the cadence, which cannot tell
-   * a perfect authentic cadence from an imperfect one without knowing the
-   * soprano.
-   *
-   * @param key Key to analyze in; falls back to the carried context.
+   * chord, and `voicing` — the pitches sounding under the progression, one
+   * voicing per chord as {@link Progression.voice} produces them — to the
+   * cadence, which cannot tell a perfect authentic cadence from an imperfect
+   * one without knowing the soprano. It is the same shape
+   * {@link Progression.cadences} takes, and the closing pair is cut from it
+   * here; a two-element array is read as that pair itself.
+   *
+   * @param key Key to analyze in, as a key name, a plain key/scale, or a
+   *   {@link Key}; falls back to the carried context.
    * @param opts Applied-numeral rendering options, `alternatives` for the
    *   readings both analyses turned down, and `voicing` for the cadence's
    *   voice-leading detail; see {@link AnalyzeChordOptions} and
@@ -1753,19 +1926,41 @@ var Progression = class _Progression {
    * ```ts
    * import { Chord, Key, Progression } from '@libraz/libcantus';
    * const progression = new Progression([Chord.parse('G7'), Chord.parse('C')], Key.major('C'));
-   * const voiced = progression.voice();
-   * progression.analyze(undefined, { voicing: [voiced[0] ?? [], voiced[1] ?? []] }).cadence
-   *   ?.strength; // 'perfect'
+   * progression.analyze(undefined, { voicing: progression.voice() }).cadence?.strength;
+   * // 'perfect'
    * ```
    */
   analyze(key, opts) {
     const resolved = this.#resolveKey(key);
     const chords = this.#chords.map((chord) => chord.analyze(resolved, opts));
+    const { voicing, ...cadenceOpts } = opts ?? {};
     const from = this.#chords[this.#chords.length - 2];
     const to = this.#chords[this.#chords.length - 1];
-    const cadence = from !== void 0 && to !== void 0 ? detectCadence(from.data, to.data, resolved.scale, opts) : null;
+    const approach = this.#chords[this.#chords.length - 3];
+    const cadence = from !== void 0 && to !== void 0 ? detectCadence(from.data, to.data, resolved, {
+      ...cadenceOpts,
+      ...approach === void 0 ? {} : { approach: approach.data },
+      ...voicing === void 0 ? {} : { voicing: this.#closingVoicing(voicing) }
+    }) : null;
     return { chords, cadence };
   }
+  /**
+   * The two voicings of the closing pair, cut from the progression's own.
+   *
+   * `cadences` takes one voicing per chord and gives each pair its own two, so
+   * this entry takes that same array rather than a shape only it understands: a
+   * caller holding what `voice()` returned can hand it to either method. A
+   * two-element array is the closing pair already, which is what a progression
+   * of two chords produces either way.
+   */
+  #closingVoicing(voicing) {
+    if (voicing.length === this.#chords.length || voicing.length === 2) {
+      return [voicing[voicing.length - 2] ?? [], voicing[voicing.length - 1] ?? []];
+    }
+    throw new InvalidInputError(
+      `voicing must hold one voicing per chord (${this.#chords.length}) or the closing pair; received ${voicing.length}`
+    );
+  }
   /**
    * Choose one compatible scale for every chord, favoring smooth changes.
    *
@@ -1786,7 +1981,8 @@ var Progression = class _Progression {
    * The chord before each pair is supplied from the progression itself, so a
    * cadential six-four is recognized as one wherever it stands.
    *
-   * @param key Key to analyze in; falls back to the carried context.
+   * @param key Key to analyze in, as a key name, a plain key/scale, or a
+   *   {@link Key}; falls back to the carried context.
    * @param opts `voicing` is the pitches sounding under the whole progression,
    *   one voicing per chord as {@link Progression.voice} produces them, from
    *   which each pair takes its own two — without it no authentic cadence can be
@@ -1815,12 +2011,12 @@ var Progression = class _Progression {
       if (from === void 0 || to === void 0) {
         continue;
       }
-      const approach = index >= 2 ? this.#chords[index - 2] : opts?.approach;
+      const approach = index >= 2 ? this.#chords[index - 2]?.data : opts?.approach;
       const pair = opts?.voicing;
       found.push(
-        detectCadence(from.data, to.data, resolved.scale, {
+        detectCadence(from.data, to.data, resolved, {
           ...opts?.alternatives === void 0 ? {} : { alternatives: opts.alternatives },
-          ...approach === void 0 ? {} : { approach: approach.data },
+          ...approach === void 0 ? {} : { approach },
           ...pair === void 0 ? {} : { voicing: [pair[index - 1] ?? [], pair[index] ?? []] }
         })
       );
@@ -1860,7 +2056,7 @@ var Progression = class _Progression {
       );
     }
     const key = this.#resolveKey();
-    const chosen = substituteChord(target.data, key.scale, opts).find(
+    const chosen = substituteChord(target.data, key, opts).find(
       (candidate) => candidate.type === type
     );
     if (chosen === void 0) {
@@ -1943,7 +2139,8 @@ var Progression = class _Progression {
    * a target in another mode — a relative, parallel, or modal key — is the key
    * the progression is then analyzed in.
    *
-   * @param target The key the transposed progression should be in.
+   * @param target The key the transposed progression should be in, as a key
+   *   name, a plain key/scale, or a {@link Key}.
    * @returns The transposed progression, carrying `target` as its key.
    * @throws If the progression carries no key context to measure from.
    * @example
@@ -1960,9 +2157,11 @@ var Progression = class _Progression {
         "progression has no key context; attach one with withKey() before transposing to another key"
       );
     }
-    const interval = from.intervalTo(target);
+    assertKeyArgument(target, "progression key");
+    const resolved = toKey(target);
+    const interval = from.intervalTo(resolved);
     const chords = this.#chords.map((chord) => chord.transposeBy(interval));
-    return new _Progression(chords, target);
+    return new _Progression(chords, resolved);
   }
   /**
    * The chord symbols separated by spaces, so a template literal or a log line
@@ -1987,10 +2186,15 @@ var Progression = class _Progression {
       key: this.#key?.toJSON()
     };
   }
-  /** Resolve the key for an analysis method: explicit first, then carried. */
+  /**
+   * Resolve the key for an analysis method: explicit first, then carried.
+   *
+   * Every method that takes a key comes through here, so the shape check and
+   * the fallback to the carried context are the same wherever a key is read.
+   */
   #resolveKey(key) {
     assertKeyArgument(key, "progression key");
-    const resolved = key ?? this.#key;
+    const resolved = key === void 0 ? this.#key : toKey(key);
     if (resolved === void 0) {
       throw new InvalidInputError(
         "progression has no key context; pass a Key or attach one with withKey()"
@@ -2004,13 +2208,6 @@ var Progression = class _Progression {
 function hintMatches(hint, pc) {
   return hint !== void 0 && pc !== void 0 && pitchClassOf(noteToPitchClass(hint)) === pitchClassOf(pc);
 }
-function transposeHint(hint, semitones) {
-  if (hint === void 0) {
-    return void 0;
-  }
-  const moved = transposeNote(hint, semitones);
-  return { letter: moved.letter, alter: moved.alter };
-}
 function transposeHintByInterval(hint, interval) {
   if (hint === void 0) {
     return void 0;
@@ -2018,12 +2215,6 @@ function transposeHintByInterval(hint, interval) {
   const moved = transposeByInterval(hint, interval);
   return { letter: moved.letter, alter: moved.alter };
 }
-function transposeToneHints(hints, semitones) {
-  return hints?.map((hint) => {
-    const moved = transposeNote(hint, semitones);
-    return { letter: moved.letter, alter: moved.alter };
-  });
-}
 function transposeToneHintsByInterval(hints, interval) {
   return hints?.map((hint) => {
     const moved = transposeByInterval(hint, interval);
@@ -2031,18 +2222,22 @@ function transposeToneHintsByInterval(hints, interval) {
   });
 }
 function copyChord(data) {
+  assertDataObject(data, "chord data");
+  assertChordQuality(data.quality);
+  const rootPc = pitchClassOf(data.rootPc);
   const copy = {
-    rootPc: pitchClassOf(data.rootPc),
+    rootPc,
     quality: data.quality,
     // Each offset is checked rather than copied blind: a chord holding a NaN
     // interval voices, spells and formats as a chord that looks real, and the
     // failure surfaces wherever the number is finally used.
-    intervals: data.intervals.map(
+    intervals: assertDataArray(data.intervals, "chord intervals").map(
       (interval, index) => assertFiniteNumber(interval, `chord intervals[${index}]`)
     )
   };
-  if (data.bassPc !== void 0) {
-    copy.bassPc = pitchClassOf(data.bassPc);
+  const bassPc = data.bassPc === void 0 ? void 0 : pitchClassOf(data.bassPc);
+  if (bassPc !== void 0 && bassPc !== rootPc) {
+    copy.bassPc = bassPc;
   }
   const tones = chordToneSpellings(data);
   if (tones !== void 0) {
@@ -2051,7 +2246,7 @@ function copyChord(data) {
   if (hintMatches(data.rootSpelling, data.rootPc) && data.rootSpelling !== void 0) {
     copy.rootSpelling = { letter: data.rootSpelling.letter, alter: data.rootSpelling.alter };
   }
-  if (hintMatches(data.bassSpelling, data.bassPc) && data.bassSpelling !== void 0) {
+  if (hintMatches(data.bassSpelling, copy.bassPc) && data.bassSpelling !== void 0) {
     copy.bassSpelling = { letter: data.bassSpelling.letter, alter: data.bassSpelling.alter };
   }
   return copy;
@@ -2072,7 +2267,7 @@ function deriveBassSpelling(chord, key) {
   if (key === void 0) {
     return void 0;
   }
-  const spelled = spellPitchClass(bassPc, key.tonic.data, key.scale);
+  const spelled = spellPitchClass(bassPc, key.tonic.data, key);
   return { letter: spelled.letter, alter: spelled.alter };
 }
 var Chord = class _Chord {
@@ -2083,11 +2278,13 @@ var Chord = class _Chord {
    * Wrap a plain chord object.
    *
    * @param data The chord; it is copied, never retained or mutated.
-   * @param key Optional key context for analysis methods.
+   * @param key Optional key context for analysis methods, in whatever form the
+   *   caller holds it: a key name, a plain key/scale, or a {@link Key}.
    */
   constructor(data, key) {
     this.#given = copyChord(data);
-    this.#key = key;
+    assertKeyArgument(key, "chord key");
+    this.#key = key === void 0 ? void 0 : toKey(key);
   }
   /**
    * The chord data with any missing spelling hint filled in from the key.
@@ -2103,7 +2300,7 @@ var Chord = class _Chord {
   #dataWithKey(key) {
     const out = copyChord(this.#given);
     if (out.rootSpelling === void 0 && key !== void 0) {
-      out.rootSpelling = spellPitchClass(out.rootPc, key.tonic.data, key.scale);
+      out.rootSpelling = spellPitchClass(out.rootPc, key.tonic.data, key);
     }
     if (out.bassSpelling === void 0) {
       const bass = deriveBassSpelling(out, key);
@@ -2188,11 +2385,11 @@ var Chord = class _Chord {
    * ```ts
    * import { Chord } from '@libraz/libcantus';
    * Chord.fromFiguredBass('B', '6', 'C major').symbol(); // 'G/B'
-   * Chord.fromFiguredBass('G', '#', 'C minor').symbol(); // 'G'
+   * Chord.fromFiguredBass('G', 'n', 'C minor').symbol(); // 'G'
    * ```
    */
   static fromFiguredBass(bass, figures, key) {
-    return new _Chord(realizeFiguredBass(toNoteData(bass), figures, toKeyScale(key)));
+    return new _Chord(realizeFiguredBass(toNoteData(bass), figures, key));
   }
   /**
    * Parse a lead-sheet chord symbol (e.g. `'Cmaj7'`, `'F#m7b5'`, `'C/G'`).
@@ -2344,7 +2541,8 @@ var Chord = class _Chord {
    * during a modulation does not keep the old key's letters and the order of
    * `withKey` calls does not affect the result.
    *
-   * @param key The key context to attach.
+   * @param key The key context to attach; a key name, a plain key/scale, or a
+   *   {@link Key}.
    * @returns The new chord.
    */
   withKey(key) {
@@ -2412,13 +2610,14 @@ var Chord = class _Chord {
   /**
    * The chord's Roman numeral in a key.
    *
-   * @param key Key to analyze in; falls back to the carried context.
+   * @param key Key to analyze in, as a key name, a plain key/scale, or a
+   *   {@link Key}; falls back to the carried context.
    * @param opts Applied-numeral rendering options.
    * @returns The Roman numeral string.
    * @throws If no key is given and none is carried.
    */
   roman(key, opts) {
-    return chordToRoman(this.#data, this.#resolveKey(key).scale, opts);
+    return chordToRoman(this.#data, this.#resolveKey(key), opts);
   }
   /**
    * The chord's Roman numeral together with the reasoning behind it: the degree
@@ -2446,23 +2645,25 @@ var Chord = class _Chord {
    * ```
    */
   explain(key, opts) {
-    return explainRoman(this.#data, this.#resolveScale(key), opts);
+    return explainRoman(this.#data, this.#resolveKey(key), opts);
   }
   /**
    * The chord's harmonic function (tonic / subdominant / dominant) in a key.
    *
-   * @param key Key to analyze in; falls back to the carried context.
+   * @param key Key to analyze in, as a key name, a plain key/scale, or a
+   *   {@link Key}; falls back to the carried context.
    * @returns The harmonic function.
    * @throws If no key is given and none is carried.
    */
   function(key) {
-    return functionOf(this.#data, this.#resolveKey(key).scale);
+    return functionOf(this.#data, this.#resolveKey(key));
   }
   /**
    * Full functional analysis: function, borrowing, Roman numeral, and the
    * rationale behind them.
    *
-   * @param key Key to analyze in; falls back to the carried context.
+   * @param key Key to analyze in, as a key name, a plain key/scale, or a
+   *   {@link Key}; falls back to the carried context.
    * @param opts Applied-numeral rendering options, plus `alternatives` to
    *   collect the readings this analysis turned down; see
    *   {@link AnalyzeChordOptions}.
@@ -2475,27 +2676,29 @@ var Chord = class _Chord {
    * ```
    */
   analyze(key, opts) {
-    return analyzeChord(this.#data, this.#resolveKey(key).scale, opts);
+    return analyzeChord(this.#data, this.#resolveKey(key), opts);
   }
   /**
    * Whether the chord is borrowed from the parallel mode (modal interchange).
    *
-   * @param key Key to analyze in; falls back to the carried context.
+   * @param key Key to analyze in, as a key name, a plain key/scale, or a
+   *   {@link Key}; falls back to the carried context.
    * @returns True if the chord is borrowed.
    * @throws If no key is given and none is carried.
    */
   isBorrowed(key) {
-    return isBorrowedChord(this.#data, this.#resolveKey(key).scale);
+    return isBorrowedChord(this.#data, this.#resolveKey(key));
   }
   /**
    * The origin of a non-diatonic chord (parallel mode or Neapolitan), or null.
    *
-   * @param key Key to analyze in; falls back to the carried context.
+   * @param key Key to analyze in, as a key name, a plain key/scale, or a
+   *   {@link Key}; falls back to the carried context.
    * @returns The borrowing source, or null.
    * @throws If no key is given and none is carried.
    */
   borrowedSource(key) {
-    return borrowedSource(this.#data, this.#resolveKey(key).scale);
+    return borrowedSource(this.#data, this.#resolveKey(key));
   }
   /**
    * The chord written as the figures a bass would carry under it: `6`, `64`,
@@ -2520,7 +2723,7 @@ var Chord = class _Chord {
    * ```
    */
   figuredBass(key) {
-    return figuredBassOf(this.#data, this.#resolveScale(key));
+    return figuredBassOf(this.#data, this.#resolveKey(key));
   }
   /**
    * The chords that can stand in for this one in a key: its tritone substitute,
@@ -2547,7 +2750,7 @@ var Chord = class _Chord {
    * ```
    */
   substitutions(key, opts) {
-    return substituteChord(this.#data, this.#resolveScale(key), opts);
+    return substituteChord(this.#data, this.#resolveKey(key), opts);
   }
   /**
    * The modal-interchange palette of the chord's key: the parallel mode's
@@ -2572,7 +2775,7 @@ var Chord = class _Chord {
    * ```
    */
   modalInterchange(key) {
-    return modalInterchangePalette(this.#resolveScale(key));
+    return modalInterchangePalette(this.#resolveKey(key));
   }
   /**
    * The chord rendered as a lead-sheet symbol (e.g. `'Cmaj7'`, `'F#m7'`, `'C/G'`).
@@ -2600,7 +2803,7 @@ var Chord = class _Chord {
    * @throws If no voicing fits the given ranges.
    */
   voice(opts) {
-    const key = opts?.key ?? this.#key?.scale;
+    const key = opts?.key ?? this.#key;
     return voiceChord(this.#data, key === void 0 ? opts : { ...opts, key });
   }
   /**
@@ -2617,14 +2820,14 @@ var Chord = class _Chord {
    * The negative-harmony mirror of the chord about the key's tonic–dominant
    * axis (major becomes minor and vice versa).
    *
-   * @param key Key providing the reflection axis; falls back to the carried
-   *   context.
+   * @param key Key providing the reflection axis, as a key name, a plain
+   *   key/scale, or a {@link Key}; falls back to the carried context.
    * @returns The mirrored chord, keeping any key context.
    * @throws If no key is given and none is carried.
    */
   negativeHarmony(key) {
     const resolved = this.#resolveKey(key);
-    return new _Chord(negativeHarmonyMirror(this.#data, resolved.scale), key ?? this.#key);
+    return new _Chord(negativeHarmonyMirror(this.#data, resolved), resolved);
   }
   /**
    * The V7 that tonicizes this chord: a dominant seventh a perfect fifth above
@@ -2690,9 +2893,10 @@ var Chord = class _Chord {
    */
   transpose(semitones) {
     const moved = transposeChord(this.#given, semitones);
-    const rootSpelling = transposeHint(this.#given.rootSpelling, semitones);
-    const bassSpelling = transposeHint(this.#given.bassSpelling, semitones);
-    const toneSpellings = transposeToneHints(this.#given.toneSpellings, semitones);
+    const { rootSpelling, bassSpelling, toneSpellings } = transposeChordSpellings(
+      this.#given,
+      semitones
+    );
     if (rootSpelling !== void 0) {
       moved.rootSpelling = rootSpelling;
     }
@@ -2744,6 +2948,10 @@ var Chord = class _Chord {
    * The named scales that fit over this chord, best fit first, rooted on the
    * chord root.
    *
+   * Only the scales of {@link NAMED_SCALES} are ranked: chord-scale theory is a
+   * Western practice, so the scales of {@link WORLD_SCALES} are left out rather
+   * than offered as answers over a chord.
+   *
    * @returns The matching scales.
    */
   scales() {
@@ -2775,12 +2983,16 @@ var Chord = class _Chord {
    * The available tensions (usable non-chord, non-avoid scale tones) of a
    * scale over this chord.
    *
-   * @param scaleName A named scale, rooted on the chord root.
+   * @param scaleName A scale of {@link NAMED_SCALES}, or one of its aliases,
+   *   rooted on the chord root. The scales of {@link WORLD_SCALES} are refused
+   *   here as they are by {@link Chord.scales}: chord-scale theory is a Western
+   *   practice, and a scale from another tradition offered over a chord would
+   *   read as an answer while being a category error.
    * @param opts Set `resolvesTo` to the plain chord this one resolves to, so a
    *   dominant resolving down a fifth onto a minor tonic takes the tensions
    *   that resolution makes available; see {@link AvailableTensionsOptions}.
    * @returns Tension pitch classes, ascending in [0, 11].
-   * @throws If `scaleName` is not a built-in scale.
+   * @throws If `scaleName` is not one of the named scales or their aliases.
    * @example
    * ```ts
    * import { Chord } from '@libraz/libcantus';
@@ -2796,12 +3008,16 @@ var Chord = class _Chord {
    * The avoid notes (scale tones a semitone above a chord tone) of a scale
    * over this chord.
    *
-   * @param scaleName A named scale, rooted on the chord root.
+   * @param scaleName A scale of {@link NAMED_SCALES}, or one of its aliases,
+   *   rooted on the chord root. The scales of {@link WORLD_SCALES} are refused
+   *   here as they are by {@link Chord.scales}: chord-scale theory is a Western
+   *   practice, and a scale from another tradition offered over a chord would
+   *   read as an answer while being a category error.
    * @param opts Set `use: 'melodic'` to judge a line rather than a voicing, so
    *   a tone a line may pass through is not counted; see
    *   {@link AvoidNotesOptions}.
    * @returns Avoid-note pitch classes, ascending in [0, 11].
-   * @throws If `scaleName` is not a built-in scale.
+   * @throws If `scaleName` is not one of the named scales or their aliases.
    * @example
    * ```ts
    * import { Chord } from '@libraz/libcantus';
@@ -2824,15 +3040,18 @@ var Chord = class _Chord {
    * are the notes the chord sounds — the same set {@link Chord.pitchClasses}
    * reports.
    *
-   * @param key Key providing the spelled tonic; falls back to the carried
-   *   context, then to the chord's own root spelling.
+   * @param key Key providing the spelled tonic, as a key name, a plain
+   *   key/scale, or a {@link Key} — the tonic its letters are spelled from is
+   *   derived from the key rather than asked of the caller. Falls back to the
+   *   carried context, then to the chord's own root spelling.
    * @returns Spelled octave-less notes in the chord's own (tertian) order,
    *   with any foreign slash bass last.
    * @throws If no key is given, none is carried, and the chord has no root
    *   spelling of its own.
    */
   spell(key) {
-    const resolved = key ?? this.#key;
+    assertKeyArgument(key, "chord key");
+    const resolved = key === void 0 ? this.#key : toKey(key);
     const data = this.#dataWithKey(resolved);
     let tones;
     if (resolved === void 0) {
@@ -2844,7 +3063,7 @@ var Chord = class _Chord {
       }
       tones = spellChordFromRoot(data, root);
     } else {
-      tones = spellChord(data, resolved.tonic.data, resolved.scale);
+      tones = spellChord(data, resolved.tonic.data, resolved);
     }
     const bassPc = data.bassPc;
     const bass = data.bassSpelling;
@@ -2913,16 +3132,14 @@ var Chord = class _Chord {
     return this.symbol();
   }
   /**
-   * Resolve the key/scale for a method that takes any key-shaped value:
-   * explicit first, then carried, by the same rule {@link Chord.roman} follows.
+   * Resolve the key for an analysis method: explicit first, then carried.
+   *
+   * Every method that takes a key comes through here, so the shape check and
+   * the fallback to the carried context are the same wherever a key is read.
    */
-  #resolveScale(key) {
-    return key === void 0 ? this.#resolveKey().scale : toKeyScale(key);
-  }
-  /** Resolve the key for an analysis method: explicit first, then carried. */
   #resolveKey(key) {
     assertKeyArgument(key, "chord key");
-    const resolved = key ?? this.#key;
+    const resolved = key === void 0 ? this.#key : toKey(key);
     if (resolved === void 0) {
       throw new InvalidInputError(
         "chord has no key context; pass a Key or attach one with withKey()"
@@ -2933,8 +3150,23 @@ var Chord = class _Chord {
 };
 
 // src/model/key.ts
-var MAX_CONVENTIONAL_FIFTHS = 7;
-var DOUBLE_ACCIDENTAL2 = 2;
+function detectedKeyMatch(match) {
+  const key = { ...resolveKey(match.key), variant: match.variant };
+  return { ...match, key: toKey(key) };
+}
+function scaleWord(mask, isMinor) {
+  const name = scaleNameOfMask(mask);
+  if (name === void 0) {
+    return isMinor ? "minor" : "major";
+  }
+  if (name === "major") {
+    return "major";
+  }
+  if (name === "naturalMinor") {
+    return "minor";
+  }
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+}
 var HEPTATONIC_DEGREES = 7;
 var REFERENCE_TONIC = { letter: 0, alter: 0 };
 function bareInterval(from, to) {
@@ -2944,7 +3176,7 @@ function bareInterval(from, to) {
   );
 }
 function spelledTonicFor(scale) {
-  return new Note(spelledKeyOf(scale).tonic);
+  return new Note(resolveKey(scale).tonic);
 }
 function isNoteInstance(value) {
   if (value === null || typeof value !== "object") {
@@ -2969,9 +3201,12 @@ var Key = class _Key {
    *
    * @param scale The key/scale; its root is normalized to a pitch class.
    * @param tonic The spelled tonic anchoring letter-name spelling.
-   * @param variant Optional detected scale form retained for display.
+   * @param variant The scale form. Read from the mask when none is named: a
+   *   major mask is a major key whoever built it, and a key with no form at all
+   *   is a state a reader would have to guess about.
    */
   constructor(scale, tonic, variant) {
+    assertDataObject(scale, "scale");
     assertInteger(scale.rootPc, "scale.rootPc");
     assertInteger(scale.modeMask12, "scale.modeMask12", 1, 4095);
     if ((scale.modeMask12 & 1) === 0) {
@@ -2988,14 +3223,16 @@ var Key = class _Key {
         `tonic ${tonic.name} does not match the scale root pitch class ${rootPc}; pass a tonic that spells the scale root, or omit it to have one chosen`
       );
     }
+    if (variant !== void 0) {
+      assertKeyVariant(variant, scale.modeMask12);
+    }
     this.#scale = { rootPc, modeMask12: scale.modeMask12 };
     this.#tonic = tonic;
-    this.#variant = variant;
+    this.#variant = variant ?? variantOfMask(scale.modeMask12);
   }
   /** Preserve detection metadata while replacing its plain key with this API's Key. */
   static #fromMatch(match) {
-    const key = new _Key(match.key, spelledTonicFor(match.key), match.variant);
-    return { ...match, key };
+    return detectedKeyMatch(match);
   }
   /**
    * Wrap a key the theory layer spelled, keeping its tonic exactly as given.
@@ -3005,7 +3242,7 @@ var Key = class _Key {
    * would throw that spelling away (Bb minor would come back as A# minor).
    */
   static #fromSpelled(spelled) {
-    return new _Key(spelled.key, new Note(spelled.tonic));
+    return new _Key(spelled.scale, new Note(spelled.tonic), spelled.variant);
   }
   /**
    * A major key.
@@ -3067,8 +3304,12 @@ var Key = class _Key {
    * is G sharp major and `'gis'` G sharp minor; see {@link parseKeyName} for
    * how a name whose case and mode word disagree is read.
    *
-   * The result is always a plain major or minor key. Only the tonic's spelling
-   * survives from the name, so `'ges dur'` is G flat major, not F sharp major.
+   * An English name may also name a built-in scale instead of a mode —
+   * `'D harmonic minor'`, `'D dorian'`, `'C major pentatonic'` — which is what
+   * {@link Key.toString} writes for a key that is neither a plain major nor a
+   * plain minor, so a key survives being written down and read back. Only the
+   * tonic's spelling survives from the name, so `'ges dur'` is G flat major,
+   * not F sharp major.
    *
    * @param text The key name.
    * @param opts `system` reads the name in that notation system instead of
@@ -3107,15 +3348,18 @@ var Key = class _Key {
    * ```
    */
   static tryParse(text, opts) {
-    const parsed = tryParseKeyName(text, opts);
-    return parsed.ok ? { ok: true, value: _Key.#modeOn(parsed.value.mode, new Note(parsed.value.tonic)) } : parsed;
+    const parsed = tryResolveKeyName(text, opts);
+    return parsed.ok ? {
+      ok: true,
+      value: new _Key(parsed.value.scale, new Note(parsed.value.tonic), parsed.value.variant)
+    } : parsed;
   }
   /**
    * The key a key signature denotes: the inverse of {@link Key.fifths}.
    *
    * A signature names two keys — three sharps is both A major and F# minor — so
    * the mode decides which one is built. The tonic is spelled the way that key
-   * is written, including the theoretical keys past ±7 (nine sharps is B#
+   * is written, including the theoretical keys past ±7 (nine sharps is D#
    * major).
    *
    * @param fifths The signed number of sharps (positive) or flats (negative).
@@ -3142,13 +3386,20 @@ var Key = class _Key {
    * This is what keeps `Key.of(detectKey(...).scale)` from handing every
    * downstream chord a double-sharp spelling.
    *
-   * @param scale The key/scale to wrap.
-   * @param tonic Optional spelled tonic; must spell the scale's root pitch class.
+   * A value that already carries a spelling keeps it — a key region's key, the
+   * data a key serializes to — so wrapping one is not where an Ab minor becomes
+   * a G# minor. Only a bare key/scale has a tonic chosen for it, because only a
+   * bare key/scale is missing one.
+   *
+   * @param key The key to wrap, in any form a key is held in.
+   * @param tonic Optional spelled tonic, overriding any the value carries; must
+   *   spell the scale's root pitch class.
    * @returns The key.
    * @throws If the given tonic is not the scale's root pitch class.
    */
-  static of(scale, tonic) {
-    return new _Key(scale, tonic ?? spelledTonicFor(scale));
+  static of(key, tonic) {
+    const resolved = resolveKey(key);
+    return new _Key(resolved.scale, tonic ?? new Note(resolved.tonic), resolved.variant);
   }
   /**
    * Rebuild a key from its {@link Key.toJSON} output.
@@ -3157,6 +3408,7 @@ var Key = class _Key {
    * @returns The key.
    */
   static fromJSON(data) {
+    assertDataObject(data, "key data");
     return new _Key(data.scale, new Note(data.tonic), data.variant);
   }
   /**
@@ -3355,12 +3607,18 @@ var Key = class _Key {
     return supportsFunctionalHarmony(this.#scale);
   }
   /**
-   * The relative key: the same key signature read in the other mode.
+   * The relative key: for a plain major or minor key, the same key signature
+   * read in the other mode.
    *
    * Because the new tonic is read off the circle of fifths rather than
    * transposed by semitones, the relative of Db major is Bb minor and not its
    * enharmonic A# minor.
    *
+   * A key that is not a plain major or minor is read through the mode its third
+   * names and stepped from where its tonic stands on the circle: the relative of
+   * D dorian is F major. The shared signature does not carry over to those —
+   * D dorian is written with no accidentals and F major with one.
+   *
    * @returns The relative key, always a plain major or minor key.
    * @throws If this key's signature falls outside [-12, 12] fifths.
    * @example
@@ -3443,10 +3701,16 @@ var Key = class _Key {
    *
    * These are the keys the German and Japanese teaching tradition counts as a
    * key's near relations: the relative and parallel keys, the dominant and the
-   * subdominant, and the relatives of those two. Five of them are written
-   * within one accidental of this key's signature — the relative shares it
-   * exactly and the other four stand one away; the parallel key stands three
-   * away and belongs to the set for the tonic it shares instead.
+   * subdominant, and the relatives of those two. For a plain major or minor key
+   * five of them are written within one accidental of this key's signature — the
+   * relative shares it exactly and the other four stand one away; the parallel
+   * key stands three away and belongs to the set for the tonic it shares
+   * instead.
+   *
+   * A key that is not a plain major or minor is read through the mode its third
+   * names, so its relations are walked from where its tonic stands on the circle
+   * rather than from its own signature, and those accidental counts do not
+   * describe them.
    *
    * @returns The related keys in relation order.
    * @throws If a neighbouring signature falls outside [-12, 12] fifths.
@@ -3487,10 +3751,38 @@ var Key = class _Key {
    * ```
    */
   relationTo(other) {
-    return keyRelationBetween(
-      { tonic: this.#tonic.data, key: this.#scale },
-      { tonic: other.tonic.data, key: other.scale }
-    );
+    return keyRelationBetween(this.toJSON(), other.toJSON());
+  }
+  /**
+   * The chords a modulation from this key into another can pivot on.
+   *
+   * A pivot belongs to both keys at once, so it is heard as a degree of this
+   * key and reinterpreted as a degree of the key being entered. The candidates
+   * are this key's diatonic triads, kept when every one of their pitch classes
+   * is also a scale tone of `other`; each is reported with its numeral in both
+   * keys. A key that stacks no diatonic triads offers nothing to pivot on and
+   * yields an empty list rather than an error.
+   *
+   * @param other The key being entered, as a key name, a plain key/scale, or a
+   *   {@link Key}.
+   * @returns The shared triads, ascending by their degree in this key, each
+   *   chord carrying this key as its context.
+   * @example
+   * ```ts
+   * import { Key } from '@libraz/libcantus';
+   * Key.major('C')
+   *   .pivotsTo('G major')
+   *   .map((pivot) => `${pivot.romanFrom}=${pivot.romanTo}`);
+   * // ['I=IV', 'iii=vi', 'V=I', 'vi=ii']
+   * ```
+   */
+  pivotsTo(other) {
+    assertKeyArgument(other, "key");
+    return pivotChords(this.#scale, other).map(({ chord, romanFrom, romanTo }) => ({
+      chord: new Chord(chord, this),
+      romanFrom,
+      romanTo
+    }));
   }
   /**
    * A scale degree, counted from 1 the way musicians name degrees: `degree(1)`
@@ -3520,6 +3812,11 @@ var Key = class _Key {
    * of C major gives F major. A scale with no diatonic triads — anything that
    * is not heptatonic — falls back to this key's own mode.
    *
+   * The tonic is derived rather than given, so the result is respelled to its
+   * enharmonic key whenever the letter arithmetic lands past the signatures keys
+   * are written with: the fourth degree of a C blues scale reads as F# minor,
+   * not as the Gb minor and its nine flats.
+   *
    * @param n The 1-based scale degree, as {@link Key.degree} counts them.
    * @param mode The mode of the resulting key; inferred when omitted.
    * @returns The key on that degree.
@@ -3569,10 +3866,17 @@ var Key = class _Key {
     );
     return _Key.#modeOn(resolved, tonic);
   }
-  /** A plain major or minor key on a spelled tonic. */
+  /**
+   * A plain major or minor key on a spelled tonic.
+   *
+   * The tonic is one this class derived — a scale degree of another key — so the
+   * result is held to the signatures keys are written with: the fourth degree of
+   * a C blues scale is written as an F# minor rather than as the Gb minor its
+   * letter arithmetic gives, which would be nine flats.
+   */
   static #modeOn(mode, tonic) {
     const rootPc = tonic.pitchClass;
-    return new _Key(mode === "minor" ? minorKey(rootPc) : majorKey(rootPc), tonic);
+    return new _Key(mode === "minor" ? minorKey(rootPc) : majorKey(rootPc), tonic).#asWritten();
   }
   /**
    * The mode a scale degree implies, read off its diatonic triad. Scales that
@@ -3661,27 +3965,45 @@ var Key = class _Key {
     assertFiniteNumber(semitones, "semitones");
     const rootPc = pitchClassOf(this.#scale.rootPc + Math.round(semitones));
     const scale = { rootPc, modeMask12: this.#scale.modeMask12 };
-    const moved = new _Key(scale, this.#tonic.transpose(semitones), this.#variant);
-    if (moved.#isWritten()) {
-      return moved;
+    return new _Key(scale, this.#tonic.transpose(semitones), this.#variant).#asWritten();
+  }
+  /**
+   * This key respelled to the enharmonic key it would actually be written as,
+   * or itself when it is already written that way.
+   *
+   * What every method that derives a tonic of its own ends on. A derived tonic
+   * can land past the signatures music is written with — nine flats, a scale
+   * needing double accidentals — and a key nobody would hand a player is not an
+   * answer to "which key is this". A key the caller spelled is never put through
+   * this: only a tonic the library chose is the library's to choose again.
+   *
+   * The enharmonic key supplies the tonic spelling only: the scale keeps this
+   * key's own mask, so a harmonic minor or a pentatonic is respelled rather than
+   * flattened into a plain major or minor key. A respelling that does not sound
+   * the same root is no respelling at all, so the key stands — deriving a key is
+   * total, and no spelling question may turn it into a throw.
+   */
+  #asWritten() {
+    if (this.#isWritten()) {
+      return this;
     }
-    const other = enharmonicKeyOf(moved.tonic.data, moved.scale);
+    const other = enharmonicKeyOf(this.#tonic.data, this.#scale);
     const respelled = other === null ? null : new Note(other.tonic);
-    return respelled === null || respelled.pitchClass !== rootPc ? moved : new _Key(scale, respelled, this.#variant);
+    return respelled === null || respelled.pitchClass !== pitchClassOf(this.#scale.rootPc) ? this : new _Key(this.#scale, respelled, this.#variant);
   }
   /**
    * Whether this key is spelled the way keys are actually written, which is
-   * what decides whether {@link Key.transpose} leaves a spelling alone.
+   * what decides whether a key this class derived a tonic for keeps that
+   * spelling — {@link Key.transpose}, {@link Key.keyOnDegree} and
+   * {@link Key.forInstrument} all end on it.
    *
-   * A key with a signature of its own is written wherever that signature is,
-   * up to seven sharps or flats. A scale that only borrows the signature of its
-   * parallel major or minor is written wherever it reads: the borrowed count
-   * says nothing — the octatonic scale on Db borrows eight flats and is spelled
-   * Db all the same — so what counts there is that no note needs a double
-   * accidental.
+   * The theory layer owns the answer and this asks it, so the class and the
+   * functions name the same written spelling — including at the ends of the
+   * church modes, where a window drawn from the major and minor keys and one
+   * drawn from the mode itself disagree.
    */
   #isWritten() {
-    return isSignatureKey(this.#scale) ? Math.abs(this.fifths) <= MAX_CONVENTIONAL_FIFTHS : this.notes().every((note) => Math.abs(note.alter) < DOUBLE_ACCIDENTAL2);
+    return isWrittenTonic(this.#tonic.data, this.#scale);
   }
   /**
    * The key a transposing instrument's part is written in, for this key at
@@ -3692,7 +4014,11 @@ var Key = class _Key {
    * lower than it reads — has its part written a major second higher, and a
    * concert C major becomes D major. The tonic is spelled by the interval, so
    * a concert E flat major reads as F major on that instrument rather than as
-   * E sharp major, and the mode mask is untouched.
+   * E sharp major, and the mode mask is untouched. What the interval spells is
+   * then respelled to its enharmonic key whenever it would not be written that
+   * way, since a part is what a player is actually handed: a concert F# major
+   * on a B flat clarinet reads as A flat major rather than as a G# major with an
+   * F double sharp in its signature.
    *
    * The opposite reading, a written key back to the key it sounds in, is
    * {@link Key.transposeBy} applied to {@link instrumentTransposition} — the
@@ -3707,6 +4033,7 @@ var Key = class _Key {
    * import { Key, instrumentTransposition } from '@libraz/libcantus';
    * Key.major('C').forInstrument('clarinetBb').toString(); // 'D major'
    * Key.major('C').forInstrument('hornF').toString(); // 'G major'
+   * Key.major('F#').forInstrument('clarinetBb').toString(); // 'Ab major'
    * // And back: what a part written in C major on a clarinet in A sounds as.
    * Key.major('C').transposeBy(instrumentTransposition('clarinetA')).toString(); // 'A major'
    * ```
@@ -3717,7 +4044,7 @@ var Key = class _Key {
       { rootPc: tonic.pitchClass, modeMask12: this.#scale.modeMask12 },
       tonic,
       this.#variant
-    );
+    ).#asWritten();
   }
   /**
    * The spelled scale, one note per degree (e.g. C D E F G A B for C major).
@@ -3835,7 +4162,28 @@ var Key = class _Key {
    * @throws If the numeral is not valid.
    */
   roman(text) {
-    return new Chord(romanToChord(text, this.#scale), this);
+    return new Chord(romanToChord(text, this), this);
+  }
+  /**
+   * The augmented sixth chord of a kind, built in this key.
+   *
+   * The three kinds share the augmented sixth between the lowered sixth degree
+   * and the raised fourth and differ in what fills it: the Italian doubles the
+   * tonic, the French adds the second degree, and the German the third. The
+   * chord is spelled as the interval demands rather than as its enharmonic
+   * dominant seventh, which is what keeps its outward resolution readable.
+   *
+   * @param kind Which augmented sixth to build.
+   * @returns The chord, with this key attached.
+   * @throws If the kind names none of the three.
+   * @example
+   * ```ts
+   * import { Key } from '@libraz/libcantus';
+   * Key.major('C').augmentedSixth('german').rootPc; // 8 (the lowered sixth degree)
+   * ```
+   */
+  augmentedSixth(kind) {
+    return new Chord(augmentedSixthChord(kind, keyIdentity(this)), this);
   }
   /**
    * Build a progression from Roman numerals in this key.
@@ -3921,16 +4269,23 @@ var Key = class _Key {
    *   one.
    */
   toJSON() {
-    return this.#variant === void 0 ? { scale: this.scale, tonic: this.#tonic.data } : { scale: this.scale, tonic: this.#tonic.data, variant: this.#variant };
+    return { scale: this.scale, tonic: this.#tonic.data, variant: this.#variant };
   }
   /**
-   * The key's tonic and mode, so a template literal or a log line reads as the
-   * key. Detected harmonic and melodic minor keys retain their scale form.
+   * The key's tonic and the scale it is read in, so a template literal or a log
+   * line reads as the key.
+   *
+   * The scale word is a function of the scale alone — its root pitch class and
+   * mode mask — rather than of how the key was built, so two keys holding the
+   * same scale print the same name: a harmonic minor names itself one whether
+   * it was detected or asked for by name, and a mode names its mode instead of
+   * the major or minor key its third would make it. What is printed is what
+   * {@link Key.parse} reads back.
    *
    * A `system` names the key the way that notation system writes it, including
-   * German's case convention. The scale form is an English-only qualifier —
-   * the other systems have no word for it — so a detected harmonic minor names
-   * its parallel plain minor there.
+   * German's case convention. The scale word is an English-only qualifier —
+   * the other systems have no word for it — so a harmonic minor names its
+   * parallel plain minor there.
    *
    * @param opts `system` writes the name in that notation system instead of
    *   English.
@@ -3939,8 +4294,8 @@ var Key = class _Key {
    * ```ts
    * import { Key } from '@libraz/libcantus';
    * Key.minor('G#').toString(); // 'G# minor'
+   * Key.named('dorian', 'D').toString(); // 'D dorian'
    * Key.minor('G#').toString({ system: 'german' }); // 'gis moll'
-   * Key.minor('G#').toString({ system: 'japanese' }); // '嬰ト短調'
    * ```
    */
   toString(opts) {
@@ -3950,32 +4305,40 @@ var Key = class _Key {
         opts
       );
     }
-    if (this.#variant === "harmonic" || this.#variant === "melodic") {
-      return `${this.#tonic.name} ${this.#variant} minor`;
-    }
-    return `${this.#tonic.name} ${this.isMinor ? "minor" : "major"}`;
+    return `${this.#tonic.name} ${scaleWord(this.#scale.modeMask12, this.isMinor)}`;
   }
 };
+function toKey(value) {
+  if (typeof value === "string") {
+    return Key.parse(value);
+  }
+  if (typeof value === "object" && value !== null) {
+    const data = "toJSON" in value && typeof value.toJSON === "function" ? value.toJSON() : value;
+    if (typeof data === "object" && data !== null) {
+      const record = data;
+      if (record.scale === void 0) {
+        const scale = toKeyScale(data);
+        return record.tonic === void 0 ? new Key(scale, spelledTonicFor(scale), record.variant) : new Key(scale, new Note(record.tonic), record.variant);
+      }
+      return record.tonic === void 0 ? Key.of(toKeyScale(record.scale)) : Key.fromJSON(record);
+    }
+  }
+  throw new InvalidInputError(`key must be a key name or a key/scale; received ${typeof value}`);
+}
+function keyIdentity(key) {
+  return { scale: key.scale, tonic: key.tonic.data, variant: key.variant };
+}
 
 // src/model/score.ts
 var DEFAULT_BPM = 120;
 function orderNotes(notes, name) {
-  if (!Array.isArray(notes)) {
-    throw new InvalidInputError(`${name} must be an array; received ${typeof notes}`);
-  }
-  return notes.map((note, index) => {
-    if (note === void 0) {
-      throw new InvalidInputError(`${name}[${index}] must be a note event; received undefined`);
-    }
-    return copyNoteEvent(
-      assertNoteEvent(note, `${name}[${index}]`, { allowNonPositiveDuration: true })
-    );
-  }).sort(
+  return assertNoteEventArray(notes, name, { allowNonPositiveDuration: true }).map((note) => copyNoteEvent(note)).sort(
     (a, b) => a.startBeat - b.startBeat || a.pitch - b.pitch || a.durationBeat - b.durationBeat
   );
 }
 function copyMeters(meters) {
-  return meters.map((change) => {
+  return assertDataObjects(meters, "score meters").map((change) => {
+    assertDataObject(change.ts, "score meters ts");
     const ts = {
       numerator: change.ts.numerator,
       denominator: change.ts.denominator
@@ -3987,6 +4350,7 @@ function copyMeters(meters) {
   });
 }
 function copyTempo(tempo) {
+  assertDataObjects(tempo, "score tempo");
   tempoAt(0, tempo);
   return tempo.map((event) => ({
     startBeat: withoutNegativeZero(event.startBeat),
@@ -3994,6 +4358,7 @@ function copyTempo(tempo) {
   }));
 }
 function copyScore(data) {
+  assertDataObject(data, "score data");
   const copy = {
     notes: orderNotes(data.notes, "score notes"),
     // The map is validated by the same resolver every meter-aware entry point
@@ -4006,33 +4371,46 @@ function copyScore(data) {
   }
   return copy;
 }
-function metersFrom(meters) {
-  if (meters === void 0) {
-    return resolveMeters({}, "score meters");
-  }
-  const meter = toMeterData(meters, "score meters");
-  return Array.isArray(meter) ? resolveMeters({ meters: meter }, "score meters") : resolveMeters({ ts: meter }, "score meters");
-}
 function tempoFrom(tempo) {
   if (tempo === void 0) {
     return [{ startBeat: 0, bpm: DEFAULT_BPM }];
   }
   return typeof tempo === "number" ? [{ startBeat: 0, bpm: tempo }] : tempo;
 }
+function statedKeyRegions(key, notes, totalBeats) {
+  const first = notes[0];
+  if (first === void 0 || totalBeats <= first.startBeat) {
+    return [];
+  }
+  return [
+    {
+      // The region starts where the music does, as an inferred one does, so a
+      // pickup is covered by the key it sounds in.
+      startBeat: first.startBeat,
+      endBeat: totalBeats,
+      key: keyIdentity(key),
+      confidence: STATED_KEY_CONFIDENCE
+    }
+  ];
+}
 function scoreData(notes, opts) {
   const data = {
-    notes: [...notes],
-    meters: metersFrom(opts?.meters),
+    notes: [...assertDataArray(notes, "score notes")],
+    meters: resolveMeters({ meters: opts?.meters }, "score meters"),
     tempo: tempoFrom(opts?.tempo)
   };
   if (opts?.key !== void 0) {
-    data.key = Key.of(toKeyScale(opts.key)).toJSON();
+    data.key = toKey(opts.key).toJSON();
   }
   return data;
 }
 var Score = class _Score {
   #data;
   #key;
+  /** The chord reading, made on the first member that needs it. */
+  #chords;
+  /** The key regions, made on the first member that needs them. */
+  #regions;
   /**
    * Wrap plain score data.
    *
@@ -4091,7 +4469,7 @@ var Score = class _Score {
    * ```
    */
   static fromTicks(events, ppq, opts) {
-    const notes = events.map((event) => ({
+    const notes = assertDataObjects(events, "score notes").map((event) => ({
       ...event,
       startBeat: ticksToBeats(event.startBeat, ppq),
       durationBeat: ticksToBeats(event.durationBeat, ppq)
@@ -4184,14 +4562,20 @@ var Score = class _Score {
   /**
    * The score moved by a number of semitones.
    *
+   * A carried key moves with the notes, so the score that comes back is read in
+   * the key it now sounds in and every analysis taken from it — its timeline,
+   * its numerals, its phrases — is taken against that key rather than against
+   * the one it was written in.
+   *
    * @param semitones The signed semitone offset.
    * @returns The transposed score.
    * @throws If a note would leave the MIDI range.
    */
   transpose(semitones) {
     assertFiniteNumber(semitones, "transpose semitones");
-    return this.#withNotes(
-      this.#data.notes.map((note) => ({ ...note, pitch: note.pitch + semitones }))
+    return this.#moved(
+      this.#data.notes.map((note) => ({ ...note, pitch: note.pitch + semitones })),
+      (key) => key.transpose(semitones)
     );
   }
   /**
@@ -4199,18 +4583,27 @@ var Score = class _Score {
    *
    * Note events carry a MIDI pitch and no spelling of their own, so the
    * interval contributes its size and its direction; a carried key is what
-   * keeps the spelling, and it moves with the notes.
+   * keeps the spelling, and it moves with the notes — by the interval itself,
+   * so an augmented fourth and a diminished fifth land on differently spelled
+   * keys.
    *
    * @param interval An interval name (e.g. `'A4'`, `'-m3'`), plain interval
    *   data, or an {@link Interval}; a descending interval moves down.
    * @returns The transposed score.
    */
   transposeBy(interval) {
-    return this.transpose(toSpelledInterval(interval).semitones);
+    const step = toSpelledInterval(interval);
+    return this.#moved(
+      this.#data.notes.map((note) => ({ ...note, pitch: note.pitch + step.semitones })),
+      // Moved by the interval rather than by its semitone count, so a key taken
+      // up an augmented fourth and one taken up a diminished fifth are spelled
+      // the way each interval demands.
+      (key) => key.transposeBy(step)
+    );
   }
   /** The same notes read against a different meter. */
   withMeters(meters) {
-    return new _Score({ ...this.#data, meters: metersFrom(meters) });
+    return new _Score({ ...this.#data, meters: resolveMeters({ meters }, "score meters") });
   }
   /** The same notes read against a different tempo. */
   withTempo(tempo) {
@@ -4218,7 +4611,7 @@ var Score = class _Score {
   }
   /** The same notes read in a different key. */
   withKey(key) {
-    return new _Score({ ...this.#data, key: Key.of(toKeyScale(key)).toJSON() });
+    return new _Score({ ...this.#data, key: toKey(key).toJSON() });
   }
   /**
    * The notes pulled onto a grid.
@@ -4324,7 +4717,7 @@ var Score = class _Score {
    *   and how sure it is of each segment.
    */
   timeline(opts) {
-    const result = chordTimelineFromNotes(this.#data.notes, this.#analysisOptions(opts));
+    const result = opts === void 0 ? this.#chordAnalysis() : chordTimelineFromNotes(this.#data.notes, this.#analysisOptions(opts));
     return Timeline.fromData({
       segments: result.timeline.segments,
       totalBeats: opts?.totalBeats ?? this.totalBeats,
@@ -4347,16 +4740,29 @@ var Score = class _Score {
       return this.#key;
     }
     const prevailing = prevailingKeyOf(this.#keyRegions());
-    return prevailing === null ? void 0 : Key.of(prevailing);
+    return prevailing === null ? void 0 : toKey(prevailing);
   }
   /**
    * Every key region the score passes through, in time order.
    *
+   * A score that was told its key answers with that key across the whole of it,
+   * as {@link Score.key} and {@link Score.timeline} do: the caller has already
+   * answered the question, and searching for a modulation away from a stated
+   * key would make the option read as a hint where it was given as an
+   * instruction. Only `totalBeats` is read from the options there, since the
+   * rest tune a search that is not run.
+   *
    * @param opts Analysis options; see {@link KeyTimelineOptions}.
    * @returns The regions; empty when nothing sounds.
    */
   keys(opts) {
-    return keyTimelineFromNotes(this.#data.notes, { meters: this.#data.meters, ...opts });
+    if (opts !== void 0) {
+      if (this.#key !== void 0) {
+        return statedKeyRegions(this.#key, this.#data.notes, opts.totalBeats ?? this.totalBeats);
+      }
+      return keyTimelineFromNotes(this.#data.notes, { meters: this.#data.meters, ...opts });
+    }
+    return this.#keyRegions().map(copyKeyRegion);
   }
   /**
    * Every key the score could be in, ranked, read as one key across the whole
@@ -4382,7 +4788,7 @@ var Score = class _Score {
    * ```
    */
   detectKeys(opts) {
-    return detectKeyFromNotes(this.#data.notes, opts);
+    return detectKeyFromNotes(this.#data.notes, opts).map(detectedKeyMatch);
   }
   /**
    * The phrases the notes fall into.
@@ -4396,7 +4802,7 @@ var Score = class _Score {
   phrases(opts) {
     return phrasesFromTimeline(this.#chordTimeline(), this.#data.notes, {
       meters: this.#data.meters,
-      ...this.#key === void 0 ? {} : { key: this.#key.scale },
+      ...this.#key === void 0 ? {} : { key: keyIdentity(this.#key) },
       ...opts
     });
   }
@@ -4428,11 +4834,18 @@ var Score = class _Score {
   /**
    * The bar-level pulse above the meter.
    *
+   * The cadences come from the score's own harmony unless the caller passes
+   * their own, so this reads the same grouping {@link Score.phrases} builds its
+   * phrases on rather than a second one that ignores where the music closes.
+   *
    * @param opts Analysis options; see {@link HypermeterOptions}.
    * @returns The grouping, its downbeats, a confidence, and a rationale.
    */
   hypermeter(opts) {
-    return hypermeter(this.#data.notes, this.#data.meters, opts);
+    return hypermeter(this.#data.notes, this.#data.meters, {
+      cadenceBeats: this.#cadenceBeats(),
+      ...opts
+    });
   }
   /**
    * The motifs the melody repeats.
@@ -4445,6 +4858,12 @@ var Score = class _Score {
    * A record is a cell, so `Motif.fromData(found)` reaches the
    * transformations without anything being rebuilt by hand.
    *
+   * 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
+   * score into lines first to have each of them answered for.
+   *
    * @param opts Cell-length bounds and the recurrence threshold; see
    *   {@link ExtractMotifsOptions}.
    * @returns The motifs found, longest first.
@@ -4467,7 +4886,15 @@ var Score = class _Score {
   motifs(opts) {
     return extractMotifs(this.#data.notes, opts);
   }
-  /** The shape the melody traces. */
+  /**
+   * The shape the melody traces.
+   *
+   * A contour is the shape of 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, which keeps a chord from being measured as a climb through
+   * its own notes. Split the score into lines first to have each of them
+   * answered for; {@link Score.voices} is what reads the polyphony as polyphony.
+   */
   contour() {
     return melodicContour(this.#data.notes);
   }
@@ -4481,12 +4908,19 @@ var Score = class _Score {
    * chord — reads every note against C major and no chord at all, which labels
    * the notes as the non-chord tones they are rather than failing.
    *
-   * @param key The key to read the notes in; defaults to the score's own.
+   * A score holds a whole piece rather than a single line, so the notes are read
+   * as the polyphony they are: each note is classified in its own voice, against
+   * everything else sounding under it. That is what a suspension needs — a
+   * dissonance is dissonant against something — and it is what keeps a note of
+   * one voice from being heard as the passing tone of another.
+   *
+   * @param key The key to read the notes in, as a key name, a plain key/scale,
+   *   or a {@link Key}; defaults to the score's own.
    * @returns One annotation per note, in the score's own time order.
    */
   voices(key) {
     const timeline = this.#chordTimeline();
-    return analyzeVoice(this.#data.notes, timeline.at, this.#keyContext(key));
+    return analyzePolyphony(this.#data.notes, timeline.at, this.#keyContext(key));
   }
   /**
    * The notes carrying the ids the voice analysis reports them back under.
@@ -4505,7 +4939,11 @@ var Score = class _Score {
   /**
    * Whether an instrument can play the score, and what makes it hard.
    *
-   * The tempo the third layer needs is the score's own, read at beat 0.
+   * The third layer asks how much time separates two notes, and the score
+   * answers it from its whole tempo map: a passage under an accelerando is
+   * judged at the tempo actually in force across it, the same integral
+   * {@link Score.secondsAt} reports. The beats the issues name are the score's
+   * own.
    *
    * @param instrument The instrument to play it on: a plain
    *   {@link InstrumentProfile} or an {@link Instrument}.
@@ -4520,11 +4958,33 @@ var Score = class _Score {
    * ```
    */
   playability(instrument) {
-    return playability(
-      this.#data.notes,
-      toInstrumentProfile(instrument),
-      tempoAt(0, this.#data.tempo)
-    );
+    const profile = toInstrumentProfile(instrument);
+    const tempo = this.#data.tempo;
+    const openingBpm = tempoAt(0, tempo);
+    if (tempo.length < 2) {
+      return playability(this.#data.notes, profile, openingBpm);
+    }
+    const played = tempoReader(tempo);
+    const evenly = tempoReader([{ startBeat: 0, bpm: openingBpm }]);
+    const restate = (beat) => evenly.beatAt(played.secondsAt(beat));
+    const scoreBeats = /* @__PURE__ */ new Map();
+    const evenlyPaced = this.#data.notes.map((note) => {
+      const startBeat = restate(note.startBeat);
+      scoreBeats.set(startBeat, note.startBeat);
+      return {
+        ...note,
+        startBeat,
+        durationBeat: restate(note.startBeat + note.durationBeat) - startBeat
+      };
+    });
+    const report = playability(evenlyPaced, profile, openingBpm);
+    return {
+      ...report,
+      issues: report.issues.map((issue) => ({
+        ...issue,
+        startBeat: scoreBeats.get(issue.startBeat) ?? issue.startBeat
+      }))
+    };
   }
   /**
    * An index for repeated lookups over the notes.
@@ -4622,24 +5082,64 @@ var Score = class _Score {
     return new _Score({ ...this.#data, notes: [...notes] });
   }
   /**
-   * The chord timeline the score's own harmony describes.
+   * The same context carrying another set of notes, with a carried key moved
+   * the same way the notes were.
+   *
+   * Every path that moves the pitches goes through here, so a score cannot come
+   * back sounding in one key and analysed in another.
+   */
+  #moved(notes, moveKey) {
+    const data = { ...this.#data, notes: [...notes] };
+    if (this.#key !== void 0) {
+      data.key = moveKey(this.#key).toJSON();
+    }
+    return new _Score(data);
+  }
+  /**
+   * The chord timeline the score's own harmony describes, read once.
    *
    * Private, because the options belong to the members that expose them: the
    * analyses that read harmony read the score's, and a caller who wants
-   * another builds it through {@link Score.timeline}.
+   * another builds it through {@link Score.timeline}. The reading is kept
+   * because a score is immutable and this takes no options: chord inference is
+   * the most expensive thing the class does, and the natural order — timeline,
+   * phrases, cadences, voices — would otherwise ask for it once per member.
    */
   #chordTimeline() {
-    return chordTimelineFromNotes(this.#data.notes, this.#analysisOptions()).timeline;
+    return this.#chordAnalysis().timeline;
+  }
+  /**
+   * The whole reading, not only the timeline it carries: the key regions and
+   * the per-segment confidence come from the same pass, and {@link
+   * Score.timeline} hands all three to the class it builds.
+   */
+  #chordAnalysis() {
+    const analysis = this.#chords ?? chordTimelineFromNotes(this.#data.notes, this.#analysisOptions());
+    this.#chords = analysis;
+    return analysis;
   }
-  /** The key regions under the score, read against its own meter. */
+  /**
+   * The key regions under the score: the key it was told it is in across the
+   * whole of it, or the ones read from the notes against its own meter.
+   *
+   * Kept on first reading for the same reason the chord timeline is.
+   */
   #keyRegions() {
-    return keyTimelineFromNotes(this.#data.notes, { meters: this.#data.meters });
+    const regions = this.#regions ?? (this.#key === void 0 ? keyTimelineFromNotes(this.#data.notes, { meters: this.#data.meters }) : statedKeyRegions(this.#key, this.#data.notes, this.totalBeats));
+    this.#regions = regions;
+    return regions;
+  }
+  /** Where the score's own harmony closes, as beats. */
+  #cadenceBeats() {
+    return detectCadences(this.#chordTimeline(), this.#keyContext(void 0)).map(
+      (hit) => hit.atBeat
+    );
   }
   /** The score's context as chord-timeline options, with the caller's on top. */
   #analysisOptions(opts) {
     return {
       meters: this.#data.meters,
-      ...this.#key === void 0 ? {} : { key: this.#key.scale },
+      ...this.#key === void 0 ? {} : { key: keyIdentity(this.#key) },
       ...opts
     };
   }
@@ -4648,15 +5148,17 @@ var Score = class _Score {
    * then the key in force at the beat, and C major where nothing sounds.
    */
   #keyContext(key) {
+    assertKeyArgument(key, "score key");
     if (key !== void 0) {
-      return toKeyScale(key);
+      return keyIdentity(toKey(key));
     }
     if (this.#key !== void 0) {
-      return this.#key.scale;
+      return keyIdentity(this.#key);
     }
     const regions = this.#keyRegions();
-    const prevailing = prevailingKeyOf(regions) ?? Key.major("C").scale;
-    return keyLookup(regions, prevailing);
+    const prevailing = prevailingKeyOf(regions) ?? keyIdentity(Key.major("C"));
+    const keyAt = keyLookup(regions, prevailing);
+    return (beat) => scaleOf(keyAt(beat));
   }
 };
 function sameNote(note, other) {
@@ -4678,52 +5180,31 @@ function sameKey(key, other) {
 }
 
 // src/model/arrangement.ts
-function copyPlain(value) {
-  if (Array.isArray(value)) {
-    return value.map((item) => copyPlain(item));
-  }
-  if (typeof value === "object" && value !== null) {
-    const copy = {};
-    for (const [key, item] of Object.entries(value)) {
-      copy[key] = copyPlain(item);
-    }
-    return copy;
-  }
-  return value;
-}
-function copyNote2(note, name) {
-  assertNoteEvent(note, name, { allowNonPositiveDuration: true });
-  return copyNoteEvent(note);
-}
-function copyNotes(notes, name) {
-  if (!Array.isArray(notes)) {
-    throw new InvalidInputError(`${name} must be an array; received ${typeof notes}`);
-  }
-  return notes.map((note, index) => {
-    if (note === void 0) {
-      throw new InvalidInputError(`${name}[${index}] must be a note event; received undefined`);
-    }
-    return copyNote2(note, `${name}[${index}]`);
-  });
+function copyNotes(notes, name, budget) {
+  return assertNoteEventArray(notes, name, { allowNonPositiveDuration: true, budget }).map(
+    copyNoteEvent
+  );
 }
-function copyTrack(track, index) {
-  if (track === void 0) {
-    throw new InvalidInputError(`tracks[${index}] must be a track; received undefined`);
-  }
-  const copy = { notes: copyNotes(track.notes, `tracks[${index}].notes`) };
+function copyTrack(track, index, budget) {
+  assertDataObject(track, `tracks[${index}]`);
+  const copy = {
+    notes: copyNotes(track.notes, `tracks[${index}].notes`, budget)
+  };
   if (track.name !== void 0) {
     copy.name = track.name;
   }
   if (track.role !== void 0) {
-    copy.role = track.role;
+    copy.role = trackRoleOf(track.role, `tracks[${index}].role`);
   }
   return copy;
 }
 function copyKeyRegions(keys) {
-  return [...new Timeline({ segments: [], totalBeats: 0, keys: [...keys] }).keys];
+  const given = assertDataObjects(keys, "arrangement keys");
+  return [...new Timeline({ segments: [], totalBeats: 0, keys: [...given] }).keys];
 }
 function copySegments(segments) {
-  return [...new Timeline({ segments: [...segments], totalBeats: spanEnd(segments) }).segments];
+  const given = assertDataObjects(segments, "arrangement timeline");
+  return [...new Timeline({ segments: [...given], totalBeats: spanEnd(given) }).segments];
 }
 function chordTimelineOf(segments) {
   return new Timeline({ segments: [...segments], totalBeats: spanEnd(segments) }).chordTimeline;
@@ -4732,16 +5213,17 @@ function copySettings(settings, trackCount) {
   if (settings === void 0) {
     return void 0;
   }
+  assertDataObject(settings, "arrangement settings");
   const copy = {};
   const meters = resolveMeters({ ts: settings.ts, meters: settings.meters }, "arrangement meters");
   if (settings.ts !== void 0) {
-    copy.ts = copyPlain(settings.ts);
+    copy.ts = copyPlain(toMeterData(settings.ts, "arrangement ts"), "arrangement ts");
   }
   if (settings.meters !== void 0) {
-    copy.meters = copyPlain(meters);
+    copy.meters = copyPlain(meters, "arrangement meters");
   }
   if (settings.key !== void 0) {
-    copy.key = toKeyScale(settings.key);
+    copy.key = resolveKey(settings.key);
   }
   if (settings.keys !== void 0) {
     copy.keys = copyKeyRegions(settings.keys);
@@ -4750,7 +5232,10 @@ function copySettings(settings, trackCount) {
     copy.timeline = copySegments(settings.timeline);
   }
   if (settings.harmonyTracks !== void 0) {
-    copy.harmonyTracks = settings.harmonyTracks.map(
+    copy.harmonyTracks = assertDataArray(
+      settings.harmonyTracks,
+      "arrangement harmonyTracks"
+    ).map(
       (track, index) => assertInteger(track, `arrangement harmonyTracks[${index}]`, 0, trackCount - 1)
     );
   }
@@ -4787,40 +5272,41 @@ function copySettings(settings, trackCount) {
   return Object.keys(copy).length === 0 ? void 0 : copy;
 }
 function copyArrangement(data) {
-  if (!Array.isArray(data.tracks)) {
-    throw new InvalidInputError(
-      `arrangement tracks must be an array; received ${typeof data.tracks}`
-    );
-  }
-  const tracks = data.tracks.map(copyTrack);
+  assertDataObject(data, "arrangement data");
+  const budget = data.settings?.budget;
+  const tracks = assertDataArray(data.tracks, "arrangement tracks").map(
+    (track, index) => copyTrack(track, index, budget)
+  );
   const settings = copySettings(data.settings, tracks.length);
   return settings === void 0 ? { tracks } : { tracks, settings };
 }
 function arrangementData(tracks, settings) {
-  const data = { tracks: [...tracks] };
+  const data = {
+    tracks: [...assertDataArray(tracks, "tracks")]
+  };
   if (settings !== void 0) {
     data.settings = settings;
   }
   return data;
 }
-function metersFrom2(meters) {
-  const meter = toMeterData(meters, "arrangement meters");
-  return Array.isArray(meter) ? resolveMeters({ meters: meter }, "arrangement meters") : resolveMeters({ ts: meter }, "arrangement meters");
-}
 function settingsFrom(setup) {
   if (setup === void 0) {
     return void 0;
   }
+  assertDataObject(setup, "arrangement options");
   const { key, meters, timeline, ...rest } = setup;
   const settings = { ...rest };
   if (key !== void 0) {
-    settings.key = toKeyScale(key);
+    settings.key = resolveKey(key);
   }
   if (meters !== void 0) {
-    settings.meters = metersFrom2(meters);
+    settings.meters = resolveMeters({ meters }, "arrangement meters");
   }
   if (timeline !== void 0) {
-    settings.timeline = [...timeline.segments];
+    assertDataObject(timeline, "arrangement timeline");
+    settings.timeline = [
+      ...assertDataArray(timeline.segments, "arrangement timeline segments")
+    ];
   }
   return settings;
 }
@@ -4828,13 +5314,14 @@ function analysisOptionsOf(setup) {
   if (setup === void 0) {
     return {};
   }
+  assertDataObject(setup, "arrangement options");
   const { key, meters, ...rest } = setup;
   const opts = { ...rest };
   if (key !== void 0) {
-    opts.key = toKeyScale(key);
+    opts.key = resolveKey(key);
   }
   if (meters !== void 0) {
-    opts.meters = metersFrom2(meters);
+    opts.meters = resolveMeters({ meters }, "arrangement meters");
   }
   return opts;
 }
@@ -4897,7 +5384,7 @@ var Arrangement = class _Arrangement {
   }
   /** The tracks as they were given, in that order. */
   get tracks() {
-    return copyPlain(this.#data.tracks);
+    return copyPlain(this.#data.tracks, "arrangement tracks");
   }
   /**
    * The reading of the whole arrangement: the key regions, the harmony, the
@@ -4907,7 +5394,7 @@ var Arrangement = class _Arrangement {
    */
   get analysis() {
     const { timeline, ...rest } = this.#session().analysis;
-    return { ...copyPlain(rest), timeline: this.timeline().chordTimeline };
+    return { ...copyPlain(rest, "arrangement analysis"), timeline: this.timeline().chordTimeline };
   }
   /**
    * The notes clashing with the harmony sounding beneath them, worst severity
@@ -4919,7 +5406,7 @@ var Arrangement = class _Arrangement {
    * labels to tell those apart.
    */
   get conflicts() {
-    return copyPlain(this.#session().analysis.conflicts);
+    return copyPlain(this.#session().analysis.conflicts, "arrangement conflicts");
   }
   /**
    * One track's notes as a score, or undefined when no track carries the name.
@@ -4976,7 +5463,7 @@ var Arrangement = class _Arrangement {
       }
       copied.push({
         trackIndex: edit.trackIndex,
-        notes: copyNotes(edit.notes, `edits[${index}].notes`)
+        notes: copyNotes(edit.notes, `edits[${index}].notes`, this.#data.settings?.budget)
       });
     }
     const session = this.#session().update(copied);
@@ -4991,6 +5478,10 @@ var Arrangement = class _Arrangement {
    * annotations describe the same chords rather than two readings of the same
    * notes.
    *
+   * Naming a key, its regions, or the tracks the harmony is read from asks for
+   * a harmony this arrangement did not find, so the curve is read under the one
+   * named rather than over the one it holds.
+   *
    * @param opts The sampling step, and any setting to lay over the
    *   arrangement's own; a meter named here replaces the arrangement's, since
    *   `ts` and `meters` name the same thing.
@@ -5057,7 +5548,7 @@ var Arrangement = class _Arrangement {
   }
   /** A copy of the underlying plain data. */
   get data() {
-    return copyPlain(this.#data);
+    return copyPlain(this.#data, "arrangement data");
   }
   /** The plain form of the arrangement, for `JSON.stringify`. */
   toJSON() {
@@ -5148,23 +5639,19 @@ function copyProfile(profile) {
   for (const [pitch, limbs] of Object.entries(profile.reach)) {
     reach[Number(pitch)] = [...limbs];
   }
-  return { kind: "percussion", ...common, limbs: [...profile.limbs], reach };
+  const percussion = {
+    kind: "percussion",
+    ...common,
+    limbs: [...profile.limbs],
+    reach
+  };
+  if (profile.overdub !== void 0) {
+    percussion.overdub = [...profile.overdub];
+  }
+  return percussion;
 }
 function checkedProfile(profile) {
-  const copy = copyProfile(toInstrumentProfile(profile));
-  assertPositiveInt(copy.polyphony, `${copy.name} polyphony`);
-  if (copy.kind === "stringed") {
-    for (const [index, open] of copy.tuning.entries()) {
-      assertInteger(open, `${copy.name} tuning[${index}]`);
-    }
-    assertInteger(copy.maxStretch, `${copy.name} maxStretch`, 0);
-  } else {
-    for (const pitch of Object.keys(copy.reach)) {
-      assertInteger(Number(pitch), `${copy.name} reach pitch`);
-    }
-  }
-  instrumentRange(copy);
-  return copy;
+  return copyProfile(toInstrumentProfile(profile));
 }
 var Instrument = class _Instrument {
   #profile;
@@ -5186,7 +5673,7 @@ var Instrument = class _Instrument {
    *   tuning, stretch or voice count that is not finite.
    * @example
    * ```ts
-   * import { GUITAR_DROP_D } from '../../src/core/index.js';
+   * import { GUITAR_DROP_D } from '@libraz/libcantus/core';
    * import { Instrument } from '@libraz/libcantus';
    * Instrument.of(GUITAR_DROP_D).range().low; // 38
    * ```
@@ -5288,7 +5775,7 @@ var Instrument = class _Instrument {
    * ```
    */
   range() {
-    return instrumentRange(this.#profile);
+    return rangeIn(this.#profile);
   }
   /**
    * Whether the instrument has this pitch at all.
@@ -5298,7 +5785,8 @@ var Instrument = class _Instrument {
    *   produces it.
    */
   canSound(pitch) {
-    return canSound(this.#profile, pitch);
+    assertMidiPitch(pitch, "pitch");
+    return soundsIn(this.#profile, pitch);
   }
   /**
    * Every position on the neck that sounds a pitch, lowest string first.
@@ -5312,15 +5800,17 @@ var Instrument = class _Instrument {
     if (profile.kind !== "stringed") {
       throw new InvalidInputError(`${profile.name} has no strings to finger`);
     }
-    return fingeringsFor(profile, pitch);
+    assertMidiPitch(pitch, "pitch");
+    return fingeringsIn(profile, pitch);
   }
   /**
    * Move a pitch by whole octaves until the instrument can sound it, which is
    * what a player does with a line written below the instrument.
    *
    * @param pitch MIDI pitch to place.
-   * @returns The nearest octave transposition the instrument sounds, searching
-   *   upward first; the pitch unchanged when no transposition is available.
+   * @returns The nearest octave transposition the instrument sounds, taking the
+   *   upper one when two are equally near; the pitch unchanged when no
+   *   transposition is available.
    * @example
    * ```ts
    * import { Instrument } from '@libraz/libcantus';
@@ -5328,7 +5818,8 @@ var Instrument = class _Instrument {
    * ```
    */
   foldIntoRange(pitch) {
-    return foldIntoRange(pitch, this.#profile);
+    assertMidiPitch(pitch, "pitch");
+    return foldIn(pitch, this.#profile);
   }
   /**
    * The pitch this instrument sounds for a note written in its part.
@@ -5407,7 +5898,7 @@ var Instrument = class _Instrument {
     if (a.kind === "stringed") {
       return b.kind === "stringed" && a.frets === b.frets && a.maxStretch === b.maxStretch && (a.fretless ?? false) === (b.fretless ?? false) && sameList(a.tuning, b.tuning);
     }
-    return b.kind === "percussion" && sameList(a.limbs, b.limbs) && sameReach(a.reach, b.reach);
+    return b.kind === "percussion" && sameList(a.limbs, b.limbs) && sameReach(a.reach, b.reach) && sameList(a.overdub ?? [], b.overdub ?? []);
   }
   /**
    * The plain profile, for JSON serialization.
@@ -5437,40 +5928,11 @@ var Instrument = class _Instrument {
 };
 
 // src/model/composer.ts
-var PROGRESSION_BAR_BEATS = 4;
-var DEFAULT_KEY = majorKey(0);
-function copyPlain2(value, name) {
-  if (typeof value === "number") {
-    return assertFiniteNumber(value, name);
-  }
-  if (Array.isArray(value)) {
-    return value.map((item, index) => copyPlain2(item, `${name}[${index}]`));
-  }
-  if (typeof value === "object" && value !== null) {
-    const copy = {};
-    for (const [key, item] of Object.entries(value)) {
-      if (item !== void 0) {
-        copy[key] = copyPlain2(item, `${name}.${key}`);
-      }
-    }
-    return copy;
-  }
-  if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
-    throw new InvalidInputError(`${name} must be plain data; received ${typeof value}`);
-  }
-  return value;
-}
 function toChordTimeline(harmony) {
   return "chordTimeline" in harmony ? harmony.chordTimeline : harmony;
 }
-function metersFrom3(meters) {
-  if (meters === void 0) {
-    return resolveMeters({}, "composer meters");
-  }
-  const meter = toMeterData(meters, "composer meters");
-  return Array.isArray(meter) ? resolveMeters({ meters: meter }, "composer meters") : resolveMeters({ ts: meter }, "composer meters");
-}
 function copyComplexity(complexity) {
+  assertDataObject(complexity, "composer complexity");
   const copy = {};
   for (const dial of ["rhythmic", "harmonic", "ornament", "difficulty"]) {
     const value = complexity[dial];
@@ -5481,6 +5943,7 @@ function copyComplexity(complexity) {
   return copy;
 }
 function copyInstruments(instruments) {
+  assertDataObject(instruments, "composer instruments");
   const copy = {};
   for (const [part, profile] of Object.entries(instruments)) {
     copy[part] = Instrument.of(profile).data;
@@ -5488,9 +5951,12 @@ function copyInstruments(instruments) {
   return copy;
 }
 function copyOptions(options) {
-  const copy = { meters: metersFrom3(options.meters) };
+  assertDataObject(options, "composer options");
+  const copy = {
+    meters: resolveMeters({ meters: options.meters }, "composer meters")
+  };
   if (options.key !== void 0) {
-    copy.key = toKeyScale(options.key);
+    copy.key = resolveKey(options.key);
   }
   if (options.bpm !== void 0) {
     copy.bpm = options.bpm;
@@ -5498,6 +5964,9 @@ function copyOptions(options) {
   if (options.seed !== void 0) {
     copy.seed = options.seed;
   }
+  if (options.algorithmVersion !== void 0) {
+    copy.algorithmVersion = options.algorithmVersion;
+  }
   if (options.complexity !== void 0) {
     copy.complexity = copyComplexity(options.complexity);
   }
@@ -5505,10 +5974,17 @@ function copyOptions(options) {
     copy.instruments = copyInstruments(options.instruments);
   }
   if (options.vocabulary !== void 0) {
-    copy.vocabulary = options.vocabulary.map(
-      (entry, index) => copyPlain2(entry, `composer vocabulary[${index}]`)
-    );
+    copy.vocabulary = assertDataObjects(
+      options.vocabulary,
+      "composer vocabulary"
+    ).map((entry, index) => copyPlain(entry, `composer vocabulary[${index}]`));
   }
+  if (options.rng !== void 0) {
+    copy.rng = options.rng;
+  }
+  const resolved = resolveContext(contextOf(copy));
+  copy.seed = resolved.seed;
+  copy.algorithmVersion = resolved.algorithmVersion;
   return copy;
 }
 function contextOf(options) {
@@ -5516,6 +5992,12 @@ function contextOf(options) {
   if (options.seed !== void 0) {
     ctx.seed = options.seed;
   }
+  if (options.algorithmVersion !== void 0) {
+    ctx.algorithmVersion = options.algorithmVersion;
+  }
+  if (options.rng !== void 0) {
+    ctx.rng = options.rng;
+  }
   if (options.bpm !== void 0) {
     ctx.bpm = options.bpm;
   }
@@ -5526,7 +6008,10 @@ function contextOf(options) {
     ctx.instruments = copyInstruments(options.instruments);
   }
   if (options.vocabulary !== void 0) {
-    ctx.vocabulary = options.vocabulary.map((entry) => copyPlain2(entry, "composer vocabulary"));
+    ctx.vocabulary = assertDataObjects(
+      options.vocabulary,
+      "composer vocabulary"
+    ).map((entry, index) => copyPlain(entry, `composer vocabulary[${index}]`));
   }
   return ctx;
 }
@@ -5554,9 +6039,8 @@ var Composer = class _Composer {
    */
   constructor(options) {
     this.#options = copyOptions(options);
-    resolveContext(contextOf(this.#options));
-    this.#meters = metersFrom3(this.#options.meters);
-    this.#key = this.#options.key === void 0 ? void 0 : toKeyScale(this.#options.key);
+    this.#meters = resolveMeters({ meters: this.#options.meters }, "composer meters");
+    this.#key = this.#options.key === void 0 ? void 0 : resolveKey(this.#options.key);
   }
   /**
    * Start from a set of settings.
@@ -5594,18 +6078,27 @@ var Composer = class _Composer {
   /**
    * A chord progression, in time.
    *
-   * The chords are laid out one per four-beat bar, which is the grid
-   * {@link generateProgression} writes on whatever meter the composer holds, so
-   * the timeline spans `bars` of four beats and carries the composer's key.
+   * The chords are laid out one per bar of the composer's own meter, so a chord
+   * change falls on a bar line of the piece and the timeline spans `bars` of it:
+   * four beats each in 4/4, three in 3/4, and three in 6/8. Every other part is
+   * written against that grid, and harmony that is not on it drifts further from
+   * the bar line with every repeat.
    *
-   * @param opts Everything the progression generator takes but the key and the
-   *   context, which are the composer's.
+   * @param opts Everything the progression generator takes but the key, the
+   *   meter and the context, which are the composer's.
    * @returns The chords over the beats they sound for.
+   * @throws If the composer names no key: the chords are degrees of one, and
+   *   there is no melody here to read a key from the way
+   *   {@link Composer.harmonize} does.
+   * @throws If the composer's meter changes: one chord per bar has no single bar
+   *   length to be laid out on, and the chords would leave the bar lines at the
+   *   first change rather than follow them.
    */
   progression(opts) {
-    const key = this.#keyScale();
-    const chords = generateProgression({ ...opts, key, ctx: this.context });
-    return Timeline.fromChords(chords, opts.bars * PROGRESSION_BAR_BEATS, key);
+    const key = this.#requireKey("progression");
+    const ts = this.#unchangingMeter("progression");
+    const chords = generateProgression({ ...opts, key, ts, ctx: this.context });
+    return Timeline.fromChords(chords, opts.bars * beatsPerBar(ts), key);
   }
   /**
    * A drum part.
@@ -5618,11 +6111,13 @@ var Composer = class _Composer {
    * @param opts Everything the drum generator takes but the meter and the
    *   context, which are the composer's.
    * @returns The hits, as a score.
-   * @throws If the composer's meter is not 4/4, which is the only meter the
-   *   drum patterns are written against.
+   * @throws If the composer's meter is not 4/4 throughout, which is the only
+   *   meter the drum patterns are written against: a piece that opens in 4/4
+   *   and changes later has bars the patterns cannot be laid out on, so the
+   *   request is refused rather than answered with 4/4 bars over the change.
    */
   drums(opts) {
-    const hits = generateDrums({ ...opts, ts: this.#openingMeter(), ctx: this.context });
+    const hits = generateDrums({ ...opts, ts: this.#unchangingMeter("drums"), ctx: this.context });
     return Score.of(hits, this.#scoreOptions());
   }
   /**
@@ -5633,6 +6128,8 @@ var Composer = class _Composer {
    * @param opts Everything the bass generator takes but the segments, the key,
    *   the meter and the context; see {@link BassLineSettings}.
    * @returns The line, as a score in the composer's key.
+   * @throws If the composer names no key: the line is written in one, and a
+   *   default key would put the part in a key the caller never asked for.
    * @throws If the instrument names a kit, which has no strings for a bass line
    *   to be placed on.
    * @example
@@ -5645,7 +6142,7 @@ var Composer = class _Composer {
    */
   bass(source, opts) {
     const segments = Array.isArray(source) ? source : source.segments;
-    const key = this.#keyScale();
+    const key = this.#requireKey("bass");
     const { instrument, ...rest } = opts ?? {};
     const notes = generateBassLine({
       ...rest,
@@ -5672,9 +6169,12 @@ var Composer = class _Composer {
    * @param opts Everything the counter-melody generator takes but the melody,
    *   the key, the meter and the context; see {@link CounterMelodySettings}.
    * @returns The counter line, as a score in the composer's key.
+   * @throws If the composer names no key: the line is written in one, and the
+   *   melody it answers is not read for a key here — {@link Composer.harmonize}
+   *   is the member that does that.
    */
   counterMelody(melody, opts) {
-    const key = this.#keyScale();
+    const key = this.#requireKey("counterMelody");
     const { timeline, ...rest } = opts ?? {};
     const notes = generateCounterMelody({
       ...rest,
@@ -5700,8 +6200,7 @@ var Composer = class _Composer {
    *   that melody and the one handed in.
    * @example
    * ```ts
-   * import { Composer } from '@libraz/libcantus';
-   * import { Score } from '../../src/model/score.js';
+   * import { Composer, Score } from '@libraz/libcantus';
    * const composer = Composer.of({ key: 'C major' });
    * const melody = Score.of([{ pitch: 60, startBeat: 0, durationBeat: 4 }]);
    * composer.harmonize(melody).transposeSemitones; // 0
@@ -5733,29 +6232,59 @@ var Composer = class _Composer {
    * Whether another composer holds the same settings.
    *
    * The comparison is made through the other composer's public data, so two
-   * composers built by different copies of the module still compare.
+   * composers built by different copies of the module still compare. Both sides
+   * are projected the same way: comparing the settings held here against the
+   * data the other hands out answered "different" for a composer holding a
+   * source and "same" for two that draw from different ones.
+   *
+   * A source is compared by identity, being a handle on a stream rather than a
+   * setting: two composers drawing from different sources write different
+   * parts, and the numbers a source will hand out cannot be read from it.
    *
    * @param other The composer to compare.
    * @returns True when both would generate the same parts.
    */
   equals(other) {
-    return samePlain(this.#options, other.data);
+    return samePlain(this.data, other.data) && this.context.rng === other.context.rng;
   }
   /** The resolved context, for handing back to the function API. */
   get context() {
     return contextOf(this.#options);
   }
-  /** A copy of the settings this composer holds. */
+  /**
+   * A copy of the settings this composer holds: the seed, the resolved
+   * algorithm version and the rest of the recipe, so a piece can be written
+   * again from what a project file stored.
+   *
+   * The source a composer was handed is left out, being a live handle rather
+   * than plain data; a composer built with one keeps it across
+   * {@link Composer.with} and its siblings.
+   */
   get data() {
-    return copyOptions(this.#options);
+    return copyOptions({ ...this.#options, rng: void 0 });
   }
   /** The plain form of the settings, for `JSON.stringify`. */
   toJSON() {
     return this.data;
   }
-  /** The key the parts are written in; C major where the composer names none. */
-  #keyScale() {
-    return this.#key ?? DEFAULT_KEY;
+  /**
+   * The key a pitched part is written in.
+   *
+   * A composer that names none is refused rather than written in C major: a
+   * default key is an answer the caller never gave, and the part would come
+   * back sounding like a piece nobody asked for with nothing to say it had
+   * been substituted. {@link Composer.harmonize} is the one member that can
+   * answer without a key, because it has a melody to read one from; the key it
+   * found comes back with the harmonization, and `with({ key })` is how it is
+   * handed to the parts written next.
+   */
+  #requireKey(part) {
+    if (this.#key === void 0) {
+      throw new InvalidInputError(
+        `composer ${part} needs a key for the part it writes; the composer names none \u2014 give it one, or take the key harmonize reads off a melody and pass it on with with({ key })`
+      );
+    }
+    return this.#key;
   }
   /**
    * The signature the parts are written against.
@@ -5767,6 +6296,22 @@ var Composer = class _Composer {
   #openingMeter() {
     return meterAt(0, this.#meters);
   }
+  /**
+   * The one signature a part laid out in bars is written against.
+   *
+   * A part that places material bar by bar has to know how long a bar is, and a
+   * piece that changes meter has no one answer: the request is refused rather
+   * than answered on the bar the piece opens in, which would put every bar after
+   * the change somewhere the piece has no bar line.
+   */
+  #unchangingMeter(part) {
+    if (this.#meters.length > 1) {
+      throw new InvalidInputError(
+        `composer ${part} needs one meter for the whole part; the composer changes meter`
+      );
+    }
+    return this.#openingMeter();
+  }
   /** The context every score a composer hands back is read against. */
   #scoreOptions(key) {
     const opts = { meters: this.#meters };
@@ -6072,7 +6617,7 @@ var Meter = class _Meter {
   get beatsPerBar() {
     return beatsPerBar(this.#ts);
   }
-  /** Main pulses (felt beats) in a bar: 3 in 6/8, 4 in 4/4. */
+  /** Main pulses (felt beats) in a bar: 2 in 6/8, 4 in 4/4. */
   get pulsesPerBar() {
     return pulsesPerBar(this.#ts);
   }
@@ -6088,13 +6633,19 @@ var Meter = class _Meter {
    * additive grouping and one is asked for.
    *
    * @param opts Set `grouping: true` to render an additive grouping. A
-   *   grouping counted in main pulses cannot be written additively and falls
-   *   back to the plain form.
+   *   grouping counted in main pulses has no additive spelling: one whose
+   *   groups are all the same length states the division the bare signature
+   *   already has and falls back to the plain form, and one whose groups differ
+   *   is refused rather than printed as a bar that weighs its pulses otherwise.
    * @returns The formatted signature.
+   * @throws If `grouping: true` is asked of a grouping that no signature text
+   *   can spell: one counted in main pulses, on a compound numerator, whose
+   *   groups are not all the same length — 12/8 as `[1, 1, 2]`.
    * @example
    * ```ts
    * import { Meter } from '@libraz/libcantus';
    * Meter.of(7, 8, [2, 2, 3]).format({ grouping: true }); // '2+2+3/8'
+   * Meter.of(12, 8, [1, 1, 1, 1]).format({ grouping: true }); // '12/8'
    * ```
    */
   format(opts = {}) {
@@ -6140,13 +6691,18 @@ var Meter = class _Meter {
    *
    * @param beatInQuarters Position in quarter-note beats.
    * @param decimals Digits of the fractional beat to keep.
-   * @returns The formatted position, e.g. `'3.2'` for bar 3, felt beat 2.
+   * @returns The formatted position in one of two forms: `bar.beat` on a felt
+   *   beat, e.g. `'3.2'` for bar 3, felt beat 2; and `bar.beat+fraction`
+   *   between felt beats, e.g. `'3.2+0.5'` halfway from the second felt beat to
+   *   the third. A reader of these strings has to take both, since most onsets
+   *   of an ordinary piece fall between pulses.
    * @throws If the position is not finite or `decimals` is not an integer in
    *   0..100.
    * @example
    * ```ts
    * import { Meter } from '@libraz/libcantus';
    * Meter.parse('6/8').formatPosition(7.5); // '3.2'
+   * Meter.parse('6/8').formatPosition(8.25); // '3.2+0.5'
    * ```
    */
   formatPosition(beatInQuarters, decimals = 2) {
@@ -6207,7 +6763,7 @@ var Meter = class _Meter {
 };
 
 // src/model/motif.ts
-function copyNote3(note) {
+function copyNote2(note) {
   return {
     pitch: withoutNegativeZero(note.pitch),
     startBeat: withoutNegativeZero(note.startBeat),
@@ -6215,17 +6771,8 @@ function copyNote3(note) {
   };
 }
 function copyCell(cell) {
-  if (!Array.isArray(cell.notes)) {
-    throw new InvalidInputError(`motif notes must be an array; received ${typeof cell.notes}`);
-  }
-  return {
-    notes: cell.notes.map((note, index) => {
-      if (note === void 0) {
-        throw new InvalidInputError(`motif notes[${index}] must be a note; received undefined`);
-      }
-      return copyNote3(assertNoteEvent(note, `motif notes[${index}]`));
-    })
-  };
+  assertDataObject(cell, "motif cell");
+  return { notes: assertNoteEventArray(cell.notes, "motif notes").map(copyNote2) };
 }
 function chordFrom(chord) {
   return chord === void 0 || chord === null ? chord : toChordData(chord);
@@ -6260,9 +6807,7 @@ var Motif = class _Motif {
    * ```
    */
   static generate(opts) {
-    return new _Motif(
-      generateMotif({ ...opts, key: toKeyScale(opts.key), chord: chordFrom(opts.chord) })
-    );
+    return new _Motif(generateMotif({ ...opts, chord: chordFrom(opts.chord) }));
   }
   /**
    * Read a run of notes as a motif.
@@ -6288,30 +6833,29 @@ var Motif = class _Motif {
   }
   /** The notes of the cell, in the order the transforms read them. */
   get notes() {
-    return this.#cell.notes.map(copyNote3);
+    return this.#cell.notes.map(copyNote2);
   }
   /** Where the cell stops sounding, measured from its own first onset. */
   get totalBeats() {
-    if (this.#cell.notes.length === 0) {
-      return 0;
-    }
-    const start = Math.min(...this.#cell.notes.map((note) => note.startBeat));
-    const end = Math.max(...this.#cell.notes.map((note) => note.startBeat + note.durationBeat));
-    return end - start;
+    return cellSpan(this.#cell);
   }
   /** A copy of the underlying plain cell. */
   get data() {
-    return { notes: this.#cell.notes.map(copyNote3) };
+    return { notes: this.#cell.notes.map(copyNote2) };
   }
   /**
    * The cell put through one of the classical transformations.
    *
-   * `invert` reflects the pitches about the first note and `retrograde` mirrors
-   * the onsets about the cell's span, both self-inverse; `augment` and
+   * `invert` reflects the pitches about the earliest note and `retrograde`
+   * mirrors the onsets about the cell's span, both self-inverse; `augment` and
    * `diminish` scale the note values by `amount` and its reciprocal;
    * `transposeChromatic` moves by semitones; `transposeDiatonic` and `sequence`
    * move by scale degrees with a key in hand, and by semitones without one.
    *
+   * The result's notes run in time order whichever way the source cell was
+   * written, so an inversion of a retrograde reflects about the note that now
+   * sounds first.
+   *
    * @param kind The transformation.
    * @param amount Semitones, scale degrees, or the time factor, as the
    *   transformation reads it.
@@ -6330,9 +6874,7 @@ var Motif = class _Motif {
    * ```
    */
   transform(kind, amount, key) {
-    return new _Motif(
-      transformMotif(this.#cell, kind, amount, key === void 0 ? void 0 : toKeyScale(key))
-    );
+    return new _Motif(transformMotif(this.#cell, kind, amount, key));
   }
   /**
    * The cell laid across a span and snapped to the harmony under it.
@@ -6345,29 +6887,30 @@ var Motif = class _Motif {
    *   plain chord timeline the analysis layer hands out.
    * @param key The key the passing notes are kept in.
    * @param bars How many bars to fill.
-   * @param ts Meter the bars are counted in; 4/4 when none is named.
+   * @param ts Meter the bars are counted in, in any form that names one. A
+   *   motif carries no meter of its own — it is a run of notes — so there is
+   *   nothing to fall back on, and a development laid on the wrong bar length
+   *   drifts off the part it plays under.
    * @returns The developed motif.
    * @throws If the bar count is not a positive integer.
    */
   develop(timeline, key, bars, ts) {
     const chords = "chordTimeline" in timeline ? timeline.chordTimeline : timeline;
-    return new _Motif(developMotif(this.#cell, chords, toKeyScale(key), bars, ts));
+    return new _Motif(developMotif(this.#cell, chords, key, bars, ts));
   }
   /**
    * How this motif stands to another: the transformation that turns one into
    * the other, named.
    *
    * @param other The statement to name against this one.
-   * @param key Key context for the tonal reading; without it, an answer that
-   *   only holds diatonically is not recognised.
+   * @param key Key context for the tonal reading. Without one an answer holding
+   *   only diatonically is left unnamed unless its interval pattern also fits
+   *   the retrograde family, in which case it is named there; a motif carries no
+   *   key of its own, so this is the only way to have the tonal reading offered.
    * @returns The relation, or null when the two stand in none.
    */
   relateTo(other, key) {
-    return relateMotifs(
-      motifFromNotes(this.#cell.notes),
-      motifFromNotes(other.notes),
-      key === void 0 ? void 0 : toKeyScale(key)
-    );
+    return relateMotifs(motifFromNotes(this.#cell.notes), motifFromNotes(other.notes), key);
   }
   /**
    * How alike two lines are, in [0, 1].
@@ -6418,7 +6961,6 @@ function sameNote2(note, other) {
 }
 
 // src/model/rhythm.ts
-var DEFAULT_TS = { numerator: 4, denominator: 4 };
 var GRID_VELOCITY = 1;
 var PART = "rhythm";
 function copyEvent(event, name) {
@@ -6432,17 +6974,10 @@ function copyEvent(event, name) {
   };
 }
 function copyEvents(events, name) {
-  if (!Array.isArray(events)) {
-    throw new InvalidInputError(`${name} must be an array; received ${typeof events}`);
-  }
-  return events.map((event, index) => {
-    if (event === void 0) {
-      throw new InvalidInputError(`${name}[${index}] must be an onset; received undefined`);
-    }
-    return copyEvent(event, `${name}[${index}]`);
-  }).sort((a, b) => a.position - b.position || a.duration - b.duration);
+  return assertDataObjects(events, name).map((event, index) => copyEvent(event, `${name}[${index}]`)).sort((a, b) => a.position - b.position || a.duration - b.duration);
 }
 function copyRhythm(data) {
+  assertDataObject(data, "rhythm data");
   return {
     events: copyEvents(data.events, "rhythm events"),
     ts: copyTimeSignature(data.ts, "rhythm ts")
@@ -6482,16 +7017,16 @@ var Rhythm = class _Rhythm {
   /**
    * Generate a pattern over a meter.
    *
-   * @param ts The time signature the bars are counted in.
+   * @param ts The time signature the bars are counted in, in any form that
+   *   names one; a meter map is read as the signature it opens in.
    * @param opts Length, grid resolution and the context; see
    *   {@link RhythmOptions}. The context's `complexity.rhythmic` is the onset
    *   density, and its `seed` fixes which grid slots are taken.
    * @returns The generated pattern.
    * @example
    * ```ts
-   * import { parseTimeSignature } from '@libraz/libcantus';
    * import { Rhythm } from '@libraz/libcantus';
-   * const rhythm = Rhythm.generate(parseTimeSignature('4/4'), {
+   * const rhythm = Rhythm.generate('4/4', {
    *   bars: 2,
    *   ctx: { seed: 7, complexity: { rhythmic: 0.6 } },
    * });
@@ -6499,18 +7034,29 @@ var Rhythm = class _Rhythm {
    * ```
    */
   static generate(ts, opts) {
-    return new _Rhythm({ events: generateRhythm(ts, opts), ts });
+    const meter = meterAt(0, toMeterData(ts, "ts"));
+    return new _Rhythm({ events: generateRhythm(meter, opts), ts: meter });
   }
   /**
    * Build a pattern from onsets that already exist.
    *
+   * The meter is asked for rather than assumed. A pattern in 6/8 read as 4/4
+   * answers every metric question — which beats are strong, where the bars
+   * fall, how dense it is — on the wrong pulse, and nothing downstream can tell
+   * that reading from a meter the caller meant. Its two siblings,
+   * {@link Rhythm.generate} and `generateRhythm`, ask for it the same way.
+   *
    * @param events The onsets, in any order.
-   * @param ts The meter they are counted in; 4/4 when none is named, as every
-   *   meter-aware function in the library assumes.
+   * @param ts The meter they are counted in, in any form that names one.
    * @returns The pattern.
+   * @throws If the meter names no signature, or an onset carries a value a
+   *   pattern cannot hold.
    */
-  static of(events, ts = DEFAULT_TS) {
-    return new _Rhythm({ events: [...events], ts });
+  static of(events, ts) {
+    return new _Rhythm({
+      events: [...assertDataArray(events, "rhythm events")],
+      ts: meterAt(0, toMeterData(ts, "ts"))
+    });
   }
   /** Rebuild a pattern from the plain data {@link Rhythm.data} hands out. */
   static fromData(data) {
@@ -6550,19 +7096,26 @@ var Rhythm = class _Rhythm {
   /**
    * Drop the onsets carrying the least of the metre.
    *
+   * The metre is the pattern's own: the ranks are read from {@link Rhythm.ts},
+   * so a pattern in 6/8 keeps its dotted-quarter pulses and one in 3/4 keeps its
+   * three-beat downbeats rather than the beats a four-beat bar would have.
+   *
    * @param amount How much to thin, in [0, 1]; at 0 nothing goes, and a full
    *   turn leaves the downbeats alone.
    * @returns The thinned pattern.
    * @throws If the amount is outside [0, 1].
    */
   thin(amount) {
-    return this.#withGrid(thin(toGrid(this.#data.events), amount));
+    return this.#withGrid(thin(toGrid(this.#data.events), amount, this.#data.ts));
   }
   /**
    * Anticipate beats, one sixteenth early.
    *
-   * The anticipations are added rather than displaced, so raising the amount
-   * only ever adds onsets and the ones already sounding stay where they are.
+   * The beats anticipated are the ones {@link Rhythm.ts} counts as main pulses
+   * or stronger, so a pattern is not syncopated against accents its own meter
+   * does not have. The anticipations are added rather than displaced, so raising
+   * the amount only ever adds onsets and the ones already sounding stay where
+   * they are.
    *
    * @param amount How much syncopation, in [0, 1].
    * @param ctx The context, or the seed alone; it fixes which beats are
@@ -6572,7 +7125,11 @@ var Rhythm = class _Rhythm {
    */
   syncopate(amount, ctx) {
     return this.#withGrid(
-      syncopate(toGrid(this.#data.events), amount, resolveContext(ctx).part(PART))
+      syncopate(
+        toGrid(this.#data.events),
+        { amount, ts: this.#data.ts },
+        resolveContext(ctx).part(PART)
+      )
     );
   }
   /**
@@ -6642,6 +7199,7 @@ var Rhythm = class _Rhythm {
       ornament: resolved.ornament,
       rate: opts?.rate,
       spanSteps: this.#spanSteps(),
+      ts: this.#data.ts,
       // The transform hands the predicate the events it was given, which carry
       // the onset each was built from; the parameter is declared over the bare
       // grid event the rule reads, so the field is named back here.
@@ -6674,7 +7232,9 @@ var Rhythm = class _Rhythm {
    * @param pitch The MIDI pitch to give every onset.
    * @param velocity Velocity for every onset; a mezzo-forte 96 by default.
    * @returns The score holding the pattern.
-   * @throws If the pitch is not finite or the velocity is outside [0, 127].
+   * @throws If the pitch or the velocity is not a whole MIDI value in [0, 127];
+   *   both are the numbers a note event carries, and a fractional one is not a
+   *   note anything downstream can sound.
    * @example
    * ```ts
    * import { parseTimeSignature } from '@libraz/libcantus';
@@ -6729,10 +7289,11 @@ function sameSignature(ts, other) {
 
 // src/model/tempo.ts
 var MAX_BPM = 1e3;
+var MIN_BPM = 0.1;
 var Tempo = class _Tempo {
   #bpm;
   constructor(bpm) {
-    this.#bpm = assertRange(bpm, Number.MIN_VALUE, MAX_BPM, "bpm");
+    this.#bpm = assertRange(bpm, MIN_BPM, MAX_BPM, "bpm");
   }
   /**
    * The one-event tempo map every conversion here is measured against.
@@ -6761,7 +7322,7 @@ var Tempo = class _Tempo {
    * @throws If the marking is not a positive, finite number the library holds.
    */
   static fromData(data) {
-    return new _Tempo(data.bpm);
+    return new _Tempo(assertDataObject(data, "tempo data").bpm);
   }
   /**
    * Rebuild a tempo from its {@link Tempo.toJSON} output.
@@ -6771,7 +7332,7 @@ var Tempo = class _Tempo {
    * @throws If the marking is not a positive, finite number the library holds.
    */
   static fromJSON(data) {
-    return new _Tempo(data.bpm);
+    return new _Tempo(assertDataObject(data, "tempo data").bpm);
   }
   /** Quarter-note beats per minute. */
   get bpm() {
@@ -6885,23 +7446,29 @@ var Tuning = class _Tuning {
   /**
    * Wrap a plain tuning table.
    *
-   * The table is checked the way {@link Tuning.edo} checks its arguments, so a
-   * deserialized or hand-written one cannot enter carrying a division count or
-   * a reference frequency no frequency follows from.
+   * Every field is read off the table, so a deserialized or hand-written one
+   * cannot enter carrying a division count or a reference frequency no
+   * frequency follows from. None of the three has a default here, unlike
+   * {@link Tuning.edo}: a table that lost its reference frequency on the way
+   * through storage is refused rather than quietly retuned to A=440.
    *
    * @param table The plain tuning table.
    * @returns The wrapped tuning.
-   * @throws If the divisions are not a positive integer, or the reference step
-   *   or frequency is not a finite positive number.
+   * @throws If a field is missing, the divisions are not a positive integer,
+   *   the reference frequency is not a finite positive number, or the reference
+   *   step is not finite.
    * @example
    * ```ts
-   * import { TWELVE_TET } from '../../src/core/tuning/index.js';
-   * import { Tuning } from '@libraz/libcantus';
+   * import { TWELVE_TET, Tuning } from '@libraz/libcantus';
    * Tuning.of(TWELVE_TET).divisions; // 12
    * ```
    */
   static of(table) {
-    return new _Tuning(edo(table.divisions, table.refFreq, table.refStep));
+    const given = assertDataObject(table, "tuning table");
+    assertFiniteNumber(given.divisions, "tuning table.divisions");
+    assertFiniteNumber(given.refFreq, "tuning table.refFreq");
+    assertFiniteNumber(given.refStep, "tuning table.refStep");
+    return new _Tuning(edo(given.divisions, given.refFreq, given.refStep));
   }
   /**
    * Build an equal temperament with `divisions` divisions of the octave.
@@ -6911,8 +7478,10 @@ var Tuning = class _Tuning {
    * @param refStep Step index of the reference; 69 by default, the MIDI number
    *   of A4.
    * @returns The tuning.
-   * @throws If the divisions are not a positive integer, or the reference step
-   *   or frequency is not a finite positive number.
+   * @throws If the divisions are not a positive integer, the reference
+   *   frequency is not a finite positive number, or the reference step is not
+   *   finite. A negative or fractional reference step is accepted: it is what a
+   *   tuner reading or a pitch-bend calibration lands on.
    * @example
    * ```ts
    * import { Tuning } from '@libraz/libcantus';
@@ -6981,7 +7550,8 @@ var Tuning = class _Tuning {
    *
    * @param cents The interval in cents.
    * @returns The frequency ratio.
-   * @throws If `cents` is not finite.
+   * @throws If `cents` is not finite, or the ratio it spans falls outside the
+   *   range a number holds.
    * @example
    * ```ts
    * import { Tuning } from '@libraz/libcantus';
@@ -7219,20 +7789,34 @@ var Tuning = class _Tuning {
 
 // src/model/voicing.ts
 function copyPitches(pitches) {
+  assertDataArray(pitches, "voicing pitches");
   if (pitches.length === 0) {
     throw new InvalidInputError("a voicing must contain at least one pitch");
   }
   return pitches.map((pitch, index) => assertMidiPitch(pitch, `pitches[${index}]`));
 }
 function spellLine(line, key) {
-  const { tonic } = spelledKeyOf(key);
   return line.map(
-    (value) => typeof value === "number" ? spellPitch(value, tonic, key) : toNoteData(value)
+    (value) => typeof value === "number" ? spellPitch(value, key.tonic, key) : toNoteData(value)
   );
 }
 function lineOf(pitches, key) {
   return key === void 0 ? pitches.map((pitch) => toNoteData(pitch)) : spellLine(pitches, key);
 }
+function carriedKeyOf(chord) {
+  if (typeof chord !== "object" || chord === null) {
+    return void 0;
+  }
+  const key = chord.key;
+  return typeof key === "object" && key !== null ? key : void 0;
+}
+function withCarriedKey(chord, opts) {
+  if (opts?.key !== void 0) {
+    return opts;
+  }
+  const key = carriedKeyOf(chord);
+  return key === void 0 ? opts : { ...opts, key };
+}
 var Voicing = class _Voicing {
   #pitches;
   /**
@@ -7273,7 +7857,7 @@ var Voicing = class _Voicing {
    * ```
    */
   static forChord(chord, opts) {
-    return new _Voicing(voiceChordStyled(toChordData(chord), opts));
+    return new _Voicing(voiceChordStyled(chord, opts));
   }
   /**
    * Realize a chord as one pitch per voice inside the voice ranges, defaulting
@@ -7282,6 +7866,10 @@ var Voicing = class _Voicing {
    * The bass takes the chord's slash bass when it has one, otherwise the root;
    * the result is compact, centred in its ranges, and free of voice crossing.
    *
+   * A chord that carries a key passes it to the voicer, so the leading tone is
+   * not doubled; an explicit `opts.key` overrides it. That is the order
+   * {@link Chord.voice} resolves them in, and the two answer alike.
+   *
    * @param chord A chord symbol, plain chord data, or a {@link Chord}.
    * @param opts Voicing options; defaults to four voices in {@link SATB_RANGES}.
    * @returns The voicing, ascending.
@@ -7293,7 +7881,7 @@ var Voicing = class _Voicing {
    * ```
    */
   static satb(chord, opts) {
-    return new _Voicing(voiceChord(toChordData(chord), opts));
+    return new _Voicing(voiceChord(toChordData(chord), withCarriedKey(chord, opts)));
   }
   /**
    * Wrap a plain pitch array, as {@link Voicing.data} hands it out.
@@ -7353,7 +7941,7 @@ var Voicing = class _Voicing {
    * @param key A key name, a plain key/scale, or a {@link Key}.
    * @param chord The chord sounding, supplying the enharmonic evidence; without
    *   it the key alone decides.
-   * @returns One spelled note per pitch, ascending.
+   * @returns One spelled note per pitch, in voice order.
    * @throws If the value names no key or no chord.
    * @example
    * ```ts
@@ -7363,7 +7951,8 @@ var Voicing = class _Voicing {
    * ```
    */
   spell(key, chord) {
-    return this.#spelled(toKeyScale(key), chord).map((note) => new Note(note));
+    assertKeyArgument(key, "voicing key");
+    return this.#spelled(resolveKey(key), chord).map((note) => new Note(note));
   }
   /**
    * Voice a chord to follow smoothly from this voicing.
@@ -7372,7 +7961,13 @@ var Voicing = class _Voicing {
    * `voices` nor `ranges` is given — within a one-octave window around each of
    * these pitches, so the answer keeps this voicing's voice count. Each is
    * scored by structural quality, motion from here, and a large penalty per
-   * counterpoint violation.
+   * counterpoint violation. A chord that carries a key passes it to the voicer
+   * unless `opts.key` names another one.
+   *
+   * The rules read from the chord being left — a chordal seventh's resolution,
+   * a leading tone's resolution, and the cross relation between the two chords
+   * — are scored only when `opts.previousChord` names that chord: a voicing
+   * does not say what it was written on.
    *
    * @param chord A chord symbol, plain chord data, or a {@link Chord}.
    * @param opts Voicing options; when omitted, the ranges follow this voicing.
@@ -7387,12 +7982,12 @@ var Voicing = class _Voicing {
    * ```
    */
   next(chord, opts) {
-    return new _Voicing(nextVoicing(this.pitches, toChordData(chord), opts));
+    return new _Voicing(nextVoicing(this.pitches, toChordData(chord), withCarriedKey(chord, opts)));
   }
   /**
    * The voice-leading cost from this voicing to another: the summed absolute
-   * semitone motion across voices, plus a penalty when the outer voices reach a
-   * perfect fifth or octave by similar motion.
+   * semitone motion across voices, and nothing besides. What the motion breaks
+   * is {@link Voicing.checkTo}'s question.
    *
    * @param other The voicing moved to.
    * @returns The cost, or `Infinity` when the two hold a different number of
@@ -7429,14 +8024,15 @@ var Voicing = class _Voicing {
    * ```
    */
   checkTo(other, chords, key, opts) {
-    const scale = toKeyScale(key);
+    assertKeyArgument(key, "voicing key");
+    const resolved = resolveKey(key);
     const from = toChordData(chords[0]);
     const to = toChordData(chords[1]);
     const voicings = [
-      spellVoicing(this.pitches, from, scale),
-      spellVoicing(other.pitches, to, scale)
+      spellVoicing(this.pitches, from, resolved),
+      spellVoicing(other.pitches, to, resolved)
     ];
-    return checkPartWriting(voicings, [from, to], scale, opts);
+    return checkPartWriting(voicings, [from, to], resolved, opts);
   }
   /**
    * Mark this voicing, read as a written counterpoint line, against a cantus
@@ -7465,12 +8061,13 @@ var Voicing = class _Voicing {
    * ```
    */
   species(cantusFirmus, species, mode, opts) {
-    const scale = toKeyScale(mode);
+    assertKeyArgument(mode, "voicing mode");
+    const resolved = resolveKey(mode);
     return checkSpecies(
-      spellLine(cantusFirmus, scale),
-      spellLine(this.#pitches, scale),
+      spellLine(cantusFirmus, resolved),
+      spellLine(this.#pitches, resolved),
       species,
-      scale,
+      resolved,
       opts
     );
   }
@@ -7492,8 +8089,12 @@ var Voicing = class _Voicing {
    */
   independence(other, opts) {
     const { key, ...rest } = opts ?? {};
-    const scale = key === void 0 ? void 0 : toKeyScale(key);
-    return voiceIndependence(lineOf(this.#pitches, scale), lineOf(other.pitches, scale), rest);
+    const resolved = key === void 0 ? void 0 : resolveKey(key);
+    return voiceIndependence(
+      lineOf(this.#pitches, resolved),
+      lineOf(other.pitches, resolved),
+      rest
+    );
   }
   /**
    * Judge a candidate pitch placed against these voices.
@@ -7505,7 +8106,8 @@ var Voicing = class _Voicing {
    * @param pitch The candidate MIDI pitch.
    * @param query The candidate's harmonic and voice-leading context.
    * @param opts Set `suggestions: false` to skip the search for safe
-   *   replacements when the verdict is not safe.
+   *   replacements when the verdict is not safe, and `partners: true` to learn
+   *   which voice of this voicing, by index, raised each pairwise flag.
    * @returns The verdict, reason bitmask, and optional resolution guidance.
    * @throws If the profile is unknown, a value names no chord or key, or a
    *   pitch is not a MIDI pitch in 0..127.
@@ -7541,13 +8143,14 @@ var Voicing = class _Voicing {
    * times over.
    *
    * A negative `n` takes the highest voice down an octave as many times, and
-   * `invert(0)` is the voicing itself. Unlike {@link Chord.invert}, which
-   * rotates a chord's interval template, this moves real voices: inverting a
-   * four-voice texture four times leaves the same chord an octave higher. The
-   * result is ascending, since the voice that moved is no longer where it was.
+   * `invert(0)` is the voicing itself, voice order and all. Unlike
+   * {@link Chord.invert}, which rotates a chord's interval template, this moves
+   * real voices: inverting a four-voice texture four times leaves the same chord
+   * an octave higher. A voicing that actually inverts comes back ascending,
+   * since the voice that moved is no longer where it was.
    *
    * @param n How many voices to move, upward when positive.
-   * @returns The inverted voicing, ascending.
+   * @returns The inverted voicing, ascending; this voicing itself when `n` is 0.
    * @throws If `n` is not an integer in [-128, 128], or a voice would leave
    *   MIDI 0..127.
    * @example
@@ -7558,6 +8161,9 @@ var Voicing = class _Voicing {
    */
   invert(n) {
     assertInteger(n, "voicing inversion", -128, 128);
+    if (n === 0) {
+      return this;
+    }
     const pitches = [...this.#pitches].sort((a, b) => a - b);
     for (let moved = 0; moved < Math.abs(n); moved += 1) {
       const index = n > 0 ? 0 : pitches.length - 1;
@@ -7587,7 +8193,7 @@ var Voicing = class _Voicing {
    * Private class fields do not serialize, so an explicit `toJSON` keeps
    * `JSON.stringify(voicing)` from collapsing to `{}`.
    *
-   * @returns A copy of the sounding MIDI pitches, ascending.
+   * @returns A copy of the sounding MIDI pitches, in voice order.
    */
   toJSON() {
     return [...this.#pitches];
@@ -7596,7 +8202,7 @@ var Voicing = class _Voicing {
    * The pitches separated by spaces, so a template literal or a log line reads
    * as the voicing.
    *
-   * @returns The pitches ascending, e.g. `'60 64 67'`.
+   * @returns The pitches in voice order, e.g. `'60 64 67'`.
    */
   toString() {
     return this.#pitches.join(" ");
@@ -7615,7 +8221,7 @@ var Voicing = class _Voicing {
     return {
       profile: query.profile,
       chord: query.chord === null ? null : toChordData(query.chord),
-      key: toKeyScale(query.key),
+      key: resolveKey(query.key).scale,
       otherVoices,
       strongBeat: query.strongBeat,
       prevPitch: query.prevPitch,
@@ -7644,4 +8250,4 @@ export {
   Tuning,
   Voicing
 };
-//# sourceMappingURL=chunk-PKFNUHDY.js.map
+//# sourceMappingURL=chunk-FBH75DAY.js.map