moontide-mcp 2.0.2 → 2.2.0

package/page/bar-model.js

@@ -6,7 +6,7 @@
 
 import { ASK_COPY } from './ask.js';
 import { MIDI_COPY } from './midi-plan.js';
-import { BEATS_PER_CYCLE, bpmText } from './change-timing.js';
+import { BEATS_PER_CYCLE, bpmText, fillChange } from './change-timing.js';
 import { BUILD_MISMATCH_COPY, CONNECTION_LABELS, SERVER_UPDATED_COPY, SOUND_LABELS, errorLineText } from './ui-state.js';
 
 /** The copy the bar and the Session drawer add. */
@@ -60,6 +60,13 @@ export const BAR_COPY = Object.freeze({
   tempoTitle: 'Tempo of the music that plays',
   tempoTitleIdle: 'Nothing plays',
   tempoNameIdle: 'No tempo, nothing plays',
+  // While a tempo ramp runs: the accessible name and the hover text say the direction, the target and the bars left.
+  tempoNameRising: 'Tempo {num} BPM, rising to {target} BPM',
+  tempoNameFalling: 'Tempo {num} BPM, falling to {target} BPM',
+  tempoTitleUp: 'Tempo moving up to {target} BPM. {left}',
+  tempoTitleDown: 'Tempo moving down to {target} BPM. {left}',
+  tempoBarsLeft: '{k} bars left.',
+  tempoOneBarLeft: '1 bar left.',
   // The failed-change banner: the lead of each kind, and the three sentences about the music. The first two
   // equal the server's NOTHING_PLAYING_TAIL and STILL_STOPPED_TAIL; the third is the user-facing wording of
   // STILL_PLAYING_TAIL ('The previous code is still playing.' stays the server's text for Claude). A test pins all three.
@@ -218,8 +225,15 @@ export function cycleBeat(now) {
  * the waiting tempo differs from the playing one after that rounding. Returns { idle, num, arrow, unit, text, name,
  * title }: `arrow` is '→ 124' or '', `unit` is 'BPM' (the view puts the spaces), `text` the whole line and `name`
  * the accessible name. A number bpmText cannot format throws; the caller logs it and shows the idle form.
+ *
+ * `ramp` is null or absent, or `{ targetBpm, barsLeft }` while a tempo ramp runs (`rising` is an optional true or false
+ * that says the direction when the live tempo already reads like the target). A ramp wins over `waitingBpm`. The number is then
+ * the live tempo rounded to a whole BPM (after bpmText has validated it), the arrow part is the target through bpmText
+ * and is empty when the number reads like the target, the name says 'rising to' or 'falling to' and the hover text says
+ * 'moving up' or 'moving down' with the whole bars left (a whole number from 1; '1 bar left.' for one). A call without
+ * a ramp returns exactly what it returned before the ramp existed. A bad ramp throws.
  */
-export function tempoText({ playing, bpm, waitingBpm }) {
+export function tempoText({ playing, bpm, waitingBpm, ramp }) {
   requireBoolean('playing', playing);
   if (!playing) {
     return {
@@ -233,6 +247,7 @@ export function tempoText({ playing, bpm, waitingBpm }) {
     };
   }
   const num = bpmText(bpm);
+  if (ramp !== null && ramp !== undefined) return rampTempoText(bpm, ramp);
   const hasWaiting = waitingBpm !== null && waitingBpm !== undefined;
   const waiting = hasWaiting ? bpmText(waitingBpm) : null;
   const changing = waiting !== null && waiting !== num;
@@ -247,6 +262,32 @@ export function tempoText({ playing, bpm, waitingBpm }) {
   };
 }
 
+/** The readout while a tempo ramp runs; `bpm` was validated by the caller. See tempoText. */
+function rampTempoText(bpm, ramp) {
+  if (typeof ramp !== 'object') {
+    throw new Error(`Moontide: the tempo ramp must be an object with targetBpm and barsLeft, got ${JSON.stringify(ramp)}.`);
+  }
+  const { targetBpm, barsLeft, rising } = ramp;
+  const target = bpmText(targetBpm);
+  if (!Number.isInteger(barsLeft) || barsLeft < 1) {
+    throw new Error(`Moontide: the bars left of a tempo ramp must be a whole number from 1, got ${JSON.stringify(barsLeft)}.`);
+  }
+  if (rising !== undefined) requireBoolean('rising', rising);
+  const num = String(Math.round(bpm));
+  const up = rising !== undefined ? rising : targetBpm > bpm;
+  const arrow = num === target ? '' : `${BAR_COPY.tempoArrow} ${target}`;
+  const left = barsLeft === 1 ? BAR_COPY.tempoOneBarLeft : fillChange(BAR_COPY.tempoBarsLeft, { k: barsLeft });
+  return {
+    idle: false,
+    num,
+    arrow,
+    unit: BAR_COPY.tempoUnit,
+    text: arrow === '' ? `${num} ${BAR_COPY.tempoUnit}` : `${num} ${arrow} ${BAR_COPY.tempoUnit}`,
+    name: fillChange(up ? BAR_COPY.tempoNameRising : BAR_COPY.tempoNameFalling, { num, target }),
+    title: fillChange(up ? BAR_COPY.tempoTitleUp : BAR_COPY.tempoTitleDown, { target, left }),
+  };
+}
+
 const BANNER_KINDS = Object.freeze(['change', 'notice']);
 
 /**

package/page/change-timing.js

@@ -76,6 +76,23 @@ export function bpmOf(cps) {
   return Math.round(cps * 60 * BEATS_PER_CYCLE * 10) / 10;
 }
 
+/**
+ * The timing of a change that must take over on one given line: a section launch writes a shift for that very line, so
+ * the takeover has to take the same one. `at` is 'section' (the end of the section that plays), 'bar' or 'phrase', and
+ * `atCycle` is the line, a finite cycle number. Returns a frozen { at, lineLength, atCycle }: `lineLength` (1 for a
+ * section end and a bar, the phrase length for a phrase) is the line the takeover falls back to when the pinned one has
+ * come too close. CHANGE_TIMINGS is not extended: it is the closed set of the stored setting and of the server's schema.
+ */
+export function pinnedTiming(at, atCycle) {
+  if (at !== 'section' && at !== 'bar' && at !== 'phrase') {
+    throw new Error(`Moontide: a pinned change timing is 'section', 'bar' or 'phrase', got '${String(at)}'.`);
+  }
+  if (typeof atCycle !== 'number' || !Number.isFinite(atCycle)) {
+    throw new Error(`Moontide: a pinned change timing needs a finite line, got ${String(atCycle)}.`);
+  }
+  return Object.freeze({ at, lineLength: at === 'phrase' ? DEFAULT_PHRASE_CYCLES : 1, atCycle });
+}
+
 /**
  * The cycle a timed change takes over on: the first multiple of `lineLength` strictly after the scheduler
  * frontier `frontier` (the cycle the scheduler has already queried up to), moved one line further while
@@ -111,6 +128,7 @@ export const CHANGE_COPY = Object.freeze({
   countdownOneBeat: 'in 1 beat',
   countdownTitleBar: 'A code change is waiting. It takes over on the next bar.',
   countdownTitlePhrase: 'A code change is waiting. It takes over on the next phrase.',
+  countdownTitleSection: 'A code change is waiting. It takes over at the end of the section.',
   // The Edits timing group of the Settings card: three buttons. The visible word of each, and its accessible name.
   timingNow: 'now',
   timingBar: 'next bar',
@@ -121,10 +139,18 @@ export const CHANGE_COPY = Object.freeze({
   timingTitle: "When your edits (Ctrl+Enter) take over: now, on the next bar or on the next phrase. Claude's changes choose their own timing.",
   queuedBar: 'Change waiting: it takes over on the next bar.',
   queuedPhrase: 'Change waiting: it takes over on the next phrase.',
+  queuedSection: 'Change waiting: it takes over at the end of the section.',
   canceled: 'Change canceled.',
   settingNow: 'Your edits now take over: now.',
   settingBar: 'Your edits now take over: on the next bar.',
   settingPhrase: 'Your edits now take over: on the next phrase.',
+  // The four sentences a tempo ramp speaks in the live region: at its start, at its end and when the code cancels it.
+  // {from}, {to} and {bpm} go through bpmText and {n} is a whole number of bars. Nothing is spoken per step.
+  rampStarted: 'Tempo ramp started: {from} to {to} BPM over {n} bars.',
+  rampStartedOneBar: 'Tempo ramp started: {from} to {to} BPM over 1 bar.',
+  rampFinished: 'Tempo ramp finished at {to} BPM.',
+  rampCanceledOtherTempo: 'Tempo ramp canceled. The code sets {bpm} BPM.',
+  rampCanceledNoTempo: 'Tempo ramp canceled. Tempo stays at {bpm} BPM.',
 });
 
 // The fit steps of the top bar, in the order text is given up: 0 nothing, 1 the decoration
@@ -167,11 +193,12 @@ export function countdownParts(beatsLeft) {
   return { lead, rest: CHANGE_COPY.countdownOneBeat };
 }
 
-/** The hover title of the countdown for a change waiting on 'bar' or 'phrase'. */
+/** The hover title of the countdown for a change waiting on 'bar', 'phrase' or (a section launch) 'section'. */
 export function countdownTitle(at) {
   if (at === 'bar') return CHANGE_COPY.countdownTitleBar;
   if (at === 'phrase') return CHANGE_COPY.countdownTitlePhrase;
-  throw new Error(`Moontide: a waiting change has the timing 'bar' or 'phrase', got '${String(at)}'.`);
+  if (at === 'section') return CHANGE_COPY.countdownTitleSection;
+  throw new Error(`Moontide: a waiting change has the timing 'bar', 'phrase' or 'section', got '${String(at)}'.`);
 }
 
 /**
@@ -188,11 +215,12 @@ export function timingOptions() {
   return CHANGE_TIMINGS.map((value) => Object.freeze({ value, label: copy[value][0], name: copy[value][1] }));
 }
 
-/** The spoken line for a change that just started to wait, for 'bar' or 'phrase'. */
+/** The spoken line for a change that just started to wait, for 'bar', 'phrase' or 'section'. */
 export function queuedLine(at) {
   if (at === 'bar') return CHANGE_COPY.queuedBar;
   if (at === 'phrase') return CHANGE_COPY.queuedPhrase;
-  throw new Error(`Moontide: a waiting change has the timing 'bar' or 'phrase', got '${String(at)}'.`);
+  if (at === 'section') return CHANGE_COPY.queuedSection;
+  throw new Error(`Moontide: a waiting change has the timing 'bar', 'phrase' or 'section', got '${String(at)}'.`);
 }
 
 /** The spoken line after a press of the setting button, for the value it now has. */
@@ -202,3 +230,31 @@ export function settingLine(value) {
   if (value === 'phrase') return CHANGE_COPY.settingPhrase;
   throw new Error(`Moontide: unknown change timing '${String(value)}' (expected one of ${CHANGE_TIMINGS.join(', ')}).`);
 }
+
+/**
+ * The spoken line of a tempo ramp, for the three events that are told: `{ kind: 'started', fromBpm, toBpm, bars }`,
+ * `{ kind: 'finished', toBpm }` and `{ kind: 'canceled', reason, bpm }` with the reason 'other-tempo' (the code states
+ * another tempo, which plays now) or 'no-tempo' (the code states none, the tempo stays). The tempos go through bpmText and
+ * `bars` is a whole number from 1; anything else throws a `Moontide:` Error. Stop, a reload and a replaced ramp are not told.
+ */
+export function rampLine(event) {
+  if (event === null || typeof event !== 'object') {
+    throw new Error(`Moontide: a ramp line needs an event, got ${String(event)}.`);
+  }
+  if (event.kind === 'started') {
+    if (!Number.isInteger(event.bars) || event.bars < 1) {
+      throw new Error(`Moontide: a ramp line needs a whole number of bars from 1, got ${String(event.bars)}.`);
+    }
+    const template = event.bars === 1 ? CHANGE_COPY.rampStartedOneBar : CHANGE_COPY.rampStarted;
+    return fillChange(template, { from: bpmText(event.fromBpm), to: bpmText(event.toBpm), n: event.bars });
+  }
+  if (event.kind === 'finished') {
+    return fillChange(CHANGE_COPY.rampFinished, { to: bpmText(event.toBpm) });
+  }
+  if (event.kind === 'canceled') {
+    if (event.reason === 'other-tempo') return fillChange(CHANGE_COPY.rampCanceledOtherTempo, { bpm: bpmText(event.bpm) });
+    if (event.reason === 'no-tempo') return fillChange(CHANGE_COPY.rampCanceledNoTempo, { bpm: bpmText(event.bpm) });
+    throw new Error(`Moontide: a canceled ramp is told for 'other-tempo' or 'no-tempo', not '${String(event.reason)}'.`);
+  }
+  throw new Error(`Moontide: a ramp line is told for 'started', 'finished' or 'canceled', not '${String(event.kind)}'.`);
+}

package/page/harmony.js

@@ -157,6 +157,19 @@ export function readHarmony(code, { parse }) {
   return { state: 'none' };
 }
 
+/**
+ * Reads one harmony text, as written in a section of a song or in a fixed variation: `{ kind: 'scale' | 'chords', scale }`
+ * with `scale` `{ rootPc, modeId }` only when the whole text is one scale token whose name is one of the nine scales (else
+ * null), or null when the text is neither a scale nor chords (nothing left to read, too long, a plain word). The same
+ * reading as a top-level declaration: readHarmony calls the same checks.
+ */
+export function readHarmonyText(text) {
+  if (text.length > MAX_HARMONY_TEXT) return null;
+  const found = classify(text);
+  if (found === null || found === 'empty') return null;
+  return { kind: found, scale: found === 'scale' ? scaleOf(text.trim()) : null };
+}
+
 function unreadable(reason, source = null) {
   return { state: 'unreadable', reason, source };
 }

package/page/index.html

@@ -47,9 +47,10 @@
       <span class="layout-word"></span>
       <div id="layout-buttons" role="group" aria-label="Layout"></div>
       <span class="bar-sep" aria-hidden="true"></span>
-      <span id="ask-status" role="status" aria-live="polite" hidden><span class="ask-long"></span><span class="ask-short" aria-hidden="true"></span></span>
+      <button type="button" id="requests-toggle" aria-expanded="false" aria-controls="requests-panel" hidden><span class="rq-word"></span><span class="rq-count" hidden></span></button>
       <button type="button" id="session-button" aria-expanded="false" aria-controls="session-drawer"><span class="session-label"></span><span id="session-count" hidden></span><span class="session-chevron" aria-hidden="true"></span></button>
     </header>
+    <div id="requests-panel" role="region" tabindex="-1" hidden></div>
     <div id="problem-banner" data-kind="change" tabindex="-1" hidden><span class="problem-lead"></span><span class="problem-consequence"></span><span id="eval-error" hidden></span><span class="problem-actions"><button type="button" id="problem-details-toggle" aria-expanded="false" aria-controls="problem-details"></button><button type="button" id="problem-copy"></button><button type="button" id="problem-ask" hidden></button><button type="button" id="problem-dismiss"></button></span><p id="problem-copy-failure" hidden></p><pre id="problem-details" hidden></pre></div>
     <div id="problem-alert" role="alert"></div>
     <div id="problem-menu" role="group" hidden><button type="button" id="problem-menu-copy"></button><button type="button" id="problem-menu-ask"></button><button type="button" id="problem-menu-dismiss"></button></div>
@@ -85,6 +86,7 @@
         <p class="session-hint session-empty" data-copy="noChange"></p>
       </section>
     </div>
+    <span id="requests-live" role="status" aria-live="polite"></span>
   </div>
   <div id="workspace">
     <main id="editor-area"><strudel-editor id="repl"></strudel-editor></main>
@@ -97,13 +99,14 @@
         <div id="timeline-body" hidden>
           <div id="timeline-ruler"></div>
           <div id="timeline-sections"></div>
-          <div id="timeline-lanes"></div>
+          <div id="timeline-lanes" tabindex="0" role="group" aria-label="Timeline notes"></div>
           <div id="timeline-playhead"><span class="playhead-cycle"></span></div>
         </div>
+        <section id="timeline-note" aria-label="Note" hidden><p id="timeline-note-line" role="status" aria-live="polite"></p></section>
       </div>
       <div id="mixer-view" hidden><p id="mixer-notice" hidden></p><p id="mixer-message" hidden></p><div id="mixer-body" hidden><div id="mixer-strips"></div><div id="mixer-inspector" hidden></div></div><p id="mixer-nonotes" hidden></p></div>
-      <div id="parts-view" hidden><p id="parts-message"></p><button type="button" id="parts-ask" hidden></button><p id="parts-ask-status" hidden></p><div id="parts-rows"></div></div>
-      <div id="jam-view" hidden><div id="jam-message" hidden><p id="jam-message-text"></p><p id="jam-message-sub" hidden></p></div><div id="jam-body" hidden><div id="jam-info"><p id="jam-declared" hidden><span id="jam-declared-label"></span><span id="jam-declared-value"></span></p><div id="jam-scale"><span id="jam-scale-label" hidden></span><h2 id="jam-scale-name"></h2><p id="jam-scale-sub"></p></div><div id="jam-degrees" role="list"></div><div id="jam-status" role="status" aria-live="polite" hidden><p id="jam-status-text"><strong id="jam-status-lead"></strong><span id="jam-status-rest"></span></p><span id="jam-status-time" aria-hidden="true"></span><span id="jam-status-spoken"></span></div><p id="jam-paused" hidden></p><div id="jam-coming"><p id="jam-coming-caption"></p><div id="jam-rows"></div></div></div><div id="jam-instrument"><div id="jam-controls"><div id="jam-instrument-switch" role="group"><button type="button" id="jam-instrument-piano">Piano</button><button type="button" id="jam-instrument-guitar">Guitar</button></div><label id="jam-chord-tones-label"><input type="checkbox" id="jam-chord-tones"> <span id="jam-chord-tones-text"></span></label><div id="jam-legend"><span id="jam-legend-chord" class="jam-legend-entry" hidden></span></div></div><p id="jam-chord" hidden></p><div id="jam-board"><div id="jam-piano" role="img"></div><div id="jam-guitar" role="img" hidden></div></div></div></div></div>
+      <div id="parts-view" hidden><p id="parts-message"></p><button type="button" id="parts-ask" hidden></button><p id="parts-ask-status" hidden></p><div id="song-notes" hidden></div><div id="song-bar" hidden><span id="song-launch-label"></span><div id="song-launch" role="group" aria-labelledby="song-launch-label"></div><p id="song-now" hidden></p></div><p id="song-line" hidden role="status" aria-live="polite"></p><div id="parts-rows"></div><div id="song-cell-list" hidden role="listbox" tabindex="-1"></div></div>
+      <div id="jam-view" hidden><div id="jam-message" hidden><p id="jam-message-text"></p><p id="jam-message-sub" hidden></p></div><div id="jam-body" hidden><div id="jam-info"><p id="jam-declared" hidden><span id="jam-declared-label"></span><span id="jam-declared-value"></span><span id="jam-declared-section" hidden></span></p><div id="jam-scale"><span id="jam-scale-label" hidden></span><h2 id="jam-scale-name"></h2><p id="jam-scale-sub"></p></div><p id="jam-reason" aria-live="polite" hidden><strong id="jam-reason-lead"></strong><span id="jam-reason-rest"></span></p><div id="jam-candidates" role="group" aria-labelledby="jam-candidates-label" hidden><span id="jam-candidates-label"></span><div id="jam-candidate-list"></div><span id="jam-candidates-more" hidden></span></div><div id="jam-degrees" role="list"></div><div id="jam-status" role="status" aria-live="polite" hidden><p id="jam-status-text"><strong id="jam-status-lead"></strong><span id="jam-status-rest"></span></p><span id="jam-status-time" aria-hidden="true"></span><span id="jam-status-spoken"></span></div><p id="jam-paused" hidden></p><div id="jam-coming"><p id="jam-coming-caption"></p><div id="jam-rows"></div></div></div><div id="jam-instrument"><div id="jam-controls"><div id="jam-instrument-switch" role="group"><button type="button" id="jam-instrument-piano">Piano</button><button type="button" id="jam-instrument-guitar">Guitar</button></div><label id="jam-chord-tones-label"><input type="checkbox" id="jam-chord-tones"> <span id="jam-chord-tones-text"></span></label><div id="jam-legend"><span id="jam-legend-chord" class="jam-legend-entry" hidden></span></div></div><p id="jam-chord" hidden></p><div id="jam-board"><div id="jam-piano" role="img"></div><div id="jam-guitar" role="img" hidden></div></div></div></div></div>
       <div id="instruments-view" hidden tabindex="-1"><p id="instruments-notice" hidden></p><div id="instruments-message" hidden><p id="instruments-message-text"></p><code id="instruments-folder" hidden></code><p id="instruments-message-sub" hidden></p><ul id="instruments-problems" hidden></ul><p id="instruments-message-closing" hidden></p></div><div id="instruments-body" hidden><ul id="instruments-list" role="list" aria-label="Instruments"></ul><p id="instruments-footer"></p></div><span id="instruments-status" role="status" aria-live="polite"></span></div>
     </section>
   </div>

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;