moontide-mcp 2.0.1 → 2.1.0

package/page/note-edit.js

@@ -0,0 +1,267 @@
+// Pure module for Moontide's browser page: the edit of one note on the Timeline. It turns the token a note leads back to
+// into its neighbour a semitone away, builds the one-token edit list and writes it through the page's shared rewrite path
+// after the page has read the edited track back. The text written is built from a closed grammar (a note letter, its
+// accidentals, an octave digit, or a number) and never from free text, and the rest of the code stays byte for byte as it
+// was. Nothing here touches the DOM or a global: the write goes through the dependencies it is given, so node:test drives
+// it with fakes and page/main.js passes the real ones.
+
+import { applyEdits } from './mixer-rewrite.js';
+import { compareReadBack, sameTokenEvents } from './note-locate.js';
+import { noteHistoryLabel } from './note-panel.js';
+import { NOTE_NAME_TOKEN, noteNameToMidi } from './timeline.js';
+
+/** The reasons an edit is refused by this module (the shared rewrite path has its own). */
+export const NOTE_EDIT_REFUSALS = Object.freeze(['stale', 'read-back']);
+
+/** Raised to stop an edit before anything is written; `reason` is one of NOTE_EDIT_REFUSALS. */
+export class NoteEditStop extends Error {
+  constructor(reason) {
+    if (!NOTE_EDIT_REFUSALS.includes(reason)) throw new Error(`Moontide: unknown note edit refusal '${String(reason)}'.`);
+    super(`Moontide: the note edit stopped (${reason}).`);
+    this.name = 'NoteEditStop';
+    this.reason = reason;
+  }
+}
+
+/** The token that stands for a rest in a mini-notation string: a slot that plays nothing and keeps the step count. */
+export const REST_TOKEN = '~';
+
+/** The lowest and the highest note number. */
+const LOWEST_NOTE = 0;
+const HIGHEST_NOTE = 127;
+
+/** The octave a note name is in when it has no digit: the default of the pinned Strudel. */
+const DEFAULT_OCTAVE = 3;
+
+const NUMBER_TOKEN = /^-?\d+(\.\d+)?$/;
+
+const SHARP_NAMES = ['c', 'c#', 'd', 'd#', 'e', 'f', 'f#', 'g', 'g#', 'a', 'a#', 'b'];
+const FLAT_NAMES = ['c', 'db', 'd', 'eb', 'e', 'f', 'gb', 'g', 'ab', 'a', 'bb', 'b'];
+
+/**
+ * The token `delta` semitones from `text`, a note name (`c3`, `Eb`, `cs4`) or a number. Gives `{ text, midi }` or, at the end
+ * of the note range (0 to 127), `{ limit: 'lowest' | 'highest' }`. A name is respelled the way the old one was written: a
+ * flat becomes a flat, a sharp keeps its sign (`#` or `s`), the case of the letter stays, and an octave digit is left out only
+ * when the old token had none and the new note is in octave 3. A number stays a number. Text that is neither throws.
+ */
+export function stepPitch(text, delta) {
+  if (typeof text !== 'string') throw new Error(`Moontide: a note token is text, got ${String(text)}.`);
+  if (!Number.isInteger(delta)) throw new Error(`Moontide: a pitch step is a whole number of semitones, got ${String(delta)}.`);
+  if (NUMBER_TOKEN.test(text)) {
+    const next = Math.round((Number(text) + delta) * 1e6) / 1e6;
+    if (next < LOWEST_NOTE) return { limit: 'lowest' };
+    if (next > HIGHEST_NOTE) return { limit: 'highest' };
+    return { text: String(next), midi: next };
+  }
+  const match = NOTE_NAME_TOKEN.exec(text);
+  const midi = match === null ? null : noteNameToMidi(text);
+  if (match === null || midi === null) throw new Error(`Moontide: '${text}' is neither a note name nor a number, so its pitch cannot be stepped.`);
+  const next = midi + delta;
+  if (next < LOWEST_NOTE) return { limit: 'lowest' };
+  if (next > HIGHEST_NOTE) return { limit: 'highest' };
+  const [, letter, accidentals, digits] = match;
+  const flat = /[bf]/.test(accidentals);
+  const names = flat ? FLAT_NAMES : SHARP_NAMES;
+  let name = names[next % 12];
+  if (name.length === 2) {
+    const sign = flat ? (accidentals.includes('f') ? 'f' : 'b') : accidentals.includes('s') ? 's' : '#';
+    name = name[0] + sign;
+  }
+  if (letter === letter.toUpperCase()) name = name[0].toUpperCase() + name.slice(1);
+  const octave = Math.floor(next / 12) - 1;
+  const written = digits === undefined && octave === DEFAULT_OCTAVE ? name : `${name}${octave}`;
+  return { text: written, midi: next };
+}
+
+/** The lowest and the highest velocity a step reaches, and the size of a step. */
+const LOWEST_VELOCITY = 0.1;
+const HIGHEST_VELOCITY = 1;
+const VELOCITY_STEP = 0.1;
+
+const round2 = (value) => Math.round(value * 100) / 100;
+const round3 = (value) => Math.round(value * 1000) / 1000;
+
+/**
+ * The velocity `steps` steps of 0.10 from `shown`, kept between 0.10 and 1.00, in two decimals. A velocity already at an end
+ * stays there when the step goes further out, so a step never moves a velocity the wrong way.
+ */
+export function velocityTarget({ shown, steps }) {
+  if (!Number.isInteger(steps)) throw new Error(`Moontide: a velocity step is a whole number of steps, got ${String(steps)}.`);
+  const now = round2(shown);
+  if (steps > 0 && now >= HIGHEST_VELOCITY) return now;
+  if (steps < 0 && now <= LOWEST_VELOCITY) return now;
+  return Math.max(LOWEST_VELOCITY, Math.min(HIGHEST_VELOCITY, round2(now + steps * VELOCITY_STEP)));
+}
+
+/**
+ * The velocity token that makes a note play `steps` steps of 0.10 louder (softer when negative) than the `shown` velocity,
+ * which is gain times the velocity written. Gives `{ token, target }` (`token` is the number to write, `target` the velocity
+ * that will be shown: the token is `target / gain` in three decimals, so on a browser lane at the default gain 0.8 it may
+ * be above 1), `{ limit: 'lowest' | 'highest' }` when the velocity is already at that end, or `{ fixed: true }` when no token
+ * can give the target: the gain is 0 or not a finite number, or the rounded token does not play as the target.
+ */
+export function velocityStep({ shown, gain, steps }) {
+  if (typeof shown !== 'number' || !Number.isFinite(shown)) throw new Error(`Moontide: the velocity shown is a finite number, got ${String(shown)}.`);
+  const target = velocityTarget({ shown, steps });
+  if (target === round2(shown)) return { limit: steps > 0 ? 'highest' : 'lowest' };
+  if (typeof gain !== 'number' || !Number.isFinite(gain) || gain <= 0) return { fixed: true };
+  const token = round3(target / gain);
+  if (!(token > 0) || !Number.isFinite(token) || round2(gain * token) !== target) return { fixed: true };
+  return { token: String(token), target };
+}
+
+/**
+ * The edit list that replaces `token` (`{ start, end, text }`, read from `code`) by `insert`: one `{ from, to, insert }`. The
+ * code at the token's place must be the token's text; anything else throws, because the place no longer belongs to the code.
+ */
+export function tokenEdit(code, token, insert) {
+  if (typeof insert !== 'string' || insert === '') throw new Error('Moontide: a token edit needs the text to write.');
+  if (code.slice(token.start, token.end) !== token.text) {
+    throw new Error(`Moontide: the code at ${token.start} to ${token.end} is not the token '${token.text}' any more.`);
+  }
+  return [{ from: token.start, to: token.end, insert }];
+}
+
+/**
+ * Writes one edit of the note the person saw. `seen` is `{ code, trackIndex, track, event, events, token, pageStart,
+ * velocity, places, placesWindow }` as they saw it (`events` the lane as drawn, `event` the note, `token` its place in `code`,
+ * `perCycle` how many notes the token draws in each cycle in a piece without a structure, `velocity` what page/note-locate.js says of its velocity, `places` what the page worked out of where the token plays: a
+ * promise or a value of `{ count, sections, onPage, events }`, absent for a piece without a structure, and `placesWindow` the
+ * `{ from, to }` stretch of the structure that `events` are the notes of, or null; `velocityPlaces` and `velocityWindow` are the same for the
+ * number that holds the velocity, which a velocity edit counts and reads back over the whole stretch just as a pitch does), `change` is `{ kind: 'pitch', semitones }`,
+ * `{ kind: 'rest' }` or `{ kind: 'velocity', steps }` (a whole number of steps of 0.10) and `deps` is `{ readBack(code, span)
+ * -> promise of the track's events over the drawn page, or over `span` (`{ from, to }`) when one is given, apply(request)
+ * (the shared rewrite path), timing, autostart, record(code, label), whenFinished(record, fn), activeCode() }`.
+ *
+ * The count of places is awaited before anything is built, so an edit is never written without it, and the result and the
+ * history entry carry it when it is above 1 (a velocity also carries how many notes of the page share its number). The edited code
+ * is read back first: the edit is written only when the read-back shows the same notes at the same times
+ * with the new pitch on the notes of the token (without them for a rest, or playing the new velocity for a velocity) and
+ * nothing else changed, over the drawn page and over the whole stretch the places were counted on, so
+ * an edit that would change a note outside the places it named is refused (a velocity number that plays at another gain in another section is refused that way). The write itself refuses unless the code that plays is the code the note was read from. Resolves one
+ * outcome, each with `what` (`pitch`, `rest` or `velocity`): `{ kind: 'written', what, label, from, to }` (for a velocity
+ * `from` is the note and `to` the new velocity in two decimals), `{ kind: 'waiting', what, label, from, to, at, record }` (the
+ * change waits for its line and is recorded when it takes over), `{ kind: 'refused', reason }` (`stale`, `read-back`,
+ * `velocity-fixed` or a refusal of the rewrite path), `{ kind: 'refused', reason: 'error', afterWrite: true, error }` (an error
+ * the page did not plan for, thrown by the rewrite path or after it, so the code may have been written), `{ kind: 'refused',
+ * reason: 'error', error }` (the evaluation threw and the rewrite path put the editor text back: nothing was written), `{ kind: 'failed' }`
+ * (the edited code did not evaluate; the editor is set back), or `{ kind: 'unchanged' }` (`limit` says which end of the note
+ * range or of the velocities stopped it). An error before the write reaches the caller as it is: nothing was written then.
+ */
+export async function writeNoteEdit({ seen, change, deps }) {
+  const known = change !== null && typeof change === 'object' && (change.kind === 'pitch' || change.kind === 'rest' || change.kind === 'velocity');
+  if (!known) throw new Error(`Moontide: a note edit does not know the change ${JSON.stringify(change)}.`);
+  // What is replaced, by what, how the read-back judges it, and the words of the outcome and the history entry.
+  let place;
+  let insert;
+  let proofChange;
+  let to;
+  let label;
+  if (change.kind === 'pitch') {
+    const step = stepPitch(seen.token.text, change.semitones);
+    if (step.limit !== undefined) return { kind: 'unchanged', what: 'pitch', limit: step.limit };
+    place = seen.token;
+    insert = step.text;
+    proofChange = { kind: 'pitch', midi: step.midi };
+    to = step.text;
+    label = noteHistoryLabel({ track: seen.track, from: seen.token.text, to: step.text });
+  } else if (change.kind === 'rest') {
+    place = seen.token;
+    insert = REST_TOKEN;
+    proofChange = { kind: 'rest' };
+    to = REST_TOKEN;
+    label = noteHistoryLabel({ track: seen.track, from: seen.token.text, rest: true });
+  } else {
+    const velocity = seen.velocity;
+    if (velocity === undefined || velocity === null || velocity.writable !== true) return { kind: 'refused', reason: 'velocity-fixed' };
+    const step = velocityStep({ shown: velocity.shown, gain: velocity.gain, steps: change.steps });
+    if (step.limit !== undefined) return { kind: 'unchanged', what: 'velocity', limit: step.limit };
+    if (step.fixed === true) return { kind: 'refused', reason: 'velocity-fixed' };
+    place = velocity.token;
+    insert = step.token;
+    proofChange = { kind: 'velocity', target: step.target, gain: velocity.gain };
+    to = step.target.toFixed(2);
+    label = noteHistoryLabel({ track: seen.track, from: seen.token.text, velocity: step.target });
+  }
+  // Where the token plays is known before anything is written: a gesture made while it is still being counted waits for it here. A
+  // velocity edit is about the number that holds the velocity, which may play in other places than the pitch token does.
+  const counting = change.kind === 'velocity' ? seen.velocityPlaces : seen.places;
+  const stretch = change.kind === 'velocity' ? seen.velocityWindow : seen.placesWindow;
+  let places = null;
+  if (counting !== undefined && counting !== null) {
+    try {
+      places = await counting;
+    } catch (error) {
+      return { kind: 'refused', reason: 'read-back', error };
+    }
+  }
+  const edits = tokenEdit(seen.code, place, insert);
+  const code = applyEdits(seen.code, edits);
+  // Every kind of edit changes every note of its token, so the stretch the places were counted on is read back as well.
+  const span = places !== null && stretch !== undefined && stretch !== null ? stretch : null;
+  let after;
+  let afterWindow = null;
+  try {
+    after = await deps.readBack(code);
+    if (span !== null) afterWindow = await deps.readBack(code, span);
+  } catch (error) {
+    return { kind: 'refused', reason: 'read-back', error };
+  }
+  const proof = compareReadBack({ before: seen.events, after, token: place, change: proofChange });
+  if (!proof.ok) return { kind: 'refused', reason: 'read-back', why: proof.why };
+  if (span !== null) {
+    const wider = compareReadBack({ before: places.events, after: afterWindow, token: place, change: proofChange });
+    if (!wider.ok) return { kind: 'refused', reason: 'read-back', why: `places-${wider.why}` };
+  }
+  // What the result and the history entry add: where the token plays, or how many notes of the page share the velocity.
+  const count = places === null ? (change.kind === 'velocity' ? 0 : (seen.perCycle ?? 0)) : places.count;
+  const onPage = places !== null && places.onPage === true;
+  const notes = change.kind === 'velocity' ? sameTokenEvents({ events: seen.events, token: place }).length : 0;
+  if (change.kind === 'pitch') label = noteHistoryLabel({ track: seen.track, from: seen.token.text, to, places: count, onPage });
+  else if (change.kind === 'rest') label = noteHistoryLabel({ track: seen.track, from: seen.token.text, rest: true, places: count, onPage });
+  else label = noteHistoryLabel({ track: seen.track, from: seen.token.text, velocity: proofChange.target, places: count, onPage });
+  const told = (outcome) => {
+    if (count > 1) {
+      outcome.places = count;
+      if (onPage) outcome.onPage = true;
+    }
+    if (notes > 1) outcome.notes = notes;
+    return outcome;
+  };
+
+  let result;
+  try {
+    result = await deps.apply({
+      timing: deps.timing,
+      autostart: deps.autostart,
+      flash: false,
+      build(base) {
+        // The place belongs to the code the note was read from and to no other.
+        if (base !== seen.code) throw new NoteEditStop('stale');
+        return { code, edits };
+      },
+    });
+  } catch (error) {
+    if (error instanceof NoteEditStop) return { kind: 'refused', reason: error.reason };
+    // An evaluation that threw after which the rewrite path put the editor text back: nothing was written or armed.
+    if (error !== null && typeof error === 'object' && error.restored === true) return { kind: 'refused', reason: 'error', error };
+    // The rewrite path may have set the editor text or evaluated it before it threw: the code may have changed.
+    return { kind: 'refused', reason: 'error', afterWrite: true, error };
+  }
+  if (result.status === 'refused') return { kind: 'refused', reason: result.reason };
+  if (result.status === 'unchanged') return { kind: 'unchanged', what: change.kind };
+  if (result.status === 'failed') return { kind: 'failed' };
+
+  // The code is written from here on: an error now is told as one that came after the write.
+  try {
+    const deferred = result.run.deferred;
+    if (deferred === null || deferred === undefined) {
+      deps.record(deps.activeCode(), label);
+      return told({ kind: 'written', what: change.kind, label, from: seen.token.text, to });
+    }
+    deps.whenFinished(deferred, () => deps.record(typeof deferred.code === 'string' ? deferred.code : deps.activeCode(), label));
+    return told({ kind: 'waiting', what: change.kind, label, from: seen.token.text, to, at: deps.timing.at, record: deferred });
+  } catch (error) {
+    return { kind: 'refused', reason: 'error', afterWrite: true, error };
+  }
+}

