Agentic UI Widget Lifecycle

ChatWidget lifecycle

Widget windows are disposable. Buffers persist; windows do not.

State machine

Each transition cites the test that pins it. A transition without a test is a gap: add the test or delete the transition.

stateDiagram-v2
    [*] --> hidden
    hidden --> visible: show()<br/>create fresh windows<br/>reapply window-local opts
    visible --> hidden: hide()<br/>close + destroy widget windows<br/>buffers persist

    state "destroy()" as destroy
    visible --> destroy
    hidden --> destroy

    destroy --> [*]: WidgetLayout.close(win_nrs)<br/>then buffers deleted<br/>(close skips handles whose tabpage is gone)

Pinned by, in lua/agentic/ui/chat_widget.test.lua:

• hidden -> visible: ::"show() after hide() creates new windows", ::"show() is idempotent when called multiple times"
• visible -> hidden: ::"hide() closes all windows and preserves buffers", ::"hide() is safe when called multiple times"
• hidden -> destroy: ::"deletes the buffers of a hidden widget without raising"
• visible -> destroy: ::"keeps the tabpage alive when the widget holds its only windows"
• hidden float on destroy: ::"tears down the hidden chat window on destroy"

Rules

• show after hide creates fresh windows and applies every window-local option. show on a visible widget reuses its live windows; it reopens nothing.
• Before closing widget windows, hide ensures a non-widget fallback window exists in the same tabpage; if find_first_non_widget_window returns nil it calls open_editor_window. Skipping this destroys the user's tabpage: closing the last window of a non-current tabpage closes that tabpage silently, and E444 (cannot close last window) only fires when it is also the last tabpage. See ChatWidget:hide.
• A caller that reaches hide across an async boundary MUST pass the tabpage it captured BEFORE the defer, as hide(keep_insert, tabpage). WinClosed fires on win_nrs.chat and invalidates it before the scheduled hide runs, and get_visible_tab_id reads no other handle, so the derived placement is already nil there: _ensure_fallback_window returns early and the close takes the widget-only tabpage down with it. Only the tabpage IDENTITY crosses the boundary — _ensure_fallback_window and find_first_non_widget_window still re-check nvim_tabpage_is_valid on it. Regression: chat_widget.test.lua::"keeps a widget-only tab alive when the chat window closes".
• ChatWidget:open_editor_window anchors on the first USABLE window in win_nrs, preferring chat. The chat handle is already dead on the WinClosed path above, and returning nil there is what loses the tabpage.
• Programmatic window closes (hide, layout rotation) MUST wrap the close call in ChatWidget:_avoid_auto_close_cmd. The wrapper sets self._closing = true so the WinClosed autocmd's auto-close-on-user-close branch skips the call. Skipping the wrapper triggers a recursive close through the autocmd. Tests: chat_widget.test.lua group "WinClosed autocmd".
• destroy never routes through hide, but both share ChatWidget:_ensure_fallback_window. It calls that, then WidgetLayout.close on its win_nrs, then deletes the buffers. Relative to hide it skips hidden-float recreation, size capture, and stopinsert suppression — a destroyed widget is never shown again. WidgetLayout.close skips every handle whose tabpage is already gone, keeping this safe during a tabclose teardown on 0.11.x. See ChatWidget:destroy.
  • The fallback is mandatory here. SessionRegistry.show_session hides non-target widgets in the current tabpage and hides the target at its previous placement, so an outgoing session in another tabpage stays visible. Destroying it reaches WidgetLayout.close there, and without the fallback that tabpage disappears under the user. Reachable from Agentic.destroy_session and from restore's explicit Destroy current session choice. Regression: chat_widget.test.lua::"keeps the tabpage alive when the widget holds its only windows".
  • Ordering: the fallback MUST run before WidgetRegistry.unregister. find_first_non_widget_window excludes windows showing a registered widget buffer, so once unregistered the widget's own chat window looks like a valid fallback and gets handed back.
• destroy is the one programmatic close exempt from the _avoid_auto_close_cmd rule above. It deletes the AgenticWinClosed_<chat bufnr> augroup before closing, so the only listener that ever read self._closing is gone by then; setting the flag would guard nothing. Any new close path that runs while that augroup still exists MUST wrap.

Widget buffers and windows

• Widget buffers are buflisted = false and buftype = nofile. Each widget window records its buffer in vim.w[winid].agentic_bufnr, 1:1. Users cannot swap buffers between widget windows; BufferGuard restores them.
• The WinClosed autocmd hides the WHOLE widget when the user closes any one widget window. The widget is one unit.