Skip to content
SHC Docs

The HUD on a phone

The SHC Console’s TUI mode runs the HUD full screen on a phone. Nothing sits over it. You drive it with gestures, and the keyboard comes and goes with the view you are on.

Every gesture the terminal tells apart is bound to a HUD key. The swipes and a long press’s drags are the arrow keys, so moving around needs no keyboard. The HUD’s help (?, or a three-finger tap) lists the same map first, under GESTURES.

GestureSendsIn the HUD
tapEnteropen the row
double tap/, keyboard upsearch
2-finger tap(the app)keyboard on or off, anywhere
3-finger tap?help
long press, lifted without moving:, keyboard upcommand prompt
hold, then drag up, down, left or rightthe arrow key, over and over while heldmove; the farther the finger, the faster
swipe up or downUp or Down, one per row of travelmove a row at a time
swipe left or rightLeft or Rightdialog buttons, a prompt’s suggestion, scroll
2-finger swipe up or downPage Up or Page Downpage
2-finger swipe left or right[ or ]history back or forward
swipe in from the left edgeEscback
pull down from the top two rowsctrl-rrefresh
pinch(the app)text size

A two-finger swipe and a pinch use the same fingers. A pinch that scales the text less than 15% counts as the swipe.

Android tells apart the same gestures. Its own back, the system’s swipe in from the edge or the back button, is the edge swipe there: Esc, back a view in the HUD, never out of it. With the keyboard up, the first back puts the keyboard away, as it does everywhere on Android.

The keyboard opens by itself on a list, where the next thing is usually a search or a command, and goes away by itself on one resource (its describe or YAML) and on logs, which you read. The help and anything else leave it as it is. A two-finger tap, or the last key of the row, shows or hides it whenever you like, and that holds until you move to another view.

The row above the keyboard carries what a phone’s keyboard lacks:

KeyDoes
esc, tabEsc and Tab
ctrlheld for the next key you type (ctrl then d is ctrl-d)
: /the HUD’s command and search keys
← ↓ ↑ →the arrow keys
⌄put the keyboard away
✕leave the HUD, back to the Console; the far end of the row, away from esc

:q in the HUD leaves it as well.

The HUD says which view is on top with the terminal’s private OSC, ESC ] 7770 ; view ; <kind> BEL, each time a different one is drawn. The kind is list, resource, logs, help or other. The Console never reads the screen to guess. The code is sent only when the app asks for the codes (codes=1 in the HUD’s args), and the gestures the help lists arrive the same way, as gestures: a JSON list of [gesture, what it does] pairs.

The tables live in packages/terminal-hud/src/index.ts (hudBindings, hudGestureHelp, hudKeyboard, hudKeyRow); the gestures themselves in packages/terminal/src/bindings.ts. Each platform’s view reads touches into them its own way: GestureLayer.swift with UIKit’s recognizers on iOS, GestureReader.kt on Android, at the same distances and times.