chore: release 0.1.0 — rename to turbo-debug.nvim

Rename from tiny-debugger to turbo-debug — inspired by Turbo Pascal,
the first IDE with a real visual debugger. This thing isn't tiny,
it's turbo charged.

CHANGELOG for 0.1.0:

Features:
- Zero-config debugging — one line install, everything works
- Modal keybindings (c/s/d/r/q/x/X/D/W/K/E/R/?), active only
  during debug mode, cleanly removed on exit
- Persistent breakpoints via persistent-breakpoints.nvim
- Inline virtual text — variable values in source code
- Hover (K), watch (W), REPL eval (E) from the code window
- Help splash (3s auto-dismiss) + manual help (?)
- Debug mode chrome — winbar indicator, cursor highlight
- dapui integration — controls toolbar, labeled panels
- which-key support — <leader>d debug group auto-registered
- quit_exits_mode option

Adapters (12 languages):
- Python (debugpy + venv detection)
- Rust (codelldb + cargo build + vim.ui.select picker)
- Go (delve), C/C++/Swift (codelldb)
- JavaScript/TypeScript (js-debug-adapter)
- C# (netcoredbg), Java, Kotlin, PHP, Ruby, Lua (osv)

Keybindings:
- <leader>dd — toggle debug mode
- <leader>dx / <leader>dX / <leader>dD — breakpoints (always)
- c s d r C x X D W K E q R ? — modal (debug mode only)

lua/turbo-debug/adapters/c.lua

