@statelyai/layout 0.2.0 → 0.4.0

package/dist/index-B6cWNrMw.d.cts

@@ -0,0 +1,80 @@
+import { a as RouteBounds, c as RoutePath, l as RoutePoint, n as NativeRoutingStrategy, r as Route, s as RoutePatch } from "./types-uxPlGRof.cjs";
+import { GraphPatch, VisualGraph } from "@statelyai/graph";
+
+//#region src/routing/engine.d.ts
+declare function applyRoutePatches(routes: ReadonlyMap<string, Route>, patches: readonly RoutePatch[]): ReadonlyMap<string, Route>;
+//#endregion
+//#region src/routing/path.d.ts
+declare function pathFromPoints(points: readonly RoutePoint[]): RoutePath;
+interface FlattenPathOptions {
+  readonly tolerance?: number;
+  readonly maxSegments?: number;
+}
+/** Adaptive, bounded-error polyline approximation. Throws rather than silently exceeding tolerance. */
+declare function flattenPath(path: RoutePath, options?: FlattenPathOptions): RoutePoint[];
+/** Conservative bounds: control hulls and full ellipse envelopes contain every curve. */
+declare function getPathBounds(path: RoutePath): RouteBounds;
+declare function getPathLength(path: RoutePath, options?: FlattenPathOptions): number;
+declare function getPointAtLength(path: RoutePath, length: number, options?: FlattenPathOptions): RoutePoint;
+declare function getTangentAtLength(path: RoutePath, length: number, options?: FlattenPathOptions): RoutePoint;
+/** Round line-to-line corners only; existing curves and path endpoints are retained. */
+declare function roundCorners(path: RoutePath, options: {
+  readonly radius: number;
+}): RoutePath;
+declare function toSvgPath(path: RoutePath, options?: {
+  readonly radius?: number;
+  readonly precision?: number;
+}): string;
+//#endregion
+//#region src/routing/adapters.d.ts
+/** ELK/native spline output: start, then repeating control1/control2/end triples. */
+declare function pathFromSplinePoints(points: readonly RoutePoint[]): RoutePath;
+/** Normalize routes from any native layout algorithm, without running layout again. */
+declare function getLayoutRoutes(graph: VisualGraph): ReadonlyMap<string, Route>;
+/** One polyline per section preserves label gaps and branching for simple renderers. */
+declare function routeToPolylines(route: Route, options?: {
+  readonly tolerance?: number;
+}): readonly (readonly RoutePoint[])[];
+/**
+ * One point list for consumers of `GraphEdge.points`. Sections are joined
+ * through their gaps (an edge label, for example); between orthogonal
+ * sections the join is orthogonal too, so it never adds a diagonal.
+ */
+declare function routeToPoints(route: Route, options?: {
+  readonly tolerance?: number;
+}): RoutePoint[];
+/** Compatibility for single-section native consumers. Refuses to erase gaps or topology. */
+declare function routeToGraphPatch(route: Route, options?: {
+  readonly tolerance?: number;
+  readonly offset?: RoutePoint;
+}): GraphPatch;
+//#endregion
+//#region src/routing/index.d.ts
+declare const straightRouting: NativeRoutingStrategy;
+declare const bezierRouting: NativeRoutingStrategy;
+declare const orthogonalRouting: NativeRoutingStrategy;
+declare const polylineRouting: NativeRoutingStrategy;
+declare const octilinearRouting: NativeRoutingStrategy;
+declare const curvedRouting: NativeRoutingStrategy;
+declare const organicRouting: NativeRoutingStrategy;
+declare const parallelRouting: NativeRoutingStrategy;
+declare const selfLoopRouting: NativeRoutingStrategy;
+declare const fanRouting: NativeRoutingStrategy;
+declare const busRouting: NativeRoutingStrategy;
+declare const bundleRouting: NativeRoutingStrategy;
+declare const routingStrategies: Readonly<{
+  straight: NativeRoutingStrategy;
+  bezier: NativeRoutingStrategy;
+  orthogonal: NativeRoutingStrategy;
+  polyline: NativeRoutingStrategy;
+  octilinear: NativeRoutingStrategy;
+  curved: NativeRoutingStrategy;
+  organic: NativeRoutingStrategy;
+  parallel: NativeRoutingStrategy;
+  "self-loop": NativeRoutingStrategy;
+  fan: NativeRoutingStrategy;
+  bus: NativeRoutingStrategy;
+  bundle: NativeRoutingStrategy;
+}>;
+//#endregion
+export { getPointAtLength as C, toSvgPath as D, roundCorners as E, applyRoutePatches as O, getPathLength as S, pathFromPoints as T, routeToPoints as _, fanRouting as a, flattenPath as b, orthogonalRouting as c, routingStrategies as d, selfLoopRouting as f, routeToGraphPatch as g, pathFromSplinePoints as h, curvedRouting as i, parallelRouting as l, getLayoutRoutes as m, bundleRouting as n, octilinearRouting as o, straightRouting as p, busRouting as r, organicRouting as s, bezierRouting as t, polylineRouting as u, routeToPolylines as v, getTangentAtLength as w, getPathBounds as x, FlattenPathOptions as y };

package/dist/index-CJQLUKD9.d.mts

