moontide-mcp 2.2.0 → 2.4.0

package/dist/catalog.js

@@ -10,7 +10,7 @@ import path from 'node:path';
 import { z } from 'zod';
 import { drumMapById, kitDrumMap, unknownMapReason } from './drum-maps.js';
 import { renameWithRetry } from './history.js';
-import { MAX_RIG_CATALOG_KITS, MAX_RIG_CATALOG_SOUNDS, MAX_RIG_PROBLEMS } from './protocol.js';
+import { MAX_RIG_CATALOG_KITS, MAX_RIG_CATALOG_SOUNDS, MAX_RIG_ENGINES, MAX_RIG_PROBLEMS } from './protocol.js';
 import { CONTROL_CHARS, cleanProblemText, dataByteSchema, errnoCode, idSchema, modelIdSchema, parseJsonText, problemsFromZod, soundKey, } from './rig-util.js';
 export const CATALOGS_DIR_NAME = 'catalogs';
 export const MAX_CATALOG_SOUNDS = MAX_RIG_CATALOG_SOUNDS;
@@ -28,14 +28,73 @@ const catalogSoundSchema = z.strictObject({
 });
 /** A drum kit of a catalog: a sound that also may name its drum map (null: no map is known for the kit). */
 const catalogKitSchema = catalogSoundSchema.extend({ noteMap: idSchema.nullable().optional() });
-/** A catalog file: the model it extends (equal to the file name), where the list came from, the sounds and the drum kits. */
+/** The banks whose tones belong to one engine of the model; a bank is the exact MSB and LSB pair a sound is sent with. */
+const catalogEngineSchema = z.strictObject({
+    engine: idSchema,
+    banks: z.array(z.strictObject({ msb: dataByteSchema, lsb: dataByteSchema.optional() })).min(1, 'at least one bank is required').max(128, 'at most 128 banks'),
+});
+/** A catalog file: the model it extends (equal to the file name), where the list came from, the engine table, the sounds and the drum kits. */
 export const catalogSchema = z.strictObject({
     model: modelIdSchema,
     source: z.string().min(1, 'must not be empty').max(200, 'at most 200 characters'),
+    // Optional, so earlier catalogs stay valid: which engine of the model each bank of melodic tones belongs to.
+    engines: z.array(catalogEngineSchema).max(MAX_RIG_ENGINES, 'at most 16 engines').optional(),
     // At least one sound or one kit is required: catalogProblems checks that, with the words of a catalog without sounds.
     sounds: z.array(catalogSoundSchema).max(MAX_CATALOG_SOUNDS, 'at most 5000 sounds'),
     kits: z.array(catalogKitSchema).max(MAX_CATALOG_KITS, 'at most 512 kits').optional(),
 });
+/**
+ * The bank as the instrument gets it: an absent bank is 0/0 and an absent LSB is 0, as the sender in
+ * page/midi-out.js sends it, so `97` and `97/0` are one bank. A model that takes an MSB only never has an LSB here
+ * (a catalog with one is refused), so the key needs no bank select.
+ */
+function bankKey(bank) {
+    return `${bank?.msb ?? 0}/${bank?.lsb ?? 0}`;
+}
+/** `97/64`, or `97` where the bank has no LSB. */
+function bankText(bank) {
+    return bank.lsb === undefined ? String(bank.msb) : `${bank.msb}/${bank.lsb}`;
+}
+/**
+ * The checks of the engine table against the model: the model declares engines and has a bank select, each
+ * engine is declared and listed once, each bank is in one engine only and fits the model's bank select.
+ */
+function engineProblems(catalog, model, add) {
+    if (catalog.engines === undefined)
+        return;
+    const declared = model.settings?.engines;
+    if (declared === undefined) {
+        add('engines', 'the model declares no engines');
+        return;
+    }
+    if (model.bankSelect === 'none') {
+        add('engines', 'this model has no bank select');
+        return;
+    }
+    const firstEngine = new Map();
+    const firstBank = new Map();
+    catalog.engines.forEach((entry, index) => {
+        if (!declared.some((engine) => engine.id === entry.engine)) {
+            add(`engines[${index}].engine`, `unknown engine "${entry.engine}", engines of model ${model.id}: ${declared.map((engine) => engine.id).join(', ')}`);
+        }
+        const earlier = firstEngine.get(entry.engine);
+        if (earlier === undefined)
+            firstEngine.set(entry.engine, index);
+        else
+            add(`engines[${index}].engine`, `same engine as engines[${earlier}]`);
+        entry.banks.forEach((bank, position) => {
+            const at = `engines[${index}].banks[${position}]`;
+            if (model.bankSelect === 'msb' && bank.lsb !== undefined)
+                add(`${at}.lsb`, 'this model takes a bank MSB only');
+            const key = bankKey(bank);
+            const seen = firstBank.get(key);
+            if (seen === undefined)
+                firstBank.set(key, index);
+            else
+                add(at, `bank ${bankText(bank)} is also in engines[${seen}]`);
+        });
+    });
+}
 /** The checks that need more than one field, or the model; the shape is already valid. Paths are bare (no file prefix). */
 function catalogProblems(catalog, model, file) {
     const problems = [];
@@ -53,6 +112,7 @@ function catalogProblems(catalog, model, file) {
     const kits = catalog.kits ?? [];
     if (catalog.sounds.length === 0 && kits.length === 0)
         add('sounds', 'at least one sound is required');
+    engineProblems(catalog, model, add);
     // Sounds are melodic, so only the model's melodic names are taken; kits are checked below against its rhythm names.
     const modelKeys = new Map(model.sounds.melodic.map((own) => [soundKey(own.name), own.name]));
     const firstByKey = new Map();
@@ -113,6 +173,33 @@ function catalogProblems(catalog, model, file) {
     });
     return problems;
 }
