@vgai/engine 0.2.0

package/src/adapter/ingest/scene-capture.ts

@@ -0,0 +1,307 @@
+/**
+ * Scene capture — the core primitive of unmodified-game ingestion.
+ *
+ * An external three.js game owns its own `WebGLRenderer`, `Scene`, camera, and
+ * render loop. To let the editor inspect/edit that live scene WITHOUT touching
+ * the game's code, we need a handle to the game's `Scene`+camera the moment it
+ * first renders. The robust way to obtain it is an **accessor trap** on
+ * `WebGLRenderer.prototype.render`:
+ *
+ *   - `WebGLRenderer` assigns `this.render` as an OWN instance property inside
+ *     its constructor (not on the prototype), and `THREE.WebGLRenderer` is a
+ *     read-only module export (can't subclass-swap it). A naive "wrap render"
+ *     hook therefore captures nothing.
+ *   - Installing a getter/setter for `render` on the PROTOTYPE means the
+ *     constructor's `this.render = realFn` hits our setter (the instance has no
+ *     own `render` yet), we stash the real fn, and our getter returns a wrapper
+ *     that captures `(scene, camera, renderer)` on the first real frame.
+ *
+ * This is the hardened, typed form of the `ingest-study` spike
+ * (`docs/ingest-study-spike/vgai-ingest-adapter.js`), proven against an
+ * unmodified `three.js/examples/games_fps` game.
+ *
+ * CRITICAL: the trap must be installed on the SAME `three` module instance the
+ * game uses. In a bundler/dev-server that dedupes `three` (one `node_modules/
+ * three`), an external ESM game's `import 'three'` resolves to that one instance,
+ * so passing the host's `THREE` here traps the game's renderer too. A game that
+ * bundles its own copy of `three` cannot be captured this way (see
+ * `docs/UNMODIFIED-GAME-INGESTION-STUDY.md` §4A — the module-identity gatekeeper).
+ *
+ * Wave 17 (`docs/WAVE17-F13-COMPOSER-RESIZE-FIX-DESIGN.md`) adds an OPTIONAL,
+ * ADDITIVE composer capture: a game rendering through its own three.js addon
+ * `EffectComposer` (`three/examples/jsm/postprocessing/EffectComposer.js`)
+ * still trips the `render` trap above (its `RenderPass` calls
+ * `renderer.render(scene,camera)` internally), but the renderer holds no
+ * reference back to the composer, so the host previously could not resize the
+ * composer's own (intentionally non-1:1, progressively-downsampled — see
+ * `UnrealBloomPass`) render targets when the host resizes the game's pane.
+ * Unlike `WebGLRenderer`, `EffectComposer` is a plain ES class whose methods
+ * (including `render`) live on the PROTOTYPE, not assigned as own instance
+ * properties in the constructor — so a direct method-wrapper (no getter/
+ * setter indirection) on `EffectComposer.prototype.render` is sufficient: it
+ * calls through to the real `render`, then — AFTER that call, so any nested
+ * `renderer.render()` the pass makes has already hit the trap above and set
+ * `captured` — records `this` (the composer instance) if its `.renderer` is
+ * the captured one. This is deduped/shared-trappable for the same reason
+ * `WebGLRenderer` is: `EffectComposer.js` is a FILE inside the same `three`
+ * package tree Vite's `resolve.dedupe: ['three', …]` already collapses to one
+ * instance — not a separate package with its own dedupe question. Proven
+ * live against the `bloom-composer` fixture
+ * (`docs/f13-bloom-composer-proof/record-fixed.mjs`).
+ */
+
+import type * as THREE from 'three';
+
+/** A live runtime captured from an external game on its first rendered frame. */
+export interface CapturedRuntime {
+  scene: THREE.Scene;
+  camera: THREE.Camera;
+  renderer: THREE.WebGLRenderer;
+}
+
+/** Handle returned by {@link installSceneCapture}. */
+export interface SceneCaptureHandle {
+  /** The captured runtime, or null until the game renders its first frame. */
+  readonly captured: CapturedRuntime | null;
+  /** Resolve once a scene+camera is captured (rejects on timeout). */
+  waitForCapture(timeoutMs?: number): Promise<CapturedRuntime>;
+  /** Total `render()` calls observed through the trap (a liveness signal). */
+  getDrawCount(): number;
+  /** The game's last (non-null) `setAnimationLoop` callback for a renderer, so the
+   *  host can pause (set null) and resume (re-set it) the game's own loop. */
+  getAnimationLoop(renderer: THREE.WebGLRenderer): ((time: number) => void) | null;
+  /**
+   * Wave 17 (D-C3): resize every captured `EffectComposer` that renders
+   * through the captured renderer to `w`×`h`, matching its pixel ratio to
+   * `renderer.getPixelRatio()` — the composer tracks whatever DPR policy the
+   * host already applies to the renderer; no separate knob. A no-op when no
+   * `effectComposerCtor` was passed to {@link installSceneCapture} (or no
+   * composer of that ctor has rendered through the captured renderer yet) —
+   * a non-composer game is unaffected.
+   */
+  resizeComposers(w: number, h: number): void;
+  /** Remove the trap and restore the captured renderer's real `render`. */
+  uninstall(): void;
+}
+
+// Minimal structural type for the bits of the THREE namespace we touch, so this
+// module never imports a concrete `three` (it must trap the CALLER's instance).
+interface ThreeLike {
+  WebGLRenderer: { prototype: Record<string, unknown> };
+}
+
+// Minimal structural type for the bits of an `EffectComposer` instance we
+// touch. This module never imports a concrete `three/examples/jsm/…` addon
+// either — the caller passes the SAME class its ingested game imports, so the
+// trap lands on the instance the game actually constructs.
+interface ComposerLike {
+  renderer?: unknown;
+  setSize(width: number, height: number): void;
+  setPixelRatio(pixelRatio: number): void;
+}
+
+interface EffectComposerCtorLike {
+  prototype: { render?: (...args: unknown[]) => unknown };
+}
+
+/**
+ * Install the render accessor trap on `threeNamespace.WebGLRenderer.prototype`.
+ * Pass the host's `three` module so the game (which shares it) is trapped.
+ *
+ * `effectComposerCtor` is OPTIONAL (Wave 17, D-C2): pass the host's
+ * `EffectComposer` class (`three/examples/jsm/postprocessing/EffectComposer.js`)
+ * to also trap composer construction/rendering on that shared addon, so
+ * `resizeComposers()` can reach it. Omitting it (or a game never constructing
+ * one) leaves capture byte-identical to before this wave.
+ *
+ * Idempotent per call site is NOT guaranteed — install once per ingest session
+ * and `uninstall()` on teardown.
+ */
+export function installSceneCapture(
+  threeNamespace: unknown,
+  effectComposerCtor?: unknown,
+): SceneCaptureHandle {
+  const THREE_NS = threeNamespace as ThreeLike;
+  const proto = THREE_NS.WebGLRenderer.prototype;
+
+  // Stash the real render fn per-instance under a unique symbol so multiple
+  // renderers (editor's + game's) never collide.
+  const REAL = Symbol('vgai.realRender');
+
+  let captured: CapturedRuntime | null = null;
+  let drawCount = 0;
+  const waiters: Array<(rt: CapturedRuntime) => void> = [];
+
+  // Preserve any descriptor already on the prototype so uninstall can restore it.
+  const priorDescriptor = Object.getOwnPropertyDescriptor(proto, 'render');
+
+  // Trap setAnimationLoop to record each renderer's game loop callback, so the host
+  // can freeze (set null) and resume (re-set) the game's own rAF for stable editing.
+  // CRITICAL: like `render`, WebGLRenderer assigns `this.setAnimationLoop` as an OWN
+  // instance property in its constructor — NOT on the prototype. A naive value-wrapper
+  // on the prototype is therefore shadowed by the instance's own property and never
+  // runs (resume could never recover the callback). So we mirror the `render` trap: a
+  // prototype getter/setter. The constructor's `this.setAnimationLoop = realFn` hits
+  // our SETTER (the instance has no own property yet) and we stash realFn per-instance;
+  // the GETTER returns a wrapper that records each non-null callback before forwarding.
+  const REAL_SAL = Symbol('vgai.realSetAnimationLoop');
+  const loopCallbacks = new WeakMap<object, (time: number) => void>();
+  const priorSAL = Object.getOwnPropertyDescriptor(proto, 'setAnimationLoop');
+  Object.defineProperty(proto, 'setAnimationLoop', {
+    configurable: true,
+    set(this: Record<symbol, unknown>, fn: unknown) {
+      this[REAL_SAL] = fn;
+    },
+    get(this: Record<symbol, unknown>) {
+      const self = this;
+      return function setAnimationLoop(this: unknown, cb: unknown) {
+        if (cb) loopCallbacks.set(self as object, cb as (time: number) => void);
+        const real = self[REAL_SAL];
+        return typeof real === 'function'
+          ? (real as (...a: unknown[]) => unknown).call(self, cb)
+          : undefined;
+      };
+    },
+  });
+
+  Object.defineProperty(proto, 'render', {
+    configurable: true,
+    set(this: Record<symbol, unknown>, fn: unknown) {
+      this[REAL] = fn;
+    },
+    get(this: Record<symbol, unknown>) {
+      const self = this;
+      return function render(this: unknown, ...args: unknown[]) {
+        const [scene, camera] = args;
+        drawCount++;
+        if (!captured && scene && (scene as { isScene?: boolean }).isScene) {
+          captured = {
+            scene: scene as THREE.Scene,
+            camera: camera as THREE.Camera,
+            renderer: self as unknown as THREE.WebGLRenderer,
+          };
+          for (const resolve of waiters.splice(0)) resolve(captured);
+        }
+        // Forward to the renderer's real render with the original args.
+        return (self[REAL] as (...a: unknown[]) => unknown).apply(self, args);
+      };
+    },
+  });
+
+  // ---- Wave 17 (D-C2): additive composer capture, only when a composer ctor
+  // was passed. `EffectComposer` methods (including `render`) live on the
+  // PROTOTYPE (a plain ES class — the constructor never does `this.render =
+  // …`), so a direct method-wrapper suffices — no getter/setter indirection
+  // like the `render`/`setAnimationLoop` traps above need. ----
+  const composers = new Set<ComposerLike>();
+  let composerProto: Record<string, unknown> | undefined;
+  let priorComposerRender: ((...a: unknown[]) => unknown) | undefined;
+  if (effectComposerCtor) {
+    const EC = effectComposerCtor as EffectComposerCtorLike;
+    composerProto = EC.prototype as unknown as Record<string, unknown>;
+    priorComposerRender = composerProto['render'] as (...a: unknown[]) => unknown;
+    composerProto['render'] = function (this: ComposerLike, ...args: unknown[]) {
+      // Call the real render FIRST: a composer's RenderPass calls
+      // `renderer.render(scene,camera)` internally, which is what actually
+      // sets `captured` (above) on the game's first frame. Checking after
+      // ensures a composer's very first render is still collected.
+      const result = priorComposerRender?.apply(this, args);
+      if (captured && this.renderer === captured.renderer) {
+        composers.add(this);
+      }
+      return result;
+    };
+  }
+
+  // Extracted so `uninstall()`'s own cognitive complexity doesn't grow with
+  // this additive Wave-17 restore step (biome's noExcessiveCognitiveComplexity).
+  function restoreComposerTrap() {
+    if (!composerProto) return;
+    if (priorComposerRender) composerProto['render'] = priorComposerRender;
+    else delete composerProto['render'];
+  }
+
+  return {
+    get captured() {
+      return captured;
+    },
+    getDrawCount() {
+      return drawCount;
+    },
+    getAnimationLoop(renderer: THREE.WebGLRenderer) {
+      return loopCallbacks.get(renderer as unknown as object) ?? null;
+    },
+    resizeComposers(w: number, h: number) {
+      // No composer ctor passed (or none constructed yet) → no-op, and never
+      // touches `renderer.getPixelRatio()` — a non-composer game's captured
+      // renderer need not even expose that method for this to stay a no-op.
+      if (!captured || composers.size === 0) return;
+      const pixelRatio = captured.renderer.getPixelRatio();
+      for (const composer of composers) {
+        composer.setSize(w, h);
+        composer.setPixelRatio(pixelRatio);
+      }
+    },
+    waitForCapture(timeoutMs = 10_000) {
+      if (captured) return Promise.resolve(captured);
+      return new Promise<CapturedRuntime>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          const i = waiters.indexOf(wrapped);
+          if (i >= 0) waiters.splice(i, 1);
+          reject(
+            new Error(
+              `Scene capture timed out after ${timeoutMs}ms — the game never rendered, ` +
+                `or it bundles its own (un-shared) copy of three.`,
+            ),
+          );
+        }, timeoutMs);
+        const wrapped = (rt: CapturedRuntime) => {
+          clearTimeout(timer);
+          resolve(rt);
+        };
+        waiters.push(wrapped);
+      });
+    },
+    uninstall() {
+      // Restore the captured renderer's real render as an OWN property so its
+      // loop keeps working after the prototype trap is removed.
+      if (captured) {
+        const r = captured.renderer as unknown as Record<symbol, unknown>;
+        const real = r[REAL];
+        if (typeof real === 'function') {
+          Object.defineProperty(captured.renderer, 'render', {
+            configurable: true,
+            writable: true,
+            value: real,
+          });
+        }
+      }
+      if (priorDescriptor) {
+        Object.defineProperty(proto, 'render', priorDescriptor);
+      } else {
+        delete proto['render'];
+      }
+      // Restore the captured renderer's real setAnimationLoop as an OWN property (the
+      // prototype getter/setter intercepted the constructor's assignment, so the
+      // instance has none) — else removing the prototype trap would leave it without
+      // setAnimationLoop and freeze its loop.
+      if (captured) {
+        const r = captured.renderer as unknown as Record<symbol, unknown>;
+        const realSal = r[REAL_SAL];
+        if (typeof realSal === 'function') {
+          Object.defineProperty(captured.renderer, 'setAnimationLoop', {
+            configurable: true,
+            writable: true,
+            value: realSal,
+          });
+        }
+      }
+      if (priorSAL) Object.defineProperty(proto, 'setAnimationLoop', priorSAL);
+      else delete proto['setAnimationLoop'];
+      // Wave 17: fully restore the composer addon's `render` (a plain
+      // prototype method — no per-instance own-property to restore, unlike
+      // the renderer/loop traps above).
+      restoreComposerTrap();
+    },
+  };
+}

