@kubex/zinc 1.1.28 → 1.1.31

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

@@ -27,19 +27,39 @@ describe('<zn-flow-builder>', () => {
     expect(items?.[0].textContent).to.contain('Webhook');
   });
 
-  it('should round-trip state through getState/setState', async () => {
+  it('should round-trip state through getState/setState, keeping positions', async () => {
     const el = await fixture<ZnFlowBuilder>(html`
       <zn-flow-builder></zn-flow-builder>`);
     const state: FlowState = {
       nodes: [{id: 'n1', type: 'webhook', x: 10, y: 20, data: {}}],
       connections: [],
-      notes: [],
+      notes: [{id: 'note1', x: 300, y: 40, width: 220, height: 120, text: 'hi'}],
     };
     el.setState(state);
     await el.updateComplete;
 
-    expect(el.getState().nodes).to.have.length(1);
-    expect(el.getState().nodes[0].id).to.equal('n1');
+    // Save (value) then load (value =) — positional data survives the trip.
+    const json = el.value;
+    el.setState({nodes: [], connections: [], notes: []});
+    el.value = json;
+
+    const loaded = el.getState();
+    expect(loaded.nodes[0]).to.deep.include({id: 'n1', x: 10, y: 20});
+    expect(loaded.notes[0]).to.deep.include({x: 300, y: 40, width: 220, height: 120});
+  });
+
+  it('should serialize to the full state via toJSON, ready for a POST body', async () => {
+    const el = await fixture<ZnFlowBuilder>(html`
+      <zn-flow-builder heading="My Flow"></zn-flow-builder>`);
+    el.setState({
+      nodes: [{id: 'n1', type: 'webhook', x: 60, y: 80, data: {}}],
+      connections: [],
+      notes: [],
+    });
+
+    const body = JSON.parse(JSON.stringify(el)) as FlowState;
+    expect(body.nodes[0]).to.deep.include({id: 'n1', x: 60, y: 80});
+    expect(JSON.stringify(el)).to.equal(el.value);
   });
 
   it('should parse the value attribute as JSON', async () => {
@@ -56,4 +76,221 @@ describe('<zn-flow-builder>', () => {
     expect(() => el.undo()).to.not.throw();
     expect(el.getState().nodes).to.have.length(0);
   });
+
+  it('should tuck the side panels away via the edge chevrons', async () => {
+    const el = await fixture<ZnFlowBuilder>(html`
+      <zn-flow-builder></zn-flow-builder>`);
+    const builder = el.shadowRoot!.querySelector('.builder')!;
+    (el.shadowRoot!.querySelector('.panel-toggle--left') as HTMLButtonElement).click();
+    (el.shadowRoot!.querySelector('.panel-toggle--right') as HTMLButtonElement).click();
+    await el.updateComplete;
+    expect(builder.classList.contains('builder--steps-collapsed')).to.equal(true);
+    expect(builder.classList.contains('builder--side-collapsed')).to.equal(true);
+
+    // Selecting a node needs the inspector — the right panel comes back.
+    el.setState({nodes: [{id: 'n1', type: 'webhook', x: 0, y: 0, data: {}}], connections: [], notes: []});
+    el.dispatchEvent(new CustomEvent('flow-node-select', {detail: {nodeId: 'n1'}}));
+    await el.updateComplete;
+    expect(builder.classList.contains('builder--side-collapsed')).to.equal(false);
+    expect(builder.classList.contains('builder--steps-collapsed')).to.equal(true);
+  });
+
+  describe('auto-save', () => {
+    const KEY = 'zn-flow-builder:as-test';
+    const STATE: FlowState = {
+      nodes: [{id: 'n1', type: 'webhook', x: 40, y: 80, data: {}}],
+      connections: [],
+      notes: [],
+    };
+    const tick = (ms: number) => new Promise(r => setTimeout(r, ms));
+
+    afterEach(() => localStorage.removeItem(KEY));
+
+    it('should not auto-save without the attribute', async () => {
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder id="as-test"></zn-flow-builder>`);
+      el.setState(STATE);
+      expect(el.autoSave).to.equal(null);
+      await tick(150);
+      expect(localStorage.getItem(KEY)).to.equal(null);
+    });
+
+    it('should default a bare attribute to 5 minutes', async () => {
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder id="as-test" auto-save></zn-flow-builder>`);
+      expect(el.autoSave).to.equal(5);
+    });
+
+    it('should save the state (with positions) on the interval', async () => {
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder id="as-test" auto-save="0.001"></zn-flow-builder>`);
+      el.setState(STATE);
+      await tick(150);
+
+      const saved = JSON.parse(localStorage.getItem(KEY)!) as { savedAt: number; state: FlowState };
+      expect(saved.savedAt).to.be.a('number');
+      expect(saved.state.nodes[0]).to.deep.include({id: 'n1', x: 40, y: 80});
+    });
+
+    it('should show the status pill: a saved flash, then time since last save', async function (this: Mocha.Context) {
+      this.timeout(6000); // outlasts the 2.5s "Auto-saved" flash
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder id="as-test" auto-save="0.001"></zn-flow-builder>`);
+      expect(el.shadowRoot?.querySelector('.save-status')).to.equal(null);
+
+      el.setState(STATE);
+      await tick(150);
+      await el.updateComplete;
+      const status = el.shadowRoot?.querySelector('.save-status');
+      expect(status?.textContent).to.contain('Auto-saved');
+      expect(status?.classList.contains('save-status--saved')).to.equal(true);
+
+      // Slow the schedule right down; once the flash runs out, the pill
+      // reports how long since the last save.
+      el.autoSave = 60;
+      await tick(2700);
+      await el.updateComplete;
+      expect(el.shadowRoot?.querySelector('.save-status')?.textContent).to.contain('Last saved');
+    });
+
+    it('should offer to restore a differing auto-save on load', async () => {
+      localStorage.setItem(KEY, JSON.stringify({savedAt: Date.now(), state: STATE}));
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder id="as-test" auto-save></zn-flow-builder>`);
+
+      // Loading a different flow — the draft is offered.
+      el.setState({nodes: [{id: 'other', type: 'webhook', x: 0, y: 0, data: {}}], connections: [], notes: []});
+      await el.updateComplete;
+      const banner = el.shadowRoot?.querySelector('.restore-banner');
+      expect(banner?.textContent).to.contain('differs from this flow');
+
+      (banner?.querySelector('.restore-banner__restore') as HTMLButtonElement).click();
+      await el.updateComplete;
+      expect(el.getState().nodes[0].id).to.equal('n1');
+      expect(el.shadowRoot?.querySelector('.restore-banner')).to.equal(null);
+
+      // Loading the same flow as the draft — nothing to offer.
+      el.setState(JSON.parse(JSON.stringify(STATE)) as FlowState);
+      await el.updateComplete;
+      expect(el.shadowRoot?.querySelector('.restore-banner')).to.equal(null);
+    });
+
+    it('should keep the offered draft intact across ticks, so Restore still applies it', async () => {
+      localStorage.setItem(KEY, JSON.stringify({savedAt: Date.now(), state: STATE}));
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder id="as-test" auto-save="0.001"></zn-flow-builder>`);
+      el.setState({nodes: [{id: 'other', type: 'webhook', x: 0, y: 0, data: {}}], connections: [], notes: []});
+      await el.updateComplete;
+      expect(el.shadowRoot?.querySelector('.restore-banner')).to.not.equal(null);
+
+      // Several auto-save ticks pass while the prompt is open — the draft
+      // must not be overwritten by the loaded flow.
+      await tick(250);
+      const saved = JSON.parse(localStorage.getItem(KEY)!) as { state: FlowState };
+      expect(saved.state.nodes[0].id).to.equal('n1');
+
+      (el.shadowRoot?.querySelector('.restore-banner__restore') as HTMLButtonElement).click();
+      await el.updateComplete;
+      expect(el.getState().nodes[0]).to.deep.include({id: 'n1', x: 40, y: 80});
+    });
+
+    it('should restore a fresh auto-save and purge an expired one', async () => {
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder id="as-test"></zn-flow-builder>`);
+
+      localStorage.setItem(KEY, JSON.stringify({savedAt: Date.now(), state: STATE}));
+      expect(el.restoreAutoSave()).to.equal(true);
+      expect(el.getState().nodes[0]).to.deep.include({id: 'n1', x: 40, y: 80});
+
+      // Past the 1-day TTL: not restored, and cleaned out of storage.
+      localStorage.setItem(KEY, JSON.stringify({savedAt: Date.now() - 25 * 60 * 60 * 1000, state: STATE}));
+      expect(el.restoreAutoSave()).to.equal(false);
+      expect(localStorage.getItem(KEY)).to.equal(null);
+    });
+  });
+
+  describe('branch filters declared in markup', () => {
+    const SPLIT_STATE: FlowState = {
+      nodes: [{id: 'n1', type: 'split', x: 0, y: 0, data: {}}],
+      connections: [],
+      notes: [],
+    };
+
+    async function makeBuilder(): Promise<ZnFlowBuilder> {
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder>
+          <zn-flow-step type="split" group="rule" label="Conditional Split"
+                        outputs='[{"id":"true","label":"TRUE"},{"id":"false","label":"FALSE"}]'>
+            <zn-flow-filter id="engagement" label="Email engagement">
+              <zn-flow-filter-field id="count" type="number" value="2">
+                <zn-flow-operator>at least</zn-flow-operator>
+                <zn-flow-operator>at most</zn-flow-operator>
+                <zn-flow-unit value="days">day(s)</zn-flow-unit>
+                <zn-flow-unit value="months">month(s)</zn-flow-unit>
+              </zn-flow-filter-field>
+            </zn-flow-filter>
+            <zn-flow-filter id="lost-reason" label="Lost reason">
+              <zn-flow-filter-field id="reason" type="select" operators="Is equal to,Is not equal to">
+                <zn-flow-option value="price">Price</zn-flow-option>
+              </zn-flow-filter-field>
+            </zn-flow-filter>
+          </zn-flow-step>
+        </zn-flow-builder>`);
+      el.setState(SPLIT_STATE);
+      await el.updateComplete;
+      // Open the TRUE branch's editor, as clicking its pill would.
+      el.dispatchEvent(new CustomEvent('flow-branch-pick', {detail: {nodeId: 'n1', port: 'true'}}));
+      await el.updateComplete;
+      return el;
+    }
+
+    it('should feed nested <zn-flow-filter> declarations to the branch conditions editor', async () => {
+      const el = await makeBuilder();
+      const editor = el.shadowRoot?.querySelector('zn-flow-branch-conditions');
+      expect(editor).to.exist;
+      expect(editor?.filters).to.have.length(2);
+      expect(editor?.filters[0]).to.deep.include({id: 'engagement', label: 'Email engagement'});
+      expect(editor?.filters[0].fields[0].operators).to.deep.equal([{value: 'at least'}, {value: 'at most'}]);
+      expect(editor?.filters[0].fields[0].units).to.deep.equal(
+        [{value: 'days', label: 'day(s)'}, {value: 'months', label: 'month(s)'}]);
+      expect(editor?.filters[0].fields[0].value).to.equal(2);
+      expect(editor?.filters[1].fields[0].options).to.deep.equal([{value: 'price', label: 'Price'}]);
+    });
+
+    it('should persist saved conditions on the output port', async () => {
+      const el = await makeBuilder();
+      const editor = el.shadowRoot?.querySelector('zn-flow-branch-conditions');
+      const conditions = [[{filter: 'engagement', values: {count: {operator: 'at least', value: 3}}}]];
+      editor?.dispatchEvent(new CustomEvent('flow-conditions-save', {
+        bubbles: true,
+        composed: true,
+        detail: {conditions},
+      }));
+      await el.updateComplete;
+
+      const port = el.getState().nodes[0].outputs?.find(p => p.id === 'true');
+      expect(port?.data?.conditions).to.deep.equal(conditions);
+      // Saving closes the branch editor.
+      expect(el.shadowRoot?.querySelector('zn-flow-branch-conditions')).to.not.exist;
+    });
+
+    it('should parse the branch-filters JSON attribute', async () => {
+      const el = await fixture<ZnFlowBuilder>(html`
+        <zn-flow-builder>
+          <zn-flow-step type="split" group="rule" label="Split"
+                        outputs='[{"id":"true","label":"TRUE"}]'
+                        branch-filters='[{"id":"plan","label":"Plan","fields":[{"id":"name","options":["Basic","Pro"]}]}]'>
+          </zn-flow-step>
+        </zn-flow-builder>`);
+      el.setState(SPLIT_STATE);
+      await el.updateComplete;
+      el.dispatchEvent(new CustomEvent('flow-branch-pick', {detail: {nodeId: 'n1', port: 'true'}}));
+      await el.updateComplete;
+
+      const editor = el.shadowRoot?.querySelector('zn-flow-branch-conditions');
+      expect(editor?.filters).to.deep.equal([
+        {id: 'plan', label: 'Plan', fields: [{id: 'name', options: [{value: 'Basic'}, {value: 'Pro'}]}]},
+      ]);
+    });
+  });
 });

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

@@ -10,10 +10,13 @@ import {
   snapToGrid,
 } from './flow.types';
 
-/** Horizontal gap between node origins within a layer. */
+/** Horizontal gap between node origins within a layer (= BRANCH_SPREAD, so siblings land under their drops). */
 export const LAYOUT_H_GAP = NODE_WIDTH + 80;
-/** Vertical gap between layers — clears the bus, a branch pill, and the wire run-in. */
-export const LAYOUT_V_GAP = 300;
+/**
+ * Vertical gap between layers: a 160 card-to-card gap — a centred pill gets 60
+ * of wire above and below — keeping the arranged flow compact.
+ */
+export const LAYOUT_V_GAP = 220;
 const MARGIN = 40;
 
 const avg = (ns: number[]) => ns.reduce((a, b) => a + b, 0) / ns.length;
@@ -60,6 +63,17 @@ export function untangledPositions(
   };
   nodes.forEach(n => layerFor(n.id));
 
+  // Secondary roots (no forward parents — e.g. a stray answer that only feeds
+  // into the flow) sink to just above their earliest child, instead of floating
+  // at the very top with a wire spanning the whole flow.
+  nodes.forEach(n => {
+    if (incoming.get(n.id)!.some(c => !backEdges.has(c))) return;
+    const outs = outgoing.get(n.id)!.filter(c => !backEdges.has(c));
+    if (!outs.length) return;
+    const above = Math.min(...outs.map(c => layerOf.get(c.target.node)!)) - 1;
+    if (above > layerOf.get(n.id)!) layerOf.set(n.id, above);
+  });
+
   const layers: FlowNodeInstance[][] = Array.from(
     {length: Math.max(...layerOf.values()) + 1},
     () => []
@@ -78,23 +92,34 @@ export function untangledPositions(
 
   // 2. Ordering: roots keep their left-to-right order; deeper layers sort by the
   //    mean of their parents' order (nudged by which output port they hang from),
-  //    which keeps siblings in port order and reduces wire crossings.
+  //    which keeps siblings in port order and reduces wire crossings. A second
+  //    pass keys parentless nodes (secondary roots sunk beside the flow they
+  //    join) on their children's first-pass order, so they sort next to what
+  //    they feed instead of defaulting to the far left.
   const orderIdx = new Map<string, number>();
+  const parentBary = (n: FlowNodeInstance): number | null => {
+    // Forward parents only — loops don't influence ordering.
+    const ordered = incoming.get(n.id)!.filter(c => !backEdges.has(c) && orderIdx.has(c.source.node));
+    if (!ordered.length) return null;
+    return avg(ordered.map(c => {
+      const parent = byId.get(c.source.node)!;
+      const outputs = nodeOutputs(parent, typeOf(parent.type));
+      const count = Math.max(outputs.length, 1);
+      const idx = Math.max(outputs.findIndex(p => p.id === c.source.port), 0);
+      return orderIdx.get(parent.id)! + (idx + 1) / (count + 1) - 0.5;
+    }));
+  };
+  const childBary = (n: FlowNodeInstance): number | null => {
+    const outs = outgoing.get(n.id)!.filter(c => !backEdges.has(c) && orderIdx.has(c.target.node));
+    return outs.length ? avg(outs.map(c => orderIdx.get(c.target.node)!)) : null;
+  };
   layers[0].sort((a, b) => a.x - b.x).forEach((n, i) => orderIdx.set(n.id, i));
   for (let l = 1; l < layers.length; l++) {
-    const bary = (n: FlowNodeInstance) => {
-      // Forward parents only — loops don't influence ordering.
-      const ordered = incoming.get(n.id)!.filter(c => !backEdges.has(c) && orderIdx.has(c.source.node));
-      if (!ordered.length) return 0;
-      return avg(ordered.map(c => {
-        const parent = byId.get(c.source.node)!;
-        const outputs = nodeOutputs(parent, typeOf(parent.type));
-        const count = Math.max(outputs.length, 1);
-        const idx = Math.max(outputs.findIndex(p => p.id === c.source.port), 0);
-        return orderIdx.get(parent.id)! + (idx + 1) / (count + 1) - 0.5;
-      }));
-    };
-    layers[l].sort((a, b) => bary(a) - bary(b)).forEach((n, i) => orderIdx.set(n.id, i));
+    layers[l].sort((a, b) => (parentBary(a) ?? 0) - (parentBary(b) ?? 0)).forEach((n, i) => orderIdx.set(n.id, i));
+  }
+  for (let l = 1; l < layers.length; l++) {
+    const key = (n: FlowNodeInstance) => parentBary(n) ?? childBary(n) ?? 0;
+    layers[l].sort((a, b) => key(a) - key(b)).forEach((n, i) => orderIdx.set(n.id, i));
   }
 
   // 3. Coordinates: place a layer at each node's desired x, resolving overlaps

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

@@ -12,6 +12,94 @@ export interface FlowPort {
   data?: Record<string, unknown>;
 }
 
+/** A choice in a filter field's operator or value dropdown. */
+export interface FlowFilterOption {
+  value: string;
+  /** Display text; defaults to the value. */
+  label?: string;
+}
+
+/** One control row of a branch filter (e.g. "[in the last ▾] [6] [month(s) ▾]"). */
+export interface FlowFilterField {
+  id: string;
+  /** Leading text shown before the controls. */
+  label?: string;
+  /** The value control. Defaults to 'select' when `options` are given, else 'text'. */
+  type?: 'select' | 'number' | 'text';
+  /** Operator choices shown before the value (e.g. "at least" / "in the last" / "is equal to"). */
+  operators?: FlowFilterOption[];
+  /** Value choices for a 'select' field. */
+  options?: FlowFilterOption[];
+  /** Choices for an adjustable trailing unit dropdown (e.g. day(s) / month(s)); shown instead of `suffix`. */
+  units?: FlowFilterOption[];
+  /** Trailing unit text (e.g. "time(s)") when the unit isn't adjustable. */
+  suffix?: string;
+  placeholder?: string;
+  /** Initial value when the filter is added to a condition. */
+  value?: string | number;
+}
+
+/**
+ * Default display labels for well-known operator keys, used when a declaration
+ * provides a value but no text (e.g. `<zn-flow-operator value="gte">`).
+ */
+const OPERATOR_LABELS: Record<string, string> = {
+  eq: 'Is Equal To',
+  neq: 'Is Not Equal To',
+  gt: 'Greater Than',
+  gte: 'Greater Than or Equal To',
+  lt: 'Less Than',
+  lte: 'Less Than or Equal To',
+  is: 'Is',
+  'is-not': 'Is Not',
+  in: 'Is One Of',
+  'not-in': 'Is Not One Of',
+  contains: 'Contains',
+  'not-contains': 'Does Not Contain',
+  'starts-with': 'Starts With',
+  'ends-with': 'Ends With',
+  empty: 'Is Empty',
+  'not-empty': 'Is Not Empty',
+  within: 'Within the Last',
+  before: 'Before the Last',
+  between: 'Between',
+  matches: 'Matches',
+};
+
+/** An operator's display label: its own, a well-known default for its value, else the value itself. */
+export function operatorLabel(option: FlowFilterOption): string {
+  return option.label ?? OPERATOR_LABELS[option.value] ?? option.value;
+}
+
+/** A filter offered by the built-in branch conditions editor. */
+export interface FlowBranchFilter {
+  id: string;
+  label: string;
+  description?: string;
+  fields: FlowFilterField[];
+}
+
+/** One configured condition: a filter plus its per-field operator / value / unit entries. */
+export interface FlowBranchCondition {
+  /** The `FlowBranchFilter` id this condition uses. */
+  filter: string;
+  values: Record<string, { operator?: string; value?: string | number; unit?: string }>;
+}
+
+/**
+ * A branch's full condition set as persisted on the output port's
+ * `data.conditions`: the outer array is OR-ed, each inner group AND-ed.
+ */
+export type FlowBranchConditions = FlowBranchCondition[][];
+
+const NO_CONDITIONS: FlowBranchConditions = [];
+
+/** Read the conditions persisted on an output port (`port.data.conditions`). */
+export function branchConditions(port: FlowPort): FlowBranchConditions {
+  const raw = port.data?.conditions;
+  return Array.isArray(raw) ? (raw as FlowBranchConditions) : NO_CONDITIONS;
+}
+
 /**
  * Describes a kind of node that can be placed on the canvas. Consumers register
  * these with the builder to extend it — the steps panel and inspector are driven
@@ -39,6 +127,12 @@ export interface FlowNodeType {
   outputs?: FlowPort[];
   /** Initial `data` for a freshly placed node. */
   defaultData?: Record<string, unknown>;
+  /**
+   * Filters offered by the built-in branch conditions editor for this type's
+   * output branches (AND/OR groups persisted on the port's `data.conditions`).
+   * Ignored when `renderBranchConfig` is set.
+   */
+  branchFilters?: FlowBranchFilter[];
   /** Renders the inspector body for a selected node of this type. */
   renderConfig?: (node: FlowNodeInstance, update: (data: Record<string, unknown>) => void) => TemplateResult;
   /** Renders the branch editor body (filters / conditions) for one of this type's output branches. */
@@ -129,8 +223,12 @@ export function emptyDragImage(): HTMLImageElement {
 export const NODE_WIDTH = 240;
 export const NODE_HEIGHT = 60;
 
-/** Horizontal spacing between the branches of a multi-output node. */
-export const BRANCH_SPREAD = 200;
+/**
+ * Horizontal spacing between the branches of a multi-output node. Matches the
+ * untangle layer gap (card width + 80) so two sibling children fit side by side
+ * directly under their drops — straight downward wires, no elbows.
+ */
+export const BRANCH_SPREAD = NODE_WIDTH + 80;
 
 // Branch geometry below a node: outputs fork from a stem onto a horizontal bus,
 // and labelled outputs drop from it into a name pill.
@@ -141,6 +239,35 @@ export const PILL_MAX_WIDTH = 240;
 /** Extra pill height per wrapped line (matches the pill's CSS line-height). */
 export const PILL_LINE_HEIGHT = 20;
 
+/** Wire clearance kept between a branch pill's exit and the child card it feeds. */
+const PILL_APPROACH = 20;
+/** The least wire kept above a sole output's pill in a tight gap. */
+const PILL_MIN_STUB = 20;
+
+/**
+ * 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.
+ */
+export function branchPillTop(
+  node: Pick<FlowNodeInstance, 'y'>,
+  pillH: number,
+  child?: Pick<FlowNodeInstance, 'y'>,
+  soleOutput = false
+): number {
+  const bottom = node.y + NODE_HEIGHT;
+  const busY = bottom + BUS_OFFSET;
+  if (child && child.y >= bottom) {
+    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));
+  }
+  return busY + PILL_DROP;
+}
+
 /**
  * Estimated pill box for a branch name: sizes to the text up to the max width,
  * then hard-wraps — the height grows a grid unit per extra line. The pill DOM
@@ -167,6 +294,13 @@ export function snapToGrid(v: number): number {
 // while pills allow tighter packing.
 const CARD_MARGIN = 10;
 const PILL_MARGIN = 4;
+/**
+ * Extra height a pill's footprint claims below itself: room for the wire "+"
+ * between the pill and its child's input port. Keeps drags from compressing a
+ * branch past the point where the "+" fits (with the grid, the tightest
+ * card-to-card gap across a pill becomes 120).
+ */
+const PILL_PLUS_ROOM = 20;
 
 interface Rect {
   x: number;
@@ -187,47 +321,17 @@ function rectsOverlap(a: Rect, b: Rect): boolean {
 export type FlowTypeOf = (type: string) => FlowNodeType | undefined;
 
 /**
- * Canvas x for each of a node's branch drops. A connected branch pulls straight
- * above its child's input — a bend-free wire — when it's the only wire into that
- * input, the child is within the branch's natural fan range, and the position
- * keeps clear of sibling branches; otherwise it fans out source-side.
+ * 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).
  */
-export function branchDropXs(
-  node: FlowNodeInstance,
-  typeOf: FlowTypeOf,
-  nodes: FlowNodeInstance[],
-  connections: FlowConnection[]
-): number[] {
+export function branchDropXs(node: FlowNodeInstance, typeOf: FlowTypeOf): number[] {
   const outputs = nodeOutputs(node, typeOf(node.type));
   const cx = node.x + NODE_WIDTH / 2;
-  const natural = (i: number) =>
-    Math.round(cx + (outputs.length === 1 ? 0 : (i - (outputs.length - 1) / 2) * BRANCH_SPREAD));
-  const MIN_SEP = 170;
-
-  const xs = outputs.map((port, i) => {
-    const spread = natural(i);
-    const conn = connections.find(c => c.source.node === node.id && c.source.port === port.id);
-    const child = conn ? nodes.find(n => n.id === conn.target.node) : undefined;
-    if (!conn || !child) return {x: spread, aligned: false};
-    // Fan-in wires converge on the target — keep their pills on the source side.
-    const fanIn = connections.some(
-      c => c !== conn && c.target.node === conn.target.node && c.target.port === conn.target.port
-    );
-    if (fanIn) return {x: spread, aligned: false};
-    const inputs = nodeInputs(child, typeOf(child.type));
-    const idx = Math.max(inputs.findIndex(p => p.id === conn.target.port), 0);
-    const anchor = portAnchor(child, 'in', idx, inputs.length).x;
-    if (Math.abs(anchor - spread) > BRANCH_SPREAD) return {x: spread, aligned: false};
-    return {x: anchor, aligned: true};
-  });
-
-  // Aligned branches yield back to their fan position rather than crowding siblings.
-  for (let i = 0; i < xs.length; i++) {
-    if (xs[i].aligned && xs.some((o, j) => j !== i && Math.abs(o.x - xs[i].x) < MIN_SEP)) {
-      xs[i] = {x: natural(i), aligned: false};
-    }
-  }
-  return xs.map(o => o.x);
+  return outputs.map((_, i) =>
+    Math.round(cx + (outputs.length === 1 ? 0 : (i - (outputs.length - 1) / 2) * BRANCH_SPREAD)));
 }
 
 /**
@@ -242,15 +346,17 @@ 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, nodes, connections);
+  const xs = branchDropXs(node, typeOf);
   ports.forEach((port, i) => {
     if (!port.label) return;
     const size = pillSize(port.label);
+    const conn = connections.find(c => c.source.node === node.id && c.source.port === port.id);
+    const child = conn ? nodes.find(n => n.id === conn.target.node) : undefined;
     rects.push({
       x: xs[i] - size.w / 2,
-      y: node.y + NODE_HEIGHT + BUS_OFFSET + PILL_DROP,
+      y: branchPillTop(node, size.h, child, ports.length === 1),
       w: size.w,
-      h: size.h,
+      h: size.h + PILL_PLUS_ROOM,
       m: PILL_MARGIN,
     });
   });
@@ -269,6 +375,25 @@ export function nodesCollide(
   return nodeObstacles(b, typeOf, nodes, connections).some(rb => rectsA.some(ra => rectsOverlap(ra, rb)));
 }
 
+/**
+ * Whether any of `node`'s branch pills overlap another node's footprint. A
+ * pill centres between its node and the connected child, so moving the CHILD
+ * moves the pill — drags use this to check the moved node's parents, whose
+ * displaced pills could land on a third node.
+ */
+export function pillsCollide(
+  node: FlowNodeInstance,
+  typeOf: FlowTypeOf,
+  nodes: FlowNodeInstance[],
+  connections: FlowConnection[]
+): boolean {
+  const pills = nodeObstacles(node, typeOf, nodes, connections).slice(1);
+  if (!pills.length) return false;
+  return nodes.some(o =>
+    o.id !== node.id
+    && nodeObstacles(o, typeOf, nodes, connections).some(rb => pills.some(ra => rectsOverlap(ra, rb))));
+}
+
 /** Whether a bare card placed at `pos` would hit any of `node`'s footprint. */
 export function cardCollides(
   pos: { x: number; y: number },