@statelyai/flow-react 0.10.1 → 0.11.1

package/README.md

@@ -17,7 +17,7 @@ The React package owns React lifecycle, context, selector subscriptions, and a c
 
 <!-- transient entity rendering split between src/StatelyFlow.tsx and flow-dom src/entity-geometry.ts -->
 
-Optimization is part of the architecture, not a later cleanup pass. Components subscribe only to durable content and interaction state. During drag and animated layout sessions, `@statelyai/flow-dom` batches node rectangles, default group child-area and header rectangles, edge paths, endpoint handles, label positions, and multi-selection bounds into imperative animation-frame writes, so React commits only at transient-session boundaries. Default group headers keep projected styles on a separate element from imperative geometry, preserving projected transforms during drag. Default edge paths expose `data-flow-edge-segment`; custom edge renderers can use the same indexed attribute to join the imperative path updates. Existing custom paths whose `d` exactly matches a routed segment are also bound automatically, including duplicate hit strokes; unrelated decoration paths are left alone. Router-provided `PathData.svgPath` geometry is honored by both initial React rendering and those imperative updates.
+Optimization is part of the architecture, not a later cleanup pass. Components subscribe only to durable content and interaction state. During drag and animated layout sessions, `@statelyai/flow-dom` batches node rectangles, default group child-area and header rectangles, edge paths, endpoint handles, label positions, and multi-selection bounds into imperative animation-frame writes, so React commits only at transient-session boundaries. Default group headers keep projected styles on a separate element from imperative geometry, preserving projected transforms during drag. Use `EdgePath` and `EdgeEndpoint` in custom edge renderers to receive the same imperative path and endpoint updates. The components declare Flow's geometry attributes for you. Existing custom paths whose `d` exactly matches a routed segment are also bound automatically, including duplicate hit strokes; unrelated decoration paths are left alone. Router-provided `PathData.svgPath` geometry is honored by both initial React rendering and those imperative updates.
 
 The graph data structure is the source of truth for graph content, not for transient UI state. Core node and edge data should not grow flags like `selected: true` or `dragging: true`; selection, focus, dragging, hover, connection state, and similar interaction state live in the flow store and are derived into render props such as `selected` or `dragging`.
 
@@ -53,7 +53,10 @@ DOM measurement is one-directional. Nodes, ports, and edge labels report their r
 | `PanePortal` / `ViewportPortal`               | Render custom content into fixed screen-coordinate or transformed canvas-coordinate layers                              |
 | `useFitViewExclusion()`                       | Register an overlay element whose measured edge band fit and center commands avoid                                      |
 | `EntityAnchor`                                | Position custom controls on entity sides or free-standing canvas bounds with screen-stable offsets and inverse scaling  |
-| `Port`                                        | Render a measured connection port or a graph-owned readonly inspection port                                             |
+| `Port`                                        | Render a measured or graph-owned port with native div props and a forwarded ref                                          |
+| `EdgePath`                                    | Render routed SVG segments with imperative geometry updates                                                             |
+| `EdgeEndpoint`                                | Render a reconnection circle with an optional canvas-space endpoint offset                                              |
+| `RenderConnectionLineProps`                   | Connection state, routed geometry, validity, port centers, and directions passed to `renderConnectionLine`               |
 | `RenderEdgeLabelProps`                        | Edge, path, bounds, interaction state, and projected attrs passed to `renderEdgeLabel`                                  |
 | `Panel`                                       | Positioned overlay panel for controls and custom UI                                                                     |
 | `ReactActiveGraphProjection`                  | React-typed active projection for `<StatelyFlow projections={...} />` or controller-owned projections                   |
@@ -67,11 +70,27 @@ DOM measurement is one-directional. Nodes, ports, and edge labels report their r
 
 Color mode is store data, not engine behavior. `@statelyai/flow-dom` exports small helpers for resolving and applying `light`, `dark`, and `system`, while React exposes hooks/components that make those values easy to use with CSS variables.
 
-`initialGraph` seeds a graph that the adapter-owned flow instance owns. For caller ownership, create a controller and pass `flow={flow}`. There is no controlled `graph` prop; observe `flow.on('commit', ...)` or `onCommit` for persistence and synchronization. Runtime `settings`, `inputModes`, and `projections` update the existing flow instance. If `projections` is omitted, `StatelyFlow` subscribes to the instance's `flow.projections` lifecycle.
+`initialGraph` seeds a graph that the adapter-owned flow instance owns. For caller ownership, create a controller and pass `flow={flow}`. There is no controlled `graph` prop; observe `flow.on('commit', ...)` for persistence and synchronization. Adapter-owned instances also accept `onCommit`. Runtime `settings`, `inputModes`, and `projections` update the existing flow instance. Changes to `inputModes` affect new gestures without cancelling one in progress. Removing connect mode clears a pending click connection. If `projections` is omitted, `StatelyFlow` subscribes to the instance's `flow.projections` lifecycle.
+
+<!-- events and listeners lifecycle from src/hooks.ts and src/StatelyFlow.tsx -->
+
+`events` and selector `listeners` work with both adapter-owned and supplied instances. The adapter keeps callbacks current and removes its subscriptions when the view unmounts or the instance changes. Callbacks registered when creating a supplied instance remain owned by that instance. Each separately registered callback still runs.
+
+```tsx
+<StatelyFlow
+	flow={flow}
+	events={{
+		connectionEnded: (event) => console.log(event.status),
+		commit: () => console.log('graph changed'),
+	}}
+/>
+```
+
+See [Keep application state in XState Store](EXTERNAL_STATE.md) for a live Flow graph with separate application state and saved documents.
 
 <!-- StatelyFlow renderEdgeLabel and layers props from src/StatelyFlow.tsx plus portal exports from src/LayerPortals.tsx -->
 
-`renderEdgeLabel` replaces the built-in label content while retaining Flow's positioned, measured, interactive label wrapper. Set `edge.label.autoSize: true` for content-driven custom labels; the wrapper then leaves width/height unset while its measurement drives stable routed geometry. Render props include the edge's current `pathData`: the same `EdgePathData` object already routed by `StatelyFlow`, including both source-to-label and label-to-target segments. Transient drag geometry remains on Flow's imperative DOM path, and the renderer receives current committed geometry at gesture boundaries. Use `layers.viewport` for canvas-coordinate interaction content and `layers.pane` for screen-coordinate content. Descendants can target the same named layers with `ViewportPortal` and `PanePortal`. Flow enforces paint bands (`edges` → `entities` → `labels` → `interaction` → `guides` → `chrome`) so entity-local z-index cannot cover labels, selection chrome, anchors, or portaled toolbars. Override the namespaced `--flow-layer-*` variables only when intentionally changing that contract. Layer wrappers ignore pointer input; opt individual controls in with `pointerEvents: "auto"` and mark controls inside labels or canvas layers with `data-flow-interactive` when Flow gestures should ignore them.
+`renderEdgeLabel` replaces the built-in label content while retaining Flow's positioned, measured, interactive label wrapper. Set `edge.label.autoSize: true` for content-driven custom labels; the wrapper then leaves width/height unset while its measurement drives stable routed geometry. Render props include the edge's current `pathData`: the same `EdgePathData` object already routed by `StatelyFlow`, including both source-to-label and label-to-target segments. Transient drag geometry remains on Flow's imperative DOM path, and the renderer receives current committed geometry at gesture boundaries. Use `layers.viewport` for canvas-coordinate interaction content and `layers.pane` for screen-coordinate content. Descendants can target the same named layers with `ViewportPortal` and `PanePortal`. Flow enforces paint bands (`edges` → `entities` → `labels` → `interaction` → `guides` → `chrome`) so entity-local z-index cannot cover labels, selection chrome, anchors, or portaled toolbars. Override the namespaced `--flow-layer-*` variables only when intentionally changing that contract. Empty pane layers use `display: none` and become visible when content mounts. Layer wrappers ignore pointer input; opt individual controls in with `pointerEvents: "auto"` and mark controls inside labels or canvas layers with `data-flow-interactive` when Flow gestures should ignore them.
 
 Attach the ref from `useFitViewExclusion({ side, gap })` to floating controls that cover the canvas. The hook measures the element relative to the Flow root at command time, including content portaled outside the root, so responsive toolbars and panel-relative chrome do not need guessed fit padding.
 
