@vgai/engine 0.5.8 → 0.5.10

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

@@ -0,0 +1,35 @@
+/**
+ * Projects a game's DECLARED system surface (`window.vgaiGame.systems`, see
+ * `game-contract.ts`) onto the host's existing {@link DebugAdapter} — the one
+ * seam `game.commands()` / `game.state()` / `game.providers()` already read
+ * through for first-party content (`command-listener.ts`'s
+ * `dispatchBridgeMethod` → `getActiveSystems().debug`).
+ *
+ * Why a projection rather than a second door: an agent driving an ingested
+ * game must not have to learn a parallel vocabulary. A first-party game
+ * registers verbs with `ctx.debug.registerCommand`; an ingested game declares
+ * them in its entry shim. Both arrive at the SAME `DebugAdapter`, so every
+ * consumer downstream — the CLI's `vgai eval`, `@vgai/e2e`'s `GameClient`, the
+ * editor's Debug Console and State Watch panels — works unchanged and unaware
+ * of the provenance.
+ *
+ * What this deliberately does NOT do:
+ * - **Validate arguments.** The first-party path validates against a declared
+ *   Zod tuple; a shim beside a foreign game is plain JS and has none. A verb
+ *   validates itself and throws its own error, which surfaces wrapped as
+ *   `DEBUG_COMMAND_FAILED` — the host never invents a schema to check against.
+ * - **Fabricate an event ring.** There is no tick loop behind an ingested
+ *   game's declarations, so `events()` is empty. That is accurate (nothing was
+ *   emitted), not a stub standing in for a missing feature.
+ */
+import type { DebugAdapter } from '../system-adapter';
+import type { VgaiGameSystems } from './game-contract';
+/**
+ * Build a {@link DebugAdapter} over a declared system surface, or `null` when
+ * the game declared no verbs and no state. `null` is the honest floor: the
+ * bridge then reports `DEBUG_ADAPTER_UNAVAILABLE` exactly as it did before,
+ * rather than serving an empty adapter that reads as "this game has no state"
+ * when the truth is "this game declared nothing".
+ */
+export declare function createContractDebugAdapter(systems: VgaiGameSystems | undefined | null): DebugAdapter | null;
+//# sourceMappingURL=contract-debug-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contract-debug-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapter/ingest/contract-debug-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAsC,MAAM,mBAAmB,CAAC;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,GAC1C,YAAY,GAAG,IAAI,CAuErB"}

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

