@volter/editor-game 0.5.66 → 0.5.67

package/src/runtime/dev/static-batch-advisor.ts

@@ -0,0 +1,188 @@
+/**
+ * THE ROUTING from a draw-call reading to the one-line fix.
+ *
+ * `dev/render-vitals.ts` can already tell a game it is submitting 4,000 draws
+ * and `dev/render-census.ts` can already say which subtree they are in. Both
+ * require someone to ASK, and both require that someone to already know that
+ * static batching exists, is possible here, and is spelled `<Frozen>`. An
+ * agent building a game does not know any of that, so the measurement has to
+ * do the routing itself — the same idiom as dev-tools' unconfigured-section
+ * warning: the reading names the exact edit.
+ *
+ * ── THE DECISION IS PURE, THE SCHEDULE IS NOT ───────────────────────────────
+ * {@link decideStaticBatchAdvisory} takes a draw-call count and two scan
+ * reports and answers with an advisory or `null`. It reads no clock, no
+ * scene, no console. `editor-game/src/runtime/dev/register-render-vitals.ts` owns the impure half —
+ * when to scan, and warning once — because that is where the profiler
+ * subscription already lives.
+ *
+ * ── COST ────────────────────────────────────────────────────────────────────
+ * The scan is TWO walks of the scene graph, once, after the frame rate has
+ * settled ({@link ADVISOR_SETTLE_FRAMES}). Never per frame: a walk of 4,000
+ * nodes every frame is itself the kind of cost this advisory exists to
+ * remove, and the answer does not change from one frame to the next in a world
+ * whose scenery is mount-static — which is the only world the advice applies
+ * to anyway.
+ *
+ * ── WHY IT ASKS INSTEAD OF ACTING ───────────────────────────────────────────
+ * "These 2,600 meshes are the same draw" is measurable. "These 2,600 meshes
+ * never move" is NOT — nothing in a scene graph distinguishes scenery from a
+ * thing that will move on the next input. Inferring it and batching anyway is
+ * how a batcher freezes a door half-open. So the advisory names the subtree
+ * and the wrapper, and the author (who knows) places it.
+ */
+
+import type { CensusReport, StructuralBatchReport } from './render-census';
+
+/**
+ * Draw calls below which no advisory fires, however batchable the scene.
+ *
+ * The field measurement this capability came out of: ~4,000 draws cost ~11 ms
+ * of CPU submission per frame — about 2.75 µs each on a desktop browser. At
+ * 500 draws that is ~1.4 ms, roughly 8% of a 60 Hz frame: the first point
+ * where halving it is a visible win rather than noise a profiler cannot
+ * separate from jitter. Below it, an advisory would be a nag pointing at
+ * something that is not costing anything, and a nag that is usually wrong is
+ * one nobody reads when it is right.
+ */
+export const ADVISOR_DRAW_CALL_THRESHOLD = 500;
+
+/**
+ * The share of the draw calls that must be collapsible before the advice is
+ * worth an edit. Half: below that, the wrapper leaves most of the cost exactly
+ * where it was, and "you could remove a third of a third" is not a payoff
+ * anyone should restructure a scene for.
+ */
+export const ADVISOR_COLLAPSIBLE_SHARE = 0.5;
+
+/**
+ * A subtree must hold at least this share of the collapsible meshes to be
+ * named as THE address. Under it the advisory says "across the scene" — an
+ * invented address is worse than none, because the reader wraps the wrong
+ * group and measures no change.
+ */
+export const ADVISOR_SUBTREE_SHARE = 0.4;
+
+/**
+ * Presented frames to wait before scanning — ~2 s at 60 Hz. Long enough for
+ * asset loads and the first setup pass to finish populating the graph (a scan
+ * at frame one measures an empty world and stays silent forever), short enough
+ * that the line lands while the author is still looking at the boot.
+ */
+export const ADVISOR_SETTLE_FRAMES = 120;
+
+/** The finding, as a caller can present it however it likes. */
+export interface StaticBatchAdvisory {
+  /** The reading that triggered it. */
+  readonly drawCalls: number;
+  /** Meshes sitting in a structural family of two or more. */
+  readonly collapsible: number;
+  /** The subtree holding most of them, or `null` when they are spread out. */
+  readonly subtree: string | null;
+  /** The exact edit, ready to paste — `<Frozen name="Terminal">`. */
+  readonly fix: string;
+  /** The one-line console message: payoff, address, edit, install. */
+  readonly message: string;
+}
+
+export interface StaticBatchAdvisoryInput {
+  /** `render.vitals`' own reading. `null` before the first presented frame. */
+  readonly drawCalls: number | null;
+  /** The one-level census, used only to sanity-check the address against a
+   *  subtree that genuinely exists in the graph. */
+  readonly census: CensusReport;
+  /** The STRUCTURAL scan — see `render-census.ts` for why the identity scan
+   *  cannot answer this. */
+  readonly structural: StructuralBatchReport;
+}
+
+/** `2600` → `2,600`. Digits a person reads at a glance, in the one place the
+ *  message is built, so every number in it is grouped the same way. */
+function grouped(value: number): string {
+  return value.toLocaleString('en-US');
+}
+
+/**
+ * Decide whether this frame's cost is worth an advisory, and what it should
+ * say. Pure — every input is an argument, and the same arguments always
+ * produce the same message.
+ */
+export function decideStaticBatchAdvisory(
+  input: StaticBatchAdvisoryInput,
+): StaticBatchAdvisory | null {
+  const { drawCalls, census, structural } = input;
+  if (drawCalls === null || drawCalls < ADVISOR_DRAW_CALL_THRESHOLD) return null;
+
+  const { collapsible } = structural;
+  if (collapsible < drawCalls * ADVISOR_COLLAPSIBLE_SHARE) return null;
+
+  // The address, when one subtree genuinely dominates. `bySubtree` is already
+  // sorted, and a name that no census row confirms is not offered: it would
+  // send the reader looking for a node the other render.* commands cannot
+  // find either.
+  const addressable = new Set(census.subtrees.map((row) => row.name));
+  const leader = structural.bySubtree[0];
+  const subtree =
+    leader &&
+    leader.collapsible >= collapsible * ADVISOR_SUBTREE_SHARE &&
+    addressable.has(leader.name)
+      ? leader.name
+      : null;
+
+  const fix = subtree === null ? '<Frozen>' : `<Frozen name="${subtree}">`;
+  const where = subtree === null ? 'spread across the scene' : `mostly under "${subtree}"`;
+  const message =
+    // `collapsible` counts meshes in the graph (culled ones included) and `drawCalls` this
+    // frame's submissions, so each number is stated in its own unit, never as a share.
+    `[static-batch] ${grouped(drawCalls)} draw calls this frame; ~${grouped(collapsible)} meshes ` +
+    `are repeats of ${grouped(structural.familyCount)} structural families, ` +
+    `${where}. If that scenery is mount-static — nothing under it moves, re-colours or ` +
+    `unmounts after mount — one wrapper collapses it to a few draws: wrap it in ` +
+    `${fix}…</Frozen>  (vgai add static-batch). Reactive scenery goes outside the wrapper, ` +
+    `and a subtree that must stay unbatched declares it: userData={{ staticBatch: false }}.`;
+
+  return { drawCalls, collapsible, subtree, fix, message };
+}
+
+/**
+ * Once per PAGE, not once per module evaluation — a hot reload re-runs this
+ * module, and an advisory that reappears on every save is one that gets muted
+ * along with everything else on the console. Same mechanism, and the same
+ * reason, as dev-tools' unconfigured-section warning.
+ */
+const WARNED_KEY = '__vgaiStaticBatchAdvised';
+
+function alreadyWarned(): boolean {
+  return (globalThis as unknown as Record<string, boolean | undefined>)[WARNED_KEY] === true;
+}
+
+/**
+ * The console IS this advisory's channel: `vgai status` reports console
+ * warnings, which is where a building agent already looks. An in-editor
+ * banner would be one nobody opens, and a provider would be one nobody reads
+ * without already knowing to ask.
+ */
+function warnOnConsole(message: string): void {
+  // biome-ignore lint/suspicious/noConsole: this function's entire job — see above.
+  console.warn(message);
+}
+
+/**
+ * Emit `advisory` on the console, at most once per page. Answers whether it
+ * warned, so a caller can stop scanning.
+ */
+export function warnStaticBatchAdvisory(
+  advisory: StaticBatchAdvisory,
+  /** Injectable so the decision is testable without a console. */
+  warn: (message: string) => void = warnOnConsole,
+): boolean {
+  if (alreadyWarned()) return false;
+  (globalThis as unknown as Record<string, boolean>)[WARNED_KEY] = true;
+  warn(advisory.message);
+  return true;
+}
+
+/** Test-only: forget that the advisory was ever emitted. */
+export function __resetStaticBatchAdvisoryForTest(): void {
+  (globalThis as unknown as Record<string, boolean | undefined>)[WARNED_KEY] = undefined;
+}

