@woosh/meep-engine 3.57.0 → 3.58.0

package/src/shade/renderer/light/environment/octahedral_z_pole_uv_to_direction.js

@@ -1,45 +1,44 @@
-/**
- * CPU port of the WGSL `uv_octahedral_unit_decode` chunk (Rune Stubbe's octahedral decode,
- * **Z-pole**): given a texel UV of an octahedral environment map, returns the world direction the
- * GPU will sample that texel for (the exact inverse of `uv_octahedral_unit_encode`).
- *
- * Every CPU-side producer/consumer of octahedral environment texels (the equirect resampler,
- * sun-extraction reverse decodes) must go through this ONE function so they can never drift
- * from the GPU sampling convention.
- *
- * ## Two conventions, and why the name says which
- *
- * `core/geom/3d` has its own octahedral codec — `octahedral_uv_to_direction` /
- * `octahedral_direction_to_uv`, and `decode_octahedron_to_unit` / `encode_unit_to_octahedron` over the
- * `[-1, 1]` range — and it folds on **`y`**, emitting `(x, z)`. This one folds on `z` and emits
- * `(x, y)`, matching the WGSL chunks, which is why a producer feeding the GPU decoder swizzles y and z
- * at the call site (see `encode_normals_to_octahedral_u32`).
- *
- * This function used to be called `octahedral_uv_to_direction` — the same name as the `core` one, with a
- * different pole *and* a different signature: `(target, u, v)` against
- * `(out, out_offset, in_uv, in_offset)`. An importer who autocompleted the name got one of two functions
- * that disagree about which axis is up, and the `core` one silently reads `u` out of
- * `arguments[2][arguments[3]]` if handed this call shape. The old name is kept as a deprecated alias
- * because it is published surface.
- *
- * @see chunk_uv_octahedral_unit_decode
- * @param {number[]|Float32Array} target receives the normalized direction (x, y, z)
- * @param {number} u in [0, 1]
- * @param {number} v in [0, 1]
- */
-export function octahedral_z_pole_uv_to_direction(target, u, v) {
-    let x = u * 2 - 1;
-    let y = v * 2 - 1;
-    const z = 1 - Math.abs(x) - Math.abs(y);
-
-    // octahedron fold for the lower hemisphere (mirrors the WGSL select-based form)
-    const t = Math.max(-z, 0);
-    x += x > 0 ? -t : t;
-    y += y > 0 ? -t : t;
-
-    const m = 1 / Math.sqrt(x * x + y * y + z * z);
-
-    target[0] = x * m;
-    target[1] = y * m;
-    target[2] = z * m;
-}
+/**
+ * CPU port of the WGSL `uv_octahedral_unit_decode` chunk (Rune Stubbe's octahedral decode,
+ * **Z-pole**): given a texel UV of an octahedral environment map, returns the world direction the
+ * GPU will sample that texel for (the exact inverse of `uv_octahedral_unit_encode`).
+ *
+ * Every CPU-side producer/consumer of octahedral environment texels (the equirect resampler,
+ * sun-extraction reverse decodes) must go through this ONE function so they can never drift
+ * from the GPU sampling convention.
+ *
+ * ## Two conventions, and why the name says which
+ *
+ * `core/geom/3d` has its own octahedral codec — `octahedral_uv_to_direction` /
+ * `octahedral_direction_to_uv`, and `decode_octahedron_to_unit` / `encode_unit_to_octahedron` over the
+ * `[-1, 1]` range — and it folds on **`y`**, emitting `(x, z)`. This one folds on `z` and emits
+ * `(x, y)`, matching the WGSL chunks, which is why a producer feeding the GPU decoder swizzles y and z
+ * at the call site (see `encode_normals_to_octahedral_u32`).
+ *
+ * This function used to be called `octahedral_uv_to_direction` — the same name as the `core` one, with a
+ * different pole *and* a different signature: `(target, u, v)` against
+ * `(out, out_offset, in_uv, in_offset)`. An importer who autocompleted the name got one of two functions
+ * that disagree about which axis is up, and the `core` one silently reads `u` out of
+ * `arguments[2][arguments[3]]` if handed this call shape.
+ *
+ * @see chunk_uv_octahedral_unit_decode
+ * @param {number[]|Float32Array} target receives the normalized direction (x, y, z)
+ * @param {number} u in [0, 1]
+ * @param {number} v in [0, 1]
+ */
+export function octahedral_z_pole_uv_to_direction(target, u, v) {
+    let x = u * 2 - 1;
+    let y = v * 2 - 1;
+    const z = 1 - Math.abs(x) - Math.abs(y);
+
+    // octahedron fold for the lower hemisphere (mirrors the WGSL select-based form)
+    const t = Math.max(-z, 0);
+    x += x > 0 ? -t : t;
+    y += y > 0 ? -t : t;
+
+    const m = 1 / Math.sqrt(x * x + y * y + z * z);
+
+    target[0] = x * m;
+    target[1] = y * m;
+    target[2] = z * m;
+}

