@vizij/runtime-react 0.0.1

package/README.md

@@ -0,0 +1,146 @@
+# @vizij/runtime-react
+
+High-level runtime harness that combines the Vizij renderer with orchestrator controllers for React apps. Drop in an asset bundle and the provider wires loading, orchestration, and rendering for you.
+
+> **Status:** experimental. Surface area may change ahead of the first stable release.
+
+## Installation
+
+```bash
+pnpm add @vizij/runtime-react @vizij/render @vizij/orchestrator-react react react-dom
+```
+
+Those three Vizij packages must stay in lock-step; always upgrade them together.
+
+## Getting Started
+
+```tsx
+import {
+  VizijRuntimeFace,
+  VizijRuntimeProvider,
+  useVizijRuntime,
+} from "@vizij/runtime-react";
+
+import rigGraph from "./rig.graph.json";
+
+const assetBundle = {
+  namespace: "demo",
+  glb: { kind: "url", src: new URL("./face.glb", import.meta.url).href },
+  rig: { id: "rig:demo", spec: rigGraph },
+  initialInputs: {
+    "pose/blinkLeft": { float: 0.2 },
+    "pose/blinkRight": { float: 0.2 },
+  },
+};
+
+export function App() {
+  return (
+    <VizijRuntimeProvider assetBundle={assetBundle} autostart>
+      <RuntimeHud />
+      <VizijRuntimeFace />
+    </VizijRuntimeProvider>
+  );
+}
+
+function RuntimeHud() {
+  const { loading, error, namespace } = useVizijRuntime();
+  if (loading) return <p>Loading bundle...</p>;
+  if (error) return <p>Failed to load runtime: {error.message}</p>;
+  return <p>Runtime online for namespace {namespace}</p>;
+}
+```
+
+The provider creates a renderer store, boots the orchestrator, registers the supplied bundle, then renders the face once bounds are available.
+
+## Asset Bundle Anatomy
+
+`VizijRuntimeProvider` expects a `VizijAssetBundle`:
+
+- `glb`: required. Either `{ kind: "url", src }`, `{ kind: "blob", blob }`, or `{ kind: "world", world, animatables }`. URL/blob variants can opt into `aggressiveImport` for tooling builds and provide `rootBounds` overrides when the GLB lacks metadata.
+- `rig`: required. Graph specification describing inputs/outputs for the orchestrator (`id` must be unique within the namespace).
+- `pose`: optional. Supply authoring pose graph/config so the runtime can neutralise the rig before you drive it.
+- `animations`: optional array. Each item defines channels that map to runtime input paths. Use `playAnimation` to trigger them.
+- `initialInputs`: optional map of ValueJSON that seeds inputs before autostart.
+- `metadata`: free-form dictionary you can read back through `useVizijRuntime().assetBundle.metadata`.
+
+Namespace defaults to `assetBundle.namespace ?? "default"`. Face id falls back to the bundle pose config when omitted.
+
+## Provider Props
+
+- `assetBundle`: bundle described above.
+- `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.
+- `mergeStrategy`: orchestrator merge strategy, defaults to additive for outputs/intermediate values.
+- `onRegisterControllers(ids)`: observe graph and animation controller ids that were registered.
+- `onStatusChange(status)`: gets every status update (loading events, errors, controller updates).
+
+The provider exposes context via `useVizijRuntime()` once `loading` flips to `false`.
+
+## Hooks and Helpers
+
+- `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.
+  - `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.
+  - `animateValue(path, target, options)`, `cancelAnimation(path)`: tween rig values with built-in easing.
+  - `playAnimation(id, options)`, `stopAnimation(id)`: drive bundle animations that were provided in `animations`.
+  - `step(dt)` / `advanceAnimations(dt)`: manually tick the orchestrator if you run outside `autostart`.
+- `useRigInput(path)`: returns `[value, setter]` for a single rig input. The setter writes through the orchestrator while the value mirrors the renderer store.
+- `useVizijOutputs(paths)`: subscribes to renderer output paths (`RawValue` map) for UI or logging.
+- `registerInputDriver(id, factory)`: attach custom drivers (speech-to-anim, sensors). The factory receives `setInput` and `setRendererValue` helpers and must return `{ start, stop, dispose }`.
+
+## Components
+
+- `<VizijRuntimeFace />`: renders a `<Vizij>` once `rootId` is known. Pass any renderer props (camera controls, overlays, etc.). Use `namespaceOverride` to inspect another namespace while keeping the runtime context intact.
+- Compose your own UI with the renderer primitives exported from `@vizij/render`. The runtime only handles wiring and state.
+
+## Error Handling
+
+Errors are captured with phase metadata. `status.error` is the most recent failure; `status.errors` keeps history for observability panels. Typical phases:
+
+- `assets`: bundle loading issues (bad GLB URL, malformed rig spec).
+- `registration`: orchestrator graph registration problems.
+- `driver`: input driver lifecycle exceptions.
+- `animation`: failures while sampling clip tracks.
+
+Watch `onStatusChange` for realtime updates and implement retries or fallbacks in your UI.
+
+## Working With Animations
+
+Animations are defined alongside rig inputs. Each track maps to an input path (`animation/<id>/<channel>`). When `playAnimation` runs, the runtime schedules frames and writes values back through the orchestrator merge strategy. Use `options.reset` to restart clips, `options.weight` to blend multiple clips, and `stopAnimation` to cut a clip immediately.
+
+For ad-hoc gestures, use `animateValue` with duration/easing. If you need custom easing, pass a function `(t) => number`.
+
+## Asset Bundling Workflow
+
+1. Export an authoring scene to GLB with Vizij metadata intact (bounds, animatable ids).
+2. Export orchestrator graphs (rig, pose, optional animation graphs) to JSON.
+3. Package everything under a namespace in a `VizijAssetBundle`.
+4. Host GLB URLs or include them via bundler asset imports (`new URL("./face.glb", import.meta.url).href`).
+
+The runtime tolerates incremental bundles; swap `assetBundle` props to hot-reload assets in dev builds.
+
+## Development Scripts
+
+```bash
+pnpm --filter "@vizij/runtime-react" build      # tsup compile to dist/
+pnpm --filter "@vizij/runtime-react" test       # vitest
+pnpm --filter "@vizij/runtime-react" typecheck  # tsc --noEmit
+pnpm --filter "@vizij/runtime-react" lint       # eslint
+pnpm --filter "@vizij/runtime-react" dev        # tsup watch build
+```
+
+Changes to orchestrator or renderer packages often require coordinated updates here; run the fullscreen tutorial app (`apps/tutorial-fullscreen-face`) to validate.
+
+## Publishing
+
+When ready to publish:
+
+1. `pnpm changeset` and follow the prompts.
+2. `pnpm version:packages` and `pnpm install` to sync lockfiles.
+3. Build, test, and pack the runtime filter (`pnpm --filter "@vizij/runtime-react" build`, `pnpm --filter "@vizij/runtime-react" test`, `pnpm --filter "@vizij/runtime-react" exec npm pack --dry-run`).
+4. Push a tag named `npm-runtime-react-vX.Y.Z`. The shared GitHub Action handles `npm publish`.

package/dist/index.d.mts

@@ -0,0 +1,176 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, PropsWithChildren } from 'react';
+import { GraphRegistrationConfig, GraphSubscriptions, AnimationSetup, ValueJSON, CreateOrchOptions, MergeStrategyOptions, ShapeJSON } from '@vizij/orchestrator-react';
+import { AnimatableValue, RawValue } from '@vizij/utils';
+import { World, VizijProps } from '@vizij/render';
+
+type PoseDefinition = {
+    id: string;
+    name?: string;
+    description?: string;
+    values: Record<string, number | undefined>;
+};
+type PoseRigConfig = {
+    version: number;
+    faceId?: string | null;
+    title?: string;
+    description?: string;
+    neutralInputs: Record<string, number>;
+    poses: PoseDefinition[];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type RootBounds = {
+    center: {
+        x: number;
+        y: number;
+    };
+    size: {
+        x: number;
+        y: number;
+    };
+};
+type VizijGlbAsset = {
+    kind: "url";
+    src: string;
+    aggressiveImport?: boolean;
+    rootBounds?: RootBounds;
+} | {
+    kind: "blob";
+    blob: Blob;
+    aggressiveImport?: boolean;
+    rootBounds?: RootBounds;
+} | {
+    kind: "world";
+    world: World;
+    animatables: Record<string, AnimatableValue>;
+};
+type VizijGraphAsset = {
+    id: string;
+    spec: GraphRegistrationConfig["spec"];
+    subscriptions?: Partial<GraphSubscriptions>;
+};
+type AnimationKeyframeLike = {
+    time?: number;
+    value?: number;
+};
+type AnimationTrackLike = {
+    channel: string;
+    keyframes?: AnimationKeyframeLike[];
+};
+type AnimationClipLike = {
+    id?: string;
+    name?: string;
+    duration?: number;
+    tracks?: AnimationTrackLike[];
+    [key: string]: unknown;
+};
+type VizijAnimationAsset = {
+    id: string;
+    clip: AnimationClipLike;
+    setup?: Partial<AnimationSetup>;
+    weight?: number;
+};
+type VizijAssetBundle = {
+    namespace?: string;
+    faceId?: string;
+    glb: VizijGlbAsset;
+    rig: VizijGraphAsset;
+    pose?: {
+        graph?: VizijGraphAsset;
+        config?: PoseRigConfig;
+        stageNeutralFilter?: (id: string, path: string) => boolean;
+    };
+    animations?: VizijAnimationAsset[];
+    initialInputs?: Record<string, ValueJSON>;
+    metadata?: Record<string, unknown>;
+};
+type RuntimeError = {
+    message: string;
+    cause?: unknown;
+    phase?: "assets" | "orchestrator" | "registration" | "animation" | "bridge" | "driver" | "unknown";
+    timestamp: number;
+};
+type VizijRuntimeStatus = {
+    loading: boolean;
+    ready: boolean;
+    error: RuntimeError | null;
+    errors: RuntimeError[];
+    namespace: string;
+    faceId?: string;
+    rootId?: string | null;
+    outputPaths: string[];
+    controllers: {
+        graphs: string[];
+        anims: string[];
+    };
+};
+type AnimateValueOptions = {
+    duration?: number;
+    easing?: ((t: number) => number) | "linear" | "easeInOut" | "easeOut" | "easeIn";
+    namespace?: string;
+    coordinate?: "input" | "renderer";
+};
+type PlayAnimationOptions = {
+    weight?: number;
+    speed?: number;
+    reset?: boolean;
+};
+type InputDriverLifecycle = {
+    start: () => void;
+    stop: () => void;
+    dispose: () => void;
+};
+type InputDriverContext = {
+    setInput: (path: string, value: ValueJSON, shape?: ShapeJSON) => void;
+    setRendererValue: (id: string, namespace: string, value: RawValue | ((prev: RawValue | undefined) => RawValue | undefined)) => void;
+    namespace: string;
+    faceId?: string;
+};
+type InputDriverFactory = (ctx: InputDriverContext) => InputDriverLifecycle;
+type VizijRuntimeFaceProps = Omit<VizijProps, "rootId" | "namespace"> & {
+    namespaceOverride?: string;
+};
+type VizijRuntimeContextValue = VizijRuntimeStatus & {
+    assetBundle: VizijAssetBundle;
+    setInput: (path: string, value: ValueJSON, shape?: ShapeJSON) => void;
+    setValue: (id: string, namespace: string, value: RawValue | ((prev: RawValue | undefined) => RawValue | undefined)) => void;
+    stagePoseNeutral: (force?: boolean) => void;
+    animateValue: (path: string, target: ValueJSON, options?: AnimateValueOptions) => Promise<void>;
+    cancelAnimation: (path: string) => void;
+    registerInputDriver: (id: string, factory: InputDriverFactory) => InputDriverLifecycle;
+    playAnimation: (id: string, options?: PlayAnimationOptions) => Promise<void>;
+    stopAnimation: (id: string) => void;
+    step: (dt: number) => void;
+    advanceAnimations: (dt: number) => void;
+};
+type VizijRuntimeProviderProps = {
+    assetBundle: VizijAssetBundle;
+    children: ReactNode;
+    namespace?: string;
+    faceId?: string;
+    autoCreate?: boolean;
+    createOptions?: CreateOrchOptions;
+    autostart?: boolean;
+    mergeStrategy?: MergeStrategyOptions;
+    onRegisterControllers?: (ids: {
+        graphs: string[];
+        anims: string[];
+    }) => void;
+    onStatusChange?: (status: VizijRuntimeStatus) => void;
+};
+
+type ProviderProps = PropsWithChildren<VizijRuntimeProviderProps>;
+declare function VizijRuntimeProvider({ assetBundle, children, namespace: namespaceProp, faceId: faceIdProp, autoCreate, createOptions, autostart, mergeStrategy, onRegisterControllers, onStatusChange, }: ProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function VizijRuntimeFaceInner({ namespaceOverride, ...props }: VizijRuntimeFaceProps): react_jsx_runtime.JSX.Element | null;
+declare const VizijRuntimeFace: react.MemoExoticComponent<typeof VizijRuntimeFaceInner>;
+
+declare function useVizijRuntime(): VizijRuntimeContextValue;
+
+declare function useVizijOutputs(paths: string[]): Record<string, RawValue | undefined>;
+
+declare function useRigInput(path: string): [RawValue | undefined, (value: ValueJSON, shape?: ShapeJSON) => void];
+
+export { type AnimateValueOptions, type AnimationClipLike, type AnimationKeyframeLike, type AnimationTrackLike, type InputDriverContext, type InputDriverFactory, type InputDriverLifecycle, type PlayAnimationOptions, type PoseDefinition, type PoseRigConfig, type RootBounds, type VizijAnimationAsset, type VizijAssetBundle, type VizijGlbAsset, type VizijGraphAsset, VizijRuntimeFace, type VizijRuntimeFaceProps, VizijRuntimeProvider, type VizijRuntimeProviderProps, type VizijRuntimeStatus, useRigInput, useVizijOutputs, useVizijRuntime };

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, PropsWithChildren } from 'react';
+import { GraphRegistrationConfig, GraphSubscriptions, AnimationSetup, ValueJSON, CreateOrchOptions, MergeStrategyOptions, ShapeJSON } from '@vizij/orchestrator-react';
+import { AnimatableValue, RawValue } from '@vizij/utils';
+import { World, VizijProps } from '@vizij/render';
+
+type PoseDefinition = {
+    id: string;
+    name?: string;
+    description?: string;
+    values: Record<string, number | undefined>;
+};
+type PoseRigConfig = {
+    version: number;
+    faceId?: string | null;
+    title?: string;
+    description?: string;
+    neutralInputs: Record<string, number>;
+    poses: PoseDefinition[];
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type RootBounds = {
+    center: {
+        x: number;
+        y: number;
+    };
+    size: {
+        x: number;
+        y: number;
+    };
+};
+type VizijGlbAsset = {
+    kind: "url";
+    src: string;
+    aggressiveImport?: boolean;
+    rootBounds?: RootBounds;
+} | {
+    kind: "blob";
+    blob: Blob;
+    aggressiveImport?: boolean;
+    rootBounds?: RootBounds;
+} | {
+    kind: "world";
+    world: World;
+    animatables: Record<string, AnimatableValue>;
+};
+type VizijGraphAsset = {
+    id: string;
+    spec: GraphRegistrationConfig["spec"];
+    subscriptions?: Partial<GraphSubscriptions>;
+};
+type AnimationKeyframeLike = {
+    time?: number;
+    value?: number;
+};
+type AnimationTrackLike = {
+    channel: string;
+    keyframes?: AnimationKeyframeLike[];
+};
+type AnimationClipLike = {
+    id?: string;
+    name?: string;
+    duration?: number;
+    tracks?: AnimationTrackLike[];
+    [key: string]: unknown;
+};
+type VizijAnimationAsset = {
+    id: string;
+    clip: AnimationClipLike;
+    setup?: Partial<AnimationSetup>;
+    weight?: number;
+};
+type VizijAssetBundle = {
+    namespace?: string;
+    faceId?: string;
+    glb: VizijGlbAsset;
+    rig: VizijGraphAsset;
+    pose?: {
+        graph?: VizijGraphAsset;
+        config?: PoseRigConfig;
+        stageNeutralFilter?: (id: string, path: string) => boolean;
+    };
+    animations?: VizijAnimationAsset[];
+    initialInputs?: Record<string, ValueJSON>;
+    metadata?: Record<string, unknown>;
+};
+type RuntimeError = {
+    message: string;
+    cause?: unknown;
+    phase?: "assets" | "orchestrator" | "registration" | "animation" | "bridge" | "driver" | "unknown";
+    timestamp: number;
+};
+type VizijRuntimeStatus = {
+    loading: boolean;
+    ready: boolean;
+    error: RuntimeError | null;
+    errors: RuntimeError[];
+    namespace: string;
+    faceId?: string;
+    rootId?: string | null;
+    outputPaths: string[];
+    controllers: {
+        graphs: string[];
+        anims: string[];
+    };
+};
+type AnimateValueOptions = {
+    duration?: number;
+    easing?: ((t: number) => number) | "linear" | "easeInOut" | "easeOut" | "easeIn";
+    namespace?: string;
+    coordinate?: "input" | "renderer";
+};
+type PlayAnimationOptions = {
+    weight?: number;
+    speed?: number;
+    reset?: boolean;
+};
+type InputDriverLifecycle = {
+    start: () => void;
+    stop: () => void;
+    dispose: () => void;
+};
+type InputDriverContext = {
+    setInput: (path: string, value: ValueJSON, shape?: ShapeJSON) => void;
+    setRendererValue: (id: string, namespace: string, value: RawValue | ((prev: RawValue | undefined) => RawValue | undefined)) => void;
+    namespace: string;
+    faceId?: string;
+};
+type InputDriverFactory = (ctx: InputDriverContext) => InputDriverLifecycle;
+type VizijRuntimeFaceProps = Omit<VizijProps, "rootId" | "namespace"> & {
+    namespaceOverride?: string;
+};
+type VizijRuntimeContextValue = VizijRuntimeStatus & {
+    assetBundle: VizijAssetBundle;
+    setInput: (path: string, value: ValueJSON, shape?: ShapeJSON) => void;
+    setValue: (id: string, namespace: string, value: RawValue | ((prev: RawValue | undefined) => RawValue | undefined)) => void;
+    stagePoseNeutral: (force?: boolean) => void;
+    animateValue: (path: string, target: ValueJSON, options?: AnimateValueOptions) => Promise<void>;
+    cancelAnimation: (path: string) => void;
+    registerInputDriver: (id: string, factory: InputDriverFactory) => InputDriverLifecycle;
+    playAnimation: (id: string, options?: PlayAnimationOptions) => Promise<void>;
+    stopAnimation: (id: string) => void;
+    step: (dt: number) => void;
+    advanceAnimations: (dt: number) => void;
+};
+type VizijRuntimeProviderProps = {
+    assetBundle: VizijAssetBundle;
+    children: ReactNode;
+    namespace?: string;
+    faceId?: string;
+    autoCreate?: boolean;
+    createOptions?: CreateOrchOptions;
+    autostart?: boolean;
+    mergeStrategy?: MergeStrategyOptions;
+    onRegisterControllers?: (ids: {
+        graphs: string[];
+        anims: string[];
+    }) => void;
+    onStatusChange?: (status: VizijRuntimeStatus) => void;
+};
+
+type ProviderProps = PropsWithChildren<VizijRuntimeProviderProps>;
+declare function VizijRuntimeProvider({ assetBundle, children, namespace: namespaceProp, faceId: faceIdProp, autoCreate, createOptions, autostart, mergeStrategy, onRegisterControllers, onStatusChange, }: ProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function VizijRuntimeFaceInner({ namespaceOverride, ...props }: VizijRuntimeFaceProps): react_jsx_runtime.JSX.Element | null;
+declare const VizijRuntimeFace: react.MemoExoticComponent<typeof VizijRuntimeFaceInner>;
+
+declare function useVizijRuntime(): VizijRuntimeContextValue;
+
+declare function useVizijOutputs(paths: string[]): Record<string, RawValue | undefined>;
+
+declare function useRigInput(path: string): [RawValue | undefined, (value: ValueJSON, shape?: ShapeJSON) => void];
+
+export { type AnimateValueOptions, type AnimationClipLike, type AnimationKeyframeLike, type AnimationTrackLike, type InputDriverContext, type InputDriverFactory, type InputDriverLifecycle, type PlayAnimationOptions, type PoseDefinition, type PoseRigConfig, type RootBounds, type VizijAnimationAsset, type VizijAssetBundle, type VizijGlbAsset, type VizijGraphAsset, VizijRuntimeFace, type VizijRuntimeFaceProps, VizijRuntimeProvider, type VizijRuntimeProviderProps, type VizijRuntimeStatus, useRigInput, useVizijOutputs, useVizijRuntime };