package/src/adapter/ingest/upstream-pin.ts

@@ -0,0 +1,52 @@
+/**
+ * Upstream-pin extraction — R5 (docs/MASTER-ARCHITECTURE-REVIEW.md §4(c)/
+ * §7.1 item 9): the fix for the overlay identity gap the structural-id +
+ * `authoredAgainst.gameVersion` scheme (T7.7/D9) does not close. A re-vendor
+ * of a vendored upstream game that keeps a slot's shape (index + three.js
+ * type + name unchanged) reapplies a saved overlay onto a semantically
+ * different object with `applied: 1, orphanedIds: []` — silent wrong-meaning
+ * success — because `authoredAgainst.gameVersion` is the MANIFEST's own
+ * `version` (hand-set by whoever wrote `vgai.game.json`, e.g. every
+ * `public/ingest/*` vendored game ships `"version": "0.1.0"` regardless of
+ * which upstream commit it vendors — see `public/ingest/{tanks,racing-game,
+ * simcity}/vgai.game.json`), never tied to the thing that actually changes on
+ * a re-vendor: the `UPSTREAM.md` pin.
+ *
+ * This module is the pure, dependency-free half (parse text -> pin, or
+ * `null`): NO file I/O here, so it is usable from any context (editor
+ * save/apply-time hooks over a fetched `/UPSTREAM.md`, a future Node-side
+ * CLI check, tests). READ-ONLY by construction — it has no writer; this
+ * codebase never generates or edits an `UPSTREAM.md` (the anti-shim rule:
+ * adapters never fabricate first-party data, and a game's own vendoring
+ * provenance is exactly that).
+ *
+ * Format (established convention, not invented here — see every
+ * `public/ingest/*\/UPSTREAM.md`'s `## Upstream` section, e.g.
+ * `public/ingest/tanks/UPSTREAM.md`):
+ *
+ *   ## Upstream
+ *
+ *   - Repo: https://github.com/colyseus/realtime-tanks-demo
+ *   - Commit: **`6339493130b4b1d4d28f0f52d17b2fba738c7d47`**
+ *
+ * i.e. a Markdown bullet whose label is `Commit:` and whose value is a bold,
+ * backtick-code full (or abbreviated) git SHA. Every vendored game in this
+ * repo (`tanks`, `racing-game`, `simcity`) follows this exact shape.
+ */
+
+/** Matches `- Commit: **\`<sha>\`**` (any amount of internal whitespace, case-insensitive hex). */
+const COMMIT_BULLET_RE = /-\s*Commit:\s*\*\*`([0-9a-fA-F]{7,40})`\*\*/;
+
+/**
+ * Extract the pinned upstream commit hash from a vendored game's
+ * `UPSTREAM.md` prose, or `null` if the file doesn't follow the convention
+ * (or wasn't found — the caller decides what a missing file means; this
+ * function only parses text it's handed). Never throws — an unparseable
+ * document is an honest `null`, not an error (anti-shim: no guessing, no
+ * fabricating a pin from a game folder that doesn't declare one, e.g. an
+ * externally-authored non-vendored project opened via the CLI-on-folder
+ * route).
+ */
+export function extractUpstreamPin(markdown: string): string | null {
+  return COMMIT_BULLET_RE.exec(markdown)?.[1] ?? null;
+}

