@vgai/engine 0.5.15 → 0.5.17

package/src/runtime/create-runtime.ts

@@ -31,12 +31,11 @@ import type { PlaytestContext } from './types';
  * by `createGameRuntime` and every headless test harness
  * (`test/game-root.test.ts`, `test/frame-order.test.ts`,
  * `test/game-two-roots.test.ts`) so there is exactly one code path for this
- * wiring (T7.1 slice 1, id-generalized in slice 3 for the two-world proof — stage
- * 3) — `physics`/`collisions`/`camera`/ `frame` are populated from the mount's
+ * wiring. `physics`/`collisions`/`camera`/`frame` are populated from the mount's
  * first-party `GameContext`/ `MountedSetupThreeRoot` when available, left
  * `undefined` otherwise (an external adapter's mount has none of these
  * first-party handles — `frame` in particular is what makes
- * `GameInternal.runFrame` (T7.1 slice 2) fall back to a single opaque
+ * `GameInternal.runFrame` fall back to a single opaque
  * `mounted.update` call per substep for such a world).
  */
 function firstPartyExtras(
@@ -53,10 +52,8 @@ function firstPartyExtras(
 
 /**
  * Register a three world onto the Game shell. `opts.id` defaults to
- * `'main'` — the single-world callers (`createGameRuntime`, slice-1/2 tests)
- * are unaffected; a second/third world (T7.1 slice 3's two-world proof, and
- * real multi-world manifests later) pass an explicit id. This is the ONE
- * registration code path for a three world, whatever its id.
+ * `'main'`; multi-root callers pass an explicit id. This is the one
+ * registration path for a three world, whatever its id.
  */
 export function registerThreeRoot(
   game: GameInternal,
@@ -104,13 +101,13 @@ export function registerPixiRoot(
 }
 
 /**
- * Register a react world onto the Game shell (T6.2 slice 1) — the react
+ * Register a React world onto the Game shell — the DOM
  * analog of {@link registerThreeRoot}/{@link registerPixiRoot}. A react
  * world has no `frame` hooks (react's own
  * `createRoot` schedules its commits; `GameInternal.runFrame` correctly
  * leaves a world with no `frame` untouched by its opaque-`update` fallback
  * too, since `MountedReactGame` declares no `update`). `adapter` is typed
- * as the real {@link ReactRootAdapter} shape (T7.5, same reasoning as
+ * as the real {@link ReactRootAdapter} shape (same reasoning as
  * `registerPixiRoot`'s doc comment above) — `RootInstance.adapter` only
  * needs `.id`, so this passes through with zero cast.
  */
@@ -134,12 +131,12 @@ export function registerReactRoot(
 }
 
 /**
- * One world to mount in the {@link RootsRuntimeConfig} roots path (T6.1
- * slice 1) — the host-facing mirror of `manifest/load.ts`'s
- * `ResolvedAdapterRoot` (same `id`/`zOrder`/`pausable`/`loop` fields; the
+ * One world to mount in the universal host — the host-facing mirror of
+ * `manifest/load.ts`'s `ResolvedAdapterRoot` (same identity and presentation
+ * fields; the
  * manifest-to-host translation itself is the editor's job, not this file's).
  *
- * `react` (T6.2 slice 1) mounts as a DOM-root layer `<div>` in the SAME
+ * A `dom` root mounts as a DOM layer `<div>` in the same
  * stack instead of a canvas — see {@link ReactRootMountSpec}/{@link
  * ReactRootAdapter} below.
  */
@@ -152,28 +149,6 @@ export interface RootMountSpecBase {
   readonly zOrder?: number | undefined;
   /** Whether play-mode pause/step applies to this world (D10). Defaults to `true`. */
   readonly pausable?: boolean | undefined;
-  /**
-   * `vgai.project.json`'s `dev: true` — this root is a DEV LAYER (the game's
-   * own dev GUI), not shipped game content. Two things happen here: the
-   * surface is stacked ABOVE every non-dev root (a dev layer sits topmost),
-   * and it is marked `data-vgai-dev-layer="true"` so the play compositor can
-   * leave it out of a capture (`composite-screenshot.ts`). Whether a dev root
-   * reaches this function at all is the CALLER's gate —
-   * `mountManifestRoots` asks `devLayersEnabled()` before building the spec.
-   *
-   * It steals no input from the game while closed for a reason that predates
-   * this flag and needs no new mechanism: a dev layer is a `dom` root, DOM
-   * layers are `pointer-events:none` (see `mountOneReactRoot`) with the
-   * mounted tree opting individual elements back in, and the input router
-   * never sees DOM roots at all.
-   */
-  readonly dev?: boolean | undefined;
-  /** `'gated'` (host-driven, default) or `'self-driven'` (this world drives
-   *  its own loop — D5's "composited, unsynchronized" tier). Carried through
-   *  for parity with `ResolvedAdapterRoot`; T6.1 slice 1 does not yet
-   *  validate it against the mounted adapter's actual `drivesOwnLoop` (that
-   *  cross-check, if ever needed, is T7.6's loop-gate surface). */
-  readonly loop?: 'gated' | 'self-driven' | undefined;
   /**
    * Optional claim predicate for the delegating input router (D5 §2a), over
    * a point RELATIVE TO THE CONTAINER. Absent means: this world claims only
@@ -199,8 +174,8 @@ export interface PixiRootMountSpec extends RootMountSpecBase {
 }
 
 /**
- * A live, mounted react world (T6.2 slice 1) — the react analog of a mounted
- * canvas world. React roots render from game state via the T7.4 bridge
+ * A live, mounted React world — the DOM analog of a mounted canvas world.
+ * React roots render from game state
  * instead of a per-frame `update`, so this shape carries no `update`/`fixedUpdate`/
  * `ctx`/`frame` — `drivesOwnLoop` is always `false` (react's `createRoot`
  * schedules its OWN commits; the host's fixed-step loop never drives it,
@@ -217,10 +192,10 @@ export interface PixiRootMountSpec extends RootMountSpecBase {
  * `kind: 'dom'` (§7.1-15): a react world has no `observe` BY DESIGN — that
  * hook is scoped to `useRootObservation` (the ingested/foreign-world case),
  * not `useWorldState` (`ui/game-state.tsx`), which a react world's own
- * mounted tree uses instead — it reads `Game.state` directly (T7.4's actual
- * bridge for first-party-observable state), never a per-world `observe`.
+ * mounted tree uses instead — it reads `Game.state` directly, never a
+ * per-world `observe`.
  *
- * `kind`/`container` (T7.5) satisfy `MountedReactRoot` (`adapter/
+ * `kind`/`container` satisfy `MountedReactRoot` (`adapter/
  * root-adapter.ts`) — `container` is the SAME `DomHostContext.container` the
  * adapter's `mount` was handed (identity matters, mirroring `threeScene()`/
  * `pixiStage()`'s "same instance the adapter mounted" contract); every
@@ -236,7 +211,7 @@ export interface MountedReactGame extends MountedReactRoot {
  * A react-shaped adapter — the structural contract `RootMountSpec`'s
  * `react` variant requires. Deliberately
  * NOT tied to a concrete implementer here so an editor-resolved adapter (the
- * `default-react` resolver branch, T6.2's editor-side follow-up) can satisfy
+ * `default-react` resolver branch) can satisfy
  * this shape without this file importing react-dom or any editor code.
  *
  * A genuine `RootAdapter<'dom'>` refinement (`HostContextFor<'dom'>` =
@@ -328,37 +303,25 @@ export interface RootsRuntimeConfig {
  *
  * This is the GENERIC host handle — it has no first-party concepts (no
  * `GameContext`, no `GameSetupFn`). First-party features (the live `GameContext`,
- * warm-restart hot reload) are reached by casting `mounted` to `MountedSetupThreeRoot`
+ * warm-restart hot reload) are reached through `game.defaultRoot.mounted`
+ * and narrowed to `MountedSetupThreeRoot`
  * (the editor does this for HMR/physics-sync — those are inherently first-party).
  *
- * `scene`/`camera`/`mounted` alias the Game's `defaultRoot`: it is the first
- * three root (else the first
- * world) by DECLARATION order, per `Game.defaultRoot`'s existing rule —
- * independent of `zOrder`/canvas stacking, which is a rendering-only concern.
+ * Root access is explicit through `game.roots`, `game.world(id)`, and
+ * `game.defaultRoot`; the session does not project a surface-specific alias.
  */
 export interface GameSession {
   stop(): void;
+  /** Resolves after every root has finished the cleanup initiated by stop(). */
+  readonly stopComplete: Promise<void>;
   pause(): void;
   resume(): void;
   step(): void;
-  /** Resize every world's render buffer. `pixelRatio` (W2c device preview)
-   *  optionally re-pins the three renderers' DPR in the same pass; omitted,
-   *  the mount-time ratio is left untouched (legacy behavior). */
+  /** Resize every world's render buffer. `pixelRatio` optionally re-pins the
+   * three renderers' DPR in the same pass. */
   resize(width: number, height: number, pixelRatio?: number): void;
-  readonly scene: THREE.Scene;
-  readonly camera: THREE.PerspectiveCamera;
-  /** The default world's mounted root, as the honest `MountedRoot` union —
-   *  narrow on `.kind` before reaching for a surface's own members (the same
-   *  discriminant `scene`/`camera` above use). This deliberately does NOT
-   *  claim `MountedThreeRoot`: a roots-path session whose default world is
-   *  canvas or dom returns that world's mount, and the old
-   *  `as MountedThreeRoot` cast made every such value a type-level lie. For a
-   *  first-party three mount, narrow to `'three'` and cast to
-   *  `MountedSetupThreeRoot` for the first-party extras. */
-  readonly mounted: MountedRoot;
-  /** The Game root (T6.1 slice 1) — the multi-world entry point
-   *  (`game.roots`/`game.world(id)`/`game.queryByComponent`) for callers
-   *  that need more than the default-world aliases above. */
+  /** The multi-root entry point. Root access stays explicit through
+   * `game.roots`, `game.world(id)`, and `game.defaultRoot`. */
   readonly game: Game;
 }
 
@@ -374,7 +337,7 @@ export async function createGameRuntime(config: RootsRuntimeConfig): Promise<Gam
 }
 
 // ---------------------------------------------------------------------------
-// Worlds path (T6.1 slice 1)
+// Universal root host
 // ---------------------------------------------------------------------------
 
 /** A stand-in `THREE.WebGLRenderer` for headless (`headless:true`) three
@@ -397,7 +360,7 @@ function createHeadlessRendererStub(): THREE.WebGLRenderer {
 
 /** One already-mounted world, tracked for disposal + the router. `element`
  *  is the world's stacked surface — an `HTMLCanvasElement` for three/
- *  canvas, or the DOM-root layer `<div>` for react (T6.2 slice 1) — kept
+ *  canvas, or the DOM-root layer `<div>` for React — kept
  *  under one field name so `fullCleanup`'s disposal loop stays kind-generic
  *  (`container.removeChild(entry.element)` needs no branch). */
 interface MountedAdapterRoot {
@@ -477,11 +440,8 @@ async function mountOneThreeRoot(
   // resize-staleness (the roots-path `resize()` below always calls
   // `setSize(rw, rh, false)`, so nothing else was ever going to update this
   // canvas' CSS after mount). `createHostRenderer`'s own default
-  // (`updateStyle:true`) is intentionally left alone — the LEGACY
-  // single-canvas path (editor play-mode's non-multi-world branch) still
-  // relies on that construction-time stamp + its own later `updateStyle:true`
-  // resizes for byte-identical behavior; this fix touches only the
-  // roots-path canvas, after the fact.
+  // (`updateStyle:true`) is intentionally left alone; the host owns CSS layout
+  // and reasserts the container-relative size after renderer construction.
   canvas.style.width = '100%';
   canvas.style.height = '100%';
   renderer.setPixelRatio(dpr);
@@ -559,7 +519,7 @@ async function mountOnePixiRoot(
 }
 
 /**
- * Mount one react `RootMountSpec` (T6.2 slice 1) — the react sibling of
+ * Mount one React `RootMountSpec` — the DOM sibling of
  * `mountOneThreeRoot`/`mountOnePixiRoot`. Unlike its canvas-backed siblings
  * this returns NO `routerEntry`: a react world's DOM-root layer participates in
  * D5's z-order/box stacking (the caller still creates and positions its `<div>`
@@ -592,7 +552,7 @@ async function mountOneReactRoot(
   // An absolutely-positioned layer with no width/height collapses to zero
   // content size, so a child's
   // own position:absolute offsets resolve against a degenerate containing
-  // block (found by the T6.2 slice-3 e2e — clicks landed outside the game).
+  // block; otherwise clicks land outside the game.
   layer.style.width = '100%';
   layer.style.height = '100%';
   const reactHost: DomHostContext = { container: layer, game };
@@ -613,8 +573,8 @@ async function mountOneReactRoot(
 }
 
 /**
- * The roots-path implementer behind {@link createGameRuntime} (T6.1 slice
- * 1; react roots added T6.2 slice 1). Builds ONE surface per world — a
+ * The universal host implementer behind {@link createGameRuntime}. It builds
+ * one surface per world — a
  * canvas for three/canvas, a DOM-root `<div>` layer for react — stacked
  * per D5 §1, z-order/ties exactly matching
  * `manifest/load.ts`'s sort, ONE `Game`, and registers every world onto it
@@ -628,16 +588,11 @@ async function mountOneReactRoot(
 
 /**
  * Dev/e2e-only `window.__vgaiScene`/`__vgaiCamera` exposure for the roots
- * path's DEFAULT world (E4) — split out of `createRootsGameRuntime` purely
- * to keep that function's own cyclomatic complexity down. Mirrors the
- * legacy single-world path's identical exposure (above, in this same file),
- * using the SAME "first three world, else none" default-world rule the
- * `GameSession.scene`/`.camera` getters alias (`Game.defaultRoot`): a
- * non-threejs default world (or none at all) publishes neither global,
- * exactly like those getters return `undefined` in that case. Returns a
- * retraction callback — identity-guarded (a newer session's globals must
- * never be clobbered by an older session's stop, same reason the legacy
- * path's own cleanup guards it) — that is a no-op when nothing was
+ * path's default world — split out of `createRootsGameRuntime` purely
+ * to keep that function's own cyclomatic complexity down. It uses the
+ * "first three world, else none" rule: a non-Three default world publishes
+ * neither global. Returns an identity-guarded retraction callback so an
+ * older session's stop cannot clobber a newer session's globals. It is a no-op when nothing was
  * published (non-DEV build, or non-threejs default world).
  */
 function installDefaultRootDevGlobals(game: GameInternal): () => void {
@@ -804,26 +759,15 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
   // --- Surface stack (D5 §1): DOM/z-order follows zOrder, ties -> array order
   // — computed FIRST (bottom -> top) so both the z-index assignment below and
   // the router's default-claim rule share one definition. A react world's
-  // DOM-root layer shares this SAME stacking pass (T6.2 slice 1 — "one
-  // stacking model, no special case") even though it is a `<div>`, not a
+  // DOM-root layer shares this SAME stacking pass even though it is a `<div>`, not a
   // canvas, and carries no `hitTest` (the router never sees react entries at
   // all — see the dispatch loop below). ---
-  // Dev layers sit TOPMOST, above every non-dev root, whatever zOrder either
-  // declares: a dev GUI the game can paint over is not a dev GUI. Expressed as
-  // two independent `stackOrder` passes concatenated rather than a magic
-  // zOrder value, so `stackOrder`'s one rule (ascending zOrder, ties -> array
-  // order) still governs WITHIN each band and nothing has to reason about what
-  // number is "high enough".
   const claimEntries = mountSpecs.map((spec) => ({
     id: spec.id,
     zOrder: spec.zOrder ?? 0,
     hitTest: spec.hitTest,
-    dev: spec.dev === true,
   }));
-  const stacked = [
-    ...stackOrder(claimEntries.filter((e) => !e.dev)),
-    ...stackOrder(claimEntries.filter((e) => e.dev)),
-  ];
+  const stacked = stackOrder(claimEntries);
   const bottomId = stacked[0]?.id;
   const kindById = new Map(mountSpecs.map((spec) => [spec.id, spec.kind] as const));
 
@@ -839,11 +783,6 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
     // surface.ts`, which is the one door the capture/staleness/screenshot
     // sites now ask (ARCHITECTURE-CORE §The editor protocol, zero inference).
     surface.dataset['vgaiRootId'] = entry.id;
-    // The capture's marker (`composite-screenshot.ts` reads exactly this
-    // attribute): a dev layer is excluded from a play capture unless the
-    // capture asks for it, because a contaminated "does the game look right"
-    // frame is worthless.
-    if (entry.dev) surface.dataset['vgaiDevLayer'] = 'true';
     if (!isReact) {
       const canvas = surface as unknown as HTMLCanvasElement;
       canvas.width = w;
@@ -862,7 +801,7 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
     // too (not just in `mountOneThreeRoot`) means every surface, whatever
     // kind, starts container-relative from its very first paint, before any
     // per-kind mount work has even run.
-    // `contain:layout paint` makes each surface the CONTAINING BLOCK for
+    // `contain:layout paint` makes each surface the containing block for
     // `position:fixed` descendants (and clips overflow to the world's
     // rectangle): full-screen game UI written the natural way (`fixed;
     // inset:0`) then fills the WORLD, not the page. Without it, `fixed` UI
@@ -936,17 +875,7 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
   started = true;
   loop.start();
 
-  // Expose scene & camera for dev tools / e2e tests — mirrors the legacy
-  // single-world path's identical dev-only exposure above, generalized to
-  // the roots path's DEFAULT world (E4): `mountGameFromManifest`/
-  // `mountManifestRoots` route every caller (including a
-  // single-threejs-world scaffold project) through THIS path, so a caller
-  // migrating off the legacy `{canvas, adapter}` call must not silently
-  // lose `window.__vgaiScene`/`__vgaiCamera` — real e2e/dev tooling
-  // depends on them
-  // (`packages/editor/e2e/tests/04-standalone-game.spec.ts`). Split into
-  // its own top-level helper (with its retraction counterpart below)
-  // purely to keep this function's own cyclomatic complexity down.
+  // Expose the default Three root's scene and camera for dev/e2e tooling.
   const retractDevGlobals = installDefaultRootDevGlobals(game);
 
   // G3/FT-11 — publish `window.__vgaiRender` for the deterministic capture
@@ -959,39 +888,49 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
       ? installSessionRenderHarness(game, renderModeLocation, config.renderControl?.target)
       : undefined;
 
+  let resolveStopComplete!: () => void;
+  const stopComplete = new Promise<void>((resolve) => {
+    resolveStopComplete = resolve;
+  });
+  let stopping = false;
+
   function fullCleanup(): void {
-    loop.stop();
-    router.dispose();
-    for (const entry of mountedEntries) {
-      entry.mounted.dispose();
-      entry.renderer?.dispose();
-      entry.renderer?.forceContextLoss();
-      // 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 */
+    if (stopping) return;
+    stopping = true;
+    try {
+      loop.stop();
+      router.dispose();
+      for (const entry of mountedEntries) {
+        entry.mounted.dispose();
+        entry.renderer?.dispose();
+        entry.renderer?.forceContextLoss();
+        // 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();
+      retractRenderHarness?.();
+    } finally {
+      void Promise.allSettled(
+        mountedEntries.map((entry) => entry.mounted.disposeComplete ?? Promise.resolve()),
+      ).then(() => resolveStopComplete());
     }
-    game.dispose();
-    retractDevGlobals();
-    retractRenderHarness?.();
   }
 
   return {
     stop: fullCleanup,
-    // D10/T7.6: `Game.play` fans out per-world pausable/loop-gate/audio-gate
-    // semantics itself now (see the legacy path's identical comment above) —
-    // a `pausable: false` world (a menu/HUD world) keeps ticking while every
-    // other world freezes, which the old blind `for (const entry of
-    // mountedEntries) entry.mounted.setPaused?.(true)` fan-out (with no
-    // `pausable` check at all) could never express.
+    stopComplete,
+    // `Game.play` owns per-world pause, loop-gate, and audio-gate semantics.
     pause() {
       game.play.pause();
     },
@@ -1014,24 +953,6 @@ async function createRootsGameRuntime(config: RootsRuntimeConfig): Promise<GameS
         entry.mounted.resize?.(safeWidth, safeHeight);
       }
     },
-    // `GameSession.scene`/`.camera`/`.mounted` alias `Game.defaultRoot` (T6.1
-    // slice 1's "first three world, else first world" rule) — a legacy
-    // convenience shaped for the threejs-only past. T7.5 narrows the read via
-    // the `kind` discriminant instead of a blind `.scene`/`.camera` cast
-    // through a nonexistent property (identical behavior to before: still
-    // `undefined` for a roots-path session whose default world isn't
-    // three — real per-world surface routing for that case is T7.6's).
-    get scene() {
-      const m = game.defaultRoot.mounted;
-      return (m.kind === 'three' ? m.scene : undefined) as THREE.Scene;
-    },
-    get camera() {
-      const m = game.defaultRoot.mounted;
-      return (m.kind === 'three' ? m.camera : undefined) as THREE.PerspectiveCamera;
-    },
-    get mounted() {
-      return game.defaultRoot.mounted;
-    },
     game,
   };
 }

package/src/runtime/dev-build.ts

@@ -0,0 +1,49 @@
+/**
+ * THE one owner of "is this a development context". Every reader that has to
+ * answer that question calls {@link devBuildEnabled}; there is deliberately NO
+ * second source of truth — not a module-level cached boolean, not a
+ * `globalThis` flag, not a per-host copy of the `import.meta.env` read below.
+ * Instrumentation that ships to players because two places disagreed about
+ * what "dev" means is exactly the failure this single owner exists to make
+ * impossible.
+ *
+ * Ownership, stated in one place (the build rule):
+ *  - OWNER: this function. It resolves the answer; nothing else derives it.
+ *  - SHARERS: the two three-root adapters (`adapter/setup-three-root-adapter.ts`
+ *    and `world3d-react/r3f-adapter.tsx`), which seed live render vitals only
+ *    under it, and the `static-batch` capability's mutation watch and `Frozen`
+ *    warning. Any future dev-only instrument calls this too, with its own
+ *    `override`.
+ *  - TEARDOWN: none. This is a pure predicate over build config and one
+ *    caller-supplied argument — it owns no resource, allocates nothing, and
+ *    has no lifecycle to end.
+ *
+ * The three inputs, highest precedence first:
+ *  1. `override` — the explicit per-call answer. A headless test, a capture
+ *     harness, or a host that knows better passes `true`/`false` and gets
+ *     exactly that. Passing `undefined` (or omitting it) means "decide for
+ *     me" and falls through. The editor's own preview mount is the worked
+ *     case: it is a dev session by definition even when the editor SPA it
+ *     runs inside is a production build.
+ *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case.
+ *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_BUILD=true`.
+ *     Instrumenting a production bundle is a real, legitimate choice (an
+ *     internal playtest build, a QA build), and it must be an opt-in someone
+ *     had to type, never something a default drifts into.
+ *
+ * Anything else — a production build with no opt-in — is `false`.
+ */
+export function devBuildEnabled(override?: boolean | undefined): boolean {
+  if (override !== undefined) return override;
+  // `import.meta` is cast whole, not just its `.env`: this module is reachable
+  // from programs whose tsconfig does not pull in `vite/client` (the session
+  // client's, for one, which reaches the three adapter transitively), and there
+  // `ImportMeta` has no declared `env` at all. The cast keeps the single owner
+  // of the dev answer importable from ANY program rather than forcing every
+  // downstream tsconfig to adopt Vite's ambient types.
+  const env = (import.meta as unknown as { env?: unknown }).env as
+    | { DEV?: boolean | undefined; VITE_VGAI_DEV_BUILD?: string | undefined }
+    | undefined;
+  if (env?.DEV === true) return true;
+  return env?.VITE_VGAI_DEV_BUILD === 'true';
+}