feat(ui): add multi-question navigation and tabbed question UI

Add group navigation to Dialog (navigate_group, set/get_group_selection, on_navigate_group)
and left/right keymaps. Update legend formatting to show key hints. Update highlight
definitions for question tabs and key hints.

Update question_window to track answers by question index, render tabbed question headers
(showing active/done/pending state), wait until all questions are answered before sending
the reply, and synchronize dialog group selection with the current question. Add unit tests
covering multi-question flow, tab rendering, and navigation.

Author: sudo-tee

lua/opencode/ui/dialog.lua

@@ -3,7 +3,9 @@
 ---@field on_select function(index: integer) Called when an option is selected
 ---@field on_dismiss? function() Called when dialog is dismissed
 ---@field on_navigate? function() Called when selection changes
+---@field on_navigate_group? function(index: integer) Called when group selection changes
 ---@field get_option_count function(): integer Returns the total number of options
+---@field get_group_count? function(): integer Returns the total number of groups
 ---@field check_focused? function(): boolean Returns whether dialog should be active
 ---@field keymaps? DialogKeymaps Custom keymap configuration
 ---@field namespace_prefix? string Prefix for vim.on_key namespace (default: 'opencode_dialog')
@@ -12,6 +14,8 @@
 ---@class DialogKeymaps
 ---@field up? string[] Keys for navigating up (default: {'k', '<Up>'})
 ---@field down? string[] Keys for navigating down (default: {'j', '<Down>'})
+---@field left? string[] Keys for navigating left between groups
+---@field right? string[] Keys for navigating right between groups
 ---@field select? string Key for selecting current option (default: '<CR>')
 ---@field dismiss? string Key for dismissing dialog (default: '<Esc>')
 ---@field number_shortcuts? boolean Enable 1-9 number shortcuts (default: true)
@@ -22,6 +26,7 @@
 ---@field private _key_capture_ns integer? Namespace for vim.on_key
 ---@field private _selected_index integer Currently selected option index
 ---@field private _active boolean Whether dialog is currently active
+---@field private _group_index integer Currently selected group index
 local Dialog = {}
 Dialog.__index = Dialog
 
