@kubex/zinc 1.1.95 → 1.1.96

package/docs/pages/components/flow-builder.md

@@ -11,7 +11,12 @@ The Flow Builder is a three-panel editor for visual automations, with an optiona
 - **Header** (optional) — a full-width action bar rendered only when `slot="header-left"` / `slot="header-right"`
   content is provided (e.g. Close / Undo All Changes on the left, Apply Changes on the right).
 - **Left panel** — the steps panel (searchable, tabbed by step group).
-- **Canvas** (center) — a pannable, zoomable surface. Connections are **append-only**: click any **output port**
+- **Canvas** (center) — a pannable, zoomable surface. A node's branches fan out along a bus below it,
+  spaced by what they actually hold: two branches with children keep a full card lane apart, while a
+  branch that is only a pill sits close in, so declaring branches you have not wired costs little room.
+  Wires never run through a card: a branch that reaches past the next row keeps its pill on its own bus
+  and takes its wire out around the outside of whatever it flies over, so it always reads as ending where
+  it ends. Connections are **append-only**: click any **output port**
   on a node to start a **stray branch** — the wire follows your cursor until you click a node (or its output
   port) to attach it. Fan-in is allowed, and so are **loops** — a branch may point back to an earlier step (e.g.
   an answer that restarts the questioning); only wiring a node directly to itself is refused. Cancel by clicking
@@ -359,6 +364,12 @@ they're declarations that drive the rendered panel):
   trigger with no input.
 - `outputs` — a JSON array of ports, each a string id or a `{"id","label"}` object (e.g.
   `outputs='[{"id":"true","label":"TRUE"},{"id":"false","label":"FALSE"}]'`). Omit for a single default output.
+- `fixed-outputs` — the declared outputs are the *only* branches this step has: their pills carry no
+  delete, and clicking a fully-wired node's output adds nothing. Use it when the branches mirror fixed
+  fields in your own model (a success / failure / skip triple, say), where an extra or missing branch has
+  nowhere to be stored. Branches a step declares but has not wired cost almost no room — they are spaced
+  by their pill rather than by a whole child lane — so a step can offer every branch it supports without
+  fanning empty lanes across the canvas.
 
 Set an optional per-tab hint with the `triggers-hint` / `actions-hint` / `rules-hint` attributes on the
 builder. (A node's inspector `renderConfig` can't be expressed in markup — supply it via
@@ -604,6 +615,11 @@ builder.registerNodeTypes([
 A node type with `inputs: []` is a starting point (a trigger) with no incoming port. A type with
 multiple `outputs` renders one labeled port per output, so a branch can fan out to different steps.
 
+Add **`fixedOutputs: true`** when those outputs are the only branches the type can have — the canvas
+drops the delete on their pills and refuses to materialise an extra one. Unwired branches are spaced by
+their pill rather than a child lane, so a type can declare its full set of branches up front without the
+canvas fanning empty lanes for the ones a given node is not using.
+
 #### User-configurable outputs
 
 A type's `outputs` are the default. For steps whose branches are defined by the user (e.g. a conditional

package/docs/pages/components/page-builder.md

@@ -62,24 +62,13 @@ toggle to opt out.
 
 Style the panel through `inspector`, `inspector-header` and `inspector-body` parts.
 
-A container section additionally gets a **Layout** group at the top of the inspector: a column
-count, a weight per column, a "Keep adding rows" toggle, and — when growing is off — a row count.
-Every edit here is lossless: changing the column count re-chunks the same ordered list of
-stacks into the new shape, changing the row count only pads or trims trailing empty rows
-(clamping at the last row that still holds content), and changing a column's weight leaves
-every cell's contents untouched. All of it is undoable like any other edit.
-
 ## JavaScript API
 
 - `state` — get/set the current `PageState`. The getter returns a deep copy; the setter
   replaces the state wholesale (like the `config` attribute, it does not emit `zn-page-change`).
 - `addSection(type, index?)` — insert a new section of a registered type (default: at the end).
-- `addSectionToCell(type, containerId, cellIndex, insertIndex?)` — insert a new section of a
-  registered type into a container's cell. `cellIndex` is the position in the container's flat,
-  row-major `cells` list; `insertIndex` (default `0`, the top of the stack) is where in that
-  cell's stack it lands. Returns the new section, or `null` if the drop isn't allowed — because
-  the type isn't in the container's `accepts` list, or because it would exceed the two-level
-  nesting cap.
+- `addSectionToSlot(type, containerId, slotIndex)` — insert into a container's empty slot,
+  honouring its `accepts` list. Returns the new section, or `null` if not allowed.
 - `undo()` / `redo()` — step through edit history (bounded at 50 entries). There is no built-in
   toolbar: wire these to your own header buttons or keyboard shortcuts.
 - `registerSectionType(type)` / `registerSectionTypes(types)` — programmatic registration,
@@ -125,8 +114,8 @@ or call `restoreAutoSave()` yourself.
 
 Every edit emits `zn-page-change` with the full page state (`event.detail.state`, also
 readable via the `state` property) — plain JSON the host persists and later feeds back in
-through the `config` attribute. Sections appear in page order; a container section additionally
-carries `layout` and `cells`, per the Containers section below:
+through the `config` attribute. Sections appear in page order; container sections carry a
+`children` array sized to their slot count, with `null` for empty slots:
 
 ```json
 {
@@ -141,11 +130,10 @@ carries `layout` and `cells`, per the Containers section below:
       "type": "article-grid",
       "label": "Popular articles",
       "data": {"title": "Popular"},
-      "layout": {"widths": [1, 1, 1], "grow": false},
-      "cells": [
-        [{"id": "s-mc42h-2", "type": "article-tile", "data": {"article": "art_42"}}],
-        [{"id": "s-mc42p-3", "type": "article-tile", "data": {"article": "art_7"}}],
-        []
+      "children": [
+        {"id": "s-mc42h-2", "type": "article-tile", "data": {"article": "art_42"}},
+        {"id": "s-mc42p-3", "type": "article-tile", "data": {"article": "art_7"}},
+        null, null, null, null
       ]
     },
     {
@@ -157,10 +145,6 @@ carries `layout` and `cells`, per the Containers section below:
 }
 ```
 
-A host loading a config saved before this model — the old flat, null-padded `children` array —
-still has it accepted and migrated on load; see "Legacy `slots`" further down for what that
-older shape looked like and how it's converted.
-
 ## A required first section
 
 Pages that must always open with a particular section — a hero banner, a masthead — set
@@ -189,87 +173,32 @@ nothing about the lock is written into the persisted config.
 ```
 
 The config above declares only a rich-text section, so the hero is inserted above it — loading a
-page that lacks the required section normalises it rather than rejecting it. Two things follow
-from that. The inserted section's `data` is empty, so a host that wants the pinned section
-prefilled should put it into the `config` it hands over rather than rely on the insert. And the
-guard is client-side, so a host that persists the config should enforce the same rule on save.
-
-## Containers
-
-A section type with the `container` attribute becomes a full-row container: its card renders a
-grid of **cells** beneath it, and each cell holds an ordered **stack** of sections. The type
-author only declares that it's a container and what it starts as; the editor reshapes it after
-placing it, from the inspector's Layout group.
-
-| Attribute | Meaning |
-|---|---|
-| `container` | Marks the type a container. Required. |
-| `columns="4"` | Seeds a new instance with 4 equal columns. |
-| `widths="1 2 1"` | Seeds the column weights directly (comma- or whitespace-separated). Wins over `columns`. |
-| `grow` | Seeds the instance growable — it always offers a further empty row. |
-| `accepts="a,b"` | Restricts which types the cells take. Omit to allow any type, within the nesting cap below. |
+page that lacks the required section normalises it rather than rejecting it. The guard is
+client-side, so a host that persists the config should still enforce the same rule on save.
 
-If `widths` is present but unparsable — non-numeric tokens are discarded rather than kept as
-columns — the container falls back to `columns`, and if that's absent too, to three equal
-columns (`[1, 1, 1]`).
+## Container tiles
 
-Drag sections from the palette into a cell, stack several sections in one cell, or drag them
-between cells or out onto the page. Containers may nest **two levels deep** — a container inside
-a cell, itself holding another container — and a drop that would nest a third level is refused.
-That cap holds even when a container's `accepts` list names another container type: `accepts`
-can't be used to bypass it.
+A section type with a `slots` attribute becomes a full-row container: its card renders a
+3-column grid of that many child slots beneath it. Drag sections from the palette into empty
+cells, drag children **between cells to reorder**, or out onto the page. `accepts` restricts
+which types the slots take. Containers can't be placed inside other containers, and slot
+contents persist as `children` on the section (empty slots are `null`).
 
 ```html:preview
 <zn-page-builder heading="KB Homepage" style="height: 560px"
-  config='{"sections":[{"id":"g1","type":"row","data":{},"layout":{"widths":[1,2,1],"grow":false},"cells":[[],[],[]]}]}'>
-  <template type="row" slot="config" label="Row" icon="view_column" category="Layout"
-            description="A row of columns you can weight" container widths="1 2 1">
-    <zn-input name="title" label="Row title"></zn-input>
-  </template>
-  <template type="grid" slot="config" label="Tile Grid" icon="grid_view" category="Layout"
-            description="Keeps adding rows as you fill it" container columns="3" grow>
+  config='{"sections":[{"id":"g1","type":"article-grid","data":{}}]}'>
+  <template type="article-grid" slot="config" label="Article Grid" icon="grid_view"
+            category="Layout" description="A 3x2 grid of article tiles"
+            slots="6" accepts="article-tile">
     <zn-input name="title" label="Grid title"></zn-input>
   </template>
-  <template type="article" slot="config" label="Article" icon="article" category="Content"
+  <template type="article-tile" slot="config" label="Article" icon="article" category="Content"
             description="A single article tile">
     <zn-input name="article" label="Article id"></zn-input>
   </template>
 </zn-page-builder>
 ```
 
-### The container config
-
-A container persists its `layout` and its `cells` — a flat, row-major list of stacks whose
-length is always a whole multiple of `layout.widths.length`. Rows are implicit
-(`cells.length / layout.widths.length`), so there's no row count to keep in sync:
-
-```json
-{
-  "id": "s-mc42a-1",
-  "type": "row",
-  "layout": { "widths": [1, 2, 1], "grow": false },
-  "cells": [
-    [ { "id": "s-1", "type": "nav", "data": {} },
-      { "id": "s-2", "type": "links", "data": {} } ],
-    [ { "id": "s-3", "type": "hero", "data": {} } ],
-    []
-  ]
-}
-```
-
-Render it by mapping each weight to a grid track and each cell to a stack. A **growable**
-container never persists a trailing all-empty row — the builder adds that row itself at render
-time, so don't expect it in the JSON. A **fixed** container's trailing empty row, by contrast, is
-part of its layout and does persist.
-
-### Legacy `slots`
-
-`slots="6"` still declares a container, and pages persisted with the old flat, null-padded
-`children` array still load: they're migrated to `layout` + `cells` on load and re-saved in the
-new shape — `children` is never written back. A `slots`-declared container that has no explicit
-`accepts` also keeps its older, stricter rule of refusing container types in its cells (rather
-than allowing anything up to the nesting cap). Prefer `container` going forward.
-
 ## List sections
 
 Sections that show a set of existing items (categories, articles, …) reference them by id:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.95",
+  "version": "1.1.96",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",

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

@@ -493,6 +493,7 @@ export default class ZnFlowBuilder extends ZincElement {
       description: el.getAttribute('description') ?? undefined,
       inputs: ZnFlowBuilder._parsePorts(el.getAttribute('inputs')),
       outputs: ZnFlowBuilder._parsePorts(el.getAttribute('outputs')),
+      fixedOutputs: el.hasAttribute('fixed-outputs'),
       branchFilters: ZnFlowBuilder._parseBranchFilters(el),
     };
   }
@@ -810,10 +811,20 @@ export default class ZnFlowBuilder extends ZincElement {
     // Centred under the branch drop (where the pill hangs), a full layer below
     // the source (same rhythm as untangle) — the child lands in a straight
     // line under the branch instead of being shoved sideways by collision.
-    const x = branchDropXs(source, t => this.registry.get(t))[idx];
+    const x = branchDropXs(source, t => this.registry.get(t), this._state.connections)[idx];
     return {x: Math.round(x - NODE_WIDTH / 2), y: source.y + LAYOUT_V_GAP};
   }
 
+  /**
+   * Whether a node refuses the branch being asked of it: a fixed-output type
+   * has only the branches it declares, so the "new branch" sentinel has nowhere
+   * to go. Checked before the history push, so a refused gesture is a no-op
+   * rather than an empty undo step.
+   */
+  private _refusesBranch(node: FlowNodeInstance, port: string): boolean {
+    return port === NEW_OUTPUT_PORT && !!this.registry.get(node.type)?.fixedOutputs;
+  }
+
   /**
    * Resolve an output port id on a node: the "new branch" sentinel materialises a
    * fresh, labelled output port (per-instance), so it exists before connecting.
@@ -847,6 +858,7 @@ export default class ZnFlowBuilder extends ZincElement {
     if (!source || !type) return;
     const inPort = typeInputs(type)[0]?.id;
     if (!inPort) return; // an entrypoint takes no inputs, so it can't be attached
+    if (this._refusesBranch(source, port)) return;
     this._pushHistory();
     port = this._ensureOutput(source, port);
     this._ensureBranchLabel(source, port);
@@ -882,6 +894,7 @@ export default class ZnFlowBuilder extends ZincElement {
     if (!source || !target || sourceId === targetId) return;
     const inPort = firstInputId(target, this.registry.get(target.type));
     if (inPort === null) return;
+    if (this._refusesBranch(source, port)) return;
     this._pushHistory();
     port = this._ensureOutput(source, port);
     this._ensureBranchLabel(source, port);
@@ -970,6 +983,7 @@ export default class ZnFlowBuilder extends ZincElement {
   private _onBranchDelete = (e: CustomEvent<{ nodeId: string; port: string }>) => {
     const node = this._state.nodes.find(n => n.id === e.detail.nodeId);
     if (!node) return;
+    if (this.registry.get(node.type)?.fixedOutputs) return; // its branches are the only ones it has
     this._pushHistory();
     const outputs = nodeOutputs(node, this.registry.get(node.type)).filter(p => p.id !== e.detail.port);
     // Deleting the last branch leaves a plain open output, so the node stays extensible.
@@ -1041,6 +1055,7 @@ export default class ZnFlowBuilder extends ZincElement {
     if (!owner || !moving) return;
     const inPort = firstInputId(moving, this.registry.get(moving.type));
     if (inPort === null) return;
+    if (this._refusesBranch(owner, e.detail.port)) return;
 
     this._pushHistory();
     const outPort = this._ensureOutput(owner, e.detail.port);

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

@@ -1,6 +1,6 @@
 import '../../../dist/zn.min.js';
 import {expect, fixture, html} from '@open-wc/testing';
-import type {FlowNodeType, FlowState} from './flow.types';
+import {type FlowNodeType, type FlowState, NEW_OUTPUT_PORT, NODE_HEIGHT, NODE_WIDTH} from './flow.types';
 import type ZnFlowBuilder from './flow-builder.component';
 
 const TRIGGER: FlowNodeType = {type: 'webhook', label: 'Webhook', group: 'trigger', category: 'Contacts'};
@@ -293,4 +293,209 @@ describe('<zn-flow-builder>', () => {
       ]);
     });
   });
+  describe('fixed outputs', () => {
+    const FIXED: FlowNodeType = {
+      type: 'step',
+      label: 'Step',
+      group: 'action',
+      fixedOutputs: true,
+      outputs: [
+        {id: 'success', label: 'Success'},
+        {id: 'failure', label: 'Failure'},
+        {id: 'skip', label: 'Skip'},
+      ],
+    };
+
+    const wiredState: FlowState = {
+      nodes: [
+        {id: 'n1', type: 'step', x: 0, y: 0, data: {}},
+        {id: 'n2', type: 'step', x: 0, y: 220, data: {}},
+      ],
+      connections: [
+        {id: 'c1', source: {node: 'n1', port: 'success'}, target: {node: 'n2', port: 'in'}},
+        {id: 'c2', source: {node: 'n1', port: 'failure'}, target: {node: 'n2', port: 'in'}},
+        {id: 'c3', source: {node: 'n1', port: 'skip'}, target: {node: 'n2', port: 'in'}},
+      ],
+      notes: [],
+    };
+
+    const makeFixed = async (state: FlowState) => {
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder></zn-flow-builder>`);
+      el.registerNodeTypes([FIXED]);
+      el.setState(state);
+      await el.updateComplete;
+      return el;
+    };
+
+    it('should refuse to delete one of a fixed type\'s branches', async () => {
+      const el = await makeFixed(wiredState);
+      el.dispatchEvent(new CustomEvent('flow-branch-delete', {detail: {nodeId: 'n1', port: 'failure'}}));
+      await el.updateComplete;
+
+      const node = el.getState().nodes[0];
+      expect(node.outputs ?? FIXED.outputs).to.have.length(3);
+      expect(el.getState().connections).to.have.length(3);
+    });
+
+    it('should not offer a delete on a fixed type\'s branch pills', async () => {
+      const el = await makeFixed(wiredState);
+      const canvas = el.shadowRoot?.querySelector('zn-flow-canvas');
+      expect(canvas?.shadowRoot?.querySelector('.branch-pill')).to.exist;
+      expect(canvas?.shadowRoot?.querySelector('.branch-pill-delete')).to.not.exist;
+    });
+
+    it('should not grow a fixed type an extra branch when every one is wired', async () => {
+      const el = await makeFixed(wiredState);
+      el.dispatchEvent(new CustomEvent('flow-link-assign', {
+        detail: {nodeId: 'n1', port: NEW_OUTPUT_PORT, targetId: 'n2'},
+      }));
+      await el.updateComplete;
+
+      const node = el.getState().nodes[0];
+      expect(node.outputs ?? FIXED.outputs).to.have.length(3);
+      expect(el.getState().connections).to.have.length(3);
+    });
+
+    it('should still let an ordinary type grow a branch', async () => {
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder></zn-flow-builder>`);
+      el.registerNodeTypes([{...FIXED, fixedOutputs: false}]);
+      el.setState(wiredState);
+      await el.updateComplete;
+
+      el.dispatchEvent(new CustomEvent('flow-link-assign', {
+        detail: {nodeId: 'n1', port: NEW_OUTPUT_PORT, targetId: 'n2'},
+      }));
+      await el.updateComplete;
+
+      expect(el.getState().nodes[0].outputs).to.have.length(4);
+    });
+
+    it('should read fixed-outputs off a declared step', async () => {
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder>
+          <zn-flow-step type="step" group="action" label="Step" fixed-outputs
+                        outputs='[{"id":"success","label":"Success"},{"id":"failure","label":"Failure"}]'>
+          </zn-flow-step>
+        </zn-flow-builder>`);
+      el.setState({
+        nodes: [{id: 'n1', type: 'step', x: 0, y: 0, data: {}}],
+        connections: [],
+        notes: [],
+      });
+      await el.updateComplete;
+
+      el.dispatchEvent(new CustomEvent('flow-branch-delete', {detail: {nodeId: 'n1', port: 'failure'}}));
+      await el.updateComplete;
+      expect(el.getState().nodes[0].outputs).to.be.undefined; // untouched: still the type's two
+    });
+  });
+  describe('wire routing', () => {
+    const TRIPLE: FlowNodeType = {
+      type: 'step',
+      label: 'Step',
+      group: 'action',
+      fixedOutputs: true,
+      outputs: [
+        {id: 'success', label: 'Success'},
+        {id: 'failure', label: 'Failure'},
+        {id: 'skip', label: 'Skip'},
+      ],
+    };
+
+    // A's failure skips the middle row entirely and lands on C, while A's other
+    // branches and B's success feed the rows in between — the arrangement that
+    // drew A's failure wire straight down through B, so it read as though the
+    // branch ended at B.
+    const SKIP_A_ROW: FlowState = {
+      nodes: [
+        {id: 'a', type: 'step', x: 200, y: 700, data: {}},
+        {id: 'b', type: 'step', x: 200, y: 920, data: {}},
+        {id: 'c', type: 'step', x: 200, y: 1140, data: {}},
+      ],
+      connections: [
+        {id: 'c1', source: {node: 'a', port: 'success'}, target: {node: 'b', port: 'in'}},
+        {id: 'c2', source: {node: 'a', port: 'skip'}, target: {node: 'b', port: 'in'}},
+        {id: 'c3', source: {node: 'a', port: 'failure'}, target: {node: 'c', port: 'in'}},
+        {id: 'c4', source: {node: 'b', port: 'success'}, target: {node: 'c', port: 'in'}},
+      ],
+      notes: [],
+    };
+
+    const points = (d: string) => {
+      const numbers = d.match(/-?\d+(\.\d+)?/g)?.map(Number) ?? [];
+      const out: { x: number; y: number }[] = [];
+      for (let i = 0; i + 1 < numbers.length; i += 2) out.push({x: numbers[i], y: numbers[i + 1]});
+      return out;
+    };
+
+    const wirePaths = async (state: FlowState) => {
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder></zn-flow-builder>`);
+      el.registerNodeTypes([TRIPLE]);
+      el.setState(state);
+      await el.updateComplete;
+      const canvas = el.shadowRoot?.querySelector('zn-flow-canvas');
+      await canvas?.updateComplete;
+      return Array.from(canvas?.shadowRoot?.querySelectorAll('path.wire--link') ?? [])
+        .map(p => points(p.getAttribute('d') ?? ''))
+        .filter(pts => pts.length > 1);
+    };
+
+    // Segments are orthogonal, so a crossing is a plain rect overlap. The card's
+    // own edges are fair game: wires legitimately end on the top one.
+    const crossesCard = (pts: { x: number; y: number }[], card: { x: number; y: number }) => {
+      const E = 1;
+      for (let i = 0; i < pts.length - 1; i++) {
+        const minX = Math.min(pts[i].x, pts[i + 1].x);
+        const maxX = Math.max(pts[i].x, pts[i + 1].x);
+        const minY = Math.min(pts[i].y, pts[i + 1].y);
+        const maxY = Math.max(pts[i].y, pts[i + 1].y);
+        if (minX < card.x + NODE_WIDTH - E && maxX > card.x + E
+          && minY < card.y + NODE_HEIGHT - E && maxY > card.y + E) {
+          return true;
+        }
+      }
+      return false;
+    };
+
+    it('should route a row-skipping wire around the card it flies over', async () => {
+      const paths = await wirePaths(SKIP_A_ROW);
+      const middle = {x: 200, y: 920};
+
+      expect(paths.length).to.be.greaterThan(0);
+      paths.forEach(pts => {
+        expect(crossesCard(pts, middle), `wire ${JSON.stringify(pts)} crosses the middle card`)
+          .to.equal(false);
+      });
+    });
+
+    it('should take the row-skipping wire out to the side, not through the column', async () => {
+      const paths = await wirePaths(SKIP_A_ROW);
+      // A's failure pill sits on A's bus, so its wire is the one leaving highest.
+      const skipping = paths.reduce((lowestY, pts) => (pts[0].y < lowestY[0].y ? pts : lowestY));
+
+      expect(skipping[skipping.length - 1].y).to.equal(1140); // ends on C's input
+      expect(skipping.length).to.be.greaterThan(2); // not the straight drop
+      // It leaves the corridor the cards occupy (200..440) on its way past.
+      const outside = skipping.some(p => p.x > 440 || p.x < 200);
+      expect(outside, `expected a detour outside the column, got ${JSON.stringify(skipping)}`).to.equal(true);
+    });
+
+    it('should still draw a straight wire when the corridor is clear', async () => {
+      const paths = await wirePaths({
+        nodes: [
+          {id: 'a', type: 'step', x: 200, y: 700, data: {}},
+          {id: 'b', type: 'step', x: 200, y: 920, data: {}},
+        ],
+        connections: [{id: 'c1', source: {node: 'a', port: 'success'}, target: {node: 'b', port: 'in'}}],
+        notes: [],
+      });
+
+      expect(paths).to.have.length(1);
+      expect(paths[0]).to.have.length(2);
+      expect(paths[0][0].x).to.equal(paths[0][1].x);
+    });
+  });
 });

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);
+  });
+});