moontide-mcp 2.0.2 → 2.1.0

package/page/midi-clock.js

@@ -67,7 +67,7 @@ export const CYCLIST_FIELDS = Object.freeze([
 // at: MIDI follows the clock, with no offset toward the browser's own sounds.
 const STRUDEL_LATENCY_MS = 34;
 // An output-timestamp pair is fresh while its performance time is this recent (measured in the spike).
-const FRESH_PAIR_MAX_AGE_MS = 100;
+export const FRESH_PAIR_MAX_AGE_MS = 100;
 // A pair whose offset differs from the alignment by more than this is an outlier; a run of this many outliers
 // resets the alignment (measured in the spike).
 const OUTLIER_MS = 20;

package/page/midi-out.js

@@ -721,6 +721,16 @@ export function createMidiOut({
     });
   }
 
+  // The timestamp the port got for each note (the hap), so a light can blink when the note is heard. The page clock is
+  // not asked a second time: it keeps state.
+  const noteStamps = new WeakMap();
+
+  /** The timestamp the port got for this note, or null when it went out without one. */
+  function noteStampOf(hap) {
+    if (hap === null || typeof hap !== 'object') return null;
+    return noteStamps.get(hap) ?? null;
+  }
+
   /**
    * Wraps one trigger function of Strudel's `.midi()`. With a timestamp from the page clock for the hap's target
    * time (its 4th argument), the trigger runs with its target moved so that its sends fire NOTE_AHEAD_MS before
@@ -752,6 +762,7 @@ export function createMidiOut({
       }
       // A note whose time has passed goes out at once and keeps its length.
       const ts = Math.max(stamp, now);
+      if (args[0] !== null && typeof args[0] === 'object') noteStamps.set(args[0], ts);
       const shifted = getAudioContext().currentTime + Math.max(0, ts - now - NOTE_AHEAD_MS) / 1000;
       const proxies = webMidi.outputs.map((output) => outputProxy(output, ts, now));
       // The real webmidi keeps `outputs` as a getter on its prototype; a fake may keep an own property: the own
@@ -2608,5 +2619,6 @@ export function createMidiOut({
     resync,
     setActive,
     installNoteStamps,
+    noteStampOf,
   };
 }

package/page/mixer-groups.js

@@ -0,0 +1,114 @@
+// Pure module for the Mixer view: the groups of a song as the Mixer draws them. It joins the groups that
+// page/structure.js read (names of tracks, nested to any depth) to the strips of the Mixer model, and returns the tree
+// of frames: each group with its fold state, its nesting level and the strips below it, then the strips no group names.
+// It has no DOM access at import time, no copy and no state, and it walks the tree with an explicit stack (never by
+// recursion), so a very deep structure cannot overflow the stack. node:test and page/mixer-model.js import it without a
+// build step; page/mixer-view.js draws what the model builds from it.
+
+import { SONG_GRID_DEEP_FROM, groupKey } from './song-grid-model.js';
+
+/**
+ * The layout of the Mixer for a read song, or null when the Mixer stays flat (the song is not read, or names no
+ * group). `reading` is the result of readStructure, `strips` the strips of the Mixer model (each with `identity` and
+ * `index`, the index readStructure gives its track) and `folds` a Set of the keys of folded groups. Returns
+ * `{ items, groups }`:
+ * - `items`: the top level in order, the groups in the song's order and then `{ kind: 'strip', identity }` for every
+ *   strip no group names, in the order of `strips`;
+ * - a group item is `{ kind: 'group', key, path, name, level, deep, open, members, items }`: its key (see groupKey),
+ *   the names from the root, its level (1 at the top), `deep` (from level 5 on), `open` (its own fold state alone: a
+ *   group inside a folded group is open but hidden with its parent's body), `members` (the identity of every strip below
+ *   at any depth, in display order) and its own `items` in the order written (group items and strip items);
+ * - `groups`: every group item in display order, the same objects as in the tree.
+ * A track a group names that has no strip adds nothing, and a group with no strip is still a group.
+ */
+export function mixerLayout({ reading, strips, folds }) {
+  if (reading === null || typeof reading !== 'object' || reading.state !== 'read') return null;
+  if (!Array.isArray(reading.groups) || reading.groups.length === 0) return null;
+
+  // Keys of these maps are names and indexes from the code, so they stay in Map and Set, never in object properties.
+  const indexOfTrack = new Map();
+  for (const track of reading.tracks) indexOfTrack.set(track.name, track.index);
+  const stripOfIndex = new Map();
+  for (const strip of strips) stripOfIndex.set(strip.index, strip.identity);
+
+  const groups = [];
+  const named = new Set();
+  const items = [];
+  const stack = [{ source: reading.groups.map((group) => ({ group })), index: 0, path: [], container: items }];
+  // The group items open on the way down, root first: each strip found below them is one of their members.
+  const open = [];
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame.index >= frame.source.length) {
+      stack.pop();
+      if (stack.length > 0) open.pop();
+      continue;
+    }
+    const entry = frame.source[frame.index];
+    frame.index += 1;
+    if (entry.track !== undefined) {
+      const index = indexOfTrack.get(entry.track);
+      if (index === undefined) continue;
+      named.add(index);
+      const identity = stripOfIndex.get(index);
+      if (identity === undefined) continue;
+      frame.container.push({ kind: 'strip', identity });
+      for (const group of open) group.members.push(identity);
+      continue;
+    }
+    const path = [...frame.path, entry.group.name];
+    const key = groupKey(path);
+    const level = path.length;
+    const item = {
+      kind: 'group',
+      key,
+      path,
+      name: entry.group.name,
+      level,
+      deep: level >= SONG_GRID_DEEP_FROM,
+      open: !folds.has(key),
+      members: [],
+      items: [],
+    };
+    frame.container.push(item);
+    groups.push(item);
+    open.push(item);
+    stack.push({ source: entry.group.items, index: 0, path, container: item.items });
+  }
+  for (const strip of strips) {
+    if (!named.has(strip.index)) items.push({ kind: 'strip', identity: strip.identity });
+  }
+  return { items, groups };
+}
+
+/**
+ * What a click on a group's mute and solo buttons does, from the strips below the group. `group` is a group item of
+ * mixerLayout (its `members` are the identities of the strips below it at any depth, in display order) and
+ * `stripsByIdentity` a Map from identity to the strip of the Mixer model. Returns `{ mute, solo, skipped }`.
+ * For each kind, `mute` and `solo` hold:
+ * - `identities`: the strips that kind can reach, in display order: the strip is editable and its own button for that
+ *   kind is not off. Only these are counted and written;
+ * - `n` and `k`: how many are reachable and how many of them are pressed (muted, or soloed);
+ * - `pressed`: false for none (or nothing reachable), true for all, 'mixed' for some;
+ * - `on`: what a click writes, true unless every reachable track is already pressed.
+ * `skipped` counts the members that mute or solo cannot reach, each once. The module holds no copy and no state.
+ */
+export function groupActions(group, stripsByIdentity) {
+  const strips = group.members.map((identity) => stripsByIdentity.get(identity)).filter((strip) => strip !== undefined);
+  const action = (kind) => {
+    const reachable = strips.filter((strip) => strip.editable === true && strip[kind].disabled === false);
+    const n = reachable.length;
+    const k = reachable.filter((strip) => strip[kind].pressed === true).length;
+    return {
+      identities: reachable.map((strip) => strip.identity),
+      n,
+      k,
+      pressed: n === 0 || k === 0 ? false : k === n ? true : 'mixed',
+      on: !(k === n && n > 0),
+    };
+  };
+  const mute = action('mute');
+  const solo = action('solo');
+  const reachedByBoth = new Set(mute.identities.filter((identity) => solo.identities.includes(identity)));
+  return { mute, solo, skipped: strips.filter((strip) => !reachedByBoth.has(strip.identity)).length };
+}

