@vgai/engine 0.5.13 → 0.5.14

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

@@ -50,6 +50,11 @@
  */
 
 import type * as THREE from 'three';
+import {
+  startVisibleCaptureWindow,
+  type VisibilityClock,
+  type VisibleCaptureWindow,
+} from './visible-capture-window';
 
 /** A live runtime captured from an external game on its first rendered frame. */
 export interface CapturedRuntime {
@@ -82,6 +87,78 @@ export interface SceneCaptureOptions {
    * so (`packages/editor/src/host-renderers.ts`).
    */
   isHostRenderer?: (renderer: unknown) => boolean;
+  /**
+   * The game's OWN declared world, read from its contract
+   * (`window.vgaiGame` — the host passes a reader, never a cached value, because
+   * the contract is declared by the game's modules and may not exist yet when
+   * the trap installs).
+   *
+   * When it answers non-null, the DECLARATION decides: only a render of that
+   * scene is adopted, and first-render-wins never runs. When it answers null —
+   * the case for every game that declares nothing — behaviour is unchanged and
+   * the adoption is reported as `measured`.
+   */
+  declaredScene?: () => unknown;
+  /**
+   * How the world was adopted, and every DISTINCT world seen afterwards.
+   *
+   * First-non-host-render-wins is a good measured default and a permanent,
+   * SILENT commitment: a splash scene, a shadow pre-pass, or a
+   * render-to-texture warm-up that happens to draw first is adopted as the game
+   * forever, and the real world that renders one frame later reaches no reader
+   * at all. This is that reader. It never changes which world is adopted — it
+   * makes the ambiguity a recorded fact (`packages/editor/src/world-adoption.ts`
+   * publishes it to `vgai status`).
+   *
+   * Post-processing games legitimately render several (scene, camera) pairs per
+   * frame, so alternates are INFORMATION, never an error. Host renders are
+   * excluded by the same `isHostRenderer` declaration the adoption itself uses.
+   */
+  onWorldAdoption?: (event: WorldAdoptionEvent) => void;
+}
+
+/**
+ * One world-adoption fact. `adopted` fires exactly once, when the trap commits
+ * to a (scene, camera, renderer) triple; `alternate` fires for each DISTINCT
+ * triple seen afterwards, up to {@link MAX_RECORDED_ALTERNATES}.
+ */
+export type WorldAdoptionEvent =
+  | {
+      readonly phase: 'adopted';
+      /** `declared` = the contract named this scene; `measured` = first render won. */
+      readonly source: 'declared' | 'measured';
+      readonly sceneId: string;
+      readonly cameraId: string;
+    }
+  | {
+      readonly phase: 'alternate';
+      readonly sceneId: string;
+      readonly cameraId: string;
+      /** `false` ⇒ a SECOND renderer is drawing, which is the stronger signal. */
+      readonly sameRenderer: boolean;
+      /** Draws observed when this alternate first appeared — how far past the
+       *  adoption it is, without a wall clock. */
+      readonly drawCount: number;
+    };
+
+/**
+ * How many distinct alternates are recorded before the trap stops looking.
+ *
+ * The bound is the point: this runs inside the game's own render call, and a
+ * post-processing chain can present a new (scene, camera) pair every frame. A
+ * handful names the ambiguity; an unbounded set would turn a diagnostic into a
+ * leak on the hottest path in the process.
+ */
+export const MAX_RECORDED_ALTERNATES = 8;
+
+/** A three object's identity, as a string a status facet can carry. `type` is
+ *  what a reader recognizes ("Scene", "PerspectiveCamera"); `uuid` is what
+ *  makes two of the same type tellable apart. */
+function objectId(value: unknown): string {
+  const obj = value as { type?: unknown; uuid?: unknown } | null | undefined;
+  const type = typeof obj?.type === 'string' ? obj.type : 'unknown';
+  const uuid = typeof obj?.uuid === 'string' ? obj.uuid : '(no uuid)';
+  return `${type}:${uuid}`;
 }
 
 /**
@@ -104,6 +181,28 @@ export interface RenderPassHooks {
   after(): void;
 }
 
+/**
+ * Options for {@link SceneCaptureHandle.waitForCapture}. Passing a bare number
+ * is the same as `{ timeoutMs }` — the shape every existing caller uses.
+ */
+export interface CaptureWaitOptions {
+  /** The capture window, in VISIBLE milliseconds (default 10s). */
+  timeoutMs?: number | undefined;
+  /** Injected in tests; defaults to the document's own visibility. */
+  visibility?: VisibilityClock | undefined;
+  /**
+   * Called with a LIVE view of the wait when it begins, and with `null` the
+   * moment it ends (captured, expired, or the window was cancelled).
+   *
+   * A wait parked on a hidden tab is otherwise indistinguishable from a hung
+   * mount: nothing renders, nothing fails, and every door reports silence.
+   * This is the seam the editor publishes to `vgai status` so the answer is
+   * "waiting for the first visible frame — the tab is hidden", not a
+   * countdown that is not running.
+   */
+  onWait?: ((wait: VisibleCaptureWindow | null) => void) | undefined;
+}
+
 /** Handle returned by {@link installSceneCapture}. */
 export interface SceneCaptureHandle {
   /** The captured runtime, or null until the game renders its first frame. */
@@ -116,8 +215,17 @@ export interface SceneCaptureHandle {
    * renders come through the same trap and are not the game's frame.
    */
   setRenderPassHooks(hooks: RenderPassHooks | null): void;
-  /** Resolve once a scene+camera is captured (rejects on timeout). */
-  waitForCapture(timeoutMs?: number): Promise<CapturedRuntime>;
+  /**
+   * Resolve once a scene+camera is captured.
+   *
+   * The timeout is a budget of **visible** time, not wall-clock time: a hidden
+   * document cannot render (the browser parks rAF), so counting hidden time
+   * against the game is counting time it was not allowed to use. The wait
+   * therefore PARKS while `document.hidden` and resumes on `visibilitychange`
+   * — see `visible-capture-window.ts` for the whole argument. Rejects only
+   * when the window is spent with the document VISIBLE.
+   */
+  waitForCapture(options?: number | CaptureWaitOptions): 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
@@ -184,6 +292,14 @@ export function installSceneCapture(
 
   let captured: CapturedRuntime | null = null;
   let drawCount = 0;
+  /** Memoized answer of `opts.declaredScene` — asked each render until it
+   *  answers, because a game declares its contract from its own modules and may
+   *  not have run yet when the trap installs. Once it answers, it is fixed:
+   *  a declaration that changes mid-boot is not a thing the host chases. */
+  let declaredScene: unknown = null;
+  /** Distinct alternates already reported, keyed by the same triple identity the
+   *  event carries — see {@link MAX_RECORDED_ALTERNATES} for why it is bounded. */
+  const seenAlternates = new Set<string>();
   /** Set post-capture by the host; see {@link SceneCaptureHandle.setRenderPassHooks}. */
   let renderPassHooks: RenderPassHooks | null = null;
   const waiters: Array<(rt: CapturedRuntime) => void> = [];
@@ -240,6 +356,55 @@ export function installSceneCapture(
     }
   }
 
+  /**
+   * Commit to a world, DECLARATION FIRST.
+   *
+   * First-non-host-render-wins is the measured default and a permanent one, so
+   * a game that states which scene is its world is not made to race its own
+   * splash screen. `declaredScene` is asked until it answers (the game's own
+   * modules declare the contract, and may not have run when the trap installed);
+   * once it does, only that scene is adopted.
+   */
+  function adoptWorld(self: unknown, scene: unknown, camera: unknown): void {
+    if (declaredScene === null) declaredScene = opts?.declaredScene?.() ?? null;
+    if (declaredScene !== null && declaredScene !== scene) return;
+    captured = {
+      scene: scene as THREE.Scene,
+      camera: camera as THREE.Camera,
+      renderer: self as THREE.WebGLRenderer,
+    };
+    opts?.onWorldAdoption?.({
+      phase: 'adopted',
+      source: declaredScene === null ? 'measured' : 'declared',
+      sceneId: objectId(scene),
+      cameraId: objectId(camera),
+    });
+    for (const resolve of waiters.splice(0)) resolve(captured);
+  }
+
+  /**
+   * A DISTINCT world drew after the adopted one. Recorded, never acted on:
+   * which world is adopted does not change (that would break every handle the
+   * host already built from it) — but the reader stops being the only party who
+   * could have noticed. Deduped and bounded because this is the game's own
+   * render call.
+   */
+  function recordAlternateWorld(self: unknown, scene: unknown, camera: unknown): void {
+    if (!captured || seenAlternates.size >= MAX_RECORDED_ALTERNATES) return;
+    if (scene === captured.scene && camera === captured.camera) return;
+    const sameRenderer = self === captured.renderer;
+    const key = `${objectId(scene)}|${objectId(camera)}|${sameRenderer}`;
+    if (seenAlternates.has(key)) return;
+    seenAlternates.add(key);
+    opts?.onWorldAdoption?.({
+      phase: 'alternate',
+      sceneId: objectId(scene),
+      cameraId: objectId(camera),
+      sameRenderer,
+      drawCount,
+    });
+  }
+
   Object.defineProperty(proto, 'render', {
     configurable: true,
     set(this: Record<symbol, unknown>, fn: unknown) {
@@ -269,14 +434,9 @@ export function installSceneCapture(
         // Whether that happened at all came down to whether the editor
         // rendered a frame inside the game's capture window, so the same
         // session could pass or fail on timing alone.
-        const isHostRender = opts?.isHostRenderer?.(self) === true;
-        if (!captured && !isHostRender && 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);
+        if (opts?.isHostRenderer?.(self) !== true && (scene as { isScene?: boolean })?.isScene) {
+          if (captured) recordAlternateWorld(self, scene, camera);
+          else adoptWorld(self, scene, camera);
         }
         return forwardRender(self, args);
       };
@@ -340,24 +500,41 @@ export function installSceneCapture(
         composer.setPixelRatio(pixelRatio);
       }
     },
-    waitForCapture(timeoutMs = 10_000) {
+    waitForCapture(options) {
+      const opts: CaptureWaitOptions =
+        typeof options === 'number' ? { timeoutMs: options } : (options ?? {});
+      const timeoutMs = opts.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);
+        // A budget of VISIBLE time. The window disarms itself while the
+        // document is hidden and resumes when it comes back, so a tab that
+        // boots in the background waits instead of dying — and the trap it is
+        // waiting on stays installed the whole time, which is what makes the
+        // first frame after foregrounding a capture rather than a retry.
+        const captureWindow = startVisibleCaptureWindow({
+          budgetMs: timeoutMs,
+          ...(opts.visibility !== undefined ? { clock: opts.visibility } : {}),
+          onExpire: () => {
+            const i = waiters.indexOf(wrapped);
+            if (i >= 0) waiters.splice(i, 1);
+            opts.onWait?.(null);
+            reject(
+              new Error(
+                `Scene capture timed out after ${timeoutMs}ms of VISIBLE time ` +
+                  `(${Math.round(captureWindow.elapsedHiddenMs())}ms hidden, which is not counted — ` +
+                  'a hidden tab cannot render) — the game never rendered, ' +
+                  'or it bundles its own (un-shared) copy of three.',
+              ),
+            );
+          },
+        });
         const wrapped = (rt: CapturedRuntime) => {
-          clearTimeout(timer);
+          captureWindow.cancel();
+          opts.onWait?.(null);
           resolve(rt);
         };
         waiters.push(wrapped);
+        opts.onWait?.(captureWindow);
       });
     },
     uninstall() {

package/src/adapter/ingest/structural-ids.ts

@@ -3,14 +3,14 @@
  * reflection helper that rides along with it) the editor's live-three authoring
  * adapter uses to address the objects of a world whose source carries no
  * serve-time identity stamps
- * (`packages/editor/src/authoring/live-three-identity.ts`, `structuralIdentity`).
+ * (`packages/editor/src/projection/three.ts`, `structuralIdentity`).
  *
  * Identity: each object gets a **structural-path id** — deterministic from the
  * scene's shape (position in the tree + three.js type + name), so the SAME id
  * re-binds to the SAME object after the game rebuilds its scene within a
- * session. It is also written to `userData.entityId` so the editor's object map
- * / gizmo / selection (which key on `entityId`) bind to foreign objects with no
- * further shim.
+ * session. The pure walk returns that identity beside the native objects; the
+ * editor keeps the reverse lookup in its authoring adapter rather than writing
+ * editor currency into a foreign graph.
  *
  * This module used to be the shared core of a per-game JSON sidecar
  * persistence system, which was deleted outright (2026-08-02) — ingest edits
@@ -36,7 +36,7 @@ const EDITOR_ONLY_LAYER_MASK = 1 << 31;
 
 /**
  * Editor furniture, not game content. Excluded from the walk entirely — see
- * {@link assignStructuralIds} for why that exclusion is what makes the id
+ * {@link collectStructuralIds} for why that exclusion is what makes the id
  * scheme's central promise true.
  */
 function isEditorOnly(o: THREE.Object3D): boolean {
@@ -67,7 +67,7 @@ export interface StructuralIdWalk {
 }
 
 /**
- * (Re)assign structural-path ids to every object under `scene` (and, if
+ * (Re)collect structural-path ids for every object under `scene` (and, if
  * given, the separately-captured render `camera`, under the fixed
  * {@link CAMERA_ID}). Idempotent and deterministic from scene structure
  * (position + type + name) — so a re-walk after the game rebuilds part of its
@@ -89,7 +89,7 @@ export interface StructuralIdWalk {
  * hierarchy/inspector projections built on this walk, where they were
  * selectable and colorable as if they were game content.
  */
-export function assignStructuralIds(
+export function collectStructuralIds(
   scene: THREE.Object3D,
   camera?: THREE.Object3D | undefined,
 ): StructuralIdWalk {
@@ -102,7 +102,6 @@ export function assignStructuralIds(
     path: string,
   ): void => {
     const id = `ingest:${path}:${o.type}:${o.name || ''}`;
-    setUserData(o, 'entityId', id);
     byId.set(id, o);
     count++;
     if (o.isLight) lights++;
@@ -119,9 +118,22 @@ export function assignStructuralIds(
   };
   visitChildren(scene, '');
   if (camera) {
-    setUserData(camera, 'entityId', CAMERA_ID);
     byId.set(CAMERA_ID, camera);
     count++;
   }
   return { byId, count, meshes, lights };
 }
+
+/**
+ * Compatibility entry point for first-party callers that explicitly want
+ * structural ids stamped into their own graph. Foreign ingest authoring uses
+ * {@link collectStructuralIds} and never calls this mutating form.
+ */
+export function assignStructuralIds(
+  scene: THREE.Object3D,
+  camera?: THREE.Object3D | undefined,
+): StructuralIdWalk {
+  const walk = collectStructuralIds(scene, camera);
+  for (const [id, object] of walk.byId) setUserData(object, 'entityId', id);
+  return walk;
+}

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

@@ -27,8 +27,10 @@
  *   - 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.
+ * backtick-code full (or abbreviated) git SHA. Every BUNDLE-vendored game in
+ * this repo (`tanks`, `simcity`) follows this exact shape. Source-tree
+ * vendored games carry their pin in `vendor/games/<id>.UPSTREAM.lock`'s
+ * machine-readable `commit` instead and never reach this parser.
  */
 
 /** Matches `- Commit: **\`<sha>\`**` (any amount of internal whitespace, case-insensitive hex). */

package/src/adapter/ingest/visible-capture-window.ts

@@ -0,0 +1,213 @@
+/**
+ * The capture window is a budget of VISIBLE time, not of wall-clock time.
+ *
+ * WHY THIS MODULE EXISTS. An ingest mount waits for the game to render its
+ * first frame and fails by name when that never happens
+ * (`scene-capture.ts`'s `waitForCapture`). That wait used to be a plain
+ * `setTimeout`, i.e. a wall-clock deadline started AT BOOT — and a game cannot
+ * render while its tab is hidden, because the browser parks `requestAnimation
+ * Frame` for a backgrounded document. The two facts together make one
+ * deterministic failure: a tab that opens in the BACKGROUND (the normal human
+ * path — `vgai edit` auto-opens a tab that routinely lands behind the current
+ * window) burns its whole capture window unable to draw, the deadline fires,
+ * the mount dies terminally, and foregrounding the tab later changes nothing.
+ * Agents, whose tabs happen to be visible, never saw it.
+ *
+ * So the clock only runs while the document is VISIBLE. Hidden time is not
+ * spent, and while a tab is hidden the wait PARKS rather than expiring: the
+ * capture trap stays installed, the game's modules stay live, and the first
+ * frame the tab draws after the human brings it forward is trapped exactly as
+ * it would have been at boot. That is the retry — no second mount, no
+ * re-running `load()` (which would re-construct module-level state: the
+ * ARCHITECTURE-CORE "LOADING CONSTRUCTS, once" contract), and no forcing of a
+ * frame: the game's own loop resumes on its own when the browser un-parks it.
+ *
+ * There is deliberately no wall-clock cap on the parked state. An unspent
+ * budget is not a failure — a human returning to the tab is what spends it —
+ * and a cap would be exactly the boot-time clock this module exists to
+ * remove. The parked wait is reported instead of being silent: see
+ * `CaptureWaitObserver` in `scene-capture.ts` and `vgai status`'s
+ * `ingestCaptureWait`.
+ *
+ * The state machine is a pure function of (banked segments, now, hidden) so
+ * the whole accrual rule is testable with no browser and no timers
+ * (`packages/engine/test/visible-capture-window.test.ts`); the runtime half
+ * below is only the timer arm/disarm around it.
+ */
+
+/**
+ * Everything the budget reads about the outside world. Injected so the pure
+ * core stays pure and the runtime half is drivable by a fake in tests — and,
+ * as a side effect, so this module never hard-depends on `document` existing
+ * (unit runners, SSR).
+ */
+export interface VisibilityClock {
+  /** Milliseconds, monotonic-ish; `performance.now()`/`Date.now()` both fit. */
+  now(): number;
+  /** True while the document is hidden (no rAF, so no frame can be captured). */
+  hidden(): boolean;
+  /** Subscribe to visibility transitions; returns the unsubscribe. */
+  subscribe(onChange: () => void): () => void;
+}
+
+/** The real one: `document.visibilityState` + `visibilitychange`. Falls back
+ *  to permanently-visible where there is no `document` at all, which is the
+ *  honest answer for a headless caller — it has no tab to background. */
+export function documentVisibilityClock(): VisibilityClock {
+  const doc = typeof document === 'undefined' ? null : document;
+  return {
+    now: () => (typeof performance === 'undefined' ? Date.now() : performance.now()),
+    hidden: () => doc?.hidden === true,
+    subscribe(onChange) {
+      if (!doc) return () => {};
+      doc.addEventListener('visibilitychange', onChange);
+      return () => doc.removeEventListener('visibilitychange', onChange);
+    },
+  };
+}
+
+/**
+ * The banked halves of the wait plus the segment currently running. Immutable:
+ * every transition returns a new value, so a caller can hold one and compare.
+ */
+export interface VisibleBudgetState {
+  /** The window, in VISIBLE milliseconds. */
+  readonly budgetMs: number;
+  /** Visible time banked from completed segments. */
+  readonly visibleMs: number;
+  /** Hidden time banked from completed segments (reported, never spent). */
+  readonly hiddenMs: number;
+  /** When the current segment started. */
+  readonly since: number;
+  /** Whether the current segment is a hidden one. */
+  readonly hidden: boolean;
+}
+
+/** Open the window at `now`, in whichever visibility the document is in. */
+export function beginVisibleBudget(
+  budgetMs: number,
+  now: number,
+  hidden: boolean,
+): VisibleBudgetState {
+  return { budgetMs, visibleMs: 0, hiddenMs: 0, since: now, hidden };
+}
+
+/**
+ * Apply the document's current visibility at `now`: bank the segment that just
+ * ended into its own bucket and start the next one. A call that does not change
+ * visibility is a no-op *by value* (same accrual, same segment start), so a
+ * duplicate `visibilitychange` can never bank a zero-length segment twice or
+ * restart the clock.
+ */
+export function applyVisibility(
+  state: VisibleBudgetState,
+  now: number,
+  hidden: boolean,
+): VisibleBudgetState {
+  if (hidden === state.hidden) return state;
+  const elapsed = Math.max(0, now - state.since);
+  return {
+    budgetMs: state.budgetMs,
+    visibleMs: state.hidden ? state.visibleMs : state.visibleMs + elapsed,
+    hiddenMs: state.hidden ? state.hiddenMs + elapsed : state.hiddenMs,
+    since: now,
+    hidden,
+  };
+}
+
+/** Visible time spent so far, including the segment in flight. */
+export function visibleElapsedMs(state: VisibleBudgetState, now: number): number {
+  return state.visibleMs + (state.hidden ? 0 : Math.max(0, now - state.since));
+}
+
+/** Hidden time so far, including the segment in flight. Never spent — it is
+ *  reported so a failure message can say what the window did NOT count. */
+export function hiddenElapsedMs(state: VisibleBudgetState, now: number): number {
+  return state.hiddenMs + (state.hidden ? Math.max(0, now - state.since) : 0);
+}
+
+/** Visible time left in the window; `0` once it is spent. */
+export function visibleRemainingMs(state: VisibleBudgetState, now: number): number {
+  return Math.max(0, state.budgetMs - visibleElapsedMs(state, now));
+}
+
+/** A live view of one running window, for the status wire and the failure message. */
+export interface VisibleCaptureWindow {
+  /** The window's size, in visible milliseconds. */
+  readonly budgetMs: number;
+  /** Visible milliseconds spent so far. */
+  elapsedVisibleMs(): number;
+  /** Milliseconds this window has spent parked while hidden (not counted). */
+  elapsedHiddenMs(): number;
+  /** Whether the wait is parked right now because the document is hidden. */
+  isHidden(): boolean;
+  /** Stop the timer and drop the visibility listener. Idempotent. */
+  cancel(): void;
+}
+
+/**
+ * Start a window that calls `onExpire` after `budgetMs` of VISIBLE time.
+ * While the document is hidden the timer is disarmed entirely (so a throttled
+ * background timer cannot fire it late either) and re-armed with the remaining
+ * budget when the document comes back.
+ */
+export function startVisibleCaptureWindow(opts: {
+  budgetMs: number;
+  onExpire: () => void;
+  /** Defaults to the document's own visibility. */
+  clock?: VisibilityClock;
+  /** Defaults to `setTimeout`/`clearTimeout`. */
+  setTimer?: (fn: () => void, ms: number) => unknown;
+  clearTimer?: (handle: unknown) => void;
+}): VisibleCaptureWindow {
+  const clock = opts.clock ?? documentVisibilityClock();
+  const setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));
+
+  let state = beginVisibleBudget(opts.budgetMs, clock.now(), clock.hidden());
+  let timer: unknown = null;
+  let done = false;
+
+  function disarm(): void {
+    if (timer !== null) {
+      clearTimer(timer);
+      timer = null;
+    }
+  }
+
+  function arm(): void {
+    disarm();
+    if (done || state.hidden) return;
+    timer = setTimer(
+      () => {
+        timer = null;
+        if (done) return;
+        done = true;
+        unsubscribe();
+        opts.onExpire();
+      },
+      visibleRemainingMs(state, clock.now()),
+    );
+  }
+
+  const unsubscribe = clock.subscribe(() => {
+    if (done) return;
+    state = applyVisibility(state, clock.now(), clock.hidden());
+    arm();
+  });
+
+  arm();
+
+  return {
+    budgetMs: opts.budgetMs,
+    elapsedVisibleMs: () => visibleElapsedMs(state, clock.now()),
+    elapsedHiddenMs: () => hiddenElapsedMs(state, clock.now()),
+    isHidden: () => state.hidden,
+    cancel() {
+      if (done) return;
+      done = true;
+      disarm();
+      unsubscribe();
+    },
+  };
+}

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

@@ -1,7 +1,7 @@
 /**
  * Capability-gate shortfall reporting (D10, T7.6) — the honesty half of the
- * play-control contract. §(d) draws the `loop` axis (`gated | self-driven`) as
- * independent of capability tier: a `self-driven` world (an ingested game
+ * play-control contract. §(d) draws the `loop` axis (`gated | self-driven`) on
+ * its own: 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 (`MountedRootBase.setPaused`/`step`) —
  * otherwise it "honestly reports so" rather than a silent no-op (the
@@ -10,8 +10,7 @@
  * 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
+ * Pure compute + message-formatting — callers own the actual
  * `console.warn`/`editorConsole.warn` call; this module never logs.
  */
 

package/src/adapter/root-adapter.ts

@@ -25,6 +25,7 @@
 
 import type { Container } from 'pixi.js';
 import type * as THREE from 'three';
+import type { WorldRendererConfig } from '../world3d-react/renderer-config';
 import type { AdapterSurface } from './adapter-surface';
 import type { AuthoringAdapter } from './authoring';
 import type { HostContextFor } from './host-context';
@@ -78,8 +79,8 @@ export interface MountedRootBase {
    *    not a promise: implement `setPaused`/`step` only where the game exposes
    *    a sanctioned pause/step mechanism. Gating a raw-rAF loop from outside
    *    was demonstrated and REJECTED (D5 — it halts the loop rather than
-   *    pausing it); such games are the "composited, unsynchronized" tier:
-   *    `setPaused` absent, host degrades loudly (T7.6 owns the tier surface).
+   *    pausing it). Where `setPaused` is absent the host reports the
+   *    shortfall loudly, naming the mechanism that would close it (T7.6).
    */
   readonly drivesOwnLoop: boolean;
 
@@ -112,6 +113,25 @@ export interface MountedThreeRoot extends MountedRootBase {
   /** The live scene + camera the editor inspects/renders for authoring. */
   readonly scene: THREE.Scene;
   readonly camera: THREE.Camera;
+  /**
+   * The colour pipeline this world was authored for, REPORTED rather than
+   * applied — the adapter has already applied it to the renderer its own host
+   * handed it (`world3d-react/renderer-config.ts`).
+   *
+   * It is here because the host that MOUNTS a world is not always the host
+   * that DRAWS it. The editor's design session mounts against a
+   * non-rasterizing renderer on purpose and then draws the mounted scene with
+   * the editor viewport's own `WebGLRenderer`, so the world's declaration
+   * lands on a surface with no pixels while the surface with pixels never
+   * hears it. Reporting the declaration is what lets that host apply the same
+   * config, through the same `applyWorldRendererConfig`, to the renderer that
+   * actually produces the frame.
+   *
+   * Absent means the world declared nothing and the drawing host should leave
+   * its own configuration alone — the same "absent = don't touch" rule the
+   * config's own fields follow.
+   */
+  readonly rendererConfig?: WorldRendererConfig | undefined;
 }
 
 /** A live, mounted canvas world (T7.3) — the pixi analog of