@x12i/diagrams 1.0.0 → 1.1.0

package/dist/messages-ZCyCfyO0.d.ts

@@ -0,0 +1,857 @@
+/**
+ * The kit's own diagram document (spec section 10). It is versioned JSON, so
+ * the node canvas engine can change without breaking saved diagrams.
+ *
+ * Coordinates: `position` is the top-left corner of the node. For a child of a
+ * group or subflow (`parentId` set) it is relative to the parent's top-left
+ * corner, the same convention React Flow uses. Everything here is plain data:
+ * no React, no DOM.
+ */
+declare const DIAGRAM_VERSION = 1;
+/** The node library. Every node reads kit tokens. */
+type NodeKind = "start" | "end" | "task" | "decision" | "group" | "note" | "image" | "entity" | "code" | "chart" | "agent" | "subflow";
+/** Status colors match the rest of the kit: a status means the same in a badge, a chart and a node. */
+type NodeStatus = "neutral" | "success" | "warning" | "danger" | "info";
+type EdgeKind = "straight" | "bezier" | "step" | "smooth-step";
+/**
+ * What the diagram models. It decides which structural rules `validateDiagram`
+ * and `checkConnection` enforce:
+ *
+ * - `graph` (default) and `flowchart`: any shape, loops are allowed.
+ * - `dag`: no cycles (workflows, data lineage).
+ * - `tree`: no cycles and at most one incoming edge per node (org charts).
+ */
+type DiagramKind = "graph" | "flowchart" | "dag" | "tree";
+interface Position {
+    x: number;
+    y: number;
+}
+interface DiagramNode {
+    id: string;
+    kind: NodeKind;
+    /** The text read aloud in the outline. Pass a translated string. */
+    label: string;
+    position: Position;
+    status?: NodeStatus;
+    /** Set on children of a group or subflow. */
+    parentId?: string;
+    width?: number;
+    height?: number;
+    /** Typed handles, for connection validation. */
+    ports?: Array<{
+        id: string;
+        direction: "in" | "out";
+        type?: string;
+    }>;
+    /** Free-form payload for custom node bodies, such as a ChartSpec for a chart node. */
+    data?: Record<string, unknown>;
+    /** A longer description, read after the label by screen readers. */
+    description?: string;
+    /** A collapsed group or subflow hides its children. */
+    collapsed?: boolean;
+    /** A locked node cannot be moved, resized, renamed or deleted in the editor. */
+    locked?: boolean;
+}
+interface DiagramEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourcePort?: string;
+    targetPort?: string;
+    kind?: EdgeKind;
+    label?: string;
+    /** Draw arrowheads at both ends. */
+    bidirectional?: boolean;
+    animated?: boolean;
+    /** Draw the line dashed. Dashes carry meaning without color (for example "optional"). */
+    dashed?: boolean;
+    /** Tints the line with a status color, the same way a node status does. */
+    status?: NodeStatus;
+}
+interface DiagramDocument {
+    version: typeof DIAGRAM_VERSION;
+    /** Every diagram has a title that states what it shows. */
+    title: string;
+    nodes: DiagramNode[];
+    edges: DiagramEdge[];
+    /** Defaults to `graph`. */
+    kind?: DiagramKind;
+    /** A longer text alternative, read after the title. */
+    description?: string;
+}
+/** Every node kind, in palette order. */
+declare const NODE_KINDS: readonly NodeKind[];
+declare const NODE_STATUSES: readonly NodeStatus[];
+declare const EDGE_KINDS: readonly EdgeKind[];
+declare const DIAGRAM_KINDS: readonly DiagramKind[];
+/** Kinds that can contain other nodes. */
+declare function isContainerKind(kind: NodeKind): boolean;
+/** Identity helper for authoring-time type checking. */
+declare function defineDiagram(document: DiagramDocument): DiagramDocument;
+/** An empty document with the current version. */
+declare function createDiagram(title?: string, extra?: Partial<Omit<DiagramDocument, "version" | "title">>): DiagramDocument;
+
+/** Lookup tables over a document. Build once, query many times. */
+interface DiagramIndex {
+    nodesById: Map<string, DiagramNode>;
+    edgesById: Map<string, DiagramEdge>;
+    /** Edges whose endpoints both exist, grouped by source node id. */
+    outgoing: Map<string, DiagramEdge[]>;
+    incoming: Map<string, DiagramEdge[]>;
+    /** Child node ids by parent id, in document order. */
+    children: Map<string, string[]>;
+}
+/** Builds the lookup tables. Dangling edges are left out of `outgoing` and `incoming`. */
+declare function buildIndex(doc: DiagramDocument): DiagramIndex;
+/** The chain of ancestor ids, nearest first. Stops if the parent chain loops. */
+declare function getAncestors(index: DiagramIndex, id: string): string[];
+/** All descendants of a node, depth first, in document order. */
+declare function getDescendants(index: DiagramIndex, id: string): string[];
+/**
+ * Finds a directed cycle and returns its node ids in order (the first id is not
+ * repeated at the end), or `undefined` when the graph is acyclic. Self-loops
+ * count as cycles. Iterative, so a very long chain cannot overflow the stack.
+ */
+declare function findCycle(doc: DiagramDocument, index?: DiagramIndex): string[] | undefined;
+/** True when `to` can be reached from `from` by following edges forward. A node reaches itself. */
+declare function hasPath(index: DiagramIndex, from: string, to: string): boolean;
+/** Nodes with no incoming edge, in document order. */
+declare function getRoots(doc: DiagramDocument, index?: DiagramIndex): string[];
+/** Ids of nodes directly connected to `id` (either direction), without duplicates. */
+declare function getNeighbors(index: DiagramIndex, id: string): string[];
+/** Topological order of the nodes (Kahn). Nodes on a cycle come last, in document order. */
+declare function topologicalOrder(doc: DiagramDocument, index?: DiagramIndex): string[];
+
+type IssueSeverity = "error" | "warning";
+type IssueCode = "unsupported-version" | "missing-title" | "empty-id" | "duplicate-node-id" | "duplicate-edge-id" | "invalid-node-kind" | "invalid-edge-kind" | "invalid-status" | "invalid-position" | "invalid-size" | "empty-label" | "dangling-source" | "dangling-target" | "unknown-source-port" | "unknown-target-port" | "source-port-direction" | "target-port-direction" | "port-type-mismatch" | "duplicate-port-id" | "duplicate-edge" | "self-loop" | "parent-missing" | "parent-self" | "parent-cycle" | "parent-not-container" | "cycle" | "multiple-parents";
+/**
+ * One finding. `message` is English for developers and logs; show your own
+ * translated text for end users, keyed by `code`.
+ */
+interface DiagramIssue {
+    code: IssueCode;
+    severity: IssueSeverity;
+    message: string;
+    /** Where in the document the problem is, for example `["edges", 2, "target"]`. */
+    path: Array<string | number>;
+    nodeId?: string;
+    edgeId?: string;
+}
+interface ValidationResult {
+    /** True when there are no errors. Warnings do not make a diagram invalid. */
+    valid: boolean;
+    issues: DiagramIssue[];
+    errors: DiagramIssue[];
+    warnings: DiagramIssue[];
+}
+interface ValidateOptions {
+    /** Overrides `doc.kind`. */
+    kind?: DiagramKind;
+    /** Report nodes with an empty label as warnings. Defaults to true. */
+    warnOnEmptyLabels?: boolean;
+}
+/**
+ * Checks a document and returns every problem it finds instead of stopping at
+ * the first: unique ids, edges that point at nothing, ports that do not exist
+ * or do not match, group (parent) structure, and, for `dag` and `tree`
+ * diagrams, cycles and multiple parents.
+ */
+declare function validateDiagram(doc: DiagramDocument, options?: ValidateOptions): ValidationResult;
+
+/** A proposed edge, before it has an id. */
+interface DiagramConnection {
+    source: string;
+    target: string;
+    sourcePort?: string;
+    targetPort?: string;
+}
+/** Why a connection was refused. The canvas maps each code to a translated message. */
+type ConnectionRejection = "unknown-source" | "unknown-target" | "self-loop" | "duplicate" | "locked" | "container-descendant" | "source-port-missing" | "target-port-missing" | "source-port-not-output" | "target-port-not-input" | "port-type-mismatch" | "cycle" | "multiple-parents" | "custom";
+type ConnectionCheck = {
+    ok: true;
+} | {
+    ok: false;
+    code: ConnectionRejection;
+    message: string;
+};
+interface ConnectionRules {
+    /** Allow an edge from a node to itself. Defaults to true, except for `dag` and `tree` diagrams. */
+    allowSelfLoops?: boolean;
+    /** Allow a second edge with the same endpoints and ports. Defaults to false. */
+    allowDuplicates?: boolean;
+    /** Refuse edges that would close a cycle. Defaults to true for `dag` and `tree` diagrams. */
+    acyclic?: boolean;
+    /** Refuse a second incoming edge. Defaults to true for `tree` diagrams. */
+    singleParent?: boolean;
+}
+/** The rules a diagram kind implies. Explicit rules override them. */
+declare function resolveConnectionRules(kind: DiagramKind | undefined, rules?: ConnectionRules): Required<ConnectionRules>;
+/** Port types are compatible when either is untyped or `any`, or when they are equal. */
+declare function portTypesCompatible(a: string | undefined, b: string | undefined): boolean;
+/**
+ * Checks a proposed edge against the diagram's rules: both nodes exist, ports
+ * exist, point the right way and have compatible types, and the structural
+ * rules of the diagram kind hold. The result carries a machine code; show a
+ * translated message for it.
+ */
+declare function checkConnection(doc: DiagramDocument, connection: DiagramConnection, rules?: ConnectionRules, index?: DiagramIndex): ConnectionCheck;
+
+/** A point in diagram space. Same shape as `Position`. */
+type Point = Position;
+interface Size {
+    width: number;
+    height: number;
+}
+interface Rect extends Point, Size {
+}
+type Side = "top" | "right" | "bottom" | "left";
+/** Flow direction of a layout: top to bottom, bottom to top, left to right, right to left. */
+type LayoutDirection = "TB" | "BT" | "LR" | "RL";
+/** The diagram grid in diagram units. Layout and snapping round to it (spec: everything sits on the 8 px grid). */
+declare const GRID_SIZE = 8;
+/** Default node sizes by kind, in diagram units. All are multiples of the grid. */
+declare const DEFAULT_NODE_SIZE: Readonly<Record<NodeKind, Size>>;
+/** Height of a collapsed group: just its title bar. */
+declare const COLLAPSED_HEIGHT = 48;
+/** Approximate text metrics, used to size nodes and labels without a DOM. */
+declare const TEXT_METRICS: {
+    readonly charWidth: 7;
+    readonly lineHeight: 20;
+    readonly nodePaddingX: 32;
+    readonly nodePaddingY: 24;
+};
+declare function estimateTextWidth(text: string, charWidth?: number): number;
+/** Wraps text into lines that fit `maxWidth`, breaking at spaces and, for a very long word, anywhere. */
+declare function wrapText(text: string, maxWidth: number, charWidth?: number): string[];
+/**
+ * The size a node is drawn at: its own `width` and `height` when set, otherwise
+ * a default for its kind that grows to fit a long label (or the rows of an
+ * entity). The estimate is deterministic, so layout, the canvas and the static
+ * SVG all agree.
+ */
+declare function getNodeSize(node: DiagramNode): Size;
+declare function getNodeBounds(node: DiagramNode): Rect;
+declare function rectCenter(rect: Rect): Point;
+declare function unionRects(rects: Iterable<Rect>): Rect;
+declare function rectsIntersect(a: Rect, b: Rect): boolean;
+declare function rectContainsPoint(rect: Rect, point: Point): boolean;
+/** Absolute (diagram space) top-left position of every node, resolving parent offsets. Loop-safe. */
+declare function getAbsolutePositions(doc: DiagramDocument, index?: DiagramIndex): Map<string, Point>;
+declare function getAbsolutePosition(doc: DiagramDocument, id: string): Point | undefined;
+/** Absolute bounds of every node. */
+declare function getAbsoluteBounds(doc: DiagramDocument, index?: DiagramIndex): Map<string, Rect>;
+/** The rectangle that contains every node (absolute). An empty diagram gives a zero rectangle. */
+declare function getDocumentBounds(doc: DiagramDocument): Rect;
+declare function snapValue(value: number, grid?: number): number;
+declare function snapPoint(point: Point, grid?: number): Point;
+/** Which sides new edges leave from and arrive at for a flow direction. */
+declare function directionSides(direction: LayoutDirection): {
+    source: Side;
+    target: Side;
+};
+/** In a right-to-left page, horizontal flows mirror: LR becomes RL. Vertical flows keep their direction. */
+declare function mirrorDirection(direction: LayoutDirection, rtl: boolean): LayoutDirection;
+declare function isHorizontal(direction: LayoutDirection): boolean;
+interface PortPlacement {
+    /** Undefined for the default (unnamed) handle of a node without declared ports. */
+    id: string | undefined;
+    direction: "in" | "out";
+    side: Side;
+    type?: string;
+    /** Position along the side, 0 to 1, measured from the start of that side. */
+    offset: number;
+}
+/**
+ * Where a node's connection points sit. A node without declared ports gets one
+ * unnamed input and one unnamed output (a `start` node only an output, an `end`
+ * node only an input). Declared ports are spread evenly along their side. In a
+ * right-to-left page the spread along a horizontal edge mirrors.
+ */
+declare function getPortPlacements(node: DiagramNode, direction?: LayoutDirection, rtl?: boolean): PortPlacement[];
+/** The point on a rectangle's side, `offset` (0 to 1) along it. */
+declare function sideAnchor(rect: Rect, side: Side, offset?: number): Point;
+declare function sideVector(side: Side): Point;
+interface EdgePathInput {
+    source: Point;
+    target: Point;
+    sourceSide: Side;
+    targetSide: Side;
+    kind?: EdgeKind;
+    /** How far an edge leaves a node before it turns. Defaults to 24. */
+    offset?: number;
+    /** Corner radius of `smooth-step` edges. Defaults to 8. */
+    radius?: number;
+    /** Bezier curvature, as React Flow defines it. Defaults to 0.25. */
+    curvature?: number;
+    /** Draw a loop that returns to the same node, `loopSize` units wide. */
+    loopSize?: number;
+}
+interface EdgePath {
+    /** SVG path data. */
+    path: string;
+    /** Where to put the label: the visual middle of the edge. */
+    label: Point;
+    /** The polyline (or control polygon for curves). Useful for bounds and hit tests. */
+    points: Point[];
+}
+/**
+ * The SVG path between two anchors. `step` and `smooth-step` run orthogonally
+ * and leave each node perpendicular to the side they attach to; `bezier` uses
+ * React Flow's control-point rule; `straight` is a line. The canvas and the
+ * static SVG both call this, so they draw the same edge.
+ */
+declare function computeEdgePath(input: EdgePathInput): EdgePath;
+interface GeometryOptions {
+    direction?: LayoutDirection;
+    rtl?: boolean;
+    /** Default edge kind for edges that do not set one. Defaults to `smooth-step`. */
+    edgeKind?: EdgeKind;
+}
+/** Precomputed lookups for drawing many edges of one document. */
+interface GeometryContext {
+    doc: DiagramDocument;
+    index: DiagramIndex;
+    direction: LayoutDirection;
+    rtl: boolean;
+    edgeKind: EdgeKind;
+    /** Absolute bounds per node id. */
+    bounds: Map<string, Rect>;
+}
+declare function createGeometryContext(doc: DiagramDocument, options?: GeometryOptions): GeometryContext;
+interface EdgeGeometry extends EdgePath {
+    source: Point;
+    target: Point;
+    sourceSide: Side;
+    targetSide: Side;
+    selfLoop: boolean;
+}
+/** Where an edge runs and how it is drawn. Returns undefined when an endpoint is missing. */
+declare function getEdgeGeometry(context: GeometryContext, edge: DiagramEdge): EdgeGeometry | undefined;
+interface ReadingOrderOptions {
+    direction?: LayoutDirection;
+    rtl?: boolean;
+    /** Nodes whose centers are this close along the flow axis share a row. Defaults to 24. */
+    tolerance?: number;
+}
+/**
+ * Node ids in reading order: top to bottom then start to end of the line for a
+ * vertical flow, or column by column for a horizontal one. A group comes
+ * before its children. This is the order the canvas puts nodes in the DOM, so
+ * Tab follows it.
+ */
+declare function getReadingOrder(doc: DiagramDocument, options?: ReadingOrderOptions): string[];
+type FocusDirection = "up" | "down" | "left" | "right";
+/**
+ * The node to move to when an arrow key is pressed on `fromId`. Connected nodes
+ * in that direction win; if there is none, the nearest node of any kind in that
+ * direction is used. Returns undefined when nothing lies that way.
+ */
+declare function findDirectionalNeighbor(doc: DiagramDocument, fromId: string, direction: FocusDirection, options?: {
+    candidates?: Iterable<string>;
+}): string | undefined;
+
+type MutationErrorCode = "duplicate-id" | "node-not-found" | "edge-not-found" | "parent-not-found" | "parent-not-container" | "invalid-connection" | "cannot-group";
+/** Thrown when a mutation is asked to do something that would corrupt the document. */
+declare class DiagramMutationError extends Error {
+    readonly code: MutationErrorCode;
+    /** For `invalid-connection`: the `ConnectionRejection` code. */
+    readonly detail?: string;
+    constructor(code: MutationErrorCode, message: string, detail?: string);
+}
+type NewNode = Omit<DiagramNode, "id" | "label" | "position"> & {
+    id?: string;
+    label?: string;
+    position?: Position;
+};
+/** The id `addNode` would give a new node of this kind. */
+declare function nextNodeId(doc: DiagramDocument, prefix?: string): string;
+/** The id `connect` would give a new edge. */
+declare function nextEdgeId(doc: DiagramDocument, prefix?: string): string;
+/** Builds a complete node with a fresh id, without adding it. */
+declare function createNode(doc: DiagramDocument, input: NewNode): DiagramNode;
+/** Adds a node. Throws `duplicate-id` if the id exists, or a parent error if `parentId` is not a container. */
+declare function addNode(doc: DiagramDocument, input: NewNode): DiagramDocument;
+type NodePatch = Partial<Omit<DiagramNode, "id">>;
+/** Changes a node. The patch can be an object or a function of the current node. Throws `node-not-found`. */
+declare function updateNode(doc: DiagramDocument, id: string, patch: NodePatch | ((node: DiagramNode) => NodePatch)): DiagramDocument;
+interface RemoveOptions {
+    /**
+     * What happens to the children of a removed group. `release` (default) keeps
+     * them and moves them out to the group's parent without changing where they
+     * appear; `remove` deletes them too.
+     */
+    children?: "release" | "remove";
+}
+/** Removes nodes and every edge that touches them. Unknown ids are ignored. */
+declare function removeNodes(doc: DiagramDocument, ids: Iterable<string>, options?: RemoveOptions): DiagramDocument;
+/** Removes a node and its edges. Throws `node-not-found` when the id is unknown. */
+declare function removeNode(doc: DiagramDocument, id: string, options?: RemoveOptions): DiagramDocument;
+/** Moves nodes to the given positions (relative to their parents). Unknown ids are ignored. */
+declare function moveNodes(doc: DiagramDocument, positions: Record<string, Position>): DiagramDocument;
+/** Moves nodes by an offset. A group's children move with it, so they are not shifted twice. */
+declare function translateNodes(doc: DiagramDocument, ids: Iterable<string>, dx: number, dy: number): DiagramDocument;
+/** Sets a node's size. */
+declare function resizeNode(doc: DiagramDocument, id: string, size: Size, position?: Position): DiagramDocument;
+/**
+ * Moves a node into another group (or out to the top level with `undefined`)
+ * without changing where it appears.
+ */
+declare function setNodeParent(doc: DiagramDocument, id: string, parentId: string | undefined): DiagramDocument;
+type NewEdge = DiagramConnection & Partial<Omit<DiagramEdge, "source" | "target" | "sourcePort" | "targetPort">>;
+interface ConnectOptions extends ConnectionRules {
+    /** Skip `checkConnection`. Defaults to true (validate). */
+    validate?: boolean;
+}
+/**
+ * Adds an edge. By default it runs `checkConnection` and throws
+ * `invalid-connection` (with the rejection code in `detail`) when the rules
+ * refuse it. Pass `{ validate: false }` to add it unconditionally.
+ */
+declare function connect(doc: DiagramDocument, input: NewEdge, options?: ConnectOptions): DiagramDocument;
+/**
+ * Removes an edge by id (throws `edge-not-found` if it does not exist), or all
+ * edges between two nodes when given `{ source, target }` (a no-op if none).
+ */
+declare function disconnect(doc: DiagramDocument, target: string | DiagramConnection): DiagramDocument;
+declare function removeEdges(doc: DiagramDocument, ids: Iterable<string>): DiagramDocument;
+type EdgePatch = Partial<Omit<DiagramEdge, "id">>;
+declare function updateEdge(doc: DiagramDocument, id: string, patch: EdgePatch): DiagramDocument;
+interface GroupOptions {
+    id?: string;
+    label?: string;
+    /** `group` (default) or `subflow`. */
+    kind?: Extract<NodeKind, "group" | "subflow">;
+    /** Space between the group border and its content. Defaults to 32. */
+    padding?: number;
+    /** Space reserved for the group title. Defaults to 40. */
+    header?: number;
+}
+/**
+ * Wraps nodes in a new group sized to fit them. The nodes keep their place on
+ * the page. They must share one parent; a node whose ancestor is also selected
+ * is left alone because it moves with that ancestor. Throws `cannot-group`.
+ */
+declare function groupNodes(doc: DiagramDocument, ids: Iterable<string>, options?: GroupOptions): DiagramDocument;
+/** Dissolves a group: its children move out to the group's parent and the group is removed. */
+declare function ungroupNode(doc: DiagramDocument, groupId: string): DiagramDocument;
+interface DiagramFragment {
+    nodes: DiagramNode[];
+    edges: DiagramEdge[];
+}
+/**
+ * Copies nodes (with all their descendants) and the edges between them. Nodes
+ * whose parent is not part of the copy are stored with absolute positions and
+ * no parent, so the fragment can be pasted anywhere.
+ */
+declare function extractFragment(doc: DiagramDocument, ids: Iterable<string>): DiagramFragment;
+interface PasteOptions {
+    /** Shift applied to the pasted top-level nodes. Defaults to 24, 24. */
+    offset?: Position;
+    /** Paste inside this group. Pasted positions are then relative to it. */
+    parentId?: string;
+}
+interface PasteResult {
+    document: DiagramDocument;
+    /** Ids of every new node, including children. */
+    nodeIds: string[];
+    /** Ids of the new top-level nodes of the paste. */
+    rootIds: string[];
+    edgeIds: string[];
+    /** Old id to new id. */
+    idMap: Record<string, string>;
+}
+/** Adds a copy of a fragment with fresh ids. */
+declare function pasteFragment(doc: DiagramDocument, fragment: DiagramFragment, options?: PasteOptions): PasteResult;
+/** Copies nodes (and the edges between them) next to the originals. Copies stay in the same group. */
+declare function duplicateNodes(doc: DiagramDocument, ids: Iterable<string>, options?: PasteOptions): PasteResult;
+type Alignment = "left" | "center" | "right" | "top" | "middle" | "bottom";
+/** Lines nodes up on one edge or center. Needs at least two nodes. */
+declare function alignNodes(doc: DiagramDocument, ids: Iterable<string>, alignment: Alignment): DiagramDocument;
+/** Spaces three or more nodes so the gaps between them are equal. The outer two stay put. */
+declare function distributeNodes(doc: DiagramDocument, ids: Iterable<string>, axis: "horizontal" | "vertical"): DiagramDocument;
+
+type LayoutAlgorithm = "layered" | "tree" | "radial" | "grid";
+interface LayoutSpacing {
+    /** Gap between neighbors in the same rank, in diagram units. Defaults to 48. */
+    node?: number;
+    /** Gap between ranks (levels). Defaults to 80. */
+    rank?: number;
+    /** Padding between a group's border and its content. Defaults to 32. */
+    group?: number;
+}
+interface LayoutOptions {
+    /** `layered` (dagre, default), `tree` (d3-hierarchy), `radial` or `grid`. */
+    algorithm?: LayoutAlgorithm;
+    /** Flow direction. Defaults to `TB`. Radial layouts ignore it. */
+    direction?: LayoutDirection;
+    /** Mirror the layout for a right-to-left page: LR becomes RL, and vertical layouts flip left to right. */
+    rtl?: boolean;
+    /** Spacing in diagram units. A number sets the node gap. */
+    spacing?: LayoutSpacing | number;
+    /** `tree` and `radial`: the root node id. Defaults to the nodes with no incoming edge. */
+    root?: string;
+    /** `tree` and `radial`: `tidy` (default) or `cluster`, which puts every leaf on the same level. */
+    treeVariant?: "tidy" | "cluster";
+    /** `grid`: items per line. Defaults to the square root of the node count, rounded up. */
+    columns?: number;
+    /** `layered`: dagre's ranking algorithm. Defaults to `network-simplex`, or to the much faster `tight-tree` on levels with more than ~400 nodes and edges. */
+    ranker?: "network-simplex" | "tight-tree" | "longest-path";
+    /** Round positions and group sizes to this grid. Defaults to 8; 0 turns rounding off. */
+    grid?: number;
+    /** Space reserved for a group's title above its content. Defaults to 40. */
+    groupHeader?: number;
+    /** Where the top-left corner of the whole layout goes. Defaults to 0, 0. */
+    origin?: Position;
+}
+interface LayoutResult {
+    /** New `position` for every node (relative to its parent, as in the document). */
+    positions: Record<string, Position>;
+    /** New size for every group that was fitted around its children. */
+    sizes: Record<string, Size>;
+    /** Absolute bounds of the laid out diagram. */
+    bounds: Rect;
+    algorithm: LayoutAlgorithm;
+    /** The direction actually used, after right-to-left mirroring. */
+    direction: LayoutDirection;
+}
+/**
+ * Computes positions for every node. Deterministic: the same document and
+ * options always give the same result. Groups are laid out from the inside out:
+ * a group's children are arranged first, the group is sized to fit them, and
+ * then the group is placed as one box among its siblings. Edges that cross a
+ * group boundary are lifted to the level where both ends are visible.
+ *
+ * It does not change the document; pass the result to `applyLayout`.
+ */
+declare function layoutDiagram(doc: DiagramDocument, options?: LayoutOptions): LayoutResult;
+/** Writes a layout result into a document: new positions, and fitted sizes for groups. */
+declare function applyLayout(doc: DiagramDocument, result: LayoutResult): DiagramDocument;
+/** Lays out and applies in one step. */
+declare function layoutedDiagram(doc: DiagramDocument, options?: LayoutOptions): DiagramDocument;
+
+/**
+ * Undo and redo as a pure reducer, so it works in a React `useReducer`, in a
+ * store, or on a server. States are never mutated.
+ */
+interface HistoryState<T> {
+    past: T[];
+    present: T;
+    future: T[];
+    /** The `coalesceKey` of the last `set`, so a run of similar changes becomes one undo step. */
+    lastKey?: string;
+}
+interface HistoryOptions {
+    /** The most undo steps to keep. Defaults to 100. */
+    limit?: number;
+}
+type HistoryAction<T> = {
+    type: "set";
+    value: T;
+    /**
+     * Changes with the same key in a row share one undo step, for example
+     * every keystroke while renaming a node.
+     */
+    coalesceKey?: string;
+} | {
+    type: "undo";
+} | {
+    type: "redo";
+}
+/** Replace the present and forget the past and future. */
+ | {
+    type: "reset";
+    value: T;
+}
+/** Forget the past and future, keeping the present. */
+ | {
+    type: "clear";
+};
+declare function createHistory<T>(initial: T): HistoryState<T>;
+declare function canUndo<T>(state: HistoryState<T>): boolean;
+declare function canRedo<T>(state: HistoryState<T>): boolean;
+declare function historyReducer<T>(state: HistoryState<T>, action: HistoryAction<T>, options?: HistoryOptions): HistoryState<T>;
+
+interface StatusPalette {
+    background: string;
+    foreground: string;
+    border: string;
+}
+/**
+ * The colors a static diagram uses. Every default is a `var(--kit-...)`
+ * reference, so the SVG follows the theme of the page it is placed in. To save
+ * a diagram as a stand-alone file, pass resolved colors (the React entry's
+ * `readDiagramPalette` reads them from the DOM).
+ */
+interface DiagramPalette {
+    surface: string;
+    canvas: string;
+    text: string;
+    textMuted: string;
+    textInverse: string;
+    /** Node outlines. */
+    border: string;
+    /** Soft separators, such as the table header rule. */
+    borderSubtle: string;
+    /** Edges. Keeps 3:1 against the surface. */
+    edge: string;
+    accent: string;
+    accentSubtle: string;
+    onAccent: string;
+    inverse: string;
+    status: Record<NodeStatus, StatusPalette>;
+    fontSans: string;
+    fontMono: string;
+}
+type DiagramPaletteOverride = Partial<Omit<DiagramPalette, "status">> & {
+    status?: Partial<Record<NodeStatus, Partial<StatusPalette>>>;
+};
+declare const defaultPalette: DiagramPalette;
+declare function resolvePalette(override?: DiagramPaletteOverride): DiagramPalette;
+type SvgAttributes = Record<string, string | number | undefined>;
+/**
+ * A tiny immutable tree of SVG elements. The string serializer and the React
+ * `StaticDiagram` both render from it, so they draw the same picture and
+ * nothing is ever injected as raw markup.
+ */
+interface SvgElement {
+    tag: string;
+    attrs?: SvgAttributes;
+    /** CSS declarations, written as the `style` attribute. */
+    style?: Record<string, string>;
+    /** Child elements and text. Text is escaped when serialized. */
+    children?: Array<SvgElement | string>;
+}
+declare function escapeXml(text: string): string;
+/** Serializes an element tree to an SVG string. Text and attribute values are escaped. */
+declare function serializeSvg(element: SvgElement): string;
+interface SvgOptions {
+    /** Flow direction, which decides where edges attach. Defaults to `TB`. */
+    direction?: LayoutDirection;
+    /** Right-to-left page: mirrors port order and aligns text to the right. */
+    rtl?: boolean;
+    /** Edge style for edges that do not set one. Defaults to `smooth-step`. */
+    edgeKind?: EdgeKind;
+    /** Space around the diagram, in diagram units. Defaults to 24. */
+    padding?: number;
+    palette?: DiagramPaletteOverride;
+    /** Prefix for generated element ids. Defaults to `kit-diagram`. Use a unique one when several diagrams share a page. */
+    idPrefix?: string;
+    /** Accessible title. Defaults to the document title. */
+    title?: string;
+    /** Accessible description. Defaults to the text outline of the diagram. */
+    description?: string;
+    /** Joins labels in the default description ("A to B"). Pass a translated word. */
+    connector?: string;
+    /** Language of the text, as a BCP 47 tag. */
+    lang?: string;
+    /** Width of the `<svg>` element. Omit to let it size from its container. */
+    width?: number | string;
+    height?: number | string;
+    /** Node ids to draw with the accent color: "one accent marks the path or node the diagram is about". */
+    highlight?: Iterable<string>;
+    /** Draw edge labels. Defaults to true. */
+    showEdgeLabels?: boolean;
+    /** Add the XML declaration, for saving as a `.svg` file. */
+    standalone?: boolean;
+}
+/**
+ * True for an image address a diagram may load: http(s) and raster `data:`
+ * URLs. Everything else (`javascript:`, `file:`, SVG data URLs, relative paths)
+ * is refused, because a diagram document is data that may come from anyone.
+ */
+declare function isSafeImageUrl(value: unknown): value is string;
+/** Builds the SVG element tree for a document. */
+declare function diagramToSvgTree(doc: DiagramDocument, options?: SvgOptions): SvgElement;
+/**
+ * Renders a diagram to an SVG string with no DOM and no React, so it works on a
+ * server, in a report or for print. Colors are `var(--kit-...)` references by
+ * default; pass `palette` for resolved colors when saving a stand-alone file.
+ */
+declare function diagramToSvg(doc: DiagramDocument, options?: SvgOptions): string;
+
+type ImportErrorCode = "invalid-json" | "not-an-object" | "missing-version" | "unsupported-version" | "missing-migration" | "invalid-structure";
+/** Thrown by `importDiagram` when the input cannot become a document. */
+declare class DiagramImportError extends Error {
+    readonly code: ImportErrorCode;
+    readonly issues: DiagramIssue[];
+    constructor(code: ImportErrorCode, message: string, issues?: DiagramIssue[]);
+}
+/** Upgrades the raw document by one version. It receives and returns plain JSON. */
+type DiagramMigration = (raw: Record<string, unknown>) => Record<string, unknown>;
+interface ImportOptions {
+    /**
+     * Migrations by the version they upgrade FROM: `{ 0: (raw) => ... }` turns a
+     * version 0 document into version 1. They run in order until the current
+     * version. The `version` field is advanced for you.
+     */
+    migrations?: Record<number, DiagramMigration>;
+    /**
+     * A single hook that runs after `migrations`, once per import, with the
+     * version the data started at. Use it for changes not tied to one version.
+     */
+    migrate?: (raw: Record<string, unknown>, fromVersion: number) => Record<string, unknown>;
+    /** Version to assume when the input has none. By default a missing version is an error. */
+    assumeVersion?: number;
+    /** Throw `invalid-structure` when validation finds errors. Defaults to false: errors are returned in `issues`. */
+    strict?: boolean;
+}
+interface ImportResult {
+    document: DiagramDocument;
+    /** Everything `validateDiagram` found. Warnings and, unless `strict`, errors. */
+    issues: DiagramIssue[];
+    /** The version the input had before migration, when it was migrated. */
+    migratedFrom?: number;
+}
+interface ExportJsonOptions {
+    /** Indentation. Defaults to 2; pass 0 for compact output. */
+    space?: number;
+}
+/** Serializes a document to JSON. The `version` field comes first. */
+declare function exportDiagramJson(doc: DiagramDocument, options?: ExportJsonOptions): string;
+/** Exports a stand-alone SVG file's text. Pass a resolved `palette`; `var(--kit-...)` colors only work inside a themed page. */
+declare function exportDiagramSvg(doc: DiagramDocument, options?: SvgOptions): string;
+/**
+ * Turns JSON text or a parsed object into a validated document. Old versions
+ * are migrated, unknown newer versions are refused, and the result is checked
+ * with `validateDiagram`. Round-trips with `exportDiagramJson`.
+ */
+declare function importDiagram(input: string | unknown, options?: ImportOptions): ImportResult;
+
+/** Values available to a message template, for example `{ label: "Review" }`. */
+type MessageValues = Record<string, string | number>;
+/**
+ * A translated string. Either a template with `{name}` placeholders, or a
+ * function for languages that need plurals or word order a template cannot
+ * express (use `Intl.PluralRules` inside it).
+ */
+type Message = string | ((values: MessageValues) => string);
+/** Fills `{name}` placeholders. An unknown placeholder is left as written. */
+declare function formatMessage(message: Message, values?: MessageValues): string;
+interface DiagramMessages {
+    canvas: {
+        /** Accessible name of the canvas. `{title}` */
+        label: Message;
+        /** Keyboard instructions for an editable canvas, read when it gets focus. */
+        instructions: Message;
+        /** Keyboard instructions for a read-only canvas. */
+        instructionsReadOnly: Message;
+        /** Shown instead of the nodes when the diagram is empty. */
+        empty: Message;
+    };
+    kinds: Record<NodeKind, Message>;
+    statuses: Record<NodeStatus, Message>;
+    node: {
+        /** `{label}`, `{kind}`, `{incoming}`, `{outgoing}` */
+        label: Message;
+        /** Appended when a node has a status other than neutral. `{status}` */
+        status: Message;
+        roleDescription: Message;
+        /** Accessible name of the inline editor. `{label}` */
+        editLabel: Message;
+        /** `{label}` */
+        collapse: Message;
+        /** `{label}` */
+        expand: Message;
+        /** Accessible name of a connection point. */
+        port: Message;
+        /** Shown on a collapsed group. `{count}` */
+        childCount: Message;
+    };
+    edge: {
+        /** `{source}`, `{target}` */
+        label: Message;
+        /** `{label}`, `{source}`, `{target}` */
+        labelWithText: Message;
+        roleDescription: Message;
+        /** Accessible name of the edge label editor. `{source}`, `{target}` */
+        editLabel: Message;
+    };
+    toolbar: {
+        label: Message;
+        addNode: Message;
+        palette: Message;
+        undo: Message;
+        redo: Message;
+        delete: Message;
+        duplicate: Message;
+        autoLayout: Message;
+        group: Message;
+        ungroup: Message;
+        zoomIn: Message;
+        zoomOut: Message;
+        fitView: Message;
+        showMiniMap: Message;
+        hideMiniMap: Message;
+        showGrid: Message;
+        hideGrid: Message;
+        controlsLabel: Message;
+    };
+    minimap: Message;
+    /** Spoken through a polite live region. */
+    announce: {
+        nodeAdded: Message;
+        nodeRemoved: Message;
+        itemsRemoved: Message;
+        connected: Message;
+        disconnected: Message;
+        moved: Message;
+        resized: Message;
+        renamed: Message;
+        selected: Message;
+        selectedMany: Message;
+        selectionCleared: Message;
+        undone: Message;
+        redone: Message;
+        nothingToUndo: Message;
+        nothingToRedo: Message;
+        layoutApplied: Message;
+        grouped: Message;
+        ungrouped: Message;
+        duplicated: Message;
+        copied: Message;
+        pasted: Message;
+        connectStarted: Message;
+        connectCancelled: Message;
+        locked: Message;
+    };
+    /** Why a connection was refused, by rejection code. */
+    connection: Record<ConnectionRejection, Message>;
+    outline: {
+        title: Message;
+        nodes: Message;
+        paths: Message;
+        /** Joins labels along a path: "A to B". */
+        connector: Message;
+        connectsTo: Message;
+        receivesFrom: Message;
+        noConnections: Message;
+        /** `{label}` */
+        goToNode: Message;
+        empty: Message;
+        /** `{status}` */
+        status: Message;
+        /** Shown before a group's children. `{label}` */
+        contains: Message;
+        /** Accessible name of the button that removes a connection. `{source}`, `{target}` */
+        disconnect: Message;
+    };
+    mermaid: {
+        loading: Message;
+        renderError: Message;
+        loadError: Message;
+        showSource: Message;
+        hideSource: Message;
+        sourceLabel: Message;
+    };
+}
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends Message ? T[K] : DeepPartial<T[K]>;
+};
+type DiagramMessagesOverride = DeepPartial<DiagramMessages>;
+/** English strings. Copy this object, translate it, and pass it as `messages`. */
+declare const defaultMessages: DiagramMessages;
+/** Merges partial translations over the English defaults. Missing keys fall back to English. */
+declare function resolveMessages(override?: DiagramMessagesOverride): DiagramMessages;
+
+export { COLLAPSED_HEIGHT as C, EDGE_KINDS as E, GRID_SIZE as H, getReadingOrder as a$, NODE_KINDS as a0, NODE_STATUSES as a1, defaultPalette as aA, defineDiagram as aB, diagramToSvg as aC, diagramToSvgTree as aD, directionSides as aE, disconnect as aF, distributeNodes as aG, duplicateNodes as aH, escapeXml as aI, estimateTextWidth as aJ, exportDiagramJson as aK, exportDiagramSvg as aL, extractFragment as aM, findCycle as aN, findDirectionalNeighbor as aO, formatMessage as aP, getAbsoluteBounds as aQ, getAbsolutePosition as aR, getAbsolutePositions as aS, getAncestors as aT, getDescendants as aU, getDocumentBounds as aV, getEdgeGeometry as aW, getNeighbors as aX, getNodeBounds as aY, getNodeSize as aZ, getPortPlacements as a_, TEXT_METRICS as aj, addNode as am, alignNodes as an, applyLayout as ao, buildIndex as ap, canRedo as aq, canUndo as ar, checkConnection as as, computeEdgePath as at, connect as au, createDiagram as av, createGeometryContext as aw, createHistory as ax, createNode as ay, defaultMessages as az, getRoots as b0, groupNodes as b1, hasPath as b2, historyReducer as b3, importDiagram as b4, isContainerKind as b5, isHorizontal as b6, isSafeImageUrl as b7, layoutDiagram as b8, layoutedDiagram as b9, updateEdge as bA, updateNode as bB, validateDiagram as bC, wrapText as bD, mirrorDirection as ba, moveNodes as bb, nextEdgeId as bc, nextNodeId as bd, pasteFragment as be, portTypesCompatible as bf, rectCenter as bg, rectContainsPoint as bh, rectsIntersect as bi, removeEdges as bj, removeNode as bk, removeNodes as bl, resizeNode as bm, resolveConnectionRules as bn, resolveMessages as bo, resolvePalette as bp, serializeSvg as bq, setNodeParent as br, sideAnchor as bs, sideVector as bt, snapPoint as bu, snapValue as bv, topologicalOrder as bw, translateNodes as bx, ungroupNode as by, unionRects as bz, DEFAULT_NODE_SIZE as f, DIAGRAM_KINDS as g, DIAGRAM_VERSION as h, DiagramImportError as l, DiagramMutationError as s };
+export type { MutationErrorCode as $, Alignment as A, EdgePathInput as B, DiagramDocument as D, ExportJsonOptions as F, FocusDirection as G, GeometryContext as I, GeometryOptions as J, GroupOptions as K, LayoutDirection as L, HistoryAction as M, NodeKind as N, HistoryOptions as O, HistoryState as P, ImportErrorCode as Q, ImportOptions as R, ImportResult as S, IssueCode as T, IssueSeverity as U, LayoutAlgorithm as V, LayoutOptions as W, LayoutResult as X, LayoutSpacing as Y, Message as Z, MessageValues as _, NodeStatus as a, NewEdge as a2, NewNode as a3, NodePatch as a4, PasteOptions as a5, PasteResult as a6, Point as a7, PortPlacement as a8, Position as a9, ReadingOrderOptions as aa, Rect as ab, RemoveOptions as ac, Side as ad, Size as ae, StatusPalette as af, SvgAttributes as ag, SvgElement as ah, SvgOptions as ai, ValidateOptions as ak, ValidationResult as al, ConnectOptions as b, ConnectionCheck as c, ConnectionRejection as d, ConnectionRules as e, DiagramConnection as i, DiagramEdge as j, DiagramFragment as k, DiagramIndex as m, DiagramIssue as n, DiagramKind as o, DiagramMessages as p, DiagramMessagesOverride as q, DiagramMigration as r, DiagramNode as t, DiagramPalette as u, DiagramPaletteOverride as v, EdgeGeometry as w, EdgeKind as x, EdgePatch as y, EdgePath as z };