@greenblacksky/honmoon 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GreenBlackSky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# Honmoon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The engine behind three apps: **Mira** (bass), **Rumi** (voice) and **Zoey**
+(theory) — the music model, spaced repetition, audio, notation drawing, and
+the screens the apps share. The names are a nod to HUNTR/X from *KPop Demon
+Hunters*: three members, and the Honmoon that all three of them hold up.
+It is a library, not an app — you never open it on its own.
+
+It started life as Fretboard Fluency (one 6,000-line HTML file) and was
+carried over to TypeScript and Svelte.
+
+## What's where
+
+```
+src/lib/
+  music/      notes and spelling, scales and their fingerings, clefs, intervals,
+              rhythm, voice warm-up data, bass warm-up exercise generators
+  notation/   drawing as SVG: staff, fretboard, keyboard, rhythm, tab, glyphs
+  audio/      the synth voices, metronome, rhythm playback, mic pitch detection
+  store/      what is remembered (types, saving, Firebase placeholder)
+  learn/      card pools, sampling, sessions, progress summaries
+  drills/     the 39 drills: definitions, question makers, answering, verdicts
+  ui/         Svelte components: the app shell, fretboard/keyboard/staff widgets,
+              and the shared screens (Practice, Drill, Stats, Setup, references…)
+  styles/     honmoon.css — the one stylesheet all three apps use, and the
+              palette: a shared night base, fixed progress colours
+              (--good / --mid / --bad) and an accent each app sets itself
+  nav.svelte.ts   which screen is showing, and go('name') to change it
+  index.ts        everything the apps import
+tests/                *.test.ts files, run by Vitest (none yet)
+```
+
+## Working on it
+
+Honmoon lives in `apps/huntrix/` next to the three apps, and is installed
+together with them: run `npm install` once in the `apps` folder (see
+`apps/README.md`). Then, in this folder:
+
+```
+npm test           the tests in tests/ (passes when there are none)
+npm run check      TypeScript and Svelte type checking
+npm run lint       code problems (ESLint); lint:fix repairs what it can
+npm run format     tidy the layout of every file (Prettier)
+```
+
+## How the apps get it
+
+The workspace links
+`@greenblacksky/honmoon` in its `node_modules` straight to this folder, and
+`package.json` points the apps at the TypeScript and Svelte source in
+`src/lib` — so there is nothing to build or release: save a file here and
+every running app reloads with the change.
+
+The version number still matters. Each app asks for a range
+(`"@greenblacksky/honmoon": "^0.4.0"`), and the workspace only links this folder
+when its version fits. For a change the apps must adapt to, bump it
+(`npm version minor`), update the range in each app, and once the repos
+are on GitHub tag the commit, so you can always tell which engine an app
+was tested with.
+
+Building an app outside the workspace (for example, automatic
+builds on GitHub) needs Honmoon published to a package registry. How to do
+that (publicly on npmjs.com, or privately on GitHub Packages), and the GitHub Actions pipeline for
+the apps, is in [docs/PUBLISHING.md](docs/PUBLISHING.md).
+
+## Tests
+
+The parity tests that checked the port against the original app were
+removed once the migration was done. New tests go in `tests/` as
+`something.test.ts` and run with `npm test`.
+
+## Saving and Firebase
+
+Progress is saved in the browser (`localStorage`, one key per app). The
+format is the original app's, so a file exported from either can be imported
+into the other. `src/lib/store/sync.ts` holds `FirebaseSync`, a placeholder
+with the shape the real thing will have; the plan for it is written at the
+top of that file.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@greenblacksky/honmoon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Honmoon: the engine under Mira, Rumi and Zoey — the music model, spaced repetition, audio, notation drawing and the shared Svelte screens.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GreenBlackSky/honmoon.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "svelte": "./src/lib/index.ts",
+  "types": "./src/lib/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/lib/index.ts",
+      "svelte": "./src/lib/index.ts",
+      "default": "./src/lib/index.ts"
+    },
+    "./styles.css": "./src/lib/styles/honmoon.css"
+  },
+  "files": [
+    "src/lib"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "package": "svelte-package -i src/lib -o dist",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix ."
+  },
+  "peerDependencies": {
+    "svelte": "^5.57.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@sveltejs/package": "3.0.1",
+    "@sveltejs/vite-plugin-svelte": "7.3.1",
+    "@types/node": "^22.20.5",
+    "eslint": "10.13.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-svelte": "3.23.1",
+    "globals": "17.13.0",
+    "prettier": "3.9.10",
+    "prettier-plugin-svelte": "4.1.1",
+    "svelte": "5.57.2",
+    "svelte-check": "4.7.7",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.72.0",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
+}

