moontide-mcp 2.1.0 → 2.4.0

package/page/ask.js

@@ -1,11 +1,12 @@
 // Pure module for the Ask Claude box: the copy, the length rules, the context
-// descriptors, the box placement and the request status sequencing. No DOM access at import time,
+// descriptors and the box placement. No DOM access at import time,
 // so node:test and page/main.js import it directly with no build step. The box's own DOM lives in
 // page/ask-view.js.
 
 import { BEATS_PER_CYCLE } from './change-timing.js';
 import { MAX_MOMENT_NOTES, MAX_RANGE_CYCLES } from './timeline.js';
 import { cleanText } from './structure.js';
+import { GRIDS, MAX_CYCLES, MIN_CYCLES, MOTIF_SOURCES, assertPhraseCode, cyclesText, notesText } from './scratch-model.js';
 
 /** Mirrors src/protocol.ts's MAX_ASK_TEXT_LENGTH by hand (test/ask.test.js checks both are 2000). */
 export const MAX_ASK_TEXT_LENGTH = 2000;
@@ -13,6 +14,12 @@ export const MAX_ASK_TEXT_LENGTH = 2000;
 /** Mirrors src/protocol.ts's MAX_REQUEST_LINE_BYTES by hand (test/ask.test.js checks both are 8192). */
 export const MAX_REQUEST_LINE_BYTES = 8192;
 
+/**
+ * Mirrors src/protocol.ts's MAX_MOTIF_PHRASE_LENGTH by hand (test/ask.test.js checks both are 8000). The motif's sources, grid ids, cycle bounds and
+ * phrase shape come from page/scratch-model.js, which src/protocol.ts mirrors by hand (the same test checks them).
+ */
+export const MAX_MOTIF_PHRASE_LENGTH = 8000;
+
 /** Mirrors src/ask.ts's REQUEST_LINE_PREFIX by hand (test/ask.test.js checks both). */
 export const REQUEST_LINE_PREFIX = 'Request from the Moontide page:';
 
@@ -25,12 +32,6 @@ export const PAGE_TOKEN_PLACEHOLDER = '__MOONTIDE_PAGE_TOKEN__';
 /** No answer from the server within this long: the request is reported as not confirmed. */
 export const ASK_CONFIRM_TIMEOUT_MS = 5000;
 
-/** A non-error status stays readable at least this long before the next one replaces it. */
-export const STATUS_MIN_SHOWN_MS = 600;
-
-/** "Claude received it" is shown this long, then the status hides. */
-export const RECEIVED_SHOWN_MS = 4000;
-
 /** From this many characters the box shows a counter, so the limit is seen before it is hit. */
 export const COUNTER_FROM = 1800;
 
