@vgai/engine 0.5.8 → 0.5.9

package/dist/dev/register-render-vitals.js

@@ -0,0 +1,182 @@
+/**
+ * THE DOOR for live render vitals: one provider and four commands on the
+ * game's own debug registry (`runtime/debug-registry.ts`), so a running game
+ * explains its own frame cost through the SAME seam every other reading and
+ * verb uses — `game.state('render.vitals')` / `game.command('render.census')`
+ * through `vgai eval`, and `game.providers()`/`game.commands()` to discover
+ * them without being told they exist.
+ *
+ * Engine-owned and first-party, seeded by the three adapter
+ * (`adapter/setup-three-root-adapter.ts`) at the same spot it seeds
+ * `systemAdapters.renderDebug` — a game writes nothing to get these, and there
+ * is no capability to install. The measurement half is `dev/render-vitals.ts`
+ * (derived entirely from profiler frames); the address-book half is
+ * `dev/render-census.ts` (pure walks over the live scene). This module is only
+ * the wiring between them and the registry.
+ *
+ * ── THE READING AND THE EXPERIMENTS ─────────────────────────────────────────
+ * A number alone does not route an investigation, so each command is the
+ * experiment that turns one reading into an address:
+ *  - `render.census`   — which subtree owns the meshes and triangles, with a
+ *                        drill-down argument;
+ *  - `render.families` — which meshes are identical enough to instance;
+ *  - `render.toggle`   — hide a subtree and watch the stat move (the only way
+ *                        to ATTRIBUTE cost rather than infer it);
+ *  - `render.dpr`      — change the pixel count, which separates GPU fill cost
+ *                        from vsync idle: render CPU that does not move when
+ *                        the drawing buffer halves was never fill-bound.
+ *
+ * ── GATING ──────────────────────────────────────────────────────────────────
+ * The caller gates. `setup-three-root-adapter.ts` calls this only under
+ * `devLayersEnabled()` (`runtime/dev-layers.ts` — the ONE owner of "is this a
+ * dev context"), so a ship build registers nothing and pays nothing.
+ *
+ * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
+ * OWNER: {@link registerRenderVitals}'s caller. It allocates one
+ * {@link RenderVitals} fold (which owns one `profiler.subscribe`), a SECOND,
+ * self-ending `profiler.subscribe` for the static-batch advisory, and the
+ * registrations, whose provenance is the caller's `worldId`. SHARERS: none.
+ * TEARDOWN: the returned `dispose()` — the ONE path that ends both
+ * subscriptions. The REGISTRATIONS are ended by the registry's own
+ * `strip(worldId)`, which the adapter already runs on stop and warm restart;
+ * this module never strips, because a blind strip here would take the game's
+ * registrations with it.
+ */
+import * as THREE from 'three';
+import { z } from 'zod';
+import { findByName, meshFamilies, sceneCensus, structuralBatchScan } from './render-census';
+import { createRenderVitals } 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';
+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) {
+    const { registry, worldId, profiler, scene, renderer } = deps;
+    const taken = registry.adapter
+        .providers()
+        .some((provider) => provider.name === RENDER_VITALS_PROVIDER);
+    if (taken)
+        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 = null;
+    let advised = false;
+    const advisorTick = () => {
+        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();
+        },
+    };
+}

package/dist/dev/render-census.d.ts

