@vizij/runtime-react 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,11 +1,39 @@
 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 { ValueJSON } from '@vizij/value-json';
 import { IrGraph } from '@vizij/node-graph-authoring';
-import { AnimatableValue, RawValue } from '@vizij/utils';
+import { RawValue, AnimatableValue } from '@vizij/utils';
 import { World, VizijBundleExtension, VizijProps } from '@vizij/render';
 
+/** Value shape hint. Accepted through the public surface, unused by the device. */
+type ShapeJSON = Record<string, unknown>;
+/** Paths a graph reads/writes — metadata for output tracking and seeding. */
+type GraphSubscriptions = {
+    inputs?: string[];
+    outputs?: string[];
+};
+/** A Vizij graph spec handled structurally (nodes/edges arrays of records). */
+type GraphSpecLike = {
+    nodes?: Array<Record<string, unknown>>;
+    edges?: Array<Record<string, unknown>>;
+    metadata?: unknown;
+    [key: string]: unknown;
+};
+/** One graph source composed into the device's behavior. */
+type GraphRegistrationConfig = {
+    id?: string;
+    spec: GraphSpecLike;
+    subs?: GraphSubscriptions;
+};
+/** Per-source merge options. Composition is last-writer-wins today (VIZ-53). */
+type MergeStrategyOptions = Record<string, unknown>;
+/** Player/instance setup carried by animation assets; consumed by the JS clip pipeline. */
+type AnimationSetup = {
+    animation?: unknown;
+    player?: Record<string, unknown>;
+    instance?: Record<string, unknown>;
+};
 type PoseDefinition = {
     id: string;
     name?: string;
@@ -135,7 +163,7 @@ type VizijAssetBundle = {
 type RuntimeError = {
     message: string;
     cause?: unknown;
-    phase?: "assets" | "orchestrator" | "registration" | "animation" | "bridge" | "driver" | "unknown";
+    phase?: "assets" | "engine" | "registration" | "animation" | "bridge" | "driver" | "unknown";
     timestamp: number;
 };
 type VizijRuntimeStatus = {
@@ -206,6 +234,29 @@ type VizijRuntimeFaceProps = Omit<VizijProps, "rootId" | "namespace"> & {
 type VizijRuntimeContextValue = VizijRuntimeStatus & {
     assetBundle: VizijAssetBundle;
     setInput: (path: string, value: ValueJSON, shape?: ShapeJSON) => void;
+    /** Current engine-store value of a path (read-your-own-write included). */
+    getValueSnapshot: (path: string) => ValueJSON | undefined;
+    /**
+     * A snapshot of EVERY key currently in the device store, as path → Value in
+     * arora's serde JSON shape (pass-through from the device; not `ValueJSON`).
+     * `undefined` until the device exists. For mirrors/bridges that forward the
+     * whole store (e.g. the standalone's native-store bridge), not for per-path
+     * sampling — use `getValueSnapshot` for that.
+     */
+    getStoreSnapshot: () => Record<string, unknown> | undefined;
+    /**
+     * Notifies with each step's drained store changes (path → Value in arora's
+     * serde JSON shape; `null` for a cleared key). The change-driven counterpart
+     * to `getStoreSnapshot` for store bridges: seed from the snapshot, then stay
+     * current from these. Returns an unsubscribe function.
+     */
+    subscribeToStoreChanges: (listener: (changes: Record<string, unknown>) => void) => () => void;
+    /**
+     * Notifies after each engine step, once the step's store changes have been
+     * applied. Pair with `getValueSnapshot` to sample values step-aligned.
+     * Returns an unsubscribe function.
+     */
+    subscribeToStep: (listener: () => void) => () => void;
     setGraphBundle: (bundle: RuntimeGraphBundle, options?: {
         tier?: "auto" | "assets" | "graphs";
     }) => void;
@@ -229,7 +280,6 @@ type VizijRuntimeContextValue = VizijRuntimeStatus & {
     step: (dt: number, opts?: {
         forceRuntime?: boolean;
     }) => void;
-    advanceAnimations: (dt: number) => void;
     inputConstraints: Record<string, {
         min?: number;
         max?: number;
@@ -243,9 +293,15 @@ type VizijRuntimeProviderProps = {
     faceId?: string;
     updateTier?: RuntimeUpdateTier;
     autoCreate?: boolean;
-    createOptions?: CreateOrchOptions;
     autostart?: boolean;
-    driveOrchestrator?: boolean;
+    /**
+     * Whether this provider's device paces itself: when true the device is
+     * handed to its own `run()` loop at boot and the provider only pumps its
+     * changes; when false the device advances solely on `step(dt,
+     * { forceRuntime: true })` calls from the host. A device handed to `run()`
+     * keeps its loop even if this later turns false.
+     */
+    driveRuntime?: boolean;
     mergeStrategy?: MergeStrategyOptions;
     onRegisterControllers?: (ids: {
         graphs: string[];
@@ -253,7 +309,6 @@ type VizijRuntimeProviderProps = {
     }) => void;
     onStatusChange?: (status: VizijRuntimeStatus) => void;
     transformOutputWrite?: (write: RuntimeOutputWrite) => RuntimeOutputWrite | null;
-    orchestratorScope?: "auto" | "shared" | "isolated";
 };
 type RuntimeUpdateTier = "auto" | "assets" | "graphs";
 type RuntimeUpdatePlan = {
@@ -268,7 +323,7 @@ type RuntimeGraphBundle = {
 };
 
 type ProviderProps = PropsWithChildren<VizijRuntimeProviderProps>;
-declare function VizijRuntimeProvider({ assetBundle, children, namespace: namespaceProp, faceId: faceIdProp, updateTier, autoCreate, createOptions, autostart, driveOrchestrator, mergeStrategy, onRegisterControllers, onStatusChange, transformOutputWrite, orchestratorScope, }: ProviderProps): react_jsx_runtime.JSX.Element;
+declare function VizijRuntimeProvider({ assetBundle, children, namespace: namespaceProp, faceId: faceIdProp, updateTier, autoCreate, autostart, driveRuntime, mergeStrategy, onRegisterControllers, onStatusChange, transformOutputWrite, }: 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>;

package/dist/index.d.ts

@@ -1,11 +1,39 @@
 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 { ValueJSON } from '@vizij/value-json';
 import { IrGraph } from '@vizij/node-graph-authoring';
-import { AnimatableValue, RawValue } from '@vizij/utils';
+import { RawValue, AnimatableValue } from '@vizij/utils';
 import { World, VizijBundleExtension, VizijProps } from '@vizij/render';
 
+/** Value shape hint. Accepted through the public surface, unused by the device. */
+type ShapeJSON = Record<string, unknown>;
+/** Paths a graph reads/writes — metadata for output tracking and seeding. */
+type GraphSubscriptions = {
+    inputs?: string[];
+    outputs?: string[];
+};
+/** A Vizij graph spec handled structurally (nodes/edges arrays of records). */
+type GraphSpecLike = {
+    nodes?: Array<Record<string, unknown>>;
+    edges?: Array<Record<string, unknown>>;
+    metadata?: unknown;
+    [key: string]: unknown;
+};
+/** One graph source composed into the device's behavior. */
+type GraphRegistrationConfig = {
+    id?: string;
+    spec: GraphSpecLike;
+    subs?: GraphSubscriptions;
+};
+/** Per-source merge options. Composition is last-writer-wins today (VIZ-53). */
+type MergeStrategyOptions = Record<string, unknown>;
+/** Player/instance setup carried by animation assets; consumed by the JS clip pipeline. */
+type AnimationSetup = {
+    animation?: unknown;
+    player?: Record<string, unknown>;
+    instance?: Record<string, unknown>;
+};
 type PoseDefinition = {
     id: string;
     name?: string;
@@ -135,7 +163,7 @@ type VizijAssetBundle = {
 type RuntimeError = {
     message: string;
     cause?: unknown;
-    phase?: "assets" | "orchestrator" | "registration" | "animation" | "bridge" | "driver" | "unknown";
+    phase?: "assets" | "engine" | "registration" | "animation" | "bridge" | "driver" | "unknown";
     timestamp: number;
 };
 type VizijRuntimeStatus = {
@@ -206,6 +234,29 @@ type VizijRuntimeFaceProps = Omit<VizijProps, "rootId" | "namespace"> & {
 type VizijRuntimeContextValue = VizijRuntimeStatus & {
     assetBundle: VizijAssetBundle;
     setInput: (path: string, value: ValueJSON, shape?: ShapeJSON) => void;
+    /** Current engine-store value of a path (read-your-own-write included). */
+    getValueSnapshot: (path: string) => ValueJSON | undefined;
+    /**
+     * A snapshot of EVERY key currently in the device store, as path → Value in
+     * arora's serde JSON shape (pass-through from the device; not `ValueJSON`).
+     * `undefined` until the device exists. For mirrors/bridges that forward the
+     * whole store (e.g. the standalone's native-store bridge), not for per-path
+     * sampling — use `getValueSnapshot` for that.
+     */
+    getStoreSnapshot: () => Record<string, unknown> | undefined;
+    /**
+     * Notifies with each step's drained store changes (path → Value in arora's
+     * serde JSON shape; `null` for a cleared key). The change-driven counterpart
+     * to `getStoreSnapshot` for store bridges: seed from the snapshot, then stay
+     * current from these. Returns an unsubscribe function.
+     */
+    subscribeToStoreChanges: (listener: (changes: Record<string, unknown>) => void) => () => void;
+    /**
+     * Notifies after each engine step, once the step's store changes have been
+     * applied. Pair with `getValueSnapshot` to sample values step-aligned.
+     * Returns an unsubscribe function.
+     */
+    subscribeToStep: (listener: () => void) => () => void;
     setGraphBundle: (bundle: RuntimeGraphBundle, options?: {
         tier?: "auto" | "assets" | "graphs";
     }) => void;
@@ -229,7 +280,6 @@ type VizijRuntimeContextValue = VizijRuntimeStatus & {
     step: (dt: number, opts?: {
         forceRuntime?: boolean;
     }) => void;
-    advanceAnimations: (dt: number) => void;
     inputConstraints: Record<string, {
         min?: number;
         max?: number;
@@ -243,9 +293,15 @@ type VizijRuntimeProviderProps = {
     faceId?: string;
     updateTier?: RuntimeUpdateTier;
     autoCreate?: boolean;
-    createOptions?: CreateOrchOptions;
     autostart?: boolean;
-    driveOrchestrator?: boolean;
+    /**
+     * Whether this provider's device paces itself: when true the device is
+     * handed to its own `run()` loop at boot and the provider only pumps its
+     * changes; when false the device advances solely on `step(dt,
+     * { forceRuntime: true })` calls from the host. A device handed to `run()`
+     * keeps its loop even if this later turns false.
+     */
+    driveRuntime?: boolean;
     mergeStrategy?: MergeStrategyOptions;
     onRegisterControllers?: (ids: {
         graphs: string[];
@@ -253,7 +309,6 @@ type VizijRuntimeProviderProps = {
     }) => void;
     onStatusChange?: (status: VizijRuntimeStatus) => void;
     transformOutputWrite?: (write: RuntimeOutputWrite) => RuntimeOutputWrite | null;
-    orchestratorScope?: "auto" | "shared" | "isolated";
 };
 type RuntimeUpdateTier = "auto" | "assets" | "graphs";
 type RuntimeUpdatePlan = {
@@ -268,7 +323,7 @@ type RuntimeGraphBundle = {
 };
 
 type ProviderProps = PropsWithChildren<VizijRuntimeProviderProps>;
-declare function VizijRuntimeProvider({ assetBundle, children, namespace: namespaceProp, faceId: faceIdProp, updateTier, autoCreate, createOptions, autostart, driveOrchestrator, mergeStrategy, onRegisterControllers, onStatusChange, transformOutputWrite, orchestratorScope, }: ProviderProps): react_jsx_runtime.JSX.Element;
+declare function VizijRuntimeProvider({ assetBundle, children, namespace: namespaceProp, faceId: faceIdProp, updateTier, autoCreate, autostart, driveRuntime, mergeStrategy, onRegisterControllers, onStatusChange, transformOutputWrite, }: 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>;