Compare commits

..
Author SHA1 Message Date
Codeman maintainer c8ac04662d fix(mobile): apply the one-shot Ctrl on the CJK input path too
onData is not the only way keystrokes reach the PTY. With cjkInputEnabled
on, the CJK textarea owns the keyboard: onData returns early for
everything it swallows, and the focus router even redirects
terminal.focus() into the field, which is exactly where the accessory bar
sends focus after every key. So an armed modifier could neither fire NOR
be spent there — it survived until a session switch or keyboard dismissal
and then turned an innocent keystroke into a control byte, the failure
mode the whole disarm list exists to prevent.

`_handleCjkInput()` is that module's single choke point to the PTY, so
applying the modifier there covers typed characters, IME flushes, Enter,
backspace and arrows in one place, with the same policy as the onData
hook: the next single character is modified, anything longer merely
spends it. A committed CJK word therefore passes through untouched and
still clears the modifier.

Verified against a real shell session with the CJK field focused and
owning input (cjkActive true, focus in #cjkInput). Before: typing c left
a literal c in the pane, `sleep 300` kept running, and Ctrl stayed armed.
After: ^C in the pane, modifier disarmed, plain typing still literal.

Tests: 5 cases driving the real _handleCjkInput against the real bar,
both loaded into one vm scope (the bar is a const singleton, so a shared
script scope is what makes the bare reference resolve). Removing the fix
fails 3 of them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 04:25:31 +02:00
Codeman maintainer 7c2a49d432 fix(mobile): keep the one-shot Ctrl armed through terminal-generated reports
Review of #268 turned up two defects, both verified against a real shell
session on an isolated instance.

1. A tap spent the modifier. The onData hook consumed every chunk while
   armed, but not every chunk is a keystroke: a shell session keeps the
   narrow scrollback strip, so mouse DECSETs reach the browser, and with
   vim/htop running a tap arrives as `\x1b[<0;31;23M`. Measured in the
   real app: armed, one tap, disarmed, and the Ctrl button read as dead.
   The hook now skips mouse and focus reports via a new
   `CodemanTerminalInput.isTerminalFocusOrMouseReport()`; they still reach
   the PTY, they just no longer stand in for the next key. Focus reports
   are covered for the same reason even though FOCUS_ESCAPE_FILTER in
   session.ts strips DECSET 1004 today, since the bar refocuses the
   terminal after every key and would spend the modifier on its own
   `\x1b[I` the moment that filter changed.

2. The armed style did not land on the four light skins. The competing
   rule is (0,3,1), not (0,2,1) as the comments claimed: `:is()` takes the
   specificity of its most specific argument and that list holds
   `.btn-toolbar.btn-shell`, so it outranked the (0,3,0) armed rules in
   both stylesheets. Measured across all seven skins at 390px, armed and
   resting backgrounds were byte-identical on paper-gray, solarized-light,
   catppuccin-latte and rose-pine-dawn. The light-skin rule now excludes
   the state as `.accessory-btn:not(.armed)`, which fixes phone and tablet
   at once; adding another class to the armed rules would only have moved
   the tie.

Tests: 20 more cases in test/mobile-shell-keyboard.test.ts (the report
classifier, the gate's effect on the modifier, and a static guard on the
light-skin selector, since the existing E2E background assertion passes on
a light skin and the browser suite runs the dark default), plus a browser
regression that taps the terminal with mouse reporting on.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-10 04:07:19 +02:00
Codeman maintainer 9b9f2c21e9 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>
2026-08-10 03:09:44 +02:00
11 changed files with 1054 additions and 385 deletions
+2 -2
View File
@@ -252,8 +252,6 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
**Entrance animations** (`entrance-animations.js`, all OFF by default): opt-in animations for the four things that appear when work starts, chosen per surface via `data-tab-anim` / `data-term-anim` / `data-win-anim` / `data-line-anim` on `<html>`. Defaults are the `legacy` theme, so an untouched install behaves exactly as before and every hook short-circuits on its first line. ⚠️ Tabs and connection lines are **destroyed mid-animation** on every re-render (`_fullRenderSessionTabs()` replaces the strip's innerHTML; `_updateConnectionLinesImmediate()` does `svg.innerHTML = ''`), so both are tracked by id and re-applied to the fresh element with a **negative `animation-delay`** to resume rather than restart. ⚠️ The terminal-pane styles may animate **transform / opacity / clip-path only**, xterm's FitAddon derives rows+cols from `getComputedStyle(parent).width/height`, so animating width/height/padding there would resize the PTY. ⚠️ Window styles other than `beam` transform the window, which moves the rect its connection line is aimed at; `beam` deliberately animates opacity/filter only so its line can draw toward a stable target. Persisted to its own `codeman:*Anim` localStorage keys (per-device, deliberately NOT in the `.strict()` `SettingsUpdateSchema`); picker in App Settings → Appearance, full per-surface lab at `?animlab=1`.
**Mobile tab strip scrolling** (issue #257): under 768px the tab strip is a horizontal scroller (desktop wraps to a second row instead), so the active tab can sit off-screen. Three rules keep it reachable and they only work together: `_updateActiveTabImmediate()` scrolls the selected tab into view via `computeTabScrollLeft()` (pure, in constants.js) using **rect math on the strip's own `scrollLeft`**, never `scrollIntoView()`, which would also scroll the document under a fixed header; `_fullRenderSessionTabs()` **restores `scrollLeft`** across the `innerHTML` rebuild, since ambient rebuilds (a task badge appearing, a session created elsewhere) otherwise snap a mid-swipe strip back to 0; and it re-reveals the active tab **only when it changed** (`_lastRenderedActiveTabId`), so browsing the far end of the strip is not undone by background renders. ⚠️ Mobile no longer hoists the active session to the front of the strip: that reordering ran on full renders only, so tab order flipped depending on which render path fired, and it renumbered the Alt+N badges. Scroll-into-view replaces it; do not reintroduce it.
**Phone overview home screen** (`mobile-overview.js`, phones only, per-device `mobileOverviewEnabled`, default ON): under 430px the "C" logo shows a session overview (NEEDS YOU / CURRENT SESSIONS / PAST SESSIONS) instead of the welcome overlay; tablet and desktop are unchanged. The branch lives in `showWelcome()`/`hideWelcome()` (terminal-ui.js) behind `shouldUseMobileOverview()`, which is **width-driven** (`getDeviceType() === 'mobile'`) because this is a layout decision, unlike the settings namespace which stays handheld-based. ⚠️ The container ships with the `hidden` attribute and only this module removes it: never give `.mobile-overview` a bare `display` rule, since desktop does not load `mobile.css` (`media="(max-width: 1023px)"`) and would then render it unstyled. Live re-renders ride on the tail of `_renderSessionTabsImmediate()` (every state change it needs already funnels there); PAST rows come from one `_fetchUnifiedSessions(60)` per home-screen visit and resume through the shared `resumeHistorySession()`, so they behave exactly like the welcome screen's Resume list. ⚠️ Two things must stay in lockstep with surfaces outside this module, because divergence reads as a bug rather than a style: the split Run button carries the **toolbar's own classes** (`btn-toolbar btn-run mode-<backend>` / `btn-run-gear`) so the per-backend gradient and the light-skin overrides apply unchanged (mobile.css must therefore set no `background`/`color` on it), and row status uses the **session-tab language** (green dot when fine, `pulse` while working, yellow blinking row when waiting for input, red blinking row when a question is pending, mirroring `tab-alert-idle`/`tab-alert-action`). The picker mirrors the toolbar run-mode menu (`setRunMode()` + `run()`, `openWebviewFromMenu()` for saved dashboards) and deliberately omits its Recent-Sessions block, since PAST SESSIONS is that. Status pills carry `data-i18n-skip` (generic words like "idle" collide with state strings elsewhere).
**Desktop home tab column** (`home-sessions.js`, desktop only): the welcome overlay centers ~560px of content in a ~1400px window, so its left gutter is dead space; it now carries the open tabs as a vertical list. Rows are in **tab order**, not sorted by urgency like the phone overview, because the row badges are the Alt+1..9 indices. State classification is REUSED from mobile-overview.js (`_mobileOverviewState`/`_mobileOverviewCaseFor`), which is why the module loads after it. ⚠️ The column is `position: absolute` so the centered content never moves, which is exactly why it needs a **width gate in two places** — `HOME_SESSIONS_MIN_WIDTH` (1180) in the JS plus a `max-width: 1179px` media query as the backstop for a resize that outruns the matchMedia listener; drift between them means a column overlapping the search panel, and `test/home-sessions.test.ts` pins them equal. ⚠️ `.home-sessions` is `display: flex`, so `[hidden]` must be re-asserted as `display: none` or the module's only visibility lever does nothing. Working state is deliberately byte-identical to the phone's: pulsing green dot + the `tab-load-spin` ring reused from the tab strip + the same green halo (added to `.mobile-overview-dot--working` at the same time), so "working" reads the same on every surface. Live re-renders ride the tail of `_renderSessionTabsImmediate()` alongside the phone overview.
@@ -272,6 +270,8 @@ Frontend JS modules have `@fileoverview` with `@dependency`/`@loadorder` tags. L
**WebGL renderer toggle** (`webglRendererEnabled`, per-device): the GPU-stall watchdog's sticky `codeman-webgl-disabled` marker survives page loads and is cleared only by an explicit OFF→ON save or `?webgl=force`. `?nowebgl` forces the DOM renderer per-load. → [architecture-invariants#webgl-renderer-toggle](docs/architecture-invariants.md#webgl-renderer-toggle)
**Shell keyboard accessory bar + one-shot Ctrl** (issue #262, `keyboard-accessory.js`): a **shell**-mode session automatically swaps the mobile accessory bar for terminal controls (Ctrl, Esc, Tab, four arrows, paste, dismiss); every other mode keeps the agent bar. `setMode()` now records the user's `extendedKeyboardBar` preference as the **base** layout and `refreshForActiveSession()` (called from `selectSession`) resolves base-vs-shell, so a settings save during a shell session cannot yank the bar away and switching back restores the user's choice. ⚠️ **Ctrl is a ONE-SHOT modifier applied in `terminal.onData`, not in a keydown handler**: a virtual keyboard emits no usable key events, so the character only exists as onData text. The hook sits AFTER `shouldSuppressTerminalQueryResponse` (xterm answers DA/CPR through onData too, and one of those would silently spend the modifier) and BEFORE every send path, so the control byte follows the normal control-char route. ⚠️ **Not every onData chunk is a keystroke**, and the query filter is not enough on its own: xterm ALSO emits mouse and focus reports on its own initiative, so the hook skips them via `isTerminalFocusOrMouseReport()` (they still reach the PTY, they just don't count as the next key). The mouse half is live — a shell session keeps the NARROW strip, so mouse DECSETs reach the browser and one tap while vim/htop runs spent the armed modifier silently (measured). The focus half is defense in depth: `FOCUS_ESCAPE_FILTER` in `session.ts` strips `\x1b[?1004h` from every PTY read, so `sendFocusMode` never turns on today; if it ever did, the bar's own post-key refocus would emit `\x1b[I` and eat the modifier before the user typed. ⚠️ It must disarm on ALL of: use, second tap, any other accessory key, session switch, keyboard dismissal, and a layout swap; a modifier left armed turns the next innocent keystroke into a control byte. ⚠️ **onData is not the only input path** — with `cjkInputEnabled` on, the CJK textarea owns the keyboard (onData returns early for everything it swallows, and the focus router sends `terminal.focus()` there, which is where the bar refocuses after every key), so `_handleCjkInput()` applies the modifier too. It is that module's single choke point to the PTY, so one call covers typed characters, IME flushes, Enter, backspace and arrows. Without it an armed modifier could neither fire NOR be spent, and survived to a later keystroke. Mapping is `ctrlByteFor()` (`code & 0x1f` over @A-Z[\]^_ and a-z, plus Ctrl+Space=NUL / Ctrl+?=DEL); characters with no control equivalent pass through unchanged, like a hardware keyboard. ⚠️ The armed style is `.accessory-btn.accessory-btn-ctrl.armed` (0,3,0) in BOTH stylesheets, and it cannot outrank mobile.css's light-skin repaint at **(0,3,1)** (`:is()` inherits its most specific argument, and that list holds `.btn-toolbar.btn-shell`) — so that rule excludes the state by hand as `.accessory-btn:not(.armed)`. Without the exclusion the armed button renders identically to a resting one on all four light skins, which is worse than no armed style at all.
**Phone toolbar: Enter replaces Shell** (post-1.8.0): inside `@media (max-width: 430px)` `btn-shell` is `display:none` and `btn-enter` takes its slot (`order: 4`); starting a shell moved into the Run dropdown (`Terminal / Shell` → `setRunMode('shell')` → `run()` → `runShell()`, button label "Run SH"). `runMode` is `z.string().max(20)` server-side, so new modes need no schema change. Desktop and tablet keep the green Run Shell button unchanged.
⚠️ **`sendEnterKey()` MUST go through `terminal._core.coreService.triggerDataEvent('\r', true)`** — not `sendInput()`, and never a raw POST to `/api/sessions/:id/input`. `localEchoEnabled` defaults to `MobileDetection.isTouchDevice()`, so on every phone the characters you type are buffered in the `LocalEchoOverlay` and have **never reached the PTY**; the `onData` Enter branch in terminal-ui.js is what flushes `pendingText` first and only then sends `\r` (after an 80ms delay so text lands first). Sending a bare `\r` submits an empty line and strands the typed text on screen, so the button looks dead. Replaying the keypress reuses the overlay flush, the flushed-offset cleanup and the ordering instead of reimplementing them. `KeyboardAccessory.sendKey()` is for escape sequences (arrows/Esc) and is the WRONG template to copy for input.
+16 -84
View File
@@ -848,9 +848,11 @@ class CodemanApp {
SwipeHandler.init();
VoiceInput.init();
KeyboardAccessoryBar.init();
// Apply keyboard bar mode from settings
// Apply keyboard bar mode from settings. Always set it (not only when the
// extended bar is on) so the bar's remembered agent-session layout matches
// the setting before the first shell session swaps in the terminal bar.
const _kbSettings = this.loadAppSettingsFromStorage();
if (_kbSettings.extendedKeyboardBar) KeyboardAccessoryBar.setMode('extended');
KeyboardAccessoryBar.setMode(_kbSettings.extendedKeyboardBar ? 'extended' : 'simple');
this.applyHeaderVisibilitySettings();
this.restorePlanUsageChip();
this.applySkin();
@@ -3461,54 +3463,6 @@ class CodemanApp {
tab.classList.remove('active');
}
}
// #257: selection used to stop at the class toggle. On phones/tablets the
// strip scrolls horizontally, so a tab selected from the palette, a swipe,
// Alt+N or a push notification could stay parked off-screen.
this._scrollActiveTabIntoView(sessionId);
}
/**
* Scroll the tab strip so the given (default: active) tab is visible.
*
* Only phones/tablets scroll the strip (desktop wraps to a second row), and
* the pure policy no-ops whenever there is nothing to scroll, so this is a
* cheap call on every device.
*
* Deliberately NOT scrollIntoView(): that also scrolls every scrollable
* ANCESTOR, which on a phone is the document itself. With the header fixed
* and the keyboard possibly open, a vertical nudge there shifts the whole
* app. Rect math + scrollLeft touches exactly one scroller.
*/
_scrollActiveTabIntoView(sessionId, behavior = 'smooth') {
const container = this.$('sessionTabs');
if (!container) return;
const tab =
(sessionId && container.querySelector(`.session-tab[data-id="${sessionId}"]`)) ||
container.querySelector('.session-tab.active');
if (!tab) return;
const policy = window.CodemanTabOverflow?.computeTabScrollLeft;
if (!policy) return;
const containerRect = container.getBoundingClientRect();
const tabRect = tab.getBoundingClientRect();
const target = policy({
scrollLeft: container.scrollLeft,
clientWidth: container.clientWidth,
scrollWidth: container.scrollWidth,
// Offsets are relative to the SCROLL CONTENT, not the offsetParent: the
// tabs' offsetParent is the positioned header, so offsetLeft would carry
// the brand column's width into the math.
tabLeft: tabRect.left - containerRect.left + container.scrollLeft,
tabWidth: tabRect.width,
});
if (Math.abs(target - container.scrollLeft) < 1) return;
const reduceMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches;
if (typeof container.scrollTo === 'function') {
container.scrollTo({ left: target, behavior: reduceMotion ? 'auto' : behavior });
} else {
container.scrollLeft = target;
}
}
_setTerminalLoadState(sessionId, selectGen, phase) {
@@ -3726,11 +3680,6 @@ class CodemanApp {
this._fullRenderSessionTabs();
}
// Keep the reveal-on-change bookkeeping honest when only the incremental
// branch ran: _updateActiveTabImmediate has already scrolled the new active
// tab into view, so the next full rebuild must not treat it as a change.
this._lastRenderedActiveTabId = this.activeSessionId;
this.updateTabOverflowMode();
// After the wrap measurement: the `unroll` style starts tabs at max-width 0,
// so measuring mid-animation would decide the wrap on collapsed widths.
@@ -3802,25 +3751,15 @@ class CodemanApp {
document.querySelectorAll('body > .subagent-dropdown').forEach(d => d.remove());
this.cancelHideSubagentDropdown();
// #257: replacing innerHTML below resets scrollLeft to 0. On phones the
// strip scrolls, and ambient rebuilds (a task badge appearing, a session
// created elsewhere) fire often enough that a user swiping toward the
// right-hand tabs kept getting yanked back to the first one. Remember
// where the strip was; the browser clamps the restore to the new content.
const prevScrollLeft = container.scrollLeft;
const prevActiveTabId = this._lastRenderedActiveTabId;
const isFirstRender = !container.querySelector('.session-tab');
// Build tabs HTML using array for better string concatenation performance.
// Iterate in sessionOrder to respect the user's custom tab arrangement, on
// EVERY device: mobile used to hoist the active session to the front, from
// when only one tab fit on screen. With five tabs it made the strip jump
// under the user's finger (and renumbered the Alt+N badges) on every full
// rebuild, while the incremental path left the order alone, so the order
// depended on which render path happened to run. Scrolling the active tab
// into view replaces it.
// Build tabs HTML using array for better string concatenation performance
// Iterate in sessionOrder to respect user's custom tab arrangement
// On mobile: put active session first (only one tab visible anyway)
const parts = [];
const tabOrder = this.sessionOrder;
let tabOrder = this.sessionOrder;
if (MobileDetection.getDeviceType() === 'mobile' && this.activeSessionId) {
// Reorder to put active tab first
tabOrder = [this.activeSessionId, ...this.sessionOrder.filter(id => id !== this.activeSessionId)];
}
let _tabIdx = 0;
for (const id of tabOrder) {
const session = this.sessions.get(id);
@@ -3889,17 +3828,6 @@ class CodemanApp {
container.innerHTML = parts.join('');
// Put the strip back where the user left it, then reveal the active tab
// only when it CHANGED (or on the first paint). Restoring unconditionally
// and revealing conditionally is what lets someone browse the far end of
// the strip while a background rebuild fires, without the active tab ever
// being stranded off-screen after a switch.
container.scrollLeft = prevScrollLeft;
this._lastRenderedActiveTabId = this.activeSessionId;
if (isFirstRender || prevActiveTabId !== this.activeSessionId) {
this._scrollActiveTabIntoView(this.activeSessionId, isFirstRender ? 'auto' : 'smooth');
}
// Set up drag-and-drop handlers for tab reordering
this.setupTabDragHandlers();
@@ -4531,6 +4459,10 @@ class CodemanApp {
this.loadAttachmentHistory?.(sessionId);
}
this._updateLocalEchoState();
// Shell sessions get the terminal keyboard bar, agent sessions the command
// bar (issue #262). Also disarms a one-shot Ctrl left over from the tab we
// just left, so it can never fire against the session we just opened.
if (typeof KeyboardAccessoryBar !== 'undefined') KeyboardAccessoryBar.refreshForActiveSession();
// Restore flushed offset AND text IMMEDIATELY so backspace/typing work during
// the async buffer load. Without this, the offset is 0 during the
-43
View File
@@ -156,47 +156,6 @@ function shouldAutoWrapTabs(input) {
return scrollWidth > clientWidth + 1;
}
// Sliver of the neighbouring tab left visible when the strip scrolls a tab into
// view. Landing a tab flush against the edge reads as "this is the last one";
// the gap is what tells the user there is more strip to swipe to.
const TAB_SCROLL_REVEAL_PX = 16;
// Phone/tablet tab-strip scroll policy (issue #257). Those breakpoints scroll
// the strip horizontally (desktop wraps to a second row instead and never
// scrolls), so the active tab can sit entirely outside the visible slice with
// no way back except a swipe the user may not know is possible.
//
// Returns the scrollLeft that puts the tab inside the window, clamped to the
// scrollable range, and returns the CURRENT scrollLeft when the tab is already
// visible: callers compare and skip the write, so an already-correct strip is
// never nudged. Pure: the caller measures, this decides.
function computeTabScrollLeft(input) {
const scrollWidth = Number(input?.scrollWidth) || 0;
const clientWidth = Number(input?.clientWidth) || 0;
const maxScroll = Math.max(0, scrollWidth - clientWidth);
if (maxScroll === 0 || clientWidth <= 0) return 0;
const pad = input?.padding == null ? TAB_SCROLL_REVEAL_PX : Number(input.padding) || 0;
const tabLeft = Number(input?.tabLeft) || 0;
const tabWidth = Number(input?.tabWidth) || 0;
const tabRight = tabLeft + tabWidth;
const viewLeft = Math.min(Math.max(Number(input?.scrollLeft) || 0, 0), maxScroll);
const viewRight = viewLeft + clientWidth;
let target = viewLeft;
if (tabWidth + pad >= clientWidth) {
// Tab is as wide as the window (long session name on a narrow phone):
// there is no position that shows all of it plus padding, so align its
// start, since the name matters more than the trailing badges.
target = tabLeft;
} else if (tabLeft - pad < viewLeft) {
target = tabLeft - pad;
} else if (tabRight + pad > viewRight) {
target = tabRight + pad - clientWidth;
}
return Math.min(Math.max(Math.round(target), 0), maxScroll);
}
// COD-134 — Terminal WebSocket reconnect policy.
//
// Decide what to do after a terminal WebSocket closes, given the close `code`
@@ -302,8 +261,6 @@ if (typeof window !== 'undefined') {
window.shouldSkipWebGL = shouldSkipWebGL;
window.CodemanTabOverflow = {
shouldAutoWrapTabs,
computeTabScrollLeft,
TAB_SCROLL_REVEAL_PX,
};
window.CodemanWsReconnect = {
plan: planWsReconnect,
+186 -5
View File
@@ -12,6 +12,13 @@
* Destructive actions (/clear, /compact, extended bar only) require double-tap confirmation (2s amber state).
* Commands are sent as text + Enter separately for Ink compatibility.
* Only initializes on touch devices (MobileDetection.isTouchDevice guard).
* SHELL sessions get their own layout automatically (issue #262): Ctrl, Esc, Tab,
* four arrows, paste, dismiss. Ctrl is a ONE-SHOT modifier: arm it, type a
* character on the system keyboard, and terminal-ui.js's onData hook swaps the
* character for its control byte (ctrlByteFor) and disarms. That is what makes
* Ctrl+C/D/Z/R/L/A/E/W/U/K reachable without a button per chord. It resets on
* use, on a second tap, on any other accessory key, on a session switch
* (refreshForActiveSession) and when the keyboard is dismissed (hide).
* - PathPicker (singleton object) — Lazy server-side file/folder browser shared
* by Link Existing and the extended mobile keyboard bar.
*
@@ -414,12 +421,58 @@ const PathPicker = {
// Mobile Keyboard Accessory Bar
// ═══════════════════════════════════════════════════════════════
/**
* Control byte a terminal sends for Ctrl+<char> (issue #262).
*
* Returns null for characters with no control equivalent (digits, most
* punctuation): the caller then sends the character unchanged, matching a
* hardware keyboard where Ctrl+7 just types "7".
*
* `code & 0x1f` covers both ranges a terminal maps: @A-Z[\]^_ (64-95 → 0-31)
* and a-z (97-122 → 1-26). Space and ? are the two conventional extras
* (Ctrl+Space = NUL, Ctrl+? = DEL) and can't come from the mask.
*/
function ctrlByteFor(char) {
if (typeof char !== 'string' || char.length !== 1) return null;
const code = char.charCodeAt(0);
if (code === 32) return '\x00';
if (code === 63) return '\x7f';
if ((code >= 64 && code <= 95) || (code >= 97 && code <= 122)) {
return String.fromCharCode(code & 0x1f);
}
return null;
}
/**
* Apply an armed one-shot Ctrl to one chunk of terminal input.
* Returns `{ data, consumed }`, where `consumed` tells the bar to disarm.
*
* Multi-character chunks (pastes, escape sequences, IME commits) have no
* single key to modify, but they still spend the modifier: leaving it armed
* would silently turn the NEXT innocent keystroke into a control byte.
*/
function applyOneShotCtrl(data) {
if (typeof data !== 'string' || data.length === 0) return { data, consumed: false };
if (data.length === 1) {
const byte = ctrlByteFor(data);
return { data: byte === null ? data : byte, consumed: true };
}
return { data, consumed: true };
}
/**
* KeyboardAccessoryBar - Quick action buttons shown above keyboard when typing.
*/
const KeyboardAccessoryBar = {
element: null,
_mode: 'simple', // 'simple' or 'extended'
// Layout currently in the DOM: 'simple' | 'extended' | 'shell'.
_mode: 'simple',
// Layout the user picked for AGENT sessions ('simple' | 'extended', the
// extendedKeyboardBar setting). Shell sessions override it with the shell
// bar; this is what we come back to when they switch to an agent tab.
_baseMode: 'simple',
// One-shot Ctrl modifier (shell bar only). See handleAction('ctrl').
_ctrlArmed: false,
/** HTML for simple mode: arrows, commands, paste, Esc, dismiss */
_simpleButtons: `
@@ -448,6 +501,45 @@ const KeyboardAccessoryBar = {
</svg>
</button>`,
/** HTML for shell mode (issue #262): terminal controls instead of agent
* commands. Ctrl is a one-shot modifier rather than one button per chord,
* which is what puts Ctrl+C/D/Z/R/L/A/E/W/U/K on a 9-button bar. */
_shellButtons: `
<button class="accessory-btn accessory-btn-ctrl" data-action="ctrl" title="Ctrl, then tap a key" aria-pressed="false">Ctrl</button>
<button class="accessory-btn" data-action="esc" title="Escape">Esc</button>
<button class="accessory-btn" data-action="tab" title="Tab">Tab</button>
<button class="accessory-btn accessory-btn-arrow" data-action="scroll-up" title="Arrow up">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
<path d="M5 15l7-7 7 7"/>
</svg>
</button>
<button class="accessory-btn accessory-btn-arrow" data-action="scroll-down" title="Arrow down">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
<path d="M19 9l-7 7-7-7"/>
</svg>
</button>
<button class="accessory-btn accessory-btn-arrow" data-action="arrow-left" title="Arrow left">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
<path d="M15 19l-7-7 7-7"/>
</svg>
</button>
<button class="accessory-btn accessory-btn-arrow" data-action="arrow-right" title="Arrow right">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
<path d="M9 5l7 7-7 7"/>
</svg>
</button>
<button class="accessory-btn" data-action="paste" title="Paste from clipboard">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
<path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/>
<rect x="8" y="2" width="8" height="4" rx="1" ry="1"/>
</svg>
</button>
<button class="accessory-btn accessory-btn-dismiss" data-action="dismiss" title="Dismiss keyboard">
<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
<path d="M19 9l-7 7-7-7"/>
</svg>
</button>`,
/** HTML for extended mode: all keys including arrows, Tab, Esc, etc. */
_extendedButtons: `
<button class="accessory-btn accessory-btn-arrow" data-action="scroll-up" title="Arrow up">
@@ -514,7 +606,7 @@ const KeyboardAccessoryBar = {
this.handleAction(action, btn);
// Refocus terminal so keyboard stays open (tap blurs terminal → keyboard dismisses → toolbar shifts)
const refocusActions = new Set(['scroll-up', 'scroll-down', 'arrow-left', 'arrow-right', 'tab', 'shift-tab', 'ctrl-o', 'opt-enter', 'esc', 'effort-max', 'clear-input']);
const refocusActions = new Set(['scroll-up', 'scroll-down', 'arrow-left', 'arrow-right', 'tab', 'shift-tab', 'ctrl', 'ctrl-o', 'opt-enter', 'esc', 'effort-max', 'clear-input']);
if (refocusActions.has(action) ||
((action === 'clear' || action === 'compact') && this._confirmAction)) {
if (typeof app !== 'undefined' && app.terminal) {
@@ -530,14 +622,91 @@ const KeyboardAccessoryBar = {
}
},
/** Switch between 'simple' and 'extended' button layouts */
/** Pick the layout the user wants for AGENT sessions ('simple' | 'extended',
* the extendedKeyboardBar setting). A shell session keeps the shell bar;
* the preference is remembered and applied on the next agent tab. */
setMode(mode) {
if (mode === this._mode || !this.element) return;
this._baseMode = mode === 'extended' ? 'extended' : 'simple';
this._applyLayout(this._resolveMode());
},
/** Re-resolve the layout after the active session changed (issue #262):
* shell sessions get the terminal bar, everything else the agent bar. Also
* disarms Ctrl, because a modifier armed on one session must never fire on
* the next one. */
refreshForActiveSession() {
this.clearCtrl();
this._applyLayout(this._resolveMode());
},
/** Which layout the current state calls for. */
_resolveMode() {
return this._isShellSession() ? 'shell' : this._baseMode;
},
_isShellSession() {
if (typeof app === 'undefined' || !app.activeSessionId) return false;
return app.sessions?.get(app.activeSessionId)?.mode === 'shell';
},
/** Swap the button set in the DOM. */
_applyLayout(mode) {
if (!this.element || mode === this._mode) return;
this._mode = mode;
this.clearConfirm();
this.element.innerHTML = mode === 'extended' ? this._extendedButtons : this._simpleButtons;
// Reset before the rewrite: _setCtrl() styles the button it can find, and
// the one holding the armed class is about to be replaced.
this.clearCtrl();
this.element.innerHTML =
mode === 'shell' ? this._shellButtons : mode === 'extended' ? this._extendedButtons : this._simpleButtons;
},
// ── One-shot Ctrl modifier (shell bar) ──────────────────────────────────
// Tap Ctrl, then type a character on the system keyboard: the character is
// replaced by its control byte and Ctrl disarms. Tapping Ctrl again cancels.
// The interception lives in the terminal onData handler (terminal-ui.js),
// which is where system-keyboard input arrives on a phone. A keydown hook
// would miss it, since virtual keyboards report no usable key events.
/** Is the one-shot Ctrl waiting for a key? */
isCtrlArmed() {
return this._ctrlArmed === true;
},
/** Arm/cancel the one-shot Ctrl (the Ctrl button toggles). */
toggleCtrl() {
this._setCtrl(!this._ctrlArmed);
},
/** Disarm: used by session switch, keyboard dismissal and every other key. */
clearCtrl() {
if (this._ctrlArmed) this._setCtrl(false);
},
_setCtrl(on) {
this._ctrlArmed = !!on;
const btn = this.element?.querySelector('[data-action="ctrl"]');
if (btn) {
btn.classList.toggle('armed', this._ctrlArmed);
btn.setAttribute('aria-pressed', this._ctrlArmed ? 'true' : 'false');
}
},
/**
* Apply an armed Ctrl to a chunk of typed input and disarm.
* Returns the data unchanged (and leaves the modifier alone) when Ctrl is
* not armed, so the caller can pipe every keystroke through it.
*/
consumeCtrl(data) {
if (!this._ctrlArmed) return data;
const result = applyOneShotCtrl(data);
if (result.consumed) this.clearCtrl();
return result.data;
},
/** Exposed for tests: pure char to control byte mapping. */
ctrlByteFor,
_confirmTimer: null,
_confirmAction: null,
@@ -545,7 +714,15 @@ const KeyboardAccessoryBar = {
handleAction(action, btn) {
if (typeof app === 'undefined' || !app.activeSessionId) return;
// Any key other than Ctrl itself spends the modifier. It is a one-shot for
// the next TYPED character, so an accessory key tapped in between (Esc, an
// arrow, paste) must not leave it armed to bite the keystroke after that.
if (action !== 'ctrl') this.clearCtrl();
switch (action) {
case 'ctrl':
this.toggleCtrl();
break;
case 'scroll-up':
this.sendKey('\x1b[A');
break;
@@ -784,6 +961,10 @@ const KeyboardAccessoryBar = {
/** Hide the accessory bar */
hide() {
// The bar goes away with the keyboard, so an armed Ctrl has nothing left
// to modify, and a modifier the user can no longer see must not survive
// to the next time they open the keyboard.
this.clearCtrl();
if (this.element) {
this.element.classList.remove('visible');
}
+20 -7
View File
@@ -115,17 +115,13 @@ html.mobile-init .file-browser-panel {
}
/* Compact session tabs — .tabs-two-rows override needed to match
specificity of .session-tabs.tabs-two-rows in styles.css (0,2,0).
overscroll-behavior-x keeps a swipe that runs past the last tab inside the
strip: chained to the page it becomes the browser's back gesture, which is
exactly the swipe someone makes reaching for the rightmost tabs (#257). */
specificity of .session-tabs.tabs-two-rows in styles.css (0,2,0) */
.session-tabs,
.session-tabs.tabs-two-rows {
flex-wrap: nowrap;
overflow-x: auto;
overflow-y: hidden;
-webkit-overflow-scrolling: touch;
overscroll-behavior-x: contain;
scrollbar-width: none;
max-height: 52px;
gap: 3px;
@@ -647,7 +643,6 @@ html.mobile-init .file-browser-panel {
overflow-x: auto;
overflow-y: hidden;
-webkit-overflow-scrolling: touch;
overscroll-behavior-x: contain;
scrollbar-width: none;
max-height: 36px;
gap: 2px;
@@ -1167,6 +1162,18 @@ html.mobile-init .file-browser-panel {
color: #ffd54f;
}
/* Armed one-shot Ctrl (shell bar, issue #262). Phone palette is hardcoded in
this block, so the state needs its own entry here. Three classes beat the
plain .accessory-btn rules; the light-skin rule at the bottom of this file
is higher still at (0,3,1) and is excluded by hand there, not outranked. */
.accessory-btn.accessory-btn-ctrl.armed {
background: #2563eb;
border-color: rgba(59, 130, 246, 0.9);
color: #fff;
font-weight: 700;
box-shadow: 0 0 0 2px rgba(59, 130, 246, 0.45);
}
.accessory-btn:active {
background: #3a3a3a;
}
@@ -2912,7 +2919,13 @@ html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="cat
color: var(--text);
}
html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-voice-mobile, .btn-settings-mobile, .btn-toolbar.btn-shell, .toolbar .btn-case-add, .accessory-btn) {
/* `.accessory-btn:not(.armed)` on purpose: this selector is (0,3,1) — `:is()`
takes the specificity of its most specific argument, and `.btn-toolbar
.btn-shell` is two classes — so it OUTRANKS the (0,3,0) armed-Ctrl rules in
both stylesheets and repainted the armed modifier back to a resting button on
all four light skins. Excluding the state here fixes phone and tablet at once;
adding a class to the armed rules would only have moved the tie. */
html:is([data-skin="paper-gray"], [data-skin="solarized-light"], [data-skin="catppuccin-latte"], [data-skin="rose-pine-dawn"]) :is(.btn-voice-mobile, .btn-settings-mobile, .btn-toolbar.btn-shell, .toolbar .btn-case-add, .accessory-btn:not(.armed)) {
background: var(--control-bg);
border-color: var(--control-border);
color: var(--text-dim);
+14
View File
@@ -12081,6 +12081,20 @@ body.touch-device.cjk-input-visible .main {
color: var(--yellow);
}
/* Armed one-shot Ctrl (shell bar, issue #262). Three classes on purpose, to beat
the plain .accessory-btn rules. It still cannot outrank the light-skin
compatibility rule in mobile.css, which repaints every .accessory-btn at
(0,3,1) — `:is()` inherits its most specific argument — so that rule excludes
`.armed` by hand. Without the exclusion the modifier looks unarmed on the four
light skins, which is worse than having no armed style at all. */
.accessory-btn.accessory-btn-ctrl.armed {
background: var(--accent);
border-color: var(--accent);
color: var(--accent-ink);
font-weight: 700;
box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 40%, transparent);
}
.accessory-btn:active {
background: var(--control-bg-hover);
}
+70
View File
@@ -15,6 +15,15 @@
(function (global) {
const TERMINAL_QUERY_RESPONSE_PATTERN = /^\x1b\[[\?>=]?[\d;]*[cnR]$/;
const TERMINAL_OSC_RESPONSE_PATTERN = /^\x1b\][\d;]*[^\x07\x1b]*(?:\x07|\x1b\\)$/;
// Pointer and focus reports xterm emits through onData on the terminal's OWN
// initiative, with no key pressed: SGR mouse (DECSET 1006, also 1016), legacy
// X10 mouse (DECSET 1000 — three raw bytes after CSI M) and focus in/out
// (DECSET 1004). They are not query REPLIES, so the query-response filter
// above does not match them, and they must keep reaching the PTY. What they
// must NOT do is stand in for a keystroke: see isTerminalFocusOrMouseReport.
const MOUSE_SGR_REPORT_PATTERN = /^\x1b\[<\d+;\d+;\d+[Mm]$/;
const MOUSE_X10_REPORT_PATTERN = /^\x1b\[M[\s\S]{3}$/;
const FOCUS_REPORT_PATTERN = /^\x1b\[[IO]$/;
// Grace window after a manual scroll-up gesture during which sticky-scroll is
// suppressed, so high-frequency Codex status redraws don't snap the viewport
// back to the bottom while the user is inspecting earlier output.
@@ -106,6 +115,30 @@
return isTerminalQueryResponse(data);
}
/**
* Did the terminal generate this chunk itself, rather than a human pressing a
* key? True for mouse and focus reports (issue #262).
*
* Consumers that treat one onData chunk as "the next keystroke" must skip
* these. The one-shot Ctrl modifier is why this exists, and the MOUSE half is
* the live one: a shell session keeps the narrow scrollback strip, so mouse
* DECSETs reach the browser and anything the user runs that enables tracking
* (vim, htop, less) turns a tap into `\x1b[<0;31;23M`. Measured in a real
* shell session: with Ctrl armed, one tap on the terminal spent it silently.
*
* Focus reports are the same class and cost nothing to cover, but they cannot
* reach xterm today: `FOCUS_ESCAPE_FILTER` in session.ts strips `\x1b[?1004h`
* (and the reports themselves) from every PTY read, so `sendFocusMode` never
* turns on. Were that filter to go, the Ctrl button would spend the modifier
* on its OWN refocus — the bar refocuses the terminal after every key so the
* keyboard stays open, and that refocus emits `\x1b[I`.
*/
function isTerminalFocusOrMouseReport(data) {
return (
FOCUS_REPORT_PATTERN.test(data) || MOUSE_SGR_REPORT_PATTERN.test(data) || MOUSE_X10_REPORT_PATTERN.test(data)
);
}
// Per-skin xterm.js palettes. The 'daylight-blue' object equals the legacy hardcoded
// theme, so default behavior is unchanged. Shared at module scope and exported on the
// global so both terminal-ui.js (main terminal) and panels-ui.js (teammate terminals,
@@ -134,6 +167,7 @@
global.CodemanTerminalInput = {
isTerminalQueryResponse,
shouldSuppressTerminalQueryResponse,
isTerminalFocusOrMouseReport,
isComposerNavKey,
classifyPredictInput,
isCodexComposerRow,
@@ -930,6 +964,28 @@ Object.assign(CodemanApp.prototype, {
) {
return;
}
// ── One-shot Ctrl (mobile shell bar, issue #262) ──
// A virtual keyboard reports no usable key events, so a keydown hook
// would never see the character the modifier applies to: it arrives
// here as onData text. Sits AFTER the query-response filter so xterm's
// own DA/CPR replies can never spend the modifier, and BEFORE every
// send path so the control byte follows the normal control-char route
// (immediate flush, local-echo state cleared).
//
// Mouse and focus reports are skipped rather than suppressed: they are
// real bytes the PTY still needs, they just were not typed by anyone.
// A shell session passes mouse DECSETs through, so with vim or htop
// running, one tap on the terminal used to spend the modifier silently
// (measured against a real shell). See isTerminalFocusOrMouseReport.
if (
typeof KeyboardAccessoryBar !== 'undefined' &&
KeyboardAccessoryBar.isCtrlArmed?.() &&
!window.CodemanTerminalInput?.isTerminalFocusOrMouseReport(data)
) {
data = KeyboardAccessoryBar.consumeCtrl(data);
}
this._lastTerminalData = { data, time: performance.now() };
// ── Local Echo Pass-through ──
@@ -2584,6 +2640,20 @@ Object.assign(CodemanApp.prototype, {
_crashDiag.log(`CJK send DROP no-session len=${text.length}`);
return;
}
// ── One-shot Ctrl (mobile shell bar, issue #262) ──
// While the CJK field is visible it OWNS the keyboard: onData returns early
// for everything it swallows, and the focus router even redirects
// terminal.focus() into it — which is where the accessory bar sends focus
// after every key. So the onData hook never sees these keystrokes, and an
// armed modifier could neither fire NOR be spent: it survived until a
// session switch and then turned an innocent keystroke into a control byte.
// This is the module's single choke point to the PTY, so applying it here
// covers typed characters, IME flushes, Enter, backspace and arrows at once.
// Same policy as the onData hook: the next single character is modified,
// anything longer merely spends the modifier.
if (typeof KeyboardAccessoryBar !== 'undefined' && KeyboardAccessoryBar.isCtrlArmed?.()) {
text = KeyboardAccessoryBar.consumeCtrl(text);
}
// Bypasses onData (like insertTerminalText): predictions cannot see this
if (this._localEchoPolicy === 'predict') this._predictiveEcho?.clearPredictions();
_crashDiag.log(`CJK send→${this.activeSessionId.slice(0, 8)} len=${text.length}`);
+567
View File
@@ -0,0 +1,567 @@
/**
* @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 TerminalInput = { isTerminalFocusOrMouseReport(data: string): boolean };
type TerminalModule = {
terminalInput: TerminalInput;
CodemanApp: { prototype: Record<string, (...args: never[]) => unknown> };
bar: Bar;
};
let terminalModule: TerminalModule | null = null;
/**
* terminal-ui.js in a vm, with the REAL accessory bar in the same script scope
* (it is a `const` singleton, so only a shared scope makes the bare
* `KeyboardAccessoryBar` reference in the CJK path resolve). Its IIFE only
* needs a window to hang `CodemanTerminalInput` on, but the rest of the file
* assigns to CodemanApp.prototype at top level, so constants.js + app.js load
* first — the same recipe as test/local-echo-codex-gating.test.ts.
*/
function loadTerminalModule(): TerminalModule {
if (terminalModule) return terminalModule;
const read = (file: string) => readFileSync(resolve(`src/web/public/${file}`), 'utf8');
const windowStub: Record<string, unknown> = { addEventListener: vi.fn(), removeEventListener: vi.fn() };
const context = vm.createContext({
console,
setInterval: vi.fn(),
clearInterval: vi.fn(),
setTimeout,
clearTimeout,
requestAnimationFrame: vi.fn(),
HTMLCanvasElement: class HTMLCanvasElement {},
WebSocket: { OPEN: 1 },
fetch: vi.fn(),
URLSearchParams,
document: { addEventListener: vi.fn(), documentElement: { dataset: {} }, getElementById: () => null },
localStorage: { length: 0, key: vi.fn(), getItem: vi.fn(), setItem: vi.fn(), removeItem: vi.fn() },
window: windowStub,
MobileDetection: { isTouchDevice: () => true, isHandheldDevice: () => false, getDeviceType: () => 'desktop' },
});
vm.runInContext(
`${read('constants.js')}\n${keyboardSource}\n${read('app.js')}\n${terminalSource}\n` +
`globalThis.__CodemanApp = CodemanApp; globalThis.__bar = KeyboardAccessoryBar;`,
context
);
const exported = context as unknown as { __CodemanApp: TerminalModule['CodemanApp']; __bar: Bar };
terminalModule = {
terminalInput: (windowStub as { CodemanTerminalInput?: TerminalInput }).CodemanTerminalInput!,
CodemanApp: exported.__CodemanApp,
bar: exported.__bar,
};
return terminalModule;
}
function loadTerminalInput(): TerminalInput {
return loadTerminalModule().terminalInput;
}
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'");
});
it('skips terminal-generated focus and mouse reports', () => {
// Pins the gate itself: without it the modifier is spent by the `\x1b[I`
// that the Ctrl button's own refocus emits (see the describe below).
expect(terminalSource).toContain('!window.CodemanTerminalInput?.isTerminalFocusOrMouseReport(data)');
});
});
describe('CodemanTerminalInput.isTerminalFocusOrMouseReport', () => {
const isReport = loadTerminalInput().isTerminalFocusOrMouseReport;
it.each([
['\x1b[I', 'focus in (DECSET 1004)'],
['\x1b[O', 'focus out (DECSET 1004)'],
['\x1b[<0;10;5M', 'SGR mouse press'],
['\x1b[<0;10;5m', 'SGR mouse release'],
['\x1b[<64;10;5M', 'SGR wheel up'],
['\x1b[M !!', 'legacy X10 mouse'],
])('classifies %j as terminal-generated (%s)', (data) => {
expect(isReport(data)).toBe(true);
});
it.each([
['c', 'a typed character'],
['\x03', 'a control byte'],
['\r', 'Enter'],
['\x1b', 'the Escape key'],
['\x1b[A', 'an arrow key'],
['\x1b[200~hi\x1b[201~', 'a bracketed paste'],
['\x1b[?1;2c', 'a DA reply'],
['I', 'the letter I'],
])('leaves %j alone (%s)', (data) => {
expect(isReport(data)).toBe(false);
});
});
describe('one-shot Ctrl vs terminal-generated reports', () => {
// The onData gate, as terminal-ui.js writes it. The wiring test above pins
// the real source; this proves the behavior the gate buys.
function feed(bar: Bar, data: string): string {
const isReport = loadTerminalInput().isTerminalFocusOrMouseReport;
return bar.isCtrlArmed() && !isReport(data) ? bar.consumeCtrl(data) : data;
}
function shellBar() {
const loaded = loadBar('shell');
loaded.bar.refreshForActiveSession();
return loaded;
}
it('survives a tap once an app in the pane turns mouse reporting on', () => {
const { bar } = shellBar();
// The live case: a shell session keeps the narrow scrollback strip, so mouse
// DECSETs reach the browser. Measured against a real shell with vim-style
// tracking on, one tap on the terminal spent the armed modifier silently.
bar.handleAction('ctrl');
expect(feed(bar, '\x1b[<0;10;5M')).toBe('\x1b[<0;10;5M');
expect(feed(bar, '\x1b[<0;10;5m')).toBe('\x1b[<0;10;5m');
expect(bar.isCtrlArmed()).toBe(true);
// ...so the character the user actually types is still the one modified.
expect(feed(bar, 'd')).toBe('\x04');
expect(bar.isCtrlArmed()).toBe(false);
});
it('survives a focus report, should one ever reach xterm', () => {
// Defense in depth: FOCUS_ESCAPE_FILTER (session.ts) strips `\x1b[?1004h`
// from every PTY read, so sendFocusMode never turns on today. If it did,
// the bar's own post-key refocus would emit `\x1b[I` and eat the modifier
// before the user typed a single character.
const { bar } = shellBar();
bar.handleAction('ctrl');
expect(feed(bar, '\x1b[I')).toBe('\x1b[I');
expect(bar.isCtrlArmed()).toBe(true);
expect(feed(bar, 'c')).toBe('\x03');
});
it('still spends the modifier on a paste, which is real input', () => {
const { bar } = shellBar();
bar.handleAction('ctrl');
expect(feed(bar, 'git status')).toBe('git status');
expect(bar.isCtrlArmed()).toBe(false);
});
});
describe('one-shot Ctrl through the CJK input field', () => {
// The CJK textarea swallows keystrokes before onData sees them, so the CJK
// send path needs the modifier applied too. These drive the REAL
// _handleCjkInput against the REAL bar, both loaded into one vm scope.
function cjkApp() {
const { CodemanApp, bar } = loadTerminalModule();
bar.clearCtrl();
const app = Object.create(CodemanApp.prototype) as {
activeSessionId: string;
_sendInputAsync: ReturnType<typeof vi.fn>;
_handleCjkInput(text: string): void;
};
app.activeSessionId = 'cjk-session';
app._sendInputAsync = vi.fn();
return { app, bar };
}
it('sends the control byte for a character typed into the CJK field', () => {
const { app, bar } = cjkApp();
bar.toggleCtrl();
app._handleCjkInput('c');
expect(app._sendInputAsync).toHaveBeenCalledWith('cjk-session', '\x03');
expect(bar.isCtrlArmed()).toBe(false);
});
it('leaves ordinary CJK input untouched when nothing is armed', () => {
const { app } = cjkApp();
app._handleCjkInput('你好');
expect(app._sendInputAsync).toHaveBeenCalledWith('cjk-session', '你好');
});
it('spends the modifier on a committed IME word instead of stranding it', () => {
// The gap this closes: with the field focused the modifier could neither
// fire nor be spent, so it survived to bite a later innocent keystroke.
const { app, bar } = cjkApp();
bar.toggleCtrl();
app._handleCjkInput('你好');
expect(app._sendInputAsync).toHaveBeenCalledWith('cjk-session', '你好');
expect(bar.isCtrlArmed()).toBe(false);
});
it('spends the modifier on Enter, like every other non-character key', () => {
const { app, bar } = cjkApp();
bar.toggleCtrl();
app._handleCjkInput('\r');
expect(app._sendInputAsync).toHaveBeenCalledWith('cjk-session', '\r');
expect(bar.isCtrlArmed()).toBe(false);
});
it('drops the input, and does not spend the modifier, with no active session', () => {
const { app, bar } = cjkApp();
(app as unknown as { activeSessionId: string | null }).activeSessionId = null;
bar.toggleCtrl();
app._handleCjkInput('c');
expect(app._sendInputAsync).not.toHaveBeenCalled();
expect(bar.isCtrlArmed()).toBe(true);
});
});
describe('armed styling survives the light-skin overrides', () => {
const mobileCss = readFileSync(resolve('src/web/public/mobile.css'), 'utf8');
it('excludes .armed from the light-skin .accessory-btn repaint', () => {
// That selector is (0,3,1): `:is()` takes the specificity of its most
// specific argument and the list holds `.btn-toolbar.btn-shell`. It
// therefore OUTRANKS the (0,3,0) armed rules in both stylesheets, and a
// bare `.accessory-btn` there paints the armed modifier back to a resting
// button on all four light skins (measured across every skin at 390px).
const lightSkinRule = mobileCss
.split('\n')
.find((line) => line.includes('[data-skin="paper-gray"]') && line.includes('.btn-voice-mobile,'));
expect(lightSkinRule).toBeDefined();
expect(lightSkinRule).toContain('.accessory-btn:not(.armed)');
});
it('keeps an armed rule in both stylesheets', () => {
// mobile.css hardcodes the phone palette, styles.css carries the
// skin-aware one for everything wider.
expect(mobileCss).toContain('.accessory-btn.accessory-btn-ctrl.armed');
expect(readFileSync(resolve('src/web/public/styles.css'), 'utf8')).toContain(
'.accessory-btn.accessory-btn-ctrl.armed'
);
});
});
+177
View File
@@ -1048,6 +1048,183 @@ 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('survives a terminal tap while the pane has mouse reporting on', async () => {
// A shell session keeps the narrow scrollback strip, so mouse DECSETs
// reach the browser: run vim or htop and xterm starts reporting taps
// through onData as \x1b[<0;31;23M. Those arrive on the same channel as
// typed characters, so a hook that treats every chunk as "the next
// keystroke" spends Ctrl on a tap and the button looks dead. Verified
// against a real shell session before this guard existed.
await activateSession('shell');
await page.evaluate(`app.terminal.write('\\x1b[?1000h\\x1b[?1006h')`);
await page.waitForTimeout(150);
await tapCtrl();
expect(await page.evaluate(`KeyboardAccessoryBar.isCtrlArmed()`)).toBe(true);
const box = await page.locator('.xterm-screen').first().boundingBox();
await page.touchscreen.tap(box!.x + box!.width / 2, box!.y + box!.height / 2);
await page.waitForTimeout(200);
expect(await page.evaluate(`KeyboardAccessoryBar.isCtrlArmed()`)).toBe(true);
expect(await typeAndCapture('c')).toEqual(['\x03']);
await page.evaluate(`app.terminal.write('\\x1b[?1000l\\x1b[?1006l')`);
});
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', () => {
-165
View File
@@ -183,171 +183,6 @@ describe('Tab Navigation', () => {
});
});
// ─── Tab Strip Scrolling (issue #257) ────────────────────────────────────
describe('Tab Strip Scrolling', () => {
/**
* Seed `count` real sessions and render the strip through the production
* code path (_fullRenderSessionTabs), so the tabs carry the real markup,
* widths and CSS rather than hand-built stand-ins.
*/
async function seedTabs(page: Page, count: number, activeIndex = 0): Promise<void> {
await page.evaluate(`(function (n, activeIndex) {
app.sessions.clear();
app.sessionOrder = [];
for (let i = 1; i <= n; i++) {
const id = 'scroll-sess-' + i;
app.sessions.set(id, { id, name: 'w' + i + '-project', status: 'idle', mode: 'claude', workingDir: '/tmp/p' + i });
app.sessionOrder.push(id);
}
app.activeSessionId = app.sessionOrder[activeIndex];
app._lastRenderedActiveTabId = null;
app._fullRenderSessionTabs();
})(${count}, ${activeIndex})`);
await page.waitForTimeout(200);
}
async function stripState(page: Page, sessionId: string) {
return page.evaluate(`(function (id) {
const c = document.getElementById('sessionTabs');
const tab = c.querySelector('.session-tab[data-id="' + id + '"]');
const cRect = c.getBoundingClientRect();
const tRect = tab ? tab.getBoundingClientRect() : null;
return {
scrollLeft: Math.round(c.scrollLeft),
maxScroll: Math.round(c.scrollWidth - c.clientWidth),
order: [...c.querySelectorAll('.session-tab[data-id]')].map((t) => t.dataset.id),
visible: tRect ? tRect.left >= cRect.left - 1 && tRect.right <= cRect.right + 1 : false,
};
})('${sessionId}')`) as Promise<{ scrollLeft: number; maxScroll: number; order: string[]; visible: boolean }>;
}
it('reveals a rightmost tab that selection would otherwise leave off-screen', async () => {
const { context, page } = await createDevicePage(standardPhone, BASE_URL, 'chromium');
try {
await page.waitForTimeout(WAIT.PAGE_SETTLE);
await seedTabs(page, 5);
const before = await stripState(page, 'scroll-sess-5');
// Precondition: the strip really does overflow and the last tab is hidden.
expect(before.maxScroll).toBeGreaterThan(0);
expect(before.visible).toBe(false);
// The selection path selectSession() uses (class toggle, no rebuild).
await page.evaluate(`(function () {
app.activeSessionId = 'scroll-sess-5';
app._updateActiveTabImmediate('scroll-sess-5');
})()`);
await page.waitForTimeout(600); // smooth scroll
const after = await stripState(page, 'scroll-sess-5');
expect(after.visible).toBe(true);
expect(after.scrollLeft).toBeGreaterThan(before.scrollLeft);
} finally {
await context.close();
}
});
it('scrolls back to reveal a leftmost tab', async () => {
const { context, page } = await createDevicePage(standardPhone, BASE_URL, 'chromium');
try {
await page.waitForTimeout(WAIT.PAGE_SETTLE);
await seedTabs(page, 5);
await page.evaluate(`document.getElementById('sessionTabs').scrollLeft = 9999`);
await page.evaluate(`(function () {
app.activeSessionId = 'scroll-sess-1';
app._updateActiveTabImmediate('scroll-sess-1');
})()`);
await page.waitForTimeout(600);
const after = await stripState(page, 'scroll-sess-1');
expect(after.visible).toBe(true);
expect(after.scrollLeft).toBe(0);
} finally {
await context.close();
}
});
it('keeps the scroll position across an ambient full re-render', async () => {
const { context, page } = await createDevicePage(standardPhone, BASE_URL, 'chromium');
try {
await page.waitForTimeout(WAIT.PAGE_SETTLE);
await seedTabs(page, 5);
// User swipes to the end of the strip, then a background rebuild fires
// (a task badge appearing forces the full-render path).
await page.evaluate(`document.getElementById('sessionTabs').scrollLeft = 9999`);
const scrolled = await stripState(page, 'scroll-sess-5');
expect(scrolled.scrollLeft).toBeGreaterThan(0);
await page.evaluate(`(function () {
app.sessions.get('scroll-sess-2').taskStats = { running: 2, total: 3 };
app._fullRenderSessionTabs();
})()`);
await page.waitForTimeout(200);
const after = await stripState(page, 'scroll-sess-5');
expect(after.scrollLeft).toBe(scrolled.scrollLeft);
} finally {
await context.close();
}
});
it('renders tabs in sessionOrder on phones instead of hoisting the active one', async () => {
const { context, page } = await createDevicePage(standardPhone, BASE_URL, 'chromium');
try {
await page.waitForTimeout(WAIT.PAGE_SETTLE);
await seedTabs(page, 5, 3); // 4th tab active
const state = await stripState(page, 'scroll-sess-4');
expect(state.order).toEqual([
'scroll-sess-1',
'scroll-sess-2',
'scroll-sess-3',
'scroll-sess-4',
'scroll-sess-5',
]);
// ...and the active tab is still brought into view by the render.
expect(state.visible).toBe(true);
} finally {
await context.close();
}
});
it('reaches the last tab with a horizontal touch drag', async () => {
const { context, page } = await createDevicePage(standardPhone, BASE_URL, 'chromium');
try {
await page.waitForTimeout(WAIT.PAGE_SETTLE);
await seedTabs(page, 5);
const cdp = await context.newCDPSession(page);
const box = await page.locator(SELECTORS.TABS_CONTAINER).boundingBox();
if (!box) throw new Error('tab strip not found');
const y = box.y + box.height / 2;
const startX = box.x + box.width * 0.85;
const endX = box.x + box.width * 0.1;
await cdp.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: [{ x: startX, y }] });
for (let i = 1; i <= 10; i++) {
await cdp.send('Input.dispatchTouchEvent', {
type: 'touchMove',
touchPoints: [{ x: startX + ((endX - startX) * i) / 10, y }],
});
await page.waitForTimeout(16);
}
await cdp.send('Input.dispatchTouchEvent', { type: 'touchEnd', touchPoints: [] });
await page.waitForTimeout(400);
const after = await stripState(page, 'scroll-sess-5');
expect(after.scrollLeft).toBeGreaterThan(0);
expect(after.visible).toBe(true);
} finally {
await context.close();
}
});
});
// ─── Swipe Navigation (CDP - Chromium) ───────────────────────────────────
describe('Swipe Navigation (CDP - Chromium)', () => {
+2 -79
View File
@@ -3,28 +3,12 @@ import { resolve } from 'node:path';
import vm from 'node:vm';
import { describe, expect, it } from 'vitest';
type ScrollInput = {
scrollLeft?: number;
clientWidth?: number;
scrollWidth?: number;
tabLeft?: number;
tabWidth?: number;
padding?: number;
};
function loadTabOverflowHelper() {
const context = vm.createContext({ window: {}, globalThis: {} });
const source = readFileSync(resolve(import.meta.dirname, '../src/web/public/constants.js'), 'utf8');
vm.runInContext(source, context, { filename: 'constants.js' });
return (
context.window as {
CodemanTabOverflow: {
shouldAutoWrapTabs: (input: unknown) => boolean;
computeTabScrollLeft: (input: ScrollInput) => number;
TAB_SCROLL_REVEAL_PX: number;
};
}
).CodemanTabOverflow;
return (context.window as { CodemanTabOverflow: { shouldAutoWrapTabs: (input: unknown) => boolean } })
.CodemanTabOverflow;
}
describe('tab overflow layout policy', () => {
@@ -79,64 +63,3 @@ describe('tab overflow layout policy', () => {
expect(helper.shouldAutoWrapTabs({ ...base, tabCount: 1, scrollWidth: 1400, clientWidth: 760 })).toBe(false);
});
});
// Issue #257: the phone tab strip scrolls horizontally, so the active tab can
// sit entirely outside the visible slice. These pin the scroll target math that
// _scrollActiveTabIntoView() feeds with measured rects.
describe('mobile tab strip scroll-into-view policy', () => {
// A 5-tab phone strip: 335px visible of 558px of tabs.
const strip = { clientWidth: 335, scrollWidth: 558 };
const pad = 16;
it('scrolls right to reveal a tab past the right edge, leaving the reveal sliver', () => {
const helper = loadTabOverflowHelper();
// Last tab: 458..558, strip parked at 0.
const target = helper.computeTabScrollLeft({ ...strip, scrollLeft: 0, tabLeft: 458, tabWidth: 100 });
// 558 + 16 - 335 = 239, clamped to the 223px maximum.
expect(target).toBe(223);
// The revealed tab is now inside the window.
expect(458).toBeGreaterThanOrEqual(target);
expect(558).toBeLessThanOrEqual(target + strip.clientWidth);
});
it('scrolls left to reveal a tab before the left edge', () => {
const helper = loadTabOverflowHelper();
// First tab: 0..150, strip scrolled to the end.
expect(helper.computeTabScrollLeft({ ...strip, scrollLeft: 223, tabLeft: 0, tabWidth: 150 })).toBe(0);
// A middle tab partially cut off on the left: reveal it with the sliver.
expect(helper.computeTabScrollLeft({ ...strip, scrollLeft: 223, tabLeft: 200, tabWidth: 100 })).toBe(200 - pad);
});
it('leaves an already-visible tab alone (callers skip the write)', () => {
const helper = loadTabOverflowHelper();
expect(helper.computeTabScrollLeft({ ...strip, scrollLeft: 100, tabLeft: 152, tabWidth: 100 })).toBe(100);
});
it('never scrolls a strip that fits, and never leaves the scrollable range', () => {
const helper = loadTabOverflowHelper();
// Everything fits: nothing to scroll, whatever the tab geometry says.
expect(
helper.computeTabScrollLeft({ clientWidth: 900, scrollWidth: 400, scrollLeft: 0, tabLeft: 300, tabWidth: 100 })
).toBe(0);
// Clamped at both ends.
const low = helper.computeTabScrollLeft({ ...strip, scrollLeft: 40, tabLeft: 4, tabWidth: 100 });
expect(low).toBe(0);
const high = helper.computeTabScrollLeft({ ...strip, scrollLeft: 0, tabLeft: 500, tabWidth: 58 });
expect(high).toBeLessThanOrEqual(strip.scrollWidth - strip.clientWidth);
});
it('aligns the start of a tab too wide to fit the window', () => {
const helper = loadTabOverflowHelper();
// 330px tab in a 335px window: no position shows it plus padding.
expect(
helper.computeTabScrollLeft({ clientWidth: 335, scrollWidth: 900, scrollLeft: 0, tabLeft: 400, tabWidth: 330 })
).toBe(400);
});
it('tolerates missing measurements instead of producing NaN', () => {
const helper = loadTabOverflowHelper();
expect(helper.computeTabScrollLeft({})).toBe(0);
expect(helper.computeTabScrollLeft(undefined as unknown as ScrollInput)).toBe(0);
expect(helper.TAB_SCROLL_REVEAL_PX).toBe(pad);
});
});