@statelyai/layout 0.3.0 → 0.4.0

package/src/elkjs/layout-quality.ts

@@ -0,0 +1,219 @@
+import type { ElkNode } from "./types";
+
+/** Geometry measures used to choose between candidate layouts of one graph. */
+export interface LayoutQuality {
+  /** Routes through leaf nodes, routes folded onto themselves, and diagonal segments. */
+  defects: number;
+  crossings: number;
+  overlap: number;
+  bends: number;
+  length: number;
+  area: number;
+}
+
+interface Point {
+  x: number;
+  y: number;
+}
+interface Rect extends Point {
+  width: number;
+  height: number;
+}
+interface Segment {
+  a: Point;
+  b: Point;
+}
+
+const EPS = 1e-6;
+/** Shared endpoint nodes get this clearance, so fan-in and fan-out are not penalized. */
+const TERMINAL_MARGIN = 12;
+const horizontal = (s: Segment) => Math.abs(s.a.y - s.b.y) < EPS;
+const vertical = (s: Segment) => Math.abs(s.a.x - s.b.x) < EPS;
+const span = (s: Segment, axis: "x" | "y") =>
+  [Math.min(s.a[axis], s.b[axis]), Math.max(s.a[axis], s.b[axis])] as const;
+const strictlyInside = (value: number, low: number, high: number) =>
+  value > low + EPS && value < high - EPS;
+const overlapLength = (a: readonly [number, number], b: readonly [number, number]) =>
+  Math.max(0, Math.min(a[1], b[1]) - Math.max(a[0], b[0]));
+const inRect = (point: Point, rect: Rect, margin: number) =>
+  point.x > rect.x - margin &&
+  point.x < rect.x + rect.width + margin &&
+  point.y > rect.y - margin &&
+  point.y < rect.y + rect.height + margin;
+
+/** Measure an ELK JSON result in absolute coordinates. */
+export function measureLayout(root: ElkNode): LayoutQuality {
+  const frames = new Map<string, Point>([[String(root.id), { x: 0, y: 0 }]]);
+  const rects = new Map<string, Rect>();
+  const owner = new Map<string, string>();
+  const leaves: Rect[] = [];
+  const bounds: Point[] = [];
+  const place = (parent: ElkNode, offset: Point) => {
+    for (const child of parent.children ?? []) {
+      const id = String(child.id);
+      const at = { x: offset.x + (child.x ?? 0), y: offset.y + (child.y ?? 0) };
+      const rect = { ...at, width: child.width ?? 0, height: child.height ?? 0 };
+      frames.set(id, at);
+      rects.set(id, rect);
+      owner.set(id, id);
+      for (const port of child.ports ?? []) owner.set(String(port.id), id);
+      bounds.push(at, { x: at.x + rect.width, y: at.y + rect.height });
+      if (child.children?.length) place(child, at);
+      else leaves.push(rect);
+    }
+  };
+  place(root, { x: 0, y: 0 });
+
+  const routes: Array<{ ends: string[]; segments: Segment[]; labels: Rect[] }> = [];
+  let defects = 0,
+    bends = 0,
+    length = 0;
+  const collect = (parent: ElkNode) => {
+    for (const edge of parent.edges ?? []) {
+      const container = String((edge as { container?: string }).container ?? parent.id);
+      const offset = frames.get(container) ?? { x: 0, y: 0 };
+      const ends = [edge.sources?.[0], edge.targets?.[0]].flatMap((end) => {
+        const node = owner.get(String(end));
+        return node === undefined ? [] : [node];
+      });
+      const segments: Segment[] = [];
+      for (const section of edge.sections ?? []) {
+        const points = [section.startPoint, ...(section.bendPoints ?? []), section.endPoint].map(
+          (point) => ({ x: point.x + offset.x, y: point.y + offset.y }),
+        );
+        bounds.push(...points);
+        let direction: Point | undefined;
+        for (let index = 0; index + 1 < points.length; index++) {
+          const segment = { a: points[index]!, b: points[index + 1]! };
+          const size = Math.hypot(segment.b.x - segment.a.x, segment.b.y - segment.a.y);
+          if (size < EPS) continue;
+          if (!horizontal(segment) && !vertical(segment)) defects++;
+          const next = {
+            x: Math.sign(segment.b.x - segment.a.x),
+            y: Math.sign(segment.b.y - segment.a.y),
+          };
+          if (direction && (direction.x !== next.x || direction.y !== next.y)) bends++;
+          direction = next;
+          length += size;
+          segments.push(segment);
+        }
+      }
+      const labels = (edge.labels ?? []).flatMap((label) =>
+        label.width && label.height
+          ? [
+              {
+                x: (label.x ?? 0) + offset.x,
+                y: (label.y ?? 0) + offset.y,
+                width: label.width,
+                height: label.height,
+              },
+            ]
+          : [],
+      );
+      for (const label of labels)
+        bounds.push(label, { x: label.x + label.width, y: label.y + label.height });
+      // A route through a leaf, or folding back onto itself, is a defect.
+      for (const segment of segments)
+        for (const rect of leaves)
+          if (
+            (horizontal(segment) &&
+              strictlyInside(segment.a.y, rect.y, rect.y + rect.height) &&
+              overlapLength(span(segment, "x"), [rect.x, rect.x + rect.width]) > EPS) ||
+            (vertical(segment) &&
+              strictlyInside(segment.a.x, rect.x, rect.x + rect.width) &&
+              overlapLength(span(segment, "y"), [rect.y, rect.y + rect.height]) > EPS)
+          )
+            defects++;
+      for (const [index, first] of segments.entries())
+        for (const second of segments.slice(index + 1))
+          if (sharedLength(first, second) > EPS) defects++;
+      routes.push({ ends, segments, labels });
+    }
+    for (const child of parent.children ?? []) collect(child);
+  };
+  collect(root);
+
+  // Labels covering nodes or each other, and routes through other edges'
+  // labels, are defects.
+  const allLabels = routes.flatMap((route) => route.labels);
+  const covers = (a: Rect, b: Rect) =>
+    a.x < b.x + b.width - EPS &&
+    a.x + a.width > b.x + EPS &&
+    a.y < b.y + b.height - EPS &&
+    a.y + a.height > b.y + EPS;
+  for (const [index, label] of allLabels.entries()) {
+    for (const rect of leaves) if (covers(label, rect)) defects++;
+    for (const other of allLabels.slice(index + 1)) if (covers(label, other)) defects++;
+  }
+  for (const route of routes)
+    for (const other of routes)
+      if (other !== route)
+        for (const label of other.labels)
+          if (
+            route.segments.some(
+              (segment) =>
+                (horizontal(segment) &&
+                  strictlyInside(segment.a.y, label.y, label.y + label.height) &&
+                  overlapLength(span(segment, "x"), [label.x, label.x + label.width]) > EPS) ||
+                (vertical(segment) &&
+                  strictlyInside(segment.a.x, label.x, label.x + label.width) &&
+                  overlapLength(span(segment, "y"), [label.y, label.y + label.height]) > EPS),
+            )
+          )
+            defects++;
+
+  let crossings = 0,
+    overlap = 0;
+  for (const [index, first] of routes.entries())
+    for (const second of routes.slice(index + 1)) {
+      const shared = first.ends
+        .filter((id) => second.ends.includes(id))
+        .flatMap((id) => {
+          const rect = rects.get(id);
+          return rect ? [rect] : [];
+        });
+      const clear = (point: Point) => shared.every((rect) => !inRect(point, rect, TERMINAL_MARGIN));
+      for (const s of first.segments)
+        for (const t of second.segments) {
+          const h = horizontal(s) && vertical(t) ? s : horizontal(t) && vertical(s) ? t : undefined;
+          if (h) {
+            const v = h === s ? t : s;
+            const point = { x: v.a.x, y: h.a.y };
+            if (
+              strictlyInside(point.x, ...span(h, "x")) &&
+              strictlyInside(point.y, ...span(v, "y")) &&
+              clear(point)
+            )
+              crossings++;
+            continue;
+          }
+          const shared = sharedLength(s, t);
+          if (shared > EPS && clear(s.a) && clear(s.b)) overlap += shared;
+        }
+    }
+  const xs = bounds.map((point) => point.x).filter(Number.isFinite),
+    ys = bounds.map((point) => point.y).filter(Number.isFinite);
+  const area = xs.length
+    ? (Math.max(...xs) - Math.min(...xs)) * (Math.max(...ys) - Math.min(...ys))
+    : 0;
+  return { defects, crossings, overlap, bends, length, area };
+}
+
+function sharedLength(s: Segment, t: Segment): number {
+  if (horizontal(s) && horizontal(t) && Math.abs(s.a.y - t.a.y) < EPS)
+    return overlapLength(span(s, "x"), span(t, "x"));
+  if (vertical(s) && vertical(t) && Math.abs(s.a.x - t.a.x) < EPS)
+    return overlapLength(span(s, "y"), span(t, "y"));
+  return 0;
+}
+
+const TOLERANCE = 0.02;
+/** True when `candidate` is better at the first measure where the two layouts differ. */
+export function isBetterLayout(candidate: LayoutQuality, current: LayoutQuality): boolean {
+  for (const key of ["defects", "crossings", "overlap", "bends", "length", "area"] as const) {
+    const tolerant = key === "overlap" || key === "length" || key === "area";
+    const limit = tolerant ? Math.max(TOLERANCE * Math.abs(current[key]), EPS) : 0;
+    if (Math.abs(candidate[key] - current[key]) > limit) return candidate[key] < current[key];
+  }
+  return false;
+}

