@elabs-ai/components-flow 4.0.0 → 4.2.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { ReactNode, SVGAttributes } from 'react';
-import { Node, Edge, ReactFlowProps, NodeProps, EdgeProps, Position, NodeChange, MiniMapProps, PanelPosition } from '@xyflow/react';
+import { ReactNode, SVGProps, CSSProperties, SVGAttributes, ComponentPropsWithoutRef } from 'react';
+import { Node, Edge, ReactFlowProps, FitViewOptions, NodeProps, EdgeProps, Position, NodeChange, MiniMapProps, PanelPosition } from '@xyflow/react';
 export { Background, Connection, Controls, Edge, EdgeProps, MiniMap, Node, NodeProps, Panel, Position, ReactFlow, ReactFlowProvider, addEdge, useEdgesState, useNodesState, useReactFlow } from '@xyflow/react';
 
 interface CanvasShellProps<NodeType extends Node = Node, EdgeType extends Edge = Edge> extends ReactFlowProps<NodeType, EdgeType> {
@@ -15,6 +15,26 @@ interface CanvasShellProps<NodeType extends Node = Node, EdgeType extends Edge =
      * use the exported `useHelperLines` + `<HelperLines>` directly.
      */
     helperLines?: boolean;
+    /**
+     * Re-fit the viewport whenever this value changes.
+     *
+     * React Flow's own `fitView` prop fits ONCE, as soon as the nodes are first measured,
+     * and then never again. A canvas whose positions arrive AFTER that first paint —
+     * anything laid out asynchronously, e.g. a debounced `layoutFlow` pass — therefore gets
+     * fitted to the pre-layout positions (typically every node still stacked at the origin)
+     * and stays there. Measured on the process map: the viewport pinned at React Flow's
+     * `maxZoom` of 2 with 2 of 11 nodes on screen, while the layout underneath was correct
+     * the whole time.
+     *
+     * Pass the key the layout is cached on (structure + direction), NOT something that
+     * changes on every render and not a metric: a re-fit is a viewport jump, so it must
+     * happen when the picture genuinely moved and never while the reader is reading. The
+     * fit waits for `useNodesInitialized`, so it measures real node boxes rather than
+     * fitting a degenerate bounding box a second time.
+     */
+    fitViewKey?: string | number;
+    /** Options for the {@link fitViewKey} re-fit. Ignored without one. */
+    fitViewKeyOptions?: FitViewOptions;
     /** Overlays rendered inside the flow (ZoomControls, Legend, Panels). */
     children?: ReactNode;
     className?: string;
@@ -31,6 +51,43 @@ interface CanvasShellProps<NodeType extends Node = Node, EdgeType extends Edge =
  */
 declare function CanvasShell<NodeType extends Node = Node, EdgeType extends Edge = Edge>({ helperLines, ...props }: CanvasShellProps<NodeType, EdgeType>): react.JSX.Element;
 
+/**
+ * The class every React Flow `<Handle>` in this package carries — and the one a
+ * consumer's own custom node must carry too.
+ *
+ * A connector dot is a MEASUREMENT ANCHOR, not a moving part. React Flow measures
+ * `handleBounds` from the DOM exactly once per layout change (`updateNodeInternals`,
+ * fired from the effect that sees `sourcePosition`/`targetPosition` change) and then
+ * draws every edge endpoint from that stored number until something invalidates it.
+ * So a dot that is still ON ITS WAY to its new side when that measurement is taken is
+ * measured at the wrong place — permanently, because nothing measures again.
+ *
+ * That is not hypothetical, and it is not only about author-written transitions:
+ *
+ * - `@elabs-ai/components-tokens`' reduced-motion backstop (`themes.css`, MOTION GATE)
+ *   sets `transition-duration: 0.01ms !important` on `*` so third-party engines that
+ *   ignore the `--t-*` tokens (Monaco, `@xyflow/react`, Streamdown) cannot animate.
+ *   `transition-property` is left at its initial value, `all` — so under
+ *   `prefers-reduced-motion: reduce` that rule does not remove a transition from a
+ *   handle, it CREATES one: every geometric property of every element becomes
+ *   transitioned, for one frame.
+ * - One frame is all it takes. Measured on `ProcessMap direction="LR"`: at the commit
+ *   that flips the handles from top/bottom to left/right, the dot's computed box was
+ *   still the OLD one (`getAnimations()` on it returned live `left`+`top`+`transform`
+ *   transitions), React Flow measured `{ x: 164, y: 45.5 }` where the settled DOM has
+ *   `{ x: 172, y: 37.5 }`, and every edge on the map then terminated up to 67 px away
+ *   from the dot it points at — for reduced-motion readers only, forever.
+ *
+ * `transition-property: none` is the fix at the right layer: it costs nothing under
+ * normal motion (no rule animates a handle there anyway) and it makes the reposition
+ * synchronous, so whenever React Flow measures, it measures the settled dot.
+ *
+ * The literal is written out here rather than assembled, because Tailwind extracts
+ * candidates from source TEXT: this file is scanned, so the utility is emitted, and
+ * components may interpolate the constant freely.
+ */
+declare const FLOW_HANDLE_ANCHOR_CLASS = "transition-none";
+
 /** A node side that can carry a handle. Doubles as the handle's stable id. */
 type FlowHandleSide = "top" | "right" | "bottom" | "left";
 /**
@@ -66,28 +123,166 @@ interface FlowNodeData extends Record<string, unknown> {
      * bottom-source (unchanged, backward-compatible).
      */
     handles?: FlowNodeHandles;
+    /**
+     * An extra row rendered INSIDE the card, below the text block — a meter bar, a
+     * sparkline, a chip row.
+     *
+     * It exists because content a composing package renders BESIDE `FlowNode` (as a sibling
+     * inside React Flow's node element) silently breaks the canvas's geometry: React Flow
+     * positions every `<Handle>` against the nearest positioned ancestor and measures the
+     * node box from its own wrapper, so a sibling row makes the node box taller than the
+     * visible card and the handles drift off the card's border by exactly that difference.
+     * Measured on the process map's activity node, whose 6px meter and 4px gap put every
+     * bottom dot 10px below the card it was supposed to sit on, and every left/right dot
+     * 5px below the card's own mid-line.
+     *
+     * Put the row here instead and the card IS the node box again, so the dots land on the
+     * card edge for free. Nothing is rendered when it is absent — existing nodes are
+     * byte-identical.
+     */
+    footer?: ReactNode;
 }
 type BrandFlowNode = Node<FlowNodeData, "brand">;
 /**
  * Branded custom node. Register it in `nodeTypes={{ brand: FlowNode }}` and
  * create nodes with `type: "brand"` and `data: FlowNodeData`.
+ *
+ * ## Focus vs selection (#312)
+ *
+ * `selected && "ring-2 ring-ring"` below is a SELECTION marker, not a focus
+ * indicator — it is React Flow's own click-driven `selected` state and is the
+ * genuine-selection carve-out `.claude/rules/theming.md` names explicitly.
+ * Keyboard focus is a separate, independent signal this component used to omit
+ * entirely (issue #312): React Flow puts `tabIndex`/`role="group"` and the real
+ * `:focus-visible` state on **its own wrapper** (`.react-flow__node`, which
+ * also always carries a `data-id` attribute), one level ABOVE the `<div>` this
+ * component returns — so neither `focus-ring` (`:focus-visible` on self) nor
+ * `focus-ring-within` (`:focus-within`, a focused descendant) can ever fire
+ * here; focus is PROXIED to an ancestor this component doesn't render.
+ * `focus-ring-static` is the flavour built for that exact shape (ADR 0027),
+ * gated by an ancestor-selector arbitrary variant — the same idiom
+ * `FlowEdgePath` uses for `.react-flow__edge:focus-visible`, keyed on
+ * `[data-id]` here (rather than the escaped `.react-flow\_\_node` class) so
+ * the selector needs no backslash escaping inside a plain JS string — a
+ * literal `\_` in a `cn()` argument is a real JS string escape and would be
+ * silently stripped at runtime (unlike in a bare, unbraced JSX attribute,
+ * where backslashes are never processed — the reason `FlowEdgePath` can use
+ * the class form safely and this component, composing through `cn()`, cannot).
+ * The two signals compose without merging into one ring: `selected` alone
+ * paints the ring layer only, while a focused node additionally gets the
+ * `--ring-contour` outline drawn outside it, so "selected AND focused" reads
+ * as two visible layers, not the single ring "selected alone" paints.
  */
 declare function FlowNode({ data, selected, sourcePosition, targetPosition, }: NodeProps<BrandFlowNode>): react.JSX.Element;
 
 /**
  * Branded bezier edge using the `--flow-edge` token. Register it in
  * `edgeTypes={{ brand: FlowEdge }}` and create edges with `type: "brand"`.
+ *
+ * Drawn through `FlowEdgePath`, so it carries the shared keyboard focus
+ * indicator (#286) — never reach for React Flow's `BaseEdge` directly.
  */
 declare function FlowEdge({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, markerEnd, style, }: EdgeProps): react.JSX.Element;
 
 /**
- * Branded edge that picks the closest source/target handle pair (from a node's
- * multi-side `FlowNodeHandles` config) and routes a bezier between them. Anchors
- * are recomputed every render, so they flip as nodes are dragged. Register it in
- * `edgeTypes={{ smart: FlowSmartEdge }}` and give the connected nodes a
- * `data.handles` config. Uses the `--flow-edge` token, matching `FlowEdge`.
+ * Extra stroke width, in px, of the `--ring` band drawn around a focused edge.
+ * The band sits *outside* the edge's own stroke, so it is visible whatever the
+ * edge's resting width is.
+ */
+declare const FLOW_EDGE_FOCUS_RING_WIDTH = 3;
+/**
+ * Extra stroke width, in px, of the neutral contour drawn outside the `--ring`
+ * band. This is the layer that carries the WCAG 1.4.11 bar: `--foreground`
+ * measures 12.50:1 against `--canvas` in `light` and 16.25:1 in `dark`, where
+ * `--ring` alone measures 1.30:1 in `light` (issue #286).
+ */
+declare const FLOW_EDGE_FOCUS_CONTOUR_WIDTH = 6;
+interface FlowEdgePathProps extends Omit<SVGProps<SVGPathElement>, "path" | "stroke" | "strokeWidth" | "style" | "ref"> {
+    /** SVG path `d` for this edge, from `getBezierPath`/`getSmoothStepPath`/… */
+    path: string;
+    /** Resting stroke paint — a `var(--token)` reference or a resolved colour. */
+    stroke: string;
+    /** Resting stroke width in px. The focus layers are drawn wider than this. */
+    strokeWidth: number;
+    /** Dash pattern, applied to the edge AND to both focus layers so a dashed edge keeps its shape when focused. */
+    strokeDasharray?: string;
+    /** Stroke opacity for the edge itself. Never applied to the focus layers. */
+    strokeOpacity?: number;
+    /** React Flow marker url, e.g. from `EdgeProps.markerEnd`. */
+    markerEnd?: string;
+    /** React Flow marker url, e.g. from `EdgeProps.markerStart`. */
+    markerStart?: string;
+    /** Width of the invisible pointer-target path React Flow draws over the edge. */
+    interactionWidth?: number;
+    /** Merged onto the edge path, last — so a consumer's `style.stroke` still wins. */
+    style?: CSSProperties;
+}
+/**
+ * The edge path every brand edge type draws, with the keyboard focus indicator
+ * built in. **Use this instead of React Flow's `BaseEdge`** — a custom edge that
+ * reaches for `BaseEdge` directly ships with no focus indicator at all, which is
+ * the defect issue #286 records (and `no-raw-base-edge.test.ts` fails on).
+ *
+ * ## Why the indicator is drawn rather than restyled
+ *
+ * React Flow zeroes the native outline on a focused edge
+ * (`.react-flow__edge:focus-visible { outline: none }`) and substitutes a stroke
+ * recolour on `.react-flow__edge-path`. Every brand edge passes its stroke as an
+ * **inline style** on that exact path — `BaseEdge` spreads `style` onto it — and
+ * an inline declaration beats any stylesheet rule, so the substitute never
+ * painted. Focusing an edge changed nothing on screen: WCAG 2.4.7 failed on
+ * every edge of every canvas, in both themes.
+ *
+ * The obvious repair — move the stroke into a custom property so a stylesheet
+ * rule can reach it — does **not** work here, and that was measured rather than
+ * assumed: React Flow's own `.react-flow__edge-path { stroke: … }` ships
+ * **unlayered**, and unlayered CSS outranks anything in `@layer utilities`,
+ * where Tailwind puts every utility. A `stroke-[var(--flow-edge-stroke)]` class
+ * would therefore lose to React Flow's `#b1b1b7` default and repaint every edge
+ * in the library. `!important` and setting `--xy-edge-stroke-selected` were both
+ * rejected in the issue.
+ *
+ * So the indicator is drawn on two paths this component owns, under the edge and
+ * on the same geometry. Nothing can shadow them: not React Flow's stylesheet,
+ * not a consumer's inline `style.stroke`, not a future edge type's own painting.
+ * They are hidden (`opacity-0`) until the ancestor `g.react-flow__edge` matches
+ * `:focus-visible`, which is a plain descendant selector on classes only this
+ * component uses.
+ *
+ * ## Compound, because one colour is not enough
+ *
+ * The indicator is two layers, per the compound-indicator recipe in
+ * `.claude/rules/theming.md`: a neutral `--foreground` contour at
+ * `strokeWidth + 6`, and the `--ring` band at `strokeWidth + 3` over it. The
+ * contour is the layer that clears WCAG 1.4.11's 3:1 bar against `--canvas` in
+ * both reference themes (12.50:1 `light`, 16.25:1 `dark`); a bare `--ring`
+ * stroke would not (1.30:1 in `light`). It is opacity + stroke only — no
+ * shadow — so it survives `data-decoration="8|9|10"`, which goes shadowless.
+ */
+declare function FlowEdgePath({ path, stroke, strokeWidth, strokeDasharray, strokeOpacity, markerEnd, markerStart, interactionWidth, className, style, ...props }: FlowEdgePathProps): react.JSX.Element;
+
+/**
+ * Branded edge that picks the closest source/target **handle** pair and routes a
+ * bezier between them. Anchors are recomputed every render, so they flip as
+ * nodes are dragged. Register it in `edgeTypes={{ smart: FlowSmartEdge }}`; give
+ * the connected nodes a `data.handles` config (e.g. `FLOW_ALL_SIDE_HANDLES`) to
+ * offer it more than the default two anchors. Uses the `--flow-edge` token,
+ * matching `FlowEdge`.
+ *
+ * ## The path terminates ON the handle dot
+ *
+ * The endpoints come from React Flow's **measured `handleBounds`** — the centre
+ * of the rendered dot — not from a point derived from the node's rectangle.
+ * That is a correctness property, not a refinement: an earlier version slid each
+ * anchor along the chosen side toward the other node (to fan out edges sharing a
+ * side) and picked sides from a four-way fallback list, so a line could meet the
+ * node up to half a side away from any dot — measured at ~22px on multi-side
+ * nodes and ~124px on nodes carrying only the default top/bottom handles, where
+ * a left/right side with no handle at all could be chosen. Two edges leaving the
+ * same handle now leave from the same point and diverge, exactly as React Flow's
+ * own edges do.
  */
