feat(ui): persist_state window/buffer persistence

When ui.persist_state = true (default), toggle hides windows without
deleting buffers and restores them on next toggle, preserving input
draft content, scroll/cursor position, focused pane, and input_hidden
state.

Three-state window model:
closed → visible → hidden → visible
  ↑___________↓____________↑
   (teardown)   (restore)

Decision engine resolves (status, persist_state, has_display_route, in_tab) → action:

| # | status  | in_tab | persist_state | has_display_route | action         |
|---|---------|--------|---------------|-------------------|----------------|
| 1 | hidden  | any    | true          | any               | restore_hidden |
| 2 | hidden  | any    | false         | any               | close_hidden   |
| 3 | visible | false  | any           | any               | migrate        |
| 4 | visible | true   | any           | true              | close          |
| 5 | visible | true   | false         | any               | close          |
| 6 | visible | true   | true          | false             | hide           |
| 7 | closed  | any    | any           | any               | open           |

Note: Multiple opencode instances across tabs are not currently supported.

Author: jensenojs

README.md

@@ -209,6 +209,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
@@ -441,6 +442,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

lua/opencode/api.lua

@@ -48,40 +48,135 @@ 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
+---@param win_id integer|nil
+---@return integer[]|nil
+local function get_window_cursor(win_id)
+  if not win_id or not vim.api.nvim_win_is_valid(win_id) then
+    return nil
+  end
+
+  local ok, pos = pcall(vim.api.nvim_win_get_cursor, win_id)
+  if not ok then
+    return nil
+  end
+
+  return pos
+end
+
+---@return {status: 'closed'|'hidden'|'visible', visible: boolean, hidden: boolean, position: string, windows: OpencodeWindowState|nil, cursor_positions: {input: integer[]|nil, output: integer[]|nil}}
+function M.get_window_state()
+  local status = state.get_window_status()
+  local current_windows = nil
+
+  if status == 'visible' and state.are_windows_in_current_tab() then
+    current_windows = state.windows
+  elseif status == 'visible' then
+    status = 'closed'
+  end
+
+  local input_cursor = get_window_cursor(current_windows and current_windows.input_win)
+    or state.get_cursor_position('input')
+  local output_cursor = get_window_cursor(current_windows and current_windows.output_win)
+    or state.get_cursor_position('output')
+
+  return {
+    status = status,
+    visible = status == 'visible',
+    hidden = status == 'hidden',
+    position = config.ui.position,
+    windows = current_windows and vim.deepcopy(current_windows) or nil,
+    cursor_positions = {
+      input = input_cursor,
+      output = output_cursor,
+    },
+  }
+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 EARLY_RETURN_ACTIONS = {
+    close = M.close,
+    hide = M.hide,
+    close_hidden = ui.drop_hidden_snapshot,
+  }
+
+  local function open_windows(restore_hidden)
+    local ctx = build_toggle_open_context(restore_hidden == true)
+    return core.open({
+      new_session = new_session == true,
+      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 early_return = EARLY_RETURN_ACTIONS[action]
+  if early_return then
+    return early_return()
+  end
+
+  if action == 'migrate' then
+    -- NOTE: We currently don't support preserving Opencode UI state across tabs.
+    -- If Opencode is visible in a different tab, we tear it down there and recreate it here.
     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_windows(false)
   end
+
+  return open_windows(action == 'restore_hidden')
 end)
 
 ---@param new_session boolean?
@@ -271,7 +366,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 +377,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 +612,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
 
@@ -1052,6 +1147,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

@@ -116,6 +116,7 @@ M.defaults = {
     display_context_size = true,
     display_cost = true,
     window_highlight = 'Normal:OpencodeBackground,FloatBorder:OpencodeBorder',
+    persist_state = true,
     icons = {
       preset = 'nerdfonts',
       overrides = {},