@synapse-sdk/react 0.3.0 → 0.3.3

package/README.md

@@ -1,3 +1,65 @@
 # @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()`, `useTopic(t, { select })`, `useCall(svc)`, `useStart(svc)`, `useServe(svc, handler)`,
+`usePublisher(t)`, `useStore(name)`, `useScene()`, `useSceneEntity(scene, id, { select, plane })`, `useSceneTree(scene)`,
+`useSceneStatus(scene)` and `useTasks(select?)`. Every hook reads a value the node keeps current; none keeps its own
+copy.
+
+## Tasks
+
+`useTasks()` is one view: `status` (what runs, `node.tasks.status.value`), `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();
+```
+
+The node must be connected when the hook first renders (`node.tasks` throws `not_connected` before).
+
+## 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])`; `v.get()` | `useSceneEntity(scene, id, { 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.value` | `useStore(name)` (any change of the namespace) |
+| tasks | `node.tasks.status.value` | `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, Notice, ViewOptions, ViewState, Run, CallOptions, Publisher, ServeHandler, ServeOptions, Registration, StoreHandle, StoreOptions, SceneEntity, SceneEntityLive, 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;
@@ -102,3 +102,25 @@ export declare function useSceneEntity<S = SceneEntityLive | undefined>(scene: S
 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. */
 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()`.
+ * The provider's node must be connected (`node.tasks` throws `not_connected` before).
+ */
+export declare function useTasks(): TasksView;
+export declare function useTasks<S>(select: (t: TasksView) => S): S;

package/dist/index.js

@@ -371,3 +371,34 @@ export function useSceneStatus(scene) {
     }, [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.subscribe(cb), b = tasks.catalog.subscribe(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 get = useCallback(() => {
+        const status = tasks.status.value, catalog = tasks.catalog.value, 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.3",
   "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.3",
+    "@synapse-sdk/client": "0.3.3"
   },
   "peerDependencies": {
     "react": ">=18"