Skip to content

Terminal Touch Selection (Mobile) ​

The app's terminal renders through xterm.js onto a <canvas>. On a touch device the browser has no native way to select canvas text - a finger drag is consumed by viewport scrolling, and there are no native selection handles - so Clusto provides its own selection layer that mimics the native Android experience.

This applies only to coarse-pointer (touch) devices. On desktop, right-click still opens the regular terminal context menu (Copy / Paste / Select All / Find / Attach file / Reload full history / Clear) and selection works with the mouse as usual.

How to use it ​

  1. Long-press anywhere in the terminal (hold a still finger for about half a second; moving it scrolls instead). The word under your finger is selected (or the whole line when you press on trailing whitespace), two draggable handles appear at the selection ends, and a floating toolbar opens.
  2. Drag either handle to grow or shrink the selection. Dragging across rows extends the selection; dragging into the top or bottom edge auto-scrolls the viewport so you can reach off-screen content.
  3. Tap a toolbar action:
    • Copy - copies the selection to the system clipboard and exits.
    • Paste - sends the clipboard contents to the session (bracketed-paste wrapped for multi-line text) and exits. This is the touch equivalent of Ctrl+V, which is otherwise hard to reach on a phone.
    • Select All - selects the entire scrollback buffer.
    • Cancel - clears the selection and exits.
  4. Tapping anywhere outside the handles or toolbar also exits selection mode.

The on-screen keyboard stays out of the way for the whole gesture: entering selection mode closes it, and neither the toolbar actions nor the tap that leaves selection mode bring it back. Tap the terminal again when you want to type - that tap is what raises the keyboard.

Text selection outside the terminal ​

On mobile operating systems, selecting regular page or editor text opens Clusto's global Copy / Cut / Select All toolbar. This applies in both the native mobile app and the web client running in a mobile browser or installed as a PWA. While that toolbar is visible, Clusto suppresses the browser or WebView context menu so only one set of copy actions appears.

Why a custom layer ​

A few mobile-specific problems this design solves:

  • No vanishing menu. A long-press on Android emits a trailing pointer/click event right after contextmenu fires. A naive "close on tap outside" menu catches that trailing event and dismisses itself instantly. The selection toolbar ignores dismiss taps for a short window after it opens, so it stays up.
  • Keyboard stays down while selecting. A browser replays a finished touch gesture as synthesized mouse events, and xterm focuses its hidden input on any mousedown - so a long-press used to pop the keyboard over the text being selected. Those replayed events are swallowed while a selection is open and briefly after it closes, and entering selection mode blurs the hidden input. Only a deliberate tap on the terminal raises the keyboard.
  • Real range selection. Instead of only auto-selecting a word, the handles let you select an arbitrary multi-row range.

Implementation notes ​

The selection layer is driven entirely by the xterm.js public API:

  • The range is set with term.select(col, row, length). xterm's selection model wraps length across rows (computing the end column modulo cols), so a single flat cell count expresses an arbitrary multi-line span.
  • The canvas renderer draws the highlight; term.getSelection() yields the copy text; term.scrollLines() drives edge auto-scroll.
  • Selection boundaries are kept in 0-based absolute buffer coordinates, and the handles are positioned with position: fixed recomputed each animation frame, so they follow scrolling and the soft-keyboard slide.

Mobile browsers do not reliably fire contextmenu on a long-press over the canvas (iOS Safari never does), so the terminal detects the long-press itself from touch pointer events. The contextmenu event remains a fallback on coarse-pointer devices that do emit it.

Clusto - remote AI coding agents over WebSocket.