@mthines/reaper-mcp 0.17.0-beta.18.1 → 0.18.0

package/README.md

@@ -246,13 +246,25 @@ Checks that the bridge is connected, knowledge is installed, and MCP config exis
 
 ### Snapshots (A/B Testing)
 
+Snapshots capture your full mixer state: track volumes, pans, mute/solo, FX chains (all parameter values, enabled/offline states, presets), and send levels. Use them to A/B compare mix decisions or revert to a known-good state.
+
 | Tool | Description |
 |------|-------------|
-| `snapshot_save` | Save current mixer state (volumes, pans, FX, mutes) |
-| `snapshot_restore` | Restore a saved snapshot |
-| `snapshot_list` | List all saved snapshots |
+| `snapshot_save` | Save current mixer state (volumes, pans, FX params, sends, mutes) |
+| `snapshot_restore` | Restore a saved snapshot (smart FX matching — only restores params if plugin names match) |
+| `snapshot_list` | List all saved snapshots with metadata |
 | `snapshot_delete` | Delete a saved snapshot by name |
 
+You can also manage snapshots directly in REAPER using the **Snapshot Manager** GUI (`mcp_snapshot_manager.lua`) — load it as a ReaScript action for a visual list with save/restore/delete buttons.
+
+For quick A/B testing, bind these action scripts to keyboard shortcuts in REAPER:
+
+| Script | Purpose | Suggested Key |
+|--------|---------|---------------|
+| `mcp_snapshot_quick_save.lua` | Save snapshot instantly (auto-named) | `Ctrl+Shift+S` |
+| `mcp_snapshot_next.lua` | Restore next snapshot (wraps around) | `Ctrl+Right` |
+| `mcp_snapshot_prev.lua` | Restore previous snapshot (wraps around) | `Ctrl+Left` |
+
 ### Routing
 
 | Tool | Description |
@@ -316,7 +328,7 @@ Every change is bracketed by snapshots:
 1. Agent saves a "Before" snapshot automatically
 2. Makes all changes
 3. Saves an "After" snapshot
-4. You can restore either with `snapshot_restore` to A/B compare
+4. You can restore either with `snapshot_restore` to A/B compare, or use the Snapshot Manager GUI in REAPER
 
 ### Genre Awareness
 
@@ -539,6 +551,7 @@ reaper-mcp/
 ├── reaper/                       # Files installed into REAPER
 │   ├── mcp_bridge.lua            # Persistent Lua bridge
 │   ├── mcp_snapshot_manager.lua  # Snapshot manager GUI (save/restore/delete)
+│   ├── mcp_snapshot_*.lua        # Snapshot action scripts (next/prev/quick-save + shared lib)
 │   ├── mcp_analyzer.jsfx         # FFT spectrum analyzer
 │   ├── mcp_lufs_meter.jsfx       # LUFS meter (BS.1770)
 │   ├── mcp_correlation_meter.jsfx # Stereo correlation meter

package/main.js

