@woosh/meep-engine 3.27.0 → 3.28.0

package/src/shade/renderer/Renderer.d.ts

@@ -389,7 +389,10 @@ export class Renderer {
      *
      * @param {PerspectiveCamera} camera
      * @param {Scene} scene
-     * @param {number} [time_delta_seconds]
+     * @param {number} [time_delta_seconds] simulation seconds this frame advances by — the particle
+     * simulation, the animation tick and exposure adaptation all step by it. Zero by default, which
+     * draws the current state and moves nothing; a fixed fraction of a second here instead would run
+     * the simulation at that rate no matter what the caller's clock was doing.
      * @returns {boolean} whether frame was rendered, will return false if previous frame hasn't finished yet
      */
     render(camera: PerspectiveCamera, scene: Scene, time_delta_seconds?: number): boolean;

package/src/shade/renderer/Renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/Renderer.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Renderer.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/Renderer.js"],"names":[],"mappings":"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"}

package/src/shade/renderer/Renderer.js

@@ -1720,13 +1720,16 @@ export class Renderer {
      *
      * @param {PerspectiveCamera} camera
      * @param {Scene} scene
-     * @param {number} [time_delta_seconds]
+     * @param {number} [time_delta_seconds] simulation seconds this frame advances by — the particle
+     * simulation, the animation tick and exposure adaptation all step by it. Zero by default, which
+     * draws the current state and moves nothing; a fixed fraction of a second here instead would run
+     * the simulation at that rate no matter what the caller's clock was doing.
      * @returns {boolean} whether frame was rendered, will return false if previous frame hasn't finished yet
      */
     render(
         camera,
         scene,
-        time_delta_seconds = 0.01666
+        time_delta_seconds = 0
     ) {
         if (this.#device_lost) {
             // device is lost, can't render — and asking the context for a texture would throw

package/src/shade/renderer/extension/RENDER_EXTENSION_DESIGN.md

@@ -677,7 +677,7 @@ add_extension(e); remove_extension(e); extension_count(phase);
 
 ## 8. Migration
 
-Nine live systems, one probe, one prototype viewer. Every one of them is the same mechanical change:
+Nine live systems and one probe. Every one of them is the same mechanical change:
 a closure becomes a class, `context.color` becomes `frame.get(SceneColor).color`, and the return
 value becomes a publication.
 
@@ -693,7 +693,6 @@ value becomes a publication.
 | `DebugDrawSystem` | `AfterTransparency` | `after: [FogOfWarExtension]` |
 | `Trail3DSystem` | `AfterTransparency` | — |
 | `probeShadePassInjection` | all | the gate is rewritten and gains the two checks it is currently blind to: a G-buffer replacement, and an order flip |
-| `vgeo_viewer` playground | `AfterTransparency` | prototype; mechanical |
 
 **The `AfterTransparency` chain is settled, not open.** Fog of war is last among the content
 extensions, because it conceals and therefore belongs over everything it is meant to conceal —

package/src/shade/renderer/geometry/meshlet/MeshletBatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeshletBatch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/MeshletBatch.js"],"names":[],"mappings":"AAkEA;;GAEG;AACH;IAiBI;;;OAGG;IACH,oCAGC;IAXD,+BAEC;IA6BD;;;OAGG;IACH,wCAGC;IAfD;;;OAGG;IACH,mCAEC;IAqBD;;;OAGG;IACH,yBAEC;IAdD;;;OAGG;IACH,oBAEC;IAUD;;;OAGG;IACH,QAFa,MAAM,CASlB;IAED;;;OAGG;IACH,cAFW,YAAY,WAQtB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAoFlB;IAED;;;OAGG;IACH,iBAEC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACL,EAAE,CAeb;IAED;;;OAGG;IACH,yBAFW,MAAM;;;;MAgChB;IA4LD,qBA+BC;IAED;;;OAGG;IACH,gBAFW,QAAQ,QASlB;IAIL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;uBA1gBY,OAAO,gBAAgB,EAAE,QAAQ"}
+{"version":3,"file":"MeshletBatch.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/meshlet/MeshletBatch.js"],"names":[],"mappings":"AAwCA;;GAEG;AACH;IAiBI;;;OAGG;IACH,oCAGC;IAXD,+BAEC;IA6BD;;;OAGG;IACH,wCAGC;IAfD;;;OAGG;IACH,mCAEC;IAqBD;;;OAGG;IACH,yBAEC;IAdD;;;OAGG;IACH,oBAEC;IAUD;;;OAGG;IACH,QAFa,MAAM,CASlB;IAED;;;OAGG;IACH,cAFW,YAAY,WAQtB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAoFlB;IAED;;;OAGG;IACH,iBAEC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACL,EAAE,CAeb;IAED;;;OAGG;IACH,yBAFW,MAAM;;;;MAgChB;IA4LD,qBA+BC;IAED;;;OAGG;IACH,gBAFW,QAAQ,QASlB;IAIL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;uBA/eY,OAAO,gBAAgB,EAAE,QAAQ"}

package/src/shade/renderer/geometry/meshlet/MeshletBatch.js

@@ -11,10 +11,11 @@ import { aabb3_from_v3_array } from "../../../../core/geom/3d/aabb/aabb3_from_v3
 import { round_up } from "../../../../core/math/round_up.js";
 import { read_wgsl_type_value } from "../../shader/type/serde/read_gpu_typed_buffer.js";
 import { write_wgsl_type_value } from "../../shader/type/serde/write_gpu_typed_buffer.js";
-import { encode_normals_to_octahedral_u32 } from "../normals/encode_normals_to_octahedral_u32.js";
-import { encode_tangents_to_u32 } from "../normals/encode_tangents_to_u32.js";
 import { StandardAttributes } from "../StandardAttributes.js";
 import { geometry_to_meshlets_meshoptimizer } from "./build/meshoptimizer/geometry_to_meshlets_meshoptimizer.js";
+import {
+    ENCODED_ATTRIBUTE_DEFAULT_VALUES
+} from "./encoding/ENCODED_ATTRIBUTE_DEFAULT_VALUES.js";
 import { ENCODED_ATTRIBUTE_SIZES } from "./encoding/ENCODED_ATTRIBUTE_SIZES.js";
 import { ENCODED_ORDERED_ATTRIBUTES } from "./encoding/ENCODED_ORDERED_ATTRIBUTES.js";
 import { MESHLET_ATTRIBUTE_COMPRESSION_FLAGS } from "./encoding/MESHLET_ATTRIBUTE_COMPRESSION_FLAGS.js";
@@ -30,33 +31,6 @@ import { meshlet_get_attribute_offset } from "./meshlet_get_attribute_offset.js"
  */
 
 
-const ENCODED_ATTRIBUTE_DEFAULT_VALUES = {
-    [StandardAttributes.Color]: 0xFFFFFFFF,
-    [StandardAttributes.TextureCoordinates0]: [0, 0],
-    [StandardAttributes.TextureCoordinates1]: 0,
-    [StandardAttributes.Normal]: 0,
-    [StandardAttributes.Tangent]: 0,
-    [StandardAttributes.SkinningJoints]: [0,0],
-    // Single u32 with all four packed unorm8 weights at zero —
-    // matches the new 1-u32-per-vertex layout (was [0,0] for the
-    // old f16×4 / 2-u32 layout).
-    [StandardAttributes.SkinningWeights]: 0,
-}
-
-{
-    const default_normal = new Uint32Array(1);
-    encode_normals_to_octahedral_u32(default_normal, 0, 1, [0, 0, 1]);
-
-    ENCODED_ATTRIBUTE_DEFAULT_VALUES[StandardAttributes.Normal] = default_normal[0];
-}
-
-{
-    const default_tangent = new Uint32Array(1);
-    encode_tangents_to_u32(default_tangent, 0, 1, [0, 0, 1, 1]);
-
-    ENCODED_ATTRIBUTE_DEFAULT_VALUES[StandardAttributes.Tangent] = default_tangent[0];
-}
-
 const DEBUG_ATTRIBUTE_SIZE_TOTALS = {};
 
 globalThis.meshlet_debug = DEBUG_ATTRIBUTE_SIZE_TOTALS;

package/src/shade/renderer/geometry/meshlet/encoding/ENCODED_ATTRIBUTE_DEFAULT_VALUES.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What an attribute section holds, already encoded, when the geometry does not carry the attribute
+ * at all. The section is written once and flagged compressed, so this is the value every vertex of
+ * that meshlet reads.
+ *
+ * It lives in its own module because it is not private to the encoder that writes it: the virtual
+ * geometry builder produces payloads that must be **byte-identical** to these, and the only way to
+ * hold it to that is for its spec to compare against this object rather than against a copy of it.
+ * Every other table the two share — order, word sizes, compression flags — is already shared that
+ * way; this was the one that was not, and so the one whose drift nothing would have caught.
+ *
+ * Note what is deliberately asymmetric: colour's default is opaque white with its alpha byte set,
+ * while `encode_colors_to_u32` writes three channels and leaves alpha zero. A geometry with no
+ * colour channel therefore reads a different word than one whose every vertex is white. That is
+ * long-standing behaviour and changing it would change what every existing asset decodes to.
+ *
+ * Position has no entry: it is never absent.
+ *
+ * @type {Object<StandardAttributes, number|number[]>}
+ */
+export const ENCODED_ATTRIBUTE_DEFAULT_VALUES: any;
+//# sourceMappingURL=ENCODED_ATTRIBUTE_DEFAULT_VALUES.d.ts.map

package/src/shade/renderer/geometry/meshlet/encoding/ENCODED_ATTRIBUTE_DEFAULT_VALUES.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ENCODED_ATTRIBUTE_DEFAULT_VALUES.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/meshlet/encoding/ENCODED_ATTRIBUTE_DEFAULT_VALUES.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,mDAUE"}

package/src/shade/renderer/geometry/meshlet/encoding/ENCODED_ATTRIBUTE_DEFAULT_VALUES.js

@@ -0,0 +1,49 @@
+import { encode_normals_to_octahedral_u32 } from "../../normals/encode_normals_to_octahedral_u32.js";
+import { encode_tangents_to_u32 } from "../../normals/encode_tangents_to_u32.js";
+import { StandardAttributes } from "../../StandardAttributes.js";
+
+/**
+ * What an attribute section holds, already encoded, when the geometry does not carry the attribute
+ * at all. The section is written once and flagged compressed, so this is the value every vertex of
+ * that meshlet reads.
+ *
+ * It lives in its own module because it is not private to the encoder that writes it: the virtual
+ * geometry builder produces payloads that must be **byte-identical** to these, and the only way to
+ * hold it to that is for its spec to compare against this object rather than against a copy of it.
+ * Every other table the two share — order, word sizes, compression flags — is already shared that
+ * way; this was the one that was not, and so the one whose drift nothing would have caught.
+ *
+ * Note what is deliberately asymmetric: colour's default is opaque white with its alpha byte set,
+ * while `encode_colors_to_u32` writes three channels and leaves alpha zero. A geometry with no
+ * colour channel therefore reads a different word than one whose every vertex is white. That is
+ * long-standing behaviour and changing it would change what every existing asset decodes to.
+ *
+ * Position has no entry: it is never absent.
+ *
+ * @type {Object<StandardAttributes, number|number[]>}
+ */
+export const ENCODED_ATTRIBUTE_DEFAULT_VALUES = {
+    [StandardAttributes.Color]: 0xFFFFFFFF,
+    [StandardAttributes.TextureCoordinates0]: [0, 0],
+    [StandardAttributes.TextureCoordinates1]: 0,
+    [StandardAttributes.Normal]: 0,
+    [StandardAttributes.Tangent]: 0,
+    [StandardAttributes.SkinningJoints]: [0, 0],
+    // Single u32 with all four packed unorm8 weights at zero — matches the 1-u32-per-vertex
+    // layout (was [0,0] for the old f16×4 / 2-u32 layout).
+    [StandardAttributes.SkinningWeights]: 0,
+};
+
+{
+    const default_normal = new Uint32Array(1);
+    encode_normals_to_octahedral_u32(default_normal, 0, 1, [0, 0, 1]);
+
+    ENCODED_ATTRIBUTE_DEFAULT_VALUES[StandardAttributes.Normal] = default_normal[0];
+}
+
+{
+    const default_tangent = new Uint32Array(1);
+    encode_tangents_to_u32(default_tangent, 0, 1, [0, 0, 1, 1]);
+
+    ENCODED_ATTRIBUTE_DEFAULT_VALUES[StandardAttributes.Tangent] = default_tangent[0];
+}

package/src/shade/renderer/geometry/virtual/VGEO_FORMAT.md

@@ -28,8 +28,10 @@ consumer reads it, and `runtime/RUNTIME_PLAN.md` §4.8 says why: at the moment a
 per-cluster test the cut has already passed is strictly tighter than any page-level test, so the
 page-level one can never reject anything. Its consumer is prefetch, which is a later campaign.
 
-`shade/playground/vgeo_viewer/` drives the reader end to end, and its `select_cut.js` is a CPU
-reference traversal of the cut rule this format was shaped around.
+`shade/playground/vgeo_runtime/` and `shade/playground/vgeo_scene/` drive the reader end to end
+against a device, and `runtime/cut/__fixtures__/vgeo_select_cut.js` is a CPU reference traversal of the
+cut rule this format was shaped around — the oracle the GPU cut is held to, and the only traversal
+of it that is not a kernel.
 
 ## 1. Design constraints (inherited, binding)
 

package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md

@@ -15,12 +15,14 @@ RAM tier's budget, and `runtime/` is everything §7 describes — the selection
 pass, the VRAM page pool, the feedback loop, and the seam through which VG instances enter the
 meshlet pipeline ([runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md)).
 
-Two playgrounds prove two different things and it is worth not confusing them.
-`shade/playground/vgeo_viewer/` puts a clamped **CPU** cut of a streaming container on screen
-through Shade's direct geometry path — it proves the DAG, the format and the clamp, and by
-construction it proves nothing about the engine. `shade/playground/vgeo_runtime/` puts an ordinary
-`Mesh` in an ordinary `Scene` and draws it entirely from a **GPU** cut through the meshlet
-pipeline — it proves the seam and nothing about the DAG. §10 says which milestone that leaves us
+`shade/playground/vgeo_runtime/` puts an ordinary `Mesh` in an ordinary `Scene` and draws it
+entirely from a **GPU** cut through the meshlet pipeline — it proves the engine seam, and
+`shade/playground/vgeo_scene/` opens a whole converted set at once, where the claim about a *scene*
+is measured. What proves the DAG, the format and the clamp is not a page at all: it is
+`runtime/cut/__fixtures__/vgeo_select_cut.js`, a CPU traversal of the same rule that every cut
+spec is held to. A third playground once drew that traversal on screen through Shade's direct
+geometry path, with its own renderer and its own streaming loop; once the GPU page could show
+everything it showed, it was a second runtime for no gain, and it was retired. §10 says which milestone that leaves us
 in, and the order the work actually arrived in.
 
 ## 1. What and why
@@ -280,7 +282,7 @@ Pinned:
   *before* it is fetched. Below page granularity, each page carries a tree over its own groups
   (format §6.1–6.2). Cost, measured: 0.3%–1.6% of asset size.
 
-  *What exists.* `playground/vgeo_viewer/select_cut.js` is this rule on the CPU, against a
+  *What exists.* `runtime/cut/__fixtures__/vgeo_select_cut.js` is this rule on the CPU, against a
   partially resident container: descend from the root's parentless groups, refine where
   `project(parent) > τ`, take the cluster where it does not, and stop where the child group is
   not selectable — recording the want that would unblock it. It is the reference the GPU pass
@@ -629,7 +631,7 @@ is the piece still missing, and M1 is where the work now starts.
   Acceptance: crack-free under τ sweep and flythrough (incl. group-boundary polyline and
   flip validation); drawn-triangle count tracks resolution, not source size; §3 build
   validations green.
-  **Done**: the builder; a CPU cut (`playground/vgeo_viewer/select_cut.js`) that is a traversal
+  **Done**: the builder; a CPU cut (`runtime/cut/__fixtures__/vgeo_select_cut.js`) that is a traversal
   rather than the flat pass planned here, and that runs against a partially resident container,
   which was M2's job; τ-sweep watertightness as a spec (`build/vgeo_cut.spec.js` counts edges
   used by one triangle instead of two, at a spread of thresholds, and wants zero); the

package/src/shade/renderer/geometry/virtual/VIRTUAL_GEOMETRY_PLAN.md

@@ -33,7 +33,7 @@ accepted-and-waiting one.
 - **Cluster-count simplification target** `[M §2.2]`, and a minimum cluster fill through the
   generalized leaf repack `[V §3.3]`.
 - **Compactness-weighted cluster adjacency** `[M §2.3]` — `compactness()` in
-  `build/vgeo_build_levels.js`.
+  `build/level/vgeo_build_levels.js`.
 - **Speculative groups, rejected individually** `[M §2.4]`.
 - **Per-level summary table in the file head** `[V §4.1, §6.1]` — VGEO_FORMAT §4.1.
 - **A traversal metric on the page DAG, and a group tree inside each page** `[V §2.1, §6.3]` —
@@ -72,12 +72,13 @@ accepted-and-waiting one.
   362 non-root groups have split parents: 355 of 576 camera positions double-drew, up to 10.7%
   of drawn triangles, before. Zero after. It reads as corrupt geometry rather than as a missing
   page, which is why the tool that found it could not name it.
-- **A CPU cut against a partially resident container** — `playground/vgeo_viewer/`.
-  `select_cut.js` is the runtime's rule rather than a debug approximation of it; the viewer is
-  what makes clamping, streaming and eviction watchable, and `__state()` is what makes it
-  assertable from a headless browser. It draws through Shade's direct geometry path, not the
-  meshlet pipeline — so it proves the DAG and the format, and proves nothing about the engine
-  seam.
+- **A CPU cut against a partially resident container** —
+  `runtime/cut/__fixtures__/vgeo_select_cut.js`. It is the runtime's rule rather than a debug
+  approximation of it, and `vgeo_select_cut.spec.js` holds it to the format's guarantees. A
+  `vgeo_viewer` playground used to draw it on screen through Shade's direct geometry path, which is
+  what made clamping, streaming and eviction watchable; once `playground/vgeo_runtime/` could show
+  all of that through the meshlet pipeline, the page was a second renderer and a second streaming
+  loop for no gain, and it was retired. The traversal stayed, because it is the oracle.
 
 - **The GPU runtime** — `runtime/`, and [runtime/RUNTIME_PLAN.md](./runtime/RUNTIME_PLAN.md) for the
   design and the adversarial review that reshaped it. The cut is a wavefront BFS over the page DAG
@@ -95,7 +96,7 @@ accepted-and-waiting one.
     evaluator does not. §6 states the fact without stating it as a term of the rule, because §4 was
     written for a traversal.
   - **Page size decides whether that state is even reachable.** At the 8 KB pages
-    `select_cut.spec.js` uses, a torus puts exactly one group in every page — so a blocked group is
+    `vgeo_select_cut.spec.js` uses, a torus puts exactly one group in every page — so a blocked group is
     a blocked page, no page is ever mixed, and no page is ever entered twice. Measured: 40 pages
     withheld one at a time and 60 random residency subsets produced *no* mixed page. At 64 KB the
     median page holds eight groups and it is ordinary. A spec for anything about mixed selectability
@@ -120,7 +121,7 @@ prefetch.
 ### 2.1 A partitioning fallback for when METIS fails `[M §3.3]`, `[V §3.2]` — LANDED
 
 `core/graph/graph_partition_spectral.js` — recursive spectral bisection over CSR, matrix-free,
-signature-compatible with `metis_partition_kway`. `build/vgeo_partition_graph.js` tries METIS
+signature-compatible with `metis_partition_kway`. `build/partition/vgeo_partition_graph.js` tries METIS
 and falls back to it; both of the builder's partitioning sites go through that wrapper.
 
 Notes worth keeping:
@@ -212,7 +213,7 @@ installed page can be re-tested without walking back to its parent.
 width at the top. This one has *no* paging question by construction: it is inside a page, it
 ships and evicts with it, and it cannot dangle.
 
-Both landed together; VGEO_FORMAT §6.1–6.2 specifies them, `build/vgeo_build_page_nodes.js`
+Both landed together; VGEO_FORMAT §6.1–6.2 specifies them, `build/page/vgeo_build_page_nodes.js`
 builds them. Notes worth keeping:
 
 - The tree needs no partitioner. A page's groups arrive in Morton order of their centroid, so
@@ -243,7 +244,7 @@ for the first few bands, which are also the cheapest to walk.
 LOD-metric sphere and error range (VGEO_FORMAT §5, §6.2), and every page carries a fanout-4 tree
 over its own groups (§6.1). The writer emits them, `vgeo_validate_container` checks them
 (§11.10–11.11) with corruption tests behind both checks, and **nothing reads either**.
-`VGeoPage` records `node_count` and stops; `select_cut.js` descends group by group.
+`VGeoPage` records `node_count` and stops; `vgeo_select_cut` descends group by group.
 
 This is not a defect to fix on its own account. Building a consumer for its own sake would fix
 the interface before the pass that has to live with it, and the CPU traversal does not need the

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.d.ts

@@ -86,5 +86,5 @@ export class VGeoBuildOptions {
      */
     level_options: VGeoLevelOptions;
 }
-import { VGeoLevelOptions } from "./VGeoLevelOptions.js";
+import { VGeoLevelOptions } from "./level/VGeoLevelOptions.js";
 //# sourceMappingURL=VGeoBuildOptions.d.ts.map

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;OAgBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCA7FgC,uBAAuB"}
+{"version":3,"file":"VGeoBuildOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH;IACI;;;;;;;;;;OAUG;IACH,OAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;;;;OAgBG;IACH,aAFU,MAAM,CAEmB;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YAFU,MAAM,CAEE;IAElB;;;;;;;;;;;;;;OAcG;IACH,mBAFU,MAAM,CAE2B;IAE3C;;OAEG;IACH,eAFU,gBAAgB,CAEa;CAC1C;iCA7FgC,6BAA6B"}

package/src/shade/renderer/geometry/virtual/build/VGeoBuildOptions.js

@@ -1,7 +1,7 @@
 import { LZ4_LEVEL } from "../../../../../core/binary/lz4/LZ4_LEVEL.js";
 import { VGEO_CODEC_LZ4 } from "../format/frame/VGEO_CODEC_LZ4.js";
 import { VGEO_DEFAULT_PAGE_SIZE } from "../format/page/VGEO_DEFAULT_PAGE_SIZE.js";
-import { VGeoLevelOptions } from "./VGeoLevelOptions.js";
+import { VGeoLevelOptions } from "./level/VGeoLevelOptions.js";
 
 /**
  * Knobs the builder pipeline exposes.

package/src/shade/renderer/geometry/virtual/build/gltf/gltf_open_document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gltf_open_document.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/gltf/gltf_open_document.js"],"names":[],"mappings":"AA6EA;;;;;;;;;;GAUG;AACH,8CARW,cAAc,yBACL,MAAM,KAAG,cAAc,4CAK9B,YAAY,CA+ExB;+BA1J8B,qBAAqB;6BACvB,mBAAmB"}
+{"version":3,"file":"gltf_open_document.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/gltf/gltf_open_document.js"],"names":[],"mappings":"AAyEA;;;;;;;;;;GAUG;AACH,8CARW,cAAc,yBACL,MAAM,KAAG,cAAc,4CAK9B,YAAY,CA+ExB;+BArJ8B,qBAAqB;6BACvB,mBAAmB"}

package/src/shade/renderer/geometry/virtual/build/gltf/gltf_open_document.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../../../../core/assert.js";
+import { Base64 } from "../../../../../../core/binary/base64/Base64.js";
 import {
     GLTF_BUFFER_VIEW_EXTENSIONS
 } from "../../../../../../format/scene/gltf/ext/gltf_buffer_view_extensions.js";
@@ -26,6 +27,9 @@ import { GltfDocument } from "./GltfDocument.js";
 /**
  * Decode a `data:` URI's payload.
  *
+ * Through {@link Base64} rather than `atob`: the decode is the engine's own, so the builder runs
+ * the same one everywhere and does not need a `atob` to exist on whatever it is running under.
+ *
  * @param {string} uri
  * @returns {Uint8Array}
  * @throws {Error} for an encoding other than base64, which is the only one glTF defines
@@ -39,15 +43,7 @@ function read_data_uri(uri) {
         throw new Error(`unsupported data URI encoding in '${header}'`);
     }
 
-    const binary = atob(uri.slice(comma + 1));
-
-    const result = new Uint8Array(binary.length);
-
-    for (let i = 0; i < binary.length; i++) {
-        result[i] = binary.charCodeAt(i);
-    }
-
-    return result;
+    return new Uint8Array(Base64.decode(uri.slice(comma + 1)));
 }
 
 /**

package/src/shade/renderer/geometry/virtual/build/level/VGeoLevel.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One band of the DAG.
+ *
+ * A level is an ordinal, not a generation: `clusters` are the clusters the round of that index
+ * created, while `groups` are the groups the round *above* consumed — and those groups may hold
+ * clusters from any level at or below their own, because a cluster no round could use waits in the
+ * frontier until one can. What the ordinal guarantees is the only thing the format needs from it:
+ * every group sits strictly below the group holding its parents, so laying pages out by descending
+ * level makes every child reference point forward in the file.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoLevel {
+    /**
+     * `0` = leaves.
+     * @type {number}
+     */
+    index: number;
+    /**
+     * The clusters this level's round created.
+     * @type {VirtualGeometryCluster[]}
+     */
+    clusters: VirtualGeometryCluster[];
+    /**
+     * The groups that sit in this level's band — the ones the round above consumed. Empty for the
+     * top level until the caller assigns its root group.
+     * @type {VirtualGeometryGroup[]}
+     */
+    groups: VirtualGeometryGroup[];
+}
+//# sourceMappingURL=VGeoLevel.d.ts.map

package/src/shade/renderer/geometry/virtual/build/level/VGeoLevel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoLevel.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoLevel.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,UAFU,wBAAwB,CAEpB;IAEd;;;;OAIG;IACH,QAFU,sBAAsB,CAEpB;CACf"}

package/src/shade/renderer/geometry/virtual/build/level/VGeoLevelOptions.d.ts

@@ -0,0 +1,59 @@
+/**
+ * How the round loop of {@link vgeo_build_levels} is allowed to behave.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoLevelOptions {
+    /**
+     * Clusters a group starts out holding. Grows when a round fails to make progress — small groups
+     * starve the simplifier (the locked perimeter dominates), large ones lock a big spatial
+     * footprint into LOD lockstep.
+     * @type {number}
+     */
+    group_size: number;
+    /**
+     * Fraction of a group's *clusters* the step above it should come to. The design's halving,
+     * stated as the thing the DAG is actually for.
+     *
+     * A triangle ratio is a means and this is the end, and asking directly is what keeps parents
+     * full: the simplifier is given the triangle count that many clusters hold, rather than half of
+     * whatever the children happened to contain. Where the children are already full the two are the
+     * same number. Where they are not, this asks for less destruction, because the reduction is
+     * available from packing the geometry better instead.
+     * @type {number}
+     */
+    simplification_ratio: number;
+    /**
+     * How much error a single round is allowed to span, as a multiple of the band's floor. `1` would
+     * admit only the exact minimum and turn every distinct error value into its own round; a large
+     * value admits the whole frontier every time and is the level sweep this replaced.
+     *
+     * Four, measured. On a 98k-triangle sphere against a full sweep: 31% fewer clusters merged into
+     * groups more than twice as coarse as themselves, and 8% fewer at four times, for one extra
+     * level. Two is tighter on the first count — 41% fewer — but costs fourteen levels, and every
+     * level is a page band and a dependent fetch on the way down.
+     * @type {number}
+     */
+    error_band_growth: number;
+    /**
+     * Least share of the frontier a round is allowed to work on, whatever the octave says.
+     *
+     * The octave alone offers no guarantee of progress: geometry whose error is spread thinly and
+     * continuously — a UV sphere, whose poles carry triangles a fraction of the size of its
+     * equator's — puts only a handful of clusters in any one octave, and the build inches forward a
+     * few merges per round. That is not merely slow, it is unbounded: `level_count` is a u8, and a
+     * round loop whose count scales with the cluster count rather than its logarithm will run out of
+     * levels on a real asset. Widening the band until it holds a fixed share of the frontier bounds
+     * the depth logarithmically, and costs error uniformity only where the octave had nothing.
+     * @type {number}
+     */
+    error_band_min_fraction: number;
+    /**
+     * Refuse to build past this many levels. `level_count` is a u8 in the container, and a build
+     * that has not converged by then has something else wrong with it.
+     * @type {number}
+     */
+    max_levels: number;
+}
+//# sourceMappingURL=VGeoLevelOptions.d.ts.map

