@weasel-js/diagram 1.10.0 → 1.11.0

package/dist/index.d.ts

@@ -1,8 +1,12 @@
-import { P as Port, a as PortsOptions, D as DiagramNodeLike, b as DiagramNodeReader, c as PortAnchor, d as DiagramGroup, R as Row, O as Outline, e as PortSpec, B as BodySpec, f as DiagramNode, L as LayoutFn, g as LayoutOptions, M as MeasureRowText, G as GraphSource, F as ForceOptions, h as LayoutResult, i as Graph } from './layout.entry-CIdRpG2i.js';
-export { j as BodyFloor, k as BodyNodeSpec, l as Bounds, m as BuildBodyOptions, n as BuildGraphOptions, C as COMPASS, o as DEFAULT_GROUP_INSET, p as DEFAULT_NODE_GAP, q as DEFAULT_PORTS, r as DEFAULT_RANK_GAP, s as DIAGRAM_TRAIT_KEY, t as DiagramNodeEntry, u as ForceBody, v as ForceRelaxation, w as Forest, x as GraphEdge, y as GraphGroup, z as GraphNode, A as GraphNodeLike, E as GroupInset, H as LayoutAxes, I as LayoutDirection, J as RowBox, K as RowNodeData, N as RowPort, Q as RowPortBox, S as RowTextStyle, T as Slot, U as axesFor, V as backEdges, W as bodyOutline, X as bodyTrait, Y as boxForContent, Z as buildBody, _ as buildGraph, $ as canvasMeasure, a0 as contentBox, a1 as createDiagramNodes, a2 as dataKeyReader, a3 as diagramNodeOf, a4 as expandGroupEdges, a5 as force, a6 as forceRelaxation, a7 as forestOf, a8 as graphOrder, a9 as insetOf, aa as isPinned, ab as layered, ac as layoutBody, ad as layoutRowPorts, ae as measureBody, af as outlinePath, ag as outlinePolyline, ah as packAcross, ai as packClusters, aj as pinnedSet, ak as portOf, al as portsOf, am as portsOnOutline, an as rankGaps, ao as ranksOf, ap as rayHit, aq as seededOrder, ar as settle, as as sizeToBody, at as translated, au as tree, av as untilSettled } from './layout.entry-CIdRpG2i.js';
-import { Vec2, DerivedDep, Path, SceneRegistry, PoseDescriptor, ChromeState, CommandFill, CommandStroke, CursorSpec, Affordance, InvocationCtx, Stroke, GestureBinding, Action, Contribution, RenderLayer, MarkerRef, AddNodeSpec, RectPose, Scene, NodeId, Fill, NodeShapeEntry, Paint, View, SelectionApi } from '@weasel-js/core';
-import { Vec2 as Vec2$1 } from '@weasel-js/core/math';
+import { f as Port, g as DiagramNodeLike, h as DiagramNodeReader, d as LayoutOptions, i as LayoutResult, G as Graph, c as LayoutFn, j as GraphSource, k as LayoutPlanner, l as LayoutDirection, L as LayoutPorts, m as LayoutPlan, n as GraphNodeLike } from './body-2lC7IiIA.js';
+export { o as BodyFloor, p as BodyNodeSpec, B as BodySpec, q as Bounds, r as BuildBodyOptions, s as BuildGraphOptions, t as DEFAULT_GROUP_INSET, u as DEFAULT_NODE_GAP, v as DEFAULT_RANK_GAP, w as DIAGRAM_TRAIT_KEY, D as DiagramGroup, e as DiagramNode, x as DiagramNodeEntry, E as EdgeLabelRoom, y as GraphEdge, z as GraphGroup, A as GraphNode, C as GroupInset, F as LayoutAxes, M as MeasureRowText, O as Outline, H as PORT_LABEL_GAP, I as PerimeterPortLabelBox, P as PortAnchor, J as PortLabelPlacement, K as PortSite, b as PortSpec, a as Row, N as RowBox, Q as RowNodeData, S as RowPort, T as RowPortBox, R as RowTextStyle, U as Slot, V as anchorOffset, W as axesFor, X as bodyOutline, Y as bodyTrait, Z as boxForContent, _ as buildBody, $ as buildGraph, a0 as canvasMeasure, a1 as contentBox, a2 as createDiagramNodes, a3 as dataKeyReader, a4 as diagramNodeOf, a5 as expandGroupEdges, a6 as graphOrder, a7 as insetOf, a8 as isPinned, a9 as layoutBody, aa as layoutRowPorts, ab as marginOf, ac as measureBody, ad as outlinePath, ae as packAcross, af as packClusters, ag as pinnedSet, ah as planOf, ai as plannerPlan, aj as portLabelBox, ak as portLabelsOf, al as rankGaps, am as seededOrder, an as settle, ao as sizeToBody, ap as translated, aq as untilSettled } from './body-2lC7IiIA.js';
+import { P as PortsOptions, F as ForceOptions } from './layout.entry-BoWFcR4G.js';
+export { C as COMPASS, D as DEFAULT_PORTS, a as ForceBody, b as ForceRelaxation, c as Forest, L as LayeredPlan, d as backEdges, e as chain, f as footprintNode, g as force, h as forceRelaxation, i as forestOf, l as layered, j as layeredPlan, o as outlinePolyline, p as portOf, k as portSitesOf, m as portsOf, n as portsOnOutline, r as ranksByLength, q as ranksOf, s as rayHit, t as tree } from './layout.entry-BoWFcR4G.js';
+import { Vec2, DerivedDep, Path, SceneRegistry, PoseDescriptor, ChromeState, CommandFill, CommandStroke, CursorSpec, Affordance, InvocationCtx, Stroke, GestureBinding, Action, Contribution, RenderLayer, NodeId, Scene, GatedLayer, Fill, NodeShapeEntry, RectPose, Paint, View, SelectionApi } from '@weasel-js/core';
+import { f as EdgeEnd, e as DiagramSpec, b as DataEdge } from './fromData-GKqRgPFs.js';
+export { A as ANCHOR_DERIVE_POSE, g as DIAGRAM_ANCHOR, h as DIAGRAM_GROUP, i as DataGroup, j as DataMark, c as DataNode, k as DiagramAnchor, D as DiagramData, l as DiagramDerivePose, m as DiagramEdge, n as DiagramLabel, o as DiagramMark, d as DiagramRouter, p as DiagramSceneData, a as DiagramSceneOptions, q as DiagramTextStyle, E as EdgeStyle, G as GROUP_DERIVE_POSE, r as GroupPoseOptions, N as NodeStyle, s as anchorDerivePose, t as boxAround, u as diagramAnchorOf, v as diagramEdgeOf, w as diagramGroupOf, x as diagramLabelOf, y as diagramMarkOf, z as diagramScene, B as edgeIdOf, C as groupDerivePose, F as layoutOwnsPort, H as layoutOwnsRoute, I as markShape, J as registerMarkShape } from './fromData-GKqRgPFs.js';
 import { EasingFn } from '@weasel-js/animator';
