@woosh/meep-engine 3.27.0 → 3.28.0

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

@@ -0,0 +1,17 @@
+/**
+ * Put one page on the wavefront queue at its root node.
+ *
+ * Both passes that start a descent — the seed, from an instance's root page, and the reseed, from
+ * last frame's frontier — push the same four words and drop on the same bound, and both wrote it
+ * out. `shader_vgeo_cut_traverse` does not use this: it reserves a run for a whole workgroup's
+ * spill in one `atomicAdd` and writes into it, which is a different thing wearing the same words.
+ *
+ * Requires the importing shader to declare `params`, `queue_out` and `feedback`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_queue: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vgeo_cut_queue.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_queue.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,mCAFU,SAAS,CAsBQ;0BAtCD,0CAA0C"}

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

@@ -0,0 +1,39 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { chunk_vgeo_cut_claim } from "./chunk_vgeo_cut_claim.js";
+
+/**
+ * Put one page on the wavefront queue at its root node.
+ *
+ * Both passes that start a descent — the seed, from an instance's root page, and the reseed, from
+ * last frame's frontier — push the same four words and drop on the same bound, and both wrote it
+ * out. `shader_vgeo_cut_traverse` does not use this: it reserves a run for a whole workgroup's
+ * spill in one `atomicAdd` and writes into it, which is a different thing wearing the same words.
+ *
+ * Requires the importing shader to declare `params`, `queue_out` and `feedback`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_queue = CodeChunk.from(
+    //language=WGSL
+    `
+fn vg_queue_push_root(instance_slot: u32, page_row: u32) {
+    let slot = atomicAdd(&queue_out.count, 1u);
+
+    if (slot >= params.queue_capacity) {
+        vg_stat(${VGEO_CUT_STAT.QUEUE_DROPPED}u, 1u);
+
+        return;
+    }
+
+    let base = slot * 4u;
+
+    queue_out.elements[base] = instance_slot;
+    queue_out.elements[base + 1u] = page_row;
+    // node 0, which is how every page visit in this runtime begins
+    queue_out.elements[base + 2u] = 0u;
+    queue_out.elements[base + 3u] = 0u;
+}
+`, [chunk_vgeo_cut_claim]);

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

@@ -1 +1 @@
-{"version":3,"file":"shader_vgeo_cut_reseed.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_reseed.js"],"names":[],"mappings":"AAqLA,mDAIG;8BAtL2B,qCAAqC"}
+{"version":3,"file":"shader_vgeo_cut_reseed.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_reseed.js"],"names":[],"mappings":"AA6HA,mDAIG;8BA9H2B,qCAAqC"}

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

@@ -3,9 +3,9 @@ import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
 import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
 import { ComputeShader } from "../../../../shader/ComputeShader.js";
 import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_vgeo_cut_claim } from "./chunk_vgeo_cut_claim.js";
+import { chunk_vgeo_cut_queue } from "./chunk_vgeo_cut_queue.js";
 import { COLLECTION_U32_STRUCT_WRITE } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
-import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
-import { VGEO_FEEDBACK_OFFSET } from "../layout/VGEO_FEEDBACK_OFFSET.js";
 import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
 import { VGEO_INSTANCE_WORDS } from "../layout/VGEO_INSTANCE_WORDS.js";
 import { VGEO_PAGE_ROW_NONE } from "../layout/VGEO_PAGE_ROW_NONE.js";
@@ -70,46 +70,6 @@ resources.createGroup()
 const body = CodeChunk.from(
     //language=WGSL
     `
-/**
- * A field of a page's slot header. Indexed rather than read through the traversal's accessors,
- * because those come with a chunk that declares rather more than this pass binds.
- */
-fn vg_reseed_page_field(page_row: u32, field: u32) -> u32 {
-    return vg_arena[page_row * params.page_slot_words + field];
-}
-
-/**
- * The claim, and the touch that goes with it — the seed pass's, taken against a page row that came
- * off a bitmask rather than off a reference already resolved.
- */
-fn vg_reseed_claim(instance_base: u32, page_row: u32) -> bool {
-    let ordinal = vg_reseed_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.ORDINAL}u);
-
-    if (ordinal >= instances[instance_base + ${VGEO_INSTANCE_OFFSET.ORDINAL_CAPACITY}u]) {
-        return false;
-    }
-
-    let bit = instances[instance_base + ${VGEO_INSTANCE_OFFSET.CLAIM_BASE}u] + ordinal;
-
-    let word = bit >> 5u;
-
-    if (word >= params.claim_word_count) {
-        return false;
-    }
-
-    let mask = 1u << (bit & 31u);
-
-    if ((atomicOr(&claim[word], mask) & mask) != 0u) {
-        return false;
-    }
-
-    atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.PAGES}u], 1u);
-
-    atomicOr(&feedback[params.touch_bits_base + (page_row >> 5u)], 1u << (page_row & 31u));
-
-    return true;
-}
-
 @compute @workgroup_size(${VGEO_CUT_WORKGROUP_SIZE})
 fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
     let rows = params.frontier_word_count * 32u;
