Appearance
Mobile Keyboard Terminal Behavior
Opening or closing the mobile keyboard never resizes the remote PTY in any keyboard mode. All three modes are local presentation choices, so keyboard animation does not wait on the daemon or force Claude Code and other TUIs to redraw. Android soft-keyboard Backspace continues through the full live prompt, including text outside the helper textarea's local mirror.
Surface: Mobile app and web client on touch devices, embedded xterm terminal
Current behavior
The Settings > Terminal > On-screen keyboard > Behavior setting (shown on touch devices) controls how the existing natural-size terminal is presented in the visible band:
| Setting | Behavior |
|---|---|
| Move above keyboard (default) | Keeps natural size and applies one vertical transform to the complete xterm surface so the cursor and the last row holding content stay visible in the band above the keyboard. Anchoring on content rather than the grid's last row avoids showing only the blank rows a TUI leaves below its output. Moving the complete surface keeps xterm's text, cursor, selection, and accessibility layers aligned; independently scrolling the outer container could leave Android WebView GPU layers at different offsets and produce duplicated or overlapping rows. Rows lifted above the band are live screen, not scrollback, so a downward touch drag first pans the surface back toward its top before scrolling history; typing snaps it back to the cursor. |
| Fit to screen (shrink) | Keeps PTY geometry unchanged and locally scales the whole grid to fit above the keyboard. |
| Scroll (keep size) | Keeps natural size and top-aligns the grid so the user can scroll within the visible band. |
Native keyboard inset updates drive a local presentation pass during the IME animation. No ResizePty request, resize boundary, SIGWINCH, or history reconciliation is triggered by the keyboard, so there is no network roundtrip, TUI repaint, blink, or lag when the keyboard opens or closes.
Hide the keyboard
The terminal key bar has a keyboard button on touch devices, just before the chevron. Hide keyboard closes the on-screen keyboard without giving up input: the terminal keeps the session claim and the key bar keys (arrows, Esc, Tab, ^C, custom buttons) still type. With the keyboard gone the terminal uses the full screen height. Like any keyboard open or close, this is local presentation only and does not resize the remote PTY.
The keyboard stays down until you ask for it again. Paste, attaching files, reloading history and switching back to the app all leave it closed. Tap the terminal or press Show keyboard to type again.
If Android's back gesture closed the keyboard, the button reads Show keyboard and reopens it. Starting a touch text selection also closes the keyboard the same way.
Continuous Backspace on Android
Android's hidden xterm textarea mirrors composed text so Gboard suggestions and IME edits can be reconciled with the PTY. That mirror can reach empty or caret position 0 while the live prompt still contains text inserted by completion, paste, the mobile key bar, or an earlier mirror reset.
Clusto prevents xterm from handling that boundary key and sends Backspace directly to the PTY. If the client is still acquiring the input claim or replacing history, the delete is queued and sent when input is safe again. Holding Backspace can therefore continue through the complete live prompt without stopping at the textarea boundary.
iOS Safari and home-screen PWA
On iPhone and iPad, Clusto uses the helper textarea mirror for terminal input. This supports both QuickPath swipe commits and normal tap typing in Safari and the installed home-screen PWA. For ordinary tap typing, Safari can emit a usable beforeinput event with insertText or insertCompositionText while leaving xterm's helper textarea stale and without a usable compositionupdate. Clusto projects that insertion into the existing mirror before xterm's target listeners run, forwards it to the PTY once, and suppresses xterm's duplicate emission. Text replacement, paste, and deletion remain governed by the authoritative textarea difference.
A short tap in the terminal explicitly focuses xterm while the tap still counts as a Safari user activation. This opens the on-screen keyboard and enables typing in both a regular browser tab and an installed home-screen PWA.
On iPhone and iPad, xterm ignores touch drags while a foreground TUI has mouse reporting enabled. Safari can then treat the gesture as page panning while the terminal remains stationary. Clusto keeps one-finger terminal drags from panning the Safari page and checks whether xterm handled each movement. Only unhandled movement becomes a synthetic wheel event at the touch coordinates. xterm then routes that wheel through its normal behavior for the claim owner: regular terminal scrollback when available, or mouse-wheel input to the foreground TUI. Whole wheel notches beyond the per-frame send cap remain queued for the next movement instead of being discarded. A gesture that xterm already handled does not receive the fallback, so it is not applied twice.
For a read-only viewer, the same gesture can scroll ordinary local scrollback but can never send mouse bytes to the remote PTY. If the running application is using the alternate buffer, Clusto consumes the gesture without changing that shared application. Use Claim or Take over before interacting with the TUI.
This fallback is specific to Safari on iPhone and iPad. Android touch scrolling is unchanged.