@weasel-js/diagram 1.4.4 → 1.5.1

package/dist/layout.entry-BO7d72yq.d.ts

@@ -0,0 +1,749 @@
+import * as _weasel_js_core from '@weasel-js/core';
+import { Path, Vec2, PoseDescriptor, SimulationNode, createSimulation } from '@weasel-js/core/math';
+
+/**
+ * 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
+ * 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.
+ */
+
+/** An axis-aligned box, in the shape `PoseDescriptor.getBounds` returns. */
+interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A named flowchart shape, or a path a consumer built themselves. */
+type Outline = 'rect' | 'diamond' | 'stadium' | 'parallelogram' | 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;
+/**
+ * The largest axis-aligned box a shape's content can occupy without leaving
+ * the shape. Rows lay out in here, not in the bounds — a diamond's corners and
+ * a parallelogram's lean are outside its own box, and a label placed against
+ * the bounding box lands there and gets clipped away by the silhouette.
+ *
+ * Conservative rather than exact: the inscribed rect of a rhombus is exact,
+ * and a stadium reports the flat span between its rounded ends, which gives up
+ * a little height near them.
+ */
+declare function contentBox(outline: Outline, bounds: Bounds): Bounds;
+/**
+ * The box whose {@link contentBox} is at least `content` — the inverse, for
+ * sizing a node to what its rows measured.
+ *
+ * The stadium case is the only inexact one: its inset depends on the height it
+ * is solving for, so it assumes the wide orientation and adds one height's
+ * worth of end caps.
+ */
+declare function boxForContent(outline: Outline, content: {
+    width: number;
+    height: number;
+}): {
+    width: number;
+    height: number;
+};
+
+/**
+ * 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 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;
+}
+/**
+ * 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;
+}
+/** 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;
+}
+
+/** One line of body content. */
+type Row = 
+/** Text. `label` is the node's name; `field` is a named value. */
+{
+    kind: 'label';
+    text: string;
+    style?: RowTextStyle;
+} | {
+    kind: 'field';
+    label: string;
+    value: string;
+    style?: RowTextStyle;
+}
+/** A row that carries ports on its own left and right edges — the
+ *  visual-programming shape, where an operator's inputs line up with the
+ *  rows they feed. */
+ | {
+    kind: 'ports';
+    left?: readonly RowPort[];
+    right?: readonly RowPort[];
+    height?: number;
+}
+/** Reserved space a consumer paints into. */
+ | {
+    kind: 'slot';
+    height: number;
+    id?: string;
+};
+/** A port declared on a row rather than on the node's perimeter. */
+interface RowPort {
+    id: string;
+    /** Label shown beside it, and what the row measures against. */
+    label?: string;
+    type?: string;
+}
+/** The subset of a text style the body measures against. Deliberately small:
+ *  a full `ResolvedTextStyle` belongs to whatever paints the row. */
+interface RowTextStyle {
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+}
+/** Measures one run of text. Returns its advance width and its line height. */
+type MeasureRowText = (text: string, style: RowTextStyle) => {
+    width: number;
+    height: number;
+};
+interface BodySpec {
+    outline: Outline;
+    rows: readonly Row[];
+    /** Space between the outline and its rows. Default 8. */
+    padding?: number;
+    /** Space between adjacent rows. Default 4. */
+    gap?: number;
+}
+/** What {@link buildBody} emits: the `AddNodeSpec` fields it fills in. Named
+ *  structurally rather than imported so a consumer whose scene is typed
+ *  differently can still spread one. */
+interface BodyNodeSpec<TData, TLayer extends string, TPose> {
+    kind: 'container' | 'leaf';
+    layer: TLayer;
+    pose: TPose;
+    data: TData;
+    id?: string;
+    parent?: string;
+    /** Set `false` on every leaf the builder emits: the innermost hit wins, so a
+     *  row that answers a press is a body that cannot be dragged. */
+    pickable?: boolean;
+}
+/** The floor a body's content puts under its node's size. */
+interface BodyFloor {
+    minWidth: number;
+    minHeight: number;
+}
+/** Where one row landed, in the same frame as the bounds it was laid out in.
+ *  A `ports` row's own ports anchor to this box. */
+interface RowBox extends Bounds {
+    row: Row;
+    index: number;
+}
+/** Where one row port's label sits, in the same frame as the row box it was
+ *  laid out in. Its vertical center is also where the port itself attaches, so
+ *  a label and the port it names cannot drift apart. */
+interface RowPortBox extends Bounds {
+    port: RowPort;
+    side: 'left' | 'right';
+    /** Position within its own side, top to bottom. */
+    index: number;
+}
+/** Adapts the kit's `measureText` for a caller holding a 2D context. Pass the
+ *  same context the renderer measures with, or the floor will not match what
+ *  is painted. */
+declare function canvasMeasure(ctx: {
+    measureText(text: string): {
+        width: number;
+    };
+    font: string;
+}): MeasureRowText;
+/**
+ * The smallest box `spec`'s rows fit in. A node's pose is maxed against this,
+ * never set to it.
+ */
+declare function measureBody(spec: BodySpec, measure?: MeasureRowText): BodyFloor;
+/**
+ * The authored size, grown to fit the body. Never shrinks: a row removed
+ * leaves the node the size the author last saw it at, which is the only
+ * behavior that survives a resize the author did on purpose.
+ */
+declare function sizeToBody<TPose extends Bounds>(pose: TPose, floor: BodyFloor): TPose;
+/** Where each row sits inside `bounds`, top to bottom. Rows keep their
+ *  measured heights; the leftover goes unclaimed at the bottom rather than
+ *  being distributed, so a row does not move when a sibling grows. */
+declare function layoutBody(spec: BodySpec, bounds: Bounds, measure?: MeasureRowText): RowBox[];
+/**
+ * Where each of a `ports` row's ports goes inside `box`, on the same terms
+ * `layoutBody` gives one box per row.
+ *
+ * Both sides are cut into the same number of slots — the longer side's count —
+ * so the nth input faces the nth output whichever side has more. A label box
+ * is as wide as its own text and pinned to its own edge of the row; an
+ * unlabeled port gets a zero-width box there, which is still where it attaches.
+ */
+declare function layoutRowPorts(row: Extract<Row, {
+    kind: 'ports';
+}>, box: Bounds, measure?: MeasureRowText): RowPortBox[];
+/**
+ * The `DiagramNode` trait a built body implies: perimeter ports for the
+ * outline, plus one port per `ports`-row entry, anchored to that row's own
+ * left or right edge.
+ *
+ * Anchors are normalized against `bounds`, so they survive the node being
+ * resized — which is the whole reason `PortAnchor` is normalized.
+ *
+ * **A row port on a side takes that side's compass default with it.** Both sit
+ * on the same edge, and a row near the vertical middle puts one exactly on top
+ * of `w` or `e` — where the later region wins the hit and the other is
+ * grabbable nowhere. A body that declares where its inputs attach has said what
+ * that side is for.
+ */
+declare function bodyTrait(spec: BodySpec, bounds: Bounds, measure?: MeasureRowText): DiagramNode;
+/** The outline path for a built body at `bounds` — what paints it, and what a
+ *  perimeter-hugging port will eventually be placed on. */
+declare function bodyOutline(spec: BodySpec, bounds: Bounds): _weasel_js_core.Path;
+/** What a built body's rows are handed to, one call per row.
+ *
+ *  `text` is the row's content already formatted — a `label`'s own text, or a
+ *  `field`'s `"label: value"` — so the common case needs no discrimination.
+ *  Return `null` for a row the consumer paints itself; `ports` and `slot` rows
+ *  arrive with `text` empty and are the usual ones to decline. */
+type RowNodeData<TData> = (text: string, box: RowBox) => TData | null;
+interface BuildBodyOptions<TData, TLayer extends string, TPose extends Bounds> {
+    layer: TLayer;
+    /** The container's id. Edges name it, so pass one for anything an edge or a
+     *  layout `pin` will refer to. */
+    id?: string;
+    measure?: MeasureRowText;
+    /** The container's own data, given the trait the builder computed and the
+     *  pose it was computed against. */
+    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 — a body whose ports are
+     *  named only for the width they claim needs nothing here. */
+    portLabel?: (text: string, box: RowPortBox) => TData | null;
+}
+/**
+ * The scene nodes a built body is: one container carrying the trait, and one
+ * leaf per row that wants drawing.
+ *
+ * Rows are ordinary scene nodes rather than something this package paints, so
+ * the kit's own text painter draws them and text editing, styling and
+ * selection work on them unchanged. The walk that places them is
+ * `layoutBody` — the same one `bodyTrait` anchors its row ports against, which
+ * is why a label and its ports cannot drift apart.
+ *
+ * The pose is `sizeToBody(at, measureBody(spec))`: the body measures a floor
+ * and the authored size is grown to clear it, never shrunk.
+ */
+declare function buildBody<TData, TLayer extends string, TPose extends Bounds>(spec: BodySpec, at: TPose, opts: BuildBodyOptions<TData, TLayer, TPose>): {
+    pose: TPose;
+    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.
+ *
+ * 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.
+ */
+
+/** 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[];
+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;
+}
+/**
+ * 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;
+
+/**
+ * `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[];
+}
+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';
+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;
+    /** 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;
+declare const DEFAULT_NODE_GAP = 48;
+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;
+}
+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.
+ *
+ * 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, which is what
+ * a random jiggle is for elsewhere.
+ *
+ * The integrator is the kit's own `createSimulation`, the same one
+ * `useSimulation` runs a frame at a time. Only the forces are local, and they
+ * are the naive O(n²) kind — right for the tens-to-hundreds of nodes an
+ * edge-per-scene-node diagram is already sized for, wrong for a 10k-node graph,
+ * which wants d3-force's Barnes–Hut through `useSimulation` and its own render
+ * layer.
+ *
+ * **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.
+ */
+
+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;
+}
+interface Body 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.
+ *
+ * Shared by the one-shot `force` below and the live relaxation in `live.ts`,
+ * which ticks it a frame at a time. Two copies of a force list drift, and the
+ * only thing that would say so is the arrangement they produce.
+ */
+interface ForceRelaxation {
+    bodies: Body[];
+    byId: Map<string, Body>;
+    /** Ids the caller must not move: declared pins, held as `fx`/`fy`. */
+    pinned: ReadonlySet<string>;
+    sim: ReturnType<typeof createSimulation<Body>>;
+    /** Where a body's node's top-left sits, given the body's center. */
+    placed(): Map<string, {
+        x: number;
+        y: number;
+    }>;
+}
+declare function forceRelaxation(graph: Graph, opts?: ForceOptions): ForceRelaxation;
+declare const force: (graph: Graph, opts?: ForceOptions) => LayoutResult;
+
+/**
+ * `layered` — ranks running one way, nodes running across.
+ *
+ * The flowchart / pipeline layout: an edge points from one rank to the next, so
+ * reading down the page is reading the order things happen in. Ranks come from
+ * longest-path layering, which puts every node as far along as its deepest
+ * predecessor allows.
+ *
+ * Cycles do not disqualify a graph. A depth-first walk in graph order names the
+ * edges that close a cycle, layering ignores those, and they draw as edges
+ * running back up the page — which is what a reader expects a loop to look
+ * like. Which edges get named depends only on the node order, so it is the same
+ * every run.
+ *
+ * This is not crossing-minimization: within a rank, nodes keep the order they
+ * already have on the cross axis. An author who dragged two branches into an
+ * order gets that order back, and re-running the layout is free.
+ */
+
+/** 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>;
+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[]>;
+    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;
+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 { forceRelaxation as $, type RowPort as A, type BodyFloor as B, COMPASS as C, type DiagramNodeLike as D, type RowPortBox as E, type ForceOptions as F, type GraphSource as G, type RowTextStyle as H, axesFor as I, backEdges as J, bodyOutline as K, type LayoutFn as L, type MeasureRowText as M, bodyTrait as N, type Outline as O, type Port as P, boxForContent as Q, type Row as R, type Slot as S, buildBody as T, buildGraph as U, canvasMeasure as V, contentBox as W, createDiagramNodes as X, dataKeyReader as Y, diagramNodeOf as Z, force as _, type PortsOptions as a, forestOf as a0, graphOrder as a1, isPinned as a2, layered as a3, layoutBody as a4, layoutRowPorts as a5, measureBody as a6, outlinePath as a7, outlinePolyline as a8, packAcross as a9, pinnedSet as aa, portOf as ab, portsOf as ac, portsOnOutline as ad, ranksOf as ae, rayHit as af, seededOrder as ag, settle as ah, sizeToBody as ai, translated as aj, tree as ak, extent as al, type DiagramNodeReader as b, type LayoutOptions as c, type LayoutResult as d, type Graph as e, type BodyNodeSpec as f, type BodySpec as g, type Bounds as h, type BuildBodyOptions as i, type BuildGraphOptions as j, DEFAULT_NODE_GAP as k, DEFAULT_PORTS as l, DEFAULT_RANK_GAP as m, DIAGRAM_TRAIT_KEY as n, type DiagramNode as o, type DiagramNodeEntry as p, type ForceRelaxation as q, type GraphEdge as r, type GraphNode as s, type GraphNodeLike as t, type LayoutAxes as u, type LayoutDirection as v, type PortAnchor as w, type PortSpec as x, type RowBox as y, type RowNodeData as z };