Merge upstream/main into feature/external-server

Resolved conflict in event_manager.lua by combining:
- Upstream's normalized_events processing
- Our nil-checking for event.type to prevent errors

All other files merged automatically.

Author: sei-dwtompkins

AGENTS.md

@@ -3,61 +3,11 @@
 ## Build, Lint, and Test
 
 - **Run all tests:** `./run_tests.sh`
-- **Minimal tests:** `./run_tests.sh -t minimal`
-  `nvim --headless -u tests/minimal/init.lua -c "lua require('plenary.test_harness').test_directory('./tests/minimal', {minimal_init = './tests/minimal/init.lua', sequential = true})"`
-- **Unit tests:** `./run_tests.sh -t unit`
-  `nvim --headless -u tests/minimal/init.lua -c "lua require('plenary.test_harness').test_directory('./tests/unit', {minimal_init = './tests/minimal/init.lua'})"`
-- **Replay tests:** `./run_tests.sh -t replay`
-  `nvim --headless -u tests/minimal/init.lua -c "lua require('plenary.test_harness').test_directory('./tests/replay', {minimal_init = './tests/minimal/init.lua'})"`
 - **Run a single test:** Replace the directory in the above command with the test file path, e.g.:
-  `nvim --headless -u tests/manual/init.lua -c "lua require('plenary.test_harness').test_directory('./tests/unit/job_spec.lua', {minimal_init = './tests/minimal/init.lua'})"`
-- **Manual/Visual tests:** `./tests/manual/run_replay.sh` - Replay captured event data for visual testing
-- **Debug rendering in headless mode:**
-  `nvim --headless -u tests/manual/init_replay.lua "+ReplayHeadless" "+ReplayLoad tests/data/FILE.json" "+ReplayAll 0" "+qa"`
-  This will replay events and dump the output buffer to stdout, useful for debugging rendering issues without a UI.
-  You can also run to just a specific message # with (e.g. message # 12):
-  `nvim --headless -u tests/manual/init_replay.lua "+ReplayHeadless" "+ReplayLoad tests/data/message-removal.json" "+ReplayNext 12" "+qa"`
-- **Lint:** No explicit lint command; follow Lua best practices.
+  - `./run_tests.sh -t tests/unit/test_example.lua`
 
 ## Code Style Guidelines
 
-- **Imports:** `local mod = require('mod')` at the top. Group standard, then project imports.
-- **Formatting:** 2 spaces per indent. No trailing whitespace. Lines ≤ 100 chars.
-- **Types:** Use Lua annotations (`---@class`, `---@field`, etc.) for public APIs/config.
-- **Naming:** Modules: `snake_case.lua`; functions/vars: `snake_case`; classes: `CamelCase`.
-- **Error Handling:** Use `vim.notify` for user-facing errors. Return early on error.
-- **Comments:** Avoid obvious comments that merely restate what the code does. Only add comments when necessary to explain *why* something is done, not *what* is being done. Prefer self-explanatory code.
-- **Functions:** Prefer local functions. Use `M.func` for module exports.
+- **Comments:** Avoid obvious comments that merely restate what the code does. Only add comments when necessary to explain _why_ something is done, not _what_ is being done. Prefer self-explanatory code.
 - **Config:** Centralize in `config.lua`. Use deep merge for user overrides.
-- **Tests:** Place in `tests/minimal/`, `tests/unit/`, or `tests/replay/`. Manual/visual tests in `tests/manual/`.
-
-_Agentic coding agents must follow these conventions strictly for consistency and reliability._
-
-## File Reference Detection
-
-The plugin automatically detects file references in LLM responses and makes them navigable via the reference picker (`<leader>or` or `:Opencode references`).
-
-### Supported Formats
-
-The reference picker recognizes these file reference patterns:
-
-1. **Backtick-wrapped** (recommended by LLMs naturally):
-   - `` `path/to/file.lua` ``
-   - `` `path/to/file.lua:42` ``
-   - `` `path/to/file.lua:42:10` `` (with column)
-   - `` `path/to/file.lua:42-50` `` (line range)
-
-2. **file:// URIs** (backward compatibility):
-   - `file://path/to/file.lua`
-   - `file://path/to/file.lua:42`
-   - `file://path/to/file.lua:42-50`
-
-3. **Plain paths** (natural format):
-   - `path/to/file.lua`
-   - `path/to/file.lua:42`
-   - `./relative/path.lua:42`
-   - `/absolute/path.lua:42`
-
-All formats support both relative and absolute paths. Files must exist to be recognized (validation prevents false positives).
-
-**No system prompt configuration is required** - the parser works with all LLM providers, including those without system prompt support.
+- **Types:** Use Lua annotations (`---@class`, `---@field`, etc.) for public APIs/config.

