@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -1,29 +1,51 @@
 import { COLLECTION_U32_STRUCT_READ } from "../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
 import { COLLECTION_U32_STRUCT_WRITE } from "../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
 import { CLIPMAP_LEVEL_ARRAY } from "../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { chunk_sphere_sample_volume } from "../../../shader/chunk/geometry/sphere/chunk_sphere_sample_volume.js";
 import { chunk_mod_v3i } from "../../../shader/chunk/geometry/vec3/chunk_mod_v3i.js";
+import { chunk_rgb_to_luminance } from "../../../shader/chunk/color/chunk_rgb_to_luminance.js";
+import { chunk_lower_bound_branchless } from "../../../shader/chunk/math/chunk_lower_bound_branchless.js";
+import { chunk_stbn_sample_vec2 } from "../../../shader/chunk/noise/chunk_stbn_sample_vec2.js";
+import { chunk_r2_canonical } from "../../../shader/chunk/noise/r/chunk_r2_canonical.js";
+import { chunk_hash_lowbias32 } from "../../../shader/chunk/random/chunk_hash_lowbias32.js";
+import { chunk_hash_to_float01 } from "../../../shader/chunk/random/chunk_hash_to_float01.js";
+import { chunk_pcg3d } from "../../../shader/chunk/random/pcg/chunk_pcg3d.js";
 import { METRO_L1_IRRADIANCE_STRUCT } from "../../../shader/chunk/spherical_harmonics/l1i/chunk_convert_to_irradiance_sh.js";
 import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
 import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
-import { atomic_u32, f32, u32, vec2u, vec3i, vec4f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { atomic_u32, f32, u32, vec2u, vec3i, vec3u, vec4f, vec4u } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { STBN_VEC2_RESOURCE } from "../../../STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js";
 import {
     PROBE_BLEND_SKIRT,
     PROBE_CLIPMAP_NONE,
+    PROBE_AGE_BUCKETS,
+    PROBE_COUNTER_AGES,
+    PROBE_COUNTER_EVICTED,
     PROBE_COUNTER_FREE,
     PROBE_COUNTER_PERIOD,
     PROBE_COUNTER_STARVED,
+    PROBE_COUNTER_WAITING,
     PROBE_DISPATCH_ACTIVE,
     PROBE_DISPATCH_ADMIT,
+    PROBE_DISPATCH_ORDER,
     PROBE_DISPATCH_PUBLISH,
     PROBE_DISPATCH_RAYS,
     PROBE_DISPATCH_ROWS,
     PROBE_DISPATCH_TEXELS,
     PROBE_DISPATCH_TRACED,
+    PROBE_GUIDE_SCALE,
+    PROBE_ORDER_RUN,
     PROBE_RAY_BACK_FACE,
+    PROBE_RAY_CASCADE_MASK,
     PROBE_RAY_CASCADE_SHIFT,
     PROBE_RAY_KIND_MASK,
+    PROBE_RAY_NONE,
+    PROBE_RAY_ORIGIN_JITTER,
+    PROBE_RAY_PROBE_SHIFT,
+    PROBE_RECORD_CASCADE_SHIFT,
+    PROBE_RECORD_SCREEN,
     PROBE_RELOCATION_LIMIT,
     PROBE_STATE_ALIVE,
     PROBE_STATE_DEAD,
@@ -31,32 +53,40 @@ import {
     PROBE_STATE_KIND_MASK,
     PROBE_STATE_NEW,
     PROBE_STATE_UPDATES_SHIFT,
-    PROBE_THREAD_WORKGROUP_SIZE
+    PROBE_TEXEL_RAYS,
+    PROBE_THREAD_WORKGROUP_SIZE,
+    PROBE_WANTED_SCREEN
 } from "./PROBE_CLIPMAP.js";
 
 /**
- * A probe's record (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.2), 64 bytes a slot: where it is, when it
- * was wanted and traced, its last update's back faces, and its irradiance. Where relocation moved it
- * is the state's second word, which readers weighing it load with the state.
+ * A probe's record (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.2), 48 bytes a slot: where it is, when it
+ * was wanted and traced, its last update's back faces, whose want it was, and its irradiance. Where
+ * relocation moved it is the state's second word, which readers weighing it load with the state.
  *
  * @type {WebGPUStruct}
  */
 export const PROBE_RECORD_STRUCT = WebGPUStruct.from({
     /** the lattice point, in its cascade's spacing: the probe stands at `cell · spacing` before relocation */
     cell: vec3i,
-    cascade: u32,
-    /** when a pixel last wanted it: seconds since the clipmap was made */
-    wanted_time: f32,
-    /** when it was last updated, on the same clock */
-    traced_time: f32,
-    /** the share of its last update's resolved rays that hit back faces (§8.4) */
-    back_face: f32,
-    /** the irradiance its rays saw, the Metro L1 encoding: luma as SH2, chroma constant */
-    sh: METRO_L1_IRRADIANCE_STRUCT,
-}, "ProbeRecord");
+    /**
+     * The share of its last update's resolved rays that hit back faces (§8.4), unorm16 in the low half;
+     * whether a pixel wanted it, `PROBE_RECORD_SCREEN`; and its cascade, `probe_record_cascade`
+     * (`PROBE_CLIPMAP.js`).
+     */
+    flags: u32,
+    /** the frame a pixel or a hit last wanted it, of the frames the clipmap has recorded */
+    wanted_frame: u32,
+    /** the frame it was last updated */
+    traced_frame: u32,
+    /**
+     * The irradiance its rays saw, the Metro L1 encoding (luma as SH2, chroma constant) in half floats:
+     * Y's xy, Y's zw, CoCg. `probe_record_sh_decode`.
+     */
+    sh: vec3u,
+}, "ProbeRecord").pack();
 
 /**
- * A ray of a probe's update (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6), 28 bytes, as trace writes it for
+ * A ray of a probe's update (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6), 24 bytes, as trace writes it for
  * the passes after it.
  *
  * @type {WebGPUStruct}
@@ -68,19 +98,21 @@ export const PROBE_RAY_STRUCT = WebGPUStruct.from({
     direction: u32,
     /** the hit's normal, octahedral, two unorm16; zero but for a hit */
     normal: u32,