@@ -81,6 +100,36 @@ The default edge renderer honors `edge.style.markerStart` and `markerEnd` values
 
 Render layout-owned ports with `<Port measured={false} interaction="inspect" />`. Inspection ports are focusable, selectable addressables (`${node.id}:${port.name}`), emit the normal entity click events, and never start a connection gesture. Omit `interaction` (or use `"connect"`) to retain existing connection behavior.
 
+<!-- Port props from src/Port.tsx and custom edge geometry from src/EdgePrimitives.tsx -->
+
+`Port` accepts native div props, including `aria-*`, `className`, `style`, and event handlers. Its forwarded ref points to the measured div. Flow composes focus handlers with yours and retains its identity attributes.
+
+Render custom edge SVG content with `EdgePath` and `EdgeEndpoint`. `EdgePath` accepts native path props except `d` and paints every routed segment. `EdgeEndpoint` accepts native circle props except `cx`, `cy`, `r`, and `offset`. Its `radius` defaults to `10` canvas units. Its `offset` is a canvas-space `{ x, y }` displacement that follows drag and layout geometry without React commits. `end` selects the source or target endpoint, and the ref points to the circle.
+
+```tsx
+import { EdgeEndpoint, EdgePath, StatelyFlow } from '@statelyai/flow-react';
+
+<StatelyFlow
+	flow={flow}
+	renderEdge={({ edge, pathData }) => (
+		<>
+			<EdgePath pathData={pathData} stroke="currentColor" />
+			<EdgeEndpoint
+				edgeId={edge.id}
+				pathData={pathData}
+				end="target"
+				radius={10}
+				offset={{ x: -6, y: 0 }}
+			/>
+		</>
+	)}
+/>
+```
+
+<!-- connection preview lifecycle and render props from src/StatelyFlow.tsx -->
+
+`renderConnectionLine` renders SVG content in a separate host above nodes. The host exists only during an active preview and is inert to pointer and keyboard input. The callback receives `connection`, `pathData`, `isValid`, `sourcePoint`, `targetPoint`, `sourceDirection`, and `targetDirection`. Points are in canvas coordinates. The source point is the gesture source port center, with the starting point as fallback. The target point is the hovered port center, with the pointer point as fallback. Directions use port sides when present, then routed directions. The gesture origin remains the source even when the resulting edge direction is reversed.
+
 Custom node and edge renderers should branch on the application-defined `entity.kind`. Keep `entity.type` as the structural `"node"` or `"edge"` discriminant so core selection, drag, connection, and CRUD behavior remains valid.
 
 For controlled reconnect gestures, `reconnectMode({ commit: false, preview: false })` keeps Flow's input lifecycle while suppressing the adapter's projected preview edge, so an external domain store can render its own temporary geometry without duplicate paths.
