@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/telemetry/gc-profiler.js

@@ -0,0 +1,82 @@
+// ============================================================================
+// GC Profiler — tracks GC frequency and duration per process
+// Works in Node.js (main/worker) and browser (renderer) via PerformanceObserver
+// ============================================================================
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+export function startGCProfiler(label, onStats, intervalMs = 2000) {
+    const PO = globalThis.PerformanceObserver;
+    if (!PO) {
+        log.warn(`GC:${label}`, "PerformanceObserver unavailable — skipping GC profiling");
+        return null;
+    }
+    // 'gc' entries are a V8/Node entry type — JSC (Bun) supports
+    // PerformanceObserver but never emits them. Bail rather than run a
+    // setInterval that reports empty stats forever.
+    const supported = PO.supportedEntryTypes;
+    if (supported && !supported.includes("gc")) {
+        log.warn(`GC:${label}`, "host does not emit 'gc' performance entries — skipping GC profiling");
+        return null;
+    }
+    let cur = {
+        count: 0, totalTime: 0,
+        scavengeCount: 0, scavengeTime: 0,
+        majorCount: 0, majorTime: 0,
+        otherCount: 0, otherTime: 0,
+    };
+    let totalGC = 0;
+    let totalGCTime = 0;
+    const startTime = performance.now();
+    const obs = new PO((list) => {
+        for (const entry of list.getEntries()) {
+            const dur = entry.duration;
+            cur.count++;
+            cur.totalTime += dur;
+            totalGC++;
+            totalGCTime += dur;
+            const kind = entry.kind;
+            if (kind === 1) {
+                cur.scavengeCount++;
+                cur.scavengeTime += dur;
+            }
+            else if (kind === 2) {
+                cur.majorCount++;
+                cur.majorTime += dur;
+            }
+            else {
+                cur.otherCount++;
+                cur.otherTime += dur;
+            }
+        }
+    });
+    try {
+        obs.observe({ entryTypes: ['gc'], buffered: true });
+    }
+    catch (e) {
+        log.warn(`GC:${label}`, `Failed to observe GC events: ${e}`);
+        return null;
+    }
+    const timer = setInterval(() => {
+        const wallMs = performance.now() - startTime;
+        onStats({
+            label,
+            interval: { ...cur },
+            overall: { count: totalGC, totalTime: totalGCTime, wallMs },
+        });
+        cur = {
+            count: 0, totalTime: 0,
+            scavengeCount: 0, scavengeTime: 0,
+            majorCount: 0, majorTime: 0,
+            otherCount: 0, otherTime: 0,
+        };
+    }, intervalMs);
+    return {
+        stop: () => {
+            clearInterval(timer);
+            try {
+                obs.disconnect();
+            }
+            catch { }
+        },
+    };
+}

package/dist/core/src/telemetry/gc-tracker.js

