@kolosal-ai/rivet 0.1.1 → 0.3.0

package/dist/presence/index.d.ts

@@ -0,0 +1,108 @@
+import { P as PeerRecord } from '../use-node-lock-DH0dB1yA.js';
+export { C as CanInteractWithLocked, D as DEFAULT_PRESENCE_OPTIONS, L as LOCK_DEFAULT_REFUSED, a as LocalPresence, b as LockIntent, c as LockInteraction, d as LockRegistry, N as NodeLock, e as PEER_COLORS, f as Peer, g as PresenceOptions, h as PresenceRegistry, R as ResolvedPresenceOptions, p as peerColor, u as useNodeLock, i as useNodeLockAllows } from '../use-node-lock-DH0dB1yA.js';
+import { a as NodeChange } from '../types-C9Vn1rzy.js';
+import 'react';
+
+/**
+ * The peers currently in the document — for participant chrome you render
+ * yourself: an avatar stack, a follow button, a "3 others editing" line.
+ *
+ * Re-renders when the **roster** changes: someone joins or leaves, is renamed,
+ * or changes what they have selected or held. It deliberately does *not*
+ * re-render on cursor frames — those arrive at pointer rate and are already
+ * painted on the canvas. If you're rendering cursors in the DOM yourself (with
+ * `presenceOptions={{ renderCursors: false }}`), read them off the frame
+ * channel instead, where the rest of the imperative chrome lives.
+ */
+declare function usePeers(): readonly PeerRecord[];
+
+/**
+ * Which local changes belong on the wire, and at which speed.
+ *
+ * Publishing a change batch to peers means answering three questions per
+ * change: is this the document (send it, keep it), is it a live gesture frame
+ * (send it, throw it away on the next one), or is it this client talking to
+ * itself (never send it). The answers are rivet semantics — they depend on
+ * which fields are gesture-bounded and which flags mark a frame as uncommitted
+ * — and every one of them fails *silently* when a consumer guesses wrong:
+ * nothing throws, the shared graph just misbehaves in ways that read like
+ * transport bugs.
+ *
+ * So the classification lives here. Transport policy does not: throttling the
+ * ephemeral half, batching or coalescing the durable half, and deciding what a
+ * frame even looks like on your wire are all yours.
+ */
+
+/**
+ * A change that can carry an uncommitted gesture frame — the only two kinds a
+ * gesture produces mid-flight. Narrower than {@link NodeChange} so that the
+ * ephemeral half always has an `id` to key a transform by.
+ */
+type EphemeralNodeChange<TData = unknown> = Extract<NodeChange<TData>, {
+    type: "position" | "dimensions";
+}>;
+/** The two halves of a local batch, as returned by {@link splitLocalNodeChanges}. */
+type LocalNodeChangeSplit<TData = unknown> = {
+    /**
+     * Document mutations. Send these, and expect peers to keep them: they're
+     * what a client that reloads has to see.
+     */
+    durable: NodeChange<TData>[];
+    /**
+     * Uncommitted gesture frames — where this client currently has a node, not
+     * where it has agreed to put it. Send them as ephemeral state (rivet's own
+     * inbound door for this is `setPeerNodeTransform`, which paints without
+     * touching the graph); drop them freely under load, because the commit that
+     * closes the gesture arrives in {@link LocalNodeChangeSplit.durable}.
+     *
+     * One gesture frame can appear twice in a batch — a resize dragged from a
+     * top-left handle emits both a `dimensions` and a `position` change for the
+     * same node — so key by `id` rather than counting.
+     */
+    ephemeral: EphemeralNodeChange<TData>[];
+};
+/**
+ * Split a local `onNodesChange` batch into the half peers must keep and the
+ * half they only need until the next frame. Changes that must not travel at
+ * all are in neither array.
+ *
+ * | change | bucket | why |
+ * | --- | --- | --- |
+ * | `add` / `remove` / `replace` | durable | the document |
+ * | `position`, `dragging` unset or `false` | durable | the commit that closes a move |
+ * | `position` with `dragging: true` | ephemeral | a live drag frame |
+ * | `dimensions` with `resizing: false` | durable | the commit that closes a resize |
+ * | `dimensions` with `resizing: true` | ephemeral | a live resize frame |
+ * | `dimensions` with no `resizing` flag | **dropped** | a measurement |
+ * | `select` | **dropped** | selection is presence |
+ *
+ * The two drops are the ones worth having in the library. A `select` on the
+ * wire makes every client select in unison — selection is a fact about a
+ * person, and it travels through `onLocalPresence` instead. And an unflagged
+ * `dimensions` is this client reporting its own measured DOM box, which every
+ * client produces for itself; publishing yours makes peers fight each other's
+ * layout. That distinction — a measurement echo versus a real resize — is
+ * invisible from outside without reading the store.
+ *
+ * Only call this on batches whose `ChangeMeta.origin` is `"local"`; a batch
+ * re-emitted after `applyRemote` is a peer's edit coming back, and sending it
+ * on is the echo loop.
+ *
+ * ```ts
+ * onNodesChange={(changes, meta) => {
+ *   setNodes((current) => applyNodeChanges(changes, current))
+ *   if (meta.origin !== "local") return
+ *   const { durable, ephemeral } = splitLocalNodeChanges(changes)
+ *   if (durable.length > 0) channel.send({ kind: "nodes", changes: durable })
+ *   for (const change of ephemeral) {
+ *     channel.send({ kind: "transform", id: change.id, rect: rivet.getNodeRect(change.id) })
+ *   }
+ * }}
+ * ```
+ *
+ * Edge changes need no equivalent: they carry no gesture-bounded fields, so
+ * dropping `select` is the whole rule.
+ */
+declare function splitLocalNodeChanges<TData = unknown>(changes: readonly NodeChange<TData>[]): LocalNodeChangeSplit<TData>;
+
+export { type EphemeralNodeChange, type LocalNodeChangeSplit, PeerRecord, splitLocalNodeChanges, usePeers };