-    /** the `meshes` row whose surface the hit is on, 0 for none */
+    /**
+     * The `meshes` row whose surface the hit is on, 0 for none. After shade, the hit's diffuse albedo,
+     * `pack4x8unorm`, which the light pass reads; zero for any other ray.
+     */
     row: u32,
     /** its kind, the back face, and the hit's cascade (`PROBE_CLIPMAP.js`) */
     flags: u32,
     /**
-     * The light, three half floats, red and green here and blue in {@link light_b}'s low half. Trace
-     * writes the direct irradiance at a front-face hit, E_dir (§8.7), zero for any other ray; shade
-     * writes over it the radiance the ray brings back.
+     * The light, RGB9E5 (`rgbe9995_encode`): held to its largest value, 65,408, which the half-float
+     * atlases after it also hold. Trace writes the direct irradiance at a front-face hit, E_dir (§8.7),
+     * zero for any other ray; shade writes over it the radiance the ray brings back, and the light pass
+     * adds what the hit takes from beyond the trace.
      */
-    light_rg: u32,
-    /** the light's blue, a half float in the low half */
-    light_b: u32,
-}, "ProbeRay");
+    light: u32,
+}, "ProbeRay").pack();
 
 /**
  * The cascades' cage windows, a {@link CLIPMAP_LEVEL_ARRAY} as a uniform, finest first: a cell of
@@ -142,6 +174,29 @@ export const PROBE_COUNTERS_READ_RESOURCE = ShaderResourceDescriptor.storageBuff
  */
 export const PROBE_FREE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_free", WebGPUArray.u32, true);
 