+import { Vec2 as Vec2$1 } from '@weasel-js/core/math';
 import * as react from 'react';
 import '@weasel-js/geom';
 import '@weasel-js/simulation';
@@ -24,24 +28,6 @@ import '@weasel-js/simulation';
  * `markerStart` / `markerEnd` any other stroke carries.
  */
 
-/** Where an edge attaches at one end. */
-interface EdgeEnd {
-    /** The port to leave from, when the endpoint declares one. Falls back to
-     *  the nearest port, so an edge drawn before ports were thought about still
-     *  meets the shape. */
-    port?: string;
-}
-/** The trait on an edge's `data`, under the same key participants use. */
-interface DiagramEdge {
-    from: EdgeEnd;
-    to: EdgeEnd;
-    /** Registry key for the router. Resolved by whoever builds the edge's
-     *  `derivePath`; unknown keys fall back to `straight`. */
-    router?: string;
-    /** Points in world coordinates the route must pass through, in order. The
-     *  author owns these; the router owns everything between them. */
-    waypoints?: readonly Vec2[];
-}
 /** What a router is given: the two resolved ends, and the author's waypoints
  *  between them. */
 interface RouteRequest {
@@ -68,19 +54,16 @@ declare const orthogonal: Router;
  * A smooth route, sampled into points.
  *
  * Each leg is a cubic that leaves along the departing end's normal and arrives
- * against the receiving one's. Sampled rather than emitted as curve commands so
- * every router returns the same thing.
+ * against the receiving one's, and passes each waypoint without a corner.
+ * Sampled rather than emitted as curve commands so every router returns the
+ * same thing.
  */
 declare const bezier: Router;
 /** The routers this package ships. A consumer's own go in the same shape. */
 declare const ROUTERS: Readonly<Record<string, Router>>;
-/** The edge trait on a node's data, or `null`. */
-declare function diagramEdgeOf(node: {
-    data: unknown;
-}): DiagramEdge | null;
 /**
- * The port an end resolves to: the one it named, else the port facing the
- * other end most directly.
+ * The port an end resolves to: the one it named, at whichever of its places
+ * faces `toward` most directly, else the port facing `toward` most directly.
  *
  * "Facing" rather than "nearest": a port on the far side of a wide node can be
  * closer in a straight line than the one pointing at the target.
@@ -152,6 +135,14 @@ declare const PORT_AFFORDANCE_KIND: "layer:diagram-ports";
 interface ParticipantPose<TPose> {
     node: DiagramNodeLike;
     pose: TPose;
+    /** Not drawn: on a hidden layer, or hidden on its own or by an ancestor.
+     *  `sceneParticipants` answers it from the scene's `nodeGates`. */
+    hidden?: boolean;
+    /** Out of reach: locked, or on a locked layer. */
+    locked?: boolean;
+    /** The scene layer the node is painted on, which the asking view may not
+     *  paint (`ChromeState.layerIsPainted`, `ViewApi.layerIsPainted`). */
+    layer?: string;
 }
 /** Where the affordance gets its participants. A thunk rather than a scene so
  *  the geometry is testable without one, and so a consumer whose participants
@@ -177,13 +168,21 @@ interface PortAffordanceOptions<TPose> {
     /** Which participants show their ports. Default: all of them. Gate on
      *  selection or hover by reading `state`. */
     shows?: (node: DiagramNodeLike, state: ChromeState) => boolean;
+    /** Which of a participant's ports show. Default: all of them. A port
+     *  this turns away is not painted or grabbable, and passed with the connect
+     *  options (as `diagramPorts` and `DiagramView` do), no connect lands on it. */
+    showsPort?: (port: Port) => boolean;
     /** Screen-pixel hit radius. Default 8, the kit's `HANDLE_BASE_PX`. */
     hitRadiusPx?: number;
-    /** Screen-pixel side of the painted square. Default 7. Omit `paint` entirely
-     *  by passing 0 — a port the consumer draws itself is still hittable. */
+    /** Screen-pixel size of the painted mark: a square's side, or a circle's
+     *  diameter. Default 7. Omit `paint` entirely by passing 0 — a port the
+     *  consumer draws itself is still hittable. */
     sizePx?: number;
-    fill?: CommandFill;
+    /** One fill for every port, or a function of the port — its `type`, say. */
+    fill?: CommandFill | ((port: Port) => CommandFill);
     stroke?: CommandStroke;
+    /** Default `'square'`. */
+    shape?: 'square' | 'circle';
     cursor?: CursorSpec;
     /** Default `'exclusive'` on pointer gestures: a drag from a port is a
      *  connect, never a move of the node underneath it. */