package/src/elkjs/opposing-tracks.ts

@@ -0,0 +1,161 @@
+import {
+  separateOpposingTracks,
+  type TrackPoint,
+  type TrackPort,
+  type TrackRect,
+  type TrackRoute,
+} from "../layered/opposing-tracks";
+import type { ElkEdge, ElkNode } from "./types";
+
+const option = (options: Readonly<Record<string, unknown>> | undefined, suffix: string) =>
+  Object.entries(options ?? {}).find(([key]) => key === suffix || key.endsWith(`.${suffix}`))?.[1];
+
+/**
+ * Separate opposite-direction track sharing in a finished ELK JSON layout,
+ * across nested containers, in world coordinates.
+ */
+export function separateElkOpposingTracks(
+  root: ElkNode,
+  options: Readonly<Record<string, unknown>>,
+): void {
+  const orthogonal = (node: ElkNode, inherited: boolean) => {
+    const value = option(node.layoutOptions, "edgeRouting");
+    return value === undefined ? inherited : String(value) === "ORTHOGONAL";
+  };
+  const rootOrthogonal = orthogonal(
+    root,
+    String(option(options, "edgeRouting") ?? "ORTHOGONAL") === "ORTHOGONAL",
+  );
+  const frames = new Map<string, TrackPoint>([[String(root.id), { x: 0, y: 0 }]]);
+  const routing = new Map<string, boolean>([[String(root.id), rootOrthogonal]]);
+  const nodes = new Map<string, TrackRect>(),
+    leaves = new Set<string>(),
+    owner = new Map<string, string>(),
+    ports = new Map<string, TrackPort>();
+  const place = (parent: ElkNode, offset: TrackPoint) => {
+    for (const child of parent.children ?? []) {
+      const id = String(child.id);
+      const at = { x: offset.x + (child.x ?? 0), y: offset.y + (child.y ?? 0) };
+      frames.set(id, at);
+      routing.set(id, orthogonal(child, routing.get(String(parent.id)) ?? rootOrthogonal));
+      nodes.set(id, { ...at, width: child.width ?? 0, height: child.height ?? 0 });
+      owner.set(id, id);
+      for (const port of child.ports ?? []) {
+        owner.set(String(port.id), id);
+        ports.set(String(port.id), {
+          node: id,
+          rect: {
+            x: at.x + (port.x ?? 0),
+            y: at.y + (port.y ?? 0),
+            width: port.width ?? 0,
+            height: port.height ?? 0,
+          },
+        });
+      }
+      if (child.children?.length) place(child, at);
+      else leaves.add(id);
+    }
+  };
+  place(root, { x: 0, y: 0 });
+  const records: Array<{ edge: ElkEdge; offset: TrackPoint; route: TrackRoute }> = [];
+  const collect = (parent: ElkNode) => {
+    for (const edge of parent.edges ?? []) {
+      // Multi-section routes are not single polylines; leave them unmeasured.
+      if ((edge.sections?.length ?? 0) > 1) continue;
+      const container = String(edge.container ?? parent.id);
+      const offset = frames.get(container) ?? { x: 0, y: 0 };
+      const sections = edge.sections ?? [];
+      const points = sections.flatMap((section) =>
+        [section.startPoint, ...(section.bendPoints ?? []), section.endPoint].map((p) => ({
+          x: p.x + offset.x,
+          y: p.y + offset.y,
+        })),
+      );
+      const axisParallel = points.every(
+        (p, i) =>
+          i === 0 ||
+          Math.abs(p.x - points[i - 1]!.x) < 1e-6 ||
+          Math.abs(p.y - points[i - 1]!.y) < 1e-6,
+      );
+      const ends = [edge.sources?.[0] ?? edge.source, edge.targets?.[0] ?? edge.target].flatMap(
+        (end) => {
+          const id = owner.get(String(end));
+          return id === undefined ? [] : [id];
+        },
+      );
+      const portOf = (end: unknown) => (ports.has(String(end)) ? String(end) : undefined);
+      records.push({
+        edge,
+        offset,
+        route: {
+          id: String(edge.id),
+          ends,
+          points,
+          ports: [
+            portOf(edge.sources?.[0] ?? edge.source),
+            portOf(edge.targets?.[0] ?? edge.target),
+          ],
+          labels: (edge.labels ?? []).flatMap((label) =>
+            label.width && label.height
+              ? [
+                  {
+                    x: (label.x ?? 0) + offset.x,
+                    y: (label.y ?? 0) + offset.y,
+                    width: label.width,
+                    height: label.height,
+                  },
+                ]
+              : [],
+          ),
+          movable: points.length > 0 && axisParallel && (routing.get(container) ?? rootOrthogonal),
+        },
+      });
+    }
+    for (const child of parent.children ?? []) collect(child);
+  };
+  collect(root);
+  if (!records.some((record) => record.route.movable)) return;
+  const spacing = Number(option(options, "spacing.edgeEdge") ?? 10);
+  const changed = separateOpposingTracks({
+    routes: records.map((record) => record.route),
+    nodes,
+    leaves,
+    ports,
+    spacing: Number.isFinite(spacing) && spacing > 0 ? spacing : 10,
+  });
+  if (!changed.size) return;
+  const routes = new Map(
+    records.map((record) => [record.route.id, changed.get(record.route.id) ?? record.route.points]),
+  );
+  const on = (point: TrackPoint, points: readonly TrackPoint[]) =>
+    points.some((b, i) => {
+      const a = points[i - 1];
+      return (
+        a !== undefined &&
+        point.x >= Math.min(a.x, b.x) - 1e-6 &&
+        point.x <= Math.max(a.x, b.x) + 1e-6 &&
+        point.y >= Math.min(a.y, b.y) - 1e-6 &&
+        point.y <= Math.max(a.y, b.y) + 1e-6
+      );
+    });
+  for (const { edge, offset, route } of records) {
+    const points = changed.get(route.id);
+    if (points) {
+      const section = edge.sections![0]!;
+      const local = points.map((p) => ({ x: p.x - offset.x, y: p.y - offset.y }));
+      section.startPoint = local[0]!;
+      section.endPoint = local.at(-1)!;
+      section.bendPoints = local.slice(1, -1);
+    }
+    // A junction marks where routes part; keep only those still shared.
+    if (!edge.junctionPoints?.length) continue;
+    const own = routes.get(route.id)!;
+    edge.junctionPoints = edge.junctionPoints.filter((junction) => {
+      const point = { x: junction.x + offset.x, y: junction.y + offset.y };
+      return (
+        on(point, own) && [...routes].some(([id, other]) => id !== route.id && on(point, other))
+      );
+    });
+    if (!edge.junctionPoints.length) delete edge.junctionPoints;
+  }
+}

