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
import { describe, it, expect, vi, afterEach } from 'vitest'
import {
applyCanvasMutation,
applyEdgeMutation,
applyEdgeMutationToScene,
createMutationGuard,
diffToMutations,
isCanvasMutation,
isWellFormedMutation,
MUTATION_MAX_BYTES,
sanitizeCanvasMutation
} from './canvas-mutations'
import type { BridgeLink, CanvasMutation, CanvasNodeState } from './types'
const n = (id: string, x = 0, title = 't'): CanvasNodeState =>
({
id,
kind: 'terminal',
title,
color: '#fff',
position: { x, y: 0 },
size: { width: 100, height: 100 }
}) as CanvasNodeState
describe('applyCanvasMutation', () => {
it('upserts by id (append when absent, replace when present) without mutating the input', () => {
const a = [n('1')]
expect(applyCanvasMutation(a, { op: 'upsert', node: n('2') }).map((x) => x.id)).toEqual([
'1',
'2'
])
expect(applyCanvasMutation(a, { op: 'upsert', node: n('1', 9) })[0].position.x).toBe(9)
expect(a[0].position.x).toBe(0)
})
it('removes by id', () => {
expect(
applyCanvasMutation([n('1'), n('2')], { op: 'remove', id: '1' }).map((x) => x.id)
).toEqual(['2'])
})
// A held launch (`pendingLaunch`) is machine-local (@shared/node-exec). The APPEND branch is the
// one the Server Edition's headless factory depends on: it publishes a brand-new held node, and
// an owner tab must receive it WITH its launch, or that tab's next save drops the launch.
describe('pendingLaunch on an APPENDED node', () => {
const held = { after: [], command: 'claude "brief"', attempted: true, manualOnly: true }
it('a core-vouched upsert of a node we do not have keeps its launch', () => {
const out = applyCanvasMutation([n('1')], { op: 'upsert', node: { ...n('2'), pendingLaunch: held }, origin: 'core' })
expect(out.find((x) => x.id === '2')?.pendingLaunch).toEqual(held)
})
it('an unvouched (peer) upsert of a node we do not have drops it', () => {
const out = applyCanvasMutation([n('1')], { op: 'upsert', node: { ...n('2'), pendingLaunch: held } })
expect(out.find((x) => x.id === '2')).toBeDefined()
expect(out.find((x) => x.id === '2')?.pendingLaunch).toBeUndefined()
})
})
})
describe('diffToMutations', () => {
it('emits an upsert for added and changed nodes and a remove for dropped ones', () => {
expect(diffToMutations([n('1')], [n('1', 5)])).toEqual([{ op: 'upsert', node: n('1', 5) }])
expect(diffToMutations([n('1')], [n('1'), n('2')])).toEqual([{ op: 'upsert', node: n('2') }])
expect(diffToMutations([n('1'), n('2')], [n('1')])).toEqual([{ op: 'remove', id: '2' }])
})
it('emits nothing when the snapshots are deep-equal regardless of key order', () => {
const a = {
id: '1',
kind: 'terminal',
position: { x: 1, y: 2 },
size: { width: 3, height: 4 }
} as CanvasNodeState
const b = {
size: { height: 4, width: 3 },
position: { y: 2, x: 1 },
kind: 'terminal',
id: '1'
} as CanvasNodeState
expect(diffToMutations([a], [b])).toEqual([])
})
it('detects a title/color/collapsed change, not just geometry', () => {
expect(diffToMutations([n('1')], [n('1', 0, 'renamed')])).toEqual([
{ op: 'upsert', node: n('1', 0, 'renamed') }
])
})
})
// The publisher's guard: the same verdict as `isCanvasMutation`, but it must not PAY for it twice on
// an unchanged node. The size check serializes the whole node, the publisher re-emits a refused node
// on every publish (that is what makes it sync the moment the user trims it), and a drag publishes at
// 20 Hz — so the one node that is already pathological (a sticky holding a pasted document) was being
// stringified 20×/s, at a cost proportional to its size.
describe('createMutationGuard', () => {
afterEach(() => vi.restoreAllMocks())
/** A sticky over the size cap. `text` is the SAME string on every rebuild — exactly what
* flowToNodeStates does: it rebuilds the node object each publish but passes `data.text` through
* by reference. */
const bigText = 'x'.repeat(MUTATION_MAX_BYTES)
const fat = (x = 0, text = bigText): CanvasNodeState =>
({ ...n('sticky-1', x), kind: 'sticky', text }) as CanvasNodeState
/** Count only the serializations of a NODE (the expensive path) — not vitest's own internals. */
const countSerializations = (): { calls: () => number } => {
const spy = vi.spyOn(JSON, 'stringify')
return {
calls: () =>
spy.mock.calls.filter((c) => {
const v = c[0] as { node?: { id?: unknown } } | undefined
return !!v && typeof v === 'object' && !!v.node
}).length
}
}
it('serializes an unchanged oversized node ONCE, however many times it is re-published', () => {
const guard = createMutationGuard()
const { calls } = countSerializations()
// 40 publishes of the SAME (still oversized) sticky — two seconds of a 20 Hz drag.
for (let i = 0; i < 40; i++) {
expect(guard({ op: 'upsert', node: fat(), src: 'me' })).toBe(false)
}
expect(calls()).toBe(1) // was: 40 — one full serialization of a 256 KB node per publish
})
it('re-validates the moment the node actually changes (and the trimmed sticky syncs)', () => {
const guard = createMutationGuard()
expect(guard({ op: 'upsert', node: fat() })).toBe(false)
// Still too big, but MOVED: a changed node is a new verdict, so it is paid for again…
const { calls } = countSerializations()
expect(guard({ op: 'upsert', node: fat(7) })).toBe(false)
expect(calls()).toBe(1)
// …and the user trims it → it is within the cap → it CASTS. (The refusal must not be sticky:
// the whole point of retrying a refused node is that it syncs as soon as it fits.)
expect(guard({ op: 'upsert', node: fat(7, 'short') })).toBe(true)
// …and stays castable afterwards, without re-consulting a stale refusal.
expect(guard({ op: 'upsert', node: fat(7, 'short') })).toBe(true)
})
it('gives exactly the verdict of isCanvasMutation (shape, ids, geometry, size)', () => {
const guard = createMutationGuard()
const cases: unknown[] = [
{ op: 'upsert', node: n('1') },
{ op: 'remove', id: '1' },
{ op: 'remove', id: '' },
{ op: 'upsert', node: { ...n('1'), id: '' } },
{ op: 'upsert', node: { ...n('1'), position: { x: NaN, y: 0 } } },
{ op: 'upsert', node: fat() },
{ op: 'nope' },
null
]
for (const c of cases) {
expect(guard(c as never), JSON.stringify(c).slice(0, 40)).toBe(isCanvasMutation(c))
}
})
it('remembers a refusal per node — one fat sticky does not mask another', () => {
const guard = createMutationGuard()
const other = (): CanvasNodeState =>
({ ...n('sticky-2'), kind: 'sticky', text: bigText }) as CanvasNodeState
expect(guard({ op: 'upsert', node: fat() })).toBe(false)
expect(guard({ op: 'upsert', node: other() })).toBe(false)
const { calls } = countSerializations()
expect(guard({ op: 'upsert', node: fat() })).toBe(false)
expect(guard({ op: 'upsert', node: other() })).toBe(false)
expect(calls()).toBe(0) // both refusals are remembered, neither is re-serialized
})
})
// ── Edges ────────────────────────────────────────────────────────────────────────────────────────
// Edges (`bridges` = context links, `ropes` = display-only lineage) ride the same whole-file save as
// the nodes but were NOT in the mutation vocabulary. So an edge you drew never reached your
// teammate — and their next save, of a canvas that never had it, DELETED it. Syncing them is what
// makes the file both clients converge on the file they both agree with.
const e = (id: string, source = 'a', target = 'b'): BridgeLink => ({ id, source, target })
describe('applyEdgeMutation', () => {
it('appends, replaces and removes by id without mutating the input', () => {
const list = [e('x')]
expect(
applyEdgeMutation(list, 'bridge', { op: 'edge-upsert', kind: 'bridge', edge: e('y') })
).toHaveLength(2)
expect(
applyEdgeMutation(list, 'bridge', {
op: 'edge-upsert',
kind: 'bridge',
edge: e('x', 'a', 'z')
})[0].target
).toBe('z')
expect(
applyEdgeMutation(list, 'bridge', { op: 'edge-remove', kind: 'bridge', id: 'x' })
).toEqual([])
expect(list).toEqual([e('x')]) // untouched
})
it('leaves the OTHER kind alone, by reference (a rope mutation is not a bridge edit)', () => {
const list = [e('x')]
expect(applyEdgeMutation(list, 'bridge', { op: 'edge-upsert', kind: 'rope', edge: e('r') })).toBe(
list
)
expect(applyEdgeMutation(list, 'bridge', { op: 'remove', id: 'x' })).toBe(list)
})
// A duplicate cast (every Server Edition tab re-casts a server-written edge) must not cost a
// setState + markDirty + save on every receiver.
it('keeps identity when an upsert carries the edge we already hold', () => {
const list = [e('x')]
expect(applyEdgeMutation(list, 'bridge', { op: 'edge-upsert', kind: 'bridge', edge: e('x') })).toBe(
list
)
})
it('keeps identity when a remove names an edge we do not have', () => {
const list = [e('x')]
expect(applyEdgeMutation(list, 'bridge', { op: 'edge-remove', kind: 'bridge', id: 'q' })).toBe(
list
)
})
it('carries only the three ids — decoration is re-derived per client, never sent', () => {
const fat = { ...e('x'), style: { stroke: 'red' } } as unknown as BridgeLink
const [out] = applyEdgeMutation([], 'bridge', { op: 'edge-upsert', kind: 'bridge', edge: fat })
expect(Object.keys(out).sort()).toEqual(['id', 'source', 'target'])
})
})
// `mutationKey` leaves `kind` out (`e:<id>`): one id is one edge. The apply has to agree, or a
// rope upsert for an id the bridge list already holds leaves that id in BOTH lists.
describe('applyEdgeMutationToScene — one id is one edge', () => {
it('an edge id lives in one list', () => {
const s0 = { bridges: [{ id: 'x', source: 'a', target: 'b' }], ropes: [] }
const s1 = applyEdgeMutationToScene(s0, { op: 'edge-upsert', kind: 'rope', edge: { id: 'x', source: 'a', target: 'b' } })
expect(s1).toEqual({ bridges: [], ropes: [{ id: 'x', source: 'a', target: 'b' }] })
expect(applyEdgeMutationToScene(s1, { op: 'edge-remove', kind: 'bridge', id: 'x' })).toEqual({ bridges: [], ropes: [] })
})
it('keeps both lists by reference when nothing changes (the caller short-circuit fires)', () => {
const s = { bridges: [e('x')], ropes: [e('r')] }
const same = (m: Parameters<typeof applyEdgeMutationToScene>[1]) => {
const out = applyEdgeMutationToScene(s, m)
expect(out.bridges).toBe(s.bridges)
expect(out.ropes).toBe(s.ropes)
}
same({ op: 'edge-remove', kind: 'bridge', id: 'q' }) // an edge we do not have
same({ op: 'edge-upsert', kind: 'bridge', edge: e('x') }) // one we already hold, unchanged
same({ op: 'remove', id: 'x' }) // a NODE op
})
it('leaves the list it does not touch by reference', () => {
const s = { bridges: [e('x')], ropes: [e('r')] }
const out = applyEdgeMutationToScene(s, { op: 'edge-upsert', kind: 'bridge', edge: e('y') })
expect(out.bridges.map((b) => b.id)).toEqual(['x', 'y'])
expect(out.ropes).toBe(s.ropes)
})
})
describe('applyCanvasMutation with an edge mutation', () => {
it('is a no-op that keeps the array identity (the caller short-circuit still fires)', () => {
const nodes = [n('1')]
expect(applyCanvasMutation(nodes, { op: 'edge-remove', kind: 'bridge', id: 'x' })).toBe(nodes)
expect(applyCanvasMutation(nodes, { op: 'edge-upsert', kind: 'rope', edge: e('x') })).toBe(nodes)
})
})
describe('isCanvasMutation — edge ops', () => {
it('accepts well-formed edge mutations', () => {
expect(isCanvasMutation({ op: 'edge-upsert', kind: 'bridge', edge: e('x') })).toBe(true)
expect(isCanvasMutation({ op: 'edge-remove', kind: 'rope', id: 'x' })).toBe(true)
})
it('rejects an unknown kind — the kind picks which persisted list is written', () => {
expect(isCanvasMutation({ op: 'edge-upsert', kind: 'bridges', edge: e('x') })).toBe(false)
expect(isCanvasMutation({ op: 'edge-remove', id: 'x' })).toBe(false)
})
it('rejects a malformed or over-long endpoint — an edge id is an ADDRESS, never truncated', () => {
expect(isCanvasMutation({ op: 'edge-upsert', kind: 'bridge', edge: { id: 'x', source: 'a' } })).toBe(
false
)
expect(isCanvasMutation({ op: 'edge-upsert', kind: 'bridge', edge: e('x', '', 'b') })).toBe(false)
expect(
isCanvasMutation({ op: 'edge-upsert', kind: 'bridge', edge: e('x', 'a'.repeat(129), 'b') })
).toBe(false)
expect(isCanvasMutation({ op: 'edge-upsert', kind: 'bridge' })).toBe(false)
})
// One case per check, each breaking exactly ONE field of an otherwise valid op, so every check is
// pinned on its own (a test that breaks two fields at once still passes with either check gone).
describe('one check per field', () => {
const ok = { op: 'edge-upsert', kind: 'rope', edge: e('x', 'a', 'b') }
const okRemove = { op: 'edge-remove', kind: 'bridge', id: 'x' }
const long = 'z'.repeat(129)
it('the valid baselines pass', () => {
expect(isCanvasMutation(ok)).toBe(true)
expect(isCanvasMutation(okRemove)).toBe(true)
})
it('edge-upsert: kind must be bridge or rope', () => {
expect(isCanvasMutation({ ...ok, kind: 'link' })).toBe(false)
})
it('edge-remove: kind must be bridge or rope', () => {
expect(isCanvasMutation({ ...okRemove, kind: 'Rope' })).toBe(false)
})
it('edge-upsert: edge.id must be a ref id', () => {
expect(isCanvasMutation({ ...ok, edge: e('', 'a', 'b') })).toBe(false)
expect(isCanvasMutation({ ...ok, edge: e(long, 'a', 'b') })).toBe(false)
})
it('edge-upsert: edge.source must be a ref id', () => {
expect(isCanvasMutation({ ...ok, edge: { id: 'x', source: 7, target: 'b' } })).toBe(false)
})
it('edge-upsert: edge.target must be a ref id', () => {
expect(isCanvasMutation({ ...ok, edge: e('x', 'a', '') })).toBe(false)
expect(isCanvasMutation({ ...ok, edge: e('x', 'a', long) })).toBe(false)
})
it('edge-remove: id must be a ref id', () => {
expect(isCanvasMutation({ ...okRemove, id: '' })).toBe(false)
expect(isCanvasMutation({ ...okRemove, id: long })).toBe(false)
expect(isCanvasMutation({ ...okRemove, id: 3 })).toBe(false)
})
it('edge-upsert: edge must be an object', () => {
expect(isCanvasMutation({ ...ok, edge: 'x' })).toBe(false)
})
})
})
describe('isWellFormedMutation — the reducer guard', () => {
it('is isCanvasMutation without the wire byte cap', () => {
const big = { op: 'upsert', node: { ...n('big'), text: 'x'.repeat(MUTATION_MAX_BYTES) } }
expect(isCanvasMutation(big)).toBe(false)
expect(isWellFormedMutation(big)).toBe(true)
const cases: unknown[] = [
null,
{ op: 'remove', id: 'a' },
{ op: 'remove', id: '' },
{ op: 'upsert', node: n('a') },
{ op: 'upsert', node: { id: 'a', position: { x: Number.NaN, y: 0 } } },
{ op: 'edge-upsert', kind: 'rope', edge: e('x') },
{ op: 'edge-upsert', kind: 'ropes', edge: e('x') },
{ op: 'edge-remove', kind: 'bridge', id: 'x' },
{ op: 'kb-card', assignment: { nodeId: 'a', columnId: 'k' } },
{ op: 'kb-card', assignment: { nodeId: '', columnId: 'k' } }
]
for (const c of cases) expect(isWellFormedMutation(c), JSON.stringify(c)).toBe(isCanvasMutation(c))
})
})
describe('diffToMutations — scenes', () => {
const scene = (
nodes: CanvasNodeState[],
bridges: BridgeLink[] = [],
ropes: BridgeLink[] = []
) => ({ nodes, bridges, ropes })
it('reads a bare node array as a scene with no edges (every pre-edge caller is unchanged)', () => {
expect(diffToMutations([n('1')], [n('1')])).toEqual([])
expect(diffToMutations([], [n('1')])).toEqual([{ op: 'upsert', node: n('1') }])
})
it('emits an edge-upsert for a drawn edge and an edge-remove for a deleted one', () => {
expect(diffToMutations(scene([]), scene([], [e('x')]))).toEqual([
{ op: 'edge-upsert', kind: 'bridge', edge: e('x') }
])
expect(diffToMutations(scene([], [e('x')]), scene([]))).toEqual([
{ op: 'edge-remove', kind: 'bridge', id: 'x' }
])
})
it('tags each list with its own kind', () => {
expect(diffToMutations(scene([]), scene([], [], [e('r')]))).toEqual([
{ op: 'edge-upsert', kind: 'rope', edge: e('r') }
])
})
it('emits nothing when only the decoration would have differed (three ids are the value)', () => {
const before = scene([], [e('x')])
const after = scene([], [{ ...e('x') }])
expect(diffToMutations(before, after)).toEqual([])
})
it('re-emits an edge whose endpoint was re-pointed', () => {
expect(diffToMutations(scene([], [e('x', 'a', 'b')]), scene([], [e('x', 'a', 'c')]))).toEqual([
{ op: 'edge-upsert', kind: 'bridge', edge: e('x', 'a', 'c') }
])
})
// One id is one edge (see applyEdgeMutationToScene): an id that moves from one list to the other
// is still on the canvas, so it is an upsert of its new kind and NOT also a remove of its old one.
// A receiver applies the batch in order, and a trailing `edge-remove` would delete it from both.
it('an edge moving between the lists casts its upsert and no remove', () => {
expect(diffToMutations(scene([], [e('x')]), scene([], [], [e('x')]))).toEqual([
{ op: 'edge-upsert', kind: 'rope', edge: e('x') }
])
})
// A peer applies these ONE AT A TIME, so the batch order decides whether an edge ever lands: an
// edge-upsert naming a node that has not arrived yet draws into nothing, and an edge-remove for an
// edge whose node dies in the same batch has to land while the edge is still there.
it('orders the batch: node adds → edge adds → edge removes → node removes', () => {
const before = scene([n('old')], [e('gone', 'old', 'old')])
const after = scene([n('new')], [e('fresh', 'new', 'new')])
expect(diffToMutations(before, after).map((m) => m.op)).toEqual([
'upsert',
'edge-upsert',
'edge-remove',
'remove'
])
})
})
// Kanban ops ride canvas:mut too (@shared/kanban-ops). The guard is `sanitizeKanbanOp`'s verdict —
// one set of shape rules, not a second copy here — plus the same byte cap every mutation has.
describe('isCanvasMutation — kanban ops', () => {
it('accepts a well-formed kanban op of every kind', () => {
const ok: unknown[] = [
{ op: 'kb-column', column: { id: 'c1', title: 'To Do', color: '#fff' } },
{ op: 'kb-column-remove', id: 'c1' },
{ op: 'kb-column-order', ids: ['c1', 'c2'] },
{ op: 'kb-card', assignment: { nodeId: 'n1', columnId: 'c1' } },
{ op: 'kb-card-remove', nodeId: 'n1' },
{ op: 'kb-meta', meta: { nodeId: 'n1', priority: 'high' } },
{ op: 'kb-meta-remove', nodeId: 'n1' },
{ op: 'kb-label', label: { id: 'l1', name: 'Bug', color: 'red' } },
{ op: 'kb-label-remove', id: 'l1' },
{ op: 'kb-label-order', ids: ['l1'] },
{ op: 'kb-view', view: { id: 'v1', name: 'Mine', query: {} } },
{ op: 'kb-view-remove', id: 'v1' }
]
for (const m of ok) expect(isCanvasMutation(m), JSON.stringify(m)).toBe(true)
})
it('refuses what sanitizeKanbanOp refuses — an unknown kb- op, a bad id, a name empty once repaired', () => {
expect(isCanvasMutation({ op: 'kb-nope' })).toBe(false)
expect(isCanvasMutation({ op: 'kb-card-remove', nodeId: '' })).toBe(false)
expect(isCanvasMutation({ op: 'kb-column-remove', id: 'x'.repeat(129) })).toBe(false)
expect(isCanvasMutation({ op: 'kb-label', label: { id: 'l1', name: ' \u0007\u202e ', color: 'red' } })).toBe(false)
})
it('accepts a repairable op (the repair is sanitizeCanvasMutation\'s job, not a refusal)', () => {
expect(isCanvasMutation({ op: 'kb-label', label: { id: 'l1', name: 'Bug', color: 'neon' } })).toBe(true)
// ruling R5: a control character in a NAME is stripped, never a refusal (an id's still is)
expect(isCanvasMutation({ op: 'kb-label', label: { id: 'l1', name: 'a\u0007b', color: 'red' } })).toBe(true)
})
it('bounds a kanban op by the same byte cap', () => {
const big = { op: 'kb-card', assignment: { nodeId: 'n1', columnId: 'c1' }, pad: 'x'.repeat(MUTATION_MAX_BYTES) }
expect(isCanvasMutation(big)).toBe(false)
})
})
describe('sanitizeCanvasMutation', () => {
it('repairs a kanban op and keeps its stamp fields', () => {
const raw = { op: 'kb-label', label: { id: 'l1', name: ' Bug ', color: 'neon', junk: 1 }, src: 'cv-a', seq: 4, seen: 3 } as unknown as CanvasMutation
expect(sanitizeCanvasMutation(raw)).toEqual({
op: 'kb-label',
label: { id: 'l1', name: 'Bug', color: 'default' },
src: 'cv-a',
seq: 4,
seen: 3
})
})
it('refuses (null) a kanban op sanitizeKanbanOp refuses', () => {
expect(sanitizeCanvasMutation({ op: 'kb-card-remove', nodeId: '' })).toBeNull()
})
it('strips the exec-enabling fields off a node upsert', () => {
const withShell = { op: 'upsert', node: { ...n('1'), shell: '/bin/evil' } } as CanvasMutation
const out = sanitizeCanvasMutation(withShell) as Extract<CanvasMutation, { op: 'upsert' }>
expect(out.node.shell).toBeUndefined()
})
// D1: every field of a cast is forwarded to every client, so a remove or an edge op is rebuilt
// from the fields its op defines — plus the stamp fields the order judges — and nothing else.
it('rebuilds remove / edge-remove / edge-upsert from their known fields, keeping src / seq / seen', () => {
const pad = 'x'.repeat(10_000)
const stamp = { src: 'cv-a', seq: 7, seen: 6 }
const rm = { op: 'remove', id: '1', pad, ...stamp } as unknown as CanvasMutation
expect(sanitizeCanvasMutation(rm)).toEqual({ op: 'remove', id: '1', ...stamp })
const er = { op: 'edge-remove', kind: 'rope', id: 'e1', pad, ...stamp } as unknown as CanvasMutation
expect(sanitizeCanvasMutation(er)).toEqual({ op: 'edge-remove', kind: 'rope', id: 'e1', ...stamp })
const eu = {
op: 'edge-upsert',
kind: 'bridge',
edge: { id: 'e1', source: 'a', target: 'b', pad },
pad,
...stamp
} as unknown as CanvasMutation
expect(sanitizeCanvasMutation(eu)).toEqual({
op: 'edge-upsert',
kind: 'bridge',
edge: { id: 'e1', source: 'a', target: 'b' },
...stamp
})
// An absent stamp stays absent (no `src: undefined` key goes on the wire).
expect(Object.keys(sanitizeCanvasMutation({ op: 'remove', id: '1' })!)).toEqual(['op', 'id'])
})
})
describe('isCanvasMutation — the byte cap covers removes too (D1)', () => {
it('refuses an oversized remove and edge-remove, like every other op', () => {
const pad = 'x'.repeat(MUTATION_MAX_BYTES)
expect(isCanvasMutation({ op: 'remove', id: '1', pad })).toBe(false)
expect(isCanvasMutation({ op: 'edge-remove', kind: 'rope', id: 'e1', pad })).toBe(false)
// The shape verdict alone (the reducer's guard) still accepts them.
expect(isWellFormedMutation({ op: 'remove', id: '1', pad })).toBe(true)
})
})
describe('applyCanvasMutation with a kanban op', () => {
it('leaves the node list untouched, by reference (a kanban op addresses the board, not a node)', () => {
const a = [n('1')]
expect(applyCanvasMutation(a, { op: 'kb-card', assignment: { nodeId: '1', columnId: 'c' } })).toBe(a)
expect(applyCanvasMutation(a, { op: 'kb-card-remove', nodeId: '1' })).toBe(a)
})
})
describe('applyCanvasMutation — parent-first order (the downgrade contract)', () => {
const g = (id: string, parentId?: string): CanvasNodeState =>
({ ...n(id), kind: 'group', ...(parentId ? { parentId } : {}) }) as CanvasNodeState
const child = (id: string, parentId: string, x = 0): CanvasNodeState => ({ ...n(id, x), parentId })
const ids = (nodes: CanvasNodeState[]): string[] => nodes.map((x) => x.id)
it('re-sorts when an upsert appends a frame', () => {
const out = applyCanvasMutation([n('a'), n('b')], { op: 'upsert', node: g('G') })
expect(ids(out)).toEqual(['G', 'a', 'b'])
})
it('re-sorts when an upsert changes a node\'s parentId', () => {
// O arrived before this re-sort rule existed, after its future child.
const out = applyCanvasMutation([g('I'), child('x', 'I'), g('O')], { op: 'upsert', node: g('I', 'O') })
expect(ids(out)).toEqual(['O', 'I', 'x'])
})
it('keeps the order, and every untouched entry, when an upsert neither appends nor reparents', () => {
const before = [child('a', 'G'), g('G'), n('b')]
const out = applyCanvasMutation(before, { op: 'upsert', node: child('a', 'G', 9) })
expect(ids(out)).toEqual(['a', 'G', 'b'])
expect(out[1]).toBe(before[1])
expect(out[2]).toBe(before[2])
})
it('an appended leaf with no frame in the list keeps plain append order', () => {
expect(ids(applyCanvasMutation([n('b'), n('a')], { op: 'upsert', node: n('c') }))).toEqual(['b', 'a', 'c'])
})
})
// Issue #852: a context link's one-way `reader` is part of the edge on the wire. Every hop of team
// sync (diff → shape gate → reflector sanitize → peer apply) used to carry only the three ids, so a
// direction flip was never cast, and a freshly cast one-way link landed on the peer as both-read —
// which the peer then saved and published back, widening who may read on every canvas.
describe('one-way context links (#852) through team sync', () => {
const oneWay = (reader: string): BridgeLink => ({ id: 'x', source: 'a', target: 'b', reader })
const scene = (bridges: BridgeLink[]) => ({ nodes: [], bridges, ropes: [] })
it('a direction flip diffs to an edge-upsert carrying the reader', () => {
expect(diffToMutations(scene([e('x')]), scene([oneWay('a')]))).toEqual([
{ op: 'edge-upsert', kind: 'bridge', edge: oneWay('a') }
])
expect(diffToMutations(scene([oneWay('a')]), scene([e('x')]))).toEqual([
{ op: 'edge-upsert', kind: 'bridge', edge: e('x') }
])
expect(diffToMutations(scene([oneWay('a')]), scene([oneWay('a')]))).toEqual([])
})
it('flip → cast → reflect → peer apply leaves the peer one-way, not both-read', () => {
const peer = [e('x')]
const [cast] = diffToMutations(scene([e('x')]), scene([oneWay('b')]))
expect(isCanvasMutation(cast)).toBe(true)
const clean = sanitizeCanvasMutation(cast as CanvasMutation)!
const out = applyEdgeMutation(peer, 'bridge', clean)
expect(out).not.toBe(peer)
expect(out).toEqual([oneWay('b')])
// …and back to both-read clears it on the peer.
const back = sanitizeCanvasMutation({ op: 'edge-upsert', kind: 'bridge', edge: e('x') })!
expect(applyEdgeMutation(out, 'bridge', back)).toEqual([e('x')])
})
it('a held one-way bridge re-cast unchanged keeps identity', () => {
const list = [oneWay('a')]
expect(applyEdgeMutation(list, 'bridge', { op: 'edge-upsert', kind: 'bridge', edge: oneWay('a') })).toBe(list)
})
it('refuses a malformed reader rather than dropping it (dropping would widen the link)', () => {
const bad = (reader: unknown) =>
isCanvasMutation({ op: 'edge-upsert', kind: 'bridge', edge: { ...e('x'), reader } })
expect(bad('a')).toBe(true)
expect(bad(7)).toBe(false)
expect(bad('')).toBe(false)
expect(bad('r'.repeat(129))).toBe(false)
// A rope has no direction.
expect(isCanvasMutation({ op: 'edge-upsert', kind: 'rope', edge: oneWay('a') })).toBe(false)
})
it('never lets a reader onto a rope, even past the gate', () => {
const [out] = applyEdgeMutation([], 'rope', { op: 'edge-upsert', kind: 'rope', edge: oneWay('a') })
expect(out).toEqual(e('x'))
})
})