@@ -0,0 +1,89 @@
+local loader = require("turbo-debug.adapters.init")
+
+local M = {}
+
+local function pick_executable(executables)
+  local co = coroutine.running()
+  if not co then
+    return executables[1]
+  end
+  vim.ui.select(executables, {
+    prompt = "Select executable",
+    format_item = function(path) return vim.fn.fnamemodify(path, ":t") end,
+  }, function(choice)
+    coroutine.resume(co, choice)
+  end)
+  return coroutine.yield()
+end
+
+local function cargo_build_and_pick()
+  vim.notify("cargo build ...")
+  local output = vim.fn.system("cargo build --message-format=json")
+  if vim.v.shell_error ~= 0 then
+    local errors = {}
+    for line in output:gmatch("[^\n]+") do
+      if not line:match("^{") then errors[#errors + 1] = line end
+    end
+    vim.notify("cargo build failed:\n" .. table.concat(errors, "\n"), vim.log.levels.ERROR)
+    return nil
+  end
+
+  local executables = {}
+  for line in output:gmatch("[^\n]+") do
+    local ok, msg = pcall(vim.json.decode, line)
+    if ok and msg.reason == "compiler-artifact" and msg.executable then
+      executables[#executables + 1] = msg.executable
+    end
+  end
+
+  if #executables == 0 then return nil end
+  if #executables == 1 then return executables[1] end
+  return pick_executable(executables)
+end
+
+function M.register(dap)
+  local codelldb = loader.find_executable({ "codelldb" })
+  if not codelldb then return end
+
+  local adapter = {
+    type = "server",
+    port = "${port}",
+    executable = {
+      command = codelldb,
+      args = { "--port", "${port}" },
+    },
+  }
+
+  if not dap.adapters.codelldb then
+    dap.adapters.codelldb = adapter
+  end
+
+  -- C/C++/Swift: pick from compiled executables in cwd
+  local prompt_config = {
+    {
+      type = "codelldb",
+      request = "launch",
+      name = "Launch executable",
+      program = function()
+        return vim.fn.input("Path to executable: ", vim.fn.getcwd() .. "/", "file")
+      end,
+      cwd = "${workspaceFolder}",
+    },
+  }
+  for _, ft in ipairs({ "c", "cpp", "swift" }) do
+    dap.configurations[ft] = dap.configurations[ft] or prompt_config
+  end
+
+  -- Rust: cargo build + picker
+  dap.configurations.rust = dap.configurations.rust or {
+    {
+      type = "codelldb",
+      request = "launch",
+      name = "Cargo build & launch",
+      program = cargo_build_and_pick,
+      cwd = "${workspaceFolder}",
+    },
+  }
+end
+
+return M

lua/turbo-debug/adapters/go.lua

@@ -0,0 +1,32 @@
+local loader = require("turbo-debug.adapters.init")
+
+local M = {}
+
+function M.register(dap)
+  local dlv = loader.find_executable({ "dlv" })
+  if not dlv then return end
+
+  loader.register(dap, "delve", {
+    type = "server",
+    port = "${port}",
+    executable = {
+      command = dlv,
+      args = { "dap", "-l", "127.0.0.1:${port}" },
+    },
+  }, {
+    {
+      type = "delve",
+      request = "launch",
+      name = "Launch file",
+      program = "${file}",
+    },
+    {
+      type = "delve",
+      request = "launch",
+      name = "Launch package",
+      program = "./${relativeFileDirname}",
+    },
+  }, { "go" })
+end
+
+return M

lua/turbo-debug/adapters/init.lua

@@ -0,0 +1,111 @@
+local config = require("turbo-debug.config")
+
+local M = {}
+
+local mason_bin = vim.fn.stdpath("data") .. "/mason/bin/"
+
+function M.find_executable(names)
+  for _, name in ipairs(names) do
+    if vim.fn.executable(name) == 1 then return name end
+    local mason_path = mason_bin .. name
+    if vim.fn.executable(mason_path) == 1 then return mason_path end
+  end
+end
+
+function M.register(dap, name, adapter, configurations, filetypes)
+  if dap.adapters[name] then return end
+  dap.adapters[name] = adapter
+  for _, ft in ipairs(filetypes) do
+    dap.configurations[ft] = dap.configurations[ft] or configurations
+  end
+end
+
+-- simple executable adapters (inlined — no separate files needed)
+local function register_simple_adapters(dap)
+  local simple = {
+    { "netcoredbg", { "netcoredbg" }, {
+      type = "executable", args = { "--interpreter=vscode" },
+    }, { {
+      type = "netcoredbg", request = "launch", name = "Launch .NET",
+      program = function() return vim.fn.input("Path to DLL: ", vim.fn.getcwd() .. "/bin/Debug/", "file") end,
+    } }, { "cs" } },
+
+    { "java", { "java-debug-adapter" }, {
+      type = "executable",
+    }, { {
+      type = "java", request = "launch", name = "Launch class",
+      mainClass = function() return vim.fn.input("Main class: ") end,
+      cwd = "${workspaceFolder}",
+    } }, { "java" } },
+
+    { "kotlin", { "kotlin-debug-adapter" }, {
+      type = "executable",
+    }, { {
+      type = "kotlin", request = "launch", name = "Launch main",
+      mainClass = function() return vim.fn.input("Main class: ") end,
+      projectRoot = "${workspaceFolder}",
+    } }, { "kotlin" } },
+
+    { "php", { "php-debug-adapter" }, {
+      type = "executable",
+    }, { {
+      type = "php", request = "launch", name = "Listen for Xdebug", port = 9003,
+    } }, { "php" } },
+
+    { "rdbg", { "rdbg" }, {
+      type = "server", port = "${port}",
+      executable = { command = nil, args = { "-n", "--open", "--port", "${port}", "-c", "--", "ruby", "${file}" } },
+    }, { {
+      type = "rdbg", request = "launch", name = "Launch file", command = "ruby", script = "${file}",
+    }, {
+      type = "rdbg", request = "attach", name = "Attach", localfsMap = "${workspaceFolder}",
+    } }, { "ruby" } },
+  }
+
+  for _, s in ipairs(simple) do
+    local name, exe_names, adapter_tpl, configurations, filetypes = s[1], s[2], s[3], s[4], s[5]
+    local exe = M.find_executable(exe_names)
+    if exe then
+      local adapter = vim.deepcopy(adapter_tpl)
+      adapter.command = adapter.command or exe
+      if adapter.executable then adapter.executable.command = exe end
+      M.register(dap, name, adapter, configurations, filetypes)
+    end
+  end
+
+  -- lua/neovim (osv) — optional, skip if not installed
+  local ok, osv = pcall(require, "osv")
+  if ok then
+    M.register(dap, "nlua", {
+      type = "server", host = "127.0.0.1",
+      port = function() return osv.launch({ port = 0 }) end,
+    }, { {
+      type = "nlua", request = "attach", name = "Attach to running Neovim",
+    } }, { "lua" })
+  end
+end
+
+function M.setup()
+  if not config.opts.builtin_adapters then return end
+
+  local dap = require("dap")
+
+  -- load adapters with non-trivial logic from separate files
+  for _, name in ipairs({ "python", "go", "c", "javascript" }) do
+    local ok, adapter_mod = pcall(require, "turbo-debug.adapters." .. name)
+    if ok and adapter_mod.register then
+      adapter_mod.register(dap)
+    end
+  end
+
+  -- register simple adapters inlined above
+  register_simple_adapters(dap)
+
+  -- apply user adapter overrides (last — wins over everything)
+  for name, adapter_config in pairs(config.opts.adapters) do
+    if adapter_config.adapter then dap.adapters[name] = adapter_config.adapter end
+    if adapter_config.configurations then dap.configurations[name] = adapter_config.configurations end
+  end
+end
+
+return M

lua/turbo-debug/adapters/javascript.lua

@@ -0,0 +1,42 @@
+local loader = require("turbo-debug.adapters.init")
+
+local M = {}
+
+function M.register(dap)
+  local js_debug = loader.find_executable({ "js-debug-adapter" })
+  if not js_debug then return end
+
+  local adapter = {
+    type = "server",
+    port = "${port}",
+    executable = {
+      command = js_debug,
+      args = { "${port}" },
+    },
+  }
+
+  local configurations = {
+    {
+      type = "pwa-node",
+      request = "launch",
+      name = "Launch file",
+      program = "${file}",
+      cwd = "${workspaceFolder}",
+    },
+    {
+      type = "pwa-node",
+      request = "attach",
+      name = "Attach",
+      processId = function()
+        return require("dap.utils").pick_process()
+      end,
+      cwd = "${workspaceFolder}",
+    },
+  }
+
+  loader.register(dap, "pwa-node", adapter, configurations, {
+    "javascript", "typescript", "javascriptreact", "typescriptreact",
+  })
+end
+
+return M

lua/turbo-debug/adapters/python.lua

@@ -0,0 +1,52 @@
+local loader = require("turbo-debug.adapters.init")
+
+local M = {}
+
+local function find_python()
+  -- check active virtualenv
+  local venv = vim.env.VIRTUAL_ENV
+  if venv then
+    local path = venv .. "/bin/python"
+    if vim.fn.executable(path) == 1 then return path end
+  end
+
+  -- check conda
+  local conda = vim.env.CONDA_PREFIX
+  if conda then
+    local path = conda .. "/bin/python"
+    if vim.fn.executable(path) == 1 then return path end
+  end
+
+  -- probe common venv directories relative to cwd
+  local cwd = vim.fn.getcwd()
+  for _, dir in ipairs({ ".venv", "venv", "env", ".env" }) do
+    local path = cwd .. "/" .. dir .. "/bin/python"
+    if vim.fn.executable(path) == 1 then return path end
+  end
+
+  -- fallback to system python
+  if vim.fn.executable("python3") == 1 then return "python3" end
+  if vim.fn.executable("python") == 1 then return "python" end
+  return nil
+end
+
+function M.register(dap)
+  local python = find_python()
+  if not python then return end
+
+  loader.register(dap, "debugpy", {
+    type = "executable",
+    command = python,
+    args = { "-m", "debugpy.adapter" },
+  }, {
+    {
+      type = "debugpy",
+      request = "launch",
+      name = "Launch file",
+      program = "${file}",
+      pythonPath = function() return find_python() end,
+    },
+  }, { "python" })
+end
+
+return M

lua/turbo-debug/breakpoints.lua

@@ -0,0 +1,44 @@
+local config = require("turbo-debug.config")
+
+local M = {}
+
+local initialized = false
+
+function M.setup()
+  if initialized then return end
+  initialized = true
+
+  require("persistent-breakpoints").setup({
+    load_breakpoints_event = { "BufReadPost" },
+  })
+
+  -- sign highlights (default = true so colorschemes can override)
+  vim.api.nvim_set_hl(0, "DapBreakpoint", { default = true, fg = "#e06c75" })
+  vim.api.nvim_set_hl(0, "DapBreakpointCondition", { default = true, fg = "#e5c07b" })
+  vim.api.nvim_set_hl(0, "DapBreakpointRejected", { default = true, fg = "#5c6370" })
+  vim.api.nvim_set_hl(0, "DapStopped", { default = true, fg = "#98c379" })
+  vim.api.nvim_set_hl(0, "DapStoppedLine", { default = true, bg = "#2e3b2e" })
+  vim.api.nvim_set_hl(0, "DapLogPoint", { default = true, fg = "#61afef" })
+
+  vim.fn.sign_define("DapBreakpoint", { text = "🔴", texthl = "DapBreakpoint" })
+  vim.fn.sign_define("DapBreakpointCondition", { text = "🟡", texthl = "DapBreakpointCondition" })
+  vim.fn.sign_define("DapBreakpointRejected", { text = "⭕", texthl = "DapBreakpointRejected" })
+  vim.fn.sign_define("DapStopped", { text = "➤", texthl = "DapStopped", linehl = "DapStoppedLine" })
+  vim.fn.sign_define("DapLogPoint", { text = "📝", texthl = "DapLogPoint" })
+
+  -- global mappings (work outside debug mode)
+  local gk = config.opts.global_keys
+  local pb = require("persistent-breakpoints.api")
+  local bindings = {
+    { gk.breakpoint, pb.toggle_breakpoint, "Toggle breakpoint" },
+    { gk.cond_breakpoint, pb.set_conditional_breakpoint, "Conditional breakpoint" },
+    { gk.clear_breakpoints, pb.clear_all_breakpoints, "Clear all breakpoints" },
+  }
+  for _, b in ipairs(bindings) do
+    if b[1] then
+      vim.keymap.set("n", b[1], b[2], { silent = true, desc = b[3] })
+    end
+  end
+end
+
+return M

lua/turbo-debug/config.lua

@@ -0,0 +1,89 @@
+local M = {}
+
+M.defaults = {
+  help_on_enter = true,
+  builtin_adapters = true,
+  quit_exits_mode = true, -- q terminates AND exits debug mode (false = terminate only)
+
+  -- modal keys (active only during debug mode, single-key)
+  keys = {
+    continue = "c",
+    step_over = "s",
+    step_into = "d",
+    step_out = "r",
+    run_to_cursor = "C",
+    breakpoint = "x",
+    cond_breakpoint = "X",
+    clear_breakpoints = "D",
+    watch = "W",
+    hover = "K",
+    eval = "E",
+    terminate = "q",
+    restart = "R",
+    help = "?",
+  },
+
+  -- global keys (always available, <leader>d prefix)
+  global_keys = {
+    toggle = "<leader>dd",
+    breakpoint = "<leader>dx",
+    cond_breakpoint = "<leader>dX",
+    clear_breakpoints = "<leader>dD",
+  },
+
+  dapui = {
+    icons = { expanded = "▼", collapsed = "▶", current_frame = "➤" },
+    controls = {
+      enabled = true,
+      element = "repl",
+    },
+    floating = { border = "rounded" },
+    render = { indent = 2, max_type_length = 20 },
+    layouts = {
+      {
+        position = "right",
+        size = 40,
+        elements = {
+          { id = "scopes", size = 0.50 },
+          { id = "watches", size = 0.25 },
+          { id = "stacks", size = 0.25 },
+        },
+      },
+      {
+        position = "bottom",
+        size = 12,
+        elements = {
+          { id = "repl", size = 0.50 },
+          { id = "console", size = 0.50 },
+        },
+      },
+    },
+  },
+
+  virtual_text = {
+    commented = true,
+    highlight_changed_variables = true,
+    only_first_definition = false,
+    all_frames = false,
+  },
+
+  adapters = {},
+}
+
+M.opts = M.defaults
+
+function M.merge(user_opts)
+  M.opts = vim.tbl_deep_extend("force", vim.deepcopy(M.defaults), user_opts or {})
+  if user_opts then
+    for _, tbl_name in ipairs({ "keys", "global_keys" }) do
+      if user_opts[tbl_name] then
+        for k, v in pairs(user_opts[tbl_name]) do
+          if v == false then M.opts[tbl_name][k] = false end
+        end
+      end
+    end
+  end
+  return M.opts
+end
+
+return M

lua/turbo-debug/help.lua

@@ -0,0 +1,133 @@
+local config = require("turbo-debug.config")
+
+local M = {}
+
+local win_id = nil
+local buf_id = nil
+local timer = nil
+
+local modal_info = {
+  { "continue", "Continue" },
+  { "step_over", "Step over" },
+  { "step_into", "Step into" },
+  { "step_out", "Step out" },
+  { "run_to_cursor", "Run to cursor" },
+  { "breakpoint", "Toggle breakpoint" },
+  { "cond_breakpoint", "Conditional breakpoint" },
+  { "clear_breakpoints", "Clear all breakpoints" },
+  { "watch", "Watch expression" },
+  { "hover", "Hover / inspect" },
+  { "eval", "Eval in REPL" },
+  { "terminate", "Quit debugging" },
+  { "restart", "Restart session" },
+}
+
+local global_info = {
+  { "toggle", "Toggle debug mode" },
+  { "breakpoint", "Toggle breakpoint" },
+  { "cond_breakpoint", "Conditional breakpoint" },
+  { "clear_breakpoints", "Clear all breakpoints" },
+}
+
+local function build_content()
+  local lines = { " turbo-debug", "" }
+  local width = #lines[1]
+
+  local function add(key, label)
+    local line = string.format("  %-12s %s", key, label)
+    lines[#lines + 1] = line
+    if #line > width then width = #line end
+  end
+
+  lines[#lines + 1] = " Debug mode:"
+  for _, pair in ipairs(modal_info) do
+    local key = config.opts.keys[pair[1]]
+    if key then add(key, pair[2]) end
+  end
+
+  lines[#lines + 1] = ""
+  lines[#lines + 1] = " Always available:"
+  for _, pair in ipairs(global_info) do
+    local key = config.opts.global_keys[pair[1]]
+    if key then add(key, pair[2]) end
+  end
+
+  -- highlight line at the bottom
+  local help_key = config.opts.keys.help or "?"
+  lines[#lines + 1] = ""
+  lines[#lines + 1] = " Press " .. help_key .. " for help"
+  lines[#lines + 1] = ""
+
+  return lines, width + 2
+end
+
+function M.close()
+  if timer then
+    timer:stop()
+    timer:close()
+    timer = nil
+  end
+  if win_id and vim.api.nvim_win_is_valid(win_id) then
+    vim.api.nvim_win_close(win_id, true)
+  end
+  win_id = nil
+  if buf_id and vim.api.nvim_buf_is_valid(buf_id) then
+    vim.api.nvim_buf_delete(buf_id, { force = true })
+  end
+  buf_id = nil
+end
+
+local function show(auto_dismiss)
+  M.close()
+
+  local lines, width = build_content()
+  local height = #lines
+
+  buf_id = vim.api.nvim_create_buf(false, true)
+  vim.api.nvim_buf_set_lines(buf_id, 0, -1, false, lines)
+
+  local hl_line = height - 2
+  vim.api.nvim_buf_add_highlight(buf_id, -1, "Bold", hl_line, 0, -1)
+
+  vim.bo[buf_id].modifiable = false
+  vim.bo[buf_id].bufhidden = "wipe"
+
+  local row = math.floor((vim.o.lines - height) / 2)
+  local col = math.floor((vim.o.columns - width) / 2)
+
+  win_id = vim.api.nvim_open_win(buf_id, false, {
+    relative = "editor",
+    row = row,
+    col = col,
+    width = width,
+    height = height,
+    style = "minimal",
+    border = "rounded",
+    focusable = false,
+    noautocmd = true,
+  })
+
+  if auto_dismiss then
+    timer = vim.uv.new_timer()
+    timer:start(3000, 0, vim.schedule_wrap(function() M.close() end))
+  else
+    vim.api.nvim_create_autocmd({ "CursorMoved", "InsertEnter", "CmdlineEnter" }, {
+      once = true,
+      callback = function() M.close() end,
+    })
+  end
+end
+
+function M.open()
+  show(false)
+end
+
+function M.splash()
+  show(true)
+end
+
+function M.is_open()
+  return win_id ~= nil and vim.api.nvim_win_is_valid(win_id)
+end
+
+return M

lua/turbo-debug/init.lua

@@ -0,0 +1,28 @@
+local config = require("turbo-debug.config")
+local mode = require("turbo-debug.mode")
+
+local M = {}
+
+function M.setup(opts)
+  config.merge(opts)
+  require("turbo-debug.breakpoints").setup()
+  require("turbo-debug.adapters").setup()
+
+  -- global toggle keybinding
+  local toggle_key = config.opts.global_keys.toggle
+  if toggle_key then
+    vim.keymap.set("n", toggle_key, function() mode.toggle() end, {
+      silent = true, desc = "Toggle debug mode",
+    })
+  end
+end
+
+function M.toggle()
+  mode.toggle()
+end
+
+function M.active()
+  return mode.is_active()
+end
+
+return M

lua/turbo-debug/mode.lua

@@ -0,0 +1,229 @@
+local config = require("turbo-debug.config")
+local help = require("turbo-debug.help")
+
+local M = {}
+
+local active = false
+local active_buf = nil
+local active_win = nil
+local stashed_maps = {}
+local saved_winbar = nil
+local mapped_keys = {} -- track exactly which keys we set, for reliable cleanup
+
+-- one-time dap-ui and virtual-text initialization
+local dapui_initialized = false
+local vt_initialized = false
+
+local function ensure_dapui()
+  if dapui_initialized then return end
+  dapui_initialized = true
+  require("dapui").setup(config.opts.dapui)
+
+  local dap = require("dap")
+  dap.listeners.after.event_terminated["turbo-debug"] = function()
+    if active then M.exit() end
+  end
+  dap.listeners.after.event_exited["turbo-debug"] = function()
+    if active then M.exit() end
+  end
+
+  -- set winbar titles on dapui panels (REPL gets controls toolbar from dapui)
+  local titles = {
+    dapui_scopes = " Scopes",
+    dapui_watches = " Watches",
+    dapui_stacks = " Call Stack",
+    dapui_console = " Console",
+    dapui_breakpoints = " Breakpoints",
+  }
+  vim.api.nvim_create_autocmd("FileType", {
+    pattern = "dapui_*",
+    callback = function(args)
+      local title = titles[vim.bo[args.buf].filetype]
+      if title then
+        vim.schedule(function()
+          local win = vim.fn.bufwinid(args.buf)
+          if win ~= -1 then vim.wo[win].winbar = title end
+        end)
+      end
+    end,
+  })
+end
+
+local function ensure_vt()
+  if vt_initialized then return end
+  vt_initialized = true
+  require("nvim-dap-virtual-text").setup(config.opts.virtual_text)
+end
+
+-- keymap stash/restore
+
+local function stash_mapping(buf, lhs)
+  for _, map in ipairs(vim.api.nvim_buf_get_keymap(buf, "n")) do
+    if map.lhs == lhs then
+      stashed_maps[lhs] = map
+      return
+    end
+  end
+  stashed_maps[lhs] = nil
+end
+
+local function restore_mapping(buf, lhs)
+  local map = stashed_maps[lhs]
+  if map then
+    local rhs = map.rhs or map.callback
+    if rhs then
+      pcall(vim.keymap.set, "n", lhs, rhs, {
+        buffer = buf,
+        silent = map.silent == 1,
+        noremap = map.noremap == 1,
+        expr = map.expr == 1,
+        desc = map.desc,
+      })
+    end
+  else
+    pcall(vim.keymap.del, "n", lhs, { buffer = buf })
+  end
+end
+
+-- actions (set up once)
+
+local actions = {}
+local visual_actions = { watch = true, hover = true }
+
+local function setup_actions()
+  if next(actions) then return end
+  local dap = require("dap")
+  local pb = require("persistent-breakpoints.api")
+
+  actions.continue = function() dap.continue() end
+  actions.step_over = function() dap.step_over() end
+  actions.step_into = function() dap.step_into() end
+  actions.step_out = function() dap.step_out() end
+  actions.run_to_cursor = function() dap.run_to_cursor() end
+  actions.restart = function() dap.restart() end
+  actions.help = function()
+    if help.is_open() then help.close() else help.open() end
+  end
+  actions.terminate = function()
+    dap.terminate()
+    if config.opts.quit_exits_mode then M.exit() end
+  end
+
+  -- breakpoint actions (modal shortcuts for the <leader>d* globals)
+  actions.breakpoint = function() pb.toggle_breakpoint() end
+  actions.cond_breakpoint = function() pb.set_conditional_breakpoint() end
+  actions.clear_breakpoints = function() pb.clear_all_breakpoints() end
+
+  actions.watch = function()
+    local expr
+    if vim.fn.mode() == "v" or vim.fn.mode() == "V" then
+      vim.cmd('noautocmd normal! "vy')
+      expr = vim.fn.getreg("v")
+    else
+      expr = vim.fn.expand("<cexpr>")
+    end
+    if expr and expr ~= "" then
+      require("dapui").elements.watches.add(expr)
+    end
+  end
+  actions.hover = function() require("dapui").eval() end
+  actions.eval = function() require("dapui").float_element("repl") end
+end
+
+-- keymap lifecycle
+-- track every key we set so cleanup is exact — never miss one, never clear the wrong one
+
+local function set_keymaps(buf)
+  mapped_keys = {}
+  local keys = config.opts.keys
+  for name, key in pairs(keys) do
+    if key and actions[name] then
+      stash_mapping(buf, key)
+      vim.keymap.set("n", key, actions[name], { buffer = buf, silent = true, desc = "turbo-debug: " .. name })
+      if visual_actions[name] then
+        vim.keymap.set("v", key, actions[name], { buffer = buf, silent = true, desc = "turbo-debug: " .. name })
+      end
+      mapped_keys[#mapped_keys + 1] = { name = name, key = key }
+    end
+  end
+end
+
+local function clear_keymaps(buf)
+  if not vim.api.nvim_buf_is_valid(buf) then
+    mapped_keys = {}
+    stashed_maps = {}
+    return
+  end
+  for _, mk in ipairs(mapped_keys) do
+    pcall(vim.keymap.del, "n", mk.key, { buffer = buf })
+    if visual_actions[mk.name] then
+      pcall(vim.keymap.del, "v", mk.key, { buffer = buf })
+    end
+    restore_mapping(buf, mk.key)
+  end
+  mapped_keys = {}
+  stashed_maps = {}
+end
+
+-- debug mode chrome
+
+local function set_debug_chrome()
+  active_win = vim.api.nvim_get_current_win()
+  saved_winbar = vim.wo[active_win].winbar
+  vim.wo[active_win].winbar = "%#DiagnosticError# 🐛 DEBUG %* %f"
+  vim.api.nvim_set_hl(0, "Cursor", { bg = "#ff6600", fg = "#000000" })
+end
+
+local function clear_debug_chrome()
+  if active_win and vim.api.nvim_win_is_valid(active_win) then
+    vim.wo[active_win].winbar = saved_winbar or ""
+  end
+  active_win = nil
+  saved_winbar = nil
+  vim.api.nvim_set_hl(0, "Cursor", {})
+end
+
+-- public API
+
+function M.enter()
+  if active then return end
+  active = true
+  setup_actions()
+
+  active_buf = vim.api.nvim_get_current_buf()
+  set_keymaps(active_buf)
+  set_debug_chrome()
+
+  ensure_dapui()
+  require("dapui").open()
+
+  ensure_vt()
+  require("nvim-dap-virtual-text").enable()
+
+  if config.opts.help_on_enter then
+    help.splash()
+  end
+end
+
+function M.exit()
+  if not active then return end
+  active = false
+
+  clear_keymaps(active_buf or vim.api.nvim_get_current_buf())
+  active_buf = nil
+  clear_debug_chrome()
+  help.close()
+
+  if dapui_initialized then require("dapui").close() end
+  if vt_initialized then require("nvim-dap-virtual-text").disable() end
+end
+
+function M.toggle()
+  if active then M.exit() else M.enter() end
+end
+
+function M.is_active()
+  return active
+end
+
+return M