@pepperhorn/chordl-core 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PepperHorn Music / Creative Ranges Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/audio/midi-export.d.ts

@@ -0,0 +1,23 @@
+interface MidiChordOptions {
+    notes: string[];
+    /** Left-hand notes (bass clef). Remaining notes go to right hand (treble clef). */
+    lhNotes?: string[];
+    octave?: number;
+    lhOctave?: number;
+    durationTicks?: number;
+    velocity?: number;
+    tempo?: number;
+    arpeggiated?: boolean;
+    arpDelayTicks?: number;
+}
+/**
+ * Generate a MIDI file as a Uint8Array containing a single chord.
+ * When lhNotes is provided, produces a Format 1 file with LH on channel 0
+ * (bass clef, octave 3) and RH on channel 1 (treble clef, octave 4).
+ */
+export declare function generateMidiFile(options: MidiChordOptions): Uint8Array;
+/**
+ * Trigger a browser download of a MIDI file.
+ */
+export declare function downloadMidi(notes: string[], chordName: string, octave?: number, lhNotes?: string[], lhOctave?: number): void;
+export {};

package/dist/audio/midi-export.js

@@ -0,0 +1,155 @@
+import { Note } from "tonal";
+/**
+ * Minimal MIDI file generator for a single chord.
+ * Produces a Format 0 (single track) Standard MIDI File.
+ */
+function toVarLen(value) {
+    if (value < 0x80)
+        return [value];
+    const bytes = [];
+    bytes.unshift(value & 0x7f);
+    value >>= 7;
+    while (value > 0) {
+        bytes.unshift((value & 0x7f) | 0x80);
+        value >>= 7;
+    }
+    return bytes;
+}
+function writeUint16(value) {
+    return [(value >> 8) & 0xff, value & 0xff];
+}
+function writeUint32(value) {
+    return [
+        (value >> 24) & 0xff,
+        (value >> 16) & 0xff,
+        (value >> 8) & 0xff,
+        value & 0xff,
+    ];
+}
+function noteToMidi(note, defaultOctave = 4) {
+    if (/[0-9]$/.test(note))
+        return Note.midi(note);
+    return Note.midi(`${note}${defaultOctave}`);
+}
+/** Build raw track bytes for a set of MIDI note numbers on a given channel. */
+function buildTrackData(midiNotes, channel, velocity, durationTicks, trackName, tempoEvent, arpeggiated, arpDelayTicks) {
+    const data = [];
+    const noteOn = 0x90 | channel;
+    const noteOff = 0x80 | channel;
+    // Tempo meta event (only on first track)
+    if (tempoEvent) {
+        const { microsecondsPerBeat } = tempoEvent;
+        data.push(0x00, 0xff, 0x51, 0x03, (microsecondsPerBeat >> 16) & 0xff, (microsecondsPerBeat >> 8) & 0xff, microsecondsPerBeat & 0xff);
+    }
+    // Track name (ASCII only, VarLen-encoded length)
+    const nameBytes = Array.from(trackName, (ch) => ch.charCodeAt(0) & 0x7f);
+    data.push(0x00, 0xff, 0x03, ...toVarLen(nameBytes.length), ...nameBytes);
+    // Note-on events
+    if (arpeggiated && arpDelayTicks) {
+        for (let i = 0; i < midiNotes.length; i++) {
+            const delta = i === 0 ? 0 : arpDelayTicks;
+            data.push(...toVarLen(delta), noteOn, midiNotes[i], velocity);
+        }
+    }
+    else {
+        for (let i = 0; i < midiNotes.length; i++) {
+            data.push(...toVarLen(0), noteOn, midiNotes[i], velocity);
+        }
+    }
+    // Note-off events
+    const totalArpDelay = arpeggiated && arpDelayTicks ? (midiNotes.length - 1) * arpDelayTicks : 0;
+    for (let i = 0; i < midiNotes.length; i++) {
+        const delta = i === 0 ? durationTicks + totalArpDelay : 0;
+        data.push(...toVarLen(delta), noteOff, midiNotes[i], 0);
+    }
+    // End of track
+    data.push(0x00, 0xff, 0x2f, 0x00);
+    return data;
+}
+/**
+ * Generate a MIDI file as a Uint8Array containing a single chord.
+ * When lhNotes is provided, produces a Format 1 file with LH on channel 0
+ * (bass clef, octave 3) and RH on channel 1 (treble clef, octave 4).
+ */
+export function generateMidiFile(options) {
+    const { notes, lhNotes, octave = 4, lhOctave: lhOctaveOpt, durationTicks = 960, velocity = 90, tempo = 120, arpeggiated = false, arpDelayTicks = 120, } = options;
+    const ticksPerQuarter = 480;
+    const microsecondsPerBeat = Math.round(60000000 / tempo);
+    if (lhNotes && lhNotes.length > 0) {
+        // Format 1: separate LH (bass clef) and RH (treble clef) tracks
+        const lhOctave = lhOctaveOpt ?? 3;
+        const rhOctave = octave;
+        const lhSet = new Set(lhNotes);
+        const rhNotes = notes.filter((n) => !lhSet.has(n));
+        const lhMidi = lhNotes.map((n) => noteToMidi(n, lhOctave)).filter((m) => m != null);
+        const rhMidi = rhNotes.map((n) => noteToMidi(n, rhOctave)).filter((m) => m != null);
+        if (lhMidi.length === 0 && rhMidi.length === 0)
+            return new Uint8Array(0);
+        const tracks = [];
+        if (lhMidi.length > 0) {
+            tracks.push(buildTrackData(lhMidi, 0, velocity, durationTicks, "L.H.", { microsecondsPerBeat }, arpeggiated, arpDelayTicks));
+        }
+        if (rhMidi.length > 0) {
+            tracks.push(buildTrackData(rhMidi, 1, velocity, durationTicks, "R.H.", tracks.length === 0 ? { microsecondsPerBeat } : undefined, arpeggiated, arpDelayTicks));
+        }
+        const header = [
+            0x4d, 0x54, 0x68, 0x64,
+            ...writeUint32(6),
+            ...writeUint16(1), // format 1
+            ...writeUint16(tracks.length),
+            ...writeUint16(ticksPerQuarter),
+        ];
+        let totalSize = header.length;
+        const trackChunks = [];
+        for (const track of tracks) {
+            const chunk = [0x4d, 0x54, 0x72, 0x6b, ...writeUint32(track.length), ...track];
+            trackChunks.push(chunk);
+            totalSize += chunk.length;
+        }
+        const file = new Uint8Array(totalSize);
+        let offset = 0;
+        file.set(header, offset);
+        offset += header.length;
+        for (const chunk of trackChunks) {
+            file.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return file;
+    }
+    // Single track (Format 0) — original behavior
+    const midiNotes = notes
+        .map((n) => noteToMidi(n, octave))
+        .filter((m) => m != null);
+    if (midiNotes.length === 0)
+        return new Uint8Array(0);
+    const trackData = buildTrackData(midiNotes, 0, velocity, durationTicks, "Chord", { microsecondsPerBeat }, arpeggiated, arpDelayTicks);
+    const header = [
+        0x4d, 0x54, 0x68, 0x64,
+        ...writeUint32(6),
+        ...writeUint16(0), // format 0
+        ...writeUint16(1),
+        ...writeUint16(ticksPerQuarter),
+    ];
+    const trackHeader = [0x4d, 0x54, 0x72, 0x6b, ...writeUint32(trackData.length)];
+    const file = new Uint8Array(header.length + trackHeader.length + trackData.length);
+    file.set(header, 0);
+    file.set(trackHeader, header.length);
+    file.set(trackData, header.length + trackHeader.length);
+    return file;
+}
+/**
+ * Trigger a browser download of a MIDI file.
+ */
+export function downloadMidi(notes, chordName, octave = 4, lhNotes, lhOctave) {
+    const midi = generateMidiFile({ notes, octave, lhNotes, lhOctave });
+    if (midi.length === 0)
+        return;
+    const blob = new Blob([midi.buffer], { type: "audio/midi" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `${chordName.replace(/[^a-zA-Z0-9\-_ ]/g, "_").slice(0, 100)}.mid`;
+    a.click();
+    URL.revokeObjectURL(url);
+}
+//# sourceMappingURL=midi-export.js.map

package/dist/audio/midi-export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"midi-export.js","sourceRoot":"","sources":["../../src/audio/midi-export.ts"],"names":[],"mappings":"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"}

package/dist/chord-sheet/codec.d.ts

@@ -0,0 +1,14 @@
+import type { ChordSheetData } from "../types";
+export interface CodecOptions {
+    /** Skip compression (for environments without CompressionStream). */
+    skipCompression?: boolean;
+}
+/**
+ * Encode a ChordSheetData object into a portable string token.
+ * Format: bcs1.<base64url(deflate(JSON))>
+ */
+export declare function encodeChordSheet(data: ChordSheetData, options?: CodecOptions): Promise<string>;
+/**
+ * Decode a token string back into ChordSheetData.
+ */
+export declare function decodeChordSheet(token: string, _options?: CodecOptions): Promise<ChordSheetData>;

package/dist/chord-sheet/codec.js

@@ -0,0 +1,119 @@
+import { CHORD_SHEET_SCHEMA_VERSION, validateVersion } from "./schema";
+const TOKEN_PREFIX = "bcs1.";
+/**
+ * Encode a ChordSheetData object into a portable string token.
+ * Format: bcs1.<base64url(deflate(JSON))>
+ */
+export async function encodeChordSheet(data, options) {
+    const json = JSON.stringify({ ...data, v: data.v ?? CHORD_SHEET_SCHEMA_VERSION });
+    const bytes = new TextEncoder().encode(json);
+    if (!options?.skipCompression && typeof CompressionStream !== "undefined") {
+        try {
+            const compressed = await compress(bytes);
+            return TOKEN_PREFIX + base64urlEncode(compressed);
+        }
+        catch {
+            // Fallback to uncompressed
+        }
+    }
+    return TOKEN_PREFIX + base64urlEncode(bytes);
+}
+/**
+ * Decode a token string back into ChordSheetData.
+ */
+export async function decodeChordSheet(token, _options) {
+    if (!token.startsWith(TOKEN_PREFIX)) {
+        throw new Error(`Invalid token: must start with "${TOKEN_PREFIX}"`);
+    }
+    const payload = token.slice(TOKEN_PREFIX.length);
+    const bytes = base64urlDecode(payload);
+    // Try decompressing first, fall back to raw JSON
+    let json;
+    if (typeof DecompressionStream !== "undefined") {
+        try {
+            const decompressed = await decompress(bytes);
+            json = new TextDecoder().decode(decompressed);
+        }
+        catch {
+            json = new TextDecoder().decode(bytes);
+        }
+    }
+    else {
+        json = new TextDecoder().decode(bytes);
+    }
+    let data;
+    try {
+        data = JSON.parse(json);
+    }
+    catch {
+        throw new Error("Invalid token: could not parse payload as JSON");
+    }
+    validateVersion(data.v);
+    return data;
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function base64urlEncode(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlDecode(str) {
+    const padded = str.replace(/-/g, "+").replace(/_/g, "/");
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+async function compress(input) {
+    const cs = new CompressionStream("deflate");
+    const writer = cs.writable.getWriter();
+    writer.write(input);
+    writer.close();
+    const reader = cs.readable.getReader();
+    const chunks = [];
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+    }
+    return concatBytes(chunks);
+}
+async function decompress(input) {
+    const ds = new DecompressionStream("deflate");
+    const writer = ds.writable.getWriter();
+    // Write and close, but don't await — let errors surface on the readable side
+    const writePromise = writer.write(input).then(() => writer.close()).catch(() => { });
+    const reader = ds.readable.getReader();
+    const chunks = [];
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+        }
+    }
+    catch (e) {
+        // Ensure writer is cleaned up
+        await writePromise;
+        throw e;
+    }
+    await writePromise;
+    return concatBytes(chunks);
+}
+function concatBytes(chunks) {
+    const total = chunks.reduce((n, c) => n + c.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        out.set(c, offset);
+        offset += c.length;
+    }
+    return out;
+}
+//# sourceMappingURL=codec.js.map

package/dist/chord-sheet/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/chord-sheet/codec.ts"],"names":[],"mappings":"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"}

package/dist/chord-sheet/defaults.d.ts

@@ -0,0 +1,13 @@
+import type { DisplayDefaults } from "../types";
+/** System-level defaults when nothing is specified. */
+export declare const SYSTEM_DEFAULTS: Required<DisplayDefaults>;
+/**
+ * Shallow-merge display defaults with undefined-stripping.
+ * Priority: chord > section > sheet > system.
+ */
+export declare function resolveDefaults(sheet?: DisplayDefaults, section?: DisplayDefaults, chord?: Partial<DisplayDefaults>): Required<DisplayDefaults>;
+/**
+ * Compute a chord reference ID from its position.
+ * Single section → "1","2","3"...  Multiple sections → "A1","A2","B1"...
+ */
+export declare function chordRef(sectionIndex: number, chordIndex: number, sectionCount: number, sectionId?: string): string;

package/dist/chord-sheet/defaults.js

@@ -0,0 +1,48 @@
+/** System-level defaults when nothing is specified. */
+export const SYSTEM_DEFAULTS = {
+    display: "keyboard",
+    format: "compact",
+    theme: "simple",
+    highlightColor: "#a0c6e8",
+    padding: 1,
+    scale: 0.5,
+    glyphs: "bravura",
+    showNoteNames: false,
+    noteNameSize: "base",
+    noteNameMode: "pitch-class",
+    showFingering: false,
+    fingeringSize: "base",
+};
+/**
+ * Shallow-merge display defaults with undefined-stripping.
+ * Priority: chord > section > sheet > system.
+ */
+export function resolveDefaults(sheet, section, chord) {
+    return {
+        ...SYSTEM_DEFAULTS,
+        ...(sheet ? stripUndefined(sheet) : {}),
+        ...(section ? stripUndefined(section) : {}),
+        ...(chord ? stripUndefined(chord) : {}),
+    };
+}
+/** Remove keys whose value is undefined so they don't overwrite lower layers. */
+function stripUndefined(obj) {
+    const out = { ...obj };
+    for (const key of Object.keys(out)) {
+        if (out[key] === undefined)
+            delete out[key];
+    }
+    return out;
+}
+/**
+ * Compute a chord reference ID from its position.
+ * Single section → "1","2","3"...  Multiple sections → "A1","A2","B1"...
+ */
+export function chordRef(sectionIndex, chordIndex, sectionCount, sectionId) {
+    const num = chordIndex + 1;
+    if (sectionCount <= 1)
+        return String(num);
+    const letter = sectionId ?? String.fromCharCode(65 + sectionIndex); // A, B, C...
+    return `${letter}${num}`;
+}
+//# sourceMappingURL=defaults.js.map

package/dist/chord-sheet/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/chord-sheet/defaults.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,MAAM,CAAC,MAAM,eAAe,GAA8B;IACxD,OAAO,EAAE,UAAU;IACnB,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,QAAQ;IACf,cAAc,EAAE,SAAS;IACzB,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,GAAG;IACV,MAAM,EAAE,SAAS;IACjB,aAAa,EAAE,KAAK;IACpB,YAAY,EAAE,MAAM;IACpB,YAAY,EAAE,aAAa;IAC3B,aAAa,EAAE,KAAK;IACpB,aAAa,EAAE,MAAM;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAuB,EACvB,OAAyB,EACzB,KAAgC;IAEhC,OAAO;QACL,GAAG,eAAe;QAClB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACX,CAAC;AACjC,CAAC;AAED,iFAAiF;AACjF,SAAS,cAAc,CAAmB,GAAM;IAC9C,MAAM,GAAG,GAAG,EAAE,GAAG,GAAG,EAA6B,CAAC;IAClD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,GAAiB,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,YAAoB,EACpB,UAAkB,EAClB,YAAoB,EACpB,SAAkB;IAElB,MAAM,GAAG,GAAG,UAAU,GAAG,CAAC,CAAC;IAC3B,IAAI,YAAY,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,SAAS,IAAI,MAAM,CAAC,YAAY,CAAC,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,aAAa;IACjF,OAAO,GAAG,MAAM,GAAG,GAAG,EAAE,CAAC;AAC3B,CAAC"}

package/dist/chord-sheet/index.d.ts

@@ -0,0 +1,3 @@
+export { resolveDefaults, chordRef, SYSTEM_DEFAULTS } from "./defaults";
+export { CHORD_SHEET_SCHEMA_VERSION, validateVersion } from "./schema";
+export { encodeChordSheet, decodeChordSheet } from "./codec";

package/dist/chord-sheet/index.js

@@ -0,0 +1,4 @@
+export { resolveDefaults, chordRef, SYSTEM_DEFAULTS } from "./defaults";
+export { CHORD_SHEET_SCHEMA_VERSION, validateVersion } from "./schema";
+export { encodeChordSheet, decodeChordSheet } from "./codec";
+//# sourceMappingURL=index.js.map

package/dist/chord-sheet/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/chord-sheet/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,0BAA0B,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/chord-sheet/schema.d.ts

@@ -0,0 +1,6 @@
+export declare const CHORD_SHEET_SCHEMA_VERSION = "1.0";
+/**
+ * Validate that a token's version is compatible with the current schema.
+ * Rejects incompatible major versions; minor differences are OK.
+ */
+export declare function validateVersion(v: string): void;

package/dist/chord-sheet/schema.js

@@ -0,0 +1,17 @@
+export const CHORD_SHEET_SCHEMA_VERSION = "1.0";
+/**
+ * Validate that a token's version is compatible with the current schema.
+ * Rejects incompatible major versions; minor differences are OK.
+ */
+export function validateVersion(v) {
+    if (!v || typeof v !== "string") {
+        throw new Error("Missing or invalid schema version");
+    }
+    const [major] = v.split(".");
+    const [currentMajor] = CHORD_SHEET_SCHEMA_VERSION.split(".");
+    if (major !== currentMajor) {
+        throw new Error(`Incompatible schema version "${v}" (current: "${CHORD_SHEET_SCHEMA_VERSION}"). ` +
+            `Major version mismatch — this sheet was created with a newer or older format.`);
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/chord-sheet/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/chord-sheet/schema.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAC;AAEhD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,CAAS;IACvC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,CAAC,YAAY,CAAC,GAAG,0BAA0B,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,gCAAgC,CAAC,gBAAgB,0BAA0B,MAAM;YACjF,+EAA+E,CAChF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+export declare const MAX_EXAMPLES = 3;
+export declare const ENABLE_CHORD_LOGGING = false;

package/dist/config.js

@@ -0,0 +1,15 @@
+export const MAX_EXAMPLES = 3;
+// --- Chord Logging ---
+// Opt-in telemetry for shared learning.
+// When enabled, chord requests and their results are sent to a write-only
+// public ledger. No personal data is collected — just chord inputs, outputs,
+// and an anonymized session hash derived server-side from the request IP.
+//
+// By pointing to the shared public ledger, we can all learn from the results
+// and keep improving the voicing logic together.
+//
+// To use the shared ledger, uncomment CHORD_LOG_ENDPOINT below.
+// To self-host, point it at your own compatible endpoint.
+export const ENABLE_CHORD_LOGGING = false;
+// export const CHORD_LOG_ENDPOINT = "https://ledger.betterchord.com/api/chord-log";
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAE9B,wBAAwB;AACxB,wCAAwC;AACxC,0EAA0E;AAC1E,6EAA6E;AAC7E,0EAA0E;AAC1E,EAAE;AACF,6EAA6E;AAC7E,iDAAiD;AACjD,EAAE;AACF,gEAAgE;AAChE,0DAA0D;AAE1D,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAC1C,oFAAoF"}

package/dist/engine/auto-fingering.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Auto-fingering engine for piano chord voicings.
+ *
+ * Inspired by Mark Levine's "The Jazz Piano Book" approach:
+ * - Chords are always playable — split across hands when needed
+ * - Max span per hand: a 12th (19 semitones)
+ * - Max notes per hand: 5
+ * - LH typically takes root + guide tones (3rd/7th)
+ * - RH takes upper extensions (9th, #11th, 13th)
+ *
+ * Finger assignment rules:
+ * - RH: 1 (thumb) = lowest, 5 (pinky) = highest
+ * - LH: 5 (pinky) = lowest, 1 (thumb) = highest
+ * - Avoid thumb on black keys except at the bottom of RH / top of LH
+ * - Wider intervals skip middle fingers (1-2-5 rather than 1-2-3)
+ */
+export type Hand = "rh" | "lh";
+export interface HandAssignment {
+    /** Finger number per note (1-5), matching the input notes array order */
+    fingering: number[];
+    /** Hand assignment per note: "lh" or "rh" */
+    hands: Hand[];
+}
+/**
+ * Assign fingering to chord notes, splitting across hands when needed.
+ *
+ * @param notes - Pitch classes in voicing order (e.g. ["B", "D#", "F#", ...])
+ * @param handHints - Optional per-note hand assignments from voicing library ("LH"/"RH")
+ * @param midiValues - Optional MIDI note numbers for accurate pitch ordering and span calculation.
+ *                     When provided, notes are sorted by actual pitch before splitting.
+ */
+export declare function assignFingering(notes: string[], handHints?: ("LH" | "RH")[], midiValues?: number[]): HandAssignment;
+/**
+ * Compute auto-fingering for a chord voicing (legacy API).
+ */
+export declare function autoFingering(notes: string[], hand?: Hand): number[];