@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_if_enabled.js

@@ -0,0 +1,56 @@
+import { graph_vgeo_expand_instances_to_meshlets } from "./graph_vgeo_expand_instances_to_meshlets.js";
+
+/**
+ * The seam, at a call site that does not want to know whether this scene has virtual geometry in it.
+ *
+ * Four rasterization paths call `graph_expand_meshes_to_meshlets`, and each of them gains exactly
+ * one line. That line has to be a no-op in the overwhelmingly common case — a scene of ordinary
+ * meshes — and it has to be a no-op *cheaply*: not a cut over an empty instance list, but no passes
+ * at all, because a wavefront is sixty-odd dispatches whose only output would be zero.
+ *
+ * The frame check is the second half of that. A runtime exists from the moment somebody enables it,
+ * but its feedback buffer exists only between `begin_frame` and `end_frame`; a path that runs
+ * outside a frame — a shadow view built before the main pass opens one, say — skips rather than
+ * writing into a resource that is not there.
+ *
+ * **And the graph check is the third.** `GPUSceneShadowmapContext` records through
+ * `graph_rasterize_scene_fast_raw`, which carries this seam, on a `FrameGraph` of its own — so a
+ * cube or tetra face inside an open frame would run a whole cut, at the *main camera's* projection
+ * scale, writing into a resource handle that belongs to another graph. Design §4 pins one cut per
+ * view and RUNTIME_PLAN §9 scopes shadow cuts out of v1; a graph that is not the one the frame was
+ * opened on is therefore not a graph this seam belongs in (REVIEW_LEDGER M13). When shadow views do
+ * get cuts, they get their own `begin_frame` and their own τ, and this check is what makes that a
+ * change rather than a discovery.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.input_meshes
+ * @param {number} options.output_meshlets
+ * @param {GPUViewContext} options.view
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} `output_meshlets`, cut records appended or not
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_vgeo_expand_if_enabled({
+                                                 graph,
+                                                 input_meshes,
+                                                 output_meshlets,
+                                                 view,
+                                                 limits,
+                                             }) {
+    const runtime = view?.scene?.virtual_geometry;
+
+    if (runtime === undefined || runtime.feedback === -1) {
+        return output_meshlets;
+    }
+
+    if (runtime.frame_graph !== graph) {
+        return output_meshlets;
+    }
+
+    return graph_vgeo_expand_instances_to_meshlets({
+        graph, input_meshes, output_meshlets, view, runtime, limits
+    });
+}

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.d.ts

@@ -0,0 +1,49 @@
+/**
+ * **The seam.**
+ *
+ * `VIRTUAL_GEOMETRY_DESIGN.md` §10 records M0's one engine-facing criterion as the piece that was
+ * never built: "nothing has yet entered the meshlet pipeline through a VG-shaped door". This is
+ * that door, and its whole shape is one call beside `graph_expand_meshes_to_meshlets`:
+ *
+ *     const meshlets = graph_expand_meshes_to_meshlets({ graph, input_meshes, ... });
+ *
+ *     graph_vgeo_expand_instances_to_meshlets({
+ *         graph, input_meshes, output_meshlets: meshlets, view, runtime, limits
+ *     });
+ *
+ * Three things make that enough, and none of them is an accident of this function:
+ *
+ * - **The instance list is already the right one.** Each expansion site is handed the visible
+ *   instances of one bucket in one HZB pass, and those sets are disjoint — the two-way filter
+ *   splits positive from maybe — so running a cut over each of them costs one cut per view in
+ *   total and no instance can be cut twice.
+ * - **A VG mesh expands to zero static meshlets.** `meshlets_count` is zero for a virtual geometry,
+ *   so `shader_meshes_to_meshlet_counts` contributes nothing for one without knowing what one is.
+ * - **The record type is unchanged.** The cut appends `MESHLET_DEFINITION_STRUCT` into the same
+ *   collection, naming rows of the same metadata pool, so the HZB meshlet filter, the material
+ *   bucket, the indirect draw and the G-buffer are untouched.
+ *
+ * What happens inside is design §7's cut pass: collect the VG instances into object space, scan
+ * their claim widths, seed one item per instance, and run the wavefront until it empties.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.input_meshes collection of visible mesh row indices
+ * @param {number} options.output_meshlets collection the cut appends into
+ * @param {GPUViewContext} options.view
+ * @param {GPUVirtualGeometryRuntime} options.runtime inside an open frame
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} `output_meshlets`, for chaining
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_vgeo_expand_instances_to_meshlets({ graph, input_meshes, output_meshlets, view, runtime, limits, }: {
+    graph: FrameGraph;
+    input_meshes: number;
+    output_meshlets: number;
+    view: GPUViewContext;
+    runtime: GPUVirtualGeometryRuntime;
+    limits: GPUCollectionLimits;
+}): number;
+//# sourceMappingURL=graph_vgeo_expand_instances_to_meshlets.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_vgeo_expand_instances_to_meshlets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH;IAX+B,KAAK;IACT,YAAY,EAA5B,MAAM;IACU,eAAe,EAA/B,MAAM;IACkB,IAAI;IACO,OAAO;IACb,MAAM;IACjC,MAAM,CAmRlB"}

package/src/shade/renderer/geometry/virtual/runtime/graph_vgeo_expand_instances_to_meshlets.js

@@ -0,0 +1,328 @@
+import { assert } from "../../../../../core/assert.js";
+import { noop } from "../../../../../core/function/noop.js";
+import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
+import {
+    graph_build_indirect_dispatch_command,
+    INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
+} from "../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { graph_prefix_scan_csdldf } from "../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { RasterizationCollectionType } from "../../../rasterize/expand/RasterizationCollectionType.js";
+import { shader_vgeo_cut_collect } from "./cut/shader_vgeo_cut_collect.js";
+import { shader_vgeo_cut_queue_prepare } from "./cut/shader_vgeo_cut_queue_prepare.js";
+import { shader_vgeo_cut_seed } from "./cut/shader_vgeo_cut_seed.js";
+import { shader_vgeo_cut_traverse } from "./cut/shader_vgeo_cut_traverse.js";
+import { VGEO_CUT_WORKGROUP_SIZE } from "./cut/VGEO_CUT_WORKGROUP_SIZE.js";
+import { VGEO_INSTANCE_WORDS } from "./layout/VGEO_INSTANCE_WORDS.js";
+import { VGEO_QUEUE_ITEM_WORDS } from "./layout/VGEO_QUEUE_ITEM_WORDS.js";
+
+/**
+ * **The seam.**
+ *
+ * `VIRTUAL_GEOMETRY_DESIGN.md` §10 records M0's one engine-facing criterion as the piece that was
+ * never built: "nothing has yet entered the meshlet pipeline through a VG-shaped door". This is
+ * that door, and its whole shape is one call beside `graph_expand_meshes_to_meshlets`:
+ *
+ *     const meshlets = graph_expand_meshes_to_meshlets({ graph, input_meshes, ... });
+ *
+ *     graph_vgeo_expand_instances_to_meshlets({
+ *         graph, input_meshes, output_meshlets: meshlets, view, runtime, limits
+ *     });
+ *
+ * Three things make that enough, and none of them is an accident of this function:
+ *
+ * - **The instance list is already the right one.** Each expansion site is handed the visible
+ *   instances of one bucket in one HZB pass, and those sets are disjoint — the two-way filter
+ *   splits positive from maybe — so running a cut over each of them costs one cut per view in
+ *   total and no instance can be cut twice.
+ * - **A VG mesh expands to zero static meshlets.** `meshlets_count` is zero for a virtual geometry,
+ *   so `shader_meshes_to_meshlet_counts` contributes nothing for one without knowing what one is.
+ * - **The record type is unchanged.** The cut appends `MESHLET_DEFINITION_STRUCT` into the same
+ *   collection, naming rows of the same metadata pool, so the HZB meshlet filter, the material
+ *   bucket, the indirect draw and the G-buffer are untouched.
+ *
+ * What happens inside is design §7's cut pass: collect the VG instances into object space, scan
+ * their claim widths, seed one item per instance, and run the wavefront until it empties.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {number} options.input_meshes collection of visible mesh row indices
+ * @param {number} options.output_meshlets collection the cut appends into
+ * @param {GPUViewContext} options.view
+ * @param {GPUVirtualGeometryRuntime} options.runtime inside an open frame
+ * @param {GPUCollectionLimits} options.limits
+ * @returns {number} `output_meshlets`, for chaining
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function graph_vgeo_expand_instances_to_meshlets({
+                                                           graph,
+                                                           input_meshes,
+                                                           output_meshlets,
+                                                           view,
+                                                           runtime,
+                                                           limits,
+                                                       }) {
+    assert.defined(graph, 'graph');
+    assert.isNonNegativeInteger(input_meshes, 'input_meshes');
+    assert.isNonNegativeInteger(output_meshlets, 'output_meshlets');
+    assert.defined(runtime, 'runtime');
+    assert.notEqual(runtime.feedback, -1, 'runtime.feedback — begin_frame must have run');
+
+    const scene = view.scene;
+    const pool = runtime.pool;
+
+    graph.push_scope("virtual geometry cut");
+
+    const instance_capacity = Math.max(1, limits.get_limit(RasterizationCollectionType.Meshes));
+
+    /*
+     What this site was handed, before any pass of it is recorded. Both numbers bound an append in
+     the kernel, and both are properties of a collection rather than of the frame — `meshlet_capacity`
+     was a constant 1 << 20 against a collection whose engine default is 2e5, so the draw-record
+     bound was five times the buffer it was checking.
+     */
+    runtime.declare_collections({
+        instance_capacity,
+        meshlet_capacity: Math.max(1, limits.get_limit(RasterizationCollectionType.Meshlets)),
+    });
+
+    // ----- collect: which of these instances are virtual, and where is the camera in each one -----
+
+    const collect_command = graph_build_indirect_dispatch_command(
+        graph, input_meshes, VGEO_CUT_WORKGROUP_SIZE
+    );
+
+    const collect_data = {};
+
+    const collect_pass = graph.add("collect vg instances", collect_data, (data, resources, context) => {
+        shader_vgeo_cut_collect.dispatchIndirect({
+            encoder: context.encoder,
+            command: resources.get(data.command),
+            bindings: {
+                params: runtime.params_buffer,
+                camera: view.camera.buffer,
+                scene_database: scene.scene_database_buffer,
+                geometries: scene.geometries.buffer_metadata,
+                vg_geometries: pool.buffer_geometries,
+                input_meshes: resources.get(data.input_meshes),
+                instances: resources.get(data.instances),
+                claim_widths: resources.get(data.claim_widths),
+                feedback: resources.get(data.feedback),
+            }
+        });
+    });
+
+    collect_data.command = collect_pass.read(collect_command);
+    collect_data.input_meshes = collect_pass.read(input_meshes);
+
+    collect_data.instances = collect_pass.create("vg instances", BufferResourceDescriptor.from(
+        instance_capacity * VGEO_INSTANCE_WORDS * 4,
+        GPUBufferUsage.STORAGE,
+        0, 16
+    ));
+
+    collect_data.claim_widths = collect_pass.create("vg claim widths", BufferResourceDescriptor.from(
+        16 + instance_capacity * 4,
+        GPUBufferUsage.STORAGE,
+        0, 16
+    ));
+
+    // the first writer of the frame's counters, so the version chain starts here
+    collect_data.feedback = collect_pass.write(runtime.feedback);
+
+    /*
+     The scan turns each instance's claim width into the first bit of its slice. It is the same
+     primitive and the same shape `graph_expand_meshes_to_meshlets` uses to size its own output, and
+     for the same reason: a dense base per element, computed on the device, out of counts only the
+     device knows.
+     */
+    const prefix_sums = graph_prefix_scan_csdldf({
+        graph,
+        data: collect_data.claim_widths,
+        element_max_count: instance_capacity,
+    });
+
+    // ----- seed: one item per instance, naming its root page's node 0 -----
+
+    const seed_command = graph_build_indirect_dispatch_command(
+        graph, prefix_sums, VGEO_CUT_WORKGROUP_SIZE
+    );
+
+    const queue_descriptor = BufferResourceDescriptor.from(
+        16 + runtime.queue_capacity * VGEO_QUEUE_ITEM_WORDS * 4,
+        GPUBufferUsage.STORAGE,
+        0, 16
+    );
+
+    const seed_data = {};
+
+    const seed_pass = graph.add("seed vg wavefront", seed_data, (data, resources, context) => {
+        shader_vgeo_cut_seed.dispatchIndirect({
+            encoder: context.encoder,
+            command: resources.get(data.command),
+            bindings: {
+                params: runtime.params_buffer,
+                vg_arena: pool.buffer_arena,
+                prefix_sums: resources.get(data.prefix_sums),
+                instances: resources.get(data.instances),
+                queue_out: resources.get(data.queue_out),
+                claim: resources.get(data.claim),
+                feedback: resources.get(data.feedback),
+            }
+        });
+    });
+
+    seed_data.command = seed_pass.read(seed_command);
+    seed_data.prefix_sums = seed_pass.read(prefix_sums);
+    seed_data.instances = seed_pass.write(collect_data.instances);
+
+    /*
+     Cleared per invocation, and that is not an optimization that could be traded away: each
+     expansion site sees a different instance set, so a claim carried over from the previous site
+     would make every page of this one look already visited. The stamps in the feedback buffer are
+     the opposite case — per frame, shared, and not cleared here.
+     */
+    seed_data.claim = seed_pass.create("vg claim", BufferResourceDescriptor.empty(
+        runtime.claim_word_capacity * 4,
+        GPUBufferUsage.STORAGE
+    ));
+
+    seed_data.feedback = seed_pass.write(collect_data.feedback);
+    seed_data.queue_out = seed_pass.create("vg queue a", queue_descriptor);
+
+    const spare_spawn = graph.add("vg queue b", {}, noop);
+
+    /*
+     The two queues ping-pong, so *which* of them holds work is not a property of either buffer —
+     it moves every iteration. Carrying the roles rather than the buffers is what makes the tail
+     pass below correct at any `max_iterations`: it was written as `queue_a`, which is the produced
+     queue only when the iteration count is even, and the default of 64 is (REVIEW_LEDGER M8).
+     */
+    let ready_queue = seed_data.queue_out;
+    let spare_queue = spare_spawn.create("vg queue b", queue_descriptor);
+
+    let claim = seed_data.claim;
+    let feedback = seed_data.feedback;
+    let meshlets = output_meshlets;
+
+    const instances = seed_data.instances;
+
+    // ----- the wavefront -----
+
+    for (let iteration = 0; iteration < runtime.max_iterations; iteration++) {
+        const prepare_data = {};
+
+        const prepare_pass = graph.add(
+            `vg prepare ${iteration}`, prepare_data, (data, resources, context) => {
+                shader_vgeo_cut_queue_prepare.dispatch({
+                    encoder: context.encoder,
+                    bindings: {
+                        params: runtime.params_buffer,
+                        queue_ready: resources.get(data.queue_ready),
+                        queue_spare: resources.get(data.queue_spare),
+                        command: resources.get(data.command),
+                        feedback: resources.get(data.feedback),
+                    }
+                });
+            }
+        );
+
+        /*
+         Both queues, because this pass does two things at once and they belong together: it clamps
+         what the last wavefront produced — the count runs past capacity by design, and handing
+         *that* to an indirect dispatch would dispatch lanes over the end of a pooled buffer — and
+         it empties the one the next wavefront will write. There is exactly one moment when neither
+         wavefront is touching either, and this is it.
+         */
+        const ready = prepare_data.queue_ready = prepare_pass.write(ready_queue);
+        const spare = prepare_data.queue_spare = prepare_pass.write(spare_queue);
+
+        feedback = prepare_data.feedback = prepare_pass.write(feedback);
+
+        prepare_data.command = prepare_pass.create(
+            `vg command ${iteration}`, INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
+        );
+
+        const traverse_data = {};
+
+        const traverse_pass = graph.add(
+            `vg traverse ${iteration}`, traverse_data, (data, resources, context) => {
+                shader_vgeo_cut_traverse.dispatchIndirect({
+                    encoder: context.encoder,
+                    command: resources.get(data.command),
+                    bindings: {
+                        params: runtime.params_buffer,
+                        vg_lookup: pool.buffer_lookup,
+                        vg_arena: pool.buffer_arena,
+                        instances: resources.get(data.instances),
+                        queue_in: resources.get(data.queue_in),
+                        queue_out: resources.get(data.queue_out),
+                        claim: resources.get(data.claim),
+                        feedback: resources.get(data.feedback),
+                        out_meshlets: resources.get(data.out_meshlets),
+                    }
+                });
+            }
+        );
+
+        traverse_data.command = traverse_pass.read(prepare_data.command);
+        traverse_data.instances = traverse_pass.read(instances);
+        traverse_data.queue_in = traverse_pass.read(ready);
+
+        const produced = traverse_data.queue_out = traverse_pass.write(spare);
+
+        claim = traverse_data.claim = traverse_pass.write(claim);
+        feedback = traverse_data.feedback = traverse_pass.write(feedback);
+        meshlets = traverse_data.out_meshlets = traverse_pass.write(meshlets);
+
+        // what this wavefront produced is what the next one consumes, and the drained one is spare
+        ready_queue = produced;
+        spare_queue = ready;
+    }
+
+    /*
+     One more prepare, for its counters alone. The loop above records a fixed number of
+     prepare/traverse pairs and the queue can still hold work when the last of them finishes — a
+     subtree never descended, which is a hole rather than a coarse stand-in, and the one degradation
+     §4.5 admits. Nothing recorded it. This pass leaves the outstanding count in
+     `VGEO_CUT_STAT.QUEUE_REMAINING`, and the dispatch command it also produces is simply not used.
+
+     `ready_queue` and not `queue_a`: the prepare pass reports the count of `queue_ready` and
+     *zeroes* `queue_spare`, so binding the drained queue as ready would report a count of work
+     already done and destroy the count of the work that was left. Which buffer holds which
+     alternates per iteration, so the roles are carried through the loop rather than named here.
+     */
+    const tail_data = {};
+
+    const tail_pass = graph.add("vg queue tail", tail_data, (data, resources, context) => {
+        shader_vgeo_cut_queue_prepare.dispatch({
+            encoder: context.encoder,
+            bindings: {
+                params: runtime.params_buffer,
+                queue_ready: resources.get(data.queue_ready),
+                queue_spare: resources.get(data.queue_spare),
+                command: resources.get(data.command),
+                feedback: resources.get(data.feedback),
+            }
+        });
+    });
+
+    tail_data.queue_ready = tail_pass.write(ready_queue);
+    tail_data.queue_spare = tail_pass.write(spare_queue);
+    tail_data.command = tail_pass.create("vg command tail", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
+
+    feedback = tail_data.feedback = tail_pass.write(feedback);
+
+    /*
+     Every expansion of this frame writes into one feedback buffer, so the next one has to start
+     from the version this one produced rather than from the version `begin_frame` created — and so
+     does the readback. The graph catches the alternative outright, which is the best kind of
+     invariant to have.
+     */
+    runtime.publish_feedback(feedback);
+
+    graph.pop_scope();
+
+    return meshlets;
+}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CLUSTER_ROW_OFFSET.d.ts

