@vgai/engine 0.5.7 → 0.5.9

package/dist/dev/static-batch-advisor.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 declare 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 declare 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 declare 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 declare 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;
+}
+/**
+ * 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 declare function decideStaticBatchAdvisory(input: StaticBatchAdvisoryInput): StaticBatchAdvisory | null;
+/**
+ * Emit `advisory` on the console, at most once per page. Answers whether it
+ * warned, so a caller can stop scanning.
+ */
+export declare function warnStaticBatchAdvisory(advisory: StaticBatchAdvisory, 
+/** Injectable so the decision is testable without a console. */
+warn?: (message: string) => void): boolean;
+/** Test-only: forget that the advisory was ever emitted. */
+export declare function __resetStaticBatchAdvisoryForTest(): void;
+//# sourceMappingURL=static-batch-advisor.d.ts.map

package/dist/dev/static-batch-advisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-batch-advisor.d.ts","sourceRoot":"","sources":["../../src/dev/static-batch-advisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE3E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;sDACkD;IAClD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;8BAC0B;IAC1B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;CAC5C;AAQD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,wBAAwB,GAC9B,mBAAmB,GAAG,IAAI,CA+B5B;AAyBD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,mBAAmB;AAC7B,gEAAgE;AAChE,IAAI,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAoB,GAC9C,OAAO,CAKT;AAED,4DAA4D;AAC5D,wBAAgB,iCAAiC,IAAI,IAAI,CAExD"}

package/dist/dev/static-batch-advisor.js

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+/** `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) {
+    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) {
+    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() {
+    return globalThis[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) {
+    // 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, 
+/** Injectable so the decision is testable without a console. */
+warn = warnOnConsole) {
+    if (alreadyWarned())
+        return false;
+    globalThis[WARNED_KEY] = true;
+    warn(advisory.message);
+    return true;
+}
+/** Test-only: forget that the advisory was ever emitted. */
+export function __resetStaticBatchAdvisoryForTest() {
+    globalThis[WARNED_KEY] = undefined;
+}

package/dist/render/render-batch-system.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-batch-system.d.ts","sourceRoot":"","sources":["../../src/render/render-batch-system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAgGhE,qBAAa,iBAAiB;IAU1B,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAVlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAe;IAEpC,OAAO,CAAC,QAAQ,CAA6C;IAE7D,OAAO,CAAC,SAAS,CAAoD;gBAG3D,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,QAAQ,EAAE,sBAAsB;IAM1C,wEAAwE;IACxE,KAAK,IAAI,IAAI;IA0Bb,OAAO,CAAC,SAAS;IAyCjB;;;;;OAKG;IACH,MAAM,IAAI,IAAI;IAyBd;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI;IAStD,kEAAkE;IAClE,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,4DAA4D;IAC5D,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,QAAQ,IAAI,IAAI;CAiBjB"}
+{"version":3,"file":"render-batch-system.d.ts","sourceRoot":"","sources":["../../src/render/render-batch-system.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AA6FhE,qBAAa,iBAAiB;IAU1B,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,QAAQ;IAVlB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAe;IAEpC,OAAO,CAAC,QAAQ,CAA6C;IAE7D,OAAO,CAAC,SAAS,CAAoD;gBAG3D,KAAK,EAAE,KAAK,CAAC,KAAK,EAClB,QAAQ,EAAE,sBAAsB;IAM1C,wEAAwE;IACxE,KAAK,IAAI,IAAI;IA0Bb,OAAO,CAAC,SAAS;IAyCjB;;;;;OAKG;IACH,MAAM,IAAI,IAAI;IAyBd;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI;IAStD,kEAAkE;IAClE,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,4DAA4D;IAC5D,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,QAAQ,IAAI,IAAI;CAiBjB"}

package/dist/render/render-batch-system.js

@@ -1,25 +1,14 @@
 import * as THREE from 'three';
 import { getUserData } from '../ecs/user-data';
+import { staticBatchSignature } from './structural-signature';
 // 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) => {
-    const params = g.parameters;
-    return params ? `${g.type}:${JSON.stringify(params)}` : `uuid:${g.uuid}`;
-};
-const matKey = (m) => {
-    const s = m;
-    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) => 
-// 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)}|${matKey(m.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) {
     let cur = obj;