package/dist/presence/index.js

@@ -0,0 +1,38 @@
+export { DEFAULT_PRESENCE_OPTIONS, LOCK_DEFAULT_REFUSED, PEER_COLORS, peerColor, useNodeLock, useNodeLockAllows } from '../chunk-A52HZWLH.js';
+import { useRivetContext } from '../chunk-VQYN27OK.js';
+import { useSyncExternalStore } from 'react';
+
+function usePeers() {
+  const { store } = useRivetContext();
+  return useSyncExternalStore(
+    store.presence.subscribe,
+    store.presence.getPeers,
+    store.presence.getPeers
+  );
+}
+
+// src/presence/changes.ts
+function splitLocalNodeChanges(changes) {
+  const durable = [];
+  const ephemeral = [];
+  for (const change of changes) {
+    if (change.type === "select") continue;
+    if (change.type === "position") {
+      if (change.dragging) ephemeral.push(change);
+      else durable.push(change);
+      continue;
+    }
+    if (change.type === "dimensions") {
+      if (change.resizing === void 0) continue;
+      if (change.resizing) ephemeral.push(change);
+      else durable.push(change);
+      continue;
+    }
+    durable.push(change);
+  }
+  return { durable, ephemeral };
+}
+
+export { splitLocalNodeChanges, usePeers };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/presence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/hooks/use-peers.ts","../../src/presence/changes.ts"],"names":[],"mappings":";;;;AAeO,SAAS,QAAA,GAAkC;AAChD,EAAA,MAAM,EAAE,KAAA,EAAM,GAAI,eAAA,EAAgB;AAClC,EAAA,OAAO,oBAAA;AAAA,IACL,MAAM,QAAA,CAAS,SAAA;AAAA,IACf,MAAM,QAAA,CAAS,QAAA;AAAA,IACf,MAAM,QAAA,CAAS;AAAA,GACjB;AACF;;;ACsEO,SAAS,sBACd,OAAA,EAC6B;AAC7B,EAAA,MAAM,UAA+B,EAAC;AACtC,EAAA,MAAM,YAA0C,EAAC;AAEjD,EAAA,KAAA,MAAW,UAAU,OAAA,EAAS;AAC5B,IAAA,IAAI,MAAA,CAAO,SAAS,QAAA,EAAU;AAE9B,IAAA,IAAI,MAAA,CAAO,SAAS,UAAA,EAAY;AAC9B,MAAA,IAAI,MAAA,CAAO,QAAA,EAAU,SAAA,CAAU,IAAA,CAAK,MAAM,CAAA;AAAA,WACrC,OAAA,CAAQ,KAAK,MAAM,CAAA;AACxB,MAAA;AAAA,IACF;AAEA,IAAA,IAAI,MAAA,CAAO,SAAS,YAAA,EAAc;AAEhC,MAAA,IAAI,MAAA,CAAO,aAAa,MAAA,EAAW;AACnC,MAAA,IAAI,MAAA,CAAO,QAAA,EAAU,SAAA,CAAU,IAAA,CAAK,MAAM,CAAA;AAAA,WACrC,OAAA,CAAQ,KAAK,MAAM,CAAA;AACxB,MAAA;AAAA,IACF;AAEA,IAAA,OAAA,CAAQ,KAAK,MAAM,CAAA;AAAA,EACrB;AAEA,EAAA,OAAO,EAAE,SAAS,SAAA,EAAU;AAC9B","file":"index.js","sourcesContent":["import { useSyncExternalStore } from \"react\"\nimport { useRivetContext } from \"../context\"\nimport type { PeerRecord } from \"../presence/registry\"\n\n/**\n * The peers currently in the document — for participant chrome you render\n * yourself: an avatar stack, a follow button, a \"3 others editing\" line.\n *\n * Re-renders when the **roster** changes: someone joins or leaves, is renamed,\n * or changes what they have selected or held. It deliberately does *not*\n * re-render on cursor frames — those arrive at pointer rate and are already\n * painted on the canvas. If you're rendering cursors in the DOM yourself (with\n * `presenceOptions={{ renderCursors: false }}`), read them off the frame\n * channel instead, where the rest of the imperative chrome lives.\n */\nexport function usePeers(): readonly PeerRecord[] {\n  const { store } = useRivetContext()\n  return useSyncExternalStore(\n    store.presence.subscribe,\n    store.presence.getPeers,\n    store.presence.getPeers,\n  )\n}\n","/**\n * Which local changes belong on the wire, and at which speed.\n *\n * Publishing a change batch to peers means answering three questions per\n * change: is this the document (send it, keep it), is it a live gesture frame\n * (send it, throw it away on the next one), or is it this client talking to\n * itself (never send it). The answers are rivet semantics — they depend on\n * which fields are gesture-bounded and which flags mark a frame as uncommitted\n * — and every one of them fails *silently* when a consumer guesses wrong:\n * nothing throws, the shared graph just misbehaves in ways that read like\n * transport bugs.\n *\n * So the classification lives here. Transport policy does not: throttling the\n * ephemeral half, batching or coalescing the durable half, and deciding what a\n * frame even looks like on your wire are all yours.\n */\n\nimport type { NodeChange } from \"../types\"\n\n/**\n * A change that can carry an uncommitted gesture frame — the only two kinds a\n * gesture produces mid-flight. Narrower than {@link NodeChange} so that the\n * ephemeral half always has an `id` to key a transform by.\n */\nexport type EphemeralNodeChange<TData = unknown> = Extract<\n  NodeChange<TData>,\n  { type: \"position\" | \"dimensions\" }\n>\n\n/** The two halves of a local batch, as returned by {@link splitLocalNodeChanges}. */\nexport type LocalNodeChangeSplit<TData = unknown> = {\n  /**\n   * Document mutations. Send these, and expect peers to keep them: they're\n   * what a client that reloads has to see.\n   */\n  durable: NodeChange<TData>[]\n  /**\n   * Uncommitted gesture frames — where this client currently has a node, not\n   * where it has agreed to put it. Send them as ephemeral state (rivet's own\n   * inbound door for this is `setPeerNodeTransform`, which paints without\n   * touching the graph); drop them freely under load, because the commit that\n   * closes the gesture arrives in {@link LocalNodeChangeSplit.durable}.\n   *\n   * One gesture frame can appear twice in a batch — a resize dragged from a\n   * top-left handle emits both a `dimensions` and a `position` change for the\n   * same node — so key by `id` rather than counting.\n   */\n  ephemeral: EphemeralNodeChange<TData>[]\n}\n\n/**\n * Split a local `onNodesChange` batch into the half peers must keep and the\n * half they only need until the next frame. Changes that must not travel at\n * all are in neither array.\n *\n * | change | bucket | why |\n * | --- | --- | --- |\n * | `add` / `remove` / `replace` | durable | the document |\n * | `position`, `dragging` unset or `false` | durable | the commit that closes a move |\n * | `position` with `dragging: true` | ephemeral | a live drag frame |\n * | `dimensions` with `resizing: false` | durable | the commit that closes a resize |\n * | `dimensions` with `resizing: true` | ephemeral | a live resize frame |\n * | `dimensions` with no `resizing` flag | **dropped** | a measurement |\n * | `select` | **dropped** | selection is presence |\n *\n * The two drops are the ones worth having in the library. A `select` on the\n * wire makes every client select in unison — selection is a fact about a\n * person, and it travels through `onLocalPresence` instead. And an unflagged\n * `dimensions` is this client reporting its own measured DOM box, which every\n * client produces for itself; publishing yours makes peers fight each other's\n * layout. That distinction — a measurement echo versus a real resize — is\n * invisible from outside without reading the store.\n *\n * Only call this on batches whose `ChangeMeta.origin` is `\"local\"`; a batch\n * re-emitted after `applyRemote` is a peer's edit coming back, and sending it\n * on is the echo loop.\n *\n * ```ts\n * onNodesChange={(changes, meta) => {\n *   setNodes((current) => applyNodeChanges(changes, current))\n *   if (meta.origin !== \"local\") return\n *   const { durable, ephemeral } = splitLocalNodeChanges(changes)\n *   if (durable.length > 0) channel.send({ kind: \"nodes\", changes: durable })\n *   for (const change of ephemeral) {\n *     channel.send({ kind: \"transform\", id: change.id, rect: rivet.getNodeRect(change.id) })\n *   }\n * }}\n * ```\n *\n * Edge changes need no equivalent: they carry no gesture-bounded fields, so\n * dropping `select` is the whole rule.\n */\nexport function splitLocalNodeChanges<TData = unknown>(\n  changes: readonly NodeChange<TData>[],\n): LocalNodeChangeSplit<TData> {\n  const durable: NodeChange<TData>[] = []\n  const ephemeral: EphemeralNodeChange<TData>[] = []\n\n  for (const change of changes) {\n    if (change.type === \"select\") continue\n\n    if (change.type === \"position\") {\n      if (change.dragging) ephemeral.push(change)\n      else durable.push(change)\n      continue\n    }\n\n    if (change.type === \"dimensions\") {\n      // No flag at all means nobody resized: the store measured the DOM.\n      if (change.resizing === undefined) continue\n      if (change.resizing) ephemeral.push(change)\n      else durable.push(change)\n      continue\n    }\n\n    durable.push(change)\n  }\n\n  return { durable, ephemeral }\n}\n"]}

