@woosh/meep-engine 3.19.0 → 3.21.0

package/src/shade/playground/basis_textures/texture_inventory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"texture_inventory.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/basis_textures/texture_inventory.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;GAkBG;AACH,yCANW,QAAQ;WACE,MAAM;aAAW,IAAI,MAAM,EAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,IAAI,MAAM,CAAC,CAAA;KAAC,CAAC;cAAY,cAAc;EAgE/G"}
+{"version":3,"file":"texture_inventory.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/basis_textures/texture_inventory.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;GAkBG;AACH,yCANW,QAAQ,GACN;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,IAAI,MAAM,EAAE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,IAAI,MAAM,CAAC,CAAA;KAAC,CAAC,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAC,CAgEhH"}

package/src/shade/playground/bvh_repro/bvh_repro_device.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bvh_repro_device.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/bvh_repro/bvh_repro_device.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH;cAFgC,eAAe;;;GA0C9C;AAED;;;;;;;;GAQG;AACH,yEAFa;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,EAAE,CAwB5C;gCAxF+B,mCAAmC"}
+{"version":3,"file":"bvh_repro_device.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/bvh_repro/bvh_repro_device.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,oCAFa,QAAQ;IAAC,QAAQ,EAAE,eAAe,CAAC;IAAC,MAAM,YAAY;IAAC,OAAO,aAAY;CAAC,CAAC,CA0CxF;AAED;;;;;;;;GAQG;AACH,yEAFa;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,EAAE,CAwB5C;gCAxF+B,mCAAmC"}

package/src/shade/playground/ground_seam/capture_scene_color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capture_scene_color.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ground_seam/capture_scene_color.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;GAcG;AACH;IA2CI;;OAEG;IACH,+BAIC;IAfD;;;;;OAKG;IACH,SAFU,OAAO,CAED;IAuEhB;;;;;;;;OAQG;IACH;cAF4B,YAAY;eAAS,MAAM;gBAAU,MAAM;OAwCtE;;CACJ;gCA5N+B,6CAA6C"}
+{"version":3,"file":"capture_scene_color.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ground_seam/capture_scene_color.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;;;;;GAcG;AACH;IA2CI;;OAEG;IACH,+BAIC;IAfD;;;;;OAKG;IACH,SAFU,OAAO,CAED;IAuEhB;;;;;;;;OAQG;IACH,kBAFa,QAAQ;QAAC,IAAI,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC,CAwCxE;;CACJ;gCA5N+B,6CAA6C"}

package/src/shade/playground/ground_seam/measure_flicker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"measure_flicker.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ground_seam/measure_flicker.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;GAiBG;AACH,kEARW,MAAM,UACN,MAAM,WACN,MAAM;UACG,SAAS;kBAAgB,SAAS;yBAAuB,MAAM;aAAW,MAAM;EAmHnG;AAED;;;;;;;GAOG;AACH;IAJ6B,QAAQ;IACX,KAAK;IACO,MAAM;;2BAqE7B,MAAM;gBAQN,MAAM;;QAoFW,aAAa,GAA9B,MAAM;QACW,MAAM,GAAvB,MAAM;;gBACa,YAAY;cAAQ,YAAY;eAAS,MAAM;gBAAU,MAAM;;;eA4DhE,YAAY;eAAS,MAAM;gBAAU,MAAM;;;EAkE3E;AAED;;;;;;;;;;;;;GAaG;AACH,uEALW,MAAM,UACN,MAAM,aACN,MAAM,EAAE,UACG,MAAM,QAAE,MAAM,KAAG,MAAM,CAyC5C"}
+{"version":3,"file":"measure_flicker.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ground_seam/measure_flicker.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;GAiBG;AACH,kEARW,MAAM,UACN,MAAM,WACN,MAAM,GACJ;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,YAAY,EAAE,SAAS,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAmHpG;AAED;;;;;;;GAOG;AACH;IAJ6B,QAAQ;IACX,KAAK;IACO,MAAM;;2BAqE7B,MAAM;gBAQN,MAAM;;QAoFW,aAAa,GAA9B,MAAM;QACW,MAAM,GAAvB,MAAM;UACJ,QAAQ;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC;sBA4DlF,QAAQ;QAAC,KAAK,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC;;EAkE7E;AAED;;;;;;;;;;;;;GAaG;AACH,uEALW,MAAM,UACN,MAAM,aACN,MAAM,EAAE,UACG,MAAM,QAAE,MAAM,KAAG,MAAM,CAyC5C"}

package/src/shade/playground/particle_editor/README.md

@@ -82,7 +82,7 @@ edits it at both altitudes.
   curve, including peaks between keys. Its fields edit the selected key's time, value and tangents.
   The scale stays fixed during a drag and refits on release. Neither ramp is sampled from a table
   at runtime: both are written out into the program as arithmetic, which is what the **Code** tab
-  shows. `Curve Table`, which *is* the table, is the other node — it takes a row handle rather than a curve.
+  shows.
 - The strip along the bottom lists every problem with the effect, from **both** phases, loudest
   first. Click one to jump to the phase it is in and select the node; the node is outlined in the
   graph too.

package/src/shade/playground/particle_system/index.html

@@ -134,7 +134,6 @@
     <div><span class="key">fps</span><span id="stat-fps">—</span></div>
     <div><span class="key">alive</span><span id="stat-alive">—</span></div>
     <div><span class="key">free</span><span id="stat-dead">—</span></div>
