@map-audio/pam-mcp-server 1.1.0 → 1.12.0

package/dist/server.js

@@ -3,6 +3,7 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
+import { inflateSync } from "node:zlib";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadManifest, getParameterIndex, getParametersByCell, getGlobalParameters, findPresetDirs, resolvePresetPath, walkPresets, } from "./manifest.js";
@@ -76,23 +77,49 @@ function parsePresetFile(raw) {
     const dataStr = raw.slice(prefixLen + metadataSize);
     return { metadata: JSON.parse(metadataStr), data: JSON.parse(dataStr) };
 }
+// PAM ≥ 1.4.61 stores variations ONLY in the data block, zlib+base64-compressed with a
+// "PAMZ1:" marker (see helpers/VariationCodec.h). Decompress one entry to plain JSON;
+// plain (older-format) entries pass through unchanged.
+const VARIATION_MARKER = "PAMZ1:";
+function decompressVariationEntry(v) {
+    if (typeof v !== "string" || !v.startsWith(VARIATION_MARKER))
+        return v;
+    try {
+        return inflateSync(Buffer.from(v.slice(VARIATION_MARKER.length), "base64")).toString("utf8");
+    }
+    catch {
+        return v;
+    }
+}
+/**
+ * Canonical variations array for a parsed preset, as plain-JSON strings (or nulls).
+ * The data block is authoritative (current format); metadata.variations is the fallback
+ * for legacy presets that still carried the duplicate copy there.
+ */
+function variationsFromParsedPreset(parsed) {
+    const fromData = parsed.data?.variations;
+    const fromMeta = parsed.metadata?.variations;
+    const src = Array.isArray(fromData) && fromData.length === PRESET_VARIATION_SLOTS ? fromData
+        : Array.isArray(fromMeta) && fromMeta.length === PRESET_VARIATION_SLOTS ? fromMeta
+            : null;
+    if (!src)
+        return Array(PRESET_VARIATION_SLOTS).fill(null);
+    return src.map(decompressVariationEntry);
+}
 /**
  * Read existing variations array from a preset file on disk.
- * Returns Array(8) of strings or nulls.
+ * Returns Array(8) of plain-JSON strings or nulls.
  */
 async function readExistingVariations(presetPath) {
     try {
         const fullPath = await resolvePresetPath(presetPath);
         const raw = await readFile(fullPath, "utf-8");
-        const { metadata } = parsePresetFile(raw);
-        if (metadata.variations && Array.isArray(metadata.variations) && metadata.variations.length === PRESET_VARIATION_SLOTS) {
-            return [...metadata.variations];
-        }
+        return variationsFromParsedPreset(parsePresetFile(raw));
     }
     catch {
         // Preset doesn't exist yet or can't be read — start fresh
+        return Array(PRESET_VARIATION_SLOTS).fill(null);
     }
-    return Array(PRESET_VARIATION_SLOTS).fill(null);
 }
 // Mirrors interop.ts VARIATION_EXCLUDED_PARAMS (activePresetPath is excluded separately below, matching interop.ts)
 const VARIATION_EXCLUDED_PARAMS = [
@@ -152,19 +179,31 @@ function formatParam(p) {
 // --- Server ---
 const server = new McpServer({
     name: "pam",
-    version: "1.1.0",
+    version: "1.8.0",
 }, {
     instructions: "PAM is an audio sampler plugin. When browsing samples, ALWAYS call get_default_locations " +
         "first to discover the user's actual library paths — never guess paths like ~/Music/PAM. " +
         "The sample library lives under ~/Library/Application Support/, NOT ~/Music/. " +
         "Use the returned paths with list_samples. When loading samples, use load_sample with " +
         "paths from list_samples. Transport must be playing for sequencer output. " +
-        "Tools added in this server version (1.1.0) — looper recording/variations, song mode, " +
-        "modulation edits (LFO/Env/Vary/Macro/ParamSeq), MIDI CC/PC, MIDI recording, sample " +
-        "analysis, live resample, bar-synced variation scheduling, variation hold — require " +
-        "PAM ≥ 1.4.44. If a tool fails with \"PAM build does not support 'X'\", the connected " +
-        "plugin is older than this MCP server; the user must update PAM (updating the npm " +
-        "package alone is not enough).",
+        "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. " +
+        "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, " +
+        "set_plugin_params, skip_current_plugin_scan, remove_plugin_from_blocklist — require PAM ≥ 1.7.0. " +
+        "VX video tools (get_video_state, video_command, add_video_layer, update_video_layer, " +
+        "remove_video_layer, apply_video_layout, add_video_fx, set_video_fx, remove_video_fx, " +
+        "bind_video_param, set_video_settings) require PAM ≥ 1.8.0 AND PAM's window to be OPEN " +
+        "(the video engine renders in the WebView; there is no headless renderer). For " +
+        "audio-reactive control, note the visual audio-react params (visualWaveDisplace, etc.) " +
+        "are regular plugin params — drive them with set_parameters; layers/FX/bindings go through " +
+        "the video tools. When building a scene, call get_video_state first to learn layer/fx ids. " +
+        "Earlier tool sets (looper, song mode, modulation edits, MIDI recording, sample analysis, " +
+        "live resample, variation scheduling, AI generation) require PAM ≥ 1.4.50 / 1.5.0. " +
+        "If a tool fails with \"PAM build does not support 'X'\", the connected plugin is older than " +
+        "this MCP server; the user must update PAM (updating the npm package alone is not enough).",
 });
 // ============================================================
 // TOOLS — Offline (work without plugin running)
@@ -478,6 +517,293 @@ server.registerTool("load_sample", {
     await bridge.send("loadSampleToCell", filePath, cellId);
     return text(`Loaded ${basename(filePath)} into cell ${cellId}.`);
 });
+// ---- Unified AI model management (notochord / aigen / magenta) ----
+// All six map to the C++ MCPBridge model* actions (helpers/MCPBridge.cpp::handleModelOp).
+// Each engine must have its experimental flags on (update_settings: experimentalMode
+// + experimental<Engine>) — the bridge returns a clear error otherwise.
+const MODEL_ENGINE = z
+    .enum(["notochord", "aigen", "magenta"])
+    .describe("Which AI engine. notochord = MIDI co-player (~18 MB blob); aigen = Stable Audio 3 sample generation (~3.2 GB ONNX); magenta = MagentaRT realtime audio (Apple Silicon, MLX).");
+const MODEL_VARIANT = z
+    .enum(["base", "small"])
+    .optional()
+    .describe("Magenta only: which variant (base = 2.4B, needs ~M2 Max/M3 Pro+; small = 230M, default). Ignored for notochord/aigen (single model).");
+server.registerTool("download_model", {
+    title: "Download AI Model",
+    description: "Start (or resume) downloading model weights for an AI engine. Async — returns immediately with download progress; poll get_model_status. aigen + notochord auto-load on completion; magenta needs a separate load_model. Requires the engine's experimental flags.",
+    inputSchema: { engine: MODEL_ENGINE, model: MODEL_VARIANT },
+}, async ({ engine, model }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelDownload", { engine, model }));
+});
+server.registerTool("get_model_status", {
+    title: "Get AI Model Status",
+    description: "Report downloaded / loaded / loading / download-in-flight + version + disk size + live download progress for an AI engine.",
+    inputSchema: { engine: MODEL_ENGINE },
+}, async ({ engine }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelStatus", { engine }));
+});
+server.registerTool("load_model", {
+    title: "Load AI Model",
+    description: "Load a downloaded model into memory (async — poll get_model_status for loaded:true). Use after unload, or for magenta after download. magenta accepts an optional variant; omit to load whichever is on disk.",
+    inputSchema: { engine: MODEL_ENGINE, model: MODEL_VARIANT },
+}, async ({ engine, model }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelLoad", { engine, model }));
+});
+server.registerTool("unload_model", {
+    title: "Unload AI Model",
+    description: "Free the loaded model from memory (weights stay on disk). May briefly stall the plugin while an in-flight load finishes (non-interruptible ORT/MLX load).",
+    inputSchema: { engine: MODEL_ENGINE },
+}, async ({ engine }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelUnload", { engine }));
+});
+server.registerTool("delete_model", {
+    title: "Delete AI Model",
+    description: "Delete downloaded model weights from disk. Unloads first automatically. DESTRUCTIVE — re-download to restore. magenta delete is variant-agnostic (removes both variants + shared resources).",
+    inputSchema: { engine: MODEL_ENGINE, model: MODEL_VARIANT },
+}, async ({ engine, model }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelDelete", { engine, model }));
+});
+server.registerTool("list_models", {
+    title: "List AI Models",
+    description: "List available model variants per engine with downloaded / loaded state. Omit engine to list all engines (notochord, aigen, magenta base + small).",
+    inputSchema: { engine: MODEL_ENGINE.optional() },
+}, async ({ engine }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("modelList", { engine }));
+});
+server.registerTool("generate_sample", {
+    title: "Generate Sample (AI)",
+    description: "Generate a new audio sample via the on-device AI engine (Stable Audio 3 Small SFX, ~3.2 GB ONNX). The plugin must have the model downloaded first (Settings → Local models). Returns the on-disk path to the generated WAV and optionally loads it into a cell.",
+    inputSchema: {
+        category: z
+            .enum(["kick", "snare", "hat", "perc", "bass", "synth", "pad", "fx", "loop"])
+            .describe("Sound category — drives prompt template defaults."),
+        prompt: z.string().describe("Text prompt describing the desired sound."),
+        durationSeconds: z
+            .number()
+            .min(0.1)
+            .max(47)
+            .describe("Output length in seconds (Stable Audio 3 Small SFX engine cap ≈ 47 s). For loops, pass bar-converted duration: bars * beatsPerBar * 60 / bpm."),
+        mode: z
+            .enum(["text", "inpaint", "continuation"])
+            .optional()
+            .default("text")
+            .describe("Generation mode. text = unconditional, inpaint = audio-to-audio with mask, continuation = extend existing audio."),
+        cellId: z
+            .number()
+            .int()
+            .min(1)
+            .max(8)
+            .optional()
+            .describe("If provided, load result directly into this cell."),
+        seed: z.number().int().optional().describe("Deterministic seed. Random if omitted."),
+        refAudioPath: z.string().optional().describe("Required for inpaint/continuation. Absolute path to a WAV."),
+        maskSpec: z
+            .string()
+            .optional()
+            .describe('Mask spec for inpaint mode: "tail:0.5" or "transient:0-0.05" or "full".'),
+    },
+}, async (args) => {
+    const ok = await requireBridge();
+    if (ok !== true)
+        return ok;
+    try {
+        const result = await bridge.send("aiGenerate", args);
+        return json(result);
+    }
+    catch (e) {
+        return error(`AI generation failed: ${e.message}`);
+    }
+});
+server.registerTool("generate_kit", {
+    title: "Generate Kit (AI)",
+    description: "Generate multiple AI samples in parallel (Stable Audio 3 Small SFX) and load them into a list of cells. Useful for building a coherent drum / instrument kit from a single high-level prompt. Requires the on-device model to be downloaded (Settings → Local models).",
+    inputSchema: {
+        prompt: z.string().describe('High-level kit description (e.g. "dark trap drum kit", "lofi house").'),
+        cells: z
+            .array(z.object({
+            id: z.number().int().min(1).max(8),
+            role: z.enum(["kick", "snare", "hat", "perc", "bass", "synth", "pad", "fx", "loop"]),
+        }))
+            .min(1)
+            .max(8)
+            .describe("Cells to populate. Each gets one sample matching the role."),
+    },
+}, async (args) => {
+    const ok = await requireBridge();
+    if (ok !== true)
+        return ok;
+    const { prompt, cells } = args;
+    // C++ handleAIGenerateKit expects { requests: [{ prompt, category, cellId, durationSeconds }] }.
+    // Derive a per-role prompt + sensible duration from the single kit prompt;
+    // cellId on each request drives the bridge's load-into-cell step. (mode omitted → text.)
+    const durationForRole = (role) => role === "loop" ? 4 : role === "bass" || role === "synth" || role === "pad" || role === "fx" ? 2 : 1.5;
+    const requests = cells.map((c) => ({
+        prompt: `${prompt}, ${c.role}`,
+        category: c.role,
+        cellId: c.id,
+        durationSeconds: durationForRole(c.role),
+    }));
+    try {
+        const results = await bridge.send("aiGenerateKit", { requests });
+        return json(results);
+    }
+    catch (e) {
+        return error(`Kit generation failed: ${e.message}`);
+    }
+});
+// --- AI Audio Workbench (Phase A, dev-gated) ---------------------------------
+// Drives the Transform canvas headlessly: canvas state (mask regions / strength
+// curve / prompt / seed / sigma), sidecar renders, and the take shelf. Requires
+// experimentalMode + experimentalAIGen (update_settings) AND the SA3 Python
+// sidecar running on 127.0.0.1:8093 (packages/sa3-workbench-sidecar/README.md).
+const WORKBENCH_MASK_REGION = z.object({
+    startSec: z.number().min(0).describe("Region start in seconds (source time)."),
+    endSec: z.number().min(0).describe("Region end in seconds (must be > startSec)."),
+    lowHz: z.number().min(0).optional()
+        .describe("Optional band low edge in Hz (canvas v2 2D mask). Omit BOTH lowHz/highHz for a full-band region (1D back-compat)."),
+    highHz: z.number().min(0).optional()
+        .describe("Optional band high edge in Hz (must be > lowHz). lowHz<=20 && highHz>=source nyquist is treated as full band by the sidecar."),
+});
+const WORKBENCH_CURVE_POINT = z.object({
+    t: z.number().describe("Normalized time 0..1."),
+    v: z.number().describe("Value 0..1 (σ at this point)."),
+    tension: z.number().optional().describe("Curve tension (CurveCanvas semantics, default 0)."),
+});
+const WORKBENCH_STATE_FIELDS = {
+    sourceCellId: z.number().int().min(1).max(8).nullable().optional()
+        .describe("Cell whose sample is the transform source (null to clear)."),
+    prompt: z.string().optional().describe("Text prompt for the render."),
+    seed: z.number().int().min(0).optional().describe("Render seed."),
+    seedLocked: z.boolean().optional().describe("Lock seed across renders (iterate at fixed identity)."),
+    sigma: z.number().min(0.02).max(1).optional()
+        .describe("Deviation σ / init noise level. a2a: 0.25-0.35 preserves melody, 0.45-0.5 variation; inpaint regime ~0.85."),
+    steps: z.number().int().min(1).max(32).optional().describe("Denoise steps (8 is the validated recipe)."),
+    maskRegions: z.array(WORKBENCH_MASK_REGION).optional()
+        .describe("Transform-lane mask. Empty = pure a2a re-render of the whole source; regions = inpaint (regenerate inside, keep outside). Regions may carry an optional lowHz/highHz band."),
+    strengthCurve: z.array(WORKBENCH_CURVE_POINT).optional()
+        .describe("Strength-lane breakpoints (stored with full provenance; per-region σ application is experimental)."),
+    activeSourcePath: z.string().optional()
+        .describe("Render-chain head: absolute WAV path used as the transform source ('' = the source cell's sample). Managed automatically — each successful render advances it to the new take's wavPath; set explicitly only to point the chain at a prior take. Walk it back with workbench_undo / workbench_reset_chain."),
+    sketchPath: z.string().optional()
+        .describe("SKETCH mode: absolute path to a painted-gesture WAV ('' = no sketch). Normally written by the UI (workbenchSaveSketch saves into ai-cache/workbench/); settable directly for headless tests. When non-empty, renders feed the model source + sketch*sketchGain as init audio AND use that MIX as the preservation reference for masks/paste-back — the gesture survives outside masked regions."),
+    sketchGain: z.number().min(0).max(1).optional()
+        .describe("SKETCH mix gain 0..1 (default 0.5) applied to the sketch before summing with the source. If the mix peaks above 0.99 the sidecar scales the whole mix down to 0.99."),
+};
+server.registerTool("workbench_get_state", {
+    title: "Workbench: Get State",
+    description: "Read the AI Audio Workbench canvas state AND the take shelf: { state: { sourceCellId, prompt, seed, seedLocked, sigma, steps, maskRegions, strengthCurve, activeSourcePath, sketchPath, sketchGain }, takes: [...] }.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchGetState"));
+});
+server.registerTool("workbench_set_state", {
+    title: "Workbench: Set State",
+    description: "Partial-merge the Workbench canvas state (only the keys you pass change). Also pushes the merged state into an open Workbench UI. Returns the full merged state.",
+    inputSchema: WORKBENCH_STATE_FIELDS,
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchSetState", args));
+});
+server.registerTool("workbench_render", {
+    title: "Workbench: Render",
+    description: "Render the Workbench transform via the SA3 sidecar and append the result to the take shelf. Renders the CURRENT canvas state merged with any overrides passed here (overrides do not persist). Blocks until done (up to ~3 min: pipeline rebuilds + multi-region inpaints render sequentially). Returns the take { id, wavPath, prompt, seed, sigma, maskRegions, createdAt, sourceCellId, durationSeconds, error? }. Source resolution: sourcePath override > activeSourcePath (chain head) > state.sourceCellId's sample file. A successful render ADVANCES the chain (activeSourcePath = new take's wavPath) — step back with workbench_undo or workbench_reset_chain.",
+    inputSchema: {
+        ...WORKBENCH_STATE_FIELDS,
+        sourcePath: z.string().optional()
+            .describe("Absolute path to a source WAV — bypasses sourceCellId resolution."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    try {
+        return json(await bridge.send("workbenchRender", args));
+    }
+    catch (e) {
+        return error(`Workbench render failed: ${e.message}`);
+    }
+});
+server.registerTool("workbench_list_takes", {
+    title: "Workbench: List Takes",
+    description: "List all Workbench takes (renders) with full provenance, oldest first.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchListTakes"));
+});
+server.registerTool("workbench_load_take", {
+    title: "Workbench: Load Take",
+    description: "Load a rendered take's WAV into a cell (same native path as load_sample).",
+    inputSchema: {
+        takeId: z.string().describe("Take id from workbench_render / workbench_list_takes."),
+        cellId: z.number().int().min(1).max(8).describe("Target cell."),
+    },
+}, async ({ takeId, cellId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    try {
+        return json(await bridge.send("workbenchLoadTake", { takeId, cellId }));
+    }
+    catch (e) {
+        return error(`Failed to load take: ${e.message}`);
+    }
+});
+server.registerTool("workbench_undo", {
+    title: "Workbench: Undo (pop chain)",
+    description: "Pop the Workbench render chain one step: restores the previous chain head (activeSourcePath) so the next render re-transforms the prior source. No-op at the chain root (cell sample). Takes are kept. Returns the full { state, takes }.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchUndo"));
+});
+server.registerTool("workbench_reset_chain", {
+    title: "Workbench: Reset Chain",
+    description: "Clear the Workbench render chain: empties the undo stack and resets the source back to the cell sample (activeSourcePath = ''). Takes are kept. Returns the full { state, takes }.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchResetChain"));
+});
+server.registerTool("workbench_sidecar_status", {
+    title: "Workbench: Sidecar Status",
+    description: "Ping the SA3 render sidecar (127.0.0.1:8093). Returns { connected, loaded } — loaded means a pipeline is resident (first render after a cold start also pays the model load).",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    return json(await bridge.send("workbenchSidecarStatus"));
+});
 server.registerTool("trigger_midi", {
     title: "Trigger MIDI",
     description: "Send a MIDI note to a specific cell or globally. " +
@@ -558,8 +884,17 @@ server.registerTool("add_modulation", {
             .boolean()
             .default(false)
             .describe("Bipolar modulation (modulates both directions)."),
+        pitch: z
+            .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."),
+        pitchDuck: z
+            .boolean()
+            .optional()
+            .describe("Envelope only: when pitch=true, switch from BOOST to DUCK semantics (notch). Ignored if pitch=false."),
     },
-}, async ({ type, paramId, cellId, lfoIndex, strength, bipolar }) => {
+}, async ({ type, paramId, cellId, lfoIndex, strength, bipolar, pitch, pitchDuck }) => {
     const index = await getParameterIndex();
     const param = index.get(paramId);
     if (!param)
@@ -582,7 +917,7 @@ server.registerTool("add_modulation", {
     else if (type === "envelope") {
         if (!cellId)
             return error("cellId is required for envelope modulation.");
-        await bridge.send("addEnvelope", paramId, cellId, strength, bipolar, effectEnableParams);
+        await bridge.send("addEnvelope", paramId, cellId, strength, bipolar, effectEnableParams, pitch ?? false, pitchDuck ?? false);
     }
     else if (type === "vary") {
         if (!cellId)
@@ -939,11 +1274,9 @@ server.registerTool("save_variation", {
     try {
         const fullPath = await resolvePresetPath(diskPath);
         const raw = await readFile(fullPath, "utf-8");
-        const { metadata: m } = parsePresetFile(raw);
-        existingMeta = m;
-        if (m.variations && Array.isArray(m.variations) && m.variations.length === PRESET_VARIATION_SLOTS) {
-            variations = [...m.variations];
-        }
+        const parsed = parsePresetFile(raw);
+        existingMeta = parsed.metadata;
+        variations = variationsFromParsedPreset(parsed);
     }
     catch {
         // New preset or unreadable — start fresh
@@ -1332,6 +1665,473 @@ server.registerTool("import_visual_folder", {
         (result.operationId ? ` (operationId: ${result.operationId})` : ""));
 });
 // ============================================================
+// VX video subsystem — layers, FX, audio-reactive bindings, settings
+// ============================================================
+//
+// The video scene lives in PAM's WebView (R3F/WebGL). These tools forward semantic
+// commands into the live video stores and read back a full-scene snapshot. PAM's
+// window must be OPEN for commands to apply (no headless renderer). Audio-reactive
+// *visual params* (visualWaveDisplace, etc.) are regular plugin params — drive those
+// with set_parameters; everything else (layers/FX/bindings/output FX) goes here.
+// Per-layer FX types (FxRegistry). Some only apply to drawing/text (trails, beam).
+const VIDEO_LAYER_FX = "hueRotate, glow, audioReact, vibration, chromaticAberration, pixelate, rgbShift, " +
+    "mirror, trails(drawing/text), beam(drawing/text), shake, rolls, barrelBlur, edge, " +
+    "halftone, patches, brightnessContrast, lines, feedback, warp, datamosh, slicer, " +
+    "polarSlitScan, cellVoronoi, spectralZones, paletteLut, asciiDither, pixelSort, " +
+    "cameraShake, blur";
+// Output/global FX chain ids (videoStore, DEFAULT_VIDEO_FX_CONFIG).
+const VIDEO_OUTPUT_FX = "lines, barrelBlur, brightnessContrast, edge, glow, shake, rgbShift, halftone, mirror, " +
+    "patches, pixelate, rolls, feedback, warp, datamosh, slicer, positionXY, speed, " +
+    "cellVoronoi, polarSlitScan, spectralZones, audioReact";
+// Binding source vocabulary (sourceKey string form OR a ModSource object).
+const VIDEO_BIND_SOURCES = "Pass `source` as a sourceKey string: " +
+    "`g:<id>` global (level, bandLow, bandMid, bandHigh, transient, transientLow, " +
+    "transientMid, transientHigh, bpm, spectralCentroid, spectralFlux, stereoWidth, " +
+    "varyActivity, phraseLevel, phraseBass, looperBus, masterOnsetLow/Mid/High, " +
+    "masterStereoWidth, masterPanScalar, masterFullMix, masterCompressorGR, " +
+    "sidechainLevel, sidechainEnv); " +
+    "`t:<phase>` transport (beat, bar, phrase); " +
+    "`c:<cell>:<field>` per-cell (level, envFollow, pulse, onset, spectrumPeak, " +
+    "spectrumCentroid, pitch, postFaderL/R, samplerRMSL/R, synthRMS, beatPosition, " +
+    "activeRetriggers, grainActivity, grainPos, grainSpread, grainPitch, " +
+    "grainPitchSpread, grainReverseRatio); " +
+    "`l:<track>:level` looper; `lf:<lfo>:rate|phase` LFO; " +
+    "`p:<paramId>` any DAW param (e.g. p:macro_1). Or a structured object e.g. " +
+    "{kind:'cell',cellIndex:1,field:'onset'}.";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function getVideoStateRaw() {
+    const r = await bridge.send("getVideoState");
+    return (typeof r === "string" ? JSON.parse(r) : r) ?? {};
+}
+const sendVideoCommand = (command) => bridge.send("videoCommand", command);
+/** Create ops are fire-and-forget; resolve the minted id by diffing the snapshot. */
+async function resolveNewId(beforeIds, pick, timeoutMs = 2500) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await sleep(120);
+        const s = await getVideoStateRaw();
+        const found = pick(s).find((id) => !beforeIds.has(id));
+        if (found)
+            return found;
+    }
+    return null;
+}
+server.registerTool("get_video_state", {
+    title: "Get Video State",
+    description: "Read the full VX video scene: layers (in render order, top-first) with their " +
+        "per-layer FX chains, the output/global FX chain, audio-reactive bindings, " +
+        "mod-matrix routes, the 3D model overlay, the active cell, and global render/sync " +
+        "settings. Layer/FX/binding ids returned here are what the other video tools " +
+        "address. If `available` is false, open PAM's window so the video UI mounts.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const state = await getVideoStateRaw();
+    return json(state);
+});
+server.registerTool("capture_ui", {
+    title: "Capture UI Screenshot",
+    description: "Render PAM's plugin UI (#app_root) to a PNG via html2canvas and return the saved " +
+        "file path (read it to view the image). Optionally compose the view first: " +
+        "gridSize (1|4|8), mainView (CellGrid|CtrlAll|Envelope|LFO|Vary|Mixer|SongMode|Video|" +
+        "PresetBrowser; omit/null = cell grid), instrumentView ('synth'|'sampler', applied to " +
+        "all cells). REQUIRES PAM's window OPEN — html2canvas needs the live DOM, there is no " +
+        "headless renderer (same constraint as the video tools). Beats screen-capture: " +
+        "deterministic, no cursor/screen control, exact UI bitmap.",
+    inputSchema: {
+        gridSize: z.number().optional().describe("Cell grid size to set before capture: 1, 4, or 8."),
+        mainView: z
+            .string()
+            .optional()
+            .describe("Main view to switch to before capture (CellGrid, Mixer, LFO, …). Omit for the cell grid."),
+        instrumentView: z
+            .enum(["synth", "sampler"])
+            .optional()
+            .describe("Switch all cells to the synth or sampler tab before capture."),
+        settleMs: z.number().optional().describe("Delay (ms) after view changes before rasterizing. Default 350."),
+        timeoutMs: z.number().optional().default(8000).describe("Max ms to wait for the WebView to return the image."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ gridSize, mainView, instrumentView, settleMs, timeoutMs }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const requestId = `ui-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+    const setup = { requestId };
+    if (typeof gridSize === "number")
+        setup.gridSize = gridSize;
+    if (mainView !== undefined)
+        setup.mainView = mainView;
+    if (instrumentView !== undefined)
+        setup.instrumentView = instrumentView;
+    if (typeof settleMs === "number")
+        setup.settleMs = settleMs;
+    // Forward is fire-and-forget; poll the C++ cache until the WebView posts the PNG back.
+    await bridge.send("captureUi", setup);
+    const deadline = Date.now() + (timeoutMs ?? 8000);
+    for (;;) {
+        const res = (await bridge.send("getUiCapture", { requestId }));
+        if (res.ready && res.requestId === requestId && res.path) {
+            return text(`Saved UI screenshot: ${res.path}`);
+        }
+        if (Date.now() > deadline) {
+            return error("capture_ui timed out waiting for the WebView to return the image. Is PAM's window " +
+                "open and active? html2canvas needs the live DOM — a closed/suspended editor cannot render.");
+        }
+        await new Promise((r) => setTimeout(r, 150));
+    }
+});
+server.registerTool("video_command", {
+    title: "Video Command (advanced)",
+    description: "Escape hatch to the full video command router — pass any { op, ...args } object. " +
+        "Use the dedicated tools (add_video_layer, set_video_fx, bind_video_param, …) when " +
+        "one fits; this reaches everything else. Ops: " +
+        "addLayer{kind,name?,insertAt?}, removeLayer{layerId}, updateLayer{layerId,patch}, " +
+        "moveLayer{layerId,toIndex}, duplicateLayer{layerId}, renameLayer{layerId,name}, " +
+        "setLayerEnabled{layerId,enabled?}, toggleSolo{layerId}, selectLayer{layerId}, " +
+        "resetLayer{layerId}, applyLayout{preset}, randomizeLayer{layerId}; " +
+        "addLayerFx{layerId,fxType,params?,beforeFxId?}, removeLayerFx{layerId,fxId}, " +
+        "removeAllLayerFx{layerId}, setLayerFxParam{layerId,fxId,param,value|params}, " +
+        "setLayerFxEnabled{layerId,fxId,enabled?}, reorderLayerFx{layerId,fxIds}, " +
+        "resetLayerFx{layerId,fxId}; bind{layerId,fxId?,paramKey,source,...}, " +
+        "unbind{layerId,fxId?,paramKey}, setBindingField{layerId,fxId?,paramKey,field,value}, " +
+        "fireImpulse{layerId,fxId?,paramKey}, removeBindingsForLayer{layerId}, clearBindings; " +
+        "addOutputFx{fxId}, removeOutputFx{instanceId}, setOutputFxParam{instanceId|fxId,param,value}, " +
+        "setOutputFxEnabled{instanceId,enabled}, setOutputFxStrength{instanceId,strength}; " +
+        "addModRoute{route}, removeModRoute{id}, updateModRoute{id,updates}, clearModRoutes, " +
+        "setModEnabled{enabled}; setModel{sourcePath?,visible?,blendMode?,audioReactive?,autoRotate?,transform?}, " +
+        "resetModel; setSettings{...}, setActiveCell{cellId}, resetWorkspace. " +
+        "Layer fx target a per-layer chain; output fx target the global chain (ids differ). " +
+        VIDEO_BIND_SOURCES,
+    inputSchema: {
+        command: z
+            .record(z.string(), z.any())
+            .describe("The command object. Must include a string `op` field."),
+    },
+}, async ({ command }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await sendVideoCommand(command);
+    return json(result);
+});
+server.registerTool("add_video_layer", {
+    title: "Add Video Layer",
+    description: "Add a layer to the VX scene and return its id. Kinds: video, image, camera, " +
+        "text, drawing, model3d, adjustment (adjustment = full-canvas FX only; master is a " +
+        "managed singleton and cannot be added). After adding, set its source/props with " +
+        "update_video_layer and stack FX with add_video_fx.",
+    inputSchema: {
+        kind: z
+            .enum(["video", "image", "camera", "text", "drawing", "model3d", "adjustment"])
+            .describe("Layer kind."),
+        name: z.string().optional().describe("Display name (auto-generated if omitted)."),
+        insertAt: z
+            .number()
+            .int()
+            .optional()
+            .describe("Data-index to insert at (default: top of stack)."),
+    },
+}, async ({ kind, name, insertAt }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const before = await getVideoStateRaw();
+    const beforeIds = new Set((before.layers ?? []).map((l) => l.id));
+    await sendVideoCommand({ op: "addLayer", kind, name, insertAt });
+    const id = await resolveNewId(beforeIds, (s) => (s.layers ?? []).map((l) => l.id));
+    return text(id
+        ? `Added ${kind} layer: ${id}`
+        : `Added ${kind} layer (window may be closed; call get_video_state to confirm).`);
+});
+server.registerTool("update_video_layer", {
+    title: "Update Video Layer",
+    description: "Update a layer's common props and/or kind-specific fields. transform is merged " +
+        "(partial) against the current transform; other fields replace. Common: opacity " +
+        "(0..1), blendMode (normal|add|multiply|screen), enabled, name, transform " +
+        "{x,y(0..1),scale,rotation(rad),anchor}. Kind-specific via `fields`: text layers " +
+        "{text,fontSize,fontWeight,color,align,lineHeight}; image/video/model3d {sourcePath,fit}; " +
+        "camera {deviceId,mirror,fit}; drawing {paintColor,paintWidth}; model3d " +
+        "{lightingMode,lightIntensity,rotateRateX/Y/Z,...}. Use get_video_state to see a " +
+        "layer's current fields.",
+    inputSchema: {
+        layerId: z.string().describe("Target layer id (from get_video_state)."),
+        opacity: z.number().min(0).max(1).optional(),
+        blendMode: z.enum(["normal", "add", "multiply", "screen"]).optional(),
+        enabled: z.boolean().optional(),
+        name: z.string().optional(),
+        transform: z
+            .record(z.string(), z.any())
+            .optional()
+            .describe("Partial transform: {x?,y?,scale?,rotation?,anchor?}. Merged."),
+        fields: z
+            .record(z.string(), z.any())
+            .optional()
+            .describe("Kind-specific fields (text, sourcePath, fit, fontSize, color, …)."),
+    },
+}, async ({ layerId, opacity, blendMode, enabled, name, transform, fields }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const patch = { ...(fields ?? {}) };
+    if (opacity !== undefined)
+        patch.opacity = opacity;
+    if (blendMode !== undefined)
+        patch.blendMode = blendMode;
+    if (enabled !== undefined)
+        patch.enabled = enabled;
+    if (name !== undefined)
+        patch.name = name;
+    if (transform !== undefined)
+        patch.transform = transform;
+    const result = await sendVideoCommand({ op: "updateLayer", layerId, patch });
+    return json(result);
+});
+server.registerTool("remove_video_layer", {
+    title: "Remove Video Layer",
+    description: "Remove a layer (and its FX + bindings). The master layer cannot be removed.",
+    inputSchema: { layerId: z.string().describe("Layer id to remove.") },
+    annotations: { destructiveHint: true },
+}, async ({ layerId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await sendVideoCommand({ op: "removeLayer", layerId });
+    return json(result);
+});
+server.registerTool("apply_video_layout", {
+    title: "Apply Video Layout",
+    description: "Arrange the spatial layers with a layout preset: centered (stacked), grid, " +
+        "columns, rows, or focus (one large + thumbnail strip). adjustment and master " +
+        "layers are untouched.",
+    inputSchema: {
+        preset: z.enum(["centered", "grid", "columns", "rows", "focus"]).describe("Layout preset."),
+    },
+}, async ({ preset }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await sendVideoCommand({ op: "applyLayout", preset });
+    return json(result);
+});
+server.registerTool("add_video_fx", {
+    title: "Add Video FX",
+    description: "Append an FX to a layer's chain (target='layer', needs layerId) or to the output/" +
+        "global chain (target='output'), and return the new id. Per-layer FX: " +
+        VIDEO_LAYER_FX +
+        ". Output FX: " +
+        VIDEO_OUTPUT_FX +
+        ". FX params seed from registry defaults; override via `params`. Use set_video_fx " +
+        "to tweak afterwards.",
+    inputSchema: {
+        target: z.enum(["layer", "output"]).default("layer").describe("Which chain."),
+        layerId: z.string().optional().describe("Required when target='layer'."),
+        fxType: z.string().describe("FX id (see the per-layer / output id lists)."),
+        params: z
+            .record(z.string(), z.number())
+            .optional()
+            .describe("Optional initial param overrides {paramKey: value}."),
+        beforeFxId: z
+            .string()
+            .optional()
+            .describe("Insert before this fx id instead of appending (layer target only)."),
+    },
+}, async ({ target, layerId, fxType, params, beforeFxId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (target === "output") {
+        const before = await getVideoStateRaw();
+        const beforeIds = new Set((before.outputFx ?? []).map((f) => f.instanceId));
+        await sendVideoCommand({ op: "addOutputFx", fxId: fxType });
+        const id = await resolveNewId(beforeIds, (s) => (s.outputFx ?? []).map((f) => f.instanceId));
+        // Apply param overrides now that the instance exists.
+        if (params && id)
+            for (const [param, value] of Object.entries(params))
+                await sendVideoCommand({ op: "setOutputFxParam", instanceId: id, param, value });
+        return text(id ? `Added output FX ${fxType}: ${id}` : `Added output FX ${fxType} (confirm via get_video_state).`);
+    }
+    if (!layerId)
+        return error("add_video_fx: layerId is required when target='layer'.");
+    const before = await getVideoStateRaw();
+    const layer = (before.layers ?? []).find((l) => l.id === layerId);
+    const beforeIds = new Set((layer?.fx ?? []).map((f) => f.id));
+    await sendVideoCommand({ op: "addLayerFx", layerId, fxType, params, beforeFxId });
+    const id = await resolveNewId(beforeIds, (s) => {
+        const l = (s.layers ?? []).find((x) => x.id === layerId);
+        return (l?.fx ?? []).map((f) => f.id);
+    });
+    return text(id ? `Added ${fxType} to layer ${layerId}: ${id}` : `Added ${fxType} (confirm via get_video_state).`);
+});
+server.registerTool("set_video_fx", {
+    title: "Set Video FX",
+    description: "Set FX params / enabled / strength on a per-layer FX (target='layer', needs " +
+        "layerId + fxId) or an output FX (target='output', needs instanceId, or fxId to " +
+        "auto-create). Pass a single {param,value}, multiple {params}, `enabled`, and/or " +
+        "`strength` (output only). Get current ids/params from get_video_state.",
+    inputSchema: {
+        target: z.enum(["layer", "output"]).default("layer"),
+        layerId: z.string().optional().describe("target='layer': owning layer id."),
+        fxId: z.string().optional().describe("Layer fx id, or output fxId (auto-creates the output fx)."),
+        instanceId: z.string().optional().describe("target='output': the output fx instance id."),
+        param: z.string().optional().describe("Single param key to set."),
+        value: z.number().optional().describe("Value for `param`."),
+        params: z.record(z.string(), z.number()).optional().describe("Multiple params {key: value}."),
+        enabled: z.boolean().optional().describe("Enable/bypass this FX."),
+        strength: z.number().optional().describe("Output FX wet strength (output target only)."),
+    },
+}, async ({ target, layerId, fxId, instanceId, param, value, params, enabled, strength }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const results = [];
+    if (target === "layer") {
+        if (!layerId || !fxId)
+            return error("set_video_fx: layerId and fxId required for target='layer'.");
+        if (param !== undefined && value !== undefined)
+            results.push(await sendVideoCommand({ op: "setLayerFxParam", layerId, fxId, param, value }));
+        if (params)
+            results.push(await sendVideoCommand({ op: "setLayerFxParam", layerId, fxId, params }));
+        if (enabled !== undefined)
+            results.push(await sendVideoCommand({ op: "setLayerFxEnabled", layerId, fxId, enabled }));
+    }
+    else {
+        if (param !== undefined && value !== undefined)
+            results.push(await sendVideoCommand({ op: "setOutputFxParam", instanceId, fxId, param, value }));
+        if (params)
+            for (const [p, v] of Object.entries(params))
+                results.push(await sendVideoCommand({ op: "setOutputFxParam", instanceId, fxId, param: p, value: v }));
+        if (enabled !== undefined && instanceId)
+            results.push(await sendVideoCommand({ op: "setOutputFxEnabled", instanceId, enabled }));
+        if (strength !== undefined && instanceId)
+            results.push(await sendVideoCommand({ op: "setOutputFxStrength", instanceId, strength }));
+    }
+    if (results.length === 0)
+        return error("set_video_fx: nothing to set (provide param/value, params, enabled, or strength).");
+    return json({ applied: results.length });
+});
+server.registerTool("remove_video_fx", {
+    title: "Remove Video FX",
+    description: "Remove an FX from a layer chain (target='layer' + layerId + fxId) or the output " +
+        "chain (target='output' + instanceId).",
+    inputSchema: {
+        target: z.enum(["layer", "output"]).default("layer"),
+        layerId: z.string().optional(),
+        fxId: z.string().optional().describe("target='layer': fx id on the layer."),
+        instanceId: z.string().optional().describe("target='output': output fx instance id."),
+    },
+    annotations: { destructiveHint: true },
+}, async ({ target, layerId, fxId, instanceId }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (target === "layer") {
+        if (!layerId || !fxId)
+            return error("remove_video_fx: layerId and fxId required for target='layer'.");
+        return json(await sendVideoCommand({ op: "removeLayerFx", layerId, fxId }));
+    }
+    if (!instanceId)
+        return error("remove_video_fx: instanceId required for target='output'.");
+    return json(await sendVideoCommand({ op: "removeOutputFx", instanceId }));
+});
+server.registerTool("bind_video_param", {
+    title: "Bind Video Param (audio-reactive)",
+    description: "Bind a per-layer FX param or layer field to an audio/transport source so it reacts " +
+        "to the music. Omit fxId (or pass '') to target a layer field: transform.x, " +
+        "transform.y, transform.scale, transform.rotation, opacity, hue, brightness, " +
+        "contrast, saturation, playbackRate, fontSize, pulseAmount, or model3d fields. " +
+        "Pass fxId to target an FX param (param key from that FX). " +
+        VIDEO_BIND_SOURCES +
+        " amount is -1..1; curve linear|exp|expInverse|bipolar; mode additive|replace|" +
+        "multiply|centered; impulse off|pulse|latch (one-shot on threshold crossing). " +
+        "attack/release default per-source if omitted.",
+    inputSchema: {
+        layerId: z.string().describe("Target layer id."),
+        paramKey: z.string().describe("FX param key, or layer field (e.g. transform.scale, opacity)."),
+        source: z
+            .union([z.string(), z.record(z.string(), z.any())])
+            .describe("sourceKey string (e.g. 'g:bandLow', 'c:1:onset', 't:beat') or ModSource object."),
+        fxId: z.string().optional().describe("FX instance id; omit/'' for a layer-field target."),
+        amount: z.number().min(-1).max(1).optional().describe("Modulation depth (-1..1), default 1."),
+        curve: z.enum(["linear", "exp", "expInverse", "bipolar"]).optional(),
+        mode: z.enum(["additive", "replace", "multiply", "centered"]).optional(),
+        attackMs: z.number().min(0).optional(),
+        releaseMs: z.number().min(0).optional(),
+        threshold: z.number().min(0).max(1).optional().describe("Gate / impulse trigger level."),
+        impulse: z.enum(["off", "pulse", "latch"]).optional(),
+    },
+}, async ({ layerId, paramKey, source, fxId, amount, curve, mode, attackMs, releaseMs, threshold, impulse }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await sendVideoCommand({
+        op: "bind",
+        layerId,
+        fxId: fxId ?? "",
+        paramKey,
+        source,
+        amount,
+        curve,
+        mode,
+        attackMs,
+        releaseMs,
+        threshold,
+        impulse,
+    });
+    return json(result);
+});
+server.registerTool("set_video_settings", {
+    title: "Set Video Settings",
+    description: "Set global VX render/sync settings: syncMode (off|beat-sync|beat-match), loopBars, " +
+        "aspectRatio (auto|16:9|4:3|1:1|stretch), renderQuality (low|medium|high), " +
+        "designAspect (w/h number or null), letterboxColor / canvasColor (#hex), the active " +
+        "video cell (cellId), and the mod-matrix master enable. resetWorkspace clears the " +
+        "scene (preserves the master layer).",
+    inputSchema: {
+        syncMode: z.enum(["off", "beat-sync", "beat-match"]).optional(),
+        loopBars: z.number().optional(),
+        aspectRatio: z.enum(["auto", "16:9", "4:3", "1:1", "stretch"]).optional(),
+        renderQuality: z.enum(["low", "medium", "high"]).optional(),
+        designAspect: z.number().nullable().optional(),
+        letterboxColor: z.string().optional(),
+        canvasColor: z.string().optional(),
+        modEnabled: z.boolean().optional().describe("Mod-matrix master enable."),
+        activeCell: z.number().int().optional().describe("Switch the active per-cell video slice."),
+        resetWorkspace: z.boolean().optional().describe("If true, clear the whole scene first."),
+    },
+}, async ({ syncMode, loopBars, aspectRatio, renderQuality, designAspect, letterboxColor, canvasColor, modEnabled, activeCell, resetWorkspace }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (resetWorkspace)
+        await sendVideoCommand({ op: "resetWorkspace" });
+    if (activeCell !== undefined)
+        await sendVideoCommand({ op: "setActiveCell", cellId: activeCell });
+    if (modEnabled !== undefined)
+        await sendVideoCommand({ op: "setModEnabled", enabled: modEnabled });
+    const settings = {};
+    if (syncMode !== undefined)
+        settings.syncMode = syncMode;
+    if (loopBars !== undefined)
+        settings.loopBars = loopBars;
+    if (aspectRatio !== undefined)
+        settings.aspectRatio = aspectRatio;
+    if (renderQuality !== undefined)
+        settings.renderQuality = renderQuality;
+    if (designAspect !== undefined)
+        settings.designAspect = designAspect;
+    if (letterboxColor !== undefined)
+        settings.letterboxColor = letterboxColor;
+    if (canvasColor !== undefined)
+        settings.canvasColor = canvasColor;
+    if (Object.keys(settings).length > 0)
+        await sendVideoCommand({ op: "setSettings", ...settings });
+    return text("Video settings updated.");
+});
+// ============================================================
 // Composite cell-operation tools
 // ============================================================
 const PATTERN_SUFFIXES = [
@@ -1628,15 +2428,21 @@ server.registerTool("update_cell_config", {
 });
 server.registerTool("set_master_effects", {
     title: "Set Master Effects",
-    description: "Configure the master bus Punch compressor and Limiter. " +
+    description: "Configure the master bus Punch compressor, Limiter, and Tape colour. " +
         "The Punch compressor is a musical bus compressor — use it for glue and pump. " +
         "The Limiter is a 3-stage brick-wall limiter with tanh saturation. " +
-        "Pass enabled flags to toggle them on/off. Pass compressor parameters to shape the sound. " +
+        "The Tape is a vintage-tape coloration stage (ADAA tanh/asymmetric saturation + HF compression + wow/flutter), " +
+        "the single biggest lever for lo-fi / dusty / 'pushed' master character (hip-hop, lo-fi, Memphis, dub). " +
+        "Pass enabled flags to toggle each on/off. Pass parameters to shape the sound. " +
         "For pumpy beats: enable punch, set threshold around -18 to -12 dB, fast attack (0.1-0.5ms), " +
-        "medium release (80-200ms), ratio 4-8, autoMakeup true.",
+        "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 (manifest key masterTapeEnabled). 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)."),
+        tapeEnabled: z.union([z.literal(0), z.literal(1)]).optional().describe("Enable master Tape colour/saturation (0=off, 1=on)."),
         masterCompThreshold: z.number().min(-60).max(0).optional().describe("Compressor threshold in dB (default -24)."),
         masterCompRatio: z.number().min(1).max(20).optional().describe("Compressor ratio (default 4)."),
         masterCompAttack: z.number().min(0.01).max(100).optional().describe("Attack in ms (default 0.2)."),
@@ -1647,8 +2453,13 @@ server.registerTool("set_master_effects", {
         masterCompCeiling: z.number().min(-6).max(0).optional().describe("Output ceiling in dB (default -0.05)."),
         masterCompInputGain: z.number().min(-24).max(24).optional().describe("Input gain in dB (default 0)."),
         masterCompKnee: z.number().min(0).max(30).optional().describe("Knee width in dB (default 0)."),
+        masterTapeDrive: z.number().min(0).max(1).optional().describe("Tape drive / saturation amount (0-1, default 0.5). Higher = more harmonic grit + HF compression ('push it harder → it gets duller')."),
+        masterTapeTone: z.number().min(-1).max(1).optional().describe("Tape tone tilt (-1 dark .. 0 flat .. +1 bright, default 0). Go negative for dusty/lo-fi."),
+        masterTapeMix: z.number().min(0).max(1).optional().describe("Tape dry/wet (0-1, default 1 = fully wet)."),
+        masterTapeMode: z.union([z.literal(0), z.literal(1), z.literal(2)]).optional().describe("Tape character: 0=Clean (gentle tanh), 1=Lo-Fi (most degradation, dusty), 2=Amp (hard asymmetric drive). Default 0."),
+        masterTapeWear: z.number().min(0).max(1).optional().describe("Tape wear: wow/flutter pitch drift + age (0-1, default 0.5). Raise for warble/sag."),
     },
-}, async ({ compressorEnabled, limiterEnabled, ...compParams }) => {
+}, async ({ compressorEnabled, limiterEnabled, tapeEnabled, ...effectParams }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
@@ -1658,8 +2469,11 @@ server.registerTool("set_master_effects", {
         delta.masterCompressorEnabled = compressorEnabled;
     if (limiterEnabled !== undefined)
         delta.masterLimiterEnabled = limiterEnabled;
-    // Compressor parameters are flat state keys read by the DSP graph
-    for (const [key, value] of Object.entries(compParams)) {
+    if (tapeEnabled !== undefined)
+        delta.masterTapeEnabled = tapeEnabled;
+    // Compressor + tape parameters are already the flat state keys read by the
+    // DSP graph / native master node (masterComp*, masterTape*). Pass through.
+    for (const [key, value] of Object.entries(effectParams)) {
         if (value !== undefined)
             delta[key] = value;
     }
@@ -1673,6 +2487,83 @@ server.registerTool("set_master_effects", {
         .join(", ");
     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)];
+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 " +
+        "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. " +
+        "On builds without it, the cell{N}_synthEngine state key is ignored.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        engine: z.enum(DRUM_SYNTH_ENGINE_NAMES).describe("Engine name. 'Off' disables the synth voice (sample-only cell)."),
+        volume: z.number().min(-60).max(12).optional().describe("Synth output level in dB (default 0)."),
+        p1: z.number().min(0).max(1).optional().describe("Param 1 (engine-specific; usually Tune). Overrides the engine default."),
+        p2: z.number().min(0).max(1).optional().describe("Param 2 (engine-specific)."),
+        p3: z.number().min(0).max(1).optional().describe("Param 3 (engine-specific)."),
+        p4: z.number().min(0).max(1).optional().describe("Param 4 (engine-specific)."),
+        p5: z.number().min(0).max(1).optional().describe("Param 5 (engine-specific)."),
+        p6: z.number().min(0).max(1).optional().describe("Param 6 (engine-specific)."),
+        p7: z.number().min(0).max(1).optional().describe("Param 7 (engine-specific)."),
+        p8: z.number().min(0).max(1).optional().describe("Param 8 (engine-specific)."),
+    },
+}, async ({ cellId, engine, volume, ...overrides }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    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;
+        });
+        for (const [key, value] of Object.entries(overrides)) {
+            if (value === undefined)
+                continue;
+            const idx = Number(key.slice(1)); // p3 -> 3
+            if (idx >= 1 && idx <= desc.params.length)
+                delta[`cell${cellId}_synth_p${idx}`] = value;
+        }
+    }
+    if (volume !== undefined)
+        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(",") : "—";
+    return text(`Cell ${cellId} drum synth → ${engine}${engineId > 0 ? ` (p1..pN = ${labels})` : ""}.`);
+});
 server.registerTool("add_param_seq", {
     title: "Add Parameter Sequencer",
     description: "Add a parameter sequencer (step modulation) targeting any modulatable parameter. " +
@@ -1780,56 +2671,129 @@ server.registerTool("normalize_sample", {
     await bridge.send("normalizeSampleForCell", cellId);
     return text(`Normalized sample in cell ${cellId}.`);
 });
+server.registerTool("gain_sample", {
+    title: "Gain Sample",
+    description: "Apply a gain in decibels to a cell's sample and render it into a new file (offline, destructive). " +
+        "Positive values make it louder, negative quieter; boosting past 0 dBFS clips. The original library file is left unchanged, so the edit can be undone by reloading the source sample.",
+    inputSchema: {
+        cellId: z.number().min(1).max(8).describe("Cell number (1-8)."),
+        gainDb: z
+            .number()
+            .min(-96)
+            .max(48)
+            .describe("Gain in decibels (e.g. 3 = +3 dB louder, -6 = 6 dB quieter)."),
+    },
+}, async ({ cellId, gainDb }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("gainSampleForCell", { cellId, gainDb });
+    return text(`Applied ${gainDb > 0 ? "+" : ""}${gainDb} dB to the sample in cell ${cellId}.`);
+});
+// Poll the offline-render status flag until the export completes or times out.
+async function pollExportStatus(maxWaitMs = 180_000, pollMs = 500) {
+    const t0 = Date.now();
+    while (Date.now() - t0 < maxWaitMs) {
+        await new Promise((r) => setTimeout(r, pollMs));
+        const status = (await bridge.send("getExportStatus"));
+        if (status.complete)
+            return status.success ? "success" : "failed";
+    }
+    return "timeout";
+}
 server.registerTool("export_audio", {
     title: "Export Audio",
-    description: "Render and export audio from the current preset to a WAV file. " +
-        "Uses the current BPM to calculate duration. Waits for completion and returns the output file path. " +
-        "Use get_audio_info afterwards to analyze the exported file.",
+    description: "Render and export audio from the current preset to a WAV file in PAM's Exports folder. " +
+        "Waits for completion. Default mode renders the looping preset for `bars` bars at the current BPM. " +
+        "Set `mode` to bounce stems or the whole Song Mode arrangement.\n\n" +
+        "Modes: 'main' (full mix, default) · 'individual' (one cell solo, needs cellId) · " +
+        "'all-cells' / 'selected-cells' (per-cell stems, the latter needs selectedCellIds) · " +
+        "'per-bus' (per output bus) · 'song-mode' (the Song Mode timeline).\n\n" +
+        "NOTE on 'song-mode': the OFFLINE bounce only renders the arrangement's FIRST section's live state — " +
+        "variation/preset switches are not applied offline (the message thread is blocked during render). " +
+        "For a true full track that captures every section change, use the `export_song` tool (live capture).",
     inputSchema: {
-        bars: z.number().min(1).max(128).default(4).describe("Number of bars to render."),
+        bars: z.number().min(1).max(128).default(4).describe("Bars to render (ignored for 'song-mode', which derives length from the timeline)."),
         cellId: z
             .number()
             .min(1)
             .max(8)
             .optional()
-            .describe("Render only a specific cell in solo. Omit for full mix."),
+            .describe("Render only a specific cell in solo (implies mode 'individual'). Omit for full mix."),
+        mode: z
+            .enum(["main", "individual", "all-cells", "selected-cells", "per-bus", "song-mode"])
+            .optional()
+            .describe("Export mode. Defaults to 'main' (or 'individual' when cellId is set)."),
+        selectedCellIds: z
+            .array(z.number().min(1).max(8))
+            .optional()
+            .describe("For mode 'selected-cells': cells to bounce as stems."),
         bitDepth: z
             .number()
             .default(24)
             .describe("Bit depth (16 or 24)."),
     },
-}, async ({ bars, cellId, bitDepth }) => {
+}, async ({ bars, cellId, mode, selectedCellIds, bitDepth }) => {
     const check = await requireBridge();
     if (check !== true)
         return check;
-    const options = { bars, bitDepth };
-    if (cellId)
-        options.cellId = cellId;
-    const startResult = await bridge.send("exportAudio", options);
-    // If bridge returned old-style "ok", it was a pass-through with full options
-    if (typeof startResult === "string") {
-        return text(`Audio export started (${bars} bars, ${bitDepth}-bit).`);
-    }
-    const result = startResult;
-    const outputPath = result.outputPath;
-    const durationSecs = result.durationInSeconds;
-    const bpm = result.bpm;
-    // Poll for completion
-    const maxWaitMs = 120_000;
-    const pollMs = 500;
-    const t0 = Date.now();
-    while (Date.now() - t0 < maxWaitMs) {
-        await new Promise((r) => setTimeout(r, pollMs));
-        const status = (await bridge.send("getExportStatus"));
-        if (status.complete) {
-            if (status.success) {
-                return text(`Audio exported successfully.\nFile: ${outputPath}\n` +
-                    `Duration: ${durationSecs.toFixed(1)}s (${bars} bars at ${bpm} BPM, ${bitDepth}-bit)`);
-            }
-            return error(`Audio export failed.`);
+    // Resolve the effective mode. A bare cellId means "individual".
+    const effectiveMode = mode ?? (cellId ? "individual" : "main");
+    // Fast path: main / individual go through the MCP-friendly bridge branch,
+    // which constructs options server-side and returns the output path + duration.
+    if (effectiveMode === "main" || (effectiveMode === "individual" && cellId)) {
+        const options = { bars, bitDepth };
+        if (cellId)
+            options.cellId = cellId;
+        const startResult = await bridge.send("exportAudio", options);
+        if (typeof startResult === "string") {
+            return text(`Audio export started (${bars} bars, ${bitDepth}-bit).`);
         }
+        const result = startResult;
+        const outputPath = result.outputPath;
+        const durationSecs = result.durationInSeconds;
+        const bpm = result.bpm;
+        const outcome = await pollExportStatus();
+        if (outcome === "success")
+            return text(`Audio exported successfully.\nFile: ${outputPath}\n` +
+                `Duration: ${durationSecs.toFixed(1)}s (${bars} bars at ${bpm} BPM, ${bitDepth}-bit)`);
+        if (outcome === "failed")
+            return error("Audio export failed.");
+        return text(`Export timed out. The render may still be running.\nExpected output: ${outputPath}`);
     }
-    return text(`Export timed out after ${maxWaitMs / 1000}s. The render may still be running.\nExpected output: ${outputPath}`);
+    // Stem / song-mode modes: build full pass-through options (filename + mode +
+    // durationInSeconds) so the C++ export handler runs the requested mode directly.
+    if (effectiveMode === "selected-cells" && (!selectedCellIds || selectedCellIds.length === 0))
+        return error("mode 'selected-cells' requires selectedCellIds.");
+    if (effectiveMode === "individual" && !cellId)
+        return error("mode 'individual' requires cellId.");
+    const transport = (await bridge.send("getTransport"));
+    const bpm = typeof transport.bpm === "number" && transport.bpm > 0 ? transport.bpm : 120;
+    // 4/4 assumption for the placeholder duration; 'song-mode' recomputes its own length from the timeline.
+    const durationInSeconds = (bars * 4 * 60) / bpm;
+    const filename = `pam_export_${effectiveMode.replace(/[^a-z0-9]/gi, "_")}_${Date.now()}`;
+    const options = {
+        filename,
+        mode: effectiveMode,
+        durationInSeconds,
+        bitDepth,
+    };
+    if (cellId)
+        options.selectedCellId = cellId;
+    if (selectedCellIds)
+        options.selectedCellIds = selectedCellIds;
+    await bridge.send("exportAudio", options);
+    const outcome = await pollExportStatus();
+    if (outcome === "success")
+        return text(`Export complete (mode '${effectiveMode}').\n` +
+            `File(s) written to PAM's Exports folder, base name: ${filename}.wav` +
+            (effectiveMode === "song-mode"
+                ? "\n\nReminder: the offline song-mode bounce captures only the first section's state. " +
+                    "Use export_song for a full track with section changes."
+                : ""));
+    if (outcome === "failed")
+        return error(`Export failed (mode '${effectiveMode}').`);
+    return text(`Export timed out (mode '${effectiveMode}'). The render may still be running.`);
 });
 // ============================================================
 // RESOURCES
@@ -2922,6 +3886,99 @@ server.registerTool("song_mode", {
     }
     return text("No-op");
 });
+server.registerTool("export_song", {
+    title: "Export Song (Full Track)",
+    description: "Bounce the full Song Mode arrangement to a single WAV — the 'render my whole track' button. " +
+        "Set up the arrangement first with the `song_mode` tool (setSequence), then call this.\n\n" +
+        "Two strategies:\n" +
+        "• 'live' (DEFAULT, full fidelity): plays the arrangement in real time and captures the master mix, " +
+        "so EVERY section/variation/preset change and all modulation is rendered. Needs a free `cellId` to " +
+        "land the captured clip in (use an empty cell). Capture is capped at 64 bars; for longer songs bounce " +
+        "in sections or raise the cap. The captured WAV also lands in PAM's Resamples folder.\n" +
+        "• 'offline' (fast, LIMITED): renders via the offline song-mode bounce. Only the first section's state " +
+        "is rendered (variation/preset switches are NOT applied offline). Use only for single-section sketches.\n\n" +
+        "After a 'live' bounce, the captured file path is read back from the destination cell; run get_audio_info " +
+        "(resolve against the Resamples location from get_default_locations) to verify it.",
+    inputSchema: {
+        strategy: z.enum(["live", "offline"]).default("live").describe("Capture strategy."),
+        bars: z
+            .number()
+            .min(1)
+            .max(64)
+            .describe("Total arrangement length in bars (the full timeline). Required for 'live'."),
+        cellId: z
+            .number()
+            .min(1)
+            .max(8)
+            .optional()
+            .describe("For 'live': empty destination cell the bounced master clip is written into."),
+        bitDepth: z.number().default(24).describe("Bit depth (16 or 24)."),
+        tailBars: z
+            .number()
+            .min(0)
+            .max(8)
+            .default(1)
+            .describe("For 'live': extra bars captured after the arrangement end for reverb/release tails."),
+    },
+}, async ({ strategy, bars, cellId, bitDepth, tailBars }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    // -------- Offline strategy: reuse the song-mode bounce (first-section only) --------
+    if (strategy === "offline") {
+        const filename = `pam_song_${Date.now()}`;
+        const transport = (await bridge.send("getTransport"));
+        const bpm = typeof transport.bpm === "number" && transport.bpm > 0 ? transport.bpm : 120;
+        await bridge.send("exportAudio", {
+            filename,
+            mode: "song-mode",
+            durationInSeconds: (bars * 4 * 60) / bpm,
+            bitDepth,
+        });
+        const outcome = await pollExportStatus();
+        if (outcome === "success")
+            return text(`Offline song bounce complete: ${filename}.wav (in PAM's Exports folder).\n` +
+                "Note: only the first section's state was rendered. Use strategy 'live' for the full track.");
+        if (outcome === "failed")
+            return error("Offline song bounce failed. Is Song Mode enabled with a non-empty sequence?");
+        return text("Offline song bounce timed out. The render may still be running.");
+    }
+    // -------- Live strategy: real-time master capture of the whole arrangement --------
+    if (typeof cellId !== "number")
+        return error("'live' strategy requires an empty destination cellId.");
+    const transport = (await bridge.send("getTransport"));
+    const bpm = typeof transport.bpm === "number" && transport.bpm > 0 ? transport.bpm : 120;
+    const totalBars = bars + (tailBars ?? 1);
+    if (totalBars > 64)
+        return error(`Total capture (${totalBars} bars incl. tail) exceeds the 64-bar live cap. Bounce in sections.`);
+    const captureSeconds = (totalBars * 4 * 60) / bpm;
+    // Reset playhead to the top so the arrangement starts at section 1, enable Song
+    // Mode, then roll the transport and capture the full master mix.
+    await bridge.send("fullStopTransport");
+    await bridge.send("toggleSongMode", true);
+    await bridge.send("setSongModePlayhead", 0);
+    await bridge.send("startTransport");
+    await bridge.send("resampleGraphToCell", JSON.stringify({ cellId, bars: totalBars, live: true, captureSource: 2, cellOnly: false }));
+    // Wait out the arrangement (plus a small safety margin), then stop + finalize.
+    await new Promise((r) => setTimeout(r, captureSeconds * 1000 + 1500));
+    await bridge.send("stopLiveResample", true);
+    await bridge.send("stopTransport");
+    // Read the captured clip path back off the destination cell.
+    let capturedPath = "(unknown — check PAM's Resamples folder)";
+    try {
+        const state = (await bridge.send("getState"));
+        const cells = state.cells;
+        const fp = cells?.[String(cellId)]?.filePath;
+        if (typeof fp === "string" && fp.length > 0)
+            capturedPath = fp;
+    }
+    catch {
+        // fall through with the placeholder
+    }
+    return text(`Live song bounce complete (${bars} bars + ${tailBars ?? 1} tail @ ${bpm} BPM, ${bitDepth}-bit).\n` +
+        `Captured into cell ${cellId}.\nClip: ${capturedPath}\n` +
+        "Resolve the absolute path against the Resamples location from get_default_locations, then verify with get_audio_info.");
+});
 // ============================================================
 // TOOLS — Metronome
 // ============================================================
@@ -3086,8 +4143,12 @@ server.registerTool("export_slice", {
 // ============================================================
 server.registerTool("live_resample", {
     title: "Live Resample",
-    description: "Capture PAM's audio graph output into a cell as a new sample. Ops: 'start' / 'stop'. " +
-        "Transport must be playing for the capture to produce audio.",
+    description: "Capture PAM's audio graph output into a cell as a new sample, in real time. Ops: 'start' / 'stop'. " +
+        "Transport MUST be playing for the capture to produce audio. Because the capture runs live, " +
+        "Song Mode section changes, modulation, and variation switches are all captured faithfully — " +
+        "this is the building block for full-track / Song Mode bounces (see export_song).\n\n" +
+        "`source` selects what to record: 'cell' (the destination cell's own output), 'input' (PAM's audio input), " +
+        "or 'fullmix' (the whole master mix — use this to bounce the entire arrangement).",
     inputSchema: {
         op: z.enum(["start", "stop"]).describe("Operation."),
         cellId: z
@@ -3095,13 +4156,21 @@ server.registerTool("live_resample", {
             .min(1)
             .max(8)
             .optional()
-            .describe("For 'start': destination cell."),
+            .describe("For 'start': destination cell the captured clip lands in. Use an empty/scratch cell for a full-mix bounce."),
         bars: z
             .number()
             .min(0.125)
             .max(64)
             .optional()
-            .describe("For 'start': capture length in bars."),
+            .describe("For 'start': capture length in bars (max 64; the capture also stops on the 'stop' op)."),
+        source: z
+            .enum(["cell", "input", "fullmix"])
+            .default("cell")
+            .describe("For 'start': capture source. 'fullmix' records the entire master output (the whole song)."),
+        normalize: z
+            .boolean()
+            .default(false)
+            .describe("For 'start': peak-normalize the captured clip after recording."),
         finalize: z
             .boolean()
             .default(true)
@@ -3114,13 +4183,578 @@ server.registerTool("live_resample", {
     if (args.op === "start") {
         if (typeof args.cellId !== "number" || typeof args.bars !== "number")
             return error("'start' requires cellId + bars");
-        await bridge.send("resampleGraphToCell", JSON.stringify({ cellId: args.cellId, bars: args.bars }));
-        return text(`Started live resample → cell ${args.cellId} (${args.bars} bars).`);
+        const source = args.source ?? "cell";
+        const captureSource = source === "fullmix" ? 2 : source === "input" ? 1 : 0;
+        await bridge.send("resampleGraphToCell", JSON.stringify({
+            cellId: args.cellId,
+            bars: args.bars,
+            live: true,
+            captureSource,
+            // For a full-mix / input bounce the destination cell must NOT be soloed,
+            // or we'd only capture that one (empty) cell.
+            cellOnly: source === "cell",
+            normalize: args.normalize ?? false,
+        }));
+        return text(`Started live resample → cell ${args.cellId} (${args.bars} bars, source '${source}').`);
     }
     await bridge.send("stopLiveResample", args.finalize ?? true);
     return text(`Stopped live resample (finalize=${args.finalize ?? true}).`);
 });
 // ============================================================
+// TOOLS — Plugin host (scan/load/unload/param/bypass on hosted VST3/AU/CLAP)
+// Instrument-role only. Effect-side hosting is not exposed via MCP yet
+// (MCPBridge only routes through the instrument manager).
+// ============================================================
+const PLUGIN_FORMAT = z.enum(["VST3", "AudioUnit", "CLAP"]);
+// Whitelist of scan-path roots. Mirrors
+// interface/src/utils/pluginScanPaths.ts (DEFAULT_PATHS_MAC / _WIN).
+// MCP-supplied searchPaths must resolve to entries beneath one of these
+// roots so an agent can't probe ~/.ssh or other sensitive folders.
+function expandHome(p) {
+    if (p.startsWith("~/"))
+        return resolve(process.env.HOME ?? "", p.slice(2));
+    if (p === "~")
+        return process.env.HOME ?? "";
+    return p;
+}
+const PLUGIN_SCAN_PATH_ROOTS = (process.platform === "win32"
+    ? ["C:/Program Files/Common Files/VST3", "C:/Program Files/Common Files/CLAP"]
+    : [
+        "/Library/Audio/Plug-Ins/VST3",
+        "~/Library/Audio/Plug-Ins/VST3",
+        "/Library/Audio/Plug-Ins/Components",
+        "~/Library/Audio/Plug-Ins/Components",
+        "/Library/Audio/Plug-Ins/CLAP",
+        "~/Library/Audio/Plug-Ins/CLAP",
+    ]).map((p) => resolve(expandHome(p)));
+function isPathUnderWhitelist(p) {
+    const abs = resolve(expandHome(p));
+    return PLUGIN_SCAN_PATH_ROOTS.some((root) => abs === root || abs.startsWith(root + "/") || abs.startsWith(root + "\\"));
+}
+// fileOrIdentifier values returned by list_plugins. load_plugin only
+// accepts entries observed here so an agent can't instantiate arbitrary
+// binaries.
+const knownPluginIdentifiers = new Set();
+// Hosted-plugin tools target PAM cells. Cap to the manifest's cell count
+// (falls back to 8 — PAM's shipping max) rather than the C++ slot
+// reservation of 32.
+async function getMaxCellCount() {
+    try {
+        const m = await loadManifest();
+        const cells = m.cells;
+        if (Array.isArray(cells) && cells.length > 0)
+            return cells.length;
+    }
+    catch {
+        // manifest unavailable — use shipping default
+    }
+    return 8;
+}
+async function clampCellId(cellId) {
+    const max = await getMaxCellCount();
+    if (!Number.isInteger(cellId) || cellId < 1 || cellId > max) {
+        return `cellId must be an integer in [1, ${max}]`;
+    }
+    return cellId;
+}
+server.registerTool("list_plugins", {
+    title: "List Plugins",
+    description: "List plugins that have been discovered by PAM's scanner (VST3, AudioUnit, and CLAP). " +
+        "Returns `plugins` (each: name, manufacturer, format, category, fileOrIdentifier, isInstrument, version) " +
+        "and `blocklist` (paths the scanner marked unsafe). " +
+        "Use this before `load_plugin` to find a valid `path` + `format`. " +
+        "If the list is empty, call `scan_plugins` first. " +
+        "Note: PAM's MCP hosts plugins in the per-cell instrument slot only — FX-side hosting is not exposed yet.",
+    inputSchema: {
+        format: PLUGIN_FORMAT.optional().describe("Filter by plugin format."),
+        isInstrument: z.boolean().optional().describe("If true, only instruments; false, only effects."),
+        nameContains: z.string().optional().describe("Case-insensitive substring match on the plugin name."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const filter = {};
+    if (args.format)
+        filter.format = args.format;
+    if (typeof args.isInstrument === "boolean")
+        filter.isInstrument = args.isInstrument;
+    if (args.nameContains)
+        filter.nameContains = args.nameContains;
+    const raw = (await bridge.send("listPlugins", filter));
+    // Record every fileOrIdentifier so load_plugin can validate that the
+    // caller-supplied path was discovered by PAM's own scanner.
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed.plugins)) {
+            for (const p of parsed.plugins) {
+                if (typeof p.fileOrIdentifier === "string") {
+                    knownPluginIdentifiers.add(p.fileOrIdentifier);
+                }
+            }
+        }
+    }
+    catch {
+        // C++ payload not JSON — fall through; load_plugin will reject unknowns.
+    }
+    return text(raw);
+});
+server.registerTool("scan_plugins", {
+    title: "Scan Plugins",
+    description: "Trigger an async scan for VST3, AudioUnit, and CLAP plugins. " +
+        "Returns immediately — poll `get_plugin_scan_status` for progress and call `list_plugins` " +
+        "once `isScanning` is false. Without `searchPaths`, scans default OS plugin folders. " +
+        "Supplied `searchPaths` must live under PAM's approved plugin roots " +
+        "(/Library/Audio/Plug-Ins/{VST3,Components,CLAP} or their ~ equivalents on macOS; " +
+        "C:/Program Files/Common Files/{VST3,CLAP} on Windows).",
+    inputSchema: {
+        searchPaths: z
+            .array(z.string())
+            .optional()
+            .describe("Folders to scan. Must be inside an approved plugin root. " +
+            "Leave empty to use OS defaults (/Library/Audio/Plug-Ins/* on macOS, etc.)."),
+        blocklist: z
+            .array(z.string())
+            .optional()
+            .describe("File paths or identifiers the scanner should skip."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const payload = {};
+    if (args.searchPaths && args.searchPaths.length > 0) {
+        const rejected = args.searchPaths.filter((p) => !isPathUnderWhitelist(p));
+        if (rejected.length > 0) {
+            return error(`Refusing to scan path(s) outside approved plugin roots: ${rejected.join(", ")}. ` +
+                `Allowed roots: ${PLUGIN_SCAN_PATH_ROOTS.join(", ")}.`);
+        }
+        payload.searchPaths = args.searchPaths;
+    }
+    if (args.blocklist)
+        payload.blocklist = args.blocklist;
+    await bridge.send("scanPlugins", payload);
+    return text("Plugin scan started. Poll get_plugin_scan_status until isScanning is false, then call list_plugins.");
+});
+server.registerTool("cancel_plugin_scan", {
+    title: "Cancel Plugin Scan",
+    description: "Cancel the in-flight plugin scan. Safe to call even if no scan is running.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("cancelPluginScan");
+    return text("Cancelled (or no scan was running).");
+});
+server.registerTool("get_plugin_scan_status", {
+    title: "Plugin Scan Status",
+    description: "Read the latest plugin scan progress. Returns `isScanning`, `format`, `currentPath`, " +
+        "`fraction` (0..1), `elapsedMs`, `isStall` (true when the in-flight plugin hasn't returned in 2s), " +
+        "and `updatedAtMs`. Poll while a scan is running.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const raw = (await bridge.send("getPluginScanStatus"));
+    return text(raw);
+});
+server.registerTool("list_loaded_plugins", {
+    title: "List Loaded Plugins",
+    description: "List plugins currently hosted in PAM cells (instrument slot only — FX-side hosting is not exposed). " +
+        "Each entry: cellId, name, manufacturer, format, " +
+        "path, isInstrument, bypassed, and the plugin's full param list (index, name, label, value, defaultValue). " +
+        "Use the param `index` with `set_plugin_param`.",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const raw = (await bridge.send("listLoadedPlugins"));
+    return text(raw);
+});
+server.registerTool("load_plugin", {
+    title: "Load Plugin Into Cell",
+    description: "Load a hosted plugin (VST3, AudioUnit, or CLAP) into a cell's instrument slot. Blocks until the plugin probes + " +
+        "instantiates (can take seconds for heavy plugins) and returns success or the underlying error. " +
+        "`path` must be a `fileOrIdentifier` returned by a previous `list_plugins` call in this session.",
+    inputSchema: {
+        cellId: z.number().int().min(1).describe("Target cell (1-based)."),
+        path: z.string().describe("Plugin fileOrIdentifier from list_plugins."),
+        format: PLUGIN_FORMAT.describe("Plugin format."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const clamped = await clampCellId(args.cellId);
+    if (typeof clamped === "string")
+        return error(clamped);
+    if (!knownPluginIdentifiers.has(args.path)) {
+        return error(`Plugin path not in the scanner's known list. Call list_plugins first and use one of its ` +
+            `fileOrIdentifier values. Refused: ${args.path}`);
+    }
+    const raw = (await bridge.send("loadPlugin", {
+        cellId: clamped,
+        path: args.path,
+        format: args.format,
+    }));
+    return text(raw);
+});
+server.registerTool("unload_plugin", {
+    title: "Unload Plugin From Cell",
+    description: "Unload the hosted plugin from a cell. No-op if no plugin is loaded there.",
+    inputSchema: {
+        cellId: z.number().int().min(1).describe("Target cell."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const clamped = await clampCellId(args.cellId);
+    if (typeof clamped === "string")
+        return error(clamped);
+    await bridge.send("unloadPlugin", clamped);
+    return text(`Unload queued for cell ${clamped}.`);
+});
+server.registerTool("set_plugin_param", {
+    title: "Set Hosted Plugin Parameter",
+    description: "Set a parameter on a hosted plugin by cell + parameter index. Value is normalized 0..1. " +
+        "Use `list_loaded_plugins` to find param indices and names. " +
+        "This is the dedicated path for hosted plugin params — `set_parameters` won't reach them. " +
+        "Targets the cell's instrument-slot plugin only.",
+    inputSchema: {
+        cellId: z.number().int().min(1),
+        paramIndex: z.number().int().min(0),
+        value: z.number().min(0).max(1).describe("Normalized 0..1."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const clamped = await clampCellId(args.cellId);
+    if (typeof clamped === "string")
+        return error(clamped);
+    await bridge.send("setPluginParam", {
+        cellId: clamped,
+        paramIndex: args.paramIndex,
+        value: args.value,
+    });
+    return text(`Queued cell ${clamped} param ${args.paramIndex} = ${args.value}.`);
+});
+server.registerTool("set_plugin_bypass", {
+    title: "Bypass Hosted Plugin",
+    description: "Toggle bypass on the hosted plugin in a cell (instrument slot). Bypassed plugins are silenced; the cell sampler " +
+        "still plays in parallel.",
+    inputSchema: {
+        cellId: z.number().int().min(1),
+        bypassed: z.boolean(),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const clamped = await clampCellId(args.cellId);
+    if (typeof clamped === "string")
+        return error(clamped);
+    await bridge.send("setPluginBypass", { cellId: clamped, bypassed: args.bypassed });
+    return text(`Cell ${clamped} bypass=${args.bypassed}.`);
+});
+// ============================================================
+// TOOLS — Settings, transport config, device + preset management
+// ============================================================
+server.registerTool("update_settings", {
+    title: "Update Plugin Settings",
+    description: "Merge a partial settings delta into PAM's plugin settings (the Settings panel state) and apply it live. " +
+        "Returns the full merged settings object so you can discover available keys. This is the only way to flip " +
+        "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 " +
+        "include UI/library preferences — call get_state or inspect the returned object for the current set.",
+    inputSchema: {
+        settings: z
+            .record(z.string(), z.any())
+            .describe("Partial settings object to merge. Example: { experimentalMode: true, experimentalPluginHost: true }"),
+    },
+}, async ({ settings }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (!settings || Object.keys(settings).length === 0)
+        return error("Provide at least one settings key to update.");
+    const merged = await bridge.send("applySettingsUpdate", settings);
+    return json(merged);
+});
+server.registerTool("configure_transport", {
+    title: "Configure Transport",
+    description: "Configure transport behaviour beyond BPM (use set_bpm for tempo). Set the time signature, toggle host-sync " +
+        "(when off, preset/user BPM overrides the host), toggle external clock sync, mute the audio output (standalone), " +
+        "or release host-sync ownership for manual transport. All fields are optional — only the provided ones are applied.",
+    inputSchema: {
+        timeSigNumerator: z.number().int().min(1).max(32).optional().describe("Beats per bar. Requires timeSigDenominator."),
+        timeSigDenominator: z.number().int().min(1).max(32).optional().describe("Beat unit. Requires timeSigNumerator."),
+        hostSyncEnabled: z.boolean().optional().describe("When false, preset/user BPM overrides the host tempo."),
+        externalClockSync: z.boolean().optional().describe("Sync the internal transport to external MIDI clock."),
+        muteAudioOutput: z.boolean().optional().describe("Standalone only: mute the master output."),
+        releaseHostSyncForManualTransport: z
+            .boolean()
+            .optional()
+            .describe("When true, release host-sync ownership so the internal transport can be driven manually."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const applied = [];
+    const { timeSigNumerator, timeSigDenominator } = args;
+    if ((timeSigNumerator === undefined) !== (timeSigDenominator === undefined))
+        return error("timeSigNumerator and timeSigDenominator must be provided together.");
+    if (timeSigNumerator !== undefined && timeSigDenominator !== undefined) {
+        await bridge.send("updateTransportTimeSig", timeSigNumerator, timeSigDenominator);
+        applied.push(`timeSig=${timeSigNumerator}/${timeSigDenominator}`);
+    }
+    if (args.hostSyncEnabled !== undefined) {
+        await bridge.send("setHostSyncEnabled", args.hostSyncEnabled);
+        applied.push(`hostSync=${args.hostSyncEnabled}`);
+    }
+    if (args.externalClockSync !== undefined) {
+        await bridge.send("setExternalClockSync", args.externalClockSync);
+        applied.push(`externalClock=${args.externalClockSync}`);
+    }
+    if (args.muteAudioOutput !== undefined) {
+        await bridge.send("setMuteAudioOutput", args.muteAudioOutput);
+        applied.push(`muteOutput=${args.muteAudioOutput}`);
+    }
+    if (args.releaseHostSyncForManualTransport) {
+        await bridge.send("releaseHostSyncForManualTransport");
+        applied.push("releasedHostSync");
+    }
+    if (applied.length === 0)
+        return error("No transport fields provided.");
+    return text(`Transport configured: ${applied.join(", ")}.`);
+});
+server.registerTool("get_audio_device_setup", {
+    title: "Get Audio Device Setup",
+    description: "Get the standalone audio/MIDI device setup (sample rate, buffer size, available and active input/output devices). " +
+        "Returns null when running plugin-hosted (the DAW owns the device config). Use the device IDs/names from here with set_midi_io.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true },
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const setup = await bridge.send("getAudioDeviceSetup");
+    return json(setup);
+});
+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. " +
+        "All fields optional.",
+    inputSchema: {
+        inputDeviceIds: z.array(z.string()).optional().describe("Enabled MIDI input device IDs (replaces the active set)."),
+        outputDeviceId: z.string().optional().describe("MIDI output device ID."),
+        outputEnabled: z.boolean().optional().describe("Enable/disable MIDI output."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const applied = [];
+    if (args.inputDeviceIds !== undefined) {
+        await bridge.send("setMidiInputDevices", args.inputDeviceIds);
+        applied.push(`inputs=${args.inputDeviceIds.length}`);
+    }
+    if (args.outputDeviceId !== undefined) {
+        await bridge.send("setMidiOutputDevice", args.outputDeviceId);
+        applied.push(`output=${args.outputDeviceId}`);
+    }
+    if (args.outputEnabled !== undefined) {
+        await bridge.send("setMidiOutputEnabled", args.outputEnabled);
+        applied.push(`outputEnabled=${args.outputEnabled}`);
+    }
+    if (applied.length === 0)
+        return error("No MIDI I/O fields provided.");
+    return text(`MIDI I/O set: ${applied.join(", ")}.`);
+});
+server.registerTool("set_midi_mapping", {
+    title: "Set MIDI Action Mapping",
+    description: "Configure the global MIDI-controller mappings that trigger PAM actions: variation switch, preset change, " +
+        "looper record, live resample, and looper-variation switch. Set the enable flag, MIDI channel, CC number, " +
+        "preset source, or bar-sync for each target. One field per call.",
+    inputSchema: {
+        target: z
+            .enum(["variation", "preset", "looper", "resample", "looperVariation"])
+            .describe("Which action's mapping to configure."),
+        field: z
+            .enum(["enabled", "channel", "ccNumber", "source", "barSync"])
+            .describe("Field to set. 'source' is preset-only; 'barSync' is variation/looperVariation-only; " +
+            "looper/resample have no source/barSync."),
+        value: z
+            .union([z.number(), z.boolean()])
+            .describe("boolean for enabled/barSync; number for channel (1-16), ccNumber (0-127), or source."),
+    },
+}, async ({ target, field, value }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("setMidiMapping", { target, field, value });
+    return text(`MIDI mapping ${target}.${field} = ${value}.`);
+});
+server.registerTool("delete_preset", {
+    title: "Delete Preset",
+    description: "Delete a user preset file from disk. Factory presets are protected and cannot be deleted. " +
+        "Use the relative path returned by list_presets.",
+    inputSchema: {
+        path: z.string().describe("Relative preset path (e.g. 'Presets/User/MyPreset.preset')."),
+    },
+    annotations: { destructiveHint: true },
+}, async ({ path: presetPath }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("removePreset", presetPath);
+    return json(result);
+});
+server.registerTool("set_preset_factory_status", {
+    title: "Set Preset Factory Status",
+    description: "Mark a preset as factory (read-only) or user (editable) on disk. Affects the factory flag and the file location.",
+    inputSchema: {
+        path: z.string().describe("Relative preset path."),
+        makeFactory: z.boolean().describe("true → factory (read-only), false → user (editable)."),
+    },
+}, async ({ path: presetPath, makeFactory }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = await bridge.send("togglePresetFactoryStatus", presetPath, makeFactory);
+    return json(result);
+});
+server.registerTool("get_sample_usage", {
+    title: "Get Sample Usage",
+    description: "Cross-reference samples and presets. mode 'presetUsesSamples' lists the samples a preset references; " +
+        "mode 'presetsUsingSample' lists presets that reference a given sample (or any sample under a folder).",
+    inputSchema: {
+        mode: z.enum(["presetUsesSamples", "presetsUsingSample"]),
+        path: z
+            .string()
+            .describe("Relative preset path (presetUsesSamples) or relative sample path (presetsUsingSample)."),
+        isFolder: z
+            .boolean()
+            .optional()
+            .describe("presetsUsingSample only: treat 'path' as a folder and match any sample beneath it."),
+    },
+    annotations: { readOnlyHint: true },
+}, async ({ mode, path: relPath, isFolder }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const result = mode === "presetUsesSamples"
+        ? await bridge.send("getPresetSampleUsage", relPath)
+        : await bridge.send("getPresetsUsingSample", relPath, isFolder ?? false);
+    return json(result);
+});
+server.registerTool("repair_preset_samples", {
+    title: "Repair Preset Sample Paths",
+    description: "Fix broken sample references in presets. mode 'fix' auto-relinks moved/renamed samples by searching the " +
+        "library (optionally scoped to one preset). mode 'rescan' re-audits a preset for still-missing samples and " +
+        "reports them. Useful after moving a sample library or importing presets from another machine.",
+    inputSchema: {
+        mode: z.enum(["fix", "rescan"]),
+        presetPath: z
+            .string()
+            .optional()
+            .describe("Relative preset path. Omit for 'fix' to scan all presets; omit for 'rescan' to audit the active preset."),
+    },
+}, async ({ mode, presetPath }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (mode === "fix") {
+        const result = await bridge.send("fixPresetSamplePaths", presetPath ?? "");
+        return json(result);
+    }
+    await bridge.send("rescanMissingSamples", presetPath ?? "");
+    return text(`Re-audited ${presetPath || "active preset"} for missing samples (results dispatched to UI state).`);
+});
+server.registerTool("preview_sample", {
+    title: "Preview Sample",
+    description: "Audition an audio file through PAM's native preview player without loading it into a cell. Pass filePath to " +
+        "start previewing; pass stop:true to stop the current preview.",
+    inputSchema: {
+        filePath: z.string().optional().describe("Absolute or library-relative path to the audio file to preview."),
+        stop: z.boolean().optional().describe("Stop the current preview instead of starting one."),
+    },
+}, async ({ filePath, stop }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    if (stop) {
+        await bridge.send("stopPreviewNative");
+        return text("Stopped sample preview.");
+    }
+    if (!filePath)
+        return error("Provide filePath to preview, or stop:true to stop.");
+    const ok = await bridge.send("previewSampleNative", filePath);
+    return text(ok ? `Previewing ${basename(filePath)}.` : `Could not preview ${basename(filePath)} (file unreadable?).`);
+});
+// ============================================================
+// TOOLS — Plugin host (extra)
+// ============================================================
+server.registerTool("set_plugin_params", {
+    title: "Set Hosted Plugin Params (batch)",
+    description: "Set multiple hosted-plugin parameters in one call (more efficient than set_plugin_param per value). Values are " +
+        "0..1 normalized. Use list_loaded_plugins to discover paramIndex values. role defaults to 'instrument'.",
+    inputSchema: {
+        cellId: z.number().int().min(1).describe("Cell number."),
+        role: z.enum(["instrument", "effect"]).optional().describe("Which hosted slot (default 'instrument')."),
+        values: z
+            .array(z.object({ paramIndex: z.number().int().min(0), value: z.number().min(0).max(1) }))
+            .min(1)
+            .describe("Array of { paramIndex, value } where value is 0..1 normalized."),
+    },
+}, async (args) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    const clamped = await clampCellId(args.cellId);
+    if (typeof clamped === "string")
+        return error(clamped);
+    await bridge.send("setPluginParams", {
+        cellId: clamped,
+        role: args.role ?? "instrument",
+        values: args.values,
+    });
+    return text(`Queued ${args.values.length} param(s) for cell ${clamped} (${args.role ?? "instrument"}).`);
+});
+server.registerTool("skip_current_plugin_scan", {
+    title: "Skip Current Plugin Scan",
+    description: "Skip (blocklist) the plugin currently being scanned and continue the scan. Use when a scan is stuck on a " +
+        "crashing/hanging plugin (poll get_plugin_scan_status to detect a stall).",
+    inputSchema: {},
+}, async () => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("skipCurrentPluginScan");
+    return text("Skipped the current plugin and continued the scan.");
+});
+server.registerTool("remove_plugin_from_blocklist", {
+    title: "Remove Plugin From Blocklist",
+    description: "Un-blocklist a plugin that was blocklisted after a failed/crashed scan so it can be scanned and loaded again. " +
+        "Pass the fileOrIdentifier as it appears in the blocklist (see list_plugins → blocklist).",
+    inputSchema: {
+        fileOrIdentifier: z.string().describe("The blocklisted plugin's file path or identifier."),
+    },
+}, async ({ fileOrIdentifier }) => {
+    const check = await requireBridge();
+    if (check !== true)
+        return check;
+    await bridge.send("removeFromBlocklist", fileOrIdentifier);
+    return text(`Removed ${fileOrIdentifier} from the plugin blocklist.`);
+});
+// ============================================================
 // Start
 // ============================================================
 async function main() {