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.

10.7 KB
Raw Blame
import { describe, it, expect } from 'vitest'
import { readFileSync } from 'node:fs'

/**
 * STRUCTURAL pins for the OFF-CANVAS branch of the canvas-control dispatch — the sibling of
 * `control-cold-open.source.test.ts`, and for the same reason: the branch lives inside a
 * 12,000-line React component's IPC listener with no unit seam, and what it must be pinned on are
 * properties of the SOURCE.
 *
 * Every behavioural half is proven separately against real primitives: the verb set and its
 * disjointness from the other two in `lib/controlRouting.test.ts`, the reply clause and the notice
 * copy in `lib/coldOpen.test.ts`, the edge append in `state/projects.links.test.ts`.
 *
 * THE BUG this closes, which the cold-open fix left open: the user is looking at project B; an
 * agent in project A renders its output as a node — a report as `show-web`, a screenshot as
 * `show-image` — and the app switched to A. Those are the commonest reason a background session
 * touches the canvas at all, so the fix that covered `open-claude` covered the rarer half.
 */
const src = readFileSync(new URL('./Canvas.tsx', import.meta.url), 'utf8').replace(/\r\n/g, '\n')

/** The off-canvas block: from its guard to the refusal that now stands where the travel did. */
const OFF_CANVAS_GUARD = 'if (answersOffCanvas(verb) || answersFromStoredNodes(verb)) {'
function offCanvasBody(): string {
  const start = src.indexOf(OFF_CANVAS_GUARD)
  expect(start, 'the off-canvas guard').toBeGreaterThan(-1)
  const end = src.indexOf('reply({ ok: false, error: offScreenRefusal(verb,', start)
  expect(end, 'the off-screen refusal after the block').toBeGreaterThan(start)
  return src.slice(start, end)
}

/** Line comments explain what a block must NOT do, so a negative pin has to judge the code. */
function code(body: string): string {
  return body
    .split('\n')
    .filter((l) => !l.trim().startsWith('//'))
    .join('\n')
}

/** The `addAndConnect` helper, whose off-canvas half is the whole write. */
function addAndConnectBody(): string {
  const start = src.indexOf('const addAndConnect = (node: CanvasNode) => {')
  expect(start, 'addAndConnect').toBeGreaterThan(-1)
  const end = src.indexOf('const nodeCount = ()', start)
  expect(end, 'nodeCount after it').toBeGreaterThan(start)
  return src.slice(start, end)
}

