@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/meshlets.js

@@ -0,0 +1,1040 @@
+// Cluster (meshlet) culling, `@yali-engine/render/meshlets` (ADR-0100): an entry of its own, so a page
+// that never asks for it carries none of its code, its shaders or meshoptimizer's clusterizer.
+import { MeshoptClusterizer } from 'meshoptimizer/clusterizer';
+import { MeshoptSimplifier } from 'meshoptimizer/simplifier';
+import { YaliError } from '@yali-engine/core';
+import { CLUSTER_BYTES, CLUSTER_WORDS, packClusters } from "./cluster-build.js";
+import { decodeClusterPage, PAGE_WORDS } from "./cluster-pages.js";
+import { ClusterResidency } from "./cluster-stream.js";
+import { clusterRequest } from "./meshlets-decoder.js";
+/** The hierarchy builder (ADR-0111), now in `cluster-build.ts` (ADR-0113). */
+export { buildClusterLod, packClusters } from "./cluster-build.js";
+import { sceneClusters } from "./post-shaders.gen.js";
+/** Whole files fetched when a server ignored `Range` (served once, sliced after). */
+const wholeFiles = new Map();
+/** The default page fetch: one `Range` request; a server that answers 200 sends the file once, kept and sliced. */
+async function rangeFetch(url, offset, length) {
+    const whole = wholeFiles.get(url);
+    if (whole)
+        return (await whole).subarray(offset, offset + length);
+    const r = await fetch(url, { headers: { Range: `bytes=${offset}-${offset + length - 1}` } });
+    if (r.status === 206)
+        return new Uint8Array(await r.arrayBuffer());
+    if (r.ok) {
+        console.warn(`[yali] meshlets: ${url} ignored the Range header; its whole file is kept in memory. Serve it from a server that answers Range (206).`);
+        const all = r.arrayBuffer().then((b) => new Uint8Array(b));
+        wholeFiles.set(url, all);
+        return (await all).subarray(offset, offset + length);
+    }
+    throw new YaliError('PAGE_FETCH', `Fetching cluster pages from ${url} answered ${r.status}.`, 'Serve the <name>.pages.bin that yali convert wrote next to the GLB.');
+}
+/** The cluster cull without the page bits (devices with 8 storage buffers a stage): `note_pages` emptied, so the binding is unused. */
+export function withoutPageBits(s) {
+    const re = /fn note_pages\(index: u32, cl: Cluster\) \{[\s\S]*?\n\}\nfn emit\(/;
+    if (!re.test(s.wgsl))
+        throw new YaliError('SHADER_SHAPE', 'The cluster cull has no note_pages to remove.', 'Keep note_pages directly before emit in shaders/scene/clusters.wesl.');
+    return { hash: `${s.hash}-nobits`, wgsl: s.wgsl.replace(re, 'fn note_pages(index: u32, cl: Cluster) {\n}\nfn emit(') };
+}
+/**
+ * Cluster culling for big meshes (ADR-0100): pass it as `renderPlugin({ meshlets: meshlets() })`.
+ *
+ * @example
+ * import { meshlets } from '@yali-engine/render/meshlets';
+ * renderPlugin({ canvas, meshlets: meshlets({ minTriangles: 8192 }) });
+ */
+export function meshlets(options = {}) {
+    return {
+        options,
+        async create(device, scene, store) {
+            await MeshoptClusterizer.ready;
+            if (options.lod)
+                await MeshoptSimplifier.ready;
+            return new ClusterRenderer(device, scene, store, options);
+        },
+    };
+}
+/** Index stride per visible-list slot (`SLOT` in clusters.wesl). */
+const SLOT = 128;
+/** The cluster record and the pool, clusters and local vertices, as the appended vertex stages read them. */
+const CLUSTER_SOURCES = `
+struct ClusterRec { center: vec3f, radius: f32, apex: vec3f, cutoff: f32, axis: vec3f, base_vertex: u32, vert_offset: u32, tri_offset: u32, tri_count: u32, flags: u32, self_sphere: vec4f, parent_sphere: vec4f, self_error: f32, parent_error: f32, pad0: vec2f, pad1: vec4f }
+@group(0) @binding(20) var<storage, read> cl_pool: array<f32>;
+@group(0) @binding(21) var<storage, read> cl_clusters: array<ClusterRec>;
+@group(0) @binding(22) var<storage, read> cl_vertices: array<u32>;
+`;
+/** Vertex pulling for the clustered draw: appended to the scene's draw shader. */
+const CLUSTER_DRAW = `${CLUSTER_SOURCES}
+@group(0) @binding(24) var<storage, read> cl_visible: array<vec4u>;
+@vertex fn vs_cluster(@builtin(vertex_index) vi: u32, @builtin(instance_index) base: u32) -> VertexOut {
+  let rec = cl_visible[base + vi / ${SLOT}u];
+  let cl = cl_clusters[rec.y];
+  let v = (cl_vertices[cl.vert_offset + vi % ${SLOT}u] + cl.base_vertex) * 8u;
+  return shade(load_instance(rec.x), vec3f(cl_pool[v], cl_pool[v + 1u], cl_pool[v + 2u]), vec3f(cl_pool[v + 3u], cl_pool[v + 4u], cl_pool[v + 5u]), vec2f(cl_pool[v + 6u], cl_pool[v + 7u]));
+}
+`;
+/**
+ * The motion pass over the clusters the view drew (ADR-0112): the same visible lists and compacted
+ * indices, so motion covers exactly the drawn surface. Appended to the motion shader (`place`,
+ * `pose_now`, `pose_then` there).
+ */
+const CLUSTER_MOTION = `${CLUSTER_SOURCES}
+@group(0) @binding(24) var<storage, read> cl_visible: array<vec4u>;
+@vertex fn vs_cluster_motion(@builtin(vertex_index) vi: u32, @builtin(instance_index) base: u32) -> Out {
+  let rec = cl_visible[base + vi / ${SLOT}u];
+  let cl = cl_clusters[rec.y];
+  let v = (cl_vertices[cl.vert_offset + vi % ${SLOT}u] + cl.base_vertex) * 8u;
+  let p = vec3f(cl_pool[v], cl_pool[v + 1u], cl_pool[v + 2u]);
+  return place(pose_now(rec.x), pose_then(rec.x), p, vec3f(prev_pool[v], prev_pool[v + 1u], prev_pool[v + 2u]));
+}
+`;
+/** Vertices per clustered caster instance: the most triangles a cluster has, three corners each. */
+const SHADOW_VERTICES = 124 * 3;
+/**
+ * Clustered shadow casters (ADR-0112): one instance per surviving cluster, pulling each corner through
+ * its triangle bytes; corners past them collapse to a point. Appended to the scene's shadow shader
+ * (`cascade`, `instances`, `shadow_clip` there). (ADR-0122's indexed casters were removed, ADR-0139.)
+ */
+const CLUSTER_SHADOW = `${CLUSTER_SOURCES}
+@group(0) @binding(23) var<storage, read> cl_triangles: array<u32>;
+@group(0) @binding(24) var<storage, read> cl_casters: array<vec4u>;
+@vertex fn vs_shadow_cluster(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> @builtin(position) vec4f {
+  let rec = cl_casters[ii];
+  let cl = cl_clusters[rec.y];
+  if (vi / 3u >= cl.tri_count) {
+    return vec4f(0.0);
+  }
+  let b = cl.tri_offset + vi;
+  let local = (cl_triangles[b / 4u] >> ((b % 4u) * 8u)) & 0xffu;
+  let v = (cl_vertices[cl.vert_offset + local] + cl.base_vertex) * 8u;
+  let a = bitcast<vec4f>(instances[2u * rec.x]);
+  let q = bitcast<vec4f>(instances[2u * rec.x + 1u]);
+  return shadow_clip(a.xyz - cascade.origin.xyz, a.w, q, vec3f(cl_pool[v], cl_pool[v + 1u], cl_pool[v + 2u]));
+}
+`;
+/** Grows a typed array to hold `n` more. */
+function grow(a, used, more, make) {
+    if (used + more <= a.length)
+        return a;
+    const b = make(Math.max(a.length * 2, used + more));
+    b.set(a.subarray(0, used));
+    return b;
+}
+/**
+ * Clusters on the CPU, in the layout the shaders read (ADR-0100, ADR-0111): 32 words per cluster
+ * (bounding sphere, normal cone, base vertex, where its vertices and triangle bytes start, its
+ * triangle count, flags, then its own and its parent's error spheres and errors, both 0 without a
+ * hierarchy), the clusters' local vertex indices, and their triangle bytes (each cluster's start
+ * rounded to 4). Pure: tested in Node.
+ */
+export class ClusterData {
+    words = new Uint32Array(1024);
+    f32 = new Float32Array(this.words.buffer);
+    count = 0;
+    vertices = new Uint32Array(4096);
+    vertexCount = 0;
+    triangles = new Uint8Array(4096);
+    triangleBytes = 0;
+    meshes = 0;
+    /**
+     * Clusters a mesh (interleaved vertices, 8 floats each; its finest LOD's indices) on this thread and
+     * appends them; with `lod`, its whole hierarchy (ADR-0111). Needs `MeshoptClusterizer.ready` (and
+     * the simplifier's for `lod`).
+     */
+    build(vertices, indices, baseVertex, doubleSided, lod = false) {
+        return this.append(packClusters(vertices, indices, lod), baseVertex, doubleSided);
+    }
+    /**
+     * Appends one mesh's packed clusters (`packClusters`, here or on a decode worker, ADR-0113): moves
+     * their vertex and triangle offsets to where they land and sets the mesh's base vertex and side.
+     */
+    append(p, baseVertex, doubleSided) {
+        const first = this.count;
+        const n = p.words.length / CLUSTER_WORDS;
+        this.words = grow(this.words, first * CLUSTER_WORDS, p.words.length, (k) => new Uint32Array(k));
+        this.f32 = new Float32Array(this.words.buffer);
+        const vBase = this.vertexCount;
+        this.vertices = grow(this.vertices, vBase, p.vertices.length, (k) => new Uint32Array(k));
+        this.vertices.set(p.vertices, vBase);
+        this.vertexCount += p.vertices.length;
+        // Each cluster's triangles start on 4 bytes, so the block keeps its alignment from a 4-byte start.
+        const tBase = this.triangleBytes;
+        this.triangles = grow(this.triangles, tBase, p.triangles.length + 4, (k) => new Uint8Array(k));
+        this.triangles.set(p.triangles, tBase);
+        this.triangleBytes = (tBase + p.triangles.length + 3) & ~3;
+        const w = this.words;
+        w.set(p.words, first * CLUSTER_WORDS);
+        for (let c = 0; c < n; c++) {
+            const o = (first + c) * CLUSTER_WORDS;
+            w[o + 11] = baseVertex;
+            w[o + 12] += vBase;
+            w[o + 13] += tBase;
+            w[o + 15] = doubleSided ? 1 : 0;
+        }
+        this.count += n;
+        this.meshes++;
+        return { first, count: n, doubleSided, indices: p.corners };
+    }
+}
+/** Floats of the shadow cull's uniform: 20 planes and the light. */
+const SHADOW_CULL_FLOATS = 84;
+/** Words of the casters' draw state (`sh_args`): 4 cascades × 2 sides × a draw record. */
+const SHADOW_ARGS_WORDS = 32;
+/** The clustered meshes' data on the GPU, the cull passes and the draw. */
+export class ClusterRenderer {
+    device;
+    #scene;
+    #store;
+    #min;
+    #maxEntries;
+    /** Whether meshes get a cluster LOD hierarchy (ADR-0111). */
+    #lod;
+    version = 0;
+    /** Meshes looked at, by id: their clusters, or null (not clustered). */
+    #meshes = [];
+    #storeVersion = -1;
+    /** The clusters on the CPU (uploaded when they grow). */
+    data = new ClusterData();
+    #uploaded = -1;
+    #buffers = null;
+    #phases;
+    /** Pass 1's held-back (instance, cluster) pairs, read by pass 2 (ADR-0109). */
+    #recheck = null;
+    #recheckDispatch;
+    /** Occlusion for clusters (ADR-0109; live): off culls them once, after both instance passes, as ADR-0100 did. */
+    occlusion = true;
+    /**
+     * Clustered shadow casters (ADR-0112; live): with a hierarchy (`lod`), casters at the view's cut, culled
+     * per cascade and pulled; without one the cascades draw clustered meshes whole (pulled costs more there).
+     * Off, they draw whole always. (ADR-0122's indexed casters were removed: slower whole frames, ADR-0139.)
+     */
+    shadows = true;
+    /** Clustered motion (ADR-0112; live): off, the motion pass draws clustered meshes whole, as before. */
+    motion = true;
+    #shadow;
+    #shadowData = new Float32Array(SHADOW_CULL_FLOATS);
+    #shadowArgs = new Uint32Array(SHADOW_ARGS_WORDS);
+    #shadowCull;
+    #shadowDraw = null;
+    #shadowHash = '';
+    #motionDraw = null;
+    #motionHash = '';
+    #motionGroups = [0, 1, 2].map(() => ({ key: '', group: null }));
+    /** The phases that culled last frame (diagnostics). */
+    #ran = [false, false, false];
+    #cull;
+    #cullFirst;
+    #cullSecond;
+    #sizeRecheck;
+    #recheckPipe;
+    #size;
+    #expand;
+    #draw = null;
+    #drawHash = '';
+    #cache = null;
+    /** Streamed pages' residency (ADR-0134). */
+    residency = new ClusterResidency();
+    /** By residency mesh: the store's mesh id and its pages. */
+    #streamIds = [];
+    #streamSrc = [];
+    /** The cull's page bits (needed, then used) and their words per half. */
+    #pageBits = null;
+    #pageWords = 0;
+    #pageReading = false;
+    /** Whether the cull binds the page bits (a ninth storage buffer a stage). */
+    #streamBits;
+    #inFlight;
+    #fetch;
+    #decoder = null;
+    #fetchWarned = false;
+    /** Pages fetched, their bytes, fetches that failed (ADR-0134). */
+    streamStats = { fetched: 0, bytes: 0, failed: 0 };
+    /** Meshes clustered and their clusters (for the counters). */
+    get stats() {
+        return { meshes: this.data.meshes, clusters: this.data.count };
+    }
+    constructor(device, scene, store, o) {
+        this.device = device;
+        this.#scene = scene;
+        this.#store = store;
+        this.#min = o.minTriangles ?? 4096;
+        this.#maxEntries = o.maxEntries ?? 4 << 20;
+        this.#lod = o.lod ?? false;
+        this.#pool = o.pool ?? null;
+        this.#streamBits = device.limits.maxStorageBuffersPerShaderStage >= 9;
+        this.#inFlight = o.stream?.inFlight ?? 8;
+        this.#fetch = o.stream?.fetch ?? rangeFetch;
+        const phase = (k) => ({
+            jobsKey: '',
+            jobs: device.createBuffer({ label: `yali:clusters:jobs${k}`, size: 32 * 64, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST }),
+            params: device.createBuffer({ label: `yali:clusters:params${k}`, size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST }),
+            outArgs: device.createBuffer({ label: `yali:clusters:args${k}`, size: 48, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC }),
+            outVisible: null,
+            outIndices: null,
+            dispatchArgs: device.createBuffer({ label: `yali:clusters:expand-dispatch${k}`, size: 12, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT }),
+            dispatch: { x: 0, y: 0, half: 0, indexHalf: 0 },
+            groupKey: '',
+            cullGroup: null,
+            sizeGroup: null,
+            expandGroup: null,
+            drawGroups: null,
+            recheckGroup: null,
+            sizeRecheckGroup: null,
+        });
+        this.#phases = [phase(0), phase(1), phase(2)];
+        this.#recheckDispatch = device.createBuffer({ label: 'yali:clusters:recheck-dispatch', size: 12, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT });
+        this.#shadow = {
+            jobsKey: '',
+            jobs: device.createBuffer({ label: 'yali:clusters:shadow-jobs', size: 32 * 64, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST }),
+            params: device.createBuffer({ label: 'yali:clusters:shadow-params', size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST }),
+            args: device.createBuffer({ label: 'yali:clusters:shadow-args', size: SHADOW_ARGS_WORDS * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC }),
+            planes: device.createBuffer({ label: 'yali:clusters:shadow-planes', size: SHADOW_CULL_FLOATS * 4, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST }),
+            visible: null,
+            dispatch: { x: 0, y: 0, half: 0, stride: 0, cascades: 0 },
+            groupKey: '',
+            cullGroup: null,
+            drawGroups: [],
+            live: false,
+        };
+    }
+    async init(cache) {
+        this.#cache = cache;
+        [this.#cull, this.#cullFirst, this.#cullSecond, this.#sizeRecheck, this.#recheckPipe, this.#size, this.#expand, this.#shadowCull] = await Promise.all(['cull_clusters', 'cull_clusters_first', 'cull_clusters_second', 'size_recheck', 'recheck_clusters', 'size_expand', 'expand_clusters', 'cull_clusters_shadow'].map((entryPoint) => cache.compute({ label: `yali:clusters:${entryPoint}`, compute: { shader: this.#streamBits ? sceneClusters : withoutPageBits(sceneClusters), entryPoint } })));
+    }
+    /** Whether mesh `mesh`'s finest LOD is drawn as clusters (the main view's slot then skips it). */
+    covers(mesh) {
+        this.#sync();
+        return !!this.#meshes[mesh];
+    }
+    /**
+     * Clusters the meshes added since the last look: on the decode pool when there is one (ADR-0113;
+     * the mesh draws whole until they arrive), else here on the main thread.
+     */
+    #sync() {
+        const store = this.#store;
+        if (store.version === this.#storeVersion)
+            return;
+        this.#storeVersion = store.version;
+        let changed = false;
+        for (let id = this.#meshes.length; id < store.entries.length; id++) {
+            const e = store.entries[id];
+            const g = store.geometry(id);
+            // Rigid, opaque (single- or double-sided) and big enough to gain from it.
+            const clusterable = g && !e.skinned && (e.drawClass === 0 || e.drawClass === 1) && g.indices.length / 3 >= this.#min;
+            this.#meshes[id] = null;
+            if (!clusterable)
+                continue;
+            // Streamed pages (`yali convert --clusters --stream`, ADR-0134): the roots now, the rest as asked for.
+            if (g.pages && this.#lod) {
+                this.#addStreamed(id, g.pages, e.baseVertex, e.drawClass === 1, g.vertices.length / 8);
+                continue;
+            }
+            // Clusters the file carried (`yali convert --clusters`, ADR-0121): no build at all.
+            if (g.clusters && g.clusters.lod === this.#lod) {
+                this.#meshes[id] = this.data.append(g.clusters, e.baseVertex, e.drawClass === 1);
+                this.buildStats.prebuilt++;
+                changed = true;
+                continue;
+            }
+            if (this.#pool) {
+                this.#offload(id, g.vertices, g.indices, e.baseVertex, e.drawClass === 1);
+                continue;
+            }
+            this.#meshes[id] = this.data.build(g.vertices, g.indices, e.baseVertex, e.drawClass === 1, this.#lod);
+            changed = true;
+        }
+        if (changed)
+            this.version++;
+    }
+    /** Builds a mesh's clusters on the pool; if the pool cannot (no `cluster-lod` decoder), here, once warned. */
+    #offload(id, vertices, indices, baseVertex, doubleSided) {
+        const t0 = performance.now();
+        const job = this.#pool.decode('cluster-lod', clusterRequest(vertices, indices, this.#lod))
+            .catch((err) => {
+            if (!this.#warned) {
+                this.#warned = true;
+                console.warn(`[yali] meshlets: building clusters on the main thread; the decode pool failed (${err instanceof Error ? err.message : String(err)}). Register decodeClusterLod from @yali-engine/render/meshlets-decoder as 'cluster-lod' in the decode worker.`);
+            }
+            return packClusters(vertices, indices, this.#lod);
+        })
+            .then((p) => {
+            this.#meshes[id] = this.data.append(p, baseVertex, doubleSided);
+            this.buildStats.meshes++;
+            this.buildStats.ms += performance.now() - t0;
+            this.version++;
+        });
+        this.#pending.add(job);
+        void job.finally(() => this.#pending.delete(job));
+    }
+    /** A streamed mesh: its records appended, its root pages decoded and applied (the mesh draws whole until then). */
+    #addStreamed(id, src, baseVertex, doubleSided, capacity) {
+        const job = (async () => {
+            const decode = await this.#vertexDecoder();
+            const roots = [];
+            let rootVertices = 0;
+            for (let p = 0; p < src.roots; p++) {
+                const at = src.pages[p * PAGE_WORDS + 3];
+                roots.push(decodeClusterPage(src.rootData.subarray(at, at + src.pages[p * PAGE_WORDS + 4]), decode));
+                rootVertices += src.pages[p * PAGE_WORDS + 2];
+            }
+            const c = this.data.append({ words: src.words.slice(), vertices: new Uint32Array(src.localIds), triangles: new Uint8Array(src.triangleBytes), corners: src.corners }, baseVertex, doubleSided);
+            const slots = src.slotVertices > 0 ? Math.max(0, Math.floor((capacity - rootVertices) / src.slotVertices)) : 0;
+            const m = this.residency.addMesh(this.data, { first: c.first, table: src.pages, roots: src.roots, slotVertices: src.slotVertices, baseVertex, rootVertices, slots }, roots);
+            this.#streamIds[m] = id;
+            this.#streamSrc[m] = src;
+            this.residency.takeDirty(); // the appended records upload whole; the roots' vertices are the mesh's own
+            this.#meshes[id] = c;
+            this.buildStats.prebuilt++;
+            this.version++;
+        })().catch((err) => console.warn(`[yali] meshlets: mesh ${id}'s streamed pages could not be read (${err instanceof Error ? err.message : String(err)}); it draws its root mesh whole.`));
+        this.#pending.add(job);
+        void job.finally(() => this.#pending.delete(job));
+    }
+    #vertexDecoder() {
+        this.#decoder ??= import('meshoptimizer/decoder').then(async ({ MeshoptDecoder }) => {
+            await MeshoptDecoder.ready;
+            return (t, c, s, src) => MeshoptDecoder.decodeVertexBuffer(t, c, s, src);
+        });
+        return this.#decoder;
+    }
+    /** The page bits buffer, sized for every page (two halves: needed, used). */
+    #ensurePageBits() {
+        const words = Math.max(1, Math.ceil(this.residency.pageCount / 32));
+        if (!this.#pageBits || this.#pageWords < words) {
+            this.#pageBits?.destroy();
+            this.#pageBits = this.device.createBuffer({ label: 'yali:clusters:page-bits', size: words * 8, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST });
+            this.#pageWords = words;
+            for (const p of this.#phases)
+                p.groupKey = '';
+        }
+        return this.#pageBits;
+    }
+    /**
+     * Once a frame (ADR-0134): what pages changed goes to the GPU (vertices straight into the scene's pool,
+     * ahead of the cull that may draw them), then the cull's page bits are read (a frame or so late) and
+     * the pages they ask for fetched. Without page bits every page is asked for, coarse first.
+     */
+    #stream() {
+        const r = this.residency;
+        if (r.pageCount === 0)
+            return;
+        const bits = this.#ensurePageBits();
+        const q = this.device.queue;
+        const dirty = r.takeDirty();
+        const pool = this.#scene.clusterSources()?.pool;
+        for (const w of dirty.vertices) {
+            const id = this.#streamIds[w.mesh];
+            this.#store.writeVertices(id, w.first, w.data);
+            if (pool)
+                q.writeBuffer(pool, (this.#store.entries[id].baseVertex + w.first) * 32, w.data);
+        }
+        if (this.#buffers && this.#uploaded === this.data.count) {
+            const b = this.#buffers;
+            const rec = dirty.records;
+            for (let i = 0; i < rec.length;) {
+                let j = i + 1;
+                while (j < rec.length && rec[j] === rec[j - 1] + 1)
+                    j++;
+                q.writeBuffer(b.clusters, rec[i] * CLUSTER_BYTES, this.data.words.buffer, rec[i] * CLUSTER_BYTES, (j - i) * CLUSTER_BYTES);
+                i = j;
+            }
+            for (const [a, z] of dirty.ids)
+                if (z > a)
+                    q.writeBuffer(b.vertices, a * 4, this.data.vertices.buffer, a * 4, (z - a) * 4);
+            for (const [a, z] of dirty.triangles)
+                if (z > a)
+                    q.writeBuffer(b.triangles, a, this.data.triangles.buffer, a, (z - a + 3) & ~3);
+        }
+        const room = this.#inFlight - r.inFlight;
+        if (room <= 0)
+            return;
+        if (!this.#streamBits) {
+            const all = new Uint32Array(this.#pageWords).fill(0xffffffff);
+            for (const g of r.requests(this.data, all, new Uint32Array(this.#pageWords), room))
+                this.#fetchPage(g);
+            return;
+        }
+        if (this.#pageReading)
+            return;
+        this.#pageReading = true;
+        const size = this.#pageWords * 8;
+        const rb = this.device.createBuffer({ label: 'yali:clusters:page-bits-read', size, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
+        const e = this.device.createCommandEncoder();
+        e.copyBufferToBuffer(bits, 0, rb, 0, size);
+        e.clearBuffer(bits);
+        q.submit([e.finish()]);
+        void rb
+            .mapAsync(GPUMapMode.READ)
+            .then(() => {
+            const w = new Uint32Array(rb.getMappedRange().slice(0));
+            const half = w.length / 2;
+            for (const g of r.requests(this.data, w.subarray(0, half), w.subarray(half), this.#inFlight - r.inFlight))
+                this.#fetchPage(g);
+        })
+            .catch(() => { })
+            .finally(() => {
+            rb.destroy();
+            this.#pageReading = false;
+        });
+    }
+    #fetchPage(g) {
+        const r = this.residency;
+        const { mesh, offset, length } = r.locate(g);
+        const src = this.#streamSrc[mesh];
+        void this.#fetch(src.url, src.base + offset - src.rootData.length, length)
+            .then(async (bytes) => {
+            const page = decodeClusterPage(bytes, await this.#vertexDecoder());
+            this.streamStats.fetched++;
+            this.streamStats.bytes += length;
+            r.load(this.data, g, page);
+        })
+            .catch((err) => {
+            r.cancel(g);
+            this.streamStats.failed++;
+            if (!this.#fetchWarned) {
+                this.#fetchWarned = true;
+                console.warn(`[yali] meshlets: a cluster page could not be fetched (${err instanceof Error ? err.message : String(err)}); its parents stay leaves.`);
+            }
+        });
+    }
+    #pool;
+    #pending = new Set();
+    #warned = false;
+    /** Meshes clustered on the pool and the milliseconds from request to arrival, summed (ADR-0113); meshes whose file carried their clusters (ADR-0121). */
+    buildStats = { meshes: 0, ms: 0, prebuilt: 0 };
+    /** Cluster builds still on the pool. */
+    get pending() {
+        return this.#pending.size;
+    }
+    #upload() {
+        if (this.#uploaded === this.data.count && this.#buffers)
+            return;
+        const d = this.device;
+        this.#buffers?.clusters.destroy();
+        this.#buffers?.vertices.destroy();
+        this.#buffers?.triangles.destroy();
+        const make = (label, data, bytes) => {
+            const b = d.createBuffer({ label, size: Math.max(16, (bytes + 3) & ~3), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+            d.queue.writeBuffer(b, 0, data.buffer, data.byteOffset, (bytes + 3) & ~3);
+            return b;
+        };
+        this.#buffers = {
+            clusters: make('yali:clusters', this.data.words, this.data.count * CLUSTER_BYTES),
+            vertices: make('yali:clusters:vertices', this.data.vertices, this.data.vertexCount * 4),
+            triangles: make('yali:clusters:triangles', this.data.triangles, this.data.triangleBytes),
+        };
+        this.#uploaded = this.data.count;
+        for (const p of this.#phases)
+            p.groupKey = '';
+        this.#shadow.groupKey = '';
+    }
+    /**
+     * The job records (8 words each) for the clustered finest-LOD slots of `sets`, and the room their
+     * survivors may need over `roomSets`: entries per side and indices per side.
+     */
+    #jobWords(lay, sets, roomSets) {
+        const words = [];
+        let prefix = 0;
+        let maxN = 0;
+        const halves = [0, 0];
+        const indexHalves = [0, 0];
+        for (const { slot, mesh, start, n } of lay.slots) {
+            const c = this.#meshes[mesh];
+            if (!c)
+                continue;
+            for (const set of sets) {
+                words.push(slot + set * lay.slots_, start + set * lay.region, c.first, c.count, prefix, c.doubleSided ? 1 : 0, 0, 0);
+                prefix += c.count;
+                maxN = Math.max(maxN, n);
+            }
+            for (const _ of roomSets) {
+                halves[c.doubleSided ? 1 : 0] += n * c.count;
+                indexHalves[c.doubleSided ? 1 : 0] += n * c.indices;
+            }
+        }
+        return { words, prefix, maxN, halves, indexHalves };
+    }
+    /**
+     * Phase `k`'s jobs for this layout: one per (clustered mesh's finest-LOD slot, slot set it culls).
+     * Pass 2 also has room for every cluster pass 1 may hold back.
+     */
+    #layoutJobs(k) {
+        const p = this.#phases[k];
+        const s = this.#scene;
+        const lay = s.clusterLayout();
+        if (!lay)
+            return false;
+        const key = `${lay.key}:${this.version}`;
+        if (key === p.jobsKey)
+            return p.dispatch.x > 0;
+        p.jobsKey = key;
+        const sets = k === 0 ? lay.sets : [k];
+        const { words, prefix, maxN, halves, indexHalves } = this.#jobWords(lay, sets, k === 2 ? [1, 2] : sets);
+        const jobs = words.length / 8;
+        if (jobs === 0 || halves[0] + halves[1] > this.#maxEntries || indexHalves[0] + indexHalves[1] > this.#maxEntries * 64) {
+            p.dispatch = { x: 0, y: 0, half: 0, indexHalf: 0 };
+            return false;
+        }
+        if (p.jobs.size < words.length * 4) {
+            p.jobs.destroy();
+            p.jobs = this.device.createBuffer({ label: `yali:clusters:jobs${k}`, size: words.length * 8, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+        }
+        this.device.queue.writeBuffer(p.jobs, 0, new Uint32Array(words));
+        this.device.queue.writeBuffer(p.params, 0, new Uint32Array([jobs, prefix, halves[0], indexHalves[0]]));
+        const entries = Math.max(1, halves[0] + halves[1]);
+        if (!p.outVisible || p.outVisible.size < entries * 16) {
+            p.outVisible?.destroy();
+            p.outVisible = this.device.createBuffer({ label: `yali:clusters:visible${k}`, size: entries * 16, usage: GPUBufferUsage.STORAGE });
+        }
+        const indices = Math.max(4, indexHalves[0] + indexHalves[1]);
+        if (!p.outIndices || p.outIndices.size < indices * 4) {
+            p.outIndices?.destroy();
+            p.outIndices = this.device.createBuffer({ label: `yali:clusters:indices${k}`, size: indices * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDEX });
+        }
+        // Pass 1 holds back at most what it culls: (instance, cluster) pairs after a count.
+        if (k === 1 && (!this.#recheck || this.#recheck.size < (1 + entries * 2) * 4)) {
+            this.#recheck?.destroy();
+            this.#recheck = this.device.createBuffer({ label: 'yali:clusters:recheck', size: (1 + entries * 2) * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+            for (const q of this.#phases)
+                q.groupKey = '';
+        }
+        p.dispatch = { x: Math.ceil(prefix / 64), y: Math.min(maxN, 65535), half: halves[0], indexHalf: indexHalves[0] };
+        p.groupKey = '';
+        return true;
+    }
+    #groups(k) {
+        const p = this.#phases[k];
+        const s = this.#scene;
+        const src = s.clusterSources();
+        const occl = k > 0 ? src?.occlusion : null;
+        if (!src || !this.#buffers || !p.outVisible || !this.#draw || (k > 0 && (!occl || !this.#recheck)))
+            return false;
+        const pageBits = this.#streamBits ? [{ binding: 21, resource: { buffer: this.#ensurePageBits() } }] : [];
+        const key = `${src.key}:${p.jobsKey}:${this.#uploaded}:${this.#drawHash}:${occl?.version ?? -1}:${this.#recheck?.size ?? 0}:${this.#pageWords}`;
+        if (key === p.groupKey)
+            return !!p.cullGroup;
+        p.groupKey = key;
+        const d = this.device;
+        const b = this.#buffers;
+        const buf = (binding, buffer) => ({ binding, resource: { buffer } });
+        const occlEntries = occl ? [buf(12, occl.params), { binding: 13, resource: occl.view }] : [];
+        const cull = k === 0 ? this.#cull : k === 1 ? this.#cullFirst : this.#cullSecond;
+        p.cullGroup = d.createBindGroup({
+            label: `yali:clusters:cull${k}`,
+            layout: cull.getBindGroupLayout(0),
+            entries: [buf(0, src.camera), buf(1, src.instances), buf(2, src.visible), buf(3, src.args), buf(4, b.clusters), buf(5, p.jobs), buf(6, p.params), buf(7, p.outArgs), buf(8, p.outVisible), buf(16, src.cullParams), ...occlEntries, ...(k === 1 ? [buf(14, this.#recheck)] : []), ...pageBits],
+        });
+        if (k === 2) {
+            p.sizeRecheckGroup = d.createBindGroup({ label: 'yali:clusters:size-recheck', layout: this.#sizeRecheck.getBindGroupLayout(0), entries: [buf(14, this.#recheck), buf(15, this.#recheckDispatch)] });
+            p.recheckGroup = d.createBindGroup({
+                label: 'yali:clusters:recheck',
+                layout: this.#recheckPipe.getBindGroupLayout(0),
+                entries: [buf(0, src.camera), buf(1, src.instances), buf(4, b.clusters), buf(6, p.params), buf(7, p.outArgs), buf(8, p.outVisible), buf(16, src.cullParams), ...occlEntries, buf(14, this.#recheck), ...pageBits],
+            });
+        }
+        p.sizeGroup = d.createBindGroup({ label: `yali:clusters:size${k}`, layout: this.#size.getBindGroupLayout(0), entries: [buf(7, p.outArgs), buf(11, p.dispatchArgs)] });
+        p.expandGroup = d.createBindGroup({
+            label: `yali:clusters:expand${k}`,
+            layout: this.#expand.getBindGroupLayout(0),
+            entries: [buf(4, b.clusters), buf(6, p.params), buf(7, p.outArgs), buf(8, p.outVisible), buf(9, p.outIndices), buf(10, b.triangles)],
+        });
+        const draw = [...src.drawEntries.filter((e) => e.binding !== 2 && e.binding !== 17), buf(20, src.pool), buf(21, b.clusters), buf(22, b.vertices), buf(24, p.outVisible)];
+        p.drawGroups = [0, 1].map((side) => d.createBindGroup({ label: `yali:clusters:draw${k}:${side}`, layout: this.#draw[side].getBindGroupLayout(0), entries: draw }));
+        return true;
+    }
+    /** The draw pipelines over the scene's current draw shader (rebuilt when its materials change). */
+    #pipelines() {
+        const src = this.#scene.clusterShader();
+        if (!src || src.hash === this.#drawHash || !this.#cache)
+            return;
+        const hash = src.hash;
+        const shader = { hash: `${hash}-clusters`, wgsl: src.wgsl + CLUSTER_DRAW };
+        const make = (cullMode) => this.#cache.render({
+            label: `yali:clusters:draw:${cullMode}`,
+            vertex: { shader, entryPoint: 'vs_cluster' },
+            fragment: { shader, entryPoint: 'fs', targets: [{ format: this.#scene.format }] },
+            primitive: { topology: 'triangle-list', cullMode },
+            depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'greater' },
+        });
+        this.#drawHash = hash;
+        this.#building = Promise.all([make('back'), make('none')]).then((p) => {
+            this.#draw = p;
+            for (const q of this.#phases)
+                q.groupKey = '';
+        });
+    }
+    #building = null;
+    /**
+     * Resolves when the clustered draw's pipelines for the current draw shader are built, and every
+     * mesh the store holds now has its clusters (the pool's builds arrived, ADR-0113).
+     */
+    async ready() {
+        this.#sync();
+        this.#pipelines();
+        const src = this.#castersOn() ? this.#scene.clusterShadow() : null;
+        if (src)
+            this.#shadowPipelines(src);
+        await Promise.all([this.#building, this.#shadowBuilding, this.#motionBuilding, ...this.#pending]);
+    }
+    /**
+     * Draws frames until streamed pages stop arriving (ADR-0134): calls `frame` (one frame drawn) until no
+     * page is in flight or being asked for and none arrived for 8 frames in a row, at most `most` frames.
+     * For golden images, whose frame must not depend on when pages came. Immediate with nothing streamed.
+     */
+    async settled(frame, most = 1200) {
+        if (this.residency.pageCount === 0)
+            return;
+        let quiet = 0;
+        for (let i = 0; i < most && quiet < 8; i++) {
+            const before = this.residency.stats.loaded + this.streamStats.failed;
+            frame();
+            await new Promise((r) => setTimeout(r, 8));
+            const busy = this.residency.inFlight > 0 || this.#pageReading || this.residency.stats.loaded + this.streamStats.failed !== before;
+            quiet = busy ? 0 : quiet + 1;
+        }
+    }
+    /**
+     * The phase a call means: without occlusion (or with `occlusion` off) only phase 0, culled once
+     * after both instance passes under occlusion, as ADR-0100 did.
+     */
+    #phaseFor(phase) {
+        if (phase === 0 || this.occlusion)
+            return phase;
+        return phase === 2 ? 0 : -1;
+    }
+    /**
+     * Adds a cluster cull, reading the instance cull's `after` (ADR-0100, ADR-0109): `phase` 0 without
+     * occlusion; under occlusion 1 (after the first instance cull, drawn in the view's first pass) and
+     * 2 (after the recheck, drawn in the second).
+     */
+    addCull(graph, after, phase = 0) {
+        graph.addPass({
+            name: `scene.clusters${phase || ''}`,
+            kind: 'compute',
+            reads: phase === 2 ? [after, 'scene.clusterList1'] : [after],
+            writes: [`scene.clusterList${phase || ''}`],
+            execute: (pass) => {
+                const k = this.#phaseFor(phase);
+                if (phase !== 2)
+                    this.#ran.fill(false);
+                if (k < 0) {
+                    // Occlusion off for clusters: pass 1 draws none, pass 2's call culls them once (phase 0).
+                    this.#phases[1].dispatch.x = 0;
+                    this.#phases[1].jobsKey = '';
+                    return;
+                }
+                this.#sync();
+                this.#pipelines();
+                if (this.data.count === 0 || !this.#layoutJobs(k))
+                    return;
+                this.#upload();
+                if (phase !== 2)
+                    this.#stream();
+                if (!this.#groups(k))
+                    return;
+                const p = this.#phases[k];
+                this.#ran[k] = true;
+                const { half, indexHalf } = p.dispatch;
+                // Two indexed draws: each side's indices from its half, its visible-list entries from its half (first instance).
+                this.device.queue.writeBuffer(p.outArgs, 0, new Uint32Array([0, 1, 0, 0, 0, 0, 1, indexHalf, 0, half, 0, 0]));
+                if (k === 1)
+                    this.device.queue.writeBuffer(this.#recheck, 0, new Uint32Array([0]));
+                pass.setPipeline(k === 0 ? this.#cull : k === 1 ? this.#cullFirst : this.#cullSecond);
+                pass.setBindGroup(0, p.cullGroup);
+                pass.dispatchWorkgroups(p.dispatch.x, p.dispatch.y);
+                if (k === 2 && this.#phases[1].dispatch.x > 0) {
+                    pass.setPipeline(this.#sizeRecheck);
+                    pass.setBindGroup(0, p.sizeRecheckGroup);
+                    pass.dispatchWorkgroups(1);
+                    pass.setPipeline(this.#recheckPipe);
+                    pass.setBindGroup(0, p.recheckGroup);
+                    pass.dispatchWorkgroupsIndirect(this.#recheckDispatch, 0);
+                }
+                pass.setPipeline(this.#size);
+                pass.setBindGroup(0, p.sizeGroup);
+                pass.dispatchWorkgroups(1);
+                pass.setPipeline(this.#expand);
+                pass.setBindGroup(0, p.expandGroup);
+                pass.dispatchWorkgroupsIndirect(p.dispatchArgs, 0);
+            },
+        });
+    }
+    /** Draws phase `phase`'s visible clusters (in the scene's opaque pass it is called from). */
+    encodeDraw(pass, phase = 0) {
+        const k = this.#phaseFor(phase);
+        if (k < 0)
+            return;
+        const p = this.#phases[k];
+        if (p.dispatch.x === 0 || !this.#draw || !p.drawGroups)
+            return;
+        pass.setIndexBuffer(p.outIndices, 'uint32');
+        for (const side of [0, 1]) {
+            pass.setPipeline(this.#draw[side]);
+            pass.setBindGroup(0, p.drawGroups[side]);
+            pass.drawIndexedIndirect(p.outArgs, side * 20);
+        }
+    }
+    // ── Clustered shadow casters (ADR-0112) ────────────────────────────────────────────────────
+    /** The shadow cull's jobs: the caster set's (0) clustered slots, with room for every cascade. */
+    #layoutShadow(cascades) {
+        const sh = this.#shadow;
+        const lay = this.#scene.clusterLayout();
+        if (!lay)
+            return false;
+        const key = `${lay.key}:${this.version}:${cascades}`;
+        if (key === sh.jobsKey)
+            return sh.dispatch.x > 0;
+        sh.jobsKey = key;
+        sh.groupKey = '';
+        const { words, prefix, maxN, halves } = this.#jobWords(lay, [0], [0]);
+        const jobs = words.length / 8;
+        const stride = halves[0] + halves[1];
+        if (jobs === 0 || stride * cascades > this.#maxEntries) {
+            sh.dispatch = { x: 0, y: 0, half: 0, stride: 0, cascades: 0 };
+            return false;
+        }
+        if (sh.jobs.size < words.length * 4) {
+            sh.jobs.destroy();
+            sh.jobs = this.device.createBuffer({ label: 'yali:clusters:shadow-jobs', size: words.length * 8, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+        }
+        this.device.queue.writeBuffer(sh.jobs, 0, new Uint32Array(words));
+        this.device.queue.writeBuffer(sh.params, 0, new Uint32Array([jobs, prefix, halves[0], stride]));
+        const bytes = Math.max(1, stride * cascades) * 16;
+        if (!sh.visible || sh.visible.size < bytes) {
+            sh.visible?.destroy();
+            sh.visible = this.device.createBuffer({ label: 'yali:clusters:shadow-visible', size: bytes, usage: GPUBufferUsage.STORAGE });
+        }
+        sh.dispatch = { x: Math.ceil(prefix / 64), y: Math.min(maxN, 65535), half: halves[0], stride, cascades };
+        return true;
+    }
+    /** The caster pipelines over the scene's shadow shader (single-sided culls back faces, as the scene's). */
+    #shadowPipelines(src) {
+        if (src.shader.hash === this.#shadowHash || !this.#cache)
+            return;
+        this.#shadowHash = src.shader.hash;
+        const shader = { hash: `${src.shader.hash}-clusters-shadow`, wgsl: src.shader.wgsl + CLUSTER_SHADOW };
+        const make = (cullMode) => this.#cache.render({
+            label: `yali:clusters:shadow:${cullMode}`,
+            vertex: { shader, entryPoint: 'vs_shadow_cluster' },
+            primitive: { topology: 'triangle-list', cullMode, frontFace: 'ccw' },
+            depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'greater' },
+        });
+        this.#shadowBuilding = Promise.all([make('back'), make('none')]).then((p) => {
+            this.#shadowDraw = [p[0], p[1]];
+            this.#shadow.groupKey = '';
+        });
+    }
+    #shadowGroups(src) {
+        const sh = this.#shadow;
+        const s = this.#scene.clusterSources();
+        if (!s || !this.#buffers || !sh.visible || !this.#shadowDraw)
+            return false;
+        const key = `${s.key}:${sh.jobsKey}:${this.#uploaded}:${this.#shadowHash}:${sh.visible.size}`;
+        if (key === sh.groupKey)
+            return !!sh.cullGroup;
+        sh.groupKey = key;
+        const d = this.device;
+        const b = this.#buffers;
+        const buf = (binding, buffer) => ({ binding, resource: { buffer } });
+        sh.cullGroup = d.createBindGroup({
+            label: 'yali:clusters:shadow-cull',
+            layout: this.#shadowCull.getBindGroupLayout(0),
+            entries: [buf(0, s.camera), buf(1, s.instances), buf(2, s.visible), buf(3, s.args), buf(4, b.clusters), buf(5, sh.jobs), buf(6, sh.params), buf(16, s.cullParams), buf(17, sh.planes), buf(18, sh.args), buf(19, sh.visible)],
+        });
+        sh.drawGroups = Array.from({ length: src.cascades }, (_, c) => [0, 1].map((side) => d.createBindGroup({
+            label: `yali:clusters:shadow:${c}:${side}`,
+            layout: this.#shadowDraw[side].getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: src.cascadeBuffer, offset: src.cascadeOffset(c), size: src.cascadeBytes } },
+                buf(1, s.instances),
+                buf(20, s.pool),
+                buf(21, b.clusters),
+                buf(22, b.vertices),
+                buf(23, b.triangles),
+                buf(24, sh.visible),
+            ],
+        })));
+        return true;
+    }
+    /**
+     * Adds the shadow casters' cluster cull after `after` (the instance cull, whose slot set 0 holds the
+     * casters): every cascade at once, read by `scene.shadow` (ADR-0112).
+     */
+    addShadowCull(graph, after) {
+        graph.addPass({
+            name: 'scene.clusterShadow',
+            kind: 'compute',
+            reads: [after],
+            writes: ['scene.clusterShadow'],
+            execute: (pass) => {
+                const sh = this.#shadow;
+                sh.live = false;
+                if (!this.#castersOn())
+                    return;
+                const src = this.#scene.clusterShadow();
+                if (!src)
+                    return;
+                this.#sync();
+                this.#shadowPipelines(src);
+                if (this.data.count === 0 || !this.#shadowDraw || !this.#layoutShadow(src.cascades))
+                    return;
+                this.#upload();
+                if (!this.#shadowGroups(src))
+                    return;
+                const u = this.#shadowData;
+                u.fill(0);
+                u.set(src.planes.subarray(0, src.cascades * 20), 0);
+                u[80] = src.light[0];
+                u[81] = src.light[1];
+                u[82] = src.light[2];
+                u[83] = src.cascades;
+                this.device.queue.writeBuffer(sh.planes, 0, u);
+                const args = this.#shadowArgs;
+                args.fill(0);
+                for (let c = 0; c < src.cascades; c++) {
+                    const o = c * 8;
+                    args[o] = args[o + 4] = SHADOW_VERTICES;
+                    args[o + 3] = c * sh.dispatch.stride;
+                    args[o + 7] = c * sh.dispatch.stride + sh.dispatch.half;
+                }
+                this.device.queue.writeBuffer(sh.args, 0, args);
+                pass.setPipeline(this.#shadowCull);
+                pass.setBindGroup(0, sh.cullGroup);
+                pass.dispatchWorkgroups(sh.dispatch.x, sh.dispatch.y, src.cascades);
+                sh.live = true;
+            },
+        });
+    }
+    /** Whether the casters are clustered: with a hierarchy (ADR-0112; without one they draw whole, cheaper). */
+    #castersOn() {
+        return this.shadows && this.#lod;
+    }
+    /** Whether this frame's casters of mesh `mesh` are drawn as clusters (the cascades' slots then skip it). */
+    shadowCovers(mesh) {
+        return this.#shadow.live && !!this.#meshes[mesh];
+    }
+    /** Draws cascade `cascade`'s clustered casters into the shadow pass (its viewport already set). */
+    encodeShadow(pass, cascade) {
+        const sh = this.#shadow;
+        if (!sh.live || !this.#shadowDraw || cascade >= sh.drawGroups.length)
+            return;
+        for (const side of [0, 1]) {
+            pass.setPipeline(this.#shadowDraw[side]);
+            pass.setBindGroup(0, sh.drawGroups[cascade][side]);
+            pass.drawIndirect(sh.args, (cascade * 2 + side) * 16);
+        }
+    }
+    // ── Clustered motion (ADR-0112) ────────────────────────────────────────────────────────────
+    /**
+     * Whether the motion pass may skip the clustered meshes' slots: the clustered motion pipeline over
+     * `m`'s shader is built (it starts building on the first call).
+     */
+    motionCovers(m) {
+        if (!this.motion)
+            return false;
+        this.prepareMotion(m.shader, m.format);
+        return !!this.#motionDraw;
+    }
+    /** Starts building the clustered motion pipeline over the motion pass's shader (`ready()` then awaits it). */
+    prepareMotion(motionShader, format) {
+        if (!this.#cache || motionShader.hash === this.#motionHash)
+            return;
+        this.#motionHash = motionShader.hash;
+        this.#motionDraw = null;
+        const shader = { hash: `${motionShader.hash}-clusters-motion`, wgsl: motionShader.wgsl + CLUSTER_MOTION };
+        this.#motionBuilding = this.#cache
+            .render({
+            label: 'yali:clusters:motion',
+            vertex: { shader, entryPoint: 'vs_cluster_motion' },
+            fragment: { shader, entryPoint: 'fs', targets: [{ format }] },
+            primitive: { topology: 'triangle-list', cullMode: 'none' },
+            depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'greater' },
+        })
+            .then((p) => {
+            this.#motionDraw = p;
+            for (const g of this.#motionGroups)
+                g.key = '';
+        });
+    }
+    #motionBuilding = null;
+    #shadowBuilding = null;
+    /** Draws the clusters this frame's view drew (every phase that ran) with the motion pipeline. */
+    encodeMotion(pass, m) {
+        const draw = this.#motionDraw;
+        const b = this.#buffers;
+        const s = this.#scene.clusterSources();
+        if (!this.motion || !draw || !b || !s)
+            return;
+        for (let k = 0; k < 3; k++) {
+            const p = this.#phases[k];
+            if (!this.#ran[k] || p.dispatch.x === 0 || !p.outVisible || !p.outIndices)
+                continue;
+            const g = this.#motionGroups[k];
+            const key = `${m.key}:${p.groupKey}:${s.key}`;
+            if (g.key !== key || !g.group) {
+                g.key = key;
+                const buf = (binding, buffer) => ({ binding, resource: { buffer } });
+                g.group = this.device.createBindGroup({
+                    label: `yali:clusters:motion${k}`,
+                    layout: draw.getBindGroupLayout(0),
+                    // The motion shader's own bindings but the visible ranges (the clusters carry their instance).
+                    entries: [...m.entries.filter((e) => e.binding !== 2), buf(20, s.pool), buf(21, b.clusters), buf(22, b.vertices), buf(24, p.outVisible)],
+                });
+            }
+            pass.setPipeline(draw);
+            pass.setBindGroup(0, g.group);
+            pass.setIndexBuffer(p.outIndices, 'uint32');
+            pass.drawIndexedIndirect(p.outArgs, 0);
+            pass.drawIndexedIndirect(p.outArgs, 20);
+        }
+    }
+    /** Clusters the last frame drew, over its phases: single- and double-sided (a diagnostic; reads back from the GPU). */
+    async readCounts() {
+        const d = this.device;
+        const rb = d.createBuffer({ size: 48 * 3 + SHADOW_ARGS_WORDS * 4, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
+        const e = d.createCommandEncoder();
+        this.#phases.forEach((p, k) => e.copyBufferToBuffer(p.outArgs, 0, rb, k * 48, 48));
+        e.copyBufferToBuffer(this.#shadow.args, 0, rb, 144, SHADOW_ARGS_WORDS * 4);
+        d.queue.submit([e.finish()]);
+        await rb.mapAsync(GPUMapMode.READ);
+        const a = new Uint32Array(rb.getMappedRange().slice(0));
+        rb.destroy();
+        // Clustered casters per cascade (ADR-0112), both sides; empty when they did not run.
+        const sh = this.#shadow;
+        const shadow = sh.live ? Array.from({ length: sh.dispatch.cascades }, (_, c) => a[36 + c * 8 + 1] + a[36 + c * 8 + 5]) : [];
+        const live = this.#ran.map((r, k) => r && this.#phases[k].dispatch.x > 0);
+        let single = 0;
+        let double = 0;
+        let triangles = 0;
+        const perPhase = [0, 1, 2].map((k) => (live[k] ? a[k * 12 + 10] + a[k * 12 + 11] : 0));
+        for (let k = 0; k < 3; k++) {
+            if (!live[k])
+                continue;
+            single += a[k * 12 + 10];
+            double += a[k * 12 + 11];
+            triangles += (a[k * 12] + a[k * 12 + 5]) / 3;
+        }
+        return { single, double, triangles, drawReady: !!this.#draw, jobs: this.#phases.reduce((n, p) => n + p.dispatch.x, 0), perPhase, shadow, motionReady: !!this.#motionDraw };
+    }
+    destroy() {
+        this.#buffers?.clusters.destroy();
+        this.#buffers?.vertices.destroy();
+        this.#buffers?.triangles.destroy();
+        for (const p of this.#phases) {
+            p.jobs.destroy();
+            p.params.destroy();
+            p.outArgs.destroy();
+            p.outVisible?.destroy();
+            p.outIndices?.destroy();
+            p.dispatchArgs.destroy();
+        }
+        this.#recheck?.destroy();
+        this.#recheckDispatch.destroy();
+        const sh = this.#shadow;
+        sh.jobs.destroy();
+        sh.params.destroy();
+        sh.args.destroy();
+        sh.planes.destroy();
+        sh.visible?.destroy();
+    }
+}
+//# sourceMappingURL=meshlets.js.map