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.

docs: canvas edge model — ropes for --after, floating routing, eye hides edges

enes5178002bb990
diff --git a/CLAUDE.md b/CLAUDE.md
index 987c17f17..f58d27a64 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1609,9 +1609,23 @@ else, and its context links must keep classifying across restarts).
threw the command away in exactly the state the button exists to rescue). (6) Canvas subscribes
to `armedDepSig`, NOT `useAgentStatus(s => s.byId)` —
the same discipline as `loopSig`; the full map re-renders the canvas on every hook event.
- Pure logic + refusal matrix in `renderer/lib/pendingLaunch.ts` (unit-tested); the dashed dep→node
- edges are **derived, never persisted** (a pending dependency is a state that ends when the launch
- fires — the durable relation is the context bridge `--after` also draws).
+ Pure logic + refusal matrix in `renderer/lib/pendingLaunch.ts` (unit-tested);
+ the dep→node edge is a **rope** (`ctrl-<dep>-<node>`, persisted in `project.ropes` like the
+ opener's) whose LOOK is derived: dashed + ⏳ while the node's `pendingLaunch.after` still lists the
+ dep, solid once it has launched (`lib/edgeModel.ts` `ropeVisual`, over the ONE `ropeInfoOf` lookup
+ the render and BOTH delete paths ask — two builders would be two answers, and the label the user
+ reads would stop describing what the delete does). The fan-in bridge `--after` also writes hides
+ under that rope (`hiddenLinkIds`), so ONE edge per pair holds on the canvas. Deleting a WAITING
+ rope drops that dep from `after` (`dropAfterDep`) and takes **nothing else** — the covered bridge
+ survives, because "stop waiting for it" is not "stop being able to read its work"; an emptied
+ list fires. Only the `open-*`/`verify` verbs write the rope, so `missingDepRopes` heals an armed
+ node that has none at **project load**: `pendingLaunch` is persisted and the rope is not, so a node
+ armed by any other path — or by a build older than this one — would otherwise hold a launch with
+ no arrow saying what for. All edges route through the single `floating` edge type
+ (`canvas/FloatingEdge.tsx`, a bezier between the nearest borders of the two node rectangles; an
+ unmeasured node draws nothing rather than a path to the origin) — no family sets a handle side;
+ and a node whose eye is closed (`hideFanout`) hides every edge touching it as well as its cards
+ (2026-09-02 edge model, spec in docs/superpowers/specs).
**(7) Delivery waits for the node's PTY, and never fails silently** (issue #569 item 1, 2026-09).
A satisfied dependency says nothing about whether there is a terminal to type into, and the
original loop conflated the two: a flat 5 × 400 ms budget started when the CANVAS held the node
@@ -2422,6 +2436,14 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
be hidden, whatever settings.json says. The group-frame menu's colors strip answers to the same
`colors` id; builders run through `tidySeparators` so a hidden row leaves no dangling rule.
- **Add menu** = bottom dock (`Dock.tsx`) `+`, mirrored by the pane menu and command palette.
+- **Edges** are all one React Flow type, `floating` (`canvas/FloatingEdge.tsx` over the pure
+ `lib/floatingEdge.ts`): every family — ropes, context bridges, note links, subagent/loop card
+ edges, trigger edges — is drawn between the two nodes' nearest borders instead of fixed handle
+ sides, so an edge to a node placed left of or above its source takes the short way round rather
+ than looping across the canvas. A terminal node's **eye** (`hide-fanout`, "Hide cards &
+ connections") hides its subagent/loop cards AND every edge touching that node — display only:
+ the links still authorise reads and an `--after` still waits. See the `--after` bullet under
+ Canvas control for the rope model the eye hides.
- **Undo/redo**: debounced snapshot of the nodes array on settle (drag/edit), `pastRef`/
`futureRef` stacks, ⌘Z / ⌘⇧Z + dock buttons. History resets per project load; skipped
while typing in inputs/terminals.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 03032f1ab..132295934 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -293,6 +293,15 @@ has already produced a real hole: a traversal check that split on `/` alone saw
as a single harmless segment on *every* platform. Split on `[\\/]`, and prefer accepting both
dialects while storing only one (see **Node icons** in CLAUDE.md for the worked example).
+**Canvas edges are all `type: 'floating'`, and one relation gets one edge.** Never set
+`sourceHandle`/`targetHandle` on an edge object — the rendered path is computed from the two nodes'
+rectangles (`renderer/lib/floatingEdge.ts`), and a fixed side is what sent an edge to a node placed
+left of its source looping across the whole canvas. And do not add a second edge family for a
+relation a rope already carries: `--after` is a **rope** whose dashed "⏳ waits for" look is DERIVED
+from the target's `pendingLaunch` (`renderer/lib/edgeModel.ts`), and the context bridge it also
+writes stays hidden underneath it. One `open-claude --after` used to land three edges on one node.
+`src/renderer/canvas/edge-model.source.test.ts` pins both halves.
+
## Testing
`npm test` must pass, and `npm run typecheck` is the fastest gate.