@synapse-sdk/client 0.1.0

package/dist/node-DbD7G0Nx.d.ts

@@ -0,0 +1,466 @@
+//#region src/types.d.ts
+/** The minimal slice of the WHATWG WebSocket we depend on — so any conforming
+ *  implementation (browser, Bun/Node global, a test double) can be injected. */
+interface WebSocketLike {
+  readonly readyState: number;
+  send(data: string | ArrayBufferLike): void;
+  close(code?: number, reason?: string): void;
+  onopen: ((ev: unknown) => void) | null;
+  onmessage: ((ev: {
+    data: unknown;
+  }) => void) | null;
+  onclose: ((ev: {
+    code?: number;
+    reason?: string;
+  }) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+}
+type WebSocketCtor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+/** Observable connection status. `connected` means open AND verified (handshake acked). */
+type ConnectionStatus = "idle" | "connecting" | "connected" | "reconnecting" | "closing" | "error";
+interface ConnectionState {
+  readonly status: ConnectionStatus;
+  readonly endpoint: string | null;
+  readonly error: Error | null;
+  readonly since: number;
+}
+type Params = Record<string, unknown>;
+type ParamsInput = Params | (() => Params | Promise<Params>);
+type TokenInput = () => string | Promise<string>;
+/** Runs after the socket opens; must resolve for status to become `connected`. */
+type VerifyFn = (handle: VerifyHandle) => Promise<void>;
+interface VerifyHandle {
+  channel(topic: string, params?: Params): Channel;
+}
+/** What to connect to. Identity = `url` + plain `params`; `token`/`verify` are *how* to
+ *  connect, never part of identity. */
+interface Target {
+  url: string;
+  params?: ParamsInput;
+  token?: TokenInput;
+  verify?: VerifyFn;
+}
+interface Reply {
+  status: "ok" | "error" | "timeout";
+  response: unknown;
+}
+type Logger = (level: "debug" | "info" | "warn" | "error", msg: string, data?: unknown) => void;
+interface ConnectionOptions {
+  /** Defaults to `globalThis.WebSocket` (browser / Bun / Node 22+ / Deno / edge). */
+  WebSocket?: WebSocketCtor;
+  serializer?: Serializer;
+  /** Heartbeat cadence; a missed reply within one interval declares the socket dead.
+   *  HMIs want this low (e.g. 2000). Default 15000. */
+  heartbeatIntervalMs?: number;
+  requestTimeoutMs?: number;
+  /** Max wait for a healthy socket's `close` during teardown before force-fence. Default 2000. */
+  closeTimeoutMs?: number;
+  reconnectAfterMs?: (tries: number) => number;
+  vsn?: string;
+  logger?: Logger;
+}
+/** One decoded Phoenix v2 frame: `[join_ref, ref, topic, event, payload]`. */
+interface Message {
+  join_ref: string | null;
+  ref: string | null;
+  topic: string;
+  event: string;
+  payload: unknown;
+}
+interface Serializer {
+  encode(msg: Message): string | ArrayBufferLike;
+  decode(raw: string | ArrayBufferLike): Message;
+}
+/** The surface a Channel needs from its Connection (so Channel depends on a contract,
+ *  not the concrete class). */
+interface ChannelHost {
+  _makeRef(): string;
+  _send(msg: Message): void;
+  _request(msg: Message, timeoutMs?: number): Promise<Reply>;
+  _isOpen(): boolean;
+  _removeChannel(topic: string): void;
+  _log: Logger;
+}
+interface SynapseOptions extends ConnectionOptions {
+  /** Stable node identity (defaults to a random uuid). */
+  userId?: string;
+  /** Human-friendly display name. */
+  name?: string;
+  /** Role the bus authorizes against: "agent" (default) or "viewer". */
+  role?: string;
+  /** Join `synapse:system` on connect and gate readiness on a server-assigned role.
+   *  Default `true`. Set `false` for headless nodes that don't need a session/role —
+   *  then `ready` simply means transport-connected. */
+  system?: boolean;
+}
+/** What to connect to. Identity params (user_id/type/name) are merged in automatically. */
+interface ConnectTarget {
+  url: string;
+  params?: Target["params"];
+  token?: Target["token"];
+  verify?: Target["verify"];
+  /** Project to activate on the system channel (request controller of it). */
+  project?: string;
+  /** Request the controller role (vs viewer). Needs a `project`; `type: "hmi"` also auto-controllers. */
+  controller?: boolean;
+}
+/**
+ * Server-assigned session role from the `synapse:system` handshake. **Open-ended** — the
+ * server may assign roles beyond these (the Python node already has `agent`), so the type is
+ * any string; the constants are just for ergonomic, typo-safe comparison
+ * (`role === SystemRole.Controller`). Add entries here as the server grows.
+ */
+declare const SystemRole: {
+  readonly Viewer: "viewer";
+  readonly Controller: "controller";
+  readonly Agent: "agent";
+};
+type SystemRole = (typeof SystemRole)[keyof typeof SystemRole] | (string & {});
+/**
+ * The node's readiness, three layers deep:
+ *  - `status`  — transport: reaching the socket (`connecting`) → reached it (`connected`).
+ *  - `role`    — system: who the server says you are once negotiated (null until then).
+ *  - `ready`   — negotiated and usable: `connected` AND (role assigned, or system disabled).
+ */
+interface SystemState {
+  readonly status: ConnectionStatus;
+  readonly role: SystemRole | null;
+  readonly projectId: string | null;
+  readonly ready: boolean;
+  readonly error: Error | null;
+}
+/** A `state_diff` from a state mirror — absolute + version-ordered (keys changed/removed). */
+interface StateDiff {
+  changed?: Record<string, unknown>;
+  removed?: string[];
+  version?: number;
+}
+/** A service's capability card (from the catalog). Open-ended; always has a `name`. */
+interface ServiceCard {
+  name: string;
+  description?: string;
+  [key: string]: unknown;
+}
+/** A state resource entry in the catalog. */
+interface ResourceInfo {
+  name: string;
+  kind: string;
+}
+/** A live catalog change as providers / state resources are added or removed. */
+interface CatalogChange {
+  change: "added" | "removed";
+  name: string;
+  kind: "service" | "resource";
+}
+type Frame = Record<string, unknown>;
+interface CallOptions {
+  onUpdate?: (frame: Frame) => void;
+  /** Cancel the call the web-standard way; the server is told to stop the provider. */
+  signal?: AbortSignal;
+  /** Bounds the initial accept (ack). */
+  timeout?: number;
+  /** Idle deadline (ms): fail the call if no `update`/`result`/`error` arrives within this
+   *  window after the ack — reset on each `update`. Catches a wedged provider that an overall
+   *  `AbortSignal.timeout` can't tell apart from legitimately slow work. Off by default. */
+  idleTimeout?: number;
+}
+interface SubscribeOptions {
+  /** Channel join params — e.g. ROS topics need `{ type: "std_msgs/String" }`. */
+  opts?: Record<string, unknown>;
+}
+interface StreamEvent {
+  type: "update" | "result";
+  data: Frame;
+}
+interface Subscription {
+  unsubscribe(): void;
+}
+interface CallContext {
+  update(data: Frame): void;
+  /** Aborted when the caller cancels — poll it for cooperative cancellation. */
+  readonly signal: AbortSignal;
+  /** The id of the call being served — handy for logging/correlation. */
+  readonly taskId: string;
+}
+type ServiceHandler = (input: Frame, ctx: CallContext) => unknown | Promise<unknown>;
+interface ServiceRegistration {
+  unregister(): void;
+}
+//#endregion
+//#region src/channel.d.ts
+type ChannelState = "closed" | "joining" | "joined" | "leaving" | "errored";
+type ChannelHandler = (payload: unknown, ref: string | null) => void;
+/**
+ * One topic on the connection. Owned and reference-counted by `Connection` (one Channel
+ * per topic). Membership is independent of any UI component lifecycle: listeners attach
+ * and detach freely via `on`/`off` without re-joining, and the channel auto-rejoins when
+ * the socket reconnects.
+ */
+declare class Channel {
+  readonly topic: string;
+  state: ChannelState;
+  private host;
+  private params;
+  private joinRef;
+  private joinPromise;
+  private joinResponse;
+  private bindings;
+  constructor(host: ChannelHost, topic: string, params: Params);
+  /** Idempotent: a join in flight or already joined returns the existing result. */
+  join(timeoutMs?: number): Promise<unknown>;
+  private doJoin;
+  leave(timeoutMs?: number): Promise<void>;
+  /** Fire-and-forget; for handlers that reply with `{:noreply, ...}` (e.g. pub/sub publish). */
+  push(event: string, payload?: unknown): void;
+  /** Send and await the reply; for handlers that reply with `{:reply, ...}`. */
+  request(event: string, payload?: unknown, timeoutMs?: number): Promise<Reply>;
+  on(event: string, cb: ChannelHandler): ChannelHandler;
+  off(event: string, cb: ChannelHandler): void;
+  _trigger(event: string, payload: unknown, ref: string | null): void;
+  /** Called when a (new) socket is open. Re-establishes membership if needed. */
+  _rejoin(): void;
+  /** Called when the socket goes down: the join is no longer valid; we'll rejoin on reconnect. */
+  _onSocketDown(): void;
+}
+//#endregion
+//#region src/connection.d.ts
+/**
+ * Single-socket connection supervisor.
+ *
+ * Invariant (the whole point): **at most one socket is ever acted upon.** A new socket is
+ * never created until the previous one's `close` is confirmed (healthy switch) or it has
+ * been fenced and abandoned (dead socket). Three mechanics enforce it:
+ *
+ *  1. **Serialized reconcile** — every transition runs through one queue; the latest
+ *     desired target always wins (rapid `connect`/`disconnect` coalesce).
+ *  2. **Generation + live-identity guards** — every socket event checks it belongs to the
+ *     current desired-epoch *and* the current socket; late events from a superseded or
+ *     replaced socket are inert.
+ *  3. **Verified teardown** — switching/closing awaits the real `close` event (with a
+ *     force-fence timeout) before any new socket opens.
+ *
+ * No global/`window` coupling, so discarding a socket is clean — nothing to leak or
+ * resurrect on tab visibility.
+ */
+declare class Connection implements ChannelHost {
+  private readonly WS;
+  private readonly serializer;
+  private readonly heartbeatIntervalMs;
+  private readonly requestTimeoutMs;
+  private readonly closeTimeoutMs;
+  private readonly reconnectAfterMs;
+  private readonly vsn;
+  readonly _log: Logger;
+  private desired;
+  private live;
+  private generation;
+  private state;
+  private listeners;
+  private channels;
+  private pending;
+  private refCounter;
+  private reconciling;
+  private dirty;
+  private reconnectAttempt;
+  private reconnectTimer;
+  private closed;
+  constructor(options?: ConnectionOptions);
+  getState(): ConnectionState;
+  /** Observe connection state. Returns an unsubscribe fn. `getState`/state are stable
+   *  references between changes, so this is `useSyncExternalStore`-friendly. */
+  subscribe(listener: (s: ConnectionState) => void): () => void;
+  /** Declarative + idempotent. Sets the desired target and converges to it. Resolves when
+   *  this target reaches `connected`; rejects if a different target supersedes it. */
+  connect(target: Target): Promise<void>;
+  /** Tear down to `idle`. Resolves once fully closed. */
+  disconnect(): Promise<void>;
+  /** Permanent dispose — closes the socket and stops everything. */
+  close(): void;
+  /** Get-or-create the (single) channel for a topic. Joined now if the socket is open,
+   *  otherwise it joins automatically once a socket comes up. */
+  channel(topic: string, params?: Params): Channel;
+  _makeRef(): string;
+  _isOpen(): boolean;
+  _send(msg: Message): void;
+  _request(msg: Message, timeoutMs?: number): Promise<Reply>;
+  _removeChannel(topic: string): void;
+  private reconcile;
+  private runReconcile;
+  private step;
+  private bringUp;
+  private onOpen;
+  private verifyHandle;
+  private setConnected;
+  private teardown;
+  private replaceDead;
+  private onUnexpectedClose;
+  /** Detach handlers and best-effort close, without awaiting (the socket may never close). */
+  private fence;
+  private afterSocketGone;
+  private scheduleReconnect;
+  private cancelReconnect;
+  private startHeartbeat;
+  private sendHeartbeat;
+  private clearHeartbeat;
+  private onMessage;
+  private sendRaw;
+  private flushPending;
+  private setState;
+  private failTarget;
+  private desiredKey;
+  private waitForTarget;
+  private bumpGeneration;
+}
+//#endregion
+//#region src/node.d.ts
+type MessageHandler = (m: Frame) => void;
+/**
+ * A Synapse bus node. Wraps the single-socket {@link Connection} and adds the bus verbs —
+ * `call`, `callStream`, `subscribe`, `publish`, `service` — mirroring the Python `Node`.
+ * Any node can both consume and provide (a browser can publish joystick state *and* expose
+ * a service the robot calls into).
+ */
+declare class Synapse {
+  readonly connection: Connection;
+  private identity;
+  private tasks;
+  private consumerChannels;
+  private pubsubChannels;
+  private pubsubSubs;
+  private stateHandles;
+  private catalogChannelP;
+  private catalogWatchers;
+  private readonly systemEnabled;
+  private systemChannel;
+  private role;
+  private projectId;
+  private systemError;
+  private systemRequest;
+  private systemState;
+  private systemListeners;
+  private systemGen;
+  constructor(options?: SynapseOptions);
+  /**
+   * Connect (and negotiate the system session). Identity params are merged in. Resolves when
+   * **ready** — transport connected *and* a server role assigned (unless `system: false`,
+   * where ready just means connected). Declarative + idempotent. To request control, pass
+   * `{ project, controller: true }`.
+   */
+  connect(target: ConnectTarget): Promise<void>;
+  disconnect(): Promise<void>;
+  close(): void;
+  getState(): ConnectionState;
+  /** Observe connection state — `useSyncExternalStore`-friendly. */
+  subscribeState(listener: (s: ConnectionState) => void): () => void;
+  /** The full readiness — `{ status, role, projectId, ready, error }`. */
+  getSystem(): SystemState;
+  /** Observe readiness — `useSyncExternalStore`-friendly. The connection indicator binds
+   *  to `{ status, role }` (transport status + server role) and `ready` is the gate. */
+  subscribeSystem(listener: (s: SystemState) => void): () => void;
+  /** Resolves once **ready** (negotiated + role assigned), or rejects after `timeoutMs`. */
+  whenReady(timeoutMs?: number): Promise<void>;
+  /** Activate a project (request control of it). Role updates arrive live via the session. */
+  activateProject(projectId: string): Promise<void>;
+  /** Step back to viewer for the active project. */
+  deactivateProject(): Promise<void>;
+  /** Resolves once the transport is connected — used internally before channel ops (channels
+   *  need the socket, not a role). */
+  private awaitConnected;
+  private onTransport;
+  private enterSystem;
+  private onSessionState;
+  private setRole;
+  private requireSystem;
+  private systemPayload;
+  private computeSystem;
+  private emitSystem;
+  call<T = unknown>(service: string, input?: Frame, opts?: CallOptions): Promise<T>;
+  /** Call as a loop: yields each `update` then the terminal `result`. Breaking cancels. */
+  callStream(service: string, input?: Frame, opts?: {
+    timeout?: number;
+    idleTimeout?: number;
+  }): AsyncGenerator<StreamEvent>;
+  publish(resource: string, data?: Frame, opts?: SubscribeOptions): Promise<void>;
+  subscribe(resource: string, callback: MessageHandler, opts?: SubscribeOptions): Subscription;
+  subscribe(resource: string, opts?: SubscribeOptions): AsyncIterable<Frame>;
+  /** A render-loop-friendly latest-value holder for high-rate topics (three.js / `useFrame`). */
+  latest<T extends Frame = Frame>(resource: string, opts?: SubscribeOptions): LatestValue<T>;
+  /**
+   * Open a live, always-current local mirror of a `synapse:state:<name>` resource — a
+   * shared key→value map that converges across nodes. `handle.value` is kept up to date
+   * from the initial sync and each diff; write with `handle.put`/`handle.delete`. Cached
+   * per resource (repeated calls share one mirror).
+   */
+  openState(resource: string): Promise<StateHandle>;
+  private doOpenState;
+  /** Capability cards of every registered service. */
+  listServices(): Promise<ServiceCard[]>;
+  /** One service's capability card (throws `BusError` if unknown). */
+  describe(service: string): Promise<ServiceCard>;
+  /** State resources currently registered on the bus. */
+  listResources(): Promise<ResourceInfo[]>;
+  /** Watch providers / resources coming and going. With a callback → push (returns a
+   *  Subscription); without → an async iterator of `{ change, name, kind }`. */
+  watchCatalog(callback: (c: CatalogChange) => void): Subscription;
+  watchCatalog(): AsyncIterable<CatalogChange>;
+  private watchCatalogIterator;
+  private catalog;
+  private openCatalog;
+  service(name: string, handler: ServiceHandler, card?: Frame): ServiceRegistration;
+  private runProvider;
+  private withIdentity;
+  private consumerChannel;
+  private routeTask;
+  private subsFor;
+  private ensurePubsub;
+  private subscribePush;
+  private subscribePull;
+}
+/**
+ * Latest-value holder for high-frequency topics. Read `.get()` inside a three.js / r3f
+ * `useFrame` loop (non-reactive) and mutate the scene directly — React never re-renders.
+ */
+declare class LatestValue<T> {
+  private value;
+  private listeners;
+  private sub;
+  constructor(subscribe: (cb: (m: T) => void) => Subscription);
+  get(): T | undefined;
+  onChange(cb: (v: T) => void): () => void;
+  close(): void;
+}
+/**
+ * A live local mirror of a `synapse:state:<name>` resource. `value` is kept current from the
+ * initial `state_sync` and each `state_diff` (absolute, version-ordered); a version gap
+ * triggers an automatic `resync`. Writes (`put`/`delete`) are server-confirmed and come back
+ * as a diff (self-included). `value` is replaced (new reference) on each change, so it binds
+ * cleanly to `useSyncExternalStore` / reads cleanly in a `useFrame` loop.
+ */
+declare class StateHandle {
+  readonly resource: string;
+  private ch;
+  private _value;
+  private _version;
+  private listeners;
+  private resyncing;
+  constructor(resource: string, ch: Channel);
+  /** The current converged map (new reference on every change). */
+  get value(): Record<string, unknown>;
+  /** The version of the last applied op. */
+  get version(): number;
+  put(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<void>;
+  /** Observe each applied change: `(value, diff) => …`. Returns unsubscribe. */
+  subscribe(listener: (value: Record<string, unknown>, diff: StateDiff) => void): () => void;
+  /** Force a full re-sync from the server. */
+  resync(): Promise<void>;
+  close(): void;
+  _applySync(sync: {
+    version?: number;
+    state?: Record<string, unknown>;
+  }): void;
+  _onDiff(diff: StateDiff): void;
+  private emit;
+}
+//#endregion
+export { SynapseOptions as A, ServiceCard as C, StreamEvent as D, StateDiff as E, VerifyFn as F, VerifyHandle as I, WebSocketCtor as L, SystemState as M, Target as N, SubscribeOptions as O, TokenInput as P, WebSocketLike as R, Serializer as S, ServiceRegistration as T, Message as _, Channel as a, Reply as b, CallOptions as c, ConnectTarget as d, ConnectionOptions as f, Logger as g, Frame as h, Connection as i, SystemRole as j, Subscription as k, CatalogChange as l, ConnectionStatus as m, StateHandle as n, ChannelHandler as o, ConnectionState as p, Synapse as r, CallContext as s, LatestValue as t, ChannelHost as u, Params as v, ServiceHandler as w, ResourceInfo as x, ParamsInput as y };

package/dist/react.d.ts

@@ -0,0 +1,63 @@
+import { C as ServiceCard, M as SystemState, O as SubscribeOptions, c as CallOptions, h as Frame, j as SystemRole, m as ConnectionStatus, n as StateHandle, p as ConnectionState, r as Synapse, w as ServiceHandler, x as ResourceInfo } from "./node-DbD7G0Nx.js";
+import { ReactNode } from "react";
+
+//#region src/react.d.ts
+/** Pass as the resource to `useSubscribe` to disable it conditionally (à la Convex). */
+declare const skip: "skip";
+declare function SynapseProvider({
+  client,
+  children
+}: {
+  client: Synapse;
+  children: ReactNode;
+}): ReactNode;
+/** The `Synapse` client from the nearest provider. */
+declare function useSynapse(): Synapse;
+/** The full connection state; re-renders on any status/endpoint/error change. */
+declare function useConnectionState(): ConnectionState;
+/** Just the status — `idle | connecting | connected | reconnecting | closing | error`. */
+declare function useConnectionStatus(): ConnectionStatus;
+/** Full readiness — `{ status, role, projectId, ready, error }`. Bind your connection
+ *  indicator to `{ status, role }`. */
+declare function useSystem(): SystemState;
+/** The gate: transport-connected AND a server role assigned (or `system: false`). */
+declare function useReady(): boolean;
+/** The server-assigned session role (`viewer` / `controller` / …), or null until negotiated. */
+declare function useRole(): SystemRole | null;
+/**
+ * Live value of a pub/sub resource — the latest message (latest-wins, no queue growth), or
+ * `undefined` until the first arrives. Pass `skip` to disable. For 60 Hz data feeding
+ * three.js, prefer the imperative `synapse.latest(resource).get()` inside `useFrame` instead
+ * (this hook re-renders on every message).
+ */
+declare function useSubscribe<T extends Frame = Frame>(resource: string, opts?: SubscribeOptions): T | undefined;
+/** A stable bound `call` — like TanStack/Convex `useMutation` returning a callable. */
+declare function useCall(): <R = unknown>(service: string, input?: Frame, opts?: CallOptions) => Promise<R>;
+/**
+ * Register this node as a provider for the lifetime of the component (e.g. a browser
+ * exposing a joystick service the robot calls into). The handler is read from a ref, so it
+ * can close over fresh props without re-registering.
+ */
+declare function useService(name: string, handler: ServiceHandler, card?: Frame): void;
+/**
+ * Live mirror of a `synapse:state:<name>` resource. Returns `[value, handle]`: `value` is the
+ * converged map (re-renders on change), `handle` exposes `put`/`delete` (null until opened).
+ *
+ * @example
+ * const [scene, handle] = useStateMirror("world/collision")
+ * // render scene.box_1 …; handle?.put("box_2", { xyz: [1, 0, 0] })
+ */
+declare function useStateMirror(resource: string): readonly [Record<string, unknown>, StateHandle | null];
+/**
+ * Live discovery — the bus's services and state resources, refreshed when any provider or
+ * resource is added/removed.
+ *
+ * @example
+ * const { services, resources } = useCatalog()
+ */
+declare function useCatalog(): {
+  services: ServiceCard[];
+  resources: ResourceInfo[];
+};
+//#endregion
+export { SynapseProvider, skip, useCall, useCatalog, useConnectionState, useConnectionStatus, useReady, useRole, useService, useStateMirror, useSubscribe, useSynapse, useSystem };

package/dist/react.js

@@ -0,0 +1,141 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react.tsx
+/** Pass as the resource to `useSubscribe` to disable it conditionally (à la Convex). */
+const skip = "skip";
+const SynapseContext = createContext(null);
+function SynapseProvider({ client, children }) {
+	return /* @__PURE__ */ jsx(SynapseContext.Provider, {
+		value: client,
+		children
+	});
+}
+/** The `Synapse` client from the nearest provider. */
+function useSynapse() {
+	const client = useContext(SynapseContext);
+	if (!client) throw new Error("useSynapse must be used within <SynapseProvider>");
+	return client;
+}
+/** The full connection state; re-renders on any status/endpoint/error change. */
+function useConnectionState() {
+	const client = useSynapse();
+	const subscribe = useCallback((cb) => client.subscribeState(() => cb()), [client]);
+	const getSnapshot = useCallback(() => client.getState(), [client]);
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/** Just the status — `idle | connecting | connected | reconnecting | closing | error`. */
+function useConnectionStatus() {
+	return useConnectionState().status;
+}
+/** Full readiness — `{ status, role, projectId, ready, error }`. Bind your connection
+*  indicator to `{ status, role }`. */
+function useSystem() {
+	const client = useSynapse();
+	const subscribe = useCallback((cb) => client.subscribeSystem(() => cb()), [client]);
+	const getSnapshot = useCallback(() => client.getSystem(), [client]);
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/** The gate: transport-connected AND a server role assigned (or `system: false`). */
+function useReady() {
+	return useSystem().ready;
+}
+/** The server-assigned session role (`viewer` / `controller` / …), or null until negotiated. */
+function useRole() {
+	return useSystem().role;
+}
+/**
+* Live value of a pub/sub resource — the latest message (latest-wins, no queue growth), or
+* `undefined` until the first arrives. Pass `skip` to disable. For 60 Hz data feeding
+* three.js, prefer the imperative `synapse.latest(resource).get()` inside `useFrame` instead
+* (this hook re-renders on every message).
+*/
+function useSubscribe(resource, opts) {
+	const client = useSynapse();
+	const disabled = resource === skip;
+	const holder = useMemo(() => disabled ? null : client.latest(resource, opts), [
+		client,
+		resource,
+		disabled,
+		opts ? JSON.stringify(opts) : ""
+	]);
+	useEffect(() => () => holder?.close(), [holder]);
+	return useSyncExternalStore(useCallback((cb) => holder ? holder.onChange(() => cb()) : () => {}, [holder]), useCallback(() => holder?.get(), [holder]), () => void 0);
+}
+/** A stable bound `call` — like TanStack/Convex `useMutation` returning a callable. */
+function useCall() {
+	const client = useSynapse();
+	return useMemo(() => client.call.bind(client), [client]);
+}
+/**
+* Register this node as a provider for the lifetime of the component (e.g. a browser
+* exposing a joystick service the robot calls into). The handler is read from a ref, so it
+* can close over fresh props without re-registering.
+*/
+function useService(name, handler, card) {
+	const client = useSynapse();
+	const handlerRef = useRef(handler);
+	handlerRef.current = handler;
+	useEffect(() => {
+		const reg = client.service(name, (input, ctx) => handlerRef.current(input, ctx), card);
+		return () => reg.unregister();
+	}, [client, name]);
+}
+const EMPTY_STATE = Object.freeze({});
+/**
+* Live mirror of a `synapse:state:<name>` resource. Returns `[value, handle]`: `value` is the
+* converged map (re-renders on change), `handle` exposes `put`/`delete` (null until opened).
+*
+* @example
+* const [scene, handle] = useStateMirror("world/collision")
+* // render scene.box_1 …; handle?.put("box_2", { xyz: [1, 0, 0] })
+*/
+function useStateMirror(resource) {
+	const client = useSynapse();
+	const [handle, setHandle] = useState(null);
+	useEffect(() => {
+		let active = true;
+		setHandle(null);
+		client.openState(resource).then((h) => {
+			if (active) setHandle(h);
+		}).catch(() => {});
+		return () => {
+			active = false;
+		};
+	}, [client, resource]);
+	return [useSyncExternalStore(useCallback((cb) => handle ? handle.subscribe(() => cb()) : () => {}, [handle]), useCallback(() => handle?.value ?? EMPTY_STATE, [handle]), () => EMPTY_STATE), handle];
+}
+/**
+* Live discovery — the bus's services and state resources, refreshed when any provider or
+* resource is added/removed.
+*
+* @example
+* const { services, resources } = useCatalog()
+*/
+function useCatalog() {
+	const client = useSynapse();
+	const [catalog, setCatalog] = useState({
+		services: [],
+		resources: []
+	});
+	useEffect(() => {
+		let active = true;
+		const refresh = async () => {
+			try {
+				const [services, resources] = await Promise.all([client.listServices(), client.listResources()]);
+				if (active) setCatalog({
+					services,
+					resources
+				});
+			} catch {}
+		};
+		refresh();
+		const sub = client.watchCatalog(() => void refresh());
+		return () => {
+			active = false;
+			sub.unsubscribe();
+		};
+	}, [client]);
+	return catalog;
+}
+//#endregion
+export { SynapseProvider, skip, useCall, useCatalog, useConnectionState, useConnectionStatus, useReady, useRole, useService, useStateMirror, useSubscribe, useSynapse, useSystem };