package/page/mixer-model.js

@@ -6,7 +6,9 @@
 import { readProgram } from './mixer-rewrite.js';
 import { controlsByCc, controlsText, defaultOf, faderControl, midiTag, readMidiTracks, sweepKey } from './midi-controls.js';
 import { fill } from './midi-plan.js';
-import { parseLabel } from './tracks.js';
+import { groupActions, mixerLayout } from './mixer-groups.js';
+import { SONG_COPY, countText, displayName, quoted } from './structure.js';
+import { labelKey, parseLabel } from './tracks.js';
 import { BUSES, BUS_IDS, DEFAULT_POSTGAIN, EFFECTS, EFFECT_IDS, MOVE_SHAPES, PARAM_STEPS, SENDS, busParamById, effectById, fixedValueOf, formatDisplayNumber, formatNumber, gainToPosition, normalizeStoredCall, valueToPosition } from './mixer-registry.js';
 
 /** Page-visible copy for the Mixer view. `notSaved` is shown
@@ -32,7 +34,9 @@ export const MIXER_COPY = {
   mute: 'Mute',
   solo: 'Solo',
   soloByName: 'Starts with a capital S — Strudel plays this track alone.',
-  soloNeedsLabel: 'Solo needs a label — ask Claude to name this track.',
+  soloNeedsLabel: 'Solo and the light need a label — ask Claude to name this track.',
+  lightTrackTitle: 'Blinks when {name} plays a note',
+  lightGroupTitle: 'Blinks when any track of {group} plays a note',
   addEffect: 'Add effect',
   off: 'off',
   moving: 'moving',
@@ -86,6 +90,26 @@ export const MIXER_COPY = {
   },
   // A strip built from shared code (a declared constant or function) shows this muted line; the mixer reads only the track's own chain.
   sharedRoot: 'Built from shared code',
+  // The accessible name of a group's frame; the group name is cut to 40 code points like every name in a sentence.
+  groupLabel: 'Group {group}',
+  // Mute and solo on a group: the accessible names, the hover texts, the count line and the notes. {tracks} is '1 track' or
+  // '{count} tracks'; {k} of {n} counts the reachable tracks that are muted (or soloed), {j} the soloed ones in the both-partial line.
+  groupMuteName: 'Mute {group}',
+  groupMuteNamePartial: 'Mute {group}, {k} of {n} tracks muted',
+  groupSoloName: 'Solo {group}',
+  groupSoloNamePartial: 'Solo {group}, {k} of {n} tracks soloed',
+  groupMuteTitle: 'Mute {tracks}',
+  groupUnmuteTitle: 'Unmute {tracks}',
+  groupMutePartialTitle: '{k} of {n} tracks muted. A click mutes all {n}.',
+  groupSoloTitle: 'Solo {tracks}',
+  groupEndSoloTitle: 'End the solo of {tracks}',
+  groupSoloPartialTitle: '{k} of {n} tracks soloed. A click solos all {n}.',
+  groupCountMuted: '{k} of {n} muted',
+  groupCountSolo: '{k} of {n} solo',
+  groupCountBoth: '{k} of {n} muted, {j} of {n} solo',
+  groupSkipOne: "Skips 1 track the mixer can't change.",
+  groupSkipMany: "Skips {n} tracks the mixer can't change.",
+  groupEmpty: 'No track of this group is in the code.',
   sharedRootTitle: 'The mixer shows and changes only what this track writes after the shared code.',
   // The fader of a MIDI track sets the instrument's own volume (CC7), written in the .midi() options.
   midiFaderLine: 'instrument volume',
@@ -171,7 +195,7 @@ export function clipMixerLabel(text) {
  * 'add-effect' | 'remove' | 'remove-effect' | 'bypass' | 'restore', name, effect }` (`effect` an effect id, written by
  * its plain name lower-cased), `{ kind: 'param', name, effect, param, value }` (`param` a parameter
  * id of the effect, written by its plain name lower-cased) or `{ kind: 'param-default', name, effect,
- * param }` or `{ kind: 'move', name, effect, from, to, over }` (a filter move) or `{ kind: 'send', name, bus, value }`
+ * param }` or `{ kind: 'group-mute' | 'group-solo', group, on }` (a group's mute or solo, named by the group alone) or `{ kind: 'move', name, effect, from, to, over }` (a filter move) or `{ kind: 'send', name, bus, value }`
  * (`bus` 'reverb' or 'delay') or `{ kind: 'bus-param', bus, param, value }` (a bus is one thing: no track name). An
  * unknown kind throws (a loud error), so a new kind cannot forget its label. A MIDI control is
  * `{ kind: 'midi-control', name, control, value }` or `{ kind: 'midi-control-default', name, control }` (`control` the
@@ -187,6 +211,12 @@ export function mixerHistoryLabel(action) {
   if (action && action.kind === 'solo') {
     return `mixer: ${action.name} solo ${action.on ? 'on' : 'off'}`;
   }
+  if (action && action.kind === 'group-mute') {
+    return `mixer: group ${displayName(action.group)} ${action.on ? 'muted' : 'unmuted'}`;
+  }
+  if (action && action.kind === 'group-solo') {
+    return `mixer: group ${displayName(action.group)} solo ${action.on ? 'on' : 'off'}`;
+  }
   if (action && action.kind === 'add-effect') {
     return `mixer: ${action.name} added ${effectById(action.effect).name.toLowerCase()}`;
   }
@@ -664,6 +694,11 @@ function sendRowsFor(strip, memory) {
  * all three are false or null for any other strip). A browser strip whose track plays MIDI without a MIDI strip (its
  * `.midi()` is in shared code or off its own chain) has `playsMidi` (true, else false) and its own reason line: no add list,
  * no sends, no place on a bus and no editing of its effects, because MIDI output never plays them; its gain, mute and solo still work.
+ * Every strip also has `lightKey`, the key the notes of its track are reported under (see lightKeysOf), or null for a track without
+ * a label, which has no light. Every strip also has `index`, its track's index in the code (the index the song reading gives the same track). `song` (the
+ * result of readStructure for this code; default `{ state: 'none' }`) and `folds` (a Set of the keys of folded groups; default
+ * empty) give a ready model its `layout`: null when the song is not read or names no group, else mixerLayout's tree with the
+ * words of each group (see groupLayout).
  */
 export function buildMixerModel(input) {
   try {
@@ -744,12 +779,12 @@ function midiChipFor(state, trackName) {
 }
 
 /**
- * The group of every MIDI track whose port and channel the page can read, `Map<identity, member[]>`: the tracks of
- * the same read that play the same port on the same channel (the port stands in for the instrument, so a file's
+ * The channel mates of every MIDI track whose port and channel the page can read, `Map<identity, mate[]>`: the tracks
+ * of the same read that play the same port on the same channel (the port stands in for the instrument, so a file's
  * instrument and its port are the same key), in code order, the track itself and muted ones included. A track whose
- * channel or port cannot be read is in no group (its channel is unknown), so it is alone.
+ * channel or port cannot be read has no channel mates (its channel is unknown), so it is alone.
  */
-function midiGroups(midiTracks) {
+function channelMates(midiTracks) {
   const byKey = new Map();
   for (const track of midiTracks.values()) {
     const { port, channel } = track.spine;
@@ -758,16 +793,16 @@ function midiGroups(midiTracks) {
     if (!byKey.has(key)) byKey.set(key, []);
     byKey.get(key).push(track);
   }
-  const groups = new Map();
-  for (const members of byKey.values()) for (const member of members) groups.set(member.identity, members);
-  return groups;
+  const mates = new Map();
+  for (const members of byKey.values()) for (const member of members) mates.set(member.identity, members);
+  return mates;
 }
 
 /**
- * The controls written on any member of a group, `Map<id, number>`: the first member in code order that writes a
+ * The controls written on any of the tracks on one port and channel, `Map<id, number>`: the first one in code order that writes a
  * control gives its value (the evaluation refuses two different values of one control on one channel, so they agree).
  */
-function groupControls(members) {
+function channelControls(members) {
   const written = new Map();
   for (const member of members) {
     for (const [id, value] of member.spine.controls) if (!written.has(id)) written.set(id, value);
@@ -775,9 +810,15 @@ function groupControls(members) {
   return written;
 }
 
-/** The shared-code facts of a strip: `sharedRoot` from the read, and the muted line with its hover (null when the track is not built from shared code). */
-function sharedRootFacts(read) {
-  const sharedRoot = read.ok && read.sharedRoot === true;
+/**
+ * The shared-code facts of a strip: `sharedRoot` from the read, and the muted line with its hover (null when the track is not
+ * built from shared code). `canonicalPlay` is true when the piece's play() is the song helper the page knows (the song
+ * reading says its helper is the canonical text).
+ */
+function sharedRootFacts(read, canonicalPlay) {
+  // A track written with play(...) starts from the song's own helper, so it shows no shared-code line. When the helper was
+  // changed, or play is some other function, that line is the warning the user needs and stays.
+  const sharedRoot = read.ok && read.sharedRoot === true && !(read.playRoot === true && canonicalPlay);
   return {
     sharedRoot,
     sharedRootText: sharedRoot ? MIXER_COPY.sharedRoot : null,
@@ -792,20 +833,20 @@ function sharedRootFacts(read) {
  * chips (every declared control except the volume, in model order; none while the controls are off) and
  * `midi.controls` the states they and the inspector rows are drawn from.
  */
-function midiStrip(track, read, midiTrack, colorOf, sweepsRead, members) {
+function midiStrip(track, read, midiTrack, colorOf, sweepsRead, members, canonicalPlay) {
   const instrument = midiTrack.instrument;
   const control = instrument === null ? null : faderControl(instrument);
-  // A member whose controls cannot be written (a rewrite writes every member or nothing) turns the whole group off with its reason.
-  const groupReason = members.map((member) => member.reason).find((candidate) => candidate !== null) ?? null;
-  const ownReason = midiTrack.reason ?? groupReason;
+  // A channel mate whose controls cannot be written (a rewrite writes every track on the channel or none) turns all of them off with its reason.
+  const channelReason = members.map((member) => member.reason).find((candidate) => candidate !== null) ?? null;
+  const ownReason = midiTrack.reason ?? channelReason;
   // A valid file whose model has no volume control: the strip says so, and the fader is off.
   const reason = ownReason === null && instrument !== null && control === null ? 'noVolume' : ownReason;
   // The other controls work for every reason but the ones that hide the instrument; a model with no volume still has them.
   const controlsOk = instrument !== null && (reason === null || reason === 'noVolume');
   const name = track.displayName ?? track.name;
   const sweeps = midiSweepsFor(midiTrack, sweepsRead);
-  // A channel has one value per control: what the group writes, not only what this track writes.
-  const written = groupControls(members);
+  // A channel has one value per control: what all its tracks write, not only what this track writes.
+  const written = channelControls(members);
   const others = members.filter((member) => member !== midiTrack).map((member) => member.name);
   const sharedText = others.length === 0 ? '' : fill(MIXER_COPY.midiShared, { names: others.join(', ') });
   const states = controlsOk ? midiControlStates(instrument, written, sweeps) : [];
@@ -832,10 +873,11 @@ function midiStrip(track, read, midiTrack, colorOf, sweepsRead, members) {
     sounding: !track.muted,
     ...muteSoloModel(track),
     color: colorOf(track.identity),
+    index: track.index,
     editable: read.ok,
     reason: read.ok ? null : read.reason,
     reasonText: read.ok ? null : reasonTextFor(read.reason),
-    ...sharedRootFacts(read),
+    ...sharedRootFacts(read, canonicalPlay),
     midi,
     busHidden: false,
     playsMidi: false,
@@ -849,7 +891,26 @@ function midiStrip(track, read, midiTrack, colorOf, sweepsRead, members) {
   };
 }
 
-function buildModel({ code, parse, colorOf, bypassRecords = [], busMemory = new Map(), keepBus = null, rig = { setup: 'absent' } }) {
+/**
+ * The key each track's light listens for, `Map<identity, key | null>`: for a plain label, the key the note tag reports (the
+ * label without its mute underscore and solo marker, the same for `hats` and a muted copy `hats_`, where the identity of the
+ * second one gets a number to stay unique), `$` and the number of the statement for a `$` label (the n-th one in code order that a
+ * leading or trailing underscore does not silence, counted from 0, as the tag counts them), null for a track without a label,
+ * which Strudel never reports. A `$` statement an underscore silences never plays, so it keeps its identity, a key no note names.
+ */
+function lightKeysOf(tracks) {
+  const keys = new Map();
+  let dollars = 0;
+  for (const track of tracks) {
+    if (track.kind !== 'label') keys.set(track.identity, null);
+    else if (!track.label.includes('$')) keys.set(track.identity, labelKey(track.label));
+    else if (track.label.startsWith('_') || track.label.endsWith('_')) keys.set(track.identity, track.identity);
+    else keys.set(track.identity, `$${dollars++}`);
+  }
+  return keys;
+}
+
+function buildModel({ code, parse, colorOf, bypassRecords = [], busMemory = new Map(), keepBus = null, rig = { setup: 'absent' }, song = { state: 'none' }, folds = new Set() }) {
   if (typeof code !== 'string' || code.trim() === '') return { status: 'empty', strips: [], buses: [], busMemory };
   let program;
   try {
@@ -859,18 +920,20 @@ function buildModel({ code, parse, colorOf, bypassRecords = [], busMemory = new
   }
   if (program.tracks.length === 0) return { status: 'empty', strips: [], buses: [], busMemory };
   const staleRecords = [];
+  // The song reading knows whether play() is the canonical helper (an unreadable song still says so); with no structure it is not.
+  const canonicalPlay = (song.state === 'read' || song.state === 'unreadable') && song.helper === 'canonical';
   // One read of the MIDI tracks per render; code that does not parse reads as no MIDI strips (it is unreadable above anyway).
   const midiRead = readMidiTracks(code, { parse, rig });
   const midiTracks = midiRead.ok ? midiRead.tracks : new Map();
   const sweepsRead = midiRead.ok ? { sweeps: midiRead.sweeps, sweepsUnknown: midiRead.sweepsUnknown } : { sweeps: new Map(), sweepsUnknown: new Set() };
-  // The groups come first: a folded track still belongs to its port and channel, so a kept strip names it.
-  const groups = midiGroups(midiTracks);
+  // The channel mates come first: a folded track still belongs to its port and channel, so a kept strip names it.
+  const mates = channelMates(midiTracks);
   const buildStrip = (track, read, midiTrack) => {
     // A track that sets its own orbit or bus values off its own chain hides its real bus: it gets no bus facts, so no bus strip counts it and its sends are off.
     const busHidden = read.ok && read.busHidden === true;
     // A browser track that plays MIDI has no MIDI strip: MIDI output never plays its effects or its sends, so none of them is offered and it feeds no bus.
     const playsMidi = read.ok && read.playsMidi === true;
-    if (midiTrack !== undefined) return midiStrip(track, read, midiTrack, colorOf, sweepsRead, groups.get(track.identity) ?? [midiTrack]);
+    if (midiTrack !== undefined) return midiStrip(track, read, midiTrack, colorOf, sweepsRead, mates.get(track.identity) ?? [midiTrack], canonicalPlay);
     const own = read.ok ? bypassRecords.filter((record) => record.identity === track.identity) : [];
     // The code wins: a record whose effect is back in the code is stale and the caller drops it.
     const kept = [];
@@ -884,10 +947,11 @@ function buildModel({ code, parse, colorOf, bypassRecords = [], busMemory = new
       sounding: !track.muted,
       ...muteSoloModel(track),
       color: colorOf(track.identity),
+      index: track.index,
       editable: read.ok,
       reason: read.ok ? null : read.reason,
       reasonText: read.ok ? (playsMidi ? MIXER_COPY.playsMidi : null) : reasonTextFor(read.reason),
-      ...sharedRootFacts(read),
+      ...sharedRootFacts(read, canonicalPlay),
       midi: null,
       playsMidi,
       fader: faderModel(read),
@@ -903,6 +967,7 @@ function buildModel({ code, parse, colorOf, bypassRecords = [], busMemory = new
       busHidden,
     };
   };
+  const lightKeys = lightKeysOf(program.tracks);
   const noNotes = [];
   const strips = [];
   for (const track of program.tracks) {
@@ -912,7 +977,9 @@ function buildModel({ code, parse, colorOf, bypassRecords = [], busMemory = new
       noNotes.push({ identity: track.identity, name: track.displayName ?? track.name, tagText: midiTag(midiTrack)?.text ?? null, silent: track.muted });
       continue;
     }
-    strips.push(buildStrip(track, read, midiTrack));
+    const strip = buildStrip(track, read, midiTrack);
+    strip.lightKey = lightKeys.get(track.identity) ?? null;
+    strips.push(strip);
   }
   const { buses, busMemory: nextMemory } = busEntries(strips, busMemory, keepBus);
   for (const strip of strips) strip.sends = sendRowsFor(strip, nextMemory);
@@ -923,7 +990,83 @@ function buildModel({ code, parse, colorOf, bypassRecords = [], busMemory = new
     })
     .join(', ');
   const noNotesText = noNotes.length === 0 ? null : fill(MIXER_COPY.noNotes, { list });
-  return { status: 'ready', strips, staleRecords, buses, busMemory: nextMemory, noNotes, noNotesText };
+  const layout = groupLayout(mixerLayout({ reading: song, strips, folds }), strips);
+  return { status: 'ready', strips, staleRecords, buses, busMemory: nextMemory, noNotes, noNotesText, layout };
+}
+
+/**
+ * The layout of mixerLayout (null stays null) with the words each group frame shows: `text` and `title` (the name cut
+ * to 40 code points, and the whole name), `label` (the frame's accessible name), `foldTitle` (the grid's words, the
+ * name in single quotes), `count` and `countText` (the strips below the group at any depth), then what the head's mute
+ * and solo buttons need (see groupControls): `mute` and `solo`, `countText` and `countTitle` (the plain count, or the
+ * partial forms) and `noteText`.
+ */
+function groupLayout(layout, strips) {
+  if (layout === null) return null;
+  const stripsByIdentity = new Map(strips.map((strip) => [strip.identity, strip]));
+  for (const group of layout.groups) {
+    group.text = displayName(group.name);
+    group.title = group.name;
+    group.label = fill(MIXER_COPY.groupLabel, { group: displayName(group.name) });
+    group.foldTitle = fill(group.open ? SONG_COPY.foldTitle : SONG_COPY.openTitle, { group: quoted(group.name) });
+    group.count = group.members.length;
+    group.countText = countText(group.count, SONG_COPY.trackOne, SONG_COPY.trackMany);
+    Object.assign(group, groupControls(group, groupActions(group, stripsByIdentity)));
+  }
+  return layout;
+}
+
+/** `n` tracks as a sentence part: '1 track' or '3 tracks'. */
+function tracksText(n) {
+  return countText(n, SONG_COPY.trackOne, SONG_COPY.trackMany);
+}
+
+/**
+ * The mute and solo of one group head, from groupActions: for each, `{ pressed, on, identities, disabled, name, title }`
+ * (`pressed` true, false or 'mixed'; `on` what a click writes; `identities` the tracks it writes; `disabled` when no
+ * track can be reached; `name` the accessible name and `title` the hover text), the group's `countText` and `countTitle`
+ * (the plain count, or what is partly muted or soloed) and `noteText` (the group has no strip, else how many tracks
+ * the buttons skip, else null).
+ */
+function groupControls(group, actions) {
+  const who = displayName(group.name);
+  const button = (kind, action) => {
+    const mute = kind === 'mute';
+    const mixed = action.pressed === 'mixed';
+    const copy = mute
+      ? { name: MIXER_COPY.groupMuteName, partial: MIXER_COPY.groupMuteNamePartial, off: MIXER_COPY.groupMuteTitle, all: MIXER_COPY.groupUnmuteTitle, some: MIXER_COPY.groupMutePartialTitle, none: MIXER_COPY.mute }
+      : { name: MIXER_COPY.groupSoloName, partial: MIXER_COPY.groupSoloNamePartial, off: MIXER_COPY.groupSoloTitle, all: MIXER_COPY.groupEndSoloTitle, some: MIXER_COPY.groupSoloPartialTitle, none: MIXER_COPY.solo };
+    const values = { group: who, k: action.k, n: action.n, tracks: tracksText(action.n) };
+    let title = copy.none;
+    if (mixed) title = fill(copy.some, values);
+    else if (action.n > 0) title = fill(action.pressed === true ? copy.all : copy.off, values);
+    return {
+      pressed: action.pressed,
+      on: action.on,
+      identities: action.identities,
+      disabled: action.n === 0,
+      name: fill(mixed ? copy.partial : copy.name, values),
+      title,
+    };
+  };
+  const mute = button('mute', actions.mute);
+  const solo = button('solo', actions.solo);
+  const partMuted = mute.pressed === 'mixed';
+  const partSolo = solo.pressed === 'mixed';
+  let countLine = group.countText;
+  if (partMuted && partSolo && actions.mute.n === actions.solo.n) {
+    countLine = fill(MIXER_COPY.groupCountBoth, { k: actions.mute.k, n: actions.mute.n, j: actions.solo.k });
+  } else if (partMuted || partSolo) {
+    // The two buttons can reach different numbers of tracks (an unlabeled track mutes but cannot solo), so each part names its own.
+    const parts = [];
+    if (partMuted) parts.push(fill(MIXER_COPY.groupCountMuted, { k: actions.mute.k, n: actions.mute.n }));
+    if (partSolo) parts.push(fill(MIXER_COPY.groupCountSolo, { k: actions.solo.k, n: actions.solo.n }));
+    countLine = parts.join(', ');
+  }
+  let noteText = null;
+  if (group.members.length === 0) noteText = MIXER_COPY.groupEmpty;
+  else if (actions.skipped > 0) noteText = fill(actions.skipped === 1 ? MIXER_COPY.groupSkipOne : MIXER_COPY.groupSkipMany, { n: actions.skipped });
+  return { mute, solo, countText: countLine, countTitle: countLine, noteText };
 }
 
 // --- The inspector: one effect's parameters ---

package/page/mixer-rewrite.js

@@ -721,6 +721,10 @@ function inspectTrack(code, entry, scope) {
   const sharedRoot =
     (root.type === 'Identifier' && declared.has(root.name)) ||
     (root.type === 'CallExpression' && root.callee.type === 'Identifier' && declared.has(root.callee.name));
+  // A track that starts with play(...) may be built by the song's own helper, whose lines are not shared code the user needs
+  // to hear about. The model drops the "built from shared code" line only when the song reading says that helper is the
+  // canonical one; this read just says the track starts with a call named play.
+  const playRoot = root.type === 'CallExpression' && root.callee.type === 'Identifier' && root.callee.name === 'play';
   for (const call of spine.calls) {
     if (!MIXER_CALLS.has(call.name) && effectOfMethod(call.name) === null) continue;
     const args = call.node.arguments;
@@ -731,6 +735,7 @@ function inspectTrack(code, entry, scope) {
   return {
     spine,
     sharedRoot,
+    playRoot,
     ...readReach(spine, entry.expression, scope),
     gain: readControl(spine.calls, 'gain'),
     postgain: readControl(spine.calls, 'postgain'),
@@ -774,7 +779,7 @@ function publicBus({ orbit, sends, busParams }) {
 /**
  * Parses `code` once and reads every track: `{ tracks, reads }`, `tracks` from extractTracks and
  * `reads` a Map from track identity to `{ ok: true, gain: { kind, value }, postgain: { kind,
- * value }, effects, bus, label, sharedRoot, playsMidi, innerPostgain }` (`sharedRoot` is true when the track's root is a declared name or a call of one; `playsMidi` is true when a `.midi(` call sits anywhere the track's code reaches, `innerPostgain` is true when a `.postgain(` call sits in that code off the spine; `busHidden` is true when the track writes an orbit, a send or a bus value anywhere but on its own chain (inside another call, in shared code it names, through `.set({ ... })` or a bare call), so its bus facts are not trusted; see readReach; kind 'none', 'fixed' or 'pattern'; `bus` is `{ orbit, sends, busParams }`
+ * value }, effects, bus, label, sharedRoot, playRoot, playsMidi, innerPostgain }` (`sharedRoot` is true when the track's root is a declared name or a call of one; `playRoot` is true when the track's own statement starts with a `play(...)` call; `playsMidi` is true when a `.midi(` call sits anywhere the track's code reaches, `innerPostgain` is true when a `.postgain(` call sits in that code off the spine; `busHidden` is true when the track writes an orbit, a send or a bus value anywhere but on its own chain (inside another call, in shared code it names, through `.set({ ... })` or a bare call), so its bus facts are not trusted; see readReach; kind 'none', 'fixed' or 'pattern'; `bus` is `{ orbit, sends, busParams }`
  * of readBusFacts without call positions (kind 'unwritten', 'fixed' or 'pattern'); `effects` is a Map from effect id
  * to `{ calls, params, written, bypassable, bypassWhy }`, see readEffects; `label` is null for a track without one,
  * else `{ raw, ...parseLabel(raw) }`) or `{ ok: false, reason }`. One bad track never throws; an
@@ -798,6 +803,7 @@ export function readProgram(code, { parse }) {
         bus: publicBus(read.bus),
         label: raw === null ? null : { raw, ...parseLabel(raw) },
         sharedRoot: read.sharedRoot,
+        playRoot: read.playRoot,
         playsMidi: read.playsMidi,
         innerPostgain: read.innerPostgain,
         busHidden: read.busHidden,
@@ -1561,3 +1567,26 @@ export function writeTrack(code, identity, change, { parse }) {
   }
   return { code: applyEdits(code, edits), edits };
 }
+
+/**
+ * Writes one mute or solo change on many tracks at once and returns `{ code, edits }`, like writeTrack. `change` is
+ * `{ type: 'mute' | 'solo', on }` and `identities` the tracks to write, each read and written against the SAME base
+ * text. All their edits are joined into one list and applied once, by position, so the result is the same whatever
+ * order the tracks are listed in, no track is written twice (a repeated identity counts once) and two edits that
+ * overlap throw. The first track that cannot be written throws its MixerRewriteError and nothing is returned, so a
+ * refused track never leaves the others half written. A track already in the asked state adds no edit.
+ */
+export function writeTracks(code, identities, change, { parse }) {
+  if (!Array.isArray(identities) || identities.length === 0 || identities.some((identity) => typeof identity !== 'string')) {
+    throw new MixerRewriteError('unsupported-change', 'a group change needs at least one track.');
+  }
+  const type = change ? change.type : undefined;
+  if (type !== 'mute' && type !== 'solo') {
+    throw new MixerRewriteError('unsupported-change', `a group can only be muted or soloed, not '${String(type)}'.`);
+  }
+  const edits = [];
+  for (const identity of new Set(identities)) {
+    edits.push(...writeTrack(code, identity, { identity, type, on: change.on }, { parse }).edits);
+  }
+  return { code: applyEdits(code, edits), edits };
+}