The flow store

KookieFlow keeps the live graph in a Zustand store: the entities and edges as the canvas holds them, the viewport, the selection, and the indexes it uses to find things quickly. Any component you render inside KookieFlow can read that store and change it.

During a drag or a pan the store changes on every frame. Read it when you need a value, and subscribe to the one piece you care about, so your components don't re-render sixty times a second.

Render your component as a child of KookieFlow, and call useFlowStoreApi() in it. Children are drawn in a layer over the canvas.

'use client';import { KookieFlow, useGraph } from '@kushagradhawan/kookie-flow';import { SelectionPanel } from './selection-panel';export function Flow() {  const { entities, edges, onEntitiesChange, onEdgesChange, onConnect } = useGraph();  return (    <div style={{ height: 480 }}>      <KookieFlow        entities={entities}        edges={edges}        onEntitiesChange={onEntitiesChange}        onEdgesChange={onEdgesChange}        onConnect={onConnect}      >        <div style={{ position: 'absolute', top: 12, right: 12, pointerEvents: 'auto' }}>          <SelectionPanel />        </div>      </KookieFlow>    </div>  );}

• Set pointerEvents: 'auto' on anything people click. The layer that holds children lets the pointer through to the canvas, so a button without it can't be pressed.
• Most canvas keys don't reach your controls. Keys like Delete and the arrows work only while the canvas itself has focus, so typing in an input in your panel doesn't delete nodes. The undo shortcut also respects inputs and editable content inside the canvas.
• Outside KookieFlow, use the ref. useFlowStoreApi() throws when it's called in a component that isn't rendered inside KookieFlow, including the component that renders it. The ref instance covers what you can do from there.

useFlowStoreApi() returns a FlowStore. You use two of its methods: getState(), which returns the current FlowState, and subscribe(). Change the store through the actions on getState() rather than setState(), because the actions also rebuild the indexes that clicks and hovers rely on.

getState() returns the state at the moment you call it. It doesn't subscribe and it doesn't render, so it's the right call inside a click handler.

'use client';import { useFlowStoreApi } from '@kushagradhawan/kookie-flow';export function SelectionPanel() {  const store = useFlowStoreApi();  const copyAsJson = () => {    const { getSelectedEntities, getConnectedEdges, selectedEntityIds } = store.getState();    const entities = getSelectedEntities();    const edges = getConnectedEdges([...selectedEntityIds]);    void navigator.clipboard.writeText(JSON.stringify({ entities, edges }, null, 2));  };  return <button onClick={copyAsJson}>Copy selection as JSON</button>;}

These are the fields you read most often. The last column says how often each one changes, which matters as soon as you subscribe to it.

The query actions are in Graph queries, and copying and pasting is in Clipboard and cloning. The rest of the store's actions are listed further down this page.

store.subscribe(selector, listener) calls listener whenever the value selector returns changes, and returns a function that unsubscribes. Values are compared with Object.is. Pass { equalityFn } as a third argument to compare them another way, or { fireImmediately: true } to call listener once straight away.

For anything that changes during a gesture, update the page through a ref, and do it at most once per frame. This readout follows the zoom while someone zooms, without rendering React once:

'use client';import { useEffect, useRef } from 'react';import { useFlowStoreApi } from '@kushagradhawan/kookie-flow';export function ZoomReadout() {  const store = useFlowStoreApi();  const labelRef = useRef<HTMLSpanElement>(null);  useEffect(() => {    let frame = 0;    const paint = () => {      frame = 0;      const { zoom } = store.getState().viewport;      if (labelRef.current) labelRef.current.textContent = `${Math.round(zoom * 100)}%`;    };    paint();    const unsubscribe = store.subscribe(      (state) => state.viewport.zoom,      () => {        if (frame === 0) frame = requestAnimationFrame(paint);      }    );    return () => {      unsubscribe();      cancelAnimationFrame(frame);    };  }, [store]);  return <span ref={labelRef} />;}

