# React Flow Compatibility Audit

This document tracks `@ai-node-editor/core` against the current React Flow documentation while preserving an original implementation and an AI-workflow-first API.

Audit date: 2026-08-01

Reference version shown by the official documentation: React Flow 12.11.x

Official sources reviewed:

- API reference: https://reactflow.dev/api-reference
- Main component API: https://reactflow.dev/api-reference/react-flow
- Components: https://reactflow.dev/api-reference/components
- Hooks: https://reactflow.dev/api-reference/hooks
- Utilities: https://reactflow.dev/api-reference/utils
- Types: https://reactflow.dev/api-reference/types
- Examples catalog: https://reactflow.dev/examples
- Pro examples catalog: https://reactflow.dev/examples/pro-examples
- Accessibility: https://reactflow.dev/learn/advanced-use/accessibility
- Whiteboard features: https://reactflow.dev/learn/advanced-use/whiteboard
- React Flow UI catalog: https://reactflow.dev/ui

Important: React Flow Pro is not a separate runtime package. React Flow remains MIT licensed; Pro provides advanced examples, templates, and support. Our equivalents must be independently designed and implemented. We do not copy React Flow Pro source, private examples, visual assets, or proprietary templates.

## Status Legend

| Status | Meaning |
| --- | --- |
| Done | A supported equivalent is implemented and public or integrated. |
| Partial | The main path exists, but documented variants or public controls remain. |
| Planned | Confirmed gap with an implementation phase assigned below. |
| Native | The package solves the requirement automatically or through a different API. |

This is a behavioral compatibility target, not a promise that React Flow code can be pasted unchanged. Our graph, ports, execution engine, and React API remain provider-independent and AI-specific.

## Runtime And Interaction Surface

| Capability | AI Node Editor equivalent | Status |
| --- | --- | --- |
| Controlled graph | `graph`, `onGraphChange` | Done |
| Uncontrolled graph | `initialGraph` | Done |
| Custom node types | `NodeDefinition`, `renderNode`, plugins | Done |
| Custom handles | typed ports and `renderSocket` | Done |
| Custom edge types | `renderEdge`, `edge.type`, path utilities | Done |
| Input/default/output node roles | computed `nodeKind` and theme classes | Done |
| Group node role | `parentId`, group metadata, frame command | Partial |
| Bezier edge | `getBezierPath`, `edge.type = "bezier"` | Done |
| Straight edge | `getStraightPath`, `edge.type = "straight"` | Done |
| Step edge | `getStepPath`, `edge.type = "step"` | Done |
| Smooth-step edge | `getSmoothStepPath`, `edge.type = "smoothstep"` | Done |
| Simple bezier edge | `getSimpleBezierPath`, `edge.type = "simplebezier"` | Done |
| Edge labels | `edge.label`, `EdgeText` | Done |
| Edge arrow markers | `markerStart`, `markerEnd` | Done |
| Animated edges | dash, particle, pulse, packet, and node motion | Done |
| Edge interaction width | `edge.interactionWidth` | Done |
| Edge reconnection | draggable selected endpoints | Done |
| Per-node interaction flags | draggable/connectable/selectable/deletable/focusable/resizable | Done |
| Per-edge interaction flags | selectable/deletable/focusable/reconnectable | Done |
| Hidden nodes and edges | `hidden` | Done |
| Node origin | model field exists | Partial |
| Parent-relative positions | `parentId`, absolute-position resolver | Partial |
| Parent extent and expansion | model fields exist | Planned |
| Node/viewport extents | coordinate types exist | Planned |
| Drag nodes | pointer capture and independent node drag | Done |
| Multi-node drag | selected-node drag | Done |
| Box selection | Shift-drag or `selectionOnDrag` | Done |
| Full/partial selection mode | `selectionMode` | Done |
| Lasso selection | freeform selection | Planned |
| Pan | empty-canvas drag, middle/space behavior | Partial |
| Zoom at cursor | wheel/trackpad with browser zoom prevention | Done |
| Pan on scroll | direction and speed options | Planned |
| Pinch zoom | touch gesture | Planned |
| Double-click zoom | configurable gesture | Planned |
| Click/tap connection | click source then target | Planned |
| Drag connection | typed socket drag | Done |
| Strict connection mode | output to input | Done |
| Loose connection mode | source-to-source style connections | Planned |
| Connection validation | compatibility preview and blocking | Done |
| Connection events | callbacks for start/connect/end | Planned |
| Auto-pan while dragging/connecting/selecting | edge-of-viewport pan | Planned |
| Drag thresholds | node and connection thresholds | Planned |
| Snap to grid | option and temporary modifier | Done |
| Fit all / fit selection | controls, Home, F | Done |
| Visible-element culling | viewport culling | Planned |
| Save and restore | serialization and graph viewport | Done |
| Copy/cut/paste/duplicate | editor commands and shortcuts | Done |
| Undo/redo | command stack | Partial: core complete, editor integration pending |
| Context menu | searchable Add menu and actions | Done |
| Delete-middle-node flow preservation | `removeNodeAndReconnect` | Done |
| Proximity connect | geometry exists | Planned |
| Node intersections | `getIntersectingNodes`, `isNodeIntersecting` | Done |
| Edge/node intersections | node intersection complete | Partial |
| Keyboard node movement | arrows, Shift for grid distance | Done |
| Keyboard focus/select/delete | nodes and edges | Done |
| Localized ARIA strings | fixed English labels today | Planned |
| ARIA roles and DOM attributes | node/edge fields | Done |
| Live-region announcements | screen-reader movement/status messages | Planned |
| `nodrag`, `nopan`, `nowheel` escape classes | menu wheel isolation exists | Partial |
| Debug event logging | debug option and event inspector | Planned |