package/src/shade/renderer/geometry/virtual/build/level/VGeoLevelOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoLevelOptions.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoLevelOptions.js"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;IACI;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;OAUG;IACH,sBAFU,MAAM,CAEW;IAE3B;;;;;;;;;;OAUG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;;;;;;OAWG;IACH,yBAFU,MAAM,CAEe;IAE/B;;;;OAIG;IACH,YAFU,MAAM,CAEC;CACpB"}

package/src/shade/renderer/geometry/virtual/build/level/VGeoLevelSummary.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What one band of the DAG came to.
+ *
+ * The counts are not a frontier size and do not have to fall monotonically: `cluster_count` is what
+ * the round of this index *created*, and a round merges a band of comparable error rather than the
+ * whole frontier, so a later round can produce fewer clusters than an earlier one — or more, when it
+ * finally reaches geometry that had been waiting.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoLevelSummary {
+    level: number;
+    /**
+     * Clusters the round of this index created.
+     * @type {number}
+     */
+    cluster_count: number;
+    /**
+     * Groups sitting in this band — the ones the round above consumed.
+     * @type {number}
+     */
+    group_count: number;
+    triangle_count: number;
+    vertex_count: number;
+    /**
+     * Smallest object-space `r_e` any cluster of this level carries.
+     * @type {number}
+     */
+    min_error: number;
+    /**
+     * Largest object-space `r_e` any cluster of this level carries. The root's is the ceiling for
+     * the whole asset; between two levels there is no ordering, for the same reason the counts have
+     * none.
+     * @type {number}
+     */
+    max_error: number;
+    /**
+     * Largest LOD-metric sphere radius at this level.
+     * @type {number}
+     */
+    max_sphere_radius: number;
+}
+//# sourceMappingURL=VGeoLevelSummary.d.ts.map

