@greenblacksky/honmoon 0.0.0-stage → 0.4.0

package/src/lib/notation/rhythmsvg.ts

@@ -0,0 +1,341 @@
+import { HEADW, STEMW, STEMX, gMid, gPath, gW, headName, type GlyphName } from './glyphs';
+import {
+  beamGroups,
+  beamsFor,
+  countAt,
+  restName,
+  rvalDef,
+  type Bar,
+  type TapGrade,
+  type TimeSig,
+} from '../music/rhythm';
+import { esc } from '../util/text';
+
+/* ---- the single-line rhythm staff ----
+   Same engraved glyphs as the pitched staff, with one line instead of five:
+   noteheads sit on it, stems go up, and beams are drawn across the beat. */
+/** Where the first note goes, width of one sixteenth, stem top and bottom. */
+const RHL = { x0: 44, uw: 15, up: -35, dn: 35 };
+/** First note's x when there is no time signature. */
+const X0_WITHOUT_TIME_SIG = 18;
+/** Two noteheads never closer than this, or a dotted note and the next. */
+const MIN_NOTE_GAP = 16;
+const MIN_GAP_AFTER_DOT = 25;
+const BEAM_THICKNESS = 5;
+const SECOND_BEAM_OFFSET = 7.5;
+/** A sixteenth with no sixteenth beside it gets a stub this long. */
+const STUB_BEAM = 8;
+const DEFAULT_SCALE = 1.15;
+const STAFF_INK = 'var(--staff)';
+const MONO = 'IBM Plex Mono,monospace';
+
+/** Dotted values: dotted eighth (3), dotted quarter (6), dotted half (12). */
+function isDotted(sixteenths: number): boolean {
+  return sixteenths === 3 || sixteenths === 6 || sixteenths === 12;
+}
+function restGlyph(sixteenths: number): GlyphName {
+  if (sixteenths >= 16) {
+    return 'restWhole';
+  }
+  if (sixteenths >= 8) {
+    return 'restHalf';
+  }
+  if (sixteenths >= 4) {
+    return 'restQuarter';
+  }
+  return sixteenths >= 2 ? 'rest8th' : 'rest16th';
+}
+function rhRest(x: number, sixteenths: number): string {
+  const glyph = restGlyph(sixteenths);
+  let out = gMid(glyph, x, 0);
+  if (isDotted(sixteenths)) {
+    out += gMid('augmentationDot', x + gW(glyph) / 2 + 5, -6);
+  }
+  return out;
+}
+function rhTimeSig(bar: Bar, x: number): string {
+  return (
+    gMid(('timeSig' + bar.ts[0]) as GlyphName, x, -11) +
+    gMid(('timeSig' + bar.ts[1]) as GlyphName, x, 11)
+  );
+}
+/** The left edge of the stem of a note at x. */
+const stemLeft = (x: number) => x + STEMX - STEMW / 2;
+function upStem(x: number): string {
+  return `<rect x="${stemLeft(x).toFixed(2)}" y="${RHL.up}" width="${STEMW}" height="${-RHL.up}" fill="${STAFF_INK}"/>`;
+}
+/** A flag on an unbeamed eighth or sixteenth. */
+function flag(x: number, sixteenths: number): string {
+  return gPath(beamsFor(sixteenths) > 1 ? 'flag16thUp' : 'flag8thUp', stemLeft(x), RHL.up);
+}
+/** A note standing alone or inside a beam group: head, stem, flag if
+    unbeamed and shorter than a quarter, dot. */
+function noteGlyphs(x: number, sixteenths: number, beamed: boolean): string {
+  let out = gMid(headName(sixteenths), x, 0);
+  if (sixteenths < 16) {
+    out += upStem(x);
+    if (!beamed && sixteenths < 4) {
+      out += flag(x, sixteenths);
+    }
+  }
+  if (isDotted(sixteenths)) {
+    out += gMid('augmentationDot', x + HEADW + 5, -6);
+  }
+  return out;
+}
+
+export interface RhythmOpts {
+  /** width of one sixteenth */
+  uw?: number;
+  /** leave out the time signature */
+  noTs?: boolean;
+  /** index of an event to pick out */
+  hi?: number;
+  /** index of an event to leave blank, with a question mark */
+  blank?: number;
+  /** write the counting under the notes */
+  count?: boolean;
+  scale?: number;
+}
+/** Time is laid out proportionally, but two noteheads can never be closer
+    than they are wide, or a run of sixteenths turns into a smudge. Each note
+    takes its proportional place or the minimum gap, whichever is further on. */
+function noteXs(bar: Bar, firstX: number, unitWidth: number): number[] {
+  const xs: number[] = [];
+  let at = 0;
+  bar.ev.forEach((event, i) => {
+    let x = firstX + at * unitWidth + unitWidth * 0.5;
+    if (i > 0) {
+      const gap = isDotted(bar.ev[i - 1].u) ? MIN_GAP_AFTER_DOT : MIN_NOTE_GAP;
+      x = Math.max(x, xs[i - 1] + gap);
+    }
+    xs.push(x);
+    at += event.u;
+  });
+  return xs;
+}
+function blankSlot(x: number): string {
+  return (
+    `<rect x="${x - 10}" y="-17" width="21" height="32" rx="4" fill="none" stroke="var(--accent)" stroke-width="2" stroke-dasharray="4 3"/>` +
+    `<text x="${x + 0.5}" y="6" text-anchor="middle" font-size="17" font-weight="700" fill="var(--accent)" font-family="${MONO}">?</text>`
+  );
+}
+function tieCurve(fromX: number, toX: number): string {
+  return `<path d="M${fromX + 2} 7.5 Q${(fromX + toX) / 2} 18 ${toX - 2} 7.5" fill="none" stroke="${STAFF_INK}" stroke-width="1.7"/>`;
+}
+function beamRect(left: number, top: number, right: number): string {
+  return `<rect x="${left.toFixed(2)}" y="${top}" width="${(right - left).toFixed(2)}" height="${BEAM_THICKNESS}" fill="${STAFF_INK}"/>`;
+}
+/** Beams over a group, drawn last so they sit over the stems: one beam across
+    the group, and a second only where both neighbours need it — a lone
+    sixteenth gets a stub. */
+function groupBeams(bar: Bar, xs: number[], group: { idx: number[] }): string {
+  const indices = group.idx;
+  const needsTwo = (k: number | undefined) => k != null && beamsFor(bar.ev[k].u) >= 2;
+  let out = beamRect(
+    stemLeft(xs[indices[0]]),
+    RHL.up,
+    xs[indices[indices.length - 1]] + STEMX + STEMW / 2,
+  );
+  indices.forEach((k, j) => {
+    if (!needsTwo(k)) {
+      return;
+    }
+    const prev = indices[j - 1];
+    const next = indices[j + 1];
+    const stemX = xs[k] + STEMX;
+    let left: number;
+    let right: number;
+    if (needsTwo(next)) {
+      left = stemX - STEMW / 2;
+      right = xs[next] + STEMX + STEMW / 2;
+    } else if (needsTwo(prev)) {
+      left = xs[prev] + STEMX - STEMW / 2;
+      right = stemX + STEMW / 2;
+    } else if (prev != null) {
+      left = stemX - STUB_BEAM;
+      right = stemX + STEMW / 2;
+    } else {
+      left = stemX - STEMW / 2;
+      right = stemX + STUB_BEAM;
+    }
+    out += beamRect(left, RHL.up + SECOND_BEAM_OFFSET, right);
+  });
+  return out;
+}
+/** The counting syllable under each attacked note. */
+function countingRow(bar: Bar, xs: number[]): string {
+  let out = '';
+  let at = 0;
+  bar.ev.forEach((event, i) => {
+    const tiedOnto = i > 0 && bar.ev[i - 1].tie;
+    if (!event.r && !tiedOnto) {
+      out += `<text x="${xs[i]}" y="32" text-anchor="middle" font-size="14" font-weight="600" font-family="${MONO}" fill="var(--ink-3)">${esc(countAt(bar, at))}</text>`;
+    }
+    at += event.u;
+  });
+  return out;
+}
+
+export function rhythmSVG(bar: Bar, options: RhythmOpts = {}): string {
+  const unitWidth = options.uw || RHL.uw;
+  const firstX = options.noTs ? X0_WITHOUT_TIME_SIG : RHL.x0;
+  const height = 100;
+  const xs = noteXs(bar, firstX, unitWidth);
+  const lastEvent = bar.ev[bar.ev.length - 1] || { u: 4 };
+  const endX = Math.max(
+    firstX + bar.u * unitWidth,
+    xs[xs.length - 1] + Math.max(unitWidth * lastEvent.u * 0.5, 14),
+  );
+  const width = endX + 18;
+  const parts: string[] = [];
+  parts.push(
+    `<line x1="0" y1="0" x2="${(width - 8).toFixed(1)}" y2="0" stroke="var(--staff-line)" stroke-width="1.4"/>`,
+  );
+  if (!options.noTs) {
+    parts.push(rhTimeSig(bar, 20));
+  }
+  parts.push(
+    `<rect x="${(width - 10).toFixed(1)}" y="-11" width="1.8" height="22" fill="${STAFF_INK}"/>`,
+  );
+  const groups = beamGroups(bar);
+  const beamed = new Set(groups.flatMap((group) => group.idx));
+
+  /* highlight, drawn first so it sits behind */
+  const picked = options.hi;
+  if (picked != null && picked >= 0 && picked < xs.length) {
+    parts.push(
+      `<rect x="${xs[picked] - 11}" y="-42" width="22" height="82" rx="6" fill="var(--accent)" opacity="0.16"/>`,
+    );
+  }
+
+  bar.ev.forEach((event, i) => {
+    const x = xs[i];
+    if (options.blank === i) {
+      parts.push(blankSlot(x));
+      return;
+    }
+    if (event.r) {
+      parts.push(rhRest(x, event.u));
+      return;
+    }
+    parts.push(noteGlyphs(x, event.u, beamed.has(i)));
+    if (event.tie && i + 1 < bar.ev.length) {
+      parts.push(tieCurve(x, xs[i + 1]));
+    }
+  });
+  groups.forEach((group) => parts.push(groupBeams(bar, xs, group)));
+  if (options.count) {
+    parts.push(countingRow(bar, xs));
+  }
+  const scale = options.scale || DEFAULT_SCALE;
+  return (
+    `<svg viewBox="-2 -48 ${width.toFixed(1)} ${height}" width="${Math.round(width * scale)}" height="${Math.round(height * scale)}" role="img" aria-label="rhythm in ${bar.ts.join(' ')}">` +
+    parts.join('') +
+    '</svg>'
+  );
+}
+
+/** A single value on its own, for the note-values drill. */
+export function rhOneSVG(sixteenths: number, rest: boolean, width?: number): string {
+  const centreX = 27;
+  const glyphs = rest ? rhRest(centreX, sixteenths) : noteGlyphs(centreX, sixteenths, false);
+  width = width || 88;
+  const label = rest ? restName(sixteenths) : rvalDef(sixteenths).n;
+  return (
+    `<svg viewBox="0 -46 56 80" width="${width}" height="${Math.round((width * 80) / 56)}" role="img" aria-label="${label}">` +
+    '<line x1="2" y1="0" x2="52" y2="0" stroke="var(--staff-line)" stroke-width="1.2"/>' +
+    glyphs +
+    '</svg>'
+  );
+}
+
+/** The numerals on their own, for the reference. */
+export function tsGlyphSVG(ts: TimeSig, height?: number): string {
+  height = height || 54;
+  return (
+    `<svg viewBox="-2 -22 26 44" width="${Math.round((height * 26) / 44)}" height="${height}" role="img" aria-label="${ts[0]} ${ts[1]} time">` +
+    gMid(('timeSig' + ts[0]) as GlyphName, 11, -11) +
+    gMid(('timeSig' + ts[1]) as GlyphName, 11, 11) +
+    '</svg>'
+  );
+}
+
+/** A picture of what you played against what was written. Written onsets stand
+    above the line, your taps below it, and every tap is drawn — including the
+    ones that landed nowhere near anything, which are the ones you most need to
+    see. The timeline runs a little past both ends of the bar so an early or
+    late tap has somewhere to be. */
+/** -1 if a time falls before the drawing, 1 if after it, 0 if inside. */
+function outsideSide(time: number, earliest: number, latest: number): -1 | 0 | 1 {
+  if (time < earliest) {
+    return -1;
+  }
+  return time > latest ? 1 : 0;
+}
+export function tapTimeline(
+  grade: TapGrade,
+  bar: Bar,
+  start: number,
+  secondsPerSixteenth: number,
+): string {
+  const duration = bar.u * secondsPerSixteenth;
+  const width = 300;
+  const height = 62;
+  /** how much of a bar is drawn each side */
+  const PAD = 0.18;
+  const xAt = (time: number) => (width * ((time - start) / duration + PAD)) / (1 + 2 * PAD);
+  const earliest = start - duration * PAD;
+  const latest = start + duration * (1 + PAD);
+  const vertical = (x: number, y1: number, y2: number, style: string) =>
+    `<line x1="${x.toFixed(1)}" y1="${y1}" x2="${x.toFixed(1)}" y2="${y2}" ${style}/>`;
+  const parts: string[] = [];
+  parts.push(
+    `<rect x="${xAt(start).toFixed(1)}" y="24" width="${(xAt(start + duration) - xAt(start)).toFixed(1)}" height="2" fill="var(--line)"/>`,
+  );
+  /* a tick on each beat. In compound time this ticks every three sixteenths,
+     which matches neither the eighth (2) nor the dotted-quarter beat (6) —
+     kept as the original drew it; noted in docs/ROADMAP.md as a likely bug */
+  const beatSixteenths = bar.cmp ? 3 : 4;
+  for (let beat = 0; beat <= bar.ts[0]; beat++) {
+    const beatTime = start + beat * beatSixteenths * secondsPerSixteenth;
+    if (beatTime <= start + duration + 1e-6) {
+      parts.push(vertical(xAt(beatTime), 16, 34, 'stroke="var(--line)" stroke-width="1.4"'));
+    }
+  }
+  grade.want.forEach((time, k) => {
+    const x = xAt(time);
+    const hit = grade.hits[k];
+    parts.push(vertical(x, 8, 25, 'stroke="var(--ink-3)" stroke-width="2"'));
+    if (hit.err != null) {
+      const colour = Math.abs(hit.err) < grade.tol * 0.5 ? 'var(--good)' : 'var(--mid)';
+      parts.push(vertical(xAt(time + hit.err), 25, 44, `stroke="${colour}" stroke-width="2.6"`));
+    } else {
+      parts.push(
+        `<circle cx="${x.toFixed(1)}" cy="36" r="3.2" fill="none" stroke="var(--bad)" stroke-width="1.6"/>`,
+      );
+    }
+  });
+  (grade.stray || []).forEach((time) => {
+    /* off the end of the drawing: park it at the edge with a chevron, so a tap
+       half a bar late still shows up rather than silently disappearing */
+    const side = outsideSide(time, earliest, latest);
+    const x = side === 0 ? xAt(time) : xAt(side < 0 ? earliest : latest);
+    parts.push(
+      vertical(x, 25, 44, 'stroke="var(--bad)" stroke-width="2.6" stroke-dasharray="3 2.4"'),
+    );
+    if (side) {
+      parts.push(
+        `<path d="M${(x + side * 2).toFixed(1)} 48 l${side * 5} 3.5 l${-side * 5} 3.5z" fill="var(--bad)"/>`,
+      );
+    }
+  });
+  /* width:100% with a fixed height attribute letterboxes the drawing into a
+     strip in the middle; letting the height follow the aspect ratio gives the
+     timeline the full width of the card, which is the whole point of it. */
+  return (
+    `<svg viewBox="-4 0 ${width + 8} ${height}" style="display:block;width:100%;height:auto" role="img" aria-label="your taps against the written rhythm">` +
+    parts.join('') +
+    '</svg>'
+  );
+}

