@statelyai/flow-react 0.7.2 → 0.9.2

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, resize, and animated layout sessions, `@statelyai/flow-dom` batches node rectangles, edge paths, endpoint handles, and label positions into imperative animation-frame writes, so React commits only at transient-session boundaries. Default edge paths expose `data-flow-edge-segment`; custom edge renderers can use the same indexed attribute to join the imperative path updates. 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, edge paths, endpoint handles, label positions, and multi-selection bounds into imperative animation-frame writes, so React commits only at transient-session boundaries. Default edge paths expose `data-flow-edge-segment`; custom edge renderers can use the same indexed attribute to join the imperative path updates. 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`.
 
@@ -27,40 +27,41 @@ DOM measurement is one-directional. Nodes, ports, and edge labels report their r
 
 <!-- exported React adapter API from src/index.ts -->
 
-| Export                                | Description                                                                      |
-| ------------------------------------- | -------------------------------------------------------------------------------- |
-| `createFlowInstance(options)`         | Creates the shared instance used by React and custom renderers                   |
-| `useFlow(options)`                    | TipTap-style hook for creating a stable flow controller                          |
-| `useCreateFlowInstance(options)`      | Deprecated alias for `useFlow(options)`                                          |
-| `useFlowSelector(selector, options?)` | Subscribe to any part of the flow store from React                               |
-| `useFlowValue(selector, isEqual?)`    | Short selector hook for the nearest provider                                     |
-| `useFlowContext()`                    | Subscribe to the full flow store context                                         |
-| `useConnection()`                     | Subscribe to the active connection gesture state                                 |
-| `useFlowConnections(query)`           | Subscribe to stable, port-aware connections for one node                          |
-| `useFlowView()`                       | Access view-owned image export and measurement refresh                            |
-| `useKeyPress(keys)`                   | Track whether one or more keys are currently pressed                             |
-| `useNodesInitialized()`               | Check whether visible auto-size nodes have measurements                          |
-| `useFlowNode(id, selector?, isEqual?)` | Subscribe to node data plus derived render fields                               |
-| `useFlowEdge(id, selector?, isEqual?)` | Subscribe to edge data plus derived render fields                               |
-| `useFlowPort(id, selector?, isEqual?)` | Subscribe to port data plus derived render fields                               |
-| `useFlowViewport()`                   | Subscribe to viewport state                                                      |
-| `useFlowMeasurement(id)`              | Subscribe to measured bounds for an entity ref                                   |
-| `FlowInstanceProvider`                | Provides a `FlowInstance` through React context                                  |
-| `useFlowInstance()`                   | Reads the nearest `FlowInstance`                                                 |
-| `useOptionalFlowInstance()`           | Reads the nearest `FlowInstance` or returns `null`                               |
-| `StatelyFlow`                         | Convenience component that renders nodes, edges, backgrounds, projections, and overlays |
-| `createEntityGeometryObserver(store)` | Batches transient node/label rectangles and edge paths into imperative animation-frame DOM writes |
-| `PanePortal` / `ViewportPortal`       | Render custom content into fixed screen-coordinate or transformed canvas-coordinate layers |
-| `EntityAnchor`                       | Position custom controls on entity sides or free-standing canvas bounds with screen-stable offsets and inverse scaling |
-| `RenderEdgeLabelProps`                | Edge, path, bounds, interaction state, and projected attrs passed to `renderEdgeLabel` |
-| `Panel`                               | Positioned overlay panel for controls and custom UI                              |
-| `NodeResizer`                         | Resize handles for custom node renderers; constraints live on `node.resize`             |
-| `ReactActiveGraphProjection`          | React-typed active projection for `<StatelyFlow projections={...} />` or controller-owned projections |
-| `ReactGraphNodeAttrs` / `ReactGraphEdgeAttrs` | React-typed visual attrs exposed to custom node/edge renderers           |
-| `FlowColorModeScope`                  | Applies the current flow color mode as DOM data attributes and `color-scheme`    |
-| `useFlowColorMode()`                  | Reads the store color mode and resolves `system` to `light` or `dark`            |
-| `useApplyFlowColorMode(element)`      | Applies flow color mode attributes to an existing DOM element from inside a flow |
-| `FLOW_BASE_CSS` / `useFlowBaseStyles()` | Base data-attribute stylesheet injected by `StatelyFlow`                      |
+| Export                                        | Description                                                                                                             |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `createFlowInstance(options)`                 | Creates the shared instance used by React and custom renderers                                                          |
+| `useFlow(options)`                            | TipTap-style hook for creating a stable flow controller                                                                 |
+| `useCreateFlowInstance(options)`              | Deprecated alias for `useFlow(options)`                                                                                 |
+| `useFlowSelector(selector, options?)`         | Subscribe to any part of the flow store from React                                                                      |
+| `useFlowValue(selector, isEqual?)`            | Short selector hook for the nearest provider                                                                            |
+| `useFlowContext()`                            | Subscribe to the full flow store context                                                                                |
+| `useConnection()`                             | Subscribe to the active connection gesture state                                                                        |
+| `useFlowConnections(query)`                   | Subscribe to stable, port-aware connections for one node                                                                |
+| `useFlowView()`                               | Access view-owned image export and measurement refresh                                                                  |
+| `useKeyPress(keys)`                           | Track whether one or more keys are currently pressed                                                                    |
+| `useNodesInitialized()`                       | Check whether visible auto-size nodes have measurements                                                                 |
+| `useFlowNode(id, selector?, isEqual?)`        | Subscribe to node data plus derived render fields                                                                       |
+| `useFlowEdge(id, selector?, isEqual?)`        | Subscribe to edge data plus derived render fields                                                                       |
+| `useFlowPort(id, selector?, isEqual?)`        | Subscribe to port data plus derived render fields                                                                       |
+| `useFlowViewport()`                           | Subscribe to viewport state                                                                                             |
+| `useFlowMeasurement(id)`                      | Subscribe to measured bounds for an entity ref                                                                          |
+| `FlowInstanceProvider`                        | Provides a `FlowInstance` through React context                                                                         |
+| `useFlowInstance()`                           | Reads the nearest `FlowInstance`                                                                                        |
+| `useOptionalFlowInstance()`                   | Reads the nearest `FlowInstance` or returns `null`                                                                      |
+| `StatelyFlow`                                 | Convenience component that renders nodes, edges, backgrounds, projections, and overlays                                 |
+| `createEntityGeometryObserver(store)`         | Batches transient node/label rectangles, multi-entity bounds, and edge paths into imperative animation-frame DOM writes |
+| `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                                             |
+| `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                   |
+| `ReactGraphNodeAttrs` / `ReactGraphEdgeAttrs` | React-typed visual attrs exposed to custom node/edge renderers                                                          |
+| `FlowColorModeScope`                          | Applies the current flow color mode as DOM data attributes and `color-scheme`                                           |
+| `useFlowColorMode()`                          | Reads the store color mode and resolves `system` to `light` or `dark`                                                   |
+| `useApplyFlowColorMode(element)`              | Applies flow color mode attributes to an existing DOM element from inside a flow                                        |
+| `FLOW_BASE_CSS` / `useFlowBaseStyles()`       | Base data-attribute stylesheet injected by `StatelyFlow`                                                                |
 
 `@statelyai/flow-react` and `@statelyai/flow-react/backgrounds` export `Background`, `DotsBackground`, `LinesBackground`, and `CrossBackground` helpers for viewport-aware canvas backgrounds. Backgrounds are plain React components, so consumers can also build custom ones with `useFlowSelector((context) => context.viewport)`.
 
@@ -70,7 +71,15 @@ Color mode is store data, not engine behavior. `@statelyai/flow-dom` exports sma
 
 <!-- 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 content and `layers.pane` for screen-coordinate content. Descendants can target the same named layers with `ViewportPortal` and `PanePortal`. 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. 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.
+
+Set `showSelectionBounds` to render a zoom-stable, square frame around established multi-selections. Its geometry follows drag and layout frames through Flow DOM without React commits; theme `[data-flow-selection-bounds]`, `--flow-selection-color`, or the screen-pixel `--flow-selection-bounds-outset`. Set `preserveViewportCenterOnResize` when root container resizes should retain the world point at its center.
+
+The default edge renderer honors `edge.style.markerStart` and `markerEnd` values `arrow`, `arrow-closed`, `circle`, and `none`, plus safe local custom marker IDs or `url(#id)` references. External and malformed marker URLs are rejected. Built-in marker definitions are namespaced per `StatelyFlow`, so multiple mounted flows cannot collide. It also renders canonical graph `edge.points`/`routing` and optional `edge.svgPath` without rerouting or splitting the route around a label.
+
+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.
 
 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.
 
@@ -78,7 +87,9 @@ For controlled reconnect gestures, `reconnectMode({ commit: false, preview: fals
 
 `EntityAnchor` can be nested inside a node or edge-label renderer with `side`, a child `anchor` point, cross-axis `align`, and an outward `offset`. The nested anchor follows the parent entity's imperative drag geometry without React commits. With `inverseScale`, its size and offset remain constant in screen pixels and its transform origin matches the selected child anchor. The existing `bounds` plus `AnchorSpec` form remains available for free-standing canvas-space overlays.
 
-`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`, 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.
+<!-- 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.
 
 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.
 
@@ -96,14 +107,14 @@ import {
   StatelyFlow,
   useFlow,
   useFlowSelector,
-} from "@statelyai/flow-react";
+} from '@statelyai/flow-react';
 
 const graph = createGraph({
   nodes: [
-    createNode({ id: "a", x: 0, y: 0, data: { label: "Start" } }),
-    createNode({ id: "b", x: 240, y: 120, data: { label: "Done" } }),
+    createNode({ id: 'a', x: 0, y: 0, data: { label: 'Start' } }),
+    createNode({ id: 'b', x: 240, y: 120, data: { label: 'Done' } }),
   ],
-  edges: [createEdge({ id: "a-b", sourceId: "a", targetId: "b" })],
+  edges: [createEdge({ id: 'a-b', sourceId: 'a', targetId: 'b' })],
 });
 
 function Flow() {
@@ -116,7 +127,7 @@ function Flow() {
       {
         selector: (context) => context.selection.size,
         onChange: (selectionSize) => {
-          console.log("selection size", selectionSize);
+          console.log('selection size', selectionSize);
         },
       },
     ],
@@ -127,9 +138,9 @@ function Flow() {
       flow={flow}
       projections={[
         {
-          projection: { id: "coverage", nodes: { a: "visited" } },
+          projection: { id: 'coverage', nodes: { a: 'visited' } },
           mapper: {
-            getNodeAttrs: () => ({ color: "#16a34a", badge: "visited" }),
+            getNodeAttrs: () => ({ color: '#16a34a', badge: 'visited' }),
           },
         },
       ]}
@@ -140,7 +151,6 @@ function Flow() {
   );
 }
 ```
-
 ## Storybook
 
 ```bash

package/dist/esm/index.d.ts

@@ -1,7 +1,7 @@
 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, FlowColorMode, FlowCommitEvent, FlowConnection, FlowController, FlowEdge, FlowGraph, FlowInputMode, FlowKeymap, FlowNode, FlowProfile, FlowStoreContext, GraphEdgeAttrs, GraphNodeAttrs, LayoutRequestedEvent, Point, Rect, ResizeHandle, Viewport, VisualPort } from "@statelyai/flow";
-import { CSSProperties, ComponentPropsWithoutRef, HTMLAttributes, ReactNode, Ref, RefObject } from "react";
+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, 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
 type FlowSelector<T> = (context: FlowStoreContext) => T;
@@ -54,6 +54,13 @@ type FlowInstance<TNodeData = any, TEdgeData = any, TLabelData = any> = FlowCont
     fireImmediately?: boolean;
   }): () => void;
 };
+/**
+ * Create the React adapter's imperative Flow instance.
+ *
+ * The instance owns its controller and all listeners registered through
+ * `listen` or creation options. `destroy()` removes those listeners and
+ * destroys the underlying controller.
+ */
 declare function createFlowInstance<TNodeData = any, TEdgeData = any, TLabelData = any>(options: CreateFlowInstanceOptions<TNodeData, TEdgeData, TLabelData>): FlowInstance<TNodeData, TEdgeData, TLabelData>;
 //#endregion
 //#region src/FlowInstanceContext.d.ts
@@ -67,9 +74,16 @@ declare function useOptionalFlowInstance(): FlowInstance | null;
 //#region src/hooks.d.ts
 type UseCreateFlowInstanceOptions<TNodeData = any, TEdgeData = any, TLabelData = any> = CreateFlowInstanceOptions<TNodeData, TEdgeData, TLabelData>;
 type UseFlowOptions<TNodeData = any, TEdgeData = any, TLabelData = any> = UseCreateFlowInstanceOptions<TNodeData, TEdgeData, TLabelData>;
+/**
+ * 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.
+ */
 declare function useFlow<TNodeData = any, TEdgeData = any, TLabelData = any>(options: UseFlowOptions<TNodeData, TEdgeData, TLabelData>): FlowInstance<TNodeData, TEdgeData, TLabelData>;
 /** @deprecated Use `useFlow(options)`. */
 declare function useCreateFlowInstance<TNodeData = any, TEdgeData = any, TLabelData = any>(options: UseCreateFlowInstanceOptions<TNodeData, TEdgeData, TLabelData>): FlowInstance<TNodeData, TEdgeData, TLabelData>;
+/** Subscribe to a derived slice of Flow context with optional equality. */
 declare function useFlowSelector<T>(selector: FlowSelector<T>, options?: {
   flow?: FlowInstance;
   isEqual?: FlowSelectorEquality<T>;
@@ -203,6 +217,10 @@ type StatelyFlowBaseProps<TNodeData = unknown, TEdgeData = unknown> = {
   renderEdge?: (props: RenderEdgeProps<TEdgeData>) => ReactNode;
   renderEdgeLabel?: (props: RenderEdgeLabelProps<TEdgeData>) => ReactNode;
   renderConnectionLine?: (props: RenderConnectionLineProps) => ReactNode;
+  /** Render a zoom-stable frame around established multi-selections. */
+  showSelectionBounds?: boolean;
+  /** Keep the same world point centered when the root container resizes. */
+  preserveViewportCenterOnResize?: boolean;
   /**
    * Only mount nodes/edges that intersect the viewport (plus an overscan
    * margin). Recommended for large graphs.
@@ -262,6 +280,12 @@ declare function ViewportPortal(props: {
 declare function PanePortal(props: {
   children: ReactNode;
 }): import("react").ReactPortal | null;
+type UseFitViewExclusionOptions = {
+  side?: FitViewExclusionSide;
+  gap?: number;
+};
+/** Register an overlay element whose measured edge band fit commands avoid. */
+declare function useFitViewExclusion(options?: UseFitViewExclusionOptions): RefCallback<HTMLElement>;
 //#endregion
 //#region src/FlowToolbar.d.ts
 /** Border-box size of an element, kept current via ResizeObserver. */
@@ -319,7 +343,7 @@ type MiniMapProps = {
 /**
  * Overview map. Deliberately thin: all math lives in core
  * (`getMinimapProjection`, `viewportCenteredOn`) and every interaction is a
- * plain store trigger — this component is exactly what you would write in
+ * controller viewport command — this component is exactly what you would write in
  * userland, kept here as a convenience.
  */
 declare function MiniMap(props: MiniMapProps): import("react").JSX.Element;
@@ -341,8 +365,7 @@ type ControlsProps = {
   children?: ReactNode;
 };
 /**
- * Zoom/fit toolbar. Deliberately thin: every button is one store trigger
- * (`zoomBy`, `fitView`) — replicate or extend it freely in userland.
+ * Zoom/fit toolbar backed by the controller's constrained viewport API.
  */
 declare function Controls(props: ControlsProps): import("react").JSX.Element;
 //#endregion
@@ -378,6 +401,11 @@ declare function EntityAnchor(props: EntityAnchorProps): import("react").JSX.Ele
 //#region src/Port.d.ts
 type PortProps = {
   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:
@@ -434,16 +462,6 @@ type DragHandleProps = HTMLAttributes<HTMLDivElement> & {
  */
 declare function DragHandle({ children, style, ...rest }: DragHandleProps): import("react").JSX.Element;
 //#endregion
-//#region src/NodeResizer.d.ts
-type NodeResizerProps = {
-  handles?: ResizeHandle[];
-  /** Defaults to node selection state. Constraints belong on `node.resize`. */
-  isVisible?: boolean;
-  className?: string;
-  style?: CSSProperties;
-};
-declare function NodeResizer(props: NodeResizerProps): import("react").JSX.Element | null;
-//#endregion
 //#region src/baseStyles.d.ts
 /**
  * Minimal base stylesheet for the flow canvas. Intentionally tiny and
@@ -461,9 +479,10 @@ declare function NodeResizer(props: NodeResizerProps): import("react").JSX.Eleme
  *   inline `pointer-events` on the same element — inline wins over this rule.
  * - `data-flow-selection-box` — the box-select marquee (styled here; geometry
  *   is set inline by the renderer).
+ * - `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  touch-action: 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-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: calc(2px / var(--flow-zoom, 1));\n  background: var(--flow-selection-bg);\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-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
@@ -480,4 +499,4 @@ 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, NodeResizer, type NodeResizerProps, PanePortal, Panel, type PanelPosition, type PanelProps, Port, type PortProps, type ReactActiveGraphProjection, type ReactGraphEdgeAttrs, type ReactGraphNodeAttrs, type RenderConnectionLineProps, type RenderEdgeLabelProps, type RenderEdgeProps, type RenderNodeProps, StatelyFlow, type StatelyFlowProps, type StatelyFlowRootProps, type StatelyFlowStyle, type UseCreateFlowInstanceOptions, type UseFlowInputOptions, type UseFlowOptions, type UseFlowToolbarOptions, ViewportPortal, createFlowInstance, useApplyFlowColorMode, useConnection, useCreateFlowInstance, useFlow, useFlowBaseStyles, useFlowColorMode, useFlowConnections, useFlowContext, useFlowEdge, useFlowEntity, useFlowInput, useFlowInstance, useFlowMeasurement, useFlowNode, useFlowPort, useFlowSelector, useFlowToolbar, useFlowValue, useFlowView, useFlowViewport, useKeyPress, useMeasuredSize, useNodesInitialized, useOptionalFlowInstance };
+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 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,12 +1,19 @@
 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, renderableIdsEqual, resolveFlowColorMode, viewportStyle } from "@statelyai/flow-dom";
