@kubex/zinc 1.1.94 → 1.1.96

package/src/components/flow-builder/flow-geometry.test.ts

@@ -0,0 +1,102 @@
+import {
+  BRANCH_SPREAD,
+  branchDropXs,
+  branchPillTop,
+  BUS_OFFSET,
+  type FlowConnection,
+  type FlowNodeInstance,
+  type FlowNodeType,
+  NODE_HEIGHT,
+  NODE_WIDTH,
+} from './flow.types';
+import {expect} from '@open-wc/testing';
+
+const TRIPLE: FlowNodeType = {
+  type: 'step',
+  label: 'Step',
+  group: 'action',
+  outputs: [
+    {id: 'success', label: 'Success'},
+    {id: 'failure', label: 'Failure'},
+    {id: 'skip', label: 'Skip'},
+  ],
+};
+
+const typeOf = () => TRIPLE;
+
+const node = (id: string, x: number, y = 0): FlowNodeInstance => ({id, type: 'step', x, y, data: {}});
+
+const wire = (from: string, port: string, to = 'child'): FlowConnection =>
+  ({id: `c-${from}-${port}`, source: {node: from, port}, target: {node: to, port: 'in'}});
+
+const centreOf = (n: FlowNodeInstance) => n.x + NODE_WIDTH / 2;
+
+describe('flow branch geometry', () => {
+  it('should keep a fully wired fan on the classic spread', () => {
+    const source = node('n1', 400);
+    const xs = branchDropXs(source, typeOf, [
+      wire('n1', 'success', 'a'), wire('n1', 'failure', 'b'), wire('n1', 'skip', 'c'),
+    ]);
+
+    expect(xs).to.deep.equal([
+      centreOf(source) - BRANCH_SPREAD,
+      centreOf(source),
+      centreOf(source) + BRANCH_SPREAD,
+    ]);
+  });
+
+  it('should run a lone wired branch straight down, whatever else the step declares', () => {
+    const source = node('n1', 400);
+    const xs = branchDropXs(source, typeOf, [wire('n1', 'success')]);
+
+    // Success is wired, so it keeps the node's centre line and its child sits
+    // directly below; the two spare branches tuck in beside it.
+    expect(xs[0]).to.equal(centreOf(source));
+    expect(xs[1]).to.be.greaterThan(xs[0]);
+    expect(xs[2]).to.be.greaterThan(xs[1]);
+  });
+
+  it('should give a spare branch its pill\'s width, not a whole child lane', () => {
+    const source = node('n1', 400);
+    const wired = branchDropXs(source, typeOf, [
+      wire('n1', 'success', 'a'), wire('n1', 'failure', 'b'), wire('n1', 'skip', 'c'),
+    ]);
+    const spare = branchDropXs(source, typeOf, [wire('n1', 'success')]);
+
+    // Same three branches, two of them unused: the fan collapses to well under
+    // half of what three child lanes claim.
+    expect(spare[2] - spare[0]).to.be.lessThan((wired[2] - wired[0]) / 2 + 1);
+    expect(spare[1] - spare[0]).to.be.lessThan(BRANCH_SPREAD);
+    expect(spare[2] - spare[1]).to.be.lessThan(BRANCH_SPREAD);
+  });
+
+  it('should centre two wired branches on the node with a spare branch declared', () => {
+    const source = node('n1', 400);
+    const xs = branchDropXs(source, typeOf, [wire('n1', 'success', 'a'), wire('n1', 'failure', 'b')]);
+
+    expect((xs[0] + xs[1]) / 2).to.equal(centreOf(source));
+    expect(xs[1] - xs[0]).to.equal(BRANCH_SPREAD);
+  });
+
+  it('should centre a pill along a short wire to the next row', () => {
+    const source = node('n1', 0, 0);
+    const child = node('n2', 0, NODE_HEIGHT + 160);
+
+    const top = branchPillTop(source, 40, child);
+    expect(top).to.be.greaterThan(source.y + NODE_HEIGHT);
+    expect(top).to.be.lessThan(child.y);
+  });
+
+  it('should keep a pill under its own node when the wire skips past a row', () => {
+    const source = node('n1', 0, 0);
+    const near = node('n2', 0, NODE_HEIGHT + 160);
+    const far = node('n3', 0, NODE_HEIGHT + 800);
+
+    // A long branch must not park its pill halfway down, in among the rows it
+    // passes — that is what stacked two nodes' pills on top of each other. It
+    // sits on the bus, leaving the gap below clear for the wire to route.
+    const top = branchPillTop(source, 40, far);
+    expect(top).to.equal(source.y + NODE_HEIGHT + BUS_OFFSET);
+    expect(top).to.be.lessThan(near.y);
+  });
+});

