moontide-mcp 2.0.1 → 2.1.0

package/page/timeline-gesture.js

@@ -0,0 +1,279 @@
+// Pure module for Moontide's browser page: the numbers behind a pointer on the Timeline lanes. Distances are written in rem,
+// the unit the whole page is sized in; the caller multiplies them by the root font size it reads when the press starts, so a
+// larger window or a larger root makes the targets larger too. Where a note is drawn is worked out from the same shapes the
+// lanes are drawn from, so the note a press picks is the note the person sees. No DOM access and no timers here, so node:test
+// and page/main.js import the module without a build step.
+
+import { PAGE_CYCLES, cycleAt } from './timeline.js';
+
+/** A press that moves less than this is a click; a press that moves more is a drag. */
+export const DRAG_THRESHOLD_REM = 0.25;
+
+/** How far from a drawn note a press still counts as on it, in both directions. */
+export const HIT_TOLERANCE_REM = 0.5;
+
+/** The share of a lane's height a pitched note mark takes (a tick spans the whole height). */
+export const NOTE_MARK_HEIGHT = 0.14;
+
+/** How far a dragged note travels up or down for one semitone. A fixed step: it does not follow the lane's own pitch scale. */
+export const SEMITONE_REM = 0.5;
+
+/**
+ * Which gesture a press that has moved turns into, decided once and kept for the rest of the press: null while the pointer is
+ * still within `thresholdPx` of where it went down (it may yet be a click), then `'pitch'` or `'range'`. On a note the larger
+ * of the two travels wins (up or down is a pitch drag, sideways a range) and equal travel is a pitch drag; on empty lane area
+ * any travel is a range. `dx` and `dy` are the pointer's distance from the press, in pixels.
+ */
+export function lockGesture({ dx, dy, onNote, thresholdPx }) {
+  if (Math.hypot(dx, dy) < thresholdPx) return null;
+  if (!onNote) return 'range';
+  return Math.abs(dy) >= Math.abs(dx) ? 'pitch' : 'range';
+}
+
+/**
+ * The whole cycles a range drag covers: the cycle under the press and the cycle under the pointer, in either order, both
+ * included. `pageStart` is the first cycle of the page drawn, `pressFraction` and `pointerFraction` how far along the lane's event
+ * area the press and the pointer are (0 at its left edge, 1 at its right). Gives `{ from, to, cut }`. A pointer that left the
+ * event area (a fraction below 0 or above 1) is held at the page's first or last cycle, and `cut` is then `{ from, to }`, the
+ * cycles the range ended up with; otherwise `cut` is null. A range never leaves the page, so it never covers more than
+ * PAGE_CYCLES cycles.
+ */
+export function rangeCycles({ pageStart, pressFraction, pointerFraction }) {
+  for (const [name, value] of Object.entries({ pressFraction, pointerFraction })) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) throw new TypeError(`rangeCycles: ${name} must be a finite number, got ${String(value)}`);
+  }
+  const pressed = cycleAt({ pageStart, fraction: pressFraction });
+  const pointed = cycleAt({ pageStart, fraction: pointerFraction });
+  const from = Math.min(pressed, pointed);
+  const to = Math.max(pressed, pointed);
+  const left = pointerFraction < 0 || pointerFraction > 1;
+  return { from, to, cut: left ? { from, to } : null };
+}
+
+/**
+ * The whole semitones a pointer that moved `dy` pixels down (negative: up) stands for, `stepPx` pixels to a semitone. Up is
+ * higher, a part of a step counts for nothing, and no travel is 0, never negative zero.
+ */
+export function semitonesFrom({ dy, stepPx }) {
+  const semitones = Math.trunc(-dy / stepPx);
+  return semitones === 0 ? 0 : semitones;
+}
+
+/**
+ * One pixel box `{ left, top, right, bottom }` for each drawn note of a lane, in the order of `shapes`, and null for a tick
+ * (it has no pitch and is not picked). `rect` is the lane's event area in the page (`left`, `top`, `width`, `height`),
+ * `shapes` what the lane was drawn from (`{ kind, x, width, y }` for a normal lane, `{ x, width, row }` for a drum lane),
+ * `rowCount` the number of drum rows of a drum lane or null, `markHeight` the share of the lane height a mark takes.
+ */
+export function noteBoxes({ rect, shapes, rowCount, markHeight }) {
+  const perCycle = rect.width / PAGE_CYCLES;
+  return shapes.map((shape) => {
+    if (rowCount === null && shape.kind !== 'note') return null;
+    const left = rect.left + shape.x * perCycle;
+    let top;
+    let height;
+    if (rowCount === null) {
+      const y = Math.max(0, Math.min(1 - markHeight, shape.y - markHeight / 2));
+      top = rect.top + y * rect.height;
+      height = markHeight * rect.height;
+    } else {
+      top = rect.top + ((shape.row + 0.25) / rowCount) * rect.height;
+      height = (0.5 / rowCount) * rect.height;
+    }
+    return { left, top, right: left + shape.width * perCycle, bottom: top + height };
+  });
+}
+
+/** How far `at` is outside the span from `low` to `high` (0 inside it). */
+function outside(at, low, high) {
+  return Math.max(low - at, 0, at - high);
+}
+
+/**
+ * The index of the drawn note a press at (`x`, `y`) is on, or null on empty lane area. A note counts when the press is within
+ * `tolerancePx` of its box in both directions; of several the nearest wins, and equal distances go to the lower pitch
+ * (`pitches[i]` is the pitch of box i, null boxes are skipped).
+ */
+export function pickNote({ boxes, pitches, x, y, tolerancePx }) {
+  let best = null;
+  let bestDistance = Infinity;
+  for (let i = 0; i < boxes.length; i++) {
+    const box = boxes[i];
+    if (box === null) continue;
+    const dx = outside(x, box.left, box.right);
+    const dy = outside(y, box.top, box.bottom);
+    if (dx > tolerancePx || dy > tolerancePx) continue;
+    const distance = Math.hypot(dx, dy);
+    const nearer = distance < bestDistance - 1e-9;
+    const tied = Math.abs(distance - bestDistance) <= 1e-9 && best !== null && pitches[i] < pitches[best];
+    if (nearer || tied) {
+      best = i;
+      bestDistance = Math.min(distance, bestDistance);
+    }
+  }
+  return best;
+}
+
+/** How long the steps of a key or a button gather before the page writes them once, in milliseconds. */
+export const STEP_GATHER_MS = 600;
+
+function defaultStepError(error) {
+  console.error('Moontide: the steps of a Timeline note could not be written:', error);
+}
+
+/**
+ * Gathers the steps of one kind (pitch, velocity) into one write. `step(kind, amount)` adds `amount` (a whole number, negative
+ * for down) to the pending total of `kind` and starts the wait again; `delayMs` after the last step `onFlush(kind, total)`
+ * runs once. A step of another kind writes the pending one first and starts a burst of its own, so a burst only ever holds
+ * one kind and each kind is its own write. A total of 0 writes nothing. `drop()` forgets the pending steps without writing,
+ * `flush()` writes them now, `pending()` gives `{ kind, total }` or null. Once handed to `onFlush` a burst belongs to the
+ * caller: the gatherer never takes it back, and `onFlush` must not call `step`, `flush` or `drop` (that throws, and the
+ * error is reported through `onError`). Like the Mixer's recorder it has no timers of its own: `setTimer(fn, ms)` gives a
+ * handle for `clearTimer(handle)`, so node:test drives it with a fake clock. `onError(error)` hears an `onFlush` that threw,
+ * and the gatherer keeps working.
+ */
+export function createStepGatherer({ setTimer, clearTimer, delayMs = STEP_GATHER_MS, onFlush, onError = defaultStepError }) {
+  for (const [name, fn] of Object.entries({ setTimer, clearTimer, onFlush })) {
+    if (typeof fn !== 'function') throw new Error(`Moontide: the step gatherer needs ${name}, a function.`);
+  }
+  let open = null;
+  let timer = null;
+  // True while a burst is being handed to onFlush: the gatherer is not entered again from there.
+  let flushing = false;
+
+  function stopTimer() {
+    if (timer !== null) clearTimer(timer);
+    timer = null;
+  }
+
+  function notInFlush(name) {
+    if (flushing) throw new Error(`Moontide: the step gatherer's ${name} was called from inside its own flush.`);
+  }
+
+  function run(kind, total) {
+    if (total === 0) return;
+    flushing = true;
+    try {
+      onFlush(kind, total);
+    } catch (error) {
+      onError(error);
+    } finally {
+      flushing = false;
+    }
+  }
+
+  function flush() {
+    notInFlush('flush');
+    stopTimer();
+    const gathered = open;
+    open = null;
+    if (gathered !== null) run(gathered.kind, gathered.total);
+  }
+
+  return {
+    step(kind, amount) {
+      notInFlush('step');
+      if (typeof kind !== 'string' || kind === '') throw new Error('Moontide: a step has the kind it belongs to.');
+      if (!Number.isInteger(amount) || amount === 0) throw new Error(`Moontide: a step is a whole number other than 0, got ${String(amount)}.`);
+      if (open !== null && open.kind !== kind) flush();
+      if (open === null) open = { kind, total: 0 };
+      open.total += amount;
+      stopTimer();
+      timer = setTimer(() => {
+        timer = null;
+        flush();
+      }, delayMs);
+    },
+    drop() {
+      notInFlush('drop');
+      stopTimer();
+      open = null;
+    },
+    flush,
+    pending() {
+      return open === null ? null : { kind: open.kind, total: open.total };
+    },
+  };
+}
+
+/** The keys that move along a lane or across lanes. */
+export const LANE_KEYS = Object.freeze(['ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown']);
+
+/** The cycle a start time falls in (a start just under a whole cycle counts as that cycle, like the lanes' own cycle numbers). */
+function cycleOfStart(begin) {
+  return Math.floor(begin + 1e-9);
+}
+
+/**
+ * The notes of one lane in the order the keys walk them: by start, then pitch (lower first), then by position. `notes` has one
+ * entry for each drawn event, `{ begin, pitch }`, or null for an event the keys skip (a tick has no pitch and no mark to pick).
+ * Gives the positions in `notes`.
+ */
+function walkOrder(notes) {
+  const order = [];
+  notes.forEach((entry, index) => {
+    if (entry !== null) order.push(index);
+  });
+  order.sort((a, b) => notes[a].begin - notes[b].begin || (notes[a].pitch ?? -1) - (notes[b].pitch ?? -1) || a - b);
+  return order;
+}
+
+/**
+ * Where a key of the keyboard model takes the person on the Timeline's lanes. `lanes` holds the drawn lanes, each the list of its
+ * events as `{ begin, pitch }` (null for an event the keys skip); `at` is the current place or null: `{ laneIndex, eventIndex }`
+ * on a note, `{ laneIndex, eventIndex: null, cycle }` on the cursor of a lane that has no notes on the page. `key` is one of
+ * LANE_KEYS; any other key throws. The answer is `{ laneIndex, eventIndex, cycle }` (`eventIndex` null for the cursor, `cycle`
+ * the whole cycle of the note or the cursor), the same place when the key goes nowhere (the first or last note, the first or
+ * last lane), or null when the key does not apply: nothing to start from and no note anywhere, or a key that needs a place and
+ * has none (Home, End, Page Up and Page Down with nothing selected, so they scroll as they always did).
+ *
+ * Left and Right walk the lane by start and then pitch, and stop at its first and last note (the page does not turn). With no
+ * place Right takes the first note of the first lane that has one and Left the last note of that lane. Home and End take the
+ * first and the last note of the lane. Page Up and Page Down take the lane before and after, keeping the cycle: the note whose
+ * start is nearest in time (the earlier one when two are as near, then the lower pitch), or the cursor when that lane has no
+ * notes on the page.
+ */
+export function laneMove({ lanes, at, key }) {
+  if (!Array.isArray(lanes)) throw new TypeError('laneMove: lanes must be an array of lanes.');
+  if (!LANE_KEYS.includes(key)) throw new Error(`laneMove: unknown key '${String(key)}'.`);
+  const note = (laneIndex, eventIndex) => ({ laneIndex, eventIndex, cycle: cycleOfStart(lanes[laneIndex][eventIndex].begin) });
+  if (at === null || at === undefined) {
+    if (key !== 'ArrowLeft' && key !== 'ArrowRight') return null;
+    for (let laneIndex = 0; laneIndex < lanes.length; laneIndex++) {
+      const order = walkOrder(lanes[laneIndex]);
+      if (order.length > 0) return note(laneIndex, key === 'ArrowRight' ? order[0] : order[order.length - 1]);
+    }
+    return null;
+  }
+  const { laneIndex, eventIndex } = at;
+  if (!Number.isInteger(laneIndex) || laneIndex < 0 || laneIndex >= lanes.length) throw new RangeError(`laneMove: there is no lane ${String(laneIndex)}.`);
+  if (eventIndex === null) {
+    if (!Number.isInteger(at.cycle)) throw new TypeError('laneMove: the cursor of a lane without notes needs its cycle.');
+  } else if (lanes[laneIndex][eventIndex] === undefined || lanes[laneIndex][eventIndex] === null) {
+    throw new RangeError(`laneMove: lane ${laneIndex} has no note ${String(eventIndex)} to walk.`);
+  }
+  const here = eventIndex === null ? { laneIndex, eventIndex: null, cycle: at.cycle } : note(laneIndex, eventIndex);
+  if (key === 'PageUp' || key === 'PageDown') {
+    const target = Math.max(0, Math.min(lanes.length - 1, laneIndex + (key === 'PageDown' ? 1 : -1)));
+    if (target === laneIndex) return here;
+    const time = eventIndex === null ? at.cycle : lanes[laneIndex][eventIndex].begin;
+    let nearest = null;
+    let nearestGap = Infinity;
+    for (const index of walkOrder(lanes[target])) {
+      const gap = Math.abs(lanes[target][index].begin - time);
+      if (gap < nearestGap - 1e-9) {
+        nearest = index;
+        nearestGap = gap;
+      }
+    }
+    return nearest === null ? { laneIndex: target, eventIndex: null, cycle: eventIndex === null ? at.cycle : cycleOfStart(time) } : note(target, nearest);
+  }
+  // The cursor of a lane without notes has no note to walk along.
+  if (eventIndex === null) return here;
+  const order = walkOrder(lanes[laneIndex]);
+  const position = order.indexOf(eventIndex);
+  if (key === 'Home') return note(laneIndex, order[0]);
+  if (key === 'End') return note(laneIndex, order[order.length - 1]);
+  const next = Math.max(0, Math.min(order.length - 1, position + (key === 'ArrowRight' ? 1 : -1)));
+  return note(laneIndex, order[next]);
+}