package/src/lib/notation/staff.ts

@@ -0,0 +1,288 @@
+import type { Pref } from '../store/types';
+import { honmoon, mastery } from '../store/honmoon.svelte';
+import { GB, accPath, gMid, gPath, stemSVG } from './glyphs';
+import { STEP, noteName, pcOf } from '../music/notes';
+import { clefDef, enabledClefs, staffNotesFor, staffPos } from '../music/clefs';
+import { degPretty, noteText, scaleName, scaleNotes, type ScaleNote } from '../music/scales';
+import { esc } from '../util/text';
+import { masteryColour, monoLabel, staffLines } from './svg';
+
+/* ---------------- clefs + staff ----------------
+   A clef says which staff position its origin sits on: the F line for the F
+   clef, the G line for the G clef, and whichever line a C clef is centred on. */
+const CLEFG: Record<string, ['fClef' | 'gClef' | 'cClef', number]> = {
+  bass: ['fClef', 10],
+  treble: ['gClef', 30],
+  alto: ['cClef', 20],
+  tenor: ['cClef', 10],
+};
+/** Distance from the left edge of the staff to the clef. */
+const CLEF_X = 3;
+/** The staff's middle line: stems point away from it. */
+const MIDDLE_LINE_Y = 20;
+const BOTTOM_LINE_Y = 40;
+const LINE_GAP = 10;
+const ACCENT = 'var(--accent)';
+
+function clefGlyph(clef?: string) {
+  return CLEFG[clef || 'bass'] || CLEFG.bass;
+}
+export function clefSVG(clef?: string): string {
+  const [glyph, y] = clefGlyph(clef);
+  return gPath(glyph, CLEF_X, y);
+}
+/** How wide the clef glyph is, so notes never collide with it. */
+export function clefW(clef?: string): number {
+  return CLEF_X + GB[clefGlyph(clef)[0]][1];
+}
+function ledgerLine(y: number, noteX: number, halfWidth: number): string {
+  return `<line x1="${noteX - halfWidth}" y1="${y}" x2="${noteX + halfWidth}" y2="${y}" stroke="var(--staff-line)" stroke-width="1.3"/>`;
+}
+/** The ledger lines a note at height `y` needs, below or above the staff. */
+export function ledgersFor(y: number, noteX: number, halfWidth: number): string {
+  const out: string[] = [];
+  if (y > BOTTOM_LINE_Y) {
+    const lowest = Math.floor(y / LINE_GAP) * LINE_GAP;
+    for (let ledgerY = BOTTOM_LINE_Y + LINE_GAP; ledgerY <= lowest; ledgerY += LINE_GAP) {
+      out.push(ledgerLine(ledgerY, noteX, halfWidth));
+    }
+  }
+  if (y < 0) {
+    const highest = Math.ceil(y / LINE_GAP) * LINE_GAP;
+    for (let ledgerY = -LINE_GAP; ledgerY >= highest; ledgerY -= LINE_GAP) {
+      out.push(ledgerLine(ledgerY, noteX, halfWidth));
+    }
+  }
+  return out.join('');
+}
+/** A notehead with its ledger lines, stem and accidental, in one colour. */
+function noteWithStem(
+  noteX: number,
+  y: number,
+  alteration: number,
+  ledgerHalfWidth: number,
+  colour: string | null = null,
+): string {
+  return (
+    ledgersFor(y, noteX, ledgerHalfWidth) +
+    gMid('noteheadBlack', noteX, y, colour) +
+    stemSVG(noteX, y, MIDDLE_LINE_Y, colour) +
+    accPath(alteration, noteX, y, colour)
+  );
+}
+
+/** One note on a staff, for the reading drills. */
+export function staffSVG(writtenMidi: number, pref: Pref, clef = 'bass'): string {
+  clef = clef || 'bass';
+  const pos = staffPos(writtenMidi, pref, clef);
+  const noteX = 86;
+  const staffWidth = 120;
+  return (
+    `<svg viewBox="-2 -46 124 118" role="img" aria-label="note on the ${clef} staff">` +
+    clefSVG(clef) +
+    staffLines(staffWidth) +
+    noteWithStem(noteX, pos.y, pos.a, 12) +
+    '</svg>'
+  );
+}
+
+/* One staff carrying a run of notes, each labelled in both systems. */
+export const RUN = { x0: 52, dx: 44, H: 158, top: -48 };
+/** Room after the last note. */
+const RUN_END_MARGIN = 14;
+/** The run is drawn a quarter larger than its viewBox. */
+const RUN_SCALE = 1.25;
+export function runX0(clef: string): number {
+  return Math.max(RUN.x0, clefW(clef) + 14);
+}
+export function runWidth(noteCount: number, clef: string): number {
+  return runX0(clef) + noteCount * RUN.dx + RUN_END_MARGIN;
+}
+export function staffRunSVG(
+  midis: number[],
+  pref: Pref,
+  selected: number,
+  showLabels: boolean,
+  clef = 'bass',
+): string {
+  clef = clef || 'bass';
+  const firstX = runX0(clef);
+  const width = runWidth(midis.length, clef);
+  const selectedIndex = midis.indexOf(selected);
+  const parts = [clefSVG(clef)];
+  /* the selected column goes down first, so the staff lines stay drawn across it */
+  if (selectedIndex >= 0) {
+    const columnX = firstX + selectedIndex * RUN.dx - 19;
+    parts.push(
+      `<rect x="${columnX}" y="-40" width="38" height="140" rx="7" fill="${ACCENT}" opacity="0.14"/>`,
+    );
+  }
+  parts.push(staffLines(width - 6));
+  midis.forEach((midi, k) => {
+    const pos = staffPos(midi, pref, clef);
+    const noteX = firstX + k * RUN.dx;
+    const isSelected = selected === midi;
+    parts.push(noteWithStem(noteX, pos.y, pos.a, 11, isSelected ? ACCENT : null));
+    if (showLabels !== false) {
+      const letter = noteName(pcOf(midi), 'en', pref);
+      const syllable = noteName(pcOf(midi), 'solf', pref);
+      parts.push(monoLabel(noteX, 80, 15, isSelected ? ACCENT : 'var(--ink)', letter, true));
+      parts.push(monoLabel(noteX, 97, 13, 'var(--ink-3)', syllable));
+    }
+  });
+  const size = `width="${Math.round(width * RUN_SCALE)}" height="${Math.round(RUN.H * RUN_SCALE)}"`;
+  return (
+    `<svg viewBox="-2 ${RUN.top} ${width} ${RUN.H}" ${size} role="img" aria-label="notes on the ${clef} staff">` +
+    parts.join('') +
+    '</svg>'
+  );
+}
+
+/* ---------------- a scale on the staff, for the degree pages and drills ----
+   One octave on the bass staff, spelled by letter (so F major gets B♭ even
+   when you have sharps selected), with the letter and the degree written
+   under each note. `mark` lists semitone offsets to pick out. */
+
+/** A written octave for a root that keeps one octave of it on the bass staff
+    with no more than a ledger line or so either way: E2 up to D♯3. */
+export function degRootWritten(pc: number): number {
+  const lowestRoot = 40; // E2
+  let midi = 36 + pc; // C2 + pc
+  while (midi < lowestRoot) {
+    midi += 12;
+  }
+  return midi;
+}
+export interface DegStaffOpts {
+  /** 'both' (letters and degrees, the default), 'letters', or 'none' — a
+      reading question must not print its own answer underneath. */
+  labels?: 'both' | 'letters' | 'none';
+  alter?: { k: number; dir: number } | null;
+}
+/** The scale's notes up to and including the octave, with one note moved
+    when `alter` asks for it (for the spot-the-wrong-note drill). */
+function scaleWithOctave(
+  sid: string,
+  rootPc: number,
+  alter: { k: number; dir: number } | null | undefined,
+): ScaleNote[] {
+  const base = scaleNotes(sid, rootPc);
+  /* a few entries (root–fifth–octave) already list the octave themselves */
+  const notes: ScaleNote[] = base.some((note) => note.semis === 12)
+    ? base
+    : base.concat([{ semis: 12, pc: rootPc, deg: '8', l: base[0].l, a: base[0].a }]);
+  if (!alter) {
+    return notes;
+  }
+  return notes.map((note, k) =>
+    k !== alter.k
+      ? note
+      : {
+          semis: note.semis + alter.dir,
+          pc: pcOf(note.pc + alter.dir),
+          deg: '?',
+          l: note.l,
+          a: (note.a || 0) + alter.dir,
+          moved: true,
+        },
+  );
+}
+/** Height of the degree staff for each labelling: room for none, one or two rows. */
+const DEG_STAFF_HEIGHT = { none: 112, letters: 128, both: 150 };
+export function degStaffSVG(
+  sid: string,
+  rootPc: number,
+  rootWritten?: number | null,
+  mark?: number[] | null,
+  options: DegStaffOpts = {},
+): string {
+  const labels = options.labels || 'both';
+  const rootMidi = rootWritten ?? degRootWritten(rootPc);
+  const notes = scaleWithOctave(sid, rootPc, options.alter);
+  const clef = 'bass';
+  const bottomLineStep = clefDef(clef).bot;
+  /* A fixed width, wide enough for a seven-note scale and its octave. Sized
+     to the notes instead, a triad was drawn half again as large as a scale
+     beside it — and when three staves are offered side by side, the odd one
+     out by size is an answer given away. */
+  const firstX = clefW(clef) + 22;
+  const noteGap = 40;
+  const width = Math.max(firstX + notes.length * noteGap, firstX + 8 * noteGap);
+  const height = DEG_STAFF_HEIGHT[labels];
+  const parts = [clefSVG(clef), staffLines(width - 4)];
+  notes.forEach((note, k) => {
+    // the height comes from the letter, not the pitch: B♭ sits on the B line
+    const naturalMidi = rootMidi + note.semis - (note.a || 0);
+    const octave = Math.floor(naturalMidi / 12) - 1;
+    const diatonicIndex = octave * 7 + STEP[note.l];
+    const y = BOTTOM_LINE_Y - (diatonicIndex - bottomLineStep) * 5;
+    const noteX = firstX + k * noteGap;
+    const marked = !!mark && mark.includes(note.semis % 12) && note.semis < 12;
+    const colour = marked ? ACCENT : null;
+    if (marked) {
+      parts.push(
+        `<rect x="${noteX - 16}" y="-34" width="32" height="${height - 10}" rx="7" fill="${ACCENT}" opacity="0.13"/>`,
+      );
+    }
+    /* No natural sign on a moved note. These staves carry no key signature, so
+       a plain B already means B — and a natural sign would be the one mark no
+       real scale here ever shows, pointing straight at the wrong answer. */
+    parts.push(noteWithStem(noteX, y, note.a || 0, 11, colour));
+    if (labels !== 'none') {
+      parts.push(monoLabel(noteX, 80, 14, colour ?? 'var(--ink)', esc(noteText(note)), true));
+    }
+    if (labels === 'both') {
+      parts.push(monoLabel(noteX, 98, 13, colour ?? 'var(--ink-3)', degPretty(note.deg)));
+    }
+  });
+  const label =
+    labels === 'none'
+      ? 'a scale on the bass staff'
+      : esc(scaleName(sid, rootPc)) + ' with its degrees';
+  /* Scaled to the card rather than scrolled: a teaching picture whose last
+     note is hidden off to the right reads as a scale with a note missing. */
+  return (
+    `<div class="dfit"><svg viewBox="-2 -44 ${width + 4} ${height}" role="img" aria-label="${label}">` +
+    parts.join('') +
+    '</svg></div>'
+  );
+}
+
+/* ---------------- a staff heat map ----------------
+   The reading counterpart to the neck map. One notehead per note you can be
+   asked for on that clef, in pitch order, shaded by how solid it is. Pitch on
+   a staff is a vertical position, so the picture only means anything drawn on
+   a real staff — a row of squares would throw away the one thing the drill is
+   training. */
+const HST = { dx: 30, H: 152, top: -52 };
+const HEAT_SCALE = 1.1;
+export function heatStaffSVG(clef: string): string {
+  const pref = honmoon.settings.pref;
+  const notes = staffNotesFor(clef as never);
+  if (!notes.length) {
+    return '';
+  }
+  const firstX = Math.max(36, clefW(clef) + 14);
+  const width = firstX + notes.length * HST.dx + 12;
+  const parts = [clefSVG(clef), staffLines(width - 8)];
+  notes.forEach((note, k) => {
+    const pos = staffPos(note.m, pref, clef);
+    const noteX = firstX + k * HST.dx;
+    const card = honmoon.cards[note.id];
+    const fill =
+      !card || !card.s ? 'var(--line-2)' : masteryColour(mastery(note.id), 'var(--surface)');
+    parts.push(ledgersFor(pos.y, noteX, 10));
+    parts.push(gMid('noteheadBlack', noteX, pos.y, fill));
+    parts.push(accPath(pos.a, noteX, pos.y, fill));
+    parts.push(monoLabel(noteX, 80, 12, 'var(--ink-3)', esc(noteName(pcOf(note.m), 'en', pref))));
+  });
+  const size = `width="${Math.round(width * HEAT_SCALE)}" height="${Math.round(HST.H * HEAT_SCALE)}"`;
+  return (
+    `<svg viewBox="-2 ${HST.top} ${width} ${HST.H}" ${size} role="img" aria-label="how solid each note on the ${clef} staff is">` +
+    parts.join('') +
+    '</svg>'
+  );
+}
+export function heatStaffClefs(): string[] {
+  return enabledClefs();
+}

