@statelyai/flow-react 0.8.0 → 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, 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.
+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`.
 
@@ -53,9 +53,9 @@ 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                                             |
 | `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`                                           |
@@ -75,7 +75,11 @@ Color mode is store data, not engine behavior. `@statelyai/flow-dom` exports sma
 
 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, resize, 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.
+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.
 

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, ResizeHandle, Viewport, VisualPort } from "@statelyai/flow";
+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
@@ -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>;
@@ -329,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;
@@ -351,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
@@ -388,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:
@@ -444,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
@@ -474,7 +482,7 @@ declare function NodeResizer(props: NodeResizerProps): import("react").JSX.Eleme
  * - `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-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-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
@@ -491,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 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 };
+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;
@@ -403,6 +417,20 @@ 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;
@@ -442,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) {
@@ -517,11 +557,6 @@ function nodePaintEntriesEqual(a, b) {
 function classNames$1(...values) {
 	return values.filter(Boolean).join(" ");
 }
-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();
-}
 function assignRef(ref, value) {
 	if (typeof ref === "function") ref(value);
 	else if (ref) ref.current = value;
@@ -897,10 +932,11 @@ function SelectionBoundsLayer(props) {
 }
 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,
@@ -913,20 +949,22 @@ function EdgeLayer(props) {
 			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) {
@@ -970,7 +1008,10 @@ 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", {
@@ -1010,7 +1051,8 @@ const EdgeView = memo(function EdgeView(props) {
 			edge,
 			pathData,
 			attrs,
-			selected
+			selected,
+			markerPrefix: props.markerPrefix
 		})
 	});
 });
@@ -1042,6 +1084,7 @@ function ConnectionPreviewEdge(props) {
 			pathData,
 			attrs: {},
 			selected: false,
+			markerPrefix: props.markerPrefix,
 			preview: true
 		})
 	});
@@ -1053,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,
@@ -1074,6 +1119,52 @@ 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__ */ jsx(Fragment, { children: props.pathData.segments.map((segment, index) => {
 		return /* @__PURE__ */ jsx("path", {
@@ -1293,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 ? [] : [{
@@ -1328,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;
@@ -1445,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,
@@ -1461,7 +1529,10 @@ const NodeView = memo(function NodeView(props) {
 			"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, {
@@ -1469,20 +1540,27 @@ const NodeView = memo(function NodeView(props) {
 					dragging
 				}),
 				cursor: dragging ? "grabbing" : "grab",
-				pointerEvents: "auto",
+				pointerEvents: node.group && groupHasInteractiveContent ? "none" : "auto",
 				userSelect: "none",
 				zIndex: props.orderIndex,
 				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,
@@ -1548,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
 		},
@@ -1710,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) {
@@ -1735,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",
@@ -1858,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();
@@ -1879,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
@@ -2000,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;
@@ -2035,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
 	});
 }
@@ -2073,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();
@@ -2207,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, useFitViewExclusion, 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.8.0",
+  "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.7.0",
-    "@statelyai/flow-dom": "3.3.0"
+    "@statelyai/flow": "0.8.2",
+    "@statelyai/flow-dom": "3.4.2"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",