@pepperhorn/chordl-core 0.3.4 → 0.4.0

package/dist/theory/hand-constraints.js

@@ -0,0 +1,214 @@
+/**
+ * Keyboard reach constraints.
+ *
+ * Two orthogonal limits, both required:
+ *   - maxSpanPerHand — physical reach, in semitones
+ *   - maxNotesPerHand — coordination, in note count
+ *
+ * Count alone does not express reach: a 3-note cap still admits C-E-C', three
+ * notes spanning a full octave, which a young player cannot stretch. The
+ * converse also holds — a 4-note cluster inside a 5th is an easy reach but
+ * harder to coordinate.
+ *
+ * Deriving a junior cutoff from "no 7ths or octaves": a 7th spans 10-11
+ * semitones and an octave 12, so maxSpanPerHand 9 (a major 6th) is binding.
+ */
+import { PC_SEMITONES, assignAscendingOctaves } from "../engine/note-spelling.js";
+/**
+ * MIDI number for a pitch class in a given octave, C4 = 60.
+ *
+ * PC_SEMITONES handles both sharps and flats, so no spelling normalization is
+ * needed here.
+ */
+export function midiOf(note, octave) {
+    const semi = PC_SEMITONES[note] ?? 0;
+    return semi + (octave + 1) * 12;
+}
+/**
+ * Stack pitch classes into an ascending voicing.
+ *
+ * @param notes - pitch classes in voicing order
+ * @param baseOctave - octave of the first note
+ * @param maxSpan - optional semitone limit; folds notes down where it can
+ *   (0 = no folding). Folding is preferred over dropping because it keeps
+ *   every chord tone.
+ */
+export function placeAscending(notes, baseOctave, maxSpan = 0) {
+    return assignAscendingOctaves(notes, baseOctave, maxSpan).map(({ note, octave }) => ({
+        note,
+        octave,
+        midi: midiOf(note, octave),
+    }));
+}
+/** Semitones between the lowest and highest pitch. Zero for 0 or 1 notes. */
+export function spanOf(pitches) {
+    if (pitches.length < 2)
+        return 0;
+    return Math.max(...pitches) - Math.min(...pitches);
+}
+const DEFAULT_HAND = "LH";
+/**
+ * Fewest notes a hand may be reduced to. A dyad is already a shell voicing —
+ * below that there is no chord left to name, so reduction stops and reports
+ * failure rather than returning a single note as a satisfied chord.
+ */
+const MIN_NOTES_PER_HAND = 2;
+/**
+ * Semitone value for matching pitch classes across spellings.
+ *
+ * `PC_SEMITONES` maps sharps and flats onto the same number, so "Bb" and "A#"
+ * compare equal — necessary because chordl-voicings spells library variants
+ * with sharps while core's resolver yields flats. Unknown spellings map to -1
+ * rather than 0 so they never collide with C.
+ */
+export function pcSemitone(note) {
+    return PC_SEMITONES[note] ?? -1;
+}
+function groupsOf(notes) {
+    const byHand = new Map();
+    for (const n of notes) {
+        const list = byHand.get(n.hand);
+        if (list)
+            list.push(n);
+        else
+            byHand.set(n.hand, [n]);
+    }
+    return [...byHand.values()];
+}
+function withinCaps(groups, c, maxNotes) {
+    return groups.every((g) => g.length <= maxNotes && spanOf(g.map((n) => n.midi)) <= c.maxSpanPerHand);
+}
+/**
+ * Place a subset of the voicing (by index) and settle each hand's octaves.
+ *
+ * Step 1 stacks the whole subset ascending with no folding, so the voicing's
+ * true shape is preserved. Step 2 groups the result by hand and re-folds
+ * only the hands whose span exceeds the cap — folding is per-hand because
+ * two hands an octave apart should not be squeezed together just because
+ * the whole voicing looks wide. Step 3 collapses duplicate MIDI numbers
+ * (same key, one finger) so they cost one slot of the note-count budget.
+ */
+function place(indices, notes, baseOctave, maxSpanPerHand, handOf) {
+    const notesForThisCall = indices.map((i) => notes[i]);
+    // Step 1: Place ascending with NO folding to preserve the voicing's true shape.
+    const unfolded = placeAscending(notesForThisCall, baseOctave, 0).map((p, i) => ({ ...p, originalIndex: indices[i], hand: handOf(indices[i]) }));
+    // Step 2: Group by hand and re-fold each hand independently if needed.
+    const handToNotes = new Map();
+    for (const p of unfolded) {
+        const list = handToNotes.get(p.hand);
+        if (list)
+            list.push(p);
+        else
+            handToNotes.set(p.hand, [p]);
+    }
+    const refolded = [];
+    for (const [hand, notesInHand] of handToNotes) {
+        const span = spanOf(notesInHand.map((n) => n.midi));
+        if (span <= maxSpanPerHand) {
+            // Already fits, use as-is
+            refolded.push(...notesInHand);
+            continue;
+        }
+        // Exceeds span, re-fold this hand's notes
+        const refoldedHand = placeAscending(notesInHand.map((n) => n.note), notesInHand[0].octave, maxSpanPerHand);
+        for (let i = 0; i < refoldedHand.length; i++) {
+            refolded.push({
+                ...refoldedHand[i],
+                originalIndex: notesInHand[i].originalIndex,
+                hand,
+            });
+        }
+    }
+    // Restore original voicing order by sorting by originalIndex.
+    refolded.sort((a, b) => a.originalIndex - b.originalIndex);
+    // Step 3: Two notes on the same MIDI number are one key under one finger.
+    // Collapse them so they cost one slot of the note-count budget, not two.
+    // The first in voicing order wins, so the surviving spelling and hand are
+    // the ones the voicing led with.
+    const seenMidi = new Set();
+    return refolded.filter((p) => {
+        if (seenMidi.has(p.midi))
+            return false;
+        seenMidi.add(p.midi);
+        return true;
+    });
+}
+/**
+ * Fit a voicing inside a hand's reach and note count.
+ *
+ * Strategy, in order:
+ *   1. Fold octaves — keeps every chord tone, so it is always preferred.
+ *   2. Drop notes in `dropOrder`, never below `keepAtLeast`, and never below
+ *      two notes in any one hand.
+ *
+ * `dropOrder` and `keepAtLeast` are matched by semitone rather than by
+ * spelling, so a drop order written in flats still recognises a voicing
+ * spelled in sharps. Each returned note keeps its own original spelling —
+ * only the matching normalizes.
+ *
+ * When the constraints still cannot be met without dropping an identity tone
+ * or taking a hand below a dyad, returns the closest legal voicing with
+ * `satisfied: false` rather than returning nothing or a chord that is no
+ * longer the chord asked for. Callers wanting a voicing that genuinely fits
+ * should try other variants — an inversion often fits where root position
+ * cannot.
+ */
+export function constrainVoicing(input) {
+    const baseOctave = input.baseOctave ?? 3;
+    const maxNotes = Math.max(MIN_NOTES_PER_HAND, input.constraints.maxNotesPerHand);
+    const keepSemitones = new Set(input.keepAtLeast.map(pcSemitone));
+    const handOf = (originalIndex) => input.handHints?.[originalIndex] ?? DEFAULT_HAND;
+    // Track note indices instead of strings to handle duplicates correctly.
+    // Each entry is an index into input.notes.
+    let working = input.notes.map((_, i) => i);
+    const dropped = [];
+    for (;;) {
+        const placed = place(working, input.notes, baseOctave, input.constraints.maxSpanPerHand, handOf);
+        // A collapsed duplicate is gone from the result, so drop it from `working`
+        // too — otherwise the drop loop would keep offering a note the caller can
+        // no longer see. `working` only ever shrinks, so this terminates.
+        if (placed.length < working.length) {
+            working = placed.map((p) => p.originalIndex);
+            continue;
+        }
+        const groups = groupsOf(placed);
+        const result = (satisfied) => ({
+            notes: placed.map((p) => ({ note: p.note, octave: p.octave, midi: p.midi, hand: p.hand })),
+            dropped,
+            span: Math.max(0, ...groups.map((g) => spanOf(g.map((n) => n.midi)))),
+            satisfied,
+        });
+        if (withinCaps(groups, input.constraints, maxNotes))
+            return result(true);
+        const notesPerHand = new Map();
+        for (const n of placed)
+            notesPerHand.set(n.hand, (notesPerHand.get(n.hand) ?? 0) + 1);
+        // Find the next note to drop: earliest in dropOrder, not an identity tone,
+        // and not the note that would take its hand below a dyad. Candidates are
+        // matched by semitone so spelling differences do not hide them.
+        let target = -1;
+        for (const pc of input.dropOrder) {
+            const semitone = pcSemitone(pc);
+            if (keepSemitones.has(semitone))
+                continue;
+            // Remove the LAST occurrence of this pitch class (conventional choice).
+            for (let i = working.length - 1; i >= 0; i--) {
+                if (pcSemitone(input.notes[working[i]]) !== semitone)
+                    continue;
+                if ((notesPerHand.get(handOf(working[i])) ?? 0) <= MIN_NOTES_PER_HAND)
+                    continue;
+                target = i;
+                break;
+            }
+            if (target >= 0)
+                break;
+        }
+        // Nothing left that may be dropped: every remaining note is an identity
+        // tone, or dropping it would leave a hand with fewer than two notes.
+        if (target < 0)
+            return result(false);
+        dropped.push(input.notes[working[target]]);
+        working.splice(target, 1);
+    }
+}
+//# sourceMappingURL=hand-constraints.js.map

