@greenblacksky/honmoon 0.0.0-stage → 0.4.1

package/src/lib/learn/session.ts

@@ -0,0 +1,304 @@
+import { honmoon, mastery } from '../store/honmoon.svelte';
+import { STRINGS, allowedPc, bassHere, placesFor, positions } from '../music/bass';
+import { parseST, staffNotes } from '../music/clefs';
+import { earCards } from '../music/intervals';
+import { mdoOn } from '../music/notes';
+import { rhCardFits, rhCards } from '../music/rhythm';
+import { parseSC, scaleCards, scaleOn } from '../music/scales';
+import { shuffle } from '../util/random';
+import {
+  appDrills,
+  drillAvailable,
+  drillOn,
+  groupOfDrill,
+  groupUsable,
+  sdrillOn,
+} from '../drills/registry.svelte';
+import { isScaleDrill, type DrillDef } from '../drills/defs';
+import { mdoCards, parseMD, pcs, playPcs, scalearCards } from './pools';
+
+/* ---------------- sampling ----------------
+   How badly a card needs practice: error rate, how stale it is, whether it has
+   ever been seen, and how far its mastery is from solid. */
+const MS_PER_HOUR = 3600000;
+/** Staleness stops counting after three days. */
+const MAX_STALE_HOURS = 72;
+/** Every this many hours unseen adds the card's base weight again. */
+const STALE_SCALE_HOURS = 22;
+const ERROR_RATE_WEIGHT = 3.2;
+const NEVER_SEEN_BOOST = 2.4;
+/** Each step of mastery short of solid adds this share. */
+const PER_MISSING_MASTERY = 0.22;
+/** The card just asked is this much less likely to come straight back. */
+const JUST_ASKED_FACTOR = 0.06;
+
+export function weightOf(id: string): number {
+  const stats = honmoon.cards[id];
+  const seen = stats ? stats.s : 0;
+  const wrong = stats ? stats.s - stats.c : 0;
+  const errorRate = seen ? wrong / seen : 0;
+  const hoursStale =
+    stats && stats.t
+      ? Math.min((Date.now() - stats.t) / MS_PER_HOUR, MAX_STALE_HOURS)
+      : MAX_STALE_HOURS;
+  return (
+    (1 + ERROR_RATE_WEIGHT * errorRate) *
+    (1 + hoursStale / STALE_SCALE_HOURS) *
+    (seen === 0 ? NEVER_SEEN_BOOST : 1) *
+    (1 + (5 - mastery(id)) * PER_MISSING_MASTERY)
+  );
+}
+/** A random index, each chosen with probability proportional to its weight. */
+function weightedIndex(weights: number[]): number {
+  const total = weights.reduce((sum, weight) => sum + weight, 0);
+  let remaining = Math.random() * total;
+  for (let i = 0; i < weights.length; i++) {
+    remaining -= weights[i];
+    if (remaining <= 0) {
+      return i;
+    }
+  }
+  return weights.length - 1;
+}
+let lastId: string | null = null;
+/** One card from a pool, weighted by need — and almost never the one just asked. */
+export function pick<T extends { id: string }>(pool: T[]): T | null {
+  if (!pool.length) {
+    return null;
+  }
+  const weights = pool.map((item) => {
+    const weight = weightOf(item.id);
+    return item.id === lastId && pool.length > 1 ? weight * JUST_ASKED_FACTOR : weight;
+  });
+  const chosen = pool[weightedIndex(weights)];
+  lastId = chosen.id;
+  return chosen;
+}
+
+/** Semitones between two pitch classes, the short way round (0–6). */
+function pcDistance(a: number, b: number): number {
+  const apart = Math.abs(a - b);
+  return Math.min(apart, 12 - apart);
+}
+/** Take a random element out of an array. */
+function takeRandom<T>(items: T[]): T {
+  return items.splice(Math.floor(Math.random() * items.length), 1)[0];
+}
+/** Wrong answers near the right one: a semitone or two away first. */
+export function distractors(correctPc: number, count: number): number[] {
+  const pool: number[] = [];
+  for (let pc = 0; pc < 12; pc++) {
+    if (allowedPc(pc) && pc !== correctPc) {
+      pool.push(pc);
+    }
+  }
+  const near = pool.filter((pc) => pcDistance(pc, correctPc) <= 2);
+  const out: number[] = [];
+  while (out.length < count && near.length) {
+    out.push(takeRandom(near));
+  }
+  while (out.length < count && pool.length) {
+    const pc = takeRandom(pool);
+    if (!out.includes(pc)) {
+      out.push(pc);
+    }
+  }
+  return out;
+}
+export interface Choice {
+  /** the label shown */
+  t: string;
+  /** whether it is the right answer */
+  ok: boolean;
+}
+/** Multiple-choice answers, built safely.
+    Every option must read differently from every other, and exactly one is
+    right. When a pool cannot supply four distinct labels the question asks
+    with fewer — padding it out by repeating a label does not make the
+    question harder, it makes it unanswerable, because the correct answer
+    becomes indistinguishable from a wrong one. */
+export function options(correct: string, pool: string[], count?: number): Choice[] {
+  const max = count || 4;
+  const out: Choice[] = [{ t: correct, ok: true }];
+  const used = new Set([correct]);
+  for (const label of shuffle(pool.slice())) {
+    if (out.length >= max || used.has(label)) {
+      continue;
+    }
+    used.add(label);
+    out.push({ t: label, ok: false });
+  }
+  return shuffle(out);
+}
+/** options() shuffles what it is handed, so the best three wrong answers are
+    chosen here, after dropping any that would read the same as the right one. */
+export function altOptions(correct: string, labels: string[]): Choice[] {
+  const used = new Set([correct]);
+  const keep: string[] = [];
+  for (const label of labels) {
+    if (!used.has(label) && keep.length < 3) {
+      used.add(label);
+      keep.push(label);
+    }
+  }
+  return options(correct, keep);
+}
+
+/* ---------------- which drills can ask a card ---------------- */
+/** For an ordinary (non-scale, non-ear) card: which drill kinds can ask it,
+    by card prefix. */
+const ASKS_CARD: Record<string, (drill: DrillDef, id: string) => boolean> = {
+  'fb:': (drill) => drill.kind === 'fb2name' || drill.kind === 'name2fb',
+  'st:': (drill, id) =>
+    drill.kind === 'staff2name' ||
+    drill.kind === 'staffkey' ||
+    (drill.kind === 'play' && drill.sys === 'staff' && parseST(id).clef === 'bass'),
+  'tr:': (drill) => drill.kind === 'translate',
+  'pl:': (drill) => drill.kind === 'play' && drill.sys !== 'staff',
+  'md:': (drill, id) =>
+    drill.kind === 'mdo' && (drill.from !== 'fb' || placesFor(parseMD(id).pc).length > 0),
+  'rh:': (drill, id) => drill.kind === 'rhythm' && rhCardFits(id, drill.rk!),
+  'se:': (drill, id) => drill.kind === 'earscale' && scaleOn(id.slice(3)),
+};
+export function drillsForCard(id: string): DrillDef[] {
+  const prefix = id.slice(0, 3);
+  const drills = appDrills();
+  if (prefix === 'sc:') {
+    return drills.filter(
+      (drill) => isScaleDrill(drill.id) && sdrillOn(drill.id) && (!drill.bass || bassHere()),
+    );
+  }
+  if (prefix === 'iv:' || prefix === 'ch:') {
+    return drills.filter((drill) => {
+      if (drill.kind !== 'ear' || !groupUsable(groupOfDrill(drill.id)!) || !drillOn(drill.id)) {
+        return false;
+      }
+      // chords are asked only by the chord drill, intervals by the others
+      return prefix === 'ch:' ? drill.id === 'chhear' : drill.id !== 'chhear';
+    });
+  }
+  const asks = ASKS_CARD[prefix];
+  return drills.filter(
+    (drill) =>
+      !isScaleDrill(drill.id) &&
+      groupUsable(groupOfDrill(drill.id)!) &&
+      drillOn(drill.id) &&
+      drillAvailable(drill) &&
+      !!asks &&
+      asks(drill, id),
+  );
+}
+
+/** Every card the daily session can draw from, in this app. */
+export function allCards(): string[] {
+  const out: string[] = [];
+  if (groupUsable('ear') || groupUsable('voice')) {
+    out.push(...earCards());
+  }
+  if (groupUsable('ear')) {
+    out.push(...scalearCards());
+  }
+  out.push(...positions().map((pos) => pos.id));
+  out.push(...staffNotes().map((note) => note.id));
+  out.push(...pcs().map((item) => item.id));
+  out.push(...playPcs().map((item) => item.id));
+  if (mdoOn()) {
+    out.push(...mdoCards());
+  }
+  if (groupUsable('read')) {
+    out.push(...rhCards());
+  }
+  /* Scale-and-key pairs join the daily mix when the family is left on. The
+     Scales screen keeps its own session for when you want a run of nothing
+     else, and that one ignores this switch. */
+  if (groupUsable('scale')) {
+    out.push(...scaleCards());
+  }
+  return out.filter((id) => drillsForCard(id).length > 0);
+}
+
+export interface QueueEntry {
+  card: string;
+  drill: string;
+  /** a card coming back after being missed */
+  retry?: 1;
+}
+/** Draw the weakest cards first, but without replacement, so one bad note
+    cannot eat the whole session. Refill if the range is smaller than the
+    session length. */
+export function buildSession(length: number, mode?: 'scales' | 'theory'): QueueEntry[] {
+  const cards =
+    mode === 'scales' ? scaleCards().filter((id) => drillsForCard(id).length > 0) : allCards();
+  if (!cards.length) {
+    return [];
+  }
+  let pool = cards.slice();
+  const out: QueueEntry[] = [];
+  for (let k = 0; k < length; k++) {
+    if (!pool.length) {
+      pool = cards.slice();
+    }
+    const index = weightedIndex(pool.map(weightOf));
+    const id = pool.splice(index, 1)[0];
+    const drills = drillsForCard(id);
+    out.push({ card: id, drill: drills[Math.floor(Math.random() * drills.length)].id });
+  }
+  return decluster(shuffle(out));
+}
+/** No drill three times running, if it can be helped. */
+function decluster(queue: QueueEntry[]): QueueEntry[] {
+  for (let i = 2; i < queue.length; i++) {
+    const threeInARow =
+      queue[i].drill === queue[i - 1].drill && queue[i - 1].drill === queue[i - 2].drill;
+    if (!threeInARow) {
+      continue;
+    }
+    for (let j = i + 1; j < queue.length; j++) {
+      if (queue[j].drill !== queue[i].drill) {
+        [queue[i], queue[j]] = [queue[j], queue[i]];
+        break;
+      }
+    }
+  }
+  return queue;
+}
+
+/** What a card id stands for, as the question makers want it. */
+export type CardItem =
+  | { id: string; sid: string; root: number }
+  | { id: string; s: number; f: number; m: number }
+  | { id: string; m: number; clef: string }
+  | { id: string; keyPc: number; pc: number }
+  | { id: string; pc: number }
+  | { id: string };
+export function cardToItem(id: string): CardItem | null {
+  const prefix = id.slice(0, 3);
+  switch (prefix) {
+    case 'sc:': {
+      const { sid, root } = parseSC(id);
+      return { sid, root, id };
+    }
+    case 'iv:':
+    case 'ch:':
+    case 'se:':
+    case 'rh:':
+      return { id };
+    case 'fb:': {
+      const [, string, fret] = id.split(':').map(Number);
+      return { s: string, f: fret, m: STRINGS[string].open + fret, id };
+    }
+    case 'st:': {
+      const { m, clef } = parseST(id);
+      return { m, clef, id };
+    }
+    case 'md:': {
+      const { keyPc, pc } = parseMD(id);
+      return { keyPc, pc, id };
+    }
+    case 'tr:':
+    case 'pl:':
+      return { pc: +id.slice(3), id };
+    default:
+      return null;
+  }
+}

