Improve mobile key input reliability

Replace sticky Ctrl defaults with explicit Prefix and Alt+Enter controls, and add a drawer combo picker for explicit Ctrl/Alt sends without depending on soft keyboard modifiers. Route combo sends through the send queue to preserve action order under async hooks.

Author: connorads

CHANGELOG.md

@@ -28,3 +28,5 @@ This project has not been published yet. On first release, rename this section t
 - Added: `floatingButtons` config — always-visible buttons on touch devices using the same `ControlButton` schema as toolbar/drawer. Renders in the help overlay when non-empty.
 - Breaking: `floatingButtons` changed from a flat `ControlButton[]` to `FloatingButtonGroup[]`. Each group has a `position` (`'top-left' | 'top-right' | 'top-centre' | 'bottom-left' | 'bottom-right' | 'bottom-centre' | 'centre-left' | 'centre-right'`), optional `direction` (`'row' | 'column'`, default `'row'`), and a `buttons` array. Migrate: `floatingButtons: [btn]` → `floatingButtons: [{ position: 'top-left', buttons: [btn] }]`.
 - Changed: Tailscale Serve guide now recommends always rebuilding the overlay before start; removed version-hash cache-key snippet to prevent stale build issues.
+- Changed: default toolbar now uses explicit tmux `Prefix` (`C-b`) and `Alt+Enter` buttons for more predictable mobile input.
+- Added: new drawer `Combo` action (`combo-picker`) that opens a small combo input modal for explicit Ctrl/Alt key sends.

README.md

@@ -8,7 +8,7 @@ Turns a ttyd web terminal into a touch-optimised tmux client with toolbar, gestu
 
 - **`webmux serve`** — one command to run webmux: builds overlay in memory, manages ttyd, serves manifest + icons
 - **PWA installable** — "Add to Home Screen" on iOS and Android with proper icon and standalone mode
-- **Two-row toolbar** — Esc, Ctrl (sticky modifier), Tab, arrows, C-c, Enter, tmux prev/next, paste, drawer toggle
+- **Two-row toolbar** — Esc, Prefix (`C-b`), Tab, arrows, C-c, Enter, Alt+Enter, paste, drawer toggle
 - **Config-driven controls** — unified button model across toolbar + drawer with ids and descriptions
 - **Swipe gestures** — configurable swipe left/right with custom data and help overlay labels
 - **Floating buttons** — always-visible quick-action buttons (top-left, touch only) for zoom, pane cycling, etc.