@@ -0,0 +1,10 @@
+export namespace VGEO_CLUSTER_ROW_OFFSET {
+    let SELF_SPHERE: number;
+    let PARENT_SPHERE: number;
+    let SELF_ERROR: number;
+    let PARENT_ERROR: number;
+    let CHILD_PAGE_INDEX: number;
+    let CHILD_GROUP: number;
+    let CHILD_REF: number;
+}
+//# sourceMappingURL=VGEO_CLUSTER_ROW_OFFSET.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CLUSTER_ROW_OFFSET.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_CLUSTER_ROW_OFFSET.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CLUSTER_ROW_OFFSET.js"],"names":[],"mappings":""}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CLUSTER_ROW_OFFSET.js

@@ -0,0 +1,51 @@
+/**
+ * Word offsets within one cluster row of the **selection buffer** — the VG-owned table the cut pass
+ * reads and nothing else writes.
+ *
+ * `VIRTUAL_GEOMETRY_DESIGN.md` §7 says why it exists rather than the cut reading the meshlet
+ * metadata pool: freed slices of that pool hold garbage, and it carries no error pairs at all.
+ *
+ * The row is the cut rule's operands and its edge, and nothing more. Culling bounds
+ * (`bounds_sphere`, `aabb`) are deliberately absent — the `aabb` becomes the meshlet metadata's
+ * `bounds_box` at install and is culled downstream by the HZB filter, so carrying it here would be
+ * a second copy read by nobody.
+ *
+ * `child_page_index` is **resolved at install**: a `SAME_PAGE` reference stores the owning page's
+ * own global index, so the kernel's lookup path is uniform and there is no `SAME_PAGE` branch
+ * anywhere in it. A leaf stores {@link VGEO_NO_CHILD_PAGE}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_CLUSTER_ROW_OFFSET = {
+    /**
+     * The LOD-metric sphere of the step that created this cluster, `cx cy cz r`.
+     */
+    SELF_SPHERE: 0,
+    /**
+     * The LOD-metric sphere of the step that consumed it; a root's duplicates its own.
+     */
+    PARENT_SPHERE: 4,
+    /**
+     * Object-space `r_e`. Zero exactly for leaves, and `project((s, 0)) ≡ 0` unconditionally.
+     */
+    SELF_ERROR: 8,
+    /**
+     * `+∞` for the one root.
+     */
+    PARENT_ERROR: 9,
+    /**
+     * Global page index of the child group's page, or {@link VGEO_NO_CHILD_PAGE}.
+     */
+    CHILD_PAGE_INDEX: 10,
+    /**
+     * Group index within that page.
+     */
+    CHILD_GROUP: 11,
+    /**
+     * Index into the *owning* page's child table. A want names it, which is what lets the CPU
+     * resolve a byte range without a directory — and what names the page the want was discovered
+     * *through*, which `VGEO_FORMAT.md` §10 wants for in-flight pinning.
+     */
+    CHILD_REF: 12,
+};

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CLUSTER_ROW_WORDS.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Words in one selection-buffer cluster row.
+ *
+ * Not rounded up to a power of two. At the million resident clusters
+ * `VIRTUAL_GEOMETRY_DESIGN.md` §4 targets, thirteen words is 52 MB and sixteen is 64 — and the
+ * addressing is a multiply either way, so the padding would buy nothing and cost twelve megabytes.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_CLUSTER_ROW_WORDS: number;
+//# sourceMappingURL=VGEO_CLUSTER_ROW_WORDS.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CLUSTER_ROW_WORDS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_CLUSTER_ROW_WORDS.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CLUSTER_ROW_WORDS.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qCAFU,MAAM,CAEyB"}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CLUSTER_ROW_WORDS.js

