@vgai/engine 0.5.5 → 0.5.6

package/dist/dev/performance-profiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-profiler.d.ts","sourceRoot":"","sources":["../../src/dev/performance-profiler.ts"],"names":[],"mappings":"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"}

package/dist/dev/performance-profiler.js

@@ -0,0 +1,215 @@
+const now = () => globalThis.performance?.now() ?? Date.now();
+function percentile(values, fraction) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * fraction))] ?? 0;
+}
+/** Game-owned, bounded external store for browser-native performance diagnostics. */
+export function createPerformanceProfiler(initiallyEnabled = false) {
+    const listeners = new Set();
+    const frames = [];
+    const currentPhases = new Map();
+    const currentSystems = new Map();
+    const currentComponents = new Map();
+    // Per-frame span logs (W4b) — cleared each beginFrame, snapshotted into the
+    // frame at endFrame. Distinct from the accumulate-by-name aggregate maps
+    // above (which back the cross-frame snapshot rollups): these preserve every
+    // individual invocation and its measured start offset, for the trace.
+    let frameSystems = [];
+    let frameComponents = [];
+    let enabled = initiallyEnabled;
+    let recording = false;
+    let frameId = 0;
+    let frameStart = 0;
+    let lastFrameStart = 0;
+    let phaseStart = 0;
+    let systemStart = 0;
+    let componentStart = 0;
+    let render = {
+        gpuMs: null,
+        drawCalls: 0,
+        triangles: 0,
+        geometries: 0,
+        textures: 0,
+    };
+    let snapshot = {
+        enabled,
+        recording,
+        fps: 0,
+        cpuMs: 0,
+        p95Ms: 0,
+        p99Ms: 0,
+        frames,
+        phases: [],
+        systems: [],
+        components: [],
+        render,
+    };
+    function publish() {
+        const latest = frames.at(-1);
+        const intervals = frames.map((frame) => frame.intervalMs).filter((value) => value > 0);
+        snapshot = {
+            enabled,
+            recording,
+            fps: latest?.intervalMs ? 1000 / latest.intervalMs : 0,
+            cpuMs: latest?.cpuMs ?? 0,
+            p95Ms: percentile(intervals, 0.95),
+            p99Ms: percentile(intervals, 0.99),
+            frames,
+            phases: latest?.phases ?? [],
+            systems: [...currentSystems].map(([name, ms]) => ({ name, ms })).sort((a, b) => b.ms - a.ms),
+            components: [...currentComponents]
+                .map(([name, ms]) => ({ name, ms }))
+                .sort((a, b) => b.ms - a.ms),
+            render,
+        };
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        get enabled() {
+            return enabled;
+        },
+        set enabled(value) {
+            if (enabled === value)
+                return;
+            enabled = value;
+            publish();
+        },
+        get recording() {
+            return recording;
+        },
+        startRecording() {
+            enabled = true;
+            recording = true;
+            frames.length = 0;
+            publish();
+        },
+        stopRecording() {
+            recording = false;
+            publish();
+        },
+        clear() {
+            frames.length = 0;
+            publish();
+        },
+        beginFrame() {
+            if (!enabled)
+                return;
+            currentPhases.clear();
+            currentSystems.clear();
+            currentComponents.clear();
+            frameSystems = [];
+            frameComponents = [];
+            render = { gpuMs: null, drawCalls: 0, triangles: 0, geometries: 0, textures: 0 };
+            frameStart = now();
+        },
+        beginPhase() {
+            if (!enabled)
+                return;
+            phaseStart = now();
+        },
+        endPhase(name) {
+            if (!enabled)
+                return;
+            const elapsed = now() - phaseStart;
+            const existing = currentPhases.get(name);
+            // Accumulate ms across re-entries of the same phase, but keep the FIRST
+            // measured start offset (earliest entry) as the span's startMs.
+            currentPhases.set(name, {
+                ms: (existing?.ms ?? 0) + elapsed,
+                startMs: existing?.startMs ?? phaseStart - frameStart,
+            });
+            if (recording)
+                performance.measure(`vgai.phase.${name}`, { start: phaseStart, duration: elapsed });
+        },
+        systemObserver: {
+            beginSystem() {
+                if (!enabled)
+                    return;
+                systemStart = now();
+            },
+            endSystem(scope, phase, name) {
+                if (!enabled)
+                    return;
+                const end = now();
+                const key = `${scope} / ${phase} / ${name}`;
+                currentSystems.set(key, (currentSystems.get(key) ?? 0) + end - systemStart);
+                frameSystems.push({
+                    name: key,
+                    phase,
+                    startMs: systemStart - frameStart,
+                    ms: end - systemStart,
+                });
+            },
+        },
+        beginComponent() {
+            if (!recording)
+                return;
+            componentStart = now();
+        },
+        endComponent(name, phase = '') {
+            if (!recording)
+                return;
+            const end = now();
+            currentComponents.set(name, (currentComponents.get(name) ?? 0) + end - componentStart);
+            frameComponents.push({
+                name,
+                phase,
+                startMs: componentStart - frameStart,
+                ms: end - componentStart,
+            });
+        },
+        reportRender(stats) {
+            if (!enabled)
+                return;
+            render = {
+                gpuMs: stats.gpuMs ?? render.gpuMs,
+                drawCalls: render.drawCalls + stats.drawCalls,
+                triangles: render.triangles + stats.triangles,
+                geometries: render.geometries + stats.geometries,
+                textures: render.textures + stats.textures,
+            };
+        },
+        endFrame() {
+            if (!enabled)
+                return;
+            const timestamp = now();
+            const intervalMs = lastFrameStart === 0 ? 0 : frameStart - lastFrameStart;
+            lastFrameStart = frameStart;
+            const frame = {
+                id: ++frameId,
+                timestamp,
+                intervalMs,
+                cpuMs: timestamp - frameStart,
+                phases: [...currentPhases]
+                    .map(([name, { ms, startMs }]) => ({ name, ms, startMs }))
+                    .sort((a, b) => b.ms - a.ms),
+                systems: frameSystems.slice(),
+                components: frameComponents.slice(),
+                render: { ...render },
+            };
+            frames.push(frame);
+            if (frames.length > 600)
+                frames.splice(0, frames.length - 600);
+            if (recording)
+                performance.measure('vgai.frame', { start: frameStart, duration: frame.cpuMs });
+            publish();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot() {
+            return snapshot;
+        },
+        exportJSON() {
+            // version 2 (W4b): frames now carry per-frame `systems`/`components`
+            // spans, per-frame `render` counters, and `startMs` on phase timings.
+            return JSON.stringify({ version: 2, capturedAt: new Date().toISOString(), frames }, null, 2);
+        },
+    };
+}

package/dist/dev/render-debug-adapter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * First-party {@link RenderDebugAdapter} wiring (W4b, F11) — the glue between
+ * the WebGL2 frame capture (`webgl-frame-capture.ts`), a live three.js scene,
+ * and the render adapter's per-frame render pass.
+ *
+ * Split OUT of `setup-three-root-adapter.ts` so the capture/attribution/restore
+ * flow is unit-testable in a headless Node test with a mock GL context and a
+ * plain scene — a real non-headless GPU mount (EffectComposer + WebGLRenderer)
+ * cannot run under vitest here, the same reason the adapter suite drives
+ * `setup(ctx)` only through hotReload on a data scene. `mount()` owns the
+ * DECISION to construct this (only under a real WebGL2 context, never
+ * headless — see `frameCaptureContextFor`); this module owns the BEHAVIOR.
+ *
+ * Attribution model (honest by construction): `captureFrame()` wraps every
+ * renderable's `onBeforeRender` to feed one annotation to the capture. three
+ * calls `onBeforeRender` immediately before that object's MAIN-pass draw, so
+ * main-pass draws are attributed and shadow/composer-pass draws record
+ * `annotation: null` (counted as unattributed) — never a fabricated guess. The
+ * wrappers are all restored when the capture resolves, rejects, times out, or
+ * the adapter is disposed.
+ */
+import type * as THREE from 'three';
+import type { RenderDebugAdapter } from '../adapter/system-adapter';
+import type { RenderMemorySnapshot } from './render-memory';
+import type { WebGLFrameCapture } from './webgl-frame-capture';
+/** Decide whether a mount can host frame capture — a real WebGL2 context with
+ *  the draw entry points, never a headless/stub renderer. Exported so the
+ *  mount uses ONE predicate and a unit test can assert both sides (mock GL ⇒
+ *  the context; headless/missing ⇒ null) without a GPU. */
+export declare function frameCaptureContextFor(headless: boolean, rendererContext: unknown): WebGL2RenderingContext | null;
+export interface RenderDebugAdapterDeps {
+    /** The armed-on-demand frame capture over the mount's real context. */
+    capture: WebGLFrameCapture;
+    /** The live scene root traversed to attribute draws. */
+    scene: THREE.Object3D;
+    /** Memory snapshot supplier (renderer.info-backed). When omitted, the
+     *  adapter's `memorySnapshot` is absent (honest capability degradation). */
+    memory?: () => RenderMemorySnapshot;
+    /** Timeout (ms) after which a pending `captureFrame` rejects — the world
+     *  never rendered (paused/stopped). Default 5000. */
+    timeoutMs?: number;
+    /** Injected timer, for tests. Defaults to the real `setTimeout`/
+     *  `clearTimeout`. */
+    setTimeoutFn?: (fn: () => void, ms: number) => unknown;
+    clearTimeoutFn?: (handle: unknown) => void;
+}
+export interface RenderDebugWiring {
+    readonly adapter: RenderDebugAdapter;
+    /** Call at the START of the host render pass, before draws. */
+    beforeRender(): void;
+    /** Call at the END of the host render pass, after draws (in a `finally`). */
+    afterRender(): void;
+    /** Restore any pending attribution wrappers and reject a pending capture. */
+    dispose(): void;
+}
+export declare function createRenderDebugAdapter(deps: RenderDebugAdapterDeps): RenderDebugWiring;
+//# sourceMappingURL=render-debug-adapter.d.ts.map

package/dist/dev/render-debug-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-debug-adapter.d.ts","sourceRoot":"","sources":["../../src/dev/render-debug-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAgC,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE7F;;;2DAG2D;AAC3D,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,OAAO,EACjB,eAAe,EAAE,OAAO,GACvB,sBAAsB,GAAG,IAAI,CAO/B;AAED,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,OAAO,EAAE,iBAAiB,CAAC;IAC3B,wDAAwD;IACxD,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC;IACtB;gFAC4E;IAC5E,MAAM,CAAC,EAAE,MAAM,oBAAoB,CAAC;IACpC;yDACqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;0BACsB;IACtB,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACvD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,+DAA+D;IAC/D,YAAY,IAAI,IAAI,CAAC;IACrB,6EAA6E;IAC7E,WAAW,IAAI,IAAI,CAAC;IACpB,6EAA6E;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAkDD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CAgFxF"}

package/dist/dev/render-debug-adapter.js

@@ -0,0 +1,141 @@
+/**
+ * First-party {@link RenderDebugAdapter} wiring (W4b, F11) — the glue between
+ * the WebGL2 frame capture (`webgl-frame-capture.ts`), a live three.js scene,
+ * and the render adapter's per-frame render pass.
+ *
+ * Split OUT of `setup-three-root-adapter.ts` so the capture/attribution/restore
+ * flow is unit-testable in a headless Node test with a mock GL context and a
+ * plain scene — a real non-headless GPU mount (EffectComposer + WebGLRenderer)
+ * cannot run under vitest here, the same reason the adapter suite drives
+ * `setup(ctx)` only through hotReload on a data scene. `mount()` owns the
+ * DECISION to construct this (only under a real WebGL2 context, never
+ * headless — see `frameCaptureContextFor`); this module owns the BEHAVIOR.
+ *
+ * Attribution model (honest by construction): `captureFrame()` wraps every
+ * renderable's `onBeforeRender` to feed one annotation to the capture. three
+ * calls `onBeforeRender` immediately before that object's MAIN-pass draw, so
+ * main-pass draws are attributed and shadow/composer-pass draws record
+ * `annotation: null` (counted as unattributed) — never a fabricated guess. The
+ * wrappers are all restored when the capture resolves, rejects, times out, or
+ * the adapter is disposed.
+ */
+/** Decide whether a mount can host frame capture — a real WebGL2 context with
+ *  the draw entry points, never a headless/stub renderer. Exported so the
+ *  mount uses ONE predicate and a unit test can assert both sides (mock GL ⇒
+ *  the context; headless/missing ⇒ null) without a GPU. */
+export function frameCaptureContextFor(headless, rendererContext) {
+    if (headless)
+        return null;
+    if (!rendererContext || typeof rendererContext !== 'object')
+        return null;
+    const gl = rendererContext;
+    if (typeof gl.getExtension !== 'function')
+        return null;
+    if (typeof gl.drawArrays !== 'function' || typeof gl.drawElements !== 'function')
+        return null;
+    return rendererContext;
+}
+/** Objects three actually issues draws for (and thus calls `onBeforeRender`
+ *  on before the main-pass draw). */
+function isRenderable(object) {
+    const o = object;
+    return Boolean(o.isMesh || o.isSkinnedMesh || o.isPoints || o.isLine || o.isSprite);
+}
+function annotationFor(object) {
+    const mesh = object;
+    const geometry = mesh.geometry;
+    const rawMaterial = mesh.material;
+    const material = (Array.isArray(rawMaterial) ? rawMaterial[0] : rawMaterial);
+    const entityId = object.userData?.['entityId'];
+    return {
+        object: {
+            name: object.name || object.type,
+            type: object.type,
+            ...(entityId !== undefined ? { entityId: String(entityId) } : {}),
+        },
+        geometry: {
+            type: geometry?.type ?? 'unknown',
+            name: geometry?.name ?? '',
+            attributes: geometry ? Object.keys(geometry.attributes) : [],
+            indexed: Boolean(geometry?.index),
+        },
+        material: {
+            type: material?.type ?? 'unknown',
+            name: material?.name ?? '',
+        },
+    };
+}
+export function createRenderDebugAdapter(deps) {
+    const { capture, scene, memory } = deps;
+    const timeoutMs = deps.timeoutMs ?? 5000;
+    const setTimer = deps.setTimeoutFn ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = deps.clearTimeoutFn ?? ((h) => clearTimeout(h));
+    let pending = null;
+    function wrapOnBeforeRender() {
+        const restores = [];
+        scene.traverse((object) => {
+            if (!isRenderable(object))
+                return;
+            const original = object.onBeforeRender;
+            object.onBeforeRender = function patched(...args) {
+                capture.annotateNextDraw(annotationFor(object));
+                original.apply(this, args);
+            };
+            restores.push(() => {
+                object.onBeforeRender = original;
+            });
+        });
+        return restores;
+    }
+    function settlePending() {
+        const p = pending;
+        if (p && !p.settled) {
+            p.settled = true;
+            clearTimer(p.timer);
+            for (const restore of p.restores)
+                restore();
+            pending = null;
+            return p;
+        }
+        return null;
+    }
+    const adapter = {
+        captureFrame() {
+            if (pending) {
+                return Promise.reject(new Error('RenderDebugAdapter: a frame capture is already pending'));
+            }
+            return new Promise((resolve, reject) => {
+                const restores = wrapOnBeforeRender();
+                capture.arm();
+                // Assign `pending` BEFORE arming the timer so a synchronous injected
+                // timer (test) sees a settle-able pending rather than a null one.
+                const p = { resolve, reject, restores, timer: null, settled: false };
+                pending = p;
+                p.timer = setTimer(() => {
+                    if (settlePending()) {
+                        reject(new Error(`RenderDebugAdapter: no frame rendered within ${timeoutMs}ms — the world may be paused or stopped`));
+                    }
+                }, timeoutMs);
+            });
+        },
+        ...(memory ? { memorySnapshot: () => memory() } : {}),
+    };
+    return {
+        adapter,
+        beforeRender() {
+            capture.beginPass();
+        },
+        afterRender() {
+            const result = capture.endPass();
+            if (result && pending) {
+                const p = settlePending();
+                p?.resolve(result);
+            }
+        },
+        dispose() {
+            const p = settlePending();
+            if (p)
+                p.reject(new Error('RenderDebugAdapter: disposed before a frame was captured'));
+        },
+    };
+}

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

@@ -0,0 +1,53 @@
+/**
+ * First-party GPU-memory estimator (W4b, F11 profiler memory tab).
+ *
+ * Walks a live three.js scene and reports geometry/texture byte footprints
+ * from data this engine ALREADY holds — attribute buffers and texture images —
+ * plus the renderer's own resource counts (`renderer.info`). Uses three.js
+ * directly, no wrapper.
+ *
+ * HONESTY (adapters never fabricate; unmeasurable = absent-with-reason):
+ *  - `estimateGeometryBytes` is EXACT: the summed `byteLength` of every
+ *    attribute and index array. Not an estimate at all — it is what the
+ *    buffers occupy in CPU memory (and, uploaded 1:1, on the GPU).
+ *  - `estimateTextureBytes` returns `null` when the footprint is genuinely
+ *    unknowable at this seam (no image dimensions, or a pixel format/type we
+ *    can't size). A null NEVER enters the totals — it goes to `unestimated[]`
+ *    with a reason, so the panel can say "N textures unmeasured" instead of
+ *    silently undercounting.
+ *  - JS heap is deliberately NOT here: `performance.memory` is a browser-only
+ *    global read editor-side (M2), not an engine-scene property.
+ */
+import * as THREE from 'three';
+export interface RenderMemoryEntry {
+    readonly name: string;
+    readonly bytes: number;
+}
+export interface RenderMemoryUnestimated {
+    readonly name: string;
+    readonly reason: string;
+}
+export interface RenderMemorySnapshot {
+    readonly counts: {
+        readonly geometries: number;
+        readonly textures: number;
+        /** Compiled program count, or `null` when the renderer doesn't expose it
+         *  (`renderer.info.programs` is populated only after the first render). */
+        readonly programs: number | null;
+    };
+    /** Sum of every ESTIMABLE texture (nulls excluded — they are in
+     *  `unestimated`). */
+    readonly estimatedTextureBytes: number;
+    /** Exact sum of geometry attribute + index buffers. */
+    readonly estimatedGeometryBytes: number;
+    readonly topTextures: readonly RenderMemoryEntry[];
+    readonly topGeometries: readonly RenderMemoryEntry[];
+    readonly unestimated: readonly RenderMemoryUnestimated[];
+}
+/** EXACT CPU/GPU footprint of a geometry's attribute + index buffers. */
+export declare function estimateGeometryBytes(geometry: THREE.BufferGeometry): number;
+/** Estimated GPU footprint of a texture, or `null` when unknowable at this
+ *  seam (the caller routes null into `unestimated[]` with a reason). */
+export declare function estimateTextureBytes(texture: THREE.Texture): number | null;
+export declare function collectRenderMemory(scene: THREE.Object3D, info: THREE.WebGLInfo): RenderMemorySnapshot;
+//# sourceMappingURL=render-memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-memory.d.ts","sourceRoot":"","sources":["../../src/dev/render-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B;mFAC2E;QAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;KAClC,CAAC;IACF;0BACsB;IACtB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,uDAAuD;IACvD,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC1D;AA+CD,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,GAAG,MAAM,CAoB5E;AAED;wEACwE;AACxE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,GAAG,MAAM,GAAG,IAAI,CA0B1E;AAsDD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,CAAC,QAAQ,EACrB,IAAI,EAAE,KAAK,CAAC,SAAS,GACpB,oBAAoB,CAsCtB"}

package/dist/dev/render-memory.js

@@ -0,0 +1,190 @@
+/**
+ * First-party GPU-memory estimator (W4b, F11 profiler memory tab).
+ *
+ * Walks a live three.js scene and reports geometry/texture byte footprints
+ * from data this engine ALREADY holds — attribute buffers and texture images —
+ * plus the renderer's own resource counts (`renderer.info`). Uses three.js
+ * directly, no wrapper.
+ *
+ * HONESTY (adapters never fabricate; unmeasurable = absent-with-reason):
+ *  - `estimateGeometryBytes` is EXACT: the summed `byteLength` of every
+ *    attribute and index array. Not an estimate at all — it is what the
+ *    buffers occupy in CPU memory (and, uploaded 1:1, on the GPU).
+ *  - `estimateTextureBytes` returns `null` when the footprint is genuinely
+ *    unknowable at this seam (no image dimensions, or a pixel format/type we
+ *    can't size). A null NEVER enters the totals — it goes to `unestimated[]`
+ *    with a reason, so the panel can say "N textures unmeasured" instead of
+ *    silently undercounting.
+ *  - JS heap is deliberately NOT here: `performance.memory` is a browser-only
+ *    global read editor-side (M2), not an engine-scene property.
+ */
+import * as THREE from 'three';
+const TOP_N = 10;
+/** Channel count per pixel format. Packed/compressed formats are handled by
+ *  the byte-size logic in {@link estimateTextureBytes}, not here. */
+const FORMAT_CHANNELS = {
+    [THREE.AlphaFormat]: 1,
+    [THREE.RedFormat]: 1,
+    [THREE.RedIntegerFormat]: 1,
+    [THREE.RGFormat]: 2,
+    [THREE.RGIntegerFormat]: 2,
+    [THREE.RGBAFormat]: 4,
+    [THREE.RGBAIntegerFormat]: 4,
+    [THREE.DepthFormat]: 1,
+    [THREE.DepthStencilFormat]: 2,
+};
+/** Bytes per channel for a (non-packed) pixel type. */
+const TYPE_BYTES = {
+    [THREE.UnsignedByteType]: 1,
+    [THREE.ByteType]: 1,
+    [THREE.ShortType]: 2,
+    [THREE.UnsignedShortType]: 2,
+    [THREE.IntType]: 4,
+    [THREE.UnsignedIntType]: 4,
+    [THREE.FloatType]: 4,
+    [THREE.HalfFloatType]: 2,
+};
+/** Packed pixel types occupy a FIXED size per texel regardless of channel
+ *  count — sized here directly rather than via channels × type-bytes. */
+const PACKED_TYPE_TEXEL_BYTES = {
+    [THREE.UnsignedShort4444Type]: 2,
+    [THREE.UnsignedShort5551Type]: 2,
+    [THREE.UnsignedInt248Type]: 4,
+};
+function bytesPerTexel(format, type) {
+    const packed = PACKED_TYPE_TEXEL_BYTES[type];
+    if (packed !== undefined)
+        return packed;
+    const channels = FORMAT_CHANNELS[format];
+    const typeBytes = TYPE_BYTES[type];
+    if (channels === undefined || typeBytes === undefined)
+        return null;
+    return channels * typeBytes;
+}
+/** EXACT CPU/GPU footprint of a geometry's attribute + index buffers. */
+export function estimateGeometryBytes(geometry) {
+    // Interleaved attributes share ONE backing buffer (`attribute.data.array`);
+    // a plain attribute owns its own (`attribute.array`). Count each unique
+    // backing view exactly once.
+    const counted = new Set();
+    let bytes = 0;
+    const add = (view) => {
+        if (view && !counted.has(view)) {
+            counted.add(view);
+            bytes += view.byteLength;
+        }
+    };
+    for (const attribute of Object.values(geometry.attributes)) {
+        const interleaved = attribute.data?.array;
+        add(interleaved ?? attribute.array);
+    }
+    add(geometry.index?.array);
+    return bytes;
+}
+/** Estimated GPU footprint of a texture, or `null` when unknowable at this
+ *  seam (the caller routes null into `unestimated[]` with a reason). */
+export function estimateTextureBytes(texture) {
+    // Compressed textures carry their real per-mip byte arrays — sum them; no
+    // format math needed and no estimate involved.
+    const compressed = texture;
+    if (compressed.isCompressedTexture &&
+        Array.isArray(compressed.mipmaps)) {
+        let bytes = 0;
+        for (const mip of compressed.mipmaps) {
+            const data = mip.data;
+            if (data?.byteLength)
+                bytes += data.byteLength;
+        }
+        return bytes;
+    }
+    const image = texture.image;
+    const width = image?.width;
+    const height = image?.height;
+    if (!width || !height)
+        return null;
+    const bpt = bytesPerTexel(texture.format, texture.type);
+    if (bpt === null)
+        return null;
+    const base = width * height * bpt;
+    return texture.generateMipmaps ? Math.round(base * 1.333) : base;
+}
+function textureName(texture) {
+    return texture.name || texture.image?.src || `texture:${texture.uuid}`;
+}
+function geometryName(geometry) {
+    return geometry.name || `${geometry.type}:${geometry.uuid}`;
+}
+function unestimatedReason(texture) {
+    const image = texture.image;
+    if (!image?.width || !image?.height)
+        return 'no image dimensions available';
+    return `unsupported format/type (format 0x${texture.format.toString(16)}, type 0x${texture.type.toString(16)})`;
+}
+/** Collect every unique geometry and texture referenced by a scene graph. */
+function collectResources(scene) {
+    const geometries = new Map();
+    const textures = new Map();
+    const addMaterialTextures = (material) => {
+        for (const value of Object.values(material)) {
+            if (value && value.isTexture) {
+                const tex = value;
+                textures.set(tex.uuid, tex);
+            }
+        }
+    };
+    scene.traverse((object) => {
+        const geometry = object.geometry;
+        if (geometry?.isBufferGeometry)
+            geometries.set(geometry.uuid, geometry);
+        const material = object.material;
+        if (Array.isArray(material))
+            material.forEach(addMaterialTextures);
+        else if (material)
+            addMaterialTextures(material);
+    });
+    // Scene-level environment/background textures count too.
+    for (const maybe of [scene]) {
+        for (const value of [maybe.background, maybe.environment]) {
+            if (value && value.isTexture) {
+                const tex = value;
+                textures.set(tex.uuid, tex);
+            }
+        }
+    }
+    return { geometries, textures };
+}
+export function collectRenderMemory(scene, info) {
+    const { geometries, textures } = collectResources(scene);
+    const geometryEntries = [];
+    let estimatedGeometryBytes = 0;
+    for (const geometry of geometries.values()) {
+        const bytes = estimateGeometryBytes(geometry);
+        estimatedGeometryBytes += bytes;
+        geometryEntries.push({ name: geometryName(geometry), bytes });
+    }
+    const textureEntries = [];
+    const unestimated = [];
+    let estimatedTextureBytes = 0;
+    for (const texture of textures.values()) {
+        const bytes = estimateTextureBytes(texture);
+        if (bytes === null) {
+            unestimated.push({ name: textureName(texture), reason: unestimatedReason(texture) });
+            continue;
+        }
+        estimatedTextureBytes += bytes;
+        textureEntries.push({ name: textureName(texture), bytes });
+    }
+    const byBytesDesc = (a, b) => b.bytes - a.bytes;
+    return {
+        counts: {
+            geometries: info.memory.geometries,
+            textures: info.memory.textures,
+            programs: info.programs ? info.programs.length : null,
+        },
+        estimatedTextureBytes,
+        estimatedGeometryBytes,
+        topTextures: textureEntries.sort(byBytesDesc).slice(0, TOP_N),
+        topGeometries: geometryEntries.sort(byBytesDesc).slice(0, TOP_N),
+        unestimated,
+    };
+}