@pepperhorn/chordl-core 0.3.4 → 0.4.0

package/dist/resolver/scale-resolver.d.ts

@@ -3,7 +3,10 @@ export interface ResolvedScale {
     notes: string[];
     root: string;
     type: string;
-    /** Single-octave Tonal intervals (e.g. ["1P","2M","3M","4P","5P","6M","7M"]). */
+    /** Single-octave Tonal intervals (e.g. ["1P","2M","3M","4P","5P","6M","7M"]),
+     *  rotated to match `notes` when a custom starting note is used. */
     intervals: string[];
+    /** Index into the un-rotated scale that `notes` starts on (0 = root). */
+    startIndex: number;
 }
-export declare function resolveScale(root: string, scaleType: string, direction?: "ascending" | "descending", octaves?: number): ResolvedScale;
+export declare function resolveScale(root: string, scaleType: string, direction?: "ascending" | "descending", octaves?: number, startOn?: string): ResolvedScale;

package/dist/resolver/scale-resolver.js

@@ -1,9 +1,10 @@
 /**
  * Scale resolver — resolves scale names to notes via Tonal.
- * Handles melodic minor direction, multi-octave expansion, and
- * generates Tonal interval arrays for degree label computation.
+ * Handles melodic minor direction, multi-octave expansion, rotation to a
+ * custom starting note, and generates Tonal interval arrays for degree
+ * label computation.
  */
