@bpmn-nova/studio 0.3.0-preview → 0.3.2-preview

package/dist/modules/core/layout.js

@@ -0,0 +1,644 @@
+import { getNode, NODE_DEFINITIONS } from './model.js';
+import {
+  applyContainmentOperation,
+  CONTAINMENT_LIMITS,
+  getSwimlaneContentBounds,
+  getSwimlaneContentInsets,
+  resolveContainment,
+} from './containment.js';
+
+function center(node) {
+  return { x: node.x + node.width / 2, y: node.y + node.height / 2 };
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function anchor(node, side, offset = 0) {
+  if (side === 'left') return { x: node.x, y: node.y + node.height / 2 + clamp(offset, -node.height / 2 + 13, node.height / 2 - 13) };
+  if (side === 'right') return { x: node.x + node.width, y: node.y + node.height / 2 + clamp(offset, -node.height / 2 + 13, node.height / 2 - 13) };
+  if (side === 'top') return { x: node.x + node.width / 2 + clamp(offset, -node.width / 2 + 13, node.width / 2 - 13), y: node.y };
+  return { x: node.x + node.width / 2 + clamp(offset, -node.width / 2 + 13, node.width / 2 - 13), y: node.y + node.height };
+}
+
+export function smartAnchors(source, target) {
+  const s = center(source);
+  const t = center(target);
+  const dx = t.x - s.x;
+  const dy = t.y - s.y;
+  if (Math.abs(dx) >= Math.abs(dy) * 0.72) {
+    return dx >= 0
+      ? { sourceSide: 'right', targetSide: 'left' }
+      : { sourceSide: 'left', targetSide: 'right' };
+  }
+  return dy >= 0
+    ? { sourceSide: 'bottom', targetSide: 'top' }
+    : { sourceSide: 'top', targetSide: 'bottom' };
+}
+
+function flowNode(node) {
+  const kind = NODE_DEFINITIONS[node?.type]?.kind;
+  return ['event', 'boundary', 'task', 'container', 'gateway'].includes(kind);
+}
+
+function bestAlignment(rawValue, candidates, threshold) {
+  let best = null;
+  for (const candidate of candidates) {
+    const delta = Math.abs(candidate.value - rawValue);
+    if (delta > threshold) continue;
+    const score = delta + (candidate.priority || 0) * (threshold + 1);
+    if (!best || score < best.score) best = { ...candidate, delta, score };
+  }
+  return best;
+}
+
+/**
+ * Pixel-smooth drag snapping with magnetic alignment guides.
+ * The visible dotted grid is deliberately independent from drag snapping so
+ * different BPMN node sizes can still share exact center lines.
+ */
+export function snapNodePosition(model, node, x, y, options = {}) {
+  if (model.settings?.alignmentGuides === false) return { x, y, guides: [] };
+  const threshold = options.threshold ?? model.settings?.alignmentThreshold ?? 7;
+  const others = model.nodes.filter((candidate) => candidate.id !== node.id && flowNode(candidate));
+  if (!others.length || options.disabled) return { x, y, guides: [] };
+
+  const centerX = x + node.width / 2;
+  const centerY = y + node.height / 2;
+  const xCandidates = [];
+  const yCandidates = [];
+
+  for (const other of others) {
+    const otherCenterX = other.x + other.width / 2;
+    const otherCenterY = other.y + other.height / 2;
+
+    // Center alignment is the primary workflow-layout signal.
+    xCandidates.push({ value: otherCenterX - node.width / 2, guide: otherCenterX, priority: 0, kind: 'center' });
+    yCandidates.push({ value: otherCenterY - node.height / 2, guide: otherCenterY, priority: 0, kind: 'center' });
+
+    // Edge alignment remains useful for swimlanes, stacked tasks and manual layout.
+    xCandidates.push({ value: other.x, guide: other.x, priority: 1, kind: 'edge' });
+    xCandidates.push({ value: other.x + other.width - node.width, guide: other.x + other.width, priority: 1, kind: 'edge' });
+    yCandidates.push({ value: other.y, guide: other.y, priority: 1, kind: 'edge' });
+    yCandidates.push({ value: other.y + other.height - node.height, guide: other.y + other.height, priority: 1, kind: 'edge' });
+  }
+
+  const xSnap = bestAlignment(x, xCandidates, threshold);
+  const ySnap = bestAlignment(y, yCandidates, threshold);
+  const nextX = xSnap ? xSnap.value : x;
+  const nextY = ySnap ? ySnap.value : y;
+  const guides = [];
+  if (xSnap) guides.push({ orientation: 'vertical', position: xSnap.guide, kind: xSnap.kind });
+  if (ySnap) guides.push({ orientation: 'horizontal', position: ySnap.guide, kind: ySnap.kind });
+
+  return { x: nextX, y: nextY, guides };
+}
+
+function connectionOffset(model, edge, end, side) {
+  const nodeId = end === 'source' ? edge.source : edge.target;
+  const node = getNode(model, nodeId);
+  const nodeKind = NODE_DEFINITIONS[node?.type]?.kind;
+  const peers = model.edges
+    .filter((candidate) => (candidate.type || 'sequenceFlow') === (edge.type || 'sequenceFlow'))
+    .filter((candidate) => (end === 'source' ? candidate.source === nodeId : candidate.target === nodeId));
+  // Gateways share their branch anchor in both directions. Any node with
+  // multiple incoming flows also shares one centered ingress anchor so the
+  // branches converge before a single visual trunk/arrow enters the node.
+  if (model.settings?.mergeGatewayConnections !== false && (nodeKind === 'gateway' || (end === 'target' && peers.length > 1))) return 0;
+  if (peers.length <= 1) return 0;
+  const horizontalSide = side === 'left' || side === 'right';
+  const scored = peers.map((candidate) => {
+    const otherId = end === 'source' ? candidate.target : candidate.source;
+    const other = getNode(model, otherId);
+    const c = other ? center(other) : { x: 0, y: 0 };
+    return { id: candidate.id, score: horizontalSide ? c.y : c.x };
+  }).sort((a, b) => a.score - b.score || a.id.localeCompare(b.id));
+  const index = Math.max(0, scored.findIndex((item) => item.id === edge.id));
+  const step = peers.length > 4 ? 10 : 14;
+  return (index - (peers.length - 1) / 2) * step;
+}
+
+function boxesIntersectSegment(a, b, node, padding = 22) {
+  const left = node.x - padding;
+  const right = node.x + node.width + padding;
+  const top = node.y - padding;
+  const bottom = node.y + node.height + padding;
+  if (Math.abs(a.x - b.x) < 0.01) {
+    if (a.x < left || a.x > right) return false;
+    const minY = Math.min(a.y, b.y);
+    const maxY = Math.max(a.y, b.y);
+    return maxY >= top && minY <= bottom;
+  }
+  if (Math.abs(a.y - b.y) < 0.01) {
+    if (a.y < top || a.y > bottom) return false;
+    const minX = Math.min(a.x, b.x);
+    const maxX = Math.max(a.x, b.x);
+    return maxX >= left && minX <= right;
+  }
+  return false;
+}
+
+function routeHitsNode(model, points, edge) {
+  const blockers = model.nodes.filter((node) => node.id !== edge.source && node.id !== edge.target && flowNode(node));
+  for (let i = 0; i < points.length - 1; i += 1) {
+    for (const blocker of blockers) {
+      if (boxesIntersectSegment(points[i], points[i + 1], blocker)) return blocker;
+    }
+  }
+  return null;
+}
+
+
+function routedAnchors(model, source, target) {
+  const direction = model.settings?.direction || 'horizontal';
+  const tolerance = 8;
+  if (direction === 'horizontal') {
+    // As long as the target is on the next horizontal side, keep right -> left
+    // anchors even when the user drags it far up/down. This avoids an abrupt
+    // connector-style flip from horizontal to vertical during manual layout.
+    if (target.x >= source.x + source.width - tolerance) return { sourceSide: 'right', targetSide: 'left' };
+    if (source.x >= target.x + target.width - tolerance) return { sourceSide: 'left', targetSide: 'right' };
+    const s = center(source);
+    const t = center(target);
+    return t.y >= s.y
+      ? { sourceSide: 'bottom', targetSide: 'top' }
+      : { sourceSide: 'top', targetSide: 'bottom' };
+  }
+  if (direction === 'vertical') {
+    if (target.y >= source.y + source.height - tolerance) return { sourceSide: 'bottom', targetSide: 'top' };
+    if (source.y >= target.y + target.height - tolerance) return { sourceSide: 'top', targetSide: 'bottom' };
+    const s = center(source);
+    const t = center(target);
+    return t.x >= s.x
+      ? { sourceSide: 'right', targetSide: 'left' }
+      : { sourceSide: 'left', targetSide: 'right' };
+  }
+  return smartAnchors(source, target);
+}
+
+function adaptiveLead(distance, preferred = 30) {
+  // Fixed 38px leads caused a classic router failure: when users moved two nodes
+  // closer than 76px, sourceLead and targetLead crossed and the connector formed a
+  // large U-shaped loop. Keep leads proportional to the actual free gap instead.
+  if (distance <= 0) return preferred;
+  const safeHalf = Math.max(2, distance / 2 - 2);
+  return Math.min(preferred, safeHalf, Math.max(6, distance * 0.28));
+}
+
+function horizontalFacingGap(sourceSide, targetSide, s, t) {
+  if (sourceSide === 'right' && targetSide === 'left') return t.x - s.x;
+  if (sourceSide === 'left' && targetSide === 'right') return s.x - t.x;
+  return -1;
+}
+
+function verticalFacingGap(sourceSide, targetSide, s, t) {
+  if (sourceSide === 'bottom' && targetSide === 'top') return t.y - s.y;
+  if (sourceSide === 'top' && targetSide === 'bottom') return s.y - t.y;
+  return -1;
+}
+
+function orthogonalRoute(model, edge, source, target) {
+  const { sourceSide, targetSide } = routedAnchors(model, source, target);
+  const s = anchor(source, sourceSide, connectionOffset(model, edge, 'source', sourceSide));
+  const t = anchor(target, targetSide, connectionOffset(model, edge, 'target', targetSide));
+  const horizontal = ['left', 'right'].includes(sourceSide);
+  let points;
+
+  if (horizontal && ['left', 'right'].includes(targetSide)) {
+    const facingGap = horizontalFacingGap(sourceSide, targetSide, s, t);
+    const sourceDirection = sourceSide === 'right' ? 1 : -1;
+    const targetDirection = targetSide === 'left' ? -1 : 1;
+
+    if (facingGap >= 0) {
+      // Forward / normally facing nodes. Leads always stay inside the available gap,
+      // therefore the route is monotonic on the primary axis and cannot produce a
+      // backtracking spike after manual node movement.
+      const lead = adaptiveLead(facingGap);
+      const sourceLead = { x: s.x + sourceDirection * lead, y: s.y };
+      const targetLead = { x: t.x + targetDirection * lead, y: t.y };
+
+      if (Math.abs(s.y - t.y) < 0.5) {
+        points = [s, t];
+      } else {
+        const mx = (sourceLead.x + targetLead.x) / 2;
+        points = [s, sourceLead, { x: mx, y: s.y }, { x: mx, y: t.y }, targetLead, t];
+      }
+
+      const blocker = routeHitsNode(model, points, edge);
+      if (blocker) {
+        const margin = 34;
+        const above = Math.min(source.y, target.y, blocker.y) - margin;
+        const below = Math.max(source.y + source.height, target.y + target.height, blocker.y + blocker.height) + margin;
+        const detourY = Math.abs(above - s.y) + Math.abs(above - t.y) < Math.abs(below - s.y) + Math.abs(below - t.y) ? above : below;
+        points = [s, sourceLead, { x: sourceLead.x, y: detourY }, { x: targetLead.x, y: detourY }, targetLead, t];
+      }
+    } else {
+      // True back-edge / overlapping ranks. Route around the pair, but keep the
+      // detour close to the nodes instead of using the old oversized 76px loop.
+      const lead = 24;
+      const sourceLead = { x: s.x + sourceDirection * lead, y: s.y };
+      const targetLead = { x: t.x + targetDirection * lead, y: t.y };
+      const margin = 32;
+      const above = Math.min(source.y, target.y) - margin;
+      const below = Math.max(source.y + source.height, target.y + target.height) + margin;
+      const detourY = Math.abs(above - s.y) + Math.abs(above - t.y) < Math.abs(below - s.y) + Math.abs(below - t.y) ? above : below;
+      points = [s, sourceLead, { x: sourceLead.x, y: detourY }, { x: targetLead.x, y: detourY }, targetLead, t];
+    }
+  } else if (!horizontal && ['top', 'bottom'].includes(targetSide)) {
+    const facingGap = verticalFacingGap(sourceSide, targetSide, s, t);
+    const sourceDirection = sourceSide === 'bottom' ? 1 : -1;
+    const targetDirection = targetSide === 'top' ? -1 : 1;
+
+    if (facingGap >= 0) {
+      const lead = adaptiveLead(facingGap);
+      const sourceLead = { x: s.x, y: s.y + sourceDirection * lead };
+      const targetLead = { x: t.x, y: t.y + targetDirection * lead };
+      if (Math.abs(s.x - t.x) < 0.5) {
+        points = [s, t];
+      } else {
+        const my = (sourceLead.y + targetLead.y) / 2;
+        points = [s, sourceLead, { x: s.x, y: my }, { x: t.x, y: my }, targetLead, t];
+      }
+      const blocker = routeHitsNode(model, points, edge);
+      if (blocker) {
+        const margin = 34;
+        const left = Math.min(source.x, target.x, blocker.x) - margin;
+        const right = Math.max(source.x + source.width, target.x + target.width, blocker.x + blocker.width) + margin;
+        const detourX = Math.abs(left - s.x) + Math.abs(left - t.x) < Math.abs(right - s.x) + Math.abs(right - t.x) ? left : right;
+        points = [s, sourceLead, { x: detourX, y: sourceLead.y }, { x: detourX, y: targetLead.y }, targetLead, t];
+      }
+    } else {
+      const lead = 24;
+      const sourceLead = { x: s.x, y: s.y + sourceDirection * lead };
+      const targetLead = { x: t.x, y: t.y + targetDirection * lead };
+      const margin = 32;
+      const left = Math.min(source.x, target.x) - margin;
+      const right = Math.max(source.x + source.width, target.x + target.width) + margin;
+      const detourX = Math.abs(left - s.x) + Math.abs(left - t.x) < Math.abs(right - s.x) + Math.abs(right - t.x) ? left : right;
+      points = [s, sourceLead, { x: detourX, y: sourceLead.y }, { x: detourX, y: targetLead.y }, targetLead, t];
+    }
+  } else {
+    // Mixed-side route (usually nodes overlap on the primary axis). Keep a compact
+    // two-bend connector and let collinear cleanup remove redundant points.
+    if (horizontal) {
+      const mx = (s.x + t.x) / 2;
+      points = [s, { x: mx, y: s.y }, { x: mx, y: t.y }, t];
+    } else {
+      const my = (s.y + t.y) / 2;
+      points = [s, { x: s.x, y: my }, { x: t.x, y: my }, t];
+    }
+  }
+  return points;
+}
+
+function dedupeCollinear(points) {
+  if (points.length <= 2) return points;
+  const out = [points[0]];
+  for (let i = 1; i < points.length - 1; i += 1) {
+    const a = out[out.length - 1];
+    const b = points[i];
+    const c = points[i + 1];
+    if (Math.hypot(a.x - b.x, a.y - b.y) < 0.1) continue;
+    const collinearX = Math.abs(a.x - b.x) < 0.01 && Math.abs(b.x - c.x) < 0.01;
+    const collinearY = Math.abs(a.y - b.y) < 0.01 && Math.abs(b.y - c.y) < 0.01;
+    if (!collinearX && !collinearY) out.push(b);
+  }
+  const last = points.at(-1);
+  if (Math.hypot(out.at(-1).x - last.x, out.at(-1).y - last.y) >= 0.1) out.push(last);
+  return out;
+}
+
+export function edgeWaypoints(model, edge) {
+  const source = getNode(model, edge.source);
+  const target = getNode(model, edge.target);
+  if (!source || !target) return [];
+  if (edge.waypoints?.length >= 2) return edge.waypoints;
+  return dedupeCollinear(orthogonalRoute(model, edge, source, target));
+}
+
+export function roundedPath(points, radius = 14) {
+  if (!points.length) return '';
+  if (points.length === 1) return `M ${points[0].x} ${points[0].y}`;
+  if (points.length === 2) return `M ${points[0].x} ${points[0].y} L ${points[1].x} ${points[1].y}`;
+
+  const distance = (a, b) => Math.hypot(a.x - b.x, a.y - b.y);
+  let d = `M ${points[0].x} ${points[0].y}`;
+  for (let i = 1; i < points.length - 1; i += 1) {
+    const prev = points[i - 1];
+    const cur = points[i];
+    const next = points[i + 1];
+    const r = Math.min(radius, distance(prev, cur) / 2, distance(cur, next) / 2);
+    const before = {
+      x: cur.x + (prev.x - cur.x) * (r / Math.max(distance(prev, cur), 1)),
+      y: cur.y + (prev.y - cur.y) * (r / Math.max(distance(prev, cur), 1)),
+    };
+    const after = {
+      x: cur.x + (next.x - cur.x) * (r / Math.max(distance(next, cur), 1)),
+      y: cur.y + (next.y - cur.y) * (r / Math.max(distance(next, cur), 1)),
+    };
+    d += ` L ${before.x} ${before.y} Q ${cur.x} ${cur.y} ${after.x} ${after.y}`;
+  }
+  const last = points.at(-1);
+  d += ` L ${last.x} ${last.y}`;
+  return d;
+}
+
+export function smoothPath(points, radius = 24) {
+  return roundedPath(points, Math.max(20, radius));
+}
+
+function graphRanks(model, candidates = null) {
+  const layoutNodes = candidates || model.nodes.filter(flowNode);
+  const byId = new Map(layoutNodes.map((node) => [node.id, node]));
+  const indegree = new Map(layoutNodes.map((node) => [node.id, 0]));
+  const incoming = new Map(layoutNodes.map((node) => [node.id, []]));
+  const outgoing = new Map(layoutNodes.map((node) => [node.id, []]));
+  const flows = model.edges.filter((edge) => (edge.type || 'sequenceFlow') === 'sequenceFlow' && byId.has(edge.source) && byId.has(edge.target));
+  for (const edge of flows) {
+    indegree.set(edge.target, indegree.get(edge.target) + 1);
+    incoming.get(edge.target).push(edge.source);
+    outgoing.get(edge.source).push(edge.target);
+  }
+
+  const priority = (node) => NODE_DEFINITIONS[node.type]?.eventStage === 'start' ? -100000 : (node.x + node.y / 10000);
+  const queue = layoutNodes.filter((node) => indegree.get(node.id) === 0).sort((a, b) => priority(a) - priority(b)).map((node) => node.id);
+  if (!queue.length && layoutNodes[0]) queue.push(layoutNodes[0].id);
+  const rank = new Map(queue.map((id) => [id, 0]));
+  const processed = new Set();
+
+  while (queue.length) {
+    const id = queue.shift();
+    if (processed.has(id)) continue;
+    processed.add(id);
+    const base = rank.get(id) || 0;
+    for (const target of outgoing.get(id) || []) {
+      rank.set(target, Math.max(rank.get(target) ?? 0, base + 1));
+      indegree.set(target, Math.max(0, indegree.get(target) - 1));
+      if (indegree.get(target) === 0) queue.push(target);
+    }
+  }
+
+  // Keep cycles compact: unresolved nodes receive a rank relative to the nearest processed predecessor.
+  let fallback = Math.max(0, ...rank.values());
+  for (const node of layoutNodes) {
+    if (rank.has(node.id)) continue;
+    const predecessorRanks = (incoming.get(node.id) || []).map((id) => rank.get(id)).filter((value) => value !== undefined);
+    rank.set(node.id, predecessorRanks.length ? Math.max(...predecessorRanks) + 1 : ++fallback);
+  }
+
+  return { layoutNodes, rank, incoming };
+}
+
+function orderRanks(layoutNodes, rank, incoming, direction) {
+  const groups = new Map();
+  for (const node of layoutNodes) {
+    const value = rank.get(node.id) || 0;
+    if (!groups.has(value)) groups.set(value, []);
+    groups.get(value).push(node);
+  }
+  const secondary = (node) => direction === 'vertical' ? node.x : node.y;
+  const placedIndex = new Map();
+  for (const [value, nodes] of [...groups.entries()].sort((a, b) => a[0] - b[0])) {
+    nodes.sort((a, b) => {
+      const aPred = (incoming.get(a.id) || []).map((id) => placedIndex.get(id)).filter((v) => v !== undefined);
+      const bPred = (incoming.get(b.id) || []).map((id) => placedIndex.get(id)).filter((v) => v !== undefined);
+      const aBary = aPred.length ? aPred.reduce((s, v) => s + v, 0) / aPred.length : secondary(a) / 100;
+      const bBary = bPred.length ? bPred.reduce((s, v) => s + v, 0) / bPred.length : secondary(b) / 100;
+      return aBary - bBary || secondary(a) - secondary(b);
+    });
+    nodes.forEach((node, index) => placedIndex.set(node.id, index));
+    groups.set(value, nodes);
+  }
+  return groups;
+}
+
+export const LAYOUT_DENSITIES = Object.freeze({
+  // rankGap is the visible gap between adjacent ranks, not center-to-center distance.
+  // Keep the default deliberately compact for enterprise approval diagrams; users can
+  // expand to spacious when presenting on a large canvas.
+  compact: Object.freeze({ rankGap: 68, nodeGap: 30, label: '紧凑' }),
+  balanced: Object.freeze({ rankGap: 92, nodeGap: 48, label: '标准' }),
+  spacious: Object.freeze({ rankGap: 136, nodeGap: 78, label: '舒展' }),
+});
+
+function laneAwareAutoLayout(model, options, densityPreset) {
+  const containment = resolveContainment(model);
+  const lanes = model.nodes.filter((node) => NODE_DEFINITIONS[node.type]?.kind === 'lane');
+  if (!lanes.length) return false;
+  const boundaryNodes = model.nodes.filter((node) => NODE_DEFINITIONS[node.type]?.kind === 'boundary');
+  const layoutNodes = model.nodes.filter((node) => flowNode(node) && NODE_DEFINITIONS[node.type]?.kind !== 'boundary');
+  const byId = new Map(layoutNodes.map((node) => [node.id, node]));
+  const { rank, incoming } = graphRanks(model, layoutNodes);
+  const orderedRanks = orderRanks(layoutNodes, rank, incoming, 'horizontal');
+  const rankGap = options.rankGap ?? densityPreset.rankGap;
+  const nodeGap = options.nodeGap ?? densityPreset.nodeGap;
+  const padding = CONTAINMENT_LIMITS.participantContentPadding;
+  const originalPositions = new Map(model.nodes.map((node) => [node.id, { x: node.x, y: node.y }]));
+  const assigned = new Set();
+  const membersByLane = new Map();
+
+  for (const lane of lanes) {
+    const laneInsets = getSwimlaneContentInsets(model, lane);
+    const members = (lane.properties?.flowNodeRefs || []).map((id) => byId.get(id)).filter(Boolean);
+    membersByLane.set(lane.id, members);
+    for (const member of members) assigned.add(member.id);
+    const groups = new Map();
+    for (const member of members) {
+      const value = rank.get(member.id) || 0;
+      const group = groups.get(value) || [];
+      group.push(member);
+      groups.set(value, group);
+    }
+    const requiredHeight = Math.max(
+      CONTAINMENT_LIMITS.laneMinHeight + laneInsets.top + laneInsets.bottom,
+      ...[...groups.values()].map((group) => (
+        group.reduce((sum, node) => sum + node.height, 0)
+        + Math.max(0, group.length - 1) * nodeGap
+        + padding * 2
+        + laneInsets.top
+        + laneInsets.bottom
+      )),
+    );
+    lane.height = Math.max(lane.height, requiredHeight);
+  }
+
+  for (const [participantId, participantLanes] of containment.lanesByParticipant) {
+    const participant = containment.nodesById.get(participantId);
+    if (!participant) continue;
+    const participantInsets = getSwimlaneContentInsets(model, participant);
+    participant.height = Math.max(
+      CONTAINMENT_LIMITS.participantMinHeight,
+      participantInsets.top
+        + participantLanes.reduce((sum, lane) => sum + lane.height, 0)
+        + participantInsets.bottom,
+    );
+  }
+  applyContainmentOperation(model, { type: 'reconcile', normalize: true });
+
+  const rankWidths = new Map();
+  for (const [value, nodes] of orderedRanks) {
+    const eligible = nodes.filter((node) => assigned.has(node.id));
+    if (eligible.length) rankWidths.set(value, Math.max(...eligible.map((node) => node.width), 56));
+  }
+  const ranks = [...rankWidths.keys()].sort((a, b) => a - b);
+  const rankOffsets = new Map();
+  let cursor = 0;
+  for (const value of ranks) {
+    rankOffsets.set(value, cursor);
+    cursor += rankWidths.get(value) + rankGap;
+  }
+  const contentWidth = Math.max(0, cursor - rankGap) + padding * 2;
+
+  for (const [participantId, participantLanes] of containment.lanesByParticipant) {
+    const participant = containment.nodesById.get(participantId);
+    if (!participant) continue;
+    const participantInsets = getSwimlaneContentInsets(model, participant);
+    const laneInsets = participantLanes[0]
+      ? getSwimlaneContentInsets(model, participantLanes[0])
+      : { top: 0, right: 0, bottom: 0, left: 0 };
+    participant.width = Math.max(
+      participant.width,
+      contentWidth + participantInsets.left + participantInsets.right + laneInsets.left + laneInsets.right,
+      CONTAINMENT_LIMITS.participantMinWidth,
+    );
+  }
+  for (const lane of lanes.filter((candidate) => !candidate.containerId)) {
+    const laneInsets = getSwimlaneContentInsets(model, lane);
+    lane.width = Math.max(
+      lane.width,
+      contentWidth + laneInsets.left + laneInsets.right,
+      CONTAINMENT_LIMITS.laneMinWidth,
+    );
+  }
+  applyContainmentOperation(model, { type: 'reconcile', normalize: true });
+
+  for (const lane of lanes) {
+    const groups = new Map();
+    for (const member of membersByLane.get(lane.id) || []) {
+      const value = rank.get(member.id) || 0;
+      const group = groups.get(value) || [];
+      group.push(member);
+      groups.set(value, group);
+    }
+    for (const [value, group] of groups) {
+      const content = getSwimlaneContentBounds(model, lane);
+      group.sort((a, b) => {
+        const aPred = (incoming.get(a.id) || []).map((id) => originalPositions.get(id)?.y).filter(Number.isFinite);
+        const bPred = (incoming.get(b.id) || []).map((id) => originalPositions.get(id)?.y).filter(Number.isFinite);
+        const aScore = aPred.length ? aPred.reduce((sum, y) => sum + y, 0) / aPred.length : originalPositions.get(a.id)?.y || 0;
+        const bScore = bPred.length ? bPred.reduce((sum, y) => sum + y, 0) / bPred.length : originalPositions.get(b.id)?.y || 0;
+        return aScore - bScore || a.id.localeCompare(b.id);
+      });
+      const totalHeight = group.reduce((sum, node) => sum + node.height, 0) + Math.max(0, group.length - 1) * nodeGap;
+      let y = content.y + Math.max(padding, (content.height - totalHeight) / 2);
+      const baseX = content.x + padding;
+      const maxWidth = rankWidths.get(value) || Math.max(...group.map((node) => node.width));
+      for (const member of group) {
+        member.x = Math.round(baseX + (rankOffsets.get(value) || 0) + (maxWidth - member.width) / 2);
+        member.y = Math.round(y);
+        y += member.height + nodeGap;
+      }
+    }
+  }
+
+  const unassigned = layoutNodes.filter((node) => !assigned.has(node.id));
+  if (unassigned.length) {
+    const bottom = Math.max(options.startY ?? 112, ...lanes.map((lane) => lane.y + lane.height + nodeGap));
+    autoLayout({
+      ...model,
+      nodes: unassigned,
+      edges: model.edges.filter((edge) => unassigned.some((node) => node.id === edge.source) && unassigned.some((node) => node.id === edge.target)),
+    }, { ...options, startY: bottom });
+  }
+
+  for (const boundary of boundaryNodes) {
+    const host = byId.get(boundary.properties?.attachedToRef);
+    const before = originalPositions.get(host?.id);
+    if (!host || !before) continue;
+    boundary.x = Math.round(boundary.x + host.x - before.x);
+    boundary.y = Math.round(boundary.y + host.y - before.y);
+  }
+  for (const edge of model.edges) edge.waypoints = null;
+  return true;
+}
+
+export function autoLayout(model, options = {}) {
+  const direction = options.direction || model.settings?.direction || 'horizontal';
+  const startX = options.startX ?? 112;
+  const startY = options.startY ?? 112;
+  const density = options.density || model.settings?.layoutDensity || (options.compact ? 'compact' : 'balanced');
+  const densityPreset = LAYOUT_DENSITIES[density] || LAYOUT_DENSITIES.balanced;
+  if (laneAwareAutoLayout(model, options, densityPreset)) return model;
+  const rankGap = options.rankGap ?? densityPreset.rankGap;
+  const nodeGap = options.nodeGap ?? densityPreset.nodeGap;
+  const { layoutNodes, rank, incoming } = graphRanks(model);
+  const groups = orderRanks(layoutNodes, rank, incoming, direction);
+  const ranks = [...groups.keys()].sort((a, b) => a - b);
+
+  if (direction === 'vertical') {
+    let y = startY;
+    for (const value of ranks) {
+      const nodes = groups.get(value);
+      const maxHeight = Math.max(...nodes.map((node) => node.height), 56);
+      const totalWidth = nodes.reduce((sum, node) => sum + node.width, 0) + Math.max(0, nodes.length - 1) * nodeGap;
+      let x = startX + Math.max(0, (920 - totalWidth) / 2);
+      for (const node of nodes) {
+        node.x = Math.round(x);
+        node.y = Math.round(y + (maxHeight - node.height) / 2);
+        x += node.width + nodeGap;
+      }
+      y += maxHeight + rankGap;
+    }
+  } else {
+    let x = startX;
+    for (const value of ranks) {
+      const nodes = groups.get(value);
+      const maxWidth = Math.max(...nodes.map((node) => node.width), 56);
+      const totalHeight = nodes.reduce((sum, node) => sum + node.height, 0) + Math.max(0, nodes.length - 1) * nodeGap;
+      let y = startY + Math.max(0, (640 - totalHeight) / 2);
+      for (const node of nodes) {
+        node.x = Math.round(x + (maxWidth - node.width) / 2);
+        node.y = Math.round(y);
+        y += node.height + nodeGap;
+      }
+      x += maxWidth + rankGap;
+    }
+  }
+
+  for (const edge of model.edges) edge.waypoints = null;
+  return model;
+}
+
+export function beautify(model, options = {}) {
+  autoLayout(model, options);
+  const grid = options.gridSize ?? model.settings?.gridSize ?? 16;
+  const snapToGrid = options.snapToGrid ?? model.settings?.snapToGrid ?? false;
+  // Do not quantize top-left coordinates by default. BPMN elements have
+  // different dimensions (events, gateways, tasks); top-left grid snapping
+  // destroys their center-line alignment even after a perfect auto layout.
+  if (snapToGrid) {
+    for (const node of model.nodes) {
+      if (!flowNode(node)) continue;
+      node.x = Math.round(node.x / grid) * grid;
+      node.y = Math.round(node.y / grid) * grid;
+    }
+  }
+  model.settings = {
+    ...(model.settings || {}),
+    direction: options.direction || model.settings?.direction || 'horizontal',
+    layoutDensity: options.density || model.settings?.layoutDensity || (options.compact ? 'compact' : 'balanced'),
+    edgeStyle: options.edgeStyle || 'rounded',
+    cornerRadius: options.cornerRadius ?? 16,
+    gridSize: grid,
+    snapToGrid,
+    alignmentThreshold: options.alignmentThreshold ?? model.settings?.alignmentThreshold ?? 7,
+    mergeGatewayConnections: options.mergeGatewayConnections ?? model.settings?.mergeGatewayConnections ?? true,
+  };
+  for (const edge of model.edges) {
+    edge.waypoints = null;
+    edge.routeStyle = model.settings.edgeStyle;
+    edge.cornerRadius = model.settings.cornerRadius;
+  }
+  return model;
+}