@greenblacksky/honmoon 0.0.0-stage → 0.4.0

package/src/lib/notation/tab.ts

@@ -0,0 +1,80 @@
+import { STRINGS } from '../music/bass';
+import { esc } from '../util/text';
+
+/** One note of a tabbed exercise: string, fret, left-hand finger, right-hand
+    finger, and an optional label marking the start of a section. */
+export interface TabStep {
+  s: number;
+  f: number;
+  fin?: number;
+  rh?: string;
+  bar?: string | null;
+}
+
+const FIRST_X = 34;
+const STEP_WIDTH = 26;
+/** y of each string's line, G (top) to E. */
+const STRING_ROWS = [14, 34, 54, 74];
+/** Rows for the left-hand (finger) and right-hand (i/m) lines under the tab. */
+const LH_ROW_Y = 98;
+const RH_ROW_Y = 114;
+const MONO = 'IBM Plex Mono,monospace';
+const DISPLAY = 'Saira Condensed,sans-serif';
+
+function tabStrings(width: number): string {
+  let out = '';
+  STRING_ROWS.forEach((y, string) => {
+    out += `<line x1="${FIRST_X - 8}" y1="${y}" x2="${width - 8}" y2="${y}" stroke="var(--line-2)" stroke-width="1.2"/>`;
+    out += `<text x="${FIRST_X - 14}" y="${y + 4.5}" text-anchor="end" font-size="12" font-family="${MONO}" font-weight="600" fill="var(--ink-3)">${STRINGS[string].n}</text>`;
+  });
+  return out;
+}
+/** A section line and its name, at the left edge of a step. */
+function sectionMark(left: number, name: string): string {
+  return (
+    `<line x1="${left}" y1="8" x2="${left}" y2="80" stroke="var(--ink-3)" stroke-width="1.4"/>` +
+    `<text x="${left + 4}" y="4" font-size="10.5" font-family="${DISPLAY}" letter-spacing="1" fill="var(--accent)">${esc(name).toUpperCase()}</text>`
+  );
+}
+/** A fret number on its string, on a patch of background so the line breaks. */
+function fretNumber(x: number, y: number, fret: number): string {
+  return (
+    `<rect x="${x - 9}" y="${y - 7}" width="18" height="14" fill="var(--surface)"/>` +
+    `<text x="${x}" y="${y + 4.5}" text-anchor="middle" font-size="13" font-weight="600" font-family="${MONO}" fill="var(--ink)">${fret}</text>`
+  );
+}
+function smallText(x: number, y: number, fill: string, text: string | number): string {
+  return `<text x="${x}" y="${y}" text-anchor="middle" font-size="11.5" font-family="${MONO}" fill="${fill}">${text}</text>`;
+}
+function rowName(y: number, name: string): string {
+  return `<text x="${FIRST_X - 14}" y="${y}" text-anchor="end" font-size="10" font-family="${DISPLAY}" fill="var(--ink-3)">${name}</text>`;
+}
+
+export function tabSVG(steps: TabStep[]): string {
+  const width = FIRST_X + steps.length * STEP_WIDTH + 12;
+  const hasRightHand = steps.some((step) => !!step.rh);
+  const height = hasRightHand ? 132 : 116;
+  const parts = [tabStrings(width)];
+  steps.forEach((step, k) => {
+    const x = FIRST_X + k * STEP_WIDTH + STEP_WIDTH / 2;
+    if (step.bar) {
+      parts.push(sectionMark(x - STEP_WIDTH / 2, step.bar));
+    }
+    parts.push(fretNumber(x, STRING_ROWS[step.s], step.f));
+    if (step.fin) {
+      parts.push(smallText(x, LH_ROW_Y, 'var(--accent)', step.fin));
+    }
+    if (step.rh) {
+      parts.push(smallText(x, hasRightHand ? RH_ROW_Y : LH_ROW_Y, 'var(--ink-3)', step.rh));
+    }
+  });
+  parts.push(rowName(LH_ROW_Y, 'LH'));
+  if (hasRightHand) {
+    parts.push(rowName(RH_ROW_Y, 'RH'));
+  }
+  return (
+    `<svg viewBox="0 -8 ${width} ${height}" width="${width}" height="${height}" role="img" aria-label="tab">` +
+    parts.join('') +
+    '</svg>'
+  );
+}

