@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/input/input-manager.ts

@@ -40,7 +40,7 @@ function isTextEntryFocused(): boolean {
 
 /**
  * Thrown by `InputManager.setVirtualAction`/`tapVirtualAction` (Task 1.4,
- * ACCEPTANCE-DRIVER-BUILD-PLAN.md / SYNTHETIC-PLAYER-SPEC.md §3.2) for an
+ * E2E-TESTING-BUILD-PLAN.md / SYNTHETIC-PLAYER-SPEC.md §3.2) for an
  * action name that was never `registerAction`/`loadMap`-ed. Carries a
  * machine-readable `code` and `data.registered` (every declared action name)
  * rather than requiring a caller to parse the message.
@@ -360,7 +360,7 @@ export class InputManager {
   private static isStickActive(v: Vector2): boolean {
     return Math.hypot(v.x, v.y) > 0.3;
   }
-  // Task 1.4 (ACCEPTANCE-DRIVER-BUILD-PLAN.md) — action-level virtual input
+  // Task 1.4 (E2E-TESTING-BUILD-PLAN.md) — action-level virtual input
   // for a synthetic player, promoted from hollowstone's `VirtualInput`. Held
   // digitals OR into isPressed alongside binding contributions (like
   // touchButtonsDown above); tap queues, then is promoted to "active" for
@@ -468,7 +468,7 @@ export class InputManager {
    *  Window focus deliberately does not participate: a synthetic player
    *  drives the shared editor tab precisely while the human's focus is
    *  elsewhere (their terminal, another window) — the first live in-editor
-   *  probe run froze mid-suite the moment the owner started typing to their
+   *  E2E run froze mid-suite the moment the owner started typing to their
    *  agent, which is the bug this gate split fixes. Real-device input keeps
    *  the stricter `inputActive` (enabled AND focused) gate above. */
   private get machineInputActive(): boolean {
@@ -614,13 +614,15 @@ export class InputManager {
   }
 
   constructor() {
-    window.addEventListener('keydown', this.onKeyDown);
-    window.addEventListener('keyup', this.onKeyUp);
-    window.addEventListener('mousedown', this.onMouseDown);
-    window.addEventListener('mouseup', this.onMouseUp);
-    window.addEventListener('mousemove', this.onMouseMove);
-    window.addEventListener('blur', this.onWindowBlur);
-    window.addEventListener('focus', this.onWindowFocus);
+    if (typeof window !== 'undefined') {
+      window.addEventListener('keydown', this.onKeyDown);
+      window.addEventListener('keyup', this.onKeyUp);
+      window.addEventListener('mousedown', this.onMouseDown);
+      window.addEventListener('mouseup', this.onMouseUp);
+      window.addEventListener('mousemove', this.onMouseMove);
+      window.addEventListener('blur', this.onWindowBlur);
+      window.addEventListener('focus', this.onWindowFocus);
+    }
     // `document` isn't touched by any pre-F2 code path (the headless vitest
     // env stubs `window` only) — guard the same way `isTextEntryFocused` does
     // so tests that don't need pointer-lock coverage need no `document` stub.
@@ -830,7 +832,8 @@ export class InputManager {
       return;
     }
 
-    this.gamepads = navigator.getGamepads ? [...navigator.getGamepads()] : [];
+    this.gamepads =
+      typeof navigator !== 'undefined' && navigator.getGamepads ? [...navigator.getGamepads()] : [];
 
     // Gamepad button edge detection: diff this frame's pressed set against the
     // previous frame's so isJustPressed/isJustReleased work for gamepads too.
@@ -2004,7 +2007,7 @@ export class InputManager {
   }
 
   // ==========================================================================
-  // Task 1.4 (ACCEPTANCE-DRIVER-BUILD-PLAN.md / SYNTHETIC-PLAYER-SPEC.md §3.2)
+  // Task 1.4 (E2E-TESTING-BUILD-PLAN.md / SYNTHETIC-PLAYER-SPEC.md §3.2)
   // — action-level virtual input for a synthetic player. Promoted from
   // hollowstone's proven `VirtualInput` (`bot/virtual-input.ts`): a bot drives
   // NAMED ACTIONS (not raw devices), and its contributions join action
@@ -2274,13 +2277,15 @@ export class InputManager {
   dispose() {
     if (this.disposed) return;
     this.disposed = true;
-    window.removeEventListener('keydown', this.onKeyDown);
-    window.removeEventListener('keyup', this.onKeyUp);
-    window.removeEventListener('mousedown', this.onMouseDown);
-    window.removeEventListener('mouseup', this.onMouseUp);
-    window.removeEventListener('mousemove', this.onMouseMove);
-    window.removeEventListener('blur', this.onWindowBlur);
-    window.removeEventListener('focus', this.onWindowFocus);
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('keydown', this.onKeyDown);
+      window.removeEventListener('keyup', this.onKeyUp);
+      window.removeEventListener('mousedown', this.onMouseDown);
+      window.removeEventListener('mouseup', this.onMouseUp);
+      window.removeEventListener('mousemove', this.onMouseMove);
+      window.removeEventListener('blur', this.onWindowBlur);
+      window.removeEventListener('focus', this.onWindowFocus);
+    }
     if (typeof document !== 'undefined' && typeof document.removeEventListener === 'function') {
       document.removeEventListener('pointerlockchange', this.onPointerLockChange);
     }

package/src/input/input-types.ts

@@ -91,7 +91,7 @@ export type ActionValueOf<T extends ActionValueType> = T extends 'digital'
  */
 export interface ActionValueSource {
   /** The binding kind that produced the current value. `'virtual'` (Task 1.4,
-   *  ACCEPTANCE-DRIVER-BUILD-PLAN.md) is not a real `InputBinding` — it marks a
+   *  E2E-TESTING-BUILD-PLAN.md) is not a real `InputBinding` — it marks a
    *  value written by `InputManager.setVirtualAction` (the synthetic-player
    *  seat), not a device binding. */
   bindingType: InputBinding['type'] | 'virtual';

package/src/loader.ts

@@ -11,6 +11,7 @@
  */
 
 import * as THREE from 'three';
+import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';
 import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
 import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
 
@@ -51,6 +52,12 @@ dracoLoader.setDecoderPath('/jsm/libs/draco/gltf/');
 /** Pre-configured GLTFLoader using the shared manager, with DRACO decoding wired in. */
 export const gltfLoader = new GLTFLoader(loadingManager);
 gltfLoader.setDRACOLoader(dracoLoader);
+// EXT_meshopt_compression decoding (three's own bundled decoder — inline
+// wasm, no fetch). Without this, a meshopt-compressed GLB — including the
+// output of the editor's Asset Budget "Compress · meshopt" action (W4a M3) —
+// throws at load time in every runtime and the editor viewport. Symmetric
+// with the DRACO wiring above (CB2): the ONE shared loader owns codec setup.
+gltfLoader.setMeshoptDecoder(MeshoptDecoder);
 
 /**
  * Set the URL prefix prepended to relative asset paths.

package/src/manifest/load.ts

@@ -119,6 +119,19 @@ export interface ResolvedGameManifest {
   readonly determinism:
     | { readonly seededRandom: boolean; readonly defaultSeed?: number | undefined }
     | undefined;
+  /** W3d (F11 perf gates) — read by `vgai perf --assert-budget`
+   *  (packages/vgai-cli/src/perf.ts, assertBudget): each set metric is
+   *  compared against the seeded headless perf run's measured value and any
+   *  exceedance fails the gate with a per-metric table + nonzero exit. */
+  readonly budget:
+    | {
+        readonly frameCpuMsP95?: number | undefined;
+        readonly physicsMsP95?: number | undefined;
+        readonly maxEntities?: number | undefined;
+        readonly maxDrawCalls?: number | undefined;
+        readonly maxTriangles?: number | undefined;
+      }
+    | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -427,5 +440,6 @@ export function loadGameManifest(raw: unknown): ResolvedGameManifest {
     authoring: manifest.authoring,
     debug: manifest.debug,
     determinism: manifest.determinism,
+    budget: manifest.budget,
   };
 }

package/src/manifest/schema.ts

@@ -475,6 +475,71 @@ export const GameManifestSchema = z
           'whether ctx.random is boot-seeded from a reproducible seed and whether the ' +
           'gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.',
       ),
+    budget: z
+      .object({
+        frameCpuMsP95: z
+          .number()
+          .positive()
+          .optional()
+          .describe(
+            'Maximum allowed p95 of per-frame CPU time (ms) across the measured frames of a ' +
+              '`vgai perf` seeded headless run. CPU-side only: headless runs rasterize under ' +
+              'SwiftShader, so this is main-thread frame cost, NOT real GPU frame time. ' +
+              'Machine-dependent — prefer the baseline-diff tolerance band for regression ' +
+              'gating and use this as a coarse absolute ceiling.',
+          ),
+        physicsMsP95: z
+          .number()
+          .positive()
+          .optional()
+          .describe(
+            "Maximum allowed p95 of the profiler's `physics` phase time (ms) per fixed-step " +
+              'frame in a `vgai perf` run. Same CPU-timing caveats as frameCpuMsP95.',
+          ),
+        maxEntities: z
+          .number()
+          .int()
+          .nonnegative()
+          .optional()
+          .describe(
+            'Maximum allowed entity-tagged scene-graph nodes (nodes carrying ' +
+              "userData.entityId) summed across the game's threejs/pixijs worlds at the end " +
+              'of a `vgai perf` run. Exact and deterministic under a seed — no tolerance band.',
+          ),
+        maxDrawCalls: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe(
+            'Maximum allowed renderer draw calls in any measured frame of a `vgai perf` run ' +
+              "(the profiler's per-frame render.drawCalls, from renderer.info). Exact and " +
+              'deterministic under a seed.',
+          ),
+        maxTriangles: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe(
+            'Maximum allowed rendered triangles in any measured frame of a `vgai perf` run ' +
+              "(the profiler's per-frame render.triangles, from renderer.info). Exact and " +
+              'deterministic under a seed.',
+          ),
+      })
+      .refine((budget) => Object.values(budget).some((value) => value !== undefined), {
+        message:
+          'Game manifest: `budget` must set at least one metric (frameCpuMsP95, physicsMsP95, ' +
+          'maxEntities, maxDrawCalls, maxTriangles) — an empty budget block gates nothing ' +
+          '(T4.1 no-dead-fields policy).',
+      })
+      .optional()
+      .describe(
+        'Performance budget (W3d, F11 perf regression gates) asserted by ' +
+          '`vgai perf --assert-budget`: a seeded, fixed-step headless run samples the engine ' +
+          'profiler and fails (nonzero exit) when any metric here is exceeded. Only ' +
+          'headlessly-measurable metrics are budgetable; real GPU frame time is not (SwiftShader).',
+      ),
   })
   .strict()
   .describe('Game manifest (vgai.game.json) — the complete v2 project configuration');

package/src/react/game-state.tsx

@@ -223,7 +223,7 @@ export function useDebugProvider(
  *
  * 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
+ * finding — `docs/E2E-TESTING-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.

package/src/render/render-batch-system.ts

@@ -84,6 +84,29 @@ function entityOptOut(obj: THREE.Object3D): boolean {
   return nearestEntity(obj)?.render?.autoBatch === false;
 }
 
+/** Match Three.js renderer visibility: a hidden ancestor hides the whole subtree. */
+function isEffectivelyVisible(obj: THREE.Object3D): boolean {
+  let cur: THREE.Object3D | null = obj;
+  while (cur) {
+    if (!cur.visible) return false;
+    cur = cur.parent;
+  }
+  return true;
+}
+
+function isBatchCandidate(object: THREE.Object3D, batchRoot: THREE.Group): object is THREE.Mesh {
+  const mesh = object as THREE.Mesh;
+  if (!mesh.isMesh) return false;
+  if ((mesh as THREE.InstancedMesh).isInstancedMesh) return false;
+  if ((mesh as THREE.SkinnedMesh).isSkinnedMesh) return false;
+  if ((mesh as unknown as THREE.BatchedMesh).isBatchedMesh) return false;
+  if (!isEffectivelyVisible(mesh)) return false;
+  if (!mesh.geometry || !mesh.material || Array.isArray(mesh.material)) return false;
+  if ((mesh.material as THREE.Material).transparent) return false;
+  if (batchRoot === mesh.parent) return false;
+  return !entityOptOut(mesh);
+}
+
 /**
  * Static-batching eligibility: only entities that won't move are safe to freeze
  * and instance. An entity with physics, behavior components, or its own animation
@@ -126,19 +149,10 @@ export class RenderBatchSystem {
     // collect eligible candidates, grouped by (geometry, material)
     const buckets = new Map<string, THREE.Mesh[]>();
     this.scene.traverse((obj) => {
-      const m = obj as THREE.Mesh;
-      if (!m.isMesh) return;
-      if ((m as THREE.InstancedMesh).isInstancedMesh) return;
-      if ((m as THREE.SkinnedMesh).isSkinnedMesh) return;
-      if ((m as unknown as THREE.BatchedMesh).isBatchedMesh) return;
-      if (!m.visible) return;
-      if (!m.geometry || !m.material || Array.isArray(m.material)) return;
-      if ((m.material as THREE.Material).transparent) return;
-      if (this.root === m.parent) return; // our own instances
-      if (entityOptOut(m)) return;
-      const key = SIG(m);
+      if (!isBatchCandidate(obj, this.root)) return;
+      const key = SIG(obj);
       const arr = buckets.get(key) ?? [];
-      arr.push(m);
+      arr.push(obj);
       buckets.set(key, arr);
     });
 

package/src/render/spark-renderer-lifecycle.ts

@@ -0,0 +1,64 @@
+import type { SparkRenderer } from '@sparkjsdev/spark';
+import type * as THREE from 'three';
+import { hasUserData } from '../scene/user-data';
+
+const IDLE_POLL_MS = 16;
+const MAX_IDLE_WAIT_MS = 3_000;
+export const SPARK_DISCOVERY_INTERVAL_MS = 500;
+
+/** Gate fallback discovery so ordinary non-splat scenes are never traversed every frame. */
+export function shouldDiscoverGaussianSplat(lastCheckAt: number, now: number): boolean {
+  return now - lastCheckAt >= SPARK_DISCOVERY_INTERVAL_MS;
+}
+
+/** True when a native scene currently contains at least one Gaussian payload. */
+export function sceneHasGaussianSplat(scene: THREE.Object3D): boolean {
+  let found = false;
+  scene.traverse((object) => {
+    if (!found && hasUserData(object, 'gaussianSplat')) found = true;
+  });
+  return found;
+}
+
+/**
+ * Stop and dispose Spark after its asynchronous depth-sort worker is idle.
+ *
+ * SparkRenderer.dispose() rejects any worker calls still in flight. Spark's
+ * automatic update path intentionally does not await those calls, so disposing
+ * synchronously during an editor stop otherwise produces an unhandled
+ * `Worker terminate` rejection. Disable future work immediately, then release
+ * the renderer once the current sort has naturally settled.
+ */
+export function disposeSparkRendererWhenIdle(renderer: SparkRenderer): void {
+  renderer.autoUpdate = false;
+  renderer.sortDirty = false;
+
+  if (renderer.updateTimeoutId !== -1) {
+    clearTimeout(renderer.updateTimeoutId);
+    renderer.updateTimeoutId = -1;
+  }
+  if (renderer.sortTimeoutId !== -1) {
+    clearTimeout(renderer.sortTimeoutId);
+    renderer.sortTimeoutId = -1;
+  }
+
+  let remainingIdleWaitMs = MAX_IDLE_WAIT_MS;
+  const disposeWhenIdle = (): void => {
+    if (renderer.sorting) {
+      if (remainingIdleWaitMs > 0) {
+        remainingIdleWaitMs -= IDLE_POLL_MS;
+        setTimeout(disposeWhenIdle, IDLE_POLL_MS);
+      } else {
+        // A stuck upstream worker is safer to abandon than to turn a routine
+        // editor stop into an unhandled rejection. Page teardown will reclaim
+        // the worker; normal sorts complete in a few milliseconds.
+        // biome-ignore lint/suspicious/noConsole: This rare upstream worker leak must degrade loudly.
+        console.warn('SparkRenderer did not become idle; skipped worker termination.');
+      }
+      return;
+    }
+    renderer.dispose();
+  };
+
+  disposeWhenIdle();
+}

package/src/runtime/create-runtime.ts

@@ -88,6 +88,12 @@ export function registerThreeWorld(
   // world directly at attach time, unaffected by this call.
   if (isFirstPartyMounted(mounted)) {
     mounted.ctx.components.adoptWorld(world);
+  } else if (mounted.components) {
+    // Same one-time backfill for a non-first-party mount exposing the
+    // optional `MountedWorldBase.components` capability (e.g.
+    // `@engine/world3d-react` — its `<Behavior>` attaches happened during
+    // `mount()`, before this `WorldInstance` existed).
+    mounted.components.adoptWorld(world);
   }
   game.registerWorld(world);
   return world;
@@ -407,7 +413,10 @@ export interface GameSession {
   pause(): void;
   resume(): void;
   step(): void;
-  resize(width: number, height: number): void;
+  /** Resize every world's render buffer. `pixelRatio` (W2c device preview)
+   *  optionally re-pins the threejs renderers' DPR in the same pass; omitted,
+   *  the mount-time ratio is left untouched (legacy behavior). */
+  resize(width: number, height: number, pixelRatio?: number): void;
   readonly scene: THREE.Scene;
   readonly camera: THREE.PerspectiveCamera;
   /** The mounted game (interface surface). Cast to `VgaiMountedGame` for first-party extras. */
@@ -616,14 +625,15 @@ async function mountOneThreeWorld(
  *  did (never self-healing, by design — see above). */
 async function mountOnePixiWorld(
   spec: PixiWorldMountSpec,
-  ctx: Omit<OneWorldContext, 'headless' | 'loopHandle' | 'assets'>,
+  ctx: Omit<OneWorldContext, 'loopHandle' | 'assets'>,
 ): Promise<OneWorldResult> {
-  const { game, canvas, w, h, dpr, isBottom } = ctx;
+  const { game, canvas, w, h, dpr, headless, isBottom } = ctx;
   const pixiHost: World2DHost = {
     canvas,
     width: w,
     height: h,
     game,
+    headless,
     dpr,
     transparent: !isBottom,
     preserveDrawingBuffer: true,
@@ -846,6 +856,7 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
   stacked.forEach((entry, i) => {
     const isReact = kindById.get(entry.id) === 'react';
     const surface = document.createElement(isReact ? 'div' : 'canvas') as HTMLElement;
+    surface.dataset['vgaiWorldSurface'] = 'true';
     if (!isReact) {
       const canvas = surface as unknown as HTMLCanvasElement;
       canvas.width = w;
@@ -938,8 +949,20 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
       entry.mounted.dispose();
       entry.renderer?.dispose();
       entry.renderer?.forceContextLoss();
-      container.removeChild(entry.element);
+      // Remove from the element's CURRENT parent, not the mount-time
+      // `container`: the editor's Game panel re-parents the live surfaces
+      // when its mount element swaps (fill <-> device preset, W2c), and
+      // `container.removeChild` would throw NotFoundError after such a move.
+      // `container` remains the fallback for hosts whose element stand-ins
+      // never wire `parentNode` (headless unit fixtures); an element already
+      // detached by such a host is a no-op via the catch.
+      try {
+        (entry.element.parentNode ?? container).removeChild(entry.element);
+      } catch {
+        /* already detached — nothing to remove */
+      }
     }
+    game.dispose();
     retractDevGlobals();
   }
 
@@ -960,10 +983,15 @@ async function createWorldsGameRuntime(config: WorldsRuntimeConfig): Promise<Gam
     step() {
       game.play.step();
     },
-    resize(rw: number, rh: number) {
+    resize(rw: number, rh: number, pixelRatio?: number) {
       const safeWidth = Math.max(1, rw);
       const safeHeight = Math.max(1, rh);
       for (const entry of mountedEntries) {
+        // W2c device preview: re-pin DPR before setSize so the drawing
+        // buffer (and the first-party composer, whose `mounted.resize` reads
+        // `getDrawingBufferSize`) picks it up in this same pass. Pixi/react
+        // worlds have no `entry.renderer` and keep their own resolution.
+        if (pixelRatio !== undefined) entry.renderer?.setPixelRatio(pixelRatio);
         entry.renderer?.setSize(safeWidth, safeHeight, false);
         entry.mounted.resize?.(safeWidth, safeHeight);
       }

package/src/runtime/debug-bridge.ts

@@ -1,6 +1,6 @@
 /**
  * The standalone in-page debug bridge (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.4,
- * D17/D18; Task 2.1 of `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md`). Query-gated
+ * D17/D18; Task 2.1 of `docs/E2E-TESTING-BUILD-PLAN.md`). Query-gated
  * `window.__vgai`, the same production-protection-lives-in-the-installer
  * pattern `render-control.ts`'s `installRenderControlHarness` established for
  * `?vgai-render=1` (production protection lives HERE, not just at whatever
@@ -9,7 +9,7 @@
  * ever gets a handle when the gate below actually passes).
  *
  * D17: this is door (a) of the seam's three doors — the SAME `DebugAdapter`
- * names/JSON the editor relay (door b) and `@vgai/probe` (door c, which
+ * names/JSON the editor relay (door b) and `@vgai/e2e` (door c, which
  * drives door (a) itself over Playwright) all read. D18: the bridge installs
  * only when the page opts in (`?vgai-debug=1`) AND is either a dev build
  * (`import.meta.env.DEV`) or the project's manifest explicitly opts a
@@ -152,7 +152,7 @@ export interface VgaiDebugHandle {
    * this is the honest human-input-path proof) → `input.clearVirtualActions()`
    * into ONE async bridge call, as a TOP-LEVEL method (not under `input`)
    * because it needs the sim clock, not just the input target. Was 15+
-   * transport round trips over the editor relay (`@vgai/probe`'s old
+   * transport round trips over the editor relay (`@vgai/e2e`'s old
    * `GameInput.hold`: set → a 150ms-interval `waitSimTime` snapshot poll loop
    * → clear); now one `page.evaluate`/relay call that runs the wait
    * in-process on the page.
@@ -224,13 +224,13 @@ export interface MaybeInstallDebugBridgeOptions {
 const PAGE_ERROR_CAP = 100;
 
 /** `holdFor`'s in-process poll interval — this loop never leaves the page
- *  (no transport round trip per poll, unlike `@vgai/probe`'s old
+ *  (no transport round trip per poll, unlike `@vgai/e2e`'s old
  *  `waitSimTime`), so it can afford to be tighter than that loop's 150ms. */
 const HOLD_FOR_POLL_MS = 50;
 
 /** Consecutive `HOLD_FOR_POLL_MS` polls with the tick unchanged before
  *  `holdFor` gives up waiting and treats the game as stopped — mirrors
- *  `@vgai/probe`'s `WAIT_FOR_STALL_POLL_LIMIT` reasoning (`wait-for.ts`:
+ *  `@vgai/e2e`'s `WAIT_FOR_STALL_POLL_LIMIT` reasoning (`wait-for.ts`:
  *  a genuinely frozen sim clock must never poll forever), scaled to this
  *  faster in-process interval so the wall-clock grace period (~5s) lands in
  *  the same neighborhood. */