# Garden Vim Configuration - .gardenvimrc
#
# Welcome! This is your Garden vim config. If you're new to vim, don't worry,
# you only need to know a few basics to make this useful. If you're a vim
# veteran, fair warning: this is a custom, slimmed-down vim implementation,
# not full Vim or Neovim. Lots of things you might be used to (text objects,
# macros, ex-commands beyond the basics, plugins, etc.) are NOT here. What IS
# here is documented below.
#
# This file lives at ~/.config/garden/.gardenvimrc and is loaded once on
# startup (when vim mode is enabled). To reload it after editing, type
# `:source` from inside Garden, or just reopen it with `:vimrc`.
#
# Lines starting with `#` or `"` are comments and are ignored. You can also
# put a comment at the end of a line, but it must be preceded by a space:
#
#       noremap H ^   # this end-of-line comment works
#
# If something in this file is invalid, you'll see a red error in the status
# bar telling you the line number and what went wrong. Click it to jump to
# the offending line.
#
# ============================================================================
# SETTINGS - `set <option>`
# ============================================================================
#
# Line numbers in the gutter - three mutually exclusive modes, pick one:
#
#   set number              # show absolute line numbers (default)
#   set relativenumber      # show line numbers relative to the cursor
#                           # (the cursor line still shows its absolute number)
#   set nonumber            # hide line numbers entirely
#
# Short forms (same meaning, fewer letters):
#
#   set nu       # = set number
#   set rnu      # = set relativenumber
#   set nonu     # = set nonumber
#
# Writing more than one of these just makes the last one win, so there's no
# reason to combine them.
#
# Incremental search - controls what happens while you type a `/` search:
#
#   set incsearch           # (default) highlight matches as you type AND
#                           # preview the first match by jumping the cursor
#                           # to it. <Esc> restores the original position.
#   set noincsearch         # only search after pressing <Enter> (vi-compat)
#
# Short forms:
#
#   set is       # = set incsearch
#   set nois     # = set noincsearch
#
# ============================================================================
# LEADER KEY - `leader <key>`
# ============================================================================
#
# The "leader" key is a single key you choose as a prefix for your custom
# shortcuts. The idea: instead of trying to find an unused key combination
# for every shortcut, you press <Leader> first and then a normal letter.
# Most vim users pick <Space> or `,` because they're easy to reach and
# don't conflict with built-in vim commands.
#
# For example, if you set `leader <Space>` and then map `<Leader>s` to save,
# pressing Space then s will save the file.
#
#   leader <Space>          # use Space as your leader key (recommended)
#   leader ,                # use comma as your leader key
#
# You only need ONE `leader` line. If you don't set one, you can't use
# `<Leader>` in any of your mappings.
#
# ============================================================================
# MAPPING COMMANDS - making your own shortcuts
# ============================================================================
#
# A "mapping" says: when I press THIS key (or sequence of keys), do THAT.
# There are three flavors depending on which mode the mapping applies in:
#
#   noremap   LHS RHS       # works in normal AND visual modes
#   nnoremap  LHS RHS       # works only in normal mode
#   vnoremap  LHS RHS       # works only in visual / visual-line modes
#   inoremap  LHS RHS       # works only in insert mode (single key, safe
#                           # app actions only - see "Insert-mode
#                           # restrictions" below)
#
# LHS = the key(s) you press. RHS = what should happen.
#
# Note for vim veterans: only the `noremap` (non-recursive) forms are
# supported. The recursive `map` / `nmap` / `vmap` / `imap` variants are
# silently ignored.
#
# Insert-mode restrictions: `inoremap` only accepts a single key (no
# multi-key sequences) and the RHS must be `:action <name>` for an
# action from the curated insert-safe set (save, find, command_palette,
# format, goto_definition, etc. - basically anything that doesn't
# mutate the buffer relative to the cursor or expect normal-mode
# semantics). Motions, operators, and ex-commands are rejected.
#
# ============================================================================
# LHS - the key(s) you press (up to 3 keys per mapping)
# ============================================================================
#
# Single character:                  H        L        $
# Angle-bracket key:                 <Esc>    <CR>     <C-d>    <Up>
# Modifier combos:                   <C-x>    <A-x>    <S-Tab>  <A-Up>
# Leader prefix:                     <Leader>s   <Leader>=
# Multi-key sequences (up to 3):     gd       gg       ]d       [d
#
# Special key names you can use inside `< >` (case-insensitive):
#
#   <Esc> / <Escape>            Escape key
#   <CR> / <Enter> / <Return>   Enter / Return key
#   <BS> / <Backspace>          Backspace key
#   <Tab>                       Tab key
#   <S-Tab>                     Shift+Tab
#   <Space>                     Spacebar
#   <Up> <Down> <Left> <Right>  Arrow keys (combine with mods, e.g. <A-Up>)
#   <F1> .. <F12>               Function keys (F1 through F12)
#   <S-F12>                     Shift + function key
#   <Leader>                    Your configured leader key (see above)
#   <C-x>                       Literal Ctrl + x  (always Ctrl, on every
#                               platform - including macOS)
#   <D-x>                       The system mod + x  (Cmd+x on macOS,
#                               Ctrl+x on Linux/Windows). This matches Vim's
#                               `<D-...>` "command key" notation.
#   <A-x>                       Alt+x  (Option+x on macOS - note that Option
#                               produces special characters in insert mode
#                               and text fields)
#   <C-S-x>                     Literal Ctrl + Shift + x
#   <D-S-x>                     System mod + Shift + x
#   <C-A-x>                     Literal Ctrl + Alt + x
#
# Pick `<D-x>` if you want "the standard editor shortcut" (Cmd on Mac,
# Ctrl on Linux/Windows). Pick `<C-x>` only if you really want literal
# Control on every platform.
#
# ============================================================================
# RHS - what the mapping does
# ============================================================================
#
# The right side of a mapping can take any of these forms:
#
# 1. A single vim key - resolves to its built-in action:
#
#       noremap H ^               # ^ -> first_non_blank motion
#       noremap L $               # $ -> line_end motion
#
# 2. A named motion (see MOTIONS below):
#
#       noremap gg file_start     # 'gg' -> file_start
#
# 3. A named builtin action (see BUILTIN ACTIONS below):
#
#       nnoremap U redo
#
# 4. `:action <name>` - invoke a Garden app action (see APP ACTIONS):
#
#       nnoremap <Leader>s :action save
#       nnoremap gd :action goto_definition
#
# 5. `:<excommand>` - invoke an ex-command (see EX-COMMANDS below):
#
#       nnoremap ZZ :wq
#       nnoremap U  :redo
#
# A trailing `<CR>` on `:action` / `:cmd` RHS is allowed and ignored, so
# `:action save<CR>` and `:action save` mean the same thing.
#
# ============================================================================
# MOTIONS - cursor movements
# ============================================================================
#
# Motions move the cursor. They can be used as a mapping RHS, OR as targets
# for the d/c/y operators below (e.g. `dw` deletes a word forward).
#
#   left              right             up                down
#   word_forward      word_backward     word_end
#   line_start        line_end          first_non_blank
#   file_start        file_end          bracket_match
#   para_start        para_end
#
# Default keys (which you can rebind):
#
#   h j k l           # left, down, up, right
#   w b e             # word_forward, word_backward, word_end
#   0 $ ^             # line_start, line_end, first_non_blank
#   gg G              # file_start, file_end
#   %                 # bracket_match (jump between matching brackets)
#   { }               # para_start, para_end (jump to prev/next blank line)
#   f<c> F<c>         # find char forward / backward (lands on the char)
#   t<c> T<c>         # till char forward / backward (lands one before)
#   ; ,               # repeat last f/F/t/T (`,` reverses direction)
#
# ============================================================================
# OPERATORS - act on a range of text
# ============================================================================
#
# Operators combine with a motion to act on the range the motion covers.
# For example, `dw` = delete + word_forward = delete from here to the next
# word. Doubling the operator acts on the whole line: `dd` deletes a line,
# `yy` yanks (copies) a line.
#
#   delete            change            yank
#
# Default keys: d (delete), c (change), y (yank).
#
# Capital-letter shortcuts (act on cursor through end of line / whole line):
#
#   D                 # = d$ (delete to end of line)
#   C                 # = c$ (change to end of line, enter insert mode)
#   Y                 # = yy (yank the whole line)
#
# Single-char replace (no operator - just one keystroke + the new char):
#
#   r<c>              # replace the char under the cursor with <c>
#                     # honors a count: e.g. `3rx` replaces three chars
#
# ============================================================================
# BUILTIN ACTIONS - vim's built-in commands
# ============================================================================
#
# Things vim does that aren't motions or operators. You can refer to these
# by name on the right-hand side of a mapping, or use the default key.
#
#   insert_before        insert_after        insert_line_start    insert_line_end
#   open_below           open_above
#   visual               visual_line
#   paste_after          paste_before
#   undo                 redo                delete_char
#   find_forward         find_backward
#   escape               enter_command
#
# Default keys:
#
#   i I a A           # insert_before, insert_line_start, insert_after, insert_line_end
#   o O               # open_below, open_above (new line below / above)
#   v V               # visual, visual_line
#   p P               # paste_after, paste_before
#   u                 # undo
#   x                 # delete_char
#   r<c>              # replace one char with <c> (count-aware: 3rx)
#   R                 # enter REPLACE mode (overstrike). Each typed char
#                     # overwrites the char under the cursor; backspace
#                     # restores the original; <Esc> exits.
#   f F               # find_forward, find_backward (find a character)
#   :                 # enter_command mode
#
# ============================================================================
# APP ACTIONS - Garden-specific actions, invoked with `:action <name>`
# ============================================================================
#
# These are things only Garden knows how to do (open files, run pickers,
# jump to a definition, etc.). Use them with `:action` on the RHS:
#
#       nnoremap <Leader>s :action save
#
#   next_tab             prev_tab             close_tab            close_all_tabs
#   save                 save_all
#   find                 find_in_files        replace
#   goto_definition      find_references      rename_symbol
#   goto_line            open_file            command_palette
#   toggle_comment       format
#   next_diagnostic      prev_diagnostic
#   fold                 unfold
#   settings             duplicate_line       select_all       quit_app
#   move_line_up         move_line_down
#   add_cursor_next_occurrence   add_cursor_above   add_cursor_below
#   half_page_down       half_page_up
#   nav_back             nav_forward
#   play_from_cursor     cycle_theme          show_diag_peek
#   toggle_bookmark      next_bookmark        prev_bookmark
#   clear_all_bookmarks  show_bookmarks       reveal_log
#   check_for_updates
#
# Activity bar panel toggles. Each mirrors clicking the activity
# bar button: opens & switches if hidden or showing a different
# view, closes the panel if it's already the visible view. The
# command palette + shortcut helper render the label dynamically
# as "Open Files" or "Close Files" based on current state.
#
#   toggle_files_panel       toggle_actors_panel
#   toggle_locations_panel   toggle_search_panel
#   toggle_story_panel       toggle_test_panel
#   toggle_locale_panel
#
# Activity bar panel focus. Opens & switches like toggle, but
# never closes -- idempotent "show me this panel".
#
#   focus_files_panel         focus_actors_panel
#   focus_locations_panel     focus_search_panel
#   focus_story_panel         focus_test_panel
#   focus_state_panel         focus_flow_graph_panel
#   focus_locale_panel
#
# Story view playback navigation. Strictly focus-gated: these
# only fire when the story panel is the focused panel AND the
# right panel is showing the .story view. They also only appear
# in the shortcut helper popup under that condition. When fired
# from a key that's bound globally (like the default Alt+Up/Down
# below), the dispatcher falls through to the focused panel if
# the story view isn't active - so the same key can do double
# duty without stealing input from the editor.
#
#   story_rewind         story_fast_forward   story_restart
#
# ============================================================================
# DEFAULT APP HOTKEYS - already bound, override with your own mappings
# ============================================================================
#
# These shortcuts are wired up by Garden out-of-the-box. Each one is also
# a normal `.gardenvimrc` lookup: in normal, visual, or insert mode you
# can shadow any default by binding the same key to a different
# `:action` (or, in normal/visual modes, to any motion / builtin /
# ex-command). The `<D-...>` entries below use the platform's system
# mod (Cmd on macOS, Ctrl on Linux/Windows) - see the modifier section
# above for the `<C-x>` vs `<D-x>` distinction.
#
#   <F2>           rename_symbol
#   <F5>           play_from_cursor
#   <F8>           next_diagnostic
#   <S-F8>         prev_diagnostic
#   <F10>          cycle_theme
#   <F12>          goto_definition
#   <S-F12>        find_references
#
#   <D-s>          save
#   <D-S-s>        save_all
#   <D-k>          command_palette
#   <D-o>          open_file
#   <D-g>          goto_line
#   <D-S-f>        find_in_files
#   <D-,>          settings
#   <D-.>          show_diag_peek
#   <D-f>          find
#   <D-r>          replace
#
#   <D-1>          focus_files_panel
#   <D-2>          focus_actors_panel
#   <D-3>          focus_locations_panel
#   <D-4>          focus_search_panel
#   <D-A-1>        focus_story_panel
#   <D-A-2>        focus_test_panel
#   <D-A-3>        focus_state_panel
#   <D-A-4>        focus_flow_graph_panel
#   <D-A-5>        focus_locale_panel
#
#   <A-Up>         story_rewind         (only fires when story view focused)
#   <A-Down>       story_fast_forward   (only fires when story view focused)
#   <A-Up>         move_line_up         (only fires when editor focused)
#   <A-Down>       move_line_down       (only fires when editor focused)
#
#   <D-d>          add_cursor_next_occurrence
#   <D-S-d>        duplicate_line
#   <D-A-Up>       add_cursor_above
#   <D-A-Down>     add_cursor_below
#
#   <C-m>          toggle_bookmark
#   <C-S-m>        show_bookmarks
#   <F3>           next_bookmark
#   <S-F3>         prev_bookmark
#
# Example: make Cmd+S quit instead of save in normal mode:
#
#   nnoremap <D-s> :action quit_app   " or any other action
#
# Example: make Cmd+S save in insert mode too (default insert-mode
# behavior already saves via the always-on dispatch - this is just to
# show that `inoremap` works for `<D-x>` chords):
#
#   inoremap <D-s> :action save
#
# ============================================================================
# EX-COMMANDS - invoked with `:<cmd>`
# ============================================================================
#
# These are the classic vim "colon commands". You can also type them live
# from inside Garden by pressing `:` in normal mode.
#
#   :w   / :write         save the current file
#   :q   / :quit          close the current tab
#   :wq  / :x             save then close
#   :q!                   force-close (discard unsaved changes)
#   :wa                   save all open tabs
#   :qa                   close all open tabs (refused if any are dirty)
#   :wqa / :xa            save all then close all
#   :qa!                  force-close all (discard unsaved changes everywhere)
#   :redo                 redo the last undo
#   :vimrc                open this file in a tab
#
# Other ex-commands available at runtime (typed live, not used as a RHS):
#
#   :<N>                  jump to line N (e.g. `:42` jumps to line 42)
#   :source               reload .gardenvimrc after editing it
#   :set <option>         change a setting at runtime
#   :reg / :registers     pop up the contents of every named register
#
# Substitute - find and replace within a line range:
#
#   :s/pat/rep/[flags]    replace `pat` with `rep` on the current line
#   :%s/pat/rep/[flags]   replace `pat` with `rep` in the whole buffer
#   :N,Ms/pat/rep/[flags] replace within lines N..M (1-based, inclusive)
#   :'<,'>s/pat/rep/[flg] replace within the last visual selection
#
# Pressing `:` while in visual or visual-line mode auto-prefills the
# command line with `'<,'>` so you can immediately type `s/pat/rep/g`.
#
# Supported flags:
#   g   replace every occurrence on each line (default: only first)
#   i   case-insensitive match
#   I   force case-sensitive match (overrides `i`)
#
# Range tokens: empty = current line, `%` = whole buffer, `.` = current,
# `$` = last line, `N` = line N, `N,M` = N through M, `'<,'>` = last visual.
# Escapes inside the pattern/replacement: `\\` -> `\`, `\/` -> `/`. The
# confirm flag `c` is not supported.
#
# ============================================================================
# REGISTERS - the things vim yanks, deletes, and pastes go in and out of
# ============================================================================
#
# Garden has the standard vim register set. Prefix any operator or paste
# with `"<name>` to target a specific register:
#
#   "ayy             yank current line into register `a`
#   "ap              paste from register `a`
#   "_dd             delete the line into the black-hole register
#                    (so it does NOT clobber the unnamed register)
#   "+y              copy the selection to the system clipboard
#   "+p              paste from the system clipboard
#   "Ayy             APPEND current line to register `a` (uppercase appends)
#
# Available registers:
#
#   ""               unnamed - the default. Every yank/delete that
#                    isn't explicitly aimed at `_` lands here.
#   "0               last yank only (deletes don't touch it).
#   "1 .. "9         delete history. Newest delete goes to "1, the old
#                    "1 shifts to "2, and so on. Only deletes that span
#                    at least one full line use this ring; smaller
#                    deletes go to "- instead (matches real vim).
#   "-               small delete (charwise, less than a line).
#   "a .. "z         named registers. Lowercase replaces the slot,
#                    UPPERCASE appends to it.
#   "_               black hole - discards on write, returns nothing
#                    on read. Use it for "I want to delete this without
#                    losing what I just yanked".
#   "+ / "*          system clipboard. Aliased - both names point at
#                    the same OS clipboard. Garden also auto-syncs the
#                    unnamed register to the clipboard, so a plain `yy`
#                    is already pasteable in other apps.
#   "/               last search pattern. Read-only. `/foo<CR>` then
#                    `"/p` pastes `foo` at the cursor.
#
# Skipped (not implemented): ".  "%  ":  "#  "=
#
# Insert mode: `<C-r><reg>` pastes the named register's contents at
# the cursor without leaving insert mode. For example, `<C-r>a` inserts
# whatever's in register `a`.
#
# Type `:reg` (or `:registers`) to pop up a window listing every
# non-empty register and its contents.
#
# ============================================================================
# EXAMPLE MAPPINGS - uncomment any of these you want to try
# ============================================================================
#
# These are commented out by default. Delete the leading `#` to enable one.