package/src/shade/renderer/geometry/virtual/build/level/VGeoLevelSummary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoLevelSummary.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/VGeoLevelSummary.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH;IACI,cAAU;IAEV;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB,uBAAmB;IACnB,qBAAiB;IAEjB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,mBAFU,MAAM,CAEM;CACzB"}

package/src/shade/renderer/geometry/virtual/build/level/vgeo_build_levels.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Build the whole DAG, from a source mesh to a single root.
+ *
+ * @param {VirtualGeometryMesh} mesh the normalized source; consumed, not copied
+ * @param {VGeoLevelOptions} options
+ * @returns {VGeoLevel[]} leaves first; the last level holds exactly one cluster, the root
+ */
+export function vgeo_build_levels(mesh: VirtualGeometryMesh, options: VGeoLevelOptions): VGeoLevel[];
+/**
+ * One cluster's geometry expressed against the frontier it came out of, which is what lets the next
+ * frontier be stitched from a mixture of freshly simplified clusters and untouched ones.
+ */
+export type VGeoContribution = {
+    positions: Float32Array;
+    /**
+     * local to {@link positions }
+     */
+    indices: Uint32Array;
+    /**
+     * ids in the mesh {@link topology } belongs to
+     */
+    local_vertex_ids: Uint32Array;
+    /**
+     * the same vertices, named in the frontier's mesh
+     */
+    source_vertex_ids: Uint32Array;
+    /**
+     * the mesh {@link local_vertex_ids } name vertices of, whose
+     * vertex data block holds their attributes
+     */
+    topology: BinaryTopology;
+};
+import { VirtualGeometryMesh } from "../mesh/VirtualGeometryMesh.js";
+import { VGeoLevel } from "./VGeoLevel.js";
+import { BinaryTopology } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+//# sourceMappingURL=vgeo_build_levels.d.ts.map

package/src/shade/renderer/geometry/virtual/build/level/vgeo_build_levels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_build_levels.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/level/vgeo_build_levels.js"],"names":[],"mappings":"AAqiDA;;;;;;GAMG;AACH,wCAJW,mBAAmB,8BAEjB,SAAS,EAAE,CA6KvB;;;;;;eAtgDa,YAAY;;;;aACZ,WAAW;;;;sBACX,WAAW;;;;uBACX,WAAW;;;;;cACX,cAAc;;oCA5KQ,gCAAgC;0BAD1C,gBAAgB;+BAjCI,yEAAyE"}