Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
test(terminal): pin the board render pause wiring by behaviour, not source text
review469f4562d090
diff --git a/src/renderer/nodes/TerminalNode.global-kanban.test.ts b/src/renderer/nodes/TerminalNode.global-kanban.test.tsindex 045f96cdd..bc4473199 100644--- a/src/renderer/nodes/TerminalNode.global-kanban.test.ts+++ b/src/renderer/nodes/TerminalNode.global-kanban.test.ts@@ -18,32 +18,42 @@ describe('TerminalNode global kanban sizing', () => {})describe('TerminalNode board render pause wiring', () => {- // The same `boardOpen` (Omni included) also stops xterm DRAWING under the board (audit GT-6:- // 36.5 % GPU board-open over streaming terminals vs 0.0 % over silent ones). The decision itself- // is unit-tested in `terminal/board-render-pause.test.ts`; this pins that the node feeds it the- // right inputs and re-syncs it on both things it reads.- it('pauses on the board flag, except for the focus-mode node that sits above the board', () => {- expect(TERMINAL_SRC).toContain('covered: () => boardOpenRef.current && focusedNodeId() !== id')- expect(TERMINAL_SRC).toContain('onUncover: fullRepaint')+ // The same `boardOpen` (Omni included) also stops xterm DRAWING under the board. The behaviour —+ // a node mounted under the board resumes when it closes, release restores xterm's handler, a+ // stale run cannot detach a newer one — is tested on the slot itself with a fake terminal+ // (`terminal/board-render-pause.test.ts`). This only pins that the node USES the slot: matched on+ // the source with comments stripped, so a call that survives only inside a comment fails.+ const CODE = stripComments(TERMINAL_SRC)++ it('attaches per lifecycle run with the board flag, except for the focus-mode node', () => {+ const attach = CODE.slice(CODE.indexOf('const releaseBoardPause = boardPauseSlot.attach('))+ const call = attach.slice(0, attach.indexOf('})') + 2)+ expect(call).toContain('covered: () => boardOpenRef.current && focusedNodeId() !== id')+ expect(call).toContain('onUncover: fullRepaint')})- it('re-syncs after the board flag moves and when focus mode moves', () => {- const effect = TERMINAL_SRC.slice(TERMINAL_SRC.indexOf('boardOpenRef.current = boardOpen'))- const body = effect.slice(0, effect.indexOf('}, [boardOpen])'))- // After the ref write, so the pause reads the new value.- expect(body.indexOf('boardPauseRef.current?.sync()')).toBeGreaterThan(0)- const focus = TERMINAL_SRC.slice(TERMINAL_SRC.indexOf('subscribeFocusedNode(() => {'))- expect(focus.slice(0, focus.indexOf('[]'))).toContain('boardPauseRef.current?.sync()')+ it('releases from the run\'s cleanup, before a park keeps the xterm', () => {+ expect(CODE.match(/\breleaseBoardPause\(\)/g)).toHaveLength(1)})- it('is removed by the run that installed it, before a park keeps the xterm', () => {- expect(TERMINAL_SRC).toContain('boardPause?.dispose()')+ it('syncs after the board flag moves and when focus mode moves', () => {+ const effect = CODE.slice(CODE.indexOf('boardOpenRef.current = boardOpen'))+ const body = effect.slice(0, effect.indexOf('}, [boardOpen])'))+ expect(body.indexOf('boardPauseSlot.sync()')).toBeGreaterThan(0)+ const focus = CODE.slice(CODE.indexOf('subscribeFocusedNode(() => {'))+ expect(focus.slice(0, focus.indexOf('[]'))).toContain('boardPauseSlot.sync()')})it('never feeds the visibility verdict (budget, hibernation, offscreen teardown)', () => {- const report = TERMINAL_SRC.slice(TERMINAL_SRC.indexOf('const reportVisible = (visible: boolean): void => {'))+ const report = CODE.slice(CODE.indexOf('const reportVisible = (visible: boolean): void => {'))const body = report.slice(0, report.indexOf('visibilityReportRef.current = reportVisible'))expect(body).not.toContain('boardOpen')expect(body).not.toContain('boardPause')})})++/** Block and line comments out, so a pin cannot be satisfied by text that only survives in one.+ * A `//` right after `:`, a quote or a backslash is kept (URLs, regexes, strings). */+function stripComments(src: string): string {+ return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"`\\])\/\/.*$/gm, '$1')+}diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsxindex 1bf4cf4e2..04f584c65 100644--- a/src/renderer/nodes/TerminalNode.tsx+++ b/src/renderer/nodes/TerminalNode.tsx@@ -251,7 +251,7 @@ import { useTerminalSearch } from '../terminal/useTerminalSearch'import { useCopyFeedback } from '../terminal/useCopyFeedback'import { pasteWithImageReceipt } from '../terminal/image-paste-confirm'import { usePasteReceipt } from '../terminal/usePasteReceipt'-import { installBoardRenderPause, type BoardRenderPause } from '../terminal/board-render-pause'+import { createBoardPauseSlot } from '../terminal/board-render-pause'import { ContextMeter } from '../components/ContextMeter'import { isZoomModifierHeld } from '../lib/zoomModifier'import { HoverGuard } from './HoverGuard'@@ -1560,11 +1560,11 @@ export function TerminalNode({viewFor(s, useProjects.getState().activeProjectId ?? '') === 'kanban')const boardOpenRef = useRef(boardOpen)- // The live session's board render pause (set by the lifecycle effect): while the board covers- // this node, xterm stops DRAWING but keeps parsing (audit GT-6: 36.5 % GPU board-open over- // streaming terminals vs 0.0 % over silent ones). Synced from the two effects that already re-run- // on what "covered" reads — the board flag and focus mode. See `terminal/board-render-pause.ts`.- const boardPauseRef = useRef<BoardRenderPause | null>(null)+ // The live session's board render pause (attached by the lifecycle effect): while the board+ // covers this node, xterm stops DRAWING but keeps parsing. Synced from the two effects that+ // already re-run on what "covered" reads — the board flag and focus mode. See+ // `terminal/board-render-pause.ts`.+ const [boardPauseSlot] = useState(createBoardPauseSlot)const dwellRef = useRef<ReturnType<typeof setTimeout> | null>(null)const [showColors, setShowColors] = useState(false)const [armed, setArmed] = useState(true)@@ -3422,12 +3422,14 @@ export function TerminalNode({// sits ABOVE the board (z 25), so a node focused before the board opened is still on screen.// Deliberately NOT folded into `reportVisible`: that verdict feeds the WebGL budget,// hibernation and the offscreen teardown, and the board must not hibernate the sessions it- // shows cards for (audit GT-6, refuted fix shapes).- const boardPause = installBoardRenderPause(term as unknown as Parameters<typeof installBoardRenderPause>[0], {- covered: () => boardOpenRef.current && focusedNodeId() !== id,- onUncover: fullRepaint- })- boardPauseRef.current = boardPause+ // shows cards for.+ const releaseBoardPause = boardPauseSlot.attach(+ term as unknown as Parameters<typeof boardPauseSlot.attach>[0],+ {+ covered: () => boardOpenRef.current && focusedNodeId() !== id,+ onUncover: fullRepaint+ }+ )// Cmd+C (mac) / Ctrl+Shift+C (Linux, Windows) / Ctrl+Insert copy the terminal selection — xterm// renders to a canvas, so the DOM-selection copy used elsewhere can't see it. Plain Ctrl+C is@@ -5163,8 +5165,7 @@ export function TerminalNode({if (fullRepaintRef.current === fullRepaint) fullRepaintRef.current = null// Hand xterm its own pause back before the terminal is parked or disposed: a parked xterm// must not carry a wrapper whose `covered` reads a dead mount's refs.- boardPause?.dispose()- if (boardPauseRef.current === boardPause) boardPauseRef.current = null+ releaseBoardPause()// Free the GPU context on unmount (park or teardown) either way, and unregister from the// budget coordinator (which releases any held grant + cancels its timers). The park path must// keep releasing it as it always has (contexts are capped ~16, and a parked terminal is@@ -5630,7 +5631,7 @@ export function TerminalNode({boardOpenRef.current = boardOpenapplyFitRef.current?.()// …and stop (or resume) drawing under it. After the ref write: the pause reads it.- boardPauseRef.current?.sync()+ boardPauseSlot.sync()}, [boardOpen])// Focus mode engaged/exited anywhere on the canvas: re-run our size vote (applyFit reads@@ -5641,7 +5642,7 @@ export function TerminalNode({() =>subscribeFocusedNode(() => {applyFitRef.current?.()- boardPauseRef.current?.sync()+ boardPauseSlot.sync()}),[])diff --git a/src/renderer/terminal/board-render-pause.test.ts b/src/renderer/terminal/board-render-pause.test.tsindex 5b5b9b097..27a6ec0b8 100644--- a/src/renderer/terminal/board-render-pause.test.ts+++ b/src/renderer/terminal/board-render-pause.test.ts@@ -1,5 +1,6 @@import { describe, expect, it } from 'vitest'import {+ createBoardPauseSlot,installBoardRenderPause,renderPaused,type IntersectionVerdict,@@ -191,3 +192,65 @@ describe('installBoardRenderPause', () => {expect(installBoardRenderPause({ _core: { _renderService: {} } }, { covered: () => true })).toBeNull()})})++/**+ * The node's wiring, run with a fake terminal: TerminalNode's lifecycle run ATTACHES (and its+ * cleanup releases), and the board-flag and focus-mode effects only SYNC the slot. A slot that+ * never held the run's controller is the bug this pins: a node mounted while the board is up+ * pauses at install, and the board closing must still reach it.+ */+describe('createBoardPauseSlot (TerminalNode wiring)', () => {+ it('a node mounted under the board resumes and repaints when the board closes', () => {+ const { term, rs } = fake()+ const slot = createBoardPauseSlot()+ let board = true+ let repaints = 0+ const release = slot.attach(term, { covered: () => board, onUncover: () => repaints++ })+ expect(rs._isPaused).toBe(true)+ rs.refreshRows()+ expect(rs.painted).toBe(0)++ board = false+ slot.sync() // what the [boardOpen] effect does after writing the ref+ expect(rs._isPaused).toBe(false)+ expect(rs.painted).toBe(1) // the refresh owed while covered was flushed+ expect(repaints).toBe(1)+ release()+ })++ it('release hands xterm its own handler back and leaves nothing for a later sync', () => {+ const { term, rs } = fake()+ const slot = createBoardPauseSlot()+ let board = true+ const release = slot.attach(term, { covered: () => board })+ release()+ expect(Object.prototype.hasOwnProperty.call(rs, '_handleIntersectionChange')).toBe(false)+ expect(rs._isPaused).toBe(false) // a covered pause is handed back, not left stuck+ board = true+ slot.sync()+ rs.observe(true)+ expect(rs._isPaused).toBe(false)+ })++ it('a stale run\'s release never detaches the controller a newer run attached', () => {+ const a = fake()+ const b = fake()+ const slot = createBoardPauseSlot()+ let board = false+ const releaseOld = slot.attach(a.term, { covered: () => board })+ slot.attach(b.term, { covered: () => board })+ releaseOld()+ board = true+ slot.sync()+ expect(b.rs._isPaused).toBe(true)+ })++ it('an xterm without the private method attaches nothing and release is still safe', () => {+ const slot = createBoardPauseSlot()+ const release = slot.attach({ _core: {} }, { covered: () => true })+ expect(() => {+ slot.sync()+ release()+ }).not.toThrow()+ })+})diff --git a/src/renderer/terminal/board-render-pause.ts b/src/renderer/terminal/board-render-pause.tsindex cd2d81970..8f7febd63 100644--- a/src/renderer/terminal/board-render-pause.ts+++ b/src/renderer/terminal/board-render-pause.ts@@ -161,3 +161,39 @@ export function installBoardRenderPause(if (covered) apply()return controller}++/**+ * Where a terminal node keeps its live session's pause, so the wiring is one tested unit rather+ * than three lines spread over TerminalNode. The lifecycle run `attach`es (the render service only+ * exists once the terminal is open) and calls the release from its cleanup — per run, NOT through+ * `cleanups`, because a park keeps the xterm while this run's closures die with it, so the+ * adopting run must install its own. The board-flag and focus-mode effects only `sync`.+ *+ * The slot is the point: a node mounted while the board is already up is paused at install, and+ * the board closing reaches it only through `sync`, so a controller that never landed in the slot+ * leaves that node frozen on stale content until it is panned off screen and back.+ */+export interface BoardPauseSlot {+ /** Install on `term` for this run and hold the controller. Returns the run's release: dispose,+ * and clear the slot unless a newer run has attached since. */+ attach(term: PausableTerminal, opts: BoardRenderPauseOptions): () => void+ /** Re-read `covered()` on whatever controller is attached now; nothing attached, nothing done. */+ sync(): void+}++export function createBoardPauseSlot(): BoardPauseSlot {+ let current: BoardRenderPause | null = null+ return {+ attach(term, opts) {+ const pause = installBoardRenderPause(term, opts)+ current = pause+ return () => {+ pause?.dispose()+ if (current === pause) current = null+ }+ },+ sync() {+ current?.sync()+ }+ }+}