package/src/shade/renderer/lightmap/atlas/rescale_uvs.js

@@ -1,5 +1,5 @@
 import AABB2 from "../../../../core/geom/2d/aabb/AABB2.js";
-import { aabb2_from_v2_array } from "../../../../core/geom/2d/aabb/aabb2_from_v2_array.js";
+import { aabb2_from_v2_buffer } from "../../../../core/geom/2d/aabb/aabb2_from_v2_buffer.js";
 
 /**
  * Often UVs do not occupy the entire 0..1 range, we rescale those to make full use of the texture space
@@ -11,7 +11,7 @@ export function rescale_uvs(uvs, vertex_count) {
     const aabb = new AABB2();
 
     // first compute UV bounds
-    aabb2_from_v2_array(aabb, uvs, vertex_count * 2);
+    aabb2_from_v2_buffer(aabb, uvs, vertex_count * 2);
 
     // Guard against degenerate (axis-collinear or single-point) charts whose UV bbox has
     // zero extent on an axis — 1/0 would produce Inf, then 0*Inf = NaN UVs.

package/src/shade/renderer/loader/gltf/tiny-gltf.d.ts

@@ -13,7 +13,7 @@ export class TinyGltf {
      * @readonly
      * @type {TextureFormat}
      */
-    static readonly "__#289@#UNCOMPRESSED_TARGET": TextureFormat;
+    static readonly "__#298@#UNCOMPRESSED_TARGET": TextureFormat;
     /**
      * @param {AssetManager} assetManager
      * @param {AssetRequestScope} [scope]

package/src/shade/renderer/material/StandardShadeMaterial.js

@@ -2,7 +2,7 @@ import { hash_mix2 } from "../../../core/math/hash/hash_mix2.js";
 import { hash_mix3 } from "../../../core/math/hash/hash_mix3.js";
 import { Color } from "../../../core/color/Color.js";
 import LinearModifier from "../../../core/model/stat/LinearModifier.js";
-import { optional_equality } from "../../../core/model/object/optional_equality.js";
+import { objectsEqual } from "../../../core/function/objectsEqual.js";
 import { optional_hash } from "../../../core/model/object/optional_hash.js";
 import { ShadeMaterial } from "./ShadeMaterial.js";
 
@@ -201,11 +201,11 @@ export class StandardShadeMaterial extends ShadeMaterial {
             && this.ior_factor === other.ior_factor
             && this.medium === other.medium
             && this.vt_stack === other.vt_stack
-            && optional_equality(this.texture_albedo, other.texture_albedo)
+            && objectsEqual(this.texture_albedo, other.texture_albedo)
             && this.diffuse_color.equals(other.diffuse_color)
-            && optional_equality(this.texture_normal, other.texture_normal)
-            && optional_equality(this.texture_orm, other.texture_orm)
-            && optional_equality(this.texture_emissive, other.texture_emissive)
+            && objectsEqual(this.texture_normal, other.texture_normal)
+            && objectsEqual(this.texture_orm, other.texture_orm)
+            && objectsEqual(this.texture_emissive, other.texture_emissive)
             && this.emissive_factor.equals(other.emissive_factor)
             && this.ambient_factors.equals(other.ambient_factors)
             ;

package/src/shade/renderer/material/resident/GPUResidentMaterialContext.d.ts

@@ -1,7 +1,3 @@
-export const RESIDENT_MATERIAL_TEXTURE_RESOLUTION: 64;
-export const RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE: 2048;
-export const RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION: number;
-export const RESIDENT_MATERIAL_TEXTURE_SLOTS_PER_LAYER: number;
 export class GPUResidentMaterialContext {
     /**
      *
@@ -9,6 +5,12 @@ export class GPUResidentMaterialContext {
      * @param {GraphicsContext} graphics
      */
     constructor(device: GPUDevice, graphics: GraphicsContext);
