fix(session-picker): support previews across picker backends

- Unify custom preview rendering behind a backend-neutral preview target so
  session previews work consistently with Telescope, fzf-lua, and Snacks.

- Normalize picker plugin aliases such as fzf-lua, telescope.nvim, and
  snacks.nvim to their internal backend names, and add regression coverage for
  custom preview behavior across the picker integrations.

Author: jensenojs

README.md

@@ -116,7 +116,7 @@ Install the plugin with your favorite package manager. See the [Configuration](#
 ```lua
 -- Default configuration with all available options
 require('opencode').setup({
-  preferred_picker = nil, -- 'telescope', 'fzf', 'mini.pick', 'snacks', 'select', if nil, it will use the best available picker. Note mini.pick does not support multiple selections
+  preferred_picker = nil, -- 'telescope'/'telescope.nvim', 'fzf'/'fzf-lua', 'mini.pick', 'snacks'/'snacks.nvim', 'select', if nil, it will use the best available picker. Note mini.pick does not support multiple selections
   preferred_completion = nil, -- 'blink', 'nvim-cmp','vim_complete' if nil, it will use the best available completion
   default_global_keymaps = true, -- If false, disables all default global keymaps
   default_mode = 'build', -- 'build' or 'plan' or any custom configured. @see [OpenCode Agents](https://opencode.ai/docs/modes/)

lua/opencode/types.lua

@@ -354,7 +354,7 @@
 ---@field fn? fun(args:string[]|nil):nil|Promise<any>|any
 
 ---@class OpencodeConfig
----@field preferred_picker 'telescope' | 'fzf' | 'mini.pick' | 'snacks' | 'select' | nil
+---@field preferred_picker 'telescope' | 'telescope.nvim' | 'fzf' | 'fzf-lua' | 'mini.pick' | 'snacks' | 'snacks.nvim' | 'select' | nil
 ---@field default_global_keymaps boolean
 ---@field default_mode 'build' | 'plan' | string -- Default mode
 ---@field default_system_prompt string | nil

lua/opencode/ui/base_picker.lua

@@ -18,10 +18,16 @@ local Promise = require('opencode.promise')
 ---@field width? number Optional width for the picker (defaults to config or current window width)
 ---@field multi_selection? table<string, boolean> Actions that support multi-selection
 ---@field preview? "file"|"custom"|"none"|false Preview mode: "file" for file preview, "custom" for custom preview via preview_fn, "none" or false to disable
----@field preview_fn? fun(item: any, bufnr: integer): nil Custom preview function, called when preview = 'custom' and a selection changes
+---@field preview_fn? fun(item: any, target: PickerPreviewTarget): nil Custom preview function, called when preview = 'custom' and a selection changes
 ---@field layout_opts? OpencodeUIPickerConfig
 ---@field close? fun() Close the picker programmatically (set by the backend)
 
+---@class PickerPreviewTarget
+---@field get_bufnr fun(self: PickerPreviewTarget): integer?
+---@field is_valid fun(self: PickerPreviewTarget): boolean
+---@field set_lines fun(self: PickerPreviewTarget, lines: string[]): nil
+---@field with_window fun(self: PickerPreviewTarget, fn: fun(): nil): nil
+
 ---@class TelescopeEntry
 ---@field value any
 ---@field display fun(entry: TelescopeEntry): string[]
@@ -58,6 +64,64 @@ local Promise = require('opencode.promise')
 local M = {}
 local picker = require('opencode.ui.picker')
 
+---@param bufnr integer?
+---@return PickerPreviewTarget
+local function create_buffer_preview_target(bufnr)
+  return {
+    get_bufnr = function()
+      return bufnr
+    end,
+    is_valid = function()
+      return bufnr ~= nil and vim.api.nvim_buf_is_valid(bufnr)
+    end,
+    set_lines = function(_, lines)
+      if bufnr == nil or not vim.api.nvim_buf_is_valid(bufnr) then
+        return
+      end
+      local modifiable = vim.bo[bufnr].modifiable
+      vim.bo[bufnr].modifiable = true
+      vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, lines)
+      vim.bo[bufnr].modifiable = modifiable
+    end,
+    with_window = function(_, fn)
+      if bufnr == nil or not vim.api.nvim_buf_is_valid(bufnr) then
+        return
+      end
+      local win = vim.fn.bufwinid(bufnr)
+      if win ~= -1 then
+        vim.api.nvim_win_call(win, fn)
+      end
+    end,
+  }
+end
+
+---@param ctx snacks.picker.preview.ctx
+---@return PickerPreviewTarget
+local function create_snacks_preview_target(ctx)
+  return {
+    get_bufnr = function()
+      return ctx.buf
+    end,
+    is_valid = function()
+      return ctx.buf ~= nil and vim.api.nvim_buf_is_valid(ctx.buf)
+    end,
+    set_lines = function(_, lines)
+      if ctx.preview and ctx.preview.set_lines then
+        ctx.preview:set_lines(lines)
+      elseif ctx.buf and vim.api.nvim_buf_is_valid(ctx.buf) then
+        create_buffer_preview_target(ctx.buf):set_lines(lines)
+      end
+    end,
+    with_window = function(_, fn)
+      if ctx.win and vim.api.nvim_win_is_valid(ctx.win) then
+        vim.api.nvim_win_call(ctx.win, fn)
+        return
+      end
+      create_buffer_preview_target(ctx.buf):with_window(fn)
+    end,
+  }
+end
+
 ---Build title with action legend
 ---@param base_title string The base title
 ---@param actions table<string, PickerAction> The available actions
@@ -156,7 +220,7 @@ local function telescope_ui(opts)
             if not entry then
               return
             end
-            opts.preview_fn(entry.value, self.state.bufnr)
+            opts.preview_fn(entry.value, create_buffer_preview_target(self.state.bufnr))
           end,
         })
       else
@@ -268,8 +332,35 @@ local function fzf_ui(opts)
         ['--delimiter'] = '\x01', -- use SOH as delimiter (invisible char)
       },
       _headers = { 'actions' },
-      -- Enable builtin previewer for file preview support
-      previewer = opts.preview == 'file' and 'builtin' or nil,
+      previewer = (function()
+        if opts.preview == 'file' then
+          return 'builtin'
+        elseif opts.preview == 'custom' and opts.preview_fn then
+          return {
+            _ctor = function()
+              local previewer = require('fzf-lua.previewer.builtin').buffer_or_file:extend()
+              function previewer:populate_preview_buf(entry_str)
+                if not self.win or not self.win:validate_preview() then
+                  return
+                end
+                local idx_str = entry_str:match('^(%d+)\x01')
+                local idx = tonumber(idx_str)
+                if not idx or not opts.items[idx] then
+                  return
+                end
+                -- Create scratch buffer, attach to preview window first
+                -- so preview_fn can use bufwinid for window-local ops (folds)
+                local buf = self:get_tmp_buffer()
+                self:set_preview_buf(buf, true) -- min_winopts=true
+                opts.preview_fn(opts.items[idx], create_buffer_preview_target(buf))
+              end
+              return previewer
+            end,
+          }
+        else
+          return nil
+        end
+      end)(),
       fn_fzf_index = function(line)
         -- Extract the numeric index prefix before the SOH delimiter
         local idx_str = line:match('^(%d+)\x01')
@@ -506,30 +597,36 @@ end
 local function snacks_picker_ui(opts)
   local Snacks = require('snacks')
 
-  local has_preview = opts.preview == 'file'
+  local has_custom_preview = opts.preview == 'custom' and opts.preview_fn ~= nil
+  local has_preview = opts.preview == 'file' or has_custom_preview
 
   local title = type(opts.title) == 'function' and opts.title() or opts.title
   ---@cast title string
 
   local layout_opts = opts.layout_opts and opts.layout_opts.snacks_layout or nil
 
   local selection_made = false
+  local default_layout = {
+    preset = has_custom_preview and 'default' or 'select',
+    config = function(layout)
+      local width = opts.width and (opts.width + 3) or nil -- extra space for snacks UI
+      if not has_preview then
+        layout.layout.width = width
+        layout.layout.max_width = width
+        layout.layout.min_width = width
+      end
+    end,
+  }
+  if opts.preview == 'file' then
+    default_layout.preview = 'main'
+  elseif not has_preview then
+    default_layout.preview = false
+  end
 
   ---@type snacks.picker.Config
   local snack_opts = {
     title = title,
-    layout = layout_opts or {
-      preview = has_preview and 'main' or false,
-      preset = 'select',
-      config = function(layout)
-        local width = opts.width and (opts.width + 3) or nil -- extra space for snacks UI
-        if not has_preview then
-          layout.layout.width = width
-          layout.layout.max_width = width
-          layout.layout.min_width = width
-        end
-      end,
-    },
+    layout = layout_opts or default_layout,
     finder = function()
       return opts.items
     end,
@@ -576,9 +673,15 @@ local function snacks_picker_ui(opts)
     },
   }
 
-  -- Add file preview if enabled
-  if has_preview then
+  if opts.preview == 'file' then
     snack_opts.preview = 'file'
+  elseif has_custom_preview then
+    snack_opts.preview = function(ctx)
+      if ctx.item then
+        ctx.preview:reset()
+        opts.preview_fn(ctx.item, create_snacks_preview_target(ctx))
+      end
+    end
   else
     snack_opts.preview = function()
       return false

lua/opencode/ui/picker.lua

@@ -1,15 +1,25 @@
 local M = {}
 
+local picker_aliases = {
+  ['fzf-lua'] = 'fzf',
+  ['snacks.nvim'] = 'snacks',
+  ['telescope.nvim'] = 'telescope',
+}
+
+local function normalize_picker_name(name)
+  if name == 'select' then
+    return nil
+  end
+
+  return picker_aliases[name] or name
+end
+
 function M.get_best_picker()
   local config = require('opencode.config')
 
   local preferred_picker = config.preferred_picker
   if preferred_picker and type(preferred_picker) == 'string' and preferred_picker ~= '' then
-    if preferred_picker == 'select' then
-      return nil
-    end
-
-    return preferred_picker
+    return normalize_picker_name(preferred_picker)
   end
 
   if pcall(require, 'telescope') then

lua/opencode/ui/session_picker.lua

@@ -172,36 +172,40 @@ local function format_messages(messages, omitted_count)
 end
 
 --- Write formatted output to a preview buffer
----@param bufnr integer
+---@param target PickerPreviewTarget
 ---@param formatted { lines: string[], extmarks: table, fold_ranges: table }
-local function render_preview_buffer(bufnr, formatted)
-  if not vim.api.nvim_buf_is_valid(bufnr) then
+local function render_preview_buffer(target, formatted)
+  if not target:is_valid() then
+    return
+  end
+  local bufnr = target:get_bufnr()
+  if not bufnr or not vim.api.nvim_buf_is_valid(bufnr) then
     return
   end
 
   local output_window = require('opencode.ui.output_window')
 
-  -- Set lines
-  vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, formatted.lines)
+  target:set_lines(formatted.lines)
+  bufnr = target:get_bufnr()
+  if not bufnr or not vim.api.nvim_buf_is_valid(bufnr) then
+    return
+  end
 
   -- Clear old extmarks then apply new ones
   pcall(vim.api.nvim_buf_clear_namespace, bufnr, output_window.namespace, 0, -1)
   output_window.apply_extmarks(bufnr, formatted.extmarks)
 
   -- Apply folds (window-local operation)
-  local win = vim.fn.bufwinid(bufnr)
-  if win ~= -1 then
-    vim.api.nvim_win_call(win, function()
-      vim.api.nvim_set_option_value('foldmethod', 'manual', { win = 0 })
-      vim.cmd('silent! normal! zE') -- clear existing manual folds
-      local line_count = vim.api.nvim_buf_line_count(bufnr)
-      for _, range in ipairs(formatted.fold_ranges) do
-        if range.from <= line_count and range.to <= line_count then
-          vim.cmd(range.from .. ',' .. range.to .. 'fold')
-        end
+  target:with_window(function()
+    vim.api.nvim_set_option_value('foldmethod', 'manual', { win = 0 })
+    vim.cmd('silent! normal! zE') -- clear existing manual folds
+    local line_count = vim.api.nvim_buf_line_count(bufnr)
+    for _, range in ipairs(formatted.fold_ranges) do
+      if range.from <= line_count and range.to <= line_count then
+        vim.cmd(range.from .. ',' .. range.to .. 'fold')
       end
-    end)
-  end
+    end
+  end)
 end
 
 function M.pick(sessions, callback)
@@ -329,32 +333,47 @@ function M.pick(sessions, callback)
     width = config.ui.picker_width or 100,
     layout_opts = config.ui.picker,
     preview = 'custom',
-    preview_fn = function(session, bufnr)
+    ---@param session table
+    ---@param target PickerPreviewTarget
+    preview_fn = function(session, target)
       preview_seq = preview_seq + 1
       local current_seq = preview_seq
+      target:set_lines({ 'Loading...' })
 
       local state = require('opencode.state')
-      local ok, messages = pcall(function()
-        return state.api_client:list_messages(session.id, nil):wait()
+      local ok, request = pcall(function()
+        return state.api_client:list_messages(session.id, nil)
       end)
-
-      -- Check race: another selection happened while we were loading
-      if current_seq ~= preview_seq then
-        return
-      end
-      if not vim.api.nvim_buf_is_valid(bufnr) then
+      if not ok or not request then
+        target:set_lines({ 'No messages or failed to load' })
         return
       end
 
-      if not ok or not messages or #messages == 0 then
-        vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, { 'No messages or failed to load' })
-        return
-      end
+      request
+        :and_then(function(messages)
+          -- Check race: another selection happened while we were loading
+          if current_seq ~= preview_seq then
+            return
+          end
+          if not target:is_valid() then
+            return
+          end
+
+          if not messages or #messages == 0 then
+            target:set_lines({ 'No messages or failed to load' })
+            return
+          end
 
-      messages = normalize_message_order(messages)
-      local preview_msgs, omitted = filter_preview_messages(messages)
-      local formatted = format_messages(preview_msgs, omitted)
-      render_preview_buffer(bufnr, formatted)
+          messages = normalize_message_order(messages)
+          local preview_msgs, omitted = filter_preview_messages(messages)
+          local formatted = format_messages(preview_msgs, omitted)
+          render_preview_buffer(target, formatted)
+        end)
+        :catch(function()
+          if current_seq == preview_seq and target:is_valid() then
+            target:set_lines({ 'No messages or failed to load' })
+          end
+        end)
     end,
   })
 end