+/**
+ * What the next frame's retire evicts (§8.3), as the frame's schedule leaves it: the oldest `buckets` of the
+ * `PROBE_AGE_BUCKETS` age buckets whole, and `remaining` probes of the bucket below them. Zero, as a new
+ * buffer holds it, evicts nothing.
+ * @type {WebGPUStruct}
+ */
+export const PROBE_EVICTION_STRUCT = WebGPUStruct.from({
+    buckets: u32,
+    remaining: u32,
+}, "ProbeEviction").pack();
+
+/**
+ * The eviction as retire reads it: plainly, every thread.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_EVICTION_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_eviction", PROBE_EVICTION_STRUCT);
+
+/**
+ * The eviction as schedule writes it.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_EVICTION_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_eviction", PROBE_EVICTION_STRUCT, true);
+
 /**
  * The live probes' slots as retire reads them: the list the frame before wrote.
  * @type {ShaderResourceDescriptor}
@@ -166,12 +221,6 @@ export const PROBE_ACTIVE_WRITTEN_RESOURCE = ShaderResourceDescriptor.storageBuf
  */
 export const PROBE_WANTED_BITS_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_wanted_bits", WebGPUArray.from(atomic_u32), true);
 
-/**
- * The wanted bits, read plainly once want has set them.
- * @type {ShaderResourceDescriptor}
- */
-export const PROBE_WANTED_BITS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_wanted_bits", WebGPUArray.u32);
-
 /**
  * The probes the frame updates, as the due passes list them, at most U (§8.5).
  * @type {ShaderResourceDescriptor}
@@ -184,6 +233,13 @@ export const PROBE_TRACE_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer
  */
 export const PROBE_TRACE_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_trace", COLLECTION_U32_STRUCT_READ);
 
+/**
+ * The probes the frame updates, as the order pass sorts them in place: the count read plainly, the
+ * entries written.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_TRACE_ORDER_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_trace", COLLECTION_U32_STRUCT_READ, true);
+
 /**
  * The keys wanted this frame, each once, as want lists them.
  * @type {ShaderResourceDescriptor}
@@ -227,6 +283,76 @@ export const PROBE_RAYS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer(
  */
 export const PROBE_RAYS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_rays", WebGPUArray.from(PROBE_RAY_STRUCT));
 
+/**
+ * Each listed probe's rays this update that the budget does not scale, `{count, elements}` by its place in
+ * the trace list: a uniform update's R and a DEAD probe's fewest, zero for a guided update. The trace
+ * command writes the count, the ray counts pass the elements.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_COUNTS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_counts", COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * Each listed probe's rays this update that the budget scales, laid out as `probe_ray_counts`: a guided
+ * update's request, zero for any other.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_REQUESTS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_requests", COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * The inclusive sums of `probe_ray_counts`, as the scan leaves them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_COUNT_SUMS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_count_sums", COLLECTION_U32_STRUCT_READ);
+
+/**
+ * The inclusive sums of `probe_ray_requests`, as the scan leaves them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_REQUEST_SUMS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_request_sums", COLLECTION_U32_STRUCT_READ);
+
+/**
+ * The frame's rays laid out by listed probe (§8.6): inclusive sums of each listed probe's rays, so that the
+ * k-th listed probe's rays are the frame's `[sums[k − 1], sums[k])`, the first from 0, and the frame's
+ * count of rays is the last sum. The ray layout pass writes them, the trace command their count.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_SUMS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_sums", COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * The frame's rays laid out by listed probe, as the passes after the layout read them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_RAY_SUMS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_ray_sums", COLLECTION_U32_STRUCT_READ);
+
+/**
+ * A slot's ray request (§8.6), as projection writes it after each update: the rays its next guided update
+ * asks for, and what tells it the probe's light moved.
+ *
+ * @type {WebGPUStruct}
+ */
+export const PROBE_REQUEST_STRUCT = WebGPUStruct.from({
+    /** the rays the probe's next guided update asks for */
+    rays: u32,
+    /** the running mean of the update's change score: its texels' falls from their means, each in its own deviation, summed over the root of their count */
+    change_mean: f32,
+    /** the running variance of the change score */
+    change_variance: f32,
+    /** the scores its running statistics hold, up to `PROBE_RADIANCE_SAMPLES_LIMIT` */
+    changes: u32,
+}, "ProbeRequest").pack();
+
+/**
+ * Each slot's {@link PROBE_REQUEST_STRUCT}, as projection writes it.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_REQUESTS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_requests", WebGPUArray.from(PROBE_REQUEST_STRUCT), true);
+
+/**
+ * Each slot's ray request, as the ray counts pass reads it.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_REQUESTS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_requests", WebGPUArray.from(PROBE_REQUEST_STRUCT));
+
 /**
  * The listed probes' maps, as accumulation writes them for projection and publish, in list order,
  * `probe_clipmap_maps_words` a probe.
@@ -240,6 +366,15 @@ export const PROBE_MAPS_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer(
  */
 export const PROBE_MAPS_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_maps", WebGPUArray.u32);
 
