@woosh/meep-engine 3.29.0 → 3.31.0

package/src/engine/ecs/terrain/tiles/TerrainTile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerrainTile.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/terrain/tiles/TerrainTile.js"],"names":[],"mappings":";AAwBA;;GAEG;AACH;IACI,sBAA6B;IAC7B,eAA0B;IAC1B,cAAyB;IACzB,kBAAyB;IACzB,4BAAoC;IAUpC;;;;;;;;;;;OAWG;IACH,UAFU,YAAY,GAAC,IAAI,CAEX;IAEhB;;OAEG;IACH,SAFU,YAAY,GAAC,IAAI,CAEZ;IAEf;;OAEG;IACH,KAFU,YAAY,GAAC,IAAI,CAEhB;IAEX;;OAEG;IACH,SAFU,WAAW,GAAC,WAAW,GAAC,IAAI,CAEvB;IAEf;;;OAGG;IACH,WAFU,OAAO,CAEA;IAEjB;;;OAGG;IACH,cAFU,SAAS,CAEY;IAE/B;;;OAGG;IACH,KAFU,eAAe,CAEd;IAEX;;;OAGG;IACH,SAFU,OAAO,CAED;IAChB;;;OAGG;IACH,mBAFU,OAAO,CAES;IAC1B,uBAAmB;IAEnB;;;;;;;;;OASG;IACH,eAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,aAAuB;IACvB,oBAA2B;IAE3B;;;;OAIG;IACH,kBAWE;IAEF;;;;;OAKG;IACH,+BAAiG;IAEjG;;;OAGG;IACH,SAFU,MAAM,CAEJ;IAUZ;;;OAGG;IACH,gCAGC;IAfD;;;OAGG;IACH,8BAEC;IAWD;;;;;;;;;;OAUG;IACH,yBATW,aAAa,WACb,MAAM,WACN,MAAM,WACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACL,OAAO,CA8ClB;IAED,+CAKC;IAED,8CAOC;IAED;;;;;;;;;;OAUG;IACH,mBATW,WAAW,GAAC,SAAS,UACrB,WAAW,GAAC,SAAS,QACrB,WAAW,GAAC,SAAS,SACrB,WAAW,GAAC,SAAS,WACrB,WAAW,GAAC,SAAS,YACrB,WAAW,GAAC,SAAS,cACrB,WAAW,GAAC,SAAS,eACrB,WAAW,GAAC,SAAS,QAsM/B;IAED,2BAoDC;IAED;;;;OAIG;IACH,mCAHW,MAAM,cACN,MAAM,QAIhB;IAED,gBAcC;IAED;;;;;OAKG;IACH,gBAFW;QAAC,QAAQ,EAAE;YAAC,QAAQ,EAAE,YAAY,CAAC;YAAC,OAAO,EAAE,YAAY,CAAC;YAAC,GAAG,EAAE,YAAY,CAAC;YAAC,OAAO,EAAE,WAAW,GAAC,WAAW,CAAA;SAAC,CAAC;QAAC,GAAG,CAAC,EAAC;YAAC,UAAU,EAAC,MAAM,CAAC;YAAC,IAAI,EAAC,WAAW,CAAA;SAAC,CAAA;KAAC,QAuBtK;;CACJ;oBAniBmB,kCAAkC;4BAG1B,2CAA2C;0BAZ7C,yCAAyC;gCADnC,mDAAmD;mBAGhE,0CAA0C;8BAM/B,2CAA2C"}
+{"version":3,"file":"TerrainTile.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/terrain/tiles/TerrainTile.js"],"names":[],"mappings":";AAwBA;;GAEG;AACH;IACI,sBAA6B;IAC7B,eAA0B;IAC1B,cAAyB;IACzB,kBAAyB;IACzB,4BAAoC;IAUpC;;;;;;;;;;;OAWG;IACH,UAFU,YAAY,GAAC,IAAI,CAEX;IAEhB;;OAEG;IACH,SAFU,YAAY,GAAC,IAAI,CAEZ;IAEf;;OAEG;IACH,KAFU,YAAY,GAAC,IAAI,CAEhB;IAEX;;OAEG;IACH,SAFU,WAAW,GAAC,WAAW,GAAC,IAAI,CAEvB;IAEf;;;OAGG;IACH,WAFU,OAAO,CAEA;IAEjB;;;OAGG;IACH,cAFU,SAAS,CAEY;IAE/B;;;OAGG;IACH,KAFU,eAAe,CAEd;IAEX;;;OAGG;IACH,SAFU,OAAO,CAED;IAChB;;;OAGG;IACH,mBAFU,OAAO,CAES;IAC1B,uBAAmB;IAEnB;;;;;;;;;OASG;IACH,eAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,aAAuB;IACvB,oBAA2B;IAE3B;;;;OAIG;IACH,kBAWE;IAEF;;;;;OAKG;IACH,+BAAiG;IAEjG;;;OAGG;IACH,SAFU,MAAM,CAEJ;IAUZ;;;OAGG;IACH,gCAGC;IAfD;;;OAGG;IACH,8BAEC;IAWD;;;;;;;;;;OAUG;IACH,yBATW,aAAa,WACb,MAAM,WACN,MAAM,WACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACL,OAAO,CA8ClB;IAED,+CAKC;IAED,8CAOC;IAED;;;;;;;;;;OAUG;IACH,mBATW,WAAW,GAAC,SAAS,UACrB,WAAW,GAAC,SAAS,QACrB,WAAW,GAAC,SAAS,SACrB,WAAW,GAAC,SAAS,WACrB,WAAW,GAAC,SAAS,YACrB,WAAW,GAAC,SAAS,cACrB,WAAW,GAAC,SAAS,eACrB,WAAW,GAAC,SAAS,QA4M/B;IAED,2BAoDC;IAED;;;;OAIG;IACH,mCAHW,MAAM,cACN,MAAM,QAIhB;IAED,gBAoBC;IA6BD;;;;;OAKG;IACH,gBAFW;QAAC,QAAQ,EAAE;YAAC,QAAQ,EAAE,YAAY,CAAC;YAAC,OAAO,EAAE,YAAY,CAAC;YAAC,GAAG,EAAE,YAAY,CAAC;YAAC,OAAO,EAAE,WAAW,GAAC,WAAW,CAAA;SAAC,CAAC;QAAC,GAAG,CAAC,EAAC;YAAC,UAAU,EAAC,MAAM,CAAC;YAAC,IAAI,EAAC,WAAW,CAAA;SAAC,CAAA;KAAC,QA0BtK;;CACJ;oBA7kBmB,kCAAkC;4BAG1B,2CAA2C;0BAZ7C,yCAAyC;gCADnC,mDAAmD;mBAGhE,0CAA0C;8BAM/B,2CAA2C"}

