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, beforeEach, afterEach, vi } from 'vitest'
import { initPlatform, resetPlatformForTests } from '../platform'
import { fakePlatform, type FakePlatform } from '../platform-fake'
import {
PresenceHub,
allocateRelayClientId,
PRESENCE_RATE_BUDGETS,
TYPING_THROTTLE_MS
} from './hub'
import { IPC } from '../../shared/ipc'
import {
PRESENCE_COLORS,
REF_MAX_LEN,
DINO_MAX_OBSTACLES,
type DinoSnapshot,
type PeerDiff,
type PeerState
} from '../../shared/presence'
let fake: FakePlatform
beforeEach(() => {
fake = fakePlatform()
initPlatform(fake)
})
afterEach(() => {
resetPlatformForTests()
vi.useRealTimers()
})
/** Every `presence:peer` diff broadcast so far, in order. */
function diffs(): PeerDiff[] {
return fake.sent
.filter((s) => s.to === 'broadcast' && s.channel === IPC.presencePeer)
.map((s) => s.args[0] as PeerDiff)
}
describe('PresenceHub join/leave', () => {
it('join creates a peer with a default name + next-free color, snapshots the newcomer, and broadcasts', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.join(2, 'phone')
expect(hub.peers()).toEqual([
{
clientId: 1,
name: 'Someone',
color: PRESENCE_COLORS[0],
cursor: null,
focus: null,
chat: null,
typing: null,
projectId: null,
dino: null,
kind: 'browser'
},
{
clientId: 2,
name: 'Phone',
color: PRESENCE_COLORS[1],
cursor: null,
focus: null,
chat: null,
typing: null,
projectId: null,
dino: null,
kind: 'phone'
}
])
// The newcomer gets the full table (it may never be able to make a request — see the phone).
const syncs = fake.sent.filter((s) => s.channel === IPC.presenceSync)
expect(syncs.map((s) => s.to)).toEqual([1, 2])
expect((syncs[1].args[0] as PeerState[]).map((p) => p.clientId)).toEqual([1, 2])
expect(diffs()).toEqual([
{ op: 'join', peer: hub.peers()[0] },
{ op: 'join', peer: hub.peers()[1] }
])
})
it('a phone is a first-class cursorless peer (no fabricated position)', () => {
const hub = new PresenceHub()
hub.join(9, 'phone')
expect(hub.peers()[0].cursor).toBeNull()
expect(hub.peers()[0].kind).toBe('phone')
})
it('join is idempotent, and leave drops the peer + broadcasts', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.join(1, 'browser')
expect(hub.peers()).toHaveLength(1)
hub.leave(1)
expect(hub.peers()).toEqual([])
expect(diffs().at(-1)).toEqual({ op: 'leave', clientId: 1 })
// Leaving twice is a silent no-op (no second diff).
const before = diffs().length
hub.leave(1)
expect(diffs()).toHaveLength(before)
})
it('a departing peer frees its color for the next joiner', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.leave(1)
hub.join(2, 'browser')
expect(hub.peers()[0].color).toBe(PRESENCE_COLORS[0])
})
})
describe('PresenceHub hello', () => {
it('returns the caller its own id + the full table, and broadcasts the identity update', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.join(2, 'browser')
const res = hub.hello(2, { name: ' Enes ', color: PRESENCE_COLORS[3] })
expect(res.clientId).toBe(2)
expect(res.peers.map((p) => p.clientId)).toEqual([1, 2])
expect(hub.peers()[1]).toMatchObject({ name: 'Enes', color: PRESENCE_COLORS[3] })
expect(diffs().at(-1)).toEqual({
op: 'update',
clientId: 2,
patch: { name: 'Enes', color: PRESENCE_COLORS[3] }
})
})
it('sanitizes junk (off-palette color / empty name) and ignores an unknown client', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.hello(1, { name: '', color: 'url(evil)' } as never)
expect(hub.peers()[0]).toMatchObject({ name: 'Someone', color: PRESENCE_COLORS[0] })
// A hello from a client that never joined must not create a ghost peer.
const res = hub.hello(99, { name: 'Ghost', color: PRESENCE_COLORS[1] })
expect(res).toEqual({ clientId: 99, peers: hub.peers() })
expect(hub.peers()).toHaveLength(1)
})
// A reconnecting client re-sends its stored identity; that must not fan an identical diff out
// to every peer. But it must STILL get its own clientId back — that return is how the renderer
// learns which cursor is its own.
it('an unchanged identity broadcasts nothing but still returns {clientId, peers}', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.join(2, 'browser')
hub.hello(2, { name: 'Enes', color: PRESENCE_COLORS[3] })
const after = diffs().length
const res = hub.hello(2, { name: 'Enes', color: PRESENCE_COLORS[3] })
expect(diffs()).toHaveLength(after) // no change → no diff
expect(res.clientId).toBe(2)
expect(res.peers.map((p) => p.clientId)).toEqual([1, 2])
// A real change still broadcasts.
hub.hello(2, { name: 'Enes', color: PRESENCE_COLORS[4] })
expect(diffs().at(-1)).toEqual({
op: 'update',
clientId: 2,
patch: { name: 'Enes', color: PRESENCE_COLORS[4] }
})
})
})
describe('PresenceHub signals', () => {
it('setCursor / setFocus / setChat / setProject patch the peer and broadcast an update diff', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
// The project comes FIRST, as it does in the app (Canvas reports the canvas it loaded, then
// the pointer starts moving on it) — a later setProject would drop the cursor with the old
// canvas it belongs to (see the project-switch test below).
hub.setProject(1, 'web')
hub.setCursor(1, { x: 12.4, y: -3 })
hub.setFocus(1, 'node-a')
hub.setChat(1, 'hey')
expect(hub.peers()[0]).toMatchObject({
cursor: { x: 12.4, y: -3 },
focus: 'node-a',
chat: 'hey',
projectId: 'web'
})
expect(diffs().slice(-4)).toEqual([
{ op: 'update', clientId: 1, patch: { projectId: 'web' } },
{ op: 'update', clientId: 1, patch: { cursor: { x: 12.4, y: -3 } } },
{ op: 'update', clientId: 1, patch: { focus: 'node-a' } },
{ op: 'update', clientId: 1, patch: { chat: 'hey' } }
])
hub.setCursor(1, null)
hub.setChat(1, null)
expect(hub.peers()[0]).toMatchObject({ cursor: null, chat: null })
})
it('setProject: switching canvases re-broadcasts, the same project is a silent no-op, and a peer with no project open goes back to null', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setProject(1, 'web')
const after = diffs().length
hub.setProject(1, 'web') // no change → no diff (a tab switch back must not spam the wire)
expect(diffs()).toHaveLength(after)
hub.setProject(1, 'api')
expect(diffs().at(-1)).toEqual({ op: 'update', clientId: 1, patch: { projectId: 'api' } })
hub.setProject(1, null) // closed the last project → welcome screen
expect(hub.peers()[0].projectId).toBeNull()
// Unknown client: silent no-op, no ghost peer.
hub.setProject(42, 'web')
expect(hub.peers()).toHaveLength(1)
})
// A project switch can be keyboard-driven (⌘1/⌘2, the palette) with the mouse parked, so no
// pointermove follows it and the renderer's sampler never sends a new position. Leaving the old
// cursor in the table would draw this peer on the NEW canvas at the OLD canvas's flow
// coordinates — a ghost pointing at nothing, indefinitely, for everyone on that project.
it('setProject drops the cursor with the old canvas (one coherent diff carries both)', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setProject(1, 'web')
hub.setCursor(1, { x: 400, y: 250 })
hub.setProject(1, 'api')
expect(hub.peers()[0]).toMatchObject({ projectId: 'api', cursor: null })
// ONE diff, carrying both changes: a peer applying it can never see the new project with the
// stale cursor, in either order.
expect(diffs().at(-1)).toEqual({
op: 'update',
clientId: 1,
patch: { projectId: 'api', cursor: null }
})
// Nothing to drop → the patch stays minimal (no redundant cursor: null on every switch).
hub.setProject(1, 'web')
expect(diffs().at(-1)).toEqual({ op: 'update', clientId: 1, patch: { projectId: 'web' } })
})
it('drops garbage input instead of broadcasting it (NaN cursor, over-long chat, unknown client)', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
const before = diffs().length
hub.setCursor(1, { x: Number.NaN, y: 0 })
hub.setCursor(2, { x: 1, y: 1 }) // never joined
hub.setFocus(2, 'node-a')
expect(diffs()).toHaveLength(before)
hub.setChat(1, 'y'.repeat(500))
expect(hub.peers()[0].chat).toHaveLength(200)
})
it('caps chat at CHAT_MAX_LEN *code points*, so an emoji is never cut into a lone surrogate', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
// 300 astral code points (600 UTF-16 units): a naive slice() would cut one in half.
hub.setChat(1, '🙂'.repeat(300))
const chat = hub.peers()[0].chat as string
expect([...chat]).toHaveLength(200)
expect(chat).toBe('🙂'.repeat(200))
// The cap is enforced at ingest, so the broadcast diff carries the capped text too.
expect(diffs().at(-1)).toEqual({ op: 'update', clientId: 1, patch: { chat } })
})
// The cursor is recomputed (and re-sent) on every pan/zoom frame, and mouse-leave/blur both
// send null. An unchanged value must not fan out to every peer for zero visual change.
it('setCursor: an unchanged position (and a repeated null) is a silent no-op', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setCursor(1, { x: 10, y: 20 })
const after = diffs().length
hub.setCursor(1, { x: 10, y: 20 }) // same position (pan/zoom recompute) → no diff
expect(diffs()).toHaveLength(after)
hub.setCursor(1, { x: 10, y: 21 }) // y moved → broadcast
expect(diffs()).toHaveLength(after + 1)
hub.setCursor(1, { x: 11, y: 21 }) // x moved → broadcast
expect(diffs()).toHaveLength(after + 2)
hub.setCursor(1, null) // mouse leave → broadcast
expect(diffs()).toHaveLength(after + 3)
hub.setCursor(1, null) // blur right after leave → already null → no diff
expect(diffs()).toHaveLength(after + 3)
expect(hub.peers()[0].cursor).toBeNull()
hub.setCursor(1, { x: 11, y: 21 }) // back from null → broadcast
expect(diffs()).toHaveLength(after + 4)
})
// Esc-then-blur closes the bubble twice, and a re-render can re-send identical text.
it('setChat: unchanged text (and a repeated null) is a silent no-op, compared AFTER the cap', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setChat(1, 'hey')
const after = diffs().length
hub.setChat(1, 'hey') // identical → no diff
expect(diffs()).toHaveLength(after)
hub.setChat(1, 'hey!') // changed → broadcast
expect(diffs()).toHaveLength(after + 1)
hub.setChat(1, null) // Esc closes the bubble
expect(diffs()).toHaveLength(after + 2)
hub.setChat(1, null) // blur closes it again → already null → no diff
expect(diffs()).toHaveLength(after + 2)
// Two DIFFERENT over-long strings that cap to the same 200 code points are the same peer
// state — comparing the raw text would leak a broadcast per keystroke past the cap.
hub.setChat(1, 'z'.repeat(500))
const capped = diffs().length
hub.setChat(1, 'z'.repeat(600))
expect(diffs()).toHaveLength(capped)
expect(hub.peers()[0].chat).toBe('z'.repeat(200))
})
it('peers() and the join diff hand out copies, so a caller cannot corrupt hub state', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setCursor(1, { x: 1, y: 2 })
hub.noteTyping(1, 'node-a')
// Nested objects are copies too — mutating them must not reach the hub's table.
const snap = hub.peers()[0]
snap.name = 'hacked'
;(snap.cursor as { x: number; y: number }).x = 999
;(snap.typing as { nodeId: string }).nodeId = 'node-evil'
expect(hub.peers()[0]).toMatchObject({
name: 'Someone',
cursor: { x: 1, y: 2 },
typing: { nodeId: 'node-a' }
})
// The join diff carries a copy, not the live PeerState reference.
hub.join(2, 'browser')
const joined = diffs().at(-1) as { op: 'join'; peer: PeerState }
expect(joined.op).toBe('join')
hub.setFocus(2, 'node-z')
expect(joined.peer.focus).toBeNull() // a live reference would have followed the setter
})
})
describe('PresenceHub dino (live spectator cast)', () => {
function snap(over: Partial<DinoSnapshot> = {}): DinoSnapshot {
return {
y: -12,
ducking: false,
crashed: false,
started: true,
score: 42,
speed: 6,
groundScroll: 100,
obstacles: [{ kind: 'cactus', x: 300, y: 0, sx: 0, sw: 20, sh: 40, flap: 0 }],
...over
}
}
it('a valid dino cast sets the sender dino and broadcasts an update diff carrying { dino }', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
const payload = { nodeId: 'dino-a', snap: snap() }
hub.setDino(1, payload)
expect(hub.peers()[0].dino).toEqual(payload)
expect(diffs().at(-1)).toEqual({ op: 'update', clientId: 1, patch: { dino: payload } })
})
it('clamps obstacles to the first DINO_MAX_OBSTACLES in the table AND the broadcast diff', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
const many = Array.from({ length: DINO_MAX_OBSTACLES + 8 }, (_, i) => ({
kind: 'cactus' as const,
x: i,
y: 0,
sx: 0,
sw: 20,
sh: 40,
flap: 0
}))
hub.setDino(1, { nodeId: 'dino-a', snap: snap({ obstacles: many }) })
expect(hub.peers()[0].dino?.snap.obstacles).toHaveLength(DINO_MAX_OBSTACLES)
// The first N are kept (x: 0..N-1), the tail is dropped.
expect(hub.peers()[0].dino?.snap.obstacles.map((o) => o.x)).toEqual(
Array.from({ length: DINO_MAX_OBSTACLES }, (_, i) => i)
)
const diff = diffs().at(-1) as { patch: { dino: { snap: DinoSnapshot } } }
expect(diff.patch.dino.snap.obstacles).toHaveLength(DINO_MAX_OBSTACLES)
})
it('drops a malformed payload — dino becomes null (never applied garbage)', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setDino(1, { nodeId: 'dino-a', snap: snap() })
expect(hub.peers()[0].dino).not.toBeNull()
// Missing nodeId → the whole cast is invalid → the field clears.
hub.setDino(1, { snap: snap() })
expect(hub.peers()[0].dino).toBeNull()
expect(diffs().at(-1)).toEqual({ op: 'update', clientId: 1, patch: { dino: null } })
// A non-object and a bad-number snap likewise never apply garbage.
hub.setDino(1, { nodeId: 'dino-a', snap: snap() })
hub.setDino(1, 'nope')
expect(hub.peers()[0].dino).toBeNull()
})
it('coerces non-finite snap numbers to 0 and drops a bad-kind obstacle', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setDino(1, {
nodeId: 'dino-a',
snap: {
y: Number.NaN,
ducking: 1,
crashed: false,
started: true,
score: Number.POSITIVE_INFINITY,
speed: 6,
groundScroll: 0,
obstacles: [
{ kind: 'ufo', x: 1, y: 0, sx: 0, sw: 1, sh: 1, flap: 0 },
{ kind: 'bird', x: 2, y: 0, sx: 0, sw: 1, sh: 1, flap: 1 }
]
}
})
const dino = hub.peers()[0].dino
expect(dino?.snap.y).toBe(0)
expect(dino?.snap.score).toBe(0)
expect(dino?.snap.ducking).toBe(true)
// The 'ufo' obstacle is dropped; only the valid 'bird' survives.
expect(dino?.snap.obstacles).toEqual([{ kind: 'bird', x: 2, y: 0, sx: 0, sw: 1, sh: 1, flap: 1 }])
})
it('leave drops the peer and its dino from the table', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setDino(1, { nodeId: 'dino-a', snap: snap() })
hub.leave(1)
expect(hub.peers()).toEqual([])
})
it('a repeated stop (null → null) is a silent no-op, and an unknown client is ignored', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setDino(1, null)
const after = diffs().length // never played → still null → nothing broadcast
expect(diffs()).toHaveLength(after)
hub.setDino(1, { nodeId: 'dino-a', snap: snap() })
hub.setDino(1, null) // real stop → broadcasts once
expect(diffs().at(-1)).toEqual({ op: 'update', clientId: 1, patch: { dino: null } })
const stopped = diffs().length
hub.setDino(1, null) // repeat stop → no-op
expect(diffs()).toHaveLength(stopped)
hub.setDino(42, { nodeId: 'x', snap: snap() }) // never joined → no ghost peer
expect(hub.peers()).toHaveLength(1)
})
it('the cast entry point is rate-limited, and a stop is an exempt clear (drains no token)', () => {
vi.useFakeTimers()
vi.setSystemTime(0)
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
const budget = PRESENCE_RATE_BUDGETS[IPC.presenceDino]
const before = diffs().length
for (let i = 0; i < 1000; i++) {
fake.senderListeners[IPC.presenceDino](1, { nodeId: 'dino-a', snap: snap({ score: i }) })
}
expect(diffs().length - before).toBe(budget.burst) // the bucket, not one cast more
// A MALFORMED non-null cast is NOT an exempt stop — it spends a token like any snapshot, so a
// garbage flood is bounded by the same bucket (which is now drained → this drops, no diff).
const afterFlood = diffs().length
for (let i = 0; i < 50; i++) fake.senderListeners[IPC.presenceDino](1, { garbage: i })
expect(diffs().length).toBe(afterFlood) // all dropped by the rate limiter, not exempted
// A genuine stop (null) is an edge (a dropped one leaves a frozen ghost) → exempt, lands even
// when the bucket is drained.
fake.senderListeners[IPC.presenceDino](1, null)
expect(hub.peers()[0].dino).toBeNull()
expect(diffs().at(-1)).toEqual({ op: 'update', clientId: 1, patch: { dino: null } })
})
})
describe('PresenceHub noteTyping (Stage 2 caller; wired here)', () => {
it('throttles to one broadcast per node per 500ms and re-fires for a different node', () => {
vi.useFakeTimers()
vi.setSystemTime(1_000_000)
const hub = new PresenceHub()
hub.join(1, 'browser')
const before = diffs().length
hub.noteTyping(1, 'node-a')
hub.noteTyping(1, 'node-a') // inside the throttle window → swallowed
expect(diffs()).toHaveLength(before + 1)
expect(hub.peers()[0].typing).toEqual({ nodeId: 'node-a', at: 1_000_000 })
// A different node always re-fires (it's a different badge).
hub.noteTyping(1, 'node-b')
expect(diffs()).toHaveLength(before + 2)
vi.setSystemTime(1_000_000 + TYPING_THROTTLE_MS + 1)
hub.noteTyping(1, 'node-a')
expect(diffs()).toHaveLength(before + 3)
})
// The throttle key is (client, node) ALONE. A throttle that also required the peer's *current*
// typing badge to be on the same node would be defeated by a client writing alternately into
// two nodes (split terminal, agent + shell): every call would see a different last node and
// broadcast, at keystroke rate, to every peer.
it('throttles per (client, node) even when the client alternates between two nodes', () => {
vi.useFakeTimers()
vi.setSystemTime(2_000_000)
const hub = new PresenceHub()
hub.join(1, 'browser')
const before = diffs().length
// 20 interleaved keystrokes inside one throttle window → one broadcast per node, not 20.
for (let i = 0; i < 10; i++) {
hub.noteTyping(1, 'node-a')
hub.noteTyping(1, 'node-b')
}
expect(diffs()).toHaveLength(before + 2)
// Each node's window is its own: node-a's expires, node-b's has not.
vi.setSystemTime(2_000_000 + TYPING_THROTTLE_MS + 1)
hub.noteTyping(1, 'node-a')
expect(diffs()).toHaveLength(before + 3)
hub.noteTyping(1, 'node-b')
expect(diffs()).toHaveLength(before + 4) // node-b's window opened at the same time → also due
})
// Two clients typing in the same node must not throttle each other (the key carries the client).
it('throttles per client, not globally per node', () => {
vi.useFakeTimers()
vi.setSystemTime(3_000_000)
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.join(2, 'browser')
const before = diffs().length
hub.noteTyping(1, 'node-a')
hub.noteTyping(2, 'node-a')
expect(diffs()).toHaveLength(before + 2)
})
})
describe('caps on client-supplied ids (focus / project)', () => {
// Focus and project ids come straight off the wire and are stored verbatim in the peer table and
// reflected to EVERY peer. Uncapped, a 10 MB `presence:focus` becomes 10 MB x N peers of egress
// down the very sink pty output rides — terminals would stall behind a hostile string.
it('caps focus and project at REF_MAX_LEN code points, in the table AND in the broadcast diff', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setFocus(1, 'n'.repeat(REF_MAX_LEN + 5_000))
expect(hub.peers()[0].focus).toBe('n'.repeat(REF_MAX_LEN))
expect(diffs().at(-1)).toEqual({
op: 'update',
clientId: 1,
patch: { focus: 'n'.repeat(REF_MAX_LEN) }
})
hub.setProject(1, 'p'.repeat(REF_MAX_LEN + 5_000))
expect(hub.peers()[0].projectId).toBe('p'.repeat(REF_MAX_LEN))
expect(diffs().at(-1)).toMatchObject({
op: 'update',
clientId: 1,
patch: { projectId: 'p'.repeat(REF_MAX_LEN) }
})
})
// The typing badge's nodeId is reflected exactly like focus — and it is just as client-supplied:
// it is the session's persistKey, which the client chose at `pty:create`. Uncapped, a scripted
// client could open a session under a multi-KB node id and have the hub re-broadcast that string
// to every peer twice a second, for as long as it holds a key down.
it('caps the typing nodeId at REF_MAX_LEN code points, in the table AND in the broadcast diff', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.noteTyping(1, 'x'.repeat(REF_MAX_LEN + 5_000))
expect(hub.peers()[0].typing?.nodeId).toBe('x'.repeat(REF_MAX_LEN))
expect(diffs().at(-1)).toMatchObject({
op: 'update',
clientId: 1,
patch: { typing: { nodeId: 'x'.repeat(REF_MAX_LEN) } }
})
})
it('caps by code point (the shared truncation rule), never splitting an emoji', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setFocus(1, '🙂'.repeat(REF_MAX_LEN + 100))
const focus = hub.peers()[0].focus as string
expect([...focus]).toHaveLength(REF_MAX_LEN)
expect(focus).not.toMatch(/[\uD800-\uDFFF]/u)
})
// Real ids are short (`term-ab12`, `web-3f9c`), so the cap can never truncate a legitimate one.
it('leaves a real node/project id untouched', () => {
const hub = new PresenceHub()
hub.join(1, 'browser')
hub.setFocus(1, 'term-ab12cd')
hub.setProject(1, 'proj-9f3a-2')
expect(hub.peers()[0]).toMatchObject({ focus: 'term-ab12cd', projectId: 'proj-9f3a-2' })
})
})
describe('rate limiting (a hostile tab must not degrade the room)', () => {
beforeEach(() => {
vi.useFakeTimers()
vi.setSystemTime(0)
})
/** Fire `n` cursor casts through the CAST entry point (where the limiter lives), each with a
* distinct position so the unchanged-value no-op can never be mistaken for a rate-limit drop. */
function floodCursor(clientId: number, n: number, from = 0): void {
for (let i = 0; i < n; i++) {
fake.senderListeners[IPC.presenceCursor](clientId, { x: from + i, y: 0 })
}
}
it('drops cursor casts past the burst budget, and refills at the sustained rate', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
const budget = PRESENCE_RATE_BUDGETS[IPC.presenceCursor]
const before = diffs().length
floodCursor(1, 1000) // a tight loop, all in the same millisecond
const passed = diffs().length - before
expect(passed).toBe(budget.burst) // the bucket, and not one cast more
// No time passed → still nothing gets through.
floodCursor(1, 100, 10_000)
expect(diffs().length - before).toBe(budget.burst)
// One second later the bucket has refilled by exactly the sustained rate.
vi.setSystemTime(1000)
floodCursor(1, 1000, 20_000)
expect(diffs().length - before).toBe(budget.burst + budget.perSec)
})
it('never drops an honest client: the renderer 20 Hz cursor stream passes in full', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
const before = diffs().length
// 10 s of the renderer's own throttle (CURSOR_MIN_INTERVAL_MS = 50 → 20 Hz). The cursor budget
// is matched to it, so a well-behaved tab must never lose a sample.
for (let i = 0; i < 200; i++) {
vi.setSystemTime(i * 50)
fake.senderListeners[IPC.presenceCursor](1, { x: i, y: i })
}
expect(diffs().length - before).toBe(200)
})
it('the limit is per (client, channel): a flooding tab starves neither its peers nor its own other channels', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
hub.join(2, 'browser')
floodCursor(1, 1000) // client 1 exhausts its cursor bucket
const after = diffs().length
// Client 2's cursor is untouched…
fake.senderListeners[IPC.presenceCursor](2, { x: 1, y: 1 })
expect(diffs().at(-1)).toEqual({ op: 'update', clientId: 2, patch: { cursor: { x: 1, y: 1 } } })
// …and so is client 1's focus (a separate channel keeps a separate bucket).
fake.senderListeners[IPC.presenceFocus](1, 'node-a')
expect(diffs().at(-1)).toEqual({ op: 'update', clientId: 1, patch: { focus: 'node-a' } })
expect(diffs().length).toBe(after + 2)
})
it('throttles the chat, focus and project channels too', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
for (const [channel, cast] of [
[IPC.presenceChat, (i: number) => fake.senderListeners[IPC.presenceChat](1, `msg ${i}`)],
[IPC.presenceFocus, (i: number) => fake.senderListeners[IPC.presenceFocus](1, `node-${i}`)],
[IPC.presenceProject, (i: number) => fake.senderListeners[IPC.presenceProject](1, `p-${i}`)]
] as Array<[string, (i: number) => void]>) {
const before = diffs().length
for (let i = 0; i < 500; i++) cast(i)
expect(diffs().length - before).toBe(PRESENCE_RATE_BUDGETS[channel].burst)
}
})
it('a dropped cast changes nothing — the peer keeps the last state that got through', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
const budget = PRESENCE_RATE_BUDGETS[IPC.presenceCursor]
floodCursor(1, budget.burst + 50)
// The dropped casts must not be applied to the table either (silently ignored, not queued).
expect(hub.peers()[0].cursor).toEqual({ x: budget.burst - 1, y: 0 })
})
it('leaving frees the client\'s buckets, so a reconnecting id starts fresh', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
const budget = PRESENCE_RATE_BUDGETS[IPC.presenceCursor]
floodCursor(1, 1000)
hub.leave(1)
hub.join(1, 'browser')
const before = diffs().length
floodCursor(1, 1000, 50_000)
expect(diffs().length - before).toBe(budget.burst)
})
})
describe('rate limiting must never drop an EDGE signal (a lost clear is lost state, not a lost frame)', () => {
beforeEach(() => {
vi.useFakeTimers()
vi.setSystemTime(0)
})
/** Drain a channel's bucket at t=0 with casts that carry a value (the flood-capable shape). */
function drain(channel: string, cast: (i: number) => void): void {
for (let i = 0; i < PRESENCE_RATE_BUDGETS[channel].burst + 50; i++) cast(i)
}
// THE STUCK BUBBLE: sendChat fires per keystroke, so a held key (X11 repeats ~25/s, macOS with
// KeyRepeat=0 far faster) drains the chat bucket. On release the renderer retracts with
// chat(null) — and if THAT is dropped, the hub keeps the last accepted line and every peer keeps
// a chat bubble pinned to a cursor forever. The renderer has no ack and no retry: it already
// believes it retracted.
it('a chat retraction lands (and is broadcast) with the chat bucket drained', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
drain(IPC.presenceChat, (i) => fake.senderListeners[IPC.presenceChat](1, `msg ${i}`))
const stuck = hub.peers()[0].chat
expect(stuck).not.toBeNull() // the bubble a peer is currently showing
const before = diffs().length
fake.senderListeners[IPC.presenceChat](1, null) // the retraction — must NOT be droppable
expect(hub.peers()[0].chat).toBeNull()
expect(diffs().slice(before)).toEqual([{ op: 'update', clientId: 1, patch: { chat: null } }])
})
it('a cursor retraction lands with the cursor bucket drained (mouse-leave / blur)', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
drain(IPC.presenceCursor, (i) => fake.senderListeners[IPC.presenceCursor](1, { x: i, y: 0 }))
expect(hub.peers()[0].cursor).not.toBeNull()
const before = diffs().length
fake.senderListeners[IPC.presenceCursor](1, null)
expect(hub.peers()[0].cursor).toBeNull()
expect(diffs().slice(before)).toEqual([{ op: 'update', clientId: 1, patch: { cursor: null } }])
})
it('a focus release lands with the focus bucket drained (else a ghost chip stays on the node)', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
drain(IPC.presenceFocus, (i) => fake.senderListeners[IPC.presenceFocus](1, `node-${i}`))
expect(hub.peers()[0].focus).not.toBeNull()
const before = diffs().length
fake.senderListeners[IPC.presenceFocus](1, null)
expect(hub.peers()[0].focus).toBeNull()
expect(diffs().slice(before)).toEqual([{ op: 'update', clientId: 1, patch: { focus: null } }])
})
// Exempting the clears cannot become a flood vector, and this is WHY: the setters ignore an
// unchanged value, so a clear only broadcasts once — the next one needs an intervening non-null
// cast to re-arm it, and THAT one is bucketed. So the clear's broadcast rate is bounded by the
// (rate-limited) value casts, not by the client's send loop.
it('an exempt clear is self-limiting: a null flood broadcasts at most once', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
fake.senderListeners[IPC.presenceCursor](1, { x: 1, y: 1 })
const before = diffs().length
for (let i = 0; i < 5000; i++) fake.senderListeners[IPC.presenceCursor](1, null)
for (let i = 0; i < 5000; i++) fake.senderListeners[IPC.presenceChat](1, null)
for (let i = 0; i < 5000; i++) fake.senderListeners[IPC.presenceFocus](1, null)
expect(diffs().length - before).toBe(1) // the one cursor clear; chat/focus were already null
})
// THE WRONG PROJECT: presence:project is a state switch, not a sample — nothing supersedes a
// dropped one, and the renderer has already recorded it as sent. A dropped switch leaves the hub
// (and therefore every teammate's canvas, chips and facepile) on the project you LEFT, forever.
// The budget must be far out of reach of any human input path.
it('a project switch survives every rate a human input path can produce', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(1, 'browser')
const budget = PRESENCE_RATE_BUDGETS[IPC.presenceProject]
expect(budget.perSec).toBeGreaterThanOrEqual(20) // > any key-repeat rate (X11 ~25/s is deduped)
expect(budget.burst).toBeGreaterThanOrEqual(60) // ~30 s of frantic ⌘1/⌘2 switching, back to back
// 30 distinct switches inside one second — far past anything a person can click or type — and
// the last one still lands, because the hub must always know which canvas you are on.
for (let i = 0; i < 30; i++) {
vi.setSystemTime(i * 33)
fake.senderListeners[IPC.presenceProject](1, `p-${i}`)
}
expect(hub.peers()[0].projectId).toBe('p-29')
expect(diffs().at(-1)).toMatchObject({ op: 'update', clientId: 1, patch: { projectId: 'p-29' } })
})
})
describe('registerIpc', () => {
it('registers hello as a sender-aware request and the three signals as sender-aware casts', () => {
const hub = new PresenceHub()
hub.registerIpc()
hub.join(4, 'browser')
const res = fake.handlers[IPC.presenceHello](4, { name: 'Ada', color: PRESENCE_COLORS[2] })
expect(res).toMatchObject({ clientId: 4 })
// Project first, cursor after — the app's own order (a cursor only means something once the
// canvas it was sampled on is known; a later switch drops it).
fake.senderListeners[IPC.presenceProject](4, 'web')
fake.senderListeners[IPC.presenceCursor](4, { x: 5, y: 6 })
fake.senderListeners[IPC.presenceFocus](4, 'node-z')
fake.senderListeners[IPC.presenceChat](4, 'yo')
expect(hub.peers()[0]).toMatchObject({
name: 'Ada',
cursor: { x: 5, y: 6 },
focus: 'node-z',
chat: 'yo',
projectId: 'web'
})
})
// The shell's listener registry does NOT dedup identical function references, so a second
// registration would make every cast fire twice. The hub guards against that itself.
it('is idempotent: a second call registers nothing', () => {
const registered: string[] = []
initPlatform(
fakePlatform({
handleWithSender: (ch) => registered.push(ch),
onWithSender: (ch) => registered.push(ch)
})
)
const hub = new PresenceHub()
hub.registerIpc()
expect(registered).toEqual([
IPC.presenceHello,
IPC.presenceCursor,
IPC.presenceFocus,
IPC.presenceChat,
IPC.presenceDino,
IPC.presenceProject
])
hub.registerIpc()
expect(registered).toHaveLength(6)
})
})
describe('shell adapters (desktop window + relay phone)', () => {
it('a desktop window and a relay phone coexist as peers with distinct ids and colors', () => {
const hub = new PresenceHub()
const windowId = 1 // Electron webContents.id
const phoneId = allocateRelayClientId()
hub.join(windowId, 'desktop')
hub.join(phoneId, 'phone')
expect(phoneId).not.toBe(windowId)
const [desk, phone] = hub.peers()
expect(desk).toMatchObject({ kind: 'desktop', name: 'Someone', cursor: null })
expect(phone).toMatchObject({ kind: 'phone', name: 'Phone', cursor: null })
expect(desk.color).not.toBe(phone.color)
// sendTo for a relay peer targets an id no shell can resolve — it must be a silent drop,
// never a throw (Electron's webContents.fromId returns null; ServerPlatform has no sink).
expect(() => hub.setChat(phoneId, 'from the phone')).not.toThrow()
hub.leave(phoneId)
expect(hub.peers().map((p) => p.kind)).toEqual(['desktop'])
})
})
describe('allocateRelayClientId', () => {
it('mints monotonic ids from a range that cannot collide with a UI id', () => {
const a = allocateRelayClientId()
const b = allocateRelayClientId()
expect(a).toBeGreaterThanOrEqual(1_000_000)
expect(b).toBe(a + 1)
})
})