package/src/adapter/loop-gate-report.ts

@@ -0,0 +1,54 @@
+/**
+ * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
+ * play-control contract. `docs/CAPABILITY-TIERS.md` §(d) draws the `loop` axis
+ * (`gated | self-driven`) as independent of capability tier: a `self-driven`
+ * world (an ingested game driving its own rAF/ticker) pauses for real ONLY if
+ * its adapter implements an explicit loop-gate capability
+ * (`MountedWorldBase.setPaused`/`step`) — otherwise it "honestly reports so"
+ * rather than a silent no-op (the D5/COMPOSITION-DESIGN.md §5.2 finding: gating
+ * a raw-rAF loop from outside was demonstrated and REJECTED). The audio seam
+ * (`SystemAdapters.AudioAdapter`) has the identical shape: absent or unable to
+ * silence a world's audio on pause must report, not pretend.
+ *
+ * Pure compute + message-formatting, same split as `achieved-tier.ts`
+ * (`packages/editor/src/achieved-tier.ts`) — callers own the actual
+ * `console.warn`/`editorConsole.warn` call; this module never logs.
+ */
+
+/** Greppable prefix for a loop-gate shortfall (pause requested, world's loop
+ *  could not actually be gated). */
+export const LOOP_GATE_PREFIX = 'loop-gate';
+
+/** Greppable prefix for an audio-gate shortfall (pause requested, world's
+ *  audio could not actually be silenced). */
+export const AUDIO_GATE_PREFIX = 'audio-gate';
+
+/** One shortfall instance: which world, and why the capability wasn't there. */
+export interface CapabilityGateReport {
+  readonly worldId: string;
+  readonly reason: string;
+}
+
+function formatGateMessage(
+  prefix: string,
+  capability: string,
+  report: CapabilityGateReport,
+): string {
+  return (
+    `${prefix} world "${report.worldId}": pause requested but ${capability} cannot be gated ` +
+    `(${report.reason}) — reporting honestly instead of silently no-op-ing ` +
+    `(docs/CAPABILITY-TIERS.md §d). ${prefix} ${JSON.stringify(report)}`
+  );
+}
+
+/** Format a loop-gate shortfall message (a `self-driven` world with no
+ *  working pause capability). */
+export function formatLoopGateMessage(report: CapabilityGateReport): string {
+  return formatGateMessage(LOOP_GATE_PREFIX, "this world's loop", report);
+}
+
+/** Format an audio-gate shortfall message (a world with no `AudioAdapter`, or
+ *  whose adapter cannot actually silence it). */
+export function formatAudioGateMessage(report: CapabilityGateReport): string {
+  return formatGateMessage(AUDIO_GATE_PREFIX, "this world's audio", report);
+}