-declare function FlowSmartEdge({ id, source, target, markerEnd, style }: EdgeProps): react.JSX.Element | null;
+declare function FlowSmartEdge({ id, source, target, sourceHandleId, targetHandleId, markerEnd, style, }: EdgeProps): react.JSX.Element | null;
 
 /** Axis-aligned node rectangle in absolute flow coordinates. */
 interface NodeRect {
@@ -100,12 +295,48 @@ interface NodeRect {
 declare const HANDLE_SIDES: FlowHandleSide[];
 /** Maps a handle side to the React Flow `Position` used for bezier control. */
 declare const sideToPosition: Record<FlowHandleSide, Position>;
+/** Maps a React Flow `Position` back to the handle side it names. */
+declare const positionToSide: Record<Position, FlowHandleSide>;
+/**
+ * One candidate connection point: the **measured centre of a rendered handle
+ * dot**, in absolute flow coordinates, plus the side it sits on.
+ *
+ * This is the unit `FlowSmartEdge` routes between. Anchoring on a measured
+ * handle — rather than on a point derived from the node's rectangle — is what
+ * guarantees the drawn path terminates exactly on the dot the user sees,
+ * whatever the handle's size, offset or CSS. See {@link pickClosestAnchors}.
+ */
+interface HandleAnchor {
+    /** The handle's `id`, when it has one (`FlowNode` uses the side name). */
+    id: string | null;
+    /** Absolute x of the handle dot's centre. */
+    x: number;
+    /** Absolute y of the handle dot's centre. */
+    y: number;
+    /** The node side the handle sits on — the bezier's control direction. */
+    side: FlowHandleSide;
+}
+/** The chosen source/target anchor pair. */
+interface ClosestAnchors {
+    source: HandleAnchor;
+    target: HandleAnchor;
+}
+/**
+ * Picks the source/target pair of **rendered handles** with the shortest
+ * straight-line distance between them.
+ *
+ * Returns `undefined` when either side has no candidates, so the caller can
+ * fall back to rectangle geometry for a node whose handles have not been
+ * measured yet (React Flow populates `handleBounds` on its first measurement
+ * pass; before that there is nothing to anchor to).
+ */
+declare function pickClosestAnchors(sources: HandleAnchor[], targets: HandleAnchor[]): ClosestAnchors | undefined;
 /** Absolute coordinate of a handle on the given side (the side's midpoint). */
 declare function handlePoint(rect: NodeRect, side: FlowHandleSide): {
     x: number;
     y: number;
 };
-/** The chosen source/target handle pair plus their absolute anchor points. */
+/** The side pair picked by {@link pickClosestHandles}, with both anchor points. */
 interface ClosestHandles {
     sourceSide: FlowHandleSide;
     targetSide: FlowHandleSide;
@@ -115,9 +346,14 @@ interface ClosestHandles {
     ty: number;
 }
 /**
- * Picks the source/target handle pair (one handle per node) with the shortest
- * straight-line distance between their anchor points. Empty side lists fall
- * back to all four sides so an edge always resolves to a pair.
+ * Rectangle-only fallback: picks the closest pair of **side midpoints** from the
+ * candidate sides of each node.
+ *
+ * `FlowSmartEdge` prefers {@link pickClosestAnchors} (measured handle centres)
+ * and only reaches for this before React Flow has measured the nodes. Pass the
+ * sides each node genuinely renders a handle on — passing sides that carry no
+ * handle produces an anchor floating on a bare border, which is the defect this
+ * module exists to avoid.
  */
 declare function pickClosestHandles(source: NodeRect, sourceSides: FlowHandleSide[], target: NodeRect, targetSides: FlowHandleSide[]): ClosestHandles;
 
@@ -229,6 +465,22 @@ interface FlowLayoutOptions {
 interface FlowLayoutResult<NodeType extends Node = Node, EdgeType extends Edge = Edge> {
     nodes: NodeType[];
     edges: EdgeType[];
+    /**
+     * Ids of edges that run **against** the layout direction — a rework / retry
+     * loop in a process graph. dagre breaks cycles by reversing such edges
+     * internally and never surfaces which ones it reversed, so this is derived
+     * from the ranks dagre stamps on the laid-out graph: an edge whose source
+     * ranks at or after its target went backwards. Render these with
+     * `FlowWeightedEdge`'s `variant="back"`.
+     */
+    backEdges: string[];
+    /**
+     * Ids of edges whose `source === target`. dagre does not lay out self-loops,
+     * so they are withheld from the graph entirely (never `setEdge`-ed) and are
+     * returned unchanged in `edges` — they take part in no rank computation and
+     * cannot distort the layout. Render these with `FlowSelfLoopEdge`.
+     */
+    selfLoops: string[];
 }
 /**
  * Pure dagre-powered auto layout. Computes new `position`s for `nodes` given
@@ -240,6 +492,11 @@ interface FlowLayoutResult<NodeType extends Node = Node, EdgeType extends Edge =
  * `node.height`, then a sensible default. Node identity and `data` are left
  * untouched — only `position` changes.
  *
+ * Also reports the graph's two structural signals — `backEdges` (edges that run
+ * against the layout direction) and `selfLoops` (`source === target`). Both are
+ * additive fields on the result; a caller that only destructures
+ * `{ nodes, edges }` is unaffected.
+ *
  * Pair with `useFlowLayout` to apply the result to a live canvas.
  */
 declare function layoutFlow<NodeType extends Node = Node, EdgeType extends Edge = Edge>(nodes: NodeType[], edges: EdgeType[], options?: FlowLayoutOptions): FlowLayoutResult<NodeType, EdgeType>;
@@ -268,8 +525,8 @@ interface UseFlowLayoutResult {
 declare function useFlowLayout<NodeType extends Node = Node, EdgeType extends Edge = Edge>(): UseFlowLayoutResult;
 
 /** Which generic graph-geometry algorithm `layoutGraph` should run. */
-type LayoutAlgorithm = "concentric" | "force" | "layered-lr" | "grid";
-/** Horizontal/vertical gap used by the `"grid"` and `"layered-lr"` algorithms. */
+type LayoutAlgorithm = "concentric" | "force" | "layered-lr" | "layered-tb" | "grid";
+/** Horizontal/vertical gap used by the `"grid"` and `"layered-*"` algorithms. */
 interface LayoutSpacing {
     x: number;
     y: number;
@@ -286,7 +543,7 @@ interface LayoutOptions {
     ringRadius?: number;
     /** `"force"` only — number of synchronous simulation ticks to run. @default 300 */
     iterations?: number;
-    /** `"grid"` / `"layered-lr"` — gap between nodes. @default {x:200,y:120} for grid. */
+    /** `"grid"` / `"layered-lr"` / `"layered-tb"` — gap between nodes. @default {x:200,y:120} for grid. */
     spacing?: LayoutSpacing;
     /** Resolve a node's size by id. Falls back to `measured`/`width`/`height`/a sensible default. */
     nodeSize?: (id: string) => {
@@ -303,7 +560,10 @@ interface LayoutOptions {
  * Node identity and `data` are left untouched — only `position` changes.
  * Pair with `useAutoLayout` for a memoized hook form.
  *
- * - `"layered-lr"` delegates to the dagre-powered `layoutFlow` (direction `"LR"`).
+ * - `"layered-lr"` / `"layered-tb"` delegate to the dagre-powered `layoutFlow`
+ *   (direction `"LR"` / `"TB"`). `spacing.x` is always the horizontal gap and
+ *   `spacing.y` the vertical one, so the two differ only in which axis carries
+ *   the ranks.
  * - `"concentric"` places `centerId` (or the highest-degree node) at the
  *   origin, with BFS shells at `ring × ringRadius`; disconnected nodes land in
  *   one extra outer ring so positions are never `NaN`.
@@ -477,13 +737,57 @@ interface LegendItem {
     /** Any CSS color or token reference, e.g. "var(--chart-1)". */
     color: string;
 }
-interface LegendProps {
+/**
+ * Categorical legend props — a swatch-and-label list. This is the shape
+ * `Legend` renders when `variant` is omitted, byte-for-byte unchanged from
+ * before the `"scale"` variant existed.
+ */
+interface LegendCategoricalProps {
+    variant?: "categorical";
     items: LegendItem[];
     title?: string;
     className?: string;
 }
-/** Small legend mapping colors/types to labels for a canvas or chart. */
-declare function Legend({ items, title, className }: LegendProps): react.JSX.Element;
+/**
+ * Continuous scale legend — a reading key that explains a WIDTH or COLOR
+ * encoding as a *range*, not a set of discrete categories (e.g.
+ * `FlowWeightedEdge`'s `data.weight` → stroke width, `data.value` → stroke
+ * color). `kind: "width"` reuses `computeEdgeWeightScale` — the exact pure
+ * scale `FlowWeightedEdge` calls — so the sample strokes drawn here can never
+ * drift from the widths a real flow's edges render for the same weights.
+ */
+interface LegendScaleProps {
+    variant: "scale";
+    /** Which continuous encoding this legend explains. */
+    kind: "width" | "color";
+    /** `[min, max]` of the underlying value the ramp represents. */
+    domain: [number, number];
+    /**
+     * Formats a domain value for display at a tick.
+     * @default the active `LocaleProvider` locale's `formatNumber` (host locale
+     * when no provider is mounted) — never a hardcoded `toLocaleString()`.
+     */
+    format?: (value: number) => string;
+    /**
+     * Sample count for `kind: "width"`: `"minmax"` draws a min/max pair of
+     * sample strokes, `"minmedmax"` adds the domain midpoint as a third
+     * sample. `kind: "color"` always renders a fixed 5-stop gradient
+     * regardless of this prop — five stops is what makes a 2-endpoint color
+     * ramp legible as an ordered scale (see the color-ramp a11y note below),
+     * independent of how many width samples are shown.
+     * @default "minmax"
+     */
+    ticks?: "minmax" | "minmedmax";
+    title?: string;
+    className?: string;
+}
+type LegendProps = LegendCategoricalProps | LegendScaleProps;
+/**
+ * Small legend mapping colors/types to labels for a canvas or chart
+ * (`variant: "categorical"`, the default), or — via `variant="scale"` — a
+ * continuous width/color ramp with a domain, tick marks and formatting.
+ */
+declare function Legend(props: LegendProps): react.JSX.Element;
 
 interface ZoomControlsProps {
     position?: PanelPosition;
@@ -631,4 +935,418 @@ interface UseFlowGroupsResult {
  */
 declare function useFlowGroups<NodeType extends Node = Node, EdgeType extends Edge = Edge>(): UseFlowGroupsResult;
 
-export { type BrandFlowButtonEdge, type BrandFlowGroupNode, type BrandFlowNode, type BrandFlowPlaceholderNode, CanvasShell, type CanvasShellProps, type ClosestHandles, type EdgeParams, FLOW_ALL_SIDE_HANDLES, FLOW_GROUP_NODE_TYPE, type FloatingEdgeData, type FloatingNodeGeometry, FlowButtonEdge, type FlowButtonEdgeData, FlowEdge, FlowFloatingEdge, FlowGroupNode, type FlowGroupNodeData, type FlowGroupOperationResult, type FlowGroupProxyEdgeData, type FlowGroupTone, type FlowHandleSide, type FlowLayoutDirection, type FlowLayoutOptions, type FlowLayoutResult, FlowMiniMap, type FlowMiniMapProps, FlowNode, type FlowNodeData, type FlowNodeHandles, FlowPlaceholderNode, type FlowPlaceholderNodeData, FlowSmartEdge, type GroupNodesOptions, type GroupOptions, HANDLE_SIDES, type HelperLineRect, HelperLines, type HelperLinesProps, type HelperLinesResult, InspectorPanel, type InspectorPanelProps, type LayoutAlgorithm, type LayoutOptions, type LayoutSpacing, Legend, type LegendItem, type LegendProps, type NodeRect, type UseFlowGroupsResult, type UseFlowLayoutResult, type UseHelperLinesOptions, type UseHelperLinesResult, ZoomControls, type ZoomControlsProps, collapseGroup, expandGroup, getEdgeParams, getHelperLines, groupNodes, handlePoint, isFlowGroupProxyEdge, layoutFlow, layoutGraph, pickClosestHandles, sideToPosition, toggleGroupCollapsed, ungroup, useAutoLayout, useFlowGroups, useFlowLayout, useHelperLines };
+interface EdgeLabelPillProps extends ComponentPropsWithoutRef<"button"> {
+    /** Primary label, e.g. a frequency count ("128×"). */
+    label?: string;
+    /** Secondary label rendered alongside the primary, e.g. a duration ("3.4d avg"). */
+    secondaryLabel?: string;
+    /** Label anchor, from `getBezierPath`/`getSmoothStepPath`'s `labelX`/`labelY`. */
+    x: number;
+    y: number;
+    /** Matches the parent edge's `selected` state. */
+    selected?: boolean;
+}
+/**
+ * A small HTML pill (via `EdgeLabelRenderer`, not SVG `<text>`) anchored at an
+ * edge's label point — so it can theme, wrap, and carry two values, unlike a
+ * bare SVG text node. Renders nothing when neither label is set. Real
+ * `<button>` so it is a genuine keyboard tab stop with a visible focus ring;
+ * `pointer-events: auto` on an otherwise `nodrag nopan` wrapper so it doesn't
+ * drag/pan the canvas, and doesn't block hovering the edge underneath it (the
+ * wrapper is sized to the pill itself, not the whole edge).
+ *
+ * `className`/`...props` spread onto the root `<button>` (`data-slot="edge-label-pill"`)
+ * so a consumer that composes this pill from outside `@elabs-ai/components-flow` —
+ * `@elabs-ai/components-process`'s `ProcessTransitionEdge` is the reference caller —
+ * can reach it directly (a dashed frame, a `data-selection` attribute) without a new
+ * semantic prop on this component. `className` merges LAST via `cn()`, so a caller can
+ * override any of the pill's own utility classes; omitting both leaves every existing
+ * caller's rendered markup unchanged.
+ */
+declare function EdgeLabelPill({ label, secondaryLabel, x, y, selected, className, ...props }: EdgeLabelPillProps): react.JSX.Element | null;
+
+interface FlowWeightedEdgeData extends Record<string, unknown> {
+    /** Frequency/volume this edge carries. Scaled into stroke width — see `computeEdgeWeightScale`. */
+    weight?: number;
+    /** Edges sharing a `scaleGroup` share one min-max width domain. @default all edges in the flow */
+    scaleGroup?: string;
+    /** A second, continuous measure (e.g. average duration). Colours the stroke — needs `valueDomain` too. */
+    value?: number;
+    /** `[min, max]` domain `value` is interpolated across, from `--flow-edge-weak` to `--flow-edge-strong`. */
+    valueDomain?: [number, number];
+    /** Primary edge-label-pill text, e.g. a frequency count. */
+    label?: string;
+    /** Secondary edge-label-pill text, e.g. a duration. */
+    secondaryLabel?: string;
+    /** Path geometry. Ignored when `variant` is `"back"`, which always routes smoothstep. @default "bezier" */
+    path?: "bezier" | "smoothstep";
+    /**
+     * Whether this edge advances the process (`"forward"`) or runs against the
+     * layout direction (`"back"` — a rework/retry edge, as reported by
+     * `layoutFlow`'s `backEdges`).
+     *
+     * `"back"` is distinguished by SHAPE, not colour: a dashed stroke, and a
+     * smoothstep route pushed clear of the forward edge between the same pair of
+     * nodes so the two never overlap. It also carries a real accessible name, so
+     * the direction reaches assistive technology as text rather than only as a
+     * `data-variant` attribute.
+     *
+     * @default "forward"
+     */
+    variant?: "forward" | "back";
+    /**
+     * Overrides the accessible name given to a `"back"` edge's graphic. Defaults
+     * to "Back edge — runs against the process direction".
+     */
+    variantLabel?: string;
+    /**
+     * Passed straight through to the rendered `EdgeLabelPill`'s `className`/`...props`
+     * (see `EdgeLabelPillProps`) — the seam a composing package (e.g.
+     * `@elabs-ai/components-process`'s `ProcessTransitionEdge`) uses to reach the pill's
+     * own root button from outside this component, without a new semantic prop here.
+     */
+    labelProps?: Omit<EdgeLabelPillProps, "label" | "secondaryLabel" | "x" | "y" | "selected">;
+}
+type BrandFlowWeightedEdge = Edge<FlowWeightedEdgeData, "weighted">;
+/**
+ * Branded weighted edge: `data.weight` scales stroke width (min-maxed per
+ * `data.scaleGroup` across every edge in the flow — see `computeEdgeWeightScale`,
+ * exported so a sibling like a continuous `Legend` renders the same ramp);
+ * `data.value` + `data.valueDomain` interpolate stroke colour between
+ * `--flow-edge-weak` and `--flow-edge-strong`; `data.label`/`data.secondaryLabel`
+ * render as an `EdgeLabelPill`. An edge with none of this data renders exactly
+ * like `FlowEdge` (fixed 1.5px, `--flow-edge` token) — fully backward-compatible.
+ * Register it in `edgeTypes={{ weighted: FlowWeightedEdge }}` and create edges
+ * with `type: "weighted"` and `data: FlowWeightedEdgeData`.
+ *
+ * `weight`/`value` are VISUAL ONLY — stroke width and colour reach no screen
+ * reader. This component cannot set its own accessible name: React Flow's
+ * `EdgeWrapper` sources it from `edge.ariaLabel` on the edge OBJECT, one level
+ * above the component it renders as a child (issue #285). Run your `edges`
+ * through `withWeightedEdgeAria` (from `./edge-aria`, or set `edge.ariaLabel`
+ * yourself) before handing them to `<CanvasShell>`/`<ReactFlow>` — otherwise
+ * the measure this component exists to show reaches no assistive technology,
+ * and the edge announces only React Flow's generic "Edge from n1 to n2".
+ * `withWeightedEdgeAria` returns a new array each call — memoize it
+ * (`useMemo(() => withWeightedEdgeAria(edges), [edges])`) if you call it
+ * inline in render.
+ *
+ * `data-weight`/`data-value` are also stamped onto the rendered `<path>` (raw
+ * `data.weight`/`data.value`, not the scaled stroke width) — a stable
+ * selector for tests/consumers, independent of the naming seam above.
+ *
+ * `data.variant: "back"` marks an edge that runs against the process direction
+ * (dagre's reversed edges — see `layoutFlow`'s `backEdges`). It is dashed and
+ * routed clear of the forward edge between the same two nodes, and carries a
+ * real accessible name; the default `"forward"` renders exactly as before.
+ *
+ * Selected state uses `--ring` (matching the `ring-ring` treatment `FlowNode`/
+ * `FlowGroupNode` use), overriding weight/value-derived width and colour so a
+ * selected edge always reads clearly. No stroke-dasharray animation — reduced
+ * motion is respected because there is no motion to reduce.
+ *
+ * KEYBOARD FOCUS is a separate state, drawn by `FlowEdgePath` (#286): selection
+ * needs a consumer's `onEdgesChange` to ever become true, so it can never be the
+ * indicator a tab stop owes its user.
+ */
+declare function FlowWeightedEdge({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, markerEnd, style, selected, data, }: EdgeProps<BrandFlowWeightedEdge>): react.JSX.Element;
+
+/**
+ * Where a back edge's return leg runs, so it stays VISIBLE.
+ *
+ * A back edge is drawn as a smoothstep with one long cross-segment running against the
+ * layout direction. React Flow puts that segment halfway between the two handles by
+ * default, and a fixed nudge off the midpoint does not help: in a top-down layout the
+ * midpoint of a rework edge sits between two ranks, i.e. squarely inside the column of
+ * cards it is supposed to run past. Edges paint UNDER nodes, so the segment vanishes
+ * behind the cards and all the reader is left with is a dashed stub below one node and
+ * another above the other — which reads as a stray rectangle, not as a loop back.
+ *
+ * So the leg is placed OUTSIDE every card it would otherwise pass behind: past the far
+ * side of every node whose extent overlaps the span the edge crosses. That is how a
+ * process-mining tool draws a rework loop — out, around the rank, back in — and it is
+ * the only placement that is correct for a graph rather than for a pair of nodes.
+ */
+/** One node's laid-out box, in flow coordinates. */
+interface BackEdgeNodeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Which axis the layout's ranks advance along. */
+type BackEdgeAxis = "vertical" | "horizontal";
+/**
+ * The `centerX` (vertical layout) or `centerY` (horizontal layout) to hand
+ * `getSmoothStepPath`, or `null` when nothing is measured yet and React Flow's own
+ * midpoint should stand.
+ *
+ * @param rects  Every laid-out node on the canvas. Nodes that cannot be hit are filtered
+ *               out here rather than by the caller, so the caller stays a plain map.
+ * @param span   The interval the edge crosses on the RANK axis (`[min, max]` of the two
+ *               handle coordinates) — a node outside it is never behind this edge.
+ * @param clearance  Gap left between the leg and the outermost card it clears.
+ */
+declare function backEdgeDetour(rects: readonly BackEdgeNodeRect[], axis: BackEdgeAxis, span: readonly [number, number], clearance: number): number | null;
+
+/**
+ * weight-scale — pure, framework-free "edge weight → stroke width" scale.
+ *
+ * `FlowWeightedEdge` calls this with every edge in the flow (via `useEdges()`,
+ * memoized) so a group of edges can be min-maxed against ONE shared domain
+ * instead of each edge picking its own arbitrary width. No React, no DOM: a
+ * sibling (e.g. RM-045's continuous `Legend`) can call it directly to render
+ * the same ramp the edges use, and it is trivially unit-testable.
+ */
+/** Minimal edge shape the scale needs — a subset of `Edge<FlowWeightedEdgeData>`. */
+interface WeightedEdgeLike {
+    id: string;
+    data?: {
+        weight?: number;
+        scaleGroup?: string;
+    };
+}
+interface EdgeWeightScaleOptions {
+    /** Output stroke-width range, in px. @default [1.5, 8] */
+    widthRange?: [number, number];
+    /**
+     * Restrict the domain calculation (and the returned map) to edges whose
+     * `data.scaleGroup` equals this value — edges in a different group are
+     * skipped entirely. Omit to compute one scale per distinct `scaleGroup`
+     * present in `edges` (edges with no `scaleGroup` share one implicit
+     * default group, so a flow that never sets it still gets one shared
+     * domain — "all edges in the same `<ReactFlow>`").
+     */
+    scaleGroup?: string;
+}
+/** Matches today's fixed 1.5px `FlowEdge` stroke, so an unweighted edge is unchanged. */
+declare const DEFAULT_EDGE_WIDTH_RANGE: [number, number];
+/**
+ * Resolve every edge's `data.weight` into a stroke-width, linearly min-maxed
+ * into `widthRange` per `scaleGroup`. An edge with no `data.weight` gets the
+ * range floor — the existing fixed 1.5px `FlowEdge` already draws, so a plain
+ * edge renders unchanged. An edge that is the only member of its group (or
+ * whose group has zero weight variance) gets the midpoint of the range —
+ * there is no domain to compare it against.
+ */
+declare function computeEdgeWeightScale(edges: WeightedEdgeLike[], opts?: EdgeWeightScaleOptions): Map<string, number>;
+
+/**
+ * edge-aria — pure, framework-free "edge data → accessible name" naming seam
+ * for `FlowWeightedEdge`, mirroring `weight-scale.ts`'s shape (no React, no
+ * DOM, trivially unit-testable).
+ *
+ * `FlowWeightedEdge` encodes `data.weight` as stroke width and, optionally,
+ * `data.value` as stroke colour — both purely visual. React Flow's own
+ * `EdgeWrapper` sources an edge's accessible name from `edge.ariaLabel`
+ * (`edge` object, not the edge COMPONENT — see issue #285), so the component
+ * has no channel to set it. This module is the seam a caller runs their
+ * `edges` array through instead.
+ *
+ * Naming contract (a decision, not an accident):
+ *  1. An explicit `edge.ariaLabel` always wins — never overwritten.
+ *  2. Otherwise compose `"Edge from <source> to <target>, weight <n>"`,
+ *     appending `", <valueLabel> <n>"` when `data.value` is set and the pill
+ *     text (`data.label`/`data.secondaryLabel`, space-joined) when either is
+ *     present.
+ *  3. When an edge carries none of `weight`/`value`/`label`/`secondaryLabel`,
+ *     return `undefined` so React Flow's own default
+ *     ("Edge from <source> to <target>") survives untouched. That quoted
+ *     string is `@xyflow/react`'s output, not ours — the `e-bare` edge in
+ *     `flow-weighted-edge.stories.tsx`'s `NamingContractEdges` story (#327)
+ *     is the browser lock for it: it renders a measure-less edge against a
+ *     real `CanvasShell` and asserts the default name via
+ *     `toHaveAccessibleName`. If that story goes red after a dependency
+ *     bump, read it as a signal that React Flow's default changed, not as a
+ *     flake to silence.
+ */
+
+interface WeightedEdgeAriaOptions {
+    /** Word used for the width measure in the composed name. @default "weight" */
+    weightLabel?: string;
+    /** Word used for the colour measure in the composed name. @default "value" */
+    valueLabel?: string;
+    /**
+     * Map a node id to its display name, so the composed name says
+     * "Edge from Order placed to Picked" rather than "Edge from n1 to n2". The
+     * caller owns node display names (this module never reaches into a `nodes`
+     * array), so it is a hook, not an automatic lookup.
+     */
+    nameOf?: (nodeId: string) => string;
+    /** Format a numeric measure for display. @default String(n) */
+    formatNumber?: (n: number) => string;
+}
+/**
+ * Derive one edge's accessible name from its weight/value/labels. Pure — no
+ * React, no DOM. Returns:
+ *  - the edge's own `ariaLabel`, unchanged, when the caller already set one;
+ *  - a composed string when the edge carries `weight`, `value`, `label` or
+ *    `secondaryLabel`;
+ *  - `undefined` when there is nothing to add (so the default announcement
+ *    from React Flow's `EdgeWrapper` survives untouched).
+ */
+declare function buildWeightedEdgeAriaLabel(edge: BrandFlowWeightedEdge, opts?: WeightedEdgeAriaOptions): string | undefined;
+/**
+ * Stamp `ariaLabel` onto every weighted edge that has none, per
+ * `buildWeightedEdgeAriaLabel`'s naming contract. An edge that already
+ * carries an `ariaLabel` is returned unchanged (never overwritten); an edge
+ * with nothing to add is also returned unchanged, so an unrelated edge type
+ * sharing this array keeps its identity.
+ *
+ * Returns a NEW array — memoize the call when used inline in render (e.g.
+ * `useMemo(() => withWeightedEdgeAria(edges), [edges])`), or a consumer hands
+ * React Flow a new `edges` identity every frame.
+ */
+declare function withWeightedEdgeAria<E extends BrandFlowWeightedEdge>(edges: E[], opts?: WeightedEdgeAriaOptions): E[];
+
+interface FlowSelfLoopEdgeData extends Record<string, unknown> {
+    /**
+     * Frequency/volume this loop carries. Scaled into stroke width by the SAME
+     * `computeEdgeWeightScale` domain as `FlowWeightedEdge`, so a loop's weight
+     * is directly comparable with the forward edges around it.
+     */
+    weight?: number;
+    /** Edges sharing a `scaleGroup` share one min-max width domain. @default all edges in the flow */
+    scaleGroup?: string;
+    /** Primary edge-label-pill text, e.g. a repeat count. */
+    label?: string;
+    /** Secondary edge-label-pill text, e.g. an average duration. */
+    secondaryLabel?: string;
+    /** Radius of the arc, in px. @default 28 */
+    loopRadius?: number;
+    /**
+     * Overrides the accessible name given to the loop's graphic. Defaults to
+     * "Self-loop on <node> — this step repeats".
+     */
+    loopLabel?: string;
+    /**
+     * Passed straight through to the rendered `EdgeLabelPill`'s `className`/`...props`
+     * (see `EdgeLabelPillProps`) — the seam a composing package (e.g.
+     * `@elabs-ai/components-process`'s `ProcessTransitionEdge`) uses to reach the pill's
+     * own root button from outside this component, without a new semantic prop here.
+     */
+    labelProps?: Omit<EdgeLabelPillProps, "label" | "secondaryLabel" | "x" | "y" | "selected">;
+}
+type BrandFlowSelfLoopEdge = Edge<FlowSelfLoopEdgeData, "self-loop">;
+/**
+ * Branded self-loop edge: an edge whose `source === target` — the "this step
+ * repeated" signal of a process map. Register it in
+ * `edgeTypes={{ "self-loop": FlowSelfLoopEdge }}` and create edges with
+ * `type: "self-loop"` and `data: FlowSelfLoopEdgeData`.
+ *
+ * dagre cannot lay a self-loop out, so `layoutFlow` withholds them from the
+ * graph entirely and reports their ids in `selfLoops` — this component draws
+ * the arc itself, from the node's own live geometry (`useInternalNode`).
+ *
+ * ## It terminates ON the handle dots, like every other brand edge
+ *
+ * The two handle points of a self-loop sit on OPPOSITE sides of one node, so they
+ * describe no useful straight line — which is why this edge used to ignore them and
+ * arc over the node's top edge instead, with its feet on bare border a loop-radius
+ * away from the nearest dot. Measured on the process map, that read as a detached
+ * arc floating above the card: 24 px clear of any dot in a top-to-bottom layout, and
+ * 69 px in a left-to-right one, where the loop stayed stubbornly on TOP while the
+ * flow (and the handles) had moved to the sides. Both are the "an edge terminates on
+ * a handle dot" rule being broken, just by a component that had declared itself
+ * exempt.
+ *
+ * `selfLoopHandleArc` keeps the loop a SHAPE — it just bulges clear of the node on
+ * the side a quarter turn from the source handle's own normal, so it lassos down the
+ * right in a top-to-bottom layout and arcs over the top in a left-to-right one,
+ * without this component knowing which direction is in force. Before the node is
+ * measured there is nothing to clear, so it falls back to the node-box arc
+ * (`selfLoopPath`) rather than to `NaN`.
+ *
+ * The loop is distinguished from a forward edge by its SHAPE, not by colour —
+ * a closed arc above the node, legible in greyscale and in every theme — and
+ * publishes that meaning as a real accessible name, because a `data-slot` is
+ * invisible to assistive technology. Its label is an `EdgeLabelPill` at the
+ * arc's apex, a genuine keyboard tab stop with a visible focus ring.
+ *
+ * Stroke width comes from the same `computeEdgeWeightScale` domain
+ * `FlowWeightedEdge` uses, so a loop weighted 8 reads as thick as a forward
+ * edge weighted 8. Nothing animates, so there is no motion to reduce.
+ *
+ * The arc is drawn through `FlowEdgePath`, so it inherits the shared keyboard
+ * focus indicator (#286) rather than having to opt into it.
+ */
+declare function FlowSelfLoopEdge({ id, source, sourceX, sourceY, targetX, targetY, markerEnd, style, selected, data, }: EdgeProps<BrandFlowSelfLoopEdge>): react.JSX.Element;
+
+/**
+ * self-loop-geometry — pure, framework-free arc math for a self-referencing edge.
+ *
+ * Kept out of the component (and out of React) so the loop's shape can be
+ * unit-tested without a canvas, and so a sibling that needs the same apex
+ * point (a legend, an overlay, a screenshot harness) can compute it directly.
+ */
+/** Default arc radius, in px. A loop this size clears `FlowNode`'s header without dominating it. */
+declare const DEFAULT_LOOP_RADIUS = 28;
+/** The box a self-loop is drawn above. Matches a React Flow `InternalNode` structurally. */
+interface SelfLoopAnchor {
+    /** Horizontal centre of the node the loop belongs to. */
+    centerX: number;
+    /** Top edge of that node — the loop is drawn above this line. */
+    topY: number;
+}
+interface SelfLoopPath {
+    /** SVG `d` for the arc. */
+    path: string;
+    /** Where a label belongs: the arc's apex. */
+    labelX: number;
+    labelY: number;
+}
+/**
+ * A cubic arc that leaves the node's top-RIGHT, bulges up over the node, and
+ * re-enters at its top-LEFT — the conventional "this step repeated" mark in a
+ * process map, and a SHAPE rather than a colour, so it survives greyscale.
+ *
+ * The curve is symmetric about `centerX`, which puts its `t = 0.5` midpoint
+ * exactly at `(centerX, topY - APEX_FACTOR × loopRadius)` — the apex the label
+ * is anchored to. Never returns `NaN`: a non-finite input falls back to `0`
+ * and a non-positive radius falls back to the default.
+ */
+declare function selfLoopPath(anchor: SelfLoopAnchor, loopRadius: number): SelfLoopPath;
+/**
+ * The two handle anchors a self-loop actually joins, plus the box it has to clear.
+ *
+ * A self-loop's `sourceX/sourceY` and `targetX/targetY` are the SAME node's two handle
+ * points, which is why they describe no useful straight line — but they are still the
+ * only two points on the canvas the reader recognises as connectors, so the arc has to
+ * start and end exactly on them. {@link selfLoopHandleArc} is the geometry that does
+ * that; {@link selfLoopPath} remains the node-box arc used before a node is measured.
+ */
+interface SelfLoopHandleAnchor {
+    /** Where the loop leaves the node — React Flow's own SOURCE handle anchor. */
+    sourceX: number;
+    sourceY: number;
+    /** Where it re-enters — React Flow's own TARGET handle anchor. */
+    targetX: number;
+    targetY: number;
+    /** The node's centre. Decides which way is "out of the card". */
+    centerX: number;
+    centerY: number;
+    /** The node's rendered size, so the arc clears the card instead of crossing it. */
+    width: number;
+    height: number;
+}
+/**
+ * A cubic that leaves the SOURCE handle dot, bulges clear of the node on one side, and
+ * re-enters at the TARGET handle dot.
+ *
+ * It is direction-agnostic by construction: the bulge is the source normal rotated a
+ * quarter turn, so a top-to-bottom layout (handles on the bottom and top) gets a lasso
+ * down the node's right-hand side, and a left-to-right layout (handles on the right and
+ * left) gets an arc over the top — with no `direction` prop, and no list of cases to keep
+ * in step with `layoutFlow`'s `HANDLE_BY_DIRECTION`.
+ *
+ * `loopRadius` is how far the curve shoots straight out of each dot before it turns, and
+ * also the gap the arc's widest point keeps from the card's edge. The label sits at that
+ * widest point — the cubic's `t = 0.5` midpoint — so it is off the node by construction.
+ *
+ * Never returns `NaN`: non-finite inputs fall back to `0`, a non-positive radius to
+ * {@link DEFAULT_LOOP_RADIUS}, and a handle point sitting on the node's centre (nothing
+ * measured yet) to a downward source normal.
+ */
+declare function selfLoopHandleArc(anchor: SelfLoopHandleAnchor, loopRadius: number): SelfLoopPath;
+
+export { type BackEdgeAxis, type BackEdgeNodeRect, type BrandFlowButtonEdge, type BrandFlowGroupNode, type BrandFlowNode, type BrandFlowPlaceholderNode, type BrandFlowSelfLoopEdge, type BrandFlowWeightedEdge, CanvasShell, type CanvasShellProps, type ClosestAnchors, type ClosestHandles, DEFAULT_EDGE_WIDTH_RANGE, DEFAULT_LOOP_RADIUS, EdgeLabelPill, type EdgeLabelPillProps, type EdgeParams, type EdgeWeightScaleOptions, FLOW_ALL_SIDE_HANDLES, FLOW_EDGE_FOCUS_CONTOUR_WIDTH, FLOW_EDGE_FOCUS_RING_WIDTH, FLOW_GROUP_NODE_TYPE, FLOW_HANDLE_ANCHOR_CLASS, type FloatingEdgeData, type FloatingNodeGeometry, FlowButtonEdge, type FlowButtonEdgeData, FlowEdge, FlowEdgePath, type FlowEdgePathProps, FlowFloatingEdge, FlowGroupNode, type FlowGroupNodeData, type FlowGroupOperationResult, type FlowGroupProxyEdgeData, type FlowGroupTone, type FlowHandleSide, type FlowLayoutDirection, type FlowLayoutOptions, type FlowLayoutResult, FlowMiniMap, type FlowMiniMapProps, FlowNode, type FlowNodeData, type FlowNodeHandles, FlowPlaceholderNode, type FlowPlaceholderNodeData, FlowSelfLoopEdge, type FlowSelfLoopEdgeData, FlowSmartEdge, FlowWeightedEdge, type FlowWeightedEdgeData, type GroupNodesOptions, type GroupOptions, HANDLE_SIDES, type HandleAnchor, type HelperLineRect, HelperLines, type HelperLinesProps, type HelperLinesResult, InspectorPanel, type InspectorPanelProps, type LayoutAlgorithm, type LayoutOptions, type LayoutSpacing, Legend, type LegendCategoricalProps, type LegendItem, type LegendProps, type LegendScaleProps, type NodeRect, type SelfLoopAnchor, type SelfLoopHandleAnchor, type SelfLoopPath, type UseFlowGroupsResult, type UseFlowLayoutResult, type UseHelperLinesOptions, type UseHelperLinesResult, type WeightedEdgeAriaOptions, type WeightedEdgeLike, ZoomControls, type ZoomControlsProps, backEdgeDetour, buildWeightedEdgeAriaLabel, collapseGroup, computeEdgeWeightScale, expandGroup, getEdgeParams, getHelperLines, groupNodes, handlePoint, isFlowGroupProxyEdge, layoutFlow, layoutGraph, pickClosestAnchors, pickClosestHandles, positionToSide, selfLoopHandleArc, selfLoopPath, sideToPosition, toggleGroupCollapsed, ungroup, useAutoLayout, useFlowGroups, useFlowLayout, useHelperLines, withWeightedEdgeAria };