@statelyai/layout 0.2.0 → 0.3.0

package/dist/types-CT2akdK0.d.mts

@@ -0,0 +1,133 @@
+import { EntityRect, Graph, GraphDiff, Point } from "@statelyai/graph";
+
+//#region src/routing/types.d.ts
+type RoutePoint = Readonly<Point>;
+type RouteSegment = {
+  readonly kind: "line";
+  readonly to: RoutePoint;
+} | {
+  readonly kind: "quadratic";
+  readonly control: RoutePoint;
+  readonly to: RoutePoint;
+} | {
+  readonly kind: "cubic";
+  readonly control1: RoutePoint;
+  readonly control2: RoutePoint;
+  readonly to: RoutePoint;
+} | {
+  readonly kind: "arc";
+  readonly rx: number;
+  readonly ry: number;
+  readonly rotation: number;
+  readonly largeArc: boolean;
+  readonly sweep: boolean;
+  readonly to: RoutePoint;
+};
+interface RoutePath {
+  readonly start: RoutePoint;
+  readonly segments: readonly RouteSegment[];
+}
+type RouteEndpoint = {
+  readonly kind: "node";
+  readonly nodeId: string;
+  readonly port?: string;
+} | {
+  readonly kind: "label";
+  readonly edgeId: string;
+} | {
+  readonly kind: "junction";
+  readonly id: string;
+};
+interface RouteSection {
+  readonly id: string;
+  readonly from: RouteEndpoint;
+  readonly to: RouteEndpoint;
+  readonly path: RoutePath;
+  /** Same ID denotes a shared trunk; render it once. */
+  readonly sharedId?: string;
+}
+type RoutingDiagnosticCode = "MISSING_GEOMETRY" | "MISSING_PORT" | "ROUTE_CONFLICT" | "ROUTE_BLOCKED" | "SEARCH_BUDGET" | "CONSTRAINT_VIOLATION";
+interface RoutingDiagnostic {
+  readonly code: RoutingDiagnosticCode;
+  readonly edgeId: string;
+  readonly message: string;
+}
+interface Route {
+  readonly edgeId: string;
+  readonly sections: readonly RouteSection[];
+  readonly status: "routed" | "fallback";
+  readonly diagnostics: readonly RoutingDiagnostic[];
+}
+type RoutePatch = {
+  readonly op: "set";
+  readonly edgeId: string;
+  readonly route: Route;
+} | {
+  readonly op: "delete";
+  readonly edgeId: string;
+};
+type RouteStyle = "straight" | "bezier" | "orthogonal" | "polyline" | "octilinear" | "curved" | "organic" | "parallel" | "self-loop" | "fan" | "bus" | "bundle";
+type RouteSide = "left" | "right" | "top" | "bottom";
+interface RouteAttachment {
+  /** Node-local attachment rectangle, independent of its outer obstacle bounds. */
+  readonly bounds: RouteBounds;
+  readonly facing?: "inward" | "outward";
+}
+interface EdgeRoutingSettings {
+  readonly sourceAttachment?: RouteAttachment;
+  readonly targetAttachment?: RouteAttachment;
+  readonly sourceSide?: RouteSide;
+  readonly targetSide?: RouteSide;
+  readonly waypoints?: readonly RoutePoint[];
+  /** Explicit shared routing group. Native binary edges describe branches of a net. */
+  readonly group?: string;
+}
+interface RoutingSettings {
+  /** Native compound geometry is parent-relative; adapters may supply resolved world geometry. */
+  readonly coordinateSpace?: "parent" | "world";
+  readonly clearance?: number;
+  readonly radius?: number;
+  readonly edgeSpacing?: number;
+  readonly bendPenalty?: number;
+  /** Soft cost per crossing; finite costs keep detours proportionate. Default 80. */
+  readonly crossingPenalty?: number;
+  /** Cost per unit of parallel overlap within edgeSpacing. Default 8. */
+  readonly overlapPenalty?: number;
+  readonly maxSearchNodes?: number;
+  readonly organicIterations?: number;
+  readonly edges?: Readonly<Record<string, EdgeRoutingSettings>>;
+}
+interface RoutingMetrics {
+  readonly routedEdges: number;
+  readonly reusedEdges: number;
+  readonly affectedEdges: number;
+  readonly searchNodes: number;
+  readonly obstacleCandidates: number;
+}
+/** Immutable value. Retain it per canvas; the private state uses structural sharing. */
+interface RoutingSnapshot {
+  readonly strategy: string;
+  readonly revision: number;
+  readonly routes: ReadonlyMap<string, Route>;
+  readonly metrics: RoutingMetrics;
+}
+interface RoutingUpdate {
+  readonly snapshot: RoutingSnapshot;
+  readonly patches: readonly RoutePatch[];
+  /** Compare identity before accepting an asynchronous result. */
+  readonly base: RoutingSnapshot;
+}
+type RoutingGraph = Graph<unknown, unknown, unknown, unknown>;
+interface RoutingStrategy {
+  readonly id: string;
+  route(graph: RoutingGraph, settings?: RoutingSettings): RoutingSnapshot | Promise<RoutingSnapshot>;
+  update(graph: RoutingGraph, previous: RoutingSnapshot, diff: GraphDiff<unknown, unknown>, settings?: RoutingSettings): RoutingUpdate | Promise<RoutingUpdate>;
+}
+interface NativeRoutingStrategy extends RoutingStrategy {
+  readonly id: RouteStyle;
+  route(graph: RoutingGraph, settings?: RoutingSettings): RoutingSnapshot;
+  update(graph: RoutingGraph, previous: RoutingSnapshot, diff: GraphDiff<unknown, unknown>, settings?: RoutingSettings): RoutingUpdate;
+}
+type RouteBounds = Readonly<EntityRect>;
+//#endregion
+export { RoutingMetrics as _, RouteBounds as a, RoutingStrategy as b, RoutePath as c, RouteSegment as d, RouteSide as f, RoutingGraph as g, RoutingDiagnosticCode as h, RouteAttachment as i, RoutePoint as l, RoutingDiagnostic as m, NativeRoutingStrategy as n, RouteEndpoint as o, RouteStyle as p, Route as r, RoutePatch as s, EdgeRoutingSettings as t, RouteSection as u, RoutingSettings as v, RoutingUpdate as x, RoutingSnapshot as y };

