@vizij/runtime-react 0.0.14 → 0.1.0

package/README.md

@@ -73,6 +73,10 @@ function RuntimeHud() {
 
 The provider creates a renderer store, boots the orchestrator, registers the supplied bundle, then renders the face once bounds are available.
 
+### Sharing one orchestrator across multiple faces
+
+Wrap your app in a single `<OrchestratorProvider>` and give each `VizijRuntimeProvider` a unique `namespace`. The runtime will automatically reuse a parent orchestrator provider (instead of spinning up one per face), prefix graph inputs/outputs with that namespace inside the wasm blackboard, and strip the prefix again before values reach the renderer store. Set `orchestratorScope="shared"` when you want to enforce reuse; leave it at the default `"auto"` to reuse when available and fall back to an isolated provider otherwise.
+
 ## Asset Bundle Anatomy
 
 `VizijRuntimeProvider` expects a `VizijAssetBundle`:
@@ -93,10 +97,14 @@ Namespace defaults to `assetBundle.namespace ?? "default"`. Face id falls back t
 - `namespace` / `faceId`: override bundle values to reuse the same assets under multiple namespaces or faces.
 - `autoCreate` + `createOptions`: forwarded to `OrchestratorProvider`. Leave `autoCreate` enabled unless you need manual control over WASM creation.
 - `autostart`: when true, the orchestrator starts ticking as soon as assets register.
+- `driveOrchestrator`: defaults to `true`. In shared orchestrator setups, set this to `false` on non-driver runtimes so only one loop calls `stepRuntime` while others continue to stage inputs/animations.
 - `mergeStrategy`: orchestrator merge strategy, defaults to additive for outputs/intermediate values.
+- `orchestratorScope`: control orchestrator reuse. `"auto"` (default) reuses a parent `OrchestratorProvider` when present, `"shared"` requires one, and `"isolated"` always spins up a dedicated instance.
 - `onRegisterControllers(ids)`: observe graph and animation controller ids that were registered.
 - `onStatusChange(status)`: gets every status update (loading events, errors, controller updates).
 
+Inputs are staged in a per-frame buffer and flushed together before each `step()`, minimizing wasm boundary crossings even when multiple drivers write in the same tick.
+
 The provider exposes context via `useVizijRuntime()` once `loading` flips to `false`.
 
 ## Hooks and Helpers
@@ -104,7 +112,7 @@ The provider exposes context via `useVizijRuntime()` once `loading` flips to `fa
 - `useVizijRuntime()`: returns the full runtime context (status, setters, animation helpers, and the original asset bundle). Common properties:
   - `loading`, `ready`, `error`, `errors`: lifecycle state.
   - `namespace`, `faceId`, `rootId`: resolved IDs the renderer/orchestrator share.
-  - `outputPaths`: list of output signal paths detected in the registered graphs.
+  - `outputPaths`: namespaced output signal paths detected in the registered graphs (matches orchestrator write keys).
   - `controllers`: `{ graphs, anims }` that were installed.
   - `setInput(path, value)`, `setValue(id, namespace, value)`: talk directly to the orchestrator or renderer store.
   - `stagePoseNeutral(force)`: restore the neutral pose captured at export.