@weasel-js/diagram 1.9.3 → 1.10.0

package/dist/index.d.ts

@@ -1,26 +1,24 @@
-import { P as Port, a as PortsOptions, D as DiagramNodeLike, b as DiagramNodeReader, c as PortAnchor, d as DiagramGroup, R as Row, O as Outline, e as PortSpec, B as BodySpec, f as DiagramNode, L as LayoutFn, g as LayoutOptions, M as MeasureRowText, G as GraphSource, F as ForceOptions, h as LayoutResult, i as Graph } from './layout.entry-KHbx5uGC.js';
-export { j as BodyFloor, k as BodyNodeSpec, l as Bounds, m as BuildBodyOptions, n as BuildGraphOptions, C as COMPASS, o as DEFAULT_GROUP_INSET, p as DEFAULT_NODE_GAP, q as DEFAULT_PORTS, r as DEFAULT_RANK_GAP, s as DIAGRAM_TRAIT_KEY, t as DiagramNodeEntry, u as ForceBody, v as ForceRelaxation, w as GraphEdge, x as GraphGroup, y as GraphNode, z as GraphNodeLike, A as GroupInset, E as LayoutAxes, H as LayoutDirection, I as RowBox, J as RowNodeData, K as RowPort, N as RowPortBox, Q as RowTextStyle, S as Slot, T as axesFor, U as backEdges, V as bodyOutline, W as bodyTrait, X as boxForContent, Y as buildBody, Z as buildGraph, _ as canvasMeasure, $ as contentBox, a0 as createDiagramNodes, a1 as dataKeyReader, a2 as diagramNodeOf, a3 as expandGroupEdges, a4 as force, a5 as forceRelaxation, a6 as forestOf, a7 as graphOrder, a8 as insetOf, a9 as isPinned, aa as layered, ab as layoutBody, ac as layoutRowPorts, ad as measureBody, ae as outlinePath, af as outlinePolyline, ag as packAcross, ah as packClusters, ai as pinnedSet, aj as portOf, ak as portsOf, al as portsOnOutline, am as rankGaps, an as ranksOf, ao as rayHit, ap as seededOrder, aq as settle, ar as sizeToBody, as as translated, at as tree } from './layout.entry-KHbx5uGC.js';
-import { Vec2, DerivedDep, Path, SceneRegistry, PoseDescriptor, ChromeState, FillStyle, Stroke, CursorSpec, Affordance, InvocationCtx, GestureBinding, Action, Contribution, RenderLayer, MarkerRef, AddNodeSpec, RectPose, Scene, EasingFn, NodeId, NodeShapeEntry, View, SelectionApi } from '@weasel-js/core';
+import { P as Port, a as PortsOptions, D as DiagramNodeLike, b as DiagramNodeReader, c as PortAnchor, d as DiagramGroup, R as Row, O as Outline, e as PortSpec, B as BodySpec, f as DiagramNode, L as LayoutFn, g as LayoutOptions, M as MeasureRowText, G as GraphSource, F as ForceOptions, h as LayoutResult, i as Graph } from './layout.entry-CIdRpG2i.js';
+export { j as BodyFloor, k as BodyNodeSpec, l as Bounds, m as BuildBodyOptions, n as BuildGraphOptions, C as COMPASS, o as DEFAULT_GROUP_INSET, p as DEFAULT_NODE_GAP, q as DEFAULT_PORTS, r as DEFAULT_RANK_GAP, s as DIAGRAM_TRAIT_KEY, t as DiagramNodeEntry, u as ForceBody, v as ForceRelaxation, w as Forest, x as GraphEdge, y as GraphGroup, z as GraphNode, A as GraphNodeLike, E as GroupInset, H as LayoutAxes, I as LayoutDirection, J as RowBox, K as RowNodeData, N as RowPort, Q as RowPortBox, S as RowTextStyle, T as Slot, U as axesFor, V as backEdges, W as bodyOutline, X as bodyTrait, Y as boxForContent, Z as buildBody, _ as buildGraph, $ as canvasMeasure, a0 as contentBox, a1 as createDiagramNodes, a2 as dataKeyReader, a3 as diagramNodeOf, a4 as expandGroupEdges, a5 as force, a6 as forceRelaxation, a7 as forestOf, a8 as graphOrder, a9 as insetOf, aa as isPinned, ab as layered, ac as layoutBody, ad as layoutRowPorts, ae as measureBody, af as outlinePath, ag as outlinePolyline, ah as packAcross, ai as packClusters, aj as pinnedSet, ak as portOf, al as portsOf, am as portsOnOutline, an as rankGaps, ao as ranksOf, ap as rayHit, aq as seededOrder, ar as settle, as as sizeToBody, at as translated, au as tree, av as untilSettled } from './layout.entry-CIdRpG2i.js';
+import { Vec2, DerivedDep, Path, SceneRegistry, PoseDescriptor, ChromeState, CommandFill, CommandStroke, CursorSpec, Affordance, InvocationCtx, Stroke, GestureBinding, Action, Contribution, RenderLayer, MarkerRef, AddNodeSpec, RectPose, Scene, NodeId, Fill, NodeShapeEntry, Paint, View, SelectionApi } from '@weasel-js/core';
 import { Vec2 as Vec2$1 } from '@weasel-js/core/math';