package/dist/render/structural-signature.d.ts

@@ -0,0 +1,148 @@
+/**
+ * STRUCTURAL IDENTITY AND ELIGIBILITY for static render batching — the one
+ * place that answers "may this draw be collapsed at all?" and "are these two
+ * meshes the same thing drawn twice?".
+ *
+ * Three consumers, which is the whole reason it is a module rather than three
+ * private helpers: `render/render-batch-system.ts` (the engine's own
+ * lab-driven instancer), `dev/render-census.ts`'s structural scan (what the
+ * advisor and `render.families` measure), and the `static-batch` capability's
+ * `<Frozen>` (what a game actually installs). A batcher and the advisor that
+ * routes people to it MUST agree about what is batchable, or the advisor
+ * promises a win the wrapper then declines to take.
+ *
+ * ── THE UUID TRAP, WHICH IS WHY THIS MODULE EXISTS ──────────────────────────
+ * The obvious key for "can these two meshes be drawn as one" is object
+ * identity: same `geometry.uuid`, same `material.uuid`. It is also the key
+ * that silently batches NOTHING in the shape that matters most. A freshly
+ * scaffolded TSX/R3F world writes its materials INLINE —
+ *
+ *     {crates.map((c) => (
+ *       <mesh key={c.id} position={c.at}>
+ *         <boxGeometry args={[1, 1, 1]} />
+ *         <meshStandardMaterial color="#8a6a44" />
+ *       </mesh>
+ *     ))}
+ *
+ * — and every one of those `<meshStandardMaterial>` elements constructs its
+ * OWN `THREE.MeshStandardMaterial`. Five hundred crates are five hundred
+ * distinct uuids describing one identical appearance. A uuid-keyed grouper
+ * reports five hundred families of one, finds nothing to do, and is indistin-
+ * guishable from a correct batcher over an unbatchable scene. The engine's own
+ * scene construction has the same property, which is why
+ * `render/render-batch-system.ts` has keyed on VALUE since it was written.
+ *
+ * So the key here is the STRUCTURE: geometry `type` + its construction
+ * `parameters`, material `type` + the props that decide what the draw looks
+ * like. Two independently constructed `BoxGeometry(1,1,1)` +
+ * `MeshStandardMaterial({color:'#8a6a44'})` pairs are the same draw, and this
+ * module says so.
+ *
+ * ── WHERE VALUE CANNOT ANSWER, IDENTITY IS THE SAFE FALLBACK ────────────────
+ * Twice below, a structural comparison would be a guess, and the answer is
+ * `uuid:` — a key nothing else can equal, so the members simply do not group.
+ * Not grouping costs a draw call; grouping two things that only LOOK alike
+ * renders the wrong picture.
+ *   - geometry with no `.parameters` (a loaded GLTF mesh, a hand-built
+ *     `BufferGeometry`): its vertices are its identity and comparing them is
+ *     not a signature, it is a diff.
+ *   - a shader material ({@link materialMergeSignature} only): its appearance
+ *     lives in shader source and uniforms that no fixed prop list can read.
+ *
+ * ── TWO KEYS, DELIBERATELY ──────────────────────────────────────────────────
+ * {@link staticBatchSignature} is `RenderBatchSystem`'s key, extracted here
+ * unchanged so there is one owner of the answer rather than two that drift.
+ * {@link materialMergeSignature} is STRICTER, and it is what the `static-batch`
+ * capability's `<Frozen>` groups by: that path hands ONE material instance to
+ * a merged/instanced product, so its members must be interchangeable, not
+ * merely similar. The looser key predates it and is kept exactly as it was —
+ * see that constant's own note.
+ */
+import type * as THREE from 'three';
+/**
+ * The `userData` key a node opts OUT of static batching with — the one
+ * declaration that beats every measurement:
+ *
+ *     <group name="Beacons" userData={{ staticBatch: false }}>
+ *
+ * Set on a node, it covers that node's whole subtree (a walker stops there).
+ * It is deliberately `userData` and not a component prop: the thing being
+ * excluded is a three node, and every authoring lane — TSX, a loaded GLTF, a
+ * hand-built graph — can set `userData` on one.
+ */
+export declare const STATIC_BATCH_OPT_OUT_KEY = "staticBatch";
+/**
+ * Why one node may not be collapsed into a batch. `null` from
+ * {@link staticBatchSkipReason} means it may.
+ *
+ * Each of these is a case where a batched draw would render something DIFFERENT
+ * from the originals, not merely a case that is awkward to implement:
+ *  - `instanced` / `batched` — already one draw; swallowing it would flatten
+ *    per-instance transforms the batch does not carry.
+ *  - `skinned` — its vertices are posed by a bone matrix palette every frame;
+ *    baking one pose freezes the character mid-stride.
+ *  - `morph-targets` — same, driven by influences instead of bones.
+ *  - `multi-material` — the geometry's `groups` select a material per range;
+ *    a batch carries one material.
+ *  - `transparent` — blending is order-dependent and three sorts TRANSPARENT
+ *    OBJECTS, not triangles. Collapsing them fixes their relative order to
+ *    whatever the merge happened to write.
+ *  - `opted-out` — see {@link STATIC_BATCH_OPT_OUT_KEY}.
+ */
+export type StaticBatchSkipReason = 'not-a-mesh' | 'instanced' | 'batched' | 'skinned' | 'no-geometry' | 'multi-material' | 'morph-targets' | 'transparent' | 'opted-out';
+/**
+ * Why `node` may not join a static batch, or `null` when it may. Pure, cheap,
+ * and the SINGLE owner of that answer — see the module note for why the
+ * batcher and the advisor cannot each keep their own copy.
+ *
+ * Checks the node itself only. Subtree exclusion (an opted-out ancestor) is
+ * the caller's walk, because the walkers that need this already prune.
+ */
+export declare function staticBatchSkipReason(node: THREE.Object3D): StaticBatchSkipReason | null;
+/**
+ * Geometry identity: construction `type` + `parameters` for the parametric
+ * primitives, object identity for everything else. See the module note.
+ */
+export declare function geometrySignature(geometry: THREE.BufferGeometry): string;
+/**
+ * Material identity as `RenderBatchSystem` has always computed it: type plus
+ * the standard-material props that change the draw.
+ *
+ * FROZEN ON PURPOSE. This is one half of {@link staticBatchSignature}, which
+ * is a live batcher's grouping key; widening or narrowing it silently
+ * regroups that batcher's scenes. New discrimination goes in
+ * {@link materialMergeSignature}, which is free to be stricter because
+ * stricter only ever means "batches less".
+ */
+export declare function materialSignature(material: THREE.Material): string;
+/**
+ * One mesh's batch key: geometry, material, and the shadow flags.
+ *
+ * The shadow flags are part of the key because a batched product carries ONE
+ * `castShadow`/`receiveShadow` pair for every member it swallowed — mixing a
+ * caster and a non-caster into one draw changes the picture.
+ */
+export declare function staticBatchSignature(mesh: THREE.Mesh): string;
+/**
+ * Which vertex attributes a geometry carries, and whether it is indexed —
+ * the compatibility precondition for `mergeGeometries`, which refuses a batch
+ * whose members disagree.
+ *
+ * Item size is in the key too: two geometries can both have `uv` and disagree
+ * about whether it is 2- or 3-component, which merges into silent garbage
+ * rather than a refusal.
+ */
+export declare function geometryLayoutSignature(geometry: THREE.BufferGeometry): string;
+/**
+ * Material identity for a path that will SHARE one material instance between
+ * every member it collapses — stricter than {@link materialSignature}.
+ *
+ * Everything the looser key reads, plus the props that decide the picture
+ * without touching colour/roughness/metalness: opacity and the depth/blend
+ * state, emissive, the remaining standard maps, and the flags that change the
+ * compiled program. A shader material answers with its uuid instead (see the
+ * module note): its appearance is source and uniforms, and there is no honest
+ * fixed-prop reading of it.
+ */
+export declare function materialMergeSignature(material: THREE.Material): string;
+//# sourceMappingURL=structural-signature.d.ts.map

package/dist/render/structural-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-signature.d.ts","sourceRoot":"","sources":["../../src/render/structural-signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,gBAAgB,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,qBAAqB,GAC7B,YAAY,GACZ,WAAW,GACX,SAAS,GACT,SAAS,GACT,aAAa,GACb,gBAAgB,GAChB,eAAe,GACf,aAAa,GACb,WAAW,CAAC;AAWhB;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,GAAG,qBAAqB,GAAG,IAAI,CAYxF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,GAAG,MAAM,CAGxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAG,MAAM,CAKlE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,GAAG,MAAM,CAI7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,GAAG,MAAM,CAM9E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAG,MAAM,CA2BvE"}

package/dist/render/structural-signature.js

@@ -0,0 +1,193 @@
+/**
+ * STRUCTURAL IDENTITY AND ELIGIBILITY for static render batching — the one
+ * place that answers "may this draw be collapsed at all?" and "are these two
+ * meshes the same thing drawn twice?".
+ *
+ * Three consumers, which is the whole reason it is a module rather than three
+ * private helpers: `render/render-batch-system.ts` (the engine's own
+ * lab-driven instancer), `dev/render-census.ts`'s structural scan (what the
+ * advisor and `render.families` measure), and the `static-batch` capability's
+ * `<Frozen>` (what a game actually installs). A batcher and the advisor that
+ * routes people to it MUST agree about what is batchable, or the advisor
+ * promises a win the wrapper then declines to take.
+ *
+ * ── THE UUID TRAP, WHICH IS WHY THIS MODULE EXISTS ──────────────────────────
+ * The obvious key for "can these two meshes be drawn as one" is object
+ * identity: same `geometry.uuid`, same `material.uuid`. It is also the key
+ * that silently batches NOTHING in the shape that matters most. A freshly
+ * scaffolded TSX/R3F world writes its materials INLINE —
+ *
+ *     {crates.map((c) => (
+ *       <mesh key={c.id} position={c.at}>
+ *         <boxGeometry args={[1, 1, 1]} />
+ *         <meshStandardMaterial color="#8a6a44" />
+ *       </mesh>
+ *     ))}
+ *
+ * — and every one of those `<meshStandardMaterial>` elements constructs its
+ * OWN `THREE.MeshStandardMaterial`. Five hundred crates are five hundred
+ * distinct uuids describing one identical appearance. A uuid-keyed grouper
+ * reports five hundred families of one, finds nothing to do, and is indistin-
+ * guishable from a correct batcher over an unbatchable scene. The engine's own
+ * scene construction has the same property, which is why
+ * `render/render-batch-system.ts` has keyed on VALUE since it was written.
+ *
+ * So the key here is the STRUCTURE: geometry `type` + its construction
+ * `parameters`, material `type` + the props that decide what the draw looks
+ * like. Two independently constructed `BoxGeometry(1,1,1)` +
+ * `MeshStandardMaterial({color:'#8a6a44'})` pairs are the same draw, and this
+ * module says so.
+ *
+ * ── WHERE VALUE CANNOT ANSWER, IDENTITY IS THE SAFE FALLBACK ────────────────
+ * Twice below, a structural comparison would be a guess, and the answer is
+ * `uuid:` — a key nothing else can equal, so the members simply do not group.
+ * Not grouping costs a draw call; grouping two things that only LOOK alike
+ * renders the wrong picture.
+ *   - geometry with no `.parameters` (a loaded GLTF mesh, a hand-built
+ *     `BufferGeometry`): its vertices are its identity and comparing them is
+ *     not a signature, it is a diff.
+ *   - a shader material ({@link materialMergeSignature} only): its appearance
+ *     lives in shader source and uniforms that no fixed prop list can read.
+ *
+ * ── TWO KEYS, DELIBERATELY ──────────────────────────────────────────────────
+ * {@link staticBatchSignature} is `RenderBatchSystem`'s key, extracted here
+ * unchanged so there is one owner of the answer rather than two that drift.
+ * {@link materialMergeSignature} is STRICTER, and it is what the `static-batch`
+ * capability's `<Frozen>` groups by: that path hands ONE material instance to
+ * a merged/instanced product, so its members must be interchangeable, not
+ * merely similar. The looser key predates it and is kept exactly as it was —
+ * see that constant's own note.
+ */
+/**
+ * The `userData` key a node opts OUT of static batching with — the one
+ * declaration that beats every measurement:
+ *
+ *     <group name="Beacons" userData={{ staticBatch: false }}>
+ *
+ * Set on a node, it covers that node's whole subtree (a walker stops there).
+ * It is deliberately `userData` and not a component prop: the thing being
+ * excluded is a three node, and every authoring lane — TSX, a loaded GLTF, a
+ * hand-built graph — can set `userData` on one.
+ */
+export const STATIC_BATCH_OPT_OUT_KEY = 'staticBatch';
+/**
+ * Why `node` may not join a static batch, or `null` when it may. Pure, cheap,
+ * and the SINGLE owner of that answer — see the module note for why the
+ * batcher and the advisor cannot each keep their own copy.
+ *
+ * Checks the node itself only. Subtree exclusion (an opted-out ancestor) is
+ * the caller's walk, because the walkers that need this already prune.
+ */
+export function staticBatchSkipReason(node) {
+    if (node.userData?.[STATIC_BATCH_OPT_OUT_KEY] === false)
+        return 'opted-out';
+    const mesh = node;
+    if (mesh.isInstancedMesh)
+        return 'instanced';
+    if (mesh.isBatchedMesh)
+        return 'batched';
+    if (mesh.isSkinnedMesh)
+        return 'skinned';
+    if (!mesh.isMesh)
+        return 'not-a-mesh';
+    if (!mesh.geometry || !mesh.material)
+        return 'no-geometry';
+    if (Array.isArray(mesh.material))
+        return 'multi-material';
+    if (Object.keys(mesh.geometry.morphAttributes).length > 0)
+        return 'morph-targets';
+    if (mesh.material.transparent)
+        return 'transparent';
+    return null;
+}
+/**
+ * Geometry identity: construction `type` + `parameters` for the parametric
+ * primitives, object identity for everything else. See the module note.
+ */
+export function geometrySignature(geometry) {
+    const params = geometry.parameters;
+    return params ? `${geometry.type}:${JSON.stringify(params)}` : `uuid:${geometry.uuid}`;
+}
+/**
+ * Material identity as `RenderBatchSystem` has always computed it: type plus
+ * the standard-material props that change the draw.
+ *
+ * FROZEN ON PURPOSE. This is one half of {@link staticBatchSignature}, which
+ * is a live batcher's grouping key; widening or narrowing it silently
+ * regroups that batcher's scenes. New discrimination goes in
+ * {@link materialMergeSignature}, which is free to be stricter because
+ * stricter only ever means "batches less".
+ */
+export function materialSignature(material) {
+    const standard = material;
+    const color = standard.color?.getHexString?.() ?? '';
+    const map = standard.map?.uuid ?? '';
+    return `${material.type}:${color}:${standard.roughness ?? ''}:${standard.metalness ?? ''}:${map}:${material.side}:${material.transparent}:${material.vertexColors}`;
+}
+/**
+ * One mesh's batch key: geometry, material, and the shadow flags.
+ *
+ * The shadow flags are part of the key because a batched product carries ONE
+ * `castShadow`/`receiveShadow` pair for every member it swallowed — mixing a
+ * caster and a non-caster into one draw changes the picture.
+ */
+export function staticBatchSignature(mesh) {
+    const geometry = mesh.geometry;
+    const material = mesh.material;
+    return `${geometrySignature(geometry)}|${materialSignature(material)}|${mesh.castShadow ? 1 : 0}${mesh.receiveShadow ? 1 : 0}`;
+}
+/**
+ * Which vertex attributes a geometry carries, and whether it is indexed —
+ * the compatibility precondition for `mergeGeometries`, which refuses a batch
+ * whose members disagree.
+ *
+ * Item size is in the key too: two geometries can both have `uv` and disagree
+ * about whether it is 2- or 3-component, which merges into silent garbage
+ * rather than a refusal.
+ */
+export function geometryLayoutSignature(geometry) {
+    const attributes = Object.keys(geometry.attributes)
+        .sort()
+        .map((name) => `${name}:${geometry.attributes[name]?.itemSize ?? '?'}`)
+        .join(',');
+    return `${attributes}${geometry.getIndex() ? '|i' : ''}`;
+}
+/**
+ * Material identity for a path that will SHARE one material instance between
+ * every member it collapses — stricter than {@link materialSignature}.
+ *
+ * Everything the looser key reads, plus the props that decide the picture
+ * without touching colour/roughness/metalness: opacity and the depth/blend
+ * state, emissive, the remaining standard maps, and the flags that change the
+ * compiled program. A shader material answers with its uuid instead (see the
+ * module note): its appearance is source and uniforms, and there is no honest
+ * fixed-prop reading of it.
+ */
+export function materialMergeSignature(material) {
+    const shader = material;
+    if (shader.isShaderMaterial || shader.isRawShaderMaterial)
+        return `uuid:${material.uuid}`;
+    const rich = material;
+    const maps = [rich.normalMap, rich.aoMap, rich.emissiveMap, rich.roughnessMap, rich.metalnessMap]
+        .map((map) => map?.uuid ?? '')
+        .join(',');
+    // A material with a patched `onBeforeCompile` declares its variant through
+    // this hook (that is what three itself keys its program cache on), so a
+    // non-empty value discriminates here too.
+    const program = material.customProgramCacheKey?.() ?? '';
+    return [
+        materialSignature(material),
+        material.opacity,
+        material.depthWrite,
+        material.depthTest,
+        material.alphaTest,
+        material.blending,
+        material.toneMapped,
+        material.visible,
+        rich.emissive?.getHexString?.() ?? '',
+        rich.flatShading ?? '',
+        rich.wireframe ?? '',
+        maps,
+        program,
+    ].join('|');
+}

package/dist/runtime/debug-registry.d.ts

@@ -4,8 +4,8 @@
  * SAME registry via {@link DebugRegistry.forRoot}, so a name a game registers is
  * visible (and name-collision-checked) across every world, not just the one that
  * registered it. `createGame` (`runtime/game.ts`) constructs the registry
- * alongside the state bridge and files it in the `Game -> DebugRegistry` WeakMap
- * this module owns; later consumers (the react `useDebugProvider`/
+ * alongside the state bridge and files it in a non-enumerable game-scoped slot;
+ * later consumers (the react `useDebugProvider`/
  * `useDebugCommand` hooks, editor panels) reach it via {@link getDebugRegistry}
  * rather than threading it through every call site.
  *