Add in-app scrollback with history mode

[shellicar]

Summary

• History region visible above the zone during a session
• Page Up/Down and Shift+Up/Down scroll through previous output
• History mode pins the viewport; Esc or scrolling to bottom returns to live
• Scroll position indicator in the status bar when in history mode

Related Issues

Closes #150

[bananabot9000]

PR #152 Review — In-App Scrollback with History Mode ✅

Clean implementation of the two-region rendering model. The HistoryViewport abstraction is solid — live/history mode state machine, proper top-padding for short content, auto-follow in live mode. This is exactly what was needed after #151 removed terminal scrollback.

What I like

HistoryViewport design — The resolve() method returning { lines, position, total, isLive } is a clean interface. Consumers don't need to know about internal scroll state. The top-padding logic (filling with empty strings when content < viewport height) handles the edge case of "just started, only 2 history lines" gracefully.

Key routing placement — History scroll keys checked early in handleKey (after ctrl+c, before ctrl+/). Escape checks isHistoryMode before command mode exit. This means you can scroll history, press Escape to return to live, without accidentally toggling command mode. Good priority ordering.

Two-region renderZone() — The 5-step data flow (get zone frame → get history viewport → combine → render → flush to main) is readable and each step has a clear responsibility. displayBuffer vs historyBuffer separation (display for viewport, history for main buffer flush) is the right call.

Test coverage — 15+ HistoryViewport tests, 7 input tests, integration tests for two-region rendering. The displayBuffer tests verify auto-follow behaviour and zone height change adaptation. 218 tests passing.

wrapLine export from Layout.ts — Was module-private, now exported for Terminal to use when pushing to displayBuffer. Minimal change, correct scope expansion.

Observations (non-blocking)

1. displayBuffer grows unbounded — writeHistory() pushes to both historyBuffer (string[]) and displayBuffer (string[]). Neither is ever trimmed. For long sessions this could get large. Not a problem now (history lines are small, sessions compact before memory matters), but worth a future cap if needed.

2. Status line [↑ N/M] — Shows in history mode. Clean indicator. Does it disappear immediately on returnToLive()? Looks like yes — isLive means renderZone skips the indicator. Good.

3. Shift modifier detection — input.ts checks \x1b[1;2 prefix for shift+arrow. This is the standard xterm encoding. Should work in all modern terminals. Edge case: some terminals send different sequences for shift+pgup/pgdn, but those are caught by the named key check first.

4. render() signature change — render(historyRows: string[], zoneFrame: ViewportResult) in TerminalRenderer. All existing tests updated to pass [] as historyRows. Clean migration.

LGTM. The alternate buffer now has eyes. 👀

Co-reviewed-by: BananaBot9000 🍌

[bananabot9000]

PR #152 Review -- In-App Scrollback with History Mode

Clean implementation of the two-region rendering model. The HistoryViewport abstraction is solid -- live/history mode state machine, proper top-padding for short content, auto-follow in live mode. This is exactly what was needed after #151 removed terminal scrollback.

What I like

HistoryViewport design -- The resolve() method returning { lines, position, total, isLive } is a clean interface. Consumers don't need to know about internal scroll state. The top-padding logic (filling with empty strings when content < viewport height) handles the edge case of "just started, only 2 history lines" gracefully.

Key routing placement -- History scroll keys checked early in handleKey (after ctrl+c, before ctrl+/). Escape checks isHistoryMode before command mode exit. This means you can scroll history, press Escape to return to live, without accidentally toggling command mode. Good priority ordering.

Two-region renderZone() -- The 5-step data flow (get zone frame, get history viewport, combine, render, flush to main) is readable and each step has a clear responsibility. displayBuffer vs historyBuffer separation (display for viewport, history for main buffer flush) is the right call.

Test coverage -- 15+ HistoryViewport tests, 7 input tests, integration tests for two-region rendering. The displayBuffer tests verify auto-follow behaviour and zone height change adaptation. 218 tests passing.

wrapLine export from Layout.ts -- Was module-private, now exported for Terminal to use when pushing to displayBuffer. Minimal change, correct scope expansion.

Observations (non-blocking)

1. displayBuffer grows unbounded -- writeHistory() pushes to both historyBuffer (string[]) and displayBuffer (string[]). Neither is ever trimmed. For long sessions this could get large. Not a problem now (history lines are small, sessions compact before memory matters), but worth a future cap if needed.

2. Status line indicator -- [up-arrow N/M] shows in history mode, disappears on returnToLive() since isLive skips the indicator in renderZone. Clean.

3. Shift modifier detection -- input.ts checks \x1b[1;2 prefix for shift+arrow. Standard xterm encoding. Should work in all modern terminals. Edge case: some terminals send different sequences for shift+pgup/pgdn, but those are caught by the named key check first.

4. render() signature change -- render(historyRows, zoneFrame) in TerminalRenderer. All existing tests updated to pass [] as historyRows. Clean migration.

LGTM. The alternate buffer now has eyes.

Co-reviewed-by: BananaBot9000