package/dist/{registry-Dkk4ZKt-.d.ts → registry-CCBgd7FN.d.ts}

@@ -1,4 +1,4 @@
-import { H as HandlePosition, N as NodeId, C as Connection } from './types-B8AAJ60T.js';
+import { H as HandlePosition, N as NodeId, C as Connection } from './types-C9Vn1rzy.js';
 
 /**
  * Anchor — a connectable point bound to a DOM element rendered inside a node.

package/dist/svg/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { CSSProperties } from 'react';
-import { g as AnchorStrayPolicy } from '../registry-Dkk4ZKt-.js';
-import '../types-B8AAJ60T.js';
+import { g as AnchorStrayPolicy } from '../registry-CCBgd7FN.js';
+import '../types-C9Vn1rzy.js';
 
 /**
  * The extract seam behind `<SvgArtwork>` — which elements inside a parsed

package/dist/swimlane/index.d.ts

@@ -1,5 +1,5 @@
-import { R as Rect, c as RivetNode, V as Vec2, S as Size, k as SwimlaneMargin, j as SwimlaneGroup } from '../types-B8AAJ60T.js';
-export { L as LaneChange, M as Swimlane, l as SwimlaneHeaderProps, m as SwimlaneLabelProps, n as SwimlaneSizeChange } from '../types-B8AAJ60T.js';
+import { R as Rect, c as RivetNode, V as Vec2, S as Size, s as SwimlaneMargin, r as SwimlaneGroup } from '../types-C9Vn1rzy.js';
+export { L as LaneChange, U as Swimlane, t as SwimlaneHeaderProps, u as SwimlaneLabelProps, v as SwimlaneSizeChange } from '../types-C9Vn1rzy.js';
 import 'react';
 
 /** World height of a group's sticky header band. */

