@vizij/runtime-react 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { ReactNode, PropsWithChildren } from 'react';
 import { ValueJSON } from '@vizij/value-json';
 import { IrGraph } from '@vizij/node-graph-authoring';
 import { RawValue, AnimatableValue } from '@vizij/utils';
-import { World, VizijBundleExtension, VizijProps } from '@vizij/render';
+import { World, VizijBundleExtension, VizijStarredItem, VizijProps } from '@vizij/render';
 
 /** Value shape hint. Accepted through the public surface, unused by the device. */
 type ShapeJSON = Record<string, unknown>;
@@ -156,6 +156,12 @@ type VizijAssetBundle = {
     };
     animations?: VizijAnimationAsset[];
     programs?: VizijProgramAsset[];
+    /**
+     * Designer-curated set of starred drivers/poses, resolved from the loaded
+     * bundle's `starred` section. References real functionality by stable id
+     * (driver = standard-input id, pose = pose id).
+     */
+    starred?: VizijStarredItem[];
     initialInputs?: Record<string, ValueJSON>;
     metadata?: Record<string, unknown>;
     bundle?: VizijBundleExtension | null;
@@ -394,4 +400,43 @@ declare function resolveFaceControls(assetBundle: VizijAssetBundle, runtimeFaceI
 declare function mapNormalizedControlValue(control: FaceScalarControl, normalizedValue: number): number;
 declare function mapUnitControlValue(control: FaceScalarControl, unitValue: number): number;
 
-export { type AnimateValueOptions, type AnimationClipLike, type AnimationKeyframeLike, type AnimationPlaybackState, type AnimationTrackLike, EMOTION_POSE_KEYS, EXPRESSIVE_EMOTION_POSE_KEYS, type FaceScalarControl, type InputDriverContext, type InputDriverFactory, type InputDriverLifecycle, POSE_WEIGHT_INPUT_PATH_PREFIX, type PlayAnimationOptions, type PoseDefinition, type PoseGroupDefinition, type PoseRigConfig, type ProgramPlaybackState, type RootBounds, type RuntimeGraphBundle, type RuntimeOutputWrite, type RuntimeUpdatePlan, type RuntimeUpdateTier, type StopProgramOptions, VISEME_POSE_KEYS, type VizijAnimationAsset, type VizijAssetBundle, type VizijGlbAsset, type VizijGraphAsset, type VizijProgramAsset, VizijRuntimeFace, type VizijRuntimeFaceProps, VizijRuntimeProvider, type VizijRuntimeProviderProps, type VizijRuntimeStatus, buildPoseWeightInputPathSegment, buildPoseWeightPathMap, buildPoseWeightRelativePath, buildRigInputPath, buildSemanticPoseWeightPathMap, filterPosesBySemanticKind, getPoseSemanticKey, mapNormalizedControlValue, mapUnitControlValue, normalizePoseSemanticKey, resolveFaceControls, resolvePoseMembership, resolvePoseSemantics, resolveRuntimeUpdatePlan, useOptionalVizijRuntime, useRigInput, useVizijOutputs, useVizijRuntime };
+/**
+ * Compose several Vizij graph specs into the ONE graph an Arora device runs.
+ *
+ * The device runs a single ProcessingGraph as its behavior, so the separate
+ * graph sources become a union of nodes and edges here. Sources and their
+ * provenance (see `graphSourcesRef` in VizijRuntimeProvider for details):
+ * the **rig** graph shipped in the loaded GLB/asset bundle, the bundle's
+ * **pose-driver** graph, and one source per **playing program** (bundle
+ * programs and the authoring motiongraph, which publishes the editor's
+ * graph as a program). Node ids
+ * are prefixed `${sourceId}::` so sources can't collide; `params.path` is
+ * deliberately NOT prefixed — path identity on the device's shared store is
+ * the cross-graph contract (a pose output written to a store path is read by
+ * a rig input node with the same path on the next tick).
+ *
+ * Output-path collisions across sources (two `output` nodes writing one
+ * path) are warned and resolved last-writer-wins by evaluation order; there
+ * is no additive merge for that case yet, and current bundles don't collide.
+ * If a real bundle does, insert an explicit combiner node here instead of
+ * widening this warning.
+ */
+type SpecRecord = Record<string, unknown>;
+/** A graph spec treated structurally (same tolerance as `utils/graph.ts`). */
+type ComposableSpec = SpecRecord;
+interface GraphSource {
+    /** Stable id of the source graph (e.g. "rig", "pose", a program id). */
+    sourceId: string;
+    spec: ComposableSpec;
+}
+/**
+ * Union `sources` into one spec. Later sources evaluate after earlier ones,
+ * so on an output-path collision the last source wins (warned).
+ */
+declare function composeGraphSpecs(sources: GraphSource[]): ComposableSpec;
+
+declare function collectInputPathMap(spec: GraphRegistrationConfig["spec"]): Record<string, string>;
+
+declare function resolveAnimationBridgeOutputPaths(channel: string, faceId?: string, rigInputMap?: Record<string, string>): string[];
+
+export { type AnimateValueOptions, type AnimationClipLike, type AnimationKeyframeLike, type AnimationPlaybackState, type AnimationTrackLike, type ComposableSpec, EMOTION_POSE_KEYS, EXPRESSIVE_EMOTION_POSE_KEYS, type FaceScalarControl, type GraphSource, type InputDriverContext, type InputDriverFactory, type InputDriverLifecycle, POSE_WEIGHT_INPUT_PATH_PREFIX, type PlayAnimationOptions, type PoseDefinition, type PoseGroupDefinition, type PoseRigConfig, type ProgramPlaybackState, type RootBounds, type RuntimeGraphBundle, type RuntimeOutputWrite, type RuntimeUpdatePlan, type RuntimeUpdateTier, type StopProgramOptions, VISEME_POSE_KEYS, type VizijAnimationAsset, type VizijAssetBundle, type VizijGlbAsset, type VizijGraphAsset, type VizijProgramAsset, VizijRuntimeFace, type VizijRuntimeFaceProps, VizijRuntimeProvider, type VizijRuntimeProviderProps, type VizijRuntimeStatus, buildPoseWeightInputPathSegment, buildPoseWeightPathMap, buildPoseWeightRelativePath, buildRigInputPath, buildSemanticPoseWeightPathMap, collectInputPathMap, composeGraphSpecs, filterPosesBySemanticKind, getPoseSemanticKey, mapNormalizedControlValue, mapUnitControlValue, normalizePoseSemanticKey, resolveAnimationBridgeOutputPaths, resolveFaceControls, resolvePoseMembership, resolvePoseSemantics, resolveRuntimeUpdatePlan, useOptionalVizijRuntime, useRigInput, useVizijOutputs, useVizijRuntime };

package/dist/index.js

@@ -1443,7 +1443,7 @@ function fieldNumber(value) {
   if (!value || typeof value !== "object") {
     return null;
   }
-  for (const key of ["u64", "u32", "f32", "f64"]) {
+  for (const key of ["u64", "u32", "f32", "f64", "float"]) {
     if (key in value) {
       const parsed = Number(value[key]);
       return Number.isFinite(parsed) ? parsed : null;
@@ -1451,38 +1451,90 @@ function fieldNumber(value) {
   }
   return null;
 }
+function fieldText(value) {
+  if (!value || typeof value !== "object") {
+    return "";
+  }
+  const record = value;
+  for (const key of ["str", "text"]) {
+    if (typeof record[key] === "string") {
+      return record[key];
+    }
+  }
+  return "";
+}
+function playerStateFromFields(byId) {
+  const player = fieldNumber(byId.get(ANIMATION_MODULE_FIELD.statePlayer));
+  if (player === null) {
+    return null;
+  }
+  return {
+    player,
+    state: fieldText(byId.get(ANIMATION_MODULE_FIELD.stateState)),
+    time: (fieldNumber(byId.get(ANIMATION_MODULE_FIELD.stateTimeNs)) ?? 0) / 1e9,
+    duration: (fieldNumber(byId.get(ANIMATION_MODULE_FIELD.stateDurationNs)) ?? 0) / 1e9,
+    speed: fieldNumber(byId.get(ANIMATION_MODULE_FIELD.stateSpeed)) ?? 1
+  };
+}
+function fieldsToMap(fields) {
+  if (!Array.isArray(fields)) {
+    return null;
+  }
+  const byId = /* @__PURE__ */ new Map();
+  for (const entry of fields) {
+    const id = entry?.id;
+    const value = entry?.value;
+    if (typeof id === "string" && value && typeof value === "object") {
+      byId.set(id, value);
+    }
+  }
+  return byId;
+}
+function recordToMap(element) {
+  if (!element || typeof element !== "object") {
+    return null;
+  }
+  const record = element.record;
+  if (!record || typeof record !== "object" || Array.isArray(record)) {
+    return null;
+  }
+  const byId = /* @__PURE__ */ new Map();
+  for (const [id, value] of Object.entries(record)) {
+    if (value && typeof value === "object") {
+      byId.set(id, value);
+    }
+  }
+  return byId;
+}
 function decodePlayerStates(raw) {
-  if (!raw || typeof raw !== "object" || !("structs" in raw)) {
+  if (!raw || typeof raw !== "object") {
     return [];
   }
-  const structs = raw.structs;
-  const elements = Array.isArray(structs?.elements) ? structs.elements : [];
+  const container = raw;
   const states = [];
-  for (const element of elements) {
-    const fields = element?.fields;
-    if (!Array.isArray(fields)) {
-      continue;
-    }
-    const byId = /* @__PURE__ */ new Map();
-    for (const entry of fields) {
-      const id = entry?.id;
-      const value = entry?.value;
-      if (typeof id === "string" && value && typeof value === "object") {
-        byId.set(id, value);
+  const structs = container.structs;
+  if (structs && Array.isArray(structs.elements)) {
+    for (const element of structs.elements) {
+      const byId = fieldsToMap(element?.fields);
+      const state = byId ? playerStateFromFields(byId) : null;
+      if (state) {
+        states.push(state);
       }
     }
-    const player = fieldNumber(byId.get(ANIMATION_MODULE_FIELD.statePlayer));
-    if (player === null) {
-      continue;
+    return states;
+  }
+  const elements = Array.isArray(container.list) ? container.list : Array.isArray(container.array) ? container.array : null;
+  if (!elements) {
+    return states;
+  }
+  for (const element of elements) {
+    const byId = recordToMap(element) ?? fieldsToMap(
+      element?.struct?.fields ?? element?.fields
+    );
+    const state = byId ? playerStateFromFields(byId) : null;
+    if (state) {
+      states.push(state);
     }
-    const stateValue = byId.get(ANIMATION_MODULE_FIELD.stateState);
-    states.push({
-      player,
-      state: stateValue && "str" in stateValue ? String(stateValue.str) : "",
-      time: (fieldNumber(byId.get(ANIMATION_MODULE_FIELD.stateTimeNs)) ?? 0) / 1e9,
-      duration: (fieldNumber(byId.get(ANIMATION_MODULE_FIELD.stateDurationNs)) ?? 0) / 1e9,
-      speed: fieldNumber(byId.get(ANIMATION_MODULE_FIELD.stateSpeed)) ?? 1
-    });
   }
   return states;
 }
@@ -1552,6 +1604,7 @@ var AnimationModuleHost = class {
           speed: 1,
           loop: "loop",
           weight: 1,
+          pendingSeekSeconds: null,
           animId: null,
           playerId: null,
           instId: null
@@ -1590,6 +1643,8 @@ var AnimationModuleHost = class {
     }
     entry.playing = false;
     this.dispatch(
+      "pause",
+      clipId,
       (device) => entry.playerId !== null ? device.call(pauseCall(entry.playerId)) : null
     );
   }
@@ -1605,6 +1660,8 @@ var AnimationModuleHost = class {
     }
     entry.playing = false;
     this.dispatch(
+      "stop",
+      clipId,
       (device) => entry.playerId !== null ? device.call(stopCall(entry.playerId)) : null
     );
   }
@@ -1614,7 +1671,14 @@ var AnimationModuleHost = class {
     if (!entry) {
       return;
     }
+    if (entry.playerId === null) {
+      entry.pendingSeekSeconds = seconds;
+      return;
+    }
+    entry.pendingSeekSeconds = null;
     this.dispatch(
+      "seek",
+      clipId,
       (device) => entry.playerId !== null ? device.call(seekCall(entry.playerId, seconds * 1e9)) : null
     );
   }
@@ -1626,6 +1690,8 @@ var AnimationModuleHost = class {
     }
     entry.speed = speed;
     this.dispatch(
+      "set speed",
+      clipId,
       (device) => entry.playerId !== null ? device.call(setSpeedCall(entry.playerId, speed)) : null
     );
   }
@@ -1637,6 +1703,8 @@ var AnimationModuleHost = class {
     }
     entry.loop = mode;
     this.dispatch(
+      "set loop",
+      clipId,
       (device) => entry.playerId !== null ? device.call(setLoopCall(entry.playerId, mode)) : null
     );
   }
@@ -1648,6 +1716,8 @@ var AnimationModuleHost = class {
     }
     entry.weight = weight;
     this.dispatch(
+      "set weight",
+      clipId,
       (device) => entry.playerId !== null && entry.instId !== null ? device.call(setWeightCall(entry.playerId, entry.instId, weight)) : null
     );
   }
@@ -1655,6 +1725,9 @@ var AnimationModuleHost = class {
    * Re-issue setup and transport for every playing clip against a freshly
    * started device (module guest state did not survive the rebuild). Voids
    * stale ids first. Called from `DeviceSlot.onDeviceStarted`.
+   *
+   * A freshly loaded player advances without an explicit `play` — asserted by
+   * the rebuild case in `animationPipeline.device.test.ts`.
    */
   replayInto(device) {
     for (const entry of this.clips.values()) {
@@ -1667,12 +1740,35 @@ var AnimationModuleHost = class {
     }
   }
   /** Fire-and-forget a transport call against the live device, if any. */
-  dispatch(issue) {
+  /**
+   * Issue a transport call, reporting rather than swallowing a rejection.
+   *
+   * This used to discard the error on the assumption that the only cause was
+   * a rebuild racing the call, which `replayInto` would repair. When that is
+   * not the cause — the module missing from the live device, say — the call
+   * fails, the player keeps running, and the next frame of `player_states`
+   * feedback tells the transport UI it is still playing. The button flips
+   * back and the pause looks like it did nothing, with nothing anywhere
+   * saying why. Whatever the cause, a dropped transport command is worth a
+   * line in the console.
+   */
+  dispatch(what, clipId, issue) {
     const device = this.getDevice();
     if (!device) {
       return;
     }
-    void issue(device)?.catch(() => {
+    const issued = issue(device);
+    if (!issued) {
+      console.warn(
+        `[vizij-runtime] animation ${what} had no player to act on for "${clipId}"`
+      );
+      return;
+    }
+    void issued.catch((err) => {
+      console.warn(
+        `[vizij-runtime] animation ${what} was dropped for "${clipId}"`,
+        err
+      );
     });
   }
   async ensureLoaded(device, entry) {
@@ -1710,6 +1806,12 @@ var AnimationModuleHost = class {
           setWeightCall(entry.playerId, entry.instId, entry.weight)
         );
       }
+      if (entry.pendingSeekSeconds !== null) {
+        followups.push(
+          seekCall(entry.playerId, entry.pendingSeekSeconds * 1e9)
+        );
+        entry.pendingSeekSeconds = null;
+      }
     }
     for (const call of followups) {
       await device.call(call);
@@ -2290,6 +2392,23 @@ function convertBundlePrograms(entries) {
     };
   }).filter(Boolean);
 }
+function convertBundleStarred(section) {
+  const items = section?.items;
+  if (!Array.isArray(items) || items.length === 0) {
+    return void 0;
+  }
+  const resolved = [];
+  for (const item of items) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const { kind, id } = item;
+    if ((kind === "driver" || kind === "pose") && typeof id === "string" && id) {
+      resolved.push({ kind, id });
+    }
+  }
+  return resolved.length > 0 ? resolved : void 0;
+}
 function resolveConstraintDefault(path, namespace, inputConstraints) {
   const trimmed = path.trim();
   if (!trimmed) {
@@ -2447,6 +2566,12 @@ function mergeAssetBundle(base, extracted, extractedAnimations) {
     hasBaseProgramsOverride,
     convertBundlePrograms(resolvedBundle?.graphs)
   );
+  const hasBaseStarredOverride = Object.prototype.hasOwnProperty.call(
+    base,
+    "starred"
+  );
+  const starredFromBundle = convertBundleStarred(resolvedBundle?.starred);
+  const resolvedStarred = hasBaseStarredOverride ? base.starred : base.starred ?? starredFromBundle;
   const merged = {
     ...base
   };
@@ -2458,6 +2583,7 @@ function mergeAssetBundle(base, extracted, extractedAnimations) {
   merged.pose = resolvedPose;
   merged.animations = resolvedAnimations;
   merged.programs = programsFromBundle;
+  merged.starred = resolvedStarred;
   merged.bundle = resolvedBundle;
   return merged;
 }
@@ -2746,6 +2872,8 @@ function VizijRuntimeProviderInner({
   const animationModuleRef = useRef(null);
   const animationHostRef = useRef(null);
   const animationsSourceRegisteredRef = useRef(false);
+  const lastRegisteredModuleRevisionRef = useRef(0);
+  const lastBehaviorErrorRef = useRef(void 0);
   const animationGapWarnedRef = useRef(/* @__PURE__ */ new Set());
   const animationSystemActiveRef = useRef(true);
   const stagedInputsRef = useRef(/* @__PURE__ */ new Map());
@@ -2972,14 +3100,15 @@ function VizijRuntimeProviderInner({
       return null;
     }
     if (!animationHostRef.current) {
-      animationHostRef.current = new AnimationModuleHost(
-        getDevice,
-        (key) => resolveAnimationBridgeOutputPaths(
+      animationHostRef.current = new AnimationModuleHost(getDevice, (key) => {
+        const namespace2 = namespaceRef.current;
+        const resolved = resolveAnimationBridgeOutputPaths(
           key,
           faceIdRef.current ?? void 0,
           rigInputMapRef.current
-        )
-      );
+        ).map((path) => namespaceTypedPath(path, namespace2));
+        return [...new Set(resolved)];
+      });
     }
     return animationHostRef.current;
   }, [getDevice]);
@@ -3008,6 +3137,7 @@ function VizijRuntimeProviderInner({
     setReady(true);
   }, []);
   const hasBundleAnimations = (assetBundle.animations?.length ?? 0) > 0;
+  const [animationModuleReadyRevision, setAnimationModuleReadyRevision] = useState(0);
   useEffect(() => {
     if (!hasBundleAnimations || animationModuleRef.current) {
       return;
@@ -3023,6 +3153,7 @@ function VizijRuntimeProviderInner({
         animationHostRef.current?.replayInto(handle.device);
       };
       ensureAnimationHost();
+      setAnimationModuleReadyRevision((previous) => previous + 1);
     }).catch((err) => {
       pushError({
         message: "Failed to load the animation module",
@@ -3155,6 +3286,17 @@ function VizijRuntimeProviderInner({
       if (!handle.device.running) {
         handle.device.step(dt * 1e3);
       }
+      const behaviorError = handle.device.behaviorError;
+      if (behaviorError !== lastBehaviorErrorRef.current) {
+        lastBehaviorErrorRef.current = behaviorError;
+        if (behaviorError) {
+          pushError({
+            message: `Graph tick failed: ${behaviorError}`,
+            phase: "engine",
+            timestamp: performance.now()
+          });
+        }
+      }
       const changes = handle.device.drainChanges();
       applyEngineChangesRef.current(changes);
       if (storeChangeListenersRef.current.size > 0) {
@@ -3484,11 +3626,9 @@ function VizijRuntimeProviderInner({
         rigInputMapRef.current
       );
       if (isRuntimeDebugEnabled()) {
-        console.log("[vizij-runtime] animation output routing", {
-          animationId: animation.id,
-          bridgeOutputs,
-          bridgeOutputsText: bridgeOutputs.join(" | ")
-        });
+        console.log(
+          `[vizij-runtime] animation output routing ${animation.id} (${bridgeOutputs.length}) | ` + bridgeOutputs.join(" | ")
+        );
       }
       recordOutputs(bridgeOutputs);
     }
@@ -3560,7 +3700,35 @@ function VizijRuntimeProviderInner({
         });
       }
     }
-    ensureAnimationHost()?.setClips(hostClips);
+    const host = ensureAnimationHost();
+    host?.setClips(hostClips);
+    if (host) {
+      let resumed = false;
+      clipPlaybackRef.current.forEach((clipState, clipId) => {
+        if (!clipState.playing || !host.has(clipId)) {
+          return;
+        }
+        resumed = true;
+        host.setSpeed(clipId, clipState.speed);
+        host.setWeight(clipId, clipState.weight);
+        host.setLoop(clipId, clipState.loop ? "loop" : "once");
+        if (clipState.playhead > 0) {
+          host.seek(clipId, clipState.playhead);
+        }
+        void host.play(clipId).catch((err) => {
+          pushError({
+            message: `Failed to resume animation ${clipId} after the module became ready`,
+            cause: err,
+            phase: "animation",
+            timestamp: performance.now()
+          });
+        });
+      });
+      if (resumed) {
+        setAnimationsSourceRegistered(host.hasPlaying());
+        updateLoopMode();
+      }
+    }
     registeredAnimationsRef.current = animationIds;
     if (assetBundle.initialInputs) {
       Object.entries(assetBundle.initialInputs).forEach(([path, value]) => {
@@ -3605,7 +3773,9 @@ function VizijRuntimeProviderInner({
     registerMergedGraph,
     reportStatus,
     resolvedProgramAssets,
-    setInput
+    setInput,
+    setAnimationsSourceRegistered,
+    updateLoopMode
   ]);
   useEffect(() => {
     if (!ready || status.loading) {
@@ -3613,7 +3783,9 @@ function VizijRuntimeProviderInner({
     }
     const plan = pendingPlanRef.current;
     const hasRegistered = registeredGraphsRef.current.length > 0 || registeredAnimationsRef.current.length > 0 || programControllerIdsRef.current.size > 0;
-    if (plan && !plan.reregisterGraphs && hasRegistered) {
+    const forcedByModuleReady = animationModuleReadyRevision !== lastRegisteredModuleRevisionRef.current;
+    lastRegisteredModuleRevisionRef.current = animationModuleReadyRevision;
+    if (plan && !plan.reregisterGraphs && hasRegistered && !forcedByModuleReady) {
       return;
     }
     registerControllers().catch((err) => {
@@ -3624,7 +3796,14 @@ function VizijRuntimeProviderInner({
         timestamp: performance.now()
       });
     });
-  }, [ready, status.loading, graphUpdateToken, registerControllers, pushError]);
+  }, [
+    ready,
+    status.loading,
+    graphUpdateToken,
+    registerControllers,
+    pushError,
+    animationModuleReadyRevision
+  ]);
   useEffect(() => {
     applyEngineChangesRef.current = (changes) => {
       const entries = Object.entries(changes);
@@ -3742,6 +3921,23 @@ function VizijRuntimeProviderInner({
       entry?.resolve();
     }
   }, []);
+  const advanceClipPlayheads = useCallback((dt) => {
+    if (!(dt > 0) || !Number.isFinite(dt)) {
+      return;
+    }
+    clipPlaybackRef.current.forEach((state) => {
+      if (!state.playing) {
+        return;
+      }
+      const speed = Number.isFinite(state.speed) && state.speed > 0 ? state.speed : 1;
+      const next = state.playhead + dt * speed;
+      if (!(state.duration > 0)) {
+        state.playhead = next;
+        return;
+      }
+      state.playhead = state.loop ? next % state.duration : Math.min(next, state.duration);
+    });
+  }, []);
   const advanceAnimationTweens = useCallback(
     (dt) => {
       if (animationTweensRef.current.size === 0) {
@@ -3806,6 +4002,7 @@ function VizijRuntimeProviderInner({
         weight: 1,
         loop: true,
         playing: false,
+        playhead: 0,
         resolve: null,
         completion: null
       };
@@ -3904,8 +4101,17 @@ function VizijRuntimeProviderInner({
       return [];
     }
     const raw = device.readValues([ANIMATION_PLAYERS_PATH])[ANIMATION_PLAYERS_PATH];
-    return decodePlayerStates(raw);
-  }, [deviceSlot]);
+    const states = decodePlayerStates(raw);
+    if (DEV_MODE && states.length === 0 && raw && typeof raw === "object") {
+      warnAnimationGap(
+        "player-states-undecodable",
+        `Animation player_states feedback at "${ANIMATION_PLAYERS_PATH}" could not be decoded (top-level keys: ${Object.keys(
+          raw
+        ).join(", ")}). The transport falls back to a host-side playhead.`
+      );
+    }
+    return states;
+  }, [deviceSlot, warnAnimationGap]);
   const settleFinishedClips = useCallback(() => {
     let pending = false;
     clipPlaybackRef.current.forEach((state) => {
@@ -3961,6 +4167,7 @@ function VizijRuntimeProviderInner({
       if (host) {
         if (options?.reset === true) {
           host.seek(id, 0);
+          state.playhead = 0;
         }
         host.setSpeed(id, state.speed);
         host.setWeight(id, state.weight);
@@ -3997,6 +4204,9 @@ function VizijRuntimeProviderInner({
     (id) => {
       const state = clipPlaybackRef.current.get(id);
       if (!state || !state.playing) {
+        console.warn(
+          `[vizij-runtime] pause ignored for "${id}": ${state ? "the clip is not marked playing" : "no clip state"}`
+        );
         return;
       }
       state.playing = false;
@@ -4006,10 +4216,13 @@ function VizijRuntimeProviderInner({
     [syncAnimationsSource]
   );
   const seekAnimation = useCallback((id, timeSeconds) => {
-    if (!clipPlaybackRef.current.has(id)) {
+    const state = clipPlaybackRef.current.get(id);
+    if (!state) {
       return;
     }
-    animationHostRef.current?.seek(id, Math.max(0, timeSeconds));
+    const target = Math.max(0, timeSeconds);
+    state.playhead = state.duration > 0 ? Math.min(target, state.duration) : target;
+    animationHostRef.current?.seek(id, target);
   }, []);
   const setAnimationLoop = useCallback(
     (id, enabled) => {
@@ -4032,9 +4245,23 @@ function VizijRuntimeProviderInner({
       const playerId = animationHostRef.current?.playerIdOf(id) ?? null;
       const feedback = playerId !== null ? readPlayerStates().find((entry) => entry.player === playerId) : void 0;
       return {
-        time: feedback?.time ?? 0,
+        // Feedback is authoritative; the host-side playhead stands in when it
+        // is unavailable. Never fall back to a hard 0 — that reads as "the
+        // animation is parked at the start" rather than "no telemetry", and it
+        // pins the transport clock and defeats seeking.
+        time: feedback?.time ?? state.playhead,
         duration: feedback && feedback.duration > 0 ? feedback.duration : state.duration,
-        playing: feedback ? feedback.state === "playing" : state.playing,
+        // A clip commanded to pause is paused, whatever the feedback says.
+        //
+        // Feedback goes stale by construction: pausing the last playing clip
+        // unregisters the animations graph source, so the module stops being
+        // stepped and `player_states` keeps reporting whatever it last said —
+        // `state: "playing"`, with the playhead frozen. Treating that as
+        // authoritative meant the transport reverted to playing a frame after
+        // every pause, leaving a Pause button over a clip that was not
+        // advancing. Feedback still decides while the clip is *meant* to be
+        // playing, which is what notices a clip reaching its end.
+        playing: state.playing && (feedback ? feedback.state === "playing" : true),
         loop: state.loop,
         speed: feedback?.speed ?? state.speed
       };
@@ -4055,6 +4282,9 @@ function VizijRuntimeProviderInner({
         syncAnimationsSource();
       } else {
         host?.stop(id);
+        if (state) {
+          state.playhead = 0;
+        }
         const unsubscribe = subscribeToStep(() => {
           unsubscribe();
           syncAnimationsSource();
@@ -4389,6 +4619,13 @@ function VizijRuntimeProviderInner({
     },
     [faceId, namespace, pushError, setInput, setRendererValue]
   );
+  const reconcileAnimationsSource = useCallback(() => {
+    const host = animationHostRef.current;
+    if (!host || !host.hasPlaying()) {
+      return;
+    }
+    setAnimationsSourceRegistered(true);
+  }, [setAnimationsSourceRegistered]);
   const flushStagedInputs = useCallback(() => {
     if (stagedInputsRef.current.size === 0) {
       return;
@@ -4406,6 +4643,8 @@ function VizijRuntimeProviderInner({
         avgStepDtRef.current = prev * (1 - alpha) + dt * alpha;
       }
       advanceAnimationTweens(dt);
+      advanceClipPlayheads(dt);
+      reconcileAnimationsSource();
       flushStagedInputs();
       if (driveRuntimeRef.current || opts?.forceRuntime) {
         stepRuntime(dt);
@@ -4414,7 +4653,9 @@ function VizijRuntimeProviderInner({
     },
     [
       advanceAnimationTweens,
+      advanceClipPlayheads,
       flushStagedInputs,
+      reconcileAnimationsSource,
       settleFinishedClips,
       stepRuntime
     ]
@@ -5074,11 +5315,14 @@ export {
   buildPoseWeightRelativePath,
   buildRigInputPath,
   buildSemanticPoseWeightPathMap,
+  collectInputPathMap,
+  composeGraphSpecs,
   filterPosesBySemanticKind,
   getPoseSemanticKey,
   mapNormalizedControlValue,
   mapUnitControlValue,
   normalizePoseSemanticKey,
+  resolveAnimationBridgeOutputPaths,
   resolveFaceControls,
   resolvePoseMembership,
   resolvePoseSemantics,