moontide-mcp 2.2.0 → 2.4.1

package/dist/protocol.js

@@ -3,6 +3,13 @@
 import { z } from 'zod';
 /** How many of the newest versions the History view loads first. */
 export const HISTORY_WINDOW_SIZE = 100;
+/**
+ * Why the memory guard refused a message: not readable as bytes, longer than it reads, a system exclusive message that
+ * does not end, not a Roland data set for the instrument's model, an instrument whose temporary areas are not known,
+ * an address outside the temporary scene and tones, a wrong checksum, or an NRPN message that is not one of the part offsets of
+ * the NRPN family of the instrument. Worded in src/midi-state.ts.
+ */
+export const MEMORY_GUARD_REASONS = ['not-bytes', 'too-long', 'incomplete', 'not-data-set', 'unknown-areas', 'outside', 'checksum', 'nrpn'];
 // Every string in a midi-state is at most MAX_MIDI_NAME_LENGTH characters (the page cuts longer
 // names with an ellipsis, the server rejects them and never trims); the arrays and the failure
 // name are bounded too.
@@ -16,6 +23,8 @@ export const MAX_MIDI_EVENTS = 20;
 // message. page/midi-rig.js mirrors the limits below (RIG_LIMITS) and the message shape
 // by hand; test/midi-rig.test.js checks both sides.
 export const MAX_RIG_INSTRUMENTS = 16;
+// The most MIDI input ports the setup file may name (its inputs list); mirrored by RIG_LIMITS.inputs in page/midi-rig.js.
+export const MAX_RIG_INPUTS = 4;
 export const MAX_RIG_SOUNDS = 512;
 // The most controls a model may declare: the model schema's own `.max(32)` of `controls` in
 // src/instruments.ts; mirrored by RIG_LIMITS.controls in page/midi-rig.js.
@@ -30,6 +39,12 @@ export const MAX_RIG_PROBLEMS = 20;
 export const MAX_RIG_DRUM_MAPS = 16;
 export const MAX_RIG_DRUM_NOTES = 128;
 export const MAX_RIG_DRUM_NAME = 40;