package/dist/{types-B8AAJ60T.d.ts → types-C9Vn1rzy.d.ts}

@@ -205,6 +205,60 @@ type EdgeChange<TData = unknown> = {
     id: EdgeId;
     item: RivetEdge<TData>;
 };
+/**
+ * Where a change batch came from.
+ *
+ * - `"local"` — this client produced it (a gesture, a `useRivet()` call). In a
+ *   multiplayer app this is the batch you send to your server.
+ * - `"remote"` — it arrived through {@link RivetStore.applyRemote}, i.e. it has
+ *   already happened elsewhere. Apply it to your state, but don't send it back
+ *   or the echo becomes a loop.
+ *
+ * Any other string is passed through untouched, so you can carry a peer id or a
+ * transaction id if you'd rather route on that.
+ */
+type ChangeOrigin = "local" | "remote" | (string & {});
+/**
+ * Batch metadata handed to `onNodesChange`/`onEdgesChange` alongside the changes.
+ * Every change in one batch shares an origin by construction.
+ */
+type ChangeMeta = {
+    origin: ChangeOrigin;
+};
+/**
+ * A local gesture opening or closing on one or more nodes — a pointer drag, a
+ * resize, or a keyboard grab. In a shared document these are the acquire and
+ * release signals: take a lock on start, drop it on end.
+ *
+ * - `id` — the node the gesture began on (the one grabbed).
+ * - `ids` — every node moving with it, `id` included. A group drag carries the
+ *   whole selection; a resize carries one node.
+ */
+type NodeGestureEvent = {
+    id: NodeId;
+    ids: NodeId[];
+};
+/**
+ * A peer's lock arrived on a node this client is already holding — the double-
+ * hold a gesture guard alone can't rule out, since two clients can start a drag
+ * before either one's lock reaches the other.
+ *
+ * rivet reports it and keeps going: the running gesture stays authoritative
+ * over its geometry, because ripping a node out from under a live pointer is a
+ * worse outcome than a late merge, and only the consumer knows whether its
+ * transport made this client the loser. Yield with
+ * {@link RivetInstance.releaseNodeGesture}.
+ *
+ * - `nodeId` — the held node the incoming lock names.
+ * - `holderId` — the peer the lock table gives it to.
+ * - `ids` — every node the local gesture is holding, `nodeId` included, so a
+ *   consumer that yields can release the whole group in one call.
+ */
+type NodeLockConflictEvent = {
+    nodeId: NodeId;
+    holderId: string;
+    ids: NodeId[];
+};
 /**
  * What a handle may be when dragging a connection:
  * - `"source"` — can only start an edge.
@@ -512,4 +566,4 @@ type RivetControls = {
     setViewport: (viewport: Viewport) => void;
 };
 
-export type { AlignmentGuide as A, EdgeMarker as B, Connection as C, DefaultEdgeOptions as D, EdgeChange as E, EdgePath as F, EdgePathParams as G, HandlePosition as H, EdgeStyle as I, FitViewOptions as J, NodeComponent as K, LaneChange as L, Swimlane as M, NodeId as N, PendingConnection as P, Rect as R, Size as S, Vec2 as V, RivetEdge as a, NodeChange as b, RivetNode as c, NodeProps as d, NodeTypes as e, HandleType as f, Viewport as g, EdgeTypes as h, EdgeRendererFactory as i, SwimlaneGroup as j, SwimlaneMargin as k, SwimlaneHeaderProps as l, SwimlaneLabelProps as m, SwimlaneSizeChange as n, RivetSelection as o, EdgeId as p, HandleRecord as q, ReconnectDelegate as r, RivetControls as s, RivetSnapshot as t, EdgeRenderer as u, EdgeRendererOptions as v, EdgeDrawExtras as w, EdgeEnd as x, EdgePathFn as y, CenterNodeOptions as z };
+export type { AlignmentGuide as A, EdgeDrawExtras as B, Connection as C, DefaultEdgeOptions as D, EdgeChange as E, EdgeEnd as F, EdgePathFn as G, HandlePosition as H, CenterNodeOptions as I, EdgeMarker as J, EdgePath as K, LaneChange as L, EdgePathParams as M, NodeId as N, EdgeStyle as O, PendingConnection as P, FitViewOptions as Q, Rect as R, Size as S, NodeComponent as T, Swimlane as U, Vec2 as V, NodeChange as a, RivetEdge as b, RivetNode as c, NodeProps as d, NodeTypes as e, HandleType as f, ChangeOrigin as g, EdgeId as h, HandleRecord as i, ChangeMeta as j, Viewport as k, NodeGestureEvent as l, NodeLockConflictEvent as m, RivetSelection as n, ReconnectDelegate as o, EdgeTypes as p, EdgeRendererFactory as q, SwimlaneGroup as r, SwimlaneMargin as s, SwimlaneHeaderProps as t, SwimlaneLabelProps as u, SwimlaneSizeChange as v, RivetControls as w, RivetSnapshot as x, EdgeRenderer as y, EdgeRendererOptions as z };

package/dist/use-node-lock-DH0dB1yA.d.ts

@@ -0,0 +1,327 @@
+import { N as NodeId, V as Vec2, R as Rect } from './types-C9Vn1rzy.js';
+
+/**
+ * Locks — nodes a peer has claimed, and what this client may still do to them.
+ *
+ * A lock is policy where presence is description. `Peer.holding` says "they
+ * have their pointer on this"; a lock says "hands off", and rivet acts on it.
+ * The two render identically on purpose — to whoever is looking, they mean the
+ * same thing — but only a lock refuses anything.
+ *
+ * Locks come in whole, as the `lockedNodes` prop, because the transport already
+ * has to hold them: a lock outlives the tab that took it (that's the point of
+ * taking one), so the server owns the lifetime and rivet only reads it. Nothing
+ * here enters the graph, the change stream, or history — a lock is no more a
+ * fact about the document than a cursor is.
+ *
+ * What a lock refuses is a default, not a rule. {@link LOCK_DEFAULT_REFUSED} is
+ * rivet's opinion; `canInteractWithLocked` is the consumer's, and it wins on
+ * every intent it's asked about.
+ */
+
+/**
+ * A thing this client might try to do to a locked node.
+ *
+ * Granular because the answer genuinely differs per app: a design tool wants a
+ * locked node inspectable, a form builder wants it untouchable, and a pipeline
+ * editor usually wants to keep wiring around one while a colleague renames it.
+ */
+type LockIntent = 
+/** Click it, or sweep it up in a marquee. */
+"select"
+/** Move it — pointer drag, group drag, keyboard grab or arrow nudge. */
+ | "drag"
+/** Change its box through {@link NodeResizer}. */
+ | "resize"
+/** Remove it as part of deleting the selection. */
+ | "delete"
+/** Start or land an edge on one of its handles. */
+ | "connect";
+/** What {@link CanInteractWithLocked} is asked about. */
+type LockInteraction = {
+    nodeId: NodeId;
+    /** The peer holding the lock — the `lockedNodes` value for this node. */
+    holderId: string;
+    intent: LockIntent;
+};
+/**
+ * Consumer override for rivet's default refusals, consulted once per attempt.
+ * Return `true` to allow the intent, `false` to refuse it — the default is
+ * replaced, not consulted, so a handler owns the whole policy.
+ */
+type CanInteractWithLocked = (event: LockInteraction) => boolean;
+/** A node's lock as {@link useNodeLock} reports it. */
+type NodeLock = {
+    locked: boolean;
+    /** The peer holding it, or `undefined` when the node isn't locked. */
+    holderId?: string;
+};
+/**
+ * The intents rivet refuses on a locked node when no policy is given.
+ *
+ * `connect` is deliberately absent. A lock claims the node, not the graph
+ * around it: an edge is its own row with its own id, and refusing to wire one
+ * would make a locked node an island for as long as somebody holds it — a far
+ * heavier lock than "someone is editing this" warrants. Consumers who want that
+ * can say so through {@link CanInteractWithLocked}.
+ */
+declare const LOCK_DEFAULT_REFUSED: ReadonlySet<LockIntent>;
+/**
+ * The lock registry — one per graph, reachable as `store.locks`.
+ *
+ * Reads are hot: every marquee frame and every mover loop asks
+ * {@link LockRegistry.allows}, so it stays a map lookup plus at most one
+ * consumer call, with no allocation on the common (nothing locked) path.
+ */
+type LockRegistry = {
+    /**
+     * Replace the lock table (the `lockedNodes` prop). Returns the nodes that
+     * weren't locked before and are now — the store scans those for conflicts
+     * with a live local gesture.
+     */
+    setLocks: (locks: Record<NodeId, string> | undefined) => NodeId[];
+    /** Install the consumer's policy, or `null` to fall back to the defaults. */
+    setPolicy: (policy: CanInteractWithLocked | null) => void;
+    isLocked: (id: NodeId) => boolean;
+    /** Who holds this node's lock, or `null` when it isn't locked. */
+    getHolder: (id: NodeId) => string | null;
+    /** The whole table. The renderer walks it once a frame. */
+    getLocks: () => ReadonlyMap<NodeId, string>;
+    /** How many nodes are locked — the render loop's early-out. */
+    size: () => number;
+    /**
+     * Whether this client may act on a node. Always `true` for an unlocked node,
+     * so callers can ask unconditionally.
+     */
+    allows: (id: NodeId, intent: LockIntent) => boolean;
+    /** Bumped on every table change, for `useSyncExternalStore`. */
+    getVersion: () => number;
+    /** Subscribe to the table changing — locks move at human rate, so this is React-safe. */
+    subscribe: (listener: () => void) => () => void;
+};
+
+/**
+ * Presence — who else is in the document, and where they are.
+ *
+ * Presence is ephemeral by construction. Nothing here enters the graph, the
+ * change stream, or history: a peer's cursor is not a fact about the document,
+ * it's a fact about a person, and it stops being true the moment they move. So
+ * the registry is imperative, painted straight from the render loop, and thrown
+ * away when the tab closes.
+ *
+ * Two doors write to it, at deliberately different speeds:
+ *
+ *  - the `peers` prop — the roster. Identity (name, colour) and the slow
+ *    fields (selection, holding). React-rate.
+ *  - {@link PresenceRegistry.setPeerCursor} / `setPeerNodeTransform` — the hot
+ *    path off your ephemeral channel, called as fast as frames arrive. These
+ *    never touch React: they mark the canvas dirty and nothing else. A cursor
+ *    dirties only the cursor layer; a transform moves a real node, so it
+ *    dirties the frame.
+ *
+ * A peer the roster has never mentioned is still legitimate — a cursor frame
+ * can beat the join event, and dropping it would blink the cursor. Such a peer
+ * lives until its cursor clears (see {@link PresenceRegistry.setPeerCursor}),
+ * and its colour is derived from its id, so the record can be rebuilt any
+ * number of times without the colour ever flickering.
+ */
+
+/**
+ * A participant other than this client, as your transport describes them.
+ *
+ * Everything is optional but `id`: presence degrades field by field, and a peer
+ * you know nothing about except that they exist is still worth an avatar.
+ */
+type Peer = {
+    id: string;
+    /** Display name, drawn beside their cursor. Unnamed peers get no label. */
+    name?: string;
+    /** Any CSS colour. Defaults to a stable colour derived from {@link Peer.id}. */
+    color?: string;
+    /**
+     * Cursor in **world** coordinates — peers pan and zoom independently, so a
+     * screen point means nothing to anyone else. `null` when their pointer is
+     * off the canvas. Only a seed: once {@link PresenceRegistry.setPeerCursor}
+     * has been called for a peer, the imperative value owns the cursor.
+     */
+    cursor?: Vec2 | null;
+    /** Nodes they have selected. Outlined in their colour. */
+    selection?: NodeId[];
+    /** Nodes under one of their live gestures (their `onNodeDragStart`). */
+    holding?: NodeId[];
+};
+/**
+ * A peer as the registry holds it: identity resolved, live overlays merged in.
+ * What the renderer and {@link usePeers} both read.
+ */
+type PeerRecord = {
+    id: string;
+    name?: string;
+    /** Always set — {@link peerColor} fills in for a peer that declared none. */
+    color: string;
+    cursor: Vec2 | null;
+    selection: readonly NodeId[];
+    holding: readonly NodeId[];
+    /**
+     * Where this peer currently has each node they're dragging, in world space —
+     * the frame-rate overlay from `setPeerNodeTransform`. The node renders there
+     * until they let go; the graph keeps its own position until their commit
+     * arrives as a real change.
+     */
+    transforms: ReadonlyMap<NodeId, Rect>;
+};
+/** Presence policy, set via the `presenceOptions` prop. */
+type PresenceOptions = {
+    /**
+     * Smallest gap between outbound `onLocalPresence` snapshots, in ms. Cursor
+     * movement is coalesced to this rate; selection and gesture changes ignore it
+     * and go out at once (a lock signal that waits is a lock signal that races).
+     * Default `50`.
+     */
+    throttleMs?: number;
+    /**
+     * Give peer cursors their own canvas layer. Turn off to render your own from
+     * {@link usePeers} — avatars, follow buttons, anything the canvas can't do —
+     * and the layer is never created at all. Node outlines and peers' live boxes
+     * are unaffected: they live with the geometry they annotate. Default `true`.
+     */
+    renderCursors?: boolean;
+};
+type ResolvedPresenceOptions = Required<PresenceOptions>;
+declare const DEFAULT_PRESENCE_OPTIONS: ResolvedPresenceOptions;
+/**
+ * Default peer colours. Spaced around the wheel and mid-toned, so they read on
+ * a light or dark canvas and stay distinguishable side by side.
+ */
+declare const PEER_COLORS: readonly ["#6366f1", "#ec4899", "#f59e0b", "#10b981", "#3b82f6", "#8b5cf6", "#ef4444", "#14b8a6"];
+/**
+ * A stable colour for a peer id. Deterministic, so the same person is the same
+ * colour on every client and across a record being pruned and rebuilt — nobody
+ * coordinates a palette, and nobody's cursor changes colour mid-session.
+ */
+declare function peerColor(id: string): string;
+/**
+ * The presence registry — one per graph, reachable as `store.presence`.
+ *
+ * Reads are snapshot-based: {@link getPeers} returns a cached array rebuilt
+ * only when something actually changed, so the render loop can call it every
+ * frame and `useSyncExternalStore` can compare identities.
+ */
+type PresenceRegistry = {
+    /**
+     * Replace the roster (the `peers` prop). Peers that were in the previous
+     * roster and aren't in this one are dropped outright — leaving the roster is
+     * how a peer leaves. Peers this registry only knows imperatively are kept.
+     */
+    setPeers: (peers: Peer[]) => void;
+    /**
+     * Move a peer's cursor, in world coordinates. The hot path: call it as fast
+     * as your channel delivers frames — it dirties the cursor layer and nothing
+     * else, so the cost doesn't scale into the rest of the canvas.
+     *
+     * `null` parks the cursor. For a peer the roster never declared, that leaves
+     * nothing to draw, so the record is dropped — the next frame recreates it
+     * with the same colour.
+     */
+    setPeerCursor: (peerId: string, point: Vec2 | null) => void;
+    /**
+     * Where a peer currently has a node, in world space — their drag, mid-flight.
+     * The node itself moves there: it's painted, hit-tested and wired at the peer's
+     * live box, while the graph underneath is untouched until their commit lands.
+     * `null` releases it, which is what their drop should do just before their
+     * real change arrives.
+     */
+    setPeerNodeTransform: (peerId: string, nodeId: NodeId, rect: Rect | null) => void;
+    /**
+     * Every node a peer currently has under a gesture, at its *rendered* position
+     * — the interpolated one, not the last frame that arrived. What the store
+     * folds into world positions.
+     */
+    getNodeTransforms: () => ReadonlyMap<NodeId, Rect>;
+    /**
+     * Bumped whenever a rendered transform moves. Lets the store cache world
+     * positions across frames where peers are idle.
+     */
+    getTransformVersion: () => number;
+    /**
+     * Advance the interpolation toward the values that arrived, and report
+     * whether anything is still in motion (i.e. whether another frame is owed).
+     *
+     * Frames arrive at whatever rate a transport manages — 20Hz is normal, and
+     * stepping straight to each one makes a cursor stutter and a dragged node
+     * jump. Easing between them costs one lerp per peer and buys motion that
+     * reads as somebody moving rather than as packets landing.
+     */
+    step: (now: number) => boolean;
+    /** Forget a peer entirely — cursor, held nodes and all. Use it when they disconnect. */
+    removePeer: (peerId: string) => void;
+    /** Every known peer. A cached snapshot; identity only changes when the data does. */
+    getPeers: () => readonly PeerRecord[];
+    /** True when nobody else is here — the render loop's early-out. */
+    isEmpty: () => boolean;
+    /**
+     * Subscribe to **roster** changes: peers arriving or leaving, and their
+     * identity, selection or holding changing. Cursor and transform frames
+     * deliberately don't notify — they'd re-render React at pointer rate, and
+     * they're already painted on the canvas. Read them from {@link getPeers} on
+     * the frame channel if you need them in the DOM.
+     */
+    subscribe: (listener: () => void) => () => void;
+};
+
+/**
+ * The outbound half of presence: what this client tells everyone else.
+ *
+ * It publishes a *snapshot*, never an event stream. A snapshot is idempotent —
+ * a dropped one costs nothing, a duplicate costs nothing, and a client that
+ * reconnects mid-session is immediately correct rather than replaying history.
+ * That's also how presence channels themselves model state, so this maps onto
+ * any transport without a translation layer.
+ *
+ * Cursor movement is coalesced to `throttleMs`; selection and gesture changes
+ * jump the queue, because they're the signals a peer acts on (a lock request
+ * that waits 50ms is a lock request that can lose a race it should have won).
+ */
+
+/** This client's presence, as handed to `onLocalPresence`. */
+type LocalPresence = {
+    /**
+     * Pointer position in **world** coordinates, or `null` when the pointer is
+     * off the canvas. World, not screen: peers have their own viewports, and a
+     * screen point means nothing on the other side.
+     */
+    cursor: Vec2 | null;
+    /** Currently selected node ids. */
+    selection: NodeId[];
+    /** Nodes under a live local gesture — the same set as `onNodeDragStart`. */
+    holding: NodeId[];
+};
+
+/**
+ * Whether a node is locked, and by whom — for the chrome rivet can't draw for
+ * you: a padlock in the node's header, a "Ada is editing" line, a disabled
+ * form inside the node body.
+ *
+ * rivet already refuses the interactions it owns (see the `lockedNodes` prop),
+ * so this is for *your* controls. Re-renders only when this node changes hands,
+ * not when any lock in the document moves.
+ *
+ * ```tsx
+ * function MyNode({ id }: NodeProps) {
+ *   const { locked, holderId } = useNodeLock(id)
+ *   return <input disabled={locked} title={locked ? `${holderId} is editing` : ""} />
+ * }
+ * ```
+ */
+declare function useNodeLock(id: NodeId): NodeLock;
+/**
+ * Whether this client may do `intent` to a node right now — the same question
+ * every rivet input path asks, answered through the same policy.
+ *
+ * Use it to keep your own affordances honest: hide a delete button on a node a
+ * peer has locked, rather than letting it be pressed and refused. Always `true`
+ * for an unlocked node.
+ */
+declare function useNodeLockAllows(id: NodeId, intent: LockIntent): boolean;
+
+export { type CanInteractWithLocked as C, DEFAULT_PRESENCE_OPTIONS as D, LOCK_DEFAULT_REFUSED as L, type NodeLock as N, type PeerRecord as P, type ResolvedPresenceOptions as R, type LocalPresence as a, type LockIntent as b, type LockInteraction as c, type LockRegistry as d, PEER_COLORS as e, type Peer as f, type PresenceOptions as g, type PresenceRegistry as h, useNodeLockAllows as i, peerColor as p, useNodeLock as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolosal-ai/rivet",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Canvas-rendered node graph for React: DOM nodes, Canvas2D edges, swimlanes, anchors, undo/redo",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,10 @@
       "types": "./dist/anchor/index.d.ts",
       "import": "./dist/anchor/index.js"
     },
+    "./presence": {
+      "types": "./dist/presence/index.d.ts",
+      "import": "./dist/presence/index.js"
+    },
     "./svg": {
       "types": "./dist/svg/index.d.ts",
       "import": "./dist/svg/index.js"