@@ -0,0 +1,90 @@
+/**
+ * Projects a game's DECLARED system surface (`window.vgaiGame.systems`, see
+ * `game-contract.ts`) onto the host's existing {@link DebugAdapter} — the one
+ * seam `game.commands()` / `game.state()` / `game.providers()` already read
+ * through for first-party content (`command-listener.ts`'s
+ * `dispatchBridgeMethod` → `getActiveSystems().debug`).
+ *
+ * Why a projection rather than a second door: an agent driving an ingested
+ * game must not have to learn a parallel vocabulary. A first-party game
+ * registers verbs with `ctx.debug.registerCommand`; an ingested game declares
+ * them in its entry shim. Both arrive at the SAME `DebugAdapter`, so every
+ * consumer downstream — the CLI's `vgai eval`, `@vgai/e2e`'s `GameClient`, the
+ * editor's Debug Console and State Watch panels — works unchanged and unaware
+ * of the provenance.
+ *
+ * What this deliberately does NOT do:
+ * - **Validate arguments.** The first-party path validates against a declared
+ *   Zod tuple; a shim beside a foreign game is plain JS and has none. A verb
+ *   validates itself and throws its own error, which surfaces wrapped as
+ *   `DEBUG_COMMAND_FAILED` — the host never invents a schema to check against.
+ * - **Fabricate an event ring.** There is no tick loop behind an ingested
+ *   game's declarations, so `events()` is empty. That is accurate (nothing was
+ *   emitted), not a stub standing in for a missing feature.
+ */
+import { DebugError } from '../../runtime/debug-registry';
+/**
+ * Build a {@link DebugAdapter} over a declared system surface, or `null` when
+ * the game declared no verbs and no state. `null` is the honest floor: the
+ * bridge then reports `DEBUG_ADAPTER_UNAVAILABLE` exactly as it did before,
+ * rather than serving an empty adapter that reads as "this game has no state"
+ * when the truth is "this game declared nothing".
+ */
+export function createContractDebugAdapter(systems) {
+    const commandList = systems?.commands ?? [];
+    const providerList = systems?.state ?? [];
+    if (commandList.length === 0 && providerList.length === 0)
+        return null;
+    // Snapshot into name-keyed maps once. A later duplicate shadows an earlier
+    // one and the listing de-duplicates with it, so `commands()` can never
+    // advertise a name `invoke()` would resolve differently.
+    const byCommand = new Map(commandList.map((c) => [c.name, c]));
+    const byProvider = new Map(providerList.map((p) => [p.name, p]));
+    return {
+        providers: () => [...byProvider.values()].map((p) => ({ name: p.name, tier: p.tier ?? 'observable' })),
+        state: (name) => {
+            const provider = byProvider.get(name);
+            if (!provider) {
+                throw new DebugError('STATE_PROVIDER_NOT_FOUND', `No state provider named "${name}" is declared by this game.`, { registered: [...byProvider.keys()] });
+            }
+            return provider.read();
+        },
+        stateAll: () => {
+            const out = {};
+            for (const [name, provider] of byProvider) {
+                // One throwing provider must not cost the caller every other reading —
+                // the same per-key isolation the first-party registry gives.
+                try {
+                    out[name] = provider.read();
+                }
+                catch (err) {
+                    out[name] = { __error: String(err) };
+                }
+            }
+            return out;
+        },
+        commands: () => [...byCommand.values()].map((c) => ({
+            name: c.name,
+            description: c.description,
+            argsJsonSchema: c.argsJsonSchema,
+            // An ingested game runs entirely in the browser realm the host mounted
+            // it in; there is no server leg for its verbs to route to.
+            locus: 'client',
+        })),
+        invoke: async (name, args) => {
+            const command = byCommand.get(name);
+            if (!command) {
+                throw new DebugError('DEBUG_COMMAND_NOT_REGISTERED', `No command named "${name}" is declared by this game.`, { registered: [...byCommand.keys()] });
+            }
+            try {
+                return await command.run(...args);
+            }
+            catch (err) {
+                throw new DebugError('DEBUG_COMMAND_FAILED', `Command "${name}" threw: ${String(err)}`, {
+                    name,
+                });
+            }
+        },
+        events: () => [],
+    };
+}

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

@@ -15,7 +15,7 @@
  * endpoint by endpoint: capture infers what it can (the scene), the game
  * declares what inference can't reach (its DOM root, its session lifecycle).
  *
