@leafo/lml 0.1.1 → 0.3.0

package/dist/song.d.ts

@@ -1,50 +1,255 @@
+import { type ChordShapeName } from "./music.js";
+/**
+ * Represents a single musical note with pitch, timing, and duration.
+ * @example
+ * const note = new SongNote("C4", 0, 1) // Middle C at beat 0, duration 1 beat
+ * const note2 = new SongNote("D#5", 4, 0.5) // D#5 at beat 4, half beat duration
+ */
 export declare class SongNote {
+    /** Unique identifier for this note instance */
     id: symbol;
+    /** Note name with octave (e.g., "C4", "D#5", "Bb3") */
     note: string;
+    /** Start position in beats */
     start: number;
+    /** Duration in beats */
     duration: number;
-    constructor(note: string, start: number, duration: number);
+    /** Source location in LML text as [startOffset, endOffset], used for editor features */
+    sourceLocation?: [number, number];
+    /**
+     * Creates a new SongNote.
+     * @param note - Note name with octave (e.g., "C4", "D#5")
+     * @param start - Start position in beats
+     * @param duration - Duration in beats
+     * @param sourceLocation - Optional source location in LML text [startOffset, endOffset]
+     */
+    constructor(note: string, start: number, duration: number, sourceLocation?: [number, number]);
+    /**
+     * Creates a copy of this note.
+     * @returns A new SongNote with the same properties
+     */
     clone(): SongNote;
+    /**
+     * Checks if this note overlaps with a time range.
+     * @param min - Start of the range in beats
+     * @param max - End of the range in beats
+     * @returns True if the note overlaps with the range
+     */
     inRange(min: number, max: number): boolean;
+    /**
+     * Creates a new note transposed by a number of semitones.
+     * @param semitones - Number of semitones to transpose (positive = up, negative = down)
+     * @returns A new SongNote with the transposed pitch
+     * @example
+     * const c4 = new SongNote("C4", 0, 1)
+     * const d4 = c4.transpose(2) // D4
+     * const b3 = c4.transpose(-1) // B3
+     */
     transpose(semitones: number): SongNote;
+    /** Returns the start position in beats. */
     getStart(): number;
+    /** Returns the end position in beats (start + duration). */
     getStop(): number;
+    /** Returns the end position for rendering purposes. */
     getRenderStop(): number;
+    /** Returns a string representation of the note. */
     toString(): string;
 }
+/**
+ * Metadata associated with a parsed song.
+ */
 export interface SongMetadata {
+    /** Key signature as number of accidentals (positive = sharps, negative = flats) */
     keySignature?: number;
+    /** Number of beats per measure */
     beatsPerMeasure?: number;
+    /** Frontmatter key-value pairs from the LML source */
+    frontmatter?: Record<string, string>;
 }
