@woosh/meep-engine 3.21.0 → 3.23.0

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

@@ -56,26 +56,6 @@ export function configure_particles(renderer: import("../../renderer/Renderer.js
  * @param {number} time seconds since start
  */
 export function animate_particle_scene(emitters: ReturnType<typeof create_particle_emitters>, time: number): void;
-/**
- * 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
- */
-export function encode_stats_copy(system: import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem, encoder: GPUCommandEncoder, destination: GPUBuffer): void;
-/**
- * Interpret the bytes {@link encode_stats_copy} wrote.
- *
- * @param {ArrayBuffer} bytes
- * @returns {ParticleSceneStats}
- */
-export function read_stats(bytes: ArrayBuffer): ParticleSceneStats;
 /**
  * A 64x64 radial-falloff sprite (white, alpha falloff) for soft additive and alpha blobs.
  *
@@ -108,19 +88,6 @@ export function make_sprite_texture(device: GPUDevice): GPUTexture;
  *   node that orbits, so a moving emitter is on screen,
  * - a sunlight and (from the page) the default environment, because the meshes are lit.
  */
-/** Bytes {@link encode_stats_copy} writes: 8 counters, then both indirect arg buffers. */
-export const PARTICLE_STATS_BYTES: 64;
-/**
- * @typedef {object} ParticleSceneStats
- * @property {number} alive particles alive at the end of the captured frame
- * @property {number} dead free slots left in the pool
- * @property {number} spawn_budget free slots the frame's emitters left unclaimed
- * @property {number} alive_in the snapshot next frame's simulate reads as its input length — the
- *   PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
- * @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
- */
 /**
  * What each of the four parametric emitters emits, apart from the fire, whose effect is the worked
  * example next door. Exported so the page can show what each emitter is doing.
@@ -138,34 +105,6 @@ export const PARTICLE_EMITTER_MOTION: {
         color: number[];
     };
 };
-export type ParticleSceneStats = {
-    /**
-     * particles alive at the end of the captured frame
-     */
-    alive: number;
-    /**
-     * free slots left in the pool
-     */
-    dead: number;
-    /**
-     * free slots the frame's emitters left unclaimed
-     */
-    spawn_budget: number;
-    /**
-     * the snapshot next frame's simulate reads as its input length — the
-     * PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
-     */
-    alive_in: number;
-    /**
-     * 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
-     */
-    sim_padded: number;
-    /**
-     * simulate's indirect dispatch args, `[x, y, z]` workgroups
-     */
-    dispatch: number[];
-};
 import { ParticleEmitter } from "../../renderer/particles/runtime/ParticleEmitter.js";
 import { Node3D } from "../../renderer/scene/Node3D.js";
 import { Scene } from "../../renderer/scene/Scene.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":"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"}
+{"version":3,"file":"particle_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_system/particle_scene.js"],"names":[],"mappings":"AAoEA;;;;;;;;;;;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;;;;;GAKG;AACH,mEA4BC;AAnQD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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;gCA5C8B,qDAAqD;uBAE9D,gCAAgC;sBACjC,+BAA+B;qBAFhC,8BAA8B"}

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

@@ -11,7 +11,6 @@ import { make_sunlight } from "../../renderer/light/make_sunlight.js";
 import { ShadeDrawSide } from "../../renderer/material/ShadeDrawSide.js";
 import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
 import { TransparencyMode } from "../../renderer/material/TransparencyMode.js";
