@woosh/meep-engine 3.27.0 → 3.28.0

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/playground/vgeo_viewer/README.md

@@ -1,150 +0,0 @@
-# `.vgeo` viewer
-
-An interactive viewer for the virtual-geometry container. Run the dev server and open it:
-
-```bash
-npm run dev --workspace @woosh/meep-engine
-```
-
-<http://localhost:5173/src/shade/playground/vgeo_viewer/index.html>
-
-Nothing loads by itself. **Drop a `.vgeo` anywhere on the page**, pass `?file=/data/models/…​.vgeo`
-to open one by URL — which is what makes a particular view of a particular asset a bookmark — or
-press **build a sample asset**, which runs the builder in the page over a torus and opens the
-container it produces. `?sample` does the last one on load.
-
-## What is on screen
-
-Not the asset — the **cut**: the clusters the container's own metric selects for where the camera is
-standing, coloured so the seams between them are visible, with the cluster count on screen.
-
-**The cut is frozen until you ask for a new one.** *Adapt to view* re-runs the traversal at wherever
-the camera is now; everything after that is you flying around a decision taken from somewhere else,
-which is the only way to see what a cut actually selected. *Follow the camera* makes it chase
-instead. *tau* is the one quality dial — pixels of permitted error.
-
-Drawing goes through Shade's direct geometry path (a `DynamicMesh` from raw attributes, no meshlet
-encode) because a cut is rebuilt from scratch on every adapt, and it is drawn opaque so the depth
-buffer orders its own triangles.
-
-## What makes it a streaming viewer
-
-The reader under it never holds the whole file. Opening a container reads the header, the level
-table and the root frame — `VGEO_FORMAT.md` §10's always-resident set, two range requests — and
-after that a page arrives only because a traversal asked for it, from exactly the byte range the
-page pointing at it wrote down.
-
-So a cut can be taken before the file has finished arriving, and this is the interesting part: it is
-**clamped, not wrong**. Where the page holding a refinement is missing, the coarser cluster is drawn
-and a *want* is recorded, and the surface is watertight either way.
-
-"Missing" there means §10's *selectable*, not merely resident: a group is refined into only once
-every page holding one of its parents is here. A group's parents are made by one simplification step
-but grouped for the next one separately, so an asset of more than a page per band puts some of them
-in different pages — and refining into a group because its own page arrived, while a coarse cluster
-still stands in for a parent that has not, draws both over the same surface. Those clamps carry no
-want, because there is nothing to fetch from a cluster that already has the bytes it points at; the
-panel counts them under *of those, on a parent*.
-
-Three controls turn that into something you can watch:
-
-| control | what it shows |
-|---|---|
-| **colour by clamp** | amber where the surface is standing in for a page that has not arrived, slate where the cut is the one the file selects |
-| **stream *n* wanted page(s)** | installs eight of them, retakes the cut, repeats — refinement happening in steps rather than in one jump |
-| **evict everything but the root** | back to cold, so it arrives again |
-
-The **streaming** panel is the measurement: `read so far` against the file's own size, the request
-count, what the cold start cost, and how many pages are resident. On anything larger than a toy the
-first of those is a small fraction, and that is the whole claim.
-
-**head prefix** re-opens the current file from cold under a different one. §10 offers a reader two
-cold starts — the 256-byte header and then one exact range per wanted page, or one speculative
-prefix that brings the head and whatever else it happens to cover — and this is the dial between
-them. Coarse-first layout is what makes the second worth doing: a prefix that overshoots the root
-frame has overshot into the pages the traversal is about to want. Watch `read so far` and `requests`
-move against each other. `?head=<bytes>` sets it on load.
-
-**head prefix** on the streaming panel is what is still *held*, and it says `released` for most of a
-session: the reader drops the prefix the first time a read falls outside it, because after the pages
-inside it have installed it is bytes nothing will read — and at a thousand open assets a retained
-256 KiB apiece was a quarter of a gigabyte that neither `resident` nor eviction could see. The
-always-resident set is about 2.4 KB, so the prefix is speculation about the next band and 64 KiB is
-enough of it; the dial is there to watch the trade rather than to tune it.
-
-**quarantined** is the other new row, and it is the difference between an asset that is coarse
-because the camera just moved and one that is coarse because a page will never arrive — which look
-identical on screen. A page that fails its retries is quarantined with its reason and is not asked
-for again; the clamped cut keeps its surface correct with a coarser ancestor, indefinitely.
-
-`read so far` is cumulative and is allowed past 100%: evicting and re-streaming really does fetch
-those pages again, and the audit really does read every byte.
-
-## Validation is optional and off
-
-**Validation is off by default and is not a precondition for anything.** It reads the whole file —
-every frame, every checksum, the directory against a full frame scan — which is exactly what an
-incremental reader exists to avoid, and it answers a question about whoever *wrote* the file rather
-than about the view being put on screen. Press **validate the whole file** when that is the
-question, or pass `?validate`.
-
-It is not a method on the reader, either. `vgeo_audit_container` and `vgeo_install_all_pages` live in
-`format/read/tool/`, and this viewer calls them as the tool it is — a renderer holding a thousand
-containers must not have either within reach of one of them. The audit takes the file as a single
-`ArrayBuffer`, because every build invariant is a cross-check between two places in it, so it refuses
-above 1 GiB naming the size rather than failing in the allocator.
-
-What is *not* optional, because it is the difference between refusing a file and misreading one:
-magic, minimum reader version, payload encoding, hash algorithm, unknown required feature bits,
-unknown codecs, a `decoded_size` outside what the stored bytes could physically produce, and a root
-frame that disagrees with the header about its own size. Those are §4 and §10 reject rules and they
-always run.
-
-**verify each frame's checksum** sits between the two. A frame's identity-seeded checksum covers
-only that frame, so it is verified from bytes just fetched, with no extra request and no whole-file
-pass — §10 requires it of a runtime, where a quarantined page is the difference between a coarse
-stand-in and a wrong surface. Off here for the same reason the audit is: hashing every installed
-byte costs something, and a tool looking at a file it just built is not defending against a network.
-It is read per fetch, so ticking it applies to the next page rather than to a reopen. `?verify` sets
-it on load.
-
-## What lives where
-
-The reader is **not** part of this page. It is `renderer/geometry/virtual/format/read/`, it is the
-shape a runtime would use, and it knows nothing about drawing:
-
-| | |
-|---|---|
-| `VGeoByteSource` | a range at a time, over an `ArrayBuffer` or a dropped `Blob` |
-| `vgeo_fetch_byte_source` | the same over HTTP, refusing a `200` where it asked for a range |
-| `vgeo_read_header` | header and level table, with §4's reject rules |
-| `vgeo_read_page` | one fetched frame → one `VGeoPage`; needs nothing else |
-| `VGeoPage` | a page's own bytes and its own cluster/group/child tables |
-| `VGeoContainerReader` | residency: open, install, evict, and the optional audit |
-| `VGeoDirectory` | the auxiliary page directory, for reaching pages no traversal leads to |
-
-What belongs to the page is everything above the bytes:
-
-| | |
-|---|---|
-| `select_cut.js` | the traversal, the residency clamp, and the wants it records |
-| `cut_geometry.js` | decoding selected clusters into one drawable geometry, and the colour modes |
-| `sample_asset.js` | a container built in the page, so there is something to open |
-| `main.js` | renderer, camera, panel, and the streaming loop |
-
-## Driving it from a script
-
-Everything is reachable from the console, which is what makes the page verifiable in a headless
-browser rather than by a person watching it:
-
-```js
-await __open_sample();       // or __open_url('/data/…​.vgeo')
-__vgeo.set_auto_stream(false);
-__vgeo.reset_residency();    // back to the root page alone
-__state();                   // { resident_pages, bytes_read, clusters, clamped, wants, … }
-await __stream();            // one round of eight pages, then a fresh cut
-await __validate();          // the whole-file audit, as an array of defect strings
-```
-
-`__state()` is the one to assert on: `clamped` reaching zero is the cut having converged on what the
-container selects, and it converges to the same numbers whatever order the pages arrived in.