+/**
+ * Each slot's radiance estimators (§8.8), n_r² a slot by texel, as accumulation reads and writes them: the
+ * texel's multi-scale mean past its mean, which the radiance atlas holds. Four words of half floats: the short
+ * mean's r and g; its b and the deviation's r; the deviation's g and b; the blend reduction and the
+ * inconsistency.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_ESTIMATORS_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_estimators", WebGPUArray.from(vec4u), true);
+
 /**
  * A row of a listed probe's radiance map, projected: its irradiance SH, and its rays this update.
  * @type {WebGPUStruct}
@@ -250,7 +385,11 @@ export const PROBE_PROJECTION_ROW_STRUCT = WebGPUStruct.from({
     resolved: u32,
     /** of them, the back faces */
     back_faces: u32,
-}, "ProbeProjectionRow");
+    /** how far the update's samples fell from their texels' means, each in its own deviation, luminance, summed */
+    change: f32,
+    /** the texels that blended a sample */
+    blended: f32,
+}, "ProbeProjectionRow").pack();
 
 /**
  * The listed probes' rows, n_r a probe, as the projection's rows write them.
@@ -303,11 +442,19 @@ export const PROBE_DEPTH_STORE_RESOURCE = ShaderResourceDescriptor.storageTextur
  * fn probe_state_kind(state: u32) -> u32 // of the state's first word
  * fn probe_state_updates(state: u32) -> u32
  * fn probe_state(kind: u32, updates: u32) -> u32
+ * fn probe_clipmap_age_bucket(age: u32) -> u32 // the bucket of frames unwanted that eviction orders by
+ * fn probe_record_flags(back_face: f32, screen: bool, cascade: u32) -> u32
+ * fn probe_record_cascade(flags: u32) -> u32
+ * fn probe_record_sh_encode(sh: MetroL1) -> vec3<u32> // held to the half float's largest, ±65,504
+ * fn probe_record_sh_decode(sh: vec3<u32>) -> MetroL1
  * fn probe_clipmap_offset_encode(offset: vec3<f32>, spacing: f32) -> u32 // the state's second word
  * fn probe_clipmap_offset_decode(word: u32, spacing: f32) -> vec3<f32>
  * fn probe_clipmap_maps_words(radiance_resolution: u32, depth_resolution: u32) -> u32 // a listed probe's, in probe_maps
  * ```
  *
+ * An age's bucket is its count of binary digits: 0 frames the first, 1 the second, 2 and 3 the third, and
+ * the last everything from 2^(`PROBE_AGE_BUCKETS` − 2) frames on.
+ *
  * The offset's fields are of `PROBE_RELOCATION_LIMIT` of the spacing, 511 steps each way: under a
  * thousandth of the spacing apart, and zero at the lattice point.
  *
@@ -326,6 +473,10 @@ const PROBE_STATE_DEAD = ${PROBE_STATE_DEAD}u;
 const PROBE_COUNTER_FREE = ${PROBE_COUNTER_FREE}u;
 const PROBE_COUNTER_STARVED = ${PROBE_COUNTER_STARVED}u;
 const PROBE_COUNTER_PERIOD = ${PROBE_COUNTER_PERIOD}u;
+const PROBE_COUNTER_WAITING = ${PROBE_COUNTER_WAITING}u;
+const PROBE_COUNTER_EVICTED = ${PROBE_COUNTER_EVICTED}u;
+const PROBE_COUNTER_AGES = ${PROBE_COUNTER_AGES}u;
+const PROBE_AGE_BUCKETS = ${PROBE_AGE_BUCKETS}u;
 
 const PROBE_DISPATCH_ACTIVE = ${PROBE_DISPATCH_ACTIVE}u;
 const PROBE_DISPATCH_ADMIT = ${PROBE_DISPATCH_ADMIT}u;
@@ -334,10 +485,20 @@ const PROBE_DISPATCH_RAYS = ${PROBE_DISPATCH_RAYS}u;
 const PROBE_DISPATCH_TEXELS = ${PROBE_DISPATCH_TEXELS}u;
 const PROBE_DISPATCH_ROWS = ${PROBE_DISPATCH_ROWS}u;
 const PROBE_DISPATCH_PUBLISH = ${PROBE_DISPATCH_PUBLISH}u;
+const PROBE_DISPATCH_ORDER = ${PROBE_DISPATCH_ORDER}u;
+const PROBE_ORDER_RUN = ${PROBE_ORDER_RUN}u;
 
 const PROBE_RAY_KIND_MASK = ${PROBE_RAY_KIND_MASK}u;
+const PROBE_RAY_NONE = ${PROBE_RAY_NONE}u;
 const PROBE_RAY_BACK_FACE = ${PROBE_RAY_BACK_FACE}u;
 const PROBE_RAY_CASCADE_SHIFT = ${PROBE_RAY_CASCADE_SHIFT}u;
+const PROBE_RAY_CASCADE_MASK = ${PROBE_RAY_CASCADE_MASK}u;
+const PROBE_RAY_PROBE_SHIFT = ${PROBE_RAY_PROBE_SHIFT}u;
+
+const PROBE_WANTED_SCREEN = ${PROBE_WANTED_SCREEN}u;
+
+const PROBE_RECORD_SCREEN = ${PROBE_RECORD_SCREEN}u;
+const PROBE_RECORD_CASCADE_SHIFT = ${PROBE_RECORD_CASCADE_SHIFT}u;
 
 const PROBE_THREAD_WORKGROUP_SIZE = ${PROBE_THREAD_WORKGROUP_SIZE}u;
 const PROBE_BLEND_SKIRT = ${PROBE_BLEND_SKIRT}.0;
@@ -376,8 +537,36 @@ fn probe_state(kind: u32, updates: u32) -> u32 {
     return kind | (updates << ${PROBE_STATE_UPDATES_SHIFT}u);
 }
 
+fn probe_clipmap_age_bucket(age: u32) -> u32 {
+    return min(32u - countLeadingZeros(age), PROBE_AGE_BUCKETS - 1u);
+}
+
+fn probe_record_flags(back_face: f32, screen: bool, cascade: u32) -> u32 {
+    return (pack2x16unorm(vec2<f32>(back_face, 0.0)) & 0xFFFFu) | select(0u, PROBE_RECORD_SCREEN, screen) | (cascade << PROBE_RECORD_CASCADE_SHIFT);
+}
+
+fn probe_record_cascade(flags: u32) -> u32 {
+    return flags >> PROBE_RECORD_CASCADE_SHIFT;
+}
+
+fn probe_record_sh_encode(sh: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref}) -> vec3<u32> {
+    let y = clamp(sh.Y, vec4<f32>(-65504.0), vec4<f32>(65504.0));
+    let cocg = clamp(sh.CoCg, vec2<f32>(-65504.0), vec2<f32>(65504.0));
+
+    return vec3<u32>(pack2x16float(y.xy), pack2x16float(y.zw), pack2x16float(cocg));
+}
+
+fn probe_record_sh_decode(sh: vec3<u32>) -> ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref} {
+    var out: ${METRO_L1_IRRADIANCE_STRUCT.wgsl_ref};
+
+    out.Y = vec4<f32>(unpack2x16float(sh.x), unpack2x16float(sh.y));
+    out.CoCg = unpack2x16float(sh.z);
+
+    return out;
+}
+
 fn probe_clipmap_maps_words(radiance_resolution: u32, depth_resolution: u32) -> u32 {
-    return 3u * radiance_resolution * radiance_resolution + depth_resolution * depth_resolution;
+    return 4u * radiance_resolution * radiance_resolution + depth_resolution * depth_resolution;
 }
 
 fn probe_clipmap_offset_encode(offset: vec3<f32>, spacing: f32) -> u32 {
@@ -395,9 +584,53 @@ fn probe_clipmap_offset_decode(word: u32, spacing: f32) -> vec3<f32> {
 }
 `, [
     PROBE_RECORD_STRUCT.declaration_chunk,
+    METRO_L1_IRRADIANCE_STRUCT.declaration_chunk,
     chunk_mod_v3i,
 ]);
 
+/**
+ * Where the frame's rays are, by listed probe (§8.6): the scan of each listed probe's count of rays this
+ * update, `probe_ray_sums`. A probe's rays follow one another, in the trace list's order.
+ *
+ * ```wgsl
+ * fn probe_clipmap_ray_probe(ray: u32) -> u32 // the listed probe the frame's ray is one of, by its place in the list; the list's count or more for none
+ * fn probe_clipmap_probe_rays(k: u32) -> vec2<u32> // the k-th listed probe's first ray, and how many it has
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_ray_layout = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_clipmap_ray_probe(ray: u32) -> u32 {
+    let listed = probe_ray_sums.count;
+
+    if (listed == 0u) {
+        return 0u;
+    }
+
+    // the first whose rays end past this one
+    return lower_bound_branchless(&probe_ray_sums.elements, ray + 1u, listed);
+}
+
+fn probe_clipmap_probe_rays(k: u32) -> vec2<u32> {
+    let end = probe_ray_sums.elements[k];
+
+    var first = 0u;
+
+    // not a select, which reads both sides, k − 1 wrapping at the first
+    if (k > 0u) {
+        first = probe_ray_sums.elements[k - 1u];
+    }
+
+    return vec2<u32>(first, end - first);
+}
+`, [
+    chunk_lower_bound_branchless,
+]);
+
+chunk_probe_clipmap_ray_layout.requireResource(PROBE_RAY_SUMS_READ_RESOURCE);
+
 /**
  * Which octahedral radiance texel a ray of an update is, and the way back (§8.6). An update casts R rays
  * over the n_r² texels:
@@ -446,3 +679,196 @@ fn probe_clipmap_texel_ray(texel: u32, round: u32, updates: u32, rays: u32, texe
 `, [
     chunk_probe_clipmap,
 ]);
+
+/**
+ * The STBN jitter of a ray in its texel (§8.6): the noise moved by the slot's hash so that neighbouring
+ * probes do not jitter alike, and a fresh sample for each update and each round of a texel's rays. The
+ * trace aims its ray by it, and the light pass picks the probes at its hit with it (§8.7).
+ *
+ * ```wgsl
+ * fn probe_clipmap_ray_jitter(slot: u32, texel: u32, ray: u32, updates: u32, rays: u32, n: u32) -> vec2<f32> // ray: its index among the probe's R; n: n_r
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_ray_jitter = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_clipmap_ray_jitter(slot: u32, texel: u32, ray: u32, updates: u32, rays: u32, n: u32) -> vec2<f32> {
+    let texels = n * n;
+    let round = select(0u, ray / texels, rays >= texels);
+    let per_texel = max(rays / texels, 1u);
+
+    let scramble = hash_lowbias32(slot);
+    let noise_xy = vec2<u32>(texel % n, texel / n) + vec2<u32>(scramble & 127u, (scramble >> 7u) & 127u);
+
+    return stbn_sample_vec2(vec3<u32>(noise_xy, updates * per_texel + round));
+}
+`, [
+    chunk_hash_lowbias32,
+    chunk_stbn_sample_vec2,
+]);
+
+chunk_probe_clipmap_ray_jitter.requireResource(STBN_VEC2_RESOURCE);
+
+/**
+ * Where a ray of an update starts (§8.6): a point of the ball of `PROBE_RAY_ORIGIN_JITTER` of the spacing
+ * around the probe, uniform in its volume, as Brick4's bake jitters its probes. The point is drawn from the
+ * probe's slot and the ray's direction as its record packs it, so every pass that puts a hit back together
+ * from `t` (shade, light, want hits) draws the same one. The trace's jitter moves the direction every
+ * update, and the point with it.
+ *
+ * ```wgsl
+ * fn probe_clipmap_ray_origin(probe: vec4<f32>, slot: u32, direction: u32) -> vec3<f32> // probe: its `probe_origins` entry; direction: as the ray's record packs it
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_ray_origin = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_clipmap_ray_origin(probe: vec4<f32>, slot: u32, direction: u32) -> vec3<f32> {
+    let hash = pcg3d(vec3<u32>(slot, direction, 0xBB67AE85u));
+    let uvw = vec3<f32>(hash_to_float01(hash.x), hash_to_float01(hash.y), hash_to_float01(hash.z));
+
+    return probe.xyz + ${PROBE_RAY_ORIGIN_JITTER} * probe.w * sphere_sample_volume(uvw);
+}
+`, [
+    chunk_pcg3d,
+    chunk_hash_to_float01,
+    chunk_sphere_sample_volume,
+]);
+
+/**
+ * The listed probes' guides, `probe_guide_words` a probe in list order, as the guide passes write them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_GUIDE_WRITE_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_guide", WebGPUArray.u32, true);
+
+/**
+ * The listed probes' guides, as trace, accumulation and projection read them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_GUIDE_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_guide", WebGPUArray.u32);
+
+/**
+ * The guide's walk over a probe's octahedral texels, and the weights it walks (§8.6). A guided update
+ * gives each texel `R·(w + e)/W` rays: `w` is its weight, `e` the even share of the leftover, `W` the
+ * total. Its rays follow one another in the order of the walk. That order is the radiance map's rows,
+ * from the corner the update's count names (`updates mod 4` mirrors x, y, or both), and it is its own
+ * inverse.
+ *
+ * A probe's first n_r²/R updates are uniform, so that together they reach every texel (Enshrouded gives a new
+ * probe its most rays for the same reason): the guide would weigh a texel no ray has reached as dark.
+ *
+ * A DEAD probe's updates are all uniform. Readers weigh it at nothing, so its light is not worth guiding.
+ * Its updates exist to reclassify it, and only uniform rays do that (§8.4); guided ones would leave it
+ * dead for `PROBE_UNIFORM_PERIOD` of its already rare updates.
+ *
+ * - A texel's weight is its share of the probe's luminance in units of 1/`PROBE_GUIDE_SCALE`, held to
+ *   `(PROBE_TEXEL_RAYS − 2 − R/n_r²)/R`. With the even share added, that leaves a texel under
+ *   `PROBE_TEXEL_RAYS` rays. What the hold takes off, and what flooring the weights leaves over, is
+ *   spread evenly over every texel. A dark probe's rays are therefore an even, stratified spread.
+ * - The walk position `p` starts at ray `⌈R·Σ_{q<p}(w_q + e)/W − φ⌉`, `φ` being the update's phase in
+ *   [0, 1). That is systematic sampling: every texel takes ⌊its share⌋ or ⌈its share⌉ rays.
+ * - A guide's words (`probe_clipmap_guide_words`, by offset from the probe's): the first rays by walk
+ *   position at 0; the weights by texel at n_r²; the row luminances at 2·n_r²; the row weights at
+ *   2·n_r² + n_r; the total at 2·n_r² + 2·n_r, and the even share after it.
+ *
+ * ```wgsl
+ * fn probe_clipmap_guided(state: u32, period: u32, rays: u32, texels: u32) -> bool // the state's first word: the update's rays follow the guide
+ * fn probe_clipmap_guide_words(n: u32) -> u32
+ * fn probe_clipmap_guide_texel(position: u32, updates: u32, n: u32) -> u32 // and the other way: the walk is its own inverse
+ * fn probe_clipmap_guide_luminance(radiance: vec3<f32>) -> f32
+ * fn probe_clipmap_guide_weight(luminance: f32, total: f32, rays: u32, texels: u32) -> u32
+ * fn probe_clipmap_guide_phase(slot: u32, updates: u32) -> f32
+ * fn probe_clipmap_guide_start(before: u32, total: u32, rays: u32, phase: f32) -> u32 // before: the weight walked before
+ * fn probe_clipmap_guide_rate(expected: f32, rays: u32, texels: u32, period: u32) -> f32 // the share of updates a texel takes rays in
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_guide = CodeChunk.from(
+    //language=WGSL
+    `
+const PROBE_GUIDE_SCALE = ${PROBE_GUIDE_SCALE}u;
+const PROBE_TEXEL_RAYS = ${PROBE_TEXEL_RAYS}u;
+
+fn probe_clipmap_guided(state: u32, period: u32, rays: u32, texels: u32) -> bool {
+    let updates = probe_state_updates(state);
+
+    return probe_state_kind(state) != PROBE_STATE_DEAD && updates >= texels / rays && updates % period != 0u;
+}
+
+fn probe_clipmap_guide_words(n: u32) -> u32 {
+    return 2u * n * n + 2u * n + 2u;
+}
+
+fn probe_clipmap_guide_texel(position: u32, updates: u32, n: u32) -> u32 {
+    let corner = updates % 4u;
+    let column = position % n;
+    let row = position / n;
+    let x = select(column, n - 1u - column, (corner & 1u) != 0u);
+    let y = select(row, n - 1u - row, (corner & 2u) != 0u);
+
+    return y * n + x;
+}
+
+fn probe_clipmap_guide_luminance(radiance: vec3<f32>) -> f32 {
+    return max(rgb_to_luminance(radiance), 0.0);
+}
+
+fn probe_clipmap_guide_weight(luminance: f32, total: f32, rays: u32, texels: u32) -> u32 {
+    if (total <= 0.0) {
+        return 0u;
+    }
+
+    let hold = max(f32(PROBE_TEXEL_RAYS) - 2.0 - f32(rays) / f32(texels), 0.0) / f32(rays);
+
+    return u32(floor(min(luminance / total, hold) * f32(PROBE_GUIDE_SCALE)));
+}
+
+fn probe_clipmap_guide_phase(slot: u32, updates: u32) -> f32 {
+    return hash_to_float01(pcg3d(vec3<u32>(slot, updates, 0x6A09E667u)).x);
+}
+
+fn probe_clipmap_guide_start(before: u32, total: u32, rays: u32, phase: f32) -> u32 {
+    let at = ceil(f32(before) / f32(total) * f32(rays) - phase);
+
+    return u32(clamp(at, 0.0, f32(rays)));
+}
+
+fn probe_clipmap_guide_rate(expected: f32, rays: u32, texels: u32, period: u32) -> f32 {
+    let uniform = min(f32(rays) / f32(texels), 1.0);
+    let guided = min(expected, 1.0);
+
+    return (uniform + f32(period - 1u) * guided) / f32(period);
+}
+`, [
+    chunk_probe_clipmap,
+    chunk_rgb_to_luminance,
+    chunk_hash_to_float01,
+    chunk_pcg3d,
+]);
+
+/**
+ * The jitter of a guided update's ray in its texel. The first ray takes the texel's STBN jitter
+ * (`probe_clipmap_ray_jitter` at round 0). The rest rotate it by the R2 sequence, so a texel's rays
+ * spread over it the way a lattice does.
+ *
+ * ```wgsl
+ * fn probe_clipmap_guided_ray_jitter(slot: u32, texel: u32, round: u32, updates: u32, rays: u32, n: u32) -> vec2<f32> // round: the ray's place among its texel's
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_guided_ray_jitter = CodeChunk.from(
+    //language=WGSL
+    `
+fn probe_clipmap_guided_ray_jitter(slot: u32, texel: u32, round: u32, updates: u32, rays: u32, n: u32) -> vec2<f32> {
+    return fract(probe_clipmap_ray_jitter(slot, texel, 0u, updates, rays, n) + r2_canonical(round) - 0.5);
+}
+`, [
+    chunk_probe_clipmap_ray_jitter,
+    chunk_r2_canonical,
+]);

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

@@ -0,0 +1,19 @@
+/**
+ * The cage of a cascade around a receiving point (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3, §9.1): the
+ * lattice cell holding the point moved along `bias_direction` by {@link PROBE_RECEIVER_BIAS} of the
+ * cascade's spacing, whose eight corners are the probes the point reads.
+ *
+ * ```wgsl
+ * fn probe_clipmap_cage(cascade: u32, position: vec3<f32>, bias_direction: vec3<f32>, cage: ptr<function, vec3<i32>>) -> bool
+ * fn probe_clipmap_biased(cascade: u32, position: vec3<f32>, bias_direction: vec3<f32>) -> vec3<f32>
+ * ```
+ *
+ * `probe_clipmap_cage` writes the cell's least corner and says whether the cascade's cage window holds
+ * it. Want takes it to choose the probes a pixel wants, and the pick to read them, so that a pixel reads
+ * the probes it wanted.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_cage: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_probe_clipmap_cage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_probe_clipmap_cage.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_cage.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH,uCAFU,SAAS,CAkBhB;0BApCuB,uCAAuC"}