package/src/lib/audio/context.ts

@@ -0,0 +1,29 @@
+/* One AudioContext for the whole app, created on first use — browsers only
+   allow sound after a user gesture, and every first use here is one. */
+let context: AudioContext | null = null;
+
+export function ac(): AudioContext | null {
+  if (!context) {
+    try {
+      const AudioContextClass =
+        window.AudioContext ||
+        (window as unknown as { webkitAudioContext: typeof AudioContext }).webkitAudioContext;
+      context = new AudioContextClass();
+    } catch {
+      context = null;
+    }
+  }
+  if (context && context.state === 'suspended') {
+    context.resume();
+  }
+  return context;
+}
+/** The context if it already exists, without creating one. */
+export function acIfAny(): AudioContext | null {
+  return context;
+}
+
+/** While the app itself is making sound, the pitch detector would hear it and
+    grade it as your playing. Every sound pushes this out to when it will have
+    died away, and the detector ignores everything before then. */
+export const audioGate = { muteUntil: 0 };

package/src/lib/audio/metronome.svelte.ts

@@ -0,0 +1,146 @@
+import { ac, acIfAny } from './context';
+import { metClick } from './synth';
+
+/* ---------------- metronome ----------------
+   Timers drift; the audio clock does not. A short polling loop schedules
+   clicks a fraction of a second ahead on the Web Audio timeline, so the beats
+   are placed by the sound hardware rather than by JavaScript. The reactive
+   fields drive the screen; the rest is bookkeeping. */
+export const met = $state({
+  on: false,
+  bpm: 72,
+  beats: 4,
+  sub: 1,
+  subClick: false,
+  /** the beat light: '' off, 'hit' on a beat, 'hit one' on the downbeat */
+  flash: '',
+  /** "2 / 4" while running */
+  beatLabel: '—',
+});
+
+/** How far ahead clicks are put on the audio clock, and how often the
+    scheduler looks. */
+const LOOKAHEAD_S = 0.14;
+const SCHEDULER_INTERVAL_MS = 25;
+const FLASH_MS = 90;
+export const BPM_MIN = 40;
+export const BPM_MAX = 200;
+/** Tap tempo: taps older than this are forgotten, and an average gap outside
+    250–1600 ms (240 down to about 38 bpm) is not taken as a beat. */
+const TAP_MEMORY_MS = 2500;
+const TAP_GAP_MIN_MS = 250;
+const TAP_GAP_MAX_MS = 1600;
+
+let timer: ReturnType<typeof setInterval> | null = null;
+/** Clicks scheduled so far (subdivisions included), and when the next falls. */
+let tick = 0;
+let nextClickTime = 0;
+/** Beats scheduled but not yet shown on the beat light. */
+let queue: { t: number; beat: number }[] = [];
+let taps: number[] = [];
+
+function schedule(): void {
+  const ctx = acIfAny();
+  if (!ctx || !met.on) {
+    return;
+  }
+  const horizon = ctx.currentTime + LOOKAHEAD_S;
+  while (nextClickTime < horizon) {
+    const onBeat = tick % met.sub === 0;
+    const beat = Math.floor(tick / met.sub) % met.beats;
+    if (onBeat || met.subClick) {
+      let kind: 'accent' | 'beat' | 'sub' = 'sub';
+      if (onBeat) {
+        kind = beat === 0 ? 'accent' : 'beat';
+      }
+      metClick(nextClickTime, kind);
+    }
+    if (onBeat) {
+      queue.push({ t: nextClickTime, beat });
+    }
+    tick++;
+    nextClickTime += 60 / met.bpm / met.sub;
+  }
+}
+/** Each animation frame: light up any beat whose click has now sounded. */
+function pulse(): void {
+  if (!met.on) {
+    return;
+  }
+  requestAnimationFrame(pulse);
+  const ctx = acIfAny();
+  if (!ctx) {
+    return;
+  }
+  while (queue.length && queue[0].t <= ctx.currentTime) {
+    const due = queue.shift()!;
+    met.flash = 'hit' + (due.beat === 0 ? ' one' : '');
+    setTimeout(() => {
+      met.flash = '';
+    }, FLASH_MS);
+    met.beatLabel = due.beat + 1 + ' / ' + met.beats;
+  }
+}
+
+export function metStart(): void {
+  const ctx = ac();
+  if (!ctx || met.on) {
+    return;
+  }
+  met.on = true;
+  tick = 0;
+  queue = [];
+  nextClickTime = ctx.currentTime + 0.12;
+  met.beatLabel = '1 / ' + met.beats;
+  schedule();
+  timer = setInterval(schedule, SCHEDULER_INTERVAL_MS);
+  pulse();
+}
+export function metStop(): void {
+  met.on = false;
+  if (timer) {
+    clearInterval(timer);
+  }
+  timer = null;
+  queue = [];
+  met.flash = '';
+  met.beatLabel = '—';
+}
+export function metToggle(): void {
+  if (met.on) {
+    metStop();
+  } else {
+    metStart();
+  }
+}
+export function metSetBpm(bpm: number): void {
+  met.bpm = Math.max(BPM_MIN, Math.min(BPM_MAX, Math.round(bpm)));
+  const ctx = acIfAny();
+  if (met.on && ctx) {
+    /* re-anchor so the change takes effect on the next beat, not retroactively */
+    nextClickTime = Math.max(ctx.currentTime + 0.06, nextClickTime);
+  }
+}
+/** Change the subdivision; a running metronome restarts its count cleanly. */
+export function metSetSub(perBeat: number): void {
+  met.sub = perBeat;
+  const ctx = acIfAny();
+  if (met.on && ctx) {
+    tick = 0;
+    nextClickTime = Math.max(ctx.currentTime + 0.08, nextClickTime);
+  }
+}
+/** Tap tempo: three taps or more set the tempo to their average spacing. */
+export function metTap(): void {
+  const now = Date.now();
+  taps = taps.filter((time) => now - time < TAP_MEMORY_MS);
+  taps.push(now);
+  if (taps.length < 3) {
+    return;
+  }
+  const gaps = taps.slice(1).map((time, i) => time - taps[i]);
+  const averageGap = gaps.reduce((sum, gap) => sum + gap, 0) / gaps.length;
+  if (averageGap > TAP_GAP_MIN_MS && averageGap < TAP_GAP_MAX_MS) {
+    metSetBpm(60000 / averageGap);
+  }
+}