-import { PARTICLE_COUNTER_COUNT } from "../../renderer/particles/data/PARTICLE_COUNTERS.js";
 import { EMITTER_BLEND, EMITTER_PROJECTION } from "../../renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
 import { particle_node, particle_wire } from "../../renderer/particles/graph/particle_graph_authoring.js";
 import {
@@ -54,23 +53,6 @@ import { fire_effect } from "./particle_prototype.js";
  * - a sunlight and (from the page) the default environment, because the meshes are lit.
  */
 
-/** Bytes {@link encode_stats_copy} writes: 8 counters, then both indirect arg buffers. */
-export const PARTICLE_STATS_BYTES = 64;
-
-const STATS_OFFSET_DISPATCH_ARGS = 32;
-
-/**
- * @typedef {object} ParticleSceneStats
- * @property {number} alive particles alive at the end of the captured frame
- * @property {number} dead free slots left in the pool
- * @property {number} spawn_budget free slots the frame's emitters left unclaimed
- * @property {number} alive_in the snapshot next frame's simulate reads as its input length — the
- *   PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
- * @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
- */
-
 /**
  * What each of the four parametric emitters emits, apart from the fire, whose effect is the worked
  * example next door. Exported so the page can show what each emitter is doing.
@@ -270,45 +252,6 @@ export function animate_particle_scene(emitters, time) {
     orbit.updateMatrices();
 }
 
-/**
- * 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
- */
-export function encode_stats_copy(system, encoder, destination) {
-    const buffers = system.buffers;
-
-    encoder.copyBufferToBuffer(buffers.counters, 0, destination, 0, PARTICLE_COUNTER_COUNT * 4);
-    encoder.copyBufferToBuffer(buffers.dispatch_args, 0, destination, STATS_OFFSET_DISPATCH_ARGS, 3 * 4);
-}
-
-/**
- * Interpret the bytes {@link encode_stats_copy} wrote.
- *
- * @param {ArrayBuffer} bytes
- * @returns {ParticleSceneStats}
- */
-export function read_stats(bytes) {
-    const words = new Uint32Array(bytes);
-    const dispatch_base = STATS_OFFSET_DISPATCH_ARGS / 4;
-
-    return {
-        alive: words[0],
-        dead: words[1],
-        spawn_budget: words[2],
-        alive_in: words[4],
-        sim_padded: words[5],
-        dispatch: [words[dispatch_base], words[dispatch_base + 1], words[dispatch_base + 2]],
-    };
-}
-
 /**
  * A 64x64 radial-falloff sprite (white, alpha falloff) for soft additive and alpha blobs.
  *

package/src/shade/playground/ssr_variance/reference.d.ts

@@ -12,7 +12,7 @@ export class ReflectionReference extends RenderExtension {
     textures: any[];
     device: any;
     record(frame: any): void;
-    read(): Promise<TypedArray>;
+    read(): Promise<import("../../../core/primitives/TypedArray.js").TypedArray>;
 }
 import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
 //# sourceMappingURL=reference.d.ts.map

package/src/shade/playground/ssr_variance/reference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_variance/reference.js"],"names":[],"mappings":"AA8DA;;;;;EAeC;AAjDD,yFAAyF;AACzF;IAKI,yBAAsD;IAHtD,iBAAgB;IAChB,cAAU;IACV,gBAAc;IACiB,YAAoB;IACnD,yBAmBC;IACD,4BAIC;CACJ;gCA5D+B,6CAA6C"}
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_variance/reference.js"],"names":[],"mappings":"AA8DA;;;;;EAeC;AAjDD,yFAAyF;AACzF;IAKI,yBAAsD;IAHtD,iBAAgB;IAChB,cAAU;IACV,gBAAc;IACiB,YAAoB;IACnD,yBAmBC;IACD,6EAIC;CACJ;gCA5D+B,6CAA6C"}

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

@@ -36,8 +36,17 @@ 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:
+and a *want* is recorded, and the surface is watertight either way.
+
+"Missing" there means §10's *selectable*, not merely resident: a group is refined into only once
+every page holding one of its parents is here. A group's parents are made by one simplification step
+but grouped for the next one separately, so an asset of more than a page per band puts some of them
+in different pages — and refining into a group because its own page arrived, while a coarse cluster
+still stands in for a parent that has not, draws both over the same surface. Those clamps carry no
+want, because there is nothing to fetch from a cluster that already has the bytes it points at; the
+panel counts them under *of those, on a parent*.
+
+Three controls turn that into something you can watch:
 
 | control | what it shows |
 |---|---|
@@ -56,6 +65,18 @@ them. Coarse-first layout is what makes the second worth doing: a prefix that ov
 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.
 
+**head prefix** on the streaming panel is what is still *held*, and it says `released` for most of a
+session: the reader drops the prefix the first time a read falls outside it, because after the pages
+inside it have installed it is bytes nothing will read — and at a thousand open assets a retained
+256 KiB apiece was a quarter of a gigabyte that neither `resident` nor eviction could see. The
+always-resident set is about 2.4 KB, so the prefix is speculation about the next band and 64 KiB is
+enough of it; the dial is there to watch the trade rather than to tune it.
+
+**quarantined** is the other new row, and it is the difference between an asset that is coarse
+because the camera just moved and one that is coarse because a page will never arrive — which look
+identical on screen. A page that fails its retries is quarantined with its reason and is not asked
+for again; the clamped cut keeps its surface correct with a coarser ancestor, indefinitely.
+
 `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.
 
@@ -67,6 +88,12 @@ incremental reader exists to avoid, and it answers a question about whoever *wro
 than about the view being put on screen. Press **validate the whole file** when that is the
 question, or pass `?validate`.
 
+It is not a method on the reader, either. `vgeo_audit_container` and `vgeo_install_all_pages` live in
+`format/read/tool/`, and this viewer calls them as the tool it is — a renderer holding a thousand
+containers must not have either within reach of one of them. The audit takes the file as a single
+`ArrayBuffer`, because every build invariant is a cross-check between two places in it, so it refuses
+above 1 GiB naming the size rather than failing in the allocator.
+
 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

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

@@ -1 +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"}
+{"version":3,"file":"cut_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_viewer/cut_geometry.js"],"names":[],"mappings":"AAqOA;;;;;;GAMG;AACH,kEAHW,eAAe,GACb,eAAe,CAsM3B;;;;;;;;;;;;;;;8BArXS,MAAM;;;;;;;;;;;AA4IhB;;;;;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;yBA5NwB,qCAAqC"}

package/src/shade/playground/vgeo_viewer/cut_geometry.js

@@ -1,5 +1,6 @@
 import { assert } from "../../../core/assert.js";
 import { UINT16_MAX } from "../../../core/binary/UINT16_MAX.js";
+import { hsv_to_rgb } from "../../../core/color/hsv/hsv_to_rgb.js";
 import {
     decode_octahedron_to_unit
 } from "../../../core/geom/3d/normal/octahedron/decode_octahedron_to_unit.js";
@@ -123,44 +124,6 @@ const stored_normals = new Float32Array(256 * 3);
  */
 const scratch_direction = new Float32Array(3);
 
-/**
- * @param {number} hue in `[0, 1)`
- * @param {number} saturation
- * @param {number} value
- * @param {Float32Array} out
- * @param {number} offset
- */
-function hsv_to_rgb(hue, saturation, value, out, offset) {
-    const sector = hue * 6;
-    const i = Math.floor(sector);
-    const f = sector - i;
-
-    const p = value * (1 - saturation);
-    const q = value * (1 - saturation * f);
-    const t = value * (1 - saturation * (1 - f));
-
-    switch (i % 6) {
-        case 0:
-            out[offset] = value; out[offset + 1] = t; out[offset + 2] = p;
-            break;
-        case 1:
-            out[offset] = q; out[offset + 1] = value; out[offset + 2] = p;
-            break;
-        case 2:
-            out[offset] = p; out[offset + 1] = value; out[offset + 2] = t;
-            break;
-        case 3:
-            out[offset] = p; out[offset + 1] = q; out[offset + 2] = value;
-            break;
-        case 4:
-            out[offset] = t; out[offset + 1] = p; out[offset + 2] = value;
-            break;
-        default:
-            out[offset] = value; out[offset + 1] = p; out[offset + 2] = q;
-            break;
-    }
-}
-
 /**
  * Decode one cluster's stored normal section into unit vectors.
  *
@@ -420,7 +383,7 @@ export function vgeo_build_cut_geometry(cut, color_mode) {
             // cool where the cut is refined, hot where it settled for the most error
             const t = error_span > 0 ? (page.self_error[id] - error_low) / error_span : 0;
 
-            hsv_to_rgb(0.68 * (1 - t), 0.9, 1, tint, 0);
+            hsv_to_rgb(tint, 0, 0.68 * (1 - t), 0.9, 1);
         } else if (color_mode === VGEO_COLOR_MODE.Clamp) {
             /*
              Two colours and nothing in between. Amber is a cluster standing in for a page that has
@@ -433,7 +396,7 @@ export function vgeo_build_cut_geometry(cut, color_mode) {
             tint[1] = waiting ? 0.66 : 0.52;
             tint[2] = waiting ? 0.16 : 0.62;
         } else {
-            hsv_to_rgb((color_key(page, id, color_mode) * HUE_STEP) % 1, 0.85, 1, tint, 0);
+            hsv_to_rgb(tint, 0, (color_key(page, id, color_mode) * HUE_STEP) % 1, 0.85, 1);
         }
 
         const end = first + vertices;

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

@@ -25,6 +25,12 @@ import {
 import {
     VGeoReadOptions
 } from "../../renderer/geometry/virtual/format/read/VGeoReadOptions.js";
+import {
+    vgeo_audit_container
+} from "../../renderer/geometry/virtual/format/read/tool/vgeo_audit_container.js";
+import {
+    vgeo_install_all_pages
+} from "../../renderer/geometry/virtual/format/read/tool/vgeo_install_all_pages.js";
 import { make_sunlight } from "../../renderer/light/make_sunlight.js";
 import { Renderer } from "../../renderer/Renderer.js";
 import { DynamicMesh } from "../../renderer/scene/DynamicMesh.js";
@@ -93,8 +99,8 @@ const STREAM_BATCH = 8;
 const HEAD_PREFIXES = [
     ['256 B — header only', 256],
     ['16 KB', 16 * 1024],
-    ['64 KB', 64 * 1024],
-    ['256 KB — the default', 256 * 1024],
+    ['64 KB — the default', 64 * 1024],
+    ['256 KB', 256 * 1024],
     ['1 MB', 1024 * 1024],
 ];
 
@@ -145,35 +151,76 @@ function escape_html(text) {
 }
 
 /**
- * What the resident pages cost stored against what they cost decoded, and under which codec.
+ * What a reader's quarantine amounts to, for the panel.
  *
- * Stored is the number that gets fetched and the number that sits on disk; decoded is the number a
- * resident page costs in RAM. The codec is per frame, so a file can genuinely be a mixture — the
- * encoder stores a page raw whenever compressing it would not have shrunk it — and naming all of
- * them is more honest than naming whichever one happened to come first.
+ * A page that has failed its retries is not an error the viewer can act on — the clamped cut keeps
+ * that surface correct with a coarser ancestor — but it is the difference between an asset that is
+ * coarse because the camera just moved and one that is coarse because a page will never arrive, and
+ * those look identical on screen. So the count goes on the panel, with the first reason.
  *
- * @param {VGeoPage[]} pages
+ * @param {VGeoContainerReader} reader
  * @returns {string}
  */
-function page_storage(pages) {
-    if (pages.length === 0) {
-        return '—';
+function quarantine_summary(reader) {
+    const count = reader.quarantined_page_count;
+
+    if (count === 0) {
+        return 'none';
     }
 
+    const [page, reason] = reader.quarantine().next().value;
+
+    return `${thousands(count)} page(s) · page ${page}: ${escape_html(reason)}`;
+}
+
+/**
+ * Everything the panel says about the resident set, in one pass over it.
+ *
+ * One pass, and over `resident_pages()` rather than `pages`, because the panel refreshes on every
+ * streaming round and `VGeoContainerReader.pages` is a snapshot that allocates an array and sorts
+ * it — 0.29 ms at 20,000 resident pages, and this used to ask for two of them.
+ *
+ * Storage: stored is what gets fetched and what sits on disk, decoded is what a resident page costs
+ * in RAM. The codec is per frame, so a file can genuinely be a mixture — the encoder stores a page
+ * raw whenever compressing it would not have shrunk it — and naming all of them is more honest than
+ * naming whichever one came first.
+ *
+ * Normals: worth saying outright because the alternative reads as a broken viewer. A source that
+ * carried no normals encodes the engine default everywhere, every cluster compresses to one constant
+ * word, and `colour by stored normal` comes out one flat colour across the whole model.
+ *
+ * @param {VGeoContainerReader} reader
+ * @returns {{storage: string, normals: string}}
+ */
+function page_summary(reader) {
     let stored = 0;
     let decoded = 0;
+    let per_vertex = 0;
+    let clusters = 0;
+    let pages = 0;
+
+    const codecs = new Set();
 
-    for (const page of pages) {
+    for (const page of reader.resident_pages()) {
         stored += page.stored_size;
         decoded += page.decoded_size;
+        per_vertex += page.per_vertex_normal_cluster_count;
+        clusters += page.cluster_count;
+
+        codecs.add(page.codec);
+
+        pages++;
     }
 
-    const codec = Array.from(new Set(pages.map((page) => page.codec)))
-        .map(vgeo_codec_name)
-        .join(' + ');
+    const codec = Array.from(codecs).map(vgeo_codec_name).join(' + ');
 
-    return `${human_bytes(stored)} stored · ${human_bytes(decoded)} decoded`
-        + ` · ${codec} ${(decoded / Math.max(stored, 1)).toFixed(2)}x`;
+    return {
+        storage: pages === 0
+            ? '—'
+            : `${human_bytes(stored)} stored · ${human_bytes(decoded)} decoded`
+                + ` · ${codec} ${(decoded / Math.max(stored, 1)).toFixed(2)}x`,
+        normals: `${thousands(per_vertex)} / ${thousands(clusters)} clusters`,
+    };
 }
 
 /**
@@ -596,6 +643,19 @@ class VGeoViewer {
             ['camera drift', `${this.#drift().toExponential(2)} u`],
         ];
 
+        /*
+         A clamp whose child page is already resident is waiting on a page holding one of that
+         group's *other* parents (§10, activation) — so it is not counted by any want, and without
+         this row the panel reads as `20 waiting on 5 page(s)` while five pages would not have
+         settled all twenty. Only shown when it happens, which on a small asset is never.
+        */
+        if (cut.clamped_on_activation > 0) {
+            rows.push([
+                'of those, on a parent',
+                `<span class="warn">${thousands(cut.clamped_on_activation)}</span>`
+            ]);
+        }
+
         if (cut.broken_child_refs > 0) {
             rows.push(['broken child refs', `<span class="bad">${thousands(cut.broken_child_refs)}</span>`]);
         }
@@ -789,10 +849,10 @@ class VGeoViewer {
         const sample = vgeo_sample_source();
 
         /*
-         The default prefix is one nominal page plus the head, and a *default* build has 256 KB
-         pages. The sample's are 8 KB, so the same prefix would swallow most of it and there would be
-         nothing left to stream — a demonstration of the head prefix rather than of the reader. Sized
-         to the sample's own pages instead, unless the address bar has already made the choice.
+         The default prefix is 64 KB, sized against a *default* build's pages of hundreds of KB. The
+         sample's are 8 KB, so even that prefix would swallow much of it and there would be little
+         left to stream — a demonstration of the head prefix rather than of the reader. Sized to the
+         sample's own pages instead, unless the address bar has already made the choice.
         */
         if (!this.#head_pinned) {
             this.#read_options.head_prefix_bytes = 16 * 1024;
@@ -854,7 +914,7 @@ class VGeoViewer {
         const started = performance.now();
 
         try {
-            this.#defects = await this.#reader.validate();
+            this.#defects = await vgeo_audit_container(this.#reader);
         } catch (e) {
             this.#defects = undefined;
             this.#validation_status = String(e.message ?? e);
@@ -883,11 +943,18 @@ class VGeoViewer {
         this.#status = 'installing every page';
         this.#refresh_panel();
 
-        await this.#reader.install_all_pages((done, total) => {
-            this.#status = `installing every page — ${done} / ${total}`;
-        });
+        try {
+            await vgeo_install_all_pages(this.#reader, (done, total) => {
+                this.#status = `installing every page — ${done} / ${total}`;
+            });
 
-        this.#status = '';
+            this.#status = '';
+        } catch (e) {
+            // A page that could not be read is quarantined rather than fatal now, and the tool
+            // reports at the end rather than stopping at the first one — so every page that *could*
+            // be installed is here, and the message says how many could not.
+            this.#status = String(e.message ?? e);
+        }
 
         this.adapt();
         this.#refresh_panel();
@@ -1010,7 +1077,7 @@ class VGeoViewer {
         const header = reader.header;
         const source = reader.source;
 
-        const pages = reader.pages;
+        const summary = page_summary(reader);
 
         /*
          Cumulative for the session, and deliberately allowed past the file's own size: evicting and
@@ -1037,32 +1104,13 @@ class VGeoViewer {
                 ['requests', thousands(source.request_count)],
                 ['cold start', `${human_bytes(this.#open_bytes)} · ${this.#open_ms.toFixed(1)} ms`],
                 ['resident', `${thousands(reader.resident_page_count)} / ${thousands(header.total_pages)} pages · ${human_bytes(reader.resident_bytes)}`],
-                ['page storage', page_storage(pages)],
-                ['per-vertex normals', this.#normal_share(pages)],
+                ['page storage', summary.storage],
+                ['per-vertex normals', summary.normals],
+                ['head prefix', reader.head_bytes === 0 ? 'released' : human_bytes(reader.head_bytes)],
+                ['quarantined', quarantine_summary(reader)],
             ]);
     }
 
-    /**
-     * How many resident clusters store a normal per vertex, against how many are resident at all.
-     *
-     * Worth saying outright because the alternative reads as a broken viewer: a source that carried
-     * no normals encodes the engine default everywhere, every cluster compresses to one constant
-     * word, and `colour by stored normal` comes out one flat colour across the whole model.
-     *
-     * @param {VGeoPage[]} pages
-     * @returns {string}
-     */
-    #normal_share(pages) {
-        let per_vertex = 0;
-        let total = 0;
-
-        for (const page of pages) {
-            per_vertex += page.per_vertex_normal_cluster_count;
-            total += page.cluster_count;
-        }
-
-        return `${thousands(per_vertex)} / ${thousands(total)} clusters`;
-    }
 
     /**
      * @returns {string}
@@ -1269,12 +1317,15 @@ function __state() {
         total_clusters: reader?.header.total_clusters,
         resident_pages: reader?.resident_page_count ?? 0,
         resident_bytes: reader?.resident_bytes ?? 0,
+        head_bytes: reader?.head_bytes ?? 0,
+        quarantined_pages: reader?.quarantined_page_count ?? 0,
         file_bytes: reader?.source.byte_length ?? 0,
         bytes_read: reader?.source.bytes_read ?? 0,
         requests: reader?.source.request_count ?? 0,
         clusters: cut.clusters.length,
         triangles: cut.triangle_count,
         clamped: cut.clamped,
+        clamped_on_activation: cut.clamped_on_activation,
         wants: cut.wants.length,
         broken_child_refs: cut.broken_child_refs,
     };

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

@@ -28,6 +28,13 @@ export function vgeo_select_cut(reader: VGeoContainerReader, view: VGeoCutView):
  * records carries the exact byte range that would refine it. That is what makes streaming safe in
  * any arrival order, and it is why this file's most interesting number is `clamped`.
  *
+ * "Not here" is `VGeoContainerReader.is_selectable`, not `is_resident`, and the difference is the
+ * one thing about this traversal that is not obvious: a group is refined into only once every page
+ * holding one of its *parents* is installed. Residency alone lets a group be entered through the
+ * parents that arrived while a coarse cluster still covers the one that did not, and then both are
+ * drawn over the same surface. §10 calls that out by name — "no holes **and no double-draw**, in any
+ * arrival order" — and the second half is the one that fails silently.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -119,6 +126,18 @@ export class VGeoCut {
      * @type {number}
      */
     clamped: number;
+    /**
+     * Of those, the ones whose child group's page is **here** and merely not selectable yet, because
+     * a page holding one of that group's other parents is not.
+     *
+     * They carry no want: there is nothing to fetch from a cluster that already has the bytes it
+     * points at. What unblocks them is elsewhere in the same cut — the cluster clamped directly
+     * against the missing page — so this number is not a second streaming frontier, it is how much
+     * of the coarseness on screen is the ancestor rule holding a group back rather than bandwidth.
+     *
+     * @type {number}
+     */
+    clamped_on_activation: number;
     /**
      * Which clusters those were, keyed `page · 65536 + cluster`. What the panel counts, a display
      * can paint — so the regions still waiting on bytes are visible as regions.

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

@@ -1 +1 @@
-{"version":3,"file":"select_cut.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_viewer/select_cut.js"],"names":[],"mappings":"AAkOA;;;;;;;;;;;;;;;GAeG;AACH,mEAHW,WAAW,GACT,OAAO,CAwInB;AAhXD;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AACH;IACI;;;OAGG;IACH,KAFU,YAAY,CAEI;IAE1B;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;;OAGG;IACH,eAFU,MAAM,CAEK;IAErB;;OAEG;IACH,OAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,cAFU,OAAO,CAEI;IAErB;;;OAGG;IACH,SAFU,YAAY,CAES;CAClC;AAED;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,OAFU,UAAU,CAET;IAEX;;;;OAIG;IACH,UAFU,MAAM,EAAE,CAEJ;IAEd;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,QAFU,MAAM,CAEL;IAEX;;;;;;;;;;OAUG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;OAIG;IACH,cAFU,IAAI,MAAM,CAAC,CAEI;IAEzB;;;;;;;;OAQG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,OAFU,YAAY,EAAE,CAEb;IAEX;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;OAEG;IACH,aAFU,MAAM,CAEA;CACnB;6BA7JM,6DAA6D"}
+{"version":3,"file":"select_cut.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_viewer/select_cut.js"],"names":[],"mappings":"AAsPA;;;;;;;;;;;;;;;GAeG;AACH,mEAHW,WAAW,GACT,OAAO,CAgKnB;AA5ZD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;GAGG;AACH;IACI;;;OAGG;IACH,KAFU,YAAY,CAEI;IAE1B;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;;OAGG;IACH,eAFU,MAAM,CAEK;IAErB;;OAEG;IACH,OAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,cAFU,OAAO,CAEI;IAErB;;;OAGG;IACH,SAFU,YAAY,CAES;CAClC;AAED;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,OAFU,UAAU,CAET;IAEX;;;;OAIG;IACH,UAFU,MAAM,EAAE,CAEJ;IAEd;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,QAFU,MAAM,CAEL;IAEX;;;;;;;;;;OAUG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;;;;;;OAUG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;OAIG;IACH,cAFU,IAAI,MAAM,CAAC,CAEI;IAEzB;;;;;;;;OAQG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,OAFU,YAAY,EAAE,CAEb;IAEX;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;OAEG;IACH,aAFU,MAAM,CAEA;CACnB;6BAjLM,6DAA6D"}