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.

fix(minimap): exclude keep-alive ghosts from drawing and bounds

review5bdd69b783e9
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 entry
is dropped at the deletion funnels (handleNodesChange's `remove`, `deleteNodes`, the peer-mutation
remove, 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 is
hidden, 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 hold
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 un
does 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 is
measured) or the next `updateNodeInternals`, against whatever the node lookup holds by then; a fit
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 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
+ <VisibleMiniMap
className="minimap"
position="bottom-right"
pannable
diff --git a/src/renderer/canvas/VisibleMiniMap.test.tsx b/src/renderer/canvas/VisibleMiniMap.test.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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
+}