moontide-mcp 2.1.0 → 2.4.0

package/page/instruments-model.js

@@ -5,7 +5,7 @@
 // CONNECTION_LABELS (read at use time, so the popover, the top bar and this view never disagree). The DOM
 // side is page/instruments-view.js; page/main.js feeds the inputs.
 
-import { ACCESS_STATES, MIDI_COPY, fill, listNames, readMidiCalls } from './midi-plan.js';
+import { ACCESS_STATES, MIDI_COPY, fill, listNames, readMidiCalls, readMidiSetup } from './midi-plan.js';
 import { BUILD_MISMATCH_COPY, CONNECTION_LABELS } from './ui-state.js';
 import { midiTag, readMidiTracks } from './midi-controls.js';
 import { drumMapFor, soundKey } from './midi-rig.js';
@@ -59,6 +59,15 @@ export const INSTRUMENTS_COPY = Object.freeze({
   labelControlsHint: 'default values',
   labelCatalog: 'Catalog',
   labelInUse: 'In use',
+  // The Synth settings row of an instrument whose model describes settings: what the playing code writes, never stored.
+  labelSynthSettings: 'Synth settings',
+  synthTone: 'tone, ch {channel}: {values}',
+  synthPart: 'part, ch {channel}: {values}',
+  synthScene: 'scene: {values}, reaches every part',
+  synthValue: '{name} {value}',
+  synthValuesJoin: ', ',
+  synthNone: 'none in the code',
+  synthStays: 'A setting taken out of the code is not sent again: the instrument keeps its value until the instrument itself changes it, and a tone setting until the instrument loads the tone again. Moontide stores no setting.',
   clockFollows: 'follows the clock',
   controlsNone: 'none',
   catalogOne: '1 sound',
@@ -303,8 +312,9 @@ function readUse(code, parse, rig) {
   if (typeof parse !== 'function') return { kind: 'unreadable' };
   const tracks = readMidiTracks(code, { parse, rig });
   const calls = readMidiCalls(code, { parse });
-  if (!tracks.ok || !calls.ok) return { kind: 'unreadable' };
-  return { kind: 'read', tracks: [...tracks.tracks.values()], calls: calls.calls };
+  const setup = readMidiSetup(code, { parse });
+  if (!tracks.ok || !calls.ok || !setup.ok) return { kind: 'unreadable' };
+  return { kind: 'read', tracks: [...tracks.tracks.values()], calls: calls.calls, setups: setup.calls };
 }
 
 /**
@@ -337,6 +347,40 @@ function inUseOf(instrument, use) {
   return { lead: instrument.enabled === false ? INSTRUMENTS_COPY.silentWhileOff : null, lines, muted: false };
 }
 
+/**
+ * The Synth settings row of one instrument: null when its model describes no settings, else `{ lines: [{ text, muted }] }`
+ * read from the playing code. The lines are the tone and part settings per channel ascending (tone first), then the scene
+ * settings, taken from the calls whose port is exactly the instrument's port; the values stay in the order written and a
+ * later equal value merges. Without any, or without readable code, one muted line says so. The standing rule about a
+ * setting taken out of the code comes last. Nothing is stored: the row is the code.
+ */
+function synthSettingsOf(instrument, use) {
+  if (instrument.settings === null || instrument.settings === undefined) return null;
+  const staying = { text: INSTRUMENTS_COPY.synthStays, muted: true };
+  if (use.kind === 'unreadable') return { lines: [{ text: INSTRUMENTS_COPY.unreadableCode, muted: true }, staying] };
+  if (use.kind === 'empty') return { lines: [{ text: MIDI_COPY.rowNotUsed, muted: true }, staying] };
+  const channels = new Map();
+  const scene = new Map();
+  for (const call of use.setups) {
+    if (call.port !== instrument.port) continue;
+    if (!channels.has(call.channel)) channels.set(call.channel, { tone: new Map(), part: new Map() });
+    const level = channels.get(call.channel);
+    for (const [name, value] of call.settings.tone) level.tone.set(name, value);
+    for (const [name, value] of call.settings.part) level.part.set(name, value);
+    for (const [name, value] of call.settings.scene) scene.set(name, value);
+  }
+  const valuesOf = (map) => Array.from(map, ([name, value]) => fill(INSTRUMENTS_COPY.synthValue, { name, value: String(value) })).join(INSTRUMENTS_COPY.synthValuesJoin);
+  const lines = [];
+  for (const channel of [...channels.keys()].sort((a, b) => a - b)) {
+    const { tone, part } = channels.get(channel);
+    if (tone.size > 0) lines.push({ text: fill(INSTRUMENTS_COPY.synthTone, { channel: String(channel), values: valuesOf(tone) }), muted: false });
+    if (part.size > 0) lines.push({ text: fill(INSTRUMENTS_COPY.synthPart, { channel: String(channel), values: valuesOf(part) }), muted: false });
+  }
+  if (scene.size > 0) lines.push({ text: fill(INSTRUMENTS_COPY.synthScene, { values: valuesOf(scene) }), muted: false });
+  if (lines.length === 0) lines.push({ text: INSTRUMENTS_COPY.synthNone, muted: true });
+  return { lines: [...lines, staying] };
+}
+
 /** True when the instrument declares at least one channel with the rhythm role (the Drum kit row and Drum map line only exist then). */
 function hasRhythmChannel(instrument) {
   return instrument.channels.some((entry) => entry.role === 'rhythm');
@@ -558,6 +602,7 @@ function cardOf(instrument, liveInstruments, use) {
     modelChannels: modelChannelsOf(instrument),
     usedChannels: usedChannelsOf(instrument, use),
     inUse: inUseOf(instrument, use),
+    synthSettings: synthSettingsOf(instrument, use),
     drumKit: drumKitOf(instrument, use),
     drumMaps: drumMapsOf(instrument, use),
     drumDeclared: drumDeclaredOf(instrument),
@@ -717,6 +762,8 @@ function declaredFacts(card) {
     drumDeclared: card.drumDeclared,
     settings: card.settings,
     modelChannels: card.modelChannels,
+    // Whether the model describes settings decides whether the Synth settings row exists; its lines are live.
+    hasSynthSettings: card.synthSettings !== null,
   });
 }
 

package/page/instruments-view.js

@@ -208,6 +208,11 @@ export function createInstrumentsView({ document, onInstrumentSwitch, onInstrume
     return lines;
   }
 
+  /** The children of the Synth settings value: one line element per model line, the muted ones with the muted class. */
+  function synthSettingsLines(synthSettings) {
+    return synthSettings.lines.map((line) => element('span', line.muted ? 'instrument-inuse-line instrument-muted' : 'instrument-inuse-line', line.text));
+  }
+
   /** The lines of the Drum kit row: one span per line, muted when the model says so, with its hover title when it has one. */
   function drumKitLines(drumKit) {
     return drumKit.lines.map((line) => {
@@ -262,7 +267,7 @@ export function createInstrumentsView({ document, onInstrumentSwitch, onInstrume
 
   /** One card and the nodes a live redraw updates. The generated ids come from the index, never from user text. */
   function cardNode(card, index) {
-    const refs = { id: card.id, index, item: null, dot: null, words: null, inUse: null, drumKit: null, maps: null, opens: [], enabled: card.enabled, switchNodes: null, head: null, errorNode: null, editButton: null, editor: null };
+    const refs = { id: card.id, index, item: null, dot: null, words: null, inUse: null, synthSettings: null, drumKit: null, maps: null, opens: [], enabled: card.enabled, switchNodes: null, head: null, errorNode: null, editButton: null, editor: null };
     const item = element('li', 'instrument-card');
     refs.item = item;
     item.tabIndex = 0;
@@ -300,6 +305,12 @@ export function createInstrumentsView({ document, onInstrumentSwitch, onInstrume
     inUse.append(...inUseLines(card.inUse));
     refs.inUse = inUse;
     rows.append(row(INSTRUMENTS_COPY.labelInUse, inUse));
+    if (card.synthSettings !== null) {
+      const synth = element('div', 'instrument-lines');
+      synth.append(...synthSettingsLines(card.synthSettings));
+      refs.synthSettings = synth;
+      rows.append(row(INSTRUMENTS_COPY.labelSynthSettings, synth));
+    }
     item.append(head, rows, editButtonNode(card, refs));
     drawError(refs);
     // An editor that was open (a draft kept in memory) comes back with the card.
@@ -766,7 +777,7 @@ export function createInstrumentsView({ document, onInstrumentSwitch, onInstrume
     instrumentsBody.scrollTop = scrollTop;
   }
 
-  /** Updates the changed parts of each card in place: the dot, the state words, the Drum kit lines, the In use lines and the Drum map lines. */
+  /** Updates the changed parts of each card in place: the dot, the state words, the Drum kit lines, the In use lines, the Synth settings lines and the Drum map lines. */
   function updateCards(previous, model, skip = []) {
     model.cards.forEach((card, index) => {
       if (skip.includes(index)) return;
@@ -786,6 +797,7 @@ export function createInstrumentsView({ document, onInstrumentSwitch, onInstrume
       setText(refs.words, card.port.words);
       if (card.port.attention !== before.port.attention) refs.words.dataset.attention = String(card.port.attention);
       if (JSON.stringify(card.inUse) !== JSON.stringify(before.inUse)) refs.inUse.replaceChildren(...inUseLines(card.inUse));
+      if (card.synthSettings !== null && JSON.stringify(card.synthSettings) !== JSON.stringify(before.synthSettings)) refs.synthSettings.replaceChildren(...synthSettingsLines(card.synthSettings));
       if (card.drumKit !== null && JSON.stringify(card.drumKit) !== JSON.stringify(before.drumKit)) refs.drumKit.replaceChildren(...drumKitLines(card.drumKit));
       if (card.drumMaps !== null && JSON.stringify(card.drumMaps) !== JSON.stringify(before.drumMaps)) {
         // The drawn flags are read first and the focus noted, because the nodes are replaced: a map that stays keeps its state.

package/page/jam-analysis.js

@@ -376,15 +376,38 @@ export function warningsFor(solidSegments, scale) {
 
 // --- scale detection ---
 
+/** The key of a candidate scale: its root pitch class and its mode id, '9:aeolian' for A minor. */
+export const candidateKey = (root, mode) => `${root}:${mode.id}`;
+
+/**
+ * The clear shape of one scale: `{ status: 'clear', root, mode, name, spell, notes, coverage }`, notes being the
+ * seven `{ pc, name, degree }` in scale order from the root. detectScale returns it for a scale that stands alone,
+ * and every proposal of an ambiguous reading has it, so a scale in use reads the same wherever it came from.
+ */
+export function clearScale(root, mode, coverage) {
+  const spell = spellTable(root, mode);
+  return {
+    status: 'clear',
+    root,
+    mode,
+    name: scaleName(root, mode),
+    spell,
+    notes: scalePcs(root, mode).map((pc, i) => ({ pc, name: spell[pc], degree: mode.degrees[i] })),
+    coverage,
+  };
+}
+
 /**
  * Reads the scale of a set of pitched events (brief ones too). `harmonicSegments` (segments of
  * the half-cycle segmentation) add tonic evidence: bass notes of segments with at least two
  * notes and chord roots, weighted 2, 2 and 1 with all notes, renormalized over the components
  * that have evidence. Returns
- * - `{ status: 'clear', root, mode, name, spell, notes, coverage }`, notes being the seven
- *   `{ pc, name, degree }` in scale order from the root;
- * - `{ status: 'ambiguous', kind: 'tie' | 'near', candidates }`, candidates `{ root, mode, name, coverage }`
- *   in score order (a tie means the candidates cover the same weight, near that they do not);
+ * - `clearScale(root, mode, coverage)` for a scale that stands alone;
+ * - `{ status: 'ambiguous', kind: 'tie' | 'near', candidates }`, candidates `{ root, mode, name, coverage, key,
+ *   score, lean, heard }` in score order, the best evidence first (a tie means the candidates cover the same weight,
+ *   near that they do not). `score` is the coverage plus TONIC_BONUS times the tonic emphasis of the root, and
+ *   that emphasis is `lean` (the part from bass notes and chord roots) plus `heard` (the part from the weight of the
+ *   notes), so a reader can say which evidence put a candidate first;
  * - `{ status: 'no-fit' }` when no scale covers MIN_COVERAGE of the weight;
  * - `{ status: 'none' }` when no event has any duration.
  */
@@ -410,8 +433,14 @@ export function detectScale(events, harmonicSegments = []) {
     .filter((component) => component[2] > 0);
   const kSum = components.reduce((x, component) => x + component[1], 0);
   const tonic = new Array(12).fill(0);
+  const lean = new Array(12).fill(0);
+  const heard = new Array(12).fill(0);
   for (const [values, k, sum] of components) {
-    for (let pc = 0; pc < 12; pc++) tonic[pc] += (k / kSum) * (values[pc] / sum);
+    for (let pc = 0; pc < 12; pc++) {
+      const part = (k / kSum) * (values[pc] / sum);
+      tonic[pc] += part;
+      (values === weight ? heard : lean)[pc] += part;
+    }
   }
   const candidates = [];
   for (const mode of MODES) {
@@ -419,30 +448,28 @@ export function detectScale(events, harmonicSegments = []) {
       let inside = 0;
       for (const pc of scalePcs(root, mode)) inside += weight[pc];
       const coverage = inside / total;
-      candidates.push({ root, mode, coverage, score: coverage + TONIC_BONUS * tonic[root] });
+      candidates.push({ root, mode, coverage, score: coverage + TONIC_BONUS * tonic[root], lean: lean[root], heard: heard[root] });
     }
   }
   if (Math.max(...candidates.map((c) => c.coverage)) < MIN_COVERAGE) return { status: 'no-fit' };
   candidates.sort((a, b) => b.score - a.score || b.coverage - a.coverage || a.mode.parent - b.mode.parent);
   const top = candidates[0];
   const unresolved = candidates.filter((c) => top.score - c.score < CLEAR_GAP);
-  if (unresolved.length === 1) {
-    const spell = spellTable(top.root, top.mode);
-    return {
-      status: 'clear',
-      root: top.root,
-      mode: top.mode,
-      name: scaleName(top.root, top.mode),
-      spell,
-      notes: scalePcs(top.root, top.mode).map((pc, i) => ({ pc, name: spell[pc], degree: top.mode.degrees[i] })),
-      coverage: top.coverage,
-    };
-  }
+  if (unresolved.length === 1) return clearScale(top.root, top.mode, top.coverage);
   const tie = unresolved.every((c) => Math.abs(c.coverage - top.coverage) < 1e-9);
   return {
     status: 'ambiguous',
     kind: tie ? 'tie' : 'near',
-    candidates: unresolved.map((c) => ({ root: c.root, mode: c.mode, name: scaleName(c.root, c.mode), coverage: c.coverage })),
+    candidates: unresolved.map((c) => ({
+      root: c.root,
+      mode: c.mode,
+      name: scaleName(c.root, c.mode),
+      coverage: c.coverage,
+      key: candidateKey(c.root, c.mode),
+      score: c.score,
+      lean: c.lean,
+      heard: c.heard,
+    })),
   };
 }
 
@@ -482,7 +509,11 @@ function scaleOfPool(pool) {
  * Warnings are computed per span, from the solid segmentation of the events that begin in the
  * span, with the span's own scale and spelling (none when that scale is not clear). `warnings`
  * lists every span's warnings in begin order, each also carrying its `index` in that list, its
- * `spanIndex` and its `scaleName`. Each span also carries `harmonic`, the half-cycle segmentation of
+ * `spanIndex` and its `scaleName`. A span whose scale is ambiguous also carries `proposals`, one
+ * `{ key, scale, warnings }` for each candidate in candidate order: the candidate as a clear scale and
+ * the warnings that scale would have, computed once from the same segmentation, so choosing among the
+ * candidates later (page/jam-resolve.js) is a lookup and never a new reading; the base `warnings` stay empty
+ * for such a span. Every other span has `proposals: []`. Each span also carries `harmonic`, the half-cycle segmentation of
  * its own events, from which the chord sounding now is read. With two or more arrangements `partOwner` names the chosen
  * one the way the Parts view does (the owner track's name among `tracks`, else `arrange() N`).
  * `partial` (default false) says the window is shorter than the look-ahead because the page after
@@ -541,9 +572,23 @@ export function buildReading({ events, windowStart, windowLength, arrangements =
   const warnings = [];
   spans.forEach((span, spanIndex) => {
     span.harmonic = segments(markSolid(spanEvents[spanIndex].map((e) => ({ ...e })), HARMONIC_MIN), span.begin, span.end);
-    span.warnings =
-      span.scale.status === 'clear'
-        ? warningsFor(segments(markSolid(spanEvents[spanIndex].map((e) => ({ ...e })), BRIEF), span.begin, span.end), span.scale)
+    // One brief segmentation per span serves the span's own scale and, when it is ambiguous, every candidate.
+    const brief =
+      span.scale.status === 'clear' || span.scale.status === 'ambiguous'
+        ? segments(markSolid(spanEvents[spanIndex].map((e) => ({ ...e })), BRIEF), span.begin, span.end)
+        : null;
+    span.warnings = span.scale.status === 'clear' ? warningsFor(brief, span.scale) : [];
+    span.proposals =
+      span.scale.status === 'ambiguous'
+        ? span.scale.candidates.map((candidate) => {
+            const scale = clearScale(candidate.root, candidate.mode, candidate.coverage);
+            const proposed = warningsFor(brief, scale);
+            for (const warning of proposed) {
+              warning.spanIndex = spanIndex;
+              warning.scaleName = scale.name;
+            }
+            return { key: candidate.key, scale, warnings: proposed };
+          })
         : [];
     for (const warning of span.warnings) {
       warning.spanIndex = spanIndex;

package/page/jam-model.js

@@ -63,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.
@@ -172,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.
@@ -202,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 }),
   };
 }
 
@@ -248,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. */
@@ -475,6 +598,14 @@ 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.
@@ -488,10 +619,16 @@ export function buildJamModel({ position, chordTones = false, declaredOverride,
     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;
@@ -514,6 +651,9 @@ export function buildJamModel({ position, chordTones = false, declaredOverride,
       noteScaleName,
       declared,
       section: sectionText,
+      reason,
+      scaleSource,
+      candidates,
     };
   }
   if (scale.status === 'clear') {
@@ -544,13 +684,26 @@ export function buildJamModel({ position, chordTones = false, declaredOverride,
       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,
@@ -560,6 +713,9 @@ export function buildJamModel({ position, chordTones = false, declaredOverride,
       noteScaleName,
       declared,
       section: sectionText,
+      reason,
+      scaleSource,
+      candidates,
     };
   }
   throw new Error(`Moontide: the Jam model cannot draw a scale reading with status '${String(scale.status)}'`);