@vgai/engine 0.5.16 → 0.5.18

package/src/world3d-react/rapier-physics-bridge.tsx

@@ -3,7 +3,7 @@
  * `@react-three/rapier` physics VISIBLE to the engine's editor/dev seams.
  *
  * WHY IT EXISTS. `SystemAdapters.physics` is what the editor's transform
- * coordination (`freeze → apply → unfreeze`) and the dev menu's universal
+ * coordination (`freeze → apply → unfreeze`) and the universal
  * "Colliders drawn" instrument (`@engine/dev/instruments`) read. The
  * first-party imperative three root registers one from
  * `../adapter/setup-three-root-adapter.ts`; an R3F world builds no first-party
@@ -44,7 +44,7 @@
  * on the R3F root it is mounted in. It allocates nothing else — no timers, no
  * subscriptions, no per-frame work (see the phase note below), and no Rapier
  * objects: the bodies it edits belong to `<Physics>`.
- * SHARERS: every reader of `game.systemAdapters.physics` — the dev menu's
+ * SHARERS: every reader of `game.systemAdapters.physics` — the
  * colliders instrument, the editor's transform coordination. They read; they
  * never dispose.
  * TEARDOWN: the effect's cleanup, and nothing else — it clears the SAME key it
@@ -55,7 +55,7 @@
  *
  * PHASE ORDERING: none to respect — this component registers pull-only
  * callbacks and runs no per-frame work. Every method it exposes is invoked
- * BETWEEN frames, by an editor gesture or a dev-menu command, never from a
+ * BETWEEN frames, by an editor gesture or an instrument command, never from a
  * phase.
  */
 
