fix(web): forward the wheel for any CLI whose registry entry asks for it

The browser's wheel gate named copilot, pi, claude and codex by id, so a custom clis.json entry that launches pi could not get the forwarding #771 gave stock pi: after every tab switch or reload its wheel scrolled an empty local buffer. Copying pi's altScreen value into such an entry made it worse, since the mouse DECSETs were then stripped while nothing forwarded the wheel.

The server now publishes every CLI's wheelForward rule as window.__codemanWheelForward, disabled entries included because disabling a CLI leaves its sessions running, and _shouldForwardWheelToApp reads that map instead of an id list. Stock CLIs keep their behaviour, and a minVersion that is not MAJOR.MINOR.PATCH refuses forwarding instead of comparing as passing.
This commit is contained in:
JD committed 2026-11-17 00:43:09 -05:00
1 parent e99b42c387
commit 3ef4900e60
12 files changed
+251 -37

No files matched your search

+11 -6
View File
@@ -596,10 +596,14 @@ export interface CliCapabilities {
* Forwarding the wheel to the CLI's own transcript. 'never' keeps local scrollback;
* 'version-gated' forwards from `minVersion` on; 'always' forwards at any version. Either
* forwarding mode applies only while the CLI has mouse tracking on (`cliMouseTracking`).
* Read by the browser's gate (`_shouldForwardWheelToApp` in terminal-ui.js) through
* `window.__codemanWheelForward`, which the server builds from this field for every CLI
* whose mode is not `never`, disabled ones included (their running sessions stay open).
*
* ⚠️ Declared only: nothing reads this field yet (see DECLARED-FOR-LATER below). The browser's
* gate is `_shouldForwardWheelToApp` in terminal-ui.js, which keeps its own hand-written
* per-CLI rules, so changing a value here changes nothing until that gate is changed too.
* ⚠️ `cliMouseTracking` is only ever set for a CLI whose mouse DECSETs the server strips
* (`altScreen: 'strip-full'` or `'strip-mux-and-mouse'`), so a forwarding mode on any other
* `altScreen` never forwards: xterm keeps the DECSETs and encodes the wheel itself, until a
* replay drops its mouse mode.
*/
wheelForward: { mode: 'never' | 'version-gated' | 'always'; minVersion?: string };
/**
@@ -1009,14 +1013,15 @@ export interface CliOverlays {
/**
* ⚠️ DECLARED-FOR-LATER: fields no code reads yet.
*
* `accent`, `overlays.credStore`, `capabilities.echo`, `capabilities.wheelForward`,
* `capabilities.keyboardAccessory` and `capabilities.maxFrameBytes` all describe FRONTEND
* `accent`, `overlays.credStore`, `capabilities.echo`, `capabilities.keyboardAccessory` and
* `capabilities.maxFrameBytes` all describe FRONTEND
* behaviour, and most of the frontend is deliberately untouched by the change that introduced
* this registry — `app.js`, `terminal-ui.js`, `styles.css` and friends keep their own
* hand-authored per-CLI rules, and moving them is its own piece of work with its own way of
* being verified (a mobile/browser suite the CI gate cannot see). `shortBadge` graduated out of
* this list (docs/cli-enable-disable-plan.md, Phase 2): `GET /api/clis` reads it for the
* CLI-management Settings list.
* CLI-management Settings list, and so did `capabilities.wheelForward`, which the browser's wheel
* gate reads through `window.__codemanWheelForward`.
*
* They are declared now because each entry should describe its CLI completely, and because
* transcribing them while the hand-written source is still on screen is when the values are
+29 -23
View File
@@ -6016,12 +6016,16 @@ Object.assign(CodemanApp.prototype, {
// True when a parsed CLI version string ('2.1.187' — banner-parsed on the
// server, delivered via session:cliInfo / SessionState.cliVersion) is known
// AND >= the minimum. Unknown or unparseable versions return false so
// callers keep the conservative behavior.
// callers keep the conservative behavior, and so does an unparseable
// minimum: it can come from a user's clis.json (`wheelForward.minVersion`).
_cliVersionAtLeast(version, minimum) {
if (typeof version !== 'string') return false;
const parts = version.trim().replace(/^v/, '').split('.').map(Number);
if (parts.length !== 3 || parts.some((n) => !Number.isFinite(n))) return false;
const min = minimum.split('.').map(Number);
const parse = (v) => {
const m = typeof v === 'string' ? /^v?(\d+)\.(\d+)\.(\d+)$/.exec(v.trim()) : null;
return m ? m.slice(1).map(Number) : null;
};
const parts = parse(version);
const min = parse(minimum);
if (!parts || !min) return false;
for (let i = 0; i < 3; i++) {
if (parts[i] !== min[i]) return parts[i] > min[i];
}
@@ -6081,24 +6085,26 @@ Object.assign(CodemanApp.prototype, {
if (mode && mode !== 'none') return false;
const session = this.sessions?.get(target.sessionId || this.activeSessionId);
const sessionMode = session?.mode || 'claude';
// GitHub Copilot CLI (and pi, fullscreen by default) scrolls its own transcript on SGR wheel
// reports (checked with xterm encoding them natively). Their mouse DECSETs are stripped
// server-side so a drag selects locally (strip-mux-and-mouse), which also means xterm no longer
// encodes the wheel: send the same reports by hand, but only while the CLI is actually tracking
// the mouse. Not gated on a version. On Copilot a stale-false flag falls through to the
// PageUp/PageDown fallback like claude's; pi has none on purpose (the `transcriptPageKeys` note
// in stock.ts), so there the wheel does nothing until the flag is back.
if (sessionMode === 'copilot' || sessionMode === 'pi') return session?.cliMouseTracking === true;
if (sessionMode !== 'claude' && sessionMode !== 'codex') return false;
if (sessionMode === 'claude' && !this._cliVersionAtLeast(session?.cliVersion, '2.1.187')) return false;
// Only while Claude or Codex is actually listening for the mouse. Claude's
// inline renderer (2.1.280 measured: alternate_on=0, mouse_any_flag=0), like
// older inline Codex, keeps its transcript in real scrollback; SGR reports are
// ignored, so forwarding made every swipe and wheel tick dead. Fullscreen
// (CLAUDE_CODE_NO_FLICKER=1, or "tui": "fullscreen" in ~/.claude/settings.json)
// turns on alt-screen + mode 1003/1006, which the server records as
// cliMouseTracking. A stale-false flag after a server restart falls through
// to _maybePageCliTranscript, so it never goes dead.
// Which CLIs scroll their own transcript on SGR wheel reports is the registry's
// `wheelForward` rule, published by renderIndexHtml as `window.__codemanWheelForward`
// (id -> rule, `never` left out; a page rendered without the map forwards nothing), so a
// custom clis.json entry shaped like pi forwards under its own id. Stock: claude from
// 2.1.187 (older versions take the wheel as menu navigation), codex, copilot and pi always.
// Their mouse DECSETs are stripped server-side (a drag selects locally), so xterm never
// encodes the wheel for them and the reports are sent by hand.
const rule = window.__codemanWheelForward?.[sessionMode];
if (!rule || (rule.mode !== 'always' && rule.mode !== 'version-gated')) return false;
if (rule.mode === 'version-gated' && !this._cliVersionAtLeast(session?.cliVersion, rule.minVersion)) return false;
// Only while the CLI is actually listening for the mouse. Claude's inline renderer
// (2.1.280 measured: alternate_on=0, mouse_any_flag=0), like older inline Codex and pi's
// `tuiMode: regular`, keeps its transcript in real scrollback; SGR reports are ignored, so
// forwarding made every swipe and wheel tick dead. Fullscreen (CLAUDE_CODE_NO_FLICKER=1, or
// "tui": "fullscreen" in ~/.claude/settings.json; pi's default since 1.0.0) turns on
// alt-screen + mouse tracking, which the server records as cliMouseTracking. That flag is
// what survives a tab switch or reload, where xterm's own mouse mode does not. A stale-false
// flag falls through to _maybePageCliTranscript (PageUp/PageDown for a CLI declaring
// `transcriptPageKeys`); pi declares none on purpose (the note in stock.ts), so there the
// wheel does nothing until the flag is back.
if (session?.cliMouseTracking !== true) return false;
// Deliberately NOT gated on _terminalViewportAtBottom(). It used to be, so
// that leaving the bottom handed the wheel back to local scrollback and both
+13
View File
@@ -2133,6 +2133,19 @@ export class WebServer extends EventEmitter {
'</head>',
() => `<script>window.__codemanKeyboardHoldModes=${JSON.stringify(keyboardHoldClis)};</script>\n</head>`
);
// Which run modes take the wheel as SGR reports while they track the mouse
// (`_shouldForwardWheelToApp`), keyed by id with the `wheelForward` rule itself, so a
// custom clis.json entry shaped like pi forwards under its own id. `never` is left out.
// Disabled entries are kept (`listClis`, not `enabledClis`): disabling a CLI never ends
// its running sessions, and their wheel must keep working across a reload.
// `minVersion` is a free string a user's clis.json sets, hence the script escaper.
const wheelForwardClis = Object.fromEntries(
listClis()
.filter((entry) => entry.capabilities.wheelForward.mode !== 'never')
.map((entry) => [entry.id, entry.capabilities.wheelForward])
);
const wheelForwardJson = escapeScriptJson(JSON.stringify(wheelForwardClis));
html = html.replace('</head>', () => `<script>window.__codemanWheelForward=${wheelForwardJson};</script>\n</head>`);
if (!soloSessionId && process.env.CODEMAN_GESTURE === '1') {
html = html.replace('</head>', () => `<script>window.__codemanGestureAvailable=true;</script>\n</head>`);
if (settings.gestureControlEnabled === true) {