@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace_command.d.ts

@@ -5,12 +5,16 @@ export const PROBE_TRACE_COMMAND_SETTINGS: WebGPUStruct;
 /**
  * The update's commands (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): one thread, once the due passes
  * have listed the frame's updates, the list's count clamped to U:
- * - a thread a listed probe, at `PROBE_DISPATCH_TRACED`: relocation and the probes' projection;
- * - a thread a ray of theirs, R a probe, at `PROBE_DISPATCH_RAYS`: trace and shade;
+ * - a thread a listed probe, at `PROBE_DISPATCH_TRACED`: relocation, the ray counts and the probes'
+ *   projection;
  * - a thread a texel of their maps, n_r² + n_d² a probe, at `PROBE_DISPATCH_TEXELS`: accumulate;
  * - a thread a row of their radiance maps, n_r a probe, at `PROBE_DISPATCH_ROWS`: the projection's rows;
  * - a thread a texel of their tiles, (n_r + 2)² + (n_d + 2)² a probe, at `PROBE_DISPATCH_PUBLISH`.
  *
+ * It writes the count of the ray counts, the ray requests and the rays' layout, the probes listed, which
+ * the passes after fill in (`shader_probe_clipmap_ray_layout.js`): a probe's rays are its own update's,
+ * even when none is listed.
+ *
  * @type {ComputeShader}
  */
 export const shader_probe_clipmap_trace_command: ComputeShader;

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace_command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_trace_command.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace_command.js"],"names":[],"mappings":"AAQA;;GAEG;AACH,2CAFU,YAAY,CAWU;AAUhC;;;;;;;;;;GAUG;AACH,iDAFU,aAAa,CAgDpB;6BAlF0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_trace_command.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace_command.js"],"names":[],"mappings":"AAeA;;GAEG;AACH,2CAFU,YAAY,CASU;AAahC;;;;;;;;;;;;;;GAcG;AACH,iDAFU,aAAa,CAoDpB;6BAlG0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_trace_command.js

@@ -4,7 +4,14 @@ 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 { chunk_probe_clipmap, PROBE_DISPATCH_RESOURCE, PROBE_TRACE_READ_RESOURCE } from "./chunk_probe_clipmap.js";
+import {
+    chunk_probe_clipmap,
+    PROBE_DISPATCH_RESOURCE,
+    PROBE_RAY_COUNTS_WRITE_RESOURCE,
+    PROBE_RAY_REQUESTS_WRITE_RESOURCE,
+    PROBE_RAY_SUMS_WRITE_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
 
 /**
  * @type {WebGPUStruct}
@@ -12,8 +19,6 @@ import { chunk_probe_clipmap, PROBE_DISPATCH_RESOURCE, PROBE_TRACE_READ_RESOURCE
 export const PROBE_TRACE_COMMAND_SETTINGS = WebGPUStruct.from({
     /** probes a frame updates at most: the trace list's bound */
     trace_capacity: u32,
-    /** rays an update casts, R */
-    rays_per_probe: u32,
     /** octahedral radiance texels a side, n_r */
     radiance_resolution: u32,
     /** octahedral depth texels a side, n_d */
@@ -26,17 +31,24 @@ resources.setImmediate("settings", PROBE_TRACE_COMMAND_SETTINGS);
 
 resources.createGroup()
     .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_RAY_COUNTS_WRITE_RESOURCE)
