Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(terminal): the wheel over a live terminal's banner is the terminal's
enes2b9f385ede20
diff --git a/CLAUDE.md b/CLAUDE.mdindex a98968151..71feec2a4 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -970,6 +970,29 @@ session.- The xterm container is `nodrag nowheel`; a transparent **hover-guard** overlay sits on topuntil you dwell `settings.panHoverDelay` (so quick drag = move node, scroll = pan). Afterthe dwell the guard is removed and xterm takes input. The header stays draggable.+- **Where the wheel stops being the terminal's is decided by HIT TEST, per packet** — `Canvas.tsx`+ answers `overNativeScrollable` with `target?.closest('.nowheel')`, and React Flow's own+ `panOnScroll` walks the same class (`noWheelClassName`). Two consequences, and issue #767 reported+ the second as the first. **(a) Inside the body the wheel is already the terminal's, band+ included.** `.term-node__xterm` carries `nowheel` AND is `position: absolute; inset: 0` over a+ body with no padding and no border, so the visible inset band (the host's own `4px 2px 6px 6px`)+ and a co-attach letterbox band are part of the HOST's hit area — MEASURED with `elementFromPoint`+ under headless Chromium against the verbatim rules, and now pinned as a three-link CSS invariant+ by `canvas/terminal-wheel-boundary.test.ts`. The styles.css line the report reads ("insets the+ xterm by a few px") is about PAINT — the band shows the body's `--term-bg` because the host paints+ none — and paint is not hit testing. An overlay laid over a LIVE terminal therefore owes+ `pointer-events: none` (`.term-node__stalecwd`, joining `.term-node__upload` and+ `.term-copy-pill`); an overlay that REPLACES a dead view (`.term-node__offscreen`,+ `.term-node__closed`) deliberately keeps the canvas wheel — there is nothing underneath to+ scroll, so panning is the useful answer. **(b) The boundary that actually moves is TEMPORAL, not+ spatial**: while it is up, `.term-hover-guard` covers the whole body and is NOT `nowheel`, so for+ the first `panHoverDelay` after the pointer enters — and again after it leaves — a wheel over+ terminal TEXT pans the canvas. That is the guard's own contract ("quick drag = move node, scroll+ = pan canvas") and the reason those incidents cannot be reproduced on demand. Hoisting `nowheel`+ to `.term-node__body` would swallow the guard with it (a second consumer, React Flow's, reads the+ class the same way and no per-element opt-out can reach it); hoisting it to the whole NODE would+ additionally take wheel-zoom-to-cursor away over every node, which is exactly where a+ `wheelZoom` user aims.- A `ResizeObserver` drives `FitAddon.fit()` + `transport.resize`. Canvas zoom is a CSStransform, so it does *not* change `clientWidth` — cols/rows stay stable across zoom.`scale-fix.ts` patches xterm's mouse coords so text selection stays aligned when zoomed.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 7977574bd..f414ff8e3 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -102,6 +102,19 @@ lane unaffected.PR; copy that really is macOS-specific (the ptmx-limit banner, the notch step) is exempt by namewith its reason. Comments are not scanned.+- **An overlay you lay over a live terminal steals its wheel — give it `pointer-events: none`.**+ Wheel routing is a per-packet hit test on `closest('.nowheel')` (ours in `Canvas.tsx`, and React+ Flow's own `panOnScroll` independently), so the element under the pointer decides, not the node.+ `.term-node__xterm` carries the class and covers the whole body, so a banner drawn ON a running+ terminal takes those pixels out of the terminal's wheel area and hands them to the canvas — the+ user scrolls and the canvas slides instead. `.term-node__upload` and `.term-copy-pill` were+ already `pointer-events: none` for this; `.term-node__stalecwd` was not (issue #767), and+ `canvas/terminal-wheel-boundary.test.ts` now fails on the next one. An overlay that REPLACES a+ dead view keeps the canvas wheel on purpose — there is nothing underneath to scroll. Same rule+ one layer up: do not "fix" a routing question by moving `nowheel` outward, because a second+ consumer reads the class and no per-element opt-out can reach it. Deep version: CLAUDE.md §+ Terminal node lifecycle.+- **The node colour palette is ONE list, and it is also the control boundary.**`src/shared/node-colors.ts` is what every picker draws and what `nodeterm color --color C`validates against — so a colour the UI offers and a colour the CLI accepts cannot drift apart.diff --git a/src/renderer/canvas/terminal-wheel-boundary.test.ts b/src/renderer/canvas/terminal-wheel-boundary.test.tsnew file mode 100644index 000000000..edd4c4e1a--- /dev/null+++ b/src/renderer/canvas/terminal-wheel-boundary.test.ts@@ -0,0 +1,162 @@+// @vitest-environment jsdom+import { describe, expect, it } from 'vitest'+import { readFileSync } from 'node:fs'+import { resolve } from 'node:path'+import { MacWheelGestureRouter } from './wheel-gesture'++/**+ * Issue #767 — where, inside one terminal node, the wheel stops being the terminal's.+ *+ * Wheel routing is a per-packet HIT TEST: `Canvas.tsx` answers `overNativeScrollable` with+ * `target?.closest('.nowheel')`, and React Flow's own `panOnScroll` walks the same class+ * (`noWheelClassName`, default `nowheel`). So the boundary is wherever that class sits in the DOM,+ * and it is invisible — which is what the report is about.+ *+ * #767 names the band by which the body insets the xterm as a place where the wheel silently+ * becomes the canvas's. MEASURED (headless Chromium, `elementFromPoint` over the verbatim rules+ * from styles.css): it is not. `.term-node__xterm` carries `nowheel` AND is `position: absolute;+ * inset: 0` over a body with no padding and no border, so its own padding box — the visible band,+ * and the co-attach letterbox band with it — hit-tests to the host and already routes to the+ * terminal. The styles.css comment the report reads ("insets the xterm by a few px") is about+ * PAINT: the band shows the body's `--term-bg` because the host paints none. Paint and hit test+ * are different questions and only the second decides the wheel.+ *+ * That correctness is INCIDENTAL, though — it rests on a three-link CSS chain nothing enforced.+ * The first describe below turns the chain into an invariant; the second pins the class contract+ * itself, hover guard included, so "the wheel is the terminal's inside the body" cannot be widened+ * or narrowed by accident.+ */+// Paths are resolved from `__dirname`, not `import.meta.url`: this file runs under jsdom, where+// `import.meta.url` is an http:// URL and `readFileSync` refuses it. The CRLF normalization is the+// house rule (`src/shared/line-endings.guard.test.ts`) — the block slicer below keys on `\n`.+const read = (rel: string): string =>+ readFileSync(resolve(__dirname, rel), 'utf8').replace(/\r\n/g, '\n')+/**+ * Comments are stripped BEFORE anything is matched, and that is not tidiness — every rule below+ * carries a comment explaining the very declaration it asserts, so a match against the raw text+ * passes on the PROSE after the declaration is deleted. Both CSS mutations were silently survived+ * until this line existed.+ */+const css = read('../styles.css').replace(/\/\*[\s\S]*?\*\//g, '')+const terminalNode = read('../nodes/TerminalNode.tsx')++/** The declaration block of a rule whose selector list is exactly `selector`. */+const block = (selector: string): string => {+ const at = css.indexOf(`\n${selector} {`)+ expect(at, `no rule for ${selector}`).toBeGreaterThan(-1)+ const open = css.indexOf('{', at)+ const close = css.indexOf('}', open)+ return css.slice(open + 1, close)+}++describe('#767 — the terminal body is one wheel surface (CSS chain)', () => {+ it('the xterm host covers the whole body, so its inset band hit-tests to the host', () => {+ const host = block('.term-node__xterm')+ // Both halves are load-bearing. `inset: 0` is what makes the host's box equal the body's;+ // `position: absolute` is what makes `inset` mean anything. Drop either and the padding band+ // stops belonging to the host — and the wheel there starts panning the canvas.+ expect(host).toMatch(/position:\s*absolute/)+ expect(host).toMatch(/inset:\s*0/)+ // The band exists because the host has padding. That is fine — padding is part of an element's+ // hit area — but it is the reason this test exists, so pin that it is still there.+ expect(host).toMatch(/padding:/)+ })++ it('the body adds no padding and no border of its own', () => {+ // A padding or border on the BODY would push the host inward and open a real band that belongs+ // to nobody — the gap #767 describes. (styles.css already states this for the glyphgrid plate,+ // which measures the host and not the body for exactly the same reason.)+ const body = block('.term-node__body')+ expect(body).not.toMatch(/(^|[;\s])padding\b/)+ expect(body).not.toMatch(/(^|[;\s])border\b/)+ })++ it('overlays laid over a LIVE terminal do not intercept its wheel', () => {+ // These three sit on top of a terminal that is still running and still scrollable, so the+ // pixels have to fall through to the host beneath. The upload note and the copy receipt were+ // already `pointer-events: none` for the same reason; the stale-cwd banner (shared by the+ // launch-too-long and lost-session banners) was not, and is the one thing #767 names that+ // measured true.+ for (const sel of ['.term-node__stalecwd', '.term-node__upload', '.term-copy-pill'])+ expect(block(sel), sel).toMatch(/pointer-events:\s*none/)+ // …and the banner's interactive halves must opt back in, or the fix breaks its buttons.+ expect(block('.term-node__stalecwd-restart,\n.term-node__stalecwd-dismiss')).toMatch(+ /pointer-events:\s*auto/+ )+ })++ it('the overlays that REPLACE the terminal keep the canvas wheel, deliberately', () => {+ // The offscreen plate and the closed/ended/failed/offline notices cover a view that is gone:+ // there is nothing underneath to scroll, so a wheel there panning the canvas is the useful+ // answer, not a bug. Stated as a test so the boundary above is read as a decision.+ for (const sel of ['.term-node__offscreen', '.term-node__closed'])+ expect(block(sel), sel).not.toMatch(/pointer-events:\s*none/)+ })+})++/**+ * The class contract, exercised through the real router with the real predicate from Canvas.tsx.+ * jsdom has no layout, so this pins WHICH ancestor owns each element — not geometry, which the+ * chain above covers.+ */+const node = (): HTMLElement => {+ const root = document.createElement('div')+ root.innerHTML = `+ <div class="react-flow__node">+ <div class="term-node">+ <div class="term-node__header"><span class="term-node__title">t</span></div>+ <div class="term-node__body">+ <div class="term-node__xterm nodrag nowheel">+ <div class="xterm"><div class="xterm-viewport"></div></div>+ </div>+ <div class="term-hover-guard"></div>+ </div>+ </div>+ </div>`+ return root+}++/** Exactly what Canvas.tsx computes per packet. */+const routeOf = (target: Element): 'native' | 'flow-pan' =>+ new MacWheelGestureRouter().destination(+ { deltaY: 6.25, deltaX: 0, deltaMode: 0, ctrlKey: false, metaKey: false },+ true, // macOS + trackpadPan: the configuration #767 reports from+ () => !!target.closest('.nowheel')+ )++describe('#767 — wheel routing inside a terminal node (class contract)', () => {+ const root = node()+ const at = (sel: string): Element => {+ const el = root.querySelector(sel)+ expect(el, sel).not.toBeNull()+ return el as Element+ }++ it('the xterm host and everything xterm renders inside it route to the terminal', () => {+ // The host itself is the element a packet in the inset band lands on.+ expect(routeOf(at('.term-node__xterm'))).toBe('native')+ expect(routeOf(at('.xterm-viewport'))).toBe('native')+ })++ it('the header stays the canvas’s — it is the drag handle, not content', () => {+ expect(routeOf(at('.term-node__header'))).toBe('flow-pan')+ expect(routeOf(at('.term-node__title'))).toBe('flow-pan')+ })++ it('the hover guard keeps panning the canvas — unchanged, and on purpose', () => {+ // While the guard is up (the first `panHoverDelay` ms after the pointer enters, and again+ // after it leaves) it covers the whole body, so the wheel pans even over terminal text. That+ // is the hover guard's own contract — "quick drag = move node, scroll = pan canvas" — and it+ // is what actually makes the boundary time-dependent rather than spatial. #767's fix does not+ // touch it; this test is here so a later change to the body's class cannot silently take the+ // guard's pan away with it.+ expect(routeOf(at('.term-hover-guard'))).toBe('flow-pan')+ })++ it('the class sits on the host, not on the node or the body', () => {+ // The whole-node variant #767 offers would also disable wheel-zoom-to-cursor over every node+ // and swallow the hover guard's pan; keep the placement explicit.+ expect(terminalNode).toContain('term-node__xterm nodrag nowheel')+ expect(terminalNode).not.toMatch(/term-node__body[^"`']*\bnowheel\b/)+ })+})diff --git a/src/renderer/styles.css b/src/renderer/styles.cssindex 7850d116b..a2056408c 100644--- a/src/renderer/styles.css+++ b/src/renderer/styles.css@@ -2620,11 +2620,29 @@ body,color: #ffd9a8;background: rgba(120, 70, 10, 0.92);border-bottom: 1px solid rgba(255, 180, 80, 0.35);+ /* Issue #767. The canvas routes a wheel packet by HIT TEST — `closest('.nowheel')` in+ `Canvas.tsx` and React Flow's own `noWheelClassName` — so whatever element sits under the+ pointer decides whether the wheel scrolls the terminal or pans the canvas. `.nowheel` lives on+ `.term-node__xterm`, which is `position: absolute; inset: 0` and therefore owns the WHOLE body+ including its own inset padding and a co-attach letterbox band (measured; see+ `terminal-wheel-boundary.test.ts`). This banner was the one thing that broke that: it is a+ strip laid OVER a terminal that is still alive and still scrollable, outside the `.nowheel`+ subtree, so two rows of live output answered the wheel with a canvas pan.++ `pointer-events: none` hands those pixels back to the host underneath — the same trick, and+ the same reasoning, as `.term-node__upload` and `.term-copy-pill` above. Its two BUTTONS opt+ back in below; nothing else in here is interactive. */+ pointer-events: none;}.term-node__stalecwd-text {flex: 1;min-width: 0;}+/* The interactive halves opt back in — see the `pointer-events: none` note on the banner. */+.term-node__stalecwd-restart,+.term-node__stalecwd-dismiss {+ pointer-events: auto;+}.term-node__stalecwd-restart {padding: 2px 10px;border: 1px solid rgba(255, 200, 120, 0.45);