@map-audio/pam-mcp-server 1.7.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,27 @@ function formatParam(p) {
 // --- Server ---
 const server = new McpServer({
     name: "pam",
-    version: "1.7.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. " +
-        "To enable experimental features (drum synth, plugin host) call update_settings with both " +
-        "experimentalMode:true AND the specific sub-flag (e.g. experimentalDrumSynth:true). " +
+        "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 " +
@@ -482,6 +517,77 @@ 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.",
@@ -563,6 +669,141 @@ server.registerTool("generate_kit", {
         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. " +
@@ -1033,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
@@ -1426,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 = [
@@ -1813,7 +2519,7 @@ server.registerTool("set_drum_synth", {
         "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) AND Settings → Experimental → Drum Synth ON. " +
+        "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)."),
@@ -1984,56 +2690,110 @@ server.registerTool("gain_sample", {
     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
@@ -3126,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
 // ============================================================
@@ -3290,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
@@ -3299,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)
@@ -3318,8 +4183,19 @@ 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}).`);
@@ -3592,14 +4468,15 @@ 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, experimentalDrumSynth, " +
-        "experimentalPluginHost, experimentalMcpBridge. To enable the drum synth or plugin host, set BOTH " +
-        "experimentalMode:true AND the specific sub-flag (e.g. experimentalDrumSynth:true) in one call. Other keys " +
+        "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, experimentalDrumSynth: true }"),
+            .describe("Partial settings object to merge. Example: { experimentalMode: true, experimentalPluginHost: true }"),
     },
 }, async ({ settings }) => {
     const check = await requireBridge();