@woosh/meep-engine 3.26.0 → 3.28.0

package/src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.js

@@ -11,6 +11,7 @@ import { CodeChunk } from "../compiler/CodeChunk.js";
 import { parse_wgsl_type } from "../type/parse_wgsl_type.js";
 import { type_has_arrays } from "../type/type_has_arrays.js";
 import { type_has_atomics } from "../type/type_has_atomics.js";
+import { WebGPUStruct } from "../type/WebGPUStruct.js";
 import { write_wgsl_type_value } from "../type/serde/write_gpu_typed_buffer.js";
 import { IMMEDIATE_ADDRESS_SPACE_EXTENSION, IMMEDIATE_SIZE_FLOOR } from "./IMMEDIATE_DATA.js";
 import { ResourceType } from "./ResourceType.js";
@@ -226,7 +227,14 @@ export class ShaderResourceSetDescriptor {
             );
         }
 
-        this.#immediate = { name, type };
+        // The top-level member names, kept so that `writeImmediate` can tell a value of this type
+        // from something that merely happens to be an object. `undefined` for a scalar, vector or
+        // matrix immediate, which has no members to name.
+        const field_names = type instanceof WebGPUStruct
+            ? type.fields.map(field => field.name)
+            : undefined;
+
+        this.#immediate = { name, type, field_names };
 
         return this;
     }
@@ -561,27 +569,73 @@ export class ShaderResourceSetDescriptor {
             );
         }
 
+        // Refuse a value of the wrong shape rather than serialise what it does not contain.
+        //
+        // The whole declared range travels every dispatch, and the zeroes this method clears it to are
+        // indistinguishable from deliberate ones: every slot ends up *set*, so WebGPU's immediate
+        // validation — and the software device's copy of it — has nothing to report. A wrong-shaped
+        // value therefore reaches the shader as zeroes, silently, and the only symptom is wrong
+        // output. That is what a call site left behind by the uniform -> immediate migration does: it
+        // keeps handing over the transient GPUBuffer the uniform needed, `generateBindings` ignores
+        // the extra key so the buffer is never bound, and nothing on a GPUBuffer matches the type.
+        //
+        // A value that names *some* of the members is left alone. Structs carry explicit padding
+        // members the CPU side has no value for, and skipping absent fields is load-bearing anyway
+        // (GPUTypedTable#set_range writes one member of a record through the same serialiser). Only a
+        // value that could not have populated the type at all is an unambiguous mistake.
+        const field_names = immediate.field_names;
+
+        if (field_names === undefined) {
+            // Scalar, vector or matrix: the serialiser reads the value as a number or indexes it.
+            const usable = typeof value === "number"
+                || typeof value === "boolean"
+                || typeof value[0] === "number";
+
+            if (!usable) {
+                throw new Error(
+                    `Immediate data '${immediate.name}' of type '${immediate.type}' was given a value the`
+                    + ` serialiser cannot read as a number: '${value}'. An immediate takes the plain value,`
+                    + ` not something bindable — a GPUBuffer is what a *uniform* binding wants, and one`
+                    + ` passed here is ignored by generateBindings and would serialise as zeroes.`
+                );
+            }
+        } else if (!value_names_a_member(value, field_names)) {
+            // Note: no `${immediate.type}` in the message. Interpolating a struct type runs its whole
+            // WGSL declaration through the code generator, and the member list is the actionable half
+            // of that anyway.
+            throw new Error(
+                `Immediate data '${immediate.name}' was given a value naming none of its members`
+                + ` (${field_names.join(', ')}), so the dispatch would have read zeroes. An immediate`
+                + ` takes the plain value — '{ ${field_names[0]}: ... }' — not`
+                + ` something bindable: a GPUBuffer is what a *uniform* binding wants, and one passed`
+                + ` here is ignored by generateBindings and serialises to nothing.`
+            );
+        }
+
         const start = buffer.position;
         const size = this.immediateSize;
 
         buffer.ensureCapacity(start + size);
 
-        write_wgsl_type_value(value, buffer, immediate.type);
-
-        // Zero-fill out to the declared size rather than stopping where the last member ended.
+        // Clear the whole declared range up front, rather than filling in from wherever the
+        // serialiser's cursor stopped.
         //