-import { CONNECTION_PREVIEW_EDGE_ID, areNodesMeasured, createConnectionPreviewGraph, createEntityChangeNotifier, createFlow, createFlowInputRuntime, getAnchorTransform, getAutoPanDelta, getMinimapProjection, getProjectedEdgeAttrs, getProjectedNodeAttrs, getToolbarPlacement, nodeDepths, pathToSVG, profileModesForContext, profilePoliciesForContext, viewportCenteredOn } from "@statelyai/flow";
-import { createContext, memo, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { CONNECTION_PREVIEW_EDGE_ID, areNodesMeasured, createConnectionPreviewGraph, createEntityChangeNotifier, createFlow, createFlowInputRuntime, getAnchorTransform, getAutoPanDelta, getMinimapProjection, getProjectedEdgeAttrs, getProjectedNodeAttrs, getToolbarPlacement, markerToSVG, pathToSVG, profileModesForContext, profilePoliciesForContext, viewportCenteredOn } from "@statelyai/flow";
+import { createContext, memo, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
 import { createPortal } from "react-dom";
 export * from "@statelyai/flow-dom";
 //#region src/createFlowInstance.ts
+/**
+* Create the React adapter's imperative Flow instance.
+*
+* The instance owns its controller and all listeners registered through
+* `listen` or creation options. `destroy()` removes those listeners and
+* destroys the underlying controller.
+*/
 function createFlowInstance(options) {
 	const { keymap, ...createFlowSettings } = options.settings ?? {};
 	const flow = createFlow({
@@ -68,6 +75,12 @@ function createFlowInstance(options) {
 }
 //#endregion
 //#region src/hooks.ts
+/**
+* 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.
+*/
 function useFlow(options) {
 	return useCreateFlowInstance(options);
 }
@@ -125,6 +138,7 @@ function useCreateFlowInstance(options) {
 	}, [flow]);
 	return flow;
 }
+/** Subscribe to a derived slice of Flow context with optional equality. */
 function useFlowSelector(selector, options = {}) {
 	const contextFlow = useOptionalFlowInstance();
 	const flow = options.flow ?? contextFlow;
@@ -375,15 +389,27 @@ function useFlowView() {
 *   inline `pointer-events` on the same element — inline wins over this rule.
 * - `data-flow-selection-box` — the box-select marquee (styled here; geometry
 *   is set inline by the renderer).
+* - `data-flow-selection-bounds` — the established multi-selection frame.
 */
 const FLOW_BASE_STYLES_ID = "flow-base-styles";
 const FLOW_BASE_CSS = `
 [data-flow-root] {
   --flow-selection-color: #2563eb;
   --flow-selection-bg: rgba(37, 99, 235, 0.12);
+  --flow-selection-bounds-outset: 1px;
+  --flow-layer-edges: 0;
+  --flow-layer-entities: 10;
+  --flow-layer-labels: 20;
+  --flow-layer-interaction: 30;
+  --flow-layer-guides: 40;
+  --flow-layer-chrome: 50;
   touch-action: none;
 }
 
+[data-flow-root]:focus {
+  outline: var(--flow-focus-outline, none);
+}
+
 [data-flow-interactive-when-selected] {
   pointer-events: none;
 }
@@ -391,14 +417,37 @@ const FLOW_BASE_CSS = `
   pointer-events: auto;
 }
 
+[data-flow-custom-node] :where(
+  button,
+  input,
+  select,
+  textarea,
+  a[href],
+  [role="button"],
+  [tabindex],
+  [data-flow-drag-handle],
+  [data-flow-port-name]
+) {
+  pointer-events: auto;
+}
+
 [data-flow-selection-box] {
   position: absolute;
   box-sizing: border-box;
   border: calc(1px / var(--flow-zoom, 1)) solid var(--flow-selection-color);
-  border-radius: calc(2px / var(--flow-zoom, 1));
+  border-radius: 0;
   background: var(--flow-selection-bg);
   pointer-events: none;
 }
+
+[data-flow-selection-bounds] {
+  position: absolute;
+  box-sizing: border-box;
+  outline: calc(1px / var(--flow-zoom, 1)) solid var(--flow-selection-color);
+  outline-offset: calc(var(--flow-selection-bounds-outset) / var(--flow-zoom, 1));
+  border-radius: 0;
+  pointer-events: none;
+}
 `;
 /** Inject the base stylesheet once per document (deduped by element id). */
 function useFlowBaseStyles() {
@@ -421,6 +470,18 @@ function useNodeRenderContext() {
 	return context;
 }
 //#endregion
+//#region src/focus.ts
+/** Whether a focused descendant owns its own graph focus identity. */
+function descendantOwnsFlowFocus(event) {
+	const target = event.target;
+	return target instanceof Element && target.closest("[data-flow-port-interaction=\"inspect\"]") !== null;
+}
+function clearEntityFocusOnBlur(flow, entityId, event) {
+	const nextTarget = event.relatedTarget;
+	if (nextTarget instanceof Node && event.currentTarget.contains(nextTarget)) return;
+	if (flow.getSnapshot().focusedEntityId === entityId) flow.internals.store.trigger.clearFocus();
+}
+//#endregion
 //#region src/LayerPortals.tsx
 const FlowLayerTargetsContext = createContext(null);
 function FlowLayerTargetsProvider(props) {
@@ -444,6 +505,43 @@ function PanePortal(props) {
 	const target = useFlowLayerTargets().pane;
 	return target ? createPortal(props.children, target) : null;
 }
+/** Register an overlay element whose measured edge band fit commands avoid. */
+function useFitViewExclusion(options = {}) {
+	const flow = useFlowInstance();
+	const root = useFlowLayerTargets().root;
+	const [element, setElement] = useState(null);
+	const ref = useCallback((next) => setElement(next), []);
+	useLayoutEffect(() => {
+		if (!root || !element) return;
+		element.setAttribute("data-flow-fit-exclusion", options.side ?? "nearest");
+		const unregister = flow.viewport.registerFitExclusion({
+			side: options.side,
+			gap: options.gap,
+			getRect: () => {
+				if (!element.isConnected || !root.isConnected) return null;
+				const rootRect = root.getBoundingClientRect();
+				const rect = element.getBoundingClientRect();
+				return {
+					x: rect.left - rootRect.left,
+					y: rect.top - rootRect.top,
+					width: rect.width,
+					height: rect.height
+				};
+			}
+		});
+		return () => {
+			unregister();
+			element.removeAttribute("data-flow-fit-exclusion");
+		};
+	}, [
+		element,
+		flow,
+		options.gap,
+		options.side,
+		root
+	]);
+	return ref;
+}
 //#endregion
 //#region src/StatelyFlow.tsx
 function stringArraysEqual(a, b) {
@@ -495,17 +593,24 @@ function OwnedStatelyFlow(props) {
 }
 function StatelyFlowView(props) {
 	const containerRef = useRef(null);
+	const [rootLayer, setRootLayer] = useState(null);
 	const setContainerRef = useCallback((element) => {
 		containerRef.current = element;
+		setRootLayer(element);
 		assignRef(props.rootRef, element);
 	}, [props.rootRef]);
 	const viewportRef = useRef(null);
 	const [viewportLayer, setViewportLayer] = useState(null);
 	const [paneLayer, setPaneLayer] = useState(null);
 	const layerTargets = useMemo(() => ({
+		root: rootLayer,
 		viewport: viewportLayer,
 		pane: paneLayer
-	}), [viewportLayer, paneLayer]);
+	}), [
+		rootLayer,
+		viewportLayer,
+		paneLayer
+	]);
 	const measurementObserver = useMemo(() => createMeasurementObserver(props.flow.internals.store, { container: () => containerRef.current }), [props.flow]);
 	const geometryObserver = useMemo(() => createEntityGeometryObserver(props.flow.internals.store, { getEdgeDependents: props.flow.internals.engine.getEdgeSourceDependents }), [props.flow]);
 	useLayoutEffect(() => () => {
@@ -519,8 +624,8 @@ function StatelyFlowView(props) {
 	useLayoutEffect(() => {
 		const element = containerRef.current;
 		if (!element) return;
-		return attachContainer(props.flow.internals.store, element);
-	}, [props.flow]);
+		return attachContainer(props.flow.internals.store, element, { preserveViewportCenter: props.preserveViewportCenterOnResize });
+	}, [props.flow, props.preserveViewportCenterOnResize]);
 	useFlowInput(props.flow, containerRef, {
 		modes: props.inputModes,
 		profile: props.settings?.store?.profile,
@@ -576,7 +681,10 @@ function StatelyFlowView(props) {
 								ref: viewportRef,
 								className: "stately-flow__viewport",
 								"data-flow-viewport": true,
-								style: viewportStyle(),
+								style: {
+									...viewportStyle(),
+									isolation: "isolate"
+								},
 								children: [
 									/* @__PURE__ */ jsx(EdgeLayer, {
 										geometryObserver,
@@ -598,6 +706,7 @@ function StatelyFlowView(props) {
 										projections,
 										onlyRenderVisible: props.onlyRenderVisible
 									}),
+									props.showSelectionBounds ? /* @__PURE__ */ jsx(SelectionBoundsLayer, { geometryObserver }) : null,
 									/* @__PURE__ */ jsx(SelectionBoxLayer, {}),
 									/* @__PURE__ */ jsx("div", {
 										ref: setViewportLayer,
@@ -607,6 +716,7 @@ function StatelyFlowView(props) {
 										style: {
 											position: "absolute",
 											inset: 0,
+											zIndex: "var(--flow-layer-interaction, 30)",
 											pointerEvents: "none"
 										},
 										children: props.layers?.viewport
@@ -621,6 +731,7 @@ function StatelyFlowView(props) {
 								style: {
 									position: "absolute",
 									inset: 0,
+									zIndex: "var(--flow-layer-chrome, 50)",
 									pointerEvents: "none"
 								},
 								children: props.layers?.pane
@@ -668,6 +779,7 @@ function SnapLinesLayer() {
 			inset: 0,
 			width: "100%",
 			height: "100%",
+			zIndex: "var(--flow-layer-guides, 40)",
 			overflow: "visible",
 			pointerEvents: "none"
 		},
@@ -782,16 +894,49 @@ function SelectionBoxLayer() {
 			left: Math.min(a.x, b.x),
 			top: Math.min(a.y, b.y),
 			width: Math.abs(b.x - a.x),
-			height: Math.abs(b.y - a.y)
+			height: Math.abs(b.y - a.y),
+			zIndex: "var(--flow-layer-interaction, 30)"
+		}
+	});
+}
+function SelectionBoundsLayer(props) {
+	const flow = useFlowInstance();
+	const selectedIds = useFlowSelector((context) => [...context.selection], { isEqual: stringArraysEqual });
+	const ref = useRef(null);
+	const bounds = selectedIds.length > 1 ? flow.getSelectionBounds() : null;
+	useLayoutEffect(() => {
+		const element = ref.current;
+		if (!element || selectedIds.length < 2) return;
+		return props.geometryObserver.observeBounds(element, {
+			ids: selectedIds,
+			getRect: () => flow.getSelectionBounds()
+		});
+	}, [
+		flow,
+		props.geometryObserver,
+		selectedIds
+	]);
+	if (!bounds) return null;
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"aria-hidden": "true",
+		className: "stately-flow__selection-bounds",
+		"data-flow-selection-bounds": "",
+		style: {
+			transform: `translate(${bounds.x}px, ${bounds.y}px)`,
+			width: bounds.width,
+			height: bounds.height,
+			zIndex: "var(--flow-layer-interaction, 30)"
 		}
 	});
 }
 function EdgeLayer(props) {
 	const instance = useFlowInstance();
+	const markerPrefix = `stately-flow-${useId().replace(/[^a-zA-Z0-9_-]/g, "")}`;
 	const renderableIds = useRenderableIds(instance, props.onlyRenderVisible);
-	const edgeIds = useFlowSelector((context) => getOrderedEntities(instance, context).edges.map((edge) => edge.id), { isEqual: stringArraysEqual });
+	const edgeIds = useFlowSelector((_context) => getOrderedEntities(instance).edges.map((edge) => edge.id), { isEqual: stringArraysEqual });
 	const renderEdge = props.renderEdge;
-	return /* @__PURE__ */ jsx("svg", {
+	return /* @__PURE__ */ jsxs("svg", {
 		"aria-label": "edges",
 		className: "stately-flow__edges",
 		"data-flow-canvas-layer": true,
@@ -800,23 +945,26 @@ function EdgeLayer(props) {
 			inset: 0,
 			width: "100%",
 			height: "100%",
+			zIndex: "var(--flow-layer-edges, 0)",
 			overflow: "visible",
 			pointerEvents: "none"
 		},
-		children: /* @__PURE__ */ jsxs("g", { children: [edgeIds.map((id) => {
+		children: [/* @__PURE__ */ jsx(DefaultMarkerDefinitions, { prefix: markerPrefix }), /* @__PURE__ */ jsxs("g", { children: [edgeIds.map((id) => {
 			if (renderableIds && !renderableIds.edgeIds.has(id)) return null;
 			return /* @__PURE__ */ jsx(EdgeView, {
 				flow: instance,
 				geometryObserver: props.geometryObserver,
 				id,
 				projections: props.projections,
-				renderEdge
+				renderEdge,
+				markerPrefix
 			}, id);
 		}), /* @__PURE__ */ jsx(ConnectionPreviewEdge, {
 			flow: instance,
 			renderEdge,
-			renderConnectionLine: props.renderConnectionLine
-		})] })
+			renderConnectionLine: props.renderConnectionLine,
+			markerPrefix
+		})] })]
 	});
 }
 const EdgeView = memo(function EdgeView(props) {
@@ -860,23 +1008,23 @@ const EdgeView = memo(function EdgeView(props) {
 		"aria-label": props.flow.internals.engine.getAriaLabel(props.id),
 		"aria-selected": selected,
 		tabIndex: focusable ? 0 : void 0,
-		onFocus: () => props.flow.internals.store.trigger.focus({ entityId: props.id })
+		onFocus: (event) => {
+			if (descendantOwnsFlowFocus(event)) return;
+			props.flow.internals.store.trigger.focus({ entityId: props.id });
+		},
+		onBlur: (event) => clearEntityFocusOnBlur(props.flow, props.id, event)
 	};
 	if (props.renderEdge) return /* @__PURE__ */ jsxs("g", {
 		ref,
 		...focusProps,
 		"data-entity-id": props.id,
 		"data-flow-selected": selected ? "true" : void 0,
+		"data-flow-focused": focused ? "true" : void 0,
 		className: classNames$1("stately-flow__edge", attrs.className),
-		style: {
-			pointerEvents: "auto",
-			outline: focused ? "2px solid #2563eb" : "none"
-		},
+		style: { pointerEvents: "auto" },
 		children: [/* @__PURE__ */ jsx(EdgeHitTarget, {
-			flow: props.flow,
 			edge,
-			pathData,
-			selected
+			pathData
 		}), props.renderEdge({
 			flow: props.flow,
 			edge,
@@ -892,18 +1040,19 @@ const EdgeView = memo(function EdgeView(props) {
 		...focusProps,
 		"data-entity-id": props.id,
 		"data-flow-selected": selected ? "true" : void 0,
+		"data-flow-focused": focused ? "true" : void 0,
 		className: classNames$1("stately-flow__edge", attrs.className),
 		style: {
 			pointerEvents: "auto",
-			opacity: attrs.opacity,
-			outline: focused ? "2px solid #2563eb" : "none"
+			opacity: attrs.opacity
 		},
 		children: /* @__PURE__ */ jsx(DefaultEdge, {
 			flow: props.flow,
 			edge,
 			pathData,
 			attrs,
-			selected
+			selected,
+			markerPrefix: props.markerPrefix
 		})
 	});
 });
@@ -935,6 +1084,7 @@ function ConnectionPreviewEdge(props) {
 			pathData,
 			attrs: {},
 			selected: false,
+			markerPrefix: props.markerPrefix,
 			preview: true
 		})
 	});
@@ -946,9 +1096,11 @@ function DefaultEdge(props) {
 			d,
 			"data-flow-edge-segment": index,
 			fill: "none",
-			stroke: props.attrs.color ?? (props.preview ? props.edge.data?.isValid === false ? "#dc2626" : props.edge.data?.isValid === true ? "#16a34a" : "#0f766e" : props.selected ? "#2563eb" : "#94a3b8"),
-			strokeDasharray: props.preview ? "6 6" : void 0,
-			strokeWidth: props.attrs.strokeWidth ?? (props.selected ? 3 : 2),
+			stroke: props.attrs.color ?? (props.preview ? props.edge.data?.isValid === false ? "#dc2626" : props.edge.data?.isValid === true ? "#16a34a" : "#0f766e" : props.selected ? "#2563eb" : props.edge.style?.stroke ?? "#94a3b8"),
+			strokeDasharray: props.preview ? "6 6" : props.edge.style?.strokeDasharray,
+			strokeWidth: props.attrs.strokeWidth ?? (props.selected ? 3 : props.edge.style?.strokeWidth ?? 2),
+			markerStart: index === 0 ? markerToSVG(props.edge.style?.markerStart, props.markerPrefix) : void 0,
+			markerEnd: index === props.pathData.segments.length - 1 ? markerToSVG(props.edge.style?.markerEnd, props.markerPrefix) : void 0,
 			style: props.attrs.style
 		}), props.preview ? null : /* @__PURE__ */ jsx("path", {
 			d,
@@ -967,8 +1119,54 @@ function DefaultEdge(props) {
 		selected: props.selected
 	})] });
 }
+function DefaultMarkerDefinitions(props) {
+	return /* @__PURE__ */ jsxs("defs", { children: [
+		/* @__PURE__ */ jsx("marker", {
+			id: `${props.prefix}-arrow`,
+			viewBox: "0 0 10 10",
+			refX: "9",
+			refY: "5",
+			markerWidth: "6",
+			markerHeight: "6",
+			orient: "auto-start-reverse",
+			children: /* @__PURE__ */ jsx("path", {
+				d: "M 1 1 L 9 5 L 1 9",
+				fill: "none",
+				stroke: "context-stroke"
+			})
+		}),
+		/* @__PURE__ */ jsx("marker", {
+			id: `${props.prefix}-arrow-closed`,
+			viewBox: "0 0 10 10",
+			refX: "9",
+			refY: "5",
+			markerWidth: "6",
+			markerHeight: "6",
+			orient: "auto-start-reverse",
+			children: /* @__PURE__ */ jsx("path", {
+				d: "M 1 1 L 9 5 L 1 9 Z",
+				fill: "context-stroke"
+			})
+		}),
+		/* @__PURE__ */ jsx("marker", {
+			id: `${props.prefix}-circle`,
+			viewBox: "0 0 10 10",
+			refX: "5",
+			refY: "5",
+			markerWidth: "5",
+			markerHeight: "5",
+			orient: "auto",
+			children: /* @__PURE__ */ jsx("circle", {
+				cx: "5",
+				cy: "5",
+				r: "4",
+				fill: "context-stroke"
+			})
+		})
+	] });
+}
 function EdgeHitTarget(props) {
-	return /* @__PURE__ */ jsxs(Fragment, { children: [props.pathData.segments.map((segment, index) => {
+	return /* @__PURE__ */ jsx(Fragment, { children: props.pathData.segments.map((segment, index) => {
 		return /* @__PURE__ */ jsx("path", {
 			d: pathToSVG(segment),
 			"data-flow-edge-segment": index,
@@ -979,7 +1177,7 @@ function EdgeHitTarget(props) {
 			strokeWidth: 18,
 			pointerEvents: "stroke"
 		}, index);
-	}), /* @__PURE__ */ jsx(EdgeEndpointHandles, { ...props })] });
+	}) });
 }
 function EdgeEndpointHandles(props) {
 	if (!props.selected) return null;
@@ -1025,6 +1223,7 @@ function EdgeLabelLayer(props) {
 		style: {
 			position: "absolute",
 			inset: 0,
+			zIndex: "var(--flow-layer-labels, 20)",
 			pointerEvents: "none"
 		},
 		children: useMemo(() => {
@@ -1185,7 +1384,7 @@ function NodeLayer(props) {
 	const instance = useFlowInstance();
 	const renderableIds = useRenderableIds(instance, props.onlyRenderVisible);
 	const nodePaintEntries = useFlowSelector((context) => {
-		const paintOrder = new Map(getOrderedEntities(instance, context).nodes.map((node, orderIndex) => [node.id, orderIndex]));
+		const paintOrder = new Map(getOrderedEntities(instance).nodes.map((node, orderIndex) => [node.id, orderIndex]));
 		return context.graph.nodes.flatMap((node) => {
 			const orderIndex = paintOrder.get(node.id);
 			return orderIndex === void 0 ? [] : [{
@@ -1202,6 +1401,7 @@ function NodeLayer(props) {
 		style: {
 			position: "absolute",
 			inset: 0,
+			zIndex: "var(--flow-layer-entities, 10)",
 			transformOrigin: "0 0",
 			pointerEvents: "none"
 		},
@@ -1219,33 +1419,8 @@ function NodeLayer(props) {
 		})
 	});
 }
-function getOrderedEntities(flow, context) {
-	const maybeEngine = flow.internals.engine;
-	const visibleOrdered = maybeEngine.getVisibleEntities?.();
-	if (visibleOrdered) return visibleOrdered;
-	const ordered = maybeEngine.getEntityOrder?.();
-	if (ordered) return ordered;
-	const depths = nodeDepths(context.graph.nodes);
-	const nodeOrder = new Map(context.graph.nodes.map((node, index) => [node.id, index]));
-	const edgeOrder = new Map(context.graph.edges.map((edge, index) => [edge.id, index]));
-	return {
-		nodes: [...context.graph.nodes].sort((a, b) => {
-			const depthDelta = (depths.get(a.id) ?? 0) - (depths.get(b.id) ?? 0);
-			if (depthDelta !== 0) return depthDelta;
-			const zDelta = (a.zIndex ?? 0) - (b.zIndex ?? 0);
-			if (zDelta !== 0) return zDelta;
-			const selectedDelta = Number(context.selection.has(a.id)) - Number(context.selection.has(b.id));
-			if (selectedDelta !== 0) return selectedDelta;
-			return (nodeOrder.get(a.id) ?? 0) - (nodeOrder.get(b.id) ?? 0);
-		}),
-		edges: [...context.graph.edges].sort((a, b) => {
-			const depthDelta = Math.max(depths.get(a.sourceId) ?? 0, depths.get(a.targetId) ?? 0) - Math.max(depths.get(b.sourceId) ?? 0, depths.get(b.targetId) ?? 0);
-			if (depthDelta !== 0) return depthDelta;
-			const zDelta = (a.zIndex ?? 0) - (b.zIndex ?? 0);
-			if (zDelta !== 0) return zDelta;
-			return (edgeOrder.get(a.id) ?? 0) - (edgeOrder.get(b.id) ?? 0);
-		})
-	};
+function getOrderedEntities(flow) {
+	return flow.internals.engine.getVisibleEntities();
 }
 function rectsShallowEqual(a, b) {
 	return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
@@ -1336,6 +1511,8 @@ const NodeView = memo(function NodeView(props) {
 		projections: props.projections
 	});
 	const focusable = props.flow.internals.engine.resolveEntityConfig(node).focusable;
+	const groupGeometry = node.group ? props.flow.internals.engine.getGroupGeometry(node.id) : void 0;
+	const groupHasInteractiveContent = Boolean(groupGeometry?.contentBounds.width && groupGeometry.contentBounds.height);
 	return /* @__PURE__ */ jsx(NodeRenderContextProvider, {
 		value: {
 			node,
@@ -1345,35 +1522,45 @@ const NodeView = memo(function NodeView(props) {
 			ref,
 			"data-entity-id": props.id,
 			"data-flow-selected": selected ? "true" : void 0,
+			"data-flow-focused": focused ? "true" : void 0,
 			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: () => props.flow.internals.store.trigger.focus({ entityId: props.id }),
+			onFocus: (event) => {
+				if (descendantOwnsFlowFocus(event)) return;
+				props.flow.internals.store.trigger.focus({ entityId: props.id });
+			},
+			onBlur: (event) => clearEntityFocusOnBlur(props.flow, props.id, event),
 			style: {
 				...nodePositionStyle(bounds, {
 					autoSize: contentOwnsSize,
 					dragging
 				}),
 				cursor: dragging ? "grabbing" : "grab",
-				pointerEvents: "auto",
+				pointerEvents: node.group && groupHasInteractiveContent ? "none" : "auto",
 				userSelect: "none",
 				zIndex: props.orderIndex,
-				outline: focused ? "2px solid #2563eb" : "none",
-				outlineOffset: 2,
 				opacity: attrs.opacity
 			},
-			children: props.renderNode ? props.renderNode({
-				flow: props.flow,
-				node,
-				bounds,
-				attrs,
-				selected,
-				dragging,
-				hovered,
-				highlights
+			children: props.renderNode ? /* @__PURE__ */ jsx("div", {
+				"data-flow-custom-node": true,
+				style: {
+					display: "contents",
+					pointerEvents: "none"
+				},
+				children: props.renderNode({
+					flow: props.flow,
+					node,
+					bounds,
+					attrs,
+					selected,
+					dragging,
+					hovered,
+					highlights
+				})
 			}) : node.group ? /* @__PURE__ */ jsx(DefaultGroupNode, {
 				flow: props.flow,
 				node,
@@ -1439,6 +1626,7 @@ function DefaultGroupNode(props) {
 			color: "#0f172a",
 			font: "600 13px/1.2 system-ui, sans-serif",
 			cursor: props.dragging ? "grabbing" : "grab",
+			pointerEvents: "auto",
 			userSelect: "none",
 			...props.attrs.style
 		},
@@ -1601,7 +1789,7 @@ function FlowToolbar(props) {
 /**
 * Overview map. Deliberately thin: all math lives in core
 * (`getMinimapProjection`, `viewportCenteredOn`) and every interaction is a
-* plain store trigger — this component is exactly what you would write in
+* controller viewport command — this component is exactly what you would write in
 * userland, kept here as a convenience.
 */
 function MiniMap(props) {
@@ -1626,7 +1814,7 @@ function MiniMap(props) {
 			x: event.clientX - rect.left,
 			y: event.clientY - rect.top
 		});
-		flow.internals.store.trigger.setViewport(viewportCenteredOn(canvasPoint, viewportSize, viewport.zoom));
+		flow.viewport.set(viewportCenteredOn(canvasPoint, viewportSize, viewport.zoom));
 	};
 	return /* @__PURE__ */ jsxs("svg", {
 		"aria-label": "minimap",
@@ -1749,8 +1937,7 @@ const buttonStyle = {
 	cursor: "pointer"
 };
 /**
-* Zoom/fit toolbar. Deliberately thin: every button is one store trigger
-* (`zoomBy`, `fitView`) — replicate or extend it freely in userland.
+* Zoom/fit toolbar backed by the controller's constrained viewport API.
 */
 function Controls(props) {
 	const flow = useFlowInstance();
@@ -1770,21 +1957,21 @@ function Controls(props) {
 				type: "button",
 				"aria-label": "zoom in",
 				style: buttonStyle,
-				onClick: () => flow.internals.store.trigger.zoomBy({ factor: 1.2 }),
+				onClick: () => flow.viewport.zoomBy(1.2),
 				children: "+"
 			}),
 			/* @__PURE__ */ jsx("button", {
 				type: "button",
 				"aria-label": "zoom out",
 				style: buttonStyle,
-				onClick: () => flow.internals.store.trigger.zoomBy({ factor: 1 / 1.2 }),
+				onClick: () => flow.viewport.zoomBy(1 / 1.2),
 				children: "−"
 			}),
 			/* @__PURE__ */ jsx("button", {
 				type: "button",
 				"aria-label": "fit view",
 				style: buttonStyle,
-				onClick: () => flow.internals.store.trigger.fitView({ padding: .1 }),
+				onClick: () => flow.viewport.fit({ padding: .1 }),
 				children: "⛶"
 			}),
 			props.children
@@ -1891,6 +2078,11 @@ function Port(props) {
 	const observerRef = useRef(null);
 	const observer = useMeasurementObserver();
 	const measured = props.measured ?? true;
+	const interaction = props.interaction ?? "connect";
+	const port = node.ports?.find((candidate) => candidate.name === props.name);
+	const portId = `${node.id}:${props.name}`;
+	const focusable = flow.internals.engine.resolveEntityConfig(node).focusable;
+	const selected = useFlowSelector((context) => context.selection.has(portId), { flow });
 	useLayoutEffect(() => {
 		const element = ref.current;
 		if (!element || !measured) return;
@@ -1926,8 +2118,20 @@ function Port(props) {
 		className: props.className,
 		"data-flow-port-name": props.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,
-		style: props.style,
+		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,
+		style: {
+			pointerEvents: "auto",
+			...props.style
+		},
 		children: props.children
 	});
 }
@@ -1964,96 +2168,6 @@ function DragHandle({ children, style, ...rest }) {
 	});
 }
 //#endregion
-//#region src/NodeResizer.tsx
-const DEFAULT_HANDLES = [
-	"top",
-	"right",
-	"bottom",
-	"left",
-	"top-left",
-	"top-right",
-	"bottom-left",
-	"bottom-right"
-];
-const HANDLE_STYLE = {
-	top: {
-		left: "50%",
-		top: 0,
-		cursor: "ns-resize"
-	},
-	right: {
-		left: "100%",
-		top: "50%",
-		cursor: "ew-resize"
-	},
-	bottom: {
-		left: "50%",
-		top: "100%",
-		cursor: "ns-resize"
-	},
-	left: {
-		left: 0,
-		top: "50%",
-		cursor: "ew-resize"
-	},
-	"top-left": {
-		left: 0,
-		top: 0,
-		cursor: "nwse-resize"
-	},
-	"top-right": {
-		left: "100%",
-		top: 0,
-		cursor: "nesw-resize"
-	},
-	"bottom-left": {
-		left: 0,
-		top: "100%",
-		cursor: "nesw-resize"
-	},
-	"bottom-right": {
-		left: "100%",
-		top: "100%",
-		cursor: "nwse-resize"
-	}
-};
-function NodeResizer(props) {
-	const { node } = useNodeRenderContext();
-	const selected = useFlowSelector((context) => context.selection.has(node.id));
-	if (!(props.isVisible ?? selected)) return null;
-	return /* @__PURE__ */ jsx("div", {
-		"aria-hidden": "true",
-		className: props.className,
-		"data-flow-node-resizer": "",
-		style: {
-			position: "absolute",
-			inset: 0,
-			pointerEvents: "none",
-			...props.style
-		},
-		children: (props.handles ?? DEFAULT_HANDLES).map((handle) => /* @__PURE__ */ jsx("div", {
-			"data-entity-id": node.id,
-			"data-flow-part": `resize-handle:${handle}`,
-			"data-flow-resize-handle": handle,
-			style: {
-				position: "absolute",
-				width: "calc(10px / var(--flow-zoom, 1))",
-				height: "calc(10px / var(--flow-zoom, 1))",
-				minWidth: 6,
-				minHeight: 6,
-				boxSizing: "border-box",
-				border: "calc(1px / var(--flow-zoom, 1)) solid #ffffff",
-				borderRadius: "calc(2px / var(--flow-zoom, 1))",
-				background: "var(--flow-selection-color, #2563eb)",
-				boxShadow: "0 0 0 calc(1px / var(--flow-zoom, 1)) rgba(15, 23, 42, 0.8)",
-				pointerEvents: "auto",
-				transform: "translate(-50%, -50%)",
-				...HANDLE_STYLE[handle]
-			}
-		}, handle))
-	});
-}
-//#endregion
 //#region src/ColorMode.tsx
 function FlowColorModeScope(props) {
 	const { colorMode, resolvedColorMode } = useFlowColorMode();
@@ -2098,4 +2212,4 @@ function useApplyFlowColorMode(element) {
 	]);
 }
 //#endregion
-export { Background, Controls, CrossBackground, DotsBackground, DragHandle, EntityAnchor, FLOW_BASE_CSS, FLOW_BASE_STYLES_ID, FlowColorModeScope, FlowInstanceProvider, FlowToolbar, LinesBackground, MiniMap, NodeResizer, PanePortal, Panel, Port, StatelyFlow, ViewportPortal, createFlowInstance, useApplyFlowColorMode, useConnection, useCreateFlowInstance, useFlow, useFlowBaseStyles, useFlowColorMode, useFlowConnections, useFlowContext, useFlowEdge, useFlowEntity, useFlowInput, useFlowInstance, useFlowMeasurement, useFlowNode, useFlowPort, useFlowSelector, useFlowToolbar, useFlowValue, useFlowView, useFlowViewport, useKeyPress, useMeasuredSize, useNodesInitialized, useOptionalFlowInstance };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/flow-react",
-  "version": "0.7.2",
+  "version": "0.9.2",
   "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.6.0",
-    "@statelyai/flow-dom": "3.2.1"
+    "@statelyai/flow": "0.8.2",
+    "@statelyai/flow-dom": "3.4.2"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",