@kolosal-ai/rivet 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,7 +1,9 @@
-import { R as Rect, V as Vec2, A as AlignmentGuide, E as EdgeChange, a as RivetEdge, b as NodeChange, c as RivetNode, N as NodeId, d as NodeProps, e as NodeTypes, f as HandleType, H as HandlePosition, S as Size, g as Viewport, h as EdgeTypes, D as DefaultEdgeOptions, i as EdgeRendererFactory, j as SwimlaneGroup, k as SwimlaneMargin, l as SwimlaneHeaderProps, m as SwimlaneLabelProps, n as SwimlaneSizeChange, L as LaneChange, C as Connection, o as RivetSelection, p as EdgeId, q as HandleRecord, r as ReconnectDelegate, P as PendingConnection, s as RivetControls, t as RivetSnapshot, u as EdgeRenderer, v as EdgeRendererOptions, w as EdgeDrawExtras, x as EdgeEnd, y as EdgePathFn } from './types-B8AAJ60T.js';
-export { z as CenterNodeOptions, B as EdgeMarker, F as EdgePath, G as EdgePathParams, I as EdgeStyle, J as FitViewOptions, K as NodeComponent } from './types-B8AAJ60T.js';
+import { R as Rect, V as Vec2, A as AlignmentGuide, E as EdgeChange, a as RivetEdge, b as NodeChange, c as RivetNode, N as NodeId, d as NodeProps, e as NodeTypes, f as HandleType, H as HandlePosition, S as Size, g as ChangeOrigin, h as EdgeId, i as HandleRecord, j as ChangeMeta, k as Viewport, l as NodeGestureEvent, m as NodeLockConflictEvent, n as RivetSelection, o as ReconnectDelegate, C as Connection, P as PendingConnection, p as EdgeTypes, D as DefaultEdgeOptions, q as EdgeRendererFactory, r as SwimlaneGroup, s as SwimlaneMargin, t as SwimlaneHeaderProps, u as SwimlaneLabelProps, v as SwimlaneSizeChange, L as LaneChange, w as RivetControls, x as RivetSnapshot, y as EdgeRenderer, z as EdgeRendererOptions, B as EdgeDrawExtras, F as EdgeEnd, G as EdgePathFn } from './types-CQqnm4yW.js';
+export { I as CenterNodeOptions, J as EdgeMarker, K as EdgePath, M as EdgePathParams, O as EdgeStyle, Q as FitViewOptions, T as NodeComponent } from './types-CQqnm4yW.js';
 import { ReactNode, CSSProperties, MouseEvent, RefObject } from 'react';
-import { b as AnchorOptions, d as AnchorRecord, f as AnchorRegistrationOptions, R as ResolvedAnchorOptions, e as AnchorRegistration } from './registry-Dkk4ZKt-.js';
+import { d as AnchorRecord, f as AnchorRegistrationOptions, b as AnchorOptions, R as ResolvedAnchorOptions, e as AnchorRegistration } from './registry-t5ldbviG.js';
+import { h as PresenceRegistry, d as LockRegistry, f as Peer, a as LocalPresence, g as PresenceOptions, C as CanInteractWithLocked } from './use-node-lock-Csg9pUeC.js';
+export { L as LOCK_DEFAULT_REFUSED, b as LockIntent, c as LockInteraction, N as NodeLock, u as useNodeLock, i as useNodeLockAllows } from './use-node-lock-Csg9pUeC.js';
 import { ResolvedLane, ViewportElements, ResolvedSwimlaneGroup, ResolvedMargin } from './swimlane/index.js';
 
 /**
@@ -153,7 +155,7 @@ type NodeResizerProps = {
  * top/left handles) via {@link RivetStore.resizeNode} — so it works with
  * controlled mode (emits dimension changes) and nested nodes alike.
  */
-declare function NodeResizer({ minWidth, minHeight, maxWidth, maxHeight, keepAspectRatio, color, onResize, onResizeEnd, }: NodeResizerProps): React.ReactElement;
+declare function NodeResizer({ minWidth, minHeight, maxWidth, maxHeight, keepAspectRatio, color, onResize, onResizeEnd, }: NodeResizerProps): React.ReactElement | null;
 
 /**
  * Edge alignment — the library-level policy for when an edge's endpoints
@@ -221,248 +223,6 @@ declare function resolveFacingSide(node: Rect, peer: Rect, previous?: HandlePosi
  */
 declare function resolveFacingSideAmong(node: Rect, peer: Rect, allowed: readonly HandlePosition[], previous?: HandlePosition, hysteresis?: number): HandlePosition;
 