package/src/lib/music/bass.ts

@@ -0,0 +1,139 @@
+import { honmoon } from '../store/honmoon.svelte';
+import { NAT, pcOf } from './notes';
+import type { LevelId } from '../store/types';
+
+/* Written pitch: bass sounds an octave below what is written.
+   Open strings written: E2 40, A2 45, D3 50, G3 55. Top row -> bottom row. */
+export const STRINGS = [
+  { n: 'G', open: 55 },
+  { n: 'D', open: 50 },
+  { n: 'A', open: 45 },
+  { n: 'E', open: 40 },
+] as const;
+
+/* How far up the neck, and — separately — whether the black notes are in.
+   These used to be one four-step ladder ending in "All 12 notes", which meant
+   the only way to meet a sharp was to jump to the whole neck, and nothing in
+   the name of a range said anything about sharps at all. They are two
+   different questions, so they are two separate controls. */
+export interface Level {
+  id: LevelId;
+  name: string;
+  lo: number;
+  hi: number;
+  /** how far the board is drawn, when that is wider than what is carded */
+  vhi?: number;
+  desc: string;
+}
+export const LEVELS: Level[] = [
+  {
+    id: 'l0',
+    name: 'Open strings',
+    lo: 0,
+    hi: 0,
+    vhi: 4,
+    desc: 'The four open strings only — the place to start on the staff',
+  },
+  { id: 'l1', name: 'Open position', lo: 0, hi: 5, desc: 'Frets 0–5' },
+  { id: 'l2', name: 'Full neck', lo: 0, hi: 12, desc: 'Frets 0–12' },
+];
+
+export function lvl(): Level {
+  return LEVELS.find((level) => level.id === honmoon.settings.level) ?? LEVELS[1];
+}
+/** The highest fret drawn on the board (can be wider than the carded range). */
+export function vhi(): number {
+  const level = lvl();
+  return level.vhi ?? level.hi;
+}
+export function accOn(): boolean {
+  return honmoon.settings.acc === true;
+}
+export function allowedPc(pc: number): boolean {
+  return accOn() || NAT.includes(pc);
+}
+/** Whether the instrument is to hand. Separate from the microphone setting:
+    the mic is about how a played note gets graded, this is about whether
+    there is a bass in the room at all. */
+export function bassHere(): boolean {
+  return honmoon.settings.bass !== false;
+}
+
+/** A place on the neck: string index `s` (0 = G, top row), fret `f`, the
+    written MIDI pitch `m`, and its card id. */
+export interface FretPos {
+  s: number;
+  f: number;
+  m: number;
+  id: string;
+}
+
+const STRING_COUNT = STRINGS.length;
+/** The neck as drawn on maps and used to place a written pitch: frets 0–12. */
+const MAP_LAST_FRET = 12;
+/** The highest fret `findPos` will suggest. */
+const REACHABLE_LAST_FRET = 15;
+/** String indices from the lowest string (E) up. */
+const LOW_TO_HIGH_STRINGS = [3, 2, 1, 0];
+
+function cardIdForFret(string: number, fret: number): string {
+  return 'fb:' + string + ':' + fret;
+}
+
+/** Every carded position on the neck at the current range. */
+export function positions(): FretPos[] {
+  const level = lvl();
+  const out: FretPos[] = [];
+  for (let string = 0; string < STRING_COUNT; string++) {
+    for (let fret = level.lo; fret <= level.hi; fret++) {
+      const midi = STRINGS[string].open + fret;
+      if (allowedPc(pcOf(midi))) {
+        out.push({ s: string, f: fret, m: midi, id: cardIdForFret(string, fret) });
+      }
+    }
+  }
+  return out;
+}
+/** Every place a pitch class can be played at this range. */
+export function placesFor(pc: number): FretPos[] {
+  return positions().filter((pos) => pcOf(pos.m) === pc);
+}
+/** Every place a written pitch sits on a 12-fret neck. */
+export function placesForMidi(midi: number): { s: number; f: number }[] {
+  const out: { s: number; f: number }[] = [];
+  for (let string = 0; string < STRING_COUNT; string++) {
+    for (let fret = 0; fret <= MAP_LAST_FRET; fret++) {
+      if (STRINGS[string].open + fret === midi) {
+        out.push({ s: string, f: fret });
+      }
+    }
+  }
+  return out;
+}
+/** Where one pitch class sits on a single string, within the range on show.
+    Two, when the string covers a full octave. The whole span that is drawn and
+    tappable counts, not just the carded one: if a fret is on the board and is
+    that note, tapping it is a fair answer. */
+export function sameNoteFrets(string: number, pc: number): number[] {
+  const out: number[] = [];
+  for (let fret = lvl().lo; fret <= vhi(); fret++) {
+    if (pcOf(STRINGS[string].open + fret) === pc) {
+      out.push(fret);
+    }
+  }
+  return out;
+}
+/** The first playable spot for a written pitch, trying a preferred string first. */
+export function findPos(
+  midi: number,
+  preferString?: number | null,
+): { s: number; f: number } | null {
+  const order = preferString == null ? LOW_TO_HIGH_STRINGS : [preferString, ...LOW_TO_HIGH_STRINGS];
+  for (const string of order) {
+    const fret = midi - STRINGS[string].open;
+    if (fret >= 0 && fret <= REACHABLE_LAST_FRET) {
+      return { s: string, f: fret };
+    }
+  }
+  return null;
+}