+// The most setting rows one level (tone, part or scene) of a model may describe, and the most engines a model may
+// declare; mirrored by RIG_LIMITS.settings and RIG_LIMITS.engines in page/midi-rig.js. The page cannot import the
+// vocabulary, so this is a fixed number; test/vocabulary.test.js checks that the whole vocabulary fits in it. It is 512
+// because the MT-32 map holds about 250 tone settings, and a settings event may name every one of them.
+export const MAX_RIG_SETTINGS = 512;
+export const MAX_RIG_ENGINES = 16;
 /**
  * The shortest and longest phrase, in cycles, that set_code accepts with at: 'phrase'. page/change-timing.js
  * mirrors both by hand (test/protocol.test.js checks both sides).
@@ -82,6 +97,24 @@ export const MAX_ASK_ID_LENGTH = 64;
 // The longest sentence Claude can close a page request with. The page shows it with an ellipsis in a
 // row and whole in the detail.
 export const MAX_ANSWER_TEXT_LENGTH = 200;
+// How the notes of a motif sent from the Scratchpad got on its roll, in the order the request lists them; `mixed` is more than one way.
+// page/scratch-model.js mirrors it by hand (test/ask.test.js checks both sides).
+export const MOTIF_SOURCES = ['played', 'drawn', 'tapped', 'mixed'];
+// The ids of the five grids of the Scratchpad, in the page's order. page/scratch-model.js mirrors them by hand
+// (test/ask.test.js checks both sides).
+export const MOTIF_GRIDS = ['quarter', 'eighth', 'sixteenth', 'eighth-triplet', 'sixteenth-triplet'];
+// The fewest and the most cycles one motif has. page/scratch-model.js mirrors them by hand (test/ask.test.js checks both sides).
+export const MIN_MOTIF_CYCLES = 1;
+export const MAX_MOTIF_CYCLES = 8;
+// The most characters the phrase of a motif has. A bound below MAX_REQUEST_LINE_BYTES so the schema is bounded; the line's own
+// bound stays the real limit, and a phrase is refused whole and never cut. page/ask.js mirrors it by hand (test/ask.test.js checks
+// both sides).
+export const MAX_MOTIF_PHRASE_LENGTH = 8000;
+// The lane of a phrase: note("...").velocity("..."), with only the characters of the phrase inside the quotes.
+const MOTIF_PHRASE_LANE = 'note\\("[a-g0-9#.~_\\[\\],/ <>]*"\\)\\.velocity\\("[a-g0-9#.~_\\[\\],/ <>]*"\\)';
+// The shape of a phrase: one lane, or stack(...) of two or more. Nothing but notes and velocities can travel in the phrase field.
+// page/scratch-model.js's PHRASE_SHAPE is the same pattern, written by hand (test/ask.test.js checks both sides).
+export const MOTIF_PHRASE_SHAPE = new RegExp(`^(${MOTIF_PHRASE_LANE}|stack\\(${MOTIF_PHRASE_LANE}(, ${MOTIF_PHRASE_LANE})+\\))$`);
 // The kinds of thing a right-click can point at. The Jam view is
 // the source of 'note' (a pitch class with its role in the scale) and 'warning' (a chord that leaves it).
 export const ASK_CONTEXT_KINDS = [
@@ -104,6 +137,7 @@ export const ASK_CONTEXT_KINDS = [
     'cell',
     'group',
     'range',
+    'motif',
 ];
 // The kinds of gesture a request can carry: what the user did to a note of the Timeline that the page could not
 // apply itself. page/ask.js mirrors the list by hand (test/ask.test.js checks both sides).
@@ -113,6 +147,12 @@ export const MAX_GESTURE_SEMITONES = 127;
 const audioStateSchema = z.enum(['playing', 'waiting-for-click', 'stopped']);
 const midiName = z.string().max(MAX_MIDI_NAME_LENGTH);
 const midiChannel = z.number().int().min(1).max(16);
+// The names of the settings an event is about: a setting name is a lowercase letter, then letters and digits
+// (page/midi-rig.js reads the same pattern), and a level holds at most MAX_RIG_SETTINGS of them.
+const settingNames = z
+    .array(z.string().regex(/^[a-z][A-Za-z0-9]{0,39}$/))
+    .min(1)
+    .max(MAX_RIG_SETTINGS);
 // A longer string is rejected, never trimmed (the page cuts before it sends).
 const askString = z.string().max(MAX_ASK_CONTEXT_LENGTH);
 const askName = askString.min(1);
@@ -168,6 +208,18 @@ export const askGestureSchema = z.discriminatedUnion('kind', [
         more: z.number().int().nonnegative(),
     }),
 ]);
+// The keys of a motif. z.object drops a key it does not name, so test/ask.test.js pins these keys equal to the ones page/scratch-model.js's
+// motifRequest can give. A cycle, a count or a phrase out of bounds is rejected, never trimmed, and a phrase that is not in the phrase form
+// is rejected whole.
+export const askMotifShape = {
+    source: z.enum(MOTIF_SOURCES),
+    cycle: z.number().int().nonnegative().optional(),
+    cycles: z.number().int().min(MIN_MOTIF_CYCLES).max(MAX_MOTIF_CYCLES),
+    grid: z.enum(MOTIF_GRIDS),
+    notes: z.number().int().min(1),
+    phrase: z.string().min(1).max(MAX_MOTIF_PHRASE_LENGTH).regex(MOTIF_PHRASE_SHAPE),
+};
+const askMotifSchema = z.object(askMotifShape);
 const askContextSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('session') }),
     z.object({ kind: z.literal('version'), id: z.number().int().positive(), label: askName.optional() }),
@@ -246,6 +298,7 @@ const askContextSchema = z.discriminatedUnion('kind', [
         message: 'outside notes come only with a fit of does-not-fit',
     }),
     z.object({ kind: z.literal('group'), name: askName, parent: askName.optional() }),
+    z.object({ kind: z.literal('motif') }),
 ]);
 /** A structure note holds at most this many lines, each at most this many characters. */
 export const MAX_STRUCTURE_NOTE_LINES = 3;
@@ -382,9 +435,10 @@ const pageMessageSchema = z.union([
         context: askContextSchema,
         chip: z.string().min(1).max(MAX_ASK_CONTEXT_LENGTH),
         current: z.number().int().positive().nullable(),
-        // z.object drops a key it does not name, so the moment and the gesture must be named here to reach Claude.
+        // z.object drops a key it does not name, so the moment, the gesture and the motif must be named here to reach Claude.
         moment: askMomentSchema.optional(),
         gesture: askGestureSchema.optional(),
+        motif: askMotifSchema.optional(),
     })
         // A gesture about one note of a lane rides only on a lane context that carries a moment; the range gesture and the range
         // context come together and carry no moment (the notes of the range are in the gesture).