@@ -0,0 +1,135 @@
+/**
+ * THE ADDRESS BOOK behind the render vitals (`dev/render-vitals.ts`): which
+ * subtree owns the draw calls, and which meshes are identical enough to
+ * instance. A draw-call count with no address is a symptom you cannot act on.
+ *
+ * Pure functions over a live `THREE.Object3D` — no renderer, no profiler, no
+ * game. They are what the `render.census` / `render.families` debug commands
+ * run; keeping them here (rather than inline in the adapter) is what lets a
+ * headless test build a scene by hand and check the arithmetic.
+ *
+ * ── WHAT "VISIBLE" MEANS HERE, AND WHY IT IS A WALK ─────────────────────────
+ * Visibility in three is HIERARCHICAL: a hidden parent hides its whole
+ * subtree, and `Object3D.traverse` cannot prune. So these walk manually and
+ * stop descending at an invisible node. That is not a detail — `render.toggle`
+ * works by hiding a PARENT, and a census that kept counting the children under
+ * it would report that nothing changed.
+ *
+ * ── TWO FAMILY SCANS, AND WHY BOTH ──────────────────────────────────────────
+ * {@link meshFamilies} keys on object IDENTITY: meshes sharing one geometry
+ * instance and one material instance (`uuid`) — exactly the precondition for
+ * collapsing them into a bare `InstancedMesh` as they stand. It deliberately
+ * does not compare material PARAMETERS.
+ *
+ * {@link structuralBatchScan} keys on STRUCTURE (`render/structural-
+ * signature.ts`): meshes that are the same DRAW, however many distinct
+ * material objects describe it. A project that writes a material per mesh —
+ * which is what inline `<meshStandardMaterial>` in a TSX world does, i.e. what
+ * every fresh scaffold does — reads as all families-of-one under the first
+ * scan and as one big collapsible family under the second. Both readings are
+ * true; they answer different questions, and only the second one routes an
+ * author to the fix (`dev/static-batch-advisor.ts`).
+ *
+ * Nothing here assumes a project interns its materials or that its world is
+ * static — the STATIC half is a claim only the author can make, which is why
+ * the advisory asks rather than acts.
+ */
+import type * as THREE from 'three';
+/** How many rows a census/family report carries. A shortlist is actionable;
+ *  a full dump through a JSON relay is a wall of text nobody reads. */
+export declare const CENSUS_ROW_LIMIT = 40;
+export declare const FAMILY_ROW_LIMIT = 30;
+/** One addressable subtree's share of the frame. */
+export interface CensusRow {
+    /** The node's own name, or a stable placeholder — this is the string
+     *  `render.census`/`render.toggle` take as their drill-down argument, so an
+     *  unnamed node is honestly reported as unaddressable rather than given an
+     *  invented name that would not resolve. */
+    readonly name: string;
+    readonly meshes: number;
+    readonly triangles: number;
+}
+export interface CensusReport {
+    /** The subtree this census covers (`'(scene)'` for the whole world). */
+    readonly root: string;
+    readonly totalMeshes: number;
+    readonly totalTriangles: number;
+    /** How many rows exist in total, so a truncated report says so out loud
+     *  instead of reading as complete. */
+    readonly subtreeCount: number;
+    /** Heaviest first, capped at {@link CENSUS_ROW_LIMIT}. */
+    readonly subtrees: readonly CensusRow[];
+}
+/**
+ * Tally visible meshes and triangles per direct child of `root`. Pure.
+ *
+ * One level, deliberately: the report is a set of addresses to drill into
+ * with the same command, and a recursive dump is not something you can act on
+ * one step at a time. `root` itself contributes its own meshes under its own
+ * name when it has any.
+ */
+export declare function sceneCensus(root: THREE.Object3D, rootLabel?: string): CensusReport;
+/** First node named `name` in `root`'s subtree, or `null`. Depth-first, so the
+ *  shallowest match under an ordinary hierarchy wins. */
+export declare function findByName(root: THREE.Object3D, name: string): THREE.Object3D | null;
+/** One (geometry, material) identity and how many meshes share it. */
+export interface FamilyRow {
+    /** How many meshes share this identity — the instancing win, minus one. */
+    readonly meshes: number;
+    /** Triangles ONE member submits. */
+    readonly triangles: number;
+    /** A representative address (`parent/child`), so the row is findable. */
+    readonly example: string;
+}
+export interface FamilyReport {
+    /** Visible, non-instanced meshes considered. `InstancedMesh`es are excluded:
+     *  they are already the thing this report recommends becoming. */
+    readonly plainMeshes: number;
+    readonly familyCount: number;
+    /** Largest first, capped at {@link FAMILY_ROW_LIMIT}. */
+    readonly top: readonly FamilyRow[];
+    /** How many of {@link plainMeshes} the reported rows cover — the honest
+     *  headroom figure, so a long tail is not mistaken for a short one. */
+    readonly meshesInTop: number;
+}
+/** Group visible non-instanced meshes by (geometry, material) identity. Pure.
+ *  See the module note for what identity does and does not assume. */
+export declare function meshFamilies(root: THREE.Object3D): FamilyReport;
+/** One top-level subtree's share of the collapsible meshes — the ADDRESS the
+ *  advisory names, so the fix is a wrapper someone can actually place. */
+export interface StructuralSubtreeRow {
+    readonly name: string;
+    readonly collapsible: number;
+}
+/** What {@link structuralBatchScan} answers with. A {@link FamilyReport} whose
+ *  families are keyed by STRUCTURE, plus the two figures the advisory needs. */
+export interface StructuralBatchReport extends FamilyReport {
+    /** Meshes sitting in a family of two or more — what would collapse. The
+     *  saving is a little less than this (each family leaves one product
+     *  behind), which is why the advisory says "~". */
+    readonly collapsible: number;
+    /** Meshes the batcher would REFUSE, by reason — the honest other half. A
+     *  scene of 4,000 transparent quads has no draw-call diet available, and a
+     *  scan that reported only the upside would send an author to a wrapper
+     *  that declines every member. */
+    readonly skipped: Readonly<Record<string, number>>;
+    /** Collapsible meshes per direct child of the scanned root, largest first. */
+    readonly bySubtree: readonly StructuralSubtreeRow[];
+}
+/**
+ * Group visible meshes by STRUCTURAL identity — the same key the batchers use
+ * (`render/structural-signature.ts`), so this measures what `<Frozen>` would
+ * actually do rather than what a uuid comparison can see.
+ *
+ * This is the companion to {@link meshFamilies}, not a replacement, and the
+ * difference between the two is the finding: `meshFamilies` asks "which meshes
+ * SHARE a geometry and material object", which is what a bare `InstancedMesh`
+ * needs; this asks "which meshes are the same draw", which is what a merging
+ * batcher needs. On a freshly scaffolded world writing inline materials the
+ * first reports families of one and the second reports the win — see the uuid
+ * trap in `render/structural-signature.ts`.
+ *
+ * Pure. One walk, plus a tally.
+ */
+export declare function structuralBatchScan(root: THREE.Object3D): StructuralBatchReport;
+//# sourceMappingURL=render-census.d.ts.map

package/dist/dev/render-census.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-census.d.ts","sourceRoot":"","sources":["../../src/dev/render-census.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC;uEACuE;AACvE,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAyCnC,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB;;;gDAG4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;0CACsC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;CACzC;AAID;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,SAAY,GAAG,YAAY,CA2CrF;AAED;yDACyD;AACzD,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,GAAG,IAAI,CAOpF;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B;sEACkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,SAAS,SAAS,EAAE,CAAC;IACnC;2EACuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;sEACsE;AACtE,wBAAgB,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,GAAG,YAAY,CAkC/D;AAED;0EAC0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;gFACgF;AAChF,MAAM,WAAW,qBAAsB,SAAQ,YAAY;IACzD;;uDAEmD;IACnD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;sCAGkC;IAClC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACrD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,GAAG,qBAAqB,CA+E/E"}

package/dist/dev/render-census.js

@@ -0,0 +1,257 @@
+/**
+ * THE ADDRESS BOOK behind the render vitals (`dev/render-vitals.ts`): which
+ * subtree owns the draw calls, and which meshes are identical enough to
+ * instance. A draw-call count with no address is a symptom you cannot act on.
+ *
+ * Pure functions over a live `THREE.Object3D` — no renderer, no profiler, no
+ * game. They are what the `render.census` / `render.families` debug commands
+ * run; keeping them here (rather than inline in the adapter) is what lets a
+ * headless test build a scene by hand and check the arithmetic.
+ *
+ * ── WHAT "VISIBLE" MEANS HERE, AND WHY IT IS A WALK ─────────────────────────
+ * Visibility in three is HIERARCHICAL: a hidden parent hides its whole
+ * subtree, and `Object3D.traverse` cannot prune. So these walk manually and
+ * stop descending at an invisible node. That is not a detail — `render.toggle`
+ * works by hiding a PARENT, and a census that kept counting the children under
+ * it would report that nothing changed.
+ *
+ * ── TWO FAMILY SCANS, AND WHY BOTH ──────────────────────────────────────────
+ * {@link meshFamilies} keys on object IDENTITY: meshes sharing one geometry
+ * instance and one material instance (`uuid`) — exactly the precondition for
+ * collapsing them into a bare `InstancedMesh` as they stand. It deliberately
+ * does not compare material PARAMETERS.
+ *
+ * {@link structuralBatchScan} keys on STRUCTURE (`render/structural-
+ * signature.ts`): meshes that are the same DRAW, however many distinct
+ * material objects describe it. A project that writes a material per mesh —
+ * which is what inline `<meshStandardMaterial>` in a TSX world does, i.e. what
+ * every fresh scaffold does — reads as all families-of-one under the first
+ * scan and as one big collapsible family under the second. Both readings are
+ * true; they answer different questions, and only the second one routes an
+ * author to the fix (`dev/static-batch-advisor.ts`).
+ *
+ * Nothing here assumes a project interns its materials or that its world is
+ * static — the STATIC half is a claim only the author can make, which is why
+ * the advisory asks rather than acts.
+ */
+import { materialMergeSignature, staticBatchSkipReason } from '../render/structural-signature';
+/** How many rows a census/family report carries. A shortlist is actionable;
+ *  a full dump through a JSON relay is a wall of text nobody reads. */
+export const CENSUS_ROW_LIMIT = 40;
+export const FAMILY_ROW_LIMIT = 30;
+function asMesh(node) {
+    const mesh = node;
+    return mesh.isMesh || mesh.isSkinnedMesh ? mesh : null;
+}
+/** Triangles one mesh submits: its geometry's own count times its instance
+ *  count. Non-indexed geometry falls back to the position attribute; a
+ *  geometry with neither contributes 0 rather than a guess. */
+function triangleCount(mesh) {
+    const geometry = mesh.geometry;
+    if (!geometry)
+        return 0;
+    const index = geometry.getIndex?.() ?? null;
+    const position = geometry.getAttribute?.('position') ?? null;
+    const vertices = index ? index.count : (position?.count ?? 0);
+    const instances = mesh.isInstancedMesh ? (mesh.count ?? 1) : 1;
+    return Math.round(vertices / 3) * instances;
+}
+/** Walk `node` and its visible descendants, calling `visit` for every visible
+ *  mesh. Stops at an invisible node — see the module note. */
+function walkVisibleMeshes(node, visit) {
+    if (!node.visible)
+        return;
+    const mesh = asMesh(node);
+    if (mesh)
+        visit(mesh);
+    for (const child of node.children)
+        walkVisibleMeshes(child, visit);
+}
+const UNNAMED = '(unnamed)';
+/**
+ * Tally visible meshes and triangles per direct child of `root`. Pure.
+ *
+ * One level, deliberately: the report is a set of addresses to drill into
+ * with the same command, and a recursive dump is not something you can act on
+ * one step at a time. `root` itself contributes its own meshes under its own
+ * name when it has any.
+ */
+export function sceneCensus(root, rootLabel = '(scene)') {
+    const rows = new Map();
+    let totalMeshes = 0;
+    let totalTriangles = 0;
+    if (!root.visible) {
+        return { root: rootLabel, totalMeshes: 0, totalTriangles: 0, subtreeCount: 0, subtrees: [] };
+    }
+    const tally = (key, node) => {
+        walkVisibleMeshes(node, (mesh) => {
+            const triangles = triangleCount(mesh);
+            const row = rows.get(key) ?? { meshes: 0, triangles: 0 };
+            row.meshes += 1;
+            row.triangles += triangles;
+            rows.set(key, row);
+            totalMeshes += 1;
+            totalTriangles += triangles;
+        });
+    };
+    // `root`'s own mesh, if it is one, is charged to `root` — not silently
+    // dropped because the grouping key is "direct child".
+    const selfMesh = asMesh(root);
+    if (selfMesh) {
+        const triangles = triangleCount(selfMesh);
+        rows.set(root.name || rootLabel, { meshes: 1, triangles });
+        totalMeshes += 1;
+        totalTriangles += triangles;
+    }
+    for (const child of root.children)
+        tally(child.name || UNNAMED, child);
+    const sorted = [...rows.entries()]
+        .map(([name, row]) => ({ name, meshes: row.meshes, triangles: row.triangles }))
+        .sort((a, b) => b.triangles - a.triangles || b.meshes - a.meshes);
+    return {
+        root: rootLabel,
+        totalMeshes,
+        totalTriangles,
+        subtreeCount: sorted.length,
+        subtrees: sorted.slice(0, CENSUS_ROW_LIMIT),
+    };
+}
+/** First node named `name` in `root`'s subtree, or `null`. Depth-first, so the
+ *  shallowest match under an ordinary hierarchy wins. */
+export function findByName(root, name) {
+    if (root.name === name)
+        return root;
+    for (const child of root.children) {
+        const hit = findByName(child, name);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/** Group visible non-instanced meshes by (geometry, material) identity. Pure.
+ *  See the module note for what identity does and does not assume. */
+export function meshFamilies(root) {
+    const families = new Map();
+    let plainMeshes = 0;
+    walkVisibleMeshes(root, (mesh) => {
+        if (mesh.isInstancedMesh)
+            return;
+        const geometry = mesh.geometry;
+        if (!geometry)
+            return;
+        const material = mesh.material;
+        const materialKey = Array.isArray(material)
+            ? material.map((entry) => entry.uuid).join('+')
+            : (material?.uuid ?? 'none');
+        const key = `${geometry.uuid}/${materialKey}`;
+        plainMeshes += 1;
+        const existing = families.get(key);
+        if (existing) {
+            existing.meshes += 1;
+            return;
+        }
+        families.set(key, {
+            meshes: 1,
+            triangles: triangleCount(mesh),
+            example: `${mesh.parent?.name || UNNAMED}/${mesh.name || UNNAMED}`,
+        });
+    });
+    const sorted = [...families.values()].sort((a, b) => b.meshes - a.meshes);
+    const top = sorted.slice(0, FAMILY_ROW_LIMIT);
+    return {
+        plainMeshes,
+        familyCount: sorted.length,
+        top,
+        meshesInTop: top.reduce((total, row) => total + row.meshes, 0),
+    };
+}
+/**
+ * Group visible meshes by STRUCTURAL identity — the same key the batchers use
+ * (`render/structural-signature.ts`), so this measures what `<Frozen>` would
+ * actually do rather than what a uuid comparison can see.
+ *
+ * This is the companion to {@link meshFamilies}, not a replacement, and the
+ * difference between the two is the finding: `meshFamilies` asks "which meshes
+ * SHARE a geometry and material object", which is what a bare `InstancedMesh`
+ * needs; this asks "which meshes are the same draw", which is what a merging
+ * batcher needs. On a freshly scaffolded world writing inline materials the
+ * first reports families of one and the second reports the win — see the uuid
+ * trap in `render/structural-signature.ts`.
+ *
+ * Pure. One walk, plus a tally.
+ */
+export function structuralBatchScan(root) {
+    const families = new Map();
+    const skipped = {};
+    // Which subtree each candidate sits under, kept per mesh so attribution can
+    // wait until the families are known (a family of one is not collapsible, and
+    // charging its member to a subtree would inflate that subtree's row).
+    const members = [];
+    let plainMeshes = 0;
+    /** One node, no recursion. Answers `false` when its subtree must be pruned. */
+    const visit = (node, subtree) => {
+        if (!node.visible)
+            return false;
+        const reason = staticBatchSkipReason(node);
+        if (reason === 'opted-out') {
+            skipped['opted-out'] = (skipped['opted-out'] ?? 0) + 1;
+            return false; // an opt-out covers its whole subtree
+        }
+        if (reason === null) {
+            const mesh = node;
+            const material = mesh.material;
+            const key = `${materialMergeSignature(material)}|${node.castShadow ? 1 : 0}${node.receiveShadow ? 1 : 0}`;
+            plainMeshes += 1;
+            members.push({ key, subtree });
+            const existing = families.get(key);
+            if (existing)
+                existing.meshes += 1;
+            else {
+                families.set(key, {
+                    meshes: 1,
+                    triangles: triangleCount(mesh),
+                    example: `${node.parent?.name || UNNAMED}/${node.name || UNNAMED}`,
+                });
+            }
+        }
+        else if (reason !== 'not-a-mesh') {
+            skipped[reason] = (skipped[reason] ?? 0) + 1;
+        }
+        return true;
+    };
+    const scan = (node, subtree) => {
+        if (!visit(node, subtree))
+            return;
+        for (const child of node.children)
+            scan(child, subtree);
+    };
+    // `root`'s own mesh, if it is one, is charged to `root` — the same rule
+    // `sceneCensus` uses, so the two reports address the same graph.
+    if (visit(root, root.name || UNNAMED)) {
+        for (const child of root.children)
+            scan(child, child.name || UNNAMED);
+    }
+    const collapsibleKeys = new Set([...families.entries()].filter(([, family]) => family.meshes >= 2).map(([key]) => key));
+    const perSubtree = new Map();
+    let collapsible = 0;
+    for (const member of members) {
+        if (!collapsibleKeys.has(member.key))
+            continue;
+        collapsible += 1;
+        perSubtree.set(member.subtree, (perSubtree.get(member.subtree) ?? 0) + 1);
+    }
+    const sorted = [...families.values()].sort((a, b) => b.meshes - a.meshes);
+    const top = sorted.slice(0, FAMILY_ROW_LIMIT);
+    return {
+        plainMeshes,
+        familyCount: sorted.length,
+        top,
+        meshesInTop: top.reduce((total, row) => total + row.meshes, 0),
+        collapsible,
+        skipped,
+        bySubtree: [...perSubtree.entries()]
+            .map(([name, count]) => ({ name, collapsible: count }))
+            .sort((a, b) => b.collapsible - a.collapsible)
+            .slice(0, CENSUS_ROW_LIMIT),
+    };
+}