@vgai/engine 0.5.21 → 0.5.23

package/src/core/countdown-timer.ts

@@ -0,0 +1,188 @@
+/**
+ * `Countdown` — a restartable interval the CALLER steps, with the two
+ * behaviours under a frame hitch that decide whether a game's event count is
+ * right.
+ *
+ * A respawn delay, a weapon cooldown, a wave spawner, a grace window: each is
+ * "count down from N seconds, tell me, maybe go again, and let me restart or
+ * stop you at any point". `core/sim-clock.ts` schedules a one-shot at an
+ * ABSOLUTE sim time — the right shape for "3 seconds from now, once" and the
+ * wrong one for a live interval that game code re-arms, reads
+ * ({@link Countdown.remaining} is what a HUD ring draws) and cancels.
+ *
+ * That gap used to be papered over in `sim-clock.ts`'s own header, which said
+ * an `after` re-arming itself was "three lines the game owns". Those three
+ * lines are wrong in a way nobody notices: re-arming schedules the next fire
+ * from the moment the callback RAN, so every long frame permanently lengthens
+ * the interval, and a game that hitches ten times has silently slowed its
+ * spawner. That is the drift {@link Countdown} exists to not have.
+ *
+ * ## It owns no clock, and that is the requirement rather than a shortcut
+ *
+ * There is no `setTimeout`, no `setInterval`, no `requestAnimationFrame` and no
+ * subscription anywhere in this module. A countdown advances only inside
+ * {@link Countdown.advance}, from seconds the caller already has — the fixed
+ * loop's own dt. This repo runs a fixed-step sim with display-rate
+ * presentation and can step a game deterministically; a countdown on wall-clock
+ * `setTimeout` would be a second, undeterministic timeline that no care
+ * downstream could re-sync. A countdown nobody advances does not fire —
+ * visibly, rather than drifting.
+ *
+ * ## The frame-hitch contract, which is the whole reason this is a module
+ *
+ * Both rules are about keeping the EVENT COUNT correct when `dt` is larger than
+ * the period, which is exactly when a game is already in trouble:
+ *
+ *  - **Overshoot carries into the next period.** A 0.5 s repeating countdown
+ *    advanced by 0.6 fires once and has 0.4 s left, not 0.5. Resetting to the
+ *    full period instead would make one slow frame lengthen every interval
+ *    after it — the drift above, one layer down.
+ *  - **A single large step fires MORE THAN ONCE.** A 0.1 s countdown advanced
+ *    by 0.35 fires three times and has 0.05 s left. Dropping the extras would
+ *    silently slow a repeating countdown down whenever the frame was long, so a
+ *    wave that should have spawned 3 enemies spawns 1 and the difficulty curve
+ *    quietly depends on frame rate.
+ *
+ * Two consequences a caller must know about, both deliberate: `onElapsed` can
+ * be invoked several times within one `advance` call, and it runs INLINE
+ * (synchronously, inside `advance`) rather than on a microtask — so the caller
+ * always knows exactly which point of its frame the callback ran at.
+ *
+ * A one-shot countdown STOPS ITSELF BEFORE invoking `onElapsed`, so a callback
+ * that calls {@link Countdown.start} re-arms rather than fighting the stop.
+ * A callback that calls {@link Countdown.stop} ends the multi-fire loop
+ * immediately, which is what makes "fire once then disarm from inside the
+ * callback" work.
+ *
+ * ## Resource ownership
+ *
+ * **Owner:** whoever calls {@link createCountdown}. A countdown holds two
+ * numbers, a boolean and the `onElapsed` reference; it registers nothing,
+ * subscribes to nothing, and this module has no module-level state — so there
+ * is deliberately no `dispose()` and dropping the countdown drops everything it
+ * had. **Sharers:** none; a countdown is not shareable, because whoever
+ * advances it decides its timeline. **Teardown:** what DOES need unregistering
+ * is the countdown's slot in whatever set the owner advances each frame, and
+ * that is the owner's — the same way `SceneTree.addTimer` hands back a remover.
+ */
+
+/** A restartable countdown. Build one with {@link createCountdown}. */
+export interface Countdown {
+  /** Seconds it counts from. Reflects the last {@link Countdown.start} that
+   *  passed a duration. */
+  readonly duration: number;
+  /** Does it re-arm itself after firing, or stop? */
+  readonly repeats: boolean;
+  /** Seconds left, or 0 when it is not running. */
+  readonly remaining: number;
+  /** Is it counting? */
+  readonly running: boolean;
+  /**
+   * Start, or RESTART a running countdown from the top. Passing `duration`
+   * overwrites {@link Countdown.duration} for this and every later start.
+   *
+   * @throws RangeError if `duration` is not a finite positive number of
+   * seconds. A non-positive period cannot fire and reads as a hung game
+   * rather than a misconfigured one, so it refuses at the call site.
+   */
+  start(duration?: number): void;
+  /** Stop counting. Invokes nothing. */
+  stop(): void;
+  /**
+   * Advance by `dt` SECONDS, invoking `onElapsed` once per completed period —
+   * possibly several times in one call. See the module header's frame-hitch
+   * contract.
+   */
+  advance(dt: number): void;
+}
+
+/** What {@link createCountdown} needs. */
+export interface CountdownOptions {
+  /** Seconds to count from. Default 1. */
+  readonly duration?: number;
+  /** Re-arm after firing instead of stopping. Default `false` (one-shot). */
+  readonly repeats?: boolean;
+  /** Begin counting immediately instead of waiting for a `start()`. Default
+   *  `false`. */
+  readonly autostart?: boolean;
+  /** Invoked inline, once per completed period. */
+  readonly onElapsed: () => void;
+}
+
+function assertDuration(value: number): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(
+      `createCountdown: duration must be a finite, positive number of seconds, got ${String(value)}`,
+    );
+  }
+}
+
+/**
+ * Build a countdown.
+ *
+ * ```ts
+ * const wave = createCountdown({ duration: 8, repeats: true, autostart: true, onElapsed: spawnWave });
+ * useFrame((_, dt) => wave.advance(dt));   // the caller owns the step
+ * ```
+ */
+export function createCountdown(options: CountdownOptions): Countdown {
+  const onElapsed = options.onElapsed;
+  const repeats = options.repeats === true;
+  let duration = options.duration ?? 1;
+  let remaining = 0;
+  let running = false;
+
+  assertDuration(duration);
+
+  const countdown: Countdown = {
+    get duration(): number {
+      return duration;
+    },
+    get repeats(): boolean {
+      return repeats;
+    },
+    get remaining(): number {
+      return running ? remaining : 0;
+    },
+    get running(): boolean {
+      return running;
+    },
+
+    start(newDuration): void {
+      if (newDuration !== undefined) {
+        assertDuration(newDuration);
+        duration = newDuration;
+      }
+      remaining = duration;
+      running = true;
+    },
+
+    stop(): void {
+      running = false;
+      remaining = 0;
+    },
+
+    advance(dt): void {
+      if (!running) return;
+      remaining -= dt;
+      // The loop is the multi-fire rule; `running` in the condition is what
+      // lets a callback's own stop() end it. Module header, frame-hitch.
+      while (running && remaining <= 0) {
+        if (!repeats) {
+          // Disarm BEFORE invoking, so a callback that calls start() re-arms
+          // instead of being immediately stopped by this branch.
+          running = false;
+          remaining = 0;
+          onElapsed();
+          return;
+        }
+        // Carry the overshoot rather than resetting to the full period.
+        remaining += duration;
+        onElapsed();
+      }
+    },
+  };
+
+  if (options.autostart === true) countdown.start();
+  return countdown;
+}

