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
fix(minimap): exclude keep-alive ghosts from drawing and bounds
review5bdd69b783e9
diff --git a/CLAUDE.md b/CLAUDE.mdindex f108819c7..3ef944a8d 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1462,6 +1462,14 @@ the wire never see any of it):every returning page until the fallback; live→ghost never did). A genuinely deleted node's entryis dropped at the deletion funnels (handleNodesChange's `remove`, `deleteNodes`, the peer-mutationremove, project deletion/prune), with the next retire as backstop — never by the merge.+- **The minimap must exclude ghosts from BOTH its node list and its bounds lookup** (#850/#786).+ React Flow's MiniMap ignores CSS `display:none`; setting `hidden` on the real node instead+ unmounts the guest. `canvas/VisibleMiniMap.tsx` projects the live flow store into a provider+ scoped to the map, preserving internal absolute positions, measured sizes and the original+ panZoom instance. Only the map's node collections are filtered; persistence and pool lifecycle+ are untouched. The real MiniMap regression tests cover ghost/live transitions, empty bounds,+ removals, grouped geometry and camera interaction. When upgrading React Flow, keep those+ tests: the projection deliberately mirrors the state fields consumed by MiniMap.- **Memory bounds** (same posture as park/WebGL: a lever must not end live work): a ghost ishidden, so the existing Browser Memory Saver discards its guest after `BROWSER_DISCARD_MS`unless loading/audible/agent-driven — `onGuestDiscarded` then drops the entry (a husk would holddiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 0223794bd..ffe832072 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -573,6 +573,11 @@ arrangement on screen both confirm first, because layout edits are not in the undoes not, because it is. Whether a dialog claims the edit reaches other people comes from`layoutIsShared`, which is true for an SSH project as well as a folder one.+**Keep-alive webview ghosts must stay mounted, but must not enter minimap geometry.**+They use `display:none`, not React Flow's `hidden` (which unmounts the guest). Render canvas maps+through `VisibleMiniMap`: it filters both drawing and bounds in a minimap-only store while sharing+the live camera. A transparent rectangle alone still distorts the map's scale.+**React Flow's `fitView` is queued, not immediate — never use it to frame something automatically.**Calling it sets `fitViewQueued` and the fit runs from a later `setNodes` (only once every node ismeasured) or the next `updateNodeInternals`, against whatever the node lookup holds by then; a fitdiff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 9cbed6b7a..e3734d6f6 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -1,3 +1,4 @@+import { VisibleMiniMap } from './VisibleMiniMap'import { useCallback, useEffect, useMemo, useRef, useState } from 'react'import { useShallow } from 'zustand/react/shallow'import { playSfx, primeSfx } from '@renderer/lib/sfx'@@ -10,7 +11,6 @@ import {ControlButton,Controls,MarkerType,- MiniMap,ReactFlow,SelectionMode,useEdgesState,@@ -979,7 +979,7 @@ function StatusAwareMiniMap({ onNodeDoubleClick }: { onNodeDoubleClick: (node: N[statusById])return (- <MiniMap+ <VisibleMiniMapclassName="minimap"position="bottom-right"pannablediff --git a/src/renderer/canvas/VisibleMiniMap.test.tsx b/src/renderer/canvas/VisibleMiniMap.test.tsxnew file mode 100644index 000000000..c5796725c--- /dev/null+++ b/src/renderer/canvas/VisibleMiniMap.test.tsx@@ -0,0 +1,133 @@+// @vitest-environment jsdom+import { act, useLayoutEffect } from 'react'+import { createRoot, type Root } from 'react-dom/client'+import { applyNodeChanges, MiniMap, ReactFlowProvider, useStoreApi, type Node } from '@xyflow/react'+import { afterEach, expect, it, vi } from 'vitest'+import { VisibleMiniMap } from './VisibleMiniMap'+import { mergeWithKeepAlive, retireIntoPool } from '../lib/webviewKeepAlive'+import type { CanvasNode } from '../state/workspace'++;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true+let root: Root+let host: HTMLDivElement+let store: ReturnType<typeof useStoreApi>+function Capture() {+ const api = useStoreApi()+ useLayoutEffect(() => { store = api }, [api])+ return null+}+function mount() {+ host = document.createElement('div')+ document.body.append(host)+ root = createRoot(host)+ act(() => root.render(+ <ReactFlowProvider>+ <Capture />+ <div id="raw"><MiniMap /></div>+ <div id="filtered"><VisibleMiniMap pannable zoomable onClick={mapClicked} onNodeClick={clicked} nodeClassName={(n) => `node-${n.id}`} /></div>+ </ReactFlowProvider>+ ))+ act(() => store.setState({ width: 800, height: 600, transform: [-2000, -2000, 1] }))+}+const clicked = vi.fn()+const mapClicked = vi.fn()+const node = (id: string, type = 'terminal', x = 2100): CanvasNode => ({+ id, type, position: { x, y: 2100 }, width: 200, height: 100,+ data: { title: id, color: '#123456', group: null, ...(type === 'browser' ? { url: 'https://example.test' } : {}) }+}) as CanvasNode+const setNodes = (nodes: Node[]) => act(() => store.getState().setNodes(nodes))+const rects = (which = 'filtered') => host.querySelectorAll(`#${which} .react-flow__minimap-node`)+const bounds = (which = 'filtered') => host.querySelector(`#${which} svg`)!.getAttribute('viewBox')+afterEach(() => {+ act(() => root?.unmount())+ host?.remove()+ clicked.mockClear()+ mapClicked.mockClear()+ vi.useRealTimers()+})++it('excludes keep-alive ghosts from both rectangles and bounds without hiding the real guest', () => {+ mount()+ const browser = node('browser', 'browser')+ const terminal = node('terminal')+ setNodes([terminal])+ const expectedBounds = bounds()+ const pool = retireIntoPool([], 'other', [browser], 1)+ setNodes(mergeWithKeepAlive([terminal], [], pool, 'active'))+ // The unmodified upstream minimap reproduces the bug with our real keep-alive output.+ expect(rects('raw')).toHaveLength(2)+ expect(bounds('raw')).not.toBe(expectedBounds)+ expect(rects()).toHaveLength(1)+ expect(bounds()).toBe(expectedBounds)+ const guest = store.getState().nodeLookup.get('browser')!+ expect(guest.hidden).not.toBe(true)+ expect(guest.style?.display).toBe('none')+ expect(guest.data.ghost).toBe(true)++ // Same id returns live and then becomes a ghost again; map subscribes without remounting.+ setNodes(mergeWithKeepAlive([browser], [], pool, 'other'))+ expect(rects()).toHaveLength(1)+ expect(rects()[0].classList.contains('node-browser')).toBe(true)+ act(() => rects()[0].dispatchEvent(new MouseEvent('click', { bubbles: true, detail: 2 })))+ expect(clicked.mock.calls[0][1]).toBe(browser)+ setNodes(mergeWithKeepAlive([], [], pool, 'active'))+ expect(rects()).toHaveLength(0)+ setNodes([])+ expect(bounds()).toBe(bounds('raw')) // ghosts alone cannot pull an empty map toward origin+})++it('tracks remove changes, direct replacements, hidden nodes, group geometry and camera updates', () => {+ mount()+ const parent = node('group', 'group', 3000)+ const child = { ...node('child'), parentId: 'group', position: { x: 50, y: 30 } }+ const hidden = { ...node('hidden', 'terminal', -9000), hidden: true }+ setNodes([parent, child, hidden])+ expect(rects()).toHaveLength(2)+ expect(host.querySelector('.node-child')!.getAttribute('x')).toBe('3050')+ expect(bounds()).toBe(bounds('raw'))+ setNodes(applyNodeChanges([{ type: 'remove', id: 'child' }], store.getState().nodes))+ expect(rects()).toHaveLength(1)+ expect(host.querySelector('.node-child')).toBeNull()+ // deleteNodes, peer removes and server reconciliation replace the controlled array directly.+ setNodes([node('replacement')])+ expect(rects()).toHaveLength(1)+ expect(host.querySelector('.node-group')).toBeNull()+ act(() => store.setState({ transform: [-5000, -4000, 2], width: 1000, height: 500 }))+ expect(bounds()).toBe(bounds('raw'))+ setNodes([])+ expect(rects()).toHaveLength(0)+ expect(bounds()).toBe(bounds('raw'))+})++it('routes wheel zoom, drag and map clicks through the original camera', () => {+ vi.useFakeTimers()+ mount()+ setNodes([node('terminal')])+ const scaleTo = vi.fn()+ const setViewportConstrained = vi.fn()+ const panZoom = { scaleTo, setViewportConstrained } as unknown as NonNullable<ReturnType<typeof store.getState>['panZoom']>+ act(() => store.setState({ panZoom, width: 1000 }))+ const svg = host.querySelector('#filtered svg')!+ // jsdom has no SVG layout; d3 reads these real-browser animated length properties.+ Object.defineProperties(svg, {+ width: { value: { baseVal: { value: 200 } } },+ height: { value: { baseVal: { value: 150 } } }+ })+ act(() => svg.dispatchEvent(new WheelEvent('wheel', { deltaY: -100, bubbles: true })))+ expect(scaleTo).toHaveBeenCalledWith(Math.pow(2, 0.2))+ act(() => vi.advanceTimersByTime(200))+ const mouse = (type: string, clientX = 0, clientY = 0) => {+ const event = new MouseEvent(type, { clientX, clientY, bubbles: true })+ Object.defineProperty(event, 'view', { value: window })+ return event+ }+ act(() => svg.dispatchEvent(mouse('mousedown', 10, 10)))+ act(() => window.dispatchEvent(mouse('mousemove', 30, 20)))+ expect(setViewportConstrained).toHaveBeenCalledWith(+ { x: -2100, y: -2050, zoom: 1 }, [[0, 0], [1000, 600]], store.getState().translateExtent+ )+ act(() => window.dispatchEvent(mouse('mouseup')))+ act(() => vi.runAllTimers())+ act(() => svg.dispatchEvent(new MouseEvent('click', { clientX: 50, clientY: 60, bubbles: true })))+ expect(mapClicked).toHaveBeenCalledTimes(1)+})diff --git a/src/renderer/canvas/VisibleMiniMap.tsx b/src/renderer/canvas/VisibleMiniMap.tsxnew file mode 100644index 000000000..a4c430821--- /dev/null+++ b/src/renderer/canvas/VisibleMiniMap.tsx@@ -0,0 +1,47 @@+import { useLayoutEffect } from 'react'+import { MiniMap, ReactFlowProvider, useStoreApi, type MiniMapProps } from '@xyflow/react'++type FlowStore = ReturnType<typeof useStoreApi>++/** MiniMap has no node filter: CSS-hidden keep-alive guests otherwise paint rectangles AND+ * enlarge its bounds. Give only the map a filtered store, keeping the canvas's mounted guests+ * untouched. `hidden: true` on the real nodes would unmount their webviews and lose page state.+ * Camera interaction still uses the original panZoom instance; this is not a second camera.+ */+export function VisibleMiniMap(props: MiniMapProps) {+ const source = useStoreApi()+ return (+ <ReactFlowProvider>+ <MiniMapProjection source={source} />+ <MiniMap {...props} />+ </ReactFlowProvider>+ )+}++function MiniMapProjection({ source }: { source: FlowStore }) {+ const target = useStoreApi()+ useLayoutEffect(() => {+ const sync = () => {+ const s = source.getState()+ const visible = (n: { hidden?: boolean; data: Record<string, unknown> }) =>+ !n.hidden && n.data.ghost !== true+ // Internal nodes carry absolute group coordinates and measured sizes. Rebuilding them+ // from serialized/project nodes would lose both and lag live drag/resize/removal updates.+ target.setState({+ nodes: s.nodes.filter(visible),+ nodeLookup: new Map([...s.nodeLookup].filter(([, n]) => visible(n))),+ width: s.width,+ height: s.height,+ transform: s.transform,+ panZoom: s.panZoom,+ translateExtent: s.translateExtent,+ rfId: s.rfId,+ ariaLabelConfig: s.ariaLabelConfig,+ userSelectionActive: s.userSelectionActive+ })+ }+ sync()+ return source.subscribe(sync)+ }, [source, target])+ return null+}