Collab OSCommons

Nodes and Cables

Ours Weft · CollabOS

Studied 2026-08-202D canvas. One graph model shared by all four figures. No libraries.

A node graph is two things drawn on a canvas: boxes you can move and curves between them. Almost every question about whether one feels good or bad turns out to be about the curves.The cable is the interface. It says which way the data goes, whether the connection is legal, whether anything is flowing, and whether the branch you are looking at matters at all. These four figures are the parts of that we have had to get right twice, once in Weft and once in the CollabOS sitemaps, and the ways we got them wrong first.

1 · The cable

Drag either node. A straight line is honest and unreadable the moment two of them overlap. An elbow reads like a circuit diagram and fights every diagonal. A cubic whose handles leave horizontally is the one everybody converges on, and the handle length is the whole design: it has to grow with distance, never fall below a floor, and grow again when the target is behind the source.

Read this: drag the right node to the left of the left one. At back boost 0 the cable folds into a hairpin that hides which end is which, and the graph stops being readable exactly when it gets complicated enough to need reading. At floor 0, two nodes side by side connect with a straight stub that could be pointing either way.

2 · The port, and the size of a decision

Drag from any port to any other. The dot you see is 4px across; the target you are actually hitting is the ring. A port is a decision, not a pixel, so the hit area is sized for the decision and the mark is sized for the drawing. Compatible ports light up on pickup, which is the cheapest thing in the whole interface and the one that stops the most mistakes.

Read this: take the hit radius down to 4 and the graph becomes a precision task. Take it to 34 and neighbouring ports start stealing each other's drops, which is the real ceiling: the target can only grow until it touches the next one. Turnenforce types off and the wires will land anywhere, which is how a graph becomes a thing you have to run to understand.

3 · Signal

A graph at rest tells you almost nothing about direction. One moving mark per cable fixes that instantly, and then immediately overdoes it: everything marching all the time is wallpaper. Motion has to mean something, so only live cables move. Click a node to mute it and watch what stops.

Read this: tick everything live and the figure becomes decoration: with all eight cables moving, none of them is telling you anything. The tint is the other half. Colour by type and a wrong connection is visible before it is run, which is the same argument as the ports and costs even less.

4 · What can reach the output

The single change that most improved reading a large Weft patch was not a layout feature. It was dimming everything that cannot reach an output. Walk backwards from every sink, mark what you touch, and draw the rest at a third. Dead work looks dead. Click any cable to cut or restore it.

Read this: cut the cable into the display node and the entire graph goes quiet, which is correct and is exactly the moment the feature earns itself. The walk is a breadth-first search over reversed edges, run once per change, and it costs nothing next to what it saves you in staring.
Sources. Both of these are ours.Weftis the node editor the cable behaviour comes from, including the reachability dimming and the per-type wire tints; the CollabOS sitemaps contributed the snapping and the hit-target sizing. The lessons in the notes are the mistakes, and every one of them was found by using the thing rather than by reasoning about it.

What it actually does

  • The handle length of the cubic is the entire cable design. It has to grow with horizontal distance, never fall below a floor, and grow again when the target sits behind the source, which is the case that folds the curve into a hairpin if you forget it.
  • A port is a decision, not a pixel. The mark is 4px because that is what the drawing wants; the hit area is four times that because that is what the decision wants. The target can grow until it touches its neighbour, and that collision is the real ceiling on how forgiving the interface can be.
  • Lighting up the compatible ports on pickup is the cheapest thing in the whole editor and prevents more mistakes than any validation that runs later.
  • One moving mark per live cable gives direction and liveness at a glance. The same mark on every cable at once gives nothing: motion has to be scarce to mean anything.
  • Colouring a wire by its type makes a wrong connection visible before it is run. It is the same argument as the port highlight, and it costs even less.
  • Weft is where the reachability dimming came from and the CollabOS sitemaps are where the snapping and hit-target sizing were argued out. Both arrived at the same shapes independently, which is the reason this is a study rather than a note.

What the rebuild taught

  • Dimming what cannot reach an output was the single change that most improved reading a large patch, and it is a breadth-first search over reversed edges in about eleven lines. It is not a layout feature and it beat every layout feature.
  • Nested draggables need the inner one to stop the event. A corner resize grip inside a draggable node does nothing at all until it calls stopPropagation on pointerdown, because the node drag has already captured the pointer. It reads as the grip being broken; it is the parent being greedy.
  • A rebuilt element cannot be double-clicked. When the SVG layer is regenerated between the two clicks, the browser sees two firsts and no second, so a relay that dissolves on double-click has to detect the pair itself, keyed on the wire id rather than on the element.
  • Dissolving a relay has to heal the wire, not delete two. The user sees one connection with a bead on it, so removing the bead must leave the connection, which means the operation is a splice and not a delete.
  • Wire tints have to be cached per wire id. Recomputing a colour per frame for every wire is invisible at ten wires and is the whole frame budget at two hundred.
  • An orphan is a real state and needs a real representation. A sitemap chip with no path and no parent has to be drawable somewhere, or the layout quietly loses work that the user still believes is there.

Rebuild

Four figures over one shared graph model, which is the point: none of the behaviour belongs to a node type. The cable with its handles exposed and the routing swappable, ports with the hit area drawable and type checking on a switch, a signal pass with a liveness solve behind it, and the reachability walk with cables you can cut.

Primitives

Cable routingA connection drawn as a curve whose handles carry the direction. The handle length is the design: it grows with distance, holds a floor, and grows again when the target is behind the source.
Magnetic targetA hit area sized for the decision rather than for the mark. It can grow until it touches its neighbour, and that is the ceiling.
Signal flowOne moving mark per connection, on live connections only. Direction and liveness for free; put it on everything at once and it is wallpaper.
Reachability dimWalk backwards from every output and dim whatever you never touch. Dead work looks dead, and a large graph becomes readable without being rearranged.

Where it lives

iris-cocreative.github.io/weft ↗