+import { EasingFn } from '@weasel-js/animator';
 import * as react from 'react';
 import '@weasel-js/geom';
+import '@weasel-js/simulation';
 
 /**
  * `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.
+ * `derivePath` that runs a **router**. Being a scene node rather than a
+ * plugin-owned render layer buys selection, hit-testing, hover, styling,
+ * z-order, SVG export, undo, and copy/paste. The cost is that an edge costs
+ * what a node costs — right for tens to hundreds of edges, wrong for a
+ * 10k-edge force graph.
  *
  * **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.
+ * through them**, so a moved endpoint still re-routes.
  *
  * Arrowheads are not here. They are stroke markers, the same
  * `markerStart` / `markerEnd` any other stroke carries.
@@ -52,11 +50,10 @@ interface RouteRequest {
     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$1 = (req: RouteRequest) => readonly Vec2[];
+ *  `to.point` last. */
+type Router = (req: RouteRequest) => readonly Vec2[];
 /** The straight run between the two ends, through any waypoints. */
-declare const straight: Router$1;
+declare const straight: Router;
 /**
  * An axis-aligned route: leave along the departing end's normal and arrive
  * against the receiving one's.
@@ -64,24 +61,19 @@ declare const straight: Router$1;
  * 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.
+ * shape.
  */
-declare const orthogonal: Router$1;
+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. The rule is `portCurvePoints`
- * in `@weasel-js/geom`, which states it over loose components so the 3D kernel
- * can route by the same one. 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$1;
+ * against the receiving one's. Sampled rather than emitted as curve commands so
+ * every router returns the same thing.
+ */
+declare const bezier: Router;
 /** The routers this package ships. A consumer's own go in the same shape. */