+/**
+ * A list of notes representing a song or track, with associated metadata.
+ * Extends Array<SongNote> to allow direct indexing and array methods.
+ * @example
+ * const song = SongNoteList.newSong([
+ *   ["C4", 0, 1],
+ *   ["E4", 1, 1],
+ *   ["G4", 2, 1],
+ * ])
+ * song.transpose(2) // Transpose up a whole step
+ */
 export declare class SongNoteList extends Array<SongNote> {
+    /** Bucket size in beats for spatial indexing optimization */
     static bucketSize: number;
+    /** Song metadata including key signature and time signature */
     metadata?: SongMetadata;
-    autoChords?: [number, [string, string]][];
+    /** Auto chord markers as [beat_position, [root, chord_shape]][] */
+    autoChords?: [number, [string, ChordShapeName]][];
+    /** Clef changes as [beat_position, clef_name][] */
     clefs?: [number, string][];
+    /** String annotations as [beat_position, text][] */
+    strings?: [number, string][];
+    /** Time signature changes as [beat_position, beats_per_measure][] */
+    timeSignatures?: [number, number][];
+    /** Key signature changes as [beat_position, accidental_count, source_location][] */
+    keySignatures?: [number, number, [number, number]][];
+    /** Optional track name */
     trackName?: string;
+    /** Cached spatial index buckets for fast note lookup */
     private buckets?;
     constructor();
+    /**
+     * Creates a new SongNoteList from an array of note tuples.
+     * @param noteTuples - Array of [note, start, duration] tuples
+     * @returns A new SongNoteList containing the notes
+     * @example
+     * const song = SongNoteList.newSong([
+     *   ["C4", 0, 1],
+     *   ["D4", 1, 1],
+     * ])
+     */
     static newSong(noteTuples: [string, number, number][]): SongNoteList;
+    /**
+     * Creates a deep copy of this song (notes are cloned).
+     * @returns A new SongNoteList with cloned notes
+     */
     clone(): SongNoteList;
+    /**
+     * Clears the spatial index cache. Call this after modifying notes.
+     */
     clearCache(): void;
+    /**
+     * Creates a new song with all notes and key signatures transposed.
+     * Uses circle of fifths for key signature transposition.
+     * Returns `this` if amount is 0.
+     * @param amount - Number of semitones to transpose (positive = up, negative = down)
+     * @returns A new SongNoteList with transposed notes, or `this` if amount is 0
+     * @example
+     * const song = parser.compile(parser.parse("ks0 c d e"))
+     * const transposed = song.transpose(1) // Transposes to Db major
+     * // transposed.metadata.keySignature === -5
+     */
     transpose(amount?: number): SongNoteList;
+    /**
+     * Transposes notes from this song into the target song.
+     * Override in subclasses for custom note handling (e.g., multi-track).
+     * @param target - The song to add transposed notes to
+     * @param amount - Number of semitones to transpose
+     */
+    protected transposeNotesInto(target: SongNoteList, amount: number): void;
+    /**
+     * Finds all notes that overlap with a time range.
+     * @param start - Start of the range in beats
+     * @param stop - End of the range in beats
+     * @returns Array of notes that overlap with the range
+     */
     notesInRange(start: number, stop: number): SongNote[];
+    /**
+     * Finds indices of notes whose source location overlaps with a text selection.
+     * Used for editor features like transposition of selected notes.
+     * @param start - Start offset in source text
+     * @param end - End offset in source text
+     * @returns Set of note indices that overlap with the selection
+     */
+    findNotesForSelection(start: number, end: number): Set<number>;
+    /**
+     * Finds key signatures whose source location overlaps with a text selection.
+     * Used for editor features like transposition of selected key signatures.
+     * @param start - Start offset in source text
+     * @param end - End offset in source text
+     * @returns Array of key signature entries that overlap with the selection
+     */
+    findKeySignaturesForSelection(start: number, end: number): [number, number, [number, number]][];
+    /**
+     * Returns the end position of the last note in beats.
+     * @returns End position in beats, or 0 if empty
+     */
     getStopInBeats(): number;
+    /**
+     * Returns the start position of the first note in beats.
+     * @returns Start position in beats, or 0 if empty
+     */
     getStartInBeats(): number;
+    /**
+     * Calculates measure boundaries based on time signatures.
+     * @returns Array of measure objects with start position and beat count
+     */
+    getMeasures(): {
+        start: number;
+        beats: number;
+    }[];
+    /**
+     * Returns the pitch range of all notes in the song.
+     * @returns Tuple of [lowest, highest] note names, or undefined if empty
+     */
     noteRange(): [string, string] | undefined;
+    /**
+     * Determines the best staff type for displaying this song.
+     * @returns "treble", "bass", or "grand" based on note range and clef settings
+     */
     fittingStaff(): "treble" | "bass" | "grand";
+    /** Calculates the bucket range for a time span. */
     private getBucketRange;
+    /** Builds the spatial index buckets for fast note lookup. */
     private buildBuckets;
+    /** Gets the buckets to scan when matching notes near a beat. */
     private adjacentBuckets;
+    /** Gets or builds the spatial index buckets. */
     private getBuckets;
+    /**
+     * Finds the note closest to a beat position using spatial indexing.
+     * Faster than matchNote for large songs.
+     * @param findNote - Note name to search for (e.g., "C4")
+     * @param beat - Beat position to search near
+     * @param wrapRight - Optional right boundary for wrap-around search
+     * @param wrapLeft - Optional left boundary for wrap-around search
+     * @returns Index of the matching note, or null if not found
+     */
     matchNoteFast(findNote: string, beat: number, wrapRight?: number, wrapLeft?: number): number | null;
+    /**
+     * Finds the note closest to a beat position using linear search.
+     * Use matchNoteFast for better performance on large songs.
+     * @param findNote - Note name to search for (e.g., "C4")
+     * @param beat - Beat position to search near
+     * @returns Index of the matching note, or null if not found
+     */
     matchNote(findNote: string, beat: number): number | null;
 }
