From b5a356dadfde511dbf16228d9d2fdb85c5a812e5 Mon Sep 17 00:00:00 2001 From: JD Date: Thu, 19 Nov 2026 02:39:47 -0500 Subject: [PATCH] docs(cli-registry): say a version-gated wheel rule needs gates to forward A version-gated rule reads the session's cliVersion, which the server probes only for an entry that declares capabilities.gates, so a custom entry with version-gated and no gates never forwards. Also brings the claude and copilot comments in line with the code that now reads them. --- docs/cli-registry.md | 2 +- src/config/cli-registry/stock.ts | 8 ++++---- src/config/cli-registry/types.ts | 4 ++++ 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/cli-registry.md b/docs/cli-registry.md index b1c4f11c..4ca92ba1 100644 --- a/docs/cli-registry.md +++ b/docs/cli-registry.md @@ -310,7 +310,7 @@ Everything else in the interface is live, including `overlays.remote` / `overlay ### Wheel forwarding for a custom full-screen CLI -`capabilities.wheelForward` reaches the browser as `window.__codemanWheelForward` (id to rule, every CLI whose mode is not `never`, disabled ones included, since disabling a CLI leaves its running sessions open), and `_shouldForwardWheelToApp` in terminal-ui.js reads only that map, so a custom entry gets the same wheel as a stock one under its own id. A full-screen TUI that turns mouse tracking on itself (a wrapper around pi, for example) needs two values in its `clis.json` entry, the ones stock pi carries: `"altScreen": "strip-mux-and-mouse"` (the server strips its mouse DECSETs and publishes `cliMouseTracking`, and a drag selects locally) and `"wheelForward": { "mode": "always" }` (the wheel goes to the CLI as SGR reports while that flag is on). With the custom-entry defaults (`strip-mux-only`, `never`) the DECSETs reach xterm, which handles the wheel only until a tab switch or reload replays the pane without them; from then on the wheel scrolls an empty local buffer. ⚠️ Saving the entry from the Settings form rebuilds its capabilities from those defaults, so both values have to be set again in the file after an edit there. +`capabilities.wheelForward` reaches the browser as `window.__codemanWheelForward` (id to rule, every CLI whose mode is not `never`, disabled ones included, since disabling a CLI leaves its running sessions open), and `_shouldForwardWheelToApp` in terminal-ui.js reads only that map, so a custom entry gets the same wheel as a stock one under its own id. A full-screen TUI that turns mouse tracking on itself (a wrapper around pi, for example) needs two values in its `clis.json` entry, the ones stock pi carries: `"altScreen": "strip-mux-and-mouse"` (the server strips its mouse DECSETs and publishes `cliMouseTracking`, and a drag selects locally) and `"wheelForward": { "mode": "always" }` (the wheel goes to the CLI as SGR reports while that flag is on). With the custom-entry defaults (`strip-mux-only`, `never`) the DECSETs reach xterm, which handles the wheel only until a tab switch or reload replays the pane without them; from then on the wheel scrolls an empty local buffer. Use `always` rather than `version-gated` for such an entry: a `version-gated` rule forwards only when the session has a `cliVersion`, and the server probes one only for an entry that declares `capabilities.gates` (`cliNeedsVersionProbe` in `session.ts`), so a custom entry with `version-gated` and no gates never forwards, and nothing says why. ⚠️ Saving the entry from the Settings form rebuilds its capabilities from those defaults, so both values have to be set again in the file after an edit there. ## Consumers outside the server diff --git a/src/config/cli-registry/stock.ts b/src/config/cli-registry/stock.ts index d62379fd..97e8bf05 100644 --- a/src/config/cli-registry/stock.ts +++ b/src/config/cli-registry/stock.ts @@ -303,8 +303,8 @@ const CLAUDE: CliEntry = { transcript: 'claude-jsonl', altScreen: 'strip-full', echo: { policy: 'buffer', anchor: { kind: 'glyph', glyph: '❯', offset: 2 } }, - // Declared-for-later: the live rule (`_shouldForwardWheelToApp`, terminal-ui.js) is this version - // AND the server-published `cliMouseTracking` flag (#498), so wiring this field up needs both. + // Read by `_shouldForwardWheelToApp` (terminal-ui.js) through `window.__codemanWheelForward`; + // forwarding also needs the server-published `cliMouseTracking` flag (#498). wheelForward: { mode: 'version-gated', minVersion: '2.1.187' }, // A repaint-mode Claude pane keeps no local history, so when the wheel is not // forwarded (older CLI, inline renderer, the local-scrollback opt-out) a scroll is @@ -1926,8 +1926,8 @@ const COPILOT: CliEntry = { // (`cliMouseTracking`). Same shape and reason as opencode. The wheel keeps working because // `_shouldForwardWheelToApp` forwards it as SGR reports while the CLI is tracking. altScreen: 'strip-mux-and-mouse', - // Forwards the wheel as SGR reports while the CLI is tracking the mouse, at any version - // (`_shouldForwardWheelToApp` in terminal-ui.js has no version check for copilot). + // Forwards the wheel as SGR reports while the CLI is tracking the mouse, at any version: + // `always` is what keeps `_shouldForwardWheelToApp` (terminal-ui.js) from checking one. wheelForward: { mode: 'always' }, // Pages its own transcript on PageUp/PageDown (1.0.95, measured in tmux: three PageUp moved // lines 109-140 to 010-042 and PageDown returned). This is the fallback when the diff --git a/src/config/cli-registry/types.ts b/src/config/cli-registry/types.ts index 6411871d..55023179 100644 --- a/src/config/cli-registry/types.ts +++ b/src/config/cli-registry/types.ts @@ -600,6 +600,10 @@ export interface CliCapabilities { * `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). * + * ⚠️ 'version-gated' needs the session's `cliVersion`, and the server probes a version only + * for an entry that declares `capabilities.gates` (`cliNeedsVersionProbe`, session.ts). An + * entry without gates never forwards under 'version-gated', silently, so it uses 'always'. + * * ⚠️ `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