package/src/engine/ecs/terrain/tiles/TerrainTile.js

@@ -326,6 +326,12 @@ class TerrainTile {
 
                 const otherResolution = left.resolution.getValue();
 
+                // NOTE: the loops below run 1..stitchCount-1, matching stitchVertical.
+                // They used to start at 0, which is the seam's TOP corner vertex - and
+                // stitchCorners() runs before stitchSides(), so that iteration overwrote the
+                // four-way corner average with a two-way left/right one, but only on the two tiles
+                // this pass touches. The four tiles meeting at a grid corner ended up holding
+                // three different normals for one world position.
                 const stitchCount = right.size.y * thisResolution - 1;
 
                 const otherOffset = left.size.x * otherResolution - 1;
@@ -335,7 +341,7 @@ class TerrainTile {
                 let index0, index1;
                 if (left.stitching.right) {
 
-                    for (i = 0; i < stitchCount; i++) {
+                    for (i = 1; i < stitchCount; i++) {
                         index0 = i * thisMultiplier;
                         index1 = otherOffset + i * otherMultiplier;
 
@@ -344,7 +350,7 @@ class TerrainTile {
                     }
                     right.stitching.left = true;
                 } else if (right.stitching.left) {
-                    for (i = 0; i < stitchCount; i++) {
+                    for (i = 1; i < stitchCount; i++) {
                         index0 = i * thisMultiplier;
                         index1 = otherOffset + i * otherMultiplier;
 
@@ -354,7 +360,7 @@ class TerrainTile {
                     left.stitching.right = true;
                 } else {
                     //neither is stitched
-                    for (i = 0; i < stitchCount; i++) {
+                    for (i = 1; i < stitchCount; i++) {
                         index0 = i * thisMultiplier;
                         index1 = otherOffset + i * otherMultiplier;
 
@@ -520,6 +526,12 @@ class TerrainTile {
         this.uvs = null;
         this.indices = null;
 
+        this.bvh = null;
+
+        // The surface is gone, so nothing about it has been stitched any more. See the note in
+        // `#reset_stitching`.
+        this.#reset_stitching();
+
         if (!this.isBuilt) {
             return;
         }
@@ -528,6 +540,33 @@ class TerrainTile {
         this.onDestroyed.send1(this);
     }
 
+    /**
+     * Forget every seam this tile has had averaged.
+     *
+     * The flags record that a seam's normals have been reconciled with a neighbour's. Nothing used
+     * to set one back to false, so from a tile's SECOND build onwards `stitchVertical` and
+     * `stitchHorizontal` took the "already stitched on the other side, copy from it" branch and
+     * blitted one side's un-averaged edge normals across, instead of averaging the two face
+     * normals. Every terrain edit after the initial build therefore left a lit crease along the
+     * seam - invisible on a freshly loaded level, which is why it survived.
+     *
+     * @private
+     */
+    #reset_stitching() {
+        const stitching = this.stitching;
+
+        stitching.top = false;
+        stitching.bottom = false;
+        stitching.left = false;
+        stitching.right = false;
+
+        stitching.topLeft = false;
+        stitching.topRight = false;
+
+        stitching.bottomLeft = false;
+        stitching.bottomRight = false;
+    }
+
     /**
      * A rebuild over a live tile replaces its surface; a renderer holding geometry made from the
      * outgoing arrays learns of it through {@link onBuilt}.
@@ -537,6 +576,9 @@ class TerrainTile {
     build(tileData) {
         this.isBuilt = true;
 
+        // a new surface has not been stitched to anything yet
+        this.#reset_stitching();
+
         const tileDataGeometry = tileData.geometry;
 
         this.vertices = tileDataGeometry.vertices;

package/src/engine/ecs/terrain/tiles/TerrainTileManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TerrainTileManager.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/terrain/tiles/TerrainTileManager.js"],"names":[],"mappings":";0BAoBa,OAAO,gDAAgD,EAAE,OAAO;AA4B7E;IA2FI;;;;;;;OAOG;IACH;QAFgC,WAAW,EAAhC,WAAW;OAYrB;IA5GD;;;OAGG;IACH,OAFU,WAAW,EAAE,CAEZ;IAEX;;;MAGE;IAEF;;;;;;;;;;OAUG;IACH,aAFU,OAAO,CAEiB;IAElC;;;;;;;;;;;;OAYG;IACH,oBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,WAFU,OAAO,CAEa;IAC9B;;;OAGG;IACH,YAFU,eAAe,CAEW;IAEpC;;;OAGG;IACH,OAFU,OAAO,CAES;IAG1B;;;;OAIG;IACH,oBAAmC;IAEnC;;;OAGG;IACH,cAFU,GAAG,CAEG;IAEhB;;;OAGG;IACH,aAFU,eAAe,CAEe;IAExC;;;;;;;;;;;OAWG;IACH,eAFU,MAAM,CAEG;IAef;;;OAGG;IACH,aAFU,WAAW,CAES;IAGlC,gCAWC;IAED,8BAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,0BAFW,MAAM,QAuBhB;IAED;;;;OAIG;IACH,2BAHW,MAAM,cACN,MAAM,QAiChB;IAED,mBAIC;IAED;;;;OAIG;IACH,mBAHW,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,uBAYrC;IAED,qBAqBC;IAED;;OAEG;IACH,gBAIC;IAED;;;;;;OAMG;IACH,qBALW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAuBhB;IAGD;;;;;;;OAOG;IACH,oCANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,WAAW,EAAE,CAgCzB;IAED,wBA0CC;IAED;;;;;OAKG;IACH,oBAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;;;;;;;;;OAcG;IACH,wBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;;;OAMG;IACH,wBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,GACJ,WAAW,GAAC,SAAS,CAiBjC;IAED;;;;;OAKG;IACH,wBAJW,MAAM,KACN,MAAM,GACJ,WAAW,CAavB;IAED;;;;;OAKG;IACH,4BAJW,MAAM,KACN,MAAM,GACL,WAAW,GAAC,SAAS,CAoBhC;IAED;;;;;OAKG;IACH,+BAJW,MAAM,KACN,MAAM,GACJ,QAAQ,WAAW,CAAC,CAYhC;IAED;;;;;;OAMG;IACH,UALW,MAAM,KACN,MAAM,GACJ,QAAQ,WAAW,CAAC,CA4BhC;IAED;;;OAGG;IACH,cAFW,WAAW,QAcrB;IAED,gBASC;IAED;;;;;;OAMG;IACH,cAJW,MAAM,KACN,MAAM,QACN,WAAW,QAUrB;IAED;;;;;;;;;;;;OAYG;IACH,yBAJW,MAAM,KACN,MAAM;YACG,MAAM,GAAC,WAAW,GAAC,SAAS;MAkD/C;IAED;;;;;;;;;;OAUG;IACH,yBATW,aAAa,WACb,MAAM,WACN,MAAM,WACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,OAAO,CAuDnB;IAED;;;;;;OAMG;IACH,kCALW,aAAa,KACb,MAAM,KACN,MAAM,GACL,OAAO,CAOlB;IAED;;;;;;OAMG;IACH,SALW,MAAM,KACN,MAAM,WACN,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,UAC3B,CAAC,MAAM,KAAG,KAAK,IAAI,QAiG7B;CACJ;wBAh3BuB,kBAAkB;mBATvB,0CAA0C;oBAGzC,kCAAkC;4BAI1B,2CAA2C;oBAVnD,mCAAmC;gCAOvB,mDAAmD;8BAFrD,2CAA2C"}
+{"version":3,"file":"TerrainTileManager.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/ecs/terrain/tiles/TerrainTileManager.js"],"names":[],"mappings":";0BAoBa,OAAO,gDAAgD,EAAE,OAAO;AA4B7E;IA2FI;;;;;;;OAOG;IACH;QAFgC,WAAW,EAAhC,WAAW;OAYrB;IA5GD;;;OAGG;IACH,OAFU,WAAW,EAAE,CAEZ;IAEX;;;MAGE;IAEF;;;;;;;;;;OAUG;IACH,aAFU,OAAO,CAEiB;IAElC;;;;;;;;;;;;OAYG;IACH,oBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,WAFU,OAAO,CAEa;IAC9B;;;OAGG;IACH,YAFU,eAAe,CAEW;IAEpC;;;OAGG;IACH,OAFU,OAAO,CAES;IAG1B;;;;OAIG;IACH,oBAAmC;IAEnC;;;OAGG;IACH,cAFU,GAAG,CAEG;IAEhB;;;OAGG;IACH,aAFU,eAAe,CAEe;IAExC;;;;;;;;;;;OAWG;IACH,eAFU,MAAM,CAEG;IAef;;;OAGG;IACH,aAFU,WAAW,CAES;IAGlC,gCAWC;IAED,8BAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,0BAFW,MAAM,QAuBhB;IAED;;;;OAIG;IACH,2BAHW,MAAM,cACN,MAAM,QAiChB;IAED,mBAIC;IAED;;;;OAIG;IACH,mBAHW,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,uBAYrC;IAED,qBAqBC;IAED;;OAEG;IACH,gBAIC;IAED;;;;;;OAMG;IACH,qBALW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAuBhB;IAGD;;;;;;;OAOG;IACH,oCANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,WAAW,EAAE,CAgCzB;IAED,wBA0CC;IAED;;;;;OAKG;IACH,oBAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;;;;;;;;;OAcG;IACH,wBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;;;OAMG;IACH,wBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;;;OAKG;IACH,UAJW,MAAM,KACN,MAAM,GACJ,WAAW,GAAC,SAAS,CAiBjC;IAED;;;;;OAKG;IACH,wBAJW,MAAM,KACN,MAAM,GACJ,WAAW,CAavB;IAED;;;;;OAKG;IACH,4BAJW,MAAM,KACN,MAAM,GACL,WAAW,GAAC,SAAS,CAoBhC;IAED;;;;;OAKG;IACH,+BAJW,MAAM,KACN,MAAM,GACJ,QAAQ,WAAW,CAAC,CAYhC;IAED;;;;;;OAMG;IACH,UALW,MAAM,KACN,MAAM,GACJ,QAAQ,WAAW,CAAC,CA4BhC;IAED;;;OAGG;IACH,cAFW,WAAW,QAcrB;IAED,gBAMC;IAED;;;;;;OAMG;IACH,cAJW,MAAM,KACN,MAAM,QACN,WAAW,QAUrB;IAED;;;;;;;;;;;;OAYG;IACH,yBAJW,MAAM,KACN,MAAM;YACG,MAAM,GAAC,WAAW,GAAC,SAAS;MAkD/C;IAED;;;;;;;;;;OAUG;IACH,yBATW,aAAa,WACb,MAAM,WACN,MAAM,WACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,OAAO,CAuDnB;IAED;;;;;;OAMG;IACH,kCALW,aAAa,KACb,MAAM,KACN,MAAM,GACL,OAAO,CAOlB;IAED;;;;;;OAMG;IACH,SALW,MAAM,KACN,MAAM,WACN,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,UAC3B,CAAC,MAAM,KAAG,KAAK,IAAI,QAiG7B;CACJ;wBA72BuB,kBAAkB;mBATvB,0CAA0C;oBAGzC,kCAAkC;4BAI1B,2CAA2C;oBAVnD,mCAAmC;gCAOvB,mDAAmD;8BAFrD,2CAA2C"}

package/src/engine/ecs/terrain/tiles/TerrainTileManager.js

@@ -622,14 +622,11 @@ class TerrainTileManager {
     }
 
     dispose() {
-        const tiles = this.tiles;
-
-        const n = tiles.length;
-
-        for (let i = 0; i < n; i++) {
-            const t = tiles[i];
-            t.dispose();
-        }
+        // Delegates, rather than looping `t.dispose()` itself. On its own that left every tile
+        // linked into the leaf BVH, every BVH node allocated and the `tiles` array populated -
+        // `Terrain#unlink` calls this on every scene teardown, so the whole tile grid and its BVH
+        // were retained for the manager's lifetime.
+        this.destroyTiles();
     }
 
     /**

package/src/engine/graphics/ecs/camera/pp/PerfectPanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PerfectPanner.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/camera/pp/PerfectPanner.js"],"names":[],"mappings":"AAYA;IA4CI;;;OAGG;IACH,sBAEC;IAVD,qBAEC;IAUD;;OAEG;IACH,2BAEC;IAwBD;;;OAGG;IACH,wBAFW,OAAO,QA4BjB;IAED,kCAuCC;IAED,YAEC;;CAEJ;oBA1KmB,qCAAqC;oBAKrC,qCAAqC"}
+{"version":3,"file":"PerfectPanner.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/camera/pp/PerfectPanner.js"],"names":[],"mappings":"AAuBA;IAmDI;;;OAGG;IACH,sBAEC;IAVD,qBAEC;IAUD;;OAEG;IACH,2BAEC;IAmCD;;;OAGG;IACH,wBAFW,OAAO,QAsCjB;IAED,kCAuDC;IAED,YAEC;;CAEJ;oBAjOmB,qCAAqC;oBAKrC,qCAAqC"}

package/src/engine/graphics/ecs/camera/pp/PerfectPanner.js

@@ -6,9 +6,20 @@ import { camera_find_active } from "../camera_find_active.js";
 import Vector2 from "../../../../../core/geom/Vector2.js";
 import { Transform64 } from "../../../../ecs/transform/Transform64.js";
 import { t64_read_translation } from "../../../../ecs/transform/t64_read_translation.js";
+import { plane3_compute_ray_intersection } from "../../../../../core/geom/3d/plane/plane3_compute_ray_intersection.js";
 
-const NEAR_PLANE_INDEX = 5;
-const FAR_PLANE_INDEX = 4;
+/**
+ * Indices into the six `[normal_x, normal_y, normal_z, constant]` tuples
+ * {@link Camera#getFrustumPlanes} publishes. Taken from the one place the tree
+ * states them, `camera_active_frustum` and `RenderLayer` — they were the other
+ * way round here, which put every projection on the wrong plane.
+ * @type {number}
+ */
+const NEAR_PLANE_INDEX = 4;
+const FAR_PLANE_INDEX = 5;
+
+/** Floats per published plane. */
+const PLANE_STRIDE = 4;
 
 export class PerfectPanner {
 
@@ -25,6 +36,13 @@ export class PerfectPanner {
      */
     #grab_eye_position = new Vector3();
 
+    /**
+     * Whether the last {@link start} found everything the pan needs: an active
+     * camera to cast from and a point in the scene to hold.
+     * @type {boolean}
+     */
+    #has_grab = false;
+
     /**
      *
      * @type {Engine|null}
@@ -81,13 +99,24 @@ export class PerfectPanner {
 
         const ray = make_ray_from_viewport_position(engine, new Vector2(viewport_x, viewport_y));
 
-        // console.log(`Ray origin:${ray.origin}, direction:${ray.direction}`);
+        // `Camera.rayPlaneIntersection` was called here and has never existed —
+        // the frustum is published as six packed `[nx, ny, nz, constant]`
+        // tuples and the intersection is the tree's own plane primitive.
+        const planes = this.#camera.getFrustumPlanes();
+
+        if (planes === null) {
+            // a camera that has not driven a frame has no frustum to project
+            // onto, and zeroed planes would answer rather than admit it
+            throw new Error('the active camera has not published a frustum');
+        }
+
+        const base = plane * PLANE_STRIDE;
 
-        this.#camera.rayPlaneIntersection(
+        plane3_compute_ray_intersection(
             out,
             ray.origin.x, ray.origin.y, ray.origin.z,
             ray.direction.x, ray.direction.y, ray.direction.z,
-            plane
+            planes[base], planes[base + 1], planes[base + 2], planes[base + 3]
         );
     }
 
@@ -98,6 +127,16 @@ export class PerfectPanner {
     update(screen_position) {
         // console.log(`PerfectPanner/update: ${screen_position}`)
 
+        if (!this.#has_grab) {
+            // Perfect panning holds a point in the scene; the grab found none —
+            // no terrain under the cursor, or no active camera to cast from —
+            // so there is nothing to be perfect about and no translation to
+            // report. Reporting one derived from the PREVIOUS grab's reference
+            // point, which is what a stale `#grab_world_reference` did, is the
+            // one answer that is certainly wrong.
+            return;
+        }
+
         const C = this.#grab_world_reference;
         const A = this.#grab_eye_position;
         const E = this.#grab_far_projection;
@@ -136,8 +175,18 @@ export class PerfectPanner {
             throw new Error('No dataset');
         }
 
+        this.#has_grab = false;
+        this.#translation.set(0, 0, 0);
+
         // bind camera
         const camera = camera_find_active(ecd);
+
+        if (camera.component === undefined) {
+            // the case `camera_find_active` documents: nothing is drawing, so
+            // there is no viewport to pan through
+            return;
+        }
+
         this.#camera = camera.component;
         this.#camera_transform = ecd.getComponent(camera.entity, Transform64);
 
@@ -149,6 +198,12 @@ export class PerfectPanner {
 
         const terrain = obtainTerrain(ecd);
 
+        if (terrain === null) {
+            // `obtainTerrain` answers null for a scene without one, and the
+            // point to hold has to come from somewhere
+            return;
+        }
+
         const hit = new SurfacePoint3();
 
         if (terrain.raycastFirstSync(hit,
@@ -157,11 +212,11 @@ export class PerfectPanner {
         )) {
             // got terrain hit
             this.#grab_world_reference.copy(hit.position);
+
+            this.#has_grab = true;
         }
 
         t64_read_translation(this.#grab_eye_position, this.#camera_transform);
-
-        this.#translation.set(0, 0, 0);
     }
 
     end() {

package/src/engine/graphics/ecs/mesh-v2/aggregate/SGMesh.d.ts

@@ -71,6 +71,15 @@ export class SGMesh {
     get materialOverride(): Material;
     applyMaterialOverride(): void;
     /**
+     * Set before the component is attached to an entity.
+     *
+     * Reassigning it afterwards is not observed: {@link MeshSystem} reads the url when it links the
+     * component and never again — the one re-read is the drain for components that arrived with no
+     * url yet — and there is no signal here for it to watch. The entity keeps drawing what it
+     * already has.
+     *
+     * To swap the model of a live entity, remove the component and add a new one. That is what the
+     * engine does everywhere it swaps one.
      *
      * @param {string|null} v
      */

package/src/engine/graphics/ecs/mesh-v2/aggregate/SGMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SGMesh.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/mesh-v2/aggregate/SGMesh.js"],"names":[],"mappings":";;;;;AAmBA;IA4OI;;;;OAIG;IACH,oBAHW,MAAM,GACJ,MAAM,CAUlB;IAkBD;;;;;;OAMG;IACH,sBAHW,MAAM,GACJ,MAAM,CAQlB;IAjRD;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,OAFU,MAAM,GAAC,IAAI,CAER;IAEb;;;;OAIG;IACH,eAAc;IAEd;;;;OAIG;IACH,yBAA+B;IAE/B;;;;OAIG;IACH,gBAEC;IAED;;;;OAIG;IACH,cAHW,MAAM,GACJ,OAAO,CAUnB;IAED,eAEC;IAED;;;OAGG;IACH,YAFW,MAAM,QAOhB;IAED;;;OAGG;IACH,SAFa,MAAM,CAQlB;IAED;;;OAGG;IACH,kCAYC;IAED,iCAEC;IAED,8BAYC;IAUD;;;OAGG;IACH,mBAOC;IAnBD;;;OAGG;IACH,kBAEC;IAeD;;;;OAIG;IACH,4BAHW,KAAK,GACH,OAAO,CAUnB;IAED;;;OAGG;IACH,yCAFW,KAAK,QAIf;IAED;;;;OAIG;IACH,cAHW,MAAM;;;;KAAY,GAChB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM;;;;KAAY,GAChB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM;;;;KAAY,SAClB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM;;;;KAAY,GAChB,OAAO,CAInB;IAUD;;;OAGG;IACH,2BAEC;IAdD;;;OAGG;IACH,0BAEC;IAkBD;;;OAGG;IACH,8BAEC;IAdD;;;OAGG;IACH,6BAEC;IAyBD;;;;MAMC;IAED;;;;aAMC;;CAgBJ;;;;sBA5SqB,2CAA2C"}
+{"version":3,"file":"SGMesh.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/mesh-v2/aggregate/SGMesh.js"],"names":[],"mappings":";;;;;AAmBA;IAyPI;;;;OAIG;IACH,oBAHW,MAAM,GACJ,MAAM,CAUlB;IAkBD;;;;;;OAMG;IACH,sBAHW,MAAM,GACJ,MAAM,CAQlB;IA9RD;;;OAGG;IACH,OAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,OAFU,MAAM,GAAC,IAAI,CAER;IAEb;;;;OAIG;IACH,eAAc;IAEd;;;;OAIG;IACH,yBAA+B;IAE/B;;;;OAIG;IACH,gBAEC;IAED;;;;OAIG;IACH,cAHW,MAAM,GACJ,OAAO,CAUnB;IAED,eAEC;IAED;;;OAGG;IACH,YAFW,MAAM,QAWhB;IAED;;;OAGG;IACH,SAFa,MAAM,CAQlB;IAED;;;OAGG;IACH,kCAYC;IAED,iCAEC;IAED,8BAYC;IAUD;;;;;;;;;;;;OAYG;IACH,mBAOC;IA5BD;;;OAGG;IACH,kBAEC;IAwBD;;;;OAIG;IACH,4BAHW,KAAK,GACH,OAAO,CAUnB;IAED;;;OAGG;IACH,yCAFW,KAAK,QAIf;IAED;;;;OAIG;IACH,cAHW,MAAM;;;;KAAY,GAChB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM;;;;KAAY,GAChB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM;;;;KAAY,SAClB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM;;;;KAAY,GAChB,OAAO,CAInB;IAUD;;;OAGG;IACH,2BAEC;IAdD;;;OAGG;IACH,0BAEC;IAkBD;;;OAGG;IACH,8BAEC;IAdD;;;OAGG;IACH,6BAEC;IAyBD;;;;MAMC;IAED;;;;aAMC;;CAgBJ;;;;sBAzTqB,2CAA2C"}

package/src/engine/graphics/ecs/mesh-v2/aggregate/SGMesh.js

@@ -84,6 +84,10 @@ export class SGMesh {
      */
     copy(other) {
         this.__url = other.__url;
+        // `equals` compares these, so a copy that left them at the constructor
+        // default was not equal to the thing it copied — and a clone of a model
+        // authored with shadows off came back casting and receiving them.
+        this.flags = other.flags;
         this.__node = null;
         this.__initial_bounds.copy(other.__initial_bounds);
         this.#material_override = other.#material_override;
@@ -146,6 +150,15 @@ export class SGMesh {
     }
 
     /**
+     * Set before the component is attached to an entity.
+     *
+     * Reassigning it afterwards is not observed: {@link MeshSystem} reads the url when it links the
+     * component and never again — the one re-read is the drain for components that arrived with no
+     * url yet — and there is no signal here for it to watch. The entity keeps drawing what it
+     * already has.
+     *
+     * To swap the model of a live entity, remove the component and add a new one. That is what the
+     * engine does everywhere it swaps one.
      *
      * @param {string|null} v
      */

package/src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshAnimationControllerSystem.d.ts

@@ -20,6 +20,17 @@ export class SGMeshAnimationControllerSystem extends System<any> {
      * @param {number} entity
      */
     link(anim: SGMeshAnimationController, mesh: SGMesh, entity: number): Promise<void>;
+    /**
+     * Take the entity out of the queue.
+     *
+     * Without this an entity destroyed while it was waiting for its node or its asset stayed in the
+     * queue for the life of the system, re-processed every frame.
+     *
+     * @param {SGMeshAnimationController} anim
+     * @param {SGMesh} mesh
+     * @param {number} entity
+     */
+    unlink(anim: SGMeshAnimationController, mesh: SGMesh, entity: number): void;
     update(td: any): void;
     #private;
 }

package/src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshAnimationControllerSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SGMeshAnimationControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshAnimationControllerSystem.js"],"names":[],"mappings":"AASA;IAmCI;;;OAGG;IACH,4BAIC;IA9BD;;;;OAIG;IACH,qBAFU,MAAM,CAES;IAQzB,mEAGE;IACF,gIAGE;IASE,eAAoB;IAwCxB;;;;;OAKG;IACH,WAJW,yBAAyB,QACzB,MAAM,UACN,MAAM,iBAUhB;IA+CD,sBAyBC;;CACJ;uBA9KsB,2BAA2B;mBAJ/B,6CAA6C;uBAMzC,aAAa;0CACM,gCAAgC;4CAL9B,0DAA0D"}
+{"version":3,"file":"SGMeshAnimationControllerSystem.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshAnimationControllerSystem.js"],"names":[],"mappings":"AAgBA;IAmCI;;;OAGG;IACH,4BAIC;IA9BD;;;;OAIG;IACH,qBAFU,MAAM,CAES;IAQzB,mEAGE;IACF,gIAGE;IASE,eAAoB;IAoExB;;;;;OAKG;IACH,WAJW,yBAAyB,QACzB,MAAM,UACN,MAAM,iBAUhB;IAED;;;;;;;;;OASG;IACH,aAJW,yBAAyB,QACzB,MAAM,UACN,MAAM,QAUhB;IA+CD,sBAmCC;;CACJ;uBA/OsB,2BAA2B;mBAJ/B,6CAA6C;uBAMzC,aAAa;0CACM,gCAAgC;4CAL9B,0DAA0D"}

package/src/engine/graphics/ecs/mesh-v2/aggregate/SGMeshAnimationControllerSystem.js

@@ -7,6 +7,13 @@ import { assetTypeByPath } from "../../mesh/assetTypeByPath.js";
 import { SGMesh } from "./SGMesh.js";
 import { SGMeshAnimationController } from "./SGMeshAnimationController.js";
 
+/**
+ * How many queued entities one update binds. The work is mostly waiting on the asset manager, but
+ * the queue is drained in frame time and a scene load can fill it with thousands at once.
+ * @type {number}
+ */
+const MAX_ENTITIES_PER_UPDATE = 1000;
+
 export class SGMeshAnimationControllerSystem extends System {
     /**
      * Current time delta
@@ -52,6 +59,19 @@ export class SGMeshAnimationControllerSystem extends System {
         this.engine = engine;
     }
 
+    /**
+     * Bind an entity's clips, waiting for its asset.
+     *
+     * Everything here is read across a suspension point, so nothing read before the await is
+     * trusted after it. `EntityComponentDataset.getComponent` guards existence only with an
+     * `assert`, which the consumer strips, so a destroyed entity answers `undefined` rather than
+     * throwing — and this used to write `controller.bound` straight through it, inside a promise
+     * the caller did not await, so a scene transition that destroyed an entity while its glb was in
+     * flight produced an unhandled rejection with no frame or system in the trace.
+     *
+     * @param {number} entity
+     * @returns {Promise<void>}
+     */
     async #process(entity) {
         const em = this.entityManager;
 
@@ -59,8 +79,13 @@ export class SGMeshAnimationControllerSystem extends System {
 
         const mesh = ecd.getComponent(entity, SGMesh);
 
+        if (mesh === undefined) {
+            // the entity went away while it was queued
+            return;
+        }
+
         if (mesh.node === null) {
-            // requeue
+            // the scene graph has not built it yet; try again next frame
             this.#enqueue(entity);
             return;
         }
@@ -69,16 +94,26 @@ export class SGMeshAnimationControllerSystem extends System {
 
         const asset = await this.engine.assetManager.promise(mesh.url, assetType);
 
-        const three_animations = asset.animations ?? [];
+        // re-read: the entity may have been destroyed, or the mesh re-pointed, while we waited
+        const current_mesh = ecd.getComponent(entity, SGMesh);
+        const controller = ecd.getComponent(entity, SGMeshAnimationController);
 
-        const animations = three_animations.map(three_animation => {
+        if (current_mesh === undefined || controller === undefined) {
+            return;
+        }
 
-            return convert_three_clip(mesh.node, three_animation)
-        });
+        const node = current_mesh.node;
 
-        const controller = ecd.getComponent(entity, SGMeshAnimationController);
+        if (node === null) {
+            this.#enqueue(entity);
+            return;
+        }
 
-        controller.bound = animations;
+        const three_animations = asset.animations ?? [];
+
+        controller.bound = three_animations.map(
+            three_animation => convert_three_clip(node, three_animation)
+        );
     }
 
     /**
@@ -105,6 +140,26 @@ export class SGMeshAnimationControllerSystem extends System {
         await this.#process(entity);
     }
 
+    /**
+     * Take the entity out of the queue.
+     *
+     * Without this an entity destroyed while it was waiting for its node or its asset stayed in the
+     * queue for the life of the system, re-processed every frame.
+     *
+     * @param {SGMeshAnimationController} anim
+     * @param {SGMesh} mesh
+     * @param {number} entity
+     */
+    unlink(anim, mesh, entity) {
+        const queue = this.#queue;
+
+        for (let i = queue.length - 1; i >= 0; i--) {
+            if (queue[i] === entity) {
+                queue.splice(i, 1);
+            }
+        }
+    }
+
     /**
      *
      * @param {SGMeshAnimationController} controller
@@ -154,14 +209,24 @@ export class SGMeshAnimationControllerSystem extends System {
         this.#cycle_clip_advance_count = 0;
         this.#time_delta = td;
 
-        for (let i = 0; i < 1000; i++) {
-            if (this.#queue.length === 0) {
-                break;
-            }
+        /*
+         Taken out of the queue as a batch rather than popped one at a time.
+
+         The old loop popped and called `#process` up to a thousand times, and `#process` requeues
+         synchronously — before its first await — when the entity's scene-graph node is not built
+         yet. So a single entity whose node never materialised pushed itself straight back and the
+         loop span on it a thousand times every frame. A requeue now lands in the queue this drain
+         already emptied, and is retried on the NEXT frame.
 
-            const entity = this.#queue.pop();
+         The promise is not awaited — the drain must not block the frame — but it is caught, because
+         an unhandled rejection here names neither the frame nor the system.
+        */
+        const batch = this.#queue.splice(0, MAX_ENTITIES_PER_UPDATE);
 
-            this.#process(entity);
+        for (let i = 0; i < batch.length; i++) {
+            this.#process(batch[i]).catch(error => {
+                console.error(`SGMeshAnimationControllerSystem: binding entity ${batch[i]} failed`, error);
+            });
         }
 
         const ecd = this.entityManager.dataset;

package/src/engine/graphics/ecs/path/tube/build/make_ring_vertices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make_ring_vertices.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/path/tube/build/make_ring_vertices.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH,4DAbW,MAAM,MACN,MAAM,MACN,MAAM,yCAIN,MAAM,cACN,MAAM,EAAE,GAAC,YAAY,SACrB,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,mBACN,MAAM,EAAE,GAAC,YAAY,QAqI/B"}
+{"version":3,"file":"make_ring_vertices.d.ts","sourceRoot":"","sources":["../../../../../../../../src/engine/graphics/ecs/path/tube/build/make_ring_vertices.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;GAeG;AACH,4DAbW,MAAM,MACN,MAAM,MACN,MAAM,yCAIN,MAAM,cACN,MAAM,EAAE,GAAC,YAAY,SACrB,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,EAAE,GAAC,YAAY,gBACrB,MAAM,mBACN,MAAM,EAAE,GAAC,YAAY,QAmJ/B"}

package/src/engine/graphics/ecs/path/tube/build/make_ring_vertices.js

@@ -122,15 +122,29 @@ export function make_ring_vertices(
         const cross_z = bend_angle[0] * T.y - bend_angle[1] * T.x;
 
         const rotated_bend_normal_length = v3_length(cross_x, cross_y, cross_z);
-        const bend_normal_length_inv = 1 / rotated_bend_normal_length;
 
-        // apply bend angle
-        const dot = v3_dot(
-            cross_x * bend_normal_length_inv, cross_y * bend_normal_length_inv, cross_z * bend_normal_length_inv,
-            normal_x, normal_y, normal_z
-        );
-
-        bend_magnitude += Math.abs(dot) * bend_angle[3];
+        // The same guard `compute_bend_normal` puts on its own cross product,
+        // and for the same reason. Its no-bend answer is the axis `(0, 1, 0)`,
+        // which a vertical piece of path makes exactly parallel to `T` — so
+        // the cross product is zero, the reciprocal is Infinity, and
+        // `0 * Infinity` is NaN. The zero weight does NOT rescue it, because
+        // `NaN * 0` is NaN: every position in the ring comes out NaN, the
+        // geometry's AABB with it, and the BVH leaf it is written into, which
+        // makes every later frustum and ray test against that tree arbitrary.
+        // The tube then draws as nothing, which reads as a path that did not
+        // show up rather than as corruption. The normal write just above has
+        // this guard already.
+        if (rotated_bend_normal_length >= 1e-10) {
+            const bend_normal_length_inv = 1 / rotated_bend_normal_length;
+
+            // apply bend angle
+            const dot = v3_dot(
+                cross_x * bend_normal_length_inv, cross_y * bend_normal_length_inv, cross_z * bend_normal_length_inv,
+                normal_x, normal_y, normal_z
+            );
+
+            bend_magnitude += Math.abs(dot) * bend_angle[3];
+        }
 
         // compute vertex position
         const vx = Px + radial_normal_x_raw * bend_magnitude;

package/src/engine/graphics/geometry/buffered/geometry_compute_vertex_normals_indexed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geometry_compute_vertex_normals_indexed.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/geometry/buffered/geometry_compute_vertex_normals_indexed.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,mEAJW,MAAO,MAAM,CAAC,GAAC,YAAY,WAC3B,MAAO,MAAM,CAAC,GAAC,YAAY,WAC3B,MAAO,MAAM,CAAC,GAAC,WAAW,GAAC,WAAW,GAAC,UAAU,QAgC3D"}
+{"version":3,"file":"geometry_compute_vertex_normals_indexed.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/geometry/buffered/geometry_compute_vertex_normals_indexed.js"],"names":[],"mappings":"AAQA;;;;;;;;;;GAUG;AACH,mEAJW,MAAO,MAAM,CAAC,GAAC,YAAY,WAC3B,MAAO,MAAM,CAAC,GAAC,YAAY,WAC3B,MAAO,MAAM,CAAC,GAAC,WAAW,GAAC,WAAW,GAAC,UAAU,QA8C3D"}

package/src/engine/graphics/geometry/buffered/geometry_compute_vertex_normals_indexed.js

@@ -1,5 +1,7 @@
 import { v3_add_array } from "../../../../core/geom/vec3/v3_add_array.js";
-import { geometry_construct_triangle_normal } from "../geometry_construct_triangle_normal.js";
+import {
+    geometry_construct_triangle_normal_area_weighted
+} from "../geometry_construct_triangle_normal_area_weighted.js";
 import { v3_array_normalize_many } from "./v3_array_normalize_many.js";
 
 const scratch_v3 = new Float64Array(3);
@@ -29,7 +31,21 @@ export function geometry_compute_vertex_normals_indexed(
         const c = indices[i + 2];
 
 
-        geometry_construct_triangle_normal(
+        // Area-weighted, which is what makes this a port of three's pass
+        // rather than a resemblance to it: the accumulated quantity is the raw
+        // cross product, so a large face pulls its vertices harder than a
+        // sliver and the answer does not change when the same surface is
+        // retriangulated. Accumulating UNIT normals gave every incident face
+        // one equal vote — a vertex between one quad of area 100 and two
+        // bevel slivers of area 0.01 came out pointing mostly along the bevel,
+        // and slivers are exactly what decimation and CAD tessellation make.
+        //
+        // It also settles the degenerate case without a special branch: a
+        // triangle with no area has a zero cross product and contributes
+        // nothing, where the normalising helper has to synthesise a unit
+        // vector — `(0, 1, 0)`, which its own comment calls an arbitrary
+        // invalid result — and that voted at full weight against real faces.
+        geometry_construct_triangle_normal_area_weighted(
             scratch_v3, 0,
             a, b, c, positions
         );

package/src/engine/graphics/geometry/geometry_construct_triangle_normal.d.ts

@@ -6,6 +6,8 @@
  * @param {number} b
  * @param {number} c
  * @param {number[]|Float32Array} positions
+ * @returns {boolean} `false` for a triangle with no area — see
+ *   {@link tri3_compute_normal}
  */
-export function geometry_construct_triangle_normal(out: number[] | Float32Array | Float64Array, out_offset: number, a: number, b: number, c: number, positions: number[] | Float32Array): void;
+export function geometry_construct_triangle_normal(out: number[] | Float32Array | Float64Array, out_offset: number, a: number, b: number, c: number, positions: number[] | Float32Array): boolean;
 //# sourceMappingURL=geometry_construct_triangle_normal.d.ts.map

package/src/engine/graphics/geometry/geometry_construct_triangle_normal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"geometry_construct_triangle_normal.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/geometry/geometry_construct_triangle_normal.js"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wDAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,aACN,MAAM,EAAE,GAAC,YAAY,QAqB/B"}
+{"version":3,"file":"geometry_construct_triangle_normal.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/geometry/geometry_construct_triangle_normal.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wDATW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,aACN,MAAM,EAAE,GAAC,YAAY,GACnB,OAAO,CAsBnB"}

package/src/engine/graphics/geometry/geometry_construct_triangle_normal.js

@@ -8,6 +8,8 @@ import { tri3_compute_normal } from "../../../core/geom/3d/triangle/tri3_compute
  * @param {number} b
  * @param {number} c
  * @param {number[]|Float32Array} positions
+ * @returns {boolean} `false` for a triangle with no area — see
+ *   {@link tri3_compute_normal}
  */
 export function geometry_construct_triangle_normal(out, out_offset, a, b, c, positions) {
 
@@ -27,5 +29,5 @@ export function geometry_construct_triangle_normal(out, out_offset, a, b, c, pos
     const cy = positions[c_address + 1];
     const cz = positions[c_address + 2];
 
-    tri3_compute_normal(out, out_offset, ax, ay, az, bx, by, bz, cx, cy, cz);
+    return tri3_compute_normal(out, out_offset, ax, ay, az, bx, by, bz, cx, cy, cz);
 }

package/src/engine/graphics/geometry/geometry_construct_triangle_normal_area_weighted.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The face normal of an indexed triangle, NOT normalised — the raw
+ * `(c - b) × (a - b)`, whose magnitude is twice the triangle's area.
+ *
+ * That magnitude is the point. A pass that accumulates one normal per incident
+ * face and normalises at the end wants each face to pull in proportion to how
+ * much surface it is: a large quad should dominate the two slivers a bevel left
+ * beside it, and the result should not change when the same surface is
+ * retriangulated. Accumulating UNIT normals instead gives every face one equal
+ * vote, so shading follows triangulation density rather than geometry — and
+ * sliver triangles are exactly what decimation and CAD tessellation produce.
+ * three's `BufferGeometry.computeVertexNormals` accumulates this quantity, and
+ * so does everything else that gets this right.
+ *
+ * It also answers the degenerate case by itself: a triangle with no area has a
+ * zero cross product, which contributes nothing, where a normalising helper has
+ * to synthesise some arbitrary unit vector and hand it over as though it were a
+ * measurement.
+ *
+ * Single-face callers — a raycast normal, a plane side test — want
+ * {@link geometry_construct_triangle_normal} instead.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number[]|Float32Array} positions
+ * @returns {void}
+ */
+export function geometry_construct_triangle_normal_area_weighted(out: number[] | Float32Array | Float64Array, out_offset: number, a: number, b: number, c: number, positions: number[] | Float32Array): void;
+//# sourceMappingURL=geometry_construct_triangle_normal_area_weighted.d.ts.map

package/src/engine/graphics/geometry/geometry_construct_triangle_normal_area_weighted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry_construct_triangle_normal_area_weighted.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/geometry/geometry_construct_triangle_normal_area_weighted.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,sEARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,aACN,MAAM,EAAE,GAAC,YAAY,GACnB,IAAI,CAwBhB"}