@@ -2307,7 +2307,11 @@ var REAPER_ASSETS = [
   "mcp_lufs_meter.jsfx",
   "mcp_correlation_meter.jsfx",
   "mcp_crest_factor.jsfx",
-  "mcp_snapshot_manager.lua"
+  "mcp_snapshot_manager.lua",
+  "mcp_snapshot_lib.lua",
+  "mcp_snapshot_next.lua",
+  "mcp_snapshot_prev.lua",
+  "mcp_snapshot_quick_save.lua"
 ];
 var MCP_TOOL_NAMES = [
   // project

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mthines/reaper-mcp",
-  "version": "0.17.0-beta.18.1",
+  "version": "0.18.0",
   "type": "module",
   "description": "MCP server for controlling REAPER DAW — real-time mixing, FX control, and frequency analysis for AI agents",
   "license": "MIT",

package/reaper/CLAUDE.md

@@ -8,6 +8,10 @@ Files installed INTO the REAPER DAW by the `setup` command. These run inside REA
 |------|----------|---------|
 | `mcp_bridge.lua` | Lua | Persistent bridge: polls for JSON commands, executes ReaScript API, writes responses |
 | `mcp_snapshot_manager.lua` | Lua | Standalone snapshot manager GUI (gfx-based, save/restore/delete snapshots) |
+| `mcp_snapshot_lib.lua` | Lua | Shared library for snapshot action scripts (path helpers, JSON, restore logic) |
+| `mcp_snapshot_next.lua` | Lua | Action: restore next snapshot (bind to key for A/B testing) |
+| `mcp_snapshot_prev.lua` | Lua | Action: restore previous snapshot (bind to key for A/B testing) |
+| `mcp_snapshot_quick_save.lua` | Lua | Action: save snapshot with auto-name, no dialog |
 | `mcp_analyzer.jsfx` | JSFX/EEL2 | Real-time FFT spectrum analyzer, writes to gmem[] |
 | `mcp_lufs_meter.jsfx` | JSFX/EEL2 | LUFS loudness metering |
 | `mcp_correlation_meter.jsfx` | JSFX/EEL2 | Stereo correlation and width analysis |

package/reaper/install.sh

@@ -26,10 +26,12 @@ echo "REAPER resource path: $REAPER_PATH"
 # Install Lua scripts
 SCRIPTS_DIR="$REAPER_PATH/Scripts"
 mkdir -p "$SCRIPTS_DIR"
-cp "$SCRIPT_DIR/mcp_bridge.lua" "$SCRIPTS_DIR/mcp_bridge.lua"
-echo "Installed: $SCRIPTS_DIR/mcp_bridge.lua"
-cp "$SCRIPT_DIR/mcp_snapshot_manager.lua" "$SCRIPTS_DIR/mcp_snapshot_manager.lua"
-echo "Installed: $SCRIPTS_DIR/mcp_snapshot_manager.lua"
+for lua in "$SCRIPT_DIR"/*.lua; do
+  [ -f "$lua" ] || continue
+  fname="$(basename "$lua")"
+  cp "$lua" "$SCRIPTS_DIR/$fname"
+  echo "Installed: $SCRIPTS_DIR/$fname"
+done
 
 # Install JSFX analyzers
 EFFECTS_DIR="$REAPER_PATH/Effects/reaper-mcp"

package/reaper/mcp_snapshot_lib.lua

@@ -0,0 +1,350 @@
+-- =============================================================================
+-- MCP Snapshot Library — shared helpers for snapshot action scripts
+-- =============================================================================
+-- Loaded via dofile() by snapshot action scripts. Provides path resolution,
+-- JSON parsing, snapshot listing, and restore logic.
+-- =============================================================================
+
+local M = {}
+
+-- ExtState section for persisting current snapshot index across action calls
+M.EXT_SECTION = "MCP_Snapshots"
+M.EXT_KEY_IDX = "current_index"
+
+-- =============================================================================
+-- Path helpers
+-- =============================================================================
+
+function M.get_snapshot_dir()
+  local proj_path = reaper.GetProjectPath()
+  if proj_path and proj_path ~= "" then
+    return proj_path .. "/.reaper-mcp/snapshots/"
+  end
+  return reaper.GetResourcePath() .. "/Scripts/mcp_bridge_data/snapshots/"
+end
+
+function M.ensure_snapshot_dir()
+  reaper.RecursiveCreateDirectory(M.get_snapshot_dir(), 0)
+end
+
+function M.snapshot_path(name)
+  local safe = name:gsub("[^%w%-_%.%s]", "_"):gsub("%s+", "_")
+  return M.get_snapshot_dir() .. safe .. ".json"
+end
+
+-- =============================================================================
+-- File I/O
+-- =============================================================================
+
+function M.read_file(path)
+  local f = io.open(path, "rb")
+  if not f then return nil end
+  local content = f:read("*a")
+  f:close()
+  return content
+end
+
+function M.write_file(path, content)
+  local f = io.open(path, "wb")
+  if not f then return false end
+  f:write(content)
+  f:close()
+  return true
+end
+
+-- =============================================================================
+-- Minimal JSON helpers
+-- =============================================================================
+
+local function json_encode_string(s)
+  s = tostring(s)
+  s = s:gsub('\\', '\\\\')
+  s = s:gsub('"', '\\"')
+  s = s:gsub('\n', '\\n')
+  s = s:gsub('\r', '\\r')
+  s = s:gsub('\t', '\\t')
+  return '"' .. s .. '"'
+end
+
+function M.json_encode(val)
+  local t = type(val)
+  if t == "nil" then return "null"
+  elseif t == "boolean" then return val and "true" or "false"
+  elseif t == "number" then
+    if val ~= val then return "null" end
+    return tostring(val)
+  elseif t == "string" then return json_encode_string(val)
+  elseif t == "table" then
+    local is_array = true
+    local max_i = 0
+    for k, _ in pairs(val) do
+      if type(k) ~= "number" or k ~= math.floor(k) or k < 1 then
+        is_array = false; break
+      end
+      if k > max_i then max_i = k end
+    end
+    if is_array and max_i == #val then
+      local parts = {}
+      for i = 1, #val do parts[i] = M.json_encode(val[i]) end
+      return "[" .. table.concat(parts, ",") .. "]"
+    else
+      local parts = {}
+      for k, v in pairs(val) do
+        parts[#parts + 1] = json_encode_string(tostring(k)) .. ":" .. M.json_encode(v)
+      end
+      return "{" .. table.concat(parts, ",") .. "}"
+    end
+  end
+  return "null"
+end
+
+local function extract_json_string(str, pos)
+  local result = {}
+  local i = pos
+  while i <= #str do
+    local ch = str:sub(i, i)
+    if ch == '\\' then
+      local next_ch = str:sub(i + 1, i + 1)
+      if next_ch == '"' then result[#result + 1] = '"'
+      elseif next_ch == '\\' then result[#result + 1] = '\\'
+      elseif next_ch == 'n' then result[#result + 1] = '\n'
+      elseif next_ch == 't' then result[#result + 1] = '\t'
+      elseif next_ch == '/' then result[#result + 1] = '/'
+      else result[#result + 1] = next_ch end
+      i = i + 2
+    elseif ch == '"' then
+      return table.concat(result), i + 1
+    else
+      result[#result + 1] = ch
+      i = i + 1
+    end
+  end
+  return nil, i
+end
+
+function M.parse_flat_object(str)
+  local obj = {}
+  local i = 1
+  while i <= #str do
+    local key_start = str:find('"', i)
+    if not key_start then break end
+    local key, after_key = extract_json_string(str, key_start + 1)
+    if not key then break end
+    i = after_key
+    local colon = str:find(':', i)
+    if not colon then break end
+    local val_start = str:match('^%s*()', colon + 1)
+    local ch = str:sub(val_start, val_start)
+    if ch == '"' then
+      local val, next_pos = extract_json_string(str, val_start + 1)
+      if val then obj[key] = val; i = next_pos
+      else i = val_start + 1 end
+    elseif ch == '{' or ch == '[' then
+      local depth = 1
+      local close_c = ch == '{' and '}' or ']'
+      local j = val_start + 1
+      while j <= #str and depth > 0 do
+        local c = str:sub(j, j)
+        if c == ch then depth = depth + 1
+        elseif c == close_c then depth = depth - 1 end
+        j = j + 1
+      end
+      i = j
+    else
+      local val_end = str:find('[,}%]]', val_start)
+      if not val_end then val_end = #str + 1 end
+      local raw = str:sub(val_start, val_end - 1):match("^%s*(.-)%s*$")
+      if raw == "true" then obj[key] = true
+      elseif raw == "false" then obj[key] = false
+      elseif raw == "null" then obj[key] = nil
+      else obj[key] = tonumber(raw) end
+      i = val_end
+    end
+  end
+  return obj
+end
+
+-- =============================================================================
+-- Snapshot listing
+-- =============================================================================
+
+function M.load_snapshots()
+  M.ensure_snapshot_dir()
+  local snap_dir = M.get_snapshot_dir()
+  local result = {}
+  local i = 0
+  while true do
+    local fn = reaper.EnumerateFiles(snap_dir, i)
+    if not fn then break end
+    if fn:match("%.json$") then
+      local path = snap_dir .. fn
+      local content = M.read_file(path)
+      if content then
+        local ok, snap = pcall(M.parse_flat_object, content)
+        if ok and snap and snap.name then
+          result[#result + 1] = {
+            name      = snap.name,
+            timestamp = tonumber(snap.timestamp) or 0,
+            path      = path,
+          }
+        end
+      end
+    end
+    i = i + 1
+  end
+  table.sort(result, function(a, b) return a.timestamp > b.timestamp end)
+  return result
+end
+
+-- =============================================================================
+-- Restore logic
+-- =============================================================================
+
+function M.restore_snapshot(snap)
+  local content = M.read_file(snap.path)
+  if not content then return false, "File not found" end
+
+  local mixer_block_start = content:find('"mixerState"%s*:%s*{')
+  if not mixer_block_start then return false, "No mixerState" end
+
+  local tracks_start = content:find('"tracks"%s*:%s*%[', mixer_block_start)
+  if not tracks_start then return false, "No tracks" end
+
+  local arr_open = content:find('%[', tracks_start)
+  if not arr_open then return false, "Invalid format" end
+
+  local track_objects = {}
+  local depth = 0
+  local obj_start = nil
+  local i = arr_open
+  while i <= #content do
+    local ch = content:sub(i, i)
+    if ch == '{' then
+      depth = depth + 1
+      if depth == 1 then obj_start = i end
+    elseif ch == '}' then
+      depth = depth - 1
+      if depth == 0 and obj_start then
+        track_objects[#track_objects + 1] = content:sub(obj_start, i)
+        obj_start = nil
+      end
+    elseif ch == ']' and depth == 0 then break end
+    i = i + 1
+  end
+
+  if #track_objects == 0 then return false, "No track data" end
+
+  reaper.Undo_BeginBlock()
+  local restored = 0
+  for _, track_json in ipairs(track_objects) do
+    local ok_t, td = pcall(M.parse_flat_object, track_json)
+    if ok_t and td and td.index then
+      local track = reaper.GetTrack(0, tonumber(td.index))
+      if track then
+        if td.volume then reaper.SetMediaTrackInfo_Value(track, "D_VOL", tonumber(td.volume)) end
+        if td.pan then reaper.SetMediaTrackInfo_Value(track, "D_PAN", tonumber(td.pan)) end
+        if td.mute ~= nil then
+          reaper.SetMediaTrackInfo_Value(track, "B_MUTE", (td.mute == true or td.mute == "true") and 1 or 0)
+        end
+        if td.solo ~= nil then
+          reaper.SetMediaTrackInfo_Value(track, "I_SOLO", (td.solo == true or td.solo == "true") and 1 or 0)
+        end
+        restored = restored + 1
+      end
+    end
+  end
+  reaper.Undo_EndBlock("MCP Snapshot: Restore '" .. snap.name .. "'", -1)
+  reaper.TrackList_AdjustWindows(false)
+  reaper.UpdateArrange()
+  return true, nil, restored
+end
+
+-- =============================================================================
+-- Capture mixer state
+-- =============================================================================
+
+function M.capture_mixer_state()
+  local state = { version = 2, tracks = {} }
+  local count = reaper.CountTracks(0)
+  for i = 0, count - 1 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")
+
+    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 = {}
+      local param_count = reaper.TrackFX_GetNumParams(track, j)
+      local limit = math.min(param_count, 500)
+      for p = 0, limit - 1 do
+        params_data[p + 1] = reaper.TrackFX_GetParam(track, j, p)
+      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
+
+    local fx_enabled = {}
+    for j = 1, #fx_states do fx_enabled[j] = fx_states[j].enabled 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, fxEnabled = fx_enabled,
+    }
+  end
+  return state
+end
+
+-- =============================================================================
+-- Persisted index helpers
+-- =============================================================================
+
+function M.get_current_index()
+  local val = reaper.GetExtState(M.EXT_SECTION, M.EXT_KEY_IDX)
+  return tonumber(val) or 0
+end
+
+function M.set_current_index(idx)
+  reaper.SetExtState(M.EXT_SECTION, M.EXT_KEY_IDX, tostring(idx), false)
+end
+
+-- =============================================================================
+-- Toast message (brief console feedback)
+-- =============================================================================
+
+function M.toast(msg)
+  reaper.Help_Set(msg, false)
+end
+
+return M

package/reaper/mcp_snapshot_manager.lua

@@ -12,12 +12,12 @@ local WIN_W = 820
 local WIN_H = 520
 local PADDING = 10
 local ROW_H = 26
-local HEADER_H = 34
+local COL_HEADER_H = 28
 local BUTTON_H = 32
 local BUTTON_W = 120
 local FOOTER_H = BUTTON_H + PADDING * 2
 local STATUS_H = 22
-local LIST_TOP = HEADER_H + PADDING
+local LIST_TOP = COL_HEADER_H + PADDING
 local LIST_BOTTOM_MARGIN = FOOTER_H + STATUS_H + PADDING
 local SCROLL_BAR_W = 14
 
@@ -238,7 +238,7 @@ local function count_tracks_in_snapshot(content)
   local count = 0
   local depth = 0
   local i = arr_start
-  while i <= #arr_start + 50000 and i <= #content do
+  while i <= math.min(#content, arr_start + 50000) do
     local ch = content:sub(i, i)
     if ch == '[' or ch == '{' then
       depth = depth + 1
@@ -623,37 +623,25 @@ local function draw()
   set_color(C_BG)
   fill_rect(0, 0, w, h)
 
-  -- Header bar
-  set_color(C_HEADER_BG)
-  fill_rect(0, 0, w, HEADER_H)
-  gfx.setfont(1, "Arial", 16, string.byte('b'))
-  draw_text(TITLE, PADDING, math.floor((HEADER_H - 16) / 2), C_TEXT_SEL)
-  gfx.setfont(1, "Arial", 12, 0)
-
-  -- Snapshot dir info
-  local snap_dir = get_snapshot_dir()
-  local dir_label = "Dir: " .. snap_dir
-  draw_text(dir_label, PADDING + 200, math.floor((HEADER_H - 12) / 2) + 2, C_TEXT_DIM, false, w - 220 - PADDING)
-
-  -- Column headers
+  -- Column headers (title is already in the window title bar)
   local lx, ly, lw, lh = get_list_rect()
-  local col_header_y = ly - ROW_H - 2
   set_color(C_HEADER_BG)
-  fill_rect(lx, col_header_y, lw - SCROLL_BAR_W, ROW_H)
+  fill_rect(0, 0, w, COL_HEADER_H)
   gfx.setfont(1, "Arial", 11, string.byte('b'))
-  local cx = lx + 4
-  draw_text("Name", cx, col_header_y + 7, C_TEXT_HEADER)
+  local col_text_y = math.floor((COL_HEADER_H - 11) / 2)
+  local cx = PADDING + 4
+  draw_text("Name", cx, col_text_y, C_TEXT_HEADER)
   cx = cx + COL_NAME_W
-  draw_text("Description", cx, col_header_y + 7, C_TEXT_HEADER)
+  draw_text("Description", cx, col_text_y, C_TEXT_HEADER)
   cx = cx + COL_DESC_W
-  draw_text("Saved", cx, col_header_y + 7, C_TEXT_HEADER)
+  draw_text("Saved", cx, col_text_y, C_TEXT_HEADER)
   cx = cx + COL_DATE_W
-  draw_text("Tracks", cx, col_header_y + 7, C_TEXT_HEADER)
+  draw_text("Tracks", cx, col_text_y, C_TEXT_HEADER)
   gfx.setfont(1, "Arial", 12, 0)
 
   -- Divider under col headers
   set_color(C_DIVIDER)
-  fill_rect(lx, col_header_y + ROW_H - 1, lw, 1)
+  fill_rect(0, COL_HEADER_H - 1, w, 1)
 
   -- Snapshot list
   local visible_rows = get_visible_rows(lh)
@@ -719,7 +707,7 @@ local function draw()
 
   -- Empty state message
   if total_rows == 0 then
-    local msg = "No snapshots found. Use 'Save New' to create one."
+    local msg = "No snapshots found. Click 'Save New' to capture your current mixer state."
     gfx.setfont(1, "Arial", 13, 0)
     local tw, _ = gfx.measurestr(msg)
     draw_text(msg, lx + math.floor((lw - tw) / 2), ly + math.floor(lh / 2) - 8, C_TEXT_DIM)
@@ -751,15 +739,18 @@ local function draw()
   set_color(C_BG)
   fill_rect(0, status_y, w, STATUS_H)
 
+  gfx.setfont(1, "Arial", 11, 0)
   if status_msg ~= "" and reaper.time_precise() < status_timer then
     local sc = C_STATUS_INFO
     if status_type == "ok" then sc = C_STATUS_OK
     elseif status_type == "err" then sc = C_STATUS_ERR
     end
-    gfx.setfont(1, "Arial", 11, 0)
     draw_text(status_msg, PADDING, status_y + 4, sc)
-    gfx.setfont(1, "Arial", 12, 0)
+  else
+    -- Default info: what snapshots contain
+    draw_text("Snapshots store: track volumes, pans, mute/solo, FX chains (params + presets), and send levels", PADDING, status_y + 4, C_TEXT_DIM)
   end
+  gfx.setfont(1, "Arial", 12, 0)
 
   -- Footer buttons
   set_color(C_BG)
@@ -816,11 +807,19 @@ local function draw()
       local has_sel = selected_idx > 0 and selected_idx <= #snapshots
 
       if hover_btn == "save" then
-        -- Show save dialog
+        -- Generate default name: "Snapshot N" where N is the next available index
+        local next_idx = #snapshots + 1
+        for _, s in ipairs(snapshots) do
+          local num = s.name:match("^Snapshot (%d+)$")
+          if num then next_idx = math.max(next_idx, tonumber(num) + 1) end
+        end
+        local default_name = "Snapshot " .. next_idx
+
+        -- Show save dialog with default name pre-filled
         local retval, inputs = reaper.GetUserInputs(
           "Save Snapshot", 2,
-          "Name:,Description:,extrawidth=200",
-          ","
+          "Name (leave default for auto-name):,Description (optional):,extrawidth=200",
+          default_name .. ","
         )
         if retval then
           local fields = {}
@@ -829,20 +828,17 @@ local function draw()
           end
           local sname = fields[1] and fields[1]:match("^%s*(.-)%s*$") or ""
           local sdesc = fields[2] and fields[2]:match("^%s*(.-)%s*$") or ""
-          if sname == "" then
-            set_status("Name cannot be empty.", "err")
-          else
-            local ok, err = do_save_snapshot(sname, sdesc)
-            if ok then
-              set_status("Saved snapshot: " .. sname, "ok")
-              snapshots = load_snapshots()
-              -- Select the newly saved snapshot
-              for j, s in ipairs(snapshots) do
-                if s.name == sname then selected_idx = j; break end
-              end
-            else
-              set_status("Save failed: " .. (err or "unknown error"), "err")
+          if sname == "" then sname = default_name end
+          local ok, err = do_save_snapshot(sname, sdesc)
+          if ok then
+            set_status("Saved snapshot: " .. sname, "ok")
+            snapshots = load_snapshots()
+            -- Select the newly saved snapshot
+            for j, s in ipairs(snapshots) do
+              if s.name == sname then selected_idx = j; break end
             end
+          else
+            set_status("Save failed: " .. (err or "unknown error"), "err")
           end
         end
 
@@ -929,11 +925,17 @@ local function draw()
   elseif char == 13 then -- Enter = restore
     if selected_idx > 0 and selected_idx <= #snapshots then
       local snap = snapshots[selected_idx]
-      local ok, err, count = do_restore_snapshot(snap)
-      if ok then
-        set_status("Restored '" .. snap.name .. "' (" .. (count or "?") .. " tracks)", "ok")
-      else
-        set_status("Restore failed: " .. (err or "unknown error"), "err")
+      local confirm = reaper.ShowMessageBox(
+        "Restore snapshot '" .. snap.name .. "'?\n\nThis will overwrite current mixer state.\nAn undo point will be created.",
+        "Restore Snapshot", 1
+      )
+      if confirm == 1 then
+        local ok, err, count = do_restore_snapshot(snap)
+        if ok then
+          set_status("Restored '" .. snap.name .. "' (" .. (count or "?") .. " tracks)", "ok")
+        else
+          set_status("Restore failed: " .. (err or "unknown error"), "err")
+        end
       end
     end
   elseif char == 6579564 then -- Delete key
@@ -960,7 +962,9 @@ local function draw()
   local wheel = gfx.mouse_wheel
   if wheel ~= 0 then
     local scroll_lines = wheel > 0 and -3 or 3
-    scroll_offset = math.max(0, math.min(scroll_offset + scroll_lines, math.max(0, #snapshots - get_visible_rows((select(4, get_list_rect())  )))))
+    local _, _, _, lh_scroll = get_list_rect()
+    local max_scroll_wheel = math.max(0, #snapshots - get_visible_rows(lh_scroll))
+    scroll_offset = math.max(0, math.min(scroll_offset + scroll_lines, max_scroll_wheel))
     gfx.mouse_wheel = 0
   end
 

package/reaper/mcp_snapshot_next.lua

@@ -0,0 +1,25 @@
+-- MCP Snapshot: Next — restore the next snapshot in the list
+-- Bind to a key for quick A/B testing. Wraps around at the end.
+
+local info = debug.getinfo(1, "S")
+local script_dir = info.source:match("@?(.*[\\/])")
+local lib = dofile(script_dir .. "mcp_snapshot_lib.lua")
+
+local snapshots = lib.load_snapshots()
+if #snapshots == 0 then
+  lib.toast("No snapshots found")
+  return
+end
+
+local idx = lib.get_current_index()
+idx = idx + 1
+if idx > #snapshots then idx = 1 end
+
+local snap = snapshots[idx]
+local ok, err = lib.restore_snapshot(snap)
+if ok then
+  lib.set_current_index(idx)
+  lib.toast("Snapshot " .. idx .. "/" .. #snapshots .. ": " .. snap.name)
+else
+  lib.toast("Restore failed: " .. (err or "unknown"))
+end

package/reaper/mcp_snapshot_prev.lua

@@ -0,0 +1,25 @@
+-- MCP Snapshot: Previous — restore the previous snapshot in the list
+-- Bind to a key for quick A/B testing. Wraps around at the beginning.
+
+local info = debug.getinfo(1, "S")
+local script_dir = info.source:match("@?(.*[\\/])")
+local lib = dofile(script_dir .. "mcp_snapshot_lib.lua")
+
+local snapshots = lib.load_snapshots()
+if #snapshots == 0 then
+  lib.toast("No snapshots found")
+  return
+end
+
+local idx = lib.get_current_index()
+idx = idx - 1
+if idx < 1 then idx = #snapshots end
+
+local snap = snapshots[idx]
+local ok, err = lib.restore_snapshot(snap)
+if ok then
+  lib.set_current_index(idx)
+  lib.toast("Snapshot " .. idx .. "/" .. #snapshots .. ": " .. snap.name)
+else
+  lib.toast("Restore failed: " .. (err or "unknown"))
+end

package/reaper/mcp_snapshot_quick_save.lua

@@ -0,0 +1,41 @@
+-- MCP Snapshot: Quick Save — save a snapshot with auto-generated name, no dialog
+-- Bind to a key for rapid iteration. Names: "Snapshot 1", "Snapshot 2", etc.
+
+local info = debug.getinfo(1, "S")
+local script_dir = info.source:match("@?(.*[\\/])")
+local lib = dofile(script_dir .. "mcp_snapshot_lib.lua")
+
+local snapshots = lib.load_snapshots()
+
+-- Find next available "Snapshot N" index
+local next_idx = #snapshots + 1
+for _, s in ipairs(snapshots) do
+  local num = s.name:match("^Snapshot (%d+)$")
+  if num then next_idx = math.max(next_idx, tonumber(num) + 1) end
+end
+
+local name = "Snapshot " .. next_idx
+lib.ensure_snapshot_dir()
+
+local snapshot = {
+  name = name,
+  description = "",
+  timestamp = os.time() * 1000,
+  mixerState = lib.capture_mixer_state(),
+}
+
+local path = lib.snapshot_path(name)
+local ok = lib.write_file(path, lib.json_encode(snapshot))
+if ok then
+  -- Set current index to the new snapshot so next/prev starts from here
+  local updated = lib.load_snapshots()
+  for i, s in ipairs(updated) do
+    if s.name == name then
+      lib.set_current_index(i)
+      break
+    end
+  end
+  lib.toast("Saved: " .. name .. " (" .. #snapshot.mixerState.tracks .. " tracks)")
+else
+  lib.toast("Save failed: " .. path)
+end