@@ -145,8 +105,8 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
      would reject the ordinal eventually, but the geometry row is the honest test and it is two
      reads of a header that is already in cache.
     */
-    if (vg_reseed_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW}u)
-        != vg_reseed_page_field(root_row, ${VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW}u)) {
+    if (vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW}u)
+        != vg_page_field(root_row, ${VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW}u)) {
         return;
     }
 
@@ -155,29 +115,13 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
      which is the LRU's whole input, and it is what stops a page reached both from the frontier and
      from a descent later in this same cut from being drawn twice.
     */
-    if (!vg_reseed_claim(instance_base, page_row)) {
+    if (!vg_claim_page(instance_base, page_row)) {
         return;
     }
 
-    let slot = atomicAdd(&queue_out.count, 1u);
-
-    if (slot >= params.queue_capacity) {
-        atomicAdd(
-            &feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.QUEUE_DROPPED}u], 1u
-        );
-
-        return;
-    }
-
-    let base = slot * 4u;
-
-    queue_out.elements[base] = instance_slot;
-    queue_out.elements[base + 1u] = page_row;
-    // node 0, which is how every page visit in this runtime begins
-    queue_out.elements[base + 2u] = 0u;
-    queue_out.elements[base + 3u] = 0u;
+    vg_queue_push_root(instance_slot, page_row);
 }
-`, []);
+`, [chunk_vgeo_cut_claim, chunk_vgeo_cut_queue]);
 
 export const shader_vgeo_cut_reseed = ComputeShader.from({
     label: "VGeo cut reseed",

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

@@ -1 +1 @@
-{"version":3,"file":"shader_vgeo_cut_seed.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_seed.js"],"names":[],"mappings":"AAuJA,iDAIG;8BAtJ2B,qCAAqC"}
+{"version":3,"file":"shader_vgeo_cut_seed.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_seed.js"],"names":[],"mappings":"AAsIA,iDAIG;8BArI2B,qCAAqC"}

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

@@ -5,12 +5,13 @@ import { COLLECTION_U32_STRUCT_READ } from "../../../../gpu_primitive/COLLECTION
 import { COLLECTION_U32_STRUCT_WRITE } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
 import { ComputeShader } from "../../../../shader/ComputeShader.js";
 import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_vgeo_cut_claim } from "./chunk_vgeo_cut_claim.js";
+import { chunk_vgeo_cut_queue } from "./chunk_vgeo_cut_queue.js";
 import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
 import { VGEO_FEEDBACK_OFFSET } from "../layout/VGEO_FEEDBACK_OFFSET.js";
 import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
 import { VGEO_INSTANCE_WORDS } from "../layout/VGEO_INSTANCE_WORDS.js";
 import { VGEO_PAGE_ROW_NONE } from "../layout/VGEO_PAGE_ROW_NONE.js";
