refactor(ui): add type annotations and clarifying comments

Add Lua annotations (@param, @return) and short descriptive comments across many
UI and renderer modules (base_picker, formatter, grep tool, highlight,
output_window, question_window, renderer/buffer, renderer/ctx, renderer/events,
renderer/flush, ui). These changes improve readability and editor tooling
support. No behavioral changes.

Author: sudo-tee

lua/opencode/ui/base_picker.lua

@@ -84,6 +84,8 @@ local function telescope_ui(opts)
   local entry_display = require('telescope.pickers.entry_display')
 
   -- Create displayer dynamically based on number of parts
+  ---@param picker_item PickerItem
+  ---@return table
   local function create_displayer(picker_item)
     local items = {}
     for _ in ipairs(picker_item.parts) do
@@ -128,6 +130,7 @@ local function telescope_ui(opts)
     return entry
   end
 
+  ---@return unknown
   local function refresh_picker()
     return current_picker
       and current_picker:refresh(
@@ -222,6 +225,7 @@ end
 local function fzf_ui(opts)
   local fzf_lua = require('fzf-lua')
 
+  ---@return table
   local function create_fzf_config()
     local has_multi_action = util.some(opts.actions, function(action)
       return action.multi_selection
@@ -251,6 +255,7 @@ local function fzf_ui(opts)
     }
   end
 
+  ---@return fun(fzf_cb: fun(line?: string))
   local function create_finder()
     return function(fzf_cb)
       for idx, item in ipairs(opts.items) do
@@ -289,6 +294,7 @@ local function fzf_ui(opts)
     end
   end
 
+  ---Reopen fzf-lua to reflect updated picker items.
   local function refresh_fzf()
     vim.schedule(function()
       fzf_ui(opts)
@@ -584,6 +590,7 @@ function M.create_picker_item(parts)
     parts = parts,
   }
 
+  ---@return string
   function item:to_string()
     local texts = {}
     for _, part in ipairs(self.parts) do
@@ -592,6 +599,7 @@ function M.create_picker_item(parts)
     return table.concat(texts, ' ')
   end
 
+  ---@return table
   function item:to_formatted_text()
     local formatted = {}
     for _, part in ipairs(self.parts) do

lua/opencode/ui/formatter.lua

@@ -99,6 +99,12 @@ function M._format_revert_message(session_data, start_idx)
   return output
 end
 
+---@param output Output
+---@param text string
+---@param action_type string
+---@param args any[]
+---@param key? string
+---@param line? integer
 local function add_action(output, text, action_type, args, key, line)
   -- actions use api-indexing (e.g. 0 indexed)
   line = (line or output:get_line_count()) - 1
@@ -384,6 +390,8 @@ function M._format_diagnostics_context(output, part)
   M.add_vertical_border(output, start_line, end_line, 'OpencodeMessageRoleUser', -3)
 end
 
+---@param part OpencodeMessagePart|nil
+---@return string|nil
 local function get_visible_user_part_kind(part)
   if not part then
     return nil
@@ -417,6 +425,10 @@ local function get_visible_user_part_kind(part)
   return nil
 end
 
+---@param message OpencodeMessage|nil
+---@param part OpencodeMessagePart|nil
+---@return string|nil previous_kind
+---@return string|nil next_kind
 local function get_user_part_neighbors(message, part)
   if not message or not message.parts or not part or not part.id then
     return nil, nil

lua/opencode/ui/formatter/tools/grep.lua

@@ -1,25 +1,27 @@
 local icons = require('opencode.ui.icons')
 local M = {}
 
----@param input GrepToolInput|nil
+---@param value any
 ---@return string
-local function resolve_grep_string(input)
-  local function normalize_part(value)
-    if value == nil or value == vim.NIL then
-      return ''
-    end
-
-    local value_type = type(value)
-    if value_type == 'string' then
-      return value
-    end
-    if value_type == 'number' or value_type == 'boolean' then
-      return tostring(value)
-    end
-
+local function normalize_part(value)
+  if value == nil or value == vim.NIL then
     return ''
   end
 
+  local value_type = type(value)
+  if value_type == 'string' then
+    return value
+  end
+  if value_type == 'number' or value_type == 'boolean' then
+    return tostring(value)
+  end
+
+  return ''
+end
+
+---@param input GrepToolInput|nil
+---@return string
+local function resolve_grep_string(input)
   if not input then
     return ''
   end

lua/opencode/ui/highlight.lua

@@ -1,5 +1,6 @@
 local M = {}
 
+---Define the plugin highlight groups for the current background.
 function M.setup()
   local is_light = vim.o.background == 'light'
 

lua/opencode/ui/output_window.lua

@@ -40,6 +40,7 @@ function M.end_update()
   end
 end
 
+---@return integer
 function M.create_buf()
   local output_buf = vim.api.nvim_create_buf(false, true)
   local filetype = config.ui.output.filetype or 'opencode_output'
@@ -53,6 +54,7 @@ function M.create_buf()
   return output_buf
 end
 
+---@return vim.api.keyset.win_config
 function M._build_output_win_config()
   return {
     relative = 'editor',
@@ -180,6 +182,7 @@ function M.sync_cursor_with_viewport(win)
   M._was_at_bottom_by_win[win] = visible_bottom >= line_count
 end
 
+---@param windows OpencodeWindowState
 function M.setup(windows)
   window_options.set_window_option(
     'winhighlight',
@@ -215,6 +218,7 @@ function M.setup(windows)
   M.setup_keymaps(windows)
 end
 
+---@param windows OpencodeWindowState?
 function M.update_dimensions(windows)
   if config.ui.position == 'current' then
     return
@@ -250,6 +254,7 @@ function M.update_dimensions(windows)
   pcall(vim.api.nvim_win_set_config, windows.output_win, { width = width })
 end
 
+---@return integer
 function M.get_buf_line_count()
   local windows = state.windows
   if not windows or not windows.output_buf or not vim.api.nvim_buf_is_valid(windows.output_buf) then
@@ -399,6 +404,7 @@ function M.highlight_changed_lines(start_line, end_line)
   end, config.debug.highlight_changed_lines_timeout_ms or 120)
 end
 
+---@param should_stop_insert? boolean
 function M.focus_output(should_stop_insert)
   if not M.mounted() then
     return
@@ -411,6 +417,7 @@ function M.focus_output(should_stop_insert)
   vim.api.nvim_set_current_win(state.windows.output_win)
 end
 
+---Close and delete the output window and buffer.
 function M.close()
   if not M.mounted() then
     return
@@ -422,11 +429,14 @@ function M.close()
   pcall(vim.api.nvim_buf_delete, state.windows.output_buf, { force = true })
 end
 
+---@param windows OpencodeWindowState
 function M.setup_keymaps(windows)
   local keymap = require('opencode.keymap')
   keymap.setup_window_keymaps(config.keymap.output_window, windows.output_buf)
 end
 
+---@param windows OpencodeWindowState
+---@param group integer
 function M.setup_autocmds(windows, group)
   vim.api.nvim_create_autocmd('WinEnter', {
     group = group,
@@ -472,6 +482,7 @@ function M.setup_autocmds(windows, group)
   })
 end
 
+---Clear the output buffer and all namespaces.
 function M.clear()
   M.set_lines({})
   -- clear extmarks in all namespaces as I've seen RenderMarkdown leave some

lua/opencode/ui/question_window.lua

@@ -51,10 +51,12 @@ function M.belongs_to_active_session(question_request)
   return false
 end
 
+---Request the renderer to show the current question display.
 local function render_question()
   require('opencode.ui.renderer.events').render_question_display()
 end
 
+---Request the renderer to remove the current question display.
 local function clear_question()
   require('opencode.ui.renderer.events').clear_question_display()
 end
@@ -111,6 +113,7 @@ function M.restore_pending_question(session_id)
     end)
 end
 
+---Reset the current question state and remove any dialog UI.
 function M.clear_question()
   M._clear_dialog()
   M._current_question = nil
@@ -161,6 +164,8 @@ local function answer_current_question(answer_value)
   end)
 end
 