@@ -89,11 +138,11 @@ For controlled reconnect gestures, `reconnectMode({ commit: false, preview: fals
 
 <!-- namespaced selector roles and entity state attributes from src/StatelyFlow.tsx -->
 
-`StatelyFlow` exposes stable, namespaced selector roles while keeping `data-flow-*` attributes authoritative: `.stately-flow` / `.stately-flow__pane` (interactive root), `.stately-flow__viewport` (transformed canvas), `.stately-flow__edges`, `.stately-flow__nodes`, `.stately-flow__edge-labels`, `.stately-flow__selection-bounds`, their singular entity classes, `.stately-flow__background`, `.stately-flow__viewport-layer`, `.stately-flow__pane-layer`, and `.stately-flow__overlays`. Consumer `className` values are merged with these roles. Focus presentation is consumer-owned and visually off by default: set `--flow-focus-outline` or target `:focus-visible` for browser focus, and use `[data-flow-focused="true"]` for synchronized Flow focus state.
+`StatelyFlow` exposes stable, namespaced selector roles while keeping `data-flow-*` attributes authoritative: `.stately-flow` / `.stately-flow__pane` (interactive root), `.stately-flow__viewport` (transformed canvas), `.stately-flow__edges`, `.stately-flow__nodes`, `.stately-flow__edge-labels`, `.stately-flow__selection-bounds`, their singular entity classes, `.stately-flow__background`, `.stately-flow__viewport-layer`, `.stately-flow__pane-layer`, and `.stately-flow__overlays`. Consumer `className` values are merged with these roles. When Flow clears entity focus, the adapter blurs the directly focused node, edge, or inspection port. Child controls and unrelated focused elements retain browser focus. Focus presentation is consumer-owned and visually off by default: set `--flow-focus-outline` or target `:focus-visible` for browser focus, and use `[data-flow-focused="true"]` for synchronized Flow focus state.
 
 Use `rootRef` and `rootProps` to access that input-owned root or attach ordinary div attributes and events such as context menu, double-click, and drag/drop. `rootProps.className` and `rootProps.style` merge with the top-level values; Flow's input runtime remains the sole gesture owner.
 
-Keyboard handling is scoped to the `StatelyFlow` root by default so multiple flows on one page do not all receive Delete/undo/arrow keys. Pass `keyboardTarget="window"` to restore global handling. Pass `settings={{ keymap }}` to rebind built-in shortcuts. Double-click zoom is enabled in the default input modes; Shift double-click zooms out.
+Keyboard handling is scoped to the `StatelyFlow` root by default so multiple flows on one page do not all receive Delete/undo/arrow keys. Pass `keyboardTarget="window"` to restore global handling. Pass `settings={{ keymap }}` to rebind built-in shortcuts. Double-click zoom is enabled in the default input modes; Shift double-click zooms out. Compose `keyboardMode` and `keyboardNavMode` to configure activation, selection, and Escape behavior. See [core input policies](../flow/README.md#input-policies).
 
 Alignment and equal-spacing guides stay a constant screen size across zoom and expose `--flow-snap-line-color` and `--flow-spacing-guide-color` for theming. Equal-spacing guides include their rounded canvas distance.
 

package/dist/esm/index.d.ts

@@ -1,6 +1,6 @@
 import { Background, BackgroundProps, BackgroundVariant, CrossBackground, DotsBackground, LinesBackground } from "./backgrounds.js";
 import { FlowView, ResolvedFlowColorMode } from "@statelyai/flow-dom";
-import { ActiveGraphProjection, AnchorSpec, ConnectionEndedEvent, ConnectionState, CreateEdgeInput, CreateFlowOptions, EdgePathData, FitViewExclusionSide, FlowColorMode, FlowCommitEvent, FlowConnection, FlowController, FlowEdge, FlowGraph, FlowInputMode, FlowKeymap, FlowNode, FlowProfile, FlowStoreContext, GraphEdgeAttrs, GraphNodeAttrs, LayoutRequestedEvent, Point, Rect, ResolvedFlowAppearance, Viewport, VisualPort } from "@statelyai/flow";
+import { ActiveGraphProjection, AnchorSpec, ConnectionEndedEvent, ConnectionState, CreateEdgeInput, CreateFlowOptions, Direction, EdgePathData, FitViewExclusionSide, FlowColorMode, FlowCommitEvent, FlowConnection, FlowController, FlowEdge, FlowGraph, FlowInputMode, FlowKeymap, FlowNode, FlowProfile, FlowStoreContext, GraphEdgeAttrs, GraphNodeAttrs, LayoutRequestedEvent, Point, Rect, ResolvedFlowAppearance, Viewport, VisualPort } from "@statelyai/flow";
 import { CSSProperties, ComponentPropsWithoutRef, HTMLAttributes, ReactNode, Ref, RefCallback, RefObject } from "react";
 export * from "@statelyai/flow-dom";
 //#region src/createFlowInstance.d.ts
@@ -78,7 +78,7 @@ type UseFlowOptions<TNodeData = any, TEdgeData = any, TLabelData = any> = UseCre
  * Create one Flow instance for a component lifetime.
  *
  * Creation settings are initial-only; use `flow.configure()` for runtime
- * changes. Event/listener props are rebound when their identities change.
+ * changes. Event callbacks stay current; selector listeners rebind on change.
  */
 declare function useFlow<TNodeData = any, TEdgeData = any, TLabelData = any>(options: UseFlowOptions<TNodeData, TEdgeData, TLabelData>): FlowInstance<TNodeData, TEdgeData, TLabelData>;
 /** @deprecated Use `useFlow(options)`. */
@@ -140,9 +140,8 @@ type UseFlowInputOptions = {
    * Input modes, or a resolver from store context. Defaults to the store
    * profile's input modes (when a profile is given) and otherwise to the
    * core default set, which follows the store's `context.mode`
-   * (interactive / readonly). Initial-only: changes after mount are ignored —
-   * swap behavior at runtime via `flow.internals.store.trigger.setMode(...)` or a
-   * context-aware resolver.
+   * (interactive / readonly). Changes apply to new gestures without cancelling
+   * a gesture already in progress.
    */
   modes?: FlowInputMode[] | ((context: FlowStoreContext) => FlowInputMode[]);
   /** Store profile whose per-mode `input.modes` drive the runtime. */
@@ -201,6 +200,12 @@ type RenderConnectionLineProps = {
   connection: ConnectionState;
   pathData: EdgePathData;
   isValid: boolean;
+  /** Current gesture source port center, or its starting canvas point. */
+  sourcePoint: Point;
+  /** Hovered target port center, or the current pointer canvas point. */
+  targetPoint: Point;
+  sourceDirection: Direction;
+  targetDirection: Direction;
 };
 type StatelyFlowStyle = CSSProperties | (CSSProperties & {
   [customProperty: `--${string}`]: string | number | undefined;
@@ -235,7 +240,8 @@ type StatelyFlowBaseProps<TNodeData = unknown, TEdgeData = unknown> = {
    */
   onlyRenderVisible?: boolean;
   /**
-   * Override the input modes driving gestures (initial-only). Defaults to
+   * Override the input modes driving gestures. Updates apply to new gestures
+   * without cancelling the current one. Defaults to
    * the store profile's input modes when `settings.store.profile` is set,
    * otherwise to the core defaults. Example — custom connection validity:
    *
@@ -405,7 +411,7 @@ type EntityAnchorProps = EntityAnchorBaseProps & ({
 declare function EntityAnchor(props: EntityAnchorProps): import("react").JSX.Element | null;
 //#endregion
 //#region src/Port.d.ts
-type PortProps = {
+type PortProps = ComponentPropsWithoutRef<"div"> & {
   name: string;
   /**
    * `inspect` makes a graph-owned port focusable/selectable without starting
@@ -427,9 +433,6 @@ type PortProps = {
    * feedback loop and runs away.
    */
   measured?: boolean;
-  className?: string;
-  style?: CSSProperties;
-  children?: ReactNode;
 };
 /**
  * A connection port. Purely declarative: it renders the
@@ -441,7 +444,29 @@ type PortProps = {
  * observe results via `flow.on("connectionEnded", …)` or the store's
  * `connection` state.
  */
-declare function Port(props: PortProps): import("react").JSX.Element | null;
+declare const Port: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+  name: string;
+  /**
+   * `inspect` makes a graph-owned port focusable/selectable without starting
+   * a connection. Defaults to `connect`.
+   */
+  interaction?: "connect" | "inspect";
+  /**
+   * Whether the DOM element reports its bounds back to the graph (default
+   * true). Ports are unidirectional, one way or the other:
+   *
+   * - DOM-owned (default): position the element with your own CSS (offsets,
+   *   percentages, flex…) — NEVER from `port.x`/`port.y` — and the graph's
+   *   port geometry follows the DOM.
+   * - Graph-owned (`measured={false}`): position the element FROM
+   *   `port.x`/`port.y` (layout results, "virtual" ports) and nothing is
+   *   written back.
+   *
+   * Mixing the two (positioning from `port.x` while measuring) creates a
+   * feedback loop and runs away.
+   */
+  measured?: boolean;
+} & import("react").RefAttributes<HTMLDivElement>>;
 //#endregion
 //#region src/DragHandle.d.ts
 type DragHandleProps = HTMLAttributes<HTMLDivElement> & {
@@ -488,7 +513,7 @@ declare function DragHandle({ children, style, ...rest }: DragHandleProps): impo
  * - `data-flow-selection-bounds` — the established multi-selection frame.
  */
 declare const FLOW_BASE_STYLES_ID = "flow-base-styles";
-declare const FLOW_BASE_CSS = "\n[data-flow-root] {\n  --flow-selection-color: #2563eb;\n  --flow-selection-bg: rgba(37, 99, 235, 0.12);\n  --flow-selection-bounds-outset: 1px;\n  --flow-layer-edges: 0;\n  --flow-layer-entities: 10;\n  --flow-layer-labels: 20;\n  --flow-layer-interaction: 30;\n  --flow-layer-guides: 40;\n  --flow-layer-chrome: 50;\n  touch-action: none;\n}\n\n[data-flow-root]:focus {\n  outline: var(--flow-focus-outline, none);\n}\n\n[data-flow-interactive-when-selected] {\n  pointer-events: none;\n}\n[data-flow-selected=\"true\"] [data-flow-interactive-when-selected] {\n  pointer-events: auto;\n}\n\n[data-flow-custom-node] :where(\n  button,\n  input,\n  select,\n  textarea,\n  a[href],\n  [role=\"button\"],\n  [tabindex],\n  [data-flow-drag-handle],\n  [data-flow-port-name]\n) {\n  pointer-events: auto;\n}\n\n[data-flow-selection-box] {\n  position: absolute;\n  box-sizing: border-box;\n  border: calc(1px / var(--flow-zoom, 1)) solid var(--flow-selection-color);\n  border-radius: 0;\n  background: var(--flow-selection-bg);\n  pointer-events: none;\n}\n\n[data-flow-selection-bounds] {\n  position: absolute;\n  box-sizing: border-box;\n  outline: calc(1px / var(--flow-zoom, 1)) solid var(--flow-selection-color);\n  outline-offset: calc(var(--flow-selection-bounds-outset) / var(--flow-zoom, 1));\n  border-radius: 0;\n  pointer-events: none;\n}\n";
+declare const FLOW_BASE_CSS = "\n[data-flow-root] {\n  --flow-selection-color: #2563eb;\n  --flow-selection-bg: rgba(37, 99, 235, 0.12);\n  --flow-selection-bounds-outset: 1px;\n  --flow-layer-edges: 0;\n  --flow-layer-entities: 10;\n  --flow-layer-labels: 20;\n  --flow-layer-interaction: 30;\n  --flow-layer-guides: 40;\n  --flow-layer-chrome: 50;\n  touch-action: none;\n}\n\n[data-flow-root]:focus {\n  outline: var(--flow-focus-outline, none);\n}\n\n[data-flow-layer=\"pane\"]:empty {\n  display: none;\n}\n\n[data-flow-connection-preview],\n[data-flow-connection-preview] * {\n  pointer-events: none !important;\n}\n\n[data-flow-interactive-when-selected] {\n  pointer-events: none;\n}\n[data-flow-selected=\"true\"] [data-flow-interactive-when-selected] {\n  pointer-events: auto;\n}\n\n[data-flow-custom-node] :where(\n  button,\n  input,\n  select,\n  textarea,\n  a[href],\n  [role=\"button\"],\n  [tabindex],\n  [data-flow-drag-handle],\n  [data-flow-port-name]\n) {\n  pointer-events: auto;\n}\n\n[data-flow-selection-box] {\n  position: absolute;\n  box-sizing: border-box;\n  border: calc(1px / var(--flow-zoom, 1)) solid var(--flow-selection-color);\n  border-radius: 0;\n  background: var(--flow-selection-bg);\n  pointer-events: none;\n}\n\n[data-flow-selection-bounds] {\n  position: absolute;\n  box-sizing: border-box;\n  outline: calc(1px / var(--flow-zoom, 1)) solid var(--flow-selection-color);\n  outline-offset: calc(var(--flow-selection-bounds-outset) / var(--flow-zoom, 1));\n  border-radius: 0;\n  pointer-events: none;\n}\n";
 /** Inject the base stylesheet once per document (deduped by element id). */
 declare function useFlowBaseStyles(): void;
 //#endregion
@@ -505,4 +530,29 @@ declare function useFlowColorMode(): {
 };
 declare function useApplyFlowColorMode(element: HTMLElement | null): void;
 //#endregion
-export { Background, type BackgroundProps, type BackgroundVariant, Controls, type ControlsProps, type CreateFlowInstanceOptions, CrossBackground, DotsBackground, DragHandle, type DragHandleProps, EntityAnchor, type EntityAnchorAlign, type EntityAnchorPoint, type EntityAnchorProps, type EntityAnchorSide, FLOW_BASE_CSS, FLOW_BASE_STYLES_ID, FlowColorModeScope, type FlowColorModeScopeProps, type FlowEdgeBinding, type FlowEventListeners, type FlowInstance, FlowInstanceProvider, type FlowInstanceSettings, type FlowNodeBinding, type FlowPortBinding, type FlowSelector, type FlowSelectorEquality, type FlowStoreListener, FlowToolbar, type FlowToolbarProps, type FlowToolbarState, LinesBackground, MiniMap, type MiniMapProps, PanePortal, Panel, type PanelPosition, type PanelProps, Port, type PortProps, type ReactActiveGraphProjection, type ReactAppearanceRenderers, type ReactGraphEdgeAttrs, type ReactGraphNodeAttrs, type RenderConnectionLineProps, type RenderEdgeLabelProps, type RenderEdgeProps, type RenderNodeProps, StatelyFlow, type StatelyFlowProps, type StatelyFlowRootProps, type StatelyFlowStyle, type UseCreateFlowInstanceOptions, type UseFitViewExclusionOptions, type UseFlowInputOptions, type UseFlowOptions, type UseFlowToolbarOptions, ViewportPortal, createFlowInstance, useApplyFlowColorMode, useConnection, useCreateFlowInstance, useFitViewExclusion, useFlow, useFlowBaseStyles, useFlowColorMode, useFlowConnections, useFlowContext, useFlowEdge, useFlowEntity, useFlowInput, useFlowInstance, useFlowMeasurement, useFlowNode, useFlowPort, useFlowSelector, useFlowToolbar, useFlowValue, useFlowView, useFlowViewport, useKeyPress, useMeasuredSize, useNodesInitialized, useOptionalFlowInstance };
+//#region src/EdgePrimitives.d.ts
+type EdgePathProps = Omit<ComponentPropsWithoutRef<"path">, "d"> & {
+  pathData: EdgePathData;
+};
+/** Paint routed segments while Flow updates their geometry during gestures. */
+declare function EdgePath({ pathData, ...props }: EdgePathProps): import("react").JSX.Element;
+type EdgeEndpointProps = Omit<ComponentPropsWithoutRef<"circle">, "cx" | "cy" | "r" | "offset"> & {
+  edgeId: string;
+  pathData: EdgePathData;
+  end: "source" | "target";
+  /** Reconnection hit radius in canvas units. Defaults to 10. */
+  radius?: number;
+  /** Reconnection hit offset from the route endpoint in canvas units. */
+  offset?: Point;
+};
+declare const EdgeEndpoint: import("react").ForwardRefExoticComponent<Omit<Omit<import("react").SVGProps<SVGCircleElement>, "ref">, "cx" | "cy" | "offset" | "r"> & {
+  edgeId: string;
+  pathData: EdgePathData;
+  end: "source" | "target";
+  /** Reconnection hit radius in canvas units. Defaults to 10. */
+  radius?: number;
+  /** Reconnection hit offset from the route endpoint in canvas units. */
+  offset?: Point;
+} & import("react").RefAttributes<SVGCircleElement>>;
+//#endregion
+export { Background, type BackgroundProps, type BackgroundVariant, Controls, type ControlsProps, type CreateFlowInstanceOptions, CrossBackground, DotsBackground, DragHandle, type DragHandleProps, EdgeEndpoint, type EdgeEndpointProps, EdgePath, type EdgePathProps, EntityAnchor, type EntityAnchorAlign, type EntityAnchorPoint, type EntityAnchorProps, type EntityAnchorSide, FLOW_BASE_CSS, FLOW_BASE_STYLES_ID, FlowColorModeScope, type FlowColorModeScopeProps, type FlowEdgeBinding, type FlowEventListeners, type FlowInstance, FlowInstanceProvider, type FlowInstanceSettings, type FlowNodeBinding, type FlowPortBinding, type FlowSelector, type FlowSelectorEquality, type FlowStoreListener, FlowToolbar, type FlowToolbarProps, type FlowToolbarState, LinesBackground, MiniMap, type MiniMapProps, PanePortal, Panel, type PanelPosition, type PanelProps, Port, type PortProps, type ReactActiveGraphProjection, type ReactAppearanceRenderers, type ReactGraphEdgeAttrs, type ReactGraphNodeAttrs, type RenderConnectionLineProps, type RenderEdgeLabelProps, type RenderEdgeProps, type RenderNodeProps, StatelyFlow, type StatelyFlowProps, type StatelyFlowRootProps, type StatelyFlowStyle, type UseCreateFlowInstanceOptions, type UseFitViewExclusionOptions, type UseFlowInputOptions, type UseFlowOptions, type UseFlowToolbarOptions, ViewportPortal, createFlowInstance, useApplyFlowColorMode, useConnection, useCreateFlowInstance, useFitViewExclusion, useFlow, useFlowBaseStyles, useFlowColorMode, useFlowConnections, useFlowContext, useFlowEdge, useFlowEntity, useFlowInput, useFlowInstance, useFlowMeasurement, useFlowNode, useFlowPort, useFlowSelector, useFlowToolbar, useFlowValue, useFlowView, useFlowViewport, useKeyPress, useMeasuredSize, useNodesInitialized, useOptionalFlowInstance };

package/dist/esm/index.js

@@ -1,7 +1,7 @@
 import { a as FlowInstanceProvider, i as LinesBackground, n as CrossBackground, o as useFlowInstance, r as DotsBackground, s as useOptionalFlowInstance, t as Background } from "./backgrounds2.js";
 import { applyFlowColorMode, attachContainer, attachInput, attachViewportTransform, clientToCanvas, computeRenderableIds, createEntityGeometryObserver, createFlowView, createMeasurementObserver, nodePositionStyle, observeAppearanceBounds, renderableIdsEqual, resolveFlowColorMode, viewportStyle } from "@statelyai/flow-dom";
-import { CONNECTION_PREVIEW_EDGE_ID, appearanceMeasurementId, areNodesMeasured, createConnectionPreviewGraph, createEntityChangeNotifier, createFlow, createFlowInputRuntime, getAnchorTransform, getAutoPanDelta, getMinimapProjection, getMinimapViewportCenter, getProjectedEdgeAttrs, getProjectedNodeAttrs, getToolbarPlacement, getVisibleBounds, markerToSVG, pathToSVG, profileModesForContext, profilePoliciesForContext, viewportCenteredOn } from "@statelyai/flow";
-import { Fragment, createContext, memo, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { CONNECTION_PREVIEW_EDGE_ID, appearanceMeasurementId, areNodesMeasured, createConnectionPreviewGraph, createEntityChangeNotifier, createFlow, createFlowInputRuntime, defaultModesForContext, getAnchorTransform, getAutoPanDelta, getMinimapProjection, getMinimapViewportCenter, getProjectedEdgeAttrs, getProjectedNodeAttrs, getToolbarPlacement, getVisibleBounds, markerToSVG, pathToSVG, profileModesForContext, profilePoliciesForContext, viewportCenteredOn } from "@statelyai/flow";
+import { Fragment, createContext, forwardRef, memo, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
 import { createPortal } from "react-dom";
@@ -79,7 +79,7 @@ function createFlowInstance(options) {
 * Create one Flow instance for a component lifetime.
 *
 * Creation settings are initial-only; use `flow.configure()` for runtime
-* changes. Event/listener props are rebound when their identities change.
+* changes. Event callbacks stay current; selector listeners rebind on change.
 */
 function useFlow(options) {
 	return useCreateFlowInstance(options);
@@ -87,56 +87,66 @@ function useFlow(options) {
 /** @deprecated Use `useFlow(options)`. */
 function useCreateFlowInstance(options) {
 	const instanceRef = useRef(null);
-	const listenersRef = useRef(options.listeners);
-	const eventsRef = useRef(options.events);
 	const lifecycleRef = useRef(0);
-	listenersRef.current = options.listeners;
-	eventsRef.current = options.events;
 	if (!instanceRef.current) instanceRef.current = createFlowInstance({
 		initialGraph: options.initialGraph,
 		settings: options.settings
 	});
 	const flow = instanceRef.current;
+	useFlowSubscriptions(flow, options);
+	useEffect(() => {
+		const lifecycle = lifecycleRef;
+		const generation = ++lifecycle.current;
+		return () => {
+			queueMicrotask(() => {
+				if (lifecycle.current !== generation) return;
+				lifecycle.current++;
+				flow.destroy();
+			});
+		};
+	}, [flow]);
+	return flow;
+}
+function useFlowSubscriptions(flow, options) {
+	const callbacks = useRef(options);
+	useLayoutEffect(() => {
+		callbacks.current = options;
+	});
+	const hasConnectionEnded = Boolean(options.events?.connectionEnded);
+	const hasLayoutRequested = Boolean(options.events?.layoutRequested);
+	const hasCommit = Boolean(options.events?.commit || options.onCommit);
 	useEffect(() => {
 		const cleanup = [];
-		if (eventsRef.current?.connectionEnded) {
-			const subscription = flow.on("connectionEnded", eventsRef.current.connectionEnded);
-			cleanup.push(() => subscription.unsubscribe());
-		}
-		if (eventsRef.current?.layoutRequested) {
-			const subscription = flow.on("layoutRequested", eventsRef.current.layoutRequested);
+		if (hasConnectionEnded) {
+			const subscription = flow.on("connectionEnded", (event) => callbacks.current.events?.connectionEnded?.(event));
 			cleanup.push(() => subscription.unsubscribe());
 		}
-		if (eventsRef.current?.commit) {
-			const subscription = flow.on("commit", eventsRef.current.commit);
+		if (hasLayoutRequested) {
+			const subscription = flow.on("layoutRequested", (event) => callbacks.current.events?.layoutRequested?.(event));
 			cleanup.push(() => subscription.unsubscribe());
 		}
-		if (options.onCommit) {
-			const subscription = flow.on("commit", options.onCommit);
+		if (hasCommit) {
+			const subscription = flow.on("commit", (event) => {
+				callbacks.current.events?.commit?.(event);
+				callbacks.current.onCommit?.(event);
+			});
 			cleanup.push(() => subscription.unsubscribe());
 		}
-		for (const listener of listenersRef.current ?? []) cleanup.push(flow.listen(listener.selector, listener.onChange, listener));
 		return () => {
-			for (const dispose of cleanup) dispose();
+			for (const unsubscribe of cleanup) unsubscribe();
 		};
 	}, [
 		flow,
-		options.listeners,
-		options.events,
-		options.onCommit
+		hasConnectionEnded,
+		hasLayoutRequested,
+		hasCommit
 	]);
 	useEffect(() => {
-		const lifecycle = lifecycleRef;
-		const generation = ++lifecycle.current;
+		const cleanup = options.listeners?.map((listener) => flow.listen(listener.selector, listener.onChange, listener));
 		return () => {
-			queueMicrotask(() => {
-				if (lifecycle.current !== generation) return;
-				lifecycle.current++;
-				flow.destroy();
-			});
+			for (const unsubscribe of cleanup ?? []) unsubscribe();
 		};
-	}, [flow]);
-	return flow;
+	}, [flow, options.listeners]);
 }
 /** Subscribe to a derived slice of Flow context with optional equality. */
 function useFlowSelector(selector, options = {}) {
@@ -303,6 +313,9 @@ function getDerivedFields(context, id, props) {
 */
 function useFlowInput(flow, containerRef, options = {}) {
 	const { modes, profile, keyboardTarget, keymap } = options;
+	const modesRef = useRef(modes);
+	const runtimeRef = useRef(null);
+	modesRef.current = modes;
 	const effectiveKeymap = keymap ?? flow.inputSettings?.keymap;
 	const keymapKey = effectiveKeymap ? JSON.stringify(effectiveKeymap) : void 0;
 	const keymapRef = useRef(effectiveKeymap);
@@ -314,25 +327,36 @@ function useFlowInput(flow, containerRef, options = {}) {
 		const runtime = createFlowInputRuntime({
 			store: flow.internals.store,
 			engine: flow.internals.engine,
-			modes: modes ?? (profile ? profileModesForContext(profile) : void 0),
+			modes: (context) => {
+				const activeModes = modesRef.current;
+				if (activeModes) return typeof activeModes === "function" ? activeModes(context) : activeModes;
+				return profile ? profileModesForContext(profile)(context) : defaultModesForContext(context, activeKeymap);
+			},
 			policies: profile ? profilePoliciesForContext(profile) : void 0,
 			...activeKeymap ? { keymap: activeKeymap } : {}
 		});
-		return attachInput({
+		runtimeRef.current = runtime;
+		const detach = attachInput({
 			container,
 			store: flow.internals.store,
 			runtime,
 			keyboardTarget,
 			autoPan: getAutoPanDelta
 		});
+		return () => {
+			runtimeRef.current = null;
+			detach();
+		};
 	}, [
 		flow,
 		containerRef,
-		modes,
 		profile,
 		keyboardTarget,
 		keymapKey
 	]);
+	useEffect(() => {
+		runtimeRef.current?.reconcileModes();
+	}, [modes]);
 }
 //#endregion
 //#region src/MeasurementContext.tsx
@@ -431,6 +455,15 @@ const FLOW_BASE_CSS = `
   outline: var(--flow-focus-outline, none);
 }
 
