@mthines/reaper-mcp 0.19.0 → 0.70.2

package/reaper/mcp_bridge.lua

@@ -12,6 +12,7 @@
 local POLL_INTERVAL = 0 -- scan every defer cycle; the notify file makes this cheap
 local HEARTBEAT_INTERVAL = 1.0 -- write heartbeat every 1s
 local MCP_ANALYZER_FX_NAME = "reaper-mcp/mcp_analyzer" -- JSFX analyzer name
+local OPEN_UI_ON_START = true -- open the status window (reaper_www_root/mcp_bridge.html) when the bridge starts
 
 -- Determine bridge directory (REAPER resource path / Scripts / mcp_bridge_data)
 local bridge_dir = reaper.GetResourcePath() .. "/Scripts/mcp_bridge_data/"
@@ -19,6 +20,54 @@ local bridge_dir = reaper.GetResourcePath() .. "/Scripts/mcp_bridge_data/"
 -- Ensure bridge directory exists
 reaper.RecursiveCreateDirectory(bridge_dir, 0)
 
+-- Plan executor library (run_plan), installed next to this script by `reaper-mcp setup`.
+-- Loaded under pcall so an older install without the file keeps every other tool working.
+local script_dir = debug.getinfo(1, "S").source:match("@?(.*[\\/])") or ""
+local plan_lib_ok, plan_lib = pcall(dofile, script_dir .. "mcp_plan_lib.lua")
+-- Action proxy + selection setters (search/get/run_action, set_selected_*), same install rules.
+local actions_lib_ok, actions_lib = pcall(dofile, script_dir .. "mcp_actions_lib.lua")
+-- Track structure + routing setters (add/delete/move track, sends, groups), same install rules.
+local tracks_lib_ok, tracks_lib = pcall(dofile, script_dir .. "mcp_tracks_lib.lua")
+
+-- Track index -1 means the master track, for every tool that takes a
+-- trackIndex. REAPER's own GetTrack returns nil for -1, so nothing relied on it.
+do
+  local get_track = reaper.GetTrack
+  reaper.GetTrack = function(proj, idx)
+    if idx == -1 then return reaper.GetMasterTrack(proj) end
+    return get_track(proj, idx)
+  end
+end
+-- Project ops, tempo map and marker editing (undo/redo, save, render, settings), same install rules.
+local project_lib_ok, project_lib = pcall(dofile, script_dir .. "mcp_project_lib.lua")
+-- Items, takes, take FX, FX move/copy/rename, .RfxChain and track templates, same install rules.
+local items_lib_ok, items_lib = pcall(dofile, script_dir .. "mcp_items_lib.lua")
+-- Record setup (arm, input, monitoring, record mode), fixed lanes and comping, same install rules.
+-- One local (the main chunk is near Lua's 200-locals limit): the lib, or { load_error = why }.
+-- Lib wrappers added since the main chunk reached the 200-locals limit live here, one field each
+local ext = {}
+ext.recording = (function()
+  local ok, lib = pcall(dofile, script_dir .. "mcp_recording_lib.lua")
+  if ok then return lib end
+  return { load_error = tostring(lib) }
+end)()
+ext.fxstate = (function()
+  local ok, lib = pcall(dofile, script_dir .. "mcp_fxstate_lib.lua")
+  if ok then return lib end
+  return { load_error = tostring(lib) }
+end)()
+ext.extensions = (function()
+  local ok, lib = pcall(dofile, script_dir .. "mcp_extensions_lib.lua")
+  if ok then return lib end
+  return { load_error = tostring(lib) }
+end)()
+-- What a write changed and what a listing showed, for the status page's drawer (same install rules).
+local edit_lib_ok, edit_lib = pcall(dofile, script_dir .. "mcp_edit_views_lib.lua")
+-- Snapshot list, restore and save from the status page (same install rules).
+local snaps_lib_ok, snaps_lib = pcall(dofile, script_dir .. "mcp_snapshots_ui_lib.lua")
+-- LoreKit tokens shared through ~/.config/reaper-mcp (same install rules).
+ext.prefs = (function() local ok, lib = pcall(dofile, script_dir .. "mcp_prefs_lib.lua"); return ok and lib or nil end)()
+
 local last_poll = 0
 local last_heartbeat = 0
 local defer_count = 0
@@ -53,6 +102,15 @@ local function extract_json_string(str, pos)
         result[#result + 1] = '\t'
       elseif next_ch == '/' then
         result[#result + 1] = '/'
+      elseif next_ch == 'r' then
+        result[#result + 1] = '\r'
+      elseif next_ch == 'b' then
+        result[#result + 1] = '\b'
+      elseif next_ch == 'f' then
+        result[#result + 1] = '\f'
+      elseif next_ch == 'u' and str:sub(i + 2, i + 5):match('^%x%x%x%x$') then
+        result[#result + 1] = utf8.char(tonumber(str:sub(i + 2, i + 5), 16))
+        i = i + 4
       else
         result[#result + 1] = next_ch
       end
@@ -67,6 +125,29 @@ local function extract_json_string(str, pos)
   return nil, i  -- unterminated string
 end
 
+-- The balanced {...} or [...] that starts at `pos`. Unlike %b{} / %b[], it
+-- skips brackets inside strings, so a "}" in a name doesn't end the object.
+local function balanced(str, pos, open, close)
+  local pat = open == "{" and '[\\"{}]' or '[\\"%[%]]'
+  local depth, in_str, i = 0, false, pos
+  while true do
+    i = str:find(pat, i)
+    if not i then return nil end
+    local c = str:sub(i, i)
+    if in_str then
+      if c == "\\" then i = i + 1 elseif c == '"' then in_str = false end
+    elseif c == '"' then
+      in_str = true
+    elseif c == open then
+      depth = depth + 1
+    elseif c == close then
+      depth = depth - 1
+      if depth == 0 then return str:sub(pos, i) end
+    end
+    i = i + 1
+  end
+end
+
 -- Parse a flat JSON object with string/number values in params.
 -- Handles escaped quotes in string values (e.g. JSON arrays passed as strings).
 local function parse_flat_object(str)
@@ -99,7 +180,7 @@ local function parse_flat_object(str)
       end
     elseif ch == '{' then
       -- Nested object — extract with balanced braces
-      local nested = str:match('%b{}', val_start)
+      local nested = balanced(str, val_start, "{", "}")
       if nested then
         obj[key] = parse_flat_object(nested)
         i = val_start + #nested
@@ -108,7 +189,7 @@ local function parse_flat_object(str)
       end
     elseif ch == '[' then
       -- Array — extract with balanced brackets
-      local arr = str:match('%b[]', val_start)
+      local arr = balanced(str, val_start, "[", "]")
       if arr then
         obj[key] = arr  -- keep as string for json_decode_array to parse later
         i = val_start + #arr
@@ -117,7 +198,8 @@ local function parse_flat_object(str)
       end
     elseif ch:match('[%d%-]') then
       -- Number
-      local num_str = str:match('-?%d+%.?%d*', val_start)
+      local num_str = str:match('^-?%d+%.?%d*[eE][-+]?%d+', val_start)
+        or str:match('^-?%d+%.?%d*', val_start)
       if num_str then
         obj[key] = tonumber(num_str)
         i = val_start + #num_str
@@ -166,20 +248,40 @@ local function json_decode_array(input)
 
   -- Fallback: extract each {...} from the array and parse individually
   local arr = {}
-  for obj_str in input:gmatch("%b{}") do
+  local i = 1
+  while true do
+    local s = input:find("{", i, true)
+    local obj_str = s and balanced(input, s, "{", "}")
+    if not obj_str then break end
     arr[#arr + 1] = parse_flat_object(obj_str)
+    i = s + #obj_str
   end
-  if #arr > 0 then return arr end
+  if #arr > 0 or input:match("^%s*%[%s*%]%s*$") then return arr end
   return nil
 end
 
+-- JSON forbids raw control characters in strings. One tab in a track or FX
+-- name would otherwise make every response that carries it unparseable.
+local JSON_ESCAPES = {
+  ['"'] = '\\"', ['\\'] = '\\\\', ['\b'] = '\\b', ['\f'] = '\\f',
+  ['\n'] = '\\n', ['\r'] = '\\r', ['\t'] = '\\t',
+}
+
+local function json_quote(s)
+  -- Explicit byte range, not %c: %c follows the C locale and, under a UTF-8
+  -- locale, also matches some bytes >= 0x80 (0x80-0x9F on macOS), which are
+  -- UTF-8 continuation bytes ("Æ" is C3 86) and would mangle names.
+  return '"' .. s:gsub('[\0-\31\127"\\]', function(c)
+    return JSON_ESCAPES[c] or string.format('\\u%04x', c:byte())
+  end) .. '"'
+end
+
 local function json_encode(obj)
   -- Simple JSON encoder for our response objects
-  local parts = {}
   local function encode_value(v)
     local t = type(v)
     if t == "string" then
-      return '"' .. v:gsub('\\', '\\\\'):gsub('"', '\\"'):gsub('\n', '\\n') .. '"'
+      return json_quote(v)
     elseif t == "number" then
       if v ~= v then return "null" end -- NaN
       if v == math.huge or v == -math.huge then return "null" end
@@ -199,7 +301,7 @@ local function json_encode(obj)
         -- Object
         local items = {}
         for k, val in pairs(v) do
-          items[#items + 1] = '"' .. tostring(k) .. '":' .. encode_value(val)
+          items[#items + 1] = json_quote(tostring(k)) .. ':' .. encode_value(val)
         end
         return "{" .. table.concat(items, ",") .. "}"
       end
@@ -457,7 +559,7 @@ function handlers.get_project_info(params)
   local proj_path = reaper.GetProjectPath()
   local track_count = reaper.CountTracks(0)
   local tempo = reaper.Master_GetTempo()
-  local _, ts_num, ts_den = reaper.TimeMap_GetTimeSigAtTime(0, 0)
+  local ts_num, ts_den = reaper.TimeMap_GetTimeSigAtTime(0, 0)
   local sr = reaper.GetSetProjectInfo(0, "PROJECT_SRATE", 0, false)
   local play_state = reaper.GetPlayState() -- 0=stopped, 1=playing, 2=paused, 4=recording
   local cursor_pos = reaper.GetCursorPosition()
@@ -588,6 +690,18 @@ function handlers.set_track_property(params)
     reaper.SetMediaTrackInfo_Value(track, "B_MUTE", value)
   elseif prop == "solo" then
     reaper.SetMediaTrackInfo_Value(track, "I_SOLO", value)
+  elseif prop == "recordArm" then
+    reaper.SetMediaTrackInfo_Value(track, "I_RECARM", value)
+  elseif prop == "phase" then
+    reaper.SetMediaTrackInfo_Value(track, "B_PHASE", value)
+  elseif prop == "input" then
+    reaper.SetMediaTrackInfo_Value(track, "I_RECINPUT", value)
+  elseif prop == "playOffsetMs" then
+    -- Track playback offset (REAPER 6.0+): D_PLAY_OFFSET is in seconds unless
+    -- flag &2 says samples; &1 bypasses it. Clear both so the value applies.
+    reaper.SetMediaTrackInfo_Value(track, "D_PLAY_OFFSET", value / 1000)
+    local flag = reaper.GetMediaTrackInfo_Value(track, "I_PLAY_OFFSET_FLAG")
+    reaper.SetMediaTrackInfo_Value(track, "I_PLAY_OFFSET_FLAG", flag & ~3)
   else
     reaper.Undo_EndBlock("MCP: Set track property", -1)
     return nil, "Unknown property: " .. tostring(prop)
@@ -607,10 +721,15 @@ function handlers.add_fx(params)
   local track = reaper.GetTrack(0, idx)
   if not track then return nil, "Track " .. idx .. " not found" end
 
-  local position = params.position or -1
+  -- TrackFX_AddByName's last argument is `instantiate`, not a slot: -1 appends, 0 only
+  -- looks up an existing instance (so a new FX is "not found"), -1000 - n inserts at slot n.
+  local instantiate = -1
+  if params.position ~= nil and params.position >= 0 then
+    instantiate = -1000 - math.floor(params.position)
+  end
 
   reaper.Undo_BeginBlock()
-  local fx_idx = reaper.TrackFX_AddByName(track, fx_name, false, position)
+  local fx_idx = reaper.TrackFX_AddByName(track, fx_name, false, instantiate)
   if fx_idx < 0 then
     reaper.Undo_EndBlock("MCP: Add FX (failed)", -1)
     return nil, "FX not found: " .. fx_name
@@ -874,6 +993,10 @@ function handlers.read_track_meters(params)
   }
 end
 
+-- Forward declaration: defined further below (line ~1618). Declared here so the
+-- earlier handlers.read_track_spectrum can capture it as an upvalue.
+local ensure_jsfx_on_track
+
 function handlers.read_track_spectrum(params)
   local idx = params.trackIndex
   if not idx then return nil, "trackIndex required" end
@@ -887,23 +1010,49 @@ function handlers.read_track_spectrum(params)
     return nil, err or "MCP Spectrum Analyzer JSFX not found. Run 'reaper-mcp setup' to install it."
   end
 
+  -- Apply the requested FFT size to the analyzer's slider1 (snapped to the sizes
+  -- the JSFX supports). JSFX params via TrackFX_(Get|Set)Param use RAW slider
+  -- values, not normalized 0-1 (verified: get_fx_parameters reports FFT Size in
+  -- its 512..8192 range, and SetParam clamps out-of-range values to the slider
+  -- min). Guard with GetParam so repeated polls at the same size don't reset the
+  -- FFT accumulator (the JSFX @slider zeroes its buffers only when the size changes).
+  local fft_size = params.fftSize or 4096
+  fft_size = fft_size <= 512 and 512
+    or fft_size <= 1024 and 1024
+    or fft_size <= 2048 and 2048
+    or fft_size <= 4096 and 4096
+    or 8192
+  local current_fft = reaper.TrackFX_GetParam(track, analyzer_idx, 0)
+  if math.abs(current_fft - fft_size) > 0.5 then
+    reaper.TrackFX_SetParam(track, analyzer_idx, 0, fft_size)
+  end
+
+  -- Give this instance its own gmem block (master -1 -> slot 0), as read_track_lufs
+  -- does; with one shared block every track's analyzer overwrote the others.
+  local slot = idx + 1
+  local current_slot = reaper.TrackFX_GetParam(track, analyzer_idx, 3)
+  if math.abs(current_slot - slot) > 0.5 then
+    reaper.TrackFX_SetParam(track, analyzer_idx, 3, slot)
+  end
+
   -- Read spectrum data from gmem
-  -- JSFX writes: gmem[0] = bin_count, gmem[1] = peak_db, gmem[2] = rms_db, gmem[3..] = bins
+  -- JSFX writes at base = slot * 4100: [base] = bin_count, [base+1] = peak_db,
+  -- [base+2] = rms_db, [base+3..] = bins
   reaper.gmem_attach("MCPAnalyzer")
+  local base = slot * 4100
 
-  local bin_count = reaper.gmem_read(0)
+  local bin_count = reaper.gmem_read(base)
   if bin_count <= 0 then
     return nil, "Spectrum analyzer not producing data yet. Ensure audio is playing."
   end
 
-  local peak_db = reaper.gmem_read(1)
-  local rms_db = reaper.gmem_read(2)
+  local peak_db = reaper.gmem_read(base + 1)
+  local rms_db = reaper.gmem_read(base + 2)
   local sr = reaper.GetSetProjectInfo(0, "PROJECT_SRATE", 0, false)
-  local fft_size = params.fftSize or 4096
 
   local bins = {}
   for i = 0, bin_count - 1 do
-    bins[#bins + 1] = reaper.gmem_read(3 + i)
+    bins[#bins + 1] = reaper.gmem_read(base + 3 + i)
   end
 
   return {
@@ -935,6 +1084,15 @@ function handlers.stop(params)
 end
 
 function handlers.record(params)
+  -- With no track armed REAPER opens a modal "Record Warning", which blocks the
+  -- main thread and with it the bridge until a person closes it (seen in 7.40).
+  local armed = false
+  for i = 0, reaper.CountTracks(0) - 1 do
+    if reaper.GetMediaTrackInfo_Value(reaper.GetTrack(0, i), "I_RECARM") ~= 0 then armed = true break end
+  end
+  if not armed then
+    return nil, "No track is armed for recording (REAPER would open a dialog that blocks the bridge). Arm a track first with set_track_record or set_track_property recordArm"
+  end
   -- Action 1013 = Transport: Record
   reaper.Main_OnCommand(1013, 0)
   return { success = true }
@@ -945,7 +1103,7 @@ function handlers.get_transport_state(params)
   local cursor_pos = reaper.GetCursorPosition()
   local play_pos = reaper.GetPlayPosition()
   local tempo = reaper.Master_GetTempo()
-  local _, ts_num, ts_den = reaper.TimeMap_GetTimeSigAtTime(0, 0)
+  local ts_num, ts_den = reaper.TimeMap_GetTimeSigAtTime(0, 0)
 
   return {
     playing = (play_state & 1) ~= 0,
@@ -973,59 +1131,47 @@ end
 
 -- Helper: detect FX type prefix from name
 local function fx_type_from_name(name)
-  if name:match("^VST3:") then return "VST3"
-  elseif name:match("^VST:") then return "VST"
+  -- Instruments carry an "i" (VST3i:, VSTi:, AUi:, CLAPi:) but are the same plugin formats
+  if name:match("^VST3i?:") then return "VST3"
+  elseif name:match("^VSTi?:") then return "VST"
   elseif name:match("^JS:") then return "JS"
-  elseif name:match("^AU:") then return "AU"
-  elseif name:match("^CLAP:") then return "CLAP"
+  elseif name:match("^AUi?:") then return "AU"
+  elseif name:match("^CLAPi?:") then return "CLAP"
   else return "JS" end  -- default for bare JSFX names
 end
 
--- Enumerate all installed FX using SWS CF_EnumerateInstalledFX if available,
--- otherwise fall back to scanning open projects via TrackFX_AddByName probe.
--- The SWS approach is preferred and more complete.
-function handlers.list_available_fx(params)
-  local category_filter = params.category
-  local fx_list = {}
-
-  -- Try SWS CF_EnumerateInstalledFX (requires SWS extension)
-  if reaper.CF_EnumerateInstalledFX then
-    local i = 0
-    while true do
-      local ok, name, ident = reaper.CF_EnumerateInstalledFX(i)
-      if not ok then break end
-      local fx_type = fx_type_from_name(name)
-      if not category_filter or fx_type:lower() == category_filter:lower() then
-        fx_list[#fx_list + 1] = {
-          name = name,
-          type = fx_type,
-          path = ident or "",
-        }
-      end
-      i = i + 1
+-- Every installed FX as REAPER lists it in the FX browser ("VST3: Pro-Q 3 (FabFilter)"), via the native
+-- EnumInstalledFX (REAPER 6.37+). nil when this REAPER is too old to enumerate.
+-- Not reaper-fxfolders.ini: that file holds the FX browser's folder layout (paths, filters), not plugins.
+local function enumerate_installed_fx()
+  if type(reaper.EnumInstalledFX) ~= "function" then return nil end
+  local list, i = {}, 0
+  while true do
+    local ok, name, ident = reaper.EnumInstalledFX(i)
+    if not ok or type(name) ~= "string" or name == "" then break end
+    -- JSFX libraries (.jsfx-inc) show up in the list but can't be loaded as effects
+    if not (name:find("%.jsfx%-inc") or (ident and ident:find("%.jsfx%-inc"))) then
+      list[#list + 1] = { name = name, type = fx_type_from_name(name), ident = ident or "" }
     end
-    return { fxList = fx_list, total = #fx_list, source = "sws" }
+    i = i + 1
   end
+  return list
+end
 
-  -- Fallback: parse reaper-fxfolders.ini for plugin names
-  local resource_path = reaper.GetResourcePath()
-  local ini_path = resource_path .. "/reaper-fxfolders.ini"
-  local content = read_file(ini_path)
-  if content then
-    for line in content:gmatch("[^\r\n]+") do
-      local name = line:match("^Item%d+=(.+)$")
-      if name and name ~= "" then
-        local fx_type = fx_type_from_name(name)
-        if not category_filter or fx_type:lower() == category_filter:lower() then
-          fx_list[#fx_list + 1] = { name = name, type = fx_type }
-        end
-      end
+function handlers.list_available_fx(params)
+  local category_filter = params.category
+  local all = enumerate_installed_fx()
+  if not all then
+    return { fxList = {}, total = 0, source = "none",
+             warning = "This REAPER cannot enumerate installed FX (EnumInstalledFX needs REAPER 6.37+)." }
+  end
+  local fx_list = {}
+  for _, fx in ipairs(all) do
+    if not category_filter or fx.type:lower() == category_filter:lower() then
+      fx_list[#fx_list + 1] = { name = fx.name, type = fx.type, path = fx.ident }
     end
-    return { fxList = fx_list, total = #fx_list, source = "fxfolders_ini" }
   end
-
-  return { fxList = fx_list, total = 0, source = "none",
-           warning = "SWS not installed and reaper-fxfolders.ini not found. Install SWS Extensions for full FX enumeration." }
+  return { fxList = fx_list, total = #fx_list, source = "reaper" }
 end
 
 function handlers.search_fx(params)
@@ -1048,6 +1194,8 @@ function handlers.search_fx(params)
   return { query = query, matches = matches, total = #matches }
 end
 
+local PRESET_LIST_MAX = 256
+
 function handlers.get_fx_preset_list(params)
   local track_idx = params.trackIndex
   local fx_idx = params.fxIndex
@@ -1058,22 +1206,49 @@ function handlers.get_fx_preset_list(params)
   local track = reaper.GetTrack(0, track_idx)
   if not track then return nil, "Track " .. track_idx .. " not found" end
 
-  local preset_count = reaper.TrackFX_GetPresetIndex(track, fx_idx)
   local presets = {}
 
-  -- TrackFX_GetPresetIndex returns current index and total count
-  -- We iterate by cycling through presets
-  -- Wrap in undo block to prevent intermediate preset changes from polluting undo history
-  local _, total = reaper.TrackFX_GetPresetIndex(track, fx_idx)
+  -- Names are only readable by loading each preset, so the FX state is saved first and put back
+  -- afterwards. Restoring the starting preset index alone is not enough: with no preset active
+  -- it is -1, which loads REAPER's default preset instead of the previous settings.
+  local current, total = reaper.TrackFX_GetPresetIndex(track, fx_idx)
+  if total and total > PRESET_LIST_MAX then
+    -- e.g. Kontakt's 2048 "Program N" slots: cycling them is slow, and each load can send
+    -- program changes, so only report the current preset
+    local _, current_preset = reaper.TrackFX_GetPreset(track, fx_idx)
+    return {
+      trackIndex = track_idx, fxIndex = fx_idx, total = total, truncated = true,
+      currentPreset = current_preset,
+      presets = {},
+      note = "More than " .. PRESET_LIST_MAX .. " presets (usually generic program slots); not enumerated",
+    }
+  end
   if total and total > 0 then
+    local chunk
+    if reaper.TrackFX_GetNamedConfigParm then
+      local ok, c = reaper.TrackFX_GetNamedConfigParm(track, fx_idx, "vst_chunk")
+      if ok and c ~= "" then chunk = c end
+    end
+    local params = {}
+    for p = 0, reaper.TrackFX_GetNumParams(track, fx_idx) - 1 do
+      params[p] = reaper.TrackFX_GetParamNormalized(track, fx_idx, p)
+    end
+
+    -- Undo block keeps the intermediate preset loads out of the undo history
     reaper.Undo_BeginBlock()
     for i = 0, total - 1 do
       reaper.TrackFX_SetPresetByIndex(track, fx_idx, i)
       local _, preset_name = reaper.TrackFX_GetPreset(track, fx_idx)
       presets[#presets + 1] = { index = i, name = preset_name or ("Preset " .. i) }
     end
-    -- Restore original preset
-    reaper.TrackFX_SetPresetByIndex(track, fx_idx, preset_count)
+    if current and current >= 0 then reaper.TrackFX_SetPresetByIndex(track, fx_idx, current) end
+    if chunk then reaper.TrackFX_SetNamedConfigParm(track, fx_idx, "vst_chunk", chunk) end
+    -- Params too: JSFX have no vst_chunk, and a plugin may not apply the chunk to its params
+    for p, v in pairs(params) do
+      if reaper.TrackFX_GetParamNormalized(track, fx_idx, p) ~= v then
+        reaper.TrackFX_SetParamNormalized(track, fx_idx, p, v)
+      end
+    end
     reaper.Undo_EndBlock("MCP: Get FX preset list", -1)
   else
     -- Plugin doesn't report preset count; return current preset only
@@ -1141,90 +1316,185 @@ local function snapshot_path(name)
   return get_snapshot_dir() .. safe .. ".json"
 end
 
+-- Base64 (standard alphabet). Used to store REAPER track state chunks inside the
+-- snapshot JSON: chunks contain quotes, newlines and {GUID} braces that would
+-- break json_encode and especially the fallback %b{} decoder. Base64's alphabet
+-- (A-Za-z0-9+/=) is safe for both the encoder and either decoder.
+local B64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+local B64_LOOKUP = {}
+for _b = 1, #B64_CHARS do B64_LOOKUP[B64_CHARS:sub(_b, _b)] = _b - 1 end
+
+local function base64_encode(data)
+  if not data or data == "" then return "" end
+  local out = {}
+  local len = #data
+  local i = 1
+  while i <= len do
+    local b1 = data:byte(i)
+    local b2 = (i + 1 <= len) and data:byte(i + 1) or 0
+    local b3 = (i + 2 <= len) and data:byte(i + 2) or 0
+    local n = b1 * 65536 + b2 * 256 + b3
+    local c1 = math.floor(n / 262144) % 64
+    local c2 = math.floor(n / 4096) % 64
+    local c3 = math.floor(n / 64) % 64
+    local c4 = n % 64
+    out[#out + 1] = B64_CHARS:sub(c1 + 1, c1 + 1)
+    out[#out + 1] = B64_CHARS:sub(c2 + 1, c2 + 1)
+    out[#out + 1] = (i + 1 <= len) and B64_CHARS:sub(c3 + 1, c3 + 1) or '='
+    out[#out + 1] = (i + 2 <= len) and B64_CHARS:sub(c4 + 1, c4 + 1) or '='
+    i = i + 3
+  end
+  return table.concat(out)
+end
+
+local function base64_decode(data)
+  if not data or data == "" then return "" end
+  data = data:gsub('[^A-Za-z0-9+/]', '')  -- strip padding/whitespace/newlines
+  local out = {}
+  local len = #data
+  local i = 1
+  while i <= len do
+    local c1 = B64_LOOKUP[data:sub(i, i)] or 0
+    local c2 = B64_LOOKUP[data:sub(i + 1, i + 1)] or 0
+    local c3 = B64_LOOKUP[data:sub(i + 2, i + 2)]
+    local c4 = B64_LOOKUP[data:sub(i + 3, i + 3)]
+    local n = c1 * 262144 + c2 * 4096 + (c3 or 0) * 64 + (c4 or 0)
+    out[#out + 1] = string.char(math.floor(n / 65536) % 256)
+    if c3 ~= nil then out[#out + 1] = string.char(math.floor(n / 256) % 256) end
+    if c4 ~= nil then out[#out + 1] = string.char(n % 256) end
+    i = i + 4
+  end
+  return table.concat(out)
+end
+
+-- Parse the trackIndices param, which under the fallback JSON parser arrives as a
+-- raw "[...]" string and under CF_Json_Parse as a Lua table. Returns a list of
+-- 0-based indices, or nil if not provided.
+local function parse_track_indices(value)
+  if value == nil then return nil end
+  if type(value) == "table" then
+    local out = {}
+    for _, v in ipairs(value) do
+      local n = tonumber(v)
+      if n then out[#out + 1] = math.floor(n) end
+    end
+    return (#out > 0) and out or nil
+  end
+  if type(value) == "string" then
+    local out = {}
+    for n in value:gmatch("%-?%d+") do out[#out + 1] = tonumber(n) end
+    return (#out > 0) and out or nil
+  end
+  return nil
+end
+
 local function capture_mixer_state(params)
   params = params or {}
   local include_fx_params = params.includeFxParams ~= false  -- default true
   local max_params = params.maxParamsPerFx or 500
-  local state = { version = 2, tracks = {} }
+
+  -- Optional scope: capture only these 0-based track indices (omit = all tracks).
+  local scope = parse_track_indices(params.trackIndices)
+
+  -- fullChunk: capture exact track state chunks (faithful plugin internal state,
+  -- e.g. Helix Native snapshots) instead of parameter values. Defaults to true
+  -- when scoped (the user wants an exact A/B of specific tracks), false otherwise
+  -- (whole-project chunk snapshots would be very large).
+  local full_chunk = params.fullChunk
+  if full_chunk == nil then full_chunk = (scope ~= nil) end
+
+  local state = { version = 2, tracks = {}, fullChunk = full_chunk and true or false }
   local count = reaper.CountTracks(0)
 
-  for i = 0, count - 1 do
+  -- Build the ordered list of track indices to capture.
+  local indices = {}
+  if scope then
+    state.scoped = true
+    for _, idx in ipairs(scope) do
+      if idx >= 0 and idx < count then indices[#indices + 1] = idx end
+    end
+  else
+    for i = 0, count - 1 do indices[#indices + 1] = i end
+  end
+
+  for _, i in ipairs(indices) do
     local track = reaper.GetTrack(0, i)
-    local _, name = reaper.GetTrackName(track)
-    local vol = reaper.GetMediaTrackInfo_Value(track, "D_VOL")
-    local pan = reaper.GetMediaTrackInfo_Value(track, "D_PAN")
-    local mute = reaper.GetMediaTrackInfo_Value(track, "B_MUTE")
-    local solo = reaper.GetMediaTrackInfo_Value(track, "I_SOLO")
-    local color = reaper.GetMediaTrackInfo_Value(track, "I_CUSTOMCOLOR")
+    if track then
+      local _, name = reaper.GetTrackName(track)
+      local track_entry = {
+        index = i,
+        name = name,
+        color = reaper.GetMediaTrackInfo_Value(track, "I_CUSTOMCOLOR"),
+        volume = reaper.GetMediaTrackInfo_Value(track, "D_VOL"),
+        pan = reaper.GetMediaTrackInfo_Value(track, "D_PAN"),
+        mute = reaper.GetMediaTrackInfo_Value(track, "B_MUTE") ~= 0,
+        solo = reaper.GetMediaTrackInfo_Value(track, "I_SOLO") ~= 0,
+      }
 
-    -- FX state with full parameter capture
-    local fx_count = reaper.TrackFX_GetCount(track)
-    local fx_states = {}
-    for j = 0, fx_count - 1 do
-      local enabled = reaper.TrackFX_GetEnabled(track, j)
-      local offline = reaper.TrackFX_GetOffline(track, j)
-      local _, preset = reaper.TrackFX_GetPreset(track, j)
-      local _, fx_name = reaper.TrackFX_GetFXName(track, j)
-
-      local params_data = {}
-      if include_fx_params then
-        local param_count = reaper.TrackFX_GetNumParams(track, j)
-        local limit = math.min(param_count, max_params)
-        for p = 0, limit - 1 do
-          local val = reaper.TrackFX_GetParam(track, j, p)
-          params_data[p + 1] = val
+      if full_chunk then
+        -- Exact, complete track state: FX chain + each plugin's internal VST
+        -- state (incl. Helix snapshot selection), routing, envelopes. Base64 so
+        -- the chunk's quotes/newlines/{GUID} braces survive the JSON round-trip.
+        local ok, chunk = reaper.GetTrackStateChunk(track, "", false)
+        if ok and chunk and chunk ~= "" then
+          track_entry.chunkB64 = base64_encode(chunk)
+        end
+      else
+        -- Lightweight: FX bypass/offline + parameter values + send levels (the
+        -- original, backward-compatible capture).
+        local fx_count = reaper.TrackFX_GetCount(track)
+        local fx_states = {}
+        for j = 0, fx_count - 1 do
+          local _, preset = reaper.TrackFX_GetPreset(track, j)
+          local _, fx_name = reaper.TrackFX_GetFXName(track, j)
+          local params_data = {}
+          if include_fx_params then
+            local param_count = reaper.TrackFX_GetNumParams(track, j)
+            local limit = math.min(param_count, max_params)
+            for p = 0, limit - 1 do
+              params_data[p + 1] = reaper.TrackFX_GetParam(track, j, p)
+            end
+          end
+          fx_states[j + 1] = {
+            name = fx_name,
+            enabled = reaper.TrackFX_GetEnabled(track, j),
+            offline = reaper.TrackFX_GetOffline(track, j),
+            preset = preset or "",
+            params = params_data,
+          }
         end
-      end
 
-      fx_states[j + 1] = {
-        name = fx_name,
-        enabled = enabled,
-        offline = offline,
-        preset = preset or "",
-        params = params_data,
-      }
-    end
+        local send_count = reaper.GetTrackNumSends(track, 0)
+        local sends = {}
+        for s = 0, send_count - 1 do
+          local dest_track = reaper.GetTrackSendInfo_Value(track, 0, s, "P_DESTTRACK")
+          local dest_idx = -1
+          local dest_name = ""
+          if dest_track then
+            dest_idx = reaper.GetMediaTrackInfo_Value(dest_track, "IP_TRACKNUMBER") - 1
+            local _, dname = reaper.GetTrackName(dest_track)
+            dest_name = dname or ""
+          end
+          sends[s + 1] = {
+            destTrackIndex = dest_idx,
+            destTrackName = dest_name,
+            volume = reaper.GetTrackSendInfo_Value(track, 0, s, "D_VOL"),
+            pan = reaper.GetTrackSendInfo_Value(track, 0, s, "D_PAN"),
+            muted = reaper.GetTrackSendInfo_Value(track, 0, s, "B_MUTE") ~= 0,
+          }
+        end
 
-    -- Send levels (volume, pan, mute for existing sends)
-    local send_count = reaper.GetTrackNumSends(track, 0)
-    local sends = {}
-    for s = 0, send_count - 1 do
-      local dest_track = reaper.GetTrackSendInfo_Value(track, 0, s, "P_DESTTRACK")
-      local dest_idx = -1
-      local dest_name = ""
-      if dest_track then
-        dest_idx = reaper.GetMediaTrackInfo_Value(dest_track, "IP_TRACKNUMBER") - 1
-        local _, dname = reaper.GetTrackName(dest_track)
-        dest_name = dname or ""
+        track_entry.fx = fx_states
+        track_entry.sends = sends
+        track_entry.fxEnabled = (function()
+          local arr = {}
+          for j = 1, #fx_states do arr[j] = fx_states[j].enabled end
+          return arr
+        end)()
       end
-      sends[s + 1] = {
-        destTrackIndex = dest_idx,
-        destTrackName = dest_name,
-        volume = reaper.GetTrackSendInfo_Value(track, 0, s, "D_VOL"),
-        pan = reaper.GetTrackSendInfo_Value(track, 0, s, "D_PAN"),
-        muted = reaper.GetTrackSendInfo_Value(track, 0, s, "B_MUTE") ~= 0,
-      }
-    end
 
-    state.tracks[i + 1] = {
-      index = i,
-      name = name,
-      color = color,
-      volume = vol,
-      pan = pan,
-      mute = mute ~= 0,
-      solo = solo ~= 0,
-      fx = fx_states,
-      sends = sends,
-      -- Legacy compat: flat fxEnabled array (derived from fx_states)
-      fxEnabled = (function()
-        local arr = {}
-        for j = 1, #fx_states do
-          arr[j] = fx_states[j].enabled
-        end
-        return arr
-      end)(),
-    }
+      state.tracks[#state.tracks + 1] = track_entry
+    end
   end
   return state
 end
@@ -1238,23 +1508,40 @@ function handlers.snapshot_save(params)
   ensure_snapshot_dir()
 
   local timestamp = os.time() * 1000
-  local snapshot = {
-    name = name,
-    description = params.description or "",
-    timestamp = timestamp,
-    mixerState = capture_mixer_state({
-      includeFxParams = params.includeFxParams ~= false,
-      maxParamsPerFx = params.maxParamsPerFx or 500,
-    }),
-  }
+  local mixer_state = capture_mixer_state({
+    includeFxParams = params.includeFxParams ~= false,
+    maxParamsPerFx = params.maxParamsPerFx or 500,
+    trackIndices = params.trackIndices,
+    fullChunk = params.fullChunk,
+  })
+  -- Metadata first, mixerState last: a lister can read name/description/trackCount from the
+  -- head of the file (mcp_snapshot_lib.lua's read_snapshot_meta reads only that prefix)
+  local content = "{" .. table.concat({
+    '"name":' .. json_encode(name),
+    '"description":' .. json_encode(params.description or ""),
+    '"timestamp":' .. json_encode(timestamp),
+    '"trackCount":' .. #mixer_state.tracks,
+    '"scoped":' .. tostring(mixer_state.scoped == true),
+    '"fullChunk":' .. tostring(mixer_state.fullChunk == true),
+    '"mixerState":' .. json_encode(mixer_state),
+  }, ",") .. "}"
 
   local path = snapshot_path(name)
-  local ok = write_file(path, json_encode(snapshot))
+  local ok = write_file(path, content)
   if not ok then
     return nil, "Failed to write snapshot file: " .. path
   end
 
-  return { success = true, name = name, timestamp = timestamp, path = path, storageLocation = get_snapshot_storage_location() }
+  return {
+    success = true,
+    name = name,
+    timestamp = timestamp,
+    path = path,
+    storageLocation = get_snapshot_storage_location(),
+    scoped = mixer_state.scoped == true,
+    fullChunk = mixer_state.fullChunk == true,
+    tracksCaptured = #mixer_state.tracks,
+  }
 end
 
 function handlers.snapshot_restore(params)
@@ -1305,6 +1592,18 @@ function handlers.snapshot_restore(params)
 
       local track = reaper.GetTrack(0, track_state.index)
       if track then
+        if track_state.chunkB64 then
+          -- Exact restore: replace the entire track state from the saved chunk.
+          -- This faithfully reproduces each plugin's internal state (incl. Helix
+          -- Native snapshot selection) which parameter-value restore cannot. The
+          -- chunk is this track's own state only, so children (e.g. guitars under
+          -- a folder) are untouched.
+          if reaper.SetTrackStateChunk(track, base64_decode(track_state.chunkB64), false) then
+            restored = restored + 1
+          else
+            warnings[#warnings + 1] = "Track " .. track_state.index .. ": SetTrackStateChunk failed"
+          end
+        else
         -- Basic mixer state (all versions)
         reaper.SetMediaTrackInfo_Value(track, "D_VOL", track_state.volume)
         reaper.SetMediaTrackInfo_Value(track, "D_PAN", track_state.pan)
@@ -1375,6 +1674,7 @@ function handlers.snapshot_restore(params)
         end
 
         restored = restored + 1
+        end
       end
     end
   end
@@ -1446,6 +1746,80 @@ function handlers.snapshot_delete(params)
   return { name = name, deleted = true }
 end
 
+-- Rename a snapshot and/or change its description; the mixer state is kept. A new name that saves to
+-- another snapshot's file is refused (pass the same name to change only the description).
+function handlers.snapshot_edit(params)
+  local name = params.name
+  if not name or name == "" then
+    return nil, "name required"
+  end
+  local new_name = params.newName
+  if new_name ~= nil then
+    new_name = tostring(new_name):match("^%s*(.-)%s*$")
+    if new_name == "" then return nil, "newName must not be empty" end
+  else
+    new_name = name
+  end
+
+  local path = snapshot_path(name)
+  local content = read_file(path)
+  if not content then
+    return nil, "Snapshot not found: " .. name
+  end
+  -- The mixer state is copied as written: the bridge's fallback decoder is flat, so it is never re-encoded.
+  -- A JSON string can't hold a bare `"mixerState":` (its quotes would be escaped), so the first one is the key.
+  local snapshot = json_decode(content)
+  local key_end = select(2, content:find('"mixerState"%s*:%s*'))
+  local raw_state
+  if key_end and content:sub(key_end + 1, key_end + 1) == "{" then
+    local depth, in_str, i = 0, false, key_end + 1
+    while i <= #content do
+      local c = content:sub(i, i)
+      if in_str then
+        if c == "\\" then i = i + 1 elseif c == '"' then in_str = false end
+      elseif c == '"' then in_str = true
+      elseif c == "{" or c == "[" then depth = depth + 1
+      elseif c == "}" or c == "]" then
+        depth = depth - 1
+        if depth == 0 then raw_state = content:sub(key_end + 1, i); break end
+      end
+      i = i + 1
+    end
+  end
+  if not snapshot or not raw_state then
+    return nil, "Invalid snapshot file for: " .. name
+  end
+  local new_path = snapshot_path(new_name)
+  -- A case-only rename is the same file on macOS and Windows: never remove it after writing
+  local same_file = new_path:lower() == path:lower()
+  if not same_file and read_file(new_path) then
+    return nil, "A snapshot already saves to that name's file: " .. new_name
+  end
+
+  local description = params.description
+  if description == nil then description = snapshot.description or "" end
+  local ok, state = pcall(plan_lib_ok and plan_lib.json_decode or json_decode, raw_state)
+  if not ok or type(state) ~= "table" then state = {} end
+  local edited = "{" .. table.concat({
+    '"name":' .. json_encode(new_name),
+    '"description":' .. json_encode(tostring(description)),
+    '"timestamp":' .. json_encode(snapshot.timestamp or os.time() * 1000),
+    '"trackCount":' .. (type(state.tracks) == "table" and #state.tracks or tonumber(snapshot.trackCount) or 0),
+    '"scoped":' .. tostring(state.scoped == true or snapshot.scoped == true),
+    '"fullChunk":' .. tostring(state.fullChunk == true or snapshot.fullChunk == true),
+    '"mixerState":' .. raw_state,
+  }, ",") .. "}"
+  if not write_file(new_path, edited) then
+    return nil, "Failed to write snapshot file: " .. new_path
+  end
+  if not same_file then os.remove(path) end
+  -- The next/prev actions continue from the current snapshot by name
+  if new_name ~= name and reaper.GetExtState("MCP_Snapshots", "current_name") == name then
+    reaper.SetExtState("MCP_Snapshots", "current_name", new_name, false)
+  end
+  return { name = new_name, previousName = name, description = tostring(description), path = new_path }
+end
+
 -- =============================================================================
 -- Routing handler
 -- =============================================================================
@@ -1611,40 +1985,104 @@ local function find_or_create_mcp_container(track)
   return idx
 end
 
+-- remove_mcp_meters: delete the "MCP Meters" container and any loose MCP meter
+-- JSFX that the metering reads inserted. Leaves the MIDI emitter alone.
+-- params.trackIndices: list of track indices (-1 = master)
+function handlers.remove_mcp_meters(params)
+  local indices = params.trackIndices
+  -- Without CF_Json_Parse the command parser hands arrays over as a JSON string
+  if type(indices) == "string" then
+    local list = {}
+    for n in indices:gmatch("%-?%d+") do list[#list + 1] = tonumber(n) end
+    indices = list
+  end
+  if type(indices) ~= "table" or #indices == 0 then
+    return nil, "trackIndices required"
+  end
+  local removed = {}
+  reaper.Undo_BeginBlock()
+  for _, idx in ipairs(indices) do
+    local track = reaper.GetTrack(0, idx)
+    local count = 0
+    if track then
+      for i = reaper.TrackFX_GetCount(track) - 1, 0, -1 do
+        local _, name = reaper.TrackFX_GetFXName(track, i)
+        local is_meter = name and (name == "MCP Meters"
+          or (name:find(MCP_FX_PREFIX, 1, true) and not name:find("MIDI Emitter", 1, true)))
+        if is_meter then
+          reaper.TrackFX_Delete(track, i)
+          count = count + 1
+        end
+      end
+      container_cache[tostring(track)] = nil
+    end
+    removed[#removed + 1] = { trackIndex = idx, removed = count, found = track ~= nil }
+  end
+  reaper.Undo_EndBlock("MCP: Remove meters", -1)
+  return { tracks = removed }
+end
+
 -- Helper: find or auto-insert a named JSFX on a track.
 -- Tries to place inside an "MCP Meters" FX Container (REAPER 7.06+).
 -- Falls back to direct insertion on older REAPER versions.
 -- Returns the FX index (possibly container-addressed) on success, or nil + error.
-local function ensure_jsfx_on_track(track, fx_name)
+function ensure_jsfx_on_track(track, fx_name)
+  -- REAPER names a JSFX "JS: <desc> [<path>]" but leaves the path out for some
+  -- (seen live: the MIDI emitter is just "JS: MCP MIDI Emitter"), so match either.
+  local desc = ({
+    ["reaper-mcp/mcp_analyzer"] = "JS: MCP Spectrum Analyzer",
+    ["reaper-mcp/mcp_lufs_meter"] = "JS: MCP LUFS Meter",
+    ["reaper-mcp/mcp_correlation_meter"] = "JS: MCP Correlation Meter",
+    ["reaper-mcp/mcp_crest_factor"] = "JS: MCP Crest Factor Meter",
+    ["reaper-mcp/mcp_midi_emitter"] = "JS: MCP MIDI Emitter",
+  })[fx_name]
+  local function is_it(name)
+    return name and (name:find(fx_name, 1, true) or (desc and name:find(desc, 1, true) == 1))
+  end
+
   -- Try container approach first (REAPER 7.06+)
   local container_idx = find_or_create_mcp_container(track)
   if container_idx then
+    -- Seen live (REAPER 7.40): a container added as a track's only FX comes up
+    -- bypassed, so the meters inside never see audio and read zeros. It only
+    -- holds pass-through meters, so it is safe to keep it enabled.
+    if not reaper.TrackFX_GetEnabled(track, container_idx) then
+      reaper.TrackFX_SetEnabled(track, container_idx, true)
+    end
     local ok, count_str = reaper.TrackFX_GetNamedConfigParm(track, container_idx, "container_count")
     local count = tonumber(count_str) or 0
 
-    -- Search inside container for existing JSFX
-    for i = 0, count - 1 do
-      local _, addr_str = reaper.TrackFX_GetNamedConfigParm(track, container_idx, "container_item." .. i)
-      local addr = tonumber(addr_str)
-      if addr then
-        local _, name = reaper.TrackFX_GetFXName(track, addr)
-        if name and name:find(fx_name, 1, true) then
-          return addr  -- Found inside container
+    local function find_in_container()
+      local _, n_str = reaper.TrackFX_GetNamedConfigParm(track, container_idx, "container_count")
+      for i = 0, (tonumber(n_str) or 0) - 1 do
+        local _, addr_str = reaper.TrackFX_GetNamedConfigParm(track, container_idx, "container_item." .. i)
+        local addr = tonumber(addr_str)
+        if addr then
+          local _, name = reaper.TrackFX_GetFXName(track, addr)
+          if is_it(name) then return addr end
         end
       end
     end
 
+    local found = find_in_container()
+    if found then return found end
+
     -- Not found — insert inside container
     -- Use legacy addressing: 0x2000000 + (1-based slot) * (top_chain_count + 1) + (1-based container pos)
     local top_count = reaper.TrackFX_GetCount(track)
     local slot = count + 1  -- 1-based, next empty slot
     local container_pos = container_idx + 1  -- 1-based
     local insert_addr = 0x2000000 + slot * (top_count + 1) + container_pos
-    local new_idx = reaper.TrackFX_AddByName(track, fx_name, false, insert_addr)
-    if new_idx >= 0 then
+    if reaper.TrackFX_AddByName(track, fx_name, false, insert_addr) >= 0 then
       -- Invalidate cache since FX count changed
       container_cache[tostring(track)] = nil
-      return new_idx
+      -- Look the new meter up by name: the index TrackFX_AddByName returns for a
+      -- container insert is not its address. Callers set slider params on the
+      -- returned index, and the wrong index wrote them into the track's first FX
+      -- (seen live: Pro-Q 4 band 1 gain pushed to +30 dB).
+      found = find_in_container()
+      if found then return found end
+      return nil, "Internal error: " .. fx_name .. " was inserted but could not be found in the MCP Meters container"
     end
     -- Container insertion failed — fall through to direct
   end
@@ -1653,7 +2091,7 @@ local function ensure_jsfx_on_track(track, fx_name)
   local fx_count = reaper.TrackFX_GetCount(track)
   for i = 0, fx_count - 1 do
     local _, name = reaper.TrackFX_GetFXName(track, i)
-    if name and name:find(fx_name, 1, true) then
+    if is_it(name) then
       return i
     end
   end
@@ -1674,17 +2112,21 @@ function handlers.read_track_lufs(params)
   local fx_idx, err = ensure_jsfx_on_track(track, MCP_LUFS_METER_FX_NAME)
   if not fx_idx then return nil, err end
 
-  -- Set the track_slot parameter so this instance writes to a unique gmem offset
-  local desired_slot = idx / 127
+  -- Give this instance its own gmem slot (master -1 -> 0). TrackFX_SetParam
+  -- takes the RAW slider value; changing it resets the measurement.
+  local slot = idx + 1
   local current_slot = reaper.TrackFX_GetParam(track, fx_idx, 1)
-  if math.abs(current_slot - desired_slot) > 0.001 then
-    reaper.TrackFX_SetParam(track, fx_idx, 1, desired_slot)
+  if math.abs(current_slot - slot) > 0.5 then
+    reaper.TrackFX_SetParam(track, fx_idx, 1, slot)
+  end
+  if params.reset then
+    reaper.TrackFX_SetParam(track, fx_idx, 0, 1)  -- the Reset slider; the JSFX sets it back to 0
   end
 
   -- Read from gmem (JSFX writes here from @sample)
   reaper.gmem_attach("MCPLufsMeter")
 
-  local base = idx * 8
+  local base = slot * 8
   local integrated  = reaper.gmem_read(base + 0)
   local short_term  = reaper.gmem_read(base + 1)
   local momentary   = reaper.gmem_read(base + 2)
@@ -1828,6 +2270,25 @@ local function ppq_to_beats(take, item)
   end
 end
 
+-- Helper: count a take's channel events by type. MIDI_CountEvts' "cc" count is
+-- every channel event MIDI_GetCC enumerates (CC, pitch bend, program change,
+-- channel/poly pressure), so ccCount comes from here: CC messages (0xB0) only.
+local CHANNEL_EVENT_KINDS = {
+  [176] = "cc", [224] = "pitchBend", [192] = "programChange",
+  [208] = "channelPressure", [160] = "polyAftertouch",
+}
+
+local function count_channel_events(take)
+  local _, _, evt_cnt, _ = reaper.MIDI_CountEvts(take)
+  local counts = { cc = 0, pitchBend = 0, programChange = 0, channelPressure = 0, polyAftertouch = 0, other = 0 }
+  for i = 0, evt_cnt - 1 do
+    local _, _, _, _, chanmsg = reaper.MIDI_GetCC(take, i)
+    local kind = CHANNEL_EVENT_KINDS[chanmsg] or "other"
+    counts[kind] = counts[kind] + 1
+  end
+  return counts.cc, evt_cnt, counts
+end
+
 function handlers.create_midi_item(params)
   local track_idx = params.trackIndex
   local start_pos = params.startPosition
@@ -1878,13 +2339,16 @@ function handlers.list_midi_items(params)
     local item = reaper.GetTrackMediaItem(track, i)
     local take = reaper.GetActiveTake(item)
     if take and reaper.TakeIsMIDI(take) then
-      local _, note_cnt, cc_cnt, _ = reaper.MIDI_CountEvts(take)
+      local _, note_cnt, _, _ = reaper.MIDI_CountEvts(take)
+      local cc_cnt, evt_cnt, evt_counts = count_channel_events(take)
       items[#items + 1] = {
         itemIndex = i,
         position = reaper.GetMediaItemInfo_Value(item, "D_POSITION"),
         length = reaper.GetMediaItemInfo_Value(item, "D_LENGTH"),
         noteCount = note_cnt,
         ccCount = cc_cnt,
+        channelEventCount = evt_cnt,
+        channelEventCounts = evt_counts,
         muted = reaper.GetMediaItemInfo_Value(item, "B_MUTE") ~= 0,
       }
     end
@@ -1940,7 +2404,8 @@ function handlers.analyze_midi(params)
   local track, item, take, err = get_midi_take(params)
   if err then return nil, err end
 
-  local _, note_cnt, cc_cnt, _ = reaper.MIDI_CountEvts(take)
+  local _, note_cnt, _, _ = reaper.MIDI_CountEvts(take)
+  local cc_cnt, evt_cnt, evt_counts = count_channel_events(take)
   local to_beats = ppq_to_beats(take, item)
 
   -- Per-pitch accumulators
@@ -2028,6 +2493,8 @@ function handlers.analyze_midi(params)
     itemIndex = params.itemIndex,
     totalNotes = note_cnt,
     totalCC = cc_cnt,
+    channelEventCount = evt_cnt,
+    channelEventCounts = evt_counts,
     durationBeats = math.floor(max_end_beat * 100 + 0.5) / 100,
     pitchStats = pitch_stats,
     velocityHistogram = vel_histogram,
@@ -2060,6 +2527,7 @@ function handlers.insert_midi_note(params)
   reaper.Undo_BeginBlock()
   reaper.MIDI_InsertNote(take, false, false, start_ppq, end_ppq, chan, pitch, vel, false)
   reaper.MIDI_Sort(take)
+  reaper.MarkTrackItemsDirty(track, item) -- else REAPER merges this into the previous MIDI undo point
   reaper.Undo_EndBlock("MCP: Insert MIDI note", -1)
 
   reaper.UpdateArrange()
@@ -2103,6 +2571,7 @@ function handlers.insert_midi_notes(params)
     end
   end
   reaper.MIDI_Sort(take)
+  reaper.MarkTrackItemsDirty(track, item) -- else REAPER merges this into the previous MIDI undo point
   reaper.Undo_EndBlock("MCP: Insert " .. inserted .. " MIDI notes", -1)
 
   reaper.UpdateArrange()
@@ -2152,6 +2621,7 @@ function handlers.edit_midi_note(params)
   reaper.Undo_BeginBlock()
   reaper.MIDI_SetNote(take, note_idx, sel, muted, new_start_ppq, new_end_ppq, new_chan, new_pitch, new_vel, false)
   reaper.MIDI_Sort(take)
+  reaper.MarkTrackItemsDirty(track, item) -- else REAPER merges this into the previous MIDI undo point
   reaper.Undo_EndBlock("MCP: Edit MIDI note " .. note_idx, -1)
 
   reaper.UpdateArrange()
@@ -2210,6 +2680,7 @@ function handlers.edit_midi_notes(params)
   end
 
   reaper.MIDI_Sort(take)
+  reaper.MarkTrackItemsDirty(track, item) -- else REAPER merges this into the previous MIDI undo point
   reaper.Undo_EndBlock("MCP: Batch edit " .. edited .. " MIDI notes", -1)
   reaper.UpdateArrange()
 
@@ -2232,6 +2703,7 @@ function handlers.delete_midi_note(params)
 
   reaper.Undo_BeginBlock()
   reaper.MIDI_DeleteNote(take, note_idx)
+  reaper.MarkTrackItemsDirty(track, item) -- else REAPER merges this into the previous MIDI undo point
   reaper.Undo_EndBlock("MCP: Delete MIDI note " .. note_idx, -1)
 
   reaper.UpdateArrange()
@@ -2291,12 +2763,13 @@ function handlers.insert_midi_cc(params)
   -- chanmsg 176 = 0xB0 = CC message
   reaper.MIDI_InsertCC(take, false, false, ppq, 176, chan, cc_num, value)
   reaper.MIDI_Sort(take)
+  reaper.MarkTrackItemsDirty(track, item) -- else REAPER merges this into the previous MIDI undo point
   reaper.Undo_EndBlock("MCP: Insert MIDI CC " .. cc_num, -1)
 
   reaper.UpdateArrange()
 
-  local _, _, cc_cnt, _ = reaper.MIDI_CountEvts(take)
-  return { success = true, ccCount = cc_cnt }
+  local cc_cnt, evt_cnt = count_channel_events(take)
+  return { success = true, ccCount = cc_cnt, channelEventCount = evt_cnt }
 end
 
 function handlers.delete_midi_cc(params)
@@ -2306,26 +2779,29 @@ function handlers.delete_midi_cc(params)
   local cc_idx = params.ccIndex
   if cc_idx == nil then return nil, "ccIndex required" end
 
-  local _, _, cc_cnt, _ = reaper.MIDI_CountEvts(take)
-  if cc_idx >= cc_cnt then
-    return nil, "CC index " .. cc_idx .. " out of range (item has " .. cc_cnt .. " CC events)"
+  -- ccIndex addresses every channel event (as get_midi_cc reports it), not CCs only
+  local _, _, evt_cnt, _ = reaper.MIDI_CountEvts(take)
+  if cc_idx >= evt_cnt then
+    return nil, "CC index " .. cc_idx .. " out of range (item has " .. evt_cnt .. " channel events)"
   end
 
   reaper.Undo_BeginBlock()
   reaper.MIDI_DeleteCC(take, cc_idx)
+  reaper.MarkTrackItemsDirty(track, item) -- else REAPER merges this into the previous MIDI undo point
   reaper.Undo_EndBlock("MCP: Delete MIDI CC " .. cc_idx, -1)
 
   reaper.UpdateArrange()
 
-  local _, _, new_cnt, _ = reaper.MIDI_CountEvts(take)
-  return { success = true, ccCount = new_cnt }
+  local cc_cnt, new_evt_cnt = count_channel_events(take)
+  return { success = true, ccCount = cc_cnt, channelEventCount = new_evt_cnt }
 end
 
 function handlers.get_midi_item_properties(params)
   local track, item, take, err = get_midi_take(params)
   if err then return nil, err end
 
-  local _, note_cnt, cc_cnt, _ = reaper.MIDI_CountEvts(take)
+  local _, note_cnt, _, _ = reaper.MIDI_CountEvts(take)
+  local cc_cnt, evt_cnt, evt_counts = count_channel_events(take)
 
   return {
     trackIndex = params.trackIndex,
@@ -2334,6 +2810,8 @@ function handlers.get_midi_item_properties(params)
     length = reaper.GetMediaItemInfo_Value(item, "D_LENGTH"),
     noteCount = note_cnt,
     ccCount = cc_cnt,
+    channelEventCount = evt_cnt,
+    channelEventCounts = evt_counts,
     muted = reaper.GetMediaItemInfo_Value(item, "B_MUTE") ~= 0,
     loopSource = reaper.GetMediaItemInfo_Value(item, "B_LOOPSRC") ~= 0,
   }
@@ -2426,8 +2904,9 @@ function handlers.get_media_item_properties(params)
     start_offset = reaper.GetMediaItemTakeInfo_Value(take, "D_STARTOFFS")
     local source = reaper.GetMediaItemTake_Source(take)
     if source then
-      local _, src_fn = reaper.GetMediaSourceFileName(source, "")
-      source_file = src_fn or ""
+      -- REAPER returns just the file name here (older docs show retval, name).
+      local a, b = reaper.GetMediaSourceFileName(source, "")
+      source_file = type(b) == "string" and b or (type(a) == "string" and a or "")
     end
   end
 
@@ -2799,12 +3278,7 @@ function handlers.set_multiple_track_properties(params)
   local tracks_input = params.tracks
   if not tracks_input then return nil, "tracks array required" end
 
-  local tracks = nil
-  if type(tracks_input) == "string" then
-    tracks = json_decode(tracks_input)
-  elseif type(tracks_input) == "table" then
-    tracks = tracks_input
-  end
+  local tracks = json_decode_array(tracks_input)
   if not tracks then return nil, "Failed to parse tracks array" end
 
   local updated = 0
@@ -2861,12 +3335,7 @@ function handlers.setup_fx_chain(params)
   local plugins_input = params.plugins
   if not plugins_input then return nil, "plugins array required" end
 
-  local plugins = nil
-  if type(plugins_input) == "string" then
-    plugins = json_decode(plugins_input)
-  elseif type(plugins_input) == "table" then
-    plugins = plugins_input
-  end
+  local plugins = json_decode_array(plugins_input)
   if not plugins then return nil, "Failed to parse plugins array" end
 
   local track = reaper.GetTrack(0, track_idx)
@@ -2894,8 +3363,10 @@ function handlers.setup_fx_chain(params)
 
         -- Set initial parameters if provided
         local param_errors = {}
-        if plugin.parameters and type(plugin.parameters) == "table" then
-          for _, p in ipairs(plugin.parameters) do
+        -- Nested arrays arrive as JSON text from the fallback decoder
+        local plugin_params = plugin.parameters and json_decode_array(plugin.parameters)
+        if plugin_params then
+          for _, p in ipairs(plugin_params) do
             if p.index ~= nil and p.value ~= nil then
               local ok = reaper.TrackFX_SetParam(track, fx_idx, p.index, p.value)
               if not ok then
@@ -2938,12 +3409,7 @@ function handlers.set_multiple_fx_parameters(params)
   local updates_input = params.updates
   if not updates_input then return nil, "updates array required" end
 
-  local updates = nil
-  if type(updates_input) == "string" then
-    updates = json_decode(updates_input)
-  elseif type(updates_input) == "table" then
-    updates = updates_input
-  end
+  local updates = json_decode_array(updates_input)
   if not updates then return nil, "Failed to parse updates array" end
 
   local updated = 0
@@ -2982,131 +3448,635 @@ function handlers.set_multiple_fx_parameters(params)
 end
 
 -- =============================================================================
--- Selection & Navigation
+-- Plan executor — one bridge call, one undo block, all-or-nothing
 -- =============================================================================
 
-function handlers.get_selected_tracks(params)
-  local count = reaper.CountSelectedTracks(0)
-  local tracks = {}
-  for i = 0, count - 1 do
-    local track = reaper.GetSelectedTrack(0, i)
-    local idx = reaper.GetMediaTrackInfo_Value(track, "IP_TRACKNUMBER") - 1
-    local _, name = reaper.GetTrackName(track)
-    tracks[#tracks + 1] = { index = idx, name = name }
-  end
-  return { tracks = tracks, count = count }
+-- Custom: macros and scripts are only listed in reaper-kb.ini.
+local function read_kb_ini()
+  local f = io.open(reaper.GetResourcePath() .. "/reaper-kb.ini", "r")
+  if not f then return "" end
+  local text = f:read("*a")
+  f:close()
+  return text
 end
 
-function handlers.get_time_selection(params)
-  local start_pos, end_pos = reaper.GetSet_LoopTimeRange(false, false, 0, 0, false)
-  return {
-    start = start_pos,
-    ["end"] = end_pos,
-    length = end_pos - start_pos,
-    hasSelection = end_pos > start_pos,
-  }
-end
+local plan_ctx = { applied = {} }  -- idempotency keys of recently applied plans
 
-function handlers.set_time_selection(params)
-  if params.start == nil then return nil, "start required" end
-  if params["end"] == nil then return nil, "end required" end
-  reaper.Undo_BeginBlock()
-  reaper.GetSet_LoopTimeRange(true, false, params.start, params["end"], false)
-  reaper.Undo_EndBlock("MCP: Set time selection", -1)
-  return { start = params.start, ["end"] = params["end"] }
+function handlers.run_plan(params)
+  if not plan_lib_ok then
+    return nil, "mcp_plan_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. tostring(plan_lib) .. ")"
+  end
+  plan_ctx.snapshot_save = function(name) return handlers.snapshot_save({ name = name }) end
+  plan_ctx.actions = actions_lib_ok and actions_lib or nil
+  plan_ctx.kb_text = actions_lib_ok and read_kb_ini() or nil
+  return plan_lib.run_plan(reaper, params, plan_ctx)
 end
 
 -- =============================================================================
--- Markers & Regions
+-- Action proxy + selection setters (logic in mcp_actions_lib.lua)
 -- =============================================================================
 
-function handlers.list_markers(params)
-  local _, num_markers, num_regions = reaper.CountProjectMarkers(0)
-  local total = num_markers + num_regions
-  local markers = {}
-  for i = 0, total - 1 do
-    local _, isrgn, pos, rgnend, name, markrgnindexnumber, color = reaper.EnumProjectMarkers3(0, i)
-    if not isrgn then
-      markers[#markers + 1] = {
-        index = markrgnindexnumber,
-        name = name,
-        position = pos,
-        color = color,
-      }
-    end
+local function with_actions_lib(fn)
+  if not actions_lib_ok then
+    return nil, "mcp_actions_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. tostring(actions_lib) .. ")"
   end
-  return { markers = markers, count = #markers }
+  local ok, res, err = pcall(fn)
+  if not ok then return nil, tostring(res) end
+  return res, err
 end
 
-function handlers.list_regions(params)
-  local _, num_markers, num_regions = reaper.CountProjectMarkers(0)
-  local total = num_markers + num_regions
-  local regions = {}
-  for i = 0, total - 1 do
-    local _, isrgn, pos, rgnend, name, markrgnindexnumber, color = reaper.EnumProjectMarkers3(0, i)
-    if isrgn then
-      regions[#regions + 1] = {
-        index = markrgnindexnumber,
-        name = name,
-        start = pos,
-        ["end"] = rgnend,
-        length = rgnend - pos,
-        color = color,
-      }
-    end
-  end
-  return { regions = regions, count = #regions }
+-- Arrays arrive as JSON strings: the flat command parser cannot read nested arrays.
+local function decode_list(value, field)
+  if type(value) == "table" then return value end
+  if type(value) ~= "string" or not plan_lib_ok then return nil, field .. " must be a JSON array" end
+  local list, err = plan_lib.json_decode(value)
+  if type(list) ~= "table" then return nil, field .. " is not a valid JSON array" .. (err and (" (" .. err .. ")") or "") end
+  return list
 end
 
-function handlers.add_marker(params)
-  if params.position == nil then return nil, "position required" end
-  local color = params.color or 0
-  local name = params.name or ""
-  reaper.Undo_BeginBlock()
-  local idx = reaper.AddProjectMarker2(0, false, params.position, 0, name, -1, color)
-  if idx < 0 then
-    reaper.Undo_EndBlock("MCP: Add marker (failed)", -1)
-    return nil, "Failed to add marker"
-  end
-  reaper.Undo_EndBlock("MCP: Add marker", -1)
-  return { index = idx, position = params.position, name = name }
+function handlers.search_actions(params)
+  return with_actions_lib(function() return actions_lib.search(reaper, params, read_kb_ini()) end)
 end
 
-function handlers.add_region(params)
-  if params.start == nil then return nil, "start required" end
-  if params["end"] == nil then return nil, "end required" end
-  local color = params.color or 0
-  local name = params.name or ""
-  reaper.Undo_BeginBlock()
-  local idx = reaper.AddProjectMarker2(0, true, params.start, params["end"], name, -1, color)
-  if idx < 0 then
-    reaper.Undo_EndBlock("MCP: Add region (failed)", -1)
-    return nil, "Failed to add region"
-  end
-  reaper.Undo_EndBlock("MCP: Add region", -1)
-  return { index = idx, start = params.start, ["end"] = params["end"], name = name }
+function handlers.get_action(params)
+  return with_actions_lib(function() return actions_lib.get(reaper, params, read_kb_ini()) end)
 end
 
-function handlers.delete_marker(params)
-  if params.markerIndex == nil then return nil, "markerIndex required" end
-  reaper.Undo_BeginBlock()
-  -- DeleteProjectMarker takes (proj, isrgn, markrgnindexnumber)
-  local deleted = reaper.DeleteProjectMarker(0, false, params.markerIndex, false)
-  if not deleted then
-    reaper.Undo_EndBlock("MCP: Delete marker (failed)", -1)
-    return nil, "Marker " .. params.markerIndex .. " not found"
-  end
-  reaper.Undo_EndBlock("MCP: Delete marker", -1)
-  return { success = true }
+function handlers.run_action(params)
+  return with_actions_lib(function() return actions_lib.run(reaper, params, read_kb_ini()) end)
 end
 
-function handlers.delete_region(params)
-  if params.regionIndex == nil then return nil, "regionIndex required" end
-  reaper.Undo_BeginBlock()
-  local deleted = reaper.DeleteProjectMarker(0, true, params.regionIndex, false)
-  if not deleted then
-    reaper.Undo_EndBlock("MCP: Delete region (failed)", -1)
-    return nil, "Region " .. params.regionIndex .. " not found"
+function handlers.set_selected_tracks(params)
+  return with_actions_lib(function()
+    if not plan_lib_ok then return nil, "mcp_plan_lib.lua is not installed next to mcp_bridge.lua" end
+    local refs, err = decode_list(params.tracks, "tracks")
+    if not refs then return nil, err end
+    return actions_lib.set_selected_tracks(reaper, refs, params.mode, plan_lib.resolve_track)
+  end)
+end
+
+function handlers.set_selected_items(params)
+  return with_actions_lib(function()
+    local items, err = decode_list(params.items, "items")
+    if not items then return nil, err end
+    return actions_lib.set_selected_items(reaper, items, params.mode)
+  end)
+end
+
+-- =============================================================================
+-- Recording setup, fixed lanes and comping (logic in mcp_recording_lib.lua)
+-- =============================================================================
+
+do -- locals scoped to this block: the main chunk is near Lua's 200-locals limit
+function ext.with_recording(fn)
+  if ext.recording.load_error then
+    return nil, "mcp_recording_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. ext.recording.load_error .. ")"
+  end
+  if not plan_lib_ok then return nil, "mcp_plan_lib.lua is not installed next to mcp_bridge.lua" end
+  local ok, res, err = pcall(fn)
+  if not ok then return nil, tostring(res) end
+  return res, err
+end
+
+-- Saved plugin state and extension commands (logic in mcp_fxstate_lib.lua / mcp_extensions_lib.lua).
+-- State travels as files in the bridge folder, never in the command JSON: it is megabytes.
+function ext.lib_call(key, fn, params, dir)
+  local lib = ext[key]
+  if lib.load_error then
+    return nil, "mcp_" .. key .. "_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. lib.load_error .. ")"
+  end
+  if not plan_lib_ok then return nil, "mcp_plan_lib.lua is not installed next to mcp_bridge.lua" end
+  local ctx = {
+    plan = plan_lib, dir = dir or bridge_dir, read = read_file, fxstate = ext.fxstate,
+    write = function(path, text)
+      local f, err = io.open(path, "wb")
+      if not f then return nil, err end
+      f:write(text)
+      f:close()
+      return true
+    end,
+  }
+  local ok, res, err = pcall(lib[fn], reaper, params, ctx)
+  if not ok then return nil, "Handler error: " .. tostring(res) end
+  return res, err
+end
+function handlers.get_fx_state(params) return ext.lib_call("fxstate", "get_fx_state", params) end
+function handlers.set_fx_state(params) return ext.lib_call("fxstate", "set_fx_state", params) end
+function handlers.extension_call(params) return ext.lib_call("extensions", "call", params, bridge_dir .. "extensions/") end
+
+-- A JSON-encoded value (number, array or object) from the flat parser
+function ext.decode_json(value, field)
+  if value == nil or type(value) == "table" or type(value) == "number" then return value end
+  local v, err = plan_lib.json_decode(tostring(value))
+  if v == nil then return nil, field .. " is not valid JSON" .. (err and (" (" .. err .. ")") or "") end
+  return v
+end
+
+function handlers.get_record_setup(params)
+  return ext.with_recording(function()
+    return ext.recording.get_record_setup(reaper, { all = params.all == true or params.all == "true" })
+  end)
+end
+
+function handlers.set_track_record(params)
+  return ext.with_recording(function()
+    local list, err = decode_list(params.tracks, "tracks")
+    if not list then return nil, err end
+    return ext.recording.set_track_record(reaper, list, plan_lib.resolve_track)
+  end)
+end
+
+function handlers.set_record_mode(params)
+  return ext.with_recording(function() return ext.recording.set_record_mode(reaper, params) end)
+end
+
+function handlers.get_track_lanes(params)
+  return ext.with_recording(function() return ext.recording.get_track_lanes(reaper, params, plan_lib.resolve_track) end)
+end
+
+function handlers.set_track_lanes(params)
+  return ext.with_recording(function()
+    local p = { track = params.track, laneCount = params.laneCount }
+    if params.fixedLanes ~= nil then p.fixedLanes = params.fixedLanes == true or params.fixedLanes == "true" end
+    local err
+    p.names, err = ext.decode_json(params.names, "names")
+    if err then return nil, err end
+    p.play, err = ext.decode_json(params.play, "play")
+    if err then return nil, err end
+    return ext.recording.set_track_lanes(reaper, p, plan_lib.resolve_track)
+  end)
+end
+
+function handlers.comp_lanes(params)
+  return ext.with_recording(function()
+    local ranges, err = decode_list(params.ranges, "ranges")
+    if not ranges then return nil, err end
+    return ext.recording.comp_lanes(reaper, {
+      track = params.track, ranges = ranges, crossfadeMs = params.crossfadeMs, name = params.name,
+    }, plan_lib.resolve_track)
+  end)
+end
+end
+
+-- =============================================================================
+-- Track structure + routing setters (logic in mcp_tracks_lib.lua)
+-- =============================================================================
+
+-- Resolve `params[field]` (index, name, GUID or "master") then run fn(track).
+local function with_tracks_lib(fn)
+  if not tracks_lib_ok then
+    return nil, "mcp_tracks_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. tostring(tracks_lib) .. ")"
+  end
+  if not plan_lib_ok then return nil, "mcp_plan_lib.lua is not installed next to mcp_bridge.lua" end
+  local ok, res, err = pcall(fn)
+  if not ok then return nil, tostring(res) end
+  return res, err
+end
+
+local function track_param(params, field)
+  local ref = params[field]
+  if ref == nil then return nil, field .. " required" end
+  local res, err = plan_lib.resolve_track(reaper, ref, {})
+  if not res then return nil, field .. ": " .. err end
+  return res.track
+end
+
+-- Run one structural edit in its own undo block, with a refreshed track list.
+local function undoable(label, fn)
+  reaper.Undo_BeginBlock()
+  reaper.PreventUIRefresh(1)
+  local ok, res, err = pcall(fn)
+  reaper.PreventUIRefresh(-1)
+  reaper.Undo_EndBlock("MCP: " .. label, -1)
+  reaper.TrackList_AdjustWindows(false)
+  reaper.UpdateArrange()
+  if not ok then return nil, tostring(res) end
+  return res, err
+end
+
+local function as_bool(v)
+  if v == nil then return nil end
+  return v == true or v == 1 or v == "true" or v == "1"
+end
+
+function handlers.add_track(params)
+  return with_tracks_lib(function()
+    return undoable("Add track", function() return tracks_lib.add_track(reaper, params) end)
+  end)
+end
+
+function handlers.delete_track(params)
+  return with_tracks_lib(function()
+    local tr, err = track_param(params, "track")
+    if not tr then return nil, err end
+    return undoable("Delete track", function() return tracks_lib.delete_track(reaper, tr) end)
+  end)
+end
+
+function handlers.move_track(params)
+  return with_tracks_lib(function()
+    local tr, err = track_param(params, "track")
+    if not tr then return nil, err end
+    return undoable("Move track", function() return tracks_lib.move_track(reaper, tr, params.toIndex) end)
+  end)
+end
+
+function handlers.set_track_folder(params)
+  return with_tracks_lib(function()
+    local tr, err = track_param(params, "track")
+    if not tr then return nil, err end
+    return undoable("Set track folder", function() return tracks_lib.set_track_folder(reaper, tr, params) end)
+  end)
+end
+
+function handlers.set_track_info(params)
+  return with_tracks_lib(function()
+    local tr, err = track_param(params, "track")
+    if not tr then return nil, err end
+    params.masterSend = as_bool(params.masterSend)
+    return undoable("Set track info", function() return tracks_lib.set_track_info(reaper, tr, params) end)
+  end)
+end
+
+function handlers.add_send(params)
+  return with_tracks_lib(function()
+    local src, e1 = track_param(params, "from")
+    if not src then return nil, e1 end
+    local dst, e2 = track_param(params, "to")
+    if not dst then return nil, e2 end
+    params.mute = as_bool(params.mute)
+    return undoable("Add send", function() return tracks_lib.add_send(reaper, src, dst, params) end)
+  end)
+end
+
+function handlers.add_hardware_output(params)
+  return with_tracks_lib(function()
+    local tr, err = track_param(params, "track")
+    if not tr then return nil, err end
+    params.mute = as_bool(params.mute)
+    params.mono = as_bool(params.mono)
+    return undoable("Add hardware output", function() return tracks_lib.add_hardware_output(reaper, tr, params) end)
+  end)
+end
+
+function handlers.set_send(params)
+  return with_tracks_lib(function()
+    local tr, err = track_param(params, "track")
+    if not tr then return nil, err end
+    params.mute = as_bool(params.mute)
+    params.mono = as_bool(params.mono)
+    return undoable("Edit send", function() return tracks_lib.set_send(reaper, tr, params) end)
+  end)
+end
+
+function handlers.remove_send(params)
+  return with_tracks_lib(function()
+    local tr, err = track_param(params, "track")
+    if not tr then return nil, err end
+    return undoable("Remove send", function() return tracks_lib.remove_send(reaper, tr, params) end)
+  end)
+end
+
+function handlers.set_track_group(params)
+  return with_tracks_lib(function()
+    local tr, err = track_param(params, "track")
+    if not tr then return nil, err end
+    local roles, rerr = decode_list(params.roles, "roles")
+    if not roles then return nil, rerr end
+    params.roles = roles
+    params.enable = as_bool(params.enable)
+    return undoable("Set track group", function() return tracks_lib.set_track_group(reaper, tr, params) end)
+  end)
+end
+
+-- get_track_routing keeps its fields and gains what the setters change:
+-- send index/mode/channels, hardware outputs, master send, channel count.
+do
+  local base = handlers.get_track_routing
+  handlers.get_track_routing = function(params)
+    local res, err = base(params)
+    if not res or not tracks_lib_ok then return res, err end
+    local tr = reaper.GetTrack(0, params.trackIndex)
+    local ok, extra = pcall(tracks_lib.routing, reaper, tr)
+    if not ok then return res end
+    for k, s in ipairs(res.sends or {}) do
+      local x = extra.sends[k]
+      if x then s.index, s.mode, s.srcChannel, s.destChannel = x.index, x.mode, x.srcChannel, x.destChannel end
+    end
+    for k, r in ipairs(res.receives or {}) do
+      local x = extra.receives[k]
+      if x then r.index, r.mode, r.srcChannel, r.destChannel = x.index, x.mode, x.srcChannel, x.destChannel end
+    end
+    res.hardwareOutputs = extra.hardwareOutputs
+    res.masterSend = extra.masterSend
+    res.channels = extra.channels
+    return res
+  end
+end
+
+-- =============================================================================
+-- Project ops, tempo map and marker editing (logic in mcp_project_lib.lua)
+-- =============================================================================
+
+local function with_project_lib(fn)
+  if not project_lib_ok then
+    return nil, "mcp_project_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. tostring(project_lib) .. ")"
+  end
+  local ok, res, err = pcall(fn)
+  if not ok then return nil, tostring(res) end
+  return res, err
+end
+
+-- Real file system for save/render checks.
+local project_fs = {
+  exists = function(path)
+    local f = io.open(path, "rb")
+    if f then f:close() return true end
+    return false
+  end,
+  dir_exists = function(path)
+    return os.rename(path, path) == true
+  end,
+  remove = function(path) os.remove(path) end,
+}
+
+function handlers.undo_project(params)
+  return with_project_lib(function() return project_lib.undo(reaper) end)
+end
+
+function handlers.redo_project(params)
+  return with_project_lib(function() return project_lib.redo(reaper) end)
+end
+
+function handlers.save_project(params)
+  return with_project_lib(function() return project_lib.save(reaper, params, project_fs) end)
+end
+
+function handlers.get_render_settings(params)
+  return with_project_lib(function() return project_lib.get_render(reaper) end)
+end
+
+function handlers.set_render_settings(params)
+  return with_project_lib(function()
+    local p, err = project_lib.decode_json_fields(params, plan_lib_ok and plan_lib.json_decode or function() return nil end)
+    if not p then return nil, err end
+    return project_lib.set_render(reaper, p, plan_lib_ok and plan_lib.resolve_track or nil)
+  end)
+end
+
+function handlers.render_project(params)
+  return with_project_lib(function()
+    local p, err = project_lib.decode_json_fields(params, plan_lib_ok and plan_lib.json_decode or function() return nil end)
+    if not p then return nil, err end
+    return project_lib.render(reaper, p, project_fs, plan_lib_ok and plan_lib.resolve_track or nil)
+  end)
+end
+
+function handlers.render_versions(params)
+  if not plan_lib_ok then return nil, "mcp_plan_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup`" end
+  return with_project_lib(function()
+    local p, err = project_lib.decode_json_fields(params, plan_lib.json_decode)
+    if not p then return nil, err end
+    return project_lib.render_versions(reaper, p, project_fs, plan_lib.resolve_track)
+  end)
+end
+
+function handlers.get_project_settings(params)
+  return with_project_lib(function() return project_lib.get_settings(reaper) end)
+end
+
+function handlers.set_project_settings(params)
+  return with_project_lib(function() return project_lib.set_settings(reaper, params) end)
+end
+
+function handlers.add_tempo_marker(params)
+  return with_project_lib(function() return project_lib.add_tempo_marker(reaper, params) end)
+end
+
+function handlers.edit_tempo_marker(params)
+  return with_project_lib(function() return project_lib.edit_tempo_marker(reaper, params) end)
+end
+
+function handlers.delete_tempo_marker(params)
+  return with_project_lib(function() return project_lib.delete_tempo_marker(reaper, params) end)
+end
+
+function handlers.set_project_tempo(params)
+  return with_project_lib(function() return project_lib.set_tempo(reaper, params) end)
+end
+
+function handlers.edit_marker(params)
+  return with_project_lib(function() return project_lib.edit_marker(reaper, params) end)
+end
+
+function handlers.edit_region(params)
+  return with_project_lib(function() return project_lib.edit_region(reaper, params) end)
+end
+
+-- =============================================================================
+-- Items, takes, take FX and FX housekeeping (logic in mcp_items_lib.lua)
+-- =============================================================================
+
+local items_fs = {
+  exists = function(path) return reaper.file_exists(path) end,
+  read = function(path) return read_file(path) end,
+  write = function(path, text)
+    local f, err = io.open(path, "w")
+    if not f then return nil, err end
+    f:write(text)
+    f:close()
+    return true
+  end,
+  mkdir = function(dir) reaper.RecursiveCreateDirectory(dir, 0) end,
+  list = function(dir)
+    local files, dirs = {}, {}
+    -- Index -1 drops REAPER's cached listing so new files show up.
+    reaper.EnumerateFiles(dir, -1)
+    reaper.EnumerateSubdirectories(dir, -1)
+    local i = 0
+    while true do
+      local f = reaper.EnumerateFiles(dir, i)
+      if not f then break end
+      files[#files + 1] = f
+      i = i + 1
+    end
+    i = 0
+    while true do
+      local d = reaper.EnumerateSubdirectories(dir, i)
+      if not d then break end
+      dirs[#dirs + 1] = d
+      i = i + 1
+    end
+    return files, dirs
+  end,
+}
+
+local function with_items_lib(name, params)
+  if not items_lib_ok then
+    return nil, "mcp_items_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. tostring(items_lib) .. ")"
+  end
+  if not plan_lib_ok then return nil, "mcp_plan_lib.lua is not installed next to mcp_bridge.lua" end
+  local ok, res, err = pcall(items_lib[name], reaper, params, { plan = plan_lib, fs = items_fs })
+  if not ok then return nil, tostring(res) end
+  return res, err
+end
+
+function handlers.insert_audio_file(params) return with_items_lib("insert_audio_file", params) end
+function handlers.insert_stem_tracks(params)
+  -- files travels as a JSON string (the bridge decodes only the top level)
+  if type(params.files) == "string" and plan_lib_ok then
+    local ok, files = pcall(plan_lib.json_decode, params.files)
+    params.files = ok and files or nil
+  end
+  return with_items_lib("insert_stems", params)
+end
+function handlers.list_takes(params) return with_items_lib("list_takes", params) end
+function handlers.set_active_take(params) return with_items_lib("set_active_take", params) end
+function handlers.get_take_fx(params) return with_items_lib("get_take_fx", params) end
+function handlers.add_take_fx(params) return with_items_lib("add_take_fx", params) end
+function handlers.remove_take_fx(params) return with_items_lib("remove_take_fx", params) end
+function handlers.set_take_fx_parameter(params) return with_items_lib("set_take_fx_parameter", params) end
+function handlers.get_item_appearance(params) return with_items_lib("get_item_appearance", params) end
+function handlers.set_item_color(params) return with_items_lib("set_item_color", params) end
+function handlers.set_item_fades(params) return with_items_lib("set_item_fades", params) end
+function handlers.move_fx(params) return with_items_lib("move_fx", params) end
+function handlers.copy_fx(params) return with_items_lib("copy_fx", params) end
+function handlers.rename_fx(params) return with_items_lib("rename_fx", params) end
+function handlers.save_fx_chain(params) return with_items_lib("save_fx_chain", params) end
+function handlers.load_fx_chain(params) return with_items_lib("load_fx_chain", params) end
+function handlers.list_fx_chains(params) return with_items_lib("list_fx_chains", params) end
+function handlers.save_track_template(params) return with_items_lib("save_track_template", params) end
+function handlers.insert_track_template(params) return with_items_lib("insert_track_template", params) end
+function handlers.list_track_templates(params) return with_items_lib("list_track_templates", params) end
+
+-- =============================================================================
+-- Selection & Navigation
+-- =============================================================================
+
+function handlers.get_selected_tracks(params)
+  -- The *2 variants include the master (IP_TRACKNUMBER -1 -> index -1).
+  local count = reaper.CountSelectedTracks2(0, true)
+  local tracks = {}
+  for i = 0, count - 1 do
+    local track = reaper.GetSelectedTrack2(0, i, true)
+    local num = reaper.GetMediaTrackInfo_Value(track, "IP_TRACKNUMBER")
+    local idx = num == -1 and -1 or num - 1
+    local _, name = reaper.GetTrackName(track)
+    tracks[#tracks + 1] = { index = idx, name = name }
+  end
+  return { tracks = tracks, count = count }
+end
+
+function handlers.get_time_selection(params)
+  local start_pos, end_pos = reaper.GetSet_LoopTimeRange(false, false, 0, 0, false)
+  return {
+    start = start_pos,
+    ["end"] = end_pos,
+    length = end_pos - start_pos,
+    hasSelection = end_pos > start_pos,
+  }
+end
+
+function handlers.set_time_selection(params)
+  if params.start == nil then return nil, "start required" end
+  if params["end"] == nil then return nil, "end required" end
+  reaper.Undo_BeginBlock()
+  reaper.GetSet_LoopTimeRange(true, false, params.start, params["end"], false)
+  reaper.Undo_EndBlock("MCP: Set time selection", -1)
+  return { start = params.start, ["end"] = params["end"] }
+end
+
+-- =============================================================================
+-- Markers & Regions
+-- =============================================================================
+
+function handlers.list_markers(params)
+  local _, num_markers, num_regions = reaper.CountProjectMarkers(0)
+  local total = num_markers + num_regions
+  local markers = {}
+  for i = 0, total - 1 do
+    local _, isrgn, pos, rgnend, name, markrgnindexnumber, color = reaper.EnumProjectMarkers3(0, i)
+    if not isrgn then
+      markers[#markers + 1] = {
+        index = markrgnindexnumber,
+        name = name,
+        position = pos,
+        color = color,
+      }
+    end
+  end
+  return { markers = markers, count = #markers }
+end
+
+function handlers.list_regions(params)
+  local _, num_markers, num_regions = reaper.CountProjectMarkers(0)
+  local total = num_markers + num_regions
+  local regions = {}
+  for i = 0, total - 1 do
+    local _, isrgn, pos, rgnend, name, markrgnindexnumber, color = reaper.EnumProjectMarkers3(0, i)
+    if isrgn then
+      regions[#regions + 1] = {
+        index = markrgnindexnumber,
+        name = name,
+        start = pos,
+        ["end"] = rgnend,
+        length = rgnend - pos,
+        color = color,
+      }
+    end
+  end
+  return { regions = regions, count = #regions }
+end
+
+function handlers.add_marker(params)
+  if params.position == nil then return nil, "position required" end
+  local color = params.color or 0
+  local name = params.name or ""
+  reaper.Undo_BeginBlock()
+  local idx = reaper.AddProjectMarker2(0, false, params.position, 0, name, -1, color)
+  if idx < 0 then
+    reaper.Undo_EndBlock("MCP: Add marker (failed)", -1)
+    return nil, "Failed to add marker"
+  end
+  reaper.Undo_EndBlock("MCP: Add marker", -1)
+  return { index = idx, position = params.position, name = name }
+end
+
+function handlers.add_region(params)
+  if params.start == nil then return nil, "start required" end
+  if params["end"] == nil then return nil, "end required" end
+  local color = params.color or 0
+  local name = params.name or ""
+  reaper.Undo_BeginBlock()
+  local idx = reaper.AddProjectMarker2(0, true, params.start, params["end"], name, -1, color)
+  if idx < 0 then
+    reaper.Undo_EndBlock("MCP: Add region (failed)", -1)
+    return nil, "Failed to add region"
+  end
+  reaper.Undo_EndBlock("MCP: Add region", -1)
+  return { index = idx, start = params.start, ["end"] = params["end"], name = name }
+end
+
+function handlers.delete_marker(params)
+  if params.markerIndex == nil then return nil, "markerIndex required" end
+  reaper.Undo_BeginBlock()
+  -- DeleteProjectMarker takes (proj, markrgnindexnumber, isrgn)
+  local deleted = reaper.DeleteProjectMarker(0, params.markerIndex, false)
+  if not deleted then
+    reaper.Undo_EndBlock("MCP: Delete marker (failed)", -1)
+    return nil, "Marker " .. params.markerIndex .. " not found"
+  end
+  reaper.Undo_EndBlock("MCP: Delete marker", -1)
+  return { success = true }
+end
+
+function handlers.delete_region(params)
+  if params.regionIndex == nil then return nil, "regionIndex required" end
+  reaper.Undo_BeginBlock()
+  local deleted = reaper.DeleteProjectMarker(0, params.regionIndex, true)
+  if not deleted then
+    reaper.Undo_EndBlock("MCP: Delete region (failed)", -1)
+    return nil, "Region " .. params.regionIndex .. " not found"
   end
   reaper.Undo_EndBlock("MCP: Delete region", -1)
   return { success = true }
@@ -3133,7 +4103,7 @@ function handlers.get_tempo_map(params)
   -- If no markers, return the project tempo as the single entry
   if count == 0 then
     local bpm = reaper.Master_GetTempo()
-    local _, num, denom = reaper.TimeMap_GetTimeSigAtTime(0, 0)
+    local num, denom = reaper.TimeMap_GetTimeSigAtTime(0, 0)
     markers[1] = {
       index = 0,
       position = 0,
@@ -3150,212 +4120,105 @@ end
 -- Envelopes / Automation
 -- =============================================================================
 
-function handlers.get_track_envelopes(params)
-  local track = reaper.GetTrack(0, params.trackIndex)
-  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
-  local count = reaper.CountTrackEnvelopes(track)
-  local envelopes = {}
-  for i = 0, count - 1 do
-    local env = reaper.GetTrackEnvelope(track, i)
-    local _, name = reaper.GetEnvelopeName(env)
-    local point_count = reaper.CountEnvelopePoints(env)
-    -- Get envelope state info (SWS extension provides BR_Env*, fallback if unavailable)
-    local active, visible, armed = true, true, false
-    if reaper.BR_EnvAlloc then
-      local br_env = reaper.BR_EnvAlloc(env, false)
-      active, visible, armed = reaper.BR_EnvGetProperties(br_env)
-      reaper.BR_EnvFree(br_env, false)
-    end
-    envelopes[#envelopes + 1] = {
-      index = i,
-      name = name,
-      pointCount = point_count,
-      active = active,
-      visible = visible,
-      armed = armed,
-    }
+-- Points, creation and automation items: logic in mcp_envelopes_lib.lua. One table, not
+-- separate locals: the bridge's main chunk is at Lua's 200-locals limit.
+local env_ext = {}
+env_ext.ok, env_ext.lib = pcall(dofile, script_dir .. "mcp_envelopes_lib.lua")
+
+function env_ext.run(name, params, ...)
+  if not env_ext.ok then
+    return nil, "mcp_envelopes_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. tostring(env_ext.lib) .. ")"
   end
-  return { trackIndex = params.trackIndex, envelopes = envelopes, count = count }
+  local ok, res, err = pcall(env_ext.lib[name], reaper, params, ...)
+  if not ok then return nil, "Handler error: " .. tostring(res) end
+  return res, err
 end
 
-function handlers.get_envelope_points(params)
-  local track = reaper.GetTrack(0, params.trackIndex)
-  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
-  local env_count = reaper.CountTrackEnvelopes(track)
-  if params.envelopeIndex >= env_count then
-    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
-  end
-  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
-  local total = reaper.CountEnvelopePoints(env)
-  local offset = params.offset or 0
-  local limit = params.limit or total
-  local points = {}
-  local end_idx = math.min(offset + limit, total)
-  for i = offset, end_idx - 1 do
-    local _, time, value, shape, tension, selected = reaper.GetEnvelopePoint(env, i)
-    points[#points + 1] = {
-      index = i,
-      time = time,
-      value = value,
-      shape = shape,
-      tension = tension,
-      selected = selected,
-    }
-  end
-  return {
-    trackIndex = params.trackIndex,
-    envelopeIndex = params.envelopeIndex,
-    points = points,
-    total = total,
-    offset = offset,
-    hasMore = end_idx < total,
-  }
+-- A JSON array param arrives as a string (or, from some clients, already decoded)
+function env_ext.list(v)
+  if type(v) == "table" then return v end
+  if type(v) ~= "string" then return nil end
+  return json_decode_array(v)
 end
 
+function handlers.get_track_envelopes(params) return env_ext.run("list_envelopes", params) end
+
+function handlers.get_envelope_points(params) return env_ext.run("get_points", params) end
+
 function handlers.insert_envelope_point(params)
-  local track = reaper.GetTrack(0, params.trackIndex)
-  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
-  local env_count = reaper.CountTrackEnvelopes(track)
-  if params.envelopeIndex >= env_count then
-    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
-  end
-  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
-  local shape = params.shape or 0
-  local tension = params.tension or 0
-  reaper.Undo_BeginBlock()
-  reaper.InsertEnvelopePoint(env, params.time, params.value, shape, tension, false, true)
-  reaper.Envelope_SortPoints(env)
-  reaper.Undo_EndBlock("MCP: Insert envelope point", -1)
-  local total = reaper.CountEnvelopePoints(env)
-  return {
-    trackIndex = params.trackIndex,
-    envelopeIndex = params.envelopeIndex,
-    time = params.time,
-    value = params.value,
-    shape = shape,
-    tension = tension,
-    totalPoints = total,
-  }
+  return env_ext.run("insert_points", params, {
+    { time = params.time, value = params.value, db = params.db, shape = params.shape, tension = params.tension },
+  })
 end
 
-function handlers.delete_envelope_point(params)
-  local track = reaper.GetTrack(0, params.trackIndex)
-  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
-  local env_count = reaper.CountTrackEnvelopes(track)
-  if params.envelopeIndex >= env_count then
-    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
-  end
-  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
-  local total = reaper.CountEnvelopePoints(env)
-  if params.pointIndex >= total then
-    return nil, "Point index " .. params.pointIndex .. " out of range (envelope has " .. total .. " points)"
-  end
-  reaper.Undo_BeginBlock()
-  reaper.DeleteEnvelopePointRange(env, params.pointIndex, params.pointIndex + 1)
-  reaper.Undo_EndBlock("MCP: Delete envelope point", -1)
-  return { success = true, totalPoints = reaper.CountEnvelopePoints(env) }
+function handlers.insert_envelope_points(params)
+  local points = env_ext.list(params.points)
+  if not points then return nil, "Failed to parse points JSON" end
+  return env_ext.run("insert_points", params, points)
 end
 
-function handlers.create_track_envelope(params)
-  local track = reaper.GetTrack(0, params.trackIndex)
-  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+function handlers.edit_envelope_points(params)
+  local points = env_ext.list(params.points)
+  if not points then return nil, "Failed to parse points JSON" end
+  return env_ext.run("edit_points", params, points)
+end
 
-  reaper.Undo_BeginBlock()
+function handlers.delete_envelope_point(params) return env_ext.run("delete_point", params) end
 
-  local env = nil
-  local env_name = nil
-
-  if params.fxIndex ~= nil then
-    -- FX parameter envelope
-    if params.paramIndex == nil then
-      return nil, "paramIndex is required when fxIndex is provided"
-    end
-    local fx_count = reaper.TrackFX_GetNumParms(track)
-    if fx_count == 0 then
-      return nil, "Track " .. params.trackIndex .. " has no FX"
-    end
-    -- create=true to create the envelope if it doesn't exist
-    env = reaper.GetFXEnvelope(track, params.fxIndex, params.paramIndex, true)
-    if not env then
-      return nil, "Failed to create FX parameter envelope (fxIndex=" .. params.fxIndex .. ", paramIndex=" .. params.paramIndex .. ")"
-    end
-    local _, pname = reaper.TrackFX_GetParamName(track, params.fxIndex, params.paramIndex)
-    local _, fname = reaper.TrackFX_GetFXName(track, params.fxIndex)
-    env_name = fname .. " / " .. pname
-  elseif params.envelopeName then
-    -- Built-in envelope: use GetTrackEnvelopeByName + show via state chunk
-    env = reaper.GetTrackEnvelopeByName(track, params.envelopeName)
-    if not env then
-      -- Some envelopes need to be activated first via the track state chunk
-      -- Toggle the envelope visibility via action or chunk editing
-      local env_map = {
-        ["Volume"] = "VOLENV",
-        ["Pan"] = "PANENV",
-        ["Mute"] = "MUTEENV",
-        ["Width"] = "WIDTHENV",
-        ["Trim Volume"] = "VOLENV2",
-      }
-      local chunk_key = env_map[params.envelopeName]
-      if not chunk_key then
-        return nil, "Unknown envelope name: " .. params.envelopeName .. ". Use Volume, Pan, Mute, Width, or Trim Volume"
-      end
-      -- Get track chunk, insert envelope chunk if missing
-      -- Use anchored pattern "<VOLENV\n" to avoid matching VOLENV2 (Trim Volume)
-      local _, chunk = reaper.GetTrackStateChunk(track, "", false)
-      if not chunk:find("<" .. chunk_key .. "\n") then
-        -- Insert a minimal envelope chunk before the closing >
-        local env_chunk = "\n<" .. chunk_key .. "\nACT 1 -1\nVIS 1 1 1\nLANEHEIGHT 0 0\nARM 0\nDEFSHAPE 0 -1 -1\n>\n"
-        -- Use position capture to find the last ">" (closing the <TRACK block).
-        -- We cannot use "\n>$" because GetTrackStateChunk may include a trailing newline.
-        local last_gt = chunk:match(".*()>")
-        if last_gt then
-          chunk = chunk:sub(1, last_gt - 1) .. env_chunk .. chunk:sub(last_gt)
-        end
-        reaper.SetTrackStateChunk(track, chunk, false)
-      else
-        -- Envelope exists in chunk but may be hidden; make it visible
-        chunk = chunk:gsub("(<" .. chunk_key .. "[^\n]*\n)ACT 0", "%1ACT 1")
-        chunk = chunk:gsub("(<" .. chunk_key .. "[^\n]*\n[^\n]*\n)VIS 0", "%1VIS 1")
-        reaper.SetTrackStateChunk(track, chunk, false)
-      end
-      env = reaper.GetTrackEnvelopeByName(track, params.envelopeName)
-      if not env then
-        return nil, "Failed to create envelope: " .. params.envelopeName
-      end
-    else
-      -- Envelope exists, ensure it's visible and active
-      local _, chunk = reaper.GetEnvelopeStateChunk(env, "", false)
-      chunk = chunk:gsub("ACT 0", "ACT 1")
-      chunk = chunk:gsub("VIS 0", "VIS 1")
-      reaper.SetEnvelopeStateChunk(env, chunk, false)
-    end
-    env_name = params.envelopeName
-  else
-    return nil, "Must provide either envelopeName or fxIndex+paramIndex"
-  end
+function handlers.create_track_envelope(params) return env_ext.run("create", params) end
 
-  -- Find the index of the newly created envelope
-  local env_count = reaper.CountTrackEnvelopes(track)
-  local env_index = -1
-  for i = 0, env_count - 1 do
-    if reaper.GetTrackEnvelope(track, i) == env then
-      env_index = i
-      break
-    end
+-- Mixing depth (mcp_mixing_lib.lua): automation modes, FX parameter modulation, pins,
+-- monitoring FX, freeze / render in place, stretch markers. Nested params arrive as JSON strings.
+-- Lib wrappers added since the main chunk reached the 200-locals limit live here, one field each
+ext.mix = {}
+ext.mix.ok, ext.mix.lib = pcall(dofile, script_dir .. "mcp_mixing_lib.lua")
+
+function ext.mix.decode(v)
+  if type(v) ~= "string" then return v end
+  local ok, res = pcall(plan_lib.json_decode, v)
+  if ok then return res end
+  return nil
+end
+
+function ext.mix.run(name, ...)
+  if not ext.mix.ok then
+    return nil, "mcp_mixing_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. tostring(ext.mix.lib) .. ")"
   end
+  local ok, res, err = pcall(ext.mix.lib[name], reaper, ...)
+  if not ok then return nil, "Handler error: " .. tostring(res) end
+  return res, err
+end
 
-  reaper.Undo_EndBlock("MCP: Create envelope '" .. (env_name or "") .. "'", -1)
-  reaper.MarkProjectDirty(0)
-  reaper.TrackList_AdjustWindows(false)
-  reaper.UpdateArrange()
+function ext.mix.tracks(params)
+  params.tracks = ext.mix.decode(params.tracks)
+  return params
+end
 
-  return {
-    trackIndex = params.trackIndex,
-    envelopeIndex = env_index,
-    name = env_name,
-    pointCount = reaper.CountEnvelopePoints(env),
-  }
+function handlers.set_automation_mode(params)
+  return ext.mix.run("set_automation_mode", plan_lib.resolve_track, ext.mix.tracks(params))
+end
+function handlers.get_fx_param_modulation(params) return ext.mix.run("get_modulation", params) end
+function handlers.set_fx_param_modulation(params)
+  return ext.mix.run("set_modulation", params, {
+    enabled = params.enabled, baseline = params.baseline,
+    lfo = ext.mix.decode(params.lfo), audio = ext.mix.decode(params.audio), link = ext.mix.decode(params.link),
+  })
 end
+function handlers.get_fx_pins(params) return ext.mix.run("get_pins", params) end
+function handlers.set_fx_pins(params)
+  return ext.mix.run("set_pins", params, ext.mix.decode(params.inputs), ext.mix.decode(params.outputs))
+end
+function handlers.list_monitoring_fx() return ext.mix.run("list_monitoring_fx") end
+function handlers.add_monitoring_fx(params) return ext.mix.run("add_monitoring_fx", params, ext.mix.decode(params.params)) end
+function handlers.set_monitoring_fx(params) return ext.mix.run("set_monitoring_fx", params, ext.mix.decode(params.params)) end
+function handlers.remove_monitoring_fx(params) return ext.mix.run("remove_monitoring_fx", params) end
+function handlers.freeze_tracks(params) return ext.mix.run("freeze_tracks", plan_lib.resolve_track, ext.mix.tracks(params)) end
+function handlers.unfreeze_tracks(params) return ext.mix.run("unfreeze_tracks", plan_lib.resolve_track, ext.mix.tracks(params)) end
+function handlers.apply_fx_to_items(params) return ext.mix.run("apply_fx_to_items", params, ext.mix.decode(params.items)) end
+function handlers.add_stretch_markers(params) return ext.mix.run("add_stretch_markers", params, ext.mix.decode(params.markers)) end
+function handlers.quantize_audio(params) return ext.mix.run("quantize_stretch", params, ext.mix.decode(params.hits)) end
+function handlers.edit_stretch_markers(params) return ext.mix.run("edit_stretch_markers", params, ext.mix.decode(params.edits)) end
+function handlers.align_audio_to_guide(params) return ext.mix.run("align_stretch", params, ext.mix.decode(params.pairs)) end
 
 function handlers.set_envelope_properties(params)
   local track = reaper.GetTrack(0, params.trackIndex)
@@ -3370,12 +4233,18 @@ function handlers.set_envelope_properties(params)
 
   if reaper.BR_EnvAlloc then
     -- SWS extension available: use BR_Env* functions
+    -- BR_EnvSetProperties needs active, visible, armed, inLane, laneHeight, defaultShape and
+    -- faderScaling; pass the current values back for everything not being changed.
     local br_env = reaper.BR_EnvAlloc(env, false)
-    local cur_active, cur_visible, cur_armed = reaper.BR_EnvGetProperties(br_env)
-    local new_active = params.active ~= nil and params.active or cur_active
-    local new_visible = params.visible ~= nil and params.visible or cur_visible
-    local new_armed = params.armed ~= nil and params.armed or cur_armed
-    reaper.BR_EnvSetProperties(br_env, new_active, new_visible, new_armed, false)
+    local cur = { reaper.BR_EnvGetProperties(br_env) }
+    local function pick(v, current) if v == nil then return current end return v end
+    local args = {
+      pick(params.active, cur[1]), pick(params.visible, cur[2]), pick(params.armed, cur[3]),
+      cur[4], cur[5], cur[6], cur[11],
+    }
+    local n = 7
+    if cur[12] ~= nil then n = 8; args[8] = cur[12] end -- automationItemsOptions (newer SWS)
+    reaper.BR_EnvSetProperties(br_env, table.unpack(args, 1, n))
     reaper.BR_EnvFree(br_env, true) -- commit=true
   else
     -- Fallback: modify envelope state chunk directly
@@ -3419,91 +4288,105 @@ function handlers.set_envelope_properties(params)
 end
 
 function handlers.clear_envelope(params)
-  local track = reaper.GetTrack(0, params.trackIndex)
-  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
-  local env_count = reaper.CountTrackEnvelopes(track)
-  if params.envelopeIndex >= env_count then
-    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
-  end
-  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
-  local prev_count = reaper.CountEnvelopePoints(env)
-  -- Delete all points by using a range from -infinity to +infinity
-  reaper.Undo_BeginBlock()
-  reaper.DeleteEnvelopePointRange(env, -math.huge, math.huge)
-  reaper.Envelope_SortPoints(env)
-  reaper.Undo_EndBlock("MCP: Clear envelope", -1)
-  return {
-    trackIndex = params.trackIndex,
-    envelopeIndex = params.envelopeIndex,
-    deletedPoints = prev_count,
-    totalPoints = reaper.CountEnvelopePoints(env),
-  }
+  return env_ext.run("remove_range", { trackIndex = params.trackIndex, envelopeIndex = params.envelopeIndex,
+    automationItemIndex = params.automationItemIndex }, "MCP: Clear envelope")
 end
 
 function handlers.remove_envelope_points(params)
-  local track = reaper.GetTrack(0, params.trackIndex)
-  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
-  local env_count = reaper.CountTrackEnvelopes(track)
-  if params.envelopeIndex >= env_count then
-    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
-  end
-  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
-  local prev_count = reaper.CountEnvelopePoints(env)
-  reaper.Undo_BeginBlock()
-  reaper.DeleteEnvelopePointRange(env, params.timeStart, params.timeEnd)
-  reaper.Envelope_SortPoints(env)
-  reaper.Undo_EndBlock("MCP: Remove envelope points", -1)
-  local new_count = reaper.CountEnvelopePoints(env)
-  return {
-    trackIndex = params.trackIndex,
-    envelopeIndex = params.envelopeIndex,
-    timeStart = params.timeStart,
-    timeEnd = params.timeEnd,
-    deletedPoints = prev_count - new_count,
-    totalPoints = new_count,
-  }
+  return env_ext.run("remove_range", params, "MCP: Remove envelope points")
 end
 
-function handlers.insert_envelope_points(params)
-  local track = reaper.GetTrack(0, params.trackIndex)
-  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
-  local env_count = reaper.CountTrackEnvelopes(track)
-  if params.envelopeIndex >= env_count then
-    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
-  end
-  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+function handlers.list_automation_items(params) return env_ext.run("list_items", params) end
 
-  -- Parse the points JSON string
-  local points_str = params.points
-  local points = nil
-  if type(points_str) == "string" then
-    points = json_decode(points_str)
-  elseif type(points_str) == "table" then
-    points = points_str
+function handlers.insert_automation_item(params)
+  local points
+  if params.points ~= nil then
+    points = env_ext.list(params.points)
+    if not points then return nil, "Failed to parse points JSON" end
   end
-  if not points then return nil, "Failed to parse points JSON" end
+  return env_ext.run("insert_item", params, points)
+end
 
-  local inserted = 0
-  reaper.Undo_BeginBlock()
-  for _, pt in ipairs(points) do
-    if pt.time and pt.value then
-      local shape = pt.shape or 0
-      local tension = pt.tension or 0
-      reaper.InsertEnvelopePoint(env, pt.time, pt.value, shape, tension, false, true)
-      inserted = inserted + 1
+function handlers.set_automation_item(params) return env_ext.run("set_item", params) end
+
+function handlers.delete_automation_item(params) return env_ext.run("delete_item", params) end
+
+-- =============================================================================
+-- MIDI composition: quantize, transform, file import, pitch profile
+-- =============================================================================
+
+-- Logic in mcp_midi_lib.lua; one table for the 200-locals limit. Nested params (note
+-- indexes, the velocity/humanize/length objects, an import's tracks) travel as JSON strings.
+ext.midi = {}
+ext.midi.ok, ext.midi.lib = pcall(dofile, script_dir .. "mcp_midi_lib.lua")
+
+function ext.midi.run(name, params)
+  if not ext.midi.ok then
+    return nil, "mcp_midi_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. tostring(ext.midi.lib) .. ")"
+  end
+  local p = {}
+  for k, v in pairs(params) do p[k] = v end
+  for _, k in ipairs({ "notes", "velocity", "humanize", "length", "tracks" }) do
+    if type(p[k]) == "string" then
+      if not plan_lib_ok then return nil, "mcp_plan_lib.lua is not installed — run `reaper-mcp setup`" end
+      local val, err = plan_lib.json_decode(p[k])
+      if type(val) ~= "table" then return nil, k .. " is not valid JSON" .. (err and (" (" .. tostring(err) .. ")") or "") .. " — nothing changed" end
+      p[k] = val
     end
   end
+  local ok, res, err = pcall(ext.midi.lib[name], reaper, p)
+  if not ok then return nil, "Handler error: " .. tostring(res) end
+  return res, err
+end
 
-  reaper.Envelope_SortPoints(env)
-  reaper.Undo_EndBlock("MCP: Insert " .. inserted .. " envelope points", -1)
-  return {
-    trackIndex = params.trackIndex,
-    envelopeIndex = params.envelopeIndex,
-    insertedPoints = inserted,
-    totalPoints = reaper.CountEnvelopePoints(env),
-  }
+function handlers.quantize_midi(params) return ext.midi.run("quantize", params) end
+function handlers.transform_midi(params) return ext.midi.run("transform", params) end
+function handlers.import_midi_file(params) return ext.midi.run("import", params) end
+-- Internal (detect_key on a MIDI track): not logged, not counted, but refused while paused,
+-- since it answers an agent's tool call (a read, so read-only mode allows it)
+handlers["_midi_pitch_profile"] = function(params) return ext.midi.run("pitch_profile", params) end
+-- Internal, likewise: detect_chords' bar/beat grid (+ MIDI profiles), and an item's range (itemIndex)
+handlers["_chord_grid"] = function(params) return ext.midi.run("chord_grid", params) end
+handlers["_item_range"] = function(params) return ext.midi.run("item_range", params) end
+ext.paused_too = { _midi_pitch_profile = true, _chord_grid = true, _item_range = true }
+
+-- =============================================================================
+-- Arrangement: copy items, insert/remove time, copy a section, process items
+-- =============================================================================
+
+-- Logic in mcp_arrange_lib.lua (one table, like env_ext: the main chunk is at the locals limit)
+ext.arrange = {}
+ext.arrange.ok, ext.arrange.lib = pcall(dofile, script_dir .. "mcp_arrange_lib.lua")
+plan_ctx.arrange = ext.arrange.ok and ext.arrange.lib or nil
+
+-- `items` / `tracks` arrive as JSON strings (the bridge decodes only the top level)
+function ext.arrange.run(name, params)
+  if not ext.arrange.ok then
+    return nil, "mcp_arrange_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. tostring(ext.arrange.lib) .. ")"
+  end
+  for _, key in ipairs({ "items", "tracks" }) do
+    if type(params[key]) == "string" then
+      if not plan_lib_ok then return nil, "mcp_plan_lib.lua is not installed next to mcp_bridge.lua" end
+      local ok, v = pcall(plan_lib.json_decode, params[key])
+      if not ok or type(v) ~= "table" then return nil, key .. " is not a JSON array — nothing changed" end
+      params[key] = v
+    end
+  end
+  local ok, res, err = pcall(ext.arrange.lib[name], reaper, params)
+  if not ok then return nil, "Handler error: " .. tostring(res) end
+  return res, err
 end
 
+function handlers.copy_media_items(params) return ext.arrange.run("copy_items", params) end
+
+function handlers.insert_time(params) return ext.arrange.run("insert_time", params) end
+
+function handlers.remove_time(params) return ext.arrange.run("remove_time", params) end
+
+function handlers.copy_section(params) return ext.arrange.run("copy_section", params) end
+
+function handlers.process_items(params) return ext.arrange.run("process_items", params) end
+
 -- =============================================================================
 -- Live MIDI output handlers
 -- =============================================================================
@@ -3617,190 +4500,64 @@ function handlers.send_midi_note(params)
 end
 
 -- =============================================================================
--- render_track_to_wav handler
+-- render_track_to_wav / render_tracks_to_wav handlers
 --
--- Renders a target track's output (post-FX, post-fader) to a temp WAV file.
--- Saves and restores all render settings and solo states around the render.
--- Blocks the defer loop during render (~0.5-1s) — this is by design.
+-- Render tracks' output (post-FX, post-fader) to temp WAVs for the analysis tools. The logic is in
+-- mcp_render_lib.lua: it caches renders until the project changes, renders several tracks in one
+-- pass and hands focus back after a render (REAPER's progress window takes it). One table, not
+-- separate locals: the bridge's main chunk is at Lua's 200-locals limit.
 --
--- Params:
---   trackIndex  (number) — zero-based track index
---   startTime   (number) — render start, seconds from project start
---   endTime     (number) — render end, seconds from project start
---   commandId   (string) — used to generate a unique temp filename
---
--- Returns:
---   { trackIndex, trackName, wavPath, durationSeconds, sampleRate, channelCount }
+-- render_track_to_wav params: trackIndex (-1 = master), startTime, endTime (seconds), commandId,
+--   fresh (skip the cache), restoreFocus (false: leave focus where the render put it)
+--   -> { trackIndex, trackName, wavPath, durationSeconds, sampleRate, channelCount,
+--        playOffsetMs, phaseInverted, cached, cacheOwned }
+-- render_tracks_to_wav: the same with trackIndices (JSON array) -> { tracks, rendered, cached }
 -- =============================================================================
 
-function handlers.render_track_to_wav(params)
-  local track_index = params.trackIndex
-  local start_time  = params.startTime
-  local end_time    = params.endTime
-  local command_id  = params.commandId or tostring(os.time())
-
-  -- Validate inputs
-  if track_index == nil then
-    return nil, "Missing required param: trackIndex"
-  end
-  if start_time == nil or end_time == nil then
-    return nil, "Missing required params: startTime, endTime"
-  end
-  if end_time <= start_time then
-    return nil, "endTime must be greater than startTime"
-  end
+ext.render = {}
+ext.render.ok, ext.render.lib = pcall(dofile, script_dir .. "mcp_render_lib.lua")
 
-  -- Get track
-  local track = reaper.GetTrack(0, track_index)
-  if not track then
-    return nil, "Track " .. tostring(track_index) .. " not found"
+function ext.render.run(name, params)
+  if not ext.render.ok then
+    return nil, "mcp_render_lib.lua is not installed next to mcp_bridge.lua — run `reaper-mcp setup` and restart the bridge (" .. tostring(ext.render.lib) .. ")"
   end
-  local track_name = ({reaper.GetSetMediaTrackInfo_String(track, "P_NAME", "", false)})[2] or ""
-  if track_name == "" then track_name = "Track " .. (track_index + 1) end
-
-  -- Render target is always 44100 Hz (WAV for sidecar inference).
-  -- The actual project sample rate is irrelevant here; Audiobox resamples internally.
-  local sample_rate = 44100
-
-  -- Build unique temp file path
-  -- Use GetTempPath() if available (REAPER 6.29+), fall back to os.tmpname pattern
-  local temp_dir
-  if reaper.GetTempPath then
-    temp_dir = reaper.GetTempPath()
-  else
-    -- Fallback: derive temp dir from os.tmpname()
-    local t = os.tmpname()
-    temp_dir = t:match("^(.+)[/\\][^/\\]+$") or "/tmp"
-    os.remove(t)
-  end
-
-  -- Ensure temp dir ends with separator
-  if temp_dir:sub(-1) ~= "/" and temp_dir:sub(-1) ~= "\\" then
-    temp_dir = temp_dir .. "/"
-  end
-
-  local wav_filename = "mcp_aes_" .. command_id:gsub("-", ""):sub(1, 16) .. ".wav"
-  local wav_path = temp_dir .. wav_filename
-
-  -- -------------------------------------------------------------------------
-  -- Save current render settings
-  -- -------------------------------------------------------------------------
-  local saved_file     = ({reaper.GetSetProjectInfo_String(0, "RENDER_FILE",       "", false)})[2] or ""
-  local saved_pattern  = ({reaper.GetSetProjectInfo_String(0, "RENDER_PATTERN",    "", false)})[2] or ""
-  local saved_format   = ({reaper.GetSetProjectInfo_String(0, "RENDER_FORMAT",     "", false)})[2] or ""
-  local saved_bounds   = reaper.GetSetProjectInfo(0, "RENDER_BOUNDSFLAG", 0, false)
-  local saved_settings = reaper.GetSetProjectInfo(0, "RENDER_SETTINGS",   0, false)
-  local saved_start    = reaper.GetSetProjectInfo(0, "RENDER_STARTPOS",   0, false)
-  local saved_end      = reaper.GetSetProjectInfo(0, "RENDER_ENDPOS",     0, false)
-  local saved_srate    = reaper.GetSetProjectInfo(0, "RENDER_SRATE",      0, false)
-  local saved_channels = reaper.GetSetProjectInfo(0, "RENDER_CHANNELS",   0, false)
-
-  -- Save solo states for all tracks
-  local track_count = reaper.CountTracks(0)
-  local saved_solo_states = {}
-  for i = 0, track_count - 1 do
-    local t = reaper.GetTrack(0, i)
-    saved_solo_states[i] = reaper.GetMediaTrackInfo_Value(t, "I_SOLO")
-  end
-
-  -- -------------------------------------------------------------------------
-  -- Apply render settings
-  -- -------------------------------------------------------------------------
-  local ok, restore_err = pcall(function()
-    -- Set output: render to temp dir with unique filename (no extension in pattern)
-    reaper.GetSetProjectInfo_String(0, "RENDER_FILE",    temp_dir,     true)
-    reaper.GetSetProjectInfo_String(0, "RENDER_PATTERN", wav_filename:match("^(.+)%.wav$") or wav_filename, true)
-
-    -- Set render bounds: 0 = custom time range
-    reaper.GetSetProjectInfo(0, "RENDER_BOUNDSFLAG", 0, true)
-    reaper.GetSetProjectInfo(0, "RENDER_STARTPOS", start_time, true)
-    reaper.GetSetProjectInfo(0, "RENDER_ENDPOS",   end_time,   true)
-
-    -- Set render mode: 2 = stems (selected tracks via master mix / solo)
-    reaper.GetSetProjectInfo(0, "RENDER_SETTINGS", 2, true)
-
-    -- Force WAV at 44100 Hz stereo so the sidecar always gets a known format,
-    -- independent of whatever the user last rendered. Restored in finally.
-    -- "evaw" is the little-endian "wave" fourcc REAPER uses for WAV format.
-    reaper.GetSetProjectInfo_String(0, "RENDER_FORMAT", "evaw", true)
-    reaper.GetSetProjectInfo(0, "RENDER_SRATE",    sample_rate, true)
-    reaper.GetSetProjectInfo(0, "RENDER_CHANNELS", 2,           true)
-
-    -- Unsolo all tracks, then solo only the target track
-    for i = 0, track_count - 1 do
-      local t = reaper.GetTrack(0, i)
-      reaper.SetMediaTrackInfo_Value(t, "I_SOLO", 0)
-    end
-    reaper.SetMediaTrackInfo_Value(track, "I_SOLO", 1)
-
-    -- Trigger render: action 42230 = "Render project, using the most recent render settings, auto-close render dialog"
-    -- This call is synchronous — it blocks the defer loop until rendering completes.
-    reaper.Main_OnCommand(42230, 0)
-  end)
-
-  -- -------------------------------------------------------------------------
-  -- Restore all settings and solo states (always, even on error)
-  -- -------------------------------------------------------------------------
-  local restore_ok, restore_err2 = pcall(function()
-    reaper.GetSetProjectInfo_String(0, "RENDER_FILE",       saved_file,     true)
-    reaper.GetSetProjectInfo_String(0, "RENDER_PATTERN",    saved_pattern,  true)
-    reaper.GetSetProjectInfo_String(0, "RENDER_FORMAT",     saved_format,   true)
-    reaper.GetSetProjectInfo(0, "RENDER_BOUNDSFLAG", saved_bounds,   true)
-    reaper.GetSetProjectInfo(0, "RENDER_SETTINGS",   saved_settings, true)
-    reaper.GetSetProjectInfo(0, "RENDER_STARTPOS",   saved_start,    true)
-    reaper.GetSetProjectInfo(0, "RENDER_ENDPOS",     saved_end,      true)
-    reaper.GetSetProjectInfo(0, "RENDER_SRATE",      saved_srate,    true)
-    reaper.GetSetProjectInfo(0, "RENDER_CHANNELS",   saved_channels, true)
-    for i = 0, track_count - 1 do
-      local t = reaper.GetTrack(0, i)
-      reaper.SetMediaTrackInfo_Value(t, "I_SOLO", saved_solo_states[i] or 0)
-    end
-  end)
+  local ok, res, err = pcall(ext.render.lib[name], reaper, params)
+  if not ok then return nil, "Handler error: " .. tostring(res) end
+  return res, err
+end
 
-  if not restore_ok then
-    -- Log but don't fail — the render may have succeeded
-    reaper.ShowConsoleMsg("[reaper-mcp] Warning: failed to restore render settings: " .. tostring(restore_err2) .. "\n")
-  end
+function handlers.render_track_to_wav(params)
+  return ext.render.run("render_track", params)
+end
 
-  if not ok then
-    return nil, "Render failed: " .. tostring(restore_err)
-  end
-
-  -- Verify the file was actually created.
-  -- RENDER_PATTERN was set without the .wav extension so REAPER appends it;
-  -- wav_path already has the full expected name including the extension.
-  local f = io.open(wav_path, "rb")
-  if not f then
-    return nil, "Render produced no output file at: " .. wav_path
-  end
-  -- Verify the rendered file is actually a WAV. RENDER_FORMAT was set to "evaw"
-  -- (REAPER's WAV fourcc) above; if REAPER silently ignored that value the file
-  -- could be any codec the user last rendered (MP3/FLAC/etc.). Check the RIFF
-  -- magic bytes so we fail loudly here rather than crashing in the Python sidecar
-  -- with a confusing "Cannot read audio file" error.
-  local magic = f:read(4)
-  f:close()
-  if magic ~= "RIFF" then
-    os.remove(wav_path)
-    return nil, "Render produced a non-WAV file (RENDER_FORMAT may not have been applied). " ..
-                "First 4 bytes: " .. (magic and string.format("%q", magic) or "<empty>")
+function handlers.render_tracks_to_wav(params)
+  local p = {}
+  for k, v in pairs(params) do p[k] = v end
+  -- Without CF_Json_Parse the command parser hands arrays over as a JSON string
+  if type(params.trackIndices) == "string" then
+    local list = {}
+    for n in params.trackIndices:gmatch("%-?%d+") do list[#list + 1] = tonumber(n) end
+    p.trackIndices = list
   end
-
-  local duration = end_time - start_time
-  return {
-    trackIndex     = track_index,
-    trackName      = track_name,
-    wavPath        = wav_path,
-    durationSeconds = duration,
-    sampleRate     = sample_rate,
-    channelCount   = 2,
-  }
+  return ext.render.run("render_tracks", p)
 end
 
 -- =============================================================================
 -- Bridge diagnostics handler
 -- =============================================================================
 
+-- Session ping from each MCP server (see apps/reaper-mcp-server/src/session.ts); the session itself
+-- is recorded from the command's top-level fields in record_command
+handlers["_session"] = function(params)
+  return { ok = true }
+end
+
+-- A sidecar tool's result for the status page; recorded by record_command (record_tool_result)
+handlers["_log_result"] = function(params)
+  if type(params.command) ~= "string" then return nil, "command required" end
+  return { logged = true }
+end
+
 handlers["_bridge_diagnostics"] = function(params)
   -- Compute defer interval stats from circular buffer
   local intervals = {}
@@ -3843,31 +4600,740 @@ handlers["_bridge_diagnostics"] = function(params)
 end
 
 -- =============================================================================
--- Command dispatcher
+-- Status feed (read by the web UI: reaper_www_root/mcp_bridge.html)
 -- =============================================================================
+-- Published as JSON to non-persistent ExtState (in-memory, no disk IO). The UI
+-- polls it through REAPER's web interface, so all rendering happens in the
+-- browser, outside REAPER's main thread. Publishing is throttled and only
+-- happens when something changed (plus a 1s liveness tick from the heartbeat).
+
+local STATUS_SECTION = "MCPBridge"
+local STATUS_RECENT_MAX = 50
+local STATUS_MIN_PUBLISH_INTERVAL = 0.2
+
+-- os.time() has 1s resolution; anchor time_precise() to it for ms timestamps
+local epoch_offset = os.time() - reaper.time_precise()
+local function now_ms()
+  return math.floor((reaper.time_precise() + epoch_offset) * 1000)
+end
 
-local function process_command(filename)
-  local pickup_time = reaper.time_precise()
-  local path = bridge_dir .. filename
-  local content = read_file(path)
-  if not content then return end
+local status = {
+  startedAt = now_ms(),
+  commands = 0,
+  errors = 0,
+  recent = {}, -- newest first
+}
+local status_dirty = true
+local last_status_publish = 0
+
+-- Agent sessions (one per MCP server process): commands carry sessionId/sessionDir/sessionClient,
+-- and each server pings `_session` every 20s so idle agents still show as connected.
+local SESSIONS_MAX = 20
+local SESSION_FORGET_S = 3600
+local sessions = {}
+
+local function touch_session(cmd, ok, failed)
+  local id = cmd.sessionId
+  if type(id) ~= "string" or id == "" then return nil end
+  local s = sessions[id]
+  local t = now_ms()
+  if not s then
+    s = { id = id, first = t, commands = 0, errors = 0 }
+    sessions[id] = s
+  end
+  s.last = t
+  if type(cmd.sessionDir) == "string" and cmd.sessionDir ~= "" then s.dir = cmd.sessionDir end
+  if type(cmd.sessionClient) == "string" and cmd.sessionClient ~= "" then s.client = cmd.sessionClient end
+  s.ended = nil
+  if ok ~= nil then
+    s.commands = s.commands + 1
+    if failed then s.errors = s.errors + 1 end
+  end
+  status_dirty = true
+  return s
+end
 
-  local cmd = json_decode(content)
-  if not cmd or not cmd.id or not cmd.type then
-    -- Invalid command, remove file
-    os.remove(path)
+local function session_list()
+  local list, cutoff = {}, now_ms() - SESSION_FORGET_S * 1000
+  for id, s in pairs(sessions) do
+    if s.last < cutoff then sessions[id] = nil else list[#list + 1] = s end
+  end
+  table.sort(list, function(a, b) return a.last > b.last end)
+  for i = SESSIONS_MAX + 1, #list do
+    sessions[list[i].id] = nil
+    list[i] = nil
+  end
+  return list
+end
+
+-- Settings written by the status page through REAPER's web interface (/_/SET/EXTSTATE...).
+-- cfg_paused is in-memory only (resets with REAPER); the others persist in reaper-extstate.ini.
+local function cfg(key)
+  return reaper.GetExtState(STATUS_SECTION, key) == "1"
+end
+
+-- Read-only mode lets agents inspect and audition but never change the project
+local READONLY_PREFIXES = { "get_", "list_", "read_", "analyze_", "search_", "measure_" }
+local READONLY_ALLOW = {
+  snapshot_list = true, render_track_to_wav = true, render_tracks_to_wav = true,
+  play = true, stop = true, set_cursor_position = true, set_time_selection = true,
+}
+local function readonly_allows(cmd_type)
+  if READONLY_ALLOW[cmd_type] then return true end
+  for _, p in ipairs(READONLY_PREFIXES) do
+    if cmd_type:sub(1, #p) == p then return true end
+  end
+  return false
+end
+
+-- Setup health and staleness, re-checked every 10s (cheap: one file read + a few stats)
+-- Read at load: inside deferred callbacks get_action_context no longer describes this script's launch
+local _, script_path, _, script_cmd_id = reaper.get_action_context()
+local script_source = script_path and read_file(script_path)
+local HEALTH_INTERVAL = 10
+local last_health_check = -HEALTH_INTERVAL
+local health = { sws = false, jsfx = true, outdated = false }
+local JSFX_FILES = { "mcp_analyzer.jsfx", "mcp_lufs_meter.jsfx", "mcp_correlation_meter.jsfx", "mcp_crest_factor.jsfx", "mcp_midi_emitter.jsfx" }
+
+local function check_health(now)
+  if now - last_health_check < HEALTH_INTERVAL then return end
+  last_health_check = now
+  local fx_dir = reaper.GetResourcePath() .. "/Effects/reaper-mcp/"
+  local missing = {}
+  for _, f in ipairs(JSFX_FILES) do
+    if not file_exists(fx_dir .. f) then missing[#missing + 1] = f end
+  end
+  local installed = script_path and read_file(script_path)
+  local next_health = {
+    sws = type(reaper.CF_GetSWSVersion) == "function",
+    jsfx = #missing == 0,
+    missingJsfx = #missing > 0 and missing or nil,
+    -- The installed script changed under us (setup ran): this running copy is stale until restarted
+    outdated = script_source ~= nil and installed ~= nil and installed ~= script_source,
+  }
+  if next_health.sws ~= health.sws or next_health.jsfx ~= health.jsfx or next_health.outdated ~= health.outdated then
+    status_dirty = true
+  end
+  health = next_health
+end
+
+-- Self-update and restart, requested from the status page with one click.
+-- The page writes ExtState MCPBridge/request = "<update|restart>-<token>" through REAPER's web interface.
+-- The token is random per run and only readable from the status feed: REAPER's web server sends no CORS
+-- headers, so another website can fire a SET at localhost but can't read the token to make it count.
+-- Updating runs <clone>/scripts/update.sh (git pull --ff-only + install.sh) detached, so REAPER never blocks;
+-- `reaper-mcp setup` writes mcp_update.conf (clone path + node binary) next to this script.
+math.randomseed(math.floor(reaper.time_precise() * 1e6) % 2147483647)
+local control_token = string.format("%08x%08x", math.random(0, 0x7fffffff), math.random(0, 0x7fffffff))
+local is_windows = (reaper.GetOS and reaper.GetOS() or ""):match("^Win") ~= nil
+local UPDATE_LOG = bridge_dir .. "update.log"
+local UPDATE_EXIT = bridge_dir .. "update.exit"
+local SOURCE_CHANGES = bridge_dir .. "source_changes"
+local update = nil -- { state = "running" | "failed" | "done", startedAt, log = { lines } }
+local last_update_poll = 0
+
+-- REAPER 7.03+: re-running this script stops it and starts the (possibly newer) installed copy
+local can_restart = type(reaper.set_action_options) == "function" and type(script_cmd_id) == "number" and script_cmd_id > 0
+-- Running the script again stops it (1: terminate when re-launched); only a restart the bridge asks for itself
+-- adds 2 (then start again), so a user re-running mcp_bridge.lua turns it off instead of getting a new window
+if can_restart then reaper.set_action_options(1) end
+
+local function update_config()
+  local text = read_file(script_dir .. "mcp_update.conf")
+  if not text then return nil end
+  local conf = {}
+  for key, value in text:gmatch("([%w_]+)=([^\r\n]*)") do conf[key] = value end
+  if not conf.repo or conf.repo == "" or not file_exists(conf.repo .. "/scripts/update.sh") then return nil end
+  return conf
+end
+
+local function restart_bridge()
+  log_event("bridge_restart", {})
+  reaper.set_action_options(3)
+  reaper.Main_OnCommand(script_cmd_id, 0)
+end
+
+local function shell_quote(s)
+  return "'" .. s:gsub("'", "'\\''") .. "'"
+end
+
+-- kind "update": pull the latest version and reinstall; "rebuild": developers, build the working tree as it is
+local function start_update(kind)
+  if is_windows or (update and update.state == "running") then return end
+  local conf = update_config()
+  if not conf then return end
+  os.remove(UPDATE_LOG)
+  os.remove(UPDATE_EXIT)
+  -- REAPER started from the Dock has a bare PATH: put the node that ran setup (and its pnpm/corepack) first
+  local node_dir = conf.node and conf.node:match("^(.*)/[^/]+$")
+  local path = (node_dir and (shell_quote(node_dir) .. ":") or "") .. "/opt/homebrew/bin:/usr/local/bin:$PATH"
+  os.execute("( cd " .. shell_quote(conf.repo) .. " && PATH=" .. path .. " ./scripts/update.sh" .. (kind == "rebuild" and " --rebuild" or "") .. " < /dev/null > " .. shell_quote(UPDATE_LOG)
+    .. " 2>&1; echo $? > " .. shell_quote(UPDATE_EXIT) .. " ) >/dev/null 2>&1 &")
+  update = { kind = kind, state = "running", startedAt = now_ms(), log = {} }
+  log_event("bridge_update_start", { kind = kind })
+  status_dirty = true
+end
+
+-- Last lines of the update log, without colors or carriage-return progress redraws
+local function update_log_tail(max)
+  local text = read_file(UPDATE_LOG) or ""
+  local lines = {}
+  for line in text:gmatch("[^\n]+") do
+    line = line:gsub("\27%[[%d;]*%a", ""):match("([^\r]*)\r*$") or ""
+    if line:match("%S") then lines[#lines + 1] = line end
+  end
+  local tail = {}
+  for i = math.max(1, #lines - max + 1), #lines do tail[#tail + 1] = lines[i] end
+  return tail
+end
+
+local function check_control(now)
+  local request = reaper.GetExtState(STATUS_SECTION, "request")
+  if request and request ~= "" then
+    reaper.DeleteExtState(STATUS_SECTION, "request", false)
+    local action, token = request:match("^(%a+)%-(%x+)$")
+    if token == control_token then
+      if action == "update" or action == "rebuild" then start_update(action)
+      elseif action == "restart" and can_restart then restart_bridge() return end
+    end
+  end
+  if not update or update.state ~= "running" or now - last_update_poll < 1 then return end
+  last_update_poll = now
+  local log = update_log_tail(12)
+  if #log ~= #update.log or log[#log] ~= update.log[#update.log] then
+    update.log = log
+    status_dirty = true
+  end
+  local code = read_file(UPDATE_EXIT)
+  if not code then return end
+  code = tonumber(code:match("%d+"))
+  update.state = code == 0 and "done" or "failed"
+  if update.state == "done" then os.remove(SOURCE_CHANGES) end -- re-checked against the new install
+  log_event("bridge_update_end", { exitCode = code })
+  status_dirty = true
+  -- The installer replaced this script: load the new copy (the page reloads when startedAt changes)
+  if update.state == "done" and can_restart then
+    local installed = script_path and read_file(script_path)
+    if installed and installed ~= script_source then restart_bridge() end
+  end
+end
+
+-- What the status page may offer: published in the status feed together with the token
+local can_update, conf_dev, last_can_update_check = false, false, -10
+local function refresh_update_config()
+  local now = reaper.time_precise()
+  if now - last_can_update_check < 10 then return end
+  last_can_update_check = now
+  local conf = not is_windows and update_config() or nil
+  can_update, conf_dev = conf ~= nil, conf ~= nil and conf.dev == "1"
+end
+
+-- Developer mode: the page's toggle (cfg_dev "1"/"0") once chosen, else what setup detected (dev=1 in mcp_update.conf)
+local function dev_mode()
+  refresh_update_config()
+  local v = reaper.GetExtState(STATUS_SECTION, "cfg_dev")
+  if v == nil or v == "" then return conf_dev end
+  return v == "1"
+end
+
+-- Developer mode: whether the clone has source files newer than the last install (setup rewrites
+-- mcp_update.conf, so its mtime marks it). find runs detached every few seconds and leaves the first
+-- match in SOURCE_CHANGES; git and the file walk stay off REAPER's main thread.
+local SOURCE_CHECK_INTERVAL = 5
+local source_changed, last_source_check = false, -SOURCE_CHECK_INTERVAL
+local function check_source_changes(now)
+  if is_windows or now - last_source_check < SOURCE_CHECK_INTERVAL or not dev_mode() or not can_update then return end
+  if update and update.state == "running" then return end
+  last_source_check = now
+  local changed = (read_file(SOURCE_CHANGES) or ""):match("%S") ~= nil
+  if changed ~= source_changed then
+    source_changed = changed
+    status_dirty = true
+  end
+  local conf = update_config()
+  if not conf then return end
+  local tmp = shell_quote(SOURCE_CHANGES .. ".tmp")
+  os.execute("( cd " .. shell_quote(conf.repo) .. " && find apps libs reaper knowledge scripts .claude package.json pnpm-lock.yaml"
+    .. " \\( -name node_modules -o -name dist -o -name .nx -o -name __pycache__ -o -name .DS_Store -o -name '*.tsbuildinfo' -o -name '*.timestamp-*' \\) -prune"
+    .. " -o -type f -newer " .. shell_quote(script_dir .. "mcp_update.conf") .. " -print -quit > " .. tmp .. " 2>/dev/null;"
+    .. " mv " .. tmp .. " " .. shell_quote(SOURCE_CHANGES) .. " ) >/dev/null 2>&1 &")
+end
+
+local function control_status()
+  refresh_update_config()
+  return {
+    token = control_token,
+    canRestart = can_restart,
+    canUpdate = can_update,
+    -- Developer mode: source changed since the last install, so Rebuild & reload has something to do
+    changed = source_changed,
+    update = update,
+    -- The page may list, restore and save snapshots (mcp_snapshots_ui_lib.lua)
+    snapshots = snaps_lib_ok,
+    -- The page keeps its LoreKit tokens in ~/.config/reaper-mcp (mcp_prefs_lib.lua)
+    sharedTokens = ext.prefs ~= nil,
+  }
+end
+
+-- Installed FX for the status page's Plugins view, in ExtState MCPBridge/installed (in memory).
+-- Re-enumerated every 60s (a few ms for ~2k plugins) and republished only when the list changed.
+local INSTALLED_FX_INTERVAL = 60
+local last_installed_fx = -INSTALLED_FX_INTERVAL
+local installed_fx_signature
+
+local function publish_installed_fx(now)
+  if now - last_installed_fx < INSTALLED_FX_INTERVAL then return end
+  last_installed_fx = now
+  local list = enumerate_installed_fx()
+  local rows, names = {}, {}
+  for i, fx in ipairs(list or {}) do
+    rows[i] = { n = fx.name, t = fx.type }
+    names[i] = fx.name
+  end
+  local signature = (list and "1" or "0") .. "\n" .. table.concat(names, "\n")
+  if signature == installed_fx_signature then return end
+  installed_fx_signature = signature
+  reaper.SetExtState(STATUS_SECTION, "installed", json_encode({ v = 1, supported = list ~= nil, fx = rows }), false)
+end
+
+-- FX used in the open project (track, master, input and take FX), in ExtState MCPBridge/used, so the
+-- Plugins view can show which plugins this session relies on. Recounted at most every 2s and only when
+-- the project changed (state change count or project tab); republished only when the counts changed.
+local USED_FX_INTERVAL = 2
+local last_used_fx = -USED_FX_INTERVAL
+local used_fx_state, used_fx_signature
+
+-- The plugin's own name ("VST3: Pro-Q 3 (FabFilter)"), not a renamed instance
+local function original_fx_name(get_named, get_name, owner, i)
+  local ok, name = get_named(owner, i, "fx_name")
+  if ok and type(name) == "string" and name ~= "" then return name end
+  local _, display = get_name(owner, i)
+  return type(display) == "string" and display ~= "" and display or nil
+end
+
+local function count_project_fx()
+  local counts = {}
+  local function add(name) if name then counts[name] = (counts[name] or 0) + 1 end end
+  local function track_fx(track)
+    if not track then return end
+    for i = 0, (reaper.TrackFX_GetCount(track) or 0) - 1 do
+      add(original_fx_name(reaper.TrackFX_GetNamedConfigParm, reaper.TrackFX_GetFXName, track, i))
+    end
+    for i = 0, (reaper.TrackFX_GetRecCount(track) or 0) - 1 do
+      add(original_fx_name(reaper.TrackFX_GetNamedConfigParm, reaper.TrackFX_GetFXName, track, 0x1000000 + i))
+    end
+  end
+  track_fx(reaper.GetMasterTrack(0))
+  for t = 0, (reaper.CountTracks(0) or 0) - 1 do track_fx(reaper.GetTrack(0, t)) end
+  for it = 0, (reaper.CountMediaItems(0) or 0) - 1 do
+    local item = reaper.GetMediaItem(0, it)
+    for k = 0, (item and reaper.CountTakes(item) or 0) - 1 do
+      local take = reaper.GetTake(item, k)
+      for i = 0, (take and reaper.TakeFX_GetCount(take) or 0) - 1 do
+        add(original_fx_name(reaper.TakeFX_GetNamedConfigParm, reaper.TakeFX_GetFXName, take, i))
+      end
+    end
+  end
+  return counts
+end
+
+local function publish_used_fx(now)
+  if now - last_used_fx < USED_FX_INTERVAL then return end
+  last_used_fx = now
+  -- Parenthesised: exactly one value, even from an API stub that returns nothing
+  local change_count = (reaper.GetProjectStateChangeCount(0))
+  local state = tostring((reaper.EnumProjects(-1))) .. ":" .. tostring(change_count)
+  -- An unknown change count (older REAPER, tests) means: recount every time
+  if state == used_fx_state and change_count ~= nil then return end
+  used_fx_state = state
+  local counts = count_project_fx()
+  local names = {}
+  for name in pairs(counts) do names[#names + 1] = name end
+  table.sort(names)
+  local rows, parts = {}, {}
+  for i, name in ipairs(names) do
+    rows[i] = { n = name, c = counts[name] }
+    parts[i] = name .. "=" .. counts[name]
+  end
+  local signature = table.concat(parts, "\n")
+  if signature == used_fx_signature then return end
+  used_fx_signature = signature
+  reaper.SetExtState(STATUS_SECTION, "used", json_encode({ v = 1, fx = rows }), false)
+end
+
+-- Command timeline at three resolutions, keyed by absolute bucket id (epoch_ms // size).
+-- Only buckets with commands exist, so idle time costs nothing.
+-- Each bucket: { total, errors, slow (ok, >= HISTORY_SLOW_MS, not LONG_RUNNING), summed handler ms }.
+-- The 10s tier is published live in ExtState `history`; the 1m and 10m tiers (for the page's
+-- day and week ranges) in `history_long`, at most every 10s. All tiers persist in history.json,
+-- saved every 30s and on exit, so the timeline survives a bridge or REAPER restart.
+local HISTORY_TIERS = {
+  { size = 10000, keep = 3600 * 1000 },
+  { size = 60000, keep = 24 * 3600 * 1000 },
+  { size = 600000, keep = 7 * 24 * 3600 * 1000 },
+}
+for _, tier in ipairs(HISTORY_TIERS) do tier.b = {} end
+local HISTORY_SLOW_MS = 100
+-- Commands whose duration is the work itself (renders, plugin loads, project IO, proxies that run
+-- arbitrary work): never counted as slow. Mirrors LONG_RUNNING in apps/bridge-ui/src/lib/commands.ts.
+local LONG_RUNNING = {}
+for _, c in ipairs({
+  "render_project", "render_track_to_wav", "render_tracks_to_wav", "render_versions", "run_plan", "run_action", "save_project", "undo_project",
+  "redo_project", "add_fx", "add_take_fx", "setup_fx_chain", "copy_fx", "move_fx", "set_fx_offline",
+  "set_fx_preset", "get_fx_preset_list", "list_available_fx", "load_fx_chain", "insert_track_template",
+  "insert_audio_file", "snapshot_save", "snapshot_restore", "snapshot_edit",
+  "analyze_track_offline", "analyze_audio_file", "measure_track_alignment", "verify_edit", "analyze_track_aesthetics",
+  "detect_transients", "create_transient_automation", "insert_stem_tracks",
+  "analyze_loudness_curve", "analyze_stereo_bands", "measure_masking", "separate_stems",
+  "transcribe_voice_sketch",
+  "freeze_tracks", "unfreeze_tracks", "apply_fx_to_items", "quantize_audio", "align_audio_to_guide", "detect_key", "detect_chords", "import_midi_file", "process_items",
+}) do LONG_RUNNING[c] = true end
+local HISTORY_MIN_PUBLISH_INTERVAL = 1.0
+local HISTORY_LONG_PUBLISH_INTERVAL = 10
+local HISTORY_SAVE_INTERVAL = 30
+local HISTORY_FILE = bridge_dir .. "history.json"
+local history_dirty, history_long_dirty, history_unsaved = false, false, false
+-- Last command sequence number, saved with the timeline: the log alone forgets it after a week idle
+local saved_seq = 0
+local last_history_publish, last_history_long_publish, last_history_save =
+  -HISTORY_MIN_PUBLISH_INTERVAL, -HISTORY_LONG_PUBLISH_INTERVAL, 0
+
+local function record_history(handler_ms, ok, cmd_type, failed)
+  local slow = ok and handler_ms >= HISTORY_SLOW_MS and not LONG_RUNNING[cmd_type]
+  local t = now_ms()
+  for _, tier in ipairs(HISTORY_TIERS) do
+    local id = math.floor(t / tier.size)
+    local b = tier.b[id]
+    if not b then
+      b = { 0, 0, 0, 0 }
+      tier.b[id] = b
+    end
+    b[1] = b[1] + 1
+    if failed then b[2] = b[2] + 1 end
+    if slow then b[3] = b[3] + 1 end -- slow successes; errors counted apart
+    b[4] = b[4] + handler_ms
+  end
+  history_dirty, history_long_dirty, history_unsaved = true, true, true
+end
+
+-- Rows `[bucketId, total, errors, slow, sumMs]`, oldest first; drops buckets older than the tier keeps
+local function tier_rows(tier)
+  local oldest = math.floor(now_ms() / tier.size) - tier.keep // tier.size + 1
+  local ids = {}
+  for id in pairs(tier.b) do
+    if id < oldest then tier.b[id] = nil else ids[#ids + 1] = id end
+  end
+  table.sort(ids)
+  local rows = {}
+  for i, id in ipairs(ids) do
+    local b = tier.b[id]
+    rows[i] = { id, b[1], b[2], b[3], math.floor(b[4] * 10 + 0.5) / 10 }
+  end
+  return rows
+end
+
+local function publish_history(now)
+  if history_dirty and now - last_history_publish >= HISTORY_MIN_PUBLISH_INTERVAL then
+    last_history_publish = now
+    history_dirty = false
+    -- b: [bucketId, total, errors, slow, sumMs]; bucket start = bucketId * size
+    local tier = HISTORY_TIERS[1]
+    reaper.SetExtState(STATUS_SECTION, "history", json_encode({ v = 1, size = tier.size, b = tier_rows(tier) }), false)
+  end
+  if history_long_dirty and now - last_history_long_publish >= HISTORY_LONG_PUBLISH_INTERVAL then
+    last_history_long_publish = now
+    history_long_dirty = false
+    local tiers = {}
+    for i = 2, #HISTORY_TIERS do
+      tiers[#tiers + 1] = { size = HISTORY_TIERS[i].size, b = tier_rows(HISTORY_TIERS[i]) }
+    end
+    reaper.SetExtState(STATUS_SECTION, "history_long", json_encode({ v = 1, tiers = tiers }), false)
+  end
+end
+
+local function save_history(now, force)
+  if not history_unsaved or (not force and now - last_history_save < HISTORY_SAVE_INTERVAL) then return end
+  last_history_save = now
+  history_unsaved = false
+  local tiers = {}
+  for i, tier in ipairs(HISTORY_TIERS) do tiers[i] = { size = tier.size, b = tier_rows(tier) } end
+  write_file(HISTORY_FILE, json_encode({ v = 1, seq = status.seq, tiers = tiers }))
+end
+
+local function load_history()
+  local content = read_file(HISTORY_FILE)
+  if not content or not plan_lib_ok then return end
+  local ok, saved = pcall(plan_lib.json_decode, content)
+  if not ok or type(saved) ~= "table" or type(saved.tiers) ~= "table" then return end
+  if type(saved.seq) == "number" then saved_seq = saved.seq end
+  for _, st in ipairs(saved.tiers) do
+    for _, tier in ipairs(HISTORY_TIERS) do
+      if type(st) == "table" and st.size == tier.size and type(st.b) == "table" then
+        for _, r in ipairs(st.b) do
+          if type(r) == "table" and #r >= 5 then tier.b[r[1]] = { r[2], r[3], r[4], r[5] } end
+        end
+      end
+    end
+  end
+  for _, tier in ipairs(HISTORY_TIERS) do tier_rows(tier) end -- drop what aged out while we were stopped
+  history_dirty, history_long_dirty = true, true
+end
+
+-- Command log: every logged command is appended to history_log.jsonl (like bridge_events.jsonl)
+-- and reloaded on start, so the page's log survives a restart. Kept to the newest LOG_KEEP_MAX
+-- entries within the week the timeline covers; the file is compacted on start and whenever it
+-- has grown by LOG_KEEP_MAX lines. Published as ExtState `log` (newest first) only when the page
+-- asks by writing ExtState `log_want` (it does on open, after a restart and on a gap): encoding a
+-- thousand entries on every change would cost the main thread for a key that is rarely read.
+local LOG_FILE = bridge_dir .. "history_log.jsonl"
+local LOG_KEEP_MAX = 1000
+local LOG_KEEP_MS = HISTORY_TIERS[#HISTORY_TIERS].keep
+local saved_log = {} -- newest first
+local log_appends = 0
+local last_log_request = ""
+
+local function compact_log()
+  local lines = {}
+  for i = #saved_log, 1, -1 do lines[#lines + 1] = json_encode(saved_log[i]) end
+  write_file(LOG_FILE, #lines > 0 and table.concat(lines, "\n") .. "\n" or "")
+  log_appends = 0
+end
+
+local function load_log()
+  local content = read_file(LOG_FILE)
+  if not content or not plan_lib_ok then return end
+  local cutoff = now_ms() - LOG_KEEP_MS
+  local entries = {} -- oldest first, as written
+  for line in content:gmatch("[^\n]+") do
+    local ok, e = pcall(plan_lib.json_decode, line)
+    if ok and type(e) == "table" and type(e.n) == "number" and type(e.t) == "number" and e.t >= cutoff then
+      entries[#entries + 1] = e
+    end
+  end
+  for i = #entries, math.max(1, #entries - LOG_KEEP_MAX + 1), -1 do saved_log[#saved_log + 1] = entries[i] end
+  compact_log()
+end
+
+local function append_log(entry)
+  table.insert(saved_log, 1, entry)
+  saved_log[LOG_KEEP_MAX + 1] = nil
+  log_appends = log_appends + 1
+  if log_appends >= LOG_KEEP_MAX then return compact_log() end
+  local f = io.open(LOG_FILE, "a")
+  if not f then return end
+  f:write(json_encode(entry) .. "\n")
+  f:close()
+end
+
+local function publish_log()
+  local req = reaper.GetExtState(STATUS_SECTION, "log_want")
+  if req == "" or req == last_log_request then return end
+  last_log_request = req
+  -- req echoes the page's request so it can tell this answer from an older one
+  reaper.SetExtState(STATUS_SECTION, "log", json_encode({ v = 1, req = req, entries = saved_log }), false)
+end
+
+load_history()
+load_log()
+-- Sequence numbers continue across restarts so the page can merge the saved log with live entries
+status.seq = math.max(saved_seq, saved_log[1] and saved_log[1].n or 0)
+for i = 1, math.min(STATUS_RECENT_MAX, #saved_log) do status.recent[i] = saved_log[i] end
+
+local STATUS_PARAMS_MAX = 400
+
+-- Measurement results and edit views are kept on the log entry (`r`) so the status page can draw them
+-- (mcp_edit_views_lib.lua); everything else logs params only.
+if edit_lib_ok then
+  edit_lib.init({
+    api = reaper, to_db = to_db, json_decode = plan_lib_ok and plan_lib.json_decode or nil, json_decode_array = json_decode_array,
+    get_midi_notes = function(p) return handlers.get_midi_notes(p) end, get_midi_take = get_midi_take,
+    get_midi_cc = function(p) return handlers.get_midi_cc(p) end,
+    recording = not ext.recording.load_error and ext.recording or nil,
+    resolve_track = function(ref)
+      local res = plan_lib_ok and plan_lib.resolve_track(reaper, ref, {}) or nil
+      return res and res.track or nil
+    end,
+  })
+end
+
+-- Results of tools the server composes itself (sidecar analysis), sent as `_log_result` so the page shows them
+-- like any command: c = the tool, its own duration, and `r` (a JSON string) for the measurement views.
+local STATUS_RESULT_MAX = 6000
+local function record_tool_result(cmd, session)
+  local p = cmd.params
+  local entry = {
+    n = status.seq + 1, t = now_ms(), c = p.command:sub(1, 64), ms = math.floor((tonumber(p.ms) or 0) * 100 + 0.5) / 100,
+    ok = p.ok ~= 0 and p.ok ~= false,
+  }
+  if session then entry.s = session.id end
+  if type(p.p) == "string" and p.p ~= "" and p.p ~= "{}" then entry.p = p.p:sub(1, STATUS_PARAMS_MAX) end
+  if type(p.e) == "string" then entry.e = p.e:gsub("%c", " "):sub(1, 300) end
+  if type(p.r) == "string" and #p.r <= STATUS_RESULT_MAX and plan_lib_ok then
+    local got, r = pcall(plan_lib.json_decode, p.r)
+    if got and type(r) == "table" then entry.r = r end
+  end
+  status.commands = status.commands + 1
+  status.seq = status.seq + 1
+  table.insert(status.recent, 1, entry)
+  status.recent[STATUS_RECENT_MAX + 1] = nil
+  status_dirty = true
+  record_history(entry.ms, entry.ok, entry.c, false)
+  append_log(entry)
+end
+
+local function record_command(cmd, handler_ms, ok, err, data, before)
+  local cmd_type = cmd.type
+  -- Internal commands (e.g. the server's _bridge_diagnostics poller) are noise, but still mark the session alive
+  if type(cmd_type) ~= "string" or cmd_type:sub(1, 1) == "_" then
+    local s = touch_session(cmd, nil)
+    if s and cmd_type == "_session" and type(cmd.params) == "table" and cmd.params.ended then s.ended = true end
+    if cmd_type == "_log_result" and ok and type(cmd.params) == "table" and type(cmd.params.command) == "string" then
+      record_tool_result(cmd, s)
+    end
+    return
+  end
+  -- Only system errors count as errors. A refused request ("Track 9 not found") is a
+  -- warning: the caller asked for something that can't be done. Same prefixes as
+  -- classifyBridgeError() in bridge.ts and SYSTEM_ERROR_PREFIXES in the page's lib/commands.ts.
+  local e_str = err and tostring(err) or ""
+  local failed = not ok and (e_str:find("^Handler error:") or e_str:find("^Unknown command type")
+    or e_str:find("^Internal error:")) ~= nil
+  local session = touch_session(cmd, ok, failed)
+  status.commands = status.commands + 1
+  status.seq = status.seq + 1
+  if failed then status.errors = status.errors + 1 end
+  local entry = { n = status.seq, t = now_ms(), c = cmd_type, ms = math.floor(handler_ms * 100 + 0.5) / 100, ok = ok }
+  if session then entry.s = session.id end
+  if type(cmd.params) == "table" and next(cmd.params) ~= nil then
+    -- Decode arrays the flat command parser left as JSON text, as the handlers do, so they log as JSON
+    local logged = {}
+    for k, v in pairs(cmd.params) do
+      logged[k] = type(v) == "string" and v:find("^%s*[%[{]") and decode_list(v, k) or v
+    end
+    entry.p = json_encode(logged):sub(1, STATUS_PARAMS_MAX)
+  end
+  if err then
+    entry.e = tostring(err):gsub("%c", " "):sub(1, 300)
+  end
+  -- Sent from the status page (a snapshot restore or save), not by an agent
+  if cmd.source == "page" then entry.src = "page" end
+  if ok and edit_lib_ok then
+    local got, r = pcall(edit_lib.summary, cmd_type, cmd.params or {}, data, before)
+    entry.r = got and r or nil
+  end
+  table.insert(status.recent, 1, entry)
+  status.recent[STATUS_RECENT_MAX + 1] = nil
+  status_dirty = true
+  record_history(handler_ms, ok, cmd_type, failed)
+  append_log(entry)
+end
+
+-- cfg_open_on_start ("1"/"0") overrides OPEN_UI_ON_START once the user has chosen in the page
+local function open_on_start()
+  local v = reaper.GetExtState(STATUS_SECTION, "cfg_open_on_start")
+  if v == "" then return OPEN_UI_ON_START end
+  return v == "1"
+end
+
+-- REAPER loads only csurf_0 … csurf_<cnt-1>; an HTTP line past the count is a leftover it ignores
+local function find_web_port()
+  local ini = read_file(reaper.get_ini_file())
+  if not ini then return nil end
+  local active = tonumber(ini:match("\ncsurf_cnt=(%d+)")) or 0
+  for i, port in ini:gmatch("\ncsurf_(%d+)=HTTP %S+ (%d+)") do
+    if tonumber(i) < active then return port end
+  end
+end
+
+-- REAPER's web server never frees a socket whose client hung up first: it stays in CLOSE_WAIT or CLOSED, and
+-- at about 100 the server stops answering until REAPER restarts. Count them every 30 s so the page can warn
+-- before that, with lsof (~50 ms) in the background so the defer loop never waits. macOS and Linux only.
+local web_watch = { interval = 30, limit = 100, last = -30, file = bridge_dir .. "web_sockets" }
+os.remove(web_watch.file) -- a count left by an earlier REAPER run describes a server that is gone
+
+function web_watch.check(now)
+  if is_windows or now - web_watch.last < web_watch.interval then return end
+  web_watch.last = now
+  web_watch.port = web_watch.port or find_web_port()
+  if not web_watch.port then return end
+  local stuck = tonumber((read_file(web_watch.file) or ""):match("%d+"))
+  if stuck and stuck ~= (web_watch.status and web_watch.status.stuck) then
+    web_watch.status = { stuck = stuck, limit = web_watch.limit }
+    status_dirty = true
+    if stuck >= web_watch.limit * 0.9 and not web_watch.warned then
+      web_watch.warned = true
+      reaper.ShowConsoleMsg(string.format("MCP Bridge: REAPER's web server holds %d of about %d connections it never "
+        .. "freed, so the status page will stop loading. Restart REAPER to clear them.\n", stuck, web_watch.limit))
+    end
+  end
+  local tmp = shell_quote(web_watch.file .. ".tmp")
+  os.execute("(lsof -nP -iTCP:" .. web_watch.port .. " -sTCP:CLOSE_WAIT,CLOSED 2>/dev/null"
+    .. " | awk 'NR > 1 && tolower($1) == \"reaper\"' | wc -l > " .. tmp
+    .. " && mv " .. tmp .. " " .. shell_quote(web_watch.file) .. ") >/dev/null 2>&1 &")
+end
+
+local function publish_status(now, force)
+  if not force and (not status_dirty or now - last_status_publish < STATUS_MIN_PUBLISH_INTERVAL) then
     return
   end
+  last_status_publish = now
+  status_dirty = false
+
+  local defer_sum, defer_n = 0, math.min(defer_count, defer_buf_size)
+  for i = 1, defer_n do defer_sum = defer_sum + defer_intervals[i] end
 
+  reaper.SetExtState(STATUS_SECTION, "status", json_encode({
+    v = 1,
+    ts = now_ms(),
+    startedAt = status.startedAt,
+    reaperVersion = reaper.GetAppVersion(),
+    project = select(2, reaper.EnumProjects(-1)) or "",
+    bridgeDir = bridge_dir,
+    commands = status.commands,
+    errors = status.errors,
+    deferMs = defer_n > 0 and math.floor(defer_sum / defer_n * 100000 + 0.5) / 100 or 0,
+    recent = status.recent,
+    sessions = session_list(),
+    settings = { paused = cfg("cfg_paused"), readonly = cfg("cfg_readonly"), openOnStart = open_on_start(), dev = dev_mode() },
+    health = health,
+    web = web_watch.status,
+    control = control_status(),
+  }), false)
+end
+
+-- =============================================================================
+-- Command dispatcher
+-- =============================================================================
+
+-- Runs one command (from a command file, or a status-page request) and logs it; returns the response
+local function run_command(cmd)
   -- Dispatch to handler
   local handler = handlers[cmd.type]
   local response = {}
   local handler_ms = 0
-
-  if handler then
+  local before -- what a write is about to change, for its edit view
+
+  local internal = type(cmd.type) == "string" and cmd.type:sub(1, 1) == "_"
+  local blocked
+  if (not internal or ext.paused_too[cmd.type]) and cfg("cfg_paused") then
+    blocked = "Paused by user in the MCP Bridge window. Ask the user to resume agent control."
+  elseif not internal and cfg("cfg_readonly") and not readonly_allows(cmd.type) then
+    blocked = "Read-only mode is on in the MCP Bridge window: '" .. tostring(cmd.type)
+      .. "' would change the project. Ask the user to turn read-only off."
+  end
+
+  if blocked then
+    response = { id = cmd.id, success = false, error = blocked, timestamp = os.time() * 1000 }
+  elseif handler then
+    if edit_lib_ok then
+      local got, snapshot = pcall(edit_lib.before, cmd.type, cmd.params or {})
+      before = got and snapshot or nil
+    end
     local handler_start = reaper.time_precise()
     local ok, data_or_err, err_msg = pcall(handler, cmd.params or {})
     handler_ms = (reaper.time_precise() - handler_start) * 1000
+    -- A command that may have changed the project makes every cached render stale
+    if ext.render.ok and not internal and not readonly_allows(cmd.type) then ext.render.lib.note_write() end
 
     if not ok then
       -- pcall caught a Lua runtime error — handler crashed
@@ -3894,6 +5360,26 @@ local function process_command(filename)
   -- Add handler timing to response (rounded to microsecond precision)
   response._handlerMs = math.floor(handler_ms * 1000 + 0.5) / 1000
 
+  record_command(cmd, handler_ms, response.success, response.error, response.data, before)
+  if snaps_lib_ok then snaps_lib.after_command(cmd, response) end
+  return response
+end
+
+local function process_command(filename)
+  local pickup_time = reaper.time_precise()
+  local path = bridge_dir .. filename
+  local content = read_file(path)
+  if not content then return end
+
+  local cmd = json_decode(content)
+  if not cmd or not cmd.id or not cmd.type then
+    -- Invalid command, remove file
+    os.remove(path)
+    return
+  end
+
+  local response = run_command(cmd)
+
   -- Add pickup timing to response for profiling
   if cmd.timestamp then
     response._pickupMs = math.floor((pickup_time - (cmd.timestamp / 1000)) * 1000 + 0.5)
@@ -3909,6 +5395,27 @@ local function process_command(filename)
   os.remove(path)
 end
 
+if snaps_lib_ok then
+  snaps_lib.init({
+    api = reaper, section = STATUS_SECTION, dir = get_snapshot_dir, storage = get_snapshot_storage_location,
+    decode = plan_lib_ok and plan_lib.json_decode or json_decode, encode = json_encode, read_file = read_file,
+    token = function() return control_token end, run = run_command,
+  })
+  snaps_lib.register_actions(reaper, script_dir, read_kb_ini())
+end
+
+if ext.prefs then
+  local windows = reaper.GetOS and tostring(reaper.GetOS()):find("Win") ~= nil
+  ext.prefs.init({
+    api = reaper, section = STATUS_SECTION, dir = ext.prefs.default_dir(os.getenv, windows),
+    decode = plan_lib_ok and plan_lib.json_decode or json_decode, encode = json_encode, read_file = read_file,
+    token = function() return control_token end,
+    chmod = not windows and function(path)
+      if not path:find("'", 1, true) then os.execute("chmod 600 '" .. path .. "'") end
+    end or nil,
+  })
+end
+
 -- =============================================================================
 -- Heartbeat
 -- =============================================================================
@@ -3955,7 +5462,21 @@ local function main_loop()
   if now - last_heartbeat >= HEARTBEAT_INTERVAL then
     last_heartbeat = now
     write_heartbeat()
-  end
+    publish_status(now, true)
+  else
+    publish_status(now, false)
+  end
+  publish_history(now)
+  save_history(now, false)
+  publish_log()
+  check_health(now)
+  web_watch.check(now)
+  check_control(now)
+  check_source_changes(now)
+  publish_installed_fx(now)
+  publish_used_fx(now)
+  if snaps_lib_ok then snaps_lib.poll(now) end
+  if ext.prefs then ext.prefs.poll() end
 
   reaper.defer(main_loop)
 end
@@ -3964,9 +5485,42 @@ end
 -- Startup
 -- =============================================================================
 
-reaper.ShowConsoleMsg("MCP Bridge: Started\n")
-reaper.ShowConsoleMsg("MCP Bridge: Bridge directory: " .. bridge_dir .. "\n")
-reaper.ShowConsoleMsg("MCP Bridge: Polling every " .. (POLL_INTERVAL * 1000) .. "ms\n")
+-- Find the REAPER web interface port (reaper.ini: csurf_N=HTTP <flags> <port> ...)
+-- The page pings ExtState ui_seen on every poll; a recent ping means it's already open
+local function ui_recently_seen()
+  local seen = tonumber(reaper.GetExtState(STATUS_SECTION, "ui_seen"))
+  return seen ~= nil and math.abs(os.time() * 1000 - seen) < 6000
+end
+
+-- Open the status page as a small chromeless app window (Chromium --app), else the default browser
+local function open_status_window(url)
+  local os_name = reaper.GetOS()
+  local cmd
+  if os_name:match("^OSX") or os_name:match("^macOS") then
+    for _, app in ipairs({ "Google Chrome", "Microsoft Edge", "Brave Browser", "Chromium" }) do
+      local bin = "/Applications/" .. app .. ".app/Contents/MacOS/" .. app
+      if file_exists(bin) then
+        cmd = shell_quote(bin) .. " --app=" .. shell_quote(url) .. " --window-size=980,720 >/dev/null 2>&1 &"
+        break
+      end
+    end
+    cmd = cmd or ("open " .. shell_quote(url))
+  elseif os_name:match("^Win") then
+    cmd = 'start "" msedge --app="' .. url .. '" --window-size=980,720'
+  else
+    local q = shell_quote(url)
+    cmd = "(google-chrome --app=" .. q .. " || chromium --app=" .. q .. " || xdg-open " .. q .. ") >/dev/null 2>&1 &"
+  end
+  os.execute(cmd)
+end
+
+local web_port = find_web_port()
+if not web_port then
+  reaper.ShowConsoleMsg("MCP Bridge: running. For the status window, quit REAPER and run `reaper-mcp setup` "
+    .. "(or enable Preferences > Control/OSC/Web > Web browser interface).\n")
+elseif open_on_start() and not ui_recently_seen() then
+  open_status_window("http://localhost:" .. web_port .. "/mcp_bridge.html?app=window")
+end
 
 -- Write initial heartbeat
 write_heartbeat()
@@ -3975,7 +5529,16 @@ write_heartbeat()
 log_event("bridge_start", { reaperVersion = reaper.GetAppVersion(), bridgeDir = bridge_dir })
 
 -- Register shutdown handler
-reaper.atexit(function() log_event("bridge_stop", {}) end)
+-- Renders a previous run left behind
+if ext.render.ok then pcall(ext.render.lib.sweep, reaper) end
+
+reaper.atexit(function()
+  if ext.render.ok then pcall(ext.render.lib.purge) end
+  log_event("bridge_stop", {})
+  save_history(reaper.time_precise(), true)
+  reaper.DeleteExtState(STATUS_SECTION, "status", false) -- UI flips to offline at once
+  for _, key in ipairs({ "history", "history_long", "log" }) do reaper.DeleteExtState(STATUS_SECTION, key, false) end
+end)
 
 -- Start the loop
 main_loop()