package/src/elkjs/orthogonal-junctions.ts

@@ -0,0 +1,174 @@
+/*******************************************************************************
+ * Copyright (c) 2010, 2020 Kiel University and others.
+ * Adapted from ELK v0.11.0 BaseRoutingDirectionStrategy junction generation.
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+import type { ElkNode, ElkPoint } from "./types";
+import {
+  createOrthogonalHypersegments,
+  type OrthogonalPort,
+} from "../layered/orthogonal-hypersegments";
+/** Reconstruct native segment spans from final orthogonal tracks, then emit ELK's unique junctions. */
+export function applyOrthogonalJunctions(
+  root: ElkNode,
+  horizontal: boolean,
+  increasing: boolean,
+  mergeEdges: boolean,
+  hypernodes: ReadonlySet<string>,
+  preservedEdges: ReadonlySet<string>,
+) {
+  const edges = root.edges ?? [],
+    ports: OrthogonalPort[] = [],
+    byPort = new Map<string, OrthogonalPort>();
+  const explicit = new Map(
+    (root.children ?? []).flatMap((n) => (n.ports ?? []).map((p) => [String(p.id), n] as const)),
+  );
+  const owner = new Map((root.children ?? []).map((node) => [String(node.id), node]));
+  for (const [id, node] of explicit) owner.set(id, node);
+  const records = edges.flatMap((edge, index) => {
+    if (preservedEdges.has(String(edge.id))) return [];
+    const sourceOwner = owner.get(String(edge.sources?.[0] ?? edge.source));
+    if (
+      sourceOwner !== undefined &&
+      sourceOwner === owner.get(String(edge.targets?.[0] ?? edge.target))
+    )
+      return [];
+    const section = edge.sections?.[0];
+    if (!section || edge.sections?.length !== 1) return [];
+    let points = [section.startPoint, ...(section.bendPoints ?? []), section.endPoint];
+    if (
+      points.some(
+        (p, i) =>
+          i > 0 &&
+          Math.abs(p.x - points[i - 1]!.x) > 1e-3 &&
+          Math.abs(p.y - points[i - 1]!.y) > 1e-3,
+      )
+    )
+      return [];
+    let source = String(edge.sources?.[0] ?? edge.source),
+      target = String(edge.targets?.[0] ?? edge.target);
+    const flow = (p: ElkPoint) => (horizontal ? p.x : p.y);
+    if (flow(points[0]!) > flow(points.at(-1)!) === increasing) {
+      points = [...points].reverse();
+      [source, target] = [target, source];
+    }
+    const key = (ref: string, side: "source" | "target") =>
+      explicit.has(ref)
+        ? JSON.stringify(["port", ref])
+        : mergeEdges || hypernodes.has(ref)
+          ? JSON.stringify(["implicit", ref, side])
+          : JSON.stringify(["edge", index, side]);
+    return [{ edge, points, source: key(source, "source"), target: key(target, "target") }];
+  });
+  const cross = (p: ElkPoint) => (horizontal ? p.y : p.x),
+    flow = (p: ElkPoint) => (horizontal ? p.x : p.y);
+  for (const side of ["source", "target"] as const) {
+    const ordered = [...records].sort(
+      (a, b) =>
+        cross(side === "source" ? a.points[0]! : a.points.at(-1)!) -
+        cross(side === "source" ? b.points[0]! : b.points.at(-1)!),
+    );
+    for (const record of ordered) {
+      const id = record[side];
+      if (!byPort.has(id)) {
+        const port = {
+          id,
+          side,
+          position: cross(side === "source" ? record.points[0]! : record.points.at(-1)!),
+        };
+        byPort.set(id, port);
+        ports.push(port);
+      }
+    }
+  }
+  const grouped = createOrthogonalHypersegments(
+    ports,
+    records.map((r) => ({ source: r.source, target: r.target })),
+  );
+  const created = new Set<string>();
+  for (const group of grouped.segments) {
+    const members = records.filter((r) => group.ports.includes(r.source));
+    // Restoring a north/south endpoint may add an elbow after routing. A
+    // singleton connection has no branch; that elbow is not a junction.
+    if (members.length === 1) {
+      delete members[0]!.edge.junctionPoints;
+      continue;
+    }
+    const tracks = new Map<
+      number,
+      { start: number; end: number; incoming: number[]; outgoing: number[] }
+    >();
+    const track = (point: ElkPoint) => {
+      const key = flow(point);
+      let t = tracks.get(key);
+      if (!t) {
+        t = { start: Infinity, end: -Infinity, incoming: [], outgoing: [] };
+        tracks.set(key, t);
+      }
+      t.start = Math.min(t.start, cross(point));
+      t.end = Math.max(t.end, cross(point));
+      return t;
+    };
+    for (const r of members) {
+      const bends = r.points.slice(1, -1);
+      if (!bends.length) continue;
+      for (const p of bends) track(p);
+      track(bends[0]!).incoming.push(cross(bends[0]!));
+      track(bends.at(-1)!).outgoing.push(cross(bends.at(-1)!));
+      for (let i = 1; i < bends.length; i++)
+        if (Math.abs(flow(bends[i]!) - flow(bends[i - 1]!)) > 1e-3) {
+          track(bends[i - 1]!).outgoing.push(cross(bends[i - 1]!));
+          track(bends[i]!).incoming.push(cross(bends[i]!));
+        }
+    }
+    for (const r of members.filter((r) => r.points.length === 2)) {
+      const start = Math.min(flow(r.points[0]!), flow(r.points[1]!));
+      const end = Math.max(flow(r.points[0]!), flow(r.points[1]!));
+      for (const [position, t] of tracks) {
+        if (position < start || position > end) continue;
+        t.incoming.push(cross(r.points[0]!));
+        t.outgoing.push(cross(r.points[1]!));
+      }
+    }
+    // Long-edge joining removes collinear dummy anchors. A straight backbone
+    // still intersects every intermediate routing track it physically spans.
+    for (const r of members) {
+      for (let index = 1; index < r.points.length; index++) {
+        const a = r.points[index - 1]!,
+          b = r.points[index]!;
+        if (Math.abs(cross(a) - cross(b)) >= 1e-3) continue;
+        const start = Math.min(flow(a), flow(b)),
+          end = Math.max(flow(a), flow(b));
+        for (const [position, t] of tracks) {
+          if (position <= start || position >= end) continue;
+          t.incoming.push(cross(a));
+          t.outgoing.push(cross(b));
+        }
+      }
+    }
+    for (const t of tracks.values()) {
+      t.start = Math.min(t.start, ...t.incoming, ...t.outgoing);
+      t.end = Math.max(t.end, ...t.incoming, ...t.outgoing);
+    }
+    for (const port of group.ports)
+      for (const r of members.filter((r) => r.source === port)) {
+        delete r.edge.junctionPoints;
+        for (const p of r.points.slice(1, -1)) {
+          const t = tracks.get(flow(p))!,
+            value = cross(p),
+            key = `${p.x}:${p.y}`;
+          const boundary =
+            t.incoming.length &&
+            t.outgoing.length &&
+            ((Math.abs(value - Math.min(...t.incoming)) < 1e-3 &&
+              Math.abs(value - Math.min(...t.outgoing)) < 1e-3) ||
+              (Math.abs(value - Math.max(...t.incoming)) < 1e-3 &&
+                Math.abs(value - Math.max(...t.outgoing)) < 1e-3));
+          if (!created.has(key) && ((value > t.start && value < t.end) || boundary)) {
+            (r.edge.junctionPoints ??= []).push({ ...p });
+            created.add(key);
+          }
+        }
+      }
+  }
+}

