@crazyhappyone/auto-graph 0.2.0 → 0.2.2

package/dist/index.js

@@ -76,6 +76,17 @@ function intersectsAabb(a, b) {
   validateBox(b, "b");
   return a.x <= b.x + b.width && a.x + a.width >= b.x && a.y <= b.y + b.height && a.y + a.height >= b.y;
 }
+function overlapArea(first, second) {
+  const x = Math.max(
+    0,
+    Math.min(first.x + first.width, second.x + second.width) - Math.max(first.x, second.x)
+  );
+  const y = Math.max(
+    0,
+    Math.min(first.y + first.height, second.y + second.height) - Math.max(first.y, second.y)
+  );
+  return x * y;
+}
 function validateMargin(value, label) {
   validateFinite(value, label);
   if (value < 0) {
@@ -88,6 +99,72 @@ function validateFinite(value, label) {
   }
 }
 
+// src/geometry/spatial-index.ts
+function createBoxSpatialIndex(entries, cellSize = 128) {
+  const normalizedCellSize = Number.isFinite(cellSize) && cellSize > 0 ? cellSize : 128;
+  const boxes = /* @__PURE__ */ new Map();
+  const mutableCells = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    boxes.set(entry.id, { ...entry.box });
+    for (const key of cellKeysForBox(entry.box, normalizedCellSize)) {
+      const ids = mutableCells.get(key) ?? [];
+      ids.push(entry.id);
+      mutableCells.set(key, ids);
+    }
+  }
+  const cells = /* @__PURE__ */ new Map();
+  for (const [key, ids] of mutableCells) {
+    cells.set(key, [...new Set(ids)].sort());
+  }
+  return { cellSize: normalizedCellSize, entries: boxes, cells };
+}
+function queryBoxSpatialIndex(index, box) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const key of cellKeysForBox(box, index.cellSize)) {
+    for (const id of index.cells.get(key) ?? []) {
+      ids.add(id);
+    }
+  }
+  return [...ids].sort().flatMap((id) => {
+    const candidate = index.entries.get(id);
+    return candidate !== void 0 && intersectsAabb(candidate, box) ? [{ id, box: candidate }] : [];
+  });
+}
+function querySegmentSpatialIndex(index, start, end) {
+  return queryBoxSpatialIndex(index, segmentBox(start, end));
+}
+function expandBoxForQuery(box, margin) {
+  return {
+    x: box.x - margin,
+    y: box.y - margin,
+    width: box.width + margin * 2,
+    height: box.height + margin * 2
+  };
+}
+function cellKeysForBox(box, cellSize) {
+  const minCol = Math.floor(box.x / cellSize);
+  const maxCol = Math.floor((box.x + Math.max(1, box.width)) / cellSize);
+  const minRow = Math.floor(box.y / cellSize);
+  const maxRow = Math.floor((box.y + Math.max(1, box.height)) / cellSize);
+  const keys = [];
+  for (let col = minCol; col <= maxCol; col += 1) {
+    for (let row = minRow; row <= maxRow; row += 1) {
+      keys.push(`${col}:${row}`);
+    }
+  }
+  return keys;
+}
+function segmentBox(start, end) {
+  const x = Math.min(start.x, end.x);
+  const y = Math.min(start.y, end.y);
+  return {
+    x,
+    y,
+    width: Math.max(1, Math.abs(start.x - end.x)),
+    height: Math.max(1, Math.abs(start.y - end.y))
+  };
+}
+
 // src/constraints/solver.ts
 function applyLayoutConstraints(input) {
   const diagnostics = [];
@@ -119,7 +196,12 @@ function applyLayoutConstraints(input) {
     dedupReplayDiagnostics(diagnostics, diagBefore);
   }
   removeResolvedConstraintDiagnostics(input.constraints, boxes, diagnostics);
-  reportOverlaps(boxes, diagnostics, containmentOverlapKeys(input.constraints));
+  reportOverlaps(
+    boxes,
+    diagnostics,
+    containmentOverlapKeys(input.constraints),
+    locks
+  );
   reportIntraContainerOverflow(input, boxes, diagnostics);
   return { boxes, locks, diagnostics };
 }
