fix(mobile): hold the PTY rows while the on-screen keyboard is up

Every keyboard open and close resized the PTY, and Claude Code's inline renderer answers each height change by clearing the screen and reprinting only the transcript tail that fits, so rows above that tail were lost from tmux for good. Measured on Claude Code 2.1.306 with tmux 3.2a: five keyboard cycles (62x38 to 62x15 and back) left 75 of 100 numbered lines in the pane's history; with the rows held the PTY stays 62x38, no SIGWINCH reaches the pane and all 100 remain (#672).

While the keyboard is up the rows captured at the show transition are held through getTerminalDimensions, columns still follow the box, and the screen, now taller than its box, is translated up by --kb-clip so the last content row sits at the bottom of the visible area. This is the one documented exception to the columns-only geometry rule: there the extra rows came from another device and nothing kept the composer in view, here they are this device's own rows held on purpose and the clip keeps the composer visible. The local-echo overlay's setRowLimit narrows the renderer's existing totalRows bound, so one place decides where a long draft stops growing downward.

Only inline renderers hold, through a new registry capability keyboardHold: 'inline' (Claude alone) published to the page as window.__codemanKeyboardHoldModes. Full-height layouts such as codex, Claude's fullscreen mode (mouse tracking on, unmeasured), and remote or docker panes resize as before. The hold is released on keyboard close, a shape change, a tab switch, a session update, a reconnect, or the setting turned off. Per-device setting Keep Size Under Keyboard, default on.
This commit is contained in:
JD committed 2026-10-24 20:17:45 -04:00
1 parent 3e06f3c141
commit 3e334357e8
26 files changed
+1226 -14

No files matched your search

+3
View File
@@ -301,6 +301,9 @@ const capabilitiesSchema = z
// the CLI to page its own transcript. Distinct from wheelForward (SGR reports).
// Optional: absent means no paging, the safe default for an unmeasured CLI.
transcriptPageKeys: z.boolean().optional(),
// Keep the PTY's rows while a phone keyboard is up (inline renderers only).
// Optional: absent means the keyboard resizes, the safe default.
keyboardHold: z.literal('inline').optional(),
keyboardAccessory: z.enum(['agent', 'shell']),
privilegedCommandGate: z.boolean(),
startMode: z.enum(['interactive', 'shell']),
+4
View File
@@ -289,6 +289,10 @@ const CLAUDE: CliEntry = {
// forwarded (older CLI, inline renderer, the local-scrollback opt-out) a scroll is
// turned into PageUp/PageDown, which Claude pages its transcript on (#205).
transcriptPageKeys: true,
// Claude's default renderer is inline, and each keyboard-driven PTY height change made
// it reprint only the tail that fits, erasing transcript rows from tmux (measured on
// 2.1.306: 25 of 100 lines over five keyboard cycles). See CliCapabilities.keyboardHold.
keyboardHold: 'inline',
keyboardAccessory: 'agent',
privilegedCommandGate: false,
startMode: 'interactive',
+24
View File
@@ -563,6 +563,30 @@ export interface CliCapabilities {
* Absent means no paging, so a CLI nobody has measured keeps plain local scrolling.
*/
transcriptPageKeys?: boolean;
/**
* `'inline'`: the CLI renders inline (its content stacks at the bottom of the
* main screen), so while a phone's on-screen keyboard is up the browser keeps
* the PTY's rows and scrolls the view instead of resizing (`keyboardHoldsRows`,
* terminal-ui.js `_keyboardHoldEligible`). Read by the frontend through
* `window.__codemanKeyboardHoldModes`, which the server builds from this field.
*
* Why it exists: every PTY height change makes Claude Code's inline renderer
* clear the screen and reprint only the tail that fits (#672). Measured on
* Claude Code 2.1.306 with tmux 3.2a, a fresh session already at the phone's
* size printing 100 numbered lines: five keyboard open/close cycles (PTY
* 62x38 to 62x15 and back, one SIGWINCH per transition) left 75 of the 100 in
* `tmux capture-pane` history, the other 25 gone for good; with the rows held
* the PTY stayed 62x38, no SIGWINCH reached the pane and all 100 remained.
*
* ⚠ Only for a renderer that is inline. A CLI that lays out the FULL height
* (codex: banner at the top, composer pinned to the bottom) cannot fit both
* ends above the keyboard and must be resized instead, so it stays absent.
* Absent means resize, the safe default for an unmeasured CLI. Even when set,
* the hold stands aside while the CLI reports mouse tracking (Claude's
* fullscreen mode, which lays out the full height and has not been measured
* losing lines, so it resizes as before), and for remote and docker sessions.
*/
keyboardHold?: 'inline';
keyboardAccessory: 'agent' | 'shell';
/** Multi-user: this CLI is a raw shell, so its commands need the privileged gate. */
privilegedCommandGate: boolean;