Skip to content

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

Open
JDProfresh wants to merge 2 commits into
Ark0N:masterfrom
JDProfresh:fix/wheel-forward-capability
Open

JDProfresh wants to merge 2 commits into
Ark0N:masterfrom
JDProfresh:fix/wheel-forward-capability

Conversation

@JDProfresh

Copy link
Copy Markdown
Contributor

A custom clis.json entry that starts pi under its own id never gets the wheel forwarding #771 gave stock pi, because _shouldForwardWheelToApp names copilot, pi, claude and codex by id and the registry's wheelForward is still declared-for-later, read by nothing.

What happens

Take a custom CLI entry that starts pi. Its pane is fullscreen pi with mouse tracking on (tmux: alternate_on=1, mouse_any_flag=1, mouse_sgr_flag=1, history_size=0). With the custom-entry defaults (altScreen: strip-mux-only, wheelForward: never) pi's mouse DECSETs reach xterm only as live output: every select, reload and tab switch loads the full=1 capture, which carries no mouse mode, so xterm comes back with mouseTrackingMode: none over a one-screen buffer and the wheel scrolls nothing. That is the bug #771 fixed for stock pi.

Giving the entry pi's own values does not help today and makes it worse: with strip-mux-and-mouse the server strips the DECSETs and publishes cliMouseTracking: true, but the gate does not know the id, so nothing forwards the wheel even in a tab that was watching when pi started.

What changes

  • renderIndexHtml publishes window.__codemanWheelForward: CLI id to its wheelForward rule, for every registry entry whose mode is not never. Disabled entries are included, since disabling a CLI leaves its running sessions open and their wheel has to keep working after a reload. minVersion is a free string from clis.json, so the JSON goes through escapeScriptJson().
  • _shouldForwardWheelToApp reads that map instead of the id list. No rule (or never) means no forwarding, version-gated compares cliVersion against minVersion, and cliMouseTracking must be true as before. A page rendered without the map forwards nothing.
  • _cliVersionAtLeast parses the minimum as strictly as the version (MAJOR.MINOR.PATCH, optional leading v) and refuses either side it cannot read. Before, a minimum such as "", "0" or "2.0" compared as passing. Claude's version reaches the browser through (\d+\.\d+\.\d+) matches only (the --version probe and the banner), so its 2.1.187 gate is unaffected.
  • Stock behaviour does not change: claude from 2.1.187, codex, copilot and pi always, every other CLI never, all only while cliMouseTracking is true. The paging fallback (transcriptPageKeys) and the touch gate are untouched.
  • wheelForward leaves the declared-for-later list (the CliEntry header, test/cli-registry-no-id-branching.test.ts, docs/cli-registry.md, the invariants), the direction that test asks for when a field gets wired up. docs/cli-registry.md gains a short section on the two values a custom full-screen TUI needs.

Invariants: the CLI registry rule that nothing outside stock.ts branches on a CLI id now also holds for the wheel gate. Terminal scrollback strip and wheel/touch forwarding keeps its behaviour and now names the map.

Known limits

  • Like __codemanTranscriptPageKeys, the map is built when the page renders, so a registry change applies from the next page load. In practice nothing changes it mid-page: a custom entry made in the Settings form gets wheelForward: never, enabling or disabling no longer touches the map, and a hand edit of clis.json needs a server restart.
  • The Settings form rebuilds a custom entry's capabilities from its defaults on every save, so a hand-set altScreen or wheelForward is lost after an edit there. The new docs section says so. I can send a separate fix if you want the form to keep the fields it does not edit.

Tests

  • test/terminal-scroll-routing.test.ts: a custom id listed as always forwards only while it tracks the mouse and never on Shift; a version-gated custom rule forwards at and above minVersion and never with an unknown session version; a malformed or missing minVersion never forwards ('', '0', '2.0', '1.2.3.4', '0.bad.999', 'x.y.z', '2..0', '+2.0.0', '0x1.0.0') while 'v2.0.0' and ' 2.0.0 ' still do; an id left out of the map, a never rule and a page without the map forward nothing. The harness now injects the map built from STOCK_CLIS, so every existing stock case runs through it.
  • test/render-index-html.test.ts: with a pi-shaped custom entry and copilot disabled in clis.json, the main page and a /session/:id window both carry exactly the claude, codex, pi, copilot and custom rules.
  • test/terminal-tile-scroll.test.ts and test/terminal-touch-tap.test.ts inject the same map their pages get, and test/server-index-title.test.ts strips the new script like the other injected ones.
  • Each new test failed before its change: the custom id did not forward, the disabled copilot was missing from the map, the empty minimum compared as passing, and a rule with no minVersion threw a TypeError once its guard was taken out.