package/dist/theory/hand-constraints.js.map

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

package/dist/types.d.ts

@@ -2,7 +2,7 @@ export type Format = "compact" | "exact";
 /** Tailwind-inspired text size scale for annotations. */
 export type TextSize = "base" | "lg" | "xl" | "2xl";
 /** Note name display mode. */
-export type NoteNameMode = "pitch-class" | "midi" | "degree" | "pitch-class+degree";
+export type NoteNameMode = "pitch-class" | "midi" | "degree" | "pitch-class+degree" | "midi+degree";
 export type WhiteNote = "C" | "D" | "E" | "F" | "G" | "A" | "B";
 export type NoteName = string;
 export interface ColorTheme {
@@ -34,6 +34,12 @@ export interface ParsedChordRequest {
     noteNameSize?: TextSize;
     /** Note name display mode: pitch-class (default) or midi (with octave numbers). */
     noteNameMode?: NoteNameMode;
+    /**
+     * Text size for degree labels. Independent of `noteNameSize` because the two
+     * are asked for separately — "note names in xl with degrees in lg" is one
+     * request with two sizes in it. Absent falls back to the note-name size.
+     */
+    degreeSize?: TextSize;
     /** Fingering values (aligned with chord notes). Numbers 1–5 plus extra symbols (0, -, x). Invalid entries become "?". */
     fingering?: (number | string)[];
     /** Auto-compute fingering when true (no explicit numbers given). */
@@ -75,6 +81,8 @@ export interface NotesGroup {
     hand?: "lh" | "rh";
     /** Clef context: affects inferred base octave and implies a hand. */
     clef?: "bass" | "treble";
+    /** Source chord symbol when the group came from one ("rh Cmaj7"). */
+    chord?: string;
 }
 export interface KeyDescriptor {
     note: string;

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@pepperhorn/chordl-core",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Pure TypeScript chord parsing, resolving, layout, and export engine",
   "type": "module",
-  "main": "./dist/index.cjs",
+  "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -18,7 +18,7 @@
   ],
   "dependencies": {
     "tonal": "^6.3.0",
-    "@pepperhorn/chordl-voicings": "0.3.0"
+    "@pepperhorn/chordl-voicings": "0.4.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0",