@pepperhorn/chordl-core 0.3.4 → 0.5.0

package/dist/theory/starting-note.d.ts

@@ -0,0 +1,43 @@
+/**
+ * "Starting on X" — the rule that decides which chord tone sits at the bottom.
+ *
+ * This lives in the theory layer rather than in a renderer because more than
+ * one view of a chord has to agree about it. `PianoChord` rotates the voicing
+ * it draws; the board's player rotates the voicing it *sounds*. A second copy
+ * of the rule in the second caller is the one kind of drift nothing on screen
+ * would reveal — the card would draw a first inversion and play root position,
+ * silently, so both call this.
+ *
+ * Degree resolution ("starting on the 3rd") lives here for the same reason: it
+ * is the first half of the same clause, and `bassDegree` ("over the 3rd") uses
+ * the identical lookup.
+ */
+/** Ordinal names for the degrees a "starting on"/"over" clause can name. */
+export declare const DEGREE_NAMES: Record<number, string>;
+/**
+ * Find the chord tone matching a musical degree, regardless of quality.
+ * e.g. degree 3 finds Eb in Cm7 and E in Cmaj7.
+ */
+export declare function degreeToNote(root: string, degree: number, notes: string[]): string | undefined;
+/** Format the available degrees for error messages */
+export declare function describeAvailableDegrees(root: string, notes: string[]): string;
+export interface StartingNoteRotation {
+    /**
+     * Where the named note sits in the original list, or `-1` when the chord
+     * does not contain it. Callers distinguish the two "no rotation" cases from
+     * this: `0` is already the bottom note, `-1` is a note that isn't there.
+     */
+    index: number;
+    /** `notes` rotated so the named note is lowest — the input list when `index <= 0`. */
+    notes: string[];
+}
+/**
+ * Rotate a voicing so `startingNote` is its lowest note.
+ *
+ * Both sides are normalised before matching. `notes` keeps the chord's own
+ * spelling — Bbm is ["Bb", "Db", "F"] — so normalising only the input turned
+ * "Bbm starting on Db" into a search for "C#" and reported Db missing from a
+ * chord whose own error message listed it as the 3rd; matching literally is
+ * the mirror bug, and drops the rotation for "Bbm starting on C#".
+ */
+export declare function rotateToStartingNote(notes: string[], startingNote: string): StartingNoteRotation;

package/dist/theory/starting-note.js