-    <div><span class="key">draw instances</span><span id="stat-draw">—</span></div>
     <div><span class="key">sim lanes</span><span id="stat-sim-lanes">—</span></div>
     <div><span class="key">sim workgroups</span><span id="stat-dispatch">—</span></div>
 </div>

package/src/shade/playground/particle_system/main.js

@@ -306,7 +306,7 @@ async function main() {
 }
 
 /** Push one stats snapshot into the overlay. Absent elements are simply skipped. */
-function write_hud({ fps, alive, dead, dispatch, draw, sim_padded }) {
+function write_hud({ fps, alive, dead, dispatch, sim_padded }) {
     const put = (id, value) => {
         const node = element(id);
         if (node !== null) {
@@ -317,7 +317,6 @@ function write_hud({ fps, alive, dead, dispatch, draw, sim_padded }) {
     put("stat-fps", fps.toFixed(0));
     put("stat-alive", alive.toLocaleString());
     put("stat-dead", dead.toLocaleString());
-    put("stat-draw", draw[1].toLocaleString());
     // Padding rounds each program's run up to a whole workgroup, so this is >= alive; the gap is
     // what wave-coherence costs in lanes.
     put("stat-sim-lanes", sim_padded.toLocaleString());

package/src/shade/playground/particle_system/particle_prototype.d.ts

@@ -1,31 +1,29 @@
 /**
  * Worked examples of authoring particle effects with the node graph + placing them in a scene for a
  * {@link GPUParticleSystem} to run. Demonstrates: distinct per-particle lifecycle (no built-in age — the
- * effect declares it), AnimationCurve sampling over life, flipbook frames, random emission,
+ * effect declares it), authored curves over life, flipbook frames, random emission,
  * additive vs alpha blending, projection modes, soft depth and lighting toggles.
  *
  * These are examples, not engine code, which is why they sit here rather than under
  * `renderer/particles/`: the only thing that opens them is this playground's page, and keeping them
  * on this side of the line means the dependency runs playground -> renderer and never back.
  *
- * `curves` is a `GPUAnimationManager` (or anything with `register_curve(AnimationCurve) -> handle`);
- * `size_curve` / `alpha_curve` are meep `AnimationCurve`s. Both are optional — passing `undefined`
- * yields effects that use constant size/alpha instead (curve handle 0, evaluated as 0 by the
- * disabled provider), which is handy for the headless tests.
+ * `size_curve` / `alpha_curve` are authored curve parameters compiled into arithmetic. Both are
+ * optional; omitted curves leave the initial size/colour unchanged.
  */
 /**
  * A fire effect: buoyant, turbulent, additive-blended camera-facing sprites whose size and opacity
  * follow curves over their lifetime and whose flipbook advances with age.
  *
  * @param {object} [options]
- * @param {number} [options.size_curve] curve handle for size(normalizedAge)
- * @param {number} [options.alpha_curve] curve handle for alpha(normalizedAge)
+ * @param {import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter} [options.size_curve] size(normalizedAge)
+ * @param {import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter} [options.alpha_curve] alpha(normalizedAge)
  * @param {number} [options.flipbook_frames]
  * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
  */
 export function fire_effect({ size_curve, alpha_curve, flipbook_frames }?: {
-    size_curve?: number;
-    alpha_curve?: number;
+    size_curve?: import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter;
+    alpha_curve?: import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter;
     flipbook_frames?: number;
 }): {
     layout: ParticleLayout;

package/src/shade/playground/particle_system/particle_prototype.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_prototype.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_prototype.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH;IAL4B,UAAU,GAA3B,MAAM;IACW,WAAW,GAA5B,MAAM;IACW,eAAe,GAAhC,MAAM;;YACK,cAAc;YAAU,MAAM;aAAW,MAAM;EA+GpE;AAED;;;;GAIG;AACH;YAFsB,cAAc;YAAU,MAAM;aAAW,MAAM;EAYpE;AAED;;;;;;;;;;;;;GAaG;AACH,yCANW,OAAO,+BAA+B,EAAE,KAAK;IAEa,IAAI,GAA9D,OAAO,gCAAgC,EAAE,MAAM;;UAEtC,eAAe;WAAS,eAAe;EAe1D;+BAzL8B,mDAAmD;gCAElD,qDAAqD"}
+{"version":3,"file":"particle_prototype.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_prototype.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;GASG;AACH;IALsG,UAAU,GAArG,OAAO,iDAAiD,EAAE,sBAAsB;IACW,WAAW,GAAtG,OAAO,iDAAiD,EAAE,sBAAsB;IAC/D,eAAe,GAAhC,MAAM;IACJ;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CA+GrE;AAED;;;;GAIG;AACH,gCAFa;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAYrE;AAED;;;;;;;;;;;;;GAaG;AACH,yCANW,OAAO,+BAA+B,EAAE,KAAK;IAEa,IAAI,GAA9D,OAAO,gCAAgC,EAAE,MAAM;IAE7C;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAC,CAe3D;+BAvL8B,mDAAmD;gCAElD,qDAAqD"}

package/src/shade/playground/particle_system/particle_prototype.js

@@ -13,17 +13,15 @@ import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitte
 /**
  * Worked examples of authoring particle effects with the node graph + placing them in a scene for a
  * {@link GPUParticleSystem} to run. Demonstrates: distinct per-particle lifecycle (no built-in age — the
- * effect declares it), AnimationCurve sampling over life, flipbook frames, random emission,
+ * effect declares it), authored curves over life, flipbook frames, random emission,
  * additive vs alpha blending, projection modes, soft depth and lighting toggles.
  *
  * These are examples, not engine code, which is why they sit here rather than under
  * `renderer/particles/`: the only thing that opens them is this playground's page, and keeping them
  * on this side of the line means the dependency runs playground -> renderer and never back.
  *
- * `curves` is a `GPUAnimationManager` (or anything with `register_curve(AnimationCurve) -> handle`);
- * `size_curve` / `alpha_curve` are meep `AnimationCurve`s. Both are optional — passing `undefined`
- * yields effects that use constant size/alpha instead (curve handle 0, evaluated as 0 by the
- * disabled provider), which is handy for the headless tests.
+ * `size_curve` / `alpha_curve` are authored curve parameters compiled into arithmetic. Both are
+ * optional; omitted curves leave the initial size/colour unchanged.
  */
 
 /**
@@ -31,8 +29,8 @@ import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitte
  * follow curves over their lifetime and whose flipbook advances with age.
  *
  * @param {object} [options]
- * @param {number} [options.size_curve] curve handle for size(normalizedAge)
- * @param {number} [options.alpha_curve] curve handle for alpha(normalizedAge)
+ * @param {import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter} [options.size_curve] size(normalizedAge)
+ * @param {import("../../renderer/particles/graph/particle_ramp.js").ParticleCurveParameter} [options.alpha_curve] alpha(normalizedAge)
  * @param {number} [options.flipbook_frames]
  * @returns {{layout: ParticleLayout, effect: object, emitter: object}}
  */
@@ -111,12 +109,12 @@ export function fire_effect({ size_curve, alpha_curve, flipbook_frames = 16 } =
 
         // size + alpha from curves over life (or constants if no curve provided)
         if (size_curve !== undefined) {
-            const sc = particle_node(update, "curve", { handle: size_curve }); particle_wire(update, sc, "t", nAge);
+            const sc = particle_node(update, "curveLiteral", { curve: size_curve }); particle_wire(update, sc, "t", nAge);
             particle_wire(update, particle_node(update, "setAttribute", { name: "size" }), "value", sc);
         }
         const color = particle_node(update, "attribute", { name: "color" });
         if (alpha_curve !== undefined) {
-            const ac = particle_node(update, "curve", { handle: alpha_curve }); particle_wire(update, ac, "t", nAge);
+            const ac = particle_node(update, "curveLiteral", { curve: alpha_curve }); particle_wire(update, ac, "t", nAge);
             // color.rgb unchanged, color.a = ac : rebuild via select on a swizzle mask is overkill;
             // simplest: multiply color by (1,1,1,ac_normalized) — approximate by scaling alpha only.
             const alphaVec = particle_node(update, "mul");

package/src/shade/playground/particle_system/particle_scene.d.ts

@@ -57,9 +57,13 @@ export function configure_particles(renderer: import("../../renderer/Renderer.js
  */
 export function animate_particle_scene(emitters: ReturnType<typeof create_particle_emitters>, time: number): void;
 /**
- * Copy the counters and both indirect arg buffers into a {@link PARTICLE_STATS_BYTES}-byte
+ * Copy the counters and simulate's indirect dispatch args into a {@link PARTICLE_STATS_BYTES}-byte
  * MAP_READ destination, for display. Read back to *look at*: nothing here may size a pass.
  *
+ * The DRAW args are not here and cannot be: they never leave the frame graph, which allocates them
+ * at the build-indirect pass and releases them after the draw. Their instance count is the alive
+ * count, which the counters carry anyway.
+ *
  * @param {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem} system
  * @param {GPUCommandEncoder} encoder
  * @param {GPUBuffer} destination
@@ -116,7 +120,6 @@ export const PARTICLE_STATS_BYTES: 64;
  * @property {number} sim_padded length of the program-coherent list the coherence pass built this
  *   frame; the gap to `alive` is the lanes padding costs to keep each wave on one VM program
  * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
- * @property {number[]} draw the draw's indirect args, `[vertices, instances]`
  */
 /**
  * What each of the four parametric emitters emits, apart from the fire, whose effect is the worked
@@ -162,10 +165,6 @@ export type ParticleSceneStats = {
      * simulate's indirect dispatch args, `[x, y, z]` workgroups
      */
     dispatch: number[];
-    /**
-     * the draw's indirect args, `[vertices, instances]`
-     */
-    draw: number[];
 };
 import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitter.js";
 import { Node3D } from "../../renderer/scene/Node3D.js";

package/src/shade/playground/particle_system/particle_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAwFA;;;;;;;;;;;GAWG;AACH;UAFoB,eAAe;WAAS,eAAe;YAAU,eAAe;UAAQ,eAAe;WAAS,eAAe;WAAS,MAAM;EA+DjJ;AAED;;;;;;;GAOG;AACH;WAF6B,KAAK;cAAY,2CAAoC;;eAAkB,IAAI;gBAAU,IAAI;eAAS,IAAI;cAAQ,IAAI;;GAuD9I;AAED;;;;;;;;;;GAUG;AACH,8CAJW,OAAO,4BAA4B,EAAE,QAAQ,SAC7C,KAAK,GACH,OAAO,+CAA+C,EAAE,iBAAiB,CAmBrF;AAED;;;;;;GAMG;AACH,iDAHW,2CAAoC,QACpC,MAAM,QAWhB;AAED;;;;;;;GAOG;AACH,0CAJW,OAAO,+CAA+C,EAAE,iBAAiB,4DAUnF;AAED;;;;;GAKG;AACH,kCAHW,WAAW,GACT,kBAAkB,CAgB9B;AAED;;;;;GAKG;AACH,mEA4BC;AA5TD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,0FAA0F;AAC1F,sCAAuC;AAKvC;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH;QAFiB,MAAM,GAAE;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC;EAOpJ;;;;;WAtBY,MAAM;;;;UACN,MAAM;;;;kBACN,MAAM;;;;;cACN,MAAM;;;;;gBAEN,MAAM;;;;cAEN,MAAM,EAAE;;;;UACR,MAAM,EAAE;;gCAjDU,qDAAqD;uBAE9D,gCAAgC;sBACjC,+BAA+B;qBAFhC,8BAA8B"}
+{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAsFA;;;;;;;;;;;GAWG;AACH,4CAFa;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CA+DlJ;AAED;;;;;;;GAOG;AACH,wCAFa,QAAQ;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,2CAAoC,CAAC;IAAC,MAAM,EAAE;QAAC,KAAK,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAC,CAAA;CAAC,CAAC,CAuDjJ;AAED;;;;;;;;;;GAUG;AACH,8CAJW,OAAO,4BAA4B,EAAE,QAAQ,SAC7C,KAAK,GACH,OAAO,+CAA+C,EAAE,iBAAiB,CAmBrF;AAED;;;;;;GAMG;AACH,iDAHW,2CAAoC,QACpC,MAAM,QAWhB;AAED;;;;;;;;;;;GAWG;AACH,0CAJW,OAAO,+CAA+C,EAAE,iBAAiB,4DASnF;AAED;;;;;GAKG;AACH,kCAHW,WAAW,GACT,kBAAkB,CAc9B;AAED;;;;;GAKG;AACH,mEA4BC;AA3TD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,0FAA0F;AAC1F,sCAAuC;AAIvC;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH;QAFiB,MAAM,GAAE;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC;EAOpJ;;;;;WArBY,MAAM;;;;UACN,MAAM;;;;kBACN,MAAM;;;;;cACN,MAAM;;;;;gBAEN,MAAM;;;;cAEN,MAAM,EAAE;;gCA/CU,qDAAqD;uBAE9D,gCAAgC;sBACjC,+BAA+B;qBAFhC,8BAA8B"}

package/src/shade/playground/particle_system/particle_scene.js

@@ -58,7 +58,6 @@ import { fire_effect } from "./particle_prototype.js";
 export const PARTICLE_STATS_BYTES = 64;
 
 const STATS_OFFSET_DISPATCH_ARGS = 32;
-const STATS_OFFSET_DRAW_ARGS = 48;
 
 /**
  * @typedef {object} ParticleSceneStats
@@ -70,7 +69,6 @@ const STATS_OFFSET_DRAW_ARGS = 48;
  * @property {number} sim_padded length of the program-coherent list the coherence pass built this
  *   frame; the gap to `alive` is the lanes padding costs to keep each wave on one VM program
  * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
- * @property {number[]} draw the draw's indirect args, `[vertices, instances]`
  */
 
 /**
@@ -273,8 +271,12 @@ export function animate_particle_scene(emitters, time) {
 }
 
 /**
- * Copy the counters and both indirect arg buffers into a {@link PARTICLE_STATS_BYTES}-byte
- * MAP_READ destination, for display. Read back to *look at*: nothing here may size a pass.
+ * Copy the counters and simulate's indirect dispatch args into a {@link PARTICLE_STATS_BYTES}-byte
+ * MAP_READ destination, for display. Read back to *look at*: nothing here may size a pass.
+ *
+ * The DRAW args are not here and cannot be: they never leave the frame graph, which allocates them
+ * at the build-indirect pass and releases them after the draw. Their instance count is the alive
+ * count, which the counters carry anyway.
  *
  * @param {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem} system
  * @param {GPUCommandEncoder} encoder
@@ -285,7 +287,6 @@ export function encode_stats_copy(system, encoder, destination) {
 
     encoder.copyBufferToBuffer(buffers.counters, 0, destination, 0, PARTICLE_COUNTER_COUNT * 4);
     encoder.copyBufferToBuffer(buffers.dispatch_args, 0, destination, STATS_OFFSET_DISPATCH_ARGS, 3 * 4);
-    encoder.copyBufferToBuffer(buffers.draw_args, 0, destination, STATS_OFFSET_DRAW_ARGS, 4 * 4);
 }
 
 /**
@@ -297,7 +298,6 @@ export function encode_stats_copy(system, encoder, destination) {
 export function read_stats(bytes) {
     const words = new Uint32Array(bytes);
     const dispatch_base = STATS_OFFSET_DISPATCH_ARGS / 4;
-    const draw_base = STATS_OFFSET_DRAW_ARGS / 4;
 
     return {
         alive: words[0],
@@ -306,7 +306,6 @@ export function read_stats(bytes) {
         alive_in: words[4],
         sim_padded: words[5],
         dispatch: [words[dispatch_base], words[dispatch_base + 1], words[dispatch_base + 2]],
-        draw: [words[draw_base], words[draw_base + 1]],
     };
 }
 

package/src/shade/playground/skinned_blas_refit/sweep_views.js

@@ -59,7 +59,7 @@ export async function sweep_views({
     const radius = Math.hypot(box[3] - box[0], box[4] - box[1], box[5] - box[2]) * 0.5;
 
     const kept = {
-        position: [...camera.transform.position],
+        position: [...camera.transform.translation],
         near: camera.near,
         far: camera.far,
     };
@@ -101,7 +101,7 @@ export async function sweep_views({
                 largest: result.largest_components[0] ?? 0,
                 median: result.median_component,
                 converging: result.still_converging,
-                position: [...camera.transform.position].map(v => +v.toFixed(3)),
+                position: [...camera.transform.translation].map(v => +v.toFixed(3)),
             });
         }
     }

package/src/shade/playground/skinned_blas_refit/verify_traversal_reachability.js

@@ -141,7 +141,7 @@ export async function verify_traversal_reachability({
 
     const origin = inverse_transform_point(
         mesh.transform_global.matrix,
-        [...camera.transform.position]
+        [...camera.transform.translation]
     );
 
     const t_bytes = leaf_count * Float32Array.BYTES_PER_ELEMENT;

package/src/shade/playground/ssr_motion/README.md

@@ -0,0 +1,22 @@
+# SSR cross camera playground
+
+Open `/src/shade/playground/ssr_motion/` on the engine's Vite development server.
+It shares the exact scene, camera lens, resolution and fixed exposure of
+`ssr_variance`: one metallic floor and an emissive cross card with two colored
+markers. Final-image TAA and raster jitter default off independently.
+
+Drag to orbit, right-drag to pan, wheel to zoom, or focus the canvas and use WASD.
+Floor roughness changes live from 0.01 to 1.00. Material changes clear history;
+ordinary camera movement does not. The lateral path uses the same motion-speed
+scale as `ssr_reprojection` (x = 2 sin(phase), phase rate = 0.7 × speed).
+Choose speed 2.0 to reproduce the faster lateral movement.
+
+Pause motion continues sampling at the current pose. Pause rendering freezes the
+image. Step frame submits one 1/60-second frame. SSR parallax, surface-only and
+no-history modes, spatial denoising, final TAA and jitter can be compared separately.
+
+Query controls: `?motion=lateral&speed=2&roughness=0.3`, `taa=on`, `jitter=on`,
+`spatial=off`, and `temporal=0|1|2`. `manual` starts at frame zero with rendering
+paused. `await ssr_motion_ready` exposes the renderer, camera, scene, `pose`,
+`frame`, and `step(n, advance=true)` for controlled experiments. `advance=false`
+keeps the current pose while sampling. Exact stepping requires rendering paused.

package/src/shade/playground/ssr_motion/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>SSR cross · camera motion</title><style>
+body{margin:24px;background:#14161a;color:#e7e9ee;font:14px/1.5 system-ui}h1{font-size:24px;margin-bottom:8px}p{color:#acb5c5;max-width:900px}main{display:grid;grid-template-columns:minmax(0,800px) 260px;gap:24px}canvas{display:block;width:100%;height:auto;background:#08090a;touch-action:none;outline:none}canvas:focus{outline:1px solid #749ac4}label{display:block;margin:0 0 14px}input[type=range],select{width:100%}button,select{font:inherit;padding:8px;background:#29313e;color:inherit;border:1px solid #4b586d;border-radius:4px}button{margin:0 4px 8px 0}output{float:right;font-variant-numeric:tabular-nums}a{color:#9ac9ff}#status{white-space:pre-wrap}.error{color:#ff9a9a}@media(max-width:900px){main{grid-template-columns:1fr}}
+</style></head><body tabindex="0">
+<h1>SSR cross · camera motion</h1>
+<p>The same glowing cross and colored markers as the variance lab. Fixed exposure; final-image TAA defaults off. Drag to orbit, right-drag to pan, scroll to zoom, or focus the scene and use WASD.</p>
+<main><section><canvas id="view" width="800" height="500" tabindex="0" aria-label="Interactive reflection scene"></canvas><p id="status" role="status">Initializing…</p><p><a href="../ssr_variance/">Exact variance and convergence measurements</a></p></section><aside>
+<label>Floor roughness <output id="roughness-value">0.30</output><input id="roughness" aria-label="Floor roughness" type="range" min="0.01" max="1" step="0.01" value="0.3"></label>
+<label>Camera <select id="motion"><option value="free">Free camera</option><option value="lateral">Lateral movement</option><option value="forward">Forward movement</option><option value="orbit">Orbit movement</option><option value="still">Still camera</option></select></label>
+<label>Motion speed <output id="speed-value">1.0×</output><input id="speed" aria-label="Motion speed" type="range" min="0.1" max="3" step="0.1" value="1"></label>
+<label>SSR history <select id="temporal"><option value="0">Parallax</option><option value="1">Surface only</option><option value="2">No temporal history</option></select></label>
+<label><input id="spatial" type="checkbox" checked> Spatial denoising</label>
+<label><input id="taa" type="checkbox"> Final-image TAA</label>
+<label><input id="jitter" type="checkbox"> Raster jitter</label>
+<button id="motion-pause">Pause motion</button><button id="render-pause">Pause rendering</button><button id="step">Step frame</button><button id="restart">Reset camera</button><button id="reset">Reset SSR history</button>
+<p>Pausing motion keeps sampling. Pausing rendering freezes the displayed frame. Ordinary camera movement preserves history; resets and material changes clear it.</p>
+</aside></main><script type="module" src="./main.js"></script></body></html>

package/src/shade/playground/ssr_motion/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/ssr_motion/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_motion/main.js"],"names":[],"mappings":""}

package/src/shade/playground/ssr_motion/main.js

@@ -0,0 +1,149 @@
+import Vector3 from "../../../core/geom/Vector3.js";
+import { PerspectiveCamera } from "../../renderer/camera/PerspectiveCamera.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { Renderer } from "../../renderer/Renderer.js";
+import { ShadeIndirectLightingMode } from "../../renderer/ShadeIndirectLightingMode.js";
+import { FixedProjection } from "../ssr_variance/capture.js";
+import { create_scene } from "../ssr_variance/scene.js";
+
+const element = id => document.getElementById(id);
+const params = new URLSearchParams(location.search);
+const number = (name, fallback, min, max) => {
+    const value = Number(params.get(name) ?? fallback);
+    return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+};
+element('roughness').value = number('roughness', 0.3, 0.01, 1);
+element('speed').value = number('speed', 1, 0.1, 3);
+if (['free', 'lateral', 'forward', 'orbit', 'still'].includes(params.get('motion'))) { element('motion').value = params.get('motion'); }
+if (['0', '1', '2'].includes(params.get('temporal'))) { element('temporal').value = params.get('temporal'); }
+element('spatial').checked = params.get('spatial') !== 'off';
+for (const name of ['taa', 'jitter']) { element(name).checked = params.get(name) === 'on'; }
+
+async function start() {
+    const canvas = element('view'), renderer = new Renderer();
+    await renderer.initialize({ context: canvas.getContext('webgpu'), pixelRatio: 1 });
+    renderer.feature_ssr_enabled = true;
+    renderer.indirect_lighting_mode = ShadeIndirectLightingMode.IBL;
+    for (const name of ['ssao', 'bloom', 'sharpening', 'motion_blur', 'automatic_exposure']) { renderer[`feature_${name}_enabled`] = false; }
+    renderer.exposure_compensation = 1;
+    renderer.internal_resolution_scale = 1;
+    renderer.feature_taa_enabled = element('taa').checked;
+    renderer.ssr.spatial_denoising_enabled = element('spatial').checked;
+    renderer.ssr.reprojection_mode = Number(element('temporal').value);
+    const world = await create_scene();
+    world.ground_material.roughness_factor = Number(element('roughness').value);
+    const floor_materials = new Map([[world.ground_material.roughness_factor, world.ground_material]]);
+    const camera = new PerspectiveCamera();
+    camera.near = 0.1; camera.far = 50; camera.fov = 50 * Math.PI / 180;
+    camera.aspect = canvas.width / canvas.height;
+    const controller = new OrbitalCameraController(camera, canvas);
+    controller.movement_speed_scale = 2;
+    renderer.resize(canvas.width, canvas.height);
+    class ProjectionControl extends FixedProjection {
+        record(frame) { if (!element('jitter').checked) { super.record(frame); } }
+    }
+    renderer.add_extension(new ProjectionControl());
+    let phase = 0, frame_count = 0, motion_paused = false;
+    let rendering_paused = params.has('manual'), stopped = false, request, last_time, last_status = 0;
+    const pose = (position, target) => {
+        camera.transform.setTranslation(...position);
+        camera.transform.lookAt(new Vector3(...target));
+        camera.transform.updateMatrix();
+        controller.look(new Vector3(...position), new Vector3(...target));
+    };
+    function status() {
+        element('status').textContent = `Frame ${frame_count} · roughness ${world.ground_material.roughness_factor.toFixed(2)}\n${rendering_paused ? 'Rendering paused' : motion_paused ? 'Motion paused · sampling continues' : 'Running'} · final TAA ${renderer.feature_taa_enabled ? 'on' : 'off'}`;
+        element('render-pause').textContent = rendering_paused ? 'Resume rendering' : 'Pause rendering';
+    }
+    function fail(error) {
+        stopped = true; cancelAnimationFrame(request);
+        element('status').textContent = error.message ?? String(error);
+        element('status').classList.add('error'); console.error(error);
+    }
+    function reset_camera() {
+        phase = 0; pose([0, 3.2, 7], [0, 0.2, -2]);
+        renderer.indicate_view_change(); status();
+    }
+    function set_roughness() {
+        const roughness = Number(element('roughness').value);
+        // GPU material contexts are immutable after upload. Reuse at most one
+        // material per slider value, and refresh the scene's material membership.
+        let material = floor_materials.get(roughness);
+        if (!material) {
+            material = world.ground_material.clone();
+            material.roughness_factor = roughness;
+            floor_materials.set(roughness, material);
+        }
+        if (material !== world.ground_material) {
+            world.scene.remove(world.ground);
+            world.ground.material = world.ground_material = material;
+            world.ground.updateMatrices();
+            renderer.graphics.materials.obtain(material);
+            world.scene.add(world.ground);
+        }
+        element('roughness-value').textContent = world.ground_material.roughness_factor.toFixed(2);
+        renderer.indicate_view_change(); status();
+    }
+    function frame(dt = 1 / 60, advance = true) {
+        if (stopped) { throw new Error('Renderer stopped after an error'); }
+        const mode = element('motion').value;
+        if (advance && !motion_paused) {
+            phase += dt * Number(element('speed').value) * 0.7;
+            const t = Math.sin(phase);
+            if (mode === 'free') { controller.update(dt); }
+            else if (mode === 'lateral') { pose([2 * t, 3.2, 7], [2 * t, 0.2, -2]); }
+            else if (mode === 'forward') { pose([0, 3.2, 7 + 1.6 * t], [0, 0.2, -2 + 1.6 * t]); }
+            else if (mode === 'orbit') { pose([4 * t, 3.2, 7 - 0.7 * t * t], [0, 0.2, -2]); }
+        }
+        if (renderer.render(camera, world.scene, dt) === false) { throw new Error('Renderer did not submit the frame'); }
+        frame_count++;
+        if (performance.now() - last_status > 250 || rendering_paused) { status(); last_status = performance.now(); }
+        return frame_count;
+    }
+    function tick(time) {
+        if (stopped) { return; }
+        const dt = last_time === undefined ? 1 / 60 : Math.min((time - last_time) / 1000, 0.05);
+        last_time = time;
+        try { if (!rendering_paused) { frame(dt); } }
+        catch (error) { fail(error); return; }
+        request = requestAnimationFrame(tick);
+    }
+    element('roughness').oninput = set_roughness;
+    element('speed').oninput = () => { element('speed-value').textContent = `${Number(element('speed').value).toFixed(1)}×`; };
+    element('speed').oninput();
+    element('motion').onchange = () => {
+        if (element('motion').value !== 'free') { reset_camera(); }
+    };
+    canvas.addEventListener('pointerdown', () => { canvas.focus(); element('motion').value = 'free'; motion_paused = false; element('motion-pause').textContent = 'Pause motion'; });
+    canvas.addEventListener('contextmenu', event => event.preventDefault());
+    element('temporal').onchange = () => { renderer.ssr.reprojection_mode = Number(element('temporal').value); };
+    element('spatial').onchange = () => { renderer.ssr.spatial_denoising_enabled = element('spatial').checked; };
+    element('taa').onchange = () => { renderer.feature_taa_enabled = element('taa').checked; renderer.indicate_view_change(); status(); };
+    element('jitter').onchange = () => renderer.indicate_view_change();
+    element('motion-pause').onclick = () => { motion_paused = !motion_paused; element('motion-pause').textContent = motion_paused ? 'Resume motion' : 'Pause motion'; status(); };
+    element('render-pause').onclick = () => { rendering_paused = !rendering_paused; status(); };
+    element('step').onclick = () => { rendering_paused = true; try { frame(); } catch (error) { fail(error); } };
+    element('restart').onclick = reset_camera;
+    element('reset').onclick = () => { renderer.ssr.reset_history = true; };
+    const device = renderer.graphics.device;
+    device.addEventListener('uncapturederror', event => fail(event.error));
+    device.lost.then(info => { if (!stopped) { fail(new Error(`GPU device lost: ${info.message}`)); } });
+    addEventListener('pagehide', () => { stopped = true; cancelAnimationFrame(request); controller.pointer.stop(); controller.keyboard.stop(); renderer.destroy(); device.destroy(); });
+    addEventListener('pageshow', event => { if (event.persisted) { location.reload(); } });
+    reset_camera(); set_roughness();
+    const lab = globalThis.ssr_motion_lab = {
+        renderer, camera, world, frame, pose,
+        step(n = 1, advance = true) {
+            if (!rendering_paused) { throw new Error('Pause rendering before exact stepping'); }
+            if (!Number.isSafeInteger(n) || n < 1) { throw new Error('Step count must be a positive integer'); }
+            for (let i = 0; i < n; i++) { frame(1 / 60, advance); }
+            return frame_count;
+        },
+        get frame_count() { return frame_count; },
+    };
+    request = requestAnimationFrame(tick);
+    return lab;
+}
+globalThis.ssr_motion_ready = start().catch(error => {
+    element('status').textContent = error.message ?? String(error); console.error(error); throw error;
+});

package/src/shade/playground/ssr_variance/index.html

@@ -5,6 +5,7 @@ body{margin:24px;background:#14161a;color:#e7e9ee;font:14px system-ui}h1{font-si
 </style></head><body>
 <h1>SSR variance lab</h1>
 <p>One ground plane · roughness 0.30 · metallic 1 · textured emissive card · fixed camera and exposure. Starts at frame zero. Rendering advances only when requested.</p>
+<p><a href="../ssr_motion/">Move the camera and adjust floor roughness</a></p>
 <label>Spatial <select id="spatial"><option value="on">On</option><option value="off">Off</option></select></label>
 <label>Temporal <select id="temporal"><option value="on">On</option><option value="off">Off</option></select></label>
 <label>Raster jitter <select id="jitter"><option value="off">Off</option><option value="on">On</option></select></label>

package/src/shade/playground/vgeo_viewer/README.md

@@ -0,0 +1,123 @@
+# `.vgeo` viewer
+
+An interactive viewer for the virtual-geometry container. Run the dev server and open it:
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+<http://localhost:5173/src/shade/playground/vgeo_viewer/index.html>
+
+Nothing loads by itself. **Drop a `.vgeo` anywhere on the page**, pass `?file=/data/models/…​.vgeo`
+to open one by URL — which is what makes a particular view of a particular asset a bookmark — or
+press **build a sample asset**, which runs the builder in the page over a torus and opens the
+container it produces. `?sample` does the last one on load.
+
+## What is on screen
+
+Not the asset — the **cut**: the clusters the container's own metric selects for where the camera is
+standing, coloured so the seams between them are visible, with the cluster count on screen.
+
+**The cut is frozen until you ask for a new one.** *Adapt to view* re-runs the traversal at wherever
+the camera is now; everything after that is you flying around a decision taken from somewhere else,
+which is the only way to see what a cut actually selected. *Follow the camera* makes it chase
+instead. *tau* is the one quality dial — pixels of permitted error.
+
+Drawing goes through Shade's direct geometry path (a `DynamicMesh` from raw attributes, no meshlet
+encode) because a cut is rebuilt from scratch on every adapt, and it is drawn opaque so the depth
+buffer orders its own triangles.
+
+## What makes it a streaming viewer
+
+The reader under it never holds the whole file. Opening a container reads the header, the level
+table and the root frame — `VGEO_FORMAT.md` §10's always-resident set, two range requests — and
+after that a page arrives only because a traversal asked for it, from exactly the byte range the
+page pointing at it wrote down.
+
+So a cut can be taken before the file has finished arriving, and this is the interesting part: it is
+**clamped, not wrong**. Where the page holding a refinement is missing, the coarser cluster is drawn
+and a *want* is recorded, and the surface is watertight either way. Three controls turn that into
+something you can watch:
+
+| control | what it shows |
+|---|---|
+| **colour by clamp** | amber where the surface is standing in for a page that has not arrived, slate where the cut is the one the file selects |
+| **stream *n* wanted page(s)** | installs eight of them, retakes the cut, repeats — refinement happening in steps rather than in one jump |
+| **evict everything but the root** | back to cold, so it arrives again |
+
+The **streaming** panel is the measurement: `read so far` against the file's own size, the request
+count, what the cold start cost, and how many pages are resident. On anything larger than a toy the
+first of those is a small fraction, and that is the whole claim.
+
+**head prefix** re-opens the current file from cold under a different one. §10 offers a reader two
+cold starts — the 256-byte header and then one exact range per wanted page, or one speculative
+prefix that brings the head and whatever else it happens to cover — and this is the dial between
+them. Coarse-first layout is what makes the second worth doing: a prefix that overshoots the root
+frame has overshot into the pages the traversal is about to want. Watch `read so far` and `requests`
+move against each other. `?head=<bytes>` sets it on load.
+
+`read so far` is cumulative and is allowed past 100%: evicting and re-streaming really does fetch
+those pages again, and the audit really does read every byte.
+
+## Validation is optional and off
+
+**Validation is off by default and is not a precondition for anything.** It reads the whole file —
+every frame, every checksum, the directory against a full frame scan — which is exactly what an
+incremental reader exists to avoid, and it answers a question about whoever *wrote* the file rather
+than about the view being put on screen. Press **validate the whole file** when that is the
+question, or pass `?validate`.
+
+What is *not* optional, because it is the difference between refusing a file and misreading one:
+magic, minimum reader version, payload encoding, hash algorithm, unknown required feature bits,
+unknown codecs, a `decoded_size` outside what the stored bytes could physically produce, and a root
+frame that disagrees with the header about its own size. Those are §4 and §10 reject rules and they
+always run.
+
+**verify each frame's checksum** sits between the two. A frame's identity-seeded checksum covers
+only that frame, so it is verified from bytes just fetched, with no extra request and no whole-file
+pass — §10 requires it of a runtime, where a quarantined page is the difference between a coarse
+stand-in and a wrong surface. Off here for the same reason the audit is: hashing every installed
+byte costs something, and a tool looking at a file it just built is not defending against a network.
+It is read per fetch, so ticking it applies to the next page rather than to a reopen. `?verify` sets
+it on load.
+
+## What lives where
+
+The reader is **not** part of this page. It is `renderer/geometry/virtual/format/read/`, it is the
+shape a runtime would use, and it knows nothing about drawing:
+
+| | |
+|---|---|
+| `VGeoByteSource` | a range at a time, over an `ArrayBuffer` or a dropped `Blob` |
+| `vgeo_fetch_byte_source` | the same over HTTP, refusing a `200` where it asked for a range |
+| `vgeo_read_header` | header and level table, with §4's reject rules |
+| `vgeo_read_page` | one fetched frame → one `VGeoPage`; needs nothing else |
+| `VGeoPage` | a page's own bytes and its own cluster/group/child tables |
+| `VGeoContainerReader` | residency: open, install, evict, and the optional audit |
+| `VGeoDirectory` | the auxiliary page directory, for reaching pages no traversal leads to |
+
+What belongs to the page is everything above the bytes:
+
+| | |
+|---|---|
+| `select_cut.js` | the traversal, the residency clamp, and the wants it records |
+| `cut_geometry.js` | decoding selected clusters into one drawable geometry, and the colour modes |
+| `sample_asset.js` | a container built in the page, so there is something to open |
+| `main.js` | renderer, camera, panel, and the streaming loop |
+
+## Driving it from a script
+
+Everything is reachable from the console, which is what makes the page verifiable in a headless
+browser rather than by a person watching it:
+
+```js
+await __open_sample();       // or __open_url('/data/…​.vgeo')
+__vgeo.set_auto_stream(false);
+__vgeo.reset_residency();    // back to the root page alone
+__state();                   // { resident_pages, bytes_read, clusters, clamped, wants, … }
+await __stream();            // one round of eight pages, then a fresh cut
+await __validate();          // the whole-file audit, as an array of defect strings
+```
+
+`__state()` is the one to assert on: `clamped` reaching zero is the cut having converged on what the
+container selects, and it converges to the same numbers whatever order the pages arrived in.