package/src/runtime/dev/webgl-frame-capture.ts

@@ -0,0 +1,366 @@
+/**
+ * First-party WebGL2 single-frame draw-call capture (W4b, F11 frame debugger).
+ *
+ * WHY FIRST-PARTY, NOT spectorjs (recorded per the "use libraries directly, no
+ * wrappers" rule): the capture seam we need is the WebGL2 context this engine
+ * ALREADY owns end-to-end (`renderer.getContext()` in
+ * `editor-game/src/host/roots/r3f-root.tsx`). spectorjs is absent from node_modules, and its
+ * actual value is a bundled inspector UI we would discard — adopting it imports
+ * ~2MB of library to keep ~10% of it, and it wraps the context with its own
+ * global patching model rather than the instance-shadow-and-restore discipline
+ * the rest of dev/ uses (see `webgl-gpu-timer.ts`, the raw-context precedent
+ * this mirrors: instance shadowing, restore-in-finally, mock-GL unit test). So
+ * we instrument the real context directly, at the one seam we control.
+ *
+ * DISCIPLINE (mirrors webgl-gpu-timer.ts):
+ *  - Patching happens ONLY inside `beginPass()` and ONLY while `armed`. Every
+ *    patch is an OWN-property shadow on the context instance; the WebGL2
+ *    prototype is NEVER touched. `endPass()` restores every original in a
+ *    `finally` (own props reassigned, prototype-inherited methods `delete`d so
+ *    the real method shows through again), so a throwing draw cannot leave the
+ *    context wrapped.
+ *  - HONESTY (adapters never fabricate): a value we cannot measure at this seam
+ *    is recorded as `null` with the reason implied by the field, never zeroed
+ *    or guessed. Program/framebuffer LABELS are capture-local identity tags
+ *    (`program#N`), not the object's real GL debug name (raw WebGL2 exposes
+ *    none). Framebuffer dimensions are only reported when cheaply knowable
+ *    (renderbuffer color attachment); a texture-attachment FBO's size is not
+ *    queryable in raw WebGL2, so it is `null`, not invented (see below —
+ *    a documented deviation from the plan's non-nullable width/height).
+ *  - Draw attribution is a single pending-annotation slot consumed by the NEXT
+ *    draw and then cleared: a second draw with no fresh annotation records
+ *    `annotation: null` (counted as unattributed), never the previous draw's.
+ */
+
+import type {
+  DrawAnnotation,
+  DrawTarget,
+  FrameCapture,
+  FrameCaptureDrawCall,
+  FrameCaptureEntryPoint,
+} from '@volter/editor-project/adapter/frame-capture';
+
+export type {
+  DrawAnnotation,
+  DrawTarget,
+  FrameCapture,
+  FrameCaptureDrawCall,
+  FrameCaptureEntryPoint,
+} from '@volter/editor-project/adapter/frame-capture';
+
+export interface WebGLFrameCaptureOptions {
+  /** Injected clock for `capturedAt`; defaults to `Date.now`. Injectable so a
+   *  test gets deterministic timestamps (mirrors the profiler stamping time
+   *  through a single `now()` indirection rather than a module-level call). */
+  now?: () => number;
+  /** Hard cap on recorded draws (default 5000). Draws past it are dropped and
+   *  counted in `totals.truncated`, with a note. */
+  maxDrawCalls?: number;
+}
+
+export interface WebGLFrameCapture {
+  /** Arm a single capture; the NEXT `beginPass()` patches the context. */
+  arm(): void;
+  readonly armed: boolean;
+  /** If armed, shadow-patch the context. No-op otherwise (zero patching when
+   *  not armed). Must be paired with `endPass()`. */
+  beginPass(): void;
+  /** Restore all patches (in `finally`) and, if a pass was patched, return the
+   *  assembled {@link FrameCapture}. Returns `null` if `beginPass` did not
+   *  patch (was not armed). One-shot: disarms after. */
+  endPass(): FrameCapture | null;
+  /** Set the annotation the next draw will consume (then cleared). */
+  annotateNextDraw(annotation: DrawAnnotation): void;
+}
+
+const DEFAULT_MAX_DRAW_CALLS = 5000;
+
+/** GL primitive-mode enum → name (decoded once, from the live context). */
+function buildModeTable(gl: WebGL2RenderingContext): Map<number, string> {
+  return new Map<number, string>([
+    [gl.POINTS, 'POINTS'],
+    [gl.LINES, 'LINES'],
+    [gl.LINE_LOOP, 'LINE_LOOP'],
+    [gl.LINE_STRIP, 'LINE_STRIP'],
+    [gl.TRIANGLES, 'TRIANGLES'],
+    [gl.TRIANGLE_STRIP, 'TRIANGLE_STRIP'],
+    [gl.TRIANGLE_FAN, 'TRIANGLE_FAN'],
+  ]);
+}
+
+export function createWebGLFrameCapture(
+  gl: WebGL2RenderingContext,
+  options: WebGLFrameCaptureOptions = {},
+): WebGLFrameCapture {
+  const nowFn = options.now ?? (() => Date.now());
+  const maxDrawCalls = options.maxDrawCalls ?? DEFAULT_MAX_DRAW_CALLS;
+  const modeTable = buildModeTable(gl);
+
+  // Persistent identity maps (stable labels across passes).
+  const programLabels = new Map<WebGLProgram, string>();
+  const framebufferLabels = new Map<WebGLFramebuffer, string>();
+  let nextProgramId = 0;
+  let nextFramebufferId = 0;
+  let captureId = 0;
+
+  // Shadow-tracked GL state (updated by the wrapped setters during a pass).
+  let currentProgram: WebGLProgram | null = null;
+  let currentFramebuffer: WebGLFramebuffer | null = null;
+  let currentViewport: [number, number, number, number] = [0, 0, 0, 0];
+
+  // Per-pass accumulators.
+  let armed = false;
+  let patched = false;
+  let drawCalls: FrameCaptureDrawCall[] = [];
+  let truncated = 0;
+  let notes: string[] = [];
+  let pendingAnnotation: DrawAnnotation | null = null;
+
+  // Saved originals for restore. Value is the original fn; a key present in
+  // `wasOwn` means it was an own property (restore by assignment), otherwise
+  // it was prototype-inherited (restore by delete).
+  const originals = new Map<string, unknown>();
+  const wasOwn = new Set<string>();
+
+  function decodeMode(mode: number): string {
+    return modeTable.get(mode) ?? `0x${mode.toString(16)}`;
+  }
+
+  function labelForProgram(program: WebGLProgram | null): string | null {
+    if (!program) return null;
+    let label = programLabels.get(program);
+    if (label === undefined) {
+      label = `program#${nextProgramId++}`;
+      programLabels.set(program, label);
+    }
+    return label;
+  }
+
+  /** Best-effort color-attachment dimensions for a bound draw FBO. Only a
+   *  RENDERBUFFER color attachment is cheaply queryable in raw WebGL2; a
+   *  texture attachment is not, so this returns nulls (honest absence). All
+   *  reads are guarded — a mock/foreign context returns nulls, never throws. */
+  function measureFramebufferSize(): { width: number | null; height: number | null } {
+    try {
+      const type = gl.getFramebufferAttachmentParameter(
+        gl.DRAW_FRAMEBUFFER,
+        gl.COLOR_ATTACHMENT0,
+        gl.FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE,
+      );
+      if (type === gl.RENDERBUFFER) {
+        const rb = gl.getFramebufferAttachmentParameter(
+          gl.DRAW_FRAMEBUFFER,
+          gl.COLOR_ATTACHMENT0,
+          gl.FRAMEBUFFER_ATTACHMENT_OBJECT_NAME,
+        ) as WebGLRenderbuffer | null;
+        if (!rb) return { width: null, height: null };
+        const prev = gl.getParameter(gl.RENDERBUFFER_BINDING) as WebGLRenderbuffer | null;
+        gl.bindRenderbuffer(gl.RENDERBUFFER, rb);
+        const width = gl.getRenderbufferParameter(gl.RENDERBUFFER, gl.RENDERBUFFER_WIDTH) as number;
+        const height = gl.getRenderbufferParameter(
+          gl.RENDERBUFFER,
+          gl.RENDERBUFFER_HEIGHT,
+        ) as number;
+        gl.bindRenderbuffer(gl.RENDERBUFFER, prev);
+        return { width, height };
+      }
+    } catch {
+      // Foreign/mock context or an attachment we can't introspect — degrade
+      // to unknown dimensions rather than throwing mid-capture.
+    }
+    return { width: null, height: null };
+  }
+
+  function currentTarget(): DrawTarget {
+    if (!currentFramebuffer) return { kind: 'canvas' };
+    let label = framebufferLabels.get(currentFramebuffer);
+    if (label === undefined) {
+      label = `framebuffer#${nextFramebufferId++}`;
+      framebufferLabels.set(currentFramebuffer, label);
+    }
+    const { width, height } = measureFramebufferSize();
+    return { kind: 'framebuffer', width, height, label };
+  }
+
+  function readCull(): 'front' | 'back' | 'none' {
+    if (!gl.getParameter(gl.CULL_FACE)) return 'none';
+    return gl.getParameter(gl.CULL_FACE_MODE) === gl.FRONT ? 'front' : 'back';
+  }
+
+  function recordDraw(
+    entryPoint: FrameCaptureEntryPoint,
+    mode: number,
+    count: number,
+    instanceCount: number | null,
+  ): void {
+    if (drawCalls.length >= maxDrawCalls) {
+      truncated++;
+      pendingAnnotation = null;
+      return;
+    }
+    const annotation = pendingAnnotation;
+    pendingAnnotation = null;
+    drawCalls.push({
+      index: drawCalls.length,
+      entryPoint,
+      mode: decodeMode(mode),
+      count,
+      instanceCount,
+      programLabel: labelForProgram(currentProgram),
+      target: currentTarget(),
+      viewport: [...currentViewport] as [number, number, number, number],
+      state: {
+        blend: Boolean(gl.getParameter(gl.BLEND)),
+        depthTest: Boolean(gl.getParameter(gl.DEPTH_TEST)),
+        depthWrite: Boolean(gl.getParameter(gl.DEPTH_WRITEMASK)),
+        cull: readCull(),
+        scissor: Boolean(gl.getParameter(gl.SCISSOR_TEST)),
+      },
+      annotation: annotation ?? null,
+    });
+  }
+
+  // Cast to an index signature to shadow methods without fighting the DOM lib
+  // types on every wrapped name.
+  const target = gl as unknown as Record<string, unknown>;
+
+  function patch(name: string, wrapper: (original: (...a: unknown[]) => unknown) => unknown): void {
+    const original = target[name] as (...a: unknown[]) => unknown;
+    originals.set(name, original);
+    if (Object.hasOwn(gl, name)) wasOwn.add(name);
+    target[name] = wrapper(original.bind(gl));
+  }
+
+  function restoreAll(): void {
+    for (const [name, original] of originals) {
+      if (wasOwn.has(name)) target[name] = original;
+      else delete target[name];
+    }
+    originals.clear();
+    wasOwn.clear();
+  }
+
+  function installPatches(): void {
+    // Seed shadow state from the live context so the first draw's viewport /
+    // framebuffer / program reflect reality even before any setter fires.
+    try {
+      const vp = gl.getParameter(gl.VIEWPORT) as ArrayLike<number> | null;
+      if (vp && vp.length >= 4) currentViewport = [vp[0]!, vp[1]!, vp[2]!, vp[3]!];
+      currentFramebuffer = gl.getParameter(gl.FRAMEBUFFER_BINDING) as WebGLFramebuffer | null;
+      currentProgram = gl.getParameter(gl.CURRENT_PROGRAM) as WebGLProgram | null;
+    } catch {
+      // Mock context without full getParameter coverage — start from defaults.
+    }
+
+    patch('useProgram', (original) => (program: unknown) => {
+      currentProgram = (program as WebGLProgram) ?? null;
+      return original(program);
+    });
+    patch('bindFramebuffer', (original) => (bindTarget: unknown, framebuffer: unknown) => {
+      // Track the DRAW framebuffer binding (FRAMEBUFFER and DRAW_FRAMEBUFFER
+      // both affect it; READ_FRAMEBUFFER does not).
+      if (bindTarget === gl.FRAMEBUFFER || bindTarget === gl.DRAW_FRAMEBUFFER) {
+        currentFramebuffer = (framebuffer as WebGLFramebuffer) ?? null;
+      }
+      return original(bindTarget, framebuffer);
+    });
+    patch('viewport', (original) => (x: unknown, y: unknown, w: unknown, h: unknown) => {
+      currentViewport = [x as number, y as number, w as number, h as number];
+      return original(x, y, w, h);
+    });
+
+    patch('drawArrays', (original) => (mode: unknown, first: unknown, count: unknown) => {
+      recordDraw('drawArrays', mode as number, count as number, null);
+      return original(mode, first, count);
+    });
+    patch(
+      'drawElements',
+      (original) => (mode: unknown, count: unknown, type: unknown, offset: unknown) => {
+        recordDraw('drawElements', mode as number, count as number, null);
+        return original(mode, count, type, offset);
+      },
+    );
+    patch(
+      'drawArraysInstanced',
+      (original) => (mode: unknown, first: unknown, count: unknown, instanceCount: unknown) => {
+        recordDraw('drawArraysInstanced', mode as number, count as number, instanceCount as number);
+        return original(mode, first, count, instanceCount);
+      },
+    );
+    patch(
+      'drawElementsInstanced',
+      (original) =>
+        (mode: unknown, count: unknown, type: unknown, offset: unknown, instanceCount: unknown) => {
+          recordDraw(
+            'drawElementsInstanced',
+            mode as number,
+            count as number,
+            instanceCount as number,
+          );
+          return original(mode, count, type, offset, instanceCount);
+        },
+    );
+    patch(
+      'drawRangeElements',
+      (original) =>
+        (
+          mode: unknown,
+          start: unknown,
+          end: unknown,
+          count: unknown,
+          type: unknown,
+          offset: unknown,
+        ) => {
+          recordDraw('drawRangeElements', mode as number, count as number, null);
+          return original(mode, start, end, count, type, offset);
+        },
+    );
+  }
+
+  return {
+    arm() {
+      armed = true;
+    },
+    get armed() {
+      return armed;
+    },
+    beginPass() {
+      if (!armed || patched) return;
+      patched = true;
+      drawCalls = [];
+      truncated = 0;
+      notes = [];
+      pendingAnnotation = null;
+      installPatches();
+    },
+    endPass(): FrameCapture | null {
+      if (!patched) {
+        armed = false;
+        return null;
+      }
+      try {
+        if (truncated > 0) {
+          notes.push(
+            `Draw list capped at ${maxDrawCalls}; ${truncated} later draw(s) were not recorded.`,
+          );
+        }
+        const unattributed = drawCalls.reduce((n, d) => n + (d.annotation === null ? 1 : 0), 0);
+        return {
+          id: ++captureId,
+          capturedAt: nowFn(),
+          drawCalls: drawCalls.slice(),
+          totals: { drawCalls: drawCalls.length, unattributed, truncated },
+          notes: notes.slice(),
+        };
+      } finally {
+        restoreAll();
+        patched = false;
+        armed = false;
+        pendingAnnotation = null;
+      }
+    },
+    annotateNextDraw(annotation: DrawAnnotation) {
+      pendingAnnotation = annotation;
+    },
+  };
+}