-        // The serialiser stops after the final member, so a struct with trailing padding — say
-        // `{vec4f, u32}`, 20 bytes written of a 32-byte type — leaves a tail. That tail is padding,
-        // WebGPU's AccessibleSlots excludes padding, and a short write would in fact validate. It
-        // would also mean the bytes handed to `setImmediates` are shorter than the `immediateSize`
-        // the pipeline layout declares, which is true-but-subtle in a way that only holds as long as
-        // nobody changes how either number is derived. Writing the full declared size costs at most
-        // 64 bytes of memset and makes the two trivially equal.
-        const written = buffer.position - start;
-
-        for (let i = written; i < size; i++) {
-            buffer.raw_bytes[start + i] = 0;
-        }
+        // Two reasons, and the second is the one that bites. The first: the serialiser stops after the
+        // final member, so a struct with trailing padding — say `{vec4f, u32}`, 20 bytes written of a
+        // 32-byte type — leaves a tail. That tail is padding, WebGPU's AccessibleSlots excludes
+        // padding, and a short write would in fact validate; it would also make the bytes handed to
+        // `setImmediates` shorter than the `immediateSize` the pipeline layout declares, true-but-subtle
+        // in a way that only holds as long as nobody changes how either number is derived.
+        //
+        // The second: this buffer is one scratch region reused by every dispatch of a context, and it
+        // is only ever written over, never cleared. A member the value did not name is skipped, and a
+        // skipped member before the final one is not in the tail — filling from the cursor left it
+        // holding the bytes the *previous* dispatch put at that offset. A partial value is legal (see
+        // above), so that made one dispatch's immediate data a function of the one before it. Clearing
+        // first closes the holes and the tail together, and costs at most 64 bytes of memset.
+        buffer.raw_bytes.fill(0, start, start + size);
+
+        write_wgsl_type_value(value, buffer, immediate.type);
 
         buffer.position = start + size;
 
@@ -589,6 +643,28 @@ export class ShaderResourceSetDescriptor {
     }
 }
 
