@woosh/meep-engine 3.57.0 → 3.58.0

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_movers.js

@@ -0,0 +1,146 @@
+import { MESH_SDF_BAND_VOXELS, MESH_SDF_BRICK_VOXELS } from "../../../geometry/sdf/MESH_SDF.js";
+import { chunk_scene_database_access } from "../../../scene/chunk_scene_database_access.js";
+import { SCENE_MOVER_POSE_ONLY, SCENE_MOVERS_READ_STRUCT } from "../../../scene/movers/SCENE_MOVER_LAYOUT.js";
+import { CLIPMAP_LEVEL_ARRAY } from "../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { chunk_mod_v3i } from "../../../shader/chunk/geometry/vec3/chunk_mod_v3i.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { BRICK_OCCUPANCY_BLOCK } from "./BRICK_CLIPMAP.js";
+import { BRICK_MOVERS_BOX_COUNT, BRICK_MOVERS_SCENE_COUNT, BRICK_MOVERS_WORKGROUP_SIZE } from "./BRICK_MOVERS.js";
+import {
+    BRICK_PENDING_RESOURCE,
+    BRICK_RING_RESOURCE,
+    BRICK_STATE_RESOURCE,
+    chunk_brick_clipmap,
+    chunk_brick_clipmap_enqueue
+} from "./chunk_brick_clipmap.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_MOVERS_SETTINGS = WebGPUStruct.from({
+    /** occupancy blocks over every cascade */
+    block_count: u32,
+    /** cells a cascade's window has a side */
+    resolution: u32,
+    /** keys `brick_ring` holds, a power of two */
+    ring_capacity: u32,
+}, "BrickMoversSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", BRICK_MOVERS_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("scene_movers", SCENE_MOVERS_READ_STRUCT)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
+    .addStorageBuffer("brick_invalidated", WebGPUArray.u32)
+    .addStorageBuffer("brick_movers", WebGPUArray.u32)
+    .addUniform("brick_levels", CLIPMAP_LEVEL_ARRAY)
+    .add(BRICK_STATE_RESOURCE)
+    .add(BRICK_RING_RESOURCE)
+    .add(BRICK_PENDING_RESOURCE);
+
+/**
+ * Movers (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.4): a thread an (occupancy block, box) pair of every
+ * cascade, dispatched by the movers' command. The pair count follows the boxes, never a box's
+ * footprint.
+ *
+ * A box is a scene mover's, from the list every reader shares, or the world box of a row the host
+ * invalidated, read from the `meshes` table now. A mover only animation moved is skipped: a skinned
+ * row stands in its bind pose here (the hook, §6.3). A box under half a voxel of a cascade across is
+ * out of that cascade, as the mesh provider's cull has it. Otherwise it grows by the cascade's band,
+ * and every cell of the block it overlaps is queued.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_movers = ComputeShader.from({
+    label: "Brick Clipmap Movers",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+const BLOCK = ${BRICK_OCCUPANCY_BLOCK}u;
+
+@compute @workgroup_size(${BRICK_MOVERS_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let pair = folded_workgroup_index(workgroup_id) * ${BRICK_MOVERS_WORKGROUP_SIZE}u + lane;
+    let box_index = pair / settings.block_count;
+
+    if (box_index >= brick_movers[${BRICK_MOVERS_BOX_COUNT}u]) {
+        return;
+    }
+
+    var box_min: vec3<f32>;
+    var box_max: vec3<f32>;
+
+    let movers = brick_movers[${BRICK_MOVERS_SCENE_COUNT}u];
+
+    if (box_index < movers) {
+        let low = scene_movers.boxes[2u * box_index];
+
+        if (low.w >= ${SCENE_MOVER_POSE_ONLY}.0) {
+            // the bind pose stands at the row's node
+            return;
+        }
+
+        box_min = low.xyz;
+        box_max = scene_movers.boxes[2u * box_index + 1u].xyz;
+    } else {
+        let mesh = scene_read_mesh(&scene_database, brick_invalidated[box_index - movers]);
+
+        box_min = vec3<f32>(mesh.bounding_box[0], mesh.bounding_box[1], mesh.bounding_box[2]);
+        box_max = vec3<f32>(mesh.bounding_box[3], mesh.bounding_box[4], mesh.bounding_box[5]);
+    }
+
+    let block_index = pair - box_index * settings.block_count;
+    let resolution = settings.resolution;
+    let blocks = resolution / BLOCK;
+
+    // blocks stack along z as the cascades do
+    let block = vec3<u32>(block_index % blocks, (block_index / blocks) % blocks, block_index / (blocks * blocks));
+    let cascade = block.z / blocks;
+    let level = brick_levels[cascade];
+
+    let voxel = level.cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+
+    if (length(box_max - box_min) < 0.5 * voxel) {
+        return;
+    }
+
+    let band = ${MESH_SDF_BAND_VOXELS}.0 * voxel;
+    let low = box_min - vec3<f32>(band);
+    let high = box_max + vec3<f32>(band);
+
+    let n = vec3<i32>(i32(resolution));
+    let first = vec3<u32>(block.x, block.y, block.z % blocks) * BLOCK;
+
+    for (var i = 0u; i < BLOCK * BLOCK * BLOCK; i++) {
+        let storage = first + vec3<u32>(i % BLOCK, (i / BLOCK) % BLOCK, i / (BLOCK * BLOCK));
+
+        // the world cell the storage cell holds: the window's one congruent to it
+        let cell = level.corner + mod_v3i(vec3<i32>(storage) - level.corner, n);
+        let cell_min = vec3<f32>(cell) * level.cell_size;
+        let cell_max = cell_min + vec3<f32>(level.cell_size);
+
+        if (all(cell_min <= high) && all(low <= cell_max)) {
+            brick_clipmap_enqueue(brick_clipmap_key(cascade, storage, resolution), settings.ring_capacity);
+        }
+    }
+}
+`, [
+            chunk_brick_clipmap,
+            chunk_brick_clipmap_enqueue,
+            chunk_folded_workgroup_index,
+            chunk_mod_v3i,
+            chunk_scene_database_access,
+        ]),
+});

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_movers_command.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_MOVERS_COMMAND_SETTINGS: WebGPUStruct;
+/**
+ * The movers' command (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.4): one thread, after the scene's mover
+ * list is made. The boxes are its movers and the rows the host invalidated: bake completions and
+ * changes of SDF membership. A list past its capacity, or past
+ * {@link BRICK_MOVERS_FULL_REQUEUE_BOXES} boxes, re-queues every key of every cascade instead; otherwise
+ * a thread a pair of an occupancy block and a box. Either dispatch is the other's zero, folded past
+ * the per-dimension limit.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_movers_command: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_brick_clipmap_movers_command.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_movers_command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_brick_clipmap_movers_command.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_movers_command.js"],"names":[],"mappings":"AAiBA;;GAEG;AACH,4CAFU,YAAY,CAWW;AAUjC;;;;;;;;;GASG;AACH,kDAFU,aAAa,CAoCpB;6BA5E0B,sCAAsC;8BAJrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_movers_command.js

@@ -0,0 +1,84 @@
+import { chunk_folded_dispatch } from "../../../gpu_primitive/indirect/chunk_folded_dispatch.js";
+import { SCENE_MOVERS_READ_STRUCT } from "../../../scene/movers/SCENE_MOVER_LAYOUT.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    BRICK_MOVERS_BOX_COUNT,
+    BRICK_MOVERS_FULL_REQUEUE_BOXES,
+    BRICK_MOVERS_PAIR_DISPATCH,
+    BRICK_MOVERS_REQUEUE_DISPATCH,
+    BRICK_MOVERS_SCENE_COUNT,
+    BRICK_MOVERS_WORKGROUP_SIZE
+} from "./BRICK_MOVERS.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_MOVERS_COMMAND_SETTINGS = WebGPUStruct.from({
+    /** boxes `scene_movers` holds at most, `SCENE_MOVER_CAPACITY` */
+    mover_capacity: u32,
+    /** rows the host invalidated this frame, after the movers */
+    row_count: u32,
+    /** occupancy blocks over every cascade: a pair a block a box */
+    block_count: u32,
+    /** keys over every cascade, what a full re-queue runs over */
+    key_count: u32,
+}, "BrickMoversCommandSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", BRICK_MOVERS_COMMAND_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("scene_movers", SCENE_MOVERS_READ_STRUCT)
+    .addStorageBuffer("brick_movers", WebGPUArray.u32, true);
+
+/**
+ * The movers' command (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.4): one thread, after the scene's mover
+ * list is made. The boxes are its movers and the rows the host invalidated: bake completions and
+ * changes of SDF membership. A list past its capacity, or past
+ * {@link BRICK_MOVERS_FULL_REQUEUE_BOXES} boxes, re-queues every key of every cascade instead; otherwise
+ * a thread a pair of an occupancy block and a box. Either dispatch is the other's zero, folded past
+ * the per-dimension limit.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_movers_command = ComputeShader.from({
+    label: "Brick Clipmap Movers Command",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+fn write_folded_dispatch(at: u32, groups: u32) {
+    let folded = folded_dispatch(groups);
+
+    brick_movers[at] = folded.x;
+    brick_movers[at + 1u] = folded.y;
+    brick_movers[at + 2u] = folded.z;
+}
+
+@compute @workgroup_size(1)
+fn main() {
+    let listed = scene_movers.count;
+    let movers = min(listed, settings.mover_capacity);
+    let boxes = movers + settings.row_count;
+
+    let everything = listed > settings.mover_capacity || boxes > ${BRICK_MOVERS_FULL_REQUEUE_BOXES}u;
+
+    let pairs = select(boxes * settings.block_count, 0u, everything);
+    let keys = select(0u, settings.key_count, everything);
+
+    write_folded_dispatch(${BRICK_MOVERS_PAIR_DISPATCH}u, (pairs + ${BRICK_MOVERS_WORKGROUP_SIZE - 1}u) / ${BRICK_MOVERS_WORKGROUP_SIZE}u);
+    write_folded_dispatch(${BRICK_MOVERS_REQUEUE_DISPATCH}u, (keys + ${BRICK_MOVERS_WORKGROUP_SIZE - 1}u) / ${BRICK_MOVERS_WORKGROUP_SIZE}u);
+
+    brick_movers[${BRICK_MOVERS_BOX_COUNT}u] = select(boxes, 0u, everything);
+    brick_movers[${BRICK_MOVERS_SCENE_COUNT}u] = movers;
+}
+`, [
+            chunk_folded_dispatch,
+        ]),
+});

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_requeue.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_REQUEUE_SETTINGS: WebGPUStruct;
+/**
+ * Re-queue (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.4): a thread a key of every cascade, dispatched by
+ * the movers' command on a frame with more boxes than pairs are worth, or a mover list past its
+ * capacity. Every key not already pending is queued, and the clipmap is built again over the frames
+ * that follow.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_requeue: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_brick_clipmap_requeue.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_requeue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_brick_clipmap_requeue.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_requeue.js"],"names":[],"mappings":"AAeA;;GAEG;AACH,qCAFU,YAAY,CAOK;AAW3B;;;;;;;GAOG;AACH,2CAFU,aAAa,CA0BpB;6BA7D0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_requeue.js

@@ -0,0 +1,67 @@
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { BRICK_MOVERS_WORKGROUP_SIZE } from "./BRICK_MOVERS.js";
+import {
+    BRICK_PENDING_RESOURCE,
+    BRICK_RING_RESOURCE,
+    BRICK_STATE_RESOURCE,
+    chunk_brick_clipmap,
+    chunk_brick_clipmap_enqueue
+} from "./chunk_brick_clipmap.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_REQUEUE_SETTINGS = WebGPUStruct.from({
+    /** keys over every cascade */
+    key_count: u32,
+    /** keys `brick_ring` holds, a power of two */
+    ring_capacity: u32,
+}, "BrickRequeueSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", BRICK_REQUEUE_SETTINGS);
+
+resources.createGroup()
+    .add(BRICK_STATE_RESOURCE)
+    .add(BRICK_RING_RESOURCE)
+    .add(BRICK_PENDING_RESOURCE);
+
+/**
+ * Re-queue (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.4): a thread a key of every cascade, dispatched by
+ * the movers' command on a frame with more boxes than pairs are worth, or a mover list past its
+ * capacity. Every key not already pending is queued, and the clipmap is built again over the frames
+ * that follow.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_requeue = ComputeShader.from({
+    label: "Brick Clipmap Requeue",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${BRICK_MOVERS_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let key = folded_workgroup_index(workgroup_id) * ${BRICK_MOVERS_WORKGROUP_SIZE}u + lane;
+
+    if (key >= settings.key_count) {
+        return;
+    }
+
+    brick_clipmap_enqueue(key, settings.ring_capacity);
+}
+`, [
+            chunk_brick_clipmap,
+            chunk_brick_clipmap_enqueue,
+            chunk_folded_workgroup_index,
+        ]),
+});

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_scroll.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_SCROLL_SETTINGS: WebGPUStruct;
+/**
+ * Scroll (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.4): a thread a cell a window exposed this frame.
+ *
+ * The exposed cells come as boxes, two `vec4<i32>` a box in `brick_scroll_runs`: the box's smallest
+ * cell and its cascade, then its size and its first thread. Its cells run x fastest. A cell's storage
+ * cell held a cell that has left the window: its slot, if it had one, goes back on the free list, its
+ * entry becomes UNKNOWN, and its key is queued unless it already is. Its occupancy block is marked as
+ * having cells to read, every one, until coarse counts it once the cell is built: a ray must not
+ * skip a cell it should read from the next cascade out.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_scroll: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_brick_clipmap_scroll.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_brick_clipmap_scroll.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_scroll.js"],"names":[],"mappings":"AAkBA;;GAEG;AACH,oCAFU,YAAY,CAeI;AAe1B;;;;;;;;;;;GAWG;AACH,0CAFU,aAAa,CAoEpB;6BAzH0B,sCAAsC;8BAJrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_scroll.js

@@ -0,0 +1,128 @@
+import { chunk_clipmap_storage_coord } from "../../../shader/chunk/clipmap/chunk_clipmap_storage_coord.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32, vec4i } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { chunk_slot_stack } from "../../../gpu_primitive/slot_stack/chunk_slot_stack.js";
+import { BRICK_OCCUPANCY_BLOCK, BRICK_THREAD_WORKGROUP_SIZE } from "./BRICK_CLIPMAP.js";
+import {
+    BRICK_FREE_RESOURCE,
+    BRICK_PENDING_RESOURCE,
+    BRICK_RING_RESOURCE,
+    BRICK_STATE_RESOURCE,
+    chunk_brick_clipmap,
+    chunk_brick_clipmap_enqueue
+} from "./chunk_brick_clipmap.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_SCROLL_SETTINGS = WebGPUStruct.from({
+    /** boxes in `brick_scroll_runs` */
+    run_count: u32,
+    /** cells over every box: the threads that do work */
+    cell_count: u32,
+    /** workgroups along x, the rest folded into y */
+    groups_x: u32,
+    /** keys `brick_ring` holds, a power of two */
+    ring_capacity: u32,
+    /** cells a cascade's window has a side */
+    resolution: u32,
+    /** 1 when the brick map holds nothing yet, so that what it reads is no slot to give back */
+    fresh: u32,
+}, "BrickScrollSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", BRICK_SCROLL_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("brick_scroll_runs", WebGPUArray.from(vec4i))
+    .addStorageTexture("brick_map", "r32uint", "3d", "read-write")
+    .addStorageTexture("brick_occupancy", "r32uint", "3d", "write-only")
+    .add(BRICK_STATE_RESOURCE)
+    .add(BRICK_RING_RESOURCE)
+    .add(BRICK_PENDING_RESOURCE)
+    .add(BRICK_FREE_RESOURCE);
+
+/**
+ * Scroll (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.4): a thread a cell a window exposed this frame.
+ *
+ * The exposed cells come as boxes, two `vec4<i32>` a box in `brick_scroll_runs`: the box's smallest
+ * cell and its cascade, then its size and its first thread. Its cells run x fastest. A cell's storage
+ * cell held a cell that has left the window: its slot, if it had one, goes back on the free list, its
+ * entry becomes UNKNOWN, and its key is queued unless it already is. Its occupancy block is marked as
+ * having cells to read, every one, until coarse counts it once the cell is built: a ray must not
+ * skip a cell it should read from the next cascade out.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_scroll = ComputeShader.from({
+    label: "Brick Clipmap Scroll",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${BRICK_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let thread = (workgroup_id.y * settings.groups_x + workgroup_id.x) * BRICK_THREAD_WORKGROUP_SIZE + lane;
+
+    if (thread >= settings.cell_count) {
+        return;
+    }
+
+    // the box: the last whose first thread is at or below this one
+    var low = 0u;
+    var high = settings.run_count;
+
+    while (high - low > 1u) {
+        let middle = (low + high) / 2u;
+
+        if (u32(brick_scroll_runs[2u * middle + 1u].w) <= thread) {
+            low = middle;
+        } else {
+            high = middle;
+        }
+    }
+
+    let corner = brick_scroll_runs[2u * low];
+    let extent = brick_scroll_runs[2u * low + 1u];
+
+    let size = vec3<u32>(extent.xyz);
+    let local = thread - u32(extent.w);
+    let cell = corner.xyz + vec3<i32>(vec3<u32>(local % size.x, (local / size.x) % size.y, local / (size.x * size.y)));
+
+    let cascade = u32(corner.w);
+    let resolution = settings.resolution;
+    let storage = vec3<u32>(clipmap_storage_coord(cell, vec3<i32>(i32(resolution))));
+    let texel = brick_clipmap_map_texel(cascade, storage, resolution);
+
+    if (settings.fresh == 0u) {
+        let old = textureLoad(brick_map, texel).x;
+
+        if (brick_clipmap_entry_holds_slot(old)) {
+            slot_stack_push(&brick_state[BRICK_STATE_FREE], &brick_free, old);
+        }
+    }
+
+    textureStore(brick_map, texel, vec4<u32>(BRICK_CLIPMAP_UNKNOWN, 0u, 0u, 0u));
+
+    // the block's every cell may be one to read; cells of a block write the same
+    let block = storage / ${BRICK_OCCUPANCY_BLOCK}u;
+
+    textureStore(brick_occupancy, vec3<u32>(block.xy, block.z + cascade * (resolution / ${BRICK_OCCUPANCY_BLOCK}u)), vec4<u32>(${BRICK_OCCUPANCY_BLOCK ** 3}u, 0u, 0u, 0u));
+
+    brick_clipmap_enqueue(brick_clipmap_key(cascade, storage, resolution), settings.ring_capacity);
+}
+`, [
+            chunk_brick_clipmap,
+            chunk_brick_clipmap_enqueue,
+            chunk_clipmap_storage_coord,
+            chunk_slot_stack,
+        ]),
+});

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_store.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_STORE_SETTINGS: WebGPUStruct;
+/**
+ * Store (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.5): a workgroup a taken cell, eight texels a lane,
+ * after free.
+ *
+ * A cell free marked pops a slot: lane 0 pops it and writes the entry, and the slot reaches the other
+ * lanes through the workgroup. Take held the frame to the free slots, so the pop is never refused. A
+ * cell that holds a slot, its own or the one just popped, has its 512 staged bytes written into the
+ * slot's atlas tile and its 64 objects into the slot's object cells; a cell free made EMPTY writes
+ * nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_store: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_brick_clipmap_store.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_brick_clipmap_store.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_store.js"],"names":[],"mappings":"AAoBA;;GAEG;AACH,mCAFU,YAAY,CASG;AAgBzB;;;;;;;;;;;GAWG;AACH,yCAFU,aAAa,CAsEpB;6BAvH0B,sCAAsC;8BAJrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_store.js

@@ -0,0 +1,127 @@
+import { chunk_slot_stack } from "../../../gpu_primitive/slot_stack/chunk_slot_stack.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { chunk_tile_atlas_slot_origin } from "../../../texture/atlas/chunk_tile_atlas_slot_origin.js";
+import { MESH_SDF_BRICK_TEXELS } from "../../../geometry/sdf/MESH_SDF.js";
+import { BRICK_CELL_WORKGROUP_SIZE } from "./BRICK_CLIPMAP.js";
+import {
+    BRICK_FREE_RESOURCE,
+    BRICK_RING_RESOURCE,
+    BRICK_STAGING_RESOURCE,
+    BRICK_STATE_RESOURCE,
+    BRICK_TAKE_RESOURCE,
+    chunk_brick_clipmap
+} from "./chunk_brick_clipmap.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_STORE_SETTINGS = WebGPUStruct.from({
+    /** keys `brick_ring` holds, a power of two */
+    ring_capacity: u32,
+    /** cells a cascade's window has a side */
+    resolution: u32,
+    /** slots the atlas and the object cells hold: what bounds a pop */
+    capacity: u32,
+}, "BrickStoreSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", BRICK_STORE_SETTINGS);
+
+resources.createGroup()
+    .add(BRICK_STATE_RESOURCE)
+    .add(BRICK_TAKE_RESOURCE)
+    .add(BRICK_RING_RESOURCE)
+    .add(BRICK_FREE_RESOURCE)
+    .add(BRICK_STAGING_RESOURCE)
+    .addStorageBuffer("brick_objects", WebGPUArray.u32, true)
+    .addStorageTexture("brick_map", "r32uint", "3d", "read-write")
+    .addStorageTexture("brick_atlas_store", "r8unorm", "3d", "write-only");
+
+/**
+ * Store (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.5): a workgroup a taken cell, eight texels a lane,
+ * after free.
+ *
+ * A cell free marked pops a slot: lane 0 pops it and writes the entry, and the slot reaches the other
+ * lanes through the workgroup. Take held the frame to the free slots, so the pop is never refused. A
+ * cell that holds a slot, its own or the one just popped, has its 512 staged bytes written into the
+ * slot's atlas tile and its 64 objects into the slot's object cells; a cell free made EMPTY writes
+ * nothing.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_store = ComputeShader.from({
+    label: "Brick Clipmap Store",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+var<workgroup> cell_slot: u32;
+
+@compute @workgroup_size(${BRICK_CELL_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let build = folded_workgroup_index(workgroup_id);
+
+    if (lane == 0u) {
+        var slot = SLOT_STACK_NONE;
+
+        if (build < brick_take[BRICK_TAKE_COUNT]) {
+            let key = brick_ring[(brick_take[BRICK_TAKE_FIRST] + build) & (settings.ring_capacity - 1u)];
+            let resolution = settings.resolution;
+            let texel = brick_clipmap_map_texel(brick_clipmap_key_cascade(key, resolution), brick_clipmap_key_storage(key, resolution), resolution);
+            let entry = textureLoad(brick_map, texel).x;
+
+            if (entry == BRICK_CLIPMAP_STORE_PENDING) {
+                slot = slot_stack_pop(&brick_state[BRICK_STATE_FREE], &brick_free, settings.capacity);
+
+                textureStore(brick_map, texel, vec4<u32>(slot, 0u, 0u, 0u));
+            } else if (brick_clipmap_entry_holds_slot(entry)) {
+                slot = entry;
+            }
+        }
+
+        cell_slot = slot;
+    }
+
+    let slot = workgroupUniformLoad(&cell_slot);
+
+    if (slot == SLOT_STACK_NONE) {
+        return;
+    }
+
+    let t = ${MESH_SDF_BRICK_TEXELS}u;
+    let slots = textureDimensions(brick_atlas_store) / t;
+    let origin = tile_atlas_slot_origin(slot, slots.xy, vec3<u32>(t));
+
+    // the lane's eight texels run along x: its two words, four texels each
+    let first = build * BRICK_STAGING_WORDS + 2u * lane;
+    let row = origin + vec3<u32>(0u, lane % t, lane / t);
+
+    for (var w = 0u; w < 2u; w++) {
+        let word = brick_staging[first + w];
+
+        for (var b = 0u; b < 4u; b++) {
+            let byte = (word >> (8u * b)) & 0xffu;
+
+            textureStore(brick_atlas_store, row + vec3<u32>(4u * w + b, 0u, 0u), vec4<f32>(f32(byte) / 255.0, 0.0, 0.0, 0.0));
+        }
+    }
+
+    brick_objects[slot * BRICK_OBJECT_CELLS + lane] = brick_staging[build * BRICK_STAGING_WORDS + BRICK_STAGING_DISTANCE_WORDS + lane];
+}
+`, [
+            chunk_brick_clipmap,
+            chunk_folded_workgroup_index,
+            chunk_slot_stack,
+            chunk_tile_atlas_slot_origin,
+        ]),
+});

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_take.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_TAKE_SETTINGS: WebGPUStruct;
+/**
+ * Take (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.4): one thread. The frame's keys off the ring, as many
+ * as are queued up to the budget, and no more than there are free slots, since every cell taken may
+ * need one: so no pop of store's fails. A take the free slots held back counts itself starved, and the
+ * host grows the capacity, as the mesh bake does (§6.4).
+ *
+ * Build slot `b` is taken key `b`, at ring position `taken_first + b`. Writes them, and the frame's
+ * two dispatches, folded past the per-dimension limit, into `brick_take`: a workgroup a taken cell,
+ * and a thread a staging word of the taken cells.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_take: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_brick_clipmap_take.d.ts.map