moontide-mcp 2.0.2 → 2.2.0

package/page/jam-view.js

@@ -1,21 +1,25 @@
-// The Jam view's DOM: the message, the scale block, the seven degree chips, the
+// The Jam view's DOM: the message, the scale block with the line that says why a scale is proposed and the list of the scales that
+// fit (buttons that switch while one can be chosen, plain text when none can), the seven degree chips, the
 // status box, the coming-up rows and the piano, built with DOM methods only. Every text reaches
 // the page through textContent, title or setAttribute, never as markup: a part name comes from
 // the code and is not trusted. The view attaches no right-click listener: page/main.js owns the
 // only one. No DOM access at import time: main.js calls createJamView() with its document, so
 // this module can be loaded anywhere. The words and the model come from page/jam-model.js.
 
-import { JAM_COPY, statusAnnounceKey, noteDescriptor, pianoKeys, keyLabel, fretCells, fretUnits, legendEntries, STRING_NAMES, FRET_NUMBERS } from './jam-model.js';
+import { JAM_COPY, statusAnnounceKey, noteDescriptor, pianoKeys, keyLabel, keyTitle, fretCells, fretUnits, legendEntries, STRING_NAMES, FRET_NUMBERS } from './jam-model.js';
 
 const DEGREE_COUNT = 7;
 
 /**
  * Builds the Jam view's DOM once and returns `{ showMessage, render, setPreferences }`.
  * `onInstrumentChange(name)` is called with 'piano' or 'guitar' when the user picks the other
- * segment, `onChordTonesChange(checked)` when the user flips the Chord tones checkbox; the view
- * never touches browser storage, main.js owns the preferences.
+ * segment, `onChordTonesChange(checked)` when the user flips the Chord tones checkbox,
+ * `onScaleChoice({ setKey, key })` when the user picks a scale that is not the one in use (a click, or Enter or Space on
+ * the focused button); a handler that throws is caught and said once per set of candidates. The view never touches
+ * browser storage and never chooses: main.js owns the preferences and the choice.
  */
-export function createJamView({ document, onInstrumentChange, onChordTonesChange }) {
+export function createJamView({ document, onInstrumentChange, onChordTonesChange, onScaleChoice }) {
+  if (typeof onScaleChoice !== 'function') throw new Error('Moontide: createJamView needs onScaleChoice, a function that takes { setKey, key }.');
   const jamView = document.getElementById('jam-view');
   const jamMessage = document.getElementById('jam-message');
   const jamMessageText = document.getElementById('jam-message-text');
@@ -24,9 +28,18 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
   const jamDeclared = document.getElementById('jam-declared');
   const jamDeclaredLabel = document.getElementById('jam-declared-label');
   const jamDeclaredValue = document.getElementById('jam-declared-value');
+  const jamDeclaredSection = document.getElementById('jam-declared-section');
+  const jamScale = document.getElementById('jam-scale');
   const jamScaleLabel = document.getElementById('jam-scale-label');
   const jamScaleName = document.getElementById('jam-scale-name');
   const jamScaleSub = document.getElementById('jam-scale-sub');
+  const jamReason = document.getElementById('jam-reason');
+  const jamReasonLead = document.getElementById('jam-reason-lead');
+  const jamReasonRest = document.getElementById('jam-reason-rest');
+  const jamCandidates = document.getElementById('jam-candidates');
+  const jamCandidatesLabel = document.getElementById('jam-candidates-label');
+  const jamCandidateList = document.getElementById('jam-candidate-list');
+  const jamCandidatesMore = document.getElementById('jam-candidates-more');
   const jamDegrees = document.getElementById('jam-degrees');
   const jamStatus = document.getElementById('jam-status');
   const jamStatusLead = document.getElementById('jam-status-lead');
@@ -104,7 +117,7 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
     labelEl.className = 'jam-key-label';
     el.append(labelEl);
     jamPiano.append(el);
-    return { key, el, labelEl, shown: { note: null, role: null, root: null, chord: null, label: null } };
+    return { key, el, labelEl, shown: { note: null, role: null, root: null, chord: null, label: null, title: '' } };
   });
   let shownPianoLabel = null;
 