package/src/lib/music/clefs.ts

@@ -0,0 +1,218 @@
+import { honmoon } from '../store/honmoon.svelte';
+import type { ClefId, Pref } from '../store/types';
+import { LETTERS, NATPC, STEP, pcOf, spell } from './notes';
+import { STRINGS, allowedPc, lvl } from './bass';
+import { rnd } from '../util/random';
+
+/* staff coords: line y = 0,10,20,30,40, bottom line at y=40.
+   A clef is nothing but an offset: it names the diatonic index sitting on
+   the bottom line. bot 18 = G2 (bass), 30 = E4 (treble), 24 = F3 (alto),
+   22 = D3 (tenor). Everything else about the staff is identical. */
+export interface ClefDef {
+  id: ClefId;
+  n: string;
+  ab: string;
+  bot: number;
+  /** mnemonic for the lines, and for the spaces */
+  ml: string;
+  ms: string;
+  sb: string;
+}
+export const CLEFS: ClefDef[] = [
+  {
+    id: 'bass',
+    n: 'Bass',
+    ab: 'F',
+    bot: 18,
+    ml: 'Good Boys Do Fine Always',
+    ms: 'All Cows Eat Grass',
+    sb: 'The F clef. Where bass guitar and the low half of the piano are written.',
+  },
+  {
+    id: 'treble',
+    n: 'Treble',
+    ab: 'G',
+    bot: 30,
+    ml: 'Every Good Boy Deserves Fruit',
+    ms: 'bottom to top they spell FACE',
+    sb: 'The G clef. Singing, guitar, the right hand of the piano — most music you will ever meet.',
+  },
+  {
+    id: 'tenor',
+    n: 'Tenor',
+    ab: 'C4',
+    bot: 22,
+    ml: 'Dogs From Africa Chase Elephants',
+    ms: 'Every Good Bass Does',
+    sb: 'A C clef on the fourth line. Turns up in high bass, cello and trombone parts, to dodge ledger lines.',
+  },
+  {
+    id: 'alto',
+    n: 'Alto',
+    ab: 'C3',
+    bot: 24,
+    ml: 'Fat Alley Cats Eat Garbage',
+    ms: 'Good Bass Does Fine',
+    sb: 'A C clef on the middle line. Viola, and the occasional arrangement. Learn it last.',
+  },
+];
+export function clefDef(id: string): ClefDef {
+  return CLEFS.find((clef) => clef.id === id) ?? CLEFS[0];
+}
+export function enabledClefs(): ClefId[] {
+  const chosen = honmoon.settings.clefs;
+  if (!chosen || !chosen.length) {
+    return ['bass'];
+  }
+  const out = CLEFS.filter((clef) => chosen.includes(clef.id)).map((clef) => clef.id);
+  return out.length ? out : ['bass'];
+}
+export function clefOn(id: ClefId): boolean {
+  return enabledClefs().includes(id);
+}
+export function multiClef(): boolean {
+  return enabledClefs().length > 1;
+}
+
+/* Staff geometry in SVG units: five lines 10 apart, so one diatonic step
+   (line to space) is 5, and the bottom line sits at y = 40. */
+const STAFF_BOTTOM_Y = 40;
+const Y_PER_STEP = 5;
+const STEPS_PER_OCTAVE = 7;
+const STAFF_LINES = 5;
+const STAFF_SPACES = 4;
+/** Two ledger lines = four diatonic steps beyond the staff. */
+const LEDGER_STEPS = 4;
+/** From the bottom line to the top line is eight steps. */
+const STAFF_HEIGHT_STEPS = 8;
+const MIDDLE_C = 60;
+
+/** Notation is diatonic, not chromatic: C and C♯ share a line. So position is
+    found from a diatonic index, offset by whichever clef is in force. */
+export function staffPos(
+  writtenMidi: number,
+  pref: Pref,
+  clef: string = 'bass',
+): { y: number; l: string; a: number } {
+  const bottomLineStep = clefDef(clef || 'bass').bot;
+  const octave = Math.floor(writtenMidi / 12) - 1;
+  const spelling = spell(pcOf(writtenMidi), pref);
+  const diatonicIndex = octave * STEPS_PER_OCTAVE + STEP[spelling.l];
+  return {
+    y: STAFF_BOTTOM_Y - (diatonicIndex - bottomLineStep) * Y_PER_STEP,
+    l: spelling.l,
+    a: spelling.a,
+  };
+}
+/** The natural MIDI note at a diatonic index (C-1 = 0, D-1 = 1, …). */
+export function diatonicMidi(diatonicIndex: number): number {
+  const octave = Math.floor(diatonicIndex / STEPS_PER_OCTAVE);
+  const stepInOctave = diatonicIndex - octave * STEPS_PER_OCTAVE;
+  for (let i = 0; i < LETTERS.length; i++) {
+    if (STEP[LETTERS[i]] === stepInOctave) {
+      return (octave + 1) * 12 + NATPC[i];
+    }
+  }
+  return MIDDLE_C;
+}
+export function clefLines(clef: string): number[] {
+  const bottom = clefDef(clef).bot;
+  const out: number[] = [];
+  for (let line = 0; line < STAFF_LINES; line++) {
+    out.push(diatonicMidi(bottom + line * 2));
+  }
+  return out;
+}
+export function clefSpaces(clef: string): number[] {
+  const bottom = clefDef(clef).bot;
+  const out: number[] = [];
+  for (let space = 0; space < STAFF_SPACES; space++) {
+    out.push(diatonicMidi(bottom + 1 + space * 2));
+  }
+  return out;
+}
+/** The written notes that sit comfortably on a clef: the staff itself plus
+    two ledger lines either side. */
+export function clefRange(clef: string): number[] {
+  const bottom = clefDef(clef).bot;
+  const lowest = bottom - LEDGER_STEPS;
+  const highest = bottom + STAFF_HEIGHT_STEPS + LEDGER_STEPS;
+  const out: number[] = [];
+  for (let step = lowest; step <= highest; step++) {
+    out.push(diatonicMidi(step));
+  }
+  return out;
+}
+
+/* ---- staff cards ----
+   Bass-clef cards keep their old id, "st:<midi>", so nothing already learned
+   is thrown away; the other clefs add their name in the middle. */
+export interface StaffNote {
+  m: number;
+  clef: ClefId;
+  id: string;
+}
+export function stId(clef: ClefId, m: number): string {
+  return clef === 'bass' ? 'st:' + m : 'st:' + clef + ':' + m;
+}
+export function parseST(id: string): { clef: ClefId; m: number } {
+  const parts = id.split(':');
+  // 'st:m' is a bass-clef note (the original format); 'st:clef:m' any other clef
+  return parts.length === 2
+    ? { clef: 'bass', m: +parts[1] }
+    : { clef: parts[1] as ClefId, m: +parts[2] };
+}
+/** Bass clef follows the fret range you are working in, so the staff and the
+    neck always agree. The other clefs have no neck to follow, so they use the
+    staff itself plus two ledger lines either way. */
+export function staffNotesFor(clef: ClefId): StaffNote[] {
+  const out: StaffNote[] = clef === 'bass' ? bassClefNotesOnNeck() : notesAroundStaff(clef);
+  out.sort((a, b) => a.m - b.m);
+  return out;
+}
+/** Each distinct written pitch the neck covers at the current range. */
+function bassClefNotesOnNeck(): StaffNote[] {
+  const level = lvl();
+  const seen = new Set<number>();
+  const out: StaffNote[] = [];
+  for (let string = 0; string < STRINGS.length; string++) {
+    for (let fret = level.lo; fret <= level.hi; fret++) {
+      const midi = STRINGS[string].open + fret;
+      if (allowedPc(pcOf(midi)) && !seen.has(midi)) {
+        seen.add(midi);
+        out.push({ m: midi, clef: 'bass', id: stId('bass', midi) });
+      }
+    }
+  }
+  return out;
+}
+function notesAroundStaff(clef: ClefId): StaffNote[] {
+  return clefRange(clef)
+    .filter((midi) => allowedPc(pcOf(midi)))
+    .map((midi) => ({ m: midi, clef, id: stId(clef, midi) }));
+}
+export function staffNotes(): StaffNote[] {
+  return enabledClefs().flatMap((clef) => staffNotesFor(clef));
+}
+/** A written pitch carrying this pitch class, sitting on the given clef. */
+export function midiForPcInClef(pc: number, clef: ClefId): number {
+  const matches = clefRange(clef).filter((midi) => pcOf(midi) === pc);
+  if (matches.length) {
+    return matches[rnd(matches.length)];
+  }
+  /* spelled notes only cover naturals, so step to the nearest one and let
+     the accidental do the rest */
+  const range = clefRange(clef);
+  let nearest = range[0];
+  let nearestDistance = Infinity;
+  for (const midi of range) {
+    const distance = Math.abs(pcOf(midi) - pc);
+    if (distance < nearestDistance) {
+      nearestDistance = distance;
+      nearest = midi;
+    }
+  }
+  const nearestPc = pcOf(nearest);
+  const wrapsToNextOctave = pc < nearestPc && nearestPc - pc > 6;
+  return nearest - nearestPc + pc + (wrapsToNextOctave ? 12 : 0);
+}