@vgai/engine 0.5.8 → 0.5.10

package/src/dev/render-vitals.ts

@@ -0,0 +1,338 @@
+/**
+ * LIVE RENDER VITALS — the frame explaining its own cost, derived ENTIRELY
+ * from `PerformanceProfiler` frames (`dev/performance-profiler.ts`).
+ *
+ * Nothing in a viewport tells you why it is slow, and a frame-time number on
+ * its own tells you only THAT it is. These readings answer the next question:
+ * where did the milliseconds go, and which subtree owns them
+ * (`dev/render-census.ts` is the address book half).
+ *
+ * ── THE MEASUREMENT SOURCE, STATED ONCE ─────────────────────────────────────
+ * There is no side ledger here. Every number below is folded out of profiler
+ * frames — the timing from phase spans, the counters from `reportRender`. The
+ * CPU submission cost is the profiler phase {@link RENDER_SUBMIT_PHASE}, which
+ * the three adapter brackets around its actual draw; the profiler's phase
+ * bookkeeping is a stack precisely so that bracket can sit INSIDE the frame's
+ * enclosing `render` phase without truncating it.
+ *
+ * ── TWO FRAME FLAVOURS, ONE FOLD ────────────────────────────────────────────
+ * The real runtime runs sim and presentation on different callbacks
+ * (`create-runtime.ts`: `update` → `runFrame({skipRenderPhases})` per fixed
+ * substep, `render` → `runRenderFrame` once per display frame), so a profiler
+ * "frame" is EITHER a sim substep OR a presentation pass. A capture/offline
+ * host drives one `runFrame` that is both. {@link foldProfilerFrame} handles
+ * all three the same way, and never has to know which host it is under:
+ *
+ *  - a frame carrying a {@link RENDER_SUBMIT_PHASE} span IS a presentation —
+ *    that phase only exists when a draw actually happened;
+ *  - sim CPU accumulates across every frame since the last presentation, so
+ *    the substeps a display frame consumed are attributed to it;
+ *  - renderer COUNTERS ride whichever frame `reportRender` landed on (the
+ *    adapter reports from its `endFrame` hook, which the substep pass drives),
+ *    so the latest report wins and the counters describe the last completed
+ *    draw. That is the same one-frame-warm reading `renderer.info` gives any
+ *    caller — three resets it when the next draw starts.
+ *
+ * ── WHY THE WORST FRAME IS NOT AN EMA ───────────────────────────────────────
+ * A decaying average keeps a restart spike on the readout for ~30 s, long
+ * after it stopped being true. The rolling two-window max
+ * ({@link WORST_WINDOW_FRAMES}) holds a hitch for one to two windows and then
+ * genuinely forgets it, so the number always describes recent history.
+ *
+ * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
+ * OWNER: the caller of {@link createRenderVitals}, which allocates one state
+ * object and one `profiler.subscribe` registration. SHARER: none — the state
+ * is private to that call. TEARDOWN: the returned `dispose()`, the ONE path
+ * that ends the subscription (`setup-three-root-adapter.ts` calls it from
+ * `disposeGame`).
+ */
+
+import type { PerformanceFrame, PerformanceProfiler } from './performance-profiler';
+
+/**
+ * The profiler phase name the three adapter brackets its CPU render
+ * submission with — spelled HERE and nowhere else, so the producer
+ * (`setup-three-root-adapter.ts`) and the consumer ({@link foldProfilerFrame})
+ * cannot drift apart. Dotted, so it reads as a decomposition of the enclosing
+ * `render` phase rather than a ninth peer of `SystemPhase`.
+ */
+export const RENDER_SUBMIT_PHASE = 'render.submit';
+
+/**
+ * The phases whose cost is SIMULATION. Deliberately not "everything that is
+ * not render": `preRender` (LOD selection, particle stepping, culling prep) is
+ * neither the simulation nor the submission, so it lands in the hitch's
+ * `other` bucket where an investigation can see it. `render` itself is
+ * excluded because {@link RENDER_SUBMIT_PHASE} nests inside it — summing both
+ * would double-count the draw.
+ */
+export const SIM_PHASES: readonly string[] = [
+  'input',
+  'prePhysics',
+  'physics',
+  'postPhysics',
+  'gameLogic',
+  'animation',
+];
+
+/** Display frames per worst-frame window — ~5 s at 60 Hz, so the reported
+ *  worst (the max of the current and previous window) survives 5–10 s. */
+export const WORST_WINDOW_FRAMES = 300;
+
+/** A display frame at or above this is worth decomposing. ~3 dropped frames at
+ *  60 Hz: below it, ordinary jitter would rewrite the reading constantly. */
+export const HITCH_THRESHOLD_MS = 50;
+
+/** Smoothing for the frame-time reading — a readable number, not a blur. */
+export const FRAME_TIME_EMA_ALPHA = 0.05;
+
+/** Smoothing for the render-CPU reading. Faster than frame time: submission
+ *  cost is what a draw-call diet moves, and it should visibly move. */
+export const RENDER_CPU_EMA_ALPHA = 0.1;
+
+/**
+ * A hitch, split into the three buckets that route an investigation. `other`
+ * is the diagnostic payload, not a rounding remainder: when it dominates, the
+ * thief is neither the renderer nor the simulation — it is GC, asset decode,
+ * a layout-thrashing DOM overlay, or the browser itself — and every minute
+ * spent on draw calls would have been wasted.
+ */
+export interface HitchDecomposition {
+  /** The display frame's wall-clock cost. */
+  readonly totalMs: number;
+  /** CPU spent submitting draws ({@link RENDER_SUBMIT_PHASE}). */
+  readonly renderMs: number;
+  /** CPU spent in {@link SIM_PHASES}, summed over the substeps this frame
+   *  consumed. */
+  readonly simMs: number;
+  /** Everything else in the wall clock — see this interface's own note. May be
+   *  negative if a measurement straddles the frame boundary; reported as
+   *  measured rather than clamped to a tidier lie. */
+  readonly otherMs: number;
+  /** The one-line reading: `"NNms = render X + sim Y + other Z"`. */
+  readonly text: string;
+}
+
+/** Split one display frame's wall clock into render / sim / other. Pure. */
+export function decomposeHitch(
+  totalMs: number,
+  renderMs: number,
+  simMs: number,
+): HitchDecomposition {
+  const otherMs = totalMs - renderMs - simMs;
+  return {
+    totalMs,
+    renderMs,
+    simMs,
+    otherMs,
+    text:
+      `${totalMs.toFixed(0)}ms = render ${renderMs.toFixed(0)} + ` +
+      `sim ${simMs.toFixed(0)} + other ${otherMs.toFixed(0)}`,
+  };
+}
+
+/** What `render.vitals` reads. Every field is `null` until the fold has
+ *  actually measured it — a stopped, headless or never-drawn game reports
+ *  emptiness rather than a fabricated `0 ms / 0 draws`. */
+export interface RenderVitalsReading {
+  /** Smoothed wall-clock ms per display frame. */
+  readonly frameTimeMs: number | null;
+  /** Frames per second implied by {@link frameTimeMs}. */
+  readonly fps: number | null;
+  /** Draw calls in the last reported draw. */
+  readonly drawCalls: number | null;
+  /** Triangles in the last reported draw. */
+  readonly triangles: number | null;
+  /** Smoothed CPU ms spent submitting draws — invisible in frame time once
+   *  vsync caps the loop, and exactly what fewer draw calls would improve. */
+  readonly renderCpuMs: number | null;
+  /** Top-level `renderer.render()` submissions the last presentation took. */
+  readonly renderPasses: number | null;
+  /** Worst display frame in the last one-to-two windows. */
+  readonly worstFrameMs: number | null;
+  /** The most recent frame over {@link HITCH_THRESHOLD_MS}, decomposed. */
+  readonly lastHitch: HitchDecomposition | null;
+  /** How many display frames the fold has seen. `0` reads as "nothing has
+   *  presented yet", which is why every reading above is `null`. */
+  readonly presentedFrames: number;
+}
+
+/** The fold's accumulator. Mutable by design (one allocation for the life of a
+ *  mount, written once per profiler frame); read through
+ *  {@link readRenderVitals}. */
+export interface RenderVitalsState {
+  /** Highest profiler frame id already folded — the dedupe that makes the fold
+   *  safe to drive from `profiler.subscribe`, which also fires for
+   *  enabled/recording changes that publish no new frame. */
+  lastFrameId: number;
+  /** `timestamp` of the last presentation, or `null` before the first (there
+   *  is no interval to measure from one sample). */
+  lastPresentAt: number | null;
+  /** Sim CPU accumulated since the last presentation. */
+  pendingSimMs: number;
+  frameTimeMs: number | null;
+  renderCpuMs: number | null;
+  drawCalls: number | null;
+  triangles: number | null;
+  renderPasses: number | null;
+  /** Running max of the CURRENT worst-frame window. */
+  worstCurrentMs: number;
+  /** The PREVIOUS window's max, kept so the reading does not drop to zero the
+   *  instant a window rolls over. */
+  worstPreviousMs: number;
+  /** Display frames counted into the current window. */
+  worstWindowFrames: number;
+  lastHitch: HitchDecomposition | null;
+  presentedFrames: number;
+}
+
+export function createRenderVitalsState(): RenderVitalsState {
+  return {
+    lastFrameId: 0,
+    lastPresentAt: null,
+    pendingSimMs: 0,
+    frameTimeMs: null,
+    renderCpuMs: null,
+    drawCalls: null,
+    triangles: null,
+    renderPasses: null,
+    worstCurrentMs: 0,
+    worstPreviousMs: 0,
+    worstWindowFrames: 0,
+    lastHitch: null,
+    presentedFrames: 0,
+  };
+}
+
+/** Sum of one frame's phase timings whose names are in `names`. */
+function sumPhases(frame: PerformanceFrame, names: readonly string[]): number {
+  let total = 0;
+  for (const timing of frame.phases) if (names.includes(timing.name)) total += timing.ms;
+  return total;
+}
+
+/** This frame's CPU render submission, or `null` when it was not a
+ *  presentation (no draw happened, so no bracket was recorded). */
+function submissionMs(frame: PerformanceFrame): number | null {
+  for (const timing of frame.phases) if (timing.name === RENDER_SUBMIT_PHASE) return timing.ms;
+  return null;
+}
+
+function ema(previous: number | null, sample: number, alpha: number): number {
+  return previous === null ? sample : previous * (1 - alpha) + sample * alpha;
+}
+
+/**
+ * Fold ONE profiler frame into the accumulator. Pure with respect to time and
+ * randomness — every input is on the frame — which is what makes the whole
+ * derivation testable from synthetic frames with no renderer, no clock and no
+ * game.
+ *
+ * Returns `true` when the frame was a presentation (the readings moved).
+ */
+export function foldProfilerFrame(state: RenderVitalsState, frame: PerformanceFrame): boolean {
+  // Re-publishes and the ring's own re-reads must not double-count. Frame ids
+  // are monotonic for the profiler's whole life, including across `clear()`.
+  if (frame.id <= state.lastFrameId) return false;
+  state.lastFrameId = frame.id;
+
+  // Counters ride whichever frame `reportRender` landed on — see the module
+  // note. `renderPasses !== null` is the marker that a reporter spoke at all;
+  // a frame nobody reported on leaves the previous reading standing rather
+  // than blanking it to a zero that would read as "nothing is drawn".
+  if (frame.render.renderPasses !== null) {
+    state.drawCalls = frame.render.drawCalls;
+    state.triangles = frame.render.triangles;
+    state.renderPasses = frame.render.renderPasses;
+  }
+
+  state.pendingSimMs += sumPhases(frame, SIM_PHASES);
+
+  const renderMs = submissionMs(frame);
+  if (renderMs === null) return false; // a sim substep: its cost is now pending
+
+  const simMs = state.pendingSimMs;
+  state.pendingSimMs = 0;
+  state.presentedFrames += 1;
+  state.renderCpuMs = ema(state.renderCpuMs, renderMs, RENDER_CPU_EMA_ALPHA);
+
+  const previousAt = state.lastPresentAt;
+  state.lastPresentAt = frame.timestamp;
+  // The FIRST presentation has no interval behind it. Everything that needs a
+  // dt (frame time, worst frame, the hitch) waits for the second one; the
+  // alternative is to invent an interval from the profiler's own start, which
+  // would report the mount cost as a frame time forever.
+  if (previousAt === null) return true;
+
+  const dt = frame.timestamp - previousAt;
+  state.frameTimeMs = ema(state.frameTimeMs, dt, FRAME_TIME_EMA_ALPHA);
+
+  if (dt > state.worstCurrentMs) state.worstCurrentMs = dt;
+  state.worstWindowFrames += 1;
+  if (state.worstWindowFrames >= WORST_WINDOW_FRAMES) {
+    state.worstPreviousMs = state.worstCurrentMs;
+    state.worstCurrentMs = 0;
+    state.worstWindowFrames = 0;
+  }
+
+  // Blame the hitch with THIS frame's own measurements: `dt` spans the work
+  // between the two presentations, which is exactly the submission just
+  // measured plus the substeps that ran in between.
+  if (dt >= HITCH_THRESHOLD_MS) state.lastHitch = decomposeHitch(dt, renderMs, simMs);
+
+  return true;
+}
+
+function round(value: number | null, places: number): number | null {
+  if (value === null) return null;
+  const factor = 10 ** places;
+  return Math.round(value * factor) / factor;
+}
+
+/** The provider body — pure over the accumulator. */
+export function readRenderVitals(state: RenderVitalsState): RenderVitalsReading {
+  const frameTimeMs = round(state.frameTimeMs, 2);
+  const worst = Math.max(state.worstCurrentMs, state.worstPreviousMs);
+  return {
+    frameTimeMs,
+    fps: frameTimeMs !== null && frameTimeMs > 0 ? round(1000 / frameTimeMs, 1) : null,
+    drawCalls: state.drawCalls,
+    triangles: state.triangles,
+    renderCpuMs: round(state.renderCpuMs, 2),
+    renderPasses: state.renderPasses,
+    worstFrameMs: state.frameTimeMs === null ? null : round(worst, 2),
+    lastHitch: state.lastHitch,
+    presentedFrames: state.presentedFrames,
+  };
+}
+
+/** What {@link createRenderVitals} hands back. */
+export interface RenderVitals {
+  /** The `render.vitals` provider body. */
+  read(): RenderVitalsReading;
+  /** See the module's ownership note — the ONE path that ends the
+   *  subscription. Idempotent. */
+  dispose(): void;
+}
+
+/**
+ * Attach a fold to a live profiler. `subscribe` fires once per published
+ * frame (and on enabled/recording changes, which the id dedupe absorbs), so
+ * nothing here polls and nothing here owns a timer.
+ */
+export function createRenderVitals(profiler: PerformanceProfiler): RenderVitals {
+  const state = createRenderVitalsState();
+  const unsubscribe = profiler.subscribe(() => {
+    const frame = profiler.getSnapshot().frames.at(-1);
+    if (frame) foldProfilerFrame(state, frame);
+  });
+  let disposed = false;
+  return {
+    read: () => readRenderVitals(state),
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      unsubscribe();
+    },
+  };
+}

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