@@ -35,6 +40,8 @@ function Dialog.new(config)
   local default_keymaps = {
     up = { 'k', '<Up>' },
     down = { 'j', '<Down>' },
+    left = {},
+    right = {},
     select = '<CR>',
     dismiss = '<Esc>',
     number_shortcuts = true,
@@ -52,6 +59,7 @@ function Dialog.new(config)
   self._keymaps = {}
   self._key_capture_ns = nil
   self._selected_index = 1
+  self._group_index = 1
   self._active = false
 
   return self
@@ -72,6 +80,24 @@ function Dialog:set_selection(index)
   end
 end
 
+---@return integer
+function Dialog:get_group_selection()
+  return self._group_index
+end
+
+---@param index integer
+function Dialog:set_group_selection(index)
+  local group_count = self._config.get_group_count and self._config.get_group_count() or 0
+  if group_count == 0 then
+    self._group_index = 1
+    return
+  end
+
+  if index >= 1 and index <= group_count then
+    self._group_index = index
+  end
+end
+
 ---Navigate selection by delta (positive for down, negative for up)
 ---@param delta integer Amount to move selection
 function Dialog:navigate(delta)
@@ -98,6 +124,28 @@ function Dialog:navigate(delta)
   end
 end
 
+---@param delta integer
+function Dialog:navigate_group(delta)
+  if not self._active or not self._config.check_focused() or not self._config.on_navigate_group then
+    return
+  end
+
+  local group_count = self._config.get_group_count and self._config.get_group_count() or 0
+  if group_count <= 1 then
+    return
+  end
+
+  self._group_index = self._group_index + delta
+
+  if self._group_index < 1 then
+    self._group_index = group_count
+  elseif self._group_index > group_count then
+    self._group_index = 1
+  end
+
+  self._config.on_navigate_group(self._group_index)
+end
+
 ---Select the current option
 function Dialog:select()
   if not self._active or not self._config.check_focused() then
@@ -178,31 +226,42 @@ function Dialog:format_legend(output, options)
   end
 
   if ui.is_opencode_focused() then
-    local legend_parts = {}
     local keymaps = self._config.keymaps
     if not keymaps then
       return
     end
 
     if keymaps.up and #keymaps.up > 0 and keymaps.down and #keymaps.down > 0 then
-      table.insert(legend_parts, string.format('Navigate: `%s`/`%s` or `↑`/`↓`', keymaps.down[1], keymaps.up[1]))
+      local line = output:add_line(string.format('Move: j/k or %s/%s', '↑', '↓'))
+      output:add_extmark(line - 1, { start_col = 6, end_col = 9, hl_group = 'OpencodeQuestionKeyHint' } --[[@as OutputExtmark]])
+      output:add_extmark(line - 1, { start_col = 13, end_col = 16, hl_group = 'OpencodeQuestionKeyHint' } --[[@as OutputExtmark]])
+    end
+
+    if keymaps.left and #keymaps.left > 0 and keymaps.right and #keymaps.right > 0 then
+      local line = output:add_line('Question: h/l or <-/->')
+      output:add_extmark(line - 1, { start_col = 10, end_col = 13, hl_group = 'OpencodeQuestionKeyHint' } --[[@as OutputExtmark]])
+      output:add_extmark(line - 1, { start_col = 17, end_col = 23, hl_group = 'OpencodeQuestionKeyHint' } --[[@as OutputExtmark]])
     end
 
     if keymaps.select and keymaps.select ~= '' then
-      local select_text = string.format('Select: `%s`', keymaps.select)
+      local select_text = 'Select: <CR>'
+      if keymaps.number_shortcuts and option_count > 0 then
+        local max_shortcut = math.min(option_count, 9)
+        select_text = select_text .. string.format(' or 1-%d', max_shortcut)
+      end
+      local line = output:add_line(select_text)
+      output:add_extmark(line - 1, { start_col = 8, end_col = 12, hl_group = 'OpencodeQuestionKeyHint' } --[[@as OutputExtmark]])
       if keymaps.number_shortcuts and option_count > 0 then
         local max_shortcut = math.min(option_count, 9)
-        select_text = select_text .. string.format(' or `1-%d`', max_shortcut)
+        local suffix = string.format('1-%d', max_shortcut)
+        local start_col = #select_text - #suffix
+        output:add_extmark(line - 1, { start_col = start_col, end_col = #select_text, hl_group = 'OpencodeQuestionKeyHint' } --[[@as OutputExtmark]])
       end
-      table.insert(legend_parts, select_text)
     end
 
     if keymaps.dismiss and keymaps.dismiss ~= '' then
-      table.insert(legend_parts, string.format('Dismiss: `%s`', keymaps.dismiss))
-    end
-
-    if #legend_parts > 0 then
-      output:add_line(table.concat(legend_parts, '  '))
+      local line = output:add_line('Close: <Esc>')
+      output:add_extmark(line - 1, { start_col = 7, end_col = 12, hl_group = 'OpencodeQuestionKeyHint' } --[[@as OutputExtmark]])
     end
   else
     local message = options.unfocused_message or 'Focus Opencode window to interact'
@@ -353,6 +412,42 @@ function Dialog:_setup_keymaps()
     end
   end
 
+  if keymaps.left then
+    for _, key in ipairs(keymaps.left) do
+      if key and key ~= '' then
+        vim.keymap.set(
+          'n',
+          key,
+          function()
+            self:navigate_group(-1)
+          end,
+          vim.tbl_extend('force', keymap_opts, {
+            desc = 'Dialog: navigate left',
+          })
+        )
+        table.insert(self._keymaps, key)
+      end
+    end
+  end
+
+  if keymaps.right then
+    for _, key in ipairs(keymaps.right) do
+      if key and key ~= '' then
+        vim.keymap.set(
+          'n',
+          key,
+          function()
+            self:navigate_group(1)
+          end,
+          vim.tbl_extend('force', keymap_opts, {
+            desc = 'Dialog: navigate right',
+          })
+        )
+        table.insert(self._keymaps, key)
+      end
+    end
+  end
+
   if keymaps.select and keymaps.select ~= '' then
     vim.keymap.set(
       'n',

lua/opencode/ui/highlight.lua

@@ -48,6 +48,10 @@ function M.setup()
     vim.api.nvim_set_hl(0, 'OpencodeQuestionOption', { link = 'Normal', default = true })
     vim.api.nvim_set_hl(0, 'OpencodeQuestionBorder', { fg = '#E3F2FD', default = true })
     vim.api.nvim_set_hl(0, 'OpencodeQuestionTitle', { link = '@label', bold = true, default = true })
+    vim.api.nvim_set_hl(0, 'OpencodeQuestionTabActive', { bg = '#E3F2FD', fg = '#1976D2', bold = true, default = true })
+    vim.api.nvim_set_hl(0, 'OpencodeQuestionTabDone', { fg = '#2E7D32', bold = true, default = true })
+    vim.api.nvim_set_hl(0, 'OpencodeQuestionTabPending', { fg = '#757575', default = true })
+    vim.api.nvim_set_hl(0, 'OpencodeQuestionKeyHint', { fg = '#1976D2', bold = true, default = true })
     vim.api.nvim_set_hl(0, 'OpencodeChangedLines', { bg = '#FFF3BF', default = true })
   else
     vim.api.nvim_set_hl(0, 'OpencodeBorder', { fg = '#616161', default = true })
@@ -92,6 +96,10 @@ function M.setup()
     vim.api.nvim_set_hl(0, 'OpencodeQuestionOption', { link = 'Normal', default = true })
     vim.api.nvim_set_hl(0, 'OpencodeQuestionBorder', { fg = '#2B3A5A', default = true })
     vim.api.nvim_set_hl(0, 'OpencodeQuestionTitle', { link = '@label', bold = true, default = true })
+    vim.api.nvim_set_hl(0, 'OpencodeQuestionTabActive', { bg = '#2B3A5A', fg = '#61AFEF', bold = true, default = true })
+    vim.api.nvim_set_hl(0, 'OpencodeQuestionTabDone', { fg = '#98C379', bold = true, default = true })
+    vim.api.nvim_set_hl(0, 'OpencodeQuestionTabPending', { fg = '#7F8490', default = true })
+    vim.api.nvim_set_hl(0, 'OpencodeQuestionKeyHint', { fg = '#61AFEF', bold = true, default = true })
     vim.api.nvim_set_hl(0, 'OpencodeChangedLines', { bg = '#3D3520', default = true })
   end
 end

lua/opencode/ui/question_window.lua

@@ -13,6 +13,48 @@ M._collected_answers = {}
 M._answering = false
 M._dialog = nil
 
+---@param index integer
+---@return string[]|nil
+local function get_answer_for_index(index)
+  local answer = M._collected_answers[index]
+  if type(answer) ~= 'table' or #answer == 0 then
+    return nil
+  end
+  return answer
+end
+
+---@return boolean
+local function has_all_answers()
+  local request = M._current_question
+  local questions = request and request.questions or {}
+  if #questions == 0 then
+    return false
+  end
+
+  for i = 1, #questions do
+    if not get_answer_for_index(i) then
+      return false
+    end
+  end
+
+  return true
+end
+
+---@return integer|nil
+local function get_next_unanswered_question_index()
+  local request = M._current_question
+  local questions = request and request.questions or {}
+  if #questions == 0 then
+    return nil
+  end
+
+  for i = 1, #questions do
+    if not get_answer_for_index(i) then
+      return i
+    end
+  end
+end
+
 ---@param question_request OpencodeQuestionRequest|nil
 ---@return boolean
 function M.matches_active_question(question_request)
@@ -159,8 +201,8 @@ function M.show_question(question_request)
   end
 
   M._current_question = question_request
-  M._current_question_index = 1
   M._collected_answers = {}
+  M._current_question_index = 1
 
   if config.ui.questions and config.ui.questions.use_vim_ui_select then
     M._show_question_with_vim_ui_select()
@@ -245,13 +287,13 @@ local function answer_current_question(answer_value)
     return
   end
 
-  table.insert(M._collected_answers, type(answer_value) == 'table' and answer_value or { answer_value })
-  M._current_question_index = M._current_question_index + 1
+  M._collected_answers[M._current_question_index] = type(answer_value) == 'table' and answer_value or { answer_value }
 
-  if M._current_question_index > #request.questions then
+  if has_all_answers() then
     M._send_reply(request.id, M._collected_answers)
     M.clear_question()
   else
+    M._current_question_index = get_next_unanswered_question_index() or M._current_question_index
     M._answering = false
     M._clear_dialog()
     M._setup_dialog()
@@ -329,6 +371,49 @@ local function add_other_if_missing(options)
   return result
 end
 
+---@param output Output
+local function format_question_tabs(output)
+  local request = M._current_question
+  if not request or #request.questions <= 1 then
+    return
+  end
+
+  local line = ''
+  local segments = {}
+
+  for i, question in ipairs(request.questions) do
+    local label = question.header ~= '' and question.header or ('Q' .. i)
+    local is_active = i == M._current_question_index
+    local is_done = get_answer_for_index(i) ~= nil
+    local marker = is_done and 'x' or ' '
+    local segment = string.format(' %d [%s] %s ', i, marker, label)
+
+    if #line > 0 then
+      line = line .. ' '
+    end
+
+    local start_col = #line
+    line = line .. segment
+    table.insert(segments, {
+      start_col = start_col,
+      end_col = #line,
+      hl_group = is_active and 'OpencodeQuestionTabActive'
+        or (is_done and 'OpencodeQuestionTabDone' or 'OpencodeQuestionTabPending'),
+    })
+  end
+
+  local line_idx = output:add_line(line)
+  for _, segment in ipairs(segments) do
+    output:add_extmark(line_idx - 1, {
+      start_col = segment.start_col,
+      end_col = segment.end_col,
+      hl_group = segment.hl_group,
+    } --[[@as OutputExtmark]])
+  end
+
+  output:add_line('')
+end
+
 ---@param output Output
 function M.format_display(output)
   if not M.has_question() or M._answering then
@@ -347,6 +432,8 @@ function M.format_display(output)
     progress = string.format(' (%d/%d)', M._current_question_index, #M._current_question.questions)
   end
 
+  format_question_tabs(output)
+
   -- Prepare options
   local options_to_display = add_other_if_missing(question_info.options)
   local options = {}
@@ -417,6 +504,12 @@ function M._setup_dialog()
     render_question()
   end
 
+  ---@param index integer
+  local function on_navigate_group(index)
+    M._current_question_index = index
+    render_question()
+  end
+
   ---@return integer
   local function get_option_count()
     local question_info = M.get_current_question_info()
@@ -428,11 +521,20 @@ function M._setup_dialog()
     on_select = on_select,
     on_dismiss = on_dismiss,
     on_navigate = on_navigate,
+    on_navigate_group = on_navigate_group,
     get_option_count = get_option_count,
+    get_group_count = function()
+      return M._current_question and #M._current_question.questions or 0
+    end,
     check_focused = check_focused,
     namespace_prefix = 'opencode_question',
+    keymaps = {
+      left = { 'h', '<Left>' },
+      right = { 'l', '<Right>' },
+    },
   })
 
+  M._dialog:set_group_selection(M._current_question_index)
   M._dialog:setup()
 end