package/page/note-locate.js

@@ -0,0 +1,346 @@
+// Pure module for Moontide's browser page: how a note drawn on the Timeline leads back to one place in the code, and
+// whether that place may be rewritten. The pinned Strudel keeps, for each note it plays, the offsets of the strings it was
+// read from (`event.locations`, a list of { start, end }). Which of those offsets is the note's own pitch is found by
+// parsing the playing code: the string that holds an offset, and the call the string is an argument of (`note`, `n`,
+// `velocity`, ...), never the position of the offset in the list, which moves with the chain. A note may be edited only when
+// it leads back to exactly one double-quoted `note("...")` token, the code at it is the bare token, the pitch heard is the
+// token's own pitch and the token lies in the code of the track alone. Every other note is refused with one reason. The
+// offsets are good only against the exact code they were measured on, so nothing here caches across versions.
+// `parse` (acorn) is injected, as in page/tracks.js, and nothing here touches the DOM, so node:test and page/main.js import
+// the module without a build step.
+
+import { PARSE_OPTIONS } from './tracks.js';
+import { NOTE_NAME_TOKEN, eventKey, gainOf, noteNameToMidi, pitchOf, sameEvents, velocityOf } from './timeline.js';
+import { playingSection } from './song-grid-model.js';
+
+/** The reasons a note cannot be edited, in the order they are tried: the first that applies is the one given. */
+export const NOTE_REASONS = Object.freeze(['no-token', 'no-pitch', 'several', 'degrees', 'escape', 'shifted', 'outside', 'shared']);
+
+/** The characters a bare note token is made of; a token is the whole run of them around its place. */
+const TOKEN_CHAR = /[A-Za-z0-9#._-]/;
+
+/** A note written as a number: a whole number or a decimal. */
+const NUMBER_TOKEN = /^-?\d+(\.\d+)?$/;
+
+/**
+ * The name of the call a string is a direct argument of: the name of an identifier callee (`note("...")`) or the property
+ * of a non-computed member callee (`s("x").note("...")`). A string that is the object of a member (`"c3 e3".note()`) or sits
+ * anywhere else has no call: null.
+ */
+function callOf(node, parent) {
+  if (parent === null || parent.type !== 'CallExpression' || !parent.arguments.includes(node)) return null;
+  const { callee } = parent;
+  if (callee.type === 'Identifier') return callee.name;
+  if (callee.type === 'MemberExpression' && !callee.computed && callee.property.type === 'Identifier') return callee.property.name;
+  return null;
+}
+
+/**
+ * Reads the playing code once: `strings` are the string literals the pinned Strudel gives locations to (double-quoted
+ * strings and untagged template literals; a single-quoted string carries no location and is left out), sorted by start,
+ * each `{ start, end, raw, call }`; `declarations` are the top-level const, let and var declarators with an initializer, each
+ * `{ name, start, end }` over the initializer; `references` maps a name to the offsets of the identifiers that read it.
+ */
+export function indexCode(code, { parse }) {
+  const ast = parse(code, PARSE_OPTIONS);
+  const strings = [];
+  const declarations = [];
+  const references = new Map();
+  const visit = (node, parent) => {
+    if (!node || typeof node.type !== 'string') return;
+    if (node.type === 'Literal' && typeof node.value === 'string' && typeof node.raw === 'string' && node.raw.startsWith('"')) {
+      strings.push({ start: node.start, end: node.end, raw: node.raw, call: callOf(node, parent) });
+      return;
+    }
+    if (node.type === 'TemplateLiteral' && (parent === null || parent.type !== 'TaggedTemplateExpression')) {
+      strings.push({ start: node.start, end: node.end, raw: code.slice(node.start, node.end), call: callOf(node, parent) });
+      return;
+    }
+    if (node.type === 'Identifier') {
+      const isPropertyName = parent !== null && parent.type === 'MemberExpression' && parent.property === node && !parent.computed;
+      const isKey = parent !== null && parent.type === 'Property' && parent.key === node && !parent.computed && !parent.shorthand;
+      if (!isPropertyName && !isKey) {
+        if (!references.has(node.name)) references.set(node.name, []);
+        references.get(node.name).push(node.start);
+      }
+      return;
+    }
+    for (const key in node) {
+      if (key === 'parent') continue;
+      const value = node[key];
+      if (Array.isArray(value)) {
+        for (const child of value) visit(child, node);
+      } else if (value && typeof value.type === 'string') {
+        visit(value, node);
+      }
+    }
+  };
+  visit(ast, null);
+  strings.sort((a, b) => a.start - b.start);
+  for (const statement of ast.body) {
+    if (statement.type !== 'VariableDeclaration') continue;
+    for (const declarator of statement.declarations) {
+      if (declarator.id.type === 'Identifier' && declarator.init) {
+        declarations.push({ name: declarator.id.name, start: declarator.init.start, end: declarator.init.end });
+      }
+    }
+  }
+  return { strings, declarations, references };
+}
+
+/** The string literal that holds the place `location`, or null (a place in no string, such as a value made by code). */
+function stringHolding(index, location) {
+  const { strings } = index;
+  let low = 0;
+  let high = strings.length - 1;
+  let found = -1;
+  while (low <= high) {
+    const middle = (low + high) >> 1;
+    if (strings[middle].start <= location.start) {
+      found = middle;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+  if (found === -1) return null;
+  const candidate = strings[found];
+  return location.end <= candidate.end ? candidate : null;
+}
+
+/**
+ * Where a track's own code lies: `{ index, kind, start, end }`. `kind` is 'variations' with the range of the track's own
+ * variation const (page/structure.js constRange) when the piece declares a song the page can read and the track is built by
+ * play(); for every other track it is 'statement' with the range of the track's own expression.
+ */
+export function trackScope({ track, reading }) {
+  if (reading !== null && reading !== undefined && reading.state === 'read') {
+    const play = reading.tracks.find((candidate) => candidate.index === track.index);
+    if (play !== undefined && play.constRange !== undefined && play.constRange !== null) {
+      return { index: track.index, kind: 'variations', start: play.constRange.start, end: play.constRange.end };
+    }
+  }
+  return { index: track.index, kind: 'statement', start: track.start, end: track.end };
+}
+
+/**
+ * Tells how many tracks read the top-level name `name`: a track reads it when an identifier with that name lies in its own
+ * code, or in the initializer of a top-level declaration that is read in turn. `scopes` is the scope of every track.
+ */
+export function readerCounter(index, scopes) {
+  const cache = new Map();
+  const tracksReading = (name, visiting) => {
+    const found = new Set();
+    if (visiting.has(name)) return found;
+    visiting.add(name);
+    const offsets = index.references.get(name) ?? [];
+    for (const scope of scopes) {
+      if (offsets.some((offset) => offset >= scope.start && offset < scope.end)) found.add(scope.index);
+    }
+    for (const declaration of index.declarations) {
+      if (declaration.name === name) continue;
+      if (offsets.some((offset) => offset >= declaration.start && offset < declaration.end)) {
+        for (const track of tracksReading(declaration.name, visiting)) found.add(track);
+      }
+    }
+    return found;
+  };
+  return (name) => {
+    if (!cache.has(name)) cache.set(name, tracksReading(name, new Set()).size);
+    return cache.get(name);
+  };
+}
+
+/** True when the code at `location` is a whole token: the run of token characters around it begins and ends there. */
+function isBareToken(code, location) {
+  if (!(location.end > location.start) || location.end > code.length) return false;
+  let from = location.start;
+  while (from > 0 && TOKEN_CHAR.test(code[from - 1])) from -= 1;
+  let to = location.end;
+  while (to < code.length && TOKEN_CHAR.test(code[to])) to += 1;
+  return from === location.start && to === location.end;
+}
+
+/**
+ * The note number a token stands for (a number or a note name spelled the way Strudel plays it and the page steps it), or null for
+ * anything else. A name the page reads but Strudel does not play (a capital accidental, `EB3`) is null, so it is never offered for an edit.
+ */
+function tokenPitch(text) {
+  if (NUMBER_TOKEN.test(text)) return Number(text);
+  return NOTE_NAME_TOKEN.test(text) ? noteNameToMidi(text) : null;
+}
+
+/** The same places once each, in the order they came. */
+function distinctLocations(locations) {
+  const seen = new Set();
+  const out = [];
+  for (const location of locations) {
+    const key = `${location.start}:${location.end}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(location);
+  }
+  return out;
+}
+
+/**
+ * Says whether the note `event` (`{ begin, end, value, locations }`) can be edited. Gives `{ editable: true, token: { start,
+ * end, text }, velocity }`, the one place in `code` that holds the note and what the page can do about its velocity, or
+ * `{ editable: false, reason }` with the first of NOTE_REASONS that applies. `index` is indexCode(code), `scope` the scope of
+ * the track the note belongs to, `scopes` the scope of every track, `readers(name)` how many tracks read the top-level name
+ * and `midi` whether the note is on a MIDI lane (its default gain differs). `velocity` is `{ writable: true, token, gain,
+ * shown }` when the velocity of the note comes from exactly one bare number in a double-quoted `velocity("...")` string in the
+ * track's own code whose value is the note's velocity and the gain is a finite number other than 0 (`shown` is the velocity
+ * the Timeline shows, gain times velocity); otherwise `{ writable: false }`.
+ */
+export function classifyNote({ code, index, event, scope, scopes, readers, midi = false }) {
+  const refuse = (reason) => ({ editable: false, reason });
+  const heard = pitchOf(event.value);
+  if (heard === null) return refuse('no-pitch');
+  const placed = distinctLocations(Array.isArray(event.locations) ? event.locations : [])
+    .map((location) => ({ location, string: stringHolding(index, location) }))
+    .filter((entry) => entry.string !== null);
+  // A velocity string, a double-quoted scale and the weighted mini clock add places in other calls: only note and n count.
+  const pitchPlaces = placed.filter((entry) => entry.string.call === 'note' || entry.string.call === 'n');
+  if (pitchPlaces.length === 0) return refuse('no-token');
+  if (pitchPlaces.length > 1) return refuse('several');
+  const { location, string } = pitchPlaces[0];
+  if (string.call === 'n') return refuse('degrees');
+  if (string.raw.includes('\\') || !isBareToken(code, location)) return refuse('escape');
+  const text = code.slice(location.start, location.end);
+  const own = tokenPitch(text);
+  if (own === null || own !== heard) return refuse('shifted');
+  const token = { start: location.start, end: location.end, text };
+  const holds = (candidate) => token.start >= candidate.start && token.end <= candidate.end;
+  if (holds(scope)) {
+    if (scopes.some((other) => other.index !== scope.index && holds(other))) return refuse('shared');
+    return { editable: true, token, velocity: velocityOfNote({ code, event, placed, scope, scopes, midi }) };
+  }
+  const declaration = index.declarations.find(holds);
+  return declaration !== undefined && readers(declaration.name) >= 2 ? refuse('shared') : refuse('outside');
+}
+
+/** The velocity part of an editable note's classification: see classifyNote. */
+function velocityOfNote({ code, event, placed, scope, scopes, midi }) {
+  const fixed = { writable: false };
+  const places = placed.filter((entry) => entry.string.call === 'velocity');
+  if (places.length !== 1) return fixed;
+  const { location } = places[0];
+  if (places[0].string.raw.includes('\\') || !isBareToken(code, location)) return fixed;
+  const text = code.slice(location.start, location.end);
+  if (!NUMBER_TOKEN.test(text)) return fixed;
+  const token = { start: location.start, end: location.end, text };
+  const holds = (candidate) => token.start >= candidate.start && token.end <= candidate.end;
+  if (!holds(scope) || scopes.some((other) => other.index !== scope.index && holds(other))) return fixed;
+  const value = event.value && typeof event.value === 'object' ? event.value : {};
+  if (typeof value.velocity !== 'number' || Number(text) !== value.velocity) return fixed;
+  const gain = gainOf(event.value, midi);
+  if (typeof gain !== 'number' || !Number.isFinite(gain) || gain === 0) return fixed;
+  const shown = velocityOf(event.value, midi);
+  if (shown === undefined) return fixed;
+  return { writable: true, token, gain, shown };
+}
+
+/** An event's key with one field of its value left out: the time and every other field. */
+function keyWithout(event, field) {
+  const value = event.value && typeof event.value === 'object' ? { ...event.value } : event.value;
+  if (value && typeof value === 'object') delete value[field];
+  return eventKey({ begin: event.begin, end: event.end, value });
+}
+
+/**
+ * Compares the lane's events before an edit with the same lane read back from the edited code. `token` is the token that
+ * was rewritten (the edit keeps its start) and `change` what was done to it: `{ kind: 'pitch', midi }`, `{ kind: 'rest' }`
+ * or `{ kind: 'velocity', target, gain }`. The edit is confirmed when the notes that carried the token are, at the same
+ * times, what the change says (a new pitch, gone, or a velocity that plays as `target`) with every other field unchanged, and
+ * every other note is the same in time, value and count. Gives `{ ok: true }` or `{ ok: false, why }`.
+ */
+export function compareReadBack({ before, after, token, change }) {
+  const known =
+    change !== null &&
+    typeof change === 'object' &&
+    ((change.kind === 'pitch' && Number.isFinite(change.midi)) ||
+      change.kind === 'rest' ||
+      (change.kind === 'velocity' && Number.isFinite(change.target) && Number.isFinite(change.gain)));
+  if (!known) throw new Error(`Moontide: the read-back does not know the change ${JSON.stringify(change)}.`);
+  const carries = (event) => Array.isArray(event.locations) && event.locations.some((place) => place.start === token.start);
+  const editedBefore = before.filter(carries);
+  const editedAfter = after.filter(carries);
+  if (editedBefore.length === 0) return { ok: false, why: 'no-edited-note' };
+  if (change.kind === 'rest') {
+    // A rest draws no note and keeps no place: every note that carried the token is gone.
+    if (editedAfter.length !== 0) return { ok: false, why: 'edited-count' };
+  } else {
+    if (editedBefore.length !== editedAfter.length) return { ok: false, why: 'edited-count' };
+    const field = change.kind === 'pitch' ? 'note' : 'velocity';
+    const expected = new Map();
+    for (const event of editedBefore) {
+      const key = keyWithout(event, field);
+      expected.set(key, (expected.get(key) ?? 0) + 1);
+    }
+    for (const event of editedAfter) {
+      if (change.kind === 'pitch') {
+        if (pitchOf(event.value) !== change.midi) return { ok: false, why: 'edited-pitch' };
+      } else {
+        const velocity = event.value && typeof event.value === 'object' ? event.value.velocity : undefined;
+        if (typeof velocity !== 'number' || Math.round(change.gain * velocity * 100) / 100 !== change.target) return { ok: false, why: 'edited-velocity' };
+      }
+      const key = keyWithout(event, field);
+      const count = expected.get(key);
+      if (!count) return { ok: false, why: 'edited-differs' };
+      if (count === 1) expected.delete(key);
+      else expected.set(key, count - 1);
+    }
+  }
+  if (!sameEvents(before.filter((event) => !carries(event)), after.filter((event) => !carries(event)))) {
+    return { ok: false, why: 'others-differ' };
+  }
+  return { ok: true };
+}
+
+/** The most cycles one pass of a structure may have for the page to count the places of a token over all of it. */
+export const PLACES_MAX_CYCLES = 1024;
+
+/** True when the note `event` carries a place that starts where `token` starts: it was read from that token. */
+function carriesToken(event, token) {
+  return Array.isArray(event.locations) && event.locations.some((place) => place.start === token.start);
+}
+
+/**
+ * Where a token plays in a song the page has read. `haps` are the notes of one track over a stretch of the structure, each
+ * `{ begin, locations }`, `token` the token `{ start }` and `reading` the read song. A place is a section entry (a column of the
+ * Song grid) holding a note that carries the token, found with the Song grid's own rule for the section that plays at a
+ * cycle, so a repeat of a variation inside one entry is not another place. Gives `{ count, sections }`: the number of
+ * distinct entries and the names of the sections they belong to, once each, in the order of the entries.
+ */
+export function placesOf({ haps, token, reading }) {
+  const entries = new Set();
+  for (const hap of haps) {
+    if (carriesToken(hap, token)) entries.add(playingSection(reading, hap.begin).index);
+  }
+  const ordered = [...entries].sort((a, b) => a - b);
+  const sections = [];
+  for (const index of ordered) {
+    const { name } = reading.sections[index];
+    if (!sections.includes(name)) sections.push(name);
+  }
+  return { count: ordered.length, sections };
+}
+
+/** How many of the `events` that begin in the whole cycle `cycle` carry the token: a token that draws several notes in a cycle. */
+export function perCycleCount({ events, token, cycle }) {
+  let count = 0;
+  for (const event of events) {
+    if (event.begin >= cycle - 1e-9 && event.begin < cycle + 1 - 1e-9 && carriesToken(event, token)) count += 1;
+  }
+  return count;
+}
+
+/** The indexes of the `events` of the drawn lane that carry the token, the selected note among them. */
+export function sameTokenEvents({ events, token }) {
+  const found = [];
+  events.forEach((event, index) => {
+    if (carriesToken(event, token)) found.push(index);
+  });
+  return found;
+}