package/dist/types-uxPlGRof.d.cts

@@ -0,0 +1,133 @@
+import { EntityRect, Graph, GraphDiff, Point } from "@statelyai/graph";
+
+//#region src/routing/types.d.ts
+type RoutePoint = Readonly<Point>;
+type RouteSegment = {
+  readonly kind: "line";
+  readonly to: RoutePoint;
+} | {
+  readonly kind: "quadratic";
+  readonly control: RoutePoint;
+  readonly to: RoutePoint;
+} | {
+  readonly kind: "cubic";
+  readonly control1: RoutePoint;
+  readonly control2: RoutePoint;
+  readonly to: RoutePoint;
+} | {
+  readonly kind: "arc";
+  readonly rx: number;
+  readonly ry: number;
+  readonly rotation: number;
+  readonly largeArc: boolean;
+  readonly sweep: boolean;
+  readonly to: RoutePoint;
+};
+interface RoutePath {
+  readonly start: RoutePoint;
+  readonly segments: readonly RouteSegment[];
+}
+type RouteEndpoint = {
+  readonly kind: "node";
+  readonly nodeId: string;
+  readonly port?: string;
+} | {
+  readonly kind: "label";
+  readonly edgeId: string;
+} | {
+  readonly kind: "junction";
+  readonly id: string;
+};
+interface RouteSection {
+  readonly id: string;
+  readonly from: RouteEndpoint;
+  readonly to: RouteEndpoint;
+  readonly path: RoutePath;
+  /** Same ID denotes a shared trunk; render it once. */
+  readonly sharedId?: string;
+}
+type RoutingDiagnosticCode = "MISSING_GEOMETRY" | "MISSING_PORT" | "ROUTE_CONFLICT" | "ROUTE_BLOCKED" | "SEARCH_BUDGET" | "CONSTRAINT_VIOLATION";
+interface RoutingDiagnostic {
+  readonly code: RoutingDiagnosticCode;
+  readonly edgeId: string;
+  readonly message: string;
+}
+interface Route {
+  readonly edgeId: string;
+  readonly sections: readonly RouteSection[];
+  readonly status: "routed" | "fallback";
+  readonly diagnostics: readonly RoutingDiagnostic[];
+}
+type RoutePatch = {
+  readonly op: "set";
+  readonly edgeId: string;
+  readonly route: Route;
+} | {
+  readonly op: "delete";
+  readonly edgeId: string;
+};
+type RouteStyle = "straight" | "bezier" | "orthogonal" | "polyline" | "octilinear" | "curved" | "organic" | "parallel" | "self-loop" | "fan" | "bus" | "bundle";
+type RouteSide = "left" | "right" | "top" | "bottom";
+interface RouteAttachment {
+  /** Node-local attachment rectangle, independent of its outer obstacle bounds. */
+  readonly bounds: RouteBounds;
+  readonly facing?: "inward" | "outward";
+}
+interface EdgeRoutingSettings {
+  readonly sourceAttachment?: RouteAttachment;
+  readonly targetAttachment?: RouteAttachment;
+  readonly sourceSide?: RouteSide;
+  readonly targetSide?: RouteSide;
+  readonly waypoints?: readonly RoutePoint[];
+  /** Explicit shared routing group. Native binary edges describe branches of a net. */
+  readonly group?: string;
+}
+interface RoutingSettings {
+  /** Native compound geometry is parent-relative; adapters may supply resolved world geometry. */
+  readonly coordinateSpace?: "parent" | "world";
+  readonly clearance?: number;
+  readonly radius?: number;
+  readonly edgeSpacing?: number;
+  readonly bendPenalty?: number;
+  /** Soft cost per crossing; finite costs keep detours proportionate. Default 80. */
+  readonly crossingPenalty?: number;
+  /** Cost per unit of parallel overlap within edgeSpacing. Default 8. */
+  readonly overlapPenalty?: number;
+  readonly maxSearchNodes?: number;
+  readonly organicIterations?: number;
+  readonly edges?: Readonly<Record<string, EdgeRoutingSettings>>;
+}
+interface RoutingMetrics {
+  readonly routedEdges: number;
+  readonly reusedEdges: number;
+  readonly affectedEdges: number;
+  readonly searchNodes: number;
+  readonly obstacleCandidates: number;
+}
+/** Immutable value. Retain it per canvas; the private state uses structural sharing. */
+interface RoutingSnapshot {
+  readonly strategy: string;
+  readonly revision: number;
+  readonly routes: ReadonlyMap<string, Route>;
+  readonly metrics: RoutingMetrics;
+}
+interface RoutingUpdate {
+  readonly snapshot: RoutingSnapshot;
+  readonly patches: readonly RoutePatch[];
+  /** Compare identity before accepting an asynchronous result. */
+  readonly base: RoutingSnapshot;
+}
+type RoutingGraph = Graph<unknown, unknown, unknown, unknown>;
+interface RoutingStrategy {
+  readonly id: string;
+  route(graph: RoutingGraph, settings?: RoutingSettings): RoutingSnapshot | Promise<RoutingSnapshot>;
+  update(graph: RoutingGraph, previous: RoutingSnapshot, diff: GraphDiff<unknown, unknown>, settings?: RoutingSettings): RoutingUpdate | Promise<RoutingUpdate>;
+}
+interface NativeRoutingStrategy extends RoutingStrategy {
+  readonly id: RouteStyle;
+  route(graph: RoutingGraph, settings?: RoutingSettings): RoutingSnapshot;
+  update(graph: RoutingGraph, previous: RoutingSnapshot, diff: GraphDiff<unknown, unknown>, settings?: RoutingSettings): RoutingUpdate;
+}
+type RouteBounds = Readonly<EntityRect>;
+//#endregion
+export { RoutingMetrics as _, RouteBounds as a, RoutingStrategy as b, RoutePath as c, RouteSegment as d, RouteSide as f, RoutingGraph as g, RoutingDiagnosticCode as h, RouteAttachment as i, RoutePoint as l, RoutingDiagnostic as m, NativeRoutingStrategy as n, RouteEndpoint as o, RouteStyle as p, Route as r, RoutePatch as s, EdgeRoutingSettings as t, RouteSection as u, RoutingSettings as v, RoutingUpdate as x, RoutingSnapshot as y };