- * Origin (root), F17+F21 (lifecycle).
+ * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems).
  */
 /**
  * Session lifecycle endpoints. Declaring `start` means "I support cold
@@ -32,6 +32,59 @@ export interface VgaiGameLifecycle {
     pause?(): void;
     resume?(): void;
 }
+/**
+ * One invokable verb the game exposes. Deliberately the SAME listing shape a
+ * first-party game gets from `ctx.debug.registerCommand`
+ * (`DebugCommandInfo`/`DebugAdapter.invoke` in `adapter/system-adapter.ts`) —
+ * an ingested game's verbs must enumerate through `game.commands()` and run
+ * through `game.command(...)` with no second vocabulary for agents to learn.
+ *
+ * `run` receives the positional argument list exactly as invoked. There is no
+ * host-side validation: the contract is plain JS declared beside a foreign
+ * game, so it cannot carry a Zod tuple the way `registerCommand` does.
+ * `argsJsonSchema` is therefore DOCUMENTATION for listing surfaces, not a
+ * gate — a verb validates its own arguments and throws its own errors.
+ */
+export interface VgaiGameCommand {
+    name: string;
+    description?: string;
+    /** JSON-Schema projection of the argument list, when the game declares one. */
+    argsJsonSchema?: unknown;
+    run(...args: unknown[]): unknown | Promise<unknown>;
+}
+/**
+ * One named, JSON-serializable state read — the `ctx.debug.registerStateProvider`
+ * shape. `tier` carries the same meaning as the first-party one: `observable`
+ * is a value the game already computes, `assisted` is one the shim derives.
+ */
+export interface VgaiGameStateProvider {
+    name: string;
+    tier?: 'observable' | 'assisted';
+    read(): unknown;
+}
+/**
+ * The game's SYSTEM surface: what its content actually IS, as opposed to how
+ * it renders. An ingested game's content is not always its scene graph — in a
+ * system-driven game the authorable content lives in the game's own model and
+ * is reached through the game's own verbs, which `root`/`lifecycle` could not
+ * express.
+ *
+ * Both members are read by exactly one consumer,
+ * `adapter/ingest/contract-debug-adapter.ts`, which projects them onto the
+ * host's ordinary `DebugAdapter` (`adapter/system-adapter.ts`) — so
+ * `game.commands()`/`game.state()` reach an ingested game through the same
+ * bridge first-party content uses, with no second vocabulary for agents to
+ * learn. That is deliberate scope: this
+ * interface describes what a foreign game's entry shim may declare, so every
+ * member here is a promise the host must already keep. A member nothing reads
+ * would be a shim author implementing a hook that is never called.
+ */
+export interface VgaiGameSystems {
+    /** Verbs, enumerated by `game.commands()` and run by `game.command(...)`. */
+    commands?: VgaiGameCommand[];
+    /** State reads, enumerated by `game.providers()` and read by `game.state(...)`. */
+    state?: VgaiGameStateProvider[];
+}
 export interface VgaiGameContract {
     /** Bump only on breaking shape changes; additive endpoints keep version 1. */
     contractVersion: 1;
@@ -43,6 +96,12 @@ export interface VgaiGameContract {
      */
     root?: HTMLElement;
     lifecycle?: VgaiGameLifecycle;
+    /**
+     * The game's own systems. Absent means "this game declared no system
+     * surface" — every dependent editor surface then shows a named absence, not
+     * an empty pretend-palette.
+     */
+    systems?: VgaiGameSystems;
 }
 /**
  * Read the declared contract, if any. The `contractVersion` gate is the

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,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;CAC/B;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;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,GAAG,IAAI,CAI1D"}

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

@@ -15,7 +15,7 @@
  * endpoint by endpoint: capture infers what it can (the scene), the game
  * declares what inference can't reach (its DOM root, its session lifecycle).
  *
- * Origin (root), F17+F21 (lifecycle).
+ * Origin (root), F17+F21 (lifecycle), WO-SYS1 (systems).
  */
 /**
  * Read the declared contract, if any. The `contractVersion` gate is the

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;AAiCrD,OAAO,EAAE,KAAK,mBAAmB,EAA2B,MAAM,4BAA4B,CAAC;AAM/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;CAmuBpE"}
+{"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

@@ -26,8 +26,10 @@ import { createSeededRandom, DEFAULT_SEEDED_RANDOM_SEED, getSeededRandom, } from
 import { createSimClock, getSimClock } from '../core/sim-clock';
 import { createSystemRunner } from '../core/system-runner';
 import { createDebugDraw } from '../dev/debug-draw';
+import { registerRenderVitals } from '../dev/register-render-vitals';
 import { createRenderDebugAdapter, frameCaptureContextFor, } from '../dev/render-debug-adapter';
 import { collectRenderMemory } from '../dev/render-memory';
+import { RENDER_SUBMIT_PHASE } from '../dev/render-vitals';
 import { createWebGLFrameCapture } from '../dev/webgl-frame-capture';
 import { createWebGLGpuTimer } from '../dev/webgl-gpu-timer';
 import { createSceneIndex } from '../ecs/scene-index';
@@ -41,6 +43,7 @@ import { updateSceneLODs } from '../render/lod';
 import { disposeSparkRendererWhenIdle, SPARK_DISCOVERY_INTERVAL_MS, sceneHasGaussianSplat, shouldDiscoverGaussianSplat, } from '../render/spark-renderer-lifecycle';
 import { ViewportShadingRenderer } from '../render/viewport-shading';
 import { createDebugRegistry, getDebugRegistry, } from '../runtime/debug-registry';
+import { devLayersEnabled } from '../runtime/dev-layers';
 import { disposeDebrisSubtree } from '../runtime/game';
 import { setupAudio } from '../setup/setup-audio';
 import { setupParticles } from '../setup/setup-particles';
@@ -150,6 +153,10 @@ export class SetupThreeRootAdapter {
             : null;
         const viewportShading = new ViewportShadingRenderer();
         let viewportShadingMode = 'solid';
+        /** Top-level `renderer.render()` calls the last presentation cost — written
+         *  by the render system, read by `postFrame`. See both for why the count is
+         *  latched rather than differenced at report time. */
+        let lastPresentationPasses = 0;
         // --- System runner (engine-level systems) ---
         const systems = createSystemRunner(host.game?.profiler.systemObserver, 'three');
         // D15/T-D15.3/.5: pass the LIVE shared game tick (not a locally-counted
@@ -201,7 +208,8 @@ export class SetupThreeRootAdapter {
         }, { name: 'materials-and-particles' });
         if (!headless) {
             systems.add('render', (dt) => {
-                if (host.game?.profiler.enabled)
+                const profiler = host.game?.profiler;
+                if (profiler?.enabled)
                     gpuTimer?.begin();
                 if (sparkRenderer)
                     scene.add(sparkRenderer);
@@ -211,6 +219,21 @@ export class SetupThreeRootAdapter {
                 // patched context — in the SAME finally as gpuTimer.end(). Spark is
                 // added before this so its draws fall inside the captured frame.
                 renderDebugWiring?.beforeRender();
+                // Issue #1504: CPU render submission, bracketed as its OWN profiler
+                // phase nested inside the frame's enclosing `render` phase. This is
+                // the frame's only isolated measurement of "how long did it take to
+                // hand the draws to the driver" — the `render` phase around it also
+                // contains physics-debug redraw and every other world's render work,
+                // and a system span would key the reading to this adapter's system
+                // NAME. The profiler's phase clock is a stack precisely so this
+                // bracket cannot truncate its parent (`dev/performance-profiler.ts`).
+                // It is also what makes a frame a PRESENTATION as far as the vitals
+                // fold is concerned: no draw, no bracket, no display frame.
+                profiler?.beginPhase();
+                // `info.render.frame` counts top-level renderer.render() calls and
+                // survives `info.reset()`, so its delta across the draw is how many
+                // passes the composer chain (plus shadows) actually cost.
+                const passesBefore = renderer.info.render.frame;
                 try {
                     viewportShading.render(scene, viewportShadingMode, () => composer.render(dt), 
                     // Scene authoring can temporarily attach editor infrastructure
@@ -219,6 +242,8 @@ export class SetupThreeRootAdapter {
                     (mesh) => camera.layers.test(mesh.layers));
                 }
                 finally {
+                    profiler?.endPhase(RENDER_SUBMIT_PHASE);
+                    lastPresentationPasses = renderer.info.render.frame - passesBefore;
                     renderDebugWiring?.afterRender();
                     sparkRenderer?.removeFromParent();
                     gpuTimer?.end();
@@ -239,13 +264,25 @@ export class SetupThreeRootAdapter {
         const postFrame = () => {
             if (ownsInput)
                 input.endFrame();
-            if (host.game?.profiler.enabled) {
+            // `renderer.info` is checked, not assumed: a headless/stub renderer
+            // supplies only what the runtime needs to mount, and a mount with no
+            // counters must report NOTHING rather than throw once per frame. This
+            // used to be unreachable because only the editor ever enabled the
+            // profiler; the engine enables it itself under the dev gate now (see the
+            // render-vitals seed below), so the assumption has to be paid for.
+            if (host.game?.profiler.enabled && renderer.info) {
                 host.game.profiler.reportRender({
                     gpuMs: gpuTimer?.poll() ?? null,
                     drawCalls: renderer.info.render.calls,
                     triangles: renderer.info.render.triangles,
                     geometries: renderer.info.memory.geometries,
                     textures: renderer.info.memory.textures,
+                    // The LAST presentation's pass count, not a delta taken here: under
+                    // the display-rate loop this hook runs once per fixed SUBSTEP, so a
+                    // delta measured at this point would read as 0 on every substep that
+                    // did not draw. Same one-frame-warm semantics as the renderer.info
+                    // counters beside it.
+                    renderPasses: lastPresentationPasses,
                 });
             }
         };
@@ -431,6 +468,59 @@ export class SetupThreeRootAdapter {
         ctx.random =
             (host.game ? getSeededRandom(host.game) : null) ??
                 createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED);
+        // --- Live render vitals (issue #1504) -------------------------------------
+        // Engine-owned and first-party, seeded HERE like `renderDebug` above: 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.
+        //
+        // THE GATE, in one place. Three conditions, and the reason for each:
+        //  1. `devLayersEnabled()` — the ONE owner of "is this a dev/editor
+        //     context" (`runtime/dev-layers.ts`). A ship build registers nothing,
+        //     subscribes to nothing, and never enables the profiler.
+        //  2. a `Game` shell exists — the readings are folded out of that game's
+        //     profiler frames, and a bare mount has no profiler to fold.
+        //  3. not headless — a headless mount registers no render system at all,
+        //     so it never brackets a submission and never presents a frame. Its
+        //     vitals could only ever read empty, and registering a door that is
+        //     structurally incapable of answering is worse than not having one.
+        //
+        // The enabled-gating question, resolved: the profiler is AUTO-ENABLED here
+        // rather than given a second, cheaper always-on counter tier. A counter
+        // tier would be a parallel measurement path — exactly the side ledger this
+        // work exists to avoid — and the profiler already has the one property
+        // that made the choice: `enabled` is a plain flag whose cost is per-frame
+        // bookkeeping the editor ALREADY pays (it sets `profiler.enabled = true`
+        // on play, `CenterDocuments.tsx`), so under the dev gate this is not a new
+        // cost, it is the same cost arriving a little earlier. Nothing here ever
+        // turns it OFF: the profiler's other owners (the Performance panel,
+        // `render-control.ts`'s perfSample) save and restore the prior state, so a
+        // dev session that enabled it at mount keeps it enabled.
+        let renderVitals = null;
+        const seedRenderVitals = () => {
+            // `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({
+                registry: debugRegistry,
+                worldId: this.id,
+                profiler: host.game.profiler,
+                scene,
+                renderer,
+            });
+        };
+        seedRenderVitals();
         // Snapshot of the engine-owned adapter kinds, taken right after seeding
         // and before any setup() has had a chance to run. `hotReload`/`disposeGame`
         // use this to strip every GAME-registered kind (including an override of a
@@ -623,6 +713,13 @@ export class SetupThreeRootAdapter {
             // roots remain alive during root replacement. A bare standalone adapter
             // owns the registry and can clear it globally.
             safeStep('debugRegistry.strip', () => host.game ? debugRegistry.strip(this.id) : debugRegistry.strip());
+            // The strip above removes the vitals REGISTRATIONS (their provenance is
+            // this world). This ends the fold's profiler subscription — the one
+            // resource `registerRenderVitals` allocates that a strip cannot reach.
+            safeStep('renderVitals.dispose', () => {
+                renderVitals?.dispose();
+                renderVitals = null;
+            });
             // Release analyser taps BEFORE the audio teardown below. A consumer
             // (the editor's meter poll) should dispose its own handle, but Stop must
             // never leak taps regardless.
@@ -735,6 +832,12 @@ export class SetupThreeRootAdapter {
             // every react-door registration (whose `useEffect` cleanup never
             // re-fires to restore them after someone else's strip).
             safeStep('debugRegistry.strip', () => debugRegistry.strip(this.id));
+            // The strip above takes the ENGINE's own vitals registrations with it
+            // (they carry this world's provenance, which is what makes the game's
+            // own re-seed silent). Re-seed them before the incoming setup runs, so a
+            // warm restart does not silently cost a game its render vitals — and so
+            // the fold starts clean rather than carrying the outgoing game's frames.
+            safeStep('renderVitals re-seed', seedRenderVitals);
             currentCleanup = await newSetup(ctx, newEditorPreview);
         };
         return {

package/dist/dev/performance-profiler.d.ts

@@ -33,6 +33,15 @@ export interface PerformanceRenderStats {
     readonly triangles: number;
     readonly geometries: number;
     readonly textures: number;
+    /**
+     * How many top-level `renderer.render()` submissions the last presentation
+     * took (`renderer.info.render.frame`'s delta across one draw) — a composer
+     * chain, a shadow pass and a post stack each cost one. `null` (never a
+     * fabricated 0, same rule as `gpuMs`) when no reporter counted them: a
+     * reporter that omits `renderPasses` is saying it does not know, which is
+     * different from saying nothing was drawn.
+     */
+    readonly renderPasses: number | null;
 }
 export interface PerformanceFrame {
     readonly id: number;
@@ -71,13 +80,7 @@ export interface PerformanceSnapshot {
     readonly phases: readonly PerformanceTiming[];
     readonly systems: readonly PerformanceTiming[];
     readonly components: readonly PerformanceTiming[];
-    readonly render: {
-        readonly gpuMs: number | null;
-        readonly drawCalls: number;
-        readonly triangles: number;
-        readonly geometries: number;
-        readonly textures: number;
-    };
+    readonly render: PerformanceRenderStats;
 }
 /** Game-owned, bounded external store for browser-native performance diagnostics. */
 export declare function createPerformanceProfiler(initiallyEnabled?: boolean): {
@@ -101,6 +104,9 @@ export declare function createPerformanceProfiler(initiallyEnabled?: boolean): {
         triangles: number;
         geometries: number;
         textures: number;
+        /** Omit when this reporter does not count passes — see
+         *  {@link PerformanceRenderStats.renderPasses}. */
+        renderPasses?: number;
     }): void;
     endFrame(): void;
     subscribe(listener: () => void): () => void;

package/dist/dev/performance-profiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"performance-profiler.d.ts","sourceRoot":"","sources":["../../src/dev/performance-profiler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"performance-profiler.d.ts","sourceRoot":"","sources":["../../src/dev/performance-profiler.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;CACzC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;CACzC;AAUD,qFAAqF;AACrF,wBAAgB,yBAAyB,CAAC,gBAAgB,UAAQ;aA8E3C,OAAO;;;;;;;mBA8CX,MAAM;;;yBAqBF,MAAM,SAAS,MAAM,QAAQ,MAAM;;;uBAiBnC,MAAM;wBAWL;QAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB;2DACmD;QACnD,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB;;wBAqCmB,MAAM,IAAI;;;EAejC;AAED,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/dev/performance-profiler.js

@@ -23,7 +23,18 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
     let frameId = 0;
     let frameStart = 0;
     let lastFrameStart = 0;
-    let phaseStart = 0;
+    /**
+     * Phase start times, innermost last. A STACK rather than the single slot
+     * this used to be, because phases NEST: the three adapter brackets its CPU
+     * render submission as its own phase (`render.submit`,
+     * `dev/render-vitals.ts`) from inside the frame's enclosing `render` phase.
+     * With one slot the inner `beginPhase()` overwrote the outer's start, so the
+     * outer `endPhase('render')` measured only the tail after the inner phase —
+     * silently under-reporting the very phase the inner one was decomposing.
+     * Balanced callers are unaffected; `endPhase` with an empty stack falls back
+     * to `frameStart` rather than a stale start from a previous frame.
+     */
+    const phaseStack = [];
     let systemStart = 0;
     let componentStart = 0;
     let render = {
@@ -32,6 +43,7 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
         triangles: 0,
         geometries: 0,
         textures: 0,
+        renderPasses: null,
     };
     let snapshot = {
         enabled,
@@ -102,17 +114,30 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
             currentComponents.clear();
             frameSystems = [];
             frameComponents = [];
-            render = { gpuMs: null, drawCalls: 0, triangles: 0, geometries: 0, textures: 0 };
+            // A frame that threw mid-phase leaves entries on the stack; a fresh
+            // frame starts from nothing rather than inheriting them.
+            phaseStack.length = 0;
+            render = {
+                gpuMs: null,
+                drawCalls: 0,
+                triangles: 0,
+                geometries: 0,
+                textures: 0,
+                renderPasses: null,
+            };
             frameStart = now();
         },
         beginPhase() {
             if (!enabled)
                 return;
-            phaseStart = now();
+            phaseStack.push(now());
         },
         endPhase(name) {
             if (!enabled)
                 return;
+            // See `phaseStack`: pop restores the ENCLOSING phase's own start, so a
+            // nested bracket measures itself without truncating its parent.
+            const phaseStart = phaseStack.pop() ?? frameStart;
             const elapsed = now() - phaseStart;
             const existing = currentPhases.get(name);
             // Accumulate ms across re-entries of the same phase, but keep the FIRST
@@ -170,6 +195,9 @@ export function createPerformanceProfiler(initiallyEnabled = false) {
                 triangles: render.triangles + stats.triangles,
                 geometries: render.geometries + stats.geometries,
                 textures: render.textures + stats.textures,
+                renderPasses: stats.renderPasses === undefined
+                    ? render.renderPasses
+                    : (render.renderPasses ?? 0) + stats.renderPasses,
             };
         },
         endFrame() {

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

@@ -0,0 +1,95 @@
+/**
+ * THE DOOR for live render vitals: one provider and four commands on the
+ * game's own debug registry (`runtime/debug-registry.ts`), so a running game
+ * explains its own frame cost through the SAME seam every other reading and
+ * verb uses — `game.state('render.vitals')` / `game.command('render.census')`
+ * 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`
+ * (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.
+ *
+ * ── THE READING AND THE EXPERIMENTS ─────────────────────────────────────────
+ * A number alone does not route an investigation, so each command is the
+ * experiment that turns one reading into an address:
+ *  - `render.census`   — which subtree owns the meshes and triangles, with a
+ *                        drill-down argument;
+ *  - `render.families` — which meshes are identical enough to instance;
+ *  - `render.toggle`   — hide a subtree and watch the stat move (the only way
+ *                        to ATTRIBUTE cost rather than infer it);
+ *  - `render.dpr`      — change the pixel count, which separates GPU fill cost
+ *                        from vsync idle: render CPU that does not move when
+ *                        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.
+ *
+ * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
+ * OWNER: {@link registerRenderVitals}'s caller. It allocates one
+ * {@link RenderVitals} fold (which owns one `profiler.subscribe`), a SECOND,
+ * self-ending `profiler.subscribe` for the static-batch advisory, and the
+ * registrations, whose provenance is the caller's `worldId`. SHARERS: none.
+ * TEARDOWN: the returned `dispose()` — the ONE path that ends both
+ * subscriptions. The REGISTRATIONS are ended by the registry's own
+ * `strip(worldId)`, which the adapter already runs on stop and warm restart;
+ * this module never strips, because a blind strip here would take the game's
+ * registrations with it.
+ */
+import * as THREE from 'three';
+import type { DebugRegistry } from '../runtime/debug-registry';
+import type { PerformanceProfiler } from './performance-profiler';
+import { type RenderVitals } from './render-vitals';
+/** The one provider name — spelled here, referenced everywhere else. */
+export declare const RENDER_VITALS_PROVIDER = "render.vitals";
+export declare const RENDER_CENSUS_COMMAND = "render.census";
+export declare const RENDER_FAMILIES_COMMAND = "render.families";
+export declare const RENDER_TOGGLE_COMMAND = "render.toggle";
+export declare const RENDER_DPR_COMMAND = "render.dpr";
+/** The slice of `THREE.WebGLRenderer` `render.dpr` actuates. Narrow on
+ *  purpose: a headless mount has no renderer at all and passes `null`. */
+export interface RenderVitalsRenderer {
+    getSize(target: THREE.Vector2): THREE.Vector2;
+    setPixelRatio(value: number): void;
+    setSize(width: number, height: number, updateStyle?: boolean): void;
+    getPixelRatio(): number;
+    readonly domElement: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+export interface RenderVitalsRegistration {
+    /** The live fold, exposed so a test can drive it without a registry. */
+    readonly vitals: RenderVitals;
+    /** See the ownership note — the ONE teardown path. Idempotent. */
+    dispose(): void;
+}
+export interface RegisterRenderVitalsDeps {
+    readonly registry: DebugRegistry;
+    /** Registration provenance — the mount's adapter id, so the adapter's own
+     *  `strip(worldId)` on stop/warm-restart removes exactly these. */
+    readonly worldId: string;
+    readonly profiler: PerformanceProfiler;
+    /** The live scene the census walks. */
+    readonly scene: THREE.Object3D;
+    /** `null` under a headless mount — `render.dpr` then refuses by name rather
+     *  than silently doing nothing. */
+    readonly renderer: RenderVitalsRenderer | null;
+}
+/**
+ * Seed the vitals door for one world. Returns `null` when another live world
+ * already owns the door: the names are fixed and discoverable on purpose, and
+ * the registry (correctly) throws on a cross-world name collision, so the
+ * FIRST three root to mount owns them. A second three root's draws still show
+ * up in the readings — the profiler is game-scoped, so every world's
+ * submission folds into the same frame — but the census commands address the
+ * owning root's scene.
+ */
+export declare function registerRenderVitals(deps: RegisterRenderVitalsDeps): RenderVitalsRegistration | null;
+//# sourceMappingURL=register-render-vitals.d.ts.map

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

@@ -0,0 +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"}