package/src/components/flow-builder/flow.types.ts

@@ -125,6 +125,14 @@ export interface FlowNodeType {
   inputs?: FlowPort[];
   /** Output ports. Defaults to a single unlabelled output. e.g. TRUE/FALSE for a split. */
   outputs?: FlowPort[];
+  /**
+   * The type's branches are the only ones it has: the canvas offers no delete
+   * on their pills, and clicking a fully-wired node's output adds nothing.
+   * For steps whose branches mirror fixed fields in the consumer's own model
+   * (a success / failure / skip triple, say), where an extra or missing branch
+   * has nowhere to be stored.
+   */
+  fixedOutputs?: boolean;
   /** Initial `data` for a freshly placed node. */
   defaultData?: Record<string, unknown>;
   /**
@@ -230,6 +238,18 @@ export const NODE_HEIGHT = 60;
  */
 export const BRANCH_SPREAD = NODE_WIDTH + 80;
 
+/** Clearance between two branches that both carry a child card. */
+const BRANCH_CARD_GAP = BRANCH_SPREAD - NODE_WIDTH;
+
+/**
+ * Clearance beside a branch with nothing under it but its own pill. A pill is a
+ * chip, not a card, so its neighbours can sit far closer than two child lanes.
+ */
+const BRANCH_PILL_GAP = 40;
+
+/** Half-width claimed by an open branch with no pill — room for its "+" target. */
+const OPEN_BRANCH_MIN_HALF = 20;
+
 // Branch geometry below a node: outputs fork from a stem onto a horizontal bus,
 // and labelled outputs drop from it into a name pill.
 export const BUS_OFFSET = 40;
@@ -243,14 +263,25 @@ export const PILL_LINE_HEIGHT = 20;
 const PILL_APPROACH = 20;
 /** The least wire kept above a sole output's pill in a tight gap. */
 const PILL_MIN_STUB = 20;
+/**
+ * The longest run a pill will centre itself along. A branch reaching past the
+ * next row would otherwise park its pill halfway down, in among nodes it has
+ * nothing to do with; beyond this it keeps the fixed drop under its own node.
+ */
+const PILL_CENTRE_MAX_RUN = 240;
 
 /**
- * Canvas y of a branch pill's top edge. A pill on a wire to a child below is
- * centred along the run from its node's bottom to the child's top — equal wire
- * above and below, however long or tight. A sole output's wire is a straight
- * stem with no bus to respect, so its pill may rise above the bus line to stay
- * centred; fan branches stop at the bus. Open branches and loop/side wires
- * keep the fixed drop below the bus.
+ * Canvas y of a branch pill's top edge. A pill on a wire to a child in the next
+ * row down is centred along the run from its node's bottom to the child's top —
+ * equal wire above and below. A sole output's wire is a straight stem with no
+ * bus to respect, so its pill may rise above the bus line to stay centred; fan
+ * branches stop at the bus.
+ *
+ * A branch reaching past the next row sits right under the bus instead: it
+ * reads as belonging to the node it hangs from rather than to whatever it flies
+ * over, and it leaves the whole gap below free for the wire to route around
+ * what is in the way. Open branches and loop/side wires keep the fixed drop
+ * below the bus, where their "+" has room.
  */
 export function branchPillTop(
   node: Pick<FlowNodeInstance, 'y'>,
@@ -261,6 +292,7 @@ export function branchPillTop(
   const bottom = node.y + NODE_HEIGHT;
   const busY = bottom + BUS_OFFSET;
   if (child && child.y >= bottom) {
+    if (child.y - bottom > PILL_CENTRE_MAX_RUN) return busY;
     const minTop = soleOutput ? bottom + PILL_MIN_STUB : busY;
     const centered = Math.round((bottom + child.y) / 2 - pillH / 2);
     return Math.max(minTop, Math.min(centered, child.y - PILL_APPROACH - pillH));
@@ -321,17 +353,52 @@ function rectsOverlap(a: Rect, b: Rect): boolean {
 export type FlowTypeOf = (type: string) => FlowNodeType | undefined;
 
 /**
- * Canvas x for each of a node's branch drops: the natural fan position under
- * the source. Pills never shift sideways to chase their child — the wire into
- * a pill is always a straight vertical, and any lateral offset to the child is
- * taken up by the elbow below the pill (which still enters the child from
- * straight above).
+ * Half the room a branch needs either side of its drop: a wired branch has to
+ * clear the child card hanging under it, an open one only its own pill.
+ */
+function branchHalfWidth(port: FlowPort, wired: boolean): number {
+  if (wired) return NODE_WIDTH / 2;
+  return port.label ? pillSize(port.label).w / 2 : OPEN_BRANCH_MIN_HALF;
+}
+
+/**
+ * Canvas x for each of a node's branch drops. Neighbours are spaced by what
+ * they actually occupy — two child lanes keep the full spread, while a branch
+ * with nothing wired to it needs only its pill — and the run is then shifted so
+ * the *wired* branches stay centred on the node. A step that declares branches
+ * it is not using therefore still runs straight down, instead of fanning empty
+ * lanes across the canvas; and a fully wired fan is spaced exactly as before.
+ *
+ * Pills never shift sideways to chase their child — the wire into a pill is
+ * always a straight vertical, and any lateral offset to the child is taken up
+ * by the elbow below the pill (which still enters the child from straight
+ * above).
  */
-export function branchDropXs(node: FlowNodeInstance, typeOf: FlowTypeOf): number[] {
+export function branchDropXs(
+  node: FlowNodeInstance,
+  typeOf: FlowTypeOf,
+  connections: FlowConnection[] = []
+): number[] {
   const outputs = nodeOutputs(node, typeOf(node.type));
   const cx = node.x + NODE_WIDTH / 2;
-  return outputs.map((_, i) =>
-    Math.round(cx + (outputs.length === 1 ? 0 : (i - (outputs.length - 1) / 2) * BRANCH_SPREAD)));
+  if (outputs.length < 2) return outputs.map(() => cx);
+
+  const wired = outputs.map(p => connections.some(c => c.source.node === node.id && c.source.port === p.id));
+
+  const offsets = [0];
+  for (let i = 1; i < outputs.length; i++) {
+    const clearance = wired[i - 1] && wired[i] ? BRANCH_CARD_GAP : BRANCH_PILL_GAP;
+    const gap = branchHalfWidth(outputs[i - 1], wired[i - 1]) + branchHalfWidth(outputs[i], wired[i]) + clearance;
+    offsets.push(offsets[i - 1] + snapToGrid(gap));
+  }
+
+  // Anchor on the branches carrying children, so wiring or unwiring a spare
+  // branch never drags the cards below the others sideways.
+  const anchored = offsets.filter((_, i) => wired[i]);
+  const span = anchored.length ? anchored : offsets;
+  const anchor = (Math.min(...span) + Math.max(...span)) / 2;
+
+  return offsets.map(o => Math.round(cx + o - anchor));
 }
 
 /**
@@ -346,7 +413,7 @@ export function nodeObstacles(
 ): Rect[] {
   const rects: Rect[] = [{x: node.x, y: node.y, w: NODE_WIDTH, h: NODE_HEIGHT, m: CARD_MARGIN}];
   const ports = nodeOutputs(node, typeOf(node.type));
-  const xs = branchDropXs(node, typeOf);
+  const xs = branchDropXs(node, typeOf, connections);
   ports.forEach((port, i) => {
     if (!port.label) return;
     const size = pillSize(port.label);

package/src/components/flow-builder/modules/flow-canvas/flow-canvas.component.ts

@@ -46,6 +46,8 @@ const ADD_POINT_OFFSET = 40;
 // input, and how far a detour clears a node card when routing around it. All
 // whole grid units so wire runs sit on grid lines.
 const WIRE_STUB = 20;
+/** Strip above a card where incoming arrows land; foreign wires keep out of it. */
+const APPROACH_ZONE = 48;
 const WIRE_APPROACH = 20;
 // Half the wire "+"'s footprint.
 const WIRE_PLUS_RADIUS = 10;
@@ -312,6 +314,9 @@ export default class ZnFlowCanvas extends ZincElement {
     const open = nodeOutputs(node, this._typeFor(node)).find(
       p => !this.connections.some(c => c.source.node === nodeId && c.source.port === p.id)
     );
+    // A fixed-output node has no spare branch to start once all of its own are
+    // wired — wire one of those instead, from its pill.
+    if (!open && this._typeFor(node)?.fixedOutputs) return;
     this._startLink(nodeId, open?.id ?? NEW_OUTPUT_PORT);
   };
 
@@ -531,7 +536,7 @@ export default class ZnFlowCanvas extends ZincElement {
     // Drops always sit at the natural fan position under the source, so the
     // arrow into a pill is a straight vertical; the wire below the pill takes
     // up any lateral offset to the child.
-    const dropXs = branchDropXs(node, t => this.registry?.get(t));
+    const dropXs = branchDropXs(node, t => this.registry?.get(t), this.connections);
     const branches = outputs.map((port, i) => {
       const conn = this.connections.find(c => c.source.node === node.id && c.source.port === port.id);
       const child = conn ? this.nodes.find(n => n.id === conn.target.node) : undefined;
@@ -590,14 +595,19 @@ export default class ZnFlowCanvas extends ZincElement {
   }
 
   /**
-   * Whether an orthogonal segment passes through any node card (with margin) —
-   * or the approach zone above one, where incoming arrows land. A foreign wire
-   * running just over a card's input port reads as connecting to it, so routes
-   * keep well clear of that strip too.
+   * Whether an orthogonal segment passes through any node card (with margin).
+   * With `keepApproachClear`, the strip above each card - where incoming arrows
+   * land - counts as occupied too: a foreign wire running just over a card's
+   * input port reads as connecting to it.
    */
-  private _segmentBlocked(a: { x: number; y: number }, b: { x: number; y: number }, ignore: Set<string>): boolean {
+  private _segmentBlocked(
+    a: { x: number; y: number },
+    b: { x: number; y: number },
+    ignore: Set<string>,
+    keepApproachClear = true
+  ): boolean {
     const M = 8;
-    const APPROACH_ZONE = 48;
+    const approach = keepApproachClear ? APPROACH_ZONE : M;
     const minX = Math.min(a.x, b.x);
     const maxX = Math.max(a.x, b.x);
     const minY = Math.min(a.y, b.y);
@@ -605,13 +615,17 @@ export default class ZnFlowCanvas extends ZincElement {
     return this.nodes.some(n =>
       !ignore.has(n.id)
       && minX < n.x + NODE_WIDTH + M && maxX > n.x - M
-      && minY < n.y + NODE_HEIGHT + M && maxY > n.y - APPROACH_ZONE
+      && minY < n.y + NODE_HEIGHT + M && maxY > n.y - approach
     );
   }
 
-  private _routeClear(points: { x: number; y: number }[], ignore: Set<string>): boolean {
+  private _routeClear(
+    points: { x: number; y: number }[],
+    ignore: Set<string>,
+    keepApproachClear = true
+  ): boolean {
     for (let i = 0; i < points.length - 1; i++) {
-      if (this._segmentBlocked(points[i], points[i + 1], ignore)) return false;
+      if (this._segmentBlocked(points[i], points[i + 1], ignore, keepApproachClear)) return false;
     }
     return true;
   }
@@ -619,8 +633,13 @@ export default class ZnFlowCanvas extends ZincElement {
   /**
    * Orthogonal waypoints from a branch exit to a child's input. The wire always
    * enters the input from above (arrow pointing down), and never passes through
-   * a node card: each candidate route is checked against every card, scanning
-   * alternative lanes / side-steps / detours until one is clear.
+   * a node card.
+   *
+   * The search runs twice: first keeping clear of the strip above every card as
+   * well as the cards themselves, then - if the corridor is genuinely too tight
+   * for that - clear of the cards alone. Only when nothing at all fits does the
+   * wire fall back to the direct line, so a wire drawn over a card now means
+   * there was no way around it rather than that the search gave up.
    */
   private _routePoints(
     from: { x: number; y: number },
@@ -632,101 +651,134 @@ export default class ZnFlowCanvas extends ZincElement {
   ) {
     const {x: tx, y: ty} = this._inputAnchor(child, targetPort);
     const ignore = new Set(sourceId ? [child.id, sourceId] : [child.id]);
+    const candidates = ty - WIRE_APPROACH >= from.y
+      ? this._forwardRoutes(from, tx, ty, midOffset, ignore)
+      : this._aroundRoutes(from, tx, ty, ignore, loop);
 
-    if (ty - WIRE_APPROACH >= from.y) {
-      // The exact midpoint, not grid-snapped: both endpoints sit on the grid,
-      // so the midpoint is always a half-tile multiple — snapping it to full
-      // tiles made the two verticals grow alternately as a node was dragged.
-      const base = Math.round((from.y + ty) / 2) + midOffset;
-      // The horizontal run stays within the middle half of the gap, so the
-      // drop and the final approach grow in proportion to the distance —
-      // lane offsets can't shove the run right up against either end.
-      const span = ty - from.y;
-      const lo = Math.min(ty - 12, Math.ceil((from.y + span / 4) / GRID_SIZE) * GRID_SIZE);
-      const hi = Math.max(lo, Math.floor((ty - span / 4) / GRID_SIZE) * GRID_SIZE);
-      const clampY = (v: number) => Math.max(lo, Math.min(hi, v));
-      let fallback: { x: number; y: number }[] | null = null;
-
-      if (tx === from.x) {
-        const straight = [from, {x: tx, y: ty}];
-        if (this._routeClear(straight, ignore)) return straight;
-        fallback = straight;
-      } else {
-        // Elbow: try the lane midY first, then scan outward for a clear line.
-        for (let step = 0; step <= 20; step++) {
-          for (const cand of step === 0 ? [base] : [base + step * GRID_SIZE, base - step * GRID_SIZE]) {
-            const my = clampY(cand);
-            if (my !== cand && step > 0) continue; // out of range
-            const route = [from, {x: from.x, y: my}, {x: tx, y: my}, {x: tx, y: ty}];
-            fallback ??= route;
-            if (this._routeClear(route, ignore)) return route;
-          }
+    for (const keepApproachClear of [true, false]) {
+      for (const route of candidates) {
+        if (this._routeClear(route, ignore, keepApproachClear)) return route;
+      }
+    }
+    return candidates[0];
+  }
+
+  /**
+   * Candidate routes to a child below, tidiest first: the straight drop or the
+   * single elbow, then the same elbow on neighbouring lines, then out around
+   * whatever sits between the two (the shape a loop-back uses - far more
+   * readable than threading a corridor when a wire skips a row it has nothing
+   * to do with), and finally a side-step that jogs out and back.
+   */
+  private _forwardRoutes(
+    from: { x: number; y: number },
+    tx: number,
+    ty: number,
+    midOffset: number,
+    ignore: Set<string>
+  ): { x: number; y: number }[][] {
+    const routes: { x: number; y: number }[][] = [];
+
+    // The exact midpoint, not grid-snapped: both endpoints sit on the grid, so
+    // the midpoint is always a half-tile multiple — snapping it to full tiles
+    // made the two verticals grow alternately as a node was dragged.
+    const base = Math.round((from.y + ty) / 2) + midOffset;
+    // The horizontal run stays within the middle half of the gap, so the drop
+    // and the final approach grow in proportion to the distance — lane offsets
+    // can't shove the run right up against either end.
+    const span = ty - from.y;
+    const lo = Math.min(ty - 12, Math.ceil((from.y + span / 4) / GRID_SIZE) * GRID_SIZE);
+    const hi = Math.max(lo, Math.floor((ty - span / 4) / GRID_SIZE) * GRID_SIZE);
+    const clampY = (v: number) => Math.max(lo, Math.min(hi, v));
+
+    if (tx === from.x) {
+      routes.push([from, {x: tx, y: ty}]);
+    } else {
+      for (let step = 0; step <= 20; step++) {
+        for (const cand of step === 0 ? [base] : [base + step * GRID_SIZE, base - step * GRID_SIZE]) {
+          const my = clampY(cand);
+          if (my !== cand && step > 0) continue; // out of range
+          routes.push([from, {x: from.x, y: my}, {x: tx, y: my}, {x: tx, y: ty}]);
         }
       }
+    }
 
-      // No simple route is clear (e.g. a card sits right under the exit) —
-      // side-step: drop to m1, jog sideways to sx, descend, and approach the
-      // input from above. The drop and the final approach share one run-in
-      // depth (equal lengths by construction); scan that depth and the jog.
-      const half = Math.floor(span / 2 / 10) * 10;
-      const baseDepth = Math.max(10, Math.round(span / 4 / 10) * 10);
-      for (let dStep = 0; dStep <= 12; dStep++) {
-        for (const depth of dStep === 0 ? [baseDepth] : [baseDepth + dStep * 10, baseDepth - dStep * 10]) {
-          if (depth < 10 || depth > half) continue;
-          const m1 = from.y + depth;
-          const m2 = ty - depth;
-          if (m2 < m1) continue;
-          for (let sStep = 1; sStep <= 14; sStep++) {
-            for (const dir of [1, -1]) {
-              const sx = from.x + dir * sStep * GRID_SIZE;
-              const route = [
-                from,
-                {x: from.x, y: m1},
-                {x: sx, y: m1},
-                {x: sx, y: m2},
-                {x: tx, y: m2},
-                {x: tx, y: ty},
-              ];
-              if (this._routeClear(route, ignore)) return route;
-            }
+    routes.push(...this._aroundRoutes(from, tx, ty, ignore, false));
+
+    // Side-step: drop to m1, jog sideways to sx, descend, and approach the
+    // input from above. The drop and the final approach share one run-in depth
+    // (equal lengths by construction); scan that depth and the jog.
+    const half = Math.floor(span / 2 / 10) * 10;
+    const baseDepth = Math.max(10, Math.round(span / 4 / 10) * 10);
+    for (let dStep = 0; dStep <= 12; dStep++) {
+      for (const depth of dStep === 0 ? [baseDepth] : [baseDepth + dStep * 10, baseDepth - dStep * 10]) {
+        if (depth < 10 || depth > half) continue;
+        const m1 = from.y + depth;
+        const m2 = ty - depth;
+        if (m2 < m1) continue;
+        for (let sStep = 1; sStep <= 14; sStep++) {
+          for (const dir of [1, -1]) {
+            const sx = from.x + dir * sStep * GRID_SIZE;
+            routes.push([
+              from,
+              {x: from.x, y: m1},
+              {x: sx, y: m1},
+              {x: sx, y: m2},
+              {x: tx, y: m2},
+              {x: tx, y: ty},
+            ]);
           }
         }
       }
-      return fallback!;
     }
 
-    // Child is beside/above: stub down, clear the card, rise above the input,
-    // then approach it from the top — widening the detour until nothing is
-    // crossed.
+    return routes;
+  }
+
+  /**
+   * Routes that leave the exit, run down the outside of everything they span
+   * vertically, and come back in above the input. Loop-backs always travel this
+   * way rather than squeezing through corridors inside the flow; a forward wire
+   * uses it when the corridor between it and its child is occupied.
+   */
+  private _aroundRoutes(
+    from: { x: number; y: number },
+    tx: number,
+    ty: number,
+    ignore: Set<string>,
+    loop: boolean
+  ): { x: number; y: number }[][] {
     const stubY = from.y + WIRE_STUB;
     const overY = ty - WIRE_APPROACH;
-    let rightSide: boolean;
-    let baseDetour: number;
-    if (loop) {
-      // Loop-backs travel around the OUTSIDE of everything they span
-      // vertically, instead of squeezing through corridors inside the flow —
-      // on whichever side costs less horizontal travel.
-      const spanned = this.nodes.filter(
-        n => n.y + NODE_HEIGHT > overY - GRID_SIZE && n.y < stubY + GRID_SIZE
-      );
-      const rightEdge = Math.max(...spanned.map(n => n.x + NODE_WIDTH)) + WIRE_DETOUR;
-      const leftEdge = Math.min(...spanned.map(n => n.x)) - WIRE_DETOUR;
-      const costRight = Math.abs(rightEdge - from.x) + Math.abs(rightEdge - tx);
-      const costLeft = Math.abs(from.x - leftEdge) + Math.abs(tx - leftEdge);
-      rightSide = costRight <= costLeft;
-      baseDetour = rightSide ? rightEdge : leftEdge;
-    } else {
-      rightSide = from.x >= child.x + NODE_WIDTH / 2;
-      baseDetour = rightSide ? child.x + NODE_WIDTH + WIRE_DETOUR : child.x - WIRE_DETOUR;
-    }
-    let fallback: { x: number; y: number }[] | null = null;
-    for (let step = 0; step <= 20; step++) {
-      const dx = baseDetour + (rightSide ? 1 : -1) * step * GRID_SIZE;
-      const route = [from, {x: from.x, y: stubY}, {x: dx, y: stubY}, {x: dx, y: overY}, {x: tx, y: overY}, {x: tx, y: ty}];
-      fallback ??= route;
-      if (this._routeClear(route, ignore)) return route;
+    const spanned = this.nodes.filter(
+      n => !ignore.has(n.id) && n.y + NODE_HEIGHT > Math.min(stubY, overY) - GRID_SIZE
+        && n.y < Math.max(stubY, overY) + GRID_SIZE
+    );
+    if (!spanned.length) return [];
+
+    const rightEdge = Math.max(...spanned.map(n => n.x + NODE_WIDTH)) + WIRE_DETOUR;
+    const leftEdge = Math.min(...spanned.map(n => n.x)) - WIRE_DETOUR;
+    const cost = (x: number) => Math.abs(x - from.x) + Math.abs(x - tx);
+    // A loop weighs both outsides; a forward wire hugs the side its child is
+    // already on, so the detour reads as a lean rather than a lap of the flow.
+    const preferRight = loop ? cost(rightEdge) <= cost(leftEdge) : tx >= (leftEdge + rightEdge) / 2;
+
+    const routes: { x: number; y: number }[][] = [];
+    for (const dir of preferRight ? [1, -1] : [-1, 1]) {
+      const edge = dir > 0 ? rightEdge : leftEdge;
+      for (let step = 0; step <= 20; step++) {
+        const dx = edge + dir * step * GRID_SIZE;
+        routes.push([
+          from,
+          {x: from.x, y: stubY},
+          {x: dx, y: stubY},
+          {x: dx, y: overY},
+          {x: tx, y: overY},
+          {x: tx, y: ty},
+        ]);
+      }
     }
-    return fallback!;
+    return routes;
   }
 
   private static _pathFrom(points: { x: number; y: number }[]): string {
@@ -1018,7 +1070,7 @@ export default class ZnFlowCanvas extends ZincElement {
           const loop = loops.has(b.conn);
           const pts = this._routePoints({x: b.x, y: b.exitY}, b.child, b.conn.target.port, offset, node.id, loop);
           paths.push(svg`<path
-            class="wire ${loop ? 'wire--loop' : ''}"
+            class="wire wire--link ${loop ? 'wire--loop' : ''}"
             d="${ZnFlowCanvas._pathFrom(pts)}"
             marker-end="url(#${loop ? 'flow-arrow-loop' : 'flow-arrow'})"
           ></path>`);
@@ -1075,10 +1127,11 @@ export default class ZnFlowCanvas extends ZincElement {
     const loops = loopConnections(this.nodes, this.connections);
     const items: {
       key: string; nodeId: string; portId: string; label: string; x: number; top: number; height: number;
-      loop: boolean; open: boolean;
+      loop: boolean; open: boolean; fixed: boolean;
     }[] = [];
     for (const node of this.nodes) {
       const {branches} = this._outputLayout(node);
+      const fixed = !!this._typeFor(node)?.fixedOutputs;
       for (const b of branches) {
         if (b.pillTop === null) continue;
         items.push({
@@ -1091,6 +1144,7 @@ export default class ZnFlowCanvas extends ZincElement {
           height: b.pillH,
           loop: !!b.conn && loops.has(b.conn),
           open: !b.conn,
+          fixed,
         });
       }
     }
@@ -1111,17 +1165,18 @@ export default class ZnFlowCanvas extends ZincElement {
               this._emit('flow-branch-pick', {nodeId: i.nodeId, port: i.portId});
             }}"
           >${i.label}</button>
-          <button
-            class="branch-pill-delete"
-            title="Delete branch"
-            @pointerdown="${(e: PointerEvent) => e.button === 0 && e.stopPropagation()}"
-            @click="${(e: Event) => {
-              e.stopPropagation();
-              this._emit('flow-branch-delete', {nodeId: i.nodeId, port: i.portId});
-            }}"
-          >
-            <zn-icon src="x@lu" size="14"></zn-icon>
-          </button>
+          ${i.fixed ? '' : html`
+            <button
+              class="branch-pill-delete"
+              title="Delete branch"
+              @pointerdown="${(e: PointerEvent) => e.button === 0 && e.stopPropagation()}"
+              @click="${(e: Event) => {
+                e.stopPropagation();
+                this._emit('flow-branch-delete', {nodeId: i.nodeId, port: i.portId});
+              }}"
+            >
+              <zn-icon src="x@lu" size="14"></zn-icon>
+            </button>`}
           ${i.open ? html`
             <span
               class="branch-pill-port"

package/src/components/flow-builder/modules/flow-step/flow-step.component.ts

@@ -42,6 +42,8 @@ export default class ZnFlowStep extends ZincElement {
   @property() inputs: string;
   /** JSON array of outputs (`"a"` or `{"id","label"}`), e.g. `'[{"id":"true","label":"TRUE"}]'`. Omit for one default output. */
   @property() outputs: string;
+  /** The declared outputs are the only branches this step has — none can be deleted or added on the canvas. */
+  @property({attribute: 'fixed-outputs', type: Boolean}) fixedOutputs = false;
 
   connectedCallback() {
     super.connectedCallback();