+[data-flow-layer="pane"]:empty {
+  display: none;
+}
+
+[data-flow-connection-preview],
+[data-flow-connection-preview] * {
+  pointer-events: none !important;
+}
+
 [data-flow-interactive-when-selected] {
   pointer-events: none;
 }
@@ -502,6 +535,14 @@ function clearEntityFocusOnBlur(flow, entityId, event) {
 	if (nextTarget instanceof Node && event.currentTarget.contains(nextTarget)) return;
 	if (flow.getSnapshot().focusedEntityId === entityId) flow.internals.store.trigger.clearFocus();
 }
+function blurClearedEntityFocus(root, previousId, nextId) {
+	if (!previousId || nextId !== null) return;
+	const active = root.ownerDocument.activeElement;
+	const view = root.ownerDocument.defaultView;
+	if (!view || !(active instanceof view.HTMLElement || active instanceof view.SVGElement) || !root.contains(active)) return;
+	if (!active.matches(".stately-flow__node, .stately-flow__edge, [data-flow-port-interaction=\"inspect\"]")) return;
+	if ((active.getAttribute("data-flow-port-id") ?? active.getAttribute("data-entity-id")) === previousId) active.blur();
+}
 //#endregion
 //#region src/LayerPortals.tsx
 const FlowLayerTargetsContext = createContext(null);