@@ -0,0 +1,80 @@
+import { a as RouteBounds, c as RoutePath, l as RoutePoint, n as NativeRoutingStrategy, r as Route, s as RoutePatch } from "./types-CT2akdK0.mjs";
+import { GraphPatch, VisualGraph } from "@statelyai/graph";
+
+//#region src/routing/engine.d.ts
+declare function applyRoutePatches(routes: ReadonlyMap<string, Route>, patches: readonly RoutePatch[]): ReadonlyMap<string, Route>;
+//#endregion
+//#region src/routing/path.d.ts
+declare function pathFromPoints(points: readonly RoutePoint[]): RoutePath;
+interface FlattenPathOptions {
+  readonly tolerance?: number;
+  readonly maxSegments?: number;
+}
+/** Adaptive, bounded-error polyline approximation. Throws rather than silently exceeding tolerance. */
+declare function flattenPath(path: RoutePath, options?: FlattenPathOptions): RoutePoint[];
+/** Conservative bounds: control hulls and full ellipse envelopes contain every curve. */
+declare function getPathBounds(path: RoutePath): RouteBounds;
+declare function getPathLength(path: RoutePath, options?: FlattenPathOptions): number;
+declare function getPointAtLength(path: RoutePath, length: number, options?: FlattenPathOptions): RoutePoint;
+declare function getTangentAtLength(path: RoutePath, length: number, options?: FlattenPathOptions): RoutePoint;
+/** Round line-to-line corners only; existing curves and path endpoints are retained. */
+declare function roundCorners(path: RoutePath, options: {
+  readonly radius: number;
+}): RoutePath;
+declare function toSvgPath(path: RoutePath, options?: {
+  readonly radius?: number;
+  readonly precision?: number;
+}): string;
+//#endregion
+//#region src/routing/adapters.d.ts
+/** ELK/native spline output: start, then repeating control1/control2/end triples. */
+declare function pathFromSplinePoints(points: readonly RoutePoint[]): RoutePath;
+/** Normalize routes from any native layout algorithm, without running layout again. */
+declare function getLayoutRoutes(graph: VisualGraph): ReadonlyMap<string, Route>;
+/** One polyline per section preserves label gaps and branching for simple renderers. */
+declare function routeToPolylines(route: Route, options?: {
+  readonly tolerance?: number;
+}): readonly (readonly RoutePoint[])[];
+/**
+ * One point list for consumers of `GraphEdge.points`. Sections are joined
+ * through their gaps (an edge label, for example); between orthogonal
+ * sections the join is orthogonal too, so it never adds a diagonal.
+ */
+declare function routeToPoints(route: Route, options?: {
+  readonly tolerance?: number;
+}): RoutePoint[];
+/** Compatibility for single-section native consumers. Refuses to erase gaps or topology. */
+declare function routeToGraphPatch(route: Route, options?: {
+  readonly tolerance?: number;
+  readonly offset?: RoutePoint;
+}): GraphPatch;
+//#endregion
+//#region src/routing/index.d.ts
+declare const straightRouting: NativeRoutingStrategy;
+declare const bezierRouting: NativeRoutingStrategy;
+declare const orthogonalRouting: NativeRoutingStrategy;
+declare const polylineRouting: NativeRoutingStrategy;
+declare const octilinearRouting: NativeRoutingStrategy;
+declare const curvedRouting: NativeRoutingStrategy;
+declare const organicRouting: NativeRoutingStrategy;
+declare const parallelRouting: NativeRoutingStrategy;
+declare const selfLoopRouting: NativeRoutingStrategy;
+declare const fanRouting: NativeRoutingStrategy;
+declare const busRouting: NativeRoutingStrategy;
+declare const bundleRouting: NativeRoutingStrategy;
+declare const routingStrategies: Readonly<{
+  straight: NativeRoutingStrategy;
+  bezier: NativeRoutingStrategy;
+  orthogonal: NativeRoutingStrategy;
+  polyline: NativeRoutingStrategy;
+  octilinear: NativeRoutingStrategy;
+  curved: NativeRoutingStrategy;
+  organic: NativeRoutingStrategy;
+  parallel: NativeRoutingStrategy;
+  "self-loop": NativeRoutingStrategy;
+  fan: NativeRoutingStrategy;
+  bus: NativeRoutingStrategy;
+  bundle: NativeRoutingStrategy;
+}>;
+//#endregion
+export { getPointAtLength as C, toSvgPath as D, roundCorners as E, applyRoutePatches as O, getPathLength as S, pathFromPoints as T, routeToPoints as _, fanRouting as a, flattenPath as b, orthogonalRouting as c, routingStrategies as d, selfLoopRouting as f, routeToGraphPatch as g, pathFromSplinePoints as h, curvedRouting as i, parallelRouting as l, getLayoutRoutes as m, bundleRouting as n, octilinearRouting as o, straightRouting as p, busRouting as r, organicRouting as s, bezierRouting as t, polylineRouting as u, routeToPolylines as v, getTangentAtLength as w, getPathBounds as x, FlattenPathOptions as y };

package/dist/{index-BSH2bloA.d.mts → index-DT6lPMfS.d.cts}

@@ -1,5 +1,6 @@
-import { LayoutConstraints } from "@statelyai/graph/layout";
+import { n as NativeRoutingStrategy, r as Route, v as RoutingSettings } from "./types-uxPlGRof.cjs";
 import { EntityRect, Graph, GraphEdge, GraphNode, GraphPatch, GraphPort, Point, VisualGraph } from "@statelyai/graph";