@@ -162,9 +175,15 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
   }
 
   let shownDeclaredOn = false;
+  let shownLabelOn = null;
+  let shownSource = null;
+  let shownReasonOn = null;
+  let shownReasonLead = null;
+  let shownReasonRest = null;
   let shownDeclaredKind = null;
   let shownDeclaredText = null;
   let shownDeclaredTitle = null;
+  let shownDeclaredSection = null;
   let shownName = null;
   let shownKind = null;
   let shownSub = null;
@@ -197,14 +216,13 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
     lastModel = null;
   }
 
-  // The Declared line and the Heard label: both shown with a declaration, both hidden without one. The
-  // text comes from the code, so it goes in as text only, and only when it changed.
+  // The Declared line: shown with a declaration, hidden without one. The text comes from the code, so it goes
+  // in as text only, and only when it changed.
   function renderDeclared(declared) {
     if (declared === undefined) throw new Error('Moontide: a ready Jam model needs its declared field (null without a declaration).');
     const on = declared !== null;
     if (on !== shownDeclaredOn) {
       jamDeclared.hidden = !on;
-      jamScaleLabel.hidden = !on;
       shownDeclaredOn = on;
     }
     if (!on) return;
@@ -222,6 +240,150 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
     }
   }
 
+  // Where the scale in use came from. The Heard label shows only with a declaration and only for a scale that was heard: it
+  // would be false for a proposed one. The source rides on #jam-scale for tests and the probe.
+  function renderSource(declared, scaleSource) {
+    if (scaleSource !== 'heard' && scaleSource !== 'proposed' && scaleSource !== 'chosen') {
+      throw new Error(`Moontide: a ready Jam model needs a scale source of heard, proposed or chosen, got '${String(scaleSource)}'.`);
+    }
+    const labelOn = declared !== null && scaleSource === 'heard';
+    if (labelOn !== shownLabelOn) {
+      jamScaleLabel.hidden = !labelOn;
+      shownLabelOn = labelOn;
+    }
+    if (scaleSource !== shownSource) {
+      jamScale.dataset.source = scaleSource;
+      shownSource = scaleSource;
+    }
+  }
+
+  // The line that says why the scale is proposed: a lead word and one sentence, written only when they changed so the
+  // polite live region reads a proposal once and never per tick. Hiding it clears both texts, so a proposal that comes back
+  // later is read again.
+  function renderReason(reason) {
+    if (reason === undefined) throw new Error('Moontide: a ready Jam model needs its reason field (null for a scale that was heard).');
+    const on = reason !== null;
+    const lead = on ? reason.lead : '';
+    const rest = on ? reason.rest : '';
+    if (lead !== shownReasonLead) {
+      jamReasonLead.textContent = lead;
+      shownReasonLead = lead;
+    }
+    if (rest !== shownReasonRest) {
+      jamReasonRest.textContent = rest;
+      shownReasonRest = rest;
+    }
+    if (on !== shownReasonOn) {
+      jamReason.hidden = !on;
+      shownReasonOn = on;
+    }
+  }
+
+  // The scales that fit. Pick mode draws one button per scale and exactly one is pressed; list mode draws plain items in a
+  // list. The items are rebuilt only when the mode, the set of candidates or the names drawn changed; a switch of the
+  // pressed scale rewrites aria-pressed in place, so the button just clicked keeps focus (and a rebuild gives focus back to
+  // the button of the same scale). Each button reads its own key
+  // from its closure, never from the markup, and a click on the pressed one does nothing. A choice the page refuses is said
+  // once per set of candidates, not once per click.
+  let shownCandidatesOn = null;
+  let shownCandidatesMode = null;
+  let shownCandidatesCaption = null;
+  let shownCandidatesMore = null;
+  let shownCandidatesKey = null;
+  let candidateRefs = [];
+  const choiceReportedFor = new Set();
+
+  function chooseCandidate(setKey, ref) {
+    if (ref.pressed) return;
+    try {
+      onScaleChoice({ setKey, key: ref.key });
+    } catch (err) {
+      if (!choiceReportedFor.has(setKey)) {
+        choiceReportedFor.add(setKey);
+        console.error('Moontide: the Jam view could not switch the scale:', err);
+      }
+    }
+  }
+
+  function buildCandidates(candidates) {
+    // The buttons are replaced, so a focused one would be lost: note its key now and give focus to the new button of the
+    // same scale (a pick can change which scale sits in the last place drawn when more than eight fit).
+    const focused = candidateRefs.find((ref) => ref.el === document.activeElement);
+    candidateRefs = candidates.items.map((item) => {
+      const pick = candidates.mode === 'pick';
+      const el = document.createElement(pick ? 'button' : 'span');
+      el.className = 'jam-candidate';
+      el.textContent = item.name;
+      const ref = { el, key: item.key, pressed: pick && item.pressed };
+      if (pick) {
+        el.type = 'button';
+        el.setAttribute('aria-pressed', String(item.pressed));
+        el.addEventListener('click', () => chooseCandidate(candidates.setKey, ref));
+      } else {
+        el.setAttribute('role', 'listitem');
+      }
+      return ref;
+    });
+    if (candidates.mode === 'list') jamCandidateList.setAttribute('role', 'list');
+    else jamCandidateList.removeAttribute('role');
+    jamCandidateList.replaceChildren(...candidateRefs.map((ref) => ref.el));
+    if (focused !== undefined) candidateRefs.find((ref) => ref.key === focused.key)?.el.focus();
+  }
+
+  function renderCandidates(candidates) {
+    if (candidates === undefined) throw new Error('Moontide: a ready Jam model needs its candidates field (null for a scale that was heard).');
+    const on = candidates !== null;
+    if (on !== shownCandidatesOn) {
+      jamCandidates.hidden = !on;
+      shownCandidatesOn = on;
+    }
+    if (!on) return;
+    if (candidates.mode !== 'pick' && candidates.mode !== 'list') {
+      throw new Error(`Moontide: the Jam view cannot draw scales that fit in the mode '${String(candidates.mode)}'.`);
+    }
+    if (candidates.mode !== shownCandidatesMode) {
+      jamCandidates.dataset.mode = candidates.mode;
+      shownCandidatesMode = candidates.mode;
+    }
+    if (candidates.caption !== shownCandidatesCaption) {
+      jamCandidatesLabel.textContent = candidates.caption;
+      shownCandidatesCaption = candidates.caption;
+    }
+    if (candidates.more !== shownCandidatesMore) {
+      jamCandidatesMore.textContent = candidates.more ?? '';
+      jamCandidatesMore.hidden = candidates.more === null;
+      shownCandidatesMore = candidates.more;
+    }
+    const listKey = [candidates.mode, candidates.setKey, ...candidates.items.map((item) => item.key)].join('\n');
+    if (listKey !== shownCandidatesKey) {
+      buildCandidates(candidates);
+      shownCandidatesKey = listKey;
+      return;
+    }
+    if (candidates.mode !== 'pick') return;
+    candidates.items.forEach((item, i) => {
+      const ref = candidateRefs[i];
+      if (ref.pressed !== item.pressed) {
+        ref.el.setAttribute('aria-pressed', String(item.pressed));
+        ref.pressed = item.pressed;
+      }
+    });
+  }
+
+  // The section the Declared line speaks for: its words after the value, hidden for a piece without sections.
+  function renderDeclaredSection(section) {
+    if (section === undefined) throw new Error('Moontide: a ready Jam model needs its section field (null without sections).');
+    if (section === shownDeclaredSection) return;
+    if (section === null) {
+      jamDeclaredSection.textContent = '';
+      jamDeclaredSection.hidden = true;
+    } else {
+      jamDeclaredSection.textContent = section;
+      jamDeclaredSection.hidden = false;
+    }
+    shownDeclaredSection = section;
+  }
+
   function renderScale(scale, degrees) {
     if (scale.text !== shownName) {
       jamScaleName.textContent = scale.text;
@@ -360,7 +522,7 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
     });
   }
 