@@ -393,7 +447,11 @@ const pageMessageSchema = z.union([
         if (isRange || ask.context.kind === 'range')
             return isRange && ask.context.kind === 'range' && ask.moment === undefined;
         return ask.gesture === undefined || (ask.context.kind === 'lane' && ask.moment !== undefined);
-    }, { message: 'a gesture needs a lane context and a moment, and a range gesture goes only with a range context' }),
+    }, { message: 'a gesture needs a lane context and a moment, and a range gesture goes only with a range context' })
+        // A motif goes only with the motif context and the motif context needs one; a motif request carries no moment and no gesture.
+        .refine((ask) => (ask.motif !== undefined) === (ask.context.kind === 'motif') && (ask.motif === undefined || (ask.moment === undefined && ask.gesture === undefined)), {
+        message: 'a motif goes only with a motif context, which needs it, and carries no moment and no gesture',
+    }),
     z.object({
         type: z.literal('midi-state'),
         access: z.enum(['idle', 'pending', 'enabled', 'denied', 'unsupported', 'failed']),
@@ -421,9 +479,28 @@ const pageMessageSchema = z.union([
             z.object({
                 kind: z.literal('send-failed'),
                 instrument: midiName,
-                what: z.enum(['reset', 'setup']),
+                what: z.enum(['reset', 'setup', 'settings']),
                 failure: z.string().max(MAX_MIDI_FAILURE_LENGTH),
             }),
+            z.object({ kind: z.literal('settings-scene'), instrument: midiName, names: settingNames }),
+            z
+                .object({
+                kind: z.literal('settings-left'),
+                instrument: midiName,
+                level: z.enum(['tone', 'part', 'scene']),
+                channel: midiChannel.nullable(),
+                names: settingNames,
+            })
+                // A tone or part setting belongs to a channel; a scene setting reaches every part and has none.
+                .refine((event) => (event.level === 'scene') === (event.channel === null), {
+                message: 'a scene setting has no channel, a tone or part setting has one',
+            }),
+            z.object({
+                kind: z.literal('sysex-refused'),
+                instrument: midiName,
+                source: z.enum(['code', 'settings', 'reset']),
+                reason: z.enum(MEMORY_GUARD_REASONS),
+            }),
             z.object({ kind: z.literal('clock-dropped') }),
         ]))
             .max(MAX_MIDI_EVENTS)

package/dist/reference.js

@@ -65,6 +65,18 @@ export const REFERENCE_TOPICS = [
         title: 'MIDI output',
         summary: 'sending a track to a MIDI port with .midi(): port names, channels, notes, control and program changes, the MIDI clock Moontide sends, and what Stop sends',
     },
+    {
+        id: 'settings',
+        file: 'settings.md',
+        title: 'Synth settings',
+        summary: 'the tone, part and scene settings of a MIDI instrument written in .midi(): what each level reaches, the setting names, what is refused, when they are sent and what undoes them',
+    },
+    {
+        id: 'motif',
+        file: 'motif.md',
+        title: 'Motif requests',
+        summary: 'how to read a motif sent from the Scratchpad: its fields, the moment, the grid, the phrase form, the velocities, the source words, what the words can ask and what the page did',
+    },
 ];
 export const REFERENCE_TOPIC_IDS = REFERENCE_TOPICS.map((topic) => topic.id);
 /** Module-relative, not cwd-relative (works wherever npm installs the package). */

package/dist/vocabulary.js