@@ -625,10 +666,7 @@ function StatelyFlow(props) {
 function OwnedStatelyFlow(props) {
 	const flow = useFlow({
 		initialGraph: props.initialGraph,
-		settings: props.settings,
-		listeners: props.listeners,
-		events: props.events,
-		onCommit: props.onCommit
+		settings: props.settings
 	});
 	return /* @__PURE__ */ jsx(StatelyFlowView, {
 		...props,
@@ -636,6 +674,7 @@ function OwnedStatelyFlow(props) {
 	});
 }
 function StatelyFlowView(props) {
+	useFlowSubscriptions(props.flow, props);
 	const containerRef = useRef(null);
 	const [rootLayer, setRootLayer] = useState(null);
 	const setContainerRef = useCallback((element) => {
@@ -661,6 +700,9 @@ function StatelyFlowView(props) {
 		measurementObserver.disconnect();
 		geometryObserver.disconnect();
 	}, [geometryObserver, measurementObserver]);
+	useLayoutEffect(() => props.flow.subscribe((context) => context.focusedEntityId, (nextId, previousId) => {
+		if (containerRef.current) blurClearedEntityFocus(containerRef.current, previousId, nextId);
+	}), [props.flow]);
 	useViewportTransform(viewportRef, props.flow);
 	useFlowBaseStyles();
 	const projections = useActiveProjections(props.flow, props.projections);
@@ -733,7 +775,6 @@ function StatelyFlowView(props) {
 									/* @__PURE__ */ jsx(EdgeLayer, {
 										geometryObserver,
 										renderEdge: props.renderEdge,
-										renderConnectionLine: props.renderConnectionLine,
 										projections,
 										onlyRenderVisible: props.onlyRenderVisible
 									}),
@@ -744,6 +785,11 @@ function StatelyFlowView(props) {
 										projections,
 										onlyRenderVisible: props.onlyRenderVisible
 									}),
+									/* @__PURE__ */ jsx(ConnectionPreviewEdge, {
+										flow: props.flow,
+										renderEdge: props.renderEdge,
+										renderConnectionLine: props.renderConnectionLine
+									}),
 									/* @__PURE__ */ jsx(SnapLinesLayer, {}),
 									/* @__PURE__ */ jsx(EdgeLabelLayer, {
 										geometryObserver,
@@ -995,7 +1041,7 @@ function EdgeLayer(props) {
 			overflow: "visible",
 			pointerEvents: "none"
 		},
-		children: [/* @__PURE__ */ jsx(DefaultMarkerDefinitions, { prefix: markerPrefix }), /* @__PURE__ */ jsxs("g", { children: [edgeIds.map((id) => {
+		children: [/* @__PURE__ */ jsx(DefaultMarkerDefinitions, { prefix: markerPrefix }), /* @__PURE__ */ jsx("g", { children: edgeIds.map((id) => {
 			if (renderableIds && !renderableIds.edgeIds.has(id)) return null;
 			return /* @__PURE__ */ jsx(EdgeView, {
 				flow: instance,
@@ -1005,12 +1051,7 @@ function EdgeLayer(props) {
 				renderEdge,
 				markerPrefix
 			}, id);
-		}), /* @__PURE__ */ jsx(ConnectionPreviewEdge, {
-			flow: instance,
-			renderEdge,
-			renderConnectionLine: props.renderConnectionLine,
-			markerPrefix
-		})] })]
+		}) })]
 	});
 }
 const EdgeView = memo(function EdgeView(props) {
@@ -1053,8 +1094,7 @@ const EdgeView = memo(function EdgeView(props) {
 	const focusProps = {
 		role: "group",
 		"aria-roledescription": "flow edge",
-		"aria-label": props.flow.internals.engine.getAriaLabel(props.id),
-		"aria-selected": selected,
+		"aria-label": props.flow.internals.engine.getAriaLabel(props.id) + (selected ? ", selected" : ""),
 		tabIndex: focusable ? 0 : void 0,
 		onFocus: (event) => {
 			if (descendantOwnsFlowFocus(event)) return;
@@ -1106,34 +1146,59 @@ const EdgeView = memo(function EdgeView(props) {
 });
 /** The in-progress connection gesture's preview edge (renders only mid-gesture). */
 function ConnectionPreviewEdge(props) {
-	const connection = useFlowSelector((context) => context.connection);
+	const markerPrefix = `stately-flow-preview-${useId().replace(/[^a-zA-Z0-9_-]/g, "")}`;
+	const connection = useFlowSelector((context) => context.connection?.active ? context : null)?.connection;
 	if (!connection?.active || connection.preview === false) return null;
 	const previewGraph = createConnectionPreviewGraph(props.flow.getSnapshot().graph, connection);
 	const pathData = props.flow.getAllEdgePaths({ graph: previewGraph }).get(CONNECTION_PREVIEW_EDGE_ID);
 	const edge = previewGraph.edges.find((candidate) => candidate.id === CONNECTION_PREVIEW_EDGE_ID);
 	if (!edge || !pathData) return null;
-	return /* @__PURE__ */ jsx("g", {
-		style: { pointerEvents: "none" },
-		children: props.renderConnectionLine ? props.renderConnectionLine({
-			connection,
-			pathData,
-			isValid: connection.isValid
-		}) : props.renderEdge ? props.renderEdge({
-			flow: props.flow,
-			edge,
-			pathData,
-			attrs: {},
-			selected: false,
-			hovered: false,
-			highlights: []
-		}) : /* @__PURE__ */ jsx(DefaultEdge, {
-			flow: props.flow,
-			edge,
-			pathData,
-			attrs: {},
-			selected: false,
-			markerPrefix: props.markerPrefix,
-			preview: true
+	return /* @__PURE__ */ jsx("div", {
+		ref: (element) => {
+			element?.setAttribute("inert", "");
+		},
+		"aria-hidden": "true",
+		className: "stately-flow__connection-preview",
+		"data-flow-connection-preview": "",
+		"data-flow-canvas-layer": "",
+		style: {
+			position: "absolute",
+			inset: 0,
+			zIndex: "var(--flow-layer-interaction, 30)",
+			pointerEvents: "none"
+		},
+		children: /* @__PURE__ */ jsxs("svg", {
+			style: {
+				width: "100%",
+				height: "100%",
+				overflow: "visible",
+				pointerEvents: "none"
+			},
+			children: [/* @__PURE__ */ jsx(DefaultMarkerDefinitions, { prefix: markerPrefix }), props.renderConnectionLine ? props.renderConnectionLine({
+				connection,
+				pathData,
+				isValid: connection.isValid,
+				sourcePoint: connection.sourcePort ? props.flow.internals.engine.getPortPosition(connection.sourceId, connection.sourcePort) ?? connection.startPosition : connection.startPosition,
+				targetPoint: connection.targetId && connection.targetPort ? props.flow.internals.engine.getPortPosition(connection.targetId, connection.targetPort) ?? connection.pointerPosition : connection.pointerPosition,
+				sourceDirection: props.flow.getNode(connection.sourceId)?.ports?.find((port) => port.name === connection.sourcePort)?.side ?? pathData.segments[0]?.sourceDirection ?? "right",
+				targetDirection: (connection.targetId ? props.flow.getNode(connection.targetId)?.ports?.find((port) => port.name === connection.targetPort)?.side : void 0) ?? pathData.segments.at(-1)?.targetDirection ?? "left"
+			}) : props.renderEdge ? props.renderEdge({
+				flow: props.flow,
+				edge,
+				pathData,
+				attrs: {},
+				selected: false,
+				hovered: false,
+				highlights: []
+			}) : /* @__PURE__ */ jsx(DefaultEdge, {
+				flow: props.flow,
+				edge,
+				pathData,
+				attrs: {},
+				selected: false,
+				markerPrefix,
+				preview: true
+			})]
 		})
 	});
 }
@@ -1548,7 +1613,8 @@ const NodeView = memo(function NodeView(props) {
 		props.id,
 		props.observer,
 		props.flow,
-		hidden
+		hidden,
+		node?.group?.type
 	]);
 	useLayoutEffect(() => {
 		const element = ref.current;
@@ -1590,7 +1656,6 @@ const NodeView = memo(function NodeView(props) {
 			className: classNames$1("stately-flow__node", attrs.className),
 			role: "group",
 			"aria-roledescription": "flow node",
-			"aria-selected": selected,
 			"aria-label": props.flow.internals.engine.getAriaLabel(props.id) + (selected ? ", selected" : ""),
 			tabIndex: focusable ? 0 : void 0,
 			onFocus: (event) => {
@@ -2329,17 +2394,30 @@ function classNames(...values) {
 * observe results via `flow.on("connectionEnded", …)` or the store's
 * `connection` state.
 */
-function Port(props) {
+const Port = forwardRef(function Port(props, forwardedRef) {
+	const { name, interaction: interactionProp, measured: measuredProp, onFocus, onBlur, ...nativeProps } = props;
 	const flow = useFlowInstance();
 	const { node } = useNodeRenderContext();
 	const ref = useRef(null);
+	const forwardedCleanup = useRef(void 0);
+	const setRef = useCallback((element) => {
+		const cleanup = forwardedCleanup.current;
+		forwardedCleanup.current = void 0;
+		cleanup?.();
+		ref.current = element;
+		if (typeof forwardedRef === "function") {
+			if (!element && cleanup) return;
+			const dispose = forwardedRef(element);
+			if (typeof dispose === "function") forwardedCleanup.current = dispose;
+		} else if (forwardedRef) forwardedRef.current = element;
+	}, [forwardedRef]);
 	const observerRef = useRef(null);
 	const observer = useMeasurementObserver();
-	const measured = props.measured ?? true;
-	const interaction = props.interaction ?? "connect";
-	const permitted = interaction !== "connect" || !flow.internals.engine.resolveAppearance(node).registered || flow.internals.engine.isPortAllowed(node, props.name);
-	const port = node.ports?.find((candidate) => candidate.name === props.name);
-	const portId = `${node.id}:${props.name}`;
+	const measured = measuredProp ?? true;
+	const interaction = interactionProp ?? "connect";
+	const permitted = interaction !== "connect" || !flow.internals.engine.resolveAppearance(node).registered || flow.internals.engine.isPortAllowed(node, name);
+	const port = node.ports?.find((candidate) => candidate.name === name);
+	const portId = `${node.id}:${name}`;
 	const focusable = flow.internals.engine.resolveEntityConfig(node).focusable;
 	const selected = useFlowSelector((context) => context.selection.has(portId), { flow });
 	useLayoutEffect(() => {
@@ -2348,7 +2426,7 @@ function Port(props) {
 		observerRef.current = observer;
 		observer.observe(element, {
 			nodeId: node.id,
-			portName: props.name
+			portName: name
 		});
 		return () => {
 			observerRef.current = null;
@@ -2357,7 +2435,7 @@ function Port(props) {
 	}, [
 		observer,
 		node.id,
-		props.name,
+		name,
 		measured,
 		permitted
 	]);
@@ -2370,32 +2448,38 @@ function Port(props) {
 	const candidate = useFlowSelector((context) => {
 		const connection = context.connection;
 		if (!connection?.active) return null;
-		if (connection.targetId !== node.id || connection.targetPort !== props.name) return null;
+		if (connection.targetId !== node.id || connection.targetPort !== name) return null;
 		return connection.isValid === false ? "invalid" : "valid";
 	}, { flow });
 	if (!permitted) return null;
 	return /* @__PURE__ */ jsx("div", {
-		ref,
-		className: props.className,
-		"data-flow-port-name": props.name,
+		role: interaction === "inspect" ? "button" : void 0,
+		"aria-label": interaction === "inspect" ? `${port?.label ?? name} port` : void 0,
+		"aria-pressed": interaction === "inspect" ? selected : void 0,
+		tabIndex: interaction === "inspect" && focusable ? 0 : void 0,
+		...nativeProps,
+		ref: setRef,
+		"data-flow-port-name": name,
 		"data-flow-node-id": node.id,
 		"data-flow-port-id": portId,
 		"data-flow-port-interaction": interaction,
 		"data-flow-selected": selected ? "true" : void 0,
 		"data-connection-candidate": candidate ?? void 0,
-		role: interaction === "inspect" ? "button" : void 0,
-		"aria-label": interaction === "inspect" ? `${port?.label ?? props.name} port` : void 0,
-		"aria-pressed": interaction === "inspect" ? selected : void 0,
-		tabIndex: interaction === "inspect" && focusable ? 0 : void 0,
-		onFocus: interaction === "inspect" && focusable ? () => flow.internals.store.trigger.focus({ entityId: portId }) : void 0,
-		onBlur: interaction === "inspect" ? (event) => clearEntityFocusOnBlur(flow, portId, event) : void 0,
+		onFocus: (event) => {
+			if (interaction === "inspect" && focusable) flow.internals.store.trigger.focus({ entityId: portId });
+			onFocus?.(event);
+		},
+		onBlur: (event) => {
+			if (interaction === "inspect") clearEntityFocusOnBlur(flow, portId, event);
+			onBlur?.(event);
+		},
 		style: {
 			pointerEvents: "auto",
 			...props.style
 		},
 		children: props.children
 	});
-}
+});
 //#endregion
 //#region src/DragHandle.tsx
 /**
@@ -2473,4 +2557,36 @@ function useApplyFlowColorMode(element) {
 	]);
 }
 //#endregion
-export { Background, Controls, CrossBackground, DotsBackground, DragHandle, EntityAnchor, FLOW_BASE_CSS, FLOW_BASE_STYLES_ID, FlowColorModeScope, FlowInstanceProvider, FlowToolbar, LinesBackground, MiniMap, PanePortal, Panel, Port, StatelyFlow, ViewportPortal, createFlowInstance, useApplyFlowColorMode, useConnection, useCreateFlowInstance, useFitViewExclusion, useFlow, useFlowBaseStyles, useFlowColorMode, useFlowConnections, useFlowContext, useFlowEdge, useFlowEntity, useFlowInput, useFlowInstance, useFlowMeasurement, useFlowNode, useFlowPort, useFlowSelector, useFlowToolbar, useFlowValue, useFlowView, useFlowViewport, useKeyPress, useMeasuredSize, useNodesInitialized, useOptionalFlowInstance };
+//#region src/EdgePrimitives.tsx
+/** Paint routed segments while Flow updates their geometry during gestures. */
+function EdgePath({ pathData, ...props }) {
+	return /* @__PURE__ */ jsx(Fragment$1, { children: pathData.segments.map((segment, index) => /* @__PURE__ */ jsx("path", {
+		fill: "none",
+		...props,
+		d: pathToSVG(segment),
+		"data-flow-edge-segment": index
+	}, index)) });
+}
+const EdgeEndpoint = forwardRef(function EdgeEndpoint({ edgeId, pathData, end, radius = 10, offset = {
+	x: 0,
+	y: 0
+}, ...props }, ref) {
+	const point = end === "source" ? pathData.segments[0]?.points[0] : pathData.segments.at(-1)?.points.at(-1);
+	if (!point) return null;
+	return /* @__PURE__ */ jsx("circle", {
+		fill: "transparent",
+		pointerEvents: "all",
+		...props,
+		ref,
+		"data-entity-id": edgeId,
+		"data-flow-part": `edge-endpoint:${end}`,
+		"data-flow-edge-endpoint": end,
+		"data-flow-edge-endpoint-offset-x": offset.x,
+		"data-flow-edge-endpoint-offset-y": offset.y,
+		cx: point.x + offset.x,
+		cy: point.y + offset.y,
+		r: radius
+	});
+});
+//#endregion
+export { Background, Controls, CrossBackground, DotsBackground, DragHandle, EdgeEndpoint, EdgePath, EntityAnchor, FLOW_BASE_CSS, FLOW_BASE_STYLES_ID, FlowColorModeScope, FlowInstanceProvider, FlowToolbar, LinesBackground, MiniMap, PanePortal, Panel, Port, StatelyFlow, ViewportPortal, createFlowInstance, useApplyFlowColorMode, useConnection, useCreateFlowInstance, useFitViewExclusion, useFlow, useFlowBaseStyles, useFlowColorMode, useFlowConnections, useFlowContext, useFlowEdge, useFlowEntity, useFlowInput, useFlowInstance, useFlowMeasurement, useFlowNode, useFlowPort, useFlowSelector, useFlowToolbar, useFlowValue, useFlowView, useFlowViewport, useKeyPress, useMeasuredSize, useNodesInitialized, useOptionalFlowInstance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/flow-react",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Thin React adapter for @statelyai/flow with core and DOM re-exports.",
   "type": "module",
   "sideEffects": false,
@@ -34,8 +34,8 @@
   "license": "MIT",
   "dependencies": {
     "use-sync-external-store": "^1.6.0",
-    "@statelyai/flow": "0.12.1",
-    "@statelyai/flow-dom": "3.5.1"
+    "@statelyai/flow": "0.13.1",
+    "@statelyai/flow-dom": "3.5.3"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",