@kolosal-ai/rivet 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,9 +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 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 { R as Rect, V as Vec2, A as AlignmentGuide, c as EdgeChange, d as RivetEdge, a as NodeChange, e as RivetNode, N as NodeId, f as NodeProps, g as NodeTypes, b as HandleType, H as HandlePosition, S as Size, h as ChangeOrigin, E 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-D3aldmsO.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-D3aldmsO.js';
 import { ReactNode, CSSProperties, MouseEvent, RefObject } from 'react';
-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 { e as AnchorRecord, g as AnchorRegistrationOptions, A as AnchorRef, c as AnchorOptions, R as ResolvedAnchorOptions, f as AnchorRegistration } from './registry-Z_oiPyjm.js';
+import { b as PresenceTargetKey, p as PresenceRegistry, h as LockRegistry, k as Peer, e as LocalPresence, o as PresenceOptions, C as CanInteractWithLocked, l as PeerConnection } from './use-node-lock-CbS59CRE.js';
+export { L as LOCK_DEFAULT_REFUSED, f as LockIntent, g as LockInteraction, i as LockTarget, N as NodeLock, y as useNodeLock, z as useNodeLockAllows } from './use-node-lock-CbS59CRE.js';
 import { ResolvedLane, ViewportElements, ResolvedSwimlaneGroup, ResolvedMargin } from './swimlane/index.js';
 
 /**
@@ -319,6 +319,19 @@ type RivetStore = {
     setViewportClamp: (clamp: ViewportClamp | null) => void;
     subscribeFrame: (listener: () => void) => () => void;
     notifyFrame: () => void;
+    /**
+     * Post-frame channel for peer cursors alone. Fires after every frame that
+     * repainted them — the cursor-only frames a pointer move schedules, *and*
+     * full frames, which own every layer.
+     *
+     * Its own channel because cursor frames are the ones that arrive at pointer
+     * rate for every peer: chrome that follows a cursor needs all of them, while
+     * everything else on {@link subscribeFrame} would be woken up for nothing.
+     * Read positions off `presence.getPeers()` — they're the interpolated ones,
+     * already stepped for this frame.
+     */
+    subscribeCursorFrame: (listener: () => void) => () => void;
+    notifyCursorFrame: () => void;
     /** Move a node. `commit` re-renders just that node; skip it during drag. */
     moveNode: (id: NodeId, position: Vec2, commit: boolean) => void;
     setNodeSize: (id: NodeId, size: Size) => void;
@@ -400,12 +413,17 @@ type RivetStore = {
      */
     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.
+     * Publish the lock table (the `lockedNodes` prop), keyed by
+     * {@link PresenceTargetKey}, 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.
+     *
+     * Only node gestures are scanned, because only nodes are held: an edge or an
+     * anchor has no gesture to conflict with, so a lock on either is simply in
+     * force from the moment it arrives.
      */
-    setLockedNodes: (locks: Record<NodeId, string> | undefined) => void;
+    setLockedNodes: (locks: Record<PresenceTargetKey, string> | undefined) => void;
     /**
      * True while a local gesture holds this node. Held geometry is exclusively
      * this client's: {@link applyRemote} drops incoming `position`/`dimensions`
@@ -440,6 +458,11 @@ type RivetStore = {
     getSelectedNodes: () => NodeId[];
     /** True if the node is part of the current selection. */
     isNodeSelected: (id: NodeId) => boolean;
+    /**
+     * The selected edge, if any — edge selection is single. The id alone, for
+     * callers that would otherwise build {@link getSelection}'s records to read it.
+     */
+    getSelectedEdgeId: () => EdgeId | null;
     /** The current selection (nodes + edges) as full records. */
     getSelection: () => RivetSelection;
     /** Subscribe to selection changes (nodes and/or edges). */
@@ -506,6 +529,14 @@ type RivetStore = {
     subscribeHistory: (listener: () => void) => () => void;
     getEdgeLabelAnchors: () => Map<EdgeId, Vec2>;
     setEdgeLabelAnchors: (anchors: Map<EdgeId, Vec2>) => void;
+    /**
+     * Screen-space anchor points for the edges peers have claimed, from the same
+     * renderer pass — a point on each drawn path, which is the one thing a DOM
+     * outline layer can't work out for itself. Empty unless something is claimed
+     * and DOM outline chrome is mounted.
+     */
+    getPeerEdgeAnchors: () => ReadonlyMap<EdgeId, Vec2>;
+    setPeerEdgeAnchors: (anchors: ReadonlyMap<EdgeId, Vec2>) => void;
     /** Alignment/snap guides to draw for the current drag (world space). Empty when idle. */
     getAlignmentGuides: () => AlignmentGuide[];
     setAlignmentGuides: (guides: AlignmentGuide[]) => void;
@@ -550,15 +581,40 @@ type RivetStore = {
     getNodeAnchors: (nodeId: NodeId) => AnchorRecord[];
     getNodeAnchorsVersion: (nodeId: NodeId) => number;
     subscribeNodeAnchors: (nodeId: NodeId, listener: () => void) => () => void;
+    /** The selected anchors. A cached snapshot — identity changes with the data. */
+    getSelectedAnchors: () => readonly AnchorRef[];
+    /**
+     * Replace the anchor selection. Selecting any anchor clears the node and edge
+     * selection: one selection concept, so delete and the chrome never describe
+     * two claims at once.
+     */
+    setSelectedAnchors: (refs: readonly AnchorRef[]) => void;
+    isAnchorSelected: (nodeId: NodeId, anchorId: string) => boolean;
+    subscribeAnchorSelection: (listener: () => void) => () => void;
     getEdgesVersion: () => number;
     subscribeEdges: (listener: () => void) => () => void;
     getPending: () => PendingConnection | null;
     beginConnection: (pending: PendingConnection) => void;
     updateConnection: (to: Vec2, toPosition?: HandlePosition) => void;
     endConnection: () => void;
+    /**
+     * The local pending connection changing — started, moved, dropped. Its own
+     * channel because presence has to publish it: the drag lives entirely in the
+     * canvas otherwise, and nothing else would tell an outbound tracker that a
+     * wire was let go of (a drop that moves the pointer no further would leave a
+     * peer's copy hanging there).
+     */
+    subscribeConnection: (listener: () => void) => () => void;
     /** Ask the runtime to schedule a canvas frame. */
     requestRender: () => void;
     bindRenderRequester: (fn: () => void) => void;
+    /**
+     * Ask the runtime to repaint the peer-cursor layer only — everything else on
+     * screen keeps last frame's pixels. Degrades to {@link requestRender} while
+     * no runtime has claimed the layer, so a caller never has to check.
+     */
+    requestCursorRender: () => void;
+    bindCursorRenderRequester: (fn: (() => void) | null) => void;
 };
 /** Create a graph store. The public entry point; the class is an implementation detail. */
 declare function createRivetStore(init: RivetStoreInit): RivetStore;
@@ -665,10 +721,14 @@ type RivetProps = {
     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.
+     * colour, `data`) 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.
+     *
+     * Claims are node ids, or `PresenceTarget`s for an edge or an anchor. Only
+     * nodes are painted today — the rest travels and is readable through
+     * {@link usePeers}, which is what a consumer rendering its own chrome needs.
      *
      * 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
@@ -688,16 +748,40 @@ type RivetProps = {
      * immediately.
      */
     onLocalPresence?: (presence: LocalPresence) => void;
-    /** Presence policy — outbound throttle, and whether rivet paints peer cursors. */
+    /**
+     * Presence policy — the outbound throttle, and how peer cursors are drawn:
+     * rivet's canvas arrow, your own component, or nothing.
+     *
+     * Compared shallowly, so `cursorComponent` must be a stable reference —
+     * declared outside the render or memoized. An inline component would be a new
+     * type on every render, and React remounts every cursor when the type changes.
+     */
     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.
+     * What a peer has claimed, as `target -> peerId`. Locks are policy where
+     * {@link peers} is description: rivet paints a claimed element 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.
+     * Keys are {@link PresenceTargetKey}s, and a bare node id is its own key — so
+     * `{ n1: "ada" }` means exactly what it always did, and edges and anchors
+     * join on the same table:
+     *
+     * ```tsx
+     * <Rivet
+     *   lockedNodes={{
+     *     n1: "ada",                  // a node, and everything inside it
+     *     "edge:e7": "kai",           // an edge — refuses reconnection
+     *     "anchor:n2:door": "wren",   // one anchor inside n2
+     *   }}
+     * />
+     * ```
+     *
+     * By default it refuses selection, dragging, resizing, deletion and
+     * reconnection, and allows connections — a lock claims the element, not the
+     * graph around it. {@link canInteractWithLocked} replaces that policy.
+     *
+     * A node's lock reaches its contents and their anchors; an edge's reaches
+     * nothing, since an edge belongs to no container.
      *
      * Lifetime is yours: rivet never takes or releases a lock, it only reads the
      * table. Take one in {@link onNodeDragStart} and drop it in
@@ -705,10 +789,10 @@ type RivetProps = {
      * for something stickier. Like presence, none of this reaches the graph, the
      * change stream, or history.
      */
-    lockedNodes?: Record<NodeId, string>;
+    lockedNodes?: Record<PresenceTargetKey, string>;
     /**
-     * Decide what this client may do to a locked node, per attempt. Return `true`
-     * to allow the intent, `false` to refuse it.
+     * Decide what this client may do to a locked element, 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:
@@ -718,6 +802,16 @@ type RivetProps = {
      * canInteractWithLocked={({ intent }) => intent === "select" || intent === "connect"}
      * ```
      *
+     * `target` is what was touched and `lockedTarget` is what carries the lock —
+     * they differ when a lock is inherited, which is how a locked container can
+     * hold itself while leaving its contents free:
+     *
+     * ```tsx
+     * canInteractWithLocked={({ target, lockedTarget }) =>
+     *   target.kind === "node" && lockedTarget.kind === "node" && target.id !== lockedTarget.id
+     * }
+     * ```
+     *
      * Called on the input path (every marquee frame, every mover), so keep it
      * cheap and free of side effects.
      */
@@ -1066,6 +1160,20 @@ type RivetInstance<TNodeData = unknown, TEdgeData = unknown> = RivetControls & {
     toObject: () => RivetSnapshot<TNodeData, TEdgeData>;
     getNodes: () => RivetNode<TNodeData>[];
     getNode: (id: NodeId) => RivetNode<TNodeData> | undefined;
+    /**
+     * A node's box in **world** coordinates — its `parentId` chain resolved, and
+     * its explicit or measured size applied. `null` for an id that isn't in the
+     * graph.
+     *
+     * This is where the node currently *is on screen*, not what the document
+     * says: a node a peer is dragging or resizing reports the box they last sent
+     * (see {@link setPeerNodeTransform}), which is what anything painting over
+     * the graph wants. Reach for {@link getNode} instead when you're computing a
+     * mutation — that position is the one the document will agree with.
+     *
+     * Reads once; never subscribes. Call it inside your own frame loop.
+     */
+    getNodeRect: (id: NodeId) => Rect | null;
     setNodes: (nodes: Updater<RivetNode<TNodeData>[]>) => void;
     addNodes: (nodes: RivetNode<TNodeData> | RivetNode<TNodeData>[]) => void;
     updateNode: (id: NodeId, patch: Updater<RivetNode<TNodeData>>) => void;
@@ -1119,6 +1227,19 @@ type RivetInstance<TNodeData = unknown, TEdgeData = unknown> = RivetControls & {
      * load) — rivet can't observe those.
      */
     remeasureAnchors: (nodeId: NodeId) => void;
+    /**
+     * One anchor's record — geometry, colour, and whatever `data` was registered
+     * with it — or `null` when the node has no such anchor.
+     */
+    getAnchor: (nodeId: NodeId, anchorId: string) => AnchorRecord | null;
+    /**
+     * Replace the anchor selection. Selecting an anchor clears the node and edge
+     * selection. View state: no change is emitted and nothing is recorded to
+     * history, so this is safe to call from a render-driven effect.
+     */
+    setSelectedAnchors: (refs: readonly AnchorRef[]) => void;
+    /** The selected anchors. Reactive through `useSelectedAnchors()`. */
+    getSelectedAnchors: () => readonly AnchorRef[];
     /**
      * Move a peer's cursor, in **world** coordinates (peers pan and zoom
      * independently, so a screen point means nothing to them). `null` parks it.
@@ -1136,6 +1257,16 @@ type RivetInstance<TNodeData = unknown, TEdgeData = unknown> = RivetControls & {
      * Pass `null` on their drop.
      */
     setPeerNodeTransform: (peerId: string, nodeId: NodeId, rect: Rect | null) => void;
+    /**
+     * Draw the wire a peer is pulling out of a handle — their `LocalPresence.pending`,
+     * fed straight back. Both ends are in **world** coordinates. Pass `null` when
+     * they let go, which their next snapshot says either way.
+     *
+     * Painted on the foreground in their colour, with a dot on the loose end. It
+     * changes nothing about the graph: a connection exists when their change
+     * lands, not while they're dragging toward it.
+     */
+    setPeerConnection: (peerId: string, connection: PeerConnection | null) => void;
     /** Forget a peer entirely — cursor, held nodes and all. For a disconnect. */
     removePeer: (peerId: string) => void;
     /**
@@ -1203,10 +1334,14 @@ declare class Canvas2DEdgeRenderer implements EdgeRenderer {
     private readonly endpoints;
     /** Screen-space label anchor per edge that has a label. */
     private readonly labels;
+    /** Screen-space midpoint per edge somebody has claimed, for DOM claim chrome. */
+    private readonly peerAnchors;
     constructor(canvas: HTMLCanvasElement, options?: EdgeRendererOptions);
     resize(width: number, height: number, dpr: number): void;
     /** Screen-space label anchors for the edges drawn last frame. */
     getLabels(): Map<EdgeId, Vec2>;
+    /** Screen-space midpoints for the edges a peer had claimed last frame. */
+    getPeerEdgeAnchors(): ReadonlyMap<EdgeId, Vec2>;
     /** Screen-space endpoints per edge from the last frame (reconnect affordance). */
     getEndpoints(): ReadonlyMap<EdgeId, {
         source: Vec2;