npm test passes apart from test/agent-skill-local-model.test.ts, whose 30 failures happen on unmodified master on my machine too, run with test/docker-start-setup.test.ts excluded (the WSL mirrored-networking hang from #797). typecheck, lint, format:check, check:frontend-syntax and check:browser-excludes pass, and the four browser files that drive the wheel (codex-wheel-routing, terminal-touch-paging, fullscreen-tab-switch-capture, terminal-tile-scroll) pass in headless Chromium.

Verified

On a throwaway instance with real pi 1.4.0 and a custom entry that starts pi, driven in headless Chromium through a first select, a reload and three same-size tab switches. "Before" is 1.49.0; the gate, the strip, the mouse-mode recorder and the replay query are unchanged on current master.

Build and entry Result after each of those
before, custom-entry defaults mouseTrackingMode: none, baseY: 0, gate false: the wheel scrolls nothing
before, strip-mux-and-mouse + always cliMouseTracking: true but gate false: the wheel scrolls nothing
this branch, strip-mux-and-mouse + always gate true; a wheel-up over the terminal sends \x1b[<64;88;20M reports to the session
this branch, same entry disabled while its session runs gate true, reports sent
this branch, stock pi unchanged: gate true, reports sent

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 Ark0N#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.
@Ark0N

Ark0N commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Thank you @JDProfresh, this is a clean fix. The wheel gate now reads each CLI's wheelForward from the registry (published as window.__codemanWheelForward) instead of a list of ids, so a custom clis.json entry shaped like pi gets the same wheel as stock pi.

I compared the old and new _shouldForwardWheelToApp across every stock CLI, a range of version strings, the tracking states, the xterm mouse modes and Shift. They agree on every combination. The stricter _cliVersionAtLeast and the escaped map also look right to me.

Three small things, none of them blocking:

  1. docs/cli-registry.md:311 (the new section) and the wheelForward JSDoc in src/config/cli-registry/types.ts:597: a version-gated rule only works when the session has a cliVersion, and the server only probes one for an entry that declares capabilities.gates (cliNeedsVersionProbe, src/session.ts:276). So a custom entry with version-gated and no gates never forwards, and nothing tells the user why. Please add a sentence saying so, and saying that a custom entry should otherwise use always. It would save the next person some debugging.
  2. src/config/cli-registry/stock.ts:306: claude's comment still says wheelForward is declared-for-later and that wiring it up needs both rules. Something like "Read by _shouldForwardWheelToApp through window.__codemanWheelForward; forwarding also needs the server-published cliMouseTracking flag (fix(terminal): only forward scroll to Claude while it tracks the mouse #498)" would match the code now.
  3. src/config/cli-registry/stock.ts:1929: copilot's comment says the gate "has no version check for copilot". That is now decided by this always value, so the comment should say so.

If you would rather not push these yourself, I will apply them at merge time. About your offer to make the Settings form keep the fields it does not edit: if you send that, please make it its own PR.

…ward

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.
@JDProfresh

Copy link
Copy Markdown
Contributor Author

Thanks for checking every combination. All three are in b5a356da:

  1. docs/cli-registry.md (end of "Wheel forwarding for a custom full-screen CLI") and the wheelForward JSDoc in src/config/cli-registry/types.ts now say that version-gated needs the session's cliVersion, that the server probes one only for an entry declaring capabilities.gates (cliNeedsVersionProbe), so a custom entry with version-gated and no gates never forwards, and that such an entry uses always.
  2. claude's comment in stock.ts now reads: "Read by _shouldForwardWheelToApp (terminal-ui.js) through window.__codemanWheelForward; forwarding also needs the server-published cliMouseTracking flag (fix(terminal): only forward scroll to Claude while it tracks the mouse #498)."
  3. copilot's comment now says the always value is what keeps the gate from checking a version.

Docs and comments only. Typecheck, lint and the 20 test files that read the registry files pass (527 tests).

On the Settings form: understood, that will be its own PR if I send it.

@Ark0N

Ark0N commented Nov 19, 2026

Copy link
Copy Markdown
Owner

Thank you @JDProfresh for the follow-up on this PR, which makes the wheel gate read each CLI's wheelForward rule from the registry instead of a list of ids. All three points from the last review are in b5a356da: the version-gated caveat is in docs/cli-registry.md and the wheelForward JSDoc, and the claude and copilot comments in stock.ts now describe what the gate does.

I re-ran the old and new _shouldForwardWheelToApp side by side with the stock map over 6,048 combinations: every stock CLI, a custom id, a spread of version strings, the tracking states, the xterm mouse modes, Shift and the local-scrollback opt-out. They agree on all of them. Typecheck, lint, format, the frontend checks, the full npm test and CI are green.

This is ready to merge as it stands. Thanks again for tracking the custom-entry case down to the gate, and for the measured before/after table.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants