@nodius/layouting 0.1.0 → 0.1.1

package/dist/index.mjs

@@ -6,7 +6,12 @@ function resolveOptions(options) {
     layerSpacing: options?.layerSpacing ?? 60,
     crossingMinimizationIterations: options?.crossingMinimizationIterations ?? 24,
     coordinateOptimizationIterations: options?.coordinateOptimizationIterations ?? 8,
-    edgeMargin: options?.edgeMargin ?? 20
+    edgeMargin: options?.edgeMargin ?? 20,
+    controlWeight: options?.edgeWeights?.control ?? 1,
+    dataWeight: options?.edgeWeights?.data ?? 0.25,
+    packComponents: options?.packComponents ?? true,
+    compoundPadding: options?.compoundPadding ?? 24,
+    onProposal: options?.onProposal
   };
 }
 
@@ -69,7 +74,7 @@ var Graph = class {
     return result;
   }
 };
-function buildGraph(nodes, edges) {
+function buildGraph(nodes, edges, ctx = { controlWeight: 1, dataWeight: 0.25 }) {
   const graph = new Graph();
   for (const node of nodes) {
     graph.addNode({
@@ -81,10 +86,15 @@ function buildGraph(nodes, edges) {
       layer: -1,
       order: -1,
       x: 0,
-      y: 0
+      y: 0,
+      parentId: node.parentId,
+      isCompound: false,
+      isValue: false
     });
   }
   for (const edge of edges) {
+    const kind = edge.kind ?? "control";
+    const defaultWeight = kind === "control" ? ctx.controlWeight : ctx.dataWeight;
     graph.addEdge({
       id: edge.id,
       from: edge.from,
@@ -92,9 +102,34 @@ function buildGraph(nodes, edges) {
       fromHandle: edge.fromHandle,
       toHandle: edge.toHandle,
       reversed: false,
-      originalId: edge.id
+      originalId: edge.id,
+      kind,
+      weight: edge.weight ?? defaultWeight
     });
   }
+  for (const [nodeId, node] of graph.nodes) {
+    const ins = graph.inEdges.get(nodeId);
+    const outs = graph.outEdges.get(nodeId);
+    let hasControl = false;
+    if (ins) {
+      for (const eid of ins) {
+        if (graph.edges.get(eid)?.kind === "control") {
+          hasControl = true;
+          break;
+        }
+      }
+    }
+    if (!hasControl && outs) {
+      for (const eid of outs) {
+        if (graph.edges.get(eid)?.kind === "control") {
+          hasControl = true;
+          break;
+        }
+      }
+    }
+    const incidentCount = (ins?.size ?? 0) + (outs?.size ?? 0);
+    node.isValue = !hasControl && incidentCount > 0;
+  }
   return graph;
 }
 function getHandlePosition(node, handleId) {
@@ -182,28 +217,88 @@ function breakCycles(graph) {
 function assignLayers(graph) {
   const layers = /* @__PURE__ */ new Map();
   const visiting = /* @__PURE__ */ new Set();
-  function computeLayer(nodeId) {
+  function controlLayer(nodeId) {
     if (layers.has(nodeId)) return layers.get(nodeId);
     if (visiting.has(nodeId)) return 0;
+    const node = graph.nodes.get(nodeId);
+    if (!node || node.isValue) return -1;
     visiting.add(nodeId);
-    const preds = graph.predecessors(nodeId);
+    const inEdgeIds = graph.inEdges.get(nodeId);
     let maxPredLayer = -1;
-    for (const pred of preds) {
-      maxPredLayer = Math.max(maxPredLayer, computeLayer(pred));
+    if (inEdgeIds) {
+      for (const eid of inEdgeIds) {
+        const edge = graph.edges.get(eid);
+        if (!edge || edge.kind !== "control") continue;
+        const pred = graph.nodes.get(edge.from);
+        if (!pred || pred.isValue) continue;
+        maxPredLayer = Math.max(maxPredLayer, controlLayer(edge.from));
+      }
     }
     const layer = maxPredLayer + 1;
     layers.set(nodeId, layer);
-    const node = graph.nodes.get(nodeId);
-    if (node) node.layer = layer;
+    node.layer = layer;
     visiting.delete(nodeId);
     return layer;
   }
-  for (const nodeId of graph.nodes.keys()) {
-    computeLayer(nodeId);
+  for (const [nodeId, node] of graph.nodes) {
+    if (!node.isValue) controlLayer(nodeId);
+  }
+  for (const [nodeId, node] of graph.nodes) {
+    if (!node.isValue) continue;
+    const neighborLayers = [];
+    const inEdgeIds = graph.inEdges.get(nodeId);
+    if (inEdgeIds) {
+      for (const eid of inEdgeIds) {
+        const edge = graph.edges.get(eid);
+        if (!edge) continue;
+        const nbr = graph.nodes.get(edge.from);
+        if (nbr && !nbr.isValue && layers.has(edge.from)) {
+          neighborLayers.push(layers.get(edge.from));
+        }
+      }
+    }
+    const outEdgeIds = graph.outEdges.get(nodeId);
+    if (outEdgeIds) {
+      for (const eid of outEdgeIds) {
+        const edge = graph.edges.get(eid);
+        if (!edge) continue;
+        const nbr = graph.nodes.get(edge.to);
+        if (nbr && !nbr.isValue && layers.has(edge.to)) {
+          neighborLayers.push(layers.get(edge.to));
+        }
+      }
+    }
+    let layer;
+    if (neighborLayers.length > 0) {
+      neighborLayers.sort((a, b) => a - b);
+      layer = neighborLayers[Math.floor(neighborLayers.length / 2)];
+    } else {
+      layer = 0;
+    }
+    layers.set(nodeId, layer);
+    node.layer = layer;
   }
-  let maxLayer = 0;
-  for (const layer of layers.values()) {
-    maxLayer = Math.max(maxLayer, layer);
+  for (const [nodeId, node] of graph.nodes) {
+    if (!layers.has(nodeId)) {
+      layers.set(nodeId, 0);
+      node.layer = 0;
+    }
+  }
+  let minLayer = Infinity;
+  let maxLayer = -Infinity;
+  for (const l of layers.values()) {
+    if (l < minLayer) minLayer = l;
+    if (l > maxLayer) maxLayer = l;
+  }
+  if (!isFinite(minLayer)) return [];
+  if (minLayer !== 0) {
+    for (const [id, l] of layers) {
+      const adj = l - minLayer;
+      layers.set(id, adj);
+      const n = graph.nodes.get(id);
+      if (n) n.layer = adj;
+    }
+    maxLayer -= minLayer;
   }
   const layersArray = Array.from({ length: maxLayer + 1 }, () => []);
   for (const [nodeId, layer] of layers) {
@@ -215,6 +310,7 @@ function insertDummyNodes(graph, layers) {
   let dummyCounter = 0;
   const edgesToProcess = [...graph.edges.values()];
   for (const edge of edgesToProcess) {
+    if (edge.kind !== "control") continue;
     const fromNode = graph.nodes.get(edge.from);
     const toNode = graph.nodes.get(edge.to);
     if (!fromNode || !toNode) continue;
@@ -239,7 +335,9 @@ function insertDummyNodes(graph, layers) {
         layer: l,
         order: -1,
         x: 0,
-        y: 0
+        y: 0,
+        isCompound: false,
+        isValue: false
       });
       layers[l].push(dummyId);
       graph.addEdge({
@@ -249,7 +347,9 @@ function insertDummyNodes(graph, layers) {
         fromHandle: prevHandleId,
         toHandle: "in",
         reversed: edge.reversed,
-        originalId: edge.originalId
+        originalId: edge.originalId,
+        kind: edge.kind,
+        weight: edge.weight
       });
       prevNodeId = dummyId;
       prevHandleId = "out";
@@ -261,7 +361,9 @@ function insertDummyNodes(graph, layers) {
       fromHandle: prevHandleId,
       toHandle: edge.toHandle,
       reversed: edge.reversed,
-      originalId: edge.originalId
+      originalId: edge.originalId,
+      kind: edge.kind,
+      weight: edge.weight
     });
   }
   return layers;
@@ -682,6 +784,176 @@ function getOrderSize(node, isHorizontal) {
   return isHorizontal ? node.height : node.width;
 }
 
+// src/algorithms/value-placement.ts
+function placeValueSidecars(graph, layers, options) {
+  const isHorizontal = options.direction === "LR" || options.direction === "RL";
+  const attachments = [];
+  const orphanValues = [];
+  for (const [nodeId, node] of graph.nodes) {
+    if (!node.isValue || node.isDummy) continue;
+    const consumer = findDominantConsumer(graph, nodeId);
+    if (consumer) {
+      attachments.push({ valueId: nodeId, consumerId: consumer });
+    } else {
+      orphanValues.push(nodeId);
+    }
+  }
+  const byConsumer = /* @__PURE__ */ new Map();
+  for (const { valueId, consumerId } of attachments) {
+    const arr = byConsumer.get(consumerId) ?? [];
+    arr.push(valueId);
+    byConsumer.set(consumerId, arr);
+  }
+  for (const [consumerId, vIds] of byConsumer) {
+    const consumer = graph.nodes.get(consumerId);
+    if (!consumer) continue;
+    const { beforeSide, afterSide } = splitValuesBySide(graph, consumerId, vIds, isHorizontal);
+    if (isHorizontal) {
+      const cxCenter = consumer.x + consumer.width / 2;
+      let topEdge = consumer.y;
+      for (const vid of beforeSide) {
+        const v = graph.nodes.get(vid);
+        if (!v) continue;
+        v.y = topEdge - options.nodeSpacing - v.height;
+        v.x = cxCenter - v.width / 2;
+        topEdge = v.y;
+      }
+      let bottomEdge = consumer.y + consumer.height;
+      for (const vid of afterSide) {
+        const v = graph.nodes.get(vid);
+        if (!v) continue;
+        v.y = bottomEdge + options.nodeSpacing;
+        v.x = cxCenter - v.width / 2;
+        bottomEdge = v.y + v.height;
+      }
+    } else {
+      const cyCenter = consumer.y + consumer.height / 2;
+      let leftEdge = consumer.x;
+      for (const vid of beforeSide) {
+        const v = graph.nodes.get(vid);
+        if (!v) continue;
+        v.x = leftEdge - options.nodeSpacing - v.width;
+        v.y = cyCenter - v.height / 2;
+        leftEdge = v.x;
+      }
+      let rightEdge = consumer.x + consumer.width;
+      for (const vid of afterSide) {
+        const v = graph.nodes.get(vid);
+        if (!v) continue;
+        v.x = rightEdge + options.nodeSpacing;
+        v.y = cyCenter - v.height / 2;
+        rightEdge = v.x + v.width;
+      }
+    }
+  }
+  let orphanX = 0, orphanY = 0;
+  for (const orphanId of orphanValues) {
+    const v = graph.nodes.get(orphanId);
+    if (!v) continue;
+    v.x = orphanX;
+    v.y = orphanY;
+    if (isHorizontal) orphanX += v.width + options.nodeSpacing;
+    else orphanY += v.height + options.nodeSpacing;
+  }
+}
+function findDominantConsumer(graph, valueId) {
+  const counts = /* @__PURE__ */ new Map();
+  const outs = graph.outEdges.get(valueId);
+  if (outs) {
+    for (const eid of outs) {
+      const edge = graph.edges.get(eid);
+      if (!edge) continue;
+      const other = graph.nodes.get(edge.to);
+      if (other && !other.isValue && !other.isDummy) {
+        counts.set(edge.to, (counts.get(edge.to) ?? 0) + 1);
+      }
+    }
+  }
+  const ins = graph.inEdges.get(valueId);
+  if (ins) {
+    for (const eid of ins) {
+      const edge = graph.edges.get(eid);
+      if (!edge) continue;
+      const other = graph.nodes.get(edge.from);
+      if (other && !other.isValue && !other.isDummy) {
+        counts.set(edge.from, (counts.get(edge.from) ?? 0) + 1);
+      }
+    }
+  }
+  let bestId = null;
+  let bestCount = -1;
+  for (const [id, count] of counts) {
+    if (count > bestCount || count === bestCount && bestId !== null && id < bestId) {
+      bestId = id;
+      bestCount = count;
+    }
+  }
+  return bestId;
+}
+function splitValuesBySide(graph, consumerId, valueIds, isHorizontal) {
+  const consumer = graph.nodes.get(consumerId);
+  if (!consumer) return { beforeSide: [...valueIds].sort(), afterSide: [] };
+  const slots = [];
+  for (const vId of valueIds) {
+    let side = "neutral";
+    let offset = 0.5;
+    const inspectHandle = (handleId) => {
+      if (!handleId) return;
+      const handle = consumer.handles.find((h) => h.id === handleId);
+      if (!handle) return;
+      offset = handle.offset ?? 0.5;
+      if (isHorizontal) {
+        if (handle.position === "top") side = "before";
+        else if (handle.position === "bottom") side = "after";
+      } else {
+        if (handle.position === "left") side = "before";
+        else if (handle.position === "right") side = "after";
+      }
+    };
+    const outs = graph.outEdges.get(vId);
+    if (outs) for (const eid of outs) {
+      const e = graph.edges.get(eid);
+      if (e && e.to === consumerId) {
+        inspectHandle(e.toHandle);
+        break;
+      }
+    }
+    if (side === "neutral") {
+      const ins = graph.inEdges.get(vId);
+      if (ins) for (const eid of ins) {
+        const e = graph.edges.get(eid);
+        if (e && e.from === consumerId) {
+          inspectHandle(e.fromHandle);
+          break;
+        }
+      }
+    }
+    slots.push({ id: vId, side, offset });
+  }
+  const before = slots.filter((s) => s.side === "before");
+  const after = slots.filter((s) => s.side === "after");
+  const neutral = slots.filter((s) => s.side === "neutral");
+  for (const n of neutral) {
+    if (before.length <= after.length) before.push(n);
+    else after.push(n);
+  }
+  const cmp = (a, b) => a.offset - b.offset || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  before.sort(cmp);
+  after.sort(cmp);
+  return {
+    beforeSide: before.map((s) => s.id),
+    afterSide: after.map((s) => s.id)
+  };
+}
+function railLayers(layers, graph) {
+  return layers.map(
+    (layer) => layer.filter((id) => {
+      const n = graph.nodes.get(id);
+      return n && !n.isValue;
+    })
+  );
+}
+
 // src/algorithms/edge-routing.ts
 function routeEdges(graph, direction, edgeMargin) {
   const chains = collectEdgeChains(graph);
@@ -732,7 +1004,8 @@ function collectEdgeChains(graph) {
       fromHandle: edge.fromHandle,
       toHandle: currentEdge.toHandle,
       dummyNodes,
-      reversed: edge.reversed
+      reversed: edge.reversed,
+      kind: edge.kind
     });
   }
   return chains;
@@ -777,7 +1050,8 @@ function routeChain(graph, chain, direction, margin) {
     to: actualTo,
     fromHandle: actualFromHandle,
     toHandle: actualToHandle,
-    points
+    points,
+    kind: chain.kind
   };
 }
 function makeOrthogonal(points, direction) {
@@ -851,21 +1125,292 @@ function getDefaultTargetSide(direction) {
   }
 }
 
+// src/algorithms/component-packing.ts
+function packComponents(nodes, edges, options) {
+  if (nodes.length === 0) return;
+  const idToNode = /* @__PURE__ */ new Map();
+  for (const n of nodes) idToNode.set(n.id, n);
+  const rootOf = /* @__PURE__ */ new Map();
+  function topAncestor(id) {
+    if (rootOf.has(id)) return rootOf.get(id);
+    const n = idToNode.get(id);
+    if (!n || !n.parentId || !idToNode.has(n.parentId)) {
+      rootOf.set(id, id);
+      return id;
+    }
+    const r = topAncestor(n.parentId);
+    rootOf.set(id, r);
+    return r;
+  }
+  for (const n of nodes) topAncestor(n.id);
+  const parent = /* @__PURE__ */ new Map();
+  function find(x) {
+    let cur = x;
+    while (parent.get(cur) !== cur) {
+      const p = parent.get(cur);
+      parent.set(cur, parent.get(p));
+      cur = parent.get(cur);
+    }
+    return cur;
+  }
+  function union(a, b) {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb) parent.set(ra, rb);
+  }
+  for (const n of nodes) parent.set(topAncestor(n.id), topAncestor(n.id));
+  for (const e of edges) {
+    const ra = topAncestor(e.from);
+    const rb = topAncestor(e.to);
+    if (idToNode.has(ra) && idToNode.has(rb)) union(ra, rb);
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    const root = topAncestor(n.id);
+    const comp = find(root);
+    const arr = groups.get(comp) ?? [];
+    arr.push(n);
+    groups.set(comp, arr);
+  }
+  if (groups.size <= 1) return;
+  const isHorizontal = options.direction === "LR" || options.direction === "RL";
+  const edgesByComp = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    const root = topAncestor(e.from);
+    const comp = find(root);
+    const arr = edgesByComp.get(comp) ?? [];
+    arr.push(e);
+    edgesByComp.set(comp, arr);
+  }
+  const boxes = [];
+  for (const [compId, group] of groups) {
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const n of group) {
+      if (n.x < minX) minX = n.x;
+      if (n.y < minY) minY = n.y;
+      if (n.x + n.width > maxX) maxX = n.x + n.width;
+      if (n.y + n.height > maxY) maxY = n.y + n.height;
+    }
+    const compEdges = edgesByComp.get(compId) ?? [];
+    for (const e of compEdges) {
+      for (const p of e.points) {
+        if (p.x < minX) minX = p.x;
+        if (p.y < minY) minY = p.y;
+        if (p.x > maxX) maxX = p.x;
+        if (p.y > maxY) maxY = p.y;
+      }
+    }
+    boxes.push({ id: compId, nodes: group, edges: compEdges, minX, minY, maxX, maxY });
+  }
+  boxes.sort((a, b) => {
+    const sizeA = isHorizontal ? a.maxX - a.minX : a.maxY - a.minY;
+    const sizeB = isHorizontal ? b.maxX - b.minX : b.maxY - b.minY;
+    return sizeB - sizeA;
+  });
+  const gap = options.layerSpacing;
+  let cursor = 0;
+  for (const box of boxes) {
+    if (isHorizontal) {
+      const dy = cursor - box.minY;
+      const dx = -box.minX;
+      for (const n of box.nodes) {
+        n.x += dx;
+        n.y += dy;
+        for (const h of n.handles) {
+          h.x += dx;
+          h.y += dy;
+        }
+      }
+      for (const e of box.edges) {
+        for (const p of e.points) {
+          p.x += dx;
+          p.y += dy;
+        }
+      }
+      cursor += box.maxY - box.minY + gap;
+    } else {
+      const dx = cursor - box.minX;
+      const dy = -box.minY;
+      for (const n of box.nodes) {
+        n.x += dx;
+        n.y += dy;
+        for (const h of n.handles) {
+          h.x += dx;
+          h.y += dy;
+        }
+      }
+      for (const e of box.edges) {
+        for (const p of e.points) {
+          p.x += dx;
+          p.y += dy;
+        }
+      }
+      cursor += box.maxX - box.minX + gap;
+    }
+  }
+}
+
+// src/proposals.ts
+function applyRotationProposals(input, options) {
+  if (!options.onProposal) return input;
+  const nodeIndex = new Map(input.nodes.map((n) => [n.id, n]));
+  const newNodes = input.nodes.map((node) => {
+    const role = classifyNode(node, input.edges);
+    const expected = expectedSidesFor(node, role, input.edges, nodeIndex, options.direction);
+    const proposal = computeProposal(node, expected, options.direction, role);
+    if (!proposal) return node;
+    const accepted = options.onProposal(proposal);
+    return accepted ?? node;
+  });
+  return { nodes: newNodes, edges: input.edges };
+}
+function classifyNode(node, edges) {
+  const incident = edges.filter((e) => e.from === node.id || e.to === node.id);
+  if (incident.length === 0) return { kind: "isolated" };
+  const allData = incident.every((e) => (e.kind ?? "control") === "data");
+  if (!allData) return { kind: "rail" };
+  for (const e of incident) {
+    const consumerId = e.from === node.id ? e.to : e.from;
+    const consumerHandleId = e.from === node.id ? e.toHandle : e.fromHandle;
+    const sideHint = sideHintFromHandle(
+      consumerId,
+      consumerHandleId,
+      edges,
+      /* recursing */
+      false
+    );
+    if (sideHint) return { kind: "value", consumerSide: sideHint };
+  }
+  return { kind: "value", consumerSide: null };
+}
+function sideHintFromHandle(_consumerId, _handleId, _edges, _recursing) {
+  return null;
+}
+function expectedSidesFor(node, role, edges, index, direction) {
+  if (role.kind === "isolated" || role.kind === "rail") {
+    return { input: inputSideFor(direction), output: outputSideFor(direction) };
+  }
+  const consumerHandleSide = findConsumerHandleSide(node, edges, index);
+  if (!consumerHandleSide) {
+    return { input: inputSideFor(direction), output: outputSideFor(direction) };
+  }
+  const isVerticalFlow = direction === "TB" || direction === "BT";
+  let outputSide;
+  if (isVerticalFlow) {
+    if (consumerHandleSide === "left") outputSide = "right";
+    else if (consumerHandleSide === "right") outputSide = "left";
+    else outputSide = "right";
+  } else {
+    if (consumerHandleSide === "top") outputSide = "bottom";
+    else if (consumerHandleSide === "bottom") outputSide = "top";
+    else outputSide = "bottom";
+  }
+  return { input: outputSide, output: outputSide };
+}
+function findConsumerHandleSide(value, edges, index) {
+  for (const e of edges) {
+    const isFromValue = e.from === value.id;
+    const isToValue = e.to === value.id;
+    if (!isFromValue && !isToValue) continue;
+    const consumerId = isFromValue ? e.to : e.from;
+    const consumer = index.get(consumerId);
+    if (!consumer) continue;
+    const consumerHandleId = isFromValue ? e.toHandle : e.fromHandle;
+    const consumerHandle = consumer.handles.find((h) => h.id === consumerHandleId);
+    if (consumerHandle) return consumerHandle.position;
+  }
+  return null;
+}
+function computeProposal(node, expected, direction, role) {
+  if (node.handles.length === 0) return null;
+  const currentScore = score(node.handles, expected);
+  if (currentScore.matchRatio >= 1) return null;
+  const candidates = [];
+  for (const rot of [90, -90, 180]) {
+    const rotated = rotateHandles(node.handles, rot);
+    candidates.push({ rotation: rot, score: score(rotated, expected) });
+  }
+  candidates.sort((a, b) => b.score.matchRatio - a.score.matchRatio);
+  const best = candidates[0];
+  if (best.score.matchRatio <= currentScore.matchRatio) return null;
+  return buildProposal(node, best.rotation, currentScore, best.score, direction, expected, role);
+}
+function buildProposal(node, rotation, current, proposedScore, direction, expected, role) {
+  const proposed = { ...node, handles: rotateHandles(node.handles, rotation) };
+  const roleDesc = role.kind === "value" ? `value node should face ${expected.output} (its sidecar lands opposite the consumer's handle)` : `direction ${direction} expects inputs on ${expected.input} and outputs on ${expected.output}`;
+  return {
+    type: "rotate",
+    nodeId: node.id,
+    current: node,
+    proposed,
+    rotation,
+    reason: `${roleDesc}; ${current.matched}/${current.total} handles match, ${proposedScore.matched}/${proposedScore.total} after rotation`
+  };
+}
+function inputSideFor(direction) {
+  switch (direction) {
+    case "TB":
+      return "top";
+    case "BT":
+      return "bottom";
+    case "LR":
+      return "left";
+    case "RL":
+      return "right";
+  }
+}
+function outputSideFor(direction) {
+  switch (direction) {
+    case "TB":
+      return "bottom";
+    case "BT":
+      return "top";
+    case "LR":
+      return "right";
+    case "RL":
+      return "left";
+  }
+}
+function score(handles, expected) {
+  let matched = 0;
+  let total = 0;
+  for (const h of handles) {
+    total++;
+    if (h.type === "input" && h.position === expected.input) matched++;
+    else if (h.type === "output" && h.position === expected.output) matched++;
+  }
+  return { matched, total, matchRatio: total === 0 ? 1 : matched / total };
+}
+function rotateHandles(handles, rot) {
+  const rotateSide = (s) => {
+    if (rot === 180) {
+      return s === "top" ? "bottom" : s === "bottom" ? "top" : s === "left" ? "right" : "left";
+    }
+    if (rot === 90) {
+      return s === "top" ? "right" : s === "right" ? "bottom" : s === "bottom" ? "left" : "top";
+    }
+    return s === "top" ? "left" : s === "left" ? "bottom" : s === "bottom" ? "right" : "top";
+  };
+  return handles.map((h) => ({ ...h, position: rotateSide(h.position) }));
+}
+
 // src/layout.ts
+var COMPOUND_HEADER = 28;
 function layout(input, options) {
   const resolved = resolveOptions(options);
-  const graph = buildGraph(input.nodes, input.edges);
-  return computeLayout(graph, resolved);
+  if (input.nodes.length === 0) return { nodes: [], edges: [] };
+  const adjusted = applyRotationProposals(input, resolved);
+  return layoutCompound(adjusted, resolved);
 }
 function computeLayout(graph, options) {
-  if (graph.nodes.size === 0) {
-    return { nodes: [], edges: [] };
-  }
+  if (graph.nodes.size === 0) return { nodes: [], edges: [] };
   breakCycles(graph);
   let layers = assignLayers(graph);
   layers = insertDummyNodes(graph, layers);
-  layers = minimizeCrossings(graph, layers, options.crossingMinimizationIterations);
-  assignCoordinates(graph, layers, options);
+  let rail = railLayers(layers, graph);
+  rail = minimizeCrossings(graph, rail, options.crossingMinimizationIterations);
+  assignCoordinates(graph, rail, options);
+  placeValueSidecars(graph, layers, options);
   const routedEdges = routeEdges(graph, options.direction, options.edgeMargin);
   return buildResult(graph, routedEdges);
 }
@@ -876,13 +1421,7 @@ function buildResult(graph, routedEdges) {
     if (node.isDummy) continue;
     const handles = node.handles.map((h) => {
       const pos = getHandlePosition(node, h.id);
-      return {
-        id: h.id,
-        type: h.type,
-        position: h.position,
-        x: pos.x,
-        y: pos.y
-      };
+      return { id: h.id, type: h.type, position: h.position, x: pos.x, y: pos.y };
     });
     nodes.push({
       id: node.id,
@@ -890,7 +1429,8 @@ function buildResult(graph, routedEdges) {
       y: node.y,
       width: node.width,
       height: node.height,
-      handles
+      handles,
+      parentId: node.parentId
     });
   }
   for (const route of routedEdges) {
@@ -900,11 +1440,146 @@ function buildResult(graph, routedEdges) {
       to: route.to,
       fromHandle: route.fromHandle,
       toHandle: route.toHandle,
-      points: route.points
+      points: route.points,
+      kind: route.kind
     });
   }
   return { nodes, edges };
 }
+function layoutCompound(input, options) {
+  const nodeMap = new Map(input.nodes.map((n) => [n.id, n]));
+  const childrenByParent = /* @__PURE__ */ new Map();
+  const rootNodes = [];
+  for (const n of input.nodes) {
+    if (n.parentId && nodeMap.has(n.parentId)) {
+      const arr = childrenByParent.get(n.parentId) ?? [];
+      arr.push(n);
+      childrenByParent.set(n.parentId, arr);
+    } else {
+      rootNodes.push(n);
+    }
+  }
+  const compoundIds = new Set(childrenByParent.keys());
+  const depthCache = /* @__PURE__ */ new Map();
+  function depthOf(id) {
+    if (depthCache.has(id)) return depthCache.get(id);
+    const n = nodeMap.get(id);
+    const d = n?.parentId && nodeMap.has(n.parentId) ? depthOf(n.parentId) + 1 : 0;
+    depthCache.set(id, d);
+    return d;
+  }
+  for (const n of input.nodes) depthOf(n.id);
+  const sortedCompounds = [...compoundIds].sort((a, b) => depthOf(b) - depthOf(a));
+  const subLayouts = /* @__PURE__ */ new Map();
+  const compoundSize = /* @__PURE__ */ new Map();
+  for (const compoundId of sortedCompounds) {
+    const children = childrenByParent.get(compoundId) ?? [];
+    if (children.length === 0) continue;
+    const childIdSet = new Set(children.map((c) => c.id));
+    const subEdges = input.edges.filter((e) => childIdSet.has(e.from) && childIdSet.has(e.to));
+    const sizedChildren = children.map((c) => {
+      const sz = compoundSize.get(c.id);
+      return sz ? { ...c, width: sz.width, height: sz.height } : c;
+    });
+    const subOptions = { ...options, packComponents: false };
+    const subInput = { nodes: sizedChildren.map(stripParent), edges: subEdges };
+    const subResult = layoutFlat(subInput, subOptions);
+    subLayouts.set(compoundId, subResult);
+    const bbox = computeBoundingBox(subResult.nodes);
+    const innerW = bbox.width + options.compoundPadding * 2;
+    const innerH = bbox.height + options.compoundPadding * 2 + COMPOUND_HEADER;
+    const original = nodeMap.get(compoundId);
+    compoundSize.set(compoundId, {
+      width: Math.max(innerW, original.width),
+      height: Math.max(innerH, original.height)
+    });
+  }
+  const sizedRootNodes = rootNodes.map((n) => {
+    const sz = compoundSize.get(n.id);
+    return sz ? { ...n, width: sz.width, height: sz.height } : n;
+  });
+  const rootIdSet = new Set(rootNodes.map((n) => n.id));
+  const rootEdges = input.edges.filter((e) => {
+    return rootIdSet.has(e.from) && rootIdSet.has(e.to);
+  });
+  const rootResult = layoutFlat({ nodes: sizedRootNodes.map(stripParent), edges: rootEdges }, options);
+  const finalNodes = [];
+  const finalEdges = [];
+  for (const n of rootResult.nodes) {
+    const wasCompound = compoundIds.has(n.id);
+    finalNodes.push({
+      ...n,
+      parentId: nodeMap.get(n.id)?.parentId
+    });
+    if (wasCompound) {
+      placeCompoundChildren(n, (compoundId) => subLayouts.get(compoundId), finalNodes, finalEdges, options, nodeMap);
+    }
+  }
+  finalEdges.push(...rootResult.edges);
+  if (options.packComponents) {
+    packComponents(finalNodes, finalEdges, options);
+  }
+  return { nodes: finalNodes, edges: finalEdges };
+}
+function placeCompoundChildren(parent, getSub, finalNodes, finalEdges, options, nodeMap) {
+  const sub = getSub(parent.id);
+  if (!sub) return;
+  const bbox = computeBoundingBox(sub.nodes);
+  const dx = parent.x + options.compoundPadding - bbox.minX;
+  const dy = parent.y + options.compoundPadding + COMPOUND_HEADER - bbox.minY;
+  const availableW = parent.width - options.compoundPadding * 2;
+  const slackX = (availableW - bbox.width) / 2;
+  const availableH = parent.height - options.compoundPadding * 2 - COMPOUND_HEADER;
+  const slackY = (availableH - bbox.height) / 2;
+  const cx = dx + Math.max(0, slackX);
+  const cy = dy + Math.max(0, slackY);
+  for (const child of sub.nodes) {
+    const placed = {
+      ...child,
+      x: child.x + cx,
+      y: child.y + cy,
+      handles: child.handles.map((h) => ({ ...h, x: h.x + cx, y: h.y + cy })),
+      parentId: nodeMap.get(child.id)?.parentId ?? parent.id
+    };
+    finalNodes.push(placed);
+    if (getSub(child.id)) {
+      placeCompoundChildren(placed, getSub, finalNodes, finalEdges, options, nodeMap);
+    }
+  }
+  for (const edge of sub.edges) {
+    finalEdges.push({
+      ...edge,
+      points: edge.points.map((p) => ({ x: p.x + cx, y: p.y + cy }))
+    });
+  }
+}
+function stripParent(n) {
+  const { parentId: _ignored, ...rest } = n;
+  return rest;
+}
+function layoutFlat(input, options) {
+  const graph = buildGraph(input.nodes, input.edges, {
+    controlWeight: options.controlWeight,
+    dataWeight: options.dataWeight
+  });
+  return computeLayout(graph, options);
+}
+function computeBoundingBox(nodes) {
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const n of nodes) {
+    if (n.x < minX) minX = n.x;
+    if (n.y < minY) minY = n.y;
+    if (n.x + n.width > maxX) maxX = n.x + n.width;
+    if (n.y + n.height > maxY) maxY = n.y + n.height;
+  }
+  if (!isFinite(minX)) {
+    minX = 0;
+    minY = 0;
+    maxX = 0;
+    maxY = 0;
+  }
+  return { minX, minY, maxX, maxY, width: maxX - minX, height: maxY - minY };
+}
 
 // src/incremental.ts
 var IncrementalLayout = class {
@@ -913,82 +1588,40 @@ var IncrementalLayout = class {
     this.inputEdges = /* @__PURE__ */ new Map();
     this.lastResult = null;
     this.nodePositions = /* @__PURE__ */ new Map();
-    this.options = resolveOptions(options);
+    this.options = options;
+    this.resolvedOptions = resolveOptions(options);
   }
-  /**
-   * Set the full graph and compute a complete layout.
-   */
   setGraph(input) {
     this.inputNodes.clear();
     this.inputEdges.clear();
-    for (const node of input.nodes) {
-      this.inputNodes.set(node.id, node);
-    }
-    for (const edge of input.edges) {
-      this.inputEdges.set(edge.id, edge);
-    }
+    for (const node of input.nodes) this.inputNodes.set(node.id, node);
+    for (const edge of input.edges) this.inputEdges.set(edge.id, edge);
     return this.recompute();
   }
-  /**
-   * Add nodes and edges incrementally.
-   * Attempts to minimize layout changes for existing nodes.
-   */
   addNodes(nodes, edges) {
-    for (const node of nodes) {
-      this.inputNodes.set(node.id, node);
-    }
-    if (edges) {
-      for (const edge of edges) {
-        this.inputEdges.set(edge.id, edge);
-      }
-    }
-    return this.recomputeIncremental(
-      new Set(nodes.map((n) => n.id)),
-      new Set(edges?.map((e) => e.id) || [])
-    );
+    for (const node of nodes) this.inputNodes.set(node.id, node);
+    if (edges) for (const edge of edges) this.inputEdges.set(edge.id, edge);
+    return this.recomputeWithStability(new Set(nodes.map((n) => n.id)));
   }
-  /**
-   * Remove nodes (and their connected edges) from the layout.
-   */
   removeNodes(nodeIds) {
     const removedSet = new Set(nodeIds);
-    for (const id of nodeIds) {
-      this.inputNodes.delete(id);
-    }
+    for (const id of nodeIds) this.inputNodes.delete(id);
     for (const [edgeId, edge] of this.inputEdges) {
       if (removedSet.has(edge.from) || removedSet.has(edge.to)) {
         this.inputEdges.delete(edgeId);
       }
     }
-    for (const id of nodeIds) {
-      this.nodePositions.delete(id);
-    }
+    for (const id of nodeIds) this.nodePositions.delete(id);
     return this.recompute();
   }
-  /**
-   * Add edges between existing nodes.
-   */
   addEdges(edges) {
-    for (const edge of edges) {
-      this.inputEdges.set(edge.id, edge);
-    }
-    return this.recomputeIncremental(
-      /* @__PURE__ */ new Set(),
-      new Set(edges.map((e) => e.id))
-    );
+    for (const edge of edges) this.inputEdges.set(edge.id, edge);
+    return this.recomputeWithStability(/* @__PURE__ */ new Set());
   }
-  /**
-   * Remove edges from the layout.
-   */
   removeEdges(edgeIds) {
-    for (const id of edgeIds) {
-      this.inputEdges.delete(id);
-    }
+    for (const id of edgeIds) this.inputEdges.delete(id);
     return this.recompute();
   }
-  /**
-   * Get the current layout result.
-   */
   getResult() {
     return this.lastResult;
   }
@@ -997,42 +1630,48 @@ var IncrementalLayout = class {
       nodes: [...this.inputNodes.values()],
       edges: [...this.inputEdges.values()]
     };
-    const graph = buildGraph(input.nodes, input.edges);
-    this.lastResult = computeLayout(graph, this.options);
+    this.lastResult = layout(input, this.options);
     this.cachePositions();
     return this.lastResult;
   }
-  recomputeIncremental(newNodeIds, newEdgeIds) {
+  recomputeWithStability(newNodeIds) {
     const input = {
       nodes: [...this.inputNodes.values()],
       edges: [...this.inputEdges.values()]
     };
-    const graph = buildGraph(input.nodes, input.edges);
-    breakCycles(graph);
-    let layers = assignLayers(graph);
-    layers = insertDummyNodes(graph, layers);
-    layers = minimizeCrossings(graph, layers, this.options.crossingMinimizationIterations);
-    assignCoordinates(graph, layers, this.options);
-    this.applyStability(graph, newNodeIds);
-    const routedEdges = routeEdges(graph, this.options.direction, this.options.edgeMargin);
-    this.lastResult = this.buildResult(graph, routedEdges);
+    const fresh = layout(input, this.options);
+    this.lastResult = this.applyStability(fresh, newNodeIds);
     this.cachePositions();
     return this.lastResult;
   }
   /**
-   * Apply stability: blend new positions with old positions for existing nodes.
-   * This reduces visual disruption when adding new nodes.
+   * Blend the freshly computed positions with the previous ones, so existing
+   * nodes don't jump too far when a small change happens.
    */
-  applyStability(graph, newNodeIds) {
-    if (this.nodePositions.size === 0) return;
+  applyStability(fresh, newNodeIds) {
+    if (this.nodePositions.size === 0) return fresh;
     const STABILITY_WEIGHT = 0.3;
-    for (const [nodeId, node] of graph.nodes) {
-      if (node.isDummy || newNodeIds.has(nodeId)) continue;
-      const oldPos = this.nodePositions.get(nodeId);
-      if (!oldPos) continue;
-      node.x = node.x * (1 - STABILITY_WEIGHT) + oldPos.x * STABILITY_WEIGHT;
-      node.y = node.y * (1 - STABILITY_WEIGHT) + oldPos.y * STABILITY_WEIGHT;
-    }
+    const blended = {
+      nodes: fresh.nodes.map((n) => {
+        if (newNodeIds.has(n.id)) return n;
+        const old = this.nodePositions.get(n.id);
+        if (!old) return n;
+        const dx = old.x - n.x;
+        const dy = old.y - n.y;
+        const x = n.x + dx * STABILITY_WEIGHT;
+        const y = n.y + dy * STABILITY_WEIGHT;
+        const ddx = x - n.x;
+        const ddy = y - n.y;
+        return {
+          ...n,
+          x,
+          y,
+          handles: n.handles.map((h) => ({ ...h, x: h.x + ddx, y: h.y + ddy }))
+        };
+      }),
+      edges: fresh.edges
+    };
+    return blended;
   }
   cachePositions() {
     if (!this.lastResult) return;
@@ -1041,46 +1680,160 @@ var IncrementalLayout = class {
       this.nodePositions.set(node.id, { x: node.x, y: node.y });
     }
   }
-  buildResult(graph, routedEdges) {
-    const nodes = [];
-    const edges = [];
-    for (const [, node] of graph.nodes) {
-      if (node.isDummy) continue;
-      const handles = node.handles.map((h) => {
-        const pos = getHandlePosition(node, h.id);
-        return {
-          id: h.id,
-          type: h.type,
-          position: h.position,
-          x: pos.x,
-          y: pos.y
-        };
-      });
-      nodes.push({
-        id: node.id,
-        x: node.x,
-        y: node.y,
-        width: node.width,
-        height: node.height,
-        handles
-      });
+};
+
+// src/debug.ts
+function printLayout(result, options = {}) {
+  const lines = [];
+  const { nodes, edges } = result;
+  if (nodes.length === 0) return "(empty layout)";
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const n of nodes) {
+    if (n.x < minX) minX = n.x;
+    if (n.y < minY) minY = n.y;
+    if (n.x + n.width > maxX) maxX = n.x + n.width;
+    if (n.y + n.height > maxY) maxY = n.y + n.height;
+  }
+  lines.push(`=== layout ${nodes.length} nodes, ${edges.length} edges ===`);
+  lines.push(`bbox: x=[${minX.toFixed(0)}..${maxX.toFixed(0)}] y=[${minY.toFixed(0)}..${maxY.toFixed(0)}] (${(maxX - minX).toFixed(0)} x ${(maxY - minY).toFixed(0)})`);
+  const byY = [...nodes].sort((a, b) => a.y - b.y || a.x - b.x);
+  const bands = [];
+  for (const n of byY) {
+    const placed = bands.find((b) => Math.abs(b[0].y - n.y) < 1);
+    if (placed) placed.push(n);
+    else bands.push([n]);
+  }
+  lines.push("");
+  lines.push("--- Y bands ---");
+  for (const band of bands) {
+    const sorted = [...band].sort((a, b) => a.x - b.x);
+    const summary = sorted.map((n) => {
+      const p = n.parentId ? `[${n.parentId}/]` : "";
+      return `${p}${n.id}@(${n.x.toFixed(0)},${n.y.toFixed(0)} ${n.width}x${n.height})`;
+    }).join("  ");
+    lines.push(`  y=${band[0].y.toFixed(0).padStart(4)} :  ${summary}`);
+  }
+  const byParent = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    const key = n.parentId;
+    const arr = byParent.get(key) ?? [];
+    arr.push(n);
+    byParent.set(key, arr);
+  }
+  const compoundIds = /* @__PURE__ */ new Set();
+  for (const k of byParent.keys()) {
+    if (k && nodes.find((n) => n.id === k)) compoundIds.add(k);
+  }
+  if (compoundIds.size > 0) {
+    let printSubtree2 = function(id, depth) {
+      const children = byParent.get(id) ?? [];
+      for (const c of children) {
+        const prefix = "  ".repeat(depth);
+        const tag = compoundIds.has(c.id) ? " (compound)" : "";
+        lines.push(`${prefix}- ${c.id}${tag}  bbox=(${c.x.toFixed(0)},${c.y.toFixed(0)})..(${(c.x + c.width).toFixed(0)},${(c.y + c.height).toFixed(0)})`);
+        if (compoundIds.has(c.id)) printSubtree2(c.id, depth + 1);
+      }
+    };
+    var printSubtree = printSubtree2;
+    lines.push("");
+    lines.push("--- hierarchy ---");
+    printSubtree2(void 0, 0);
+  }
+  lines.push("");
+  lines.push("--- edges ---");
+  for (const e of edges) {
+    const head = e.points[0];
+    const tail = e.points[e.points.length - 1];
+    lines.push(`  [${e.kind}] ${e.from}.${e.fromHandle} \u2192 ${e.to}.${e.toHandle}  (${head.x.toFixed(0)},${head.y.toFixed(0)}) \u2192 (${tail.x.toFixed(0)},${tail.y.toFixed(0)})  via ${e.points.length} pts`);
+  }
+  const overlaps = findOverlaps(nodes);
+  if (overlaps.length > 0) {
+    lines.push("");
+    lines.push("--- OVERLAPS (problem!) ---");
+    for (const o of overlaps) {
+      lines.push(`  ${o.a} overlaps ${o.b}`);
     }
-    for (const route of routedEdges) {
-      edges.push({
-        id: route.id,
-        from: route.from,
-        to: route.to,
-        fromHandle: route.fromHandle,
-        toHandle: route.toHandle,
-        points: route.points
-      });
+  }
+  if (options.grid !== false) {
+    lines.push("");
+    lines.push("--- ASCII grid ---");
+    lines.push(asciiGrid(nodes, edges, options));
+  }
+  return lines.join("\n");
+}
+function findOverlaps(nodes) {
+  const out = [];
+  const compoundIds = /* @__PURE__ */ new Set();
+  for (const n of nodes) if (n.parentId) compoundIds.add(n.parentId);
+  for (let i = 0; i < nodes.length; i++) {
+    for (let j = i + 1; j < nodes.length; j++) {
+      const a = nodes[i];
+      const b = nodes[j];
+      if (a.id === b.parentId || b.id === a.parentId) continue;
+      const overlapX = a.x < b.x + b.width && b.x < a.x + a.width;
+      const overlapY = a.y < b.y + b.height && b.y < a.y + a.height;
+      if (overlapX && overlapY) {
+        out.push({ a: a.id, b: b.id });
+      }
     }
-    return { nodes, edges };
   }
-};
+  return out;
+}
+function asciiGrid(nodes, edges, options) {
+  if (nodes.length === 0) return "";
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const n of nodes) {
+    if (n.x < minX) minX = n.x;
+    if (n.y < minY) minY = n.y;
+    if (n.x + n.width > maxX) maxX = n.x + n.width;
+    if (n.y + n.height > maxY) maxY = n.y + n.height;
+  }
+  for (const e of edges) for (const p of e.points) {
+    if (p.x < minX) minX = p.x;
+    if (p.y < minY) minY = p.y;
+    if (p.x > maxX) maxX = p.x;
+    if (p.y > maxY) maxY = p.y;
+  }
+  const targetW = options.gridWidth ?? 80;
+  const layoutW = Math.max(1, maxX - minX);
+  const layoutH = Math.max(1, maxY - minY);
+  const scaleX = options.gridScale ?? targetW / layoutW;
+  const scaleY = scaleX * 0.5;
+  const w = Math.max(1, Math.ceil(layoutW * scaleX) + 1);
+  const h = Math.max(1, Math.ceil(layoutH * scaleY) + 1);
+  if (h > 80) return "(grid suppressed: too tall \u2014 pass {grid:false} to skip)";
+  const grid = Array.from({ length: h }, () => Array.from({ length: w }, () => " "));
+  const compoundIds = /* @__PURE__ */ new Set();
+  for (const n of nodes) if (n.parentId) compoundIds.add(n.parentId);
+  for (const n of nodes) {
+    const x0 = Math.round((n.x - minX) * scaleX);
+    const y0 = Math.round((n.y - minY) * scaleY);
+    const x1 = Math.max(x0, Math.round((n.x + n.width - minX) * scaleX) - 1);
+    const y1 = Math.max(y0, Math.round((n.y + n.height - minY) * scaleY) - 1);
+    const isCompound = compoundIds.has(n.id);
+    const ch = isCompound ? "." : "#";
+    for (let y = y0; y <= y1 && y < h; y++) {
+      for (let x = x0; x <= x1 && x < w; x++) {
+        if (y < 0 || x < 0) continue;
+        if (y === y0 || y === y1 || x === x0 || x === x1) grid[y][x] = ch;
+        else if (isCompound) {
+        } else grid[y][x] = ch;
+      }
+    }
+    const label = n.id.slice(0, Math.min(n.id.length, Math.max(2, x1 - x0 - 1)));
+    const lx = Math.max(0, x0 + 1);
+    const ly = Math.max(0, y0);
+    for (let i = 0; i < label.length && lx + i < w; i++) {
+      if (ly < h) grid[ly][lx + i] = label[i];
+    }
+  }
+  return grid.map((row) => row.join("")).join("\n");
+}
 export {
   IncrementalLayout,
   countAllCrossings,
-  layout
+  layout,
+  printLayout,
+  rotateHandles
 };
 //# sourceMappingURL=index.mjs.map