mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-10 17:29:41 +02:00
Codeman maintainer
312a8faa06
#541 fixed Android autocorrect duplicating the typed line in the primary pane: xterm's keyCode-229 textarea diff is append-only, so an autocorrect on space (delete a word, insert the corrected one) sent the whole line again. The fix, an edit-based diff that sends one DEL per deleted code point and then the inserted text, lives in terminal-keycode229-recovery.js together with #441's next-keydown drain (a character committed in the same task as Enter goes out ahead of the \r) and the original orphaned-insertText recovery. Only the primary pane created that controller, so a grid tile or the split's Pane B still ran xterm's stock behaviour. Both are gated on width alone (1180 CSS px), which a wide Android tablet clears. TerminalTile now creates its own controller in connect(), after the xterm opens and before the first await, handed this tile's textarea, this tile's CompositionHelper and _onTerminalData as the send path, so recovered bytes go to the tile's own session through the exactly-once queue. As in the primary pane, handleKeyEvent runs first in the custom key handler, above the keyCode-229 early return, and notifyCanonicalData sits in the onData lambda, gated on the same two CodemanTerminalInput predicates, never in _onTerminalData, which the recovered bytes also take. destroy() tears the controller down before disposing the xterm, which restores xterm's own diff and removes the capture listeners. No mode or device gate, matching the primary. The module itself is unchanged apart from its header; terminal-ui.js gains only a comment naming the twin. Tests: test/terminal-tile-input.test.ts now loads the real module into its vm harness (with window timers, without which create() would silently throw and every test would run against no controller) and drives a fake CompositionHelper carrying xterm's own append-only diff. It covers install and restore on the tile's own helper and textarea, autocorrect sent as an edit (with a control reproducing the device-log duplicate), the last character and an autocorrect each followed by Enter in one task, a self-rescued 229 key delivered once, the onData gate ignoring query replies and focus reports, two refused inserts after one keydown both recovered, robustness when the controller throws, per-tile controllers, and a source pin keeping the call above the early return. Removing the create, the handleKeyEvent call, the notify, its gate, or the destroy each turns at least one of them red, as does moving the notify into _onTerminalData. The browser suite gains a TerminalTile block in test/terminal-keycode229-recovery.browser.test.ts (real xterm, trusted execCommand input, chunks asserted to address the tile's session, with a destroyed-controller control). Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
215 lines
11 KiB
Markdown
215 lines
11 KiB
Markdown
# Split-Pane Sessions — Design Spec
|
||
|
||
**Status**: Implemented (v1)
|
||
**Author**: Claude (session with Tim), 2026-09-15
|
||
**Scope**: v1 only. v2 items are named and explicitly deferred, not designed.
|
||
|
||
> **Update (tile grid, PR 1):** Pane B is now a `TerminalTile`
|
||
> (`terminal-tile.js`) and is no longer as plain as this spec describes: it
|
||
> reconnects after a drop, delivers input exactly once, has clickable paths
|
||
> and image paste, sizes its PTY without a floor and adopts `zc` columns, and
|
||
> the app-level terminal shortcuts follow the focused pane. Ctrl+W no longer
|
||
> closes anything (Close Session has no default key).
|
||
> See `docs/tile-grid-plan.md` and `architecture-invariants#split-pane-sessions`.
|
||
|
||
## Problem
|
||
|
||
Codeman's terminal area shows exactly one active session (pane) at a time —
|
||
switching panes re-binds the single xterm instance and the single WebSocket
|
||
to a different session. Multi-monitor spanning (`scripts/span-codeman.sh` /
|
||
`span-codeman.ps1`) turned out to solve a different problem: it makes one
|
||
browser window bigger, but that window still shows one session; floating
|
||
subagent windows are draggable overlays on top of it, not tiled panes. There
|
||
is no way today to see two live sessions (e.g. `w1-codeman` and
|
||
`w1-mcp-memory`) side-by-side in one window, even on a monitor wide enough to
|
||
fit both.
|
||
|
||
## Goal (v1)
|
||
|
||
From the active session, open a **second, independent, fully live session**
|
||
in a pane beside it — draggable divider, side-by-side only. Closing the
|
||
second pane collapses back to today's normal single-pane view. No
|
||
persistence: a page reload always returns to single-pane. Floating
|
||
subagent/Ultracode windows keep their current behavior unchanged (global,
|
||
unconstrained across the whole viewport, split or not).
|
||
|
||
Explicitly out of scope for v1 (v2 candidates, not designed here):
|
||
- More than 2 panes / grid layouts
|
||
- Vertical (stacked) splits
|
||
- Drag-a-tab-to-split as a trigger (v1 trigger is an explicit button + picker)
|
||
- Persisting the split layout across reload or across devices
|
||
- Mobile/tablet layouts (viewport is too narrow for this to make sense; gated
|
||
to desktop widths the same way `home-sessions.js`'s rail is)
|
||
- Feature parity between the two panes (see "Pane B is deliberately plainer"
|
||
below)
|
||
|
||
## Current architecture (why this isn't a CSS change)
|
||
|
||
`terminal-ui.js` is built entirely around **singleton** state: `this.terminal`
|
||
(one xterm instance), `this._ws`/`this._wsSessionId` (one WebSocket, rebound
|
||
on every pane switch via `_disconnectWs()` + `_connectWs(newId)`), a
|
||
`this._xtermSnapshots` map used only to restore scrollback into that one
|
||
terminal when switching back to a session. Roughly 280 references to this
|
||
singleton state exist across the file (input handling, resize/fit, sizing-
|
||
token claims, mobile touch gestures, CJK IME, local-echo overlay wiring,
|
||
keyboard accessory bar, link providers, etc.).
|
||
|
||
Showing two sessions at once therefore requires a second, independently
|
||
alive xterm + WebSocket pair running concurrently — not a layout change to
|
||
one shared instance.
|
||
|
||
**Related prior art**: `detachSession(id)` (app.js) already opens one session
|
||
in a genuinely separate browser window (`isSoloWindow` mode) with its own
|
||
independent WebSocket, and two of those can already be snapped side-by-side
|
||
today with zero new code. That covers "two sessions visible at once" but not
|
||
what this spec is for: one Codeman window with two panes and a divider you
|
||
can drag without leaving your seat, each still a full participant in that
|
||
window's floating subagent windows, header, and settings. This spec builds
|
||
past detach, not a duplicate of it.
|
||
|
||
**Server-side check (done, not just assumed)**: `MAX_WS_PER_SESSION = 5`
|
||
(`src/web/routes/ws-routes.ts`), scoped by `clientId:tabNonce`
|
||
(`ws-connection-registry.ts`). Splitting always opens a *different* session
|
||
in the second pane (self-splitting is disallowed, see below), so this is two
|
||
sessions each getting their normal one connection — the existing cap is
|
||
irrelevant here and needs no server change.
|
||
|
||
## Key design decision: Pane B is deliberately plainer than Pane A
|
||
|
||
Porting all ~280 singleton behaviors to a second, symmetric pane is not
|
||
worth it for v1 — most of that code is input-quality-of-life for **mobile/
|
||
touch** (local-echo overlay, CJK IME textarea, touch gesture handling,
|
||
keyboard accessory bar), and this feature is desktop-only by nature (a split
|
||
view needs a wide viewport). So:
|
||
|
||
- **Pane A** (the session that was already active when you opened the split)
|
||
stays exactly what it is today — `this.terminal`, `this._ws`, unchanged
|
||
code path, zero regression risk.
|
||
- **Pane B** is a new, smaller `SplitTerminalPane` object: its own xterm
|
||
instance + fit addon, its own WebSocket to `/ws/sessions/:id/terminal`,
|
||
resize-on-divider-drag, and plain keyboard input. It does **not** get the
|
||
local-echo overlay, CJK IME composition, touch/mobile handlers, or the
|
||
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. (Since moved to `TerminalTile`, terminal-tile.js,
|
||
which has gained three pieces of the primary pane: hollow-buffer wheel
|
||
paging (#555) and the desktop click report for a CLI with
|
||
`cliMouseTracking` on, both through the primary pane's gates aimed at the
|
||
tile, and its own keyCode-229 soft-keyboard controller
|
||
(terminal-keycode229-recovery.js: the #441 next-keydown drain and #541's
|
||
edit-based diff, so an Android autocorrect is not sent twice). The 1180px
|
||
width gate is all that keeps a phone out, and a wide Android tablet clears
|
||
it. 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
|
||
call sites to compare, rather than guessing the right abstraction now).
|
||
|
||
One more asymmetry worth naming here rather than discovering by surprise:
|
||
while both panes accept keyboard input, the global capture-phase shortcut
|
||
handler (`app.js`) always resolves against Pane A — it has no notion of
|
||
which pane currently has focus. So Ctrl+L or Ctrl+W typed while Pane B has
|
||
focus clears or closes Pane A, not the session you were actually typing
|
||
into. Not fixed for v1, same reasoning as the rest of this section.
|
||
|
||
## Components
|
||
|
||
### 1. `SplitTerminalPane` (new, `terminal-split.js`)
|
||
|
||
A small class, one instance per secondary pane:
|
||
- `constructor(sessionId, mountEl)`
|
||
- `connect()` — creates the xterm instance (same theme/font config as the
|
||
primary, read from the same settings so it doesn't visually clash), opens
|
||
`/ws/sessions/:id/terminal`, wires input → WS, WS → terminal write
|
||
- `fit()` — calls the fit addon; called on divider drag (rAF-throttled) and
|
||
on window resize
|
||
- `destroy()` — disposes the xterm instance, closes the WS cleanly
|
||
|
||
No snapshot/scrollback-restore map is needed the way `_xtermSnapshots` exists
|
||
for Pane A — Pane B is destroyed on close, not hidden-and-restored, since
|
||
there's no persistence requirement.
|
||
|
||
### 2. Split container (layout)
|
||
|
||
```
|
||
.terminal-split-container (flex row, only rendered when split is active)
|
||
├── .terminal-wrap (existing element, Pane A — untouched)
|
||
├── .split-divider (new, draggable seam)
|
||
└── .terminal-pane-b (new, hosts SplitTerminalPane's xterm + a
|
||
small header: session name + × close button)
|
||
```
|
||
|
||
When not split, `.terminal-wrap` renders exactly as it does today (no
|
||
wrapping container at all, to keep the no-split path byte-identical to
|
||
current behavior). Splitting inserts the container and reparents
|
||
`.terminal-wrap` into it as the first child — same reparenting pattern
|
||
already used by `applySessionListLayout()` for `#sessionTabs`, so this isn't
|
||
a new pattern for the codebase.
|
||
|
||
Default split is 50/50 (`flex-basis: 50%` each). Divider drag updates both
|
||
panes' `flex-basis` live (rAF-throttled) and calls `fit()` on **both**
|
||
terminals per tick, clamped to 20%/80% so neither pane can be dragged into an
|
||
unusably thin sliver.
|
||
|
||
### 3. Trigger UI
|
||
|
||
A **"Split"** button (header, opt-in like the other header buttons —
|
||
`showSplitButton`, default off, same pattern as `showMultiMonitorButton`)
|
||
opens a small picker listing your other open sessions (reuses
|
||
`this.sessions`/`sessionOrder`, filtered to exclude the currently active
|
||
session — you cannot split a session against itself). Picking one:
|
||
1. Creates the split container, reparents `.terminal-wrap`
|
||
2. Instantiates `SplitTerminalPane` for the chosen session in `.terminal-pane-b`
|
||
3. Button state flips to "close split" (or Pane B's own header × does it)
|
||
|
||
Closing (via Pane B's × or the header button toggling off):
|
||
1. `SplitTerminalPane.destroy()`
|
||
2. Removes `.terminal-split-container`, reparents `.terminal-wrap` back to
|
||
its original location at 100% width
|
||
3. Fires a resize/fit on Pane A (same `ResizeObserver`-driven fit already in
|
||
place today — no new code needed here, it fires naturally once the
|
||
container's size changes)
|
||
|
||
v2 note (not designed): dragging a session tab onto the active pane as an
|
||
alternate trigger. You confirmed right-click doesn't work today (Codeman
|
||
doesn't intercept it) and declined a keybind, so v1 is button+picker only.
|
||
|
||
### 4. Failure / edge cases
|
||
|
||
- **The Pane B session ends or is deleted while split is active** → treat
|
||
identically to the user closing Pane B manually: destroy the pane, collapse
|
||
to Pane A at full width.
|
||
- **The Pane A session ends while split is active** → Pane B is promoted:
|
||
it becomes the new single full-width pane (reusing today's normal
|
||
single-pane code path means Pane B's `SplitTerminalPane` must hand off to
|
||
a real `this.terminal`/`this._ws` binding — simplest correct approach is
|
||
to just collapse the split and let normal session-select logic reopen
|
||
Pane B's session as the new primary, rather than trying to promote the
|
||
lightweight pane object in place).
|
||
- **Both end** → falls through to today's normal "no active session" /
|
||
welcome-screen state.
|
||
- **Subagent/Ultracode floating windows** → no design work needed; they're
|
||
already positioned independent of `.terminal-wrap`'s layout, so they
|
||
continue to float over whichever pane(s) are on screen, unconstrained,
|
||
exactly as today.
|
||
|
||
## Testing
|
||
|
||
- Unit: `SplitTerminalPane` connect/fit/destroy lifecycle (mock WS, like
|
||
existing terminal tests use `TEST_PTY_SCRIPT`).
|
||
- Route/integration: opening two WS connections to two different sessions
|
||
from one simulated client concurrently — confirms the existing per-session
|
||
cap and connection registry need no changes.
|
||
- Browser (Playwright, `test/browser` since this is desktop-viewport-gated
|
||
UI): open split via button+picker, verify both panes render live output
|
||
independently, drag divider and confirm both refit, close Pane B and
|
||
confirm Pane A returns to full width, kill the Pane B session externally
|
||
and confirm auto-collapse.
|
||
|
||
## Open questions for review
|
||
|
||
None blocking — the scope-narrowing decisions above (Pane B feature parity,
|
||
no persistence, side-by-side only, button+picker trigger) came directly from
|
||
your answers during brainstorming. Flag anything here you want reconsidered.
|