@vgai/engine 0.5.9 → 0.5.11

package/dist/adapter/ingest/game-contract.d.ts

@@ -107,6 +107,12 @@ export interface VgaiGameContract {
  * Read the declared contract, if any. The `contractVersion` gate is the
  * forward-compatibility hinge: a future v2 game on a v1 host is ignored
  * (pre-contract fallbacks apply) rather than half-interpreted.
+ *
+ * `scope` is the REALM to read from, and defaults to this module's own `window`
+ * — correct for a same-realm mount, where the game's modules and the host share
+ * one global. An iframe-hosted game declares on ITS realm's window, so the host
+ * passes `iframe.contentWindow`: the contract is a property of the realm the
+ * game runs in, never of the realm that happens to be asking.
  */
-export declare function readGameContract(): VgaiGameContract | null;
+export declare function readGameContract(scope?: Window | null | undefined): VgaiGameContract | null;
 //# sourceMappingURL=game-contract.d.ts.map

package/dist/adapter/ingest/game-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"game-contract.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/game-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACjC,IAAI,IAAI,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,mFAAmF;IACnF,KAAK,CAAC,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,eAAe,EAAE,CAAC,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,GAAG,IAAI,CAI1D"}
+{"version":3,"file":"game-contract.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/game-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,KAAK,CAAC,IAAI,IAAI,CAAC;IACf,MAAM,CAAC,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACjC,IAAI,IAAI,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,mFAAmF;IACnF,KAAK,CAAC,EAAE,qBAAqB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,eAAe,EAAE,CAAC,CAAC;IACnB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,GAAE,MAAM,GAAG,IAAI,GAAG,SAAyD,GAC/E,gBAAgB,GAAG,IAAI,CAKzB"}

package/dist/adapter/ingest/game-contract.js

@@ -21,9 +21,16 @@
  * Read the declared contract, if any. The `contractVersion` gate is the
  * forward-compatibility hinge: a future v2 game on a v1 host is ignored
  * (pre-contract fallbacks apply) rather than half-interpreted.
+ *
+ * `scope` is the REALM to read from, and defaults to this module's own `window`
+ * — correct for a same-realm mount, where the game's modules and the host share
+ * one global. An iframe-hosted game declares on ITS realm's window, so the host
+ * passes `iframe.contentWindow`: the contract is a property of the realm the
+ * game runs in, never of the realm that happens to be asking.
  */
