Skip to content

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.

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.ts
index 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.tsx
index 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 = boardOpen
applyFitRef.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.ts
index 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.ts
index 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()
+ }
+ }
+}