Skip to content

1.0: TUI render-path stabilization freeze — soak + regression tests before 1.0 #480

Description

@mabry1985

From the 1.0-readiness audit. Not a filed bug — a churn signal. The TUI render/resize path has dominated recent releases:

  • #467 / v0.71.1 — reflow <Static> history on resize
  • #469 / v0.71.2 — stop live-region output duplicating on resize (the throttled clear+repaint)
  • #440 — full-screen + native selection (reversed v0.65.0's mouse capture)
  • #444 word-diff, #459 thinking render, #449 gradient spinner

4+ of the last ~8 releases touched the render loop. For a 1.0 the render path should stop churning.

Why this is fragile (verified constraints, don't re-litigate)

  • Ink's <Static> is append-only and index-tracked — it never redraws committed lines; the array passed to it must only ever grow (packages/cli/src/ui/components/MainContent.tsx:36-40).
  • Ink's live region redraws by erasing the previous frame's stored log-update line count — after a resize the terminal has reflowed that frame to a different height, so the erase misses and stale frames land in scrollback.
  • refreshStatic() (clear + historyRemountKey bump) is the only lever that fully repaints; it's now called on model change, /clear, view switch, transcript toggle, and (as of fix(tui): stop live-region output duplicating on terminal resize #469) resize.
  • In full-screen, layout height==rows forces Ink into the clearTerminal branch — it rewrites the whole alt-screen on every commit.

Proposed 1.0 gate

  1. Soak the render path — a real-terminal pass over: drag-resize (inline + full-screen), long sessions, streaming + spinner, agent tabs, transcript overlay, dialogs. Resize duplication is real-TTY-onlyink-testing-library's fake stdout has no cursor/scrollback, so unit tests cannot catch it (this is exactly why fix(tui): stop live-region output duplicating on terminal resize #469 shipped unverified until a live check).
  2. Regression tests at the seams we can test — resize→repaint wiring (done in DefaultAppLayout.test.tsx), <Static> growth invariant, refreshStatic call sites.
  3. Tune RESIZE_THROTTLE_MS (currently 80ms, DefaultAppLayout.tsx) if the drag repaint flickers in daily use.
  4. Freeze the render loop for 1.0 — TUI Wave-2 (TUI S4 — Steer & Queue (interrupt + resubmit-merge) #450TUI S9 — adaptive 'system' theme + semantic palette + gradient brand #455) is explicitly post-1.0; several are high-blast-radius (S6 touches the ~1100-line KeypressContext; S7 refactors AppContainer's ~120-field memo).

Related: specs/tui-overhaul.md, #456 (minor follow-ups).

Metadata

Metadata

Assignees

No one assigned

    Labels

    1.01.0 readiness (see 1.0 epic)tuiTerminal UI overhaul (specs/tui-overhaul.md)

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions