ui: keep every full-frame screen on the alternate buffer (#119)

* ui: trim whitespace on wrapped fact lines, align wrapped prompt lines, rename placeholder to cloud agent

* ui: keep every full-frame screen on the alternate buffer

Only a live chat runs on the primary buffer now. The new-session composer
and the loading placeholder painted full-height frames onto the primary
buffer, pushing stale copies of themselves into scrollback on every
repaint. useAltScreen also reports when the buffer hop has settled, and
the chat mounts only after the terminal is back on the primary buffer,
so its Static transcript rows are never printed onto (and destroyed
with) the alt screen.

Author: hbrooks

src/ui/SessionsApp.tsx

@@ -262,7 +262,6 @@ export function SessionsApp(props: SessionsAppProps): React.ReactElement {
   // terminal rather than a fixed handful of rows.
   const [focus, setFocus] = useState<'nav' | 'chat'>('chat')
   const navOpen = focus === 'nav' && !hideNav
-  useAltScreen(navOpen)
   const [mainPane, setMainPane] = useState<MainPane>(
     props.initialSessionId ? { type: 'chat', sessionId: props.initialSessionId } : { type: 'new' },
   )
@@ -273,6 +272,19 @@ export function SessionsApp(props: SessionsAppProps): React.ReactElement {
   // ------------------------------ chat entries ------------------------------
 
   const [entries, setEntries] = useState<ReadonlyMap<string, ChatEntry>>(new Map())
+  // Only a live chat runs on the primary buffer, printing into the terminal's
+  // real scrollback. Every other screen — the picker, the new-session
+  // composer, the loading placeholder — paints a full-height frame, and a
+  // frame repainted on the primary buffer pushes a stale copy of itself into
+  // scrollback on every repaint. So all of them live on the alternate buffer,
+  // and the primary buffer only ever holds transcript rows.
+  const chatOwnsScreen = mainPane.type === 'chat' && entries.has(mainPane.sessionId)
+  // `altScreenOn` trails the hop: it stays true until the terminal is actually
+  // back on the primary buffer. The chat may only mount once it is false —
+  // its transcript prints each row exactly ONCE (ink <Static>), and a row
+  // printed while the alt screen still has the terminal is destroyed with it.
+  const altScreenOn = useAltScreen(navOpen || !chatOwnsScreen)
+  const chatVisible = chatOwnsScreen && !altScreenOn
   // Sessions whose chat has already printed into this terminal's scrollback.
   // The NEXT one to open prints a rule naming itself first, so two conversations
   // in one scrollback don't run together (see ConnectApp's scrollbackBreak).
@@ -459,9 +471,8 @@ export function SessionsApp(props: SessionsAppProps): React.ReactElement {
   // ctrl+c quits from the nav and from the panes that aren't a live chat (the
   // new-session form, a chat still loading) — the chat pane owns its own, where
   // the first press also interrupts the running turn.
-  const chatOwnsCtrlC = mainPane.type === 'chat' && entries.has(mainPane.sessionId)
   const navArmed = useCtrlCQuit(focus === 'nav' && isRawModeSupported)
-  const paneArmed = useCtrlCQuit(focus === 'chat' && !chatOwnsCtrlC && isRawModeSupported)
+  const paneArmed = useCtrlCQuit(focus === 'chat' && !chatOwnsScreen && isRawModeSupported)
 
   // With the session bar hidden there is nothing to hand focus to: esc and ↓
   // at the chat's bottom edge land where they started.
@@ -735,9 +746,10 @@ export function SessionsApp(props: SessionsAppProps): React.ReactElement {
   // A LIVE CHAT owns the terminal outright: no box around it, no header, no
   // inset. All three would be frame furniture around a region that prints into
   // the terminal's scrollback, and the rows scrolling past would run straight
-  // through them.
-  const chatOwnsScreen = mainPane.type === 'chat' && entries.has(mainPane.sessionId)
-  if (chatOwnsScreen) return main
+  // through them. It mounts only once the alt-screen hop has finished (see
+  // chatVisible above); the one frame in between renders nothing.
+  if (chatVisible) return main
+  if (chatOwnsScreen) return <Box />
 
   // The remaining screens (the new-session composer, a chat still loading) do
   // own their frame, so they keep the inset and the header.

src/ui/altScreen.ts

@@ -1,12 +1,12 @@
-import { useEffect, useRef } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { useApp, useStdout } from 'ink'
 
 // The alternate screen buffer (DECSET 1049), hand-rolled because ink 7 takes
 // `alternateScreen` only as a render()-time option and this app has to hop
 // buffers at runtime under ONE live ink instance: the default view lives in the
 // primary buffer with its settled transcript flushed to real scrollback, and
-// the transcript browser takes over the alt screen and hands the primary buffer
-// back untouched on exit.
+// the full-frame screens (picker, composer, browser) take over the alt screen
+// and hand the primary buffer back untouched on exit.
 //
 // The switch goes through ink's suspendTerminal, which is the only way to keep
 // ink's picture of the screen honest across it: suspend ERASES the current
@@ -18,26 +18,51 @@ import { useApp, useStdout } from 'ink'
 const ENTER = '[?1049h'
 const LEAVE = '[?1049l'
 
-export function useAltScreen(active: boolean): void {
+// Returns whether the app is ON the alt screen right now, trailing `active` by
+// the hop: it flips only after the buffer switch has been written. Callers that
+// print into the terminal's real scrollback (ink's <Static>) must wait for
+// `false` before mounting — <Static> prints each row exactly once, so a row
+// flushed while the alt screen still has the terminal is lost when it closes.
+export function useAltScreen(active: boolean): boolean {
   const { suspendTerminal } = useApp()
   const { stdout } = useStdout()
   // Transitions are serialized: suspendTerminal throws if the terminal is
   // already suspended, and two fast toggles (ctrl+r then esc) would otherwise
   // overlap. Errors are swallowed — failing to hop buffers must not take the
   // session down.
-  const queue = useRef<Promise<unknown>>(Promise.resolve())
-  const hop = (write: string): void => {
-    if (!stdout?.isTTY) return
+  const queue = useRef<Promise<void>>(Promise.resolve())
+  const hop = (write: string): Promise<void> => {
+    if (!stdout?.isTTY) return Promise.resolve()
     queue.current = queue.current
       .then(() => suspendTerminal(() => void stdout.write(write)))
       .catch(() => {})
+    return queue.current
   }
+  // What the terminal is actually showing. `on` tracks the writes issued (so a
+  // re-render never re-enters a buffer it is already in); `settled` follows the
+  // completed hop and is what callers key rendering off.
+  const on = useRef(false)
+  const [settled, setSettled] = useState(false)
   useEffect(() => {
-    if (!active) return
-    hop(ENTER)
-    // Also the unmount path: quitting from inside the browser must give the
-    // primary buffer back rather than leave the shell on the alt screen.
-    return () => hop(LEAVE)
+    if (active === on.current) return
+    on.current = active
+    let alive = true
+    void hop(active ? ENTER : LEAVE).then(() => {
+      if (alive) setSettled(active)
+    })
+    return () => {
+      alive = false
+    }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [active, stdout, suspendTerminal])
+  // The unmount path: quitting from inside an alt screen must give the primary
+  // buffer back rather than leave the shell on the alt screen.
+  useEffect(
+    () => () => {
+      if (on.current) void hop(LEAVE)
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+  return settled
 }