@pepperhorn/chordl-core 0.3.0

package/dist/engine/auto-fingering.js

@@ -0,0 +1,344 @@
+import { normalizeToSharps, PC_SEMITONES as NOTE_SEMITONE } from "./note-spelling";
+/** Max playable span for a single hand: a 12th = 19 semitones */
+const MAX_HAND_SPAN = 19;
+/** Max notes a single hand can play */
+const MAX_HAND_NOTES = 5;
+const BLACK_NOTES = new Set(["C#", "D#", "F#", "G#", "A#"]);
+function normalize(note) {
+    return normalizeToSharps(note);
+}
+function isBlack(note) {
+    return BLACK_NOTES.has(normalize(note));
+}
+/** Ascending semitone interval between two pitch classes (mod 12). */
+function interval(a, b) {
+    const sa = NOTE_SEMITONE[normalize(a)];
+    const sb = NOTE_SEMITONE[normalize(b)];
+    if (sa == null || sb == null)
+        return 0;
+    return ((sb - sa) % 12 + 12) % 12;
+}
+/** Total ascending span of a note sequence in semitones (mod 12 per step). */
+function totalSpanMod12(notes) {
+    let span = 0;
+    for (let i = 1; i < notes.length; i++) {
+        span += interval(notes[i - 1], notes[i]);
+    }
+    return span;
+}
+/** Check if a set of notes is playable by one hand using mod-12 intervals. */
+function isOneHandPlayable(notes) {
+    return notes.length <= MAX_HAND_NOTES && totalSpanMod12(notes) <= MAX_HAND_SPAN;
+}
+/** Check if a set of MIDI values is playable by one hand. */
+function isOneHandPlayableMidi(midis) {
+    if (midis.length > MAX_HAND_NOTES)
+        return false;
+    if (midis.length <= 1)
+        return true;
+    const sorted = [...midis].sort((a, b) => a - b);
+    return sorted[sorted.length - 1] - sorted[0] <= MAX_HAND_SPAN;
+}
+// ── Fingering patterns ────────────────────────────────────────────
+/** Standard RH fingering patterns by note count. */
+const RH_PATTERNS = {
+    2: [[1, 5], [1, 3], [2, 5]],
+    3: [[1, 3, 5], [1, 2, 5], [1, 2, 4], [1, 3, 4], [2, 3, 5], [1, 2, 3]],
+    4: [[1, 2, 3, 5], [1, 2, 4, 5], [1, 2, 3, 4], [1, 3, 4, 5], [2, 3, 4, 5]],
+    5: [[1, 2, 3, 4, 5]],
+};
+/**
+ * Score a candidate fingering for a set of notes (RH perspective).
+ * Lower is better.
+ */
+function scoreFingering(notes, fingers) {
+    let penalty = 0;
+    for (let i = 0; i < notes.length; i++) {
+        if (fingers[i] === 1 && isBlack(notes[i]) && i !== 0) {
+            penalty += 10;
+        }
+        if (fingers[i] === 5 && isBlack(notes[i])) {
+            penalty += 2;
+        }
+    }
+    for (let i = 0; i < notes.length - 1; i++) {
+        const semitones = interval(notes[i], notes[i + 1]);
+        const fingerGap = Math.abs(fingers[i + 1] - fingers[i]);
+        if (semitones >= 5 && fingerGap <= 1) {
+            penalty += 5;
+        }
+        if (semitones <= 1 && fingerGap >= 3) {
+            penalty += 3;
+        }
+    }
+    if (fingers[0] !== 1)
+        penalty += 1;
+    const last = fingers[fingers.length - 1];
+    if (last !== 5 && last !== 4)
+        penalty += 1;
+    return penalty;
+}
+/** Pick the best fingering pattern for a single hand. */
+function fingerOneHand(notes, hand) {
+    const n = notes.length;
+    if (n === 0)
+        return [];
+    if (n === 1)
+        return [3];
+    const patterns = RH_PATTERNS[n];
+    if (!patterns)
+        return Array(n).fill(3);
+    let bestPattern = patterns[0];
+    let bestScore = Infinity;
+    for (const pattern of patterns) {
+        const score = scoreFingering(notes, pattern);
+        if (score < bestScore) {
+            bestScore = score;
+            bestPattern = pattern;
+        }
+    }
+    // LH: mirror via (5+1)-f so 1↔5, 2↔4, 3 stays
+    if (hand === "lh") {
+        return bestPattern.map((f) => 6 - f);
+    }
+    return bestPattern;
+}
+/**
+ * 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 function assignFingering(notes, handHints, midiValues) {
+    const n = notes.length;
+    if (n === 0)
+        return { fingering: [], hands: [] };
+    // If hand hints are provided (from voicing library), use them directly
+    if (handHints && handHints.length === n) {
+        return fingerWithHints(notes, handHints);
+    }
+    // When MIDI values are provided, sort by actual pitch to avoid crossing
+    if (midiValues && midiValues.length === n) {
+        return assignFingeringByMidi(notes, midiValues);
+    }
+    // Fallback: pitch-class-only mode (mod 12)
+    if (isOneHandPlayable(notes)) {
+        const fingers = fingerOneHand(notes, "rh");
+        return { fingering: fingers, hands: Array(n).fill("rh") };
+    }
+    const splitIdx = findSplitPointMod12(notes);
+    return splitAndFinger(notes, splitIdx);
+}
+/**
+ * MIDI-aware fingering: sorts notes by actual pitch, splits, and maps back
+ * to original order.
+ */
+function assignFingeringByMidi(notes, midiValues) {
+    const n = notes.length;
+    // Create index array sorted by MIDI pitch (ascending)
+    const sortedIndices = Array.from({ length: n }, (_, i) => i)
+        .sort((a, b) => midiValues[a] - midiValues[b]);
+    const sortedNotes = sortedIndices.map((i) => notes[i]);
+    const sortedMidis = sortedIndices.map((i) => midiValues[i]);
+    // Check if playable by one hand using actual MIDI span
+    if (isOneHandPlayableMidi(sortedMidis)) {
+        const fingers = fingerOneHand(sortedNotes, "rh");
+        // Map back to original order
+        const fingering = new Array(n);
+        const hands = new Array(n);
+        sortedIndices.forEach((origIdx, sortIdx) => {
+            fingering[origIdx] = fingers[sortIdx];
+            hands[origIdx] = "rh";
+        });
+        return { fingering, hands };
+    }
+    // Find best split point using actual MIDI distances
+    const splitIdx = findSplitPointMidi(sortedNotes, sortedMidis);
+    const lhNotes = sortedNotes.slice(0, splitIdx);
+    const rhNotes = sortedNotes.slice(splitIdx);
+    const lhFingers = fingerOneHand(lhNotes, "lh");
+    const rhFingers = fingerOneHand(rhNotes, "rh");
+    // Map back to original order
+    const fingering = new Array(n);
+    const hands = new Array(n);
+    sortedIndices.forEach((origIdx, sortIdx) => {
+        if (sortIdx < splitIdx) {
+            fingering[origIdx] = lhFingers[sortIdx];
+            hands[origIdx] = "lh";
+        }
+        else {
+            fingering[origIdx] = rhFingers[sortIdx - splitIdx];
+            hands[origIdx] = "rh";
+        }
+    });
+    return { fingering, hands };
+}
+/** Split and finger using sorted note order. */
+function splitAndFinger(notes, splitIdx) {
+    const lhNotes = notes.slice(0, splitIdx);
+    const rhNotes = notes.slice(splitIdx);
+    const lhFingers = fingerOneHand(lhNotes, "lh");
+    const rhFingers = fingerOneHand(rhNotes, "rh");
+    return {
+        fingering: [...lhFingers, ...rhFingers],
+        hands: [
+            ...Array(lhNotes.length).fill("lh"),
+            ...Array(rhNotes.length).fill("rh"),
+        ],
+    };
+}
+/** Use voicing library hand hints to finger each hand independently. */
+function fingerWithHints(notes, hints) {
+    const lhIndices = [];
+    const rhIndices = [];
+    for (let i = 0; i < notes.length; i++) {
+        if (hints[i] === "LH")
+            lhIndices.push(i);
+        else
+            rhIndices.push(i);
+    }
+    const lhNotes = lhIndices.map((i) => notes[i]);
+    const rhNotes = rhIndices.map((i) => notes[i]);
+    const lhFingers = fingerOneHand(lhNotes, "lh");
+    const rhFingers = fingerOneHand(rhNotes, "rh");
+    const fingering = new Array(notes.length);
+    const hands = new Array(notes.length);
+    lhIndices.forEach((idx, i) => {
+        fingering[idx] = lhFingers[i];
+        hands[idx] = "lh";
+    });
+    rhIndices.forEach((idx, i) => {
+        fingering[idx] = rhFingers[i];
+        hands[idx] = "rh";
+    });
+    return { fingering, hands };
+}
+/**
+ * Find split point using actual MIDI values — guaranteed no hand crossing.
+ *
+ * Levine-style:
+ * - LH gets 1-3 lower notes (root + guide tones)
+ * - RH gets upper notes (extensions)
+ * - Prefer split at the widest MIDI gap
+ */
+/** Largest interval between adjacent notes in a sorted MIDI array. */
+function maxAdjacentStretch(midis) {
+    let max = 0;
+    for (let i = 1; i < midis.length; i++) {
+        max = Math.max(max, midis[i] - midis[i - 1]);
+    }
+    return max;
+}
+/**
+ * Find split point using actual MIDI values — guaranteed no hand crossing.
+ *
+ * Scoring priorities (highest to lowest):
+ * 1. Minimize worst-case stretch — penalize the hand with the biggest
+ *    inter-note gap. If LH has spare capacity, absorb notes to give RH room.
+ * 2. Prefer split at wider MIDI gaps — natural hand separation.
+ * 3. Levine-style preferences — LH 1-3 notes, RH 3-4 notes.
+ * 4. Balance note count between hands.
+ */
+function findSplitPointMidi(sortedNotes, sortedMidis) {
+    const n = sortedNotes.length;
+    let bestSplit = Math.min(2, n - 1);
+    let bestScore = Infinity;
+    for (let split = 1; split < n; split++) {
+        const lhMidis = sortedMidis.slice(0, split);
+        const rhMidis = sortedMidis.slice(split);
+        // Both hands must be playable
+        if (split > MAX_HAND_NOTES || (n - split) > MAX_HAND_NOTES)
+            continue;
+        const lhSpan = lhMidis[lhMidis.length - 1] - lhMidis[0];
+        const rhSpan = rhMidis[rhMidis.length - 1] - rhMidis[0];
+        if (lhSpan > MAX_HAND_SPAN || rhSpan > MAX_HAND_SPAN)
+            continue;
+        let score = 0;
+        const lhCount = split;
+        const rhCount = n - split;
+        // 1. STRAIN BALANCE — minimize the worst stretch in either hand.
+        const lhStretch = maxAdjacentStretch(lhMidis);
+        const rhStretch = maxAdjacentStretch(rhMidis);
+        const worstStretch = Math.max(lhStretch, rhStretch);
+        score += worstStretch * 5;
+        // 2. LOAD BALANCE — penalize hands at max capacity (5 notes = no slack).
+        //    A hand with spare fingers can accommodate stretches more comfortably.
+        //    Reward splits where both hands have breathing room.
+        const lhLoad = lhCount / MAX_HAND_NOTES; // 0.2 to 1.0
+        const rhLoad = rhCount / MAX_HAND_NOTES;
+        const loadImbalance = Math.abs(lhLoad - rhLoad);
+        score += loadImbalance * 8;
+        // Extra penalty when either hand is maxed out at 5 notes
+        if (lhCount === MAX_HAND_NOTES || rhCount === MAX_HAND_NOTES) {
+            score += 4;
+        }
+        // 3. Prefer wider MIDI gap at the split point — natural hand separation
+        const gap = sortedMidis[split] - sortedMidis[split - 1];
+        score -= gap * 3;
+        // 4. Levine-style: LH with 1-3 notes (root + guide tones)
+        if (lhCount >= 1 && lhCount <= 3)
+            score -= 4;
+        // 5. Prefer RH with 3-4 notes
+        if (rhCount >= 3 && rhCount <= 4)
+            score -= 2;
+        if (score < bestScore) {
+            bestScore = score;
+            bestSplit = split;
+        }
+    }
+    return bestSplit;
+}
+/** Fallback split point using mod-12 intervals (no MIDI data). */
+function findSplitPointMod12(notes) {
+    const n = notes.length;
+    let bestSplit = Math.min(2, n - 1);
+    let bestScore = Infinity;
+    for (let split = 1; split < n; split++) {
+        const lhNotes = notes.slice(0, split);
+        const rhNotes = notes.slice(split);
+        if (split > MAX_HAND_NOTES || (n - split) > MAX_HAND_NOTES)
+            continue;
+        if (totalSpanMod12(lhNotes) > MAX_HAND_SPAN || totalSpanMod12(rhNotes) > MAX_HAND_SPAN)
+            continue;
+        let score = 0;
+        // Strain balance: penalize the hand with biggest adjacent interval
+        let lhMaxGap = 0;
+        for (let i = 1; i < split; i++)
+            lhMaxGap = Math.max(lhMaxGap, interval(notes[i - 1], notes[i]));
+        let rhMaxGap = 0;
+        for (let i = split + 1; i < n; i++)
+            rhMaxGap = Math.max(rhMaxGap, interval(notes[i - 1], notes[i]));
+        score += Math.max(lhMaxGap, rhMaxGap) * 5;
+        const gapSemitones = interval(notes[split - 1], notes[split]);
+        score -= gapSemitones * 3;
+        if (split >= 1 && split <= 3)
+            score -= 4;
+        if ((n - split) >= 3 && (n - split) <= 4)
+            score -= 2;
+        score += Math.abs(split - (n - split));
+        if (score < bestScore) {
+            bestScore = score;
+            bestSplit = split;
+        }
+    }
+    return bestSplit;
+}
+// ── Legacy API ────────────────────────────────────────────────────
+/**
+ * Compute auto-fingering for a chord voicing (legacy API).
+ */
+export function autoFingering(notes, hand = "rh") {
+    const n = notes.length;
+    if (n === 0)
+        return [];
+    if (n === 1)
+        return [3];
+    if (isOneHandPlayable(notes)) {
+        return fingerOneHand(notes, hand);
+    }
+    const result = assignFingering(notes);
+    return result.fingering;
+}
+//# sourceMappingURL=auto-fingering.js.map

