feat(mobile): shell keyboard bar with a one-shot Ctrl modifier (#262)

The mobile accessory bar was built around coding-agent commands, so a shell
session had no way to send Ctrl chords at all.

A shell-mode session now gets its own bar automatically: Ctrl, Esc, Tab,
four arrows, paste, dismiss. Agent sessions (claude, codex, opencode,
gemini, antigravity) keep the existing bar unchanged.

Ctrl is a one-shot modifier: tap it and it lights up, the next character
typed on the system keyboard is sent as its control byte, and Ctrl disarms.
Tapping it again cancels. That puts Ctrl+C/D/Z/R/L/A/E/W/U/K on a
nine-button bar without a button per chord.

Implementation notes:

* The interception lives in terminal.onData, not a keydown handler: a
  virtual keyboard reports no usable key events, so the character only
  exists as onData text. It sits after shouldSuppressTerminalQueryResponse
  (xterm answers DA/CPR queries through onData too, and letting one of those
  spend the modifier would silently eat the user's Ctrl) and before every
  send path, so the control byte follows the normal control-char route.
* ctrlByteFor() maps `code & 0x1f` over @A-Z[\]^_ and a-z, plus
  Ctrl+Space = NUL and Ctrl+? = DEL. Characters with no control equivalent
  pass through unchanged, like a hardware keyboard.
* The bar now separates the base layout (the extendedKeyboardBar setting)
  from the effective one, resolved per session by refreshForActiveSession().
  A settings save during a shell session cannot yank the bar away, and
  switching back to an agent tab restores the user's choice.
* Ctrl disarms on use, a second tap, any other accessory key, a session
  switch, keyboard dismissal and a layout swap.
* Ctrl joins the refocus set, so tapping it keeps the terminal focused and
  the keyboard open.
* The armed style needs three classes to outrank mobile.css's light-skin
  .accessory-btn rule at (0,2,1).

Verified end to end against a real shell session on an isolated instance:
tapping Ctrl then typing c interrupted a running `sleep 300` (^C in the
pane), the modifier disarmed, plain typing stayed literal, Ctrl+L cleared,
and a cancelled Ctrl typed a literal c.

Tests: test/mobile-shell-keyboard.test.ts (new, runs in CI) covers the
mapping table, layout selection per session mode, base-mode memory and every
disarm path; test/mobile/keyboard.test.ts adds nine browser regressions that
drive the real xterm with page.keyboard.type() and assert on the bytes that
would go out.

Closes #262

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Codeman maintainer
2026-08-10 03:09:44 +02:00
parent c942bb5dfb
commit 9b9f2c21e9
8 changed files with 728 additions and 7 deletions
+344
View File
@@ -0,0 +1,344 @@
/**
* @fileoverview Shell-specific mobile keyboard bar and its one-shot Ctrl
* modifier (issue #262).
*
* The bar is a `const` singleton in a non-module script, so it is loaded with
* `vm` against a small fake DOM (no jsdom in this repo), the same approach as
* test/path-picker-ui.test.ts. What matters here is the state machine: which
* layout a session gets, when the modifier arms, what byte a keystroke turns
* into, and every path that must disarm it. Behavior against a real shell
* (Ctrl+C reaching the PTY) is covered in test/mobile/keyboard.test.ts.
*/
import { readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import vm from 'node:vm';
import { describe, expect, it, vi } from 'vitest';
const keyboardSource = readFileSync(resolve('src/web/public/keyboard-accessory.js'), 'utf8');
const terminalSource = readFileSync(resolve('src/web/public/terminal-ui.js'), 'utf8');
type FakeButton = {
dataset: { action: string };
classList: { has: Set<string>; toggle(name: string, on: boolean): void; contains(name: string): boolean };
attrs: Record<string, string>;
setAttribute(name: string, value: string): void;
};
function fakeButton(action: string): FakeButton {
const has = new Set<string>();
return {
dataset: { action },
classList: {
has,
toggle(name: string, on: boolean) {
if (on) has.add(name);
else has.delete(name);
},
contains: (name: string) => has.has(name),
},
attrs: {},
setAttribute(name: string, value: string) {
this.attrs[name] = value;
},
};
}
/** Fake bar element: tracks the button set parsed out of the assigned HTML. */
function fakeBarElement() {
let html = '';
let buttons = new Map<string, FakeButton>();
const classes = new Set<string>();
return {
className: '',
classList: {
add: (name: string) => classes.add(name),
remove: (name: string) => classes.delete(name),
contains: (name: string) => classes.has(name),
},
get innerHTML() {
return html;
},
set innerHTML(next: string) {
html = next;
buttons = new Map();
for (const match of next.matchAll(/data-action="([^"]+)"/g)) {
buttons.set(match[1], fakeButton(match[1]));
}
},
get actions() {
return [...buttons.keys()];
},
querySelector(selector: string) {
const match = /\[data-action="([^"]+)"\]/.exec(selector);
return match ? (buttons.get(match[1]) ?? null) : null;
},
addEventListener: vi.fn(),
};
}
type Bar = {
element: ReturnType<typeof fakeBarElement>;
_mode: string;
init(): void;
setMode(mode: string): void;
refreshForActiveSession(): void;
handleAction(action: string, btn?: unknown): void;
isCtrlArmed(): boolean;
toggleCtrl(): void;
clearCtrl(): void;
consumeCtrl(data: string): string;
ctrlByteFor(char: string): string | null;
hide(): void;
show(): void;
};
function loadBar(sessionMode = 'claude') {
const app = {
activeSessionId: 'session-1',
sessions: new Map<string, { mode: string }>([['session-1', { mode: sessionMode }]]),
terminal: { focus: vi.fn() },
};
const fetchMock = vi.fn(() => Promise.resolve({ ok: true, catch: () => {} }));
const barElement = fakeBarElement();
const context = vm.createContext({
app,
MobileDetection: { isTouchDevice: () => true },
URLSearchParams,
fetch: fetchMock,
document: {
createElement: () => barElement,
querySelector: () => ({ parentNode: { insertBefore: vi.fn() } }),
},
setTimeout: (fn: () => void) => {
fn();
return 1;
},
clearTimeout: vi.fn(),
});
vm.runInContext(`${keyboardSource}\nglobalThis.__bar = KeyboardAccessoryBar;`, context, {
filename: 'keyboard-accessory.js',
});
const bar = (context as unknown as { __bar: Bar }).__bar;
bar.init();
return { app, bar, barElement, fetchMock };
}
describe('ctrlByteFor: character to control byte', () => {
const { bar } = loadBar();
it.each([
['c', '\x03'], // interrupt
['d', '\x04'], // EOF
['z', '\x1a'], // suspend
['r', '\x12'], // reverse search
['l', '\x0c'], // clear
['a', '\x01'],
['e', '\x05'],
['w', '\x17'],
['u', '\x15'],
['k', '\x0b'],
])('maps %s to its control byte', (char, byte) => {
expect(bar.ctrlByteFor(char)).toBe(byte);
});
it('maps uppercase the same as lowercase (Ctrl+C == Ctrl+c)', () => {
expect(bar.ctrlByteFor('C')).toBe('\x03');
expect(bar.ctrlByteFor('D')).toBe('\x04');
});
it('maps the punctuation controls a terminal defines', () => {
expect(bar.ctrlByteFor('@')).toBe('\x00');
expect(bar.ctrlByteFor('[')).toBe('\x1b'); // Ctrl+[ is Escape
expect(bar.ctrlByteFor('\\')).toBe('\x1c');
expect(bar.ctrlByteFor(']')).toBe('\x1d');
expect(bar.ctrlByteFor('^')).toBe('\x1e');
expect(bar.ctrlByteFor('_')).toBe('\x1f');
expect(bar.ctrlByteFor(' ')).toBe('\x00'); // Ctrl+Space = NUL
expect(bar.ctrlByteFor('?')).toBe('\x7f'); // Ctrl+? = DEL
});
it('returns null for characters with no control equivalent', () => {
// A hardware keyboard types these straight through under Ctrl.
for (const char of ['1', '9', '.', ',', '/', '-', '=', 'é']) {
expect(bar.ctrlByteFor(char)).toBeNull();
}
expect(bar.ctrlByteFor('ab')).toBeNull();
expect(bar.ctrlByteFor('')).toBeNull();
});
});
describe('shell keyboard bar selection', () => {
it('gives a shell session the terminal bar', () => {
const { bar, barElement } = loadBar('shell');
bar.refreshForActiveSession();
expect(bar._mode).toBe('shell');
expect(barElement.actions).toEqual([
'ctrl',
'esc',
'tab',
'scroll-up',
'scroll-down',
'arrow-left',
'arrow-right',
'paste',
'dismiss',
]);
});
it.each(['claude', 'codex', 'opencode', 'gemini', 'antigravity'])('leaves a %s session on the agent bar', (mode) => {
const { bar, barElement } = loadBar(mode);
bar.refreshForActiveSession();
expect(bar._mode).toBe('simple');
expect(barElement.actions).toContain('init');
expect(barElement.actions).not.toContain('ctrl');
});
it('remembers the extended-bar preference across a shell session', () => {
const { app, bar, barElement } = loadBar('claude');
bar.setMode('extended');
expect(bar._mode).toBe('extended');
app.sessions.set('shell-1', { mode: 'shell' });
app.activeSessionId = 'shell-1';
bar.refreshForActiveSession();
expect(bar._mode).toBe('shell');
// Settings saved while the shell bar is up must not yank it away...
bar.setMode('extended');
expect(bar._mode).toBe('shell');
// ...and switching back to the agent session restores the user's choice.
app.activeSessionId = 'session-1';
bar.refreshForActiveSession();
expect(bar._mode).toBe('extended');
expect(barElement.actions).toContain('compact');
});
it('falls back to the agent bar with no active session', () => {
const { app, bar } = loadBar('shell');
app.activeSessionId = null as unknown as string;
bar.refreshForActiveSession();
expect(bar._mode).toBe('simple');
});
});
describe('one-shot Ctrl modifier', () => {
function shellBar() {
const loaded = loadBar('shell');
loaded.bar.refreshForActiveSession();
return loaded;
}
it('is disarmed until the Ctrl key is tapped', () => {
const { bar } = shellBar();
expect(bar.isCtrlArmed()).toBe(false);
expect(bar.consumeCtrl('c')).toBe('c');
});
it('arms visibly and rewrites the next character as its control byte', () => {
const { bar, barElement } = shellBar();
bar.handleAction('ctrl');
expect(bar.isCtrlArmed()).toBe(true);
const button = barElement.querySelector('[data-action="ctrl"]')!;
expect(button.classList.contains('armed')).toBe(true);
expect(button.attrs['aria-pressed']).toBe('true');
expect(bar.consumeCtrl('c')).toBe('\x03');
// One shot: spent, and the button says so.
expect(bar.isCtrlArmed()).toBe(false);
expect(button.classList.contains('armed')).toBe(false);
expect(button.attrs['aria-pressed']).toBe('false');
expect(bar.consumeCtrl('c')).toBe('c');
});
it('sends Ctrl+D for the next key too', () => {
const { bar } = shellBar();
bar.handleAction('ctrl');
expect(bar.consumeCtrl('d')).toBe('\x04');
});
it('cancels on a second tap of Ctrl', () => {
const { bar, barElement } = shellBar();
bar.handleAction('ctrl');
bar.handleAction('ctrl');
expect(bar.isCtrlArmed()).toBe(false);
expect(barElement.querySelector('[data-action="ctrl"]')!.classList.contains('armed')).toBe(false);
expect(bar.consumeCtrl('c')).toBe('c');
});
it('passes a character with no control byte through unchanged, spending the modifier', () => {
const { bar } = shellBar();
bar.handleAction('ctrl');
expect(bar.consumeCtrl('7')).toBe('7');
expect(bar.isCtrlArmed()).toBe(false);
});
it('spends the modifier on a paste instead of leaving it armed for the next keystroke', () => {
const { bar } = shellBar();
bar.handleAction('ctrl');
expect(bar.consumeCtrl('git status')).toBe('git status');
expect(bar.isCtrlArmed()).toBe(false);
});
it('is cancelled by any other accessory key', () => {
const { bar } = shellBar();
bar.handleAction('ctrl');
bar.handleAction('esc');
expect(bar.isCtrlArmed()).toBe(false);
});
it('is cancelled by a session switch', () => {
const { app, bar } = shellBar();
bar.handleAction('ctrl');
expect(bar.isCtrlArmed()).toBe(true);
app.sessions.set('shell-2', { mode: 'shell' });
app.activeSessionId = 'shell-2';
bar.refreshForActiveSession();
// Same layout, but the modifier must not survive into the next session.
expect(bar._mode).toBe('shell');
expect(bar.isCtrlArmed()).toBe(false);
});
it('is cancelled when the keyboard is dismissed', () => {
const { bar } = shellBar();
bar.handleAction('ctrl');
bar.hide();
expect(bar.isCtrlArmed()).toBe(false);
});
it('drops the armed state when the layout is swapped out from under it', () => {
const { app, bar } = shellBar();
bar.handleAction('ctrl');
app.sessions.set('agent-1', { mode: 'claude' });
app.activeSessionId = 'agent-1';
bar.refreshForActiveSession();
expect(bar._mode).toBe('simple');
expect(bar.isCtrlArmed()).toBe(false);
expect(bar.consumeCtrl('c')).toBe('c');
});
});
describe('terminal input wiring', () => {
it('applies the modifier in onData after the query-response filter and before the send paths', () => {
const hook = terminalSource.indexOf('KeyboardAccessoryBar.consumeCtrl(data)');
const queryFilter = terminalSource.indexOf('shouldSuppressTerminalQueryResponse(data)', hook - 4000);
const firstSend = terminalSource.indexOf('this._lastTerminalData', hook - 4000);
expect(hook).toBeGreaterThan(0);
// xterm answers DA/CPR queries through onData as well; letting one of those
// spend the modifier would silently eat the user's Ctrl.
expect(queryFilter).toBeGreaterThan(0);
expect(queryFilter).toBeLessThan(hook);
// Every send path (local echo, predictive echo, plain flush) reads `data`
// after this point, so the control byte reaches the PTY unchanged.
expect(firstSend).toBeGreaterThan(hook);
});
it('guards the hook so a page without the bar (desktop) still types normally', () => {
expect(terminalSource).toContain("typeof KeyboardAccessoryBar !== 'undefined'");
});
});
+153
View File
@@ -1048,6 +1048,159 @@ describe('Virtual Keyboard', () => {
});
});
// ── Shell keyboard bar + one-shot Ctrl (issue #262) ───────────────────
//
// The bar swaps layouts per session mode, and Ctrl is a one-shot modifier
// applied to the next character typed on the SYSTEM keyboard, which on a
// phone reaches the app as xterm onData text, not a key event. These drive
// the real xterm instance with page.keyboard.type() and assert on what would
// go out on the wire (_sendInputAsync), not on DOM state alone.
describe('Shell keyboard bar', () => {
let context: BrowserContext;
let page: Page;
beforeAll(async () => {
({ context, page } = await createDevicePage(REPRESENTATIVE_DEVICES['standard-phone'], BASE_URL, 'chromium'));
await page.waitForTimeout(WAIT.PAGE_SETTLE);
});
afterAll(async () => {
await context.close();
});
/** Point the app at a fake session of `mode` and re-resolve the bar. */
async function activateSession(mode: string, id = 'kb-shell-1'): Promise<void> {
await page.evaluate(`(function (id, mode) {
app.sessions.set(id, { id, name: id, status: 'idle', mode, workingDir: '/tmp' });
app.activeSessionId = id;
KeyboardAccessoryBar.show();
KeyboardAccessoryBar.refreshForActiveSession();
})('${id}', '${mode}')`);
}
/** Capture what the terminal would send, while typing on the real keyboard. */
async function typeAndCapture(text: string): Promise<string[]> {
await page.evaluate(`(function () {
window.__sent = [];
if (!app.__origSend) app.__origSend = app._sendInputAsync;
app._sendInputAsync = function (sessionId, input) { window.__sent.push(input); };
app.terminal.focus();
})()`);
await page.keyboard.type(text);
await page.waitForTimeout(200);
const sent = (await page.evaluate(`window.__sent`)) as string[];
await page.evaluate(`(function () { app._sendInputAsync = app.__origSend; })()`);
return sent;
}
async function tapCtrl(): Promise<void> {
await page.evaluate(`document.querySelector('.keyboard-accessory-bar [data-action="ctrl"]').click()`);
}
it('shows the terminal bar for shell sessions', async () => {
await activateSession('shell');
const actions = await page.evaluate(() =>
Array.from(document.querySelectorAll('.keyboard-accessory-bar [data-action]')).map(
(button) => (button as HTMLElement).dataset.action
)
);
expect(actions).toEqual([
'ctrl',
'esc',
'tab',
'scroll-up',
'scroll-down',
'arrow-left',
'arrow-right',
'paste',
'dismiss',
]);
});
it('keeps the command bar for agent sessions', async () => {
await activateSession('claude', 'kb-agent-1');
const actions = await page.evaluate(() =>
Array.from(document.querySelectorAll('.keyboard-accessory-bar [data-action]')).map(
(button) => (button as HTMLElement).dataset.action
)
);
expect(actions).toContain('init');
expect(actions).not.toContain('ctrl');
});
it('sends Ctrl+C for the next typed character and disarms', async () => {
await activateSession('shell');
await tapCtrl();
expect(await page.evaluate(`KeyboardAccessoryBar.isCtrlArmed()`)).toBe(true);
expect(await typeAndCapture('c')).toEqual(['\x03']);
expect(await page.evaluate(`KeyboardAccessoryBar.isCtrlArmed()`)).toBe(false);
// The very next keystroke is a literal c again.
expect(await typeAndCapture('c')).toEqual(['c']);
});
it('sends Ctrl+D for the next typed character', async () => {
await activateSession('shell');
await tapCtrl();
expect(await typeAndCapture('d')).toEqual(['\x04']);
});
it('cancels on a second tap of Ctrl', async () => {
await activateSession('shell');
await tapCtrl();
await tapCtrl();
expect(await page.evaluate(`KeyboardAccessoryBar.isCtrlArmed()`)).toBe(false);
expect(await typeAndCapture('c')).toEqual(['c']);
});
it('shows the armed state and keeps the terminal focused', async () => {
await activateSession('shell');
await tapCtrl();
const state = await page.evaluate(() => {
const button = document.querySelector('.keyboard-accessory-bar [data-action="ctrl"]') as HTMLElement;
const style = getComputedStyle(button);
return {
armed: button.classList.contains('armed'),
pressed: button.getAttribute('aria-pressed'),
background: style.backgroundColor,
focusedTerminal: document.activeElement === (app.terminal as { textarea: Element }).textarea,
};
});
expect(state.armed).toBe(true);
expect(state.pressed).toBe('true');
// Armed styling must actually land (three-class rule beating the skin
// overrides): an invisible modifier is worse than none.
expect(state.background).not.toBe('rgba(0, 0, 0, 0)');
expect(state.focusedTerminal).toBe(true);
});
it('drops the armed modifier when switching sessions', async () => {
await activateSession('shell');
await tapCtrl();
expect(await page.evaluate(`KeyboardAccessoryBar.isCtrlArmed()`)).toBe(true);
await activateSession('shell', 'kb-shell-2');
expect(await page.evaluate(`KeyboardAccessoryBar.isCtrlArmed()`)).toBe(false);
expect(await typeAndCapture('c')).toEqual(['c']);
});
it('drops the armed modifier when the keyboard is dismissed', async () => {
await activateSession('shell');
await tapCtrl();
await page.evaluate(`KeyboardAccessoryBar.hide()`);
expect(await page.evaluate(`KeyboardAccessoryBar.isCtrlArmed()`)).toBe(false);
});
it('spends the modifier on another accessory key instead of the next keystroke', async () => {
await activateSession('shell');
await tapCtrl();
await page.evaluate(`document.querySelector('.keyboard-accessory-bar [data-action="esc"]').click()`);
expect(await page.evaluate(`KeyboardAccessoryBar.isCtrlArmed()`)).toBe(false);
expect(await typeAndCapture('c')).toEqual(['c']);
});
});
// ── Cross-device keyboard behavior ────────────────────────────────────
describe('Cross-device keyboard behavior', () => {