package/src/runtime/dev/webgl-gpu-timer.ts

@@ -0,0 +1,53 @@
+interface DisjointTimerQueryExtension {
+  readonly TIME_ELAPSED_EXT: number;
+  readonly GPU_DISJOINT_EXT: number;
+}
+
+/** Non-blocking WebGL2 timer query; results are consumed on later frames. */
+export function createWebGLGpuTimer(context: WebGLRenderingContext | WebGL2RenderingContext) {
+  const gl = context as WebGL2RenderingContext;
+  const extension = gl.getExtension(
+    'EXT_disjoint_timer_query_webgl2',
+  ) as DisjointTimerQueryExtension | null;
+  const supported = extension !== null && typeof gl.createQuery === 'function';
+  const pending: WebGLQuery[] = [];
+  let active: WebGLQuery | null = null;
+  let latestMs: number | null = null;
+
+  return {
+    begin() {
+      if (!supported || active) return;
+      active = gl.createQuery();
+      if (active) gl.beginQuery(extension!.TIME_ELAPSED_EXT, active);
+    },
+    end() {
+      if (!supported || !active) return;
+      gl.endQuery(extension!.TIME_ELAPSED_EXT);
+      pending.push(active);
+      active = null;
+    },
+    poll(): number | null {
+      if (!supported) return null;
+      if (gl.getParameter(extension!.GPU_DISJOINT_EXT)) {
+        for (const query of pending.splice(0)) gl.deleteQuery(query);
+        return null;
+      }
+      while (pending.length > 0) {
+        const query = pending[0]!;
+        if (!gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE)) break;
+        pending.shift();
+        latestMs = (gl.getQueryParameter(query, gl.QUERY_RESULT) as number) / 1_000_000;
+        gl.deleteQuery(query);
+      }
+      return latestMs;
+    },
+    dispose() {
+      if (active) {
+        gl.endQuery(extension!.TIME_ELAPSED_EXT);
+        gl.deleteQuery(active);
+        active = null;
+      }
+      for (const query of pending.splice(0)) gl.deleteQuery(query);
+    },
+  };
+}

package/src/runtime/dev-build.ts

@@ -0,0 +1,47 @@
+/**
+ * THE one owner of "is this a development context". Every reader that has to
+ * answer that question calls {@link devBuildEnabled}; there is deliberately NO
+ * second source of truth — not a module-level cached boolean, not a
+ * `globalThis` flag, not a per-host copy of the `import.meta.env` read below.
+ * Instrumentation that ships to players because two places disagreed about
+ * what "dev" means is exactly the failure this single owner exists to make
+ * impossible.
+ *
+ * Ownership, stated in one place (the build rule):
+ *  - OWNER: this function. It resolves the answer; nothing else derives it.
+ *  - SHARERS: the three-root adapter (`editor-game/src/host/roots/r3f-root.tsx`),
+ *    which seeds live render vitals only under it. Any future dev-only
+ *    instrument calls this too, with its own `override`.
+ *  - TEARDOWN: none. This is a pure predicate over build config and one
+ *    caller-supplied argument — it owns no resource, allocates nothing, and
+ *    has no lifecycle to end.
+ *
+ * The three inputs, highest precedence first:
+ *  1. `override` — the explicit per-call answer. A headless test, a capture
+ *     harness, or a host that knows better passes `true`/`false` and gets
+ *     exactly that. Passing `undefined` (or omitting it) means "decide for
+ *     me" and falls through. The editor's own preview mount is the worked
+ *     case: it is a dev session by definition even when the editor SPA it
+ *     runs inside is a production build.
+ *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case.
+ *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_BUILD=true`.
+ *     Instrumenting a production bundle is a real, legitimate choice (an
+ *     internal playtest build, a QA build), and it must be an opt-in someone
+ *     had to type, never something a default drifts into.
+ *
+ * Anything else — a production build with no opt-in — is `false`.
+ */
+export function devBuildEnabled(override?: boolean | undefined): boolean {
+  if (override !== undefined) return override;
+  // `import.meta` is cast whole, not just its `.env`: this module is reachable
+  // from programs whose tsconfig does not pull in `vite/client` (the session
+  // client's, for one, which reaches the three adapter transitively), and there
+  // `ImportMeta` has no declared `env` at all. The cast keeps the single owner
+  // of the dev answer importable from ANY program rather than forcing every
+  // downstream tsconfig to adopt Vite's ambient types.
+  const env = (import.meta as unknown as { env?: unknown }).env as
+    | { DEV?: boolean | undefined; VITE_VGAI_DEV_BUILD?: string | undefined }
+    | undefined;
+  if (env?.DEV === true) return true;
+  return env?.VITE_VGAI_DEV_BUILD === 'true';
+}