moontide-mcp 2.0.2 → 2.2.0

package/page/jam-model.js

@@ -44,6 +44,8 @@ export const JAM_COPY = {
   heardLabel: 'Heard:',
   noFitDeclared: 'The notes fit none of the nine scales.',
   heardUnclearLabel: 'The heard scale is not clear.',
+  // The muted words after the Declared value of a piece with sections: the section whose harmony the line shows.
+  declaredSection: 'section {section}',
   declaredReasons: {
     'not-const': 'Not readable: harmony is declared with let or var; the page reads only const.',
     computed: 'Not readable: harmony is computed ({source}); the page reads only written text.',
@@ -61,8 +63,109 @@ export const JAM_COPY = {
     outside: { word: 'Outside', title: 'Chord note outside the scale, fine to play' },
     chord: { word: 'Chord tone', title: 'Note of the chord sounding now' },
   },
+  // The line that says why a scale is in use when several fit: a bold lead and a sentence that always names the scale and
+  // the reason. {scale} is the page's own name for it ('D Dorian'), {root} its spelled root ('D').
+  reason: {
+    proposedLead: 'Proposed:',
+    chosenLead: 'Your pick:',
+    section: ' {scale}, declared by the section.',
+    code: ' {scale}, declared by the code.',
+    'bass-chords': ' {scale}, the bass and chords lean on {root}.',
+    'most-heard': ' {scale}, {root} is the note heard most.',
+    nothing: ' {scale}, nothing in the notes says which scale is the key.',
+    chosen: ' {scale}. It holds while these same scales fit.',
+  },
+  // The scales that fit, listed under the scale in use: a caption, then one item per scale (buttons while one can be chosen,
+  // plain text when none can) and, past the eighth, the count of the rest.
+  candidates: {
+    pickCaption: 'Scales that fit, click to switch:',
+    listCaption: 'Scales that fit:',
+    more: 'and {n} more',
+  },
+  // The sentences an instrument's accessible name adds to its lead: where the scale in use comes from, the chord notes
+  // outside it, the notes of the chord sounding now, and why nothing is coloured when no scale can be chosen. The role words
+  // are the ones a piano key's hover title says.
+  instrument: {
+    proposedScale: 'Proposed scale: {scale}.',
+    chosenScale: 'Chosen scale: {scale}.',
+    outside: 'Outside: {notes}.',
+    chordTones: 'Chord tones: {notes}.',
+    cannotChoose: 'Several scales fit with different notes, so none is coloured.',
+  },
+  roleWords: { scale: 'scale', root: 'root', avoid: 'avoid', outside: 'outside', chord: 'chord tone' },
+  // Several scales fit with different notes and none can be used: the sentence for each cause, and the line under it.
+  cannotChoose: {
+    'nothing-declared': 'Several scales fit, with different notes, and nothing is declared.',
+    'declared-not-among': 'Several scales fit, with different notes, and none of them is the declared scale.',
+    sub: 'Warnings are off until a scale is declared or the notes settle on one.',
+  },
 };
 
+/**
+ * A sentence of the copy with each `{name}` replaced by its value in `values`. A placeholder with no value throws, so a
+ * sentence is never shown with a hole in it. The values are put in as plain text.
+ */
+export function fillJam(template, values) {
+  return template.replace(/\{(\w+)\}/g, (match, name) => {
+    if (!Object.hasOwn(values, name)) throw new Error(`Moontide: the Jam copy has no value for {${name}} in '${template}'`);
+    return String(values[name]);
+  });
+}
+
+/**
+ * The line that says why a scale is in use, `{ lead, rest }`, or null for a scale that was simply heard. A proposed scale
+ * reads 'Proposed:' and a sentence naming the scale and what decided (its reason code: 'declared' is the section's or the
+ * code's declaration, `section` being the section's words or null; 'bass-chords', 'most-heard' or 'nothing'); a scale the
+ * user picked reads 'Your pick:'. The word alone is never returned. An unknown source or reason throws.
+ */
+export function reasonLine(scale, { section = null } = {}) {
+  const source = scale.source ?? 'heard';
+  if (source === 'heard') return null;
+  const values = { scale: scale.name, root: scale.spell[scale.root] };
+  if (source === 'chosen') return { lead: JAM_COPY.reason.chosenLead, rest: fillJam(JAM_COPY.reason.chosen, values) };
+  if (source !== 'proposed') throw new Error(`Moontide: no reason line for a scale whose source is '${String(source)}'`);
+  const key = scale.reason === 'declared' ? (section === null || section === undefined ? 'code' : 'section') : scale.reason;
+  if (!['section', 'code', 'bass-chords', 'most-heard', 'nothing'].includes(key)) {
+    throw new Error(`Moontide: no reason line for the reason '${String(scale.reason)}'`);
+  }
+  return { lead: JAM_COPY.reason.proposedLead, rest: fillJam(JAM_COPY.reason[key], values) };
+}
+
+/** How many of the scales that fit are drawn as items; the rest are only counted. */
+export const MAX_CANDIDATES_SHOWN = 8;
+
+/**
+ * The list of the scales that fit, or null when no list is due. A scale that was heard (clear, no fit, none) has none. A
+ * proposed or chosen scale gives `mode: 'pick'` (buttons: the user can switch) and an unresolved one `mode: 'list'` (plain
+ * text: nothing can be chosen). `items` are the first MAX_CANDIDATES_SHOWN candidates in the order the resolver gave them
+ * (the order never changes with a pick), each `{ key, name, pressed }`; `pressed` is true only for the scale in use in pick
+ * mode, which takes the last place drawn when it comes later in the order. `more` says how many candidates are not drawn,
+ * or is null. `setKey` names the set of candidates a choice is made for.
+ */
+function candidatesOf(scale) {
+  const source = scale.source ?? 'heard';
+  if (source === 'heard') return null;
+  const pick = source === 'proposed' || source === 'chosen';
+  const all = scale.candidates;
+  if (!Array.isArray(all) || typeof scale.setKey !== 'string') {
+    throw new Error(`Moontide: the Jam model needs the candidates and the set key of a scale whose source is '${source}'`);
+  }
+  let shown = all.slice(0, MAX_CANDIDATES_SHOWN);
+  if (pick) {
+    const inUse = all.findIndex((candidate) => candidate.key === scale.key);
+    if (inUse === -1) throw new Error(`Moontide: the scale in use '${String(scale.key)}' is not among the candidates`);
+    if (inUse >= MAX_CANDIDATES_SHOWN) shown = [...all.slice(0, MAX_CANDIDATES_SHOWN - 1), all[inUse]];
+  }
+  const rest = all.length - shown.length;
+  return {
+    mode: pick ? 'pick' : 'list',
+    caption: pick ? JAM_COPY.candidates.pickCaption : JAM_COPY.candidates.listCaption,
+    setKey: scale.setKey,
+    items: shown.map((candidate) => ({ key: candidate.key, name: candidate.name, pressed: pick && candidate.key === scale.key })),
+    more: rest > 0 ? fillJam(JAM_COPY.candidates.more, { n: rest }) : null,
+  };
+}
+
 // --- the piano ---
 
 // The 14 white keys of two octaves and the pitch classes that have a black key to their right.
@@ -170,25 +273,56 @@ export function legendEntries(chordTones) {
   return roles.map((role) => ({ role, ...JAM_COPY.legend[role] }));
 }
 
+/**
+ * The hover title of one piano key: the spelled note and its role word ('D, root', 'C#, outside', 'B, scale'), with ', root'
+ * added for an avoided root and ', chord tone' for a chord tone. An 'off' key that is no chord tone has no title (''), and an
+ * 'off' chord tone reads 'F#, chord tone'. `names` are the position's spelled names, `chordPcs` the optional 12 chord-tone
+ * flags, `rootPc` the scale's root or null. The title only repeats what the marks and the instrument's name already say.
+ */
+export function keyTitle(key, roles, names, chordPcs = null, rootPc = null) {
+  const role = roles[key.pc];
+  const chord = chordPcs !== null && chordPcs[key.pc] === true;
+  if (role === 'off' && !chord) return '';
+  const words = [names[key.pc]];
+  if (role !== 'off') words.push(JAM_COPY.roleWords[role]);
+  if (role === 'avoid' && key.pc === rootPc) words.push(JAM_COPY.roleWords.root);
+  if (chord) words.push(JAM_COPY.roleWords.chord);
+  return words.join(', ');
+}
+
 /**
  * The accessible name of an instrument ('piano' or 'guitar'): 'Piano, two octaves from C3.' or
- * 'Guitar fretboard, standard tuning, 12 frets.' and then, with a clear scale,
- * 'Scale notes: D, E, F. Root D. Avoid: C.' ('Avoid: none.' when nothing is to be avoided), or 'No
- * clear scale.' The marks repeat in every octave, so the label names pitch classes. With `declared` (the
- * code declares a harmony) an unclear scale reads 'The heard scale is not clear.' instead, and a reading with no
- * pitched note reads the nothing-pitched sentence.
+ * 'Guitar fretboard, standard tuning, 12 frets.' and then, with a clear scale, in this order and each sentence only when it
+ * applies: 'Proposed scale: C major.' or 'Chosen scale: C major.' (none for a scale that was simply heard),
+ * 'Scale notes: D, E, F. Root D. Avoid: C.' ('Avoid: none.' when nothing is to be avoided), 'Outside: C#.' while the current
+ * warning has chord notes outside the scale. A scale that cannot be chosen reads that several scales fit with different notes,
+ * so none is coloured; no clear scale reads 'No clear scale.' The marks repeat in every octave, so the label names pitch
+ * classes. With `declared` (the code declares a harmony) an unclear scale reads 'The heard scale is not clear.' instead, and a
+ * reading with no pitched note reads the nothing-pitched sentence. With `chordTones` on and a chord sounding, 'Chord tones:
+ * D, F, A, C.' (from the bass up) comes last, in every state the overlay draws chord marks. A label with none of these facts is
+ * the label of a heard scale, unchanged.
  */
-export function instrumentLabel(kind, position, { declared = false } = {}) {
+export function instrumentLabel(kind, position, { declared = false, chordTones = false } = {}) {
   let lead;
   if (kind === 'piano') lead = 'Piano, two octaves from C3.';
   else if (kind === 'guitar') lead = 'Guitar fretboard, standard tuning, 12 frets.';
   else throw new Error(`Moontide: no accessible name for an instrument called '${String(kind)}'`);
+  const chordPart = chordTones && position.chord !== null ? ` ${fillJam(JAM_COPY.instrument.chordTones, { notes: position.chord.notes.join(', ') })}` : '';
   const scale = position.scale;
   // With a declaration the label never says 'No clear scale'; a reading with no pitched note has nothing heard to call unclear.
-  if (declared && scale.status === 'none') return `${lead} ${JAM_COPY.noPitched}`;
-  if (scale.status !== 'clear') return `${lead} ${declared ? JAM_COPY.heardUnclearLabel : 'No clear scale.'}`;
+  if (declared && scale.status === 'none') return `${lead} ${JAM_COPY.noPitched}${chordPart}`;
+  if (scale.status === 'ambiguous' && scale.source === 'unresolved') return `${lead} ${JAM_COPY.instrument.cannotChoose}${chordPart}`;
+  if (scale.status !== 'clear') return `${lead} ${declared ? JAM_COPY.heardUnclearLabel : 'No clear scale.'}${chordPart}`;
   const avoid = position.warning === null || position.warning.avoid.length === 0 ? 'none' : position.warning.avoid.join(', ');
-  return `${lead} Scale notes: ${scale.notes.map((note) => note.name).join(', ')}. Root ${scale.spell[scale.root]}. Avoid: ${avoid}.`;
+  const source =
+    scale.source === 'proposed' ? ` ${fillJam(JAM_COPY.instrument.proposedScale, { scale: scale.name })}`
+    : scale.source === 'chosen' ? ` ${fillJam(JAM_COPY.instrument.chosenScale, { scale: scale.name })}`
+    : '';
+  const outside =
+    position.warning !== null && position.warning.outside.length > 0
+      ? ` ${fillJam(JAM_COPY.instrument.outside, { notes: position.warning.outside.join(', ') })}`
+      : '';
+  return `${lead}${source} Scale notes: ${scale.notes.map((note) => note.name).join(', ')}. Root ${scale.spell[scale.root]}. Avoid: ${avoid}.${outside}${chordPart}`;
 }
 
 // The 12 chord-tone flags: the pitch classes of the chord sounding now while the overlay is on.
@@ -200,15 +334,15 @@ function chordFlags(position, chordTones) {
 
 // The instrument part of a ready model: roles and names by pitch class, the root, the chord
 // tones and the labels.
-function instrumentOf(position, chordPcs, declared) {
+function instrumentOf(position, chordPcs, declared, chordTones) {
   const clear = position.scale.status === 'clear';
   return {
     roles: rolesByPc(position),
     names: pcNames(position),
     rootPc: clear ? position.scale.root : null,
     chordPcs,
-    pianoLabel: instrumentLabel('piano', position, { declared }),
-    guitarLabel: instrumentLabel('guitar', position, { declared }),
+    pianoLabel: instrumentLabel('piano', position, { declared, chordTones }),
+    guitarLabel: instrumentLabel('guitar', position, { declared, chordTones }),
   };
 }
 
@@ -246,23 +380,14 @@ export function messageModel(text, sub = null) {
 }
 
 /**
- * The plain sentence for a scale that cannot be named: 'No clear scale: the notes fit C major and
- * A minor equally.' (two names joined by 'and', three as 'A, B and C', more as the first three then
- * 'and {N} more'; 'almost equally' for a near tie), or the no-fit sentence. With `declared` (the code
- * declares a harmony) the 'No clear scale: ' prefix is dropped and the sentence starts 'The notes fit'.
+ * The plain sentence for notes that fit none of the nine scales: 'No clear scale: the notes fit none of the nine scales.',
+ * or, with `declared` (the code declares a harmony), 'The notes fit none of the nine scales.' without the verdict prefix.
+ * Several scales that fit are never said here: the resolver (page/jam-resolve.js) uses one of them, or says why it cannot.
+ * Any other reading throws.
  */
 export function ambiguitySentence(scale, { declared = false } = {}) {
   if (scale.status === 'no-fit') return declared ? JAM_COPY.noFitDeclared : JAM_COPY.noFit;
-  if (scale.status !== 'ambiguous') {
-    throw new Error(`Moontide: no ambiguity sentence for a scale reading with status '${String(scale.status)}'`);
-  }
-  const names = scale.candidates.map((candidate) => candidate.name);
-  let list;
-  if (names.length <= 1) list = names.join('');
-  else if (names.length === 2) list = `${names[0]} and ${names[1]}`;
-  else if (names.length === 3) list = `${names[0]}, ${names[1]} and ${names[2]}`;
-  else list = `${names[0]}, ${names[1]}, ${names[2]} and ${names.length - 3} more`;
-  return `${declared ? 'The' : 'No clear scale: the'} notes fit ${list} ${scale.kind === 'near' ? 'almost equally' : 'equally'}.`;
+  throw new Error(`Moontide: no ambiguity sentence for a scale reading with status '${String(scale.status)}'`);
 }
 
 /** The longest declared text shown on the Declared line, in UTF-16 units; the title keeps the whole text. */
@@ -473,19 +598,37 @@ function statusOf(position, paused) {
  * (even an unreadable declaration) no sentence says 'No clear scale', and a reading with no pitched note is a ready
  * model of kind 'none' instead of the message model, so the Declared line stays on screen. The heard scale, the
  * degrees, the status, the rows and the instrument roles are the ones of the same notes without a declaration.
+ * The position comes from a resolved reading (page/jam-resolve.js resolveReading): when several scales fit, a proposed
+ * scale is a clear scale carrying its `source` ('proposed') and `reason`, and the model draws it like a heard one (kind 'clear',
+ * seven degrees, status, rows, roles, warnings on) and adds `reason` (`{ lead, rest }` of reasonLine, null for a heard scale) and
+ * `scaleSource` ('heard', 'proposed' or 'chosen'; 'heard' for none, no-fit and cannot-choose); scales with different notes that
+ * cannot be chosen give kind 'ambiguous', the sentence for their `why` and the sub-line that says warnings are off. An
+ * ambiguous scale with no `why` was never resolved and throws. A scale that was not heard (proposed, chosen or cannot be chosen)
+ * also gives `candidates`: `{ mode, caption, setKey, items, more }`, the list of the scales that fit (see candidatesOf; 'pick'
+ * mode for a scale in use, 'list' mode when none can be chosen), and null for a heard scale. A chosen scale reads 'Your pick:'.
+ * A piece with sections shows the harmony of the section that plays: `declaredOverride` (the same shapes as a reading's
+ * `declared`) replaces the one in the reading, and `section` is that section's name as the page shows it, quoted; every
+ * ready model carries `section`, the words 'section {name}' for a piece with sections and null otherwise.
  */
-export function buildJamModel({ position, chordTones = false }) {
-  const declaredState = position.reading.declared ?? { state: 'none' };
+export function buildJamModel({ position, chordTones = false, declaredOverride, section = null }) {
+  const declaredState = declaredOverride ?? position.reading.declared ?? { state: 'none' };
+  const sectionText = section === null || section === undefined ? null : JAM_COPY.declaredSection.replace('{section}', () => section);
   const declaredMode = declaredState.state !== 'none';
   const declared = declaredLine(declaredState);
   if (position.reading.status === 'none' && !declaredMode) {
     return messageModel(JAM_COPY.noPitched, JAM_COPY.noPitchedSub);
   }
   const scale = position.scale;
+  const scaleSource = scale.status === 'clear' ? (scale.source ?? 'heard') : 'heard';
+  if (!['heard', 'proposed', 'chosen'].includes(scaleSource)) {
+    throw new Error(`Moontide: the Jam model cannot draw a scale whose source is '${String(scaleSource)}'`);
+  }
+  const reason = scale.status === 'clear' ? reasonLine(scale, { section: sectionText }) : null;
+  const candidates = candidatesOf(scale);
   const paused = position.playing === false;
   const rows = rowsFor(position, paused);
   const chordPcs = chordFlags(position, chordTones);
-  const instrument = instrumentOf(position, chordPcs, declaredMode);
+  const instrument = instrumentOf(position, chordPcs, declaredMode, chordTones);
   const chordLine = chordTones ? chordLineText(position.chord) : null;
   // The scale a note context names: only a clear scale, never a guess.
   const noteScaleName = position.scale.status === 'clear' ? position.scale.name : null;
@@ -507,6 +650,10 @@ export function buildJamModel({ position, chordTones = false }) {
       chordLine,
       noteScaleName,
       declared,
+      section: sectionText,
+      reason,
+      scaleSource,
+      candidates,
     };
   }
   if (scale.status === 'clear') {
@@ -536,13 +683,27 @@ export function buildJamModel({ position, chordTones = false }) {
       chordLine,
       noteScaleName,
       declared,
+      section: sectionText,
+      reason,
+      scaleSource,
+      candidates,
     };
   }
   if (scale.status === 'ambiguous' || scale.status === 'no-fit') {
-    const sentence = ambiguitySentence(scale, { declared: declaredMode });
+    let sentence;
+    let sub = JAM_COPY.warningsOff;
+    if (scale.status === 'no-fit') {
+      sentence = ambiguitySentence(scale, { declared: declaredMode });
+    } else {
+      if (scale.why !== 'nothing-declared' && scale.why !== 'declared-not-among') {
+        throw new Error(`Moontide: the Jam model needs a resolved scale: several scales fit and the reading says no reason it cannot choose (why: '${String(scale.why)}')`);
+      }
+      sentence = JAM_COPY.cannotChoose[scale.why];
+      sub = JAM_COPY.cannotChoose.sub;
+    }
     return {
       state: 'ready',
-      scale: { kind: 'ambiguous', text: sentence, title: sentence, sub: JAM_COPY.warningsOff },
+      scale: { kind: 'ambiguous', text: sentence, title: sentence, sub },
       degrees: [],
       status: OFF_STATUS,
       paused,
@@ -551,6 +712,10 @@ export function buildJamModel({ position, chordTones = false }) {
       chordLine,
       noteScaleName,
       declared,
+      section: sectionText,
+      reason,
+      scaleSource,
+      candidates,
     };
   }
   throw new Error(`Moontide: the Jam model cannot draw a scale reading with status '${String(scale.status)}'`);

package/page/jam-resolve.js

@@ -0,0 +1,271 @@
+// Pure module for Moontide's browser page: decides which scale the Jam view uses when the heard notes fit several of
+// the nine. Several scales can hold the very same notes (C major, A minor and G Mixolydian are one set of seven notes),
+// and the view should help instead of switching its warnings off: it uses one of them, says why, and every path that
+// needs a clear scale (the piano and the guitar, the degree chips, the status, the coming-up rows, the notes and warnings
+// a right-click asks about) reads that one scale, resolved here. The warnings of every candidate were computed with the
+// reading (page/jam-analysis.js buildReading, `proposals`), so choosing among them is a lookup and never a new reading.
+//
+// The scale in use follows one fixed order, the first rule that applies:
+//   1. the user's pick, held for this exact set of candidates (source 'chosen');
+//   2. the declared scale of the playing section, or of the piece without sections, when it is among the candidates;
+//   3. the kept proposal, the one last chosen from the evidence for this same set, so near-equal readings do not make the
+//      proposal flicker (it applies to scales that share their notes only, and never over a declaration);
+//   4. the strongest evidence of the notes.
+// The kept proposal steadies only choices made from the evidence: a section that declares another scale among the same
+// candidates moves the proposal, because the declaration is what the code states. Picks and the kept proposal are held
+// per set of candidates in a small page memory (createScaleMemory) that holds no reading and no DOM; both are capped, and
+// gone when the page reloads. No DOM access at import time, so this module can be imported directly by node:test and by
+// page/main.js without a build step.
+
+import { MODES, scalePcs, clearScale } from './jam-analysis.js';
+
+/** Two evidence values closer than this are the same evidence. */
+const EVIDENCE_TOLERANCE = 1e-9;
+
+/** The reasons a proposal can give, in the words of the reason codes: what decided between the candidates. */
+export const REASONS = Object.freeze(['declared', 'bass-chords', 'most-heard', 'nothing']);
+
+/** Why a scale cannot be chosen: no declaration to break the tie, or a declared scale that is none of the candidates. */
+export const UNRESOLVED_REASONS = Object.freeze(['nothing-declared', 'declared-not-among']);
+
+function candidateKeyOf(candidate) {
+  if (candidate === null || typeof candidate !== 'object' || typeof candidate.key !== 'string') {
+    throw new Error(`Moontide: a candidate scale needs its key, got ${JSON.stringify(candidate)}`);
+  }
+  return candidate.key;
+}
+
+/**
+ * The key of a set of candidates: their keys (page/jam-analysis.js candidateKey) sorted as strings and joined by
+ * commas, so the same candidates in another order share one key.
+ */
+export function candidateSetKey(candidates) {
+  return candidates.map(candidateKeyOf).sort().join(',');
+}
+
+/** How many sets of candidates the page remembers a pick for, and a kept proposal for; the oldest is dropped first. */
+export const MAX_REMEMBERED_SETS = 32;
+
+const pcsKey = (candidate) => [...scalePcs(candidate.root, candidate.mode)].sort((a, b) => a - b).join(',');
+
+/** True when every candidate holds the same seven pitch classes as the first one. */
+export function sameNotes(candidates) {
+  if (candidates.length === 0) throw new Error('Moontide: no candidate scales to compare');
+  const first = pcsKey(candidates[0]);
+  return candidates.every((candidate) => pcsKey(candidate) === first);
+}
+
+/**
+ * Which evidence put `chosen` ahead of the other `candidates`: 'bass-chords' when the bass and the chord roots lean on
+ * its root more than on every other candidate's, else 'most-heard' when the weight of its root among the notes exceeds
+ * every other's, else 'nothing' (the evidence does not tell them apart). The evidence is the one the detection scored
+ * (`lean` and `heard` of each candidate); nothing new is added.
+ */
+export function evidenceReason(chosen, candidates) {
+  const others = candidates.filter((candidate) => candidateKeyOf(candidate) !== candidateKeyOf(chosen));
+  if (others.length === 0) return 'nothing';
+  if (others.every((other) => chosen.lean - other.lean > EVIDENCE_TOLERANCE)) return 'bass-chords';
+  if (others.every((other) => chosen.heard - other.heard > EVIDENCE_TOLERANCE)) return 'most-heard';
+  return 'nothing';
+}
+
+function declaredScaleOf(declared) {
+  if (declared === null || typeof declared !== 'object') {
+    throw new Error(`Moontide: resolving a scale needs the declared harmony, got ${String(declared)}`);
+  }
+  if (declared.state !== 'declared' || declared.scale === null || declared.scale === undefined) return null;
+  const { rootPc, modeId } = declared.scale;
+  if (!Number.isInteger(rootPc) || rootPc < 0 || rootPc > 11) {
+    throw new Error(`Moontide: a declared scale needs a root pitch class from 0 to 11, got ${String(rootPc)}`);
+  }
+  if (!MODES.some((mode) => mode.id === modeId)) {
+    throw new Error(`Moontide: no scale called '${String(modeId)}' among the nine the Jam view knows`);
+  }
+  return declared.scale;
+}
+
+function inputsOf(inputs) {
+  if (inputs === null || typeof inputs !== 'object' || !('declared' in inputs)) {
+    throw new Error('Moontide: resolving a scale needs its inputs, { declared } (the declared harmony of the playing section).');
+  }
+  return inputs;
+}
+
+const nonEmptyString = (value) => typeof value === 'string' && value !== '';
+
+function needString(value, what) {
+  if (!nonEmptyString(value)) throw new Error(`Moontide: the scale memory needs ${what} as a non-empty string, got ${JSON.stringify(value)}`);
+  return value;
+}
+
+/**
+ * The page's memory of the user's choices, `{ pick, pickFor, keep, keptFor, size }`; it holds keys only, never a reading and
+ * never a DOM node, and it lives in a variable of the page, so a reload forgets it.
+ * - `pick(setKey, key)` remembers that the user chose the candidate `key` while the set of candidates was `setKey`;
+ *   `pickFor(setKey)` gives it back, or null. Picks are kept in recency order and at most `cap` sets are remembered (the
+ *   oldest dropped first; picking an old set again makes it the newest), so a long session cannot grow the memory.
+ * - `keep(setKey, key)` records a proposal in view that came from the evidence for the set of candidates `setKey`;
+ *   `keptFor(setKey)` gives its key, or null. Kept proposals are held per set like picks, in recency order and at most
+ *   `cap` sets (the oldest dropped first), so going back to an earlier ambiguous span finds the proposal it had. A kept
+ *   proposal is not a pick and does not count in `size()`.
+ * A missing or empty argument throws a Moontide error.
+ */
+export function createScaleMemory({ cap = MAX_REMEMBERED_SETS } = {}) {
+  if (!Number.isInteger(cap) || cap < 1) throw new Error(`Moontide: the scale memory needs a cap of at least 1, got ${String(cap)}`);
+  const picks = new Map();
+  const kept = new Map();
+  return {
+    pick(setKey, key) {
+      needString(setKey, 'a set key');
+      needString(key, 'a scale key');
+      picks.delete(setKey);
+      picks.set(setKey, key);
+      while (picks.size > cap) picks.delete(picks.keys().next().value);
+    },
+    pickFor(setKey) {
+      needString(setKey, 'a set key');
+      return picks.get(setKey) ?? null;
+    },
+    keep(setKey, key) {
+      needString(setKey, 'a set key');
+      needString(key, 'a scale key');
+      kept.delete(setKey);
+      kept.set(setKey, key);
+      while (kept.size > cap) kept.delete(kept.keys().next().value);
+    },
+    keptFor(setKey) {
+      needString(setKey, 'a set key');
+      return kept.get(setKey) ?? null;
+    },
+    size: () => picks.size,
+  };
+}
+
+const HEARD = Object.freeze({ source: 'heard', key: null, reason: null, setKey: null, sameNotes: null, why: null });
+
+// A key held in memory must be one of the candidates it was looked up for (by the set key); anything else is a caller bug.
+function candidateOf(candidates, key, what) {
+  const hit = candidates.find((candidate) => candidate.key === key);
+  if (hit === undefined) throw new Error(`Moontide: the ${what} '${key}' is not one of the scales that fit now`);
+  return hit;
+}
+
+/**
+ * Which scale a detected `scale` stands for, as `{ source, key, reason, setKey, sameNotes, why }`. A clear, no-fit or
+ * none scale is the heard one (source 'heard', nothing else set). For an ambiguous scale `inputs` is `{ declared, pick,
+ * kept }`: `declared` is the harmony the code declares for what plays now (page/harmony.js: a declared scale is
+ * `{ rootPc, modeId }` or null), `pick` the key the user chose for this set of candidates (or null) and `kept` the key of
+ * the proposal in view that came from the evidence for this set (or null). The first rule that applies wins:
+ * - source 'chosen' (reason null): the user's `pick`, also when the candidates have different notes;
+ * - source 'proposed', reason 'declared': the declared scale is one of the candidates, matched on its root and mode (never
+ *   on its name text), also when the candidates have different notes;
+ * - source 'proposed': the candidates share their notes and `kept` is one of them, with the reason evidenceReason gives
+ *   for it; a kept key is never used for candidates with different notes;
+ * - source 'proposed': the candidates share their notes, so the first one (the detection puts the best evidence first) is
+ *   used, with the reason evidenceReason gives;
+ * - source 'unresolved': the candidates have different notes and nothing above names one of them; `why` is
+ *   'declared-not-among' when a declared scale exists and is none of the candidates, else 'nothing-declared' (no
+ *   declaration, a chords declaration, an unreadable one).
+ * `key` is the scale in use, `setKey` the key of the set of candidates (a memory of a choice hangs on it). A `pick` or
+ * `kept` that is not one of the candidates throws, as anything else a Moontide error can name.
+ */
+export function resolveScale(scale, inputs) {
+  if (scale === null || typeof scale !== 'object') throw new Error(`Moontide: cannot resolve ${String(scale)} as a scale`);
+  if (scale.status === 'clear' || scale.status === 'no-fit' || scale.status === 'none') return HEARD;
+  if (scale.status !== 'ambiguous') throw new Error(`Moontide: cannot resolve a scale reading with status '${String(scale.status)}'`);
+  const { declared, pick = null, kept = null } = inputsOf(inputs);
+  const declaredScale = declaredScaleOf(declared);
+  const { candidates } = scale;
+  const setKey = candidateSetKey(candidates);
+  const same = sameNotes(candidates);
+  if (pick !== null) candidateOf(candidates, pick, 'picked scale');
+  const keptCandidate = kept === null ? null : candidateOf(candidates, kept, 'kept scale');
+  if (pick !== null) return { source: 'chosen', key: pick, reason: null, setKey, sameNotes: same, why: null };
+  if (declaredScale !== null) {
+    const hit = candidates.find((candidate) => candidate.root === declaredScale.rootPc && candidate.mode.id === declaredScale.modeId);
+    if (hit !== undefined) return { source: 'proposed', key: hit.key, reason: 'declared', setKey, sameNotes: same, why: null };
+  }
+  if (same) {
+    const used = keptCandidate ?? candidates[0];
+    return { source: 'proposed', key: used.key, reason: evidenceReason(used, candidates), setKey, sameNotes: true, why: null };
+  }
+  return { source: 'unresolved', key: null, reason: null, setKey, sameNotes: false, why: declaredScale === null ? 'nothing-declared' : 'declared-not-among' };
+}
+
+// The names of a list of candidates, in the order the detection gave them (the best evidence first).
+const namesOf = (candidates) => candidates.map((candidate) => ({ key: candidate.key, name: candidate.name }));
+
+// A scale of the reading as the resolution says: the scale in use (proposed or chosen) as a clear scale with the fields the
+// model reads, the ambiguous scale with why it cannot be chosen, or the heard scale itself.
+function resolvedScale(scale, resolution) {
+  if (resolution.source === 'heard') return scale;
+  const { setKey, sameNotes: same } = resolution;
+  const candidates = namesOf(scale.candidates);
+  if (resolution.source === 'unresolved') {
+    return { ...scale, source: 'unresolved', why: resolution.why, setKey, sameNotes: same, candidates };
+  }
+  const hit = scale.candidates.find((candidate) => candidate.key === resolution.key);
+  return { ...clearScale(hit.root, hit.mode, hit.coverage), source: resolution.source, reason: resolution.reason, key: resolution.key, setKey, sameNotes: same, candidates };
+}
+
+function memoryOf(inputs) {
+  const { memory } = inputs;
+  if (memory === null || typeof memory !== 'object' || typeof memory.pickFor !== 'function' || typeof memory.keptFor !== 'function') {
+    throw new Error('Moontide: resolving a reading needs the scale memory, { declared, memory } (page/jam-resolve.js createScaleMemory).');
+  }
+  return memory;
+}
+
+// What a span's scale resolves to, with the pick and the kept proposal the memory holds for its set of candidates.
+function resolveWithMemory(scale, { declared }, memory) {
+  if (scale.status !== 'ambiguous') return resolveScale(scale, { declared });
+  const setKey = candidateSetKey(scale.candidates);
+  return resolveScale(scale, { declared, pick: memory.pickFor(setKey), kept: memory.keptFor(setKey) });
+}
+
+/**
+ * The reading with every scale resolved, as a new object (the reading given is never changed): what every path that needs
+ * a clear scale reads, `readingAt` first. `inputs` is `{ declared, memory }`, the declared harmony in effect at the playing
+ * position and the page memory (createScaleMemory) that holds the user's picks and the kept proposal. Each span whose scale
+ * is ambiguous resolves on its own scale with the pick and the kept proposal the memory holds for its set of candidates,
+ * so the whole window follows what plays now.
+ * - a proposed or chosen span gets its scale as the clear scale of the chosen candidate, plus `source`, `reason`, `key`,
+ *   `setKey`, `sameNotes` and `candidates` (`[{ key, name }]` in evidence order), and the warnings that candidate's proposal
+ *   computed;
+ * - an unresolved span keeps its ambiguous scale, plus `source: 'unresolved'`, `why`, `setKey`, `sameNotes` and
+ *   `candidates`, and has no warning;
+ * - a heard span is returned unchanged, and `whole` is resolved the same way (it carries no warnings);
+ * - `warnings` is rebuilt in begin order from the warnings of every span, each a copy with a fresh `index`, its
+ *   `spanIndex` and its `scaleName`. A resolved span's own `warnings` are the same copies; a heard span keeps its own list
+ *   as it was, and `warnings` of the reading is the list that holds the current indexes.
+ * A reading of a status other than 'ready' or 'none', or inputs without a memory, throws.
+ */
+export function resolveReading(reading, inputs) {
+  if (reading === null || typeof reading !== 'object' || (reading.status !== 'ready' && reading.status !== 'none')) {
+    throw new Error(`Moontide: cannot resolve a reading with status '${String(reading?.status)}'`);
+  }
+  inputsOf(inputs);
+  const memory = memoryOf(inputs);
+  const whole = resolvedScale(reading.whole, resolveWithMemory(reading.whole, inputs, memory));
+  const warnings = [];
+  const spans = reading.spans.map((span, spanIndex) => {
+    const resolution = resolveWithMemory(span.scale, inputs, memory);
+    const inUse = resolution.source === 'proposed' || resolution.source === 'chosen';
+    let resolved = span;
+    if (resolution.source !== 'heard') {
+      const scale = resolvedScale(span.scale, resolution);
+      const proposal = inUse ? span.proposals.find((entry) => entry.key === resolution.key) : undefined;
+      if (inUse && proposal === undefined) {
+        throw new Error(`Moontide: the reading has no proposal for the scale '${resolution.key}'`);
+      }
+      resolved = { ...span, scale, warnings: proposal === undefined ? [] : proposal.warnings };
+    }
+    const own = resolved.warnings.map((warning) => ({ ...warning, spanIndex, scaleName: resolved.scale.name }));
+    for (const warning of own) {
+      warning.index = warnings.length;
+      warnings.push(warning);
+    }
+    return inUse ? { ...resolved, warnings: own } : resolved;
+  });
+  return { ...reading, whole, spans, warnings };
+}