# set relativenumber
# set noincsearch
# leader <Space>

# Motion remaps
# noremap H ^
# noremap L $
# noremap gg file_start

# Half-page scrolling (noremap so it works in visual mode too)
# noremap <C-d> :action half_page_down
# noremap <C-u> :action half_page_up

# Navigation history (jump back/forward through cursor history)
# nnoremap gb :action nav_back
# nnoremap gf :action nav_forward

# Tab navigation
# nnoremap <Tab>   :action next_tab
# nnoremap <S-Tab> :action prev_tab
# nnoremap <Leader>q :action close_tab

# Quick save
# nnoremap <Leader>s :action save

# Code navigation
# nnoremap gd :action goto_definition
# nnoremap <Leader>u :action find_references
# nnoremap <Leader>r :action rename_symbol

# Diagnostics (errors / warnings)
# nnoremap ]d :action next_diagnostic
# nnoremap [d :action prev_diagnostic

# Format / comment
# nnoremap <Leader>f :action format
# nnoremap <Leader>c :action toggle_comment

# Pickers
# nnoremap <C-a> :action command_palette
# nnoremap <C-f> :action open_file
# nnoremap <C-/> :action find_in_files

# Redo with capital U (instead of Ctrl-R)
# nnoremap U :redo

# Override a default app hotkey: rebind <F2> to format the buffer instead
# of opening the rename dialog. (See "DEFAULT APP HOTKEYS" above.)
# nnoremap <F2> :action format