@weasel-js/diagram 1.9.2 → 1.9.4

package/dist/{layout.entry-W-8PYfGM.d.ts → layout.entry-DyKFfHG5.d.ts}

@@ -1,5 +1,5 @@
 import * as _weasel_js_geom from '@weasel-js/geom';
-import { Path, Vec2, PoseDescriptor, SimulationNode, createSimulation } from '@weasel-js/core/math';
+import { Path, PoseDescriptor, Vec2, SimulationNode, createSimulation } from '@weasel-js/core/math';
 
 /**
  * The shapes a built body can wear, as paths in the node's bounds.
@@ -53,6 +53,340 @@ declare function boxForContent(outline: Outline, content: {
     height: number;
 };
 
+/**
+ * Reading the `DiagramNode` trait off a scene node.
+ *
+ * Two ways to attach it, both of which this module's default reader answers:
+ *
+ *   - **On the node.** `data.diagram` holds the trait. One node, one answer;
+ *     what a connect gesture writes when the author drags a new edge.
+ *   - **By kind.** A consumer declares once which data shapes take part, and
+ *     every matching node gets the trait without being stamped. This mirrors
+ *     `createNodeRouting` in the kit — a predicate over `data`, first match
+ *     wins — and is the shape to reach for when the participants are a class
+ *     of node rather than a hand-picked set.
+ *
+ * A reader is a plain function, so a consumer whose data lives somewhere else
+ * entirely passes their own and never touches either form.
+ */
+
+/** The key on a node's `data` the default reader looks under. */
+declare const DIAGRAM_TRAIT_KEY = "diagram";
+/** All a reader looks at. Deliberately not `SceneNode`: naming `TPose` there
+ *  would put it in a contravariant position for no gain, since nothing here
+ *  reads a pose. */
+interface DiagramNodeLike {
+    id: string;
+    kind: 'leaf' | 'container';
+    data: unknown;
+}
+/** Answers "is this node a diagram participant, and on what terms" — `null`
+ *  for a node that takes no part. */
+type DiagramNodeReader = (node: DiagramNodeLike) => DiagramNode | null;
+/** One class of participant, declared once for every node whose data matches.
+ *  Mirrors `NodeRoutingEntry`. */
+interface DiagramNodeEntry {
+    /** Unique within a reader; the same vocabulary as `NodeRoutingEntry.name`. */
+    name: string;
+    matches: (data: unknown) => boolean;
+    /** The trait every matching node carries. A function when it varies with the
+     *  node's own data — a pipeline stage whose ports come from its rows. */
+    trait: DiagramNode | ((data: unknown) => DiagramNode);
+}
+/** The trait on the node's own `data.diagram`, or `null`.
+ *
+ *  An edge's trait lives under the same key, so `from` and `to` are what tells
+ *  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 — four grabbable ports in the middle of nowhere. An edge label's
+ *  `label` trait and an anchored node's `anchor` are the same story, and would
+ *  also take a slot in every layout. */
+declare const dataKeyReader: DiagramNodeReader;
+/**
+ * A reader over declared kinds. A trait on the node's own data still wins, so
+ * a single node can opt out of, or override, whatever its kind says.
+ *
+ * Throws on a duplicate `name`, for the reason `mergeContributions` does: a
+ * class of node silently losing its ports is what this registry exists to make
+ * loud.
+ */
+declare function createDiagramNodes(entries: readonly DiagramNodeEntry[]): DiagramNodeReader;
+/** The trait `node` carries, through `read` (default: its own `data.diagram`). */
+declare function diagramNodeOf(node: DiagramNodeLike, read?: DiagramNodeReader): DiagramNode | null;
+/** True when layout must leave this node where it is. */
+declare function isPinned(node: DiagramNodeLike, read?: DiagramNodeReader): boolean;
+
+/**
+ * `Graph` — the adjacency index a layout runs over.
+ *
+ * The scene is the document, so there is no second graph kept in sync with it:
+ * this one is built from the scene on demand, used, and thrown away. Rebuilding
+ * per layout invocation is deliberate — a maintained index is a cache to
+ * invalidate on every add, delete, reparent and `dependsOn` edit, and layout is
+ * not on the hot path. Measure before changing that.
+ *
+ * A node's *identity* is its id and its *size* is its bounds; where it currently
+ * sits is here too, because a re-layout that ignores where things already are
+ * scrambles a diagram the author has arranged.
+ */
+
+/** A scene node as the graph reads it. `dependsOn` is what an edge's two
+ *  endpoints are: the edge trait names *ports*, and the nodes those ports are
+ *  on are the dependencies the derivation already runs on. */
+interface GraphNodeLike extends DiagramNodeLike {
+    dependsOn?: readonly string[] | 'children';
+}
+/** Where the graph gets its nodes. The same thunk shape the port affordance
+ *  takes, so one source answers both. */
+type GraphSource<TPose> = () => Iterable<{
+    node: GraphNodeLike;
+    pose: TPose;
+}>;
+/** One participant. */
+interface GraphNode {
+    id: string;
+    /** Where it is now, in world coordinates. */
+    bounds: Bounds;
+    /** Layout must not move it. */
+    pinned: boolean;
+    /** The innermost group it belongs to, when it belongs to one. */
+    group?: string;
+}
+/** A box drawn around some participants, which a layout keeps together and
+ *  leaves room for. */
+interface GraphGroup {
+    id: string;
+    /** Every participant inside, through any group nested in this one, in
+     *  source order. */
+    members: readonly string[];
+    /** Room the box keeps around what it holds, in world units. */
+    inset: GroupInset;
+    /** The group this one is directly inside. */
+    parent?: string;
+}
+/** One connection. `id` is the edge node's own id, so a caller can go back to
+ *  the scene for its trait. */
+interface GraphEdge {
+    id: string;
+    from: string;
+    to: string;
+}
+/**
+ * Nodes, edges, and the two adjacency reads a layout needs.
+ *
+ * Every list is in source order — render order, when the source is a scene —
+ * which is what a layout's tiebreaks resolve against. There is no RNG anywhere
+ * downstream of this, and this is where that starts.
+ */
+interface Graph {
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+    /** Absent or empty for a graph with no groups. */
+    readonly groups?: readonly GraphGroup[];
+    node(id: string): GraphNode | undefined;
+    /** Edges leaving `id`, in source order. */
+    outgoing(id: string): readonly GraphEdge[];
+    /** Edges arriving at `id`, in source order. */
+    incoming(id: string): readonly GraphEdge[];
+}
+/** Options for {@link buildGraph}: how the trait is read, and how a pose
+ *  yields bounds. Both default to the kit's own. */
+interface BuildGraphOptions<TPose> {
+    read?: DiagramNodeReader;
+    geometry?: PoseDescriptor<TPose>;
+}
+/**
+ * Read a graph out of a source of scene nodes.
+ *
+ * A node is an edge if it carries the edge trait and names exactly two
+ * dependencies; a group if its trait carries `group`, with its dependencies as
+ * its members, which may be groups themselves (see `nestGroups`); a participant if the reader hands back any other
+ * `DiagramNode`; and otherwise not in the diagram at all. An edge whose
+ * endpoints are not both participants or groups is dropped — a dangling edge
+ * should not be ranking anything — and an edge to a group ranks against its
+ * members (see `expandGroupEdges`).
+ */
+declare function buildGraph<TPose>(source: GraphSource<TPose>, opts?: BuildGraphOptions<TPose>): Graph;
+
+/**
+ * Layout: where the participants go.
+ *
+ * A layout is a pure function of the graph — no scene, no ops, no history. It
+ * hands back the new top-left for every node that **moves**, and a node already
+ * standing where the layout wants it is simply absent from the answer. That is
+ * what makes re-running a layout free rather than destructive, and it is the
+ * property the idempotence test asserts.
+ *
+ * Three rules keep re-layout non-destructive, and all three live here rather
+ * than in each algorithm:
+ *
+ *   - **No RNG anywhere.** Every tiebreak falls back to the graph's own node
+ *     order, which is the source's order — render order, for a scene.
+ *   - **Within-rank order is seeded from where the nodes already are**, read
+ *     off the cross axis, rather than from crossing-minimization. An author who
+ *     dragged two boxes into an order gets that order back.
+ *   - **A pin set nothing moves.** Pinned nodes are never in the result, and
+ *     the rest of the layout is translated to sit around them.
+ *
+ * `layered` and `tree` are idempotent by construction: the second run reads the
+ * order the first run produced and computes the same slots. `force` is an
+ * iterative relaxation and makes no such claim — re-running it keeps relaxing.
+ */
+
+/** Which way the ranks stack. `force` ignores it. */
+type LayoutDirection = 'down' | 'up' | 'right' | 'left';
+/** Options every layout takes. */
+interface LayoutOptions {
+    /** Default `'down'`. */
+    direction?: LayoutDirection;
+    /** Between neighbors within a rank, in world units. Default 48. */
+    nodeGap?: number;
+    /** 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
+     *  crossings, for a generated diagram with no arranged order to keep.
+     *  Other layouts ignore it. */
+    order?: 'seeded' | 'barycenter';
+    /** Ids layout must not move, on top of whatever carries `pinned: true`. */
+    pin?: Iterable<string>;
+    /** How far a node has to move to be worth moving, in world units. Default
+     *  `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;
+}
+/** 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;
+/** `LayoutOptions.nodeGap`'s default, in world units. */
+declare const DEFAULT_NODE_GAP = 48;
+/** `LayoutOptions.rankGap`'s default, in world units. */
+declare const DEFAULT_RANK_GAP = 96;
+/** Which world axis carries ranks, which carries within-rank order, and
+ *  whether ranks grow toward positive world coordinates. */
+interface LayoutAxes {
+    rank: 'x' | 'y';
+    cross: 'x' | 'y';
+    /** `-1` for `'up'` and `'left'`, where the canonical frame is mirrored. */
+    sign: 1 | -1;
+}
+/** The axes a direction lays ranks along. Default `'down'`. */
+declare function axesFor(direction?: LayoutDirection): LayoutAxes;
+/** A node's extent along one axis. */
+declare function extent(bounds: Bounds, axis: 'x' | 'y'): number;
+/** Every id layout must leave alone. */
+declare function pinnedSet(graph: Graph, opts?: LayoutOptions): Set<string>;
+/**
+ * A placement in the canonical `(cross, rank)` frame, before it is turned into
+ * world coordinates. `cross` and `rank` are the node's low corner along each.
+ */
+interface Slot {
+    cross: number;
+    rank: number;
+}
+/**
+ * Turn canonical slots into the positions to write.
+ *
+ * Three steps, in order: map the canonical frame onto the world axes the
+ * direction names; translate the whole layout so it lands where the graph
+ * already is; drop everything that is pinned or that would not move.
+ *
+ * The translation is what makes the layout non-destructive, and it is chosen so
+ * that a second run lands on the same answer. With a pin, it is whatever keeps
+ * the first pinned node exactly where it is. Without one, it is whatever puts
+ * the layout's own bounding box where the graph's bounding box already starts —
+ * which the first run then makes true, so the second run computes the same
+ * translation and writes nothing.
+ */
+declare function settle(graph: Graph, slots: ReadonlyMap<string, Slot>, opts?: LayoutOptions): LayoutResult;
+/**
+ * Run `once` until a pass moves nothing, and answer with where that leaves
+ * each node.
+ *
+ * A layout that keeps groups together can move an outsider out of a group's
+ * column, which changes the order the next run would start from. Its answer
+ * has to be the arrangement a re-run keeps, so it re-runs here rather than
+ * leaving the second pass to the caller. `passes` bounds an arrangement that
+ * never comes to rest.
+ */
+declare function untilSettled(once: LayoutFn, graph: Graph, opts?: LayoutOptions, passes?: number): LayoutResult;
+/**
+ * {@link settle}'s second half, for a layout that already works in world
+ * coordinates — `force` does, since the integrator moves points around rather
+ * than filling slots.
+ */
+declare function translated(graph: Graph, placed: ReadonlyMap<string, Vec2>, pinned: ReadonlySet<string>, tolerance?: number): LayoutResult;
+/**
+ * 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.
+ *
+ * Shared by `layered`'s ranks and `tree`'s sibling rows, which pack a row the
+ * same way and differ only in what decides the order.
+ */
+declare function packAcross(nodes: readonly GraphNode[], axis: 'x' | 'y', gap: number): {
+    at: Map<string, number>;
+    span: number;
+};
+/** Order within a rank: where the nodes already sit on the cross axis, with
+ *  graph order breaking a tie. Never a comparison that could reverse between
+ *  two runs on the same input. */
+declare function seededOrder(nodes: readonly GraphNode[], axis: 'x' | 'y', indexOf: (id: string) => number): GraphNode[];
+/** Each node's position in `graph.nodes`, for tiebreaks. */
+declare function graphOrder(graph: Graph): (id: string) => number;
+
+/**
+ * Clusters: keeping a group's members together through a ranked layout.
+ *
+ * A group's box is the union of its members plus an inset, so the layout's job
+ * is to leave a rectangle for it that nothing else enters. Each group gets a
+ * **column** on the cross axis, reserved in every rank from its first member's
+ * to its last — including a rank in between that holds none of its members, or
+ * an outsider would land inside the box there. Groups keep one cross position
+ * across every rank, so two groups' columns never cross and their boxes never
+ * overlap. Ungrouped nodes pack around the columns rank by rank, as before.
+ *
+ * A group may be a member of another: its column then sits inside its parent's.
+ */
+
+/** Room a group's box keeps around its members, in world units. */
+interface GroupInset {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** A `DiagramGroup.inset` as all four sides. Default 12 on every side. */
+declare function insetOf(inset: number | Partial<GroupInset> | undefined): GroupInset;
+/** `DiagramGroup.inset`'s default on each side, in world units. */
+declare const DEFAULT_GROUP_INSET = 12;
+/**
+ * The gap between each rank and the next, widened so a group's box fits: the
+ * widest inset of a group ending at rank `i` and of one starting at `i + 1`
+ * both come on top of `rankGap`, since those two boxes can face each other
+ * 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[];
+/**
+ * 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.
+ * `preferred` is where the layout would put each node's low corner with no
+ * groups at all; nodes and columns keep that order and are only ever pushed
+ * toward the high end, by as much as it takes to stop overlapping.
+ */
+declare function packClusters(graph: Graph, rows: readonly (readonly GraphNode[])[], preferred: ReadonlyMap<string, number>, axes: LayoutAxes, nodeGap: number): Map<string, number>;
+/**
+ * Edges as a layout should rank by: one into a group arrives at its entry
+ * members — those no other member points at — and one out of it leaves from its
+ * exit members. A group with no such member, a pure cycle, is all entries and
+ * all exits. An edge between a group and something inside it, a member or a
+ * nested group, is that group's internal business and ranks nothing beyond
+ * what its member-to-member edges already do.
+ */
+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
@@ -95,6 +429,17 @@ interface DiagramNode {
      *  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>;
 }
 /** A port resolved against a node's current pose: where it is in world
  *  coordinates, and which way an edge leaves it. */
@@ -303,67 +648,6 @@ declare function buildBody<TData, TLayer extends string, TPose extends Bounds>(s
     specs: BodyNodeSpec<TData, TLayer, TPose>[];
 };
 
-/**
- * Reading the `DiagramNode` trait off a scene node.
- *
- * Two ways to attach it, both of which this module's default reader answers:
- *
- *   - **On the node.** `data.diagram` holds the trait. One node, one answer;
- *     what a connect gesture writes when the author drags a new edge.
- *   - **By kind.** A consumer declares once which data shapes take part, and
- *     every matching node gets the trait without being stamped. This mirrors
- *     `createNodeRouting` in the kit — a predicate over `data`, first match
- *     wins — and is the shape to reach for when the participants are a class
- *     of node rather than a hand-picked set.
- *
- * A reader is a plain function, so a consumer whose data lives somewhere else
- * entirely passes their own and never touches either form.
- */
-
-/** The key on a node's `data` the default reader looks under. */
-declare const DIAGRAM_TRAIT_KEY = "diagram";
-/** All a reader looks at. Deliberately not `SceneNode`: naming `TPose` there
- *  would put it in a contravariant position for no gain, since nothing here
- *  reads a pose. */
-interface DiagramNodeLike {
-    id: string;
-    kind: 'leaf' | 'container';
-    data: unknown;
-}
-/** Answers "is this node a diagram participant, and on what terms" — `null`
- *  for a node that takes no part. */
-type DiagramNodeReader = (node: DiagramNodeLike) => DiagramNode | null;
-/** One class of participant, declared once for every node whose data matches.
- *  Mirrors `NodeRoutingEntry`. */
-interface DiagramNodeEntry {
-    /** Unique within a reader; the same vocabulary as `NodeRoutingEntry.name`. */
-    name: string;
-    matches: (data: unknown) => boolean;
-    /** The trait every matching node carries. A function when it varies with the
-     *  node's own data — a pipeline stage whose ports come from its rows. */
-    trait: DiagramNode | ((data: unknown) => DiagramNode);
-}
-/** The trait on the node's own `data.diagram`, or `null`.
- *
- *  An edge's trait lives under the same key, so `from` and `to` are what tells
- *  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 — four grabbable ports in the middle of nowhere. */
-declare const dataKeyReader: DiagramNodeReader;
-/**
- * A reader over declared kinds. A trait on the node's own data still wins, so
- * a single node can opt out of, or override, whatever its kind says.
- *
- * Throws on a duplicate `name`, for the reason `mergeContributions` does: a
- * class of node silently losing its ports is what this registry exists to make
- * loud.
- */
-declare function createDiagramNodes(entries: readonly DiagramNodeEntry[]): DiagramNodeReader;
-/** The trait `node` carries, through `read` (default: its own `data.diagram`). */
-declare function diagramNodeOf(node: DiagramNodeLike, read?: DiagramNodeReader): DiagramNode | null;
-/** True when layout must leave this node where it is. */
-declare function isPinned(node: DiagramNodeLike, read?: DiagramNodeReader): boolean;
-
 /**
  * Where a node's ports are, in world coordinates.
  *
@@ -434,197 +718,6 @@ declare function portsOf<TPose>(node: DiagramNodeLike, pose: TPose, opts?: Ports
 /** 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;
 
-/**
- * `Graph` — the adjacency index a layout runs over.
- *
- * The scene is the document, so there is no second graph kept in sync with it:
- * this one is built from the scene on demand, used, and thrown away. Rebuilding
- * per layout invocation is deliberate — a maintained index is a cache to
- * invalidate on every add, delete, reparent and `dependsOn` edit, and layout is
- * not on the hot path. Measure before changing that.
- *
- * A node's *identity* is its id and its *size* is its bounds; where it currently
- * sits is here too, because a re-layout that ignores where things already are
- * scrambles a diagram the author has arranged.
- */
-
-/** A scene node as the graph reads it. `dependsOn` is what an edge's two
- *  endpoints are: the edge trait names *ports*, and the nodes those ports are
- *  on are the dependencies the derivation already runs on. */
-interface GraphNodeLike extends DiagramNodeLike {
-    dependsOn?: readonly string[] | 'children';
-}
-/** Where the graph gets its nodes. The same thunk shape the port affordance
- *  takes, so one source answers both. */
-type GraphSource<TPose> = () => Iterable<{
-    node: GraphNodeLike;
-    pose: TPose;
-}>;
-/** One participant. */
-interface GraphNode {
-    id: string;
-    /** Where it is now, in world coordinates. */
-    bounds: Bounds;
-    /** Layout must not move it. */
-    pinned: boolean;
-}
-/** One connection. `id` is the edge node's own id, so a caller can go back to
- *  the scene for its trait. */
-interface GraphEdge {
-    id: string;
-    from: string;
-    to: string;
-}
-/**
- * Nodes, edges, and the two adjacency reads a layout needs.
- *
- * Every list is in source order — render order, when the source is a scene —
- * which is what a layout's tiebreaks resolve against. There is no RNG anywhere
- * downstream of this, and this is where that starts.
- */
-interface Graph {
-    readonly nodes: readonly GraphNode[];
-    readonly edges: readonly GraphEdge[];
-    node(id: string): GraphNode | undefined;
-    /** Edges leaving `id`, in source order. */
-    outgoing(id: string): readonly GraphEdge[];
-    /** Edges arriving at `id`, in source order. */
-    incoming(id: string): readonly GraphEdge[];
-}
-/** Options for {@link buildGraph}: how the trait is read, and how a pose
- *  yields bounds. Both default to the kit's own. */
-interface BuildGraphOptions<TPose> {
-    read?: DiagramNodeReader;
-    geometry?: PoseDescriptor<TPose>;
-}
-/**
- * Read a graph out of a source of scene nodes.
- *
- * A node is an edge if it carries the edge trait and names exactly two
- * dependencies; a participant if the reader hands back a `DiagramNode`;
- * neither, and it is not in the diagram at all. An edge whose endpoints are not
- * both participants is dropped — a dangling edge should not be ranking
- * anything.
- */
-declare function buildGraph<TPose>(source: GraphSource<TPose>, opts?: BuildGraphOptions<TPose>): Graph;
-
-/**
- * Layout: where the participants go.
- *
- * A layout is a pure function of the graph — no scene, no ops, no history. It
- * hands back the new top-left for every node that **moves**, and a node already
- * standing where the layout wants it is simply absent from the answer. That is
- * what makes re-running a layout free rather than destructive, and it is the
- * property the idempotence test asserts.
- *
- * Three rules keep re-layout non-destructive, and all three live here rather
- * than in each algorithm:
- *
- *   - **No RNG anywhere.** Every tiebreak falls back to the graph's own node
- *     order, which is the source's order — render order, for a scene.
- *   - **Within-rank order is seeded from where the nodes already are**, read
- *     off the cross axis, rather than from crossing-minimization. An author who
- *     dragged two boxes into an order gets that order back.
- *   - **A pin set nothing moves.** Pinned nodes are never in the result, and
- *     the rest of the layout is translated to sit around them.
- *
- * `layered` and `tree` are idempotent by construction: the second run reads the
- * order the first run produced and computes the same slots. `force` is an
- * iterative relaxation and makes no such claim — re-running it keeps relaxing.
- */
-
-/** Which way the ranks stack. `force` ignores it. */
-type LayoutDirection = 'down' | 'up' | 'right' | 'left';
-/** Options every layout takes. */
-interface LayoutOptions {
-    /** Default `'down'`. */
-    direction?: LayoutDirection;
-    /** Between neighbors within a rank, in world units. Default 48. */
-    nodeGap?: number;
-    /** 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
-     *  crossings, for a generated diagram with no arranged order to keep.
-     *  Other layouts ignore it. */
-    order?: 'seeded' | 'barycenter';
-    /** Ids layout must not move, on top of whatever carries `pinned: true`. */
-    pin?: Iterable<string>;
-    /** How far a node has to move to be worth moving, in world units. Default
-     *  `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;
-}
-/** 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;
-/** `LayoutOptions.nodeGap`'s default, in world units. */
-declare const DEFAULT_NODE_GAP = 48;
-/** `LayoutOptions.rankGap`'s default, in world units. */
-declare const DEFAULT_RANK_GAP = 96;
-/** Which world axis carries ranks, which carries within-rank order, and
- *  whether ranks grow toward positive world coordinates. */
-interface LayoutAxes {
-    rank: 'x' | 'y';
-    cross: 'x' | 'y';
-    /** `-1` for `'up'` and `'left'`, where the canonical frame is mirrored. */
-    sign: 1 | -1;
-}
-/** The axes a direction lays ranks along. Default `'down'`. */
-declare function axesFor(direction?: LayoutDirection): LayoutAxes;
-/** A node's extent along one axis. */
-declare function extent(bounds: Bounds, axis: 'x' | 'y'): number;
-/** Every id layout must leave alone. */
-declare function pinnedSet(graph: Graph, opts?: LayoutOptions): Set<string>;
-/**
- * A placement in the canonical `(cross, rank)` frame, before it is turned into
- * world coordinates. `cross` and `rank` are the node's low corner along each.
- */
-interface Slot {
-    cross: number;
-    rank: number;
-}
-/**
- * Turn canonical slots into the positions to write.
- *
- * Three steps, in order: map the canonical frame onto the world axes the
- * direction names; translate the whole layout so it lands where the graph
- * already is; drop everything that is pinned or that would not move.
- *
- * The translation is what makes the layout non-destructive, and it is chosen so
- * that a second run lands on the same answer. With a pin, it is whatever keeps
- * the first pinned node exactly where it is. Without one, it is whatever puts
- * the layout's own bounding box where the graph's bounding box already starts —
- * which the first run then makes true, so the second run computes the same
- * translation and writes nothing.
- */
-declare function settle(graph: Graph, slots: ReadonlyMap<string, Slot>, opts?: LayoutOptions): LayoutResult;
-/**
- * {@link settle}'s second half, for a layout that already works in world
- * coordinates — `force` does, since the integrator moves points around rather
- * than filling slots.
- */
-declare function translated(graph: Graph, placed: ReadonlyMap<string, Vec2>, pinned: ReadonlySet<string>, tolerance?: number): LayoutResult;
-/**
- * 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.
- *
- * Shared by `layered`'s ranks and `tree`'s sibling rows, which pack a row the
- * same way and differ only in what decides the order.
- */
-declare function packAcross(nodes: readonly GraphNode[], axis: 'x' | 'y', gap: number): {
-    at: Map<string, number>;
-    span: number;
-};
-/** Order within a rank: where the nodes already sit on the cross axis, with
- *  graph order breaking a tie. Never a comparison that could reverse between
- *  two runs on the same input. */
-declare function seededOrder(nodes: readonly GraphNode[], axis: 'x' | 'y', indexOf: (id: string) => number): GraphNode[];
-/** Each node's position in `graph.nodes`, for tiebreaks. */
-declare function graphOrder(graph: Graph): (id: string) => number;
-
 /**
  * `force` — relaxation, for a graph with no direction to read it in.
  *
@@ -662,6 +755,8 @@ interface ForceOptions extends LayoutOptions {
     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. */
@@ -709,25 +804,6 @@ declare function ranksOf(graph: Graph, back: ReadonlySet<string>): Map<string, n
  *  moves nothing — except under `order: 'barycenter'`, which reorders them. */
 declare const layered: LayoutFn;
 
-/**
- * `tree` — a parent centered over the block its children occupy.
- *
- * The hierarchy layout: org charts, file trees, decision trees. Depth is the
- * rank axis, so every child sits one band past its parent, and a subtree is
- * packed as a solid block so two siblings' descendants never interleave.
- *
- * A graph that is not a tree still lays out. Roots are the nodes nothing points
- * at, in graph order; a node reachable from two parents belongs to whichever
- * the depth-first walk reaches first; and anything the walk never reaches — a
- * disconnected part, or a pure cycle — becomes a root of its own. So the answer
- * is always a forest, and which forest depends only on the node order.
- *
- * The block packing is deliberately not Reingold–Tilford: it never slides a
- * deep subtree under a shallow neighbor's overhang. That costs horizontal
- * space and buys an invariant an author can rely on — a subtree's extent is a
- * rectangle, and dragging one never lands it inside another.
- */
-
 interface Forest {
     roots: GraphNode[];
     children: Map<string, GraphNode[]>;
@@ -767,4 +843,4 @@ declare function rayHit(poly: readonly number[], center: {
  */
 declare function portsOnOutline(ports: readonly Port[], outline: Outline, bounds: Bounds): Port[];
 
-export { force as $, type RowNodeData as A, type BodySpec as B, COMPASS as C, type DiagramNodeLike as D, type RowPort as E, type ForceOptions as F, type GraphSource as G, type RowPortBox as H, type RowTextStyle as I, axesFor as J, backEdges as K, type LayoutFn as L, type MeasureRowText as M, bodyOutline as N, type Outline as O, type Port as P, bodyTrait as Q, type Row as R, type Slot as S, boxForContent as T, buildBody as U, buildGraph as V, canvasMeasure as W, contentBox as X, createDiagramNodes as Y, dataKeyReader as Z, diagramNodeOf as _, type PortsOptions as a, forceRelaxation as a0, forestOf as a1, graphOrder as a2, isPinned as a3, layered as a4, layoutBody as a5, layoutRowPorts as a6, measureBody as a7, outlinePath as a8, outlinePolyline as a9, packAcross as aa, pinnedSet as ab, portOf as ac, portsOf as ad, portsOnOutline as ae, ranksOf as af, rayHit as ag, seededOrder as ah, settle as ai, sizeToBody as aj, translated as ak, tree as al, extent as am, type DiagramNodeReader as b, type PortSpec as c, type DiagramNode as d, type LayoutOptions as e, type LayoutResult as f, type Graph as g, type BodyFloor as h, type BodyNodeSpec as i, type Bounds as j, type BuildBodyOptions as k, type BuildGraphOptions as l, DEFAULT_NODE_GAP as m, DEFAULT_PORTS as n, DEFAULT_RANK_GAP as o, DIAGRAM_TRAIT_KEY as p, type DiagramNodeEntry as q, type ForceBody as r, type ForceRelaxation as s, type GraphEdge as t, type GraphNode as u, type GraphNodeLike as v, type LayoutAxes as w, type LayoutDirection as x, type PortAnchor as y, type RowBox as z };
+export { contentBox as $, type GroupInset as A, type BodySpec as B, COMPASS as C, type DiagramNodeLike as D, type LayoutAxes as E, type ForceOptions as F, type GraphSource as G, type LayoutDirection as H, type RowBox as I, type RowNodeData as J, type RowPort as K, type LayoutFn as L, type MeasureRowText as M, type RowPortBox as N, type Outline as O, type Port as P, type RowTextStyle as Q, type Row as R, type Slot as S, axesFor as T, backEdges as U, bodyOutline as V, bodyTrait as W, boxForContent as X, buildBody as Y, buildGraph as Z, canvasMeasure as _, type PortsOptions as a, createDiagramNodes as a0, dataKeyReader as a1, diagramNodeOf as a2, expandGroupEdges as a3, force as a4, forceRelaxation as a5, forestOf as a6, graphOrder as a7, insetOf as a8, isPinned as a9, layered as aa, layoutBody as ab, layoutRowPorts as ac, measureBody as ad, outlinePath as ae, outlinePolyline as af, packAcross as ag, packClusters as ah, pinnedSet as ai, portOf as aj, portsOf as ak, portsOnOutline as al, rankGaps as am, ranksOf as an, rayHit as ao, seededOrder as ap, settle as aq, sizeToBody as ar, translated as as, tree as at, untilSettled as au, extent as av, 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 BodyFloor as j, type BodyNodeSpec as k, type Bounds as l, type BuildBodyOptions as m, type BuildGraphOptions as n, DEFAULT_GROUP_INSET as o, DEFAULT_NODE_GAP as p, DEFAULT_PORTS as q, DEFAULT_RANK_GAP as r, DIAGRAM_TRAIT_KEY as s, type DiagramNodeEntry as t, type ForceBody as u, type ForceRelaxation as v, type GraphEdge as w, type GraphGroup as x, type GraphNode as y, type GraphNodeLike as z };