+/**
+ * A song containing multiple tracks, where each track is a SongNoteList.
+ * Notes are stored both in the main list and in their respective tracks.
+ * @example
+ * const song = new MultiTrackSong()
+ * song.pushWithTrack(new SongNote("C4", 0, 1), 0) // Track 0
+ * song.pushWithTrack(new SongNote("E4", 0, 1), 1) // Track 1
+ */
 export declare class MultiTrackSong extends SongNoteList {
+    /** Array of individual tracks */
     tracks: SongNoteList[];
     constructor();
+    /**
+     * Adds a note to both the main song and a specific track.
+     * @param note - The note to add
+     * @param trackIdx - The track index to add the note to
+     * @returns The added note
+     */
     pushWithTrack(note: SongNote, trackIdx: number): SongNote;
+    /**
+     * Finds an unused track index for auto-generated content like chords.
+     * @returns The next available track index
+     */
     findEmptyTrackIdx(): number;
+    /**
+     * Gets a track by index, creating it if it doesn't exist.
+     * @param idx - The track index
+     * @returns The SongNoteList for the track
+     */
     getTrack(idx: number): SongNoteList;
+    /**
+     * Transposes notes from this song into the target song, handling tracks.
+     * Notes are transposed per-track and added to both the track and main list.
+     * @param target - The MultiTrackSong to add transposed notes to
+     * @param amount - Number of semitones to transpose
+     */
+    protected transposeNotesInto(target: SongNoteList, amount: number): void;
 }
 //# sourceMappingURL=song.d.ts.map

package/dist/song.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"song.d.ts","sourceRoot":"","sources":["../src/song.ts"],"names":[],"mappings":"AAKA,qBAAa,QAAQ;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;gBAEJ,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAOzD,KAAK,IAAI,QAAQ;IAMjB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAS1C,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ;IAMtC,QAAQ,IAAI,MAAM;IAIlB,OAAO,IAAI,MAAM;IAIjB,aAAa,IAAI,MAAM;IAIvB,QAAQ,IAAI,MAAM;CAGnB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAGD,qBAAa,YAAa,SAAQ,KAAK,CAAC,QAAQ,CAAC;IAC/C,MAAM,CAAC,UAAU,SAAI;IAErB,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAA;IACzC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,OAAO,CAAC,OAAO,CAAC,CAA0B;;IAO1C,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,YAAY;IAYpE,KAAK,IAAI,YAAY;IAUrB,UAAU,IAAI,IAAI;IAIlB,SAAS,CAAC,MAAM,SAAI,GAAG,YAAY;IAenC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE;IAIrD,cAAc,IAAI,MAAM;IAKxB,eAAe,IAAI,MAAM;IAKzB,SAAS,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS;IAoBzC,YAAY,IAAI,QAAQ,GAAG,MAAM,GAAG,OAAO;IAyC3C,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,UAAU;IAQlB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAqDnG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAsBzD;AAED,qBAAa,cAAe,SAAQ,YAAY;IAC9C,MAAM,EAAE,YAAY,EAAE,CAAK;;IAO3B,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ;IAQzD,iBAAiB,IAAI,MAAM;IAI3B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY;CAOpC"}
+{"version":3,"file":"song.d.ts","sourceRoot":"","sources":["../src/song.ts"],"names":[],"mappings":"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"}

package/dist/song.js