package/src/lib/audio/mic.ts

@@ -0,0 +1,254 @@
+import { ac, acIfAny, audioGate } from './context';
+import { decimate, nsdfPitch } from './pitch';
+
+/** What the listener reports on every animation frame while the mic is on. */
+export interface MicReading {
+  rms: number;
+  /** the app's own sound was playing, so nothing was measured */
+  muted?: boolean;
+  freq?: number;
+  /** median of the last few frames, as a fractional MIDI number */
+  midi?: number;
+  clarity?: number;
+  /** the last three frames agree to within 40 cents */
+  stable?: boolean;
+}
+
+const mic = {
+  on: false,
+  stream: null as MediaStream | null,
+  an: null as AnalyserNode | null,
+  buf: null as Float32Array | null,
+  raf: 0,
+  floor: 0.004,
+  cb: null as ((r: MicReading) => void) | null,
+  hist: [] as number[],
+};
+
+export function micOn(): boolean {
+  return mic.on;
+}
+/** Who hears the readings. One listener at a time: the drill or the Setup check. */
+export function micListen(cb: ((r: MicReading) => void) | null): void {
+  mic.cb = cb;
+}
+
+/* A microphone can fail in five quite different ways and they need five
+   different answers. In particular: inside an embedded frame the browser
+   refuses WITHOUT ever showing a prompt, which looks exactly like a dead
+   button, and no site setting can override it. */
+export interface MicEnv {
+  secure: boolean;
+  api: boolean;
+  framed: boolean;
+  policy: boolean | null;
+}
+export function micEnv(): MicEnv {
+  const doc = document as unknown as {
+    featurePolicy?: { allowsFeature(feature: string): boolean };
+    permissionsPolicy?: { allowsFeature(feature: string): boolean };
+  };
+  const policy = doc.featurePolicy || doc.permissionsPolicy || null;
+  let allowedByPolicy: boolean | null = null;
+  let framed: boolean;
+  try {
+    if (policy && policy.allowsFeature) {
+      allowedByPolicy = policy.allowsFeature('microphone');
+    }
+  } catch {
+    allowedByPolicy = null;
+  }
+  try {
+    framed = window.top !== window.self;
+  } catch {
+    framed = true;
+  }
+  return {
+    secure: !!window.isSecureContext,
+    api: !!(navigator.mediaDevices && navigator.mediaDevices.getUserMedia),
+    framed,
+    policy: allowedByPolicy,
+  };
+}
+export function micUsable(): boolean {
+  const env = micEnv();
+  return env.api && env.secure && env.policy !== false;
+}
+export interface MicReason {
+  t: string;
+  m: string;
+  tab: boolean;
+}
+export function micReason(err: unknown): MicReason {
+  const env = micEnv();
+  const errorName = (err && (err as { name?: string }).name) || '';
+  if (!env.api || !env.secure) {
+    return {
+      t: 'No microphone API here',
+      m: 'This page cannot reach a microphone at all — the connection is not secure, or the browser exposes no capture API in this context.',
+      tab: false,
+    };
+  }
+  if (env.policy === false) {
+    return {
+      t: 'No microphone in this viewer',
+      m: 'The page this app runs inside does not pass microphone access through to it, so the prompt never appears and no browser setting can override it. Nothing here can change that — the play-along drills fall back to marking yourself, and everything else is unaffected.',
+      tab: false,
+    };
+  }
+  if (errorName === 'NotAllowedError' || errorName === 'SecurityError') {
+    return env.framed
+      ? {
+          t: 'Refused without asking',
+          m: 'The browser said no without showing a prompt, which almost always means the embedding page is not passing microphone access through to this frame. Try opening the app in its own browser tab.',
+          tab: true,
+        }
+      : {
+          t: 'Permission refused',
+          m: 'Tap the padlock or camera icon in the address bar, set Microphone to Allow, then press Start listening again.',
+          tab: false,
+        };
+  }
+  if (errorName === 'NotFoundError' || errorName === 'OverconstrainedError') {
+    return {
+      t: 'No microphone found',
+      m: 'The browser reports no capture device on this machine.',
+      tab: false,
+    };
+  }
+  if (errorName === 'NotReadableError' || errorName === 'AbortError') {
+    return {
+      t: 'Microphone is busy',
+      m: 'Another app is holding it. Close that app and try again.',
+      tab: false,
+    };
+  }
+  return {
+    t: 'Could not start the microphone',
+    m:
+      (errorName || 'unknown error') +
+      '. Everything except the play-along drills works without it.',
+    tab: env.framed,
+  };
+}
+
+/** Band kept from the microphone: rumble below a bass's low B goes, and so
+    does everything above the pitches the detector looks for. */
+const HIGHPASS_HZ = 32;
+const LOWPASS_HZ = 1400;
+/** Samples per analysis frame. */
+const FRAME_SIZE = 8192;
+/** Pitch detection runs on the signal decimated to about this rate. */
+const ANALYSIS_RATE = 12000;
+/** Readings kept for the median, and how close (in semitones) the last two
+    must be to it to count as a stable note. */
+const HISTORY_LENGTH = 5;
+const STABLE_WITHIN = 0.4;
+
+export function micStart(): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (mic.on) {
+      return resolve();
+    }
+    const ctx = ac();
+    if (!ctx) {
+      return reject(new Error('no-audio'));
+    }
+    if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
+      return reject(new Error('no-mic'));
+    }
+    navigator.mediaDevices
+      .getUserMedia({
+        // raw signal: the browser's voice-call processing would distort pitch
+        audio: { echoCancellation: false, noiseSuppression: false, autoGainControl: false },
+      })
+      .then((stream) => {
+        mic.stream = stream;
+        const source = ctx.createMediaStreamSource(stream);
+        const highpass = ctx.createBiquadFilter();
+        highpass.type = 'highpass';
+        highpass.frequency.value = HIGHPASS_HZ;
+        highpass.Q.value = 0.7;
+        const lowpass = ctx.createBiquadFilter();
+        lowpass.type = 'lowpass';
+        lowpass.frequency.value = LOWPASS_HZ;
+        lowpass.Q.value = 0.7;
+        const analyser = ctx.createAnalyser();
+        analyser.fftSize = FRAME_SIZE;
+        analyser.smoothingTimeConstant = 0;
+        source.connect(highpass);
+        highpass.connect(lowpass);
+        lowpass.connect(analyser);
+        mic.an = analyser;
+        mic.buf = new Float32Array(analyser.fftSize);
+        mic.on = true;
+        mic.hist = [];
+        loop();
+        resolve();
+      })
+      .catch(reject);
+  });
+}
+export function micStop(): void {
+  if (mic.raf) {
+    cancelAnimationFrame(mic.raf);
+  }
+  mic.raf = 0;
+  if (mic.stream) {
+    mic.stream.getTracks().forEach((track) => track.stop());
+  }
+  mic.stream = null;
+  mic.on = false;
+  mic.cb = null;
+}
+
+function rootMeanSquare(samples: Float32Array): number {
+  let sum = 0;
+  for (let i = 0; i < samples.length; i++) {
+    sum += samples[i] * samples[i];
+  }
+  return Math.sqrt(sum / samples.length);
+}
+/** Frequency to a fractional MIDI number (A4 = 440 Hz = 69). */
+function midiOfFrequency(freq: number): number {
+  return 69 + 12 * Math.log2(freq / 440);
+}
+/** Each animation frame: measure, then report to whoever is listening. */
+function loop(): void {
+  mic.raf = requestAnimationFrame(loop);
+  const ctx = acIfAny();
+  if (!mic.an || !mic.cb || !mic.buf || !ctx) {
+    return;
+  }
+  mic.an.getFloatTimeDomainData(mic.buf as Float32Array<ArrayBuffer>);
+  const rms = rootMeanSquare(mic.buf);
+  if (Date.now() < audioGate.muteUntil) {
+    mic.cb({ rms, muted: true });
+    return;
+  }
+  if (rms < mic.floor) {
+    mic.hist.length = 0;
+    mic.cb({ rms });
+    return;
+  }
+  const factor = Math.max(1, Math.round(ctx.sampleRate / ANALYSIS_RATE));
+  const pitch = nsdfPitch(decimate(mic.buf, factor), ctx.sampleRate / factor);
+  if (!pitch) {
+    mic.cb({ rms });
+    return;
+  }
+  const history = mic.hist;
+  history.push(midiOfFrequency(pitch.f));
+  if (history.length > HISTORY_LENGTH) {
+    history.shift();
+  }
+  const sorted = history.slice().sort((a, b) => a - b);
+  const median = sorted[Math.floor(sorted.length / 2)];
+  const last = history[history.length - 1];
+  const beforeLast = history[history.length - 2];
+  const stable =
+    history.length >= 3 &&
+    Math.abs(last - median) < STABLE_WITHIN &&
+    Math.abs(beforeLast - median) < STABLE_WITHIN;
+  mic.cb({ rms, freq: pitch.f, midi: median, clarity: pitch.clarity, stable });
+}