package/src/adapter/rapier-physics-adapter.ts

@@ -0,0 +1,56 @@
+/**
+ * RapierPhysicsAdapter — the first-party `PhysicsAdapter` over the existing
+ * `PhysicsRegistry` (Object3D ↔ Rapier body/collider). This is the generalized,
+ * behind-the-interface form of the old `setEcsSyncTransform` teleport: it lets
+ * the editor freeze a body, apply a gizmo edit, and resume — without the editor
+ * knowing Rapier exists.
+ */
+
+import type RAPIER from '@dimforge/rapier3d-compat';
+import type * as THREE from 'three';
+import type { PhysicsRegistry } from '../physics/physics-registry';
+import type { PhysicsAdapter } from './system-adapter';
+import type { Transform, TransformOwner } from './transform';
+
+export function createRapierPhysicsAdapter(
+  registry: PhysicsRegistry,
+  debugMesh?: THREE.Object3D | null,
+): PhysicsAdapter {
+  /** Saved body types while frozen, so unfreeze can restore them. */
+  const frozen = new Map<RAPIER.RigidBody, number>();
+
+  return {
+    ownerOf(o: THREE.Object3D): TransformOwner {
+      const body = registry.get(o)?.body;
+      if (!body) return 'editor';
+      // A fixed body never moves on its own → the editor owns its transform.
+      return body.isFixed() ? 'editor' : 'physics';
+    },
+    freeze(o: THREE.Object3D): void {
+      const body = registry.get(o)?.body;
+      if (!body || frozen.has(body)) return;
+      frozen.set(body, body.bodyType());
+      // Kinematic-position: the body stops simulating but tracks the pose we set.
+      body.setBodyType(2 /* KinematicPositionBased */, true);
+    },
+    commit(o: THREE.Object3D, t: Transform): void {
+      const body = registry.get(o)?.body;
+      if (!body) return;
+      body.setTranslation({ x: t.position[0], y: t.position[1], z: t.position[2] }, true);
+      body.setRotation(
+        { x: t.rotation[0], y: t.rotation[1], z: t.rotation[2], w: t.rotation[3] },
+        true,
+      );
+    },
+    unfreeze(o: THREE.Object3D): void {
+      const body = registry.get(o)?.body;
+      if (!body) return;
+      const prev = frozen.get(body);
+      if (prev !== undefined) {
+        body.setBodyType(prev, true);
+        frozen.delete(body);
+      }
+    },
+    debugDraw: () => debugMesh ?? null,
+  };
+}

