What it does:

• Moves overlay focus restoration into pi-tui, so a focused visible overlay can reclaim input after temporary non-overlay UI steals focus and closes. Adds OverlayHandle.unfocus({ target }), expands overlay focus tests, and updates the manual overlay QA demo.

Good:

• Fixes the reported ctx.ui.custom(factory) without overlay:true bricks any open sibling overlay #5129 path for the common coding-agent flow: overlay opened from editor, non-overlay custom UI takes focus, then restoreEditor() focuses the editor and the overlay reclaims input.
• The rendering/compositing path is mostly untouched; risk is concentrated in focus routing.
• Test coverage is much stronger for blocked replacement focus, hidden overlays, setFocus(null), non-capturing overlays, visual focus order, and stale preFocus chains.

Bad:

• Contributor PR edits packages/tui/CHANGELOG.md. Per repo policy, contributor PRs should not edit changelogs.
• Coding-agent docs should be updated. packages/coding-agent/docs/tui.md and packages/coding-agent/docs/extensions.md still only document handle.setHidden() / hide() in onHandle, not focus(), unfocus({ target }), or the new “focused visible overlay reclaims input” behavior.
• Missing an integration/regression test around actual InteractiveMode.showExtensionCustom: overlay ctx.ui.custom(..., { overlay: true }) followed by non-overlay ctx.ui.custom(...). Current tests simulate TUI behavior but not the coding-agent path that caused ctx.ui.custom(factory) without overlay:true bricks any open sibling overlay #5129.

Ugly:

• setFocus() semantics become stateful when a visible overlay is focused. A caller can no longer reliably move input to a base component with tui.setFocus(base) while the overlay remains visible; the overlay may reclaim input unless the caller uses handle.unfocus({ target }). That may be intended, but it is a public behavior change and needs clear docs.
• Restoration depends on the temporary UI returning focus to the overlay’s preFocus target. If an overlay was focused with preFocus !== editor, then a coding-agent non-overlay close that calls setFocus(editor) can leave the overlay visible but non-interactive again. That edge is not tested.

Tests:

• Covered: many TUI-level unit cases for overlay focus stealing/restoring, blocked replacement input, explicit unfocus targets, invisible overlays, null focus, focus order, and preFocus retargeting.
• Missing: coding-agent integration coverage for the real ctx.ui.custom overlay/non-overlay sequence, and an edge case where overlay preFocus differs from the component focused when replacement UI closes.

This comment is AI-generated.

@nicobailon sorry for the ai review above, but it's 0:30am and i'm tired :D

Updated: removed the changelog entry, added the missing coding-agent docs, and covered the real InteractiveMode.showExtensionCustom path with a regression test. TUI now also restores overlay focus when the temporary replacement component is removed from the mounted tree before focus returns.

cheers!