-import { VGEO_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
 import { VGEO_CUT_PARAMS_STRUCT } from "./VGEO_CUT_PARAMS_STRUCT.js";
 import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
 
@@ -118,36 +119,18 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
      because it is also what stamps the root page as touched, and a root that never reports a touch
      is a root that ages out of the touch-LRU while it is on screen.
      */
-    let ordinal = vg_arena[
-        page_row * params.page_slot_words + ${VGEO_PAGE_ROW_OFFSET.ORDINAL}u
-    ];
-
-    let bit = claim_base + ordinal;
-
-    atomicOr(&claim[bit >> 5u], 1u << (bit & 31u));
-
-    atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.PAGES}u], 1u);
-
-    atomicOr(&feedback[params.touch_bits_base + (page_row >> 5u)], 1u << (page_row & 31u));
-
-    let slot = atomicAdd(&queue_out.count, 1u);
-
-    if (slot >= params.queue_capacity) {
-        atomicAdd(
-            &feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.QUEUE_DROPPED}u], 1u
-        );
-
-        return;
-    }
-
-    let base = slot * 4u;
-
-    queue_out.elements[base] = instance_slot;
-    queue_out.elements[base + 1u] = page_row;
-    queue_out.elements[base + 2u] = 0u;
-    queue_out.elements[base + 3u] = 0u;
+    /*
+     Through the shared claim, and by slice rather than by instance record: the claim base was
+     written to the instance record two lines above and is still in a register here, so the
+     _at form spares the read back. The claim cannot fail — the root is pinned and the capacity
+     bound was taken above — but it is the same code the descent and the reseed run, which is
+     the point of taking it rather than open-coding the three atomics.
+    */
+    vg_claim_page_at(claim_base, capacity, page_row);
+
+    vg_queue_push_root(instance_slot, page_row);
 }
-`, []);
+`, [chunk_vgeo_cut_claim, chunk_vgeo_cut_queue]);
 
 export const shader_vgeo_cut_seed = ComputeShader.from({
     label: "VGeo cut seed",

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

@@ -1 +1 @@
-{"version":3,"file":"shader_vgeo_cut_traverse.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_traverse.js"],"names":[],"mappings":"AAq5BA,qDAIG;8BAt5B2B,qCAAqC"}
+{"version":3,"file":"shader_vgeo_cut_traverse.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_traverse.js"],"names":[],"mappings":"AAu2BA,qDAIG;8BAx2B2B,qCAAqC"}

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

@@ -23,6 +23,7 @@ import { VGEO_QUEUE_TARGET_PARENT_BIT } from "../layout/VGEO_QUEUE_TARGET_PARENT
 import { VGEO_QUEUE_TARGET_GROUP_BIT } from "../layout/VGEO_QUEUE_TARGET_GROUP_BIT.js";
 import { VGEO_WANT_WORDS } from "../layout/VGEO_WANT_WORDS.js";
 import { chunk_vgeo_cut_access } from "./chunk_vgeo_cut_access.js";
+import { chunk_vgeo_cut_claim } from "./chunk_vgeo_cut_claim.js";
 import { VGEO_CUT_EXPAND } from "./VGEO_CUT_EXPAND.js";
 import { VGEO_CUT_FLAG_COARSEN } from "./VGEO_CUT_FLAG_COARSEN.js";
 import { VGEO_CUT_FLAG_CULL } from "./VGEO_CUT_FLAG_CULL.js";
@@ -237,58 +238,10 @@ fn vg_expand_none() -> VGExpand {
     return VGExpand(VG_EXPAND_NONE, 0u, 0u, 0u, 0u);
 }
 