-export function readGameContract() {
-    const declared = window.vgaiGame;
+export function readGameContract(scope = typeof window === 'undefined' ? null : window) {
+    const declared = scope
+        ?.vgaiGame;
     if (!declared || declared.contractVersion !== 1)
         return null;
     return declared;

package/dist/adapter/setup-three-root-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup-three-root-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/setup-three-root-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAmCrD,OAAO,EAAE,KAAK,mBAAmB,EAA2B,MAAM,4BAA4B,CAAC;AAO/F,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAe,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGpE,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,wEAAwE;IACxE,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,+FAA+F;IAC/F,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACxD,kFAAkF;IAClF,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC;AAeD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAErE;AAED,qBAAa,qBAAsB,YAAW,WAAW;IAE3C,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBACS,MAAM,GAAE,oBAAyB;IAKxD,KAAK,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CA4zBpE"}
+{"version":3,"file":"setup-three-root-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/setup-three-root-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAmCrD,OAAO,EAAE,KAAK,mBAAmB,EAA2B,MAAM,4BAA4B,CAAC;AAO/F,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAe,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM7F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGpE,sFAAsF;AACtF,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,wEAAwE;IACxE,aAAa,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC1C,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,+FAA+F;IAC/F,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACxD,kFAAkF;IAClF,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC;AAeD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAErE;AAED,qBAAa,qBAAsB,YAAW,WAAW;IAE3C,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBACS,MAAM,GAAE,oBAAyB;IAKxD,KAAK,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAu0BpE"}

package/dist/adapter/setup-three-root-adapter.js

@@ -497,7 +497,18 @@ export class SetupThreeRootAdapter {
         // dev session that enabled it at mount keeps it enabled.
         let renderVitals = null;
         const seedRenderVitals = () => {
-            if (!host.game || headless || !devLayersEnabled())
+            // `editorPreview ? true : undefined`: an adapter holding an editor
+            // preview is being authored IN the editor — a dev context by
+            // definition, even when the editor SPA itself is a production build.
+            // The packaged runtime bakes `import.meta.env.DEV = false` into its
+            // prebuilt bundle, which is a fact about how the EDITOR was built, not
+            // about whether this mount is a dev session — found live: a
+            // package-native project's vitals never seeded while its dev menu,
+            // capabilities, and every project-graph dev layer ran fine. The
+            // override argument is dev-layers' own documented seam for exactly
+            // this caller-knows-better case; a standalone/ship mount (no
+            // editorPreview) still resolves purely from the build env.
+            if (!host.game || headless || !devLayersEnabled(editorPreview ? true : undefined))
                 return;
             renderVitals?.dispose();
             host.game.profiler.enabled = true;

package/dist/dev/register-render-vitals.d.ts

@@ -6,10 +6,19 @@
  * through `vgai eval`, and `game.providers()`/`game.commands()` to discover
  * them without being told they exist.
  *
- * Engine-owned and first-party, seeded by the three adapter
- * (`adapter/setup-three-root-adapter.ts`) at the same spot it seeds
- * `systemAdapters.renderDebug` — a game writes nothing to get these, and there
- * is no capability to install. The measurement half is `dev/render-vitals.ts`
+ * 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
+ *    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
+ * onto the same `Game`, and a door wired into only one of them is a door half
+ * the engine's worlds never get (issue #1518 — the R3F half was dark
+ * everywhere, found in the field on a package-native project).
+ * The measurement half is `dev/render-vitals.ts`
  * (derived entirely from profiler frames); the address-book half is
  * `dev/render-census.ts` (pure walks over the live scene). This module is only
  * the wiring between them and the registry.
@@ -27,9 +36,11 @@
  *                        the drawing buffer halves was never fill-bound.
  *
  * ── GATING ──────────────────────────────────────────────────────────────────
- * The caller gates. `setup-three-root-adapter.ts` calls this only under
- * `devLayersEnabled()` (`runtime/dev-layers.ts` — the ONE owner of "is this a
- * dev context"), so a ship build registers nothing and pays nothing.
+ * 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
+ * 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).
  *
  * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
  * OWNER: {@link registerRenderVitals}'s caller. It allocates one

package/dist/dev/register-render-vitals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register-render-vitals.d.ts","sourceRoot":"","sources":["../../src/dev/register-render-vitals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAOxE,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AACtD,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AACrD,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AACzD,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AACrD,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAE/C;0EAC0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACpE,aAAa,IAAI,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1E;AAED,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,kEAAkE;IAClE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC;uEACmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC;IAC/B;uCACmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAChD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,wBAAwB,GAC7B,wBAAwB,GAAG,IAAI,CA2IjC"}
+{"version":3,"file":"register-render-vitals.d.ts","sourceRoot":"","sources":["../../src/dev/register-render-vitals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAOxE,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AACtD,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AACrD,eAAO,MAAM,uBAAuB,oBAAoB,CAAC;AACzD,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AACrD,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAE/C;0EAC0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACpE,aAAa,IAAI,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1E;AAED,MAAM,WAAW,wBAAwB;IACvC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,kEAAkE;IAClE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC;uEACmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC;IAC/B;uCACmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAChD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,wBAAwB,GAC7B,wBAAwB,GAAG,IAAI,CA8JjC"}

package/dist/dev/register-render-vitals.js

@@ -6,10 +6,19 @@
  * through `vgai eval`, and `game.providers()`/`game.commands()` to discover
  * them without being told they exist.
  *
- * Engine-owned and first-party, seeded by the three adapter
- * (`adapter/setup-three-root-adapter.ts`) at the same spot it seeds
- * `systemAdapters.renderDebug` — a game writes nothing to get these, and there
- * is no capability to install. The measurement half is `dev/render-vitals.ts`
+ * 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
+ *    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
+ * onto the same `Game`, and a door wired into only one of them is a door half
+ * the engine's worlds never get (issue #1518 — the R3F half was dark
+ * everywhere, found in the field on a package-native project).
+ * The measurement half is `dev/render-vitals.ts`
  * (derived entirely from profiler frames); the address-book half is
  * `dev/render-census.ts` (pure walks over the live scene). This module is only
  * the wiring between them and the registry.
@@ -27,9 +36,11 @@
  *                        the drawing buffer halves was never fill-bound.
  *
  * ── GATING ──────────────────────────────────────────────────────────────────
- * The caller gates. `setup-three-root-adapter.ts` calls this only under
- * `devLayersEnabled()` (`runtime/dev-layers.ts` — the ONE owner of "is this a
- * dev context"), so a ship build registers nothing and pays nothing.
+ * 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
+ * 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).
  *
  * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
  * OWNER: {@link registerRenderVitals}'s caller. It allocates one
@@ -69,8 +80,24 @@ export function registerRenderVitals(deps) {
     const taken = registry.adapter
         .providers()
         .some((provider) => provider.name === RENDER_VITALS_PROVIDER);
-    if (taken)
+    if (taken) {
+        // Loud, by name. This branch used to return `null` in silence, and a
+        // silent decline is indistinguishable from a door that was never seeded —
+        // which is precisely how issue #1518 stayed a mystery through a field
+        // session: every hypothesis about WHY the door was closed had to be
+        // guessed, because nothing on any path said anything. It costs one line to
+        // make the one legitimate decline explain itself, and the same line names
+        // the mount/teardown OVERLAP case (a re-mount seeding before the outgoing
+        // mount's `strip()` runs), where the second world would otherwise lose the
+        // door and no log would mention it.
+        console.warn(`[render-vitals] world "${worldId}" did not get the ${RENDER_VITALS_PROVIDER} door: ` +
+            'another live world already owns it (the names are fixed, so the first three root to ' +
+            'mount wins). Its draws still fold into the readings — the profiler is game-scoped — ' +
+            'but render.census/families/toggle address the owning root. If this world IS the ' +
+            'current one, the previous mount was torn down AFTER this one seeded and its ' +
+            'strip() took the door with it.');
         return null;
+    }
     const vitals = createRenderVitals(profiler);
     const debug = registry.forRoot(worldId);
     debug.registerStateProvider(RENDER_VITALS_PROVIDER, () => vitals.read());

package/dist/manifest/load.d.ts

@@ -15,6 +15,15 @@ export type ResolvedAdapter = {
     readonly surface: 'three' | 'canvas' | 'dom';
     readonly strategy: IngestStrategy;
     readonly entryHtml: string | undefined;
+    /**
+     * Project-relative ES module declaring `window.vgaiGame` beside a
+     * pristine copy. OPTIONAL rather than required-and-possibly-undefined
+     * (the shape its siblings above use) because it is read by exactly one
+     * mount route: every other construction site of this type — the ingest
+     * routes' own fixtures included — has nothing to say about it, and
+     * requiring the key would only make them all say `undefined`.
+     */
+    readonly contractShim?: string | undefined;
     readonly assets: Record<string, string> | undefined;
     readonly domStubs: string[] | undefined;
     readonly captureTimeoutMs: number | undefined;

package/dist/manifest/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/manifest/load.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/manifest/load.ts"],"names":[],"mappings":"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"}

package/dist/manifest/load.js

@@ -125,6 +125,7 @@ function resolveAdapter(root) {
         surface: adapter.surface,
         strategy: ingest.strategy,
         entryHtml: ingest.entryHtml,
+        contractShim: ingest.contractShim,
         assets: ingest.assets,
         domStubs: ingest.domStubs,
         captureTimeoutMs: ingest.captureTimeoutMs,

package/dist/manifest/schema.d.ts

@@ -45,6 +45,7 @@ export declare const RootAdapterSchema: z.ZodPipe<z.ZodTransform<unknown, unknow
             "opaque-embed": "opaque-embed";
         }>;
         entryHtml: z.ZodOptional<z.ZodString>;
+        contractShim: z.ZodOptional<z.ZodString>;
         assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         domStubs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         captureTimeoutMs: z.ZodOptional<z.ZodNumber>;
@@ -85,6 +86,7 @@ export declare const AdapterRootSchema: z.ZodObject<{
                 "opaque-embed": "opaque-embed";
             }>;
             entryHtml: z.ZodOptional<z.ZodString>;
+            contractShim: z.ZodOptional<z.ZodString>;
             assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             domStubs: z.ZodOptional<z.ZodArray<z.ZodString>>;
             captureTimeoutMs: z.ZodOptional<z.ZodNumber>;
@@ -194,6 +196,7 @@ export declare const GameManifestSchema: z.ZodObject<{
                     "opaque-embed": "opaque-embed";
                 }>;
                 entryHtml: z.ZodOptional<z.ZodString>;
+                contractShim: z.ZodOptional<z.ZodString>;
                 assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
                 domStubs: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 captureTimeoutMs: z.ZodOptional<z.ZodNumber>;

package/dist/manifest/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/manifest/schema.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAMhD,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE,eAAO,MAAM,UAAU;;;;;;;EAOrB,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAsF9C,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAkM3B,CAAC;AACJ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoEnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAkB5D,eAAO,MAAM,eAAe;;;;;EAMzB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,qBAAqB;;;;EAEa,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;kBAqC7B,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA+RyD,CAAC;AAEzF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/manifest/schema.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAMhD,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE,eAAO,MAAM,UAAU;;;;;;;EAOrB,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAsF9C,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmP3B,CAAC;AACJ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoEnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAkB5D,eAAO,MAAM,eAAe;;;;;EAMzB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,qBAAqB;;;;EAEa,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;kBAqC7B,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA+RyD,CAAC;AAEzF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/manifest/schema.js

@@ -151,6 +151,24 @@ export const RootAdapterSchema = z
                 'introspection), for both canvas and three roots. Legal but NOT wired to a ' +
                 'mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` ' +
                 'instead, the wired reachable route).'),
+            contractShim: z
+                .string()
+                .optional()
+                .describe("Project-relative path to a HOST-ADDED ES module that declares this game's " +
+                '`window.vgaiGame` contract (adapter/ingest/game-contract.ts) WITHOUT editing a ' +
+                'vendored byte — the pristine-copy door. The host injects it as a ' +
+                '`<script type="module">` into the assembled iframe document AFTER the game`s own ' +
+                'importmap (moving a module load ahead of an import map invalidates the map) and ' +
+                'BEFORE the game`s entry module, so deferred module scripts run it first. ' +
+                'TIMING CONTRACT, which a shim author must obey: because it runs before the ' +
+                'game`s entry, it MUST assign `window.vgaiGame` SYNCHRONOUSLY at top level — the ' +
+                'host waits for that assignment and fails the mount by name if it never arrives. ' +
+                'Anything that needs the game`s own modules must be LAZY: a dynamic `import()` ' +
+                'INSIDE each verb/provider closure, resolved at call time. Importing a game module ' +
+                'eagerly from the shim would evaluate it ahead of the game`s own entry and reorder ' +
+                'its module side effects. Read by the vendored/self-hosted three route only ' +
+                '(strategy `iframe-reachable` with `entryHtml`); declaring it elsewhere is a ' +
+                'schema error rather than a silently dead field.'),
             assets: z
                 .record(z.string(), z.string())
                 .optional()
@@ -226,6 +244,32 @@ export const RootAdapterSchema = z
         })
             .describe('Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
             'own external folder)')
+            // `contractShim` is injected into the assembled ENTRY DOCUMENT, so
+            // the ONLY route that can read it is the self-hosted one
+            // (`iframe-reachable` + `entryHtml`,
+            // ingest-self-hosted-three-adapter.ts). An `opaque-embed` entry
+            // document is hosted sandboxed with no host wiring, and a `bundleUrl`
+            // mount has no game document at all — under either, a declared shim
+            // would be a silently dead declaration, the exact failure the
+            // dead-field-under-wrong-variant checks below exist to prevent. Its
+            // own `.superRefine` rather than a branch inside the next one: they
+            // check unrelated invariants, and folding them together only made
+            // one function harder to read.
+            .superRefine((ingest, ctx) => {
+            if (ingest.contractShim === undefined ||
+                (ingest.strategy === 'iframe-reachable' && ingest.entryHtml !== undefined)) {
+                return;
+            }
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: '`contractShim` is read ONLY by the self-hosted entry-document route, so it ' +
+                    "requires strategy 'iframe-reachable' together with `entryHtml` (got strategy " +
+                    `"${ingest.strategy}"${ingest.entryHtml === undefined ? ' and no `entryHtml`' : ''}) — ` +
+                    "the host injects the shim module into the GAME'S OWN entry HTML " +
+                    '(ingest-self-hosted-three-adapter.ts), and no other mount has such a document.',
+                path: ['contractShim'],
+            });
+        })
             .superRefine((ingest, ctx) => {
             // The six iframe-reachable-multi fields only make sense for the
             // iframe-reachable-multi mount — reject them under any other

package/dist/world3d-react/r3f-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"r3f-adapter.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAGlF,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGvF,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;uBAEmB;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;iDAG6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CA2W9E"}
+{"version":3,"file":"r3f-adapter.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAMlF,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAYvF,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;uBAEmB;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;iDAG6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAqc9E"}

package/dist/world3d-react/r3f-adapter.js

@@ -20,7 +20,10 @@
  */
 import { advance, createRoot, extend, events as pointerEvents, } from '@react-three/fiber';
 import { createElement } from 'react';
+import { registerRenderVitals } from '../dev/register-render-vitals';
+import { RENDER_SUBMIT_PHASE } from '../dev/render-vitals';
 import { WorldProvider } from '../react/world-state';
+import { devLayersEnabled } from '../runtime/dev-layers';
 import { EngineBridge } from './engine-bridge';
 import { applyWorldRendererConfig } from './renderer-config';
 import { createR3FRootContext } from './world-context';
@@ -279,6 +282,52 @@ export function createR3FAdapter(options) {
             // `RootState` for precisely this reason, so reading it per frame is the
             // supported way to see the live root. It is a plain map read.
             const live = () => state.get();
+            // --- Live render vitals (issue #1504), for an R3F world -----------------
+            // The SAME door the classic adapter seeds
+            // (`../adapter/setup-three-root-adapter.ts`), seeded here for the same
+            // reason: a running game must be able to explain its own frame cost
+            // through the debug registry, with no capability to install and nothing
+            // for a game to write. It has to be seeded in BOTH adapters because they
+            // are two independent mount paths onto the same `Game` — and a TSX/R3F
+            // world is the only shape a scaffolded project's three root has, so a
+            // door wired only into the classic path is a door no scaffolded project
+            // ever gets (issue #1518: `game.state('render.vitals')` answered "no
+            // state provider registered" in the field while every other dev layer of
+            // the same world worked).
+            //
+            // The gate is the same three conditions, minus the one that cannot
+            // arise: `devLayersEnabled()` (`../runtime/dev-layers.ts`, the ONE owner
+            // of "is this a dev context" — a ship build registers nothing and pays
+            // nothing), and a `Game` shell (the readings are folded out of that
+            // game's profiler frames). "Not headless" needs no term here: a headless
+            // mount returned above, before fiber was ever configured.
+            //
+            // Two module instances, one answer: under the packaged editor this
+            // module is served out of the PROJECT's own Vite graph (see
+            // `packages/editor/vite-plugin-react-world-runtime.ts` — the packaged
+            // shell imports `resolveR3FEntryAdapter` through the project-rooted
+            // server precisely so fiber/react/three identity is the project's), so
+            // `import.meta.env.DEV` here is the project server's `true`, not the
+            // prebuilt shell's `false`.
+            //
+            // OWNER of the registration+fold: this mount, ended by `dispose()` below
+            // (the fold) and `runtime.dispose()`'s scoped `strip(id)` (the
+            // registrations) — the same split the classic adapter documents.
+            let renderVitals = null;
+            if (host.game && devLayersEnabled()) {
+                // Same auto-enable as the classic adapter: the readings are folded out
+                // of profiler frames, and the profiler is a flag the editor already
+                // sets on play — under the dev gate this is the same cost arriving a
+                // little earlier, not a new one.
+                host.game.profiler.enabled = true;
+                renderVitals = registerRenderVitals({
+                    registry: runtime.debugRegistry,
+                    worldId: id,
+                    profiler: host.game.profiler,
+                    scene: live().scene,
+                    renderer: host.renderer,
+                });
+            }
             // The engine drives every `useFrame` through the mounted world's
             // `update(dt)` hook, never off a raw host-loop callback. That is the
             // whole pause story: `runFrameImpl` (`runtime/game.ts`) calls
@@ -350,7 +399,44 @@ export function createR3FAdapter(options) {
                     // then fiber's advance (useFrame callbacks + the actual render see
                     // the fresh state). Both are host-gated: neither runs while frozen.
                     systems.run(dt);
-                    advance(elapsed, true, current);
+                    const profiler = host.game?.profiler;
+                    if (!profiler?.enabled) {
+                        advance(elapsed, true, current);
+                        return;
+                    }
+                    // Issue #1504's measurement, produced where the draw actually
+                    // happens. `advance()` under `frameloop: 'never'` is what calls
+                    // `gl.render(scene, camera)`, so this bracket — not a phase span
+                    // inside `systems` — is the frame's CPU submission cost, and it is
+                    // also what makes this frame a PRESENTATION as far as the vitals
+                    // fold is concerned (`../dev/render-vitals.ts`: no bracket, no
+                    // display frame). The profiler's phase clock is a stack, so
+                    // bracketing here cannot truncate an enclosing phase.
+                    const info = host.renderer.info;
+                    const passesBefore = info?.render.frame ?? 0;
+                    profiler.beginPhase();
+                    try {
+                        advance(elapsed, true, current);
+                    }
+                    finally {
+                        profiler.endPhase(RENDER_SUBMIT_PHASE);
+                    }
+                    // Checked, not assumed — a duck-typed/design-time renderer supplies
+                    // only what a mount needs, and a mount with no counters must report
+                    // NOTHING rather than throw once per frame (the classic adapter's
+                    // `postFrame` pays for the same assumption for the same reason).
+                    // `gpuMs` is null: this path runs no GPU timer, and the profiler
+                    // keeps the previous reading rather than inventing a zero.
+                    if (info) {
+                        profiler.reportRender({
+                            gpuMs: null,
+                            drawCalls: info.render.calls,
+                            triangles: info.render.triangles,
+                            geometries: info.memory.geometries,
+                            textures: info.memory.textures,
+                            renderPasses: info.render.frame - passesBefore,
+                        });
+                    }
                 },
                 resize(width, height) {
                     live().setSize(width, height);
@@ -359,6 +445,13 @@ export function createR3FAdapter(options) {
                     // Unmount FIRST so component effect cleanups run, then tear the
                     // runtime down (scoped debug-registry strip).
                     root.unmount();
+                    // The vitals fold owns two `profiler.subscribe` registrations, and
+                    // `runtime.dispose()`'s `strip(id)` removes the REGISTRATIONS only —
+                    // this is the one path that ends the subscriptions, exactly as the
+                    // classic adapter's teardown documents. Before the strip, so a
+                    // subscription can never outlive the door it feeds.
+                    renderVitals?.dispose();
+                    renderVitals = null;
                     runtime.dispose();
                     restoreRendererConfig();
                 },

package/dist/world3d-react/world-context.d.ts

@@ -35,6 +35,7 @@ import type * as THREE from 'three';
 import type { ThreeHostContext } from '../adapter';
 import type { SystemAdapters } from '../adapter/system-adapter';
 import { createSystemRunner } from '../core/system-runner';
+import { type DebugRegistry } from '../runtime/debug-registry';
 import type { GameContext } from '../runtime/types';
 /** The classic adapter's default input-map path — the conventional location
  *  every scaffolded project ships (`public/inputmaps/default.inputmap.json`). */
@@ -99,6 +100,14 @@ export interface R3FRootRuntime {
     /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —
      *  `ctx.registerSystemAdapter` writes into it; `debug` is pre-seeded. */
     readonly systemAdapters: SystemAdapters;
+    /** The registry every registration of this world's lands in — the game's
+     *  own when a `Game` hosts it, a private mount-local one otherwise. Exposed
+     *  (rather than re-derived by the caller) because `createR3FAdapter` seeds
+     *  the render-vitals door onto THIS registry after fiber's first commit
+     *  resolves the scene, and two `getDebugRegistry` calls that are "obviously"
+     *  the same object is exactly the second source of truth the classic
+     *  adapter's single `debugRegistry` local avoids. */
+    readonly debugRegistry: DebugRegistry;
     /** Resolves once the input map load settles (immediately when skipped).
      *  Never rejects — a failed load reports loudly and resolves. */
     readonly inputMapReady: Promise<void>;

package/dist/world3d-react/world-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world-context.d.ts","sourceRoot":"","sources":["../../src/world3d-react/world-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgCK;AAEL,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAQ3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;iFACiF;AACjF,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAC/B,WAAW,EACT,OAAO,GACP,QAAQ,GACR,YAAY,GACZ,OAAO,GACP,QAAQ,GACR,SAAS,GACT,OAAO,GACP,OAAO,GACP,QAAQ,GACR,MAAM,GACN,OAAO,GACP,UAAU,GACV,uBAAuB,CAC1B,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC;gFAC4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED;+EAC+E;AAC/E,MAAM,WAAW,cAAc;IAC7B;6EACyE;IACzE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IACxD;6EACyE;IACzE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;qEACiE;IACjE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;4DAGwD;IACxD,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC/D;;gFAE4E;IAC5E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAqKhB"}
+{"version":3,"file":"world-context.d.ts","sourceRoot":"","sources":["../../src/world3d-react/world-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgCK;AAEL,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;iFACiF;AACjF,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,CAC/B,WAAW,EACT,OAAO,GACP,QAAQ,GACR,YAAY,GACZ,OAAO,GACP,QAAQ,GACR,SAAS,GACT,OAAO,GACP,OAAO,GACP,QAAQ,GACR,MAAM,GACN,OAAO,GACP,UAAU,GACV,uBAAuB,CAC1B,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC;gFAC4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED;+EAC+E;AAC/E,MAAM,WAAW,cAAc;IAC7B;6EACyE;IACzE,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IACxD;6EACyE;IACzE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;;yDAMqD;IACrD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;qEACiE;IACjE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;;;4DAGwD;IACxD,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC/D;;gFAE4E;IAC5E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAsKhB"}

package/dist/world3d-react/world-context.js

@@ -164,6 +164,7 @@ export function createR3FRootContext(host, options) {
         ctx,
         systems,
         systemAdapters,
+        debugRegistry,
         inputMapReady,
         setSceneCamera(scene, camera) {
             const sameScene = ctxRaw['scene'] === scene && sceneIndex !== null;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "description": "Readable TypeScript game engine and universal host for Three.js, PixiJS, and React games.",
   "keywords": [
     "game-engine",

package/schemas/engine-capabilities.json

@@ -15,7 +15,7 @@
       ],
       "notes": "Grepped packages/engine/src for ccd/CCD/setCcdEnabled: zero matches. The engine constructs no rigid bodies itself — games build their own descs via ctx.RAPIER — and nothing engine-side ever enables ccd. Workaround: keep dynamic-body per-step travel small relative to the thinnest collider, or add intermediate colliders; a game may also call setCcdEnabled on its own bodies directly.",
       "evidenceHashes": {
-        "packages/engine/src/adapter/setup-three-root-adapter.ts": "b55b5aa1b032a813ddeaa1dedb6488326ed4cf3497e8cf76a07bada1e40243ea"
+        "packages/engine/src/adapter/setup-three-root-adapter.ts": "f1b599b9fd25dfacd1c155ce83418734c984ac843d7173f573947fceb860cf51"
       }
     },
     {
@@ -73,7 +73,7 @@
       "notes": "Track P shipped 2026-07-03; proven: bubbo-bubbo/puzzling-potions/flappy-pixi. Tiers/limits: ARCHITECTURE-CORE.md.",
       "evidenceHashes": {
         "vendor/games/verify-unaltered.mjs": "df875b09d698b3cfc03443ff3dba4929f5f08ea8913009d4fae253d478282312",
-        "packages/engine/src/manifest/schema.ts": "63d3f6fdbe3e9323ecbd4910c540d8a77e57d95e9044016424b46ca15a5c0bea"
+        "packages/engine/src/manifest/schema.ts": "d689135c4702e09be1de6a66c8625e64be10ca80deb988f30430678fa77b88db"
       }
     },
     {

package/schemas/vgai-project.schema.json

@@ -114,6 +114,10 @@
                         "description": "Entry HTML path, project-relative. WIRED for opaque-embed (D-W2): the file`s bytes are read verbatim through the project-static route and hosted in a sandboxed iframe (embed-only, no scene introspection), for both canvas and three roots. Legal but NOT wired to a mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` instead, the wired reachable route).",
                         "type": "string"
                       },
+                      "contractShim": {
+                        "description": "Project-relative path to a HOST-ADDED ES module that declares this game's `window.vgaiGame` contract (adapter/ingest/game-contract.ts) WITHOUT editing a vendored byte — the pristine-copy door. The host injects it as a `<script type=\"module\">` into the assembled iframe document AFTER the game`s own importmap (moving a module load ahead of an import map invalidates the map) and BEFORE the game`s entry module, so deferred module scripts run it first. TIMING CONTRACT, which a shim author must obey: because it runs before the game`s entry, it MUST assign `window.vgaiGame` SYNCHRONOUSLY at top level — the host waits for that assignment and fails the mount by name if it never arrives. Anything that needs the game`s own modules must be LAZY: a dynamic `import()` INSIDE each verb/provider closure, resolved at call time. Importing a game module eagerly from the shim would evaluate it ahead of the game`s own entry and reorder its module side effects. Read by the vendored/self-hosted three route only (strategy `iframe-reachable` with `entryHtml`); declaring it elsewhere is a schema error rather than a silently dead field.",
+                        "type": "string"
+                      },
                       "assets": {
                         "description": "Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)",
                         "type": "object",

package/src/adapter/ingest/game-contract.ts

@@ -113,9 +113,18 @@ export interface VgaiGameContract {
  * Read the declared contract, if any. The `contractVersion` gate is the
  * forward-compatibility hinge: a future v2 game on a v1 host is ignored
  * (pre-contract fallbacks apply) rather than half-interpreted.
+ *
+ * `scope` is the REALM to read from, and defaults to this module's own `window`
+ * — correct for a same-realm mount, where the game's modules and the host share
+ * one global. An iframe-hosted game declares on ITS realm's window, so the host
+ * passes `iframe.contentWindow`: the contract is a property of the realm the
+ * game runs in, never of the realm that happens to be asking.
  */
-export function readGameContract(): VgaiGameContract | null {
-  const declared = (window as unknown as { vgaiGame?: VgaiGameContract }).vgaiGame;
+export function readGameContract(
+  scope: Window | null | undefined = typeof window === 'undefined' ? null : window,
+): VgaiGameContract | null {
+  const declared = (scope as unknown as { vgaiGame?: VgaiGameContract } | null | undefined)
+    ?.vgaiGame;
   if (!declared || declared.contractVersion !== 1) return null;
   return declared;
 }

package/src/adapter/setup-three-root-adapter.ts

@@ -604,7 +604,18 @@ export class SetupThreeRootAdapter implements RootAdapter {
     // dev session that enabled it at mount keeps it enabled.
     let renderVitals: RenderVitalsRegistration | null = null;
     const seedRenderVitals = (): void => {
-      if (!host.game || headless || !devLayersEnabled()) return;
+      // `editorPreview ? true : undefined`: an adapter holding an editor
+      // preview is being authored IN the editor — a dev context by
+      // definition, even when the editor SPA itself is a production build.
+      // The packaged runtime bakes `import.meta.env.DEV = false` into its
+      // prebuilt bundle, which is a fact about how the EDITOR was built, not
+      // about whether this mount is a dev session — found live: a
+      // package-native project's vitals never seeded while its dev menu,
+      // capabilities, and every project-graph dev layer ran fine. The
+      // override argument is dev-layers' own documented seam for exactly
+      // this caller-knows-better case; a standalone/ship mount (no
+      // editorPreview) still resolves purely from the build env.
+      if (!host.game || headless || !devLayersEnabled(editorPreview ? true : undefined)) return;
       renderVitals?.dispose();
       host.game.profiler.enabled = true;
       renderVitals = registerRenderVitals({

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

@@ -6,10 +6,19 @@
  * through `vgai eval`, and `game.providers()`/`game.commands()` to discover
  * them without being told they exist.
  *
- * Engine-owned and first-party, seeded by the three adapter
- * (`adapter/setup-three-root-adapter.ts`) at the same spot it seeds
- * `systemAdapters.renderDebug` — a game writes nothing to get these, and there
- * is no capability to install. The measurement half is `dev/render-vitals.ts`
+ * 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
+ *    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
+ * onto the same `Game`, and a door wired into only one of them is a door half
+ * the engine's worlds never get (issue #1518 — the R3F half was dark
+ * everywhere, found in the field on a package-native project).
+ * The measurement half is `dev/render-vitals.ts`
  * (derived entirely from profiler frames); the address-book half is
  * `dev/render-census.ts` (pure walks over the live scene). This module is only
  * the wiring between them and the registry.
@@ -27,9 +36,11 @@
  *                        the drawing buffer halves was never fill-bound.
  *
  * ── GATING ──────────────────────────────────────────────────────────────────
- * The caller gates. `setup-three-root-adapter.ts` calls this only under
- * `devLayersEnabled()` (`runtime/dev-layers.ts` — the ONE owner of "is this a
- * dev context"), so a ship build registers nothing and pays nothing.
+ * 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
+ * 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).
  *
  * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
  * OWNER: {@link registerRenderVitals}'s caller. It allocates one
@@ -112,7 +123,26 @@ export function registerRenderVitals(
   const taken = registry.adapter
     .providers()
     .some((provider) => provider.name === RENDER_VITALS_PROVIDER);
-  if (taken) return null;
+  if (taken) {
+    // Loud, by name. This branch used to return `null` in silence, and a
+    // silent decline is indistinguishable from a door that was never seeded —
+    // which is precisely how issue #1518 stayed a mystery through a field
+    // session: every hypothesis about WHY the door was closed had to be
+    // guessed, because nothing on any path said anything. It costs one line to
+    // make the one legitimate decline explain itself, and the same line names
+    // the mount/teardown OVERLAP case (a re-mount seeding before the outgoing
+    // mount's `strip()` runs), where the second world would otherwise lose the
+    // door and no log would mention it.
+    console.warn(
+      `[render-vitals] world "${worldId}" did not get the ${RENDER_VITALS_PROVIDER} door: ` +
+        'another live world already owns it (the names are fixed, so the first three root to ' +
+        'mount wins). Its draws still fold into the readings — the profiler is game-scoped — ' +
+        'but render.census/families/toggle address the owning root. If this world IS the ' +
+        'current one, the previous mount was torn down AFTER this one seeded and its ' +
+        'strip() took the door with it.',
+    );
+    return null;
+  }
 
   const vitals = createRenderVitals(profiler);
   const debug = registry.forRoot(worldId);

package/src/manifest/load.ts

@@ -57,6 +57,15 @@ export type ResolvedAdapter =
       readonly surface: 'three' | 'canvas' | 'dom';
       readonly strategy: IngestStrategy;
       readonly entryHtml: string | undefined;
+      /**
+       * Project-relative ES module declaring `window.vgaiGame` beside a
+       * pristine copy. OPTIONAL rather than required-and-possibly-undefined
+       * (the shape its siblings above use) because it is read by exactly one
+       * mount route: every other construction site of this type — the ingest
+       * routes' own fixtures included — has nothing to say about it, and
+       * requiring the key would only make them all say `undefined`.
+       */
+      readonly contractShim?: string | undefined;
       readonly assets: Record<string, string> | undefined;
       readonly domStubs: string[] | undefined;
       readonly captureTimeoutMs: number | undefined;
@@ -274,6 +283,7 @@ function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
     surface: adapter.surface,
     strategy: ingest.strategy,
     entryHtml: ingest.entryHtml,
+    contractShim: ingest.contractShim,
     assets: ingest.assets,
     domStubs: ingest.domStubs,
     captureTimeoutMs: ingest.captureTimeoutMs,

package/src/manifest/schema.ts

@@ -174,6 +174,26 @@ export const RootAdapterSchema = z
                     'mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` ' +
                     'instead, the wired reachable route).',
                 ),
+              contractShim: z
+                .string()
+                .optional()
+                .describe(
+                  "Project-relative path to a HOST-ADDED ES module that declares this game's " +
+                    '`window.vgaiGame` contract (adapter/ingest/game-contract.ts) WITHOUT editing a ' +
+                    'vendored byte — the pristine-copy door. The host injects it as a ' +
+                    '`<script type="module">` into the assembled iframe document AFTER the game`s own ' +
+                    'importmap (moving a module load ahead of an import map invalidates the map) and ' +
+                    'BEFORE the game`s entry module, so deferred module scripts run it first. ' +
+                    'TIMING CONTRACT, which a shim author must obey: because it runs before the ' +
+                    'game`s entry, it MUST assign `window.vgaiGame` SYNCHRONOUSLY at top level — the ' +
+                    'host waits for that assignment and fails the mount by name if it never arrives. ' +
+                    'Anything that needs the game`s own modules must be LAZY: a dynamic `import()` ' +
+                    'INSIDE each verb/provider closure, resolved at call time. Importing a game module ' +
+                    'eagerly from the shim would evaluate it ahead of the game`s own entry and reorder ' +
+                    'its module side effects. Read by the vendored/self-hosted three route only ' +
+                    '(strategy `iframe-reachable` with `entryHtml`); declaring it elsewhere is a ' +
+                    'schema error rather than a silently dead field.',
+                ),
               assets: z
                 .record(z.string(), z.string())
                 .optional()
@@ -269,6 +289,35 @@ export const RootAdapterSchema = z
               'Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
                 'own external folder)',
             )
+            // `contractShim` is injected into the assembled ENTRY DOCUMENT, so
+            // the ONLY route that can read it is the self-hosted one
+            // (`iframe-reachable` + `entryHtml`,
+            // ingest-self-hosted-three-adapter.ts). An `opaque-embed` entry
+            // document is hosted sandboxed with no host wiring, and a `bundleUrl`
+            // mount has no game document at all — under either, a declared shim
+            // would be a silently dead declaration, the exact failure the
+            // dead-field-under-wrong-variant checks below exist to prevent. Its
+            // own `.superRefine` rather than a branch inside the next one: they
+            // check unrelated invariants, and folding them together only made
+            // one function harder to read.
+            .superRefine((ingest, ctx) => {
+              if (
+                ingest.contractShim === undefined ||
+                (ingest.strategy === 'iframe-reachable' && ingest.entryHtml !== undefined)
+              ) {
+                return;
+              }
+              ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message:
+                  '`contractShim` is read ONLY by the self-hosted entry-document route, so it ' +
+                  "requires strategy 'iframe-reachable' together with `entryHtml` (got strategy " +
+                  `"${ingest.strategy}"${ingest.entryHtml === undefined ? ' and no `entryHtml`' : ''}) — ` +
+                  "the host injects the shim module into the GAME'S OWN entry HTML " +
+                  '(ingest-self-hosted-three-adapter.ts), and no other mount has such a document.',
+                path: ['contractShim'],
+              });
+            })
             .superRefine((ingest, ctx) => {
               // The six iframe-reachable-multi fields only make sense for the
               // iframe-reachable-multi mount — reject them under any other

package/src/world3d-react/r3f-adapter.tsx

@@ -28,11 +28,23 @@ import {
 } from '@react-three/fiber';
 import { createElement, type ReactNode } from 'react';
 import type { MountedThreeRoot, RootAdapter, ThreeHostContext } from '../adapter';
+import { type RenderVitalsRegistration, registerRenderVitals } from '../dev/register-render-vitals';
+import { RENDER_SUBMIT_PHASE } from '../dev/render-vitals';
 import { WorldProvider } from '../react/world-state';
+import { devLayersEnabled } from '../runtime/dev-layers';
 import { EngineBridge, type EngineBridgeValue } from './engine-bridge';
 import { applyWorldRendererConfig, type WorldRendererConfig } from './renderer-config';
 import { createR3FRootContext } from './world-context';
 
+/** The slice of `WebGLRenderer.info` the vitals reporter reads. Declared
+ *  structurally rather than imported from `three`, per this module's own
+ *  identity rule (see the header): a duck-typed host renderer legitimately has
+ *  no `info` at all, which is why every read of it is guarded. */
+interface RendererCounters {
+  readonly render: { readonly calls: number; readonly triangles: number; readonly frame: number };
+  readonly memory: { readonly geometries: number; readonly textures: number };
+}
+
 /** What {@link createR3FAdapter} needs to build one `RootAdapter`. */
 export interface CreateR3FAdapterOptions {
   /** Stable id (telemetry/registry/conformance) — `RootAdapter.id`. */
@@ -336,6 +348,53 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
       // supported way to see the live root. It is a plain map read.
       const live = (): RootState => state.get();
 
+      // --- Live render vitals (issue #1504), for an R3F world -----------------
+      // The SAME door the classic adapter seeds
+      // (`../adapter/setup-three-root-adapter.ts`), seeded here for the same
+      // reason: a running game must be able to explain its own frame cost
+      // through the debug registry, with no capability to install and nothing
+      // for a game to write. It has to be seeded in BOTH adapters because they
+      // are two independent mount paths onto the same `Game` — and a TSX/R3F
+      // world is the only shape a scaffolded project's three root has, so a
+      // door wired only into the classic path is a door no scaffolded project
+      // ever gets (issue #1518: `game.state('render.vitals')` answered "no
+      // state provider registered" in the field while every other dev layer of
+      // the same world worked).
+      //
+      // The gate is the same three conditions, minus the one that cannot
+      // arise: `devLayersEnabled()` (`../runtime/dev-layers.ts`, the ONE owner
+      // of "is this a dev context" — a ship build registers nothing and pays
+      // nothing), and a `Game` shell (the readings are folded out of that
+      // game's profiler frames). "Not headless" needs no term here: a headless
+      // mount returned above, before fiber was ever configured.
+      //
+      // Two module instances, one answer: under the packaged editor this
+      // module is served out of the PROJECT's own Vite graph (see
+      // `packages/editor/vite-plugin-react-world-runtime.ts` — the packaged
+      // shell imports `resolveR3FEntryAdapter` through the project-rooted
+      // server precisely so fiber/react/three identity is the project's), so
+      // `import.meta.env.DEV` here is the project server's `true`, not the
+      // prebuilt shell's `false`.
+      //
+      // OWNER of the registration+fold: this mount, ended by `dispose()` below
+      // (the fold) and `runtime.dispose()`'s scoped `strip(id)` (the
+      // registrations) — the same split the classic adapter documents.
+      let renderVitals: RenderVitalsRegistration | null = null;
+      if (host.game && devLayersEnabled()) {
+        // Same auto-enable as the classic adapter: the readings are folded out
+        // of profiler frames, and the profiler is a flag the editor already
+        // sets on play — under the dev gate this is the same cost arriving a
+        // little earlier, not a new one.
+        host.game.profiler.enabled = true;
+        renderVitals = registerRenderVitals({
+          registry: runtime.debugRegistry,
+          worldId: id,
+          profiler: host.game.profiler,
+          scene: live().scene,
+          renderer: host.renderer,
+        });
+      }
+
       // The engine drives every `useFrame` through the mounted world's
       // `update(dt)` hook, never off a raw host-loop callback. That is the
       // whole pause story: `runFrameImpl` (`runtime/game.ts`) calls
@@ -408,7 +467,43 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           // then fiber's advance (useFrame callbacks + the actual render see
           // the fresh state). Both are host-gated: neither runs while frozen.
           systems.run(dt);
-          advance(elapsed, true, current);
+          const profiler = host.game?.profiler;
+          if (!profiler?.enabled) {
+            advance(elapsed, true, current);
+            return;
+          }
+          // Issue #1504's measurement, produced where the draw actually
+          // happens. `advance()` under `frameloop: 'never'` is what calls
+          // `gl.render(scene, camera)`, so this bracket — not a phase span
+          // inside `systems` — is the frame's CPU submission cost, and it is
+          // also what makes this frame a PRESENTATION as far as the vitals
+          // fold is concerned (`../dev/render-vitals.ts`: no bracket, no
+          // display frame). The profiler's phase clock is a stack, so
+          // bracketing here cannot truncate an enclosing phase.
+          const info = host.renderer.info as RendererCounters | undefined;
+          const passesBefore = info?.render.frame ?? 0;
+          profiler.beginPhase();
+          try {
+            advance(elapsed, true, current);
+          } finally {
+            profiler.endPhase(RENDER_SUBMIT_PHASE);
+          }
+          // Checked, not assumed — a duck-typed/design-time renderer supplies
+          // only what a mount needs, and a mount with no counters must report
+          // NOTHING rather than throw once per frame (the classic adapter's
+          // `postFrame` pays for the same assumption for the same reason).
+          // `gpuMs` is null: this path runs no GPU timer, and the profiler
+          // keeps the previous reading rather than inventing a zero.
+          if (info) {
+            profiler.reportRender({
+              gpuMs: null,
+              drawCalls: info.render.calls,
+              triangles: info.render.triangles,
+              geometries: info.memory.geometries,
+              textures: info.memory.textures,
+              renderPasses: info.render.frame - passesBefore,
+            });
+          }
         },
         resize(width: number, height: number): void {
           live().setSize(width, height);
@@ -417,6 +512,13 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter
           // Unmount FIRST so component effect cleanups run, then tear the
           // runtime down (scoped debug-registry strip).
           root.unmount();
+          // The vitals fold owns two `profiler.subscribe` registrations, and
+          // `runtime.dispose()`'s `strip(id)` removes the REGISTRATIONS only —
+          // this is the one path that ends the subscriptions, exactly as the
+          // classic adapter's teardown documents. Before the strip, so a
+          // subscription can never outlive the door it feeds.
+          renderVitals?.dispose();
+          renderVitals = null;
           runtime.dispose();
           restoreRendererConfig();
         },

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

@@ -132,6 +132,14 @@ export interface R3FRootRuntime {
   /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —
    *  `ctx.registerSystemAdapter` writes into it; `debug` is pre-seeded. */
   readonly systemAdapters: SystemAdapters;
+  /** The registry every registration of this world's lands in — the game's
+   *  own when a `Game` hosts it, a private mount-local one otherwise. Exposed
+   *  (rather than re-derived by the caller) because `createR3FAdapter` seeds
+   *  the render-vitals door onto THIS registry after fiber's first commit
+   *  resolves the scene, and two `getDebugRegistry` calls that are "obviously"
+   *  the same object is exactly the second source of truth the classic
+   *  adapter's single `debugRegistry` local avoids. */
+  readonly debugRegistry: DebugRegistry;
   /** Resolves once the input map load settles (immediately when skipped).
    *  Never rejects — a failed load reports loudly and resolves. */
   readonly inputMapReady: Promise<void>;
@@ -288,6 +296,7 @@ export function createR3FRootContext(
     ctx,
     systems,
     systemAdapters,
+    debugRegistry,
     inputMapReady,
     setSceneCamera(scene, camera): void {
       const sameScene = ctxRaw['scene'] === scene && sceneIndex !== null;