fix(ui): pin composer to terminal bottom — stop layout jitter during streaming

[HUQIANTAO]

Problem

During agent output streaming, the composer input box at the bottom of the terminal moves up and down. This is visually jarring — the user is trying to read streaming output while the input area they will type into next is bouncing around.

Root Cause: Ink/Yoga layout with unconstrained height

The current layout structure in App.tsx (simplified):

// main branch — unconstrained outer container
<Box flexDirection="row" backgroundColor={SURFACE.bg}>
  <Box flexDirection="column" flexGrow={1}>
    <Box flexDirection="column" flexGrow={1}>   // content area
      <CardStream />                           // grows during streaming
      <WelcomeBanner />
      <LiveActivityArea />                     // height fluctuates (progress bars)
    </Box>
    <ComposerArea flexShrink={0} />            // should be bottom-pinned
  </Box>
</Box>

Ink uses Yoga (Facebook's flexbox engine) for layout. Yoga calculates the height of each flex container from its children. When the outer container has no explicit height, Yoga's layout algorithm works as follows:

1. Initial state: content area contains a few settled cards. Total height ≈ 60% of terminal. Composer sits at the bottom with a large gap above it.

2. Streaming starts: new text lines are appended to the active card. CardStream's content grows. Yoga recalculates — the content area now needs more vertical space.

3. Layout reflow: since the outer container is unconstrained, Yoga expands it to accommodate the new content. The composer (which sits at the end of the flex column) gets pushed down. The terminal scrolls.

4. Streaming settles: the active card stops growing. The layout stabilizes. But on the NEXT turn, new cards appear again, causing another reflow.

5. Bidirectional jitter: When LiveActivityArea updates (progress bar appears/disappears, tool status line changes), the height changes by 1-2 rows. Yoga reflows again → composer shifts by 1-2 rows → visible flicker.

The fundamental issue is that Yoga does not know the terminal has a fixed number of rows. Without an explicit height, it treats the container as infinitely expandable, and every content change triggers a full reflow.

Fix

Two properties added to the layout:

1. Fixed outer height via useTerminalSize()

// fix branch
const { rows: terminalRows } = useTerminalSize();

<Box flexDirection="row" backgroundColor={SURFACE.bg} height={terminalRows}>

useTerminalSize() is Inks built-in hook that reads the actual TTY dimensions (process.stdout.rows). By passing height={terminalRows} to the outermost layout Box, we tell Yoga: "this container is exactly N rows tall — no more, no less."

Effect: Yoga no longer recalculates the container height when children change. It allocates the fixed terminalRows space, then distributes it among children using flexGrow/flexShrink. The composer's position is now a function of the terminal size (which only changes on resize), not of the streaming content.

2. Overflow clamping on the content area

// fix branch
<Box flexDirection="column" flexGrow={1} overflow="hidden">

The overflow="hidden" property (passed through to Yoga) tells the layout engine: "children may not extend beyond this container's allocated height." Yoga clips content at the boundary.

Effect: Even if CardStream renders more cards than fit in the viewport, Yoga does not expand the content area. The CardStream component already implements virtual scrolling (it only renders cards within a visible window + buffer), so this acts as a safety net for edge cases where the measured card heights are temporarily inconsistent with actual rendered heights (common during streaming when card heights are being measured for the first time).

Why this is beneficial

Aspect	Before	After
Composer position during streaming	Shifts up/down by 1-6 rows	Fixed at terminal bottom
Layout recalculation per frame	Full reflow from unconstrained root	Constrained reflow within fixed bounds
Visual experience	Jarring — text you're reading moves while input box bounces	Stable — only the streaming content area updates
Resize handling	Same (Yoga recalculates anyway)	Slightly better — terminalRows updates on next render

Potential downsides — and why they don't apply

1. "What if the terminal is resized?"

useTerminalSize() returns live dimensions. When the user resizes their terminal window, the hook returns the new rows value on the next render. Yoga recalculates the layout with the new height. This is correct behavior — the composer re-anchors to the new bottom.

2. "What if CardStream virtual scrolling breaks with a fixed outer height?"

CardStream already uses outer.height (from useBoxMetrics) to compute its visible window. The fixed outer height ensures outer.height is stable frame-to-frame, which actually improves virtual scrolling consistency — the visible window boundaries don't oscillate.

3. "What about the StaticCardStream path (historyScrollMode: "terminal")?"

StaticCardStream uses Inks <Static> component which positions items at absolute coordinates within the container. A fixed-height container is the intended usage pattern for <Static> — it requires a known viewport to correctly map item indices to screen positions. This change makes StaticCardStream strictly more correct.

4. "Does useTerminalSize() work in non-TTY environments (piped stdout)?"

Yes. Inks useTerminalSize() falls back to process.stdout.columns || 80 / process.stdout.rows || 24 when stdout is not a TTY. The desktop app (Electron) always uses a pty, so TTY dimensions are always available.

5. "Any performance impact?"

No. useTerminalSize() reads a value that Ink already tracks internally (it's used for the root node height). This is a property read, not a measurement. The height and overflow props are standard Yoga properties with no additional overhead.

Changes

File	Diff	Description
src/cli/ui/App.tsx	+4 −3	Import useTerminalSize, add height to outer Box, add overflow to content Box

Testing

1. Start Reasonix: npx reasonix code
2. Send a message that triggers a long streaming response with tool calls
3. Observe: the composer input box stays fixed at the bottom throughout streaming
4. Resize the terminal: the layout correctly re-anchors to the new bottom
5. Send multiple messages in sequence: no position drift accumulates

Related

• Ink uses Yoga 2.x for layout: https://yogalayout.com/
• Inks useTerminalSize(): packages/ink/src/index.ts:101