@libraz/libcantus 0.9.0 → 0.9.2

package/src/{chord → theory/chord}/index.ts

@@ -1,7 +1,11 @@
+import type { KeyScale } from '../../core/types.js';
 import { scaleTonesInDegreeOrder } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
 
-/** Chord quality identifiers understood by the chord builder. */
+/**
+ * Chord quality identifiers understood by the chord builder.
+ *
+ * @category Chords
+ */
 export type ChordQuality =
   | 'maj'
   | 'min'
@@ -34,12 +38,54 @@ export type ChordQuality =
   | '13'
   | '5';
 
-/** A chord expressed as a root pitch class plus semitone offsets. */
+/**
+ * A bare spelled pitch used as an enharmonic hint: a diatonic letter
+ * (0..6 = C..B) plus a chromatic alteration (-2 double-flat .. +2 double-sharp).
+ * Mirrors the letter/alter half of the pitch module's `Note` without an octave.
+ *
+ * @category Chords
+ */
+export type PitchSpelling = {
+  letter: number;
+  alter: number;
+};
+
+/**
+ * A chord expressed as a root pitch class plus semitone offsets.
+ *
+ * `rootSpelling`/`bassSpelling` are optional enharmonic hints recorded by
+ * parsers (e.g. `parseChordSymbol('Bb7')`) so formatters can reproduce the
+ * original spelling instead of defaulting to sharps. Consumers may ignore
+ * them; a hint is only trusted when its pitch class still matches the
+ * corresponding `rootPc`/`bassPc`.
+ *
+ * @category Chords
+ */
 export type Chord = {
   rootPc: number;
   quality: ChordQuality;
   intervals: number[];
   bassPc?: number;
+  rootSpelling?: PitchSpelling;
+  bassSpelling?: PitchSpelling;
+};
+
+/**
+ * A chord positioned in time: a root pitch class and quality placed at a beat,
+ * with optional harmonic-analysis hints. Serves as the neutral exchange record
+ * between progression generators and timeline analysers.
+ *
+ * @category Composition
+ */
+export type ChordSpan = {
+  rootPc: number;
+  quality: ChordQuality;
+  startBeat: number;
+  bassPc?: number;
+  /** 0-based scale degree of the chord root, when known. */
+  degree?: number;
+  /** True when the chord is a secondary dominant tonicizing another degree. */
+  secondaryDominant?: boolean;
 };
 
 /** Semitone offsets from the root for each supported chord quality. */
@@ -81,7 +127,11 @@ function pitchClass(value: number): number {
   return ((Math.trunc(value) % 12) + 12) % 12;
 }
 
-/** All chord qualities the builder understands, longest templates last. */
+/**
+ * All chord qualities the builder understands, longest templates last.
+ *
+ * @category Chords
+ */
 export function chordQualities(): ChordQuality[] {
   return Object.keys(QUALITY_INTERVALS) as ChordQuality[];
 }
@@ -97,6 +147,8 @@ export function chordQualities(): ChordQuality[] {
  * @param ext Chord quality to apply.
  * @param key Key context supplying the diatonic root.
  * @returns The constructed chord.
+ *
+ * @category Chords
  */
 export function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScale): Chord {
   const tones = scaleTonesInDegreeOrder(key);
@@ -113,6 +165,15 @@ export function chordFromDegree(degree: number, ext: ChordQuality, key: KeyScale
  * @param quality Chord quality supplying the interval template.
  * @param bassPc Optional slash-chord bass pitch class.
  * @returns The constructed chord.
+ *
+ * @example
+ * ```ts
+ * import { makeChord } from '@libraz/libcantus';
+ * const cmaj7 = makeChord(0, 'maj7');
+ * // { rootPc: 0, quality: 'maj7', intervals: [0, 4, 7, 11] }
+ * ```
+ *
+ * @category Chords
  */
 export function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number): Chord {
   const chord: Chord = {
@@ -131,6 +192,14 @@ export function makeChord(rootPc: number, quality: ChordQuality, bassPc?: number
  *
  * @param chord The chord to enumerate.
  * @returns The chord's pitch classes, sorted ascending in [0, 11].
+ *
+ * @example
+ * ```ts
+ * import { makeChord, chordPitchClasses } from '@libraz/libcantus';
+ * chordPitchClasses(makeChord(0, 'maj7')); // [0, 4, 7, 11]
+ * ```
+ *
+ * @category Chords
  */
 export function chordPitchClasses(chord: Chord): number[] {
   const set = new Set<number>();
@@ -156,6 +225,8 @@ function chordToneOffsets(chord: Chord): Set<number> {
  * @param pitch MIDI pitch or bare pitch class.
  * @param chord The chord providing the root reference.
  * @returns The chord-tone role, or null if the pitch has no basic role.
+ *
+ * @category Chords
  */
 export function chordToneRole(
   pitch: number,
@@ -275,6 +346,14 @@ function stackThirds(degree: number, key: KeyScale, size: 3 | 4): Chord {
  * @param degree 0-based scale degree of the chord root.
  * @param key Key/scale context.
  * @returns The diatonic triad.
+ *
+ * @example
+ * ```ts
+ * import { majorKey, diatonicTriad } from '@libraz/libcantus';
+ * const tonic = diatonicTriad(0, majorKey(0)); // C major triad (degree 0 of C major)
+ * ```
+ *
+ * @category Chords
  */
 export function diatonicTriad(degree: number, key: KeyScale): Chord {
   return stackThirds(degree, key, 3);
@@ -286,6 +365,8 @@ export function diatonicTriad(degree: number, key: KeyScale): Chord {
  * @param degree 0-based scale degree of the chord root.
  * @param key Key/scale context.
  * @returns The diatonic seventh chord.
+ *
+ * @category Chords
  */
 export function diatonicSeventh(degree: number, key: KeyScale): Chord {
   return stackThirds(degree, key, 4);

package/src/{chordscale → theory/chordscale}/index.ts

@@ -29,6 +29,8 @@ function maskHasPitchClass(mask: number, scaleRootPc: number, pc: number): boole
  * @param scaleMask The scale's 12-bit mode mask.
  * @param scaleRootPc The pitch class the mask is rooted on.
  * @returns True if the scale is a superset of the chord.
+ *
+ * @category Scales
  */
 export function scaleMatchesChord(
   chordPcs: number[],
@@ -43,37 +45,67 @@ export function scaleMatchesChord(
   return true;
 }
 
-/** A named scale rooted on a pitch class that fits over a chord. */
+/**
+ * A named scale rooted on a pitch class that fits over a chord.
+ *
+ * @category Scales
+ */
 export type ChordScaleMatch = {
   name: string;
   rootPc: number;
 };
 
+/**
+ * Scale names whose mask duplicates another {@link NAMED_SCALES} entry
+ * (major/ionian, naturalMinor/aeolian). Chord-scale analysis conventionally
+ * speaks in mode names, so these aliases are skipped and only the modal name
+ * is reported.
+ */
+const ALIASED_SCALE_NAMES = new Set(['major', 'naturalMinor']);
+
+/** Number of tones in a heptatonic (seven-note) scale. */
+const HEPTATONIC_SIZE = 7;
+
 /**
  * List the scales that fit over a chord, best fit first.
  *
  * Only the chord root is considered as the scale root, matching the
  * conventional chord-scale relationship. Every entry of {@link NAMED_SCALES}
- * whose pitch-class set is a superset of the chord's is returned, ranked by
- * fewest extra scale tones beyond the chord, then by scale size (heptatonic
- * before larger scales), then by scale name. The chromatic scale is only
- * returned as a fallback when no other scale contains the chord.
+ * whose pitch-class set is a superset of the chord's is returned once per
+ * distinct pitch-class set (aliased masks such as major/ionian report only the
+ * modal name), ranked by fewest extra scale tones beyond the chord, then by
+ * scale size (heptatonic before larger scales), then by scale name. For bare
+ * triads and smaller chords, heptatonic scales rank before pentatonics and
+ * other sizes: a pentatonic adds no modal color over a triad, so the seven-note
+ * modes are the more useful answer. The chromatic scale is only returned as a
+ * fallback when no other scale contains the chord.
  *
  * @param chord The chord to fit scales over.
  * @returns The matching scales rooted on the chord root, best fit first.
+ *
+ * @example
+ * ```ts
+ * import { makeChord, chordScales } from '@libraz/libcantus';
+ * const scales = chordScales(makeChord(0, 'maj7'));
+ * // scales for Cmaj7, best fit first; each is { name, rootPc: 0 }
+ * ```
+ *
+ * @category Scales
  */
 export function chordScales(chord: Chord): ChordScaleMatch[] {
   const chordPcs = chordPitchClasses(chord);
   const rootPc = pitchClass(chord.rootPc);
   const ranked: { name: string; extra: number; size: number }[] = [];
+  const seenMasks = new Set<number>();
   for (const name of Object.keys(NAMED_SCALES)) {
-    if (name === 'chromatic') {
+    if (name === 'chromatic' || ALIASED_SCALE_NAMES.has(name)) {
       continue;
     }
     const mask = NAMED_SCALES[name];
-    if (mask === undefined) {
+    if (mask === undefined || seenMasks.has(mask)) {
       continue;
     }
+    seenMasks.add(mask);
     if (scaleMatchesChord(chordPcs, mask, rootPc)) {
       const size = popcount12(mask);
       ranked.push({ name, extra: size - chordPcs.length, size });
@@ -87,7 +119,11 @@ export function chordScales(chord: Chord): ChordScaleMatch[] {
     }
     return [];
   }
+  const preferHeptatonic = chordPcs.length <= 3;
   ranked.sort((a, b) => {
+    if (preferHeptatonic && (a.size === HEPTATONIC_SIZE) !== (b.size === HEPTATONIC_SIZE)) {
+      return a.size === HEPTATONIC_SIZE ? -1 : 1;
+    }
     if (a.extra !== b.extra) {
       return a.extra - b.extra;
     }
@@ -109,6 +145,8 @@ export function chordScales(chord: Chord): ChordScaleMatch[] {
  * @param chord The chord providing the chord tones.
  * @param scaleName A key of {@link NAMED_SCALES}.
  * @returns The avoid-note pitch classes, sorted ascending in [0, 11].
+ *
+ * @category Scales
  */
 export function avoidNotes(chord: Chord, scaleName: string): number[] {
   const mask = NAMED_SCALES[scaleName];
@@ -144,6 +182,14 @@ export function avoidNotes(chord: Chord, scaleName: string): number[] {
  * @param chord The chord providing the chord tones.
  * @param scaleName A key of {@link NAMED_SCALES}.
  * @returns The available-tension pitch classes, sorted ascending in [0, 11].
+ *
+ * @example
+ * ```ts
+ * import { makeChord, availableTensions } from '@libraz/libcantus';
+ * availableTensions(makeChord(0, 'maj7'), 'ionian'); // [2, 9] — color tones over Cmaj7
+ * ```
+ *
+ * @category Scales
  */
 export function availableTensions(chord: Chord, scaleName: string): number[] {
   const mask = NAMED_SCALES[scaleName];
@@ -167,7 +213,11 @@ export function availableTensions(chord: Chord, scaleName: string): number[] {
   return tensions.sort((a, b) => a - b);
 }
 
-/** A scale fit over a chord together with its avoid notes and tensions. */
+/**
+ * A scale fit over a chord together with its avoid notes and tensions.
+ *
+ * @category Scales
+ */
 export type ChordScaleReportEntry = {
   name: string;
   rootPc: number;
@@ -184,6 +234,8 @@ export type ChordScaleReportEntry = {
  * @param chord The chord to analyze.
  * @param limit Optional maximum number of scales to report; all by default.
  * @returns One entry per reported scale, best fit first.
+ *
+ * @category Scales
  */
 export function chordScaleReport(chord: Chord, limit?: number): ChordScaleReportEntry[] {
   const matches = chordScales(chord);
@@ -196,7 +248,11 @@ export function chordScaleReport(chord: Chord, limit?: number): ChordScaleReport
   }));
 }
 
-/** A chord paired with the scale chosen for it by {@link scalesForChanges}. */
+/**
+ * A chord paired with the scale chosen for it by {@link scalesForChanges}.
+ *
+ * @category Scales
+ */
 export type ScaleChoice = {
   chord: Chord;
   scale: ChordScaleMatch;
@@ -251,6 +307,8 @@ function symmetricDifferenceSize(a: Set<number>, b: Set<number>): number {
  *
  * @param chords The chord sequence to choose scales for.
  * @returns One scale choice per chord, in input order.
+ *
+ * @category Scales
  */
 export function scalesForChanges(chords: Chord[]): ScaleChoice[] {
   if (chords.length === 0) {

package/src/{counterpoint → theory/counterpoint}/index.ts

@@ -1,5 +1,5 @@
-import { isConsonantInterval } from '../interval/index.js';
-import type { KeyScale } from '../types.js';
+import { isConsonantInterval } from '../../core/interval/index.js';
+import type { KeyScale } from '../../core/types.js';
 
 /** Reduce a MIDI pitch (or pitch class) to a pitch class in [0, 11]. */
 function pitchClass(pitch: number): number {
@@ -12,6 +12,7 @@ function pitchClass(pitch: number): number {
  * @param upperPitch Pitch of the nominally higher voice.
  * @param lowerPitch Pitch of the nominally lower voice.
  * @returns True when the upper voice sits below the lower voice.
+ * @category Voicing & Counterpoint
  */
 export function createsVoiceCrossing(upperPitch: number, lowerPitch: number): boolean {
   return upperPitch < lowerPitch;
@@ -24,6 +25,7 @@ export function createsVoiceCrossing(upperPitch: number, lowerPitch: number): bo
  * @param b Second pitch.
  * @param twoVoice When true, the perfect fourth counts as dissonant.
  * @returns True when the vertical interval is dissonant.
+ * @category Voicing & Counterpoint
  */
 export function createsVerticalDissonance(a: number, b: number, twoVoice: boolean): boolean {
   return !isConsonantInterval(a - b, twoVoice);
@@ -39,6 +41,7 @@ export function createsVerticalDissonance(a: number, b: number, twoVoice: boolea
  * @param prev Starting pitch.
  * @param cur Ending pitch.
  * @returns True when the leap is forbidden in strict counterpoint.
+ * @category Voicing & Counterpoint
  */
 export function isForbiddenMelodicLeap(prev: number, cur: number): boolean {
   const semis = Math.abs(cur - prev);
@@ -78,6 +81,8 @@ function bothVoicesMove(aMove: number, bMove: number): boolean {
  * A fifth expanding to a twelfth counts (same perfect class); a fifth moving to
  * an octave does not (different perfect kinds — the direct/hidden case owned by
  * {@link createsHiddenParallelPerfect}).
+ *
+ * @category Voicing & Counterpoint
  */
 export function createsParallelPerfect(
   aPrev: number,
@@ -96,6 +101,15 @@ export function createsParallelPerfect(
 /**
  * Whether two voices move in consecutive parallel octaves (or unisons) by
  * similar motion.
+ *
+ * This is a strict subset of {@link createsParallelPerfect}: a similar-motion
+ * octave-to-octave is the perfect-class-zero case that predicate already flags
+ * (and it additionally catches the contrary-motion anti-parallel). Callers that
+ * tally parallel violations should therefore use {@link createsParallelPerfect}
+ * alone to avoid double counting; this predicate remains for callers wanting a
+ * dedicated similar-motion octave test.
+ *
+ * @category Voicing & Counterpoint
  */
 export function createsParallelOctave(
   aPrev: number,
@@ -112,6 +126,8 @@ export function createsParallelOctave(
 /**
  * Whether two voices move in consecutive parallel unisons — both landing on the
  * same pitch, having shared a pitch on the previous move.
+ *
+ * @category Voicing & Counterpoint
  */
 export function createsParallelUnison(
   aPrev: number,
@@ -132,6 +148,8 @@ export function createsParallelUnison(
  * The traditional step exception is applied: the approach is allowed when the
  * upper of the two voices moves by step, so only leaps into the perfect
  * interval are flagged.
+ *
+ * @category Voicing & Counterpoint
  */
 export function createsHiddenParallelPerfect(
   aPrev: number,
@@ -168,6 +186,7 @@ export function createsHiddenParallelPerfect(
  * @param upperCur Current pitch of the upper voice.
  * @param lowerPrev Previous pitch of the lower voice.
  * @param lowerCur Current pitch of the lower voice.
+ * @category Voicing & Counterpoint
  */
 export function createsVoiceOverlap(
   upperPrev: number,
@@ -186,6 +205,7 @@ export function createsVoiceOverlap(
  * @param upperPitch Pitch of the higher voice.
  * @param lowerPitch Pitch of the lower voice.
  * @param maxSemitones Maximum allowed spacing in semitones (default an octave).
+ * @category Voicing & Counterpoint
  */
 export function exceedsSpacing(upperPitch: number, lowerPitch: number, maxSemitones = 12): boolean {
   return Math.abs(upperPitch - lowerPitch) > maxSemitones;
@@ -198,6 +218,7 @@ export function exceedsSpacing(upperPitch: number, lowerPitch: number, maxSemito
  * @param cur The following pitch.
  * @param key Key context supplying the tonic.
  * @returns True when `prev` is the leading tone and `cur` is the tonic a step above.
+ * @category Voicing & Counterpoint
  */
 export function isLeadingToneResolution(prev: number, cur: number, key: KeyScale): boolean {
   const tonic = pitchClass(key.rootPc);

package/src/{harmony → theory/harmony}/index.ts

@@ -1,6 +1,10 @@
 import type { Chord } from '../chord/index.js';
 
-/** Harmonic role a pitch plays within a chord. */
+/**
+ * Harmonic role a pitch plays within a chord.
+ *
+ * @category Functional Harmony
+ */
 export type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'tension' | 'doubling';
 
 /**
@@ -9,10 +13,16 @@ export type HarmonyRole = 'root' | 'third' | 'fifth' | 'sixth' | 'seventh' | 'te
  * - `identity`: moving it produces a different chord (the root).
  * - `quality`: moving it flips the chord quality (the third).
  * - `voicing`: it can move freely without changing chord identity or quality.
+ *
+ * @category Functional Harmony
  */
 export type LockLevel = 'identity' | 'quality' | 'voicing';
 
-/** A pitch's role, lock level, and owning chord. */
+/**
+ * A pitch's role, lock level, and owning chord.
+ *
+ * @category Functional Harmony
+ */
 export type VoicedRole = {
   role: HarmonyRole;
   lock: LockLevel;
@@ -36,6 +46,13 @@ export type VoicedRole = {
  * @param chord The chord providing the root reference.
  * @param chordId Identifier stored on the result (defaults to 0).
  * @returns The pitch's role, lock level, and owning chord id.
+ * @example
+ * ```ts
+ * import { roleOf, makeChord } from '@libraz/libcantus';
+ * roleOf(64, makeChord(0, 'maj')); // E over C major
+ * // { role: 'third', lock: 'quality', belongsToChordId: 0 }
+ * ```
+ * @category Functional Harmony
  */
 export function roleOf(pitch: number, chord: Chord, chordId = 0): VoicedRole {
   const interval = (((Math.trunc(pitch) - chord.rootPc) % 12) + 12) % 12;

package/src/theory/index.ts

@@ -0,0 +1,107 @@
+/**
+ * Public API of the theory layer. Re-exports every theory-layer module;
+ * also available from the package root.
+ */
+export type { Chord as ChordData, ChordQuality } from './chord/index.js';
+export {
+  chordFromDegree,
+  chordPitchClasses,
+  chordQualities,
+  chordToneRole,
+  diatonicSeventh,
+  diatonicTriad,
+  makeChord,
+} from './chord/index.js';
+export type {
+  ChordScaleMatch,
+  ChordScaleReportEntry,
+  ScaleChoice,
+} from './chordscale/index.js';
+export {
+  availableTensions,
+  avoidNotes,
+  chordScaleReport,
+  chordScales,
+  scaleMatchesChord,
+  scalesForChanges,
+} from './chordscale/index.js';
+export {
+  createsHiddenParallelPerfect,
+  createsParallelOctave,
+  createsParallelPerfect,
+  createsParallelUnison,
+  createsVerticalDissonance,
+  createsVoiceCrossing,
+  createsVoiceOverlap,
+  exceedsSpacing,
+  isForbiddenMelodicLeap,
+  isLeadingToneResolution,
+} from './counterpoint/index.js';
+export type { HarmonyRole, LockLevel, VoicedRole } from './harmony/index.js';
+export { roleOf } from './harmony/index.js';
+export type {
+  SafetyProfile,
+  SafetyQuery,
+  SafetyResult,
+  VoiceSnapshot,
+} from './safety/index.js';
+export {
+  enumerateSafePitches,
+  evaluateSafety,
+  NoteSafety,
+  ReasonFlag,
+} from './safety/index.js';
+export {
+  BLUES_MASK,
+  CHROMATIC_MASK,
+  DORIAN_MASK,
+  diatonicPitchClasses,
+  HARMONIC_MINOR_MASK,
+  isScaleTone,
+  LOCRIAN_MASK,
+  LYDIAN_MASK,
+  MAJOR_MASK,
+  MAJOR_PENTATONIC_MASK,
+  MELODIC_MINOR_MASK,
+  MINOR_PENTATONIC_MASK,
+  MIXOLYDIAN_MASK,
+  majorKey,
+  maskFromOffsets,
+  minorKey,
+  NAMED_SCALES,
+  NATURAL_MINOR_MASK,
+  nearestScaleTone,
+  OCTATONIC_HALF_WHOLE_MASK,
+  OCTATONIC_WHOLE_HALF_MASK,
+  PHRYGIAN_MASK,
+  pitchToScaleDegree,
+  scaleByName,
+  scaleTonesInDegreeOrder,
+  WHOLE_TONE_MASK,
+} from './scale/index.js';
+export {
+  noteNames,
+  spellChord,
+  spellPitchClass,
+  spellPitchClasses,
+  spellScale,
+} from './spelling/index.js';
+export {
+  formatChordSymbol,
+  parseChordSymbol,
+  transposeChordSymbol,
+} from './symbol/index.js';
+export type {
+  StyledVoicingOptions,
+  VoiceRange,
+  VoicingOptions,
+  VoicingStyle,
+} from './voicing/index.js';
+export {
+  nextVoicing,
+  SATB_RANGES,
+  voiceChord,
+  voiceChordStyled,
+  voiceLeadingCost,
+  voiceProgression,
+} from './voicing/index.js';

package/src/{safety → theory/safety}/index.ts

@@ -1,26 +1,37 @@
+import type { KeyScale } from '../../core/types.js';
 import type { Chord } from '../chord/index.js';
 import { chordPitchClasses } from '../chord/index.js';
 import {
   createsHiddenParallelPerfect,
-  createsParallelOctave,
   createsParallelPerfect,
   createsVerticalDissonance,
   isForbiddenMelodicLeap,
 } from '../counterpoint/index.js';
 import { isScaleTone } from '../scale/index.js';
-import type { KeyScale } from '../types.js';
 
-/** Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading. */
+/**
+ * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
+ *
+ * @category Arrangement & Analysis
+ */
 export type SafetyProfile = 'strict' | 'pop';
 
-/** Overall placeability verdict for a candidate pitch. */
+/**
+ * Overall placeability verdict for a candidate pitch.
+ *
+ * @category Arrangement & Analysis
+ */
 export enum NoteSafety {
   Safe = 0,
   Warning = 1,
   Dissonant = 2,
 }
 
-/** Bit flags describing why a pitch received its verdict. */
+/**
+ * Bit flags describing why a pitch received its verdict.
+ *
+ * @category Arrangement & Analysis
+ */
 export enum ReasonFlag {
   ChordTone = 1 << 0,
   Tension = 1 << 1,
@@ -40,13 +51,21 @@ export enum ReasonFlag {
   NeedsResolution = 1 << 15,
 }
 
-/** A neighbouring voice's current and previous pitch. */
+/**
+ * A neighbouring voice's current and previous pitch.
+ *
+ * @category Arrangement & Analysis
+ */
 export type VoiceSnapshot = {
   pitch: number;
   prevPitch?: number;
 };
 
-/** Everything needed to evaluate one candidate pitch. */
+/**
+ * Everything needed to evaluate one candidate pitch.
+ *
+ * @category Arrangement & Analysis
+ */
 export type SafetyQuery = {
   profile: SafetyProfile;
   candidatePitch: number;
@@ -59,7 +78,11 @@ export type SafetyQuery = {
   vocalHigh?: number;
 };
 
-/** The verdict, reason flags, and optional resolution guidance. */
+/**
+ * The verdict, reason flags, and optional resolution guidance.
+ *
+ * @category Arrangement & Analysis
+ */
 export type SafetyResult = {
   safety: NoteSafety;
   reasons: number;
@@ -115,6 +138,20 @@ function stepResolution(pitch: number, chord: Chord): number | undefined {
  *
  * @param q The candidate and its harmonic/voice-leading context.
  * @returns The verdict, reason bitmask, and optional resolution guidance.
+ * @example
+ * ```ts
+ * import { evaluateSafety, makeChord, majorKey, NoteSafety } from '@libraz/libcantus';
+ * const result = evaluateSafety({
+ *   profile: 'pop',
+ *   candidatePitch: 60, // C over a C major chord
+ *   chord: makeChord(0, 'maj'),
+ *   key: majorKey(0),
+ *   otherVoices: [],
+ *   strongBeat: true,
+ * });
+ * result.safety === NoteSafety.Safe; // true — C is a chord tone
+ * ```
+ * @category Arrangement & Analysis
  */
 export function evaluateSafety(q: SafetyQuery): SafetyResult {
   return evaluateInternal(q, true);
@@ -242,10 +279,9 @@ function evaluateInternal(q: SafetyQuery, collectSuggestions: boolean): SafetyRe
       if (ov.prevPitch === undefined) {
         continue;
       }
-      if (
-        createsParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch) ||
-        createsParallelOctave(prev, pitch, ov.prevPitch, ov.pitch)
-      ) {
+      // createsParallelPerfect covers every perfect class (unison/octave and
+      // fifth), so no separate octave check is needed.
+      if (createsParallelPerfect(prev, pitch, ov.prevPitch, ov.pitch)) {
         reasons |= ReasonFlag.ParallelPerfect;
         raise(parallelSeverity);
       }
@@ -346,6 +382,17 @@ function describe(reasons: number, q: SafetyQuery): string {
  * @param pitchLow Lowest MIDI pitch to consider (inclusive).
  * @param pitchHigh Highest MIDI pitch to consider (inclusive).
  * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
+ * @example
+ * ```ts
+ * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';
+ * const pitches = enumerateSafePitches(
+ *   { profile: 'pop', chord: makeChord(0, 'maj'), key: majorKey(0), otherVoices: [], strongBeat: true },
+ *   60,
+ *   72,
+ * );
+ * pitches; // placeable pitches in [60, 72], chord tones first, each group descending
+ * ```
+ * @category Arrangement & Analysis
  */
 export function enumerateSafePitches(
   q: Omit<SafetyQuery, 'candidatePitch'>,