+/**
+ * Whether `value` carries at least one of `field_names`.
+ *
+ * A plain loop, and a free function rather than a closure over `value`, because
+ * {@link ShaderResourceSetDescriptor#writeImmediate} runs once per dispatch and allocates nothing.
+ *
+ * @param {Object} value
+ * @param {string[]} field_names
+ * @returns {boolean}
+ */
+function value_names_a_member(value, field_names) {
+    const count = field_names.length;
+
+    for (let i = 0; i < count; i++) {
+        if (value[field_names[i]] !== undefined) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
 /**
  * Special immutable empty set
  * @readonly

package/src/shade/renderer/view/GPUViewContext.d.ts

@@ -90,6 +90,10 @@ export class GPUViewContext {
      * @returns {GPUCameraContext}
      */
     get gpu_previous_camera_state(): GPUCameraContext;
+    /**
+     * @return {VGeoViewCut}
+     */
+    get virtual_geometry_cut(): VGeoViewCut;
     /**
      *
      * @return {GPUCameraContext}
@@ -136,4 +140,5 @@ import { HierarchicalZBuffer } from "../hiz/HierarchicalZBuffer.js";
 import { GPUTypedBuffer } from "../buffer/GPUTypedBuffer.js";
 import { GPUViewVolumetrics } from "../volumetrics/GPUViewVolumetrics.js";
 import { GPUCameraContext } from "../camera/GPUCameraContext.js";
+import { VGeoViewCut } from "../geometry/virtual/runtime/VGeoViewCut.js";
 //# sourceMappingURL=GPUViewContext.d.ts.map

package/src/shade/renderer/view/GPUViewContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUViewContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/view/GPUViewContext.js"],"names":[],"mappings":";;;;;;;;AA+BA;;GAEG;AACH;IAiOI;;;;;OAKG;IACH,sBAJW,eAAe,SACf,eAAe,UACf,gBAAgB,EAuB1B;IA1PD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,OAFU,MAAM,CAEL;IAuBX;;;;OAIG;IACH,mBAHW,MAAM,KACN,MAAM,QAiBhB;IAED;;;;OAIG;IACH,aAHW,MAAM,KACN,MAAM,QAQhB;IAED;;;;OAIG;IACH,kBAHW,MAAM,KACN,MAAM,QAOhB;IAED,wEAAwE;IACxE,2BAAqC;IAErC,6BAA6B;IAC7B,8BAEC;IAQD;;;OAGG;IACH,0BAEC;IAED;;;;OAIG;IACH,mBAHW,MAAM,KACN,MAAM,QAUhB;IAgBD;;;OAGG;IACH,kDAEC;IAdD;;;OAGG;IACH,iDAEC;IAgBD;;;OAGG;IACH,qCAEC;IAQD;;;OAGG;IACH,sCAEC;IA4BD;;;OAGG;IACH,mDAEC;IAdD;;;OAGG;IACH,kDAEC;IAgBD;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,mEAEC;IA+BD;;;;OAIG;IACH,cAHW,cAAc,GACZ,OAAO,CAWnB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED,wBA6BC;IAGD;;;OAGG;IACH,YAFW,eAAe,QAWzB;IAED;;OAEG;IACH,0BAFW,sBAAsB,QAShC;IAED,gBAgBC;IAGL;;;OAGG;IACH,2BAFU,OAAO,CAEwB;;CANxC;qCAtXY,OAAO,wCAAwC,EAAE,sBAAsB;8BACvE,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;oCAP9B,+BAA+B;+BAFpC,6BAA6B;mCAGzB,sCAAsC;iCAFxC,+BAA+B"}
+{"version":3,"file":"GPUViewContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/view/GPUViewContext.js"],"names":[],"mappings":";;;;;;;;AAgCA;;GAEG;AACH;IAiPI;;;;;OAKG;IACH,sBAJW,eAAe,SACf,eAAe,UACf,gBAAgB,EAyB1B;IA5QD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,OAFU,MAAM,CAEL;IAuBX;;;;OAIG;IACH,mBAHW,MAAM,KACN,MAAM,QAiBhB;IAED;;;;OAIG;IACH,aAHW,MAAM,KACN,MAAM,QAQhB;IAED;;;;OAIG;IACH,kBAHW,MAAM,KACN,MAAM,QAOhB;IAED,wEAAwE;IACxE,2BAAqC;IAErC,6BAA6B;IAC7B,8BAEC;IAQD;;;OAGG;IACH,0BAEC;IAED;;;;OAIG;IACH,mBAHW,MAAM,KACN,MAAM,QAUhB;IAgBD;;;OAGG;IACH,kDAEC;IAdD;;;OAGG;IACH,iDAEC;IAgBD;;;OAGG;IACH,qCAEC;IAQD;;;OAGG;IACH,sCAEC;IA4BD;;;OAGG;IACH,mDAEC;IAdD;;;OAGG;IACH,kDAEC;IAyBD;;OAEG;IACH,wCAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,mEAEC;IAiCD;;;;OAIG;IACH,cAHW,cAAc,GACZ,OAAO,CAWnB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED,wBA6BC;IAGD;;;OAGG;IACH,YAFW,eAAe,QAWzB;IAED;;OAEG;IACH,0BAFW,sBAAsB,QAShC;IAED,gBAkBC;IAGL;;;OAGG;IACH,2BAFU,OAAO,CAEwB;;CANxC;qCA1YY,OAAO,wCAAwC,EAAE,sBAAsB;8BACvE,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;oCAP9B,+BAA+B;+BAHpC,6BAA6B;mCAIzB,sCAAsC;iCAHxC,+BAA+B;4BACpC,4CAA4C"}

package/src/shade/renderer/view/GPUViewContext.js

@@ -7,6 +7,7 @@ import Vector3 from "../../../core/geom/Vector3.js";
 import { queue_typed_buffer_update } from "../shader/type/queue_typed_buffer_update.js";
 import { GPUTypedBuffer } from "../buffer/GPUTypedBuffer.js";
 import { GPUCameraContext } from "../camera/GPUCameraContext.js";
+import { VGeoViewCut } from "../geometry/virtual/runtime/VGeoViewCut.js";
 import { HierarchicalZBuffer } from "../hiz/HierarchicalZBuffer.js";
 import { GPUViewVolumetrics } from "../volumetrics/GPUViewVolumetrics.js";
 import { VIEW_UNIFORM_STRUCT } from "./VIEW_UNIFORM_STRUCT.js";
@@ -241,6 +242,22 @@ export class GPUViewContext {
     #device;
 
 
+    /**
+     * What cutting virtual geometry is per view: this view's params, and the state a cut
+     * kept between frames would live in. Held here for the same reason the HZB is —
+     * two views must not share it.
+     *
+     * @type {VGeoViewCut}
+     */
+    #virtual_geometry_cut;
+
+    /**
+     * @return {VGeoViewCut}
+     */
+    get virtual_geometry_cut() {
+        return this.#virtual_geometry_cut;
+    }
+
     /**
      *
      * @return {GPUCameraContext}
@@ -284,6 +301,8 @@ export class GPUViewContext {
 
         this.#volumetrics = new GPUViewVolumetrics(this, device);
 
+        this.#virtual_geometry_cut = new VGeoViewCut({ device, label: this.label });
+
     }
 
     /**
@@ -385,6 +404,8 @@ export class GPUViewContext {
         this.#hierarchical_z_buffer.destroy();
 
         this.#volumetrics.destroy();
+
+        this.#virtual_geometry_cut.destroy();
     }
 }
 

package/src/shade/wgsl/emulator/WGSLLanguageCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":"AA0PA;;;;;;;;;;;;GAYG;AACH,+BAFU,MAAM,CAkgCd"}
+{"version":3,"file":"WGSLLanguageCore.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLLanguageCore.js"],"names":[],"mappings":"AA0PA;;;;;;;;;;;;GAYG;AACH,+BAFU,MAAM,CAykCd"}

package/src/shade/wgsl/emulator/WGSLLanguageCore.js

@@ -1166,6 +1166,28 @@ export const WGSLLanguageCore = {
         return { old_value: old, exchanged: false };
     },
 
+    // ---------------------------------------------------------------------
+    // Runtime-sized arrays
+    // ---------------------------------------------------------------------
+
+    /**
+     * WGSL's `arrayLength(&a)` — how many elements of a runtime-sized array the *binding* covers.
+     *
+     * The compiler has already reduced `&a` to `a` itself, so what arrives is the bound value: a
+     * typed array, or a plain array for a binding of structs. Its length is the answer, and the
+     * binding a spec supplies is therefore what decides it — which is the point. Every collection
+     * in this engine is a `count` in front of a runtime-sized `elements`, and the count is produced
+     * by an unconditional `atomicAdd` whose element write alone is bounded, so the count can run
+     * past what the collection holds. `min(count, arrayLength(&elements))` is how a consumer reads
+     * such a collection, and without this a kernel that does so could not be emulated at all.
+     *
+     * @param {ArrayLike<*>} a
+     * @returns {number}
+     */
+    arrayLength(a) {
+        return a.length;
+    },
+
     // ---------------------------------------------------------------------
     // Barriers — no-ops when running pointwise (one thread).
     // ---------------------------------------------------------------------
@@ -1187,12 +1209,61 @@ export const WGSLLanguageCore = {
     // pointwise there is exactly one, so the answer is the caller's own value — which is also the
     // only value a shader can soundly rely on it for: one that broadcasts something its lanes
     // disagree on has made its result depend on which lane the hardware counts as first, and no
-    // CPU model reproduces that. The rest of the family — ballots, reductions, shuffles — stays
-    // unsupported on purpose: a reduction over one lane would pass tests a real wave fails, which
-    // is worse than throwing.
+    // CPU model reproduces that.
+    //
+    // The reductions and the shuffle below are the same identity, and they were left out on the
+    // argument that "a reduction over one lane would pass tests a real wave fails". That argument
+    // is right about what they cover and wrong about the alternative, because there is no
+    // alternative: a subgroup kernel has to be correct at **every** width, WGSL promising nothing
+    // about which one a device hands it, and one is a width a device may hand it. Refusing to model
+    // it does not test the wide case — it leaves the kernel with no CPU-tier coverage at all,
+    // including of the part that has nothing to do with width.
+    //
+    // So: width one is a configuration, not a stand-in for a wave. What these cover is a kernel's
+    // *semantics* at that width. What they cannot cover is the redistribution itself — whether
+    // lanes pack their neighbours' work correctly — and that needs a real device and a test that
+    // varies the counts across lanes. Anything relying on more than one lane being live must say so
+    // and be tested there.
+    //
+    // A shader that would diverge between width one and width thirty-two is a shader that has read
+    // something other than its own lane's value out of these, and that is exactly what the wide
+    // test is for.
 
     subgroupBroadcastFirst(value) { return value; },
 
+    // The reduction over a subgroup of one is that one's value.
+    subgroupAdd(value) { return value; },
+    subgroupMul(value) { return value; },
+    subgroupMin(value) { return value; },
+    subgroupMax(value) { return value; },
+    subgroupAnd(value) { return value; },
+    subgroupOr(value) { return value; },
+    subgroupXor(value) { return value; },
+
+    // Scans: exclusive of the only lane is the identity, inclusive of it is its value.
+    subgroupExclusiveAdd() { return 0; },
+    subgroupExclusiveMul() { return 1; },
+    subgroupInclusiveAdd(value) { return value; },
+    subgroupInclusiveMul(value) { return value; },
+
+    // Lane 0 is the only lane, so it is elected and it is the only one a shuffle can name. An `id`
+    // of anything else is reading a lane that does not exist, which on a device is an undefined
+    // value rather than an error — here it is an error, because a CPU model that invents one is how
+    // a kernel indexing lanes by arithmetic passes.
+    subgroupElect() { return true; },
+
+    subgroupShuffle(value, id) {
+        if (id !== 0) {
+            throw new Error(
+                `subgroupShuffle(e, ${id}): the emulated subgroup is one lane wide, so 0 is the only`
+                + ` lane there is to read. A kernel that needs a wider one has to be tested on a`
+                + ` device.`
+            );
+        }
+
+        return value;
+    },
+
     // ---------------------------------------------------------------------
     // Fragment-stage derivatives — unsupported because we run a single pixel.
     // ---------------------------------------------------------------------

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

@@ -1,150 +0,0 @@
-# `.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.
-
-"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 |
-|---|---|
-| **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.
-
-**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.
-
-## 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`.
-
-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
-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.