package/dist/engine/auto-fingering.js.map

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

package/dist/engine/highlight-mapper.d.ts

@@ -0,0 +1,3 @@
+import type { KeyDescriptor, ColorTheme } from "../types";
+export declare function normalizeNote(note: string): string;
+export declare function mapHighlights(keys: KeyDescriptor[], highlightKeys: string[], theme?: ColorTheme): string[];

package/dist/engine/highlight-mapper.js

@@ -0,0 +1,46 @@
+import { DEFAULT_WHITE_FILL, DEFAULT_BLACK_FILL } from "./svg-constants";
+import { normalizeToSharps } from "./note-spelling";
+export function normalizeNote(note) {
+    return normalizeToSharps(note);
+}
+/**
+ * Normalize a highlight key. Supports octave-qualified format "note:octave"
+ * (e.g., "A#:0", "C:1") for multi-octave keyboards.
+ */
+function normalizeHighlightKey(key) {
+    const colonIdx = key.indexOf(":");
+    if (colonIdx !== -1) {
+        const note = normalizeNote(key.slice(0, colonIdx));
+        const octave = parseInt(key.slice(colonIdx + 1), 10);
+        return { note, octave };
+    }
+    return { note: normalizeNote(key), octave: null };
+}
+export function mapHighlights(keys, highlightKeys, theme) {
+    const normalized = highlightKeys.map(normalizeHighlightKey);
+    const remaining = [...normalized];
+    return keys.map((key) => {
+        const keyNote = normalizeNote(key.note);
+        const matchIndex = remaining.findIndex((h) => {
+            if (h.note !== keyNote)
+                return false;
+            if (h.octave !== null && h.octave !== key.octave)
+                return false;
+            return true;
+        });
+        const isHighlighted = matchIndex !== -1;
+        if (isHighlighted) {
+            remaining.splice(matchIndex, 1);
+        }
+        if (theme) {
+            return key.isBlack
+                ? theme.blackKey(keyNote, isHighlighted)
+                : theme.whiteKey(keyNote, isHighlighted);
+        }
+        if (isHighlighted) {
+            return key.isBlack ? "#5a8ab5" : "#a0c6e8";
+        }
+        return key.isBlack ? DEFAULT_BLACK_FILL : DEFAULT_WHITE_FILL;
+    });
+}
+//# sourceMappingURL=highlight-mapper.js.map

package/dist/engine/highlight-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlight-mapper.js","sourceRoot":"","sources":["../../src/engine/highlight-mapper.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,SAAS,qBAAqB,CAAC,GAAW;IACxC,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACrD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC1B,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,IAAqB,EACrB,aAAuB,EACvB,KAAkB;IAElB,MAAM,UAAU,GAAG,aAAa,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;IAElC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACtB,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,UAAU,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;YAC3C,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO;gBAAE,OAAO,KAAK,CAAC;YACrC,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM;gBAAE,OAAO,KAAK,CAAC;YAC/D,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;QACH,MAAM,aAAa,GAAG,UAAU,KAAK,CAAC,CAAC,CAAC;QAExC,IAAI,aAAa,EAAE,CAAC;YAClB,SAAS,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,GAAG,CAAC,OAAO;gBAChB,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;gBACxC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAC7C,CAAC;QAED,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7C,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,kBAAkB,CAAC;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/engine/keyboard-layout.d.ts

@@ -0,0 +1,6 @@
+import type { Format, WhiteNote, KeyDescriptor } from "../types";
+export declare function computeKeyboard(startFrom?: WhiteNote, size?: number, format?: Format): KeyDescriptor[];
+export declare function computeSvgDimensions(size: number, format?: Format): {
+    width: number;
+    height: number;
+};