README.md

@@ -216,6 +216,7 @@ require('opencode').setup({
     },
   },
   ui = {
+    enable_treesitter_markdown = true, -- Use Treesitter for markdown rendering in the output window (default: true).
     position = 'right', -- 'right' (default), 'left' or 'current'. Position of the UI split. 'current' uses the current window for the output.
     input_position = 'bottom', -- 'bottom' (default) or 'top'. Position of the input window
     window_width = 0.40, -- Width as percentage of editor width
@@ -224,6 +225,7 @@ require('opencode').setup({
     display_context_size = true, -- Display context size in the footer
     display_cost = true, -- Display cost in the footer
     window_highlight = 'Normal:OpencodeBackground,FloatBorder:OpencodeBorder', -- Highlight group for the opencode window
+    persist_state = true, -- Keep buffers when toggling/closing UI so window state restores quickly
     icons = {
       preset = 'nerdfonts', -- 'nerdfonts' | 'text'. Choose UI icon style (default: 'nerdfonts')
       overrides = {}, -- Optional per-key overrides, see section below
@@ -456,6 +458,19 @@ Available icon keys (see implementation at lua/opencode/ui/icons.lua lines 7-29)
 - status_on, status_off
 - border, bullet
 
+### Window Persistence Behavior
+
+`ui.persist_state` controls how `toggle` behaves:
+
+- `persist_state = true` (default): `toggle()` hides/restores the UI and keeps buffers/session view in memory for fast restore.
+- `persist_state = false`: `toggle()` fully tears down UI buffers and recreates them on next open.
+
+Related APIs:
+
+- `require('opencode.api').toggle()` follows the `persist_state` behavior above.
+- `require('opencode.api').close()` always fully closes and clears hidden snapshot state.
+- `require('opencode.api').hide()` preserves buffers only when `persist_state = true`; otherwise it behaves like close.
+
 ### Picker Layout
 
 You can customize the layout of the picker used for history, session, references, and timeline
@@ -637,6 +652,7 @@ The plugin provides the following actions that can be triggered via keymaps, com
 - `open_input` (boolean, default: `true`): Whether to open the input window after adding the selection. Set to `false` to add selection silently without changing focus.
 
 Example keymap for silent add:
+
 ```lua
 ['<leader>oY'] = { 'add_visual_selection', { open_input = false }, mode = {'v'} }
 ```

lua/opencode/api.lua

@@ -48,40 +48,101 @@ function M.close()
     return
   end
 
-  ui.close_windows(state.windows)
+  ui.teardown_visible_windows(state.windows)
+end
+
+function M.hide()
+  ui.hide_visible_windows(state.windows)
 end
 
 function M.paste_image()
   core.paste_image_from_clipboard()
 end
 
---- Check if opencode windows are in the current tab page
---- @return boolean
-local function are_windows_in_current_tab()
-  if not state.windows or not state.windows.output_win then
-    return false
+---@return {status: 'closed'|'hidden'|'visible', position: string, windows: OpencodeWindowState|nil, cursor_positions: {input: integer[]|nil, output: integer[]|nil}}
+function M.get_window_state()
+  return state.get_window_state()
+end
+
+---@param hidden OpencodeHiddenBuffers|nil
+---@return 'input'|'output'
+local function resolve_hidden_focus(hidden)
+  if hidden and (hidden.focused_window == 'input' or hidden.focused_window == 'output') then
+    return hidden.focused_window
+  end
+
+  if hidden and hidden.input_hidden then
+    return 'output'
+  end
+
+  return 'input'
+end
+
+---@param restore_hidden boolean
+---@return {focus: 'input'|'output', open_action: 'reuse_visible'|'restore_hidden'|'create_fresh'}
+local function build_toggle_open_context(restore_hidden)
+  if restore_hidden then
+    local hidden = state.inspect_hidden_buffers()
+    return {
+      focus = resolve_hidden_focus(hidden),
+      open_action = 'restore_hidden',
+    }
   end
 
-  local current_tab = vim.api.nvim_get_current_tabpage()
-  local ok, win_tab = pcall(vim.api.nvim_win_get_tabpage, state.windows.output_win)
-  return ok and win_tab == current_tab
+  local focus = config.ui.input.auto_hide and 'input'
+    or state.last_focused_opencode_window
+    or 'input'
+
+  return {
+    focus = focus,
+    open_action = 'create_fresh',
+  }
 end
 
 M.toggle = Promise.async(function(new_session)
-  -- When auto_hide input is enabled, always focus input; otherwise use last focused
-  local focus = 'input' ---@cast focus 'input' | 'output'
-  if not config.ui.input.auto_hide then
-    focus = state.last_focused_opencode_window or 'input'
+  local decision = state.resolve_toggle_decision(
+    config.ui.persist_state,
+    state.display_route ~= nil
+  )
+  local action = decision.action
+  local is_new_session = new_session == true
+
+  local function open_windows(restore_hidden)
+    local ctx = build_toggle_open_context(restore_hidden == true)
+    return core.open({
+      new_session = is_new_session,
+      focus = ctx.focus,
+      start_insert = false,
+      open_action = ctx.open_action,
+    }):await()
   end
 
-  if state.windows == nil or not are_windows_in_current_tab() then
+  local function open_fresh_windows()
+    return open_windows(false)
+  end
+
+  local function restore_hidden_windows()
+    return open_windows(true)
+  end
+
+  local function migrate_windows()
     if state.windows then
-      M.close()
+      ui.teardown_visible_windows(state.windows)
     end
-    core.open({ new_session = new_session == true, focus = focus, start_insert = false }):await()
-  else
-    M.close()
+    return open_fresh_windows()
   end
+
+  local action_handlers = {
+    close = M.close,
+    hide = M.hide,
+    close_hidden = ui.drop_hidden_snapshot,
+    migrate = migrate_windows,
+    restore_hidden = restore_hidden_windows,
+    open = open_fresh_windows,
+  }
+
+  local handler = action_handlers[action] or action_handlers.open
+  return handler()
 end)
 
 ---@param new_session boolean?
@@ -271,7 +332,7 @@ function M.set_review_breakpoint()
 end
 
 function M.prev_history()
-  if not state.windows then
+  if not state.is_visible() then
     return
   end
   local prev_prompt = history.prev()
@@ -282,7 +343,7 @@ function M.prev_history()
 end
 
 function M.next_history()
-  if not state.windows then
+  if not state.is_visible() then
     return
   end
   local next_prompt = history.next()
@@ -517,7 +578,7 @@ function M.help()
     '|--------------|-------------|',
   }, false)
 
-  if not state.windows or not state.windows.output_win then
+  if not state.is_visible() or not state.windows.output_win then
     return
   end
 
@@ -1051,6 +1112,13 @@ M.commands = {
     end,
   },
 
+  hide = {
+    desc = 'Hide opencode windows (preserve buffers for fast restore)',
+    fn = function(args)
+      M.hide()
+    end,
+  },
+
   cancel = {
     desc = 'Cancel running request',
     fn = M.cancel,

lua/opencode/config.lua

@@ -119,6 +119,7 @@ M.defaults = {
     },
   },
   ui = {
+    enable_treesitter_markdown = true,
     position = 'right',
     input_position = 'bottom',
     window_width = 0.40,
@@ -128,6 +129,7 @@ M.defaults = {
     display_context_size = true,
     display_cost = true,
     window_highlight = 'Normal:OpencodeBackground,FloatBorder:OpencodeBorder',
+    persist_state = true,
     icons = {
       preset = 'nerdfonts',
       overrides = {},