-fn vg_stat(slot: u32, amount: u32) {
-    atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + slot], amount);
-}
-
-/**
- * Claim a page for one instance, and touch it if the claim was won.
- *
- * The claim is what makes "at most one draw record per (instance, cluster)" true, so an instance
- * whose slice of the bitmask does not fit is refused upstream rather than run unclaimed.
- */
-fn vg_claim_page(instance_base: u32, page_row: u32) -> bool {
-    let ordinal = vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.ORDINAL}u);
-
-    if (ordinal >= instances[instance_base + ${VGEO_INSTANCE_OFFSET.ORDINAL_CAPACITY}u]) {
-        return false;
-    }
-
-    let bit = instances[instance_base + ${VGEO_INSTANCE_OFFSET.CLAIM_BASE}u] + ordinal;
-
-    let word = bit >> 5u;
-
-    if (word >= params.claim_word_count) {
-        return false;
-    }
-
-    let mask = 1u << (bit & 31u);
-
-    if ((atomicOr(&claim[word], mask) & mask) != 0u) {
-        return false;
-    }
-
-    vg_stat(${VGEO_CUT_STAT.PAGES}u, 1u);
-
-    vg_touch_page(page_row);
-
-    return true;
-}
-
-/**
- * Record that this page was selected from this frame — design §6's eviction key.
- *
- * LRU on last-*touched*, never on last-wanted: stamping at fetch time freezes the stamp of exactly
- * the pages that are on screen and evicts them, which is the classic fallback-chain bug the virtual
- * texture cache already keys on touch to avoid.
- *
- * One bit per page row, because the feedback buffer is per frame rather than per invocation: the
- * bit dedups across every view and bucket of the frame and is the record the host reads, so
- * there is no list to fill and no touch a full list could lose.
- */
-fn vg_touch_page(page_row: u32) {
-    atomicOr(&feedback[params.touch_bits_base + (page_row >> 5u)], 1u << (page_row & 31u));
-}
+/*
+ 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.
+*/
 
 /**
  * Ask for the page a clamped cluster could not reach.
@@ -906,6 +859,7 @@ fn main(
 }
 `, [
     chunk_vgeo_cut_access,
+    chunk_vgeo_cut_claim,
     MESHLET_DEFINITION_STRUCT.declaration_chunk,
 ]);
 

package/src/shade/renderer/loader/gltf/load_gltf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load_gltf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/gltf/load_gltf.js"],"names":[],"mappings":"AAqIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,sDATW,YAAY,aAGZ,MAAM,iBACN,MAAM,kBACN;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAA;CAAC,QAgDlD;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,+BAdW,MAAM;IAEgB,YAAY;IAGN,KAAK;IACY,OAAO,GAApD,IAAI,MAAM,EAAE,IAAI,GAAC,IAAI,GAAC,WAAW,CAAC;IAGF,eAAe,GAA/C,qBAAqB;IAGpB,QAAQ,WAAW,CAAC,CA+0B/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCARW,MAAM;IAEgB,YAAY;IACN,KAAK;IACY,OAAO,GAApD,IAAI,MAAM,EAAE,IAAI,GAAC,IAAI,GAAC,WAAW,CAAC;IACF,eAAe,GAA/C,qBAAqB;IACnB,QAAQ,QAAQ,CAAC,CAU7B;4BAtlC2B,mBAAmB;yBAUtB,gBAAgB"}
+{"version":3,"file":"load_gltf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/loader/gltf/load_gltf.js"],"names":[],"mappings":"AAmIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,sDATW,YAAY,aAGZ,MAAM,iBACN,MAAM,kBACN;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAA;CAAC,QAgDlD;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,+BAdW,MAAM;IAEgB,YAAY;IAGN,KAAK;IACY,OAAO,GAApD,IAAI,MAAM,EAAE,IAAI,GAAC,IAAI,GAAC,WAAW,CAAC;IAGF,eAAe,GAA/C,qBAAqB;IAGpB,QAAQ,WAAW,CAAC,CA8zB/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCARW,MAAM;IAEgB,YAAY;IACN,KAAK;IACY,OAAO,GAApD,IAAI,MAAM,EAAE,IAAI,GAAC,IAAI,GAAC,WAAW,CAAC;IACF,eAAe,GAA/C,qBAAqB;IACnB,QAAQ,QAAQ,CAAC,CAU7B;4BApkC2B,mBAAmB;yBAStB,gBAAgB"}

package/src/shade/renderer/loader/gltf/load_gltf.js

@@ -9,7 +9,6 @@ import { clamp01 } from "../../../../core/math/clamp01.js";
 import { computeObjectHash } from "../../../../core/math/hash/computeObjectHash.js";
 import { inverseLerp } from "../../../../core/math/inverseLerp.js";
 import { objectDeepEquals } from "../../../../core/model/object/objectDeepEquals.js";
-import { number_format_by_thousands } from "../../../../core/primitives/numbers/number_format_by_thousands.js";
 import { AnimationInterpolationKind } from "../../../../engine/animation/clip/AnimationInterpolationKind.js";
 import { curve_from_track_data } from "../../../../engine/animation/clip/curve_from_track_data.js";
 import { AnimationCurve } from "../../../../engine/animation/curve/AnimationCurve.js";
@@ -35,7 +34,6 @@ import { ShadeImage } from "../../texture/source/ShadeImage.js";
 import { SceneBundle } from "../SceneBundle.js";
 import { SceneNode } from "../SceneNode.js";
 import { coalesce_array_duplicates } from "../../../../format/scene/gltf/coalesce_array_duplicates.js";
-import { fix_up_material_sides } from "./fix_up_material_sides.js";
 import { GLTF_COMPONENT_TYPE } from "../../../../format/scene/gltf/gltf_component_type.js";
 import { gltf_create_material } from "./gltf_create_material.js";
 import { gltf_create_texture } from "./gltf_create_texture.js";
@@ -1092,25 +1090,8 @@ export function load_gltf(url, { assetManager, scope, fileMap, texture_support }
         return bundle;
     }
 
-    /**
-     * @param {SceneBundle} bundle
-     */
-    function fix_scene_material_sidedness(bundle) {
-        const meshes = bundle.nodes.filter(node => node.geometry !== null);
-
-        const { geometries_modified: fixed_count, primitives_delta } = fix_up_material_sides(meshes);
-
-        if (fixed_count > 0) {
-            console.warn(`Fixed ${fixed_count} geometries in accordance with material sidedness. Primitives added: ${number_format_by_thousands(primitives_delta)}`);
-        }
-
-        return bundle;
-    }
-
-
     return load_gltf_document(url, { assetManager, scope, fileMap, texture_support })
         .then(process)
