@downdraft/engine 0.1.1 → 0.2.0

package/dist/core/src/render/game-renderer.js

@@ -0,0 +1,1165 @@
+// ============================================================================
+// GameRenderer — generic WebGPU render loop infrastructure
+// Extracted from WebGPURenderer: device init, surface config, rAF loop,
+// frame rate limiter, viewport management, telemetry, GPU UI pass, depth cache.
+// Games register render passes via FrameGraph slots and provide game-specific
+// logic through callback hooks.
+// ============================================================================
+import { UIInputRouter } from "../input/ui-router.js";
+import { getHostCapabilities, getNativeHost } from "../platform/runtime.js";
+import { TelemetryCollector } from "../telemetry/collector.js";
+import { GPUProfiler } from "../telemetry/gpu-profiler.js";
+import { GPUResourceTracker } from "../telemetry/gpu-resource-tracker.js";
+import { createLogger } from "../util/logger.js";
+import { CanvasResizeWatcher } from "./canvas-resize-watcher.js";
+import { GPUDeviceManager } from "./device.js";
+import { FrameGraph } from "./frame-graph.js";
+import { InputManager } from "./input-manager.js";
+import { RendererModuleHost } from "./renderer-module-host.js";
+import { installShaderValidationGuard } from "./shader-validator.js";
+const log = createLogger();
+export class GameRenderer {
+    canvas;
+    device = null;
+    adapter = null;
+    context = null;
+    format = "bgra8unorm";
+    config;
+    depthFormat = "depth32float";
+    msaaSampleCount = 1;
+    mode = "3d";
+    // Infrastructure
+    deviceManager;
+    resizeWatcher = null;
+    inputManager;
+    frameGraph;
+    rendererModuleHost = null;
+    // Telemetry & profiling
+    gpuProfiler = null;
+    gpuResourceTracker = null;
+    telemetryCollector = null;
+    /** Input router for the active UI stack (html-ui via Blitz, or none). */
+    uiInputRouter = null;
+    /** Screen-space compositors (html-ui panels etc.) drawn in the UI pass. */
+    uiCompositors = new Set();
+    // Render loop state
+    running = false;
+    deviceLost = false;
+    /** True when init() borrowed the native host's device — the surface was
+     *  already configured by the host, so the renderer must not reconfigure. */
+    hostConfiguredSurface = false;
+    lastTime = 0;
+    elapsedTime = 0;
+    fps = 0;
+    frameCount = 0;
+    fpsTimer = 0;
+    lastResourceStatsTime = 0;
+    static RESOURCE_STATS_INTERVAL = 1000;
+    // Frame rate limiter
+    targetFrameTime = 0;
+    limiterActive = false;
+    frameAccum = 0;
+    lastLimiterTick = 0;
+    rafInterval = 0;
+    rafSum = 0;
+    rafCount = 0;
+    lastRafTime = 0;
+    // Viewport management
+    viewportCount = 1;
+    viewports = [];
+    // Transient surface/depth handles (imported into the frame graph each frame)
+    colorHandle = null;
+    depthHandle = null;
+    graphCompiled = false;
+    // Reusable per-frame RenderContext (mutated per viewport — see renderViewport)
+    frameCtx = null;
+    // Depth texture cache (used when the graph does not own depth)
+    // LRU: Map insertion order = access order (delete + re-set on access).
+    depthTextures = new Map();
+    depthTextureCacheSize;
+    // Frame stats
+    frameDrawCalls = 0;
+    frameTriangles = 0;
+    // Callbacks
+    callbacks = {};
+    // Offscreen mode (set by game for postprocessing)
+    offscreenMode = null;
+    // XR render target provider (overrides canvas surface when set)
+    renderTargetProvider = null;
+    // rAF source override (for XR sessions)
+    rafSource = null;
+    cancelRaf = null;
+    currentRafId = 0;
+    // Dedup for the render chain: exactly one pending rAF may exist at a time.
+    // renderFrame() is also called outside the loop by renderOnce() (native
+    // screenshots, deterministic steps); letting it re-schedule leaked a
+    // permanent second (third, ...) render chain per call — each chain ran
+    // renderFrame() every pump tick, multiplying both real render work and the
+    // FPS counter (the "1100 fps" badge after MCP screenshot calls).
+    rafPending = false;
+    // Dpr
+    dpr = 1;
+    constructor(canvas, config = {}) {
+        this.canvas = canvas;
+        this.config = config;
+        this.depthFormat = config.depthFormat ?? "depth32float";
+        this.msaaSampleCount = config.msaaSampleCount ?? 1;
+        this.depthTextureCacheSize = config.depthTextureCacheSize ?? 3;
+        this.mode = config.mode ?? "3d";
+        this.deviceManager = new GPUDeviceManager();
+        this.inputManager = new InputManager(canvas, config.enablePointerLock ?? false);
+        this.frameGraph = new FrameGraph();
+    }
+    /** Build requiredLimits for the bindless binding model (clamped to adapter). */
+    buildRequiredLimits(adapter) {
+        const a = adapter.limits;
+        const clamp = (key, want) => {
+            const have = a[key];
+            if (have === undefined)
+                return null;
+            return [key, Math.min(want, Number(have))];
+        };
+        const entries = [];
+        [
+            clamp("maxTextureArrayLayers", 512),
+            clamp("maxStorageBuffersPerShaderStage", 8),
+            clamp("maxStorageBufferBindingSize", 64 * 1024 * 1024),
+            clamp("maxSampledTexturesPerShaderStage", 16),
+        ].forEach((e) => {
+            if (e)
+                entries.push(e);
+        });
+        return Object.fromEntries(entries);
+    }
+    async init() {
+        try {
+            // Device resolution order: explicit config → native host's device →
+            // self-acquire. On native the host owns the only wgpu device and the
+            // surface context — borrowing it avoids a second requestDevice() and
+            // a reconfigure race on the same surface. In-process there is
+            // exactly one device.
+            const nativeHost = getNativeHost();
+            const borrowedDevice = this.config.device ?? nativeHost?.device;
+            const borrowedAdapter = this.config.adapter ?? nativeHost?.adapter;
+            // An adapter is only required when we must acquire the device ourselves;
+            // a borrowed device is already usable (adapter.info is null-tolerated
+            // below).
+            const adapter = borrowedAdapter ?? await this.requestAdapterWithFallback();
+            if (!adapter && !borrowedDevice) {
+                log.error("game-renderer", "No GPU adapter found — check GPU drivers and /dev/dri permissions");
+                return false;
+            }
+            this.device = borrowedDevice ?? await this.requestDeviceFromAdapter(adapter);
+            this.adapter = adapter;
+            // The host configured the surface with its own usage set at creation —
+            // reconfiguring here would tear down the swapchain and race the host's
+            // readback hook. Skip when borrowing the host's device.
+            this.hostConfiguredSurface =
+                borrowedDevice !== undefined && borrowedDevice === nativeHost?.device;
+            // Install the shader validation guard so all createShaderModule calls
+            // route through getCompilationInfo() validation.
+            installShaderValidationGuard(this.device);
+            // Wrap device with GPU resource tracker for VRAM visibility
+            this.gpuResourceTracker = new GPUResourceTracker();
+            this.gpuResourceTracker.wrapDevice(this.device);
+            // GPU profiler
+            const adapterInfo = adapter?.info ?? null;
+            this.context = this.canvas.getContext("webgpu");
+            this.format = navigator.gpu.getPreferredCanvasFormat();
+            this.gpuProfiler = new GPUProfiler();
+            this.gpuProfiler.init(this.device, adapterInfo, this.format, 32);
+            log.debug("game-renderer", `GPU timer pool supported: ${this.gpuProfiler.isGpuTimerSupported()} features: ${Array.from(this.device.features).join(", ")}`);
+            // Device lost handler
+            this.device.lost.then((info) => {
+                this.handleDeviceLost(info);
+            });
+            // Configure surface — skipped when the surface was already configured
+            // by the device owner (native host) or the caller opted out. A borrowed
+            // host surface is never reconfigured: the host's usage set and
+            // pre-present readback hook are bound to its configure call.
+            if (!this.hostConfiguredSurface && (this.config.configureSurface ?? true)) {
+                this.context.configure({
+                    device: this.device,
+                    format: this.format,
+                    alphaMode: "premultiplied",
+                });
+            }
+            // UI input router — the active UI stack (html-ui via Blitz) replaces
+            // this with its own router when its module registers.
+            this.uiInputRouter = new UIInputRouter();
+            this.inputManager.setUIInputRouter(this.uiInputRouter);
+            // Telemetry
+            this.telemetryCollector = new TelemetryCollector(this.config.enableTelemetry ?? true);
+            // Canvas resize watcher
+            this.resizeWatcher = new CanvasResizeWatcher(this.canvas, this);
+            // Input listeners
+            this.inputManager.setupListeners();
+            // Renderer plugin host — owns renderer-thread plugins (camera
+            // controllers, gizmos, XR frame loops, OSR). Created after InputManager
+            // so the host's input bus coexists with the FPS/pointer-lock layer.
+            this.rendererModuleHost = new RendererModuleHost(this.canvas, {
+                getSurface: () => this.canvas,
+                getDevice: () => this.device,
+                getFormat: () => this.format,
+                getGraph: () => this.frameGraph,
+                getSlotRegistry: () => this.frameGraph.getSlotRegistry(),
+                setOffscreenMode: (mode) => this.setOffscreenMode(mode),
+                setRenderTargetProvider: (provider) => this.setRenderTargetProvider(provider),
+                setRAFSource: (src, cancel) => {
+                    if (src && cancel)
+                        this.setRAFSource(src, cancel);
+                    else
+                        this.clearRAFSource();
+                },
+                setViewportCount: (count) => this.setViewportCount(count),
+                getUIInputRouter: () => this.uiInputRouter,
+                registerUiCompositor: (c) => {
+                    this.uiCompositors.add(c);
+                    return () => this.uiCompositors.delete(c);
+                },
+            });
+            // Initial viewport layout
+            this.updateViewports(1);
+            log.info("game-renderer", "initialized");
+            return true;
+        }
+        catch (err) {
+            log.error("game-renderer", `Init failed: ${err}`);
+            return false;
+        }
+    }
+    // --- Device acquisition + loss recovery ---
+    /** Adapter fallback chain: high-performance → low-power → any. */
+    async requestAdapterWithFallback() {
+        let adapter = await navigator.gpu.requestAdapter({
+            powerPreference: "high-performance",
+        });
+        if (!adapter) {
+            log.warn("game-renderer", "No high-performance GPU adapter, trying low-power...");
+            adapter = await navigator.gpu.requestAdapter({
+                powerPreference: "low-power",
+            });
+        }
+        if (!adapter) {
+            log.warn("game-renderer", "No low-power adapter, trying any...");
+            adapter = await navigator.gpu.requestAdapter({});
+        }
+        return adapter;
+    }
+    async requestDeviceFromAdapter(adapter) {
+        // Request timestamp-query features for GPU-side per-pass timing
+        const requiredFeatures = [];
+        if (adapter.features.has("timestamp-query")) {
+            requiredFeatures.push("timestamp-query");
+        }
+        return adapter.requestDevice({
+            requiredFeatures,
+            requiredLimits: this.buildRequiredLimits(adapter),
+        });
+    }
+    recoveringDevice = false;
+    handleDeviceLost(info) {
+        if (this.deviceLost || this.recoveringDevice)
+            return; // already handled
+        this.deviceLost = true;
+        log.error("game-renderer", `WebGPU device lost: ${info?.reason ?? "unknown"} — ${info?.message ?? ""}`);
+        try {
+            this.callbacks.onDeviceLost?.(info);
+        }
+        catch (err) {
+            log.error("game-renderer", `onDeviceLost callback threw: ${err}`);
+        }
+        if ((this.config.deviceLossRecovery ?? "auto") === "reload" ||
+            info?.reason === "destroyed" ||
+            this.hostConfiguredSurface) {
+            // "destroyed" = device.destroy() was called deliberately — a new device
+            // can't help, the app is tearing down or opted out. A borrowed host
+            // device can't be recovered in place either: the host's surface
+            // configure and readback hook are bound to the dead device, and every
+            // other holder of it (bridge, devtools hosts) would still point at
+            // the old handle. Restart instead.
+            this.reloadForDeviceLoss();
+            return;
+        }
+        this.recoverDevice();
+    }
+    reloadForDeviceLoss() {
+        setTimeout(() => {
+            // Host already tearing down (host.destroy() destroys the device,
+            // which resolves .lost with reason "destroyed") — restarting now
+            // would respawn a session on top of a dead window.
+            if (globalThis.__nativeHost?.destroyed)
+                return;
+            // Native runtime: window.location.reload() is a no-op. Route through
+            // the host's first-class restart hook (detached self-respawn — the
+            // real reload equivalent), then fall back to a dialog + clean quit if
+            // the restart budget is exhausted.
+            const req = globalThis.downdraft?.requestRestart;
+            if (typeof req === "function" && req("GPU device lost"))
+                return;
+            const nativeWin = globalThis.__nativeWindow;
+            if (nativeWin?.showMessageBox) {
+                try {
+                    nativeWin.showMessageBox("GPU Device Lost", "The GPU device was lost and could not be recovered. The application will now close.");
+                }
+                catch { /* window may be gone */ }
+                try {
+                    nativeWin.requestQuit?.();
+                }
+                catch { /* best-effort */ }
+                return;
+            }
+            log.warn("game-renderer", "Attempting page reload for GPU recovery...");
+            window.location.reload();
+        }, 2000);
+    }
+    /**
+     * Attempt in-place device recovery: re-acquire adapter+device, reconfigure
+     * the surface, re-prepare UI/profiler and every registered frame-graph
+     * pass, then recompile the graph (transient textures get fresh allocations
+     * on the new device). Falls back to a page reload on any failure.
+     */
+    async recoverDevice() {
+        this.recoveringDevice = true;
+        try {
+            const adapter = await this.requestAdapterWithFallback();
+            if (!adapter)
+                throw new Error("no GPU adapter after device loss");
+            const device = await this.requestDeviceFromAdapter(adapter);
+            device.lost.then((info) => this.handleDeviceLost(info));
+            this.device = device;
+            this.adapter = adapter;
+            installShaderValidationGuard(device);
+            this.gpuResourceTracker = new GPUResourceTracker();
+            this.gpuResourceTracker.wrapDevice(device);
+            this.context.configure({
+                device,
+                format: this.format,
+                alphaMode: "premultiplied",
+            });
+            const adapterInfo = adapter.info ?? null;
+            this.gpuProfiler?.init(device, adapterInfo, this.format, 32);
+            // Re-prepare every registered pass — pipelines/bind groups built on the
+            // dead device are invalid. Passes that can't recreate resources should
+            // throw here so we fall back to reload.
+            for (const pass of this.frameGraph.getPasses()) {
+                pass.prepare(device);
+            }
+            // Force graph recompile so transient textures are re-allocated on the
+            // new device — pooled physical textures and cached views all belong to
+            // the dead device and must not be reused.
+            this.frameGraph.invalidatePhysicalResources();
+            this.graphCompiled = false;
+            await this.onDeviceRecovered(device);
+            await this.callbacks.onDeviceRecovered?.(device);
+            this.deviceLost = false;
+            log.warn("game-renderer", "GPU device recovered — rendering resumed without reload");
+        }
+        catch (err) {
+            log.error("game-renderer", `Device recovery failed: ${err}`);
+            this.reloadForDeviceLoss();
+        }
+        finally {
+            this.recoveringDevice = false;
+        }
+    }
+    /**
+     * Subclass hook — called during device-loss recovery after the engine has
+     * re-prepared its own resources and all registered passes. Recreate
+     * subclass-owned GPU resources here. Throwing aborts recovery → reload.
+     */
+    async onDeviceRecovered(_device) { }
+    // --- CanvasResizeHandler ---
+    resolutionScale = 1;
+    lastCssW = 0;
+    lastCssH = 0;
+    lastRawDpr = 1;
+    /**
+     * Render-resolution scale [0.25..1]. Multiplies the effective DPR so the
+     * swap chain renders fewer pixels (performance) and the compositor
+     * upscales. Re-applies the last known canvas size immediately.
+     */
+    setResolutionScale(scale) {
+        this.resolutionScale = Math.max(0.25, Math.min(1, scale));
+        if (!getHostCapabilities().hasDom) {
+            // On the native host the swapchain extent must equal the window's
+            // real size — wgpu compares the configured size against the surface's
+            // currentExtent at acquire time and returns Outdated forever when
+            // they differ. Shrinking canvas.width/height would also corrupt
+            // clientWidth (UI layout + input coords). Resolution scaling needs
+            // an offscreen-render + upscale path to work here; for now it is a
+            // no-op rather than a brick.
+            if (this.resolutionScale < 1) {
+                log.warn("game-renderer", "resolutionScale is not supported on the native surface (swapchain must match the window size) — ignoring");
+            }
+        }
+        if (this.lastCssW > 0)
+            this.onResize(this.lastCssW, this.lastCssH, this.lastRawDpr);
+    }
+    getResolutionScale() {
+        return this.resolutionScale;
+    }
+    onResize(cssWidth, cssHeight, dpr) {
+        this.lastCssW = cssWidth;
+        this.lastCssH = cssHeight;
+        this.lastRawDpr = dpr;
+        // Render at the display's real DPR — resolutionScale is the opt-in
+        // performance knob when fill rate is a concern. On native the
+        // swapchain is window-sized (see setResolutionScale) so the scale is
+        // never applied to the backing store.
+        const cappedDpr = dpr * (getHostCapabilities().hasDom ? this.resolutionScale : 1);
+        this.dpr = cappedDpr;
+        const w = Math.round(cssWidth * cappedDpr);
+        const h = Math.round(cssHeight * cappedDpr);
+        if (this.canvas.width !== w)
+            this.canvas.width = w;
+        if (this.canvas.height !== h)
+            this.canvas.height = h;
+        this.updateViewports(this.viewportCount);
+        this.callbacks.onResize?.(cssWidth, cssHeight, dpr);
+        this.rendererModuleHost?.dispatchResize(cssWidth, cssHeight, dpr);
+    }
+    // --- Viewport management ---
+    setViewportCount(count) {
+        this.updateViewports(count);
+    }
+    getViewportCount() {
+        return this.viewportCount;
+    }
+    getViewport(idx) {
+        return this.viewports[idx] ?? null;
+    }
+    getViewports() {
+        return this.viewports;
+    }
+    updateViewports(count) {
+        this.viewportCount = count;
+        this.viewports = [];
+        const w = this.canvas.width;
+        const h = this.canvas.height;
+        if (count === 1) {
+            this.viewports.push({ x: 0, y: 0, w, h });
+        }
+        else if (count === 2) {
+            this.viewports.push({ x: 0, y: 0, w: w / 2, h });
+            this.viewports.push({ x: w / 2, y: 0, w: w / 2, h });
+        }
+        else if (count === 3) {
+            this.viewports.push({ x: 0, y: 0, w, h: h / 2 });
+            this.viewports.push({ x: 0, y: h / 2, w: w / 2, h: h / 2 });
+            this.viewports.push({ x: w / 2, y: h / 2, w: w / 2, h: h / 2 });
+        }
+        else if (count >= 4) {
+            this.viewports.push({ x: 0, y: 0, w: w / 2, h: h / 2 });
+            this.viewports.push({ x: w / 2, y: 0, w: w / 2, h: h / 2 });
+            this.viewports.push({ x: 0, y: h / 2, w: w / 2, h: h / 2 });
+            this.viewports.push({ x: w / 2, y: h / 2, w: w / 2, h: h / 2 });
+        }
+    }
+    // --- Frame rate limiter ---
+    setFrameRateLimit(refreshRate) {
+        if (refreshRate > 0) {
+            this.targetFrameTime = 1000 / refreshRate;
+            this.updateLimiterState();
+        }
+        else {
+            this.targetFrameTime = 0;
+            this.limiterActive = false;
+        }
+    }
+    updateLimiterState() {
+        if (this.targetFrameTime <= 0 || this.rafInterval <= 0) {
+            this.limiterActive = this.targetFrameTime > 0;
+            return;
+        }
+        this.limiterActive = this.rafInterval < this.targetFrameTime * 0.85;
+    }
+    // --- Render loop ---
+    start() {
+        this.running = true;
+        this.lastTime = performance.now();
+        // Go through scheduleRender() rather than invoking render() inline — a
+        // pending rAF (loop already primed) would otherwise survive alongside the
+        // new registration and double the chain.
+        this.scheduleRender();
+    }
+    stop() {
+        this.running = false;
+        // cancelRaf only exists when a rAF source override (XR) is installed —
+        // fall back to the global so the pending callback is actually removed.
+        const cancel = this.cancelRaf ?? (typeof cancelAnimationFrame === "function" ? cancelAnimationFrame : null);
+        if (cancel && this.currentRafId) {
+            cancel(this.currentRafId);
+            this.currentRafId = 0;
+        }
+        this.rafPending = false;
+    }
+    /** True while the render loop is started (frames are being scheduled). */
+    isRunning() {
+        return this.running;
+    }
+    /** Render a single frame on demand — deterministic/test mode and native
+     *  screenshot capture call this while the loop is stopped. Bypasses the
+     *  frame limiter; safe to call with the loop running or stopped. */
+    renderOnce() {
+        if (!this.device || !this.context || this.deviceLost)
+            return;
+        const savedLimiter = this.limiterActive;
+        this.limiterActive = false;
+        try {
+            this.prepareForcedFrame();
+            this.renderFrame();
+        }
+        finally {
+            this.limiterActive = savedLimiter;
+        }
+    }
+    /** Subclass hook: clear internal dirty-tracking so renderOnce() actually
+     *  draws. Renderers that skip unchanged frames (e.g. MiningRenderer's
+     *  forceDirty check) override this to force the next frame out. */
+    prepareForcedFrame() { }
+    /** Schedule the next render() invocation. Centralized here so renderFrame()
+     *  stays scheduling-free — renderOnce() and test paths call renderFrame()
+     *  directly and must never grow a parallel loop. */
+    scheduleRender() {
+        if (this.rafPending)
+            return;
+        this.rafPending = true;
+        this.currentRafId = this.rafSource ? this.rafSource(this.render) : requestAnimationFrame(this.render);
+    }
+    render = () => {
+        this.rafPending = false;
+        this.currentRafId = 0;
+        if (!this.running)
+            return;
+        if (!this.device || !this.context) {
+            // init() hasn't finished — keep the chain alive until it has.
+            this.scheduleRender();
+            return;
+        }
+        // Measure rAF interval (rolling average over 60 samples)
+        const rafNow = performance.now();
+        if (this.lastRafTime > 0) {
+            this.rafSum += rafNow - this.lastRafTime;
+            this.rafCount++;
+            if (this.rafCount >= 60) {
+                this.rafInterval = this.rafSum / this.rafCount;
+                this.rafSum = 0;
+                this.rafCount = 0;
+                this.updateLimiterState();
+            }
+        }
+        this.lastRafTime = rafNow;
+        if (this.deviceLost) {
+            // Keep the loop alive while the device is lost — handleDeviceLost()
+            // re-creates the device and clears this flag; returning without
+            // re-scheduling would permanently stop rendering after a transient
+            // GPU crash.
+            this.scheduleRender();
+            return;
+        }
+        try {
+            this.renderFrame();
+        }
+        catch (err) {
+            log.error("game-renderer", `Render loop error: ${err.message}\n${err.stack}`);
+            if (this.device?.lost) {
+                this.device.lost.then((info) => {
+                    this.handleDeviceLost(info);
+                });
+            }
+        }
+        this.scheduleRender();
+    };
+    renderFrame() {
+        const now = performance.now();
+        // Frame rate limiter: phase accumulator (skip during XR — XR drives its own cadence)
+        // Accumulate real elapsed time in frame units — NOT rafInterval ratios.
+        // The ratio variant starved on hosts with a faster-than-vsync rAF pump
+        // (native SDL loop ticks at ~µs cadence): updateLimiterState() resets
+        // frameAccum every 60 rAF samples, and 60 × rafInterval/targetFrameTime
+        // never reached 1, so present() was never called.
+        if (!this.renderTargetProvider && this.limiterActive && this.targetFrameTime > 0) {
+            if (this.lastLimiterTick === 0)
+                this.lastLimiterTick = now;
+            this.frameAccum += (now - this.lastLimiterTick) / this.targetFrameTime;
+            this.lastLimiterTick = now;
+            if (this.frameAccum < 1) {
+                // render() owns re-scheduling — just skip the frame's work.
+                return;
+            }
+            // Cap carry at one frame — a stale lastLimiterTick (limiter toggled
+            // off→on) would otherwise burst-render to drain a huge accumulator.
+            this.frameAccum = Math.min(this.frameAccum - 1, 1);
+        }
+        const dt = Math.min(0.1, (now - this.lastTime) / 1000);
+        this.lastTime = now;
+        this.elapsedTime += dt;
+        // FPS counter
+        this.frameCount++;
+        this.fpsTimer += dt;
+        if (this.fpsTimer >= 1) {
+            this.fps = this.frameCount;
+            this.frameCount = 0;
+            this.fpsTimer = 0;
+        }
+        // Before frame callback (game-specific: camera updates, input processing)
+        this.callbacks.beforeFrame?.(dt, this.elapsedTime);
+        this.rendererModuleHost?.dispatchFrame("beforeFrame", dt, this.elapsedTime);
+        // Before viewports callback (game-specific: particle ticks, pre-viewport setup)
+        this.callbacks.beforeViewports?.(dt, this.elapsedTime);
+        this.rendererModuleHost?.dispatchFrame("beforeViewports", dt, this.elapsedTime);
+        // If an uncaptured GPU error has fired, skip all GPU work this frame to
+        // avoid the per-frame cascade of native "is invalid due to a previous
+        // error" validation warnings. Game logic callbacks still run so the
+        // simulation stays responsive. The flag is cleared by recovery code that
+        // recreates the invalid resources.
+        const gpuError = this.gpuProfiler?.hasUncapturedError() ?? false;
+        // XR render target provider beginFrame hook
+        if (this.renderTargetProvider && !gpuError) {
+            this.renderTargetProvider.beginFrame();
+        }
+        // Render each viewport
+        const offscreen = this.offscreenMode;
+        const useOffscreen = offscreen && offscreen.type !== "none";
+        if (offscreen && useOffscreen && offscreen.ensureTargets && !gpuError) {
+            offscreen.ensureTargets(this.canvas.width, this.canvas.height);
+        }
+        // Collect command buffers from all phases and submit once at the end
+        // (reduces CPU→GPU sync points from 3+ per frame to 1).
+        const frameCommandBuffers = [];
+        if (!gpuError) {
+            // 2D mode with viewportCount=0: clear the canvas if a clearColor is
+            // configured, then let the afterFrame callback do custom rendering.
+            if (this.viewportCount === 0 && this.device && this.context && this.config.clearColor !== null) {
+                const clearTex = this.getSurfaceTexture();
+                if (clearTex) {
+                    const clearEncoder = this.device.createCommandEncoder();
+                    const clearPass = clearEncoder.beginRenderPass({
+                        colorAttachments: [{
+                                view: clearTex.createView(),
+                                clearValue: this.config.clearColor ?? { r: 0, g: 0, b: 0, a: 1 },
+                                loadOp: "clear",
+                                storeOp: "store",
+                            }],
+                    });
+                    clearPass.end();
+                    frameCommandBuffers.push(clearEncoder.finish());
+                }
+            }
+            for (let v = 0; v < this.viewportCount; v++) {
+                const cb = this.renderViewport(v, dt, offscreen);
+                if (cb)
+                    frameCommandBuffers.push(cb);
+            }
+            // Apply postprocessing
+            if (offscreen && useOffscreen && offscreen.applyPostprocess) {
+                const canvasView = this.getSurfaceTexture()?.createView();
+                if (canvasView) {
+                    const postEncoder = this.device.createCommandEncoder();
+                    offscreen.applyPostprocess(postEncoder, canvasView, this.canvas.width, this.canvas.height);
+                    frameCommandBuffers.push(postEncoder.finish());
+                }
+            }
+        }
+        // After viewports callback
+        this.callbacks.afterViewports?.(dt, this.elapsedTime);
+        this.rendererModuleHost?.dispatchFrame("afterViewports", dt, this.elapsedTime);
+        // Worker-produced passes (postPass → "preSubmit" slot on the native
+        // host's GpuPassMailbox) join this frame's submit batch — refs that
+        // arrived since the last drain execute after the owner's buffers.
+        // Stale-tolerant by design: a worker that misses the drain lands next
+        // frame instead of rendezvousing the render thread.
+        const passMailbox = getNativeHost()?.passMailbox;
+        if (passMailbox) {
+            frameCommandBuffers.push(...passMailbox.drain("preSubmit"));
+        }
+        // Submit all command buffers for this frame in a single queue.submit() call
+        if (frameCommandBuffers.length > 0) {
+            this.device.queue.submit(frameCommandBuffers);
+        }
+        // Read GPU timer results asynchronously (1-frame latency).
+        // Must be called AFTER queue.submit() — readGpuTimers() calls mapAsync on
+        // the read buffer, and a mapped/mapping-pending buffer cannot be used in a
+        // submitted command buffer (the copy-to-readBuffer was encoded above).
+        if (this.gpuProfiler) {
+            this.gpuProfiler.readGpuTimers().then(() => {
+                // Results available for next frame
+            }).catch(() => { });
+        }
+        // Record telemetry
+        if (this.telemetryCollector) {
+            this.telemetryCollector.recordFrame(dt * 1000);
+            this.telemetryCollector.recordDrawStats(this.frameDrawCalls, this.frameTriangles);
+            this.telemetryCollector.recordGraphSample(dt * 1000);
+            if (this.gpuProfiler) {
+                for (const timing of this.gpuProfiler.getPassTimings()) {
+                    this.telemetryCollector.recordPassTiming(timing);
+                }
+            }
+            if (this.gpuResourceTracker && now - this.lastResourceStatsTime > GameRenderer.RESOURCE_STATS_INTERVAL) {
+                this.lastResourceStatsTime = now;
+                const resStats = this.gpuResourceTracker.getStats();
+                this.telemetryCollector.recordResourceStats({
+                    textureCount: resStats.textureCount,
+                    bufferCount: resStats.bufferCount,
+                    totalBytes: resStats.totalBytes,
+                    textureBytes: resStats.textureBytes,
+                    bufferBytes: resStats.bufferBytes,
+                    resources: resStats.resources.map((r) => ({
+                        id: r.id,
+                        type: r.type,
+                        label: r.label,
+                        size: r.size,
+                        callsite: r.callsite,
+                        width: r.width,
+                        height: r.height,
+                        format: r.format,
+                    })),
+                });
+            }
+            this.frameDrawCalls = 0;
+            this.frameTriangles = 0;
+        }
+        // XR render target provider endFrame hook (skip on GPU error)
+        if (!gpuError && this.renderTargetProvider && this.device) {
+            this.renderTargetProvider.endFrame(this.device.createCommandEncoder());
+        }
+        // After frame callback
+        this.callbacks.afterFrame?.(dt, this.elapsedTime);
+        this.rendererModuleHost?.dispatchFrame("afterFrame", dt, this.elapsedTime);
+        // Composite registered screen-space UI (html-ui panels) on top of the
+        // final image (skip on GPU error to avoid cascade). This must run AFTER
+        // afterFrame — 2D games (viewportCount=0) do their custom rendering in
+        // the afterFrame callback, so drawing UI earlier would put it underneath
+        // their clear pass.
+        if (!gpuError && this.device && this.context) {
+            const compositors = [...this.uiCompositors]
+                .filter((c) => c.hasContent())
+                .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+            const uiCanvasView = compositors.length > 0
+                ? this.getSurfaceTexture()?.createView()
+                : undefined;
+            if (uiCanvasView) {
+                const uiEncoder = this.device.createCommandEncoder();
+                const uiPass = uiEncoder.beginRenderPass({
+                    colorAttachments: [{
+                            view: uiCanvasView,
+                            clearValue: { r: 0, g: 0, b: 0, a: 0 },
+                            loadOp: "load",
+                            storeOp: "store",
+                        }],
+                });
+                compositors.forEach((c) => { c.render(uiPass, this.canvas.width, this.canvas.height); });
+                uiPass.end();
+                // "preUi" slot — worker passes ordered ahead of the UI-composite
+                // submit so their output is visible to the compositor this frame.
+                this.device.queue.submit([...(passMailbox?.drain("preUi") ?? []), uiEncoder.finish()]);
+            }
+        }
+        // Present the surface (native wgpu requires explicit presentation;
+        // in browsers this is automatic at the end of the frame). Must be last —
+        // all submissions targeting the surface texture happen above.
+        if (this.context && this.context.present) {
+            this.context.present();
+        }
+        const __rfTotal = performance.now() - now;
+        if (this.config.debugTimingWarnings && __rfTotal > 20)
+            log.warn("game-renderer", `renderFrame took ${__rfTotal.toFixed(1)}ms`);
+        // NOTE: renderFrame() intentionally does NOT schedule the next frame —
+        // render() owns the rAF chain so one-shot callers (renderOnce, MCP
+        // screenshot capture) can't leak parallel loops.
+    }
+    /**
+     * Acquire this frame's swapchain texture. May return null on the native
+     * runtime while the surface can't produce a frame (in-flight resize,
+     * occluded window, transient swapchain failure) — callers must skip the
+     * canvas-targeted GPU work for that frame instead of crashing on
+     * `null.createView()`.
+     */
+    getSurfaceTexture() {
+        try {
+            return this.context?.getCurrentTexture() ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    renderViewport(viewportIdx, dt, offscreen) {
+        if (!this.device || !this.context)
+            return null;
+        const xrProvider = this.renderTargetProvider;
+        const useOffscreen = !xrProvider && offscreen && offscreen.type !== "none";
+        const origViewport = xrProvider
+            ? xrProvider.getViewportRect(viewportIdx, this.canvas.width, this.canvas.height)
+            : this.viewports[viewportIdx];
+        if (!origViewport)
+            return null;
+        const viewport = (useOffscreen && offscreen?.scaleViewport)
+            ? offscreen.scaleViewport(origViewport)
+            : origViewport;
+        // Get camera info: viewport camera provider (XR) takes priority, then
+        // game callback, then renderer plugin host's camera controller fallback.
+        // The game callback is always called (even when the provider returns
+        // non-null) so side effects like per-eye uniform updates still run.
+        const providerInfo = this.rendererModuleHost?.getViewportCameraInfo(viewportIdx, dt, this.elapsedTime) ?? null;
+        const gameInfo = this.callbacks.onViewport?.(viewportIdx, dt, this.elapsedTime) ?? null;
+        let camInfo = providerInfo ?? gameInfo;
+        if (!camInfo && this.rendererModuleHost) {
+            const camState = this.rendererModuleHost.getCameraState(viewportIdx);
+            if (camState) {
+                camInfo = { camera: camState, viewport };
+            }
+        }
+        // 2D mode: if no camera info was provided, use a default orthographic
+        // camera that covers the full viewport. This allows 2D-only renderers
+        // (sand games, tile games) to use GameRenderer without a camera system.
+        if (!camInfo && this.mode === "2d") {
+            camInfo = {
+                camera: {
+                    position: [0, 0, 1],
+                    target: [0, 0, 0],
+                    up: [0, 1, 0],
+                    fov: 90,
+                    near: 0.1,
+                    far: 100,
+                    aspect: viewport.w / viewport.h,
+                },
+                viewport,
+            };
+        }
+        if (!camInfo)
+            return null;
+        const isFirst = viewportIdx === 0;
+        const isLast = viewportIdx === this.viewportCount - 1;
+        // Determine color/depth views — XR provider takes precedence, then offscreen, then canvas
+        const __ctStart = performance.now();
+        const colorView = xrProvider
+            ? xrProvider.getColorView(viewportIdx)
+            : (useOffscreen && offscreen)
+                ? (offscreen.type === "pixelation"
+                    ? offscreen.getColorView()
+                    : offscreen.type === "postprocess"
+                        ? (offscreen.getSceneColorView?.() ?? this.getSurfaceTexture()?.createView())
+                        : this.getSurfaceTexture()?.createView())
+                : this.getSurfaceTexture()?.createView();
+        const __ctMs = performance.now() - __ctStart;
+        // Swapchain couldn't produce a frame (native resize in flight, occluded
+        // window, transient failure) — skip this viewport's GPU work; game
+        // callbacks already ran above and the loop stays alive for next frame.
+        if (!colorView)
+            return null;
+        if (this.config.debugTimingWarnings && __ctMs > 20)
+            log.warn("game-renderer", `getCurrentTexture took ${__ctMs.toFixed(1)}ms`);
+        const depthView = xrProvider
+            ? xrProvider.getDepthView(viewportIdx, origViewport.w, origViewport.h)
+            : (useOffscreen && offscreen)
+                ? (offscreen.type === "pixelation"
+                    ? offscreen.getDepthView()
+                    : offscreen.type === "postprocess"
+                        ? (offscreen.getSceneDepthView?.() ?? this.createDepthTexture(origViewport.w, origViewport.h))
+                        : this.createDepthTexture(origViewport.w, origViewport.h))
+                : this.createDepthTexture(origViewport.w, origViewport.h);
+        // Ensure graph handles exist for the imported color/depth views.
+        if (!this.colorHandle) {
+            this.colorHandle = this.frameGraph.importTextureView("color", null);
+            this.frameGraph.markDirty();
+        }
+        if (!this.depthHandle) {
+            this.depthHandle = this.frameGraph.importTextureView("depth", null);
+            this.frameGraph.markDirty();
+        }
+        this.frameGraph.setImportedTextureView(this.colorHandle, colorView);
+        this.frameGraph.setImportedTextureView(this.depthHandle, depthView);
+        if (isFirst) {
+            this.gpuProfiler.beginFrame();
+        }
+        if (this.frameGraph.isDirty() || !this.graphCompiled) {
+            this.frameGraph.compile(this.device, this.canvas.width, this.canvas.height);
+            this.graphCompiled = true;
+        }
+        const encoder = this.device.createCommandEncoder();
+        // Reuse a single RenderContext across viewports/frames — allocating the
+        // ~35-field literal per viewport per frame was pure GC churn. Fields that
+        // vary per viewport are reassigned below; the closures capture `this` and
+        // are created once.
+        if (!this.frameCtx) {
+            this.frameCtx = {
+                device: this.device,
+                encoder,
+                pass: null,
+                camera: camInfo.camera,
+                viewport,
+                viewportIdx,
+                viewportCount: this.viewportCount,
+                dt,
+                elapsedTime: this.elapsedTime,
+                isFirstViewport: isFirst,
+                isLastViewport: isLast,
+                width: viewport.w,
+                height: viewport.h,
+                viewProj: undefined,
+                invViewProj: undefined,
+                prevViewProj: undefined,
+                cameraPos: camInfo.camera.position,
+                lightData: null,
+                lightViewProj: undefined,
+                mesh: null,
+                modelMatrix: undefined,
+                shadowsEnabled: false,
+                bloomEnabled: false,
+                shadowSampler: null,
+                debugQueue: null,
+                opaqueVertexBuffer: null,
+                opaqueIndexBuffer: null,
+                opaqueIndexCount: 0,
+                opaqueIndexFormat: "uint32",
+                getView: (h) => this.frameGraph.getTextureView(h),
+                getTexture: (h) => this.frameGraph.getTexture(h),
+                addDrawCalls: (n) => { this.frameDrawCalls += n; },
+                addTriangles: (n) => { this.frameTriangles += n; },
+            };
+        }
+        const ctx = this.frameCtx;
+        ctx.device = this.device;
+        ctx.encoder = encoder;
+        ctx.camera = camInfo.camera;
+        ctx.viewport = viewport;
+        ctx.viewportIdx = viewportIdx;
+        ctx.viewportCount = this.viewportCount;
+        ctx.dt = dt;
+        ctx.elapsedTime = this.elapsedTime;
+        ctx.isFirstViewport = isFirst;
+        ctx.isLastViewport = isLast;
+        ctx.width = viewport.w;
+        ctx.height = viewport.h;
+        ctx.cameraPos = camInfo.camera.position;
+        this.frameGraph.execute(ctx);
+        // Resolve GPU timestamp queries on first viewport.
+        // NOTE: readGpuTimers() (which calls mapAsync on the read buffer) must NOT
+        // be called here — the command buffer containing the copy-to-readBuffer
+        // hasn't been submitted yet. Calling mapAsync before submit puts the buffer
+        // in a mapped-pending state, and the subsequent queue.submit() fails with
+        // "Buffer used in submit while mapped." readGpuTimers() is called after
+        // submit in renderFrame().
+        if (isFirst) {
+            this.gpuProfiler.resolveGpuTimers(encoder);
+        }
+        return encoder.finish();
+    }
+    // --- Depth texture cache ---
+    createDepthTexture(w, h) {
+        if (!this.device)
+            throw new Error("No device");
+        const key = `${w}x${h}`;
+        let tex = this.depthTextures.get(key);
+        if (tex) {
+            // LRU: move to most-recently-used by re-inserting.
+            this.depthTextures.delete(key);
+            this.depthTextures.set(key, tex);
+        }
+        else {
+            tex = this.device.createTexture({
+                size: [w, h],
+                format: this.depthFormat,
+                usage: GPUTextureUsage.RENDER_ATTACHMENT,
+            });
+            this.depthTextures.set(key, tex);
+            // Evict oldest entries if over cap.
+            while (this.depthTextures.size > this.depthTextureCacheSize) {
+                const oldestKey = this.depthTextures.keys().next().value;
+                if (oldestKey === undefined)
+                    break;
+                const oldest = this.depthTextures.get(oldestKey);
+                this.depthTextures.delete(oldestKey);
+                oldest?.destroy();
+            }
+        }
+        return tex.createView();
+    }
+    // --- UI ---
+    // --- Offscreen mode ---
+    setOffscreenMode(mode) {
+        this.offscreenMode = mode;
+    }
+    getOffscreenMode() {
+        return this.offscreenMode;
+    }
+    // --- XR render target provider ---
+    setRenderTargetProvider(provider) {
+        this.renderTargetProvider = provider;
+    }
+    getRenderTargetProvider() {
+        return this.renderTargetProvider;
+    }
+    // --- rAF source override (for XR sessions) ---
+    setRAFSource(request, cancel) {
+        this.rafSource = request;
+        this.cancelRaf = cancel;
+    }
+    clearRAFSource() {
+        this.rafSource = null;
+        this.cancelRaf = null;
+    }
+    // --- Callbacks ---
+    setCallbacks(callbacks) {
+        this.callbacks = callbacks;
+    }
+    /** Get the current frame callbacks (for wrapping/extending). */
+    getCallbacks() {
+        return this.callbacks;
+    }
+    // --- Renderer plugins ---
+    useRendererModule(plugin) {
+        if (!this.rendererModuleHost) {
+            throw new Error("RendererModuleHost not initialized — call init() first");
+        }
+        this.rendererModuleHost.registerModule(plugin);
+    }
+    getRendererModuleHost() {
+        return this.rendererModuleHost;
+    }
+    /**
+     * Composite registered screen-space UI (html-ui panels via
+     * ctx.registerUiCompositor) onto the current surface texture.
+     *
+     * Renderers with a custom drawFrame()/present path that bypass
+     * renderFrame() must call this at end-of-frame — after post-processing
+     * lands on the surface, before present — or module-registered UI will
+     * never be drawn. renderFrame() itself uses the equivalent block inline;
+     * this helper only runs the compositors.
+     */
+    renderScreenUiCompositors() {
+        const compositors = [...this.uiCompositors]
+            .filter((c) => c.hasContent())
+            .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+        if (compositors.length === 0 || !this.device || !this.context)
+            return;
+        const canvasView = this.getSurfaceTexture()?.createView();
+        if (!canvasView)
+            return;
+        const uiEncoder = this.device.createCommandEncoder();
+        const uiPass = uiEncoder.beginRenderPass({
+            colorAttachments: [{
+                    view: canvasView,
+                    clearValue: { r: 0, g: 0, b: 0, a: 0 },
+                    loadOp: "load",
+                    storeOp: "store",
+                }],
+        });
+        compositors.forEach((c) => { c.render(uiPass, this.canvas.width, this.canvas.height); });
+        uiPass.end();
+        this.device.queue.submit([uiEncoder.finish()]);
+    }
+    // --- Getters ---
+    getDevice() {
+        return this.device;
+    }
+    getAdapter() {
+        return this.adapter;
+    }
+    getContext() {
+        return this.context;
+    }
+    getFormat() {
+        return this.format;
+    }
+    getDepthFormat() {
+        return this.depthFormat;
+    }
+    getMSAASampleCount() {
+        return this.msaaSampleCount;
+    }
+    /** The render surface this renderer draws into. Canonical accessor. */
+    getSurface() {
+        return this.canvas;
+    }
+    /** @deprecated Use getSurface() — the surface is not necessarily a DOM canvas. */
+    getCanvas() {
+        return this.canvas;
+    }
+    getCanvasWidth() {
+        return this.canvas.width;
+    }
+    getCanvasHeight() {
+        return this.canvas.height;
+    }
+    getFPS() {
+        return this.fps;
+    }
+    getElapsedTime() {
+        return this.elapsedTime;
+    }
+    getInputManager() {
+        return this.inputManager;
+    }
+    getGraph() {
+        return this.frameGraph;
+    }
+    getSlotRegistry() {
+        return this.frameGraph.getSlotRegistry();
+    }
+    getUIInputRouter() {
+        return this.uiInputRouter;
+    }
+    getTelemetryCollector() {
+        return this.telemetryCollector;
+    }
+    getGPUProfiler() {
+        return this.gpuProfiler;
+    }
+    getFrameGraph() {
+        if (!this.gpuProfiler)
+            return null;
+        const passTimings = this.gpuProfiler.getPassTimings();
+        const ppInfo = this.callbacks.getPostProcessInfo?.() ?? {
+            pixelationEnabled: false, pixelSize: 4, postProcessEffects: [],
+        };
+        const passNames = this.frameGraph.getPassOrder();
+        return GPUProfiler.buildFrameGraphData(passTimings, ppInfo, passNames);
+    }
+    getGPUResourceTracker() {
+        return this.gpuResourceTracker;
+    }
+    getGPUInfo() {
+        if (!this.gpuProfiler)
+            return null;
+        return this.gpuProfiler.getGPUInfo(this.canvas, this.msaaSampleCount);
+    }
+    getAdapterInfo() {
+        return this.gpuProfiler?.getAdapterInfo() ?? null;
+    }
+    getGPUErrors() {
+        return this.gpuProfiler?.getGPUErrors() ?? [];
+    }
+    clearGPUErrors() {
+        this.gpuProfiler?.clearGPUErrors();
+    }
+    getDpr() {
+        return this.dpr;
+    }
+    // --- Frame stats (for game passes to update) ---
+    addDrawCalls(n) {
+        this.frameDrawCalls += n;
+    }
+    addTriangles(n) {
+        this.frameTriangles += n;
+    }
+    // --- Destroy ---
+    destroy() {
+        this.running = false;
+        this.resizeWatcher?.destroy();
+        this.resizeWatcher = null;
+        this.rendererModuleHost?.disposeAll();
+        this.rendererModuleHost = null;
+        this.inputManager.destroy();
+        this.gpuProfiler?.destroy();
+        this.gpuProfiler = null;
+        this.telemetryCollector = null;
+        this.device = null;
+        for (const tex of this.depthTextures.values()) {
+            tex.destroy();
+        }
+        this.depthTextures.clear();
+    }
+}