-declare const ROUTERS: Readonly<Record<string, Router$1>>;
+declare const ROUTERS: Readonly<Record<string, Router>>;
 /** The edge trait on a node's data, or `null`. */
 declare function diagramEdgeOf(node: {
     data: unknown;
@@ -91,22 +83,26 @@ declare function diagramEdgeOf(node: {
  * 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.
+ * closer in a straight line than the one pointing at the target.
  */
 declare function resolveEnd<TPose>(end: EdgeEnd, dep: DerivedDep<TPose>, toward: Vec2, opts: PortsOptions<TPose>, allPorts: (d: DerivedDep<TPose>) => Port[]): Port | undefined;
 /** Options for {@link edgeDerivePath}. */
 interface EdgeRouteOptions<TPose> extends PortsOptions<TPose> {
     /** Routers by key. Defaults to {@link ROUTERS}. */
-    routers?: Readonly<Record<string, Router$1>>;
+    routers?: Readonly<Record<string, Router>>;
+    /** How far outside its node a self-edge with no ports named turns, in
+     *  world units. Defaults to half the node's shorter side. */
+    selfLoopStandoff?: number;
 }
 /**
  * A `derivePath` that routes an edge between its two dependencies.
  *
+ * An edge from a node to itself that names no ports leaves and returns by the
+ * sides {@link selfLoop} picks, and where the author set no waypoints the
+ * router is handed that rule's point outside the node as one.
+ *
  * 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.
+ * dependency is gone, or when an endpoint offers no ports at all.
  */
 declare function edgeDerivePath<TPose>(opts?: EdgeRouteOptions<TPose>): (node: {
     data: unknown;
@@ -128,10 +124,9 @@ declare function withDiagramRegistry<TPose, TData = unknown, TLayer extends stri
  *
  * 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.
+ * exclusive claim that keeps a port drag out of the select tool's hands. 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.
  *
@@ -187,8 +182,8 @@ interface PortAffordanceOptions<TPose> {
     /** 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;
+    fill?: CommandFill;
+    stroke?: CommandStroke;
     cursor?: CursorSpec;
     /** Default `'exclusive'` on pointer gestures: a drag from a port is a
      *  connect, never a move of the node underneath it. */
@@ -210,26 +205,17 @@ declare function createPortAffordance<TPose>(participants: ParticipantSource<TPo
  *
  * 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.
+ * starts from whatever tool happens to be active, and a press that is *not* on
+ * a port falls through to the tool that wants it.
+ *
+ * *Which presses start a connect* is routing, and belongs to the binding spec.
+ * *Which ports a live connect may land on* cannot be routing — the dispatcher
+ * never re-reads the affordance under a moving pointer — so `canConnect`
+ * filters the candidate set: the preview will not snap to an illegal port and
+ * a release over it commits nothing.
+ *
+ * One resolver answers both the live preview and the commit, so the preview
+ * cannot lie about what releasing will do.
  */
 
 /** The default action id, and what {@link connectBinding} points at. */
@@ -248,11 +234,8 @@ interface PendingEdge {
  * 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.
+ * A port with no type joins anything. Two different ports on the *same node*
+ * may be joined: a self-edge is meaningful in a state machine.
  */
 declare const defaultCanConnect: CanConnect;
 /** Options for {@link createConnectAction}. Only `participants` is required. */
@@ -272,14 +255,12 @@ interface ConnectActionOptions<TPose> {
     /** Registry key the new edge names, and the router the preview draws with.
      *  Default `'straight'`. */
     router?: string;
-    routers?: Readonly<Record<string, Router$1>>;
+    routers?: Readonly<Record<string, Router>>;
     /**
      * 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.
+     * Defaults to {@link commitEdgeToScene} against `deps.scene`. Override it to
+     * choose the edge node's data, its layer, or its stroke.
      */
     commit?: (edge: PendingEdge, ctx: InvocationCtx) => void;
 }
@@ -291,8 +272,7 @@ declare const DEFAULT_EDGE_STROKE: Stroke;
  * 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.
+ * in specificity: a bare `{ kind: 'drag' }` on the select tool cannot outrank it.
  */
 declare function connectBinding(actionId?: string): GestureBinding;
 /** The action id that absorbs a press on a port. */
@@ -305,8 +285,7 @@ declare const GRAB_PORT_ACTION_ID = "diagram.grabPort";
  * 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.
+ * happens.
  */
 declare function grabPortAction(id?: string): Action;
 /** The two bindings that keep a port's claim from dropping the press. */
@@ -315,20 +294,12 @@ 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.
+ * The edge lands on the **source node's** layer rather than the bottom one.
  */
 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;
 
@@ -336,17 +307,14 @@ declare function createConnectAction<TPose>(opts: ConnectActionOptions<TPose>):
  * 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.
+ * **Ambient, not a tool.** A port is grabbable whatever tool is active:
+ * `claimed` 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.
+ * `hitTest` call — so the port layer as an overlay would paint every port and
+ * make none of them grabbable. {@link diagramPorts} hands back both.
  */
 
 /** The connect action's options and the port affordance's, in one bag. */
@@ -367,6 +335,25 @@ declare function diagramPorts<TPose>(opts: DiagramContributionOptions<TPose>): {
     contribution: Contribution;
 };
 
+/** How a self-edge with no ports named leaves its node and comes back. */
+interface SelfLoop {
+    from: Port;
+    to: Port;
+    /** A point outside the node, off the corner between the two sides. */
+    via: Vec2;
+}
+/**
+ * The route a self-edge takes when neither end names a port: out by one side
+ * and back by the next one round, past a point `standoff` clear of both.
+ *
+ * Both ends of such an edge aim at their own node's center, so every port
+ * faces it equally, both pick the same one, and the edge has no length. The
+ * sides are taken by where they face on the page, east and then north, so the
+ * loop sits at the same corner of every node however its ports are listed.
+ * `null` where the node has no two ports facing different ways.
+ */
+declare function selfLoop(ports: readonly Port[], standoff: number): SelfLoop | null;
+
 /**
  * A label on an edge: an ordinary leaf node that derives its *pose* from the
  * route it sits on.
@@ -452,7 +439,8 @@ declare function diagramAnchorOf(node: {
 interface GroupPoseOptions<TPose> {
     geometry?: PoseDescriptor<TPose>;
 }
-type DerivePose<TPose> = (node: {
+/** A `derivePose` function as the scene calls it: the node, then what it depends on, in `dependsOn` order. */
+type DiagramDerivePose<TPose> = (node: {
     pose: TPose;
     data: unknown;
 }, deps: readonly (DerivedDep<TPose> | undefined)[]) => TPose | null;
@@ -461,19 +449,20 @@ type DerivePose<TPose> = (node: {
  * grown by the trait's inset. `null` — the authored pose stands — when the node
  * carries no group trait or every member is gone.
  */
-declare function groupDerivePose<TPose>(opts?: GroupPoseOptions<TPose>): DerivePose<TPose>;
+declare function groupDerivePose<TPose>(opts?: GroupPoseOptions<TPose>): DiagramDerivePose<TPose>;
 /**
  * A `derivePose` that keeps a node at a point on its dependency's bounds.
  * `null` when the node carries no anchor trait or the dependency is gone.
  */
-declare function anchorDerivePose<TPose>(opts?: GroupPoseOptions<TPose>): DerivePose<TPose>;
+declare function anchorDerivePose<TPose>(opts?: GroupPoseOptions<TPose>): DiagramDerivePose<TPose>;
 /** Registry key for {@link GROUP_DERIVE_POSE}. */
 declare const DIAGRAM_GROUP = "diagram:group";
 /** Registry key for {@link ANCHOR_DERIVE_POSE}. */
 declare const DIAGRAM_ANCHOR = "diagram:anchor";
-/** The default derivations, as stable references so `toJSON` can find their keys. */
-declare const GROUP_DERIVE_POSE: DerivePose<unknown>;
-declare const ANCHOR_DERIVE_POSE: DerivePose<unknown>;
+/** The default group derivation, a stable reference so `toJSON` can find its key. */
+declare const GROUP_DERIVE_POSE: DiagramDerivePose<unknown>;
+/** The default anchor derivation, a stable reference for the same reason. */
+declare const ANCHOR_DERIVE_POSE: DiagramDerivePose<unknown>;
 
 /**
  * `diagramScene` — a laid-out diagram from plain `{ nodes, edges }`.
@@ -484,6 +473,7 @@ declare const ANCHOR_DERIVE_POSE: DerivePose<unknown>;
  * the same answer in node and in a browser.
  */
 
+/** One node of a {@link DiagramData}: its rows of text, and optionally its outline, ports, size, and starting place. */
 interface DataNode {
     id: string;
     /** Shorthand for one `label` row per line. Ignored when `rows` is given. */
@@ -509,6 +499,7 @@ interface DataNode {
     /** Default `DiagramSceneOptions.verticalAlign`. */
     verticalAlign?: BodySpec['verticalAlign'];
 }
+/** One edge of a {@link DiagramData}, between two nodes or groups by id. */
 interface DataEdge {
     /** A node's id, or a group's: an edge naming a group meets its box. */
     from: string;
@@ -521,7 +512,7 @@ interface DataEdge {
     /** Where along the edge the label sits. Default `DiagramSceneOptions.labelPlacement`. */
     labelPlacement?: DiagramLabel;
     /** Default `DiagramSceneOptions.router`. */
-    router?: Router;
+    router?: DiagramRouter;
     /** World points the route passes through. Layout does not move them. */
     waypoints?: readonly Vec2$1[];
 }
@@ -529,8 +520,9 @@ interface DataEdge {
 interface DataGroup {
     /** Shares one namespace with node ids. */
     id: string;
-    /** Node ids. A node a later group also names stays in this one, and an id
-     *  that is not a node is ignored. */
+    /** Node ids, and the ids of groups nested in this one. A node or group a
+     *  later group also names stays in this one; an id that is neither is
+     *  ignored, and so is one that would put a group inside itself. */
     members: readonly string[];
     /** Drawn inside the box, above its members. */
     label?: string;
@@ -538,14 +530,16 @@ interface DataGroup {
      *  `DiagramSceneOptions.groupPadding`. */
     padding?: number;
 }
+/** A diagram as plain data, the input to `diagramScene`. */
 interface DiagramData {
     nodes: readonly DataNode[];
     edges: readonly DataEdge[];
-    /** Flat: a group is never a member of another. `layered` and `tree` keep
-     *  each group's members together; `force` and `'none'` ignore groups but
-     *  still draw them. */
+    /** A group may be a member of another. `layered`, `tree`, and `force` keep
+     *  each group's members together; `'none'` ignores groups but still draws
+     *  them. */
     groups?: readonly DataGroup[];
 }
+/** The colors and outline a node is drawn with. */
 interface NodeStyle {
     fill: string;
     stroke: string;
@@ -553,6 +547,7 @@ interface NodeStyle {
     strokeWidth?: number;
     dash?: number[];
 }
+/** The stroke, markers, and label color an edge is drawn with. */
 interface EdgeStyle {
     stroke: string;
     width?: number;
@@ -564,12 +559,15 @@ interface EdgeStyle {
     /** Default `stroke`. */
     label?: string;
 }
-type Router = 'straight' | 'bezier' | 'orthogonal';
-type TextStyle = {
+/** How an edge is drawn between its ends. */
+type DiagramRouter = 'straight' | 'bezier' | 'orthogonal';
+/** The face a diagram node's text is set in. */
+type DiagramTextStyle = {
     fontFamily: string;
     fontSize: number;
     fontWeight?: number;
 };
+/** The `data` of a scene node `diagramScene` makes: its diagram role, and what it paints. */
 interface DiagramSceneData {
     diagram?: DiagramNode | DiagramEdge | {
         label: DiagramLabel;
@@ -577,13 +575,17 @@ interface DiagramSceneData {
         anchor: DiagramAnchor;
     };
     fill?: {
-        color: string;
+        paint: {
+            color: string;
+        };
     };
     stroke?: Stroke;
     text?: string;
-    style?: TextStyle;
+    style?: DiagramTextStyle;
 }
+/** A scene node spec, as `diagramScene` returns them. */
 type DiagramSpec = AddNodeSpec<DiagramSceneData, 'main', RectPose>;
+/** How `diagramScene` lays out, routes, and styles a {@link DiagramData}. */
 interface DiagramSceneOptions {
     /** A layout by name, or any `LayoutFn`. Default `'layered'`. `'none'`
      *  leaves every node at its `at`. */
@@ -591,7 +593,7 @@ interface DiagramSceneOptions {
     /** Merged over `{ order: 'barycenter' }`. */
     layoutOptions?: LayoutOptions;
     /** Default `'bezier'`. */
-    router?: Router;
+    router?: DiagramRouter;
     /** The text style rows fall back on. Default 12px sans-serif. */
     font?: {
         fontFamily: string;
@@ -619,6 +621,7 @@ interface DiagramSceneOptions {
     groupStyle?: (group: DataGroup) => NodeStyle;
     edgeStyle?: (edge: DataEdge) => EdgeStyle;
 }
+/** The scene node id `diagramScene` gives an edge, built from its ends, ports, and label. */
 declare const edgeIdOf: (e: DataEdge) => string;
 /** Every spec carries an id — a node's own, `<id>/<k>` for its text,
  *  `<edge id>/label`, a group's own and `<group id>/label` — so a later call's
@@ -658,21 +661,13 @@ interface ForceProducerOptions<TPose> extends ForceOptions {
 /**
  * A relaxation, one tick a frame, done when the graph stops moving.
  *
- * Motion ends long before alpha cools — a few dozen ticks against three
- * hundred — so a run that waited for alpha would sit visibly still for
- * seconds while still reporting itself running. It finishes on whichever
- * comes first: `restTicks` ticks in a row with no node moving `restDistance`,
- * or the cooling schedule running out. Nothing rests while a node is held.
+ * Motion ends long before alpha cools, so it finishes on whichever comes
+ * first: `restTicks` ticks in a row with no node moving `restDistance`, or the
+ * cooling schedule running out. Nothing rests while a node is held.
  *
- * 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.
+ * It does **not** re-anchor the way the one-shot `force` does. Re-anchoring
+ * per frame would 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>;
 /** Options for {@link easedProducer}. */
@@ -744,12 +739,8 @@ declare const EASED_LAYOUTS: Readonly<Record<string, 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 action that reaches both. A layout is a pure function of the graph;
+ * `applyLayout` is the only thing that touches a scene.
  */
 
 /** The layouts this package ships. A consumer's own go in the same shape. */
@@ -771,18 +762,16 @@ interface ApplyLayoutOptions<TPose> {
  * 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.
+ * does not cascade — poses are absolute.
  */
 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.
+ * The translation is measured from the node's document pose, which a live 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?: PoseDescriptor<TPose>): Map<string, TPose>;
 /** The default action id. */
@@ -806,18 +795,11 @@ interface LayoutActionOptions<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;
 
 /**
  * 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`
@@ -843,12 +825,9 @@ interface ParticipantScene<TPose> {
  *
  * `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.
+ * mid-drag sits somewhere the user can see the node is not.
  *
- * 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.
+ * One source answers both the ports and the graph.
  */
 declare function sceneParticipants<TPose>(scene: ParticipantScene<TPose>): GraphSource<TPose>;
 /**
@@ -856,27 +835,18 @@ declare function sceneParticipants<TPose>(scene: ParticipantScene<TPose>): Graph
  * 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
+ * The painter for a node whose trait names an `outline`. 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.
+ * under the container, so the kit's own text painter draws them.
  */
 
 /** Options for {@link diagramShape} and {@link registerDiagramShape}. */
@@ -889,7 +859,7 @@ interface DiagramShapeOptions<TPose> {
     /** Reads the box the outline is built in. Default `RECT_POSE_DESCRIPTOR`. */
     geometry?: PoseDescriptor<TPose>;
     /** Painted when the node's data declares neither. */
-    defaultFill?: FillStyle | null;
+    defaultFill?: Fill | null;
     defaultStroke?: Stroke | null;
 }
 /** The entry, for a consumer composing their own painter list. */
@@ -907,6 +877,7 @@ interface NodeMove {
     x: number;
     y: number;
 }
+/** Props for `DiagramView`. */
 interface DiagramViewProps {
     /** Every spec needs an id, which `diagramScene` gives them. A new array is
      *  reconciled into the scene the view already holds, so the view, the
@@ -955,7 +926,7 @@ interface DiagramViewProps {
      *  Default 16. */
     fitPadding?: number;
     /** What the canvas paints behind the diagram. Unset, it is transparent. */
-    background?: FillStyle;
+    background?: Paint;
     /** The view, controlled. Set it and the initial fit is skipped; pair it
      *  with `onViewChange` or panning does nothing. */
     view?: View;
@@ -984,4 +955,4 @@ declare const DiagramView: react.ForwardRefExoticComponent<DiagramViewProps & re
  *  `<SceneCanvas onClick>`. */
 declare function useMirroredSelection(selection: Pick<SelectionApi, 'get' | 'set'>, selected: string | null | undefined, onSelect: ((id: string | null) => void) | undefined): () => void;
 
-export { ANCHOR_DERIVE_POSE, type ApplyLayoutOptions, BodySpec, CONNECT_ACTION_ID, type CanConnect, type ConnectActionOptions, DEFAULT_EDGE_STROKE, DIAGRAM_ANCHOR, DIAGRAM_EDGE, DIAGRAM_GROUP, DIAGRAM_LABEL, type DataEdge, type DataGroup, type DataNode, type DiagramAnchor, type DiagramContributionOptions, type DiagramData, type DiagramEdge, DiagramGroup, type DiagramLabel, DiagramNode, DiagramNodeLike, DiagramNodeReader, type DiagramSceneData, type DiagramSceneOptions, type DiagramShapeOptions, type DiagramSpec, DiagramView, type DiagramViewApi, type DiagramViewProps, EASED_LAYOUTS, EDGE_DERIVE_PATH, type EasedProducerOptions, type EdgeEnd, type EdgeRouteOptions, type EdgeStyle, ForceOptions, type ForceProducerOptions, GRAB_PORT_ACTION_ID, GROUP_DERIVE_POSE, Graph, GraphSource, type GroupPoseOptions, LABEL_DERIVE_POSE, LAYOUTS, LAYOUT_ACTION_ID, type LabelPoseOptions, type LayoutActionOptions, LayoutFn, LayoutOptions, LayoutResult, type LiveLayout, type LiveLayoutCtx, type LiveLayoutFrame, type LiveLayoutProducer, MeasureRowText, type NodeMove, type NodeStyle, Outline, PORT_AFFORDANCE_KIND, PORT_LAYER_ID, type ParticipantPose, type ParticipantScene, type ParticipantSource, type PendingEdge, Port, type PortAffordanceOptions, PortAnchor, type PortScratch, PortSpec, PortsOptions, ROUTERS, type RouteRequest, type Router$1 as Router, Row, type UseLiveLayoutOptions, anchorDerivePose, applyLayout, bezier, commitEdgeToScene, connectBinding, createConnectAction, createDiagramContribution, createLayoutAction, createPortAffordance, defaultCanConnect, diagramAnchorOf, diagramEdgeOf, diagramGroupOf, diagramLabelOf, diagramPorts, diagramScene, diagramShape, easedProducer, edgeDerivePath, edgeIdOf, forceProducer, grabPortAction, grabPortBindings, groupDerivePose, labelDerivePose, layoutPoses, orthogonal, portLayer, portScratchOf, registerDiagramShape, resolveEnd, sceneParticipants, straight, useLiveLayout, useMirroredSelection, withDiagramRegistry };
+export { ANCHOR_DERIVE_POSE, type ApplyLayoutOptions, BodySpec, CONNECT_ACTION_ID, type CanConnect, type ConnectActionOptions, DEFAULT_EDGE_STROKE, DIAGRAM_ANCHOR, DIAGRAM_EDGE, DIAGRAM_GROUP, DIAGRAM_LABEL, type DataEdge, type DataGroup, type DataNode, type DiagramAnchor, type DiagramContributionOptions, type DiagramData, type DiagramDerivePose, type DiagramEdge, DiagramGroup, type DiagramLabel, DiagramNode, DiagramNodeLike, DiagramNodeReader, type DiagramRouter, type DiagramSceneData, type DiagramSceneOptions, type DiagramShapeOptions, type DiagramSpec, type DiagramTextStyle, DiagramView, type DiagramViewApi, type DiagramViewProps, EASED_LAYOUTS, EDGE_DERIVE_PATH, type EasedProducerOptions, type EdgeEnd, type EdgeRouteOptions, type EdgeStyle, ForceOptions, type ForceProducerOptions, GRAB_PORT_ACTION_ID, GROUP_DERIVE_POSE, Graph, GraphSource, type GroupPoseOptions, LABEL_DERIVE_POSE, LAYOUTS, LAYOUT_ACTION_ID, type LabelPoseOptions, type LayoutActionOptions, LayoutFn, LayoutOptions, LayoutResult, type LiveLayout, type LiveLayoutCtx, type LiveLayoutFrame, type LiveLayoutProducer, MeasureRowText, type NodeMove, type NodeStyle, Outline, PORT_AFFORDANCE_KIND, PORT_LAYER_ID, type ParticipantPose, type ParticipantScene, type ParticipantSource, type PendingEdge, Port, type PortAffordanceOptions, PortAnchor, type PortScratch, PortSpec, PortsOptions, ROUTERS, type RouteRequest, type Router, Row, type SelfLoop, type UseLiveLayoutOptions, anchorDerivePose, applyLayout, bezier, commitEdgeToScene, connectBinding, createConnectAction, createDiagramContribution, createLayoutAction, createPortAffordance, defaultCanConnect, diagramAnchorOf, diagramEdgeOf, diagramGroupOf, diagramLabelOf, diagramPorts, diagramScene, diagramShape, easedProducer, edgeDerivePath, edgeIdOf, forceProducer, grabPortAction, grabPortBindings, groupDerivePose, labelDerivePose, layoutPoses, orthogonal, portLayer, portScratchOf, registerDiagramShape, resolveEnd, sceneParticipants, selfLoop, straight, useLiveLayout, useMirroredSelection, withDiagramRegistry };