moontide-mcp 2.0.1 → 2.1.0

package/page/page-rewrite.js

@@ -0,0 +1,184 @@
+// The one path through which the page itself changes the code: a Mixer move, a part launch, a grid
+// gesture. It runs the guards in a fixed order, writes the new text and checks the write, makes one
+// evaluation and, when that fails, sets the editor back and shows the failed-change banner through the
+// same helper every other failure uses. Each caller keeps its own wording for a refusal and sends its own
+// message to the server; this module only decides whether the text may change and whether it played.
+// No DOM access at import time and every dependency injected, so node:test can import it with fakes.
+
+import { parseTiming } from './change-timing.js';
+
+// The reasons a change is refused before anything is written. A refusal never touches the editor, except
+// write-mismatch, which sets the editor back to the text it had before the write.
+export const PAGE_REWRITE_REFUSALS = Object.freeze(['not-played', 'waiting', 'closed', 'no-parser', 'dirty', 'write-mismatch']);
+
+// The guards, in the order they run. Each one is on unless the request turns it off.
+const GUARD_KEYS = Object.freeze(['played', 'waiting', 'socket', 'parser', 'dirty']);
+
+const WRITES = Object.freeze(['dispatch', 'replace']);
+
+const DEP_FUNCTIONS = Object.freeze([
+  'hasEvaluated',
+  'pending',
+  'playingCode',
+  'socketOpen',
+  'parserReady',
+  'evaluate',
+  'evalError',
+  'revertAndReport',
+  'markPageOrigin',
+  'whenFinished',
+  'markPageOriginAtTakeover',
+]);
+
+function refused(reason) {
+  return Object.freeze({ status: 'refused', reason });
+}
+
+/**
+ * Builds the page's rewrite path around its dependencies:
+ *   editor { code, setCode(text), dispatch(edits) }: the text the user sees; dispatch applies a list of
+ *     { from, to, insert } edits in the coordinates of the text before the write, keeping selection and scroll,
+ *   hasEvaluated() -> true once some code has played, pending() -> the waiting change or null,
+ *   playingCode() -> the code that plays now, socketOpen() -> true while the server socket is open,
+ *   parserReady() -> true when the code parser is loaded,
+ *   evaluate({ code, timing, autostart, flash }) -> promise of the run ({ timing, deferred, ... }); flash true
+ *     evaluates through the editor (it flashes), flash false through the repl directly,
+ *   evalError() -> the evaluation's error or null,
+ *   revertAndReport(error) -> { errorText, line }: sets the editor back to the committed code and shows the banner,
+ *   markPageOrigin() -> the playing code now has no Claude evaluate id,
+ *   whenFinished(record, fn) -> runs fn when the waiting change takes over (or is dropped),
+ *   markPageOriginAtTakeover() -> the same mark, for the moment a waiting change takes over.
+ */
+export function createPageRewrite(deps) {
+  if (deps === null || typeof deps !== 'object') {
+    throw new Error('Moontide: createPageRewrite needs its dependencies.');
+  }
+  const editor = deps.editor;
+  if (
+    editor === null ||
+    typeof editor !== 'object' ||
+    typeof editor.setCode !== 'function' ||
+    typeof editor.dispatch !== 'function' ||
+    !('code' in editor)
+  ) {
+    throw new Error('Moontide: createPageRewrite needs an editor with code, setCode and dispatch.');
+  }
+  for (const name of DEP_FUNCTIONS) {
+    if (typeof deps[name] !== 'function') {
+      throw new Error(`Moontide: createPageRewrite needs the function ${name}.`);
+    }
+  }
+
+  function readGuards(guards) {
+    const on = {};
+    for (const key of GUARD_KEYS) on[key] = true;
+    if (guards === undefined) return on;
+    if (guards === null || typeof guards !== 'object' || Array.isArray(guards)) {
+      throw new Error('Moontide: the guards of a page rewrite are an object.');
+    }
+    for (const [key, value] of Object.entries(guards)) {
+      if (!GUARD_KEYS.includes(key)) {
+        throw new Error(`Moontide: unknown guard '${key}' in a page rewrite (expected one of ${GUARD_KEYS.join(', ')}).`);
+      }
+      if (typeof value !== 'boolean') {
+        throw new Error(`Moontide: the guard '${key}' of a page rewrite is true or false.`);
+      }
+      on[key] = value;
+    }
+    return on;
+  }
+
+  /**
+   * Applies one change to the code. See the request fields below; resolves one of
+   *   { status: 'played', code, run, edits }  the text that was evaluated; run.deferred is the waiting change
+   *       when the change waits for its line, else null,
+   *   { status: 'unchanged', code }  the build left the text as it was and the request did not ask to evaluate it,
+   *   { status: 'refused', reason }  one of PAGE_REWRITE_REFUSALS; nothing was written,
+   *   { status: 'failed', errorText, line }  the evaluation failed; the editor is already set back and the banner shown.
+   *
+   * Request:
+   *   build(base) -> { code, edits }: the new text; edits is a list of { from, to, insert } in the coordinates of
+   *     base for write 'dispatch' and may be null for write 'replace'. An error it throws reaches the caller as it is.
+   *   base: the text the build starts from and the dirty guard compares with the editor (default: the playing code).
+   *   timing: a parsed timing (default: at once). autostart: only used when flash is false (default true).
+   *   flash: evaluate through the editor, which flashes (default false).
+   *   write: 'dispatch' (default) changes the text by edits and checks the result; 'replace' sets the whole text.
+   *   guards: any of played, waiting, socket, parser, dirty set to false to leave that guard out.
+   *   evaluateUnchanged: also evaluate when the build left the text as it was (default false).
+   */
+  async function apply(request) {
+    if (request === null || typeof request !== 'object' || typeof request.build !== 'function') {
+      throw new Error('Moontide: a page rewrite needs a build function.');
+    }
+    const write = request.write === undefined ? 'dispatch' : request.write;
+    if (!WRITES.includes(write)) {
+      throw new Error(`Moontide: unknown write '${String(request.write)}' in a page rewrite (expected one of ${WRITES.join(', ')}).`);
+    }
+    const guards = readGuards(request.guards);
+    const timing = request.timing === undefined ? parseTiming('now') : request.timing;
+    const autostart = request.autostart === undefined ? true : request.autostart;
+    const flash = request.flash === true;
+    const evaluateUnchanged = request.evaluateUnchanged === true;
+
+    if (guards.played && !deps.hasEvaluated()) return refused('not-played');
+    if (guards.waiting && deps.pending() !== null) return refused('waiting');
+    if (guards.socket && !deps.socketOpen()) return refused('closed');
+    if (guards.parser && !deps.parserReady()) return refused('no-parser');
+    const base = request.base === undefined ? deps.playingCode() : request.base;
+    if (guards.dirty && editor.code !== base) return refused('dirty');
+
+    const built = request.build(base);
+    if (built === null || typeof built !== 'object' || typeof built.code !== 'string') {
+      throw new Error('Moontide: the build of a page rewrite must return { code, edits }.');
+    }
+    const code = built.code;
+    const edits = Array.isArray(built.edits) ? built.edits : null;
+    if (code === base && !evaluateUnchanged) {
+      return Object.freeze({ status: 'unchanged', code });
+    }
+
+    if (write === 'dispatch') {
+      if (edits === null && code !== base) {
+        throw new Error('Moontide: a page rewrite that writes by edits needs an edit list from its build.');
+      }
+      if (edits !== null && edits.length > 0) editor.dispatch(edits);
+      if (editor.code !== code) {
+        editor.setCode(base);
+        return refused('write-mismatch');
+      }
+    } else {
+      editor.setCode(code);
+    }
+
+    let run;
+    try {
+      run = await deps.evaluate({ code, timing, autostart, flash });
+    } catch (err) {
+      // The evaluation itself threw (not a program error, which is read from evalError below): nothing is armed, so the
+      // text written above would sit in the editor as typing that was never evaluated. It is taken back, unless the
+      // person typed over it meanwhile; the error goes on to the caller, marked `restored` when the editor holds the base
+      // text again, so the caller can say the code is as it was.
+      if (code !== base && editor.code === code) editor.setCode(base);
+      if (editor.code === base && err !== null && typeof err === 'object' && Object.isExtensible(err)) err.restored = true;
+      throw err;
+    }
+    if (run === null || typeof run !== 'object') {
+      throw new Error('Moontide: the evaluation of a page rewrite must give back its run.');
+    }
+    const evalError = deps.evalError();
+    if (evalError) {
+      const { errorText, line } = deps.revertAndReport(evalError);
+      return Object.freeze({ status: 'failed', errorText, line });
+    }
+    // A change the page makes by itself has no Claude evaluate id: at once when it plays at once, otherwise at
+    // the moment it takes over (the old code, and its id, keep playing until then).
+    if (run.deferred === null || run.deferred === undefined) {
+      deps.markPageOrigin();
+    } else {
+      deps.whenFinished(run.deferred, deps.markPageOriginAtTakeover);
+    }
+    return Object.freeze({ status: 'played', code, run, edits });
+  }
+
+  return Object.freeze({ apply });
+}