package/src/adapter/system-adapter.ts

@@ -0,0 +1,154 @@
+/**
+ * System adapters — optional subsystem capability providers hung off a mounted
+ * game (`MountedGame.systems`). Each is a thin capability boundary the editor can
+ * coordinate with WITHOUT owning the implementation. The first-party
+ * implementers wrap Rapier / Colyseus / the InputManager; an external game
+ * supplies its own or none, and the editor degrades per `capabilities`.
+ *
+ * These are introspection/coordination boundaries, NOT re-implementations: e.g.
+ * `NetworkingAdapter` is not a transport, and `PhysicsAdapter` does not replace
+ * Rapier — it lets the editor ask "who owns this object" and "freeze it while I
+ * edit it".
+ */
+
+import type * as THREE from 'three';
+import type { Transform, TransformOwner } from './transform';
+
+/**
+ * Physics coordination so the editor can stably edit an object a simulation
+ * would otherwise overwrite every frame: `freeze → apply → unfreeze`.
+ */
+export interface PhysicsAdapter {
+  /** Returns `'physics'` when a body drives this object, else another owner. */
+  ownerOf(o: THREE.Object3D): TransformOwner;
+  /** Pause the body driving `o` (kinematic / sleep / detach) for editing. */
+  freeze(o: THREE.Object3D): void;
+  /** Teleport the body to the edited pose (so the sim continues from there). */
+  commit(o: THREE.Object3D, t: Transform): void;
+  /** Resume simulation of `o`. */
+  unfreeze(o: THREE.Object3D): void;
+  /** Optional debug-draw object (collider wireframes). */
+  debugDraw?(): THREE.Object3D | null;
+}
+
+export interface NetPeer {
+  id: string;
+  label?: string;
+}
+
+/** The live connection lifecycle, for the editor's network inspector. */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+
+/** Identity of the room the local peer is currently in, or `null` when not connected. */
+export interface RoomInfo {
+  roomId: string;
+  sessionId: string;
+  roomName: string;
+}
+
+/** Lightweight replication counters for the editor's network inspector. */
+export interface ReplicationStats {
+  /** Number of replicated entities currently known (e.g. players + NPCs). */
+  entities: number;
+  /** Approximate inbound replication activity (state changes observed per second). */
+  msgsInPerSec: number;
+  /** Approximate outbound message rate (client → server sends per second). */
+  msgsOutPerSec: number;
+}
+
+export type Unsubscribe = () => void;
+
+/** INTROSPECTION over replication state — NOT a networking transport. */
+export interface NetworkingAdapter {
+  peers(): NetPeer[];
+  networkId(o: THREE.Object3D): string | null;
+  authority(o: THREE.Object3D): 'local' | 'remote' | 'server';
+  /** Remote/server-authoritative objects → inspect-only in the editor. */
+  editable(o: THREE.Object3D): boolean;
+  /** Current connection lifecycle state. */
+  getConnectionState(): ConnectionState;
+  /** The active room's identity, or `null` when not connected to a room. */
+  getRoomInfo(): RoomInfo | null;
+  /** Replication activity snapshot, for a live network inspector panel. */
+  getReplicationStats(): ReplicationStats;
+  /** Subscribe to changes in connection state / room / replication stats. */
+  subscribe(cb: () => void): Unsubscribe;
+}
+
+export interface InputAdapter {
+  poll(): void;
+  /** Current value of every named action (1 = pressed, 0 = not), for inspection. */
+  actions(): Readonly<Record<string, number>>;
+}
+
+/** URL remap so an ingested game's relative asset paths resolve under the host. */
+export interface AssetAdapter {
+  resolve(url: string): string;
+}
+
+/** A snapshot of one object's animation graph (state + parameter values). */
+export interface AnimationGraphInfo {
+  object: THREE.Object3D;
+  state: string;
+  parameters: Record<string, number | boolean>;
+}
+
+/**
+ * Inspect + drive a game's animation graphs (state machines / blend params). The
+ * editor uses this to list animated objects, read their current state, and scrub
+ * parameters — without owning the animation system.
+ */
+export interface AnimationAdapter {
+  graphs(): AnimationGraphInfo[];
+  state(o: THREE.Object3D): string | null;
+  getParameter(o: THREE.Object3D, name: string): number | boolean | undefined;
+  setParameter(o: THREE.Object3D, name: string, value: number | boolean): void;
+}
+
+export interface NavPoint {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/**
+ * Inspect a game's navigation mesh: whether one is built, query a path, and get a
+ * debug overlay. Coordination/introspection only — the editor doesn't own the build.
+ */
+export interface NavigationAdapter {
+  hasNavMesh(): boolean;
+  findPath(start: NavPoint, end: NavPoint): NavPoint[];
+  debugMesh(scene: THREE.Scene): THREE.Object3D | null;
+}
+
+/**
+ * Silence/restore a world's own audio (D10, T7.6) — NOT a mixer/bus API. This
+ * is the seam `Game.play.pause()` calls so a paused world's audio goes quiet
+ * too (`docs/DECISIONS-PENDING.md` §D10: "an audio seam in `SystemAdapters` so
+ * pause can silence game audio (howler et al.) or explicitly report it
+ * cannot"). Absence on a world's `mounted.systems` means exactly that:
+ * `Game.play.pause()` reports it loudly once per world rather than silently
+ * leaving that world's audio playing under a "paused" game.
+ */
+export interface AudioAdapter {
+  /** `true` silences this world's audio; `false` restores it to whatever
+   *  level it was at before silencing (an implementer's own concern — the
+   *  first-party adapter restores its master-gain value, not a hardcoded 1). */
+  setMuted(muted: boolean): void;
+  /** Current muted state, for inspection (editor mute UI, proofs). */
+  isMuted(): boolean;
+}
+
+/**
+ * The set of optional subsystem providers a mounted game may expose. Absence of
+ * a provider means "capability not supported" — the editor degrades gracefully.
+ */
+export interface SystemAdapters {
+  physics?: PhysicsAdapter;
+  networking?: NetworkingAdapter;
+  input?: InputAdapter;
+  assets?: AssetAdapter;
+  animation?: AnimationAdapter;
+  navigation?: NavigationAdapter;
+  audio?: AudioAdapter;
+}

package/src/adapter/transform.ts

@@ -0,0 +1,18 @@
+/**
+ * The neutral transform value used across adapter interfaces. Position + scale
+ * are xyz; rotation is a quaternion (xyzw) — matching `Object3D.quaternion`, so
+ * adapters never have to agree on an Euler convention.
+ */
+export interface Transform {
+  position: [number, number, number];
+  rotation: [number, number, number, number];
+  scale: [number, number, number];
+}
+
+/**
+ * Who currently owns an object's transform — i.e. what writes it each frame.
+ * The editor uses this to decide whether a gizmo edit is durable (`editor`),
+ * needs simulation coordination (`physics`), or is best-effort/inspect-only
+ * (`script`/`network`/`external`).
+ */
+export type TransformOwner = 'editor' | 'physics' | 'animation' | 'script' | 'network' | 'external';