+/**
+ * The engine whose banks hold this bank as the instrument gets it (see bankKey: no bank is 0/0, no LSB is 0),
+ * or null when there is no catalog, no engine table, or no engine holds the bank.
+ */
+export function engineOf(catalog, bank) {
+    if (catalog === null || catalog === undefined || catalog.engines === undefined)
+        return null;
+    const key = bankKey(bank);
+    const found = catalog.engines.find((entry) => entry.banks.some((candidate) => bankKey(candidate) === key));
+    return found === undefined ? null : found.engine;
+}
+/**
+ * What a reply says of the engine of a melodic sound: `engine "<name>"` when the catalog places the bank in one, `in no
+ * engine` when it places it in none (also when there is no catalog or no engine table, since the page then knows no
+ * engine for the sound), and null (say nothing) for a model that declares no engines. The name is the model's, quoted
+ * like a port name.
+ */
+export function engineClause(catalog, model, bank) {
+    const declared = model.settings?.engines;
+    if (declared === undefined)
+        return null;
+    const id = engineOf(catalog, bank);
+    if (id === null)
+        return 'in no engine';
+    const engine = declared.find((entry) => entry.id === id);
+    return engine === undefined ? 'in no engine' : `engine ${quote(engine.name)}`;
+}
 /**
  * Checks a catalog value against the model it extends: the shape with its limits, then the
  * cross-checks. `file` names the catalog file for the problems (`catalogs/<id>.json:<path>`).
@@ -245,12 +332,12 @@ export function categoriesSentence(catalog, prefix) {
     const counts = categoryCounts(catalog);
     return counts.length === 0 ? 'The catalog has no categories.' : `${prefix}${categoryList(counts, 30)}.`;
 }
-/** A match line: facts only, in the order name, program, bank, category; a drum kit is marked and ends with its drum map. */
-function matchLine(sound, kit) {
+/** A match line: facts only, in the order name, program, bank, category, engine; a drum kit is marked and ends with its drum map. */
+function matchLine(sound, kit, engine) {
     const bank = sound.bank === undefined ? '' : `, bank ${sound.bank.lsb === undefined ? sound.bank.msb : `${sound.bank.msb}/${sound.bank.lsb}`}`;
     const category = sound.category === undefined ? '' : `, category ${quote(sound.category)}`;
     if (kit === null)
-        return `- ${quote(sound.name)}: program ${sound.program}${bank}${category}`;
+        return `- ${quote(sound.name)}: program ${sound.program}${bank}${category}${engine === null ? '' : `, ${engine}`}`;
     const use = kitDrumMap(kit.model, sound);
     const map = use.state === 'known' ? `, drum map ${quote(use.map.name)} (${use.map.notes.length} notes)` : ', drum map unknown';
     return `- ${quote(sound.name)} (drum kit): program ${sound.program}${bank}${category}${map}`;
@@ -269,7 +356,10 @@ export function searchReply(options) {
         lines.push('1 match:');
     else
         lines.push(result.total > MAX_SEARCH_RESULTS ? `${result.total} matches, first ${MAX_SEARCH_RESULTS}:` : `${result.total} matches:`);
-    result.matches.forEach((sound, index) => lines.push(matchLine(sound, result.kits[index] === true ? { model } : null)));
+    result.matches.forEach((sound, index) => {
+        const isKit = result.kits[index] === true;
+        lines.push(matchLine(sound, isKit ? { model } : null, isKit ? null : engineClause(catalog, model, sound.bank)));
+    });
     if (result.total > MAX_SEARCH_RESULTS)
         lines.push(`${result.total - MAX_SEARCH_RESULTS} more, refine your search.`);
     if (result.matches.some((sound) => /['\\]/.test(sound.name))) {
@@ -286,7 +376,8 @@ export class CatalogSaveError extends Error {
     }
 }
 /**
- * The text of a catalog file: the model and source lines, then one sound per line (about 420 KB for
+ * The text of a catalog file: the model and source lines, then the engine table when there is one (one engine
+ * per line), then one sound per line (about 420 KB for
  * 5,000 sounds, where indented JSON is nearly twice that), then the kits list when there are kits,
  * ending with a newline.
  */
@@ -294,7 +385,8 @@ export function catalogFileText(catalog) {
     const list = (items) => `[\n${items.map((item) => `  ${JSON.stringify(item)}`).join(',\n')}\n  ]`;
     const sounds = catalog.sounds.length === 0 ? '[]' : list(catalog.sounds);
     const kits = catalog.kits === undefined || catalog.kits.length === 0 ? '' : `,\n  "kits": ${list(catalog.kits)}`;
-    return `{\n  "model": ${JSON.stringify(catalog.model)},\n  "source": ${JSON.stringify(catalog.source)},\n  "sounds": ${sounds}${kits}\n}\n`;
+    const engines = catalog.engines === undefined || catalog.engines.length === 0 ? '' : `,\n  "engines": ${list(catalog.engines)}`;
+    return `{\n  "model": ${JSON.stringify(catalog.model)},\n  "source": ${JSON.stringify(catalog.source)}${engines},\n  "sounds": ${sounds}${kits}\n}\n`;
 }
 /**
  * Writes `<data>/catalogs/<model id>.json`: the file is written whole beside its name and renamed over
@@ -396,6 +488,21 @@ function summaryLine(label, sound) {
     parts.push(`program ${sound.program} as sent, ${sound.program + 1} in a manual numbered from 1`);
     return `${label}: ${quote(sound.name)} (${parts.join(', ')}).`;
 }
+/** `Engines: <id> (N banks, M sounds), ...; in no engine: K sounds.`, singular for one; kits are not counted. */
+function engineSummaryLine(catalog) {
+    const count = (n, noun) => `${n} ${noun}${n === 1 ? '' : 's'}`;
+    const sounds = new Map();
+    let loose = 0;
+    for (const sound of catalog.sounds) {
+        const engine = engineOf(catalog, sound.bank);
+        if (engine === null)
+            loose++;
+        else
+            sounds.set(engine, (sounds.get(engine) ?? 0) + 1);
+    }
+    const parts = (catalog.engines ?? []).map((entry) => `${entry.engine} (${count(entry.banks.length, 'bank')}, ${count(sounds.get(entry.engine) ?? 0, 'sound')})`);
+    return `Engines: ${parts.join(', ')}; in no engine: ${count(loose, 'sound')}.`;
+}
 /**
  * The summary the user is shown before a catalog drafted from a sound list is saved, one fact per line:
  * the model and the source, how the list numbers programs, the categories with counts, the bank select
@@ -419,9 +526,11 @@ export function summarizeCatalog(options) {
         lines.push('Bank select: none.');
     }
     else {
-        const banks = new Set([...sounds, ...kits].map((sound) => `${sound.bank?.msb ?? 0}/${sound.bank?.lsb ?? 0}`)).size;
+        const banks = new Set([...sounds, ...kits].map((sound) => bankKey(sound.bank))).size;
         lines.push(`Bank select: ${model.bankSelect === 'msb' ? 'CC0' : 'CC0 then CC32'}; ${banks} ${banks === 1 ? 'bank' : 'banks'}.`);
     }
+    if (catalog.engines !== undefined && catalog.engines.length > 0)
+        lines.push(engineSummaryLine(catalog));
     if (total >= 1)
         lines.push(summaryLine('First', sounds[0]));
     if (total >= 3)

package/dist/instruments.js

@@ -10,12 +10,13 @@ import { mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { z } from 'zod';
-import { catalogLine, categoriesSentence, readCatalogFile, searchCatalog, searchReply } from './catalog.js';
+import { catalogLine, categoriesSentence, engineClause, engineOf, readCatalogFile, searchCatalog, searchReply } from './catalog.js';
 import { MAX_DRUM_MAPS, drumMapById, drumMapSchema, kitDrumMap, mapsToSend, unknownMapReason, BUILT_IN_DRUM_MAPS, } from './drum-maps.js';
 import { renameWithRetry } from './history.js';
 import { cleanMidiName, quoteMidiName } from './midi-state.js';
-import { MAX_MIDI_NAME_LENGTH, MAX_RIG_INSTRUMENTS, MAX_RIG_PROBLEMS, MAX_RIG_SOUNDS, } from './protocol.js';
+import { MAX_MIDI_NAME_LENGTH, MAX_RIG_INPUTS, MAX_RIG_INSTRUMENTS, MAX_RIG_PROBLEMS, MAX_RIG_SOUNDS, } from './protocol.js';
 import { CONTROL_CHARS, MAX_RIG_FILE_BYTES, RIG_FILE_NAME, RIG_STATE_FILE_NAME, cleanProblemText, dataByteSchema, errnoCode, idSchema, modelIdSchema, parseJsonText, problemsFromZod, soundKey, } from './rig-util.js';
+import { settingsMessage, settingsProblems, settingsSchema, settingsSummary } from './vocabulary.js';
 // The helpers other modules and tests already read from here live in src/rig-util.ts.
 export { MAX_RIG_FILE_BYTES, RIG_FILE_NAME, RIG_STATE_FILE_NAME, problemsFromZod, soundKey } from './rig-util.js';
 export const MODELS_DIR_NAME = 'models';
@@ -93,12 +94,18 @@ export const modelSchema = z.strictObject({
     notes: z.array(z.string().min(1).max(240)).max(10),
     // Whether the instrument follows MIDI clock. Optional, so a model saved before the field existed still loads.
     clock: z.boolean().optional(),
+    // Whether the instrument plays one note at a time, so a chord is heard as one note. Optional: absent means unknown (never polyphonic),
+    // and a model saved before the field existed still loads.
+    monophonic: z.boolean().optional(),
     // Whether the rhythm channels choose a kit by bank select and program. Optional, absent means off, so every earlier model loads unchanged.
     rhythmBank: z.boolean().optional(),
     // Which note plays which drum. The maps of the model, the id of the map its kits take unless they name
     // another, both optional, so every earlier model loads unchanged. The General MIDI map is built in.
     drumMaps: z.array(drumMapSchema).max(MAX_DRUM_MAPS).optional(),
     drumMap: idSchema.optional(),
+    // Which tone, part and scene settings the instrument has and the message each becomes. Optional, absent means
+    // none, so every earlier model loads unchanged.
+    settings: settingsSchema.optional(),
 });
 /** The setup file: one entry per instrument the user plays. */
 export const rigFileSchema = z.strictObject({
@@ -113,6 +120,14 @@ export const rigFileSchema = z.strictObject({
     }))
         .min(1, 'at least one instrument is required')
         .max(MAX_RIG_INSTRUMENTS, 'at most 16 instruments'),
+    // The MIDI input ports the page listens to, by exact full name. Optional: absent means no input. An entry has
+    // the shape of an instrument's output port, so a refusal names inputs[0].port. The file is never written for this.
+    inputs: z
+        .array(z.strictObject({
+        port: z.string().min(1, 'must not be empty').max(MAX_MIDI_NAME_LENGTH, `at most ${MAX_MIDI_NAME_LENGTH} characters`),
+    }))
+        .max(MAX_RIG_INPUTS, `at most ${MAX_RIG_INPUTS} inputs`)
+        .optional(),
 });
 /** The state file: the instruments the user switched off in the page, by id. A missing file means none. */
 export const rigStateSchema = z.strictObject({
@@ -298,6 +313,9 @@ function modelProblems(model) {
                 checkSevenBit(bytes, 0, bytes.length, `${at}.${name}`, problems);
         }
     });
+    for (const problem of settingsProblems(model.settings)) {
+        add(problem.field === '' ? 'settings' : `settings.${problem.field}`, problem.reason);
+    }
     return problems;
 }
 /**
@@ -561,13 +579,23 @@ export class RigStore {
                 }
                 instruments.push({ id: entry.id, port: entry.port, model, channels, catalog: catalogs.get(model.id) ?? null, clock: entry.clock ?? model.clock ?? false, enabled: !off.has(entry.id) });
             });
+            // Inputs are matched exactly and in full, so the outputs' part-of-each-other rule does not apply to them, and an input may
+            // carry the name of an output (one device can be both). Only the same port twice is refused.
+            const firstInput = new Map();
+            (parsed.data.inputs ?? []).forEach((input, index) => {
+                const same = firstInput.get(input.port);
+                if (same === undefined)
+                    firstInput.set(input.port, index);
+                else
+                    problems.push({ field: `inputs[${index}].port`, reason: `same port as inputs[${same}]` });
+            });
         }
         if (!state.ok)
             problems.push(...state.problems);
         problems.push(...user.problems);
         if (problems.length > 0)
             return invalid(problems);
-        return { setup: 'valid', instruments };
+        return { setup: 'valid', instruments, inputs: (parsed.success ? parsed.data.inputs ?? [] : []).map((input) => input.port) };
     }
 }
 /**
@@ -666,6 +694,11 @@ export function rigMessage(state) {
         // name like a model name. The category stays on the server. There is no cache: the catalog is read
         // at every use (about 10 ms for 5,000 sounds), and a push goes out only when its JSON changed.
         const catalogSounds = (instrument.catalog?.sounds ?? []).map((sound) => sound.bank === undefined ? { name: sound.name, program: sound.program } : { name: sound.name, program: sound.program, bank: sound.bank });
+        // Each melodic sound tells the page its engine when the catalog places its bank in one (the model's own sounds too).
+        const withEngine = (sound) => {
+            const engine = engineOf(instrument.catalog, sound.bank);
+            return engine === null ? sound : { ...sound, engine };
+        };
         // The catalog kits follow the model's own in the rhythm list, resolved by the same sound option.
         const catalogKits = (instrument.catalog?.kits ?? []).map((kit) => ({
             name: kit.name,
@@ -687,7 +720,7 @@ export function rigMessage(state) {
             reset,
             // The rhythm sounds are copied key by key, so no other key of the model rides along to the page.
             sounds: {
-                melodic: [...model.sounds.melodic, ...catalogSounds],
+                melodic: [...model.sounds.melodic, ...catalogSounds].map(withEngine),
                 rhythm: [
                     ...model.sounds.rhythm.map((sound) => ({
                         name: sound.name,
@@ -706,14 +739,18 @@ export function rigMessage(state) {
             catalogKits: catalogKits.length,
             // The fields the Instruments view's switch and settings editor read.
             enabled: instrument.enabled,
+            // True only when the model states that the instrument plays one note at a time; a model that says nothing sends false.
+            monophonic: model.monophonic === true,
             // Every channel of the model, so the editor can offer them all (the chosen ones are in `channels`).
             modelChannels: [
                 ...model.channels.melodic.map((channel) => ({ channel, role: 'melodic' })),
                 ...model.channels.rhythm.map((channel) => ({ channel, role: 'rhythm' })),
             ].sort((a, b) => a.channel - b.channel),
+            // The settings the model describes, as names and ranges only: nothing about how they are sent.
+            settings: settingsMessage(model.settings),
         };
     });
-    return { type: 'midi-rig', setup: 'valid', instruments };
+    return { type: 'midi-rig', setup: 'valid', instruments, inputs: [...state.inputs] };
 }
 /**
  * Whether a port is connected right now, from the last MIDI facts of the active page: 'unknown' while
@@ -795,6 +832,34 @@ function drumMapLine(instrument) {
 }
 /** The line under an instrument the user switched off in the page (indented in the summary, bare in the single-instrument text). */
 const SWITCHED_OFF_LINE = '  Switched off: the user switched this instrument off in the page.';
+/** Setting rows as Claude reads them: each name with its range, in the model's row order; no rows is "none.". */
+function settingNamesText(rows) {
+    return rows.length === 0 ? 'none.' : `${rows.map((row) => `${row.name} ${row.min}-${row.max}`).join(', ')}.`;
+}
+/**
+ * The Settings lines of one instrument: the names and ranges of each level, the tone ones per engine the model
+ * declares. An instrument whose model describes no settings has none, so its reply stays as it was. An engine name
+ * comes from the user's model file and is quoted like a port name.
+ */
+function settingsLines(model) {
+    const { settings } = model;
+    if (settings === undefined)
+        return [];
+    const lines = ['  Settings: the tone, part and scene options of .midi(); the settings topic of get_strudel_reference has their rules.'];
+    const tone = settings.tone ?? [];
+    if (settings.engines === undefined) {
+        lines.push(`    Tone: ${settingNamesText(tone)}`);
+    }
+    else {
+        for (const engine of settings.engines) {
+            lines.push(`    Tone, for a sound of engine ${quotePort(engine.name)}: ${settingNamesText(tone.filter((row) => row.engines?.includes(engine.id) === true))}`);
+        }
+        lines.push('    Tone, for a sound in no engine: none.');
+    }
+    lines.push(`    Part, reaches the part its channel plays: ${settingNamesText(settings.part ?? [])}`);
+    lines.push(`    Scene, reaches every part of the instrument: ${settingNamesText(settings.scene ?? [])}`);
+    return lines;
+}
 /** The summary Claude reads without an argument: each instrument of the setup file, as facts. */
 export function describeRig(state, options) {
     if (state.setup !== 'valid')
@@ -838,9 +903,13 @@ export function describeRig(state, options) {
         lines.push(instrument.clock
             ? '  Clock: follows MIDI clock; Moontide sends the clock, Start and Stop while the playing code names this instrument.'
             : '  Clock: none.');
+        // Only a model that states it: nothing is said about an instrument whose model is silent on it.
+        if (model.monophonic === true)
+            lines.push('  Notes at once: one; a chord is heard as one note.');
         lines.push(model.controls.length === 0
             ? '  Controls: none.'
             : `  Controls: ${model.controls.map((control) => `${control.id} CC${control.cc} ${control.min}-${control.max} (default ${control.default})`).join(', ')}`);
+        lines.push(...settingsLines(model));
         if (model.notes.length > 0)
             lines.push(`  Notes: ${model.notes.join(' ')}`);
     }
@@ -849,11 +918,11 @@ export function describeRig(state, options) {
         `One instrument's full sound list: get_midi_instruments with instrument set to its id.`);
     return lines.join('\n');
 }
-function soundLine(sound) {
+function soundLine(sound, engine = null) {
     if (sound.bank === undefined)
-        return `${sound.program} ${sound.name}`;
+        return `${sound.program} ${sound.name}${engine === null ? '' : ` (${engine})`}`;
     const bank = sound.bank.lsb === undefined ? `${sound.bank.msb}` : `${sound.bank.msb}/${sound.bank.lsb}`;
-    return `${sound.program} ${sound.name} (bank ${bank})`;
+    return `${sound.program} ${sound.name} (bank ${bank}${engine === null ? '' : `, ${engine}`})`;
 }
 /** A drum map as Claude reads it: its name, its count, what it is for when it is not the whole model's, and its notes in note order. */
 function mapListLine(map, scope) {
@@ -906,8 +975,9 @@ export function describeInstrument(state, id, options) {
         const sounds = [...instrument.model.sounds[role]].sort((a, b) => a.program - b.program || (a.bank?.msb ?? -1) - (b.bank?.msb ?? -1) || (a.bank?.lsb ?? -1) - (b.bank?.lsb ?? -1));
         if (sounds.length === 0)
             lines.push('no sounds to choose.');
+        // A drum kit never carries an engine; a melodic sound of a model that declares engines does.
         for (const sound of sounds)
-            lines.push(soundLine(sound));
+            lines.push(soundLine(sound, role === 'melodic' ? engineClause(instrument.catalog, instrument.model, sound.bank) : null));
     }
     if (instrument.channels.some((entry) => entry.role === 'rhythm'))
         lines.push('', ...drumMapLines(instrument.model, instrument.catalog?.kits ?? []));
@@ -1003,6 +1073,10 @@ export function summarizeDraft(model) {
         lines.push(`Reset when it connects: ${messages}, then a ${model.reset.waitMs} ms wait.`);
     }
     lines.push(model.clock === true ? 'Clock: follows MIDI clock.' : 'Clock: none.');
+    if (model.monophonic === true)
+        lines.push('Notes at once: one.');
+    if (model.settings !== undefined)
+        lines.push(...settingsSummary(model.settings));
     if (model.notes.length > 0) {
         lines.push('Notes:');
         for (const note of model.notes)

package/dist/mcp.js

@@ -779,7 +779,7 @@ export function createMcpServer(options) {
         }
     });
     server.registerTool('get_midi_instruments', {
-        description: "When the user has described their instruments, call this before writing MIDI code. Lists the MIDI instruments the user described in instruments.json, as facts: for each one its id, model, exact port name, whether it is connected right now, its channels and their roles, how many sounds it has, its bank select, its reset, whether it follows MIDI clock and its controls. Pass instrument (an id from that list) to get that instrument's full sound list, with the program number sent for each sound and its bank when it has one. A sound is chosen in the code with the sound option of .midi(). An instrument with a sound catalog shows how many sounds the catalog holds and its categories; search_midi_sounds finds them. For an instrument with a rhythm channel it says how a kit goes out and which drum map applies; with instrument set it lists each drum map as note numbers and drum names, a kit's own map only when it differs from the model's, and says when a kit has no known map. Drum notes are written as note numbers in the code. It also says which instruments the user switched off in the page: their notes are silent, and .midi() code newly aimed at them is refused until the user switches them on.",
+        description: "When the user has described their instruments, call this before writing MIDI code. Lists the MIDI instruments the user described in instruments.json, as facts: for each one its id, model, exact port name, whether it is connected right now, its channels and their roles, how many sounds it has, its bank select, its reset, whether it follows MIDI clock and its controls. Pass instrument (an id from that list) to get that instrument's full sound list, with the program number sent for each sound and its bank when it has one. A sound is chosen in the code with the sound option of .midi(). An instrument with a sound catalog shows how many sounds the catalog holds and its categories; search_midi_sounds finds them. For an instrument whose model describes settings it lists the tone, part and scene setting names with their ranges, the tone ones per engine, and the settings topic of get_strudel_reference has their rules; with instrument set it gives the engine of each sound the catalog places in one. For an instrument with a rhythm channel it says how a kit goes out and which drum map applies; with instrument set it lists each drum map as note numbers and drum names, a kit's own map only when it differs from the model's, and says when a kit has no known map. Drum notes are written as note numbers in the code. It also says which instruments the user switched off in the page: their notes are silent, and .midi() code newly aimed at them is refused until the user switches them on.",
         annotations: { readOnlyHint: true },
         inputSchema: {
             instrument: z.string().min(1).max(32).optional().describe('An instrument id from instruments.json, to list its sounds'),
@@ -798,7 +798,7 @@ export function createMcpServer(options) {
         }
     });
     server.registerTool('search_midi_sounds', {
-        description: "Searches the sound catalog of one instrument: a list of the model's sounds kept in the user's data folder, built from a patch-name file or a sound list the user owns. It finds sounds by words in the name or the category, in any order, with case and spaces ignored. It returns at most 25 matches: the exact name first, then names that start with the words, then names that contain them, then matches in the category only. Each match gives the name as the sound option of .midi() takes it, the program as sent (0-127), the bank when there is one and the category. It says how many more matched. A drum kit is marked (drum kit) and gives its drum map, or says the map is unknown.",
+        description: "Searches the sound catalog of one instrument: a list of the model's sounds kept in the user's data folder, built from a patch-name file or a sound list the user owns. It finds sounds by words in the name or the category, in any order, with case and spaces ignored. It returns at most 25 matches: the exact name first, then names that start with the words, then names that contain them, then matches in the category only. Each match gives the name as the sound option of .midi() takes it, the program as sent (0-127), the bank when there is one, the category and, for an instrument whose model declares engines, the engine of the sound or that it is in no engine. It says how many more matched. A drum kit is marked (drum kit) and gives its drum map, or says the map is unknown.",
         annotations: { readOnlyHint: true },
         inputSchema: {
             instrument: z.string().min(1).max(32).describe('An instrument id from instruments.json whose model has a sound catalog'),
@@ -819,7 +819,7 @@ export function createMcpServer(options) {
         }
     });
     server.registerTool('save_midi_model', {
-        description: "Saves an instrument model that you drafted from a page of the instrument's manual the user pasted, into the user's Moontide data folder (models/<id>.json), never into Moontide itself. First call it with confirmed: false: it checks the model and returns a summary (channels, sounds with their program numbers as sent and as numbered in a manual from 1, controls, reset bytes, notes) and saves nothing. Show that summary to the user, and call it again with the same model and confirmed: true only after they say yes. It refuses an id of a model Moontide ships, and an existing model unless overwrite is true. Fields: id (lowercase letters, digits, dashes or underscores, at most 32), name, channels { melodic, rhythm } (lists of channels 1-16), bankSelect (none, msb or msb-lsb), rhythmBank (optional: true when the instrument chooses drum kits by bank select and program change; every rhythm sound then needs a bank), drumMaps (optional, at most 8: [{ id, name, notes: [{ note 0-127, name }] }] typed from the instrument's manual), drumMap (optional: the id of the map of kits without their own; general-midi is built in), a rhythm sound's noteMap (optional: a map id, or null when no map is known for that kit), defaultVolume (0-127), clock (optional: true when the instrument follows MIDI clock, so Moontide sends it the clock, Start and Stop), reset (optional: sysex with at most 4 messages, each { kind: roland-dt1, model, address, data } as hex bytes or { kind: raw, bytes } from F0 to F7 and at most 32 bytes, and waitMs), controls ([{ id, name, cc, min, max, default }]), sounds { melodic, rhythm } ([{ name, program 0-127 as sent, bank { msb, lsb } when the instrument needs one }]) and notes (facts about the instrument, at most 10).",
+        description: "Saves an instrument model that you drafted from a page of the instrument's manual the user pasted, into the user's Moontide data folder (models/<id>.json), never into Moontide itself. First call it with confirmed: false: it checks the model and returns a summary (channels, sounds with their program numbers as sent and as numbered in a manual from 1, controls, reset bytes, notes) and saves nothing. Show that summary to the user, and call it again with the same model and confirmed: true only after they say yes. It refuses an id of a model Moontide ships, and an existing model unless overwrite is true. Fields: id (lowercase letters, digits, dashes or underscores, at most 32), name, channels { melodic, rhythm } (lists of channels 1-16), bankSelect (none, msb or msb-lsb), rhythmBank (optional: true when the instrument chooses drum kits by bank select and program change; every rhythm sound then needs a bank), drumMaps (optional, at most 8: [{ id, name, notes: [{ note 0-127, name }] }] typed from the instrument's manual), drumMap (optional: the id of the map of kits without their own; general-midi is built in), a rhythm sound's noteMap (optional: a map id, or null when no map is known for that kit), defaultVolume (0-127), clock (optional: true when the instrument follows MIDI clock, so Moontide sends it the clock, Start and Stop), monophonic (optional: true when the instrument plays one note at a time), reset (optional: sysex with at most 4 messages, each { kind: roland-dt1, model, address, data } as hex bytes or { kind: raw, bytes } from F0 to F7 and at most 32 bytes, and waitMs), controls ([{ id, name, cc, min, max, default }]), sounds { melodic, rhythm } ([{ name, program 0-127 as sent, bank { msb, lsb } when the instrument needs one }]) and notes (facts about the instrument, at most 10).",
         inputSchema: {
             model: z.record(z.string(), z.unknown()).describe('The drafted model, as a JSON object'),
             confirmed: z.boolean().describe('false to check and summarize without saving; true only after the user said yes to the summary'),

package/dist/midi-state.js

@@ -104,6 +104,21 @@ export function midiFailedLine(failure) {
     const reason = failure === null ? '' : ` (${quoteMidiName(failure)})`;
     return `MIDI: Web MIDI could not start${reason}, so tracks using .midi() are silent. Other tracks keep playing.`;
 }
+/** Setting names joined by ', ': the schema holds each to a letter and then letters and digits, and cleaning keeps it so. */
+function settingNameList(names) {
+    return names.map(cleanMidiName).join(', ');
+}
+/** The words of each reason the memory guard gives (src/protocol.ts lists them). */
+const GUARD_REASON_WORDS = {
+    'not-bytes': 'it is not a list of numbers, so it cannot be checked',
+    'too-long': 'it is too long to be checked',
+    incomplete: 'it is not a complete system exclusive message',
+    'not-data-set': 'it is not a Roland data set (command 12) for the model of the instrument',
+    'unknown-areas': 'Moontide does not know which addresses of this instrument are temporary',
+    outside: 'it would write outside the temporary scene and tones',
+    checksum: 'its checksum does not match',
+    nrpn: 'it is not one of the NRPN part offsets Moontide knows for this instrument',
+};
 /**
  * The line of one event the page sent: a reset of an instrument, a sound change that may
  * cut a note, a sound kept after a failed evaluation, a send that failed, and clock or transport the
@@ -129,9 +144,36 @@ export function midiEventLine(event) {
         }
         case 'send-failed': {
             const id = quoteMidiName(event.instrument);
-            const what = event.what === 'reset' ? 'the reset' : 'the sound setup';
+            const what = event.what === 'reset' ? 'the reset' : event.what === 'settings' ? 'the settings' : 'the sound setup';
             return `MIDI: ${what} could not be sent to instrument ${id} (${quoteMidiName(event.failure)}).`;
         }
+        case 'settings-scene': {
+            const id = quoteMidiName(event.instrument);
+            return `MIDI: the scene settings ${settingNameList(event.names)} of ${id} reach every part of the instrument, not only the channel of their .midi() call.`;
+        }
+        case 'settings-left': {
+            const id = quoteMidiName(event.instrument);
+            const names = settingNameList(event.names);
+            const nothing = 'are no longer in the code that plays. Nothing is sent for them, so the instrument keeps the last value';
+            if (event.level === 'scene')
+                return `MIDI: the scene settings ${names} of ${id} ${nothing} until the instrument itself changes it.`;
+            if (event.level === 'part')
+                return `MIDI: the part settings ${names} of ${id} channel ${event.channel} ${nothing} until the instrument itself changes it.`;
+            return `MIDI: the tone settings ${names} of ${id} channel ${event.channel} ${nothing} until it loads the tone again.`;
+        }
+        case 'sysex-refused': {
+            const id = quoteMidiName(event.instrument);
+            const unread = event.reason === 'not-bytes' || event.reason === 'too-long';
+            const what = event.source === 'reset'
+                ? `the reset of ${id} was`
+                : event.source === 'settings'
+                    ? `the settings for ${id} were`
+                    : `a ${unread ? 'MIDI' : 'system exclusive'} message from the code to ${id} was`;
+            const only = event.reason === 'nrpn'
+                ? 'only Roland data sets into its temporary scene and tones, and the NRPN part offsets it knows.'
+                : 'only Roland data sets into its temporary scene and tones.';
+            return `MIDI: ${what} not sent: ${GUARD_REASON_WORDS[event.reason]}. Moontide sends nothing to an instrument that could write to its memory, ${only}`;
+        }
         case 'clock-dropped':
             return MIDI_CLOCK_DROPPED_LINE;
     }