moontide-mcp 2.0.2 → 2.2.0

package/page/ui-state.js

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

package/page/views.js

@@ -30,7 +30,11 @@ export const JAM_INSTRUMENTS = ['piano', 'guitar'];
 /** The two values of the Jam "Chord tones" overlay: marks the notes of the chord sounding now, or not. */
 export const JAM_CHORD_TONES = ['on', 'off'];
 
-/** Browser-storage keys for the remembered layout, view, motion switch, History display, the two Jam preferences, the change timing of hand evaluations and the size of the view in layout a and in layout b. */
+/** When a section launched from the Song grid starts: at the end of the section that plays, on the next phrase or on the next bar. */
+export const SONG_LAUNCHES = ['section', 'phrase', 'bar'];
+export const DEFAULT_SONG_LAUNCH = 'section';
+
+/** Browser-storage keys for the remembered layout, view, motion switch, History display, the two Jam preferences, the change timing of hand evaluations, the Song grid's launch choice and the size of the view in layout a and in layout b. */
 export const STORAGE_KEYS = {
   layout: 'moontide.layout',
   view: 'moontide.view',
@@ -39,10 +43,21 @@ export const STORAGE_KEYS = {
   jamInstrument: 'moontide.jamInstrument',
   jamChordTones: 'moontide.jamChordTones',
   changeTiming: 'moontide.changeTiming',
+  songLaunch: 'moontide.songLaunch',
   splitA: 'moontide.split.a',
   splitB: 'moontide.split.b',
 };
 
+const SONG_LAUNCH_LIST = `${SONG_LAUNCHES.slice(0, -1).join(', ')} or ${SONG_LAUNCHES[SONG_LAUNCHES.length - 1]}`;
+
+/**
+ * The console line for a stored song launch choice that is not in the list. It is built from the storage key and
+ * the allowed values only, never from the stored text, so nothing a stranger wrote into storage is echoed.
+ */
+export const VIEW_PREFS_COPY = Object.freeze({
+  badSongLaunch: `Moontide: the stored song launch choice under '${STORAGE_KEYS.songLaunch}' is not ${SONG_LAUNCH_LIST}; sections start at the end of the section that plays.`,
+});
+
 /** Plain-word motion switch labels. */
 export const MOTION_LABELS = { on: 'Motion: on', off: 'Motion: off' };
 
@@ -92,17 +107,18 @@ export function applyKey(state, { key, focusInEditor, focusInTextEntry, ctrlKey,
 }
 
 /**
- * Reads the nine stored preferences from `storage` (a Storage-like object, or null). Each
+ * Reads the ten stored preferences from `storage` (a Storage-like object, or null). Each
  * value is validated against its closed set — layout in LAYOUTS; view 'none' or in
  * BUILT_VIEWS; motion 'on' or 'off'; historyMode in HISTORY_MODES; jamInstrument in
- * JAM_INSTRUMENTS; jamChordTones in JAM_CHORD_TONES; changeTiming in CHANGE_TIMINGS; splitA and splitB a plain number from 15 to 85 (page/split-model.js) — and
+ * JAM_INSTRUMENTS; jamChordTones in JAM_CHORD_TONES; changeTiming in CHANGE_TIMINGS; songLaunch in SONG_LAUNCHES; splitA and splitB a plain number from 15 to 85 (page/split-model.js) — and
  * becomes undefined when missing or invalid, so a stray/legacy value is never interpolated into selectors, HTML or code.
  * `rejected` lists the storage keys of the sizes that were stored but refused (a missing key is not
- * listed), so the page can say so once, loudly. Returns `available: false`, with every value undefined, when storage is
+ * listed), so the page can say so once, loudly. `songLaunchRejected` is true when a launch choice was stored but is
+ * not in SONG_LAUNCHES (a missing key is not), so the page can say that once too; it is false when storage is unavailable. Returns `available: false`, with every value undefined, when storage is
  * null or any read throws (private window, blocked storage).
  */
 export function readViewPrefs(storage) {
-  const UNAVAILABLE_PREFS = { layout: undefined, view: undefined, motion: undefined, historyMode: undefined, jamInstrument: undefined, jamChordTones: undefined, changeTiming: undefined, splitA: undefined, splitB: undefined, rejected: [], available: false };
+  const UNAVAILABLE_PREFS = { layout: undefined, view: undefined, motion: undefined, historyMode: undefined, jamInstrument: undefined, jamChordTones: undefined, changeTiming: undefined, songLaunch: undefined, splitA: undefined, splitB: undefined, rejected: [], songLaunchRejected: false, available: false };
   if (!storage) {
     return { ...UNAVAILABLE_PREFS };
   }
@@ -114,6 +130,7 @@ export function readViewPrefs(storage) {
     const rawJamInstrument = storage.getItem(STORAGE_KEYS.jamInstrument);
     const rawJamChordTones = storage.getItem(STORAGE_KEYS.jamChordTones);
     const rawChangeTiming = storage.getItem(STORAGE_KEYS.changeTiming);
+    const rawSongLaunch = storage.getItem(STORAGE_KEYS.songLaunch);
     const rawSplitA = storage.getItem(STORAGE_KEYS.splitA);
     const rawSplitB = storage.getItem(STORAGE_KEYS.splitB);
     const splitA = parseStoredSplit(rawSplitA);
@@ -121,6 +138,7 @@ export function readViewPrefs(storage) {
     const rejected = [];
     if (rawSplitA !== null && rawSplitA !== undefined && splitA === undefined) rejected.push(STORAGE_KEYS.splitA);
     if (rawSplitB !== null && rawSplitB !== undefined && splitB === undefined) rejected.push(STORAGE_KEYS.splitB);
+    const songLaunchRejected = rawSongLaunch !== null && rawSongLaunch !== undefined && !SONG_LAUNCHES.includes(rawSongLaunch);
     return {
       layout: LAYOUTS.includes(rawLayout) ? rawLayout : undefined,
       view: rawView === 'none' || BUILT_VIEWS.includes(rawView) ? rawView : undefined,
@@ -129,9 +147,11 @@ export function readViewPrefs(storage) {
       jamInstrument: JAM_INSTRUMENTS.includes(rawJamInstrument) ? rawJamInstrument : undefined,
       jamChordTones: JAM_CHORD_TONES.includes(rawJamChordTones) ? rawJamChordTones : undefined,
       changeTiming: CHANGE_TIMINGS.includes(rawChangeTiming) ? rawChangeTiming : undefined,
+      songLaunch: SONG_LAUNCHES.includes(rawSongLaunch) ? rawSongLaunch : undefined,
       splitA,
       splitB,
       rejected,
+      songLaunchRejected,
       available: true,
     };
   } catch {
@@ -156,7 +176,7 @@ export function writeViewPref(storage, key, value) {
 /**
  * The page's state at first render, before any keypress: the stored layout/view/motion/historyMode and
  * Jam preferences, else the defaults (layout 'a', view 'none', motion following the OS reduce-motion
- * setting, history 'list', Jam instrument 'piano', Jam chord tones 'off', change timing 'now').
+ * setting, history 'list', Jam instrument 'piano', Jam chord tones 'off', change timing 'now', Song launch 'section').
  * motionChosen is true only when a motion value was actually stored — while false, the motion
  * value keeps following the OS live (see motionAfterOsChange).
  */
@@ -170,6 +190,7 @@ export function initialViewState({ prefs, prefersReducedMotion }) {
     jamInstrument: prefs.jamInstrument ?? 'piano',
     jamChordTones: prefs.jamChordTones ?? 'off',
     changeTiming: prefs.changeTiming ?? 'now',
+    songLaunch: prefs.songLaunch ?? DEFAULT_SONG_LAUNCH,
   };
 }
 
@@ -205,19 +226,28 @@ export function setChangeTiming(state, value) {
   return { ...state, changeTiming: value };
 }
 
+/** Sets when a section launched from the Song grid starts: 'section', 'phrase' or 'bar'. Throws on a value outside SONG_LAUNCHES (a loud error). */
+export function setSongLaunch(state, value) {
+  if (!SONG_LAUNCHES.includes(value)) {
+    throw new Error(`Moontide: unknown song launch '${String(value)}' (expected one of ${SONG_LAUNCHES.join(', ')})`);
+  }
+  return { ...state, songLaunch: value };
+}
+
 /**
  * The view buttons of the top bar as an ordered list, listing only the given built views in key order (1..6)
  * whatever order `builtViews` lists them in. Each part is { key, digit, name, label, title }: `key` is the digit the
  * button sends to applyKey, `name` the view title, `label` the accessible name `{digit} {Name}` (it contains the
  * visible text at every fit step) and `title` the tooltip `{Name} (key {digit})`. A view without a fixed key
- * (VIEW_KEYS) is ignored.
+ * (VIEW_KEYS) is ignored. `titles` replaces VIEW_TITLES, so a view can be called by another name (the Parts view is called
+ * Song while the code declares a song); the key and the view itself never change.
  */
-export function viewButtonParts(builtViews = BUILT_VIEWS) {
+export function viewButtonParts(builtViews = BUILT_VIEWS, titles = VIEW_TITLES) {
   return Object.entries(VIEW_KEYS)
     .filter(([, view]) => builtViews.includes(view))
     .sort(([a], [b]) => Number(a) - Number(b))
     .map(([digit, view]) => {
-      const name = VIEW_TITLES[view];
+      const name = titles[view];
       return { key: digit, digit, name, label: `${digit} ${name}`, title: `${name} (key ${digit})` };
     });
 }

package/reference/functions.md

@@ -24,6 +24,7 @@ n(run(4))
 - `cat(...patterns)` / `slowcat(...patterns)` — plays one whole pattern per cycle, cycling through the list (`cat` and `slowcat` are the same function).
 - `seq(...patterns)` / `fastcat(...patterns)` — plays each pattern in its own equal slice of one cycle (`seq` and `fastcat` are the same function).
 - `arrange(...[cycles, pattern])` — plays each pattern for the given number of cycles, in order, then repeats the whole list every total number of cycles (see reference/transitions.md "Sections over many cycles").
+- `arrange` takes patterns: it calls `.fast` on each item without turning it into a pattern, so a single-quoted string item throws when the code is evaluated.
 - The page's Parts view and Timeline section row show an `arrange()` call as parts only when each section is a `[length, pattern]` array whose length is a whole number above zero; the length is written as a number, as the name of a top-level `const` holding a number, or as arithmetic with `+ - * /` over those; a section may be the name of a top-level `const` holding one `[length, pattern]` array, and a spread of a top-level `const` holding such arrays is read as its sections; other `arrange()` calls still play but are not shown as parts, and the Parts view says why.
 - `polymeter(...patterns)` — like `{ }` mini-notation: several sequences of different lengths sharing one clock.
 

package/reference/midi.md

@@ -72,6 +72,8 @@ A program change and a note at the same instant go out in no fixed order, so a p
 
 The Moontide page reads `sound` when the user has described instruments in instruments.json: `.midi('port name', { midichannel: 3, sound: 'sound name' })` makes the page send that instrument's program change before the new code plays, and get_midi_instruments lists each instrument's sounds. With a change that waits for a bar or phrase line, the page sends the program change just before the line, timestamped at the line.
 
+A track's `.midi()` options are sent once when the code is evaluated, not at a section change; two variations asking different sounds of one channel are refused.
+
 The Moontide page also reads `controls` when the user has described instruments in instruments.json: `.midi('port name', { midichannel: 3, controls: { volume: 100 } })` sets one static level per control of that instrument, in the control's own range, and the page sends it before the new code plays. Control ids and ranges come from get_midi_instruments; a control that leaves the code goes back to the instrument's default; a sweep stays `ccn` and `ccv`. With a change that waits for a bar or phrase line, the page sends the controls just before the line, timestamped at the line.
 
 ## What a MIDI track ignores

package/reference/structure.md

@@ -0,0 +1,131 @@
+# Song structure
+
+Applies to @strudel/repl 1.3.0, the version the Moontide page loads (it bundles @strudel/core 1.2.6, @strudel/mini 1.2.6, @strudel/tonal 1.2.6, @strudel/transpiler 1.2.6, @strudel/webaudio 1.3.0 and @strudel/soundfonts 1.3.0).
+
+How a piece declares its song structure: one `const song` at the top that names the sections and their lengths and says, for every track in every section, which variation plays or that the track rests, followed by a few helper lines that turn the declaration into music. The page reads the declaration from the text of the code and shows it in the Parts view; nothing is added to the code by the page, and the same code plays in plain Strudel.
+
+## The template
+
+```js
+const harmony = 'C3:major';
+const song = {
+  shift: 0,
+  sections: [['sectionA', 6]],
+  plan: { sectionA: { trackA: 'variationA' } },
+  groups: {},
+};
+const total = song.sections.reduce((a, [, n]) => a + n, 0);
+const clock = timeCat(...song.sections.map(([name, n]) => [n, pure(name)])).slow(total).late(song.shift);
+const play = (track, variations) => {
+  const cells = {};
+  for (const [name, , own] of song.sections) {
+    const key = (song.plan[name] || {})[track];
+    if (key === undefined) throw new Error('song: section ' + name + ' has no cell for track ' + track);
+    const v = key === '-' ? silence : variations[key];
+    if (v === undefined) throw new Error('song: section ' + name + ', track ' + track + ': no variation ' + key + ' (it has ' + Object.keys(variations).join(', ') + ')');
+    cells[name] = typeof v === 'function' ? v(own || harmony) : Array.isArray(v) ? v[1] : v;
+  }
+  return clock.pickRestart(cells);
+};
+const trackA = {
+  variationA: (h) => n("0 2 4").scale(h),
+};
+trackA: play('trackA', trackA);
+```
+
+The block above is a complete piece with one section and one track, and it plays as it stands. The names and the length in it are placeholders.
+
+## The declaration
+
+- `song.shift` is a number of cycles that moves every section start later; 0 means no shift.
+- `song.sections` lists the sections in playing order. Each entry is `['name', length]`, with a whole length above zero written out as a number; a third entry, as in `['name', length, 'E3:minor']`, gives that section its own harmony. A section name can come round again later in the list.
+- `song.plan` is keyed by section name, then by track name. Each cell is the name of one of that track's variations, or `'-'` for a rest. Every track has a cell in every section.
+- `song.groups` is data: an object of named groups, each a list of track names or an object of groups, nested to any depth. A group changes nothing in what plays; a track can sit in one group only.
+
+A structure with one section is valid, as the template shows. There is no limit on the number of sections, tracks, variations or group depth, and a track can rest in any section.
+
+There is no default form. How many sections and tracks a piece has, what they are called and how long each section lasts come from the music asked for, and can differ from one piece to the next.
+
+Write section names, track names and harmonies in single quotes inside the song declaration: a double-quoted string is a mini-notation pattern and the clock then fails with a message about `late`. The helper's messages are joined with `+`, because a template literal is a mini-notation pattern in the page too (see the tidal-differences topic).
+
+## The helper
+
+The helper lines of the template are written as they are, with the declaration above them and the tracks below. The page recognises the text and says when it was changed or is missing; it never rewrites it.
+
+The helper plays each track's variation for the section the clock names, starts it at its first cycle, and throws, naming the section and the track, for a missing cell or an unknown variation.
+
+A section plays each track's variation from its first cycle every time the section comes round, also when the same name is used twice.
+
+A cell that names no variation is refused when the code is evaluated, with the section and the track named. Without that check a wrong name would play one stray default tone per cycle and report nothing, so a mistake in the last section would go unseen.
+
+## Tracks and variations
+
+One const per track holds only that track's variations: an object from a variation name to a variation. The track's statement is `name: play('name', name)`, with the same name as its label and as the first argument of the call.
+
+A variation is one of three kinds:
+
+- a pattern, played as it is;
+- a function that receives the section's harmony and returns a pattern;
+- a two-element array, a harmony it was written for and then a pattern: a fixed variation, played as written whatever the section's harmony is.
+
+Write each variation out where it is listed, as a call, a function or a pair. A variation given as a bare name or another expression is refused by the page, because the text does not say whether it is a pattern, a function or a pair.
+
+Put `.postgain(n)` and `.midi('port')` at the end of the track's own statement, not inside its variations, which is where the Mixer reads and writes them. A fixed `.gain(n)` on the statement makes the Mixer's fader write the gain instead of the post-gain. A track's `.midi()` options are sent once when the code is evaluated, not at a section change (see the midi topic).
+
+## Harmony
+
+A section's harmony is its third entry; without one, the harmony is the piece's own `const harmony` line (see the theory topic). Both are single-quoted text, a scale such as `'E3:minor'` or chord symbols such as `'Am'`.
+
+A variation in degrees is written as a function of the section's harmony, `(h) => n("0 2 4").scale(h)`; do not read a global harmony pattern inside a variation. A variation starts over at the first cycle of its section, so a global pattern read inside it starts over too and gives every section after the first the scale of the first one. A chord harmony works the same way: `(h) => chord(h).voicing()` receives the chord of its section.
+
+To move a pattern of degrees up, add `n(k)`, not the bare number `k`. A bare number changes nothing in a pattern of degrees.
+
+A note held across a section line is cut at the line and is not struck again; the next section's first note starts at the line, in its own harmony.
+
+## Changing a structure
+
+Changing a length, or adding or removing a section, counts the position again from the new lengths, so the music can move to another section. An older piece without a structure keeps its form when only part of it changes: a small change is made in place.
+
+## Two more shapes
+
+Another shape, with two sections, the second with its own harmony, and three tracks. It holds a rest, the three kinds of variation, and groups nested one level:
+
+```js
+// (the helper lines of the first block go here)
+const harmony = 'D3:dorian';
+const song = {
+  shift: 2,
+  sections: [['partOne', 10], ['partTwo', 6, 'A2:minor']],
+  plan: {
+    partOne: { trackB: 'plain', trackC: 'follow', trackD: '-' },
+    partTwo: { trackB: 'plain', trackC: 'follow', trackD: 'fixed' },
+  },
+  groups: { lower: ['trackB'], upper: { inner: ['trackC', 'trackD'] } },
+};
+const trackB = { plain: note("c3 e3 g3") };
+const trackC = { follow: (h) => n("0 2 4 6").scale(h) };
+const trackD = { fixed: ['D3:dorian', note("d4 f4 a4")] };
+trackB: play('trackB', trackB);
+trackC: play('trackC', trackC);
+trackD: play('trackD', trackD);
+```
+
+A third shape, with three entries in the section list, one name coming round again, a chord harmony and a track level set on the statement:
+
+```js
+// (the helper lines of the first block go here)
+const harmony = 'Am';
+const song = {
+  shift: 0,
+  sections: [['first', 12], ['second', 9], ['first', 12]],
+  plan: {
+    first: { trackE: 'low', trackF: 'follow' },
+    second: { trackE: 'high', trackF: '-' },
+  },
+  groups: { both: ['trackE', 'trackF'] },
+};
+const trackE = { low: note("c3 g3"), high: note("c4 g4 e4") };
+const trackF = { follow: (h) => chord(h).voicing() };
+trackE: play('trackE', trackE);
+trackF: play('trackF', trackF).postgain(0.6);
+```

package/reference/transitions.md

@@ -133,8 +133,20 @@ A tempo set by the waiting code with `setcps` or `setcpm` applies in the schedul
 
 ## Tempo
 
-`setcps(n)` and `setcpm(n)` (or the chained `.cpm(n)`, see reference/functions.md "Tempo") take effect the instant the code is evaluated — each is a single value read once at that moment, not a control that is queried continuously like a signal. In a change that waits for a bar or phrase line, they take effect at the line (see "Taking over on a bar or phrase line", above). Whether tempo itself can follow a continuous signal: this bundle's own `setcps`/`setcpm` accept a plain number, and unwrap a single-value ("pure") pattern into that same plain number if given one, but do not continuously sample a changing signal.
+`setcps(n)` and `setcpm(n)` (or the chained `.cpm(n)`, see reference/functions.md "Tempo") take effect the instant the code is evaluated — each is a single value read once at that moment, not a control that is queried continuously like a signal. In a change that waits for a bar or phrase line, they take effect at the line (see "Taking over on a bar or phrase line", above). Whether tempo itself can follow a continuous signal: this bundle's own `setcps`/`setcpm` accept a plain number, and unwrap a single-value ("pure") pattern into that same plain number if given one, but do not continuously sample a changing signal. A smooth change of tempo is asked for with `glideBars` (see "Tempo ramp", below).
 
 ```js
 setcpm(120)   // takes effect immediately when this code evaluates, then stays fixed
 ```
+
+## Tempo ramp
+
+`set_code` and `edit_code` take `glideBars`, a whole number of bars from 1 to 64, to move the tempo smoothly instead of jumping. The code states the tempo to reach with `setcps` or `setcpm`. The tempo moves from the tempo that plays to that tempo over that many bars, in equal small steps of BPM, and ends exactly on the code's tempo. It starts at once, or at the line when `at` is `'bar'` or `'phrase'`, from the tempo that plays then.
+
+A ramp is refused, and nothing changes, when nothing plays or the music is stopped, when the code sets no tempo, and when the code sets the tempo that already plays. Send the change again without `glideBars`.
+
+A ramp goes on through any later program that states the same tempo again, whatever its source (a Mixer move, a Song grid edit, a Timeline edit, a hand edit, `set_code`, `edit_code`, `restore_version`), and through a program that fails. A program that states another tempo cancels it, and that tempo plays at once. A program with no tempo statement cancels it, and the tempo stays where it was. A new `glideBars` replaces it, from the tempo that plays then. Stop cancels it, and the next Play starts at the code's tempo. A page reload, or another tab taking over, ends it, and the code's tempo plays.
+
+The reply to a change states the ramp once. A ramp that ended early is told once, in a later reply; a ramp that finished is not announced. A ramp is an event of the page, never a version: it writes no tempo into the code or the history.
+
+A pattern's `.cpm()` is worked out once, when the program runs, against the tempo at that moment (the code's own tempo when its `setcps` or `setcpm` comes first), and its length in cycles stays fixed after that, so it moves with a ramp like the rest of the music. The MIDI clock follows every step of a ramp. How a hardware instrument that follows the MIDI clock reacts to a ramp has not been verified.