-/** Resolved graph context for a pane right-click, passed to `onPaneContextMenu`. */
-type PaneContextMenuContext = {
-    /** The click position in world coordinates (already unprojected). */
-    world: Vec2;
-    /** The swimlane lane whose body sits under the cursor, or `null`. */
-    lane: ResolvedLane | null;
-};
-type RivetProps = {
-    /**
-     * Nodes to seed the graph with (uncontrolled). Read once on mount to initialize
-     * the internal store — later changes to this array are ignored. Use {@link nodes}
-     * + {@link onNodesChange} for controlled mode instead. Defaults to `[]`.
-     */
-    defaultNodes?: RivetNode[];
-    /**
-     * Edges to seed the graph with (uncontrolled). See {@link defaultNodes}. An edge
-     * whose `source` or `target` node is absent is skipped by the renderer. Defaults to `[]`.
-     */
-    defaultEdges?: RivetEdge[];
-    /**
-     * Controlled nodes. When provided, the graph mirrors this array — hold the nodes
-     * in your own state and feed back the batches from {@link onNodesChange} (apply
-     * them with `applyNodeChanges`). Node drags are suppressed from reconciling
-     * mid-drag so the graph stays smooth. Takes precedence over {@link defaultNodes}.
-     */
-    nodes?: RivetNode[];
-    /** Controlled edges. See {@link nodes}. Takes precedence over {@link defaultEdges}. */
-    edges?: RivetEdge[];
-    /** Change batches the graph wants applied to your nodes (controlled mode). */
-    onNodesChange?: (changes: NodeChange[]) => void;
-    /** Change batches the graph wants applied to your edges (controlled mode). */
-    onEdgesChange?: (changes: EdgeChange[]) => void;
-    /**
-     * Initial pan/zoom. `x`/`y` are the screen-space offset in pixels and `zoom`
-     * is the scale factor. Defaults to `{ x: 0, y: 0, zoom: 1 }` (origin, 1:1).
-     */
-    defaultViewport?: Viewport;
-    /**
-     * Maps a node's `type` to the React component that renders it. A node whose
-     * `type` has no entry here (or no `type` at all) falls back to
-     * {@link DefaultNode}. Defaults to `{}`.
-     */
-    nodeTypes?: NodeTypes;
-    /**
-     * Registry of custom edge shapes, keyed by `edge.type`. Each is a pure geometry
-     * function (see {@link EdgePathFn}) so edges stay canvas/GPU-renderable. Merged
-     * over the built-ins `bezier` (default), `smoothstep`, `step`, and `straight`.
-     */
-    edgeTypes?: EdgeTypes;
-    /** Defaults merged into every edge that doesn't set the field (type, style, markers…). */
-    defaultEdgeOptions?: DefaultEdgeOptions;
-    /** Accessible name for the graph surface (`aria-label` on the pane). Defaults to "Node graph". */
-    ariaLabel?: string;
-    /**
-     * Backend factory for the edge layers — swap Canvas2D for another
-     * {@link EdgeRenderer}. Defaults to {@link canvas2DEdgeRenderer}. Pass a stable/memoized
-     * reference; a new identity re-creates the renderers.
-     */
-    renderer?: EdgeRendererFactory;
-    /**
-     * Lower bound on `viewport.zoom`. All zooming (wheel, controls, `fitView`) is
-     * clamped to this. Defaults to `0.2` (zoomed out to 20%).
-     */
-    minZoom?: number;
-    /**
-     * Upper bound on `viewport.zoom`. All zooming is clamped to this. Defaults to
-     * `2.5` (zoomed in to 250%).
-     */
-    maxZoom?: number;
-    /**
-     * Spacing in world units between background grid dots. The grid scales with
-     * zoom, so this is measured at `zoom === 1`. Defaults to `24`.
-     */
-    gridGap?: number;
-    /**
-     * Snap dragged nodes to a `[x, y]` world-unit grid. A `0` axis is left free.
-     * Omit (default) for free positioning. Independent of {@link gridGap} (the
-     * visual dot grid) — pass the same value to snap to the dots you see.
-     */
-    snapGrid?: [number, number];
-    /**
-     * While dragging a single node, show alignment guides and snap its edges/center
-     * to nearby nodes' edges/centers. Defaults to `false`.
-     */
-    alignmentGuides?: boolean;
-    /**
-     * Placement policy for anchor chrome — the grab dots and stray perimeter
-     * handles rivet renders for registered anchors (see {@link Anchor}). Omitted
-     * fields fall back to the defaults.
-     */
-    anchorOptions?: AnchorOptions;
-    /**
-     * Which mouse buttons pan when dragging the pane: `true` = left only, `false` =
-     * none, or a list of `MouseEvent.button` codes (`0` left, `1` middle, `2` right).
-     * e.g. `[1, 2]` pans with middle/right and frees left for selection. Defaults to
-     * `true`. Pass a stable reference; a new array identity re-binds the listeners.
-     */
-    panOnDrag?: boolean | number[];
-    /**
-     * Draw a selection marquee on a plain left-drag instead of panning. Pair with
-     * `panOnDrag={[1, 2]}` so left selects and middle/right pan. A marquee that
-     * ends over nodes leaves a persistent selection box around them — drag it to
-     * move the whole selection; a click elsewhere or Escape dismisses it.
-     * Defaults to `false`.
-     */
-    selectionOnDrag?: boolean;
-    /**
-     * Key(s) that force a marquee on a left-drag when held (e.g. `"Shift"`, `"Meta"`,
-     * or `["Shift", "Meta"]`). `null` disables. Defaults to `"Shift"`.
-     */
-    selectionKeyCode?: string | string[] | null;
-    /**
-     * Key(s) that make a click or marquee **add to** the selection instead of
-     * replacing it. Defaults to `["Meta", "Control", "Shift"]`. Use modifier keys
-     * (`Shift`/`Meta`/`Control`/`Alt`) — other keys only resolve during a pane drag.
-     */
-    multiSelectionKeyCode?: string | string[];
-    /**
-     * Pan the viewport on wheel / two-finger trackpad scroll instead of zooming.
-     * A pinch gesture (reported by the browser as ctrl+wheel) still zooms. When
-     * `false` (default), scrolling zooms toward the cursor.
-     */
-    scrollToPan?: boolean;
-    /**
-     * Wheel/pinch zoom sensitivity — larger zooms faster per scroll delta.
-     * Defaults to `0.0015`. Try `~0.003` for faster trackpad pinch zoom.
-     */
-    zoomSpeed?: number;
-    /**
-     * Swimlanes drawn behind the graph — a decorative background of labeled lane
-     * groups (like planout's swimlanes). Not nodes or edges; just layout regions.
-     * Omit for no swimlanes.
-     */
-    swimlane?: SwimlaneGroup[];
-    /**
-     * Bind node dragging to the swimlanes: on drop each node snaps fully inside
-     * one lane (honoring {@link swimlaneMargin}) and is reassigned to the lane it
-     * lands in via {@link RivetNode.laneId}. Defaults to `true` when
-     * {@link swimlane} is provided, `false` otherwise. Ignored with no swimlanes.
-     */
-    clampToSwimlane?: boolean;
-    /**
-     * Inner clearance kept between a clamped node and its lane's edges. A number
-     * applies to all sides; per-side values override it. Defaults to `16`.
-     */
-    swimlaneMargin?: number | SwimlaneMargin;
-    /** Screen height of the sticky group header band, in px. Defaults to `32`. */
-    swimlaneHeaderHeight?: number;
-    /**
-     * Show a resize handle on each lane's bottom edge to change its height.
-     * Defaults to `true` when {@link swimlane} is provided.
-     */
-    swimlaneResizable?: boolean;
-    /**
-     * Fraction of the last lane's height that must stay visible when scrolled to
-     * the bottom — the down-scroll stop. `0.5` (default) keeps half of it in view.
-     * Only applies when {@link clampToSwimlane} is on.
-     */
-    swimlaneBottomReveal?: number;
-    /** Render custom content for a group's sticky header (replaces the default). */
-    renderSwimlaneHeader?: (props: SwimlaneHeaderProps) => ReactNode;
-    /** Render custom content for a lane's sticky label (replaces the default). */
-    renderSwimlaneLabel?: (props: SwimlaneLabelProps) => ReactNode;
-    /**
-     * Called when a lane's height changes — from a resize drag or from auto-fit
-     * growing it to contain a node that grew. The graph owns lane heights, so this
-     * is a notification (persist it if you like), not a request to update state.
-     */
-    onSwimlaneSizeChange?: (change: SwimlaneSizeChange) => void;
-    /**
-     * Right-click on empty canvas (not over a node or swimlane chrome). The second
-     * argument carries the resolved graph context — the world position and the lane
-     * under the cursor — so you don't have to re-derive them.
-     */
-    onPaneContextMenu?: (event: MouseEvent, context: PaneContextMenuContext) => void;
-    /** Right-click on a lane's sticky label. */
-    onSwimlaneHeaderContextMenu?: (laneId: string, event: MouseEvent) => void;
-    /** Right-click on a group's sticky header. */
-    onSwimlaneGroupHeaderContextMenu?: (groupId: string, event: MouseEvent) => void;
-    /** Called when a dragged node is reassigned to a different lane. */
-    onLaneChange?: (change: LaneChange) => void;
-    /** Veto a proposed connection; return false to reject it. Applies to reconnection too. */
-    isValidConnection?: (connection: Connection) => boolean;
-    /**
-     * Rewrite a validated connection before it commits — normalize handle ids
-     * (e.g. redirect an in-content grab handle to its canonical perimeter
-     * handle), or force direction conventions. Returning `null` cancels the
-     * drop. Applies to new connections and reconnections; `isValidConnection`
-     * sees the raw connection, `onConnect`/`onReconnect` see the mapped one.
-     */
-    mapConnection?: (connection: Connection) => Connection | null;
-    /** Called after a valid connection is made (the edge is already added). */
-    onConnect?: (connection: Connection) => void;
-    /**
-     * Allow reconnecting edges by dragging an endpoint onto a new handle. Per-edge
-     * `reconnectable` overrides this. Defaults to `false`.
-     */
-    edgesReconnectable?: boolean;
-    /**
-     * When edge endpoints re-side to face the peer node. `"manual"` (default)
-     * never rewrites a chosen handle; `"on-move"` re-sides both ends of a moved
-     * node's edges when the move commits — in the same batch as the move, so one
-     * undo restores position and handles together. `"live"` additionally renders
-     * a dragging node's edges as if their ends were auto — re-siding per frame
-     * to face each other, with hysteresis so near-diagonal positions don't
-     * flicker — and commits the displayed sides on drop, inside the move's
-     * history step; nothing is persisted mid-gesture. Only committed position
-     * changes trigger a rewrite: data replaces and dimension changes never
-     * re-side, and a freshly created or reconnected edge keeps exactly the
-     * handles the user grabbed or dropped on. Anchor and bare-side ends rewrite
-     * their side directly; plain handles re-side to a registered handle of a
-     * compatible type on the facing side, or stay pinned when the node has none
-     * there. Independent of the policy, an end with *no* side — a missing
-     * handle, or an `anchorAutoHandleId` anchor end — always floats: the
-     * renderer resolves its facing side per frame and never writes it back.
-     */
-    edgeAlignment?: EdgeAlignment;
-    /** Called when an endpoint drag re-points an edge (the edge is already updated). */
-    onReconnect?: (edge: RivetEdge, connection: Connection) => void;
-    /** Called when an endpoint reconnection drag starts. */
-    onReconnectStart?: (edge: RivetEdge) => void;
-    /** Called when an endpoint reconnection drag ends (committed or cancelled). */
-    onReconnectEnd?: (edge: RivetEdge) => void;
-    /** Called whenever the selected nodes and/or edges change. */
-    onSelectionChange?: (selection: RivetSelection) => void;
-    /**
-     * Called when keyboard focus moves to a node (or leaves the graph — `null`).
-     * The same state is available inside `<Rivet>` via {@link useRivetFocusedNode}.
-     * Rivet draws no focus ring; use this (or the wrapper's `:focus-visible`) to
-     * render your own indicator.
-     */
-    onFocusChange?: (id: NodeId | null) => void;
-    className?: string;
-    style?: CSSProperties;
-    children?: ReactNode;
-};
-/**
- * The graph surface. Stacks a background grid canvas, an edge canvas, and a DOM
- * node layer — all driven by one shared viewport (see {@link useRivetRuntime}).
- */
-declare function Rivet({ defaultNodes, defaultEdges, nodes: controlledNodes, edges: controlledEdges, onNodesChange, onEdgesChange, defaultViewport, nodeTypes, edgeTypes, defaultEdgeOptions, ariaLabel, renderer, minZoom, maxZoom, gridGap, snapGrid, alignmentGuides, anchorOptions, panOnDrag, selectionOnDrag, selectionKeyCode, multiSelectionKeyCode, scrollToPan, zoomSpeed, swimlane, clampToSwimlane, swimlaneMargin, swimlaneHeaderHeight, swimlaneResizable, swimlaneBottomReveal, renderSwimlaneHeader, renderSwimlaneLabel, onSwimlaneSizeChange, onPaneContextMenu, onSwimlaneHeaderContextMenu, onSwimlaneGroupHeaderContextMenu, onLaneChange, isValidConnection, mapConnection, onConnect, edgesReconnectable, edgeAlignment, onReconnect, onReconnectStart, onReconnectEnd, onSelectionChange, onFocusChange, className, style, children, }: RivetProps): React.ReactElement;
-
 /** Composite key for the handle/anchor registries. */
 declare function handleKey(nodeId: NodeId, handleId: string): string;
 
