@map-audio/pam-mcp-server 1.18.1 → 1.21.0

package/dist/server.js

@@ -3,12 +3,14 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
 import { z } from "zod";
+import { buildVariationSnapshotBase } from "./generated/variationSnapshot.js";
 import { readFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { inflateSync } from "node:zlib";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { loadManifest, getParameterIndex, getParametersByCell, getGlobalParameters, findPresetDirs, resolvePresetPath, setActiveProductHint, walkPresets, } from "./manifest.js";
+import { createDrumSynthCatalog, } from "./drumSynth.js";
+import { loadManifest, cellEffectNames, getParameterIndex, getParametersByCell, getGlobalParameters, findPresetDirs, resolvePresetPath, setActiveProductHint, walkPresets, } from "./manifest.js";
 import { PluginBridge } from "./bridge.js";
 import { buildMixMeasurementFromState, currentFlatFromState, parseMixAnalysisPayload, suggestMix, } from "./mixAssist.js";
 import { normalizePresetLookupPath, selectSaveVariationSourcePath, } from "./presetSave.js";
@@ -207,42 +209,93 @@ async function readExistingVariations(presetPath) {
         return Array(PRESET_VARIATION_SLOTS).fill(null);
     }
 }
-// Mirrors interop.ts VARIATION_EXCLUDED_PARAMS (activePresetPath is excluded separately below, matching interop.ts)
+const VARIATION_CONTRACT = (() => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "..", "..", "..", "shared", "variationSessionKeys.json"), // repo checkout
+        resolve(here, "variationSessionKeys.json"), // published dist/
+    ];
+    for (const file of candidates) {
+        if (!existsSync(file))
+            continue;
+        const contract = JSON.parse(readFileSync(file, "utf8"));
+        if (Array.isArray(contract.all) && contract.all.length > 0)
+            return contract;
+    }
+    throw new Error("pam-mcp: variationSessionKeys.json not found. Run `node scripts/generate-variation-session-keys.mjs` " +
+        "(repo) or rebuild the package — saving a variation without it would bake session state into the slot.");
+})();
+// `transport` is live host position, reported in state but never variation content.
 const VARIATION_EXCLUDED_PARAMS = [
-    "variations",
-    "interfaceCache",
-    "songMode",
-    "volume",
-    "hqMode",
-    "previewSamplePath",
-    "previewCellId",
-    "transport",
-    "snapshotRateHz",
-    "looperCrossfade",
-    "looperLength",
-    "looperVolume",
-    "looperFilter",
-    "loopers",
-    "looperPlaybackBars",
-    "looperTrack1Level",
-    "looperTrack2Level",
-    "looperTrack3Level",
-    "looperTrack4Level",
-    "looperTrack5Level",
-    "looperTrack6Level",
-    "looperTrack7Level",
-    "looperTrack8Level",
+    ...new Set([...(VARIATION_CONTRACT.all ?? []), "transport"]),
 ];
 /**
- * Build a variation snapshot string from plugin state (matching interop.ts logic).
+ * Build a variation snapshot string from plugin state.
+ *
+ * The exclusion set comes from the generated contract, so this matches what a
+ * UI save strips. It does NOT match a UI save in one respect: interop.ts awaits
+ * `refreshLoadedPluginStateBlobs()` first and stamps each hosted plugin's
+ * identity and bypass from `pluginHostStore` — data that lives in the WebView,
+ * not in the headless bridge's state. `hostedPluginCells` reports the cells
+ * where that difference bites so callers are told rather than silently handed a
+ * lossy slot.
+ *
+ * This path is the FALLBACK. A PAM build carrying the `getSaveSnapshot` action
+ * hands back the native canonical snapshot (hosted-plugin state included) and
+ * never reaches here.
  */
 function buildVariationString(state) {
-    const stateForVariation = { ...state };
-    for (const param of VARIATION_EXCLUDED_PARAMS) {
-        delete stateForVariation[param];
+    return JSON.stringify(buildVariationSnapshotBase(state, {
+        sessionKeys: VARIATION_EXCLUDED_PARAMS,
+        visualParamIds: VARIATION_CONTRACT.visualParamIds ?? [],
+        lfoGeneratorCount: VARIATION_CONTRACT.lfoGeneratorCount ?? 6,
+    }));
+}
+/**
+ * The canonical save-time state — engine state PLUS every live hosted plugin's
+ * identity, bypass and state blob (PluginProcessor::buildCanonicalSaveSnapshot).
+ *
+ * `getState` returns the live map, which carries no hosted-plugin blob, so a
+ * variation built from it silently dropped the hosted patch (A1). Falls back to
+ * `getState` on a PAM build that predates the action, and reports the fallback
+ * so the save result can say the snapshot is lossy.
+ */
+async function fetchSaveSnapshot() {
+    try {
+        const snap = await bridge.send("getSaveSnapshot");
+        if (snap && typeof snap === "object") {
+            return { state: snap, canonical: true };
+        }
     }
-    delete stateForVariation.activePresetPath;
-    return JSON.stringify(stateForVariation);
+    catch {
+        // Older PAM: action not registered. Fall through.
+    }
+    const state = (await bridge.send("getState"));
+    return { state, canonical: false };
+}
+/** Cells whose hosted plugin this snapshot cannot fully capture. */
+function hostedPluginCells(state) {
+    const cells = new Set();
+    for (const key of Object.keys(state)) {
+        const m = /^cell(\d+)_plugin(?:Fx)?Path$/.exec(key);
+        if (m && state[key])
+            cells.add(Number(m[1]));
+    }
+    return [...cells].sort((a, b) => a - b);
+}
+/** Appended to a save result when the snapshot is known to be lossy. */
+function hostedPluginSaveWarning(state, canonical = false) {
+    // The canonical snapshot stamps hosted-plugin state on the message thread, so
+    // there is nothing to warn about.
+    if (canonical)
+        return "";
+    const cells = hostedPluginCells(state);
+    if (!cells.length)
+        return "";
+    return (`\n\n⚠️  Cell${cells.length > 1 ? "s" : ""} ${cells.join(", ")} host${cells.length > 1 ? "" : "s"} a plugin. ` +
+        "This save captured the plugin's last-known state, not its live one — the bridge cannot refresh a " +
+        "hosted plugin's state blob (that runs in the plugin UI). Re-save from the PAM window to capture " +
+        "current hosted-plugin settings.");
 }
 function formatParam(p) {
     let desc = `${p.paramId}: ${p.displayName}`;
@@ -263,7 +316,14 @@ function formatParam(p) {
     return desc;
 }
 const FULL_STATE_RESPONSE_LIMIT_CHARS = 24_000;
-const CELL_EFFECTS = ["filter", "delay", "crusher", "flanger", "eq", "fdn", "gate", "compressor"];
+// Cell effects are derived per product from the manifest (`cellEffectNames`) —
+// this constant is only the fallback for a manifest that failed to load. The
+// hardcoded eight it used to be is why get_design_overview under-reported:
+// limiter, qverb, eq8, panner, gain, vocoder (and MFX's wavefold/resonator)
+// were enabled in state but absent from `enabledEffects`.
+const CELL_EFFECTS_FALLBACK = [
+    "filter", "delay", "crusher", "flanger", "eq", "fdn", "gate", "compressor",
+];
 const PATTERN_LANES = {
     note: "midiSequence",
     pitch: "pitchSequence",
@@ -480,7 +540,8 @@ const server = new McpServer({
         "paths from list_samples. Transport must be playing for sequencer output. " +
         "To enable experimental features (plugin host, AI engines) call update_settings with both " +
         "experimentalMode:true AND the specific sub-flag (e.g. experimentalPluginHost:true). " +
-        "The drum synth is a standard feature (PAM ≥ 1.5) — no settings flag needed. " +
+        "The standard Drum Synth UI follows drumSynthEnabled (default true); this preference does not mute synth audio. " +
+        "set_mfx_routing is the MFX cable patchbay and errors on PAM/Cell1; set_audio_device is standalone-only. " +
         "Tools added in server version 1.7.0 — update_settings, configure_transport, " +
         "get_audio_device_setup, set_midi_io, set_midi_mapping, delete_preset, " +
         "set_preset_factory_status, get_sample_usage, repair_preset_samples, preview_sample, " +
@@ -644,6 +705,8 @@ const TOOL_ANNOTATIONS = {
     export_audio: W,
     // Settings / devices
     update_settings: WI,
+    set_audio_device: WI,
+    set_mfx_routing: WI,
     set_midi_io: WI,
     set_midi_mapping: WI,
     // Plugin host
@@ -1132,6 +1195,9 @@ server.registerTool("get_design_overview", {
     ]);
     const state = isRecord(stateRaw) ? stateRaw : {};
     const transport = isRecord(transportRaw) ? transportRaw : {};
+    // Product-aware: MFX carries wavefold/resonator, PAM/Cell1 do not.
+    const derivedEffects = cellEffectNames(manifest);
+    const effectNames = derivedEffects.length ? derivedEffects : CELL_EFFECTS_FALLBACK;
     const manifestCellIds = [...new Set(manifest.parameters
             .map((p) => p.cell)
             .filter((cell) => typeof cell === "string" && /^cell\d+$/.test(cell))
@@ -1162,8 +1228,9 @@ server.registerTool("get_design_overview", {
                 name: stemName(samplePath),
                 path: typeof samplePath === "string" ? samplePath : undefined,
             },
-            synthEngine: state[`${prefix}synthEngine`] ?? 0,
-            enabledEffects: CELL_EFFECTS.filter((effectName) => state[`${prefix}${effectName}Enabled`] === 1 || state[`${prefix}${effectName}Enabled`] === true),
+            // Both halves: the enum an agent writes back, and the name it reasons about.
+            synthEngine: describeSynthEngine(state[`${prefix}synthEngine`]),
+            enabledEffects: effectNames.filter((effectName) => state[`${prefix}${effectName}Enabled`] === 1 || state[`${prefix}${effectName}Enabled`] === true),
             patternEvents: Object.fromEntries(Object.entries(PATTERN_LANES).map(([lane, suffix]) => [
                 lane,
                 countEvents(state[`${prefix}${suffix}`]),
@@ -1653,11 +1720,11 @@ server.registerTool("add_modulation", {
             .boolean()
             .optional()
             .describe("Envelope only: route from the cell's pitch-tracked source instead of amp. " +
-            "false (default) = AMP; true & pitchDuck=false = BOOST; true & pitchDuck=true = DUCK."),
+            "false (default) = AMP; true & pitchDuck=false = PITCH (comb); true & pitchDuck=true = DUCK."),
         pitchDuck: z
             .boolean()
             .optional()
-            .describe("Envelope only: when pitch=true, switch from BOOST to DUCK semantics (notch). Ignored if pitch=false."),
+            .describe("Envelope only: when pitch=true, switch from PITCH (comb) to DUCK semantics (notch). Ignored if pitch=false."),
     },
 }, async ({ type, paramId, cellId, lfoIndex, strength, bipolar, pitch, pitchDuck }) => {
     const index = await getParameterIndex();
@@ -2103,7 +2170,7 @@ server.registerTool("save_preset", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const state = (await bridge.send("getState"));
+    const { state, canonical } = await fetchSaveSnapshot();
     // Bare save (no name): the UI Save button's semantics — overwrite the
     // ACTIVE user preset in place, preserving its on-disk metadata. Mirrors
     // the in-plugin assistant executor (error strings included — the model's
@@ -2168,7 +2235,8 @@ server.registerTool("save_preset", {
     const result = (await bridge.send("savePreset", metadata));
     lastSavedPresetName = name;
     lastSavedPresetPath = result?.path || readPath;
-    return text(`Saved preset: ${name}\nPath: ${result?.path || "(unknown path)"}`);
+    return text(`Saved preset: ${name}\nPath: ${result?.path || "(unknown path)"}` +
+        hostedPluginSaveWarning(state, canonical));
 });
 server.registerTool("save_variation", {
     title: "Save Variation",
@@ -2201,8 +2269,8 @@ server.registerTool("save_variation", {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    // 1. Get current full state and build variation snapshot
-    const state = (await bridge.send("getState"));
+    // 1. Canonical save snapshot (engine + hosted-plugin state), then shape it
+    const { state, canonical } = await fetchSaveSnapshot();
     const variationString = buildVariationString(state);
     // 2. Determine preset name and disk path — needed to read existing variations and metadata
     let presetName = name;
@@ -2267,7 +2335,8 @@ server.registerTool("save_variation", {
     return text(`Saved variation ${index} for "${presetName}"\n` +
         `Path: ${result?.path || "(unknown path)"}\n` +
         `Filled slots: ${variations.filter((v) => v !== null).length}/8` +
-        resultSuffix);
+        resultSuffix +
+        hostedPluginSaveWarning(state, canonical));
 });
 server.registerTool("update_preset_metadata", {
     title: "Update Preset Metadata",
@@ -2896,6 +2965,10 @@ server.registerTool("video_command", {
         "moveLayer{layerId,toIndex}, duplicateLayer{layerId}, renameLayer{layerId,name}, " +
         "setLayerEnabled{layerId,enabled?}, toggleSolo{layerId}, selectLayer{layerId}, " +
         "resetLayer{layerId}, applyLayout{preset}, randomizeLayer{layerId}; " +
+        "setShaderSource{layerId,source} (GLSL fragment for a 'shader' layer; auto-parses " +
+        "'// @param uP_x 0..1 = 0.5 \"Label\"' rows into sliders/bind targets; read " +
+        "layers[].shaderCompile in get_video_state for the compile ok/infoLog and repair), " +
+        "setShaderParam{layerId,paramKey,value}; " +
         "addLayerFx{layerId,fxType,params?,beforeFxId?}, removeLayerFx{layerId,fxId}, " +
         "removeAllLayerFx{layerId}, setLayerFxParam{layerId,fxId,param,value|params}, " +
         "setLayerFxEnabled{layerId,fxId,enabled?}, reorderLayerFx{layerId,fxIds}, " +
@@ -2938,8 +3011,8 @@ server.registerTool("add_video_layer", {
         "update_video_layer and stack FX with add_video_fx.",
     inputSchema: {
         kind: z
-            .enum(["video", "image", "camera", "text", "drawing", "model3d", "adjustment"])
-            .describe("Layer kind."),
+            .enum(["video", "image", "camera", "text", "drawing", "model3d", "shader", "adjustment"])
+            .describe("Layer kind. 'shader' is a user-GLSL fragment layer — write its source with video_command {op:'setShaderSource'}."),
         name: z.string().optional().describe("Display name (auto-generated if omitted)."),
         insertAt: z
             .number()
@@ -3578,7 +3651,8 @@ server.registerTool("reset_patterns", {
 });
 server.registerTool("update_effect_config", {
     title: "Update Effect Config",
-    description: "Toggle cell effects on/off (filter, delay, crusher, flanger, eq, fdn, gate, compressor). " +
+    description: "Toggle cell effects on/off (filter, delay, crusher, flanger, eq, eq8, fdn, gate, compressor, panner, gain, vocoder, limiter, qverb, wavefold, resonator). " +
+        "wavefold and resonator exist on MFX only. " +
         "Uses the lighter KV path that does not rebuild the audio graph. Pass 1 to enable, 0 to disable.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
@@ -3590,6 +3664,20 @@ server.registerTool("update_effect_config", {
         fdnEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
         gateEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
         compressorEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        // The page-2 effects. These ship on PAM/Cell1 too, so leaving them out of the
+        // schema made them unreachable over the bridge even though the handler is
+        // generic (it just builds `cell{N}_{key}`) and the state vars exist in
+        // build.js alongside the eight above.
+        eq8Enabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        pannerEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        gainEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        vocoderEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        limiterEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        qverbEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        // MFX-only page-2 signature effects; harmless no-ops on PAM/Cell1, whose
+        // manifests carry no cellN_wavefoldEnabled / cellN_resonatorEnabled key.
+        wavefoldEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
+        resonatorEnabled: z.union([z.literal(0), z.literal(1)]).optional(),
     },
 }, async ({ cellId, ...config }) => {
     const check = await requireBridge();
@@ -3613,6 +3701,88 @@ server.registerTool("update_effect_config", {
         .join(", ");
     return text(`Updated effect config for cell ${cellId}: ${summary}`);
 });
+// MFX cable patchbay. `mfx_routing` is a non-numeric state variable, so it was
+// unreachable through set_parameters (numbers only) — an agent could shape an MFX
+// cell but never patch one to another, which is the whole product.
+//
+// Validation mirrors parseRoutingEdges (interface/src/dsp/mfxRouting.ts): the
+// plugin re-validates on receipt, so this pass exists to fail loudly here rather
+// than have a typo silently drop a cable.
+const MFX_ROUTING_SOURCE_HINT = "'input', 'sidechain', or 'cellN'. 'output' is a destination only.";
+const MFX_ROUTING_SINK_HINT = "'output' or 'cellN'. 'input'/'sidechain' are sources only.";
+function mfxPortCell(port) {
+    const m = /^cell([1-9]\d*)$/.exec(port); // canonical form only — 'cell01' is not a port
+    return m ? Number(m[1]) : null;
+}
+function validateMfxEdges(edges, maxCells) {
+    const seen = new Set();
+    const out = [];
+    const inRange = (port) => {
+        const c = mfxPortCell(port);
+        return c !== null && c >= 1 && c <= maxCells;
+    };
+    for (const { from, to } of edges) {
+        if (from !== "input" && from !== "sidechain" && !inRange(from)) {
+            return { ok: false, reason: `invalid source port '${from}' — expected ${MFX_ROUTING_SOURCE_HINT}` };
+        }
+        if (to !== "output" && !inRange(to)) {
+            return { ok: false, reason: `invalid destination port '${to}' — expected ${MFX_ROUTING_SINK_HINT}` };
+        }
+        const key = `${from}->${to}`;
+        if (seen.has(key))
+            continue; // dedupe, matching the plugin
+        seen.add(key);
+        out.push({ from, to });
+    }
+    return { ok: true, edges: out };
+}
+server.registerTool("set_mfx_routing", {
+    title: "Set MFX Cable Routing",
+    description: "Read or replace the MFX cable patch — the graph that decides which cell feeds which. MFX-only; on PAM/Cell1 " +
+        "this returns a product error.\n\n" +
+        "Ports: 'input' (the host's audio in) and 'sidechain' are sources; 'output' is the destination; 'cellN' is both. " +
+        "A self-edge cellN→cellN is a feedback loop, and input→output is a direct dry path. Duplicate cables are dropped.\n\n" +
+        "A plain serial chain on 4 cells is input→cell1, cell1→cell2, cell2→cell3, cell3→cell4, cell4→output. " +
+        "Parallel is input→each cell plus each cell→output.\n\n" +
+        "'set' REPLACES the whole patch, so send the full cable list. Per-cable levels live in mfx_edge_gains and are " +
+        "left alone; a new cable takes the graph's own default (unity forward, 0.5 on a back or self edge). " +
+        "Re-patching rebuilds the audio graph, like reordering FX.",
+    inputSchema: {
+        op: z.enum(["get", "set"]).describe("'get' reads the current cables; 'set' replaces them."),
+        edges: z
+            .array(z.object({
+            from: z.string().describe(`Source port: ${MFX_ROUTING_SOURCE_HINT}`),
+            to: z.string().describe(`Destination port: ${MFX_ROUTING_SINK_HINT}`),
+        }))
+            .optional()
+            .describe("Full cable list for 'set'. An empty array clears the patch (silence)."),
+    },
+    annotations: { destructiveHint: false, idempotentHint: true },
+}, async ({ op, edges }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const manifest = await loadManifestForProductGuard();
+    if (manifest && !isMfxManifest(manifest)) {
+        return error(`set_mfx_routing is MFX-only. ${manifest.name ?? "This product"} has no cable patchbay — ` +
+            "its cells run in a fixed per-cell chain.");
+    }
+    if (op === "get") {
+        const raw = await bridge.send("getState", "mfx_routing");
+        return json(isRecord(raw) ? raw.mfx_routing ?? raw : raw);
+    }
+    if (!edges)
+        return error("op 'set' requires an `edges` array (pass [] to clear the patch).");
+    const maxCells = manifestMaxCellId(manifest) ?? 4;
+    const validated = validateMfxEdges(edges, maxCells);
+    if (!validated.ok) {
+        return error(`${validated.reason}. This product exposes cells 1..${maxCells}.`);
+    }
+    // mfx_routing is a GRAPH_RENDER state var — a re-patch must rebuild the graph.
+    await applyKv({ mfx_routing: validated.edges }, KV_OPTS_STANDARD);
+    const summary = validated.edges.map((e) => `${e.from}→${e.to}`).join(", ");
+    return text(`MFX routing set: ${validated.edges.length} cable(s)${summary ? ` — ${summary}` : " (patch cleared)"}.`);
+});
 server.registerTool("update_cell_config", {
     title: "Update Cell Config",
     description: "Update cell-level configuration properties like polyphony, MIDI settings, varispeed, and modulation latch. " +
@@ -3640,7 +3810,24 @@ server.registerTool("update_cell_config", {
             .max(2)
             .optional()
             .describe("Slice playback length when sliceKeymapMode=1: 0=Boundary (stop at the next slice edge), 1=Sample End (play to end of sample), 2=Note Off (sustain until key release; requires the cell to be in Gate mode)."),
-        scaleName: z.string().optional().describe("Scale name for pitch sequencer quantization (e.g. 'chromatic', 'major', 'minor')."),
+        scaleName: z
+            .enum([
+            "chromatic",
+            "major",
+            "minor",
+            "pentatonicMajor",
+            "pentatonicMinor",
+            "dorian",
+            "mixolydian",
+            "blues",
+            "harmonicMinor",
+            "phrygian",
+            "lydian",
+            "locrian",
+        ])
+            .optional()
+            .describe("Scale name for pitch sequencer / note quantization ('chromatic' = no filter). " +
+            "An out-of-vocabulary string would silently play as chromatic while junk persists into the preset, so the name is validated."),
         scaleRoot: z.number().min(0).max(11).optional().describe("Root note of the scale (0=C, 1=C#, ..., 11=B)."),
         pitchMode: z.number().int().min(0).max(3).optional().describe("Pitch engine: 0=Varispeed, 1=Formant, 2=Pitch Shift Quantize, 3=Varispeed Quantize."),
         stretchMode: z.number().int().min(0).max(3).optional().describe("Stretch engine: 0=OLA, 1=Cloud, 2=Phase Vocoder, 3=GrainRate."),
@@ -3664,22 +3851,35 @@ server.registerTool("update_cell_config", {
     const cellCheck = validateCellIdForManifest(cellId, manifest);
     if (cellCheck !== true)
         return cellCheck;
-    const cellConfig = {};
-    const flatDelta = {};
-    for (const [key, value] of Object.entries(config)) {
-        if (value !== undefined)
-            cellConfig[key] = value;
-    }
-    if (Object.keys(cellConfig).length === 0) {
+    // These four are DAW params (cell{N}_quantScale, …), not cell-config keys —
+    // nothing consumes them on the cells{} config channel (the sampler reads
+    // the param signal inputs), so a cells{} write was a silent no-op that
+    // also persisted junk keys into the preset. Route them to flat param keys,
+    // which applyKv maps onto the JUCE params (updateParameters: true).
+    const PARAM_ROUTED_KEYS = new Set(["quantScale", "quantRoot", "spread", "chaos"]);
+    const providedKeys = Object.entries(config)
+        .filter(([, value]) => value !== undefined)
+        .map(([key]) => key);
+    if (providedKeys.length === 0) {
         return error("At least one config property must be provided.");
     }
     if (manifest && isMfxManifest(manifest)) {
-        const unsupported = Object.keys(cellConfig).filter((key) => !MFX_CELL_CONFIG_KEYS.has(key));
+        const unsupported = providedKeys.filter((key) => !MFX_CELL_CONFIG_KEYS.has(key));
         if (unsupported.length > 0) {
             return error("update_cell_config in MFX only accepts sidechainFrom. " +
                 `Sampler/MIDI/instrument config keys are PAM/Cell1-only: ${unsupported.join(", ")}.`);
         }
     }
+    const cellConfig = {};
+    const flatDelta = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (value === undefined)
+            continue;
+        if (PARAM_ROUTED_KEYS.has(key))
+            flatDelta[`cell${cellId}_${key}`] = value;
+        else
+            cellConfig[key] = value;
+    }
     // Auto-enable compressor when setting sidechain source
     if (cellConfig.sidechainFrom !== undefined && cellConfig.sidechainFrom !== null) {
         flatDelta[`cell${cellId}_compressorEnabled`] = 1;
@@ -3694,11 +3894,14 @@ server.registerTool("update_cell_config", {
         cellModeChangeSeq[cellId] = next;
         cellConfig.modeChangeSeq = next;
     }
-    const delta = { cells: { [cellId]: cellConfig }, ...flatDelta };
+    const delta = { ...flatDelta };
+    if (Object.keys(cellConfig).length > 0)
+        delta.cells = { [cellId]: cellConfig };
     await applyKv(delta, KV_OPTS_CELL_CONFIG);
-    const summary = Object.entries(cellConfig)
-        .map(([k, v]) => `${k}=${v}`)
-        .join(", ");
+    const summary = [
+        ...Object.entries(cellConfig).map(([k, v]) => `${k}=${v}`),
+        ...Object.entries(flatDelta).map(([k, v]) => `${k}=${v}`),
+    ].join(", ");
     return text(`Updated cell ${cellId} config: ${summary}`);
 });
 server.registerTool("set_cell_mute", {
@@ -3752,7 +3955,8 @@ server.registerTool("set_master_effects", {
         "medium release (80-200ms), ratio 4-8, autoMakeup true. " +
         "For lo-fi/Memphis/dusty glue: tapeEnabled=1, tapeMode=1 (Lo-Fi), masterTapeDrive 0.55-0.7, " +
         "masterTapeTone -0.4..-0.1 (darker), masterTapeWear 0.5-0.7 (wow/flutter). " +
-        "NOTE: the Tape requires a PAM build that ships it (flat state key masterTapeEnabled — master-chain keys are not manifest params). On older builds these keys are ignored.",
+        "Squeeze (masterSqueeze*) is the 3-band up/down density stage between Punch and Tape — for dense modern-electronic masters set masterSqueezeEnabled=1 with masterSqueezeDepth 0.2-0.4; it lifts quiet detail and limits loud bands per band (a character stage, not glue — Punch stays the glue). " +
+        "NOTE: the Tape and Squeeze stages require a PAM build that ships them (flat state keys, not manifest params). On older builds these keys are ignored.",
     inputSchema: {
         compressorEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable Punch compressor (0=off, 1=on)."),
         limiterEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable master Limiter (0=off, 1=on)."),
@@ -3792,6 +3996,15 @@ server.registerTool("set_master_effects", {
         masterIronDrive: z.number().min(0).max(12).optional().describe("Iron drive dB (default 0). Level-compensated — drive adds colour, not loudness."),
         masterIronAmount: z.number().min(0).max(1).optional().describe("Transformer (magnetizing-branch) depth 0..1 — LF-concentrated saturation, the 'iron' signature (default 0.5)."),
         masterIronMode: z.union([z.literal(0), z.literal(1)]).optional().describe("0=Console (amp-forward, subtle), 1=Transformer (heavier LF iron)."),
+        masterSqueezeEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable Squeeze — a 3-band upward+downward compressor (post-Punch, pre-Tape; zero latency). The character (88/2500 Hz splits, thresholds, ratios) is baked; Depth is the main lever."),
+        masterSqueezeDepth: z.number().min(0).max(1).optional().describe("Squeeze depth 0..1 (default 0.3): scales the applied per-band gain toward the full character — a density control, NOT a dry/wet. 0.15-0.3 densifies a master; 0.6+ is the aggressive pumped sound."),
+        masterSqueezeTime: z.number().min(0.1).max(10).optional().describe("Squeeze time multiplier on all band attack+release (0.1 fast .. 10 slow, default 1)."),
+        masterSqueezeTone: z.number().min(-1).max(1).optional().describe("Squeeze tone: bipolar low<->high band tilt, ±6 dB at the extremes (default 0)."),
+        masterSqueezeInGain: z.number().min(-12).max(12).optional().describe("Squeeze input gain dB (default 0) — drives program into the fixed thresholds (more In = more of everything)."),
+        masterSqueezeOutTrim: z.number().min(-12).max(12).optional().describe("Squeeze output trim dB (default 0)."),
+        masterSqueezeUpAmount: z.number().min(0).max(1.5).optional().describe("Squeeze upward-branch trim 0..1.5 (default 1). 0 disables the upward lift (downward-only multiband)."),
+        masterSqueezeDownAmount: z.number().min(0).max(1.5).optional().describe("Squeeze downward-branch trim 0..1.5 (default 1). 0 disables the downward limiting (pure upward lift)."),
+        masterSqueezeUpCapDb: z.number().min(0).max(24).optional().describe("Squeeze upward max-boost clamp dB (default 12) — bounds how far quiet material (tails, noise floor) is lifted."),
         masterLoudnessAutoReset: z.union([z.literal(0), z.literal(1)]).optional().describe("Loudness meter auto-reset on host transport start (default 1). 0 keeps measurements running across transport stops."),
         masterEqBells: z
             .array(z.object({
@@ -3857,38 +4070,50 @@ server.registerTool("set_master_effects", {
     return text(`Updated master effects: ${summary}`);
 });
 // Built-in per-cell drum synth ("machines"). Engine enum index = drumsynth::Engine
-// (Off = 0). Per-engine param labels + musical defaults mirror DRUM_SYNTH_ENGINES
-// in interface/src/dsp/modules/drumSynth.ts — keep in lockstep (append-only).
-const DRUM_SYNTH_ENGINES = [
-    { name: "Kick", params: [["Tune", 0.25], ["Pitch", 0.5], ["P.Decay", 0.35], ["Decay", 0.5], ["Click", 0.3], ["Drive", 0.35], ["Tone", 0.6]] },
-    { name: "Snare", params: [["Tune", 0.4], ["Snap", 0.45], ["Body", 0.35], ["N.Decay", 0.45], ["N.Tone", 0.5], ["Detune", 0.3], ["Drive", 0.25]] },
-    { name: "HiHat", params: [["Tune", 0.5], ["Decay", 0.3], ["Tone", 0.5], ["Metal", 0.6], ["Noise", 0.2]] },
-    { name: "Clap", params: [["Tune", 0.45], ["Spread", 0.4], ["Decay", 0.4], ["Tone", 0.5], ["Drive", 0.2]] },
-    { name: "Tom", params: [["Tune", 0.4], ["Pitch", 0.4], ["Decay", 0.45], ["Tone", 0.55], ["Noise", 0.2], ["Drive", 0.2]] },
-    { name: "FM", params: [["Tune", 0.4], ["Ratio", 0.45], ["FM Amt", 0.4], ["Decay", 0.4], ["FM Dcy", 0.4], ["F.Back", 0.1], ["Drive", 0.2]] },
-    { name: "Cymbal", params: [["Tune", 0.5], ["Decay", 0.5], ["Tone", 0.6], ["Metal", 0.7], ["Sizzle", 0.4]] },
-    { name: "Cowbell", params: [["Tune", 0.5], ["Decay", 0.4], ["Ratio", 0.45], ["Tone", 0.5], ["Drive", 0.2]] },
-    { name: "808", params: [["Tune", 0.35], ["Glide", 0.25], ["P.Decay", 0.4], ["Decay", 0.55], ["Saturate", 0.2], ["Click", 0.25], ["Tone", 0.5]] },
-    { name: "Shaker", params: [["Tune", 0.5], ["Color", 0.3], ["Decay", 0.3], ["Attack", 0.4], ["Rattle", 0.0], ["Tone", 0.4]] },
-    { name: "Rim", params: [["Tune", 0.4], ["Ring", 0.5], ["Decay", 0.3], ["Mode", 0.4], ["Snap", 0.6], ["Drive", 0.2]] },
-    { name: "Conga", params: [["Tune", 0.45], ["Slap", 0.4], ["Decay", 0.4], ["Mode", 0.3], ["Tone", 0.55], ["Skin", 0.25], ["Drive", 0.2]] },
-    { name: "Bell", params: [["Tune", 0.5], ["Ratio", 0.4], ["FM Amt", 0.4], ["Decay", 0.5], ["Inharm", 0.3], ["Strike", 0.3], ["Tone", 0.3]] },
-    { name: "Pluck", params: [["Tune", 0.4], ["Sustain", 0.6], ["Damp", 0.5], ["Excite", 0.4], ["Tone", 0.6], ["Drive", 0.15], ["Decay", 0.5]] },
-    { name: "Zap", params: [["Tune", 0.3], ["Sweep", 0.7], ["S.Time", 0.35], ["Decay", 0.4], ["Timbre", 0.3], ["Noise", 0.1], ["Drive", 0.25], ["Tone", 0.6]] },
-    { name: "Wave", params: [["Tune", 0.35], ["Position", 0.2], ["P.Env", 0.4], ["Decay", 0.4], ["Bright", 0.6], ["Morph", 0.0], ["Drive", 0.2]] },
-    { name: "Chaos", params: [["Tune", 0.4], ["Chaos", 0.6], ["Decay", 0.4], ["Tone", 0.5], ["Drive", 0.3], ["Noise", 0.1]] },
-];
-const DRUM_SYNTH_ENGINE_NAMES = ["Off", ...DRUM_SYNTH_ENGINES.map((e) => e.name)];
+// (Off = 0). The roster, the curated defaults and the engine-switch rule all come
+// from shared/drumSynthEngines.json — the registry build.js codegens the C++ cook
+// and the manifest from, and interface/src/dsp/modules/drumSynth.ts derives its
+// own tables from. The hand-copied table this replaced had drifted on Kick,
+// Cowbell and 808 (issue #999); the switch rule it shipped with carried knob
+// positions where the plugin carries engine units.
+const DRUM_SYNTH_REGISTRY = (() => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        resolve(here, "..", "..", "..", "shared", "drumSynthEngines.json"), // repo checkout
+        resolve(here, "drumSynthEngines.json"), // published dist/
+    ];
+    for (const file of candidates) {
+        if (!existsSync(file))
+            continue;
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (parsed.engines && Object.keys(parsed.engines).length > 0)
+            return parsed;
+    }
+    throw new Error("pam-mcp: drumSynthEngines.json not found. Rebuild the package (scripts/build-postprocess.mjs " +
+        "vendors it into dist/) — seeding a drum engine without it would write defaults that disagree " +
+        "with the plugin.");
+})();
+const drumSynth = createDrumSynthCatalog(DRUM_SYNTH_REGISTRY);
+const DRUM_SYNTH_ENGINE_NAMES = drumSynth.engineNames;
+/** State carries the bare enum; agents reason about the name. Report both. */
+function describeSynthEngine(raw) {
+    const id = Math.round(Number(raw ?? 0));
+    return { id, name: DRUM_SYNTH_ENGINE_NAMES[id] ?? "Off" };
+}
 server.registerTool("set_drum_synth", {
     title: "Set Drum Synth (built-in machine)",
     description: "Select and shape a cell's built-in drum-synth 'machine' — a real-time synthesized voice that sums into the cell " +
-        "alongside (or instead of) its sample. 18 engines: Off, Kick, Snare, HiHat, Clap, Tom, FM, Cymbal, Cowbell, 808, " +
-        "Shaker, Rim, Conga, Bell, Pluck, Zap, Wave, Chaos. The 808 engine is a tuned long-glide sub that plays as a chromatic " +
+        `alongside (or instead of) its sample. ${DRUM_SYNTH_ENGINE_NAMES.length} engines: ${DRUM_SYNTH_ENGINE_NAMES.join(", ")}. ` +
+        "The 808 engine is a tuned long-glide sub that plays as a chromatic " +
         "bassline (drive it with a pitch lane + pitch-quantize) — ideal for 808 sub-bass, trap, Memphis. Use a cell with NO " +
         "sample for a pure synth voice, or layer over a sample. Each engine reinterprets the 8 generic params (p1..p8); pass " +
-        "only the ones you want to nuance — unspecified params seed to the engine's musical default. Per-engine p-labels: " +
-        DRUM_SYNTH_ENGINES.map((e) => `${e.name}=[${e.params.map((p) => p[0]).join(",")}]`).join("; ") + ". " +
-        "NOTE: requires a PAM build with drum synth (manifest.drumSynth.enabled) — a standard PAM feature, no settings flag. " +
+        "only the ones you want to nuance. First activation seeds every slot from the engine's musical defaults. On a switch " +
+        "between two active engines, only slots you had moved off their default travel, and they carry the engine VALUE " +
+        "(re-mapped through the destination's own range), so Kick Decay 0.41 becomes Stab Decay 0.336 — the same 198 ms. " +
+        "Untouched slots, and slots whose label or unit has no counterpart, take the destination's default. Per-engine p-labels: " +
+        drumSynth.engines.map((e) => `${e.name}=[${e.params.map((p) => p.label).join(",")}]`).join("; ") + ". " +
+        "NOTE: requires a PAM build with drum synth (manifest.drumSynth.enabled). This headless tool is product-gated, " +
+        "not gated by the UI-only drumSynthEnabled preference. " +
         "On products without it, this tool returns a product error instead of writing inert synth keys.",
     inputSchema: {
         cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
@@ -3917,14 +4142,11 @@ server.registerTool("set_drum_synth", {
     const engineId = DRUM_SYNTH_ENGINE_NAMES.indexOf(engine);
     if (engineId < 0)
         return error(`Unknown drum synth engine: ${engine}`);
-    const delta = { [`cell${cellId}_synthEngine`]: engineId };
-    if (engineId > 0) {
-        // Seed the engine's musical defaults so the voice sounds good immediately,
-        // then apply explicit p-overrides on top (nuance only what you mean to).
-        const desc = DRUM_SYNTH_ENGINES[engineId - 1];
-        desc.params.forEach(([, def], i) => {
-            delta[`cell${cellId}_synth_p${i + 1}`] = def;
-        });
+    const stateRaw = await bridge.send("getState");
+    const state = isRecord(stateRaw) ? stateRaw : {};
+    const delta = drumSynth.buildEngineSwitchDelta(cellId, engineId, state);
+    const desc = drumSynth.getEngine(engineId);
+    if (desc) {
         for (const [key, value] of Object.entries(overrides)) {
             if (value === undefined)
                 continue;
@@ -3937,7 +4159,7 @@ server.registerTool("set_drum_synth", {
         delta[`cell${cellId}_synthVolume`] = volume;
     // synthEngine is a graph-render key → needs a graph dispatch (KV_OPTS_STANDARD).
     await applyKv(delta, KV_OPTS_STANDARD);
-    const labels = engineId > 0 ? DRUM_SYNTH_ENGINES[engineId - 1].params.map((p) => p[0]).join(",") : "—";
+    const labels = desc ? desc.params.map((p) => p.label).join(",") : "—";
     return text(`Cell ${cellId} drum synth → ${engine}${engineId > 0 ? ` (p1..pN = ${labels})` : ""}.`);
 });
 server.registerTool("set_drum_synth_wave", {
@@ -4482,7 +4704,7 @@ Variations exclude: global volume, looper state.
 
 ## Master Effects — The Final Stage
 
-Signal chain: Cell outputs → Bus Mix → **Punch Compressor** → **Limiter** → Volume Fader → Output
+Signal chain: Cell outputs → Bus Mix → **EQ** → **Punch Compressor** → **Squeeze** (3-band up/down) → **Tape** → **Iron** → **Clipper** → **Limiter** → Volume Fader → Output
 
 ### Punch Compressor (Musical Bus Comp)
 \`\`\`
@@ -4603,7 +4825,8 @@ update_cell_config: cellId=5, scaleName="pentatonicMinor", scaleRoot=0
 \`\`\`
 \`scaleRoot\`: 0=C, 1=C#, 2=D, 3=D#, 4=E, 5=F, 6=F#, 7=G, 8=G#, 9=A, 10=A#, 11=B
 
-Available scales: \`chromatic\` (default/none), \`major\`, \`minor\`, \`pentatonicMajor\`, \`pentatonicMinor\`, \`dorian\`, \`mixolydian\`, \`blues\`, \`harmonicMinor\`, \`phrygian\`
+Available scales: \`chromatic\` (default/none), \`major\`, \`minor\`, \`pentatonicMajor\`, \`pentatonicMinor\`, \`dorian\`, \`mixolydian\`, \`blues\`, \`harmonicMinor\`, \`phrygian\`, \`lydian\`, \`locrian\`
+(The sampler pitch-quantize lane \`cell{N}_quantScale\` is a separate, deliberately frozen 10-scale DAW param — no lydian/locrian there.)
 
 ### Playback Modes
 \`cell{N}_mode\`: 0=Trigger (one-shot), 1=Gate (plays while held, default), 2=Loop (continuous)
@@ -4646,6 +4869,9 @@ Index → multiplier: 0=1/32, 1=1/16, 2=1/12, 3=1/8, 4=1/6, 5=1/5, 6=1/4, 7=1/3,
 // commands in Claude Code). Each stages the same flows the
 // README and tool descriptions teach, with exact tool names.
 // ============================================================
+// Mirror of RANDOMIZER_GENRES (shared/randomizer/types.ts) — the published
+// package can't import repo-relative shared modules, so the copy is pinned by
+// interface/test/randomizerGenre.test.ts (source-text parity check).
 const GENRE_SUGGESTIONS = ["boom_bap", "trap", "drill", "house", "techno", "dnb"];
 const completeGenre = (value) => GENRE_SUGGESTIONS.filter((g) => g.startsWith((value ?? "").toLowerCase()));
 // completable() tags the schema OBJECT with a symbol, so ordering is delicate:
@@ -4833,7 +5059,7 @@ server.registerTool("set_looper_track", {
     if (typeof rest.sourceCell === "number")
         trackDelta.sourceCell = rest.sourceCell;
     if (typeof rest.autoSelect === "boolean")
-        trackDelta.autoSelect = rest.autoSelect ? 1 : 0;
+        trackDelta.autoSelect = rest.autoSelect;
     if (typeof rest.recordedBpm === "number")
         trackDelta.recordedBpm = rest.recordedBpm;
     if (Object.keys(trackDelta).length === 0)
@@ -4914,6 +5140,10 @@ server.registerTool("start_looper_recording", {
     const check = await requireBridge();
     if (check !== true)
         return check;
+    // Arm in UI state too — the plugin's live recording overlay and progress
+    // mount off loopers[id].armed, so a bridge-only record left the timeline
+    // blank while recording ran fine underneath.
+    await applyLoopersDelta(Object.fromEntries(armedCellIds.map((cellId) => [cellId, { armed: 1 }])));
     const meta = trackMetadata ??
         armedCellIds.map((cellId) => ({
             cellId,
@@ -5129,7 +5359,9 @@ server.registerTool("looper_variation_sync", {
 server.registerTool("queue_variation", {
     title: "Queue Variation Switch",
     description: "Schedule a global variation switch on the next bar boundary. " +
-        "For an immediate switch, use load_variation instead.",
+        "For an immediate switch, use load_variation instead. Optionally morph " +
+        "into the new section over the bars before the boundary (song mode / an " +
+        "already-engaged queued-flip window only; a from-idle flip hard-switches).",
     inputSchema: {
         index: z.number().min(0).max(7).describe("Variation slot 0-7."),
         intervalBars: z.number().min(0.125).max(64).describe("Bars before switching."),
@@ -5138,13 +5370,48 @@ server.registerTool("queue_variation", {
             .boolean()
             .default(true)
             .describe("Reset pattern phase on switch."),
+        morphBars: z
+            .number()
+            .min(0.25)
+            .max(8)
+            .optional()
+            .describe("Pre-anchor morph window in bars for this flip (PAM >= 1.19.3). Omit = hard switch."),
+        morphMode: z
+            .enum(["auto", "param", "mix", "seq", "all"])
+            .optional()
+            .describe("Morph style: 'param' glides continuous params (default); 'mix' equal-power blends the two sections; 'seq' adds a staged pattern dissolve to the glide (old notes lose trigger probability as new notes gain it); 'all' runs glide + dissolve + blend together; 'auto' lets the engine pick — mix when the sections differ in graph topology (samples, synth engines, routing) or when nothing can glide, param otherwise (PAM >= 1.19.4; seq/all on older builds run param)."),
+        morphCurve: z
+            .enum(["linear", "ease", "exp", "log"])
+            .optional()
+            .describe("Morph easing; default ease."),
+        transition: z
+            .object({
+            patternPolicy: z.enum(["dissolve", "wipe", "cells"]).optional(),
+            mixLaw: z.enum(["equalPower", "equalGain", "correlation"]).optional(),
+            tail: z.enum(["cut", "fade", "ring"]).optional(),
+            tailMaxBars: z.number().min(0.25).max(8).optional(),
+        })
+            .optional()
+            .describe("Advanced transition settings for this flip (PAM >= 1.20.0): pattern policy for a " +
+            "seq/all morph, blend gain law for a mix/all morph, and the outgoing section's " +
+            "tail. Omitted fields keep the defaults (dissolve, equalPower, fade)."),
     },
-}, async ({ index, intervalBars, fadeMs, resetPhase }) => {
+}, async ({ index, intervalBars, fadeMs, resetPhase, morphBars, morphMode, morphCurve, transition }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    await bridge.send("queueVariationOnBars", { index, intervalBars, fadeMs, resetPhase });
-    return text(`Queued variation ${index} on next ${intervalBars}-bar boundary.`);
+    await bridge.send("queueVariationOnBars", {
+        index,
+        intervalBars,
+        fadeMs,
+        resetPhase,
+        ...(morphBars !== undefined && { morphBars }),
+        ...(morphMode !== undefined && { morphMode }),
+        ...(morphCurve !== undefined && { morphCurve }),
+        ...(transition !== undefined && { transition }),
+    });
+    const morphNote = morphBars !== undefined ? ` (morph ${morphBars} bars, ${morphMode ?? "param"})` : "";
+    return text(`Queued variation ${index} on next ${intervalBars}-bar boundary${morphNote}.`);
 });
 server.registerTool("cancel_queued_variation", {
     title: "Cancel Queued Variation",
@@ -5298,16 +5565,17 @@ server.registerTool("midi_recording", {
 // ============================================================
 server.registerTool("update_modulation", {
     title: "Update Modulation",
-    description: "Apply a delta to a modulation source: LFO, Envelope, Vary, Macro, ParamSeq config, or ParamSeq sequence data. " +
+    description: "Apply a delta to a modulation source: LFO, Envelope, Vary, Macro, ParamSeq config, ParamSeq sequence data, " +
+        "or the Free Sequencer master pattern. " +
         "The payload is type-specific; see modulation update flows in interop.ts (applyLfoUpdate / updateEnvelope / etc.). " +
         "Use add_modulation to first attach a source to a target — then this tool to edit it.",
     inputSchema: {
         type: z
-            .enum(["lfo", "envelope", "vary", "macro", "paramSeq", "paramSeqSequence"])
+            .enum(["lfo", "envelope", "vary", "macro", "paramSeq", "paramSeqSequence", "freeSeqSequence"])
             .describe("Which modulation system to update."),
         payload: z
             .record(z.string(), z.unknown())
-            .describe("Update payload object. Shape depends on type: lfo expects { index, rate?, depth?, shape?, customCurve?, target? }, envelope expects matrix entry edits, paramSeqSequence expects { id, steps[] }, etc."),
+            .describe("Update payload object. Shape depends on type: lfo expects { index, rate?, depth?, shape?, customCurve?, target? }, envelope expects matrix entry edits, paramSeqSequence expects { id, steps[] }, freeSeqSequence expects { sequence: number[] } (the master step contour every free-mode ParamSeq follows), etc."),
     },
 }, async ({ type, payload }) => {
     const check = await requireBridge();
@@ -5324,13 +5592,55 @@ server.registerTool("update_modulation", {
                     ? "applyMacroUpdate"
                     : type === "paramSeq"
                         ? "applyParamSeqUpdate"
-                        : "applyParamSeqSequenceUpdate";
+                        : type === "paramSeqSequence"
+                            ? "applyParamSeqSequenceUpdate"
+                            : "applyFreeSeqSequenceUpdate";
     await bridge.send(action, data);
     return text(`Applied ${type} update.`);
 });
 // ============================================================
 // TOOLS — Song mode
 // ============================================================
+// Advanced transition spec (ADR-001, PAM >= 1.19.6; engine families live from
+// PAM >= 1.20.0). Honest contract: it persists, round-trips, and reads back
+// RESOLVED. Pattern policy (dissolve/wipe/cells), mix law (equal power / equal
+// gain / correlation), tail (cut/fade/ring) and phase run on song VARIATION
+// sections and queued bar-sync flips; preset destinations coerce to a param
+// glide, and offline bounces coerce ring→fade and blend→hard switch (each
+// reported, never silent). Wire enums are append-only.
+const morphCurveEnum = z.enum(["linear", "ease", "exp", "log"]);
+const transitionSpecSchema = z.object({
+    mode: z.enum(["auto", "param", "mix", "seq", "all"]).optional(),
+    window: z
+        .object({
+        bars: z.number().min(0).max(8).optional(),
+        paramCurve: morphCurveEnum.optional(),
+        patternCurve: morphCurveEnum.optional(),
+        mixCurve: morphCurveEnum.optional(),
+    })
+        .optional(),
+    pattern: z.object({ policy: z.enum(["dissolve", "wipe", "cells"]).optional() }).optional(),
+    audio: z
+        .object({
+        mixLaw: z.enum(["equalPower", "equalGain", "correlation"]).optional(),
+        tail: z.enum(["cut", "fade", "ring"]).optional(),
+        tailMaxBars: z.number().min(0.25).max(8).optional(),
+    })
+        .optional(),
+    phase: z.enum(["inherit", "reset", "continue"]).optional(),
+});
+const TRANSITION_SPEC_HONESTY = "Advanced transition spec (PAM >= 1.19.6; live engine from PAM >= 1.20.0): pattern.policy " +
+    "('dissolve' prob-morphs events, 'wipe' replaces them at a moving frontier, 'cells' hands " +
+    "whole cells over in ascending order), audio.mixLaw ('equalPower' default, 'equalGain' for " +
+    "correlated sections, 'correlation' auto-adapts), audio.tail ('fade' default, 'cut', 'ring' " +
+    "lets voices/FX decay up to tailMaxBars), phase ('reset'/'continue' overrides the song's " +
+    "Reset Phase per cable), window.patternCurve/mixCurve (per-domain easing; patternCurve " +
+    "defaults linear). Runs on variation sections + queued flips, and on preset destinations " +
+    "when the lanePresetSections setting is on (PAM >= 1.20.1 — the dual-lane preset section " +
+    "pipeline; with it off, preset destinations coerce to a param glide). Offline bounces " +
+    "coerce ring→fade, blend→hard switch. 'get' reads back each cable's resolvedTransition " +
+    "(effective values after inheritance and capability coercion) and lastMorphResolution " +
+    "(the engine's latest AUTO decision + reason).";
 server.registerTool("song_mode", {
     title: "Song Mode",
     description: "Control PAM's song mode (timeline of variation/preset sections). Ops: 'setArrangement', " +
@@ -5342,9 +5652,13 @@ server.registerTool("song_mode", {
         "VX (visual) variation slot via `vxVariationIndex` (omit = visuals follow the section's " +
         "audio slot 1:1; see the vx_variation tool), optionally inside a specific VX scene via " +
         "`vxScenePath` (the .vxpreset loads before the section plays, so sections can pull visuals " +
-        "from different scenes). 'get' reads the arrangement back (nodes, compiled steps with the " +
-        "VX scene+slot each recalls, total bars); 'assignVx' re-pins one section's VX slot (and " +
-        "optional scene) after authoring.\n\n" +
+        "from different scenes). A section can also carry `morphBars`/`morphCurve`/`morphMode` to glide the " +
+        "incoming variation's continuous params over the bars before its boundary (PAM >= 1.19.3), and an " +
+        "advanced `transition` spec (PAM >= 1.19.6 — authored metadata; see the field description). " +
+        "'get' reads the arrangement back (nodes, compiled steps with the " +
+        "VX scene+slot each recalls, total bars, and each cable's `resolvedTransition` — the effective " +
+        "transition after inheritance and capability coercion, e.g. preset destinations report param); " +
+        "'assignVx' re-pins one section's VX slot (and optional scene) after authoring.\n\n" +
         "'setSequence' is the older HEADLESS raw-step path (works with the window closed): steps " +
         "land in the C++ player but carry no grid nodes, so the UI can't edit them and VX can only " +
         "follow 1:1 by audio slot.",
@@ -5365,13 +5679,28 @@ server.registerTool("song_mode", {
             .describe("Operation."),
         sections: z
             .array(z.object({
-            variationIndex: z.number().min(0).max(7).describe("Audio variation slot 0-7 this section plays."),
+            variationIndex: z.number().min(0).max(7).describe("Audio variation slot 0-7 this section plays. With presetPath set, this selects the variation INSIDE that preset's own bank — the two compose, they are not mutually exclusive."),
             bars: z.number().positive().optional().describe("Section length in bars (default: auto from longest pattern)."),
             repeat: z.number().int().min(1).optional().describe("Times to play before advancing (default 1)."),
             muted: z.boolean().optional().describe("Pass through without an audio trigger."),
             probability: z.number().min(0).max(1).optional().describe("Trigger probability (0-1)."),
-            presetPath: z.string().optional().describe("Load this preset instead of switching variation."),
+            presetPath: z.string().optional().describe("Cross-preset section: at this section's boundary the song switches to THIS preset file, playing its variations[variationIndex] slot. With lanePresetSections on (PAM >= 1.20.1) it transitions exactly like a variation section (prepared off the audible path, full morph family); otherwise the legacy in-place load applies."),
             label: z.string().optional().describe("Section label shown on the grid node (e.g. 'Intro', 'Hook')."),
+            morphBars: z
+                .number()
+                .min(0)
+                .max(8)
+                .optional()
+                .describe("Pre-anchor morph window in bars for the transition INTO this section — continuous params glide to the new values, landing at the boundary (PAM >= 1.19.3). 0 = explicit hard switch (never morph, ignores the song's default); omit to inherit the default. Values in (0, 0.25) clamp up to 0.25."),
+            morphCurve: z
+                .enum(["linear", "ease", "exp", "log"])
+                .optional()
+                .describe("Morph glide easing; default ease. Ignored without morphBars."),
+            morphMode: z
+                .enum(["auto", "param", "mix", "seq", "all"])
+                .optional()
+                .describe("Morph realization; default auto — the engine picks mix when the sections differ in graph topology (samples, synth engines, routing) or when nothing can glide, param otherwise (PAM >= 1.19.4; older builds run param). 'param' glides continuous params; 'mix' DJ-blends stems; 'seq' adds a staged pattern dissolve to the glide; 'all' runs glide + dissolve + blend (seq/all on older builds run param). Ignored without morphBars."),
+            transition: transitionSpecSchema.optional().describe(TRANSITION_SPEC_HONESTY),
             vxVariationIndex: z
                 .number()
                 .int()
@@ -5399,9 +5728,28 @@ server.registerTool("song_mode", {
                 .max(1)
                 .optional()
                 .describe("Branch probability (0-1). Sibling routes normalize to 100%."),
+            morphBars: z
+                .number()
+                .min(0)
+                .max(8)
+                .optional()
+                .describe("Per-cable morph window in bars — overrides the destination section's morphBars for THIS cable only (branching arrangements can give each incoming cable its own window). 0 = hard switch; omit to use the section value / song default."),
+            morphCurve: z
+                .enum(["linear", "ease", "exp", "log"])
+                .optional()
+                .describe("Per-cable morph easing; overrides the destination section's morphCurve."),
+            morphMode: z
+                .enum(["auto", "param", "mix", "seq", "all"])
+                .optional()
+                .describe("Per-cable morph realization; overrides the destination section's morphMode. Same modes as the section field, incl. 'seq' (pattern dissolve) and 'all' (glide + dissolve + blend)."),
+            transition: transitionSpecSchema.optional().describe("Per-cable " + TRANSITION_SPEC_HONESTY),
         }))
             .optional()
-            .describe("For 'setArrangement': optional cable graph. Multiple cables may leave or enter a section."),
+            .describe("For 'setArrangement': optional cable graph. Multiple cables may leave or enter a section. Each cable may carry its own morphBars/morphCurve/morphMode/transition."),
+        defaultTransition: transitionSpecSchema
+            .nullable()
+            .optional()
+            .describe("For 'setArrangement': song-level advanced transition defaults inherited by cables without their own `transition`; null clears. " + TRANSITION_SPEC_HONESTY),
         loop: z.boolean().optional().describe("For 'setArrangement': loop the whole arrangement."),
         nodeId: z.string().optional().describe("For 'assignVx': grid node id (from op 'get')."),
         stepIndex: z.number().int().min(0).optional().describe("For 'assignVx': compiled step index (alternative to nodeId)."),
@@ -5464,6 +5812,7 @@ server.registerTool("song_mode", {
                 op: "setSongArrangement",
                 sections: args.sections,
                 ...(args.connections !== undefined && { connections: args.connections }),
+                ...(args.defaultTransition !== undefined && { defaultTransition: args.defaultTransition }),
                 ...(args.loop !== undefined && { loop: args.loop }),
                 ...(args.enabled !== undefined && { enabled: args.enabled }),
                 ...(args.crossfadeMs !== undefined && { crossfadeMs: args.crossfadeMs }),
@@ -6239,7 +6588,7 @@ server.registerTool("update_settings", {
         "experimental-feature gates from an agent. Common boolean keys: experimentalMode, " +
         "experimentalPluginHost, experimentalMcpBridge. To enable the plugin host, set BOTH " +
         "experimentalMode:true AND the specific sub-flag (e.g. experimentalPluginHost:true) in one call. " +
-        "The drum synth needs no flag — it is a standard feature on PAM. Other keys " +
+        "Set drumSynthEnabled:false to hide its UI without muting loaded synths. Other keys " +
         "include UI/library preferences — call get_state or inspect the returned object for the current set.",
     inputSchema: {
         settings: z
@@ -6316,6 +6665,24 @@ server.registerTool("get_audio_device_setup", {
     const setup = await bridge.send("getAudioDeviceSetup");
     return json(setup);
 });
+server.registerTool("set_audio_device", {
+    title: "Set Audio Output Device",
+    description: "Switch the active audio OUTPUT device by name (standalone only — plugin-hosted builds let the DAW own the " +
+        "device, and the call errors there). Use the exact name from get_audio_device_setup's device list. " +
+        "The usual reason to call this headlessly is routing PAM into a loopback device (BlackHole, Soundflower) " +
+        "so a capture run records audio. MIDI devices go through set_midi_io.",
+    inputSchema: {
+        deviceName: z
+            .string()
+            .describe("Output device name exactly as listed by get_audio_device_setup."),
+    },
+}, async ({ deviceName }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("setAudioDevice", [deviceName]);
+    return text(`Audio output device set to '${deviceName}'.`);
+});
 server.registerTool("set_midi_io", {
     title: "Set MIDI I/O Devices",
     description: "Select MIDI input/output devices (standalone). Use get_audio_device_setup to discover device IDs first. " +