@woosh/meep-engine 3.26.0 → 3.28.0

package/src/shade/renderer/scene/GPUSceneContext.d.ts

@@ -57,6 +57,14 @@ export class GPUSceneContext {
      * @returns {GPUVirtualGeometryRuntime|undefined}
      */
     get virtual_geometry(): GPUVirtualGeometryRuntime;
+    /**
+     * @returns {VGeoResidency|undefined}
+     */
+    get virtual_geometry_residency(): VGeoResidency;
+    /**
+     * @returns {VGeoFeedbackLoop|undefined}
+     */
+    get virtual_geometry_feedback(): VGeoFeedbackLoop;
     /**
      * Give this scene a virtual-geometry runtime, sharing the meshlet pool with everything else it
      * draws.
@@ -65,11 +73,20 @@ export class GPUSceneContext {
      * records naming rows of the same metadata buffer a static mesh's meshlets live in, so nothing
      * downstream of the expansion has to know which kind of geometry it is looking at.
      *
+     * And the residency and the feedback loop with it, so that an engine host gets the whole
+     * streaming loop by enabling virtual geometry rather than by wiring four objects itself
+     * (REVIEW_LEDGER U1): `register` a container with {@link virtual_geometry_residency}, call
+     * {@link virtual_geometry_feedback}'s `read` once a frame after the last rasterization path,
+     * and every page after the root arrives because the cut asked for it.
+     *
      * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and
-     *     {@link GPUVirtualGeometryRuntime}
+     *     {@link GPUVirtualGeometryRuntime}, except for `residency`
+     * @param {VGeoResidencyOptions} [options.residency] every knob of both residency tiers
      * @returns {GPUVirtualGeometryRuntime}
      */
-    enable_virtual_geometry(options?: any): GPUVirtualGeometryRuntime;
+    enable_virtual_geometry(options?: {
+        residency?: VGeoResidencyOptions;
+    }): GPUVirtualGeometryRuntime;
     /**
      * @returns {GPUAnimationManager}
      */
@@ -183,6 +200,9 @@ import { GPULightCollection } from "../light/GPULightCollection.js";
 import { GPULightProbeVolume } from "../global_illumination/lpv/GPULightProbeVolume.js";
 import { GPUInstancesAccelerationStructure } from "./GPUInstancesAccelerationStructure.js";
 import { GPUVirtualGeometryRuntime } from "../geometry/virtual/runtime/GPUVirtualGeometryRuntime.js";
+import { VGeoResidency } from "../geometry/virtual/runtime/VGeoResidency.js";
+import { VGeoFeedbackLoop } from "../geometry/virtual/runtime/VGeoFeedbackLoop.js";
+import { VGeoResidencyOptions } from "../geometry/virtual/runtime/VGeoResidencyOptions.js";
 import { GPUAnimationManager } from "../animation/GPUAnimationManager.js";
 import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
 import { GPUMeshSkinningContext } from "../animation/skinning/GPUMeshSkinningContext.js";

package/src/shade/renderer/scene/GPUSceneContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUSceneContext.js"],"names":[],"mappings":"AA8DA;;;;;;;;;GASG;AACH;IA0II;;;;OAIG;IACH,sBAHW,eAAe,SACf,KAAK,EAiCf;IA5KD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAGV;;OAEG;IACH,sBAFU,cAAc,CAEH;IASrB;;;OAGG;IACH,mBAEC;IAOD,uCAEC;IAQD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,8CAEC;IAOD;;;OAGG;IACH,8CAEC;IAsGD;;OAEG;IACH,kDAEC;IAED;;;;;;;;;;;OAWG;IACH,wCAFa,yBAAyB,CAoBrC;IAED;;OAEG;IACH,6CAEC;IAYD;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,uCAEC;IAED;;;;;;;;;;;OAWG;IACH,uCAUC;IAED,+BAUC;IAED;;;;;;;;;;OAUG;IACH,yBAEC;IAED;;;;;OAKG;IACH,sCAMC;IAOD;;;;;;;OAOG;IACH,8EAEC;IA0BD;;;;OAIG;IACH,cAqEC;IAED;;;OAGG;IACH,YAFW,eAAe,QA0BzB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAHW,sBAAsB,cACtB,MAAM,QAuBhB;IAoCD,gBAYC;IAIL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;8BAxmBY,OAAO,uBAAuB,EAAE,eAAe;iCAC/C,OAAO,mCAAmC,EAAE,kBAAkB;iCAC9D,OAAO,mCAAmC,EAAE,kBAAkB;4BAC9D,OAAO,8BAA8B,EAAE,aAAa;8BACpD,OAAO,iDAAiD,EAAE,eAAe;+BAtBvD,iDAAiD;sBAI1D,YAAY;oCADE,uCAAuC;mCADxC,gCAAgC;oCAD/B,mDAAmD;kDAIrC,wCAAwC;0CAVhD,0DAA0D;oCAGhE,qCAAqC;4BAC7C,gCAAgC;uCAOrB,iDAAiD;6BAM3D,wBAAwB;wCADb,mCAAmC;uCAdpC,wCAAwC"}
+{"version":3,"file":"GPUSceneContext.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/GPUSceneContext.js"],"names":[],"mappings":"AAqEA;;;;;;;;;GASG;AACH;IA0II;;;;OAIG;IACH,sBAHW,eAAe,SACf,KAAK,EAiCf;IA5KD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH,YAFU,kBAAkB,CAEjB;IAEX;;OAEG;IACH,WAFU,kBAAkB,CAElB;IAGV;;OAEG;IACH,sBAFU,cAAc,CAEH;IASrB;;;OAGG;IACH,mBAEC;IAOD,uCAEC;IAQD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,8CAEC;IAOD;;;OAGG;IACH,8CAEC;IAoHD;;OAEG;IACH,kDAEC;IAED;;OAEG;IACH,gDAEC;IAED;;OAEG;IACH,kDAEC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAH0C,SAAS,GAAxC,oBAAoB;QAClB,yBAAyB,CAmCrC;IAED;;OAEG;IACH,6CAEC;IAYD;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,uCAEC;IAED;;;;;;;;;;;OAWG;IACH,uCAUC;IAED,+BAUC;IAED;;;;;;;;;;OAUG;IACH,yBAEC;IAED;;;;;OAKG;IACH,sCAMC;IAOD;;;;;;;OAOG;IACH,8EAEC;IA0BD;;;;OAIG;IACH,cAqEC;IAED;;;OAGG;IACH,YAFW,eAAe,QA0BzB;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAHW,sBAAsB,cACtB,MAAM,QAuBhB;IAoCD,gBAYC;IAIL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C;8BA5pBY,OAAO,uBAAuB,EAAE,eAAe;iCAC/C,OAAO,mCAAmC,EAAE,kBAAkB;iCAC9D,OAAO,mCAAmC,EAAE,kBAAkB;4BAC9D,OAAO,8BAA8B,EAAE,aAAa;8BACpD,OAAO,iDAAiD,EAAE,eAAe;+BAtBvD,iDAAiD;sBAI1D,YAAY;oCADE,uCAAuC;mCADxC,gCAAgC;oCAD/B,mDAAmD;kDAIrC,wCAAwC;0CAfhD,0DAA0D;8BAItE,8CAA8C;iCAF3C,iDAAiD;qCAG7C,qDAAqD;oCAGtD,qCAAqC;4BAC7C,gCAAgC;uCAOrB,iDAAiD;6BAM3D,wBAAwB;wCADb,mCAAmC;uCAdpC,wCAAwC"}