@@ -0,0 +1,12 @@
+/**
+ * Words in one selection-buffer cluster row.
+ *
+ * Not rounded up to a power of two. At the million resident clusters
+ * `VIRTUAL_GEOMETRY_DESIGN.md` §4 targets, thirteen words is 52 MB and sixteen is 64 — and the
+ * addressing is a multiply either way, so the padding would buy nothing and cost twelve megabytes.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_CLUSTER_ROW_WORDS = 13;

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT.d.ts

@@ -0,0 +1,17 @@
+export namespace VGEO_CUT_STAT {
+    let DRAWN: number;
+    let CLAMPED: number;
+    let CLAMPED_ON_ACTIVATION: number;
+    let ITEMS: number;
+    let PAGES: number;
+    let CLUSTERS_TESTED: number;
+    let CULLED_FRUSTUM: number;
+    let CULLED_LOD: number;
+    let MESHLETS_DROPPED: number;
+    let WANTS_DROPPED: number;
+    let QUEUE_DROPPED: number;
+    let INSTANCES_DROPPED: number;
+    let WAVEFRONTS: number;
+    let QUEUE_REMAINING: number;
+}
+//# sourceMappingURL=VGEO_CUT_STAT.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_CUT_STAT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT.js"],"names":[],"mappings":""}

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT.js

@@ -0,0 +1,99 @@
+/**
+ * Counter slots in the feedback buffer's stat block — the cut telling the truth about itself.
+ *
+ * Design §10 asks M1 for "selection cost measured"; these are what measures it, and several are
+ * correctness signals rather than performance ones. {@link CLAMPED} at rest above zero means the
+ * cut on screen is standing in for something finer, and the want list says what to fetch to fix it.
+ * Any `*_DROPPED` above zero means a bound was hit, and every bound in this runtime is arranged to
+ * degrade the same way — coarser or missing, never doubled.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const VGEO_CUT_STAT = {
+    /**
+     * Clusters that passed the whole predicate and emitted a draw record.
+     */
+    DRAWN: 0,
+    /**
+     * Clusters drawn above the threshold because the page holding their refinement is not
+     * VRAM-resident.
+     */
+    CLAMPED: 1,
+    /**
+     * Of those, the ones whose child page **is** here and whose child group is 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. So this is not a second streaming frontier — it is how much of the coarseness on
+     * screen is the activation rule holding a group back rather than bandwidth.
+     */
+    CLAMPED_ON_ACTIVATION: 2,
+    /**
+     * Queue items popped, summed over every iteration.
+     */
+    ITEMS: 3,
+    /**
+     * Page visits that won their claim — the cut's real page working set, per view.
+     */
+    PAGES: 4,
+    /**
+     * Cluster rows the predicate was evaluated against.
+     */
+    CLUSTERS_TESTED: 5,
+    /**
+     * Subtrees discarded by the frustum, at a node rather than at a cluster.
+     */
+    CULLED_FRUSTUM: 6,
+    /**
+     * Subtrees discarded because nothing under them could satisfy `project(parent) > tau`.
+     */
+    CULLED_LOD: 7,
+    /**
+     * Draw records that did not fit the meshlet collection.
+     */
+    MESHLETS_DROPPED: 8,
+    /**
+     * Wants that did not fit their list.
+     */
+    WANTS_DROPPED: 9,
+    /**
+     * Queue items that did not fit the next wavefront.
+     *
+     * Unlike the others this one **can** cost correctness: a dropped item is a subtree never
+     * descended, and the parent that would have stood in over it was not drawn either — so it is a
+     * hole rather than a coarse stand-in. It is bounded by the queue's size, which is a host-side
+     * option, and it is the one counter worth alarming on.
+     */
+    QUEUE_DROPPED: 10,
+    /**
+     * Instances refused because their slice of the claim bitmask did not fit.
+     *
+     * Refusing the instance is the point. An instance run *without* a claim visits every page once
+     * per parent page that reaches it — 82 of 91 pages on a measured sphere have more than one
+     * parent — and draws its whole cut that many times over, which reads as corrupt geometry rather
+     * than as a missing instance.
+     */
+    INSTANCES_DROPPED: 11,
+    /**
+     * Wavefronts that actually ran — one per iteration whose queue was not empty.
+     *
+     * The descent is a fixed number of indirect dispatches, of zero workgroups once the work runs
+     * out, so this is the only way to know how deep it went. RUNTIME_PLAN §4.7 measures depth at
+     * about 48 against a default budget of 64; this reaching the budget means the measurement no
+     * longer holds for the asset on screen.
+     */
+    WAVEFRONTS: 12,
+    /**
+     * Items still queued when the descent stopped.
+     *
+     * **The one degradation that costs a hole rather than coarseness**, and it was silent. §4.5
+     * promises every bound "degrades in one direction" and §4.7 promises the exhaustion is
+     * recorded; neither counter existed (REVIEW_LEDGER M8, D1).
+     *
+     * Written by the prepare pass with a plain store rather than an add, so the last prepare of the
+     * frame — one extra, recorded after the wavefront loop for exactly this — leaves behind the
+     * number that was outstanding at the end.
+     */
+    QUEUE_REMAINING: 13,
+};

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT_COUNT.d.ts

@@ -0,0 +1,9 @@
+/**
+ * How many counters {@link VGEO_CUT_STAT} names.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {number}
+ */
+export const VGEO_CUT_STAT_COUNT: number;
+//# sourceMappingURL=VGEO_CUT_STAT_COUNT.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT_COUNT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_CUT_STAT_COUNT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/layout/VGEO_CUT_STAT_COUNT.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,kCAFU,MAAM,CAEsB"}