diff --git a/CLAUDE.md b/CLAUDE.md index 438ac05e..4ab21163 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -286,7 +286,7 @@ Codeman is a Claude Code session manager with web interface and autonomous Ralph **Ctrl+V paste trap** (`image-input.js`): `Ctrl+V` routes through `_handleImagePaste()`, which focuses a hidden `contenteditable` trap and reads the clipboard from the paste event landing there; images upload and their paths are typed in, text goes through `terminal.paste()` so bracketed-paste markers survive. ⚠️ **The trap must consume exactly ONE paste event** (Firefox delivers two per keypress: the `execCommand('paste')` event and the keydown's default action); the one-shot flag lives on the trap, never on a browser check. ⚠️ Do not remove the `execCommand('paste')` call: on some mobile engines it is the only route into the trap, and the trap is the only place image blobs are read. Tests: `test/image-paste-trap.test.ts`. → [architecture-invariants#terminal-paste-ctrlv](docs/architecture-invariants.md#terminal-paste-ctrlv) -**Terminal scrollback strip + wheel/touch forwarding**: codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed opencode gets the MIDDLE strip (alt-screen toggles + mouse DECSETs, `3J` kept); every other tmux-backed mode (shell/antigravity/pi/grok/deepseek/omp) gets the NARROW strip (alt-screen toggles only). Table: `CliCapabilities.altScreen` JSDoc, pinned in test/claude-scrollback-strip.test.ts. ⚠️ Gated on `useMux`: direct-PTY sessions must keep the alt screen. Wheel and touch forward to the CLI for **claude ≥ 2.1.187 ONLY, and only while it has mouse tracking on** (`cliMouseTracking`: fullscreen claude sets it, its default inline renderer does not and scrolls locally like codex); ⚠️ never re-add codex without a fresh measurement (it ignores SGR wheel reports). ⚠️ `getClaudeCliVersion()` must never cache a FAILED probe. ⚠️ Hand-report clicks only while the CLI has mouse tracking on: `_shouldReportMouseToCli()` gates all three report sites on `cliMouseTracking` (from `_recordStrippedMouseMode()`, session.ts), or a plain shell prints the reports as literal text. Read `_logScrollRouting()` before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding) +**Terminal scrollback strip + wheel/touch forwarding**: codex/claude/gemini get the FULL strip (alt-screen, `3J`, mouse DECSETs); tmux-backed opencode gets the MIDDLE strip (alt-screen toggles + mouse DECSETs, `3J` kept); every other tmux-backed mode (shell/antigravity/pi/grok/deepseek/omp) gets the NARROW strip (alt-screen toggles only). Table: `CliCapabilities.altScreen` JSDoc, pinned in test/claude-scrollback-strip.test.ts. ⚠️ Gated on `useMux`: direct-PTY sessions must keep the alt screen. Wheel and touch forward to the CLI for **claude ≥ 2.1.187 ONLY, and only while it has mouse tracking on** (`cliMouseTracking`: fullscreen claude sets it, its default inline renderer does not and scrolls locally like codex); ⚠️ never re-add codex without a fresh measurement (it ignores SGR wheel reports). ⚠️ `getClaudeCliVersion()` must never cache a FAILED probe. ⚠️ Hand-report clicks only while the CLI has mouse tracking on: `_shouldReportMouseToCli()` gates all three report sites on `cliMouseTracking` (from `_recordStrippedMouseMode()`, session.ts), or a plain shell prints the reports as literal text. ⚠️ A `TerminalTile` (grid tile, split Pane B) pages the wheel and reports clicks through these SAME gates with itself as the target (its terminal, its session, never `activeSessionId`); never copy the mode lists into terminal-tile.js. Read `_logScrollRouting()` before diagnosing a scroll report. → [architecture-invariants#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding](docs/architecture-invariants.md#terminal-scrollback-strip-flavors-and-wheeltouch-forwarding) **Detached start + service install**: `codeman web -d` relaunches the same entry script `detached:true` (setsid); `nohup` is not what makes it survive. ⚠️ Both `-d` and `service install` must REFUSE when a server is already up on this data dir (pidfile + `/api/status` probe), or a second instance attaches to the first one's live sessions. ⚠️ Never report success not observed: poll `/api/status` until the child answers or dies. `--stop` must verify the pid still looks like Codeman (`ps -o command=`) before signalling. Unit/label names live only in `config/service-names.ts`. `service install` bakes the installing shell's PATH into the unit and never writes `CODEMAN_PASSWORD` into it. → [architecture-invariants#detached-start-and-service-install](docs/architecture-invariants.md#detached-start-and-service-install) **Self-update** (App Settings → System → Updates): in-app updater for git-clone installs under a supervisor (`systemd`, `launchd`, `launchd-daemon`, `docker-compose`, else `none`). The work runs in a DETACHED `scripts/self-update.sh` writing `update-status.json`, polled across the restart; pure helpers in `src/web/self-update.ts`. ⚠️ Compose: the restart kills the script, so nothing may be appended after the `restarting` marker; the repo must stay a host bind mount over `/opt/codeman` and the image must keep devDependencies + toolchain. ⚠️ `evaluateEnvironmentGate()` refuses releases that change `server.Dockerfile`/`docker-compose.yaml` or add `.env.example` keys, re-evaluated on `POST /api/system/update`; unknowns fail OPEN, but the exit-to-restart needs `--restart-by-exit 1` (`CODEMAN_RESTART_BY_EXIT=1` only in the Compose file). ⚠️ Keep the agent CLIs in `server.Dockerfile` pinned. → [docs/docker-self-update.md](docs/docker-self-update.md), [architecture-invariants#self-update](docs/architecture-invariants.md#self-update) diff --git a/config/test-suites.ts b/config/test-suites.ts index 24662c30..6283d361 100644 --- a/config/test-suites.ts +++ b/config/test-suites.ts @@ -33,6 +33,7 @@ export const BROWSER_TEST_GLOBS = [ 'test/capture-geometry-retry.browser.test.ts', 'test/codex-predictive-echo.test.ts', // also needs a real codex binary 'test/split-pane-terminal.browser.test.ts', + 'test/terminal-tile-scroll.browser.test.ts', 'test/shift-enter-keypress.browser.test.ts', 'test/key-tester.browser.test.ts', 'test/webhook-settings.browser.test.ts', diff --git a/docs/architecture-invariants.md b/docs/architecture-invariants.md index 240b18a3..87e6a360 100644 --- a/docs/architecture-invariants.md +++ b/docs/architecture-invariants.md @@ -225,7 +225,7 @@ Further detail: the `: ` form (`w3-myapp: fix the login redirect` **Wheel/touch forwarding is NOT gated on viewport-at-bottom** (#205, `terminal-ui.js:_shouldForwardWheelToApp`): for sessions verified to scroll their own transcript on SGR wheel reports (claude ≥ 2.1.187 while `cliMouseTracking` is true, i.e. fullscreen; version via the local/docker/remote `--version` probes), the plain wheel AND touch drags forward as coalesced SGR reports (`_forwardScrollToApp` → `_sendSyntheticSgrWheel`, 40ms batches, 5-tick cap, 512-byte queue bound). It used to gate on the viewport being at the bottom so both scrollbacks stayed reachable, but a repaint-mode CLI keeps NO terminal scrollback of its own — xterm's buffer holds only replayed repaint frames, so local scrolling drags the CLI's pinned prompt box up the screen over stale frames; and `scrollToLastNonEmptyLine()` routinely parked the viewport off-bottom, silently pinning the wheel to local. Forwarding now snaps the viewport home first (SGR coordinates address the LIVE screen — a report computed from a scrolled-up viewport would hit-test the wrong row). Local scrollback remains on Shift+wheel and the `terminalWheelLocalScrollback` opt-out (both also cover touch via the shared gate; touch has no Shift, so the setting is its only local pin). `_wheelScrollLines()` normalizes `deltaMode` (Firefox fires LINE deltas ≈3/notch — read as pixels that rounded to 0 and fell to the ±1 fallback, ~4× too slow; PAGE deltas scale by `terminal.rows`) while keeping the #154 Shift-axis trap (macOS trackpads put Shift+scroll magnitude on deltaX). Tests: `test/terminal-touch-tap.test.ts`. -**A false gate on a hollow pane must not mean a DEAD gesture** (#205 round 2, `_maybePageCliTranscript`): every way `_shouldForwardWheelToApp()` returns false leaves a repaint-mode pane scrolling a buffer that has nothing in it (`baseY === 0`) — the version probe came back empty, the CLI really is older than 2.1.187, the `cliMouseTracking` flag is unset (inline claude, or fullscreen right after a server restart), or the user turned on `terminalWheelLocalScrollback`. **opencode is the fifth case, and the gate is false there by design**: its TUI runs on the ALTERNATE SCREEN (1.18.31 measured: tmux `alternate_on=1`, `history_size=0`), so the buffer is hollow, and it IGNORES SGR wheel reports entirely (six `\x1b[<64;…M` reports against an idle pane left the capture byte-identical) while still paging its transcript on PageUp/PageDown (`messages_page_up/down`) — so paging is the only gesture that can reach it, and without it the wheel was silently dead in every opencode tab. The 1.12.0 retest reported exactly that shape for Claude: a wheel that did nothing at all while Fn+Up (PageUp) paged back through intact text, which is the proof that the CLI's own history and the PTY input path were both fine. So under the guard (`_localScrollbackIsHollow()` — `claude` or `opencode`, gate false, `baseY === 0`) wheel and touch travel is translated into coalesced `\x1b[5~` / `\x1b[6~` through the same 40ms queue as the SGR reports, at half a screen of travel per page key (the key jumps a whole screen; a 1:1 mapping was unusably slow with a discrete wheel). ⚠️ `shell`/`pi` own real terminal scrollback and are never paged, and codex/gemini/antigravity/grok/deepseek/omp page-key behaviour is unverified (`docs/scrollback-fix-plan.md`). ⚠️ Shift is excluded on purpose — it is the explicit "give me local scrollback" gesture and must keep that meaning. ⚠️ `terminalWheelLocalScrollback` is deliberately NOT scoped away from repaint-mode CLIs even though it is a footgun there: that would silently override an explicit user choice, so the fallback catches it instead. **Server-side counterpart**: `getClaudeCliVersion()` caches SUCCESS for the process lifetime but must never cache FAILURE — it used to, so one timed-out or PATH-starved probe at the first Claude session start disabled wheel-forwarding for every Claude session until the server restarted (a dead wheel on phone, tablet and laptop at once, the signature of a server-side cause). Failures now retry with a 1/2/4…15min backoff; the policy is the pure `resolveClaudeCliVersion()`. Tests: `test/terminal-scroll-routing.test.ts`, `test/claude-cli-version-cache.test.ts`. +**A false gate on a hollow pane must not mean a DEAD gesture** (#205 round 2, `_maybePageCliTranscript`): every way `_shouldForwardWheelToApp()` returns false leaves a repaint-mode pane scrolling a buffer that has nothing in it (`baseY === 0`) — the version probe came back empty, the CLI really is older than 2.1.187, the `cliMouseTracking` flag is unset (inline claude, or fullscreen right after a server restart), or the user turned on `terminalWheelLocalScrollback`. **opencode is the fifth case, and the gate is false there by design**: its TUI runs on the ALTERNATE SCREEN (1.18.31 measured: tmux `alternate_on=1`, `history_size=0`), so the buffer is hollow, and it IGNORES SGR wheel reports entirely (six `\x1b[<64;…M` reports against an idle pane left the capture byte-identical) while still paging its transcript on PageUp/PageDown (`messages_page_up/down`) — so paging is the only gesture that can reach it, and without it the wheel was silently dead in every opencode tab. The 1.12.0 retest reported exactly that shape for Claude: a wheel that did nothing at all while Fn+Up (PageUp) paged back through intact text, which is the proof that the CLI's own history and the PTY input path were both fine. So under the guard (`_localScrollbackIsHollow()` — `claude` or `opencode`, gate false, `baseY === 0`) wheel and touch travel is translated into coalesced `\x1b[5~` / `\x1b[6~` through the same 40ms queue as the SGR reports, at half a screen of travel per page key (the key jumps a whole screen; a 1:1 mapping was unusably slow with a discrete wheel). ⚠️ `shell`/`pi` own real terminal scrollback and are never paged, and codex/gemini/antigravity/grok/deepseek/omp page-key behaviour is unverified (`docs/scrollback-fix-plan.md`). ⚠️ Shift is excluded on purpose — it is the explicit "give me local scrollback" gesture and must keep that meaning. ⚠️ `terminalWheelLocalScrollback` is deliberately NOT scoped away from repaint-mode CLIs even though it is a footgun there: that would silently override an explicit user choice, so the fallback catches it instead. **Server-side counterpart**: `getClaudeCliVersion()` caches SUCCESS for the process lifetime but must never cache FAILURE — it used to, so one timed-out or PATH-starved probe at the first Claude session start disabled wheel-forwarding for every Claude session until the server restarted (a dead wheel on phone, tablet and laptop at once, the signature of a server-side cause). Failures now retry with a 1/2/4…15min backoff; the policy is the pure `resolveClaudeCliVersion()`. **Tiles** (a grid tile, the split's Pane B: `TerminalTile`) page the wheel through these same gates, called with the tile's own terminal and session (`_localScrollbackIsHollow(target)`, `_shouldForwardWheelToApp(ev, target)`) and the pure `CodemanTerminalInput.pageKeysForTravel`, so the mode list stays in terminal-ui.js alone. ⚠️ A tile's `baseY` is rarely 0 even when hollow: its first capture is taken at the PTY's previous, taller size and its row-shrinking fits push rows up, so it passes `localRows` with those rows discounted (`TerminalTile._localRows`). Tiles have no touch path and do not forward SGR wheel (tile-grid-plan follow-up 4). Tests: `test/terminal-scroll-routing.test.ts`, `test/terminal-tile-scroll.test.ts`, `test/claude-cli-version-cache.test.ts`. **Why the wheel went where it went is LOGGED** (`_logScrollRouting`): one console line per session per distinct decision — `[scroll] <id> → forward-sgr|page-keys|local-scrollback|repull-refused-downgrade (mode=…, cliVersion=…, localScrollbackOptOut=…, mouseTracking=…, localScrollbackRows=…)`. #205 ran two rounds of remote guesswork over questions this line answers directly; keep it when touching the routing. @@ -801,7 +801,7 @@ Further detail: with many sessions the horizontal strip stops being scannable, w ### Split-pane sessions -**Split-pane sessions** (`showSplitButton`, header button, default OFF, per-device like `showFileViewerButton` — not in `SettingsUpdateSchema`, `displayKeys` in settings-ui.js): shows two live sessions side-by-side in one Codeman window. Pane A is the untouched, existing singleton terminal (`this.terminal`/`this._ws` in terminal-ui.js); Pane B is an independent `TerminalTile` (terminal-tile.js, constructed by the orchestration in terminal-split.js) with its own xterm instance and its own `/ws/sessions/:id/terminal` WebSocket, whose `cid` is the tab's identity with a `:tile` suffix, so it can never supersede the primary pane's socket (the registry supersedes by cid per session). ⚠️ **Pane B is deliberately plainer than Pane A** — no local-echo overlay, no CJK IME, no touch/mobile handlers, no keyboard accessory bar — since this is a desktop-only feature (a split view needs a wide viewport) and those features exist for mobile/touch input; `.btn-split` is hard-hidden below 1180px regardless of the setting by the `@media (max-width: 1179px)` rule in styles.css (mobile.css only carries a comment pointing at it: that file loads up to 1023px, so it cannot cover the 1024-1179px tablet range the feature also needs to stay off), and the per-device setting means turning it on at a desk can never sync it onto a phone in the first place. No persistence: closing the browser tab or reloading always returns to the normal single-pane view; there is no localStorage key for split state. ⚠️ Splitting a session against itself is disallowed (the picker excludes the active session), **as is splitting against a popped-out (detached) session** — `buildSplitPickerSessions()` excludes `detachedSessions` because a detached session's own window is already claiming its PTY size, and `MAX_WS_PER_SESSION` needs no change since Pane A/B are always two different sessions. ⚠️ Either pane's session ending (deleted locally or from another client) auto-collapses the split — Pane A's session ending promotes Pane B to the new single pane via `selectSession(id, { auto: true })` (an app-driven selection, so it must not spend the session's idle alert — see the Approvals Inbox note above), never by trying to hot-swap the lightweight `TerminalTile` object into the primary singleton state. ⚠️ Pane B refits on every window/sidebar/tab-rail resize via the SAME trailing-edge `ResizeObserver` callback that resizes Pane A (`throttledResize` in terminal-ui.js) — it only ever measured Pane A's own container, so without the explicit `this._forEachTile?.((tile) => tile.fit(), { grid: false })` call there (grid tiles are left out: the grid's own observer refits them on the same resize) Pane B silently kept its stale PTY size through every resize that did not happen to be a divider drag. ⚠️ A dropped WebSocket writes a `[disconnected, reconnecting…]` marker into Pane B and reconnects on the primary pane's backoff ladder (`CodemanWsReconnect` plus jitter; the attempt count resets only on a successful open), then refreshes the buffer to close the output gap. ⚠️ The open handler clears `_wsClosed`/`_markerOwed` BEFORE that refresh, or the refresh re-owes the marker and stamps it under a healthy pane. ⚠️ 4003/4004/4009/4010 stop the pane for good, report once through `onExit(code)` and write a marker saying why (`CodemanWsReconnect` alone would retry 4003). ⚠️ A replacement socket detaches the old one first and every handler ignores a socket that is no longer `this.ws`, so a late 4010 from a superseded socket cannot stop its successor; `destroy()` cancels a pending reconnect. Related but distinct: `detachSession()` already opens one session in a separate OS-level browser window (`isSoloWindow`) — that is prior art for "two sessions visible at once" but not for one window with a draggable in-page divider, which is what this feature adds. ⚠️ Pane B installs its own `attachCustomKeyEventHandler` gating the same app-level chords Pane A's own handler gates (command palette, Alt+1-9/[/] tab nav, Alt+B sidebar toggle, Ctrl+Z suspend, Shift/Ctrl+Enter newline, smart-copy Ctrl+C) — without it the document capture-phase handler's `preventDefault()` (which never stops xterm) let each chord ALSO write its raw byte/escape sequence into Pane B's live PTY on top of whatever the app action did to Pane A (COD-153). Ctrl+Z is swallowed unless Pane B's own session is `mode === 'shell'`, mirroring terminal-ui.js's reasoning: in a plain shell it is the user's own job-control tool, everywhere else it silently suspends an unattended agent loop. Shift/Ctrl+Enter POSTs to `/api/sessions/:id/send-key` (`{key:'S-Enter'|'C-Enter'}`, typed by tmux `send-keys -H`: Ctrl+Enter is always a real 0x0a, Shift+Enter is the CLI's declared `capabilities.newline` chord, also 0x0a unless the CLI declares another; sent on keydown only, with the keypress and keyup swallowed too, see the keypress rule under Command palette and shortcut registry) targeting THIS pane's own `sessionId` rather than the primary pane's `activeSessionId` — without it xterm's plain `\r` would submit an incomplete prompt instead of adding a line to it. Smart-copy Ctrl+C/Ctrl+Shift+C is re-implemented against `this.terminal` (Pane B's own) rather than reusing `app.copyTerminalSelection()`, which reads Pane A's terminal and would copy the wrong pane's selection; Ctrl+Shift+C never falls through even with nothing to copy, mirroring terminal-ui.js's own `ev.shiftKey` branch. ⚠️ **This is a UX-parity fix, not an interrupt-safety one** — verified live in a real browser: xterm's `evaluateKeyboardEvent` routes a shifted ctrl-letter into a branch that assigns `c.key` only for two special cases (`_`→US, `@`→NUL), so it emits no data for Ctrl+Shift+C at all regardless of any application gate; a synthetic keydown with the gate removed produces zero WS frames, proving no accidental interrupt reaches the PTY either way. What gating the whole copy block on `hasSelection()` (an earlier draft) actually cost: with no selection, a selection-less Ctrl+Shift+C fell straight to `return true`, silently ceding the keystroke to the BROWSER's own handling (e.g. Chrome's Inspect-Element binding) with no feedback and no copy attempt — Pane A always intercepts it. Ctrl+V goes through the primary pane's paste trap aimed at Pane B (`_handleImagePaste({ terminal, sessionId })`), so a pasted image uploads to Pane B's session. ⚠️ `buildSplitPickerSessions()` also excludes any session with `pid === null` (an exited CLI, a crash-looped session whose breaker tripped, a restore that never re-attached): Pane B has no equivalent of `selectSession()`'s auto re-attach POST, so a pane opened onto one has nothing reading its tmux pane — no `terminal` events ever arrive, and `Session.write()` silently drops every keystroke with no ack either way, so the loss is invisible behind a socket that reports healthy. Pane B's keystrokes go through the exactly-once queue (`_sendInputAsync`) over its own socket, registered in the app's input-socket map (`_registerInputSocket` / `_inputSocketFor`), so they are seq-tagged, ACKed (`{t:'ia'}` is routed by the RECEIVING socket's session, since the frame names none), redelivered after a drop, and the ACK clears the idle alert. ⚠️ What xterm generates never enters that persisted queue: query replies are dropped (`shouldSuppressTerminalQueryResponse`, as the primary pane drops them) and focus/mouse reports go through `_sendInputEphemeral`, or a reload would replay them as typed text. ⚠️ A SHELL Pane B pulls scrollback itself when the wheel goes up at the top of its buffer (`_maybeLoadMoreHistory`/`_pullHistory`): tmux repaints a burst of output instead of scrolling it, so Pane B's own xterm holds about one screen of scrollback while tmux holds every line, and it loaded history exactly once at connect and never again. It is the same bounded pull as Pane A's (`?full=1&tail=TERMINAL_TAIL_SIZE`, no rewrite when the window holds no more rows than the pane already has or the pane is at its `scrollback + rows` cap, and a 60 s back-off instead of 4 s when that skipped window was truncated or the pane is full, since each ask costs the server a whole-history `capture-pane`), against Pane B's OWN terminal rather than `app.terminal`, so it cannot share `_maybeRefetchFullHistory`. The wheel listener is capture-phase because xterm `stopPropagation()`s the events it consumes; the alternate-screen skip (nano, vim, less) only matters for a direct-PTY shell, since under tmux the browser xterm never enters the alternate buffer; skipped too for a detached session (mirrors `_sendResize()`'s own check and app.js's `_maybeRefetchFullHistory`), since its own window already owns its PTY size and scrollback. Live frames arriving from the response onward, a `{t:'c'}` clear frame included, are held with their arrival time (`_liveQueue`, opened right after `await fetch(...)` beside `capturedAt`; a frame from before it is replaced by the capture or written unchanged, so the pane keeps painting during the round trip) and replayed in order only if they arrived after the capture (the response's arrival stands in for the capture instant, as in `_finishBufferLoad`, so a frame inside that one round trip can be lost or doubled); the request uses the primary pane's budget (`CodemanFetchDeadline.terminalFetchDeadlineMs({ full: true })`, 45 s, 10 s only if that helper is absent) and the body read gets 10 s once the headers land, because from then on the pull holds the pane's live output. The request phase holds no live output, but it does hold the single-flight flag, so a coalesced `{t:'r'}` refresh and a marker owed by a close (below) wait for the response, at worst for that whole budget (accepted: a Codeman restart resets an in-flight request along with the socket, so that pull fails at once and stamps the marker). ⚠️ The "disconnected" marker must be the LAST thing on screen. A replay's own `\x1bc` would otherwise wipe a marker written before the pull and paint a fresh, current-looking history while `onData` keeps silently dropping every keystroke on the dead socket (a Codeman restart drops the socket while the tmux session, and so the HTTP pull, still succeeds), so `_pullHistory()` re-stamps it after the live-frame flush. A close DURING any load (a pull, a refresh; `connect()` awaits the initial load before it creates the socket, so no close lands in that one) writes nothing: `_onSocketClosed()` sets `_markerOwed` while a load's work runs (`_loadRunning`; a load that only waits in the tile grid's queue writes the marker at once, and its refresh clears the screen only when its turn comes), since written there it would sit above the held frames the pull flushes after a skip, a downgrade, a failed fetch or the deadline, above a refresh's replay, or land mid-way through a chunked replay. Each load settles the marker in its OWN `finally` (`_stampMarkerIfOwed()`), after the queue flush, EXCEPT when a trailing refresh is pending: that refresh's `clear()` is synchronous while xterm parses a `write()` on a later tick, so a marker stamped just before it lands in the freshly cleared buffer ABOVE the refresh's replay (a second, stale copy; the default fake terminal in `test/terminal-tile-unit.test.ts` writes synchronously and cannot show it, so an async-parse fake there pins it). The marker stays owed instead, and the trailing refresh, which re-owes it on a closed socket anyway, writes the one copy below its own replay. Anything that wipes the terminal on a closed socket (a replay's `\x1bc`, a refresh's `clear()`) sets `_markerOwed` too, so the marker is rewritten whether or not the close landed during the load. Tracked via `_wsClosed`/`_markerOwed` rather than routed through `_onLiveOutput()`, since a close landing before the response is stamped before the cutoff and would be dropped with the rest of the pre-capture queue. There is no "Load full history" banner in Pane B, so a shell history past that 1 MiB window stays out of reach there. Non-shell Pane B is unchanged: it already loads `full=1`, and its history is out of scope for this pull (codex and Claude's inline renderer do grow tmux history; this just isn't how they recover it). ⚠️ App-level terminal actions find their pane through `_focusedPane()`, the terminal focused LAST (not `document.activeElement`, which the mic or a header button takes): Ctrl+L, Ctrl+Shift+R, voice and image paste act on Pane B while it holds the keyboard. Ctrl+W is not an app shortcut at all (Close Session has no default key), so it reaches whichever pane is focused as delete-word. ⚠️ Geometry: `TerminalTile.fit()` sends the size the xterm actually holds, unfloored (the divider's 20% clamp leaves about 28 columns), skips an unchanged size, re-sends on every fresh socket, and adopts the PTY's column count from `{t:'zc'}`; the font, family and weight setters call `tile.fit()`, never a local refit alone (#464). Every capture a pane fetches carries a deadline covering the body (`CodemanFetchDeadline`), so a capture that never answers cannot hold its single-flight flag forever. Design: `docs/split-pane-sessions-plan.md`; the tile class: `docs/tile-grid-plan.md`. +**Split-pane sessions** (`showSplitButton`, header button, default OFF, per-device like `showFileViewerButton` — not in `SettingsUpdateSchema`, `displayKeys` in settings-ui.js): shows two live sessions side-by-side in one Codeman window. Pane A is the untouched, existing singleton terminal (`this.terminal`/`this._ws` in terminal-ui.js); Pane B is an independent `TerminalTile` (terminal-tile.js, constructed by the orchestration in terminal-split.js) with its own xterm instance and its own `/ws/sessions/:id/terminal` WebSocket, whose `cid` is the tab's identity with a `:tile` suffix, so it can never supersede the primary pane's socket (the registry supersedes by cid per session). ⚠️ **Pane B is deliberately plainer than Pane A** — no local-echo overlay, no CJK IME, no touch/mobile handlers, no keyboard accessory bar (it does carry the primary pane's hollow-buffer wheel paging and desktop click report, through terminal-ui.js's own gates aimed at the tile; see terminal-tile.js's fileoverview) — since this is a desktop-only feature (a split view needs a wide viewport) and those features exist for mobile/touch input; `.btn-split` is hard-hidden below 1180px regardless of the setting by the `@media (max-width: 1179px)` rule in styles.css (mobile.css only carries a comment pointing at it: that file loads up to 1023px, so it cannot cover the 1024-1179px tablet range the feature also needs to stay off), and the per-device setting means turning it on at a desk can never sync it onto a phone in the first place. No persistence: closing the browser tab or reloading always returns to the normal single-pane view; there is no localStorage key for split state. ⚠️ Splitting a session against itself is disallowed (the picker excludes the active session), **as is splitting against a popped-out (detached) session** — `buildSplitPickerSessions()` excludes `detachedSessions` because a detached session's own window is already claiming its PTY size, and `MAX_WS_PER_SESSION` needs no change since Pane A/B are always two different sessions. ⚠️ Either pane's session ending (deleted locally or from another client) auto-collapses the split — Pane A's session ending promotes Pane B to the new single pane via `selectSession(id, { auto: true })` (an app-driven selection, so it must not spend the session's idle alert — see the Approvals Inbox note above), never by trying to hot-swap the lightweight `TerminalTile` object into the primary singleton state. ⚠️ Pane B refits on every window/sidebar/tab-rail resize via the SAME trailing-edge `ResizeObserver` callback that resizes Pane A (`throttledResize` in terminal-ui.js) — it only ever measured Pane A's own container, so without the explicit `this._forEachTile?.((tile) => tile.fit(), { grid: false })` call there (grid tiles are left out: the grid's own observer refits them on the same resize) Pane B silently kept its stale PTY size through every resize that did not happen to be a divider drag. ⚠️ A dropped WebSocket writes a `[disconnected, reconnecting…]` marker into Pane B and reconnects on the primary pane's backoff ladder (`CodemanWsReconnect` plus jitter; the attempt count resets only on a successful open), then refreshes the buffer to close the output gap. ⚠️ The open handler clears `_wsClosed`/`_markerOwed` BEFORE that refresh, or the refresh re-owes the marker and stamps it under a healthy pane. ⚠️ 4003/4004/4009/4010 stop the pane for good, report once through `onExit(code)` and write a marker saying why (`CodemanWsReconnect` alone would retry 4003). ⚠️ A replacement socket detaches the old one first and every handler ignores a socket that is no longer `this.ws`, so a late 4010 from a superseded socket cannot stop its successor; `destroy()` cancels a pending reconnect. Related but distinct: `detachSession()` already opens one session in a separate OS-level browser window (`isSoloWindow`) — that is prior art for "two sessions visible at once" but not for one window with a draggable in-page divider, which is what this feature adds. ⚠️ Pane B installs its own `attachCustomKeyEventHandler` gating the same app-level chords Pane A's own handler gates (command palette, Alt+1-9/[/] tab nav, Alt+B sidebar toggle, Ctrl+Z suspend, Shift/Ctrl+Enter newline, smart-copy Ctrl+C) — without it the document capture-phase handler's `preventDefault()` (which never stops xterm) let each chord ALSO write its raw byte/escape sequence into Pane B's live PTY on top of whatever the app action did to Pane A (COD-153). Ctrl+Z is swallowed unless Pane B's own session is `mode === 'shell'`, mirroring terminal-ui.js's reasoning: in a plain shell it is the user's own job-control tool, everywhere else it silently suspends an unattended agent loop. Shift/Ctrl+Enter POSTs to `/api/sessions/:id/send-key` (`{key:'S-Enter'|'C-Enter'}`, typed by tmux `send-keys -H`: Ctrl+Enter is always a real 0x0a, Shift+Enter is the CLI's declared `capabilities.newline` chord, also 0x0a unless the CLI declares another; sent on keydown only, with the keypress and keyup swallowed too, see the keypress rule under Command palette and shortcut registry) targeting THIS pane's own `sessionId` rather than the primary pane's `activeSessionId` — without it xterm's plain `\r` would submit an incomplete prompt instead of adding a line to it. Smart-copy Ctrl+C/Ctrl+Shift+C is re-implemented against `this.terminal` (Pane B's own) rather than reusing `app.copyTerminalSelection()`, which reads Pane A's terminal and would copy the wrong pane's selection; Ctrl+Shift+C never falls through even with nothing to copy, mirroring terminal-ui.js's own `ev.shiftKey` branch. ⚠️ **This is a UX-parity fix, not an interrupt-safety one** — verified live in a real browser: xterm's `evaluateKeyboardEvent` routes a shifted ctrl-letter into a branch that assigns `c.key` only for two special cases (`_`→US, `@`→NUL), so it emits no data for Ctrl+Shift+C at all regardless of any application gate; a synthetic keydown with the gate removed produces zero WS frames, proving no accidental interrupt reaches the PTY either way. What gating the whole copy block on `hasSelection()` (an earlier draft) actually cost: with no selection, a selection-less Ctrl+Shift+C fell straight to `return true`, silently ceding the keystroke to the BROWSER's own handling (e.g. Chrome's Inspect-Element binding) with no feedback and no copy attempt — Pane A always intercepts it. Ctrl+V goes through the primary pane's paste trap aimed at Pane B (`_handleImagePaste({ terminal, sessionId })`), so a pasted image uploads to Pane B's session. ⚠️ `buildSplitPickerSessions()` also excludes any session with `pid === null` (an exited CLI, a crash-looped session whose breaker tripped, a restore that never re-attached): Pane B has no equivalent of `selectSession()`'s auto re-attach POST, so a pane opened onto one has nothing reading its tmux pane — no `terminal` events ever arrive, and `Session.write()` silently drops every keystroke with no ack either way, so the loss is invisible behind a socket that reports healthy. Pane B's keystrokes go through the exactly-once queue (`_sendInputAsync`) over its own socket, registered in the app's input-socket map (`_registerInputSocket` / `_inputSocketFor`), so they are seq-tagged, ACKed (`{t:'ia'}` is routed by the RECEIVING socket's session, since the frame names none), redelivered after a drop, and the ACK clears the idle alert. ⚠️ What xterm generates never enters that persisted queue: query replies are dropped (`shouldSuppressTerminalQueryResponse`, as the primary pane drops them) and focus/mouse reports go through `_sendInputEphemeral`, or a reload would replay them as typed text. ⚠️ A SHELL Pane B pulls scrollback itself when the wheel goes up at the top of its buffer (`_maybeLoadMoreHistory`/`_pullHistory`): tmux repaints a burst of output instead of scrolling it, so Pane B's own xterm holds about one screen of scrollback while tmux holds every line, and it loaded history exactly once at connect and never again. It is the same bounded pull as Pane A's (`?full=1&tail=TERMINAL_TAIL_SIZE`, no rewrite when the window holds no more rows than the pane already has or the pane is at its `scrollback + rows` cap, and a 60 s back-off instead of 4 s when that skipped window was truncated or the pane is full, since each ask costs the server a whole-history `capture-pane`), against Pane B's OWN terminal rather than `app.terminal`, so it cannot share `_maybeRefetchFullHistory`. The wheel listener is capture-phase because xterm `stopPropagation()`s the events it consumes; the alternate-screen skip (nano, vim, less) only matters for a direct-PTY shell, since under tmux the browser xterm never enters the alternate buffer; skipped too for a detached session (mirrors `_sendResize()`'s own check and app.js's `_maybeRefetchFullHistory`), since its own window already owns its PTY size and scrollback. Live frames arriving from the response onward, a `{t:'c'}` clear frame included, are held with their arrival time (`_liveQueue`, opened right after `await fetch(...)` beside `capturedAt`; a frame from before it is replaced by the capture or written unchanged, so the pane keeps painting during the round trip) and replayed in order only if they arrived after the capture (the response's arrival stands in for the capture instant, as in `_finishBufferLoad`, so a frame inside that one round trip can be lost or doubled); the request uses the primary pane's budget (`CodemanFetchDeadline.terminalFetchDeadlineMs({ full: true })`, 45 s, 10 s only if that helper is absent) and the body read gets 10 s once the headers land, because from then on the pull holds the pane's live output. The request phase holds no live output, but it does hold the single-flight flag, so a coalesced `{t:'r'}` refresh and a marker owed by a close (below) wait for the response, at worst for that whole budget (accepted: a Codeman restart resets an in-flight request along with the socket, so that pull fails at once and stamps the marker). ⚠️ The "disconnected" marker must be the LAST thing on screen. A replay's own `\x1bc` would otherwise wipe a marker written before the pull and paint a fresh, current-looking history while `onData` keeps silently dropping every keystroke on the dead socket (a Codeman restart drops the socket while the tmux session, and so the HTTP pull, still succeeds), so `_pullHistory()` re-stamps it after the live-frame flush. A close DURING any load (a pull, a refresh; `connect()` awaits the initial load before it creates the socket, so no close lands in that one) writes nothing: `_onSocketClosed()` sets `_markerOwed` while a load's work runs (`_loadRunning`; a load that only waits in the tile grid's queue writes the marker at once, and its refresh clears the screen only when its turn comes), since written there it would sit above the held frames the pull flushes after a skip, a downgrade, a failed fetch or the deadline, above a refresh's replay, or land mid-way through a chunked replay. Each load settles the marker in its OWN `finally` (`_stampMarkerIfOwed()`), after the queue flush, EXCEPT when a trailing refresh is pending: that refresh's `clear()` is synchronous while xterm parses a `write()` on a later tick, so a marker stamped just before it lands in the freshly cleared buffer ABOVE the refresh's replay (a second, stale copy; the default fake terminal in `test/terminal-tile-unit.test.ts` writes synchronously and cannot show it, so an async-parse fake there pins it). The marker stays owed instead, and the trailing refresh, which re-owes it on a closed socket anyway, writes the one copy below its own replay. Anything that wipes the terminal on a closed socket (a replay's `\x1bc`, a refresh's `clear()`) sets `_markerOwed` too, so the marker is rewritten whether or not the close landed during the load. Tracked via `_wsClosed`/`_markerOwed` rather than routed through `_onLiveOutput()`, since a close landing before the response is stamped before the cutoff and would be dropped with the rest of the pre-capture queue. There is no "Load full history" banner in Pane B, so a shell history past that 1 MiB window stays out of reach there. Non-shell Pane B is unchanged: it already loads `full=1`, and its history is out of scope for this pull (codex and Claude's inline renderer do grow tmux history; this just isn't how they recover it). ⚠️ App-level terminal actions find their pane through `_focusedPane()`, the terminal focused LAST (not `document.activeElement`, which the mic or a header button takes): Ctrl+L, Ctrl+Shift+R, voice and image paste act on Pane B while it holds the keyboard. Ctrl+W is not an app shortcut at all (Close Session has no default key), so it reaches whichever pane is focused as delete-word. ⚠️ Geometry: `TerminalTile.fit()` sends the size the xterm actually holds, unfloored (the divider's 20% clamp leaves about 28 columns), skips an unchanged size, re-sends on every fresh socket, and adopts the PTY's column count from `{t:'zc'}`; the font, family and weight setters call `tile.fit()`, never a local refit alone (#464). Every capture a pane fetches carries a deadline covering the body (`CodemanFetchDeadline`), so a capture that never answers cannot hold its single-flight flag forever. Design: `docs/split-pane-sessions-plan.md`; the tile class: `docs/tile-grid-plan.md`. ### Tile grid diff --git a/docs/split-pane-sessions-plan.md b/docs/split-pane-sessions-plan.md index 6d7416d2..6b3259e1 100644 --- a/docs/split-pane-sessions-plan.md +++ b/docs/split-pane-sessions-plan.md @@ -92,7 +92,10 @@ view needs a wide viewport). So: keyboard accessory bar. On a desktop, typing directly into an xterm instance with no overlay is exactly how Codeman behaved before the local- echo overlay existed for touch devices — normal, not degraded, for a - keyboard-and-mouse user. + keyboard-and-mouse user. (Since moved to `TerminalTile`, terminal-tile.js, + which has gained two pieces of the primary pane through its own gates aimed + at the tile: hollow-buffer wheel paging (#555) and the desktop click report + for a CLI with `cliMouseTracking` on. See that file's fileoverview.) If this asymmetry actually bothers you in daily use, promoting Pane B to full parity is a scoped v2 (extract the shared logic already once you have two diff --git a/docs/tile-grid-plan.md b/docs/tile-grid-plan.md index fde97b16..de6612f3 100644 --- a/docs/tile-grid-plan.md +++ b/docs/tile-grid-plan.md @@ -998,7 +998,12 @@ exits green. Use the browser runner for those files and read the file count. 3. WebSocket backpressure (`bufferedAmount` threshold, drop and send `{t:'r'}` on drain) for grids over slow links. 4. Tile parity extras: mouse-wheel forwarding for Claude's fullscreen renderer, - a "Load full history" action inside a tile. + a "Load full history" action inside a tile. (Done since: a tile pages a + hollow buffer's CLI transcript with PageUp/PageDown, the primary pane's + #555 route, and hand-reports a plain click while its session has + `cliMouseTracking` on, both through the primary pane's gates aimed at the + tile. The SGR wheel forwarding itself is still open: a fullscreen Claude + tile leaves the wheel to xterm.) 5. WebGL in tiles, after measuring the DOM renderer with nine busy tiles. 6. Named grid presets, possibly per owner on the server. 7. The end state: the main terminal becomes a 1x1 grid of `TerminalTile`, diff --git a/docs/wiki/The-Dashboard.md b/docs/wiki/The-Dashboard.md index cd9da9e2..0795cef0 100644 --- a/docs/wiki/The-Dashboard.md +++ b/docs/wiki/The-Dashboard.md @@ -219,7 +219,8 @@ Worth knowing: `~/.claude/settings.json`), so the wheel scrolls the conversation rather than the terminal. Claude's default inline view keeps its history in the terminal and scrolls locally. `Shift+Wheel` is always local scrollback. OpenCode's wheel and swipes page its own conversation - (PageUp/PageDown). Other CLIs scroll locally. + (PageUp/PageDown); in a grid tile or the split view's second pane the wheel does + too. Other CLIs scroll locally. - **Selection copy.** `Ctrl+C` copies when text is selected and interrupts when it is not. `Ctrl+Shift+C` always copies. - **Selecting where the CLI owns the mouse.** `Shift+drag` starts a selection even in a pane diff --git a/src/web/public/terminal-tile.js b/src/web/public/terminal-tile.js index 240df0fb..243d4d97 100644 --- a/src/web/public/terminal-tile.js +++ b/src/web/public/terminal-tile.js @@ -11,12 +11,27 @@ * * Deliberately plainer than the primary pane (this.terminal/this._ws in * terminal-ui.js): no local-echo overlay, no CJK IME, no touch/mobile - * handlers, no keyboard accessory bar. Desktop-only by nature; see - * docs/split-pane-sessions-plan.md. + * handlers (a swipe on a touch screen pages nothing), no keyboard accessory + * bar, and no SGR wheel forwarding to Claude's fullscreen renderer + * (docs/tile-grid-plan.md follow-up 4). Built for wide screens; see + * docs/split-pane-sessions-plan.md and docs/tile-grid-plan.md. + * + * What it does carry over from the primary pane, through the primary pane's + * own code aimed at THIS pane (its terminal, its session, never the active + * one): + * - Hollow-buffer paging (#555): a CLI that draws in place (opencode on the + * alternate screen, Claude's repaint mode) leaves the xterm no scrollback, + * so the wheel pages the CLI's own transcript with PageUp/PageDown + * (_maybePageCliTranscript) through the primary pane's gates, plus an + * overflow-row discount for this pane's capture-before-resize load + * (_localRows). + * - The desktop click report: a plain left-click hand-encoded as SGR while + * the session's CLI has mouse tracking on (cliMouseTracking), for the modes + * whose mouse DECSETs the server strips (_installClickListener). * * @dependency vendor/xterm.js, vendor/xterm-addon-fit.js * @dependency constants.js (window.CodemanTerminalFont, window.CodemanFetchDeadline, DEFAULT_SCROLLBACK, TERMINAL_TAIL_SIZE, TERMINAL_CHUNK_SIZE) - * @dependency terminal-ui.js (codemanCurrentXtermTheme, codemanCurrentSkinIsLight) + * @dependency terminal-ui.js (codemanCurrentXtermTheme, codemanCurrentSkinIsLight, CodemanTerminalInput.wheelDeltaLines/pageKeysForTravel, app._shouldForwardWheelToApp/_localScrollbackIsHollow/_handleDesktopTerminalClick) * @loadorder 7.4 of 16, loaded after terminal-ui.js and before terminal-split.js */ @@ -157,6 +172,19 @@ // flag, app._linkHovered, belongs to its terminal alone). this._linkHovered = false; this._onFocusIn = null; + // Hollow-buffer paging (_maybePageCliTranscript): wheel travel short of a + // whole page, carried to the next wheel event. + this._pageKeyPending = 0; + // Page keys waiting for the 40 ms flush, and its timer (_queueScrollBytes). + this._scrollBytes = ''; + this._scrollFlushTimer = null; + // Rows above the screen that this pane pushed there itself rather than + // received as history: a capture taken at the PTY's previous, taller size + // and row-shrinking fits (_overflowAfterLoad, _noteResizeRows). Not + // history, so the paging gate leaves them out (_localRows). + this._overflowRows = 0; + // The desktop click reporter (_installClickListener). + this._onClick = null; } async connect() { @@ -192,6 +220,7 @@ }); this._installWheelListener(); + this._installClickListener(); // Focusing this terminal makes it the pane the keyboard is in, so the // app-level shortcuts, voice and paste act on it (app._focusedPane). @@ -600,6 +629,7 @@ // Cleared at the load's turn, not when it was asked for: a grid tile // waiting in the queue keeps its last frame instead of sitting blank. this.terminal?.clear(); + this._overflowRows = 0; // The clear wipes a "disconnected" marker (a `{t:'r'}` frame can queue // a trailing refresh behind a pull that the socket's close then // interrupts), so a refresh on a closed socket owes it back once its @@ -635,6 +665,7 @@ () => this._destroyed, (cancel) => (this._cancelReplay = cancel) ); + if (!this._destroyed && this.terminal) this._overflowRows = this._overflowAfterLoad(payload); } } catch { /* Best-effort: live output still arrives once the socket connects. */ @@ -699,18 +730,140 @@ // one it is restoring. Queued, it lands in order with the frames around it. _onLiveClear() { if (this._liveQueue) this._liveQueue.push({ at: performance.now(), clear: true }); - else this.terminal?.clear(); + else this._clearTerminal(); + } + + // A clear leaves no rows above the screen, the pane's own overflow included. + _clearTerminal() { + this.terminal?.clear(); + this._overflowRows = 0; } // Capture phase, because xterm's own wheel handler stopPropagation()s every // event it consumes, so a bubbling listener here would never see the wheel - // while the pane still has scrollback to scroll. Passive: this only observes, - // xterm keeps doing the scrolling. + // while the pane still has scrollback to scroll. Not passive: the one route + // this pane takes over, paging a hollow buffer's CLI transcript + // (_maybePageCliTranscript), is consumed right here (preventDefault plus + // stopPropagation in the capture phase, the primary pane's technique), so + // xterm's viewport, a descendant, never sees it. Every other wheel is left + // to xterm, which keeps doing the scrolling, and only observed for the + // shell history pull. _installWheelListener() { this._onWheel = (ev) => { + if (this._maybePageCliTranscript(ev)) { + ev.preventDefault(); + ev.stopPropagation(); + return; + } if (ev.deltaY < 0) this._maybeLoadMoreHistory(); }; - this.mountEl.addEventListener('wheel', this._onWheel, { capture: true, passive: true }); + this.mountEl.addEventListener('wheel', this._onWheel, { capture: true, passive: false }); + } + + // A plain left-click reported to the CLI, the primary pane's desktop click + // (terminal-ui.js _handleDesktopTerminalClick) aimed at this pane. The + // server strips the mouse DECSETs of some modes (opencode's since #555, so a + // drag selects text), which leaves this xterm's own mouse encoder idle for + // them; without this a click in such a pane never reached the CLI. Only + // while this pane's session has tracking on (cliMouseTracking), through the + // same skips as the primary pane. Bubble phase, as there. The target is + // built per click, so the terminal and the link hover are read live. + _installClickListener() { + this._onClick = (ev) => { + if (this._destroyed || !this.terminal) return; + global.app?._handleDesktopTerminalClick?.(ev, { + terminal: this.terminal, + sessionId: this.sessionId, + linkHovered: this._linkHovered, + }); + }; + this.mountEl.addEventListener('click', this._onClick); + } + + // Hollow-buffer paging, the twin of the primary pane's + // _maybePageCliTranscript (terminal-ui.js; keep the two in step). A CLI that + // draws in place (opencode, on the alternate screen; Claude's repaint mode) + // leaves this xterm no scrollback, so a wheel scrolled nothing; instead the + // travel pages the CLI's own transcript with PageUp/PageDown. Every gate is + // the primary pane's own, asked for THIS pane (its terminal, its session, + // never the active one), so the CLI rules stay in terminal-ui.js and this + // file names no CLI. Returns true when the wheel was consumed here. + _maybePageCliTranscript(ev) { + if (this._destroyed || !this.terminal || !ev || ev.shiftKey) return false; + const app = global.app; + const input = global.CodemanTerminalInput; + if (!app || !input?.pageKeysForTravel || !input.wheelDeltaLines) return false; + // xterm's own encoder forwards the wheel while the CLI's tracking reaches + // it (a shell running htop), as in the primary pane. + const tracking = this.terminal.modes?.mouseTrackingMode; + if (tracking && tracking !== 'none') return false; + const target = { terminal: this.terminal, sessionId: this.sessionId }; + // The primary pane would forward this wheel to Claude's fullscreen + // renderer as SGR reports. Tiles do not do that yet (docs/tile-grid-plan.md + // follow-up 4), so the wheel stays with xterm, as before. + if (app._shouldForwardWheelToApp?.(ev, target)) return false; + if (!app._localScrollbackIsHollow?.({ ...target, localRows: this._localRows() })) return false; + const lines = input.wheelDeltaLines(ev, this.terminal.rows); + if (!lines) return false; + const step = input.pageKeysForTravel(this._pageKeyPending, lines, this.terminal.rows); + this._pageKeyPending = step.pending; + if (step.keys) this._queueScrollBytes(step.keys); + return true; + } + + // Coalesces the page keys into one send per 40 ms, bounded at 512 bytes so a + // fling cannot build a backlog that keeps paging after it stops. A narrow + // twin of the primary pane's _queueScrollBytes / _flushWheelSgrQueue + // (terminal-ui.js; keep the two in step), which flushes to the active + // session only. Sent ephemeral (no seq, never persisted) to THIS pane's + // session, over this pane's socket while it is open. + _queueScrollBytes(data) { + if (!data || this._destroyed) return; + if (this._scrollBytes.length > 512) return; + this._scrollBytes += data; + if (this._scrollFlushTimer) return; + this._scrollFlushTimer = setTimeout(() => { + this._scrollFlushTimer = null; + const bytes = this._scrollBytes; + this._scrollBytes = ''; + if (bytes && !this._destroyed) global.app?._sendInputEphemeral?.(this.sessionId, bytes); + }, 40); + } + + // History rows in this xterm, for the paging gate: baseY less the rows this + // pane pushed up itself. Clamped, because a clear (Ctrl+L, a `{t:'c'}` + // frame) or an ED3/RIS in the stream drops rows behind this count's back. + _localRows() { + const baseY = this.terminal?.buffer?.active?.baseY || 0; + this._overflowRows = Math.min(this._overflowRows, baseY); + return baseY - this._overflowRows; + } + + // After a local resize: rows a shrinking fit pushed above the screen count + // as overflow, and rows a growing one pulled back come off it. `before` is + // baseY just before the resize (xterm resizes synchronously). + _noteResizeRows(before) { + const after = this.terminal?.buffer?.active?.baseY || 0; + this._overflowRows = Math.max(0, Math.min(after, this._overflowRows + (after - before))); + } + + // The overflow a finished load leaves: everything above the screen when the + // capture held a single screen (the server says how tall in `captureRows`; + // the full-history path keeps every pane row and trims one newline), none + // when it carried history. The counterpart of the primary pane resizing the + // PTY before it captures (app.js selectSession's sendResize), which this + // pane does not do: its first capture is taken at the PTY's previous size + // (usually the primary pane's, taller) and written into a shorter xterm, + // whose extra rows land above the screen with nothing after them to clear + // them. Without a `captureRows` the raw baseY stands, as in the primary. + _overflowAfterLoad(payload) { + const captureRows = payload?.captureRows; + if (!Number.isFinite(captureRows)) return 0; + const text = payload.terminalBuffer || ''; + let lines = 1; + for (let i = text.indexOf('\n'); i !== -1 && lines <= captureRows; i = text.indexOf('\n', i + 1)) lines++; + if (lines > captureRows) return 0; + return this.terminal?.buffer?.active?.baseY || 0; } // Wheel-up at the top of a SHELL pane's scrollback. tmux repaints a burst of @@ -818,6 +971,7 @@ } this._historyPullUseless = false; term.write('\x1bc'); + this._overflowRows = 0; // the reset leaves nothing above the screen replayed = true; if (this._wsClosed) this._markerOwed = true; await writeChunked( @@ -849,7 +1003,7 @@ const cutoff = replayed ? capturedAt : 0; for (const entry of queued) { if (entry.at < cutoff) continue; - if (entry.clear) this.terminal?.clear(); + if (entry.clear) this._clearTerminal(); else this.terminal?.write(entry.data); } // Settled after the queue flush so the marker is the last thing on @@ -894,7 +1048,9 @@ // pane's own convention (throttledResize in terminal-ui.js). localFit() { if (!this.fitAddon) return; + const before = this.terminal?.buffer?.active?.baseY || 0; this.fitAddon.fit(); + this._noteResizeRows(before); } // Reflow to the container and tell the PTY, as one step: the xterm and the @@ -955,7 +1111,9 @@ { cols, rows } ); if (!verdict?.adopt) return; + const before = terminal.buffer?.active?.baseY || 0; terminal.resize(verdict.cols, terminal.rows); + this._noteResizeRows(before); // a column change reflows rows above the screen this._lastSentDims = { cols: verdict.cols, rows: terminal.rows }; } @@ -982,6 +1140,15 @@ this.mountEl?.removeEventListener('wheel', this._onWheel, { capture: true }); this._onWheel = null; } + if (this._onClick) { + this.mountEl?.removeEventListener('click', this._onClick); + this._onClick = null; + } + // Page keys still waiting for their flush go nowhere: the pane is gone. + clearTimeout(this._scrollFlushTimer); + this._scrollFlushTimer = null; + this._scrollBytes = ''; + this._pageKeyPending = 0; this._detachSocket(); if (this._onFocusIn) { this.terminal?.textarea?.removeEventListener('focus', this._onFocusIn); diff --git a/test/frontend-cli-no-id-branching.test.ts b/test/frontend-cli-no-id-branching.test.ts index ba098bc7..e4f3aa30 100644 --- a/test/frontend-cli-no-id-branching.test.ts +++ b/test/frontend-cli-no-id-branching.test.ts @@ -3,7 +3,9 @@ * (`session-ui.js`, `mobile-overview.js`), plus the files that draw a session * header's harness logo and model (`constants.js`, `terminal-split.js`, * `tile-grid.js`: the logo's `run-mode-dot <cliId>` class is the id as DATA), - * mirroring + * and `terminal-tile.js`, whose wheel paging and click reports reach the + * primary pane's CLI rules through terminal-ui.js and must not grow a copy of + * them, mirroring * `test/cli-registry-no-id-branching.test.ts` for the backend registry. * * Deliberately scoped to ONLY these two files, not all of `src/web/public/`. @@ -24,7 +26,14 @@ import { fileURLToPath } from 'node:url'; import { STOCK_CLIS } from '../src/config/cli-registry/stock.js'; const PUBLIC = fileURLToPath(new URL('../src/web/public/', import.meta.url)); -const SCANNED_FILES = ['session-ui.js', 'mobile-overview.js', 'constants.js', 'terminal-split.js', 'tile-grid.js']; +const SCANNED_FILES = [ + 'session-ui.js', + 'mobile-overview.js', + 'constants.js', + 'terminal-split.js', + 'tile-grid.js', + 'terminal-tile.js', +]; /** * Every currently-surviving branch, each with the COUNT of physical call @@ -100,6 +109,20 @@ const ALLOWED_BRANCHES: Record<string, { count: number; reason: string }> = { reason: 'attach route: a shell session attaches through /shell, an agent through /interactive', }, + // terminal-tile.js: the pane's two shell-only mechanisms, both mirrors of the + // primary pane's own shell checks (terminal-ui.js / app.js). Its wheel + // paging and click reports name no CLI: they ask terminal-ui.js's gates. + "terminal-tile.js::mode !== 'shell'": { + count: 2, + reason: + 'Ctrl+Z reaches the PTY only in a shell (job control), and the scroll-to-top history pull is shell-only, ' + + 'both as in the primary pane', + }, + "terminal-tile.js::mode === 'shell'": { + count: 1, + reason: 'the load query: a shell loads the bounded tail= window instead of a full capture, as in the primary pane', + }, + // mobile-overview.js: shell is exempt from the isCliAvailable() gate the // same way the toolbar's #runModeMenu exempts it (shell needs no CLI). "mobile-overview.js::mode !== 'shell'": { @@ -188,7 +211,7 @@ function actualCounts(): Map<string, number> { } describe('no NEW CLI-id branching in the scanned frontend files', () => { - it('scans both files (sanity)', () => { + it('scans every listed file (sanity)', () => { // If this drops to zero the scanner or the file list drifted and every // assertion below would pass vacuously. const scannedBytes = SCANNED_FILES.reduce((n, f) => n + readFileSync(PUBLIC + f, 'utf-8').length, 0); diff --git a/test/mocks/terminal-tile-fakes.ts b/test/mocks/terminal-tile-fakes.ts index 63eb82b9..3bb4a349 100644 --- a/test/mocks/terminal-tile-fakes.ts +++ b/test/mocks/terminal-tile-fakes.ts @@ -61,15 +61,45 @@ export class FakeFit { /** An xterm that records writes, resizes and its handlers; `type()` feeds onData like a keystroke. */ export class FakeTerminal { static last: FakeTerminal | null = null; + /** + * Opt-in, set by a test BEFORE the tile connects: the buffer's rows follow + * what is written, as in xterm. Every `\n` adds a line, `baseY` is the lines + * beyond the screen, a clear leaves one line, and a resize recomputes it + * (a row-shrinking fit pushes rows above the screen, a growing one pulls them + * back). The viewport follows the bottom. Off, `baseY` stays where a test + * puts it. + */ + static emulateScroll = false; options: Record<string, unknown>; cols = 80; rows = 24; dataCb: ((data: string) => void) | null = null; - buffer = { active: { type: 'normal', viewportY: 0, length: 24 } }; + buffer = { active: { type: 'normal', viewportY: 0, baseY: 0, length: 24 } }; + /** xterm's own mouse-tracking mode (DECSET 1000 and friends); 'none' while no app asked for the mouse. */ + modes = { mouseTrackingMode: 'none' }; + /** Lines in the buffer while emulating (the cursor line counts). */ + lineCount = 1; + emulate = FakeTerminal.emulateScroll; + /** Called after an emulated resize, so a test can stand in for a reflow. */ + afterResize: ((cols: number, rows: number) => void) | null = null; + /** Where the screen sits and how big a cell renders, for the click-to-cell math. */ + screenRect = { left: 10, top: 20 }; + element = { + querySelector: (sel: string) => + sel === '.xterm-screen' ? { getBoundingClientRect: () => ({ ...this.screenRect }) } : null, + }; + _core = { _renderService: { dimensions: { css: { cell: { width: 8, height: 16 } } } } }; constructor(options: Record<string, unknown>) { this.options = { ...options }; FakeTerminal.last = this; } + /** Re-derives baseY (and a viewport following the bottom) from the emulated line count. */ + settleRows() { + const active = this.buffer.active; + active.baseY = Math.max(0, this.lineCount - this.rows); + active.viewportY = active.baseY; + active.length = Math.max(this.lineCount, this.rows); + } loadAddon(addon: FakeFit) { addon.term = this; } @@ -101,16 +131,28 @@ export class FakeTerminal { // An empty write puts nothing on screen; the replay queues one only to hear // (its callback) that everything before it has been parsed. if (data) this.writes.push(data); + if (data && this.emulate) { + this.lineCount += data.split('\n').length - 1; + this.settleRows(); + } if (!this.holdParse) cb?.(); } clear() { this.writes.push('<CLEAR>'); + if (this.emulate) { + this.lineCount = 1; + this.settleRows(); + } } resizes: Array<[number, number]> = []; resize(cols: number, rows: number) { this.resizes.push([cols, rows]); this.cols = cols; this.rows = rows; + if (this.emulate) { + this.settleRows(); + this.afterResize?.(cols, rows); + } } scrollToLine() {} scrollToTop() {} diff --git a/test/terminal-tile-scroll.browser.test.ts b/test/terminal-tile-scroll.browser.test.ts new file mode 100644 index 00000000..a37ae39b --- /dev/null +++ b/test/terminal-tile-scroll.browser.test.ts @@ -0,0 +1,176 @@ +/** + * @fileoverview Real Chromium + real xterm coverage for a TerminalTile's + * hollow-buffer paging (#555 parity), the parts a fake xterm cannot prove: + * + * - the capture-phase wheel listener on the tile's mount really keeps the + * paged wheel away from xterm (its viewport does not move into the stale + * rows above the screen), while a wheel the tile does not page still + * reaches xterm and scrolls it, and + * - real xterm puts a one-screen capture taken at a taller size above the + * screen, and a row-shrinking fit pushes more rows up, which is what the + * tile's overflow discount (`_localRows`) counts. Output that scrolls real + * lines is history, and the tile stops paging. + * + * The wheel is a real one (`page.mouse.wheel()`), and the last step proves it + * reaches xterm: a wheel the tile does not page scrolls xterm's viewport, so + * "xterm did not scroll" on a paged wheel means something. What keeps xterm + * still there is the tile's preventDefault (xterm 6's scrollable element skips + * a wheel whose default was prevented); its stopPropagation, the primary + * pane's other half, keeps xterm's own handlers from seeing the event at all. + * Dropping both makes this test fail. + * + * The tile's load and socket are stubbed in the page (fetch answers its one + * capture, WebSocket never opens), so nothing here needs a PTY; the page keys + * are read from a spy on `app._sendInputEphemeral`. The gates themselves are + * the real ones in terminal-ui.js, asked for the tile's own session. + * + * Port: ephemeral (`new WebServer(0, …)`, read back from `boundPort`). + */ +import { describe, it, expect, beforeAll, afterAll } from 'vitest'; +import { chromium, type Browser, type Page } from 'playwright'; +import { WebServer } from '../src/web/server.js'; + +const PROBE_ID = 'tile-scroll-probe'; + +type Snap = { rows: number; baseY: number; viewportY: number; localRows: number; sent: Array<[string, string]> }; + +describe('TerminalTile wheel paging in a real browser', () => { + let server: WebServer; + let browser: Browser; + let page: Page; + + beforeAll(async () => { + server = new WebServer(0, false, true); + await server.start(); + browser = await chromium.launch({ headless: true }); + page = await browser.newPage({ viewport: { width: 1280, height: 900 }, deviceScaleFactor: 1 }); + await page.goto(`http://localhost:${server.boundPort}`, { waitUntil: 'domcontentloaded' }); + await page.waitForFunction(() => (window as any).app?.terminal && (window as any).TerminalTile, null, { + timeout: 30000, + }); + }, 90000); + + afterAll(async () => { + if (browser) await browser.close(); + if (server) await server.stop(); + }, 60000); + + /** The tile's state plus every page key sent so far. */ + const snap = () => + page.evaluate(() => { + const probe = (window as any).__tileProbe; + const term = probe.tile.terminal; + return { + rows: term.rows, + baseY: term.buffer.active.baseY, + viewportY: term.buffer.active.viewportY, + localRows: probe.tile._localRows(), + sent: probe.sent.slice(), + } as Snap; + }); + + /** A real wheel-up of a whole screen over the tile, then time for the 40 ms flush and a frame. */ + async function wheelUp(rows: number) { + await page.mouse.move(200, 60); + await page.mouse.wheel(0, -rows * 25); + await page.waitForTimeout(150); + } + + it('pages a hollow tile, keeps xterm still, survives a shrink, and stops once real lines scroll', async () => { + await page.evaluate(async (id) => { + const w = window as any; + const app = w.app; + const CAPTURE_ROWS = 40; + const capture = Array.from({ length: CAPTURE_ROWS }, (_, i) => `row ${i}`).join('\r\n'); + + // The tile's session, as the app knows it: opencode, which draws in place. + app.sessions.set(id, { id, mode: 'opencode' }); + const sent: Array<[string, string]> = []; + const realEphemeral = app._sendInputEphemeral; + app._sendInputEphemeral = (sessionId: string, data: string) => sent.push([sessionId, data]); + const realFetch = w.fetch; + w.fetch = async (url: string, init?: unknown) => + String(url).includes(`/api/sessions/${id}/terminal`) + ? new Response(JSON.stringify({ data: { terminalBuffer: capture, captureRows: CAPTURE_ROWS } })) + : realFetch(url, init); + const RealWebSocket = w.WebSocket; + w.WebSocket = class { + static OPEN = 1; + readyState = 0; + send() {} + close() {} + }; + + const mount = document.createElement('div'); + mount.style.cssText = 'position:fixed;left:0;top:0;width:640px;height:300px;z-index:99999;background:#000'; + document.body.appendChild(mount); + const tile = new w.TerminalTile(id, mount, { mode: 'opencode' }); + try { + await tile.connect(); + } finally { + w.fetch = realFetch; + w.WebSocket = RealWebSocket; + } + w.__tileProbe = { tile, mount, sent, realEphemeral }; + }, PROBE_ID); + + try { + // A 40-row capture in a shorter xterm: the extra rows sit above the + // screen, and the tile counts every one of them as its own overflow. + const afterLoad = await snap(); + expect(afterLoad.rows).toBeLessThan(40); + expect(afterLoad.baseY).toBe(40 - afterLoad.rows); + expect(afterLoad.viewportY).toBe(afterLoad.baseY); + expect(afterLoad.localRows).toBe(0); + + // The wheel is consumed and paged: xterm never saw it, so its viewport + // stayed at the bottom instead of scrolling into the stale rows. + await wheelUp(afterLoad.rows); + const afterWheel = await snap(); + expect(afterWheel.viewportY).toBe(afterLoad.baseY); + expect(afterWheel.sent.length).toBeGreaterThanOrEqual(1); + expect(afterWheel.sent.every(([id]) => id === PROBE_ID)).toBe(true); + expect(afterWheel.sent.map(([, data]) => data).join('')).toMatch(/^(?:\x1b\[5~)+$/); + + // A row-shrinking fit pushes more rows up; still not history, still paged. + await page.evaluate(() => { + const probe = (window as any).__tileProbe; + probe.mount.style.height = '200px'; + probe.tile.localFit(); + }); + const afterShrink = await snap(); + expect(afterShrink.rows).toBeLessThan(afterLoad.rows); + expect(afterShrink.baseY).toBeGreaterThan(afterLoad.baseY); + expect(afterShrink.localRows).toBe(0); + await wheelUp(afterShrink.rows); + const afterSecondWheel = await snap(); + expect(afterSecondWheel.sent.length).toBeGreaterThan(afterWheel.sent.length); + expect(afterSecondWheel.viewportY).toBe(afterShrink.baseY); + + // Output that scrolled real lines is history: the wheel goes back to + // xterm, which scrolls its own buffer, and no page key is sent. + await page.evaluate( + () => + new Promise((resolve) => + (window as any).__tileProbe.tile.terminal.write('real 1\r\nreal 2\r\nreal 3\r\n', resolve) + ) + ); + const afterOutput = await snap(); + expect(afterOutput.localRows).toBe(3); + await wheelUp(afterOutput.rows); + const afterThirdWheel = await snap(); + expect(afterThirdWheel.sent.length).toBe(afterSecondWheel.sent.length); + expect(afterThirdWheel.viewportY).toBeLessThan(afterOutput.baseY); + } finally { + await page.evaluate((id) => { + const w = window as any; + const probe = w.__tileProbe; + probe.tile.destroy(); + probe.mount.remove(); + w.app.sessions.delete(id); + w.app._sendInputEphemeral = probe.realEphemeral; + delete w.__tileProbe; + }, PROBE_ID); + } + }); +}); diff --git a/test/terminal-tile-scroll.test.ts b/test/terminal-tile-scroll.test.ts new file mode 100644 index 00000000..4a4e55d5 --- /dev/null +++ b/test/terminal-tile-scroll.test.ts @@ -0,0 +1,573 @@ +/** + * @fileoverview A TerminalTile pages a hollow buffer's CLI transcript, and + * reports a plain click to a CLI whose mouse DECSETs the server strips, the way + * the primary pane does (#555), through the primary pane's own gates aimed at + * the TILE: its terminal, its session, never the active one. + * + * opencode draws in place on the alternate screen, so tmux keeps no history + * for it and the browser's buffer holds one screen. The primary pane turns the + * wheel into PageUp/PageDown there (`_maybePageCliTranscript`, terminal-ui.js); + * a tile left the wheel to xterm, which scrolled nothing. #555 also strips + * opencode's mouse DECSETs on the server, which reaches tile sockets too: a + * drag selects text again, but xterm's own encoder no longer reports a click, + * so the tile now hand-encodes it like the primary pane. + * + * A tile's buffer is rarely empty above the screen even so: its first capture + * is taken at the PTY's previous, taller size and written into a shorter + * xterm, and its own row-shrinking fits push more rows up. Those rows are not + * history, so the tile discounts them (`_localRows`); the overflow cases below + * fail without that discount. + * + * Real code under test: constants.js + app.js + terminal-ui.js + + * terminal-tile.js in one `vm` context, as in terminal-tile-input.test.ts. + * xterm, the fit addon and WebSocket are fakes (test/mocks/terminal-tile-fakes.ts), + * with the fake xterm's row emulation switched on. + * + * Port: none (no server, no browser). + */ +import { readFileSync } from 'node:fs'; +import { performance } from 'node:perf_hooks'; +import { resolve } from 'node:path'; +import vm from 'node:vm'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { FakeFit, FakeSocket, FakeTerminal } from './mocks/terminal-tile-fakes.js'; + +const fetchMock = vi.fn(); + +function loadContext() { + const read = (f: string) => readFileSync(resolve(import.meta.dirname, `../src/web/public/${f}`), 'utf8'); + const windowStub: Record<string, unknown> = { + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + CodemanBase: { base: '' }, + }; + const context = vm.createContext({ + console: { ...console, log: vi.fn(), debug: vi.fn() }, + performance, + setInterval: vi.fn(), + clearInterval: vi.fn(), + // Late-bound, so vi.useFakeTimers() (which swaps the globals) reaches code + // running inside this context. + setTimeout: (fn: () => void, ms?: number) => globalThis.setTimeout(fn, ms), + clearTimeout: (id: ReturnType<typeof setTimeout>) => globalThis.clearTimeout(id), + requestAnimationFrame: vi.fn(), + HTMLCanvasElement: class HTMLCanvasElement {}, + WebSocket: FakeSocket, + Terminal: FakeTerminal, + FitAddon: { FitAddon: FakeFit }, + fetch: (...args: unknown[]) => fetchMock(...args), + location: { protocol: 'http:', host: 'codeman.test' }, + document: { addEventListener: vi.fn(), documentElement: { dataset: {} } }, + localStorage: { length: 0, key: vi.fn(), getItem: vi.fn(), setItem: vi.fn(), removeItem: vi.fn() }, + window: windowStub, + MobileDetection: { + isTouchDevice: () => false, + isHandheldDevice: () => false, + getDeviceType: () => 'desktop', + }, + }); + vm.runInContext( + `${read('constants.js')}\n${read('app.js')}\n${read('terminal-ui.js')}\n${read('terminal-tile.js')}\n` + + 'globalThis.__CodemanApp = CodemanApp;', + context + ); + return { + CodemanApp: (context as unknown as { __CodemanApp: { prototype: object } }).__CodemanApp, + windowStub, + }; +} + +const { CodemanApp, windowStub } = loadContext(); + +type Session = { mode: string; cliVersion?: string; cliMouseTracking?: boolean }; +type App = Record<string, unknown> & { + sessions: Map<string, Session>; + activeSessionId: string | null; + _linkHovered?: boolean; + loadAppSettingsFromStorage: () => Record<string, unknown>; +}; + +function makeApp(sessions: Record<string, Session>, activeSessionId: string | null = 'other'): App { + const app = Object.create(CodemanApp.prototype) as App; + app._clientId = 'c-test'; + app._wsTabNonce = 'nonce-1'; + app._seqCounters = new Map(); + app._pendingDeliveries = new Map(); + app._postDraining = new Set(); + app._extraInputSockets = new Map(); + app._persistReliableState = vi.fn(); + app._persistReliableNow = vi.fn(); + app._updateConnectionIndicator = vi.fn(); + app.markIdleAlertSeen = vi.fn(); + app.showToast = vi.fn(); + app.loadAppSettingsFromStorage = () => ({}); + app._ws = null; + app._wsSessionId = null; + app._estimateReplayRows = (text: string) => text.split('\n').length; + app.sessions = new Map(Object.entries(sessions)); + app.activeSessionId = activeSessionId; + return app; +} + +/** The tile's mount element: records its listeners by type, with their options. */ +function makeMount() { + const listeners: Record<string, Array<{ fn: (ev: unknown) => void; opts: unknown }>> = {}; + return { + listeners, + addEventListener: vi.fn((type: string, fn: (ev: unknown) => void, opts?: unknown) => { + (listeners[type] ||= []).push({ fn, opts }); + }), + removeEventListener: vi.fn(), + fire(type: string, ev: unknown) { + for (const { fn } of listeners[type] || []) fn(ev); + }, + }; +} + +type Tile = { + connect(): Promise<void>; + destroy(): void; + fit(opts?: { force?: boolean }): void; + ws: FakeSocket | null; + sessionId: string; + _linkHovered: boolean; + _scrollFlushTimer: unknown; + _onPtyGeometryReport(cols: number, rows: number): void; +}; +const TerminalTile = windowStub.TerminalTile as new (id: string, mount: unknown, opts?: object) => Tile; + +const liveTiles: Tile[] = []; + +const lines = (n: number) => Array.from({ length: n }, (_, i) => `row ${i}`).join('\r\n'); + +/** The capture a tile's first load receives. `captureRows` absent = the server could not say. */ +function serveCapture(terminalBuffer: string, captureRows?: number) { + fetchMock.mockImplementation(async () => ({ + ok: true, + status: 200, + json: async () => ({ data: { terminalBuffer, ...(captureRows === undefined ? {} : { captureRows }) } }), + })); +} + +async function connectTile(app: App, opts: { sessionId?: string; mode?: string } = {}) { + windowStub.app = app; + const mount = makeMount(); + const tile = new TerminalTile(opts.sessionId ?? 's-tile', mount, { mode: opts.mode ?? 'opencode' }); + liveTiles.push(tile); + await tile.connect(); + const ws = FakeSocket.instances.at(-1)!; + ws.open(); + return { tile, ws, term: FakeTerminal.last!, mount }; +} + +function wheel(deltaY: number, extra: Record<string, unknown> = {}) { + return { + deltaY, + deltaX: 0, + deltaMode: 0, + shiftKey: false, + preventDefault: vi.fn(), + stopPropagation: vi.fn(), + ...extra, + }; +} + +/** One wheel event worth `rowsOfTravel` lines (pixel mode: 25 px a line). */ +const wheelLines = (rowsOfTravel: number, extra: Record<string, unknown> = {}) => wheel(rowsOfTravel * 25, extra); + +const PAGE_UP = '\x1b[5~'; +const PAGE_DOWN = '\x1b[6~'; + +/** Frames the tile's socket sent once the 40 ms coalescer has flushed. */ +function flushed(ws: FakeSocket) { + vi.advanceTimersByTime(40); + return ws.inputFrames(); +} + +beforeEach(() => { + vi.useFakeTimers(); + FakeFit.proposed = { cols: 80, rows: 24 }; + FakeSocket.instances = []; + FakeTerminal.emulateScroll = true; + fetchMock.mockReset(); + serveCapture(lines(10), 24); +}); + +afterEach(() => { + for (const tile of liveTiles.splice(0)) tile.destroy(); + FakeTerminal.emulateScroll = false; + vi.useRealTimers(); +}); + +describe('a tile pages a hollow buffer through the primary pane gates', () => { + it('turns half a screen of wheel-up into one ephemeral PageUp on its own socket, and down into PageDown', async () => { + const { ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + expect(term.buffer.active.baseY).toBe(0); + + const up = wheelLines(-term.rows / 2); + mount.fire('wheel', up); + + expect(up.preventDefault).toHaveBeenCalled(); + expect(up.stopPropagation).toHaveBeenCalled(); + expect(ws.inputFrames()).toEqual([]); // coalesced, not sent per event + expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]); // no seq: never persisted + + mount.fire('wheel', wheelLines(term.rows / 2)); + expect(flushed(ws).at(-1)).toEqual({ t: 'i', d: PAGE_DOWN }); + }); + + it("reads the TILE's session, not the active one", async () => { + // Active session is a shell; the tile shows opencode: the tile still pages. + const app = makeApp({ other: { mode: 'shell' }, 's-tile': { mode: 'opencode' } }, 'other'); + const { ws, mount } = await connectTile(app); + + mount.fire('wheel', wheelLines(-12)); + + expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]); + }); + + it.each(['shell', 'codex', 'antigravity'])( + 'leaves a %s tile to xterm even while the active session is opencode', + async (mode) => { + const app = makeApp({ other: { mode: 'opencode' }, 's-tile': { mode } }, 'other'); + const { ws, mount } = await connectTile(app, { mode }); + + const ev = wheelLines(-12); + mount.fire('wheel', ev); + + expect(ev.preventDefault).not.toHaveBeenCalled(); + expect(ev.stopPropagation).not.toHaveBeenCalled(); + expect(flushed(ws)).toEqual([]); + } + ); + + it('still pulls history on a wheel-up at the top of a shell tile', async () => { + const { mount } = await connectTile(makeApp({ 's-tile': { mode: 'shell' } }), { mode: 'shell' }); + expect(fetchMock).toHaveBeenCalledTimes(1); // the initial load + + mount.fire('wheel', wheelLines(-3)); + await vi.advanceTimersByTimeAsync(0); + + expect(fetchMock).toHaveBeenCalledTimes(2); + expect(String(fetchMock.mock.calls[1][0])).toContain('full=1&tail='); + }); + + it('never pages Shift, a tracking xterm, the alternate buffer, real history or a horizontal swipe', async () => { + const { ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + const fireAndCheck = (ev: ReturnType<typeof wheel>) => { + mount.fire('wheel', ev); + expect(ev.preventDefault).not.toHaveBeenCalled(); + expect(ev.stopPropagation).not.toHaveBeenCalled(); + }; + + fireAndCheck(wheelLines(-12, { shiftKey: true })); // the explicit "local scrollback" gesture + + term.modes.mouseTrackingMode = 'any'; // xterm's own encoder forwards the wheel + fireAndCheck(wheelLines(-12)); + term.modes.mouseTrackingMode = 'none'; + + term.buffer.active.type = 'alternate'; // xterm's alt-scroll owns it + fireAndCheck(wheelLines(-12)); + term.buffer.active.type = 'normal'; + + fireAndCheck(wheel(0, { deltaX: 120 })); // pure horizontal: nothing to page + + term.write(lines(40)); // real output scrolled real lines above the screen + expect(term.buffer.active.baseY).toBeGreaterThan(0); + fireAndCheck(wheelLines(-12)); + + expect(flushed(ws)).toEqual([]); + }); +}); + +describe("the forwarding gate behaves as in the primary pane, for the tile's session", () => { + it('leaves a fullscreen Claude tile to xterm (tiles do not forward SGR wheel yet)', async () => { + const app = makeApp({ 's-tile': { mode: 'claude', cliVersion: '2.1.223', cliMouseTracking: true } }); + const { ws, mount } = await connectTile(app, { mode: 'claude' }); + + const ev = wheelLines(-12); + mount.fire('wheel', ev); + + expect(ev.preventDefault).not.toHaveBeenCalled(); + expect(flushed(ws)).toEqual([]); + }); + + it('pages that same tile under the "Wheel scrolls local history" opt-out (the footgun rescue)', async () => { + const app = makeApp({ 's-tile': { mode: 'claude', cliVersion: '2.1.223', cliMouseTracking: true } }); + app.loadAppSettingsFromStorage = () => ({ terminalWheelLocalScrollback: true }); + const { ws, mount } = await connectTile(app, { mode: 'claude' }); + + mount.fire('wheel', wheelLines(-12)); + + expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]); + }); + + it('pages a Claude tile whose CLI version is unknown', async () => { + const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'claude', cliMouseTracking: true } }), { + mode: 'claude', + }); + + mount.fire('wheel', wheelLines(-12)); + + expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]); + }); +}); + +describe('page-key travel, cap and coalescing', () => { + beforeEach(() => { + FakeFit.proposed = { cols: 80, rows: 36 }; + }); + + it('accumulates sub-page travel: two wheels of 10 lines are one PageUp', async () => { + const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + + mount.fire('wheel', wheelLines(-10)); + expect(flushed(ws)).toEqual([]); + mount.fire('wheel', wheelLines(-10)); + + expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]); + }); + + it('caps one wheel at three PageUps, in one frame', async () => { + const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + + mount.fire('wheel', wheelLines(-1000)); + + expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP.repeat(3) }]); + }); + + it('sends two pages queued within 40 ms as one frame', async () => { + const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + + mount.fire('wheel', wheelLines(-18)); + vi.advanceTimersByTime(20); + mount.fire('wheel', wheelLines(-18)); + + expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP.repeat(2) }]); + }); + + it('sends exactly the bytes the primary pane sends for the same wheel sequence', async () => { + const sequence = [-10, -10, -4, 30, -1000, 7, -18, 200].map((n) => wheelLines(n)); + const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + for (const ev of sequence) mount.fire('wheel', ev); + const tileBytes = flushed(ws) + .map((f) => f.d) + .join(''); + + const primary = makeApp({ other: { mode: 'opencode' } }, 'other') as App & { + terminal: unknown; + _maybePageCliTranscript(ev: unknown, lines: number): boolean; + _wheelScrollLinesFloat(ev: unknown): number; + _flushWheelSgrQueue(): void; + }; + const sent: string[] = []; + primary._sendInputEphemeral = (_id: string, data: string) => sent.push(data); + primary.terminal = { + rows: 36, + modes: { mouseTrackingMode: 'none' }, + buffer: { active: { type: 'normal', baseY: 0, viewportY: 0 } }, + }; + for (const ev of sequence) primary._maybePageCliTranscript(ev, primary._wheelScrollLinesFloat(ev)); + primary._flushWheelSgrQueue(); + + expect(tileBytes).not.toBe(''); + expect(tileBytes).toBe(sent.join('')); + }); +}); + +describe('rows the tile pushed above the screen itself are not history', () => { + it('pages after a one-screen capture taken at a taller size (the first load)', async () => { + serveCapture(lines(40), 40); // the PTY was 40 rows when it was captured + const { ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + expect(term.buffer.active.baseY).toBe(16); // 40 lines into a 24-row xterm + + mount.fire('wheel', wheelLines(-12)); + + expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]); + }); + + it('does not page a capture that carried real history', async () => { + serveCapture(lines(60), 24); + const { ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + expect(term.buffer.active.baseY).toBeGreaterThan(0); + + const ev = wheelLines(-12); + mount.fire('wheel', ev); + + expect(ev.preventDefault).not.toHaveBeenCalled(); + expect(flushed(ws)).toEqual([]); + }); + + it('falls back to the raw baseY when the server sent no captureRows', async () => { + serveCapture(lines(40)); + const tall = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + expect(tall.term.buffer.active.baseY).toBe(16); + tall.mount.fire('wheel', wheelLines(-12)); + expect(flushed(tall.ws)).toEqual([]); + + serveCapture(lines(10)); + const short = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + expect(short.term.buffer.active.baseY).toBe(0); + short.mount.fire('wheel', wheelLines(-12)); + expect(flushed(short.ws)).toEqual([{ t: 'i', d: PAGE_UP }]); + }); + + it('keeps paging after a row-shrinking fit pushes more rows up', async () => { + serveCapture(lines(40), 40); + const { tile, ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + + FakeFit.proposed = { cols: 80, rows: 20 }; // a zoom-out or a divider drag + tile.fit(); + expect(term.buffer.active.baseY).toBe(20); + + mount.fire('wheel', wheelLines(-10)); + expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]); + }); + + it('stops paging once output scrolls real lines above the screen', async () => { + serveCapture(lines(40), 40); + const { ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + + ws.receive({ t: 'o', d: 'a\r\nb\r\nc\r\n' }); // three real lines scrolled off + + const ev = wheelLines(-12); + mount.fire('wheel', ev); + expect(ev.preventDefault).not.toHaveBeenCalled(); + expect(flushed(ws)).toEqual([]); + }); + + it('forgets the overflow on a server clear, so later real history counts', async () => { + serveCapture(lines(40), 40); + const { ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + + ws.receive({ t: 'c' }); + expect(term.buffer.active.baseY).toBe(0); + ws.receive({ t: 'o', d: '\r\n'.repeat(term.rows + 1) }); // two real lines above the screen + expect(term.buffer.active.baseY).toBe(2); + + const ev = wheelLines(-12); + mount.fire('wheel', ev); + expect(ev.preventDefault).not.toHaveBeenCalled(); + expect(flushed(ws)).toEqual([]); + }); + + it('keeps paging when the PTY geometry report reflows the rows above the screen', async () => { + serveCapture(lines(40), 40); + const { tile, ws, term, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + // A narrower width wraps the overflow rows onto more rows, as xterm's reflow does. + term.afterResize = () => { + term.lineCount += 3; + term.settleRows(); + }; + + tile._onPtyGeometryReport(60, 40); + expect(term.cols).toBe(60); + expect(term.buffer.active.baseY).toBe(19); + + mount.fire('wheel', wheelLines(-12)); + expect(flushed(ws)).toEqual([{ t: 'i', d: PAGE_UP }]); + }); +}); + +describe('a tile reports a plain click to a CLI with mouse tracking on', () => { + const click = (overrides: Record<string, unknown> = {}) => ({ + isTrusted: true, + button: 0, + detail: 1, + // 10 + 8 * 20 + 1, 20 + 16 * 5 + 1 inside the tile's own screen: column 21, row 6. + clientX: 171, + clientY: 101, + target: { closest: (sel: string) => (sel === '.xterm-screen' ? {} : null) }, + ...overrides, + }); + const TAP = '\x1b[<0;21;6M\x1b[<0;21;6m'; + + it("sends one seq-tagged SGR press+release on the tile's socket, from the tile's own geometry", async () => { + const app = makeApp({ other: { mode: 'shell' }, 's-tile': { mode: 'opencode', cliMouseTracking: true } }); + const { ws, mount } = await connectTile(app); + + mount.fire('click', click()); + + expect(ws.inputFrames().map((f) => [f.d, typeof f.seq])).toEqual([[TAP, 'number']]); + }); + + it('sends nothing without the flag, over a selection, over its own hovered link, or scrolled up', async () => { + const app = makeApp({ 's-tile': { mode: 'opencode' } }); + const { tile, ws, term, mount } = await connectTile(app); + + mount.fire('click', click()); // the CLI has no tracking mode on + app.sessions.set('s-tile', { mode: 'opencode', cliMouseTracking: true }); + + term.selection = 'picked'; + mount.fire('click', click()); // a drag-selection just ended + term.selection = ''; + + tile._linkHovered = true; + mount.fire('click', click()); // the link provider opens this one + tile._linkHovered = false; + + term.buffer.active.baseY = 10; + term.buffer.active.viewportY = 0; + mount.fire('click', click()); // would hit-test a different row + term.buffer.active.viewportY = 10; + + expect(ws.inputFrames()).toEqual([]); + + mount.fire('click', click()); // nothing in the way any more + expect(ws.inputFrames().map((f) => f.d)).toEqual([TAP]); + }); + + it("is not blocked by the primary pane's own link hover", async () => { + const app = makeApp({ 's-tile': { mode: 'opencode', cliMouseTracking: true } }); + app._linkHovered = true; + const { ws, mount } = await connectTile(app); + + mount.fire('click', click()); + + expect(ws.inputFrames().map((f) => f.d)).toEqual([TAP]); + }); + + it("follows the tile session's flag, never the active session's", async () => { + const reported = await connectTile( + makeApp({ + other: { mode: 'claude', cliMouseTracking: false }, + 's-tile': { mode: 'opencode', cliMouseTracking: true }, + }) + ); + reported.mount.fire('click', click()); + expect(reported.ws.inputFrames().map((f) => f.d)).toEqual([TAP]); + + const silent = await connectTile( + makeApp({ + other: { mode: 'claude', cliMouseTracking: true }, + 's-tile': { mode: 'opencode', cliMouseTracking: false }, + }) + ); + silent.mount.fire('click', click()); + expect(silent.ws.inputFrames()).toEqual([]); + }); +}); + +describe('destroy()', () => { + it('drops queued page keys and detaches both listeners it registered', async () => { + const { tile, ws, mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + mount.fire('wheel', wheelLines(-12)); // queued, not yet flushed + const wheelFn = mount.listeners.wheel[0].fn; + const clickFn = mount.listeners.click[0].fn; + + tile.destroy(); + vi.advanceTimersByTime(100); + + expect(ws.inputFrames()).toEqual([]); + expect(tile._scrollFlushTimer).toBeNull(); + expect(mount.removeEventListener).toHaveBeenCalledWith('wheel', wheelFn, { capture: true }); + expect(mount.removeEventListener).toHaveBeenCalledWith('click', clickFn); + }); + + it('registers the wheel listener non-passive in the capture phase and the click one in the bubble phase', async () => { + const { mount } = await connectTile(makeApp({ 's-tile': { mode: 'opencode' } })); + + expect(mount.listeners.wheel.map((l) => l.opts)).toEqual([{ capture: true, passive: false }]); + expect(mount.listeners.click.map((l) => l.opts)).toEqual([undefined]); + }); +}); diff --git a/test/terminal-tile-unit.test.ts b/test/terminal-tile-unit.test.ts index 5606abf2..8eb28d48 100644 --- a/test/terminal-tile-unit.test.ts +++ b/test/terminal-tile-unit.test.ts @@ -65,6 +65,8 @@ type PaneUnderTest = { _onLiveOutput(data: string): void; _onLiveClear(): void; _installWheelListener(): void; + _installClickListener(): void; + _onClick: unknown; _writeDisconnectedMarker(): void; _onSocketClosed(): void; }; @@ -763,9 +765,13 @@ describe('TerminalTile scroll-to-top history pull', () => { // Capture phase: xterm's own wheel handler stopPropagation()s the events it // consumes, so a bubbling listener would never fire while the pane still has // scrollback to scroll, and the pull would work only from the exact top row. + // Not passive: the hollow-buffer paging route consumes its wheel right here + // (test/terminal-tile-scroll.test.ts). This stub window has neither the + // shared paging helpers nor the app's gates, so that route stays inert and + // every wheel below falls through to the pull, as before. const [type, listener, options] = mount.addEventListener.mock.calls[0]; expect(type).toBe('wheel'); - expect(options).toEqual({ capture: true, passive: true }); + expect(options).toEqual({ capture: true, passive: false }); listener({ deltaY: 120 }); // wheel down listener({ deltaY: 0 }); @@ -789,6 +795,22 @@ describe('TerminalTile scroll-to-top history pull', () => { expect(pane._onWheel).toBeNull(); }); + it('destroy() detaches exactly the click listener it registered', () => { + const mount = { addEventListener: vi.fn(), removeEventListener: vi.fn() }; + const pane = makePane('opencode', mount); + pane._installWheelListener(); + pane._installClickListener(); + const [type, registered, options] = mount.addEventListener.mock.calls[1]; + // Bubble phase, like the primary pane's click reporter (terminal-ui.js). + expect(type).toBe('click'); + expect(options).toBeUndefined(); + + pane.destroy(); + + expect(mount.removeEventListener).toHaveBeenCalledWith('click', registered); + expect(pane._onClick).toBeNull(); + }); + it('connect() installs the wheel listener (static guard)', () => { // connect() needs a whole xterm to run, so its wiring is pinned by source // rather than executed; the listener's behaviour is exercised above. @@ -800,6 +822,7 @@ describe('TerminalTile scroll-to-top history pull', () => { expect(end).toBeGreaterThan(start); const connect = SOURCE.slice(start, end); expect(connect).toContain('this._installWheelListener();'); + expect(connect).toContain('this._installClickListener();'); expect(connect).toContain('this._onLiveClear();'); expect(connect).not.toContain('this.terminal.clear();'); // The tests below drive the close through _onSocketClosed() directly; the