package/src/shade/renderer/scene/GPUSceneContext.js

@@ -1,5 +1,10 @@
 import { GPUVirtualGeometryPool } from "../geometry/virtual/runtime/GPUVirtualGeometryPool.js";
 import { GPUVirtualGeometryRuntime } from "../geometry/virtual/runtime/GPUVirtualGeometryRuntime.js";
+import { make_vgeo_page_worker } from "../geometry/virtual/runtime/make_vgeo_page_worker.js";
+import { VGeoFeedbackLoop } from "../geometry/virtual/runtime/VGeoFeedbackLoop.js";
+import { VGeoPageFetcher } from "../geometry/virtual/runtime/VGeoPageFetcher.js";
+import { VGeoResidency } from "../geometry/virtual/runtime/VGeoResidency.js";
+import { VGeoResidencyOptions } from "../geometry/virtual/runtime/VGeoResidencyOptions.js";
 import { assert } from "../../../core/assert.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 import { GPUAnimationManager } from "../animation/GPUAnimationManager.js";
@@ -46,6 +51,8 @@ const ROOT_RECORD = {
     global: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
     prev_global: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]),
     parent: NODE3D_SCENE_ID,
+    // identity does not reflect
+    global_flags: 0,
 };
 
 /**
@@ -258,6 +265,20 @@ export class GPUSceneContext {
      */
     #virtual_geometry;
 
+    /**
+     * Both tiers of virtual-geometry residency, once {@link enable_virtual_geometry} has run.
+     * @type {VGeoResidency|undefined}
+     */
+    #virtual_geometry_residency;
+
+    /**
+     * The feedback loop that carries the cut's readings into the residency, once
+     * {@link enable_virtual_geometry} has run. A host calls its `read` once a frame after every
+     * rasterization path has cut.
+     * @type {VGeoFeedbackLoop|undefined}
+     */
+    #virtual_geometry_feedback;
+
     /**
      * @returns {GPUVirtualGeometryRuntime|undefined}
      */
@@ -265,6 +286,20 @@ export class GPUSceneContext {
         return this.#virtual_geometry;
     }
 
