@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/runtime/gameplay-rng-trap.ts

@@ -0,0 +1,134 @@
+/**
+ * D15 — the dev-mode `Math.random` phase trap (`docs/D15-DETERMINISM-DESIGN.md`
+ * §2.a enforcer 3, T-D15.3). A project that declares
+ * `determinism.seededRandom` is claiming ALL gameplay RNG flows through
+ * `ctx.random` — the burn-down scan (`test/gameplay-rng-ban.test.ts`) catches
+ * raw `Math.random()`/`Date.now()`/`performance.now()` call sites it can
+ * SEE in source; this trap catches what the scan structurally can't: a
+ * TRANSITIVE draw made by a third-party library the game calls into during a
+ * gameplay tick.
+ *
+ * Scope is exactly one fixed-step frame (`GameInternal.runFrame`'s whole
+ * body — see `game.ts`'s `runFrameImpl`, which brackets its entire call with
+ * `profiler.beginFrame()`/`endFrame()`; this trap's `enable()`/`disable()`
+ * are called at those exact two points) — code that runs OUTSIDE a frame
+ * (module-load-time library init, an unrelated timer callback) never trips
+ * it. Warn-once PER CALL SITE (not once ever, not once per call) — a
+ * third-party library that draws from several different internal call sites
+ * gets one warning per site, so nothing is silently swallowed after the
+ * first hit, but a hot per-frame draw from the SAME site doesn't spam.
+ * Never throws: a cosmetic third-party draw is legal, just outside the
+ * contract (the design doc is explicit about this — "warn, never throw").
+ */
+
+export interface GameplayRngTrap {
+  /** Wrap `Math.random` for the duration of one frame — call at frame start. */
+  enable(): void;
+  /** Restore whatever `Math.random` was immediately before `enable()` — call
+   *  at frame end. A no-op if something else already replaced `Math.random`
+   *  out from under this trap between `enable()` and `disable()` (defensive;
+   *  should not happen in practice). */
+  disable(): void;
+}
+
+/** Pull a single representative "call site" line out of a captured stack —
+ *  the warn-once dedupe key. `stack[0]` is the `Error:` header line,
+ *  `stack[1]` is this trap's OWN wrapper frame — the caller's frame is the
+ *  next one down. Falls back to a fixed string when `Error().stack` isn't
+ *  populated (some non-V8 engines) so the trap still functions, just with
+ *  coarser (single-bucket) deduping. */
+function callSiteFromStack(stack: string | undefined): string {
+  if (!stack) return '<unknown call site — no stack captured>';
+  const lines = stack.split('\n');
+  return (lines[2] ?? lines[1] ?? lines[0] ?? '<unknown call site>').trim();
+}
+
+/**
+ * Construct a fresh trap. `warn` defaults to `console.warn`; tests (and any
+ * caller that wants to assert on the message) can override it to a plain
+ * capturing function instead of spying on the global console.
+ */
+export function createGameplayRngTrap(
+  warn: (message: string) => void = (message: string) => {
+    // biome-ignore lint/suspicious/noConsole: the trap's entire purpose is a structured, greppable dev-mode warning (D15) — this IS the console sink, not incidental debug output.
+    console.warn(message);
+  },
+): GameplayRngTrap {
+  const warnedSites = new Set<string>();
+  let previous: (() => number) | undefined;
+
+  function trapped(): number {
+    const site = callSiteFromStack(new Error().stack);
+    if (!warnedSites.has(site)) {
+      warnedSites.add(site);
+      warn(
+        // Deliberately NOT the literal substring "Math.random(" (the phrasing
+        // below reads fine without it) — this engine repo's OWN gameplay-rng-
+        // ban scan (`test/gameplay-rng-ban.test.ts`) greps engine src/ for
+        // that exact pattern, and a plain-text mention of the call inside
+        // this warning STRING would otherwise false-positive against itself.
+        '[determinism] the global Math.random generator was drawn from during a gameplay frame ' +
+          'while this project declares determinism.seededRandom — use ctx.random() / ' +
+          `ctx.random.stream(name) instead (docs/D15-DETERMINISM-DESIGN.md). Call site:\n${site}`,
+      );
+    }
+    // `previous` is always set by the time `trapped` can run — `enable()`
+    // assigns it before installing `trapped` as `Math.random`, and nothing
+    // else can invoke this function reference.
+    return previous!();
+  }
+
+  return {
+    enable() {
+      previous = Math.random;
+      Math.random = trapped;
+    },
+    disable() {
+      if (Math.random === trapped && previous) {
+        Math.random = previous;
+        previous = undefined;
+      }
+      // else: something else replaced `Math.random` out from under this trap
+      // between `enable()` and `disable()` — leave `previous` untouched.
+      // `trapped` may still be reachable via a chain built on top of it (e.g.
+      // a third party did `const wrapped = Math.random; Math.random = () =>
+      // { ...; return wrapped(); }` while `wrapped` was `trapped`) — nulling
+      // `previous` here would make that still-chained call to `trapped()`
+      // throw (`previous!()` on undefined) instead of quietly forwarding to
+      // the real original generator.
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Game-scoped registry — same WeakMap-on-owner-object pattern as
+// `core/seeded-random.ts`'s `registerSeededRandom`/`getSeededRandom` (and
+// `debug-registry.ts`'s `registerDebugRegistry`/`getDebugRegistry`): the
+// trap's enable/disable calls live inside `game.ts`'s `runFrameImpl`, gated
+// on a boolean only the manifest-aware boot path (`mount-manifest.ts`) knows
+// how to set — `createGame` constructs the trap unconditionally (cheap, does
+// nothing while disabled) and registers a control surface for that boot path
+// to flip once it has resolved `manifest.determinism?.seededRandom`.
+// ---------------------------------------------------------------------------
+
+export interface GameplayRngTrapControl {
+  setEnabled(enabled: boolean): void;
+  readonly enabled: boolean;
+}
+
+const controlByOwner = new WeakMap<object, GameplayRngTrapControl>();
+
+/** Called once by `createGame`, alongside `registerSeededRandom`/
+ *  `registerDebugRegistry`. */
+export function registerGameplayRngTrapControl(
+  owner: object,
+  control: GameplayRngTrapControl,
+): void {
+  controlByOwner.set(owner, control);
+}
+
+/** `null` for an owner built without one — same absence precedent as
+ *  `getSeededRandom`/`getDebugRegistry`. */
+export function getGameplayRngTrapControl(owner: object): GameplayRngTrapControl | null {
+  return controlByOwner.get(owner) ?? null;
+}

package/src/runtime/input-router.ts

@@ -1,11 +1,11 @@
 /**
  * The delegating input router (COMPOSITION-DESIGN.md D5 §2a) —
- * `createGameRuntime`'s worlds path (T6.1 slice 1,
+ * `createGameRuntime`'s roots path (T6.1 slice 1,
  * docs/MULTI-WORLD-DESIGN.md §1.C) uses this to route pointer input across
  * N stacked world canvases with exactly ONE root listener.
  *
  * Split into two layers so the decision logic is unit-testable with plain
- * fake worlds — no real DOM/canvas needed:
+ * fake roots — no real DOM/canvas needed:
  *
  *  - `stackOrder` / `resolveClaimingWorld`: pure functions over
  *    `{id, zOrder, hitTest?}` — "who claims this point".
@@ -26,21 +26,21 @@ export interface ClaimEntry {
   /**
    * Optional claim predicate over a point RELATIVE TO THE CONTAINER. Absent
    * means: "this world claims only if it is the bottom (lowest zOrder)
-   * world" — D5 §2a's stated default ("transparent upper worlds do not
+   * world" — D5 §2a's stated default ("transparent upper roots do not
    * claim, the bottom world claims everything").
    */
   readonly hitTest?: ((x: number, y: number) => boolean) | undefined;
 }
 
 /** The DOM-wiring inputs — one real canvas per world. */
-export interface RouterWorldEntry extends ClaimEntry {
+export interface RouterAdapterRoot extends ClaimEntry {
   readonly canvas: HTMLCanvasElement;
 }
 
 /**
  * Bottom-to-top paint order: ascending `zOrder`, ties -> original array
  * order — the SAME rule `manifest/load.ts`'s `loadGameManifest` sorts
- * worlds by, so a world's DOM stacking position always matches its
+ * roots by, so a world's DOM stacking position always matches its
  * manifest-resolved zOrder. The last element is the topmost (visually on
  * top / highest z-index).
  */
@@ -83,7 +83,7 @@ export function resolveClaimingWorld(
  * DOM-hit-tests it — the router's JS-level `hitTest` is what still lets it
  * claim a point via `createInputRouter`'s forwarding).
  */
-export function applyPointerEventsStacking(entries: readonly RouterWorldEntry[]): void {
+export function applyPointerEventsStacking(entries: readonly RouterAdapterRoot[]): void {
   const order = stackOrder(entries);
   order.forEach((entry, i) => {
     entry.canvas.style.pointerEvents = i === 0 ? 'auto' : 'none';
@@ -179,7 +179,7 @@ export interface InputRouterHandle {
  */
 export function createInputRouter(
   container: HTMLElement,
-  entries: readonly RouterWorldEntry[],
+  entries: readonly RouterAdapterRoot[],
 ): InputRouterHandle {
   applyPointerEventsStacking(entries);
   const byId = new Map(entries.map((e) => [e.id, e] as const));

package/src/runtime/mount-game.ts

@@ -4,22 +4,22 @@
 // duplicates its per-kind dispatch/validation) to add the one thing that
 // module deliberately does NOT have: a KIND REGISTRY, so a project doesn't
 // have to hand-build an `entries` map inline in its own `main.ts` every time
-// — it registers a `WorldKindFactory` per kind it uses (once, at module load)
+// — it registers a `AdapterSurfaceFactory` per kind it uses (once, at module load)
 // and then mounts with a single `mountGameFromManifest(manifest, host)` call.
 //
 // Engine-core react/pixi-free discipline (mirrors `mount-manifest.ts`'s own
 // header comment, and the HARD INVARIANT this file was built under): this
-// registry is pure mechanism — it holds whatever `WorldKindFactory` functions
+// registry is pure mechanism — it holds whatever `AdapterSurfaceFactory` functions
 // callers register, but it registers NONE itself. In particular there is no
 // built-in 'pixijs'/'react' registration here (that would require this file
 // to value-import `pixi.js`/`react`/`react-dom`, exactly what `mount-manifest
 // .ts` forbids); a project that has a pixijs or react world MUST register a
-// factory for that kind itself — see `defaultThreeKindFactory` below for why
+// factory for that kind itself — see `defaultThreeAdapterFactory` below for why
 // even the 'threejs' convenience export is a plain function the CALLER
 // registers, not something this module wires up automatically.
 
 import type { GameAdapter } from '../adapter/game-adapter';
-import type { ResolvedWorldEntry } from '../manifest/load';
+import type { ResolvedAdapterRoot } from '../manifest/load';
 import type { ComponentRegistry } from '../scene/component-registry';
 import type { GameSession } from './create-runtime';
 import { type MountEntry, mountManifestWorlds, resolveManifest } from './mount-manifest';
@@ -42,7 +42,7 @@ export interface ManifestHost {
   /**
    * Resolve a manifest-declared `entry` (a project-relative module path,
    * e.g. `"src/scripts/main.ts"`) to the ALREADY-IMPORTED module namespace a
-   * registered {@link WorldKindFactory} needs to build a `MountEntry` from.
+   * registered {@link AdapterSurfaceFactory} needs to build a `MountEntry` from.
    *
    * Deliberately NOT "import this arbitrary string path" — a static bundler
    * (Vite/rollup building a `dist/`) cannot resolve a runtime-computed import
@@ -55,7 +55,7 @@ export interface ManifestHost {
    */
   loadEntryModule?(path: string): Promise<unknown>;
   /** Resolve asset/scene URLs relative to the project — forwarded to a
-   *  registered {@link WorldKindFactory} via {@link WorldKindFactoryContext},
+   *  registered {@link AdapterSurfaceFactory} via {@link AdapterSurfaceFactoryContext},
    *  never called by this module itself (a factory only needs it for a
    *  non-default resolution scheme, e.g. a hosted-editor iframe). */
   resolveUrl?(path: string): string;
@@ -66,8 +66,8 @@ export interface ManifestHost {
   readonly headless?: boolean | undefined;
 }
 
-/** What a registered {@link WorldKindFactory} is handed for one world. */
-export interface WorldKindFactoryContext {
+/** What a registered {@link AdapterSurfaceFactory} is handed for one world. */
+export interface AdapterSurfaceFactoryContext {
   readonly host: ManifestHost;
   /**
    * The result of `host.loadEntryModule(world.entry)`, if the world declares
@@ -85,19 +85,19 @@ export interface WorldKindFactoryContext {
  * `examples/tri-world/src/main.ts`'s pre-E4 shape). May be async (loading an
  * asset, fetching a scene file, etc.).
  */
-export type WorldKindFactory = (
-  world: ResolvedWorldEntry,
-  ctx: WorldKindFactoryContext,
+export type AdapterSurfaceFactory = (
+  world: ResolvedAdapterRoot,
+  ctx: AdapterSurfaceFactoryContext,
 ) => MountEntry | Promise<MountEntry>;
 
 // ---------------------------------------------------------------------------
 // The registry
 // ---------------------------------------------------------------------------
 
-const registry = new Map<string, WorldKindFactory>();
+const registry = new Map<string, AdapterSurfaceFactory>();
 
 /**
- * Register a `WorldKindFactory` for a manifest world `kind` (`'threejs'` /
+ * Register a `AdapterSurfaceFactory` for a manifest world `kind` (`'threejs'` /
  * `'pixijs'` / `'react'`, or any future kind the manifest schema grows).
  * Call once, at module load — mirrors `registerSceneUIRenderer()`'s existing
  * "call before mounting" convention (`packages/editor/template/src/main.ts`).
@@ -105,14 +105,14 @@ const registry = new Map<string, WorldKindFactory>();
  * Throws on double-registration of the SAME kind: an accidental duplicate
  * (two side-effect imports of the same registration module, or a copy-paste)
  * is far more likely than an intentional runtime swap — a caller that really
- * wants to replace a registration must `unregisterWorldKind` first, making
+ * wants to replace a registration must `unregisterAdapter` first, making
  * the intent explicit.
  */
-export function registerWorldKind(kind: string, factory: WorldKindFactory): void {
+export function registerAdapter(kind: string, factory: AdapterSurfaceFactory): void {
   if (registry.has(kind)) {
     throw new Error(
-      `registerWorldKind: a factory is already registered for kind "${kind}" — ` +
-        'call unregisterWorldKind(kind) first if you intend to replace it (an accidental ' +
+      `registerAdapter: a factory is already registered for kind "${kind}" — ` +
+        'call unregisterAdapter(kind) first if you intend to replace it (an accidental ' +
         'double-registration, e.g. two side-effect imports of the same registration module, ' +
         'is far more common than an intentional swap).',
     );
@@ -121,12 +121,12 @@ export function registerWorldKind(kind: string, factory: WorldKindFactory): void
 }
 
 /** Remove a kind's registration (e.g. before re-registering a replacement). */
-export function unregisterWorldKind(kind: string): void {
+export function unregisterAdapter(kind: string): void {
   registry.delete(kind);
 }
 
 /** Whether a factory is currently registered for `kind`. */
-export function isWorldKindRegistered(kind: string): boolean {
+export function isAdapterRegistered(kind: string): boolean {
   return registry.has(kind);
 }
 
@@ -136,17 +136,17 @@ export function isWorldKindRegistered(kind: string): boolean {
  * call this; it exists so unit tests can start each case from a clean
  * registry without cross-test leakage.
  */
-export function __clearWorldKindRegistryForTests(): void {
+export function __clearAdapterSurfaceRegistryForTests(): void {
   registry.clear();
 }
 
 // ---------------------------------------------------------------------------
-// `defaultThreeKindFactory` — an OPT-IN convenience, never auto-registered
+// `defaultThreeAdapterFactory` — an OPT-IN convenience, never auto-registered
 // ---------------------------------------------------------------------------
 
 /** The entry-module export shape every first-party entry module follows
- *  (`packages/editor/template/src/scripts/main.ts`, every `examples/*`
- *  project's `src/index.ts` — see CLAUDE.md's "Adding an example project"). */
+ *  (an explicit world entry module, including `examples/*` projects'
+ *  `src/index.ts` — see CLAUDE.md's "Adding an example project"). */
 interface ThreeEntryModuleExports {
   readonly adapter?: GameAdapter;
   readonly setup?: GameSetupFn;
@@ -154,7 +154,7 @@ interface ThreeEntryModuleExports {
 }
 
 /**
- * A ready-to-register {@link WorldKindFactory} for `kind: 'threejs'` worlds
+ * A ready-to-register {@link AdapterSurfaceFactory} for `kind: 'threejs'` roots
  * that follow the first-party entry-module convention (`export const
  * adapter` and/or `export async function setup`) or are plain scene files
  * with an optional named `componentRegistry` export. Threejs is safe to
@@ -162,7 +162,7 @@ interface ThreeEntryModuleExports {
  * `VgaiSceneGameAdapter` are already unconditional engine dependencies —
  * see `mount-manifest.ts`'s header comment. Still never auto-registered:
  * the registry itself stays zero-policy (see this file's header comment) —
- * a caller opts in with `registerWorldKind('threejs', defaultThreeKindFactory)`.
+ * a caller opts in with `registerAdapter('threejs', defaultThreeAdapterFactory)`.
  *
  * Resolution mirrors `mount-manifest.ts`'s own `resolveThreeAdapter` branch
  * order: an entry module's `adapter` export wins outright; else its `setup`
@@ -171,15 +171,15 @@ interface ThreeEntryModuleExports {
  * `entry` at all) a scene-driven world, forwarding `componentRegistry` if
  * the entry module supplied one.
  */
-export const defaultThreeKindFactory: WorldKindFactory = (world, ctx) => {
+export const defaultThreeAdapterFactory: AdapterSurfaceFactory = (world, ctx) => {
   const mod = ctx.entryModule as ThreeEntryModuleExports | undefined;
   if (mod?.adapter) return { kind: 'threejs', adapter: mod.adapter };
   if (mod?.setup) return { kind: 'threejs', setup: mod.setup };
   if (world.entry !== undefined) {
     throw new Error(
-      `defaultThreeKindFactory: entry module "${world.entry}" for world "${world.id}" exports ` +
+      `defaultThreeAdapterFactory: entry module "${world.entry}" for world "${world.id}" exports ` +
         'neither `adapter` nor `setup` — every first-party entry module exports at least one ' +
-        '(see packages/editor/template/src/scripts/main.ts).',
+        '(export one from the declared entry module).',
     );
   }
   return { kind: 'threejs', componentRegistry: mod?.componentRegistry };
@@ -203,13 +203,15 @@ export interface MountGameOptions {
  *  nothing beyond the manifest itself). Every other shape (pixijs, react, an
  *  entry-declaring or module/ingest-adapter threejs world) needs SOMETHING
  *  in `entries[id]` to succeed. */
-function worldIsSelfSufficient(world: ResolvedWorldEntry): boolean {
-  return world.kind === 'threejs' && world.adapter.type === 'default' && world.entry === undefined;
+function worldIsSelfSufficient(world: ResolvedAdapterRoot): boolean {
+  return (
+    world.surface === 'threejs' && world.adapter.type === 'builtin' && world.entry === undefined
+  );
 }
 
 /**
  * Mount every world declared by a `vgai.game.json` manifest onto `host
- * .container`, resolving each world's kind through the `registerWorldKind`
+ * .container`, resolving each world's kind through the `registerAdapter`
  * registry — falling back to an explicit `opts.entries[id]` where supplied,
  * exactly like `mountManifestWorlds` (so a caller can migrate one world at a
  * time, or never touch the registry if it prefers hand-building entries).
@@ -224,7 +226,7 @@ function worldIsSelfSufficient(world: ResolvedWorldEntry): boolean {
  * into E4): a world whose kind has no registered factory AND no explicit
  * entry, and which cannot self-mount from the manifest alone, throws a named
  * `Error` identifying the world id + kind and BOTH ways to fix it
- * (`registerWorldKind` or `opts.entries`) — never a silent skip.
+ * (`registerAdapter` or `opts.entries`) — never a silent skip.
  */
 export async function mountGameFromManifest(
   manifestInput: unknown,
@@ -234,10 +236,10 @@ export async function mountGameFromManifest(
   const manifest = resolveManifest(manifestInput);
   const entries: Record<string, MountEntry> = { ...opts.entries };
 
-  for (const world of manifest.worlds) {
+  for (const world of manifest.roots) {
     if (entries[world.id] !== undefined) continue; // explicit entry always wins
 
-    const factory = registry.get(world.kind);
+    const factory = registry.get(world.adapter.identity);
     if (factory) {
       const entryModule =
         world.entry !== undefined && host.loadEntryModule
@@ -250,10 +252,10 @@ export async function mountGameFromManifest(
     if (worldIsSelfSufficient(world)) continue; // mountManifestWorlds needs nothing further
 
     throw new Error(
-      `mountGameFromManifest: world "${world.id}" (kind "${world.kind}") has no registered ` +
-        `world-kind factory and no explicit entries["${world.id}"] — call ` +
-        `registerWorldKind("${world.kind}", factory) before mounting (see ` +
-        '`defaultThreeKindFactory` for a worked threejs example), or pass ' +
+      `mountGameFromManifest: root "${world.id}" (adapter "${world.adapter.identity}") has no registered ` +
+        `adapter factory and no explicit entries["${world.id}"] — call ` +
+        `registerAdapter("${world.adapter.identity}", factory) before mounting (see ` +
+        '`defaultThreeAdapterFactory` for a worked threejs example), or pass ' +
         `opts.entries["${world.id}"] directly (see mount-manifest.ts's \`MountEntry\`).`,
     );
   }