unmount on Buf{Delete,Unload}, too, not just Wipeout

Author: jrop

AGENTS.md

@@ -10,6 +10,50 @@
 
 **Single test**: Use busted directly: `busted --verbose --filter='"<FULL TEST NAME HERE>"'`
 
+## Test Environment Notes
+
+### TextChanged Autocmds in Headless Mode
+
+**Key Understanding**: `TextChanged` autocmds don't fire in headless neovim due to typeahead/operator pending behavior:
+
+- **`TextChanged`/`TextChangedI`/`TextChangedP` autocmds**: Do NOT fire in headless mode, regardless of whether changes are programmatic (`nvim_buf_set_lines`) or simulated user input (`feedkeys`, `vim.cmd.normal`). According to `:help TextChanged`: *"Not triggered when there is typeahead or when an operator is pending."*
+- **`nvim_buf_attach` with `on_bytes` callback**: DOES fire reliably in all scenarios (headless, interactive, programmatic, user input).
+- **`changedtick`**: Does increment for all buffer changes, providing a way to detect that changes occurred.
+
+This is why tests require manual `r.buf_watcher.fire()` calls - the current implementation uses `TextChanged` autocmd to batch `on_bytes` events, but this autocmd never fires in headless test environments.
+
+**Current workaround in tests**: Call `r.buf_watcher.fire()` manually after programmatic buffer changes to simulate the autocmd that would fire with real user input.
+
+### Buffer Event Testing
+
+- **Buffer cleanup**: Tests use `with_buf()` wrapper that explicitly calls `vim.cmd.bdelete { bang = true }`, which fires all deletion events (`BufUnload`, `BufDelete`, `BufWipeout`) regardless of `bufhidden` settings
+- **Event testing**: To test buffer deletion events, use explicit `vim.api.nvim_buf_delete(bufnr, { force = true })` rather than Vim commands like `:enew` or `:tabclose`, which have inconsistent behavior depending on `bufhidden`
+
+### Testing Neovim Behaviors Interactively
+
+When you need to quickly test Neovim behaviors outside of the formal test suite:
+
+1. **Create a test script**: Create a standalone `.lua` file (e.g., `test_behavior.lua`) in the project root
+2. **Write the test**: Use standard Lua and Neovim API calls. The script should end with `vim.cmd.qall { bang = true }` to exit
+3. **Run the test**: Execute with `nvim --headless -u NONE -c "set rtp+=." -c "luafile test_behavior.lua" 2>&1`
+   - `--headless`: Run without UI
+   - `-u NONE`: Don't load user config
+   - `-c "set rtp+=."`: Add current directory to runtime path so `require 'morph'` works
+   - `-c "luafile test_behavior.lua"`: Execute your test script
+   - `2>&1`: Capture all output
+4. **Clean up**: Delete test files when done (they should not be committed)
+
+**Example test script**:
+```lua
+#!/usr/bin/env nvim -l
+local Morph = require 'morph'
+-- Your test code here
+vim.print('Testing something...')
+vim.cmd.qall { bang = true }
+```
+
+**Note**: Interactive nvim commands with input (like `nvim --headless -c "..."` where commands expect user input) will hang. Always use non-interactive commands or scripts.
+
 ## Code Style Guidelines
 
 ### Formatting
@@ -20,7 +64,7 @@
 - Sort requires automatically
 
 ### Type Annotations
-- Use EmmyLua type annotations (`---@param`, `---@return`, `---@type`)
+- Use EmmyLua type annotations (`--- @param`, `--- @return`, `--- @type`)
 - Follow patterns in existing code: `morph.Ctx<Props, State>`
 - Component functions should annotate props and state types
 

lua/morph.lua

@@ -544,15 +544,15 @@ function Morph.new(bufnr)
   )
   table.insert(self.cleanup_hooks, self.buf_watcher.cleanup)
 
-  local wipeout_id = vim.api.nvim_create_autocmd('BufWipeout', {
+  local cleanup_autocmd = vim.api.nvim_create_autocmd({ 'BufDelete', 'BufUnload', 'BufWipeout' }, {
     buffer = self.bufnr,
     callback = function()
       for _, cleanup_hook in ipairs(self.cleanup_hooks) do
         cleanup_hook()
       end
     end,
   })
-  table.insert(self.cleanup_hooks, function() vim.api.nvim_del_autocmd(wipeout_id) end)
+  table.insert(self.cleanup_hooks, function() vim.api.nvim_del_autocmd(cleanup_autocmd) end)
 
   return self
 end
@@ -862,16 +862,16 @@ function Morph:mount(tree)
     end
   end
 
-  -- Don't track this autocmd in cleanup_hooks, because the prior BufWipeout
+  -- Don't track this autocmd in cleanup_hooks, because the prior BufDelete/BufUnload/BufWipeout
   -- will take priority, and will delete this autocmd before it even has a
   -- chance to run:
-  local wipeout_id
-  wipeout_id = vim.api.nvim_create_autocmd('BufWipeout', {
+  local unmount_autocmd_id
+  unmount_autocmd_id = vim.api.nvim_create_autocmd({ 'BufDelete', 'BufUnload', 'BufWipeout' }, {
     buffer = self.bufnr,
     callback = function()
       -- Effectively unmount everything:
       H2.visit_tree(self.component_tree.old, nil)
-      vim.api.nvim_del_autocmd(wipeout_id)
+      vim.api.nvim_del_autocmd(unmount_autocmd_id)
     end,
   })