@@ -285,14 +367,19 @@ function applyContainment(constraints, boxes, locks, diagnostics, reportOverflow
       if (samePosition(child, next)) {
         continue;
       }
-      if (locks.has(childId)) {
+      const lock = locks.get(childId);
+      if (lock !== void 0) {
         if (!reportOverflow) {
           diagnostics.push({
             severity: "warning",
             code: "constraints.locked-target-not-moved",
             message: `Locked child ${childId} was not moved into containment.`,
             path: ["constraints", constraint.id ?? constraint.containerId],
-            detail: { nodeId: childId, containerId: constraint.containerId }
+            detail: {
+              nodeId: childId,
+              containerId: constraint.containerId,
+              lockSource: lock.source
+            }
           });
           if (!isInside(child, content)) {
             diagnostics.push({
@@ -407,18 +494,29 @@ function repairOverlaps(input, boxes, locks, diagnostics, siblingPairs) {
   const secondaryAxis = axis === "x" ? "y" : "x";
   const ignoredPairs = containmentOverlapKeys(input.constraints);
   const ids = [...boxes.keys()].sort();
+  const index = createBoxSpatialIndex(
+    ids.flatMap((id) => {
+      const box = boxes.get(id);
+      return box === void 0 ? [] : [{ id, box }];
+    }),
+    spacing
+  );
   for (let pass = 0; pass < 2; pass += 1) {
     for (const firstId of ids) {
-      for (const secondId of ids) {
+      const first = boxes.get(firstId);
+      if (first === void 0) {
+        continue;
+      }
+      const candidateIds = queryBoxSpatialIndex(index, first).map((candidate) => candidate.id).filter((id) => id > firstId).sort();
+      for (const secondId of candidateIds) {
         if (firstId >= secondId) {
           continue;
         }
         if (ignoredPairs.has(overlapKey(firstId, secondId))) {
           continue;
         }
-        const first = boxes.get(firstId);
         const second = boxes.get(secondId);
-        if (first === void 0 || second === void 0 || !intersectsAabb(first, second)) {
+        if (second === void 0 || !intersectsAabb(first, second)) {
           continue;
         }
         const firstLocked = locks.has(firstId);
@@ -442,7 +540,7 @@ function repairOverlaps(input, boxes, locks, diagnostics, siblingPairs) {
       }
     }
   }
-  reportOverlaps(boxes, diagnostics, ignoredPairs);
+  reportOverlaps(boxes, diagnostics, ignoredPairs, locks);
 }
 function removeResolvedConstraintDiagnostics(constraints, boxes, diagnostics) {
   for (let i = diagnostics.length - 1; i >= 0; i -= 1) {
@@ -498,29 +596,56 @@ function removeResolvedConstraintDiagnostics(constraints, boxes, diagnostics) {
     }
   }
 }
-function reportOverlaps(boxes, diagnostics, ignoredPairs = /* @__PURE__ */ new Set()) {
+function reportOverlaps(boxes, diagnostics, ignoredPairs = /* @__PURE__ */ new Set(), locks = /* @__PURE__ */ new Map()) {
   const ids = [...boxes.keys()].sort();
   const reported = new Set(
     diagnostics.filter(
-      (diagnostic) => diagnostic.code === "constraints.overlap.unresolved"
+      (diagnostic) => diagnostic.code === "constraints.overlap.unresolved" || diagnostic.code === "constraints.overlap.locked-conflict"
     ).map((diagnostic) => {
       const firstId = diagnostic.detail?.firstId;
       const secondId = diagnostic.detail?.secondId;
       return typeof firstId === "string" && typeof secondId === "string" ? overlapKey(firstId, secondId) : void 0;
     }).filter((key) => key !== void 0)
   );
+  const index = createBoxSpatialIndex(
+    ids.flatMap((id) => {
+      const box = boxes.get(id);
+      return box === void 0 ? [] : [{ id, box }];
+    }),
+    40
+  );
   for (const firstId of ids) {
-    for (const secondId of ids) {
-      if (firstId >= secondId) {
-        continue;
-      }
+    const first = boxes.get(firstId);
+    if (first === void 0) {
+      continue;
+    }
+    const candidateIds = queryBoxSpatialIndex(index, first).map((candidate) => candidate.id).filter((id) => id > firstId).sort();
+    for (const secondId of candidateIds) {
       const key = overlapKey(firstId, secondId);
       if (reported.has(key) || ignoredPairs.has(key)) {
         continue;
       }
-      const first = boxes.get(firstId);
       const second = boxes.get(secondId);
-      if (first !== void 0 && second !== void 0 && intersectsAabb(first, second)) {
+      if (second !== void 0 && intersectsAabb(first, second)) {
+        const firstLock = locks.get(firstId);
+        const secondLock = locks.get(secondId);
+        if (firstLock !== void 0 && secondLock !== void 0) {
+          diagnostics.push({
+            severity: "warning",
+            code: "constraints.overlap.locked-conflict",
+            message: `Locked boxes ${firstId} (${firstLock.source}) and ${secondId} (${secondLock.source}) overlap and cannot be repaired.`,
+            path: ["boxes"],
+            detail: {
+              firstId,
+              secondId,
+              firstLockSource: firstLock.source,
+              secondLockSource: secondLock.source,
+              overlapArea: overlapArea(first, second)
+            }
+          });
+          reported.add(key);
+          continue;
+        }
         diagnostics.push({
           severity: "warning",
           code: "constraints.overlap.unresolved",
@@ -676,12 +801,17 @@ function setUnlockedBox(id, next, boxes, locks, diagnostics, constraint) {
     return;
   }
   if (locks.has(id) && !samePosition(current, next)) {
+    const lock = locks.get(id);
     diagnostics.push({
       severity: "warning",
       code: "constraints.locked-target-not-moved",
       message: `Locked target ${id} was not moved by ${constraint.kind}.`,
       path: ["constraints", constraint.id ?? id],
-      detail: { nodeId: id, constraintKind: constraint.kind }
+      detail: {
+        nodeId: id,
+        constraintKind: constraint.kind,
+        ...lock === void 0 ? {} : { lockSource: lock.source }
+      }
     });
     return;
   }
@@ -850,7 +980,28 @@ function applyDistributeContained(input, boxes, locks, diagnostics) {
     if (distributable.length < 2) {
       continue;
     }
+    const spread = typeof input.distributeContainedChildren === "string";
+    let effectiveGap = minGap;
     let pos = content[axis];
+    if (spread) {
+      let totalChildSpan = 0;
+      for (const child of distributable) {
+        totalChildSpan += child.box[mainSize];
+      }
+      let reservedSpan = 0;
+      const contentEnd = content[axis] + content[mainSize];
+      for (const r of reserved) {
+        const rStart = Math.max(r.start, content[axis]);
+        const rEnd = Math.min(r.end, contentEnd);
+        if (rEnd > rStart) {
+          reservedSpan += rEnd - rStart + minGap;
+        }
+      }
+      const remaining = content[mainSize] - totalChildSpan - reservedSpan - minGap * (distributable.length - 1);
+      if (remaining > 0) {
+        effectiveGap = minGap + remaining / (distributable.length - 1);
+      }
+    }
     for (const child of distributable) {
       pos = advancePastReserved(pos, child.box[mainSize], reserved, minGap);
       const crossPos = content[crossAxis] + Math.max(0, (content[crossSize] - child.box[crossSize]) / 2);
@@ -869,7 +1020,7 @@ function applyDistributeContained(input, boxes, locks, diagnostics) {
       }
       boxes.set(child.id, clamped);
       locks.delete(child.id);
-      pos = clamped[axis] + clamped[mainSize] + minGap;
+      pos = clamped[axis] + clamped[mainSize] + effectiveGap;
     }
     diagnostics.push({
       severity: "info",
@@ -1625,6 +1776,7 @@ function normalizeDiagramDsl(dslValue, options = {}) {
   const measurer = options.textMeasurer ?? createDefaultTextMeasurer();
   const routeKind = dsl.routing?.kind ?? "orthogonal";
   const portShifting = normalizePortShifting(dsl.routing?.portShifting);
+  const initialLayout = dsl.layout?.mode;
   const primaryReadingDirection = dsl.layout?.primaryReadingDirection;
   const matrices = normalizeMatrices(dsl);
   const tables = normalizeTables(dsl);
@@ -1645,6 +1797,7 @@ function normalizeDiagramDsl(dslValue, options = {}) {
     ...dsl.frame === void 0 ? {} : { frame: normalizeFrame(dsl.frame) },
     metadata: {
       routeKind,
+      ...initialLayout === void 0 ? {} : { initialLayout },
       ...primaryReadingDirection === void 0 ? {} : { primaryReadingDirection },
       ...portShifting === void 0 ? {} : { portShifting }
     }
@@ -2194,6 +2347,7 @@ function point(value) {
   return { x: value.x, y: value.y };
 }
 var directionSchema = z.enum(["TB", "LR", "BT", "RL"]);
+var layoutModeSchema = z.enum(["dagre", "positions"]);
 var routeKindSchema = z.enum(["orthogonal", "straight", "obstacle-avoiding"]);
 var outputFormatSchema = z.enum(["svg", "excalidraw"]);
 var edgeStrokeStyleSchema = z.enum(["solid", "dashed"]);
@@ -2504,6 +2658,7 @@ var diagramDslSchema = z.object({
   direction: directionSchema.optional(),
   layout: z.object({
     direction: directionSchema.optional(),
+    mode: layoutModeSchema.optional(),
     primaryReadingDirection: primaryReadingDirectionSchema.optional()
   }).optional(),
   routing: z.object({
@@ -2840,13 +2995,22 @@ function exportExcalidraw(diagram, options = {}) {
     appState: {
       name: options.title ?? diagram.title ?? diagram.id,
       viewBackgroundColor: "#ffffff",
-      gridSize: null
+      gridSize: null,
+      ...options.viewportPadding === void 0 ? {} : viewportAppState(diagram.bounds, options.viewportPadding)
     },
     files: {}
   };
   return `${JSON.stringify(scene, null, 2)}
 `;
 }
+function viewportAppState(bounds, padding) {
+  const safePadding = Number.isFinite(padding) ? Math.max(0, padding) : 0;
+  return {
+    scrollX: finite(-bounds.x + safePadding),
+    scrollY: finite(-bounds.y + safePadding),
+    zoom: { value: 1 }
+  };
+}
 function renderGroup(group) {
   return {
     ...baseElement(`group:${group.id}`, "rectangle", group.box),
@@ -3170,6 +3334,9 @@ function exportSvg(diagram, options = {}) {
   return `${[
     `<svg xmlns="http://www.w3.org/2000/svg" role="img" viewBox="${formatBoxViewBox(diagram.bounds)}">`,
     ...title === void 0 ? [] : [`  <title>${escapeXml(title)}</title>`],
+    ...options.viewportPadding === void 0 ? [] : [
+      `  <metadata data-dge-viewport="${escapeAttribute(viewportMetadata(diagram.bounds, options.viewportPadding))}"></metadata>`
+    ],
     `  <rect class="background" x="${formatNumber(diagram.bounds.x)}" y="${formatNumber(diagram.bounds.y)}" width="${formatNumber(diagram.bounds.width)}" height="${formatNumber(diagram.bounds.height)}" fill="#ffffff"/>`,
     ...diagram.frame === void 0 ? [] : [indent(renderFrame(diagram.frame, annotations))],
     ...(diagram.swimlanes ?? []).flatMap(
@@ -3203,6 +3370,16 @@ function exportSvg(diagram, options = {}) {
   ].join("\n")}
 `;
 }
+function viewportMetadata(bounds, padding) {
+  const safePadding = Number.isFinite(padding) ? Math.max(0, padding) : 0;
+  return JSON.stringify({
+    x: bounds.x - safePadding,
+    y: bounds.y - safePadding,
+    width: bounds.width + safePadding * 2,
+    height: bounds.height + safePadding * 2,
+    padding: safePadding
+  });
+}
 function renderGroup2(group) {
   return `<rect class="group" data-id="${escapeAttribute(group.id)}" x="${formatNumber(group.box.x)}" y="${formatNumber(group.box.y)}" width="${formatNumber(group.box.width)}" height="${formatNumber(group.box.height)}" fill="${GROUP_FILL}" stroke="${STROKE}" stroke-dasharray="6 4"/>`;
 }
@@ -3877,6 +4054,7 @@ function indentLines(values) {
 // src/ir/diagnostics.ts
 var DELIVERABILITY_DIAGNOSTIC_CODES = /* @__PURE__ */ new Set([
   "constraints.locked-target-not-moved",
+  "constraints.overlap.locked-conflict",
   "routing.evidence.crossing_forbidden",
   "routing.obstacle.unavoidable",
   "route_obstacle_fallback",
@@ -3888,6 +4066,7 @@ var DEFAULT_OPTIONS = {
   edgesep: 40,
   marginx: 0,
   marginy: 0,
+  componentGap: 160,
   ranker: "network-simplex"
 };
 function runDagreInitialLayout(input) {
@@ -3976,20 +4155,137 @@ function runDagreInitialLayout(input) {
   }
   return { boxes, diagnostics };
 }
+function runComponentAwareDagreInitialLayout(input) {
+  const options = { ...DEFAULT_OPTIONS, ...input.options };
+  const diagnostics = reportMissingEdgeReferences(input);
+  const validNodeIds = new Set(input.nodes.map((node) => node.id));
+  const validEdges = input.edges.filter(
+    (edge) => validNodeIds.has(edge.sourceId) && validNodeIds.has(edge.targetId)
+  );
+  const components = connectedComponents(input.nodes, validEdges);
+  if (components.length <= 1) {
+    const layout2 = runDagreInitialLayout({ ...input, edges: validEdges });
+    return {
+      boxes: layout2.boxes,
+      diagnostics: [...diagnostics, ...layout2.diagnostics]
+    };
+  }
+  const boxes = /* @__PURE__ */ new Map();
+  let cursor = 0;
+  for (const component of components) {
+    const componentNodeIds = new Set(component.map((node) => node.id));
+    const componentLayout = runDagreInitialLayout({
+      ...input,
+      nodes: component,
+      edges: validEdges.filter(
+        (edge) => componentNodeIds.has(edge.sourceId) && componentNodeIds.has(edge.targetId)
+      )
+    });
+    diagnostics.push(...componentLayout.diagnostics);
+    if (componentLayout.boxes.size === 0) {
+      continue;
+    }
+    const bounds = unionBoxes([...componentLayout.boxes.values()]);
+    const axis = input.direction === "LR" || input.direction === "RL" ? "x" : "y";
+    const dx = axis === "x" ? cursor - bounds.x : -bounds.x;
+    const dy = axis === "y" ? cursor - bounds.y : -bounds.y;
+    for (const [id, box] of componentLayout.boxes) {
+      boxes.set(id, { ...box, x: box.x + dx, y: box.y + dy });
+    }
+    cursor += (axis === "x" ? bounds.width : bounds.height) + options.componentGap;
+  }
+  return { boxes, diagnostics };
+}
+function reportMissingEdgeReferences(input) {
+  const validNodeIds = new Set(input.nodes.map((node) => node.id));
+  return input.edges.flatMap((edge) => {
+    if (validNodeIds.has(edge.sourceId) && validNodeIds.has(edge.targetId)) {
+      return [];
+    }
+    return [
+      {
+        severity: "error",
+        code: "layout.edge-reference.missing",
+        message: `Edge ${edge.id} references a missing layout node.`,
+        path: ["edges", edge.id],
+        detail: {
+          edgeId: edge.id,
+          sourceId: edge.sourceId,
+          targetId: edge.targetId
+        }
+      }
+    ];
+  });
+}
 function isValidDimension(value) {
   return Number.isFinite(value) && value >= 0;
 }
+function connectedComponents(nodes, edges) {
+  const nodeById = new Map(nodes.map((node) => [node.id, node]));
+  const adjacency = new Map(nodes.map((node) => [node.id, /* @__PURE__ */ new Set()]));
+  for (const edge of edges) {
+    if (!nodeById.has(edge.sourceId) || !nodeById.has(edge.targetId)) {
+      continue;
+    }
+    adjacency.get(edge.sourceId)?.add(edge.targetId);
+    adjacency.get(edge.targetId)?.add(edge.sourceId);
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const components = [];
+  for (const node of [...nodes].sort((a, b) => a.id.localeCompare(b.id))) {
+    if (visited.has(node.id)) {
+      continue;
+    }
+    const ids = [];
+    const stack = [node.id];
+    visited.add(node.id);
+    while (stack.length > 0) {
+      const id = stack.pop();
+      if (id === void 0) {
+        continue;
+      }
+      ids.push(id);
+      for (const neighbor of [...adjacency.get(id) ?? []].sort().reverse()) {
+        if (!visited.has(neighbor)) {
+          visited.add(neighbor);
+          stack.push(neighbor);
+        }
+      }
+    }
+    components.push(
+      ids.sort().flatMap((id) => {
+        const componentNode = nodeById.get(id);
+        return componentNode === void 0 ? [] : [componentNode];
+      })
+    );
+  }
+  return components.sort((a, b) => {
+    const left = a[0]?.id ?? "";
+    const right = b[0]?.id ?? "";
+    return left.localeCompare(right);
+  });
+}
 
 // src/routing/astar.ts
-function findObstacleFreePath(source, target, obstacles, options = {}) {
+function findObstacleFreePath(source, target, obstacles, options = {}, diagnostics) {
   const margin = options.margin ?? 0;
   const turnPenalty = options.turnPenalty ?? 50;
   const segmentPenalty = options.segmentPenalty ?? 1;
   const endpointObstacles = options.endpointObstacles ?? [];
-  const maxNodes = options.maxNodes ?? 4e3;
+  const maxNodes = options.maxNodes ?? (obstacles.length > 30 ? 16e3 : 4e3);
   const xs = collectXs(source, target, obstacles, margin);
   const ys = collectYs(source, target, obstacles, margin);
   if (xs.length * ys.length > maxNodes) {
+    diagnostics?.push({
+      severity: "warning",
+      code: "routing.astar.grid_overflow",
+      message: `A* grid overflow: ${xs.length * ys.length} nodes > ${maxNodes} limit. Falling back to heuristic routing.`,
+      detail: {
+        xsCount: xs.length,
+        ysCount: ys.length,
+        maxNodes
+      }
+    });
     return null;
   }
   const { nodes, nodeIndex } = buildGraph(xs, ys);
@@ -4007,24 +4303,54 @@ function findObstacleFreePath(source, target, obstacles, options = {}) {
   return simplifyRoute(path);
 }
 function collectXs(source, target, obstacles, margin) {
-  const set = /* @__PURE__ */ new Set();
-  set.add(source.x);
-  set.add(target.x);
+  const raw = [];
   for (const obs of obstacles) {
-    set.add(obs.x - margin - 2);
-    set.add(obs.x + obs.width + margin + 2);
+    raw.push(obs.x - margin - 2, obs.x + obs.width + margin + 2);
+  }
+  const deduped = insertChannelMidpoints(dedupSorted(raw));
+  for (const v of [source.x, target.x]) {
+    if (!deduped.includes(v)) {
+      deduped.push(v);
+    }
   }
-  return [...set].sort((a, b) => a - b);
+  return deduped.sort((a, b) => a - b);
 }
 function collectYs(source, target, obstacles, margin) {
-  const set = /* @__PURE__ */ new Set();
-  set.add(source.y);
-  set.add(target.y);
+  const raw = [];
   for (const obs of obstacles) {
-    set.add(obs.y - margin - 2);
-    set.add(obs.y + obs.height + margin + 2);
+    raw.push(obs.y - margin - 2, obs.y + obs.height + margin + 2);
   }
-  return [...set].sort((a, b) => a - b);
+  const deduped = insertChannelMidpoints(dedupSorted(raw));
+  for (const v of [source.y, target.y]) {
+    if (!deduped.includes(v)) {
+      deduped.push(v);
+    }
+  }
+  return deduped.sort((a, b) => a - b);
+}
+function dedupSorted(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const result = [];
+  for (const v of sorted) {
+    const last = result[result.length - 1];
+    if (last === void 0 || v - last > 2) {
+      result.push(v);
+    }
+  }
+  return result;
+}
+function insertChannelMidpoints(sorted, minGap = 8) {
+  const result = [];
+  for (let i = 0; i < sorted.length - 1; i++) {
+    const a = sorted[i];
+    const b = sorted[i + 1];
+    result.push(a);
+    if (b - a > minGap) {
+      result.push((a + b) / 2);
+    }
+  }
+  result.push(sorted[sorted.length - 1]);
+  return result.sort((a, b) => a - b);
 }
 function buildGraph(xs, ys) {
   const nodes = [];
@@ -4188,10 +4514,36 @@ function areCollinear(a, b, c) {
 }
 
 // src/routing/routes.ts
+function checkBacktracking(points, source, target, diagnostics) {
+  if (points.length < 2) return;
+  const direct = Math.hypot(target.x - source.x, target.y - source.y);
+  if (direct <= 0) return;
+  let routeLen = 0;
+  for (let i = 0; i < points.length - 1; i++) {
+    const a = points[i];
+    const b = points[i + 1];
+    routeLen += Math.hypot(b.x - a.x, b.y - a.y);
+  }
+  const threshold = 10;
+  if (routeLen > direct * threshold) {
+    diagnostics.push({
+      severity: "warning",
+      code: "routing.backtracking_excessive",
+      message: `Route length ${Math.round(routeLen)} px exceeds ${threshold}\xD7 direct distance ${Math.round(direct)} px.`,
+      detail: {
+        routeLength: Math.round(routeLen),
+        directDistance: Math.round(direct),
+        threshold
+      }
+    });
+  }
+}
 function routeEdge(input) {
   const diagnostics = [];
   const softObstacles = input.obstacles ?? [];
   const hardObstacles = input.hardObstacles ?? [];
+  const softObstacleIndex = input.obstacleIndex ?? createBoxSpatialIndex(indexedBoxes(softObstacles));
+  const hardObstacleIndex = input.hardObstacleIndex ?? createBoxSpatialIndex(indexedBoxes(hardObstacles));
   const maxAttempts = input.maxRoutingAttempts ?? 5;
   const defaultAnchors = defaultAnchorsForGeometry(
     input.source.box,
@@ -4213,9 +4565,11 @@ function routeEdge(input) {
       [source, target],
       softObstacles,
       hardObstacles,
-      diagnostics
+      diagnostics,
+      softObstacleIndex,
+      hardObstacleIndex
     );
-    if (routeCrossesBoxes(points, hardObstacles)) {
+    if (routeCrossesBoxes(points, hardObstacles, hardObstacleIndex)) {
       diagnostics.push({
         severity: "error",
         code: "routing.evidence.crossing_forbidden",
@@ -4223,7 +4577,7 @@ function routeEdge(input) {
       });
       return { points, diagnostics };
     }
-    if (routeCrossesBoxes(points, softObstacles)) {
+    if (routeCrossesBoxes(points, softObstacles, softObstacleIndex)) {
       diagnostics.push({
         severity: "warning",
         code: "routing.obstacle.unavoidable",
@@ -4254,16 +4608,24 @@ function routeEdge(input) {
         [...softObstacles, ...hardObstacles],
         {
           endpointObstacles
-        }
+        },
+        diagnostics
       );
       if (path !== null && path.length >= 2) {
         const finalized = finalizeRoute(
           path,
           softObstacles,
           hardObstacles,
-          diagnostics
+          diagnostics,
+          softObstacleIndex,
+          hardObstacleIndex
         );
-        if (!routeIntersectsObstacles(finalized, softObstacles) && !routeIntersectsObstacles(finalized, hardObstacles)) {
+        if (!routeIntersectsObstacles(
+          finalized,
+          softObstacles,
+          softObstacleIndex
+        ) && !routeIntersectsObstacles(finalized, hardObstacles, hardObstacleIndex)) {
+          checkBacktracking(finalized, source, target, diagnostics);
           return { points: finalized, diagnostics };
         }
       }
@@ -4303,23 +4665,41 @@ function routeEdge(input) {
     }
   );
   for (const candidate of candidateRoutes) {
-    if (!routeIntersectsObstacles(candidate.points, softObstacles) && !routeIntersectsObstacles(candidate.points, hardObstacles) && !routeIntersectsEndpointInteriors(
+    if (!routeIntersectsObstacles(candidate.points, softObstacles) && !routeIntersectsObstacles(
+      candidate.points,
+      softObstacles,
+      softObstacleIndex
+    ) && !routeIntersectsObstacles(
+      candidate.points,
+      hardObstacles,
+      hardObstacleIndex
+    ) && !routeIntersectsEndpointInteriors(
       candidate.points,
       candidate.endpointObstacles
     )) {
-      return {
-        points: finalizeRoute(
-          candidate.points,
-          softObstacles,
-          hardObstacles,
-          diagnostics
-        ),
+      const finalizedClean = finalizeRoute(
+        candidate.points,
+        softObstacles,
+        hardObstacles,
+        diagnostics,
+        softObstacleIndex,
+        hardObstacleIndex
+      );
+      checkBacktracking(
+        finalizedClean,
+        candidate.points[0],
+        candidate.points[candidate.points.length - 1],
         diagnostics
-      };
+      );
+      return { points: finalizedClean, diagnostics };
     }
   }
   const hardClearCandidate = candidateRoutes.find(
-    (candidate) => !routeIntersectsObstacles(candidate.points, hardObstacles) && !routeIntersectsEndpointInteriors(
+    (candidate) => !routeIntersectsObstacles(
+      candidate.points,
+      hardObstacles,
+      hardObstacleIndex
+    ) && !routeIntersectsEndpointInteriors(
       candidate.points,
       candidate.endpointObstacles
     )
@@ -4470,13 +4850,21 @@ function routeEdge(input) {
     diagnostics
   };
 }
-function finalizeRoute(points, softObstacles, hardObstacles, diagnostics) {
+function finalizeRoute(points, softObstacles, hardObstacles, diagnostics, softObstacleIndex, hardObstacleIndex) {
   const simplified = simplifyRoute2(points);
   if (simplified.length >= 3) {
     return simplified;
   }
-  const crossesHardObstacles = routeCrossesBoxes(simplified, hardObstacles);
-  const crossesSoftObstacles = routeCrossesBoxes(simplified, softObstacles);
+  const crossesHardObstacles = routeCrossesBoxes(
+    simplified,
+    hardObstacles,
+    hardObstacleIndex
+  );
+  const crossesSoftObstacles = routeCrossesBoxes(
+    simplified,
+    softObstacles,
+    softObstacleIndex
+  );
   if (!crossesHardObstacles && !crossesSoftObstacles) {
     return simplified;
   }
@@ -4484,8 +4872,16 @@ function finalizeRoute(points, softObstacles, hardObstacles, diagnostics) {
     ...softObstacles,
     ...hardObstacles
   ]);
-  const expandedCrossesHard = routeCrossesBoxes(expanded, hardObstacles);
-  const expandedCrossesSoft = routeCrossesBoxes(expanded, softObstacles);
+  const expandedCrossesHard = routeCrossesBoxes(
+    expanded,
+    hardObstacles,
+    hardObstacleIndex
+  );
+  const expandedCrossesSoft = routeCrossesBoxes(
+    expanded,
+    softObstacles,
+    softObstacleIndex
+  );
   if (expandedCrossesHard || expandedCrossesSoft) {
     diagnostics.push({
       severity: expandedCrossesHard ? "error" : "warning",
@@ -4927,15 +5323,20 @@ function sortedUniqueLanes(lanes, midpoint) {
     return distance === 0 ? left - right : distance;
   });
 }
-function routeIntersectsObstacles(points, obstacles) {
-  for (let index = 0; index < points.length - 1; index += 1) {
-    const a = points[index];
-    const b = points[index + 1];
+function routeIntersectsObstacles(points, obstacles, spatialIndex) {
+  for (let pointIndex = 0; pointIndex < points.length - 1; pointIndex += 1) {
+    const a = points[pointIndex];
+    const b = points[pointIndex + 1];
     if (a === void 0 || b === void 0) {
       continue;
     }
-    const segment = segmentBox(a, b);
-    for (const obstacle of obstacles) {
+    const segment = segmentBox2(a, b);
+    for (const obstacle of candidateBoxesForSegment(
+      obstacles,
+      a,
+      b,
+      spatialIndex
+    )) {
       validateBox(obstacle);
       if (intersectsAabb(segment, obstacle)) {
         return true;
@@ -4951,7 +5352,7 @@ function routeIntersectsEndpointInteriors(points, endpointInteriors) {
     if (a === void 0 || b === void 0) {
       continue;
     }
-    const segment = segmentBox(a, b);
+    const segment = segmentBox2(a, b);
     for (const endpointInterior of endpointInteriors) {
       validateBox(endpointInterior);
       if (intersectsAabb(segment, endpointInterior)) {
@@ -4961,14 +5362,19 @@ function routeIntersectsEndpointInteriors(points, endpointInteriors) {
   }
   return false;
 }
-function routeCrossesBoxes(points, obstacles) {
-  for (let index = 0; index < points.length - 1; index += 1) {
-    const a = points[index];
-    const b = points[index + 1];
+function routeCrossesBoxes(points, obstacles, spatialIndex) {
+  for (let pointIndex = 0; pointIndex < points.length - 1; pointIndex += 1) {
+    const a = points[pointIndex];
+    const b = points[pointIndex + 1];
     if (a === void 0 || b === void 0) {
       continue;
     }
-    for (const obstacle of obstacles) {
+    for (const obstacle of candidateBoxesForSegment(
+      obstacles,
+      a,
+      b,
+      spatialIndex
+    )) {
       validateBox(obstacle);
       if (segmentIntersectsBox(a, b, obstacle)) {
         return true;
@@ -4977,6 +5383,12 @@ function routeCrossesBoxes(points, obstacles) {
   }
   return false;
 }
+function candidateBoxesForSegment(obstacles, start, end, index) {
+  return index === void 0 ? obstacles : querySegmentSpatialIndex(index, start, end).map((entry) => entry.box);
+}
+function indexedBoxes(obstacles) {
+  return obstacles.map((box, index) => ({ id: `obstacle:${index}`, box }));
+}
 function segmentIntersectsBox(start, end, box) {
   const left = box.x;
   const right = box.x + box.width;
@@ -5010,7 +5422,7 @@ function segmentIntersectsBoxEdge(start, end, x1, y1, x2, y2) {
   const u = ((x1 - start.x) * (end.y - start.y) - (y1 - start.y) * (end.x - start.x)) / denominator;
   return t > 0 && t < 1 && u > 0 && u < 1;
 }
-function segmentBox(a, b) {
+function segmentBox2(a, b) {
   const minX = Math.min(a.x, b.x);
   const minY = Math.min(a.y, b.y);
   return {
@@ -5082,17 +5494,16 @@ function solveDiagram(diagram, options = {}) {
     (swimlane) => enhanceSwimlaneCjkTypography(swimlane, cjkTypography, diagnostics)
   );
   const constraints = stableByConstraintId(diagram.constraints);
-  const layout2 = runDagreInitialLayout({
+  const initialLayoutMode = options.initialLayout ?? "dagre";
+  const layout2 = runInitialLayout({
+    mode: initialLayoutMode,
+    componentAware: options.maxStackDepth === void 0,
     direction: diagram.direction,
-    nodes: styledNodes.map((node) => ({ id: node.id, size: node.size })),
-    edges: styledEdges.map((edge) => ({
-      id: edge.id,
-      sourceId: edge.source.nodeId,
-      targetId: edge.target.nodeId
-    }))
+    nodes: styledNodes,
+    edges: styledEdges
   });
   diagnostics.push(...layout2.diagnostics);
-  const initialNodeBoxes = wrapVerticalStackIfNeeded(
+  const initialNodeBoxes = initialLayoutMode === "positions" ? layout2.boxes : wrapVerticalStackIfNeeded(
     layout2.boxes,
     styledNodes,
     styledEdges,
@@ -5105,7 +5516,7 @@ function solveDiagram(diagram, options = {}) {
     direction: diagram.direction,
     overlapSpacing: options?.overlapSpacing ?? 40,
     ...options.minSiblingGap === void 0 ? {} : { minSiblingGap: options.minSiblingGap },
-    ...options.distributeContainedChildren === void 0 ? {} : { distributeContainedChildren: options.distributeContainedChildren },
+    distributeContainedChildren: options.distributeContainedChildren ?? true,
     boxes: initialNodeBoxes,
     nodes: styledNodes,
     constraints
@@ -5352,6 +5763,84 @@ function solveDiagram(diagram, options = {}) {
 function solveDiagramSafe(diagram, options = {}) {
   return solveDiagram(diagram, { ...options, prefitLabelSize: true });
 }
+function runInitialLayout(input) {
+  if (input.mode === "positions") {
+    return runPositionSeededInitialLayout(input);
+  }
+  const runAutoLayout = input.componentAware ? runComponentAwareDagreInitialLayout : runDagreInitialLayout;
+  return runAutoLayout({
+    direction: input.direction,
+    nodes: input.nodes.map((node) => ({ id: node.id, size: node.size })),
+    edges: input.edges.map((edge) => ({
+      id: edge.id,
+      sourceId: edge.source.nodeId,
+      targetId: edge.target.nodeId
+    }))
+  });
+}
+function runPositionSeededInitialLayout(input) {
+  const diagnostics = [];
+  const boxes = /* @__PURE__ */ new Map();
+  const autoNodes = [];
+  for (const node of input.nodes) {
+    if (!isValidInitialDimension(node.size.width) || !isValidInitialDimension(node.size.height)) {
+      diagnostics.push({
+        severity: "error",
+        code: "layout.node-size.invalid",
+        message: `Node ${node.id} has invalid layout dimensions.`,
+        path: ["nodes", node.id, "size"],
+        detail: { nodeId: node.id }
+      });
+      continue;
+    }
+    if (node.position === void 0) {
+      autoNodes.push(node);
+      continue;
+    }
+    if (!isFiniteInitialPoint(node.position)) {
+      diagnostics.push({
+        severity: "error",
+        code: "layout.node-position.invalid",
+        message: `Node ${node.id} has an invalid seeded position.`,
+        path: ["nodes", node.id, "position"],
+        detail: { nodeId: node.id }
+      });
+      continue;
+    }
+    boxes.set(node.id, {
+      x: node.position.x,
+      y: node.position.y,
+      width: node.size.width,
+      height: node.size.height
+    });
+  }
+  if (autoNodes.length === 0) {
+    return { boxes, diagnostics };
+  }
+  const autoNodeIds = new Set(autoNodes.map((node) => node.id));
+  const autoLayout = runComponentAwareDagreInitialLayout({
+    direction: input.direction,
+    nodes: autoNodes.map((node) => ({ id: node.id, size: node.size })),
+    edges: input.edges.filter(
+      (edge) => autoNodeIds.has(edge.source.nodeId) && autoNodeIds.has(edge.target.nodeId)
+    ).map((edge) => ({
+      id: edge.id,
+      sourceId: edge.source.nodeId,
+      targetId: edge.target.nodeId
+    }))
+  });
+  diagnostics.push(...autoLayout.diagnostics);
+  for (const [id, box] of autoLayout.boxes) {
+    boxes.set(id, box);
+  }
+  return { boxes, diagnostics };
+}
+function isValidInitialDimension(value) {
+  return Number.isFinite(value) && value >= 0;
+}
+function isFiniteInitialPoint(point2) {
+  return Number.isFinite(point2.x) && Number.isFinite(point2.y);
+}
 function prefitNodeLabelSize(node, options, diagnostics) {
   if (node.label === void 0) {
     return node;
@@ -7103,6 +7592,10 @@ function coordinateEdges(edges, nodes, coordinatedNodes, obstacles, softObstacle
   const coordinatedNodeById = new Map(
     coordinatedNodes.map((node) => [node.id, node])
   );
+  const nodeObstacleIndex = createBoxSpatialIndex(
+    obstacles.map((box, index) => ({ id: `node-obstacle:${index}`, box })),
+    options.routingGutter ?? 160
+  );
   for (const edge of edges) {
     const source = nodes.get(edge.source.nodeId);
     const target = nodes.get(edge.target.nodeId);
@@ -7123,6 +7616,14 @@ function coordinateEdges(edges, nodes, coordinatedNodes, obstacles, softObstacle
     const sourcePort = coordinatedNodeById.get(edge.source.nodeId)?.ports?.find((port) => port.id === edge.source.portId);
     const targetPort = coordinatedNodeById.get(edge.target.nodeId)?.ports?.find((port) => port.id === edge.target.portId);
     const routeTextObstacles = textObstacles.filter((annotation) => !isEdgeConnectedTextAnnotation(edge, annotation)).map((annotation) => annotation.box);
+    const corridor = edgeCorridorBox(
+      source.box,
+      target.box,
+      options.routingGutter ?? 160
+    );
+    const routeNodeObstacles = queryBoxSpatialIndex(nodeObstacleIndex, corridor).map((entry) => entry.box).filter(
+      (obstacle) => !sameBox(obstacle, source.obstacleBox) && !sameBox(obstacle, target.obstacleBox)
+    );
     const route = routeEdge({
       kind: options.routeKind ?? "orthogonal",
       direction,
@@ -7131,9 +7632,7 @@ function coordinateEdges(edges, nodes, coordinatedNodes, obstacles, softObstacle
       ...edge.source.anchor === void 0 ? {} : { sourceAnchor: edge.source.anchor },
       ...edge.target.anchor === void 0 ? {} : { targetAnchor: edge.target.anchor },
       obstacles: [
-        ...obstacles.filter(
-          (obstacle) => obstacle !== source.obstacleBox && obstacle !== target.obstacleBox
-        ),
+        ...routeNodeObstacles,
         ...softObstacles,
         ...groupObstaclesForEdge(edge, groups, options.obstacleMargin ?? 0),
         ...routeTextObstacles
@@ -7154,6 +7653,19 @@ function coordinateEdges(edges, nodes, coordinatedNodes, obstacles, softObstacle
   }
   return coordinated;
 }
+function edgeCorridorBox(source, target, margin) {
+  const minX = Math.min(source.x, target.x);
+  const minY = Math.min(source.y, target.y);
+  const maxX = Math.max(source.x + source.width, target.x + target.width);
+  const maxY = Math.max(source.y + source.height, target.y + target.height);
+  return expandBoxForQuery(
+    { x: minX, y: minY, width: maxX - minX, height: maxY - minY },
+    margin
+  );
+}
+function sameBox(first, second) {
+  return first.x === second.x && first.y === second.y && first.width === second.width && first.height === second.height;
+}
 function isEdgeConnectedTextAnnotation(edge, annotation) {
   switch (annotation.surfaceKind) {
     case "edge-label":
@@ -8042,6 +8554,7 @@ function renderDiagramDsl(source, options = {}) {
     return { diagnostics };
   }
   const solved = solveDiagram(normalized.diagram, {
+    ...solveInitialLayoutOption(normalized.diagram.metadata?.initialLayout),
     routeKind: normalized.diagram.metadata?.routeKind === "straight" ? "straight" : normalized.diagram.metadata?.routeKind === "obstacle-avoiding" ? "obstacle-avoiding" : "orthogonal",
     ...solvePortShiftingOption(normalized.diagram.metadata?.portShifting),
     ...options.textMeasurer === void 0 ? {} : { textMeasurer: options.textMeasurer }
@@ -8083,6 +8596,9 @@ function renderDiagramDsl(source, options = {}) {
 function toSolveDiagnostic(diagnostic) {
   return { ...diagnostic, layer: "solve" };
 }
+function solveInitialLayoutOption(value) {
+  return value === "positions" ? { initialLayout: "positions" } : {};
+}
 function solvePortShiftingOption(value) {
   if (!isJsonObject(value)) {
     return {};
@@ -8232,6 +8748,6 @@ function isPointLikeRecord(value) {
   return isPlainObject(value) && typeof value.x === "number" && typeof value.y === "number";
 }
 
-export { DEFAULT_CANONICAL_PRECISION, DEFAULT_DSL_MAX_BYTES, DELIVERABILITY_DIAGNOSTIC_CODES, DeterministicTextMeasurer, LabelFitter, PretextTextMeasurer, applyLayoutConstraints, assertFiniteNonNegative, assertFinitePositive, boxCenter, canonicalize, computeArrowhead, computeContainerGeometry, computeShapeGeometry, createDefaultTextMeasurer, expandBox, exportExcalidraw, exportSvg, fitLabel, getEdgePort, installNodeCanvasRuntime, intersectsAabb, isPretextRuntimeAvailable, normalizeDiagramDsl, normalizeInsets, parseDiagramDsl, parseEdgeShorthand, renderDiagramDsl, resolveLineHeight, resolveOutputFormat, routeEdge, runDagreInitialLayout, simplifyRoute2 as simplifyRoute, solveDiagram, solveDiagramSafe, sortDslDiagnostics, stringifyCanonical, toCanvasFont, unionBoxes, validateBox, validateTextStyle };
+export { DEFAULT_CANONICAL_PRECISION, DEFAULT_DSL_MAX_BYTES, DELIVERABILITY_DIAGNOSTIC_CODES, DeterministicTextMeasurer, LabelFitter, PretextTextMeasurer, applyLayoutConstraints, assertFiniteNonNegative, assertFinitePositive, boxCenter, canonicalize, computeArrowhead, computeContainerGeometry, computeShapeGeometry, createBoxSpatialIndex, createDefaultTextMeasurer, expandBox, expandBoxForQuery, exportExcalidraw, exportSvg, fitLabel, getEdgePort, installNodeCanvasRuntime, intersectsAabb, isPretextRuntimeAvailable, normalizeDiagramDsl, normalizeInsets, overlapArea, parseDiagramDsl, parseEdgeShorthand, queryBoxSpatialIndex, querySegmentSpatialIndex, renderDiagramDsl, resolveLineHeight, resolveOutputFormat, routeEdge, runComponentAwareDagreInitialLayout, runDagreInitialLayout, simplifyRoute2 as simplifyRoute, solveDiagram, solveDiagramSafe, sortDslDiagnostics, stringifyCanonical, toCanvasFont, unionBoxes, validateBox, validateTextStyle };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map