@kolosal-ai/rivet 0.3.0 → 0.4.0

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

@@ -1,327 +0,0 @@
-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 };