*turbo-debug.txt*    A zero-config debugging experience for Neovim 0.12+

==============================================================================
CONTENTS                                            *turbo-debug-contents*

  1. Introduction .......................... |turbo-debug-introduction|
  2. Installation .......................... |turbo-debug-installation|
  3. Setup ................................. |turbo-debug.setup|
  4. Debug Mode ............................ |turbo-debug-debug-mode|
  5. Keybindings ........................... |turbo-debug.keys|
  6. Breakpoints ........................... |turbo-debug-breakpoints|
  7. UI Layout ............................. |turbo-debug-layout|
  8. Adapters .............................. |turbo-debug.adapters|
  9. API ................................... |turbo-debug-api|
 10. Troubleshooting ....................... |turbo-debug-troubleshooting|

==============================================================================
1. Introduction                                 *turbo-debug-introduction*

turbo-debug.nvim gives you a fully-featured, beautiful debugging experience
out of one line of config. Under the hood it wires together nvim-dap,
nvim-dap-ui, nvim-dap-virtual-text, and persistent-breakpoints into a single
cohesive experience with modal keybindings.

Features:
- Inline virtual text showing variable values in source code
- Hover inspection with `K`
- Persistent breakpoints that survive restarts
- Watch expressions from the code window with `W`
- Scopes, stacks, REPL, and console panels
- Modal keybindings active only during debug sessions
- Help box showing all keybindings
- Zero-config adapters for 10+ languages

==============================================================================
2. Installation                                 *turbo-debug-installation*

Add one line to your init.lua: >lua
  vim.pack.add("swaits/turbo-debug.nvim")
<
That's it. All dependencies are managed automatically.

Requires Neovim >= 0.12.

==============================================================================
3. Setup                                               *turbo-debug.setup*

Setup is optional. The plugin works with no configuration. To customize: >lua
  require("turbo-debug").setup({
    help_on_enter = true,       -- show help splash on debug mode entry
    quit_exits_mode = true,     -- q terminates AND exits debug mode
    builtin_adapters = true,    -- register built-in language adapters
    keys = { ... },             -- override modal keybindings
    global_keys = { ... },      -- override always-available keybindings
    adapters = { ... },         -- override or add language adapters
    dapui = { ... },            -- override nvim-dap-ui layout/settings
    virtual_text = { ... },     -- override nvim-dap-virtual-text settings
  })
<
                                           *turbo-debug.setup.help_on_enter*
help_on_enter ~
  Type: boolean, Default: `true`
  Show the help box automatically when entering debug mode.

                                        *turbo-debug.setup.builtin_adapters*
builtin_adapters ~
  Type: boolean, Default: `true`
  Register built-in adapters for supported languages. Set to `false` to
  disable all built-in adapter registration.

==============================================================================
4. Debug Mode                                    *turbo-debug-debug-mode*

Press `<leader>dd` to toggle debug mode.

Entering debug mode:
1. Opens nvim-dap-ui with the configured layout
2. Enables inline virtual text for variable values
3. Activates modal keybindings (buffer-local)
4. Shows winbar indicator and help splash (3s)

Exiting debug mode (any of):
- `<leader>dd` again (manual toggle)
- `q` (terminate session — exits debug mode if `quit_exits_mode`)
- DAP session ends naturally

On exit, everything is restored: keymaps, UI, virtual text, cursor.

==============================================================================
5. Keybindings                                         *turbo-debug.keys*

Modal keybindings are active only during debug mode. They shadow editing
keys you don't need while debugging, but preserve all navigation keys.

Default keymap:

  Key   Action                    Mnemonic ~
  `c`     Continue                  Universal across debuggers
  `s`     Step over                 Step
  `d`     Step into                 Descend into the function
  `r`     Step out                  Return from the function
  `C`     Run to cursor             Continue to cursor
  `x`     Toggle breakpoint         X marks the spot
  `X`     Conditional breakpoint    Shift variant of x
  `D`     Clear all breakpoints     Delete all
  `W`     Watch expr under cursor   Watch
  `K`     Hover / inspect           Matches LSP hover convention
  `E`     Eval in REPL              Evaluate
  `q`     Terminate session         Quit debugging
  `R`     Restart session           Rerun
  `?`     Help popup                Show keybindings