+    /**
+     * Sent with a material when it is repacked because its {@link ShadeMaterial#version} moved: the
+     * row the device reads changes with the next {@link update}. Not sent for a material's first pack.
+     * @type {Signal<ShadeMaterial>}
+     */
+    onMaterialRepacked: any;
     /**
      *
      * @returns {number}
@@ -24,6 +26,10 @@ export class GPUResidentMaterialContext {
      * @returns {GPUTextureContext}
      */
     get buffer_textures(): GPUTextureContext;
+    /**
+     * @returns {GPUBuffer}
+     */
+    get buffer_texture_means(): GPUBuffer;
     /**
      *
      * @returns {GPUTextureView}

package/src/shade/renderer/material/resident/GPUResidentMaterialContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUResidentMaterialContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/GPUResidentMaterialContext.js"],"names":[],"mappings":"AA0HA,sDAAuD;AAEvD,wDAAyD;AAEzD,+DAAiJ;AAEjJ,+DAA+I;AAE/I;IAqKI;;;;OAIG;IACH,yCAFW,eAAe,EAiDzB;IA7LD;;;OAGG;IACH,6BAEC;IAQD;;;OAGG;IACH,kCAEC;IAQD;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,kCAIC;IAmED;;;;;OAKG;IACH,0BAEC;IAOD;;;;;;OAMG;IACH,8BAEC;IAqJD;;;;;;;;;OASG;IACH,0BAHW,aAAa,GACX,YAAY,CAmBxB;IAgBD;;;;OAIG;IACH,wBAHW,YAAY,GACV,WAAW,CAIvB;IAGD,uBA+HC;IAED,wBA8EC;IAED;;;;OAIG;IACH,sCAFW,eAAe,QAUzB;IAoCD,eAWC;IAGD,gBAIC;;CACJ;8BA/uBY,OAAO,0BAA0B,EAAE,eAAe;8BAClD,OAAO,gCAAgC,EAAE,eAAe;2BACxD,OAAO,+BAA+B,EAAE,YAAY;4BACpD,OAAO,qBAAqB,EAAE,aAAa;oCAC3C,OAAO,6BAA6B,EAAE,qBAAqB;kCAC3D,OAAO,qCAAqC,EAAE,mBAAmB;kCAZ5C,oCAAoC;AAMtE;;;;;;;GAOG;AAEH;IACI,WAAM;IAEN;;;OAGG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,QAFU,qBAAqB,CAExB;IAEP;;OAEG;IACH,gBAFU,WAAW,CAEP;IAEd;;OAEG;IACH,aAFU,WAAW,CAEV;IAEX;;;;OAIG;IACH,gBAFU,WAAW,GAAC,IAAI,CAEZ;IACd;;OAEG;IACH,kBAFU,WAAW,CAEL;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEe;CAClC;AAqBD;IACI,WAAO;IAEP;;OAEG;IACH,QAFU,YAAY,CAEf;CACV"}
+{"version":3,"file":"GPUResidentMaterialContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/GPUResidentMaterialContext.js"],"names":[],"mappings":"AAkIA;IAqMI;;;;OAIG;IACH,yCAFW,eAAe,EAwDzB;IA9PD;;;;OAIG;IACH,wBAAkC;IA4BlC;;;OAGG;IACH,6BAEC;IAQD;;;OAGG;IACH,kCAEC;IAQD;;;OAGG;IACH,yCAEC;IAoBD;;OAEG;IACH,sCAEC;IAED;;;OAGG;IACH,kCAIC;IAmED;;;;;OAKG;IACH,0BAEC;IAOD;;;;;;OAMG;IACH,8BAEC;IA4JD;;;;;;;;;OASG;IACH,0BAHW,aAAa,GACX,YAAY,CAqBxB;IAgBD;;;;OAIG;IACH,wBAHW,YAAY,GACV,WAAW,CAIvB;IAGD,uBAiIC;IA6DD,wBA8EC;IAED;;;;OAIG;IACH,sCAFW,eAAe,QAUzB;IAoCD,eAWC;IAGD,gBAMC;;CACJ;8BA/0BY,OAAO,0BAA0B,EAAE,eAAe;8BAClD,OAAO,gCAAgC,EAAE,eAAe;2BACxD,OAAO,+BAA+B,EAAE,YAAY;4BACpD,OAAO,qBAAqB,EAAE,aAAa;oCAC3C,OAAO,6BAA6B,EAAE,qBAAqB;kCAC3D,OAAO,qCAAqC,EAAE,mBAAmB;kCAlB5C,oCAAoC;AAYtE;;;;;;;GAOG;AAEH;IACI,WAAM;IAEN;;;OAGG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,QAFU,qBAAqB,CAExB;IAEP;;OAEG;IACH,gBAFU,WAAW,CAEP;IAEd;;OAEG;IACH,aAFU,WAAW,CAEV;IAEX;;;;OAIG;IACH,gBAFU,WAAW,GAAC,IAAI,CAEZ;IACd;;OAEG;IACH,kBAFU,WAAW,CAEL;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEe;CAClC;AAqBD;IACI,WAAO;IAEP;;OAEG;IACH,QAFU,YAAY,CAEf;CACV"}

package/src/shade/renderer/material/resident/GPUResidentMaterialContext.js

@@ -1,11 +1,13 @@
 import { assert } from "../../../../core/assert.js";
 import { HashMap } from "../../../../core/collection/map/HashMap.js";
+import Signal from "../../../../core/events/signal/Signal.js";
 import IdPool from "../../../../core/IdPool.js";
 import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
 import { round_up } from "../../../../core/math/round_up.js";
 import { TextureViewDescriptor } from "../../../descriptor/texture/TextureViewDescriptor.js";
 import { ShadeGPUCommandContext } from "../../../device/ShadeGPUCommandContext.js";
 import { GPU_DATABASE_NULL } from "../../buffer/table/GPU_DATABASE_NULL.js";
+import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "../../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
 import { MEDIA_TABLE_CAPACITY, MEDIA_TABLE_STRUCT } from "../../medium/MEDIA_TABLE_STRUCT.js";
 import { MEDIUM_STRUCT } from "../../medium/MEDIUM_STRUCT.js";
 import { write_gpu_typed_buffer } from "../../shader/type/serde/write_gpu_typed_buffer.js";
@@ -17,6 +19,12 @@ import { sampler_descriptor_pack } from "../../texture/format/sampler_descriptor
 import { WHITE_PIXEL_TEXTURE } from "../../texture/util/WHITE_PIXEL_TEXTURE.js";
 import { INDIRECT_MATERIAL_ARRAY_TYPE } from "./INDIRECT_MATERIAL_ARRAY_TYPE.js";
 import { INDIRECT_MATERIAL_STRUCT } from "./INDIRECT_MATERIAL_STRUCT.js";
+import {
+    RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE,
+    RESIDENT_MATERIAL_TEXTURE_RESOLUTION,
+    RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION
+} from "./RESIDENT_MATERIAL_TEXTURE_LAYOUT.js";
+import { shader_resident_texture_means, shader_resident_texture_rows } from "./shader_resident_texture_means.js";
 
 /**
  * @typedef {import("../../GraphicsContext.js").GraphicsContext} GraphicsContext
@@ -120,16 +128,15 @@ const NEUTRAL_SURFACE = Object.freeze({
     emissive_factor: Object.freeze([0, 0, 0]),
 });
 
-export const RESIDENT_MATERIAL_TEXTURE_RESOLUTION = 64;
-
-export const RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE = 2048;
-
-export const RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION = Math.floor(RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE / RESIDENT_MATERIAL_TEXTURE_RESOLUTION);
-
-export const RESIDENT_MATERIAL_TEXTURE_SLOTS_PER_LAYER = RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION * RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION;
-
 export class GPUResidentMaterialContext {
 
+    /**
+     * Sent with a material when it is repacked because its {@link ShadeMaterial#version} moved: the
+     * row the device reads changes with the next {@link update}. Not sent for a material's first pack.
+     * @type {Signal<ShadeMaterial>}
+     */
+    onMaterialRepacked = new Signal();
+
     /**
      * @type {GraphicsContext}
      */
