@vgai/engine 0.5.14 → 0.5.16

package/src/animation/xstate-animation-binding.ts

@@ -4,7 +4,10 @@ import type { createSystemRunner } from '../core/system-runner';
 import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
 import type { BlendTreeDef } from './anim-graph-types';
 import { evaluateBlendTree } from './blend-node';
-import { attachAnimationRuntimeInspection } from './runtime-inspection';
+import {
+  type AnimationPreviewTransport,
+  attachAnimationRuntimeInspection,
+} from './runtime-inspection';
 import {
   type AnimationBoneMask,
   type AnimationMetaStateNodeLike,
@@ -109,6 +112,12 @@ export interface XStateAnimationBindingOptions {
    * omitted, the caller owns ticking (useful for standalone Three tests).
    */
   systems?: Pick<ReturnType<typeof createSystemRunner>, 'add' | 'remove'>;
+  /**
+   * Publish a seekable transport for an isolated design-time mount such as a
+   * CSF story. Never enable this on the live game binding: runtime inspection
+   * stays read-only there, while the story deliberately owns this preview.
+   */
+  previewTransport?: boolean;
 }
 
 export interface XStateAnimationLayerState {
@@ -368,6 +377,89 @@ export function bindXStateAnimation(
   const activeLayers = new Map<string, ActiveState>();
   let disposed = false;
   let detachRuntimeInspection = () => {};
+  let previewClip: string | null = null;
+  let previewAction: THREE.AnimationAction | null = null;
+  let previewPlaying = true;
+  let previewLoop = true;
+  let previewSpeed = 1;
+
+  function controllerPreviewSubject(): {
+    clip: string;
+    action: THREE.AnimationAction | null;
+  } {
+    const layers = [activeLayers.get('base'), ...activeLayers.values()].filter(
+      (active, index, all): active is ActiveState =>
+        Boolean(active) && all.indexOf(active) === index,
+    );
+    for (const active of layers) {
+      const weighted = [...active.natural].sort((left, right) => {
+        const leftWeight = actionCache.get(left.actionKey)?.action.getEffectiveWeight() ?? 0;
+        const rightWeight = actionCache.get(right.actionKey)?.action.getEffectiveWeight() ?? 0;
+        return rightWeight - leftWeight;
+      })[0];
+      if (weighted) {
+        return {
+          clip: weighted.clip,
+          action: actionCache.get(weighted.actionKey)?.action ?? null,
+        };
+      }
+    }
+    return { clip: clips.keys().next().value ?? '', action: null };
+  }
+
+  function actionIsControllerOwned(action: THREE.AnimationAction): boolean {
+    for (const cached of actionCache.values()) {
+      if (cached.action === action) return true;
+    }
+    return false;
+  }
+
+  function releasePreviewAction(): void {
+    const action = previewAction;
+    if (!action) return;
+    action.stop();
+    if (!actionIsControllerOwned(action)) {
+      mixer.uncacheAction(action.getClip(), action.getRoot());
+    }
+    previewAction = null;
+  }
+
+  function enterClipPreview(name: string): void {
+    const clip = clips.get(name);
+    if (!clip) return;
+    releasePreviewAction();
+    previewClip = name;
+    for (const cached of actionCache.values()) cached.action.setEffectiveWeight(0);
+    const action = mixer.clipAction(clip).reset().play();
+    action.setEffectiveWeight(1);
+    action.setEffectiveTimeScale(1);
+    action.setLoop(previewLoop ? THREE.LoopRepeat : THREE.LoopOnce, previewLoop ? Infinity : 1);
+    action.clampWhenFinished = !previewLoop;
+    previewAction = action;
+    mixer.update(0);
+  }
+
+  function restoreControllerPreview(): void {
+    releasePreviewAction();
+    previewClip = null;
+    const snapshot = actor.getSnapshot();
+    reconcile(snapshot);
+    const context = snapshot.context;
+    for (const cached of actionCache.values()) cached.action.setEffectiveWeight(0);
+    for (const active of activeLayers.values()) {
+      active.crossfadeRemaining = 0;
+      active.natural = weightsOf(active.stateId, active.meta, context);
+      const loop = isBlendTreeAnimationMeta(active.meta) ? true : active.meta.loop;
+      const speed = isBlendTreeAnimationMeta(active.meta) ? 1 : active.meta.speed;
+      const layerWeight = layerWeightOf(active.meta);
+      for (const weighted of active.natural) {
+        ensureAction(weighted.actionKey, loop, speed, layerWeight)
+          .play()
+          .setEffectiveWeight(weighted.weight * layerWeight);
+      }
+    }
+    mixer.update(0);
+  }
 
   function silence(weights: WeightedClip[], except: string | undefined, duration: number): void {
     for (const weighted of weights) {
@@ -465,23 +557,76 @@ export function bindXStateAnimation(
   const initialSnapshot = actor.getSnapshot();
   reconcile(initialSnapshot);
   const subscription = actor.subscribe((snapshot) => {
-    if (!disposed) reconcile(snapshot);
+    // Isolated clip review deliberately holds behavior output. The actor may
+    // keep receiving story args, but its latest state is reconciled only when
+    // the user returns to Controller.
+    if (!disposed && !previewClip) reconcile(snapshot);
   });
 
   function tick(dt: number): void {
     if (disposed) return;
+    if (options.previewTransport && !previewPlaying) return;
+    const elapsed = dt * (options.previewTransport ? previewSpeed : 1);
+    if (options.previewTransport && previewClip && previewAction) {
+      mixer.update(elapsed);
+      const clip = clips.get(previewClip);
+      if (!previewLoop && clip && previewAction.time >= clip.duration) previewPlaying = false;
+      return;
+    }
     const context = actor.getSnapshot().context;
     for (const active of activeLayers.values()) {
       if (active.crossfadeRemaining > 0) {
-        active.crossfadeRemaining = Math.max(0, active.crossfadeRemaining - dt);
+        active.crossfadeRemaining = Math.max(0, active.crossfadeRemaining - elapsed);
         if (active.crossfadeRemaining <= 0) applyLiveBlendWeights(active, context);
       } else {
         applyLiveBlendWeights(active, context);
       }
     }
-    mixer.update(dt);
+    mixer.update(elapsed);
   }
 
+  const previewTransport: AnimationPreviewTransport | undefined = options.previewTransport
+    ? {
+        getSnapshot: () => {
+          const controller = controllerPreviewSubject();
+          return {
+            clip: previewClip ?? controller.clip,
+            time: previewClip ? (previewAction?.time ?? 0) : (controller.action?.time ?? 0),
+            playing: previewPlaying,
+            loop: previewLoop,
+            speed: previewSpeed,
+            mode: previewClip ? 'clip' : 'controller',
+          };
+        },
+        setPlaying(playing) {
+          previewPlaying = playing;
+        },
+        setLoop(loop) {
+          previewLoop = loop;
+          if (!previewClip) enterClipPreview(controllerPreviewSubject().clip);
+          previewAction?.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, loop ? Infinity : 1);
+          if (previewAction) previewAction.clampWhenFinished = !loop;
+        },
+        setSpeed(speed) {
+          previewSpeed = THREE.MathUtils.clamp(speed, 0.05, 4);
+        },
+        seek(time) {
+          if (!previewClip) enterClipPreview(controllerPreviewSubject().clip);
+          const clip = previewClip ? clips.get(previewClip) : undefined;
+          if (!clip || !previewAction) return;
+          previewAction.time = THREE.MathUtils.clamp(time, 0, Math.max(clip.duration, 0));
+          mixer.update(0);
+        },
+        setClip(name) {
+          if (name === null) {
+            if (previewClip) restoreControllerPreview();
+            return;
+          }
+          enterClipPreview(name);
+        },
+      }
+    : undefined;
+
   const binding: XStateAnimationBinding = {
     tick,
     actor,
@@ -503,6 +648,7 @@ export function bindXStateAnimation(
       if (disposed) return;
       disposed = true;
       detachRuntimeInspection();
+      releasePreviewAction();
       options.systems?.remove('animation', tick);
       subscription.unsubscribe();
       for (const { action, clip } of actionCache.values()) {
@@ -520,6 +666,7 @@ export function bindXStateAnimation(
   detachRuntimeInspection = attachAnimationRuntimeInspection(owner, {
     mixer,
     clips,
+    ...(previewTransport ? { previewTransport } : {}),
     getSnapshot: () => ({
       layers: [...activeLayers.values()].map((active) => {
         const parameters = readParameters(actor.getSnapshot().context);

package/src/canvas-react/engine-bridge.ts

@@ -14,20 +14,20 @@
  */
 
 import { createContext, useContext } from 'react';
-import type { GameContext } from '../runtime/types';
+import type { CanvasGameContext } from './world-context';
 
 export interface EngineBridgeValue {
-  /** This root's `GameContext` — `input`, `debug`, `random`, `clock`, `game`,
+  /** This root's `CanvasGameContext` — `input`, `debug`, `random`, `clock`, `game`,
    *  `roots`, `systems`, `registerSystemAdapter`. Present so ordinary
    *  components can reach engine services with a HOOK (see
    *  {@link useGameContext}). */
-  readonly ctx?: GameContext | undefined;
+  readonly ctx?: CanvasGameContext | undefined;
 }
 
 export const EngineBridge = createContext<EngineBridgeValue | null>(null);
 
 /**
- * This canvas root's `GameContext`, for use inside any component in the tree.
+ * This canvas root's `CanvasGameContext`, for use inside any component in the tree.
  *
  * An ordinary component does what a model would write:
  *
@@ -36,7 +36,7 @@ export const EngineBridge = createContext<EngineBridgeValue | null>(null);
  *   const { input } = useGameContext();
  *   const ref = useRef<Sprite>(null);
  *   useTick(({ deltaMS }) => {
- *     if (input.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
+ *     if (input?.isPressed('move_right')) ref.current!.x += speed * (deltaMS / 1000);
  *   });
  *   return <pixiSprite ref={ref} texture={Texture.WHITE} />;
  * }
@@ -46,7 +46,7 @@ export const EngineBridge = createContext<EngineBridgeValue | null>(null);
  * `createPixiReactAdapter` — absent context is a wiring bug, and a silent
  * `null` would surface as a mystery `undefined` deep in a tick callback.
  */
-export function useGameContext(): GameContext {
+export function useGameContext(): CanvasGameContext {
   const bridge = useContext(EngineBridge);
   if (!bridge?.ctx) {
     throw new Error(

package/src/canvas-react/index.ts

@@ -22,7 +22,7 @@
  *  - `PixiPrimitive` / `adoptNow` — the canvas surface's `<primitive object={…}>`:
  *    render a container the game already owns, and place a spawn in the
  *    display tree ahead of the commit that renders it.
- *  - `useGameContext()` — this root's `GameContext` (`input`, `debug`,
+ *  - `useGameContext()` — this root's `CanvasGameContext` (`input`, `debug`,
  *    `random`, `clock`, `game`, `roots`) from inside any component in the tree.
  *    Behavior in a canvas world is components + hooks, never a class under a
  *    string key.
@@ -43,6 +43,7 @@ export {
 } from './pixi-react-adapter';
 export { pixiReactRootFactory, resolveCanvasEntryAdapter } from './pixi-react-root-factory';
 export {
+  type CanvasGameContext,
   type CanvasRootContextOptions,
   type CanvasRootRuntime,
   createCanvasRootContext,

package/src/canvas-react/pixi-react-adapter.tsx

@@ -6,20 +6,20 @@
  * this returns a `MountedPixiRoot` (`../adapter/root-adapter.ts`) whose `stage`
  * is the REAL `PIXI.Container` the reconciler renders into.
  *
- * This is the canvas surface's exact sibling of `world3d-react`'s
+ * This is the canvas surface's sibling of `world3d-react`'s
  * `createR3FAdapter`, with `@pixi/react` where that one has
- * react-three-fiber. Everything structural is the same, because the seam is
- * the same: one loop (the host's), one canvas (the host's), a world-local
- * `SystemRunner` ticked in engine phase order before the renderer advances,
- * and a `GameContext` threaded into the tree through `EngineBridge`.
+ * react-three-fiber. The explicit factory still supplies the engine context
+ * used by the current first-party Canvas examples while their app-owned input
+ * and debugger migration remains tracked in `docs/WORK.md`; `useTick` hooks
+ * stay registered on Pixi's real ticker throughout that migration.
  *
  * ## The loop contract
  *
  * `Application` is initialized with `autoStart: false` and `sharedTicker:
- * false`, so it owns a ticker that is NEVER started and therefore never
- * requests an animation frame. `mounted.update(dt)` is the only thing that
- * advances it, and it feeds GAME time, not wall time — which is what makes the
- * world freeze exactly when the host freezes it, and what makes
+ * false`, so it owns a native Pixi ticker that is NEVER started and therefore
+ * never requests an animation frame. `mounted.update(dt)` is the only thing
+ * that advances that ticker, and it feeds GAME time, not wall time — which is
+ * what makes the world freeze exactly when the host freezes it, and what makes
  * `game.waitSimTime` work in a hidden tab (a hidden tab has no rAF; the engine
  * loop's own catch-up still calls `update`, and Pixi has no independent clock
  * to disagree with it).
@@ -38,9 +38,11 @@
 import { createRoot, extend } from '@pixi/react';
 import type { Application, ApplicationOptions } from 'pixi.js';
 import * as PIXI from 'pixi.js';
-import { createElement, type ReactNode, useLayoutEffect } from 'react';
+import { createElement, Fragment, type ReactNode, useEffect, useLayoutEffect } from 'react';
 import type { CanvasHostContext, MountedPixiRoot, RootAdapter } from '../adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
 import { WorldProvider } from '../react/world-state';
+import { getDebugRegistry } from '../runtime/debug-registry';
 import { EngineBridge, type EngineBridgeValue } from './engine-bridge';
 import { createCanvasRootContext } from './world-context';
 
@@ -77,6 +79,12 @@ export interface CreatePixiReactAdapterOptions {
    *  actions). A missing/invalid map degrades loudly without failing the
    *  mount — see `world-context.ts`. */
   readonly inputMapPath?: string | null | undefined;
+  /**
+   * Transitional compatibility for component trees that still consume the
+   * engine context. Native trees opt out once their input, observation and
+   * debugger state are application-owned.
+   */
+  readonly engineRuntime?: boolean | undefined;
   /**
    * Extra `Application.init` options merged UNDER this adapter's own — e.g.
    * `{ antialias: false }`, `{ roundPixels: true }`. The loop-critical ones
@@ -98,21 +106,21 @@ export interface CreatePixiReactAdapterOptions {
 export function createPixiReactAdapter(
   options: CreatePixiReactAdapterOptions,
 ): RootAdapter<'canvas'> {
-  const { id, content, inputMapPath, applicationOptions } = options;
+  const { id, content, inputMapPath, engineRuntime = true, applicationOptions } = options;
 
   return {
     id,
 
     async mount(host: CanvasHostContext): Promise<MountedPixiRoot> {
-      const runtime = createCanvasRootContext(host, { id, inputMapPath });
-      const bridge: EngineBridgeValue = { ctx: runtime.ctx };
+      const runtime = engineRuntime ? createCanvasRootContext(host, { id, inputMapPath }) : null;
+      const bridge: EngineBridgeValue | null = runtime ? { ctx: runtime.ctx } : null;
       // Actions must exist before any component's first tick reads them — wait
       // for the (never-rejecting) input-map load before the first commit.
-      await runtime.inputMapReady;
+      await runtime?.inputMapReady;
 
       const canvas = host.canvas;
       if (MOUNTED_CANVASES.has(canvas)) {
-        runtime.dispose();
+        runtime?.dispose();
         throw new Error(
           `createPixiReactAdapter: root "${id}" was handed a canvas this lane has already ` +
             'mounted. @pixi/react keys its reconciler roots off the canvas element, so re-using ' +
@@ -129,6 +137,10 @@ export function createPixiReactAdapter(
       const committed = new Promise<void>((resolve) => {
         resolveCommitted = resolve;
       });
+      let resolveEffectsReady!: () => void;
+      const effectsReady = new Promise<void>((resolve) => {
+        resolveEffectsReady = resolve;
+      });
       let resolveUnmounted!: () => void;
       const unmounted = new Promise<void>((resolve) => {
         resolveUnmounted = resolve;
@@ -152,22 +164,28 @@ export function createPixiReactAdapter(
           resolveCommitted();
           return resolveUnmounted;
         }, []);
+        // This component is the last sibling. Reaching its passive effect
+        // means the initial tree's useDebugProvider/useDebugCommand effects
+        // have registered, so mount() can truthfully back Play's ack.
+        useEffect(resolveEffectsReady, []);
         return null;
       }
 
-      const game = runtime.ctx.game;
+      const game = runtime?.ctx.game;
       // The React seam every dom root already has — `useWorldState`,
       // `useDebugProvider`/`useDebugCommand`/`useDebugEmit`
       // (`../react/world-state`) — works identically inside a canvas root
       // because a canvas root IS React. `host.game` is genuinely absent in
       // bare/foreign hosts, so the provider is conditional and those hooks
       // stay the inert no-ops they already document themselves to be.
-      const element = createElement(
-        EngineBridge.Provider,
-        { value: bridge },
-        game ? createElement(WorldProvider, { game }, content) : content,
-        createElement(Lifecycle),
-      );
+      const world = createElement(Fragment, null, content, createElement(Lifecycle));
+      const element = bridge
+        ? createElement(
+            EngineBridge.Provider,
+            { value: bridge },
+            game ? createElement(WorldProvider, { game }, world) : world,
+          )
+        : world;
 
       const root: PixiReactRoot = createRoot(canvas);
 
@@ -193,7 +211,7 @@ export function createPixiReactAdapter(
       // creates the renderer) and only then hands the tree to the reconciler.
       // A crash inside init rejects here, which is the loud failure we want.
       const app: Application = await root.render(element, initOptions);
-      runtime.setApplication(app);
+      runtime?.setApplication(app);
 
       // A reconcile-time crash (e.g. an un-extended component) surfaces as an
       // uncaught window error and the first commit never lands — without this
@@ -207,7 +225,7 @@ export function createPixiReactAdapter(
           } catch {
             /* the world never fully came up; teardown failure must not mask why */
           }
-          runtime.dispose();
+          runtime?.dispose();
           reject(new Error(`createPixiReactAdapter: root "${id}" — ${why}`));
         };
         const onError = (event: ErrorEvent) =>
@@ -228,7 +246,7 @@ export function createPixiReactAdapter(
           globalThis.removeEventListener?.('error', onError);
         };
         globalThis.addEventListener?.('error', onError);
-        void committed.then(() => {
+        void Promise.all([committed, effectsReady]).then(() => {
           cleanup();
           resolve();
         });
@@ -243,6 +261,9 @@ export function createPixiReactAdapter(
       app.ticker.lastTime = 0;
       let elapsedMs = 0;
       let disposed = false;
+      const registry = host.game ? getDebugRegistry(host.game) : null;
+      const systemAdapters: SystemAdapters =
+        runtime?.systemAdapters ?? (registry ? { debug: registry.adapter } : {});
 
       return {
         kind: 'canvas',
@@ -250,17 +271,17 @@ export function createPixiReactAdapter(
         // `RootInstance.pixiStage()` hands the editor.
         stage: app.stage,
         drivesOwnLoop: false,
-        // Adapter surface: `debug` pre-seeded (the shared game registry's
-        // adapter); game code adds capabilities via `ctx.registerSystemAdapter`.
-        systems: runtime.systemAdapters,
+        // Adapter surface: the host's shared debug registry. A native component
+        // tree registers nothing; its entry-module `debug` export is projected
+        // after mount by the shared native adapter.
+        systems: systemAdapters,
         update(dt: number): void {
           if (disposed) return;
           elapsedMs += dt * 1000;
-          // Engine phases FIRST (registered systems mutate transforms), then
-          // the ticker — so `useTick` callbacks and the render that follows
-          // them at `UPDATE_PRIORITY.LOW` both see the fresh state. Both are
-          // host-gated: neither runs while this world is frozen.
-          runtime.systems.run(dt);
+          // The optional legacy runtime drains first when explicitly enabled;
+          // the native path has none. The real Pixi ticker remains the one
+          // scheduler `useTick` observes, and the host only gates/advances it.
+          runtime?.systems.run(dt);
           app.ticker.update(elapsedMs);
         },
         resize(width: number, height: number): void {
@@ -282,7 +303,7 @@ export function createPixiReactAdapter(
           // `removeView` stays false — the canvas belongs to the HOST.
           void root.render(null, initOptions);
           void unmounted.then(() => app.destroy(false, { children: true }));
-          runtime.dispose();
+          runtime?.dispose();
         },
       };
     },

package/src/canvas-react/pixi-react-root-factory.tsx

@@ -66,6 +66,10 @@ export function resolveCanvasEntryAdapter(
     return createPixiReactAdapter({
       id: rootId,
       content: createElement(mod.default),
+      // The supported Canvas portfolio still consumes the compatibility
+      // context. Removing it belongs to the tracked component-root migration;
+      // disabling it here first made every current default-exported game fail
+      // to mount before that migration had happened.
     });
   }
   return null;