package/dist/{worker-client-DAT_z2OR.d.mts → worker-client-BwGGRD5y.d.mts}

@@ -1,4 +1,4 @@
-import { d as ElkLayoutCategoryDescription, f as ElkLayoutOptionDescription, l as ElkLayoutAlgorithmDescription, n as ELKConstructorArguments, p as ElkNode, t as ELK, u as ElkLayoutArguments, v as LaidOutElkNode } from "./public-types-B8rAALJq.mjs";
+import { d as ElkLayoutCategoryDescription, f as ElkLayoutOptionDescription, l as ElkLayoutAlgorithmDescription, n as ELKConstructorArguments, p as ElkNode, t as ELK, u as ElkLayoutArguments, v as LaidOutElkNode } from "./public-types-9NCPoqbp.mjs";
 
 //#region src/elkjs/worker-client.d.ts
 declare class WorkerELK implements ELK {

package/dist/{worker-client-DVhklF6A.d.cts → worker-client-D4zNyPEI.d.cts}

@@ -1,4 +1,4 @@
-import { d as ElkLayoutCategoryDescription, f as ElkLayoutOptionDescription, l as ElkLayoutAlgorithmDescription, n as ELKConstructorArguments, p as ElkNode, t as ELK, u as ElkLayoutArguments, v as LaidOutElkNode } from "./public-types-CVB0hXGk.cjs";
+import { d as ElkLayoutCategoryDescription, f as ElkLayoutOptionDescription, l as ElkLayoutAlgorithmDescription, n as ELKConstructorArguments, p as ElkNode, t as ELK, u as ElkLayoutArguments, v as LaidOutElkNode } from "./public-types-BcRZoJE3.cjs";
 
 //#region src/elkjs/worker-client.d.ts
 declare class WorkerELK implements ELK {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/layout",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Extensible, graph-native layout algorithms for @statelyai/graph",
   "license": "EPL-2.0 OR GPL-3.0-or-later",
   "repository": {
@@ -59,7 +59,12 @@
       "import": "./dist/layered/index.mjs",
       "require": "./dist/layered/index.cjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./routing": {
+      "types": "./src/routing/index.ts",
+      "import": "./dist/routing/index.mjs",
+      "require": "./dist/routing/index.cjs"
+    }
   },
   "publishConfig": {
     "access": "public"

package/src/authoring/coordinates.ts

@@ -1,7 +1,7 @@
 import { LayoutError } from "../errors";
 import type { VisualGraph, Point } from "@statelyai/graph";
 
-/** Native compound nodes and sibling edges are parent-relative; crossing edges are world-relative. */
+/** Legacy sibling edges are parent-relative; native compound output marks world-space edges. */
 function frames<N, E, G, P>(graph: VisualGraph<N, E, G, P>) {
   const nodes = new Map(graph.nodes.map((n) => [n.id, n]));
   const offsets = new Map<string, Point>();
@@ -33,6 +33,7 @@ function frames<N, E, G, P>(graph: VisualGraph<N, E, G, P>) {
       const target = nodes.get(edge.targetId)!;
       return [
         edge.id,
+        (graph as VisualGraph & { edgeCoordinateSpace?: string }).edgeCoordinateSpace !== "world" &&
         (source.parentId ?? null) === (target.parentId ?? null)
           ? offset(source.id)
           : { x: 0, y: 0 },
@@ -44,8 +45,15 @@ function frames<N, E, G, P>(graph: VisualGraph<N, E, G, P>) {
 
 export function worldGeometry<N, E, G, P>(graph: VisualGraph<N, E, G, P>): VisualGraph<N, E, G, P> {
   const offsets = frames(graph);
+  const base = { ...graph } as VisualGraph<N, E, G, P> & {
+    compoundRoutes?: unknown;
+    compoundGeometry?: unknown;
+  };
+  // Authoring may change nodes, labels, or paths. Never carry derived full-layout caches.
+  delete base.compoundRoutes;
+  delete base.compoundGeometry;
   return {
-    ...graph,
+    ...base,
     nodes: graph.nodes.map((n) => {
       const p = offsets.nodes.get(n.id)!;
       return p.x === 0 && p.y === 0 ? n : { ...n, x: n.x + p.x, y: n.y + p.y };

package/src/elkjs/index.ts

@@ -1,5 +1,4 @@
-import { createGraph, type Graph } from "@statelyai/graph";
-import type { getLayeredLayout } from "../layered";
+import { createGraph, type Graph, type VisualGraph } from "@statelyai/graph";
 import {
   elkLayeredOptionDefinitions,
   type ElkLayeredOptionValueByName,
@@ -1388,7 +1387,7 @@ function toSection(edge: ElkEdge, points: readonly ElkPoint[]) {
 
 function applyLayout(
   root: ElkNode,
-  graph: ReturnType<typeof getLayeredLayout>,
+  graph: VisualGraph,
   padding: { top: number; right: number; bottom: number; left: number },
   layoutOptions: Readonly<Record<string, unknown>>,
   resultPolicy?: Elkjs0111ResultPolicy,
@@ -1901,3 +1900,6 @@ export type {
   StatechartLayoutScore,
   StatechartLayoutPlan,
 } from "./statechart";
+
+export { getElkRoutes } from "./routes";
+export type { ElkRouteOptions } from "./routes";

package/src/elkjs/routes.ts

@@ -0,0 +1,147 @@
+import type { ElkExtendedEdge, ElkNode, ElkPoint } from "./public-types";
+import { pathFromPoints } from "../routing/path";
+import { pathFromSplinePoints } from "../routing/adapters";
+import { freeze } from "../routing/model";
+import type { Route, RouteEndpoint, RoutePath, RoutePoint, RouteSection } from "../routing/types";
+
+export interface ElkRouteOptions {
+  /** ELK stores spline controls in bendPoints; the caller must identify that encoding. */
+  routing?: "ORTHOGONAL" | "POLYLINE" | "SPLINES";
+}
+/** Normalize any ELK layout's section geometry, preserving ports and hyperedge junctions. */
+export function getElkRoutes(
+  graph: ElkNode,
+  options: ElkRouteOptions = {},
+): ReadonlyMap<string, Route> {
+  const shapes = new Map<string, { ref: RouteEndpoint; center: RoutePoint }>(),
+    frames = new Map<string, RoutePoint>();
+  const edges: { edge: ElkExtendedEdge; offset: RoutePoint; routing: string }[] = [];
+  function visit(node: ElkNode, offset: RoutePoint, inherited: string) {
+    const position = { x: offset.x + (node.x ?? 0), y: offset.y + (node.y ?? 0) };
+    const routing =
+      node.layoutOptions?.["elk.edgeRouting"] ??
+      node.layoutOptions?.["org.eclipse.elk.edgeRouting"] ??
+      inherited;
+    frames.set(node.id, position);
+    shapes.set(node.id, {
+      ref: { kind: "node", nodeId: node.id },
+      center: { x: position.x + (node.width ?? 0) / 2, y: position.y + (node.height ?? 0) / 2 },
+    });
+    for (const port of node.ports ?? [])
+      shapes.set(port.id, {
+        ref: { kind: "node", nodeId: node.id, port: port.id },
+        center: {
+          x: position.x + (port.x ?? 0) + (port.width ?? 0) / 2,
+          y: position.y + (port.y ?? 0) + (port.height ?? 0) / 2,
+        },
+      });
+    for (const edge of node.edges ?? [])
+      edges.push({
+        edge,
+        offset: position,
+        routing:
+          edge.layoutOptions?.["elk.edgeRouting"] ??
+          edge.layoutOptions?.["org.eclipse.elk.edgeRouting"] ??
+          routing,
+      });
+    for (const child of node.children ?? []) visit(child, position, routing);
+  }
+  visit(graph, { x: 0, y: 0 }, options.routing ?? "POLYLINE");
+  const result = new Map<string, Route>();
+  for (const { edge, offset: inheritedOffset, routing } of edges) {
+    const offset = edge.container
+      ? (frames.get(edge.container) ?? inheritedOffset)
+      : inheritedOffset;
+    const point = (p: ElkPoint): RoutePoint => ({ x: p.x + offset.x, y: p.y + offset.y });
+    // Join section endpoints by topology, never by equal coordinates alone.
+    const parents = new Map<string, string>();
+    const root = (key: string): string => {
+      let current = key;
+      while (parents.has(current)) current = parents.get(current)!;
+      return current;
+    };
+    const join = (a: string, b: string) => {
+      const x = root(a),
+        y = root(b);
+      if (x !== y) parents.set(x < y ? y : x, x < y ? x : y);
+    };
+    for (const section of edge.sections ?? []) {
+      for (const id of section.outgoingSections ?? []) join(`${section.id}:end`, `${id}:start`);
+      for (const id of section.incomingSections ?? []) join(`${id}:end`, `${section.id}:start`);
+    }
+    const sections: RouteSection[] = [];
+    let malformed = false;
+    for (const section of edge.sections ?? []) {
+      const points = [section.startPoint, ...(section.bendPoints ?? []), section.endPoint].map(
+        point,
+      );
+      let path: RoutePath;
+      if (points.some((p) => !Number.isFinite(p.x) || !Number.isFinite(p.y))) {
+        malformed = true;
+        for (let i = 0; i < points.length; i++)
+          if (!Number.isFinite(points[i]!.x) || !Number.isFinite(points[i]!.y))
+            points[i] = { x: offset.x + i * 20, y: offset.y };
+      }
+      if (routing === "SPLINES") {
+        if ((points.length - 1) % 3 || points.length < 4) {
+          malformed = true;
+          path = pathFromPoints([points[0]!, points.at(-1)!]);
+        } else path = pathFromSplinePoints(points);
+      } else path = pathFromPoints(points);
+      const fromShape =
+        section.incomingShape ??
+        (!section.incomingSections?.length && edge.sources.length === 1
+          ? edge.sources[0]
+          : undefined);
+      const toShape =
+        section.outgoingShape ??
+        (!section.outgoingSections?.length && edge.targets.length === 1
+          ? edge.targets[0]
+          : undefined);
+      sections.push({
+        id: section.id,
+        from: fromShape
+          ? (shapes.get(fromShape)?.ref ?? { kind: "node", nodeId: fromShape })
+          : { kind: "junction", id: `${edge.id}:${root(`${section.id}:start`)}` },
+        to: toShape
+          ? (shapes.get(toShape)?.ref ?? { kind: "node", nodeId: toShape })
+          : { kind: "junction", id: `${edge.id}:${root(`${section.id}:end`)}` },
+        path,
+      });
+    }
+    if (!sections.length) {
+      malformed = true;
+      const source = shapes.get(edge.sources[0] ?? ""),
+        origin = source?.center ?? { x: 0, y: 0 };
+      const targets = [...edge.targets, ...edge.sources.slice(1)];
+      for (const [i, id] of (targets.length ? targets : [""]).entries()) {
+        const target = shapes.get(id);
+        sections.push({
+          id: `${edge.id}:fallback:${i}`,
+          from: source?.ref ?? { kind: "node", nodeId: edge.sources[0] ?? "" },
+          to: target?.ref ?? { kind: "node", nodeId: id },
+          path: pathFromPoints([origin, target?.center ?? { x: origin.x + 40, y: origin.y + 40 }]),
+        });
+      }
+    }
+    result.set(
+      edge.id,
+      freeze({
+        edgeId: edge.id,
+        sections,
+        status: malformed ? "fallback" : "routed",
+        diagnostics: malformed
+          ? [
+              {
+                code: "MISSING_GEOMETRY",
+                edgeId: edge.id,
+                message:
+                  "ELK sections contain missing or invalid geometry; rendered fallback paths",
+              },
+            ]
+          : [],
+      }),
+    );
+  }
+  return result;
+}

package/src/index.ts

@@ -71,6 +71,10 @@ export type {
   EdgeRoutes,
   LayerAssigner,
   LayerAssignment,
+  CompoundVisualGraph,
+  CompoundLayoutOptions,
+  CompoundLayoutGeometry,
+  CompoundEdgeAttachment,
   LayeredLayoutOptions,
   LayeredAdvancedOptions,
   ElkLayeredOptionId,
@@ -103,3 +107,5 @@ export type {
   LinearConstraint,
   WaypointConstraint,
 } from "./constraints";
+
+export * from "./routing";