@woosh/meep-engine 3.0.2 → 3.2.0

package/src/shade/renderer/Renderer.js

@@ -1,2436 +1,2436 @@
-import { assert } from "../../core/assert.js";
-import Signal from "../../core/events/signal/Signal.js";
-import Vector2 from "../../core/geom/Vector2.js";
-import { clamp } from "../../core/math/clamp.js";
-import { remap } from "../../core/math/remap.js";
-import { MetricCollection } from "../../engine/development/performance/MetricCollection.js";
-import {
-    MetricCollectionConsoleMonitor
-} from "../../engine/development/performance/monitor/MetricCollectionConsoleMonitor.js";
-import { FrameGraph } from "../../engine/graphics/render/frame_graph/FrameGraph.js";
-import { TextureDescriptor } from "../descriptor/texture/TextureDescriptor.js";
-import { WebGPUExtensionType } from "../descriptor/WebGPUExtensionType.js";
-import { ShadeDeviceFailure } from "../device/ShadeDeviceFailure.js";
-import { ShadeGPUCommandContext } from "../device/ShadeGPUCommandContext.js";
-import { CameraManager } from "./camera/CameraManager.js";
-import { shader_background } from "./deferred/shader_background.js";
-import { shader_composite_volumetrics } from "./deferred/shader_composite_volumetrics.js";
-import { shader_deferred_main, shader_deferred_main_restir } from "./deferred/shader_deferred_main.js";
-import { ReSTIRDI } from "./restir/di/ReSTIRDI.js";
-import { shader_tonemap_HDR } from "./deferred/shader_tonemap_HDR.js";
-import { shader_tonemap_LDR } from "./deferred/shader_tonemap_LDR.js";
-import { G_BUFFER_MIP_LEVELS } from "./gbuffer/G_BUFFER_MIP_LEVELS.js";
-import {
-    graph_rasterize_meshes_transparent_oit
-} from "./rasterize/native/oit/graph_rasterize_meshes_transparent_oit.js";
-import {
-    viz_rasterization_alpha_tested_pass_descriptor
-} from "./rasterize/native/viz/viz_rasterization_alpha_tested_pass_descriptor.js";
-import {
-    viz_rasterization_opaque_pass_descriptor
-} from "./rasterize/native/viz/viz_rasterization_opaque_pass_descriptor.js";
-import { RasterizationJob } from "./rasterize/RasterizationJob.js";
-import { graph_rasterize_scene } from "./rasterize/standard/graph_rasterize_scene.js";
-import { FrameContext } from "./extension/FrameContext.js";
-import { FramePhase } from "./extension/FramePhase.js";
-import { GBufferTextures } from "./extension/GBufferTextures.js";
-import { PresentTarget } from "./extension/PresentTarget.js";
-import { RenderExtensionRegistry } from "./extension/RenderExtensionRegistry.js";
-import { SceneColor } from "./extension/SceneColor.js";
-import { ViewTextures } from "./extension/ViewTextures.js";
-import { shader_brick4_diffuse } from "./global_illumination/brick4/gpu/draw/shader_brick4_diffuse.js";
-import {
-    shader_brick4_indirect_lighting
-} from "./global_illumination/brick4/gpu/draw/shader_brick4_indirect_lighting.js";
-import { shader_brick4_specular } from "./global_illumination/brick4/gpu/draw/shader_brick4_specular.js";
-import { shader_diffuse_IBL } from "./global_illumination/ibl/shader_diffuse_IBL.js";
-import { shader_specular_IBL } from "./global_illumination/ibl/shader_specular_IBL.js";
-import { GPULightProbeVolumeRenderer } from "./global_illumination/lpv/bake/GPULightProbeVolumeRenderer.js";
-import { shader_diffuse_LPV } from "./global_illumination/lpv/shader_diffuse_LPV.js";
-import { shader_resolve_indirect_lighting } from "./global_illumination/shader_resolve_indirect_lighting.js";
-import { GraphicsContext } from "./GraphicsContext.js";
-import { graph_build_light_clusters } from "./light/cluster/graph_build_light_clusters.js";
-import { AccumulatingPathTracer } from "./path_tracer/accumulating/AccumulatingPathTracer.js";
-import { graph_postprocess_bloom } from "./postprocess/bloom/graph_postprocess_bloom.js";
-import { shader_ffx_rcas } from "./postprocess/cas/shader_ffx_rcas.js";
-import { GPUCameraExposureManager } from "./postprocess/eye/GPUCameraExposureManager.js";
-import { NSS } from "./postprocess/nss/NSS.js";
-import { PostProcess } from "./postprocess/PostProcess.js";
-import { shader_depth_occlusion_clip } from "./postprocess/taa/shader_depth_occlusion_clip.js";
-import { TAA } from "./postprocess/taa/TAA.js";
-import { MotionBlur } from "./postprocess/motion_blur/MotionBlur.js";
-import { DepthOfField } from "./postprocess/dof/raymarch/DepthOfField.js";
-import { DepthOfFieldU } from "./postprocess/dof/gather/DepthOfFieldU.js";
-import { graph_add_per_object_velocity } from "./postprocess/velocity/graph_add_per_object_velocity.js";
-import { SceneManager } from "./scene/SceneManager.js";
-import { ShadeIndirectLightingMode } from "./ShadeIndirectLightingMode.js";
-import { ShadeUpscalerType } from "./ShadeUpscalerType.js";
-import { graph_image_pass } from "./shader/graph/graph_image_pass.js";
-import { graph_import_buffer } from "./shader/graph/graph_import_buffer.js";
-import { graph_import_texture } from "./shader/graph/graph_import_texture.js";
-import { CascadedSceneSDF } from "./shadow/sdf/cascade/CascadedSceneSDF.js";
-import { STATIC_GRAPHICS_ENGINE_ASSETS } from "./STATIC_GRAPHICS_ENGINE_ASSETS.js";
-import { shader_debug_velocity } from "./postprocess/velocity/shader_debug_velocity.js";
-import { GPUTextureContext } from "./texture/GPUTextureContext.js";
-import { RenderTarget } from "./texture/RenderTarget.js";
-import { View } from "./view/View.js";
-import { ViewManager } from "./view/ViewManager.js";
-
-const METRICS = new MetricCollection();
-METRICS.create({ name: 'frame_time' });
-
-/**
- * Depth and G-buffer textures carry {@link G_BUFFER_MIP_LEVELS} mip levels.
- * WebGPU's createTexture validation requires mipLevelCount <= floor(log2(max(w,h))) + 1,
- * so the internal resolution must never drop below 2^(G_BUFFER_MIP_LEVELS - 1)
- * or texture allocation will fail.
- * @type {number}
- */
-const INTERNAL_RESOLUTION_MIN = 1 << (G_BUFFER_MIP_LEVELS - 1);
-
-MetricCollectionConsoleMonitor.from(METRICS);
-
-export class Renderer {
-    /**
-     * Indexes current drawn frame
-     * @type {number}
-     */
-    #frame_count = 0;
-
-    get frame_count() {
-        return this.#frame_count;
-    }
-
-    /**
-     * @type {GPUCanvasContext}
-     */
-    context;
-
-    /**
-     * The HTMLCanvasElement (or OffscreenCanvas) bound to this renderer.
-     * If `initialize()` was called without a `context`, this is the canvas
-     * the renderer created — append it to the DOM to display the output.
-     *
-     * @returns {HTMLCanvasElement|OffscreenCanvas|undefined}
-     */
-    get canvas() {
-        return this.context?.canvas;
-    }
-
-    /**
-     * @type {GPUDevice}
-     */
-    device;
-
-    /**
-     * @type {GPUCameraExposureManager}
-     */
-    #autoexposure;
-
-    /**
-     * @type {SceneManager}
-     */
-    #scenes;
-
-    /**
-     * Only use for read-access
-     * @returns {SceneManager}
-     */
-    get scenes() {
-        return this.#scenes;
-    }
-
-    /**
-     * @type {CameraManager}
-     */
-    #cameras
-
-    /**
-     * @type {ViewManager}
-     */
-    #views
-
-
-    set feature_shadows_enabled(v) {
-        assert.isBoolean(v, 'v');
-        this.#feature_shadows_enabled = v;
-    }
-
-    get feature_shadows_enabled() {
-        return this.#feature_shadows_enabled;
-    }
-
-    /**
-     * Controls which indirect lighting technique is used for
-     * both deferred resolve and forward transparency passes.
-     * @type {ShadeIndirectLightingMode}
-     */
-    indirect_lighting_mode = ShadeIndirectLightingMode.IBL;
-
-    feature_ssr_enabled = false;
-    feature_ssao_enabled = true;
-    /**
-     * ReSTIR DI — stochastic screen-bounded direct shadowing of local
-     * (point+spot) lights. When on, the deferred pass skips its froxel cluster
-     * loop and consumes the ReSTIR-resolved radiance instead.
-     */
-    feature_restir_di_enabled = false;
-    /**
-     * Generate point-light shadows with the tetrahedral (4-face) path instead of the default
-     * cube (6-face) path. Both produce the same octahedral atlas encoding, so this is safe to
-     * flip at runtime and is meant for A/B comparison of the two generators. Pushed to the
-     * scene's shadow context each frame; see
-     * {@link GPUSceneShadowmapContext.use_tetrahedron_point_shadows}.
-     * @type {boolean}
-     */
-    feature_tetrahedron_point_shadows = false;
-    feature_bloom_enabled = true;
-    feature_automatic_exposure_enabled = true;
-
-    /**
-     * Virtual texture streaming (opt-in per material via
-     * {@link StandardShadeMaterial#vt_stack}). This flag is the system-wide
-     * kill switch: when off, the feedback pass and residency maintenance
-     * stop running — already-resident pages keep rendering, nothing new
-     * streams in. Costs nothing while no stack is registered.
-     * @type {boolean}
-     */
-    feature_virtual_textures = true;
-
-    #feature_taa_enabled = true;
-
-    get feature_taa_enabled() {
-        return this.#feature_taa_enabled;
-    }
-
-    /**
-     * While TAA is off nothing writes the history textures, but the frame counter that
-     * indexes them keeps advancing — re-enabling would blend with arbitrarily stale
-     * history of arbitrary parity. Reset temporal history on the transition.
-     * @param {boolean} v
-     */
-    set feature_taa_enabled(v) {
-        if (this.#feature_taa_enabled === v) {
-            return;
-        }
-
-        this.#feature_taa_enabled = v;
-        this.indicate_view_change();
-    }
-
-    /**
-     * Jimenez 2014 reconstruction-filter motion blur, runs between
-     * TAA and sharpening on the HDR colour. Reads the velocity buffer
-     * the same way TAA does — per-pixel pixel-space deltas — and
-     * scatter-gathers along the dilated tile velocity. Off by default
-     * because the reconstruction pass is a few-ms-budget item and not
-     * every scene needs it.
-     *
-     * @type {boolean}
-     */
-    feature_motion_blur_enabled = false;
-
-    /**
-     * Motion-blur subsystem (Jimenez 2014 reconstruction filter). A
-     * self-contained manager — same pattern as {@link #autoexposure} /
-     * {@link #depth_of_field} — that owns the motion-blur parameters
-     * (currently just `strength`). Constructed in init.
-     * @type {MotionBlur}
-     */
-    #motion_blur;
-
-    /**
-     * The motion-blur subsystem. Configure it via `renderer.motion_blur.*`
-     * (currently `strength`); toggle the effect with
-     * {@link feature_motion_blur_enabled}.
-     * @returns {MotionBlur}
-     */
-    get motion_blur() { return this.#motion_blur; }
-
-    /**
-     * Debug-only override: when true, the per-object velocity texture
-     * is drawn straight into the post-TAA color path so the screen
-     * shows the velocity buffer instead of the rendered image. Wired
-     * just before TAA — TAA then operates on the velocity texture,
-     * which is nonsense but cheap to set up. Default false.
-     *
-     * @type {boolean}
-     */
-    feature_velocity_debug_view = false;
-
-    /**
-     * Screen-space ray-marched depth of field — the Tiny Glade model
-     * (Stachowiak, GPC 2024; see {@link DepthOfField}): aperture sub-rays
-     * marched through the half-res depth/CoC buffer with nearest-hit
-     * occlusion, plus tilt-shift. Runs on the resolved HDR colour after TAA
-     * (which resolves the march's sample noise) and before motion blur. Off
-     * by default — a half-res march is a few-ms item, only worth it for a
-     * deliberate shallow-focus / diorama look. Configure via `renderer.dof`.
-     *
-     * @type {boolean}
-     */
-    feature_dof_enabled = false;
-
-    /**
-     * Depth-of-field subsystem (screen-space ray-marched). A self-contained
-     * manager — same pattern as {@link #autoexposure} — that owns all DoF
-     * parameters, focus state, and GPU buffers. Constructed in init.
-     * @type {DepthOfField}
-     */
-    #depth_of_field;
-
-    /**
-     * The depth-of-field subsystem. Configure it via `renderer.dof.*`
-     * (`f_number`, `quality`, the `focus*` helpers, `applyPreset`, …);
-     * toggle the effect with {@link feature_dof_enabled}.
-     * @returns {DepthOfField}
-     */
-    get dof() { return this.#depth_of_field; }
-
-    /**
-     * Which depth-of-field implementation runs when {@link feature_dof_enabled}
-     * is on. `"raymarch"` (default) is the screen-space ray-march
-     * ({@link DepthOfField}); `"unreal"` is the gather-based Diaphragm /
-     * Cinematic DoF ({@link DepthOfFieldU}) — half-res near/far gather with a
-     * foreground coverage bleed. Mutually exclusive by construction (only one
-     * runs at the single DoF call site).
-     * @type {"raymarch"|"unreal"}
-     */
-    dof_algorithm = "raymarch";
-
-    /**
-     * Unreal-style (Diaphragm / Cinematic) gather depth of field — a drop-in
-     * alternative to {@link #depth_of_field}, selected via {@link dof_algorithm}.
-     * Constructed in init.
-     * @type {DepthOfFieldU}
-     */
-    #depth_of_field_unreal;
-
-    /**
-     * The Unreal-style depth-of-field subsystem. Configure it via
-     * `renderer.dof_unreal.*` and select it with `renderer.dof_algorithm = "unreal"`.
-     * @returns {DepthOfFieldU}
-     */
-    get dof_unreal() { return this.#depth_of_field_unreal; }
-
-    /**
-     * When true and {@link indirect_lighting_mode} is Brick4, run a single fused
-     * pass that produces the resolved indirect lighting directly (combining the
-     * brick4 diffuse, brick4 specular and indirect resolve passes). Trades a
-     * bit of cache pressure inside the pass for substantially less memory
-     * bandwidth: no intermediate rgba16float diffuse/specular targets, the
-     * g-buffer is read once, and a single brick4 probe pair is shared between
-     * the diffuse and specular evaluations.
-     *
-     * SSR is mutually exclusive with the fused path (it needs the standalone
-     * specular target as input), so when SSR is enabled the split path is used.
-     * @type {boolean}
-     */
-    fused_indirect = true;
-
-    /**
-     * RCAS
-     * @type {boolean}
-     */
-    feature_sharpening_enabled = true;
-
-    #feature_shadows_enabled = true;
-    #feature_enabled_transparencies = true;
-
-    /**
-     *
-     * @return {ViewManager}
-     */
-    get views() {
-        return this.#views;
-    }
-
-    /**
-     * @type {GraphicsContext}
-     */
-    #graphics;
-
-    /**
-     *
-     * @return {GraphicsContext}
-     */
-    get graphics() {
-        return this.#graphics;
-    }
-
-
-    /**
-     *
-     * @type {Signal<number>}
-     */
-    /**
-     * Extensions an outside caller has put into the frame, by phase.
-     *
-     * @type {RenderExtensionRegistry}
-     */
-    #extensions = new RenderExtensionRegistry();
-
-    /**
-     * Raised when there is no usable device — the browser has no WebGPU, the hardware is below the
-     * floor, or a working device was lost while running. Carries a {@link ShadeDeviceFailure}.
-     *
-     * The floor is deliberate and there are no fallbacks (D6/I-8), so telling the player plainly is
-     * the whole of what the engine owes here. Loss is not recovered from (R6): everything built on
-     * the device went with it, and the honest response is a message and a reload.
-     *
-     * @type {Signal<ShadeDeviceFailure>}
-     */
-    onDeviceFailure = new Signal();
-
-    onFrameFinished = new Signal();
-
-    /**
-     * First argument is frame index, second is table of debug data
-     * @type {Signal<number, Object[]>}
-     */
-    onFrameDebug = new Signal();
-
-
-    /**
-     * Fraction of the output resolution.
-     * Controls {@link #internal_resolution}.
-     * If this is set to 0.5 for example - internal resolution will be 50% of the output resolution.
-     * @type {number}
-     */
-    #internal_resolution_scale = 1;
-
-    /**
-     *
-     * @type {boolean}
-     */
-    #internal_resolution_needs_update = true;
-
-    /**
-     *
-     * @param {number} v
-     */
-    set internal_resolution_scale(v) {
-        assert.isNumber(v, 'v');
-        assert.notNaN(v, 'v');
-        assert.greaterThan(v, 0);
-        assert.isFinite(v, 'v');
-
-        if (this.#internal_resolution_scale === v) {
-            // no change
-            return;
-        }
-
-        this.#internal_resolution_scale = v;
-
-        // schedule resolution recalculation
-        this.#internal_resolution_needs_update = true;
-    }
-
-    /**
-     *
-     * @returns {number}
-     */
-    get internal_resolution_scale() {
-        return this.#internal_resolution_scale;
-    }
-
-    /**
-     * This is the resolution that the rendering happens at before upscaling.
-     * Derived from input resolution via {@link internal_resolution_scale}
-     * @type {Vector2}
-     */
-    #internal_resolution = new Vector2(1, 1);
-
-
-    /**
-     * Output viewport size
-     * @type {Vector2}
-     */
-    #size = new Vector2(1, 1);
-
-    /**
-     * Output resolution.
-     * Equal to {@link size} * {@link pixel_ratio}
-     * Don't write directly
-     * @type {Vector2}
-     * @see {#size}
-     * @see {#pixel_ratio}
-     */
-    #output_resolution = new Vector2(1, 1);
-
-    /**
-     *
-     * @returns {Vector2}
-     */
-    get output_resolution() {
-        return this.#output_resolution.clone();
-    }
-
-    /**
-     * width/height
-     * Useful for camera projection setup
-     * @return {number}
-     */
-    get aspect_ratio() {
-        return this.#internal_resolution.x / this.#internal_resolution.y;
-    }
-
-    /**
-     * TODO rework ping-ping buffer usage to release old buffer when no longer needed. Can reach much better resource utilization that way. Same for all other TAA-like techniques
-     * @type {GPUTextureContext[]}
-     */
-    #textures_depth = new Array(2);
-
-    /**
-     *
-     * @returns {GPUTextureContext}
-     */
-    get texture_depth_current() {
-        const tx = this.#textures_depth;
-
-        return tx[this.#frame_count % tx.length];
-    }
-
-    /**
-     *
-     * @returns {GPUTextureContext}
-     */
-    get texture_depth_previous() {
-        const tx = this.#textures_depth;
-
-        return tx[(this.#frame_count - 1 + tx.length) % tx.length];
-    }
-
-    /**
-     *
-     * @type {GPUTextureContext[]}
-     */
-    #textures_taa_history = new Array(2);
-
-    /**
-     *
-     * @returns {GPUTextureContext}
-     */
-    #get_texture_taa_history(x) {
-        const tx = this.#textures_taa_history;
-
-        return tx[(this.#frame_count - x + tx.length) % tx.length];
-    }
-
-
-    /**
-     * @type {GPUTextureFormat}
-     */
-    #presentation_format = "rgba8unorm";
-
-    /**
-     * How many pixels to draw per screen pixel.
-     * Typically, this is used to match physical screen resolution to virtual resolution.
-     * On the high pixel density displays, CSS pixels usually take up more than one screen pixel.
-     * @type {number}
-     */
-    #pixel_ratio = window.devicePixelRatio;
-
-    /**
-     *
-     * @return {number}
-     */
-    get pixel_ratio() {
-        return this.#pixel_ratio;
-    }
-
-    /**
-     *
-     * @param {number} ratio
-     */
-    set pixel_ratio(ratio) {
-        assert.isNumber(ratio, 'ratio');
-        assert.notNaN(ratio, 'ratio');
-        assert.greaterThan(ratio, 0);
-        assert.isFinite(ratio, 'ratio');
-
-        if (ratio === this.#pixel_ratio) {
-            // no change
-            return;
-        }
-
-        this.#pixel_ratio = ratio;
-
-        this.#update_resolution();
-    }
-
-    /**
-     * How many future frames should be debugged
-     * @type {number}
-     */
-    #debug_frame_count = 0;
-
-    /**
-     * Increase the number of future debug frames by X
-     */
-    /**
-     * Record work into the frame at a named point in it.
-     *
-     * The extension is called once per frame, when its phase comes round, and is handed the
-     * {@link FrameContext} — the frame's graph and the typed records holding the handles that exist
-     * at that moment. It records with the `graph_*` helpers exactly as the built-in passes do, and
-     * everything it produces reaches the rest of the frame by publishing a handle into a record.
-     *
-     * Handles come from the records rather than from the renderer on purpose: the graph is what
-     * knows which resources a pass touched, and work recorded around it cannot be ordered or aliased
-     * correctly against the rest of the frame.
-     *
-     * @param {RenderExtension} extension
-     * @returns {RenderExtension} `extension`, for handing back to {@link remove_extension}
-     */
-    add_extension(extension) {
-        return this.#extensions.add(extension);
-    }
-
-    /**
-     * Take an extension back out of the frame.
-     *
-     * @param {RenderExtension} extension
-     * @returns {boolean} whether it was registered
-     */
-    remove_extension(extension) {
-        return this.#extensions.remove(extension);
-    }
-
-    /**
-     * @param {FramePhase} phase
-     * @returns {number} how many extensions are registered on `phase`
-     */
-    extension_count(phase) {
-        return this.#extensions.count(phase);
-    }
-
-
-    add_debug_frame(count = 1) {
-        assert.isNonNegativeInteger(count, 'count');
-
-        this.#debug_frame_count += count;
-    }
-
-    /**
-     *
-     * @type {Map<Scene, GPULightProbeVolumeRenderer>}
-     */
-    #probe_bakers = new Map();
-
-
-    /**
-     *
-     * @type {Map<Scene, CascadedSceneSDF>}
-     */
-    #scene_sdfs = new Map();
-
-    /**
-     *
-     * @param {Scene} scene
-     * @return {CascadedSceneSDF}
-     */
-    obtains_scene_sdf(scene) {
-        let sdf = this.#scene_sdfs.get(scene);
-
-        if (sdf === undefined) {
-            sdf = new CascadedSceneSDF(this.device);
-            this.#scene_sdfs.set(scene, sdf);
-        }
-
-        return sdf;
-    }
-
-    /**
-     * Used to instruct renderer that either the scene or camera has changed significantly
-     * Primarily instructs resetting history on temporal accumulation
-     */
-    indicate_view_change() {
-        this.#postprocess.reset_history();
-
-        if (this.#path_tracer !== undefined) {
-            this.#path_tracer.clear_history = true;
-        }
-
-        this.#taa.reset_history = true;
-
-        if (this.#nss !== undefined) {
-            this.#nss.reset_history = true;
-        }
-    }
-
-    /**
-     * For internal and debug use only
-     * @param {Scene} scene
-     * @returns {GPULightProbeVolumeRenderer}
-     */
-    getProbeRendererForScene(scene) {
-
-        const scene_ctx = this.#scenes.obtain(scene);
-
-        let baker = this.#probe_bakers.get(scene);
-
-        if (baker === undefined) {
-            baker = new GPULightProbeVolumeRenderer(this.#graphics, scene_ctx);
-            this.#probe_bakers.set(scene, baker);
-        }
-
-        return baker;
-    }
-
-
-    /**
-     *
-     * @param {Scene} scene
-     */
-    update_lpv(scene) {
-
-        //
-        // let baker = this.getProbeRendererForScene(scene);
-        //
-        // baker.autoSetRaysPerProbe(1);
-        // baker.bake();
-
-        const scene_ctx = this.#scenes.obtain(scene);
-
-        const graph = new FrameGraph("LPV");
-
-        const cmd = ShadeGPUCommandContext.create(this.graphics, 'LPV');
-
-        scene_ctx.light_probe_volume.atlas.graph_update({
-            graph,
-            scene: scene_ctx,
-            graphics: this.graphics,
-            update_ray_count: 100_000
-        });
-
-        cmd.encodeGraph(graph);
-        cmd.finish();
-    }
-
-    /**
-     * Compute deferred indirect specular and diffuse contributions
-     * based on the active indirect lighting mode.
-     *
-     * @param {object} params
-     * @param {FrameGraph} params.graph
-     * @param {GPUViewContext} params.view_ctx
-     * @param {GPUSceneContext} params.scene_ctx
-     * @param {number} params.bent_normals - graph resource ID
-     * @param {number} params.current_color_out - graph resource ID (scene color, needed for SSR)
-     * @param {number} params.gr_texture_depth_current
-     * @param {number} params.gr_texture_hzb
-     * @param {number} params.gr_texture_material_albedo_ao
-     * @param {number} params.gr_texture_pbr
-     * @param {number} params.gr_texture_normal
-     * @param {number} params.gr_texture_environment
-     * @param {number} params.gr_velocity
-     * @param {number} params.gr_occlusion_clip
-     * @param {number} params.gr_buffer_camera_current
-     * @param {number} params.gr_buffer_camera_previous
-     * @param {Vector2} params.resolution
-     * @returns {{indirect_specular: number, indirect_diffuse: number}}
-     */
-    #graph_indirect_lighting({
-                                 graph,
-                                 view_ctx,
-                                 scene_ctx,
-                                 bent_normals,
-                                 current_color_out,
-                                 //
-                                 gr_texture_depth_current,
-                                 gr_texture_hzb,
-                                 gr_texture_material_albedo_ao,
-                                 gr_texture_pbr,
-                                 gr_texture_normal,
-                                 gr_texture_environment,
-                                 gr_velocity,
-                                 gr_occlusion_clip,
-                                 gr_buffer_camera_current,
-                                 gr_buffer_camera_previous,
-                                 resolution,
-                             }) {
-
-        const mode = this.indirect_lighting_mode;
-
-        let indirect_specular = -1;
-        let indirect_diffuse = -1;
-
-        const lpv = scene_ctx.light_probe_volume;
-
-        //
-        // ── SPECULAR ────────────────────────────────────────────
-        //
-
-        // SSR replaces the specular IBL fallback when enabled.
-        // NOTE: SSR is currently not supported in Brick4 mode — this is a known
-        // limitation and will be addressed in a future update.
-        if (this.feature_ssr_enabled && mode !== ShadeIndirectLightingMode.Brick4) {
-
-            const ssr = this.#postprocess.ssr.graph_pass({
-                graph,
-                input_depth: gr_texture_depth_current,
-                input_hzb: gr_texture_hzb,
-                input_scene_color: current_color_out,
-                input_albedo: gr_texture_material_albedo_ao,
-                input_pbr: gr_texture_pbr,
-                input_normal: gr_texture_normal,
-                input_velocity: gr_velocity,
-                input_occlusion: gr_occlusion_clip,
-                input_environment: gr_texture_environment,
-                camera_current: gr_buffer_camera_current,
-                camera_previous: gr_buffer_camera_previous,
-                lpv: mode === ShadeIndirectLightingMode.LPV ? lpv : undefined,
-                resolution,
-            });
-
-            indirect_specular = ssr.denoised;
-
-        } else if (mode === ShadeIndirectLightingMode.Brick4) {
-
-            // Brick4 specular from volumetric lightmap
-            [indirect_specular] = graph_image_pass({
-                graph,
-                shader: shader_brick4_specular,
-                input_depth: gr_texture_depth_current,
-                inputs: {
-                    tDepth: gr_texture_depth_current,
-                    tNormals: gr_texture_normal,
-                    tPBR: gr_texture_pbr,
-                    tSTBN_vec2: STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2,
-                    camera: gr_buffer_camera_current,
-                    view: view_ctx.uniform_buffer.buffer,
-                    brick4: scene_ctx.volumetric_light_map.buffer,
-                },
-                output_resolution: view_ctx.resolution,
-            });
-
-        } else {
-            // IBL / LPV fallback — environment map specular
-            [indirect_specular] = graph_image_pass({
-                graph,
-                shader: shader_specular_IBL,
-                input_depth: gr_texture_depth_current,
-                inputs: {
-                    tBentNormals: bent_normals,
-                    tNormals: gr_texture_normal,
-                    tDepth: gr_texture_depth_current,
-                    tPBR: gr_texture_pbr,
-                    tEnvironment: gr_texture_environment,
-                    camera: gr_buffer_camera_current,
-                },
-                output_resolution: view_ctx.resolution,
-            });
-        }
-
-        //
-        // ── DIFFUSE ─────────────────────────────────────────────
-        //
-
-        switch (mode) {
-
-            case ShadeIndirectLightingMode.IBL:
-                // Environment map irradiance
-                [indirect_diffuse] = graph_image_pass({
-                    graph,
-                    shader: shader_diffuse_IBL,
-                    input_depth: gr_texture_depth_current,
-                    inputs: {
-                        tBentNormals: bent_normals,
-                        tGBufferAlbedo: gr_texture_material_albedo_ao,
-                        tEnvironment: gr_texture_environment,
-                    },
-                    output_resolution: view_ctx.resolution,
-                });
-                break;
-
-            case ShadeIndirectLightingMode.Brick4:
-                // Brick4 diffuse from volumetric lightmap
-                [indirect_diffuse] = graph_image_pass({
-                    graph,
-                    shader: shader_brick4_diffuse,
-                    input_depth: gr_texture_depth_current,
-                    inputs: {
-                        tDepth: gr_texture_depth_current,
-                        tBentNormals: bent_normals,
-                        tAlbedoAO: gr_texture_material_albedo_ao,
-                        tSTBN_vec2: STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2,
-                        camera: gr_buffer_camera_current,
-                        view: view_ctx.uniform_buffer.buffer,
-                        brick4: scene_ctx.volumetric_light_map.buffer,
-                    },
-                    output_resolution: view_ctx.resolution,
-                });
-                break;
-
-            case ShadeIndirectLightingMode.LPV:
-                // Light Probe Volume diffuse
-                [indirect_diffuse] = graph_image_pass({
-                    graph,
-                    shader: shader_diffuse_LPV,
-                    input_depth: gr_texture_depth_current,
-                    inputs: {
-                        camera: gr_buffer_camera_current,
-                        tDepth: gr_texture_depth_current,
-                        tBentNormals: bent_normals,
-                        tGBufferAlbedo: gr_texture_material_albedo_ao,
-                        //
-                        lpv_atlas_radiance: lpv.atlas.texture_radiance,
-                        lpv_atlas_depth: lpv.atlas.texture_depth,
-                        //
-                        lpv_lookup: lpv.buffer_mesh_bvh,
-                        lpv_metadata: lpv.buffer_metadata,
-                        lpv_mesh: lpv.buffer_mesh,
-                        lpv_probes: lpv.buffer_probes,
-                    },
-                    output_resolution: view_ctx.resolution,
-                });
-                break;
-        }
-
-        return { indirect_specular, indirect_diffuse };
-    }
-
-    /**
-     * @type {PostProcess}
-     */
-    #postprocess
-
-    /**
-     * @type {ReSTIRDI}
-     */
-    #restir_di
-
-    /**
-     * ReSTIR DI subsystem — exposed for runtime tuning (e.g. GUI toggles like
-     * `use_screen_space_shadow`, `m_initial`).
-     * @returns {ReSTIRDI}
-     */
-    get restir_di() {
-        return this.#restir_di;
-    }
-
-    /**
-     *
-     * @type {TAA}
-     */
-    #taa = new TAA();
-
-    /**
-     * Lazily constructed in {@link initialize} once a graphics context is
-     * available — NSS owns persistent GPU textures, so it can't be a
-     * field initializer like {@link #taa}.
-     * @type {NSS | undefined}
-     */
-    #nss
-
-    /**
-     * Selects which temporal-AA / upscaler runs at the temporal-resolve
-     * stage. Defaults to {@link ShadeUpscalerType.TAA}; assign
-     * {@link ShadeUpscalerType.NSS} to use the bundled neural upscaler
-     * (no extra setup — the NSS instance ships with placeholder weights).
-     * @type {ShadeUpscalerType}
-     */
-    upscale_type = ShadeUpscalerType.TAA;
-
-    /**
-     * Public read access to the NSS instance. Lazily constructed on
-     * first access, which is also when the bundled weights blob is
-     * decoded — so the cost of selecting NSS is amortized to a single
-     * frame.
-     * @returns {NSS}
-     */
-    get nss() {
-        if (this.#nss === undefined) {
-            assert.defined(this.#graphics, 'graphics context not yet initialized — call Renderer.initialize() first');
-            this.#nss = new NSS(this.#graphics);
-
-            // First-time setup: align the jitter sequence size with the
-            // current upscale ratio. Subsequent resolution changes are
-            // picked up by #update_internal_resolution.
-            const out_w = this.#output_resolution.x;
-            const in_w = this.#internal_resolution.x;
-            if (out_w > 0 && in_w > 0) {
-                const upscale_ratio = out_w / in_w;
-                this.#nss.jitter_sequence_size = NSS.recommended_jitter_sequence_size(upscale_ratio);
-            }
-        }
-        return this.#nss;
-    }
-
-    #device_lost = false;
-
-    /**
-     * Handles event when GPUDevice is lost
-     * @param {GPUDeviceLostInfo} info
-     */
-    #handle_device_lost(info) {
-        this.#device_lost = true;
-
-        if (info.reason === "destroyed") {
-            // most likely renderer was destroyed, this is expected behavior
-            // TODO check if renderer owns the device, if not, log a warning
-            return;
-        }
-
-        console.error('GPUDevice lost', info);
-
-        // Everything the renderer built lives on the device that just went away, so there is
-        // nothing to carry over and no attempt to (R6). Whoever is hosting this gets told, and a
-        // reload is the way back.
-        this.onDeviceFailure.send1(ShadeDeviceFailure.device_lost(info.message ?? info.reason ?? ""));
-    }
-
-    #hdr_supported = false;
-
-    /**
-     * What's the peak brightness of the display?
-     * Only valid for HDR.
-     *
-     * @type {number}
-     */
-    #display_peak_brightness_nits = 1000;
-
-    #update_presentation_format() {
-
-        const format8bit = navigator.gpu.getPreferredCanvasFormat();
-
-        const format = this.#hdr_supported ? "rgba16float" : format8bit;
-
-        if (format === this.#presentation_format) {
-            return;
-        }
-
-        this.#presentation_format = format;
-
-        this.#context_needs_update = true;
-    }
-
-    /**
-     * Needs to be a lambda, because we use it as a listener.
-     */
-    #update_hdr_support = () => {
-        const isHDR = window.matchMedia("(dynamic-range: high)").matches;
-
-        const previous_value = this.#hdr_supported;
-
-
-        this.#hdr_supported = isHDR;
-
-        if (isHDR) {
-            // Currently, there is no way to interrogate this from the browser, so going with an assumption
-            this.#display_peak_brightness_nits = 1000;
-        } else {
-            // Assume SDR nits
-            this.#display_peak_brightness_nits = 80;
-        }
-
-        if (isHDR === previous_value) {
-            // no change
-            return;
-        }
-
-        console.log(`HDR support: ${isHDR ? 'enabled' : 'disabled'}`);
-
-        this.#update_presentation_format();
-
-        this.#context_needs_update = true;
-    }
-
-    /**
-     *
-     * @param {GPUCanvasContext} [context] Optional, if not provided - one will be created.
-     * @param {GPUDevice} [device] Optional, if not provided - one will be created.
-     * @param {number} [pixelRatio] Optiona, if not provided - will be taken from browser context
-     */
-    async initialize({
-                         context,
-                         device,
-                         pixelRatio = window.devicePixelRatio,
-                     } = {}) {
-
-        if (!('gpu' in navigator)) {
-            throw new Error('navigator.gpu not available — WebGPU disabled or unsupported');
-        }
-
-        this.#update_presentation_format();
-        this.#update_hdr_support();
-
-        if (context === undefined) {
-            const canvas = document.createElement('canvas');
-            canvas.width = window.innerWidth;
-            canvas.height = window.innerHeight;
-            // Sensible default styling so a freshly-appended canvas covers
-            // the viewport without depending on the host page's CSS reset.
-            // Override `style` after `initialize()` returns if the host
-            // page wants the canvas embedded somewhere else.
-            canvas.style.cssText = 'position:fixed;inset:0;width:100vw;height:100vh;display:block';
-
-            context = canvas.getContext('webgpu');
-
-            if (context === null) {
-                throw new Error('Failed to bind GPUCanvasContext');
-            }
-        }
-
-        if (device === undefined) {
-            // no device present, let's create one
-
-            const gpu = navigator.gpu;
-
-            if (gpu === undefined) {
-                throw ShadeDeviceFailure.webgpu_unavailable();
-            }
-
-            const adapter = await gpu.requestAdapter({
-                powerPreference: "high-performance",
-            });
-
-            if (adapter === null) {
-                throw ShadeDeviceFailure.adapter_unavailable();
-            }
-
-            if (adapter.isFallbackAdapter) {
-                // see https://www.w3.org/TR/webgpu/#dom-gpurequestadapteroptions-forcefallbackadapter
-                // fallback device is typically a software implementation and is going to be slow as sin
-                console.warn('GPU provided a fallback adapter (typically because no other appropriate adapter was available). Fallback adapter is typically a software implementation and will be slow.');
-            }
-
-            // log details of the adapter
-            console.log(`GPU adapter is ${adapter.info.vendor}/${adapter.info.architecture}, device='${adapter.info.device}', description='${adapter.info.description}'`);
-
-            // console.warn(`Buffer size limit: ${number_format_by_thousands(adapter.limits.maxBufferSize)}`);
-            //
-            // console.warn('adapter limits:', adapter.limits);
-
-            const maxStorageBuffersPerShaderStage = adapter.limits.maxStorageBuffersPerShaderStage;
-
-            if (maxStorageBuffersPerShaderStage < 10) {
-                throw ShadeDeviceFailure.below_floor(
-                    `requires at least 10 storage buffers per shader stage, adapter offers ${maxStorageBuffersPerShaderStage}`
-                );
-            }
-
-            const requiredFeatures = [
-                // required for indirect draw that's used extensively in Shade
-                WebGPUExtensionType.IndirectFirstInstance,
-                // required for OIT (might be unavailable)
-                WebGPUExtensionType.Float32Blendable,
-            ];
-
-            // add features if they are available
-            const optional_desired = [
-                // Profiling only, and some browsers withhold it on hardware that is otherwise
-                // fine — so it is taken when offered and the timers go quiet when it is not
-                // (E7, sponsor 2026-08-16). Requiring it would refuse to start on those browsers
-                // for the sake of a feature the game does not need to run.
-                WebGPUExtensionType.TimestampQuery,
-                WebGPUExtensionType.Subgroups,
-                WebGPUExtensionType.TextureFormatsTier1,
-            ];
-
-            // valid required features
-            for (const feature of requiredFeatures) {
-                if (!adapter.features.has(feature)) {
-                    throw ShadeDeviceFailure.below_floor(`adapter does not support required feature '${feature}'`);
-                }
-            }
-
-            for (const feature of optional_desired) {
-                if (adapter.features.has(feature)) {
-                    requiredFeatures.push(feature);
-                }
-            }
-
-
-            device = await adapter.requestDevice({
-                requiredLimits: {
-                    // required for large G-buffers
-                    maxColorAttachmentBytesPerSample: 32,
-
-                    /*
-                     grab the largest buffer limit we can get, default limits are super-low
-                     */
-                    maxBufferSize: adapter.limits.maxBufferSize,
-                    maxStorageBufferBindingSize: adapter.limits.maxStorageBufferBindingSize,
-
-                    maxStorageBuffersPerShaderStage: 10,
-                },
-                requiredFeatures
-            });
-
-            // NOTE: according to spec (as of 2025/09/19) - adapter can only be used to create one device, after which it becomes "consumed"
-            //       see https://www.w3.org/TR/webgpu/#adapters
-
-            // TODO obtained device might be "lost" if something goes wrong, would make sense to check for that
-        }
-
-        device.lost.then(info => {
-            this.#handle_device_lost(info);
-        })
-
-        if (context === undefined) {
-            const canvas = document.createElement('canvas');
-            canvas.width = window.innerWidth;
-            canvas.height = window.innerHeight;
-
-            context = canvas.getContext('webgpu');
-
-            if (context === null) {
-                throw new Error('Failed to bind GPUCanvasContext');
-            }
-        }
-
-        assert.ok(device.features.has("indirect-first-instance"), '"indirect-first-instance" feature needs to be enabled for non-zero firstInstance values to be used.')
-        assert.isInstanceOf(context, GPUCanvasContext, 'context', 'GPUCanvasContext');
-
-        this.context = context;
-        this.device = device;
-
-        this.#pixel_ratio = pixelRatio;
-
-        // clientWidth/clientHeight are 0 for a canvas that is not attached to the DOM,
-        // which is always the case for the renderer-owned canvas created above.
-        // Fall back to the backing-store size so that #configure_context doesn't
-        // overwrite the just-set canvas size with the 1x1 minimum resolution.
-        this.#size.set(
-            context.canvas.clientWidth || context.canvas.width,
-            context.canvas.clientHeight || context.canvas.height
-        );
-
-        this.#update_output_resolution();
-
-        this.#graphics = new GraphicsContext(device);
-
-        const graphics = this.#graphics;
-
-        await graphics.initialize();
-
-
-        this.#scenes = new SceneManager(graphics);
-
-        this.#cameras = new CameraManager(this.device);
-        this.#views = new ViewManager(graphics, this.#cameras, this.#scenes);
-
-        const resolution_internal = this.#internal_resolution.asArray();
-
-        for (let i = 0; i < this.#textures_depth.length; i++) {
-
-            this.#textures_depth[i] = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
-                label: `Depth ${i}`,
-                size: resolution_internal,
-                format: 'depth32float',
-                mipLevelCount: G_BUFFER_MIP_LEVELS,
-                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC,
-            }));
-        }
-
-
-        const resolution_out = this.#output_resolution.asArray();
-
-        for (let i = 0; i < this.#textures_taa_history.length; i++) {
-
-            this.#textures_taa_history[i] = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
-                label: `Color ${i}`,
-                size: resolution_out,
-                format: "rgba16float",
-                mipLevelCount: 1,
-                // STORAGE_BINDING is required for the NSS postprocess
-                // compute shader to write here. TAA continues to use
-                // RENDER_ATTACHMENT — the flags coexist on the same
-                // texture and the active upscaler picks its preferred
-                // write path each frame.
-                usage: GPUTextureUsage.RENDER_ATTACHMENT
-                    | GPUTextureUsage.TEXTURE_BINDING
-                    | GPUTextureUsage.STORAGE_BINDING
-                    | GPUTextureUsage.COPY_SRC,
-            }));
-        }
-
-        this.#autoexposure = new GPUCameraExposureManager(device);
-        this.#depth_of_field = new DepthOfField(device);
-        this.#depth_of_field_unreal = new DepthOfFieldU(device);
-        this.#motion_blur = new MotionBlur();
-
-        this.#postprocess = new PostProcess(this.#graphics);
-
-        this.#restir_di = new ReSTIRDI(this.#graphics);
-
-        this.#configure_context();
-        this.init_render_targets();
-
-        window.matchMedia("(dynamic-range: high)").addEventListener("change", this.#update_hdr_support);
-
-    }
-
-    /**
-     * Cleanup
-     */
-    destroy() {
-
-        window.matchMedia("(dynamic-range: high)").removeEventListener("change", this.#update_hdr_support);
-    }
-
-
-    /**
-     * @type {RenderTarget}
-     */
-    #vis_render_target;
-
-    init_render_targets() {
-        const vis_rt = new RenderTarget();
-        this.#vis_render_target = vis_rt;
-
-        const textures = this.#graphics.textures;
-
-        // TODO these can be moved to frame graph instead and managed in a transient manner
-        const internal_resolution_array = this.#internal_resolution.asArray();
-
-        vis_rt.color_attachments = [
-            textures.contextFromDescriptor(TextureDescriptor.from({
-                size: internal_resolution_array,
-                format: "r32uint",
-                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
-            })),
-            textures.contextFromDescriptor(TextureDescriptor.from({
-                size: internal_resolution_array,
-                format: "r32uint",
-                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
-            })),
-        ];
-
-        vis_rt.depth_attachment = this.#textures_depth[0];
-
-    }
-
-    /**
-     * If set to true, will force {@link #configure_context} on next render
-     * @type {boolean}
-     */
-    #context_needs_update = false;
-
-    #configure_context() {
-        const context = this.context;
-
-        const resolution = this.#output_resolution;
-
-        context.canvas.width = resolution.x;
-        context.canvas.height = resolution.y;
-
-        // canvas must be scaled on-screen differently from resolution to account for pixel ratio
-        const size = this.#size;
-        context.canvas.style.width = `${size.x}px`;
-        context.canvas.style.height = `${size.y}px`;
-
-        const preferred_color_space = 'display-p3';
-
-
-        const config = {
-            device: this.device,
-            format: this.#presentation_format,
-            alphaMode: 'opaque',
-            colorSpace: preferred_color_space,
-            toneMapping: {
-                // see https://www.w3.org/TR/webgpu/#dom-gpucanvastonemappingmode-extended
-                mode: this.#hdr_supported ? "extended" : "standard"
-            }
-        };
-
-
-        try {
-            context.configure(config);
-        } catch (e) {
-            // try fall-back colorspace
-            context.configure({
-                ...config,
-                colorSpace: 'srgb'
-            });
-        }
-
-    }
-
-    #apply_size() {
-        const out_w = this.#output_resolution.x;
-        const out_h = this.#output_resolution.y;
-
-        this.#textures_taa_history.forEach(t => t.resize(out_w, out_h));
-
-
-        this.#context_needs_update = true;
-    }
-
-
-    #update_internal_resolution() {
-        const out_w = this.#output_resolution.x;
-        const out_h = this.#output_resolution.y;
-
-        const dimension_limit = this.device.limits.maxTextureDimension2D;
-
-        const irs = this.#internal_resolution_scale;
-
-        const _iw = clamp(Math.floor(out_w * irs), INTERNAL_RESOLUTION_MIN, dimension_limit);
-        const _ih = clamp(Math.floor(out_h * irs), INTERNAL_RESOLUTION_MIN, dimension_limit);
-
-        this.#internal_resolution.set(_iw, _ih);
-
-        // figure out exact x/y resolution scale
-        const irs_x_inv = out_w / _iw;
-        const irs_y_int = out_h / _ih;
-
-        // we need to make TAA sequence long enough to provide full coverage over output resolution texels
-        const taa_sequence_scale = Math.max(1, irs_x_inv * irs_y_int);
-
-        const upscale_factor = 1 / irs;
-
-        // shrink the sequence as upscale factor increases
-        // we lose crispness of the edges, but we have to trade it to get faster convergence
-        const base_sequence_size = remap(
-            1, 2,
-            16, 4,
-            clamp(upscale_factor, 1, 2),
-        );
-
-        this.#taa.jitter_sequence_size = Math.ceil(base_sequence_size * taa_sequence_scale);
-
-        // ARM's NSS expects `8 * upscale_ratio^2` jitter phases. Apply the
-        // same coverage scaling as TAA so DPR-mismatch resolutions still
-        // get full coverage. Only applied if the NSS instance has been
-        // created — no point spinning it up just to set a number.
-        if (this.#nss !== undefined) {
-            const nss_base = NSS.recommended_jitter_sequence_size(upscale_factor);
-            this.#nss.jitter_sequence_size = Math.ceil(nss_base * taa_sequence_scale);
-        }
-
-        const in_w = this.#internal_resolution.x;
-        const in_h = this.#internal_resolution.y;
-
-        this.#textures_depth.forEach(t => {
-            t.resize(in_w, in_h)
-        });
-
-        this.#vis_render_target.resize(in_w, in_h);
-
-        // resizing destroys BOTH ping-pong depth textures, including the one holding last
-        // frame's depth — disocclusion/SSAO would read a zeroed "previous depth" this frame
-        // and silently corrupt temporal history. The external resize() path resets history
-        // via indicate_view_change(); internal-resolution changes (DRS steps) must too.
-        this.indicate_view_change();
-
-        this.#internal_resolution_needs_update = false;
-    }
-
-    #update_output_resolution() {
-        const size = this.#size;
-        const pixel_ratio = this.#pixel_ratio;
-
-        const dimension_limit = this.device.limits.maxTextureDimension2D;
-
-        // limits are there to prevent crashing out
-        const w = clamp(Math.ceil(size.x * pixel_ratio), 1, dimension_limit);
-        const h = clamp(Math.ceil(size.y * pixel_ratio), 1, dimension_limit);
-
-        this.#output_resolution.set(w, h);
-
-        this.#internal_resolution_needs_update = true;
-    }
-
-    /**
-     * Make sure to resize at the start of the frame to avoid flicker
-     *
-     * @param {number} x
-     * @param {number} y
-     */
-    resize(x, y) {
-        assert.isNonNegativeInteger(x, 'x');
-        assert.isNonNegativeInteger(y, 'y');
-
-        const size = this.#size;
-
-        if (size.x === x && size.y === y) {
-            // no change
-            return;
-        }
-
-        size.set(x, y);
-
-        this.#update_resolution();
-    }
-
-    /**
-     * Does not check for changes, so make sure to call this sparingly
-     */
-    #update_resolution() {
-
-        this.#update_output_resolution();
-
-        if (this.#internal_resolution_needs_update) {
-            this.#update_internal_resolution();
-        }
-
-        this.#apply_size();
-
-        // drop history buffers to prevent artifacts
-        this.indicate_view_change();
-    }
-
-    /**
-     * Bring the canvas context up to date with the size the renderer is drawing at.
-     *
-     * **Only {@link render} calls this, and that is the point.** Configuring a context resizes the
-     * canvas and invalidates the texture it last handed out, so it has to happen before the frame
-     * asks for one — and a frame going somewhere other than the canvas must not do it at all, or
-     * every offscreen picture would resize the page's canvas to its own size and back.
-     */
-    #ensure_context_configured() {
-        this.#update_resolution_if_needed();
-
-        if (this.#context_needs_update) {
-            this.#configure_context();
-            this.#context_needs_update = false;
-        }
-    }
-
-    #update_resolution_if_needed() {
-        if (this.#internal_resolution_needs_update) {
-            this.#update_internal_resolution();
-        }
-    }
-
-    #begin_frame() {
-
-        this.#update_resolution_if_needed();
-
-        this.#graphics.update();
-
-        // Virtual texture maintenance: apply arrived pages (budgeted
-        // uploads), flush page-table dirty rects and stack info, issue
-        // streaming loads. Queue-ordered before this frame's submits, so
-        // the material pass samples a consistent table+cache snapshot.
-        if (this.feature_virtual_textures) {
-            this.#graphics.virtual_textures.update();
-        }
-
-        // cycle depth attachment
-        this.#vis_render_target.depth_attachment = this.texture_depth_current;
-        this.#postprocess.update(this.#frame_count);
-
-        // Advance whichever upscaler we're going to ask for jitter on this
-        // frame. Both share the same Halton(2, 3) sequence; we only tick
-        // the active one to avoid spinning up NSS just to drive a counter.
-        if (this.upscale_type === ShadeUpscalerType.NSS) {
-            const nss = this.nss;
-            nss.frame_count = this.#frame_count;
-            nss.frame_index = this.#frame_count;
-        } else {
-            this.#taa.frame_index = this.#frame_count;
-        }
-    }
-
-    #end_frame() {
-        this.#frame_count++;
-
-        // dispatch event
-        this.onFrameFinished.send1(this.#frame_count);
-    }
-
-    /**
-     * @type {AccumulatingPathTracer}
-     */
-    #path_tracer;
-
-    get path_tracer() {
-        if (this.#path_tracer === undefined) {
-            this.#path_tracer = new AccumulatingPathTracer(this.#graphics);
-        }
-
-        return this.#path_tracer;
-    }
-
-    /**
-     * Draw a frame onto the canvas this renderer is bound to.
-     *
-     * The canvas is one target among others: this is {@link render_to_target} with the canvas's
-     * current texture as the target, and nothing else.
-     *
-     * @param {PerspectiveCamera} camera
-     * @param {Scene} scene
-     * @param {number} [time_delta_seconds]
-     * @returns {boolean} whether frame was rendered, will return false if previous frame hasn't finished yet
-     */
-    render(
-        camera,
-        scene,
-        time_delta_seconds = 0.01666
-    ) {
-        if (this.#device_lost) {
-            // device is lost, can't render — and asking the context for a texture would throw
-            return false;
-        }
-
-        this.#ensure_context_configured();
-
-        const canvas_texture = this.context.getCurrentTexture();
-
-        return this.render_to_target(
-            camera,
-            scene,
-            time_delta_seconds,
-            GPUTextureContext.fromTexture(canvas_texture, this.device)
-        );
-    }
-
-    /**
-     * Draw a frame into a texture of the caller's choosing.
-     *
-     * **The target says where the picture goes, not how big it is.** Everything the frame is built
-     * out of — the G-buffer, the visibility buffer, the depth ping-pong, the temporal history — is
-     * sized from {@link output_resolution}, so a target has to be that size; a caller wanting a
-     * different one calls {@link resize} first and puts the size back afterwards. Rendering into a
-     * texture the caller owns is what makes a frame readable: a canvas texture is configured by the
-     * presentation path and cannot carry `COPY_SRC`, and one of these can.
-     *
-     * @param {PerspectiveCamera} camera
-     * @param {Scene} scene
-     * @param {number} time_delta_seconds
-     * @param {GPUTextureContext} target must match {@link output_resolution}
-     * @returns {boolean} whether frame was rendered, will return false if previous frame hasn't finished yet
-     */
-    render_to_target(
-        camera,
-        scene,
-        time_delta_seconds,
-        target
-    ) {
-        assert.defined(target, 'target');
-        assert.equal(target.isGPUTextureContext, true, 'target.isGPUTextureContext !== true');
-
-        if (this.#device_lost) {
-            // device is lost, can't render
-            return false;
-        }
-
-        this.#begin_frame();
-
-
-        if (this.indirect_lighting_mode === ShadeIndirectLightingMode.LPV) {
-            this.update_lpv(scene);
-        }
-
-        const view = View.from(camera, scene);
-        view.label = "Main View";
-        const view_ctx = this.#views.obtain(view);
-
-        const graphics = this.#graphics;
-
-        // Shadow allocation + per-light shadow_id assignment happens inside
-        // GPULightCollection.update (which view_ctx.update will trigger via
-        // GPUSceneContext.update below), so by the time we reach select_for_draw the
-        // light records on the GPU already carry their up-to-date shadow_id. Forward the
-        // feature flag so process_lights inside lights.update can evict everything when
-        // the renderer has shadows turned off — keeps CASTS_SHADOW_BIT cleared on every
-        // light record without further plumbing.
-        const sm = view_ctx.scene.lights.shadow_context;
-        sm.enabled = this.#feature_shadows_enabled;
-        // Which point-light shadow generator to use this frame; a flip triggers a rebuild of
-        // existing point maps inside process_lights (run via view_ctx.update above/below).
-        sm.use_tetrahedron_point_shadows = this.feature_tetrahedron_point_shadows;
-
-        const taa = this.#taa;
-
-        // Whichever upscaler is going to consume the temporal sequence
-        // also has to dictate the jitter applied to the camera projection.
-        // Both share Halton(2, 3); they just drive different jitter
-        // sequence sizes via #update_internal_resolution.
-        const jitter_source = this.upscale_type === ShadeUpscalerType.NSS
-            ? this.nss
-            : taa;
-
-        const resolution_internal = this.#internal_resolution;
-        {
-            const jitter_x = jitter_source.Jitter[0];
-            const jitter_y = jitter_source.Jitter[1];
-
-            view_ctx.setJitter(jitter_x, jitter_y);
-            view_ctx.setViewportSize(resolution_internal.x, resolution_internal.y);
-            view_ctx.setUpscaleRatio(
-                this.#output_resolution.x / resolution_internal.x,
-                this.#output_resolution.y / resolution_internal.y
-            );
-            // 2x offsets because the offsets are in NDC (-1, 1)
-            view_ctx.camera.setViewportOffset(
-                (2 * jitter_x) / resolution_internal.x,
-                (2 * jitter_y) / resolution_internal.y
-            );
-
-        }
-
-        view_ctx.update(graphics);
-
-        const command_ctx = ShadeGPUCommandContext.create(
-            graphics,
-            "Renderer/main-0"
-        );
-
-        if (this.#debug_frame_count > 0) {
-            this.#debug_frame_count--;
-
-            const current_frame = this.#frame_count;
-
-            command_ctx.enable_debug_timers((table) => {
-                this.onFrameDebug.send2(current_frame, table);
-            });
-        }
-
-        // Per-frame animation tick — runs before shadow allocation so
-        // animated transforms (joint poses, mesh.global from animated
-        // parents) are in the scene database by the time shadow
-        // culling samples it. No-op when nothing's registered.
-        view_ctx.scene.tick(command_ctx, time_delta_seconds);
-
-        const viz_rt = this.#vis_render_target;
-
-        // prepare shadows (process_lights already ran inside lights.update via view_ctx.update,
-        // so the GPU light records already carry their up-to-date shadow_id)
-        if (this.#feature_shadows_enabled) {
-            // Two-stage: (1) score+select which maps refresh this frame and publish their metadata,
-            // (2) rasterize the selected maps. The context internally dispatches to the right
-            // raster path per light type — directional/spot go direct, point lights do a cube
-            // pass plus octahedral remap — so we don't have to juggle job arrays out here.
-            // draw() also writes per-shadow records into the scene's GPU light database
-            // (shadow_point/shadow_spot/shadow_directional tables) via its owner reference.
-            sm.select_for_draw(camera, view_ctx.scene, view_ctx.frame_index, view_ctx.resolution);
-            sm.draw(command_ctx);
-        }
-
-
-        const graph = new FrameGraph("Shading");
-
-        /*
-         The view is updated and nothing has been rasterized, so an extension here is doing the
-         per-frame compute that later phases depend on. There are no records yet — the frame has
-         built nothing to hand out.
-        */
-        const frame = new FrameContext(graph, view_ctx);
-
-        frame.phase = FramePhase.FrameStart;
-
-        this.#extensions.run(frame);
-
-        // build main view rasterization job
-        const raster_main = new RasterizationJob();
-        raster_main.view_ctx = view_ctx;
-        raster_main.render_target = viz_rt;
-        raster_main.opaque_pass = viz_rasterization_opaque_pass_descriptor;
-        raster_main.alpha_tested_pass = viz_rasterization_alpha_tested_pass_descriptor;
-
-        const gr_render_buckets = graph_rasterize_scene({
-            job: raster_main,
-            graph,
-            limits: graphics.collection_limits,
-        });
-
-        // `let` rather than `const` because an extension at `AfterGBuffer` may publish replacements
-        let gr_viz_buffer_triangle = graph_import_texture(graph, this.#vis_render_target.color_attachments[0], "viz_triangle");
-        let gr_viz_buffer_mesh = graph_import_texture(graph, this.#vis_render_target.color_attachments[1], "viz_mesh");
-
-        // Virtual texture feedback: derive per-pixel page usage from the viz
-        // buffer (no extra geometry pass) into a unique-request hash set and
-        // kick its async readback. No-op unless VT stacks are registered.
-        if (this.feature_virtual_textures) {
-            graphics.virtual_textures.graph_feedback({
-                graph,
-                view: view_ctx,
-                texture_viz_mesh: gr_viz_buffer_mesh,
-                texture_viz_triangle: gr_viz_buffer_triangle,
-                material_metadata_buffer: graphics.materials.metadata_table.buffer,
-            });
-        }
-
-        // run materials
-        const mat_g = graphics.materials.graph_viz_render({
-            graph,
-            view: view_ctx,
-            texture_viz_mesh: gr_viz_buffer_mesh,
-            texture_viz_triangle: gr_viz_buffer_triangle,
-        });
-
-        // update texture references
-        // `let` rather than `const` because a pass injected at `AfterGBuffer` may replace any of
-        // them; see the read-back below.
-        let gr_texture_pbr = mat_g.g_pbr;
-        let gr_texture_normal = mat_g.g_normal;
-        let gr_texture_material_albedo_ao = mat_g.g_albedo;
-        let gr_texture_material_emissive = mat_g.g_emissive;
-
-        // do mips for G-buffer
-        // mipmap_nearest(command_ctx, this.texture_depth_current);
-        // this.gBuffer.mipmap(command_ctx);
-
-        // Update lights position
-        command_ctx.pushDebugGroup("Shade");
-
-        const resolution = resolution_internal.asArray();
-
-        const scene_ctx = view_ctx.scene;
-        const lights = scene_ctx.lights;
-
-
-        const gr_texture_canvas = graph_import_texture(graph, target, "canvas");
-        let gr_texture_depth_current = graph_import_texture(graph, this.texture_depth_current, "depth");
-        const gr_buffer_camera_current = graph_import_buffer(graph, view_ctx.camera.gpu_buffer, "camera/current");
-        const gr_buffer_camera_previous = graph_import_buffer(graph, view_ctx.gpu_previous_camera_state.gpu_buffer, "camera/previous");
-        const gr_texture_hzb = graph_import_texture(graph, view_ctx.hierarchical_z_buffer.texture, "HZB");
-        const gr_texture_environment = graph_import_texture(graph, view_ctx.scene.lights.environment);
-
-        const taa_history_0 = this.#get_texture_taa_history(0);
-        const taa_history_1 = this.#get_texture_taa_history(-1);
-
-        const gr_texture_taa_history = graph_import_texture(graph, taa_history_0, "taa history");
-        const gr_texture_taa_out = graph_import_texture(graph, taa_history_1, "taa out");
-        let gr_texture_depth_previous = graph_import_texture(graph, this.texture_depth_previous, "depth previous");
-
-        const gr_shadowmap_atlas = graph_import_texture(graph, sm.texture);
-
-        // The frame's surface handles exist now, so this is where the records that carry them are
-        // published. There is no colour yet, which is what makes this the phase for G-buffer work.
-        frame.phase = FramePhase.AfterGBuffer;
-
-        const record_gbuffer = frame.create(GBufferTextures);
-        const record_view_textures = frame.create(ViewTextures);
-
-        record_gbuffer.albedo = gr_texture_material_albedo_ao;
-        record_gbuffer.normal = gr_texture_normal;
-        record_gbuffer.pbr = gr_texture_pbr;
-        record_gbuffer.emissive = gr_texture_material_emissive;
-
-        record_view_textures.depth = gr_texture_depth_current;
-        record_view_textures.depth_previous = gr_texture_depth_previous;
-        record_view_textures.visibility_mesh = gr_viz_buffer_mesh;
-        record_view_textures.visibility_triangle = gr_viz_buffer_triangle;
-
-        this.#extensions.run(frame);
-
-        /*
-         `GBufferTextures` is in/out at this phase, and frozen after it. An extension that wants to
-         *change* surface properties — decals are the reason this exists — cannot blend into these
-         targets: two of the four are integer formats, and one texture cannot be a render attachment
-         and a sampled source in the same pass. So it reads them, writes replacements, and publishes
-         the new handles. Everything downstream carries what it left.
-
-         Writing the originals in place would work by accident rather than by contract: a written
-         handle is a *renamed* clone of the same physical resource, so the change would land in the
-         texture the shading pass reads only because the graph happens to execute in insertion
-         order, with no dependency edge saying so. Threading the handles makes the edge real.
-        */
-        gr_texture_pbr = record_gbuffer.pbr;
-        gr_texture_normal = record_gbuffer.normal;
-        gr_texture_material_albedo_ao = record_gbuffer.albedo;
-        gr_texture_material_emissive = record_gbuffer.emissive;
-
-        gr_texture_depth_current = record_view_textures.depth;
-        gr_texture_depth_previous = record_view_textures.depth_previous;
-        gr_viz_buffer_mesh = record_view_textures.visibility_mesh;
-        gr_viz_buffer_triangle = record_view_textures.visibility_triangle;
-
-        // Velocity pass with three branches: rotation-reprojection
-        // background, rigid per-object foreground (mesh.global delta),
-        // and skinned per-vertex foreground (barycentric interpolation
-        // of the triangle's mesh-local `position_prev` written by
-        // skinning into the side-buffer the skinning context owns).
-        // Per-vertex limb deformation lands in the final pixel-space
-        // velocity, so TAA reads correct history for character animation.
-        const gr_scene_database_for_velocity = graph_import_buffer(
-            graph, scene_ctx.scene_database_buffer, "scene_database/velocity"
-        );
-        const gr_meshlet_metadata_for_velocity = graph_import_buffer(
-            graph, scene_ctx.geometries.meshlets.buffer_metadata, "meshlet_metadata/velocity"
-        );
-        const gr_meshlet_data_for_velocity = graph_import_buffer(
-            graph, scene_ctx.geometries.meshlets.buffer_data, "meshlet_data/velocity"
-        );
-        // Skinning side-buffers — both null when no SkinnedMesh has
-        // been registered. The velocity shader still references these
-        // bindings (the dormant per-vertex branch), so the bind group
-        // must supply *something*; use the scene_database buffer as a
-        // placeholder when skinning is inactive. The shader is told via
-        // `skinning_active` whether the bindings are real — when false
-        // it never reads them and forces the rigid path, so the
-        // placeholder is never sampled. (Binding the placeholder
-        // without that guard was the source of phantom velocity on
-        // static meshes: `prev_position_offsets[meshlet_id]` read an
-        // unrelated scene_database word, and any non-0xFFFFFFFF value
-        // sent a static triangle down the skinned branch.)
-        const skinning_ctx = scene_ctx.skinning;
-        const skinning_active = skinning_ctx.prev_position_offsets_buffer !== null
-            && skinning_ctx.prev_positions_buffer !== null;
-        const gr_prev_position_offsets = graph_import_buffer(
-            graph,
-            skinning_ctx.prev_position_offsets_buffer ?? scene_ctx.scene_database_buffer,
-            "prev_position_offsets/velocity",
-        );
-        const gr_prev_positions = graph_import_buffer(
-            graph,
-            skinning_ctx.prev_positions_buffer ?? scene_ctx.scene_database_buffer,
-            "prev_positions/velocity",
-        );
-
-        let gr_velocity = graph_add_per_object_velocity({
-            graph,
-            texture_depth: gr_texture_depth_current,
-            texture_viz_mesh: gr_viz_buffer_mesh,
-            texture_viz_triangle: gr_viz_buffer_triangle,
-            buffer_scene_database: gr_scene_database_for_velocity,
-            buffer_meshlet_metadata: gr_meshlet_metadata_for_velocity,
-            buffer_meshlet_data: gr_meshlet_data_for_velocity,
-            buffer_prev_position_offsets: gr_prev_position_offsets,
-            buffer_prev_positions: gr_prev_positions,
-            skinning_active,
-            resolution,
-            view: view_ctx,
-            enable_mipmap: true
-        });
-
-        // gr_velocity = graph_mipmap_nearest(graph, gr_velocity, G_BUFFER_MIP_LEVELS);
-
-        let [gr_occlusion_clip] = graph_image_pass({
-            graph,
-            shader: shader_depth_occlusion_clip,
-            output_resolution: view_ctx.resolution,
-            // mipmaps are going to be necessary for half-resolution post-process passes
-            output_mipmaps: true,
-            inputs: {
-                camera_current: gr_buffer_camera_current,
-                camera_previous: gr_buffer_camera_previous,
-                DepthBuffer: gr_texture_depth_current,
-                PrevDepthBuffer: gr_texture_depth_previous,
-                VelocityBuffer: gr_velocity
-            }
-        });
-
-        const light_clusters = graph_build_light_clusters({
-            graph,
-            lights: lights,
-            camera: view_ctx.camera,
-            hzb: gr_texture_hzb,
-            resolution: view_ctx.resolution,
-        });
-
-        // Build the view's volumetric fog LUTs (participating media -> per-froxel lighting ->
-        // ray-marched integration). Needs the light clusters and shadow atlas. Built every frame so
-        // the transparency (OIT) pass always has a valid LUT to sample — an empty scene integrates
-        // to a no-op (transmittance 1, in-scatter 0). The opaque composite below is still skipped
-        // when the scene has no fog.
-        const has_volumetrics = view_ctx.scene.volumetrics.source.volumes.length > 0;
-
-        const volumetrics = view_ctx.volumetrics.graph_update({
-            graph,
-            light_cluster_data: light_clusters.data,
-            light_cluster_lookup: light_clusters.lookup,
-            light_cluster_parameters: light_clusters.parameters,
-            shadowmap_atlas: gr_shadowmap_atlas,
-        });
-
-        /**
-         *
-         * @type {number}
-         */
-        let current_color_out = -1;
-
-        // ReSTIR DI — stochastic direct lighting of local (point+spot) lights.
-        // When enabled, resolve per-pixel point+spot radiance and shade with the
-        // ReSTIR deferred variant (no brute-force cluster loop). The variant is a
-        // separate compiled shader, selected here at the JS level rather than via
-        // a runtime branch inside the shader.
-        let deferred_shader = shader_deferred_main;
-
-        const deferred_inputs = {
-            gBufferDepth: gr_texture_depth_current,
-            gBufferPBR: gr_texture_pbr,
-            gBufferNormal: gr_texture_normal,
-            gBufferAlbedo: gr_texture_material_albedo_ao,
-            gBufferEmissive: gr_texture_material_emissive,
-
-            //
-            light_data: lights.buffer_data,
-            tEnvironment: gr_texture_environment,
-
-            // light clusters
-            cluster_parameters: light_clusters.parameters,
-            cluster_lookup: light_clusters.lookup,
-            cluster_data: light_clusters.data,
-
-            // shadows
-            shadowmapAtlas: gr_shadowmap_atlas,
-
-            //
-            camera: view_ctx.camera.buffer,
-            view: view_ctx.uniform_buffer.buffer,
-        };
-
-        if (this.feature_restir_di_enabled) {
-            deferred_shader = shader_deferred_main_restir;
-
-            deferred_inputs.tRestirRadiance = this.#restir_di.execute({
-                graph,
-                view: view_ctx,
-                depth: gr_texture_depth_current,
-                pbr: gr_texture_pbr,
-                normal: gr_texture_normal,
-                albedo: gr_texture_material_albedo_ao,
-                emissive: gr_texture_material_emissive,
-                velocity: gr_velocity,
-                occlusion_clip: gr_occlusion_clip,
-                hzb: gr_texture_hzb,
-                cluster_parameters: light_clusters.parameters,
-                cluster_lookup: light_clusters.lookup,
-                cluster_data: light_clusters.data,
-            });
-        }
-
-        // Main shading pass
-        [current_color_out] = graph_image_pass({
-            graph,
-            shader: deferred_shader,
-            input_depth: gr_texture_depth_current,
-            inputs: deferred_inputs,
-            output_resolution: view_ctx.resolution,
-        });
-
-
-        let bent_normals = -1;
-
-        if (this.feature_ssao_enabled) {
-
-            const ssao = this.#postprocess.ssao.graph_pass({
-                graph: graph,
-                frame_index: this.#frame_count,
-                input_depth: gr_texture_depth_current,
-                input_color: current_color_out,
-                input_depth_previous: gr_texture_depth_previous,
-                input_velocity: gr_velocity,
-                input_normal: gr_texture_normal,
-                input_occlusion: gr_occlusion_clip,
-                // NOTE: AO is blended into the G-buffer
-                output: gr_texture_material_albedo_ao,
-                camera: gr_buffer_camera_current,
-                resolution: resolution,
-            });
-
-            gr_texture_material_albedo_ao = ssao.occlusion;
-            bent_normals = ssao.bent_normals;
-
-        } else {
-
-            // default to shading normals
-            bent_normals = gr_texture_normal;
-
-        }
-
-
-        // Shade background
-        [current_color_out] = graph_image_pass({
-            graph,
-            shader: shader_background,
-            inputs: {
-                camera: view_ctx.camera.buffer,
-                view: view_ctx.uniform_buffer.buffer,
-                tEnvironment: gr_texture_environment,
-            },
-            input_depth: gr_texture_depth_current,
-            load_op: "load",
-            output: [current_color_out],
-        });
-
-        {
-            // Fused brick4 path: skip the intermediate diffuse/specular targets and the
-            // separate resolve, doing it all in a single shader. SSR isn't compatible
-            // since it consumes the standalone specular target.
-            const use_fused_indirect = this.fused_indirect
-                && this.indirect_lighting_mode === ShadeIndirectLightingMode.Brick4
-                && !this.feature_ssr_enabled;
-
-            if (use_fused_indirect) {
-
-                [current_color_out] = graph_image_pass({
-                    graph,
-                    shader: shader_brick4_indirect_lighting,
-                    output: [current_color_out],
-                    input_depth: gr_texture_depth_current,
-                    load_op: "load",
-                    inputs: {
-                        tDepth: gr_texture_depth_current,
-                        tGBufferNormals: gr_texture_normal,
-                        tBentNormals: bent_normals,
-                        tGBufferAlbedo: gr_texture_material_albedo_ao,
-                        tGBufferPBR: gr_texture_pbr,
-                        tSTBN_vec2: STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2,
-                        view: view_ctx.uniform_buffer.buffer,
-                        camera: gr_buffer_camera_current,
-                        //
-                        brick4: scene_ctx.volumetric_light_map.buffer,
-                        tSplitSum: STATIC_GRAPHICS_ENGINE_ASSETS.split_sum,
-                    },
-                });
-
-            } else {
-
-                const { indirect_specular, indirect_diffuse } = this.#graph_indirect_lighting({
-                    graph,
-                    view_ctx,
-                    scene_ctx,
-                    bent_normals,
-                    current_color_out,
-                    //
-                    gr_texture_depth_current,
-                    gr_texture_hzb,
-                    gr_texture_material_albedo_ao,
-                    gr_texture_pbr,
-                    gr_texture_normal,
-                    gr_texture_environment,
-                    gr_velocity,
-                    gr_occlusion_clip,
-                    gr_buffer_camera_current,
-                    gr_buffer_camera_previous,
-                    resolution,
-                });
-
-                // resolve indirect lighting
-                [current_color_out] = graph_image_pass({
-                    graph,
-                    shader: shader_resolve_indirect_lighting,
-                    output: [current_color_out],
-                    input_depth: gr_texture_depth_current,
-                    load_op: "load",
-                    inputs: {
-                        tIndirectDiffuse: indirect_diffuse,
-                        tIndirectSpecular: indirect_specular,
-                        //
-                        tGBufferNormals: gr_texture_normal,
-                        tBentNormals: bent_normals,
-                        tGBufferAlbedo: gr_texture_material_albedo_ao,
-                        tGBufferPBR: gr_texture_pbr,
-                        tDepth: gr_texture_depth_current,
-                        //
-                        camera: gr_buffer_camera_current,
-                        //
-                        tSplitSum: STATIC_GRAPHICS_ENGINE_ASSETS.split_sum,
-                    },
-                });
-
-            }
-
-            // current_color_out = indirect_diffuse
-            // current_color_out = indirect_specular
-
-        }
-
-        // current_color_out = graph_decode_rgbe9995_to_rgb16float({
-        //     graph,
-        //     input:indirect_diffuse_near_field,
-        //     resolution: view_ctx.resolution,
-        // });
-        //
-        // const [norm] = graph_image_pass({
-        //     shader: shader_decode_octahedral_normal,
-        //     inputs:{
-        //         tInput: bent_normals,
-        //     },
-        //     graph,
-        //     output_resolution: view_ctx.resolution,
-        // });
-        //
-        // [current_color_out] = graph_image_pass({
-        //     graph,
-        //     shader: shader_draw_normals,
-        //     inputs:{
-        //         tInput: norm,
-        //     },
-        //     output_resolution: view_ctx.resolution,
-        // });
-
-        // Composite volumetric fog over the finalized opaque + background + indirect colour.
-        // A dedicated pass (not inline in the shading shaders) because indirect lighting is added
-        // in a separate additively-blended pass, so the full surface radiance only exists here.
-        // Runs before transparency (transparent surfaces blend over the fog) and before the main
-        // TAA (which then smooths the fog's per-pixel sampling noise).
-        if (has_volumetrics) {
-            [current_color_out] = graph_image_pass({
-                graph,
-                shader: shader_composite_volumetrics,
-                output_resolution: view_ctx.resolution,
-                inputs: {
-                    tColor: current_color_out,
-                    gBufferDepth: gr_texture_depth_current,
-                    tVolumetrics: volumetrics.resolved,
-                    tSTBN_vec3: STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3,
-                    volumetrics_metadata: volumetrics.metadata,
-                    camera: view_ctx.camera.buffer,
-                    view: view_ctx.uniform_buffer.buffer,
-                },
-            });
-        }
-
-        /*
-         The frame has a colour for the first time, so this is where `SceneColor` is published. It is
-         republished before each later phase because the built-in passes between them replace it —
-         the record names which handle currently *means* the scene colour, and the graph already
-         holds the dependency edge underneath.
-        */
-        frame.phase = FramePhase.AfterLighting;
-
-        const record_scene_color = frame.create(SceneColor);
-
-        record_scene_color.color = current_color_out;
-
-        this.#extensions.run(frame);
-
-        current_color_out = record_scene_color.color;
-        gr_texture_depth_current = record_view_textures.depth;
-
-        if (this.#feature_enabled_transparencies) {
-            // do transparent alpha pass
-            current_color_out = graph_rasterize_meshes_transparent_oit({
-                graph,
-                buckets: gr_render_buckets,
-                view_ctx,
-                viewport: [0, 0, resolution_internal.x, resolution_internal.y],
-                color_texture: current_color_out,
-                depth_texture: gr_texture_depth_current,
-
-                limits: this.graphics.collection_limits,
-
-                light_cluster_data: light_clusters.data,
-                light_cluster_lookup: light_clusters.lookup,
-                light_cluster_parameters: light_clusters.parameters,
-
-                shadowmap_atlas: gr_shadowmap_atlas,
-
-                volumetrics_lut: volumetrics.resolved,
-                volumetrics_metadata: volumetrics.metadata,
-
-                indirect_lighting_mode: this.indirect_lighting_mode,
-            });
-        }
-
-        frame.phase = FramePhase.AfterTransparency;
-
-        record_scene_color.color = current_color_out;
-
-        this.#extensions.run(frame);
-
-        current_color_out = record_scene_color.color;
-        gr_texture_depth_current = record_view_textures.depth;
-
-        // current_color_out = gr_texture_material_albedo_ao;
-
-        // current_color_out = this.path_tracer.render({
-        //     graph,
-        //     view: view_ctx
-        // });
-
-        // Debug override: replace the post-shading color with a
-        // visualization of the velocity buffer via shader_debug_velocity.
-        // Direction is encoded as hue (red = +X, cyan = -X, etc.) and
-        // magnitude as brightness; the AO channel of the albedo+AO
-        // G-buffer modulates the static base so geometry shape is
-        // still readable where motion is zero or near-zero. Done
-        // BEFORE TAA so the chain stays well-formed; TAA blending
-        // the debug view is meaningless, but it's debug.
-        if (this.feature_velocity_debug_view) {
-            [current_color_out] = graph_image_pass({
-                graph,
-                shader: shader_debug_velocity,
-                inputs: {
-                    tInput: gr_velocity,
-                    tAlbedoAO: gr_texture_material_albedo_ao,
-                },
-                output_resolution: resolution_internal.asArray(),
-            });
-        }
-
-        if (this.feature_taa_enabled) {
-
-            if (this.upscale_type === ShadeUpscalerType.NSS) {
-                current_color_out = this.nss.graph_pass({
-                    graph,
-                    texture_color_current: current_color_out,
-                    texture_depth_current: gr_texture_depth_current,
-                    texture_velocity: gr_velocity,
-                    texture_disocclusion_confidence: gr_occlusion_clip,
-                    texture_color_history: gr_texture_taa_history,
-                    texture_output: gr_texture_taa_out,
-                    render_resolution: resolution_internal.asArray(),
-                    output_resolution: this.#output_resolution.asArray(),
-                });
-            } else {
-                current_color_out = taa.graph_pass({
-                    graph,
-                    texture_output: gr_texture_taa_out,
-                    texture_color_current: current_color_out,
-                    texture_color_history: gr_texture_taa_history,
-                    texture_velocity: gr_velocity,
-                    texture_occlusion: gr_occlusion_clip,
-                    camera_current: gr_buffer_camera_current,
-                    camera_previous: gr_buffer_camera_previous,
-                });
-            }
-        }
-
-        // Bokeh depth of field on the resolved HDR colour. Runs after
-        // TAA (blurs a clean, converged image — TAA's neighbourhood
-        // clamp would otherwise fight the defocus) and before motion
-        // blur / bloom, so out-of-focus highlights bloom and the bokeh
-        // carries through the rest of the post chain. Perspective-only:
-        // the thin-lens CoC has no meaning under orthographic.
-        if (this.feature_dof_enabled && camera.isPerspectiveCamera === true) {
-            // Both implementations share the same render() signature, so the
-            // call site is identical — only the subsystem differs.
-            const dof = this.dof_algorithm === "unreal"
-                ? this.#depth_of_field_unreal
-                : this.#depth_of_field;
-
-            current_color_out = dof.render({
-                graph,
-                input_color: current_color_out,
-                depth: gr_texture_depth_current,
-                camera,
-                camera_buffer: view_ctx.camera.buffer,
-                resolution: this.#output_resolution.asArray(),
-            });
-        }
-
-        // Jimenez 2014 motion blur runs on the resolved-but-not-
-        // sharpened HDR colour. TAA has already converged the
-        // jittered samples; sharpening, bloom, and tonemap operate
-        // on the blurred output after this. Skipped when the toggle
-        // is off so the rest of the chain stays bit-identical.
-        if (this.feature_motion_blur_enabled) {
-            current_color_out = this.#motion_blur.render({
-                graph,
-                input_color: current_color_out,
-                velocity: gr_velocity,
-                depth: gr_texture_depth_current,
-                resolution: this.#output_resolution.asArray(),
-            });
-        }
-
-        // TODO if TAA is disabled, and internal resolution is < 100% - we need to do upscale
-
-        if (this.feature_sharpening_enabled) {
-            [current_color_out] = graph_image_pass({
-                graph,
-                shader: shader_ffx_rcas,
-                output_resolution: this.#output_resolution.asArray(),
-                inputs: {
-                    tInput: current_color_out,
-                    uSharpness: {
-                        value: 0.8
-                    }
-                }
-            });
-        }
-
-        let exposure = -1;
-
-        if (this.feature_bloom_enabled || this.feature_automatic_exposure_enabled) {
-            const bloom = graph_postprocess_bloom({
-                graph,
-                input: current_color_out,
-                resolution: this.#output_resolution.asArray(),
-            });
-
-            if (this.feature_bloom_enabled) {
-                current_color_out = bloom.composited;
-            }
-
-            if (this.feature_automatic_exposure_enabled) {
-                // TODO force time_delta_second to a very high value on view transition
-
-                exposure = this.#autoexposure.update({
-                    graph,
-                    input_color: bloom.downsampled,
-                    time_delta_seconds,
-                });
-            }
-
-        }
-
-
-        if (this.feature_automatic_exposure_enabled === false) {
-            exposure = this.#autoexposure.unadapted({ graph });
-        }
-
-
-        // current_color_out = graph_draw_texture_as_rgba({
-        //     graph,
-        //     source: gr_shadowmap_atlas,
-        //     resolution: this.#output_resolution.asArray(),
-        // });
-
-        /*
-         Past the upscale: the colour published here is output-sized while the G-buffer beside it is
-         still internal-sized, and `FrameContext.resolution` reads whichever of them the phase draws
-         into rather than a number anybody wrote down. With `feature_taa_enabled === false` no
-         upscale happened and the two agree — which a constant could not express.
-        */
-        frame.phase = FramePhase.BeforePresent;
-
-        record_scene_color.color = current_color_out;
-
-        this.#extensions.run(frame);
-
-        current_color_out = record_scene_color.color;
-
-        if (this.#hdr_supported) {
-            [current_color_out] = graph_image_pass({
-                graph,
-                shader: shader_tonemap_HDR,
-                inputs: {
-                    input_color: current_color_out,
-                    settings: {
-                        peak_nits: this.#display_peak_brightness_nits,
-                        paper_white_nits: 100, // SDR spec is 80, but 100 has been accepted as de-facto in recent years
-                    },
-                    exposure
-                },
-                output: [gr_texture_canvas]
-            });
-        } else {
-            [current_color_out] = graph_image_pass({
-                graph,
-                shader: shader_tonemap_LDR,
-                inputs: {
-                    input_color: current_color_out,
-                    exposure
-                },
-                output: [gr_texture_canvas]
-            });
-        }
-
-        /*
-         The canvas is written here and cannot be read: a texture may not be a render attachment and
-         a sampled source in the same pass. So what this phase carries is a `PresentTarget` with one
-         field and no colour to be tempted by — an extension that wants the finished image as input
-         finds that out at `get` time and belongs at `BeforePresent`.
-        */
-        frame.phase = FramePhase.Overlay;
-
-        frame.create(PresentTarget).canvas = current_color_out;
-
-        this.#extensions.run(frame);
-
-        frame.close();
-
-        command_ctx.encodeGraph(graph);
-
-        command_ctx.popDebugGroup();
-
-        view_ctx.finish_frame(command_ctx);
-
-        command_ctx.finish();
-
-        this.#end_frame();
-
-        return true;
-    }
-}
+import { assert } from "../../core/assert.js";
+import Signal from "../../core/events/signal/Signal.js";
+import Vector2 from "../../core/geom/Vector2.js";
+import { clamp } from "../../core/math/clamp.js";
+import { remap } from "../../core/math/remap.js";
+import { MetricCollection } from "../../engine/development/performance/MetricCollection.js";
+import {
+    MetricCollectionConsoleMonitor
+} from "../../engine/development/performance/monitor/MetricCollectionConsoleMonitor.js";
+import { FrameGraph } from "../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { TextureDescriptor } from "../descriptor/texture/TextureDescriptor.js";
+import { WebGPUExtensionType } from "../descriptor/WebGPUExtensionType.js";
+import { ShadeDeviceFailure } from "../device/ShadeDeviceFailure.js";
+import { ShadeGPUCommandContext } from "../device/ShadeGPUCommandContext.js";
+import { CameraManager } from "./camera/CameraManager.js";
+import { shader_background } from "./deferred/shader_background.js";
+import { shader_composite_volumetrics } from "./deferred/shader_composite_volumetrics.js";
+import { shader_deferred_main, shader_deferred_main_restir } from "./deferred/shader_deferred_main.js";
+import { ReSTIRDI } from "./restir/di/ReSTIRDI.js";
+import { shader_tonemap_HDR } from "./deferred/shader_tonemap_HDR.js";
+import { shader_tonemap_LDR } from "./deferred/shader_tonemap_LDR.js";
+import { G_BUFFER_MIP_LEVELS } from "./gbuffer/G_BUFFER_MIP_LEVELS.js";
+import {
+    graph_rasterize_meshes_transparent_oit
+} from "./rasterize/native/oit/graph_rasterize_meshes_transparent_oit.js";
+import {
+    viz_rasterization_alpha_tested_pass_descriptor
+} from "./rasterize/native/viz/viz_rasterization_alpha_tested_pass_descriptor.js";
+import {
+    viz_rasterization_opaque_pass_descriptor
+} from "./rasterize/native/viz/viz_rasterization_opaque_pass_descriptor.js";
+import { RasterizationJob } from "./rasterize/RasterizationJob.js";
+import { graph_rasterize_scene } from "./rasterize/standard/graph_rasterize_scene.js";
+import { FrameContext } from "./extension/FrameContext.js";
+import { FramePhase } from "./extension/FramePhase.js";
+import { GBufferTextures } from "./extension/GBufferTextures.js";
+import { PresentTarget } from "./extension/PresentTarget.js";
+import { RenderExtensionRegistry } from "./extension/RenderExtensionRegistry.js";
+import { SceneColor } from "./extension/SceneColor.js";
+import { ViewTextures } from "./extension/ViewTextures.js";
+import { shader_brick4_diffuse } from "./global_illumination/brick4/gpu/draw/shader_brick4_diffuse.js";
+import {
+    shader_brick4_indirect_lighting
+} from "./global_illumination/brick4/gpu/draw/shader_brick4_indirect_lighting.js";
+import { shader_brick4_specular } from "./global_illumination/brick4/gpu/draw/shader_brick4_specular.js";
+import { shader_diffuse_IBL } from "./global_illumination/ibl/shader_diffuse_IBL.js";
+import { shader_specular_IBL } from "./global_illumination/ibl/shader_specular_IBL.js";
+import { GPULightProbeVolumeRenderer } from "./global_illumination/lpv/bake/GPULightProbeVolumeRenderer.js";
+import { shader_diffuse_LPV } from "./global_illumination/lpv/shader_diffuse_LPV.js";
+import { shader_resolve_indirect_lighting } from "./global_illumination/shader_resolve_indirect_lighting.js";
+import { GraphicsContext } from "./GraphicsContext.js";
+import { graph_build_light_clusters } from "./light/cluster/graph_build_light_clusters.js";
+import { AccumulatingPathTracer } from "./path_tracer/accumulating/AccumulatingPathTracer.js";
+import { graph_postprocess_bloom } from "./postprocess/bloom/graph_postprocess_bloom.js";
+import { shader_ffx_rcas } from "./postprocess/cas/shader_ffx_rcas.js";
+import { GPUCameraExposureManager } from "./postprocess/eye/GPUCameraExposureManager.js";
+import { NSS } from "./postprocess/nss/NSS.js";
+import { PostProcess } from "./postprocess/PostProcess.js";
+import { shader_depth_occlusion_clip } from "./postprocess/taa/shader_depth_occlusion_clip.js";
+import { TAA } from "./postprocess/taa/TAA.js";
+import { MotionBlur } from "./postprocess/motion_blur/MotionBlur.js";
+import { DepthOfField } from "./postprocess/dof/raymarch/DepthOfField.js";
+import { DepthOfFieldU } from "./postprocess/dof/gather/DepthOfFieldU.js";
+import { graph_add_per_object_velocity } from "./postprocess/velocity/graph_add_per_object_velocity.js";
+import { SceneManager } from "./scene/SceneManager.js";
+import { ShadeIndirectLightingMode } from "./ShadeIndirectLightingMode.js";
+import { ShadeUpscalerType } from "./ShadeUpscalerType.js";
+import { graph_image_pass } from "./shader/graph/graph_image_pass.js";
+import { graph_import_buffer } from "./shader/graph/graph_import_buffer.js";
+import { graph_import_texture } from "./shader/graph/graph_import_texture.js";
+import { CascadedSceneSDF } from "./shadow/sdf/cascade/CascadedSceneSDF.js";
+import { STATIC_GRAPHICS_ENGINE_ASSETS } from "./STATIC_GRAPHICS_ENGINE_ASSETS.js";
+import { shader_debug_velocity } from "./postprocess/velocity/shader_debug_velocity.js";
+import { GPUTextureContext } from "./texture/GPUTextureContext.js";
+import { RenderTarget } from "./texture/RenderTarget.js";
+import { View } from "./view/View.js";
+import { ViewManager } from "./view/ViewManager.js";
+
+const METRICS = new MetricCollection();
+METRICS.create({ name: 'frame_time' });
+
+/**
+ * Depth and G-buffer textures carry {@link G_BUFFER_MIP_LEVELS} mip levels.
+ * WebGPU's createTexture validation requires mipLevelCount <= floor(log2(max(w,h))) + 1,
+ * so the internal resolution must never drop below 2^(G_BUFFER_MIP_LEVELS - 1)
+ * or texture allocation will fail.
+ * @type {number}
+ */
+const INTERNAL_RESOLUTION_MIN = 1 << (G_BUFFER_MIP_LEVELS - 1);
+
+MetricCollectionConsoleMonitor.from(METRICS);
+
+export class Renderer {
+    /**
+     * Indexes current drawn frame
+     * @type {number}
+     */
+    #frame_count = 0;
+
+    get frame_count() {
+        return this.#frame_count;
+    }
+
+    /**
+     * @type {GPUCanvasContext}
+     */
+    context;
+
+    /**
+     * The HTMLCanvasElement (or OffscreenCanvas) bound to this renderer.
+     * If `initialize()` was called without a `context`, this is the canvas
+     * the renderer created — append it to the DOM to display the output.
+     *
+     * @returns {HTMLCanvasElement|OffscreenCanvas|undefined}
+     */
+    get canvas() {
+        return this.context?.canvas;
+    }
+
+    /**
+     * @type {GPUDevice}
+     */
+    device;
+
+    /**
+     * @type {GPUCameraExposureManager}
+     */
+    #autoexposure;
+
+    /**
+     * @type {SceneManager}
+     */
+    #scenes;
+
+    /**
+     * Only use for read-access
+     * @returns {SceneManager}
+     */
+    get scenes() {
+        return this.#scenes;
+    }
+
+    /**
+     * @type {CameraManager}
+     */
+    #cameras
+
+    /**
+     * @type {ViewManager}
+     */
+    #views
+
+
+    set feature_shadows_enabled(v) {
+        assert.isBoolean(v, 'v');
+        this.#feature_shadows_enabled = v;
+    }
+
+    get feature_shadows_enabled() {
+        return this.#feature_shadows_enabled;
+    }
+
+    /**
+     * Controls which indirect lighting technique is used for
+     * both deferred resolve and forward transparency passes.
+     * @type {ShadeIndirectLightingMode}
+     */
+    indirect_lighting_mode = ShadeIndirectLightingMode.IBL;
+
+    feature_ssr_enabled = false;
+    feature_ssao_enabled = true;
+    /**
+     * ReSTIR DI — stochastic screen-bounded direct shadowing of local
+     * (point+spot) lights. When on, the deferred pass skips its froxel cluster
+     * loop and consumes the ReSTIR-resolved radiance instead.
+     */
+    feature_restir_di_enabled = false;
+    /**
+     * Generate point-light shadows with the tetrahedral (4-face) path instead of the default
+     * cube (6-face) path. Both produce the same octahedral atlas encoding, so this is safe to
+     * flip at runtime and is meant for A/B comparison of the two generators. Pushed to the
+     * scene's shadow context each frame; see
+     * {@link GPUSceneShadowmapContext.use_tetrahedron_point_shadows}.
+     * @type {boolean}
+     */
+    feature_tetrahedron_point_shadows = false;
+    feature_bloom_enabled = true;
+    feature_automatic_exposure_enabled = true;
+
+    /**
+     * Virtual texture streaming (opt-in per material via
+     * {@link StandardShadeMaterial#vt_stack}). This flag is the system-wide
+     * kill switch: when off, the feedback pass and residency maintenance
+     * stop running — already-resident pages keep rendering, nothing new
+     * streams in. Costs nothing while no stack is registered.
+     * @type {boolean}
+     */
+    feature_virtual_textures = true;
+
+    #feature_taa_enabled = true;
+
+    get feature_taa_enabled() {
+        return this.#feature_taa_enabled;
+    }
+
+    /**
+     * While TAA is off nothing writes the history textures, but the frame counter that
+     * indexes them keeps advancing — re-enabling would blend with arbitrarily stale
+     * history of arbitrary parity. Reset temporal history on the transition.
+     * @param {boolean} v
+     */
+    set feature_taa_enabled(v) {
+        if (this.#feature_taa_enabled === v) {
+            return;
+        }
+
+        this.#feature_taa_enabled = v;
+        this.indicate_view_change();
+    }
+
+    /**
+     * Jimenez 2014 reconstruction-filter motion blur, runs between
+     * TAA and sharpening on the HDR colour. Reads the velocity buffer
+     * the same way TAA does — per-pixel pixel-space deltas — and
+     * scatter-gathers along the dilated tile velocity. Off by default
+     * because the reconstruction pass is a few-ms-budget item and not
+     * every scene needs it.
+     *
+     * @type {boolean}
+     */
+    feature_motion_blur_enabled = false;
+
+    /**
+     * Motion-blur subsystem (Jimenez 2014 reconstruction filter). A
+     * self-contained manager — same pattern as {@link #autoexposure} /
+     * {@link #depth_of_field} — that owns the motion-blur parameters
+     * (currently just `strength`). Constructed in init.
+     * @type {MotionBlur}
+     */
+    #motion_blur;
+
+    /**
+     * The motion-blur subsystem. Configure it via `renderer.motion_blur.*`
+     * (currently `strength`); toggle the effect with
+     * {@link feature_motion_blur_enabled}.
+     * @returns {MotionBlur}
+     */
+    get motion_blur() { return this.#motion_blur; }
+
+    /**
+     * Debug-only override: when true, the per-object velocity texture
+     * is drawn straight into the post-TAA color path so the screen
+     * shows the velocity buffer instead of the rendered image. Wired
+     * just before TAA — TAA then operates on the velocity texture,
+     * which is nonsense but cheap to set up. Default false.
+     *
+     * @type {boolean}
+     */
+    feature_velocity_debug_view = false;
+
+    /**
+     * Screen-space ray-marched depth of field — the Tiny Glade model
+     * (Stachowiak, GPC 2024; see {@link DepthOfField}): aperture sub-rays
+     * marched through the half-res depth/CoC buffer with nearest-hit
+     * occlusion, plus tilt-shift. Runs on the resolved HDR colour after TAA
+     * (which resolves the march's sample noise) and before motion blur. Off
+     * by default — a half-res march is a few-ms item, only worth it for a
+     * deliberate shallow-focus / diorama look. Configure via `renderer.dof`.
+     *
+     * @type {boolean}
+     */
+    feature_dof_enabled = false;
+
+    /**
+     * Depth-of-field subsystem (screen-space ray-marched). A self-contained
+     * manager — same pattern as {@link #autoexposure} — that owns all DoF
+     * parameters, focus state, and GPU buffers. Constructed in init.
+     * @type {DepthOfField}
+     */
+    #depth_of_field;
+
+    /**
+     * The depth-of-field subsystem. Configure it via `renderer.dof.*`
+     * (`f_number`, `quality`, the `focus*` helpers, `applyPreset`, …);
+     * toggle the effect with {@link feature_dof_enabled}.
+     * @returns {DepthOfField}
+     */
+    get dof() { return this.#depth_of_field; }
+
+    /**
+     * Which depth-of-field implementation runs when {@link feature_dof_enabled}
+     * is on. `"raymarch"` (default) is the screen-space ray-march
+     * ({@link DepthOfField}); `"unreal"` is the gather-based Diaphragm /
+     * Cinematic DoF ({@link DepthOfFieldU}) — half-res near/far gather with a
+     * foreground coverage bleed. Mutually exclusive by construction (only one
+     * runs at the single DoF call site).
+     * @type {"raymarch"|"unreal"}
+     */
+    dof_algorithm = "raymarch";
+
+    /**
+     * Unreal-style (Diaphragm / Cinematic) gather depth of field — a drop-in
+     * alternative to {@link #depth_of_field}, selected via {@link dof_algorithm}.
+     * Constructed in init.
+     * @type {DepthOfFieldU}
+     */
+    #depth_of_field_unreal;
+
+    /**
+     * The Unreal-style depth-of-field subsystem. Configure it via
+     * `renderer.dof_unreal.*` and select it with `renderer.dof_algorithm = "unreal"`.
+     * @returns {DepthOfFieldU}
+     */
+    get dof_unreal() { return this.#depth_of_field_unreal; }
+
+    /**
+     * When true and {@link indirect_lighting_mode} is Brick4, run a single fused
+     * pass that produces the resolved indirect lighting directly (combining the
+     * brick4 diffuse, brick4 specular and indirect resolve passes). Trades a
+     * bit of cache pressure inside the pass for substantially less memory
+     * bandwidth: no intermediate rgba16float diffuse/specular targets, the
+     * g-buffer is read once, and a single brick4 probe pair is shared between
+     * the diffuse and specular evaluations.
+     *
+     * SSR is mutually exclusive with the fused path (it needs the standalone
+     * specular target as input), so when SSR is enabled the split path is used.
+     * @type {boolean}
+     */
+    fused_indirect = true;
+
+    /**
+     * RCAS
+     * @type {boolean}
+     */
+    feature_sharpening_enabled = true;
+
+    #feature_shadows_enabled = true;
+    #feature_enabled_transparencies = true;
+
+    /**
+     *
+     * @return {ViewManager}
+     */
+    get views() {
+        return this.#views;
+    }
+
+    /**
+     * @type {GraphicsContext}
+     */
+    #graphics;
+
+    /**
+     *
+     * @return {GraphicsContext}
+     */
+    get graphics() {
+        return this.#graphics;
+    }
+
+
+    /**
+     *
+     * @type {Signal<number>}
+     */
+    /**
+     * Extensions an outside caller has put into the frame, by phase.
+     *
+     * @type {RenderExtensionRegistry}
+     */
+    #extensions = new RenderExtensionRegistry();
+
+    /**
+     * Raised when there is no usable device — the browser has no WebGPU, the hardware is below the
+     * floor, or a working device was lost while running. Carries a {@link ShadeDeviceFailure}.
+     *
+     * The floor is deliberate and there are no fallbacks (D6/I-8), so telling the player plainly is
+     * the whole of what the engine owes here. Loss is not recovered from (R6): everything built on
+     * the device went with it, and the honest response is a message and a reload.
+     *
+     * @type {Signal<ShadeDeviceFailure>}
+     */
+    onDeviceFailure = new Signal();
+
+    onFrameFinished = new Signal();
+
+    /**
+     * First argument is frame index, second is table of debug data
+     * @type {Signal<number, Object[]>}
+     */
+    onFrameDebug = new Signal();
+
+
+    /**
+     * Fraction of the output resolution.
+     * Controls {@link #internal_resolution}.
+     * If this is set to 0.5 for example - internal resolution will be 50% of the output resolution.
+     * @type {number}
+     */
+    #internal_resolution_scale = 1;
+
+    /**
+     *
+     * @type {boolean}
+     */
+    #internal_resolution_needs_update = true;
+
+    /**
+     *
+     * @param {number} v
+     */
+    set internal_resolution_scale(v) {
+        assert.isNumber(v, 'v');
+        assert.notNaN(v, 'v');
+        assert.greaterThan(v, 0);
+        assert.isFinite(v, 'v');
+
+        if (this.#internal_resolution_scale === v) {
+            // no change
+            return;
+        }
+
+        this.#internal_resolution_scale = v;
+
+        // schedule resolution recalculation
+        this.#internal_resolution_needs_update = true;
+    }
+
+    /**
+     *
+     * @returns {number}
+     */
+    get internal_resolution_scale() {
+        return this.#internal_resolution_scale;
+    }
+
+    /**
+     * This is the resolution that the rendering happens at before upscaling.
+     * Derived from input resolution via {@link internal_resolution_scale}
+     * @type {Vector2}
+     */
+    #internal_resolution = new Vector2(1, 1);
+
+
+    /**
+     * Output viewport size
+     * @type {Vector2}
+     */
+    #size = new Vector2(1, 1);
+
+    /**
+     * Output resolution.
+     * Equal to {@link size} * {@link pixel_ratio}
+     * Don't write directly
+     * @type {Vector2}
+     * @see {#size}
+     * @see {#pixel_ratio}
+     */
+    #output_resolution = new Vector2(1, 1);
+
+    /**
+     *
+     * @returns {Vector2}
+     */
+    get output_resolution() {
+        return this.#output_resolution.clone();
+    }
+
+    /**
+     * width/height
+     * Useful for camera projection setup
+     * @return {number}
+     */
+    get aspect_ratio() {
+        return this.#internal_resolution.x / this.#internal_resolution.y;
+    }
+
+    /**
+     * TODO rework ping-ping buffer usage to release old buffer when no longer needed. Can reach much better resource utilization that way. Same for all other TAA-like techniques
+     * @type {GPUTextureContext[]}
+     */
+    #textures_depth = new Array(2);
+
+    /**
+     *
+     * @returns {GPUTextureContext}
+     */
+    get texture_depth_current() {
+        const tx = this.#textures_depth;
+
+        return tx[this.#frame_count % tx.length];
+    }
+
+    /**
+     *
+     * @returns {GPUTextureContext}
+     */
+    get texture_depth_previous() {
+        const tx = this.#textures_depth;
+
+        return tx[(this.#frame_count - 1 + tx.length) % tx.length];
+    }
+
+    /**
+     *
+     * @type {GPUTextureContext[]}
+     */
+    #textures_taa_history = new Array(2);
+
+    /**
+     *
+     * @returns {GPUTextureContext}
+     */
+    #get_texture_taa_history(x) {
+        const tx = this.#textures_taa_history;
+
+        return tx[(this.#frame_count - x + tx.length) % tx.length];
+    }
+
+
+    /**
+     * @type {GPUTextureFormat}
+     */
+    #presentation_format = "rgba8unorm";
+
+    /**
+     * How many pixels to draw per screen pixel.
+     * Typically, this is used to match physical screen resolution to virtual resolution.
+     * On the high pixel density displays, CSS pixels usually take up more than one screen pixel.
+     * @type {number}
+     */
+    #pixel_ratio = window.devicePixelRatio;
+
+    /**
+     *
+     * @return {number}
+     */
+    get pixel_ratio() {
+        return this.#pixel_ratio;
+    }
+
+    /**
+     *
+     * @param {number} ratio
+     */
+    set pixel_ratio(ratio) {
+        assert.isNumber(ratio, 'ratio');
+        assert.notNaN(ratio, 'ratio');
+        assert.greaterThan(ratio, 0);
+        assert.isFinite(ratio, 'ratio');
+
+        if (ratio === this.#pixel_ratio) {
+            // no change
+            return;
+        }
+
+        this.#pixel_ratio = ratio;
+
+        this.#update_resolution();
+    }
+
+    /**
+     * How many future frames should be debugged
+     * @type {number}
+     */
+    #debug_frame_count = 0;
+
+    /**
+     * Increase the number of future debug frames by X
+     */
+    /**
+     * Record work into the frame at a named point in it.
+     *
+     * The extension is called once per frame, when its phase comes round, and is handed the
+     * {@link FrameContext} — the frame's graph and the typed records holding the handles that exist
+     * at that moment. It records with the `graph_*` helpers exactly as the built-in passes do, and
+     * everything it produces reaches the rest of the frame by publishing a handle into a record.
+     *
+     * Handles come from the records rather than from the renderer on purpose: the graph is what
+     * knows which resources a pass touched, and work recorded around it cannot be ordered or aliased
+     * correctly against the rest of the frame.
+     *
+     * @param {RenderExtension} extension
+     * @returns {RenderExtension} `extension`, for handing back to {@link remove_extension}
+     */
+    add_extension(extension) {
+        return this.#extensions.add(extension);
+    }
+
+    /**
+     * Take an extension back out of the frame.
+     *
+     * @param {RenderExtension} extension
+     * @returns {boolean} whether it was registered
+     */
+    remove_extension(extension) {
+        return this.#extensions.remove(extension);
+    }
+
+    /**
+     * @param {FramePhase} phase
+     * @returns {number} how many extensions are registered on `phase`
+     */
+    extension_count(phase) {
+        return this.#extensions.count(phase);
+    }
+
+
+    add_debug_frame(count = 1) {
+        assert.isNonNegativeInteger(count, 'count');
+
+        this.#debug_frame_count += count;
+    }
+
+    /**
+     *
+     * @type {Map<Scene, GPULightProbeVolumeRenderer>}
+     */
+    #probe_bakers = new Map();
+
+
+    /**
+     *
+     * @type {Map<Scene, CascadedSceneSDF>}
+     */
+    #scene_sdfs = new Map();
+
+    /**
+     *
+     * @param {Scene} scene
+     * @return {CascadedSceneSDF}
+     */
+    obtains_scene_sdf(scene) {
+        let sdf = this.#scene_sdfs.get(scene);
+
+        if (sdf === undefined) {
+            sdf = new CascadedSceneSDF(this.device);
+            this.#scene_sdfs.set(scene, sdf);
+        }
+
+        return sdf;
+    }
+
+    /**
+     * Used to instruct renderer that either the scene or camera has changed significantly
+     * Primarily instructs resetting history on temporal accumulation
+     */
+    indicate_view_change() {
+        this.#postprocess.reset_history();
+
+        if (this.#path_tracer !== undefined) {
+            this.#path_tracer.clear_history = true;
+        }
+
+        this.#taa.reset_history = true;
+
+        if (this.#nss !== undefined) {
+            this.#nss.reset_history = true;
+        }
+    }
+
+    /**
+     * For internal and debug use only
+     * @param {Scene} scene
+     * @returns {GPULightProbeVolumeRenderer}
+     */
+    getProbeRendererForScene(scene) {
+
+        const scene_ctx = this.#scenes.obtain(scene);
+
+        let baker = this.#probe_bakers.get(scene);
+
+        if (baker === undefined) {
+            baker = new GPULightProbeVolumeRenderer(this.#graphics, scene_ctx);
+            this.#probe_bakers.set(scene, baker);
+        }
+
+        return baker;
+    }
+
+
+    /**
+     *
+     * @param {Scene} scene
+     */
+    update_lpv(scene) {
+
+        //
+        // let baker = this.getProbeRendererForScene(scene);
+        //
+        // baker.autoSetRaysPerProbe(1);
+        // baker.bake();
+
+        const scene_ctx = this.#scenes.obtain(scene);
+
+        const graph = new FrameGraph("LPV");
+
+        const cmd = ShadeGPUCommandContext.create(this.graphics, 'LPV');
+
+        scene_ctx.light_probe_volume.atlas.graph_update({
+            graph,
+            scene: scene_ctx,
+            graphics: this.graphics,
+            update_ray_count: 100_000
+        });
+
+        cmd.encodeGraph(graph);
+        cmd.finish();
+    }
+
+    /**
+     * Compute deferred indirect specular and diffuse contributions
+     * based on the active indirect lighting mode.
+     *
+     * @param {object} params
+     * @param {FrameGraph} params.graph
+     * @param {GPUViewContext} params.view_ctx
+     * @param {GPUSceneContext} params.scene_ctx
+     * @param {number} params.bent_normals - graph resource ID
+     * @param {number} params.current_color_out - graph resource ID (scene color, needed for SSR)
+     * @param {number} params.gr_texture_depth_current
+     * @param {number} params.gr_texture_hzb
+     * @param {number} params.gr_texture_material_albedo_ao
+     * @param {number} params.gr_texture_pbr
+     * @param {number} params.gr_texture_normal
+     * @param {number} params.gr_texture_environment
+     * @param {number} params.gr_velocity
+     * @param {number} params.gr_occlusion_clip
+     * @param {number} params.gr_buffer_camera_current
+     * @param {number} params.gr_buffer_camera_previous
+     * @param {Vector2} params.resolution
+     * @returns {{indirect_specular: number, indirect_diffuse: number}}
+     */
+    #graph_indirect_lighting({
+                                 graph,
+                                 view_ctx,
+                                 scene_ctx,
+                                 bent_normals,
+                                 current_color_out,
+                                 //
+                                 gr_texture_depth_current,
+                                 gr_texture_hzb,
+                                 gr_texture_material_albedo_ao,
+                                 gr_texture_pbr,
+                                 gr_texture_normal,
+                                 gr_texture_environment,
+                                 gr_velocity,
+                                 gr_occlusion_clip,
+                                 gr_buffer_camera_current,
+                                 gr_buffer_camera_previous,
+                                 resolution,
+                             }) {
+
+        const mode = this.indirect_lighting_mode;
+
+        let indirect_specular = -1;
+        let indirect_diffuse = -1;
+
+        const lpv = scene_ctx.light_probe_volume;
+
+        //
+        // ── SPECULAR ────────────────────────────────────────────
+        //
+
+        // SSR replaces the specular IBL fallback when enabled.
+        // NOTE: SSR is currently not supported in Brick4 mode — this is a known
+        // limitation and will be addressed in a future update.
+        if (this.feature_ssr_enabled && mode !== ShadeIndirectLightingMode.Brick4) {
+
+            const ssr = this.#postprocess.ssr.graph_pass({
+                graph,
+                input_depth: gr_texture_depth_current,
+                input_hzb: gr_texture_hzb,
+                input_scene_color: current_color_out,
+                input_albedo: gr_texture_material_albedo_ao,
+                input_pbr: gr_texture_pbr,
+                input_normal: gr_texture_normal,
+                input_velocity: gr_velocity,
+                input_occlusion: gr_occlusion_clip,
+                input_environment: gr_texture_environment,
+                camera_current: gr_buffer_camera_current,
+                camera_previous: gr_buffer_camera_previous,
+                lpv: mode === ShadeIndirectLightingMode.LPV ? lpv : undefined,
+                resolution,
+            });
+
+            indirect_specular = ssr.denoised;
+
+        } else if (mode === ShadeIndirectLightingMode.Brick4) {
+
+            // Brick4 specular from volumetric lightmap
+            [indirect_specular] = graph_image_pass({
+                graph,
+                shader: shader_brick4_specular,
+                input_depth: gr_texture_depth_current,
+                inputs: {
+                    tDepth: gr_texture_depth_current,
+                    tNormals: gr_texture_normal,
+                    tPBR: gr_texture_pbr,
+                    tSTBN_vec2: STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2,
+                    camera: gr_buffer_camera_current,
+                    view: view_ctx.uniform_buffer.buffer,
+                    brick4: scene_ctx.volumetric_light_map.buffer,
+                },
+                output_resolution: view_ctx.resolution,
+            });
+
+        } else {
+            // IBL / LPV fallback — environment map specular
+            [indirect_specular] = graph_image_pass({
+                graph,
+                shader: shader_specular_IBL,
+                input_depth: gr_texture_depth_current,
+                inputs: {
+                    tBentNormals: bent_normals,
+                    tNormals: gr_texture_normal,
+                    tDepth: gr_texture_depth_current,
+                    tPBR: gr_texture_pbr,
+                    tEnvironment: gr_texture_environment,
+                    camera: gr_buffer_camera_current,
+                },
+                output_resolution: view_ctx.resolution,
+            });
+        }
+
+        //
+        // ── DIFFUSE ─────────────────────────────────────────────
+        //
+
+        switch (mode) {
+
+            case ShadeIndirectLightingMode.IBL:
+                // Environment map irradiance
+                [indirect_diffuse] = graph_image_pass({
+                    graph,
+                    shader: shader_diffuse_IBL,
+                    input_depth: gr_texture_depth_current,
+                    inputs: {
+                        tBentNormals: bent_normals,
+                        tGBufferAlbedo: gr_texture_material_albedo_ao,
+                        tEnvironment: gr_texture_environment,
+                    },
+                    output_resolution: view_ctx.resolution,
+                });
+                break;
+
+            case ShadeIndirectLightingMode.Brick4:
+                // Brick4 diffuse from volumetric lightmap
+                [indirect_diffuse] = graph_image_pass({
+                    graph,
+                    shader: shader_brick4_diffuse,
+                    input_depth: gr_texture_depth_current,
+                    inputs: {
+                        tDepth: gr_texture_depth_current,
+                        tBentNormals: bent_normals,
+                        tAlbedoAO: gr_texture_material_albedo_ao,
+                        tSTBN_vec2: STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2,
+                        camera: gr_buffer_camera_current,
+                        view: view_ctx.uniform_buffer.buffer,
+                        brick4: scene_ctx.volumetric_light_map.buffer,
+                    },
+                    output_resolution: view_ctx.resolution,
+                });
+                break;
+
+            case ShadeIndirectLightingMode.LPV:
+                // Light Probe Volume diffuse
+                [indirect_diffuse] = graph_image_pass({
+                    graph,
+                    shader: shader_diffuse_LPV,
+                    input_depth: gr_texture_depth_current,
+                    inputs: {
+                        camera: gr_buffer_camera_current,
+                        tDepth: gr_texture_depth_current,
+                        tBentNormals: bent_normals,
+                        tGBufferAlbedo: gr_texture_material_albedo_ao,
+                        //
+                        lpv_atlas_radiance: lpv.atlas.texture_radiance,
+                        lpv_atlas_depth: lpv.atlas.texture_depth,
+                        //
+                        lpv_lookup: lpv.buffer_mesh_bvh,
+                        lpv_metadata: lpv.buffer_metadata,
+                        lpv_mesh: lpv.buffer_mesh,
+                        lpv_probes: lpv.buffer_probes,
+                    },
+                    output_resolution: view_ctx.resolution,
+                });
+                break;
+        }
+
+        return { indirect_specular, indirect_diffuse };
+    }
+
+    /**
+     * @type {PostProcess}
+     */
+    #postprocess
+
+    /**
+     * @type {ReSTIRDI}
+     */
+    #restir_di
+
+    /**
+     * ReSTIR DI subsystem — exposed for runtime tuning (e.g. GUI toggles like
+     * `use_screen_space_shadow`, `m_initial`).
+     * @returns {ReSTIRDI}
+     */
+    get restir_di() {
+        return this.#restir_di;
+    }
+
+    /**
+     *
+     * @type {TAA}
+     */
+    #taa = new TAA();
+
+    /**
+     * Lazily constructed in {@link initialize} once a graphics context is
+     * available — NSS owns persistent GPU textures, so it can't be a
+     * field initializer like {@link #taa}.
+     * @type {NSS | undefined}
+     */
+    #nss
+
+    /**
+     * Selects which temporal-AA / upscaler runs at the temporal-resolve
+     * stage. Defaults to {@link ShadeUpscalerType.TAA}; assign
+     * {@link ShadeUpscalerType.NSS} to use the bundled neural upscaler
+     * (no extra setup — the NSS instance ships with placeholder weights).
+     * @type {ShadeUpscalerType}
+     */
+    upscale_type = ShadeUpscalerType.TAA;
+
+    /**
+     * Public read access to the NSS instance. Lazily constructed on
+     * first access, which is also when the bundled weights blob is
+     * decoded — so the cost of selecting NSS is amortized to a single
+     * frame.
+     * @returns {NSS}
+     */
+    get nss() {
+        if (this.#nss === undefined) {
+            assert.defined(this.#graphics, 'graphics context not yet initialized — call Renderer.initialize() first');
+            this.#nss = new NSS(this.#graphics);
+
+            // First-time setup: align the jitter sequence size with the
+            // current upscale ratio. Subsequent resolution changes are
+            // picked up by #update_internal_resolution.
+            const out_w = this.#output_resolution.x;
+            const in_w = this.#internal_resolution.x;
+            if (out_w > 0 && in_w > 0) {
+                const upscale_ratio = out_w / in_w;
+                this.#nss.jitter_sequence_size = NSS.recommended_jitter_sequence_size(upscale_ratio);
+            }
+        }
+        return this.#nss;
+    }
+
+    #device_lost = false;
+
+    /**
+     * Handles event when GPUDevice is lost
+     * @param {GPUDeviceLostInfo} info
+     */
+    #handle_device_lost(info) {
+        this.#device_lost = true;
+
+        if (info.reason === "destroyed") {
+            // most likely renderer was destroyed, this is expected behavior
+            // TODO check if renderer owns the device, if not, log a warning
+            return;
+        }
+
+        console.error('GPUDevice lost', info);
+
+        // Everything the renderer built lives on the device that just went away, so there is
+        // nothing to carry over and no attempt to (R6). Whoever is hosting this gets told, and a
+        // reload is the way back.
+        this.onDeviceFailure.send1(ShadeDeviceFailure.device_lost(info.message ?? info.reason ?? ""));
+    }
+
+    #hdr_supported = false;
+
+    /**
+     * What's the peak brightness of the display?
+     * Only valid for HDR.
+     *
+     * @type {number}
+     */
+    #display_peak_brightness_nits = 1000;
+
+    #update_presentation_format() {
+
+        const format8bit = navigator.gpu.getPreferredCanvasFormat();
+
+        const format = this.#hdr_supported ? "rgba16float" : format8bit;
+
+        if (format === this.#presentation_format) {
+            return;
+        }
+
+        this.#presentation_format = format;
+
+        this.#context_needs_update = true;
+    }
+
+    /**
+     * Needs to be a lambda, because we use it as a listener.
+     */
+    #update_hdr_support = () => {
+        const isHDR = window.matchMedia("(dynamic-range: high)").matches;
+
+        const previous_value = this.#hdr_supported;
+
+
+        this.#hdr_supported = isHDR;
+
+        if (isHDR) {
+            // Currently, there is no way to interrogate this from the browser, so going with an assumption
+            this.#display_peak_brightness_nits = 1000;
+        } else {
+            // Assume SDR nits
+            this.#display_peak_brightness_nits = 80;
+        }
+
+        if (isHDR === previous_value) {
+            // no change
+            return;
+        }
+
+        console.log(`HDR support: ${isHDR ? 'enabled' : 'disabled'}`);
+
+        this.#update_presentation_format();
+
+        this.#context_needs_update = true;
+    }
+
+    /**
+     *
+     * @param {GPUCanvasContext} [context] Optional, if not provided - one will be created.
+     * @param {GPUDevice} [device] Optional, if not provided - one will be created.
+     * @param {number} [pixelRatio] Optiona, if not provided - will be taken from browser context
+     */
+    async initialize({
+                         context,
+                         device,
+                         pixelRatio = window.devicePixelRatio,
+                     } = {}) {
+
+        if (!('gpu' in navigator)) {
+            throw new Error('navigator.gpu not available — WebGPU disabled or unsupported');
+        }
+
+        this.#update_presentation_format();
+        this.#update_hdr_support();
+
+        if (context === undefined) {
+            const canvas = document.createElement('canvas');
+            canvas.width = window.innerWidth;
+            canvas.height = window.innerHeight;
+            // Sensible default styling so a freshly-appended canvas covers
+            // the viewport without depending on the host page's CSS reset.
+            // Override `style` after `initialize()` returns if the host
+            // page wants the canvas embedded somewhere else.
+            canvas.style.cssText = 'position:fixed;inset:0;width:100vw;height:100vh;display:block';
+
+            context = canvas.getContext('webgpu');
+
+            if (context === null) {
+                throw new Error('Failed to bind GPUCanvasContext');
+            }
+        }
+
+        if (device === undefined) {
+            // no device present, let's create one
+
+            const gpu = navigator.gpu;
+
+            if (gpu === undefined) {
+                throw ShadeDeviceFailure.webgpu_unavailable();
+            }
+
+            const adapter = await gpu.requestAdapter({
+                powerPreference: "high-performance",
+            });
+
+            if (adapter === null) {
+                throw ShadeDeviceFailure.adapter_unavailable();
+            }
+
+            if (adapter.isFallbackAdapter) {
+                // see https://www.w3.org/TR/webgpu/#dom-gpurequestadapteroptions-forcefallbackadapter
+                // fallback device is typically a software implementation and is going to be slow as sin
+                console.warn('GPU provided a fallback adapter (typically because no other appropriate adapter was available). Fallback adapter is typically a software implementation and will be slow.');
+            }
+
+            // log details of the adapter
+            console.log(`GPU adapter is ${adapter.info.vendor}/${adapter.info.architecture}, device='${adapter.info.device}', description='${adapter.info.description}'`);
+
+            // console.warn(`Buffer size limit: ${number_format_by_thousands(adapter.limits.maxBufferSize)}`);
+            //
+            // console.warn('adapter limits:', adapter.limits);
+
+            const maxStorageBuffersPerShaderStage = adapter.limits.maxStorageBuffersPerShaderStage;
+
+            if (maxStorageBuffersPerShaderStage < 10) {
+                throw ShadeDeviceFailure.below_floor(
+                    `requires at least 10 storage buffers per shader stage, adapter offers ${maxStorageBuffersPerShaderStage}`
+                );
+            }
+
+            const requiredFeatures = [
+                // required for indirect draw that's used extensively in Shade
+                WebGPUExtensionType.IndirectFirstInstance,
+                // required for OIT (might be unavailable)
+                WebGPUExtensionType.Float32Blendable,
+            ];
+
+            // add features if they are available
+            const optional_desired = [
+                // Profiling only, and some browsers withhold it on hardware that is otherwise
+                // fine — so it is taken when offered and the timers go quiet when it is not
+                // (E7, sponsor 2026-08-16). Requiring it would refuse to start on those browsers
+                // for the sake of a feature the game does not need to run.
+                WebGPUExtensionType.TimestampQuery,
+                WebGPUExtensionType.Subgroups,
+                WebGPUExtensionType.TextureFormatsTier1,
+            ];
+
+            // valid required features
+            for (const feature of requiredFeatures) {
+                if (!adapter.features.has(feature)) {
+                    throw ShadeDeviceFailure.below_floor(`adapter does not support required feature '${feature}'`);
+                }
+            }
+
+            for (const feature of optional_desired) {
+                if (adapter.features.has(feature)) {
+                    requiredFeatures.push(feature);
+                }
+            }
+
+
+            device = await adapter.requestDevice({
+                requiredLimits: {
+                    // required for large G-buffers
+                    maxColorAttachmentBytesPerSample: 32,
+
+                    /*
+                     grab the largest buffer limit we can get, default limits are super-low
+                     */
+                    maxBufferSize: adapter.limits.maxBufferSize,
+                    maxStorageBufferBindingSize: adapter.limits.maxStorageBufferBindingSize,
+
+                    maxStorageBuffersPerShaderStage: 10,
+                },
+                requiredFeatures
+            });
+
+            // NOTE: according to spec (as of 2025/09/19) - adapter can only be used to create one device, after which it becomes "consumed"
+            //       see https://www.w3.org/TR/webgpu/#adapters
+
+            // TODO obtained device might be "lost" if something goes wrong, would make sense to check for that
+        }
+
+        device.lost.then(info => {
+            this.#handle_device_lost(info);
+        })
+
+        if (context === undefined) {
+            const canvas = document.createElement('canvas');
+            canvas.width = window.innerWidth;
+            canvas.height = window.innerHeight;
+
+            context = canvas.getContext('webgpu');
+
+            if (context === null) {
+                throw new Error('Failed to bind GPUCanvasContext');
+            }
+        }
+
+        assert.ok(device.features.has("indirect-first-instance"), '"indirect-first-instance" feature needs to be enabled for non-zero firstInstance values to be used.')
+        assert.isInstanceOf(context, GPUCanvasContext, 'context', 'GPUCanvasContext');
+
+        this.context = context;
+        this.device = device;
+
+        this.#pixel_ratio = pixelRatio;
+
+        // clientWidth/clientHeight are 0 for a canvas that is not attached to the DOM,
+        // which is always the case for the renderer-owned canvas created above.
+        // Fall back to the backing-store size so that #configure_context doesn't
+        // overwrite the just-set canvas size with the 1x1 minimum resolution.
+        this.#size.set(
+            context.canvas.clientWidth || context.canvas.width,
+            context.canvas.clientHeight || context.canvas.height
+        );
+
+        this.#update_output_resolution();
+
+        this.#graphics = new GraphicsContext(device);
+
+        const graphics = this.#graphics;
+
+        await graphics.initialize();
+
+
+        this.#scenes = new SceneManager(graphics);
+
+        this.#cameras = new CameraManager(this.device);
+        this.#views = new ViewManager(graphics, this.#cameras, this.#scenes);
+
+        const resolution_internal = this.#internal_resolution.asArray();
+
+        for (let i = 0; i < this.#textures_depth.length; i++) {
+
+            this.#textures_depth[i] = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
+                label: `Depth ${i}`,
+                size: resolution_internal,
+                format: 'depth32float',
+                mipLevelCount: G_BUFFER_MIP_LEVELS,
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC,
+            }));
+        }
+
+
+        const resolution_out = this.#output_resolution.asArray();
+
+        for (let i = 0; i < this.#textures_taa_history.length; i++) {
+
+            this.#textures_taa_history[i] = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
+                label: `Color ${i}`,
+                size: resolution_out,
+                format: "rgba16float",
+                mipLevelCount: 1,
+                // STORAGE_BINDING is required for the NSS postprocess
+                // compute shader to write here. TAA continues to use
+                // RENDER_ATTACHMENT — the flags coexist on the same
+                // texture and the active upscaler picks its preferred
+                // write path each frame.
+                usage: GPUTextureUsage.RENDER_ATTACHMENT
+                    | GPUTextureUsage.TEXTURE_BINDING
+                    | GPUTextureUsage.STORAGE_BINDING
+                    | GPUTextureUsage.COPY_SRC,
+            }));
+        }
+
+        this.#autoexposure = new GPUCameraExposureManager(device);
+        this.#depth_of_field = new DepthOfField(device);
+        this.#depth_of_field_unreal = new DepthOfFieldU(device);
+        this.#motion_blur = new MotionBlur();
+
+        this.#postprocess = new PostProcess(this.#graphics);
+
+        this.#restir_di = new ReSTIRDI(this.#graphics);
+
+        this.#configure_context();
+        this.init_render_targets();
+
+        window.matchMedia("(dynamic-range: high)").addEventListener("change", this.#update_hdr_support);
+
+    }
+
+    /**
+     * Cleanup
+     */
+    destroy() {
+
+        window.matchMedia("(dynamic-range: high)").removeEventListener("change", this.#update_hdr_support);
+    }
+
+
+    /**
+     * @type {RenderTarget}
+     */
+    #vis_render_target;
+
+    init_render_targets() {
+        const vis_rt = new RenderTarget();
+        this.#vis_render_target = vis_rt;
+
+        const textures = this.#graphics.textures;
+
+        // TODO these can be moved to frame graph instead and managed in a transient manner
+        const internal_resolution_array = this.#internal_resolution.asArray();
+
+        vis_rt.color_attachments = [
+            textures.contextFromDescriptor(TextureDescriptor.from({
+                size: internal_resolution_array,
+                format: "r32uint",
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
+            })),
+            textures.contextFromDescriptor(TextureDescriptor.from({
+                size: internal_resolution_array,
+                format: "r32uint",
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
+            })),
+        ];
+
+        vis_rt.depth_attachment = this.#textures_depth[0];
+
+    }
+
+    /**
+     * If set to true, will force {@link #configure_context} on next render
+     * @type {boolean}
+     */
+    #context_needs_update = false;
+
+    #configure_context() {
+        const context = this.context;
+
+        const resolution = this.#output_resolution;
+
+        context.canvas.width = resolution.x;
+        context.canvas.height = resolution.y;
+
+        // canvas must be scaled on-screen differently from resolution to account for pixel ratio
+        const size = this.#size;
+        context.canvas.style.width = `${size.x}px`;
+        context.canvas.style.height = `${size.y}px`;
+
+        const preferred_color_space = 'display-p3';
+
+
+        const config = {
+            device: this.device,
+            format: this.#presentation_format,
+            alphaMode: 'opaque',
+            colorSpace: preferred_color_space,
+            toneMapping: {
+                // see https://www.w3.org/TR/webgpu/#dom-gpucanvastonemappingmode-extended
+                mode: this.#hdr_supported ? "extended" : "standard"
+            }
+        };
+
+
+        try {
+            context.configure(config);
+        } catch (e) {
+            // try fall-back colorspace
+            context.configure({
+                ...config,
+                colorSpace: 'srgb'
+            });
+        }
+
+    }
+
+    #apply_size() {
+        const out_w = this.#output_resolution.x;
+        const out_h = this.#output_resolution.y;
+
+        this.#textures_taa_history.forEach(t => t.resize(out_w, out_h));
+
+
+        this.#context_needs_update = true;
+    }
+
+
+    #update_internal_resolution() {
+        const out_w = this.#output_resolution.x;
+        const out_h = this.#output_resolution.y;
+
+        const dimension_limit = this.device.limits.maxTextureDimension2D;
+
+        const irs = this.#internal_resolution_scale;
+
+        const _iw = clamp(Math.floor(out_w * irs), INTERNAL_RESOLUTION_MIN, dimension_limit);
+        const _ih = clamp(Math.floor(out_h * irs), INTERNAL_RESOLUTION_MIN, dimension_limit);
+
+        this.#internal_resolution.set(_iw, _ih);
+
+        // figure out exact x/y resolution scale
+        const irs_x_inv = out_w / _iw;
+        const irs_y_int = out_h / _ih;
+
+        // we need to make TAA sequence long enough to provide full coverage over output resolution texels
+        const taa_sequence_scale = Math.max(1, irs_x_inv * irs_y_int);
+
+        const upscale_factor = 1 / irs;
+
+        // shrink the sequence as upscale factor increases
+        // we lose crispness of the edges, but we have to trade it to get faster convergence
+        const base_sequence_size = remap(
+            1, 2,
+            16, 4,
+            clamp(upscale_factor, 1, 2),
+        );
+
+        this.#taa.jitter_sequence_size = Math.ceil(base_sequence_size * taa_sequence_scale);
+
+        // ARM's NSS expects `8 * upscale_ratio^2` jitter phases. Apply the
+        // same coverage scaling as TAA so DPR-mismatch resolutions still
+        // get full coverage. Only applied if the NSS instance has been
+        // created — no point spinning it up just to set a number.
+        if (this.#nss !== undefined) {
+            const nss_base = NSS.recommended_jitter_sequence_size(upscale_factor);
+            this.#nss.jitter_sequence_size = Math.ceil(nss_base * taa_sequence_scale);
+        }
+
+        const in_w = this.#internal_resolution.x;
+        const in_h = this.#internal_resolution.y;
+
+        this.#textures_depth.forEach(t => {
+            t.resize(in_w, in_h)
+        });
+
+        this.#vis_render_target.resize(in_w, in_h);
+
+        // resizing destroys BOTH ping-pong depth textures, including the one holding last
+        // frame's depth — disocclusion/SSAO would read a zeroed "previous depth" this frame
+        // and silently corrupt temporal history. The external resize() path resets history
+        // via indicate_view_change(); internal-resolution changes (DRS steps) must too.
+        this.indicate_view_change();
+
+        this.#internal_resolution_needs_update = false;
+    }
+
+    #update_output_resolution() {
+        const size = this.#size;
+        const pixel_ratio = this.#pixel_ratio;
+
+        const dimension_limit = this.device.limits.maxTextureDimension2D;
+
+        // limits are there to prevent crashing out
+        const w = clamp(Math.ceil(size.x * pixel_ratio), 1, dimension_limit);
+        const h = clamp(Math.ceil(size.y * pixel_ratio), 1, dimension_limit);
+
+        this.#output_resolution.set(w, h);
+
+        this.#internal_resolution_needs_update = true;
+    }
+
+    /**
+     * Make sure to resize at the start of the frame to avoid flicker
+     *
+     * @param {number} x
+     * @param {number} y
+     */
+    resize(x, y) {
+        assert.isNonNegativeInteger(x, 'x');
+        assert.isNonNegativeInteger(y, 'y');
+
+        const size = this.#size;
+
+        if (size.x === x && size.y === y) {
+            // no change
+            return;
+        }
+
+        size.set(x, y);
+
+        this.#update_resolution();
+    }
+
+    /**
+     * Does not check for changes, so make sure to call this sparingly
+     */
+    #update_resolution() {
+
+        this.#update_output_resolution();
+
+        if (this.#internal_resolution_needs_update) {
+            this.#update_internal_resolution();
+        }
+
+        this.#apply_size();
+
+        // drop history buffers to prevent artifacts
+        this.indicate_view_change();
+    }
+
+    /**
+     * Bring the canvas context up to date with the size the renderer is drawing at.
+     *
+     * **Only {@link render} calls this, and that is the point.** Configuring a context resizes the
+     * canvas and invalidates the texture it last handed out, so it has to happen before the frame
+     * asks for one — and a frame going somewhere other than the canvas must not do it at all, or
+     * every offscreen picture would resize the page's canvas to its own size and back.
+     */
+    #ensure_context_configured() {
+        this.#update_resolution_if_needed();
+
+        if (this.#context_needs_update) {
+            this.#configure_context();
+            this.#context_needs_update = false;
+        }
+    }
+
+    #update_resolution_if_needed() {
+        if (this.#internal_resolution_needs_update) {
+            this.#update_internal_resolution();
+        }
+    }
+
+    #begin_frame() {
+
+        this.#update_resolution_if_needed();
+
+        this.#graphics.update();
+
+        // Virtual texture maintenance: apply arrived pages (budgeted
+        // uploads), flush page-table dirty rects and stack info, issue
+        // streaming loads. Queue-ordered before this frame's submits, so
+        // the material pass samples a consistent table+cache snapshot.
+        if (this.feature_virtual_textures) {
+            this.#graphics.virtual_textures.update();
+        }
+
+        // cycle depth attachment
+        this.#vis_render_target.depth_attachment = this.texture_depth_current;
+        this.#postprocess.update(this.#frame_count);
+
+        // Advance whichever upscaler we're going to ask for jitter on this
+        // frame. Both share the same Halton(2, 3) sequence; we only tick
+        // the active one to avoid spinning up NSS just to drive a counter.
+        if (this.upscale_type === ShadeUpscalerType.NSS) {
+            const nss = this.nss;
+            nss.frame_count = this.#frame_count;
+            nss.frame_index = this.#frame_count;
+        } else {
+            this.#taa.frame_index = this.#frame_count;
+        }
+    }
+
+    #end_frame() {
+        this.#frame_count++;
+
+        // dispatch event
+        this.onFrameFinished.send1(this.#frame_count);
+    }
+
+    /**
+     * @type {AccumulatingPathTracer}
+     */
+    #path_tracer;
+
+    get path_tracer() {
+        if (this.#path_tracer === undefined) {
+            this.#path_tracer = new AccumulatingPathTracer(this.#graphics);
+        }
+
+        return this.#path_tracer;
+    }
+
+    /**
+     * Draw a frame onto the canvas this renderer is bound to.
+     *
+     * The canvas is one target among others: this is {@link render_to_target} with the canvas's
+     * current texture as the target, and nothing else.
+     *
+     * @param {PerspectiveCamera} camera
+     * @param {Scene} scene
+     * @param {number} [time_delta_seconds]
+     * @returns {boolean} whether frame was rendered, will return false if previous frame hasn't finished yet
+     */
+    render(
+        camera,
+        scene,
+        time_delta_seconds = 0.01666
+    ) {
+        if (this.#device_lost) {
+            // device is lost, can't render — and asking the context for a texture would throw
+            return false;
+        }
+
+        this.#ensure_context_configured();
+
+        const canvas_texture = this.context.getCurrentTexture();
+
+        return this.render_to_target(
+            camera,
+            scene,
+            time_delta_seconds,
+            GPUTextureContext.fromTexture(canvas_texture, this.device)
+        );
+    }
+
+    /**
+     * Draw a frame into a texture of the caller's choosing.
+     *
+     * **The target says where the picture goes, not how big it is.** Everything the frame is built
+     * out of — the G-buffer, the visibility buffer, the depth ping-pong, the temporal history — is
+     * sized from {@link output_resolution}, so a target has to be that size; a caller wanting a
+     * different one calls {@link resize} first and puts the size back afterwards. Rendering into a
+     * texture the caller owns is what makes a frame readable: a canvas texture is configured by the
+     * presentation path and cannot carry `COPY_SRC`, and one of these can.
+     *
+     * @param {PerspectiveCamera} camera
+     * @param {Scene} scene
+     * @param {number} time_delta_seconds
+     * @param {GPUTextureContext} target must match {@link output_resolution}
+     * @returns {boolean} whether frame was rendered, will return false if previous frame hasn't finished yet
+     */
+    render_to_target(
+        camera,
+        scene,
+        time_delta_seconds,
+        target
+    ) {
+        assert.defined(target, 'target');
+        assert.equal(target.isGPUTextureContext, true, 'target.isGPUTextureContext !== true');
+
+        if (this.#device_lost) {
+            // device is lost, can't render
+            return false;
+        }
+
+        this.#begin_frame();
+
+
+        if (this.indirect_lighting_mode === ShadeIndirectLightingMode.LPV) {
+            this.update_lpv(scene);
+        }
+
+        const view = View.from(camera, scene);
+        view.label = "Main View";
+        const view_ctx = this.#views.obtain(view);
+
+        const graphics = this.#graphics;
+
+        // Shadow allocation + per-light shadow_id assignment happens inside
+        // GPULightCollection.update (which view_ctx.update will trigger via
+        // GPUSceneContext.update below), so by the time we reach select_for_draw the
+        // light records on the GPU already carry their up-to-date shadow_id. Forward the
+        // feature flag so process_lights inside lights.update can evict everything when
+        // the renderer has shadows turned off — keeps CASTS_SHADOW_BIT cleared on every
+        // light record without further plumbing.
+        const sm = view_ctx.scene.lights.shadow_context;
+        sm.enabled = this.#feature_shadows_enabled;
+        // Which point-light shadow generator to use this frame; a flip triggers a rebuild of
+        // existing point maps inside process_lights (run via view_ctx.update above/below).
+        sm.use_tetrahedron_point_shadows = this.feature_tetrahedron_point_shadows;
+
+        const taa = this.#taa;
+
+        // Whichever upscaler is going to consume the temporal sequence
+        // also has to dictate the jitter applied to the camera projection.
+        // Both share Halton(2, 3); they just drive different jitter
+        // sequence sizes via #update_internal_resolution.
+        const jitter_source = this.upscale_type === ShadeUpscalerType.NSS
+            ? this.nss
+            : taa;
+
+        const resolution_internal = this.#internal_resolution;
+        {
+            const jitter_x = jitter_source.Jitter[0];
+            const jitter_y = jitter_source.Jitter[1];
+
+            view_ctx.setJitter(jitter_x, jitter_y);
+            view_ctx.setViewportSize(resolution_internal.x, resolution_internal.y);
+            view_ctx.setUpscaleRatio(
+                this.#output_resolution.x / resolution_internal.x,
+                this.#output_resolution.y / resolution_internal.y
+            );
+            // 2x offsets because the offsets are in NDC (-1, 1)
+            view_ctx.camera.setViewportOffset(
+                (2 * jitter_x) / resolution_internal.x,
+                (2 * jitter_y) / resolution_internal.y
+            );
+
+        }
+
+        view_ctx.update(graphics);
+
+        const command_ctx = ShadeGPUCommandContext.create(
+            graphics,
+            "Renderer/main-0"
+        );
+
+        if (this.#debug_frame_count > 0) {
+            this.#debug_frame_count--;
+
+            const current_frame = this.#frame_count;
+
+            command_ctx.enable_debug_timers((table) => {
+                this.onFrameDebug.send2(current_frame, table);
+            });
+        }
+
+        // Per-frame animation tick — runs before shadow allocation so
+        // animated transforms (joint poses, mesh.global from animated
+        // parents) are in the scene database by the time shadow
+        // culling samples it. No-op when nothing's registered.
+        view_ctx.scene.tick(command_ctx, time_delta_seconds);
+
+        const viz_rt = this.#vis_render_target;
+
+        // prepare shadows (process_lights already ran inside lights.update via view_ctx.update,
+        // so the GPU light records already carry their up-to-date shadow_id)
+        if (this.#feature_shadows_enabled) {
+            // Two-stage: (1) score+select which maps refresh this frame and publish their metadata,
+            // (2) rasterize the selected maps. The context internally dispatches to the right
+            // raster path per light type — directional/spot go direct, point lights do a cube
+            // pass plus octahedral remap — so we don't have to juggle job arrays out here.
+            // draw() also writes per-shadow records into the scene's GPU light database
+            // (shadow_point/shadow_spot/shadow_directional tables) via its owner reference.
+            sm.select_for_draw(camera, view_ctx.scene, view_ctx.frame_index, view_ctx.resolution);
+            sm.draw(command_ctx);
+        }
+
+
+        const graph = new FrameGraph("Shading");
+
+        /*
+         The view is updated and nothing has been rasterized, so an extension here is doing the
+         per-frame compute that later phases depend on. There are no records yet — the frame has
+         built nothing to hand out.
+        */
+        const frame = new FrameContext(graph, view_ctx);
+
+        frame.phase = FramePhase.FrameStart;
+
+        this.#extensions.run(frame);
+
+        // build main view rasterization job
+        const raster_main = new RasterizationJob();
+        raster_main.view_ctx = view_ctx;
+        raster_main.render_target = viz_rt;
+        raster_main.opaque_pass = viz_rasterization_opaque_pass_descriptor;
+        raster_main.alpha_tested_pass = viz_rasterization_alpha_tested_pass_descriptor;
+
+        const gr_render_buckets = graph_rasterize_scene({
+            job: raster_main,
+            graph,
+            limits: graphics.collection_limits,
+        });
+
+        // `let` rather than `const` because an extension at `AfterGBuffer` may publish replacements
+        let gr_viz_buffer_triangle = graph_import_texture(graph, this.#vis_render_target.color_attachments[0], "viz_triangle");
+        let gr_viz_buffer_mesh = graph_import_texture(graph, this.#vis_render_target.color_attachments[1], "viz_mesh");
+
+        // Virtual texture feedback: derive per-pixel page usage from the viz
+        // buffer (no extra geometry pass) into a unique-request hash set and
+        // kick its async readback. No-op unless VT stacks are registered.
+        if (this.feature_virtual_textures) {
+            graphics.virtual_textures.graph_feedback({
+                graph,
+                view: view_ctx,
+                texture_viz_mesh: gr_viz_buffer_mesh,
+                texture_viz_triangle: gr_viz_buffer_triangle,
+                material_metadata_buffer: graphics.materials.metadata_table.buffer,
+            });
+        }
+
+        // run materials
+        const mat_g = graphics.materials.graph_viz_render({
+            graph,
+            view: view_ctx,
+            texture_viz_mesh: gr_viz_buffer_mesh,
+            texture_viz_triangle: gr_viz_buffer_triangle,
+        });
+
+        // update texture references
+        // `let` rather than `const` because a pass injected at `AfterGBuffer` may replace any of
+        // them; see the read-back below.
+        let gr_texture_pbr = mat_g.g_pbr;
+        let gr_texture_normal = mat_g.g_normal;
+        let gr_texture_material_albedo_ao = mat_g.g_albedo;
+        let gr_texture_material_emissive = mat_g.g_emissive;
+
+        // do mips for G-buffer
+        // mipmap_nearest(command_ctx, this.texture_depth_current);
+        // this.gBuffer.mipmap(command_ctx);
+
+        // Update lights position
+        command_ctx.pushDebugGroup("Shade");
+
+        const resolution = resolution_internal.asArray();
+
+        const scene_ctx = view_ctx.scene;
+        const lights = scene_ctx.lights;
+
+
+        const gr_texture_canvas = graph_import_texture(graph, target, "canvas");
+        let gr_texture_depth_current = graph_import_texture(graph, this.texture_depth_current, "depth");
+        const gr_buffer_camera_current = graph_import_buffer(graph, view_ctx.camera.gpu_buffer, "camera/current");
+        const gr_buffer_camera_previous = graph_import_buffer(graph, view_ctx.gpu_previous_camera_state.gpu_buffer, "camera/previous");
+        const gr_texture_hzb = graph_import_texture(graph, view_ctx.hierarchical_z_buffer.texture, "HZB");
+        const gr_texture_environment = graph_import_texture(graph, view_ctx.scene.lights.environment);
+
+        const taa_history_0 = this.#get_texture_taa_history(0);
+        const taa_history_1 = this.#get_texture_taa_history(-1);
+
+        const gr_texture_taa_history = graph_import_texture(graph, taa_history_0, "taa history");
+        const gr_texture_taa_out = graph_import_texture(graph, taa_history_1, "taa out");
+        let gr_texture_depth_previous = graph_import_texture(graph, this.texture_depth_previous, "depth previous");
+
+        const gr_shadowmap_atlas = graph_import_texture(graph, sm.texture);
+
+        // The frame's surface handles exist now, so this is where the records that carry them are
+        // published. There is no colour yet, which is what makes this the phase for G-buffer work.
+        frame.phase = FramePhase.AfterGBuffer;
+
+        const record_gbuffer = frame.create(GBufferTextures);
+        const record_view_textures = frame.create(ViewTextures);
+
+        record_gbuffer.albedo = gr_texture_material_albedo_ao;
+        record_gbuffer.normal = gr_texture_normal;
+        record_gbuffer.pbr = gr_texture_pbr;
+        record_gbuffer.emissive = gr_texture_material_emissive;
+
+        record_view_textures.depth = gr_texture_depth_current;
+        record_view_textures.depth_previous = gr_texture_depth_previous;
+        record_view_textures.visibility_mesh = gr_viz_buffer_mesh;
+        record_view_textures.visibility_triangle = gr_viz_buffer_triangle;
+
+        this.#extensions.run(frame);
+
+        /*
+         `GBufferTextures` is in/out at this phase, and frozen after it. An extension that wants to
+         *change* surface properties — decals are the reason this exists — cannot blend into these
+         targets: two of the four are integer formats, and one texture cannot be a render attachment
+         and a sampled source in the same pass. So it reads them, writes replacements, and publishes
+         the new handles. Everything downstream carries what it left.
+
+         Writing the originals in place would work by accident rather than by contract: a written
+         handle is a *renamed* clone of the same physical resource, so the change would land in the
+         texture the shading pass reads only because the graph happens to execute in insertion
+         order, with no dependency edge saying so. Threading the handles makes the edge real.
+        */
+        gr_texture_pbr = record_gbuffer.pbr;
+        gr_texture_normal = record_gbuffer.normal;
+        gr_texture_material_albedo_ao = record_gbuffer.albedo;
+        gr_texture_material_emissive = record_gbuffer.emissive;
+
+        gr_texture_depth_current = record_view_textures.depth;
+        gr_texture_depth_previous = record_view_textures.depth_previous;
+        gr_viz_buffer_mesh = record_view_textures.visibility_mesh;
+        gr_viz_buffer_triangle = record_view_textures.visibility_triangle;
+
+        // Velocity pass with three branches: rotation-reprojection
+        // background, rigid per-object foreground (mesh.global delta),
+        // and skinned per-vertex foreground (barycentric interpolation
+        // of the triangle's mesh-local `position_prev` written by
+        // skinning into the side-buffer the skinning context owns).
+        // Per-vertex limb deformation lands in the final pixel-space
+        // velocity, so TAA reads correct history for character animation.
+        const gr_scene_database_for_velocity = graph_import_buffer(
+            graph, scene_ctx.scene_database_buffer, "scene_database/velocity"
+        );
+        const gr_meshlet_metadata_for_velocity = graph_import_buffer(
+            graph, scene_ctx.geometries.meshlets.buffer_metadata, "meshlet_metadata/velocity"
+        );
+        const gr_meshlet_data_for_velocity = graph_import_buffer(
+            graph, scene_ctx.geometries.meshlets.buffer_data, "meshlet_data/velocity"
+        );
+        // Skinning side-buffers — both null when no SkinnedMesh has
+        // been registered. The velocity shader still references these
+        // bindings (the dormant per-vertex branch), so the bind group
+        // must supply *something*; use the scene_database buffer as a
+        // placeholder when skinning is inactive. The shader is told via
+        // `skinning_active` whether the bindings are real — when false
+        // it never reads them and forces the rigid path, so the
+        // placeholder is never sampled. (Binding the placeholder
+        // without that guard was the source of phantom velocity on
+        // static meshes: `prev_position_offsets[meshlet_id]` read an
+        // unrelated scene_database word, and any non-0xFFFFFFFF value
+        // sent a static triangle down the skinned branch.)
+        const skinning_ctx = scene_ctx.skinning;
+        const skinning_active = skinning_ctx.prev_position_offsets_buffer !== null
+            && skinning_ctx.prev_positions_buffer !== null;
+        const gr_prev_position_offsets = graph_import_buffer(
+            graph,
+            skinning_ctx.prev_position_offsets_buffer ?? scene_ctx.scene_database_buffer,
+            "prev_position_offsets/velocity",
+        );
+        const gr_prev_positions = graph_import_buffer(
+            graph,
+            skinning_ctx.prev_positions_buffer ?? scene_ctx.scene_database_buffer,
+            "prev_positions/velocity",
+        );
+
+        let gr_velocity = graph_add_per_object_velocity({
+            graph,
+            texture_depth: gr_texture_depth_current,
+            texture_viz_mesh: gr_viz_buffer_mesh,
+            texture_viz_triangle: gr_viz_buffer_triangle,
+            buffer_scene_database: gr_scene_database_for_velocity,
+            buffer_meshlet_metadata: gr_meshlet_metadata_for_velocity,
+            buffer_meshlet_data: gr_meshlet_data_for_velocity,
+            buffer_prev_position_offsets: gr_prev_position_offsets,
+            buffer_prev_positions: gr_prev_positions,
+            skinning_active,
+            resolution,
+            view: view_ctx,
+            enable_mipmap: true
+        });
+
+        // gr_velocity = graph_mipmap_nearest(graph, gr_velocity, G_BUFFER_MIP_LEVELS);
+
+        let [gr_occlusion_clip] = graph_image_pass({
+            graph,
+            shader: shader_depth_occlusion_clip,
+            output_resolution: view_ctx.resolution,
+            // mipmaps are going to be necessary for half-resolution post-process passes
+            output_mipmaps: true,
+            inputs: {
+                camera_current: gr_buffer_camera_current,
+                camera_previous: gr_buffer_camera_previous,
+                DepthBuffer: gr_texture_depth_current,
+                PrevDepthBuffer: gr_texture_depth_previous,
+                VelocityBuffer: gr_velocity
+            }
+        });
+
+        const light_clusters = graph_build_light_clusters({
+            graph,
+            lights: lights,
+            camera: view_ctx.camera,
+            hzb: gr_texture_hzb,
+            resolution: view_ctx.resolution,
+        });
+
+        // Build the view's volumetric fog LUTs (participating media -> per-froxel lighting ->
+        // ray-marched integration). Needs the light clusters and shadow atlas. Built every frame so
+        // the transparency (OIT) pass always has a valid LUT to sample — an empty scene integrates
+        // to a no-op (transmittance 1, in-scatter 0). The opaque composite below is still skipped
+        // when the scene has no fog.
+        const has_volumetrics = view_ctx.scene.volumetrics.source.volumes.length > 0;
+
+        const volumetrics = view_ctx.volumetrics.graph_update({
+            graph,
+            light_cluster_data: light_clusters.data,
+            light_cluster_lookup: light_clusters.lookup,
+            light_cluster_parameters: light_clusters.parameters,
+            shadowmap_atlas: gr_shadowmap_atlas,
+        });
+
+        /**
+         *
+         * @type {number}
+         */
+        let current_color_out = -1;
+
+        // ReSTIR DI — stochastic direct lighting of local (point+spot) lights.
+        // When enabled, resolve per-pixel point+spot radiance and shade with the
+        // ReSTIR deferred variant (no brute-force cluster loop). The variant is a
+        // separate compiled shader, selected here at the JS level rather than via
+        // a runtime branch inside the shader.
+        let deferred_shader = shader_deferred_main;
+
+        const deferred_inputs = {
+            gBufferDepth: gr_texture_depth_current,
+            gBufferPBR: gr_texture_pbr,
+            gBufferNormal: gr_texture_normal,
+            gBufferAlbedo: gr_texture_material_albedo_ao,
+            gBufferEmissive: gr_texture_material_emissive,
+
+            //
+            light_data: lights.buffer_data,
+            tEnvironment: gr_texture_environment,
+
+            // light clusters
+            cluster_parameters: light_clusters.parameters,
+            cluster_lookup: light_clusters.lookup,
+            cluster_data: light_clusters.data,
+
+            // shadows
+            shadowmapAtlas: gr_shadowmap_atlas,
+
+            //
+            camera: view_ctx.camera.buffer,
+            view: view_ctx.uniform_buffer.buffer,
+        };
+
+        if (this.feature_restir_di_enabled) {
+            deferred_shader = shader_deferred_main_restir;
+
+            deferred_inputs.tRestirRadiance = this.#restir_di.execute({
+                graph,
+                view: view_ctx,
+                depth: gr_texture_depth_current,
+                pbr: gr_texture_pbr,
+                normal: gr_texture_normal,
+                albedo: gr_texture_material_albedo_ao,
+                emissive: gr_texture_material_emissive,
+                velocity: gr_velocity,
+                occlusion_clip: gr_occlusion_clip,
+                hzb: gr_texture_hzb,
+                cluster_parameters: light_clusters.parameters,
+                cluster_lookup: light_clusters.lookup,
+                cluster_data: light_clusters.data,
+            });
+        }
+
+        // Main shading pass
+        [current_color_out] = graph_image_pass({
+            graph,
+            shader: deferred_shader,
+            input_depth: gr_texture_depth_current,
+            inputs: deferred_inputs,
+            output_resolution: view_ctx.resolution,
+        });
+
+
+        let bent_normals = -1;
+
+        if (this.feature_ssao_enabled) {
+
+            const ssao = this.#postprocess.ssao.graph_pass({
+                graph: graph,
+                frame_index: this.#frame_count,
+                input_depth: gr_texture_depth_current,
+                input_color: current_color_out,
+                input_depth_previous: gr_texture_depth_previous,
+                input_velocity: gr_velocity,
+                input_normal: gr_texture_normal,
+                input_occlusion: gr_occlusion_clip,
+                // NOTE: AO is blended into the G-buffer
+                output: gr_texture_material_albedo_ao,
+                camera: gr_buffer_camera_current,
+                resolution: resolution,
+            });
+
+            gr_texture_material_albedo_ao = ssao.occlusion;
+            bent_normals = ssao.bent_normals;
+
+        } else {
+
+            // default to shading normals
+            bent_normals = gr_texture_normal;
+
+        }
+
+
+        // Shade background
+        [current_color_out] = graph_image_pass({
+            graph,
+            shader: shader_background,
+            inputs: {
+                camera: view_ctx.camera.buffer,
+                view: view_ctx.uniform_buffer.buffer,
+                tEnvironment: gr_texture_environment,
+            },
+            input_depth: gr_texture_depth_current,
+            load_op: "load",
+            output: [current_color_out],
+        });
+
+        {
+            // Fused brick4 path: skip the intermediate diffuse/specular targets and the
+            // separate resolve, doing it all in a single shader. SSR isn't compatible
+            // since it consumes the standalone specular target.
+            const use_fused_indirect = this.fused_indirect
+                && this.indirect_lighting_mode === ShadeIndirectLightingMode.Brick4
+                && !this.feature_ssr_enabled;
+
+            if (use_fused_indirect) {
+
+                [current_color_out] = graph_image_pass({
+                    graph,
+                    shader: shader_brick4_indirect_lighting,
+                    output: [current_color_out],
+                    input_depth: gr_texture_depth_current,
+                    load_op: "load",
+                    inputs: {
+                        tDepth: gr_texture_depth_current,
+                        tGBufferNormals: gr_texture_normal,
+                        tBentNormals: bent_normals,
+                        tGBufferAlbedo: gr_texture_material_albedo_ao,
+                        tGBufferPBR: gr_texture_pbr,
+                        tSTBN_vec2: STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2,
+                        view: view_ctx.uniform_buffer.buffer,
+                        camera: gr_buffer_camera_current,
+                        //
+                        brick4: scene_ctx.volumetric_light_map.buffer,
+                        tSplitSum: STATIC_GRAPHICS_ENGINE_ASSETS.split_sum,
+                    },
+                });
+
+            } else {
+
+                const { indirect_specular, indirect_diffuse } = this.#graph_indirect_lighting({
+                    graph,
+                    view_ctx,
+                    scene_ctx,
+                    bent_normals,
+                    current_color_out,
+                    //
+                    gr_texture_depth_current,
+                    gr_texture_hzb,
+                    gr_texture_material_albedo_ao,
+                    gr_texture_pbr,
+                    gr_texture_normal,
+                    gr_texture_environment,
+                    gr_velocity,
+                    gr_occlusion_clip,
+                    gr_buffer_camera_current,
+                    gr_buffer_camera_previous,
+                    resolution,
+                });
+
+                // resolve indirect lighting
+                [current_color_out] = graph_image_pass({
+                    graph,
+                    shader: shader_resolve_indirect_lighting,
+                    output: [current_color_out],
+                    input_depth: gr_texture_depth_current,
+                    load_op: "load",
+                    inputs: {
+                        tIndirectDiffuse: indirect_diffuse,
+                        tIndirectSpecular: indirect_specular,
+                        //
+                        tGBufferNormals: gr_texture_normal,
+                        tBentNormals: bent_normals,
+                        tGBufferAlbedo: gr_texture_material_albedo_ao,
+                        tGBufferPBR: gr_texture_pbr,
+                        tDepth: gr_texture_depth_current,
+                        //
+                        camera: gr_buffer_camera_current,
+                        //
+                        tSplitSum: STATIC_GRAPHICS_ENGINE_ASSETS.split_sum,
+                    },
+                });
+
+            }
+
+            // current_color_out = indirect_diffuse
+            // current_color_out = indirect_specular
+
+        }
+
+        // current_color_out = graph_decode_rgbe9995_to_rgb16float({
+        //     graph,
+        //     input:indirect_diffuse_near_field,
+        //     resolution: view_ctx.resolution,
+        // });
+        //
+        // const [norm] = graph_image_pass({
+        //     shader: shader_decode_octahedral_normal,
+        //     inputs:{
+        //         tInput: bent_normals,
+        //     },
+        //     graph,
+        //     output_resolution: view_ctx.resolution,
+        // });
+        //
+        // [current_color_out] = graph_image_pass({
+        //     graph,
+        //     shader: shader_draw_normals,
+        //     inputs:{
+        //         tInput: norm,
+        //     },
+        //     output_resolution: view_ctx.resolution,
+        // });
+
+        // Composite volumetric fog over the finalized opaque + background + indirect colour.
+        // A dedicated pass (not inline in the shading shaders) because indirect lighting is added
+        // in a separate additively-blended pass, so the full surface radiance only exists here.
+        // Runs before transparency (transparent surfaces blend over the fog) and before the main
+        // TAA (which then smooths the fog's per-pixel sampling noise).
+        if (has_volumetrics) {
+            [current_color_out] = graph_image_pass({
+                graph,
+                shader: shader_composite_volumetrics,
+                output_resolution: view_ctx.resolution,
+                inputs: {
+                    tColor: current_color_out,
+                    gBufferDepth: gr_texture_depth_current,
+                    tVolumetrics: volumetrics.resolved,
+                    tSTBN_vec3: STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec3,
+                    volumetrics_metadata: volumetrics.metadata,
+                    camera: view_ctx.camera.buffer,
+                    view: view_ctx.uniform_buffer.buffer,
+                },
+            });
+        }
+
+        /*
+         The frame has a colour for the first time, so this is where `SceneColor` is published. It is
+         republished before each later phase because the built-in passes between them replace it —
+         the record names which handle currently *means* the scene colour, and the graph already
+         holds the dependency edge underneath.
+        */
+        frame.phase = FramePhase.AfterLighting;
+
+        const record_scene_color = frame.create(SceneColor);
+
+        record_scene_color.color = current_color_out;
+
+        this.#extensions.run(frame);
+
+        current_color_out = record_scene_color.color;
+        gr_texture_depth_current = record_view_textures.depth;
+
+        if (this.#feature_enabled_transparencies) {
+            // do transparent alpha pass
+            current_color_out = graph_rasterize_meshes_transparent_oit({
+                graph,
+                buckets: gr_render_buckets,
+                view_ctx,
+                viewport: [0, 0, resolution_internal.x, resolution_internal.y],
+                color_texture: current_color_out,
+                depth_texture: gr_texture_depth_current,
+
+                limits: this.graphics.collection_limits,
+
+                light_cluster_data: light_clusters.data,
+                light_cluster_lookup: light_clusters.lookup,
+                light_cluster_parameters: light_clusters.parameters,
+
+                shadowmap_atlas: gr_shadowmap_atlas,
+
+                volumetrics_lut: volumetrics.resolved,
+                volumetrics_metadata: volumetrics.metadata,
+
+                indirect_lighting_mode: this.indirect_lighting_mode,
+            });
+        }
+
+        frame.phase = FramePhase.AfterTransparency;
+
+        record_scene_color.color = current_color_out;
+
+        this.#extensions.run(frame);
+
+        current_color_out = record_scene_color.color;
+        gr_texture_depth_current = record_view_textures.depth;
+
+        // current_color_out = gr_texture_material_albedo_ao;
+
+        // current_color_out = this.path_tracer.render({
+        //     graph,
+        //     view: view_ctx
+        // });
+
+        // Debug override: replace the post-shading color with a
+        // visualization of the velocity buffer via shader_debug_velocity.
+        // Direction is encoded as hue (red = +X, cyan = -X, etc.) and
+        // magnitude as brightness; the AO channel of the albedo+AO
+        // G-buffer modulates the static base so geometry shape is
+        // still readable where motion is zero or near-zero. Done
+        // BEFORE TAA so the chain stays well-formed; TAA blending
+        // the debug view is meaningless, but it's debug.
+        if (this.feature_velocity_debug_view) {
+            [current_color_out] = graph_image_pass({
+                graph,
+                shader: shader_debug_velocity,
+                inputs: {
+                    tInput: gr_velocity,
+                    tAlbedoAO: gr_texture_material_albedo_ao,
+                },
+                output_resolution: resolution_internal.asArray(),
+            });
+        }
+
+        if (this.feature_taa_enabled) {
+
+            if (this.upscale_type === ShadeUpscalerType.NSS) {
+                current_color_out = this.nss.graph_pass({
+                    graph,
+                    texture_color_current: current_color_out,
+                    texture_depth_current: gr_texture_depth_current,
+                    texture_velocity: gr_velocity,
+                    texture_disocclusion_confidence: gr_occlusion_clip,
+                    texture_color_history: gr_texture_taa_history,
+                    texture_output: gr_texture_taa_out,
+                    render_resolution: resolution_internal.asArray(),
+                    output_resolution: this.#output_resolution.asArray(),
+                });
+            } else {
+                current_color_out = taa.graph_pass({
+                    graph,
+                    texture_output: gr_texture_taa_out,
+                    texture_color_current: current_color_out,
+                    texture_color_history: gr_texture_taa_history,
+                    texture_velocity: gr_velocity,
+                    texture_occlusion: gr_occlusion_clip,
+                    camera_current: gr_buffer_camera_current,
+                    camera_previous: gr_buffer_camera_previous,
+                });
+            }
+        }
+
+        // Bokeh depth of field on the resolved HDR colour. Runs after
+        // TAA (blurs a clean, converged image — TAA's neighbourhood
+        // clamp would otherwise fight the defocus) and before motion
+        // blur / bloom, so out-of-focus highlights bloom and the bokeh
+        // carries through the rest of the post chain. Perspective-only:
+        // the thin-lens CoC has no meaning under orthographic.
+        if (this.feature_dof_enabled && camera.isPerspectiveCamera === true) {
+            // Both implementations share the same render() signature, so the
+            // call site is identical — only the subsystem differs.
+            const dof = this.dof_algorithm === "unreal"
+                ? this.#depth_of_field_unreal
+                : this.#depth_of_field;
+
+            current_color_out = dof.render({
+                graph,
+                input_color: current_color_out,
+                depth: gr_texture_depth_current,
+                camera,
+                camera_buffer: view_ctx.camera.buffer,
+                resolution: this.#output_resolution.asArray(),
+            });
+        }
+
+        // Jimenez 2014 motion blur runs on the resolved-but-not-
+        // sharpened HDR colour. TAA has already converged the
+        // jittered samples; sharpening, bloom, and tonemap operate
+        // on the blurred output after this. Skipped when the toggle
+        // is off so the rest of the chain stays bit-identical.
+        if (this.feature_motion_blur_enabled) {
+            current_color_out = this.#motion_blur.render({
+                graph,
+                input_color: current_color_out,
+                velocity: gr_velocity,
+                depth: gr_texture_depth_current,
+                resolution: this.#output_resolution.asArray(),
+            });
+        }
+
+        // TODO if TAA is disabled, and internal resolution is < 100% - we need to do upscale
+
+        if (this.feature_sharpening_enabled) {
+            [current_color_out] = graph_image_pass({
+                graph,
+                shader: shader_ffx_rcas,
+                output_resolution: this.#output_resolution.asArray(),
+                inputs: {
+                    tInput: current_color_out,
+                    uSharpness: {
+                        value: 0.8
+                    }
+                }
+            });
+        }
+
+        let exposure = -1;
+
+        if (this.feature_bloom_enabled || this.feature_automatic_exposure_enabled) {
+            const bloom = graph_postprocess_bloom({
+                graph,
+                input: current_color_out,
+                resolution: this.#output_resolution.asArray(),
+            });
+
+            if (this.feature_bloom_enabled) {
+                current_color_out = bloom.composited;
+            }
+
+            if (this.feature_automatic_exposure_enabled) {
+                // TODO force time_delta_second to a very high value on view transition
+
+                exposure = this.#autoexposure.update({
+                    graph,
+                    input_color: bloom.downsampled,
+                    time_delta_seconds,
+                });
+            }
+
+        }
+
+
+        if (this.feature_automatic_exposure_enabled === false) {
+            exposure = this.#autoexposure.unadapted({ graph });
+        }
+
+
+        // current_color_out = graph_draw_texture_as_rgba({
+        //     graph,
+        //     source: gr_shadowmap_atlas,
+        //     resolution: this.#output_resolution.asArray(),
+        // });
+
+        /*
+         Past the upscale: the colour published here is output-sized while the G-buffer beside it is
+         still internal-sized, and `FrameContext.resolution` reads whichever of them the phase draws
+         into rather than a number anybody wrote down. With `feature_taa_enabled === false` no
+         upscale happened and the two agree — which a constant could not express.
+        */
+        frame.phase = FramePhase.BeforePresent;
+
+        record_scene_color.color = current_color_out;
+
+        this.#extensions.run(frame);
+
+        current_color_out = record_scene_color.color;
+
+        if (this.#hdr_supported) {
+            [current_color_out] = graph_image_pass({
+                graph,
+                shader: shader_tonemap_HDR,
+                inputs: {
+                    input_color: current_color_out,
+                    settings: {
+                        peak_nits: this.#display_peak_brightness_nits,
+                        paper_white_nits: 100, // SDR spec is 80, but 100 has been accepted as de-facto in recent years
+                    },
+                    exposure
+                },
+                output: [gr_texture_canvas]
+            });
+        } else {
+            [current_color_out] = graph_image_pass({
+                graph,
+                shader: shader_tonemap_LDR,
+                inputs: {
+                    input_color: current_color_out,
+                    exposure
+                },
+                output: [gr_texture_canvas]
+            });
+        }
+
+        /*
+         The canvas is written here and cannot be read: a texture may not be a render attachment and
+         a sampled source in the same pass. So what this phase carries is a `PresentTarget` with one
+         field and no colour to be tempted by — an extension that wants the finished image as input
+         finds that out at `get` time and belongs at `BeforePresent`.
+        */
+        frame.phase = FramePhase.Overlay;
+
+        frame.create(PresentTarget).canvas = current_color_out;
+
+        this.#extensions.run(frame);
+
+        frame.close();
+
+        command_ctx.encodeGraph(graph);
+
+        command_ctx.popDebugGroup();
+
+        view_ctx.finish_frame(command_ctx);
+
+        command_ctx.finish();
+
+        this.#end_frame();
+
+        return true;
+    }
+}