@real-music-packages/web-core 0.30.0 → 0.32.0

package/dist/chunk-ILIXNGPE.js

@@ -0,0 +1,127 @@
+// src/intervals.ts
+var INTERVALS = [
+  { semitones: 1, label: "m2", mnemonic: "Jaws theme" },
+  { semitones: 2, label: "M2", mnemonic: "Happy Birthday opening" },
+  { semitones: 3, label: "m3", mnemonic: "Brahms' Lullaby" },
+  { semitones: 4, label: "M3", mnemonic: "When the Saints" },
+  { semitones: 5, label: "P4", mnemonic: "Here Comes the Bride" },
+  { semitones: 6, label: "TT", mnemonic: "The Simpsons theme" },
+  { semitones: 7, label: "P5", mnemonic: "Twinkle Twinkle" },
+  { semitones: 8, label: "m6", mnemonic: "Love Story theme" },
+  { semitones: 9, label: "M6", mnemonic: "NBC chimes" },
+  { semitones: 10, label: "m7", mnemonic: "Somewhere (West Side Story)" },
+  { semitones: 11, label: "M7", mnemonic: "Take On Me chorus" },
+  { semitones: 12, label: "P8", mnemonic: "Somewhere Over the Rainbow" }
+];
+function intervalBySemitones(semitones) {
+  return INTERVALS.find((i) => i.semitones === semitones);
+}
+
+// src/music/fretboard.ts
+var STRINGS = [40, 45, 50, 55, 59, 64];
+var STRING_COUNT = STRINGS.length;
+var MAX_FRET = 15;
+function noteToFret(midi, stringIndex) {
+  const fret = midi - STRINGS[stringIndex];
+  if (fret < 0 || fret > MAX_FRET) return null;
+  return fret;
+}
+function midiToPositions(midi) {
+  const positions = [];
+  for (let s = 0; s < STRING_COUNT; s++) {
+    const fret = noteToFret(midi, s);
+    if (fret !== null) {
+      positions.push({ string: s, fret });
+    }
+  }
+  return positions;
+}
+function chosenPlacement(midi) {
+  for (let s = 0; s < STRING_COUNT; s++) {
+    const fret = noteToFret(midi, s);
+    if (fret !== null) {
+      return { string: s, fret };
+    }
+  }
+  return null;
+}
+function buildPlacementMap(midiNotes) {
+  const map = /* @__PURE__ */ new Map();
+  for (const midi of midiNotes) {
+    const pos = chosenPlacement(midi);
+    if (pos !== null) {
+      map.set(midi, pos);
+    }
+  }
+  return map;
+}
+function enumerateBoardCells(visibleFrets = MAX_FRET) {
+  const cells = [];
+  for (let s = 0; s < STRING_COUNT; s++) {
+    for (let f = 0; f <= visibleFrets; f++) {
+      const midi = STRINGS[s] + f;
+      cells.push({ string: s, fret: f, midi });
+    }
+  }
+  return cells;
+}
+function bestPosition(midi, opts = {}) {
+  const max = opts.maxFret ?? MAX_FRET;
+  if (opts.preferHighString) {
+    for (let s = STRING_COUNT - 1; s >= 0; s--) {
+      const fret = midi - STRINGS[s];
+      if (fret >= 0 && fret <= max) return { string: s, fret };
+    }
+    return null;
+  }
+  for (let s = 0; s < STRING_COUNT; s++) {
+    const fret = midi - STRINGS[s];
+    if (fret >= 0 && fret <= max) return { string: s, fret };
+  }
+  return null;
+}
+function distributeChord(midiNotes) {
+  const sorted = [...midiNotes].sort((a, b) => a - b);
+  const usedStrings = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const midi of sorted) {
+    let assigned = null;
+    for (let s = 0; s < STRING_COUNT; s++) {
+      if (usedStrings.has(s)) continue;
+      const fret = midi - STRINGS[s];
+      if (fret >= 0 && fret <= MAX_FRET) {
+        assigned = { string: s, fret };
+        break;
+      }
+    }
+    const idx = result.length;
+    if (assigned !== null) {
+      usedStrings.add(assigned.string);
+      result.push({
+        string: assigned.string,
+        fret: assigned.fret,
+        midi,
+        strumOffsetMs: idx * 12
+      });
+    } else {
+      result.push({ string: -1, fret: -1, midi, strumOffsetMs: idx * 12 });
+    }
+  }
+  return result;
+}
+
+export {
+  INTERVALS,
+  intervalBySemitones,
+  STRINGS,
+  STRING_COUNT,
+  MAX_FRET,
+  noteToFret,
+  midiToPositions,
+  chosenPlacement,
+  buildPlacementMap,
+  enumerateBoardCells,
+  bestPosition,
+  distributeChord
+};
+//# sourceMappingURL=chunk-ILIXNGPE.js.map

