@weasel-js/diagram 1.4.3 → 1.4.4

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _weasel_js_core from '@weasel-js/core';
-import { Path, Vec2, PoseProjection } from '@weasel-js/core';
+import { Path, Vec2, PoseProjection, DerivedDep, SceneRegistry, ChromeState, FillStyle, Stroke, CursorSpec, Affordance, InvocationCtx, GestureBinding, Action, Contribution, RenderLayer, SimulationNode, createSimulation, EasingFn, NodeId, Scene, NodeShapeEntry } from '@weasel-js/core';
 
 /**
  * The shapes a built body can wear, as paths in the node's bounds.
@@ -23,6 +23,32 @@ 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**:
@@ -62,6 +88,10 @@ interface DiagramNode {
     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. */
@@ -132,6 +162,20 @@ interface BodySpec {
     /** 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;
@@ -143,6 +187,15 @@ 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. */
@@ -167,6 +220,18 @@ declare function sizeToBody<TPose extends Bounds>(pose: TPose, floor: BodyFloor)
  *  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
@@ -174,11 +239,57 @@ declare function layoutBody(spec: BodySpec, bounds: Bounds, measure?: MeasureRow
  *
  * 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.
@@ -220,7 +331,12 @@ interface DiagramNodeEntry {
      *  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`. */
+/** 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
@@ -305,4 +421,985 @@ 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;
 
-export { type BodyFloor, type BodySpec, type Bounds, COMPASS, DEFAULT_PORTS, DIAGRAM_TRAIT_KEY, type DiagramNode, type DiagramNodeEntry, type DiagramNodeLike, type DiagramNodeReader, type MeasureRowText, type Outline, type Port, type PortAnchor, type PortSpec, type PortsOptions, type Row, type RowBox, type RowPort, type RowTextStyle, bodyOutline, bodyTrait, canvasMeasure, createDiagramNodes, dataKeyReader, diagramNodeOf, isPinned, layoutBody, measureBody, outlinePath, portOf, portsOf, sizeToBody };
+/**
+ * `DiagramEdge` — a connection between two participants.
+ *
+ * An edge is an ordinary leaf scene node with `dependsOn: [from, to]` and a
+ * `derivePath` that runs a **router**. Making it a scene node rather than a
+ * plugin-owned render layer is the load-bearing choice: it buys selection,
+ * hit-testing, hover, styling, z-order, SVG export, undo and copy/paste
+ * without implementing any of them. The cost is that an edge costs what a node
+ * costs — right for diagrams of tens to hundreds of edges, wrong for a
+ * 10k-edge force graph, which keeps its render layer.
+ *
+ * **Author-dragged waypoints are data on the edge and the router routes
+ * through them.** Manual control never authors the path; it authors
+ * constraints on the path. That is what keeps derived geometry and hand-tuning
+ * compatible — a moved endpoint still re-routes, through the waypoints the
+ * author put there.
+ *
+ * Arrowheads are not here. They are stroke markers, the same
+ * `markerStart` / `markerEnd` any other stroke carries.
+ */
+
+/** Where an edge attaches at one end. */
+interface EdgeEnd {
+    /** The port to leave from, when the endpoint declares one. Falls back to
+     *  the nearest port, so an edge drawn before ports were thought about still
+     *  meets the shape. */
+    port?: string;
+}
+/** The trait on an edge's `data`, under the same key participants use. */
+interface DiagramEdge {
+    from: EdgeEnd;
+    to: EdgeEnd;
+    /** Registry key for the router. Resolved by whoever builds the edge's
+     *  `derivePath`; unknown keys fall back to `straight`. */
+    router?: string;
+    /** Points in world coordinates the route must pass through, in order. The
+     *  author owns these; the router owns everything between them. */
+    waypoints?: readonly Vec2[];
+}
+/** What a router is given: the two resolved ends, and the author's waypoints
+ *  between them. */
+interface RouteRequest {
+    from: Port;
+    to: Port;
+    waypoints: readonly Vec2[];
+}
+/** A router returns the points the edge runs through, `from.point` first and
+ *  `to.point` last. Turning those into a `Path` is `edgePath`'s job, so a
+ *  router never has to know about path encodings. */
+type Router = (req: RouteRequest) => readonly Vec2[];
+/** The straight run between the two ends, through any waypoints. */
+declare const straight: Router;
+/**
+ * An axis-aligned route: leave along the departing end's normal and arrive
+ * against the receiving one's.
+ *
+ * A leg is one elbow where the two ends face different axes and two where they
+ * face the same one, turning at the midpoint of the axis they share. Arriving
+ * along the port's own facing is what makes the arrowhead point *into* the
+ * shape — a route that lands on a west-facing port from above puts its marker
+ * across the corner, which reads as aimed at nothing.
+ */
+declare const orthogonal: Router;
+/**
+ * A smooth route, sampled into points.
+ *
+ * Each leg is a cubic that leaves along the departing end's normal and arrives
+ * against the receiving one's, which is what makes a bezier edge read as
+ * plugged into its port rather than aimed at it. Sampled rather than emitted
+ * as curve commands so every router returns the same thing; `edgePath` is free
+ * to emit curves later without changing the contract.
+ */
+declare const bezier: Router;
+/** The routers this package ships. A consumer's own go in the same shape. */
+declare const ROUTERS: Readonly<Record<string, Router>>;
+/** The edge trait on a node's data, or `null`. */
+declare function diagramEdgeOf(node: {
+    data: unknown;
+}): DiagramEdge | null;
+/**
+ * The port an end resolves to: the one it named, else the port facing the
+ * other end most directly.
+ *
+ * "Facing" rather than "nearest": a port on the far side of a wide node can be
+ * closer in a straight line than the one pointing at the target, and an edge
+ * that leaves through its own node reads as a bug however short it is.
+ */
+declare function resolveEnd<TPose>(end: EdgeEnd, dep: DerivedDep<TPose>, toward: Vec2, opts: PortsOptions<TPose>, allPorts: (d: DerivedDep<TPose>) => Port[]): Port | undefined;
+interface EdgeRouteOptions<TPose> extends PortsOptions<TPose> {
+    /** Routers by key. Defaults to {@link ROUTERS}. */
+    routers?: Readonly<Record<string, Router>>;
+}
+/**
+ * A `derivePath` that routes an edge between its two dependencies.
+ *
+ * Returns `null` — nothing to draw — when the node is not an edge, when either
+ * dependency is gone, or when an endpoint offers no ports at all. A dangling
+ * edge painting a line to the origin is worse than a dangling edge painting
+ * nothing.
+ */
+declare function edgeDerivePath<TPose>(opts?: EdgeRouteOptions<TPose>): (node: {
+    data: unknown;
+}, deps: readonly (DerivedDep<TPose> | undefined)[]) => Path | null;
+/** Registry key for {@link EDGE_DERIVE_PATH}. */
+declare const DIAGRAM_EDGE = "diagram:edge";
+/** The default edge router, as one stable function reference so `toJSON` can
+ *  find its key. A consumer wanting different options registers their own
+ *  `edgeDerivePath(...)` under a key of their choosing. */
+declare const EDGE_DERIVE_PATH: (node: {
+    data: unknown;
+}, deps: readonly (DerivedDep<unknown> | undefined)[]) => Path | null;
+/** Merge this package's registry entries under a consumer's, so an edge
+ *  round-trips through `toJSON` without the consumer wiring the key. */
+declare function withDiagramRegistry<TPose>(registry?: SceneRegistry<TPose>): SceneRegistry<TPose>;
+
+/**
+ * Ports as affordances — what makes a painted port a grabbable one.
+ *
+ * A port is declared as an `AffordanceRegion`, so the kit's own region walk
+ * supplies the hit-test, the screen-pixel hit radius, the cursor and the
+ * exclusive claim that keeps a port drag out of the select tool's hands. That
+ * is the "visible chrome is always hittable" rule doing the work: the walk runs
+ * on every pointerdown before any tool sees the event, so a port answers
+ * whatever tool happens to be active.
+ *
+ * Two things about this are easy to get wrong, and both fail silently.
+ *
+ * **`targetId` is `null`.** The framework composes a target's rotation about
+ * its bounds center for any region naming one, and `portsOf` has already
+ * rotated the port. Naming the participant here would rotate it twice.
+ *
+ * **`hitKind` is not set.** On the registered-layer route the discriminator is
+ * the layer's own id — `<SceneCanvas>` stamps the hit `layer:<RenderLayer.id>`
+ * and carries `initialScratch` through as `payload`. A `hitKind` declared here
+ * would be dropped, and a binding written against it would never match.
+ */
+
+/** The layer id this package composes its port regions into. */
+declare const PORT_LAYER_ID = "diagram-ports";
+/** The affordance kind a press on a port reports — what a binding's
+ *  `target: 'affordance:...'` has to name. `<SceneCanvas>` builds it from
+ *  {@link PORT_LAYER_ID}, so the two cannot drift. */
+declare const PORT_AFFORDANCE_KIND: "layer:diagram-ports";
+/** A participant and the pose it is **painted** at. `effectivePose`, not
+ *  `node.pose` — a port that answers from the document pose while its node is
+ *  mid-drag sits somewhere the user can see the node is not. */
+interface ParticipantPose<TPose> {
+    node: DiagramNodeLike;
+    pose: TPose;
+}
+/** Where the affordance gets its participants. A thunk rather than a scene so
+ *  the geometry is testable without one, and so a consumer whose participants
+ *  come from somewhere else needs no adapter. */
+type ParticipantSource<TPose> = () => Iterable<ParticipantPose<TPose>>;
+/** What a press on a port hands the action that picks up the drag. Arrives as
+ *  `InvocationCtx.drag.affordance.payload`. */
+interface PortScratch {
+    /** `CommonAffordanceScratch.targetId` — becomes `AffordanceHit.targetIds`. */
+    targetId: string;
+    nodeId: string;
+    portId: string;
+    /** The port resolved at press time: where it was and which way it faces. */
+    port: Port;
+}
+interface PortAffordanceOptions<TPose> {
+    /** Also the chrome-caps visibility id. Default {@link PORT_LAYER_ID}. */
+    id?: string;
+    read?: DiagramNodeReader;
+    geometry?: PoseProjection<TPose>;
+    /** Which participants show their ports. Default: all of them. Gate on
+     *  selection or hover by reading `state`. */
+    shows?: (node: DiagramNodeLike, state: ChromeState) => boolean;
+    /** Screen-pixel hit radius. Default 8, the kit's `HANDLE_BASE_PX`. */
+    hitRadiusPx?: number;
+    /** Screen-pixel side of the painted square. Default 7. Omit `paint` entirely
+     *  by passing 0 — a port the consumer draws itself is still hittable. */
+    sizePx?: number;
+    fill?: FillStyle;
+    stroke?: Stroke;
+    cursor?: CursorSpec;
+    /** Default `'exclusive'` on pointer gestures: a drag from a port is a
+     *  connect, never a move of the node underneath it. */
+    strength?: 'exclusive' | 'shared';
+}
+/** Read a port press's scratch back off the hit an action was handed. */
+declare function portScratchOf(hit: {
+    payload?: unknown;
+} | null | undefined): PortScratch | null;
+/**
+ * The affordance. Compose it into a layer with `composeAffordanceLayer` and
+ * attach that with `CanvasExtensionApi.registerLayer` — the only attach route
+ * that is hit-tested. A `Contribution.overlay` is painted and never hit.
+ */
+declare function createPortAffordance<TPose>(participants: ParticipantSource<TPose>, opts?: PortAffordanceOptions<TPose>): Affordance;
+
+/**
+ * The connect gesture — dragging one port onto another to author an edge.
+ *
+ * Connect is an ordinary drag binding, not a mode and not a tool of its own:
+ * the binding is gated on a press landing on a port affordance, so a connect
+ * starts from whatever tool happens to be active. The gate lives in the
+ * binding's `target`, which is what lets a press that is *not* on a port fall
+ * through to the tool that wants it instead of being swallowed here.
+ *
+ * **Where validity is decided.** The two halves are decided in different
+ * places, and conflating them is the mistake this package is written to avoid:
+ *
+ *   - *Which presses start a connect* is routing, and belongs to the binding
+ *     spec. `connectBinding` names the port layer's affordance kind; nothing in
+ *     the action body re-checks what was pressed.
+ *   - *Which ports a live connect may land on* cannot be routing — the
+ *     dispatcher never re-reads the affordance under a moving pointer, so a
+ *     spec has no vocabulary for it. It is decided by `canConnect` filtering
+ *     the **candidate set**: an illegal port is never a candidate, so the
+ *     preview will not snap to it and a release over it commits nothing. That
+ *     is a narrower thing than an action body that inspects a hit and bails.
+ *
+ * One resolver answers both the live preview and the commit, for the reason
+ * `insertAction` does the same: a preview computed separately from the commit
+ * is a preview that can lie about what releasing will do.
+ */
+
+/** The default action id, and what {@link connectBinding} points at. */
+declare const CONNECT_ACTION_ID = "diagram.connect";
+/** Whether an edge may run from `from` to `to`. */
+type CanConnect = (from: Port, to: Port) => boolean;
+/** The edge a finished connect describes. Both ends are resolved ports, so a
+ *  consumer minting the node has nothing left to look up. */
+interface PendingEdge {
+    from: Port;
+    to: Port;
+    /** Registry key for the router the new edge should name. */
+    router: string;
+}
+/**
+ * The shipped policy: a port may not join itself, and two ports that both
+ * declare a `type` must declare the same one.
+ *
+ * A port with no type joins anything — `PortSpec.type` is uninterpreted by this
+ * package, so an untyped diagram stays fully connectable without opting out.
+ * Two ports on the *same node* may be joined: a self-edge between two different
+ * ports is meaningful in a state machine, and refusing it here would be policy
+ * masquerading as a rule.
+ */
+declare const defaultCanConnect: CanConnect;
+interface ConnectActionOptions<TPose> {
+    /** Where the droppable ports come from. The same source the port affordance
+     *  reads, so what is grabbable and what is landable cannot disagree. */
+    participants: ParticipantSource<TPose>;
+    /** Default {@link CONNECT_ACTION_ID}. */
+    id?: string;
+    read?: DiagramNodeReader;
+    geometry?: PoseProjection<TPose>;
+    /** Default {@link defaultCanConnect}. */
+    canConnect?: CanConnect;
+    /** How near the pointer must come to a port, in world units, before the
+     *  edge snaps to it. Default 16. */
+    snapRadius?: number;
+    /** Registry key the new edge names, and the router the preview draws with.
+     *  Default `'straight'`. */
+    router?: string;
+    routers?: Readonly<Record<string, Router>>;
+    /** How the in-flight edge is painted. */
+    stroke?: Stroke;
+    /**
+     * Mints and commits the edge. Called once, on release over a valid port.
+     *
+     * Defaults to {@link commitEdgeToScene} against `deps.scene`, which is what
+     * makes the gesture work with nothing wired. Override it the way a consumer
+     * overrides the kit's `insert` dep — to choose the edge node's data, its
+     * layer, or its stroke.
+     */
+    commit?: (edge: PendingEdge, ctx: InvocationCtx) => void;
+}
+/** What a connect-authored edge is drawn with, when the consumer overrides
+ *  nothing. */
+declare const DEFAULT_EDGE_STROKE: Stroke;
+/**
+ * The binding that starts a connect: a drag whose press landed on the port
+ * layer's own chrome.
+ *
+ * The string form of `target` rather than a predicate, because it ranks higher
+ * in specificity — a bare `{ kind: 'drag' }` on the select tool cannot outrank
+ * it, so no tool needs a predicate of its own to keep out of the way.
+ */
+declare function connectBinding(actionId?: string): GestureBinding;
+/** The action id that absorbs a press on a port. */
+declare const GRAB_PORT_ACTION_ID = "diagram.grabPort";
+/**
+ * Absorbs a press on a port, and does nothing else.
+ *
+ * A port claims the press **protocol**, not one gesture in it: `pointerDown`,
+ * `click` and `drag` are a single claimable `'pointer'` token, and an exclusive
+ * claim bars every binding whose target does not consult the affordance. So a
+ * bundle that binds only `drag` leaves the pointerdown with nowhere to go, and
+ * the dispatcher drops the press — the drag it would have grown into never
+ * happens. Absorbing the press is also the behavior you want on its own: a
+ * press on a port should not pick or deselect the node underneath it.
+ */
+declare function grabPortAction(id?: string): Action;
+/** The two bindings that keep a port's claim from dropping the press. */
+declare function grabPortBindings(actionId?: string): GestureBinding[];
+/**
+ * The default commit: one leaf node carrying the edge trait, added to
+ * `deps.scene`. One `add` is one history entry, so the edge undoes in one.
+ *
+ * The edge lands on the **source node's** layer rather than the bottom one: an
+ * edge between two nodes on a `wires` layer belongs on `wires`, and picking the
+ * first layer in the stack would quietly move it somewhere the author did not
+ * put its endpoints.
+ */
+declare function commitEdgeToScene(edge: PendingEdge, ctx: InvocationCtx): void;
+/**
+ * The `diagram.connect` action: an ongoing drag whose preview is an ephemeral
+ * edge and whose commit is one op batch.
+ *
+ * A factory rather than a singleton because every input it needs — which nodes
+ * are droppable, what counts as a legal pair, how an edge node is shaped — is
+ * the consumer's, and this package has no scene at module scope. Same reason
+ * `edgeDerivePath` and `diagramShape` are factories.
+ */
+declare function createConnectAction<TPose>(opts: ConnectActionOptions<TPose>): Action;
+
+/**
+ * The plugin as a `Contribution` bundle — one object a consumer hands to
+ * `<SceneCanvas ambient={…}>`.
+ *
+ * **Ambient, not a tool.** Connect is not a mode the author enters: a port is
+ * grabbable whatever tool is active, which is the same reason `@weasel-js/hud`
+ * ships `eligibility: { claimed: true }`. `claimed` is what makes the bundle
+ * live for a press the port layer's affordance claimed, and dormant otherwise.
+ *
+ * **The layer is not in here, on purpose.** `Contribution.overlay` is painted
+ * and never hit-tested — only `CanvasExtensionApi.registerLayer` gets a
+ * `hitTest` call. Shipping the port layer as an overlay would paint every port
+ * and make none of them grabbable, which is exactly the state this arc started
+ * from. {@link diagramPorts} hands back the bundle and the layer together so
+ * the two cannot be wired half-way.
+ */
+
+interface DiagramContributionOptions<TPose> extends ConnectActionOptions<TPose>, PortAffordanceOptions<TPose> {
+}
+/** The bundle: the connect action and the one binding that reaches it. */
+declare function createDiagramContribution<TPose>(opts: DiagramContributionOptions<TPose>): Contribution;
+/**
+ * Both halves of the port affordance: the layer to `registerLayer`, and the
+ * contribution to pass as `ambient`.
+ *
+ * They are returned together because attaching one without the other fails
+ * quietly — the layer alone paints ports that start no gesture, and the
+ * contribution alone binds an affordance kind nothing ever reports.
+ */
+declare function diagramPorts<TPose>(opts: DiagramContributionOptions<TPose>): {
+    layer: RenderLayer<unknown>;
+    contribution: Contribution;
+};
+
+/**
+ * `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?: PoseProjection<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;
+
+/**
+ * A label on an edge: an ordinary leaf node that derives its *pose* from the
+ * route it sits on.
+ *
+ * It reads the edge's resolved path off its dependency rather than routing
+ * again, so the label and the arrowhead can never disagree about where the
+ * edge went. Everything else about it is a normal scene node — its own size,
+ * data, styling, z-order and selection.
+ */
+
+/** Where along an edge a label sits. */
+interface DiagramLabel {
+    /** `'start'`, `'mid'` and `'end'` are 0, 0.5 and 1; a number is that
+     *  fraction of the route's length. */
+    at: 'start' | 'mid' | 'end' | number;
+    /** World units perpendicular to the route, to the **left of the direction of
+     *  travel** — above a left-to-right edge. Default 0, which centers the label
+     *  on the line. */
+    offset?: number;
+}
+/** The label trait on a node's data, or `null`. */
+declare function diagramLabelOf(node: {
+    data: unknown;
+}): DiagramLabel | null;
+interface LabelPoseOptions<TPose> {
+    geometry?: PoseProjection<TPose>;
+}
+/**
+ * A `derivePose` that stations a label along its dependency's path.
+ *
+ * Returns `null` — nothing derived, so the node keeps its authored pose —
+ * when the node carries no label trait, when the dependency is gone, or when
+ * the dependency derives no path. A label that snapped to the origin because
+ * its edge was deleted is worse than one that stayed where the author left it.
+ */
+declare function labelDerivePose<TPose>(opts?: LabelPoseOptions<TPose>): (node: {
+    pose: TPose;
+    data: unknown;
+}, deps: readonly (DerivedDep<TPose> | undefined)[]) => TPose | null;
+/** Registry key for {@link LABEL_DERIVE_POSE}. */
+declare const DIAGRAM_LABEL = "diagram:label";
+/** The default label derivation, as one stable function reference so `toJSON`
+ *  can find its key. */
+declare const LABEL_DERIVE_POSE: (node: {
+    pose: unknown;
+    data: unknown;
+}, deps: readonly (DerivedDep<unknown> | undefined)[]) => unknown;
+
+/**
+ * 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;
+/** 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;
+
+/** What a live producer is told, and what it answers with. */
+interface LiveLayoutCtx<TPose> {
+    /** Nodes another gesture is moving, and where each is drawn. */
+    pinned: ReadonlyMap<NodeId, TPose>;
+    /** Frames since this run heated, starting at 0. */
+    frame: number;
+}
+/** A frame of a live layout: where the participants are, and whether it is
+ *  finished. Positions are top-lefts, the same as a `LayoutResult`. */
+interface LiveLayoutFrame {
+    result: LayoutResult;
+    done: boolean;
+}
+type LiveLayoutProducer<TPose> = (ctx: LiveLayoutCtx<TPose>) => LiveLayoutFrame;
+interface ForceProducerOptions<TPose> extends ForceOptions {
+    geometry?: PoseProjection<TPose>;
+    /** Alpha held while something is pinned, so the graph keeps answering a drag
+     *  instead of freezing under it. Default 0.3. */
+    dragAlpha?: number;
+}
+/**
+ * A relaxation, one tick a frame, done when the simulation settles.
+ *
+ * The forces are `forceRelaxation`'s — the same ones the one-shot `force`
+ * runs, wound up once here and ticked rather than run to completion.
+ *
+ * It does **not** re-anchor the way the one-shot does. That translation exists
+ * so a single 300-tick jump does not move the diagram off where the author left
+ * it; a live run cannot jump, every frame being one step from the last, and
+ * gravity holds the graph around the centroid it was seeded from. Re-anchoring
+ * per frame would also fight a drag: the anchor is measured from where the
+ * nodes were, and a pinned node is deliberately somewhere else.
+ */
+declare function forceProducer<TPose>(graph: Graph, opts?: ForceProducerOptions<TPose>): LiveLayoutProducer<TPose>;
+interface EasedProducerOptions {
+    layout?: LayoutOptions;
+    /** Frames to arrive in. Default 24. */
+    frames?: number;
+    easing?: EasingFn;
+}
+/**
+ * A layout that knows its destination, walked into place.
+ *
+ * The target is computed once, from the graph as it stood when the run heated;
+ * each frame is that target scaled by the easing curve, measured from where the
+ * nodes started. A pinned node is dropped from the target rather than fought
+ * over.
+ */
+declare function easedProducer<TPose>(graph: Graph, algorithm: LayoutFn, opts?: EasedProducerOptions): LiveLayoutProducer<TPose>;
+interface UseLiveLayoutOptions<TPose> {
+    scene: Scene<unknown, string, TPose>;
+    /** Where the graph is read from. The same thunk the port affordance takes. */
+    source: GraphSource<TPose>;
+    /** A key in `LAYOUTS`, or a layout of the consumer's own. `'force'` relaxes
+     *  continuously; anything else eases to its answer. Default `'force'`. */
+    algorithm?: string | LayoutFn;
+    layout?: LayoutOptions;
+    force?: ForceOptions;
+    /** Frames an eased layout takes to arrive. Default 24. */
+    frames?: number;
+    easing?: EasingFn;
+    read?: DiagramNodeReader;
+    geometry?: PoseProjection<TPose>;
+    /** The undo entry's name. Default `'Layout'`. */
+    label?: string;
+    /** Fires once the run has settled or been stopped and its poses are in the
+     *  document, with how many participants moved. */
+    onSettle?: (moved: number) => void;
+    /** Whether a node or edge appearing or disappearing re-heats the run.
+     *  Default true — a diagram that ignores a new edge looks broken. */
+    reheatOnGraphChange?: boolean;
+    /** Clock injection, for tests. Defaults to `requestAnimationFrame`. */
+    requestFrame?: (cb: (t: number) => void) => number;
+    cancelFrame?: (handle: number) => void;
+}
+interface LiveLayout {
+    /** Heat and run. Idempotent while running. */
+    start(): void;
+    /** Finish now: commit where the nodes stand. */
+    stop(): void;
+    /** Abandon: the document keeps the poses it had. */
+    cancel(): void;
+    /** Rebuild the graph and run again from where the nodes are now. */
+    restart(): void;
+    isRunning(): boolean;
+}
+/**
+ * Run a layout live against a scene.
+ *
+ * The returned handle is stable. Dragging a participant while it runs needs no
+ * wiring: the consumer's move tool publishes an override, and the run treats
+ * that as a pin.
+ */
+declare function useLiveLayout<TPose>(opts: UseLiveLayoutOptions<TPose>): LiveLayout;
+/** The layouts that ease rather than relax, for a consumer choosing one. */
+declare const EASED_LAYOUTS: Readonly<Record<string, LayoutFn>>;
+
+/**
+ * `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;
+
+/**
+ * Running a layout against a scene: `LAYOUTS`, one batch of pose writes, and
+ * the action that reaches both.
+ *
+ * The split is the point. A layout is a pure function of the graph and is
+ * tested as one; `applyLayout` is the only thing that touches a scene, and it
+ * writes every move inside a single `scene.batch`, so a re-layout is one undo
+ * entry rather than one per node.
+ */
+
+/** The layouts this package ships. A consumer's own go in the same shape. */
+declare const LAYOUTS: Readonly<Record<string, LayoutFn>>;
+interface ApplyLayoutOptions<TPose> {
+    geometry?: PoseProjection<TPose>;
+    /** The undo entry's name. Default `'Layout'`. */
+    label?: string;
+}
+/**
+ * Write a layout's answer to the scene, as one undoable batch.
+ *
+ * Returns how many nodes moved, which is zero for a layout that had nothing to
+ * do — nothing is written and no history entry is pushed.
+ *
+ * Nodes are **translated**, never re-posed from the layout's numbers: a node's
+ * pose can be a path or anything else a consumer wired, and only its own
+ * descriptor knows how to move one.
+ *
+ * A participant that is a container takes its whole subtree along. `setPose`
+ * does not cascade — poses are absolute — so a built body would otherwise walk
+ * out from under its own label rows with every test green.
+ */
+declare function applyLayout<TPose>(scene: Scene<unknown, string, TPose>, result: LayoutResult, opts?: ApplyLayoutOptions<TPose>): number;
+/**
+ * The poses a layout result implies, without writing any of them: each moved
+ * node translated to its new top-left, and its subtree translated with it.
+ *
+ * Split out because a *live* layout needs the same answer every frame and must
+ * not write it — it publishes to the override channel and commits once. The
+ * translation is measured from the node's document pose, which a run in flight
+ * never changes, so a frame's answer does not depend on the frame before it.
+ */
+declare function layoutPoses<TPose>(scene: Scene<unknown, string, TPose>, result: LayoutResult, geometry?: PoseProjection<TPose>): Map<string, TPose>;
+/** The default action id. */
+declare const LAYOUT_ACTION_ID = "diagram.layout";
+interface LayoutActionOptions<TPose> {
+    /** Where the graph is read from. The same thunk the port affordance takes. */
+    source: GraphSource<TPose>;
+    /** Default {@link LAYOUT_ACTION_ID}. */
+    id?: string;
+    label?: string;
+    /** Which `<ActionBar group>` it lands in. Default `'diagram'`, alongside
+     *  connect — give a bar of its own a group of its own. */
+    group?: string;
+    /** A key in {@link LAYOUTS}, or a layout of the consumer's own. Default
+     *  `'layered'`. */
+    algorithm?: string | LayoutFn;
+    layout?: LayoutOptions;
+    read?: DiagramNodeReader;
+    geometry?: PoseProjection<TPose>;
+}
+/**
+ * `diagram.layout` — rebuild the graph, run a layout, write the result.
+ *
+ * A factory rather than a singleton for the reason every other entry point in
+ * this package is one: which nodes are in the diagram is the consumer's, and
+ * this package has no scene at module scope.
+ */
+declare function createLayoutAction<TPose>(opts: LayoutActionOptions<TPose>): Action;
+
+/**
+ * `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[];
+
+/**
+ * The port affordance, composed into a layer and pointed at a scene.
+ *
+ * Two conveniences over {@link createPortAffordance}, both of which encode a
+ * rule that is easy to get wrong rather than merely saving a line.
+ */
+
+/** The minimum a participant source needs from a scene. Narrower than `Scene`
+ *  so a consumer can pass anything that answers these two. */
+interface ParticipantScene<TPose> {
+    renderOrderNodes(): readonly {
+        id: string;
+        kind: 'leaf' | 'container';
+        data: unknown;
+        pose: TPose;
+        dependsOn?: readonly string[] | 'children';
+    }[];
+    readonly overrides: {
+        get(id: string): {
+            pose?: TPose;
+        } | undefined;
+    };
+    get(id: string): unknown;
+    childrenOf(id: string): readonly string[];
+}
+/**
+ * Every node in `scene`, at the pose it is **painted** at.
+ *
+ * `effectivePose`, not `node.pose`: an override is what a gesture is currently
+ * showing, and a port that answers from the document pose while its node is
+ * mid-drag sits somewhere the user can see the node is not. Nodes that carry no
+ * participant trait cost one reader call each and contribute no regions.
+ *
+ * One source answers both the ports and the graph — `GraphSource` is a
+ * `ParticipantSource` that also carries `dependsOn`, which is where an edge's
+ * two endpoints live.
+ */
+declare function sceneParticipants<TPose>(scene: ParticipantScene<TPose>): GraphSource<TPose>;
+/**
+ * The composed layer, ready for `CanvasExtensionApi.registerLayer` — the only
+ * attach route that is hit-tested. Handing this to `SceneCanvas`'s `layers`
+ * prop, or to a `Contribution.overlay`, paints the ports and makes none of them
+ * grabbable.
+ *
+ * The cast is `composeAffordanceLayer` typing its data slot as `ChromeState`
+ * while the layer registry takes `RenderLayer<unknown>`; both are handed the
+ * same live `CanvasHelpers` envelope at runtime.
+ */
+declare function portLayer<TPose>(participants: ParticipantSource<TPose>, opts?: PortAffordanceOptions<TPose>): RenderLayer<unknown> & {
+    hitTest: NonNullable<RenderLayer<unknown>['hitTest']>;
+};
+
+/**
+ * The painter for a node whose trait names an `outline`.
+ *
+ * Registered the way every other trait's renderer is — a `NodeShapeEntry` with
+ * a `matches` over the node's data — so a diagram body is picked, clipped and
+ * area-selected by the same walk as everything else, and a participant that
+ * already had a look of its own (a text block, an image, a path) keeps it by
+ * naming no outline at all.
+ *
+ * Rows are **not** painted here. A built body's rows are ordinary scene nodes
+ * under the container, so the kit's own text painter draws them and text
+ * editing, selection and styling work on them without a special case.
+ */
+
+interface DiagramShapeOptions<TPose> {
+    /** Distinguishes one registration from another, and is what the disposer
+     *  removes. Default `'diagram:outline'`. */
+    id?: string;
+    /** How the trait is read. Default: the node's own `data.diagram`. */
+    read?: DiagramNodeReader;
+    /** Reads the box the outline is built in. Default `RECT_POSE_DESCRIPTOR`. */
+    geometry?: PoseProjection<TPose>;
+    /** Painted when the node's data declares neither. */
+    defaultFill?: FillStyle | null;
+    defaultStroke?: Stroke | null;
+}
+/** The entry, for a consumer composing their own painter list. */
+declare function diagramShape<TPose>(opts?: DiagramShapeOptions<TPose>): NodeShapeEntry<unknown, TPose>;
+/**
+ * Register {@link diagramShape}. Returns the disposer, and takes `'high'`
+ * priority so a body outline wins over a `data.shape` or `data.path` the same
+ * node may also carry.
+ */
+declare function registerDiagramShape<TPose>(opts?: DiagramShapeOptions<TPose>): () => void;
+
+export { type ApplyLayoutOptions, type BodyFloor, type BodyNodeSpec, type BodySpec, type Bounds, type BuildBodyOptions, type BuildGraphOptions, COMPASS, CONNECT_ACTION_ID, type CanConnect, type ConnectActionOptions, DEFAULT_EDGE_STROKE, DEFAULT_NODE_GAP, DEFAULT_PORTS, DEFAULT_RANK_GAP, DIAGRAM_EDGE, DIAGRAM_LABEL, DIAGRAM_TRAIT_KEY, type DiagramContributionOptions, type DiagramEdge, type DiagramLabel, type DiagramNode, type DiagramNodeEntry, type DiagramNodeLike, type DiagramNodeReader, type DiagramShapeOptions, EASED_LAYOUTS, EDGE_DERIVE_PATH, type EasedProducerOptions, type EdgeEnd, type EdgeRouteOptions, type ForceOptions, type ForceProducerOptions, type ForceRelaxation, GRAB_PORT_ACTION_ID, type Graph, type GraphEdge, type GraphNode, type GraphNodeLike, type GraphSource, LABEL_DERIVE_POSE, LAYOUTS, LAYOUT_ACTION_ID, type LabelPoseOptions, type LayoutActionOptions, type LayoutAxes, type LayoutDirection, type LayoutFn, type LayoutOptions, type LayoutResult, type LiveLayout, type LiveLayoutCtx, type LiveLayoutFrame, type LiveLayoutProducer, type MeasureRowText, type Outline, PORT_AFFORDANCE_KIND, PORT_LAYER_ID, type ParticipantPose, type ParticipantScene, type ParticipantSource, type PendingEdge, type Port, type PortAffordanceOptions, type PortAnchor, type PortScratch, type PortSpec, type PortsOptions, ROUTERS, type RouteRequest, type Router, type Row, type RowBox, type RowNodeData, type RowPort, type RowPortBox, type RowTextStyle, type Slot, type UseLiveLayoutOptions, applyLayout, axesFor, backEdges, bezier, bodyOutline, bodyTrait, boxForContent, buildBody, buildGraph, canvasMeasure, commitEdgeToScene, connectBinding, contentBox, createConnectAction, createDiagramContribution, createDiagramNodes, createLayoutAction, createPortAffordance, dataKeyReader, defaultCanConnect, diagramEdgeOf, diagramLabelOf, diagramNodeOf, diagramPorts, diagramShape, easedProducer, edgeDerivePath, force, forceProducer, forceRelaxation, forestOf, grabPortAction, grabPortBindings, graphOrder, isPinned, labelDerivePose, layered, layoutBody, layoutPoses, layoutRowPorts, measureBody, orthogonal, outlinePath, outlinePolyline, packAcross, pinnedSet, portLayer, portOf, portScratchOf, portsOf, portsOnOutline, ranksOf, rayHit, registerDiagramShape, resolveEnd, sceneParticipants, seededOrder, settle, sizeToBody, straight, translated, tree, useLiveLayout, withDiagramRegistry };