@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/scene.js

@@ -0,0 +1,2005 @@
+import { YaliError } from '@yali-engine/core';
+import { isBlendClass, isSkinnedClass, MAX_LODS, SKIN_STREAM_BYTES } from "./meshes.js";
+import { sceneCull, sceneDraw, sceneShadow } from "./shaders.gen.js";
+import { CASCADE_UNIFORM_BYTES, cascadeCullPlanes, fitCascades, MAX_CASCADES, SHADOW_FLOATS, SunShadows } from "./shadows.js";
+import { CULL_CASCADES, CulledDraws } from "./culled-draws.js";
+import { StagingRing } from "./staging-ring.js";
+import { CURVES, toneMapColor } from "./tonemap.js";
+/**
+ * A draw class's bind group entries: the skinned classes read the palette (binding 17, ADR-0088);
+ * a rigid pipeline's auto layout has no binding 17, so its group leaves it out.
+ */
+function entriesFor(entries, drawClass) {
+    return isSkinnedClass(drawClass) ? entries : entries.filter((e) => e.binding !== 17);
+}
+/** Texels per palette texture row (`shaders/scene/skin.wesl` `PALETTE_WIDTH`). */
+export const PALETTE_WIDTH = 1024;
+/**
+ * The order draw classes draw in (ADR-0081, ADR-0088): everything opaque and masked, rigid then
+ * skinned, before anything blended.
+ */
+export const CLASS_ORDER = [0, 1, 2, 3, 6, 7, 8, 9, 4, 5, 10, 11];
+/** Each shading level's fragment entry (ADR-0072), cheapest last. */
+const FRAGMENT_ENTRIES = ['fs', 'fs_lambert', 'fs_flat'];
+/** Bytes per instance: a 32-byte transform plus a 16-byte static record (ADR-0055). */
+export const INSTANCE_BYTES = 48;
+/** The `Camera` uniform (shaders/core/camera.wesl): the camera's 176 bytes, then the instance origin (ADR-0075). */
+export const CAMERA_BYTES = 192;
+/** Bytes per CPU-culled record (ADR-0059): position, scale, rotation, colour, material (no mesh: the draw knows it). */
+export const CULLED_BYTES = 40;
+/** Bytes of the per-frame part of an instance (the transform). */
+const TRANSFORM_BYTES = 32;
+/** Bytes of the part uploaded only when it changes (colour, mesh, material). */
+const STATIC_BYTES = 16;
+const VERTEX_BYTES = 32;
+/** The skin stream's vertex layout (ADR-0088): 4 × u16 joints at location 6, 4 × unorm16 weights at 7. */
+/** A pool vertex's position only (the motion pass, ADR-0098). */
+export const POSITION_LAYOUT = { arrayStride: VERTEX_BYTES, attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }] };
+export const SKIN_LAYOUT = {
+    arrayStride: SKIN_STREAM_BYTES,
+    attributes: [
+        { shaderLocation: 6, offset: 0, format: 'uint16x4' },
+        { shaderLocation: 7, offset: 8, format: 'unorm16x4' },
+    ],
+};
+const ARGS_WORDS = 5;
+const ARGS_BYTES = ARGS_WORDS * 4;
+const MESH_INFO_WORDS = 16;
+/** The scene pass's clear colour (linear). */
+const CLEAR = [0.035, 0.035, 0.045];
+/**
+ * The GPU-driven many-draw renderer (DESIGN.md §11, M2 increment 2). The core's extract
+ * writes every `render.Mesh` instance into linear memory, grouped by mesh, with the count
+ * per mesh; `upload` copies them to the GPU straight from that memory. A compute pass
+ * culls each instance against its mesh's bounding sphere, picks its LOD from the projected
+ * error, and appends it to that (mesh, LOD) slot; the draw is one `drawIndexedIndirect`
+ * per slot over one geometry pool.
+ *
+ * A slot's instances live at a start the CPU computes from the counts (the layout), so a
+ * draw finds them through `firstInstance` (the storage path) or through a vertex-buffer
+ * offset with `firstInstance` 0 (the vertex path, for compatibility mode; ADR-0045). The
+ * layout, the indirect-argument template and the recorded render bundle change only when
+ * the counts do.
+ */
+export class SceneRenderer {
+    device;
+    /** Instance-buffer capacity (grows on demand). */
+    capacity;
+    /** Instances uploaded this frame. */
+    count = 0;
+    /** Instances drawn, read back a few frames late (NaN until the first readback). */
+    visible = Number.NaN;
+    /** Replay a recorded render bundle instead of encoding the draws each frame. Set before `init`. */
+    useBundles = false;
+    /** Upload instances through a mapped staging ring (default true; see `StagingRing`). Set before `init`. */
+    useStaging = true;
+    /** How the vertex stage gets instance data (ADR-0045; see the class comment). Set before `init`. */
+    path = 'storage';
+    /**
+     * Who culls (ADR-0057): `gpu`, the compute pass feeding indirect draws; `cpu`, the extract
+     * (`InstanceExtractor.runCulled`) with ordinary draws from its per-slot counts, for
+     * devices where indirect draws cost more than they save (compatibility mode). `cpu` uses
+     * the vertex path. Set before `init`.
+     */
+    cull = 'gpu';
+    /** The largest projected LOD error allowed, in pixels, before `lodBias`. */
+    errorPx = 1;
+    /**
+     * The governor's knob (`render.lodBias`, ADR-0050): each unit doubles the allowed LOD
+     * error, and from 1 up also drops instances under `0.25 × 2^lodBias` pixels of radius
+     * (0.5, 1, 2 px), so a step saves work even in a scene without LODs.
+     */
+    lodBias = 0;
+    /** Instances whose projected radius is under this many pixels are not drawn (0 keeps them all; `lodBias` may raise it). */
+    minRadiusPx = 0;
+    // The CPU-cull path: interleaved records in a vertex buffer, and per draw: index count,
+    // first index, base vertex, first instance, instance count.
+    #cpuBuf = null;
+    #cpuDraws = new Uint32Array(0);
+    #cpuDrawCount = 0;
+    #cpuByLod = new Uint32Array(8);
+    /** The CPU cull's draws, per slot and per cascade run (ADR-0073). */
+    #culledDraws = new CulledDraws();
+    /** The cascade fit the CPU cull's caster planes come from (ADR-0073). */
+    #cullFit = new Float32Array(SHADOW_FLOATS);
+    /** Instances each shadow cascade drew last frame on the CPU cull (ADR-0073; a diagnostic). */
+    get shadowCasters() {
+        return this.#culledDraws.casters.slice(0, this.#cpuCascades);
+    }
+    /** Cascades the last CPU cull partitioned by (0: every cascade draws whole slots). */
+    #cpuCascades = 0;
+    /** What the last layout and draw looked like. */
+    stats = { slots: 0, draws: 0, layouts: 0, meshes: 0, shaderBuilds: 0 };
+    #format;
+    #store;
+    #materials;
+    #textures;
+    #texturesArrays = -1;
+    #environment = null;
+    #lights = null;
+    #shadows = null;
+    #shadowPipeline = null;
+    #shadowGroups = [];
+    /** The cascade pipeline without back-face culling, for double-sided casters (built when one exists). */
+    #shadowPipelineDouble = null;
+    #shadowGroupsDouble = [];
+    /** The camera uniform as uploaded: with shadows, its planes swept towards the light (the cull's casters). */
+    #cameraData = new Float32Array(CAMERA_BYTES / 4);
+    #envVersion = -1;
+    #lightingBuf;
+    #lightingData = new Float32Array(48);
+    /** The light; changes apply the next frame. */
+    lighting = { sunColor: [1, 1, 1], sunIntensity: 3, ambient: 1 };
+    /**
+     * When set (T0, ADR-0071), the draw tone-maps inline with these knobs and writes the display
+     * format directly: no HDR target, no tone-mapping pass. Set before `init`.
+     */
+    inlineTone = null;
+    /** The pass's clear colour: linear, or tone-mapped when `inlineTone` is set. */
+    #clear = { r: CLEAR[0], g: CLEAR[1], b: CLEAR[2], a: 1 };
+    #lightingKey = '';
+    #cullPipeline;
+    #drawPipeline;
+    /** One draw pipeline per shading level, and its bind group (the layouts match: `bindings_anchor`). */
+    #levelPipelines = [];
+    #levelGroups = [];
+    #activeLevel = 0;
+    /**
+     * Draw classes 1–5 (ADR-0081: mask, blend, double-sided): per class, one pipeline per shading
+     * level, built the first time a mesh of that class exists (a scene without them compiles
+     * nothing more), and their bind groups. Class 0 is `#levelPipelines` / `#levelGroups`.
+     */
+    #classPipelines = new Array(CLASS_ORDER.length).fill(null);
+    #classGroups = Array.from({ length: CLASS_ORDER.length }, () => []);
+    /** The skinned pool (ADR-0088): vertices in the rigid layout, and the skin stream beside them. */
+    #skinnedVertexBuf = null;
+    #skinBuf = null;
+    #skinnedBlocks = 0;
+    #skinBlocks = 0;
+    /** The palette: `PALETTE_WIDTH` × rows of rgba32float, three texels per joint (`skin.wesl`). */
+    #palette = null;
+    /** Skinned casters' shadow pipelines (single-, double-sided) and their groups (they bind the palette). */
+    #shadowSkinned = null;
+    #shadowSkinnedDouble = null;
+    #shadowSkinnedGroups = [];
+    #shadowSkinnedDoubleGroups = [];
+    /** Where the skinned draws read the palette each frame (`@yali-engine/animation` sets it). */
+    paletteSource = null;
+    #classBuilding = new Map();
+    /** The last draw bind-group entries, for the groups of class pipelines built later. */
+    #groupEntries = null;
+    /** Each slot's draw class (GPU cull path). */
+    #slotClass = new Uint8Array(0);
+    /** Shading levels compiled from the draw shader itself (`shaderVariant`'s levels follow). */
+    #baseLevels = 1;
+    /**
+     * Benchmarks only: a transform of the linked draw shader, compiled beside it as extra
+     * shading levels (`#buildDraws`), so a page can alternate the two and compare them under
+     * the same conditions (a phone's GPU clocks move between separate runs). Set before `init`.
+     * A variant must keep every binding statically used (or keep the level's `bindings_anchor`
+     * call): its pipelines share the bind-group entries, and an unused binding drops out of
+     * the auto layout, so the group fails validation (`RENDER_SETUP`).
+     */
+    shaderVariant = null;
+    /** Shading levels to compile (1, or 3 for the governor's knob). Set before `init`. */
+    shadingLevels = 1;
+    shadingLevel = 0;
+    #camera;
+    #params;
+    #paramsData = new ArrayBuffer(16);
+    #paramsU32 = new Uint32Array(this.#paramsData);
+    #paramsF32 = new Float32Array(this.#paramsData);
+    #lodScale = 1;
+    #materialBuf;
+    /** The materials' glTF extensions (`material_ext`, binding 18, ADR-0093). */
+    #materialExtBuf;
+    #materialVersion = -1;
+    #vertexBuf = null;
+    #indexBuf = null;
+    #vertexBlocks = 0;
+    #indexBlocks = 0;
+    #geometryVersion = -1;
+    #instances = null;
+    #staging = null;
+    // What the GPU's static region holds: records [0, #staticCount) of extract buffer
+    // generation #staticEpoch; -1 after the GPU buffer is (re)created.
+    #staticEpoch = -1;
+    #staticCount = 0;
+    /** Static-region uploads so far (they should be rare: ADR-0055). */
+    staticUploads = 0;
+    // What the GPU's transform region holds: records [0, #transformCount) of extract buffer
+    // generation #transformEpoch, current as of the last frame; -1 after the GPU buffer is
+    // (re)created (ADR-0075).
+    #transformEpoch = -1;
+    #transformCount = 0;
+    /** Transform bytes uploaded last frame (all of them, or only the dirty ranges: ADR-0075). */
+    transformBytes = 0;
+    // The layout: rebuilt when the per-mesh counts (or the meshes' LODs) change.
+    #counts = new Uint32Array(0);
+    #layoutMeshes = -1;
+    #layoutVersion = -1;
+    #meshInfo = null;
+    #argsTemplate = null;
+    #args = null;
+    #ranges = null;
+    #readback = null;
+    #readbackBusy = false;
+    #frame = 0;
+    /** Per draw: slot, first instance of its range, instance capacity of the range. */
+    #drawList = new Uint32Array(0);
+    /** The LOD each slot draws. */
+    #slotLod = new Uint8Array(0);
+    /** Instances drawn per slot, from the last readback. */
+    #drawnBySlot = new Uint32Array(0);
+    #cullGroup = null;
+    #drawGroup = null;
+    /** Recorded draws per slot set (0: the plain cull's or the shadows', 1 and 2: occlusion's passes). */
+    #bundles = null;
+    /**
+     * Two-pass occlusion culling (ADR-0095), `occlusion()` from `@yali-engine/render/occlusion`: set before
+     * `init`; it runs on the GPU cull's storage path only (`occlusionActive`).
+     */
+    occlusion = null;
+    #occl = null;
+    #recheckGroup = null;
+    #occlVersion = -1;
+    /** Draw slots and visible entries per set, under occlusion. */
+    #slots = 0;
+    #region = 0;
+    #dirtyGroups = true;
+    #destroyed = false;
+    constructor(device, format, store, materials, textures, capacity) {
+        this.device = device;
+        this.#format = format;
+        this.#store = store;
+        this.#materials = materials;
+        this.#textures = textures;
+        this.#lightingBuf = device.createBuffer({ label: 'yali:lighting', size: 192, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.#noSceneColor = device.createTexture({ label: 'yali:scene-color:none', size: [1, 1], format: 'rgba16float', usage: GPUTextureUsage.TEXTURE_BINDING });
+        this.capacity = capacity;
+        this.#camera = device.createBuffer({ label: 'yali:camera', size: CAMERA_BYTES, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.#params = device.createBuffer({ label: 'yali:cull:params', size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.#materialBuf = device.createBuffer({ label: 'yali:materials', size: materials.data.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.#materialExtBuf = device.createBuffer({ label: 'yali:materials:ext', size: materials.ext.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    }
+    /** Compiles both pipelines asynchronously through `cache` (DESIGN.md §13: never on the first frame). */
+    async init(cache) {
+        if (this.cull === 'cpu')
+            this.path = 'vertex';
+        const vertex = this.path === 'vertex';
+        this.#cache = cache;
+        this.#palette = this.#paletteTexture(1);
+        [this.#cullPipeline, this.#levelPipelines, this.#shadowPipeline] = await Promise.all([
+            cache.compute({ label: 'yali:scene:cull', compute: { shader: sceneCull, entryPoint: vertex ? 'cull_compact' : 'cull' } }),
+            this.#buildDraws(),
+            this.#shadows?.enabled ? this.#buildShadow() : Promise.resolve(null),
+        ]);
+        this.#drawPipeline = this.#levelPipelines[0];
+        if (this.occlusion && !vertex && this.cull === 'gpu') {
+            const occl = this.occlusion(this.device, this.capacity);
+            await occl.init(cache);
+            this.#occl = occl;
+        }
+        this.#allocateInstances(this.capacity);
+        if (this.cull === 'cpu')
+            this.#cpuDrawGroup();
+    }
+    /**
+     * The draw shader with the app's node materials in its material block (ADR-0064): the
+     * linked `sceneDraw` as is when there are none.
+     */
+    #drawShader() {
+        this.#shadersVersion = this.#materials.shadersVersion;
+        const block = this.#materials.shaderBlock();
+        if (!block)
+            return sceneDraw;
+        const begin = sceneDraw.wgsl.indexOf('// @yali:materials begin');
+        const end = sceneDraw.wgsl.indexOf('// @yali:materials end');
+        if (begin < 0 || end < begin)
+            throw new YaliError('SHADER_MARKERS', 'The draw shader lost its @yali:materials markers.', 'Restore them in shaders/scene/draw.wesl.');
+        const wgsl = `${sceneDraw.wgsl.slice(0, begin)}${block}\n${sceneDraw.wgsl.slice(end)}`;
+        return { hash: `${sceneDraw.hash}-m${fnv1a(block)}`, wgsl };
+    }
+    /**
+     * Every shading level's draw pipeline (all compiled up front: never on a frame). With
+     * `shaderVariant`, the same levels again from the transformed shader, after them: level
+     * `shadingLevels + k` is level k's variant, for A/B measurements in one page.
+     */
+    #buildDraws() {
+        const shader = this.#drawShader();
+        const entries = FRAGMENT_ENTRIES.slice(0, Math.max(1, Math.min(FRAGMENT_ENTRIES.length, this.shadingLevels)));
+        this.#baseLevels = entries.length;
+        const builds = entries.map((fs) => this.#buildDraw(shader, fs));
+        if (this.shaderVariant) {
+            const wgsl = this.shaderVariant(shader.wgsl);
+            const variant = { hash: `${shader.hash}-v${fnv1a(wgsl)}`, wgsl };
+            builds.push(...entries.map((fs) => this.#buildDraw(variant, fs)));
+        }
+        return Promise.all(builds);
+    }
+    #buildDraw(shader, fsEntry, drawClass = 0) {
+        const vertex = this.path === 'vertex';
+        const blend = isBlendClass(drawClass);
+        const skinned = isSkinnedClass(drawClass);
+        const alpha = (drawClass % 6) >> 1;
+        const entry = this.cull === 'cpu' ? 'vs_culled' : vertex ? 'vs_attr' : 'vs';
+        return this.#cache.render({
+            label: skinned ? 'yali:scene:draw:skinned' : 'yali:scene:draw',
+            vertex: {
+                shader,
+                entryPoint: skinned ? `${entry}_skinned` : entry,
+                buffers: [
+                    {
+                        arrayStride: VERTEX_BYTES,
+                        attributes: [
+                            { shaderLocation: 0, offset: 0, format: 'float32x3' },
+                            { shaderLocation: 1, offset: 12, format: 'float32x3' },
+                            { shaderLocation: 5, offset: 24, format: 'float32x2' },
+                        ],
+                    },
+                    ...(vertex
+                        ? [
+                            {
+                                arrayStride: this.cull === 'cpu' ? CULLED_BYTES : INSTANCE_BYTES,
+                                stepMode: 'instance',
+                                attributes: [
+                                    { shaderLocation: 2, offset: 0, format: 'float32x4' },
+                                    { shaderLocation: 3, offset: 16, format: 'float32x4' },
+                                    { shaderLocation: 4, offset: 32, format: this.cull === 'cpu' ? 'uint32x2' : 'uint32x4' },
+                                ],
+                            },
+                        ]
+                        : []),
+                    // The skin stream (ADR-0088), after the instance slot: 4 × u16 joints, 4 × unorm16 weights.
+                    ...(skinned ? [SKIN_LAYOUT] : []),
+                ],
+            },
+            fragment: {
+                shader,
+                entryPoint: alpha === 0 ? fsEntry : `${fsEntry}_${alpha === 1 ? 'mask' : 'blend'}`,
+                targets: [blend ? { format: this.#format, blend: { color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha' }, alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' } } } : { format: this.#format }],
+            },
+            primitive: { topology: 'triangle-list', cullMode: drawClass & 1 ? 'none' : 'back', frontFace: 'ccw' },
+            // Blended surfaces test depth but do not write it (drawn after everything opaque).
+            depthStencil: { format: 'depth32float', depthWriteEnabled: !blend, depthCompare: 'greater' },
+        });
+    }
+    /** Starts building the pipelines of every draw class in `classes` not built yet (never on a frame). */
+    #ensureClasses(classes) {
+        if (!this.#cache)
+            return;
+        for (const c of classes) {
+            if (c === 0 || this.#classPipelines[c] || this.#classBuilding.has(c))
+                continue;
+            const shader = this.#drawShader();
+            const entries = FRAGMENT_ENTRIES.slice(0, this.#baseLevels);
+            const build = Promise.all(entries.map((fs) => this.#buildDraw(shader, fs, c))).then((ps) => {
+                this.#classBuilding.delete(c);
+                if (this.#destroyed)
+                    return;
+                this.#classPipelines[c] = ps;
+                if (this.#groupEntries)
+                    this.#classGroups[c] = ps.map((p, i) => this.device.createBindGroup({ label: `yali:scene:draw:c${c}:${i}`, layout: p.getBindGroupLayout(0), entries: entriesFor(this.#groupEntries, c) }));
+                this.#bundles = null;
+            }, (err) => {
+                this.#classBuilding.delete(c);
+                this.shaderError = err instanceof Error ? err.message : String(err);
+                console.error(`[yali render] draw class ${c} failed to compile:`, err);
+            });
+            this.#classBuilding.set(c, build);
+        }
+        if (this.#shadows?.enabled && !this.#shadowPipelineDouble && [...classes].some((c) => c & 1 && !isBlendClass(c) && !isSkinnedClass(c))) {
+            this.#buildShadow(true).then((p) => {
+                if (this.#destroyed)
+                    return;
+                this.#shadowPipelineDouble = p;
+                this.#buildShadowGroups();
+            });
+        }
+        // Skinned casters (ADR-0088): their own pipelines, single- and double-sided, when one exists.
+        for (const two of [false, true]) {
+            const have = two ? this.#shadowSkinnedDouble : this.#shadowSkinned;
+            if (!this.#shadows?.enabled || have || this.#shadowBuilding.has(two) || ![...classes].some((c) => isSkinnedClass(c) && !isBlendClass(c) && (c & 1) === (two ? 1 : 0)))
+                continue;
+            this.#shadowBuilding.add(two);
+            this.#buildShadow(two, true).then((p) => {
+                this.#shadowBuilding.delete(two);
+                if (this.#destroyed)
+                    return;
+                if (two)
+                    this.#shadowSkinnedDouble = p;
+                else
+                    this.#shadowSkinned = p;
+                this.#buildShadowGroups();
+            });
+        }
+    }
+    #shadowBuilding = new Set();
+    /**
+     * Resolves when every draw class the stored meshes need is compiled (they build in the
+     * background, and a class draws from the frame after its pipelines exist). Await it for a
+     * first frame that must show every mesh (goldens, captures).
+     */
+    async drawClassesReady() {
+        this.#ensureClasses(new Set(this.#store.entries.map((e) => e.drawClass)));
+        if (this.#maskMotionFormat)
+            this.prepareMaskMotion(this.#maskMotionFormat);
+        await Promise.all([...this.#classBuilding.values(), ...this.#maskMotionBuilding.values()]);
+        await this.clusters?.ready();
+    }
+    /** Class `c`'s pipeline and bind group at the active shading level (null until built). */
+    #classDraw(c) {
+        if (c === 0)
+            return this.#drawPipeline && this.#drawGroup ? [this.#drawPipeline, this.#drawGroup] : null;
+        const ps = this.#classPipelines[c];
+        const gs = this.#classGroups[c];
+        if (!ps || gs.length !== ps.length)
+            return null;
+        const level = this.#activeLevel % this.#baseLevels;
+        return [ps[level], gs[level]];
+    }
+    /** The depth-only cascade pipeline (ADR-0068): the draw's vertex buffers, transform only (and, skinned, the skin stream). */
+    #buildShadow(doubleSided = false, skinned = false) {
+        const vertex = this.path === 'vertex';
+        const cpu = this.cull === 'cpu';
+        const entry = skinned ? (cpu ? 'vs_shadow_culled_skinned' : vertex ? 'vs_shadow_attr_skinned' : 'vs_shadow_skinned') : vertex ? 'vs_shadow_attr' : 'vs_shadow';
+        return this.#cache.render({
+            label: `yali:scene:shadow${skinned ? ':skinned' : ''}${doubleSided ? ':double' : ''}`,
+            vertex: {
+                shader: sceneShadow,
+                entryPoint: entry,
+                buffers: [
+                    { arrayStride: VERTEX_BYTES, attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }] },
+                    ...(vertex
+                        ? [
+                            {
+                                arrayStride: cpu ? CULLED_BYTES : INSTANCE_BYTES,
+                                stepMode: 'instance',
+                                attributes: [
+                                    { shaderLocation: 2, offset: 0, format: 'float32x4' },
+                                    { shaderLocation: 3, offset: 16, format: 'float32x4' },
+                                    // The skinned casters read the record's ids for their skin row.
+                                    ...(skinned ? [{ shaderLocation: 4, offset: 32, format: (cpu ? 'uint32x2' : 'uint32x4') }] : []),
+                                ],
+                            },
+                        ]
+                        : []),
+                    ...(skinned ? [SKIN_LAYOUT] : []),
+                ],
+            },
+            primitive: { topology: 'triangle-list', cullMode: doubleSided ? 'none' : 'back', frontFace: 'ccw' },
+            depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'greater' },
+        });
+    }
+    /** One bind group per cascade: its matrix at its offset, and (storage path) the instances. */
+    #buildShadowGroups() {
+        const sh = this.#shadows;
+        if (!sh?.enabled || !this.#shadowPipeline)
+            return;
+        const storage = this.path === 'storage';
+        if (storage && (!this.#instances || !this.#ranges))
+            return;
+        const groups = (pipeline, label) => Array.from({ length: sh.cascades }, (_, c) => this.device.createBindGroup({
+            label: `${label}:${c}`,
+            layout: pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: sh.cascadeBuffer, offset: SunShadows.offset(c), size: CASCADE_UNIFORM_BYTES } },
+                ...(storage ? [{ binding: 1, resource: { buffer: this.#instances } }, { binding: 2, resource: { buffer: this.#ranges } }] : []),
+            ],
+        }));
+        this.#shadowGroups = groups(this.#shadowPipeline, 'yali:scene:shadow');
+        this.#shadowGroupsDouble = this.#shadowPipelineDouble ? groups(this.#shadowPipelineDouble, 'yali:scene:shadow:double') : [];
+        // The skinned casters' groups add the palette (binding 3).
+        const skinned = (pipeline, label) => Array.from({ length: sh.cascades }, (_, c) => this.device.createBindGroup({
+            label: `${label}:${c}`,
+            layout: pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: sh.cascadeBuffer, offset: SunShadows.offset(c), size: CASCADE_UNIFORM_BYTES } },
+                ...(storage ? [{ binding: 1, resource: { buffer: this.#instances } }, { binding: 2, resource: { buffer: this.#ranges } }] : []),
+                { binding: 3, resource: this.#palette.createView() },
+            ],
+        }));
+        this.#shadowSkinnedGroups = this.#shadowSkinned && this.#palette ? skinned(this.#shadowSkinned, 'yali:scene:shadow:skinned') : [];
+        this.#shadowSkinnedDoubleGroups = this.#shadowSkinnedDouble && this.#palette ? skinned(this.#shadowSkinnedDouble, 'yali:scene:shadow:skinned:double') : [];
+    }
+    /** A palette texture `rows` texture rows tall (ADR-0088). */
+    #paletteTexture(rows) {
+        return this.device.createTexture({ label: 'yali:palette', size: [PALETTE_WIDTH, rows], format: 'rgba32float', usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.COPY_SRC });
+    }
+    /**
+     * Uploads this frame's palette (ADR-0088): full texture rows, then the partial last one. A
+     * palette taller than the texture replaces it (doubling), and the bind groups are rebuilt.
+     */
+    #syncPalette() {
+        const view = this.paletteSource?.();
+        if (!view || view.rows === 0 || !this.#palette)
+            return;
+        const texels = view.rows * 3;
+        const rows = Math.ceil(texels / PALETTE_WIDTH);
+        if (rows > this.#palette.height) {
+            this.#palette.destroy();
+            this.#palette = this.#paletteTexture(nextPow2(rows));
+            if (this.cull === 'cpu')
+                this.#cpuDrawGroup();
+            else
+                this.#dirtyGroups = true;
+        }
+        const q = this.device.queue;
+        const src = view.f32;
+        const full = Math.floor(texels / PALETTE_WIDTH);
+        const byteAt = src.byteOffset + view.at * 4;
+        if (full > 0)
+            q.writeTexture({ texture: this.#palette }, src.buffer, { offset: byteAt, bytesPerRow: PALETTE_WIDTH * 16, rowsPerImage: full }, [PALETTE_WIDTH, full]);
+        const rest = texels - full * PALETTE_WIDTH;
+        if (rest > 0)
+            q.writeTexture({ texture: this.#palette, origin: [0, full] }, src.buffer, { offset: byteAt + full * PALETTE_WIDTH * 16, bytesPerRow: PALETTE_WIDTH * 16 }, [rest, 1]);
+    }
+    /**
+     * When node-material shaders were registered, compiles the new draw pipeline in the
+     * background and swaps it in when ready (DESIGN.md §13: never a compile on the frame);
+     * until then the old one draws (new shader ids fall back to the standard material).
+     */
+    #syncShaders() {
+        if (this.#rebuilding || this.#shadersVersion === this.#materials.shadersVersion || !this.#cache)
+            return;
+        this.#rebuilding = this.#buildDraws().then((ps) => {
+            this.#rebuilding = null;
+            if (this.#destroyed)
+                return;
+            this.#levelPipelines = ps;
+            this.#drawPipeline = ps[Math.min(this.#activeLevel, ps.length - 1)];
+            this.stats.shaderBuilds++;
+            if (this.cull === 'cpu')
+                this.#cpuDrawGroup();
+            else
+                this.#dirtyGroups = true;
+        }, (err) => {
+            this.#rebuilding = null;
+            this.shaderError = err instanceof Error ? err.message : String(err);
+            console.error('[yali render] the draw shader with the node materials failed to compile:', err);
+        });
+    }
+    /**
+     * Resolves when the draw pipeline includes every node-material shader registered so far
+     * (it compiles in the background). Await it after registering shaders to keep the first
+     * frames from drawing those materials as standard ones; rejects when the build failed.
+     */
+    async shadersReady() {
+        for (;;) {
+            this.#syncShaders();
+            if (this.#rebuilding)
+                await this.#rebuilding;
+            if (this.shaderError)
+                throw new YaliError('SHADER_BUILD', `The draw shader with the node materials failed to compile: ${this.shaderError}`, 'See the WGSL error; recompile the materials (the materials build step).');
+            if (this.#shadersVersion === this.#materials.shadersVersion)
+                return;
+        }
+    }
+    #cache = null;
+    #shadersVersion = -1;
+    #rebuilding = null;
+    /** The last failed node-material shader build's message ('' when none). */
+    shaderError = '';
+    /** The sun's shadows (set before `init`; the render plugin does). */
+    set shadows(s) {
+        this.#shadows = s;
+    }
+    /** The clustered point and spot lights (set before `init`; the render plugin does). */
+    set lights(l) {
+        this.#lights = l;
+    }
+    /** The environment the draw lights with (set before `init`; the render plugin does). */
+    set environment(env) {
+        this.#environment = env;
+        this.#envVersion = -1;
+    }
+    /** The texture and lighting bindings every draw path shares (ADR-0060, M2 increment 5). */
+    #textureEntries() {
+        this.#texturesArrays = this.#textures.arraysVersion;
+        if (!this.#environment)
+            throw new YaliError('NO_ENVIRONMENT', 'The scene renderer has no environment.', 'Set scene.environment before init (the render plugin does).');
+        if (!this.#lights)
+            throw new YaliError('NO_LIGHTS', 'The scene renderer has no clustered lights.', 'Set scene.lights before init (the render plugin does).');
+        if (!this.#shadows)
+            throw new YaliError('NO_SHADOWS', 'The scene renderer has no shadow maps.', 'Set scene.shadows before init (the render plugin does).');
+        return [
+            { binding: 4, resource: this.#textures.texture('srgb').createView({ dimension: '2d-array' }) },
+            { binding: 5, resource: this.#textures.sampler },
+            { binding: 6, resource: this.#textures.texture('linear').createView({ dimension: '2d-array' }) },
+            { binding: 7, resource: { buffer: this.#lightingBuf } },
+            { binding: 8, resource: this.#environment.prefiltered.createView({ dimension: 'cube' }) },
+            { binding: 9, resource: this.#textures.rgba8Texture('srgb').createView({ dimension: '2d-array' }) },
+            { binding: 10, resource: this.#textures.rgba8Texture('linear').createView({ dimension: '2d-array' }) },
+            { binding: 11, resource: { buffer: this.#lights.lightsBuffer } },
+            { binding: 12, resource: { buffer: this.#lights.paramsBuffer } },
+            { binding: 13, resource: this.#lights.bins.createView() },
+            { binding: 14, resource: { buffer: this.#shadows.paramsBuffer } },
+            { binding: 15, resource: this.#shadows.view },
+            { binding: 16, resource: this.#shadows.sampler },
+            { binding: 17, resource: (this.#palette ??= this.#paletteTexture(1)).createView() },
+        ];
+    }
+    /** Uploads the lighting uniform when the light or the environment changed. */
+    #syncLighting() {
+        const env = this.#environment;
+        if (!env)
+            return;
+        const l = this.lighting;
+        const c = l.sunColor;
+        const t = this.inlineTone;
+        const exposure = t ? t.exposure : 0;
+        const curve = t ? CURVES[t.curve] : -1;
+        if (c[0] === this.#lit[0] && c[1] === this.#lit[1] && c[2] === this.#lit[2] && l.sunIntensity === this.#lit[3] && l.ambient === this.#lit[4] && exposure === this.#lit[5] && curve === this.#lit[6] && env.version === this.#envVersion)
+            return;
+        this.#lit.set([c[0], c[1], c[2], l.sunIntensity, l.ambient, exposure, curve]);
+        if (t) {
+            const [r, g, b] = toneMapColor(CLEAR, t.exposure, t.curve);
+            Object.assign(this.#clear, { r, g, b });
+        }
+        this.#envVersion = env.version;
+        const d = this.#lightingData;
+        d[0] = c[0] * l.sunIntensity;
+        d[1] = c[1] * l.sunIntensity;
+        d[2] = c[2] * l.sunIntensity;
+        d[3] = l.ambient;
+        d[4] = env.mips;
+        d[5] = t ? 1 : 0;
+        d[6] = exposure;
+        d[7] = Math.max(0, curve);
+        d.set(env.sh9, 8);
+        const screen = this.#splitBlend() && this.#sceneColor;
+        d[44] = screen ? 1 : 0;
+        d[45] = screen ? 1 / this.#targetW : 0;
+        d[46] = screen ? 1 / this.#targetH : 0;
+        // The copy's mip chain (ADR-0119): its levels once the downsample is built, else just the copy.
+        d[47] = screen && this.#mips ? this.#sceneColor.mipLevelCount : 1;
+        this.device.queue.writeBuffer(this.#lightingBuf, 0, d);
+        // The second transparent layer's (ADR-0125): `screen.x` 2 says which pass draws, the layer copy's levels.
+        if (screen && this.#lighting2 && this.#layerColor) {
+            d[44] = 2;
+            d[47] = this.#mips ? this.#layerColor.mipLevelCount : 1;
+            this.device.queue.writeBuffer(this.#lighting2, 0, d);
+            d[44] = 1;
+            d[47] = this.#mips ? this.#sceneColor.mipLevelCount : 1;
+        }
+    }
+    #lit = new Float64Array(7).fill(Number.NaN);
+    #cpuDrawGroup() {
+        this.#drawGroups([{ binding: 0, resource: { buffer: this.#camera } }, { binding: 3, resource: { buffer: this.#materialBuf } }, { binding: 18, resource: { buffer: this.#materialExtBuf } }, { binding: 19, resource: (this.#sceneColor ?? this.#noSceneColor).createView() }, ...this.#textureEntries()]);
+        this.#buildShadowGroups();
+    }
+    /** The draw's bind group for every shading level's pipeline (the same entries). */
+    #drawGroups(entries) {
+        this.#groupEntries = entries;
+        this.#groupsEpoch++;
+        this.#levelGroups = this.#levelPipelines.map((p, i) => this.device.createBindGroup({ label: `yali:scene:draw:${i}`, layout: p.getBindGroupLayout(0), entries: entriesFor(entries, 0) }));
+        for (let c = 1; c < CLASS_ORDER.length; c++) {
+            const ps = this.#classPipelines[c];
+            this.#classGroups[c] = ps ? ps.map((p, i) => this.device.createBindGroup({ label: `yali:scene:draw:c${c}:${i}`, layout: p.getBindGroupLayout(0), entries: entriesFor(entries, c) })) : [];
+        }
+        this.#drawGroup = this.#levelGroups[Math.min(this.#activeLevel, this.#levelGroups.length - 1)];
+    }
+    /** Swaps in the shading level's pipeline and bind group when the knob moved. */
+    #syncLevel() {
+        const level = Math.max(0, Math.min(this.#levelPipelines.length - 1, Math.round(this.shadingLevel)));
+        if (level === this.#activeLevel)
+            return;
+        this.#activeLevel = level;
+        this.#drawPipeline = this.#levelPipelines[level];
+        if (this.#levelGroups[level])
+            this.#drawGroup = this.#levelGroups[level];
+        this.#bundles = null;
+    }
+    /** Whether the sun casts this frame (shadows on, and not shading level 2). */
+    get #casting() {
+        return !!this.#shadows?.enabled && this.#activeLevel % this.#baseLevels < 2;
+    }
+    /**
+     * Writes the CPU cull's parameters (ADR-0057) into linear memory at word `at` of `f32`:
+     * the camera's six frustum planes (camera-relative), the LOD scale for a target `heightPx`
+     * tall, and the error and small-instance thresholds after `lodBias`: what the GPU cull
+     * reads from its uniforms.
+     */
+    writeCullParams(f32, at, camera, heightPx, widthPx = heightPx) {
+        this.#syncLevel();
+        if (this.#casting)
+            SunShadows.sweptPlanes(camera, f32, at);
+        else
+            for (let k = 0; k < 24; k++)
+                f32[at + k] = camera.uniform[16 + k];
+        // Casters per cascade (ADR-0073): fit now (the Submit stage's fit is the same), then the boxes.
+        const sh = this.#shadows;
+        const partition = this.#casting && sh && sh.cascades <= CULL_CASCADES ? sh.cascades : 0;
+        f32[at + 27] = partition;
+        if (partition > 0) {
+            // The fit only: the Submit stage's update fits again and uploads (no GPU write here).
+            fitCascades(sh, camera, widthPx / Math.max(1, heightPx), this.#cullFit);
+            cascadeCullPlanes(this.#cullFit, partition, f32, at + 28);
+        }
+        const scale = 2 ** this.lodBias;
+        f32[at + 24] = heightPx / (2 * Math.tan(camera.fovY / 2));
+        f32[at + 25] = this.errorPx * scale;
+        f32[at + 26] = Math.max(this.minRadiusPx, this.lodBias > 0 ? 0.25 * scale : 0);
+    }
+    #allocateInstances(capacity) {
+        this.#instances?.destroy();
+        this.#staging?.destroy();
+        this.capacity = capacity;
+        // Exactly capacity * 48 bytes: the shaders find the static region from its length.
+        this.#instances = this.device.createBuffer({ label: 'yali:instances', size: capacity * INSTANCE_BYTES, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC });
+        this.#staging = this.useStaging ? new StagingRing(this.device, capacity * TRANSFORM_BYTES) : null;
+        this.#staticEpoch = -1;
+        this.#transformEpoch = -1;
+        this.#dirtyGroups = true;
+    }
+    /** Grows the instance buffers to hold `count` instances (rare; reallocates). */
+    ensureCapacity(count) {
+        if (count <= this.capacity)
+            return;
+        this.#allocateInstances(Math.max(count, Math.ceil(this.capacity * 1.5)));
+        this.#occl?.ensureCapacity(this.capacity);
+    }
+    /** Whether two-pass occlusion culling runs (asked for, on the GPU cull's storage path). */
+    get occlusionActive() {
+        return !!this.#occl;
+    }
+    /** The staging ring's counters (null when staging is off). */
+    get staging() {
+        return this.#staging;
+    }
+    /** The camera uniform buffer. */
+    get cameraBuffer() {
+        return this.#camera;
+    }
+    /**
+     * Uploads the camera uniform; `heightPx` (the render target's height) sets the LOD scale.
+     * `origin` is the camera's offset from the anchor the instance records are relative to
+     * (ADR-0075; omit it for camera-relative records).
+     */
+    setCamera(camera, heightPx, origin) {
+        // The draw reads only viewProj and the light; the GPU cull reads the planes, which with
+        // shadows are swept towards the light so off-screen casters survive (ADR-0068).
+        this.#syncLevel();
+        const data = this.#cameraData;
+        data.set(camera.uniform);
+        // TAA's sub-pixel jitter (ADR-0092): a clip-space offset, so x += jx * w (and y).
+        const j = this.jitter;
+        if (j) {
+            for (let c = 0; c < 4; c++) {
+                data[c * 4] += j[0] * data[c * 4 + 3];
+                data[c * 4 + 1] += j[1] * data[c * 4 + 3];
+            }
+        }
+        for (let i = 0; i < 3; i++)
+            data[44 + i] = origin ? origin[i] : 0;
+        if (this.#casting)
+            SunShadows.sweptPlanes(camera, data, 16);
+        this.device.queue.writeBuffer(this.#camera, 0, data);
+        this.#occl?.update(camera, data, this.#casting, this.#slots, this.#region);
+        this.#lodScale = heightPx / (2 * Math.tan(camera.fovY / 2));
+    }
+    /**
+     * Uploads this frame's extracted instances straight from linear memory (`heap` is the
+     * whole-memory byte view, `u32` the same memory as words): the transforms every frame,
+     * the static records only when they changed or the GPU has not got them (ADR-0055). Lays
+     * out the draw slots from the per-mesh counts. Call `recordUpload` on the frame's encoder
+     * before the passes, and `afterSubmit` after `queue.submit`.
+     */
+    upload(heap, u32, x) {
+        this.#syncGeometry();
+        this.#syncPalette();
+        this.#syncMaterials();
+        this.#syncShaders();
+        this.#syncLighting();
+        if (this.#texturesArrays !== this.#textures.arraysVersion) {
+            if (this.cull === 'cpu')
+                this.#cpuDrawGroup();
+            else
+                this.#dirtyGroups = true;
+        }
+        if (this.cull === 'cpu')
+            return this.#uploadCulled(heap, u32, x);
+        this.count = Math.min(x.count, this.capacity);
+        const countsAt = x.countsAt >>> 2;
+        if (this.#layoutChanged(u32, countsAt, x.meshes))
+            this.#layout(u32, countsAt, x.meshes);
+        if (this.#dirtyGroups)
+            this.#bindGroups();
+        const q = this.device.queue;
+        const bytes = this.count * TRANSFORM_BYTES;
+        // The heap may be a SharedArrayBuffer view (threaded core): WebGPU accepts shared
+        // sources (GPUAllowSharedBufferSource); @webgpu/types' generics don't say so yet.
+        const src = heap;
+        if (x.dirty < 0 || x.epoch !== this.#transformEpoch || this.count > this.#transformCount) {
+            // Everything: the extract rewrote it all, or the GPU buffer does not hold the rest.
+            if (bytes > 0 && !this.#staging?.write(heap, x.address, bytes))
+                q.writeBuffer(this.#instances, 0, src, x.address, bytes);
+            this.#transformEpoch = x.epoch;
+            this.#transformCount = this.count;
+            this.transformBytes = bytes;
+        }
+        else {
+            // Only the ranges the extract rewrote (ADR-0075); the GPU holds the rest from earlier frames.
+            let sent = 0;
+            const at = x.dirtyAt >>> 2;
+            for (let i = 0; i < x.dirty; i++) {
+                const first = u32[at + 2 * i];
+                const end = Math.min(u32[at + 2 * i + 1], this.count);
+                if (end <= first)
+                    continue;
+                q.writeBuffer(this.#instances, first * TRANSFORM_BYTES, src, x.address + first * TRANSFORM_BYTES, (end - first) * TRANSFORM_BYTES);
+                sent += (end - first) * TRANSFORM_BYTES;
+            }
+            this.transformBytes = sent;
+        }
+        if (this.count > 0 && (x.staticChanged || x.epoch !== this.#staticEpoch || this.count > this.#staticCount)) {
+            q.writeBuffer(this.#instances, this.capacity * TRANSFORM_BYTES, heap, x.address + x.cap * TRANSFORM_BYTES, this.count * STATIC_BYTES);
+            this.#staticEpoch = x.epoch;
+            this.#staticCount = this.count;
+            this.staticUploads++;
+        }
+        const scale = 2 ** this.lodBias;
+        this.#paramsU32[0] = this.count;
+        this.#paramsF32[1] = this.#lodScale;
+        this.#paramsF32[2] = this.errorPx * scale;
+        this.#paramsF32[3] = Math.max(this.minRadiusPx, this.lodBias > 0 ? 0.25 * scale : 0);
+        q.writeBuffer(this.#params, 0, this.#paramsData);
+    }
+    /**
+     * The CPU-cull upload (ADR-0057, ADR-0059): the visible instances' 40-byte records, already
+     * grouped by draw slot, into one vertex buffer; one draw per non-empty slot from the
+     * per-slot counts. No compute pass, no indirect draw, no readback.
+     */
+    #uploadCulled(heap, u32, x) {
+        const q = this.device.queue;
+        const bytes = x.count * CULLED_BYTES;
+        if (!this.#cpuBuf || this.#cpuBuf.size < bytes) {
+            this.#cpuBuf?.destroy();
+            this.#cpuBuf = this.device.createBuffer({ label: 'yali:scene:culled', size: Math.max(1 << 16, nextPow2(bytes)), usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+        }
+        if (bytes > 0)
+            q.writeBuffer(this.#cpuBuf, 0, heap, x.address, bytes);
+        const draws = this.#culledDraws;
+        draws.build(u32, x.countsAt >>> 2, x.meshes, this.#store.entries, x.cascades);
+        this.#cpuDraws = draws.main;
+        this.#cpuByLod.set(draws.byLod);
+        this.#cpuCascades = x.cascades;
+        this.#cpuDrawCount = draws.mainCount;
+        this.count = x.count;
+        this.visible = x.count;
+    }
+    /** The last `MeshStore.updateVertices` serial uploaded. */
+    #writesSeen = 0;
+    /** Uploads meshes added since the last call (grows the pool, re-uploading, when full). */
+    #syncGeometry() {
+        const s = this.#store;
+        if (this.#geometryVersion === s.version) {
+            this.#syncWrites();
+            return;
+        }
+        const vBytes = s.vertexCount * VERTEX_BYTES;
+        const iBytes = s.indexCount * 4;
+        const q = this.device.queue;
+        if (!this.#vertexBuf || this.#vertexBuf.size < vBytes) {
+            this.#vertexBuf?.destroy();
+            // STORAGE too: the clustered draw pulls vertices (ADR-0100).
+            this.#vertexBuf = this.device.createBuffer({ label: 'yali:geometry:vertices', size: Math.max(1 << 16, nextPow2(vBytes)), usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST | GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC });
+            this.#poolEpoch++;
+            this.#vertexBlocks = 0;
+            this.#dirtyGroups = true;
+        }
+        if (!this.#indexBuf || this.#indexBuf.size < iBytes) {
+            this.#indexBuf?.destroy();
+            this.#indexBuf = this.device.createBuffer({ label: 'yali:geometry:indices', size: Math.max(1 << 16, nextPow2(iBytes)), usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST });
+            this.#indexBlocks = 0;
+            this.#dirtyGroups = true;
+        }
+        for (; this.#vertexBlocks < s.vertexBlocks.length; this.#vertexBlocks++) {
+            const b = s.vertexBlocks[this.#vertexBlocks];
+            q.writeBuffer(this.#vertexBuf, b.at * VERTEX_BYTES, b.data);
+        }
+        for (; this.#indexBlocks < s.indexBlocks.length; this.#indexBlocks++) {
+            const b = s.indexBlocks[this.#indexBlocks];
+            q.writeBuffer(this.#indexBuf, b.at * 4, b.data);
+        }
+        // The skinned pool (ADR-0088), only once a skinned mesh exists.
+        if (s.skinnedVertexCount > 0) {
+            const sv = s.skinnedVertexCount * VERTEX_BYTES;
+            if (!this.#skinnedVertexBuf || this.#skinnedVertexBuf.size < sv) {
+                this.#skinnedVertexBuf?.destroy();
+                this.#skinBuf?.destroy();
+                const n = Math.max(1 << 12, nextPow2(s.skinnedVertexCount));
+                this.#skinnedVertexBuf = this.device.createBuffer({ label: 'yali:geometry:skinned', size: n * VERTEX_BYTES, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST | GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC });
+                this.#skinBuf = this.device.createBuffer({ label: 'yali:geometry:skin', size: n * SKIN_STREAM_BYTES, usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST });
+                this.#skinnedBlocks = 0;
+                this.#skinBlocks = 0;
+                this.#bundles = null;
+            }
+            for (; this.#skinnedBlocks < s.skinnedVertexBlocks.length; this.#skinnedBlocks++) {
+                const b = s.skinnedVertexBlocks[this.#skinnedBlocks];
+                q.writeBuffer(this.#skinnedVertexBuf, b.at * VERTEX_BYTES, b.data);
+            }
+            for (; this.#skinBlocks < s.skinBlocks.length; this.#skinBlocks++) {
+                const b = s.skinBlocks[this.#skinBlocks];
+                q.writeBuffer(this.#skinBuf, b.at * SKIN_STREAM_BYTES, b.data);
+            }
+        }
+        this.#geometryVersion = s.version;
+        this.#syncWrites();
+        this.#ensureClasses(new Set(s.entries.map((e) => e.drawClass)));
+    }
+    /** Rewritten vertices (`MeshStore.updateVertices`, morphs) and indices (`updateIndices`, ADR-0117) newer than the last upload. */
+    #syncWrites() {
+        const s = this.#store;
+        if (s.writeSerial === this.#writesSeen)
+            return;
+        const q = this.device.queue;
+        for (const w of s.vertexWrites.values()) {
+            if (w.serial <= this.#writesSeen)
+                continue;
+            if (w.skinned)
+                this.#skinnedDynamic = true;
+            else
+                this.#poolDynamic = true;
+            if (this.#motionWanted)
+                this.#prevPools();
+            const buf = w.skinned ? this.#skinnedVertexBuf : this.#vertexBuf;
+            if (buf)
+                q.writeBuffer(buf, w.at * VERTEX_BYTES, w.data);
+        }
+        for (const w of s.indexWrites.values()) {
+            if (w.serial > this.#writesSeen && this.#indexBuf)
+                q.writeBuffer(this.#indexBuf, w.at * 4, w.data);
+        }
+        // Streamed cluster pages' vertices (ADR-0134): static, so the pool stays as it was for motion.
+        for (const w of s.rangeWrites) {
+            if (w.serial > this.#writesSeen && this.#vertexBuf)
+                q.writeBuffer(this.#vertexBuf, w.at * VERTEX_BYTES, w.data);
+        }
+        s.rangesSeen = s.writeSerial;
+        this.#writesSeen = s.writeSerial;
+    }
+    #syncMaterials() {
+        const m = this.#materials;
+        m.sync(this.#textures.version);
+        if (this.#materialVersion === m.version)
+            return;
+        this.device.queue.writeBuffer(this.#materialBuf, 0, m.data);
+        this.device.queue.writeBuffer(this.#materialExtBuf, 0, m.ext);
+        this.#materialVersion = m.version;
+    }
+    #layoutChanged(counts, at, meshes) {
+        if (meshes !== this.#layoutMeshes || this.#layoutVersion !== this.#store.version)
+            return true;
+        const own = this.#counts;
+        for (let m = 0; m < meshes; m++)
+            if (counts[at + m] !== own[m])
+                return true;
+        return false;
+    }
+    /**
+     * Lays out the draw slots: each mesh with instances gets one slot per LOD, and each
+     * slot a range as long as the mesh's instance count (any LOD may take them all). Writes
+     * the mesh table, the indirect-argument template and the draw list; reallocates what
+     * no longer fits. Runs when the counts change, never per frame.
+     */
+    #layout(counts, at, meshes) {
+        const d = this.device;
+        const entries = this.#store.entries;
+        if (this.#counts.length < meshes)
+            this.#counts = new Uint32Array(nextPow2(meshes));
+        this.#counts.set(counts.subarray(at, at + meshes));
+        this.#layoutMeshes = meshes;
+        this.#layoutVersion = this.#store.version;
+        const info = new ArrayBuffer(Math.max(1, meshes) * MESH_INFO_WORDS * 4);
+        const infoU = new Uint32Array(info);
+        const infoF = new Float32Array(info);
+        let slots = 0;
+        let range = 0;
+        for (let m = 0; m < meshes; m++) {
+            const n = this.#counts[m];
+            const e = entries[m];
+            const o = m * MESH_INFO_WORDS;
+            infoF[o] = e.center[0];
+            infoF[o + 1] = e.center[1];
+            infoF[o + 2] = e.center[2];
+            infoF[o + 3] = e.radius;
+            infoU[o + 4] = e.lods.length;
+            infoU[o + 5] = slots;
+            infoU[o + 6] = range;
+            infoU[o + 7] = n;
+            for (let l = 0; l < MAX_LODS; l++)
+                infoF[o + 8 + l] = e.lods[l]?.error ?? 0;
+            if (n > 0) {
+                slots += e.lods.length;
+                range += e.lods.length * n;
+            }
+        }
+        // Occlusion (ADR-0095) keeps three sets of slots and ranges: shadows, pass 1, pass 2.
+        const sets = this.#occl ? 3 : 1;
+        const args = new Uint32Array(Math.max(1, slots) * ARGS_WORDS * sets);
+        const draws = new Uint32Array(slots * 3);
+        const slotLod = new Uint8Array(slots);
+        const slotClass = new Uint8Array(slots);
+        const slotMesh = new Uint32Array(slots);
+        const storage = this.path === 'storage';
+        for (let m = 0, s = 0; m < meshes; m++) {
+            const n = this.#counts[m];
+            if (n === 0)
+                continue;
+            const e = entries[m];
+            const base = infoU[m * MESH_INFO_WORDS + 6];
+            for (let l = 0; l < e.lods.length; l++, s++) {
+                const lod = e.lods[l];
+                const start = base + l * n;
+                for (let k = 0; k < sets; k++)
+                    args.set([lod.count, 0, lod.firstIndex, e.baseVertex, storage ? start + k * range : 0], (s + k * slots) * ARGS_WORDS);
+                draws.set([s, start, n], s * 3);
+                slotLod[s] = l;
+                slotMesh[s] = m;
+                slotClass[s] = e.drawClass;
+            }
+        }
+        this.#drawList = draws;
+        this.#slots = slots;
+        this.#region = range;
+        this.#slotLod = slotLod;
+        this.#slotMesh = slotMesh;
+        this.#slotClass = slotClass;
+        this.#drawnBySlot = new Uint32Array(slots);
+        this.stats.slots = slots;
+        this.stats.meshes = meshes;
+        this.stats.layouts++;
+        const grow = (buf, size, label, usage) => {
+            if (buf && buf.size >= size)
+                return buf;
+            buf?.destroy();
+            this.#dirtyGroups = true;
+            return d.createBuffer({ label, size: nextPow2(Math.max(size, 256)), usage });
+        };
+        this.#meshInfo = grow(this.#meshInfo, info.byteLength, 'yali:scene:meshes', GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+        this.#argsTemplate = grow(this.#argsTemplate, args.byteLength, 'yali:scene:args-template', GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST);
+        this.#args = grow(this.#args, args.byteLength, 'yali:scene:args', GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC);
+        if (!this.#readbackBusy) {
+            const rb = grow(this.#readback, args.byteLength, 'yali:scene:args-readback', GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST);
+            this.#readback = rb;
+        }
+        this.#ranges = storage
+            ? grow(this.#ranges, Math.max(1, range) * 4 * sets, 'yali:scene:visible', GPUBufferUsage.STORAGE)
+            : grow(this.#ranges, Math.max(1, range) * INSTANCE_BYTES, 'yali:scene:compact', GPUBufferUsage.STORAGE | GPUBufferUsage.VERTEX);
+        d.queue.writeBuffer(this.#meshInfo, 0, info);
+        d.queue.writeBuffer(this.#argsTemplate, 0, args);
+        this.#argsBytes = args.byteLength;
+        this.#bundles = null; // re-recorded with the new draw list
+    }
+    #argsBytes = 0;
+    #bindGroups() {
+        if (!this.#instances || !this.#meshInfo || !this.#args || !this.#ranges)
+            return;
+        const d = this.device;
+        const vertex = this.path === 'vertex';
+        const cullEntries = [
+            { binding: 0, resource: { buffer: this.#camera } },
+            { binding: 1, resource: { buffer: this.#instances } },
+            { binding: 2, resource: { buffer: this.#meshInfo } },
+            { binding: 3, resource: { buffer: this.#args } },
+            { binding: 4, resource: { buffer: this.#params } },
+            { binding: vertex ? 6 : 5, resource: { buffer: this.#ranges } },
+        ];
+        const occl = this.#occl;
+        if (occl) {
+            cullEntries.push({ binding: 7, resource: { buffer: occl.params } }, { binding: 8, resource: occl.view }, { binding: 9, resource: { buffer: occl.recheck } });
+            this.#recheckGroup = d.createBindGroup({ label: 'yali:scene:recheck', layout: occl.recheckPipeline.getBindGroupLayout(0), entries: cullEntries });
+            this.#occlVersion = occl.version;
+        }
+        this.#cullGroup = d.createBindGroup({ label: 'yali:scene:cull', layout: (occl?.cullPipeline ?? this.#cullPipeline).getBindGroupLayout(0), entries: cullEntries });
+        // The vertex path's draw reads only the camera and materials (instances come as vertex buffers).
+        this.#drawGroups(vertex
+            ? [{ binding: 0, resource: { buffer: this.#camera } }, { binding: 3, resource: { buffer: this.#materialBuf } }, { binding: 18, resource: { buffer: this.#materialExtBuf } }, { binding: 19, resource: (this.#sceneColor ?? this.#noSceneColor).createView() }, ...this.#textureEntries()]
+            : [
+                { binding: 0, resource: { buffer: this.#camera } },
+                { binding: 1, resource: { buffer: this.#instances } },
+                { binding: 2, resource: { buffer: this.#ranges } },
+                { binding: 3, resource: { buffer: this.#materialBuf } },
+                { binding: 18, resource: { buffer: this.#materialExtBuf } },
+                { binding: 19, resource: (this.#sceneColor ?? this.#noSceneColor).createView() },
+                ...this.#textureEntries(),
+            ]);
+        this.#buildShadowGroups();
+        this.#dirtyGroups = false;
+        this.#bundles = null;
+    }
+    /** Every cascade, each into its tile of the atlas, from the same instances and slots as the draw. */
+    #encodeShadows(pass) {
+        const sh = this.#shadows;
+        pass.setVertexBuffer(0, this.#vertexBuf);
+        const vertex = this.path === 'vertex';
+        // Single-sided casters cull back faces; double-sided ones (ADR-0081) draw both, through the
+        // no-cull pipeline once it is built (until then the single-sided one). Blend casts nothing.
+        const double = this.#shadowPipelineDouble && this.#shadowGroupsDouble.length === sh.cascades;
+        // Skinned casters (ADR-0088) draw after the rigid ones, from the skinned pool, through their
+        // own pipelines (until those are built, they cast nothing).
+        const passes = [];
+        for (const two of double ? [false, true] : [false])
+            passes.push([false, two]);
+        if (this.#skinBuf) {
+            if (this.#shadowSkinned && this.#shadowSkinnedGroups.length === sh.cascades)
+                passes.push([true, false]);
+            if (this.#shadowSkinnedDouble && this.#shadowSkinnedDoubleGroups.length === sh.cascades)
+                passes.push([true, true]);
+        }
+        for (let c = 0; c < sh.cascades; c++) {
+            pass.setViewport(c * sh.size, 0, sh.size, sh.size, 0, 1);
+            // Per cascade: the last cascade's clustered casters drew from their own index buffer (ADR-0122).
+            pass.setIndexBuffer(this.#indexBuf, 'uint32');
+            for (const [skinned, twoSided] of passes) {
+                pass.setPipeline(skinned ? (twoSided ? this.#shadowSkinnedDouble : this.#shadowSkinned) : twoSided ? this.#shadowPipelineDouble : this.#shadowPipeline);
+                pass.setBindGroup(0, skinned ? (twoSided ? this.#shadowSkinnedDoubleGroups[c] : this.#shadowSkinnedGroups[c]) : twoSided ? this.#shadowGroupsDouble[c] : this.#shadowGroups[c]);
+                pass.setVertexBuffer(0, skinned ? this.#skinnedVertexBuf : this.#vertexBuf);
+                if (skinned)
+                    pass.setVertexBuffer(vertex ? 2 : 1, this.#skinBuf);
+                const wants = (cls) => !isBlendClass(cls) && isSkinnedClass(cls) === skinned && (skinned ? (cls & 1) === (twoSided ? 1 : 0) : !double || ((cls & 1) === 1) === twoSided);
+                if (this.cull === 'cpu') {
+                    // Only this cascade's casters when the cull partitioned them, else whole slots.
+                    const part = c < this.#cpuCascades;
+                    const d = part ? this.#culledDraws.cascade[c] : this.#cpuDraws;
+                    const cls = part ? this.#culledDraws.cascadeClass[c] : this.#culledDraws.mainClass;
+                    const count = part ? this.#culledDraws.cascadeCount[c] : this.#cpuDrawCount;
+                    for (let i = 0; i < count; i++) {
+                        if (!wants(cls[i]))
+                            continue;
+                        const o = i * 5;
+                        pass.setVertexBuffer(1, this.#cpuBuf, d[o + 3] * CULLED_BYTES, d[o + 4] * CULLED_BYTES);
+                        pass.drawIndexed(d[o], d[o + 4], d[o + 1], d[o + 2], 0);
+                    }
+                    continue;
+                }
+                const list = this.#drawList;
+                const cl = skinned ? null : this.clusters;
+                for (let i = 0; i < list.length; i += 3) {
+                    if (!wants(this.#slotClass[list[i]]))
+                        continue;
+                    // A clustered mesh's finest-LOD casters are drawn as clusters below (ADR-0112).
+                    if (cl && this.#slotLod[list[i]] === 0 && cl.shadowCovers(this.#slotMesh[list[i]]))
+                        continue;
+                    if (vertex)
+                        pass.setVertexBuffer(1, this.#ranges, list[i + 1] * INSTANCE_BYTES, list[i + 2] * INSTANCE_BYTES);
+                    pass.drawIndexedIndirect(this.#args, list[i] * ARGS_BYTES);
+                }
+            }
+            if (this.cull !== 'cpu')
+                this.clusters?.encodeShadow(pass, c);
+        }
+    }
+    /** Encodes the draws (one indirect draw per slot of slot set `set`) on a pass or a bundle encoder. */
+    #encodeDraws(enc, set = 0, part = 'all', layer = 0) {
+        const at = set * this.#slots;
+        const cl = this.clusters;
+        enc.setIndexBuffer(this.#indexBuf, 'uint32');
+        const list = this.#drawList;
+        const vertex = this.path === 'vertex';
+        // Class by class (ADR-0081, ADR-0088): opaque and mask (rigid, then skinned), then blend. A
+        // class whose pipeline is still compiling is skipped for those frames.
+        for (const c of CLASS_ORDER) {
+            if (part !== 'all' && isBlendClass(c) !== (part === 'blend'))
+                continue;
+            let bound = false;
+            for (let i = 0; i < list.length; i += 3) {
+                if (this.#slotClass[list[i]] !== c)
+                    continue;
+                if (cl && this.#slotLod[list[i]] === 0 && cl.covers(this.#slotMesh[list[i]]))
+                    continue;
+                if (!bound) {
+                    const draw = layer ? this.#layerDraw(c) : this.#classDraw(c);
+                    if (!draw || !this.#bindPool(enc, c, vertex ? 2 : 1))
+                        break;
+                    enc.setPipeline(draw[0]);
+                    enc.setBindGroup(0, draw[1]);
+                    bound = true;
+                }
+                if (vertex)
+                    enc.setVertexBuffer(1, this.#ranges, list[i + 1] * INSTANCE_BYTES, list[i + 2] * INSTANCE_BYTES);
+                enc.drawIndexedIndirect(this.#args, (list[i] + at) * ARGS_BYTES);
+            }
+        }
+    }
+    /**
+     * Binds the vertex pool class `c` draws from (ADR-0088): the rigid pool, or the skinned pool and
+     * its skin stream at slot `skinSlot`. False when the skinned pool is not there yet.
+     */
+    #bindPool(enc, c, skinSlot) {
+        if (!isSkinnedClass(c)) {
+            enc.setVertexBuffer(0, this.#vertexBuf);
+            return true;
+        }
+        if (!this.#skinnedVertexBuf || !this.#skinBuf)
+            return false;
+        enc.setVertexBuffer(0, this.#skinnedVertexBuf);
+        enc.setVertexBuffer(skinSlot, this.#skinBuf);
+        return true;
+    }
+    /** The CPU-cull draws: one ordinary indexed draw per non-empty slot, at its range's vertex-buffer offset. */
+    #encodeCulled(pass) {
+        pass.setIndexBuffer(this.#indexBuf, 'uint32');
+        const d = this.#cpuDraws;
+        const cls = this.#culledDraws.mainClass;
+        let draws = 0;
+        for (const c of CLASS_ORDER) {
+            let bound = false;
+            for (let i = 0; i < this.#cpuDrawCount; i++) {
+                if (cls[i] !== c)
+                    continue;
+                if (!bound) {
+                    const draw = this.#classDraw(c);
+                    if (!draw || !this.#bindPool(pass, c, 2))
+                        break;
+                    pass.setPipeline(draw[0]);
+                    pass.setBindGroup(0, draw[1]);
+                    bound = true;
+                }
+                const o = i * 5;
+                pass.setVertexBuffer(1, this.#cpuBuf, d[o + 3] * CULLED_BYTES, d[o + 4] * CULLED_BYTES);
+                pass.drawIndexed(d[o], d[o + 4], d[o + 1], d[o + 2], 0);
+                draws++;
+            }
+        }
+        this.stats.draws = draws;
+    }
+    #ready() {
+        if (this.cull === 'cpu')
+            return this.#cpuDrawCount > 0 && !!this.#cpuBuf && !!this.#drawGroup && !!this.#vertexBuf && !!this.#indexBuf;
+        return this.count > 0 && this.#drawList.length > 0 && !!this.#cullGroup && !!this.#drawGroup && !!this.#vertexBuf && !!this.#indexBuf;
+    }
+    // ── Transmission through the opaque scene (ADR-0099) ─────────────────────────────────────
+    /** Set before `addPasses` when the colour target is the HDR one: blended classes then draw after a copy of the opaque scene. */
+    screenTransmission = false;
+    #sceneColor = null;
+    #noSceneColor;
+    #targetW = 0;
+    #targetH = 0;
+    /** The colour target's size (call before `upload` each frame): the opaque copy follows it. */
+    setTargetSize(width, height) {
+        if (!this.#splitBlend() || (width === this.#targetW && height === this.#targetH))
+            return;
+        this.#targetW = width;
+        this.#targetH = height;
+        this.#sceneColor?.destroy();
+        // A mip chain for the rough-surface blur (ADR-0119): down to 1/64, where roughness 1 is drawn from.
+        const levels = Math.min(7, Math.floor(Math.log2(Math.max(width, height))) + 1);
+        this.#sceneColor = this.device.createTexture({
+            label: 'yali:scene-color',
+            size: [width, height],
+            mipLevelCount: levels,
+            format: 'rgba16float',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+        });
+        this.#mipGroups = [];
+        this.#mipViews = [];
+        this.#buildMips();
+        this.#lit[0] = Number.NaN; // the lighting uniform carries the size
+        this.#dirtyGroups = true;
+    }
+    // The opaque copy's mip chain (ADR-0119): a 2 × 2 box downsample per level, by loads.
+    #mips = null;
+    #mipsBuilding = false;
+    #mipViews = [];
+    #mipGroups = [];
+    #buildMips() {
+        if (this.#mips || this.#mipsBuilding || !this.#cache)
+            return;
+        this.#mipsBuilding = true;
+        const wgsl = `@group(0) @binding(0) var src: texture_2d<f32>;
+@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
+  let p = vec2f(f32((i << 1u) & 2u), f32(i & 2u));
+  return vec4f(p * 2.0 - 1.0, 0.0, 1.0);
+}
+@fragment fn fs(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+  let hi = vec2i(textureDimensions(src)) - 1;
+  let p = vec2i(pos.xy) * 2;
+  let s = textureLoad(src, min(p, hi), 0) + textureLoad(src, min(p + vec2i(1, 0), hi), 0) + textureLoad(src, min(p + vec2i(0, 1), hi), 0) + textureLoad(src, min(p + vec2i(1, 1), hi), 0);
+  return s * 0.25;
+}`;
+        const shader = { hash: 'yali-scene-color-mips-1', wgsl };
+        void this.#cache.render({ label: 'yali:scene-color:mips', vertex: { shader, entryPoint: 'vs' }, fragment: { shader, entryPoint: 'fs', targets: [{ format: 'rgba16float' }] }, primitive: { topology: 'triangle-list' } }).then((p) => {
+            this.#mips = p;
+            this.#lit[0] = Number.NaN; // the lighting uniform says how many levels there are
+        });
+    }
+    /** Fills the opaque copy's levels below the first (the copy's encoder, after the copy). */
+    #encodeMips(encoder) {
+        const t = this.#sceneColor;
+        if (!t || !this.#mips || t.mipLevelCount < 2)
+            return;
+        if (this.#mipViews.length !== t.mipLevelCount) {
+            this.#mipViews = Array.from({ length: t.mipLevelCount }, (_, l) => t.createView({ baseMipLevel: l, mipLevelCount: 1 }));
+            this.#mipGroups = this.#mipViews.slice(0, -1).map((view, l) => this.device.createBindGroup({ label: `yali:scene-color:mip${l}`, layout: this.#mips.getBindGroupLayout(0), entries: [{ binding: 0, resource: view }] }));
+        }
+        for (let l = 1; l < t.mipLevelCount; l++) {
+            const pass = encoder.beginRenderPass({ label: 'scene.copy.mips', colorAttachments: [{ view: this.#mipViews[l], loadOp: 'clear', storeOp: 'store', clearValue: { r: 0, g: 0, b: 0, a: 0 } }] });
+            pass.setPipeline(this.#mips);
+            pass.setBindGroup(0, this.#mipGroups[l - 1]);
+            pass.draw(3);
+            pass.end();
+        }
+    }
+    /** Whether the blended classes draw in their own pass after the opaque copy (the GPU cull with an HDR target). */
+    #splitBlend() {
+        return this.screenTransmission && this.cull === 'gpu';
+    }
+    /** TAA's jitter in clip units, applied to the uploaded view-projection (ADR-0092); null for none. */
+    jitter = null;
+    // ── Cluster culling (ADR-0100) ─────────────────────────────────────────────────────────
+    /** Set by the render plugin from `renderPlugin({ meshlets })`, on the GPU cull's storage path. */
+    clusters = null;
+    #clusterVersion = -1;
+    #slotMesh = new Uint32Array(0);
+    #poolEpoch = 0;
+    /** The finest-LOD slots of this layout (and where their instances are), for the cluster cull. */
+    clusterLayout() {
+        if (this.cull === 'cpu' || this.path !== 'storage' || this.#drawList.length === 0)
+            return null;
+        const list = this.#drawList;
+        const slots = [];
+        for (let i = 0; i < list.length; i += 3)
+            if (this.#slotLod[list[i]] === 0)
+                slots.push({ slot: list[i], mesh: this.#slotMesh[list[i]], start: list[i + 1], n: list[i + 2] });
+        return { key: `${this.stats.layouts}`, slots, sets: this.#occl ? [1, 2] : [0], slots_: this.#slots, region: this.#region };
+    }
+    /** What the cluster passes bind (null until the buffers exist). */
+    clusterSources() {
+        if (!this.#instances || !this.#ranges || !this.#args || !this.#vertexBuf || !this.#groupEntries)
+            return null;
+        const o = this.#occl;
+        return { key: `${this.stats.layouts}:${this.capacity}:${this.#poolEpoch}:${this.#groupsEpoch}`, camera: this.#camera, instances: this.#instances, visible: this.#ranges, args: this.#args, cullParams: this.#params, pool: this.#vertexBuf, drawEntries: entriesFor(this.#groupEntries, 0), occlusion: o ? { params: o.params, view: o.view, version: o.version } : null };
+    }
+    /** The full-shading draw shader, with the app's node materials (the clustered draw extends it). */
+    clusterShader() {
+        return this.#drawShader();
+    }
+    #clusterShadow = null;
+    /** What the clustered shadow casters read this frame (ADR-0112; the planes refitted in place); null when the sun casts nothing. */
+    clusterShadow() {
+        const sh = this.#shadows;
+        if (!sh?.enabled || !this.#casting || this.cull === 'cpu' || this.path !== 'storage')
+            return null;
+        this.#clusterShadow ??= {
+            cascades: sh.cascades,
+            planes: new Float32Array(MAX_CASCADES * 20),
+            light: this.#cameraData.subarray(40, 43),
+            cascadeBuffer: sh.cascadeBuffer,
+            cascadeOffset: SunShadows.offset,
+            cascadeBytes: CASCADE_UNIFORM_BYTES,
+            shader: sceneShadow,
+        };
+        cascadeCullPlanes(sh.params, sh.cascades, this.#clusterShadow.planes, 0);
+        return this.#clusterShadow;
+    }
+    #groupsEpoch = 0;
+    // ── Per-object motion (ADR-0098) ──────────────────────────────────────────────────────
+    #prevInstances = null;
+    #prevPalette = null;
+    #motionWanted = false;
+    /** Bumped when a motion resource is recreated: bind groups that hold one are rebuilt. */
+    motionVersion = 0;
+    /** Whether motion vectors can be drawn here (the GPU cull's storage path). */
+    get motionSupported() {
+        return this.cull === 'gpu' && this.path === 'storage';
+    }
+    /** What the motion pass binds (null until the instances exist, or off this path); keeps last frame's copies from now on. */
+    motionResources() {
+        if (!this.motionSupported || !this.#instances || !this.#ranges || !this.#palette || !this.#vertexBuf)
+            return null;
+        this.#motionWanted = true;
+        this.#prevPools();
+        const size = this.capacity * TRANSFORM_BYTES;
+        if (!this.#prevInstances || this.#prevInstances.size < size) {
+            this.#prevInstances?.destroy();
+            this.#prevInstances = this.device.createBuffer({ label: 'yali:instances:prev', size, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+            this.motionVersion++;
+        }
+        const p = this.#palette;
+        if (!this.#prevPalette || this.#prevPalette.height !== p.height) {
+            this.#prevPalette?.destroy();
+            this.#prevPalette = this.device.createTexture({ label: 'yali:palette:prev', size: [p.width, p.height], format: 'rgba32float', usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST });
+            this.motionVersion++;
+        }
+        // A pool nothing rewrites is its own last frame (no copy, no memory).
+        const prevPool = this.#poolDynamic && this.#prevPool ? this.#prevPool : this.#vertexBuf;
+        const prevSkinnedPool = this.#skinnedDynamic && this.#prevSkinned ? this.#prevSkinned : (this.#skinnedVertexBuf ?? this.#noPool());
+        return { camera: this.#camera, instances: this.#instances, visible: this.#ranges, prevInstances: this.#prevInstances, palette: p, prevPalette: this.#prevPalette, prevPool, prevSkinnedPool };
+    }
+    /**
+     * Last frame's copy of each pool something rewrites (ADR-0124): made (from the pool as it is now, so
+     * before a pending write lands) when missing or when the pool was recreated; kept by `recordMotionCopies`.
+     */
+    #prevPools() {
+        const copy = (pool, prev, label) => {
+            if (!pool)
+                return prev;
+            if (prev && prev.size === pool.size && this.#prevOf.get(prev) === pool)
+                return prev;
+            prev?.destroy();
+            // VERTEX too: the masked motion stage reads last frame's position as a vertex buffer (ADR-0133).
+            const made = this.device.createBuffer({ label, size: pool.size, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.VERTEX });
+            this.#prevOf.set(made, pool);
+            const e = this.device.createCommandEncoder();
+            e.copyBufferToBuffer(pool, 0, made, 0, pool.size);
+            this.device.queue.submit([e.finish()]);
+            this.motionVersion++;
+            return made;
+        };
+        if (this.#poolDynamic)
+            this.#prevPool = copy(this.#vertexBuf, this.#prevPool, 'yali:geometry:vertices:prev');
+        if (this.#skinnedDynamic)
+            this.#prevSkinned = copy(this.#skinnedVertexBuf, this.#prevSkinned, 'yali:geometry:skinned:prev');
+    }
+    /** A stand-in for a skinned pool that does not exist (the skinned motion pipeline still binds one). */
+    #noPool() {
+        this.#emptyPool ??= this.device.createBuffer({ label: 'yali:geometry:none', size: 32, usage: GPUBufferUsage.STORAGE });
+        return this.#emptyPool;
+    }
+    #poolDynamic = false;
+    #skinnedDynamic = false;
+    #prevPool = null;
+    #prevSkinned = null;
+    #emptyPool = null;
+    /** Which pool each copy was made from (a recreated pool needs a new copy). */
+    #prevOf = new WeakMap();
+    /** The bind-group generation of the instances, the visible ranges and the palette (motion rebuilds its groups on a change). */
+    get motionKey() {
+        return `${this.motionVersion}:${this.stats.layouts}:${this.capacity}:${this.#palette?.height ?? 0}:${this.#poolEpoch}:${this.#skinnedVertexBuf?.size ?? 0}`;
+    }
+    /**
+     * Draws every opaque instance of the view's slot sets (both passes under occlusion) with the
+     * motion pipelines: `rigid`, and `skinned` for the skinned classes (pipeline, bind group). With
+     * `clustered` (the motion pass's shader and rigid entries), meshes the view drew as clusters draw
+     * those same clusters once their pipeline is built (ADR-0112), whole until then.
+     */
+    encodeMotion(pass, rigid, skinned, clustered, motionParams) {
+        if (this.cull === 'cpu' || !this.#ready())
+            return;
+        // Meshes added since: their masked classes' pipelines too.
+        if (this.#maskMotionFormat && (this.#maskMotionVersion !== this.#store.version || this.#maskMotionMaterials !== this.#materials.blendMotion)) {
+            this.#maskMotionVersion = this.#store.version;
+            this.#maskMotionMaterials = this.#materials.blendMotion;
+            this.prepareMaskMotion(this.#maskMotionFormat);
+        }
+        const cl = clustered && this.clusters?.motionCovers(clustered) ? this.clusters : null;
+        pass.setIndexBuffer(this.#indexBuf, 'uint32');
+        const list = this.#drawList;
+        const sets = this.#occl ? [1, 2] : [0];
+        let bound = null;
+        let pool = -1;
+        for (let i = 0; i < list.length; i += 3) {
+            const c = this.#slotClass[list[i]];
+            // Blended surfaces draw motion only through their own stage, while a material asks (ADR-0133).
+            const blend = isBlendClass(c);
+            if (blend && !(motionParams && this.#materials.blendMotion > 0))
+                continue;
+            if (cl && this.#slotLod[list[i]] === 0 && cl.covers(this.#slotMesh[list[i]]))
+                continue;
+            // Masked classes through their alpha test once built (ADR-0124), else as solid as the rest.
+            const mask = ((c % 6) >> 1 === 1 || blend) && motionParams ? this.#maskMotionFor(c, motionParams) : null;
+            if (blend && !mask)
+                continue;
+            const pp = mask ?? (isSkinnedClass(c) ? skinned : rigid);
+            if (!pp)
+                continue;
+            const skin = isSkinnedClass(c) ? 1 : 0;
+            if (pool !== skin) {
+                if (!this.#bindPool(pass, c, 1))
+                    continue;
+                pool = skin;
+            }
+            // The masked stage's last-frame positions (ADR-0133): after the pool (and the skin buffer).
+            if (mask)
+                pass.setVertexBuffer(skin ? 2 : 1, skin ? (this.#skinnedDynamic && this.#prevSkinned ? this.#prevSkinned : this.#skinnedVertexBuf) : this.#poolDynamic && this.#prevPool ? this.#prevPool : this.#vertexBuf);
+            if (bound !== pp[0]) {
+                pass.setPipeline(pp[0]);
+                pass.setBindGroup(0, pp[1]);
+                bound = pp[0];
+            }
+            for (const s of sets)
+                pass.drawIndexedIndirect(this.#args, (list[i] + s * this.#slots) * ARGS_BYTES);
+        }
+        if (cl)
+            cl.encodeMotion(pass, clustered);
+    }
+    // ── Motion for alpha-masked cut-outs (ADR-0124) ─────────────────────────────────────────────
+    /**
+     * Starts building the masked classes' motion pipelines over the draw shader (`vs_motion_mask`,
+     * `fs_motion_mask`: the material's alpha test), for a motion target of `format`: the motion pass calls
+     * it when it builds its graph, so `drawClassesReady()` awaits them (trap 134). Classes present only.
+     */
+    prepareMaskMotion(format) {
+        this.#maskMotionFormat = format;
+        if (!this.#cache || !this.motionSupported)
+            return;
+        for (const e of this.#store.entries) {
+            const c = e.drawClass;
+            // Masked classes, and blended ones while a material asks for their motion (ADR-0133).
+            const blend = isBlendClass(c);
+            if (((c % 6) >> 1 !== 1 && !(blend && this.#materials.blendMotion > 0)) || this.#maskMotion[c] || this.#maskMotionBuilding.has(c))
+                continue;
+            const skinned = isSkinnedClass(c);
+            const build = this.#cache
+                .render({
+                label: `yali:motion:mask:c${c}`,
+                vertex: {
+                    shader: this.#drawShader(),
+                    entryPoint: skinned ? 'vs_motion_mask_skinned' : 'vs_motion_mask',
+                    buffers: [
+                        {
+                            arrayStride: VERTEX_BYTES,
+                            attributes: [
+                                { shaderLocation: 0, offset: 0, format: 'float32x3' },
+                                { shaderLocation: 1, offset: 12, format: 'float32x3' },
+                                { shaderLocation: 5, offset: 24, format: 'float32x2' },
+                            ],
+                        },
+                        ...(skinned ? [SKIN_LAYOUT] : []),
+                        // Last frame's position (ADR-0133), from last frame's copy of the pool (or the pool itself).
+                        { arrayStride: VERTEX_BYTES, attributes: [{ shaderLocation: 8, offset: 0, format: 'float32x3' }] },
+                    ],
+                },
+                fragment: { shader: this.#drawShader(), entryPoint: blend ? 'fs_motion_blend' : 'fs_motion_mask', targets: [{ format }] },
+                primitive: { topology: 'triangle-list', cullMode: c & 1 ? 'none' : 'back', frontFace: 'ccw' },
+                depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'greater' },
+            })
+                .then((p) => {
+                this.#maskMotionBuilding.delete(c);
+                this.#maskMotion[c] = p;
+                this.#maskMotionGroups[c] = null;
+            }, (err) => {
+                this.#maskMotionBuilding.delete(c);
+                console.warn(`[yali] motion: ${blend ? `the blended class ${c} draws no motion` : `the masked class ${c} draws its motion without its alpha test`} (${err instanceof Error ? err.message : String(err)}).`);
+            });
+            this.#maskMotionBuilding.set(c, build);
+        }
+    }
+    #maskMotionFormat = null;
+    #maskMotion = [];
+    #maskMotionGroups = [];
+    #maskMotionBuilding = new Map();
+    #maskMotionKey = '';
+    #maskMotionVersion = -1;
+    #maskMotionMaterials = 0;
+    /** Class `c`'s masked motion pipeline and group (the draw's entries, the motion uniform, last frame's transforms and palette), when built. */
+    #maskMotionFor(c, params) {
+        const p = this.#maskMotion[c];
+        if (!p || !this.#groupEntries || !this.#prevInstances || !this.#prevPalette)
+            return null;
+        const key = `${this.motionKey}:${this.#groupsEpoch}:${this.#prevInstances.size}`;
+        if (key !== this.#maskMotionKey) {
+            this.#maskMotionKey = key;
+            this.#maskMotionGroups.fill(null);
+        }
+        let g = this.#maskMotionGroups[c];
+        if (!g) {
+            g = this.device.createBindGroup({
+                label: `yali:motion:mask:c${c}`,
+                layout: p.getBindGroupLayout(0),
+                entries: [
+                    ...entriesFor(this.#groupEntries, c),
+                    { binding: 20, resource: { buffer: params } },
+                    { binding: 21, resource: { buffer: this.#prevInstances } },
+                    ...(isSkinnedClass(c) ? [{ binding: 22, resource: this.#prevPalette.createView() }] : []),
+                ],
+            });
+            this.#maskMotionGroups[c] = g;
+        }
+        return [p, g];
+    }
+    /** What the motion pass reads besides the visible instances: the cluster lists it redraws (ADR-0112). */
+    get motionReads() {
+        if (!this.clusters)
+            return [];
+        return this.#occl ? ['scene.clusterList1', 'scene.clusterList2'] : ['scene.clusterList'];
+    }
+    /** After the frame's passes: this frame's transforms and palette become last frame's (motion only). */
+    recordMotionCopies(encoder) {
+        if (!this.#motionWanted || !this.#instances || !this.#prevInstances)
+            return;
+        encoder.copyBufferToBuffer(this.#instances, 0, this.#prevInstances, 0, Math.min(this.capacity * TRANSFORM_BYTES, this.#prevInstances.size));
+        const p = this.#palette;
+        if (p && this.#prevPalette && this.#prevPalette.height === p.height)
+            encoder.copyTextureToTexture({ texture: p }, { texture: this.#prevPalette }, [p.width, p.height]);
+        // The pools something rewrites (ADR-0124): this frame's vertices become last frame's.
+        for (const [pool, prev, on] of [[this.#vertexBuf, this.#prevPool, this.#poolDynamic], [this.#skinnedVertexBuf, this.#prevSkinned, this.#skinnedDynamic]]) {
+            if (on && pool && prev && prev.size === pool.size && this.#prevOf.get(prev) === pool)
+                encoder.copyBufferToBuffer(pool, 0, prev, 0, pool.size);
+        }
+    }
+    /**
+     * Adds `scene.cull`, `scene.shadow` (with shadows) and `scene.draw` to the graph. `keepDepth`
+     * stores the depth after the draw, for a later pass that samples it (TAA).
+     */
+    addPasses(graph, color, depth, keepDepth = false) {
+        const sh = this.#shadows;
+        graph.addPass({
+            name: 'scene.cull',
+            kind: 'compute',
+            writes: ['scene.visible'],
+            execute: (pass) => {
+                if (this.cull === 'cpu' || !this.#ready())
+                    return;
+                if (this.#occl && this.#occl.version !== this.#occlVersion)
+                    this.#bindGroups();
+                pass.setPipeline(this.#occl?.cullPipeline ?? this.#cullPipeline);
+                pass.setBindGroup(0, this.#cullGroup);
+                pass.dispatchWorkgroups(Math.ceil(this.count / 64));
+            },
+        });
+        // The clusters are culled now and drawn in scene.draw: all of them without occlusion (ADR-0100),
+        // under it those of the instances visible last frame, against its pyramid (ADR-0109).
+        this.clusters?.addCull(graph, 'scene.visible', this.#occl ? 1 : 0);
+        if (sh?.enabled) {
+            // Clustered casters (ADR-0112): slot set 0's clustered meshes culled per cascade, at the view's cut.
+            this.clusters?.addShadowCull(graph, 'scene.visible');
+            graph.importTexture('shadow.atlas', () => sh.view);
+            graph.addPass({
+                name: 'scene.shadow',
+                kind: 'render',
+                reads: this.clusters ? ['scene.visible', 'scene.clusterShadow'] : ['scene.visible'],
+                writes: ['scene.shadow'],
+                depth: { target: 'shadow.atlas', clear: 0, store: true },
+                execute: (pass) => {
+                    if (!this.#ready() || this.#shadowGroups.length !== sh.cascades || !this.#casting)
+                        return;
+                    this.#encodeShadows(pass);
+                },
+            });
+        }
+        graph.addPass({
+            name: 'scene.draw',
+            kind: 'render',
+            reads: [...(sh?.enabled ? ['scene.visible', 'scene.lights', 'scene.shadow'] : ['scene.visible', 'scene.lights']), ...(this.clusters ? [this.#occl ? 'scene.clusterList1' : 'scene.clusterList'] : [])],
+            color: { target: color, clear: this.#clear },
+            // Occlusion's pyramid and second pass read and continue this depth.
+            depth: { target: depth, clear: 0, store: keepDepth || !!this.#occl || this.#splitBlend() },
+            execute: (pass) => {
+                this.#encodeScene(pass, this.#occl ? 1 : 0, this.#splitBlend() ? 'opaque' : 'all');
+                this.clusters?.encodeDraw(pass, this.#occl ? 1 : 0);
+                if (!this.#occl && !this.#splitBlend())
+                    for (let i = 0; i < this.overlays.length; i++)
+                        this.overlays[i](pass);
+            },
+        });
+        const occl = this.#occl;
+        if (occl)
+            this.#addOcclusionPasses(graph, color, depth, keepDepth, occl);
+        if (!this.#splitBlend())
+            return;
+        // The blended classes after a copy of the opaque scene (ADR-0099): transmission samples it.
+        graph.addPass({
+            name: 'scene.copy',
+            kind: 'encoder',
+            reads: occl ? ['scene.opaque2'] : [],
+            writes: ['scene.opaque'],
+            execute: (encoder, ctx) => {
+                if (!this.#sceneColor || this.#sceneColor.width !== ctx.width || this.#sceneColor.height !== ctx.height)
+                    return;
+                encoder.copyTextureToTexture({ texture: ctx.texture(color) }, { texture: this.#sceneColor }, [ctx.width, ctx.height]);
+                this.#encodeMips(encoder);
+            },
+        });
+        graph.addPass({
+            name: 'scene.transparent',
+            kind: 'render',
+            reads: ['scene.opaque'],
+            color: { target: color, clear: this.#clear, load: true },
+            // Stored for the second layer's pass (ADR-0125), which tests against it.
+            depth: { target: depth, clear: 0, store: true, load: true },
+            execute: (pass) => {
+                if (occl) {
+                    this.#encodeScene(pass, 1, 'blend');
+                    this.#encodeScene(pass, 2, 'blend');
+                }
+                else
+                    this.#encodeScene(pass, 0, 'blend');
+                for (let i = 0; i < this.overlays.length; i++)
+                    this.overlays[i](pass);
+            },
+        });
+        // The second transparent layer (ADR-0125): the scene with layer 0's surfaces copied again, then the
+        // layer-1 surfaces refracting that copy. Both do nothing while no material is in layer 1.
+        graph.addPass({
+            name: 'scene.copyLayer',
+            kind: 'encoder',
+            writes: ['scene.layerCopy'],
+            execute: (encoder, ctx) => {
+                if (!this.#layered() || !this.#ensureLayerCopy(ctx.width, ctx.height))
+                    return;
+                encoder.copyTextureToTexture({ texture: ctx.texture(color) }, { texture: this.#layerColor }, [ctx.width, ctx.height]);
+                this.#encodeLayerMips(encoder);
+            },
+        });
+        graph.addPass({
+            name: 'scene.transparent2',
+            kind: 'render',
+            reads: ['scene.layerCopy'],
+            color: { target: color, clear: this.#clear, load: true },
+            depth: { target: depth, clear: 0, store: keepDepth, load: true },
+            execute: (pass) => {
+                if (!this.#layered() || !this.#layerColor)
+                    return;
+                if (occl) {
+                    this.#encodeScene(pass, 1, 'blend', 1);
+                    this.#encodeScene(pass, 2, 'blend', 1);
+                }
+                else
+                    this.#encodeScene(pass, 0, 'blend', 1);
+            },
+        });
+    }
+    // ── The second transparent layer (ADR-0125) ───────────────────────────────────────────────
+    /** Whether layer 1 draws: a material is in it, and the blended classes draw after the opaque copy. */
+    #layered() {
+        return this.#materials.layered > 0 && this.#splitBlend() && !!this.#sceneColor;
+    }
+    /** The layer copy (the opaque copy's size and levels) and its lighting uniform; false until they exist. */
+    #ensureLayerCopy(width, height) {
+        const src = this.#sceneColor;
+        if (!src || src.width !== width || src.height !== height)
+            return false;
+        if (!this.#layerColor || this.#layerColor.width !== width || this.#layerColor.height !== height) {
+            this.#layerColor?.destroy();
+            this.#layerColor = this.device.createTexture({ label: 'yali:scene-color:layer', size: [width, height], mipLevelCount: src.mipLevelCount, format: 'rgba16float', usage: src.usage });
+            this.#layerMipViews = [];
+            this.#layerMipGroups = [];
+            this.#layerGroups = [];
+            this.#lighting2 ??= this.device.createBuffer({ label: 'yali:lighting:layer', size: 192, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+            this.#lit[0] = Number.NaN; // the second lighting uniform is written with the first
+            this.#bundles = null;
+        }
+        return true;
+    }
+    /** The layer copy's levels below the first (as `#encodeMips` the opaque copy's). */
+    #encodeLayerMips(encoder) {
+        const t = this.#layerColor;
+        if (!t || !this.#mips || t.mipLevelCount < 2)
+            return;
+        if (this.#layerMipViews.length !== t.mipLevelCount) {
+            this.#layerMipViews = Array.from({ length: t.mipLevelCount }, (_, l) => t.createView({ baseMipLevel: l, mipLevelCount: 1 }));
+            this.#layerMipGroups = this.#layerMipViews.slice(0, -1).map((view, l) => this.device.createBindGroup({ label: `yali:scene-color:layer:mip${l}`, layout: this.#mips.getBindGroupLayout(0), entries: [{ binding: 0, resource: view }] }));
+        }
+        for (let l = 1; l < t.mipLevelCount; l++) {
+            const pass = encoder.beginRenderPass({ label: 'scene.copyLayer.mips', colorAttachments: [{ view: this.#layerMipViews[l], loadOp: 'clear', storeOp: 'store', clearValue: { r: 0, g: 0, b: 0, a: 0 } }] });
+            pass.setPipeline(this.#mips);
+            pass.setBindGroup(0, this.#layerMipGroups[l - 1]);
+            pass.draw(3);
+            pass.end();
+        }
+    }
+    /** Class `c`'s draw in layer 1's pass: its pipeline with the layer uniform and the layer copy bound. */
+    #layerDraw(c) {
+        const ps = this.#classPipelines[c];
+        if (!ps || !this.#groupEntries || !this.#lighting2 || !this.#layerColor)
+            return null;
+        if (this.#layerGroupsEpoch !== this.#groupsEpoch) {
+            this.#layerGroupsEpoch = this.#groupsEpoch;
+            this.#layerGroups = [];
+        }
+        const level = this.#activeLevel % this.#baseLevels;
+        let gs = this.#layerGroups[c];
+        if (!gs || gs.length !== ps.length) {
+            const view = this.#layerColor.createView();
+            const entries = entriesFor(this.#groupEntries, c).map((e) => (e.binding === 7 ? { binding: 7, resource: { buffer: this.#lighting2 } } : e.binding === 19 ? { binding: 19, resource: view } : e));
+            gs = ps.map((p, i) => this.device.createBindGroup({ label: `yali:scene:draw:layer:c${c}:${i}`, layout: p.getBindGroupLayout(0), entries }));
+            this.#layerGroups[c] = gs;
+        }
+        return [ps[level], gs[level]];
+    }
+    #layerColor = null;
+    #lighting2 = null;
+    #layerMipViews = [];
+    #layerMipGroups = [];
+    #layerGroups = [];
+    #layerGroupsEpoch = -1;
+    #addOcclusionPasses(graph, color, depth, keepDepth, occl) {
+        // Occlusion's second pass (ADR-0095): the pyramid from pass 1's depth, the held-back
+        // instances against it, and what turned out visible drawn over pass 1.
+        occl.addPass(graph, depth);
+        graph.addPass({
+            name: 'scene.recheck',
+            kind: 'compute',
+            reads: ['scene.hzb'],
+            writes: ['scene.visible2'],
+            execute: (pass) => {
+                if (!this.#ready() || !this.#recheckGroup)
+                    return;
+                if (occl.version !== this.#occlVersion)
+                    this.#bindGroups();
+                pass.setPipeline(occl.recheckPipeline);
+                pass.setBindGroup(0, this.#recheckGroup);
+                pass.dispatchWorkgroups(Math.ceil(this.count / 64));
+            },
+        });
+        const split = this.#splitBlend();
+        // Under occlusion pass 2's clusters and those pass 1 held back, against this pyramid (ADR-0109).
+        this.clusters?.addCull(graph, 'scene.visible2', 2);
+        graph.addPass({
+            name: 'scene.draw2',
+            kind: 'render',
+            reads: this.clusters ? ['scene.visible2', 'scene.clusterList2'] : ['scene.visible2'],
+            ...(split ? { writes: ['scene.opaque2'] } : {}),
+            color: { target: color, clear: this.#clear, load: true },
+            depth: { target: depth, clear: 0, store: keepDepth || split, load: true },
+            execute: (pass) => {
+                this.#encodeScene(pass, 2, split ? 'opaque' : 'all');
+                this.clusters?.encodeDraw(pass, 2);
+                if (!split)
+                    for (let i = 0; i < this.overlays.length; i++)
+                        this.overlays[i](pass);
+            },
+        });
+    }
+    /**
+     * Drawn at the end of `scene.draw`, after every draw class, into the same colour and depth
+     * targets (debug lines, ADR-0087). Each gets the pass encoder.
+     */
+    overlays = [];
+    #encodeScene(pass, set = 0, part = 'all', layer = 0) {
+        if (set < 2 && part !== 'blend')
+            this.stats.draws = 0;
+        if (!this.#ready())
+            return;
+        if (this.cull === 'cpu')
+            return this.#encodeCulled(pass);
+        if (part !== 'blend')
+            this.stats.draws += this.#drawList.length / 3;
+        if (!this.useBundles)
+            return this.#encodeDraws(pass, set, part, layer);
+        // The clusters covering a new mesh change what the recorded draws skip.
+        if (this.clusters && this.clusters.version !== this.#clusterVersion) {
+            this.#clusterVersion = this.clusters.version;
+            this.#bundles = null;
+        }
+        if (!this.#bundles)
+            this.#bundles = new Map();
+        const key = `${set}:${part}:${layer}`;
+        let b = this.#bundles.get(key);
+        if (!b) {
+            const enc = this.device.createRenderBundleEncoder({ label: `yali:scene:bundle:${key}`, colorFormats: [this.#format], depthStencilFormat: 'depth32float' });
+            this.#encodeDraws(enc, set, part, layer);
+            b = [enc.finish()];
+            this.#bundles.set(key, b);
+        }
+        pass.executeBundles(b);
+    }
+    /** The colour format the scene draws into (an overlay's pipeline must match it). */
+    get format() {
+        return this.#format;
+    }
+    /** The rigid vertex pool (`MESH_VERTEX_FLOATS` f32 per vertex; STORAGE): GPU deformables write their meshes' vertices into it (ADR-0101). */
+    get vertexPool() {
+        // Whoever takes the pool writes it on the GPU (the cloth, ADR-0101): motion keeps last frame's copy.
+        this.#poolDynamic = true;
+        return this.#vertexBuf;
+    }
+    /** The index pool (u32; COPY_DST): a torn cloth copies its triangles over its mesh's (ADR-0104). */
+    get indexPool() {
+        return this.#indexBuf;
+    }
+    /** Records this frame's staged instance copy and the indirect-argument reset (call first on the frame's encoder). */
+    recordUpload(encoder) {
+        if (this.#instances)
+            this.#staging?.record(encoder, this.#instances);
+        this.#occl?.record(encoder);
+        if (this.#argsBytes > 0 && this.#argsTemplate && this.#args)
+            encoder.copyBufferToBuffer(this.#argsTemplate, 0, this.#args, 0, this.#argsBytes);
+    }
+    /** Call after `queue.submit`: recycles the staging buffers. */
+    afterSubmit() {
+        this.#staging?.recycle();
+        this.#occl?.afterSubmit();
+    }
+    /** Call after recording: every 30 frames, copies the draw args out to count the drawn instances. */
+    afterPasses(encoder) {
+        this.#frame++;
+        if (this.cull === 'cpu')
+            return false;
+        if (this.#readbackBusy || this.#frame % 30 !== 0 || !this.#readback || !this.#args || this.#argsBytes === 0)
+            return false;
+        if (this.#readback.size < this.#argsBytes)
+            return false;
+        encoder.copyBufferToBuffer(this.#args, 0, this.#readback, 0, this.#argsBytes);
+        this.#readbackBusy = true;
+        this.#readbackLayout = this.stats.layouts;
+        return true;
+    }
+    /** The layout the pending readback was copied under (a later layout's slots differ). */
+    #readbackLayout = 0;
+    /** Call after submit when `afterPasses` returned true. */
+    collect() {
+        const rb = this.#readback;
+        const bytes = this.#argsBytes;
+        const layout = this.#readbackLayout;
+        void rb.mapAsync(GPUMapMode.READ, 0, bytes).then(() => {
+            const a = new Uint32Array(rb.getMappedRange(0, bytes));
+            let n = 0;
+            // Counts from an older layout are kept out of the per-slot table: its slots meant other LODs.
+            const bySlot = layout === this.stats.layouts ? this.#drawnBySlot : null;
+            // Under occlusion, the view's two sets (set 0 holds the shadow casters).
+            const slots = this.#occl ? this.#slots : 0;
+            if (bySlot)
+                bySlot.fill(0);
+            for (let s = 0, i = 1; i < a.length; s++, i += ARGS_WORDS) {
+                if (slots && s < slots)
+                    continue;
+                n += a[i];
+                const slot = slots ? s % slots : s;
+                if (bySlot && slot < bySlot.length)
+                    bySlot[slot] += a[i];
+            }
+            this.visible = n;
+            rb.unmap();
+            this.#readbackBusy = false;
+        }, () => {
+            this.#readbackBusy = false;
+        });
+    }
+    /** Instances drawn at each LOD (index 0 = full detail), from the last readback. A diagnostic: it allocates. */
+    drawnByLod() {
+        if (this.cull === 'cpu') {
+            let last = 0;
+            for (let l = 0; l < 8; l++)
+                if (this.#cpuByLod[l])
+                    last = l + 1;
+            return Array.from(this.#cpuByLod.subarray(0, Math.max(1, last)));
+        }
+        const out = [];
+        const bySlot = this.#drawnBySlot;
+        for (let s = 0; s < bySlot.length && s < this.#slotLod.length; s++)
+            out[this.#slotLod[s]] = (out[this.#slotLod[s]] ?? 0) + bySlot[s];
+        return Array.from(out, (v) => v ?? 0);
+    }
+    /** Bytes of the per-instance and layout GPU buffers, for the memory counter. */
+    get gpuBytes() {
+        if (this.#destroyed)
+            return 0;
+        let n = 0;
+        for (const b of this.#owned())
+            n += b?.size ?? 0;
+        return n + (this.#staging?.bytes ?? 0);
+    }
+    #owned() {
+        return [this.#camera, this.#params, this.#materialBuf, this.#materialExtBuf, this.#lightingBuf, this.#vertexBuf, this.#indexBuf, this.#instances, this.#meshInfo, this.#argsTemplate, this.#args, this.#ranges, this.#readback, this.#cpuBuf, this.#skinnedVertexBuf, this.#skinBuf];
+    }
+    /** GPU buffers this renderer currently owns (for the dispose leak check). */
+    get liveBuffers() {
+        return this.#destroyed ? 0 : this.#owned().filter(Boolean).length + (this.#staging?.liveBuffers ?? 0);
+    }
+    /** Destroys every GPU buffer this renderer owns. */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        for (const b of this.#owned())
+            b?.destroy();
+        this.#occl?.destroy();
+        this.#sceneColor?.destroy();
+        this.#noSceneColor.destroy();
+        this.#prevInstances?.destroy();
+        this.#prevPalette?.destroy();
+        this.#layerColor?.destroy();
+        this.#lighting2?.destroy();
+        this.#prevPool?.destroy();
+        this.#prevSkinned?.destroy();
+        this.#emptyPool?.destroy();
+        this.#palette?.destroy();
+        this.#staging?.destroy();
+    }
+}
+function fnv1a(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+function nextPow2(n) {
+    return n <= 1 ? 1 : 2 ** Math.ceil(Math.log2(n));
+}
+//# sourceMappingURL=scene.js.map