@vgai/engine 0.5.15 → 0.5.17

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

@@ -11,7 +11,8 @@
  *     the ONE game-scoped registry (`getDebugRegistry(host.game)`), so a
  *     component's effect can `ctx.debug.registerStateProvider(...)` and be
  *     visible to `vgai eval`/the editor's debug panels.
- *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` — the
+ *  2. **`ctx.input` is the game-owned `InputManager` when a Game hosts the
+ *     root** (`host.game.input` — the
  *     same instance every sibling root shares), and this module registers the
  *     per-world debug-registry seams (`setVirtualInputTarget`/
  *     `setInputActionsSource`/`setInputTraceSource`) that make `game.input.*`
@@ -19,13 +20,14 @@
  *     `DEBUG_INPUT_UNAVAILABLE`. The project's input map loads through
  *     `Game.loadInputMap` (the game-owned, load-once path every root shares).
  *     A missing/unparseable map degrades LOUDLY without failing the mount — a
- *     canvas world with no declared actions is legal.
- *  3. **Absent subsystems fail loudly at the ctx surface.** A canvas world
- *     builds no THREE scene/camera, no Rapier world, no composer, no first-party
- *     audio/particles/debug-draw, and is handed no `AssetCache` (the canvas host
- *     context carries none — see `adapter/host-context.ts`). Reading those
- *     `ctx` fields yields a throwing getter naming the limitation and the
- *     sanctioned alternative, never a silent `undefined`.
+ *     canvas world with no declared actions is legal. A bare/foreign mount
+ *     receives `null`, visibly in the type, rather than a throwing getter.
+ *  3. **Absent subsystems are absent from the type.** A canvas world builds no
+ *     THREE scene/camera, Rapier world, composer, first-party audio/particles/
+ *     debug-draw, or Three-flavoured `AssetCache`. Its explicit
+ *     {@link CanvasGameContext} cannot name those fields, so misuse fails at
+ *     the call site during typechecking instead of from a throwing getter at
+ *     runtime.
  *
  * The Pixi handles themselves are deliberately NOT re-exposed here: a component
  * reaches the live `Application` (and therefore `app.stage`, `app.renderer`,
@@ -42,6 +44,7 @@ import {
   DEFAULT_SEEDED_RANDOM_SEED,
   getSeededRandom,
 } from '../core/seeded-random';
+import type { SimClock } from '../core/sim-clock';
 import { createSimClock, getSimClock, type SimClockInternal } from '../core/sim-clock';
 import { createSystemRunner } from '../core/system-runner';
 import {
@@ -49,7 +52,7 @@ import {
   type DebugRegistry,
   getDebugRegistry,
 } from '../runtime/debug-registry';
-import type { GameContext } from '../runtime/types';
+import type { ComponentContextBase } from '../runtime/types';
 
 /** The conventional input-map location every scaffolded project ships. Shared
  *  verbatim with the three lane — a project has ONE input map, whatever surface
@@ -70,12 +73,20 @@ export interface CanvasRootContextOptions {
   readonly inputMapPath?: string | null | undefined;
 }
 
+/** The engine services a Canvas component genuinely receives. Pixi's own
+ * `useApplication()` and `Assets` remain the doors to rendering and assets.
+ * `disposeAfter` is excluded because it accepts a `THREE.Object3D`; Canvas
+ * code schedules `displayObject.destroy()` with `clock.after()` instead. */
+export type CanvasGameContext = ComponentContextBase & {
+  readonly clock: Omit<SimClock, 'disposeAfter'>;
+};
+
 /** What {@link createCanvasRootContext} returns — the engine runtime one canvas
  *  world owns, plus the wiring hooks the adapter's `mount()` drives. */
 export interface CanvasRootRuntime {
-  /** The (partial, loud-on-absence) `GameContext` this world's components read
-   *  through `useGameContext`. See this module's header for what is present. */
-  readonly ctx: GameContext;
+  /** The explicit Canvas context this world's components read through
+   *  `useGameContext`. See {@link CanvasGameContext}. */
+  readonly ctx: CanvasGameContext;
   /** The world-local phase runner `mount().update(dt)` ticks. */
   readonly systems: ReturnType<typeof createSystemRunner>;
   /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —
@@ -95,32 +106,6 @@ export interface CanvasRootRuntime {
   dispose(): void;
 }
 
-/** Install a throwing getter for a `GameContext` field this world genuinely
- *  does not build — a component reaching for it fails LOUDLY at its own call
- *  site, naming the limitation, instead of reading `undefined` and breaking
- *  somewhere downstream. Non-enumerable so spreads/serialization of the ctx
- *  never trip it. */
-function defineAbsentCtxField(
-  target: Record<string, unknown>,
-  worldId: string,
-  key: string,
-  why: string,
-): void {
-  Object.defineProperty(target, key, {
-    configurable: true,
-    enumerable: false,
-    get(): never {
-      throw new Error(
-        `canvas world "${worldId}": ctx.${key} is not available — ${why} ` +
-          '(A canvas world ctx provides: input, systems, clock, debug, random, game, roots, ' +
-          "registerSystemAdapter. The Pixi runtime itself comes from @pixi/react's " +
-          'useApplication() — app.stage, app.renderer, app.ticker — and assets from Pixi`s own ' +
-          'Assets.)',
-      );
-    },
-  });
-}
-
 /**
  * Build the engine runtime for one canvas world from a `CanvasHostContext`.
  * React-free on purpose: everything here is plain engine wiring the adapter
@@ -145,13 +130,14 @@ export function createCanvasRootContext(
 
   const ctxRaw: Record<string, unknown> = {
     systems,
+    input: host.game?.input ?? null,
     registerSystemAdapter: (kind: keyof SystemAdapters, adapter: SystemAdapters[typeof kind]) => {
       // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the three lane performs; correct by construction
       (systemAdapters as any)[kind] = adapter;
       host.game?.notifySystemAdaptersChanged();
     },
   };
-  const ctx = ctxRaw as unknown as GameContext;
+  const ctx = ctxRaw as unknown as CanvasGameContext;
   if (host.game) {
     ctx.game = host.game;
     ctx.roots = host.game.roots;
@@ -188,7 +174,7 @@ export function createCanvasRootContext(
         );
       },
     });
-  ctx.clock = clock;
+  ctxRaw['clock'] = clock;
 
   // --- ctx.input + the debug-registry input seams — the game-owned
   // InputManager, polled by the game-scoped runner each frame; this world
@@ -198,7 +184,6 @@ export function createCanvasRootContext(
   if (host.game) {
     const game = host.game;
     const input = game.input;
-    ctxRaw['input'] = input;
     debugRegistry.setInputActionsSource(id, () =>
       input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })),
     );
@@ -239,68 +224,8 @@ export function createCanvasRootContext(
         );
       });
     }
-  } else {
-    defineAbsentCtxField(
-      ctxRaw,
-      id,
-      'input',
-      'input is game-owned and this mount has no Game host (host.game is absent — bare ' +
-        'harness/foreign host); mount through the vgai host to get the shared InputManager.',
-    );
   }
 
-  // --- Loud absence for everything a canvas world genuinely does not build. ---
-  const threeWhy =
-    'a canvas world renders through PixiJS and owns no THREE scene graph; the world root is ' +
-    "the Pixi stage, reached with @pixi/react's useApplication().app.stage.";
-  defineAbsentCtxField(ctxRaw, id, 'scene', threeWhy);
-  defineAbsentCtxField(ctxRaw, id, 'camera', threeWhy);
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'sceneIndex',
-    'the live scene index walks a THREE.Scene; a canvas world has none (walk the Pixi display ' +
-      'tree from useApplication().app.stage instead).',
-  );
-  const rapierWhy =
-    'canvas worlds do not build the first-party Rapier runtime; drive physics from inside the ' +
-    'tree with the 2D physics library of your choice.';
-  defineAbsentCtxField(ctxRaw, id, 'rapierWorld', rapierWhy);
-  defineAbsentCtxField(ctxRaw, id, 'rapier', rapierWhy);
-  defineAbsentCtxField(ctxRaw, id, 'physics', rapierWhy);
-  defineAbsentCtxField(ctxRaw, id, 'collisions', rapierWhy);
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'assets',
-    'the canvas host context carries no AssetCache (that cache is a GLTF/texture loader ' +
-      "resolving THREE objects); load textures/spritesheets with Pixi's own `Assets`.",
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'composer',
-    'a canvas world has no postprocessing EffectComposer; use Pixi filters on a Container.',
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'audio',
-    'canvas worlds build no first-party audio context; use Web Audio directly (or @pixi/sound).',
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'particles',
-    'canvas worlds build no three.quarks particle runtime; use a Pixi particle container.',
-  );
-  defineAbsentCtxField(
-    ctxRaw,
-    id,
-    'debugDraw',
-    'canvas worlds build no debug-draw helper; draw into a Pixi `Graphics` in the tree.',
-  );
-
   return {
     ctx,
     systems,

package/src/data/curve.ts

@@ -59,7 +59,7 @@ export interface CurveAxes {
   y: { min: number; max: number; label?: string };
 }
 
-/** How the marker rides out to the emitted JSON Schema — the editor's and the dev menu's detection key, the exact shape `dataRef` uses with `x-vgai-ref`. */
+/** How the marker rides out to the emitted JSON Schema — the editor's detection key, the exact shape `dataRef` uses with `x-vgai-ref`. */
 const CURVE_META_KEY = 'x-vgai-curve';
 
 function axisLabel(axes: CurveAxes, axis: 'x' | 'y'): string {
@@ -155,7 +155,7 @@ export function curve(axes: CurveAxes): z.ZodType<CurveValue> {
  * Read a curve field's declared axes back off a LIVE Zod schema (as opposed to
  * the emitted JSON Schema, which the editor's Data panel reads instead).
  *
- * This is the dev-menu capability's detection door: it derives its rows by
+ * This is the dev-tools capability's detection door: it derives its rows by
  * walking the game's own `TuningSchema` object, so it needs the axes from the
  * schema in hand. Wrappers (`.optional()`, `.default(…)`, `.describe(…)` chains
  * that re-wrap) hide the metadata behind an inner type, so a bounded unwrap

package/src/dev/instruments.ts

@@ -25,11 +25,11 @@
  * game registry.
  *
  * ── THE DOOR ────────────────────────────────────────────────────────────────
- * This module is IMPLEMENTATION ONLY. It publishes nothing itself: the dev-menu
- * capability's own registry adopts this list (`installDevMenuInstruments`) and
+ * This module is IMPLEMENTATION ONLY. It publishes nothing itself: the dev-tools
+ * capability's own registry adopts this list (`installDevToolsInstruments`) and
  * publishes each instrument through the SAME door every declaration in that
  * capability uses — one provider per reading (`instrument.timescale`), one
- * command per action (`instrument.timescale.set`), plus the `dev-menu` index
+ * command per action (`instrument.timescale.set`), plus the `dev-tools` index
  * provider. That is deliberate and load-bearing: the registry IS the product,
  * so every reader of an instrument reaches the SAME registration.
  *
@@ -43,7 +43,7 @@
  * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
  * {@link createDevInstruments} owns everything it allocates: the frame-time
  * ring buffer and its ONE `game.onRenderStep` subscription. SHARER: the
- * dev-menu capability's `DevMenuBridge`, which creates one set per mounted
+ * dev-tools capability's `DevToolsBridge`, which creates one set per mounted
  * game. TEARDOWN: the returned {@link DevInstrumentSet.dispose} — the ONE path
  * that ends it. Nothing else here holds a resource; the time-scale, pause and
  * collider instruments only drive state that `Game` already owns.

package/src/dev/register-render-vitals.ts

@@ -36,8 +36,8 @@
  *                        the drawing buffer halves was never fill-bound.
  *
  * ── GATING ──────────────────────────────────────────────────────────────────
- * The caller gates. Both seeders call this only under `devLayersEnabled()`
- * (`runtime/dev-layers.ts` — the ONE owner of "is this a dev context"), so a
+ * The caller gates. Both seeders call this only under `devBuildEnabled()`
+ * (`runtime/dev-build.ts` — the ONE owner of "is this a dev context"), so a
  * ship build registers nothing and pays nothing. Each also requires a `Game`
  * shell (there is no profiler to fold without one) and a non-headless mount
  * (nothing brackets a submission, so the readings could only ever be empty).

package/src/dev/static-batch-advisor.ts

@@ -6,7 +6,7 @@
  * require someone to ASK, and both require that someone to already know that
  * static batching exists, is possible here, and is spelled `<Frozen>`. An
  * agent building a game does not know any of that, so the measurement has to
- * do the routing itself — the same idiom as the dev-menu's unconfigured-section
+ * do the routing itself — the same idiom as dev-tools' unconfigured-section
  * warning: the reading names the exact edit.
  *
  * ── THE DECISION IS PURE, THE SCHEDULE IS NOT ───────────────────────────────
@@ -146,7 +146,7 @@ export function decideStaticBatchAdvisory(
  * Once per PAGE, not once per module evaluation — a hot reload re-runs this
  * module, and an advisory that reappears on every save is one that gets muted
  * along with everything else on the console. Same mechanism, and the same
- * reason, as the dev menu's unconfigured-section warning.
+ * reason, as dev-tools' unconfigured-section warning.
  */
 const WARNED_KEY = '__vgaiStaticBatchAdvised';
 

package/src/ecs/user-data.ts

@@ -111,6 +111,8 @@
  *                           JSX props for renderer/editor integration.
  * - `constraints`         — live project-owned spatial constraints projected
  *                           into the shared Inspector and viewport.
+ * - `authoringSubject`    — transient identity/inspection for an ecosystem-native
+ *                           subject represented by an Object3D proxy.
  * - `splineControlPoint`  — index of a spline control-point drag handle.
  * - `vcDirIdx`            — view-cube face direction index (0=+X,1=-X,2=+Y,...).
  */
@@ -118,6 +120,7 @@
 import type * as THREE from 'three';
 import type { ParticleSystem } from 'three.quarks';
 import type { ConstraintMark } from '../adapter/constraint';
+import type { Object3DAuthoringSubjectMark } from '../adapter/object3d-authoring-subject';
 import type { RapierEditableBody } from '../adapter/rapier-physics-adapter';
 import type { ReflectionProbeMark } from '../adapter/reflection-probe';
 import type { AnimationRuntimeInspection } from '../animation/runtime-inspection';
@@ -197,6 +200,7 @@ export interface UserDataSchema {
   skeletonEnabled: boolean;
   envObject: boolean;
   constraints: readonly ConstraintMark[];
+  authoringSubject: Object3DAuthoringSubjectMark;
   reflectionProbe: ReflectionProbeMark;
   vcDirIdx: number;
   /** W1a navmesh path-probe preview polyline: the routed waypoints, mirrored
@@ -252,6 +256,7 @@ export const UserDataKeys = {
   skeletonEnabled: 'skeletonEnabled',
   envObject: 'envObject',
   constraints: 'constraints',
+  authoringSubject: 'authoringSubject',
   reflectionProbe: 'reflectionProbe',
   vcDirIdx: 'vcDirIdx',
   navPathPoints: 'navPathPoints',

package/src/input/input-manager.ts

@@ -310,6 +310,9 @@ export class InputManager {
   private mouseButtonsJustUp = new Set<number>();
   private mouseDeltaX = 0;
   private mouseDeltaY = 0;
+  /** Last `mousemove` client position. Device-poll only — action maps read delta, not this. */
+  private mouseClientX = 0;
+  private mouseClientY = 0;
   private gamepads: (Gamepad | null)[] = [];
   // Gamepad button edge tracking (P1.6c). Keys are `${gamepadIndex}:${buttonIndex}`.
   // `Prev` is last frame's pressed set; `Down` is this frame's; the just-down/up
@@ -568,6 +571,8 @@ export class InputManager {
     if (e.movementX !== 0 || e.movementY !== 0) this.lastActiveDevice = 'mouse';
     this.mouseDeltaX += e.movementX;
     this.mouseDeltaY += e.movementY;
+    this.mouseClientX = e.clientX;
+    this.mouseClientY = e.clientY;
   };
 
   /** F2 — real window blur: drop focus and flush held REAL-device state
@@ -674,10 +679,32 @@ export class InputManager {
    * data reaches `isPressed`/`isJustPressed`/`isJustReleased`.
    */
   async loadMap(url: string) {
+    await this.fetchMap(url, false);
+  }
+
+  /**
+   * `loadMap`'s OPTIONAL sibling: apply the map at `url` when the project
+   * ships one and report `false` — SILENTLY — when it does not exist.
+   *
+   * The host loads the conventional map path at mount for every three/canvas
+   * root, including the scaffolded shape that has declared no actions yet, so
+   * "no map on disk" is the ordinary state of a brand-new project and must not
+   * print an error on every boot. Everything else stays exactly as loud as
+   * `loadMap`: a map that EXISTS and is malformed (or any non-404 failure)
+   * still logs and throws.
+   */
+  async loadMapIfPresent(url: string): Promise<boolean> {
+    return this.fetchMap(url, true);
+  }
+
+  /** Shared fetch/validate/apply for {@link loadMap} and
+   *  {@link loadMapIfPresent}; `optional` decides only what a 404 means. */
+  private async fetchMap(url: string, optional: boolean): Promise<boolean> {
     let data: InputMapFile;
     try {
       const res = await fetch(resolveUrl(url));
       if (!res.ok) {
+        if (optional && res.status === 404) return false;
         throw new Error(`HTTP ${res.status} ${res.statusText}`);
       }
       const json = await res.json();
@@ -692,6 +719,7 @@ export class InputManager {
       throw err instanceof AssetParseError ? err : new Error(message);
     }
     this.applyParsedMap(data);
+    return true;
   }
 
   /**
@@ -1690,6 +1718,99 @@ export class InputManager {
     return { x: this.mouseDeltaX, y: this.mouseDeltaY };
   }
 
+  /**
+   * Device-poll door (not an action binding). Every getter checks
+   * {@link inputActive} at READ time so a poll while play is off or the
+   * tab is unfocused is inert — the same predicate `onKeyDown` / `onMouseMove`
+   * already use. Inventing an implicit `registerAction` per key would define
+   * bindings the project's own `.inputmap` never named.
+   */
+  isDeviceKeyPressed(code: string): boolean {
+    if (!this.inputActive) return false;
+    return this.keysDown.has(code);
+  }
+
+  isDeviceKeyJustPressed(code: string): boolean {
+    if (!this.inputActive) return false;
+    return this.keysJustDown.has(code);
+  }
+
+  isDeviceKeyJustReleased(code: string): boolean {
+    if (!this.inputActive) return false;
+    return this.keysJustUp.has(code);
+  }
+
+  /** `button` is the DOM `MouseEvent.button` index (0 left, 1 middle, 2 right). */
+  isDeviceMouseButtonPressed(button: number): boolean {
+    if (!this.inputActive) return false;
+    return this.mouseButtons.has(button);
+  }
+
+  isDeviceMouseButtonJustPressed(button: number): boolean {
+    if (!this.inputActive) return false;
+    return this.mouseButtonsJustDown.has(button);
+  }
+
+  isDeviceMouseButtonJustReleased(button: number): boolean {
+    if (!this.inputActive) return false;
+    return this.mouseButtonsJustUp.has(button);
+  }
+
+  /**
+   * This-frame mouse delta in DOM space (Y +down). Callers that need Unity
+   * `Pointer.delta` (Y-up) flip Y themselves.
+   */
+  getDeviceMouseDelta(): { x: number; y: number } {
+    if (!this.inputActive) return { x: 0, y: 0 };
+    return { x: this.mouseDeltaX, y: this.mouseDeltaY };
+  }
+
+  /** Last `mousemove` client position in DOM space (origin top-left, Y +down). */
+  getDeviceMousePosition(): { x: number; y: number } {
+    if (!this.inputActive) return { x: 0, y: 0 };
+    return { x: this.mouseClientX, y: this.mouseClientY };
+  }
+
+  hasDeviceGamepad(): boolean {
+    if (!this.inputActive) return false;
+    return this.gamepads.some((pad) => pad !== null);
+  }
+
+  isDeviceGamepadButtonPressed(button: number): boolean {
+    if (!this.inputActive) return false;
+    const index = this.firstConnectedGamepadIndex();
+    if (index < 0) return false;
+    return this.gamepadButtonsDown.has(`${index}:${button}`);
+  }
+
+  isDeviceGamepadButtonJustPressed(button: number): boolean {
+    if (!this.inputActive) return false;
+    const index = this.firstConnectedGamepadIndex();
+    if (index < 0) return false;
+    return this.gamepadButtonsJustDown.has(`${index}:${button}`);
+  }
+
+  isDeviceGamepadButtonJustReleased(button: number): boolean {
+    if (!this.inputActive) return false;
+    const index = this.firstConnectedGamepadIndex();
+    if (index < 0) return false;
+    return this.gamepadButtonsJustUp.has(`${index}:${button}`);
+  }
+
+  getDeviceGamepadAxis(axis: number): number {
+    if (!this.inputActive) return 0;
+    const index = this.firstConnectedGamepadIndex();
+    if (index < 0) return 0;
+    return this.gamepads[index]?.axes[axis] ?? 0;
+  }
+
+  private firstConnectedGamepadIndex(): number {
+    for (let i = 0; i < this.gamepads.length; i++) {
+      if (this.gamepads[i] !== null) return i;
+    }
+    return -1;
+  }
+
   /**
    * F4 (spec §12 "Schema and Examples" — the F3 prompt-switching gap): which
    * device family most recently produced real input, or `null` before any
@@ -2295,6 +2416,30 @@ export class InputManager {
     element.addEventListener('click', this.onPointerLockClick);
   }
 
+  /**
+   * Release pointer lock on the element {@link requestPointerLock} wired.
+   *
+   * Godot's `Input.mouse_mode = MOUSE_MODE_VISIBLE` is this call: drop the
+   * lock if this manager holds it, and unwire the click-to-lock listener so a
+   * later click does not recapture. Idempotent. A host with no
+   * `document.exitPointerLock` (headless) still unwires — the lock never
+   * existed there.
+   *
+   * Only the lock THIS manager requested is released. An editor viewport
+   * holding lock on a different element is not ours to drop.
+   */
+  exitPointerLock() {
+    const el = this.pointerLockElement;
+    if (el) {
+      el.removeEventListener('click', this.onPointerLockClick);
+      this.pointerLockElement = null;
+    }
+    this.pointerLocked = false;
+    const doc = typeof document !== 'undefined' ? document : undefined;
+    if (!doc || typeof doc.exitPointerLock !== 'function') return;
+    if (el && doc.pointerLockElement === el) doc.exitPointerLock();
+  }
+
   /** Clean up event listeners */
   dispose() {
     if (this.disposed) return;

package/src/manifest/load.ts

@@ -79,9 +79,6 @@ export interface ResolvedAdapterRoot {
   readonly entry: string | undefined;
   readonly zOrder: number;
   readonly pausable: boolean;
-  /** `dev: true` — this root is a DEV LAYER, not shipped game content. See
-   *  `manifest/schema.ts`'s `dev` field for the four readers. */
-  readonly dev: boolean;
   readonly loop: 'gated' | 'self-driven';
 }
 
@@ -256,9 +253,6 @@ function checkEngineVersionPin(version: string): void {
  * resolution; `entry` drives the entry cross-field rule and is
  * carried through; `zOrder` drives the final sort; `pausable`/`loop` are
  * carried through as-is (their consumers are the runtime/CLI, T3.2/T3.3);
- * `dev` is carried through for the four dev-layer readers (`mountManifestRoots`'s
- * ship gate, the host's topmost stacking pass, the play compositor's capture
- * exclusion, and the editor's chrome-not-content seam);
  * `description` (T3.3
  * slice 3) is carried through as-is — its consumer today is
  * `resolveIngestDescriptor` (packages/editor/src/adapter-resolver.ts), which
@@ -276,7 +270,6 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
     entry: root.entry,
     zOrder: root.zOrder,
     pausable: root.pausable,
-    dev: root.dev,
     loop: root.loop,
   };
 }

package/src/manifest/schema.ts

@@ -315,19 +315,6 @@ export const AdapterRootSchema = z
       .boolean()
       .default(true)
       .describe('Whether play-mode pause/step applies to this root'),
-    dev: z
-      .boolean()
-      .default(false)
-      .describe(
-        "Marks this root as a DEV LAYER: the game's own dev GUI, not shipped game content. " +
-          'Four readers act on it. `mountManifestRoots` mounts it only when dev layers are ' +
-          'enabled (`devLayersEnabled`, runtime/dev-layers.ts), so a production build carries ' +
-          'no dev GUI; the host stacks every dev root ABOVE every non-dev root (a dev layer ' +
-          'sits topmost, and as a DOM layer it steals no input from the game while closed); ' +
-          'the play compositor EXCLUDES dev layers from a capture unless the capture asks for ' +
-          'them; and the editor mounts a dev root as edit-time CHROME rather than authorable ' +
-          'content (no hierarchy entry, no OID stamping, no JSX write-back, not selectable).',
-      ),
     loop: z
       .enum(['gated', 'self-driven'])
       .default('gated')
@@ -475,17 +462,9 @@ export const GameManifestSchema = z
         // root): a second root of the same medium parsed cleanly and was then
         // silently never mounted, which is the failure mode this rejects.
         //
-        // DEV LAYERS ARE COUNTED SEPARATELY. A `dev: true` root is not content
-        // competing for the medium — it is the game's dev GUI stacked above
-        // everything (`create-runtime.ts`'s stacking pass), and the editor
-        // mounts it as chrome, not as the one dom document. Counting it with
-        // the content roots would make the ratified shape — a game with a HUD
-        // and a dev panel, both `dom` — unrepresentable. The one-per-medium
-        // rule still applies WITHIN the dev band, for the same
-        // silently-never-mounted reason.
         const idsByMedium = new Map<string, string[]>();
         for (const root of roots) {
-          const medium = `${root.dev ? 'dev ' : ''}${rootMedium(root)}`;
+          const medium = rootMedium(root);
           const ids = idsByMedium.get(medium);
           if (ids) ids.push(root.id);
           else idsByMedium.set(medium, [root.id]);
@@ -507,9 +486,7 @@ export const GameManifestSchema = z
         "The Game's explicit, non-empty adapter-root composition. There is no implicit root. " +
           'Root ids are unique, and a project declares at most ONE world root per medium — ' +
           'one `three`, one `dom`, one canvas-surface root (first-party canvas, canvas ingest ' +
-          'and canvas module are the same medium). A `dev: true` root is counted in its own ' +
-          'band: a dev layer is chrome stacked above the game, not content competing for the ' +
-          'medium, so a game may declare a `dom` HUD and a `dom` dev layer — but not two of either.',
+          'and canvas module are the same medium).',
       ),
     authoring: z
       .object({