package/dist/engine/keyboard-layout.js

@@ -0,0 +1,65 @@
+import { WHITE_KEY_WIDTH, WHITE_KEY_WIDTH_EXACT, WHITE_KEY_HEIGHT_COMPACT, WHITE_KEY_HEIGHT_EXACT, BLACK_KEY_WIDTH, BLACK_KEY_WIDTH_EXACT, BLACK_KEY_HEIGHT_COMPACT, BLACK_KEY_HEIGHT_EXACT, BLACK_KEY_OFFSETS, BLACK_KEY_OFFSETS_EXACT, WHITE_NOTES_WITH_SHARPS, WHITE_NOTE_ORDER, } from "./svg-constants";
+const SHARP_SUFFIX = {
+    C: "C#",
+    D: "D#",
+    F: "F#",
+    G: "G#",
+    A: "A#",
+};
+export function computeKeyboard(startFrom = "C", size = 8, format = "compact") {
+    const isExact = format === "exact";
+    const whiteHeight = isExact ? WHITE_KEY_HEIGHT_EXACT : WHITE_KEY_HEIGHT_COMPACT;
+    const blackHeight = isExact ? BLACK_KEY_HEIGHT_EXACT : BLACK_KEY_HEIGHT_COMPACT;
+    const whiteW = isExact ? WHITE_KEY_WIDTH_EXACT : WHITE_KEY_WIDTH;
+    const blackW = isExact ? BLACK_KEY_WIDTH_EXACT : BLACK_KEY_WIDTH;
+    const offsets = isExact ? BLACK_KEY_OFFSETS_EXACT : BLACK_KEY_OFFSETS;
+    const keys = [];
+    const startIndex = WHITE_NOTE_ORDER.indexOf(startFrom);
+    // Offset by half stroke width so left border isn't clipped
+    let whiteX = 0.5;
+    let relativeOctave = 0;
+    for (let i = 0; i < size; i++) {
+        const noteIndex = (startIndex + i) % 7;
+        const whiteNote = WHITE_NOTE_ORDER[noteIndex];
+        // Octave increments each time we cross C
+        if (i > 0 && whiteNote === "C") {
+            relativeOctave++;
+        }
+        // Add white key
+        keys.push({
+            note: whiteNote,
+            octave: relativeOctave,
+            isBlack: false,
+            x: whiteX,
+            y: 0,
+            width: whiteW,
+            height: whiteHeight,
+        });
+        // Add black key if this white note has one
+        if (WHITE_NOTES_WITH_SHARPS.has(whiteNote)) {
+            const offset = offsets[whiteNote];
+            keys.push({
+                note: SHARP_SUFFIX[whiteNote],
+                octave: relativeOctave,
+                isBlack: true,
+                x: whiteX + offset,
+                y: 0,
+                width: blackW,
+                height: blackHeight,
+            });
+        }
+        whiteX += whiteW;
+    }
+    return keys;
+}
+export function computeSvgDimensions(size, format = "compact") {
+    const isExact = format === "exact";
+    const keyHeight = isExact ? WHITE_KEY_HEIGHT_EXACT : WHITE_KEY_HEIGHT_COMPACT;
+    const whiteW = isExact ? WHITE_KEY_WIDTH_EXACT : WHITE_KEY_WIDTH;
+    // Add padding so strokes + rounded corners aren't clipped at edges
+    return {
+        width: size * whiteW + 1,
+        height: keyHeight + 2,
+    };
+}
+//# sourceMappingURL=keyboard-layout.js.map