Always available (under `<leader>d` prefix, with which-key support):

  `<leader>dd`  Toggle debug mode
  `<leader>dx`  Toggle breakpoint         X marks the spot
  `<leader>dX`  Conditional breakpoint    Shift variant
  `<leader>dD`  Clear all breakpoints     Delete all

Override any key: >lua
  require("turbo-debug").setup({
    keys = {                          -- modal keys (debug mode only)
      continue = "g",
      step_over = false,              -- set to false to disable
    },
    global_keys = {                   -- always-available keys
      toggle = "<leader>DD",
      breakpoint = "<leader>db",
    },
  })
<
Preserved keys (not shadowed):
- Navigation: `h j k l w b e f F t T / n N 0 ^ $ G g { } % [ ]`
- Insert: `i a o O` (needed for REPL/terminal)
- Visual/yank: `v V y p u`
- All Ctrl/leader combos

                                       *turbo-debug.setup.quit_exits_mode*
quit_exits_mode ~
  Type: boolean, Default: `true`
  Whether `q` (terminate) also exits debug mode. Set to `false` if you
  want `q` to terminate the process but keep the debug UI open.

==============================================================================
6. Breakpoints                                  *turbo-debug-breakpoints*

Breakpoints are managed by persistent-breakpoints.nvim. They persist across
Neovim restarts and are visible in the sign column at all times.

`<leader>dx` toggles a breakpoint (always available).
`<leader>dX` sets a conditional breakpoint (always available).
`x`, `X`, `D` also work as shortcuts during debug mode.

==============================================================================
7. UI Layout                                       *turbo-debug-layout*

Default layout:

  Left sidebar (40 columns):
  - Scopes (50%) — local/global variables in current frame
  - Watches (25%) — user-added watch expressions
  - Stacks (25%) — call stack navigation

  Bottom tray (12 lines):
  - REPL (50%) — evaluate expressions
  - Console (50%) — program stdout/stderr

Override the layout: >lua
  require("turbo-debug").setup({
    dapui = {
      layouts = { ... },  -- see nvim-dap-ui docs for format
    },
  })
<
==============================================================================
8. Adapters                                        *turbo-debug.adapters*

Built-in adapter support (adapter binary must be installed):

  Language         Adapter          Binary ~
  Python           debugpy          python -m debugpy
  JavaScript/TS    js-debug         js-debug-adapter
  Go               delve            dlv
  C/C++            codelldb         codelldb
  Rust             codelldb         codelldb
  Swift            codelldb         codelldb
  C#               netcoredbg       netcoredbg
  Java             java-debug       java-debug-adapter
  Kotlin           kotlin-debug     kotlin-debug-adapter
  PHP              php-debug        php-debug-adapter
  Ruby             rdbg             rdbg
  Lua (Neovim)     osv              one-small-step-for-vimkind

Path resolution order:
1. User override via `opts.adapters`
2. Binary on `$PATH`
3. Standard mason install path (~/.local/share/nvim/mason/bin/)

Adapter binaries are the user's responsibility to install.

Override or add adapters: >lua
  require("turbo-debug").setup({
    adapters = {
      python = { ... },    -- override built-in
      zig = { ... },        -- add new language
    },
    builtin_adapters = false,  -- disable all built-ins
  })
<
Existing user nvim-dap configurations are never overridden.

==============================================================================
9. API                                              *turbo-debug-api*

                                                    *turbo-debug.toggle()*
require("turbo-debug").toggle()
  Toggle debug mode on/off.

                                                    *turbo-debug.active()*
require("turbo-debug").active()
  Returns `true` if debug mode is currently active, `false` otherwise.
  Useful for statusline integration.

==============================================================================
10. Troubleshooting                          *turbo-debug-troubleshooting*

No adapter found ~
  Ensure the adapter binary is installed and on your PATH, or installed
  via mason.nvim. turbo-debug configures adapters, it does not install
  them.

Breakpoints not persisting ~
  Check that persistent-breakpoints.nvim is loaded. Run:
  `:lua print(require("persistent-breakpoints") and "ok")`

Virtual text not appearing ~
  Virtual text only appears during an active DAP session in debug mode.
  Ensure nvim-dap-virtual-text is loaded:
  `:lua print(require("nvim-dap-virtual-text") and "ok")`

Version error ~
  turbo-debug.nvim requires Neovim >= 0.12 for vim.pack support.

==============================================================================
vim:tw=78:ts=8:ft=help:norl:
