@weasel-js/diagram 1.10.1 → 1.11.1

package/dist/{layout.entry-BUkiRKuX.d.ts → types-BbHunLXm.d.ts}

@@ -1,15 +1,16 @@
+import { Path, Vec2, PoseDescriptor } from '@weasel-js/core/math';
 import * as _weasel_js_geom from '@weasel-js/geom';
-import { Path, PoseDescriptor, Vec2 } from '@weasel-js/core/math';
-import { SimulationNode, createSimulation } from '@weasel-js/simulation';
 
 /**
  * The shapes a built body can wear, as paths in the node's bounds.
  *
  * These are the flowchart vocabulary — a decision is a diamond, an I/O step a
- * parallelogram, a terminator a stadium — plus `'rect'` for everything else and
+ * parallelogram, a terminator a stadium, a demultiplexer a trapezoid, a preparation step a hexagon,
+ * a connector an ellipse — plus `'rect'` for everything else and
  * a `Path` escape hatch for a shape the vocabulary does not have. The path is
  * built in world coordinates from the bounds it is given, the same way the
- * kit's own `clipFromPose` factories are.
+ * kit's own `clipFromPose` factories are; a custom `Path` is drawn in a unit
+ * square and stretched over them, as a mark is.
  */
 
 /** An axis-aligned box. This is `PoseDescriptor.getBounds`'s return shape
@@ -22,8 +23,10 @@ interface Bounds {
     width: number;
     height: number;
 }
-/** A named flowchart shape, or a path a consumer built themselves. */
-type Outline = 'rect' | 'diamond' | 'stadium' | 'parallelogram' | Path;
+/** A named flowchart shape, or a path a consumer built themselves in a unit
+ *  square — `(0, 0)` the box's top-left, `(1, 1)` its bottom-right — so it
+ *  follows its node wherever layout or a drag puts it. */
+type Outline = 'rect' | 'diamond' | 'stadium' | 'ellipse' | 'parallelogram' | 'trapezoid' | 'hexagon' | Path;
 /** The path `outline` describes inside `bounds`. A zero-area box gives a
  *  zero-area rect rather than a degenerate polygon. */
 declare function outlinePath(outline: Outline, bounds: Bounds): Path;
@@ -54,6 +57,208 @@ declare function boxForContent(outline: Outline, content: {
     height: number;
 };
 
+/**
+ * The label trait: where along its edge a label sits. Data only — placing the
+ * label on the route is `label`'s job, so layout can read one without
+ * reaching the scene.
+ */
+
+/** 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. `{ near }` is the point on the route
+     *  nearest `near`, in world coordinates — where `layered` leaves a label
+     *  room — so a bend added or removed elsewhere leaves the label on the
+     *  stretch it was on. */
+    at: 'start' | 'mid' | 'end' | number | {
+        near: Vec2;
+    };
+    /** World units between the route and the label's near side, 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;
+    /** Where label placement moved it, off a station something covered:
+     *  `at` a fraction of the route's length, `offset` as above. Read in place
+     *  of `at` and `offset`, which stay the author's preference. Written only
+     *  by placement (`installLabelPlacement`). */
+    placed?: LabelSpot;
+    /** `false` keeps placement from ever moving this label. */
+    dodge?: false;
+}
+/** A station placement chose: a fraction of the route's length, and the
+ *  offset from the line. */
+interface LabelSpot {
+    at: number;
+    offset: number;
+}
+/** Where an edge label sits when neither the edge nor the scene says. */
+declare const LABEL_PLACEMENT: DiagramLabel;
+/** The label trait on a node's data, or `null`. */
+declare function diagramLabelOf(node: {
+    data: unknown;
+}): DiagramLabel | null;
+
+/**
+ * The container trait: what makes a core `ContainerNode` a diagram container,
+ * a pool, or one of a pool's lanes, and where its header is.
+ *
+ * A container's title is a text child in its header, named
+ * `<container id>/title`. The layouts find it by that name, because a layout
+ * strategy sees only ids and poses.
+ */
+
+/** Which kind of region a container is. */
+type ContainerRole = 'container' | 'pool' | 'lane';
+/** The strip a container's title sits in, along one side. */
+interface ContainerHeader {
+    side: 'top' | 'left';
+    /** Its depth into the container, in world units. */
+    size: number;
+}
+/** The container half of a diagram node's trait, under `data.diagram.container`. */
+interface DiagramContainer {
+    role: ContainerRole;
+    header?: ContainerHeader;
+    /** Its box is fitted to its members each time the diagram is built from data
+     *  (`DataContainer` with no `box`), so a move that carries it along is no edit of its own. */
+    fitted?: true;
+}
+type Box = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** The container trait on a node's data, or `null`. */
+declare function diagramContainerOf(node: {
+    data: unknown;
+}): DiagramContainer | null;
+/** The id of a container's title node. */
+declare const titleIdOf: (containerId: string) => string;
+/** The header strip of a container at `bounds`; null with no header. */
+declare function headerBox(bounds: Box, header: ContainerHeader | undefined): Box | null;
+/** What a container at `bounds` holds members in: everything past its header. */
+declare function bodyBox(bounds: Box, header: ContainerHeader | undefined): Box;
+
+/** A color on a shape or connector that the author can set by hand, and a theme then leaves alone.
+ *  On a connector, `text` is its label's color. */
+type StyleField = 'fill' | 'stroke' | 'text';
+/** A part of a shape's or connector's text face the author can set by hand, which a theme then
+ *  leaves alone. Kept apart from {@link StyleField}, so choosing a role, which hands back the
+ *  colors, keeps it. */
+type FontField = 'size';
+
+/**
+ * Where a port sits on its node, in **normalized bounds coordinates**:
+ * `(0, 0)` is the top-left corner of the node's AABB and `(1, 1)` the
+ * bottom-right. `COMPASS` names the eight positions almost everything wants.
+ *
+ * Normalized rather than absolute because a node's size is authored data that
+ * resize, align and distribute all write — a port fixed at an offset would
+ * drift off the shape the first time one of them ran.
+ */
+interface PortAnchor {
+    u: number;
+    v: number;
+}
+/** One more place a port may sit, and optionally the direction it faces there. */
+interface PortSite extends PortAnchor {
+    normal?: Vec2 | null;
+}
+/** One attachment point declared on a node. */
+interface PortSpec {
+    /** Unique within the node. Edges name this, so it outlives a re-layout. */
+    id: string;
+    at: PortAnchor;
+    /** Other places the port may sit. An edge meeting the port takes whichever
+     *  of `at` and these faces the edge's next point most directly, so a
+     *  diamond's second exit can leave by its top or its bottom vertex, toward
+     *  wherever its wire goes. Everything else that shows a port where it is —
+     *  the connect affordance, `portsOf` — reads `at`. A site faces away from
+     *  the node's center unless it gives a `normal` of its own. */
+    sites?: readonly PortSite[];
+    /** Consulted by a connect gesture's validity predicate. Uninterpreted here. */
+    type?: string;
+    /** What the port is for, drawn beside it outside the node: beside the
+     *  wire rather than across it. A built body draws it and keeps it in its
+     *  `margin`; any other participant gets it on its resolved `Port`. */
+    label?: string;
+    /** The direction an edge leaves along, overriding the one the anchor
+     *  implies. `null` means "no preferred direction" — a router goes straight
+     *  at it. Applies at `at`; each of `sites` says its own. */
+    normal?: Vec2 | null;
+}
+/**
+ * The trait that makes an existing scene node a diagram participant.
+ *
+ * Attached to a node's `data`, not a node kind the plugin mints: a text block,
+ * an image, a path, a group or a plain rect all take part by carrying this,
+ * and nothing has to be authored through this package to be connectable.
+ */
+interface DiagramNode {
+    /** Defaults to {@link DEFAULT_PORTS} — the four edge midpoints of the
+     *  node's own bounds, which every node has. */
+    ports?: readonly PortSpec[];
+    /** Layout must not move this node. */
+    pinned?: boolean;
+    /** What the node is *drawn* as. Present on a built body; absent on a
+     *  participant that already had a look of its own — a text block, an image,
+     *  a path — which keeps whatever painter it already matched. */
+    outline?: Outline;
+    /** Present on a group's box: a node drawn around the participants it
+     *  depends on, which layout keeps together and leaves room for. The box
+     *  itself is never laid out — it derives its pose from its members — but an
+     *  edge can attach to it like any participant. */
+    group?: DiagramGroup;
+    /** Present on a container, a pool, or a lane: a `ContainerNode` holding
+     *  members (`containers/trait.ts`). */
+    container?: DiagramContainer;
+    /** How far past its bounds something drawn with it reaches, on each side —
+     *  a built body's port labels. Layout keeps neighbors that far off too. */
+    margin?: GroupInset;
+    /** The theme role it is drawn in. Unset, the theme's default role. */
+    style?: string;
+    /** The colors the author set by hand, which a theme leaves as they are. */
+    ownStyle?: readonly StyleField[];
+    /** The parts of its text face the author set by hand, which a theme leaves as they are. */
+    ownFont?: readonly FontField[];
+    /** On a built body whose rows are all text: how it stacks them, so it can be laid out again when
+     *  their text changes size. Each row's text node carries its place as `bodyRow`. */
+    body?: BodyLayout;
+}
+/** How a built body stacks its text rows: the `BodySpec` fields its layout reads, and how many rows. */
+interface BodyLayout {
+    padding: number;
+    gap: number;
+    verticalAlign: 'top' | 'center' | 'bottom';
+    rows: number;
+}
+/** The group half of a {@link DiagramNode}. */
+interface DiagramGroup {
+    /** Room the box keeps around its members, in world units: one number for
+     *  every side, or per side. Default 12 on each. */
+    inset?: number | Partial<GroupInset>;
+    /** The narrowest the box may be, in world units, as room for its label.
+     *  A box its members leave narrower grows evenly on both sides. */
+    minWidth?: number;
+    /** The axis its members can be dragged along to change their order. */
+    reorder?: 'x' | 'y';
+}
+/** A port resolved against a node's current pose: where it is in world
+ *  coordinates, and which way an edge leaves it. */
+interface Port {
+    id: string;
+    /** The node this port belongs to. */
+    nodeId: string;
+    /** World point an edge attaches to. */
+    point: Vec2;
+    /** Unit vector pointing away from the node, or `null` when the port
+     *  declared no direction. Rotated with the node. */
+    normal: Vec2 | null;
+    type?: string;
+    label?: string;
+}
+
 /**
  * Reading the `DiagramNode` trait off a scene node.
  *
@@ -97,7 +302,7 @@ interface DiagramNodeEntry {
  *  the two apart. Without that test an edge reads as a participant declaring
  *  no ports, and collects the four defaults on the degenerate pose an edge
  *  carries. An edge label's `label` trait and an anchored node's `anchor` are
- *  excluded the same way. */
+ *  excluded the same way, and so is a pool's lane, which takes no connectors. */
 declare const dataKeyReader: DiagramNodeReader;
 /**
  * A reader over declared kinds. A trait on the node's own data still wins, so
@@ -140,6 +345,15 @@ interface GraphNode {
     pinned: boolean;
     /** The innermost group it belongs to, when it belongs to one. */
     group?: string;
+    /** Where its ports sit. Absent, the four compass midpoints
+     *  (`DEFAULT_PORTS`). */
+    ports?: readonly PortSpec[];
+    /** The shape its ports are cast onto, as `portsOf` casts them. Absent,
+     *  its bounds. */
+    outline?: Outline;
+    /** How far past `bounds` it reaches (`DiagramNode.margin`). `planOf` lays
+     *  it out as that much bigger. */
+    margin?: GroupInset;
 }
 /** A box drawn around some participants, which a layout keeps together and
  *  leaves room for. */
@@ -155,6 +369,9 @@ interface GraphGroup {
     minWidth?: number;
     /** The group this one is directly inside. */
     parent?: string;
+    /** Its direct members, nodes and groups, in the order a layered layout
+     *  keeps them across every rank: set for a group that reorders. */
+    ordered?: readonly string[];
 }
 /** One connection. `id` is the edge node's own id, so a caller can go back to
  *  the scene for its trait. */
@@ -162,6 +379,37 @@ interface GraphEdge {
     id: string;
     from: string;
     to: string;
+    /** The port it leaves `from` by, when it names one. */
+    fromPort?: string;
+    /** The port it arrives at `to` by, when it names one. */
+    toPort?: string;
+    /** Room its label needs: the label's box, and how far its near side sits
+     *  from the wire (`DiagramLabel.offset`). `layered` sets the label beside
+     *  its wire in a rank of its own. */
+    label?: EdgeLabelRoom;
+    /** Where its route runs now, from `from` to `to`. `layered` starts each
+     *  placeholder where the route already crosses that rank, so a re-run keeps
+     *  the order the last one settled on. */
+    waypoints?: readonly Vec2[];
+    /** Its route is someone's own: layout leaves it, and keeps no room for it
+     *  in the ranks it crosses. */
+    authored?: boolean;
+    /** The edge as drawn, when this one stands in for an edge to or from a
+     *  group (see `expandGroupEdges`). */
+    origin?: {
+        id: string;
+        from: string;
+        to: string;
+    };
+}
+/** The room a {@link GraphEdge}'s label takes, in world units. */
+interface EdgeLabelRoom {
+    width: number;
+    height: number;
+    /** Between the wire and the label's near side, to the left of the
+     *  direction of travel; negative for the right. Default 0, which centers
+     *  the label on the wire. */
+    offset?: number;
 }
 /**
  * Nodes, edges, and the two adjacency reads a layout needs.
@@ -229,7 +477,8 @@ interface LayoutOptions {
     /** Between one rank and the next. Default 96. */
     rankGap?: number;
     /** How `layered` orders nodes within a rank. `'seeded'` (default) keeps
-     *  the order they already sit in; `'barycenter'` reorders to reduce edge
+     *  the order they already sit in, an edge's place included: where its
+     *  route crosses the rank now. `'barycenter'` reorders to reduce edge
      *  crossings, for a generated diagram with no arranged order to keep.
      *  Other layouts ignore it. */
     order?: 'seeded' | 'barycenter';
@@ -239,12 +488,53 @@ interface LayoutOptions {
      *  `1e-6` — a float-noise floor, not a snapping quantum. Raise it to let a
      *  `force` pass that has stopped doing anything useful commit nothing. */
     tolerance?: number;
+    /** `chain` only: the ids that stand on the line, in order. Unset, the
+     *  longest path through the graph. */
+    chain?: readonly string[];
+    /** `chain` only: which side of the line everything else hangs on, along
+     *  the cross axis. Default `'after'`. */
+    chainSide?: 'after' | 'before';
 }
 /** The new top-left for each node that moves. A node that is already there is
  *  absent, so an empty result means "nothing to do". */
 type LayoutResult = ReadonlyMap<string, Vec2>;
-/** Every layout in this package has this shape, and so does a consumer's. */
-type LayoutFn = (graph: Graph, opts?: LayoutOptions) => LayoutResult;
+/** A layout's answer with the edge routes it laid out, keyed by edge id. */
+interface LayoutPlan {
+    moves: LayoutResult;
+    /** For each edge layout routed: the points it runs through, from its
+     *  `from` end to its `to` end. An edge absent runs straight between its
+     *  ends. Absent altogether, the layout routes nothing. */
+    waypoints?: ReadonlyMap<string, readonly Vec2[]>;
+    /** For each edge layout left label room beside: the point on its route
+     *  the room is beside, as a `DiagramLabel`'s `{ near }`. */
+    labels?: ReadonlyMap<string, Vec2>;
+    /** For each edge layout named ports for: the port it leaves `from` by and
+     *  the one it arrives at `to` by, either absent where layout names none.
+     *  Absent altogether, the layout names no ports. */
+    ports?: ReadonlyMap<string, LayoutPorts>;
+}
+/** The ports a layout names for one edge. */
+interface LayoutPorts {
+    from?: string;
+    to?: string;
+}
+/** Every layout in this package has this shape, and so does a consumer's.
+ *  One that routes edges as well says so with `plan`. */
+interface LayoutFn {
+    (graph: Graph, opts?: LayoutOptions): LayoutResult;
+    readonly plan?: (graph: Graph, opts?: LayoutOptions) => LayoutPlan;
+}
+/** A layout that answers with a whole plan, now or later: ELK's, say, or one
+ *  computed on a server. A live run asks it once, with the graph it will ease
+ *  from, and eases to the answer the way it eases to `layered`'s. */
+interface LayoutPlanner {
+    plan(graph: Graph, opts?: LayoutOptions): LayoutPlan | Promise<LayoutPlan>;
+}
+/** A layout's plan: its own `plan`, or its moves alone. A node with a
+ *  `margin` is laid out as its footprint, so neighbors keep clear of it. */
+declare function planOf(layout: LayoutFn, graph: Graph, opts?: LayoutOptions): LayoutPlan;
+/** `planner`'s plan for `graph`, laid out by footprint the way {@link planOf}'s is. */
+declare function plannerPlan(planner: LayoutPlanner, graph: Graph, opts?: LayoutOptions): LayoutPlan | Promise<LayoutPlan>;
 /** `LayoutOptions.nodeGap`'s default, in world units. */
 declare const DEFAULT_NODE_GAP = 48;
 /** `LayoutOptions.rankGap`'s default, in world units. */
