---
url: https://clusto.app/docs/known-issues-mobile-keyboard-menu.md
description: >-
  How Clusto handles mobile terminal input, keyboard layout, and history
  scrolling without resizing the remote PTY.
---

# 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.
