@woosh/meep-engine 3.64.0 → 3.65.0

package/src/shade/renderer/extension/ViewTextures.js

@@ -3,21 +3,18 @@ import { FrameRecord } from "./FrameRecord.js";
 
 /**
  * What the frame knows about where each pixel came from: this frame's depth, last frame's depth,
- * the visibility buffer, and the visible-meshlet table that resolves it.
+ * the visibility buffer, the visible-meshlet table that resolves it, and how far each pixel moved.
  *
  * Carried from {@link FramePhase.AfterGBuffer} through {@link FramePhase.BeforePresent}, and
  * writable wherever it is carried — an extension that rasterizes geometry which should own depth
  * publishes a replacement here, the same way any other record is published into.
- *
- * `velocity` is deliberately absent: it is one of the frame's optional products, and products are
- * their own delivery step. A field nothing may legally read yet would be a promise with no
- * mechanism behind it.
  */
 export class ViewTextures extends FrameRecord {
     #depth = -1;
     #depth_previous = -1;
     #visibility = -1;
     #visible_meshlets = -1;
+    #velocity = -1;
 
     static is_present_at(phase) {
         return phase === FramePhase.AfterGBuffer
@@ -80,4 +77,21 @@ export class ViewTextures extends FrameRecord {
     set visible_meshlets(handle) {
         this.#visible_meshlets = this.publish(handle);
     }
+
+    /**
+     * How far each pixel's surface moved on screen since the last frame: `rg16float`, in pixels, this
+     * frame's place less last frame's, free of the sub-pixel jitter. The renderer fills it from depth and
+     * {@link visibility} before {@link FramePhase.AfterGBuffer}; an extension that draws surfaces the
+     * visibility buffer cannot describe writes their pixels' motion over it at that phase and publishes
+     * the handle it wrote. What is published later than that phase reaches nothing the renderer runs.
+     *
+     * @returns {number}
+     */
+    get velocity() {
+        return this.read(this.#velocity);
+    }
+
+    set velocity(handle) {
+        this.#velocity = this.publish(handle);
+    }
 }

package/src/shade/renderer/fluid/GPUFluidCascadeStack.d.ts

@@ -170,7 +170,9 @@ export class GPUFluidCascadeStack {
      *     wind.set_far_velocity(v_far(t))
      *
      * A tile holds `v − v_far(t_s,c)` and `k` is taken for `t`, so a cascade that did not step reads
-     * from its old tile through its new decay. The field's own update uploads the table.
+     * from its old tile through its new decay. A cascade that is published takes the field's
+     * `publish_slot`, so the tile the frame before read stays as it was. The field's own update uploads
+     * the table.
      *
      * @param {object} options
      * @param {FrameGraph} options.graph

package/src/shade/renderer/fluid/GPUFluidCascadeStack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUFluidCascadeStack.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/GPUFluidCascadeStack.js"],"names":[],"mappings":"AASA;;;;GAIG;AAEH;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IACI;;;;;OAKG;IACH,iCAFW,OAAO,0CAA0C,EAAE,eAAe,QAK5E;IA2VD;;;;OAIG;IACH,uCAJW,MAAM,4BAEN;QAAC,OAAO,EAAE,OAAO,wCAAwC,EAAE,sBAAsB,CAAA;KAAC,QAkC5F;IAhVD;;;;;;;;;;OAUG;IACH;QAT8B,MAAM;QACE,UAAU,EAArC,UAAU,MAAM,CAAC;QAED,SAAS,EAAzB,MAAM;QACU,aAAa,EAA7B,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QACL,iBAAiB,EAAjC,MAAM;OAwChB;IA/DD;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;;OAIG;IACH,UAFU,OAAO,CAED;IAqDhB,wBAAwB;IACxB,4BAEC;IAED;;;OAGG;IACH,uCAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,WAHW,MAAM,GACJ,eAAe,CAI3B;IAED;;;;;OAKG;IACH,qBAFW,YAAY,GAAC,MAAM,EAAE,QAY/B;IAED;;;;;;OAMG;IACH,wBAHW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,QAMhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAd+B,KAAK,EAAzB,UAAU;QACM,IAAI,EAApB,MAAM;QAEU,EAAE,EAAlB,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;QACyB,OAAO,GAAtC,eAAe,GAAC,IAAI;QAEH,qBAAqB,GAAtC,MAAM;aA8FhB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACY,IAAI,EAA1B,YAAY;QACmB,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;aAsDhB;IA4CD;;OAEG;IACH,gBAUC;;CACJ;yBA/cY,OAAO,2DAA2D,EAAE,UAAU;2BAC9E,OAAO,yBAAyB,EAAE,YAAY;8BAC9C,OAAO,8BAA8B,EAAE,eAAe;gCARnC,sBAAsB"}
+{"version":3,"file":"GPUFluidCascadeStack.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/GPUFluidCascadeStack.js"],"names":[],"mappings":"AASA;;;;GAIG;AAEH;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IACI;;;;;OAKG;IACH,iCAFW,OAAO,0CAA0C,EAAE,eAAe,QAK5E;IAgWD;;;;OAIG;IACH,uCAJW,MAAM,4BAEN;QAAC,OAAO,EAAE,OAAO,wCAAwC,EAAE,sBAAsB,CAAA;KAAC,QAkC5F;IArVD;;;;;;;;;;OAUG;IACH;QAT8B,MAAM;QACE,UAAU,EAArC,UAAU,MAAM,CAAC;QAED,SAAS,EAAzB,MAAM;QACU,aAAa,EAA7B,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QACL,iBAAiB,EAAjC,MAAM;OAwChB;IA/DD;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;;OAIG;IACH,UAFU,OAAO,CAED;IAqDhB,wBAAwB;IACxB,4BAEC;IAED;;;OAGG;IACH,uCAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,WAHW,MAAM,GACJ,eAAe,CAI3B;IAED;;;;;OAKG;IACH,qBAFW,YAAY,GAAC,MAAM,EAAE,QAY/B;IAED;;;;;;OAMG;IACH,wBAHW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,QAMhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAd+B,KAAK,EAAzB,UAAU;QACM,IAAI,EAApB,MAAM;QAEU,EAAE,EAAlB,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;QACyB,OAAO,GAAtC,eAAe,GAAC,IAAI;QAEH,qBAAqB,GAAtC,MAAM;aA8FhB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACY,IAAI,EAA1B,YAAY;QACmB,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;aAyDhB;IA4CD;;OAEG;IACH,gBAUC;;CACJ;yBApdY,OAAO,2DAA2D,EAAE,UAAU;2BAC9E,OAAO,yBAAyB,EAAE,YAAY;8BAC9C,OAAO,8BAA8B,EAAE,eAAe;gCARnC,sBAAsB"}

package/src/shade/renderer/fluid/GPUFluidCascadeStack.js

@@ -352,7 +352,9 @@ export class GPUFluidCascadeStack {
      *     wind.set_far_velocity(v_far(t))
      *
      * A tile holds `v − v_far(t_s,c)` and `k` is taken for `t`, so a cascade that did not step reads
-     * from its old tile through its new decay. The field's own update uploads the table.
+     * from its old tile through its new decay. A cascade that is published takes the field's
+     * `publish_slot`, so the tile the frame before read stays as it was. The field's own update uploads
+     * the table.
      *
      * @param {object} options
      * @param {FrameGraph} options.graph
@@ -394,6 +396,9 @@ export class GPUFluidCascadeStack {
             record.far_velocity.set(cascade.read_far_velocity);
             cascade.describe_parent(record.parent, record.parent_faces, c + 1 < count ? cascades[c + 1] : null);
 
+            // its tile is written beside the one the frame before read
+            wind.publish_slot(c);
+
             pass.order[pending++] = c;
             this.#unpublished[c] = 0;
         }

package/src/shade/renderer/fluid/forcing/GPUFluidForcing.d.ts

@@ -125,6 +125,13 @@ export class GPUFluidForcing {
      * @returns {number}
      */
     get obstacle_count(): number;
+    /**
+     * A number that changes whenever an effector or obstacle row is added or removed: while it stands, a
+     * list of either table's rows is the list it was.
+     *
+     * @returns {number}
+     */
+    get sets_version(): number;
     /**
      * Every obstacle and effector row: the leaves of the finest tree, before its resolution cull.
      * @returns {number}

package/src/shade/renderer/fluid/forcing/GPUFluidForcing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUFluidForcing.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/GPUFluidForcing.js"],"names":[],"mappings":"AAuIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH;IAEI;;;;OAIG;IACH,iCAFW,eAAe,QAUzB;IA2ID;;;;;;;;;;;OAWG;IACH,kCAPW,wBAAwB,EAAE,QAC1B,MAAM,QACN,MAAM,SACN,MAAM,cACN,MAAM,GACJ,wBAAwB,CAcpC;IAylBD;;;;OAIG;IACH,yCAJW,MAAM,0CAEN;QAAC,OAAO,yBAAwB;KAAC,QAc3C;IA+MD,iFAcC;IAWD,gFAiCC;IAWD,kFAsBC;IA+GD,gFA0CC;IAjnCD;;;OAGG;IACH;QAF8B,MAAM;OAwCnC;IA4BD;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;;;;;OAOG;IACH,mBAHW,MAAM,GACJ,MAAM,CAiBlB;IAED;;;;;OAKG;IACH,4BAEC;IAED;;;;;OAKG;IACH,2BAEC;IAED;;;;;OAKG;IACH,qBAHW,mBAAmB,GACjB,MAAM,CAQlB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,UACN,mBAAmB,QAQ7B;IAED;;OAEG;IACH,qBAFW,MAAM,QAUhB;IAED;;;;;OAKG;IACH,uBAHW,mBAAmB,EAAE,GACnB,MAAM,CAsBlB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,UACN,mBAAmB,QAgB7B;IAED;;;OAGG;IACH,wBAHW,MAAM,SACN,MAAM,QAYhB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,MAAM,CAuBlB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,SACN,MAAM,QAmBhB;IAED;;;OAGG;IACH,qBAHW,MAAM,SACN,MAAM,QAUhB;IAyID;;;;;;;;;;;;;;;;;;;OAmBG;IACH;QAf+B,KAAK,EAAzB,UAAU;QACW,cAAc,EAAnC,WAAW;QAEgB,MAAM,EAAjC,UAAU,MAAM,CAAC;QAID,UAAU,EAA1B,MAAM;QAEU,gBAAgB,EAAhC,MAAM;QAEU,SAAS,EAAzB,MAAM;aA4ChB;IAyND;;;;;;;;;;;;OAYG;IACH;QAJ+B,KAAK,EAAzB,UAAU;QACe,KAAK,EAA9B,eAAe;QACe,MAAM,EAApC,eAAe,GAAC,IAAI;aA8H9B;IAmHD;;;;;;;;;;;OAWG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACe,OAAO,EAAhC,eAAe;QACC,EAAE,EAAlB,MAAM;QACJ,MAAM,GAAC,IAAI,CAuFvB;IAyDD;;;OAGG;IACH,gBAwBC;;CACJ;yBA16CY,OAAO,8DAA8D,EAAE,UAAU;8BACjF,OAAO,6CAA6C,EAAE,eAAe;8BACrE,OAAO,uBAAuB,EAAE,eAAe;kCAC/C,OAAO,kFAAkF,EAAE,mBAAmB;kCAC9G,OAAO,2EAA2E,EAAE,mBAAmB;4BAtCxF,mCAAmC;yCADtB,mDAAmD"}
+{"version":3,"file":"GPUFluidForcing.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/forcing/GPUFluidForcing.js"],"names":[],"mappings":"AAuIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH;IAEI;;;;OAIG;IACH,iCAFW,eAAe,QAUzB;IA2ID;;;;;;;;;;;OAWG;IACH,kCAPW,wBAAwB,EAAE,QAC1B,MAAM,QACN,MAAM,SACN,MAAM,cACN,MAAM,GACJ,wBAAwB,CAcpC;IAmmBD;;;;OAIG;IACH,yCAJW,MAAM,0CAEN;QAAC,OAAO,yBAAwB;KAAC,QAc3C;IA+MD,iFAcC;IAWD,gFAiCC;IAWD,kFAsBC;IA+GD,gFA0CC;IA3nCD;;;OAGG;IACH;QAF8B,MAAM;OAwCnC;IA4BD;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;;;OAKG;IACH,2BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;;;;;OAOG;IACH,mBAHW,MAAM,GACJ,MAAM,CAiBlB;IAED;;;;;OAKG;IACH,4BAEC;IAED;;;;;OAKG;IACH,2BAEC;IAED;;;;;OAKG;IACH,qBAHW,mBAAmB,GACjB,MAAM,CAQlB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,UACN,mBAAmB,QAQ7B;IAED;;OAEG;IACH,qBAFW,MAAM,QAUhB;IAED;;;;;OAKG;IACH,uBAHW,mBAAmB,EAAE,GACnB,MAAM,CAsBlB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,UACN,mBAAmB,QAgB7B;IAED;;;OAGG;IACH,wBAHW,MAAM,SACN,MAAM,QAYhB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,MAAM,CAuBlB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,SACN,MAAM,QAmBhB;IAED;;;OAGG;IACH,qBAHW,MAAM,SACN,MAAM,QAUhB;IAyID;;;;;;;;;;;;;;;;;;;OAmBG;IACH;QAf+B,KAAK,EAAzB,UAAU;QACW,cAAc,EAAnC,WAAW;QAEgB,MAAM,EAAjC,UAAU,MAAM,CAAC;QAID,UAAU,EAA1B,MAAM;QAEU,gBAAgB,EAAhC,MAAM;QAEU,SAAS,EAAzB,MAAM;aA4ChB;IAyND;;;;;;;;;;;;OAYG;IACH;QAJ+B,KAAK,EAAzB,UAAU;QACe,KAAK,EAA9B,eAAe;QACe,MAAM,EAApC,eAAe,GAAC,IAAI;aA8H9B;IAmHD;;;;;;;;;;;OAWG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACe,OAAO,EAAhC,eAAe;QACC,EAAE,EAAlB,MAAM;QACJ,MAAM,GAAC,IAAI,CAuFvB;IAyDD;;;OAGG;IACH,gBAwBC;;CACJ;yBAp7CY,OAAO,8DAA8D,EAAE,UAAU;8BACjF,OAAO,6CAA6C,EAAE,eAAe;8BACrE,OAAO,uBAAuB,EAAE,eAAe;kCAC/C,OAAO,kFAAkF,EAAE,mBAAmB;kCAC9G,OAAO,2EAA2E,EAAE,mBAAmB;4BAtCxF,mCAAmC;yCADtB,mDAAmD"}

package/src/shade/renderer/fluid/forcing/GPUFluidForcing.js

@@ -410,6 +410,16 @@ export class GPUFluidForcing {
         return this.#database.get(FLUID_OBSTACLE_TABLE).count;
     }
 
+    /**
+     * A number that changes whenever an effector or obstacle row is added or removed: while it stands, a
+     * list of either table's rows is the list it was.
+     *
+     * @returns {number}
+     */
+    get sets_version() {
+        return this.#sets_version;
+    }
+
     /**
      * Every obstacle and effector row: the leaves of the finest tree, before its resolution cull.
      * @returns {number}

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.d.ts

@@ -274,11 +274,17 @@ export class GPUGeometrySDFManager {
      * `caches`, as the device holds them when the readbacks land: each brick once, however many fields
      * hold it, and each cache naming its field. Read while nothing bakes, it is what was baked.
      *
+     * With `morton`, the bundle is laid out for locality (`model_cache_bundle_sort_morton`): each field's
+     * bricks numbered in Morton order, its surface blocks with them, and the bricks in that order, which
+     * {@link upload_bundle} places them in. Off by default: worth it for assets prepared offline, where it
+     * costs nothing at load, and worth about 0.5% to the probe clipmap's material gather there.
+     *
      * @param {GPUGeometryMetadata[]} records
      * @param {number[]} caches surface cache ids, each of a geometry of `records`
+     * @param {boolean} [morton] lay the bundle out in Morton order
      * @returns {Promise<ModelCacheBundle>}
      */
-    export_bundle(records: GPUGeometryMetadata[], caches: number[]): Promise<ModelCacheBundle>;
+    export_bundle(records: GPUGeometryMetadata[], caches: number[], morton?: boolean): Promise<ModelCacheBundle>;
     /**
      * Record the frame's bake: queue again what is held for the other side than it was baked for, free
      * what was given back, classify what is admitted, and take, evaluate and store up to `budget`

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometrySDFManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js"],"names":[],"mappings":"AAmLA;;;;GAIG;AACH,uCAFU,MAAM,CAEuH;AAoEvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH;IA8QI;;;OAGG;IACH,2CAFW,kBAAkB,EAS5B;IA7QD;;;;OAIG;IACH,aAAuB;IAEvB;;;;OAIG;IACH,iBAA2B;IAE3B;;;;OAIG;IACH,iBAA2B;IA4P3B;;;;;OAKG;IACH,qCAEC;IAED;;;;;;OAMG;IACH,sBAHW,MAAM,cACN,MAAM,QAkChB;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAajB;IAiCD;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAqBjB;IAED;;OAEG;IACH,aAYC;IAED;;;;;OAKG;IACH,eAFW,mBAAmB,QAiB7B;IAED;;;;;;;;;;;;OAYG;IACH,aAHW,mBAAmB,UACnB,mBAAmB,QAwD7B;IAcD;;;;;OAKG;IACH,iBAHW,mBAAmB,GACjB,YAAY,CAcxB;IAED;;;;;;OAMG;IACH,qBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;;;OAKG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,8BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAUC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;OAIG;IACH,8BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,6BAIC;IAED;;;OAGG;IACH,8EAIC;IAED;;;;;;OAMG;IACH,mCAOC;IAED;;OAEG;IACH,+BAcC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBANW,gBAAgB,WAChB,CAAC,mBAAmB,GAAC,IAAI,CAAC,EAAE,aAC5B,CAAC,aAAa,GAAC,IAAI,CAAC,EAAE,eACtB,OAAO,GACL,MAAM,CA2JlB;IA2CD;;;;;;;;OAQG;IACH,uBAJW,mBAAmB,EAAE,UACrB,MAAM,EAAE,GACN,QAAQ,gBAAgB,CAAC,CAqIrC;IAED;;;;;;;;;;;;;OAaG;IACH;QAP+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACW,cAAc,GAA/B,MAAM;QAEoC,SAAS,GAAnD,0BAA0B,GAAC,IAAI;aA+EzC;IAy+BD,gBAsCC;;CACJ;yBAj6EY,OAAO,8DAA8D,EAAE,UAAU;iCACjF,OAAO,0BAA0B,EAAE,kBAAkB;kCACrD,OAAO,2BAA2B,EAAE,mBAAmB;yCACvD,OAAO,uDAAuD,EAAE,0BAA0B;4BAC1F,OAAO,iCAAiC,EAAE,aAAa;qCAnB/B,mCAAmC;6BAOjE,eAAe;iCATyD,8BAA8B"}
+{"version":3,"file":"GPUGeometrySDFManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js"],"names":[],"mappings":"AAoLA;;;;GAIG;AACH,uCAFU,MAAM,CAEuH;AAoEvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH;IA8QI;;;OAGG;IACH,2CAFW,kBAAkB,EAS5B;IA7QD;;;;OAIG;IACH,aAAuB;IAEvB;;;;OAIG;IACH,iBAA2B;IAE3B;;;;OAIG;IACH,iBAA2B;IA4P3B;;;;;OAKG;IACH,qCAEC;IAED;;;;;;OAMG;IACH,sBAHW,MAAM,cACN,MAAM,QAkChB;IAED;;OAEG;IACH,yBAEC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAajB;IAiCD;;;;;OAKG;IACH,gBAHW,mBAAmB,aACnB,OAAO,QAqBjB;IAED;;OAEG;IACH,aAYC;IAED;;;;;OAKG;IACH,eAFW,mBAAmB,QAiB7B;IAED;;;;;;;;;;;;OAYG;IACH,aAHW,mBAAmB,UACnB,mBAAmB,QAwD7B;IAcD;;;;;OAKG;IACH,iBAHW,mBAAmB,GACjB,YAAY,CAcxB;IAED;;;;;;OAMG;IACH,qBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;;;OAKG;IACH,wBAHW,mBAAmB,GACjB,OAAO,CAInB;IAED;;;OAGG;IACH,8BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,2BAUC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;OAIG;IACH,8BAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,yBAIC;IAED;;;OAGG;IACH,6BAIC;IAED;;;OAGG;IACH,8EAIC;IAED;;;;;;OAMG;IACH,mCAOC;IAED;;OAEG;IACH,+BAcC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,sBANW,gBAAgB,WAChB,CAAC,mBAAmB,GAAC,IAAI,CAAC,EAAE,aAC5B,CAAC,aAAa,GAAC,IAAI,CAAC,EAAE,eACtB,OAAO,GACL,MAAM,CAiLlB;IA2CD;;;;;;;;;;;;;;OAcG;IACH,uBALW,mBAAmB,EAAE,UACrB,MAAM,EAAE,WACR,OAAO,GACL,QAAQ,gBAAgB,CAAC,CAuIrC;IAED;;;;;;;;;;;;;OAaG;IACH;QAP+B,KAAK,EAAzB,UAAU;QACM,MAAM,EAAtB,MAAM;QACW,cAAc,GAA/B,MAAM;QAEoC,SAAS,GAAnD,0BAA0B,GAAC,IAAI;aA+EzC;IAy+BD,gBAsCC;;CACJ;yBA/7EY,OAAO,8DAA8D,EAAE,UAAU;iCACjF,OAAO,0BAA0B,EAAE,kBAAkB;kCACrD,OAAO,2BAA2B,EAAE,mBAAmB;yCACvD,OAAO,uDAAuD,EAAE,0BAA0B;4BAC1F,OAAO,iCAAiC,EAAE,aAAa;qCAnB/B,mCAAmC;6BAOjE,eAAe;iCAVyD,8BAA8B"}

package/src/shade/renderer/geometry/sdf/GPUGeometrySDFManager.js

@@ -59,6 +59,7 @@ import {
     shader_mesh_sdf_upload_store
 } from "./bake/shader_mesh_sdf_upload.js";
 import { ModelCacheBundle, ModelCacheBundleCache, ModelCacheBundleField } from "./bundle/ModelCacheBundle.js";
+import { model_cache_bundle_sort_morton } from "./bundle/model_cache_bundle_sort_morton.js";
 import { download_texture_data } from "../../texture/download_texture_data.js";
 import { GPUMeshSurfaceCaches } from "./surface/GPUMeshSurfaceCaches.js";
 import {
@@ -1083,8 +1084,10 @@ export class GPUGeometrySDFManager {
         this.#ensure_headers(this.#geometries.__last_geometry_index);
 
         const layout = this.#layout;
-        /** the bundle's bricks the upload carries, by their place in it */
+        /** the bundle's bricks the upload carries, by their place in it: placed below in the bundle's order */
         const place_of = new Map();
+        /** each field taken's offset, entry count and indirection words, its entries naming bundle bricks until placed */
+        const writes = [];
         const runs = [];
         const fields = [];
 
@@ -1133,19 +1136,12 @@ export class GPUGeometrySDFManager {
                 const entry = field.entries[e];
 
                 if (entry < MESH_SDF_EMPTY) {
-                    let place = place_of.get(entry);
-
-                    if (place === undefined) {
-                        place = place_of.size;
-                        place_of.set(entry, place);
-                    }
-
-                    // its place in the upload, which link turns into its slot
-                    scratch[2 + e] = place;
-                } else {
-                    scratch[2 + e] = entry;
+                    // the bundle's brick for now: its place in the upload, which link turns into its slot, below
+                    place_of.set(entry, 0);
                 }
 
+                scratch[2 + e] = entry;
+
                 scratch[2 + count + e] = MESH_SDF_UNNUMBERED;
             }
 
@@ -1154,7 +1150,7 @@ export class GPUGeometrySDFManager {
                 scratch[2 + 2 * count + n] = field.numbered[n];
             }
 
-            this.#device.queue.writeBuffer(this.#indirection, 4 * range.offset, scratch);
+            writes.push(range.offset, count, scratch);
 
             this.#records[id] = record;
             this.#ranges[id] = range;
@@ -1184,6 +1180,33 @@ export class GPUGeometrySDFManager {
             return 0;
         }
 
+        // the bricks placed in the bundle's order, about the order the fresh pass pops their slots in (an atomic a
+        // thread). A sorted bundle's (`model_cache_bundle_sort_morton`) is its own. A whole exported bundle's,
+        // every field taken, is the order its fields first name them; with fields left out, the bricks of
+        // those taken still keep the bundle's order
+        const placed = Array.from(place_of.keys()).sort((a, b) => a - b);
+
+        for (let place = 0; place < placed.length; place++) {
+            place_of.set(placed[place], place);
+        }
+
+        // after every growth's copy is submitted, so none of these is copied over
+        for (let w = 0; w < writes.length; w += 3) {
+            const offset = writes[w];
+            const count = writes[w + 1];
+            const scratch = writes[w + 2];
+
+            for (let e = 0; e < count; e++) {
+                const entry = scratch[2 + e];
+
+                if (entry < MESH_SDF_EMPTY) {
+                    scratch[2 + e] = place_of.get(entry);
+                }
+            }
+
+            this.#device.queue.writeBuffer(this.#indirection, 4 * offset, scratch);
+        }
+
         const brick_count = place_of.size;
         const bytes = new Uint8Array(Math.max(4, brick_count * MESH_SDF_BRICK_TEXEL_COUNT));
 
@@ -1273,11 +1296,19 @@ export class GPUGeometrySDFManager {
      * `caches`, as the device holds them when the readbacks land: each brick once, however many fields
      * hold it, and each cache naming its field. Read while nothing bakes, it is what was baked.
      *
+     * With `morton`, the bundle is laid out for locality (`model_cache_bundle_sort_morton`): each field's
+     * bricks numbered in Morton order, its surface blocks with them, and the bricks in that order, which
+     * {@link upload_bundle} places them in. Off by default: worth it for assets prepared offline, where it
+     * costs nothing at load, and worth about 0.5% to the probe clipmap's material gather there.
+     *
      * @param {GPUGeometryMetadata[]} records
      * @param {number[]} caches surface cache ids, each of a geometry of `records`
+     * @param {boolean} [morton] lay the bundle out in Morton order
      * @returns {Promise<ModelCacheBundle>}
      */
-    async export_bundle(records, caches) {
+    async export_bundle(records, caches, morton = false) {
+        assert.isBoolean(morton, 'morton');
+
         this.#ensure_device();
 
         for (let i = 0; i < records.length; i++) {
@@ -1407,7 +1438,7 @@ export class GPUGeometrySDFManager {
             bundle.caches.push(this.#surfaces.export_cache(caches[i], field, data, new ModelCacheBundleCache()));
         }
 
-        return bundle;
+        return morton ? model_cache_bundle_sort_morton(bundle) : bundle;
     }
 
     /**

package/src/shade/renderer/geometry/sdf/bundle/ModelCacheBundle.d.ts

@@ -91,8 +91,9 @@ export class ModelCacheBundleCache {
  * takes it only at the same.
  *
  * `GPUGeometrySDFManager.export_bundle` makes one of what is resident; `upload_bundle` takes one back,
- * with or without sharing its bricks with those resident; `model_cache_bundle_write` and
- * `model_cache_bundle_read` keep it as bytes.
+ * with or without sharing its bricks with those resident, placing them in the order the bundle holds
+ * them; `model_cache_bundle_write` and `model_cache_bundle_read` keep it as bytes; and
+ * `model_cache_bundle_sort_morton` lays one out in Morton order for offline preparation.
  */
 export class ModelCacheBundle {
     /**

package/src/shade/renderer/geometry/sdf/bundle/ModelCacheBundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModelCacheBundle.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/bundle/ModelCacheBundle.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH;IACI;;;OAGG;IACH,QAFU,YAAY,CAEO;IAE7B;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,WAAW,CAEO;IAE5B;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;OAIG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;OAIG;IACH,UAFU,WAAW,CAES;IAE9B;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,OAFU,WAAW,CAEM;CAC9B;AAED;;;GAGG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,OAFU,WAAW,CAEM;IAE3B;;;;OAIG;IACH,UAFU,WAAW,CAES;IAE9B;;;;OAIG;IACH,QAFU,WAAW,EAAE,CAE+C;CACzE;AAED;;;;;;;;;GASG;AACH;IACI;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,QAFU,UAAU,CAEO;IAE3B;;OAEG;IACH,QAFU,qBAAqB,EAAE,CAErB;IAEZ;;OAEG;IACH,QAFU,qBAAqB,EAAE,CAErB;IAEZ;;OAEG;IACH,0BAEC;CACJ"}
+{"version":3,"file":"ModelCacheBundle.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/bundle/ModelCacheBundle.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH;IACI;;;OAGG;IACH,QAFU,YAAY,CAEO;IAE7B;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,WAAW,CAEO;IAE5B;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;OAIG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;OAIG;IACH,UAFU,WAAW,CAES;IAE9B;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,OAFU,WAAW,CAEM;CAC9B;AAED;;;GAGG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,OAFU,WAAW,CAEM;IAE3B;;;;OAIG;IACH,UAFU,WAAW,CAES;IAE9B;;;;OAIG;IACH,QAFU,WAAW,EAAE,CAE+C;CACzE;AAED;;;;;;;;;;GAUG;AACH;IACI;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,QAFU,UAAU,CAEO;IAE3B;;OAEG;IACH,QAFU,qBAAqB,EAAE,CAErB;IAEZ;;OAEG;IACH,QAFU,qBAAqB,EAAE,CAErB;IAEZ;;OAEG;IACH,0BAEC;CACJ"}

package/src/shade/renderer/geometry/sdf/bundle/ModelCacheBundle.js

@@ -107,8 +107,9 @@ export class ModelCacheBundleCache {
  * takes it only at the same.
  *
  * `GPUGeometrySDFManager.export_bundle` makes one of what is resident; `upload_bundle` takes one back,
- * with or without sharing its bricks with those resident; `model_cache_bundle_write` and
- * `model_cache_bundle_read` keep it as bytes.
+ * with or without sharing its bricks with those resident, placing them in the order the bundle holds
+ * them; `model_cache_bundle_write` and `model_cache_bundle_read` keep it as bytes; and
+ * `model_cache_bundle_sort_morton` lays one out in Morton order for offline preparation.
  */
 export class ModelCacheBundle {
     /**

package/src/shade/renderer/geometry/sdf/bundle/model_cache_bundle_sort_morton.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A copy of a {@link ModelCacheBundle} laid out for locality, holding the same fields and caches: what
+ * every entry reads, the bytes of its brick and its surface blocks, is unchanged.
+ *
+ * - each field's stored bricks are numbered in (level, Morton code of the brick) order, and its block
+ *   table and its caches' blocks follow: a brick's blocks keep its mask and come in number order;
+ * - the bundle's bricks are ordered as the fields first name them, field by field in that numbering,
+ *   with bricks no field names after them. `upload_bundle` places a bundle's bricks in that order, and its
+ *   fresh pass pops their slots in about that order (an atomic a thread), so a field's neighbouring bricks
+ *   mostly sit in neighbouring slots.
+ *
+ * Measured (2026-11-11, a 69k-brick library loaded into the probe clipmap on an RTX 4090 and a Radeon
+ * RDNA2 iGPU): the SDF batch pass does not change, and the brick material gather is about 0.5% faster.
+ * Bake order is already near this one, so the sort is for offline asset preparation, where it costs
+ * nothing at load, and is off unless asked for (`GPUGeometrySDFManager.export_bundle`).
+ *
+ * @param {ModelCacheBundle} bundle
+ * @returns {ModelCacheBundle} a new bundle; `bundle` is left as it was
+ */
+export function model_cache_bundle_sort_morton(bundle: ModelCacheBundle): ModelCacheBundle;
+import { ModelCacheBundle } from "./ModelCacheBundle.js";
+//# sourceMappingURL=model_cache_bundle_sort_morton.d.ts.map

package/src/shade/renderer/geometry/sdf/bundle/model_cache_bundle_sort_morton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model_cache_bundle_sort_morton.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/bundle/model_cache_bundle_sort_morton.js"],"names":[],"mappings":"AA0FA;;;;;;;;;;;;;;;;;;GAkBG;AACH,uDAHW,gBAAgB,GACd,gBAAgB,CA2I5B;iCA9O8E,uBAAuB"}

package/src/shade/renderer/geometry/sdf/bundle/model_cache_bundle_sort_morton.js

@@ -0,0 +1,247 @@
+import { assert } from "../../../../../core/assert.js";
+import { v3_morton_encode_magicbits } from "../../../../../core/geom/3d/morton/v3_morton_encode_magicbits.js";
+import { MESH_SDF_BRICK_TEXEL_COUNT, MESH_SDF_EMPTY } from "../MESH_SDF.js";
+import {
+    MESH_SURFACE_PLANE_BLOCK_WORDS,
+    MESH_SURFACE_PRESENCE_BLOCK_WORDS,
+    MESH_SURFACE_TABLE_MASK_BITS
+} from "../surface/MESH_SURFACE_BLOCK.js";
+import { ModelCacheBundle, ModelCacheBundleCache, ModelCacheBundleField } from "./ModelCacheBundle.js";
+
+/**
+ * Bricks along an axis a level's Morton code holds: 10 bits an axis.
+ * @type {number}
+ */
+const MORTON_AXIS_LIMIT = 1 << 10;
+
+/**
+ * @param {number} v
+ * @returns {number}
+ */
+function popcount8(v) {
+    let c = 0;
+
+    for (let b = 0; b < 8; b++) {
+        c += (v >>> b) & 1;
+    }
+
+    return c;
+}
+
+/**
+ * Each entry's place in (level, Morton code of its brick) order, levels coarsening as `MeshSDFLayout`'s
+ * do: level k has ⌈bricks / 2^k⌉ along each axis, its entries after every finer level's, x fastest.
+ *
+ * @param {ModelCacheBundleField} field
+ * @returns {Float64Array} a key an entry
+ */
+function entry_keys(field) {
+    const keys = new Float64Array(field.entries.length);
+
+    let e = 0;
+
+    for (let level = 0; level < field.level_count; level++) {
+        const nx = Math.ceil(field.bricks[0] / 2 ** level);
+        const ny = Math.ceil(field.bricks[1] / 2 ** level);
+        const nz = Math.ceil(field.bricks[2] / 2 ** level);
+
+        assert.ok(nx <= MORTON_AXIS_LIMIT && ny <= MORTON_AXIS_LIMIT && nz <= MORTON_AXIS_LIMIT, 'field.bricks: past the 10 bits an axis a Morton code holds');
+
+        for (let z = 0; z < nz; z++) {
+            for (let y = 0; y < ny; y++) {
+                for (let x = 0; x < nx; x++) {
+                    // 30 bits of code under the level: exact in a double
+                    keys[e++] = level * 2 ** 30 + v3_morton_encode_magicbits(x, y, z);
+                }
+            }
+        }
+    }
+
+    assert.equal(e, field.entries.length, 'field.entries: one a brick of its levels');
+
+    return keys;
+}
+
+/**
+ * `words` holding `per_block` words for each block, its blocks moved: run r of `runs` (old first block,
+ * new first block, blocks) from its old place to its new.
+ *
+ * @param {Uint32Array} words
+ * @param {number} per_block
+ * @param {number} blocks
+ * @param {number[]|null} runs null for a field with no table, whose blocks no brick numbers
+ * @returns {Uint32Array}
+ */
+function move_blocks(words, per_block, blocks, runs) {
+    if (words.length === 0 || runs === null) {
+        return words.slice();
+    }
+
+    assert.equal(words.length, blocks * per_block, 'a cache\'s blocks: its field\'s, each of its plane\'s words');
+
+    const out = new Uint32Array(words.length);
+
+    for (let r = 0; r < runs.length; r += 3) {
+        out.set(words.subarray(runs[r] * per_block, (runs[r] + runs[r + 2]) * per_block), runs[r + 1] * per_block);
+    }
+
+    return out;
+}
+
+/**
+ * A copy of a {@link ModelCacheBundle} laid out for locality, holding the same fields and caches: what
+ * every entry reads, the bytes of its brick and its surface blocks, is unchanged.
+ *
+ * - each field's stored bricks are numbered in (level, Morton code of the brick) order, and its block
+ *   table and its caches' blocks follow: a brick's blocks keep its mask and come in number order;
+ * - the bundle's bricks are ordered as the fields first name them, field by field in that numbering,
+ *   with bricks no field names after them. `upload_bundle` places a bundle's bricks in that order, and its
+ *   fresh pass pops their slots in about that order (an atomic a thread), so a field's neighbouring bricks
+ *   mostly sit in neighbouring slots.
+ *
+ * Measured (2026-11-11, a 69k-brick library loaded into the probe clipmap on an RTX 4090 and a Radeon
+ * RDNA2 iGPU): the SDF batch pass does not change, and the brick material gather is about 0.5% faster.
+ * Bake order is already near this one, so the sort is for offline asset preparation, where it costs
+ * nothing at load, and is off unless asked for (`GPUGeometrySDFManager.export_bundle`).
+ *
+ * @param {ModelCacheBundle} bundle
+ * @returns {ModelCacheBundle} a new bundle; `bundle` is left as it was
+ */
+export function model_cache_bundle_sort_morton(bundle) {
+    const out = new ModelCacheBundle();
+
+    out.voxel_size = bundle.voxel_size;
+    out.max_bricks = bundle.max_bricks;
+
+    const brick_count = bundle.brick_count;
+    /** the new index of each old brick, -1 until a field names it */
+    const brick_to = new Int32Array(brick_count).fill(-1);
+    let next_brick = 0;
+
+    /** each field's runs of moved blocks, for its caches */
+    const field_runs = [];
+
+    for (let f = 0; f < bundle.fields.length; f++) {
+        const field = bundle.fields[f];
+        const stored = field.numbered.length;
+        const keys = entry_keys(field);
+
+        // brick n's new number is its place in key order; entries are distinct, so no two keys tie
+        const order = Array.from({ length: stored }, (_, n) => n);
+
+        order.sort((a, b) => keys[field.numbered[a]] - keys[field.numbered[b]]);
+
+        const sorted = new ModelCacheBundleField();
+
+        sorted.origin.set(field.origin);
+        sorted.voxel = field.voxel;
+        sorted.bricks.set(field.bricks);
+        sorted.level_count = field.level_count;
+        sorted.two_sided = field.two_sided;
+        sorted.blocks = field.blocks;
+        sorted.numbered = new Uint32Array(stored);
+
+        for (let m = 0; m < stored; m++) {
+            sorted.numbered[m] = field.numbered[order[m]];
+        }
+
+        // without a table no block is numbered by a brick: a cache's blocks, if any, stay where they are
+        let runs = null;
+
+        if (field.table.length > 0) {
+            runs = [];
+            assert.equal(field.table.length, stored, 'field.table: a word a stored brick, or none');
+
+            sorted.table = new Uint32Array(stored);
+
+            // every block in exactly one brick's run, as a survey hands them out: what moves them losslessly
+            const covered = new Uint8Array(field.blocks);
+
+            let first = 0;
+
+            for (let m = 0; m < stored; m++) {
+                const word = field.table[order[m]];
+                const mask = word & ((1 << MESH_SURFACE_TABLE_MASK_BITS) - 1);
+                const count = popcount8(mask);
+                const from = word >>> MESH_SURFACE_TABLE_MASK_BITS;
+
+                sorted.table[m] = ((first << MESH_SURFACE_TABLE_MASK_BITS) | mask) >>> 0;
+
+                if (count > 0) {
+                    assert.lessThanOrEqual(from + count, field.blocks, 'field.table: a run past the field\'s blocks');
+
+                    for (let b = from; b < from + count; b++) {
+                        assert.equal(covered[b], 0, 'field.table: two bricks\' runs share a block');
+                        covered[b] = 1;
+                    }
+
+                    runs.push(from, first, count);
+                }
+
+                first += count;
+            }
+
+            assert.equal(first, field.blocks, 'field.blocks: the blocks its table\'s masks keep');
+        }
+
+        field_runs.push(runs);
+
+        // the bricks as this field first names them, in its new numbering
+        for (let m = 0; m < stored; m++) {
+            const brick = field.entries[sorted.numbered[m]];
+
+            assert.lessThan(brick, brick_count, 'a numbered entry names a brick of the bundle');
+
+            if (brick_to[brick] === -1) {
+                brick_to[brick] = next_brick++;
+            }
+        }
+
+        out.fields.push(sorted);
+    }
+
+    // bricks no field numbers: after the rest, as they were
+    for (let b = 0; b < brick_count; b++) {
+        if (brick_to[b] === -1) {
+            brick_to[b] = next_brick++;
+        }
+    }
+
+    out.bricks = new Uint8Array(bundle.bricks.length);
+
+    for (let b = 0; b < brick_count; b++) {
+        out.bricks.set(bundle.bricks.subarray(b * MESH_SDF_BRICK_TEXEL_COUNT, (b + 1) * MESH_SDF_BRICK_TEXEL_COUNT), brick_to[b] * MESH_SDF_BRICK_TEXEL_COUNT);
+    }
+
+    for (let f = 0; f < bundle.fields.length; f++) {
+        const entries = bundle.fields[f].entries;
+        const renamed = new Uint32Array(entries.length);
+
+        for (let e = 0; e < entries.length; e++) {
+            const entry = entries[e];
+
+            renamed[e] = entry < MESH_SDF_EMPTY ? brick_to[entry] : entry;
+        }
+
+        out.fields[f].entries = renamed;
+    }
+
+    for (const cache of bundle.caches) {
+        const sorted = new ModelCacheBundleCache();
+        const runs = field_runs[cache.field];
+        const blocks = bundle.fields[cache.field].blocks;
+
+        sorted.field = cache.field;
+        sorted.texels = cache.texels;
+        sorted.codes.set(cache.codes);
+        sorted.presence = move_blocks(cache.presence, MESH_SURFACE_PRESENCE_BLOCK_WORDS, blocks, runs);
+
+        for (let p = 0; p < cache.planes.length; p++) {
+            sorted.planes[p] = move_blocks(cache.planes[p], MESH_SURFACE_PLANE_BLOCK_WORDS[p], blocks, runs);
+        }
+
+        out.caches.push(sorted);
+    }
+
+    return out;
+}

package/src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.d.ts

@@ -88,6 +88,56 @@ export class GPUProbeClipmapGI {
      * @returns {boolean}
      */
     get has_probes(): boolean;
+    /**
+     * Record the wants of a screen surface drawn apart from the G-buffer whose reader picks the frustum's probes a
+     * pixel (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): the water's interface. A pixel of each screen tile wants
+     * the cages its pick reads, as the G-buffer's pixels do (`ProbeClipmapScreenWants`).
+     *
+     * For a pass after this frame's {@link graph_update}, once the surface is drawn. Its wants are taken by the
+     * next frame's lifetime, so a probe the surface newly reads is there a frame after the surface is. Records
+     * nothing where there are no probes ({@link has_probes}): out of the mode it costs nothing.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.depth graph handle of the surface's reverse-Z depth, zero where it has none
+     * @param {number} options.normal graph handle of its normals, a `uint` texture: a channel holds a normal
+     *   octahedral, as the G-buffer packs its own
+     * @param {number} [options.normal_channel] the channel that holds the normal, 0 to 3
+     * @param {boolean} [options.two_sided] whether the reader turns a normal that faces away from the eye to face it
+     * @param {GPUBuffer} options.camera the camera uniform the surface was drawn with
+     * @param {ArrayLike<number>} options.resolution the surface's pixels, x and y
+     */
+    graph_want_surface({ graph, depth, normal, normal_channel, two_sided, camera, resolution }: {
+        graph: FrameGraph;
+        depth: number;
+        normal: number;
+        normal_channel?: number;
+        two_sided?: boolean;
+        camera: GPUBuffer;
+        resolution: ArrayLike<number>;
+    }): void;
+    /**
+     * Record the wants of a list of meshlets a forward pass draws, whose fragments pick the frustum's probes
+     * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): each wants the cages a reader anywhere inside its box can
+     * read (`graph_probe_clipmap_want_meshlets`).
+     *
+     * For a pass after this frame's {@link graph_update}; taken by the next frame's lifetime, as
+     * {@link graph_want_surface}'s are. Records nothing where there are no probes ({@link has_probes}).
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {import("../../scene/GPUSceneContext.js").GPUSceneContext} options.scene the meshlets' scene
+     * @param {number} options.camera graph handle of the view's camera uniform
+     * @param {number} options.meshlet_collection graph handle of the list, `MESHLET_COLLECTION_STRUCT`
+     * @param {number} options.meshlet_iterator_command graph handle of the indirect dispatch that walks the list
+     */
+    graph_want_meshlets({ graph, scene, camera, meshlet_collection, meshlet_iterator_command }: {
+        graph: FrameGraph;
+        scene: import("../../scene/GPUSceneContext.js").GPUSceneContext;
+        camera: number;
+        meshlet_collection: number;
+        meshlet_iterator_command: number;
+    }): void;
     /**
      * Put what the probes' readers bind into `bindings`, `PROBE_CLIPMAP_SAMPLING_GROUP` but its sampler:
      * once {@link has_probes}, the probes as this frame's {@link graph_update} left them