@vgai/engine 0.5.21 → 0.5.22

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

@@ -1,8 +1,6 @@
 /**
  * `pixiReactRootFactory` — mount a `canvas` root whose entry module
- * DEFAULT-EXPORTS a React component.
- *
- * A model asked for a 2D world writes:
+ * DEFAULT-EXPORTS a React component. This is the ONE first-party canvas mount:
  *
  * ```tsx
  * export default function World() {
@@ -10,11 +8,13 @@
  * }
  * ```
  *
- * It does NOT write `export const adapter = createPixiReactAdapter({ id, content })`.
- * That export is vgai ceremony wrapped around a component the author already
- * wrote. The `three` and `dom` roots both settled this convention — read
- * `entryModule.default` and wrap it — and this is the same contract for canvas
- * roots, so all three surfaces answer "what do I export?" the same way.
+ * The world is an ordinary `@pixi/react` app. Everything vgai-shaped stays at
+ * the entry module's STATIC surface (`export { debug, systems } from
+ * './commands'`) and on the host's side of the seam; no vgai runtime context
+ * ever enters the React tree. The host advances Pixi's real (never-started)
+ * ticker on GAME time, wires the game-scoped input seams from outside
+ * (`../runtime/game-input-seams.ts`), and installs `WorldProvider` off the
+ * Game handle so the lib-legal react doors resolve.
  *
  * ## Why this is NOT in `mount-game.ts`
  *
@@ -24,22 +24,298 @@
  * the opt-in module that owns those dependencies, so the factory lives here and
  * a project opts in with `registerAdapter('canvas', pixiReactRootFactory)`.
  *
- * ## Compatibility
+ * ## The loop contract
+ *
+ * `Application` is initialized with `autoStart: false` and `sharedTicker:
+ * 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).
  *
- * An `adapter` export still wins, so a game needing full control over its own
- * `RootAdapter<'canvas'>` keeps it.
+ * ## Component catalogue
+ *
+ * `@pixi/react` resolves `<pixiSprite>` etc. through a module-global catalogue
+ * that starts EMPTY — the first intrinsic in an un-extended tree throws
+ * "X is not part of the PIXI namespace! Did you forget to extend?". This
+ * module extends it with the whole `pixi.js` namespace once per mount
+ * (idempotent `Object.assign`). A world that adds its own classes
+ * (`@pixi/tilemap`, a custom `Container` subclass) calls `extend`/`useExtend`
+ * itself.
  */
 
-import { type ComponentType, createElement } from 'react';
-import type { RootAdapter } from '../adapter/root-adapter';
+import { createRoot, extend } from '@pixi/react';
+import type { Application, ApplicationOptions } from 'pixi.js';
+import * as PIXI from 'pixi.js';
+import { type ComponentType, createElement, Fragment, 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 { DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from '../runtime/game-input-seams';
 import type { AdapterSurfaceFactory } from '../runtime/mount-game';
-import { createPixiReactAdapter } from './pixi-react-adapter';
+
+/** How long `mount()` waits for the tree's first commit before failing loudly
+ *  rather than hanging (and wedging every root declared after this one, since
+ *  roots mount sequentially). */
+const FIRST_COMMIT_TIMEOUT_MS = 10_000;
+
+/**
+ * `@pixi/react` keys its reconciler roots off the canvas element in a
+ * module-global map, and its own unmount path (which would clear that key) is
+ * not exported. So a canvas this lane has already mounted must never be handed
+ * to a second mount: `createRoot` would silently hand back the FIRST root,
+ * whose `Application` this lane already destroyed. Every host in this repo
+ * builds a fresh canvas per mount, so this only ever fires on a genuine bug —
+ * and it fires as a named error rather than as a dead world.
+ */
+const MOUNTED_CANVASES = new WeakSet<HTMLCanvasElement>();
+
+/** `@pixi/react`'s reconciler-root handle. Its `Root` type is internal (the
+ *  package exports the FUNCTION, not the type), so name it off the function. */
+type PixiReactRoot = ReturnType<typeof createRoot>;
 
 interface CanvasEntryModuleExports {
-  /** The idiomatic shape: the world IS a component. */
+  /** The one shape: the world IS a component. */
   readonly default?: ComponentType;
-  /** Full control, and still the winner when present. */
-  readonly adapter?: RootAdapter<'canvas'>;
+}
+
+/**
+ * Build the `RootAdapter<'canvas'>` for one default-exported Pixi world.
+ * Mounts through `@pixi/react`, gated entirely by the host's own loop and
+ * rendering into the host's own canvas — never a second canvas, never a
+ * second `requestAnimationFrame` loop.
+ */
+function canvasWorldAdapter(id: string, component: ComponentType): RootAdapter<'canvas'> {
+  const content = createElement(component);
+
+  return {
+    id,
+
+    async mount(host: CanvasHostContext): Promise<MountedPixiRoot> {
+      // THE HOST WIRES THIS GAME'S INPUT FROM OUTSIDE THE TREE — the project's
+      // declared map (conventional path, optional: a brand-new project
+      // declares no actions yet) and this root's `game.input.*` seams on the
+      // debug registry. Actions must exist before any component's first tick
+      // reads them — wait for the (never-rejecting) load before the first
+      // commit.
+      const registry = host.game ? getDebugRegistry(host.game) : null;
+      if (registry) {
+        await wireGameInputSeams(host, registry, {
+          id,
+          inputMapPath: DEFAULT_INPUT_MAP_PATH,
+          optionalInputMap: true,
+        });
+      }
+
+      const canvas = host.canvas;
+      if (MOUNTED_CANVASES.has(canvas)) {
+        throw new Error(
+          `canvas world "${id}": this lane has already mounted this canvas. @pixi/react keys ` +
+            'its reconciler roots off the canvas element, so re-using one would resurrect a ' +
+            'root whose Application is destroyed. Hand each mount a fresh canvas (every vgai ' +
+            'host already does).',
+        );
+      }
+      MOUNTED_CANVASES.add(canvas);
+
+      // The catalogue is module-global and starts empty; this is idempotent.
+      extend(PIXI as unknown as Parameters<typeof extend>[0]);
+
+      let resolveCommitted!: () => void;
+      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;
+      });
+      /**
+       * Signals the tree's FIRST COMMIT and its LAST. A layout effect,
+       * deliberately, and rendered as the LAST child, deliberately:
+       *
+       *  - mount: layout effects run synchronously inside the commit, before
+       *    any passive effect and before any tick can be scheduled;
+       *  - unmount: React commits deletion effects in tree order, each node
+       *    before its own children, so the LAST sibling's cleanup is the last
+       *    to run. That is what makes this a reliable "every component has
+       *    finished tearing down" signal — and it is load-bearing, because
+       *    `useTick`'s own cleanup calls `ticker.remove()`. Destroying the
+       *    Application before that cleanup lands throws inside React's commit
+       *    on every teardown of any world with a tick hook.
+       */
+      function Lifecycle(): null {
+        useLayoutEffect(() => {
+          resolveCommitted();
+          return resolveUnmounted;
+        }, []);
+        // This component is the last sibling. Reaching its passive effect
+        // means the initial tree's provider/command effects have registered,
+        // so mount() can truthfully back Play's ack.
+        useEffect(resolveEffectsReady, []);
+        return null;
+      }
+
+      // `WorldProvider` rides `host.game` — the React seam every dom root
+      // already has, and the only way a capability hook can reach the ONE
+      // game-scoped registry the editor/`vgai eval` read. `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 game = host.game;
+      const world = createElement(Fragment, null, content, createElement(Lifecycle));
+      const element = game ? createElement(WorldProvider, { game }, world) : world;
+
+      const root: PixiReactRoot = createRoot(canvas);
+
+      // The host owns size, dpr, transparency and capture cost; the loop
+      // contract owns `autoStart`/`sharedTicker`.
+      const initOptions: Partial<ApplicationOptions> = {
+        antialias: true,
+        width: host.width,
+        height: host.height,
+        resolution: host.dpr ?? globalThis.devicePixelRatio ?? 1,
+        autoDensity: true,
+        // Stacked ABOVE a sibling root -> clear with alpha 0 so the layer below
+        // shows through (COMPOSITION-DESIGN D5 §1).
+        backgroundAlpha: host.transparent ? 0 : 1,
+        preserveDrawingBuffer: host.preserveDrawingBuffer ?? false,
+        autoStart: false,
+        sharedTicker: false,
+      };
+
+      // Install the reconcile-error listener BEFORE `root.render`: Pixi hands
+      // the Application back after `init()` but React can already have thrown
+      // during that same turn. Attaching after the await loses the real error
+      // and turns it into a misleading ten-second timeout.
+      let reportReconcileFailure!: (why: string) => void;
+      const reconcileFailure = new Promise<string>((resolve) => {
+        reportReconcileFailure = resolve;
+      });
+      const onError = (event: ErrorEvent): void => {
+        reportReconcileFailure(
+          `the Pixi tree crashed before its first commit — ${event.message} ` +
+            '(mount() fails loudly instead of hanging)',
+        );
+      };
+      globalThis.addEventListener?.('error', onError);
+
+      let app: Application | undefined;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        // `root.render` is async: it awaits `Application.init()` (which is what
+        // 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 renderedApp = await root.render(element, initOptions);
+        app = renderedApp;
+
+        // A reconcile-time crash (e.g. an un-extended component) surfaces as
+        // an uncaught window error and the first commit never lands. Race that
+        // exact signal against the commit and the last-resort ceiling.
+        const timeout = new Promise<string>((resolve) => {
+          timer = setTimeout(
+            () =>
+              resolve(
+                `no first commit within ${FIRST_COMMIT_TIMEOUT_MS / 1000}s ` +
+                  '(mount() fails loudly instead of hanging)',
+              ),
+            FIRST_COMMIT_TIMEOUT_MS,
+          );
+        });
+        const failure = await Promise.race([
+          Promise.all([committed, effectsReady]).then(() => null),
+          reconcileFailure,
+          timeout,
+        ]);
+        if (failure !== null) {
+          throw new Error(`canvas world "${id}": ${failure}`);
+        }
+      } catch (error) {
+        try {
+          app?.destroy(false, { children: true });
+        } catch {
+          /* the world never fully came up; teardown failure must not mask why */
+        }
+        throw error;
+      } finally {
+        if (timer !== undefined) clearTimeout(timer);
+        globalThis.removeEventListener?.('error', onError);
+      }
+
+      // `app` is assigned before the first-commit race. Reaching here proves
+      // both initialization and commit succeeded, so narrow once for the live
+      // mounted-root methods below.
+      if (app === undefined) {
+        throw new Error(`canvas world "${id}": initialized without an Application`);
+      }
+      const mountedApp = app;
+
+      // Pin the ticker's clock to GAME time. `Ticker.lastTime` starts at -1, so
+      // without this the first `update()` would report a 1ms phantom delta on
+      // top of the real one. From here every `deltaMS` a `useTick` callback
+      // sees is exactly the `dt` the host handed us — no wall clock anywhere,
+      // which is what makes a paused world's resume frame ordinary rather than
+      // one giant catch-up step.
+      mountedApp.ticker.lastTime = 0;
+      let elapsedMs = 0;
+      let disposed = false;
+      // Adapter surface: the host's shared debug registry. The game's own
+      // capabilities arrive as the entry module's declared `systems`.
+      const systemAdapters: SystemAdapters = registry ? { debug: registry.adapter } : {};
+      const disposeComplete = unmounted.then(() => {
+        mountedApp.destroy(false, { children: true });
+      });
+
+      return {
+        kind: 'canvas',
+        // The reconciler's real root container — the same `PIXI.Container`
+        // `RootInstance.pixiStage()` hands the editor.
+        stage: mountedApp.stage,
+        drivesOwnLoop: false,
+        systems: systemAdapters,
+        disposeComplete,
+        update(dt: number): void {
+          if (disposed) return;
+          elapsedMs += dt * 1000;
+          // The real Pixi ticker remains the one scheduler `useTick` observes;
+          // the host only gates/advances it.
+          mountedApp.ticker.update(elapsedMs);
+        },
+        resize(width: number, height: number): void {
+          if (disposed) return;
+          // `autoDensity: true` makes Pixi re-stamp `canvas.style.width`/
+          // `.height` from this call, so the on-screen box follows the logical
+          // size with no explicit CSS write from the host.
+          mountedApp.renderer.resize(width, height);
+        },
+        dispose(): void {
+          if (disposed) return;
+          disposed = true;
+          // Pixi's EventSystem owns document.pointermove + window.pointerup
+          // (and its event ticker's global listener). React's deletion commit
+          // is asynchronous, so waiting to destroy the Application leaves
+          // those listeners live when the host audits this game realm. Detach
+          // the input target synchronously; the later Application.destroy()
+          // repeats this idempotently after every useTick cleanup has landed.
+          mountedApp.renderer.events.setTargetElement(null as unknown as HTMLElement);
+          // Rendering `null` children is the only unmount path `@pixi/react`
+          // exposes publicly (its `unmountRoot` helper is internal), and React
+          // commits that deletion on its own schedule — NOT synchronously. So
+          // the Application is destroyed on the `Lifecycle` cleanup signal
+          // instead of inline: `useTick`'s cleanup calls `ticker.remove()`, and
+          // a ticker destroyed before it lands throws inside React's commit.
+          // `removeView` stays false — the canvas belongs to the HOST.
+          void root.render(null, initOptions);
+        },
+      };
+    },
+  };
 }
 
 /**
@@ -48,45 +324,31 @@ interface CanvasEntryModuleExports {
  * Two callers need this answer and must never disagree about it: the runtime
  * mount ({@link pixiReactRootFactory}, below) and the EDITOR, which resolves
  * the same entry for play mode and for the design-time layer. When only one
- * side knows about the default-export shape, a world plays fine and shows
- * "(no scene loaded)" in edit mode — the exact split the three lane already
- * paid for.
+ * side knows the shape, a world plays fine and shows "(no scene loaded)" in
+ * edit mode.
  *
- * Returns `null` when the module is neither shape — the callers differ on what
- * to do about that (the factory throws; the editor reports a mount failure on
- * that root's boundary node and leaves every sibling working).
+ * Returns `null` when the module has no default-exported component — the
+ * callers differ on what to do about that (the factory throws; the editor
+ * reports a mount failure on that root's boundary node and leaves every
+ * sibling working).
  */
 export function resolveCanvasEntryAdapter(
   entryModule: unknown,
   rootId: string,
 ): RootAdapter<'canvas'> | null {
   const mod = entryModule as CanvasEntryModuleExports | undefined;
-  if (mod?.adapter) return mod.adapter;
-  if (typeof mod?.default === 'function') {
-    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.
-    });
-  }
+  if (typeof mod?.default === 'function') return canvasWorldAdapter(rootId, mod.default);
   return null;
 }
 
 /**
  * Register with `registerAdapter('canvas', pixiReactRootFactory)`.
- *
- * Resolution order mirrors the three lane's (explicit adapter wins) and then
- * accepts the default-exported component.
  */
 export const pixiReactRootFactory: AdapterSurfaceFactory = (root, ctx) => {
   const adapter = resolveCanvasEntryAdapter(ctx.entryModule, root.id);
   if (adapter) return { kind: 'canvas', adapter };
   throw new Error(
     `pixiReactRootFactory: entry module "${root.entry ?? '(none)'}" for root "${root.id}" must ` +
-      'default-export a React component (`export default function World() { … }`) — or export ' +
-      'an `adapter` for full control.',
+      'default-export a React component (`export default function World() { … }`).',
   );
 };

package/src/core/countdown-timer.ts

@@ -0,0 +1,188 @@
+/**
+ * `Countdown` — a restartable interval the CALLER steps, with the two
+ * behaviours under a frame hitch that decide whether a game's event count is
+ * right.
+ *
+ * A respawn delay, a weapon cooldown, a wave spawner, a grace window: each is
+ * "count down from N seconds, tell me, maybe go again, and let me restart or
+ * stop you at any point". `core/sim-clock.ts` schedules a one-shot at an
+ * ABSOLUTE sim time — the right shape for "3 seconds from now, once" and the
+ * wrong one for a live interval that game code re-arms, reads
+ * ({@link Countdown.remaining} is what a HUD ring draws) and cancels.
+ *
+ * That gap used to be papered over in `sim-clock.ts`'s own header, which said
+ * an `after` re-arming itself was "three lines the game owns". Those three
+ * lines are wrong in a way nobody notices: re-arming schedules the next fire
+ * from the moment the callback RAN, so every long frame permanently lengthens
+ * the interval, and a game that hitches ten times has silently slowed its
+ * spawner. That is the drift {@link Countdown} exists to not have.
+ *
+ * ## It owns no clock, and that is the requirement rather than a shortcut
+ *
+ * There is no `setTimeout`, no `setInterval`, no `requestAnimationFrame` and no
+ * subscription anywhere in this module. A countdown advances only inside
+ * {@link Countdown.advance}, from seconds the caller already has — the fixed
+ * loop's own dt. This repo runs a fixed-step sim with display-rate
+ * presentation and can step a game deterministically; a countdown on wall-clock
+ * `setTimeout` would be a second, undeterministic timeline that no care
+ * downstream could re-sync. A countdown nobody advances does not fire —
+ * visibly, rather than drifting.
+ *
+ * ## The frame-hitch contract, which is the whole reason this is a module
+ *
+ * Both rules are about keeping the EVENT COUNT correct when `dt` is larger than
+ * the period, which is exactly when a game is already in trouble:
+ *
+ *  - **Overshoot carries into the next period.** A 0.5 s repeating countdown
+ *    advanced by 0.6 fires once and has 0.4 s left, not 0.5. Resetting to the
+ *    full period instead would make one slow frame lengthen every interval
+ *    after it — the drift above, one layer down.
+ *  - **A single large step fires MORE THAN ONCE.** A 0.1 s countdown advanced
+ *    by 0.35 fires three times and has 0.05 s left. Dropping the extras would
+ *    silently slow a repeating countdown down whenever the frame was long, so a
+ *    wave that should have spawned 3 enemies spawns 1 and the difficulty curve
+ *    quietly depends on frame rate.
+ *
+ * Two consequences a caller must know about, both deliberate: `onElapsed` can
+ * be invoked several times within one `advance` call, and it runs INLINE
+ * (synchronously, inside `advance`) rather than on a microtask — so the caller
+ * always knows exactly which point of its frame the callback ran at.
+ *
+ * A one-shot countdown STOPS ITSELF BEFORE invoking `onElapsed`, so a callback
+ * that calls {@link Countdown.start} re-arms rather than fighting the stop.
+ * A callback that calls {@link Countdown.stop} ends the multi-fire loop
+ * immediately, which is what makes "fire once then disarm from inside the
+ * callback" work.
+ *
+ * ## Resource ownership
+ *
+ * **Owner:** whoever calls {@link createCountdown}. A countdown holds two
+ * numbers, a boolean and the `onElapsed` reference; it registers nothing,
+ * subscribes to nothing, and this module has no module-level state — so there
+ * is deliberately no `dispose()` and dropping the countdown drops everything it
+ * had. **Sharers:** none; a countdown is not shareable, because whoever
+ * advances it decides its timeline. **Teardown:** what DOES need unregistering
+ * is the countdown's slot in whatever set the owner advances each frame, and
+ * that is the owner's — the same way `SceneTree.addTimer` hands back a remover.
+ */
+
+/** A restartable countdown. Build one with {@link createCountdown}. */
+export interface Countdown {
+  /** Seconds it counts from. Reflects the last {@link Countdown.start} that
+   *  passed a duration. */
+  readonly duration: number;
+  /** Does it re-arm itself after firing, or stop? */
+  readonly repeats: boolean;
+  /** Seconds left, or 0 when it is not running. */
+  readonly remaining: number;
+  /** Is it counting? */
+  readonly running: boolean;
+  /**
+   * Start, or RESTART a running countdown from the top. Passing `duration`
+   * overwrites {@link Countdown.duration} for this and every later start.
+   *
+   * @throws RangeError if `duration` is not a finite positive number of
+   * seconds. A non-positive period cannot fire and reads as a hung game
+   * rather than a misconfigured one, so it refuses at the call site.
+   */
+  start(duration?: number): void;
+  /** Stop counting. Invokes nothing. */
+  stop(): void;
+  /**
+   * Advance by `dt` SECONDS, invoking `onElapsed` once per completed period —
+   * possibly several times in one call. See the module header's frame-hitch
+   * contract.
+   */
+  advance(dt: number): void;
+}
+
+/** What {@link createCountdown} needs. */
+export interface CountdownOptions {
+  /** Seconds to count from. Default 1. */
+  readonly duration?: number;
+  /** Re-arm after firing instead of stopping. Default `false` (one-shot). */
+  readonly repeats?: boolean;
+  /** Begin counting immediately instead of waiting for a `start()`. Default
+   *  `false`. */
+  readonly autostart?: boolean;
+  /** Invoked inline, once per completed period. */
+  readonly onElapsed: () => void;
+}
+
+function assertDuration(value: number): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(
+      `createCountdown: duration must be a finite, positive number of seconds, got ${String(value)}`,
+    );
+  }
+}
+
+/**
+ * Build a countdown.
+ *
+ * ```ts
+ * const wave = createCountdown({ duration: 8, repeats: true, autostart: true, onElapsed: spawnWave });
+ * useFrame((_, dt) => wave.advance(dt));   // the caller owns the step
+ * ```
+ */
+export function createCountdown(options: CountdownOptions): Countdown {
+  const onElapsed = options.onElapsed;
+  const repeats = options.repeats === true;
+  let duration = options.duration ?? 1;
+  let remaining = 0;
+  let running = false;
+
+  assertDuration(duration);
+
+  const countdown: Countdown = {
+    get duration(): number {
+      return duration;
+    },
+    get repeats(): boolean {
+      return repeats;
+    },
+    get remaining(): number {
+      return running ? remaining : 0;
+    },
+    get running(): boolean {
+      return running;
+    },
+
+    start(newDuration): void {
+      if (newDuration !== undefined) {
+        assertDuration(newDuration);
+        duration = newDuration;
+      }
+      remaining = duration;
+      running = true;
+    },
+
+    stop(): void {
+      running = false;
+      remaining = 0;
+    },
+
+    advance(dt): void {
+      if (!running) return;
+      remaining -= dt;
+      // The loop is the multi-fire rule; `running` in the condition is what
+      // lets a callback's own stop() end it. Module header, frame-hitch.
+      while (running && remaining <= 0) {
+        if (!repeats) {
+          // Disarm BEFORE invoking, so a callback that calls start() re-arms
+          // instead of being immediately stopped by this branch.
+          running = false;
+          remaining = 0;
+          onElapsed();
+          return;
+        }
+        // Carry the overshoot rather than resetting to the full period.
+        remaining += duration;
+        onElapsed();
+      }
+    },
+  };
+
+  if (options.autostart === true) countdown.start();
+  return countdown;
+}