feat(terminal): customize the mobile key bar

CHANGELOG.md

@@ -18,6 +18,18 @@ between releases do not reach them. Remote-PC runtime bundles are versioned sepa
   A double-click returns to the default width. The width is remembered on each device, and the
   sidebar never takes more than half the window.
   ([#521](https://github.com/devswha/herdr-web-ui/pull/521))
+- The mobile terminal key bar has sticky Ctrl, Alt and Shift toggles and an Enter key.
+  Herdr encodes held combinations with arrows, special keys and direct typing for
+  the pane's keyboard protocol. Modifiers clear when leaving
+  the pane or disconnecting. Pasted text and submitted drafts keep their contents.
+  Queued terminal chords and text are cancelled when the sender leaves their attachment or
+  its terminal is replaced.
+  ([#433](https://github.com/devswha/herdr-web-ui/pull/433) by @nickadminroot,
+  [#508](https://github.com/devswha/herdr-web-ui/pull/508))
+- Settings can add, remove and reorder every mobile terminal key and register custom key
+  combinations in a separate key bar editor. Existing extra-key preferences keep their keys and order,
+  and Restore defaults returns the original bar. Native clipboard shortcuts on non-Latin keyboards
+  and existing Alt combinations remain intact. ([#508](https://github.com/devswha/herdr-web-ui/pull/508))
 
 ### Changed
 - Every agent's chat uses one compact Send/Stop button on desktop and phones. Sending during
@@ -72,6 +84,9 @@ between releases do not reach them. Remote-PC runtime bundles are versioned sepa
   took the change for old news and said nothing. A finished turn is also measured from its own
   start in that case, so a short turn is not told as a long one.
   ([#536](https://github.com/devswha/herdr-web-ui/pull/536))
+- **Dismiss** on the terminal's notice that input was not sent works: a tap or click on it went
+  through to the terminal under it and the notice stayed.
+  ([#508](https://github.com/devswha/herdr-web-ui/pull/508))
 
 ## [0.3.52] - 2026-10-06
 

DESIGN.md

@@ -950,6 +950,16 @@ One set for both themes: the card is island black wherever it shows.
   pane / Wide 1152px / Full, the pane less its gutters), chat font
   size and family. Shortcuts: the complete
   platform-resolved table.
+- Appearance keeps Key bar as a compact description and Edit key bar button. That button opens
+  a detail screen in the same dialog with its own scroll body and a Back to settings control.
+  Back or Escape returns to the previous Settings scroll position and focuses Edit key bar;
+  closing the dialog resets it to Settings for the next open. The detail lists the terminal keys
+  in their display order. Every key can be
+  removed or moved with up/down buttons; those controls keep `--touch-target` hit areas on phones.
+  Add key offers the supported key catalog, and Ctrl/Alt/Shift toggles add or remove held-modifier
+  buttons. Custom combination chooses one key or printable character plus modifiers, with its cap
+  previewed before Add. Saved combinations send exactly those modifiers; ordinary keys inherit the
+  held modifiers. Restore defaults returns the original row. The keyboard mode control stays first.
 - A font family is a text field saved when it is left, on Enter or when the dialog closes, not
   per keystroke.
 - Remote PCs follows Devices: an **Add PC** row (label, one-line description, button) opens the PC
@@ -974,7 +984,12 @@ One set for both themes: the card is island black wherever it shows.
 - xterm has `scrollback: 0`; wheel/touch gestures reach herdr's alternate-screen scrollback. The
   mount clips its own gutter and hides the unused xterm scrollbar.
 - Terminal banners stack top-right for ended, reconnecting, observe and held-draft review states.
-- The mobile key bar is Esc, Tab, one-shot Ctrl, arrows and `^C`; it never steals xterm focus.
+- The mobile key bar is Esc, Tab, sticky Ctrl/Alt/Shift, Enter, arrows and `^C`;
+  it never steals typing focus. Modifiers remain highlighted until toggled off,
+  leaving the pane/lens or disconnecting; each exposes `aria-pressed`.
+- That is the default row. Settings → Appearance → Key bar can add, remove and reorder every
+  terminal key and register exact combinations. Removing a held modifier clears it immediately.
+  A deliberately empty row retains only the keyboard mode control on a touch screen.
 - The mobile drawer slides over a scrim. Closed visibility removes its controls from the tab order.
 
 ### In-app alert

docs/development.md

@@ -20,6 +20,8 @@ bun run build
 bun run test:unit               # no herdr needed; CI's Fast checks run it
 bun test                        # needs herdr installed; creates and removes its own workspaces
 bun run test:ui                 # browser regression against isolated test servers
+bun scripts/sticky-modifiers-regression.ts # mobile held keys through real legacy/Kitty PTYs
+bun scripts/key-bar-customization-demo-regression.ts # mobile key layout, saved combinations and migration on demo fixtures
 bun scripts/chat-browser-qa.ts  # chat lens end to end
 bun scripts/output-browser-qa.ts # terminal output flow control end to end
 bun scripts/math-browser-qa.ts  # chat math: KaTeX loads with the first expression

docs/guide.md

@@ -241,9 +241,18 @@ whether the test was sent or failed; a missing subscription offers **Turn alerts
 
 On a phone:
 - Agent panes open in the chat.
-- The terminal gets a key bar above the keyboard (Esc, Tab, Ctrl, Alt, arrows, Ctrl+C).
-  **Settings → Appearance → Key bar** adds or removes Alt, Shift+Tab, Home/End, PgUp/PgDn,
-  Ctrl+D, Ctrl+Z, `|`, `~` and `/`.
+- The terminal gets a key bar above the keyboard (Esc, Tab, Ctrl, Alt, Shift, Enter, arrows, Ctrl+C).
+  Ctrl, Alt and Shift stay held until tapped again and combine with each other.
+  Enable direct terminal typing with the keyboard button to use them with letters and
+  symbols. Herdr encodes each chord for the program's keyboard protocol; legacy
+  protocols cannot distinguish every chord (for example Ctrl+I and Tab).
+  Draft text in the input line is sent unchanged. Modifiers clear
+  when leaving the pane or terminal view, or when the connection drops.
+  **Settings → Appearance → Key bar → Edit key bar** opens a separate screen to add, remove and
+  reorder every key, including modifier
+  buttons. Register a custom combination such as Ctrl+W, choose editing keys or F1–F12, or restore
+  the default row. Saved combinations use exactly their selected modifiers; ordinary keys use
+  the currently held modifiers. Removing a held modifier button clears it.
 - Dragging the terminal scrolls the real herdr pane.
 - **Settings → Phone → Keep screen on** keeps the screen awake while a terminal or chat
   pane is open. It is off by default, releases when the app is hidden, and resumes when

docs/terminal-input.md

@@ -45,13 +45,20 @@ Control sequences are counted as discarded, never saved for later execution. No
 on reconnect. The input-line and chat Send buttons preserve an active composition, and the key bar
 waits for composition to finish. Leaving the input clears its composition guard.
 
-The key bar always has Esc, Tab, Ctrl, the arrows and ^C. Settings → Appearance → Key bar adds
-Alt (on by default), Shift+Tab, Home/End, PgUp/PgDn, ^D, ^Z, `|`, `~` and `/`, each in a fixed
-place in the row. Ctrl and Alt are one-shot: an armed Alt puts ESC before the next character
-(Alt+Backspace, Alt+Enter) and adds the Alt modifier to an arrow, Home, End or Page key
-(`CSI 1;3D`); armed together they send ESC and the control code. A paste or a report the
-terminal answers with passes through and leaves Alt armed. Neither applies to the input line
-or the chat composer, which send their text as typed.
+The key bar defaults to Esc, Tab, Ctrl, Alt, Shift, Enter, the arrows and ^C.
+Settings → Appearance → Key bar → Edit key bar opens the complete list: add or remove keys, move each key up or
+down, and register a custom combination such as Ctrl+W. The catalog includes editing keys and
+F1–F12; a custom combination can use any single printable character, including space and `+`.
+Existing extra-key preferences migrate to the same visible order. Restore defaults returns the
+original bar; an empty list stays empty. The keyboard mode button stays first on touch screens.
+Ctrl, Alt and Shift stay held until tapped again and can be combined. Removing a modifier button
+clears its held state immediately. Ordinary key buttons use the held modifiers, while saved
+combinations send exactly their configured modifiers without changing the held state.
+Direct typing and arrow buttons send logical key chords; Herdr encodes them for the
+PTY's keyboard protocol. Home/End, Page and Delete/Insert keys use CSI navigation through the attach
+stream because Herdr's RPC key parser lacks those names. Paste, IME commits and terminal reports pass through unchanged.
+The input line and chat composer send their text as typed. Changing panes, leaving the
+terminal view or disconnecting clears the held modifiers.
 
 On macOS, Cmd+Left and Cmd+Right in direct typing send Ctrl+A and Ctrl+E, moving to the
 beginning and end of the input line in shells and agents that use those bindings.

package.json

@@ -18,7 +18,7 @@
     "test": "bun test",
     "test:unit": "bun scripts/ci-tests.ts unit",
     "test:integration": "bun scripts/ci-tests.ts integration",
-    "test:ui": "bun run build && bun scripts/ui-regression.ts",
+    "test:ui": "bun run build && bun scripts/ui-regression.ts && bun scripts/sticky-modifiers-regression.ts",
     "generate:types": "bun run scripts/generate-protocol-types.ts",
     "build:remote": "bun run scripts/build-remote-bundle.ts",
     "build:site": "bun scripts/build-site.ts",

scripts/ci-browser.sh

@@ -5,6 +5,8 @@ bun node_modules/playwright-core/cli.js install --with-deps chromium
 CHROME_PATH="$(bun -e 'console.log(require("playwright-core").chromium.executablePath())')"
 export CHROME_PATH
 bun scripts/ui-regression.ts
+bun scripts/sticky-modifiers-regression.ts
+bun scripts/key-bar-customization-demo-regression.ts
 bun scripts/chat-history-browser-qa.ts
 bun scripts/math-browser-qa.ts
 bun scripts/file-viewer-regression.ts

scripts/fixtures/modifier-probe.py

@@ -0,0 +1,25 @@
+"""Owned test pane: capture actual terminal stdin without shell/TUI interpretation."""
+import os
+import sys
+import termios
+import tty
+
+path, mode = sys.argv[1:]
+before = termios.tcgetattr(0)
+try:
+    tty.setraw(0)
+    # Disambiguation + report all keys; no release/repeat reporting in this probe.
+    if mode == "kitty":
+        os.write(1, b"\x1b[>9u")
+    os.write(1, ("PROBE READY " + mode + "\r\n").encode())
+    with open(path, "a", buffering=1) as output:
+        while True:
+            data = os.read(0, 4096)
+            if not data:
+                break
+            output.write(data.hex())
+            output.flush()
+finally:
+    if mode == "kitty":
+        os.write(1, b"\x1b[<u")
+    termios.tcsetattr(0, termios.TCSANOW, before)