@volter/editor-game 0.5.66 → 0.5.68

package/src/runtime/dev/performance-profiler.ts

@@ -0,0 +1,367 @@
+export interface PerformanceTiming {
+  readonly name: string;
+  readonly ms: number;
+  /**
+   * Offset (ms) from THIS frame's start (`frameStart`) at which the timing
+   * began — a MEASURED value (e.g. a phase's `phaseStart - frameStart`), never
+   * synthesized. Present on per-frame phase timings (W4b, so a Chrome trace
+   * can place each phase span under its frame at the real offset). OMITTED on
+   * cross-frame aggregate rollups (`PerformanceSnapshot.phases`/`systems`/
+   * `components`), where no single start point exists — absent, never a
+   * fabricated 0.
+   */
+  readonly startMs?: number;
+}
+
+/**
+ * One MEASURED span within a frame (W4b) — a system or component invocation,
+ * with the phase it ran in and its measured start offset from `frameStart`.
+ * Distinct from {@link PerformanceTiming}: a span is a single timed
+ * invocation carrying `phase` + always-present `startMs` (the trace/flame
+ * unit), whereas a `PerformanceTiming` may be a cross-frame rollup.
+ */
+export interface PerformanceSpan {
+  readonly name: string;
+  readonly phase: string;
+  /** Measured offset (ms) from `frameStart` at which this span began. */
+  readonly startMs: number;
+  readonly ms: number;
+}
+
+/** Renderer counters accumulated over a frame (from `renderer.info`). */
+export interface PerformanceRenderStats {
+  readonly gpuMs: number | null;
+  readonly drawCalls: number;
+  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;
+  readonly timestamp: number;
+  readonly intervalMs: number;
+  readonly cpuMs: number;
+  readonly phases: readonly PerformanceTiming[];
+  /**
+   * Per-invocation system spans measured this frame (W4b). Ordered by
+   * `startMs` (execution order), NOT accumulated — a system that ran twice
+   * (two substeps) appears twice. Empty when the profiler saw no named
+   * systems this frame.
+   */
+  readonly systems: readonly PerformanceSpan[];
+  /**
+   * Per-invocation component spans measured this frame (W4b) — populated ONLY
+   * while `recording` (component timing is gated on recording, matching
+   * `beginComponent`/`endComponent`). Empty otherwise.
+   */
+  readonly components: readonly PerformanceSpan[];
+  /**
+   * Renderer counters reported during this frame (W4b) — a snapshot of the
+   * accumulated `reportRender` totals taken at `endFrame`. `gpuMs` is `null`
+   * when no GPU timer reported (headless/SwiftShader), never a fabricated 0.
+   */
+  readonly render: PerformanceRenderStats;
+}
+
+export interface PerformanceSnapshot {
+  readonly enabled: boolean;
+  readonly recording: boolean;
+  readonly fps: number;
+  readonly cpuMs: number;
+  readonly p95Ms: number;
+  readonly p99Ms: number;
+  readonly frames: readonly PerformanceFrame[];
+  readonly phases: readonly PerformanceTiming[];
+  readonly systems: readonly PerformanceTiming[];
+  readonly components: readonly PerformanceTiming[];
+  readonly render: PerformanceRenderStats;
+}
+
+const now = () => globalThis.performance?.now() ?? Date.now();
+
+function percentile(sorted: readonly number[], fraction: number): number {
+  if (sorted.length === 0) return 0;
+  return sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * fraction))] ?? 0;
+}
+
+/** Game-owned, bounded external store for browser-native performance diagnostics. */
+export function createPerformanceProfiler(initiallyEnabled = false) {
+  const listeners = new Set<() => void>();
+  const frames: PerformanceFrame[] = [];
+  const currentPhases = new Map<string, { ms: number; startMs: number }>();
+  const currentSystems = new Map<string, number>();
+  const currentComponents = new Map<string, number>();
+  // Per-frame span logs (W4b) — cleared each beginFrame, snapshotted into the
+  // frame at endFrame. Distinct from the accumulate-by-name aggregate maps
+  // above (which back the cross-frame snapshot rollups): these preserve every
+  // individual invocation and its measured start offset, for the trace.
+  let frameSystems: PerformanceSpan[] = [];
+  let frameComponents: PerformanceSpan[] = [];
+  let enabled = initiallyEnabled;
+  // The header's always-visible FPS sparkline needs frame INTERVALS without
+  // turning on the full profiler. Full profiling measures phases/systems,
+  // issues GPU timer queries at render sites, and intentionally warns about
+  // overhead; a glanceable heartbeat must not silently opt the user into all
+  // of that work. `telemetryEnabled` records only the frame envelope.
+  let telemetryEnabled = false;
+  let recording = false;
+  let frameId = 0;
+  let frameStart = 0;
+  let lastFrameStart = 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: number[] = [];
+  let systemStart = 0;
+  let componentStart = 0;
+  let render: PerformanceRenderStats = {
+    gpuMs: null,
+    drawCalls: 0,
+    triangles: 0,
+    geometries: 0,
+    textures: 0,
+    renderPasses: null,
+  };
+  let snapshot: PerformanceSnapshot = {
+    enabled,
+    recording,
+    fps: 0,
+    cpuMs: 0,
+    p95Ms: 0,
+    p99Ms: 0,
+    frames: [],
+    phases: [],
+    systems: [],
+    components: [],
+    render,
+  };
+
+  function publish(): void {
+    const latest = frames.at(-1);
+    // Frame-only subscribers need no percentile work. Keep this window stable
+    // so a retained snapshot's first percentile read still describes its frames.
+    const snapshotFrames = frames.slice();
+    let sortedIntervals: number[] | undefined;
+    const readPercentile = (fraction: number): number => {
+      sortedIntervals ??= snapshotFrames
+        .map((frame) => frame.intervalMs)
+        .filter((value) => value > 0)
+        .sort((a, b) => a - b);
+      return percentile(sortedIntervals, fraction);
+    };
+    snapshot = {
+      enabled,
+      recording,
+      fps: latest?.intervalMs ? 1000 / latest.intervalMs : 0,
+      cpuMs: latest?.cpuMs ?? 0,
+      get p95Ms() {
+        return readPercentile(0.95);
+      },
+      get p99Ms() {
+        return readPercentile(0.99);
+      },
+      frames: snapshotFrames,
+      phases: latest?.phases ?? [],
+      systems: [...currentSystems].map(([name, ms]) => ({ name, ms })).sort((a, b) => b.ms - a.ms),
+      components: [...currentComponents]
+        .map(([name, ms]) => ({ name, ms }))
+        .sort((a, b) => b.ms - a.ms),
+      render,
+    };
+    for (const listener of listeners) listener();
+  }
+
+  return {
+    get enabled() {
+      return enabled;
+    },
+    set enabled(value: boolean) {
+      if (enabled === value) return;
+      enabled = value;
+      if (value && !telemetryEnabled) lastFrameStart = 0;
+      publish();
+    },
+    get telemetryEnabled() {
+      return telemetryEnabled;
+    },
+    set telemetryEnabled(value: boolean) {
+      if (telemetryEnabled === value) return;
+      const wasInactive = !enabled && !telemetryEnabled;
+      telemetryEnabled = value;
+      if (value && wasInactive) lastFrameStart = 0;
+      publish();
+    },
+    get recording() {
+      return recording;
+    },
+    startRecording() {
+      const wasInactive = !enabled && !telemetryEnabled;
+      enabled = true;
+      if (wasInactive) lastFrameStart = 0;
+      recording = true;
+      frames.length = 0;
+      publish();
+    },
+    stopRecording() {
+      recording = false;
+      publish();
+    },
+    clear() {
+      frames.length = 0;
+      publish();
+    },
+    beginFrame() {
+      if (!enabled && !telemetryEnabled) return;
+      currentPhases.clear();
+      currentSystems.clear();
+      currentComponents.clear();
+      frameSystems = [];
+      frameComponents = [];
+      // 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;
+      phaseStack.push(now());
+    },
+    endPhase(name: string) {
+      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
+      // measured start offset (earliest entry) as the span's startMs.
+      currentPhases.set(name, {
+        ms: (existing?.ms ?? 0) + elapsed,
+        startMs: existing?.startMs ?? phaseStart - frameStart,
+      });
+      if (recording)
+        performance.measure(`vgai.phase.${name}`, { start: phaseStart, duration: elapsed });
+    },
+    systemObserver: {
+      beginSystem() {
+        if (!enabled) return;
+        systemStart = now();
+      },
+      endSystem(scope: string, phase: string, name: string) {
+        if (!enabled) return;
+        const end = now();
+        const key = `${scope} / ${phase} / ${name}`;
+        currentSystems.set(key, (currentSystems.get(key) ?? 0) + end - systemStart);
+        frameSystems.push({
+          name: key,
+          phase,
+          startMs: systemStart - frameStart,
+          ms: end - systemStart,
+        });
+      },
+    },
+    beginComponent() {
+      if (!recording) return;
+      componentStart = now();
+    },
+    endComponent(name: string, phase = '') {
+      if (!recording) return;
+      const end = now();
+      currentComponents.set(name, (currentComponents.get(name) ?? 0) + end - componentStart);
+      frameComponents.push({
+        name,
+        phase,
+        startMs: componentStart - frameStart,
+        ms: end - componentStart,
+      });
+    },
+    reportRender(stats: {
+      gpuMs: number | null;
+      drawCalls: number;
+      triangles: number;
+      geometries: number;
+      textures: number;
+      /** Omit when this reporter does not count passes — see
+       *  {@link PerformanceRenderStats.renderPasses}. */
+      renderPasses?: number;
+    }) {
+      if (!enabled) return;
+      render = {
+        gpuMs: stats.gpuMs ?? render.gpuMs,
+        drawCalls: render.drawCalls + stats.drawCalls,
+        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() {
+      if (!enabled && !telemetryEnabled) return;
+      const timestamp = now();
+      const intervalMs = lastFrameStart === 0 ? 0 : frameStart - lastFrameStart;
+      lastFrameStart = frameStart;
+      const frame: PerformanceFrame = {
+        id: ++frameId,
+        timestamp,
+        intervalMs,
+        cpuMs: timestamp - frameStart,
+        phases: [...currentPhases]
+          .map(([name, { ms, startMs }]) => ({ name, ms, startMs }))
+          .sort((a, b) => b.ms - a.ms),
+        systems: frameSystems.slice(),
+        components: frameComponents.slice(),
+        render: { ...render },
+      };
+      frames.push(frame);
+      if (frames.length > 600) frames.splice(0, frames.length - 600);
+      if (recording)
+        performance.measure('vgai.frame', { start: frameStart, duration: frame.cpuMs });
+      publish();
+    },
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+    exportJSON() {
+      // version 2 (W4b): frames now carry per-frame `systems`/`components`
+      // spans, per-frame `render` counters, and `startMs` on phase timings.
+      return JSON.stringify({ version: 2, capturedAt: new Date().toISOString(), frames }, null, 2);
+    },
+  };
+}
+
+export type PerformanceProfiler = ReturnType<typeof createPerformanceProfiler>;

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

@@ -0,0 +1,276 @@
+/**
+ * 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 BOTH three-root mount paths — a game
+ * writes nothing to get these, and there is no capability to install:
+ *  - `editor-game/src/host/roots/r3f-root.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.
+ *
+ * ── 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. Both seeders call this only under `devBuildEnabled()`
+ * (`runtime/dev-build.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
+ * {@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 { z } from 'zod';
+import type { DebugRegistry } from '../debug-registry';
+import type { PerformanceProfiler } from './performance-profiler';
+import { findByName, meshFamilies, sceneCensus, structuralBatchScan } from './render-census';
+import { createRenderVitals, type RenderVitals } from './render-vitals';
+import {
+  ADVISOR_SETTLE_FRAMES,
+  decideStaticBatchAdvisory,
+  warnStaticBatchAdvisory,
+} from './static-batch-advisor';
+
+/** The one provider name — spelled here, referenced everywhere else. */
+export const RENDER_VITALS_PROVIDER = 'render.vitals';
+export const RENDER_CENSUS_COMMAND = 'render.census';
+export const RENDER_FAMILIES_COMMAND = 'render.families';
+export const RENDER_TOGGLE_COMMAND = 'render.toggle';
+export 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;
+}
+
+const NO_RENDERER =
+  'render.dpr: this world has no WebGL renderer (headless mount), so there is no pixel ratio ' +
+  'to change. The other render.* commands still work — they read the scene graph.';
+
+/**
+ * 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 function registerRenderVitals(
+  deps: RegisterRenderVitalsDeps,
+): RenderVitalsRegistration | null {
+  const { registry, worldId, profiler, scene, renderer } = deps;
+  const taken = registry.adapter
+    .providers()
+    .some((provider) => provider.name === RENDER_VITALS_PROVIDER);
+  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());
+
+  debug.registerCommand(
+    RENDER_CENSUS_COMMAND,
+    {
+      description:
+        'Visible meshes and triangles per subtree — the address book behind the draw-call ' +
+        'reading. Pass a subtree name (as listed by a previous census) to drill into it.',
+      args: z.tuple([z.string().optional()]),
+      locus: 'client',
+    },
+    (subtree) => {
+      if (subtree === undefined || subtree === '') return sceneCensus(scene);
+      const node = findByName(scene, subtree);
+      if (!node) {
+        throw new Error(
+          `render.census: no node named "${subtree}" in this world. Run render.census with no ` +
+            'argument to list the addressable subtrees.',
+        );
+      }
+      return sceneCensus(node, subtree);
+    },
+  );
+
+  debug.registerCommand(
+    RENDER_FAMILIES_COMMAND,
+    {
+      description:
+        'Meshes grouped by shared (geometry, material) identity, largest group first — the ' +
+        'instancing shortlist for a draw-call diet. `structural` is the same scan keyed by ' +
+        'VALUE instead of object identity: what would collapse under a <Frozen> wrapper ' +
+        '(vgai add static-batch) even when every mesh carries its own inline material.',
+      args: z.tuple([]),
+      locus: 'client',
+    },
+    // Two readings, deliberately: the identity families (what can be instanced
+    // as the scene stands) and the STRUCTURAL scan (what would collapse if the
+    // same draws were batched by value). A world writing inline materials —
+    // every fresh scaffold — has families of one and a large structural win,
+    // and reporting only the first would say "nothing to do" about the exact
+    // scene the `static-batch` capability exists for.
+    () => ({ ...meshFamilies(scene), structural: structuralBatchScan(scene) }),
+  );
+
+  debug.registerCommand(
+    RENDER_TOGGLE_COMMAND,
+    {
+      description:
+        'Show/hide a named subtree (as listed by render.census) and read render.vitals again — ' +
+        'the difference is what that subtree costs.',
+      args: z.tuple([z.string()]),
+      locus: 'client',
+    },
+    (name) => {
+      const node = findByName(scene, name);
+      if (!node) {
+        throw new Error(
+          `render.toggle: no node named "${name}" in this world. Run render.census to list the ` +
+            'addressable subtrees.',
+        );
+      }
+      node.visible = !node.visible;
+      return { name, visible: node.visible };
+    },
+  );
+
+  debug.registerCommand(
+    RENDER_DPR_COMMAND,
+    {
+      description:
+        'Set the renderer pixel ratio (retina default is ~2) to probe GPU fill cost — render CPU ' +
+        'that does not move when the drawing buffer shrinks was never fill-bound.',
+      args: z.tuple([z.number().positive().max(8)]),
+      locus: 'client',
+    },
+    (ratio) => {
+      if (!renderer) throw new Error(NO_RENDERER);
+      const size = renderer.getSize(new THREE.Vector2());
+      renderer.setPixelRatio(ratio);
+      // `updateStyle: false` — the CSS size is the layout's, not ours to
+      // change; only the drawing buffer moves, which is the whole experiment.
+      renderer.setSize(size.x, size.y, false);
+      return {
+        pixelRatio: renderer.getPixelRatio(),
+        drawingBuffer: { width: renderer.domElement.width, height: renderer.domElement.height },
+      };
+    },
+  );
+
+  // --- The static-batch advisory (issue #1503) -------------------------------
+  // A reading nobody asks for is a reading nobody gets, so the measurement
+  // routes itself: once the frame rate has settled, scan ONCE, and if this
+  // world is paying for draws it does not have to, name the exact wrapper on
+  // the console (`dev/static-batch-advisor.ts` owns the decision and the
+  // wording; this owns only WHEN).
+  //
+  // It rides the profiler subscription rather than a timer because the trigger
+  // is presented frames, not wall time: a tab that never presents (hidden,
+  // headless) should never scan, and a slow boot should not be measured before
+  // its assets are in the graph. The subscription ends itself the moment it
+  // fires or the advisory turns out to be `null`.
+  let stopAdvisor: (() => void) | null = null;
+  let advised = false;
+  const advisorTick = (): void => {
+    if (advised) return;
+    if (vitals.read().presentedFrames < ADVISOR_SETTLE_FRAMES) return;
+    advised = true;
+    stopAdvisor?.();
+    stopAdvisor = null;
+    const advisory = decideStaticBatchAdvisory({
+      drawCalls: vitals.read().drawCalls,
+      census: sceneCensus(scene),
+      structural: structuralBatchScan(scene),
+    });
+    if (advisory) warnStaticBatchAdvisory(advisory);
+  };
+  stopAdvisor = profiler.subscribe(advisorTick);
+
+  let disposed = false;
+  return {
+    vitals,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      stopAdvisor?.();
+      stopAdvisor = null;
+      vitals.dispose();
+    },
+  };
+}