package/src/lib/store/honmoon.svelte.ts

@@ -0,0 +1,329 @@
+import type { Card, HonmoonState, Payload, Settings } from './types';
+import { todayKey } from '../util/text';
+import type { SyncAdapter } from './sync';
+
+export const DEF: Settings = {
+  pref: 'sharp',
+  level: 'l1',
+  acc: false,
+  bass: true,
+  mic: true,
+  sound: true,
+  labels: true,
+  slen: 30,
+  off: [],
+  woff: [],
+  wlen: 3,
+  sen: null,
+  sroots: 'nat',
+  sstart: 'both',
+  sslen: 20,
+  sdoff: [],
+  wmode: 'bass',
+  vlo: null,
+  vhi: null,
+  voff: null,
+  vtempo: 76,
+  vgap: true,
+  ivset: 'basic',
+  clefs: ['bass'],
+  mdo: false,
+  rlev: 'r1',
+  rtempo: 72,
+  rfloor: 50,
+  rlat: 0,
+  theme: 'auto',
+  hints: true,
+  doff: [],
+};
+
+/** Everything the app knows about you. Reactive: any screen reading from it
+    redraws by itself when it changes. */
+export const honmoon: HonmoonState = $state({
+  cards: {},
+  daily: {},
+  tempo: {},
+  settings: { ...DEF, off: [], woff: [], sdoff: [], doff: [], clefs: ['bass'] },
+  answers: 0,
+});
+
+/* ---------------- configuration ----------------
+   Each app keeps its own copy of everything under its own key, and tells the
+   store how to tidy a payload it loads (an old save may name drills or
+   families that no longer exist). */
+interface StoreConfig {
+  key: string;
+  normalize: ((s: Settings) => void)[];
+  sync: SyncAdapter | null;
+}
+const cfg: StoreConfig = { key: 'honmoon.v1', normalize: [], sync: null };
+
+export function configureStore(options: { key: string; sync?: SyncAdapter | null }): void {
+  cfg.key = options.key;
+  cfg.sync = options.sync ?? null;
+}
+/** Register a tidy-up step applied to settings whenever a payload is adopted. */
+export function addNormalizer(normalize: (settings: Settings) => void): void {
+  cfg.normalize.push(normalize);
+}
+function runNormalizers(settings: Settings): void {
+  for (const normalize of cfg.normalize) {
+    normalize(settings);
+  }
+}
+
+/* ---------------- cards ----------------
+   A card's mastery climbs one step for each right answer and falls two for
+   each wrong one, between 0 (new or shaky) and 5 (solid). */
+const MAX_MASTERY = 5;
+const MASTERY_UP = 1;
+const MASTERY_DOWN = 2;
+/** Time spent on one answer counts for at most a minute (a phone left on). */
+const MAX_ANSWER_MS = 60000;
+
+export function card(id: string): Card {
+  if (!honmoon.cards[id]) {
+    honmoon.cards[id] = { s: 0, c: 0, t: 0, k: 0 };
+  }
+  return honmoon.cards[id];
+}
+export function mastery(id: string): number {
+  const existing = honmoon.cards[id];
+  if (!existing || !existing.s) {
+    return 0;
+  }
+  return Math.max(0, Math.min(MAX_MASTERY, existing.k));
+}
+/** Count one answer to a card: its counts and mastery, and today's log. */
+export function record(id: string, ok: boolean, ms: number): void {
+  const answered = card(id);
+  answered.s++;
+  if (ok) {
+    answered.c++;
+    answered.k = Math.min(MAX_MASTERY, (answered.k || 0) + MASTERY_UP);
+  } else {
+    answered.k = Math.max(0, (answered.k || 0) - MASTERY_DOWN);
+  }
+  answered.t = Date.now();
+  const dayKey = todayKey();
+  const today = honmoon.daily[dayKey] || { n: 0, c: 0, ms: 0 };
+  today.n++;
+  if (ok) {
+    today.c++;
+  }
+  today.ms += Math.min(ms || 0, MAX_ANSWER_MS);
+  honmoon.daily[dayKey] = today;
+  honmoon.answers++;
+  queueSave();
+}
+
+/* ---------------- saving ---------------- */
+let dirty = false;
+let saveTimer: ReturnType<typeof setTimeout> | null = null;
+let synced = false;
+/** Progress is written a few seconds after the last change, not on every answer. */
+const SAVE_DELAY_MS = 3500;
+
+export function queueSave(): void {
+  dirty = true;
+  if (saveTimer) {
+    return;
+  }
+  saveTimer = setTimeout(() => {
+    saveTimer = null;
+    save();
+  }, SAVE_DELAY_MS);
+}
+
+export function payload(): Payload {
+  const snapshot = $state.snapshot(honmoon);
+  return {
+    v: 1,
+    t: Date.now(),
+    cards: snapshot.cards,
+    daily: snapshot.daily,
+    tempo: snapshot.tempo,
+    settings: snapshot.settings,
+  };
+}
+
+function writeLocal(): void {
+  try {
+    localStorage.setItem(cfg.key, JSON.stringify(payload()));
+  } catch {
+    /* private mode, quota: progress stays in memory */
+  }
+}
+
+/** Settings are written through at once: they are tiny, and a preference that
+    vanishes because the page was closed within the save delay is maddening.
+    Progress still goes through the debounce. */
+export function saveLocal(): void {
+  writeLocal();
+}
+
+export function save(): void {
+  if (!dirty) {
+    return;
+  }
+  dirty = false;
+  writeLocal();
+  if (cfg.sync && synced) {
+    cfg.sync.save(payload()).catch(() => {});
+  }
+}
+
+/** Change one setting, write it through, and schedule a sync. */
+export function setSetting<K extends keyof Settings>(key: K, value: Settings[K]): void {
+  honmoon.settings[key] = value;
+  saveLocal();
+  queueSave();
+}
+
+/** A label for the Stats screen. */
+export function syncLabel(): string {
+  return cfg.sync && synced ? 'Synced across your devices' : 'Saved in this browser only';
+}
+
+/* ---------------- loading ---------------- */
+/** Total answers recorded in a set of cards. */
+function answersIn(cards: Record<string, Card> | undefined): number {
+  let total = 0;
+  for (const id in cards || {}) {
+    total += cards![id].s || 0;
+  }
+  return total;
+}
+function progressOf(saved: Partial<Payload> | null): number {
+  if (!saved || typeof saved !== 'object') {
+    return 0;
+  }
+  return answersIn(saved.cards);
+}
+/** Snapshots from a store may be frozen, so nothing read from one goes into
+    honmoon directly — the first c.s++ would throw. Copy before adopting. */
+function thaw<T>(value: T): T | null {
+  try {
+    return value ? JSON.parse(JSON.stringify(value)) : null;
+  } catch {
+    return null;
+  }
+}
+/** Bring settings from an older save up to date. */
+function upgradeSettings(settings: Settings): void {
+  /* An old save may name a level that no longer exists. "All 12 notes" was the
+     full neck plus the black notes, so it becomes exactly that. */
+  if ((settings.level as string) === 'l3') {
+    settings.level = 'l2';
+    settings.acc = true;
+  }
+  if (!['l0', 'l1', 'l2'].includes(settings.level)) {
+    settings.level = 'l1';
+  }
+  /* an older save has no clef list; bass is where everyone starts */
+  if (!Array.isArray(settings.clefs) || !settings.clefs.length) {
+    settings.clefs = ['bass'];
+  }
+  if (!Array.isArray(settings.doff)) {
+    settings.doff = [];
+  }
+}
+
+/** Adopt a saved payload as the current state. */
+export function apply(saved: Partial<Payload> | null, keepSettings?: boolean): void {
+  if (!saved) {
+    return;
+  }
+  honmoon.cards = thaw(saved.cards) || {};
+  honmoon.daily = thaw(saved.daily) || {};
+  honmoon.tempo = thaw(saved.tempo) || {};
+  if (!keepSettings) {
+    honmoon.settings = Object.assign({}, structuredClone(DEF), thaw(saved.settings) || {});
+  }
+  upgradeSettings(honmoon.settings);
+  runNormalizers(honmoon.settings);
+  honmoon.answers = answersIn(honmoon.cards);
+}
+
+/** Read what this browser has, then — if a sync service is configured — take
+    progress from wherever there is more of it, and settings from whichever
+    copy was written last. Otherwise a sync from a device you have not touched
+    in a week quietly undoes the preferences you changed a minute ago. */
+export function load(): void {
+  let local: Partial<Payload> | null = null;
+  try {
+    const raw = localStorage.getItem(cfg.key);
+    if (raw) {
+      local = JSON.parse(raw);
+    }
+  } catch {
+    /* unreadable: start fresh */
+  }
+  if (local) {
+    apply(local);
+  } else {
+    runNormalizers(honmoon.settings);
+  }
+  const sync = cfg.sync;
+  if (!sync) {
+    return;
+  }
+  sync
+    .load()
+    .then((remote) => {
+      synced = true;
+      if (remote && remote.cards && progressOf(remote) >= progressOf(local)) {
+        const localWrittenAt = (local && local.t) || 0;
+        const remoteWrittenAt = remote.t || 0;
+        const keepLocalSettings = remoteWrittenAt <= localWrittenAt && !!(local && local.settings);
+        apply(remote, keepLocalSettings);
+      } else {
+        dirty = true;
+        save();
+      }
+    })
+    .catch(() => {});
+}
+
+export function resetProgress(): void {
+  honmoon.cards = {};
+  honmoon.daily = {};
+  honmoon.answers = 0;
+  dirty = true;
+  save();
+}
+
+/** Progress as a JSON file's text, for the export button. */
+export function exportText(): string {
+  return JSON.stringify(payload(), null, 1);
+}
+
+/** Replace progress with an exported payload — from any of the apps or from the original
+    Fretboard Fluency (same format). Settings are kept unless asked for. */
+export function importText(
+  text: string,
+  withSettings = false,
+): { ok: boolean; answers: number; msg: string } {
+  let imported: Partial<Payload>;
+  try {
+    imported = JSON.parse(text);
+  } catch {
+    return { ok: false, answers: 0, msg: 'That file is not readable JSON.' };
+  }
+  if (!imported || typeof imported !== 'object' || !imported.cards) {
+    return { ok: false, answers: 0, msg: 'That file has no progress in it.' };
+  }
+  apply(imported, !withSettings);
+  dirty = true;
+  save();
+  return { ok: true, answers: honmoon.answers, msg: 'Imported ' + honmoon.answers + ' answers.' };
+}
+
+if (typeof document !== 'undefined') {
+  document.addEventListener('visibilitychange', () => {
+    if (document.hidden) {
+      save();
+    }
+  });
+  window.addEventListener('pagehide', save);
+}