+    /**
+     * @returns {VGeoResidency|undefined}
+     */
+    get virtual_geometry_residency() {
+        return this.#virtual_geometry_residency;
+    }
+
+    /**
+     * @returns {VGeoFeedbackLoop|undefined}
+     */
+    get virtual_geometry_feedback() {
+        return this.#virtual_geometry_feedback;
+    }
+
     /**
      * Give this scene a virtual-geometry runtime, sharing the meshlet pool with everything else it
      * draws.
@@ -273,8 +308,15 @@ export class GPUSceneContext {
      * records naming rows of the same metadata buffer a static mesh's meshlets live in, so nothing
      * downstream of the expansion has to know which kind of geometry it is looking at.
      *
+     * And the residency and the feedback loop with it, so that an engine host gets the whole
+     * streaming loop by enabling virtual geometry rather than by wiring four objects itself
+     * (REVIEW_LEDGER U1): `register` a container with {@link virtual_geometry_residency}, call
+     * {@link virtual_geometry_feedback}'s `read` once a frame after the last rasterization path,
+     * and every page after the root arrives because the cut asked for it.
+     *
      * @param {Object} [options] passed to {@link GPUVirtualGeometryPool} and
-     *     {@link GPUVirtualGeometryRuntime}
+     *     {@link GPUVirtualGeometryRuntime}, except for `residency`
+     * @param {VGeoResidencyOptions} [options.residency] every knob of both residency tiers
      * @returns {GPUVirtualGeometryRuntime}
      */
     enable_virtual_geometry(options = {}) {
@@ -282,16 +324,31 @@ export class GPUSceneContext {
             return this.#virtual_geometry;
         }
 
+        const { residency = new VGeoResidencyOptions(), ...rest } = options;
+
         const pool = new GPUVirtualGeometryPool({
             device: this.#device,
             meshlets: this.geometries.meshlets,
-            ...options,
+            ...rest,
         });
 
         this.#virtual_geometry = new GPUVirtualGeometryRuntime({
             pool,
-            device: this.#device,
-            ...options,
+            ...rest,
+        });
+
+        // pages are fetched, verified and decoded on workers, spawned on first use; a host with no
+        // Worker gets the same fetch in-process
+        const fetcher = new VGeoPageFetcher({
+            worker_count: residency.worker_count,
+            make_worker: typeof Worker === 'undefined' ? undefined : make_vgeo_page_worker,
+        });
+
+        this.#virtual_geometry_residency = new VGeoResidency({ pool, options: residency, fetcher });
+
+        this.#virtual_geometry_feedback = new VGeoFeedbackLoop({
+            runtime: this.#virtual_geometry,
+            residency: this.#virtual_geometry_residency,
         });
 
         return this.#virtual_geometry;

package/src/shade/renderer/scene/NODE3D_STRUCT.d.ts

@@ -18,6 +18,25 @@
  * shaders that need it pull in `chunk_mat4_inverse`.
  */
 export const NODE3D_STRUCT: WebGPUStruct;
+/**
+ * `global` reflects: the determinant of its linear part is negative,
+ * because an odd number of negative scale axes appears somewhere in the
+ * chain that composed it.
+ *
+ * Two consequences, and the renderer has to act on both. Every triangle
+ * drawn under the node comes out of the vertex shader wound backwards,
+ * so fixed-function front-face determination culls exactly the faces
+ * pointing at the camera unless the draw reverses them. And the node's
+ * tangent frame changes handedness, so a bitangent reconstructed as
+ * `cross(N, T) * w` needs the other `w`.
+ *
+ * A node is not necessarily a mesh — bones, empties and particle
+ * emitters have rows in the same table — so this says nothing about
+ * geometry, only about the transform.
+ *
+ * @type {number}
+ */
+export const NODE3D_GLOBAL_FLAG_MIRRORED: number;
 /**
  * Reserved row id for the scene root in the GPU `transforms` table.
  *

package/src/shade/renderer/scene/NODE3D_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NODE3D_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/NODE3D_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,yCA4CU;AAEV;;;;;;;;;;;;;;;GAeG;AACH,8BAFU,MAAM,CAEiB;6BAnFJ,gCAAgC"}
+{"version":3,"file":"NODE3D_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/NODE3D_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,yCA0DU;AAEV;;;;;;;;;;;;;;;;;GAiBG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,8BAFU,MAAM,CAEiB;6BArHJ,gCAAgC"}

package/src/shade/renderer/scene/NODE3D_STRUCT.js

@@ -64,8 +64,42 @@ export const NODE3D_STRUCT = WebGPUStruct.from({
      * terminates when it sees this value.
      */
     parent: u32,
+
+    /**
+     * Properties of `global` that are cheaper to carry than to re-derive
+     * per vertex and per pixel — see {@link NODE3D_GLOBAL_FLAG_MIRRORED}.
+     *
+     * Not an independent field: it is part of how `global` is
+     * represented, and whoever writes one writes the other.
+     * `scene_write_node_global` is the only publisher and writes both, so
+     * the two cannot drift.
+     *
+     * Free, as it happens — the packed record was 176 bytes with the
+     * padding this word now occupies, and is 176 bytes with it.
+     */
+    global_flags: u32,
 }).pack();
 