@@ -0,0 +1,97 @@
+/**
+ * "Starting on X" — the rule that decides which chord tone sits at the bottom.
+ *
+ * This lives in the theory layer rather than in a renderer because more than
+ * one view of a chord has to agree about it. `PianoChord` rotates the voicing
+ * it draws; the board's player rotates the voicing it *sounds*. A second copy
+ * of the rule in the second caller is the one kind of drift nothing on screen
+ * would reveal — the card would draw a first inversion and play root position,
+ * silently, so both call this.
+ *
+ * Degree resolution ("starting on the 3rd") lives here for the same reason: it
+ * is the first half of the same clause, and `bassDegree` ("over the 3rd") uses
+ * the identical lookup.
+ */
+import { Note } from "tonal";
+import { FLAT_TO_SHARP } from "../engine/note-spelling.js";
+/**
+ * Map semitones (mod 12) from root to a scale degree number.
+ * Handles both major and minor variants of each degree.
+ * Note: does not distinguish quality (e.g. b9 vs M9 both map to degree 2).
+ * This means degree-based lookups may match the wrong quality in altered chords.
+ */
+function semitonesToDegree(semitones) {
+    const s = ((semitones % 12) + 12) % 12;
+    if (s === 0)
+        return 1;
+    if (s <= 2)
+        return 2; // m2=1, M2=2 (also 9th)
+    if (s <= 4)
+        return 3; // m3=3, M3=4
+    if (s === 5)
+        return 4; // P4=5 (also 11th)
+    if (s <= 7)
+        return 5; // d5=6, P5=7
+    if (s <= 9)
+        return 6; // m6=8, M6=9 (also 13th)
+    return 7; // m7=10, M7=11
+}
+/** Ordinal names for the degrees a "starting on"/"over" clause can name. */
+export const DEGREE_NAMES = {
+    1: "root", 2: "2nd", 3: "3rd", 4: "4th", 5: "5th", 6: "6th", 7: "7th",
+    9: "9th", 11: "11th", 13: "13th",
+};
+/**
+ * Find the chord tone matching a musical degree, regardless of quality.
+ * e.g. degree 3 finds Eb in Cm7 and E in Cmaj7.
+ */
+export function degreeToNote(root, degree, notes) {
+    const rootMidi = Note.midi(`${root}4`);
+    if (rootMidi == null)
+        return undefined;
+    // Normalize compound degrees: 9→2, 11→4, 13→6
+    const simpleDegree = degree > 7 ? degree - 7 : degree;
+    for (const note of notes) {
+        const noteMidi = Note.midi(`${note}4`);
+        if (noteMidi == null)
+            continue;
+        const semitones = ((noteMidi - rootMidi) % 12 + 12) % 12;
+        if (semitonesToDegree(semitones) === simpleDegree)
+            return note;
+    }
+    return undefined;
+}
+/** Format the available degrees for error messages */
+export function describeAvailableDegrees(root, notes) {
+    const rootMidi = Note.midi(`${root}4`);
+    if (rootMidi == null)
+        return notes.join(", ");
+    const degrees = [];
+    for (const note of notes) {
+        const noteMidi = Note.midi(`${note}4`);
+        if (noteMidi == null)
+            continue;
+        const semitones = ((noteMidi - rootMidi) % 12 + 12) % 12;
+        const deg = semitonesToDegree(semitones);
+        const name = DEGREE_NAMES[deg] ?? `${deg}th`;
+        degrees.push(`${name} (${note})`);
+    }
+    return degrees.join(", ");
+}
+/**
+ * Rotate a voicing so `startingNote` is its lowest note.
+ *
+ * Both sides are normalised before matching. `notes` keeps the chord's own
+ * spelling — Bbm is ["Bb", "Db", "F"] — so normalising only the input turned
+ * "Bbm starting on Db" into a search for "C#" and reported Db missing from a
+ * chord whose own error message listed it as the 3rd; matching literally is
+ * the mirror bug, and drops the rotation for "Bbm starting on C#".
+ */
+export function rotateToStartingNote(notes, startingNote) {
+    const norm = FLAT_TO_SHARP[startingNote] ?? startingNote;
+    const index = notes.findIndex((n) => (FLAT_TO_SHARP[n] ?? n) === norm);
+    if (index <= 0)
+        return { index, notes };
+    return { index, notes: [...notes.slice(index), ...notes.slice(0, index)] };
+}
+//# sourceMappingURL=starting-note.js.map

package/dist/theory/starting-note.js.map

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

package/dist/types.d.ts

@@ -2,9 +2,10 @@ 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 type PlaybackInstrument = "acoustic_grand_piano" | "electric_guitar_clean" | "ukulele";
 export interface ColorTheme {
     name: string;
     whiteKey: (note: string, highlighted: boolean) => string;
@@ -34,6 +35,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 +82,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;
@@ -105,6 +114,10 @@ export interface DisplayDefaults {
     noteNameMode?: NoteNameMode;
     showFingering?: boolean;
     fingeringSize?: TextSize;
+    /** Arpeggio tempo on a sixteenth-note grid. */
+    arpeggioBpm?: number;
+    /** Transient colour used to identify the note currently being attacked. */
+    playbackHighlightColor?: string;
 }
 export interface ChordData {
     /** NL string — source of truth for chord resolution. */
@@ -119,6 +132,11 @@ export interface ChordData {
     theme?: ColorTheme | string;
     highlightColor?: string;
     padding?: number;
+    arpeggioBpm?: number;
+    playbackHighlightColor?: string;
+    /** Ordered MIDI pitches for the exact rendered voicing. */
+    playbackNotes?: number[];
+    playbackInstrument?: PlaybackInstrument;
 }
 export interface SectionData {
     /** Section letter ID (auto-assigned "A","B",... if omitted). */

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "@pepperhorn/chordl-core",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "description": "Pure TypeScript chord parsing, resolving, layout, and export engine",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pepperhorn/chordl.git",
+    "directory": "packages/chordl-core"
+  },
   "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 +23,7 @@
   ],
   "dependencies": {
     "tonal": "^6.3.0",
-    "@pepperhorn/chordl-voicings": "0.3.0"
+    "@pepperhorn/chordl-voicings": "0.4.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0",