@dschz/solid-flow 0.3.0-next.4 → 0.3.0-next.5

package/README.md

@@ -1,100 +1,69 @@
 <p align="center">
-  <img src="https://assets.solidjs.com/banner?project=solid-flow&type=Ecosystem&background=tiles" alt="@dschz/solid-flow banner" />
+  <!-- the %20%20 suffix works around a banner-generator bug that clips a trailing W -->
+  <img src="https://assets.solidjs.com/banner?project=solid-flow%20%20&type=Ecosystem&background=tiles" alt="@dschz/solid-flow banner" />
 </p>
 
 # Solid Flow
 
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![npm](https://img.shields.io/npm/v/@dschz/solid-flow?color=blue)](https://www.npmjs.com/package/@dschz/solid-flow)
+[![JSR](https://jsr.io/badges/@dschz/solid-flow)](https://jsr.io/@dschz/solid-flow)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@dschz/solid-flow)](https://bundlephobia.com/package/@dschz/solid-flow)
 [![CI](https://github.com/dsnchz/solid-flow/actions/workflows/ci.yaml/badge.svg)](https://github.com/dsnchz/solid-flow/actions/workflows/ci.yaml)
 
-> Solid Flow is a port of [React Flow](https://reactflow.dev/) and [Svelte Flow](https://svelteflow.dev/) for SolidJS.
+A SolidJS port of [React Flow](https://reactflow.dev/) and [Svelte Flow](https://svelteflow.dev/): build node-based editors, diagrams, and interactive graphs with the same battle-tested gesture system ([@xyflow/system](https://github.com/xyflow/xyflow)) and an API designed around Solid's fine-grained reactivity.
 
-☣️ **Solid Flow is alpha and currently under development. The API intends to follow React/Svelte Flow closely but some things might change for the sake of SolidJS.** ☣️
+## Version pairing
 
-## Current Unsupported Features:
+| Solid Flow | SolidJS         | Status              |
+| ---------- | --------------- | ------------------- |
+| `0.3.x`    | `solid-js` 2.x  | Active development  |
+| `0.2.x`    | `solid-js` 1.9+ | Maintenance (fixes) |
 
-- [onlyRenderVisibleElements](https://github.com/dsnchz/solid-flow/issues/15): render only visible elements.
-- [Custom MiniMap Nodes](https://github.com/dsnchz/solid-flow/issues/12): define custom minimap jsx node elements.
-- [Edge Reconnect Anchors](https://github.com/dsnchz/solid-flow/issues/13): the ability to re-connect already connected edges.
+The 0.3 line is built for SolidJS 2.0 and its deferred, fine-grained reactive graph. Keep `solid-js` and `@solidjs/web` on matching 2.0 versions — mixing them breaks at import time. Upgrading from 0.2.x? See [Migrating from 0.2.x](#migrating-from-02x).
 
 ## Key Features
 
-- **Easy to use:** Seamless zooming and panning, single- and multi selection of graph elements and keyboard shortcuts are supported out of the box
-- **Customizable:** Different node types (Input, Output, Default, Group) and edge types (Bezier, Straight, Step, SmoothStep) with full support for custom nodes and edges
-- **Fast rendering:** Only nodes that have changed are re-rendered using SolidJS's fine-grained reactivity
-- **Rich Plugin Ecosystem:** Background patterns, Interactive MiniMap, Zoom Controls, Node Toolbar, and Node Resizer components
-- **Powerful Hooks:** Comprehensive set of reactive hooks for nodes, edges, viewport, connections, and data management
-- **Full Accessibility:** Complete keyboard navigation, screen reader support, ARIA labels, and focus management
-- **Drag & Drop:** Built-in dragging for nodes, external drag-and-drop support, and customizable drag handles
-- **Advanced Features:** Node grouping, intersection detection, connection validation, and subflow support
-- **TypeScript First:** Fully typed API with generic type support and IntelliSense integration
+- **Easy to use:** Zooming and panning, single- and multi-selection of graph elements, and keyboard shortcuts out of the box
+- **Customizable:** Built-in node types (Input, Output, Default, Group) and edge types (Bezier, Straight, Step, SmoothStep) with full support for custom nodes and edges — including edge reconnection via `EdgeReconnectAnchor`
+- **Fine-grained by construction:** A node drag is a handful of DOM attribute writes — no virtual DOM, no component re-renders, no memoization ceremony
+- **Scales to large graphs:** Off-screen elements are viewport-culled by default, and an opt-in `onlyRenderVisibleElements` mode only mounts what's visible — stress-tested at 10,000 nodes
+- **Type-guided data:** Your custom components are the schema — node/edge stores narrow each element's `data` by its `type` field, with autocomplete for type names
+- **Rich plugins:** Background patterns, interactive MiniMap (custom minimap nodes, click handlers), zoom Controls, Node Toolbar, and Node Resizer
+- **Accessible:** Keyboard navigation, screen reader support, ARIA labels, and focus management
+- **SSR-ready:** Renders on the server (a dedicated SSR test lane keeps it that way)
 
 ## Installation
 
-The easiest way to get the latest version of Solid Flow is to install it via npm, yarn or pnpm:
-
 ```sh
-npm install @dschz/solid-flow
-pnpm install @dschz/solid-flow
-yarn install @dschz/solid-flow
-bun install @dschz/solid-flow
+npm  install @dschz/solid-flow
+pnpm add     @dschz/solid-flow
+yarn add     @dschz/solid-flow
+bun  add     @dschz/solid-flow
 ```
 
-## Quick Start
+`solid-js` is a peer dependency. Also available on [JSR](https://jsr.io/@dschz/solid-flow).
 
-This is a basic example to get you started. For more advanced examples and full API documentation, explore the playground examples included in this repository.
+## Quick Start
 
 ```tsx
 import {
-  SolidFlow,
-  SolidFlowProvider,
-  Controls,
   Background,
-  MiniMap,
-  addEdge,
-  type EdgeConnection,
+  Controls,
   createEdgeStore,
   createNodeStore,
-  type Viewport,
+  type EdgeConnection,
+  MiniMap,
+  Panel,
+  SolidFlow,
 } from "@dschz/solid-flow";
-import "@dschz/solid-flow/styles"; // Required styles
-
-import { createStore, produce } from "solid-js/store";
-
-export default function Page() {
-  return (
-    <SolidFlowProvider>
-      <Flow />
-    </SolidFlowProvider>
-  )
-}
-
-function Flow() {
-  // Can invoke useSolidFlow due to parent Page + SolidFlowProvider wrapper. Contains all helper APIs
-  const { .. } = useSolidFlow();
+import "@dschz/solid-flow/styles"; // required styles, import once
 
-  // Use createNodeStore and createEdgeStore for reactive state management
+export const Flow = () => {
   const [nodes, setNodes] = createNodeStore([
-    {
-      id: "1",
-      type: "input",
-      data: { label: "Input Node" },
-      position: { x: 250, y: 0 },
-    },
-    {
-      id: "2",
-      type: "default",
-      data: { label: "Default Node" },
-      position: { x: 100, y: 100 },
-    },
-    {
-      id: "3",
-      type: "output",
-      data: { label: "Output Node" },
-      position: { x: 250, y: 200 },
-    },
+    { id: "1", type: "input", data: { label: "Input" }, position: { x: 250, y: 0 } },
+    { id: "2", type: "default", data: { label: "Default" }, position: { x: 100, y: 100 } },
+    { id: "3", type: "output", data: { label: "Output" }, position: { x: 250, y: 200 } },
   ]);
 
   const [edges, setEdges] = createEdgeStore([
@@ -102,234 +71,269 @@ function Flow() {
     { id: "e2-3", source: "2", target: "3" },
   ]);
 
-  const [viewport, setViewport] = createStore<Viewport>({
-    x: 100,
-    y: 100,
-    zoom: 5,
-  });
-
-  const updateViewport = () => {
-    setViewport("x", (prev) => prev + 10);
+  // Your stores own which elements exist — adopt new connections into
+  // your edge store (see "Who owns the data" below).
+  const onConnect = (connection: EdgeConnection) => {
+    setEdges((edges) => {
+      edges.push(connection);
+    });
   };
 
-  const onConnect = (connection: EdgeConnection) => {
-    /**
-     * Solid Flow updates the node/edge stores internally. The user-land edge store will have the connection inserted by the time onConnect fires so we can just go ahead and update the state of it
-     */
-    setEdges(
-      (edge) => edge.id === connection.id,
-      produce((edge) => {
-        edge.animated = true;
-      }),
-    );
+  const nudge = () => {
+    // SolidJS 2.0 store writes are drafts: mutate what changed.
+    setNodes((nodes) => {
+      nodes[0]!.position.x += 20;
+    });
   };
 
   return (
     <SolidFlow nodes={nodes} edges={edges} onConnect={onConnect} fitView>
       <Controls />
       <MiniMap />
+      <Background variant="dots" />
       <Panel position="top-left">
-        <button onClick={updateViewport}>Update viewport</button>
+        <button onClick={nudge}>Nudge first node</button>
       </Panel>
-      <Background variant="dots" />
     </SolidFlow>
   );
-}
+};
 ```
 
-## Core Components
-
-### Built-in Node Types
+## Your components are the schema
 
-- **InputNode** - Nodes with source handles only (starting points)
-- **OutputNode** - Nodes with target handles only (ending points)
-- **DefaultNode** - Standard nodes with both source and target handles
-- **GroupNode** - Container nodes for organizing other nodes
+`createNodeStore` / `createEdgeStore` derive each element's `data` type from the component registered for its `type` — the renderer map is the single source of truth, and the stores narrow against it:
 
-### Built-in Edge Types
+```tsx
+import {
+  createNodeStore,
+  Handle,
+  type NodeProps,
+  type NodeTypes,
+  Position,
+} from "@dschz/solid-flow";
 
-- **BezierEdge** - Smooth curved connections (default)
-- **StraightEdge** - Direct straight line connections
-- **StepEdge** - Right-angle step connections
-- **SmoothStepEdge** - Rounded step connections
+const CounterNode = (props: NodeProps<{ count: number }, "counter">) => (
+  <div style={{ padding: "10px", background: "white", border: "1px solid #333" }}>
+    <Handle type="target" position={Position.Top} />
+    <div>count: {props.data.count}</div>
+    <Handle type="source" position={Position.Bottom} />
+  </div>
+);
 
-### Plugin Components
+const nodeTypes = { counter: CounterNode } satisfies NodeTypes;
 
-- **Background** - Customizable canvas backgrounds (dots, lines, cross patterns)
-- **Controls** - Zoom in/out, fit view, lock/unlock interactions
-- **MiniMap** - Interactive overview with viewport indicator
-- **NodeToolbar** - Context-sensitive toolbars for nodes
-- **NodeResizer** - Real-time node resizing with handles
+const [nodes] = createNodeStore<typeof nodeTypes>([
+  // "counter" narrows data to { count: number }; built-ins still work
+  { id: "a", type: "counter", data: { count: 1 }, position: { x: 0, y: 0 } },
+  { id: "b", type: "default", data: { label: "hi" }, position: { x: 0, y: 100 } },
+  // { id: "c", type: "countr", ... }   <-- compile error: unknown type name
+]);
 
-## Hooks & Utilities
+<SolidFlow nodes={nodes} nodeTypes={nodeTypes} />;
+```
 
-### Essential Hooks
+The same guided unions are exported as standalone types, so plain arrays, props, and vanilla stores get identical narrowing:
 
 ```tsx
-// Main flow instance with full API
-const solidFlow = useSolidFlow();
+import type { EdgesFor, NodesFor } from "@dschz/solid-flow";
 
-// Reactive access to nodes and edges
-const nodes = useNodes();
-const edges = useEdges();
+const initialNodes = [
+  { id: "a", type: "counter", data: { count: 1 }, position: { x: 0, y: 0 } },
+] satisfies NodesFor<typeof nodeTypes>[];
+```
 
-// Viewport control and monitoring
-const viewport = useViewport();
+## Who owns the data
 
-// Connection state during drag operations
-const connection = useConnection();
+The stores you pass as `nodes` / `edges` props are **controlled** — a deliberate contract:
 
-// Reactive access to node data
-const nodeData = useNodesData(["node-1", "node-2"]);
+- **Your store owns membership.** Which nodes and edges exist is decided by your store. Any write form works: draft mutations update in place (`O(changed)`), and wholesale replacement (`setNodes(() => next)`) re-seeds the flow — rows are keyed by `id`, so surviving elements keep their runtime state.
+- **The flow writes runtime fields onto your rows.** Dragging updates `position`, selection updates `selected`, measurement fills `measured` — on the same objects you provided, so reading your store is always live.
+- **Imperative commands don't write membership back.** `commands.addNodes(...)` and friends update the flow, not your store. To keep an element across a store replacement, adopt it — like the `onConnect` handler in the Quick Start pushing the new connection into the edge store.
 
-// Node connection information
-const connections = useNodeConnections("node-1");
+## The flow API
 
-// Which node/edge a nested component is rendered inside (for building
-// composable custom nodes and edge labels without prop drilling)
-const nodeId = useNodeId();
-const edgeId = useEdgeId();
-```
+`useSolidFlow()` returns `{ flow, commands }` (with `commands` also spread at the top level for React/Svelte Flow familiarity). Both are stable identities — destructuring is safe.
 
-#### Coming from React Flow?
+```tsx
+import { SolidFlowProvider, useSolidFlow } from "@dschz/solid-flow";
 
-Some React Flow hooks intentionally have no Solid Flow equivalent, because
-Solid's fine-grained reactivity makes them unnecessary:
+const Toolbar = () => {
+  const { flow, commands } = useSolidFlow();
 
-- `useOnSelectionChange` / `useOnViewportChange` — reading `flow.selection`
-  or `flow.viewport` (from `useSolidFlow()`) in a tracked scope IS the
-  subscription; wrap side effects in `createEffect` over those reads.
-- `useNodesState` / `useEdgesState` — use `createNodeStore` /
-  `createEdgeStore` instead.
-- `useStore` — the reactive `flow` struct is the supported read surface;
-  there is no public escape hatch into internals.
+  // flow.* reads are reactive: use them in JSX or tracked scopes.
+  // flow.nodes, flow.edges, flow.viewport, flow.selection,
+  // flow.nodesInitialized, flow.viewportInitialized, ...
 
-### Utility Functions
+  return (
+    <div>
+      <span>{flow.selection.nodes.length} selected</span>
+      <button onClick={() => commands.fitView()}>Fit</button>
+      <button onClick={() => commands.zoomIn()}>+</button>
+    </div>
+  );
+};
 
-```tsx
-// Create reactive stores (replaces signals)
-const [nodes, setNodes] = createNodeStore(initialNodes);
-const [edges, setEdges] = createEdgeStore(initialEdges);
-
-// Update stores with SolidJS patterns
-import { produce } from "solid-js/store";
-setNodes(
-  (node) => node.id === "1",
-  produce((node) => {
-    node.position.x += 20;
-  }),
+// Hooks used outside <SolidFlow> children need a provider:
+export const App = () => (
+  <SolidFlowProvider>
+    <Toolbar />
+    <Flow />
+  </SolidFlowProvider>
 );
+```
 
-// Add new connections
-setEdges(addEdge(connection, edges));
+Commands include viewport control (`fitView`, `fitBounds`, `zoomIn`/`zoomOut`, `setZoom`, `setCenter`, `setViewport`, `panBy`), element updates (`updateNode`, `updateNodeData`, `updateEdge`, `addNodes`, `addEdges`, `deleteElements`), coordinate conversion (`screenToFlowPosition`, `flowToScreenPosition`), and geometry queries (`isNodeIntersecting`, `getIntersectingNodes`).
 
-// Coordinate transformations (via useSolidFlow)
-const { screenToFlowPosition, flowToScreenPosition } = useSolidFlow();
+## Hooks
 
-// Node/edge utilities
-getNodesBounds(nodes);
-getIntersectingNodes(node, nodes);
+```tsx
+const solidFlow = useSolidFlow(); // { flow, commands } — the main API
+const nodes = useNodes(); // reactive readonly node array
+const edges = useEdges(); // reactive readonly edge array
+const viewport = useViewport(); // reactive viewport accessor
+const connection = useConnection(); // in-progress connection state
+
+// Hook parameters that feed reactive reads are accessors, so they can't
+// silently go stale when derived from props:
+const nodeData = useNodesData(() => ["node-1", "node-2"]);
+const connections = useNodeConnections(() => ({ id: "node-1" }));
+const internal = useInternalNode(() => props.nodeId); // measured/internal record
+
+const updateInternals = useUpdateNodeInternals(); // re-measure after handle changes
+
+// Which node/edge a nested component is rendered inside — for composable
+// custom nodes and edge labels without prop drilling:
+const nodeId = useNodeId();
+const edgeId = useEdgeId();
 ```
 
-## Advanced Features
+### Coming from React Flow?
 
-### Custom Nodes and Edges
+Some React Flow hooks intentionally have no Solid Flow equivalent, because Solid's fine-grained reactivity makes them unnecessary:
 
-Create fully customized components with multiple handles:
+- `useOnSelectionChange` / `useOnViewportChange` — reading `flow.selection` or `flow.viewport` in a tracked scope IS the subscription; wrap side effects in `createEffect` over those reads.
+- `useNodesState` / `useEdgesState` — use `createNodeStore` / `createEdgeStore` instead.
+- `useStore` — the reactive `flow` struct is the supported read surface; there is no public escape hatch into internals.
+
+## Custom edges and reconnection
 
 ```tsx
-import { Handle, type NodeProps } from "@dschz/solid-flow";
+import { BaseEdge, EdgeReconnectAnchor, type EdgeProps, getBezierPath } from "@dschz/solid-flow";
+
+const ReconnectableEdge = (props: EdgeProps) => {
+  const path = () =>
+    getBezierPath({
+      sourceX: props.sourceX,
+      sourceY: props.sourceY,
+      sourcePosition: props.sourcePosition,
+      targetX: props.targetX,
+      targetY: props.targetY,
+      targetPosition: props.targetPosition,
+    })[0];
 
-// Type-safe custom node component
-function CustomNode(props: NodeProps<{ label: string }, "custom">) {
   return (
-    <div class="custom-node" style={{ padding: "10px", background: "white" }}>
-      <Handle type="target" position="top" />
-      <div>{props.data.label}</div>
-      <Handle type="source" position="bottom" id="output-a" />
-      <Handle type="source" position="bottom" id="output-b" style={{ left: "80%" }} />
-    </div>
+    <>
+      <BaseEdge path={path()} markerEnd={props.markerEnd} />
+      {/* drag either end of a selected edge onto another handle */}
+      <EdgeReconnectAnchor type="source" position={{ x: props.sourceX, y: props.sourceY }} />
+      <EdgeReconnectAnchor type="target" position={{ x: props.targetX, y: props.targetY }} />
+    </>
   );
-}
+};
+```
 
-// Create type-safe node types
-const nodeTypes = {
-  custom: CustomNode,
-} satisfies NodeTypes;
+Reconnection lifecycle callbacks (`onReconnectStart`, `onReconnect`, `onReconnectEnd`, `onBeforeReconnect`) are available on `<SolidFlow>`.
 
-// Use with typed store
-const [nodes] = createNodeStore<typeof nodeTypes>([...]);
+## Built-in components
 
-<SolidFlow nodeTypes={nodeTypes} nodes={nodes} ... />
-```
+**Node types:** `input` (source handle only), `output` (target handle only), `default` (both), `group` (container for subflows)
 
-### Connection Validation
+**Edge types:** `default` (bezier), `straight`, `step`, `smoothstep`
 
-```tsx
-import { type Connection } from "@dschz/solid-flow";
+**Plugins:**
 
-const isValidConnection = (connection: Connection) => {
-  // Custom validation logic
-  return connection.source !== connection.target;
-};
+- **Background** — dots, lines, and cross patterns
+- **Controls** — zoom in/out, fit view, lock interactions
+- **MiniMap** — interactive overview with viewport indicator, custom node rendering via `nodeComponent`, and `onClick` / `onNodeClick` handlers
+- **NodeToolbar** — context-sensitive toolbars for nodes
+- **NodeResizer** — interactive node resizing with handles
 
-const onConnect = (connection: Connection) => {
-  console.log("New connection:", connection);
-  setEdges(addEdge(connection, edges));
-};
+## Performance
 
-<SolidFlow
-  isValidConnection={isValidConnection}
-  onConnect={onConnect}
-  ...
-/>
-```
+Two complementary culling tiers keep large graphs fast:
 
-### Event Handling
+- **CSS culling (always on):** Elements outside the (overscanned) viewport are hidden with `visibility: hidden` + `pointer-events: none`. Everything stays mounted, so component state, measurement, and accessibility semantics are untouched — this tier has no userland contract at all.
+- **`onlyRenderVisibleElements` (opt-in):** Off-screen elements are **unmounted entirely** and remount as the viewport reaches them. At 10,000 nodes this cuts the DOM ~16x, roughly halves memory, and makes node drags several times faster. Positions, selection, and cached measurements live in the flow's data graph — outside your components — so elements come back exactly as they left. Component-_local_ state does not survive unmounting: keep state you care about in `node.data`. Selected elements, unmeasured nodes, and the node holding focus are never unmounted — and an element whose content must keep running off-screen (media, timers, embeds) can opt out of culling entirely with `cullable: false` on the node or edge.
 
-```tsx
-<SolidFlow
-  onNodeClick={(event, node) => console.log("Node clicked:", node)}
-  onNodeDrag={(event, node) => console.log("Node dragged:", node)}
-  onEdgeClick={(event, edge) => console.log("Edge clicked:", edge)}
-  onPaneClick={(event) => console.log("Pane clicked")}
-  onSelectionChange={(params) => console.log("Selection changed:", params)}
-/>
-```
+The MiniMap always renders the full graph in either mode — it reads the data graph, not the DOM.
+
+## Server-side rendering
+
+`<SolidFlow>` renders with `renderToString` and hydrates cleanly. For meaningful server-rendered layout, give nodes explicit `width` / `height` (there is no DOM to measure on the server) — the same guidance as React/Svelte Flow.
 
 ## Accessibility
 
-Solid Flow includes comprehensive accessibility features:
+- Full keyboard navigation (arrow-key node movement, focus traversal, Escape to deselect)
+- Screen reader support with ARIA labels and live announcements
+- Focus management, including under viewport culling
+- Color mode support (`light` / `dark` / `system`)
 
-- Full keyboard navigation support
-- Screen reader compatibility with ARIA labels
-- Focus management and visual indicators
-- High contrast and color mode support
-- Customizable keyboard shortcuts
+## Migrating from 0.2.x
 
-## Performance
+The 0.3 line targets SolidJS 2.0, which changes how you write to stores, and reworks the read API. The gestures, components, plugins, and commands are otherwise the same.
 
-- **Reactive Updates**: Only re-renders components when their specific data changes
-- **Viewport Optimization**: Option to render only visible elements (coming soon)
-- **Memory Efficient**: Optimized data structures for large graphs
-- **Stress Tested**: Handles hundreds of nodes smoothly
+**1. Upgrade the peer dependencies.** `solid-js` and `@solidjs/web` move to matching 2.0 versions.
 
-## Examples
+**2. Store writes: path setters are gone (SolidJS 2.0).** Every `setNodes` / `setEdges` call site using 1.x path syntax becomes a draft callback — the callback's argument is a mutable draft, so mutation is the API. Returning a value instead replaces wholesale.
+
+```tsx
+// 0.2.x (SolidJS 1.x) — path syntax
+setNodes(0, "position", "x", (x) => x + 20);
+setEdges((edge) => edge.id === "e1", "animated", true);
+
+// 0.3.x (SolidJS 2.0) — draft callback
+setNodes((nodes) => {
+  nodes[0]!.position.x += 20;
+});
+setEdges((edges) => {
+  const edge = edges.find((e) => e.id === "e1");
+  if (edge) edge.animated = true;
+});
+
+// wholesale replacement (re-seeds the flow; rows keyed by id are reused)
+setNodes(() => nextNodes);
+```
+
+**3. `useSolidFlow` reads moved to the reactive `flow` struct.** The flat getters (`getNodes()`, `getEdges()`, `getNode(id)`, `getEdge(id)`, `getInternalNode(id)`, `getViewport()`, `getZoom()`) are removed:
+
+```tsx
+// 0.2.x                          // 0.3.x
+solidFlow.getNodes();
+flow.nodes;
+solidFlow.getViewport();
+flow.viewport;
+solidFlow.getZoom();
+flow.viewport.zoom;
+solidFlow.getNode("a");
+flow.nodes.find((n) => n.id === "a");
+solidFlow.getInternalNode("a");
+useInternalNode(() => "a");
+```
 
-The repository includes a comprehensive playground with 25+ examples:
+`flow.*` reads are reactive — using them in JSX or a tracked scope subscribes. Commands (`fitView`, `setViewport`, `updateNode`, `deleteElements`, ...) are unchanged and now also available namespaced under `commands`.
 
-- **Basic Usage** - Simple flows and interactions
-- **Custom Nodes** - Creating specialized node types
-- **Edge Types** - Different connection styles
-- **Drag & Drop** - External elements and node creation
-- **Validation** - Connection rules and constraints
-- **Subflows** - Hierarchical node organization
-- **Performance** - Large dataset handling
-- **Accessibility** - Keyboard navigation and screen readers
+**4. New connections are no longer written into your edge store.** In 0.2.x the flow inserted the connected edge into your store before `onConnect` fired. Under 0.3's ownership contract your store owns membership: adopt the connection yourself (see the Quick Start's `onConnect`). Unadopted connections still render, but won't survive a wholesale store replacement.
 
-Run the examples locally:
+**5. `onlyRenderVisibleElements` now does what it says.** In 0.2.x the prop was accepted but inert. In 0.3 it opts into unmount culling (off-screen elements are not mounted at all — see [Performance](#performance)), while the CSS culling tier is always on and needs no prop.
+
+**6. Smaller signature changes.** `useNodes()` / `useEdges()` return `readonly` arrays; `useHandleEdgeSelect` is removed (it was internal plumbing — select edges through `commands`).
+
+## Examples
+
+The repository ships a playground with 25+ runnable examples — custom nodes and edges, edge reconnection, drag & drop, subflows, validation, minimap customization, a 10k-node stress test, accessibility, and more:
 
 ```bash
+bun install
 bun start
 ```
 
@@ -359,6 +363,14 @@ bun install
 bun start
 ```
 
+### Testing
+
+```bash
+bun run test      # unit + component tests (vitest, jsdom)
+bun run test:ssr  # SSR lane (node environment, server builds)
+bun run test:e2e  # browser gesture harness (Playwright)
+```
+
 ### Linting & Formatting
 
 ```bash

package/dist/index/index.d.ts

@@ -21,6 +21,14 @@ type Node<NodeData extends UnknownStruct = UnknownStruct, NodeType extends strin
   class?: string;
   style?: JSX.CSSProperties;
   focusable?: boolean;
+  /**
+   * When `false`, the node is exempt from viewport culling on both tiers:
+   * the always-on CSS tier never hides it and `onlyRenderVisibleElements`
+   * never unmounts it. Use for nodes whose content must keep running while
+   * off-screen (media playback, timers, third-party embeds).
+   * @default true
+   */
+  cullable?: boolean;
   /**
    * The ARIA role attribute for the node element, used for accessibility.
    * @default "group"
@@ -72,6 +80,13 @@ type Edge<EdgeData extends UnknownStruct = UnknownStruct, EdgeType extends strin
   style?: JSX.CSSProperties;
   class?: string;
   focusable?: boolean;
+  /**
+   * When `false`, the edge is exempt from viewport culling on both tiers:
+   * the always-on CSS tier never hides it and `onlyRenderVisibleElements`
+   * never unmounts it.
+   * @default true
+   */
+  cullable?: boolean;
   /**
    * The ARIA role attribute for the edge, used for accessibility.
    * @default "group"
@@ -866,7 +881,10 @@ type SolidFlowProps<NodeType extends Node = Node, EdgeType extends Edge = Edge>
    * Component-LOCAL state does not survive — signals created inside a
    * custom node, uncontrolled inputs, scroll positions of inner elements.
    * Keep state you care about in `node.data`. Never unmounted: selected
-   * elements, unmeasured nodes, and the node holding DOM focus.
+   * elements, unmeasured nodes, and the node holding DOM focus. Elements
+   * whose component-local state (or side effects) must keep running while
+   * off-screen can opt out entirely with `cullable: false` on the node or
+   * edge — they are then exempt from both tiers.
    *
    * Independent of this prop, off-viewport elements are always CSS-culled
    * (`visibility: hidden` + `pointer-events: none`, everything stays

package/dist/index/index.js

@@ -430,9 +430,9 @@ const A11yDescriptions = () => {
 		height: 2 * halfHeight
 	};
 }, { equals: rectsEqual }), isNodeCulled = (node, cullingViewport) => {
-	if (!cullingViewport || node.selected) return !1;
+	if (!cullingViewport || node.selected || node.cullable === !1) return !1;
 	let { width, height } = node.measured;
-	if (!width || !height) return !1;
+	if (!width || !height || !node.internals.handleBounds) return !1;
 	let { x, y } = node.internals.positionAbsolute;
 	return !rectsOverlap({
 		x,
@@ -441,7 +441,7 @@ const A11yDescriptions = () => {
 		height
 	}, cullingViewport);
 }, isEdgeCulled = (row, cullingViewport) => {
-	if (!cullingViewport || row.selected) return !1;
+	if (!cullingViewport || row.selected || row.cullable === !1) return !1;
 	let x = Math.min(row.sourceX, row.targetX), y = Math.min(row.sourceY, row.targetY);
 	return !rectsOverlap({
 		x,
@@ -3278,6 +3278,34 @@ function matchesKey(event, keyDef) {
 function matchesKeyArray(event, keyDefs) {
 	return keyDefs ? (Array.isArray(keyDefs) ? keyDefs : [keyDefs]).some((keyDef) => matchesKey(event, keyDef)) : !1;
 }
+const MODIFIER_FLAG = {
+	alt: "altKey",
+	control: "ctrlKey",
+	ctrl: "ctrlKey",
+	meta: "metaKey",
+	shift: "shiftKey"
+};
+/**
+* Whether an event's modifier flags PROVE this key definition cannot be held
+* right now: the key itself is a modifier whose flag is off, or one of its
+* required modifiers is off. Definitions built on non-modifier keys are never
+* contradicted (their state isn't derivable from flags).
+*/
+function isContradicted(flags, keyDef) {
+	let keyFlag = MODIFIER_FLAG[getKeyString(keyDef).toLowerCase()];
+	if (keyFlag && !flags[keyFlag]) return !0;
+	let modifiers = getModifier(keyDef);
+	return (Array.isArray(modifiers) ? modifiers.flatMap((mod) => mod) : [modifiers]).some((mod) => {
+		let modFlag = MODIFIER_FLAG[mod.toLowerCase()];
+		return !!modFlag && !flags[modFlag];
+	});
+}
+/** True only when EVERY definition for this key state is contradicted. */
+function allContradicted(flags, keyDefs) {
+	if (!keyDefs) return !1;
+	let keys = Array.isArray(keyDefs) ? keyDefs : [keyDefs];
+	return keys.length > 0 && keys.every((keyDef) => isContradicted(flags, keyDef));
+}
 const KeyHandler = (props) => {
 	let { store, actions } = useInternalSolidFlow(), { deleteElements } = useSolidFlow(), _props = {
 		get selectionKey() {
@@ -3297,6 +3325,20 @@ const KeyHandler = (props) => {
 		}
 	}, resetKeysAndSelection = () => {
 		actions.setSelectionRect(void 0), actions.setSelectionKeyPressed(!1), actions.setMultiselectionKeyPressed(!1), actions.setDeleteKeyPressed(!1), actions.setPanActivationKeyPressed(!1), actions.setZoomActivationKeyPressed(!1);
+	}, reconcileModifiers = (event) => {
+		let changed = !1;
+		store.selectionKeyPressed && allContradicted(event, _props.selectionKey) && (actions.setSelectionKeyPressed(!1), changed = !0), store.multiselectionKeyPressed && allContradicted(event, _props.multiSelectionKey) && (actions.setMultiselectionKeyPressed(!1), changed = !0), store.panActivationKeyPressed && allContradicted(event, _props.panActivationKey) && (actions.setPanActivationKeyPressed(!1), changed = !0), store.zoomActivationKeyPressed && allContradicted(event, _props.zoomActivationKey) && (actions.setZoomActivationKeyPressed(!1), changed = !0), changed && flush();
+	}, cancelPointerGestures = () => {
+		let release = (Ctor, type) => {
+			try {
+				window.dispatchEvent(new Ctor(type, { view: window }));
+			} catch {
+				window.dispatchEvent(new Ctor(type));
+			}
+		};
+		release(MouseEvent, "mouseup"), typeof PointerEvent < "u" && release(PointerEvent, "pointerup");
+	}, handleWindowBlur = () => {
+		resetKeysAndSelection(), cancelPointerGestures();
 	}, handleDelete = async () => {
 		let selectedNodes = store.nodes.filter((node) => node.selected), selectedEdges = store.edges.filter((edge) => edge.selected), { deletedNodes, deletedEdges } = await deleteElements({
 			nodes: selectedNodes,
@@ -3307,16 +3349,22 @@ const KeyHandler = (props) => {
 			edges: deletedEdges
 		});
 	};
-	return isServer || createEventListenerMap(window, {
+	return isServer || (createEventListenerMap(window, {
 		keydown: (event) => {
-			matchesKeyArray(event, _props.selectionKey) && actions.setSelectionKeyPressed(!0), matchesKeyArray(event, _props.multiSelectionKey) && actions.setMultiselectionKeyPressed(!0), matchesKeyArray(event, _props.deleteKey) && !isInputDOMNode(event) && (event.ctrlKey || event.metaKey || event.shiftKey || (actions.setDeleteKeyPressed(!0), handleDelete())), matchesKeyArray(event, _props.panActivationKey) && actions.setPanActivationKeyPressed(!0), matchesKeyArray(event, _props.zoomActivationKey) && actions.setZoomActivationKeyPressed(!0), flush();
+			reconcileModifiers(event), matchesKeyArray(event, _props.selectionKey) && actions.setSelectionKeyPressed(!0), matchesKeyArray(event, _props.multiSelectionKey) && actions.setMultiselectionKeyPressed(!0), matchesKeyArray(event, _props.deleteKey) && !isInputDOMNode(event) && (event.ctrlKey || event.metaKey || event.shiftKey || (actions.setDeleteKeyPressed(!0), handleDelete())), matchesKeyArray(event, _props.panActivationKey) && actions.setPanActivationKeyPressed(!0), matchesKeyArray(event, _props.zoomActivationKey) && actions.setZoomActivationKeyPressed(!0), flush();
 		},
 		keyup: (event) => {
-			matchesKeyArray(event, _props.selectionKey) && actions.setSelectionKeyPressed(!1), matchesKeyArray(event, _props.multiSelectionKey) && actions.setMultiselectionKeyPressed(!1), matchesKeyArray(event, _props.deleteKey) && actions.setDeleteKeyPressed(!1), matchesKeyArray(event, _props.panActivationKey) && actions.setPanActivationKeyPressed(!1), matchesKeyArray(event, _props.zoomActivationKey) && actions.setZoomActivationKeyPressed(!1), flush();
+			reconcileModifiers(event), matchesKeyArray(event, _props.selectionKey) && actions.setSelectionKeyPressed(!1), matchesKeyArray(event, _props.multiSelectionKey) && actions.setMultiselectionKeyPressed(!1), matchesKeyArray(event, _props.deleteKey) && actions.setDeleteKeyPressed(!1), matchesKeyArray(event, _props.panActivationKey) && actions.setPanActivationKeyPressed(!1), matchesKeyArray(event, _props.zoomActivationKey) && actions.setZoomActivationKeyPressed(!1), flush();
 		},
-		blur: resetKeysAndSelection,
+		blur: handleWindowBlur,
 		contextmenu: resetKeysAndSelection
-	}), null;
+	}), createEventListenerMap(window, {
+		pointerdown: reconcileModifiers,
+		wheel: reconcileModifiers
+	}, {
+		capture: !0,
+		passive: !0
+	})), null;
 };
 //#endregion
 //#region src/components/SolidFlow.tsx

package/dist/index/index.jsx

@@ -250,9 +250,9 @@ const getEdgeId = (connection) => {
 		height: 2 * halfHeight
 	};
 }, { equals: rectsEqual }), isNodeCulled = (node, cullingViewport) => {
-	if (!cullingViewport || node.selected) return !1;
+	if (!cullingViewport || node.selected || node.cullable === !1) return !1;
 	let { width, height } = node.measured;
-	if (!width || !height) return !1;
+	if (!width || !height || !node.internals.handleBounds) return !1;
 	let { x, y } = node.internals.positionAbsolute;
 	return !rectsOverlap({
 		x,
@@ -261,7 +261,7 @@ const getEdgeId = (connection) => {
 		height
 	}, cullingViewport);
 }, isEdgeCulled = (row, cullingViewport) => {
-	if (!cullingViewport || row.selected) return !1;
+	if (!cullingViewport || row.selected || row.cullable === !1) return !1;
 	let x = Math.min(row.sourceX, row.targetX), y = Math.min(row.sourceY, row.targetY);
 	return !rectsOverlap({
 		x,
@@ -2385,6 +2385,34 @@ function matchesKey(event, keyDef) {
 function matchesKeyArray(event, keyDefs) {
 	return keyDefs ? (Array.isArray(keyDefs) ? keyDefs : [keyDefs]).some((keyDef) => matchesKey(event, keyDef)) : !1;
 }
+const MODIFIER_FLAG = {
+	alt: "altKey",
+	control: "ctrlKey",
+	ctrl: "ctrlKey",
+	meta: "metaKey",
+	shift: "shiftKey"
+};
+/**
+* Whether an event's modifier flags PROVE this key definition cannot be held
+* right now: the key itself is a modifier whose flag is off, or one of its
+* required modifiers is off. Definitions built on non-modifier keys are never
+* contradicted (their state isn't derivable from flags).
+*/
+function isContradicted(flags, keyDef) {
+	let keyFlag = MODIFIER_FLAG[getKeyString(keyDef).toLowerCase()];
+	if (keyFlag && !flags[keyFlag]) return !0;
+	let modifiers = getModifier(keyDef);
+	return (Array.isArray(modifiers) ? modifiers.flatMap((mod) => mod) : [modifiers]).some((mod) => {
+		let modFlag = MODIFIER_FLAG[mod.toLowerCase()];
+		return !!modFlag && !flags[modFlag];
+	});
+}
+/** True only when EVERY definition for this key state is contradicted. */
+function allContradicted(flags, keyDefs) {
+	if (!keyDefs) return !1;
+	let keys = Array.isArray(keyDefs) ? keyDefs : [keyDefs];
+	return keys.length > 0 && keys.every((keyDef) => isContradicted(flags, keyDef));
+}
 const KeyHandler = (props) => {
 	let { store, actions } = useInternalSolidFlow(), { deleteElements } = useSolidFlow(), _props = {
 		get selectionKey() {
@@ -2404,6 +2432,20 @@ const KeyHandler = (props) => {
 		}
 	}, resetKeysAndSelection = () => {
 		actions.setSelectionRect(void 0), actions.setSelectionKeyPressed(!1), actions.setMultiselectionKeyPressed(!1), actions.setDeleteKeyPressed(!1), actions.setPanActivationKeyPressed(!1), actions.setZoomActivationKeyPressed(!1);
+	}, reconcileModifiers = (event) => {
+		let changed = !1;
+		store.selectionKeyPressed && allContradicted(event, _props.selectionKey) && (actions.setSelectionKeyPressed(!1), changed = !0), store.multiselectionKeyPressed && allContradicted(event, _props.multiSelectionKey) && (actions.setMultiselectionKeyPressed(!1), changed = !0), store.panActivationKeyPressed && allContradicted(event, _props.panActivationKey) && (actions.setPanActivationKeyPressed(!1), changed = !0), store.zoomActivationKeyPressed && allContradicted(event, _props.zoomActivationKey) && (actions.setZoomActivationKeyPressed(!1), changed = !0), changed && flush();
+	}, cancelPointerGestures = () => {
+		let release = (Ctor, type) => {
+			try {
+				window.dispatchEvent(new Ctor(type, { view: window }));
+			} catch {
+				window.dispatchEvent(new Ctor(type));
+			}
+		};
+		release(MouseEvent, "mouseup"), typeof PointerEvent < "u" && release(PointerEvent, "pointerup");
+	}, handleWindowBlur = () => {
+		resetKeysAndSelection(), cancelPointerGestures();
 	}, handleDelete = async () => {
 		let selectedNodes = store.nodes.filter((node) => node.selected), selectedEdges = store.edges.filter((edge) => edge.selected), { deletedNodes, deletedEdges } = await deleteElements({
 			nodes: selectedNodes,
@@ -2414,16 +2456,22 @@ const KeyHandler = (props) => {
 			edges: deletedEdges
 		});
 	};
-	return isServer || createEventListenerMap(window, {
+	return isServer || (createEventListenerMap(window, {
 		keydown: (event) => {
-			matchesKeyArray(event, _props.selectionKey) && actions.setSelectionKeyPressed(!0), matchesKeyArray(event, _props.multiSelectionKey) && actions.setMultiselectionKeyPressed(!0), matchesKeyArray(event, _props.deleteKey) && !isInputDOMNode(event) && (event.ctrlKey || event.metaKey || event.shiftKey || (actions.setDeleteKeyPressed(!0), handleDelete())), matchesKeyArray(event, _props.panActivationKey) && actions.setPanActivationKeyPressed(!0), matchesKeyArray(event, _props.zoomActivationKey) && actions.setZoomActivationKeyPressed(!0), flush();
+			reconcileModifiers(event), matchesKeyArray(event, _props.selectionKey) && actions.setSelectionKeyPressed(!0), matchesKeyArray(event, _props.multiSelectionKey) && actions.setMultiselectionKeyPressed(!0), matchesKeyArray(event, _props.deleteKey) && !isInputDOMNode(event) && (event.ctrlKey || event.metaKey || event.shiftKey || (actions.setDeleteKeyPressed(!0), handleDelete())), matchesKeyArray(event, _props.panActivationKey) && actions.setPanActivationKeyPressed(!0), matchesKeyArray(event, _props.zoomActivationKey) && actions.setZoomActivationKeyPressed(!0), flush();
 		},
 		keyup: (event) => {
-			matchesKeyArray(event, _props.selectionKey) && actions.setSelectionKeyPressed(!1), matchesKeyArray(event, _props.multiSelectionKey) && actions.setMultiselectionKeyPressed(!1), matchesKeyArray(event, _props.deleteKey) && actions.setDeleteKeyPressed(!1), matchesKeyArray(event, _props.panActivationKey) && actions.setPanActivationKeyPressed(!1), matchesKeyArray(event, _props.zoomActivationKey) && actions.setZoomActivationKeyPressed(!1), flush();
+			reconcileModifiers(event), matchesKeyArray(event, _props.selectionKey) && actions.setSelectionKeyPressed(!1), matchesKeyArray(event, _props.multiSelectionKey) && actions.setMultiselectionKeyPressed(!1), matchesKeyArray(event, _props.deleteKey) && actions.setDeleteKeyPressed(!1), matchesKeyArray(event, _props.panActivationKey) && actions.setPanActivationKeyPressed(!1), matchesKeyArray(event, _props.zoomActivationKey) && actions.setZoomActivationKeyPressed(!1), flush();
 		},
-		blur: resetKeysAndSelection,
+		blur: handleWindowBlur,
 		contextmenu: resetKeysAndSelection
-	}), null;
+	}), createEventListenerMap(window, {
+		pointerdown: reconcileModifiers,
+		wheel: reconcileModifiers
+	}, {
+		capture: !0,
+		passive: !0
+	})), null;
 }, SolidFlow = (props) => {
 	let [domNodeRef, setDomNodeRef] = createSignal(), domNode, _props = merge({
 		...getDefaultFlowStateProps(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dschz/solid-flow",
-  "version": "0.3.0-next.4",
+  "version": "0.3.0-next.5",
   "description": "Solid Flow - A highly customizable Solid library for building node-based editors, workflow systems, diagrams and more.",
   "keywords": [
     "ai workflows",
@@ -87,6 +87,7 @@
     "start": "vite",
     "test": "vitest run",
     "test:cov": "vitest run --coverage",
+    "test:e2e": "playwright test",
     "typecheck": "tsc --noEmit",
     "test:ssr": "vitest run --config vite.config.ssr.ts"
   },
@@ -100,6 +101,7 @@
     "@changesets/cli": "2.31.1",
     "@dagrejs/dagre": "^1.1.5",
     "@dom-expressions/compiler": "0.50.0-next.43",
+    "@playwright/test": "1.62.1",
     "@solidjs/testing-library": "1.0.0-beta.2",
     "@solidjs/vite-plugin": "3.0.0-next.28",
     "@testing-library/jest-dom": "7.0.0",