Tool call streaming flicker: why we use manual folds with anchor pads

[carlos-algms]

Tool call streaming flicker: why we use manual folds with anchor pads

Notes from #210. Posting because the dead ends are non-obvious.

Symptom

Streaming tool call updates flickered the chat buffer up and down in auto mode. Worst when a body crossed the fold threshold for the first time.

Two interacting causes

1. nvim_buf_set_lines shifts topline by buffer-line delta to keep the cursor visually anchored. zb recomputes topline by screen-row math. With wrap=on (chat needs it), one buffer line can wrap to 30+ screen rows. The two algorithms diverge.
2. With foldmethod=expr, foldexpr is lazy. set_lines only evaluates a small neighborhood around the change. zb then measures screen rows against an unfolded buffer state and lands on a wrong topline. ~10ms later foldexpr catches up, the fold materializes, and WinScrolled jumps the viewport. That jump is the flicker.

What we shipped

Two changes:

Synchronous scroll. Replaced the scheduled _auto_scroll with a _capture_scroll (pre-mutation) + _apply_scroll (post-mutation, same tick) pair. Collapses the two-frame transition that made both topline values visible.

Manual folds with anchor pads. Switched from foldmethod=expr to foldmethod=manual. Every tool call block is now laid out as:

header              <- not folded, rewritten on every update
"" top_pad          <- empty anchor
... body ...        <- replaced on every update
"" bottom_pad       <- empty anchor
"" trailing

Body updates replace lines strictly between the anchors. The fold (created once via :N,Nfold when interior crosses the threshold) survives indefinitely because Vim grows manual folds when content is inserted inside their range. Replacing the entire fold range would destroy it; the anchors prevent that.

Why not foldexpr + force recompute

We tried. The only Vim command that synchronously forces foldexpr recompute is zX. It works but:

• O(N) per transition (evaluates foldexpr for every line in the buffer). At 20k+ line conversations this matters.
• Re-applies foldlevel=0, closing any folds the user had opened with zo elsewhere.

Manual folds avoid both costs.

Things that look like they should work but do not

All disproven empirically with headless tests counting foldexpr calls:

Attempt	Result
vim.fn.foldlevel(L)	Passive cache read. Does NOT trigger eval.
vim.fn.foldclosed(L)	Same. Passive.
vim.wo.foldexpr = vim.wo.foldexpr	Invalidates cached entries only. New uncached lines stay unfolded.
:[start],[end] foldclose	Closes existing folds; no-op if foldexpr has not run for the range.
zn then zN	Toggles foldenable. Preserves manual state. Does NOT recompute.
winrestview({topline=...})	zb recomputes from cursor anyway, overwrites the restore.

How avante and codecompanion avoid this

Both sidestep the problem by not using foldexpr:

• avante.nvim: no folds. Auto-scroll is nvim_win_set_cursor(winid, {last_line, last_col}). Cursor-follow handles topline.
• codecompanion.nvim: foldmethod=manual, folds created via :N,Nfold only after streaming completes. Never has live mid-stream fold transitions.

Our case (live transitions on growing blocks) is the harder variant.

Sources

• :help fold-expr, :help :fold (Neovim runtime docs)
• vim/vim#16184 — cache foldexpr levels
• olimorris/codecompanion.nvim — chat UI
• yetone/avante.nvim — sidebar

[carlos-algms]

Update: two more dead ends

Found making manual folds actually persist across panel close/reopen.

style="minimal" corrupts manual fold storage

Open chat, fold a tool call, close panel, reopen -> fold gone or
shifted. Cause: nvim_open_win(..., { style = "minimal" }) stores an
empty fold map in the buffer's last-window memory on close.
Undocumented; the API docs only mention UI options.

Fix: drop style="minimal", replace with explicit options
(PANEL_WINDOW_OPTS) for no number / no signcolumn / no ~ past EOF.

Assigning an option re-runs Vim's set-handler

After (1), folds persisted. But zo-opened folds snapped closed on
every reopen. Cause: Fold.setup_window reasserts foldlevel = 0,
which re-applies even when the value is unchanged.

Same trap on foldmethod. Fix: equality guard.

if vim.wo[winid].foldmethod ~= "manual" then
    vim.wo[winid].foldmethod = "manual"
end
if vim.wo[winid].foldlevel ~= 0 then
    vim.wo[winid].foldlevel = 0
end

Result

Folds now survive hide/show, layout rotation, and tab switches.
User's zo/zc state preserved across reopens.

[carlos-gomes-parloa]

Update: folds while the widget is hidden

After the previous fix, folds survived hide/show. But folds created
while the widget was hidden (streaming tool calls in the background)
appeared unfolded on the next show.

Why

Fold.close_range ran :N,Nfold only inside a window currently
displaying the buffer. With the widget hidden, no window held the
chat buffer, so the call was a no-op and the fold was never created.
On reopen, only previously-folded blocks were folded.

What docs/community solutions said (and why they did not fit)

• :mkview / :loadview — requires a real filename. buftype=nofile
  throws E32: No file name.
• winsaveview / winrestview — :help winsaveview is explicit:
  "This does not save fold information."
• Walking foldclosed on BufWinLeave to snapshot ranges, then
  rebuilding on BufWinEnter — works, but the buffer's per-window
  fold-state cache (:help fold-manual, fold.txt:647-652) already
  does this. The bug was upstream of the cache: no window meant no
  cache entry.

What actually works

Per fold.txt:647-652, when re-displaying a buffer Neovim "uses the
last used folding settings... from the window where the buffer was
edited last". So a single window holding the buffer at all times is
enough. The widget needs that window to exist whether visible or not.

Solution: a per-ChatWidget hidden floating window that holds the
chat buffer whenever the widget is hidden.

visible    visible chat window holds buffer
  | hide
hidden     hidden float holds buffer (Fold.close_range works here)
  | show
visible    visible chat window holds buffer (folds carry over)

Hard invariant: exactly one window on the chat buffer at a time.

• _initialize opens the float after the chat buffer exists.
• show closes the float before opening the visible chat window.
• hide closes any prior float, then opens a new one after
  closing visible windows.
• destroy closes the float after hide.

Verified empirically

Two windows on the same buffer concurrently break the snapshot — only
one wins on next reopen, and the wrong one can win. Single-ownership
preserves folds across arbitrary hide/show cycles. Tests:
hidden chat window lifecycle group in chat_widget.test.lua,
including preserves manual folds across hide/show via hidden chat window.

Two non-obvious traps from this work

1. hide=true does NOT exempt the float from layout edge cases.
   On older Neovim, a 1-row float fails with E36: Not enough room
   when the source window has winbar set
   (neovim/neovim#19464,
   fixed in neovim/neovim#25192).
   Generous dimensions (we use 80x20) plus a pcall for graceful
   degradation. The widget tolerates float-creation failure and just
   loses the hidden-state fold guarantee.

2. hide reopening without closing the previous float leaks.
   The two-hide sequence (no intervening show) overwrites
   _hidden_chat_winid and orphans the previous winid. Test:
   does not leak a hidden float across hide() calls.

Summary

Manual folds are window-local, but Neovim's per-buffer last-used
fold-state snapshot replays them on next display — provided some
window held the buffer at all times. A hidden float is the cheapest
way to guarantee that for a hideable widget.