-        // .then(fix_scene_material_sidedness)
         // .then(prepare_lightmap)
         ;
 }

package/src/shade/renderer/material/chunk_material_draw_side.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What a {@link ShadeDrawSide} means once `Back` stopped being a pipeline state of its own.
+ *
+ * A back-sided material is a front-sided one drawn with its winding reversed: the vertex shader
+ * emits each triangle's corners in the opposite order and the fixed-function rasterizer, still
+ * culling back faces, keeps the surface's back. That is what lets both share a bucket — see
+ * `chunk_rasterization_material_bucket` — and it is the same mechanism a reflected instance uses,
+ * so the two compose by exclusive-or.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_material_draw_side: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_material_draw_side.d.ts.map

package/src/shade/renderer/material/chunk_material_draw_side.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_material_draw_side.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/material/chunk_material_draw_side.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,uCAFU,SAAS,CAqBb;0BAjCoB,iCAAiC"}

package/src/shade/renderer/material/chunk_material_draw_side.js

@@ -0,0 +1,34 @@
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ShadeDrawSide } from "./ShadeDrawSide.js";
+
+/**
+ * What a {@link ShadeDrawSide} means once `Back` stopped being a pipeline state of its own.
+ *
+ * A back-sided material is a front-sided one drawn with its winding reversed: the vertex shader
+ * emits each triangle's corners in the opposite order and the fixed-function rasterizer, still
+ * culling back faces, keeps the surface's back. That is what lets both share a bucket — see
+ * `chunk_rasterization_material_bucket` — and it is the same mechanism a reflected instance uses,
+ * so the two compose by exclusive-or.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_material_draw_side = CodeChunk.from(
+    //language=WGSL
+    `
+/**
+ * Whether the material asks for the back face, and therefore for reversed winding.
+ */
+fn material_draws_back_side( draw_side: u32 ) -> bool{
+    return draw_side == ${ShadeDrawSide.Back}u;
+}
+
+/**
+ * Whether the fragment is looking at the front of the surface.
+ *
+ * Not \`front_facing\`: that is the rasterizer's answer about the winding the vertex shader
+ * emitted, and a back-sided material emitted it reversed on purpose.
+ */
+fn material_fragment_faces_front( front_facing: bool, draw_side: u32 ) -> bool{
+    return front_facing != material_draws_back_side(draw_side);
+}
+`, [])

package/src/shade/renderer/material/standard/fragment_gbuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fragment_gbuffer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/fragment_gbuffer.js"],"names":[],"mappings":"AA6EA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAR6B,OAAO,GAAzB,MAAM;IACW,GAAG,EAApB,MAAM;IACW,MAAM,EAAvB,MAAM;IACW,OAAO,EAAxB,MAAM;IACW,QAAQ,EAAzB,MAAM;kBACN,SAAS,EAAE,GACT,SAAS,CAkOrB;AAjRD,oEAA2E;AAI3E,oIAEG;AASH,sIAEG;AAyQH,8CAIE;0BA1SwB,oCAAoC;4CAClB,sDAAsD;iCACjE,kCAAkC"}
+{"version":3,"file":"fragment_gbuffer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/fragment_gbuffer.js"],"names":[],"mappings":"AA8EA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAR6B,OAAO,GAAzB,MAAM;IACW,GAAG,EAApB,MAAM;IACW,MAAM,EAAvB,MAAM;IACW,OAAO,EAAxB,MAAM;IACW,QAAQ,EAAzB,MAAM;kBACN,SAAS,EAAE,GACT,SAAS,CAwOrB;AAvRD,oEAA2E;AAI3E,oIAEG;AASH,sIAEG;AA+QH,8CAIE;0BAhTwB,oCAAoC;4CAClB,sDAAsD;iCACjE,kCAAkC"}

package/src/shade/renderer/material/standard/fragment_gbuffer.js

@@ -6,6 +6,7 @@ import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
 import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../geometry/GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
 import { GEOMETRY_METADATA_STRUCT } from "../../geometry/GEOMETRY_METADATA_STRUCT.js";
 import { MESHLET_METADATA_STRUCT } from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { chunk_node3d_flags } from "../../scene/chunk_node3d_flags.js";
 import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
 import { RENDER_GLOBAL_MIP_BIAS } from "../../postprocess/taa/RENDER_GLOBAL_MIP_BIAS.js";
 import { chunk_barycentric_full } from "../../shader/chunk/geometry/triangle/chunk_barycentric_full.js";
@@ -225,7 +226,12 @@ fn main(
     );
 
     // Get tangent handedness from the provoking vertex (0).
-    let geometry_tangent_handedness = vertex_0.tangent.w;
+    // a reflection changes the tangent frame's handedness — see NODE3D_GLOBAL_FLAG_MIRRORED
+    let geometry_tangent_handedness = select(
+        vertex_0.tangent.w,
+        -vertex_0.tangent.w,
+        node3d_global_is_mirrored(node)
+    );
 
     let geometry_color = interpolate_attribute_3f32(
         vertex_0.color,
@@ -316,6 +322,7 @@ fn main(
         chunk_rgbe9995_encode,
         chunk_dither_color_8bit_triangle_noise,
         chunk_scene_database_access,
+        chunk_node3d_flags,
 
         ...extra_chunks,
     ]

package/src/shade/renderer/path_tracer/shader/chunk_sample_material_data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_sample_material_data.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_sample_material_data.js"],"names":[],"mappings":"AA8BA;;;GAGG;AACH,0CAFU,SAAS,CA8FlB;AAED,mDAsHC;0BA/NyB,oCAAoC"}
+{"version":3,"file":"chunk_sample_material_data.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_sample_material_data.js"],"names":[],"mappings":"AAiCA;;;GAGG;AACH,0CAFU,SAAS,CA8FlB;AAED,mDA+HC;0BAxOyB,oCAAoC"}

package/src/shade/renderer/path_tracer/shader/chunk_sample_material_data.js

@@ -1,4 +1,7 @@
 import { chunk_compute_normal_matrix_from_m4 } from "../../shader/chunk/geometry/mat4/chunk_compute_normal_matrix_from_m4.js";
+import {
+    chunk_mat4_linear_determinant
+} from "../../shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js";
 import { chunk_decode_tangent_normal } from "../../shader/chunk/geometry/normal/chunk_decode_tangent_normal.js";
 import { chunk_F_Hauber } from "../../shader/chunk/brdf/fresnel/chunk_F_Hauber.js";
 import {
@@ -201,7 +204,15 @@ fn sample_material_data(
         world_face_normal = -world_face_normal;
     }
 
-    let world_tangent_frame = build_orthonormal_matrix_nt(world_vertex_normal, vec4(world_tangent, geometry_tangent.w));
+    // a reflection changes the tangent frame's handedness — see NODE3D_GLOBAL_FLAG_MIRRORED.
+    // No node here: the tracer is handed a matrix, so the sign comes off the matrix.
+    let tangent_handedness = select(
+        geometry_tangent.w,
+        -geometry_tangent.w,
+        mat4_linear_determinant(instance_transform) < 0.0
+    );
+
+    let world_tangent_frame = build_orthonormal_matrix_nt(world_vertex_normal, vec4(world_tangent, tangent_handedness));
 
     var normal_sample = decode_tangent_normal(indirect_sample_texture(material.texture_normal, material.sampler_normal, uv));
     
@@ -238,6 +249,7 @@ fn sample_material_data(
         chunk_interpolate_attribute_3f32,
         chunk_interpolate_attribute_4f32,
         chunk_compute_normal_matrix_from_m4,
+        chunk_mat4_linear_determinant,
         chunk_build_orthonormal_matrix_nt,
         chunk_decode_tangent_normal,
         chunk_compute_triangle_face_normal,

package/src/shade/renderer/rasterize/bucket/construct_primitive_state.d.ts

@@ -9,9 +9,14 @@ export function construct_primitive_state(draw_mode: ShadeDrawMode, side: ShadeD
 /**
  * Named cull-mode lookup tables, keyed by {@link ShadeDrawSide }.
  *
- *  - `Standard` is the main-pass mapping: a `Front`-sided material renders its front face
- *    (cull back), `Back` renders its back face (cull front), `Double` renders both.
- *  - `Reversed` flips sided materials so the *back* face is what gets drawn. This is the
+ * `Front` and `Back` map to the same cull mode, because the winding they differ by is the
+ * vertex shader's to reverse — see `chunk_triangle_list_reverse_winding`. That is what lets
+ * them share a bucket, and it is why nothing here needs a fourth entry for the *instance's*
+ * handedness either.
+ *
+ *  - `Standard` is the main-pass mapping: a one-sided material renders the face its winding
+ *    presents (cull back), `Double` renders both.
+ *  - `Reversed` culls the other way, so the *back* face is what gets drawn. This is the
  *    standard "back-face shadow casting" / "front-face culling for shadow casters"
  *    technique — shadow callers select this policy so the surface written into the shadow
  *    map sits behind the lit surface, eliminating self-shadow acne on the lit side and
@@ -21,12 +26,21 @@ export function construct_primitive_state(draw_mode: ShadeDrawMode, side: ShadeD
 export type CullPolicy = Readonly<Record<number, GPUCullMode>>;
 export namespace CullPolicy {
     let Standard: Readonly<{
-        [x: number]: "none" | "back" | "front";
+        [x: number]: "none" | "back";
     }>;
     let Reversed: Readonly<{
-        [x: number]: "none" | "back" | "front";
+        [x: number]: "none" | "front";
     }>;
 }
+/**
+ * One {@link ShadeDrawSide} per rasterization bucket — the sides that still differ once `Back`
+ * is drawn as a reversed `Front`. Callers that enumerate buckets iterate this rather than the
+ * enum, so a `Back`-sided material is picked up by the `Front` pass rather than by a pass of
+ * its own that would repeat the whole expansion chain for it.
+ *
+ * @type {ReadonlyArray<ShadeDrawSide>}
+ */
+export const RASTERIZATION_BUCKET_SIDES: ReadonlyArray<ShadeDrawSide>;
 import { ShadeDrawMode } from "../../material/ShadeDrawMode.js";
 import { ShadeDrawSide } from "../../material/ShadeDrawSide.js";
 import { PrimitiveState } from "../../../descriptor/pipeline/render/PrimitiveState.js";

package/src/shade/renderer/rasterize/bucket/construct_primitive_state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"construct_primitive_state.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/construct_primitive_state.js"],"names":[],"mappings":"AAoCA;;;;;;GAMG;AACH,qDALW,aAAa,QACb,aAAa,gBACb,SAAS,OAAO,MAAM,cAAc,CAAC,GACnC,cAAc,CAgB1B;;;;;;;;;;;;;yBApCS,SAAS,OAAO,MAAM,cAAc,CAAC;;;;;;;;;8BApBjB,iCAAiC;8BACjC,iCAAiC;+BAFhC,uDAAuD"}
+{"version":3,"file":"construct_primitive_state.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/construct_primitive_state.js"],"names":[],"mappings":"AAsDA;;;;;;GAMG;AACH,qDALW,aAAa,QACb,aAAa,gBACb,SAAS,OAAO,MAAM,cAAc,CAAC,GACnC,cAAc,CAgB1B;;;;;;;;;;;;;;;;;;yBAjDS,SAAS,OAAO,MAAM,cAAc,CAAC;;;;;;;;;AAe/C;;;;;;;GAOG;AACH,yCAFU,cAAc,aAAa,CAAC,CAKnC;8BAnD2B,iCAAiC;8BACjC,iCAAiC;+BAFhC,uDAAuD"}

package/src/shade/renderer/rasterize/bucket/construct_primitive_state.js

@@ -10,9 +10,14 @@ const lut_topology = {
 /**
  * Named cull-mode lookup tables, keyed by {@link ShadeDrawSide}.
  *
- *  - `Standard` is the main-pass mapping: a `Front`-sided material renders its front face
- *    (cull back), `Back` renders its back face (cull front), `Double` renders both.
- *  - `Reversed` flips sided materials so the *back* face is what gets drawn. This is the
+ * `Front` and `Back` map to the same cull mode, because the winding they differ by is the
+ * vertex shader's to reverse — see `chunk_triangle_list_reverse_winding`. That is what lets
+ * them share a bucket, and it is why nothing here needs a fourth entry for the *instance's*
+ * handedness either.
+ *
+ *  - `Standard` is the main-pass mapping: a one-sided material renders the face its winding
+ *    presents (cull back), `Double` renders both.
+ *  - `Reversed` culls the other way, so the *back* face is what gets drawn. This is the
  *    standard "back-face shadow casting" / "front-face culling for shadow casters"
  *    technique — shadow callers select this policy so the surface written into the shadow
  *    map sits behind the lit surface, eliminating self-shadow acne on the lit side and
@@ -24,16 +29,29 @@ const lut_topology = {
 export const CullPolicy = {
     Standard: Object.freeze({
         [ShadeDrawSide.Front]:  'back',
-        [ShadeDrawSide.Back]:   'front',
+        [ShadeDrawSide.Back]:   'back',
         [ShadeDrawSide.Double]: 'none',
     }),
     Reversed: Object.freeze({
         [ShadeDrawSide.Front]:  'front',
-        [ShadeDrawSide.Back]:   'back',
+        [ShadeDrawSide.Back]:   'front',
         [ShadeDrawSide.Double]: 'none',
     }),
 };
 
+/**
+ * One {@link ShadeDrawSide} per rasterization bucket — the sides that still differ once `Back`
+ * is drawn as a reversed `Front`. Callers that enumerate buckets iterate this rather than the
+ * enum, so a `Back`-sided material is picked up by the `Front` pass rather than by a pass of
+ * its own that would repeat the whole expansion chain for it.
+ *
+ * @type {ReadonlyArray<ShadeDrawSide>}
+ */
+export const RASTERIZATION_BUCKET_SIDES = Object.freeze([
+    ShadeDrawSide.Front,
+    ShadeDrawSide.Double,
+]);
+
 /**
  *
  * @param {ShadeDrawMode} draw_mode

package/src/shade/renderer/rasterize/bucket/filter_materials_by_bucket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filter_materials_by_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/filter_materials_by_bucket.js"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,mDATW,eAAe,iBACf,MAAM,cACN,gBAAgB,aAChB,aAAa,aACb,aAAa,aACb,eAAe,SACf,MAAM,GACJ,MAAM,CAsClB;iCAjDgC,oCAAoC;8BAFvC,iCAAiC;8BACjC,iCAAiC"}
+{"version":3,"file":"filter_materials_by_bucket.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/bucket/filter_materials_by_bucket.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,mDATW,eAAe,iBACf,MAAM,cACN,gBAAgB,aAChB,aAAa,aACb,aAAa,aACb,eAAe,SACf,MAAM,GACJ,MAAM,CA4ClB;iCAxDgC,oCAAoC;8BAFvC,iCAAiC;8BACjC,iCAAiC"}

package/src/shade/renderer/rasterize/bucket/filter_materials_by_bucket.js

@@ -2,6 +2,7 @@ import { assert } from "../../../../core/assert.js";
 import { ShadeDrawMode } from "../../material/ShadeDrawMode.js";
 import { ShadeDrawSide } from "../../material/ShadeDrawSide.js";
 import { TransparencyMode } from "../../material/TransparencyMode.js";
+import { rasterization_material_bucket } from "../expand/bucket/chunk_rasterization_material_bucket.js";
 
 /**
  *
@@ -33,14 +34,20 @@ export function filter_materials_by_bucket(
 
     let material_count = 0;
 
+    // by bucket, not field by field: `Front` and `Back` are one bucket, so asking for either
+    // yields both, which is what puts them in a single pass
+    const bucket = rasterization_material_bucket(alpha_mode, draw_mode, draw_side);
+
     for (let i = 0; i < count; i++) {
         const material = materials[i];
 
-        if (
-            material.transparency_mode !== alpha_mode
-            || material.draw_mode !== draw_mode
-            || material.draw_side !== draw_side
-        ) {
+        const material_bucket = rasterization_material_bucket(
+            material.transparency_mode,
+            material.draw_mode,
+            material.draw_side
+        );
+
+        if (material_bucket !== bucket) {
             continue;
         }