@@ -192,6 +199,31 @@ export class GPUResidentMaterialContext {
         return this.#buffer_textures;
     }
 
+    /**
+     * Each texture slot's mean, `vec4<f32>`, of its texels as the atlas stores them: an albedo's colour
+     * premultiplied by its coverage. Written whenever the textures are (§6.6 of
+     * PROBE_CLIPMAP_PROPOSAL_2026_10_27.md): what a GI hit that no card sees takes of its material.
+     * Replaced when the slots outgrow it, so take it each frame.
+     *
+     * @type {GPUBuffer}
+     */
+    #buffer_texture_means;
+
+    /** The rows' sums the means are made of. @type {GPUBuffer|null} */
+    #buffer_texture_rows = null;
+
+    /** Slots the means hold. */
+    #texture_means_capacity = 0;
+
+    #texture_means_settings = { slot_count: 0 };
+
+    /**
+     * @returns {GPUBuffer}
+     */
+    get buffer_texture_means() {
+        return this.#buffer_texture_means;
+    }
+
     /**
      *
      * @returns {GPUTextureView}
@@ -335,6 +367,13 @@ export class GPUResidentMaterialContext {
             size: MEDIA_TABLE_STRUCT.size,
         });
 
+        // a slot's worth until the first textures are written
+        this.#buffer_texture_means = device.createBuffer({
+            label: 'Material Texture Means',
+            usage: GPUBufferUsage.STORAGE,
+            size: 16,
+        });
+
         this.#buffer_textures = new GPUTextureContext(device);
         const descriptor = this.#buffer_textures.descriptor;
 
@@ -464,6 +503,8 @@ export class GPUResidentMaterialContext {
             this.#pack_material(info);
         } else if (info.version !== material.version) {
             this.#pack_material(info);
+
+            this.onMaterialRepacked.send1(material);
         }
 
         return info;
@@ -618,10 +659,71 @@ export class GPUResidentMaterialContext {
             }
         }
 
+        this.#record_texture_means(encoder, textures);
+
         encoder.finish();
 
     }
 
+    /**
+     * Every texture slot's mean, after the slots are written (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6):
+     * the rows' sums, then the slots' means, which {@link buffer_texture_means} holds.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {TextureInfo[]} textures
+     */
+    #record_texture_means(encoder, textures) {
+        let slot_count = 0;
+
+        for (let i = 0; i < textures.length; i++) {
+            slot_count = Math.max(slot_count, textures[i].id + 1);
+        }
+
+        if (slot_count === 0) {
+            return;
+        }
+
+        if (this.#texture_means_capacity < slot_count) {
+            // textures arrive a few at a time as a scene loads: doubling replaces the buffers a
+            // logarithmic number of times
+            const capacity = Math.max(slot_count, 2 * this.#texture_means_capacity);
+
+            this.#buffer_texture_means.destroy();
+            this.#buffer_texture_rows?.destroy();
+
+            this.#texture_means_capacity = capacity;
+            this.#buffer_texture_means = this.#device.createBuffer({
+                label: 'Material Texture Means',
+                usage: GPUBufferUsage.STORAGE,
+                size: 16 * capacity,
+            });
+            this.#buffer_texture_rows = this.#device.createBuffer({
+                label: 'Material Texture Rows',
+                usage: GPUBufferUsage.STORAGE,
+                size: 16 * RESIDENT_MATERIAL_TEXTURE_RESOLUTION * capacity,
+            });
+        }
+
+        const settings = this.#texture_means_settings;
+
+        settings.slot_count = slot_count;
+
+        // a workgroup a slot, folded as folded_workgroup_index reads it: the array holds more slots than a
+        // dimension does
+        shader_resident_texture_rows.dispatch({
+            encoder,
+            group_count_x: Math.min(slot_count, WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION),
+            group_count_y: Math.ceil(slot_count / WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION),
+            bindings: { settings, textures: this.textureView, texture_rows: this.#buffer_texture_rows },
+        });
+
+        shader_resident_texture_means.dispatch({
+            encoder,
+            group_count_x: Math.ceil(slot_count / 64),
+            bindings: { settings, texture_rows: this.#buffer_texture_rows, texture_means: this.#buffer_texture_means },
+        });
+    }
+
     build_materials() {
 
         /**
@@ -769,5 +871,7 @@ export class GPUResidentMaterialContext {
         this.#buffer_materials.destroy();
         this.#buffer_media.destroy();
         this.#buffer_textures.destroy();
+        this.#buffer_texture_means.destroy();
+        this.#buffer_texture_rows?.destroy();
     }
 }

package/src/shade/renderer/material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Texels a side of a texture's slot.
+ * @type {number}
+ */
+export const RESIDENT_MATERIAL_TEXTURE_RESOLUTION: number;
+/**
+ * Texels a side of a layer.
+ * @type {number}
+ */
+export const RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE: number;
+/**
+ * Slots a side of a layer.
+ * @type {number}
+ */
+export const RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION: number;
+/**
+ * Slots a layer holds.
+ * @type {number}
+ */
+export const RESIDENT_MATERIAL_TEXTURE_SLOTS_PER_LAYER: number;
+//# sourceMappingURL=RESIDENT_MATERIAL_TEXTURE_LAYOUT.d.ts.map

package/src/shade/renderer/material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RESIDENT_MATERIAL_TEXTURE_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.js"],"names":[],"mappings":"AAOA;;;GAGG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;GAGG;AACH,mDAFU,MAAM,CAEyC;AAEzD;;;GAGG;AACH,wDAFU,MAAM,CAEiI;AAEjJ;;;GAGG;AACH,wDAFU,MAAM,CAE+H"}

package/src/shade/renderer/material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.js

@@ -0,0 +1,30 @@
+/*
+ How the resident material textures sit in their array (`GPUResidentMaterialContext.buffer_textures`):
+ each texture a square slot, the slots in rows across a layer, the layers stacked. Slot `s` is in layer
+ `⌊s / SLOTS_PER_LAYER⌋`, at column `s mod SLOT_RESOLUTION` and row `⌊s / SLOT_RESOLUTION⌋ mod
+ SLOT_RESOLUTION` of it.
+*/
+
+/**
+ * Texels a side of a texture's slot.
+ * @type {number}
+ */
+export const RESIDENT_MATERIAL_TEXTURE_RESOLUTION = 64;
+
+/**
+ * Texels a side of a layer.
+ * @type {number}
+ */
+export const RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE = 2048;
+
+/**
+ * Slots a side of a layer.
+ * @type {number}
+ */
+export const RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION = Math.floor(RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE / RESIDENT_MATERIAL_TEXTURE_RESOLUTION);
+
+/**
+ * Slots a layer holds.
+ * @type {number}
+ */
+export const RESIDENT_MATERIAL_TEXTURE_SLOTS_PER_LAYER = RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION * RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION;

package/src/shade/renderer/material/resident/shader_resident_texture_means.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const RESIDENT_TEXTURE_MEANS_SETTINGS: WebGPUStruct;
+/**
+ * The rows' sums (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6): a workgroup a texture slot, a lane a row of
+ * its {@link SLOT_TEXELS}, which sums the row's texels into `texture_rows[slot · 64 + row]`. The launch
+ * is the slots, folded over x then y past the per-dimension limit.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_resident_texture_rows: ComputeShader;
+/**
+ * The slots' means (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6): a thread a texture slot, the mean of its
+ * rows' sums over the slot's texels, into `texture_means[slot]`, as the atlas stores it: an albedo's
+ * colour premultiplied by its coverage, so `rgb / a` is the mean colour of what the slot covers. A
+ * workgroup of 64 slots.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_resident_texture_means: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_resident_texture_means.d.ts.map

package/src/shade/renderer/material/resident/shader_resident_texture_means.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_resident_texture_means.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/shader_resident_texture_means.js"],"names":[],"mappings":"AAyBA;;GAEG;AACH,8CAFU,YAAY,CAKa;AAUnC;;;;;;GAMG;AACH,2CAFU,aAAa,CAgCpB;AAUH;;;;;;;GAOG;AACH,4CAFU,aAAa,CAyBpB;6BAjH0B,mCAAmC;8BAJlC,+BAA+B"}

package/src/shade/renderer/material/resident/shader_resident_texture_means.js

@@ -0,0 +1,120 @@
+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, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import {
+    RESIDENT_MATERIAL_TEXTURE_RESOLUTION,
+    RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION,
+    RESIDENT_MATERIAL_TEXTURE_SLOTS_PER_LAYER
+} from "./RESIDENT_MATERIAL_TEXTURE_LAYOUT.js";
+
+/*
+ A texture slot's mean (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6): what a GI hit no card sees takes
+ of its material. Two passes, so that no thread reads more than a row: the rows of every slot, then
+ every slot from its rows.
+*/
+
+/**
+ * The rows a slot has, and the texels a row.
+ * @type {number}
+ */
+const SLOT_TEXELS = RESIDENT_MATERIAL_TEXTURE_RESOLUTION;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const RESIDENT_TEXTURE_MEANS_SETTINGS = WebGPUStruct.from({
+    /** texture slots, the highest one's id and one */
+    slot_count: u32,
+}, "ResidentTextureMeansSettings");
+
+const row_resources = new ShaderResourceSetDescriptor();
+
+row_resources.setImmediate("settings", RESIDENT_TEXTURE_MEANS_SETTINGS);
+
+row_resources.createGroup()
+    .addTexture("textures", "unfilterable-float", "2d-array")
+    .addStorageBuffer("texture_rows", WebGPUArray.from(vec4f), true);
+
+/**
+ * The rows' sums (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6): a workgroup a texture slot, a lane a row of
+ * its {@link SLOT_TEXELS}, which sums the row's texels into `texture_rows[slot · 64 + row]`. The launch
+ * is the slots, folded over x then y past the per-dimension limit.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_resident_texture_rows = ComputeShader.from({
+    label: "Resident Texture Rows",
+    resources: row_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${SLOT_TEXELS})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) row: u32,
+) {
+    let slot = folded_workgroup_index(workgroup_id);
+
+    if (slot >= settings.slot_count) {
+        return;
+    }
+
+    let layer = slot / ${RESIDENT_MATERIAL_TEXTURE_SLOTS_PER_LAYER}u;
+    let in_layer = slot % ${RESIDENT_MATERIAL_TEXTURE_SLOTS_PER_LAYER}u;
+    let origin = vec2<u32>(in_layer % ${RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION}u, in_layer / ${RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION}u) * ${SLOT_TEXELS}u;
+
+    var sum = vec4<f32>(0.0);
+
+    for (var x = 0u; x < ${SLOT_TEXELS}u; x++) {
+        sum += textureLoad(textures, origin + vec2<u32>(x, row), layer, 0);
+    }
+
+    texture_rows[slot * ${SLOT_TEXELS}u + row] = sum;
+}
+`, [chunk_folded_workgroup_index]),
+});
+
+const mean_resources = new ShaderResourceSetDescriptor();
+
+mean_resources.setImmediate("settings", RESIDENT_TEXTURE_MEANS_SETTINGS);
+
+mean_resources.createGroup()
+    .addStorageBuffer("texture_rows", WebGPUArray.from(vec4f))
+    .addStorageBuffer("texture_means", WebGPUArray.from(vec4f), true);
+
+/**
+ * The slots' means (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6): a thread a texture slot, the mean of its
+ * rows' sums over the slot's texels, into `texture_means[slot]`, as the atlas stores it: an albedo's
+ * colour premultiplied by its coverage, so `rgb / a` is the mean colour of what the slot covers. A
+ * workgroup of 64 slots.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_resident_texture_means = ComputeShader.from({
+    label: "Resident Texture Means",
+    resources: mean_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let slot = id.x;
+
+    if (slot >= settings.slot_count) {
+        return;
+    }
+
+    var sum = vec4<f32>(0.0);
+
+    for (var row = 0u; row < ${SLOT_TEXELS}u; row++) {
+        sum += texture_rows[slot * ${SLOT_TEXELS}u + row];
+    }
+
+    texture_means[slot] = sum / ${SLOT_TEXELS * SLOT_TEXELS}.0;
+}
+`),
+});

package/src/shade/renderer/particles/GPUParticleSystem.js

@@ -21,9 +21,9 @@ import {
 } from "./data/PARTICLE_COUNTERS.js";
 import { graph_particles_simulate } from "./graph_particles.js";
 import {
-    PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE,
-    shader_particle_init_free_list,
-} from "./shaders/shader_particle_init_free_list.js";
+    SLOT_STACK_FILL_WORKGROUP_SIZE,
+    shader_slot_stack_fill,
+} from "../gpu_primitive/slot_stack/shader_slot_stack_fill.js";
 import {
     graph_particle_avboit_draw,
     graph_particle_avboit_occupancy,
@@ -1035,7 +1035,7 @@ export class GPUParticleSystem {
     }
 
     /**
-     * Fill the free list with every slot, on the GPU — see `shaders/shader_particle_init_free_list.js`
+     * Fill the free list with every slot, on the GPU — see `gpu_primitive/slot_stack/shader_slot_stack_fill.js`
      * for why this is a dispatch and not a host write.
      *
      * The launch is clamped to what a dispatch dimension holds and the shader strides through the
@@ -1047,13 +1047,13 @@ export class GPUParticleSystem {
 
         const cmd = ShadeGPUCommandContext.create(this.graphics, "particles/free list init");
 
-        shader_particle_init_free_list.dispatch({
+        shader_slot_stack_fill.dispatch({
             encoder: cmd,
             group_count_x: Math.min(
-                Math.ceil(this.capacity / PARTICLE_INIT_FREE_LIST_WORKGROUP_SIZE),
+                Math.ceil(this.capacity / SLOT_STACK_FILL_WORKGROUP_SIZE),
                 device.limits.maxComputeWorkgroupsPerDimension,
             ),
-            bindings: { dead: this.buffers.dead, u_capacity: this.capacity },
+            bindings: { slots: this.buffers.dead, capacity: this.capacity },
         });
 
         cmd.finish();

package/src/shade/renderer/particles/graph/validate_particle_graph.d.ts

@@ -68,5 +68,4 @@ export const PARTICLE_GRAPH_PHASE: Readonly<{
     INIT: "init";
     UPDATE: "update";
 }>;
-export { PARTICLE_GRAPH_ERROR, PARTICLE_GRAPH_INFO, PARTICLE_GRAPH_WARNING } from "./particle_graph_diagnostic.js";
 //# sourceMappingURL=validate_particle_graph.d.ts.map

package/src/shade/renderer/particles/graph/validate_particle_graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate_particle_graph.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/validate_particle_graph.js"],"names":[],"mappings":"AAqEA;;;;;;;;GAQG;AACH;IAN0E,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAEnC,KAAK,GAAtB,MAAM;IAEJ,yBAAyB,CAoDrC;;;;;;;;mCAlES,MAAM;AA5ChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;GAQG;AACH;;;GAGG"}
+{"version":3,"file":"validate_particle_graph.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/validate_particle_graph.js"],"names":[],"mappings":"AA+DA;;;;;;;;GAQG;AACH;IAN0E,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAEnC,KAAK,GAAtB,MAAM;IAEJ,yBAAyB,CAoDrC;;;;;;;;mCAlES,MAAM;AA5ChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;GAQG;AACH;;;GAGG"}

package/src/shade/renderer/particles/graph/validate_particle_graph.js

@@ -10,12 +10,6 @@ import {
 import { PARTICLE_PARAMETER_KIND, particle_node_parameters } from "./particle_node_parameters.js";
 import { is_particle_curve, is_particle_gradient } from "./particle_ramp.js";
 
-export {
-    PARTICLE_GRAPH_ERROR,
-    PARTICLE_GRAPH_INFO,
-    PARTICLE_GRAPH_WARNING,
-} from "./particle_graph_diagnostic.js";
-
 /**
  * Check a particle graph and say what is wrong with it, per node.
  *

package/src/shade/renderer/particles/shaders/shader_particle_emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_emit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,kDAA8E;AAE9E;;;;;;;;GAQG;AACH,4BAFU,YAAY,CAOK;AA4D3B,iDAIG;6BAnH0B,mCAAmC;8BAIlC,+BAA+B"}
+{"version":3,"file":"shader_particle_emit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,kDAA8E;AAE9E;;;;;;;;GAQG;AACH,4BAFU,YAAY,CAOK;AA0D3B,iDAIG;6BAlH0B,mCAAmC;8BAIlC,+BAA+B"}