package/dist/chunk-ILIXNGPE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/intervals.ts","../src/music/fretboard.ts"],"sourcesContent":["export interface IntervalDef { semitones: number; label: string; mnemonic: string }\n\nexport const INTERVALS: IntervalDef[] = [\n  { semitones: 1,  label: 'm2', mnemonic: 'Jaws theme' },\n  { semitones: 2,  label: 'M2', mnemonic: 'Happy Birthday opening' },\n  { semitones: 3,  label: 'm3', mnemonic: \"Brahms' Lullaby\" },\n  { semitones: 4,  label: 'M3', mnemonic: 'When the Saints' },\n  { semitones: 5,  label: 'P4', mnemonic: 'Here Comes the Bride' },\n  { semitones: 6,  label: 'TT', mnemonic: 'The Simpsons theme' },\n  { semitones: 7,  label: 'P5', mnemonic: 'Twinkle Twinkle' },\n  { semitones: 8,  label: 'm6', mnemonic: 'Love Story theme' },\n  { semitones: 9,  label: 'M6', mnemonic: 'NBC chimes' },\n  { semitones: 10, label: 'm7', mnemonic: 'Somewhere (West Side Story)' },\n  { semitones: 11, label: 'M7', mnemonic: 'Take On Me chorus' },\n  { semitones: 12, label: 'P8', mnemonic: 'Somewhere Over the Rainbow' },\n];\n\nexport function intervalBySemitones(semitones: number): IntervalDef | undefined {\n  return INTERVALS.find(i => i.semitones === semitones);\n}\n","/**\n * fretboard.ts — Pure MIDI <-> guitar fretboard mapping utilities.\n *\n * Standard tuning EADGBE, index 0 = low E (6th string), index 5 = high E (1st string).\n * Open-string MIDI values: E2=40, A2=45, D3=50, G3=55, B3=59, E4=64.\n *\n * No Svelte, no audio, no side effects. Unit-testable in isolation.\n */\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/** Open-string MIDI pitches, low E to high E (index 0 = 6th string). */\nexport const STRINGS: readonly number[] = [40, 45, 50, 55, 59, 64];\n\n/** Number of strings on a standard guitar. */\nexport const STRING_COUNT = STRINGS.length; // 6\n\n/**\n * Maximum fret number rendered. Covers MIDI range 40–79 while staying\n * readable on mobile. Frets 0–15 give string 5 (high E, open=64) a top note\n * of 79 (G5), well above the piano's practical teaching range.\n */\nexport const MAX_FRET = 15;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** A playable position on the fretboard. string is 0-based (0 = low E). */\nexport interface FretPosition {\n\t/** String index, 0 = low E (6th string), 5 = high E (1st string). */\n\tstring: number;\n\t/** Fret number, 0 = open. */\n\tfret: number;\n}\n\n// ---------------------------------------------------------------------------\n// Core helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Compute the fret number for a MIDI note on a specific string, or null if\n * outside the playable range [0, MAX_FRET].\n */\nexport function noteToFret(midi: number, stringIndex: number): number | null {\n\tconst fret = midi - STRINGS[stringIndex];\n\tif (fret < 0 || fret > MAX_FRET) return null;\n\treturn fret;\n}\n\n/**\n * Return ALL playable positions for a MIDI note across all strings.\n * Results are ordered from lowest string (index 0) to highest (index 5).\n * Returns an empty array if the note is unreachable on any string.\n */\nexport function midiToPositions(midi: number): FretPosition[] {\n\tconst positions: FretPosition[] = [];\n\tfor (let s = 0; s < STRING_COUNT; s++) {\n\t\tconst fret = noteToFret(midi, s);\n\t\tif (fret !== null) {\n\t\t\tpositions.push({ string: s, fret });\n\t\t}\n\t}\n\treturn positions;\n}\n\n/**\n * Single canonical placement for a MIDI note: the lowest string that can\n * reach it. This mirrors the piano's \"lowest sensible voicing\" — a beginner\n * sees the note in the lowest fret cluster available.\n *\n * Returns null if the note is off-board (below MIDI 40 or above 64+15=79).\n * Callers should silently skip off-board notes, matching Piano.svelte's\n * behavior for notes outside the visible white-key range.\n */\nexport function chosenPlacement(midi: number): FretPosition | null {\n\tfor (let s = 0; s < STRING_COUNT; s++) {\n\t\tconst fret = noteToFret(midi, s);\n\t\tif (fret !== null) {\n\t\t\treturn { string: s, fret };\n\t\t}\n\t}\n\treturn null;\n}\n\n/**\n * Build a Map from MIDI number to its chosen (canonical) FretPosition for a\n * collection of MIDI values. Off-board values are omitted.\n */\nexport function buildPlacementMap(midiNotes: Iterable<number>): Map<number, FretPosition> {\n\tconst map = new Map<number, FretPosition>();\n\tfor (const midi of midiNotes) {\n\t\tconst pos = chosenPlacement(midi);\n\t\tif (pos !== null) {\n\t\t\tmap.set(midi, pos);\n\t\t}\n\t}\n\treturn map;\n}\n\n// ---------------------------------------------------------------------------\n// Board enumeration\n// ---------------------------------------------------------------------------\n\n/**\n * Enumerate every (string, fret, midi) cell on the board for a given visible\n * fret range [0, visibleFrets]. Useful for rendering the fretboard grid.\n */\nexport function enumerateBoardCells(\n\tvisibleFrets: number = MAX_FRET\n): Array<FretPosition & { midi: number }> {\n\tconst cells: Array<FretPosition & { midi: number }> = [];\n\tfor (let s = 0; s < STRING_COUNT; s++) {\n\t\tfor (let f = 0; f <= visibleFrets; f++) {\n\t\t\tconst midi = STRINGS[s] + f;\n\t\t\tcells.push({ string: s, fret: f, midi });\n\t\t}\n\t}\n\treturn cells;\n}\n\n// ---------------------------------------------------------------------------\n// Best single position (public alias with options)\n// ---------------------------------------------------------------------------\n\nexport interface BestPositionOpts {\n\t/** Maximum fret to consider. Defaults to MAX_FRET. */\n\tmaxFret?: number;\n\t/** Prefer higher strings (index closer to 5) over lower ones. Default false. */\n\tpreferHighString?: boolean;\n}\n\n/**\n * A single playable, low-fret choice for a MIDI note, respecting opts.\n * Returns null if no string can reach the note within maxFret.\n */\nexport function bestPosition(midi: number, opts: BestPositionOpts = {}): FretPosition | null {\n\tconst max = opts.maxFret ?? MAX_FRET;\n\tif (opts.preferHighString) {\n\t\t// Iterate high string first\n\t\tfor (let s = STRING_COUNT - 1; s >= 0; s--) {\n\t\t\tconst fret = midi - STRINGS[s];\n\t\t\tif (fret >= 0 && fret <= max) return { string: s, fret };\n\t\t}\n\t\treturn null;\n\t}\n\t// Default: lowest string first (same as chosenPlacement)\n\tfor (let s = 0; s < STRING_COUNT; s++) {\n\t\tconst fret = midi - STRINGS[s];\n\t\tif (fret >= 0 && fret <= max) return { string: s, fret };\n\t}\n\treturn null;\n}\n\n// ---------------------------------------------------------------------------\n// Chord voicing helper\n// ---------------------------------------------------------------------------\n\nexport interface ChordVoicing {\n\t/** Assigned string index. */\n\tstring: number;\n\t/** Assigned fret. */\n\tfret: number;\n\t/** The MIDI note placed here. */\n\tmidi: number;\n\t/**\n\t * Strum offset in milliseconds from the first note. Notes are sorted\n\t * ascending (low string first) with 12 ms between each successive pick.\n\t */\n\tstrumOffsetMs: number;\n}\n\n/**\n * Distribute a set of MIDI notes across distinct strings for a strummed chord.\n *\n * Algorithm:\n * 1. Sort incoming MIDI notes ascending (lowest pitch first).\n * 2. For each note, greedily assign to the lowest available string whose fret\n *    is in [0, MAX_FRET] and has not yet been used.\n * 3. If no free string is available for a note, it is still included in the\n *    result (midi/strumOffsetMs set) but string/fret will be -1 to signal\n *    \"play at frequency only\" — audio is still correct, just unpositioned.\n * 4. Add 12 ms strum offset per successive note.\n *\n * This keeps audio faithful to the lesson's intended harmony (unchanged lesson\n * data) while sounding guitar-like.\n */\nexport function distributeChord(midiNotes: number[]): ChordVoicing[] {\n\tconst sorted = [...midiNotes].sort((a, b) => a - b);\n\tconst usedStrings = new Set<number>();\n\tconst result: ChordVoicing[] = [];\n\n\tfor (const midi of sorted) {\n\t\tlet assigned: FretPosition | null = null;\n\t\t// Try each string from low to high, skip already-used ones\n\t\tfor (let s = 0; s < STRING_COUNT; s++) {\n\t\t\tif (usedStrings.has(s)) continue;\n\t\t\tconst fret = midi - STRINGS[s];\n\t\t\tif (fret >= 0 && fret <= MAX_FRET) {\n\t\t\t\tassigned = { string: s, fret };\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\n\t\tconst idx = result.length;\n\t\tif (assigned !== null) {\n\t\t\tusedStrings.add(assigned.string);\n\t\t\tresult.push({\n\t\t\t\tstring: assigned.string,\n\t\t\t\tfret: assigned.fret,\n\t\t\t\tmidi,\n\t\t\t\tstrumOffsetMs: idx * 12\n\t\t\t});\n\t\t} else {\n\t\t\t// Off-board or all strings taken: include but mark unpositioned\n\t\t\tresult.push({ string: -1, fret: -1, midi, strumOffsetMs: idx * 12 });\n\t\t}\n\t}\n\n\treturn result;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -61,4 +61,103 @@ interface ChordTemplate {
  *  most specific quality (e.g. maj7 before plain major). */
 declare const CHORD_TEMPLATES: ChordTemplate[];
 
-export { ALL_KEYS, CHORD_TEMPLATES, type ChordTemplate, INTERVALS, type IntervalDef, KEYS_PREFER_FLATS, MAJOR_SCALE_INTERVALS, NOTE_NAMES, NOTE_NAMES_FLAT, getMidiNote, getScaleDegree, getStability, intervalBySemitones, isInScale, midiToFrequency, midiToNoteName, noteNameToIndex, pitchClass, useFlatsForKeyFifths, useFlatsForKeyName };
+/**
+ * fretboard.ts — Pure MIDI <-> guitar fretboard mapping utilities.
+ *
+ * Standard tuning EADGBE, index 0 = low E (6th string), index 5 = high E (1st string).
+ * Open-string MIDI values: E2=40, A2=45, D3=50, G3=55, B3=59, E4=64.
+ *
+ * No Svelte, no audio, no side effects. Unit-testable in isolation.
+ */
+/** Open-string MIDI pitches, low E to high E (index 0 = 6th string). */
+declare const STRINGS: readonly number[];
+/** Number of strings on a standard guitar. */
+declare const STRING_COUNT: number;
+/**
+ * Maximum fret number rendered. Covers MIDI range 40–79 while staying
+ * readable on mobile. Frets 0–15 give string 5 (high E, open=64) a top note
+ * of 79 (G5), well above the piano's practical teaching range.
+ */
+declare const MAX_FRET = 15;
+/** A playable position on the fretboard. string is 0-based (0 = low E). */
+interface FretPosition {
+    /** String index, 0 = low E (6th string), 5 = high E (1st string). */
+    string: number;
+    /** Fret number, 0 = open. */
+    fret: number;
+}
+/**
+ * Compute the fret number for a MIDI note on a specific string, or null if
+ * outside the playable range [0, MAX_FRET].
+ */
+declare function noteToFret(midi: number, stringIndex: number): number | null;
+/**
+ * Return ALL playable positions for a MIDI note across all strings.
+ * Results are ordered from lowest string (index 0) to highest (index 5).
+ * Returns an empty array if the note is unreachable on any string.
+ */
+declare function midiToPositions(midi: number): FretPosition[];
+/**
+ * Single canonical placement for a MIDI note: the lowest string that can
+ * reach it. This mirrors the piano's "lowest sensible voicing" — a beginner
+ * sees the note in the lowest fret cluster available.
+ *
+ * Returns null if the note is off-board (below MIDI 40 or above 64+15=79).
+ * Callers should silently skip off-board notes, matching Piano.svelte's
+ * behavior for notes outside the visible white-key range.
+ */
+declare function chosenPlacement(midi: number): FretPosition | null;
+/**
+ * Build a Map from MIDI number to its chosen (canonical) FretPosition for a
+ * collection of MIDI values. Off-board values are omitted.
+ */
+declare function buildPlacementMap(midiNotes: Iterable<number>): Map<number, FretPosition>;
+/**
+ * Enumerate every (string, fret, midi) cell on the board for a given visible
+ * fret range [0, visibleFrets]. Useful for rendering the fretboard grid.
+ */
+declare function enumerateBoardCells(visibleFrets?: number): Array<FretPosition & {
+    midi: number;
+}>;
+interface BestPositionOpts {
+    /** Maximum fret to consider. Defaults to MAX_FRET. */
+    maxFret?: number;
+    /** Prefer higher strings (index closer to 5) over lower ones. Default false. */
+    preferHighString?: boolean;
+}
+/**
+ * A single playable, low-fret choice for a MIDI note, respecting opts.
+ * Returns null if no string can reach the note within maxFret.
+ */
+declare function bestPosition(midi: number, opts?: BestPositionOpts): FretPosition | null;
+interface ChordVoicing {
+    /** Assigned string index. */
+    string: number;
+    /** Assigned fret. */
+    fret: number;
+    /** The MIDI note placed here. */
+    midi: number;
+    /**
+     * Strum offset in milliseconds from the first note. Notes are sorted
+     * ascending (low string first) with 12 ms between each successive pick.
+     */
+    strumOffsetMs: number;
+}
+/**
+ * Distribute a set of MIDI notes across distinct strings for a strummed chord.
+ *
+ * Algorithm:
+ * 1. Sort incoming MIDI notes ascending (lowest pitch first).
+ * 2. For each note, greedily assign to the lowest available string whose fret
+ *    is in [0, MAX_FRET] and has not yet been used.
+ * 3. If no free string is available for a note, it is still included in the
+ *    result (midi/strumOffsetMs set) but string/fret will be -1 to signal
+ *    "play at frequency only" — audio is still correct, just unpositioned.
+ * 4. Add 12 ms strum offset per successive note.
+ *
+ * This keeps audio faithful to the lesson's intended harmony (unchanged lesson
+ * data) while sounding guitar-like.
+ */
+declare function distributeChord(midiNotes: number[]): ChordVoicing[];
+
+export { ALL_KEYS, type BestPositionOpts, CHORD_TEMPLATES, type ChordTemplate, type ChordVoicing, type FretPosition, INTERVALS, type IntervalDef, KEYS_PREFER_FLATS, MAJOR_SCALE_INTERVALS, MAX_FRET, NOTE_NAMES, NOTE_NAMES_FLAT, STRINGS, STRING_COUNT, bestPosition, buildPlacementMap, chosenPlacement, distributeChord, enumerateBoardCells, getMidiNote, getScaleDegree, getStability, intervalBySemitones, isInScale, midiToFrequency, midiToNoteName, midiToPositions, noteNameToIndex, noteToFret, pitchClass, useFlatsForKeyFifths, useFlatsForKeyName };

package/dist/index.js

@@ -5,8 +5,18 @@ import {
 } from "./chunk-BYZBLH25.js";
 import {
   INTERVALS,
-  intervalBySemitones
-} from "./chunk-N56UTMWA.js";
+  MAX_FRET,
+  STRINGS,
+  STRING_COUNT,
+  bestPosition,
+  buildPlacementMap,
+  chosenPlacement,
+  distributeChord,
+  enumerateBoardCells,
+  intervalBySemitones,
+  midiToPositions,
+  noteToFret
+} from "./chunk-ILIXNGPE.js";
 import {
   ALL_KEYS,
   MAJOR_SCALE_INTERVALS,
@@ -46,8 +56,16 @@ export {
   INTERVALS,
   KEYS_PREFER_FLATS,
   MAJOR_SCALE_INTERVALS,
+  MAX_FRET,
   NOTE_NAMES,
   NOTE_NAMES_FLAT,
+  STRINGS,
+  STRING_COUNT,
+  bestPosition,
+  buildPlacementMap,
+  chosenPlacement,
+  distributeChord,
+  enumerateBoardCells,
   getMidiNote,
   getScaleDegree,
   getStability,
@@ -55,7 +73,9 @@ export {
   isInScale,
   midiToFrequency,
   midiToNoteName,
+  midiToPositions,
   noteNameToIndex,
+  noteToFret,
   pitchClass,
   useFlatsForKeyFifths,
   useFlatsForKeyName

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/frequency.ts","../src/chords.ts"],"sourcesContent":["/** Equal-temperament MIDI → frequency (A4 = MIDI 69 = 440 Hz). */\nexport function midiToFrequency(midi: number): number {\n  return 440 * Math.pow(2, (midi - 69) / 12);\n}\n","export interface ChordTemplate { name: string; intervals: number[] }\n\n/** Chord-quality templates, richer qualities first so naming matches the\n *  most specific quality (e.g. maj7 before plain major). */\nexport const CHORD_TEMPLATES: ChordTemplate[] = [\n  { name: 'maj7', intervals: [0, 4, 7, 11] },\n  { name: '7',    intervals: [0, 4, 7, 10] },\n  { name: 'm7',   intervals: [0, 3, 7, 10] },\n  { name: 'dim7', intervals: [0, 3, 6, 9] },\n  { name: 'm7b5', intervals: [0, 3, 6, 10] },\n  { name: '',     intervals: [0, 4, 7] },\n  { name: 'm',    intervals: [0, 3, 7] },\n  { name: 'dim',  intervals: [0, 3, 6] },\n  { name: 'aug',  intervals: [0, 4, 8] },\n  { name: 'sus4', intervals: [0, 5, 7] },\n  { name: 'sus2', intervals: [0, 2, 7] },\n];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AACO,SAAS,gBAAgB,MAAsB;AACpD,SAAO,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,EAAE;AAC3C;;;ACCO,IAAM,kBAAmC;AAAA,EAC9C,EAAE,MAAM,QAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,EAAE,EAAE;AAAA,EACzC,EAAE,MAAM,KAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,EAAE,EAAE;AAAA,EACzC,EAAE,MAAM,MAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,EAAE,EAAE;AAAA,EACzC,EAAE,MAAM,QAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,CAAC,EAAE;AAAA,EACxC,EAAE,MAAM,QAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,EAAE,EAAE;AAAA,EACzC,EAAE,MAAM,IAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AAAA,EACrC,EAAE,MAAM,KAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AAAA,EACrC,EAAE,MAAM,OAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AAAA,EACrC,EAAE,MAAM,OAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AAAA,EACrC,EAAE,MAAM,QAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AAAA,EACrC,EAAE,MAAM,QAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AACvC;","names":[]}
+{"version":3,"sources":["../src/frequency.ts","../src/chords.ts"],"sourcesContent":["/** Equal-temperament MIDI → frequency (A4 = MIDI 69 = 440 Hz). */\nexport function midiToFrequency(midi: number): number {\n  return 440 * Math.pow(2, (midi - 69) / 12);\n}\n","export interface ChordTemplate { name: string; intervals: number[] }\n\n/** Chord-quality templates, richer qualities first so naming matches the\n *  most specific quality (e.g. maj7 before plain major). */\nexport const CHORD_TEMPLATES: ChordTemplate[] = [\n  { name: 'maj7', intervals: [0, 4, 7, 11] },\n  { name: '7',    intervals: [0, 4, 7, 10] },\n  { name: 'm7',   intervals: [0, 3, 7, 10] },\n  { name: 'dim7', intervals: [0, 3, 6, 9] },\n  { name: 'm7b5', intervals: [0, 3, 6, 10] },\n  { name: '',     intervals: [0, 4, 7] },\n  { name: 'm',    intervals: [0, 3, 7] },\n  { name: 'dim',  intervals: [0, 3, 6] },\n  { name: 'aug',  intervals: [0, 4, 8] },\n  { name: 'sus4', intervals: [0, 5, 7] },\n  { name: 'sus2', intervals: [0, 2, 7] },\n];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACO,SAAS,gBAAgB,MAAsB;AACpD,SAAO,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,EAAE;AAC3C;;;ACCO,IAAM,kBAAmC;AAAA,EAC9C,EAAE,MAAM,QAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,EAAE,EAAE;AAAA,EACzC,EAAE,MAAM,KAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,EAAE,EAAE;AAAA,EACzC,EAAE,MAAM,MAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,EAAE,EAAE;AAAA,EACzC,EAAE,MAAM,QAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,CAAC,EAAE;AAAA,EACxC,EAAE,MAAM,QAAQ,WAAW,CAAC,GAAG,GAAG,GAAG,EAAE,EAAE;AAAA,EACzC,EAAE,MAAM,IAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AAAA,EACrC,EAAE,MAAM,KAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AAAA,EACrC,EAAE,MAAM,OAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AAAA,EACrC,EAAE,MAAM,OAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AAAA,EACrC,EAAE,MAAM,QAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AAAA,EACrC,EAAE,MAAM,QAAQ,WAAW,CAAC,GAAG,GAAG,CAAC,EAAE;AACvC;","names":[]}

package/dist/scene/index.d.ts

@@ -1017,6 +1017,24 @@ interface KeyboardProps {
 }
 declare const keyboardFactory: LayerFactory<KeyboardProps>;
 
+interface FretboardProps {
+    /** Highest fret drawn. Default: auto-fit the excerpt (min 5, max 15), padded. */
+    visibleFrets?: number;
+    /** Board height in world px. Default 360 — 6 strings need more vertical room
+     *  than the piano strip (220 cramped them to ~37px each). */
+    height?: number;
+    /** Board bottom edge in world px. Default safeBox.bottom. */
+    bottomY?: number;
+    /** Right/left hand dot colours. Defaults R=theme.accent, L=theme.gold. */
+    handColors?: {
+        R: string;
+        L: string;
+    };
+    /** Draw note-name labels inside lit dots. Default false. */
+    showLabels?: boolean;
+}
+declare const fretboardFactory: LayerFactory<FretboardProps>;
+
 interface FallingNotesProps {
     /** Pair with a `keyboard` layer (read its layout + hit-line). When false the
      *  layer is standalone and builds its own layout from the props below.
@@ -1971,4 +1989,24 @@ interface EndCardProps {
 }
 declare const endCardFactory: LayerFactory<EndCardProps>;
 
-export { type Affine, type AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatPulseProps, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordRibbonProps, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type ContourPlot, type ContourPoint, type CountInOpts, type CountdownProps, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type EndCardProps, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type IntervalArcsProps, type KaraokeCaptionProps, type KaraokeWord, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type KineticMode, type KineticTextProps, type LabelMode, type Layer, type LayerFactory, type McqCardProps, type NotationEngraving, type NotationLayout, type NotationLayoutOpts, type NotationProps, type NotationRect, type OutputProbe, PIANO_HIGH, PIANO_LOW, type ParticleBurstProps, type PitchContourProps, type Placement, type PlayheadLine, type PortraitProps, type ProgressRingProps, type PromoCardsDemoOpts, type PulseStyle, type Quiz, type QuizOption, type QuizPhase, type RadialSpectrumProps, type RayEndpoints, type RecordSceneSpecOpts, type Rect, type RenderCtx, type ResolvedSegment, type RevealProps, SCALE_INTERVALS, type SafeGuidesProps, type ScaleHighlightProps, type SceneSpec, type ScheduleTarget, type Score, type ScoreFromMusicXMLOpts, type ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type SpectrumInput, type SpectrumProps, type StaffKeyboardRayProps, type StatCounterProps, type TempoMap, type TensionGraphProps, type TensionPoint, type TextureProps, type TimeAnchor, type TimelineSegment, type WaveformInput, type WaveformProps, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, audioPlayheadLine, ballArc, ballX, beatGrid, beatPhase, beatPulseFactory, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, chordRibbonFactory, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownFactory, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, cropAroundBox, ctaFactory, cubicEaseInOut, cueOpacity, degreeLabel, degreeLabelsFactory, distinctMeasureIndices, distinctOnsets, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, endCardFactory, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, firstMeasureBox, followBoxAt, followSrcBox, followWindowStart, fracSlotPoint, frameRect, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, inRange, intervalArcsFactory, invLerp, isBlackKey, karaokeCaptionFactory, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, kineticTextFactory, lerp, lerpBox, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureColumnsFromLayout, measureCount, measureSpanBox, measureSpans, measureSystemMap, timeToX as minimapTimeToX, msPerBeat, notationFactory, notationLayout, noteColor, noteSetXRange, parseKey, parseTimeSig, particleBurstFactory, pcToSlot, pitchAt, pitchContourFactory, pitchRange, playheadLine, portraitFactory, progress01, progressRingFactory, projectPoint, promoCardsDemoSpec, pulseAt, quizPhase, radialSpectrumFactory, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scaleHighlightFactory, scoreFromMusicXML, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, spectrumFactory, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, statCounterFactory, systemBox, tensionGraphFactory, textureFactory, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, vstackAudioPlayheadLine, vstackFollowBox, waveformFactory, whiteKeys, worldToViewport };
+type ImageRevealMode = 'pixelate' | 'shuffle' | 'blur';
+interface ImageRevealProps {
+    /** The image to reveal. Any CanvasImageSource (HTMLImageElement, OffscreenCanvas, …). */
+    image: CanvasImageSource;
+    /** Reveal mode. Default 'pixelate'. */
+    mode?: ImageRevealMode;
+    /** When the reveal starts (ms). Default 0. */
+    startMs?: number;
+    /** How long the full reveal takes (ms). Default 6000. */
+    durationMs?: number;
+    /**
+     * Difficulty scalar 0..1.
+     * - pixelate: controls maximum block size (0→small, 1→large; default 0.5 ≈ 1/8 width).
+     * - shuffle:  controls maximum tile offset fraction (default 0.5).
+     * - blur:     controls maximum blur radius in px (0→mild, 1→extreme; default 0.5 ≈ 40px).
+     */
+    difficulty?: number;
+}
+declare const imageRevealFactory: LayerFactory<ImageRevealProps>;
+
+export { type Affine, type AudioClock, type AudioEvent, type BackgroundProps, type BeatGridOpts, type BeatPulseProps, type BeatTick, type BrandingProps, type BufferFactory, type BuildSceneOpts, type BuiltScene, type CameraState, type CaptionCue, type CaptionProps, type CaptionScript, type CaptionStyle, type ChordRibbonProps, type ChordSpan, type CircleOfFifthsProps, type CirclePoint, type ClickTrackOpts, type ColorBy, type ContourPlot, type ContourPoint, type CountInOpts, type CountdownProps, type CountingTrackProps, type CtaProps, DEFAULT_FUNCTION_COLORS, type DegreeLabel, type DegreeLabelsProps, type DroneOpts, type DuckWindow, type Easing, type EndCardProps, type ExtendedDemoOpts, FIFTHS_MAJOR, FIFTHS_MINOR, FOLLOW_BARS, FOLLOW_PAD, type FallingKeyboardDemoOpts, type FallingNotesProps, type FretboardProps, type FunctionColors, type FunctionalHarmonyProps, type GateError, type GateInput, type HandColors, type HarmonicFunction, type HarmonyMode, type HighlightRegion, type HookProps, type ImageRevealMode, type ImageRevealProps, type IntervalArcsProps, type KaraokeCaptionProps, type KaraokeWord, type KeyRect, type KeyboardLayout, type KeyboardLayoutOpts, type KeyboardProps, type KineticMode, type KineticTextProps, type LabelMode, type Layer, type LayerFactory, type McqCardProps, type NotationEngraving, type NotationLayout, type NotationLayoutOpts, type NotationProps, type NotationRect, type OutputProbe, PIANO_HIGH, PIANO_LOW, type ParticleBurstProps, type PitchContourProps, type Placement, type PlayheadLine, type PortraitProps, type ProgressRingProps, type PromoCardsDemoOpts, type PulseStyle, type Quiz, type QuizOption, type QuizPhase, type RadialSpectrumProps, type RayEndpoints, type RecordSceneSpecOpts, type Rect, type RenderCtx, type ResolvedSegment, type RevealProps, SCALE_INTERVALS, type SafeGuidesProps, type ScaleHighlightProps, type SceneSpec, type ScheduleTarget, type Score, type ScoreFromMusicXMLOpts, type ScoreNote, type ScrollCursorProps, type Section, type SectionMinimapProps, type SegmentAudio, type SegmentAudioCtx, type SegmentTransition, type SpecLayer, type SpectrumInput, type SpectrumProps, type StaffKeyboardRayProps, type StatCounterProps, type TempoMap, type TensionGraphProps, type TensionPoint, type TextureProps, type TimeAnchor, type TimelineSegment, type WaveformInput, type WaveformProps, activeChord, activeCue, activeSection, animatedSlot, applySchedule, applyToContext, assertGate, audioPlayheadLine, ballArc, ballX, beatGrid, beatPhase, beatPulseFactory, blackKeys, bpmOf, brandingFactory, buildScene, cameraForFollow, cameraTransform, chordRibbonFactory, circleOfFifthsDemoSpec, circleOfFifthsFactory, clamp, clickTrackSchedule, contourMinimapDemoSpec, contourPoints, contourPolyline, countInLeadSec, countInSchedule, countdownFactory, countdownRemaining, countdownSeconds, countingDegreeDemoSpec, countingTrackFactory, cropAroundBox, ctaFactory, cubicEaseInOut, cueOpacity, degreeLabel, degreeLabelsFactory, distinctMeasureIndices, distinctOnsets, dotAt, drawCaption, drawHighlight, droneSchedule, duckGainAt, easeIn, easeInOut, easeOut, endCardFactory, fallingKeyboardDemoScore, fallingKeyboardDemoSpec, fallingNotesFactory, firstMeasureBox, followBoxAt, followSrcBox, followWindowStart, fracSlotPoint, frameRect, fretboardFactory, functionColor, functionalHarmonyFactory, getKeyboardLayout, getLayerFactory, getNotationEngraving, harmonyDemoSpec, highlightIntensity, hookFactory, identityCamera, imageRevealFactory, inRange, intervalArcsFactory, invLerp, isBlackKey, karaokeCaptionFactory, kenBurns, keyCenterX, keyColumnWidth, keyRect, keySlot, keyboardFactory, keyboardLayout, kineticTextFactory, lerp, lerpBox, lerpCamera, linear, mapBoxThroughLayout, mcqCardFactory, mcqDemoSpec, measureColumnsFromLayout, measureCount, measureSpanBox, measureSpans, measureSystemMap, timeToX as minimapTimeToX, msPerBeat, notationFactory, notationLayout, noteColor, noteSetXRange, parseKey, parseTimeSig, particleBurstFactory, pcToSlot, pitchAt, pitchContourFactory, pitchRange, playheadLine, portraitFactory, progress01, progressRingFactory, projectPoint, promoCardsDemoSpec, pulseAt, quizPhase, radialSpectrumFactory, rayEndpoints, rayPointAt, recordSceneSpec, registerLayer, registeredKeys, resolveAnchor, resolveKeyboardLayout, resolveTimeline, revealFactory, revealProgress, runGate, safeGuidesFactory, scaleHighlightFactory, scoreFromMusicXML, scorePitchSpan, scrollCursorFactory, sectionMinimapFactory, setFollowLayoutProvider, setKeyboardLayout, setNotationEngraving, slotAngle, slotPc, slotPoint, spectrumFactory, staffAnchor, staffKeyboardRayFactory, staffRayDemoSpec, statCounterFactory, systemBox, tensionGraphFactory, textureFactory, transitionProgress, validateChordTrack, validateQuiz, validateSections, visualTimelineMs, vstackAudioPlayheadLine, vstackFollowBox, waveformFactory, whiteKeys, worldToViewport };