@@ -1,17 +1,39 @@
-import { parseNote, noteName, MIDDLE_C_PITCH } from "./music.js";
-// note: C4, D#5, etc...
-// start: when note begins in beats
-// duration: how long note is in beats
+import { parseNote, noteName, MIDDLE_C_PITCH, transposeKeySignature } from "./music.js";
+/**
+ * Represents a single musical note with pitch, timing, and duration.
+ * @example
+ * const note = new SongNote("C4", 0, 1) // Middle C at beat 0, duration 1 beat
+ * const note2 = new SongNote("D#5", 4, 0.5) // D#5 at beat 4, half beat duration
+ */
 export class SongNote {
-    constructor(note, start, duration) {
+    /**
+     * Creates a new SongNote.
+     * @param note - Note name with octave (e.g., "C4", "D#5")
+     * @param start - Start position in beats
+     * @param duration - Duration in beats
+     * @param sourceLocation - Optional source location in LML text [startOffset, endOffset]
+     */
+    constructor(note, start, duration, sourceLocation) {
         this.id = Symbol();
         this.note = note;
         this.start = start;
         this.duration = duration;
+        this.sourceLocation = sourceLocation;
     }
+    /**
+     * Creates a copy of this note.
+     * @returns A new SongNote with the same properties
+     */
     clone() {
-        return new SongNote(this.note, this.start, this.duration);
+        const cloned = new SongNote(this.note, this.start, this.duration, this.sourceLocation);
+        return cloned;
     }
+    /**
+     * Checks if this note overlaps with a time range.
+     * @param min - Start of the range in beats
+     * @param max - End of the range in beats
+     * @returns True if the note overlaps with the range
+     */
     inRange(min, max) {
         const stop = this.start + this.duration;
         if (min >= stop) {
@@ -22,28 +44,61 @@ export class SongNote {
         }
         return true;
     }
+    /**
+     * Creates a new note transposed by a number of semitones.
+     * @param semitones - Number of semitones to transpose (positive = up, negative = down)
+     * @returns A new SongNote with the transposed pitch
+     * @example
+     * const c4 = new SongNote("C4", 0, 1)
+     * const d4 = c4.transpose(2) // D4
+     * const b3 = c4.transpose(-1) // B3
+     */
     transpose(semitones) {
-        return new SongNote(noteName(parseNote(this.note) + semitones), this.start, this.duration);
+        return new SongNote(noteName(parseNote(this.note) + semitones), this.start, this.duration, this.sourceLocation);
     }
+    /** Returns the start position in beats. */
     getStart() {
         return this.start;
     }
+    /** Returns the end position in beats (start + duration). */
     getStop() {
         return this.start + this.duration;
     }
+    /** Returns the end position for rendering purposes. */
     getRenderStop() {
         return this.start + this.duration;
     }
+    /** Returns a string representation of the note. */
     toString() {
         return `${this.note},${this.start},${this.duration}`;
     }
 }
-// like note list but notes in time
+/**
+ * A list of notes representing a song or track, with associated metadata.
+ * Extends Array<SongNote> to allow direct indexing and array methods.
+ * @example
+ * const song = SongNoteList.newSong([
+ *   ["C4", 0, 1],
+ *   ["E4", 1, 1],
+ *   ["G4", 2, 1],
+ * ])
+ * song.transpose(2) // Transpose up a whole step
+ */
 export class SongNoteList extends Array {
     constructor() {
         super();
         Object.setPrototypeOf(this, SongNoteList.prototype);
     }
+    /**
+     * Creates a new SongNoteList from an array of note tuples.
+     * @param noteTuples - Array of [note, start, duration] tuples
+     * @returns A new SongNoteList containing the notes
+     * @example
+     * const song = SongNoteList.newSong([
+     *   ["C4", 0, 1],
+     *   ["D4", 1, 1],
+     * ])
+     */
     static newSong(noteTuples) {
         const notes = noteTuples.map(([note, start, duration]) => new SongNote(note, start, duration));
         const song = new SongNoteList();
@@ -52,38 +107,157 @@ export class SongNoteList extends Array {
         }
         return song;
     }
+    /**
+     * Creates a deep copy of this song (notes are cloned).
+     * @returns A new SongNoteList with cloned notes
+     */
     clone() {
         const song = new SongNoteList();
         this.forEach(note => song.push(note.clone()));
         return song;
     }
+    /**
+     * Clears the spatial index cache. Call this after modifying notes.
+     */
     clearCache() {
         delete this.buckets;
     }
+    /**
+     * Creates a new song with all notes and key signatures transposed.
+     * Uses circle of fifths for key signature transposition.
+     * Returns `this` if amount is 0.
+     * @param amount - Number of semitones to transpose (positive = up, negative = down)
+     * @returns A new SongNoteList with transposed notes, or `this` if amount is 0
+     * @example
+     * const song = parser.compile(parser.parse("ks0 c d e"))
+     * const transposed = song.transpose(1) // Transposes to Db major
+     * // transposed.metadata.keySignature === -5
+     */
     transpose(amount = 0) {
         if (amount == 0) {
             return this;
         }
-        const song = new SongNoteList();
-        this.forEach(note => song.push(note.transpose(amount)));
+        const song = new this.constructor();
+        this.transposeNotesInto(song, amount);
+        // Copy metadata, transposing key signature
+        if (this.metadata) {
+            song.metadata = {
+                ...this.metadata,
+                keySignature: this.metadata.keySignature !== undefined
+                    ? transposeKeySignature(this.metadata.keySignature, amount)
+                    : undefined
+            };
+        }
+        // Transpose key signatures array
+        if (this.keySignatures) {
+            song.keySignatures = this.keySignatures.map(([beat, count, loc]) => [beat, transposeKeySignature(count, amount), loc]);
+        }
+        // Reuse references to unchanged properties
+        song.timeSignatures = this.timeSignatures;
+        song.clefs = this.clefs;
+        song.strings = this.strings;
+        song.autoChords = this.autoChords;
+        song.trackName = this.trackName;
         return song;
     }
-    // find the notes that fall in the time range
+    /**
+     * Transposes notes from this song into the target song.
+     * Override in subclasses for custom note handling (e.g., multi-track).
+     * @param target - The song to add transposed notes to
+     * @param amount - Number of semitones to transpose
+     */
+    transposeNotesInto(target, amount) {
+        this.forEach(note => target.push(note.transpose(amount)));
+    }
+    /**
+     * Finds all notes that overlap with a time range.
+     * @param start - Start of the range in beats
+     * @param stop - End of the range in beats
+     * @returns Array of notes that overlap with the range
+     */
     notesInRange(start, stop) {
         return [...this.filter((n) => n.inRange(start, stop))];
     }
+    /**
+     * Finds indices of notes whose source location overlaps with a text selection.
+     * Used for editor features like transposition of selected notes.
+     * @param start - Start offset in source text
+     * @param end - End offset in source text
+     * @returns Set of note indices that overlap with the selection
+     */
+    findNotesForSelection(start, end) {
+        const result = new Set();
+        this.forEach((note, index) => {
+            if (!note.sourceLocation)
+                return;
+            const [noteStart, noteEnd] = note.sourceLocation;
+            if (start <= noteEnd && end >= noteStart) {
+                result.add(index);
+            }
+        });
+        return result;
+    }
+    /**
+     * Finds key signatures whose source location overlaps with a text selection.
+     * Used for editor features like transposition of selected key signatures.
+     * @param start - Start offset in source text
+     * @param end - End offset in source text
+     * @returns Array of key signature entries that overlap with the selection
+     */
+    findKeySignaturesForSelection(start, end) {
+        if (!this.keySignatures)
+            return [];
+        return this.keySignatures.filter(([, , [ksStart, ksEnd]]) => start <= ksEnd && end >= ksStart);
+    }
+    /**
+     * Returns the end position of the last note in beats.
+     * @returns End position in beats, or 0 if empty
+     */
     getStopInBeats() {
         if (this.length == 0) {
             return 0;
         }
         return Math.max.apply(null, this.map((n) => n.getStop()));
     }
+    /**
+     * Returns the start position of the first note in beats.
+     * @returns Start position in beats, or 0 if empty
+     */
     getStartInBeats() {
         if (this.length == 0) {
             return 0;
         }
         return Math.min.apply(null, this.map((n) => n.getStart()));
     }
+    /**
+     * Calculates measure boundaries based on time signatures.
+     * @returns Array of measure objects with start position and beat count
+     */
+    getMeasures() {
+        const measures = [];
+        const songEnd = this.getStopInBeats();
+        if (songEnd === 0)
+            return measures;
+        // Default to 4 beats per measure if no time signatures
+        const timeSigs = this.timeSignatures ?? [[0, 4]];
+        let position = 0;
+        let sigIndex = 0;
+        let currentBeats = timeSigs[0]?.[1] ?? 4;
+        while (position < songEnd) {
+            // Check if time signature changes at or before current position
+            while (sigIndex < timeSigs.length && timeSigs[sigIndex][0] <= position) {
+                currentBeats = timeSigs[sigIndex][1];
+                sigIndex++;
+            }
+            measures.push({ start: position, beats: currentBeats });
+            position += currentBeats;
+        }
+        return measures;
+    }
+    /**
+     * Returns the pitch range of all notes in the song.
+     * @returns Tuple of [lowest, highest] note names, or undefined if empty
+     */
     noteRange() {
         if (!this.length) {
             return undefined;
@@ -101,6 +275,10 @@ export class SongNoteList extends Array {
         }
         return [noteName(min), noteName(max)];
     }
+    /**
+     * Determines the best staff type for displaying this song.
+     * @returns "treble", "bass", or "grand" based on note range and clef settings
+     */
     fittingStaff() {
         if (this.clefs && this.clefs.length == 1) {
             const firstNote = this[0];
@@ -138,12 +316,14 @@ export class SongNoteList extends Array {
             return "treble";
         }
     }
+    /** Calculates the bucket range for a time span. */
     getBucketRange(start, stop) {
         const bucketSize = SongNoteList.bucketSize;
         const left = Math.floor(start / bucketSize);
         const right = Math.ceil(stop / bucketSize);
         return [left, right];
     }
+    /** Builds the spatial index buckets for fast note lookup. */
     buildBuckets() {
         const buckets = {};
         this.forEach((songNote, idx) => {
@@ -156,16 +336,26 @@ export class SongNoteList extends Array {
         });
         return buckets;
     }
-    // get the buckets to scan to match notes for beat
+    /** Gets the buckets to scan when matching notes near a beat. */
     adjacentBuckets(beat) {
         return this.getBucketRange(beat - 1, beat + 1);
     }
+    /** Gets or builds the spatial index buckets. */
     getBuckets() {
         if (!this.buckets) {
             this.buckets = this.buildBuckets();
         }
         return this.buckets;
     }
+    /**
+     * Finds the note closest to a beat position using spatial indexing.
+     * Faster than matchNote for large songs.
+     * @param findNote - Note name to search for (e.g., "C4")
+     * @param beat - Beat position to search near
+     * @param wrapRight - Optional right boundary for wrap-around search
+     * @param wrapLeft - Optional left boundary for wrap-around search
+     * @returns Index of the matching note, or null if not found
+     */
     matchNoteFast(findNote, beat, wrapRight, wrapLeft) {
         const buckets = this.getBuckets();
         const [left, right] = this.adjacentBuckets(beat);
@@ -213,7 +403,13 @@ export class SongNoteList extends Array {
         }
         return foundIdx;
     }
-    // see if we're hitting a valid note
+    /**
+     * Finds the note closest to a beat position using linear search.
+     * Use matchNoteFast for better performance on large songs.
+     * @param findNote - Note name to search for (e.g., "C4")
+     * @param beat - Beat position to search near
+     * @returns Index of the matching note, or null if not found
+     */
     matchNote(findNote, beat) {
         let foundIdx = null;
         for (let idx = 0; idx < this.length; idx++) {
@@ -234,28 +430,68 @@ export class SongNoteList extends Array {
         return foundIdx;
     }
 }
-SongNoteList.bucketSize = 8; // bucket size in beats
+/** Bucket size in beats for spatial indexing optimization */
+SongNoteList.bucketSize = 8;
+/**
+ * A song containing multiple tracks, where each track is a SongNoteList.
+ * Notes are stored both in the main list and in their respective tracks.
+ * @example
+ * const song = new MultiTrackSong()
+ * song.pushWithTrack(new SongNote("C4", 0, 1), 0) // Track 0
+ * song.pushWithTrack(new SongNote("E4", 0, 1), 1) // Track 1
+ */
 export class MultiTrackSong extends SongNoteList {
     constructor() {
         super();
+        /** Array of individual tracks */
         this.tracks = [];
         Object.setPrototypeOf(this, MultiTrackSong.prototype);
     }
+    /**
+     * Adds a note to both the main song and a specific track.
+     * @param note - The note to add
+     * @param trackIdx - The track index to add the note to
+     * @returns The added note
+     */
     pushWithTrack(note, trackIdx) {
         this.push(note);
         const track = this.getTrack(trackIdx);
         track.push(note);
         return note;
     }
-    // find an empty track to put autochords in
+    /**
+     * Finds an unused track index for auto-generated content like chords.
+     * @returns The next available track index
+     */
     findEmptyTrackIdx() {
         return this.tracks.length + 1;
     }
+    /**
+     * Gets a track by index, creating it if it doesn't exist.
+     * @param idx - The track index
+     * @returns The SongNoteList for the track
+     */
     getTrack(idx) {
         if (!this.tracks[idx]) {
             this.tracks[idx] = new SongNoteList();
         }
         return this.tracks[idx];
     }
+    /**
+     * Transposes notes from this song into the target song, handling tracks.
+     * Notes are transposed per-track and added to both the track and main list.
+     * @param target - The MultiTrackSong to add transposed notes to
+     * @param amount - Number of semitones to transpose
+     */
+    transposeNotesInto(target, amount) {
+        const multiTarget = target;
+        this.tracks.forEach((track, idx) => {
+            if (track) {
+                const transposedTrack = track.transpose(amount);
+                multiTarget.tracks[idx] = transposedTrack;
+                transposedTrack.forEach(note => multiTarget.push(note));
+            }
+        });
+    }
 }
 //# sourceMappingURL=song.js.map