@woosh/meep-engine 3.58.0 → 3.59.0

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_descent.js

@@ -0,0 +1,467 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { VGEO_GROUP_ROW_OFFSET } from "../layout/VGEO_GROUP_ROW_OFFSET.js";
+import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
+import { VGEO_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
+import { VGEO_PARENT_ROW_OFFSET } from "../layout/VGEO_PARENT_ROW_OFFSET.js";
+import { chunk_vgeo_cut_claim } from "./chunk_vgeo_cut_claim.js";
+import { chunk_vgeo_cut_rule } from "./chunk_vgeo_cut_rule.js";
+import { chunk_vgeo_cut_want } from "./chunk_vgeo_cut_want.js";
+import { VGEO_CUT_FLAG_COARSEN } from "./VGEO_CUT_FLAG_COARSEN.js";
+import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
+
+/**
+ * The virtual-geometry cut's descent — design §7's pass, as a descent that lives inside one dispatch — for every
+ * cut: the camera's (`shader_vgeo_cut_traverse`) and a box cut's. A kernel is this chunk with the rule's two culls
+ * and what taking a cluster means to it:
+ *
+ * ```wgsl
+ * fn vg_cut_sphere_outside(instance_base: u32, sphere: vec4<f32>) -> bool
+ * fn vg_cut_box_outside(instance_base: u32, lower: vec3<f32>, upper: vec3<f32>) -> bool
+ * fn vg_cut_take(instance_base: u32, page_row: u32, verdict: VGVerdict)
+ * ```
+ *
+ * `vg_cut_take` is called for a cluster in the cut, a stand-in's too (`VGEO_CUT_VERDICT` TAKE, CLAMP, HELD); the
+ * descent itself counts the stand-ins and wants what a clamp could not reach.
+ *
+ * ## The rule
+ *
+ * A cluster is in the cut iff
+ *
+ * > `own group selectable AND project(parent) > tau AND (project(self) <= tau OR child group not
+ * > selectable)`
+ *
+ * which is {@link chunk_vgeo_cut_rule}'s.
+ *
+ * ## The shape
+ *
+ * The loop over depth is *inside* this kernel: a dispatch is a spill generation rather than a level
+ * of the descent. Depth is what a cut costs. Measured on a 28M-face container at tau = 1 on a 4090:
+ * the descent converges at **39 levels**, carrying 15,027 items — an average frontier of 385 items,
+ * or **six workgroups of 64 on a 128-SM part** — and an empty prepare/traverse pair costs 3.9 us
+ * whatever it contains. Page depth grows like log2(triangles), so a dispatch per level gets *worse*
+ * with better assets and no better with a faster GPU.
+ *
+ * What a lane cannot do is wait for another workgroup: WebGPU guarantees no forward progress across
+ * workgroups, so persistent threads over an MPMC queue — Nanite's answer — is unbounded waiting.
+ * What a lane *can* do is cooperate with the other lanes of its own subgroup, and that is enough:
+ *
+ * - Every lane executes its item and says how many children it produced. No lane walks its own
+ *   subtree while its neighbours idle; production is a **count**, at constant cost.
+ * - `subgroupExclusiveAdd` over those counts numbers the wave's whole production densely. The first
+ *   `subgroup_size` of them are taken back into the wave's own lanes — perfectly packed, one child
+ *   per lane, whoever produced them — and the descent takes another step without touching memory.
+ * - Everything past a full wave **spills** to the global queue under one `atomicAdd`. Breadth the
+ *   wave cannot hold becomes work for other waves rather than a serial loop inside this one.
+ *
+ * So the number of dispatches is the number of spill generations, and the narrow top of the DAG —
+ * twenty levels that move between 1 and 120 items and draw nothing — is one wave taking twenty
+ * steps in registers.
+ *
+ * This is Karis' "Variable sized work" (graphicrants, 2026-03) with its groupshared scatter
+ * removed. That scatter needs HLSL's `GroupMemoryBarrier()` — memory ordering with no execution
+ * sync, sound because a wave is in lockstep — and WGSL has no memory-only workgroup barrier.
+ * `workgroupBarrier` synchronizes execution as well, which pins every subgroup of the workgroup to
+ * the same number of steps and is a deadlock the moment they disagree; `workgroupUniformLoad` is
+ * that same control barrier plus a load, and what it returns is one value uniform across the
+ * workgroup, which is the opposite of the per-lane read a scatter is made of.
+ * `vg_child_owner` finds each item's producer by binary search over the same prefix sums
+ * instead: `log2(subgroup_size)` shuffles, no workgroup memory and no barrier anywhere in this
+ * file, so nothing here needs the workgroup to agree on anything.
+ *
+ * ## What WGSL will not let this do
+ *
+ * Every loop around a subgroup operation needs a **uniform trip count**, and nothing launders one —
+ * not `subgroupAdd`, not `subgroupMax`, not even `subgroupBroadcastFirst`, which launders a value
+ * for a use but not for control flow. Nor may such a loop carry a non-uniform `break`, `continue`
+ * or `return`. So the descent runs `params.descent_steps` times and masks; a wave that drains its
+ * subtree early pays the remaining steps at about ten instructions each rather than leaving. That
+ * makes `descent_steps` a tuning knob rather than a safety bound, and
+ * `VGEO_CUT_STAT.QUEUE_REMAINING` is what says when it is set too low.
+ *
+ * Divergence *inside* the loop is free: Tint models reconvergence, so a non-uniform `if` that opens
+ * and closes taints nothing after it, and the spill's per-lane loop is fine because it contains no
+ * subgroup operation of its own.
+ *
+ * ## One lane per cluster
+ *
+ * A leaf produces one item per cluster of its groups and the wave packs them, so what bounds a
+ * lane's work is the packing rather than a chunk size, and consecutive lanes read consecutive
+ * cluster rows instead of striding over runs of them.
+ *
+ * ## Why page-granular dedup is enough, and why it is necessary
+ *
+ * The page DAG is many-parented — 82 of 91 pages of a measured 98k sphere have more than one parent
+ * — so an undeduped descent would visit a page once per parent and draw its whole cut that many
+ * times. The claim is one bit per (instance, resident page), which is affordable. Cluster-granular
+ * dedup is what this avoids: the resident cluster count is exactly the number design §4 is trying
+ * not to pay per frame.
+ *
+ * Visiting a cluster the descent "should not" have reached costs only the test, because the
+ * predicate is a pure function of the row and gives the same answer from every direction. Missing
+ * one costs a hole. That asymmetry is the whole design:
+ *
+ * - **No cluster is drawn twice.** It is evaluated once per page visit, and the claim makes that at
+ *   most once per instance.
+ * - **No cluster the flat rule would draw is missed.** If `project(C.parent) > tau`, then any
+ *   parent cluster `P` of `C`'s group has `project(P.self) = project(C.parent) > tau` — every
+ *   cluster of a group shares the consuming step's sphere and error — and monotonicity gives
+ *   `project(P.parent) >= project(P.self)`, so `P` satisfies the predicate's first half and by
+ *   induction its page is visited. `P` fails `project(self) <= tau`, so it either enqueues `C`'s
+ *   page or clamps, and it clamps only when `C`'s group is not selectable, in which case `C` must
+ *   not be drawn. Neither cull intervenes: a node's sphere contains `P.parent_sphere` and its
+ *   `max_parent_error` is at least `P.parent_error`, so the LOD cull cannot fire, and both culls
+ *   are on bounds of `P`'s whole subtree, which contains `C` — so they fire only where `C` is
+ *   outside the cut's volume anyway.
+ *
+ * Note that the per-cluster culls do **not** have to agree across a group's several parents, and
+ * nothing here asks them to. A group is claimed and descended once, by whichever parent reaches it
+ * first; a parent that culls itself out simply is not that one. What each test promises is about
+ * its own subtree and nothing else.
+ *
+ * Descent crosses a page boundary by producing the child page's **node 0**: uniform items, one
+ * kernel, no special case for "entering a page". `SAME_PAGE` needs no special case either, because
+ * the CPU resolved it to this page's own index at install, so it looks up a page that is trivially
+ * resident and falls through to the only question it was really asking — is that group selectable.
+ *
+ * ## Bounds
+ *
+ * Every append is checked and every overflow is counted, and they all degrade in one direction —
+ * coarser or missing, never doubled. The exception worth knowing is `QUEUE_DROPPED`: a dropped item
+ * is a subtree never descended, and the parent that would have stood in over it was not drawn
+ * either, so that one is a hole.
+ *
+ * Requires the importing shader to declare `params`, `vg_lookup`, `vg_arena`, `vg_want_stamps`,
+ * `instances`, `queue_in`, `queue_out`, `claim` and `feedback`, and the three hooks.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_descent = CodeChunk.from(
+    //language=WGSL
+    `
+/*
+ vg_stat, vg_claim_page and vg_touch_page are chunk_vgeo_cut_claim's — the seed and reseed
+ passes take the same three, which is why they are no longer written here.
+*/
+
+/**
+ * One cluster: the rule's verdict taken, wanted, claimed, or the walk up it elects.
+ */
+fn vg_visit_cluster(
+    instance_base: u32,
+    page_row: u32,
+    group: u32,
+    member: u32
+) -> VGExpand {
+    let verdict = vg_cut_cluster(instance_base, page_row, group, member);
+
+    if (verdict.kind == VG_VERDICT_BELOW) {
+        /*
+         The decision is group-uniform, so the group's first member can carry the election alone.
+         That is an election with nothing to communicate: the other members reach the same answer
+         and defer to the same lane.
+        */
+        let group_row_here = vg_group_row(page_row, group);
+
+        let parent_count = vg_arena[group_row_here + ${VGEO_GROUP_ROW_OFFSET.PARENT_COUNT}u];
+
+        if ((params.flags & ${VGEO_CUT_FLAG_COARSEN}u) == 0u || member != 0u
+            || parent_count == 0u) {
+            return vg_expand_none();
+        }
+
+        return VGExpand(
+            VG_EXPAND_PARENTS,
+            parent_count,
+            page_row,
+            vg_arena[group_row_here + ${VGEO_GROUP_ROW_OFFSET.PARENT_FIRST}u],
+            0u
+        );
+    }
+
+    if (verdict.kind == VG_VERDICT_TAKE) {
+        vg_cut_take(instance_base, page_row, verdict);
+        return vg_expand_none();
+    }
+
+    if (verdict.kind == VG_VERDICT_CLAMP) {
+        vg_cut_take(instance_base, page_row, verdict);
+
+        vg_stat(${VGEO_CUT_STAT.CLAMPED}u, 1u);
+
+        vg_want(
+            page_row,
+            verdict.child_ref,
+            verdict.child_page_index,
+            instances[instance_base + ${VGEO_INSTANCE_OFFSET.LOOKUP_WORD_OFFSET}u],
+            verdict.projected
+        );
+
+        return vg_expand_none();
+    }
+
+    if (verdict.kind == VG_VERDICT_HELD) {
+        vg_cut_take(instance_base, page_row, verdict);
+
+        vg_stat(${VGEO_CUT_STAT.CLAMPED}u, 1u);
+        vg_stat(${VGEO_CUT_STAT.CLAMPED_ON_ACTIVATION}u, 1u);
+
+        return vg_expand_none();
+    }
+
+    if (verdict.kind != VG_VERDICT_REFINE || !vg_claim_page(instance_base, verdict.child_page_row)) {
+        // nothing, or another lane, or another parent of this page, got there first
+        return vg_expand_none();
+    }
+
+    return VGExpand(VG_EXPAND_PAGE, 1u, verdict.child_page_row, 0u, 0u);
+}
+
+/**
+ * One entry of a page's parent rows: the page holding that parent, claimed and queued.
+ *
+ * The mirror of the descent's page crossing, and deliberately page-granular like it. The
+ * entry names a cluster as well, and this ignores it: a page reached from any direction is
+ * evaluated whole, the rule is a pure function of each row, and visiting a cluster the walk
+ * did not need costs only the test. What the cluster half of the entry is for is the
+ * refine-side election of CUT_PLAN_2026_09_14 section 3, which is section 7.6's work.
+ *
+ * A parent that is not resident stops the walk rather than clamping. There is nothing to
+ * clamp *to* -- the surface this lane is standing on is below the cut and is not drawn -- so
+ * the honest answer is that this instance cannot be served incrementally this frame, which
+ * is the fallback section 4 already defines and section 7.6 wires up.
+ */
+fn vg_visit_parent(instance_base: u32, page_row: u32, entry: u32) -> VGExpand {
+    if (entry >= vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.PARENT_ENTRY_COUNT}u)) {
+        return vg_expand_none();
+    }
+
+    let row = vg_parent_base(page_row) + entry * VG_PARENT_ROW_WORDS;
+
+    let parent_page_index = vg_arena[row + ${VGEO_PARENT_ROW_OFFSET.PAGE_INDEX}u];
+
+    if (parent_page_index == VG_NO_CHILD_PAGE) {
+        return vg_expand_none();
+    }
+
+    let lookup_base = instances[instance_base + ${VGEO_INSTANCE_OFFSET.LOOKUP_WORD_OFFSET}u];
+
+    let parent_page_row = vg_lookup[lookup_base + parent_page_index];
+
+    if (parent_page_row == VG_PAGE_ROW_NONE) {
+        return vg_expand_none();
+    }
+
+    if (!vg_claim_page(instance_base, parent_page_row)) {
+        // this page is already in this instance's cut, from above or from another parent
+        return vg_expand_none();
+    }
+
+    return VGExpand(VG_EXPAND_PAGE, 1u, parent_page_row, 0u, 0u);
+}
+
+/**
+ * Execute whatever this lane is holding.
+ */
+fn vg_execute(item: VGItem, holding: bool) -> VGExpand {
+    if (!holding) {
+        return vg_expand_none();
+    }
+
+    vg_stat(${VGEO_CUT_STAT.ITEMS}u, 1u);
+
+    let instance_base = item.instance_slot * VG_INSTANCE_WORDS;
+
+    if ((item.visit & VG_QUEUE_GROUP_BIT) != 0u) {
+        return vg_visit_cluster(
+            instance_base, item.page_row, item.visit & ~VG_QUEUE_GROUP_BIT, item.aux
+        );
+    }
+
+    if ((item.visit & VG_QUEUE_PARENT_BIT) != 0u) {
+        return vg_visit_parent(
+            instance_base, item.page_row, item.visit & ~VG_QUEUE_PARENT_BIT
+        );
+    }
+
+    return vg_cut_node(instance_base, item.page_row, item.visit);
+}
+
+/**
+ * Which lane of the wave produced the item at \`index\` of its densely numbered production.
+ *
+ * The owner is the **largest** lane whose base is at or below the index — largest, because a lane
+ * that produced nothing repeats its neighbour's base, and a repeat sits at the start of the next
+ * producer's run rather than the end of the previous one. The bases are non-decreasing, so this is
+ * a binary search, and \`span\` starts at a builtin so the loop's trip count is uniform.
+ */
+fn vg_child_owner(first: u32, index: u32, lane_count: u32) -> u32 {
+    var owner = 0u;
+    var span = lane_count;
+
+    while (span > 1u) {
+        let step_half = span >> 1u;
+        let mid = owner + step_half;
+
+        // branchless: a non-uniform if around the next iteration's shuffle would not compile
+        owner = select(owner, mid, subgroupShuffle(first, mid) <= index);
+
+        span = span - step_half;
+    }
+
+    return owner;
+}
+
+fn vg_queue_write(slot: u32, item: VGItem) {
+    if (slot >= params.queue_capacity) {
+        vg_stat(${VGEO_CUT_STAT.QUEUE_DROPPED}u, 1u);
+        return;
+    }
+
+    let base = slot * 4u;
+
+    queue_out.elements[base] = item.instance_slot;
+    queue_out.elements[base + 1u] = item.page_row;
+    queue_out.elements[base + 2u] = item.visit;
+    queue_out.elements[base + 3u] = item.aux;
+}
+
+@compute @workgroup_size(${VGEO_CUT_WORKGROUP_SIZE})
+fn main(
+    @builtin(global_invocation_id) global_id: vec3<u32>,
+    @builtin(subgroup_size) lane_count: u32,
+    @builtin(subgroup_invocation_id) lane_index: u32,
+) {
+    let slot = global_id.x;
+
+    /*
+     The queue's count against what the queue holds. \`shader_vgeo_cut_queue_prepare\` runs
+     immediately before every dispatch of this kernel and stores exactly this clamp back, so the
+     bound is already there — but it was the *read* below that carried it here and not the predicate
+     that decides whether a lane executes, and those two have to agree. A lane held past capacity
+     reads the clamped index, which is the last item of the queue: it would execute a duplicate of
+     an item another lane is already holding, and a cluster visited twice from two lanes is two draw
+     records for one surface. That is the one failure the claim bitmask and the own-group term are
+     both arranged to prevent, so the predicate does not get to be the looser of the two.
+    */
+    let queue_count = min(queue_in.count, params.queue_capacity);
+
+    /*
+     One per dispatch that had work, which is one per spill generation rather than one per level of
+     the descent: the depth is inside this kernel. Reaching params.descent_steps with items still
+     held is what QUEUE_REMAINING reports, and nothing else can.
+    */
+    if (slot == 0u && queue_count > 0u) {
+        vg_stat(${VGEO_CUT_STAT.WAVEFRONTS}u, 1u);
+    }
+
+    var holding = slot < queue_count;
+
+    let base = slot * 4u;
+
+    /*
+     Read unconditionally and mask the result. A branch here would be a non-uniform if, which is
+     harmless on its own — but every lane must reach every subgroup operation below, and a lane that
+     returned early is a lane the shuffles are not allowed to read.
+    */
+    let in_bounds = min(base, params.queue_capacity * 4u - 4u);
+
+    var item = VGItem(
+        queue_in.elements[in_bounds],
+        queue_in.elements[in_bounds + 1u],
+        queue_in.elements[in_bounds + 2u],
+        queue_in.elements[in_bounds + 3u]
+    );
+
+    for (var step = 0u; step < params.descent_steps; step = step + 1u) {
+        let expand = vg_execute(item, holding);
+
+        let first = subgroupExclusiveAdd(expand.count);
+        let total = subgroupAdd(expand.count);
+
+        // ----- what this wave keeps: one child per lane, densely packed, whoever produced it -----
+
+        let owner = vg_child_owner(first, lane_index, lane_count);
+
+        let kept = vg_child(
+            subgroupShuffle(item.instance_slot, owner),
+            VGExpand(
+                subgroupShuffle(expand.kind, owner),
+                0u,
+                subgroupShuffle(expand.page_row, owner),
+                subgroupShuffle(expand.first, owner),
+                subgroupShuffle(expand.span, owner)
+            ),
+            lane_index - subgroupShuffle(first, owner)
+        );
+
+        // ----- what it cannot hold: spilled, packed, under one reservation for the whole wave -----
+
+        let mine_first = max(first, lane_count);
+        let mine_last = max(first + expand.count, lane_count);
+
+        let spill_count = mine_last - mine_first;
+
+        let spill_offset = subgroupExclusiveAdd(spill_count);
+        let spill_total = subgroupAdd(spill_count);
+
+        /*
+         Elected *before* the branch, so the branch carries no subgroup operation of its own and is
+         free to be non-uniform — which lets a wave with nothing to spill skip the reservation
+         outright. An atomic on the queue head is a global round trip; a descent step that keeps
+         everything it produced is otherwise register work, and would spend more reserving zero
+         slots than on the step.
+        */
+        let spill_elected = subgroupElect();
+
+        var reserved = 0u;
+
+        if (spill_elected && spill_total > 0u) {
+            reserved = atomicAdd(&queue_out.count, spill_total);
+        }
+
+        // after the branch closes, which Tint permits: it models reconvergence
+        let spill_base = subgroupBroadcastFirst(reserved) + spill_offset;
+
+        for (var i = 0u; i < spill_count; i = i + 1u) {
+            vg_queue_write(spill_base + i, vg_child(
+                item.instance_slot, expand, mine_first - first + i
+            ));
+        }
+
+        item = kept;
+        holding = lane_index < total;
+    }
+
+    /*
+     Whatever is still held has not been executed, so it goes back to the queue rather than being
+     dropped. This is the descent handing its unfinished frontier to the next dispatch, and at
+     lane_count items per wave it is the common case rather than an overflow path.
+    */
+    let tail_count = select(0u, 1u, holding);
+
+    let tail_offset = subgroupExclusiveAdd(tail_count);
+    let tail_total = subgroupAdd(tail_count);
+
+    let tail_elected = subgroupElect();
+
+    var tail_reserved = 0u;
+
+    // as above: a wave holding nothing does not reserve
+    if (tail_elected && tail_total > 0u) {
+        tail_reserved = atomicAdd(&queue_out.count, tail_total);
+    }
+
+    let tail_base = subgroupBroadcastFirst(tail_reserved) + tail_offset;
+
+    if (holding) {
+        vg_queue_write(tail_base, item);
+    }
+}
+`, [
+    chunk_vgeo_cut_rule,
+    chunk_vgeo_cut_want,
+    chunk_vgeo_cut_claim,
+]);

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_instance.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What every cut's collect writes of an instance record (`VGEO_INSTANCE_OFFSET`), whatever its view:
+ *
+ * ```wgsl
+ * fn vg_instance_stretch(global: mat4x4<f32>) -> vec2<f32>
+ * fn vg_instance_record(mesh_index: u32, geometry_row: u32, capacity: u32) -> u32
+ * fn vg_store(base: u32, field: u32, value: f32)
+ * ```
+ *
+ * `vg_instance_stretch` is the largest and smallest stretch the transform applies to any direction,
+ * or zero for a transform that flattens the instance. `vg_instance_record` reserves a record under
+ * `capacity`, writes the instance's mesh row and its geometry's root page, lookup and claim width,
+ * and returns the record's first word, or {@link VG_INSTANCE_RECORD_NONE} when the records are full.
+ * What the instance is cut against (its eye, projection and volume) is the collect's own.
+ *
+ * Requires the importing shader to declare `instances`, `claim_widths` and `vg_geometries`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_instance: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_instance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vgeo_cut_instance.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_instance.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sCAFU,SAAS,CAoFc;0BA7GP,0CAA0C"}

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_instance.js

@@ -0,0 +1,111 @@
+import { chunk_mat3_singular_values } from "../../../../shader/chunk/geometry/mat3/chunk_mat3_singular_values.js";
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { VGEO_GEOMETRY_ROW_OFFSET } from "../layout/VGEO_GEOMETRY_ROW_OFFSET.js";
+import { VGEO_GEOMETRY_ROW_WORDS } from "../layout/VGEO_GEOMETRY_ROW_WORDS.js";
+import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
+import { VGEO_INSTANCE_WORDS } from "../layout/VGEO_INSTANCE_WORDS.js";
+
+/**
+ * What every cut's collect writes of an instance record (`VGEO_INSTANCE_OFFSET`), whatever its view:
+ *
+ * ```wgsl
+ * fn vg_instance_stretch(global: mat4x4<f32>) -> vec2<f32>
+ * fn vg_instance_record(mesh_index: u32, geometry_row: u32, capacity: u32) -> u32
+ * fn vg_store(base: u32, field: u32, value: f32)
+ * ```
+ *
+ * `vg_instance_stretch` is the largest and smallest stretch the transform applies to any direction,
+ * or zero for a transform that flattens the instance. `vg_instance_record` reserves a record under
+ * `capacity`, writes the instance's mesh row and its geometry's root page, lookup and claim width,
+ * and returns the record's first word, or {@link VG_INSTANCE_RECORD_NONE} when the records are full.
+ * What the instance is cut against (its eye, projection and volume) is the collect's own.
+ *
+ * Requires the importing shader to declare `instances`, `claim_widths` and `vg_geometries`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_instance = CodeChunk.from(
+    //language=WGSL
+    `
+const VG_INSTANCE_RECORD_NONE = 0xffffffffu;
+
+fn vg_store(base: u32, field: u32, value: f32) {
+    instances[base + field] = bitcast<u32>(value);
+}
+
+fn vg_instance_stretch(global: mat4x4<f32>) -> vec2<f32> {
+    let linear = mat3x3<f32>(global[0].xyz, global[1].xyz, global[2].xyz);
+
+    let stretch = mat3_singular_values(linear);
+
+    /*
+     A singular transform — an instance scaled to zero in some direction. mat4_inverse says so
+     by dividing by a zero determinant, and the NaN that comes back makes **every** comparison
+     in vg_project and the culls fail open, so one zero-scaled instance draws its whole
+     resident set. It covers nothing, so dropping it is also the right picture.
+
+     **The determinant is the test, and sigma_min alone was not.** This guard used to be
+     !(sigma_min > 0) on its own, and the closed form's own doc offered sigma_min as a
+     degeneracy test — true in exact arithmetic, false in f32. An axis-aligned flatten makes
+     MtM exactly diagonal and takes the exact branch, which does return zero. A ROTATED one
+     takes the trigonometric branch, where sigma_min is a difference of nearly equal numbers
+     with an absolute error of about sqrt(eps_f32) * sigma_max — so it came back near 1e-4
+     rather than 0, and thirty-six of forty rotated zero-scale instances passed this line with
+     a NaN eye and a projection scale of 6.2e10 behind it (REVIEW_LEDGER M3, re-review
+     2026-09-12). The determinant does not have that problem: a flattened instance has one
+     exactly-zero column at every rotation, and every term of the expansion carries a factor
+     from it. It is also, exactly, the number mat4_inverse divides by.
+
+     sigma_min is kept beside it because it is not redundant: a matrix that is merely very
+     close to singular has a non-zero determinant and can still report sigma_min as zero, and
+     a ratio of the two would then be an infinity rather than a correction.
+
+     Both written as !(x > 0) rather than x <= 0 so that a NaN — which compares false against
+     everything — is caught rather than passed through.
+     */
+    if (!(abs(determinant(linear)) > 0.0) || !(stretch.y > 0.0)) {
+        return vec2<f32>(0.0);
+    }
+
+    return stretch;
+}
+
+fn vg_instance_record(mesh_index: u32, geometry_row: u32, capacity: u32) -> u32 {
+    let slot = atomicAdd(&claim_widths.count, 1u);
+
+    if (slot >= capacity) {
+        /*
+         Dropping the instance is the safe direction: a cut run without a claim slice draws every
+         page once per parent that reaches it.
+         */
+        return VG_INSTANCE_RECORD_NONE;
+    }
+
+    let base = slot * ${VGEO_INSTANCE_WORDS}u;
+
+    let geometry_base = geometry_row * ${VGEO_GEOMETRY_ROW_WORDS}u;
+
+    /*
+     The geometry's ordinal capacity rather than its resident page count is the claim width,
+     because ordinals come from a free list and can be sparse; a bitmask indexed by a sparse
+     ordinal has to be as wide as the highest one handed out.
+     */
+    let ordinal_capacity = vg_geometries[
+        geometry_base + ${VGEO_GEOMETRY_ROW_OFFSET.ORDINAL_CAPACITY}u
+    ];
+
+    instances[base + ${VGEO_INSTANCE_OFFSET.MESH_INDEX}u] = mesh_index;
+    instances[base + ${VGEO_INSTANCE_OFFSET.ROOT_PAGE_ROW}u] =
+        vg_geometries[geometry_base + ${VGEO_GEOMETRY_ROW_OFFSET.ROOT_PAGE_ROW}u];
+    instances[base + ${VGEO_INSTANCE_OFFSET.LOOKUP_WORD_OFFSET}u] =
+        vg_geometries[geometry_base + ${VGEO_GEOMETRY_ROW_OFFSET.LOOKUP_WORD_OFFSET}u];
+    instances[base + ${VGEO_INSTANCE_OFFSET.ORDINAL_CAPACITY}u] = ordinal_capacity;
+    instances[base + ${VGEO_INSTANCE_OFFSET.CLAIM_BASE}u] = 0u;
+
+    claim_widths.elements[slot] = ordinal_capacity;
+
+    return base;
+}
+`, [chunk_mat3_singular_values]);

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_rule.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The cut's rule, once, for every traversal that selects clusters: the camera's wavefront
+ * (`shader_vgeo_cut_traverse`) and a box cut. A cluster is in the cut iff
+ *
+ * > `own group selectable AND project(parent) > tau AND (project(self) <= tau OR child group not
+ * > selectable)`
+ *
+ * which is design §4's per-cluster form together with its first term. That term is load-bearing
+ * and §4 states the rule without it: a group that is resident but not yet selectable has clusters
+ * satisfying the rest of the rule while their coarse stand-in is drawn over the same surface, a few
+ * microns apart, with the depth buffer choosing between them. That reads as corrupt geometry rather
+ * than as a missing page, which is what makes it hard to attribute and worth stating first.
+ *
+ * ```wgsl
+ * fn vg_cut_node(instance_base: u32, page_row: u32, node: u32) -> VGExpand
+ * fn vg_cut_cluster(instance_base: u32, page_row: u32, group: u32, member: u32) -> VGVerdict
+ * fn vg_child(instance_slot: u32, expand: VGExpand, k: u32) -> VGItem
+ * ```
+ *
+ * The rule is evaluated in an instance's own space, against the instance record
+ * (`VGEO_INSTANCE_OFFSET`): its eye, projection constant and distance weight for `vg_project`,
+ * its lookup base for the child pages. What it is culled against is the traversal's, so the
+ * importing shader defines both culls, each a test of a bound of the whole subtree under it:
+ *
+ * ```wgsl
+ * fn vg_cut_sphere_outside(instance_base: u32, sphere: vec4<f32>) -> bool
+ * fn vg_cut_box_outside(instance_base: u32, lower: vec3<f32>, upper: vec3<f32>) -> bool
+ * ```
+ *
+ * What a traversal does with a verdict is its own: the camera draws, wants and claims; a box cut
+ * takes the cluster's triangles.
+ *
+ * Requires the importing shader to declare `params`, `vg_lookup`, `vg_arena`, `instances` and
+ * `feedback`. Claiming a page is the traversal's: the camera's takes `chunk_vgeo_cut_claim`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_rule: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_rule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vgeo_cut_rule.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_rule.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,kCAFU,SAAS,CA8V8B;0BAnZvB,0CAA0C"}