package/src/lib/store/normalize.ts

@@ -0,0 +1,23 @@
+import { addNormalizer } from './honmoon.svelte';
+import { SCALES } from '../music/scales';
+import { VSTAGES } from '../music/voice';
+import { appHasDrill, appHasGroup } from '../drills/registry.svelte';
+
+/** The tidy-ups the original applied to every save it loaded. Call once at
+    start-up, after configureGroups(). */
+export function installDefaultNormalizers(): void {
+  addNormalizer((settings) => {
+    if (!settings.sen) {
+      settings.sen = SCALES.filter((scale) => scale.on).map((scale) => scale.id);
+    }
+    if (!settings.voff) {
+      settings.voff = VSTAGES.filter((stage) => !stage.on).map((stage) => stage.k);
+    }
+    /* The families were regrouped; an old save may hold keys that no longer
+       name anything. Guessing what the owner meant would switch off the wrong
+       half, so anything unrecognised is simply dropped and that family comes
+       back on. */
+    settings.off = Array.isArray(settings.off) ? settings.off.filter(appHasGroup) : [];
+    settings.doff = Array.isArray(settings.doff) ? settings.doff.filter(appHasDrill) : [];
+  });
+}

package/src/lib/store/sync.ts

@@ -0,0 +1,43 @@
+import type { Payload } from './types';
+
+/** Anything that can keep a copy of the progress payload somewhere other than
+    this browser. The store calls load() once at start-up and save() after
+    every debounced write. */
+export interface SyncAdapter {
+  /** Short name for the Stats screen, e.g. "Firebase". */
+  readonly name: string;
+  load(): Promise<Payload | null>;
+  save(payload: Payload): Promise<void>;
+}
+
+/* ---------------- Firebase (not wired up yet) ----------------
+   This is the stub the apps will fill in once there is a Firebase project.
+   The plan, so the shape of this file does not have to change later:
+
+     1. Sign in with Firebase Auth (Google sign-in is the simplest on Android).
+     2. Keep one Firestore document per app per user:
+          users/{uid}/apps/{appId}   ->  the Payload, as is
+        A payload is a few tens of kilobytes at most, far inside one document.
+     3. load() reads that document; save() writes it with set().
+     4. Turn on Firestore's offline persistence, so practising on the bus with
+        no signal still saves and catches up later.
+
+   Until then load() rejects, which the store treats exactly like "no sync
+   configured": everything stays in this browser, and the Stats screen says so. */
+export interface FirebaseSyncOptions {
+  appId: string;
+  /** The web-app config from the Firebase console. */
+  config?: Record<string, string>;
+}
+
+export class FirebaseSync implements SyncAdapter {
+  readonly name = 'Firebase';
+  constructor(readonly opts: FirebaseSyncOptions) {}
+  async load(): Promise<Payload | null> {
+    // TODO(firebase): sign in, then read users/{uid}/apps/{appId}
+    throw new Error('Firebase sync is not set up yet');
+  }
+  async save(_payload: Payload): Promise<void> {
+    // TODO(firebase): write users/{uid}/apps/{appId}
+  }
+}