package/src/lib/notation/svg.ts

@@ -0,0 +1,37 @@
+/* Small builders for the SVG strings the notation code assembles. They
+   return markup as text; it ends up in the page through {@html}. */
+
+/** The five lines of a staff, 10 apart, from x = 0 to `width`. */
+export function staffLines(width: number): string {
+  let out = '';
+  for (let line = 0; line < 5; line++) {
+    out += `<line x1="0" y1="${line * 10}" x2="${width}" y2="${line * 10}" stroke="var(--staff-line)" stroke-width="1.1"/>`;
+  }
+  return out;
+}
+
+/** A monospace label centred on x. */
+export function monoLabel(
+  x: number,
+  y: number,
+  size: number,
+  fill: string,
+  text: string,
+  bold = false,
+): string {
+  const weight = bold ? ' font-weight="600"' : '';
+  return `<text x="${x}" y="${y}" text-anchor="middle" font-size="${size}"${weight} font-family="IBM Plex Mono,monospace" fill="${fill}">${text}</text>`;
+}
+
+/** The colour a mastery level is shown in on the heat maps: shaky (1 or less)
+    red, solid (5) green, and in between the "getting there" colour, mixed
+    stronger the higher the level, into the given background. */
+export function masteryColour(level: number, background: string): string {
+  if (level <= 1) {
+    return 'var(--bad)';
+  }
+  if (level < 5) {
+    return `color-mix(in srgb,var(--mid) ${40 + level * 12}%, ${background})`;
+  }
+  return 'var(--good)';
+}