package/dist/engine/keyboard-layout.js.map

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

package/dist/engine/note-spelling.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Consolidated enharmonic spelling logic.
+ *
+ * Single source of truth for flat↔sharp conversion, key-context-aware
+ * note spelling, and pitch class normalization.
+ */
+/** Convert flat note names to their sharp equivalents. */
+export declare const FLAT_TO_SHARP: Record<string, string>;
+/** Convert sharp note names to their flat equivalents. */
+export declare const SHARP_TO_FLAT: Record<string, string>;
+/**
+ * Keys whose notes should be spelled with flats.
+ * Includes both major flat keys and enharmonic equivalents.
+ */
+export declare const FLAT_KEYS: Set<string>;
+/**
+ * Normalize a pitch class to sharps for internal matching.
+ * e.g. "Bb" → "A#", "Db" → "C#", "C" → "C"
+ */
+export declare function normalizeToSharps(note: string): string;
+/**
+ * Spell a pitch class to match the key context of the given root.
+ * Flat-key roots get flat spelling; sharp-key roots keep sharp spelling.
+ *
+ * e.g. spellForKey("A#", "Bb") → "Bb"
+ *      spellForKey("Bb", "E")  → "A#"
+ */
+export declare function spellForKey(pc: string, key: string): string;
+/**
+ * Choose enharmonic spelling with explicit flat preference.
+ * Used for roman numeral accidentals (bVII → flat spelling regardless of key).
+ */
+export declare function spellWithPreference(note: string, key: string, preferFlat?: boolean): string;
+/**
+ * Pitch class to semitone value (0-11). Handles both sharps and flats.
+ * C=0, C#/Db=1, D=2, D#/Eb=3, E=4, F=5, F#/Gb=6, G=7, G#/Ab=8, A=9, A#/Bb=10, B=11
+ */
+export declare const PC_SEMITONES: Record<string, number>;
+/** A3 MIDI value — default floor for scale starting notes. */
+export declare const MIDI_A3 = 57;
+/**
+ * Assign ascending octaves to an array of pitch classes.
+ * Each note that would descend (lower semitone than previous) bumps the octave.
+ * Optionally compacts the result to stay within a maximum span.
+ *
+ * @param notes - Sharp-normalized pitch classes in voicing/scale order
+ * @param baseOctave - Starting octave for the first note
+ * @param maxSpan - Maximum semitone span before folding (0 = no limit)
+ * @returns Array of { note, octave } pairs
+ */
+export declare function assignAscendingOctaves(notes: string[], baseOctave: number, maxSpan?: number): Array<{
+    note: string;
+    octave: number;
+}>;

