@vgai/engine 0.5.2 → 0.5.4

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

@@ -1,10 +1,9 @@
 /**
- * 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
+ * The dev-mode `Math.random` phase trap (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.
  *
@@ -69,7 +68,7 @@ export function createGameplayRngTrap(
         // 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}`,
+          `ctx.random.stream(name) instead. Call site:\n${site}`,
       );
     }
     // `previous` is always set by the time `trapped` can run — `enable()`

package/src/runtime/input-router.ts

@@ -1,22 +1,22 @@
 /**
- * The delegating input router (COMPOSITION-DESIGN.md D5 §2a) —
- * `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.
+ * The delegating input router (D5 §2a) —
+ * `createGameRuntime`'s roots path (T6.1 slice 1) 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 roots — no real DOM/canvas needed:
  *
- *  - `stackOrder` / `resolveClaimingWorld`: pure functions over
+ *  - `stackOrder` / `resolveClaimingRoot`: pure functions over
  *    `{id, zOrder, hitTest?}` — "who claims this point".
  *  - `applyPointerEventsStacking` / `createInputRouter`: the DOM wiring —
  *    sets `pointer-events` CSS per D5 §2a and forwards a claimed event to
  *    the claiming world's own canvas.
  *
  * Per-event fall-through (D5 §2b — the sanctioned mechanism for an
- * authoring surface's own interior drag affordances, e.g. the world2d
- * editor's gizmos) is explicitly NOT this file's job (MULTI-WORLD-DESIGN.md
- * task 4) — it stays inside whatever authoring surface needs it.
+ * authoring surface's own interior drag affordances, e.g. a canvas
+ * editor's gizmos) is explicitly NOT this file's job — it stays inside
+ * whatever authoring surface needs it.
  */
 
 /** The pure decision inputs — no DOM. */
@@ -59,7 +59,7 @@ export function stackOrder<T extends ClaimEntry>(entries: readonly T[]): T[] {
  * (or via its own `hitTest`, if it declares one) — "no-claim falls to
  * bottom". Returns `null` only when `entries` is empty.
  */
-export function resolveClaimingWorld(
+export function resolveClaimingRoot(
   entries: readonly ClaimEntry[],
   x: number,
   y: number,
@@ -191,7 +191,7 @@ export function createInputRouter(
     const clientY = (evt as unknown as { clientY?: number }).clientY ?? 0;
     const x = clientX - rect.left;
     const y = clientY - rect.top;
-    const claimant = resolveClaimingWorld(entries, x, y);
+    const claimant = resolveClaimingRoot(entries, x, y);
     if (claimant && claimant !== bottomId) {
       const entry = byId.get(claimant);
       if (entry) forwardEvent(entry.canvas, evt);
@@ -203,7 +203,7 @@ export function createInputRouter(
   }
 
   return {
-    resolveClaim: (x, y) => resolveClaimingWorld(entries, x, y),
+    resolveClaim: (x, y) => resolveClaimingRoot(entries, x, y),
     dispose() {
       for (const type of ROUTED_EVENT_TYPES) {
         container.removeEventListener?.(type, handler, true);

package/src/runtime/mount-game.ts

@@ -1,28 +1,26 @@
-// E4 — the S-D composer (docs/unified-world-editor/27-visual-react-editing.md
-// §7 E4; design lineage docs/unified-world-editor/26-unified-editor-spec.md
-// §5 Stage S-D). Builds ON `mount-manifest.ts`'s `mountManifestWorlds` (never
-// 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 `AdapterSurfaceFactory` per kind it uses (once, at module load)
-// and then mounts with a single `mountGameFromManifest(manifest, host)` call.
+// The S-D composer (design lineage Stage S-D). Builds ON `mount-manifest.ts`'s
+// `mountManifestRoots` (never 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 `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 `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
+// built-in 'canvas'/'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
+// .ts` forbids); a project that has a canvas or react world MUST register a
 // factory for that kind itself — see `defaultThreeAdapterFactory` below for why
-// even the 'threejs' convenience export is a plain function the CALLER
+// even the 'three' 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 { RootAdapter } from '../adapter/root-adapter';
 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';
+import { type MountEntry, mountManifestRoots, resolveManifest } from './mount-manifest';
 import type { GameSetupFn } from './types';
 
 // ---------------------------------------------------------------------------
@@ -37,7 +35,7 @@ import type { GameSetupFn } from './types';
  */
 export interface ManifestHost {
   /** The host creates one absolutely-positioned surface per world inside
-   *  this element — see `WorldsRuntimeConfig.container`. */
+   *  this element — see `RootsRuntimeConfig.container`. */
   readonly container: HTMLElement;
   /**
    * Resolve a manifest-declared `entry` (a project-relative module path,
@@ -62,7 +60,7 @@ export interface ManifestHost {
   readonly width?: number | undefined;
   readonly height?: number | undefined;
   /** Forwarded to `createGameRuntime` — Node/headless test harnesses only,
-   *  never a real host. See `WorldsRuntimeConfig.headless`. */
+   *  never a real host. See `RootsRuntimeConfig.headless`. */
   readonly headless?: boolean | undefined;
 }
 
@@ -80,7 +78,7 @@ export interface AdapterSurfaceFactoryContext {
 /**
  * A caller-registered per-kind mount strategy: given the world's resolved
  * manifest entry and the loaded entry module (if any), produce the
- * `MountEntry` `mountManifestWorlds` needs to mount it (exactly what a
+ * `MountEntry` `mountManifestRoots` needs to mount it (exactly what a
  * project used to hand-build inline as its own `entries[id]` — see
  * `examples/tri-world/src/main.ts`'s pre-E4 shape). May be async (loading an
  * asset, fetching a scene file, etc.).
@@ -97,8 +95,8 @@ export type AdapterSurfaceFactory = (
 const registry = new Map<string, AdapterSurfaceFactory>();
 
 /**
- * Register a `AdapterSurfaceFactory` for a manifest world `kind` (`'threejs'` /
- * `'pixijs'` / `'react'`, or any future kind the manifest schema grows).
+ * Register a `AdapterSurfaceFactory` for a manifest world `kind` (`'three'` /
+ * `'canvas'` / `'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`).
  *
@@ -148,33 +146,29 @@ export function __clearAdapterSurfaceRegistryForTests(): void {
  *  (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 adapter?: RootAdapter;
   readonly setup?: GameSetupFn;
-  readonly componentRegistry?: ComponentRegistry;
 }
 
 /**
- * A ready-to-register {@link AdapterSurfaceFactory} for `kind: 'threejs'` roots
+ * A ready-to-register {@link AdapterSurfaceFactory} for `kind: 'three'` 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
- * ship as an exported convenience (unlike pixijs/react) because `three`/
- * `VgaiSceneGameAdapter` are already unconditional engine dependencies —
+ * adapter` and/or `export async function setup`). Threejs is safe to
+ * ship as an exported convenience (unlike canvas/react) because `three`/
+ * `SetupThreeRootAdapter` 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 `registerAdapter('threejs', defaultThreeAdapterFactory)`.
+ * a caller opts in with `registerAdapter('three', defaultThreeAdapterFactory)`.
  *
  * Resolution mirrors `mount-manifest.ts`'s own `resolveThreeAdapter` branch
  * order: an entry module's `adapter` export wins outright; else its `setup`
- * export (wrapping via `fromSetup` happens inside `mountManifestWorlds`
- * itself — this factory just returns the `MountEntry` shape); else (no
- * `entry` at all) a scene-driven world, forwarding `componentRegistry` if
- * the entry module supplied one.
+ * export (wrapping via `fromSetup` happens inside `mountManifestRoots`
+ * itself — this factory just returns the `MountEntry` shape).
  */
 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 (mod?.adapter) return { kind: 'three', adapter: mod.adapter };
+  if (mod?.setup) return { kind: 'three', setup: mod.setup };
   if (world.entry !== undefined) {
     throw new Error(
       `defaultThreeAdapterFactory: entry module "${world.entry}" for world "${world.id}" exports ` +
@@ -182,7 +176,10 @@ export const defaultThreeAdapterFactory: AdapterSurfaceFactory = (world, ctx) =>
         '(export one from the declared entry module).',
     );
   }
-  return { kind: 'threejs', componentRegistry: mod?.componentRegistry };
+  throw new Error(
+    `defaultThreeAdapterFactory: world "${world.id}" declares no \`entry\` — a three root is ` +
+      'authored as a TSX/R3F world module; point `entry` at it.',
+  );
 };
 
 // ---------------------------------------------------------------------------
@@ -190,30 +187,32 @@ export const defaultThreeAdapterFactory: AdapterSurfaceFactory = (world, ctx) =>
 // ---------------------------------------------------------------------------
 
 export interface MountGameOptions {
-  /** Explicit per-world entries, same shape `mountManifestWorlds` accepts —
+  /** Explicit per-world entries, same shape `mountManifestRoots` accepts —
    *  ALWAYS wins over a registered kind factory for that world id (backward
    *  compat: a caller mid-migration, or one that just prefers building one
    *  entry by hand, never has to touch the registry at all). */
   readonly entries?: Readonly<Record<string, MountEntry>> | undefined;
 }
 
-/** True for the one shape `mountManifestWorlds` can ALREADY mount with zero
- *  `entries[id]` at all (a plain `default`-adapter, scene-driven, no-`entry`
- *  threejs world — `resolveThreeAdapter`'s own scene branch, which needs
- *  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: ResolvedAdapterRoot): boolean {
-  return (
-    world.surface === 'threejs' && world.adapter.type === 'builtin' && world.entry === undefined
-  );
+/** True for the one shape `mountManifestRoots` can ALREADY mount with zero
+ *  `entries[id]` at all.
+ *
+ *  WO-8: nothing is self-sufficient any more. The one shape that was — a plain
+ *  `default`-adapter, SCENE-driven, no-`entry` three world, which
+ *  `resolveThreeAdapter`'s scene branch could mount from the manifest alone —
+ *  died with the `.vscn.json` format. `load.ts` now rejects a three root with no
+ *  `entry` outright, so every world needs a registered factory or an explicit
+ *  entry, and this predicate is retained only to keep the loud-degrade error the
+ *  documented outcome rather than a silent skip. */
+function worldIsSelfSufficient(_world: ResolvedAdapterRoot): boolean {
+  return false;
 }
 
 /**
- * Mount every world declared by a `vgai.game.json` manifest onto `host
+ * Mount every world declared by a `vgai.project.json` manifest onto `host
  * .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
+ * exactly like `mountManifestRoots` (so a caller can migrate one world at a
  * time, or never touch the registry if it prefers hand-building entries).
  *
  * This is the "one call" scaffold/example projects mount through (E4
@@ -222,11 +221,11 @@ function worldIsSelfSufficient(world: ResolvedAdapterRoot): boolean {
  * `packages/editor/template/src/main.ts` for the worked single-world
  * example and `examples/tri-world/src/main.ts` for a multi-kind one.
  *
- * Degrades loudly (`docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md` D-Z2, carried
- * 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
- * (`registerAdapter` or `opts.entries`) — never a silent skip.
+ * Degrades loudly (carried 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 (`registerAdapter` or `opts.entries`) — never a silent
+ * skip.
  */
 export async function mountGameFromManifest(
   manifestInput: unknown,
@@ -249,18 +248,18 @@ export async function mountGameFromManifest(
       continue;
     }
 
-    if (worldIsSelfSufficient(world)) continue; // mountManifestWorlds needs nothing further
+    if (worldIsSelfSufficient(world)) continue; // mountManifestRoots needs nothing further
 
     throw new Error(
       `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 ' +
+        '`defaultThreeAdapterFactory` for a worked three example), or pass ' +
         `opts.entries["${world.id}"] directly (see mount-manifest.ts's \`MountEntry\`).`,
     );
   }
 
-  return mountManifestWorlds({
+  return mountManifestRoots({
     manifest,
     container: host.container,
     entries,