@synapse-sdk/react 0.3.0 → 0.3.4

package/README.md

@@ -1,3 +1,155 @@
 # @synapse-sdk/react
 
-Part of the Synapse SDK for JavaScript. Documentation: the repository.
+React hooks for a Synapse node: `<SynapseProvider node={node}>` above your components, then `useConnection()`,
+`useProject()`, `useCatalog()` (the node's `status`, `project` and `catalog` cells), `useTopic(t, { select })`, `useCall(svc)`, `useServe(svc, handler)`,
+`usePublisher(t)`, `useStore(name)`, `useScene()`, `useSceneEntity(scene, id | { name }, { select })`, `useSceneTree(scene)`,
+`useSceneStatus(scene)` and `useTasks(select?)`. Every hook reads a value the node keeps current; none keeps its own
+copy.
+
+## Two kinds of users
+
+- **Node author** (a robot driver, a sim, a task, a panel that edits a few known things): `node.store(name)` with
+  `get()`/`set()`/`watch()`; `scene.authored.upsert(kind, { name, ... })`, keyed by name, resolves with the entity's view;
+  `scene.entity(id)` or `scene.entity({ name })`, a view of the merged entity with `get()`/`get(component)`/`watch()` and
+  its two planes: `view.authored.get()`/`.set(...)` (one patch of the authored entity) and `view.live.get()` (the live row,
+  its `stamp`)/`.set({ xform, joints, state }, { lifetimeMs })` (its live lanes; the first write of an id asks its
+  override claim and lands once granted)/`await .remove()` (the release call); the view's own `watch`/`subscribe`/`changed`
+  cover both planes; `await scene.live.upsert(kind, { name?, parent?, ... }, { lifetimeMs })` for a live entity of the
+  node's own (the claim call: the view of the id the runtime answered; claimed again, same id, on every attach until
+  `await scene.live.remove(x)`); `scene.live.batch({ poses, joints, state, lifetimeMs })` (lanes only) for a sim's one write per tick.
+  Decisions are calls, data is streams.
+- **Engine or editor builder** (a 3D view, a scene editor): `scene.authored.spawn`/`patch`/`rename`/`reparent`/`despawn`/
+  `setLocked`, `txn`/`apply` (an entity named by its id or its view), and the feeds (`scene.watch()` for the authored
+  changes, `watchLiveRemovals`, `watchLiveDenied`).
+
+Every handle (store, scene) has one shape: `ready()`, `status` (a cell: `get()`, `subscribe(listener)`, `changed()`),
+`synced`, `watch()`, `changed()`, `close()`. `useSceneStatus(scene)` reads `scene.status`; `useNotices()` follows
+`node.notices(cb)`.
+
+```tsx
+const tool = useSceneEntity(scene, { name: "tool" }, { select: e => e?.props?.speed });   // follows the name
+const view = useMemo(() => scene?.entity({ name: "tool" }), [scene]);
+<button onClick={() => view?.authored.set("props", { speed: 2 })}>faster</button>          // one patch of whoever holds the name now
+const busy = useSceneEntity(scene, { name: "tool" }, { select: e => e?.state?.busy });     // merged: the live state lane shows
+// the live row alone (its `stamp`) is the view's, read in a frame loop: view.live.get()?.stamp (no render)
+```
+
+## Connecting
+
+`new Synapse(opts)` is the only way to make a node; `opts` is who the node is (`type`, `name`, ...), never where it
+connects. It returns a node that works at once: its status, every hook and every handle, before any connection.
+Constructing opens nothing (safe during SSR); only `connect(target)` dials (a script awaits it; an app does not). Before
+the first session the node behaves as it does between two sessions: `useConnection()` is `idle` (no target yet) or
+`connecting`, the catalog is empty, `useStore`/`useScene` hand back their handle once the first session brings it in,
+`useTasks()` is empty with `synced: false`, and a call fails `not_connected`.
+
+```tsx
+import { useEffect } from "react";
+import { Synapse } from "@synapse-sdk/client";
+import { SynapseProvider, useConnection } from "@synapse-sdk/react";
+
+const node = new Synapse({ type: "hmi" });   // or useState(() => new Synapse({ type: "hmi" })) in a component
+
+function Robot({ robot }: { robot?: string }) {   // the robot's url, picked from the app's URL
+  useEffect(() => {
+    if (robot) node.connect({ url: robot });   // not awaited: a failure shows as `failed` in useConnection()
+    else node.disconnect();                    // "no robot": `idle`, every handle kept
+  }, [robot]);
+  return null;
+}
+
+function Status() {
+  const c = useConnection();
+  switch (c.status) {
+    case "connected": return <span>connected to {c.url}</span>;
+    case "connecting": case "reconnecting": return <span>connecting…</span>;
+    case "failed": return <button onClick={() => node.connect()}>{c.error.code}: retry</button>;   // resting: connect() dials the target again
+    case "idle": return <span>no robot selected</span>;                                          // no target (disconnect())
+    default: return <span>{c.status}</span>;                                                       // closing / closed (after close())
+  }
+}
+
+export const App = ({ robot }: { robot?: string }) => <SynapseProvider node={node}><Robot robot={robot} /><Status />{/* … */}</SynapseProvider>;
+```
+
+`connect({ url })` (or `connect(url)`) closes the old session, if any, before the new target is dialed; every handle
+re-binds to the new session as across a reconnect. Operator intent is never lost under quick clicking: the newest call
+wins, and a call superseded by a newer `connect()` or `disconnect()` resolves quietly. The same target again dials
+nothing and settles with it. `connect()` with no target settles with the declared one. `failed` is not the end: the
+node rests there until the next `connect()`; only `close()` ends it (`closed`).
+
+## Calls
+
+`useCall(svc, opts)` is the one call hook, request/reply or streaming: `{ call, cancel, status, data, error, updates,
+latestUpdate, run, reset }`. `status` speaks TanStack (`idle | pending | success | error`); the spec's run status is on
+`run.status`. `call(args)` returns the `Run`: ignore it (the hook handles the outcome: a failure lands in `error`, never
+an unhandled rejection) or `await` it (resolves with the result, rejects with the error). `cancel(reason?)` never
+rejects: it resolves once the run has ended, and the outcome is what `status`/`error` show (a canceled run is `error`
+with `error.code === "canceled"`). Every run still in flight is canceled with reason `"unmount"` when the component
+unmounts. `updates` keeps the newest `maxUpdates` (default 100); `reset()` goes back to `idle`.
+
+```tsx
+const { call, cancel, status, data, error, latestUpdate } = useCall(api.arm.moveTo);
+<button onClick={() => call({ target: 1.2 })} disabled={status === "pending"}>move</button>
+{status === "pending" && <><progress value={latestUpdate?.progress ?? 0} /><button onClick={() => cancel()}>stop</button></>}
+{status === "success" && <span>reached: {String(data!.reached)}</span>}
+{status === "error" && <span>{error!.code}</span>}
+```
+
+## Tasks
+
+`useTasks()` is one view: `status` (what runs, `node.tasks.status.get()`), `catalog` (what the runtime offers), `synced`,
+and the four verbs; the view is the same object while none of the three values changed. `useTasks(select)` is what
+`select` picks from that view, and the component re-renders only when the selection changes (an unchanged selection
+keeps its object). A button that only runs and stops needs no subscription: it calls the verbs on the node.
+
+```tsx
+function RunPill() {
+  const node = useSynapse();
+  const state = useTasks(t => t.status.project.state);               // re-renders on the project run's state only
+  const [note, setNote] = useState<string>();
+  const run = () => node.tasks.runProjectTasks().then(
+    r => setNote(`${r.launched} running · ${r.passive} passive`),
+    e => setNote(isTasksRefusal(e) ? e.data.report.map(i => `${i.entity_name ?? i.instance}: ${i.reason}`).join("\n") : e.code));
+  if (state === "running" || state === "stopping")
+    return <button disabled={state === "stopping"} onClick={() => node.tasks.stopProjectTasks()}>{state === "stopping" ? "stopping" : "running · stop"}</button>;
+  return <><button disabled={state !== "stopped"} onClick={run}>{state === "starting" ? "starting" : "run"}</button>{note}</>;
+}
+
+// a per-entity dot: undefined = not running
+const sim = useTasks(t => t.status.project.tasks[entityId]?.sim?.state);
+
+// the picker: every task the runtime offers, by address
+const { catalog, synced } = useTasks();
+```
+
+`useTasks()` works from the first render, connected or not: before a session `status` and `catalog` are empty and `synced` is false.
+
+## 3D reads, HTML renders
+
+3D never renders through React. A frame loop (`useFrame`, or any engine loop) reads the current value imperatively,
+from a view made once, and compares with `===`: the values are structurally shared, so a part that did not change is
+the same object and the loop can skip it. No React state, no re-render, no hook per entity. Hooks with `select` are
+for the HTML side: they wake a component only when its selection changes.
+
+| what | in the frame loop (no render) | hook for HTML (wakes on) |
+|---|---|---|
+| one entity | `const v = useMemo(() => scene.entity(id), [scene, id])` (or `scene.entity({ name })`); `v.get()`, `v.get("xform")` | `useSceneEntity(scene, id \| { name }, { select })` (the selection changing) |
+| a topic | `const v = useMemo(() => node.view(t), [t])` (close it on unmount); `v.get().data` | `useTopic(t, { select })` (the selection changing) |
+| a namespace | `store.get()` (or `store.get(key)`) | `useStore(name)` (any change of the namespace) |
+| tasks | `node.tasks.status.get()` | `useTasks(select)` (the selection changing) |
+
+```tsx
+function Arm({ scene, id }: { scene: SceneHandle; id: string }) {
+  const ref = useRef<THREE.Group>(null);
+  const view = useMemo(() => scene.entity(id), [scene, id]);       // made once
+  const last = useRef<SceneEntity | undefined>(undefined);
+  useFrame(() => {
+    const e = view.get();                                          // the value now: no render
+    if (e === last.current || !e?.xform) return;                   // unchanged: the same object
+    last.current = e;
+    ref.current!.position.fromArray(e.xform.t ?? [0, 0, 0]);
+  });
+  return <group ref={ref} />;
+}
+```

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { Synapse, Catalog, ConnectionState, Notice, ViewOptions, ViewState, Run, CallOptions, Publisher, ServeHandler, ServeOptions, Registration, StoreHandle, StoreOptions, SceneEntity, SceneEntityLive, SceneHandle, SceneStatus, SceneTree } from "@synapse-sdk/client";
+import type { Synapse, Catalog, ConnectionState, ViewOptions, ViewState, Run, CallOptions, Publisher, ServeHandler, ServeOptions, Registration, StoreHandle, StoreOptions, SceneEntity, SceneEntityRef, SceneHandle, SceneStatus, SceneTree, TasksStatus, TaskCatalogEntry, TasksRun } from "@synapse-sdk/client";
 import type { ErrorBody, ProjectSnapshot, ServiceRef, TopicRef, SynapseError } from "@synapse-sdk/core";
 export declare function SynapseProvider({ node, children }: {
     node: Synapse;
@@ -8,16 +8,14 @@ export declare function SynapseProvider({ node, children }: {
 export declare function useSynapse(): Synapse;
 /** The node from the nearest `<SynapseProvider>`, or `null` when there is none. */
 export declare function useSynapseOptional(): Synapse | null;
-/** The node's `ConnectionState`; a `setTarget` switch shows as `connecting` → `connected` with the new `url`. */
+/** The node's `ConnectionState` (`node.status`); a `connect(target)` switch shows as `connecting` → `connected` with the new `url`. */
 export declare function useConnection(): ConnectionState;
-/** The runtime's project state (`node.project()`, WP §3.5); `undefined` between sessions or before the first snapshot. */
+/** The runtime's project state (`node.project`, WP §3.5); `undefined` between sessions or before the first snapshot. */
 export declare function useProject(): ProjectSnapshot | undefined;
-/** The runtime's catalogs as the current session last read them. */
+/** The runtime's catalogs as the current session last read them (`node.catalog`). */
 export declare function useCatalog(): Catalog;
-/** The last `limit` broker notices (`node.onNotice`) since the component mounted, newest last. */
+/** The last `limit` notices (`node.notices`) since the component mounted, newest last. */
 export declare function useNotices(limit?: number): ErrorBody[];
-/** The last `limit` `promoted`/`demoted` notices since the component mounted, newest last. */
-export declare function useProjectNotices(limit?: number): Notice[];
 /** Typed disabled sentinel: `useTopic("skip")` renders `pending` without subscribing. */
 export type Skip = "skip";
 /**
@@ -31,32 +29,30 @@ export type Skip = "skip";
 export declare function useTopic<TOut, S = TOut>(topic: TopicRef<unknown, TOut> | Skip, opts?: ViewOptions<TOut, S>): ViewState<S>;
 /** TanStack's mutation vocabulary (`useMutation().status`); the protocol's `RunStatus` lives on `run.status`. */
 export type CallStatus = "idle" | "pending" | "success" | "error";
-/** A request/reply call as a mutation: `call(args)` returns the result; `status`/`data`/`error` follow the latest call. */
-export declare function useCall<A, R>(svc: ServiceRef<A, unknown, unknown, R>, opts?: CallOptions<unknown>): {
-    call: (args: A) => Promise<R>;
-    reset(): void;
-    status: CallStatus;
-    data?: R;
-    error?: SynapseError;
-};
-export interface UseStartOptions<U> extends CallOptions<U> {
+export interface UseCallOptions<U> extends CallOptions<U> {
     /** How many progress updates `updates` keeps (newest last); default 100. `latestUpdate` is always the newest. */
     maxUpdates?: number;
 }
 /**
- * `start()` a streaming call from a component. `status` is TanStack's (`pending` covers the spec's
- * `pending` and `running`; `error` covers `failed` and `canceled` — `run.status` and `error.code`
- * tell which). The run in flight is canceled with reason `"unmount"` when the component unmounts.
+ * A call from a component, request/reply or streaming: `call(args)` starts it and returns its `Run`; `status`, `data`,
+ * `error`, `updates`, `latestUpdate` and `run` follow the latest call. `status` is TanStack's (`pending` covers the
+ * spec's `pending` and `running`; `error` covers `failed` and `canceled`: `run.status` and `error.code` tell which).
+ * The hook handles every run's outcome itself, so `call(args)` may be ignored (no unhandled rejection) or awaited
+ * (`await call(args)` resolves with the result or rejects with the error). `cancel(reason?)` cancels the latest run and
+ * resolves once it has ended, never rejecting: its outcome (`canceled`, or the result that won the race) is what
+ * `status`/`error`/`data` show. Every run still in flight is canceled with reason `"unmount"` when the component
+ * unmounts. `reset()` forgets the latest call (back to `idle`); a run in flight goes on, unfollowed.
  */
-export declare function useStart<A, U, R>(svc: ServiceRef<A, unknown, U, R>, opts?: UseStartOptions<U>): {
-    start: (args: A) => Run<U, R>;
+export declare function useCall<A, U, R>(svc: ServiceRef<A, unknown, U, R>, opts?: UseCallOptions<U>): {
+    call: (args: A) => Run<U, R>;
     cancel: (reason?: string) => Promise<void>;
+    reset: () => void;
     run: Run<U, R> | undefined;
     status: CallStatus;
+    data: R | undefined;
+    error: SynapseError | undefined;
     updates: U[];
     latestUpdate: U;
-    result: R | undefined;
-    error: SynapseError | undefined;
 };
 /** Registers a provider on mount and unregisters on unmount (see `acquireLease`). The handler may change between renders. */
 export declare function useServe<I, U, R>(svc: ServiceRef<I, I, U, R>, handler: ServeHandler<I, U, R>, opts?: ServeOptions): {
@@ -83,22 +79,40 @@ export declare function useStore(name: string, opts?: StoreOptions): readonly [R
  */
 export declare function useScene(): readonly [SceneHandle | null, SynapseError | undefined];
 /**
- * One entity of the scene (`scene.entity(id, { plane })`): the merged entity (or, with `plane`, that
- * layer's value alone: `authored` or `live`), or what `select` picks from it (`select` gets
- * `undefined` while there is none). The view reads the handle's copy
+ * One entity of the scene: `scene.entity(id | { name })`, the merged entity (authored with its live overrides), or what
+ * `select` picks from it (`select` gets `undefined` while there is none). One plane alone (`view.authored.get()`,
+ * `view.live.get()` with its `stamp`) is read imperatively from the view, as a frame loop does. By name (`useSceneEntity(scene, { name: "tool" })`) it follows the name: the
+ * entity holding it now. The view reads the handle's copy
  * of the scene and follows it only while the component is subscribed. `select` runs here with the
  * selector of the latest render; a selected value deep-equal to the previous one keeps its reference,
  * so a live pose that does not change what `select` picks does not re-render the component.
  */
-export declare function useSceneEntity<S = SceneEntity | undefined>(scene: SceneHandle | null | undefined, id: string | null | undefined, opts?: {
-    plane?: "authored";
+export declare function useSceneEntity<S = SceneEntity | undefined>(scene: SceneHandle | null | undefined, ref: SceneEntityRef | null | undefined, opts?: {
     select?: (e: SceneEntity | undefined) => S;
 }): S;
-export declare function useSceneEntity<S = SceneEntityLive | undefined>(scene: SceneHandle | null | undefined, id: string | null | undefined, opts: {
-    plane: "live";
-    select?: (e: SceneEntityLive | undefined) => S;
-}): S;
 /** The scene's hierarchy (`scene.tree()`), as its roots: the same array while the structure does not change; empty without a scene. */
 export declare function useSceneTree(scene: SceneHandle | null | undefined): SceneTree;
-/** The scene handle's status (`scene.status`), re-rendering when a field changes; `undefined` without a scene. */
+/** The scene handle's status (`scene.status`, a state value), re-rendering when a field changes; `undefined` without a scene. */
 export declare function useSceneStatus(scene: SceneHandle | null | undefined): SceneStatus | undefined;
+/** What `useTasks` hands back: the facet's three values as the node keeps them current, and its verbs (stable for the node's life). */
+export interface TasksView {
+    readonly status: TasksStatus;
+    /** By address. */
+    readonly catalog: Readonly<Record<string, TaskCatalogEntry>>;
+    /** Both `status` and `catalog` current. */
+    readonly synced: boolean;
+    runRobotTasks(): Promise<TasksRun>;
+    stopRobotTasks(): Promise<void>;
+    runProjectTasks(): Promise<TasksRun>;
+    stopProjectTasks(): Promise<void>;
+}
+/**
+ * The node's tasks: `status` (what runs), `catalog` (what the runtime offers) and `synced`, with the verbs, as one
+ * `TasksView`; or what `select` picks from it. The view is the same object while none of the three values changed.
+ * `select` runs here with the selector of the latest render; a selected value deep-equal to the previous one keeps its
+ * reference, so a change elsewhere (another task's restart, a catalog refresh) does not re-render the component.
+ * A component that only runs and stops needs no subscription: `useSynapse().tasks.runProjectTasks()`.
+ * Works from the first render, connected or not: before a session `status`/`catalog` are empty and `synced` is false.
+ */
+export declare function useTasks(): TasksView;
+export declare function useTasks<S>(select: (t: TasksView) => S): S;

package/dist/index.js

@@ -1,5 +1,5 @@
-// @synapse-sdk/react: thin hooks over the client's cells (SDK §8). No wrapper state: every hook reads
-// through useSyncExternalStore from a client object (a view, a store handle, the node's link).
+// @synapse-sdk/react: thin hooks over the client's state values (SDK §8). No wrapper state: every hook reads
+// through useSyncExternalStore from a client object (a view, a store handle, the node's state values).
 //
 // Statuses speak TanStack here (`idle | pending | success | error`, like `useMutation`); the spec's
 // five-state `RunStatus` stays on the `Run` the hooks hand back. One rule, two layers.
@@ -18,43 +18,26 @@ export function useSynapse() {
 }
 /** The node from the nearest `<SynapseProvider>`, or `null` when there is none. */
 export function useSynapseOptional() { return useContext(SynapseContext); }
-/** The node's `ConnectionState`; a `setTarget` switch shows as `connecting` → `connected` with the new `url`. */
+/** The node's `ConnectionState` (`node.status`); a `connect(target)` switch shows as `connecting` → `connected` with the new `url`. */
 export function useConnection() {
     const node = useSynapse();
-    // `node.status` builds a new object on every read; React needs the same object while nothing
-    // changed, so the last one read is kept and handed back while every field is the same.
-    const last = useRef(undefined);
-    const get = useCallback(() => {
-        const s = node.status;
-        if (!shallowEqual(last.current, s))
-            last.current = s;
-        return last.current;
-    }, [node]);
-    return useSyncExternalStore(useCallback((cb) => node.watchStatus(() => cb()), [node]), get, get);
+    return useSyncExternalStore(useCallback((cb) => node.status.onChange(() => cb()), [node]), () => node.status.get(), () => node.status.get());
 }
-/** The runtime's project state (`node.project()`, WP §3.5); `undefined` between sessions or before the first snapshot. */
+/** The runtime's project state (`node.project`, WP §3.5); `undefined` between sessions or before the first snapshot. */
 export function useProject() {
     const node = useSynapse();
-    return useSyncExternalStore(useCallback((cb) => node.watchProject(() => cb()), [node]), () => node.project(), () => node.project());
+    return useSyncExternalStore(useCallback((cb) => node.project.onChange(() => cb()), [node]), () => node.project.get(), () => node.project.get());
 }
-/** The runtime's catalogs as the current session last read them. */
+/** The runtime's catalogs as the current session last read them (`node.catalog`). */
 export function useCatalog() {
     const node = useSynapse();
-    const ref = useRef(node.catalog);
-    return useSyncExternalStore(useCallback((cb) => node.watchCatalog(c => { ref.current = c; cb(); }), [node]), () => ref.current, () => ref.current);
+    return useSyncExternalStore(useCallback((cb) => node.catalog.onChange(() => cb()), [node]), () => node.catalog.get(), () => node.catalog.get());
 }
-/** The last `limit` broker notices (`node.onNotice`) since the component mounted, newest last. */
+/** The last `limit` notices (`node.notices`) since the component mounted, newest last. */
 export function useNotices(limit = 20) {
     const node = useSynapse();
     const [list, setList] = useState([]);
-    useEffect(() => node.onNotice(n => setList(l => [...l, n].slice(-limit))), [node, limit]);
-    return list;
-}
-/** The last `limit` `promoted`/`demoted` notices since the component mounted, newest last. */
-export function useProjectNotices(limit = 20) {
-    const node = useSynapse();
-    const [list, setList] = useState([]);
-    useEffect(() => node.onProjectNotice(n => setList(l => [...l, n].slice(-limit))), [node, limit]);
+    useEffect(() => node.notices(n => setList(l => [...l, n].slice(-limit))), [node, limit]);
     return list;
 }
 const SKIP_STATE = { data: undefined, status: "pending", connection: "connecting", lastChangeAtUs: undefined };
@@ -87,7 +70,7 @@ export function useTopic(topic, opts = {}) {
         setView(v);
         return () => { v.close(); };
     }, [node, key]);
-    const subscribe = useCallback((cb) => (view ? view.subscribe(cb) : () => { }), [view]);
+    const subscribe = useCallback((cb) => (view ? view.onChange(() => cb()) : () => { }), [view]);
     // The last result, with what it was made from: the same view state and selector give it back unchanged.
     const last = useRef(undefined);
     const get = useCallback(() => {
@@ -109,78 +92,75 @@ export function useTopic(topic, opts = {}) {
 }
 /** A service as a name: what the hooks key their memoisation on, so an inline contract (a new object every render) is fine. */
 function nameOf(svc) { return typeof svc === "string" ? svc : svc.name; }
-/** A request/reply call as a mutation: `call(args)` returns the result; `status`/`data`/`error` follow the latest call. */
-export function useCall(svc, opts = {}) {
-    const node = useSynapse();
-    const [state, setState] = useState({ status: "idle" });
-    const optsRef = useRef(opts);
-    optsRef.current = opts;
-    const svcRef = useRef(svc);
-    svcRef.current = svc;
-    const name = nameOf(svc);
-    const seq = useRef(0);
-    const call = useCallback(async (args) => {
-        const my = ++seq.current;
-        setState(s => ({ ...s, status: "pending", error: undefined }));
-        try {
-            const r = await node.call(svcRef.current, args, optsRef.current).result;
-            if (my === seq.current)
-                setState({ status: "success", data: r });
-            return r;
-        }
-        catch (e) {
-            const err = toSynapseError(e);
-            if (my === seq.current)
-                setState(s => ({ ...s, status: "error", error: err }));
-            throw err;
-        }
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [node, name]);
-    const reset = useCallback(() => { seq.current++; setState({ status: "idle" }); }, []);
-    return { call, reset, ...state };
-}
+const IDLE = { run: undefined, status: "idle", data: undefined, error: undefined, updates: [] };
 /**
- * `start()` a streaming call from a component. `status` is TanStack's (`pending` covers the spec's
- * `pending` and `running`; `error` covers `failed` and `canceled` — `run.status` and `error.code`
- * tell which). The run in flight is canceled with reason `"unmount"` when the component unmounts.
+ * A call from a component, request/reply or streaming: `call(args)` starts it and returns its `Run`; `status`, `data`,
+ * `error`, `updates`, `latestUpdate` and `run` follow the latest call. `status` is TanStack's (`pending` covers the
+ * spec's `pending` and `running`; `error` covers `failed` and `canceled`: `run.status` and `error.code` tell which).
+ * The hook handles every run's outcome itself, so `call(args)` may be ignored (no unhandled rejection) or awaited
+ * (`await call(args)` resolves with the result or rejects with the error). `cancel(reason?)` cancels the latest run and
+ * resolves once it has ended, never rejecting: its outcome (`canceled`, or the result that won the race) is what
+ * `status`/`error`/`data` show. Every run still in flight is canceled with reason `"unmount"` when the component
+ * unmounts. `reset()` forgets the latest call (back to `idle`); a run in flight goes on, unfollowed.
  */
-export function useStart(svc, opts = {}) {
+export function useCall(svc, opts = {}) {
     const node = useSynapse();
-    const [run, setRun] = useState(undefined);
-    const [status, setStatus] = useState("idle");
-    const [updates, setUpdates] = useState([]);
-    const [result, setResult] = useState(undefined);
-    const [error, setError] = useState(undefined);
+    const [state, setState] = useState(IDLE);
     const optsRef = useRef(opts);
     optsRef.current = opts;
     const svcRef = useRef(svc);
     svcRef.current = svc;
+    /** The run the state follows (the latest call's, until `reset`). */
     const runRef = useRef(undefined);
+    /** Every run started here and not yet ended: canceled on unmount. */
+    const inFlight = useRef(new Set());
     const name = nameOf(svc);
-    const start = useCallback((args) => {
+    const call = useCallback((args) => {
         const { maxUpdates = 100, ...callOpts } = optsRef.current;
         const keep = Math.max(1, maxUpdates);
-        const r = node.call(svcRef.current, args, { ...callOpts, onUpdate: u => { if (runRef.current === r)
-                setUpdates(prev => (prev.length < keep ? [...prev, u] : [...prev.slice(prev.length - keep + 1), u])); optsRef.current.onUpdate?.(u); } });
-        runRef.current = r;
-        setRun(r);
-        setStatus("pending");
-        setUpdates([]);
-        setResult(undefined);
-        setError(undefined);
-        r.result.then(v => { if (runRef.current === r) {
-            setResult(v);
-            setStatus("success");
-        } }, e => { if (runRef.current === r) {
-            setError(toSynapseError(e));
-            setStatus("error");
-        } });
-        return r;
+        let r;
+        const onUpdate = (u) => {
+            if (r !== undefined && runRef.current === r) {
+                const mine = r;
+                setState(s => (s.run === mine ? { ...s, updates: s.updates.length < keep ? [...s.updates, u] : [...s.updates.slice(s.updates.length - keep + 1), u] } : s));
+            }
+            // Forwarded while the run is in flight here: not after unmount (its cleanup empties the set), even for a frame
+            // that lands before the cancel does. `reset()` leaves the run in flight, so it goes on forwarding.
+            if (r !== undefined && inFlight.current.has(r))
+                optsRef.current.onUpdate?.(u);
+        };
+        const run = node.call(svcRef.current, args, { ...callOpts, onUpdate });
+        r = run;
+        runRef.current = run;
+        inFlight.current.add(run);
+        setState({ run, status: "pending", data: undefined, error: undefined, updates: [] });
+        run.result.then(v => { inFlight.current.delete(run); if (runRef.current === run)
+            setState(s => ({ ...s, status: "success", data: v })); }, e => { inFlight.current.delete(run); if (runRef.current === run)
+            setState(s => ({ ...s, status: "error", error: toSynapseError(e) })); });
+        return run;
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [node, name]);
-    const cancel = useCallback((reason) => runRef.current?.cancel(reason) ?? Promise.resolve(), []);
-    useEffect(() => () => { const r = runRef.current; runRef.current = undefined; void r?.cancel("unmount"); }, []);
-    return { start, cancel, run, status, updates, latestUpdate: updates[updates.length - 1], result, error };
+    const cancel = useCallback(async (reason) => {
+        const r = runRef.current;
+        if (!r)
+            return;
+        try {
+            await r.cancel(reason);
+        }
+        catch { /* the run's outcome is shown by status/error */ }
+        try {
+            await r.result;
+        }
+        catch { /* ended: shown by status/error */ }
+    }, []);
+    const reset = useCallback(() => { runRef.current = undefined; setState(IDLE); }, []);
+    useEffect(() => () => {
+        runRef.current = undefined;
+        for (const r of inFlight.current)
+            r.cancel("unmount").catch(() => { });
+        inFlight.current.clear();
+    }, []);
+    return { call, cancel, reset, run: state.run, status: state.status, data: state.data, error: state.error, updates: state.updates, latestUpdate: state.updates[state.updates.length - 1] };
 }
 const leases = new WeakMap();
 function acquireLease(node, svc, handler, opts) {
@@ -286,18 +266,17 @@ export function useStore(name, opts = {}) {
         return () => { mine = false; h?.close(); };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [node, key]);
-    const subscribe = useCallback((cb) => (handle ? handle.subscribe(cb) : () => { }), [handle]);
+    const subscribe = useCallback((cb) => (handle ? handle.onChange(() => cb()) : () => { }), [handle]);
     // React re-renders when the snapshot changes: it holds the value and the handle's status, so a
     // change of `synced`/`pending`/`connected` alone re-renders too (the component reads them on
-    // `handle`). `handle.status` builds a new object on every read, so the snapshot is rebuilt only
-    // when the value or a status field differs.
+    // `handle`). `handle.status.get()` is the same object while unchanged.
     const last = useRef(undefined);
     const get = useCallback(() => {
         if (!handle)
             return undefined;
-        const value = handle.value, status = handle.status;
+        const value = handle.get(), status = handle.status.get();
         const prev = last.current;
-        if (!prev || prev.handle !== handle || prev.value !== value || !shallowEqual(prev.status, status))
+        if (!prev || prev.handle !== handle || prev.value !== value || prev.status !== status)
             last.current = { handle, value, status };
         return last.current;
     }, [handle]);
@@ -327,12 +306,25 @@ export function useScene() {
     }, [node]);
     return [scene, error];
 }
-export function useSceneEntity(scene, id, opts = {}) {
+/**
+ * One entity of the scene: `scene.entity(id | { name })`, the merged entity (authored with its live overrides), or what
+ * `select` picks from it (`select` gets `undefined` while there is none). One plane alone (`view.authored.get()`,
+ * `view.live.get()` with its `stamp`) is read imperatively from the view, as a frame loop does. By name (`useSceneEntity(scene, { name: "tool" })`) it follows the name: the
+ * entity holding it now. The view reads the handle's copy
+ * of the scene and follows it only while the component is subscribed. `select` runs here with the
+ * selector of the latest render; a selected value deep-equal to the previous one keeps its reference,
+ * so a live pose that does not change what `select` picks does not re-render the component.
+ */
+export function useSceneEntity(scene, ref, opts = {}) {
     const selectRef = useRef(opts.select);
     selectRef.current = opts.select;
-    const plane = opts.plane;
-    const view = useMemo(() => (scene && id ? scene.entity(id, plane ? { plane } : undefined) : undefined), [scene, id, plane]);
-    const subscribe = useCallback((cb) => (view ? view.subscribe(cb) : () => { }), [view]);
+    // An inline `{ name }` is a new object every render: the view is keyed on what it names.
+    const id = typeof ref === "string" ? ref : undefined, name = ref && typeof ref === "object" ? ref.name : undefined;
+    const view = useMemo(() => {
+        const target = id !== undefined && id !== "" ? id : name !== undefined ? { name } : undefined;
+        return scene && target !== undefined ? scene.entity(target) : undefined;
+    }, [scene, id, name]);
+    const subscribe = useCallback((cb) => (view ? view.onChange(() => cb()) : () => { }), [view]);
     const last = useRef(undefined);
     const get = useCallback(() => {
         const from = view?.get();
@@ -352,22 +344,44 @@ const EMPTY_TREE = [];
 /** The scene's hierarchy (`scene.tree()`), as its roots: the same array while the structure does not change; empty without a scene. */
 export function useSceneTree(scene) {
     const view = useMemo(() => scene?.tree(), [scene]);
-    const subscribe = useCallback((cb) => (view ? view.subscribe(cb) : () => { }), [view]);
+    const subscribe = useCallback((cb) => (view ? view.onChange(() => cb()) : () => { }), [view]);
     const get = useCallback(() => view?.get() ?? EMPTY_TREE, [view]);
     return useSyncExternalStore(subscribe, get, get);
 }
-/** The scene handle's status (`scene.status`), re-rendering when a field changes; `undefined` without a scene. */
+/** The scene handle's status (`scene.status`, a state value), re-rendering when a field changes; `undefined` without a scene. */
 export function useSceneStatus(scene) {
-    // `scene.status` builds a new object on every read: the last one is kept while every field is the same.
+    const subscribe = useCallback((cb) => (scene ? scene.status.onChange(() => cb()) : () => { }), [scene]);
+    const get = useCallback(() => scene?.status.get(), [scene]);
+    return useSyncExternalStore(subscribe, get, get);
+}
+export function useTasks(select) {
+    const node = useSynapse();
+    const tasks = node.tasks;
+    const selectRef = useRef(select);
+    selectRef.current = select;
+    const subscribe = useCallback((cb) => {
+        const a = tasks.status.onChange(() => cb()), b = tasks.catalog.onChange(() => cb());
+        return () => { a(); b(); };
+    }, [tasks]);
+    const verbs = useMemo(() => ({
+        runRobotTasks: () => tasks.runRobotTasks(), stopRobotTasks: () => tasks.stopRobotTasks(),
+        runProjectTasks: () => tasks.runProjectTasks(), stopProjectTasks: () => tasks.stopProjectTasks(),
+    }), [tasks]);
+    const view = useRef(undefined);
     const last = useRef(undefined);
-    const subscribe = useCallback((cb) => (scene ? scene.subscribe(cb) : () => { }), [scene]);
     const get = useCallback(() => {
-        if (!scene)
-            return undefined;
-        const s = scene.status;
-        if (!shallowEqual(last.current, s))
-            last.current = s;
-        return last.current;
-    }, [scene]);
+        const status = tasks.status.get(), catalog = tasks.catalog.get(), synced = tasks.status.synced && tasks.catalog.synced;
+        const v = view.current;
+        const from = v && v.status === status && v.catalog === catalog && v.synced === synced ? v : (view.current = { status, catalog, synced, ...verbs });
+        const sel = selectRef.current;
+        if (!sel)
+            return from;
+        const prev = last.current;
+        if (prev && prev.from === from && prev.select === sel)
+            return prev.out;
+        const out = replaceEqualDeep(prev?.out, sel(from));
+        last.current = { from, select: sel, out };
+        return out;
+    }, [tasks, verbs]);
     return useSyncExternalStore(subscribe, get, get);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/react",
-  "version": "0.3.0",
+  "version": "0.3.4",
   "description": "Synapse SDK React hooks: connection, topics, calls, services, store.",
   "type": "module",
   "sideEffects": false,
@@ -14,8 +14,8 @@
     "dist"
   ],
   "dependencies": {
-    "@synapse-sdk/core": "0.3.0",
-    "@synapse-sdk/client": "0.3.0"
+    "@synapse-sdk/core": "0.3.4",
+    "@synapse-sdk/client": "0.3.4"
   },
   "peerDependencies": {
     "react": ">=18"