@@ -52,9 +53,6 @@ export const ASK_COPY = {
   disconnected: 'Disconnected — asking Claude is off until Moontide reconnects.',
   notSent: 'This request was not sent. Press Enter to try again.',
   notSentToken: 'This request was not sent.',
-  sent: 'Sent to Claude',
-  received: 'Claude received it',
-  waiting: 'Claude will see it on its next action',
   tooLong: 'request too long — 2000 characters at most.',
   lineTooLong: 'request too long to send — some characters take extra room, so shorten the text.',
   rateLimit: 'too many requests — wait a moment, then send again.',
@@ -121,33 +119,6 @@ export function pageRequestsText(live) {
   throw new Error(`Moontide: the page-requests state must be true or false, got ${JSON.stringify(live)}.`);
 }
 
-/** The status text for requests handed to Claude: one, or a count. */
-export function receivedText(count) {
-  return count === 1 ? ASK_COPY.received : `Claude received ${count} requests`;
-}
-
-/** The status text for requests that wait on the server: one, or a count. */
-export function waitingText(count) {
-  return count === 1 ? ASK_COPY.waiting : `Claude will see ${count} requests on its next action`;
-}
-
-/**
- * The short forms of the status texts, shown at fit step 3 of the top bar when the long
- * sentence no longer fits. They are made here, next to the long texts, and travel with them: nothing shortens a long
- * text by matching strings afterwards. The long text stays in the accessibility tree.
- */
-export const ASK_SHORT_COPY = Object.freeze({ sent: 'Sent', received: 'Received', waiting: 'Waiting' });
-
-/** The short form of receivedText(count). */
-export function receivedShortText(count) {
-  return count === 1 ? ASK_SHORT_COPY.received : `${count} received`;
-}
-
-/** The short form of waitingText(count). */
-export function waitingShortText(count) {
-  return count === 1 ? ASK_SHORT_COPY.waiting : `${count} waiting`;
-}
-
 /** 'empty' | 'too-long' | null for the text the user typed (counted on the trimmed text, in UTF-16 units,
  * the same count the server uses). */
 export function askTextProblem(text) {
@@ -190,8 +161,8 @@ export function askMessage({ connected, length, notSent, tokenRefused, lineTooLo
 
 /**
  * The Parts view's "Ask Claude to add sections" button: disabled while asking is off or its request is
- * pending, with the line under it saying why. `statusText` is the top-bar
- * status text of that request, or null.
+ * pending, with the line under it saying why. `statusText` is the state phrase of that request's row in the
+ * Requests list, or null.
  */
 export function partsAskState({ connected, pending, statusText }) {
   if (!connected) return { disabled: true, line: ASK_COPY.disconnected };
@@ -243,6 +214,28 @@ function optionalText(descriptor, field) {
   return cutText(value);
 }
 
+/**
+ * The section names of a range: undefined when the descriptor has none, else a list of 1 to MAX_RANGE_CYCLES non-empty strings
+ * (a range crosses at most one section per cycle). A name is not cut here.
+ */
+function rangeSectionNames(descriptor) {
+  const names = descriptor.sections;
+  if (names === undefined || names === null) return undefined;
+  if (!Array.isArray(names) || names.length < 1 || names.length > MAX_RANGE_CYCLES || names.some((name) => typeof name !== 'string' || name === '')) {
+    throw missing(descriptor.kind, `sections as 1 to ${MAX_RANGE_CYCLES} non-empty names`);
+  }
+  return names;
+}
+
+/** The count of sections a range leaves out: undefined when absent, else a whole number from 1 to MAX_RANGE_CYCLES - 1. */
+function rangeMoreSections(descriptor, names) {
+  const more = descriptor.moreSections;
+  if (more === undefined || more === null) return undefined;
+  if (names === undefined) throw missing(descriptor.kind, 'moreSections only with sections');
+  if (!Number.isInteger(more) || more < 1 || more > MAX_RANGE_CYCLES - 1) throw missing(descriptor.kind, `moreSections as a whole number from 1 to ${MAX_RANGE_CYCLES - 1}`);
+  return more;
+}
+
 function requiredInteger(descriptor, field, min) {
   const value = descriptor[field];
   if (!Number.isInteger(value) || value < min) throw missing(descriptor.kind, `a whole number ${field} of at least ${min}`);
@@ -393,14 +386,50 @@ function checkedMoment(kind, moment) {
   return { cycle: moment.cycle, beat: moment.beat, at: moment.at, version: moment.version, notes, more: moment.more };
 }
 
+/**
+ * A motif of a motif descriptor checked by the schema's rules (src/protocol.ts's askMotifShape) and copied field by field: the source, the cycle
+ * when there is one (a whole number of at least 0), the cycles, the grid, the notes count and the phrase, which must have the phrase shape. The
+ * phrase is never cut. A wrong value throws like every other context, so a bug is loud.
+ */
+function checkedMotif(motif) {
+  const bad = (field) => missing('motif', field);
+  if (motif === null || typeof motif !== 'object') throw bad('a motif');
+  const { source, cycle, cycles, grid, notes, phrase } = motif;
+  if (!MOTIF_SOURCES.includes(source)) throw bad(`a source of ${MOTIF_SOURCES.join(', ')}`);
+  if (cycle !== undefined && !isNonNegativeInteger(cycle)) throw bad('a whole number cycle of at least 0, or no cycle');
+  if (!Number.isInteger(cycles) || cycles < MIN_CYCLES || cycles > MAX_CYCLES) throw bad(`cycles as a whole number from ${MIN_CYCLES} to ${MAX_CYCLES}`);
+  if (!GRIDS.some((candidate) => candidate.id === grid)) throw bad(`a grid of ${GRIDS.map((candidate) => candidate.id).join(', ')}`);
+  if (!Number.isInteger(notes) || notes < 1) throw bad('a notes count of at least 1');
+  if (typeof phrase !== 'string' || phrase === '' || phrase.length > MAX_MOTIF_PHRASE_LENGTH) throw bad(`a phrase of 1 to ${MAX_MOTIF_PHRASE_LENGTH} characters`);
+  assertPhraseCode(phrase);
+  return { source, ...(cycle === undefined ? {} : { cycle }), cycles, grid, notes, phrase };
+}
+
+/**
+ * The chip of a motif context: the source, the cycles, the notes and, when there is a moment, its cycle, cut to the context limit. The
+ * motif is not checked here (describeContext checks it); the Ask view also uses this to measure the line of a motif it refuses.
+ */
+export function motifChip(motif) {
+  return cutText(`Motif${SEPARATOR}${motif.source}${SEPARATOR}${cyclesText(motif.cycles)}${SEPARATOR}${notesText(motif.notes)}${motif.cycle === undefined ? '' : `${SEPARATOR}at cycle ${motif.cycle}`}`);
+}
+
 /**
  * The size in bytes (UTF-8) of the line the server builds from one request: src/ask.ts's requestLine, the
  * prefix, a space and the JSON of the fields in the same order (U+2028 and U+2029 escaped), so the page can
  * tell before it sends whether the server will take the line.
  */
-export function requestLineBytes({ id, text, context, chip, current, moment, gesture }) {
-  // The moment, then the gesture, each only when there is one (the order of src/ask.ts's requestLine).
-  const fields = { id, text, context, chip, current, ...(moment === undefined ? {} : { moment }), ...(gesture === undefined ? {} : { gesture }) };
+export function requestLineBytes({ id, text, context, chip, current, moment, gesture, motif }) {
+  // The moment, then the gesture, then the motif, each only when there is one (the order of src/ask.ts's requestLine).
+  const fields = {
+    id,
+    text,
+    context,
+    chip,
+    current,
+    ...(moment === undefined ? {} : { moment }),
+    ...(gesture === undefined ? {} : { gesture }),
+    ...(motif === undefined ? {} : { motif }),
+  };
   const json = JSON.stringify(fields).replaceAll('\u2028', '\\u2028').replaceAll('\u2029', '\\u2029');
   return new TextEncoder().encode(`${REQUEST_LINE_PREFIX} ${json}`).length;
 }
@@ -465,6 +494,47 @@ function momentChipPart(moment) {
 /** The longest section name the chip of a range shows; the context carries the whole name (cut at the context limit). */
 const MAX_RANGE_CHIP_SECTION = 40;
 
+/** The words of the sections part of a range chip: one section, a list of them, and the sections the chip does not show. */
+const RANGE_SECTION_WORDS = Object.freeze({ one: 'section', list: 'sections', more: (n) => `and ${n} more` });
+
+/** The shortest lane part a range chip keeps, so the tail never takes its room: 'Range', the separator and one character. */
+const SHORTEST_RANGE_LANE_PART = `Range${SEPARATOR}x`;
+
+/**
+ * The section names of a range cut to what the context holds: names from the start while they and their ', ' separators stay
+ * within MAX_ASK_CONTEXT_LENGTH characters. The first name is always kept (cut with cutText when it is longer). Gives
+ * `{ names, more }` with `more` the count of names left out. The server rejects a longer list and never trims.
+ */
+export function fitSectionNames(names) {
+  if (names.length === 0) throw new Error('Moontide: a section list to fit needs at least one name');
+  const kept = [cutText(names[0])];
+  let length = kept[0].length;
+  for (let at = 1; at < names.length; at++) {
+    length += 2 + names[at].length;
+    if (length > MAX_ASK_CONTEXT_LENGTH) break;
+    kept.push(names[at]);
+  }
+  return { names: kept, more: names.length - kept.length };
+}
+
+/**
+ * The sections part of a range chip, built around `others` (the chip's other parts, as they will be joined): the most names
+ * that keep the tail within the room left after the shortest lane part, each cut to MAX_RANGE_CHIP_SECTION, and 'and N more' for
+ * every name not shown. `more` counts the names the context already leaves out. At least one name stays.
+ */
+function rangeSectionsPart(names, more, assemble) {
+  const total = names.length + more;
+  const room = MAX_ASK_CONTEXT_LENGTH - SEPARATOR.length - SHORTEST_RANGE_LANE_PART.length;
+  let part = '';
+  for (let shown = names.length; shown >= 1; shown--) {
+    const quoted = names.slice(0, shown).map((name) => `"${cutText(name, MAX_RANGE_CHIP_SECTION)}"`).join(', ');
+    const hidden = total - shown;
+    part = total === 1 ? `${RANGE_SECTION_WORDS.one} ${quoted}` : `${RANGE_SECTION_WORDS.list} ${quoted}${hidden > 0 ? ` ${RANGE_SECTION_WORDS.more(hidden)}` : ''}`;
+    if (assemble(part).length <= room) break;
+  }
+  return part;
+}
+
 /**
  * What a right-click pointed at, as the context the server receives and the chip the user sees.
  * `descriptor` is what a view reports about an element:
@@ -477,6 +547,8 @@ export function describeContext(descriptor) {
   const kind = descriptor && descriptor.kind;
   let moment = descriptor ? descriptor.moment : undefined;
   let gesture = descriptor ? descriptor.gesture : undefined;
+  let motif;
+  if (kind !== 'motif' && descriptor && descriptor.motif !== undefined) throw new Error(`Moontide: ask context ${kind} cannot carry a motif`);
   // A moment is the Timeline's facts at the pointer: a lane, a part header over the lanes and the rest of the
   // Timeline (a session descriptor) carry one; nothing else does.
   if (moment !== undefined && kind !== 'lane' && kind !== 'part' && kind !== 'session') throw new Error(`Moontide: ask context ${kind} cannot carry a moment`);
@@ -616,24 +688,29 @@ export function describeContext(descriptor) {
       const from = requiredInteger(descriptor, 'from', 0);
       const to = requiredInteger(descriptor, 'to', from);
       if (to - from >= MAX_RANGE_CYCLES) throw missing(kind, `at most ${MAX_RANGE_CYCLES} cycles`);
-      const section = optionalText(descriptor, 'section');
-      const sectionTo = optionalText(descriptor, 'sectionTo');
-      if (sectionTo !== undefined && (section === undefined || sectionTo === section)) throw missing(kind, 'a sectionTo only when it differs from the section');
+      const sections = rangeSectionNames(descriptor);
+      const moreSections = rangeMoreSections(descriptor, sections);
       if (gesture === undefined || gesture.kind !== 'range') throw missing(kind, 'a range gesture with its notes');
       gesture = checkedGesture(gesture);
       const cut = descriptor.cut === undefined || descriptor.cut === null ? null : { from: descriptor.cut.from, to: descriptor.cut.to };
       if (cut !== null) rangeCutText(cut);
       context = { kind, track, from, to };
-      if (section !== undefined) context.section = section;
-      if (sectionTo !== undefined) context.sectionTo = sectionTo;
+      let fitted;
+      if (sections !== undefined) {
+        // The page cuts the list to what the context holds; the cut and a cut the descriptor already made are one count.
+        fitted = fitSectionNames(sections);
+        const left = fitted.more + (moreSections ?? 0);
+        if (left > MAX_RANGE_CYCLES - 1) throw missing(kind, `at most ${MAX_RANGE_CYCLES - 1} moreSections`);
+        context.sections = fitted.names;
+        if (left > 0) context.moreSections = left;
+      }
       // The cycles, the section and the notes are built first and the lane name is cut to the room left, so a long name never
       // costs the cycles.
-      const parts = [from === to ? `cycle ${from}` : `cycles ${from} to ${to}`];
-      if (section !== undefined) {
-        const shown = (name) => `"${cutText(name, MAX_RANGE_CHIP_SECTION)}"`;
-        parts.push(sectionTo === undefined ? `section ${shown(section)}` : `sections ${shown(section)} to ${shown(sectionTo)}`);
-      }
-      parts.push(notesWords(gesture.notes.length + gesture.more));
+      const cycles = from === to ? `cycle ${from}` : `cycles ${from} to ${to}`;
+      const notes = notesWords(gesture.notes.length + gesture.more);
+      const parts = [cycles];
+      if (fitted !== undefined) parts.push(rangeSectionsPart(fitted.names, context.moreSections ?? 0, (part) => [cycles, part, notes].join(SEPARATOR)));
+      parts.push(notes);
       const tail = parts.join(SEPARATOR);
       chip = `${cutText(`Range${SEPARATOR}${track}`, MAX_ASK_CONTEXT_LENGTH - SEPARATOR.length - tail.length)}${SEPARATOR}${tail}`;
       return { context, chip: cutText(chip), gesture, ...(cut === null ? {} : { rangeCut: cut }) };
@@ -711,9 +788,17 @@ export function describeContext(descriptor) {
       chip = `Group "${name}"${parent === undefined ? '' : `${SEPARATOR}in "${parent}"`}`;
       break;
     }
+    case 'motif': {
+      // A motif sent from the Scratchpad: the context is only the kind, the motif rides next to it and carries its own moment.
+      motif = checkedMotif(descriptor.motif);
+      context = { kind };
+      chip = motifChip(motif);
+      break;
+    }
     default:
       throw new Error(`Moontide: unknown ask context kind ${kind}`);
   }
+
   // A gesture is about one note of a lane: it rides only on a lane that carries a moment (the range gesture is the range
   // context's own and is checked in its case above).
   if (gesture !== undefined) {
@@ -721,7 +806,7 @@ export function describeContext(descriptor) {
     gesture = checkedGesture(gesture);
     if (gesture.kind === 'range') throw new Error('Moontide: a range gesture goes only with a range context');
   }
-  return { context, chip: cutText(chip), ...(moment === undefined ? {} : { moment }), ...(gesture === undefined ? {} : { gesture }) };
+  return { context, chip: cutText(chip), ...(moment === undefined ? {} : { moment }), ...(gesture === undefined ? {} : { gesture }), ...(motif === undefined ? {} : { motif }) };
 }
 
 /**
@@ -838,118 +923,3 @@ export function placeBox({ pointerX, pointerY, boxWidth, boxHeight, maxBoxHeight
 export function newAskId(counter, nowMs) {
   return `ask-${nowMs.toString(36)}-${counter}`;
 }
-
-/**
- * The top-bar status of the latest request, as a small state machine with injected time (the
- * page/mixer-gesture.js style). `render(text, short)` receives a string or null and, with a string, its short form (the
- * second argument is left out when hiding). `onTimeout(id)` is called
- * for a request the server did not answer in time, or whose connection dropped.
- *
- * Every non-error text becomes visible no sooner than `minShownMs` after the previous non-error text
- * appeared (a later text is scheduled, never lost); hiding for an error or a refusal is immediate and
- * cancels anything scheduled.
- */
-export function createAskStatus({
-  render,
-  onTimeout,
-  setTimer,
-  clearTimer,
-  now,
-  minShownMs = STATUS_MIN_SHOWN_MS,
-  receivedShownMs = RECEIVED_SHOWN_MS,
-  confirmTimeoutMs = ASK_CONFIRM_TIMEOUT_MS,
-}) {
-  // The request the status describes.
-  let latestId = null;
-  // Requests sent and not yet answered: id -> confirm timer.
-  const unconfirmed = new Map();
-  // When the text on screen appeared; null while nothing shows.
-  let shownAt = null;
-  let scheduled = null;
-  let hideTimer = null;
-
-  function cancelScheduled() {
-    if (scheduled !== null) clearTimer(scheduled);
-    scheduled = null;
-  }
-
-  function cancelHide() {
-    if (hideTimer !== null) clearTimer(hideTimer);
-    hideTimer = null;
-  }
-
-  function hideNow() {
-    cancelScheduled();
-    cancelHide();
-    shownAt = null;
-    render(null);
-  }
-
-  function reveal(text, short, hideAfterMs) {
-    scheduled = null;
-    render(text, short);
-    shownAt = now();
-    if (hideAfterMs !== null) {
-      hideTimer = setTimer(() => {
-        hideTimer = null;
-        hideNow();
-      }, hideAfterMs);
-    }
-  }
-
-  /** Shows a non-error text now, or as soon as the text on screen has been readable long enough. */
-  function present(text, short, hideAfterMs) {
-    cancelScheduled();
-    cancelHide();
-    const wait = shownAt === null ? 0 : Math.max(0, minShownMs - (now() - shownAt));
-    if (wait === 0) {
-      reveal(text, short, hideAfterMs);
-    } else {
-      scheduled = setTimer(() => reveal(text, short, hideAfterMs), wait);
-    }
-  }
-
-  function forget(id) {
-    const timer = unconfirmed.get(id);
-    if (timer === undefined) return;
-    clearTimer(timer);
-    unconfirmed.delete(id);
-  }
-
-  function expire(id) {
-    unconfirmed.delete(id);
-    onTimeout(id);
-    if (id === latestId) hideNow();
-  }
-
-  return {
-    /** A request was sent: it becomes the latest and waits for the server's answer. */
-    sent(id) {
-      latestId = id;
-      unconfirmed.set(id, setTimer(() => expire(id), confirmTimeoutMs));
-      present(ASK_COPY.sent, ASK_SHORT_COPY.sent, null);
-    },
-    /** The server's ask-result for a request. */
-    answered(msg) {
-      forget(msg.id);
-      if (msg.id !== latestId) return;
-      if (msg.status === 'received') present(receivedText(1), receivedShortText(1), receivedShownMs);
-      else if (msg.status === 'waiting') present(waitingText(msg.waiting), waitingShortText(msg.waiting), null);
-      else hideNow();
-    },
-    /** The server's ask-received: waiting requests were just handed to Claude. */
-    handedOver(ids) {
-      for (const id of ids) forget(id);
-      if (latestId !== null && ids.includes(latestId)) present(receivedText(ids.length), receivedShortText(ids.length), receivedShownMs);
-    },
-    /** The connection is gone: nothing sent and unanswered will be answered any more. */
-    dropAll() {
-      for (const [id, timer] of unconfirmed) {
-        clearTimer(timer);
-        onTimeout(id);
-      }
-      unconfirmed.clear();
-      hideNow();
-    },
-  };
-}

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. */
@@ -30,6 +30,7 @@ export const BAR_COPY = Object.freeze({
   cardChange: 'Last change',
   rightClickHint: 'Right-click anything to ask Claude.',
   rightClickHintTitle: ASK_COPY.shiftRightClickTitle,
+  earlyNote: 'Early: Moontide is young and has known bugs.',
   midiHint: 'Instruments view: key 6.',
   settingsLabel: 'Your edits take over',
   timingNote: "Claude's changes say their own timing.",
@@ -60,6 +61,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 +226,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 +248,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 +263,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

@@ -144,6 +144,13 @@ export const CHANGE_COPY = Object.freeze({
   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
@@ -223,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/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>
@@ -62,6 +63,7 @@
         <span id="build-mismatch" class="bar-text" hidden></span>
         <span id="midi-takeover" class="bar-text" hidden><span id="midi-takeover-text"></span><button type="button" id="take-back"></button></span>
         <p class="session-hint" data-copy="rightClickHint"></p>
+        <p class="session-hint" data-copy="earlyNote"></p>
       </section>
       <section id="session-card-midi" class="session-card">
         <h2 class="session-card-title" data-copy="cardMidi"></h2>
@@ -85,6 +87,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>
@@ -104,8 +107,9 @@
       </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="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><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="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>
+      <div id="scratch-view" hidden role="region" aria-label="Scratchpad"><div id="scratch-controls" role="toolbar" aria-label="Scratchpad controls"><div id="scratch-grids" role="group" aria-label="Grid"><button type="button" id="scratch-grid-quarter" class="tl-btn" data-grid="quarter"></button><button type="button" id="scratch-grid-eighth" class="tl-btn" data-grid="eighth"></button><button type="button" id="scratch-grid-sixteenth" class="tl-btn" data-grid="sixteenth"></button><button type="button" id="scratch-grid-eighth-triplet" class="tl-btn" data-grid="eighth-triplet"></button><button type="button" id="scratch-grid-sixteenth-triplet" class="tl-btn" data-grid="sixteenth-triplet"></button></div><div id="scratch-length" role="group" aria-label="Length of the motif"><button type="button" id="scratch-fewer" class="tl-btn"></button><span id="scratch-cycles" class="sp-readout"></span><button type="button" id="scratch-more" class="tl-btn"></button></div><div id="scratch-pitch" role="group" aria-label="Pitch"><button type="button" id="scratch-lower" class="tl-btn"></button><span id="scratch-window" class="sp-readout" role="img"></span><button type="button" id="scratch-higher" class="tl-btn"></button></div><div id="scratch-mode" role="group" aria-label="Mode"><button type="button" id="scratch-draw" class="tl-btn" aria-pressed="false"></button><button type="button" id="scratch-tap" class="tl-btn" aria-pressed="false"></button></div><div id="scratch-edit" role="group" aria-label="Edit"><button type="button" id="scratch-earlier" class="tl-btn"></button><button type="button" id="scratch-later" class="tl-btn"></button><button type="button" id="scratch-align" class="tl-btn"></button><button type="button" id="scratch-clear" class="tl-btn"></button></div><div id="scratch-history" role="group" aria-label="Undo and redo"><button type="button" id="scratch-undo" class="tl-btn"></button><button type="button" id="scratch-redo" class="tl-btn"></button></div><div id="scratch-record-group" role="group" aria-label="Keyboard"><button type="button" id="scratch-record" class="tl-btn"></button></div><span id="scratch-early"></span></div><div id="scratch-scroll"><div id="scratch-ruler" aria-hidden="true"></div><div id="scratch-roll" tabindex="0" role="group" aria-label="Scratchpad piano roll" aria-describedby="scratch-hint"><div id="scratch-gutter" aria-hidden="true"></div><div id="scratch-grid"><div id="scratch-hover-cell" hidden></div><div id="scratch-select-rect" hidden aria-hidden="true"></div><div id="scratch-notes"></div><div id="scratch-live" aria-hidden="true"></div><div id="scratch-preview" hidden></div><div id="scratch-cursor" hidden></div><div id="scratch-now" hidden></div><div id="scratch-playhead" hidden aria-hidden="true"></div></div></div><div id="scratch-lane" tabindex="0" role="group" aria-label="Velocity of the notes" aria-describedby="scratch-hint"><div id="scratch-lane-label" aria-hidden="true"></div><div id="scratch-bars"></div></div></div><div id="scratch-note"><p id="scratch-note-line" role="status" aria-live="polite"><span id="scratch-note-shown" aria-hidden="true"><span id="scratch-note-name"></span><span id="scratch-note-rest"></span></span><span id="scratch-note-spoken"></span></p><p id="scratch-note-hover" hidden aria-hidden="true"></p><p id="scratch-hint"></p></div><div id="scratch-listen"><p id="scratch-listen-state" role="status" aria-live="polite"></p><button type="button" id="scratch-allow" class="tl-btn" hidden></button><p id="scratch-heard"></p></div><div id="scratch-play" role="group" aria-label="Hear the motif"><select id="scratch-play-output" aria-label="Instrument and channel"></select><div id="scratch-play-start" role="group" aria-label="Start"><button type="button" id="scratch-play-music" class="tl-btn" aria-pressed="true"></button><button type="button" id="scratch-play-now" class="tl-btn" aria-pressed="false"></button></div><button type="button" id="scratch-play-loop" class="tl-btn" aria-pressed="false"></button><button type="button" id="scratch-play-listen" class="tl-btn"></button><button type="button" id="scratch-play-stop" class="tl-btn"></button><p id="scratch-play-note" role="status" aria-live="polite"></p></div><div id="scratch-send"><code id="scratch-phrase" tabindex="0"></code><div id="scratch-send-row"><input type="text" id="scratch-words" autocomplete="off" spellcheck="false" /><button type="button" id="scratch-send-button" class="tl-btn"></button></div><p id="scratch-send-status" role="status" aria-live="polite"></p></div></div>
     </section>
   </div>
   <div id="ask-box" role="dialog" hidden><div id="ask-chips"><span id="ask-context-chip"></span><span id="ask-current-chip" hidden></span></div><textarea id="ask-field" rows="1" aria-describedby="ask-context-chip ask-hint"></textarea><p id="ask-message" hidden></p><p id="ask-hint"></p></div>