@@ -92,10 +92,11 @@ export default defineConfig({
   toolbar: {
     row1: [
       { id: 'esc', label: 'Esc', description: 'Send Escape key', action: { type: 'send', data: '\x1b' } },
-      { id: 'ctrl-mod', label: 'Ctrl', description: 'Sticky Ctrl modifier', action: { type: 'ctrl-modifier' } },
+      { id: 'tmux-prefix', label: 'Prefix', description: 'Send tmux prefix key (Ctrl-B)', action: { type: 'send', data: '\x02' } },
       // ...
     ],
     row2: [
+      { id: 'alt-enter', label: 'M-↵', description: 'Send Alt+Enter (ESC + Enter)', action: { type: 'send', data: '\x1b\r' } },
       { id: 'drawer-toggle', label: '☰ More', description: 'Open command drawer', action: { type: 'drawer-toggle' } },
       { id: 'paste', label: 'Paste', description: 'Paste from clipboard', action: { type: 'paste' } },
       // ...
@@ -105,6 +106,7 @@ export default defineConfig({
     buttons: [
       { id: 'tmux-new-window', label: '+ Win', description: 'Create tmux window', action: { type: 'send', data: '\x02c' } },
       { id: 'tmux-split-vertical', label: 'Split |', description: 'Split pane vertically', action: { type: 'send', data: '\x02|' } },
+      { id: 'combo-picker', label: 'Combo', description: 'Open combo sender (Ctrl/Alt + key)', action: { type: 'combo-picker' } },
       // ...
     ],
   },
@@ -129,8 +131,12 @@ export default defineConfig({
     widthThreshold: 768,   // px — default matches common phone/tablet breakpoint
   },
   floatingButtons: [
-    // Always-visible buttons in the top-left corner (touch devices only)
-    { id: 'zoom', label: 'Zoom', description: 'Toggle pane zoom', action: { type: 'send', data: '\x02z' } },
+    {
+      position: 'top-left',
+      buttons: [
+        { id: 'zoom', label: 'Zoom', description: 'Toggle pane zoom', action: { type: 'send', data: '\x02z' } },
+      ],
+    },
   ],
 })
 ```

src/actions/registry.ts

@@ -7,6 +7,10 @@ export interface ActionExecutionContext {
 	readonly sendText: (data: string) => Promise<void>
 	readonly sendRawText?: (data: string) => Promise<void>
 	readonly openDrawer?: () => void
+	readonly openComboPicker?: (options: {
+		readonly sendText: (data: string) => Promise<void>
+		readonly focusIfNeeded: () => void
+	}) => void
 	readonly toggleCtrlModifier?: () => void
 }
 
@@ -104,5 +108,24 @@ export function createDefaultActionRegistry(): ActionRegistry {
 		}
 	})
 
+	registry.register('combo-picker', (_action, context) => {
+		if (context.openComboPicker) {
+			context.openComboPicker({
+				sendText: async (data: string) => {
+					await registry.execute(
+						{ type: 'send', data },
+						{
+							...context,
+							sendText: context.sendRawText ?? context.sendText,
+						},
+					)
+				},
+				focusIfNeeded: context.focusIfNeeded,
+			})
+		} else {
+			context.focusIfNeeded()
+		}
+	})
+
 	return registry
 }

src/config-validate.ts

@@ -211,7 +211,7 @@ function validateAction(value: unknown, path: string, issues: ValidationIssue[])
 		pushIssue(
 			issues,
 			`${path}.type`,
-			`'send' | 'ctrl-modifier' | 'paste' | 'drawer-toggle'`,
+			`'send' | 'ctrl-modifier' | 'paste' | 'combo-picker' | 'drawer-toggle'`,
 			actionType,
 		)
 		return
@@ -221,12 +221,13 @@ function validateAction(value: unknown, path: string, issues: ValidationIssue[])
 		actionType !== 'send' &&
 		actionType !== 'ctrl-modifier' &&
 		actionType !== 'paste' &&
+		actionType !== 'combo-picker' &&
 		actionType !== 'drawer-toggle'
 	) {
 		pushIssue(
 			issues,
 			`${path}.type`,
-			`'send' | 'ctrl-modifier' | 'paste' | 'drawer-toggle'`,
+			`'send' | 'ctrl-modifier' | 'paste' | 'combo-picker' | 'drawer-toggle'`,
 			actionType,
 		)
 		return

src/config.ts

@@ -25,7 +25,7 @@ const defaultGestures: WebmuxConfig['gestures'] = {
 	scroll: { enabled: true, sensitivity: 40, strategy: 'wheel', wheelIntervalMs: 24 },
 }
 
-/** Default row 1 buttons (modifiers + nav) */
+/** Default row 1 buttons (prefix + nav) */
 const defaultRow1: WebmuxConfig['toolbar']['row1'] = [
 	{
 		id: 'esc',
@@ -34,10 +34,10 @@ const defaultRow1: WebmuxConfig['toolbar']['row1'] = [
 		action: { type: 'send', data: '\x1b' },
 	},
 	{
-		id: 'ctrl-mod',
-		label: 'Ctrl',
-		description: 'Sticky Ctrl modifier for the next typed key',
-		action: { type: 'ctrl-modifier' },
+		id: 'tmux-prefix',
+		label: 'Prefix',
+		description: 'Send tmux prefix key (Ctrl-B)',
+		action: { type: 'send', data: '\x02' },
 	},
 	{ id: 'tab', label: 'Tab', description: 'Send Tab key', action: { type: 'send', data: '\t' } },
 	{
@@ -86,7 +86,12 @@ const defaultRow1: WebmuxConfig['toolbar']['row1'] = [
 
 /** Default row 2 buttons */
 const defaultRow2: WebmuxConfig['toolbar']['row2'] = [
-	{ id: 'q', label: 'q', description: 'Send q key', action: { type: 'send', data: 'q' } },
+	{
+		id: 'alt-enter',
+		label: 'M-↵',
+		description: 'Send Alt+Enter (ESC + Enter)',
+		action: { type: 'send', data: '\x1b\r', keyLabel: 'Alt+Enter' },
+	},
 	{
 		id: 'ctrl-d',
 		label: 'C-d',
@@ -194,6 +199,12 @@ export const defaultDrawerButtons: readonly ControlButton[] = [
 		description: 'Kill current pane (with confirm)',
 		action: { type: 'send', data: '\x02x' },
 	},
+	{
+		id: 'combo-picker',
+		label: 'Combo',
+		description: 'Open combo sender (Ctrl/Alt + key)',
+		action: { type: 'combo-picker' },
+	},
 ]
 
 /** Default mobile configuration */