@@ -78,7 +78,7 @@ import { useGameContext } from './engine-bridge';
 export interface RapierPhysicsBridgeProps {
   /**
    * Set the `debug` prop of the SAME `<Physics>` this bridge is mounted in.
-   * The dev menu's "Colliders drawn" toggle calls it; the world's own state is
+   * The "Colliders drawn" instrument calls it; the world's own state is
    * what `<Physics debug={…}>` reads, so the library's debug rendering is the
    * only thing that ever draws a collider.
    */

package/src/world3d-react/renderer-config.ts

@@ -1,168 +1,11 @@
 /**
- * world3d-react/renderer-config.ts — the seam a WORLD uses to state how its own frame is rendered.
+ * `@engine/world3d-react/renderer-config` — a published entry point.
  *
- * The host owns the `WebGLRenderer` (`ThreeHostContext.renderer`) and configures it with this
- * engine's defaults: ACES tone mapping, sRGB output, PCF-soft shadows. Those defaults are right for
- * a world authored against them and WRONG for a world that was authored against a different
- * engine's pipeline — an imported Godot 3 GLES2 game does gamma-space lighting with no tonemapper
- * at all, so ACES quietly desaturates and darkens every colour its author picked.
- *
- * So a world may DECLARE the pipeline it was authored for, and `createR3FAdapter` applies it to the
- * host's renderer for the life of the mount, restoring what it found on dispose. Three properties
- * of that shape are load-bearing:
- *
- *  - **It is per-renderer, never engine-wide.** Every field here is a `WebGLRenderer` instance
- *    property, and a play root gets its own renderer (`create-runtime.ts`). Nothing here reaches a
- *    module-level three global, so one world's declaration cannot change how the editor's own
- *    viewport, another root, or a thumbnail bake renders.
- *  - **Absent means "leave the host's value alone".** Every field is optional and an omitted one
- *    is never written, so declaring a tone mapping does not silently reset the clear colour.
- *  - **It is restored on dispose.** The renderer outlives the mount, so a world that did not put
- *    back what it found would leak its pipeline into whatever mounts next.
- *
- * This is deliberately NOT a general render-settings system. It carries what a world can honestly
- * state about its own colour pipeline and nothing else; a property the host fixes at CONSTRUCTION
- * (the WebGL context's `antialias` attribute, and therefore the MSAA sample count) cannot be
- * declared here, because there would be no honest moment to apply it.
- */
-
-import type * as THREE from 'three';
-
-/** The tone-mapping operators three exposes, named as data rather than as three's numeric enum. */
-export type WorldToneMapping =
-  | 'none'
-  | 'linear'
-  | 'reinhard'
-  | 'cineon'
-  | 'aces'
-  | 'agx'
-  | 'neutral';
-
-/**
- * The output transfer function the frame is written with.
- *
- *  - `srgb` — three's own default and this engine's: linear lighting, sRGB encode on output.
- *  - `srgb-linear` — NO output transform. This is what a gamma-space renderer needs: the shading
- *    result is already in display space and encoding it a second time washes the frame out.
- */
-export type WorldOutputColorSpace = 'srgb' | 'srgb-linear';
-
-/**
- * The shadow-map filter, named as data rather than as three's numeric enum.
- *
- * This is a renderer INSTANCE property (`WebGLRenderer.shadowMap.type`), not a context attribute,
- * so unlike MSAA it has an honest moment at which a world can ask for it — which is the whole test
- * this file's header states. A source engine that declares its own shadow filter (Godot 3's
- * `rendering/quality/shadows/filter_mode`) would otherwise inherit whatever the host built with.
- */
-export type WorldShadowMapType = 'basic' | 'pcf' | 'pcf-soft' | 'vsm';
-
-/** What a world may declare about the renderer that draws it. Every field is optional; see header. */
-export interface WorldRendererConfig {
-  readonly toneMapping?: WorldToneMapping | undefined;
-  readonly toneMappingExposure?: number | undefined;
-  readonly outputColorSpace?: WorldOutputColorSpace | undefined;
-  /**
-   * `WebGLRenderer.shadowMap.type`. Writing it after a shadow map has already been built needs
-   * `shadowMap.needsUpdate`, which this function sets — three caches the compiled depth material
-   * per type and would otherwise keep filtering with the previous one.
-   */
-  readonly shadowMapType?: WorldShadowMapType | undefined;
-  /**
-   * The colour the frame is cleared to, as a CSS hex string. The renderer's existing clear ALPHA
-   * is preserved: a stacked canvas is transparent on purpose (`create-runtime.ts` gives every
-   * non-bottom root `alpha: true`), and forcing it opaque here would hide every layer below.
-   */
-  readonly clearColor?: string | undefined;
-}
-
-/**
- * Apply `config` to `renderer`, returning the restore function that puts back what was there.
- *
- * `three` is passed in rather than imported for values so the enum constants come from the HOST's
- * three instance — the same identity rule `r3f-adapter.tsx` follows for the scene and camera.
+ * The engine package's export map is the wildcard `"./*"`, so every file under
+ * `packages/engine/src/` is an entry point a game outside this repo can import by path. The module
+ * itself now lives in the adapter seam (`@engine/adapter/renderer-config`, which its header
+ * explains), and this file keeps the path that shipped resolving to it. Import the seam path in
+ * new code.
  */
-export function applyWorldRendererConfig(
-  three: typeof THREE,
-  renderer: THREE.WebGLRenderer,
-  config: WorldRendererConfig,
-): () => void {
-  // A host that mounts a world WITHOUT rasterizing it hands the adapter a duck-typed renderer —
-  // the editor's design session (`createDesignTimeRenderer`: four members, deliberately never
-  // widened) and jsdom test harnesses both do. Such a surface has no colour pipeline to configure:
-  // the frame the user sees is drawn by a DIFFERENT renderer (the editor's own), so applying the
-  // world's config there is meaningless — and calling `getClearColor` on it is a TypeError that
-  // unmounts the whole world at edit time (measured: every Godot port's edit viewport blanked with
-  // '"world" failed to mount — renderer.getClearColor is not a function'). Detect the real
-  // `WebGLRenderer` surface by the one method this function must call, and no-op otherwise.
-  if (typeof renderer.getClearColor !== 'function') {
-    return () => {};
-  }
-  const toneMappings: Record<WorldToneMapping, THREE.ToneMapping> = {
-    none: three.NoToneMapping,
-    linear: three.LinearToneMapping,
-    reinhard: three.ReinhardToneMapping,
-    cineon: three.CineonToneMapping,
-    aces: three.ACESFilmicToneMapping,
-    agx: three.AgXToneMapping,
-    neutral: three.NeutralToneMapping,
-  };
-  const colorSpaces: Record<WorldOutputColorSpace, THREE.ColorSpace> = {
-    srgb: three.SRGBColorSpace,
-    'srgb-linear': three.LinearSRGBColorSpace,
-  };
-  const shadowMapTypes: Record<WorldShadowMapType, THREE.ShadowMapType> = {
-    basic: three.BasicShadowMap,
-    pcf: three.PCFShadowMap,
-    'pcf-soft': three.PCFSoftShadowMap,
-    vsm: three.VSMShadowMap,
-  };
-
-  const restores: (() => void)[] = [];
-
-  if (config.toneMapping !== undefined) {
-    const previous = renderer.toneMapping;
-    renderer.toneMapping = toneMappings[config.toneMapping];
-    restores.push(() => {
-      renderer.toneMapping = previous;
-    });
-  }
-  if (config.toneMappingExposure !== undefined) {
-    const previous = renderer.toneMappingExposure;
-    renderer.toneMappingExposure = config.toneMappingExposure;
-    restores.push(() => {
-      renderer.toneMappingExposure = previous;
-    });
-  }
-  if (config.outputColorSpace !== undefined) {
-    const previous = renderer.outputColorSpace;
-    renderer.outputColorSpace = colorSpaces[config.outputColorSpace];
-    restores.push(() => {
-      renderer.outputColorSpace = previous;
-    });
-  }
-  if (config.shadowMapType !== undefined && renderer.shadowMap !== undefined) {
-    const previous = renderer.shadowMap.type;
-    renderer.shadowMap.type = shadowMapTypes[config.shadowMapType];
-    renderer.shadowMap.needsUpdate = true;
-    restores.push(() => {
-      renderer.shadowMap.type = previous;
-      renderer.shadowMap.needsUpdate = true;
-    });
-  }
-  if (config.clearColor !== undefined) {
-    const previousColor = new three.Color();
-    renderer.getClearColor(previousColor);
-    // Alpha is READ BACK and re-passed, never assumed: see `clearColor`'s doc above.
-    const alpha = renderer.getClearAlpha();
-    renderer.setClearColor(new three.Color(config.clearColor), alpha);
-    restores.push(() => {
-      renderer.setClearColor(previousColor, alpha);
-    });
-  }
 
-  return () => {
-    // Reverse order, so a field written twice (it cannot be, today) unwinds correctly.
-    for (let i = restores.length - 1; i >= 0; i--) restores[i]?.();
-  };
-}
+export * from '../adapter/renderer-config';

package/src/world3d-react/world-context.ts

@@ -147,6 +147,103 @@ export interface R3FRootRuntime {
   dispose(): void;
 }
 
+/**
+ * The GAME-SCOPED input wiring one three root owns — and the half that has
+ * nothing to do with the vgai runtime context.
+ *
+ * Two things happen here, both of them HOST work performed from outside the
+ * world's own tree:
+ *
+ *  1. the project's input map is loaded through `Game.loadInputMap` (game-owned,
+ *     load-once), so the actions the project declared exist;
+ *  2. this root's seams are registered on the game-scoped debug registry
+ *     (`setVirtualInputTarget`/`setInputActionsSource`/`setInputTraceSource`),
+ *     which is what makes `game.input.hold/tap/...` (the bot/`vgai eval` input
+ *     doctrine) and the built-in `input.actions`/`input.trace` providers
+ *     resolve to this world instead of throwing `DEBUG_INPUT_UNAVAILABLE`.
+ *
+ * It is called on BOTH three-root paths, and that is the point: a world that
+ * mounts as a default-exported component receives no vgai runtime context
+ * (`engineRuntime: false` — see `r3f-root-factory.tsx`), but "no context in the
+ * tree" was never meant to say "the host does not wire this game's input". It
+ * was read that way, and the cost was measured on a fresh scaffold: the
+ * declared map never loaded and every `game.input.*` door threw, so the QA
+ * bot, autoplay routes and `vgai eval` could not drive the ONE world shape
+ * `vgai create` produces. Same split, same reasoning, as `WorldProvider`
+ * riding `host.game` rather than the runtime (see `r3f-adapter.tsx`).
+ *
+ * `optionalInputMap` is the CONVENTIONAL-PATH probe used when the project
+ * never named a map: an absent file is the ordinary state of a brand-new
+ * project, so it resolves quietly instead of printing an error on every boot.
+ * A map that exists and fails to parse is as loud as ever.
+ *
+ * LIFETIME, honestly: `registry.strip(id)` runs on the mount's dispose (both
+ * paths), but it walks providers/commands only — the three seams set here
+ * survive it, keyed by this world's id, until a remount of the same id
+ * overwrites them. That residue is inert rather than hidden: every closure
+ * below reads GAME-scoped state (`game.input`, `game.loop.fixedDt`, the game's
+ * seed), so a stale entry actuates exactly what a live one would. See the
+ * dispose comment in `r3f-adapter.tsx` for the full accounting.
+ */
+export function wireGameInputSeams(
+  host: ThreeHostContext,
+  registry: DebugRegistry,
+  options: {
+    readonly id: string;
+    readonly inputMapPath?: string | null | undefined;
+    readonly optionalInputMap?: boolean | undefined;
+  },
+): Promise<void> {
+  const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH, optionalInputMap = false } = options;
+  if (!host.game) return Promise.resolve();
+  const game = host.game;
+  const input = game.input;
+  registry.setInputActionsSource(id, () =>
+    input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
+  );
+  registry.setInputTraceSource(id, () => {
+    const raw = input.getInputTrace();
+    return {
+      version: raw.version,
+      seed: getSeededRandom(game)?.seed ?? null,
+      fixedDt: game.loop.fixedDt,
+      ticks: raw.ticks,
+    };
+  });
+  registry.setVirtualInputTarget(id, {
+    setVirtualAction: (action, value) => input.setVirtualAction(action, value),
+    tapVirtualAction: (action) => input.tapVirtualAction(action),
+    clearVirtualActions: () => input.clearVirtualActions(),
+    scheduleActionAtTick: (tick, action, value) => input.scheduleActionAtTick(tick, action, value),
+    startInputRecording: () => input.startInputRecording(),
+    stopInputRecording: () => input.stopInputRecording(),
+    isInputRecording: () => input.isInputRecording(),
+    injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
+    injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
+    injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
+    injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
+  });
+  if (host.headless || inputMapPath === null) return Promise.resolve();
+  // Load-once through the game-owned path (competing paths across roots throw
+  // THERE, loudly). A FAILED load (missing/bad file) must not fail the mount:
+  // a three world with no declared actions is legal. It degrades loudly
+  // instead — naming exactly what breaks.
+  // The non-optional call passes ONE argument, exactly as it always has — a
+  // trailing `undefined` is a different call to any observer of it.
+  const load = optionalInputMap
+    ? game.loadInputMap(inputMapPath, { optional: true })
+    : game.loadInputMap(inputMapPath);
+  return load.catch((err: unknown) => {
+    // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount (see comment above)
+    console.error(
+      `three world "${id}": failed to load input map "${inputMapPath}" — declared input ` +
+        'actions and `game.input.*` (bot/virtual input) will not work until a valid map ' +
+        'loads. Ship one at the conventional path or pass `inputMapPath` to ' +
+        `createR3FAdapter (null to opt out). Cause: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  });
+}
+
 /**
  * Build the engine runtime for one R3F world from a `ThreeHostContext` — the same
  * wiring, at the same layer, as the classic `SetupThreeRootAdapter.mount()`
@@ -216,57 +313,9 @@ export function createR3FRootContext(
     gameClock ?? createSimClock({ dispose: (obj) => disposeDebrisSubtree(obj, []) });
   ctx.clock = clock;
 
-  // --- ctx.input + the debug-registry input seams (gap 3) — the game-owned
-  // InputManager, polled by the game-scoped runner each frame; this world
-  // registers the SAME per-world seams the classic adapter registers so
-  // `game.input.*` (virtual input) and the built-in `input.actions`/
-  // `input.trace` providers resolve to it. ---
-  let inputMapReady: Promise<void> = Promise.resolve();
-  if (host.game) {
-    const game = host.game;
-    const input = game.input;
-    debugRegistry.setInputActionsSource(id, () =>
-      input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
-    );
-    debugRegistry.setInputTraceSource(id, () => {
-      const raw = input.getInputTrace();
-      return {
-        version: raw.version,
-        seed: getSeededRandom(game)?.seed ?? null,
-        fixedDt: game.loop.fixedDt,
-        ticks: raw.ticks,
-      };
-    });
-    debugRegistry.setVirtualInputTarget(id, {
-      setVirtualAction: (action, value) => input.setVirtualAction(action, value),
-      tapVirtualAction: (action) => input.tapVirtualAction(action),
-      clearVirtualActions: () => input.clearVirtualActions(),
-      scheduleActionAtTick: (tick, action, value) =>
-        input.scheduleActionAtTick(tick, action, value),
-      startInputRecording: () => input.startInputRecording(),
-      stopInputRecording: () => input.stopInputRecording(),
-      isInputRecording: () => input.isInputRecording(),
-      injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
-      injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
-      injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
-      injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
-    });
-    if (!host.headless && inputMapPath !== null) {
-      // Load-once through the game-owned path (classic parity — competing
-      // paths across roots throw THERE, loudly). A FAILED load (missing/bad
-      // file) must not fail this mount: an R3F tree with no declared actions
-      // is legal. It degrades loudly instead — naming exactly what breaks.
-      inputMapReady = game.loadInputMap(inputMapPath).catch((err: unknown) => {
-        // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount (see comment above)
-        console.error(
-          `R3F world "${id}": failed to load input map "${inputMapPath}" — declared input ` +
-            'actions and `game.input.*` (bot/virtual input) will not work until a valid map ' +
-            'loads. Ship one at the conventional path or pass `inputMapPath` to ' +
-            `createR3FAdapter (null to opt out). Cause: ${err instanceof Error ? err.message : String(err)}`,
-        );
-      });
-    }
-  }
+  // --- ctx.input + the debug-registry input seams (gap 3) — see
+  // `wireGameInputSeams` below; `ctx.input` is that same game-owned manager. ---
+  const inputMapReady = wireGameInputSeams(host, debugRegistry, { id, inputMapPath });
 
   return {
     ctx,

package/dist/runtime/dev-layers.d.ts

@@ -1,34 +0,0 @@
-/**
- * THE one owner of "are dev layers enabled" (`vgai.project.json`'s `dev: true`
- * root flag). Every reader that has to answer that question calls
- * {@link devLayersEnabled}; 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. A dev GUI 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: `mountManifestRoots` (the ship gate — a dev root only mounts
- *    when this returns true). Any future host that mounts manifest roots
- *    itself 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-mount 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.
- *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case:
- *     dev layers are on.
- *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_LAYERS=true`.
- *     Shipping the dev GUI in 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 declare function devLayersEnabled(override?: boolean | undefined): boolean;
-//# sourceMappingURL=dev-layers.d.ts.map

package/dist/runtime/dev-layers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dev-layers.d.ts","sourceRoot":"","sources":["../../src/runtime/dev-layers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAaxE"}

package/dist/runtime/dev-layers.js

@@ -1,46 +0,0 @@
-/**
- * THE one owner of "are dev layers enabled" (`vgai.project.json`'s `dev: true`
- * root flag). Every reader that has to answer that question calls
- * {@link devLayersEnabled}; 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. A dev GUI 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: `mountManifestRoots` (the ship gate — a dev root only mounts
- *    when this returns true). Any future host that mounts manifest roots
- *    itself 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-mount 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.
- *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case:
- *     dev layers are on.
- *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_LAYERS=true`.
- *     Shipping the dev GUI in 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 devLayersEnabled(override) {
-    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.env;
-    if (env?.DEV === true)
-        return true;
-    return env?.VITE_VGAI_DEV_LAYERS === 'true';
-}

package/src/runtime/dev-layers.ts

@@ -1,46 +0,0 @@
-/**
- * THE one owner of "are dev layers enabled" (`vgai.project.json`'s `dev: true`
- * root flag). Every reader that has to answer that question calls
- * {@link devLayersEnabled}; 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. A dev GUI 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: `mountManifestRoots` (the ship gate — a dev root only mounts
- *    when this returns true). Any future host that mounts manifest roots
- *    itself 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-mount 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.
- *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case:
- *     dev layers are on.
- *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_LAYERS=true`.
- *     Shipping the dev GUI in 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 devLayersEnabled(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_LAYERS?: string | undefined }
-    | undefined;
-  if (env?.DEV === true) return true;
-  return env?.VITE_VGAI_DEV_LAYERS === 'true';
-}