package/src/lib/store/types.ts

@@ -0,0 +1,101 @@
+/* The shape of everything the apps remember. One payload per app, in the same
+   format the original Fretboard Fluency used (`ff.v1`), so progress exported
+   from the old app can be imported into any of the new ones unchanged. */
+
+export type Pref = 'sharp' | 'flat';
+export type Sys = 'en' | 'solf';
+export type ClefId = 'bass' | 'treble' | 'tenor' | 'alto';
+export type LevelId = 'l0' | 'l1' | 'l2';
+export type RhythmLevelId = 'r1' | 'r2' | 'r3';
+export type Theme = 'auto' | 'light' | 'dark';
+
+/** One thing you can be asked about. s = seen, c = correct, t = last seen (ms), k = mastery 0–5. */
+export interface Card {
+  s: number;
+  c: number;
+  t: number;
+  k: number;
+}
+
+/** One calendar day: answers, correct answers, milliseconds spent. */
+export interface Day {
+  n: number;
+  c: number;
+  ms: number;
+}
+
+export interface TempoEntry {
+  d: string;
+  bpm: number;
+  v: TempoVerdict;
+}
+export type TempoVerdict = 'clean' | 'sloppy' | 'fast';
+
+/** Tempo tracking for a warm-up family or a rhythm level. */
+export interface TempoRec {
+  bpm: number;
+  best: number;
+  n: number;
+  hist: TempoEntry[];
+}
+
+export interface Settings {
+  /* notes */
+  pref: Pref;
+  level: LevelId;
+  acc: boolean;
+  clefs: ClefId[];
+  mdo: boolean;
+  /* screen */
+  theme: Theme;
+  hints: boolean;
+  labels: boolean;
+  /* instrument and sound */
+  bass: boolean;
+  mic: boolean;
+  sound: boolean;
+  /* daily session */
+  slen: number;
+  off: string[];
+  doff: string[];
+  /* scales */
+  sen: string[] | null;
+  sroots: 'nat' | 'all';
+  sstart: 'both' | 'E' | 'A';
+  sslen: number;
+  sdoff: string[];
+  /* ear */
+  ivset: 'basic' | 'all';
+  /* bass warm-ups */
+  woff: string[];
+  wlen: number;
+  wmode: 'bass' | 'voice';
+  /* voice */
+  vlo: number | null;
+  vhi: number | null;
+  voff: string[] | null;
+  vtempo: number;
+  vgap: boolean;
+  /* rhythm */
+  rlev: RhythmLevelId;
+  rtempo: number;
+  rfloor: number;
+  rlat: number;
+}
+
+export interface Payload {
+  v: 1;
+  t: number;
+  cards: Record<string, Card>;
+  daily: Record<string, Day>;
+  tempo: Record<string, TempoRec>;
+  settings: Settings;
+}
+
+export interface HonmoonState {
+  cards: Record<string, Card>;
+  daily: Record<string, Day>;
+  tempo: Record<string, TempoRec>;
+  settings: Settings;
+  answers: number;
+}