@real-music-packages/web-core 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @real-music-packages/web-core
+
+Shared, framework-agnostic music-theory primitives for the music-suite web apps
+(stave-web-sightread / RealSightReader and realeartrainer-web). Pure TypeScript —
+no DOM, Tone.js, Svelte, or OSMD. Published publicly on npmjs.com.
+
+## Modules
+- **notes** — `NOTE_NAMES`, `NOTE_NAMES_FLAT`, `noteNameToIndex(name)`, `pitchClass(midi)`, `midiToNoteName(midi, useFlats?)`
+- **frequency** — `midiToFrequency(midi)` (equal temperament, A4=440)
+- **enharmonic** — `KEYS_PREFER_FLATS`, `useFlatsForKeyName(key)`, `useFlatsForKeyFifths(fifths)` (bridges RET's key-name model and Stave's keyFifths model)
+- **scales** — `MAJOR_SCALE_INTERVALS`, `ALL_KEYS`, `getMidiNote(degree, key, octave?)`, `getScaleDegree(midi, key)`, `isInScale(midi, key)`, `getStability(degree)`
+- **intervals** — `INTERVALS`, `intervalBySemitones(n)`
+- **chords** — `CHORD_TEMPLATES` (quality → interval set, richer qualities first)
+
+## ⚠️ Octave-base gotcha (`scales.getMidiNote` / `getScaleDegree`)
+These are ported verbatim from RealEarTrainer and use **RET's non-standard octave
+base**: `getMidiNote(1, 'C', 4) === 48`, i.e. one octave below the General-MIDI
+convention (where C4 = 60). They are internally consistent and RET-only. The
+general-purpose helpers (`midiToNoteName`, `midiToFrequency`, `pitchClass`) use the
+**standard** GM convention (C4 = 60). Don't mix `getMidiNote`'s output with the
+standard helpers without accounting for the one-octave offset.
+
+## Install (consumers)
+Published publicly on npmjs.com — no auth/token needed anywhere:
+```
+npm install @real-music-packages/web-core
+```
+
+## Dev
+```
+npm install
+npm test          # vitest
+npm run build     # tsup → dist/ (ESM + .d.ts)
+```
+
+## Publishing
+Public on npmjs.com under the `@e7mac` scope. Push a `v*` tag; the GitHub Actions
+`Publish` workflow runs tests, builds, and `npm publish --access public` using the
+`NPM_TOKEN` repo secret (an npm automation token with publish rights).

package/dist/audio.d.ts

@@ -0,0 +1,31 @@
+declare const SALAMANDER_CDN_BASE = "https://tonejs.github.io/audio/salamander/";
+/** 8-anchor sample set (Stave uses these from the CDN). */
+declare const SALAMANDER_URLS_8: Record<string, string>;
+/** Full chromatic-anchor set A0..C8 (RET ships these locally under /audio/salamander/). */
+declare const SALAMANDER_URLS_FULL: Record<string, string>;
+
+/**
+ * Emit a near-silent, very short tone on the given AudioContext. iOS Safari
+ * only unlocks audio if actual output is produced DURING the user gesture —
+ * resuming the context alone is not enough. Call this synchronously inside a
+ * click/pointerdown handler. (This is the trick RET's old unlock() omitted.)
+ */
+declare function emitUnlockBlip(ctx: AudioContext): void;
+type ToneContextSetter = (ctx: AudioContext) => void;
+/**
+ * Owns a raw AudioContext that is created + resumed SYNCHRONOUSLY inside the
+ * first user gesture, then emits an unlock blip on it. Hand the context to your
+ * audio library (e.g. Tone.setContext) via the onContext callback so the lib
+ * runs on an already-running context (so its own start()/resume() can't hang
+ * on iOS). Tone-agnostic — works with any version or no Tone at all.
+ */
+declare function createAudioUnlocker(): {
+    /** Call SYNCHRONOUSLY from a user gesture. Idempotent. */
+    unlock(onContext?: ToneContextSetter): void;
+    /** Resume the context if it has fallen back to suspended/interrupted. */
+    ensureRunning(): void;
+    readonly context: AudioContext | null;
+};
+type AudioUnlocker = ReturnType<typeof createAudioUnlocker>;
+
+export { type AudioUnlocker, SALAMANDER_CDN_BASE, SALAMANDER_URLS_8, SALAMANDER_URLS_FULL, createAudioUnlocker, emitUnlockBlip };