@@ -249,6 +248,10 @@ interface ConnectActionOptions<TPose> {
     geometry?: PoseDescriptor<TPose>;
     /** Default {@link defaultCanConnect}. */
     canConnect?: CanConnect;
+    /** Which ports a connect may land on: a port this turns away is never a
+     *  target. The port affordance's option of the same name, so a port that is
+     *  not shown cannot be dropped onto. Default: all of them. */
+    showsPort?: (port: Port) => boolean;
     /** How near the pointer must come to a port, in world units, before the
      *  edge snaps to it. Default 16. */
     snapRadius?: number;
@@ -364,20 +367,6 @@ declare function selfLoop(ports: readonly Port[], standoff: number): SelfLoop |
  * data, styling, z-order and selection.
  */
 
-/** Where along an edge a label sits. */
-interface DiagramLabel {
-    /** `'start'`, `'mid'` and `'end'` are 0, 0.5 and 1; a number is that
-     *  fraction of the route's length. */
-    at: 'start' | 'mid' | 'end' | number;
-    /** World units perpendicular to the route, to the **left of the direction of
-     *  travel** — above a left-to-right edge. Default 0, which centers the label
-     *  on the line. */
-    offset?: number;
-}
-/** The label trait on a node's data, or `null`. */
-declare function diagramLabelOf(node: {
-    data: unknown;
-}): DiagramLabel | null;
 /** Options for {@link labelDerivePose}. `geometry` defaults to the kit's
  *  `AUTO_POSE_DESCRIPTOR`. */
 interface LabelPoseOptions<TPose> {
@@ -405,232 +394,11 @@ declare const LABEL_DERIVE_POSE: (node: {
 }, deps: readonly (DerivedDep<unknown, unknown, string> | undefined)[]) => unknown;
 
 /**
- * A group's box, and anything pinned to a point on another node.
- *
- * The box is an ordinary node that depends on its members and derives its pose
- * from theirs: their union, grown by the inset. Drag a member and the box
- * follows; lay the diagram out and the box lands around wherever the members
- * went. Nothing has to keep it in sync, because nothing stores it.
- *
- * An anchored node — a group's title is the first — derives its pose from one
- * dependency's bounds the same way, so it travels with the box it labels.
- */
-
-/** Where an anchored node sits on its dependency. */
-interface DiagramAnchor {
-    /** The point on the dependency's bounds, normalized as a port's is. */
-    at: PortAnchor;
-    /** The point on the node's own bounds that lands there. Default `at`, so
-     *  `{ u: 0, v: 0 }` puts the node's top-left on the dependency's. */
-    self?: PortAnchor;
-    /** Then moved by this much, in world units. */
-    offset?: Vec2$1;
-}
-/** The group trait on a node's data, or `null`. */
-declare function diagramGroupOf(node: {
-    data: unknown;
-}): DiagramGroup | null;
-/** The anchor trait on a node's data, or `null`. */
-declare function diagramAnchorOf(node: {
-    data: unknown;
-}): DiagramAnchor | null;
-/** Options for {@link groupDerivePose} and {@link anchorDerivePose}.
- *  `geometry` defaults to the kit's `AUTO_POSE_DESCRIPTOR`. */
-interface GroupPoseOptions<TPose> {
-    geometry?: PoseDescriptor<TPose>;
-}
-/** A `derivePose` function as the scene calls it: the node, then what it depends on, in `dependsOn` order. */
-type DiagramDerivePose<TPose> = (node: {
-    pose: TPose;
-    data: unknown;
-}, deps: readonly (DerivedDep<TPose> | undefined)[]) => TPose | null;
-/**
- * A `derivePose` that draws a group's box around its members: their union,
- * grown by the trait's inset. `null` — the authored pose stands — when the node
- * carries no group trait or every member is gone.
- */
-declare function groupDerivePose<TPose>(opts?: GroupPoseOptions<TPose>): DiagramDerivePose<TPose>;
-/**
- * A `derivePose` that keeps a node at a point on its dependency's bounds.
- * `null` when the node carries no anchor trait or the dependency is gone.
- */
-declare function anchorDerivePose<TPose>(opts?: GroupPoseOptions<TPose>): DiagramDerivePose<TPose>;
-/** Registry key for {@link GROUP_DERIVE_POSE}. */
-declare const DIAGRAM_GROUP = "diagram:group";
-/** Registry key for {@link ANCHOR_DERIVE_POSE}. */
-declare const DIAGRAM_ANCHOR = "diagram:anchor";
-/** The default group derivation, a stable reference so `toJSON` can find its key. */
-declare const GROUP_DERIVE_POSE: DiagramDerivePose<unknown>;
-/** The default anchor derivation, a stable reference for the same reason. */
-declare const ANCHOR_DERIVE_POSE: DiagramDerivePose<unknown>;
-
-/**
- * `diagramScene` — a laid-out diagram from plain `{ nodes, edges }`.
- *
- * Every box is a `buildBody` body, so a data node can say anything a body
- * can: outline, rows, padding, ports. Sizes are estimated from character
- * counts unless `measure` is given, so layout runs without a canvas and gives
- * the same answer in node and in a browser.
+ * A live layout's producers: what each frame of a run says about where the
+ * participants are. `forceProducer` relaxes; `easedProducer` walks to a
+ * destination it knows. `useLiveLayout` (`live.ts`) runs them.
  */
 
-/** One node of a {@link DiagramData}: its rows of text, and optionally its outline, ports, size, and starting place. */
-interface DataNode {
-    id: string;
-    /** Shorthand for one `label` row per line. Ignored when `rows` is given. */
-    lines?: readonly string[];
-    rows?: readonly Row[];
-    /** Default `DiagramSceneOptions.outline`, which defaults to `'rect'`. */
-    outline?: Outline;
-    /** Perimeter ports, replacing the four compass midpoints. */
-    ports?: readonly PortSpec[];
-    /** Layout leaves this node at `at`. */
-    pinned?: boolean;
-    /** Where the node starts, before layout. Unset, nodes start on the
-     *  diagonal in source order, which is what within-rank order is seeded
-     *  from. */
-    at?: Vec2$1;
-    /** The smallest the box may be. Its content grows it past this. */
-    width?: number;
-    height?: number;
-    /** Default `DiagramSceneOptions.padding`. */
-    padding?: number;
-    /** Default `DiagramSceneOptions.gap`. */
-    gap?: number;
-    /** Default `DiagramSceneOptions.verticalAlign`. */
-    verticalAlign?: BodySpec['verticalAlign'];
-}
-/** One edge of a {@link DiagramData}, between two nodes or groups by id. */
-interface DataEdge {
-    /** A node's id, or a group's: an edge naming a group meets its box. */
-    from: string;
-    to: string;
-    /** The port to leave from or arrive at. Unset, the end facing the other
-     *  node most directly. */
-    fromPort?: string;
-    toPort?: string;
-    label?: string;
-    /** Where along the edge the label sits. Default `DiagramSceneOptions.labelPlacement`. */
-    labelPlacement?: DiagramLabel;
-    /** Default `DiagramSceneOptions.router`. */
-    router?: DiagramRouter;
-    /** World points the route passes through. Layout does not move them. */
-    waypoints?: readonly Vec2$1[];
-}
-/** A box drawn around some nodes, which layout keeps together. */
-interface DataGroup {
-    /** Shares one namespace with node ids. */
-    id: string;
-    /** Node ids, and the ids of groups nested in this one. A node or group a
-     *  later group also names stays in this one; an id that is neither is
-     *  ignored, and so is one that would put a group inside itself. */
-    members: readonly string[];
-    /** Drawn inside the box, above its members. */
-    label?: string;
-    /** Between the box and its members, and around the label. Default
-     *  `DiagramSceneOptions.groupPadding`. */
-    padding?: number;
-}
-/** A diagram as plain data, the input to `diagramScene`. */
-interface DiagramData {
-    nodes: readonly DataNode[];
-    edges: readonly DataEdge[];
-    /** A group may be a member of another. `layered`, `tree`, and `force` keep
-     *  each group's members together; `'none'` ignores groups but still draws
-     *  them. */
-    groups?: readonly DataGroup[];
-}
-/** The colors and outline a node is drawn with. */
-interface NodeStyle {
-    fill: string;
-    stroke: string;
-    text: string;
-    strokeWidth?: number;
-    dash?: number[];
-}
-/** The stroke, markers, and label color an edge is drawn with. */
-interface EdgeStyle {
-    stroke: string;
-    width?: number;
-    dash?: number[];
-    /** `null` for none. Default none. */
-    markerStart?: MarkerRef | null;
-    /** `null` for none. Default `'arrow'`. */
-    markerEnd?: MarkerRef | null;
-    /** Default `stroke`. */
-    label?: string;
-}
-/** How an edge is drawn between its ends. */
-type DiagramRouter = 'straight' | 'bezier' | 'orthogonal';
-/** The face a diagram node's text is set in. */
-type DiagramTextStyle = {
-    fontFamily: string;
-    fontSize: number;
-    fontWeight?: number;
-};
-/** The `data` of a scene node `diagramScene` makes: its diagram role, and what it paints. */
-interface DiagramSceneData {
-    diagram?: DiagramNode | DiagramEdge | {
-        label: DiagramLabel;
-    } | {
-        anchor: DiagramAnchor;
-    };
-    fill?: {
-        paint: {
-            color: string;
-        };
-    };
-    stroke?: Stroke;
-    text?: string;
-    style?: DiagramTextStyle;
-}
-/** A scene node spec, as `diagramScene` returns them. */
-type DiagramSpec = AddNodeSpec<DiagramSceneData, 'main', RectPose>;
-/** How `diagramScene` lays out, routes, and styles a {@link DiagramData}. */
-interface DiagramSceneOptions {
-    /** A layout by name, or any `LayoutFn`. Default `'layered'`. `'none'`
-     *  leaves every node at its `at`. */
-    layout?: 'layered' | 'tree' | 'force' | 'none' | LayoutFn;
-    /** Merged over `{ order: 'barycenter' }`. */
-    layoutOptions?: LayoutOptions;
-    /** Default `'bezier'`. */
-    router?: DiagramRouter;
-    /** The text style rows fall back on. Default 12px sans-serif. */
-    font?: {
-        fontFamily: string;
-        fontSize: number;
-    };
-    /** Measures one run of text. Default an estimate from character count, so
-     *  layout needs no canvas; pass `canvasMeasure(ctx)` for real widths. */
-    measure?: MeasureRowText;
-    /** Default `'rect'`. */
-    outline?: Outline;
-    /** Between a box's outline and its rows. Default 8. */
-    padding?: number;
-    /** Between adjacent rows. Default 4. */
-    gap?: number;
-    /** Where a box's rows sit when it is taller than they need. Default `'center'`. */
-    verticalAlign?: BodySpec['verticalAlign'];
-    /** The narrowest a box may be. Default 64. */
-    minWidth?: number;
-    /** Where edge labels sit. Default `{ at: 'mid', offset: 9 }`. */
-    labelPlacement?: DiagramLabel;
-    nodeStyle?: (node: DataNode) => NodeStyle;
-    /** Default 12. */
-    groupPadding?: number;
-    /** A group's box and label. `text` colors the label. */
-    groupStyle?: (group: DataGroup) => NodeStyle;
-    edgeStyle?: (edge: DataEdge) => EdgeStyle;
-}
-/** The scene node id `diagramScene` gives an edge, built from its ends, ports, and label. */
-declare const edgeIdOf: (e: DataEdge) => string;
-/** Every spec carries an id — a node's own, `<id>/<k>` for its text,
- *  `<edge id>/label`, a group's own and `<group id>/label` — so a later call's
- *  specs can be reconciled against this one's. Throws on a repeated id among
- *  nodes and groups, which names two things as one. An edge whose
- *  end is not a node is dropped, and so is a repeat of an earlier edge with
- *  the same ends, ports and label: it would draw exactly on top of the first. */
-declare function diagramScene(data: DiagramData, opts?: DiagramSceneOptions): DiagramSpec[];
-
 /** What a live producer is told, and what it answers with. */
 interface LiveLayoutCtx<TPose> {
     /** Nodes another gesture is moving, and where each is drawn. */
@@ -686,14 +454,16 @@ interface EasedProducerOptions {
  * over.
  */
 declare function easedProducer<TPose>(graph: Graph, algorithm: LayoutFn, opts?: EasedProducerOptions): LiveLayoutProducer<TPose>;
+
 /** Options for {@link useLiveLayout}. Only `scene` and `source` are required. */
 interface UseLiveLayoutOptions<TPose> {
     scene: Scene<unknown, string, TPose>;
     /** Where the graph is read from. The same thunk the port affordance takes. */
     source: GraphSource<TPose>;
-    /** A key in `LAYOUTS`, or a layout of the consumer's own. `'force'` relaxes
-     *  continuously; anything else eases to its answer. Default `'force'`. */
-    algorithm?: string | LayoutFn;
+    /** A key in `LAYOUTS`, a layout of the consumer's own, or a planner that
+     *  answers later. `'force'` relaxes continuously; anything else eases to its
+     *  answer. Default `'force'`. */
+    algorithm?: string | LayoutFn | LayoutPlanner;
     layout?: LayoutOptions;
     /** The relaxation's forces, and when a live run of it counts as at rest. */
     force?: Omit<ForceProducerOptions<TPose>, 'geometry'>;
@@ -707,6 +477,9 @@ interface UseLiveLayoutOptions<TPose> {
     /** Fires once the run has settled or been stopped and its poses are in the
      *  document, with how many participants moved. */
     onSettle?: (moved: number) => void;
+    /** Hears why a `LayoutPlanner` failed to answer, and no run starts. Unset,
+     *  the failure goes to `console.error`. */
+    onError?: (error: unknown) => void;
     /** Whether a node or edge appearing or disappearing re-heats the run.
      *  Default true — a diagram that ignores a new edge looks broken. */
     reheatOnGraphChange?: boolean;
@@ -716,9 +489,11 @@ interface UseLiveLayoutOptions<TPose> {
 }
 /** Controls for a live layout run, from {@link useLiveLayout}. */
 interface LiveLayout {
-    /** Heat and run. Idempotent while running. */
+    /** Heat and run. Idempotent while running, which includes waiting on a
+     *  planner's answer. */
     start(): void;
-    /** Finish now: commit where the nodes stand. */
+    /** Finish now: commit where the nodes stand. A planner's answer still to
+     *  come is dropped. */
     stop(): void;
     /** Abandon: the document keeps the poses it had. */
     cancel(): void;
@@ -737,6 +512,94 @@ declare function useLiveLayout<TPose>(opts: UseLiveLayoutOptions<TPose>): LiveLa
 /** The layouts that ease rather than relax, for a consumer choosing one. */
 declare const EASED_LAYOUTS: Readonly<Record<string, LayoutFn>>;
 
+/**
+ * Routes for a laid-out `layered` diagram.
+ *
+ * An edge running down the ranks leaves its source by the face toward the
+ * next rank and arrives at its target's face toward the last, so it reads
+ * along the direction the diagram flows; one running back up the ranks does
+ * the same the other way round. An edge that spans ranks runs through the
+ * waypoints `layeredPlan` placed for it.
+ */
+
+/** One edge to route, by the ids of its ends: a node's or a group's. */
+interface RouteEdge {
+    id: string;
+    from: string;
+    to: string;
+}
+/** What {@link layeredRoutes} hands an edge. A field is absent where the
+ *  default does as well. */
+interface LayeredRoute {
+    fromPort?: string;
+    toPort?: string;
+    waypoints?: readonly Vec2$1[];
+    /** The point on the route layout left the edge's label room beside, as a
+     *  `DiagramLabel`'s `{ near }`. */
+    labelAt?: Vec2$1;
+}
+/** What {@link layeredRoutes} reads: where `layeredPlan` put things. */
+interface LayeredRouteInput {
+    edges: readonly RouteEdge[];
+    /** Each node's rank, from `layeredPlan`. Empty for a layout with none,
+     *  which names no ports. */
+    ranks: ReadonlyMap<string, number>;
+    /** Each spanning edge's waypoints, from `layeredPlan`. */
+    waypoints: ReadonlyMap<string, readonly Vec2$1[]>;
+    /** Where each labeled edge's label room is among its waypoints, from
+     *  `layeredPlan`. */
+    labels?: ReadonlyMap<string, Vec2$1>;
+    /** Each group's node members, through nested groups. */
+    members: ReadonlyMap<string, readonly string[]>;
+    /** Ids whose ports are the four compass midpoints, which are the only ones
+     *  a route names. */
+    compass: ReadonlySet<string>;
+    direction?: LayoutDirection;
+}
+/** Ports and waypoints for each edge of a laid-out `layered` diagram that
+ *  needs any, keyed by edge id. */
+declare function layeredRoutes(input: LayeredRouteInput): Map<string, LayeredRoute>;
+
+/**
+ * The edge half of writing a layout to a scene: each edge's waypoints, and
+ * where its label sits among them.
+ *
+ * Layout writes only what it owns. An edge's route is its own while the edge
+ * has no waypoints or still has the ones layout last wrote (`laidOut`); a
+ * label's place is its own while the label sits at the default middle or at a
+ * `{ near }`, and its edge's route is layout's.
+ */
+
+/** Edge routes for `applyLayout` to write alongside a layout's moves. */
+interface LayoutRoutes {
+    /** Every edge the layout laid out. Each one layout owns gets its route
+     *  from `waypoints`, or loses the one a layout gave it before. */
+    edges: ReadonlySet<string>;
+    waypoints: ReadonlyMap<string, readonly Vec2$1[]>;
+    labels?: ReadonlyMap<string, Vec2$1>;
+    /** The ports layout names. Each end layout owns gets its port from here,
+     *  or loses the one a layout named before. */
+    ports?: ReadonlyMap<string, LayoutPorts>;
+}
+/** The routes `plan` laid out for `graph`'s edges. A layout that routes
+ *  nothing routes every edge straight, taking back what `layered` wrote. */
+declare function routesOf(graph: Graph, plan: LayoutPlan): LayoutRoutes;
+/** A scene as {@link routeWrites} reads it. */
+interface RoutedScene {
+    get(id: never): {
+        data: unknown;
+    } | undefined;
+    isLocked(id: never): boolean;
+    renderOrderNodes(): readonly {
+        id: string;
+        data: unknown;
+        dependsOn?: readonly string[] | 'children';
+    }[];
+}
+/** The new `data` for every edge and label whose route or place changes. A
+ *  locked edge or label is left as it is. */
+declare function routeWrites(scene: RoutedScene, routes: LayoutRoutes): Map<string, unknown>;
+
 /**
  * Running a layout against a scene: `LAYOUTS`, one batch of pose writes, and
  * the action that reaches both. A layout is a pure function of the graph;
@@ -750,12 +613,14 @@ interface ApplyLayoutOptions<TPose> {
     geometry?: PoseDescriptor<TPose>;
     /** The undo entry's name. Default `'Layout'`. */
     label?: string;
+    /** Edge routes to write in the same batch, from `routesOf`. */
+    routes?: LayoutRoutes;
 }
 /**
  * Write a layout's answer to the scene, as one undoable batch.
  *
- * Returns how many nodes moved, which is zero for a layout that had nothing to
- * do — nothing is written and no history entry is pushed.
+ * Returns how many nodes moved. A layout with nothing to do, nodes or routes,
+ * writes nothing and pushes no history entry.
  *
  * Nodes are **translated**, never re-posed from the layout's numbers: a node's
  * pose can be a path or anything else a consumer wired, and only its own
@@ -803,11 +668,18 @@ declare function createLayoutAction<TPose>(opts: LayoutActionOptions<TPose>): Ac
  */
 
 /** The minimum a participant source needs from a scene. Narrower than `Scene`
- *  so a consumer can pass anything that answers these two. */
+ *  so a consumer can pass anything that answers these. `layers` and each
+ *  node's `layer`, `parent`, `hidden` and `locked` feed `nodeGates`; a stand-in
+ *  without them gates nothing. */
 interface ParticipantScene<TPose> {
+    readonly layers?: readonly GatedLayer[];
     renderOrderNodes(): readonly {
         id: string;
         kind: 'leaf' | 'container';
+        layer?: string;
+        parent?: string | null;
+        hidden?: boolean;
+        locked?: boolean;
         data: unknown;
         pose: TPose;
         dependsOn?: readonly string[] | 'children';
@@ -821,7 +693,11 @@ interface ParticipantScene<TPose> {
     childrenOf(id: string): readonly string[];
 }
 /**
- * Every node in `scene`, at the pose it is **painted** at.
+ * Every node in `scene`, at the pose it is **painted** at, marked `hidden` or
+ * `locked` where the scene's `nodeGates` says so, and carrying its `layer` so
+ * a view that does not paint that layer can turn its ports away too. The
+ * marks keep ports off such a node; the graph reads past them, so a hidden
+ * node is still laid out.
  *
  * `effectivePose`, not `node.pose`: an override is what a gesture is currently
  * showing, and a port that answers from the document pose while its node is
@@ -829,7 +705,9 @@ interface ParticipantScene<TPose> {
  *
  * One source answers both the ports and the graph.
  */
-declare function sceneParticipants<TPose>(scene: ParticipantScene<TPose>): GraphSource<TPose>;
+declare function sceneParticipants<TPose>(scene: ParticipantScene<TPose>): () => Iterable<ParticipantPose<TPose> & {
+    node: GraphNodeLike;
+}>;
 /**
  * The composed layer, ready for `CanvasExtensionApi.registerLayer` — the only
  * attach route that is hit-tested. Handing this to `SceneCanvas`'s `layers`
@@ -871,12 +749,39 @@ declare function diagramShape<TPose>(opts?: DiagramShapeOptions<TPose>): NodeSha
  */
 declare function registerDiagramShape<TPose>(opts?: DiagramShapeOptions<TPose>): () => void;
 
+/**
+ * `DiagramView`'s two-way sync with the data it was built from: new specs are
+ * reconciled into the scene, and what a drag or a layout run changed is
+ * reported back, so a consumer keeping the diagram as data can store it.
+ * `diagramLayoutOf` reads the same report off a `diagramScene` build.
+ */
+
 /** Where a moved node now stands. */
 interface NodeMove {
     id: string;
     x: number;
     y: number;
 }
+/** An edge whose route or ports a layout run rewrote. `id` is the edge's
+ *  scene id, `edgeIdOf` of its data edge; `waypoints` is empty when the run
+ *  took a route away and left the edge straight, and `ports` names the ends
+ *  layout owns. Store them as the data edge's `routed` and `routedPorts`,
+ *  which stay layout's, not as `waypoints`, `fromPort` and `toPort`, which
+ *  would be the author's and rename the edge. */
+interface EdgeRoute {
+    id: string;
+    waypoints: readonly Vec2$1[];
+    ports: LayoutPorts;
+}
+/** What layout placed in a `diagramScene` build, in the shape `DiagramView`'s
+ *  `onMove` reports: every node not pinned, where it stands, and every edge
+ *  whose route or ports layout wrote. Store them the way `onMove` says and
+ *  the next build leaves those nodes where they are. */
+declare function diagramLayoutOf(specs: readonly DiagramSpec[]): {
+    moves: NodeMove[];
+    routes: EdgeRoute[];
+};
+
 /** Props for `DiagramView`. */
 interface DiagramViewProps {
     /** Every spec needs an id, which `diagramScene` gives them. A new array is
@@ -884,8 +789,12 @@ interface DiagramViewProps {
      *  selection and anything moved since stay put unless the new specs change
      *  them. Pass a new `key` to start over instead. */
     specs: readonly DiagramSpec[];
-    width: number;
-    height: number;
+    /** The view opens fitted to the diagram, and fits again when the size or a
+     *  fit option changes or a layout run settles, until the user pans or zooms;
+     *  from then on the view is theirs. Omit both to fill the parent, which
+     *  then needs a size of its own; a resize of the parent is a size change. */
+    width?: number;
+    height?: number;
     /** A participant id, or null for none. */
     selected?: string | null;
     /** Reports what each click leaves picked, `null` for none — a re-click on the
@@ -893,12 +802,18 @@ interface DiagramViewProps {
      *  `selected` does not follow it; only a change to `selected` is pushed in. */
     onSelect?: (id: string | null) => void;
     /** Set to let nodes be dragged. Reports every node a drag or a layout run
-     *  moved. Store each as the data node's `at` with `pinned: true`, or the
-     *  next `diagramScene` lays it out again. */
-    onMove?: (moves: readonly NodeMove[]) => void;
-    /** Set to make ports grabbable. Dragging one port onto another reports the
+     *  moved, and every edge whose route or ports a layout run rewrote. Store
+     *  each move as the data node's `at` with `pinned: true`, and each route as
+     *  the data edge's `routed` and `routedPorts`, or the next `diagramScene`
+     *  lays them out again. */
+    onMove?: (moves: readonly NodeMove[], routes: readonly EdgeRoute[]) => void;
+    /** Ports are grabbable when this is set, unless `ports` says otherwise. Dragging one port onto another reports the
      *  edge it describes and draws nothing; add it to the data to keep it. */
     onConnect?: (edge: DataEdge) => void;
+    /** Whether ports are drawn. `'connect'` draws them and lets one be dragged
+     *  onto another; `'show'` only draws them. Default: `'connect'` when
+     *  `onConnect` is set, else `'none'`. */
+    ports?: 'connect' | 'show' | 'none';
     /** Whether the canvas's keyboard shortcuts — held Space to pan among them —
      *  run. They listen page-wide, so a view-only diagram beside other UI would
      *  claim keys meant for the page. Default: on when `onMove` or `onConnect`
@@ -909,28 +824,29 @@ interface DiagramViewProps {
     canConnect?: CanConnect;
     /** How ports look and answer the pointer, and the router a connect's
      *  preview draws with. */
-    portOptions?: Pick<DiagramContributionOptions<RectPose>, 'fill' | 'stroke' | 'sizePx' | 'hitRadiusPx' | 'cursor' | 'shows' | 'snapRadius' | 'router'>;
+    portOptions?: Pick<DiagramContributionOptions<RectPose>, 'fill' | 'stroke' | 'shape' | 'sizePx' | 'hitRadiusPx' | 'cursor' | 'shows' | 'showsPort' | 'snapRadius' | 'router'>;
     /** How a layout run from {@link DiagramViewApi.layout} behaves: its forces,
-     *  how many frames an eased layout takes, its easing. */
+     *  how many frames an eased layout takes, its easing, and `onError`, which
+     *  hears a `LayoutPlanner` that failed to answer. */
     live?: Omit<UseLiveLayoutOptions<RectPose>, 'scene' | 'source' | 'algorithm'>;
-    /** The smallest scale the initial fit may use. Unset, the whole diagram fits
+    /** The smallest scale the fit may use. Unset, the whole diagram fits
      *  however small that makes it; set, it stops here and the rest is a pan away. */
     minScale?: number;
-    /** The largest scale the initial fit may use. Default 1, so a small
+    /** The largest scale the fit may use. Default 1, so a small
      *  diagram opens at its own size rather than blown up. */
     maxScale?: number;
     /** Which part of a diagram too big for the box it opens on: its middle
      *  (default) or its top-left, where a layered flow begins. */
     anchor?: 'center' | 'start';
-    /** Space kept clear around the diagram by the initial fit, in CSS pixels.
+    /** Space kept clear around the diagram by the fit, in CSS pixels.
      *  Default 16. */
     fitPadding?: number;
     /** What the canvas paints behind the diagram. Unset, it is transparent. */
     background?: Paint;
-    /** The view, controlled. Set it and the initial fit is skipped; pair it
+    /** The view, controlled. Set it and the fit is skipped; pair it
      *  with `onViewChange` or panning does nothing. */
     view?: View;
-    /** Every view change, from a pan, a zoom or the initial fit. */
+    /** Every view change, from a pan, a zoom or a refit. */
     onViewChange?: (view: View) => void;
     className?: string;
 }
@@ -938,11 +854,15 @@ interface DiagramViewProps {
 interface DiagramViewApi {
     /** Lay the diagram out again from where its nodes stand, animated. `'force'`
      *  (default) relaxes until it settles; any other layout eases to its answer.
-     *  What moved is reported to `onMove` once the run settles. */
-    layout(algorithm?: 'layered' | 'tree' | 'force' | LayoutFn): void;
+     *  A `LayoutPlanner` is handed the diagram's graph and eased to once it
+     *  answers; a drag, an edit or another `layout` call before then drops the
+     *  answer. What moved is reported to `onMove` once the run settles. */
+    layout(algorithm?: DiagramLayout): void;
     /** The run `layout` started: stop it where it stands, or cancel it. */
     live: LiveLayout;
 }
+/** What {@link DiagramViewApi.layout} runs. */
+type DiagramLayout = 'layered' | 'tree' | 'force' | 'chain' | LayoutFn | LayoutPlanner;
 /** A diagram: drag or wheel to pan, zoom, and pick a node; drag nodes with
  *  `onMove`, join ports with `onConnect`. Labels paint only in a registered
  *  font family; `diagramScene` defaults to sans-serif, so call
@@ -955,4 +875,4 @@ declare const DiagramView: react.ForwardRefExoticComponent<DiagramViewProps & re
  *  `<SceneCanvas onClick>`. */
 declare function useMirroredSelection(selection: Pick<SelectionApi, 'get' | 'set'>, selected: string | null | undefined, onSelect: ((id: string | null) => void) | undefined): () => void;
 
-export { ANCHOR_DERIVE_POSE, type ApplyLayoutOptions, BodySpec, CONNECT_ACTION_ID, type CanConnect, type ConnectActionOptions, DEFAULT_EDGE_STROKE, DIAGRAM_ANCHOR, DIAGRAM_EDGE, DIAGRAM_GROUP, DIAGRAM_LABEL, type DataEdge, type DataGroup, type DataNode, type DiagramAnchor, type DiagramContributionOptions, type DiagramData, type DiagramDerivePose, type DiagramEdge, DiagramGroup, type DiagramLabel, DiagramNode, DiagramNodeLike, DiagramNodeReader, type DiagramRouter, type DiagramSceneData, type DiagramSceneOptions, type DiagramShapeOptions, type DiagramSpec, type DiagramTextStyle, DiagramView, type DiagramViewApi, type DiagramViewProps, EASED_LAYOUTS, EDGE_DERIVE_PATH, type EasedProducerOptions, type EdgeEnd, type EdgeRouteOptions, type EdgeStyle, ForceOptions, type ForceProducerOptions, GRAB_PORT_ACTION_ID, GROUP_DERIVE_POSE, Graph, GraphSource, type GroupPoseOptions, LABEL_DERIVE_POSE, LAYOUTS, LAYOUT_ACTION_ID, type LabelPoseOptions, type LayoutActionOptions, LayoutFn, LayoutOptions, LayoutResult, type LiveLayout, type LiveLayoutCtx, type LiveLayoutFrame, type LiveLayoutProducer, MeasureRowText, type NodeMove, type NodeStyle, Outline, PORT_AFFORDANCE_KIND, PORT_LAYER_ID, type ParticipantPose, type ParticipantScene, type ParticipantSource, type PendingEdge, Port, type PortAffordanceOptions, PortAnchor, type PortScratch, PortSpec, PortsOptions, ROUTERS, type RouteRequest, type Router, Row, type SelfLoop, type UseLiveLayoutOptions, anchorDerivePose, applyLayout, bezier, commitEdgeToScene, connectBinding, createConnectAction, createDiagramContribution, createLayoutAction, createPortAffordance, defaultCanConnect, diagramAnchorOf, diagramEdgeOf, diagramGroupOf, diagramLabelOf, diagramPorts, diagramScene, diagramShape, easedProducer, edgeDerivePath, edgeIdOf, forceProducer, grabPortAction, grabPortBindings, groupDerivePose, labelDerivePose, layoutPoses, orthogonal, portLayer, portScratchOf, registerDiagramShape, resolveEnd, sceneParticipants, selfLoop, straight, useLiveLayout, useMirroredSelection, withDiagramRegistry };
+export { type ApplyLayoutOptions, CONNECT_ACTION_ID, type CanConnect, type ConnectActionOptions, DEFAULT_EDGE_STROKE, DIAGRAM_EDGE, DIAGRAM_LABEL, DataEdge, type DiagramContributionOptions, type DiagramLayout, DiagramNodeLike, DiagramNodeReader, type DiagramShapeOptions, DiagramSpec, DiagramView, type DiagramViewApi, type DiagramViewProps, EASED_LAYOUTS, EDGE_DERIVE_PATH, type EasedProducerOptions, EdgeEnd, type EdgeRoute, type EdgeRouteOptions, ForceOptions, type ForceProducerOptions, GRAB_PORT_ACTION_ID, Graph, GraphNodeLike, GraphSource, LABEL_DERIVE_POSE, LAYOUTS, LAYOUT_ACTION_ID, type LabelPoseOptions, type LayeredRoute, type LayeredRouteInput, type LayoutActionOptions, LayoutDirection, LayoutFn, LayoutOptions, LayoutPlan, LayoutPlanner, LayoutPorts, LayoutResult, type LayoutRoutes, type LiveLayout, type LiveLayoutCtx, type LiveLayoutFrame, type LiveLayoutProducer, type NodeMove, PORT_AFFORDANCE_KIND, PORT_LAYER_ID, type ParticipantPose, type ParticipantScene, type ParticipantSource, type PendingEdge, Port, type PortAffordanceOptions, type PortScratch, PortsOptions, ROUTERS, type RouteEdge, type RouteRequest, type RoutedScene, type Router, type SelfLoop, type UseLiveLayoutOptions, applyLayout, bezier, commitEdgeToScene, connectBinding, createConnectAction, createDiagramContribution, createLayoutAction, createPortAffordance, defaultCanConnect, diagramLayoutOf, diagramPorts, diagramShape, easedProducer, edgeDerivePath, forceProducer, grabPortAction, grabPortBindings, labelDerivePose, layeredRoutes, layoutPoses, orthogonal, portLayer, portScratchOf, registerDiagramShape, resolveEnd, routeWrites, routesOf, sceneParticipants, selfLoop, straight, useLiveLayout, useMirroredSelection, withDiagramRegistry };