## Built-In Components

| React Flow component | AI Node Editor equivalent | Status |
| --- | --- | --- |
| `ReactFlow` | `AINodeEditor` | Done |
| `ReactFlowProvider` | provider integrated by `AINodeEditor` | Done |
| `Background` | `CanvasGrid` with dots/lines/cross | Done |
| `BaseEdge` | public `BaseEdge` | Done |
| `ControlButton` | custom controls child API | Planned |
| `Controls` | `ViewportControls` | Partial |
| `EdgeLabelRenderer` | public interactive HTML label renderer | Done |
| `EdgeText` | public `EdgeText` | Done |
| `EdgeToolbar` | public non-scaling `EdgeToolbar` | Done |
| `Handle` | `Socket` and `renderSocket` | Done |
| `MiniMap` | minimap with click-to-center | Done |
| `NodeResizeControl` | selected-node resize control | Done for diagram shapes; partial for standard nodes |
| `NodeResizer` | four-corner constrained shape resizing and width resizing for standard nodes | Partial: side-only handles pending |
| `NodeToolbar` | `NodeActionToolbar` | Done |
| `Panel` | public `EditorPanel` | Done |
| `ViewportPortal` | world-coordinate portal | Planned |

## Hooks And Instance API

| React Flow API | AI Node Editor equivalent | Status |
| --- | --- | --- |
| `useReactFlow` | `useAINodeEditor` | Partial: graph methods done, viewport methods pending |
| `useNodes` | `useEditorNodes` | Done |
| `useEdges` | `useEditorEdges` | Done |
| `useNodesState` | controlled graph + `applyNodeChanges` | Done |
| `useEdgesState` | controlled graph + `applyEdgeChanges` | Done |
| `useNodeId` | `useCurrentNodeId` | Done |
| `useNodesData` | `useEditorNodeData` | Done |
| `useNodeConnections` | `useNodeConnections` | Done |
| `useHandleConnections` | `useNodeConnections({ portId })` | Done |
| `useInternalNode` | `useEditorNodeData` | Partial |
| `useOnSelectionChange` | `useEditorSelection` and `onSelectionChange` | Done |
| `useConnection` | active connection subscription | Planned |
| `useKeyPress` | key-state hook | Planned |
| `useNodesInitialized` | measured-node readiness | Planned |
| `useOnViewportChange` | viewport lifecycle hook | Planned |
| `useViewport` | reactive viewport hook | Planned |
| `useStore` / `useStoreApi` | focused context hooks | Partial |
| `useUpdateNodeInternals` | automatic DOM socket remeasurement | Native |
| Instance graph getters/setters | `AINodeEditorApi` | Done |
| Instance add/update/delete | `AINodeEditorApi` | Done |
| Instance viewport helpers | zoom/center/fit/coordinate projection | Planned |
| Instance intersection helpers | public graph geometry utilities | Done |
| Instance `toObject` | `serializeGraph`, `getGraph` | Done |