package/dist/audio.js

@@ -0,0 +1,103 @@
+// src/salamander.ts
+var SALAMANDER_CDN_BASE = "https://tonejs.github.io/audio/salamander/";
+var SALAMANDER_URLS_8 = {
+  C2: "C2.mp3",
+  "F#2": "Fs2.mp3",
+  C3: "C3.mp3",
+  "F#3": "Fs3.mp3",
+  C4: "C4.mp3",
+  "F#4": "Fs4.mp3",
+  C5: "C5.mp3",
+  "F#5": "Fs5.mp3"
+};
+var SALAMANDER_URLS_FULL = {
+  A0: "A0.mp3",
+  C1: "C1.mp3",
+  "D#1": "Ds1.mp3",
+  "F#1": "Fs1.mp3",
+  A1: "A1.mp3",
+  C2: "C2.mp3",
+  "D#2": "Ds2.mp3",
+  "F#2": "Fs2.mp3",
+  A2: "A2.mp3",
+  C3: "C3.mp3",
+  "D#3": "Ds3.mp3",
+  "F#3": "Fs3.mp3",
+  A3: "A3.mp3",
+  C4: "C4.mp3",
+  "D#4": "Ds4.mp3",
+  "F#4": "Fs4.mp3",
+  A4: "A4.mp3",
+  C5: "C5.mp3",
+  "D#5": "Ds5.mp3",
+  "F#5": "Fs5.mp3",
+  A5: "A5.mp3",
+  C6: "C6.mp3",
+  "D#6": "Ds6.mp3",
+  "F#6": "Fs6.mp3",
+  A6: "A6.mp3",
+  C7: "C7.mp3",
+  "D#7": "Ds7.mp3",
+  "F#7": "Fs7.mp3",
+  A7: "A7.mp3",
+  C8: "C8.mp3"
+};
+
+// src/audioUnlock.ts
+function emitUnlockBlip(ctx) {
+  try {
+    const osc = ctx.createOscillator();
+    const gain = ctx.createGain();
+    gain.gain.value = 5e-4;
+    osc.type = "sine";
+    osc.frequency.value = 440;
+    osc.connect(gain);
+    gain.connect(ctx.destination);
+    const t = ctx.currentTime;
+    osc.start(t);
+    osc.stop(t + 0.05);
+  } catch {
+  }
+}
+function createAudioUnlocker() {
+  let ctx = null;
+  let blipped = false;
+  function ensureContext() {
+    if (ctx) return ctx;
+    if (typeof window === "undefined") return null;
+    const AC = window.AudioContext || window.webkitAudioContext;
+    if (!AC) return null;
+    ctx = new AC();
+    return ctx;
+  }
+  return {
+    /** Call SYNCHRONOUSLY from a user gesture. Idempotent. */
+    unlock(onContext) {
+      const c = ensureContext();
+      if (!c) return;
+      if (c.state !== "running") c.resume().catch(() => {
+      });
+      if (!blipped) {
+        emitUnlockBlip(c);
+        blipped = true;
+      }
+      onContext?.(c);
+    },
+    /** Resume the context if it has fallen back to suspended/interrupted. */
+    ensureRunning() {
+      if (ctx && ctx.state !== "running") ctx.resume().catch(() => {
+      });
+    },
+    get context() {
+      return ctx;
+    }
+  };
+}
+export {
+  SALAMANDER_CDN_BASE,
+  SALAMANDER_URLS_8,
+  SALAMANDER_URLS_FULL,
+  createAudioUnlocker,
+  emitUnlockBlip
+};
+//# sourceMappingURL=audio.js.map

