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
/**
* Background keep-alive for webview-hosting nodes (browser/web) across project switches —
* issue #301's "browser nodes reload their page on every tab change".
*
* WHY THIS SHAPE. An Electron `<webview>`'s guest process dies the moment its element leaves the
* DOM, and — measured on Electron 42.x — it ALSO dies on a DOM *move* (`insertBefore` into a new
* or even the same parent detaches first), while it survives, state intact, any amount of sibling
* churn around it and `display:none` of itself or an ancestor (the guest keeps its viewport size
* and scroll while hidden, repaints pixel-identically on reveal, and its timers keep running,
* throttled like a background tab). So a page survives a project switch if and only if its
* `<webview>` element is NEVER unmounted and NEVER reordered relative to the other kept elements —
* React only calls `insertBefore` on a kept child when its relative order among kept children
* changes (the `lastPlacedIndex` rule), and that one call is the guest's death.
*
* Hence the design: every webview-hosting node renders in ONE stable region at the END of the
* `<ReactFlow>` nodes prop — the "pool region" — whose internal order is owned by the pool entries
* here and never changes while an entry lives. The active project's entries render as the live
* nodes; a background project's render as GHOSTS: same node id (React key stability is the whole
* point), `display:none`, non-interactive, position parked at the origin. Merging happens at the
* prop, exactly like the ephemeral subagent cards — Canvas state, persistence, undo and the wire
* never see a ghost.
*
* The invariant every function here preserves, and the one a refactor must not break: **the
* relative order of surviving entries is identical in consecutive merge outputs.** Appends and
* removals are fine; a reorder kills a live page. `orderIsStable` in the tests states it directly.
*
* Memory bounds (same posture as the park/WebGL budgets — a lever must not end live work):
* - the Browser Memory Saver already discards any HIDDEN webview after `BROWSER_DISCARD_MS`
* unless it is loading/audible/agent-driven, and a ghost is hidden by construction — the
* existing per-surface hook reaps it, and `onGuestDiscarded` then drops the entry (the husk
* would otherwise hold a cap slot for a guest that no longer exists);
* - `BACKGROUND_WEBVIEW_MAX` hard-caps how many background guests exist at once, evicting the
* longest-retired first, for the user who switches through many projects faster than the
* saver's window (or who turned the saver off).
*/
import type { CanvasNode } from '../state/workspace'
import type { NodeKind } from '@shared/types'
/** Node kinds that host an Electron `<webview>` (a whole Chromium renderer process). */
export const KEEPALIVE_KINDS: ReadonlySet<string> = new Set(['browser', 'web'])
/**
* Hard cap on simultaneously-alive BACKGROUND guests. Each one is a Chromium renderer
* (~50–200 MB); the Browser Memory Saver reaps hidden ones after its window, so this cap only
* bites a fast multi-project switcher — and then evicts the longest-retired page, which is also
* the one whose in-page state was most likely stale anyway.
*/
export const BACKGROUND_WEBVIEW_MAX = 8
/** One pooled webview node. Immutable — every update replaces the entry object, which is what
* lets the merge cache ghost node objects by entry identity. */
export interface KeepAliveEntry {
nodeId: string
projectId: string
/** Snapshot of the node as last seen live. `data` carries what the mounted surface needs to
* keep rendering consistently (url/title/partition/filePath…). */
node: { type: NodeKind; width?: number; height?: number; data: CanvasNode['data'] }
/** When this entry went to the background (ms epoch) — LRU key for the cap. 0 = active. */
retiredAt: number
}
/** Does this live flow node belong in the pool region at all? */
export function isKeepAliveKind(n: { type?: string }): boolean {
return !!n.type && KEEPALIVE_KINDS.has(n.type)
}
/** Does this node hold a guest worth keeping alive in the background? A start-page browser or an
* empty web node has no guest process — retiring it would keep a husk for nothing. */
export function hasKeepAliveContent(n: { data?: { url?: unknown; filePath?: unknown } }): boolean {
return !!(n.data && (n.data.url || n.data.filePath))
}
/** Ghost node objects cached by entry identity, so a drag frame's merge re-emits the SAME object
* and React Flow / React bail out instead of re-rendering every ghost per frame. */
const ghostCache = new WeakMap<KeepAliveEntry, CanvasNode>()
/**
* The React Flow node a background entry renders as. Same id (key stability), `display:none`
* (guest survives, IntersectionObserver reads it as hidden so the memory saver's clock runs),
* non-interactive on every axis, `parentId`-free and parked at the origin — a hidden node has no
* geometry, so its position only matters for not skewing minimap/fit bounds.
*/
export function ghostFlowNode(entry: KeepAliveEntry): CanvasNode {
const cached = ghostCache.get(entry)
if (cached) return cached
const node: CanvasNode = {
id: entry.nodeId,
type: entry.node.type,
position: { x: 0, y: 0 },
width: entry.node.width,
height: entry.node.height,
data: { ...entry.node.data, ghost: true },
style: { display: 'none' },
draggable: false,
selectable: false,
deletable: false,
connectable: false,
focusable: false
}
ghostCache.set(entry, node)
return node
}
/**
* Build the `<ReactFlow>` nodes prop: non-webview live nodes, then the ephemeral cards, then the
* pool region — every pool entry in pool order (live object for the MOUNTED project, ghost for
* any other), then any mounted webview node the pool does not know yet (a node created since the
* last switch), in live array order.
*
* `mountedProjectId` is the project `liveNodes` actually BELONGS to (Canvas's
* `keepAliveFromRef`), and deliberately NOT the active-project id. The two disagree for exactly
* one commit per switch — the tab click re-renders with the new active id while the load effect
* has not yet swapped the node array — and pairing entries against the active id there made a
* returning entry take the live branch, miss its node in the not-yet-swapped array, and drop out
* of the merged list for that commit: one unmount, guest dead, page reloaded — the precise
* failure this module exists to prevent ([MEASURED] in the app: ghost→live remounted the wrapper
* while live→ghost, which has no such window, kept it). Keyed on the mounted project, that
* commit's output is id-identical to the previous one, and the whole swap lands in the single
* commit the load effect produces.
*
* Hoisting the ACTIVE webview nodes to the tail region is what keeps their DOM position stable
* across the active↔ghost transitions; the visible cost is a tie-break change — an unselected
* webview node now paints above other unselected z-0 nodes it overlaps, instead of by creation
* order. Selection elevation (z 1000) still wins, so anything being dragged or selected stays on
* top of a page.
*/
export function mergeWithKeepAlive(
liveNodes: readonly CanvasNode[],
ephemeralNodes: readonly CanvasNode[],
entries: readonly KeepAliveEntry[],
mountedProjectId: string | null
): CanvasNode[] {
const anyPool = entries.length > 0 || liveNodes.some(isKeepAliveKind)
if (!anyPool) {
// No webview node anywhere: hand back the live array ITSELF (React Flow's array-identity
// short-circuit), byte-identical to the pre-pool merge.
return ephemeralNodes.length ? [...liveNodes, ...ephemeralNodes] : (liveNodes as CanvasNode[])
}
const byId = new Map<string, CanvasNode>()
for (const n of liveNodes) if (isKeepAliveKind(n)) byId.set(n.id, n)
const out: CanvasNode[] = []
for (const n of liveNodes) if (!isKeepAliveKind(n)) out.push(n)
out.push(...ephemeralNodes)
const seen = new Set<string>()
for (const e of entries) {
seen.add(e.nodeId)
if (e.projectId === mountedProjectId) {
// Live object, not the snapshot: position/selection/data flow straight through.
//
// A miss FALLS BACK TO THE GHOST rather than dropping the entry from the output. The pool
// store, `keepAliveFromRef` and `nodes` are three state sources that do not all land in the
// same commit (zustand rides useSyncExternalStore; `setNodes` is ordinary state), so a
// switch can render one commit where the entries already say "mounted" while the node array
// is still the outgoing project's — and an id absent from ONE commit is an unmount, i.e. a
// dead guest and a page reload ([MEASURED] in the app: this exact interleaving remounted
// every returning page; the jsdom test cannot see it because it renders atomically).
// The fallback costs nothing when it fires wrongly for a genuinely DELETED node: the ghost
// is invisible, and every deletion funnel drops the entry (handleNodesChange's remove
// branch, the peer-mutation remove, project deletion), with the next retire as the backstop.
const live = byId.get(e.nodeId)
out.push(live ?? ghostFlowNode(e))
} else {
out.push(ghostFlowNode(e))
}
}
for (const n of liveNodes) {
if (isKeepAliveKind(n) && !seen.has(n.id)) out.push(n)
}
return out
}
/** The node ids currently rendered as GHOSTS (background entries) — the set `handleNodesChange`
* drops on the floor: nothing about a background node is a canvas edit. */
export function backgroundNodeIds(
entries: readonly KeepAliveEntry[],
activeProjectId: string | null
): Set<string> {
const out = new Set<string>()
for (const e of entries) if (e.projectId !== activeProjectId) out.add(e.nodeId)
return out
}
/**
* Retire a project's webview nodes into the pool: upsert a fresh snapshot for every content-bearing
* webview node (keeping an existing entry's ORDER SLOT — the invariant), prune the project's
* entries whose node is gone (deleted, or its content cleared), and evict the longest-retired
* background entries beyond the cap. Pure; the store owns the state.
*/
export function retireIntoPool(
entries: readonly KeepAliveEntry[],
projectId: string,
outgoingNodes: readonly CanvasNode[],
now: number,
cap: number = BACKGROUND_WEBVIEW_MAX
): KeepAliveEntry[] {
const keep = new Map<string, CanvasNode>()
for (const n of outgoingNodes) {
if (isKeepAliveKind(n) && hasKeepAliveContent(n)) keep.set(n.id, n)
}
const snapshot = (n: CanvasNode, prior?: KeepAliveEntry): KeepAliveEntry => ({
nodeId: n.id,
projectId,
node: {
type: n.type as NodeKind,
width: n.width ?? n.measured?.width ?? undefined,
height: n.height ?? n.measured?.height ?? undefined,
// The ghost must render with the values the mounted surface last reported, or the props
// transition at the switch would navigate the live page (BrowserSurface reloads when its
// `url` prop moves away from where it is).
data: { ...n.data }
},
// A re-retired entry keeps its original clock only if it was already background (it cannot
// be: retire runs on the project we are LEAVING, whose entries were active). Fresh clock.
retiredAt: prior && prior.projectId === projectId && prior.retiredAt ? prior.retiredAt : now
})
const next: KeepAliveEntry[] = []
for (const e of entries) {
if (e.projectId !== projectId) {
next.push(e)
continue
}
const live = keep.get(e.nodeId)
if (!live) continue // node deleted or content gone — entry ends, ghost unmounts
keep.delete(e.nodeId)
next.push(snapshot(live, e))
}
// Nodes the pool has not seen yet, appended in live array order (their merge position was
// already "after every entry", so appending preserves each element's relative order).
for (const n of outgoingNodes) {
if (keep.has(n.id)) next.push(snapshot(n))
}
return evictOverCap(next, cap)
}
/**
* Mark a project's entries ACTIVE (retiredAt 0). Runs on the way INTO a project, and must run
* BEFORE the outgoing project's `retireIntoPool` — an incoming entry still carrying its old
* background clock would be the cap's oldest candidate at the exact moment its page is about to
* be revealed, and evicting it there would reload the very page the pool preserved.
*/
export function activateInPool(
entries: readonly KeepAliveEntry[],
projectId: string
): KeepAliveEntry[] {
return entries.map((e) => (e.projectId === projectId && e.retiredAt !== 0 ? { ...e, retiredAt: 0 } : e))
}
/** Drop the longest-retired background entries beyond `cap`. Removal never reorders survivors. */
export function evictOverCap(entries: readonly KeepAliveEntry[], cap: number): KeepAliveEntry[] {
const background = entries.filter((e) => e.retiredAt > 0)
if (background.length <= cap) return [...entries]
const evict = new Set(
background
.slice()
.sort((a, b) => a.retiredAt - b.retiredAt)
.slice(0, background.length - cap)
.map((e) => e.nodeId)
)
return entries.filter((e) => !evict.has(e.nodeId))
}
/**
* Overlay a returning project's pool data onto its freshly deserialized flow nodes, BEFORE the
* single `setNodes` — a page that navigated while it was a ghost must come back with `data.url`
* already at its live location, or the props transition (persisted, stale url) would navigate the
* surviving webview backwards. Only url/title move; everything else is the file's business.
*/
export function overlayKeepAliveData(
flow: readonly CanvasNode[],
entries: readonly KeepAliveEntry[],
projectId: string
): CanvasNode[] {
const byId = new Map<string, KeepAliveEntry>()
for (const e of entries) if (e.projectId === projectId) byId.set(e.nodeId, e)
if (byId.size === 0) return [...flow]
return flow.map((n) => {
const e = byId.get(n.id)
if (!e) return n
const url = e.node.data.url
const title = e.node.data.title
if ((url === undefined || url === n.data.url) && (title === undefined || title === n.data.title))
return n
return {
...n,
data: {
...n.data,
...(url !== undefined ? { url } : {}),
...(title !== undefined ? { title } : {})
}
}
})
}