@vgai/engine 0.5.0 → 0.5.2

package/dist/physics/transform-writer.js

@@ -1,38 +0,0 @@
-import * as THREE from 'three';
-const _quat = new THREE.Quaternion();
-const _parentInv = new THREE.Matrix4();
-const _parentQuat = new THREE.Quaternion();
-/**
- * Build the single postPhysics transform writer.
- *
- * Replaces the old three-step path (physicsSyncSystem → ECS Position/Rotation →
- * vnode-manager.syncTransforms). Rapier always reports world-space transforms, so
- * for objects parented under something other than the scene root we convert the
- * body's world position/rotation into the parent's local space (P1.5) — the old
- * vnode path wrote world transforms as local and mis-placed parented children.
- *
- * Scale is left untouched: Rapier carries no scale, so the Object3D keeps its
- * authored local scale.
- */
-export function createTransformWriter(physics, sceneRoot) {
-    return function writeTransforms() {
-        for (const [object3D, { body }] of physics.entries()) {
-            const t = body.translation();
-            const r = body.rotation();
-            const parent = object3D.parent;
-            if (parent && parent !== sceneRoot) {
-                // World → local: position through the inverse parent world matrix,
-                // rotation through the inverse parent world quaternion.
-                parent.updateWorldMatrix(true, false);
-                _parentInv.copy(parent.matrixWorld).invert();
-                object3D.position.set(t.x, t.y, t.z).applyMatrix4(_parentInv);
-                parent.getWorldQuaternion(_parentQuat).invert();
-                object3D.quaternion.copy(_parentQuat.multiply(_quat.set(r.x, r.y, r.z, r.w)));
-            }
-            else {
-                object3D.position.set(t.x, t.y, t.z);
-                object3D.quaternion.set(r.x, r.y, r.z, r.w);
-            }
-        }
-    };
-}

package/dist/physics/trigger-dispatch.d.ts

@@ -1,24 +0,0 @@
-import type RAPIER from '@dimforge/rapier3d-compat';
-import type { ComponentManager } from '../ecs/component-manager';
-import type { GameContext } from '../runtime/types';
-import type { CollisionHandler } from './collision-system';
-import type { PhysicsRegistry } from './physics-registry';
-/**
- * Build a {@link CollisionHandler} that turns Rapier sensor overlaps into
- * `onTriggerEnter` / `onTriggerExit` callbacks on the GameComponents of the two
- * involved Object3Ds.
- *
- * Rapier collision events report collider *handles*; we resolve each to its
- * Object3D via the physics registry's reverse index, then notify each side's
- * components with the *other* Object3D. Only sensor-involved collisions dispatch
- * triggers (a solid-vs-solid contact is a regular collision, not a trigger).
- *
- * Tracks currently-active trigger partners so that if one side is unregistered
- * (despawned) from the physics registry before Rapier's own exit event is
- * drained, the still-live side still gets its `onTriggerExit` (T1.12d) — see
- * `physics.onRemove` below.
- *
- * Register with `collisions.onCollision(createTriggerDispatch(...))`.
- */
-export declare function createTriggerDispatch(physics: PhysicsRegistry, components: ComponentManager, rapierWorld: RAPIER.World, ctx: GameContext): CollisionHandler;
-//# sourceMappingURL=trigger-dispatch.d.ts.map

package/dist/physics/trigger-dispatch.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"trigger-dispatch.d.ts","sourceRoot":"","sources":["../../src/physics/trigger-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,gBAAgB,EAC5B,WAAW,EAAE,MAAM,CAAC,KAAK,EACzB,GAAG,EAAE,WAAW,GACf,gBAAgB,CAsDlB"}

package/dist/physics/trigger-dispatch.js

@@ -1,80 +0,0 @@
-/**
- * Build a {@link CollisionHandler} that turns Rapier sensor overlaps into
- * `onTriggerEnter` / `onTriggerExit` callbacks on the GameComponents of the two
- * involved Object3Ds.
- *
- * Rapier collision events report collider *handles*; we resolve each to its
- * Object3D via the physics registry's reverse index, then notify each side's
- * components with the *other* Object3D. Only sensor-involved collisions dispatch
- * triggers (a solid-vs-solid contact is a regular collision, not a trigger).
- *
- * Tracks currently-active trigger partners so that if one side is unregistered
- * (despawned) from the physics registry before Rapier's own exit event is
- * drained, the still-live side still gets its `onTriggerExit` (T1.12d) — see
- * `physics.onRemove` below.
- *
- * Register with `collisions.onCollision(createTriggerDispatch(...))`.
- */
-export function createTriggerDispatch(physics, components, rapierWorld, ctx) {
-    const activePartners = new Map();
-    const link = (a, b) => {
-        let set = activePartners.get(a);
-        if (!set) {
-            set = new Set();
-            activePartners.set(a, set);
-        }
-        set.add(b);
-    };
-    const unlink = (a, b) => {
-        const set = activePartners.get(a);
-        if (!set)
-            return;
-        set.delete(b);
-        if (set.size === 0)
-            activePartners.delete(a);
-    };
-    // Flush pending exits at unregister: an entity removed from the physics
-    // registry (e.g. despawned) may still have queued Rapier "stopped" events
-    // that never reach drain(), or may never generate one at all (the collider
-    // is simply gone). Either way, any object still tracked as its trigger
-    // partner must get its onTriggerExit now, not silently never.
-    physics.onRemove((object3D) => {
-        const partners = activePartners.get(object3D);
-        if (!partners || partners.size === 0)
-            return;
-        for (const other of partners) {
-            notify(components, other, object3D, false, ctx);
-            notify(components, object3D, other, false, ctx);
-            unlink(other, object3D);
-        }
-        activePartners.delete(object3D);
-    });
-    return (handleA, handleB, started) => {
-        const colA = rapierWorld.getCollider(handleA);
-        const colB = rapierWorld.getCollider(handleB);
-        if (!colA?.isSensor() && !colB?.isSensor())
-            return;
-        const objA = physics.getByColliderHandle(handleA);
-        const objB = physics.getByColliderHandle(handleB);
-        if (!objA || !objB)
-            return;
-        if (started) {
-            link(objA, objB);
-            link(objB, objA);
-        }
-        else {
-            unlink(objA, objB);
-            unlink(objB, objA);
-        }
-        notify(components, objA, objB, started, ctx);
-        notify(components, objB, objA, started, ctx);
-    };
-}
-function notify(components, self, other, started, ctx) {
-    for (const inst of components.getComponents(self)) {
-        if (started)
-            inst.onTriggerEnter?.(other, ctx);
-        else
-            inst.onTriggerExit?.(other, ctx);
-    }
-}

package/dist/react/game-state.d.ts

@@ -1,156 +0,0 @@
-/**
- * Canonical `GameProvider`/`useGame`/`useGameState`/`useWorldObservation`
- * entry for React adapter roots. Also home to `useDebugProvider` and
- * `useDebugCommand`/`useDebugEmit`, the React-facing debug seam.
- *
- * This is a SEPARATE, react-value-importing module under
- * `packages/engine/src/react/` — colocated per REACT-STATE-BRIDGE §3's own
- * "colocate the react-facing hooks with the HUD seam, not the react-free
- * core" rule, just now living IN the engine package rather than only in the
- * project template. It is imported by NOTHING in the engine core import
- * graph (`packages/engine/src/` outside this `react/` directory) — that
- * invariant is proved by `packages/engine/test/react-core-import-ban.test.ts`
- * (AC-F1).
- *
- * Every host and game imports this one module, so provider and hooks share
- * one `createContext()` identity. The engine core outside `src/react/`
- * remains React-free, enforced by `react-core-import-ban.test.ts`.
- */
-import { type PropsWithChildren } from 'react';
-import type { z } from 'zod';
-import type { WorldStateObserver } from '../adapter';
-import { type Equals, shallow } from '../runtime/frame-selector-cache';
-import type { Game } from '../runtime/game';
-import type { DebugCommandArgs } from '../runtime/types';
-/** Re-exported for convenience — the opt-in equality for selectors that
- *  return a fresh object/array/tuple every call (default is `Object.is`). */
-export { shallow };
-/** Provide the `Game` to `useGameState`/`useGame` for everything mounted
- *  beneath it. Adapter-root hosts install this provider automatically — see the module doc
- *  comment above for the context-identity rule this hook family depends on.
- *
- *  Props use `PropsWithChildren` (children optional in the TYPE, not
- *  runtime-optional in practice — you always want children mounted under
- *  the provider) rather than a bare `{ children: ReactNode }` field: a
- *  required `children` in `P` makes TS's `createElement<P>(type, props?:
- *  Attributes & P, ...children)` overload reject the plain 3-arg call
- *  `React.createElement(GameProvider, { game }, child)` (no JSX transform,
- *  e.g. a `.ts` main composing a sibling `.tsx` HUD) with "Property
- *  'children' is missing" even though the 3rd arg supplies it — issue #97.
- *  Making `children` optional in the type lets that overload resolve; the
- *  rest-arg children are still wired through to `children` at runtime by
- *  React itself, unchanged. See `test/game-state-create-element-types.test.tsx`. */
-export declare function GameProvider({ game, children }: PropsWithChildren<{
-    game: Game;
-}>): import("react").JSX.Element;
-/** Read the `Game` provided by the nearest `GameProvider`. Throws
- *  descriptively when called outside one — matching the repo's loud-failure
- *  habit rather than silently returning `null`. */
-export declare function useGame(): Game;
-/**
- * Subscribe to a selected slice of game state (`docs/REACT-STATE-BRIDGE.md`
- * §3). Re-renders only when the selected value changes: the selector re-runs
- * at most once per completed frame (`game.state.frameVersion`), and
- * `equals` (default `Object.is`; pass {@link shallow} for tuples/objects)
- * gates whether the fresh result actually counts as a change.
- *
- * `selector` reads the live graph (e.g.
- * `g => g.queryByComponent(Hp)[0]?.hp`) at post-frame quiescence — no
- * copies. A selector that returns a fresh object every call must pass
- * `shallow` (or an equivalent `equals`), or it will re-render every frame.
- *
- * Note: `equals` is captured once, when this hook first mounts (in the
- * per-instance cache created below) — pass a stable function (module-level
- * `shallow`/`Object.is`, or a value that doesn't change across renders),
- * not a fresh inline arrow every render.
- */
-export declare function useGameState<T>(selector: (game: Game) => T, equals?: Equals<T>): T;
-/**
- * Pure, react-free lookup for the `useWorldObservation` hook below — factored
- * out so the hook body stays a thin `useSyncExternalStore` wrapper. Throws
- * descriptively (loud, not `undefined`-forever) when `worldId` doesn't name a
- * registered world, or that world's mount has no `observe`
- * (`WorldStateObserver`, `@engine/adapter`) — matching the `Game.registerWorld`
- * "no state bridge" report (`runtime/game.ts`) this is the react-side half of.
- */
-export declare function requireWorldObserver(game: Game, worldId: string): WorldStateObserver;
-/**
- * Subscribe to a selected slice of a FOREIGN (non-first-party) world's
- * observed state (`docs/REACT-STATE-BRIDGE.md` §4) — the ingested-world
- * counterpart of `useGameState` above; both are sugar over the same
- * subscribe/snapshot shape, so a react HUD reads native and ingested sources
- * through one mental model.
- *
- * `selector` runs over that world's `snapshot()` — NOT the `Game` — since a
- * foreign world hosts no `GameComponent`s to query. Re-renders only when the
- * selected value changes (`equals`, default `Object.is`; pass {@link shallow}
- * for tuples/objects returned fresh every call).
- *
- * Cadence note: unlike `useGameState`, this does NOT key its cache off
- * `game.state.frameVersion` — a foreign/self-driven world may notify on its
- * OWN rAF cadence, unrelated to our frame timing (§4's "consumers must not
- * assume our frame timing"). Instead this keeps a local version counter,
- * bumped once per `onChange` notification from the observer itself.
- *
- * Throws (loud, not a silently-undefined subscription) if `worldId` isn't
- * registered, or its mount has no `observe` — see `requireWorldObserver`.
- */
-export declare function useWorldObservation<T>(worldId: string, selector: (snapshot: unknown) => T, equals?: Equals<T>): T;
-/**
- * The debug seam's react-world registration door (Task 1.5,
- * `docs/SYNTHETIC-PLAYER-SPEC.md` §3.1): react roots have no `setup()`/
- * `ctx.debug` of their own, so this hook registers a named state provider
- * into the SAME game-scoped registry every `GameComponent`'s `ctx.debug`
- * feeds (`getDebugRegistry(game)`, `runtime/debug-registry.ts`), readable
- * through `game.systemAdapters.debug.state(name)` exactly like a
- * `ctx.debug.registerStateProvider` call.
- *
- * Registers ONCE per mount (keyed on `name`) and unregisters on unmount —
- * silently, like hot-reload's `strip()`. Re-renders never re-register or
- * re-warn: `fn` is kept in a ref updated every render, so the registered
- * closure always calls the CURRENT `fn` without touching the registry.
- * Outside a `<GameProvider>` (or against a bare test `Game` built without a
- * registry) this is an inert no-op — it never throws, matching the "no seam
- * without a consumer" degrade every optional `ctx.*` surface follows.
- */
-export declare function useDebugProvider(name: string, fn: () => unknown, opts?: {
-    tier?: 'observable' | 'assisted';
-}): void;
-/**
- * The command-side counterpart of {@link useDebugProvider} — registers an
- * invokable debug command into the same game-scoped registry, readable
- * through `game.systemAdapters.debug.commands()`/`invoke(name, args)`.
- *
- * Same mount/unmount/ref-latest contract as {@link useDebugProvider}: `spec`
- * (description/args/locus) is captured at registration time, `fn` always
- * calls through to the latest render's closure via a ref, and the hook is an
- * inert no-op with no `<GameProvider>` in scope.
- *
- * Generic over the declared `args` Zod tuple, same as
- * `DebugCtxSurface.registerCommand` ({@link DebugCommandArgs}, dry-run
- * finding — `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md` Wave 6 ledger): declaring
- * `args: z.tuple([z.number(), z.string()])` types `fn`'s parameters as
- * `(n: number, s: string) => ...` with no `unknown[]` cast; omitting `args`
- * keeps `fn` typed `(...args: unknown[]) => ...` as before.
- */
-export declare function useDebugCommand<T extends z.ZodTuple | undefined = undefined>(name: string, spec: {
-    description?: string;
-    args?: T;
-    locus?: 'client' | 'server';
-}, fn: (...args: DebugCommandArgs<T>) => unknown | Promise<unknown>): void;
-/**
- * The event-side counterpart of {@link useDebugProvider} and
- * {@link useDebugCommand}. Returns a stable callback that writes a
- * tick-stamped event to the game-scoped debug flight recorder:
- *
- * ```tsx
- * const emit = useDebugEmit();
- * emit('score-changed', { score });
- * ```
- *
- * It is an inert no-op outside a `<GameProvider>`, matching the optional
- * behavior of the other React debug hooks. Games never need to import the
- * debug registry or know its internal React provenance id.
- */
-export declare function useDebugEmit(): (event: string, detail?: unknown) => void;
-//# sourceMappingURL=game-state.d.ts.map

package/dist/react/game-state.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"game-state.d.ts","sourceRoot":"","sources":["../../src/react/game-state.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EAMvB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAA4B,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;6EAC6E;AAC7E,OAAO,EAAE,OAAO,EAAE,CAAC;AAInB;;;;;;;;;;;;;;oFAcoF;AACpF,wBAAgB,YAAY,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,iBAAiB,CAAC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,+BAEjF;AAED;;mDAEmD;AACnD,wBAAgB,OAAO,IAAI,IAAI,CAQ9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAAG,CAAC,CAW7F;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAiBpF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,CAAC,EAClC,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAC5B,CAAC,CAoBH;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,EACjB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;CAAE,GAC1C,IAAI,CAaN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,GAAG,SAAS,GAAG,SAAS,EAC1E,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAAE,EACrE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC/D,IAAI,CAeN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CASxE"}

package/dist/react/game-state.js

@@ -1,222 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-/**
- * Canonical `GameProvider`/`useGame`/`useGameState`/`useWorldObservation`
- * entry for React adapter roots. Also home to `useDebugProvider` and
- * `useDebugCommand`/`useDebugEmit`, the React-facing debug seam.
- *
- * This is a SEPARATE, react-value-importing module under
- * `packages/engine/src/react/` — colocated per REACT-STATE-BRIDGE §3's own
- * "colocate the react-facing hooks with the HUD seam, not the react-free
- * core" rule, just now living IN the engine package rather than only in the
- * project template. It is imported by NOTHING in the engine core import
- * graph (`packages/engine/src/` outside this `react/` directory) — that
- * invariant is proved by `packages/engine/test/react-core-import-ban.test.ts`
- * (AC-F1).
- *
- * Every host and game imports this one module, so provider and hooks share
- * one `createContext()` identity. The engine core outside `src/react/`
- * remains React-free, enforced by `react-core-import-ban.test.ts`.
- */
-import { createContext, useCallback, useContext, useEffect, useRef, useSyncExternalStore, } from 'react';
-import { getDebugRegistry } from '../runtime/debug-registry';
-import { createFrameSelectorCache, shallow } from '../runtime/frame-selector-cache';
-/** Re-exported for convenience — the opt-in equality for selectors that
- *  return a fresh object/array/tuple every call (default is `Object.is`). */
-export { shallow };
-const GameContext = createContext(null);
-/** Provide the `Game` to `useGameState`/`useGame` for everything mounted
- *  beneath it. Adapter-root hosts install this provider automatically — see the module doc
- *  comment above for the context-identity rule this hook family depends on.
- *
- *  Props use `PropsWithChildren` (children optional in the TYPE, not
- *  runtime-optional in practice — you always want children mounted under
- *  the provider) rather than a bare `{ children: ReactNode }` field: a
- *  required `children` in `P` makes TS's `createElement<P>(type, props?:
- *  Attributes & P, ...children)` overload reject the plain 3-arg call
- *  `React.createElement(GameProvider, { game }, child)` (no JSX transform,
- *  e.g. a `.ts` main composing a sibling `.tsx` HUD) with "Property
- *  'children' is missing" even though the 3rd arg supplies it — issue #97.
- *  Making `children` optional in the type lets that overload resolve; the
- *  rest-arg children are still wired through to `children` at runtime by
- *  React itself, unchanged. See `test/game-state-create-element-types.test.tsx`. */
-export function GameProvider({ game, children }) {
-    return _jsx(GameContext.Provider, { value: game, children: children });
-}
-/** Read the `Game` provided by the nearest `GameProvider`. Throws
- *  descriptively when called outside one — matching the repo's loud-failure
- *  habit rather than silently returning `null`. */
-export function useGame() {
-    const game = useContext(GameContext);
-    if (!game) {
-        throw new Error('useGame: no Game in context — wrap this component in <GameProvider game={ctx.game!}>.');
-    }
-    return game;
-}
-/**
- * Subscribe to a selected slice of game state (`docs/REACT-STATE-BRIDGE.md`
- * §3). Re-renders only when the selected value changes: the selector re-runs
- * at most once per completed frame (`game.state.frameVersion`), and
- * `equals` (default `Object.is`; pass {@link shallow} for tuples/objects)
- * gates whether the fresh result actually counts as a change.
- *
- * `selector` reads the live graph (e.g.
- * `g => g.queryByComponent(Hp)[0]?.hp`) at post-frame quiescence — no
- * copies. A selector that returns a fresh object every call must pass
- * `shallow` (or an equivalent `equals`), or it will re-render every frame.
- *
- * Note: `equals` is captured once, when this hook first mounts (in the
- * per-instance cache created below) — pass a stable function (module-level
- * `shallow`/`Object.is`, or a value that doesn't change across renders),
- * not a fresh inline arrow every render.
- */
-export function useGameState(selector, equals = Object.is) {
-    const game = useGame();
-    const cacheRef = useRef(null);
-    if (cacheRef.current === null) {
-        cacheRef.current = createFrameSelectorCache(equals);
-    }
-    return useSyncExternalStore((onStoreChange) => game.state.subscribe(onStoreChange), () => cacheRef.current.get(game.state.frameVersion, () => selector(game)));
-}
-/**
- * Pure, react-free lookup for the `useWorldObservation` hook below — factored
- * out so the hook body stays a thin `useSyncExternalStore` wrapper. Throws
- * descriptively (loud, not `undefined`-forever) when `worldId` doesn't name a
- * registered world, or that world's mount has no `observe`
- * (`WorldStateObserver`, `@engine/adapter`) — matching the `Game.registerWorld`
- * "no state bridge" report (`runtime/game.ts`) this is the react-side half of.
- */
-export function requireWorldObserver(game, worldId) {
-    const world = game.world(worldId);
-    if (!world) {
-        throw new Error(`useWorldObservation: no world registered with id "${worldId}" — check game.roots for the ` +
-            'ids actually registered.');
-    }
-    const observer = world.mounted.observe;
-    if (!observer) {
-        throw new Error(`useWorldObservation: world "${worldId}" (kind: ${world.kind}, adapter: "${world.adapter.id}") ` +
-            'has no state bridge — its mount has no `observe` (WorldStateObserver). This world cannot ' +
-            'be observed from React (docs/REACT-STATE-BRIDGE.md §4).');
-    }
-    return observer;
-}
-/**
- * Subscribe to a selected slice of a FOREIGN (non-first-party) world's
- * observed state (`docs/REACT-STATE-BRIDGE.md` §4) — the ingested-world
- * counterpart of `useGameState` above; both are sugar over the same
- * subscribe/snapshot shape, so a react HUD reads native and ingested sources
- * through one mental model.
- *
- * `selector` runs over that world's `snapshot()` — NOT the `Game` — since a
- * foreign world hosts no `GameComponent`s to query. Re-renders only when the
- * selected value changes (`equals`, default `Object.is`; pass {@link shallow}
- * for tuples/objects returned fresh every call).
- *
- * Cadence note: unlike `useGameState`, this does NOT key its cache off
- * `game.state.frameVersion` — a foreign/self-driven world may notify on its
- * OWN rAF cadence, unrelated to our frame timing (§4's "consumers must not
- * assume our frame timing"). Instead this keeps a local version counter,
- * bumped once per `onChange` notification from the observer itself.
- *
- * Throws (loud, not a silently-undefined subscription) if `worldId` isn't
- * registered, or its mount has no `observe` — see `requireWorldObserver`.
- */
-export function useWorldObservation(worldId, selector, equals = Object.is) {
-    const game = useGame();
-    const observer = requireWorldObserver(game, worldId);
-    const cacheRef = useRef(null);
-    if (cacheRef.current === null) {
-        cacheRef.current = createFrameSelectorCache(equals);
-    }
-    // Local notification-version counter — see the cadence note above. A
-    // plain mutable ref (not React state): bumping it must not itself trigger
-    // a render, `useSyncExternalStore`'s `onStoreChange` is what does that.
-    const versionRef = useRef(0);
-    return useSyncExternalStore((onStoreChange) => observer.subscribe(() => {
-        versionRef.current++;
-        onStoreChange();
-    }), () => cacheRef.current.get(versionRef.current, () => selector(observer.snapshot())));
-}
-/**
- * The debug seam's react-world registration door (Task 1.5,
- * `docs/SYNTHETIC-PLAYER-SPEC.md` §3.1): react roots have no `setup()`/
- * `ctx.debug` of their own, so this hook registers a named state provider
- * into the SAME game-scoped registry every `GameComponent`'s `ctx.debug`
- * feeds (`getDebugRegistry(game)`, `runtime/debug-registry.ts`), readable
- * through `game.systemAdapters.debug.state(name)` exactly like a
- * `ctx.debug.registerStateProvider` call.
- *
- * Registers ONCE per mount (keyed on `name`) and unregisters on unmount —
- * silently, like hot-reload's `strip()`. Re-renders never re-register or
- * re-warn: `fn` is kept in a ref updated every render, so the registered
- * closure always calls the CURRENT `fn` without touching the registry.
- * Outside a `<GameProvider>` (or against a bare test `Game` built without a
- * registry) this is an inert no-op — it never throws, matching the "no seam
- * without a consumer" degrade every optional `ctx.*` surface follows.
- */
-export function useDebugProvider(name, fn, opts) {
-    const game = useContext(GameContext);
-    const fnRef = useRef(fn);
-    fnRef.current = fn;
-    const tier = opts?.tier;
-    useEffect(() => {
-        const registry = game && getDebugRegistry(game);
-        if (!registry)
-            return;
-        return registry.registerReactProvider(name, () => fnRef.current(), { tier });
-        // `tier` is deliberately NOT a dep (same reasoning as `useDebugCommand`'s
-        // `spec`) — captured once at mount, so it never forces re-registration.
-    }, [game, name]);
-}
-/**
- * The command-side counterpart of {@link useDebugProvider} — registers an
- * invokable debug command into the same game-scoped registry, readable
- * through `game.systemAdapters.debug.commands()`/`invoke(name, args)`.
- *
- * Same mount/unmount/ref-latest contract as {@link useDebugProvider}: `spec`
- * (description/args/locus) is captured at registration time, `fn` always
- * calls through to the latest render's closure via a ref, and the hook is an
- * inert no-op with no `<GameProvider>` in scope.
- *
- * Generic over the declared `args` Zod tuple, same as
- * `DebugCtxSurface.registerCommand` ({@link DebugCommandArgs}, dry-run
- * finding — `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md` Wave 6 ledger): declaring
- * `args: z.tuple([z.number(), z.string()])` types `fn`'s parameters as
- * `(n: number, s: string) => ...` with no `unknown[]` cast; omitting `args`
- * keeps `fn` typed `(...args: unknown[]) => ...` as before.
- */
-export function useDebugCommand(name, spec, fn) {
-    const game = useContext(GameContext);
-    const fnRef = useRef(fn);
-    fnRef.current = fn;
-    useEffect(() => {
-        const registry = game && getDebugRegistry(game);
-        if (!registry)
-            return;
-        return registry.registerReactCommand(name, spec, (...args) => fnRef.current(...args));
-        // `spec` is deliberately NOT a dep (like `equals` above) — captured once
-        // at mount, so a fresh inline object literal every render never forces
-        // re-registration.
-    }, [game, name]);
-}
-/**
- * The event-side counterpart of {@link useDebugProvider} and
- * {@link useDebugCommand}. Returns a stable callback that writes a
- * tick-stamped event to the game-scoped debug flight recorder:
- *
- * ```tsx
- * const emit = useDebugEmit();
- * emit('score-changed', { score });
- * ```
- *
- * It is an inert no-op outside a `<GameProvider>`, matching the optional
- * behavior of the other React debug hooks. Games never need to import the
- * debug registry or know its internal React provenance id.
- */
-export function useDebugEmit() {
-    const game = useContext(GameContext);
-    return useCallback((event, detail) => {
-        if (!game)
-            return;
-        getDebugRegistry(game)?.emitReact(event, detail);
-    }, [game]);
-}

package/dist/react/root-adapter.d.ts

@@ -1,11 +0,0 @@
-import { type ComponentType } from 'react';
-import type { ReactRootAdapter } from '../runtime/create-runtime';
-/** Construct one canonical React root adapter for direct host composition. */
-export declare function createReactRootAdapter(id: string, Entry: ComponentType): ReactRootAdapter;
-/**
- * Register the engine's React adapter-root factory. This module is an
- * explicit optional React entry point: engine core never imports it, while a
- * React game host imports it once and receives the canonical root lifecycle.
- */
-export declare function registerReactAdapter(): void;
-//# sourceMappingURL=root-adapter.d.ts.map

package/dist/react/root-adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"root-adapter.d.ts","sourceRoot":"","sources":["../../src/react/root-adapter.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,OAAO,CAAC;AAG1D,OAAO,KAAK,EAAoB,gBAAgB,EAAkB,MAAM,2BAA2B,CAAC;AAQpG,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,gBAAgB,CAiBzF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAY3C"}

package/dist/react/root-adapter.js

@@ -1,41 +0,0 @@
-import { createElement } from 'react';
-import { flushSync } from 'react-dom';
-import { createRoot } from 'react-dom/client';
-import { isAdapterRegistered, registerAdapter } from '../runtime/mount-game';
-import { GameProvider } from './game-state';
-/** Construct one canonical React root adapter for direct host composition. */
-export function createReactRootAdapter(id, Entry) {
-    return {
-        id,
-        async mount(host) {
-            if (!host.game)
-                throw new Error(`React root "${id}" requires a Game host.`);
-            const reactRoot = createRoot(host.container);
-            flushSync(() => {
-                reactRoot.render(createElement(GameProvider, { game: host.game }, createElement(Entry)));
-            });
-            return {
-                kind: 'react',
-                container: host.container,
-                drivesOwnLoop: false,
-                dispose: () => reactRoot.unmount(),
-            };
-        },
-    };
-}
-/**
- * Register the engine's React adapter-root factory. This module is an
- * explicit optional React entry point: engine core never imports it, while a
- * React game host imports it once and receives the canonical root lifecycle.
- */
-export function registerReactAdapter() {
-    if (isAdapterRegistered('react'))
-        return;
-    registerAdapter('react', (root, { entryModule }) => {
-        const Entry = entryModule?.default;
-        if (!Entry) {
-            throw new Error(`React root "${root.id}" entry "${root.entry ?? '(missing)'}" must default-export a component.`);
-        }
-        return { kind: 'react', adapter: createReactRootAdapter(root.id, Entry) };
-    });
-}

package/dist/react/unmanaged-root-detector.d.ts

@@ -1,12 +0,0 @@
-export interface UnmanagedReactRootFinding {
-    readonly file: string;
-    readonly line: number;
-    readonly api: 'createRoot' | 'hydrateRoot' | 'ReactDOM.render';
-}
-/**
- * Find project-owned React DOM root creation. VGAI hosts React through
- * manifest adapter roots, so any of these calls in game source creates an
- * unmanaged second lifecycle and is a hard validation error.
- */
-export declare function detectUnmanagedReactRoots(source: string, file: string): UnmanagedReactRootFinding[];
-//# sourceMappingURL=unmanaged-root-detector.d.ts.map

package/dist/react/unmanaged-root-detector.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"unmanaged-root-detector.d.ts","sourceRoot":"","sources":["../../src/react/unmanaged-root-detector.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,aAAa,GAAG,iBAAiB,CAAC;CAChE;AAMD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,yBAAyB,EAAE,CA+C7B"}

package/dist/react/unmanaged-root-detector.js

@@ -1,45 +0,0 @@
-function lineAt(source, offset) {
-    return source.slice(0, offset).split('\n').length;
-}
-/**
- * Find project-owned React DOM root creation. VGAI hosts React through
- * manifest adapter roots, so any of these calls in game source creates an
- * unmanaged second lifecycle and is a hard validation error.
- */
-export function detectUnmanagedReactRoots(source, file) {
-    const findings = [];
-    const aliases = new Map();
-    for (const match of source.matchAll(/import\s*\{([^}]*)\}\s*from\s*['"]react-dom\/client['"]/g)) {
-        for (const member of (match[1] ?? '').split(',')) {
-            const parsed = member.trim().match(/^(createRoot|hydrateRoot)(?:\s+as\s+([\w$]+))?$/);
-            if (parsed)
-                aliases.set(parsed[2] ?? parsed[1], parsed[1]);
-        }
-    }
-    for (const [alias, api] of aliases) {
-        const call = new RegExp(`\\b${alias.replace(/[$]/g, '\\$&')}\\s*\\(`, 'g');
-        for (const match of source.matchAll(call)) {
-            findings.push({ file, line: lineAt(source, match.index ?? 0), api });
-        }
-    }
-    const namespaceNames = new Set();
-    for (const match of source.matchAll(/import\s+(?:\*\s+as\s+|)([\w$]+)\s+from\s*['"]react-dom(?:\/client)?['"]/g)) {
-        namespaceNames.add(match[1]);
-    }
-    namespaceNames.add('ReactDOM');
-    for (const name of namespaceNames) {
-        for (const api of ['createRoot', 'hydrateRoot', 'render']) {
-            const call = new RegExp(`\\b${name}\\.${api}\\s*\\(`, 'g');
-            for (const match of source.matchAll(call)) {
-                findings.push({
-                    file,
-                    line: lineAt(source, match.index ?? 0),
-                    api: api === 'render' ? 'ReactDOM.render' : api,
-                });
-            }
-        }
-    }
-    return findings.filter((finding, index) => findings.findIndex((candidate) => candidate.file === finding.file &&
-        candidate.line === finding.line &&
-        candidate.api === finding.api) === index);
-}