@@ -0,0 +1,420 @@
+// The settings vocabulary: the names code uses to set a tone, a part or a scene, and the optional
+// `settings` description of an instrument model that maps those names to the messages the instrument
+// takes. The names say nothing about how a setting is sent: a model maps the same name to a Roland data
+// set, a control change or an NRPN, and the code does not change. A wrong description is a list of
+// problems (a field and a reason), never an exception, so a hand edit in progress cannot crash the server.
+//
+// Nothing here sends a message: the page receives the names, the ranges and the message of each setting
+// (settingsMessage) and builds the bytes itself, so the model file stays the one place that says where a setting goes.
+import { z } from 'zod';
+import { MAX_RIG_ENGINES, MAX_RIG_SETTINGS } from './protocol.js';
+import { CONTROL_CHARS, dataByteSchema, idSchema } from './rig-util.js';
+export const SETTING_LEVELS = ['tone', 'part', 'scene'];
+// The tone names of one oscillator, the filter, the two envelopes, the LFO and the FM engine's global
+// settings, then the names of the engines whose settings are their own (the number of a partial sits inside
+// the name); the six operators follow, built from one list so their names stay in step.
+const TONE_NAMES = [
+    'osc1Wave', 'osc1Feet', 'osc1Tune', 'osc1Level',
+    'osc2Wave', 'osc2Feet', 'osc2Tune', 'osc2Level',
+    'filterType', 'filterCutoff', 'filterResonance', 'filterEnvDepth',
+    'env1Attack', 'env1Decay', 'env1Sustain', 'env1Release',
+    'env2Attack', 'env2Decay', 'env2Sustain', 'env2Release',
+    'lfoRate', 'lfoOscDepth', 'lfoFilterDepth',
+    'algorithm', 'feedback',
+    'partial1Cutoff', 'toneCoarseTune',
+    'partialMute', 'partial1Level',
+];
+// The part names that are offsets from the instrument's normal sound (an NRPN of the GS family): the lowest value moves the
+// sound down, it does not close or silence anything.
+const PART_OFFSET_NAMES = [
+    'vibratoRateOffset', 'vibratoDepthOffset', 'vibratoDelayOffset',
+    'cutoffOffset', 'resonanceOffset',
+    'attackOffset', 'decayOffset', 'releaseOffset',
+];
+const OPERATOR_SETTINGS = ['Level', 'Ratio', 'Detune', 'Attack', 'Decay', 'Sustain', 'Release'];
+const OPERATOR_COUNT = 6;
+const operatorNames = [];
+for (let operator = 1; operator <= OPERATOR_COUNT; operator++) {
+    for (const setting of OPERATOR_SETTINGS)
+        operatorNames.push(`op${operator}${setting}`);
+}
+// The settings of one partial of a timbre with four partials, in the order of the instrument's own table (pitch, wave,
+// pitch envelope, pitch LFO, filter, filter envelope, volume, volume envelope); the four partials are built from this one
+// list so their names stay in step. Two names of partial 1 already stand in TONE_NAMES and are not added twice.
+const PARTIAL_SETTINGS = [
+    'CoarseTune', 'FineTune', 'PitchKeyFollow', 'BendSwitch', 'Wave', 'PcmWave', 'PulseWidth', 'PulseWidthVelocity',
+    'PitchEnvDepth', 'PitchEnvVelocity', 'PitchEnvTimeKeyFollow',
+    'PitchEnvTime1', 'PitchEnvTime2', 'PitchEnvTime3', 'PitchEnvTime4',
+    'PitchEnvLevel0', 'PitchEnvLevel1', 'PitchEnvLevel2', 'PitchEnvSustain', 'PitchEnvEnd',
+    'PitchLfoRate', 'PitchLfoDepth', 'PitchLfoModSens',
+    'Cutoff', 'Resonance', 'CutoffKeyFollow', 'FilterBiasPoint', 'FilterBiasLevel',
+    'FilterEnvDepth', 'FilterEnvVelocity', 'FilterEnvDepthKeyFollow', 'FilterEnvTimeKeyFollow',
+    'FilterEnvTime1', 'FilterEnvTime2', 'FilterEnvTime3', 'FilterEnvTime4', 'FilterEnvTime5',
+    'FilterEnvLevel1', 'FilterEnvLevel2', 'FilterEnvLevel3', 'FilterEnvSustain',
+    'Level', 'LevelVelocity', 'AmpBiasPoint1', 'AmpBiasLevel1', 'AmpBiasPoint2', 'AmpBiasLevel2',
+    'AmpEnvTimeKeyFollow', 'AmpEnvTimeVelocity',
+    'AmpEnvTime1', 'AmpEnvTime2', 'AmpEnvTime3', 'AmpEnvTime4', 'AmpEnvTime5',
+    'AmpEnvLevel1', 'AmpEnvLevel2', 'AmpEnvLevel3', 'AmpEnvSustain',
+];
+const PARTIAL_COUNT = 4;
+// The tone names of a timbre with four partials after the earlier names: how two partials are joined, the envelope mode,
+// every partial, then the settings of the patch that a program change loads again.
+const timbreNames = ['structure12', 'structure34', 'envMode'];
+for (let partial = 1; partial <= PARTIAL_COUNT; partial++) {
+    for (const setting of PARTIAL_SETTINGS) {
+        const name = `partial${partial}${setting}`;
+        if (!TONE_NAMES.includes(name))
+            timbreNames.push(name);
+    }
+}
+timbreNames.push('keyShift', 'toneFineTune', 'bendRange', 'assignMode', 'toneReverbSwitch');
+/** The setting names of each level, in the order a list shows them. Room for the FM engine is already here. */
+export const SETTING_VOCABULARY = Object.freeze({
+    tone: Object.freeze([...TONE_NAMES, ...operatorNames, ...timbreNames]),
+    part: Object.freeze(['level', 'pan', 'chorusSend', 'reverbSend', 'delaySend', ...PART_OFFSET_NAMES]),
+    scene: Object.freeze([
+        'level',
+        'chorusSwitch', 'chorusType', 'chorusLevel',
+        'delaySwitch', 'delayType', 'delayLevel',
+        'reverbSwitch', 'reverbType', 'reverbLevel',
+        'driveAmount', 'driveSwitch',
+        'masterTune', 'reverbTime',
+    ]),
+});
+const settingValueSchema = z.number().int().min(0).max(65535);
+// The message a setting becomes: a Roland data set at an address, an NRPN or a control change.
+const messageSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('roland-dt1'), address: z.string(), size: z.union([z.literal(1), z.literal(2), z.literal(4)]) }),
+    z.strictObject({ kind: z.literal('nrpn'), msb: dataByteSchema, lsb: dataByteSchema }),
+    z.strictObject({ kind: z.literal('cc'), cc: dataByteSchema }),
+]);
+const rowSchema = z.strictObject({
+    name: z.string().min(1).max(40),
+    min: settingValueSchema,
+    max: settingValueSchema,
+    // Tone rows only, and required when the model declares engines: the engines that have this setting.
+    engines: z.array(idSchema).min(1).max(MAX_RIG_ENGINES).optional(),
+    message: messageSchema,
+});
+/** The optional `settings` field of a model; every key is optional, and a model without it stays valid. */
+export const settingsSchema = z.strictObject({
+    // The engines a tone can belong to (the sound catalog places a sound on one of them).
+    engines: z.array(z.strictObject({ id: idSchema, name: z.string().min(1).max(40) })).min(1).max(MAX_RIG_ENGINES).optional(),
+    // The model ID bytes of the Roland data sets, as hex text.
+    rolandModel: z.string().optional(),
+    // The NRPN family of the instrument's NRPN rows. Moontide knows one: 'gs', the part offsets of the Roland GS family.
+    nrpnFamily: z.literal('gs').optional(),
+    tone: z.array(rowSchema).max(MAX_RIG_SETTINGS).optional(),
+    part: z.array(rowSchema).max(MAX_RIG_SETTINGS).optional(),
+    scene: z.array(rowSchema).max(MAX_RIG_SETTINGS).optional(),
+});
+/**
+ * The largest value a message carries: a control change 7 bits, an NRPN 7 bits (the page sends the data entry MSB only),
+ * and a Roland data set cuts a value into 4-bit pieces, one per byte of its size.
+ */
+export function messageMax(message) {
+    if (message.kind === 'cc')
+        return 127;
+    if (message.kind === 'nrpn')
+        return 127;
+    if (message.size === 1)
+        return 127;
+    if (message.size === 2)
+        return 255;
+    return 65535;
+}
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let row = 1; row <= a.length; row++) {
+        const current = [row];
+        for (let column = 1; column <= b.length; column++) {
+            const same = a[row - 1] === b[column - 1] ? 0 : 1;
+            current[column] = Math.min(previous[column] + 1, current[column - 1] + 1, previous[column - 1] + same);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** The vocabulary name of a level closest to `name`, when it is at most 3 edits away. */
+function closestName(level, name) {
+    let best = null;
+    let bestDistance = 4;
+    for (const candidate of SETTING_VOCABULARY[level]) {
+        const distance = editDistance(name, candidate);
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+const hex2 = (byte) => byte.toString(16).toUpperCase().padStart(2, '0');
+/**
+ * The data range of each NRPN family the page knows (KNOWN_NRPNS in page/midi-settings.js; a test pins both): a row of the
+ * family whose range leaves it would be refused at every use, so it is refused when the model loads.
+ */
+export const NRPN_FAMILY_RANGES = Object.freeze({
+    gs: Object.freeze({ min: 14, max: 114 }),
+});
+/**
+ * The Roland model IDs whose temporary areas the page knows, with the length of the addresses their data sets take
+ * (TEMPORARY_AREAS in page/midi-settings.js; a test pins both). A row of another length would be refused at every use.
+ */
+export const ROLAND_ADDRESS_SIZES = Object.freeze([
+    Object.freeze({ model: Object.freeze([0x00, 0x00, 0x00, 0x65]), size: 4 }),
+    Object.freeze({ model: Object.freeze([0x16]), size: 3 }),
+]);
+/**
+ * Why hex text is not 1 to 4 two-digit bytes of at most 7F (3 or 4 with `isAddress`: a data set takes a three-byte or a
+ * four-byte address, and a shorter one would make the instrument read data bytes as address bytes; which of the two the
+ * instrument takes is checked when the bytes are built), or null when it is.
+ */
+function hexProblem(text, isAddress = false) {
+    const parts = text.trim().split(/\s+/).filter((part) => part !== '');
+    if (parts.length === 0)
+        return 'must not be empty';
+    for (const part of parts) {
+        if (!/^[0-9a-fA-F]{2}$/.test(part))
+            return `"${part}" is not a two-digit hex byte`;
+    }
+    if (isAddress && (parts.length < 3 || parts.length > 4))
+        return 'must be 3 or 4 bytes';
+    if (parts.length > 4)
+        return 'must be 1 to 4 bytes';
+    for (let index = 0; index < parts.length; index++) {
+        const byte = Number.parseInt(parts[index], 16);
+        if (byte > 0x7f)
+            return `byte ${index} (${hex2(byte)}) is above 7F`;
+    }
+    return null;
+}
+/** The engine rules: ids and names unique, a tone row names declared engines when the model declares some, no other row names any. */
+function checkEngines(settings, add) {
+    const declared = settings.engines;
+    const first = new Map();
+    const firstNamed = new Map();
+    (declared ?? []).forEach((engine, index) => {
+        if (CONTROL_CHARS.test(engine.name))
+            add(`engines[${index}].name`, 'contains a control character');
+        const earlier = first.get(engine.id);
+        if (earlier === undefined)
+            first.set(engine.id, index);
+        else
+            add(`engines[${index}].id`, `same id as engines[${earlier}]`);
+        const sameName = firstNamed.get(engine.name);
+        if (sameName === undefined)
+            firstNamed.set(engine.name, index);
+        else
+            add(`engines[${index}].name`, `same name as engines[${sameName}]`);
+    });
+    (settings.tone ?? []).forEach((row, index) => {
+        const at = `tone[${index}].engines`;
+        if (declared === undefined) {
+            if (row.engines !== undefined)
+                add(at, 'the model declares no engines');
+        }
+        else if (row.engines === undefined) {
+            add(at, 'required: the model declares engines');
+        }
+        else {
+            row.engines.forEach((id, position) => {
+                if (!first.has(id))
+                    add(`${at}[${position}]`, `unknown engine "${id}", engines: ${declared.map((engine) => engine.id).join(', ')}`);
+            });
+        }
+    });
+    for (const level of ['part', 'scene']) {
+        (settings[level] ?? []).forEach((row, index) => {
+            if (row.engines !== undefined)
+                add(`${level}[${index}].engines`, `${level} settings reach every engine`);
+        });
+    }
+}
+/**
+ * Why a row repeats the name of earlier rows of its level, or null when it may. A tone name may have one row per engine
+ * (the same setting sits at another address on each engine), so a tone row may repeat a name only when the model declares
+ * engines and no engine appears in two rows of the name; every other repeat is refused.
+ */
+function repeatProblem(level, settings, row, earlier) {
+    const rows = settings[level] ?? [];
+    for (const index of earlier) {
+        const other = rows[index];
+        const perEngine = level === 'tone' && settings.engines !== undefined && row.engines !== undefined && other.engines !== undefined;
+        if (!perEngine)
+            return `same name as ${level}[${index}]`;
+        const shared = row.engines.find((id) => other.engines.includes(id));
+        if (shared !== undefined)
+            return `same name as ${level}[${index}], and both reach engine "${shared}"`;
+    }
+    return null;
+}
+/**
+ * The checks that need more than one field of a settings description; the shape is already valid.
+ * Paths are relative to the settings object (`tone[0].name`); the empty path is the object itself.
+ */
+export function settingsProblems(settings) {
+    const problems = [];
+    if (settings === undefined)
+        return problems;
+    const add = (field, reason) => {
+        problems.push({ field, reason });
+    };
+    if (SETTING_LEVELS.every((level) => (settings[level] ?? []).length === 0))
+        add('', 'describes no setting');
+    let needsRolandModel = false;
+    let needsNrpnFamily = false;
+    // The rows with a well-formed data set address, checked against the address length of the model ID below.
+    const addressed = [];
+    for (const level of SETTING_LEVELS) {
+        // The rows seen so far by name: a tone name may repeat once per engine (see repeatProblem), no other name may.
+        const seen = new Map();
+        (settings[level] ?? []).forEach((row, index) => {
+            const at = `${level}[${index}]`;
+            if (!SETTING_VOCABULARY[level].includes(row.name)) {
+                const other = SETTING_LEVELS.find((candidate) => candidate !== level && SETTING_VOCABULARY[candidate].includes(row.name));
+                const closest = closestName(level, row.name);
+                add(`${at}.name`, other !== undefined
+                    ? `"${row.name}" is a ${other} setting name, not a ${level} one`
+                    : `"${row.name}" is not a ${level} setting name${closest === null ? '' : ` (closest: ${closest})`}`);
+            }
+            else {
+                const earlier = seen.get(row.name) ?? [];
+                const problem = repeatProblem(level, settings, row, earlier);
+                if (problem !== null)
+                    add(`${at}.name`, problem);
+                seen.set(row.name, [...earlier, index]);
+            }
+            const carried = messageMax(row.message);
+            if (row.max < row.min)
+                add(`${at}.max`, 'must not be below min');
+            else if (row.max > carried)
+                add(`${at}.max`, `${row.max} is more than this message carries (${carried})`);
+            if (row.message.kind === 'roland-dt1') {
+                needsRolandModel = true;
+                const address = hexProblem(row.message.address, true);
+                if (address !== null)
+                    add(`${at}.message.address`, address);
+                else
+                    addressed.push({ at, length: row.message.address.trim().split(/\s+/).length });
+            }
+            if (row.message.kind === 'nrpn') {
+                needsNrpnFamily = true;
+                if (level === 'scene')
+                    add(`${at}.message`, 'an NRPN reaches one channel, so it is not a scene setting');
+                if (settings.nrpnFamily !== undefined) {
+                    const family = NRPN_FAMILY_RANGES[settings.nrpnFamily];
+                    if (row.min < family.min)
+                        add(`${at}.min`, `${row.min} is below the lowest value of the ${settings.nrpnFamily} family (${family.min})`);
+                    if (row.max > family.max)
+                        add(`${at}.max`, `${row.max} is above the highest value of the ${settings.nrpnFamily} family (${family.max})`);
+                }
+            }
+        });
+    }
+    checkEngines(settings, add);
+    if (settings.rolandModel === undefined) {
+        if (needsRolandModel)
+            add('rolandModel', 'required: a roland-dt1 setting needs the model ID');
+    }
+    else {
+        const bad = hexProblem(settings.rolandModel);
+        if (bad !== null)
+            add('rolandModel', bad);
+        else {
+            // A model ID whose temporary areas Moontide knows takes one address length; any other takes 3 or 4 bytes.
+            const model = hexToBytes(settings.rolandModel);
+            const known = ROLAND_ADDRESS_SIZES.find((entry) => entry.model.length === model.length && entry.model.every((byte, index) => byte === model[index]));
+            if (known !== undefined) {
+                const modelText = model.map(hex2).join(' ');
+                for (const row of addressed) {
+                    if (row.length !== known.size)
+                        add(`${row.at}.message.address`, `must be ${known.size} bytes: the data sets of model ID ${modelText} take ${known.size}-byte addresses`);
+                }
+            }
+        }
+    }
+    if (needsNrpnFamily && settings.nrpnFamily === undefined)
+        add('nrpnFamily', 'required: an nrpn setting needs the NRPN family');
+    return problems;
+}
+/** Hex text as bytes. The description was checked when it was read, so a bad byte here is a fault: it throws. */
+function hexToBytes(text) {
+    return text
+        .trim()
+        .split(/\s+/)
+        .map((part) => {
+        if (!/^[0-9a-fA-F]{2}$/.test(part))
+            throw new Error(`Moontide: "${part}" is not a two-digit hex byte.`);
+        return Number.parseInt(part, 16);
+    });
+}
+/** The message of one row for the page, copied key by key so nothing else of the model rides along. */
+function rowMessage(message) {
+    if (message.kind === 'roland-dt1')
+        return { kind: 'roland-dt1', address: hexToBytes(message.address), size: message.size };
+    if (message.kind === 'nrpn')
+        return { kind: 'nrpn', msb: message.msb, lsb: message.lsb };
+    return { kind: 'cc', cc: message.cc };
+}
+/**
+ * The settings as the page gets them: names, ranges and the message of each row, copied key by key so no other
+ * key of the model rides along. Null when the model describes no settings.
+ */
+export function settingsMessage(settings) {
+    if (settings === undefined)
+        return null;
+    const declared = settings.engines !== undefined;
+    const row = (entry, withEngines) => ({
+        name: entry.name,
+        min: entry.min,
+        max: entry.max,
+        ...(withEngines && declared && entry.engines !== undefined ? { engines: [...entry.engines] } : {}),
+        message: rowMessage(entry.message),
+    });
+    return {
+        engines: (settings.engines ?? []).map((engine) => ({ id: engine.id, name: engine.name })),
+        rolandModel: settings.rolandModel === undefined ? null : hexToBytes(settings.rolandModel),
+        nrpnFamily: settings.nrpnFamily ?? null,
+        tone: (settings.tone ?? []).map((entry) => row(entry, true)),
+        part: (settings.part ?? []).map((entry) => row(entry, false)),
+        scene: (settings.scene ?? []).map((entry) => row(entry, false)),
+    };
+}
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+function messageText(message) {
+    if (message.kind === 'cc')
+        return `control change ${message.cc}`;
+    if (message.kind === 'nrpn')
+        return `NRPN ${message.msb} ${message.lsb}`;
+    return `Roland data set at ${hexBytesText(message.address)} over ${plural(message.size, 'byte')}`;
+}
+/** Hex text as two-digit upper-case bytes joined by single spaces. */
+function hexBytesText(text) {
+    return text
+        .trim()
+        .split(/\s+/)
+        .map((part) => part.toUpperCase())
+        .join(' ');
+}
+/**
+ * The save summary lines of a settings description, one fact per line, so nothing that reaches hardware
+ * later is hidden behind the user's yes: the engines, the Roland model ID, then every setting row in level order.
+ */
+export function settingsSummary(settings) {
+    const lines = [];
+    if (settings.engines !== undefined) {
+        lines.push(`Settings engines: ${settings.engines.map((engine) => `${engine.id} (${engine.name})`).join(', ')}.`);
+    }
+    if (settings.rolandModel !== undefined)
+        lines.push(`Settings Roland model ID: ${hexBytesText(settings.rolandModel)}.`);
+    if (settings.nrpnFamily !== undefined)
+        lines.push(`Settings NRPN family: ${settings.nrpnFamily}.`);
+    for (const level of SETTING_LEVELS) {
+        const label = `${level.charAt(0).toUpperCase()}${level.slice(1)}`;
+        for (const row of settings[level] ?? []) {
+            const engines = row.engines === undefined ? '' : `, engines ${row.engines.join(', ')}`;
+            lines.push(`${label} setting ${row.name}: ${row.min}-${row.max}, ${messageText(row.message)}${engines}.`);
+        }
+    }
+    return lines;
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "moontide-mcp",
-  "version": "2.2.0",
+  "version": "2.4.1",
   "mcpName": "io.github.konni-arcadia/moontide",
-  "description": "Claude steers live music by writing Strudel code played in a browser page",
+  "description": "Early: Claude steers live music by writing Strudel code played in a browser page",
   "keywords": [
     "mcp",
     "mcp-server",
@@ -46,6 +46,7 @@
     "prepack": "npm run build",
     "smoke:npx": "node scripts/smoke-npx.mjs",
     "check:reference": "node scripts/check-reference.mjs",
+    "build:site": "node scripts/build-site.mjs",
     "tint:report": "npm run build && node scripts/tint-report.mjs",
     "probe:page": "npm run build && node scripts/probe-page.mjs",
     "probe:midi": "npm run build && node scripts/probe-midi.mjs",