fix(tui): defer rebuild after output-driven layout shrink

[hetaoBackend]

Change

Refs #426.

In regular (main-screen) mode, a reader who has scrolled up in native scrollback is thrown to the very top of the history (line 0) when the TUI rebuilds its history. This PR covers the rebuild that follows an output-driven layout shrink, such as the task list or another transient region collapsing when a reply finishes, without user input. After this PR that rebuild waits for the next key or paste, so a scrolled-up reader stays where they are and a tailing reader stays at the bottom.

Scope note: resize (for example a host fit addon reacting to a layout change) also triggers the rebuild after it settles. That deferral has been split out of this PR pending more information from the reporter about their fit/resize behaviour; resize keeps its current replay here.

Root cause

The L034 full reconstruction writes ESC[2J ESC[H ESC[3J and replays the whole document. In xterm.js, ED 3 sets the viewport to max(ydisp - scrollback, 0) = 0 while the buffer keeps its "user is scrolling" state, so the replay does not move the viewport down again and it stays at line 0. No output-only escape sequence can restore a host's scroll offset (only a full reset clears the scrolling state), so restoring the offset from the application side is not possible. Plain streaming does not reconstruct; the triggers are a settled resize and an output-driven layout shrink (unknown or changed layout key, L041).

Changes

• packages/tui/src/tui/engine/tui.ts: a protected onUserInput() hook is called when an input chunk contains a key or paste. The chunk is split into control sequences rather than matched as a whole: focus, window-size, cursor-position (CPR/DECXCPR), device-attribute, device-status, kitty-flag and mode (DECRPM) reports, OSC/DCS/APC strings, SGR mouse reports and key releases do not count, and a key or paste that shares a chunk with reports still does.
• packages/tui/src/tui/engine/tui-main-screen.ts:
  • A shrink in an unknown or changed layout reconstructs immediately only within 1 s of user input, so input-driven closes still restore rows right away. Otherwise it pads with blank rows like L038 and marks the replay as deferred.
  • The deferred L034 reconstruction runs on the next user input after the deferral, on a settled resize replay, or on stop(), so native history still ends exact and unique.
  • Unchanged: resize replays history after settling as before, and changed historical text still reconstructs immediately.
• packages/tui/src/tui/engine/LOCAL_CHANGES.md / .json: new L047 entry (contract, cause, change, tradeoff, evidence, removal condition), a note on L034/L041, updated file hashes and change IDs.
• packages/tui/test/unit/tui-engine-local-deltas.test.ts: new xterm-based cases using the real TuiChatLayout:
  • scrolled up, the Tasks section collapses without input: no ED 3, unchanged scroll position, unique history; after a key, exact history;
  • tailing at the bottom when output ends and the task list collapses: no jump, stays at the bottom with the final line visible; after a key, exact history at the bottom;
  • recent input reconstructs immediately; a settled resize keeps its replay;
  • focus, window-size, CPR, DECXCPR, kitty flags, DA, DSR, DECRPM, kitty key release and a report-only mixed chunk do not trigger the replay; a key after a CPR, a key between reports, an arrow key after a focus report, a paste after a report, and Escape do;
  • the deferred replay runs before stop.
    Existing input-driven close tests now deliver a key first.

Validation

• Checks run and results (head 931c470, base 564e916, Linux, Node 24.21.0):
  • Against main's renderer the shrink cases, the key cases and the stop case fail (ED 3 emitted or no deferral); on main the tailing case fails only on the ED 3 assertion (that reader also ends at the bottom on main). With whole-chunk matching, the CPR, DECXCPR and mixed report-only chunk cases fail.
  • pnpm typecheck, pnpm lint, pnpm check:source: pass.
  • node scripts/run-vitest-suite.mjs capability: 206 files, 5228 passed, 18 skipped.
  • pnpm verify: passed, 14 gates on Linux (test:windows, test:sandbox and test:release-package skipped as not applicable).
  • Local replay of the real TUI (built dist) in node-pty driving @xterm/headless 6.0.0 with a dense-streaming mock provider:
    • queued follow-up drained at the end of each turn, scrolled up and tailing: no ED 3, scrolled viewport unchanged (e.g. 283 → 283, 587 → 587), tailing at the bottom.
    • resize mid-stream: unchanged from main (scrolled-up viewport still ends at 0; tailing at the bottom), as intended for this scope.
  • Same replay into @xterm/xterm 6.0.0 + addon-fit 0.11.0 + addon-webgl 0.19.0 in headless Chrome: tailing with resize stays at the bottom; scrolled up during streaming without resize never reaches line 0.
  • The local harness does not drive a real background-task collapse in the product; that path is covered by the engine tests above with the real chat layout.
• Performance: basic.
• NOT RUN, platform limitations and live-service boundaries: native Windows Terminal / ConPTY, iTerm2, Apple Terminal and other native emulators were not tested; evidence is from xterm.js (headless and browser) only. No live-service runs.

Risks / tradeoffs

• Blank rows after an output-driven layout shrink can separate history from the visible screen until the next key (or exit).
• The 1 s input window is a heuristic: a reader who scrolls up within 1 s of a key while a layout shrink lands can still be moved.
• Hosts that do not scroll to the bottom on input could still be moved to the top when the deferred replay runs.
• Legacy modified F3 keys encoded as CSI 1;n R are indistinguishable from cursor position reports and do not trigger the deferred replay.
• A resize that settles while the reader is scrolled up still moves the viewport to the top (split out, see scope note).
• Untested on native Windows Terminal / ConPTY, which is where the issue was reported.
• Tests reach the protected onUserInput() through a cast helper.

Publication and contribution checks

• I have permission to contribute these changes under the existing licenses applicable to the changed files/packages; imported material and its provenance are identified and existing notices are preserved.
• No credentials, account data, real user content, internal source history or private review material is included.
• Added/removed source files were reviewed before regenerating release/public-source.json; new tests are declared in test/vitest-suites.json where applicable.
• Shared English/Chinese documentation and capability/verification records are updated where applicable. Mock/offline results are not described as live-service acceptance.

Maintainer handoff

Publication scope or license changes (if any): none.

Shared-source port: pending.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}