describe('the off-canvas dispatch block (source pins)', () => {
  it('stands IN FRONT of the refusal that replaced the travel call', () => {
    // The travel call is what moved the user's screen, and it is gone. Scoped to the dispatch's
    // source-routing block, the off-canvas guard must precede the refusal, or the block is dead
    // code sitting behind the very thing it stands in for.
    const from = src.indexOf('routeControlSource(projects, activeId, sourceNodeId)')
    expect(from, 'the source-routing lookup').toBeGreaterThan(-1)
    const to = src.indexOf('waitForCanvasNode(', from)
    expect(to, 'the post-routing canvas wait').toBeGreaterThan(from)
    const routing = src.slice(from, to)
    const guard = routing.indexOf(OFF_CANVAS_GUARD)
    const refusal = routing.indexOf('reply({ ok: false, error: offScreenRefusal(verb,')
    expect(guard, 'the off-canvas guard inside the routing block').toBeGreaterThan(-1)
    expect(refusal, 'the off-screen refusal').toBeGreaterThan(guard)
    // …and the refusal is its ELSE, so the two are exclusive by construction rather than by a
    // `return` someone can move.
    expect(routing).toMatch(/\} else \{[\s\S]{0,800}?reply\(\{ ok: false, error: offScreenRefusal\(verb,/)
    // A refusal REPLIES and stops — it must never fall through into the canvas wait, which would
    // burn the 120 s timeout before answering.
    expect(routing.slice(refusal)).toMatch(/offScreenRefusal\(verb,[\s\S]{0,200}?\n\s*return\n/)
  })

  it('the guard polarity is not inverted', () => {
    expect(src).toContain(OFF_CANVAS_GUARD)
    expect(src).not.toContain('if (!answersOffCanvas(verb))')
    expect(src).not.toContain('if (!answersFromStoredNodes(verb))')
  })

  it('never travels, activates, reopens or moves the camera', () => {
    // The whole point. A "Go there" button exists and is the user's to press; nothing here presses
    // it for them.
    const body = code(offCanvasBody())
    expect(body).not.toContain('travelToProject')
    expect(body).not.toContain('travelToNodeRef')
    expect(body).not.toContain('setActive')
    expect(body).not.toContain('reopenProject')
    expect(body).not.toContain('goToNode')
    expect(body).not.toContain('focusNodeById')
  })

  it('does NOT wait for a canvas — waiting for one is what travelling was for', () => {
    // `waitForCanvasNode` polls the LIVE nodes for the source. Off canvas that node is never
    // going to appear there, so an ungated wait would burn the whole timeout and then answer
    // "source node is not on an open canvas" — a refusal for being off-screen, which is exactly
    // what cecb4dfe removed.
    expect(src).toContain('if (!offCanvas && route.kind !== \'unknown\' && route.kind !== \'blocked\') {')
  })

  it('keeps cecb4dfe’s fix: the only source refusal is the capability sentence', () => {
    const body = code(offCanvasBody())
    expect(body).toContain("error: 'source node is not a control-capable agent'")
    expect(body).not.toContain('is not on an open canvas')
    expect(body).not.toContain('not the active project')
  })

  it('resolves the source from the OWNING project’s serialized nodes', () => {
    const body = offCanvasBody()
    expect(body).toContain('ocStore.getProject(route.projectId)')
    expect(body).toMatch(/owner\?\.nodes\.find\(\(n\) => n\.id === sourceNodeId\)/)
    // Hydrated with the same transform the project load uses, so the shape cannot drift from a
    // live node's — the verb bodies read `src.data.title`, `src.data.cwd` and its geometry. The
    // WHOLE array, not just the source: the stored-node verbs resolve other ids against it, and a
    // display verb's placement walks the source's parent chain.
    expect(body).toContain('nodeStatesToFlow(owner.nodes) as CanvasNode[]')
    expect(body).toContain('src = ocNodes.find((n) => n.id === sourceNodeId)')
  })

  it('the acting project is the SOURCE’s, not whatever is on screen', () => {
    // `ctlProject` decides the ssh flag, the browser session key and the media allowlist route.
    // Reading `activeProjectId` off canvas answers a background agent with the human's project.
    expect(src).toMatch(/const ctlProject =\s*\n\s*offCanvas\?\.project \?\?/)
  })

  it('writes through the store, never into the live canvas', () => {
    // React Flow holds the ACTIVE project's nodes. `setNodes` / `setControlEdges` / `markDirty`
    // would put the node in front of the wrong person and dirty the wrong file.
    const body = addAndConnectBody()
    const off = code(body.slice(body.indexOf('if (offCanvas) {'), body.indexOf('setNodes((ns) =>')))
    expect(off.length).toBeGreaterThan(0)
    expect(off).toContain('applyOwnNodeMutation(offCanvas.project.id, {')
    expect(off).toContain('appendCanvasLinks(offCanvas.project.id, {')
    expect(off).toContain('writeDisk()')
    expect(off).not.toContain('setNodes(')
    expect(off).not.toContain('setControlEdges')
    expect(off).not.toContain('markDirty()')
  })

  it('the opener’s edge is a ROPE, and only a rope', () => {
    // Same edge the live path's `connect` draws, under the same id, so the node reads as
    // "produced by that conversation" when the project is next shown. `appendCanvasLinks` takes
    // both arrays and the two mean different things: a rope is display-only lineage, a bridge is
    // a context link that authorizes a READ. A display node has nothing to read, and the live
    // path draws no bridge for one — writing it here would hand an agent a context edge on
    // another project's canvas that nobody asked for, and the swap is a one-word edit.
    const off = code(
      addAndConnectBody().slice(
        addAndConnectBody().indexOf('if (offCanvas) {'),
        addAndConnectBody().indexOf('setNodes((ns) =>')
      )
    )
    expect(off).toContain(
      'ropes: [ropeEdge(`ctrl-${sourceNodeId}-${placed.id}`, sourceNodeId, placed.id)]'
    )
    expect(off).not.toContain('bridges:')
  })

  it('the colour index comes from the owning project, not the live array', () => {
    expect(src).toContain(
      'const nodeCount = () => (offCanvas ? offCanvas.project.nodes.length : nodesRef.current.length)'
    )
    // …and every display verb asks through it. A bare `nodesRef.current.length` in one of these
    // four cases compiles, passes every other test, and colours by a count from another project.
    // Scoped to the case bodies: these factories have unrelated callers (the user's own "open
    // file"), which legitimately count the live array because they land on the live canvas.
    for (const verb of ['show-image', 'show-video', 'show-web', 'open-browser']) {
      const at = src.indexOf(`case '${verb}': {`)
      expect(at, verb).toBeGreaterThan(-1)
      const body = src.slice(at, src.indexOf("\n          case '", at + 1))
      expect(body.length, verb).toBeGreaterThan(0)
      expect(body, verb).toContain('nodeCount()')
      expect(body, verb).not.toContain('nodesRef.current')
    }
  })

  it('says WHERE it went in both voices, once, and only after a node was made', () => {
    // The reply the agent reads and the strip the human reads are raised in the same place, so
    // neither can be forgotten for a verb. `created.length` is the gate: a refusal and a
    // `--dry-run` decorate nothing, because they made nothing.
    const start = src.indexOf('const reply = (r: {')
    expect(start).toBeGreaterThan(-1)
    const decor = src.slice(start, src.indexOf('api.sendAgentControlResult({ requestId, ...r })', start))
    expect(decor).toContain('if (offCanvas && r.ok && offCanvas.created.length) {')
    expect(decor).toContain('offCanvasReplyClause(project.name, { closed })')
    expect(decor).toContain('offCanvasNoticeText(project.name, created.length)')
    expect(decor).toContain('sticky: true')
    expect(decor).toContain("label: 'Go there'")
  })

  it('a CLOSED project is written into, and both voices say so', () => {
    // The same choice route `reopen` gets on the cold path: restoring a tab AND activating it is
    // the loudest version of the hijack this fixes.
    expect(offCanvasBody()).toMatch(/closed: route\.kind === 'reopen'/)
  })

  it('the notice does not fade — it reports work the user was not watching', () => {
    // An info strip that reports something the user just did may fade; this one reports a node
    // that landed in another project while they were busy elsewhere, and once it fades nothing
    // anywhere says it happened.
    expect(src).toContain("if (notice?.kind !== 'info' || notice.sticky) return")
  })
})