+import { LayoutConstraints } from "@statelyai/graph/layout";
 
 //#region src/constraints.d.ts
 type GeometryReference = {
@@ -143,6 +144,53 @@ interface LayoutResult<N = unknown, E = unknown, G = unknown, P = unknown> {
   metrics: LayoutMetrics;
 }
 //#endregion
+//#region src/layered/hints.d.ts
+/**
+ * Hints steer the layered phases toward a reader's expectations. They are
+ * preferences unless marked `require`, and never at the cost of a defect: a
+ * hint that would make nodes overlap is relaxed and reported instead.
+ */
+type HintStrength = "prefer" | "require";
+interface HintBase {
+  id: string;
+  strength?: HintStrength;
+}
+/** Place a node at the start (top-left) or end of its container. */
+interface AnchorHint extends HintBase {
+  kind: "anchor";
+  nodeId: string;
+  corner: "start" | "end";
+}
+/** Align the centers of nodes that follow each other, such as sequential states. */
+interface ChainHint extends HintBase {
+  kind: "chain";
+  nodeIds: readonly string[];
+}
+type LayoutHint = AnchorHint | ChainHint;
+/** Serializable hint constructors, alongside the `c` geometry constraint constructors. */
+declare const hint: {
+  anchor: (value: Omit<AnchorHint, "kind">) => AnchorHint;
+  chain: (value: Omit<ChainHint, "kind">) => ChainHint;
+};
+/**
+ * Hints for statecharts: each container's initial state (and the graph's)
+ * is required at the start, and each run of states joined one-to-one within
+ * the same parent forms a preferred chain. Callers can filter or extend the
+ * result.
+ */
+declare function statechartHints(graph: {
+  initialNodeId?: string | null;
+  nodes: readonly {
+    id: string;
+    parentId?: string | null;
+    initialNodeId?: string | null;
+  }[];
+  edges: readonly {
+    sourceId: string;
+    targetId: string;
+  }[];
+}): LayoutHint[];
+//#endregion
 //#region src/layered/elk-options.generated.d.ts
 interface ElkLayeredOptionValueByName {
   "spacing.commentComment"?: number;
@@ -1151,6 +1199,8 @@ interface LayoutPadding {
   left: number;
 }
 interface LayeredPhaseInput {
+  /** Authored edge order retained through label and long-edge expansion. */
+  modelOrderByEdgeId?: ReadonlyMap<string, number>;
   graph: Graph<unknown, unknown, unknown, unknown>;
   sizes: ReadonlyMap<string, NodeSize>;
   direction: LayoutDirection;
@@ -1166,11 +1216,14 @@ interface AcyclicOrientation {
   reversedEdgeIds: ReadonlySet<string>;
 }
 interface LayerAssignment {
+  layerCount?: number;
   layerByNodeId: ReadonlyMap<string, number>;
   /** Layer-internal seed order produced by layerers whose insertion order is observable. */
   seedOrder?: readonly string[];
 }
 interface LayerOrder {
+  /** Canonical clockwise physical port identities, independent of edge reversal. */
+  physicalPortOrderByNodeId?: ReadonlyMap<string, readonly string[]>;
   layers: readonly (readonly string[])[];
   /** Internal ELK sweep state retained for exact port-aware placement. */
   inputPortOrderByNodeId?: ReadonlyMap<string, readonly string[]>;
@@ -1182,6 +1235,8 @@ interface NodePlacement {
 }
 interface EdgeRoutes {
   pointsByEdgeId: ReadonlyMap<string, readonly Point[]>;
+  /** Branch points generated on physical orthogonal hypersegments before restoration. */
+  junctionPointsByEdgeId?: ReadonlyMap<string, readonly Point[]>;
   /** ELK spline segment NUB controls retained until long-edge joining. */
   splineNubControlsByEdgeId?: ReadonlyMap<string, readonly Point[]>;
   /** Reversed fixed-side routes that must stay outside the node envelope during compaction. */
@@ -1199,11 +1254,40 @@ interface LayeredStrategies {
   placeNodes?: NodePlacer;
   routeEdges?: EdgeRouter;
 }
+/** Geometry reserved while laying out a compound, before its ancestors. */
+interface CompoundLayoutOptions {
+  padding?: number | Partial<LayoutPadding>;
+  direction?: LayoutDirection;
+  header?: NodeSize & {
+    side?: "top" | "right" | "bottom" | "left";
+  };
+  minContentSize?: Partial<NodeSize>;
+}
+interface CompoundLayoutGeometry {
+  /** Parent-relative outer rectangle; header/content are relative to this rectangle. */
+  bounds: EntityRect;
+  header?: EntityRect;
+  content: EntityRect;
+}
+interface CompoundEdgeAttachment {
+  /** Content attachments leave toward the interior; outer attachments leave outward. */
+  source?: "content" | "outer";
+  target?: "content" | "outer";
+}
 interface LayeredLayoutOptions {
+  /** Replace initial routes after initial placement and routing, without moving geometry. */
+  routing?: {
+    strategy: Pick<NativeRoutingStrategy, "route">;
+    settings?: RoutingSettings;
+  };
   direction?: LayoutDirection;
+  compound?: (node: GraphNode) => CompoundLayoutOptions | undefined;
+  edgeAttachment?: (edge: GraphEdge) => CompoundEdgeAttachment | undefined;
   spacing?: Partial<LayeredSpacing>;
   padding?: number | Partial<LayoutPadding>;
   constraints?: LayoutConstraints;
+  /** Reader-facing preferences applied during layering, ordering and placement. */
+  hints?: readonly LayoutHint[];
   measure?: (node: GraphNode) => NodeSize;
   crossingSweeps?: number;
   strategies?: LayeredStrategies;
@@ -1217,11 +1301,20 @@ interface LayeredLayoutOptions {
   portSettings?: (port: GraphPort, node: GraphNode) => ElkLayeredOptionValueByName | undefined;
 }
 //#endregion
+//#region src/layered/compound.d.ts
+type CompoundVisualGraph<N = unknown, E = unknown, G = unknown, P = unknown> = VisualGraph<N, E, G, P> & {
+  /** Nodes remain parent-relative; edge rectangles and points are world-space. */
+  readonly edgeCoordinateSpace?: "world";
+  readonly compoundGeometry: ReadonlyMap<string, CompoundLayoutGeometry>;
+  /** World-space route sections preserve label gaps and fallback diagnostics. */
+  readonly compoundRoutes: ReadonlyMap<string, Route>;
+};
+//#endregion
 //#region src/layered/strategies.d.ts
 declare const breakCyclesWithDepthFirstSearch: CycleBreaker;
 declare const breakCyclesGreedily: CycleBreaker;
 declare const breakCyclesGreedilyByModelOrder: CycleBreaker;
-/** ELK MODEL_ORDER for flat graphs without FIRST/LAST layer constraints. */
+/** ELK MODEL_ORDER: layer-constrained nodes (e.g. external port dummies) order before/after the rest. */
 declare const breakCyclesByModelOrder: CycleBreaker;
 /** ELK INTERACTIVE: honor authored x-order, then remove any remaining DFS back edges. */
 declare const breakCyclesInteractively: CycleBreaker;
@@ -1262,7 +1355,7 @@ declare const assignLayersWithMinWidth: LayerAssigner;
 declare const assignLayersWithStretchWidth: LayerAssigner;
 //#endregion
 //#region src/layered/bk-node-placement.d.ts
-/** ELK-compatible Brandes-Koepf placement for implicit center ports. */
+/** ELK-compatible Brandes-Koepf placement with port-aware compaction. */
 declare function placeNodesWithBrandesKoepf(input: LayeredPhaseInput, order: LayerOrder): NodePlacement;
 //#endregion
 //#region src/layered/linear-segments-node-placement.d.ts
@@ -1274,13 +1367,32 @@ declare function placeNodesWithLinearSegments(input: LayeredPhaseInput, order: L
 declare function placeNodesWithNetworkSimplex(input: LayeredPhaseInput, order: LayerOrder): NodePlacement;
 //#endregion
 //#region src/layered/index.d.ts
+/** @internal A prepared native scope, before crossing, placement or routing. */
+interface LayeredCrossingPhase {
+  input: LayeredPhaseInput;
+  orientation: AcyclicOrientation;
+  assignment: LayerAssignment;
+  /** Refresh compound body dimensions after child placement, before this scope resumes. */
+  updateNodeSize(id: string, size: NodeSize): void;
+  finishOrder(order: LayerOrder): LayerOrder;
+  /** Run this scope's standalone minimizer, including authored ordering policies. */
+  minimize(): LayerOrder;
+}
+/**
+ * @internal Suspend a native scope at crossing minimization. A hierarchy
+ * coordinator can prepare every scope, share sweep state, then resume each
+ * scope with its final order. The ordinary entry point drains this same pipeline.
+ */
+declare function createLayeredScopePipeline<N, E, G, P>(graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>, options: LayeredLayoutOptions, context?: LayoutExecutionContext): Generator<LayeredCrossingPhase, VisualGraph<N, E, G, P>, LayerOrder>;
 /**
  * Deterministic native layered layout for an `@statelyai/graph` graph.
  *
  * Supports flat and nested graphs, cycles, ports, self-loops, four directions,
  * custom phase strategies, and all layered edge-routing styles.
  */
-declare function getLayeredLayout<N, E, G, P>(graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>, options?: LayeredLayoutOptions): VisualGraph<N, E, G, P>;
+declare function getLayeredLayout<N, E, G, P>(graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>, options?: LayeredLayoutOptions): CompoundVisualGraph<N, E, G, P>;
 declare const layeredAlgorithm: LayoutAlgorithm<LayeredLayoutOptions>;
+/** The pinned ELK adapter retains its established placement/routing contract. */
+declare const elkjs0111LayeredAlgorithm: LayoutAlgorithm<LayeredLayoutOptions>;
 //#endregion
-export { LayeringStrategy as $, routeEdgesOrthogonally as A, LayerOrder as B, breakCyclesWithModelOrderDepthFirstSearch as C, GeometryReference as Ct, minimizeCrossingsWithModelOrder as D, WaypointConstraint as Dt, minimizeCrossingsWithMedian as E, PinConstraint as Et, CycleBreaker as F, LayoutPadding as G, LayeredPhaseInput as H, EdgeRouter as I, NodeSize as J, NodePlacement as K, EdgeRoutes as L, routeEdgesWithSplines as M, AcyclicOrientation as N, placeNodesInLayers as O, c as Ot, CrossingMinimizer as P, LayeredAdvancedOptions as Q, LayerAssigner as R, breakCyclesWithModelOrderBreadthFirstSearch as S, GeometryAttribute as St, minimizeCrossingsWithBarycenter as T, LinearConstraint as Tt, LayeredSpacing as U, LayeredLayoutOptions as V, LayeredStrategies as W, CycleBreakingStrategy as X, CrossingMinimizationStrategy as Y, EdgeRoutingStyle as Z, breakCyclesByStronglyConnectedNodeType as _, LayoutResult as _t, placeNodesWithBrandesKoepf as a, ElkLayeredOptionName as at, breakCyclesInteractively as b, ConstraintStrength as bt, assignLayersWithNetworkSimplex as c, AnyGraph as ct, assignLayersByLongestPath as d, LayoutDiagnostic as dt, NodePlacementStrategy as et, assignLayersByLongestPathToSink as f, LayoutDirection as ft, breakCyclesByStronglyConnectedConnectivity as g, LayoutRequest as gt, breakCyclesByModelOrder as h, LayoutPhaseMetrics as ht, placeNodesWithLinearSegments as i, ElkLayeredOptionId as it, routeEdgesWithPolylines as j, placeNodesInteractively as k, assignLayersByBreadthFirstModelOrder as l, LayoutAlgorithm as lt, assignLayersWithCoffmanGraham as m, LayoutMetrics as mt, layeredAlgorithm as n, toElkLayeredOptions as nt, assignLayersWithStretchWidth as o, ElkLayeredOptionValueByName as ot, assignLayersInteractively as p, LayoutExecutionContext as pt, NodePlacer as q, placeNodesWithNetworkSimplex as r, elkLayeredEnumValues as rt, assignLayersWithMinWidth as s, elkLayeredOptionDefinitions as st, getLayeredLayout as t, fromElkLayeredOptionId as tt, assignLayersByDepthFirstModelOrder as u, LayoutCapabilities as ut, breakCyclesGreedily as v, LayoutScope as vt, minimizeCrossingsInteractively as w, LayoutConstraint as wt, breakCyclesWithDepthFirstSearch as x, DistributeConstraint as xt, breakCyclesGreedilyByModelOrder as y, AlignConstraint as yt, LayerAssignment as z };
+export { NodePlacement as $, minimizeCrossingsWithModelOrder as A, LayoutResult as At, CompoundLayoutOptions as B, WaypointConstraint as Bt, breakCyclesInteractively as C, LayoutCapabilities as Ct, minimizeCrossingsInteractively as D, LayoutMetrics as Dt, breakCyclesWithModelOrderDepthFirstSearch as E, LayoutExecutionContext as Et, routeEdgesWithSplines as F, GeometryAttribute as Ft, LayerAssigner as G, CycleBreaker as H, CompoundVisualGraph as I, GeometryReference as It, LayeredLayoutOptions as J, LayerAssignment as K, AcyclicOrientation as L, LayoutConstraint as Lt, placeNodesInteractively as M, AlignConstraint as Mt, routeEdgesOrthogonally as N, ConstraintStrength as Nt, minimizeCrossingsWithBarycenter as O, LayoutPhaseMetrics as Ot, routeEdgesWithPolylines as P, DistributeConstraint as Pt, LayoutPadding as Q, CompoundEdgeAttachment as R, LinearConstraint as Rt, breakCyclesGreedilyByModelOrder as S, LayoutAlgorithm as St, breakCyclesWithModelOrderBreadthFirstSearch as T, LayoutDirection as Tt, EdgeRouter as U, CrossingMinimizer as V, c as Vt, EdgeRoutes as W, LayeredSpacing as X, LayeredPhaseInput as Y, LayeredStrategies as Z, assignLayersWithCoffmanGraham as _, HintStrength as _t, layeredAlgorithm as a, LayeredAdvancedOptions as at, breakCyclesByStronglyConnectedNodeType as b, statechartHints as bt, placeNodesWithBrandesKoepf as c, fromElkLayeredOptionId as ct, assignLayersWithNetworkSimplex as d, ElkLayeredOptionId as dt, NodePlacer as et, assignLayersByBreadthFirstModelOrder as f, ElkLayeredOptionName as ft, assignLayersInteractively as g, ChainHint as gt, assignLayersByLongestPathToSink as h, AnchorHint as ht, getLayeredLayout as i, EdgeRoutingStyle as it, placeNodesInLayers as j, LayoutScope as jt, minimizeCrossingsWithMedian as k, LayoutRequest as kt, assignLayersWithStretchWidth as l, toElkLayeredOptions as lt, assignLayersByLongestPath as m, elkLayeredOptionDefinitions as mt, createLayeredScopePipeline as n, CrossingMinimizationStrategy as nt, placeNodesWithNetworkSimplex as o, LayeringStrategy as ot, assignLayersByDepthFirstModelOrder as p, ElkLayeredOptionValueByName as pt, LayerOrder as q, elkjs0111LayeredAlgorithm as r, CycleBreakingStrategy as rt, placeNodesWithLinearSegments as s, NodePlacementStrategy as st, LayeredCrossingPhase as t, NodeSize as tt, assignLayersWithMinWidth as u, elkLayeredEnumValues as ut, breakCyclesByModelOrder as v, LayoutHint as vt, breakCyclesWithDepthFirstSearch as w, LayoutDiagnostic as wt, breakCyclesGreedily as x, AnyGraph as xt, breakCyclesByStronglyConnectedConnectivity as y, hint as yt, CompoundLayoutGeometry as z, PinConstraint as zt };

package/dist/{index-CG712jzV.d.cts → index-F1U-fCTu.d.mts}

@@ -1,5 +1,6 @@
-import { EntityRect, Graph, GraphEdge, GraphNode, GraphPatch, GraphPort, Point, VisualGraph } from "@statelyai/graph";
+import { n as NativeRoutingStrategy, r as Route, v as RoutingSettings } from "./types-CT2akdK0.mjs";
 import { LayoutConstraints } from "@statelyai/graph/layout";
+import { EntityRect, Graph, GraphEdge, GraphNode, GraphPatch, GraphPort, Point, VisualGraph } from "@statelyai/graph";
 
 //#region src/constraints.d.ts
 type GeometryReference = {
@@ -143,6 +144,53 @@ interface LayoutResult<N = unknown, E = unknown, G = unknown, P = unknown> {
   metrics: LayoutMetrics;
 }
 //#endregion
+//#region src/layered/hints.d.ts
+/**
+ * Hints steer the layered phases toward a reader's expectations. They are
+ * preferences unless marked `require`, and never at the cost of a defect: a
+ * hint that would make nodes overlap is relaxed and reported instead.
+ */
+type HintStrength = "prefer" | "require";
+interface HintBase {
+  id: string;
+  strength?: HintStrength;
+}
+/** Place a node at the start (top-left) or end of its container. */
+interface AnchorHint extends HintBase {
+  kind: "anchor";
+  nodeId: string;
+  corner: "start" | "end";
+}
+/** Align the centers of nodes that follow each other, such as sequential states. */
+interface ChainHint extends HintBase {
+  kind: "chain";
+  nodeIds: readonly string[];
+}
+type LayoutHint = AnchorHint | ChainHint;
+/** Serializable hint constructors, alongside the `c` geometry constraint constructors. */
+declare const hint: {
+  anchor: (value: Omit<AnchorHint, "kind">) => AnchorHint;
+  chain: (value: Omit<ChainHint, "kind">) => ChainHint;
+};
+/**
+ * Hints for statecharts: each container's initial state (and the graph's)
+ * is required at the start, and each run of states joined one-to-one within
+ * the same parent forms a preferred chain. Callers can filter or extend the
+ * result.
+ */
+declare function statechartHints(graph: {
+  initialNodeId?: string | null;
+  nodes: readonly {
+    id: string;
+    parentId?: string | null;
+    initialNodeId?: string | null;
+  }[];
+  edges: readonly {
+    sourceId: string;
+    targetId: string;
+  }[];
+}): LayoutHint[];
+//#endregion
 //#region src/layered/elk-options.generated.d.ts
 interface ElkLayeredOptionValueByName {
   "spacing.commentComment"?: number;
@@ -1151,6 +1199,8 @@ interface LayoutPadding {
   left: number;
 }
 interface LayeredPhaseInput {
+  /** Authored edge order retained through label and long-edge expansion. */
+  modelOrderByEdgeId?: ReadonlyMap<string, number>;
   graph: Graph<unknown, unknown, unknown, unknown>;
   sizes: ReadonlyMap<string, NodeSize>;
   direction: LayoutDirection;
@@ -1166,11 +1216,14 @@ interface AcyclicOrientation {
   reversedEdgeIds: ReadonlySet<string>;
 }
 interface LayerAssignment {
+  layerCount?: number;
   layerByNodeId: ReadonlyMap<string, number>;
   /** Layer-internal seed order produced by layerers whose insertion order is observable. */
   seedOrder?: readonly string[];
 }
 interface LayerOrder {
+  /** Canonical clockwise physical port identities, independent of edge reversal. */
+  physicalPortOrderByNodeId?: ReadonlyMap<string, readonly string[]>;
   layers: readonly (readonly string[])[];
   /** Internal ELK sweep state retained for exact port-aware placement. */
   inputPortOrderByNodeId?: ReadonlyMap<string, readonly string[]>;
@@ -1182,6 +1235,8 @@ interface NodePlacement {
 }
 interface EdgeRoutes {
   pointsByEdgeId: ReadonlyMap<string, readonly Point[]>;
+  /** Branch points generated on physical orthogonal hypersegments before restoration. */
+  junctionPointsByEdgeId?: ReadonlyMap<string, readonly Point[]>;
   /** ELK spline segment NUB controls retained until long-edge joining. */
   splineNubControlsByEdgeId?: ReadonlyMap<string, readonly Point[]>;
   /** Reversed fixed-side routes that must stay outside the node envelope during compaction. */
@@ -1199,11 +1254,40 @@ interface LayeredStrategies {
   placeNodes?: NodePlacer;
   routeEdges?: EdgeRouter;
 }
+/** Geometry reserved while laying out a compound, before its ancestors. */
+interface CompoundLayoutOptions {
+  padding?: number | Partial<LayoutPadding>;
+  direction?: LayoutDirection;
+  header?: NodeSize & {
+    side?: "top" | "right" | "bottom" | "left";
+  };
+  minContentSize?: Partial<NodeSize>;
+}
+interface CompoundLayoutGeometry {
+  /** Parent-relative outer rectangle; header/content are relative to this rectangle. */
+  bounds: EntityRect;
+  header?: EntityRect;
+  content: EntityRect;
+}
+interface CompoundEdgeAttachment {
+  /** Content attachments leave toward the interior; outer attachments leave outward. */
+  source?: "content" | "outer";
+  target?: "content" | "outer";
+}
 interface LayeredLayoutOptions {
+  /** Replace initial routes after initial placement and routing, without moving geometry. */
+  routing?: {
+    strategy: Pick<NativeRoutingStrategy, "route">;
+    settings?: RoutingSettings;
+  };
   direction?: LayoutDirection;
+  compound?: (node: GraphNode) => CompoundLayoutOptions | undefined;
+  edgeAttachment?: (edge: GraphEdge) => CompoundEdgeAttachment | undefined;
   spacing?: Partial<LayeredSpacing>;
   padding?: number | Partial<LayoutPadding>;
   constraints?: LayoutConstraints;
+  /** Reader-facing preferences applied during layering, ordering and placement. */
+  hints?: readonly LayoutHint[];
   measure?: (node: GraphNode) => NodeSize;
   crossingSweeps?: number;
   strategies?: LayeredStrategies;
@@ -1217,11 +1301,20 @@ interface LayeredLayoutOptions {
   portSettings?: (port: GraphPort, node: GraphNode) => ElkLayeredOptionValueByName | undefined;
 }
 //#endregion
+//#region src/layered/compound.d.ts
+type CompoundVisualGraph<N = unknown, E = unknown, G = unknown, P = unknown> = VisualGraph<N, E, G, P> & {
+  /** Nodes remain parent-relative; edge rectangles and points are world-space. */
+  readonly edgeCoordinateSpace?: "world";
+  readonly compoundGeometry: ReadonlyMap<string, CompoundLayoutGeometry>;
+  /** World-space route sections preserve label gaps and fallback diagnostics. */
+  readonly compoundRoutes: ReadonlyMap<string, Route>;
+};
+//#endregion
 //#region src/layered/strategies.d.ts
 declare const breakCyclesWithDepthFirstSearch: CycleBreaker;
 declare const breakCyclesGreedily: CycleBreaker;
 declare const breakCyclesGreedilyByModelOrder: CycleBreaker;
-/** ELK MODEL_ORDER for flat graphs without FIRST/LAST layer constraints. */
+/** ELK MODEL_ORDER: layer-constrained nodes (e.g. external port dummies) order before/after the rest. */
 declare const breakCyclesByModelOrder: CycleBreaker;
 /** ELK INTERACTIVE: honor authored x-order, then remove any remaining DFS back edges. */
 declare const breakCyclesInteractively: CycleBreaker;
@@ -1262,7 +1355,7 @@ declare const assignLayersWithMinWidth: LayerAssigner;
 declare const assignLayersWithStretchWidth: LayerAssigner;
 //#endregion
 //#region src/layered/bk-node-placement.d.ts
-/** ELK-compatible Brandes-Koepf placement for implicit center ports. */
+/** ELK-compatible Brandes-Koepf placement with port-aware compaction. */
 declare function placeNodesWithBrandesKoepf(input: LayeredPhaseInput, order: LayerOrder): NodePlacement;
 //#endregion
 //#region src/layered/linear-segments-node-placement.d.ts
@@ -1274,13 +1367,32 @@ declare function placeNodesWithLinearSegments(input: LayeredPhaseInput, order: L
 declare function placeNodesWithNetworkSimplex(input: LayeredPhaseInput, order: LayerOrder): NodePlacement;
 //#endregion
 //#region src/layered/index.d.ts
+/** @internal A prepared native scope, before crossing, placement or routing. */
+interface LayeredCrossingPhase {
+  input: LayeredPhaseInput;
+  orientation: AcyclicOrientation;
+  assignment: LayerAssignment;
+  /** Refresh compound body dimensions after child placement, before this scope resumes. */
+  updateNodeSize(id: string, size: NodeSize): void;
+  finishOrder(order: LayerOrder): LayerOrder;
+  /** Run this scope's standalone minimizer, including authored ordering policies. */
+  minimize(): LayerOrder;
+}
+/**
+ * @internal Suspend a native scope at crossing minimization. A hierarchy
+ * coordinator can prepare every scope, share sweep state, then resume each
+ * scope with its final order. The ordinary entry point drains this same pipeline.
+ */
+declare function createLayeredScopePipeline<N, E, G, P>(graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>, options: LayeredLayoutOptions, context?: LayoutExecutionContext): Generator<LayeredCrossingPhase, VisualGraph<N, E, G, P>, LayerOrder>;
 /**
  * Deterministic native layered layout for an `@statelyai/graph` graph.
  *
  * Supports flat and nested graphs, cycles, ports, self-loops, four directions,
  * custom phase strategies, and all layered edge-routing styles.
  */
-declare function getLayeredLayout<N, E, G, P>(graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>, options?: LayeredLayoutOptions): VisualGraph<N, E, G, P>;
+declare function getLayeredLayout<N, E, G, P>(graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>, options?: LayeredLayoutOptions): CompoundVisualGraph<N, E, G, P>;
 declare const layeredAlgorithm: LayoutAlgorithm<LayeredLayoutOptions>;
+/** The pinned ELK adapter retains its established placement/routing contract. */
+declare const elkjs0111LayeredAlgorithm: LayoutAlgorithm<LayeredLayoutOptions>;
 //#endregion
-export { LayeringStrategy as $, routeEdgesOrthogonally as A, LayerOrder as B, breakCyclesWithModelOrderDepthFirstSearch as C, GeometryReference as Ct, minimizeCrossingsWithModelOrder as D, WaypointConstraint as Dt, minimizeCrossingsWithMedian as E, PinConstraint as Et, CycleBreaker as F, LayoutPadding as G, LayeredPhaseInput as H, EdgeRouter as I, NodeSize as J, NodePlacement as K, EdgeRoutes as L, routeEdgesWithSplines as M, AcyclicOrientation as N, placeNodesInLayers as O, c as Ot, CrossingMinimizer as P, LayeredAdvancedOptions as Q, LayerAssigner as R, breakCyclesWithModelOrderBreadthFirstSearch as S, GeometryAttribute as St, minimizeCrossingsWithBarycenter as T, LinearConstraint as Tt, LayeredSpacing as U, LayeredLayoutOptions as V, LayeredStrategies as W, CycleBreakingStrategy as X, CrossingMinimizationStrategy as Y, EdgeRoutingStyle as Z, breakCyclesByStronglyConnectedNodeType as _, LayoutResult as _t, placeNodesWithBrandesKoepf as a, ElkLayeredOptionName as at, breakCyclesInteractively as b, ConstraintStrength as bt, assignLayersWithNetworkSimplex as c, AnyGraph as ct, assignLayersByLongestPath as d, LayoutDiagnostic as dt, NodePlacementStrategy as et, assignLayersByLongestPathToSink as f, LayoutDirection as ft, breakCyclesByStronglyConnectedConnectivity as g, LayoutRequest as gt, breakCyclesByModelOrder as h, LayoutPhaseMetrics as ht, placeNodesWithLinearSegments as i, ElkLayeredOptionId as it, routeEdgesWithPolylines as j, placeNodesInteractively as k, assignLayersByBreadthFirstModelOrder as l, LayoutAlgorithm as lt, assignLayersWithCoffmanGraham as m, LayoutMetrics as mt, layeredAlgorithm as n, toElkLayeredOptions as nt, assignLayersWithStretchWidth as o, ElkLayeredOptionValueByName as ot, assignLayersInteractively as p, LayoutExecutionContext as pt, NodePlacer as q, placeNodesWithNetworkSimplex as r, elkLayeredEnumValues as rt, assignLayersWithMinWidth as s, elkLayeredOptionDefinitions as st, getLayeredLayout as t, fromElkLayeredOptionId as tt, assignLayersByDepthFirstModelOrder as u, LayoutCapabilities as ut, breakCyclesGreedily as v, LayoutScope as vt, minimizeCrossingsInteractively as w, LayoutConstraint as wt, breakCyclesWithDepthFirstSearch as x, DistributeConstraint as xt, breakCyclesGreedilyByModelOrder as y, AlignConstraint as yt, LayerAssignment as z };
+export { NodePlacement as $, minimizeCrossingsWithModelOrder as A, LayoutResult as At, CompoundLayoutOptions as B, WaypointConstraint as Bt, breakCyclesInteractively as C, LayoutCapabilities as Ct, minimizeCrossingsInteractively as D, LayoutMetrics as Dt, breakCyclesWithModelOrderDepthFirstSearch as E, LayoutExecutionContext as Et, routeEdgesWithSplines as F, GeometryAttribute as Ft, LayerAssigner as G, CycleBreaker as H, CompoundVisualGraph as I, GeometryReference as It, LayeredLayoutOptions as J, LayerAssignment as K, AcyclicOrientation as L, LayoutConstraint as Lt, placeNodesInteractively as M, AlignConstraint as Mt, routeEdgesOrthogonally as N, ConstraintStrength as Nt, minimizeCrossingsWithBarycenter as O, LayoutPhaseMetrics as Ot, routeEdgesWithPolylines as P, DistributeConstraint as Pt, LayoutPadding as Q, CompoundEdgeAttachment as R, LinearConstraint as Rt, breakCyclesGreedilyByModelOrder as S, LayoutAlgorithm as St, breakCyclesWithModelOrderBreadthFirstSearch as T, LayoutDirection as Tt, EdgeRouter as U, CrossingMinimizer as V, c as Vt, EdgeRoutes as W, LayeredSpacing as X, LayeredPhaseInput as Y, LayeredStrategies as Z, assignLayersWithCoffmanGraham as _, HintStrength as _t, layeredAlgorithm as a, LayeredAdvancedOptions as at, breakCyclesByStronglyConnectedNodeType as b, statechartHints as bt, placeNodesWithBrandesKoepf as c, fromElkLayeredOptionId as ct, assignLayersWithNetworkSimplex as d, ElkLayeredOptionId as dt, NodePlacer as et, assignLayersByBreadthFirstModelOrder as f, ElkLayeredOptionName as ft, assignLayersInteractively as g, ChainHint as gt, assignLayersByLongestPathToSink as h, AnchorHint as ht, getLayeredLayout as i, EdgeRoutingStyle as it, placeNodesInLayers as j, LayoutScope as jt, minimizeCrossingsWithMedian as k, LayoutRequest as kt, assignLayersWithStretchWidth as l, toElkLayeredOptions as lt, assignLayersByLongestPath as m, elkLayeredOptionDefinitions as mt, createLayeredScopePipeline as n, CrossingMinimizationStrategy as nt, placeNodesWithNetworkSimplex as o, LayeringStrategy as ot, assignLayersByDepthFirstModelOrder as p, ElkLayeredOptionValueByName as pt, LayerOrder as q, elkjs0111LayeredAlgorithm as r, CycleBreakingStrategy as rt, placeNodesWithLinearSegments as s, NodePlacementStrategy as st, LayeredCrossingPhase as t, NodeSize as tt, assignLayersWithMinWidth as u, elkLayeredEnumValues as ut, breakCyclesByModelOrder as v, LayoutHint as vt, breakCyclesWithDepthFirstSearch as w, LayoutDiagnostic as wt, breakCyclesGreedily as x, AnyGraph as xt, breakCyclesByStronglyConnectedConnectivity as y, hint as yt, CompoundLayoutGeometry as z, PinConstraint as zt };