@kolosal-ai/rivet 0.2.0 → 0.4.0

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

@@ -0,0 +1,716 @@
+import { N as NodeId, E as EdgeId, V as Vec2, b as HandleType, H as HandlePosition, R as Rect } from './types-D3aldmsO.js';
+import { ComponentType } from 'react';
+
+/**
+ * Presence targets — the things a peer can have a claim on.
+ *
+ * Presence started node-shaped: `Peer.selection` and `Peer.holding` were
+ * `NodeId[]`. The graph addresses more than nodes, though, and the rest of it
+ * is just as selectable — an edge is a row with its own id, and an anchor is an
+ * addressable element inside a node that can be clicked and wired. A target
+ * says *which kind of thing* an id refers to, so presence can describe any of
+ * them without three parallel fields.
+ *
+ * Strings stay the wire format, the same arrangement {@link EdgeEndpoint} uses
+ * for edge ends: a bare string is a node id, which is exactly what a 0.2.0
+ * transport already sends, so nothing has to be migrated to adopt the rest of
+ * this. The struct sits on top as a codec.
+ *
+ * | structured                          | key                        |
+ * |-------------------------------------|----------------------------|
+ * | `{ kind: "node", id }`              | `<nodeId>`                 |
+ * | `{ kind: "edge", id }`              | `edge:<edgeId>`            |
+ * | `{ kind: "anchor", nodeId, anchorId }` | `anchor:<nodeId>:<anchorId>` |
+ *
+ * `edge:` and `anchor:` are therefore reserved prefixes on a node id, and a
+ * node id inside an anchor key can't contain `:` (the anchor id may — the split
+ * takes the first separator). Anything that doesn't parse reads as a node id,
+ * which is the safe direction: an unknown node is skipped everywhere, where an
+ * unknown *kind* would need a decision at every call site.
+ */
+
+/** Something a peer can select, hold or lock. */
+type PresenceTarget = {
+    kind: "node";
+    id: NodeId;
+} | {
+    kind: "edge";
+    id: EdgeId;
+}
+/** An {@link Anchor} inside a node — addressed by both, since anchor ids are per-node. */
+ | {
+    kind: "anchor";
+    nodeId: NodeId;
+    anchorId: string;
+};
+/**
+ * A target in wire form — what travels, and what `PeerRecord.selection` and
+ * `PeerRecord.holding` hold. A plain node id is its own key.
+ */
+type PresenceTargetKey = string;
+/** The wire key for a target. A bare node id passes through unchanged. */
+declare function presenceTargetKey(target: PresenceTarget | NodeId): PresenceTargetKey;
+/**
+ * The key for an edge, without building the struct first. Sugar over
+ * {@link presenceTargetKey} for the call sites that ask a key-shaped question
+ * every frame — a lock check on the hovered edge, say — where the intermediate
+ * object is the only allocation in the path.
+ */
+declare function edgeTargetKey(id: EdgeId): PresenceTargetKey;
+/** The key for an anchor, without building the struct first. */
+declare function anchorTargetKey(nodeId: NodeId, anchorId: string): PresenceTargetKey;
+/**
+ * Whether a key addresses a node itself — in which case the key *is* the node
+ * id, and no parse is needed. The render loop's question, asked once per
+ * claimed target per peer per frame, so it allocates nothing.
+ */
+declare function isNodeTarget(key: PresenceTargetKey): boolean;
+/** Read a wire key back into a target. Anything malformed comes back as a node. */
+declare function parsePresenceTarget(key: PresenceTargetKey): PresenceTarget;
+/**
+ * The node a target belongs to: itself for a node, its owner for an anchor,
+ * `null` for an edge (which has two, and rivet holds neither as the edge's own).
+ * How a node-keyed question — geometry, a parent chain, a lock — is asked of a
+ * target that isn't a node.
+ */
+declare function presenceTargetNodeId(target: PresenceTarget | PresenceTargetKey): NodeId | null;
+/**
+ * The edge a target names, or `null` for anything else. The mirror of
+ * {@link presenceTargetNodeId}, and deliberately parse-free: an `edge:` key is
+ * recognisable by its prefix alone, so the frame loop that asks this of every
+ * claim allocates nothing on the answers it discards.
+ */
+declare function presenceTargetEdgeId(target: PresenceTarget | PresenceTargetKey): EdgeId | null;
+
+/**
+ * Locks — what a peer has claimed, and what this client may still do to it.
+ *
+ * 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 lock reaches down the parent chain: locking a container makes everything
+ * inside it read-only, because a claim on a box that leaves its contents free
+ * isn't a claim on anything. The table itself stays exactly as declared — the
+ * cascade is resolved per question, not stored — so paint and policy can differ,
+ * and they should: one outline on the container says what a stroke around every
+ * descendant would only repeat.
+ *
+ * The table is keyed by {@link PresenceTargetKey}, so an edge and an anchor are
+ * lockable on the same terms a node is. A bare node id is its own key, which is
+ * what every 0.2.0 table already contains — widening the key space cost nothing
+ * and migrates nothing. What each kind inherits differs, because containment
+ * does:
+ *
+ *  - a **node** inherits from its ancestors;
+ *  - an **anchor** inherits from the node that owns it, and so from that node's
+ *    ancestors — a locked container reaches its contents' anchors too;
+ *  - an **edge** inherits from nothing. Locking a node claims the node, not the
+ *    graph around it (the same reasoning that keeps `connect` out of
+ *    {@link LOCK_DEFAULT_REFUSED}), so an edge is governed by its own entry
+ *    alone even when both its endpoints are locked.
+ */
+
+/**
+ * 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"
+/**
+ * Drag one end of an existing edge onto a different handle. Asked of the
+ * *edge*, never of the nodes it runs between — reconnection is the one thing
+ * a lock on an edge is for, and asking its endpoints instead would make
+ * `connect`'s deliberate permissiveness meaningless.
+ */
+ | "reconnect";
+/** What {@link CanInteractWithLocked} is asked about. */
+type LockInteraction = {
+    /** The thing this client is trying to act on. */
+    target: PresenceTarget;
+    /**
+     * The target actually carrying the lock: {@link target} itself for a direct
+     * lock, an ancestor node when it's inherited from a container, the owning
+     * node when an anchor inherits from it. Compare the two to treat a locked
+     * container's contents differently from the container.
+     */
+    lockedTarget: PresenceTarget;
+    /** The peer holding the lock — the `lockedNodes` value for {@link lockedTarget}. */
+    holderId: string;
+    /**
+     * The node {@link target} belongs to: itself for a node, its owner for an
+     * anchor, and `null` for an edge — an edge runs between two nodes and rivet
+     * holds neither as its own. The node-shaped view of {@link target}, kept
+     * because every policy written before targets existed reads it.
+     */
+    nodeId: NodeId | null;
+    /** The node-shaped view of {@link lockedTarget}, `null` for an edge lock. */
+    lockedNodeId: NodeId | null;
+    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}.
+ *
+ * `reconnect` is present for the same reason `connect` isn't. It's asked of the
+ * edge being re-pointed, so refusing it withholds exactly the edge somebody has
+ * claimed and leaves every other wire on those nodes free.
+ */
+declare const LOCK_DEFAULT_REFUSED: ReadonlySet<LockIntent>;
+/**
+ * What the registry can be asked about — a target struct, or its wire key.
+ * A node's key *is* its id, so every call site written against the node-only
+ * registry still passes a valid target.
+ */
+type LockTarget = PresenceTarget | PresenceTargetKey;
+/**
+ * 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 targets that
+     * weren't locked before and are now — the store scans those for conflicts
+     * with a live local gesture.
+     */
+    setLocks: (locks: Record<PresenceTargetKey, string> | undefined) => PresenceTargetKey[];
+    /** Install the consumer's policy, or `null` to fall back to the defaults. */
+    setPolicy: (policy: CanInteractWithLocked | null) => void;
+    /** Whether a lock governs this target — its own, or one it inherits. */
+    isLocked: (target: LockTarget) => boolean;
+    /**
+     * Who holds the lock governing this target, or `null` when none does. Reports
+     * the inherited holder for a node inside a locked container, so consumer
+     * chrome inside the contents reads the same as chrome on the container.
+     */
+    getHolder: (target: LockTarget) => string | null;
+    /**
+     * The target whose lock governs `target` — itself when directly locked, the
+     * nearest locked ancestor (or owning node, for an anchor) when inherited,
+     * `null` when nothing governs it.
+     */
+    getLockSource: (target: LockTarget) => PresenceTargetKey | null;
+    /**
+     * The declared table, exactly as the prop gave it — containers only, never
+     * the contents they govern. The renderer walks it once a frame and outlines
+     * what it finds; expanding it to every descendant would stroke a box around
+     * each child of a locked container, which reads as many claims rather than
+     * one.
+     *
+     * Keyed by {@link PresenceTargetKey}, so a walk that only wants nodes has to
+     * say so — `isNodeTarget` is the cheap filter.
+     */
+    getLocks: () => ReadonlyMap<PresenceTargetKey, string>;
+    /**
+     * Just the edge locks, `edgeId -> holderId`, indexed when the table is set.
+     * The edge renderer wants them keyed by edge id and nothing else, once a
+     * frame; deriving that from {@link getLocks} each time would allocate a map
+     * per frame to answer a question that changes at human rate.
+     */
+    getLockedEdges: () => ReadonlyMap<EdgeId, string>;
+    /** How many targets are directly locked — the render loop's early-out. */
+    size: () => number;
+    /**
+     * Whether this client may act on a target. Always `true` for a target no lock
+     * governs, so callers can ask unconditionally.
+     */
+    allows: (target: LockTarget, 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, `data`) and the
+ *    slow fields (selection, holding). React-rate, and notified as two
+ *    channels: people change far less often than what they're pointing at.
+ *  - {@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 wire somebody is pulling out of a handle, right now — the peer-side view of
+ * a `PendingConnection`.
+ *
+ * Both ends are in **world** coordinates for the reason cursors are: peers pan
+ * and zoom independently. `from` travels rather than being recomputed from the
+ * handle, because the node it belongs to may be culled on this client, and a
+ * wire that vanishes when you scroll away from its source is worse than one
+ * drawn from a point.
+ *
+ * Deliberately not `PendingConnection` itself: that type carries `reconnecting`,
+ * the local drag's note that an edge is hidden while its preview stands in for
+ * it. A peer's uncommitted gesture must not hide an edge from this client — the
+ * edge is still in the document until their change lands — so the field stops
+ * at the publishing boundary.
+ */
+type PeerConnection = {
+    source: NodeId;
+    sourceHandle: string;
+    sourceType: HandleType;
+    /** The anchored end, at the handle it was pulled from. */
+    from: Vec2;
+    /** The loose end, following their pointer. Interpolated, like a cursor. */
+    to: Vec2;
+    /** Side the loose end enters from while they're snapped onto a handle. */
+    toPosition?: HandlePosition;
+};
+/**
+ * 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;
+    /**
+     * Anything else your app knows about them — an avatar URL, a role, what
+     * they're doing. rivet never reads it; it rides along to {@link PeerRecord}
+     * so participant chrome doesn't need a side map keyed by peer id.
+     */
+    data?: unknown;
+    /**
+     * What they have selected. Bare strings are node ids — the 0.2.0 shape, still
+     * exactly right — and a {@link PresenceTarget} names an edge or an anchor.
+     */
+    selection?: readonly (NodeId | PresenceTarget)[];
+    /**
+     * What's under one of their live gestures (their `onNodeDragStart`). Nodes in
+     * practice: an edge or an anchor is selected, never dragged.
+     */
+    holding?: readonly (NodeId | PresenceTarget)[];
+    /**
+     * A wire they're pulling out of a handle, or `null` when they aren't. Like
+     * {@link Peer.cursor} this is only a seed: once
+     * {@link PresenceRegistry.setPeerConnection} has been called for a peer, the
+     * imperative value owns it.
+     */
+    pending?: PeerConnection | null;
+};
+/**
+ * Who a peer is, with nothing about what they're doing.
+ *
+ * Its own type because it's its own subscription: identity changes when someone
+ * joins, leaves, is renamed or recoloured — human-rate events — while claims
+ * change every time anybody clicks anything. Chrome that only shows *who is
+ * here* subscribes to this and sits out the rest (see `usePeerIdentities`).
+ */
+type PeerIdentity = {
+    id: string;
+    name?: string;
+    /** Always set — {@link peerColor} fills in for a peer that declared none. */
+    color: string;
+    /** Whatever the roster attached to them, untouched. */
+    data?: unknown;
+};
+/**
+ * A peer as the registry holds it: identity resolved, live overlays merged in.
+ * What the renderer and {@link usePeers} both read.
+ */
+type PeerRecord = PeerIdentity & {
+    cursor: Vec2 | null;
+    /**
+     * Their claims, in wire form: a bare node id, or an `edge:`/`anchor:` key.
+     * {@link isNodeTarget} is the cheap question, `parsePresenceTarget` the full
+     * one.
+     */
+    selection: readonly PresenceTargetKey[];
+    holding: readonly PresenceTargetKey[];
+    /**
+     * 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>;
+    /**
+     * The wire they're pulling right now, `null` when they aren't. The loose end
+     * is the interpolated one — what {@link step} has eased to, as with cursors.
+     */
+    pending: PeerConnection | null;
+};
+/**
+ * What a {@link PresenceOptions.cursorComponent} is handed: who the cursor
+ * belongs to, and nothing about where it is.
+ *
+ * Position is deliberately absent. A cursor moves at pointer rate for every
+ * peer in the room, and passing it as a prop would re-render the component that
+ * often — the cost the cursor layer exists to avoid. rivet writes the position
+ * onto the wrapper element around your component instead, as a `transform`, so
+ * your component re-renders only when the *person* changes.
+ *
+ * {@link PeerIdentity} rather than {@link PeerRecord} for the same reason: a
+ * record's `cursor`, `selection` and `transforms` all move faster than this
+ * component is re-rendered, so they would be stale in your hands. Anything else
+ * you want to show — an avatar, a role, what they're doing — rides on
+ * {@link PeerIdentity.data}.
+ */
+type PeerCursorProps = {
+    peer: PeerIdentity;
+};
+/** One peer's claim on a target, as {@link PeerOutlineProps} reports it. */
+type PeerClaim = {
+    peer: PeerIdentity;
+    /**
+     * `"held"` when the target is under one of their live gestures, `"selected"`
+     * when they merely have it selected. A peer who is doing both appears once,
+     * as `"held"` — the more current fact, and the one the canvas paint picks too.
+     */
+    kind: "selected" | "held";
+};
+/**
+ * What a {@link PresenceOptions.outlineComponent} is handed: one claimed
+ * target, everybody who has claimed it, and whether it's locked.
+ *
+ * One wrapper per **target**, not per peer-per-target. A node can be in three
+ * peers' selections while a fourth holds it and a lock sits on top; the canvas
+ * paint resolves that itself, because two strokes on one box read as a heavier
+ * border rather than as two facts. A component can do better than a stroke —
+ * stack avatars, badge a count, truncate at three — so it gets the whole list
+ * instead of rivet's answer to a question it didn't ask.
+ *
+ * Like {@link PeerCursorProps}, peers arrive as {@link PeerIdentity}: this
+ * re-renders when the *claims* change, so a record's `cursor` and `transforms`
+ * would be stale in your hands. Geometry isn't a prop for the same reason —
+ * rivet sizes and positions the wrapper element imperatively every frame.
+ */
+type PeerOutlineProps = {
+    target: PresenceTarget;
+    claims: readonly PeerClaim[];
+    /**
+     * The lock on this target, or `null` when it isn't locked. `peer` is absent
+     * when the holder isn't in the roster — a lock outlives the tab that took it,
+     * which is the point of taking one.
+     */
+    lock: {
+        holderId: string;
+        peer?: PeerIdentity;
+    } | null;
+};
+/** 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;
+    /**
+     * Draw peer cursors. Turn off to render them entirely yourself off
+     * `subscribeCursorFrame`; neither layer below is created. Node outlines and
+     * peers' live boxes are unaffected — they live with the geometry they
+     * annotate. Default `true`.
+     */
+    renderCursors?: boolean;
+    /**
+     * Render each peer's cursor as your own React component instead of the
+     * built-in canvas arrow: an avatar, a follow button, a status chip — anything
+     * a canvas glyph can't be.
+     *
+     * One wrapper per peer, mounted when they join and unmounted when they leave.
+     * rivet positions the wrapper imperatively every cursor frame, so nothing
+     * re-renders at pointer rate; see {@link PeerCursorProps}.
+     *
+     * Supplying this means the cursor *canvas* is never created. Setting
+     * `renderCursors: false` beats it: the boolean is "no cursors from rivet at
+     * all", which is a different statement from "cursors, drawn my way".
+     */
+    cursorComponent?: ComponentType<PeerCursorProps>;
+    /**
+     * Outline what peers have claimed — their selections, whatever they're
+     * holding, and locked targets — in the claimant's colour. Turn off to show
+     * claims entirely yourself, or not at all: no outlines are stroked around
+     * nodes and anchors, and no halo is drawn under a claimed edge. Cursors are
+     * unaffected. Default `true`.
+     */
+    renderOutlines?: boolean;
+    /**
+     * Render each claimed target as your own React component instead of the
+     * built-in outline: an avatar stack, a "3 others" badge, a name chip — again,
+     * anything a stroked box can't be.
+     *
+     * One wrapper per claimed target, mounted when the first claim on it arrives
+     * and unmounted with the last. rivet positions and sizes the wrapper
+     * imperatively every frame, so nothing re-renders as peers drag things
+     * around; see {@link PeerOutlineProps}.
+     *
+     * Supplying this replaces the outlines rivet strokes around **nodes and
+     * anchors**. The halo under a claimed *edge* stays, because a DOM overlay
+     * cannot follow an edge's path — your component still gets `edge` targets,
+     * positioned at the midpoint of the drawn path, for chrome that sits on one.
+     * `renderOutlines: false` is the switch that turns off all of it.
+     */
+    outlineComponent?: ComponentType<PeerOutlineProps>;
+};
+/**
+ * Presence options with every default filled in. The two components stay
+ * optional — there is no default component, and "no component" is the state
+ * that selects the canvas.
+ */
+type ResolvedPresenceOptions = Required<Omit<PresenceOptions, "cursorComponent" | "outlineComponent">> & Pick<PresenceOptions, "cursorComponent" | "outlineComponent">;
+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;
+    /**
+     * The wire a peer is pulling out of a handle, or `null` when they let go.
+     *
+     * Hot path like the cursor, but it takes a **full** frame rather than the
+     * cursor layer's narrow one: the wire is painted on the shared foreground,
+     * which is also where the local pending connection, the alignment guides and
+     * the peer outlines live. Unlike a pointer, which is always moving, this only
+     * arrives while somebody is actually dragging a connection.
+     */
+    setPeerConnection: (peerId: string, connection: PeerConnection | 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[];
+    /**
+     * Every known peer, identity only — no cursor, no claims. Its own cached
+     * snapshot, so it keeps its identity across every frame and every click that
+     * leaves the roster's *people* unchanged.
+     */
+    getPeerIdentities: () => readonly PeerIdentity[];
+    /** 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 half of {@link subscribe} that's about *people*: joins, leaves, names,
+     * colours and `data`. Silent when a peer only changes what they have
+     * selected or held.
+     *
+     * The two halves move at completely different rates. At 15–100 participants,
+     * somebody is always clicking something, so a roster subscription that counts
+     * claims re-renders continuously — while the set of people in the room barely
+     * moves. An avatar stack wants this one.
+     */
+    subscribeIdentity: (listener: () => void) => () => void;
+    /**
+     * The other half: what peers have selected or are holding. Also fires when a
+     * peer joins or leaves carrying claims, since that changes who claims what.
+     */
+    subscribeClaims: (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;
+    /**
+     * What this client has selected, as {@link PresenceTargetKey}s: node ids bare,
+     * the selected edge as `edge:<id>`, selected anchors as `anchor:<node>:<id>`.
+     * Feed it straight back to a peer's `selection` on the other side.
+     *
+     * Only nodes existed here in 0.2.0 and node ids are still bare strings, so a
+     * transport that treats these as node ids keeps working — it just carries a
+     * couple of keys it doesn't recognise once someone clicks an edge.
+     */
+    selection: PresenceTargetKey[];
+    /** Nodes under a live local gesture — the same set as `onNodeDragStart`. */
+    holding: NodeId[];
+    /**
+     * The wire this client is pulling out of a handle, or `null`. Both ends in
+     * world coordinates; feed it straight back to a peer's `pending`.
+     *
+     * The local drag's `reconnecting` id is deliberately not here. It means "the
+     * edge this preview stands in for is hidden", which is true for the client
+     * doing the dragging and must not be true for anybody else — the edge is
+     * still in the document until their change lands.
+     */
+    pending: PeerConnection | null;
+};
+
+/**
+ * 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.
+ *
+ * Answers for the lock that *governs* the node: a node inside a locked container
+ * reports the container's holder, so a disabled input inside the contents reads
+ * the same as one on the container itself.
+ *
+ * ```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 PeerIdentity as P, type ResolvedPresenceOptions as R, type PeerRecord as a, type PresenceTargetKey as b, type PresenceTarget as c, type PeerClaim as d, type LocalPresence as e, type LockIntent as f, type LockInteraction as g, type LockRegistry as h, type LockTarget as i, PEER_COLORS as j, type Peer as k, type PeerConnection as l, type PeerCursorProps as m, type PeerOutlineProps as n, type PresenceOptions as o, type PresenceRegistry as p, anchorTargetKey as q, edgeTargetKey as r, isNodeTarget as s, parsePresenceTarget as t, peerColor as u, presenceTargetEdgeId as v, presenceTargetKey as w, presenceTargetNodeId as x, useNodeLock as y, useNodeLockAllows as z };