-  // The piano: each key's note, role, avoided-root ring and label, written only when changed.
+  // The piano: each key's note, role, avoided-root ring, label and hover title, written only when changed.
   function renderInstrument(instrument) {
     const { roles, names, rootPc, chordPcs } = instrument;
     for (const ref of keys) {
@@ -392,6 +554,12 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
         ref.labelEl.textContent = label;
         ref.shown.label = label;
       }
+      const title = keyTitle(ref.key, roles, names, chordPcs, rootPc);
+      if (ref.shown.title !== title) {
+        if (title === '') ref.el.removeAttribute('title');
+        else ref.el.setAttribute('title', title);
+        ref.shown.title = title;
+      }
     }
     if (instrument.pianoLabel !== shownPianoLabel) {
       jamPiano.setAttribute('aria-label', instrument.pianoLabel);
@@ -477,6 +645,10 @@ export function createJamView({ document, onInstrumentChange, onChordTonesChange
     }
     lastModel = model;
     renderDeclared(model.declared);
+    renderDeclaredSection(model.section);
+    renderSource(model.declared, model.scaleSource);
+    renderReason(model.reason);
+    renderCandidates(model.candidates);
     renderScale(model.scale, model.degrees);
     renderStatus(model.status);
     if (model.paused !== shownPaused) {

package/page/lights.js

@@ -0,0 +1,300 @@
+// The lights of the Mixer: the state behind the small dot on every track strip and every group.
+//
+// Pure: no DOM, and the clocks are handed in, so node:test drives it with fake time. The page tells it which tracks
+// the Mixer shows (setLayout), which notes were played (noteSeen) and, once per animation frame, asks which lights
+// changed (frame). It never draws: the Mixer view writes what frame returns.
+//
+// What a light shows. With motion on, a light goes to full in the first frame at or after the moment its note is
+// heard and falls in a straight line to nothing over LIGHT_FADE_MS; a note that comes while it fades starts it over.
+// With motion off nothing blinks: a light stays lit while a note was heard within the last cycle. A group's light
+// shows the brightest of the tracks below it, at any depth, folded or not.
+//
+// Why a note is kept as a time to convert, not as a converted time. A browser sound is due at a time on the audio
+// clock; it is heard later, after the output delay, and the page maps one to the other from the audio context's
+// output timestamp. That timestamp is read once per frame (not once per note: at 40 tracks that would be hundreds of
+// reads a second), so the note waits here as its audio time and `toPerf` turns it into the page clock when a frame runs.
+// A MIDI note already has the time its port got and needs no conversion.
+//
+// Why frame returns only what changed: the page writes to the document only for those lights, in steps of 1/64 of
+// the brightness, so a fading light does not rewrite the same value and 40 tracks stay far under a frame's budget.
+//
+// The two offsets start at 0 and the fade at 180 ms. They are meant to be tuned by ear on real hardware.
+
+import { FRESH_PAIR_MAX_AGE_MS } from './midi-clock.js';
+
+/** How long a light takes to fall from full to dark, with motion on. */
+export const LIGHT_FADE_MS = 180;
+/** Added to the moment a browser sound is heard (positive: later). */
+export const BROWSER_LIGHT_OFFSET_MS = 0;
+/** Added to the timestamp a MIDI note got (positive: later). */
+export const MIDI_LIGHT_OFFSET_MS = 0;
+/** A light's brightness is rounded to this many steps from dark to full. */
+export const LIGHT_STEPS = 64;
+/** The most notes a track keeps waiting; the oldest goes first. */
+export const MAX_PENDING_NOTES = 256;
+
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+
+/**
+ * Maps the audio time a note is due to the moment it is heard, on the page clock (performance.now()).
+ * `pair` is the audio context's output timestamp `{ contextTime, performanceTime }`; while it is fresh the mapping goes
+ * through it. Otherwise (right after the context starts, or while it is suspended) the time is shifted by the context's
+ * own latencies, a missing latency counting as 0.
+ */
+export function heardMapper({ pair, currentTime, baseLatency, outputLatency, perfNow }) {
+  if (!isFiniteNumber(perfNow)) {
+    throw new Error(`Moontide: the lights need the page clock as a number, got ${String(perfNow)}.`);
+  }
+  const fresh =
+    pair !== null &&
+    typeof pair === 'object' &&
+    isFiniteNumber(pair.contextTime) &&
+    isFiniteNumber(pair.performanceTime) &&
+    pair.contextTime > 0 &&
+    pair.performanceTime > 0 &&
+    perfNow - pair.performanceTime < FRESH_PAIR_MAX_AGE_MS;
+  if (fresh) {
+    return (target) => pair.performanceTime + (target - pair.contextTime) * 1000 + BROWSER_LIGHT_OFFSET_MS;
+  }
+  if (!isFiniteNumber(currentTime)) {
+    throw new Error(`Moontide: the lights need the audio clock as a number, got ${String(currentTime)}.`);
+  }
+  const latencyMs = ((isFiniteNumber(baseLatency) ? baseLatency : 0) + (isFiniteNumber(outputLatency) ? outputLatency : 0)) * 1000;
+  return (target) => perfNow + (target - currentTime) * 1000 + latencyMs + BROWSER_LIGHT_OFFSET_MS;
+}
+
+/** Whether `cps` can drive the lights: a number above 0. A piece can set the tempo to 0 and set it back later. */
+export function usableTempo(cps) {
+  return isFiniteNumber(cps) && cps > 0;
+}
+
+/**
+ * The audio context's output timestamp for `heardMapper`, or null when this browser has no such method; the mapper then
+ * shifts a time by the context's own latencies, as it does while the pair is stale.
+ */
+export function readOutputPair(audio) {
+  return typeof audio.getOutputTimestamp === 'function' ? audio.getOutputTimestamp() : null;
+}
+
+/**
+ * What the lights need to know about a Mixer model: `{ tracks, ancestors }`. `tracks` has one entry
+ * `{ key, id, sounding, midi }` for every strip that has a light key (`key` is what a note names, `id` the strip's identity,
+ * which the view finds the light by, `midi` whether the strip plays a MIDI instrument). A strip that plays MIDI cannot sound in a browser without Web MIDI, so it counts as
+ * not sounding there. `ancestors` maps a strip's id to the keys of the groups above it, outermost first. A model that
+ * is not ready gives an empty layout.
+ */
+export function lightLayout(model, { webMidi }) {
+  const tracks = [];
+  const ancestors = new Map();
+  if (model === null || typeof model !== 'object' || model.status !== 'ready') return { tracks, ancestors };
+  for (const strip of model.strips) {
+    if (strip.lightKey === null || strip.lightKey === undefined) continue;
+    const playsMidi = (strip.midi !== null && strip.midi !== undefined) || strip.playsMidi === true;
+    tracks.push({ key: strip.lightKey, id: strip.identity, sounding: strip.sounding === true && (webMidi === true || !playsMidi), midi: playsMidi });
+  }
+  if (model.layout !== null && model.layout !== undefined) {
+    for (const group of model.layout.groups) {
+      for (const id of group.members) {
+        const above = ancestors.get(id);
+        if (above === undefined) ancestors.set(id, [group.key]);
+        else above.push(group.key);
+      }
+    }
+  }
+  return { tracks, ancestors };
+}
+
+/**
+ * The light state. `setLayout(layout)` says which tracks and groups exist (see lightLayout); `noteSeen(key, heard)` queues
+ * a note, `heard` being `{ at }` (a time on the page clock, in ms) or `{ target }` (an audio time, in seconds);
+ * `frame(ts, { motion, cps, toPerf })` lights what is due at `ts` and returns `[{ kind, id, value }]` for the lights whose
+ * value changed since the last frame; `reset()` forgets every note and every lit light; `forgetShown()` forgets only which
+ * values were handed out, so the next frame hands out every lit value again and still darkens a light that has gone out
+ * meanwhile (after the view rebuilt some of its lights);
+ * `playsMidi(key)` tells whether the strip that owns `key` plays a MIDI instrument (false for an unknown key).
+ */
+export function createLights() {
+  // key -> { id, sounding, midi }
+  let tracks = new Map();
+  // strip id -> keys of the groups above it
+  let ancestors = new Map();
+  // key -> the notes waiting to be heard, each { at } or { target }
+  const pending = new Map();
+  const pendingKeys = new Set();
+  // key -> { litAt, lastHeard }: when a track last lit in a frame, and the latest heard time among its notes
+  const states = new Map();
+  // The keys whose light may be lit now: the only ones a frame looks at.
+  const active = new Set();
+  // What the last frame returned that is not dark: key -> { id, value } for tracks, group key -> value for groups.
+  const shownTracks = new Map();
+  const shownGroups = new Map();
+  // Scratch maps of one frame, kept to write nothing new on the common path.
+  const trackValues = new Map();
+  const groupValues = new Map();
+
+  function forget(key) {
+    pending.delete(key);
+    pendingKeys.delete(key);
+    states.delete(key);
+    active.delete(key);
+  }
+
+  return {
+    setLayout(layout) {
+      if (layout === null || typeof layout !== 'object' || !Array.isArray(layout.tracks) || !(layout.ancestors instanceof Map)) {
+        throw new Error('Moontide: the lights need a layout of tracks and ancestors.');
+      }
+      const next = new Map();
+      // Strips can share a key (a muted copy `hats_` kept next to `hats`): the one that sounds owns the key, so the
+      // copy stays dark and the audible track blinks.
+      for (const track of layout.tracks) {
+        const known = next.get(track.key);
+        if (known !== undefined && known.sounding) continue;
+        next.set(track.key, { id: track.id, sounding: track.sounding === true, midi: track.midi === true });
+      }
+      tracks = next;
+      ancestors = layout.ancestors;
+      // A track that is gone or silent drops its notes and reads dark from the next frame on.
+      for (const key of [...pending.keys(), ...states.keys()]) {
+        const track = tracks.get(key);
+        if (track === undefined || !track.sounding) forget(key);
+      }
+    },
+
+    noteSeen(key, heard) {
+      const hasAt = heard !== null && typeof heard === 'object' && isFiniteNumber(heard.at);
+      const hasTarget = heard !== null && typeof heard === 'object' && isFiniteNumber(heard.target);
+      if (!hasAt && !hasTarget) {
+        throw new Error('Moontide: a note for the lights needs a heard time (at) or an audio time (target) that is a number.');
+      }
+      const track = tracks.get(key);
+      if (track === undefined || !track.sounding) return;
+      let queue = pending.get(key);
+      if (queue === undefined) {
+        queue = [];
+        pending.set(key, queue);
+      }
+      queue.push(hasAt ? { at: heard.at } : { target: heard.target });
+      if (queue.length > MAX_PENDING_NOTES) queue.shift();
+      pendingKeys.add(key);
+    },
+
+    frame(ts, { motion, cps, toPerf } = {}) {
+      if (!isFiniteNumber(ts)) throw new Error(`Moontide: a light frame needs a time that is a number, got ${String(ts)}.`);
+      if (motion !== 'on' && motion !== 'off') throw new Error(`Moontide: a light frame needs motion 'on' or 'off', got ${String(motion)}.`);
+      if (!isFiniteNumber(cps) || cps <= 0) throw new Error(`Moontide: a light frame needs a tempo above 0, got ${String(cps)}.`);
+      if (typeof toPerf !== 'function') throw new Error('Moontide: a light frame needs toPerf, the function that turns an audio time into the page clock.');
+
+      // Notes heard by now light their track in this frame. The whole queue is read: a note that arrives out of order must
+      // not wait behind one that is heard later.
+      for (const key of pendingKeys) {
+        const queue = pending.get(key);
+        let latest = -Infinity;
+        let kept = 0;
+        for (let i = 0; i < queue.length; i++) {
+          const note = queue[i];
+          const heard = note.at !== undefined ? note.at : toPerf(note.target);
+          if (!isFiniteNumber(heard)) throw new Error(`Moontide: toPerf gave ${String(heard)} for an audio time, not a number.`);
+          if (heard <= ts) {
+            if (heard > latest) latest = heard;
+          } else {
+            queue[kept++] = note;
+          }
+        }
+        queue.length = kept;
+        if (kept === 0) pendingKeys.delete(key);
+        if (latest === -Infinity) continue;
+        let state = states.get(key);
+        if (state === undefined) {
+          state = { litAt: ts, lastHeard: latest };
+          states.set(key, state);
+        } else {
+          state.litAt = ts;
+          if (latest > state.lastHeard) state.lastHeard = latest;
+        }
+        active.add(key);
+      }
+
+      // The value of every light that may be lit; a track whose value reached 0 leaves the active set.
+      trackValues.clear();
+      groupValues.clear();
+      const cycleMs = 1000 / cps;
+      for (const key of active) {
+        const state = states.get(key);
+        const track = tracks.get(key);
+        let value = 0;
+        if (state !== undefined && track !== undefined && track.sounding) {
+          if (motion === 'on') {
+            value = Math.round(Math.min(1, Math.max(0, 1 - (ts - state.litAt) / LIGHT_FADE_MS)) * LIGHT_STEPS) / LIGHT_STEPS;
+          } else {
+            value = ts - state.lastHeard <= cycleMs ? 1 : 0;
+          }
+        }
+        if (value <= 0) {
+          active.delete(key);
+          continue;
+        }
+        trackValues.set(key, value);
+        const above = ancestors.get(track.id);
+        if (above === undefined) continue;
+        for (const group of above) {
+          if (value > (groupValues.get(group) ?? 0)) groupValues.set(group, value);
+        }
+      }
+
+      const changes = [];
+      for (const [key, value] of trackValues) {
+        const shown = shownTracks.get(key);
+        const id = tracks.get(key).id;
+        // The strip that owns a shared key can change while its light is lit: the old strip goes dark and the new one shows
+        // the current value in this same frame.
+        if (shown !== undefined && shown.id !== id) {
+          changes.push({ kind: 'track', id: shown.id, value: 0 });
+          shown.id = id;
+          shown.value = -1;
+        }
+        if (shown !== undefined && shown.value === value) continue;
+        if (shown === undefined) shownTracks.set(key, { id, value });
+        else shown.value = value;
+        changes.push({ kind: 'track', id, value });
+      }
+      for (const [key, shown] of shownTracks) {
+        if (trackValues.has(key)) continue;
+        shownTracks.delete(key);
+        changes.push({ kind: 'track', id: shown.id, value: 0 });
+      }
+      for (const [group, value] of groupValues) {
+        if (shownGroups.get(group) === value) continue;
+        shownGroups.set(group, value);
+        changes.push({ kind: 'group', id: group, value });
+      }
+      for (const group of shownGroups.keys()) {
+        if (groupValues.has(group)) continue;
+        shownGroups.delete(group);
+        changes.push({ kind: 'group', id: group, value: 0 });
+      }
+      return changes;
+    },
+
+    forgetShown() {
+      // Keep the entries but mark their values unknown: a light that is lit gets its value handed out again, and one that
+      // has gone dark by the next frame still falls into the leaving loops and gets its dark change.
+      for (const shown of shownTracks.values()) shown.value = -1;
+      for (const group of shownGroups.keys()) shownGroups.set(group, -1);
+    },
+
+    playsMidi(key) {
+      const track = tracks.get(key);
+      return track !== undefined && track.midi === true;
+    },
+
+    reset() {
+      pending.clear();
+      pendingKeys.clear();
+      states.clear();
+      active.clear();
+      shownTracks.clear();
+      shownGroups.clear();
+    },
+  };
+}