package/dist/engine/note-spelling.js

@@ -0,0 +1,103 @@
+/**
+ * Consolidated enharmonic spelling logic.
+ *
+ * Single source of truth for flat↔sharp conversion, key-context-aware
+ * note spelling, and pitch class normalization.
+ */
+/** Convert flat note names to their sharp equivalents. */
+export const FLAT_TO_SHARP = {
+    Db: "C#", Eb: "D#", Gb: "F#", Ab: "G#", Bb: "A#",
+};
+/** Convert sharp note names to their flat equivalents. */
+export const SHARP_TO_FLAT = {
+    "C#": "Db", "D#": "Eb", "F#": "Gb", "G#": "Ab", "A#": "Bb",
+};
+/**
+ * Keys whose notes should be spelled with flats.
+ * Includes both major flat keys and enharmonic equivalents.
+ */
+export const FLAT_KEYS = new Set([
+    "F", "Bb", "Eb", "Ab", "Db", "Gb", "Cb",
+]);
+/**
+ * Normalize a pitch class to sharps for internal matching.
+ * e.g. "Bb" → "A#", "Db" → "C#", "C" → "C"
+ */
+export function normalizeToSharps(note) {
+    return FLAT_TO_SHARP[note] ?? note;
+}
+/**
+ * Spell a pitch class to match the key context of the given root.
+ * Flat-key roots get flat spelling; sharp-key roots keep sharp spelling.
+ *
+ * e.g. spellForKey("A#", "Bb") → "Bb"
+ *      spellForKey("Bb", "E")  → "A#"
+ */
+export function spellForKey(pc, key) {
+    if (FLAT_KEYS.has(key)) {
+        return SHARP_TO_FLAT[pc] ?? pc;
+    }
+    return FLAT_TO_SHARP[pc] ?? pc;
+}
+/**
+ * Choose enharmonic spelling with explicit flat preference.
+ * Used for roman numeral accidentals (bVII → flat spelling regardless of key).
+ */
+export function spellWithPreference(note, key, preferFlat = false) {
+    if (preferFlat) {
+        return SHARP_TO_FLAT[note] ?? note;
+    }
+    return spellForKey(note, key);
+}
+// ── Semitone mapping (canonical, replaces duplicates across codebase) ──
+/**
+ * Pitch class to semitone value (0-11). Handles both sharps and flats.
+ * C=0, C#/Db=1, D=2, D#/Eb=3, E=4, F=5, F#/Gb=6, G=7, G#/Ab=8, A=9, A#/Bb=10, B=11
+ */
+export const PC_SEMITONES = {
+    C: 0, "C#": 1, Db: 1,
+    D: 2, "D#": 3, Eb: 3,
+    E: 4, Fb: 4, "E#": 5,
+    F: 5, "F#": 6, Gb: 6,
+    G: 7, "G#": 8, Ab: 8,
+    A: 9, "A#": 10, Bb: 10,
+    B: 11, Cb: 11, "B#": 0,
+};
+/** A3 MIDI value — default floor for scale starting notes. */
+export const MIDI_A3 = 57;
+/**
+ * Assign ascending octaves to an array of pitch classes.
+ * Each note that would descend (lower semitone than previous) bumps the octave.
+ * Optionally compacts the result to stay within a maximum span.
+ *
+ * @param notes - Sharp-normalized pitch classes in voicing/scale order
+ * @param baseOctave - Starting octave for the first note
+ * @param maxSpan - Maximum semitone span before folding (0 = no limit)
+ * @returns Array of { note, octave } pairs
+ */
+export function assignAscendingOctaves(notes, baseOctave, maxSpan = 0) {
+    if (notes.length === 0)
+        return [];
+    let octave = baseOctave;
+    let prevSemi = PC_SEMITONES[notes[0]] ?? 0;
+    const result = notes.map((n, i) => {
+        const semi = PC_SEMITONES[n] ?? 0;
+        if (i > 0 && semi <= prevSemi) {
+            octave++;
+        }
+        prevSemi = semi;
+        return { note: n, octave };
+    });
+    // Optional compaction: fold notes down if span exceeds limit
+    if (maxSpan > 0 && result.length > 1) {
+        const baseSemi = (PC_SEMITONES[result[0].note] ?? 0) + result[0].octave * 12;
+        for (let i = 1; i < result.length; i++) {
+            const noteSemi = (PC_SEMITONES[result[i].note] ?? 0) + result[i].octave * 12;
+            if (noteSemi - baseSemi > maxSpan && result[i].octave > result[0].octave) {
+                result[i].octave--;
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=note-spelling.js.map