When a value changes only when someone clicks, a render is fine. useFlowStore(selector) re-renders your component whenever the selected value changes:

import { useFlowStore } from '@kushagradhawan/kookie-flow';export function SelectionCount() {  const count = useFlowStore((state) => state.selectedEntityIds.size);  return <span>{count} selected</span>;}

Two rules keep useFlowStore from costing you frames:

• Don't select viewport or positionVersion for interaction readouts. Each changes during a gesture, so the component would render on every frame. Subscribe with a ref instead.
• An entities selector observes array replacements, not drag/resize. Read the current entity from entityMap in a positionVersion subscriber to follow movement.
• Return a value that stays the same when nothing changed: a number, a string, a boolean, or a reference the store already holds. A selector that builds a new array or object on every call never returns the same value twice, and React renders again and again.

addElements and deleteElements change several entities and edges in one update.

interface ElementsBatch {  entities?: Entity[];  edges?: Edge[];}interface DeleteElementsBatch {  entityIds?: string[];  edgeIds?: string[];}

The store also holds actions for selection, the camera and positions:

These actions work on frames, on the order entities are drawn in, and on evaluation:

markDirty is for a change the canvas can't see, such as a file or a remote value one of your entities reads. Evaluation covers what dirty means and what runs.

bringToFront and markDirty change only what the store holds, like selection and the camera, so they work in any graph. moveGroup, setEntityParent, updateEntityDimensions and fitEntityToContent change entities without reporting it, so the next section applies to them.

The rest of FlowState serves the canvas's own gestures: hovering, drawing a wire, editing text, pressing a widget and drawing with the pen. Those fields change in step with the gesture, and calling one of the actions on its own can leave the gesture half done. stopEditing, for example, closes the text editor without reporting what was typed, and setWidgetValue changes what a widget shows without calling onWidgetChange.

Store actions change the canvas, and they don't call onEntitiesChange or onEdgesChange. The canvas also replaces its entities whenever your entities prop changes, and its edges whenever your edges prop changes. So in a controlled graph, an edit made through the store lasts only until your state next changes.

Here's how that goes wrong. A child calls addElements(), and the new node appears. Someone drags another node. useGraph applies that drag to its own array, which never had the new node, and the new node disappears.

In a controlled graph, add, delete and move entities through your own state. Pass the handlers from useGraph to the child that needs them:

'use client';import {  screenToWorld,  useFlowStoreApi,  type Entity,  type EntityChange,} from '@kushagradhawan/kookie-flow';export function AddNodeButton({ onEntitiesChange }: { onEntitiesChange: (changes: EntityChange[]) => void }) {  const store = useFlowStoreApi();  const add = () => {    const entity: Entity = {      id: crypto.randomUUID(),      type: 'default',      // 40 pixels in from the top-left corner of what's on screen.      position: screenToWorld({ x: 40, y: 40 }, store.getState().viewport),      data: { label: 'New node' },    };    onEntitiesChange([{ type: 'add', entity }]);  };  return <button onClick={add}>Add node</button>;}

Render it as <AddNodeButton onEntitiesChange={onEntitiesChange} /> inside KookieFlow. The change goes through useGraph, so it survives the next render, and with history on, undo can take it back.

Selection and the camera exist only in the store, so selection and viewport actions are safe in a controlled graph. If your entities and edges arrays never change identity, the store is the only copy of the graph, and its edits last. The Controlled and uncontrolled state chapter explains both setups.

getState().entities is live. Use toObject() for a graph snapshot rather than retaining that array across moves. Input arrays supplied by your app are not mutated by drag/resize.

Use socketValueKey(entityId, socketId) or entitySocketKey(entityId, socketId) for flat value maps, and connectedSocketKey(entityId, socketId, isInput) for connectedSockets and SocketIndexMap. The helpers escape delimiters in entity ids, so ids containing : or % do not alias a different entity/socket pair. Avoid constructing these keys by concatenation.