+    .add(PROBE_RAY_REQUESTS_WRITE_RESOURCE)
+    .add(PROBE_RAY_SUMS_WRITE_RESOURCE)
     .add(PROBE_DISPATCH_RESOURCE);
 
 /**
  * The update's commands (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): one thread, once the due passes
  * have listed the frame's updates, the list's count clamped to U:
- * - a thread a listed probe, at `PROBE_DISPATCH_TRACED`: relocation and the probes' projection;
- * - a thread a ray of theirs, R a probe, at `PROBE_DISPATCH_RAYS`: trace and shade;
+ * - a thread a listed probe, at `PROBE_DISPATCH_TRACED`: relocation, the ray counts and the probes'
+ *   projection;
  * - a thread a texel of their maps, n_r² + n_d² a probe, at `PROBE_DISPATCH_TEXELS`: accumulate;
  * - a thread a row of their radiance maps, n_r a probe, at `PROBE_DISPATCH_ROWS`: the projection's rows;
  * - a thread a texel of their tiles, (n_r + 2)² + (n_d + 2)² a probe, at `PROBE_DISPATCH_PUBLISH`.
  *
+ * It writes the count of the ray counts, the ray requests and the rays' layout, the probes listed, which
+ * the passes after fill in (`shader_probe_clipmap_ray_layout.js`): a probe's rays are its own update's,
+ * even when none is listed.
+ *
  * @type {ComputeShader}
  */
 export const shader_probe_clipmap_trace_command = ComputeShader.from({
@@ -54,11 +66,9 @@ fn main() {
     probe_dispatch[PROBE_DISPATCH_TRACED + 1u] = probes.y;
     probe_dispatch[PROBE_DISPATCH_TRACED + 2u] = probes.z;
 
-    let rays = folded_dispatch((traced * settings.rays_per_probe + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
-
-    probe_dispatch[PROBE_DISPATCH_RAYS] = rays.x;
-    probe_dispatch[PROBE_DISPATCH_RAYS + 1u] = rays.y;
-    probe_dispatch[PROBE_DISPATCH_RAYS + 2u] = rays.z;
+    probe_ray_counts.count = traced;
+    probe_ray_requests.count = traced;
+    probe_ray_sums.count = traced;
 
     let n = settings.radiance_resolution;
     let m = settings.depth_resolution;
@@ -80,6 +90,12 @@ fn main() {
     probe_dispatch[PROBE_DISPATCH_PUBLISH] = tiles.x;
     probe_dispatch[PROBE_DISPATCH_PUBLISH + 1u] = tiles.y;
     probe_dispatch[PROBE_DISPATCH_PUBLISH + 2u] = tiles.z;
+
+    let runs = folded_dispatch((traced + PROBE_ORDER_RUN - 1u) / PROBE_ORDER_RUN);
+
+    probe_dispatch[PROBE_DISPATCH_ORDER] = runs.x;
+    probe_dispatch[PROBE_DISPATCH_ORDER + 1u] = runs.y;
+    probe_dispatch[PROBE_DISPATCH_ORDER + 2u] = runs.z;
 }
 `, [
             chunk_probe_clipmap,

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want.d.ts

@@ -6,18 +6,14 @@ export const PROBE_WANT_SETTINGS: WebGPUStruct;
  * Want (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a tile of {@link PROBE_WANT_TILE}² pixels,
  * the launch the screen's tiles.
  *
- * Each frame a tile wants the probes of one of its pixels, picked by STBN at (tile, frame), the cages
- * that pixel's pick reads (§9.1): the finest cascade whose cage window holds the point, the cage of
- * the point biased `0.1` of that cascade's spacing along `mix(n, v, 0.2)`, and in the cascade's blend
- * skirt the next cascade's cage too, biased by its own spacing. A sky pixel wants nothing; neither does
- * a cage a bias moved out of its window. Each cage point's bit is set, and a point whose bit was clear
- * goes on the wanted list, so the list holds every point wanted this frame once.
+ * Each frame a tile wants the probes of one of its pixels, picked by STBN at (tile, frame): the cages
+ * that pixel's pick reads (§9.1), biased along `mix(n, v, 0.2)`, through `probe_clipmap_want`. A sky
+ * pixel wants nothing. Its points go on the wanted list as the screen's, `PROBE_WANTED_SCREEN`; want runs
+ * before the hits' wants, so a point both want is the screen's.
  *
  * At a cascade's outer edge a lattice cell is 58 pixels on a 1080p screen at a 60° field of view, and
  * 19 at 120°, so a tile of 8 samples every cell several times a frame, and a workgroup's 64 tiles want
- * a few cages between them. So the first lane of a workgroup to want a cage claims it in the
- * workgroup's table and sets its bits; the rest want it through that lane. Measured on the AMD iGPU at
- * 1280×720 on Sponza, the bits' atomics were 140 of want's 345 µs and the appends 90.
+ * a few cages between them, which its claims keep to one want each.
  *
  * @type {ComputeShader}
  */

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_want.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want.js"],"names":[],"mappings":"AAoCA;;GAEG;AACH,kCAFU,YAAY,CAUE;AAexB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCAFU,aAAa,CAuHpB;6BAxL0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_want.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want.js"],"names":[],"mappings":"AAqBA;;GAEG;AACH,kCAFU,YAAY,CAUE;AAexB;;;;;;;;;;;;;;GAcG;AACH,wCAFU,aAAa,CAqCpB;6BAtF0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want.js

@@ -1,8 +1,5 @@
 import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { chunk_collection_u32_append } from "../../../gpu_primitive/chunk_collection_u32_append.js";
 import { chunk_project_position_from_depth } from "../../../shader/chunk/camera/chunk_project_position_from_depth.js";
-import { chunk_clipmap_contains } from "../../../shader/chunk/clipmap/chunk_clipmap_contains.js";
-import { chunk_clipmap_select_finest } from "../../../shader/chunk/clipmap/chunk_clipmap_select_finest.js";
 import { chunk_is_background } from "../../../shader/chunk/depth/chunk_is_background.js";
 import { chunk_mat4_extract_position } from "../../../shader/chunk/geometry/mat4/chunk_mat4_extract_position.js";
 import { chunk_decode_g_buffer_normal } from "../../../shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
@@ -19,20 +16,8 @@ import {
     PROBE_WANTED_BITS_RESOURCE,
     PROBE_WANTED_WRITE_RESOURCE
 } from "./chunk_probe_clipmap.js";
-import { PROBE_RECEIVER_BIAS, PROBE_RECEIVER_BIAS_VIEW, PROBE_WANT_TILE, PROBE_WANT_WORKGROUP_TILES } from "./PROBE_CLIPMAP.js";
-
-/**
- * Slots of a workgroup's claim table: twice the claims its lanes make at most, a cage in each of two
- * cascades a lane, so a probe finds a slot within a few.
- * @type {number}
- */
-const WANT_CLAIM_SLOTS = 2 * 2 * PROBE_WANT_WORKGROUP_TILES ** 2;
-
-/**
- * Slots a claim tries before it wants its cage anyway: a bound, which a half-full table does not reach.
- * @type {number}
- */
-const WANT_CLAIM_PROBES = 16;
+import { chunk_probe_clipmap_want } from "./chunk_probe_clipmap_want.js";
+import { PROBE_RECEIVER_BIAS_VIEW, PROBE_WANT_TILE, PROBE_WANT_WORKGROUP_TILES } from "./PROBE_CLIPMAP.js";
 
 /**
  * @type {WebGPUStruct}
@@ -64,18 +49,14 @@ resources.createGroup()
  * Want (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a tile of {@link PROBE_WANT_TILE}² pixels,
  * the launch the screen's tiles.
  *
- * Each frame a tile wants the probes of one of its pixels, picked by STBN at (tile, frame), the cages
- * that pixel's pick reads (§9.1): the finest cascade whose cage window holds the point, the cage of
- * the point biased `0.1` of that cascade's spacing along `mix(n, v, 0.2)`, and in the cascade's blend
- * skirt the next cascade's cage too, biased by its own spacing. A sky pixel wants nothing; neither does
- * a cage a bias moved out of its window. Each cage point's bit is set, and a point whose bit was clear
- * goes on the wanted list, so the list holds every point wanted this frame once.
+ * Each frame a tile wants the probes of one of its pixels, picked by STBN at (tile, frame): the cages
+ * that pixel's pick reads (§9.1), biased along `mix(n, v, 0.2)`, through `probe_clipmap_want`. A sky
+ * pixel wants nothing. Its points go on the wanted list as the screen's, `PROBE_WANTED_SCREEN`; want runs
+ * before the hits' wants, so a point both want is the screen's.
  *
  * At a cascade's outer edge a lattice cell is 58 pixels on a 1080p screen at a 60° field of view, and
  * 19 at 120°, so a tile of 8 samples every cell several times a frame, and a workgroup's 64 tiles want
- * a few cages between them. So the first lane of a workgroup to want a cage claims it in the
- * workgroup's table and sets its bits; the rest want it through that lane. Measured on the AMD iGPU at
- * 1280×720 on Sponza, the bits' atomics were 140 of want's 345 µs and the appends 90.
+ * a few cages between them, which its claims keep to one want each.
  *
  * @type {ComputeShader}
  */
@@ -85,47 +66,6 @@ export const shader_probe_clipmap_want = ComputeShader.from({
     body: CodeChunk.from(
         //language=WGSL
         `
-// the cages the workgroup's lanes have claimed, by their key plus one; zero at the workgroup's start
-var<workgroup> probe_want_claims: array<atomic<u32>, ${WANT_CLAIM_SLOTS}>;
-
-// the cell whose corners are the cascade's cage around a point biased by its spacing, and whether the
-// cascade's cage window holds it
-fn probe_want_cage(cascade: u32, position: vec3<f32>, bias_direction: vec3<f32>, cage: ptr<function, vec3<i32>>) -> bool {
-    let level = probe_levels[cascade];
-    let biased = position + bias_direction * (${PROBE_RECEIVER_BIAS} * level.cell_size);
-
-    *cage = vec3<i32>(floor(biased / level.cell_size));
-
-    return clipmap_contains(*cage, level.corner, level.size);
-}
-
-// whether this lane is the first of its workgroup to want the cage whose least point has \`key\`; a lane
-// that finds no room in its probes wants it as well, which the bits make harmless
-fn probe_want_claim(key: u32) -> bool {
-    let tag = key + 1u;
-
-    var at = (tag * 2654435761u) >> ${32 - Math.log2(WANT_CLAIM_SLOTS)}u;
-
-    for (var probe = 0u; probe < ${WANT_CLAIM_PROBES}u; probe++) {
-        let seen = atomicCompareExchangeWeak(&probe_want_claims[at], 0u, tag);
-
-        if (seen.exchanged) {
-            return true;
-        }
-
-        if (seen.old_value == tag) {
-            return false;
-        }
-
-        // another cage's slot: the next one; an empty slot that failed spuriously is tried again
-        if (seen.old_value != 0u) {
-            at = (at + 1u) & ${WANT_CLAIM_SLOTS - 1}u;
-        }
-    }
-
-    return true;
-}
-
 @compute @workgroup_size(${PROBE_WANT_WORKGROUP_TILES}, ${PROBE_WANT_WORKGROUP_TILES})
 fn main(@builtin(global_invocation_id) id: vec3<u32>) {
     let size = textureDimensions(gBufferDepth);
@@ -144,46 +84,7 @@ fn main(@builtin(global_invocation_id) id: vec3<u32>) {
     let view_direction = normalize(mat4_extract_position(camera.transform) - position);
     let bias_direction = mix(normal, view_direction, ${PROBE_RECEIVER_BIAS_VIEW});
 
-    let selection = clipmap_select_finest(&probe_levels, settings.cascade_count, position, PROBE_BLEND_SKIRT);
-
-    let surface = on_screen && !is_background(depth) && selection.level != CLIPMAP_LEVEL_NONE;
-    let finest = select(0u, selection.level, surface);
-    let next = min(finest + 1u, settings.cascade_count - 1u);
-
-    var cage_finest: vec3<i32>;
-    var cage_next: vec3<i32>;
-
-    let resolution = settings.resolution;
-
-    // storage wraps by the window's side, a power of two: the low bits of a point, negative ones too
-    let wrap = vec3<u32>(resolution - 1u);
-
-    let wants_finest = surface && probe_want_cage(finest, position, bias_direction, &cage_finest)
-        && probe_want_claim(probe_clipmap_key(finest, vec3<u32>(cage_finest) & wrap, resolution));
-    let wants_next = surface && selection.edge_weight > 0.0 && finest + 1u < settings.cascade_count
-        && probe_want_cage(next, position, bias_direction, &cage_next)
-        && probe_want_claim(probe_clipmap_key(next, vec3<u32>(cage_next) & wrap, resolution));
-
-    // every lane through all sixteen corners, so that the appends stay in uniform control flow
-    for (var k = 0u; k < 16u; k++) {
-        let coarse = k >= 8u;
-        let cascade = select(finest, next, coarse);
-        let wants = select(wants_finest, wants_next, coarse);
-        let corner = vec3<i32>(vec3<u32>(k & 1u, (k >> 1u) & 1u, (k >> 2u) & 1u));
-        let point = select(cage_finest, cage_next, coarse) + corner;
-
-        let storage = vec3<u32>(point) & wrap;
-        let key = probe_clipmap_key(cascade, storage, resolution);
-        let bit = 1u << (key & 31u);
-
-        var first = false;
-
-        if (wants) {
-            first = (atomicOr(&probe_wanted_bits[key >> 5u], bit) & bit) == 0u;
-        }
-
-        collection_u32_append(&probe_wanted, first, key, settings.key_count);
-    }
+    probe_clipmap_want(on_screen && !is_background(depth), position, bias_direction, settings.cascade_count, settings.resolution, settings.key_count, PROBE_WANTED_SCREEN);
 }
 `, [
             chunk_probe_clipmap,
@@ -192,8 +93,6 @@ fn main(@builtin(global_invocation_id) id: vec3<u32>) {
             chunk_decode_g_buffer_normal,
             chunk_mat4_extract_position,
             chunk_is_background,
-            chunk_clipmap_select_finest,
-            chunk_clipmap_contains,
-            chunk_collection_u32_append,
+            chunk_probe_clipmap_want,
         ]),
 });

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_hits.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_WANT_HITS_SETTINGS: WebGPUStruct;
+/**
+ * The hits' wants (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3, §8.7, D31): a thread a ray of the last
+ * frame's updates, after want and before admit, through the launch those rays had,
+ * `PROBE_DISPATCH_RAYS`, before the frame's trace command writes it over.
+ *
+ * A front-face hit that bounces anything wants the cages its pick reads, as a pixel does: the light pass
+ * takes the hit's next bounce from those probes. So a probe a hit needs is admitted where nothing on
+ * screen wanted one, and kept while hits read it. Until its first update a NEW probe weighs nothing and
+ * the hit takes no bounce: light is lost for a frame or two, never invented.
+ *
+ * Only a probe a pixel wanted in the frame of its update has hits that want, so the probes hits wanted
+ * want nothing in turn: the chain stops after one step, as Enshrouded's world-cache probes do. Unstopped,
+ * hits would want a probe at every surface the windows hold, the dense lattice D31 turned down.
+ *
+ * It binds the last frame's trace list, origins and rays, which the frame's trace writes over later. A ray
+ * names its probe, its place in that list, in its flags; a record of no ray (`PROBE_RAY_NONE`) is past
+ * that frame's last.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_want_hits: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_want_hits.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_hits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_want_hits.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_hits.js"],"names":[],"mappings":"AAqBA;;GAEG;AACH,uCAFU,YAAY,CAQM;AAe5B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6CAFU,aAAa,CA8CpB;6BAvG0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_hits.js

@@ -0,0 +1,110 @@
+import { chunk_uv_octahedral_unit_decode } from "../../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_decode.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 { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    chunk_probe_clipmap,
+    chunk_probe_clipmap_ray_origin,
+    PROBE_LEVELS_RESOURCE,
+    PROBE_ORIGINS_READ_RESOURCE,
+    PROBE_RAYS_READ_RESOURCE,
+    PROBE_RECORDS_READ_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE,
+    PROBE_WANTED_BITS_RESOURCE,
+    PROBE_WANTED_WRITE_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { chunk_probe_clipmap_want } from "./chunk_probe_clipmap_want.js";
+import { PROBE_RECEIVER_BIAS_VIEW, PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_WANT_HITS_SETTINGS = WebGPUStruct.from({
+    cascade_count: u32,
+    /** lattice points a cascade's window has a side */
+    resolution: u32,
+    /** keys over every cascade: what the wanted list holds at most */
+    key_count: u32,
+}, "ProbeWantHitsSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_WANT_HITS_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_ORIGINS_READ_RESOURCE)
+    .add(PROBE_RAYS_READ_RESOURCE)
+    .add(PROBE_RECORDS_READ_RESOURCE)
+    .add(PROBE_LEVELS_RESOURCE)
+    .add(PROBE_WANTED_BITS_RESOURCE)
+    .add(PROBE_WANTED_WRITE_RESOURCE);
+
+/**
+ * The hits' wants (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3, §8.7, D31): a thread a ray of the last
+ * frame's updates, after want and before admit, through the launch those rays had,
+ * `PROBE_DISPATCH_RAYS`, before the frame's trace command writes it over.
+ *
+ * A front-face hit that bounces anything wants the cages its pick reads, as a pixel does: the light pass
+ * takes the hit's next bounce from those probes. So a probe a hit needs is admitted where nothing on
+ * screen wanted one, and kept while hits read it. Until its first update a NEW probe weighs nothing and
+ * the hit takes no bounce: light is lost for a frame or two, never invented.
+ *
+ * Only a probe a pixel wanted in the frame of its update has hits that want, so the probes hits wanted
+ * want nothing in turn: the chain stops after one step, as Enshrouded's world-cache probes do. Unstopped,
+ * hits would want a probe at every surface the windows hold, the dense lattice D31 turned down.
+ *
+ * It binds the last frame's trace list, origins and rays, which the frame's trace writes over later. A ray
+ * names its probe, its place in that list, in its flags; a record of no ray (`PROBE_RAY_NONE`) is past
+ * that frame's last.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_want_hits = ComputeShader.from({
+    label: "Probe Clipmap Want Hits",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${PROBE_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let ray = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
+
+    var wants = false;
+    var position = vec3<f32>(0.0);
+    var bias_direction = vec3<f32>(0.0);
+
+    let record = probe_rays[ray];
+
+    if ((record.flags & PROBE_RAY_KIND_MASK) != PROBE_RAY_NONE) {
+        let k = record.flags >> PROBE_RAY_PROBE_SHIFT;
+        let slot = probe_trace.elements[k];
+
+        // shade left a front-face hit's albedo in its row and zero in any other ray's: a ray that takes no
+        // bounce, a black hit's among them, wants nothing
+        wants = record.row != 0u && (probe_records[slot].flags & PROBE_RECORD_SCREEN) != 0u;
+
+        let direction = uv_octahedral_unit_decode(unpack2x16unorm(record.direction));
+        let normal = uv_octahedral_unit_decode(unpack2x16unorm(record.normal));
+
+        position = probe_clipmap_ray_origin(probe_origins[k], slot, record.direction) + record.t * direction;
+        // the view back along the ray, as the light pass's pick takes it
+        bias_direction = mix(normal, -direction, ${PROBE_RECEIVER_BIAS_VIEW});
+    }
+
+    probe_clipmap_want(wants, position, bias_direction, settings.cascade_count, settings.resolution, settings.key_count, 0u);
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_probe_clipmap_ray_origin,
+            chunk_folded_workgroup_index,
+            chunk_uv_octahedral_unit_decode,
+            chunk_probe_clipmap_want,
+        ]),
+});

package/src/shade/renderer/gpu_primitive/sort/SORT_DIGIT_SETTINGS_STRUCT.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Per-digit-pass constants of a sort over a device count, shared by
+ * {@link shader_radix_sort_histogram_indirect} and {@link shader_radix_sort_scatter_indirect}. The
+ * host knows these; the size of the input it does not, and that lives in {@link SORT_SIZE_STRUCT}.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_DIGIT_SETTINGS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=SORT_DIGIT_SETTINGS_STRUCT.d.ts.map

package/src/shade/renderer/gpu_primitive/sort/SORT_DIGIT_SETTINGS_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SORT_DIGIT_SETTINGS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/SORT_DIGIT_SETTINGS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,yCAFU,YAAY,CAYE;6BAnBK,mCAAmC"}

package/src/shade/renderer/gpu_primitive/sort/SORT_DIGIT_SETTINGS_STRUCT.js

@@ -0,0 +1,21 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Per-digit-pass constants of a sort over a device count, shared by
+ * {@link shader_radix_sort_histogram_indirect} and {@link shader_radix_sort_scatter_indirect}. The
+ * host knows these; the size of the input it does not, and that lives in {@link SORT_SIZE_STRUCT}.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_DIGIT_SETTINGS_STRUCT = WebGPUStruct.from({
+    /**
+     * Bit position of the digit this pass sorts on — 0, 8, 16, 24.
+     */
+    shift: u32,
+    /**
+     * The key's bits, `key_bits` of them set from the bottom: what a digit is selected from. See
+     * `sort_extract_key_digit` in {@link chunk_sort_digit}.
+     */
+    key_mask: u32,
+}, "SortDigitSettings");

package/src/shade/renderer/gpu_primitive/sort/SORT_PASS_SETTINGS_STRUCT.d.ts

@@ -1,6 +1,9 @@
 /**
- * Per-digit-pass constants, shared by the histogram and the scatter so the two agree on which keys
- * exist and where their counts live in the spine.
+ * Per-digit-pass constants of a sort over a host count, shared by the histogram and the scatter so
+ * the two agree on which keys exist and where their counts live in the spine.
+ *
+ * A sort over a device count reads `element_count` and `tile_count` from {@link SORT_SIZE_STRUCT}
+ * instead, and carries the rest as {@link SORT_DIGIT_SETTINGS_STRUCT}.
  *
  * @type {WebGPUStruct}
  */

package/src/shade/renderer/gpu_primitive/sort/SORT_PASS_SETTINGS_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SORT_PASS_SETTINGS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/SORT_PASS_SETTINGS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wCAFU,YAAY,CAeC;6BArBM,mCAAmC"}
+{"version":3,"file":"SORT_PASS_SETTINGS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/SORT_PASS_SETTINGS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,wCAFU,YAAY,CAoBC;6BA7BM,mCAAmC"}

package/src/shade/renderer/gpu_primitive/sort/SORT_PASS_SETTINGS_STRUCT.js

@@ -1,23 +1,31 @@
-import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
-
-/**
- * Per-digit-pass constants, shared by the histogram and the scatter so the two agree on which keys
- * exist and where their counts live in the spine.
- *
- * @type {WebGPUStruct}
- */
-export const SORT_PASS_SETTINGS_STRUCT = WebGPUStruct.from({
-    /**
-     * Bit position of the digit this pass sorts on — 0, 8, 16, 24.
-     */
-    shift: u32,
-    /**
-     * Keys in the input. The tail tile is partial and every read is bounds-checked against this.
-     */
-    element_count: u32,
-    /**
-     * Number of tiles, which is the stride between adjacent bins in the bin-major spine.
-     */
-    tile_count: u32,
-}, "SortPassSettings");
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Per-digit-pass constants of a sort over a host count, shared by the histogram and the scatter so
+ * the two agree on which keys exist and where their counts live in the spine.
+ *
+ * A sort over a device count reads `element_count` and `tile_count` from {@link SORT_SIZE_STRUCT}
+ * instead, and carries the rest as {@link SORT_DIGIT_SETTINGS_STRUCT}.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_PASS_SETTINGS_STRUCT = WebGPUStruct.from({
+    /**
+     * Bit position of the digit this pass sorts on — 0, 8, 16, 24.
+     */
+    shift: u32,
+    /**
+     * Keys in the input. The tail tile is partial and every read is bounds-checked against this.
+     */
+    element_count: u32,
+    /**
+     * Number of tiles, which is the stride between adjacent bins in the bin-major spine.
+     */
+    tile_count: u32,
+    /**
+     * The key's bits, `key_bits` of them set from the bottom: what a digit is selected from. See
+     * `sort_extract_key_digit` in {@link chunk_sort_digit}.
+     */
+    key_mask: u32,
+}, "SortPassSettings");

package/src/shade/renderer/gpu_primitive/sort/SORT_SIZE_STRUCT.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The live size of a sort over a device count, written once by {@link shader_radix_sort_prepare} and
+ * read by every histogram and scatter after it. The same two numbers a host-count sort carries in
+ * {@link SORT_PASS_SETTINGS_STRUCT}, which the host cannot know here.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_SIZE_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=SORT_SIZE_STRUCT.d.ts.map

package/src/shade/renderer/gpu_primitive/sort/SORT_SIZE_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SORT_SIZE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/SORT_SIZE_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,+BAFU,YAAY,CAaP;6BApBc,mCAAmC"}

package/src/shade/renderer/gpu_primitive/sort/SORT_SIZE_STRUCT.js

@@ -0,0 +1,22 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * The live size of a sort over a device count, written once by {@link shader_radix_sort_prepare} and
+ * read by every histogram and scatter after it. The same two numbers a host-count sort carries in
+ * {@link SORT_PASS_SETTINGS_STRUCT}, which the host cannot know here.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SORT_SIZE_STRUCT = WebGPUStruct.from({
+    /**
+     * Keys being sorted: the device count, at most the sort's `element_max_count`. The tail tile is
+     * partial and every read is bounds-checked against this.
+     */
+    element_count: u32,
+    /**
+     * Tiles those keys fill, which is the stride between adjacent bins in the bin-major spine and the
+     * number of workgroups the histogram and scatter are dispatched over.
+     */
+    tile_count: u32,
+}, "SortSize");

package/src/shade/renderer/gpu_primitive/sort/chunk_sort_constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The sort's tile geometry from `defs.js`, as WGSL constants: one declaration for every chunk and
+ * shader of the sort that links it, rather than a copy in each.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_constants: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sort_constants.d.ts.map

package/src/shade/renderer/gpu_primitive/sort/chunk_sort_constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sort_constants.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/sort/chunk_sort_constants.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,mCAFU,SAAS,CAUhB;0BAjBuB,oCAAoC"}

package/src/shade/renderer/gpu_primitive/sort/chunk_sort_constants.js

@@ -0,0 +1,18 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { RADIX, RADIX_LOG, SORT_KEYS_PER_THREAD, SORT_TILE_SIZE, SORT_WORKGROUP_SIZE } from "./defs.js";
+
+/**
+ * The sort's tile geometry from `defs.js`, as WGSL constants: one declaration for every chunk and
+ * shader of the sort that links it, rather than a copy in each.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sort_constants = CodeChunk.from(
+    //language=WGSL
+    `
+const SORT_WORKGROUP_SIZE = ${SORT_WORKGROUP_SIZE}u;
+const SORT_KEYS_PER_THREAD = ${SORT_KEYS_PER_THREAD}u;
+const SORT_TILE_SIZE = ${SORT_TILE_SIZE}u;
+const SORT_RADIX = ${RADIX}u;
+const SORT_RADIX_LOG = ${RADIX_LOG}u;
+`);