@woosh/meep-engine 3.20.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_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.map

@@ -1 +1 @@
-{"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;;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;+BAvL8B,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_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/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.

package/src/shade/playground/vgeo_viewer/cut_geometry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Decode the selected clusters into one geometry.
+ *
+ * @param {VGeoCut} cut
+ * @param {VGEO_COLOR_MODE} color_mode
+ * @returns {VGeoCutGeometry}
+ */
+export function vgeo_build_cut_geometry(cut: VGeoCut, color_mode: VGEO_COLOR_MODE): VGeoCutGeometry;
+/**
+ * What a cluster's colour is keyed on.
+ *
+ * The two normal modes are not keyed on the cluster at all: they paint every vertex with its own
+ * direction, and the cluster boundaries go with it. `stored normal` is the container's own
+ * {@link VGEO_ATTRIBUTE.NORMAL }, decoded out of the payload — the only mode that shows an attribute
+ * the file carries rather than something derived from it. `geometric normal` is the area-weighted
+ * normal of the decoded triangles, which is what every other mode shades with. The pair is the
+ * point: they agree where the builder's normals still describe the geometry it shipped, and a source
+ * with no normals at all makes the first one flat.
+ *
+ * `clamp` is the streaming one: it paints the clusters a coarser page is standing in for, so the
+ * regions still waiting on bytes are visible as regions rather than as a number in a panel.
+ */
+export type VGEO_COLOR_MODE = string;
+export namespace VGEO_COLOR_MODE {
+    let Cluster: string;
+    let Group: string;
+    let Page: string;
+    let Level: string;
+    let Error: string;
+    let Clamp: string;
+    let StoredNormal: string;
+    let GeometricNormal: string;
+}
+/**
+ * A cut, decoded into one geometry.
+ *
+ * Nothing about it depends on where the camera is: the mesh is drawn solid and the depth buffer
+ * orders it, so the triangle list is uploaded once when the cut is taken and never touched again.
+ */
+export class VGeoCutGeometry {
+    /**
+     * Position and colour, indexed by {@link triangles}.
+     * @type {Geometry}
+     */
+    geometry: Geometry;
+    /**
+     * `3 · triangle_count` — the full triangle list, in cluster order, and the geometry's index.
+     * @type {Uint32Array}
+     */
+    triangles: Uint32Array;
+    /**
+     * @type {number}
+     */
+    triangle_count: number;
+    /**
+     * @type {number}
+     */
+    vertex_count: number;
+}
+import { Geometry } from "../../renderer/geometry/Geometry.js";
+//# sourceMappingURL=cut_geometry.d.ts.map

package/src/shade/playground/vgeo_viewer/cut_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cut_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_viewer/cut_geometry.js"],"names":[],"mappings":"AA0QA;;;;;;GAMG;AACH,kEAHW,eAAe,GACb,eAAe,CAsM3B;;;;;;;;;;;;;;;8BA3ZS,MAAM;;;;;;;;;;;AAkLhB;;;;;GAKG;AACH;IACI;;;OAGG;IACH,UAFU,QAAQ,CAEQ;IAE1B;;;OAGG;IACH,WAFU,WAAW,CAEU;IAE/B;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;CACpB;yBAlQwB,qCAAqC"}