package/page/song-edit.js

@@ -0,0 +1,230 @@
+// Pure module for Moontide's browser page: the line maths and the edits of a section launch from the Song grid. A launch
+// reads the scheduler's frontier, computes the line the section must start on (the end of the section that plays, the next
+// phrase or the next bar), writes the shift that puts the section on that line into the code and evaluates it, all in one
+// turn; the takeover is then pinned to the very line the shift was written for, so the two cannot disagree. This was
+// measured in the real page before it was built: the line agreed with the landing in every launch of the page's own path.
+// Nothing here touches the DOM or the editor: the functions take a reading of the code (page/structure.js) and give back
+// numbers and edit lists, so node:test and page/main.js import them without a build step.
+
+import { boundaryCycle, DEFAULT_PHRASE_CYCLES } from './change-timing.js';
+import { launchOffset } from './parts.js';
+import { SONG_LAUNCHES } from './views.js';
+
+/** The decimals a shift literal is written with; a fraction needs no more than a cycle split into a thousand million. */
+const SHIFT_DECIMALS = 9;
+
+/** Two shifts closer than this give the same position (floating-point noise of a few additions). */
+const SHIFT_TOLERANCE = 1e-9;
+
+function finite(name, value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`Moontide: ${name} must be a finite number, got ${String(value)}.`);
+  }
+  return value;
+}
+
+/**
+ * Where every section of the read song starts while its shift is 0, in entry order: the start the reader gives (the shift
+ * is already in it) minus the shift. Starts are whole numbers (lengths are whole), so a result within rounding noise of a
+ * whole number is that number.
+ */
+export function unshiftedStarts(reading) {
+  return reading.sections.map((section) => {
+    const value = section.start - reading.shift;
+    const whole = Math.round(value);
+    return Math.abs(value - whole) < SHIFT_TOLERANCE ? whole : value;
+  });
+}
+
+/**
+ * The line a launch at the end of the section that plays starts on: the first section start of the shifted structure that
+ * is strictly after the scheduler frontier and at least `minLeadSeconds` ahead of it at tempo `cps`. A request in the last
+ * half second of a section therefore lands on the end of the next section. `starts` are the unshifted section starts in
+ * ascending order and `total` the length of the whole structure; the search covers four passes of the structure and throws
+ * when it finds no line, and when an argument is not usable.
+ */
+export function sectionEndLine({ frontier, cps, shift, total, starts, minLeadSeconds }) {
+  finite('the frontier', frontier);
+  finite('the shift', shift);
+  finite('the minimum lead', minLeadSeconds);
+  if (finite('the tempo', cps) <= 0) throw new Error(`Moontide: the tempo must be above 0, got ${String(cps)}.`);
+  if (finite('the length of the structure', total) <= 0) throw new Error(`Moontide: the length of the structure must be above 0, got ${String(total)}.`);
+  if (!Array.isArray(starts) || starts.length === 0) throw new Error('Moontide: a section line needs the starts of the sections.');
+  starts.forEach((start, i) => {
+    finite('a section start', start);
+    if (i > 0 && start <= starts[i - 1]) throw new Error('Moontide: the section starts must ascend.');
+  });
+  const first = Math.floor((frontier - shift) / total) - 1;
+  for (let pass = first; pass <= first + 3; pass++) {
+    for (const start of starts) {
+      const cycle = shift + pass * total + start;
+      if (cycle > frontier && (cycle - frontier) / cps >= minLeadSeconds) return cycle;
+    }
+  }
+  throw new Error('Moontide: no section line was found ahead of the scheduler.');
+}
+
+/**
+ * The line of a launch and the word the takeover knows it by: `kind` is one of the toolbar's choices ('section', 'phrase',
+ * 'bar'). Returns a frozen { line, at } with `at` 'section', 'phrase' or 'bar'. Bar and phrase lines are multiples of 1 and
+ * of the page's phrase length counted from Play, at least `minLeadSeconds` ahead of the frontier; the end of the section
+ * that plays comes from the read song. Any other kind throws.
+ */
+export function launchLine({ kind, frontier, cps, reading, minLeadSeconds }) {
+  if (!SONG_LAUNCHES.includes(kind)) {
+    throw new Error(`Moontide: unknown launch choice '${String(kind)}' (expected one of ${SONG_LAUNCHES.join(', ')}).`);
+  }
+  if (kind === 'section') {
+    const line = sectionEndLine({ frontier, cps, shift: reading.shift, total: reading.total, starts: unshiftedStarts(reading), minLeadSeconds });
+    return Object.freeze({ line, at: 'section' });
+  }
+  const lineLength = kind === 'bar' ? 1 : DEFAULT_PHRASE_CYCLES;
+  return Object.freeze({ line: boundaryCycle({ frontier, cps, lineLength, minLeadSeconds }), at: kind });
+}
+
+/** The shift that puts section `sectionIndex` of the read song on cycle `line`. */
+export function launchShift(reading, sectionIndex, line) {
+  const starts = unshiftedStarts(reading);
+  if (!Number.isInteger(sectionIndex) || sectionIndex < 0 || sectionIndex >= starts.length) {
+    throw new Error(`Moontide: the song has no section ${String(sectionIndex)} to launch.`);
+  }
+  finite('the launch line', line);
+  return launchOffset(line, starts[sectionIndex], reading.total);
+}
+
+/** True when shifts `a` and `b` give the same position in a structure of `total` cycles (they differ by a whole number of structures). */
+export function sameShift(a, b, total) {
+  finite('a shift', a);
+  finite('a shift', b);
+  if (finite('the length of the structure', total) <= 0) throw new Error(`Moontide: the length of the structure must be above 0, got ${String(total)}.`);
+  const rest = (((a - b) % total) + total) % total;
+  return rest < SHIFT_TOLERANCE || total - rest < SHIFT_TOLERANCE;
+}
+
+/**
+ * The number literal to write for a shift: whole numbers as digits, a fraction rounded to nine decimals with no trailing
+ * zero, a negative zero as '0'. A value that is not finite throws.
+ */
+export function shiftText(value) {
+  finite('a shift', value);
+  const fixed = value.toFixed(SHIFT_DECIMALS);
+  const text = fixed.includes('.') ? fixed.replace(/0+$/, '').replace(/\.$/, '') : fixed;
+  return text === '-0' ? '0' : text;
+}
+
+/** The edit list that replaces the shift literal of the read song with `value`. */
+export function shiftEdit(reading, value) {
+  const range = reading.shiftRange;
+  if (range === undefined || range === null) throw new Error('Moontide: the reading of the song has no range for its shift.');
+  return [{ from: range.start, to: range.end, insert: shiftText(value) }];
+}
+
+/**
+ * The edit that makes Play start a piece from its first section: the scheduler's cycle count restarts at 0 at every Play, so
+ * a shift left in the code starts the music inside the structure. null when the shift is 0 already (Play changes nothing);
+ * otherwise the one edit that writes 0 over the shift literal and touches nothing else.
+ */
+export function playResetEdit(reading) {
+  if (reading.shift === 0) return null;
+  const range = reading.shiftRange;
+  if (range === undefined || range === null) throw new Error('Moontide: the reading of the song has no range for its shift.');
+  return [{ from: range.start, to: range.end, insert: '0' }];
+}
+
+/**
+ * What the editor holds again when a launch from the grid is over without having taken over (canceled, or the sound
+ * stopped while it waited). The launch wrote only the shift into the code, so the code that plays goes back, but only while
+ * the editor still holds exactly the text the launch wrote. Text the person typed since is never replaced: the answer is
+ * then null and the editor is left as it is. Also null when the launch never recorded its text.
+ */
+export function textAfterCanceledLaunch({ editorCode, launchCode, playingCode }) {
+  if (typeof editorCode !== 'string' || typeof playingCode !== 'string') {
+    throw new Error('Moontide: a canceled launch needs the text of the editor and the code that plays.');
+  }
+  return typeof launchCode === 'string' && editorCode === launchCode ? playingCode : null;
+}
+
+/** null when section `index` of the read song still has the name and length the person saw, else 'section-gone'. */
+export function checkSection(reading, { index, name, length }) {
+  const section = reading.sections[index];
+  return section !== undefined && section.name === name && section.length === length ? null : 'section-gone';
+}
+
+// ---- changing a cell of the plan ----
+
+/** The sentence each refusal id of the cell edits stands for, so an error says what was refused. */
+const EDIT_REFUSALS = {
+  'name-unwritable': "Moontide: that variation's name cannot be written into the plan as it is.",
+};
+
+/** Raised when an edit cannot be built from what the person chose; `reason` is the id the grid turns into a sentence. */
+export class SongEditRefusal extends Error {
+  constructor(reason) {
+    const message = Object.hasOwn(EDIT_REFUSALS, reason) ? EDIT_REFUSALS[reason] : null;
+    if (message === null) throw new Error(`Moontide: unknown song edit refusal '${String(reason)}'.`);
+    super(message);
+    this.name = 'SongEditRefusal';
+    this.reason = reason;
+  }
+}
+
+/** The plan reads this name as a rest, so a variation called so cannot be chosen by name. */
+const REST_KEY = '-';
+
+/** The literal the plan holds for a rest. */
+const REST_LITERAL = "'-'";
+
+/** Characters that cannot sit in a single-quoted literal on one line: controls, line separator, paragraph separator. */
+const UNWRITABLE = /[\u0000-\u001F\u007F\u2028\u2029]/;
+
+/**
+ * The text to write into the plan for the variation called `key`: a single-quoted literal with the backslash and the single
+ * quote escaped. A name that holds a control, line separator or paragraph separator character, or the name '-' (the plan reads
+ * it as a rest), is refused with SongEditRefusal('name-unwritable').
+ */
+export function quoteKey(key) {
+  if (typeof key !== 'string') throw new Error(`Moontide: a variation name must be text, got ${String(key)}.`);
+  if (key === REST_KEY || UNWRITABLE.test(key)) throw new SongEditRefusal('name-unwritable');
+  return `'${key.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+/** The cell of `track` in section entry `index`, or undefined. */
+function cellOf(track, index) {
+  return track.cells.find((cell) => cell.section === index);
+}
+
+/**
+ * null when the cell the person clicked is still what they saw, else the id of what changed: `section-gone` (entry `index`
+ * has another name or length now), `cell-gone` (the track is gone, or its cell in that section no longer holds `key`; a
+ * `key` of null stands for a rest) or `variation-gone` (`choice.key` is no longer a variation of that track). `choice` is
+ * `{ key }` or `{ rest: true }`.
+ */
+export function checkCell(reading, { index, name, length, track, key }, choice) {
+  const section = reading.sections[index];
+  if (section === undefined || section.name !== name || section.length !== length) return 'section-gone';
+  const found = reading.tracks.find((candidate) => candidate.name === track);
+  if (found === undefined) return 'cell-gone';
+  const cell = cellOf(found, index);
+  if (cell === undefined || cell.key !== key) return 'cell-gone';
+  if (choice.rest !== true && !found.variations.some((variation) => variation.key === choice.key)) return 'variation-gone';
+  return null;
+}
+
+/**
+ * The edit that puts `choice` (`{ key }` or `{ rest: true }`) into the cell of `track` in section entry `index`: one
+ * `{ from, to, insert }` over the plan string of that cell and nothing else (entries that share a section name share the
+ * string, so one edit changes every column of that name). `changed` is false, with no edit, when the choice is what the cell
+ * holds already. A name that cannot be written throws SongEditRefusal; a track or section the reading does not have throws.
+ */
+export function cellEdit(reading, { index, track }, choice) {
+  const found = reading.tracks.find((candidate) => candidate.name === track);
+  const cell = found === undefined ? undefined : cellOf(found, index);
+  if (cell === undefined) throw new Error(`Moontide: the song has no cell for track '${String(track)}' in section ${String(index)}.`);
+  const rest = choice !== null && typeof choice === 'object' && choice.rest === true;
+  if (!rest && (choice === null || typeof choice !== 'object' || typeof choice.key !== 'string')) {
+    throw new Error('Moontide: a cell choice is { key } or { rest: true }.');
+  }
+  if (rest ? cell.key === null : cell.key === choice.key) return { edits: [], changed: false };
+  const insert = rest ? REST_LITERAL : quoteKey(choice.key);
+  return { edits: [{ from: cell.range.start, to: cell.range.end, insert }], changed: true };
+}

package/page/song-fit.js

@@ -0,0 +1,250 @@
+// Pure module for Moontide's browser page: whether the notes of a fixed variation fit the harmony of the section they play
+// in. The page asks each fixed variation for its own pattern, by a query of the code's own constants (never through the
+// code's play() helper), keeps which pitch classes it plays in each cycle, and compares those of the cycles a section covers
+// with the scale of the section's harmony, over the nine scales the Jam view knows. It only says words: nothing here
+// changes the code, the music or a launch.
+//
+// The query follows the same shape as the check of what a song declares: the code's top-level declarations are evaluated by
+// the prelude the per-track programs start with, then each variation is read from its track's constant. The clock, the
+// budget, the yield to the page and the cancel flag are injected, so this module has no DOM access at import time and
+// node:test drives it with fake patterns.
+
+import { soloPrelude } from './tracks.js';
+import { pitchOf } from './timeline.js';
+import { MICROTONE, MODES, scalePcs, spellTable } from './jam-analysis.js';
+import { readHarmonyText } from './harmony.js';
+import { SONG_COPY, displayHarmony, fillSong, quoted } from './structure.js';
+
+/** Why a variation's fit cannot be checked, by id; each has one sentence in SONG_COPY.fitReasons. */
+export const FIT_REASONS = Object.freeze(['no-harmony', 'harmony-unreadable', 'harmony-unknown', 'no-notes', 'not-read', 'too-slow']);
+
+/** How many outside notes the line under a variation names before it says how many more there are. */
+const NAMED_OUTSIDE = 3;
+
+/** How many cycles are read between two looks at the clock and the cancel flag. */
+const CHECK_EVERY_CYCLES = 4;
+
+const AsyncFunctionConstructor = Object.getPrototypeOf(async function () {}).constructor;
+
+const mod12 = (n) => ((n % 12) + 12) % 12;
+
+/** The key of one variation of one track in the answer: the track's name and the variation's key, as JSON text. */
+export function pairKey(track, key) {
+  return JSON.stringify([track, key]);
+}
+
+/**
+ * The (track, variation) pairs the fit query holds a pattern for: every fixed variation of every play track, muted tracks
+ * included, used or not, tracks in code order and then variations in code order. Returns `[{ track, key }]` with the
+ * track's name and the variation's key.
+ */
+export function fitPairs(reading) {
+  const pairs = [];
+  for (const track of reading.tracks) {
+    for (const variation of track.variations) {
+      if (variation.kind === 'fixed') pairs.push({ track: track.name, key: variation.key });
+    }
+  }
+  return pairs;
+}
+
+/**
+ * The body of an async function that returns one entry per pair of fitPairs: the pattern of the variation, or null. It
+ * starts with the declarations and string rewrites the per-track programs start with (soloPrelude), then reads each
+ * variation from the track's constant by the key the reader found, through a helper called by `this` so no name in the code
+ * can shadow it: the second element of the pair when it can be queried, else null. Keys enter only through JSON.stringify
+ * and constant names are the identifier names the parser gave the reader.
+ */
+export function fitSource(code, reading, { parse }) {
+  const constants = new Map(reading.tracks.map((track) => [track.name, track.constName]));
+  const entries = fitPairs(reading).map(({ track, key }) => `this.pick(${constants.get(track)}[${JSON.stringify(key)}])`);
+  const pick = "(value) => (Array.isArray(value) && value[1] && typeof value[1].queryArc === 'function' ? value[1] : null)";
+  return `${soloPrelude(code, { parse })}return (function () {\nreturn [\n${entries.join(',\n')}\n];\n}).call({ pick: ${pick} });`;
+}
+
+/**
+ * Builds and awaits an AsyncFunction from `body` (a fitSource result), never through the editor's evaluate, so it never
+ * touches the scheduler and never calls the code's play(). Throws a 'Moontide: ...' error when the result is not a list.
+ */
+export async function evaluateFit(body) {
+  const result = await new AsyncFunctionConstructor(body)();
+  if (!Array.isArray(result)) throw new Error('Moontide: the fit query did not come out as a list of patterns.');
+  return result;
+}
+
+/** The 12-bit set of the pitch classes of the onsets that begin in one cycle of `pattern`. A note farther than MICROTONE from a semitone is left out. */
+function maskOfCycle(pattern, cycle) {
+  let mask = 0;
+  for (const hap of pattern.queryArc(cycle, cycle + 1)) {
+    if (!hap.whole || !hap.hasOnset()) continue;
+    const pitch = pitchOf(hap.value);
+    if (pitch === null) continue;
+    const midi = Math.round(pitch);
+    if (Math.abs(pitch - midi) > MICROTONE) continue;
+    mask |= 1 << mod12(midi);
+  }
+  return mask;
+}
+
+/**
+ * Reads, for every pair, which pitch classes its pattern plays in each of the first `cycles` cycles (a variation restarts at
+ * its first cycle in every section, so cycle 0 is the section's first). `patterns[i]` belongs to `pairs[i]`; a null pattern
+ * is a variation the page could not read. Resolves to `{ state: 'ready', byPair, failures }` or `{ state: 'cancelled' }`:
+ * `byPair` maps pairKey(track, key) to `{ masks }` (one 12-bit set per cycle, a note counted in the cycle it begins in) or
+ * to `{ reason: 'not-read' | 'too-slow' }`; `failures` lists `{ track, key, message }` for each query that threw. The
+ * clock and the cancel flag are looked at before each variation and every few cycles; a variation the budget cuts short and
+ * every one after it are 'too-slow'. It yields to the page after each variation and never throws.
+ */
+export async function collectFit({ patterns, pairs, cycles, budgetMs, clock, yieldToPage, isCancelled }) {
+  const begun = clock();
+  const byPair = new Map();
+  const failures = [];
+  if (!Array.isArray(patterns) || patterns.length !== pairs.length) {
+    return { state: 'ready', byPair: new Map(pairs.map((pair) => [pairKey(pair.track, pair.key), { reason: 'not-read' }])), failures: [{ track: null, key: null, message: 'the fit query did not match the variations of the reading' }] };
+  }
+  let overBudget = false;
+  for (let at = 0; at < pairs.length; at++) {
+    const { track, key } = pairs[at];
+    const id = pairKey(track, key);
+    if (isCancelled()) return { state: 'cancelled' };
+    if (!overBudget && clock() - begun > budgetMs) overBudget = true;
+    if (overBudget) {
+      byPair.set(id, { reason: 'too-slow' });
+      continue;
+    }
+    const pattern = patterns[at];
+    if (pattern === null || pattern === undefined || typeof pattern.queryArc !== 'function') {
+      byPair.set(id, { reason: 'not-read' });
+      continue;
+    }
+    const masks = [];
+    try {
+      for (let cycle = 0; cycle < cycles; cycle++) {
+        masks.push(maskOfCycle(pattern, cycle));
+        if (cycle % CHECK_EVERY_CYCLES === CHECK_EVERY_CYCLES - 1 && clock() - begun > budgetMs) {
+          overBudget = true;
+          break;
+        }
+      }
+    } catch (err) {
+      failures.push({ track, key, message: err instanceof Error ? err.message : String(err) });
+      byPair.set(id, { reason: 'not-read' });
+      continue;
+    }
+    byPair.set(id, overBudget ? { reason: 'too-slow' } : { masks });
+    await yieldToPage();
+    if (isCancelled()) return { state: 'cancelled' };
+  }
+  return { state: 'ready', byPair, failures };
+}
+
+/**
+ * The scale a section's harmony gives to compare with: `{ rootPc, modeId, text }`, or `{ reason }` with a reason of
+ * FIT_REASONS when there is none to compare with: no harmony anywhere, a piece harmony the page cannot read, text the reader
+ * rejects, chord text, or a scale outside the nine. `section` is an entry of a read song.
+ */
+export function sectionHarmony(section) {
+  const { harmony } = section;
+  if (harmony.from === 'none') return { reason: 'no-harmony' };
+  if (harmony.from === 'piece-unreadable') return { reason: 'harmony-unreadable' };
+  const read = readHarmonyText(harmony.text);
+  if (read === null) return { reason: 'harmony-unreadable' };
+  if (read.scale === null) return { reason: 'harmony-unknown' };
+  return { rootPc: read.scale.rootPc, modeId: read.scale.modeId, text: harmony.text };
+}
+
+/**
+ * Whether the notes of one variation fit one section. `masks` is what collectFit read for the variation (one set per cycle),
+ * `length` the section's length in cycles (only the first `length` cycles count; a note that begins exactly at the length
+ * belongs to the next cycle), `harmony` the sectionHarmony result, and `readReason` the reason collectFit gave when it could
+ * not read the variation. Returns `{ state: 'fits' }`, `{ state: 'does-not-fit', outside }` with the outside notes spelled the
+ * way the Jam view spells the section's scale and listed upward from its root, each once, or `{ state: 'cannot-check', reason }`.
+ * The harmony's reason comes first, then the reason the variation was not read, then a variation with no pitched note.
+ */
+export function fitOf({ masks, length, harmony, readReason = null }) {
+  if (harmony.reason !== undefined) return { state: 'cannot-check', reason: harmony.reason };
+  if (readReason !== null) {
+    if (!FIT_REASONS.includes(readReason)) throw new Error(`Moontide: unknown fit reason '${String(readReason)}'.`);
+    return { state: 'cannot-check', reason: readReason };
+  }
+  if (!Array.isArray(masks) || masks.length < length) {
+    throw new Error(`Moontide: the fit of a section of ${String(length)} cycles needs the notes of that many cycles.`);
+  }
+  let played = 0;
+  for (let cycle = 0; cycle < length; cycle++) played |= masks[cycle];
+  if (played === 0) return { state: 'cannot-check', reason: 'no-notes' };
+  const mode = MODES.find((candidate) => candidate.id === harmony.modeId);
+  if (mode === undefined) throw new Error(`Moontide: no scale called '${String(harmony.modeId)}' to compare with.`);
+  const inScale = new Set(scalePcs(harmony.rootPc, mode));
+  const outside = [];
+  for (let pc = 0; pc < 12; pc++) {
+    if ((played & (1 << pc)) !== 0 && !inScale.has(pc)) outside.push(pc);
+  }
+  if (outside.length === 0) return { state: 'fits' };
+  outside.sort((a, b) => mod12(a - harmony.rootPc) - mod12(b - harmony.rootPc));
+  const spelling = spellTable(harmony.rootPc, mode);
+  return { state: 'does-not-fit', outside: outside.map((pc) => spelling[pc]) };
+}
+
+/**
+ * The words for one fit. `fit` is a fitOf result; the rest names the cell: `track`, `section` and `variation` as written,
+ * `fixedHarmony` the harmony text of the variation, `sectionHarmonyText` the section's harmony text (needed for a fit and a
+ * non-fit). Returns `{ line, title, chip }`: `line` is `fits`, `does not fit (F#, A)` naming at most three notes and then
+ * ` and {n} more`, or `cannot check`; `title` holds every outside note or the one reason sentence; `chip` is the line with
+ * the separator the Ask chip of the cell ends with. An unknown state or reason throws.
+ */
+export function fitText(fit, { track, section, variation, fixedHarmony, sectionHarmonyText }) {
+  const values = { track: quoted(track), section: quoted(section), variation: quoted(variation), harmony: displayHarmony(fixedHarmony) };
+  const sectionText = () => displayHarmony(sectionHarmonyText);
+  if (fit.state === 'fits') {
+    const line = SONG_COPY.fitFits;
+    return { line, title: fillSong(SONG_COPY.fitTitleFits, { ...values, sectionHarmony: sectionText() }), chip: fillSong(SONG_COPY.fitChip, { fit: line }) };
+  }
+  if (fit.state === 'does-not-fit') {
+    const named = fit.outside.slice(0, NAMED_OUTSIDE).join(', ');
+    const more = fit.outside.length - NAMED_OUTSIDE;
+    const notes = more > 0 ? fillSong(SONG_COPY.fitMore, { notes: named, count: more }) : named;
+    const line = fillSong(SONG_COPY.fitNot, { notes });
+    const title = fillSong(SONG_COPY.fitTitleNot, { ...values, sectionHarmony: sectionText(), notes: fit.outside.join(', ') });
+    return { line, title, chip: fillSong(SONG_COPY.fitChip, { fit: line }) };
+  }
+  if (fit.state === 'cannot-check') {
+    if (!Object.hasOwn(SONG_COPY.fitReasons, fit.reason)) throw new Error(`Moontide: unknown fit reason '${String(fit.reason)}'.`);
+    const line = SONG_COPY.fitCannot;
+    return { line, title: fillSong(SONG_COPY.fitTitleCannot, { ...values, reason: SONG_COPY.fitReasons[fit.reason] }), chip: fillSong(SONG_COPY.fitChip, { fit: line }) };
+  }
+  throw new Error(`Moontide: unknown fit state '${String(fit.state)}'.`);
+}
+
+/**
+ * The lookup the grid and the cell list use: `lookup(trackName, sectionIndex, key)` gives the fit of that fixed variation in
+ * that section entry as `{ ...fitOf result, ...fitText result }`, from the answer of collectFit, or null when the variation is
+ * not a fixed one of the reading. Each entry of a section that is used more than once gets its own length and harmony.
+ * Results are made once per variation and section entry.
+ */
+export function fitLookup({ reading, byPair }) {
+  const made = new Map();
+  const harmonies = reading.sections.map((section) => sectionHarmony(section));
+  return (trackName, sectionIndex, key) => {
+    const track = reading.tracks.find((candidate) => candidate.name === trackName);
+    const variation = track === undefined ? undefined : track.variations.find((candidate) => candidate.key === key);
+    const section = reading.sections[sectionIndex];
+    if (variation === undefined || variation.kind !== 'fixed' || section === undefined) return null;
+    const id = `${sectionIndex}\u0000${pairKey(trackName, key)}`;
+    if (!made.has(id)) {
+      const entry = byPair.get(pairKey(trackName, key));
+      if (entry === undefined) throw new Error(`Moontide: the fit answer has nothing for variation '${String(key)}' of track '${String(trackName)}'.`);
+      const harmony = harmonies[sectionIndex];
+      const fit = fitOf({ masks: entry.masks, length: section.length, harmony, readReason: entry.reason ?? null });
+      const words = fitText(fit, {
+        track: trackName,
+        section: section.name,
+        variation: key,
+        fixedHarmony: variation.fixedHarmony,
+        sectionHarmonyText: harmony.text ?? '',
+      });
+      made.set(id, { ...fit, ...words, outsideText: fit.state === 'does-not-fit' ? fit.outside.join(', ') : null });
+    }
+    return made.get(id);
+  };
+}