package/src/core/deferred-commands.ts

@@ -0,0 +1,174 @@
+/**
+ * `DeferredCommands` — work the caller runs at ONE point it chooses, plus the
+ * subject-keyed disposal that has to land after it.
+ *
+ * The hazard is not exotic and it is not a foreign engine's: it is what a
+ * Rapier world does to anything that mutates it from inside a callback. Disable
+ * a collider while the solver is iterating, or free the node a collision
+ * handler was dispatched ON, and the failure is either a corrupt step or
+ * Rapier's own "recursive use of an object ... unsafe aliasing in rust". The
+ * remedy is always the same shape — write down WHAT to do, do it once the frame
+ * is out of anybody's way — and every caller that needs it was previously
+ * hand-rolling an array.
+ *
+ * ## The one point is the CALLER's, deliberately
+ *
+ * There is no `queueMicrotask`, no `setTimeout(0)`, no `requestAnimationFrame`
+ * and no subscription anywhere in this module. Whoever builds the queue decides
+ * where {@link DeferredCommands.drain} runs — after physics, at the tail of a
+ * world's update, wherever the frame's quiet moment actually is. A queue nobody
+ * drains simply does not run its work, which is a visible failure rather than a
+ * silent reordering onto a timeline the game does not control.
+ *
+ * ## This is NOT `SimClock`, and `after(0)` is not a substitute
+ *
+ * `core/sim-clock.ts` schedules on SIM TIME: `after(0, fn)` scheduled mid-frame
+ * does land in that frame's tail flush (`runtime/game.ts` calls `flush(simT)`
+ * after every phase of every world), so the resemblance is real and worth
+ * naming. Three things make it the wrong tool for deferral:
+ *
+ *  - **A paused world never flushes.** `flush` is inside `runFrameImpl`'s
+ *    `advanced` guard, so a game that pauses between the defer and the drain
+ *    holds the work forever. End-of-frame deferral has to run on the frame,
+ *    not on the clock.
+ *  - **No subject identity.** Deferring destruction needs "this object, once",
+ *    and needs the two questions that fall out of it —
+ *    {@link DeferredCommands.isDisposePending} (a handler must be able to skip
+ *    a subject that is already going away) and
+ *    {@link DeferredCommands.wasDisposed} (an owner sweeping its own indexes
+ *    after the drain). A time-ordered timer set answers neither.
+ *  - **No same-drain re-entry.** A sim timer scheduled during a flush is
+ *    deliberately never due in that flush; a deferred command that defers one
+ *    more command must still land this frame, or the second write arrives a
+ *    frame after the first and the two are no longer atomic.
+ *
+ * ## Ordering, and why disposal goes last
+ *
+ * {@link DeferredCommands.drain} runs every deferred command first, re-draining
+ * until the queue is empty, and only then disposes every pending subject. That
+ * order is not cosmetic: a deferred write to a subject that is ALSO queued for
+ * disposal must still happen — it is what the caller asked for — and disposing
+ * first would make that write operate on a freed handle. A subject queued twice
+ * is disposed once, and the FIRST thunk wins (every caller for one subject
+ * passes the same one).
+ *
+ * The re-drain is bounded by {@link MAX_DRAIN_PASSES}. A command that defers
+ * itself forever is a bug in the caller, and a bounded loop names it in a
+ * millisecond instead of hanging the frame.
+ *
+ * ## Why disposal carries its own thunk
+ *
+ * Disposal is the one thing here that is not surface-neutral. A `PIXI.Container`
+ * ends with `removeFromParent()` + `destroy({ children })`; a `THREE.Object3D`
+ * ends by detaching and disposing the geometries and materials underneath it;
+ * a physics-backed entity has a Rapier body to pull first. This queue does none
+ * of that — it takes the thunk from whoever owns the surface and runs it at the
+ * drain. So the ORDERING lives here once and the surface knowledge stays where
+ * the surface is, which is what lets one queue serve a 2D world and a 3D one.
+ *
+ * ## Resource ownership
+ *
+ * **Owner:** whoever calls {@link createDeferredCommands}, and that owner is
+ * also the only caller of `drain()` — a queue is per-DRAINER, not per-process,
+ * so two mounted games are two queues and neither can see the other's work.
+ * This module registers nothing anywhere: there is no game-scoped slot (unlike
+ * `sim-clock.ts`, which needs one because every world on a Game shares one
+ * clock) and no module-level state at all.
+ * **Sharers:** the queued subjects, by reference, and only until the drain that
+ * disposes them.
+ * **Teardown:** dropping the queue. There is deliberately no `dispose()` —
+ * nothing here holds a handle, a listener or a timer, and a queue dropped with
+ * work still in it has simply not run that work, which is what discarding a
+ * frame means.
+ */
+
+/**
+ * How many times {@link DeferredCommands.drain} re-drains a queue that keeps
+ * refilling itself before declaring the caller's own logic non-terminating.
+ *
+ * A bound that correct code cannot reach (a deferred command that defers one
+ * more, ten deep) while catching the infinite case immediately.
+ */
+export const MAX_DRAIN_PASSES = 16;
+
+/** The queue. Build one per drainer with {@link createDeferredCommands}. */
+export interface DeferredCommands {
+  /**
+   * Run `command` at the next {@link DeferredCommands.drain}.
+   *
+   * ```ts
+   * // inside a collision handler, where the solver still owns the world:
+   * frame.defer(() => collider.setSensor(true));
+   * ```
+   */
+  defer(command: () => void): void;
+  /**
+   * Dispose `subject` at the next drain, after every deferred command has run.
+   * Queuing the same subject twice disposes it once — the first `dispose`
+   * thunk wins.
+   */
+  deferDispose(subject: object, dispose: () => void): void;
+  /**
+   * Is `subject` queued for disposal and not yet disposed? Read by a handler
+   * that must skip a subject already on its way out.
+   */
+  isDisposePending(subject: object): boolean;
+  /**
+   * Has THIS queue already disposed `subject`? Read after a drain by an owner
+   * sweeping its own indexes (a group, a registry, a spatial bucket) — "am I
+   * destroyed" is a surface-specific question that a plain `Object3D` has no
+   * answer to, so the queue is asked instead.
+   */
+  wasDisposed(subject: object): boolean;
+  /** Run every deferred command (re-draining), then dispose every pending
+   *  subject. Called once per frame, by the owner, at the point it chose. */
+  drain(): void;
+}
+
+/** Build one queue. See the module header for who owns it and who drains it. */
+export function createDeferredCommands(): DeferredCommands {
+  let commands: (() => void)[] = [];
+  const doomed = new Map<object, () => void>();
+  const disposed = new WeakSet<object>();
+
+  return {
+    defer(command): void {
+      commands.push(command);
+    },
+
+    deferDispose(subject, dispose): void {
+      if (!doomed.has(subject)) doomed.set(subject, dispose);
+    },
+
+    isDisposePending(subject): boolean {
+      return doomed.has(subject);
+    },
+
+    wasDisposed(subject): boolean {
+      return disposed.has(subject);
+    },
+
+    drain(): void {
+      let passes = 0;
+      while (commands.length > 0) {
+        if (++passes > MAX_DRAIN_PASSES) {
+          throw new Error(
+            `DeferredCommands.drain: still queueing more work after ${MAX_DRAIN_PASSES} passes. ` +
+              'Something passed to defer() defers itself, so this drain would never terminate.',
+          );
+        }
+        const batch = commands;
+        commands = [];
+        for (const command of batch) command();
+      }
+
+      // Subjects last, and only after every deferred command has run — see the
+      // module header's ordering section.
+      for (const [subject, dispose] of doomed) {
+        dispose();
+        disposed.add(subject);
+      }
+      doomed.clear();
+    },
+  };
+}

