feat: prefix button sends prefix then opens combo picker

New `prefix` action type: sends the prefix byte (e.g. Ctrl-B) then
immediately opens the combo picker for the follow-up key. Solves the
mobile UX problem where tapping the terminal to bring up the keyboard
breaks tmux prefix mode.

Combo picker now accepts optional title/description so the prefix
flow shows contextual help ("After prefix").

Users who want raw prefix-only behaviour can override to
`{ type: 'send', data: '\x02' }` via existing config system.

Author: connorads

.agents/skills/remobi-setup/SKILL.md

@@ -278,12 +278,13 @@ name  theme  font  toolbar  drawer  gestures  mobile  floatingButtons  pwa  reco
 | `type`           | Required fields     | Notes |
 |------------------|---------------------|-------|
 | `send`           | `data: string`      | Optional `keyLabel?: string` for help overlay |
+| `prefix`         | `data: string`      | Sends prefix byte then opens combo picker for follow-up key. Use `{ type: 'send', data: '\x02' }` for raw prefix-only behaviour |
 | `ctrl-modifier`  | (none)              | Opens Ctrl+key combo UI |
 | `paste`          | (none)              | Paste from clipboard |
 | `combo-picker`   | (none)              | Opens Ctrl/Alt + key modal |
 | `drawer-toggle`  | (none)              | Opens/closes command drawer |
 
-Non-`send` actions must NOT have `data` or `keyLabel` — the validator rejects them.
+Non-`send`/`prefix` actions must NOT have `data` or `keyLabel` — the validator rejects them.
 
 ### ControlButton shape
 