+---@param options OpencodeQuestionOption[]
+---@return integer|nil
 local function find_other_option(options)
   for i, opt in ipairs(options) do
     if vim.startswith(opt.label:lower(), 'other') then
@@ -170,6 +175,8 @@ local function find_other_option(options)
   return nil
 end
 
+---@param question_info OpencodeQuestionInfo
+---@return integer
 local function get_total_options(question_info)
   local has_other = find_other_option(question_info.options) ~= nil
   return has_other and #question_info.options or (#question_info.options + 1)
@@ -198,6 +205,7 @@ function M._answer_with_option(option_index)
   answer_current_question(question_info.options[option_index].label)
 end
 
+---Prompt for a free-form answer to the active question.
 function M._answer_with_custom()
   vim.ui.input({ prompt = 'Enter your response: ' }, function(input)
     if input and input ~= '' then
@@ -210,6 +218,8 @@ function M._answer_with_custom()
   end)
 end
 
+---@param options OpencodeQuestionOption[]
+---@return OpencodeQuestionOption[]
 local function add_other_if_missing(options)
   if find_other_option(options) ~= nil then
     return options
@@ -258,6 +268,7 @@ function M.format_display(output)
   })
 end
 
+---Create the in-buffer dialog used to answer the active question.
 function M._setup_dialog()
   if not M.has_question() then
     return
@@ -272,11 +283,13 @@ function M._setup_dialog()
 
   local buf = state.windows.output_buf
 
+  ---@return boolean
   local function check_focused()
     local ui = require('opencode.ui.ui')
     return ui.is_opencode_focused() and M.has_question()
   end
 
+  ---@param index integer
   local function on_select(index)
     if not check_focused() then
       return
@@ -289,6 +302,7 @@ function M._setup_dialog()
     end, 100)
   end
 
+  ---Reject the current question if the dialog is dismissed.
   local function on_dismiss()
     if not check_focused() then
       return
@@ -298,10 +312,12 @@ function M._setup_dialog()
     render_question()
   end
 
+  ---Refresh the rendered question state after navigation changes.
   local function on_navigate()
     render_question()
   end
 
+  ---@return integer
   local function get_option_count()
     local question_info = M.get_current_question_info()
     return question_info and get_total_options(question_info) or 0
@@ -320,6 +336,7 @@ function M._setup_dialog()
   M._dialog:setup()
 end
 
+---Tear down the active question dialog, if any.
 function M._clear_dialog()
   if M._dialog then
     M._dialog:teardown()