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: snap fan-out cards in root space, not frame space

Bas Milius1a2fe58cf4ce
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 937db3b80..b34dd2aee 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -155,6 +155,7 @@ import { reopenVariants } from '../lib/reopenVariants'
import { modelsForAgent } from '@shared/agents/model-gateway'
import { useModelGateway } from '../state/modelGateway'
import { viewportAtZoom } from '../lib/zoomReset'
+import { containerOrigin, snapPointInRootSpace } from '../lib/gridSnap'
import { zoomFromPct } from '../lib/zoomPresets'
import { CANVAS_MAX_ZOOM, CANVAS_MIN_ZOOM } from './zoom-limits'
import { isSpaceRelease, spacePanKeydown } from '../lib/spacePan'
@@ -645,24 +646,27 @@ const NO_EPHEMERAL: { ephemeralNodes: CanvasNode[]; ephemeralEdges: Edge[] } = {
* ungrouping the agent flips that space between absolute and group-relative, and a stored
* position would then teleport the card by the group's own x/y.
*
- * `snap` (0 = off) rounds the LAID-OUT default onto the grid: React Flow's `snapToGrid` only
+ * `snap` (absent = off) rounds the LAID-OUT default onto the grid: React Flow's `snapToGrid` only
* constrains a drag, so a fan-out card landed off-grid and only jumped into place once the user
* nudged it. A DRAGGED offset is left alone — it was already snapped at drag time if the mode was
* on, and re-rounding it here would move cards the user placed by hand while it was off.
+ *
+ * The snap carries its container's root-space `origin` because the composed position above is
+ * container-relative, and React Flow's own drag snap works in root space — see
+ * `snapPointInRootSpace`.
*/
const offsetFrom = (
parent: { position: { x: number; y: number } },
stored: { x: number; y: number } | undefined,
fallback: { x: number; y: number },
- snap = 0
+ snap?: { grid: number; origin: { x: number; y: number } }
): { x: number; y: number } => {
const off = stored ?? fallback
- const x = parent.position.x + off.x
- const y = parent.position.y + off.y
+ const position = { x: parent.position.x + off.x, y: parent.position.y + off.y }
if (stored || !snap) {
- return { x, y }
+ return position
}
- return { x: Math.round(x / snap) * snap, y: Math.round(y / snap) * snap }
+ return snapPointInRootSpace(position, snap.origin, snap.grid)
}
// Delivering an armed node's held launch (canvas-control `--after`) can lose the race against
@@ -1617,7 +1621,9 @@ export function Canvas() {
// Selection state for ephemeral nodes (they live outside React Flow's managed nodes), owned by
// the agent-nodes store so the cards themselves can set it — see `selectable: false` below.
const ephSelId = useAgentNodes((s) => s.selectedId)
- // Grid the laid-out fan-out cards round onto (0 = snap off) — see offsetFrom.
+ // Grid the laid-out fan-out cards round onto (0 = snap off) — see offsetFrom. A hand-edited
+ // `gridSize: 0` reads as "use the default" here, exactly as it does everywhere else on this
+ // canvas, rather than as a second way to switch snapping off.
const ephSnap = settings.snapToGrid ? settings.gridSize || GRID : 0
const { ephemeralNodes, ephemeralEdges } = useMemo(() => {
// Common case: no /loop running and no subagents → return a stable empty result so
@@ -1648,6 +1654,9 @@ export function Canvas() {
if (!parent || parent.data.hideFanout) continue
const ph = parent.measured?.height ?? (parent.height as number) ?? 400
const accent = agentConfig((parent.data.agentId as string) ?? 'claude')?.color ?? '#d97757'
+ const snap = ephSnap
+ ? { grid: ephSnap, origin: containerOrigin(parent.parentId, nodes) }
+ : undefined
const lid = `loop-${pid}`
eNodes.push({
id: lid,
@@ -1657,7 +1666,7 @@ export function Canvas() {
// with the group). Deliberately no extent:'parent' — the fan-out may hang below the
// frame border without being clamped into it.
...(parent.parentId ? { parentId: parent.parentId } : {}),
- position: offsetFrom(parent, ephemeralPos[lid], { x: -250, y: ph + 60 }, ephSnap),
+ position: offsetFrom(parent, ephemeralPos[lid], { x: -250, y: ph + 60 }, snap),
draggable: true,
// NOT selectable: React Flow's rubber band would otherwise sweep a whole fan-out of cards
// into the selection alongside the real nodes, and every selection action (Group,
@@ -1697,6 +1706,9 @@ export function Canvas() {
if (!parent || parent.data.hideFanout) continue
const ph = parent.measured?.height ?? (parent.height as number) ?? 400
const accent = agentConfig((parent.data.agentId as string) ?? 'claude')?.color ?? '#d97757'
+ const snap = ephSnap
+ ? { grid: ephSnap, origin: containerOrigin(parent.parentId, nodes) }
+ : undefined
const COLS = 4
const COL_W = 240
const ROW_H = 140
@@ -1714,7 +1726,7 @@ export function Canvas() {
x: (i % COLS) * COL_W,
y: ph + 60 + Math.floor(i / COLS) * ROW_H
},
- ephSnap
+ snap
),
draggable: true,
selectable: false, // see the loop card above
diff --git a/src/renderer/lib/gridSnap.test.ts b/src/renderer/lib/gridSnap.test.ts
new file mode 100644
index 000000000..8b87ee9d4
--- /dev/null
+++ b/src/renderer/lib/gridSnap.test.ts
@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest'
+import type { CanvasNode } from '../state/workspace'
+import { containerOrigin, snapPointInRootSpace, snapRectInRootSpace } from './gridSnap'
+
+const G = 20
+
+const node = (
+ id: string,
+ type: string,
+ pos: { x: number; y: number },
+ parentId?: string
+): CanvasNode =>
+ ({
+ id,
+ type,
+ position: pos,
+ width: 320,
+ height: 240,
+ data: { title: id, color: '#888', group: null },
+ ...(parentId ? { parentId, extent: 'parent' as const } : {})
+ }) as unknown as CanvasNode
+
+// `groupSelectedNodes` creates a frame at (minX - 28, minY - 62), so an off-grid frame origin is
+// the normal case rather than an edge case.
+const FRAME = { x: -28, y: -62 }
+
+// `%` keeps the sign of its left operand, so a negative grid multiple yields -0 and `toBe(0)`
+// fails on a value that is on the grid.
+const onGrid = (value: number): boolean => Math.abs(value % G) === 0
+
+describe('containerOrigin', () => {
+ it('is the root for a top-level object', () => {
+ expect(containerOrigin(undefined, [])).toEqual({ x: 0, y: 0 })
+ })
+
+ it('is the frame own root position', () => {
+ const nodes = [node('g1', 'group', FRAME)]
+ expect(containerOrigin('g1', nodes)).toEqual(FRAME)
+ })
+
+ it('sums every ancestor frame in a nested tree', () => {
+ const nodes = [node('g1', 'group', { x: 100, y: 50 }), node('g2', 'group', { x: 7, y: 3 }, 'g1')]
+ expect(containerOrigin('g2', nodes)).toEqual({ x: 107, y: 53 })
+ })
+
+ it('falls back to the root for a dangling parentId', () => {
+ expect(containerOrigin('gone', [node('g1', 'group', FRAME)])).toEqual({ x: 0, y: 0 })
+ })
+})
+
+describe('snapPointInRootSpace', () => {
+ it('snaps a top-level point onto the canvas grid', () => {
+ expect(snapPointInRootSpace({ x: 113, y: 47 }, { x: 0, y: 0 }, G)).toEqual({ x: 120, y: 40 })
+ })
+
+ it('lands a card inside an off-grid frame on the CANVAS grid, not the frame grid', () => {
+ // The card's stored position is frame-relative; only origin + position is on the canvas.
+ const out = snapPointInRootSpace({ x: 113, y: 47 }, FRAME, G)
+ expect(out.x + FRAME.x).toBe(80)
+ expect(out.y + FRAME.y).toBe(-20)
+ expect(onGrid(out.x + FRAME.x)).toBe(true)
+ expect(onGrid(out.y + FRAME.y)).toBe(true)
+ })
+
+ it('is what React Flow drag snap would produce, so the first drag does not move the card', () => {
+ const position = { x: 113, y: 47 }
+ const snapped = snapPointInRootSpace(position, FRAME, G)
+ // XYDrag: snap in flow coordinates, then subtract the parent origin.
+ const dragged = {
+ x: Math.round((snapped.x + FRAME.x) / G) * G - FRAME.x,
+ y: Math.round((snapped.y + FRAME.y) / G) * G - FRAME.y
+ }
+ expect(dragged).toEqual(snapped)
+ })
+
+ it('rounding frame-relative instead would put the card on a different grid', () => {
+ // The bug this helper exists for: the old math rounded the composed frame-relative value.
+ const frameRelative = { x: Math.round(113 / G) * G, y: Math.round(47 / G) * G }
+ expect(snapPointInRootSpace({ x: 113, y: 47 }, FRAME, G)).not.toEqual(frameRelative)
+ })
+
+ it('normalizes -0 so it never reaches project.json', () => {
+ const out = snapPointInRootSpace({ x: -2, y: -3 }, { x: 0, y: 0 }, G)
+ expect(Object.is(out.x, -0)).toBe(false)
+ expect(Object.is(out.y, -0)).toBe(false)
+ })
+
+ it('is a no-op when snapping is off', () => {
+ const point = { x: 113, y: 47 }
+ expect(snapPointInRootSpace(point, FRAME, 0)).toBe(point)
+ })
+})
+
+describe('snapRectInRootSpace', () => {
+ it('snaps every edge of a top-level rect onto the grid', () => {
+ const out = snapRectInRootSpace(
+ { x: 113, y: 47, width: 331, height: 205 },
+ { x: 0, y: 0 },
+ G,
+ 'terminal'
+ )
+ expect(onGrid(out.x)).toBe(true)
+ expect(onGrid(out.y)).toBe(true)
+ expect(onGrid(out.x + out.width)).toBe(true)
+ expect(onGrid(out.y + out.height)).toBe(true)
+ })
+
+ it('puts a child rect edges on the CANVAS grid, not the frame grid', () => {
+ const out = snapRectInRootSpace({ x: 113, y: 47, width: 331, height: 205 }, FRAME, G, 'terminal')
+ expect(onGrid(out.x + FRAME.x)).toBe(true)
+ expect(onGrid(out.y + FRAME.y)).toBe(true)
+ expect(onGrid(out.x + FRAME.x + out.width)).toBe(true)
+ expect(onGrid(out.y + FRAME.y + out.height)).toBe(true)
+ })
+
+ it('is a no-op when snapping is off', () => {
+ const rect = { x: 113, y: 47, width: 331, height: 205 }
+ expect(snapRectInRootSpace(rect, FRAME, 0, 'terminal')).toBe(rect)
+ })
+})
diff --git a/src/renderer/lib/gridSnap.ts b/src/renderer/lib/gridSnap.ts
new file mode 100644
index 000000000..fb19d1626
--- /dev/null
+++ b/src/renderer/lib/gridSnap.ts
@@ -0,0 +1,63 @@
+import type { NodeKind } from '@shared/types'
+import type { CanvasNode } from '../state/workspace'
+import { rootPosition } from '../state/workspace'
+import { snapNodeToGrid, type Rect } from './nodeSizing'
+
+export interface Point {
+ x: number
+ y: number
+}
+
+const ROOT_ORIGIN: Point = { x: 0, y: 0 }
+
+/**
+ * Root-space origin of the container `parentId` names: (0, 0) for a top-level object, else the
+ * frame's own root position. A missing frame resolves to the root rather than throwing, matching
+ * how the rest of the canvas treats a dangling parentId.
+ */
+export function containerOrigin(parentId: string | undefined, nodes: CanvasNode[]): Point {
+ if (!parentId) return ROOT_ORIGIN
+ const frame = nodes.find((node) => node.id === parentId)
+ if (!frame) return ROOT_ORIGIN
+ return rootPosition(frame, nodes)
+}
+
+/**
+ * Snap a CONTAINER-relative point onto the canvas grid.
+ *
+ * React Flow snaps a drag in flow (root) coordinates and only converts to parent-relative
+ * afterwards: `XYDrag` runs `snapPosition(nextPosition, snapGrid)` and `calculateNodePosition`
+ * subtracts the parent origin after that. Rounding a parent-relative value directly instead puts
+ * the object on the FRAME's grid, and `groupSelectedNodes` creates frames at
+ * `(minX - 28, minY - 62)`, so an off-grid frame origin is the normal case — the two grids then
+ * differ by the frame's own fractional offset and the first drag moves the object again.
+ */
+export function snapPointInRootSpace(point: Point, origin: Point, grid: number): Point {
+ if (grid <= 0) return point
+ const x = Math.round((point.x + origin.x) / grid) * grid - origin.x
+ const y = Math.round((point.y + origin.y) / grid) * grid - origin.y
+ // `+ 0` normalizes the -0 that rounding a small negative coordinate produces, which would
+ // otherwise ride into node positions and out to project.json.
+ return { x: x + 0, y: y + 0 }
+}
+
+/**
+ * Snap a CONTAINER-relative rect onto the canvas grid, in root space for the reason above, then
+ * hand it back in the caller's coordinate space. Sizes are grid deltas, so only the origin has to
+ * cross spaces.
+ */
+export function snapRectInRootSpace(rect: Rect, origin: Point, grid: number, kind: NodeKind): Rect {
+ if (grid <= 0) return rect
+ const snapped = snapNodeToGrid(grid, kind, {
+ x: rect.x + origin.x,
+ y: rect.y + origin.y,
+ width: rect.width,
+ height: rect.height
+ })
+ return {
+ x: snapped.x - origin.x + 0,
+ y: snapped.y - origin.y + 0,
+ width: snapped.width,
+ height: snapped.height
+ }
+}
diff --git a/src/renderer/state/workspace.ts b/src/renderer/state/workspace.ts
index edceb2085..066925469 100644
--- a/src/renderer/state/workspace.ts
+++ b/src/renderer/state/workspace.ts
@@ -1259,7 +1259,7 @@ function groupsFirst(nodes: CanvasNode[]): CanvasNode[] {
}
/** A node's position in ROOT space: its own position plus every ancestor frame's origin. */
-function rootPosition(node: CanvasNode, nodes: CanvasNode[]): { x: number; y: number } {
+export function rootPosition(node: CanvasNode, nodes: CanvasNode[]): { x: number; y: number } {
const byId = new Map(nodes.map((candidate) => [candidate.id, candidate]))
const seen = new Set<string>([node.id])
let x = node.position.x