+/**
+ * `global` reflects: the determinant of its linear part is negative,
+ * because an odd number of negative scale axes appears somewhere in the
+ * chain that composed it.
+ *
+ * Two consequences, and the renderer has to act on both. Every triangle
+ * drawn under the node comes out of the vertex shader wound backwards,
+ * so fixed-function front-face determination culls exactly the faces
+ * pointing at the camera unless the draw reverses them. And the node's
+ * tangent frame changes handedness, so a bitangent reconstructed as
+ * `cross(N, T) * w` needs the other `w`.
+ *
+ * A node is not necessarily a mesh — bones, empties and particle
+ * emitters have rows in the same table — so this says nothing about
+ * geometry, only about the transform.
+ *
+ * @type {number}
+ */
+export const NODE3D_GLOBAL_FLAG_MIRRORED = 1;
+
 /**
  * Reserved row id for the scene root in the GPU `transforms` table.
  *

package/src/shade/renderer/scene/chunk_node3d_flags.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Readers for {@link NODE3D_STRUCT}'s `global_flags`. Every consumer of the encoding goes through
+ * here rather than masking the word itself.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_node3d_flags: CodeChunk;
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_node3d_flags.d.ts.map

package/src/shade/renderer/scene/chunk_node3d_flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_node3d_flags.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/chunk_node3d_flags.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,iCAFU,SAAS,CAeb;0BAtBoB,iCAAiC"}

package/src/shade/renderer/scene/chunk_node3d_flags.js

@@ -0,0 +1,23 @@
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { NODE3D_GLOBAL_FLAG_MIRRORED, NODE3D_STRUCT } from "./NODE3D_STRUCT.js";
+
+/**
+ * Readers for {@link NODE3D_STRUCT}'s `global_flags`. Every consumer of the encoding goes through
+ * here rather than masking the word itself.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_node3d_flags = CodeChunk.from(
+    //language=WGSL
+    `
+/**
+ * Whether the node's world transform reflects — an odd number of negative scale axes anywhere in
+ * its ancestry. Triangles drawn under it come out wound backwards unless the draw reverses them,
+ * and its tangent frame changes handedness.
+ */
+fn node3d_global_is_mirrored( node: ${NODE3D_STRUCT.wgsl_ref} ) -> bool{
+    return ( node.global_flags & ${NODE3D_GLOBAL_FLAG_MIRRORED}u ) != 0u;
+}
+`, [
+        NODE3D_STRUCT.declaration_chunk,
+    ])

package/src/shade/renderer/scene/chunk_scene_database_access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_scene_database_access.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/chunk_scene_database_access.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,wGAA8D;AAC9D,4GAAsE;AAEtE;;;;;;;GAOG;AACH,0CAFU,SAAS,CAqBZ;AAEP;;;;;;;;;;;;;;GAcG;AACH,6CAFU,SAAS,CAsGZ;0BA9JmB,iCAAiC"}
+{"version":3,"file":"chunk_scene_database_access.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/scene/chunk_scene_database_access.js"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,wGAA8D;AAC9D,4GAAsE;AAEtE;;;;;;;GAOG;AACH,0CAFU,SAAS,CAqBZ;AAEP;;;;;;;;;;;;;;GAcG;AACH,6CAFU,SAAS,CAiHZ;0BAzKmB,iCAAiC"}

package/src/shade/renderer/scene/chunk_scene_database_access.js

@@ -1,6 +1,9 @@
+import {
+    chunk_mat4_linear_determinant
+} from "../shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js";
 import { CodeChunk } from "../shader/compiler/CodeChunk.js";
 import { MESH_INSTANCE_METADATA_STRUCT } from "./MESH_INSTANCE_METADATA_STRUCT.js";
-import { NODE3D_STRUCT } from "./NODE3D_STRUCT.js";
+import { NODE3D_GLOBAL_FLAG_MIRRORED, NODE3D_STRUCT } from "./NODE3D_STRUCT.js";
 import { SCENE_DATABASE_SPEC } from "./SCENE_DATABASE_SPEC.js";
 
 /**
@@ -113,12 +116,21 @@ fn scene_write_node_local_scale(
     ${TRANSFORMS_TABLE.marshalling_method_write_field('local_scale')}(database, node_id, value);
 }
 
+/**
+ * Publishes a node's world transform. Writes \`global_flags\` from the same matrix — the flags are
+ * part of how \`global\` is represented, not a field of their own, and deriving them here is what
+ * stops a caller from publishing one without the other.
+ */
 fn scene_write_node_global(
     database: ptr<storage, array<u32>, read_write>,
     node_id: u32,
     value: mat4x4<f32>,
 ) {
     ${TRANSFORMS_TABLE.marshalling_method_write_field('global')}(database, node_id, value);
+
+    let flags = select(0u, ${NODE3D_GLOBAL_FLAG_MIRRORED}u, mat4_linear_determinant(value) < 0.0);
+
+    ${TRANSFORMS_TABLE.marshalling_method_write_field('global_flags')}(database, node_id, flags);
 }
 
 fn scene_write_node_prev_global(
@@ -153,7 +165,9 @@ fn scene_write_mesh_bounding_sphere(
         TRANSFORMS_TABLE.wgsl_gen_write_field_code('local_rotation'),
         TRANSFORMS_TABLE.wgsl_gen_write_field_code('local_scale'),
         TRANSFORMS_TABLE.wgsl_gen_write_field_code('global'),
+        TRANSFORMS_TABLE.wgsl_gen_write_field_code('global_flags'),
         TRANSFORMS_TABLE.wgsl_gen_write_field_code('prev_global'),
+        chunk_mat4_linear_determinant,
         MESHES_TABLE.wgsl_gen_write_field_code('bounding_box'),
         MESHES_TABLE.wgsl_gen_write_field_code('bounding_sphere'),
     ]);

package/src/shade/renderer/scene/rows/GPUSceneRows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneRows.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/rows/GPUSceneRows.js"],"names":[],"mappings":"AAYA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,sCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AAmID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IA2II;;;;;;;;;OASG;IACH;QAR2C,OAAO,EAAvC,sBAAsB;QACC,UAAU;QACV,MAAM;QACD,UAAU,EAAtC,kBAAkB;QACU,SAAS,EAArC,kBAAkB;QACyB,IAAI,EAA/C,iCAAiC;QACW,QAAQ,QAAxC,sBAAsB;OAmB5C;IAED;;OAEG;IACH,iGAEC;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,8BAHoB,MAAM,QAAE,eAAe,QAAE,aAAa,QAAE,OAAO,KAAG,IAAI,QASzE;IAED;;;;;;;;;OASG;IACH,6BAHW,KAAK,GACH,OAAO,CAyBnB;IAED;;;;;;;;;;OAUG;IACH,gBAFW,MAAM,QAuChB;IAED;;;;;;;;OAQG;IACH,gBAFW,MAAM,QA0BhB;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,2EAOC;IAED;;;;OAIG;IACH,gCAEC;IAqCD;;;;;;;;;;;;;;OAcG;IACH,oBALW,MAAM,YACN,eAAe,YACf,aAAa,YACb,OAAO,QAgDjB;IAED;;;;;OAKG;IACH,oBAFW,MAAM,QAUhB;IAsCD;;;;OAIG;IACH,SAFa,MAAM,CAsDlB;IAmMD;;;;OAIG;IACH;;;;;;;;OAQG;IACH,4BAHW,MAAM,kBACG,MAAM,KAAG,IAAI,QAiBhC;IAyGD;;OAEG;IACH,gBA+BC;;CACJ;qCAxnCY,OAAO,kDAAkD,EAAE,sBAAsB;;iCAEjF,OAAO,sCAAsC,EAAE,kBAAkB;iCACjE,OAAO,sCAAsC,EAAE,kBAAkB;gDACjE,OAAO,yCAAyC,EAAE,iCAAiC;qCACnF,OAAO,oDAAoD,EAAE,sBAAsB;8BACnF,OAAO,mCAAmC,EAAE,eAAe;4BAC3D,OAAO,iCAAiC,EAAE,aAAa;oBACvD,OAAO,wCAAwC,EAAE,KAAK"}
+{"version":3,"file":"GPUSceneRows.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/rows/GPUSceneRows.js"],"names":[],"mappings":"AAaA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,sCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AAoID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IA2II;;;;;;;;;OASG;IACH;QAR2C,OAAO,EAAvC,sBAAsB;QACC,UAAU;QACV,MAAM;QACD,UAAU,EAAtC,kBAAkB;QACU,SAAS,EAArC,kBAAkB;QACyB,IAAI,EAA/C,iCAAiC;QACW,QAAQ,QAAxC,sBAAsB;OAmB5C;IAED;;OAEG;IACH,iGAEC;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,8BAHoB,MAAM,QAAE,eAAe,QAAE,aAAa,QAAE,OAAO,KAAG,IAAI,QASzE;IAED;;;;;;;;;OASG;IACH,6BAHW,KAAK,GACH,OAAO,CAyBnB;IAED;;;;;;;;;;OAUG;IACH,gBAFW,MAAM,QAuChB;IAED;;;;;;;;OAQG;IACH,gBAFW,MAAM,QA0BhB;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,2EAOC;IAED;;;;OAIG;IACH,gCAEC;IAqCD;;;;;;;;;;;;;;OAcG;IACH,oBALW,MAAM,YACN,eAAe,YACf,aAAa,YACb,OAAO,QAgDjB;IAED;;;;;OAKG;IACH,oBAFW,MAAM,QAUhB;IAsCD;;;;OAIG;IACH,SAFa,MAAM,CAsDlB;IAyMD;;;;OAIG;IACH;;;;;;;;OAQG;IACH,4BAHW,MAAM,kBACG,MAAM,KAAG,IAAI,QAiBhC;IAyGD;;OAEG;IACH,gBA+BC;;CACJ;qCA/nCY,OAAO,kDAAkD,EAAE,sBAAsB;;iCAEjF,OAAO,sCAAsC,EAAE,kBAAkB;iCACjE,OAAO,sCAAsC,EAAE,kBAAkB;gDACjE,OAAO,yCAAyC,EAAE,iCAAiC;qCACnF,OAAO,oDAAoD,EAAE,sBAAsB;8BACnF,OAAO,mCAAmC,EAAE,eAAe;4BAC3D,OAAO,iCAAiC,EAAE,aAAa;oBACvD,OAAO,wCAAwC,EAAE,KAAK"}

package/src/shade/renderer/scene/rows/GPUSceneRows.js

@@ -4,10 +4,11 @@ import { GPUStateAuthority } from "../../../../engine/ecs/gpu/GPUStateAuthority.
 import { GPUStateAuthorityFlags } from "../../../../engine/ecs/gpu/GPUStateAuthorityFlags.js";
 import { TransformAttachment } from "../../../../engine/ecs/transform-attachment/TransformAttachment.js";
 import { aabb3_matrix4_project } from "../../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
+import { m4_linear_determinant } from "../../../../core/geom/3d/mat4/m4_linear_determinant.js";
 import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
 import { generate_record_writer } from "../../buffer/table/serde/generate_record_writer.js";
 import { MESH_INSTANCE_METADATA_STRUCT } from "../MESH_INSTANCE_METADATA_STRUCT.js";
-import { NODE3D_SCENE_ID, NODE3D_STRUCT } from "../NODE3D_STRUCT.js";
+import { NODE3D_GLOBAL_FLAG_MIRRORED, NODE3D_SCENE_ID, NODE3D_STRUCT } from "../NODE3D_STRUCT.js";
 import { TransparencyMode } from "../../material/TransparencyMode.js";
 
 /**
@@ -66,6 +67,7 @@ const TRANSFORM_RECORD = {
     global: new Float32Array(16),
     prev_global: new Float32Array(16),
     parent: NODE3D_SCENE_ID,
+    global_flags: 0,
 };
 
 /**
@@ -962,6 +964,12 @@ export class GPUSceneRows {
             TRANSFORM_RECORD.prev_global[i] = world[i];
         }
 
+        // seeded alongside `global`, exactly as the hierarchy pass derives it when it recomposes
+        // the row next tick — a row that reflects has to read as reflecting on its first frame too
+        TRANSFORM_RECORD.global_flags = m4_linear_determinant(world) < 0
+            ? NODE3D_GLOBAL_FLAG_MIRRORED
+            : 0;
+
         return TRANSFORM_RECORD;
     }
 

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_compute_normal_matrix_from_m4.d.ts

@@ -1,6 +1,13 @@
 /**
  * This is the transpose adjugate method of computing the normal matrix from a 4x4 matrix
  * Note that the matrix will produce scaled vectors, so you need to normalize them afterward.
+ *
+ * The adjugate transpose is `det(M) * M^-T`, so under a reflection it points every normal *into*
+ * the surface rather than out of it — the one case where the determinant's magnitude being
+ * irrelevant does not make its sign irrelevant too. Re-orienting by that sign is what keeps a
+ * mirrored instance's shading normal, tangent and geometric normal agreeing with each other and
+ * with the winding the rasterizer sees.
+ *
  * @source Eric Lengyel, "Transforming Normals", 2024:  https://terathon.com/blog/transforming-normals.html
  * @source Ken Turkowski, "Properties of Surface Normal Transformations" (Graphics Gems, 1990)
  * @type {CodeChunk}

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_compute_normal_matrix_from_m4.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_compute_normal_matrix_from_m4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat4/chunk_compute_normal_matrix_from_m4.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,kDAFU,SAAS,CAiBjB;0BAxBwB,gCAAgC"}
+{"version":3,"file":"chunk_compute_normal_matrix_from_m4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat4/chunk_compute_normal_matrix_from_m4.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,kDAFU,SAAS,CAsBjB;0BApCwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_compute_normal_matrix_from_m4.js

@@ -3,6 +3,13 @@ import { CodeChunk } from "../../../compiler/CodeChunk.js";
 /**
  * This is the transpose adjugate method of computing the normal matrix from a 4x4 matrix
  * Note that the matrix will produce scaled vectors, so you need to normalize them afterward.
+ *
+ * The adjugate transpose is `det(M) * M^-T`, so under a reflection it points every normal *into*
+ * the surface rather than out of it — the one case where the determinant's magnitude being
+ * irrelevant does not make its sign irrelevant too. Re-orienting by that sign is what keeps a
+ * mirrored instance's shading normal, tangent and geometric normal agreeing with each other and
+ * with the winding the rasterizer sees.
+ *
  * @source Eric Lengyel, "Transforming Normals", 2024:  https://terathon.com/blog/transforming-normals.html
  * @source Ken Turkowski, "Properties of Surface Normal Transformations" (Graphics Gems, 1990)
  * @type {CodeChunk}
@@ -14,11 +21,16 @@ fn compute_normal_matrix_from_m4( m: mat4x4<f32> ) -> mat3x3<f32>{
     let c0 = m[0].xyz;
     let c1 = m[1].xyz;
     let c2 = m[2].xyz;
-    
+
+    let cofactor_0 = cross(c1, c2);
+
+    // dot(c0, cross(c1, c2)) is the determinant, and the cross is already in hand
+    let orientation = select(1.0, -1.0, dot(c0, cofactor_0) < 0.0);
+
     return mat3x3<f32>(
-        cross(c1, c2),
-        cross(c2, c0),
-        cross(c0, c1)
+        cofactor_0 * orientation,
+        cross(c2, c0) * orientation,
+        cross(c0, c1) * orientation
     );
 }
 `, [

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Determinant of the linear (upper-left 3x3) part of a 4x4 transform. WGSL twin of
+ * {@link m4_linear_determinant} — keep the two in step.
+ *
+ * Negative exactly when the transform reflects, which is what reverses triangle winding and
+ * tangent-frame handedness under it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mat4_linear_determinant: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_mat4_linear_determinant.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_mat4_linear_determinant.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,4CAFU,SAAS,CAQb;0BAjBoB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js

@@ -0,0 +1,18 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * Determinant of the linear (upper-left 3x3) part of a 4x4 transform. WGSL twin of
+ * {@link m4_linear_determinant} — keep the two in step.
+ *
+ * Negative exactly when the transform reflects, which is what reverses triangle winding and
+ * tangent-frame handedness under it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mat4_linear_determinant = CodeChunk.from(
+    //language=WGSL
+    `
+fn mat4_linear_determinant( m: mat4x4<f32> ) -> f32{
+    return dot( m[0].xyz, cross( m[1].xyz, m[2].xyz ) );
+}
+`, [])

package/src/shade/renderer/shader/chunk/geometry/triangle/chunk_triangle_list_reverse_winding.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Programmable winding for a non-indexed `triangle-list` draw.
+ *
+ * Maps a `@builtin(vertex_index)` to the one that puts the same three vertices on the rasterizer
+ * in the opposite order: corners `0,1,2` of a triangle become `2,1,0`. That is an odd permutation,
+ * so the emitted winding reverses, and it is the only thing needed to make a reflected instance
+ * face the right way — front-face determination is fixed-function and reads screen-space winding
+ * alone, and WebGPU has no per-draw `frontFace` state to reach it with.
+ *
+ * Only the order changes: the same three vertices are emitted, so coverage (the fill rule is
+ * defined on the triangle's interior, not its vertex order), depth, and barycentric interpolation
+ * are all untouched. `flat` varyings are safe as long as they are constant across the triangle,
+ * which for a visibility buffer's mesh/triangle ids they are.
+ *
+ * Safe to apply to the raw builtin, before any clamp or bounds guard: a meshlet's padding vertices
+ * begin at `primitive_count * 3`, always a corner-0 boundary, so the permutation maps each padding
+ * triple onto itself and can never move a padding vertex into range or a real one out of it.
+ *
+ * @see chunk_node3d_flags for where the `reverse` bit comes from
+ * @type {CodeChunk}
+ */
+export const chunk_triangle_list_reverse_winding: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_triangle_list_reverse_winding.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/triangle/chunk_triangle_list_reverse_winding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_triangle_list_reverse_winding.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/triangle/chunk_triangle_list_reverse_winding.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,kDAFU,SAAS,CAWb;0BAhCoB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/triangle/chunk_triangle_list_reverse_winding.js

@@ -0,0 +1,33 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * Programmable winding for a non-indexed `triangle-list` draw.
+ *
+ * Maps a `@builtin(vertex_index)` to the one that puts the same three vertices on the rasterizer
+ * in the opposite order: corners `0,1,2` of a triangle become `2,1,0`. That is an odd permutation,
+ * so the emitted winding reverses, and it is the only thing needed to make a reflected instance
+ * face the right way — front-face determination is fixed-function and reads screen-space winding
+ * alone, and WebGPU has no per-draw `frontFace` state to reach it with.
+ *
+ * Only the order changes: the same three vertices are emitted, so coverage (the fill rule is
+ * defined on the triangle's interior, not its vertex order), depth, and barycentric interpolation
+ * are all untouched. `flat` varyings are safe as long as they are constant across the triangle,
+ * which for a visibility buffer's mesh/triangle ids they are.
+ *
+ * Safe to apply to the raw builtin, before any clamp or bounds guard: a meshlet's padding vertices
+ * begin at `primitive_count * 3`, always a corner-0 boundary, so the permutation maps each padding
+ * triple onto itself and can never move a padding vertex into range or a real one out of it.
+ *
+ * @see chunk_node3d_flags for where the `reverse` bit comes from
+ * @type {CodeChunk}
+ */
+export const chunk_triangle_list_reverse_winding = CodeChunk.from(
+    //language=WGSL
+    `
+fn triangle_list_reverse_winding( draw_index: u32, reverse: bool ) -> u32{
+    // corner 0 -> +2, corner 1 -> +0, corner 2 -> -2
+    let reversed = draw_index + 2u - ( draw_index % 3u ) * 2u;
+
+    return select( draw_index, reversed, reverse );
+}
+`, [])

package/src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShaderResourceSetDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.js"],"names":[],"mappings":"AAsIA;IAoBI;;OAEG;IACH;cAFoB,MAAM;cAAQ,UAAU;MAI3C;IAED;;;;;OAKG;IACH,4BAMC;IAED;;;;;;;;;;;;OAYG;IACH,mBALW,MAAM,SACN,UAAU,GAAC,MAAM,GAEf,IAAI,CA6ChB;IAED;;;OAGG;IACH,8CAEC;IAGD;;;OAGG;IACH,6CAEC;IAaD;;;;OAIG;IACH;;;;;;;;;;;OAWG;IACH,sBAHW,MAAM,GACJ,OAAO,CAInB;IAED,+FAYC;IAED;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACW,KAAK,GAAtB,MAAM;QACJ,6BAA6B,CAsBzC;IAED;;;;OAIG;IACH,gBAHW,6BAA6B,GAC3B,OAAO,CAQnB;IAED;;;OAGG;IACH,qBAFW,iBAAe,MAAM,QAW/B;IAED;;OAEG;IACH,oCAFa,wBAAwB,CAiBpC;IAED;;;OAGG;IACH,yBAFY,EAAE,EAAE,CAcf;IAED;;;;OAIG;IACH,8BAHW,iBAAe,MAAM,GACnB,wBAAwB,CAMpC;IAED;;;;;OAKG;IACH,qCAHW,sBAAsB,GACpB,oBAAoB,EAAE,CAgBlC;IAED;;;OAGG;IACH,qBAFY,SAAS,CAwGpB;IAED;;;;;;;;;;;;;;;OAeG;IACH,iCAHW,YAAY,GACV,OAAO,CA0CnB;;CACJ;;eAKS,SAAS,2BAA2B,CAAC;;2BA/jBlC,OAAO,yCAAyC,EAAE,YAAY;qCAC9D,OAAO,2CAA2C,EAAE,sBAAsB;yBAC1E,OAAO,uBAAuB,EAAE,UAAU;8CALT,oCAAoC;yCAXzC,0DAA0D;0BAIzE,0BAA0B"}
+{"version":3,"file":"ShaderResourceSetDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shader/resource/ShaderResourceSetDescriptor.js"],"names":[],"mappings":"AAuIA;IAoBI;;OAEG;IACH;cAFoB,MAAM;cAAQ,UAAU;MAI3C;IAED;;;;;OAKG;IACH,4BAMC;IAED;;;;;;;;;;;;OAYG;IACH,mBALW,MAAM,SACN,UAAU,GAAC,MAAM,GAEf,IAAI,CAoDhB;IAED;;;OAGG;IACH,8CAEC;IAGD;;;OAGG;IACH,6CAEC;IAaD;;;;OAIG;IACH;;;;;;;;;;;OAWG;IACH,sBAHW,MAAM,GACJ,OAAO,CAInB;IAED,+FAYC;IAED;;;;;;OAMG;IACH;QAJ4B,KAAK,GAAtB,MAAM;QACW,KAAK,GAAtB,MAAM;QACJ,6BAA6B,CAsBzC;IAED;;;;OAIG;IACH,gBAHW,6BAA6B,GAC3B,OAAO,CAQnB;IAED;;;OAGG;IACH,qBAFW,iBAAe,MAAM,QAW/B;IAED;;OAEG;IACH,oCAFa,wBAAwB,CAiBpC;IAED;;;OAGG;IACH,yBAFY,EAAE,EAAE,CAcf;IAED;;;;OAIG;IACH,8BAHW,iBAAe,MAAM,GACnB,wBAAwB,CAMpC;IAED;;;;;OAKG;IACH,qCAHW,sBAAsB,GACpB,oBAAoB,EAAE,CAgBlC;IAED;;;OAGG;IACH,qBAFY,SAAS,CAwGpB;IAED;;;;;;;;;;;;;;;OAeG;IACH,iCAHW,YAAY,GACV,OAAO,CAwFnB;;CACJ;;eA2BS,SAAS,2BAA2B,CAAC;;2BA1oBlC,OAAO,yCAAyC,EAAE,YAAY;qCAC9D,OAAO,2CAA2C,EAAE,sBAAsB;yBAC1E,OAAO,uBAAuB,EAAE,UAAU;8CALT,oCAAoC;yCAZzC,0DAA0D;0BAIzE,0BAA0B"}