## Utility Functions

| Utility | Status |
| --- | --- |
| `addEdge` | Done |
| `applyEdgeChanges` | Done |
| `applyNodeChanges` | Done |
| `getBezierPath` | Done |
| `getConnectedEdges` | Done |
| `getIncomers` | Done |
| `getNodesBounds` | Done |
| `getOutgoers` | Done |
| `getSimpleBezierPath` | Done |
| `getSmoothStepPath` | Done |
| `getStraightPath` | Done |
| `getViewportForBounds` | Done |
| `isEdge` | Done |
| `isNode` | Done |
| `reconnectEdge` | Done |

Additional AI Node Editor utilities include `applyGraphChanges`, `getEdgePath`, `getStepPath`, `getPolylinePath`, `getSelfLoopPath`, `getSmartEdgePath`, `getFloatingEdgePoints`, `planNodeInsertion`, `insertNodeIntoEdge`, `createTemporaryConnection`, `getNodeAbsolutePosition`, `getNodeRect`, `getIntersectingNodes`, `isNodeIntersecting`, `screenToGraphPosition`, `graphToScreenPosition`, `snapPosition`, and `removeNodeAndReconnect`.

## Official Free Examples Audit

| Example family | Status |
| --- | --- |
| Add node on edge drop | Done for connection drop on empty canvas menu |
| Connection limits | Done through `multiple` and compatibility validation |
| Custom/easy-connect nodes | Custom done; whole-node handle planned |
| Delete middle node | Done as utility; UI action planned |
| Drag handle | Partial through header drag; configurable selector planned |
| Intersections | Done |
| Node resizer and toolbar | Partial / Done |
| Proximity connect | Planned |
| Rotatable node | Possible through custom render/style; first-class control planned |
| Stress test | Rendering works; culling benchmark planned |
| Updating nodes | Done through API and inspector |
| Custom/animated edges | Done with type renderer maps and five animation modes |
| Delete edge on drop | Done through `deleteEdgeOnReconnectDrop` |
| Edge label and toolbar | Done |
| Floating edges | Done with boundary and cardinal-side modes |
| Edge markers and reconnection | Done, including custom SVG marker paths and per-end reconnect rules |
| Multi-connection line | Done through selected compatible sources |
| Temporary/ghost edges | Done through an internal endpoint node and public graph helpers |
| Computing flows | execution engine exceeds baseline | Done |
| Connection event sequence | Done with connect/reconnect/delete callbacks |
| Context menu | Done |
| Contextual zoom | custom renderer possible; helper planned |
| Drag and drop from sidebar | shape palette drag/drop and node library click-to-add | Done |
| Prevent cycles | Done |
| Save and restore | Done |
| Touch device connection | Planned |
| Validation | Done with suggestions |
| Sub-flows | Partial |
| Dagre/ELK integrations | adapter API planned; left-right layout done |
| Horizontal flow | Done |
| Node collision resolution | Planned |
| Base/dark/system styling | Done |
| Tailwind compatibility | CSS class hooks work; guide planned |
| Eraser, lasso, rectangle | Planned whiteboard module |
| Download image | Planned export adapter |

### Official edge examples

The edge example family was audited against the public official examples and reimplemented independently:

| Official example | AI Node Editor implementation | Status |
| --- | --- | --- |
| Animating edges | `Edge.animation`: dash, particle, pulse, packet, or existing-node motion | Done |
| Custom connection line | `renderConnectionPreview` with path, endpoints, validity, and message | Done |
| Custom edges | `renderEdge` or `edgeRenderers` plus `BaseEdge` | Done |
| Delete edge on drop | `deleteEdgeOnReconnectDrop` | Done |
| Edge label renderer | `EdgeLabelRenderer` and `edge.labels` | Done |
| Edge intersection | `enableAutoInsertOnEdge` highlights and splits a compatible edge | Done |
| Edge toolbar | non-scaling `EdgeToolbar` with live viewport context | Done |
| Edge types | bezier, straight, step, smooth-step, simple bezier, orthogonal, smart, editable, floating, self | Done |
| Edge routing | original grid A* router with padding, bend cost, node avoidance, and bounded work | Done |
| Floating edges | exact rectangle-boundary intersection | Done |
| Markers | start/end, open/closed, custom paths, color, size, orientation, marker units | Done |
| Multi-connection line | compatible previews and connections from selected sources | Done |
| Reconnect edge | source, target, both, or disabled per edge | Done |
| Simple floating edges | nearest cardinal-side endpoint mode | Done |
| Temporary edges | reconnectable incomplete endpoint retained on empty-canvas drop | Done |
| Editable edge | draggable waypoints, double-click insertion, and Space-drawn freeform paths | Done |

## Pro Examples Audit

These are independently implemented behavior targets, not copied examples.

| Pro example | Current status | Planned home |
| --- | --- | --- |
| Node position animation | Existing-node motion along an edge is done; general layout transitions remain planned | Mixed |
| Flowchart shapes | Ten original SVG presets, duplex handles, color/shape toolbar, drag palette, resizing, and shape-aware minimap | Done |
| Editable edge control points | Done with serializable waypoints and freeform drawing | Done |
| Advanced edge routing | Done with an original bounded grid router; optional adapters can still be added | Done |
| Helper alignment lines | Planned | interaction module |
| Collaboration with Yjs | Planned | optional collaboration adapter |
| Copy and paste | Done | core editor |
| Undo and redo | Partial | command-backed editor integration |
| Selection grouping | Partial | grouping module |
| Dynamic parent/child relation | Partial | grouping module |
| Expand and collapse hierarchy | Planned | layout module |
| Multi-engine auto layout | Planned | optional adapters |
| Force layout | Planned | optional adapter |
| Dynamic layouting | Planned | layout controller |
| Freehand drawing | Planned | whiteboard module |
| Server-side image creation | Planned | SSR/export package |

## React Flow UI Catalog

React Flow UI is a shadcn/Tailwind component catalog rather than core runtime behavior. Our equivalents are original and framework-neutral so the core keeps zero Tailwind, shadcn, Zustand, Next.js, and provider dependencies. Version 0.3.0 includes a searchable `WorkflowTemplateGallery`, ten free AI-specific workflow starters, isolated template instantiation, catalog filters, and custom card rendering. Future optional UI packs can add more node shells, labeled sockets, status nodes, button edges, tooltips, and search controls without changing the graph engine.

## Delivery Phases

### Phase A: foundational parity - completed in 0.1.x

- controlled/uncontrolled editor,
- custom nodes/sockets/edges,
- background, controls, minimap, panel,
- five edge path types,
- edge labels, markers, animation, reconnection,
- box and multi-selection,
- change-set and geometry utilities,
- public graph hooks and API,
- AI validation, execution, registry, plugins, themes.

### Phase B: viewport and event parity

- controlled viewport and viewport hooks,
- complete instance viewport methods,
- connection/node/edge/pane lifecycle callbacks,
- auto-pan, pan-on-scroll, pinch, double-click zoom,
- configurable key codes and interaction thresholds,
- viewport portal and edge label portal,
- visible-element culling.

### Phase C: grouping and editing parity

- true group/frame nodes and parent extents,
- dynamic attach/detach,
- eight-direction resizing with constraints,
- richer group/frame containment and parent extents,
- helper lines and collision handling,
- complete undo/redo integration,
- lasso, eraser, rectangle, and freehand tools.

### Phase D: advanced and Pro-equivalent accelerators

- layout adapter interfaces for Dagre, ELK, hierarchy, and force engines,
- animated layout transitions and expand/collapse,
- collaboration adapter contract with presence metadata,
- image/export and SSR utilities,
- original flowchart/UI preset pack,
- performance benchmark suite for hundreds and thousands of elements.

## Release Gate

A feature is only moved to Done when it has:

1. public TypeScript API or an intentionally documented integrated behavior,
2. editor implementation where applicable,
3. tests for core logic,
4. README usage documentation,
5. successful typecheck, tests, build, and package dry run.