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: 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.tsxindex 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 : 0const { 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) continueconst ph = parent.measured?.height ?? (parent.height as number) ?? 400const accent = agentConfig((parent.data.agentId as string) ?? 'claude')?.color ?? '#d97757'+ const snap = ephSnap+ ? { grid: ephSnap, origin: containerOrigin(parent.parentId, nodes) }+ : undefinedconst 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) continueconst ph = parent.measured?.height ?? (parent.height as number) ?? 400const accent = agentConfig((parent.data.agentId as string) ?? 'claude')?.color ?? '#d97757'+ const snap = ephSnap+ ? { grid: ephSnap, origin: containerOrigin(parent.parentId, nodes) }+ : undefinedconst COLS = 4const COL_W = 240const 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 abovediff --git a/src/renderer/lib/gridSnap.test.ts b/src/renderer/lib/gridSnap.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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