package/page/timeline.js

@@ -33,6 +33,137 @@ export const TIMELINE_COPY = {
   drumNumbered: 'note {note}',
   drumMapUnknown: ' · drum map unknown',
   drumRowsMax: 8,
+  // The words of the note panel under the lanes: what it says about the selected note, what a change did and why a
+  // note cannot be edited. page/note-panel.js builds every sentence from these strings and nowhere else.
+  noteNone: 'No note selected',
+  noteEditable: 'Editable',
+  noteNotEditable: 'Not editable',
+  notePosition: ' · cycle {cycle}, beat {beat}',
+  noteSection: " · section '{section}'",
+  notePitchLabel: 'Pitch',
+  noteVelocityLabel: 'Velocity',
+  notePitchValue: '{note} · {midi}',
+  notePitchDrum: '{value} · {drum}',
+  noteVelocityUnknown: 'unknown',
+  notePitchDown: 'Pitch down',
+  notePitchDownName: 'Lower pitch by a semitone',
+  notePitchDownTitle: 'Lower pitch by a semitone (Down). Shift: an octave.',
+  notePitchUp: 'Pitch up',
+  notePitchUpName: 'Raise pitch by a semitone',
+  notePitchUpTitle: 'Raise pitch by a semitone (Up). Shift: an octave.',
+  noteVelocityDown: '−',
+  noteVelocityDownName: 'Lower velocity',
+  noteVelocityDownTitle: 'Lower velocity by 0.10',
+  noteVelocityUp: '+',
+  noteVelocityUpName: 'Raise velocity',
+  noteVelocityUpTitle: 'Raise velocity by 0.10',
+  noteVelocityFixed: 'fixed in the code',
+  noteMakeRest: 'Make a rest',
+  noteMakeRestName: 'Turn this note into a rest',
+  noteMakeRestTitle: 'Turn this note into a rest (Delete)',
+  noteAsk: 'Ask Claude',
+  noteAskName: 'Ask Claude about this note',
+  noteAskTitle: 'Opens the Ask box for this note.',
+  // What a gesture on a note the page cannot edit does: the sentence while it is dragged, and the one after it is released.
+  noteRefusedPreview: 'Release to ask Claude: {verb} this note by {amount}.',
+  noteRaise: 'raise',
+  noteLower: 'lower',
+  noteRequestReady: 'Request ready in the Ask box. Nothing is sent until you press Enter.',
+  noteHintNone: 'Click a note to edit it. Drag across an empty part of a lane to ask Claude about those cycles.',
+  noteHintEditable: 'Drag the note or press Up / Down: a semitone, with Shift an octave. Delete makes a rest. Each edit is one History entry.',
+  noteHintRefused: 'Up, Down, Make a rest, − and + prepare a request for Claude. Nothing is sent until you press Enter.',
+  noteHintRange: 'Press Enter or Ask Claude to ask about these cycles. Esc clears the range.',
+  // A range of cycles on one lane: the panel's identity line, built by page/note-panel.js, and what the Ask Claude button says then.
+  noteRangeWhere: 'Range · {lane}',
+  noteRangeCycles: ' · cycles {a} to {b}',
+  noteRangeCycle: ' · cycle {a}',
+  noteRangeSections: " · sections '{first}' to '{last}'",
+  noteRangeNotes: ' · {n} notes',
+  noteRangeOneNote: ' · 1 note',
+  noteRangeNoNotes: ' · no notes',
+  noteRangeAskName: 'Ask Claude about these cycles',
+  noteRangeAskTitle: 'Opens the Ask box for these cycles.',
+  // The keyboard cursor on a lane that has no note on the page: the panel's identity line, its hint and what Ask Claude says then.
+  noteCursorPosition: ' · no notes on this page',
+  noteHintCursor: 'Press Enter or Ask Claude to ask about this lane. Shift+Left or Shift+Right selects cycles.',
+  noteLaneAskName: 'Ask Claude about this lane',
+  noteLaneAskTitle: 'Opens the Ask box for this lane.',
+  // The name a screen reader gives the active note of the lanes (the lanes point at it with aria-activedescendant).
+  noteActiveName: '{lane}, cycle {cycle}, beat {beat}: note {note}, velocity {velocity}. {state}',
+  noteActiveEditable: 'Editable.',
+  noteActiveNotEditable: 'Not editable. {reason}',
+  noteActiveCursor: '{lane}, cycle {cycle}: no notes on this page.',
+  noteStanding: 'An edit rewrites one token in the code: {token}.',
+  // Where a token plays: the standing sentences, and the count the preview and the result repeat.
+  notePlaces: 'Plays in {n} places: sections {list}. An edit changes all of them.',
+  notePlacesOnPage:
+    'Plays in {n} places on this page: sections {list}. An edit changes every place it plays, on this page and after it.',
+  notePlacesPerCycle: 'This token draws {n} notes in each cycle. An edit changes all of them.',
+  notePlacesWords: ' in {n} places',
+  notePlacesPageWords: ' in {n} places on this page',
+  noteVelocityNotes: ', for {n} notes on this page',
+  noteVelocityNotesShort: ', for {n} notes',
+  noteSectionName: "'{name}'",
+  noteListAnd: '{first} and {last}',
+  noteListMore: '{first} and {n} more',
+  // The steps of a key or a button that were not written because the note they were aimed at is gone.
+  noteStepsDropped: 'The steps you pressed were not written: the note changed in the code. Select it again.',
+  noteStepsNotWritten: 'The steps you pressed were not written. Select the note and press them again.',
+  noteChangeDropped: 'The change was not written: the note changed in the code. Select it again.',
+  noteChangeNotWritten: 'The change you made was not written. Select the note and make it again.',
+  noteEditTimeout: 'The page did not answer this edit in time, so check the code.',
+  noteNamed: '{note} on {lane}: {text}',
+  noteChanged: 'Changed {from} to {to}{places}.',
+  noteChangedRest: 'Changed {from} to a rest{places}.',
+  noteVelocityNow: 'Velocity of {note} is now {v}{places}{notes}.',
+  noteWaitingBar: 'Waiting for the next bar — {from} becomes {to}.',
+  noteWaitingPhrase: 'Waiting for the next phrase — {from} becomes {to}.',
+  noteWaitingBarRest: 'Waiting for the next bar — {from} becomes a rest.',
+  noteWaitingPhraseRest: 'Waiting for the next phrase — {from} becomes a rest.',
+  noteWaitingBarVelocity: 'Waiting for the next bar — {note} velocity becomes {v}.',
+  noteWaitingPhraseVelocity: 'Waiting for the next phrase — {note} velocity becomes {v}.',
+  // The sentence while a note is dragged, and the size of the change in it.
+  notePreview: '{from} → {to} ({delta}){places}. Release to write.',
+  noteDeltaSemitone: '{sign}1 semitone',
+  noteDeltaSemitones: '{sign}{n} semitones',
+  noteDeltaOctave: '{sign}1 octave',
+  noteDeltaOctaves: '{sign}{n} octaves',
+  // The sentence while steps of a key or a button wait for the pause before they are written.
+  noteStepPreview: '{from} → {to} ({delta}){places}. Writing in a moment.',
+  noteVelocityPreview: 'Velocity {from} → {to}{places}{notes}. Writing in a moment.',
+  noteLowest: 'Already the lowest note.',
+  noteHighest: 'Already the highest note.',
+  noteVelocityLowest: 'Velocity is already at the lowest (0.10).',
+  noteVelocityHighest: 'Velocity is already at the highest (1.00).',
+  noteVelocityRefusal:
+    "The velocity of this note comes from something the page can't change here, like a signal or an option of .midi(). Ask Claude to change it.",
+  noteStale: 'That note changed in the code since you selected it. Nothing was changed. Select it again, or ask Claude.',
+  noteReadBack: "The page couldn't confirm this edit, so the code is as it was. Ask Claude to make it.",
+  noteEditError: 'The page ran into a problem before it changed this note, so the code is as it was. Ask Claude to make the change.',
+  noteEditErrorWritten: 'The page ran into a problem after it wrote this change, so check the code.',
+  noteNotEvaluated: 'The change did not evaluate, so the code is as it was. Ask Claude to make it.',
+  noteNoticeDisconnected: 'Disconnected — editing is off until Moontide reconnects.',
+  noteNoticeWaiting: 'A change is waiting for its bar line. Editing works again when it takes over.',
+  noteNoticeUnevaluated: 'The editor has changes that are not playing yet. Evaluate them first — editing works on the playing code.',
+  // The history entry of one written edit.
+  noteRecord: 'changed {track}: {from} to {to}{places}',
+  noteRecordRest: 'changed {track}: {from} to a rest{places}',
+  noteRecordVelocity: 'changed {track}: velocity of {note} to {v}{places}',
+  // Why a note cannot be edited, one sentence for each reason page/note-locate.js gives (NOTE_REASONS).
+  noteReasons: {
+    'no-token':
+      'Made by a function or by chance, or written in a single-quoted string, so no single place in the code holds this note. Ask Claude to change it.',
+    'no-pitch': 'This is a sample, not a pitched note, so there is no pitch to change. Ask Claude to change it.',
+    several:
+      'Shaped by several places in the code (an added note or a factor like *2), so no one place can be edited. Ask Claude to change it.',
+    degrees: "Written in degrees. The page doesn't edit those directly yet. Ask Claude to change it.",
+    escape:
+      "The string that holds this note has an escape sequence, so the page can't find the note in the code. Ask Claude to change it.",
+    shifted: 'The pitch you hear is not the pitch written: something adds to it or copies it. Ask Claude to change it.',
+    outside:
+      "Written outside this track's own code (its statement, or its variations in a song), so the page doesn't edit it here. Ask Claude to change it.",
+    shared: 'Comes from code shared by several tracks, so an edit here would change them too. Ask Claude to change it.',
+  },
 };
 
 /** Cycle count from which the next page starts computing in the background, while the current
@@ -85,6 +216,13 @@ export function rulerMarks(pageStart) {
 export const TRACK_COLOR_COUNT = 8;
 
 const NOTE_BASE_SEMITONE = { c: 0, d: 2, e: 4, f: 5, g: 7, a: 9, b: 11 };
+
+/**
+ * The spelling of a note name that Strudel itself plays: a letter in either case, lower-case accidentals (`#`, `s`, `b`, `f`) and an
+ * optional octave. noteNameToMidi reads a capital accidental too (`EB3`), which Strudel does not play, so a token is edited only when it
+ * matches this: the spelling the page edits and the one the sound engine plays are the same.
+ */
+export const NOTE_NAME_TOKEN = /^([a-gA-G])([#sbf]*)(-?\d+)?$/;
 const DEFAULT_NOTE_OCTAVE = 3;
 
 /**
@@ -93,7 +231,7 @@ const DEFAULT_NOTE_OCTAVE = 3;
  * (default 3, matching Strudel's own default). `null` for anything that doesn't parse as a
  * plain note name (a mini-notation pattern string, for example).
  */
-function noteNameToMidi(note) {
+export function noteNameToMidi(note) {
   const match = /^([a-g])((?:[#sbf])*)(-?\d+)?$/.exec(note.toLowerCase());
   if (!match) return null;
   const [, letter, accidentals, octaveText] = match;
@@ -340,6 +478,19 @@ function toEvent(hap) {
   return { begin: hap.whole.begin.valueOf(), end: hap.whole.end.valueOf(), value: hap.value };
 }
 
+/**
+ * One event of a lane: the same fields as the real pattern's events, plus `locations`, plain copies of the places in the
+ * code the note was read from, `[{ start, end }]` offsets into the code that was evaluated, or null when the note has none
+ * (a value made by a function, a hap without a context such as a test double). The real pattern's events keep no
+ * locations, so the check that the lanes add up to the real pattern never looks at them. Exported so the page reads the
+ * edited track back into the same shape.
+ */
+export function toLaneEvent(hap) {
+  const raw = hap.context && Array.isArray(hap.context.locations) ? hap.context.locations : null;
+  const locations = raw === null ? null : raw.map((location) => ({ start: location.start, end: location.end }));
+  return { begin: hap.whole.begin.valueOf(), end: hap.whole.end.valueOf(), value: hap.value, locations };
+}
+
 /**
  * Queries the real pattern and every unmuted track's own solo pattern over `pageCycles`
  * cycles starting at `pageStart`, in slices of `sliceCycles` with a yield to the page between
@@ -385,7 +536,7 @@ export async function computeTimeline({
         const pattern = trackPatterns[index];
         if (!pattern) return;
         for (const hap of pattern.queryArc(from, to)) {
-          if (hap.whole && hap.hasOnset()) laneEvents[index].push(toEvent(hap));
+          if (hap.whole && hap.hasOnset()) laneEvents[index].push(toLaneEvent(hap));
         }
       });
 
@@ -423,6 +574,12 @@ export const SIXTEENTHS_PER_CYCLE = BEATS_PER_CYCLE * 4;
  */
 export const MAX_MOMENT_NOTES = 32;
 
+/**
+ * The most cycles one range covers: the cycles of a page. Mirrors src/protocol.ts's MAX_RANGE_CYCLES by hand
+ * (test/ask.test.js checks both are 32).
+ */
+export const MAX_RANGE_CYCLES = 32;
+
 // Float noise allowed when an event edge is compared with the instant, in cycles.
 const MOMENT_EPSILON = 1e-9;
 
@@ -450,7 +607,7 @@ function round3(value) {
  * the event and is not seen here: such a note reads the default 0.9 (the reference documents
  * `.velocity()` on the pattern).
  */
-function velocityOf(value, midi) {
+export function velocityOf(value, midi) {
   const defaults = midi ? MIDI_LEVEL : BROWSER_LEVEL;
   const set = value && typeof value === 'object' ? value : {};
   const gain = set.gain === undefined ? defaults.gain : set.gain;
@@ -461,6 +618,15 @@ function velocityOf(value, midi) {
   return product < 0 ? undefined : Math.round(product * 100) / 100;
 }
 
+/**
+ * The gain of one event as the pinned bundle would apply it: the gain set on the event, else the default of a browser track
+ * (0.8) or a MIDI track (1). It may not be a number (a signal), which the caller must check.
+ */
+export function gainOf(value, midi) {
+  const set = value && typeof value === 'object' ? value : {};
+  return set.gain === undefined ? (midi ? MIDI_LEVEL : BROWSER_LEVEL).gain : set.gain;
+}
+
 function momentNote(lane, event, state) {
   const value = event.value && typeof event.value === 'object' ? event.value : {};
   const note = { track: lane.track };
@@ -559,3 +725,30 @@ export function momentAt({ pageStart, fraction, lanes, version, focusTrack }) {
     more: Math.max(0, notes.length - MAX_MOMENT_NOTES),
   };
 }
+
+/**
+ * The notes of one lane that start in the whole cycles `from` to `to` (both included): `{ notes, more }`. A note counts when its
+ * start is at least `from` and before `to + 1`, so one that started earlier and still sounds is not in it, and one that starts
+ * exactly at `to + 1` is not either. `lane` is `{ track, midi, instrument, drumMap, events }` as `momentAt` takes it. Each
+ * note is shaped like a moment note (the same fields, built by the same code) without its state, in order of start and then of
+ * pitch, the lower first; at most MAX_MOMENT_NOTES are kept and `more` counts the rest. Bad input is a loud TypeError.
+ */
+export function rangeNotes(lane, from, to) {
+  if (lane === null || typeof lane !== 'object' || !Array.isArray(lane.events)) {
+    throw new TypeError(`rangeNotes: lane must hold an events array, got ${String(lane)}`);
+  }
+  if (!Number.isInteger(from) || from < 0) throw new TypeError(`rangeNotes: from must be a non-negative integer, got ${String(from)}`);
+  if (!Number.isInteger(to) || to < from || to - from >= MAX_RANGE_CYCLES) {
+    throw new TypeError(`rangeNotes: to must be an integer from ${from} to ${from + MAX_RANGE_CYCLES - 1}, got ${String(to)}`);
+  }
+  const inside = lane.events.filter((event) => event.begin >= from - MOMENT_EPSILON && event.begin < to + 1 - MOMENT_EPSILON);
+  const keyed = inside.map((event) => ({ event, pitch: pitchOf(event.value) }));
+  // A note without a pitch (a sample, a tick) sorts after the pitched notes that start with it.
+  keyed.sort((a, b) => a.event.begin - b.event.begin || (a.pitch ?? Infinity) - (b.pitch ?? Infinity) || 0);
+  const notes = keyed.slice(0, MAX_MOMENT_NOTES).map(({ event }) => {
+    const note = momentNote(lane, event, 'sounding');
+    delete note.state;
+    return note;
+  });
+  return { notes, more: Math.max(0, keyed.length - MAX_MOMENT_NOTES) };
+}

package/page/tracks.js

@@ -364,6 +364,17 @@ export function parseLabel(label) {
   return { mutedByLabel, core, solo, soloInert: solo === 'marker' && mutedByLabel, base, safe };
 }
 
+/**
+ * The identity of a labeled track that has no `$` in its label: `label:` and the label without
+ * its mute underscore and solo marker, or the raw label when the mixer cannot read it. The
+ * mixer and the note tag both use this one rule, so a note is always reported under the same
+ * key as the strip it belongs to.
+ */
+export function labelKey(label) {
+  const parsed = parseLabel(label);
+  return `label:${parsed.safe ? parsed.base : label}`;
+}
+
 /**
  * Every labeled statement in the code, in source order (after the last-statement-wins dedup
  * above). A track is `{ index, kind: 'label', label, name, identity, muted, start, end, ... }`:
@@ -407,7 +418,7 @@ function buildLabelTracks(statements, topLevelDecls) {
       kind: 'label',
       label,
       name: isDollar ? displayNameFromSound(expression) : label,
-      identity: isDollar ? structuralIdentity(expression) : `label:${baseLabel}`,
+      identity: isDollar ? structuralIdentity(expression) : labelKey(label),
       baseLabel,
       hushed,
       ownMuted,
@@ -650,13 +661,10 @@ export function soloSource(code, trackIndex, { parse }) {
   const edits = [];
   collectStringEdits(ast, edits);
 
-  const declarationTexts = [];
   const allCalls = [];
   let lastEachCall = null;
   for (const statement of ast.body) {
-    if (statement.type === 'VariableDeclaration' || statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration') {
-      declarationTexts.push(applyEdits(code, edits, statement.start, statement.end));
-    } else if (topLevelCallNamed(statement, 'all')) {
+    if (topLevelCallNamed(statement, 'all')) {
       allCalls.push(statement.expression);
     } else if (topLevelCallNamed(statement, 'each')) {
       lastEachCall = statement.expression;
@@ -701,10 +709,31 @@ export function soloSource(code, trackIndex, { parse }) {
     wrapped = wrapEachAll(applyEdits(code, [...keptEdits, ...silenceEdits], programExpr.start, programExpr.end));
   }
 
+  return `${preludeOf(code, ast, edits)}return (${wrapped});`;
+}
+
+/** True for a top-level statement that declares a name: a variable, a function or a class. */
+function isDeclaration(statement) {
+  return statement.type === 'VariableDeclaration' || statement.type === 'FunctionDeclaration' || statement.type === 'ClassDeclaration';
+}
+
+/** The prelude text for an already parsed program and its string edits. */
+function preludeOf(code, ast, edits) {
   let body = '"use strict";\n';
-  for (const declarationText of declarationTexts) {
-    body += declarationText + '\n';
+  for (const statement of ast.body) {
+    if (isDeclaration(statement)) body += applyEdits(code, edits, statement.start, statement.end) + '\n';
   }
-  body += `return (${wrapped});`;
   return body;
 }
+
+/**
+ * The text every solo program starts with, and the declared-against-played check starts with too: "use strict"; and every
+ * top-level declaration in source order, each followed by a newline, with the same string rewrites soloSource applies.
+ * Evaluated, it defines the code's own constants and helper functions and nothing else runs.
+ */
+export function soloPrelude(code, { parse }) {
+  const ast = parse(code, PARSE_OPTIONS);
+  const edits = [];
+  collectStringEdits(ast, edits);
+  return preludeOf(code, ast, edits);
+}

package/page/ui-state.js

@@ -61,8 +61,11 @@ export const VCSL_MANIFEST_COMMIT = '9eacfc86ec4393e68a463ff52b01c19cfaa77f38';
 export const VCSL_MANIFEST_URL = 'https://raw.githubusercontent.com/felixroos/dough-samples/' + VCSL_MANIFEST_COMMIT + '/vcsl.json';
 export const VCSL_SAMPLE_BASE = 'https://cdn.jsdelivr.net/gh/sgossner/VCSL@' + VCSL_COMMIT + '/';
 
+/** What every sound-load failure text ends with; the reply adds the final period. */
+const REPLACED_SOUND_DUTY = '; if you replace it, tell the user which one and what replaced it, never silently';
+
 /** How many candidate sound names soundLoadFailureText lists before "and N more". */
-export const MAX_NAMED_SOUNDS = 8;
+export const MAX_NAMED_SOUNDS = 7;
 
 /**
  * How long the page waits for AudioContext.resume() to reach 'running' after
@@ -219,20 +222,22 @@ export function isFetchFailure(text) {
  * The page names a sound only when it is the single candidate — a wrong name misled
  * Claude in an earlier user test. With several it lists them, sorted and de-duplicated so the text is
  * stable for any arrival order, capped at MAX_NAMED_SOUNDS so the server's 500 code point
- * cleanErrorDetail cap never cuts a name in half. With none, it says the page could not tell.
+ * cleanErrorDetail cap never cuts a name in half. With none, it says the page could not tell. Every variant ends
+ * with the duty to say which sound was replaced and by what: it lives here, where Claude reads about the failure,
+ * and not in the server instructions, which have a fixed length.
  */
 export function soundLoadFailureText(detail, names) {
   const distinct = [...new Set(names)].sort();
   if (distinct.length === 1) {
-    return `sound "${distinct[0]}" failed to load (${detail}); it plays nothing until the page is reloaded`;
+    return `sound "${distinct[0]}" failed to load (${detail}); it plays nothing until the page is reloaded${REPLACED_SOUND_DUTY}`;
   }
   if (distinct.length === 0) {
-    return `a sound failed to load (${detail}), and the page could not tell which one`;
+    return `a sound failed to load (${detail}), and the page could not tell which one${REPLACED_SOUND_DUTY}`;
   }
   const shown = distinct.slice(0, MAX_NAMED_SOUNDS);
   const rest = distinct.length - shown.length;
   const list = rest > 0 ? `${shown.join(', ')} and ${rest} more` : shown.join(', ');
-  return `one of these sounds failed to load (${detail}): ${list}; the one that failed plays nothing until the page is reloaded`;
+  return `one of these sounds failed to load (${detail}): ${list}; the one that failed plays nothing until the page is reloaded${REPLACED_SOUND_DUTY}`;
 }
 
 /**