@@ -0,0 +1,63 @@
+export class GCTracker {
+    enabled = false;
+    pauseTotal = 0;
+    pauseCount = 0;
+    pauseMax = 0;
+    lastGcTime = 0;
+    constructor(enabled = false) {
+        this.enabled = enabled;
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    recordGcPause(durationMs) {
+        if (!this.enabled)
+            return;
+        this.pauseTotal += durationMs;
+        this.pauseCount++;
+        if (durationMs > this.pauseMax) {
+            this.pauseMax = durationMs;
+        }
+        this.lastGcTime = performance.now();
+    }
+    getStats() {
+        return {
+            pauseTotal: this.pauseTotal,
+            pauseCount: this.pauseCount,
+            pauseMax: this.pauseMax,
+            pauseAvg: this.pauseCount > 0 ? this.pauseTotal / this.pauseCount : 0,
+            lastGcTime: this.lastGcTime,
+        };
+    }
+    reset() {
+        this.pauseTotal = 0;
+        this.pauseCount = 0;
+        this.pauseMax = 0;
+        this.lastGcTime = 0;
+    }
+    static getCurrentMemory() {
+        if (typeof process !== "undefined" && process.memoryUsage) {
+            const mem = process.memoryUsage();
+            return {
+                heapUsed: mem.heapUsed,
+                heapTotal: mem.heapTotal,
+                rss: mem.rss,
+                external: mem.external,
+            };
+        }
+        // Browser fallback — performance.memory is a non-standard Blink API
+        const perfMem = performance.memory;
+        if (perfMem) {
+            return {
+                heapUsed: perfMem.usedJSHeapSize,
+                heapTotal: perfMem.totalJSHeapSize,
+                rss: 0,
+                external: 0,
+            };
+        }
+        return { heapUsed: 0, heapTotal: 0, rss: 0, external: 0 };
+    }
+}

package/dist/core/src/telemetry/gpu-profiler.js

@@ -0,0 +1,554 @@
+// ============================================================================
+// GPUProfiler — consolidated GPU debugging: pass timing, error capture,
+// GPU info/limits snapshot, and tracked render pass wrapping.
+// ============================================================================
+import { createLogger } from "../util/logger.js";
+import { GPUTimerPool } from "./gpu-timer-pool.js";
+const log = createLogger();
+export class GPUProfiler {
+    passTimings = new Map();
+    passStartTimes = new Map();
+    passGpuIndices = new Map();
+    gpuPassCounter = 0;
+    gpuTimerPool = null;
+    passTracker = {
+        pipelineSwitches: 0,
+        bindGroupChanges: 0,
+        bufferRebinds: 0,
+        drawCalls: 0,
+        triangles: 0,
+    };
+    adapterInfo = null;
+    gpuErrors = [];
+    deviceLost = false;
+    canvasFormat = null;
+    device = null;
+    // Error throttling — uncaptured GPU errors fire per-frame when something is
+    // wrong, which floods the console. We log the first occurrence immediately,
+    // suppress duplicates within a throttle window, then emit a summary.
+    static ERROR_THROTTLE_MS = 1000;
+    static ERROR_LOG_CAP = 100;
+    static MAX_PASS_TIMINGS = 256;
+    errorThrottle = new Map();
+    // Once an uncaptured error fires, subsequent GPU operations on the same
+    // invalid resources produce a cascade of native validation warnings every
+    // frame. This flag lets the render loop skip GPU work until recovery.
+    uncapturedErrorFired = false;
+    init(device, adapterInfo, canvasFormat, maxPasses = 16) {
+        this.device = device;
+        this.adapterInfo = adapterInfo;
+        this.canvasFormat = canvasFormat;
+        this.gpuTimerPool = new GPUTimerPool(device, maxPasses);
+        const self = this;
+        device.onuncapturederror = function (ev) {
+            const label = ev.error?.label ?? "";
+            const message = ev.error.message;
+            const entry = {
+                timestamp: performance.now(),
+                message,
+                label: label || undefined,
+            };
+            self.gpuErrors.push(entry);
+            if (self.gpuErrors.length > GPUProfiler.ERROR_LOG_CAP)
+                self.gpuErrors.shift();
+            self.uncapturedErrorFired = true;
+            const key = `${label}\u0000${message}`;
+            const now = performance.now();
+            const state = self.errorThrottle.get(key);
+            if (!state) {
+                // First occurrence — log immediately and start a throttle window.
+                self.errorThrottle.set(key, { count: 1, firstSeen: now, lastLogged: now, suppressed: 0 });
+                log.error("gpu", `${label ? label + " " : ""}WebGPU uncaptured error: ${message}`);
+                return;
+            }
+            state.count++;
+            const elapsed = now - state.lastLogged;
+            if (elapsed < GPUProfiler.ERROR_THROTTLE_MS) {
+                // Within the throttle window — suppress.
+                state.suppressed++;
+                return;
+            }
+            // Window elapsed — emit a summary of suppressed duplicates and reset.
+            const suppressed = state.suppressed + 1; // +1 for this occurrence
+            log.error("gpu", `${label ? label + " " : ""}WebGPU uncaptured error: ${message} ` +
+                `(repeated ${suppressed}× in ${Math.round(elapsed)}ms)`);
+            state.lastLogged = now;
+            state.suppressed = 0;
+        };
+        device.lost.then((info) => {
+            self.deviceLost = true;
+            log.error("gpu", `WebGPU device lost: ${info?.reason ?? "unknown"} — ${info?.message ?? ""}`);
+        });
+    }
+    getGPUTimerPool() {
+        return this.gpuTimerPool;
+    }
+    isGpuTimerSupported() {
+        return this.gpuTimerPool?.isSupported() ?? false;
+    }
+    /** True after an uncaptured GPU error — the render loop should skip GPU work
+     *  to avoid per-frame validation warning cascades. Stays true until cleared. */
+    hasUncapturedError() {
+        return this.uncapturedErrorFired;
+    }
+    /** Clear the uncaptured-error flag (e.g. after recreating resources). */
+    clearUncapturedError() {
+        this.uncapturedErrorFired = false;
+    }
+    // --- Pass timing ---
+    beginFrame() {
+        this.passStartTimes.clear();
+        this.passTimings.clear();
+        this.passGpuIndices.clear();
+        this.gpuPassCounter = 0;
+    }
+    beginPass(name, passEncoder, viewportIdx) {
+        this.beginPassInternal(name, passEncoder, viewportIdx, "render");
+    }
+    endPass(name, passEncoder, viewportIdx, drawCalls = 0, triangles = 0) {
+        this.endPassInternal(name, passEncoder, viewportIdx, drawCalls, triangles, "render");
+    }
+    /**
+     * Begin timing a compute pass. Writes a GPU timestamp at the start of the
+     * pass (if supported) and records the CPU start time.
+     */
+    beginComputePass(name, passEncoder) {
+        this.beginPassInternal(name, passEncoder, 0, "compute");
+    }
+    /**
+     * End timing a compute pass. Writes the end GPU timestamp and records the
+     * CPU duration. Workgroup count is stored in drawCalls for display.
+     */
+    endComputePass(name, passEncoder, workgroups = 0) {
+        this.endPassInternal(name, passEncoder, 0, workgroups, 0, "compute");
+    }
+    /**
+     * Begin timing a blit pass (buffer/texture copies, resolves). Blit passes
+     * don't have a pass encoder — timestamps are written on the command encoder
+     * using the "timestamp-query" base feature (encoder-level timestamps).
+     */
+    beginBlitPass(name, encoder) {
+        if (this.passStartTimes.has(name))
+            return;
+        this.passStartTimes.set(name, performance.now());
+        if (!this.gpuTimerPool || !this.gpuTimerPool.isEncoderTimestampSupported())
+            return;
+        const maxPasses = this.gpuTimerPool.getMaxPasses();
+        const idx = this.gpuPassCounter++;
+        if (idx >= maxPasses)
+            return;
+        this.passGpuIndices.set(name, idx);
+        this.gpuTimerPool.beginEncoder(encoder, idx);
+    }
+    /**
+     * End timing a blit pass. Writes the end timestamp on the command encoder.
+     */
+    endBlitPass(name, encoder) {
+        if (this.gpuTimerPool && this.gpuTimerPool.isEncoderTimestampSupported()) {
+            const idx = this.passGpuIndices.get(name);
+            if (idx !== undefined && idx < this.gpuTimerPool.getMaxPasses()) {
+                this.gpuTimerPool.endEncoder(encoder, idx);
+            }
+        }
+        const start = this.passStartTimes.get(name);
+        if (start === undefined)
+            return;
+        const cpuMs = performance.now() - start;
+        const gpuIdx = this.passGpuIndices.get(name);
+        const gpuMs = (gpuIdx !== undefined && this.gpuTimerPool) ? this.gpuTimerPool.getPassGpuMs(gpuIdx) : 0;
+        if (!this.passTimings.has(name) && this.passTimings.size >= GPUProfiler.MAX_PASS_TIMINGS) {
+            const oldest = this.passTimings.keys().next().value;
+            if (oldest !== undefined)
+                this.passTimings.delete(oldest);
+        }
+        this.passTimings.set(name, {
+            cpuMs,
+            gpuMs,
+            drawCalls: 0,
+            triangles: 0,
+            pipelineSwitches: 0,
+            bindGroupChanges: 0,
+            bufferRebinds: 0,
+            category: "blit",
+        });
+    }
+    beginPassInternal(name, passEncoder, viewportIdx, category) {
+        if (viewportIdx !== 0)
+            return;
+        this.passStartTimes.set(name, performance.now());
+        this.passTracker.pipelineSwitches = 0;
+        this.passTracker.bindGroupChanges = 0;
+        this.passTracker.bufferRebinds = 0;
+        this.passTracker.drawCalls = 0;
+        this.passTracker.triangles = 0;
+        if (!this.gpuTimerPool || !this.gpuTimerPool.isSupported())
+            return;
+        const maxPasses = this.gpuTimerPool.getMaxPasses();
+        const idx = this.gpuPassCounter++;
+        if (idx >= maxPasses)
+            return;
+        this.passGpuIndices.set(name, idx);
+        this.gpuTimerPool.begin(passEncoder, idx);
+    }
+    endPassInternal(name, passEncoder, viewportIdx, drawCalls, triangles, category) {
+        if (viewportIdx !== 0)
+            return;
+        // End GPU timer
+        if (this.gpuTimerPool && this.gpuTimerPool.isSupported()) {
+            const idx = this.passGpuIndices.get(name);
+            if (idx !== undefined && idx < this.gpuTimerPool.getMaxPasses()) {
+                this.gpuTimerPool.end(passEncoder, idx);
+            }
+        }
+        // Record timing
+        const start = this.passStartTimes.get(name);
+        if (start === undefined)
+            return;
+        const cpuMs = performance.now() - start;
+        const existing = this.passTimings.get(name);
+        const gpuIdx = this.passGpuIndices.get(name);
+        const gpuMs = (gpuIdx !== undefined && this.gpuTimerPool) ? this.gpuTimerPool.getPassGpuMs(gpuIdx) : 0;
+        if (!this.passTimings.has(name) && this.passTimings.size >= GPUProfiler.MAX_PASS_TIMINGS) {
+            const oldest = this.passTimings.keys().next().value;
+            if (oldest !== undefined)
+                this.passTimings.delete(oldest);
+        }
+        this.passTimings.set(name, {
+            cpuMs,
+            gpuMs,
+            drawCalls: this.passTracker.drawCalls || drawCalls || existing?.drawCalls || 0,
+            triangles: this.passTracker.triangles || triangles || existing?.triangles || 0,
+            pipelineSwitches: this.passTracker.pipelineSwitches,
+            bindGroupChanges: this.passTracker.bindGroupChanges,
+            bufferRebinds: this.passTracker.bufferRebinds,
+            category,
+        });
+    }
+    resolveGpuTimers(encoder) {
+        if (this.gpuTimerPool && (this.gpuTimerPool.isSupported() || this.gpuTimerPool.isEncoderTimestampSupported())) {
+            this.gpuTimerPool.resolve(encoder);
+        }
+    }
+    readGpuTimers() {
+        if (this.gpuTimerPool && (this.gpuTimerPool.isSupported() || this.gpuTimerPool.isEncoderTimestampSupported())) {
+            return this.gpuTimerPool.readAll();
+        }
+        return Promise.resolve(new Map());
+    }
+    getPassTimings() {
+        const result = [];
+        for (const [name, t] of this.passTimings.entries()) {
+            result.push({
+                name,
+                cpuMs: t.cpuMs,
+                gpuMs: t.gpuMs,
+                drawCalls: t.drawCalls,
+                triangles: t.triangles,
+                pipelineSwitches: t.pipelineSwitches,
+                bindGroupChanges: t.bindGroupChanges,
+                bufferRebinds: t.bufferRebinds,
+                category: t.category,
+            });
+        }
+        return result;
+    }
+    // --- Tracked render pass ---
+    wrapTrackedPass(pass) {
+        const tracker = this.passTracker;
+        return new Proxy(pass, {
+            get(target, prop) {
+                if (prop === "setPipeline") {
+                    return (pipeline) => {
+                        tracker.pipelineSwitches++;
+                        target.setPipeline(pipeline);
+                    };
+                }
+                if (prop === "setBindGroup") {
+                    return (index, group, dynamicOffsets) => {
+                        tracker.bindGroupChanges++;
+                        target.setBindGroup(index, group, dynamicOffsets ?? []);
+                    };
+                }
+                if (prop === "setVertexBuffer") {
+                    return (slot, buffer, offset = 0, size) => {
+                        tracker.bufferRebinds++;
+                        target.setVertexBuffer(slot, buffer, offset, size);
+                    };
+                }
+                if (prop === "setIndexBuffer") {
+                    return (buffer, format, offset = 0, size) => {
+                        tracker.bufferRebinds++;
+                        target.setIndexBuffer(buffer, format, offset, size);
+                    };
+                }
+                if (prop === "draw") {
+                    return (vertexCount, instanceCount = 1, firstVertex = 0, firstInstance = 0) => {
+                        tracker.drawCalls++;
+                        tracker.triangles += Math.floor(vertexCount / 3) * instanceCount;
+                        target.draw(vertexCount, instanceCount, firstVertex, firstInstance);
+                    };
+                }
+                if (prop === "drawIndexed") {
+                    return (indexCount, instanceCount = 1, firstIndex = 0, baseVertex = 0, firstInstance = 0) => {
+                        tracker.drawCalls++;
+                        tracker.triangles += Math.floor(indexCount / 3) * instanceCount;
+                        target.drawIndexed(indexCount, instanceCount, firstIndex, baseVertex, firstInstance);
+                    };
+                }
+                const value = Reflect.get(target, prop);
+                if (typeof value === "function")
+                    return value.bind(target);
+                return value;
+            },
+        });
+    }
+    // --- GPU errors ---
+    getGPUErrors() {
+        return this.gpuErrors;
+    }
+    clearGPUErrors() {
+        this.gpuErrors = [];
+    }
+    isDeviceLost() {
+        return this.deviceLost;
+    }
+    // --- GPU info / limits ---
+    getGPUInfo(canvas, msaaSampleCount) {
+        const a = this.adapterInfo;
+        const adapter = a ? {
+            vendor: a.vendor ?? "",
+            architecture: a.architecture ?? "",
+            device: a.device ?? "",
+            description: a.description ?? "",
+        } : null;
+        const limits = this.device?.limits;
+        const deviceLimits = limits ? {
+            maxTextureDimension1D: limits.maxTextureDimension1D,
+            maxTextureDimension2D: limits.maxTextureDimension2D,
+            maxTextureDimension3D: limits.maxTextureDimension3D,
+            maxTextureArrayLayers: limits.maxTextureArrayLayers,
+            maxBindGroups: limits.maxBindGroups,
+            maxBindGroupsPerShaderStage: limits.maxBindGroupsPerShaderStage,
+            maxBindingsPerBindGroup: limits.maxBindingsPerBindGroup,
+            maxBufferSize: limits.maxBufferSize,
+            maxStorageBufferBindingSize: limits.maxStorageBufferBindingSize,
+            maxUniformBufferBindingSize: limits.maxUniformBufferBindingSize,
+            maxDynamicUniformBuffersPerPipelineLayout: limits.maxDynamicUniformBuffersPerPipelineLayout,
+            maxDynamicStorageBuffersPerPipelineLayout: limits.maxDynamicStorageBuffersPerPipelineLayout,
+            maxSampledTexturesPerShaderStage: limits.maxSampledTexturesPerShaderStage,
+            maxSamplersPerShaderStage: limits.maxSamplersPerShaderStage,
+            maxStorageBuffersPerShaderStage: limits.maxStorageBuffersPerShaderStage,
+            maxStorageTexturesPerShaderStage: limits.maxStorageTexturesPerShaderStage,
+            maxUniformBuffersPerShaderStage: limits.maxUniformBuffersPerShaderStage,
+            maxVertexAttributes: limits.maxVertexAttributes,
+            maxVertexBuffers: limits.maxVertexBuffers,
+            maxVertexBufferArrayStride: limits.maxVertexBufferArrayStride,
+            minUniformBufferOffsetAlignment: limits.minUniformBufferOffsetAlignment,
+            minStorageBufferOffsetAlignment: limits.minStorageBufferOffsetAlignment,
+            maxColorAttachments: limits.maxColorAttachments,
+            maxColorAttachmentBytesPerSample: limits.maxColorAttachmentBytesPerSample,
+            maxComputeWorkgroupStorageSize: limits.maxComputeWorkgroupStorageSize,
+            maxComputeInvocationsPerWorkgroup: limits.maxComputeInvocationsPerWorkgroup,
+            maxComputeWorkgroupSizeX: limits.maxComputeWorkgroupSizeX,
+            maxComputeWorkgroupSizeY: limits.maxComputeWorkgroupSizeY,
+            maxComputeWorkgroupSizeZ: limits.maxComputeWorkgroupSizeZ,
+            maxComputeWorkgroupsPerDimension: limits.maxComputeWorkgroupsPerDimension,
+        } : null;
+        return {
+            adapter,
+            deviceLost: this.deviceLost,
+            canvasFormat: this.canvasFormat,
+            msaaSampleCount,
+            canvasSize: { width: canvas.width, height: canvas.height },
+            deviceLimits,
+        };
+    }
+    getAdapterInfo() {
+        return this.adapterInfo;
+    }
+    // --- Frame Graph Builder ---
+    static buildFrameGraphData(passTimings, ppInfo, scenePassOrder, alwaysOnPasses = []) {
+        const timingMap = new Map();
+        passTimings.forEach((t) => { timingMap.set(t.name, t); ; });
+        const nodes = [];
+        const edges = [];
+        const validations = [];
+        let totalGpuMs = 0;
+        let totalCpuMs = 0;
+        let totalDrawCalls = 0;
+        let totalTriangles = 0;
+        // --- Scene passes (layer 0) ---
+        const activeScenePasses = [];
+        scenePassOrder.forEach((name) => {
+            const t = timingMap.get(name);
+            const active = !!t;
+            const node = {
+                id: "scene:" + name,
+                name,
+                category: "scene",
+                layer: 0,
+                cpuMs: t?.cpuMs ?? 0,
+                gpuMs: t?.gpuMs ?? 0,
+                drawCalls: t?.drawCalls ?? 0,
+                triangles: t?.triangles ?? 0,
+                pipelineSwitches: t?.pipelineSwitches ?? 0,
+                bindGroupChanges: t?.bindGroupChanges ?? 0,
+                bufferRebinds: t?.bufferRebinds ?? 0,
+                active,
+            };
+            nodes.push(node);
+            if (active) {
+                activeScenePasses.push(node.id);
+                totalGpuMs += node.gpuMs;
+                totalCpuMs += node.cpuMs;
+                totalDrawCalls += node.drawCalls;
+                totalTriangles += node.triangles;
+            }
+        });
+        // Edges between consecutive active scene passes (shared color+depth)
+        for (let i = 0; i < activeScenePasses.length - 1; i++) {
+            edges.push({
+                from: activeScenePasses[i],
+                to: activeScenePasses[i + 1],
+                resource: "color+depth",
+                type: "color",
+            });
+        }
+        // --- Post-process / pixelation (layer 1) ---
+        const layer1NodeIds = [];
+        if (ppInfo.pixelationEnabled) {
+            const pxId = "pp:Pixelation";
+            nodes.push({
+                id: pxId,
+                name: "Pixelation (size=" + ppInfo.pixelSize + ")",
+                category: "pixelation",
+                layer: 1,
+                cpuMs: 0, gpuMs: 0, drawCalls: 0, triangles: 0,
+                pipelineSwitches: 0, bindGroupChanges: 0, bufferRebinds: 0,
+                active: true,
+            });
+            layer1NodeIds.push(pxId);
+        }
+        else if (ppInfo.postProcessEffects.length > 0) {
+            ppInfo.postProcessEffects.forEach((effName) => {
+                const eid = "pp:" + effName;
+                nodes.push({
+                    id: eid,
+                    name: effName,
+                    category: "postprocess",
+                    layer: 1,
+                    cpuMs: 0, gpuMs: 0, drawCalls: 0, triangles: 0,
+                    pipelineSwitches: 0, bindGroupChanges: 0, bufferRebinds: 0,
+                    active: true,
+                });
+                layer1NodeIds.push(eid);
+            });
+            // Chain edges between consecutive post-process effects
+            for (let i = 0; i < layer1NodeIds.length - 1; i++) {
+                edges.push({
+                    from: layer1NodeIds[i],
+                    to: layer1NodeIds[i + 1],
+                    resource: "intermediate",
+                    type: "chain",
+                });
+            }
+        }
+        // Edge: last scene pass → first layer-1 node (or UI if no layer 1)
+        const lastSceneId = activeScenePasses.length > 0
+            ? activeScenePasses[activeScenePasses.length - 1]
+            : null;
+        if (lastSceneId && layer1NodeIds.length > 0) {
+            edges.push({
+                from: lastSceneId,
+                to: layer1NodeIds[0],
+                resource: "color attachment",
+                type: "color",
+            });
+        }
+        // --- UI composite (layer 2) ---
+        const uiId = "ui:Composite";
+        nodes.push({
+            id: uiId,
+            name: "UI Composite",
+            category: "ui",
+            layer: 2,
+            cpuMs: 0, gpuMs: 0, drawCalls: 0, triangles: 0,
+            pipelineSwitches: 0, bindGroupChanges: 0, bufferRebinds: 0,
+            active: true,
+        });
+        // Edge: layer 1 → UI (or scene → UI if no layer 1)
+        if (layer1NodeIds.length > 0) {
+            edges.push({
+                from: layer1NodeIds[layer1NodeIds.length - 1],
+                to: uiId,
+                resource: "canvas",
+                type: "color",
+            });
+        }
+        else if (lastSceneId) {
+            edges.push({
+                from: lastSceneId,
+                to: uiId,
+                resource: "canvas",
+                type: "color",
+            });
+        }
+        // --- Validation warnings ---
+        for (let _i = 0, _it = nodes, _n = _it.length; _i < _n; _i++) {
+            const node = _it[_i];
+            if (node.category !== "scene")
+                continue;
+            if (!node.active)
+                continue;
+            if (node.drawCalls === 0 && !alwaysOnPasses.includes(node.name)) {
+                validations.push({
+                    level: "info",
+                    message: `Pass "${node.name}" executed with 0 draw calls — consider skipping when empty`,
+                    passName: node.name,
+                });
+            }
+            if (node.pipelineSwitches > 0 && node.drawCalls > 0) {
+                const ratio = node.pipelineSwitches / node.drawCalls;
+                if (ratio > 2) {
+                    validations.push({
+                        level: "warning",
+                        message: `Pass "${node.name}" has ${node.pipelineSwitches} pipeline switches for ${node.drawCalls} draw calls (ratio ${ratio.toFixed(1)}) — excessive state changes`,
+                        passName: node.name,
+                    });
+                }
+            }
+            if (node.gpuMs > 3) {
+                validations.push({
+                    level: "warning",
+                    message: `Pass "${node.name}" took ${node.gpuMs.toFixed(2)}ms GPU time — exceeds 3ms budget`,
+                    passName: node.name,
+                });
+            }
+        }
+        // Check for inactive scene passes that are always-on
+        alwaysOnPasses.forEach((name) => {
+            const node = nodes.find(n => n.name === name);
+            if (node && !node.active) {
+                validations.push({
+                    level: "info",
+                    message: `Pass "${name}" was not executed this frame`,
+                    passName: name,
+                });
+            }
+        });
+        return {
+            nodes,
+            edges,
+            validations,
+            totalGpuMs,
+            totalCpuMs,
+            totalDrawCalls,
+            totalTriangles,
+            timestamp: performance.now(),
+        };
+    }
+    destroy() {
+        this.gpuTimerPool?.destroy();
+        this.gpuTimerPool = null;
+    }
+}