@@ -340,7 +341,7 @@ Valid positions: `top-left | top-right | top-centre | bottom-left | bottom-right
 | `id` | `label` | `action` |
 |------|---------|----------|
 | `esc` | Esc | `send` `\x1b` |
-| `tmux-prefix` | Prefix | `send` `\x02` |
+| `tmux-prefix` | Prefix | `prefix` `\x02` (sends prefix then opens combo picker for follow-up key) |
 | `tab` | Tab | `send` `\t` |
 | `shift-tab` | S-Tab | `send` `\x1b[Z` |
 | `left` | <- | `send` `\x1b[D` |
@@ -479,7 +480,7 @@ export default {
   toolbar: {
     row1: (defaults) => defaults.map(b =>
       b.id === 'tmux-prefix'
-        ? { ...b, description: 'Send tmux prefix key (Ctrl-A)', action: { type: 'send', data: '\x01' } }
+        ? { ...b, description: 'Send tmux prefix key (Ctrl-A)', action: { type: 'prefix', data: '\x01' } }
         : b
     ),
   },

src/actions/registry.ts

@@ -10,6 +10,8 @@ export interface ActionExecutionContext {
 	readonly openComboPicker?: (options: {
 		readonly sendText: (data: string) => Promise<void>
 		readonly focusIfNeeded: () => void
+		readonly title?: string
+		readonly description?: string
 	}) => void
 	readonly toggleCtrlModifier?: () => void
 }
@@ -33,7 +35,7 @@ export function createActionRegistry(): ActionRegistry {
 		const handler = handlers.get(action.type)
 		if (!handler) return false
 
-		if (action.type === 'send') {
+		if (action.type === 'send' || action.type === 'prefix') {
 			const current = sendQueue.then(async () => {
 				await handler(action, context)
 			})
@@ -55,6 +57,17 @@ export function createActionRegistry(): ActionRegistry {
 	return { register, execute }
 }
 
+/** Map a prefix byte to a human-readable label (e.g. '\x02' → 'Ctrl-B') */
+function describePrefixByte(data: string): string | null {
+	if (data.length !== 1) return null
+	const code = data.charCodeAt(0)
+	// Ctrl-A through Ctrl-Z → 0x01–0x1A
+	if (code >= 1 && code <= 26) {
+		return `Ctrl-${String.fromCharCode(code + 64)}`
+	}
+	return null
+}
+
 export function createDefaultActionRegistry(): ActionRegistry {
 	const registry = createActionRegistry()
 	let pasteQueue: Promise<void> = Promise.resolve()
@@ -108,6 +121,28 @@ export function createDefaultActionRegistry(): ActionRegistry {
 		}
 	})
 
+	registry.register('prefix', async (action, context) => {
+		if (action.type !== 'prefix') return
+		await context.sendText(action.data)
+		if (context.openComboPicker) {
+			const prefixLabel = describePrefixByte(action.data)
+			context.openComboPicker({
+				title: `Prefix sent${prefixLabel ? ` (${prefixLabel})` : ''} — type follow-up`,
+				description:
+					'A letter like r (reload config) or c (new window). ' + 'C-x = Ctrl+x, M-x = Alt+x',
+				sendText: async (data: string) => {
+					await registry.execute(
+						{ type: 'send', data },
+						{ ...context, sendText: context.sendRawText ?? context.sendText },
+					)
+				},
+				focusIfNeeded: context.focusIfNeeded,
+			})
+		} else {
+			context.focusIfNeeded()
+		}
+	})
+
 	registry.register('combo-picker', (_action, context) => {
 		if (context.openComboPicker) {
 			context.openComboPicker({

src/config-schema.ts

@@ -16,13 +16,18 @@ const sendActionSchema = v.strictObject({
 	keyLabel: v.optional(v.string()),
 })
 
+const prefixActionSchema = v.strictObject({
+	type: v.literal('prefix'),
+	data: v.string(),
+})
 const ctrlModifierActionSchema = v.strictObject({ type: v.literal('ctrl-modifier') })
 const pasteActionSchema = v.strictObject({ type: v.literal('paste') })
 const comboPickerActionSchema = v.strictObject({ type: v.literal('combo-picker') })
 const drawerToggleActionSchema = v.strictObject({ type: v.literal('drawer-toggle') })
 
 const buttonActionSchema = v.variant('type', [
 	sendActionSchema,
+	prefixActionSchema,
 	ctrlModifierActionSchema,
 	pasteActionSchema,
 	comboPickerActionSchema,

src/config.ts

@@ -45,7 +45,7 @@ const defaultRow1: RemobiConfig['toolbar']['row1'] = [
 		id: 'tmux-prefix',
 		label: 'Prefix',
 		description: 'Send tmux prefix key (Ctrl-B)',
-		action: { type: 'send', data: '\x02' },
+		action: { type: 'prefix', data: '\x02' },
 	},
 	{ id: 'tab', label: 'Tab', description: 'Send Tab key', action: { type: 'send', data: '\t' } },
 	{

src/controls/combo-picker.ts

@@ -5,6 +5,8 @@ import { onTap } from '../util/tap'
 interface ComboDispatch {
 	readonly sendText: (data: string) => Promise<void>
 	readonly focusIfNeeded: () => void
+	readonly title?: string
+	readonly description?: string
 }
 
 type ComboParseResult =
@@ -263,15 +265,22 @@ export function createComboPicker(): ComboPickerResult {
 		}
 	}
 
+	const defaultTitle = 'Send combo'
+	const defaultDescription = 'Examples: C-s, C-[, M-Enter, Alt-x'
+
 	function open(dispatch: ComboDispatch): void {
 		currentDispatch = dispatch
 		clearError()
 		input.value = ''
+		title.textContent = dispatch.title ?? defaultTitle
+		description.textContent = dispatch.description ?? defaultDescription
 		backdrop.style.display = 'flex'
 		setTimeout(() => input.focus(), 0)
 	}
 
 	function close(): void {
+		title.textContent = defaultTitle
+		description.textContent = defaultDescription
 		closeAndFocus()
 	}
 

src/types.ts

@@ -3,6 +3,7 @@ export type ButtonAction =
 	| { readonly type: 'send'; readonly data: string; readonly keyLabel?: string }
 	| { readonly type: 'ctrl-modifier' }
 	| { readonly type: 'paste' }
+	| { readonly type: 'prefix'; readonly data: string }
 	| { readonly type: 'combo-picker' }
 	| { readonly type: 'drawer-toggle' }
 

tests/action-registry.test.ts

@@ -349,6 +349,107 @@ describe('createDefaultActionRegistry', () => {
 		expect(sent).toBe('raw:abc')
 	})
 
+	test('prefix action sends data then opens combo picker', async () => {
+		const registry = createDefaultActionRegistry()
+		const sent: string[] = []
+		let pickerOptions: { title?: string; description?: string } | null = null
+
+		await registry.execute(
+			{ type: 'prefix', data: '\x02' },
+			{
+				term: mockTerminal(),
+				kbWasOpen: false,
+				focusIfNeeded() {},
+				async sendText(data: string) {
+					sent.push(data)
+				},
+				openComboPicker(options) {
+					pickerOptions = options
+				},
+			},
+		)
+
+		expect(sent).toEqual(['\x02'])
+		expect(pickerOptions).toMatchObject({
+			title: expect.stringContaining('Ctrl-B'),
+			description: expect.stringContaining('C-x = Ctrl+x'),
+		})
+	})
+
+	test('prefix action falls back to focus when picker unavailable', async () => {
+		const registry = createDefaultActionRegistry()
+		const sent: string[] = []
+		let focused = false
+
+		await registry.execute(
+			{ type: 'prefix', data: '\x02' },
+			{
+				term: mockTerminal(),
+				kbWasOpen: false,
+				focusIfNeeded() {
+					focused = true
+				},
+				async sendText(data: string) {
+					sent.push(data)
+				},
+			},
+		)
+
+		expect(sent).toEqual(['\x02'])
+		expect(focused).toBe(true)
+	})
+
+	test('prefix action serialises with send queue', async () => {
+		const registry = createDefaultActionRegistry()
+		const sent: string[] = []
+
+		const context = {
+			term: mockTerminal(),
+			kbWasOpen: false,
+			focusIfNeeded() {},
+			async sendText(data: string) {
+				if (data === '\x02') {
+					await new Promise((resolve) => setTimeout(resolve, 10))
+				}
+				sent.push(data)
+			},
+			openComboPicker() {},
+		}
+
+		const first = registry.execute({ type: 'prefix', data: '\x02' }, context)
+		const second = registry.execute({ type: 'send', data: 'q' }, context)
+		await Promise.all([first, second])
+
+		expect(sent).toEqual(['\x02', 'q'])
+	})
+
+	test('prefix combo follow-up uses raw sender', async () => {
+		const registry = createDefaultActionRegistry()
+		let sent = ''
+		let comboPromise: Promise<void> | null = null
+
+		await registry.execute(
+			{ type: 'prefix', data: '\x02' },
+			{
+				term: mockTerminal(),
+				kbWasOpen: false,
+				focusIfNeeded() {},
+				async sendText(_data: string) {},
+				async sendRawText(data: string) {
+					sent = `raw:${data}`
+				},
+				openComboPicker(options) {
+					comboPromise = options.sendText('r')
+				},
+			},
+		)
+
+		if (comboPromise) {
+			await comboPromise
+		}
+		expect(sent).toBe('raw:r')
+	})
+
 	test('combo-picker falls back to focus when picker unavailable', async () => {
 		const registry = createDefaultActionRegistry()
 		let focused = false

tests/buttons.test.ts

@@ -10,7 +10,7 @@ describe('defaultRow1', () => {
 	test('has tmux Prefix button', () => {
 		const prefix = defaultRow1.find((b) => b.id === 'tmux-prefix')
 		expect(prefix).toBeDefined()
-		expect(prefix?.action).toEqual({ type: 'send', data: '\x02' })
+		expect(prefix?.action).toEqual({ type: 'prefix', data: '\x02' })
 	})
 
 	test('has S-Tab after Tab', () => {

tests/combo-picker.test.ts

@@ -1,5 +1,66 @@
-import { describe, expect, test } from 'vitest'
-import { parseComboInput } from '../src/controls/combo-picker'
+import { GlobalRegistrator } from '@happy-dom/global-registrator'
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+import { createComboPicker, parseComboInput } from '../src/controls/combo-picker'
+
+beforeEach(() => {
+	GlobalRegistrator.register()
+})
+
+afterEach(() => {
+	GlobalRegistrator.unregister()
+})
+
+describe('createComboPicker', () => {
+	test('open with custom title and description sets DOM text', () => {
+		const picker = createComboPicker()
+		document.body.appendChild(picker.element)
+
+		picker.open({
+			async sendText() {},
+			focusIfNeeded() {},
+			title: 'After prefix',
+			description: 'Examples: r (reload), c (new window)',
+		})
+
+		const title = picker.element.querySelector('h3')
+		const desc = picker.element.querySelector('p')
+		expect(title?.textContent).toBe('After prefix')
+		expect(desc?.textContent).toBe('Examples: r (reload), c (new window)')
+	})
+
+	test('open without custom title uses defaults', () => {
+		const picker = createComboPicker()
+		document.body.appendChild(picker.element)
+
+		picker.open({
+			async sendText() {},
+			focusIfNeeded() {},
+		})
+
+		const title = picker.element.querySelector('h3')
+		const desc = picker.element.querySelector('p')
+		expect(title?.textContent).toBe('Send combo')
+		expect(desc?.textContent).toBe('Examples: C-s, C-[, M-Enter, Alt-x')
+	})
+
+	test('close resets title and description to defaults', () => {
+		const picker = createComboPicker()
+		document.body.appendChild(picker.element)
+
+		picker.open({
+			async sendText() {},
+			focusIfNeeded() {},
+			title: 'Custom',
+			description: 'Custom desc',
+		})
+		picker.close()
+
+		const title = picker.element.querySelector('h3')
+		const desc = picker.element.querySelector('p')
+		expect(title?.textContent).toBe('Send combo')
+		expect(desc?.textContent).toBe('Examples: C-s, C-[, M-Enter, Alt-x')
+	})
+})
 
 describe('parseComboInput', () => {
 	test('parses Ctrl letter combos', () => {