package/src/elkjs/statechart.ts

@@ -178,8 +178,14 @@ export function scoreStatechartLayout(
       height: shape.height ?? 0,
     };
   };
-  const visit = (node: ElkNode, x: number, y: number, ancestors: ElkNode[]) => {
-    const direction = String(option(node, "direction") ?? "RIGHT").toUpperCase();
+  const visit = (
+    node: ElkNode,
+    x: number,
+    y: number,
+    ancestors: ElkNode[],
+    inheritedDirection = "RIGHT",
+  ) => {
+    const direction = String(option(node, "direction") ?? inheritedDirection).toUpperCase();
     const horizontal = direction === "RIGHT" || direction === "LEFT";
     const sign = direction === "LEFT" || direction === "UP" ? -1 : 1;
     const path = paths[String(node.id)] ?? [];
@@ -199,7 +205,7 @@ export function scoreStatechartLayout(
       )
         score.invalid++;
       boxes.push({ rect: box, ancestors, node: child });
-      visit(child, box.x, box.y, [...ancestors, child]);
+      visit(child, box.x, box.y, [...ancestors, child], direction);
     }
     for (const edge of node.edges ?? []) {
       if (String(option(edge, "noLayout")).toLowerCase() === "true") continue;

package/src/elkjs/types.ts

@@ -35,6 +35,8 @@ export interface ElkEdgeSection extends ElkGraphElement {
 }
 
 export interface ElkEdge extends ElkGraphElement {
+  /** Node whose coordinate frame contains the exported route. */
+  container?: ElkId;
   sources?: ElkId[];
   targets?: ElkId[];
   source?: ElkId;

package/src/index.ts

@@ -96,6 +96,8 @@ export type {
 } from "./layered";
 
 export { c } from "./constraints";
+export { hint, statechartHints } from "./layered/hints";
+export type { AnchorHint, ChainHint, HintStrength, LayoutHint } from "./layered/hints";
 export type {
   LayoutConstraint,
   GeometryReference,

package/src/internal/elkjs-compatibility.ts

@@ -1,6 +1,9 @@
-import type { VisualGraph } from "@statelyai/graph";
+import type { VisualGraph, Point } from "@statelyai/graph";
 
 export interface Elkjs0111ResultPolicy {
+  junctionPointsByEdgeId?: ReadonlyMap<string, readonly Point[]>;
+  placementCrossBounds?: { axis: "x" | "y"; maximum: number };
+  normalizationBounds?: { left: number; top: number; right: number; bottom: number };
   providerBounds?: { width: number; height: number };
   preserveEdgeSections?: boolean;
   skipBoundsNormalization?: boolean;

package/src/internal/layered-trace.ts

@@ -0,0 +1,48 @@
+/** Development-only phase observations for differential tracing against real ELK. */
+export type LayeredTraceEvent =
+  | {
+      kind: "sweep";
+      scope: string;
+      attempt: number;
+      forward: boolean;
+      firstSweep: boolean;
+      crossings: number;
+      layers: readonly (readonly string[])[];
+    }
+  | {
+      kind: "port-lists";
+      scope: string;
+      ports: ReadonlyMap<
+        string,
+        readonly { name?: string; outgoing: readonly string[]; incoming: readonly string[] }[]
+      >;
+    }
+  | {
+      kind: "initial-order";
+      scope: string;
+      layers: readonly (readonly string[])[];
+    }
+  | {
+      kind: "crossing-order";
+      scope: string;
+      edgeIds: readonly string[];
+      reversedEdgeIds: readonly string[];
+      layerByNodeId: ReadonlyMap<string, number>;
+      layers: readonly (readonly string[])[];
+    };
+
+let observer: ((event: LayeredTraceEvent) => void) | undefined;
+
+/** Install an observer and return the previous one. Production code never sets one. */
+export function setLayeredTraceObserver(
+  next: ((event: LayeredTraceEvent) => void) | undefined,
+): ((event: LayeredTraceEvent) => void) | undefined {
+  const previous = observer;
+  observer = next;
+  return previous;
+}
+
+/** Build and emit an event only while an observer is installed. */
+export function traceLayeredPhase(event: () => LayeredTraceEvent): void {
+  observer?.(event());
+}

package/src/internal/layout-engine.ts

@@ -1,7 +1,7 @@
 import type { Graph, VisualGraph } from "@statelyai/graph";
 import { boxAlgorithm, elkjs0111BoxAlgorithm, type BoxLayoutOptions } from "../box";
 import { fixedAlgorithm, type FixedLayoutOptions } from "../fixed";
-import { layeredAlgorithm, type LayeredLayoutOptions } from "../layered";
+import { layeredAlgorithm, elkjs0111LayeredAlgorithm, type LayeredLayoutOptions } from "../layered";
 import {
   elkjs0111RectanglePackingAlgorithm,
   rectanglePackingAlgorithm,
@@ -43,6 +43,7 @@ const elkjs0111LayoutAlgorithms = {
   ...builtInLayoutAlgorithms,
   box: elkjs0111BoxAlgorithm,
   random: elkjs0111RandomAlgorithm,
+  layered: elkjs0111LayeredAlgorithm,
   rectpacking: elkjs0111RectanglePackingAlgorithm,
 } satisfies {
   [Id in BuiltInLayoutAlgorithmId]: LayoutAlgorithm<BuiltInLayoutOptionsById[Id]>;