-import { Scale } from "tonal";
+import { Note, Scale } from "tonal";
 /** Normalize common scale name variants for Tonal compatibility. */
 const SCALE_NAME_MAP = {
     "natural minor": "minor",
@@ -14,7 +15,7 @@ const SCALE_NAME_MAP = {
     "whole tone": "whole tone",
     "bebop": "bebop major",
 };
-export function resolveScale(root, scaleType, direction, octaves = 1) {
+export function resolveScale(root, scaleType, direction, octaves = 1, startOn) {
     // Melodic minor descending = natural minor
     let effectiveType = scaleType;
     if (scaleType === "melodic minor" && direction === "descending") {
@@ -26,20 +27,39 @@ export function resolveScale(root, scaleType, direction, octaves = 1) {
     if (scale.empty) {
         throw new Error(`Unknown scale: "${root} ${scaleType}"`);
     }
-    const oneOctaveNotes = scale.notes;
-    const intervals = scale.intervals;
-    // Expand across octaves: repeat pitch classes + add final tonic
+    let oneOctaveNotes = scale.notes;
+    let intervals = scale.intervals;
+    let startIndex = 0;
+    // "starting on X" — rotate the scale so it runs one octave (or N octaves)
+    // from that note instead of the root. Matched by pitch (chroma) so an
+    // enharmonic spelling like G# still finds Ab.
+    if (startOn) {
+        const targetChroma = Note.chroma(startOn);
+        startIndex = oneOctaveNotes.findIndex((n) => Note.chroma(n) === targetChroma);
+        if (startIndex < 0) {
+            throw new Error(`${startOn} isn't in ${root} ${scaleType} — the notes are: ${oneOctaveNotes.join(", ")}`);
+        }
+        if (startIndex > 0) {
+            oneOctaveNotes = [
+                ...oneOctaveNotes.slice(startIndex),
+                ...oneOctaveNotes.slice(0, startIndex),
+            ];
+            intervals = [...intervals.slice(startIndex), ...intervals.slice(0, startIndex)];
+        }
+    }
+    // Expand across octaves: repeat pitch classes + add final starting note
     const notes = [];
     for (let oct = 0; oct < octaves; oct++) {
         notes.push(...oneOctaveNotes);
     }
-    // Add the final tonic to complete the last octave
+    // Add the final starting note to complete the last octave
     notes.push(oneOctaveNotes[0]);
     return {
         notes,
         root,
         type: scaleType,
         intervals,
+        startIndex,
     };
 }
 //# sourceMappingURL=scale-resolver.js.map

package/dist/resolver/scale-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"scale-resolver.js","sourceRoot":"","sources":["../../src/resolver/scale-resolver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAW9B,oEAAoE;AACpE,MAAM,cAAc,GAA2B;IAC7C,eAAe,EAAE,OAAO;IACxB,gBAAgB,EAAE,gBAAgB;IAClC,eAAe,EAAE,eAAe;IAChC,kBAAkB,EAAE,kBAAkB;IACtC,kBAAkB,EAAE,kBAAkB;IACtC,YAAY,EAAE,YAAY;IAC1B,OAAO,EAAE,aAAa;CACvB,CAAC;AAEF,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,SAAiB,EACjB,SAAsC,EACtC,UAAkB,CAAC;IAEnB,2CAA2C;IAC3C,IAAI,aAAa,GAAG,SAAS,CAAC;IAC9B,IAAI,SAAS,KAAK,eAAe,IAAI,SAAS,KAAK,YAAY,EAAE,CAAC;QAChE,aAAa,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,2BAA2B;IAC3B,MAAM,SAAS,GAAG,cAAc,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC;IAEjE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,SAAS,EAAE,CAAC,CAAC;IAChD,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,IAAI,SAAS,GAAG,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,cAAc,GAAG,KAAK,CAAC,KAAK,CAAC;IACnC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAElC,gEAAgE;IAChE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,CAAC;IAChC,CAAC;IACD,kDAAkD;IAClD,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9B,OAAO;QACL,KAAK;QACL,IAAI;QACJ,IAAI,EAAE,SAAS;QACf,SAAS;KACV,CAAC;AACJ,CAAC"}
+{"version":3,"file":"scale-resolver.js","sourceRoot":"","sources":["../../src/resolver/scale-resolver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAcpC,oEAAoE;AACpE,MAAM,cAAc,GAA2B;IAC7C,eAAe,EAAE,OAAO;IACxB,gBAAgB,EAAE,gBAAgB;IAClC,eAAe,EAAE,eAAe;IAChC,kBAAkB,EAAE,kBAAkB;IACtC,kBAAkB,EAAE,kBAAkB;IACtC,YAAY,EAAE,YAAY;IAC1B,OAAO,EAAE,aAAa;CACvB,CAAC;AAEF,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,SAAiB,EACjB,SAAsC,EACtC,UAAkB,CAAC,EACnB,OAAgB;IAEhB,2CAA2C;IAC3C,IAAI,aAAa,GAAG,SAAS,CAAC;IAC9B,IAAI,SAAS,KAAK,eAAe,IAAI,SAAS,KAAK,YAAY,EAAE,CAAC;QAChE,aAAa,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,2BAA2B;IAC3B,MAAM,SAAS,GAAG,cAAc,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC;IAEjE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,SAAS,EAAE,CAAC,CAAC;IAChD,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,IAAI,SAAS,GAAG,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,cAAc,GAAG,KAAK,CAAC,KAAK,CAAC;IACjC,IAAI,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAChC,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,0EAA0E;IAC1E,sEAAsE;IACtE,8CAA8C;IAC9C,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1C,UAAU,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC;QAC9E,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,aAAa,IAAI,IAAI,SAAS,qBAAqB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzF,CAAC;QACJ,CAAC;QACD,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACnB,cAAc,GAAG;gBACf,GAAG,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC;gBACnC,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC;aACvC,CAAC;YACF,SAAS,GAAG,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,CAAC;IAChC,CAAC;IACD,0DAA0D;IAC1D,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAE9B,OAAO;QACL,KAAK;QACL,IAAI;QACJ,IAAI,EAAE,SAAS;QACf,SAAS;QACT,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/themes/boomwhacker.d.ts

@@ -1,2 +1,2 @@
-import type { ColorTheme } from "../types";
+import type { ColorTheme } from "../types.js";
 export declare const boomwhackerTheme: ColorTheme;

package/dist/themes/boomwhacker.js

@@ -1,4 +1,4 @@
-import { DEFAULT_WHITE_FILL, DEFAULT_BLACK_FILL } from "../engine/svg-constants";
+import { DEFAULT_WHITE_FILL, DEFAULT_BLACK_FILL } from "../engine/svg-constants.js";
 // Boomwhacker chromatic pitch-class colors
 const PITCH_COLORS = {
     C: "#e81c1c",

package/dist/themes/boomwhacker.js.map

@@ -1 +1 @@
-{"version":3,"file":"boomwhacker.js","sourceRoot":"","sources":["../../src/themes/boomwhacker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEjF,2CAA2C;AAC3C,MAAM,YAAY,GAA2B;IAC3C,CAAC,EAAE,SAAS;IACZ,IAAI,EAAE,SAAS;IACf,CAAC,EAAE,SAAS;IACZ,IAAI,EAAE,SAAS;IACf,CAAC,EAAE,SAAS;IACZ,CAAC,EAAE,SAAS;IACZ,IAAI,EAAE,SAAS;IACf,CAAC,EAAE,SAAS;IACZ,IAAI,EAAE,SAAS;IACf,CAAC,EAAE,SAAS;IACZ,IAAI,EAAE,SAAS;IACf,CAAC,EAAE,SAAS;CACb,CAAC;AAEF,0CAA0C;AAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,CAAC,sBAAsB;AAEhD,SAAS,IAAI,CAAC,GAAW;IACvB,OAAO,GAAG,GAAG,WAAW,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAe;IAC1C,IAAI,EAAE,aAAa;IACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE;QAC9B,IAAI,CAAC,WAAW;YAAE,OAAO,kBAAkB,CAAC;QAC5C,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,kBAAkB,CAAC;IAClD,CAAC;IACD,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE;QAC9B,IAAI,CAAC,WAAW;YAAE,OAAO,kBAAkB,CAAC;QAC5C,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,kBAAkB,CAAC;IAClD,CAAC;CACF,CAAC"}
+{"version":3,"file":"boomwhacker.js","sourceRoot":"","sources":["../../src/themes/boomwhacker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEpF,2CAA2C;AAC3C,MAAM,YAAY,GAA2B;IAC3C,CAAC,EAAE,SAAS;IACZ,IAAI,EAAE,SAAS;IACf,CAAC,EAAE,SAAS;IACZ,IAAI,EAAE,SAAS;IACf,CAAC,EAAE,SAAS;IACZ,CAAC,EAAE,SAAS;IACZ,IAAI,EAAE,SAAS;IACf,CAAC,EAAE,SAAS;IACZ,IAAI,EAAE,SAAS;IACf,CAAC,EAAE,SAAS;IACZ,IAAI,EAAE,SAAS;IACf,CAAC,EAAE,SAAS;CACb,CAAC;AAEF,0CAA0C;AAC1C,MAAM,WAAW,GAAG,IAAI,CAAC,CAAC,sBAAsB;AAEhD,SAAS,IAAI,CAAC,GAAW;IACvB,OAAO,GAAG,GAAG,WAAW,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAe;IAC1C,IAAI,EAAE,aAAa;IACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE;QAC9B,IAAI,CAAC,WAAW;YAAE,OAAO,kBAAkB,CAAC;QAC5C,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,kBAAkB,CAAC;IAClD,CAAC;IACD,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE;QAC9B,IAAI,CAAC,WAAW;YAAE,OAAO,kBAAkB,CAAC;QAC5C,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,kBAAkB,CAAC;IAClD,CAAC;CACF,CAAC"}

package/dist/themes/crf.d.ts

@@ -1,4 +1,4 @@
-import type { ColorTheme } from "../types";
+import type { ColorTheme } from "../types.js";
 /**
  * Creative Ranges Foundation piano keyboard colors.
  *

package/dist/themes/crf.js

@@ -1,4 +1,4 @@
-import { DEFAULT_WHITE_FILL, DEFAULT_BLACK_FILL } from "../engine/svg-constants";
+import { DEFAULT_WHITE_FILL, DEFAULT_BLACK_FILL } from "../engine/svg-constants.js";
 export const CRF_PITCH_PALETTE = {
     C: { hex: "#f86e6e", cmyk: [0, 56, 56, 3] },
     "C#": { hex: "#f58841", cmyk: [0, 44, 73, 4] },

package/dist/themes/crf.js.map

@@ -1 +1 @@
-{"version":3,"file":"crf.js","sourceRoot":"","sources":["../../src/themes/crf.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAiBjF,MAAM,CAAC,MAAM,iBAAiB,GAAkC;IAC9D,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;IAC9C,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;IAC9C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;IAC9C,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;IAC/C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;IAC7C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;IAC9C,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;IAC/C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;IAC/C,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IAC7C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IAC9C,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IAC9C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;CAChD,CAAC;AAEF,2FAA2F;AAC3F,MAAM,UAAU,UAAU,CAAC,IAAsC;IAC/D,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IAC1B,OAAO,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;AAC5C,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAe;IAClC,IAAI,EAAE,KAAK;IACX,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE;QAC9B,IAAI,CAAC,WAAW;YAAE,OAAO,kBAAkB,CAAC;QAC5C,OAAO,iBAAiB,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,kBAAkB,CAAC;IAC5D,CAAC;IACD,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE;QAC9B,IAAI,CAAC,WAAW;YAAE,OAAO,kBAAkB,CAAC;QAC5C,OAAO,iBAAiB,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,kBAAkB,CAAC;IAC5D,CAAC;CACF,CAAC"}
+{"version":3,"file":"crf.js","sourceRoot":"","sources":["../../src/themes/crf.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAiBpF,MAAM,CAAC,MAAM,iBAAiB,GAAkC;IAC9D,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;IAC9C,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;IAC9C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;IAC9C,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;IAC/C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;IAC7C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;IAC9C,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;IAC/C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;IAC/C,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IAC7C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IAC9C,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE;IAC9C,CAAC,EAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;CAChD,CAAC;AAEF,2FAA2F;AAC3F,MAAM,UAAU,UAAU,CAAC,IAAsC;IAC/D,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IAC1B,OAAO,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;AAC5C,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAe;IAClC,IAAI,EAAE,KAAK;IACX,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE;QAC9B,IAAI,CAAC,WAAW;YAAE,OAAO,kBAAkB,CAAC;QAC5C,OAAO,iBAAiB,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,kBAAkB,CAAC;IAC5D,CAAC;IACD,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE;QAC9B,IAAI,CAAC,WAAW;YAAE,OAAO,kBAAkB,CAAC;QAC5C,OAAO,iBAAiB,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,kBAAkB,CAAC;IAC5D,CAAC;CACF,CAAC"}

package/dist/themes/index.d.ts

@@ -1,3 +1,3 @@
-import type { ColorTheme } from "../types";
+import type { ColorTheme } from "../types.js";
 export declare function getTheme(name: string): ColorTheme | undefined;
 export declare function resolveTheme(theme: ColorTheme | string | undefined, highlightColor?: string): ColorTheme | undefined;

package/dist/themes/index.js

@@ -1,6 +1,6 @@
-import { boomwhackerTheme } from "./boomwhacker";
-import { crfTheme } from "./crf";
-import { createSimpleTheme } from "./simple";
+import { boomwhackerTheme } from "./boomwhacker.js";
+import { crfTheme } from "./crf.js";
+import { createSimpleTheme } from "./simple.js";
 const themeRegistry = {
     boomwhacker: boomwhackerTheme,
     crf: crfTheme,

package/dist/themes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/themes/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,aAAa,GAA+B;IAChD,WAAW,EAAE,gBAAgB;IAC7B,GAAG,EAAE,QAAQ;IACb,MAAM,EAAE,iBAAiB,EAAE;CAC5B,CAAC;AAEF,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,KAAsC,EACtC,cAAuB;IAEvB,IAAI,CAAC,KAAK,IAAI,CAAC,cAAc;QAAE,OAAO,SAAS,CAAC;IAChD,IAAI,CAAC,KAAK,IAAI,cAAc;QAAE,OAAO,iBAAiB,CAAC,cAAc,CAAC,CAAC;IACvE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,KAAK,QAAQ,IAAI,cAAc,EAAE,CAAC;YACzC,OAAO,iBAAiB,CAAC,cAAc,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/themes/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,aAAa,GAA+B;IAChD,WAAW,EAAE,gBAAgB;IAC7B,GAAG,EAAE,QAAQ;IACb,MAAM,EAAE,iBAAiB,EAAE;CAC5B,CAAC;AAEF,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,KAAsC,EACtC,cAAuB;IAEvB,IAAI,CAAC,KAAK,IAAI,CAAC,cAAc;QAAE,OAAO,SAAS,CAAC;IAChD,IAAI,CAAC,KAAK,IAAI,cAAc;QAAE,OAAO,iBAAiB,CAAC,cAAc,CAAC,CAAC;IACvE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,KAAK,QAAQ,IAAI,cAAc,EAAE,CAAC;YACzC,OAAO,iBAAiB,CAAC,cAAc,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/themes/simple.d.ts

@@ -1,2 +1,2 @@
-import type { ColorTheme } from "../types";
+import type { ColorTheme } from "../types.js";
 export declare function createSimpleTheme(highlightColor?: string): ColorTheme;

package/dist/themes/simple.js

@@ -1,4 +1,4 @@
-import { DEFAULT_WHITE_FILL, DEFAULT_BLACK_FILL } from "../engine/svg-constants";
+import { DEFAULT_WHITE_FILL, DEFAULT_BLACK_FILL } from "../engine/svg-constants.js";
 const DEFAULT_HIGHLIGHT = "#a0c6e8";
 const DEFAULT_BLACK_HIGHLIGHT = "#5a8ab5";
 export function createSimpleTheme(highlightColor) {

package/dist/themes/simple.js.map

@@ -1 +1 @@
-{"version":3,"file":"simple.js","sourceRoot":"","sources":["../../src/themes/simple.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEjF,MAAM,iBAAiB,GAAG,SAAS,CAAC;AACpC,MAAM,uBAAuB,GAAG,SAAS,CAAC;AAE1C,MAAM,UAAU,iBAAiB,CAAC,cAAuB;IACvD,MAAM,cAAc,GAAG,cAAc,IAAI,iBAAiB,CAAC;IAC3D,MAAM,cAAc,GAAG,cAAc,IAAI,uBAAuB,CAAC;IAEjE,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CAC/B,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,kBAAkB;QACnD,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CAC/B,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,kBAAkB;KACpD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"simple.js","sourceRoot":"","sources":["../../src/themes/simple.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEpF,MAAM,iBAAiB,GAAG,SAAS,CAAC;AACpC,MAAM,uBAAuB,GAAG,SAAS,CAAC;AAE1C,MAAM,UAAU,iBAAiB,CAAC,cAAuB;IACvD,MAAM,cAAc,GAAG,cAAc,IAAI,iBAAiB,CAAC;IAC3D,MAAM,cAAc,GAAG,cAAc,IAAI,uBAAuB,CAAC;IAEjE,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CAC/B,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,kBAAkB;QACnD,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,CAC/B,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,kBAAkB;KACpD,CAAC;AACJ,CAAC"}

package/dist/theory/constrained-variants.d.ts

@@ -0,0 +1,46 @@
+import type { VoicingQuality, VoicingVariant } from "@pepperhorn/chordl-voicings";
+import type { ConstrainedVoicing, HandConstraints } from "./hand-constraints.js";
+/**
+ * A source voicing refitted to a hand.
+ *
+ * `id` and `label` name the character of the *source* voicing — "Drop 2+4",
+ * "Rootless A" — not the shape of `voicing.notes`. `VoicingVariant.notes` is
+ * pitch classes only, with no octave information, so those pitch classes are
+ * re-stacked close-position from `baseOctave` and then folded and reduced to
+ * fit the hand. A voicing whose real intervals span fifteen semitones comes
+ * back inside the hand's reach, and the label still says "Drop 2+4".
+ *
+ * So: read the label as provenance, not as geometry. A consumer that needs the
+ * true open-position shape should realize the voicing through chordl-voicings
+ * directly rather than infer it from this label.
+ */
+export interface ConstrainedVariant {
+    id: string;
+    label: string;
+    source: VoicingVariant["source"];
+    voicing: ConstrainedVoicing;
+}
+export interface GenerateConstrainedOptions {
+    /** Tonal interval names, e.g. ["1P","3M","5P","7M"]. */
+    intervals?: string[];
+    /** Tonal chord type, e.g. "major seventh". */
+    chordType?: string;
+    styleHint?: string;
+    excludeIds?: string[];
+    baseOctave?: number;
+}
+/**
+ * Generate voicing variants and fit each to a hand.
+ *
+ * Variants that satisfy the constraints are returned first, then those that
+ * could not be satisfied without losing a chord tone. Ordering matters because
+ * an inversion often fits where root position cannot: Cmaj7 spans 11 semitones
+ * in root position but 8 in first inversion.
+ *
+ * @param root - root note, e.g. "C"
+ * @param quality - voicing quality from mapToVoicingQuality, may be undefined
+ * @param resolvedNotes - pitch classes in root position
+ * @param count - how many variants to generate before constraining
+ * @param constraints - the hand's reach and note count
+ */
+export declare function generateConstrainedVariants(root: string, quality: VoicingQuality | undefined, resolvedNotes: string[], count: number, constraints: HandConstraints, options?: GenerateConstrainedOptions): ConstrainedVariant[];

package/dist/theory/constrained-variants.js

@@ -0,0 +1,117 @@
+/**
+ * Voicing variants that fit a given hand.
+ *
+ * This lives in core rather than chordl-voicings because it needs
+ * classifyTones/dropOrder, and voicings is a leaf package that core depends
+ * on — the dependency cannot run the other way.
+ */
+import { generateVariants } from "@pepperhorn/chordl-voicings";
+import { classifyTones, dropOrder } from "./chord-tones.js";
+import { constrainVoicing, pcSemitone } from "./hand-constraints.js";
+/**
+ * Drop order when the chord's intervals are unknown.
+ *
+ * resolveChord returns undefined intervals for special-builder chords, so
+ * roles cannot be classified. But it returns notes in root-position order, so
+ * position stands in for role: 0 = root, 1 = 3rd, 2 = 5th, 3 = 7th, 4+ =
+ * extensions. That is enough to mirror what classifyTones would conclude on
+ * the primary path, rather than diverging from it.
+ *
+ * Triads keep the 5th — on piano a triad needs it to still be a triad, which
+ * is exactly what assignRole concludes for degree 5 in the "triad" family.
+ * Larger chords treat the 5th as omittable and protect the 3rd and 7th, so
+ * the root stays droppable and a shell voicing can form.
+ */
+function fallbackDropOrder(notes) {
+    if (notes.length <= 3) {
+        const keep = notes.slice(1, 3);
+        return { order: notes[0] === undefined ? [] : [notes[0]], keep };
+    }
+    const order = [];
+    for (let i = notes.length - 1; i >= 4; i--)
+        order.push(notes[i]); // extensions, top down
+    if (notes[2] !== undefined)
+        order.push(notes[2]); // 5th — conventionally omittable
+    if (notes[0] !== undefined)
+        order.push(notes[0]); // root — last, forming a shell
+    const keep = [notes[1], notes[3]].filter((n) => n !== undefined);
+    return { order, keep };
+}
+/**
+ * Put a variant's unclassified notes at the head of the drop order.
+ *
+ * `order` and `keep` come from the resolved chord tones, so a library
+ * voicing's added 9th or 13th — the whole point of a rootless voicing — is in
+ * neither list. `constrainVoicing` only ever drops what `dropOrder` names, so
+ * without this the reduction stalls with the voicing still over the cap.
+ * Extensions are colour tones and the safest thing to lose, so they go first,
+ * in the order the voicing lists them.
+ *
+ * Membership is tested by semitone because chordl-voicings spells library
+ * variants with sharps where core's resolver yields flats.
+ */
+function withUnclassifiedFirst(notes, order, keep) {
+    const classified = new Set([...order, ...keep].map(pcSemitone));
+    const extras = [];
+    for (const note of notes) {
+        const semitone = pcSemitone(note);
+        if (classified.has(semitone))
+            continue;
+        classified.add(semitone);
+        extras.push(note);
+    }
+    return extras.length === 0 ? order : [...extras, ...order];
+}
+/**
+ * Generate voicing variants and fit each to a hand.
+ *
+ * Variants that satisfy the constraints are returned first, then those that
+ * could not be satisfied without losing a chord tone. Ordering matters because
+ * an inversion often fits where root position cannot: Cmaj7 spans 11 semitones
+ * in root position but 8 in first inversion.
+ *
+ * @param root - root note, e.g. "C"
+ * @param quality - voicing quality from mapToVoicingQuality, may be undefined
+ * @param resolvedNotes - pitch classes in root position
+ * @param count - how many variants to generate before constraining
+ * @param constraints - the hand's reach and note count
+ */
+export function generateConstrainedVariants(root, quality, resolvedNotes, count, constraints, options = {}) {
+    const variants = generateVariants(root, quality, resolvedNotes, count, {
+        styleHint: options.styleHint,
+        excludeIds: options.excludeIds,
+    });
+    if (variants.length === 0)
+        return [];
+    let order;
+    let keep;
+    if (options.intervals && options.intervals.length > 0) {
+        const analysis = classifyTones(root, options.chordType ?? "", options.intervals, resolvedNotes, "piano");
+        order = dropOrder(analysis);
+        // Identity tones only — the root is droppable as a last resort, which is
+        // exactly how a shell voicing is formed.
+        keep = analysis.identityTones;
+    }
+    else {
+        ({ order, keep } = fallbackDropOrder(resolvedNotes));
+    }
+    const constrained = variants.map((v) => ({
+        id: v.id,
+        label: v.label,
+        source: v.source,
+        voicing: constrainVoicing({
+            notes: v.notes,
+            handHints: v.handHints,
+            dropOrder: withUnclassifiedFirst(v.notes, order, keep),
+            keepAtLeast: keep,
+            constraints,
+            baseOctave: options.baseOctave,
+        }),
+    }));
+    // Stable partition: satisfied first, original order preserved within groups.
+    return [
+        ...constrained.filter((c) => c.voicing.satisfied),
+        ...constrained.filter((c) => !c.voicing.satisfied),
+    ];
+}
+//# sourceMappingURL=constrained-variants.js.map

package/dist/theory/constrained-variants.js.map

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

package/dist/theory/degree-labels.d.ts

@@ -29,3 +29,42 @@ export declare function intervalToDegreeLabel(interval: string): string;
  * degreesForIntervals(["1P", "3M", "5A", "7m"]) → ["I", "III", "#V", "bVII"]
  */
 export declare function degreesForIntervals(intervals: string[]): string[];
+/**
+ * Label each rendered note with the degree it plays in the chord, keyed by
+ * pitch rather than by position.
+ *
+ * Position is not usable here: `notes` is rotated by inversions and by
+ * "starting on", and repeated across octaves for arpeggios, while
+ * `resolved.intervals` stays canonical (the resolver deliberately does not
+ * rotate it — the voicing lookup classifies by degree number). Zipping the two
+ * by index therefore called whatever note came first the root.
+ *
+ * Matching is spelling-first, then chroma. Spelling has to win: `C7#5b13`
+ * renders both `G#` (5A) and `Ab` (6m), which share chroma 8, and a chroma-first
+ * lookup would give them the same label. Chroma is the fallback for the cases
+ * spelling cannot cover — a `7d` off C is `Bbb` but renders as `A`, and a
+ * voicing may respell `Bb` as `A#`.
+ *
+ * A note in neither map — an added tone from a style voicing, e.g. the 9th in a
+ * rootless `Cmaj7` — is labelled from its distance to the root instead of
+ * borrowing a chord tone's label, and a 2nd, 4th or 6th is raised an octave so
+ * it reads as the extension it is: `IX`, `XI`, `XIII`. The quality rides along,
+ * so an altered extension still reads `bIX` / `#XI` / `bXIII`. Raising is safe
+ * precisely because this branch only fires for notes absent from the chord's
+ * own interval list: a chord that genuinely owns a 2nd, 4th or 6th (`Csus2`,
+ * `Csus4`, `C6`) matches by spelling or chroma first and keeps `II`, `IV`, `VI`.
+ * Anything that still cannot be named comes back `undefined`, and the keyboard
+ * draws no label for it.
+ *
+ * @param root   The chord root, e.g. "C".
+ * @param intervals The chord's canonical intervals, e.g. ["1P","3M","5P"].
+ * @param notes  The notes as rendered, in render order.
+ * @returns One label per note, index-parallel to `notes`.
+ *
+ * @example
+ * degreeLabelsForNotes("C", ["1P","3M","5P"], ["E","G","C"]) → ["III","V","I"]
+ * degreeLabelsForNotes("C", ["3M","5P","8P"], ["E","G","C"]) → ["III","V","8"]
+ * degreeLabelsForNotes("C", ["1P","3M","5P","7M"], ["E","G","B","D"])
+ *   → ["III","V","VII","IX"]  // the D is an added tone, so it reads as a 9th
+ */
+export declare function degreeLabelsForNotes(root: string, intervals: string[] | undefined, notes: string[]): (string | undefined)[];

package/dist/theory/degree-labels.js

@@ -9,7 +9,8 @@
  * - Minor/Diminished = flat (b)
  * - Augmented = sharp (#)
  */
-import { parseInterval } from "./chord-tones";
+import { Note, Interval } from "tonal";
+import { parseInterval } from "./chord-tones.js";
 const ROMAN = ["", "I", "II", "III", "IV", "V", "VI", "VII"];
 const ROMAN_EXT = {
     9: "IX", 10: "X", 11: "XI", 12: "XII", 13: "XIII",
@@ -71,4 +72,104 @@ export function intervalToDegreeLabel(interval) {
 export function degreesForIntervals(intervals) {
     return intervals.map(intervalToDegreeLabel);
 }
+/**
+ * Raise a simple 2nd, 4th or 6th by an octave so it reads as the extension it
+ * is: 2→9, 4→11, 6→13. The quality is carried over untouched, so `2m` becomes
+ * `9m` and `4A` becomes `11A` — a flattened or raised extension keeps its
+ * accidental. Degrees 1, 3, 5, 7 and 8 are returned unchanged.
+ *
+ * Only for the non-chord-tone fallback in `degreeLabelsForNotes`: pitch-class
+ * distances are always simple, so an added 9th arrives here as a bare `2M`.
+ */
+function raiseExtension(interval) {
+    const parsed = Interval.get(interval);
+    if (parsed.empty || parsed.num == null)
+        return interval;
+    if (parsed.num !== 2 && parsed.num !== 4 && parsed.num !== 6)
+        return interval;
+    return `${parsed.num + 7}${parsed.q}`;
+}
+/**
+ * Label each rendered note with the degree it plays in the chord, keyed by
+ * pitch rather than by position.
+ *
+ * Position is not usable here: `notes` is rotated by inversions and by
+ * "starting on", and repeated across octaves for arpeggios, while
+ * `resolved.intervals` stays canonical (the resolver deliberately does not
+ * rotate it — the voicing lookup classifies by degree number). Zipping the two
+ * by index therefore called whatever note came first the root.
+ *
+ * Matching is spelling-first, then chroma. Spelling has to win: `C7#5b13`
+ * renders both `G#` (5A) and `Ab` (6m), which share chroma 8, and a chroma-first
+ * lookup would give them the same label. Chroma is the fallback for the cases
+ * spelling cannot cover — a `7d` off C is `Bbb` but renders as `A`, and a
+ * voicing may respell `Bb` as `A#`.
+ *
+ * A note in neither map — an added tone from a style voicing, e.g. the 9th in a
+ * rootless `Cmaj7` — is labelled from its distance to the root instead of
+ * borrowing a chord tone's label, and a 2nd, 4th or 6th is raised an octave so
+ * it reads as the extension it is: `IX`, `XI`, `XIII`. The quality rides along,
+ * so an altered extension still reads `bIX` / `#XI` / `bXIII`. Raising is safe
+ * precisely because this branch only fires for notes absent from the chord's
+ * own interval list: a chord that genuinely owns a 2nd, 4th or 6th (`Csus2`,
+ * `Csus4`, `C6`) matches by spelling or chroma first and keeps `II`, `IV`, `VI`.
+ * Anything that still cannot be named comes back `undefined`, and the keyboard
+ * draws no label for it.
+ *
+ * @param root   The chord root, e.g. "C".
+ * @param intervals The chord's canonical intervals, e.g. ["1P","3M","5P"].
+ * @param notes  The notes as rendered, in render order.
+ * @returns One label per note, index-parallel to `notes`.
+ *
+ * @example
+ * degreeLabelsForNotes("C", ["1P","3M","5P"], ["E","G","C"]) → ["III","V","I"]
+ * degreeLabelsForNotes("C", ["3M","5P","8P"], ["E","G","C"]) → ["III","V","8"]
+ * degreeLabelsForNotes("C", ["1P","3M","5P","7M"], ["E","G","B","D"])
+ *   → ["III","V","VII","IX"]  // the D is an added tone, so it reads as a 9th
+ */
+export function degreeLabelsForNotes(root, intervals, notes) {
+    if (!intervals || intervals.length === 0)
+        return notes.map(() => undefined);
+    // First interval to claim a pitch keeps it: a chord that names the same
+    // sounding pitch twice should read as the lower of the two degrees.
+    const bySpelling = new Map();
+    const byChroma = new Map();
+    for (const iv of intervals) {
+        const pc = Note.pitchClass(Note.transpose(root, iv));
+        if (!pc)
+            continue;
+        const label = intervalToDegreeLabel(iv);
+        // A slash chord whose bass sits below the root arrives with a negative
+        // interval — C/F is ["-5P","1P","3M","5P"] — and parseInterval's `^(\d+)`
+        // does not match the leading minus, so the label is the "?" sentinel.
+        // Leaving it out of the maps hands the note to the distance fallback,
+        // which names it from the root and gets bVII for C/Bb. Storing it printed
+        // a literal "?" under the bass key.
+        if (label === "?")
+            continue;
+        if (!bySpelling.has(pc))
+            bySpelling.set(pc, label);
+        const chroma = Note.chroma(pc);
+        if (Number.isFinite(chroma) && !byChroma.has(chroma))
+            byChroma.set(chroma, label);
+    }
+    return notes.map((n) => {
+        const pc = Note.pitchClass(n) || n;
+        const spelled = bySpelling.get(pc);
+        if (spelled !== undefined)
+            return spelled;
+        const chroma = Note.chroma(pc);
+        if (Number.isFinite(chroma)) {
+            const enharmonic = byChroma.get(chroma);
+            if (enharmonic !== undefined)
+                return enharmonic;
+        }
+        // Not a chord tone — name it by its distance from the root anyway.
+        const distance = Interval.distance(root, pc);
+        if (!distance)
+            return undefined;
+        const label = intervalToDegreeLabel(raiseExtension(distance));
+        return label === "?" ? undefined : label;
+    });
+}
 //# sourceMappingURL=degree-labels.js.map

package/dist/theory/degree-labels.js.map

@@ -1 +1 @@
-{"version":3,"file":"degree-labels.js","sourceRoot":"","sources":["../../src/theory/degree-labels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,KAAK,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;AAC7D,MAAM,SAAS,GAA2B;IACxC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM;CAClD,CAAC;AAEF;;;;GAIG;AACH,SAAS,cAAc,CAAC,MAAc;IACpC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,MAAM,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAC7D,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAE7B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC;QACzB,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAE1C,MAAM,GAAG,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IAEnC,uBAAuB;IACvB,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;QACpB,kDAAkD;QAClD,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;QACvC,OAAO,IAAI,OAAO,EAAE,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;QACpB,OAAO,IAAI,OAAO,EAAE,CAAC;IACvB,CAAC;IACD,2EAA2E;IAC3E,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,KAAK,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAmB;IACrD,OAAO,SAAS,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"degree-labels.js","sourceRoot":"","sources":["../../src/theory/degree-labels.ts"],"names":[],"mappings":"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"}

package/dist/theory/hand-constraints.d.ts

@@ -0,0 +1,104 @@
+import type { Hand } from "@pepperhorn/chordl-voicings";
+export interface HandConstraints {
+    /** Maximum semitones between lowest and highest note in one hand. */
+    maxSpanPerHand: number;
+    /** Maximum notes in one hand. Values below 2 are clamped to 2. */
+    maxNotesPerHand: number;
+}
+export interface PlacedNote {
+    note: string;
+    octave: number;
+    midi: number;
+}
+/**
+ * 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 declare function midiOf(note: string, octave: number): number;
+/**
+ * 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 declare function placeAscending(notes: string[], baseOctave: number, maxSpan?: number): PlacedNote[];
+/** Semitones between the lowest and highest pitch. Zero for 0 or 1 notes. */
+export declare function spanOf(pitches: number[]): number;
+export interface ConstrainedNote extends PlacedNote {
+    hand: Hand;
+}
+export interface ConstrainVoicingInput {
+    /** Pitch classes in voicing order. */
+    notes: string[];
+    /**
+     * Per-note hand assignment. When absent the whole voicing counts as one
+     * hand — variants from the `inversion` and `algorithmic` sources carry no
+     * hand hints, so both caps apply to the voicing as a whole.
+     */
+    handHints?: Hand[];
+    /**
+     * Safest-to-drop first, from core's `dropOrder(analysis)`. Matched against
+     * `notes` by semitone, so either list may be spelled with sharps or flats.
+     */
+    dropOrder: string[];
+    /**
+     * Notes that must survive — the chord's identity tones. Matched by semitone,
+     * like `dropOrder`.
+     */
+    keepAtLeast: string[];
+    constraints: HandConstraints;
+    /** Octave of the lowest note. Default 3. */
+    baseOctave?: number;
+}
+export interface ConstrainedVoicing {
+    /**
+     * Surviving notes in voicing order, each keeping its input spelling. Never
+     * two notes on the same MIDI number, and never fewer than two notes in a
+     * hand unless the input itself had fewer.
+     */
+    notes: ConstrainedNote[];
+    /**
+     * Pitch classes removed, in the order they were dropped, spelled as the
+     * input spelled them rather than as `dropOrder` did.
+     */
+    dropped: string[];
+    /** Largest per-hand span in the result, semitones. */
+    span: number;
+    /** True when every hand is within both caps. */
+    satisfied: boolean;
+}
+/**
+ * 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 declare function pcSemitone(note: string): number;
+/**
+ * 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 declare function constrainVoicing(input: ConstrainVoicingInput): ConstrainedVoicing;