@@ -0,0 +1,186 @@
+/**
+ * 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 the dev-menu's 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. `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 =
+    `[static-batch] ~${grouped(collapsible)} of ${grouped(drawCalls)} draw calls are the same ` +
+    `handful of draws repeated (${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 the dev menu's 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/render/render-batch-system.ts

@@ -1,6 +1,7 @@
 import * as THREE from 'three';
 import { getUserData } from '../ecs/user-data';
 import type { ResolvedRenderSettings } from './render-settings';
+import { staticBatchSignature } from './structural-signature';
 
 /**
  * Runtime STATIC render-batching (the framework-level transparent perf delivery).
@@ -24,7 +25,15 @@ import type { ResolvedRenderSettings } from './render-settings';
  *     kept in-graph hidden + dirty-synced each frame. A bucket may split into both.
  *
  * Scope / limitations (v1):
- *   - Runs once per scene load (build() is called after loadScene). Entities spawned
+ *   - NOT WIRED: nothing in the engine calls build() — the rendering-scale
+ *     example's render lab is the only driver (via the hosted-module map), and
+ *     no adapter batches automatically. That is settled, not pending: a game's
+ *     production answer is the `static-batch` capability's `<Frozen>`, a
+ *     DECLARED mount-static subtree in the game's own TSX, and `dev/static-
+ *     batch-advisor.ts` is what routes an author to it by measurement. Full-
+ *     auto inference over a scene nobody declared static is what this class
+ *     would need to become, and it was rejected (issue #1503).
+ *   - build() is a one-shot scan of the scene handed to it. Entities spawned
  *     AFTER build do not join a batch; call build() again to re-scan. Removing a batched
  *     source leaves a stale instance until rebuild. (Static scenery is load-time stable.)
  *   - The batch culls as ONE unit (no per-instance frustum culling yet — Tier-2).
@@ -39,24 +48,12 @@ interface Group {
 
 // Structural signature — groups meshes that are VALUE-identical, not object-identical.
 // The engine scene-loader instantiates a fresh geometry+material per entity (no dedup),
-// so keying on .uuid would never batch a real scene. Keying on geometry type+parameters
-// and material type+key-props groups identical authored primitives (e.g. 10k boxes of
-// the same size+color → one batch). Non-primitive geometry (GLTF, no `.parameters`)
-// falls back to uuid → it simply won't group, which is the safe default.
-const geoKey = (g: THREE.BufferGeometry): string => {
-  const params = (g as unknown as { parameters?: object }).parameters;
-  return params ? `${g.type}:${JSON.stringify(params)}` : `uuid:${g.uuid}`;
-};
-const matKey = (m: THREE.Material): string => {
-  const s = m as THREE.MeshStandardMaterial;
-  const col = s.color?.getHexString?.() ?? '';
-  const map = s.map?.uuid ?? '';
-  return `${m.type}:${col}:${s.roughness ?? ''}:${s.metalness ?? ''}:${map}:${m.side}:${m.transparent}:${m.vertexColors}`;
-};
-const SIG = (m: THREE.Mesh): string =>
-  // include shadow flags: meshes with different cast/receive must not share a batch
-  // (the InstancedMesh carries one flag for the whole group).
-  `${geoKey(m.geometry as THREE.BufferGeometry)}|${matKey(m.material as THREE.Material)}|${m.castShadow ? 1 : 0}${m.receiveShadow ? 1 : 0}`;
+// so keying on .uuid would never batch a real scene; a TSX/R3F world writing inline
+// `<meshStandardMaterial>` elements has exactly the same property. That key lives in
+// `render/structural-signature.ts` — ONE owner, shared with the `static-batch`
+// capability's `<Frozen>`, so the two cannot drift into disagreeing about what
+// "the same draw" means. `staticBatchSignature` is this file's original key, moved.
+const SIG = staticBatchSignature;
 
 /** Match Three.js renderer visibility: a hidden ancestor hides the whole subtree. */
 function isEffectivelyVisible(obj: THREE.Object3D): boolean {