package/dist/audio.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/salamander.ts","../src/audioUnlock.ts"],"sourcesContent":["export const SALAMANDER_CDN_BASE = 'https://tonejs.github.io/audio/salamander/';\n\n/** 8-anchor sample set (Stave uses these from the CDN). */\nexport const SALAMANDER_URLS_8: Record<string, string> = {\n  C2: 'C2.mp3', 'F#2': 'Fs2.mp3', C3: 'C3.mp3', 'F#3': 'Fs3.mp3',\n  C4: 'C4.mp3', 'F#4': 'Fs4.mp3', C5: 'C5.mp3', 'F#5': 'Fs5.mp3',\n};\n\n/** Full chromatic-anchor set A0..C8 (RET ships these locally under /audio/salamander/). */\nexport const SALAMANDER_URLS_FULL: Record<string, string> = {\n  A0: 'A0.mp3', C1: 'C1.mp3', 'D#1': 'Ds1.mp3', 'F#1': 'Fs1.mp3', A1: 'A1.mp3',\n  C2: 'C2.mp3', 'D#2': 'Ds2.mp3', 'F#2': 'Fs2.mp3', A2: 'A2.mp3',\n  C3: 'C3.mp3', 'D#3': 'Ds3.mp3', 'F#3': 'Fs3.mp3', A3: 'A3.mp3',\n  C4: 'C4.mp3', 'D#4': 'Ds4.mp3', 'F#4': 'Fs4.mp3', A4: 'A4.mp3',\n  C5: 'C5.mp3', 'D#5': 'Ds5.mp3', 'F#5': 'Fs5.mp3', A5: 'A5.mp3',\n  C6: 'C6.mp3', 'D#6': 'Ds6.mp3', 'F#6': 'Fs6.mp3', A6: 'A6.mp3',\n  C7: 'C7.mp3', 'D#7': 'Ds7.mp3', 'F#7': 'Fs7.mp3', A7: 'A7.mp3',\n  C8: 'C8.mp3',\n};\n","/**\n * Emit a near-silent, very short tone on the given AudioContext. iOS Safari\n * only unlocks audio if actual output is produced DURING the user gesture —\n * resuming the context alone is not enough. Call this synchronously inside a\n * click/pointerdown handler. (This is the trick RET's old unlock() omitted.)\n */\nexport function emitUnlockBlip(ctx: AudioContext): void {\n  try {\n    const osc = ctx.createOscillator();\n    const gain = ctx.createGain();\n    gain.gain.value = 0.0005; // effectively inaudible\n    osc.type = 'sine';\n    osc.frequency.value = 440;\n    osc.connect(gain);\n    gain.connect(ctx.destination);\n    const t = ctx.currentTime;\n    osc.start(t);\n    osc.stop(t + 0.05);\n  } catch {\n    /* best-effort: never throw out of an unlock path */\n  }\n}\n\ntype ToneContextSetter = (ctx: AudioContext) => void;\n\n/**\n * Owns a raw AudioContext that is created + resumed SYNCHRONOUSLY inside the\n * first user gesture, then emits an unlock blip on it. Hand the context to your\n * audio library (e.g. Tone.setContext) via the onContext callback so the lib\n * runs on an already-running context (so its own start()/resume() can't hang\n * on iOS). Tone-agnostic — works with any version or no Tone at all.\n */\nexport function createAudioUnlocker() {\n  let ctx: AudioContext | null = null;\n  let blipped = false;\n\n  function ensureContext(): AudioContext | null {\n    if (ctx) return ctx;\n    if (typeof window === 'undefined') return null;\n    const AC = (window.AudioContext ||\n      (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext) as\n      | typeof AudioContext\n      | undefined;\n    if (!AC) return null;\n    ctx = new AC();\n    return ctx;\n  }\n\n  return {\n    /** Call SYNCHRONOUSLY from a user gesture. Idempotent. */\n    unlock(onContext?: ToneContextSetter): void {\n      const c = ensureContext();\n      if (!c) return;\n      if (c.state !== 'running') c.resume().catch(() => {});\n      if (!blipped) { emitUnlockBlip(c); blipped = true; }\n      onContext?.(c);\n    },\n    /** Resume the context if it has fallen back to suspended/interrupted. */\n    ensureRunning(): void {\n      if (ctx && ctx.state !== 'running') ctx.resume().catch(() => {});\n    },\n    get context(): AudioContext | null { return ctx; },\n  };\n}\n\nexport type AudioUnlocker = ReturnType<typeof createAudioUnlocker>;\n"],"mappings":";AAAO,IAAM,sBAAsB;AAG5B,IAAM,oBAA4C;AAAA,EACvD,IAAI;AAAA,EAAU,OAAO;AAAA,EAAW,IAAI;AAAA,EAAU,OAAO;AAAA,EACrD,IAAI;AAAA,EAAU,OAAO;AAAA,EAAW,IAAI;AAAA,EAAU,OAAO;AACvD;AAGO,IAAM,uBAA+C;AAAA,EAC1D,IAAI;AAAA,EAAU,IAAI;AAAA,EAAU,OAAO;AAAA,EAAW,OAAO;AAAA,EAAW,IAAI;AAAA,EACpE,IAAI;AAAA,EAAU,OAAO;AAAA,EAAW,OAAO;AAAA,EAAW,IAAI;AAAA,EACtD,IAAI;AAAA,EAAU,OAAO;AAAA,EAAW,OAAO;AAAA,EAAW,IAAI;AAAA,EACtD,IAAI;AAAA,EAAU,OAAO;AAAA,EAAW,OAAO;AAAA,EAAW,IAAI;AAAA,EACtD,IAAI;AAAA,EAAU,OAAO;AAAA,EAAW,OAAO;AAAA,EAAW,IAAI;AAAA,EACtD,IAAI;AAAA,EAAU,OAAO;AAAA,EAAW,OAAO;AAAA,EAAW,IAAI;AAAA,EACtD,IAAI;AAAA,EAAU,OAAO;AAAA,EAAW,OAAO;AAAA,EAAW,IAAI;AAAA,EACtD,IAAI;AACN;;;ACZO,SAAS,eAAe,KAAyB;AACtD,MAAI;AACF,UAAM,MAAM,IAAI,iBAAiB;AACjC,UAAM,OAAO,IAAI,WAAW;AAC5B,SAAK,KAAK,QAAQ;AAClB,QAAI,OAAO;AACX,QAAI,UAAU,QAAQ;AACtB,QAAI,QAAQ,IAAI;AAChB,SAAK,QAAQ,IAAI,WAAW;AAC5B,UAAM,IAAI,IAAI;AACd,QAAI,MAAM,CAAC;AACX,QAAI,KAAK,IAAI,IAAI;AAAA,EACnB,QAAQ;AAAA,EAER;AACF;AAWO,SAAS,sBAAsB;AACpC,MAAI,MAA2B;AAC/B,MAAI,UAAU;AAEd,WAAS,gBAAqC;AAC5C,QAAI,IAAK,QAAO;AAChB,QAAI,OAAO,WAAW,YAAa,QAAO;AAC1C,UAAM,KAAM,OAAO,gBAChB,OAAmE;AAGtE,QAAI,CAAC,GAAI,QAAO;AAChB,UAAM,IAAI,GAAG;AACb,WAAO;AAAA,EACT;AAEA,SAAO;AAAA;AAAA,IAEL,OAAO,WAAqC;AAC1C,YAAM,IAAI,cAAc;AACxB,UAAI,CAAC,EAAG;AACR,UAAI,EAAE,UAAU,UAAW,GAAE,OAAO,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AACpD,UAAI,CAAC,SAAS;AAAE,uBAAe,CAAC;AAAG,kBAAU;AAAA,MAAM;AACnD,kBAAY,CAAC;AAAA,IACf;AAAA;AAAA,IAEA,gBAAsB;AACpB,UAAI,OAAO,IAAI,UAAU,UAAW,KAAI,OAAO,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IACjE;AAAA,IACA,IAAI,UAA+B;AAAE,aAAO;AAAA,IAAK;AAAA,EACnD;AACF;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+declare const NOTE_NAMES: readonly ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+declare const NOTE_NAMES_FLAT: readonly ["C", "Db", "D", "Eb", "E", "F", "Gb", "G", "Ab", "A", "Bb", "B"];
+/** Note name (e.g. "C", "C#", "Db", "Cb") → pitch class 0..11. */
+declare function noteNameToIndex(note: string): number;
+/** MIDI number → pitch class 0..11. */
+declare function pitchClass(midi: number): number;
+/** MIDI → note name with octave, e.g. 61 → "C#4" (or "Db4" with useFlats). */
+declare function midiToNoteName(midi: number, useFlats?: boolean): string;
+
+/** Equal-temperament MIDI → frequency (A4 = MIDI 69 = 440 Hz). */
+declare function midiToFrequency(midi: number): number;
+
+/** Keys conventionally spelled with flats (RET's key-name model). */
+declare const KEYS_PREFER_FLATS: readonly ["F", "Bb", "Eb", "Ab", "Db", "Gb"];
+/** Whether to use flat spellings for a key given by name (e.g. "Eb"). */
+declare function useFlatsForKeyName(key: string): boolean;
+/**
+ * Whether to use flat spellings for a key given by its key-signature "fifths"
+ * value (Stave's model: -7..+7, negative = flat keys). 0 (C) and positive
+ * (sharp keys) use sharps.
+ */
+declare function useFlatsForKeyFifths(fifths: number): boolean;
+
+declare const MAJOR_SCALE_INTERVALS: readonly [0, 2, 4, 5, 7, 9, 11];
+declare const ALL_KEYS: readonly ["C", "G", "D", "A", "E", "B", "F#", "F", "Bb", "Eb", "Ab", "Db"];
+/**
+ * Get MIDI note number for a scale degree in a given key.
+ * Ported verbatim from RET src/lib/audio/scales.ts.
+ * NOTE: RET uses octave*12 (not (octave+1)*12), so getMidiNote(1,'C',4)=48,
+ * not 60. This is RET's established convention — consumers must account for it.
+ */
+declare function getMidiNote(degree: number, key: string, octave?: number): number;
+/**
+ * Get the scale degree (1-7) for a MIDI note in a key, or null if not in scale.
+ * Ported verbatim from RET src/lib/audio/scales.ts.
+ */
+declare function getScaleDegree(midiNote: number, key: string): number | null;
+/**
+ * Check if a MIDI note is in the given key.
+ */
+declare function isInScale(midiNote: number, key: string): boolean;
+/**
+ * Get stability category for a scale degree.
+ * Ported verbatim from RET src/lib/audio/scales.ts.
+ */
+declare function getStability(degree: number): 'stable' | 'lessStable' | 'unstable' | null;
+
+interface IntervalDef {
+    semitones: number;
+    label: string;
+    mnemonic: string;
+}
+declare const INTERVALS: IntervalDef[];
+declare function intervalBySemitones(semitones: number): IntervalDef | undefined;
+
+interface ChordTemplate {
+    name: string;
+    intervals: number[];
+}
+/** Chord-quality templates, richer qualities first so naming matches the
+ *  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 };

package/dist/index.js

@@ -0,0 +1,117 @@
+// src/notes.ts
+var NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+var NOTE_NAMES_FLAT = ["C", "Db", "D", "Eb", "E", "F", "Gb", "G", "Ab", "A", "Bb", "B"];
+var LETTER_TO_INDEX = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+function noteNameToIndex(note) {
+  const letter = note[0]?.toUpperCase();
+  let index = LETTER_TO_INDEX[letter];
+  if (index === void 0) throw new Error(`Invalid note name: ${note}`);
+  for (const ch of note.slice(1)) {
+    if (ch === "#") index += 1;
+    else if (ch === "b") index -= 1;
+  }
+  return (index % 12 + 12) % 12;
+}
+function pitchClass(midi) {
+  return (midi % 12 + 12) % 12;
+}
+function midiToNoteName(midi, useFlats = false) {
+  const names = useFlats ? NOTE_NAMES_FLAT : NOTE_NAMES;
+  const octave = Math.floor(midi / 12) - 1;
+  return `${names[pitchClass(midi)]}${octave}`;
+}
+
+// src/frequency.ts
+function midiToFrequency(midi) {
+  return 440 * Math.pow(2, (midi - 69) / 12);
+}
+
+// src/enharmonic.ts
+var KEYS_PREFER_FLATS = ["F", "Bb", "Eb", "Ab", "Db", "Gb"];
+function useFlatsForKeyName(key) {
+  return KEYS_PREFER_FLATS.includes(key);
+}
+function useFlatsForKeyFifths(fifths) {
+  return fifths < 0;
+}
+
+// src/scales.ts
+var MAJOR_SCALE_INTERVALS = [0, 2, 4, 5, 7, 9, 11];
+var ALL_KEYS = ["C", "G", "D", "A", "E", "B", "F#", "F", "Bb", "Eb", "Ab", "Db"];
+function getMidiNote(degree, key, octave = 4) {
+  const rootIndex = noteNameToIndex(key);
+  const actualDegree = ((degree - 1) % 7 + 7) % 7;
+  const octaveShift = Math.floor((degree - 1) / 7);
+  const semitones = MAJOR_SCALE_INTERVALS[actualDegree];
+  return rootIndex + semitones + (octave + octaveShift) * 12;
+}
+function getScaleDegree(midiNote, key) {
+  const rootIndex = noteNameToIndex(key);
+  const noteInOctave = (midiNote % 12 - rootIndex + 12) % 12;
+  const degreeIndex = MAJOR_SCALE_INTERVALS.indexOf(noteInOctave);
+  return degreeIndex !== -1 ? degreeIndex + 1 : null;
+}
+function isInScale(midiNote, key) {
+  return getScaleDegree(midiNote, key) !== null;
+}
+function getStability(degree) {
+  if ([1, 3, 5].includes(degree)) return "stable";
+  if ([2, 4, 6].includes(degree)) return "lessStable";
+  if (degree === 7) return "unstable";
+  return null;
+}
+
+// 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/chords.ts
+var CHORD_TEMPLATES = [
+  { name: "maj7", intervals: [0, 4, 7, 11] },
+  { name: "7", intervals: [0, 4, 7, 10] },
+  { name: "m7", intervals: [0, 3, 7, 10] },
+  { name: "dim7", intervals: [0, 3, 6, 9] },
+  { name: "m7b5", intervals: [0, 3, 6, 10] },
+  { name: "", intervals: [0, 4, 7] },
+  { name: "m", intervals: [0, 3, 7] },
+  { name: "dim", intervals: [0, 3, 6] },
+  { name: "aug", intervals: [0, 4, 8] },
+  { name: "sus4", intervals: [0, 5, 7] },
+  { name: "sus2", intervals: [0, 2, 7] }
+];
+export {
+  ALL_KEYS,
+  CHORD_TEMPLATES,
+  INTERVALS,
+  KEYS_PREFER_FLATS,
+  MAJOR_SCALE_INTERVALS,
+  NOTE_NAMES,
+  NOTE_NAMES_FLAT,
+  getMidiNote,
+  getScaleDegree,
+  getStability,
+  intervalBySemitones,
+  isInScale,
+  midiToFrequency,
+  midiToNoteName,
+  noteNameToIndex,
+  pitchClass,
+  useFlatsForKeyFifths,
+  useFlatsForKeyName
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/notes.ts","../src/frequency.ts","../src/enharmonic.ts","../src/scales.ts","../src/intervals.ts","../src/chords.ts"],"sourcesContent":["export const NOTE_NAMES = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'] as const;\nexport const NOTE_NAMES_FLAT = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B'] as const;\n\nconst LETTER_TO_INDEX: Record<string, number> = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };\n\n/** Note name (e.g. \"C\", \"C#\", \"Db\", \"Cb\") → pitch class 0..11. */\nexport function noteNameToIndex(note: string): number {\n  const letter = note[0]?.toUpperCase();\n  let index = LETTER_TO_INDEX[letter];\n  if (index === undefined) throw new Error(`Invalid note name: ${note}`);\n  for (const ch of note.slice(1)) {\n    if (ch === '#') index += 1;\n    else if (ch === 'b') index -= 1;\n  }\n  return ((index % 12) + 12) % 12;\n}\n\n/** MIDI number → pitch class 0..11. */\nexport function pitchClass(midi: number): number {\n  return ((midi % 12) + 12) % 12;\n}\n\n/** MIDI → note name with octave, e.g. 61 → \"C#4\" (or \"Db4\" with useFlats). */\nexport function midiToNoteName(midi: number, useFlats = false): string {\n  const names = useFlats ? NOTE_NAMES_FLAT : NOTE_NAMES;\n  const octave = Math.floor(midi / 12) - 1;\n  return `${names[pitchClass(midi)]}${octave}`;\n}\n","/** 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","/** Keys conventionally spelled with flats (RET's key-name model). */\nexport const KEYS_PREFER_FLATS = ['F', 'Bb', 'Eb', 'Ab', 'Db', 'Gb'] as const;\n\n/** Whether to use flat spellings for a key given by name (e.g. \"Eb\"). */\nexport function useFlatsForKeyName(key: string): boolean {\n  return (KEYS_PREFER_FLATS as readonly string[]).includes(key);\n}\n\n/**\n * Whether to use flat spellings for a key given by its key-signature \"fifths\"\n * value (Stave's model: -7..+7, negative = flat keys). 0 (C) and positive\n * (sharp keys) use sharps.\n */\nexport function useFlatsForKeyFifths(fifths: number): boolean {\n  return fifths < 0;\n}\n","import { noteNameToIndex } from './notes';\n\nexport const MAJOR_SCALE_INTERVALS = [0, 2, 4, 5, 7, 9, 11] as const;\nexport const ALL_KEYS = ['C', 'G', 'D', 'A', 'E', 'B', 'F#', 'F', 'Bb', 'Eb', 'Ab', 'Db'] as const;\n\n/**\n * Get MIDI note number for a scale degree in a given key.\n * Ported verbatim from RET src/lib/audio/scales.ts.\n * NOTE: RET uses octave*12 (not (octave+1)*12), so getMidiNote(1,'C',4)=48,\n * not 60. This is RET's established convention — consumers must account for it.\n */\nexport function getMidiNote(degree: number, key: string, octave = 4): number {\n  const rootIndex = noteNameToIndex(key);\n  const actualDegree = ((degree - 1) % 7 + 7) % 7;\n  const octaveShift = Math.floor((degree - 1) / 7);\n  const semitones = MAJOR_SCALE_INTERVALS[actualDegree];\n  return rootIndex + semitones + ((octave + octaveShift) * 12);\n}\n\n/**\n * Get the scale degree (1-7) for a MIDI note in a key, or null if not in scale.\n * Ported verbatim from RET src/lib/audio/scales.ts.\n */\nexport function getScaleDegree(midiNote: number, key: string): number | null {\n  const rootIndex = noteNameToIndex(key);\n  const noteInOctave = ((midiNote % 12) - rootIndex + 12) % 12;\n  const degreeIndex = (MAJOR_SCALE_INTERVALS as readonly number[]).indexOf(noteInOctave);\n  return degreeIndex !== -1 ? degreeIndex + 1 : null;\n}\n\n/**\n * Check if a MIDI note is in the given key.\n */\nexport function isInScale(midiNote: number, key: string): boolean {\n  return getScaleDegree(midiNote, key) !== null;\n}\n\n/**\n * Get stability category for a scale degree.\n * Ported verbatim from RET src/lib/audio/scales.ts.\n */\nexport function getStability(degree: number): 'stable' | 'lessStable' | 'unstable' | null {\n  if ([1, 3, 5].includes(degree)) return 'stable';\n  if ([2, 4, 6].includes(degree)) return 'lessStable';\n  if (degree === 7) return 'unstable';\n  return null;\n}\n","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","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":"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","names":[]}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@real-music-packages/web-core",
+  "version": "0.1.0",
+  "description": "Shared music-theory + audio primitives for the music-suite web apps",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./audio": { "types": "./dist/audio.d.ts", "import": "./dist/audio.js" }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": { "type": "git", "url": "git+https://github.com/e7mac/web-core.git" },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}