@@ -295,6 +585,9 @@ declare function untilSettled(once: LayoutFn, graph: Graph, opts?: LayoutOptions
  * coordinates.
  */
 declare function translated(graph: Graph, placed: ReadonlyMap<string, Vec2>, pinned: ReadonlySet<string>, tolerance?: number): LayoutResult;
+/** How far {@link translated} moves a placement: onto the first pinned node,
+ *  or else so its low corner lands on the graph's current one. */
+declare function anchorOffset(graph: Graph, placed: ReadonlyMap<string, Vec2>, pinned: ReadonlySet<string>): Vec2;
 /**
  * Lay a list of nodes out along the cross axis, in the order given, and hand
  * back each one's low corner plus the total span.
@@ -342,7 +635,7 @@ declare const DEFAULT_GROUP_INSET = 12;
  * across it. A group's inset there includes that of any group nested in it
  * that ends, or starts, at the same rank. `rows` is the nodes of each rank.
  */
-declare function rankGaps(graph: Graph, rows: readonly (readonly GraphNode[])[], axes: LayoutAxes, rankGap: number): number[];
+declare function rankGaps(graph: Pick<Graph, 'groups'>, rows: readonly (readonly Pick<GraphNode, 'id'>[])[], axes: LayoutAxes, rankGap: number): number[];
 /**
  * Cross positions for every node, with each group's members kept in a column
  * of their own, and a nested group in a column inside its parent's.
@@ -362,88 +655,74 @@ declare function packClusters(graph: Graph, rows: readonly (readonly GraphNode[]
 declare function expandGroupEdges(edges: readonly GraphEdge[], groups: readonly GraphGroup[]): GraphEdge[];
 
 /**
- * Where a port sits on its node, in **normalized bounds coordinates**:
- * `(0, 0)` is the top-left corner of the node's AABB and `(1, 1)` the
- * bottom-right. `COMPASS` names the eight positions almost everything wants.
+ * Perimeter port labels: where the text naming a port is drawn, and how far
+ * past its node that reaches.
  *
- * Normalized rather than absolute because a node's size is authored data that
- * resize, align and distribute all write — a port fixed at an offset would
- * drift off the shape the first time one of them ran.
+ * A label sits outside the node, on the port's own face, and to one side of
+ * the line the port's wire leaves along, so the wire does not run through it.
+ * A port inside a row draws its label inside the box instead; that is a
+ * `ports` row's job, not this module's.
  */
-interface PortAnchor {
-    u: number;
-    v: number;
-}
-/** One attachment point declared on a node. */
-interface PortSpec {
-    /** Unique within the node. Edges name this, so it outlives a re-layout. */
-    id: string;
-    at: PortAnchor;
-    /** Consulted by a connect gesture's validity predicate. Uninterpreted here. */
-    type?: string;
-    /** The direction an edge leaves along, overriding the one the anchor
-     *  implies. `null` means "no preferred direction" — a router goes straight
-     *  at it. */
-    normal?: Vec2 | null;
-}
+
+/** Between a port and the near sides of its label, in world units. */
+declare const PORT_LABEL_GAP = 4;
 /**
- * The trait that makes an existing scene node a diagram participant.
+ * Where a label `size` big goes for a port at `point` facing `normal`.
  *
- * Attached to a node's `data`, not a node kind the plugin mints: a text block,
- * an image, a path, a group or a plain rect all take part by carrying this,
- * and nothing has to be authored through this package to be connectable.
+ * A port on a left or right face gets its label outside that face, above its
+ * wire; one on a top or bottom face, outside that face, right of its wire; a
+ * corner port, off the corner. A port with no direction gets it centered
+ * above.
  */
-interface DiagramNode {
-    /** Defaults to {@link DEFAULT_PORTS} — the four edge midpoints of the
-     *  node's own bounds, which every node has. */
-    ports?: readonly PortSpec[];
-    /** Layout must not move this node. */
-    pinned?: boolean;
-    /** What the node is *drawn* as. Present on a built body; absent on a
-     *  participant that already had a look of its own — a text block, an image,
-     *  a path — which keeps whatever painter it already matched. */
-    outline?: Outline;
-    /** Present on a group's box: a node drawn around the participants it
-     *  depends on, which layout keeps together and leaves room for. The box
-     *  itself is never laid out — it derives its pose from its members — but an
-     *  edge can attach to it like any participant. */
-    group?: DiagramGroup;
-}
-/** The group half of a {@link DiagramNode}. */
-interface DiagramGroup {
-    /** Room the box keeps around its members, in world units: one number for
-     *  every side, or per side. Default 12 on each. */
-    inset?: number | Partial<GroupInset>;
-    /** The narrowest the box may be, in world units, as room for its label.
-     *  A box its members leave narrower grows evenly on both sides. */
-    minWidth?: number;
-}
-/** A port resolved against a node's current pose: where it is in world
- *  coordinates, and which way an edge leaves it. */
-interface Port {
-    id: string;
-    /** The node this port belongs to. */
-    nodeId: string;
-    /** World point an edge attaches to. */
+declare function portLabelBox(port: {
     point: Vec2;
-    /** Unit vector pointing away from the node, or `null` when the port
-     *  declared no direction. Rotated with the node. */
     normal: Vec2 | null;
-    type?: string;
+}, size: {
+    width: number;
+    height: number;
+}, gap?: number): Bounds;
+/** Where a built body's perimeter port label sits, as `buildBody`'s
+ *  `portLabel` is handed it. */
+interface PerimeterPortLabelBox extends Bounds {
+    port: PortSpec;
+    side: 'outside';
+}
+/** A labeled port, resolved, and the box its label is drawn in. */
+interface PortLabelPlacement {
+    port: Port & {
+        label: string;
+    };
+    box: Bounds;
 }
+/** Every labeled port of `trait` resolved against `bounds`, with its label's
+ *  box. `size` measures one label. */
+declare function portLabelsOf(trait: DiagramNode, bounds: Bounds, size: (text: string) => {
+    width: number;
+    height: number;
+}): PortLabelPlacement[];
+/** How far `boxes` reach past `bounds` on each side; `undefined` for none. */
+declare function marginOf(bounds: Bounds, boxes: readonly Bounds[]): GroupInset | undefined;
 
 /** One line of body content. */
 type Row = 
-/** Text. `label` is the node's name; `field` is a named value. */
+/** Text. `label` is the node's name; `field` is a named value. A row with
+ *  an `id` gets a scene node of that name under the body's, so it can be
+ *  found again; one without is named by its place. Not a bare number. */
 {
     kind: 'label';
     text: string;
     style?: RowTextStyle;
-} | {
+    id?: string;
+}
+/** `room` is a value the row is measured as at least as wide as, so a
+ *  value written in later fits the box it already has. */
+ | {
     kind: 'field';
     label: string;
     value: string;
     style?: RowTextStyle;
+    id?: string;
+    room?: string;
 }
 /** A row that carries ports on its own left and right edges. */
  | {
@@ -452,10 +731,12 @@ type Row =
     right?: readonly RowPort[];
     height?: number;
 }
-/** Reserved space a consumer paints into. */
+/** Reserved space a consumer paints into. With a `width`, the body is at
+ *  least that wide and the slot's box is that wide, centered in its row. */
  | {
     kind: 'slot';
     height: number;
+    width?: number;
     id?: string;
 };
 /** A port declared on a row rather than on the node's perimeter. */
@@ -490,6 +771,8 @@ interface BodySpec {
     /** The perimeter ports, replacing the four compass midpoints. A `ports`
      *  row's own ports are added either way. */
     ports?: readonly PortSpec[];
+    /** Perimeter port labels by id, drawn outside the box; over a port's own `label`. */
+    portLabels?: Readonly<Record<string, string>>;
 }
 /** What {@link buildBody} emits: the `AddNodeSpec` fields it fills in. Named
  *  structurally rather than imported so a consumer whose scene is typed
@@ -597,9 +880,9 @@ interface BuildBodyOptions<TData, TLayer extends string, TPose extends Bounds> {
     body: (trait: DiagramNode, pose: TPose) => TData;
     /** One row's data, or `null` to leave that row undrawn. */
     row: RowNodeData<TData>;
-    /** One row port's label, or `null` to leave it undrawn. Ports with no
-     *  `label` are never offered. Omit to draw none. */
-    portLabel?: (text: string, box: RowPortBox) => TData | null;
+    /** One port's label — a row port's or a perimeter port's — or `null` to
+     *  leave it undrawn. Ports with no label are never offered. Omit to draw none. */
+    portLabel?: (text: string, box: RowPortBox | PerimeterPortLabelBox) => TData | null;
 }
 /**
  * The scene nodes a built body is: one container carrying the trait, and one
@@ -616,190 +899,28 @@ declare function buildBody<TData, TLayer extends string, TPose extends Bounds>(s
 };
 
 /**
- * Where a node's ports are, in world coordinates.
- *
- * A port is placed in the node's **unrotated** bounds, then carried through
- * the pose's rotation — the same pivot every other kit reader uses, the AABB
- * center. Bounds come from the pose descriptor rather than from `pose.width`
- * and friends, so a node whose pose is a path, an ellipse or anything else a
- * consumer wired is connectable on the same terms as a rect.
+ * Line jumps as data: the document value that turns them on, and the hops a
+ * connector carries. Plain data, so layout and any reader can use it.
  */
 
-/** The eight anchors almost everything wants, named the way a compass is. */
-declare const COMPASS: {
-    readonly nw: {
-        readonly u: 0;
-        readonly v: 0;
-    };
-    readonly n: {
-        readonly u: 0.5;
-        readonly v: 0;
-    };
-    readonly ne: {
-        readonly u: 1;
-        readonly v: 0;
-    };
-    readonly e: {
-        readonly u: 1;
-        readonly v: 0.5;
-    };
-    readonly se: {
-        readonly u: 1;
-        readonly v: 1;
-    };
-    readonly s: {
-        readonly u: 0.5;
-        readonly v: 1;
-    };
-    readonly sw: {
-        readonly u: 0;
-        readonly v: 1;
-    };
-    readonly w: {
-        readonly u: 0;
-        readonly v: 0.5;
-    };
-};
-/**
- * What a node carrying no `ports` gets: the four edge midpoints of its own
- * bounds. Every node has bounds, so every node is connectable without saying
- * anything.
- */
-declare const DEFAULT_PORTS: readonly PortSpec[];
-/** How ports are resolved against a node: its bounds, and its trait. */
-interface PortsOptions<TPose> {
-    /** Reads the AABB a port is placed in, and the node's rotation. Defaults to
-     *  the kit's `AUTO_POSE_DESCRIPTOR`, which handles rect and path poses. */
-    geometry?: PoseDescriptor<TPose>;
-    /** How the `DiagramNode` trait is read off a node. */
-    read?: DiagramNodeReader;
+/** The document value (`scene.doc`) holding the line-jump setting: present
+ *  while hops are on, absent while off. */
+declare const HOPS_DOC_KEY = "diagram:hops";
+/** The line-jump setting while it is on. */
+interface HopsDocValue {
+    /** A hop's radius, in world units. */
+    size: number;
+}
+/** The radius a hop takes when nothing sets one. */
+declare const DEFAULT_HOP_SIZE = 5;
+/** Where a connector bows over others: a half circle of radius `r` centered
+ *  on `at`, which lies on the connector's route. `over` names the connectors
+ *  it passes over; hops closer than `2r` merge into one, which passes over all
+ *  of theirs. */
+interface EdgeHop {
+    at: Vec2;
+    over: readonly string[];
+    r: number;
 }
-/**
- * Every port on `node`, resolved against `pose`.
- *
- * Pass the pose the node is **painted** at — `effectivePose(scene, node)` —
- * not `node.pose`. A port that answers from the document pose while the node
- * is mid-drag puts an edge somewhere the user can see the node is not.
- */
-declare function portsOf<TPose>(node: DiagramNodeLike, pose: TPose, opts?: PortsOptions<TPose>): Port[];
-/** One named port, or `undefined` when the node has no such port. */
-declare function portOf<TPose>(node: DiagramNodeLike, pose: TPose, portId: string, opts?: PortsOptions<TPose>): Port | undefined;
-
-/**
- * `force` — relaxation, for a graph with no direction to read it in.
- *
- * Seeded from where the nodes already are rather than from a fresh random
- * scatter: an author who has arranged half a diagram gets that arrangement
- * relaxed, not replaced. There is no RNG in it at all — two coincident nodes
- * are separated along a golden-angle spiral keyed to their index.
- *
- * The forces are the naive O(n²) kind — right for tens to hundreds of nodes,
- * wrong for a 10k-node graph.
- *
- * **This is the one layout that is not idempotent.** A relaxation re-run from
- * its own output keeps relaxing; `direction` means nothing to it. Pins and the
- * `tolerance` option are what keep a second pass from scrambling a settled
- * diagram.
- */
-
-/** Options for {@link force} and {@link forceRelaxation}. `direction` is
- *  ignored. */
-interface ForceOptions extends LayoutOptions {
-    /** Ticks to run. Default 300 — one full cooling schedule. */
-    iterations?: number;
-    /** Rest length of an edge, in world units. Default 160. */
-    linkDistance?: number;
-    /** How hard an edge pulls, 0..1. Default 0.35. */
-    linkStrength?: number;
-    /** Pairwise repulsion. Negative repels; default -3000. */
-    charge?: number;
-    /** How hard the graph is held around its own centroid. Default 0.02. */
-    gravity?: number;
-    /** Clear space kept between two boxes, in world units. Default 24. */
-    padding?: number;
-    /** How hard a group draws its members together, 0..1. Default 0.2. */
-    groupStrength?: number;
-}
-/** One node as the relaxation sees it: a simulation point centered on the
- *  node's box. */
-interface ForceBody extends SimulationNode {
-    id: string;
-    /** Half the node's box, so separation can work on the shape the author sees
-     *  rather than on a point. */
-    hw: number;
-    hh: number;
-}
-/**
- * The bodies and the force list, wound up and ready to tick.
- */
-interface ForceRelaxation {
-    bodies: ForceBody[];
-    byId: Map<string, ForceBody>;
-    /** Ids the caller must not move: declared pins, held as `fx`/`fy`. */
-    pinned: ReadonlySet<string>;
-    sim: ReturnType<typeof createSimulation<ForceBody>>;
-    /** Where a body's node's top-left sits, given the body's center. */
-    placed(): Map<string, {
-        x: number;
-        y: number;
-    }>;
-}
-/** Wind up a relaxation of `graph` without ticking it: bodies seeded from
- *  where the nodes are, pins held fixed. Tick `sim` yourself and read the
- *  top-lefts from `placed()`. */
-declare function forceRelaxation(graph: Graph, opts?: ForceOptions): ForceRelaxation;
-/** The force-directed layout. Unlike the others it is not idempotent: a
- *  re-run keeps relaxing, so pins and `tolerance` are what hold a settled
- *  diagram still. */
-declare const force: (graph: Graph, opts?: ForceOptions) => LayoutResult;
-
-/** Edge ids that close a cycle, found by a depth-first walk in graph order. */
-declare function backEdges(graph: Graph): Set<string>;
-/** Longest-path rank per node: one past its deepest predecessor. */
-declare function ranksOf(graph: Graph, back: ReadonlySet<string>): Map<string, number>;
-/** The ranked layout: each edge points one rank further along `direction`.
- *  Within a rank, nodes keep their current cross-axis order, so a re-run
- *  moves nothing — except under `order: 'barycenter'`, which reorders them. */
-declare const layered: LayoutFn;
-
-/** A graph read as trees: its roots, each node's children in order, and each node's depth. */
-interface Forest {
-    roots: GraphNode[];
-    children: Map<string, GraphNode[]>;
-    depth: Map<string, number>;
-}
-/** The forest a depth-first walk in graph order finds. Exported because "which
- *  node ended up whose child" is the question anyone debugging a tree layout
- *  asks first. */
-declare function forestOf(graph: Graph, crossAxis: 'x' | 'y'): Forest;
-/** The hierarchy layout: each parent centered over its children's block, one
- *  rank per depth. A graph that is not a tree lays out as the forest
- *  {@link forestOf} reads from it. */
-declare const tree: LayoutFn;
-
-/** The outline as a closed polyline: `[x0, y0, x1, y1, …]`. */
-declare function outlinePolyline(outline: Outline, bounds: Bounds): number[];
-/**
- * Where the ray from `center` through `point` last crosses `poly`, or `null`
- * when it never does.
- *
- * The *last* crossing rather than the first: a concave outline can be crossed
- * more than once, and the far side is the boundary an edge should attach to.
- */
-declare function rayHit(poly: readonly number[], center: {
-    x: number;
-    y: number;
-}, point: {
-    x: number;
-    y: number;
-}): {
-    x: number;
-    y: number;
-} | null;
-/**
- * Every port moved onto `outline`. A port the ray misses — one at the node's
- * dead center, with no direction to cast along — is left where it was.
- */
-declare function portsOnOutline(ports: readonly Port[], outline: Outline, bounds: Bounds): Port[];
 
-export { canvasMeasure as $, type GraphNode as A, type BodySpec as B, COMPASS as C, type DiagramNodeLike as D, type GraphNodeLike as E, type ForceOptions as F, type GraphSource as G, type GroupInset as H, type LayoutAxes as I, type RowBox as J, type RowNodeData as K, type LayoutFn as L, type MeasureRowText as M, type RowPort as N, type Outline as O, type Port as P, type RowPortBox as Q, type Row as R, type RowTextStyle as S, type Slot as T, axesFor as U, backEdges as V, bodyOutline as W, bodyTrait as X, boxForContent as Y, buildBody as Z, buildGraph as _, type PortsOptions as a, contentBox as a0, createDiagramNodes as a1, dataKeyReader as a2, diagramNodeOf as a3, expandGroupEdges as a4, force as a5, forceRelaxation as a6, forestOf as a7, graphOrder as a8, insetOf as a9, isPinned as aa, layered as ab, layoutBody as ac, layoutRowPorts as ad, measureBody as ae, outlinePath as af, outlinePolyline as ag, packAcross as ah, packClusters as ai, pinnedSet as aj, portOf as ak, portsOf as al, portsOnOutline as am, rankGaps as an, ranksOf as ao, rayHit as ap, seededOrder as aq, settle as ar, sizeToBody as as, translated as at, tree as au, untilSettled as av, extent as aw, type DiagramNodeReader as b, type PortAnchor as c, type DiagramGroup as d, type PortSpec as e, type DiagramNode as f, type LayoutOptions as g, type LayoutResult as h, type Graph as i, type LayoutDirection as j, type BodyFloor as k, type BodyNodeSpec as l, type Bounds as m, type BuildBodyOptions as n, type BuildGraphOptions as o, DEFAULT_GROUP_INSET as p, DEFAULT_NODE_GAP as q, DEFAULT_PORTS as r, DEFAULT_RANK_GAP as s, DIAGRAM_TRAIT_KEY as t, type DiagramNodeEntry as u, type ForceBody as v, type ForceRelaxation as w, type Forest as x, type GraphEdge as y, type GraphGroup as z };
+export { type PortSite as $, DEFAULT_RANK_GAP as A, type BodySpec as B, type ContainerRole as C, type DiagramGroup as D, type EdgeHop as E, type FontField as F, type Graph as G, DIAGRAM_TRAIT_KEY as H, type DiagramNodeEntry as I, type EdgeLabelRoom as J, type GraphEdge as K, type LayoutPorts as L, type MeasureRowText as M, type GraphGroup as N, type Outline as O, type PortAnchor as P, type GraphNode as Q, type RowTextStyle as R, type StyleField as S, type GroupInset as T, HOPS_DOC_KEY as U, type HopsDocValue as V, LABEL_PLACEMENT as W, type LayoutAxes as X, PORT_LABEL_GAP as Y, type PerimeterPortLabelBox as Z, type PortLabelPlacement as _, type Row as a, type RowBox as a0, type RowNodeData as a1, type RowPort as a2, type RowPortBox as a3, type Slot as a4, anchorOffset as a5, axesFor as a6, bodyBox as a7, bodyOutline as a8, bodyTrait as a9, portLabelsOf as aA, rankGaps as aB, seededOrder as aC, settle as aD, sizeToBody as aE, titleIdOf as aF, translated as aG, untilSettled as aH, extent as aI, boxForContent as aa, buildBody as ab, buildGraph as ac, canvasMeasure as ad, contentBox as ae, createDiagramNodes as af, dataKeyReader as ag, diagramContainerOf as ah, diagramLabelOf as ai, diagramNodeOf as aj, expandGroupEdges as ak, graphOrder as al, headerBox as am, insetOf as an, isPinned as ao, layoutBody as ap, layoutRowPorts as aq, marginOf as ar, measureBody as as, outlinePath as at, packAcross as au, packClusters as av, pinnedSet as aw, planOf as ax, plannerPlan as ay, portLabelBox as az, type PortSpec as b, type DiagramLabel as c, type LayoutFn as d, type LayoutOptions as e, type DiagramNode as f, type Port as g, type DiagramNodeLike as h, type DiagramNodeReader as i, type DiagramContainer as j, type ContainerHeader as k, type LabelSpot as l, type Bounds as m, type LayoutResult as n, type GraphSource as o, type LayoutPlanner as p, type LayoutDirection as q, type LayoutPlan as r, type GraphNodeLike as s, type BodyFloor as t, type BodyNodeSpec as u, type BuildBodyOptions as v, type BuildGraphOptions as w, DEFAULT_GROUP_INSET as x, DEFAULT_HOP_SIZE as y, DEFAULT_NODE_GAP as z };