package/src/core/frame-pacing.ts

@@ -1,6 +1,6 @@
 /**
  * Frame pacing — the accumulator/alpha arithmetic of the fixed-timestep loop,
- * extracted PURE (WO-P13, `docs/WORK.md` §2 P13).
+ * extracted PURE.
  *
  * `core/game-loop.ts` owns the browser side (rAF, `visibilitychange`,
  * `performance.now`); this module owns the arithmetic, so the interesting
@@ -108,7 +108,7 @@ export function paceFrame(
   const maxAccumulator = fixedDt * maxSubSteps;
 
   // Clamp large frame gaps (a slow frame, a debugger pause) BEFORE scaling by
-  // timeScale — unchanged from the pre-WO-P13 loop.
+  // timeScale.
   const displayDt = Math.min(rawDt, maxAccumulator) * timeScale;
   let next = accumulator + displayDt;
   // Spiral-of-death guard: bound the accumulator regardless of timeScale or

package/src/core/game-loop.ts

@@ -9,9 +9,7 @@ const LOOP_STARVATION_MS = 1_000;
 
 /**
  * Fixed-timestep game loop with accumulator pattern — SIM at a fixed rate,
- * PRESENTATION at the display's rate (WO-P13, `docs/WORK.md` §2 P13, which
- * flipped the former D1 "render is fixed-rate too" decision this comment used
- * to state).
+ * PRESENTATION at the display's rate.
  *
  * Per real (rAF) frame:
  *

package/src/core/seeded-random.ts

@@ -42,7 +42,7 @@ export const GAMEPLAY_STREAM = 'gameplay';
 export const DEFAULT_SEEDED_RANDOM_SEED = 0x9e3779b9;
 
 /**
- * The `ctx.random` surface (`GameContext.random`, `runtime/types.ts`).
+ * A game-scoped random surface.
  * Callable (draws from the `'gameplay'` stream), plus:
  * - `stream(name)` — an independent named generator, `[0, 1)` floats, same
  *   call signature as `Math.random`/the bare `SeededRandom` call itself.

package/src/core/sim-clock.ts

@@ -93,10 +93,9 @@
  * controller cancels everything a `setup()` scheduled:
  *
  * ```ts
- * export async function setup(ctx: GameContext): Promise<GameCleanup> {
- *   const ac = new AbortController();
- *   ctx.clock.after(3, () => spawnWave(), { signal: ac.signal });
- *   return { dispose: () => ac.abort() }; // cancels timers AND listeners
+ * const ac = new AbortController();
+ * clock.after(3, () => spawnWave(), { signal: ac.signal });
+ * // on dispose: ac.abort() — cancels timers AND listeners
  * }
  * ```
  *
@@ -105,8 +104,20 @@
  *
  * ## Deliberately absent
  *
- *  - **No `every`/`repeat`/interval.** Nothing needs one, and `after`
- *    re-arming itself is three lines the game owns.
+ *  - **No `every`/`repeat`/interval — that is `core/countdown-timer.ts`.**
+ *    This header used to say an `after` re-arming itself was "three lines the
+ *    game owns"; it is three lines that DRIFT, because re-arming schedules the
+ *    next fire from the moment the callback ran, so every long frame
+ *    permanently lengthens the interval. A repeating interval needs
+ *    overshoot carry and multi-fire on a big step to keep its event count
+ *    right, and it is stepped by its owner rather than by the clock. Both
+ *    belong to a countdown object, not to a sim-time one-shot.
+ *  - **No end-of-frame command queue — that is
+ *    `core/deferred-commands.ts`.** `after(0, fn)` looks like one (the flush
+ *    below does run at the tail of the frame that scheduled it) and is not:
+ *    it holds the work forever across a pause, it has no subject identity, and
+ *    a command it schedules during a flush waits a whole extra frame. See that
+ *    module's header for all three.
  *  - **No fiber kernel, no coroutine emulation, no `task.spawn`.** Calling an
  *    `async function` *is* `task.spawn` — the language already has it.
  *  - **No wall clock.** This module reads no system timer and creates no
@@ -158,7 +169,7 @@ export interface SimClock {
 /**
  * The runtime-facing half — NOT for game code. Split off the public
  * {@link SimClock} the same way `runtime/game.ts` splits `GameInternal` off
- * `Game`: `GameContext.clock` is typed as `SimClock`, so game code cannot
+ * `Game`: game code only ever sees the public `SimClock`, so it cannot
  * reach `flush`/`dispose`.
  */
 export interface SimClockInternal extends SimClock {
@@ -382,7 +393,7 @@ export function registerSimClock(owner: object, clock: SimClockInternal): void {
  *  Returns the INTERNAL view because this registry is engine-only — but a
  *  caller that RESOLVES a clock here is not its owner and must not call
  *  `dispose()` on it (module header, ownership). Game code never reaches it at
- *  all: `GameContext.clock` is typed as the public {@link SimClock}, which has
+ *  all: it only ever sees the public {@link SimClock}, which has
  *  neither `flush` nor `dispose`, the same way `Game` hides `GameInternal`. */
 export function getSimClock(owner: object): SimClockInternal | null {
   return clockByOwner.get(owner) ?? null;

package/src/core/types.ts

@@ -72,9 +72,7 @@ export interface GameLoopConfig {
    */
   update: (dt: number) => void;
   /**
-   * Called EXACTLY ONCE per real (rAF) frame — the PRESENTATION half
-   * (WO-P13, `docs/WORK.md` §2 P13; this is the callback whose absence the
-   * former D1 decision recorded).
+   * Called EXACTLY ONCE per real (rAF) frame — the PRESENTATION half.
    *
    * - `alpha` — `accumulator / fixedDt` after this frame's substeps were
    *   consumed, in `[0, 1]`: how far presentation sits past the last

package/src/defaults.ts

@@ -1,20 +1,12 @@
 /**
  * Single source of truth for default values the engine's factories read.
  *
- * WO-8 deleted SEVEN groups — `transform`, `entity`, `audio`, `shadow`,
- * `animation`, `fog`, `environment` — because every one of their readers was a
- * `.vscn.json` consumer (`entity-factory.ts`, `scene-loader.ts`,
- * `scene-sync.ts`, `scene-serializer.ts`, the per-section inspectors) and
- * `defaults-source-scan.test.ts` reported them with ZERO `DEFAULTS.<group>`
- * readers anywhere in engine/editor src or tests. That guard offers two remedies
- * — wire the group to the factory that reads it, or delete it if truly unused —
- * and there is no surviving factory to wire these to: `transform` restated
- * THREE's own Object3D constructor values, `entity.locked`/ `pivot` were
- * descriptor-only fields, and `fog`/`environment.envMapIntensity`/ `shadow` were
- * the `.vscn` `environment` block that `render-env.ts` explicitly did NOT carry
- * forward. Keeping them would have been exactly the dead documentation T1.13
- * created this guard to prevent.
- *
+ * A group belongs here only while a FACTORY reads it. A default with no
+ * reader is dead documentation: it looks authoritative, nothing consults it,
+ * and it drifts from the value the code actually uses. Restating a library's
+ * own constructor values (THREE's `Object3D` transform, say) is the same
+ * mistake in a different shape — the library is already the source of truth.
+ * So when a factory goes, its group goes with it.
  */
 export const DEFAULTS = {
   material: {

package/src/dev/instruments.ts

@@ -25,13 +25,13 @@
  * game registry.
  *
  * ── THE DOOR ────────────────────────────────────────────────────────────────
- * 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-tools` index
- * provider. That is deliberate and load-bearing: the registry IS the product,
- * so every reader of an instrument reaches the SAME registration.
+ * The HOST publishes these itself ({@link publishDevInstruments}, called by
+ * the mount install paths): one provider per reading
+ * (`instrument.timescale`), one command per action
+ * (`instrument.timescale.set`), plus the `instruments` index provider. The
+ * registry IS the product, so every reader of an instrument reaches the SAME
+ * registration — and a game writes zero lines and mounts nothing to have
+ * them.
  *
  * ── DEGRADING ───────────────────────────────────────────────────────────────
  * An instrument whose subject this game does not have (no physics adapter ⇒ no
@@ -42,16 +42,17 @@
  *
  * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
  * {@link createDevInstruments} owns everything it allocates: the frame-time
- * ring buffer and its ONE `game.onRenderStep` subscription. SHARER: the
- * 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
+ * ring buffer and its ONE `game.onRenderStep` subscription. SHARER: the host
+ * install path ({@link publishDevInstruments}), 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.
  */
 
 import { z } from 'zod';
 import { nodeKeyedPhysics } from '../adapter/system-adapter';
 import { clampTimeScale, TIME_SCALE_RANGE } from '../core/frame-pacing';
+import { getDebugRegistry } from '../runtime/debug-registry';
 import type { Game } from '../runtime/game';
 
 /** What shape an instrument's reading is, and what drives it. Data, not
@@ -304,3 +305,99 @@ export function createDevInstruments(game: Game): DevInstrumentSet {
 function now(): number {
   return typeof performance === 'undefined' ? Date.now() : performance.now();
 }
+
+// ---------------------------------------------------------------------------
+// Host publication — the instruments' OWN door
+// ---------------------------------------------------------------------------
+//
+// The HOST publishes these (the editor's mount install path), so every game
+// gets them for literally zero lines — no capability, no bridge component, no
+// mount. One provider per reading (`instrument.timescale`), one command per
+// action (`instrument.timescale.set`), plus ONE index provider
+// (`instruments`) carrying every descriptor with this instant's values, so an
+// outside reader gets the whole panel in one round trip. Naming is unchanged
+// from when the dev-tools capability published them, so every existing reader
+// keeps working; only the publisher moved realms.
+
+/** The index provider's name. */
+export const INSTRUMENTS_PROVIDER = 'instruments';
+
+/** The registry scope the host publishes under. Not a mounted world —
+ *  instruments are game-scoped host furniture, like the hooks' `__react__`. */
+const INSTRUMENTS_WORLD_ID = '__instruments__';
+
+/** One instrument in the index: descriptor plus this instant's value. A
+ *  throwing read is reported as itself, never swallowed. */
+export interface PublishedInstrumentReading {
+  readonly name: string;
+  readonly id: string;
+  readonly label: string;
+  readonly hint: string;
+  readonly unit?: string;
+  readonly control: DevInstrumentControl;
+  readonly actions: readonly {
+    readonly name: string;
+    readonly id: string;
+    readonly label: string;
+    readonly hint: string;
+  }[];
+  readonly value: unknown;
+  readonly error?: string;
+}
+
+function readingOf(instrument: DevInstrument): PublishedInstrumentReading {
+  const base = {
+    name: `instrument.${instrument.id}`,
+    id: instrument.id,
+    label: instrument.label,
+    hint: instrument.hint,
+    ...(instrument.unit === undefined ? {} : { unit: instrument.unit }),
+    control: instrument.control,
+    actions: instrument.actions.map((action) => ({
+      name: `instrument.${instrument.id}.${action.id}`,
+      id: action.id,
+      label: action.label,
+      hint: action.hint,
+    })),
+  };
+  try {
+    return { ...base, value: instrument.read() };
+  } catch (error) {
+    return { ...base, value: null, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * Create this game's instrument set and register every door on its debug
+ * registry. Called once per mounted Game by the host install path; the
+ * returned disposer ends the set's one resource (the frame-time
+ * subscription) — the registrations die with the Game itself.
+ */
+export function publishDevInstruments(game: Game): () => void {
+  const registry = getDebugRegistry(game);
+  if (!registry) {
+    throw new Error('Cannot publish dev instruments: mounted Game has no debug registry.');
+  }
+  const set = createDevInstruments(game);
+  const scope = registry.forRoot(INSTRUMENTS_WORLD_ID);
+  for (const instrument of set.instruments) {
+    scope.registerStateProvider(`instrument.${instrument.id}`, () => instrument.read(), {
+      tier: 'assisted',
+    });
+    for (const action of instrument.actions) {
+      scope.registerCommand(
+        `instrument.${instrument.id}.${action.id}`,
+        {
+          description: `${instrument.label}: ${action.label} — ${action.hint}`,
+          locus: 'client',
+          args: action.args,
+        },
+        (...values: unknown[]) => action.run(values),
+      );
+    }
+  }
+  scope.registerStateProvider(INSTRUMENTS_PROVIDER, () => set.instruments.map(readingOf), {
+    tier: 'assisted',
+  });
+  return () => set.dispose();
+}

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

@@ -8,10 +8,7 @@
  *
  * Engine-owned and first-party, seeded by BOTH three-root mount paths — a game
  * writes nothing to get these, and there is no capability to install:
- *  - `adapter/setup-three-root-adapter.ts` (the classic imperative
- *    `setup(ctx)` world), at the same spot it seeds
- *    `systemAdapters.renderDebug`;
- *  - `world3d-react/r3f-adapter.tsx` (a TSX/R3F world — the shape EVERY
+ *  - `world3d-react/r3f-root-factory.tsx` (a TSX/R3F world — the shape EVERY
  *    scaffolded project's three root has), right after fiber's first commit
  *    resolves the scene.
  * Both is the whole point and not redundancy: they are two independent mounts

package/src/dev/render-debug-adapter.ts

@@ -3,11 +3,10 @@
  * the WebGL2 frame capture (`webgl-frame-capture.ts`), a live three.js scene,
  * and the render adapter's per-frame render pass.
  *
- * Split OUT of `setup-three-root-adapter.ts` so the capture/attribution/restore
+ * Split OUT of `world3d-react/r3f-root-factory.tsx` so the capture/attribution/restore
  * flow is unit-testable in a headless Node test with a mock GL context and a
  * plain scene — a real non-headless GPU mount (EffectComposer + WebGLRenderer)
- * cannot run under vitest here, the same reason the adapter suite drives
- * `setup(ctx)` only through hotReload on a data scene. `mount()` owns the
+ * cannot run under vitest here. `mount()` owns the
  * DECISION to construct this (only under a real WebGL2 context, never
  * headless — see `frameCaptureContextFor`); this module owns the BEHAVIOR.
  *