@@ -477,8 +237,22 @@ type ViewportClamp = {
     maxY?: number;
 };
 type ChangeHandlers = {
-    nodes?: (changes: NodeChange[]) => void;
-    edges?: (changes: EdgeChange[]) => void;
+    nodes?: (changes: NodeChange[], meta: ChangeMeta) => void;
+    edges?: (changes: EdgeChange[], meta: ChangeMeta) => void;
+};
+/** Gesture lifecycle sinks — see {@link RivetStore.setGestureHandlers}. */
+type GestureHandlers = {
+    start?: (event: NodeGestureEvent) => void;
+    end?: (event: NodeGestureEvent) => void;
+    /** A peer's lock landed on a node this client is already holding. */
+    conflict?: (event: NodeLockConflictEvent) => void;
+};
+/** Changes to hand to {@link RivetStore.applyRemote}. */
+type RemoteChanges = {
+    nodes?: NodeChange[];
+    edges?: EdgeChange[];
+    /** Defaults to `"remote"`. Pass a peer or transaction id to route on it. */
+    origin?: ChangeOrigin;
 };
 /**
  * The single source of truth for a graph instance — the public contract. It's an
@@ -516,6 +290,18 @@ type RivetStore = {
      * nodes don't re-render.
      */
     reconcile: (nodes: RivetNode[], edges: RivetEdge[]) => void;
