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.

feat(canvas-control): group, move, arrange and align a project that is not on screen

Fabricio Casali4adcb9f9af41
diff --git a/CLAUDE.md b/CLAUDE.md
index ef1965189..f32faf702 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3780,9 +3780,19 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
`STORE_ANSWERED_VERBS` (no canvas at either end), `COLD_OPENABLE_VERBS` (a session node, armed
and inert until shown), `OFF_CANVAS_VERBS` (a display node, complete when written),
`STORED_NODE_VERBS` (`write`/`close`/`rename`/`color`/`link`/`board`/`assign` — each reaches a
- pane, a store writer or the board file), and `OFF_SCREEN_REFUSALS` (the eleven that genuinely
+ pane, a store writer or the board file — plus the five layout verbs
+ `group`/`ungroup`/`move`/`arrange`/`align`), and `OFF_SCREEN_REFUSALS` (the six that genuinely
need live React Flow, each with its own reason in the refusal the agent reads). A refusal an
- agent can act on is strictly better than hijacking someone's screen. Load-bearing details:
+ agent can act on is strictly better than hijacking someone's screen. **The layout verbs off
+ screen lay out from PERSISTED sizes** (nothing there was measured; a node is born at a persisted
+ default size and a user resize is persisted too, so the gap is at most the overlap a live canvas
+ can already show) and write back through `commitCtlNodes` → `geometryMutations`
+ (`renderer/lib/storedGeometry.ts`): only the geometry that changed (`position`/`size`/`parentId`/
+ `group`) is patched onto the STORED node, a created frame is added whole, only a frame is ever
+ removed, and the batch lands in one `applyOwnNodeMutations` re-sorted parents-first. Never write
+ the hydrated array back whole: that round-trips every node through the serializers. They were
+ refusals until 2026-09-30; an orchestrator that could open a team off screen but never frame it
+ was the report that moved them. Load-bearing details:
(1) **`ctlNodes()` is the one name for "the node array this call acts on"** — on screen it is
`nodesRef.current` verbatim, off canvas it is the owning project's serialized nodes hydrated by
`nodeStatesToFlow`. A verb body that resolves `--node` against the live array while answering
diff --git a/src/main/canvas-control-core.test.ts b/src/main/canvas-control-core.test.ts
index 0116f7743..e4ab9605c 100644
--- a/src/main/canvas-control-core.test.ts
+++ b/src/main/canvas-control-core.test.ts
@@ -1218,7 +1218,7 @@ describe('the --project clause tells the truth about travel (review #363 I-1 + M
}
// Every refused verb is named AND carries its own reason — a bare list would tell an agent
// that `branch` and `arrange` fail for the same cause, and they do not.
- for (const v of ['group', 'ungroup', 'move', 'arrange', 'align', 'verify', 'spawn-team', 'branch', 'open-worktree', 'close-worktree', 'browser']) {
+ for (const v of ['verify', 'spawn-team', 'branch', 'open-worktree', 'close-worktree', 'browser']) {
const d = offScreenDisposition(v)
expect(d.kind, v).toBe('refuse')
if (d.kind !== 'refuse') continue
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 72a50b0d8..3cbdd8e20 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -319,6 +319,7 @@ import {
storedAgentIdOf,
type ColdNode
} from '../lib/coldOpen'
+import { geometryMutations } from '../lib/storedGeometry'
import { stampOpenedBy, withOpenedBy } from '../lib/stationOpener'
import { installStationNoticeWiring } from '../lib/stationNoticeWiring'
import { installBoardDispatchReportWiring } from '../lib/boardDispatchReportWiring'
@@ -13195,6 +13196,24 @@ export function Canvas() {
// against a stranger's project.
const ctlNodes = (): CanvasNode[] =>
offCanvas ? offCanvas.nodes : (nodesRef.current as CanvasNode[])
+ // The write twin of `ctlNodes`, for the structural verbs (group/ungroup/move/arrange/align)
+ // that compute a whole new node array. On screen it is the live write it always was. Off
+ // canvas it writes only what changed into the owning project's stored nodes — geometry of
+ // the nodes that moved, plus a frame created or dissolved (lib/storedGeometry.ts) — through
+ // our own store writer, and persists it. The layout was computed from the persisted sizes,
+ // which is what an unmeasured canvas has.
+ const commitCtlNodes = (next: CanvasNode[]): void => {
+ if (!offCanvas) {
+ setNodes(next)
+ markDirty()
+ return
+ }
+ const st = useProjects.getState()
+ const stored = st.getProject(offCanvas.project.id)?.nodes ?? []
+ st.applyOwnNodeMutations(offCanvas.project.id, geometryMutations(stored, next))
+ offCanvas.nodes = next
+ void writeDisk()
+ }
// `linkEndpointOf` off canvas. Same answer, read out of the hydrated array: the live one
// holds another project's nodes, so every id would resolve to null (or, worse, to a
// same-named node over there).
@@ -13829,7 +13848,7 @@ export function Canvas() {
}
}
const ids = (args.nodes ?? '').split(',').map((s) => s.trim()).filter(Boolean)
- const live = nodesRef.current as CanvasNode[]
+ const live = ctlNodes()
const resolvable = ids.filter((id) => live.some((node) => node.id === id))
if (resolvable.length === 0) {
reply({ ok: false, error: 'group: none of the given node ids exist' })
@@ -13859,8 +13878,7 @@ export function Canvas() {
: nd
)
}
- setNodes(grouped)
- markDirty()
+ commitCtlNodes(grouped)
const skippedGrouped = ids.length - resolvable.length
const groupNote = skippedGrouped > 0 ? ` (${skippedGrouped} unknown id(s) skipped)` : ''
reply({
@@ -13872,15 +13890,14 @@ export function Canvas() {
}
case 'ungroup': {
const gid = (args.group ?? '').trim()
- const live = nodesRef.current as CanvasNode[]
+ const live = ctlNodes()
const frame = live.find((nd) => nd.id === gid && nd.type === 'group')
if (!frame) {
reply({ ok: false, error: `ungroup: --group names no group frame (${gid || 'missing'})` })
return
}
const freed = live.filter((nd) => nd.parentId === gid).map((nd) => nd.id)
- setNodes(ungroupNodes(live, gid))
- markDirty()
+ commitCtlNodes(ungroupNodes(live, gid))
reply({ ok: true, message: `ungrouped ${gid}, freed ${freed.length} node(s)`, result: { freed } })
return
}
@@ -13890,7 +13907,7 @@ export function Canvas() {
// deliberately won't do. `reparentNode` keeps each node's ROOT-space position fixed
// and refuses a cycle (a frame into itself or its own descendant).
const ids = (args.nodes ?? '').split(',').map((s) => s.trim()).filter(Boolean)
- const live = nodesRef.current as CanvasNode[]
+ const live = ctlNodes()
const rawTarget = (args.group ?? '').trim().toLowerCase()
const toTop = !rawTarget || rawTarget === 'top' || rawTarget === 'none' || rawTarget === 'ungrouped'
const targetGroup = toTop ? null : args.group!.trim()
@@ -13922,8 +13939,7 @@ export function Canvas() {
for (const g of affected) {
if (next.some((n) => n.parentId === g)) next = fitGroupToChildren(next, g, snapGridNow())
}
- setNodes(next)
- markDirty()
+ commitCtlNodes(next)
const where = targetGroup ? `into ${targetGroup}` : 'to the top level'
reply({ ok: true, message: `moved ${moved.length} node(s) ${where}`, result: { moved, group: targetGroup } })
return
@@ -13931,7 +13947,7 @@ export function Canvas() {
case 'arrange':
case 'align': {
const ids = (args.nodes ?? '').split(',').map((s) => s.trim()).filter(Boolean)
- const live = nodesRef.current as CanvasNode[]
+ const live = ctlNodes()
const edge = (['left', 'right', 'top', 'bottom', 'hcenter', 'vcenter'] as const).find((e2) => e2 === args.edge)
if (verb === 'align' && !edge) {
reply({ ok: false, error: 'align requires --edge left|right|top|bottom|hcenter|vcenter' })
@@ -13959,8 +13975,7 @@ export function Canvas() {
// Tidying a frame's children usually leaves the frame oversized (it was sized to their
// old scattered spots) — shrink it to hug the new layout. Top-level sets have no frame.
if (container) next = fitGroupToChildren(next, container, snapGridNow())
- setNodes(next)
- markDirty()
+ commitCtlNodes(next)
const how = verb === 'arrange' ? `as ${layout}` : `to ${edge}`
reply({ ok: true, message: `${verb === 'arrange' ? 'arranged' : 'aligned'} ${ids.length} node(s) ${how}`, result: { count: ids.length, container } })
return
diff --git a/src/renderer/lib/controlRouting.test.ts b/src/renderer/lib/controlRouting.test.ts
index a0c91e186..2c36da997 100644
--- a/src/renderer/lib/controlRouting.test.ts
+++ b/src/renderer/lib/controlRouting.test.ts
@@ -393,24 +393,26 @@ describe('the off-screen disposition table (the verbs that used to travel)', ()
}
})
- it('the structural verbs refuse, and each says WHY in its own words', () => {
+ it('the structural layout verbs are answered from the stored nodes (persisted sizes)', () => {
+ for (const v of ['group', 'ungroup', 'move', 'arrange', 'align']) {
+ expect(offScreenDisposition(v), v).toEqual({ kind: 'stored-node' })
+ }
+ })
+
+ it('the verbs that still refuse each say WHY in their own words', () => {
// A refusal an agent can act on beats hijacking the human's screen. The reasons are per verb
- // because the caller's next move differs: an `arrange` can wait for the human, a `branch`
+ // because the caller's next move differs: a `verify` can wait for the human, a `branch`
// cannot happen at all until that terminal is mounted.
const why = (v: string) => {
const d = offScreenDisposition(v)
expect(d.kind, v).toBe('refuse')
return d.kind === 'refuse' ? d.why : ''
}
- expect(why('arrange')).toMatch(/measured/)
- expect(why('group')).toMatch(/measured/)
expect(why('branch')).toMatch(/parks the original/)
expect(why('verify')).toMatch(/live canvas/)
+ expect(why('spawn-team')).toMatch(/live canvas/)
expect(why('open-worktree')).toMatch(/worktree store/)
expect(why('browser')).toMatch(/webview/)
- // …and no two structural verbs share a copy-pasted sentence that names the wrong mechanism.
- expect(why('move')).toContain('reparenting')
- expect(why('align')).toContain('aligning')
})
it('an unknown verb refuses — the fail-closed direction', () => {
@@ -435,9 +437,9 @@ describe('the off-screen disposition table (the verbs that used to travel)', ()
})
it('the refusal sentence names the project, the reason and the fact that nothing happened', () => {
- const msg = offScreenRefusal('group', 'web-app')
- expect(msg.startsWith('group: project "web-app" is not on screen')).toBe(true)
- expect(msg).toContain('measured node sizes')
+ const msg = offScreenRefusal('branch', 'web-app')
+ expect(msg.startsWith('branch: project "web-app" is not on screen')).toBe(true)
+ expect(msg).toContain('parks the original session')
expect(msg).toContain('Open that project and run this again')
expect(msg).toContain('nothing was changed')
})
diff --git a/src/renderer/lib/storedGeometry.test.ts b/src/renderer/lib/storedGeometry.test.ts
new file mode 100644
index 000000000..701f078b5
--- /dev/null
+++ b/src/renderer/lib/storedGeometry.test.ts
@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest'
+import type { CanvasNodeState } from '@shared/types'
+import { applyOwnCanvasMutation, groupSelectedNodes, nodeStatesToFlow, ungroupNodes } from '../state/workspace'
+import { groupsFirst } from '@shared/node-order'
+import { geometryMutations } from './storedGeometry'
+
+const term = (id: string, x: number, extra: Partial<CanvasNodeState> = {}): CanvasNodeState =>
+ ({
+ id,
+ kind: 'terminal',
+ position: { x, y: 0 },
+ size: { width: 600, height: 400 },
+ title: id,
+ color: '#0a84ff',
+ group: null,
+ tags: [],
+ collapsed: false,
+ ...extra
+ }) as CanvasNodeState
+
+// The stored project, as the store holds it: one node carries a held launch the serializers must
+// never be trusted to round-trip.
+const stored: CanvasNodeState[] = [
+ term('a', 0, { pendingLaunch: { after: [], command: 'claude' } } as Partial<CanvasNodeState>),
+ term('b', 700),
+ term('c', 1400)
+]
+
+const apply = (nodes: CanvasNodeState[], ms: ReturnType<typeof geometryMutations>) =>
+ groupsFirst(ms.reduce(applyOwnCanvasMutation, nodes))
+
+describe('geometryMutations — a structural verb run off screen', () => {
+ it('groups from persisted sizes: a new frame, children re-parented, nothing else rewritten', () => {
+ const next = groupSelectedNodes(nodeStatesToFlow(stored), ['a', 'b'], 0, false)
+ const ms = geometryMutations(stored, next)
+ const after = apply(stored, ms)
+ const frame = after.find((n) => n.kind === 'group')!
+ expect(frame).toBeTruthy()
+ expect(after[0].id).toBe(frame.id) // parents first
+ expect(after.find((n) => n.id === 'a')!.parentId).toBe(frame.id)
+ expect(after.find((n) => n.id === 'b')!.parentId).toBe(frame.id)
+ // The frame wraps both 600-wide nodes laid out from their persisted size.
+ expect(frame.size.width).toBeGreaterThanOrEqual(1300)
+ // The untouched node is not rewritten, and the held launch survives on the moved one.
+ expect(ms.some((m) => m.op === 'upsert' && m.node.id === 'c')).toBe(false)
+ expect(after.find((n) => n.id === 'a')!.pendingLaunch).toEqual({ after: [], command: 'claude' })
+ })
+
+ it('ungroup removes only the frame and frees its children', () => {
+ const grouped = apply(stored, geometryMutations(stored, groupSelectedNodes(nodeStatesToFlow(stored), ['a', 'b'], 0, false)))
+ const frameId = grouped.find((n) => n.kind === 'group')!.id
+ const ms = geometryMutations(grouped, ungroupNodes(nodeStatesToFlow(grouped), frameId))
+ const after = apply(grouped, ms)
+ expect(after.map((n) => n.id).sort()).toEqual(['a', 'b', 'c'])
+ expect(after.every((n) => n.parentId === undefined)).toBe(true)
+ expect(ms.filter((m) => m.op === 'remove')).toEqual([{ op: 'remove', id: frameId }])
+ })
+
+ it('never removes a non-frame the hydration did not return', () => {
+ const ms = geometryMutations(stored, nodeStatesToFlow(stored.slice(0, 2)))
+ expect(ms).toEqual([])
+ })
+})
diff --git a/src/renderer/lib/storedGeometry.ts b/src/renderer/lib/storedGeometry.ts
new file mode 100644
index 000000000..4c7f2fbd2
--- /dev/null
+++ b/src/renderer/lib/storedGeometry.ts
@@ -0,0 +1,53 @@
+// The write half of a structural control verb (`group`, `ungroup`, `move`, `arrange`, `align`) run
+// against a project that is NOT on screen.
+//
+// Those verbs compute a whole new node array through the same pure transforms the live canvas uses
+// (`groupSelectedNodes`, `reparentNode`, `arrangeNodes`, …), over the owning project's serialized
+// nodes hydrated by `nodeStatesToFlow`. Off screen nothing was ever measured, so the sizes they lay
+// out with are the persisted ones — which is what a node is born with and what it keeps until the
+// user resizes it, so the layout matches what the user will see closely enough (a node the user
+// resized is persisted at that size too).
+//
+// Writing that array back whole would round-trip every node through the serializers. This turns it
+// into the smallest set of ops instead: an existing node keeps EVERY stored field (exec overlay,
+// launch, account, …) and only takes the geometry the verb changed; a frame the verb created is
+// added whole; a frame the verb dissolved is removed. Nothing else is ever removed.
+
+import type { CanvasMutation, CanvasNodeState } from '@shared/types'
+import { flowToNodeStates, type CanvasNode } from '../state/workspace'
+
+/** The fields a structural verb may change on a node that already exists. */
+const GEOMETRY = ['position', 'size', 'parentId', 'group'] as const
+
+// null and absent are the same fact here (`group: null` vs no `group`), or an untouched node would
+// be rewritten just for its spelling.
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a ?? null) === JSON.stringify(b ?? null)
+
+export function geometryMutations(
+ stored: readonly CanvasNodeState[],
+ next: readonly CanvasNode[]
+): CanvasMutation[] {
+ const byId = new Map(stored.map((n) => [n.id, n]))
+ const out: CanvasMutation[] = []
+ const kept = new Set<string>()
+ for (const n of flowToNodeStates(next as CanvasNode[])) {
+ kept.add(n.id)
+ const s = byId.get(n.id)
+ if (!s) {
+ out.push({ op: 'upsert', node: n })
+ continue
+ }
+ const changed = GEOMETRY.filter((k) => !same(s[k], n[k]))
+ if (changed.length === 0) continue
+ const patched: CanvasNodeState = { ...s }
+ for (const k of changed) {
+ if (n[k] === undefined) delete (patched as Partial<CanvasNodeState>)[k]
+ else (patched as unknown as Record<string, unknown>)[k] = n[k]
+ }
+ out.push({ op: 'upsert', node: patched })
+ }
+ // Only a FRAME can be dissolved by these verbs (`ungroup`). A non-frame missing from `next` is one
+ // the hydration skipped, and it is not this write's to delete.
+ for (const s of stored) if (!kept.has(s.id) && s.kind === 'group') out.push({ op: 'remove', id: s.id })
+ return out
+}
diff --git a/src/renderer/state/projects.ts b/src/renderer/state/projects.ts
index f88170583..c7ee33b92 100644
--- a/src/renderer/state/projects.ts
+++ b/src/renderer/state/projects.ts
@@ -25,6 +25,7 @@ import {
} from '@shared/canvas-layout'
import { applyCanvasOp as applyCanvasOpTo, contentOf } from '@shared/canvas-content'
import { diffToMutations, type CanvasScene } from '@shared/canvas-mutations'
+import { groupsFirst } from '@shared/node-order'
import { applyOwnCanvasMutation, createProject, reorderGroupWithinParent } from './workspace'
import { registerCodexRelayProjectCheck } from './codexCli'
import { markWorkspaceDirty } from './workspaceDirty'
@@ -191,6 +192,9 @@ interface ProjectsState {
* Never route a peer's mutation through this.
*/
applyOwnNodeMutation(projectId: string, mutation: CanvasMutation): boolean
+ /** Several of our own node writes as ONE store write, re-sorted parents-first (`groupsFirst`) —
+ * a structural control verb run off screen adds a frame after the children it now holds. */
+ applyOwnNodeMutations(projectId: string, mutations: readonly CanvasMutation[]): boolean
/** Renames a node within a project (source of truth for inactive projects). */
renameNode(projectId: string, nodeId: string, title: string): void
/** Recolors a node within a project. */
@@ -740,6 +744,19 @@ export const useProjects = create<ProjectsState>((set, get) => ({
return true
},
+ applyOwnNodeMutations(projectId, mutations) {
+ if (!get().projects.some((p) => p.id === projectId)) return false
+ if (mutations.length === 0) return true
+ ownWrite(get, projectId, () =>
+ set((s) => ({
+ projects: mapProjectNodes(s.projects, projectId, (nodes) =>
+ groupsFirst(mutations.reduce(applyOwnCanvasMutation, nodes))
+ )
+ }))
+ )
+ return true
+ },
+
renameNode(projectId, nodeId, title) {
ownWrite(get, projectId, () =>
set((s) => ({
diff --git a/src/shared/control-off-screen.ts b/src/shared/control-off-screen.ts
index 7626fca3e..06465d11f 100644
--- a/src/shared/control-off-screen.ts
+++ b/src/shared/control-off-screen.ts
@@ -212,12 +212,24 @@ export function answersOffCanvas(verb: string): boolean {
* to read `activeProjectId`, which off canvas was a second bug hiding behind the first: after
* the travel the two projects were the same, so the wrong read was never wrong in practice.
*
+ * - `group` / `ungroup` / `move` / `arrange` / `align` lay out from persisted sizes (below).
+ *
* Deliberately NOT here — and these REFUSE rather than travel, see `offScreenDisposition`: the
- * structural verbs. A refusal an agent can act on is strictly better than hijacking the human's
+ * verbs that arm a graph, park a live terminal, read the worktree store or drive a webview. A refusal an agent can act on is strictly better than hijacking the human's
* screen, and every one of these would have to guess at something the serialized copy does not
* carry.
*/
const STORED_NODE_VERBS: ReadonlySet<string> = new Set([
+ // The five structural verbs run their pure transforms over the stored nodes, laid out from the
+ // PERSISTED sizes (nothing off screen was measured — but a node is born at a persisted default
+ // size and keeps it until the user resizes it, which is persisted too), and write back only the
+ // geometry that changed (renderer/lib/storedGeometry.ts). They were refused here once; a team an
+ // orchestrator could open off screen but never frame was the worse outcome.
+ 'group',
+ 'ungroup',
+ 'move',
+ 'arrange',
+ 'align',
'write',
'close',
'run',
@@ -242,16 +254,6 @@ export function answersFromStoredNodes(verb: string): boolean {
* verb unable to act, it says so.
*/
const OFF_SCREEN_REFUSALS: Readonly<Record<string, string>> = {
- // The five structural verbs rewrite the WHOLE node array through React Flow's parent/extent
- // model and re-fit frames from MEASURED sizes (`nodeW`/`nodeH` prefer `measured` over the
- // persisted `size`), which the serialized copy does not carry — nothing rendered it. Laying a
- // canvas out to geometry the user would not get on screen, and round-tripping every node
- // through the serializers to persist it, is drift no reply could report.
- group: 'grouping re-fits frames from measured node sizes, which only a rendered canvas has',
- ungroup: 'ungrouping re-fits frames from measured node sizes, which only a rendered canvas has',
- move: 'reparenting re-fits both frames from measured node sizes, which only a rendered canvas has',
- arrange: 'arranging lays nodes out from measured node sizes, which only a rendered canvas has',
- align: 'aligning lays nodes out from measured node sizes, which only a rendered canvas has',
// Both compose `--after` arming and context bridges over nodes created in the SAME tick, and
// check each dep against the live canvas before arming it. A cold open defers ONE node's launch;
// these defer a graph, and an armed station is fired by the live canvas effect.