+    /**
+     * Apply a change batch that happened somewhere else — a peer's edit arriving
+     * over your transport. The graph updates and repaints immediately, then the
+     * batch is re-emitted to the change handlers tagged `"remote"` so a controlled
+     * owner applies it through the same path as everything else.
+     *
+     * Remote batches never create an undo step: undoing a peer's edit isn't undo,
+     * and in a shared document it would silently revert work you don't own. The
+     * history baseline is refreshed instead, so your next local step still diffs
+     * against reality.
+     */
+    applyRemote: (changes: RemoteChanges) => void;
     /** Add a node (imperative CRUD). Ignored if the id already exists. */
     addNode: (node: RivetNode) => void;
     /** Replace a node wholesale by id (imperative CRUD). Ignored if absent. */
@@ -593,13 +379,54 @@ type RivetStore = {
     /** True while a node drag is in progress (pauses swimlane auto-fit). */
     isNodeDragging: () => boolean;
     setNodeDragging: (dragging: boolean) => void;
+    /**
+     * Open a gesture on `ids` — a pointer drag, a resize, or a keyboard grab.
+     * While it's open those nodes are *held*: this client's geometry for them wins
+     * over anything arriving from elsewhere (see {@link isNodeHeld}), and
+     * {@link GestureHandlers.start} fires so a consumer can take a lock.
+     *
+     * `id` is the node the gesture began on; `ids` is everything moving with it
+     * (a group drag holds the whole selection). Re-opening an already-held node
+     * is a no-op, so a gesture may safely widen.
+     */
+    beginNodeGesture: (id: NodeId, ids?: NodeId[]) => void;
+    /**
+     * Close a gesture opened by {@link beginNodeGesture}, releasing its nodes.
+     *
+     * Normally the gesture calls this itself on drop. Calling it from outside is
+     * how a consumer yields a contested node mid-drag: the running gesture sees
+     * that it no longer holds its nodes, stops writing to them, and tears itself
+     * down without committing.
+     */
+    endNodeGesture: (id: NodeId, ids?: NodeId[]) => void;
+    /**
+     * Publish the lock table (the `lockedNodes` prop), and report any node it
+     * claims that a local gesture is already holding to
+     * {@link GestureHandlers.conflict}. The gesture itself is left running — see
+     * {@link NodeLockConflictEvent} for why rivet doesn't pick the loser.
+     */
+    setLockedNodes: (locks: Record<NodeId, string> | undefined) => void;
+    /**
+     * True while a local gesture holds this node. Held geometry is exclusively
+     * this client's: {@link applyRemote} drops incoming `position`/`dimensions`
+     * for it, and {@link reconcile} keeps the live box rather than the prop's.
+     */
+    isNodeHeld: (id: NodeId) => boolean;
+    /** Every node currently under a local gesture. */
+    getHeldNodeIds: () => ReadonlySet<NodeId>;
+    /**
+     * Subscribe to the held set opening or closing. Unlike
+     * {@link setGestureHandlers} — a single sink the `onNodeDragStart` /
+     * `onNodeDragEnd` props own — this is a broadcast channel, so presence can
+     * watch the same gesture the consumer's lock handler is acting on.
+     */
+    subscribeHeldNodes: (listener: () => void) => () => void;
+    /** Register the gesture lifecycle handlers (the lock acquire/release signals). */
+    setGestureHandlers: (handlers: GestureHandlers) => void;
     /**
      * True while a resize gesture is in progress — set by {@link resizeNode}'s live
-     * frames and cleared by its commit. Guards controlled-mode reconciliation the
-     * same way {@link isNodeDragging} does: mid-gesture the consumer's props lag
-     * the store (live frames may be dropped, and measurement echoes carry `size`
-     * but not the explicit `width`/`height`), so reconciling them would stomp the
-     * live box back to its pre-gesture value every frame.
+     * frames and cleared by its commit. Stomp protection is per-node and lives in
+     * {@link isNodeHeld}; this stays a coarse "is a resize happening at all" flag.
      */
     isNodeResizing: () => boolean;
     /**
@@ -684,6 +511,20 @@ type RivetStore = {
     setAlignmentGuides: (guides: AlignmentGuide[]) => void;
     registerHandle: (record: HandleRecord) => void;
     unregisterHandle: (nodeId: NodeId, handleId: string) => void;
+    /**
+     * Ephemeral peer presence — cursors, selections, and the boxes peers are
+     * dragging right now. Never part of the graph, the change stream, or
+     * history: presence describes people, not the document. Painted from the
+     * render loop; see `rivet/presence`.
+     */
+    readonly presence: PresenceRegistry;
+    /**
+     * Nodes peers have claimed, and the policy for what this client may still do
+     * to them. Published whole by {@link setLockedNodes}; read by every input
+     * path before it acts, and by the render loop to outline the holder. Like
+     * presence, never part of the graph, the change stream, or history.
+     */
+    readonly locks: LockRegistry;
     readonly anchors: Map<string, AnchorRecord>;
     /**
      * Register (or re-bind) an anchor. Idempotent on the `(nodeId, anchorId)`
@@ -722,6 +563,339 @@ type RivetStore = {
 /** Create a graph store. The public entry point; the class is an implementation detail. */
 declare function createRivetStore(init: RivetStoreInit): RivetStore;
 
+/** Resolved graph context for a pane right-click, passed to `onPaneContextMenu`. */
+type PaneContextMenuContext = {
+    /** The click position in world coordinates (already unprojected). */
+    world: Vec2;
+    /** The swimlane lane whose body sits under the cursor, or `null`. */
+    lane: ResolvedLane | null;
+};
+type RivetProps = {
+    /**
+     * Nodes to seed the graph with (uncontrolled). Read once on mount to initialize
+     * the internal store — later changes to this array are ignored. Use {@link nodes}
+     * + {@link onNodesChange} for controlled mode instead. Defaults to `[]`.
+     */
+    defaultNodes?: RivetNode[];
+    /**
+     * Edges to seed the graph with (uncontrolled). See {@link defaultNodes}. An edge
+     * whose `source` or `target` node is absent is skipped by the renderer. Defaults to `[]`.
+     */
+    defaultEdges?: RivetEdge[];
+    /**
+     * Controlled nodes. When provided, the graph mirrors this array — hold the nodes
+     * in your own state and feed back the batches from {@link onNodesChange} (apply
+     * them with `applyNodeChanges`). A node under a live gesture keeps its own
+     * geometry rather than the array's, so a drag stays smooth while the props
+     * lag behind it. Takes precedence over {@link defaultNodes}.
+     */
+    nodes?: RivetNode[];
+    /** Controlled edges. See {@link nodes}. Takes precedence over {@link defaultEdges}. */
+    edges?: RivetEdge[];
+    /**
+     * Change batches the graph wants applied to your nodes (controlled mode).
+     *
+     * `meta.origin` says where the batch came from: `"local"` for anything this
+     * client did, `"remote"` for a batch that arrived through
+     * {@link RivetInstance.applyRemote}. Multiplayer consumers apply both and send
+     * only the local ones onward — an untagged echo is indistinguishable from a
+     * peer's edit and loops straight back out.
+     */
+    onNodesChange?: (changes: NodeChange[], meta: ChangeMeta) => void;
+    /** Change batches the graph wants applied to your edges (controlled mode). See {@link onNodesChange}. */
+    onEdgesChange?: (changes: EdgeChange[], meta: ChangeMeta) => void;
+    /**
+     * Initial pan/zoom. `x`/`y` are the screen-space offset in pixels and `zoom`
+     * is the scale factor. Defaults to `{ x: 0, y: 0, zoom: 1 }` (origin, 1:1).
+     */
+    defaultViewport?: Viewport;
+    /**
+     * Maps a node's `type` to the React component that renders it. A node whose
+     * `type` has no entry here (or no `type` at all) falls back to
+     * {@link DefaultNode}. Defaults to `{}`.
+     */
+    nodeTypes?: NodeTypes;
+    /**
+     * Registry of custom edge shapes, keyed by `edge.type`. Each is a pure geometry
+     * function (see {@link EdgePathFn}) so edges stay canvas/GPU-renderable. Merged
+     * over the built-ins `bezier` (default), `smoothstep`, `step`, and `straight`.
+     */
+    edgeTypes?: EdgeTypes;
+    /** Defaults merged into every edge that doesn't set the field (type, style, markers…). */
+    defaultEdgeOptions?: DefaultEdgeOptions;
+    /** Accessible name for the graph surface (`aria-label` on the pane). Defaults to "Node graph". */
+    ariaLabel?: string;
+    /**
+     * Backend factory for the edge layers — swap Canvas2D for another
+     * {@link EdgeRenderer}. Defaults to {@link canvas2DEdgeRenderer}. Pass a stable/memoized
+     * reference; a new identity re-creates the renderers.
+     */
+    renderer?: EdgeRendererFactory;
+    /**
+     * Lower bound on `viewport.zoom`. All zooming (wheel, controls, `fitView`) is
+     * clamped to this. Defaults to `0.2` (zoomed out to 20%).
+     */
+    minZoom?: number;
+    /**
+     * Upper bound on `viewport.zoom`. All zooming is clamped to this. Defaults to
+     * `2.5` (zoomed in to 250%).
+     */
+    maxZoom?: number;
+    /**
+     * Spacing in world units between background grid dots. The grid scales with
+     * zoom, so this is measured at `zoom === 1`. Defaults to `24`.
+     */
+    gridGap?: number;
+    /**
+     * Snap dragged nodes to a `[x, y]` world-unit grid. A `0` axis is left free.
+     * Omit (default) for free positioning. Independent of {@link gridGap} (the
+     * visual dot grid) — pass the same value to snap to the dots you see.
+     */
+    snapGrid?: [number, number];
+    /**
+     * While dragging a single node, show alignment guides and snap its edges/center
+     * to nearby nodes' edges/centers. Defaults to `false`.
+     */
+    alignmentGuides?: boolean;
+    /**
+     * Placement policy for anchor chrome — the grab dots and stray perimeter
+     * handles rivet renders for registered anchors (see {@link Anchor}). Omitted
+     * fields fall back to the defaults.
+     */
+    anchorOptions?: AnchorOptions;
+    /**
+     * The other people in this document — the presence roster. Identity (name,
+     * colour) plus the slow fields: what each peer has selected, and what they're
+     * holding under a gesture. Rivet paints them: a cursor per peer, an outline
+     * around what they've selected, and the nodes they're moving drawn where they
+     * currently have them.
+     *
+     * Peer cursors move far faster than React should re-render, so the roster
+     * carries only a seed for them — feed live cursors and drag boxes through
+     * {@link RivetInstance.setPeerCursor} / `setPeerNodeTransform` instead.
+     *
+     * Presence is ephemeral: none of it reaches the graph, the change stream, or
+     * history. Dropping a peer from the array is how they leave.
+     */
+    peers?: Peer[];
+    /**
+     * Called with this client's presence — cursor (in world coordinates),
+     * selection, and held nodes — as a whole snapshot, ready to broadcast.
+     *
+     * Snapshots are idempotent, so a dropped or duplicated one costs nothing and
+     * a reconnecting peer is instantly correct. Cursor movement is coalesced to
+     * `presenceOptions.throttleMs`; selection and gesture changes are published
+     * immediately.
+     */
+    onLocalPresence?: (presence: LocalPresence) => void;
+    /** Presence policy — outbound throttle, and whether rivet paints peer cursors. */
+    presenceOptions?: PresenceOptions;
+    /**
+     * Nodes a peer has claimed, as `nodeId -> peerId`. Locks are policy where
+     * {@link peers} is description: rivet paints a locked node in its holder's
+     * colour *and* refuses to act on it.
+     *
+     * By default it refuses selection, dragging, resizing and deletion, and
+     * allows connections — a lock claims the node, not the graph around it.
+     * {@link canInteractWithLocked} replaces that policy.
+     *
+     * Lifetime is yours: rivet never takes or releases a lock, it only reads the
+     * table. Take one in {@link onNodeDragStart} and drop it in
+     * {@link onNodeDragEnd} for drag-scoped locks, or hold through deselection
+     * for something stickier. Like presence, none of this reaches the graph, the
+     * change stream, or history.
+     */
+    lockedNodes?: Record<NodeId, string>;
+    /**
+     * Decide what this client may do to a locked node, per attempt. Return `true`
+     * to allow the intent, `false` to refuse it.
+     *
+     * A handler owns the whole policy — rivet's defaults are replaced, not
+     * consulted — so answer every intent you care about:
+     *
+     * ```tsx
+     * // locked nodes stay inspectable, but nothing may change them
+     * canInteractWithLocked={({ intent }) => intent === "select" || intent === "connect"}
+     * ```
+     *
+     * Called on the input path (every marquee frame, every mover), so keep it
+     * cheap and free of side effects.
+     */
+    canInteractWithLocked?: CanInteractWithLocked;
+    /**
+     * Called when a lock for a peer arrives on a node this client is already
+     * holding — two clients started before either lock reached the other.
+     *
+     * rivet reports it and keeps going: the running gesture stays authoritative
+     * over its geometry, because only your transport knows which client actually
+     * lost the race. To yield, call {@link RivetInstance.releaseNodeGesture} —
+     * the gesture stops writing and tears down without committing.
+     */
+    onNodeLockConflict?: (event: NodeLockConflictEvent) => void;
+    /**
+     * Which mouse buttons pan when dragging the pane: `true` = left only, `false` =
+     * none, or a list of `MouseEvent.button` codes (`0` left, `1` middle, `2` right).
+     * e.g. `[1, 2]` pans with middle/right and frees left for selection. Defaults to
+     * `true`. Pass a stable reference; a new array identity re-binds the listeners.
+     */
+    panOnDrag?: boolean | number[];
+    /**
+     * Draw a selection marquee on a plain left-drag instead of panning. Pair with
+     * `panOnDrag={[1, 2]}` so left selects and middle/right pan. A marquee that
+     * ends over nodes leaves a persistent selection box around them — drag it to
+     * move the whole selection; a click elsewhere or Escape dismisses it.
+     * Defaults to `false`.
+     */
+    selectionOnDrag?: boolean;
+    /**
+     * Key(s) that force a marquee on a left-drag when held (e.g. `"Shift"`, `"Meta"`,
+     * or `["Shift", "Meta"]`). `null` disables. Defaults to `"Shift"`.
+     */
+    selectionKeyCode?: string | string[] | null;
+    /**
+     * Key(s) that make a click or marquee **add to** the selection instead of
+     * replacing it. Defaults to `["Meta", "Control", "Shift"]`. Use modifier keys
+     * (`Shift`/`Meta`/`Control`/`Alt`) — other keys only resolve during a pane drag.
+     */
+    multiSelectionKeyCode?: string | string[];
+    /**
+     * Pan the viewport on wheel / two-finger trackpad scroll instead of zooming.
+     * A pinch gesture (reported by the browser as ctrl+wheel) still zooms. When
+     * `false` (default), scrolling zooms toward the cursor.
+     */
+    scrollToPan?: boolean;
+    /**
+     * Wheel/pinch zoom sensitivity — larger zooms faster per scroll delta.
+     * Defaults to `0.0015`. Try `~0.003` for faster trackpad pinch zoom.
+     */
+    zoomSpeed?: number;
+    /**
+     * Swimlanes drawn behind the graph — a decorative background of labeled lane
+     * groups (like planout's swimlanes). Not nodes or edges; just layout regions.
+     * Omit for no swimlanes.
+     */
+    swimlane?: SwimlaneGroup[];
+    /**
+     * Bind node dragging to the swimlanes: on drop each node snaps fully inside
+     * one lane (honoring {@link swimlaneMargin}) and is reassigned to the lane it
+     * lands in via {@link RivetNode.laneId}. Defaults to `true` when
+     * {@link swimlane} is provided, `false` otherwise. Ignored with no swimlanes.
+     */
+    clampToSwimlane?: boolean;
+    /**
+     * Inner clearance kept between a clamped node and its lane's edges. A number
+     * applies to all sides; per-side values override it. Defaults to `16`.
+     */
+    swimlaneMargin?: number | SwimlaneMargin;
+    /** Screen height of the sticky group header band, in px. Defaults to `32`. */
+    swimlaneHeaderHeight?: number;
+    /**
+     * Show a resize handle on each lane's bottom edge to change its height.
+     * Defaults to `true` when {@link swimlane} is provided.
+     */
+    swimlaneResizable?: boolean;
+    /**
+     * Fraction of the last lane's height that must stay visible when scrolled to
+     * the bottom — the down-scroll stop. `0.5` (default) keeps half of it in view.
+     * Only applies when {@link clampToSwimlane} is on.
+     */
+    swimlaneBottomReveal?: number;
+    /** Render custom content for a group's sticky header (replaces the default). */
+    renderSwimlaneHeader?: (props: SwimlaneHeaderProps) => ReactNode;
+    /** Render custom content for a lane's sticky label (replaces the default). */
+    renderSwimlaneLabel?: (props: SwimlaneLabelProps) => ReactNode;
+    /**
+     * Called when a lane's height changes — from a resize drag or from auto-fit
+     * growing it to contain a node that grew. The graph owns lane heights, so this
+     * is a notification (persist it if you like), not a request to update state.
+     */
+    onSwimlaneSizeChange?: (change: SwimlaneSizeChange) => void;
+    /**
+     * Right-click on empty canvas (not over a node or swimlane chrome). The second
+     * argument carries the resolved graph context — the world position and the lane
+     * under the cursor — so you don't have to re-derive them.
+     */
+    onPaneContextMenu?: (event: MouseEvent, context: PaneContextMenuContext) => void;
+    /** Right-click on a lane's sticky label. */
+    onSwimlaneHeaderContextMenu?: (laneId: string, event: MouseEvent) => void;
+    /** Right-click on a group's sticky header. */
+    onSwimlaneGroupHeaderContextMenu?: (groupId: string, event: MouseEvent) => void;
+    /** Called when a dragged node is reassigned to a different lane. */
+    onLaneChange?: (change: LaneChange) => void;
+    /** Veto a proposed connection; return false to reject it. Applies to reconnection too. */
+    isValidConnection?: (connection: Connection) => boolean;
+    /**
+     * Rewrite a validated connection before it commits — normalize handle ids
+     * (e.g. redirect an in-content grab handle to its canonical perimeter
+     * handle), or force direction conventions. Returning `null` cancels the
+     * drop. Applies to new connections and reconnections; `isValidConnection`
+     * sees the raw connection, `onConnect`/`onReconnect` see the mapped one.
+     */
+    mapConnection?: (connection: Connection) => Connection | null;
+    /** Called after a valid connection is made (the edge is already added). */
+    onConnect?: (connection: Connection) => void;
+    /**
+     * Allow reconnecting edges by dragging an endpoint onto a new handle. Per-edge
+     * `reconnectable` overrides this. Defaults to `false`.
+     */
+    edgesReconnectable?: boolean;
+    /**
+     * When edge endpoints re-side to face the peer node. `"manual"` (default)
+     * never rewrites a chosen handle; `"on-move"` re-sides both ends of a moved
+     * node's edges when the move commits — in the same batch as the move, so one
+     * undo restores position and handles together. `"live"` additionally renders
+     * a dragging node's edges as if their ends were auto — re-siding per frame
+     * to face each other, with hysteresis so near-diagonal positions don't
+     * flicker — and commits the displayed sides on drop, inside the move's
+     * history step; nothing is persisted mid-gesture. Only committed position
+     * changes trigger a rewrite: data replaces and dimension changes never
+     * re-side, and a freshly created or reconnected edge keeps exactly the
+     * handles the user grabbed or dropped on. Anchor and bare-side ends rewrite
+     * their side directly; plain handles re-side to a registered handle of a
+     * compatible type on the facing side, or stay pinned when the node has none
+     * there. Independent of the policy, an end with *no* side — a missing
+     * handle, or an `anchorAutoHandleId` anchor end — always floats: the
+     * renderer resolves its facing side per frame and never writes it back.
+     */
+    edgeAlignment?: EdgeAlignment;
+    /** Called when an endpoint drag re-points an edge (the edge is already updated). */
+    onReconnect?: (edge: RivetEdge, connection: Connection) => void;
+    /** Called when an endpoint reconnection drag starts. */
+    onReconnectStart?: (edge: RivetEdge) => void;
+    /** Called when an endpoint reconnection drag ends (committed or cancelled). */
+    onReconnectEnd?: (edge: RivetEdge) => void;
+    /**
+     * Called when a local gesture takes hold of one or more nodes — a pointer
+     * drag, a resize, or a keyboard grab. While it's open, those nodes' geometry
+     * belongs to this client: remote `position`/`dimensions` writes for them are
+     * dropped, and controlled props can't stomp the live box.
+     *
+     * In a shared document this is where you acquire a lock. It's paired with
+     * {@link onNodeDragEnd} — every start gets exactly one end, including a
+     * cancelled keyboard grab.
+     */
+    onNodeDragStart?: (event: NodeGestureEvent) => void;
+    /** Called when a gesture releases its nodes. See {@link onNodeDragStart}. */
+    onNodeDragEnd?: (event: NodeGestureEvent) => void;
+    /** Called whenever the selected nodes and/or edges change. */
+    onSelectionChange?: (selection: RivetSelection) => void;
+    /**
+     * Called when keyboard focus moves to a node (or leaves the graph — `null`).
+     * The same state is available inside `<Rivet>` via {@link useRivetFocusedNode}.
+     * Rivet draws no focus ring; use this (or the wrapper's `:focus-visible`) to
+     * render your own indicator.
+     */
+    onFocusChange?: (id: NodeId | null) => void;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+};
+/**
+ * The graph surface. Stacks a background grid canvas, an edge canvas, and a DOM
+ * node layer — all driven by one shared viewport (see {@link useRivetRuntime}).
+ */
+declare function Rivet({ defaultNodes, defaultEdges, nodes: controlledNodes, edges: controlledEdges, onNodesChange, onEdgesChange, defaultViewport, nodeTypes, edgeTypes, defaultEdgeOptions, ariaLabel, renderer, minZoom, maxZoom, gridGap, snapGrid, alignmentGuides, anchorOptions, peers, onLocalPresence, presenceOptions, lockedNodes, canInteractWithLocked, onNodeLockConflict, panOnDrag, selectionOnDrag, selectionKeyCode, multiSelectionKeyCode, scrollToPan, zoomSpeed, swimlane, clampToSwimlane, swimlaneMargin, swimlaneHeaderHeight, swimlaneResizable, swimlaneBottomReveal, renderSwimlaneHeader, renderSwimlaneLabel, onSwimlaneSizeChange, onPaneContextMenu, onSwimlaneHeaderContextMenu, onSwimlaneGroupHeaderContextMenu, onLaneChange, isValidConnection, mapConnection, onConnect, edgesReconnectable, edgeAlignment, onReconnect, onReconnectStart, onReconnectEnd, onNodeDragStart, onNodeDragEnd, onSelectionChange, onFocusChange, className, style, children, }: RivetProps): React.ReactElement;
+
 type RivetContextValue = {
     store: RivetStore;
     nodeTypes: NodeTypes;
@@ -905,6 +1079,25 @@ type RivetInstance<TNodeData = unknown, TEdgeData = unknown> = RivetControls & {
         nodes?: NodeId[];
         edges?: EdgeId[];
     }) => void;
+    /**
+     * Apply a change batch that already happened elsewhere — a peer's edit off
+     * your transport. The graph updates and repaints, then re-emits the batch to
+     * `onNodesChange`/`onEdgesChange` tagged `"remote"`, so a controlled owner
+     * keeps its state in step through the one path it already has.
+     *
+     * Remote batches never create an undo step; in a shared document, undoing a
+     * peer's edit would silently revert work you don't own.
+     *
+     * ```ts
+     * connection.onNodeMoved((row) => {
+     *   if (row.caller === me) return // your own echo — already applied
+     *   rivet.applyRemote({
+     *     nodes: [{ type: "position", id: row.id, position: row.position }],
+     *   })
+     * })
+     * ```
+     */
+    applyRemote: (changes: RemoteChanges) => void;
     /**
      * Bind an anchor — a connectable point — to a DOM element inside a node.
      * The imperative core behind `<Anchor>`, for consumers whose content DOM is
@@ -926,6 +1119,40 @@ type RivetInstance<TNodeData = unknown, TEdgeData = unknown> = RivetControls & {
      * load) — rivet can't observe those.
      */
     remeasureAnchors: (nodeId: NodeId) => void;
+    /**
+     * Move a peer's cursor, in **world** coordinates (peers pan and zoom
+     * independently, so a screen point means nothing to them). `null` parks it.
+     *
+     * The presence hot path: it paints on the next frame without going through
+     * React, so call it as fast as your channel delivers. A peer the `peers`
+     * roster hasn't mentioned yet still gets a cursor — a frame that beats the
+     * join event shouldn't blink.
+     */
+    setPeerCursor: (peerId: string, point: Vec2 | null) => void;
+    /**
+     * Show a node where a peer currently has it, in world space — their drag,
+     * mid-flight. The node renders, hit-tests and wires at that box until their
+     * change lands through {@link applyRemote}; the graph itself is untouched.
+     * Pass `null` on their drop.
+     */
+    setPeerNodeTransform: (peerId: string, nodeId: NodeId, rect: Rect | null) => void;
+    /** Forget a peer entirely — cursor, held nodes and all. For a disconnect. */
+    removePeer: (peerId: string) => void;
+    /**
+     * Give up a gesture's hold on its nodes without committing — the yield lever
+     * for `onNodeLockConflict`, when your transport says this client lost the
+     * race for a node it's already dragging.
+     *
+     * The running gesture notices on its next frame, stops writing, and tears
+     * itself down; the nodes stay where they are and the holder's positions land
+     * normally from then on. `onNodeDragEnd` fires as it would on a drop, so a
+     * consumer's own lock release runs unchanged. Pass the conflict event's
+     * `ids` to release a whole group.
+     *
+     * Doing nothing is also a valid answer: without this call the gesture keeps
+     * its nodes until the pointer lifts.
+     */
+    releaseNodeGesture: (id: NodeId, ids?: NodeId[]) => void;
     /** Copy nodes (default: the current selection) to the in-memory clipboard. */
     copy: (ids?: NodeId[]) => void;
     /** Copy then delete nodes (default: the current selection). */
@@ -1028,4 +1255,4 @@ declare function rectsIntersect(a: Rect, b: Rect): boolean;
 
 declare const VERSION = "0.0.0";
 
-export { AlignmentGuide, BUILTIN_EDGE_TYPES, BUILTIN_NODE_TYPES, Canvas2DEdgeRenderer, type CloneOptions, type ClonedElements, Connection, Controls, type ControlsProps, DEFAULT_ALIGNMENT_HYSTERESIS, DefaultEdgeOptions, DefaultNode, type EdgeAlignment, EdgeChange, EdgeDrawExtras, EdgeEnd, type EdgeEndpoint, EdgeId, EdgePathFn, EdgeRenderer, EdgeRendererFactory, EdgeRendererOptions, EdgeTypes, GroupNode, Handle, HandlePosition, type HandleProps, HandleRecord, HandleType, MiniMap, type MiniMapProps, NodeChange, NodeId, NodeProps, NodeResizer, type NodeResizerProps, NodeTypes, type PaneContextMenuContext, PendingConnection, ReconnectDelegate, Rect, Rivet, RivetControls, RivetEdge, type RivetInstance, RivetNode, type RivetProps, RivetSelection, RivetSnapshot, type RivetStore, Size, VERSION, Vec2, Viewport, alignRect, applyEdgeChanges, applyNodeChanges, boundingRect, canvas2DEdgeRenderer, clampChildToParent, cloneElements, createRivetStore, edgeEndpointHandle, facingSide, getBezierPath, getSmoothStepPath, getStepPath, getStraightPath, handleKey, parseEdgeEndpoint, parseSideHandleId, rectsIntersect, resolveFacingSide, resolveFacingSideAmong, screenToWorld, serializeGraph, snapToGrid, useRivet, useRivetContext, useRivetControls, useRivetFocusedNode, useRivetHistory, useRivetViewport, viewportToCss, visibleWorldRect, worldToScreen, zoomAt };
+export { AlignmentGuide, BUILTIN_EDGE_TYPES, BUILTIN_NODE_TYPES, CanInteractWithLocked, Canvas2DEdgeRenderer, ChangeMeta, ChangeOrigin, type CloneOptions, type ClonedElements, Connection, Controls, type ControlsProps, DEFAULT_ALIGNMENT_HYSTERESIS, DefaultEdgeOptions, DefaultNode, type EdgeAlignment, EdgeChange, EdgeDrawExtras, EdgeEnd, type EdgeEndpoint, EdgeId, EdgePathFn, EdgeRenderer, EdgeRendererFactory, EdgeRendererOptions, EdgeTypes, GroupNode, Handle, HandlePosition, type HandleProps, HandleRecord, HandleType, LockRegistry, MiniMap, type MiniMapProps, NodeChange, NodeGestureEvent, NodeId, NodeLockConflictEvent, NodeProps, NodeResizer, type NodeResizerProps, NodeTypes, type PaneContextMenuContext, PendingConnection, ReconnectDelegate, Rect, type RemoteChanges, Rivet, RivetControls, RivetEdge, type RivetInstance, RivetNode, type RivetProps, RivetSelection, RivetSnapshot, type RivetStore, Size, VERSION, Vec2, Viewport, alignRect, applyEdgeChanges, applyNodeChanges, boundingRect, canvas2DEdgeRenderer, clampChildToParent, cloneElements, createRivetStore, edgeEndpointHandle, facingSide, getBezierPath, getSmoothStepPath, getStepPath, getStraightPath, handleKey, parseEdgeEndpoint, parseSideHandleId, rectsIntersect, resolveFacingSide, resolveFacingSideAmong, screenToWorld, serializeGraph, snapToGrid, useRivet, useRivetContext, useRivetControls, useRivetFocusedNode, useRivetHistory, useRivetViewport, viewportToCss, visibleWorldRect, worldToScreen, zoomAt };