@woosh/meep-engine 2.138.20 → 2.140.0

package/src/core/geom/3d/shape/Triangle3D.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Buffer-backed flyweight triangle shape.
+ *
+ * Vertex data is NOT stored on the instance — instead the triangle binds
+ * to a region of an external Float64 buffer via {@link bind}, reading
+ * 9 consecutive floats (vA.xyz, vB.xyz, vC.xyz) at the bound offset.
+ *
+ * Pattern: the narrowphase keeps one persistent `Triangle3D` per side of
+ * a contact pair and rebinds its offset while iterating decomposed
+ * triangles from a non-convex shape's enumerator. Zero allocations per
+ * iteration step — the cost of "another triangle" is a single integer
+ * offset change.
+ *
+ * The shape is convex (a triangle is the canonical 2-simplex in 3D, and
+ * GJK handles 2-simplices natively). It's degenerate in the sense that
+ * `volume = 0` and `contains_point` is always false — a triangle is a
+ * 2D surface in 3D space, no interior.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Triangle3D extends AbstractShape3D {
+    /**
+     * Convenience constructor for tests and one-off triangles.
+     * Allocates a private 9-float buffer; for hot paths use {@link bind}
+     * against a shared buffer instead.
+     *
+     * @param {number} ax
+     * @param {number} ay
+     * @param {number} az
+     * @param {number} bx
+     * @param {number} by
+     * @param {number} bz
+     * @param {number} cx
+     * @param {number} cy
+     * @param {number} cz
+     * @returns {Triangle3D}
+     */
+    static from(ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number): Triangle3D;
+    /**
+     * External buffer holding vertex data.
+     * @type {Float64Array | null}
+     */
+    buffer: Float64Array | null;
+    /**
+     * Float-index of vA.x in {@link buffer}. The other 8 floats
+     * (vA.yz, vB.xyz, vC.xyz) follow consecutively.
+     * @type {number}
+     */
+    offset: number;
+    /**
+     * Bind this triangle to a region of an external buffer. Reads 9
+     * consecutive floats starting at `offset`.
+     *
+     * @param {Float64Array} buffer
+     * @param {number} offset float-index of vA.x in the buffer
+     * @returns {Triangle3D} this (for chaining)
+     */
+    bind(buffer: Float64Array, offset: number): Triangle3D;
+    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    compute_bounding_box(result: any): void;
+    /**
+     * A triangle has zero interior volume.
+     */
+    contains_point(_point: any): boolean;
+    /**
+     * Signed distance has a well-defined sign relative to the triangle's
+     * face plane: positive on the side that the face normal points to
+     * (normal = (B-A) × (C-A), CCW convention), negative on the other.
+     *
+     * Magnitude is the true point-to-triangle distance (handles vertex,
+     * edge, and face Voronoi regions correctly via
+     * {@link computeTriangleClosestPointToPointBarycentric}).
+     */
+    signed_distance_at_point(point: any): number;
+    nearest_point_on_surface(result: any, reference: any): void;
+    /**
+     * Uniform random barycentric sample within the triangle.
+     * Triangles have no interior, so the sample lies on the surface.
+     */
+    sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
+    /**
+     * @param {Triangle3D} other
+     * @returns {boolean}
+     */
+    equals(other: Triangle3D): boolean;
+    /**
+     * Fast type-check marker.
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isTriangle3D: boolean;
+}
+import { AbstractShape3D } from "./AbstractShape3D.js";
+//# sourceMappingURL=Triangle3D.d.ts.map

package/src/core/geom/3d/shape/Triangle3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Triangle3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/Triangle3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAmCI;;;;;;;;;;;;;;;OAeG;IACH,gBAXW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,UAAU,CAWtB;IAxDG;;;OAGG;IACH,QAFU,YAAY,GAAG,IAAI,CAEX;IAElB;;;;OAIG;IACH,QAFU,MAAM,CAED;IAGnB;;;;;;;OAOG;IACH,aAJW,YAAY,UACZ,MAAM,GACJ,UAAU,CAStB;IA6BD,qGAyBC;IAED,wCAeC;IAED;;OAEG;IACH,qCAEC;IAED;;;;;;;;OAQG;IACH,6CA4CC;IAED,4DAwBC;IAED;;;OAGG;IACH,kFAsBC;IAwBD;;;OAGG;IACH,cAHW,UAAU,GACR,OAAO,CAenB;IAgBL;;;;OAIG;IACH,uBAFU,OAAO,CAEgB;CAPhC;gCA1S+B,sBAAsB"}

package/src/core/geom/3d/shape/Triangle3D.js

@@ -0,0 +1,318 @@
+import { assert } from "../../../assert.js";
+import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.js";
+import { v3_length } from "../../vec3/v3_length.js";
+import { computeTriangleClosestPointToPointBarycentric } from "../triangle/computeTriangleClosestPointToPointBarycentric.js";
+import { AbstractShape3D } from "./AbstractShape3D.js";
+
+/**
+ * Buffer-backed flyweight triangle shape.
+ *
+ * Vertex data is NOT stored on the instance — instead the triangle binds
+ * to a region of an external Float64 buffer via {@link bind}, reading
+ * 9 consecutive floats (vA.xyz, vB.xyz, vC.xyz) at the bound offset.
+ *
+ * Pattern: the narrowphase keeps one persistent `Triangle3D` per side of
+ * a contact pair and rebinds its offset while iterating decomposed
+ * triangles from a non-convex shape's enumerator. Zero allocations per
+ * iteration step — the cost of "another triangle" is a single integer
+ * offset change.
+ *
+ * The shape is convex (a triangle is the canonical 2-simplex in 3D, and
+ * GJK handles 2-simplices natively). It's degenerate in the sense that
+ * `volume = 0` and `contains_point` is always false — a triangle is a
+ * 2D surface in 3D space, no interior.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Triangle3D extends AbstractShape3D {
+    constructor() {
+        super();
+
+        /**
+         * External buffer holding vertex data.
+         * @type {Float64Array | null}
+         */
+        this.buffer = null;
+
+        /**
+         * Float-index of vA.x in {@link buffer}. The other 8 floats
+         * (vA.yz, vB.xyz, vC.xyz) follow consecutively.
+         * @type {number}
+         */
+        this.offset = 0;
+    }
+
+    /**
+     * Bind this triangle to a region of an external buffer. Reads 9
+     * consecutive floats starting at `offset`.
+     *
+     * @param {Float64Array} buffer
+     * @param {number} offset float-index of vA.x in the buffer
+     * @returns {Triangle3D} this (for chaining)
+     */
+    bind(buffer, offset) {
+        assert.isNonNegativeInteger(offset, "offset");
+
+        this.buffer = buffer;
+        this.offset = offset;
+
+        return this;
+    }
+
+    /**
+     * Convenience constructor for tests and one-off triangles.
+     * Allocates a private 9-float buffer; for hot paths use {@link bind}
+     * against a shared buffer instead.
+     *
+     * @param {number} ax
+     * @param {number} ay
+     * @param {number} az
+     * @param {number} bx
+     * @param {number} by
+     * @param {number} bz
+     * @param {number} cx
+     * @param {number} cy
+     * @param {number} cz
+     * @returns {Triangle3D}
+     */
+    static from(ax, ay, az, bx, by, bz, cx, cy, cz) {
+        const buf = new Float64Array(9);
+        buf[0] = ax; buf[1] = ay; buf[2] = az;
+        buf[3] = bx; buf[4] = by; buf[5] = bz;
+        buf[6] = cx; buf[7] = cy; buf[8] = cz;
+
+        const t = new Triangle3D();
+        t.bind(buf, 0);
+        return t;
+    }
+
+    support(result, result_offset, direction_x, direction_y, direction_z) {
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        const da = ax * direction_x + ay * direction_y + az * direction_z;
+        const db = bx * direction_x + by * direction_y + bz * direction_z;
+        const dc = cx * direction_x + cy * direction_y + cz * direction_z;
+
+        if (da >= db && da >= dc) {
+            result[result_offset    ] = ax;
+            result[result_offset + 1] = ay;
+            result[result_offset + 2] = az;
+        } else if (db >= dc) {
+            result[result_offset    ] = bx;
+            result[result_offset + 1] = by;
+            result[result_offset + 2] = bz;
+        } else {
+            result[result_offset    ] = cx;
+            result[result_offset + 1] = cy;
+            result[result_offset + 2] = cz;
+        }
+    }
+
+    compute_bounding_box(result) {
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        result[0] = ax < bx ? (ax < cx ? ax : cx) : (bx < cx ? bx : cx);
+        result[1] = ay < by ? (ay < cy ? ay : cy) : (by < cy ? by : cy);
+        result[2] = az < bz ? (az < cz ? az : cz) : (bz < cz ? bz : cz);
+
+        result[3] = ax > bx ? (ax > cx ? ax : cx) : (bx > cx ? bx : cx);
+        result[4] = ay > by ? (ay > cy ? ay : cy) : (by > cy ? by : cy);
+        result[5] = az > bz ? (az > cz ? az : cz) : (bz > cz ? bz : cz);
+    }
+
+    /**
+     * A triangle has zero interior volume.
+     */
+    contains_point(_point) {
+        return false;
+    }
+
+    /**
+     * Signed distance has a well-defined sign relative to the triangle's
+     * face plane: positive on the side that the face normal points to
+     * (normal = (B-A) × (C-A), CCW convention), negative on the other.
+     *
+     * Magnitude is the true point-to-triangle distance (handles vertex,
+     * edge, and face Voronoi regions correctly via
+     * {@link computeTriangleClosestPointToPointBarycentric}).
+     */
+    signed_distance_at_point(point) {
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        const px = point[0]; const py = point[1]; const pz = point[2];
+
+        computeTriangleClosestPointToPointBarycentric(
+            scratch_bary, 0,
+            px, py, pz,
+            ax, ay, az,
+            bx, by, bz,
+            cx, cy, cz
+        );
+
+        // result format: [alpha_A, alpha_B]; alpha_C = 1 - alpha_A - alpha_B
+        const alpha_a = scratch_bary[0];
+        const alpha_b = scratch_bary[1];
+        const alpha_c = 1 - alpha_a - alpha_b;
+
+        const closest_x = alpha_a * ax + alpha_b * bx + alpha_c * cx;
+        const closest_y = alpha_a * ay + alpha_b * by + alpha_c * cy;
+        const closest_z = alpha_a * az + alpha_b * bz + alpha_c * cz;
+
+        const dx = px - closest_x;
+        const dy = py - closest_y;
+        const dz = pz - closest_z;
+
+        const distance = v3_length(dx, dy, dz);
+
+        // face normal = (B - A) × (C - A)  — CCW convention
+        const e1x = bx - ax; const e1y = by - ay; const e1z = bz - az;
+        const e2x = cx - ax; const e2y = cy - ay; const e2z = cz - az;
+
+        const nx = e1y * e2z - e1z * e2y;
+        const ny = e1z * e2x - e1x * e2z;
+        const nz = e1x * e2y - e1y * e2x;
+
+        const side = (px - ax) * nx + (py - ay) * ny + (pz - az) * nz;
+
+        return side >= 0 ? distance : -distance;
+    }
+
+    nearest_point_on_surface(result, reference) {
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        computeTriangleClosestPointToPointBarycentric(
+            scratch_bary, 0,
+            reference[0], reference[1], reference[2],
+            ax, ay, az,
+            bx, by, bz,
+            cx, cy, cz
+        );
+
+        // result format: [alpha_A, alpha_B]; alpha_C = 1 - alpha_A - alpha_B
+        const alpha_a = scratch_bary[0];
+        const alpha_b = scratch_bary[1];
+        const alpha_c = 1 - alpha_a - alpha_b;
+
+        result[0] = alpha_a * ax + alpha_b * bx + alpha_c * cx;
+        result[1] = alpha_a * ay + alpha_b * by + alpha_c * cy;
+        result[2] = alpha_a * az + alpha_b * bz + alpha_c * cz;
+    }
+
+    /**
+     * Uniform random barycentric sample within the triangle.
+     * Triangles have no interior, so the sample lies on the surface.
+     */
+    sample_random_point_in_volume(result, result_offset, random) {
+        let r1 = random();
+        let r2 = random();
+
+        // unit-square reflection trick for uniform-barycentric sampling
+        if (r1 + r2 > 1) {
+            r1 = 1 - r1;
+            r2 = 1 - r2;
+        }
+
+        const r0 = 1 - r1 - r2;
+
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        result[result_offset    ] = r0 * ax + r1 * bx + r2 * cx;
+        result[result_offset + 1] = r0 * ay + r1 * by + r2 * cy;
+        result[result_offset + 2] = r0 * az + r1 * bz + r2 * cz;
+    }
+
+    get volume() {
+        return 0;
+    }
+
+    get surface_area() {
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        const e1x = bx - ax; const e1y = by - ay; const e1z = bz - az;
+        const e2x = cx - ax; const e2y = cy - ay; const e2z = cz - az;
+
+        const nx = e1y * e2z - e1z * e2y;
+        const ny = e1z * e2x - e1x * e2z;
+        const nz = e1x * e2y - e1y * e2x;
+
+        return 0.5 * v3_length(nx, ny, nz);
+    }
+
+    /**
+     * @param {Triangle3D} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (!super.equals(other)) return false;
+
+        const a = this.buffer;
+        const ao = this.offset;
+        const b = other.buffer;
+        const bo = other.offset;
+
+        for (let i = 0; i < 9; i++) {
+            if (a[ao + i] !== b[bo + i]) return false;
+        }
+
+        return true;
+    }
+
+    hash() {
+        const b = this.buffer;
+        const o = this.offset;
+
+        let h = 0;
+
+        for (let i = 0; i < 9; i++) {
+            h = ((h << 5) - h + computeHashFloat(b[o + i])) | 0;
+        }
+
+        return h;
+    }
+}
+
+/**
+ * Fast type-check marker.
+ * @readonly
+ * @type {boolean}
+ */
+Triangle3D.prototype.isTriangle3D = true;
+
+/**
+ * Scratch for barycentric output from {@link computeTriangleClosestPointToPointBarycentric}.
+ * Module-scoped because every triangle method that needs barycentric
+ * coords does it strictly inline — no nested calls that could re-enter.
+ * @type {Float64Array}
+ */
+const scratch_bary = new Float64Array(2);

package/src/core/geom/3d/shape/UnionShape3D.js

@@ -352,3 +352,16 @@ export class UnionShape3D extends AbstractShape3D {
         return hash;
     }
 }
+
+/**
+ * The set-union of convex shapes is convex only in the trivial cases (one
+ * child, or fully overlapping children). The general case is non-convex,
+ * so the narrowphase must decompose the union into its children and run
+ * per-child GJK against the other body, then merge the resulting contact
+ * manifolds. Treating the union as a single convex blob via GJK on a
+ * combined support would conflate distinct children into a fake hull.
+ *
+ * @readonly
+ * @type {boolean}
+ */
+UnionShape3D.prototype.is_convex = false;

package/src/core/geom/3d/shape/UnitCubeShape3D.d.ts

@@ -1,12 +1,40 @@
-export class UnitCubeShape3D extends AbstractShape3D {
+/**
+ * Unit cube centred at the origin, spanning `[-0.5, 0.5]` on every axis.
+ *
+ * @deprecated Use {@link BoxShape3D} instead — UnitCubeShape3D is now a thin
+ * subclass that just pins `half_extents` to `(0.5, 0.5, 0.5)`. All geometry
+ * (`support`, `signed_distance_at_point`, `volume`, `surface_area`,
+ * `nearest_point_on_surface`, ...) is inherited from {@link BoxShape3D}.
+ *
+ * Kept only for:
+ *   - the `UnitCubeShape3D.INSTANCE` shared singleton that scenes and tests
+ *     embed by reference
+ *   - the JSON `'cube'` type-tag round-trip in `shape_to_type` /
+ *     `type_adapters` (an `instanceof` check, which is why we still need a
+ *     distinct subclass rather than a constant `BoxShape3D` instance)
+ *
+ * For new code prefer:
+ *   - `new BoxShape3D()` — also defaults to half-extents `(0.5, 0.5, 0.5)`
+ *   - `BoxShape3D.from_size(w, h, d)` — express by full side lengths
+ *   - `BoxShape3D.from(hx, hy, hz)` — express by half-extents
+ */
+export class UnitCubeShape3D extends BoxShape3D {
+    /**
+     * Shared singleton. Many call sites — JSON deserialisation, tests,
+     * `TransformedShape3D.from_translation(UnitCubeShape3D.INSTANCE, ...)`
+     * — embed this by reference rather than allocating a fresh cube.
+     * @type {UnitCubeShape3D}
+     */
     static INSTANCE: UnitCubeShape3D;
-    compute_bounding_box(result: any): void;
-    nearest_point_on_surface(result: any, reference: any): void;
-    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
-    signed_distance_gradient_at_point(result: any, point: any): number;
-    signed_distance_at_point(point: any): number;
-    contains_point(point: any): boolean;
-    sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
+    /**
+     * @deprecated Prefer dispatching on `isBoxShape3D`, which is `true` for both
+     * UnitCubeShape3D (inherited via prototype chain) and {@link BoxShape3D}.
+     * Retained so any older external code that already narrowed via this marker
+     * keeps working.
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isUnitCubeShape3D: boolean;
 }
-import { AbstractShape3D } from "./AbstractShape3D.js";
+import { BoxShape3D } from "./BoxShape3D.js";
 //# sourceMappingURL=UnitCubeShape3D.d.ts.map

package/src/core/geom/3d/shape/UnitCubeShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UnitCubeShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnitCubeShape3D.js"],"names":[],"mappings":"AAUA;IAsFI,iCAAwC;IA5ExC,wCAQC;IAED,4DAYC;IAED,qGAIC;IAED,mEAEC;IAED,6CAqBC;IAED,oCASC;IAED,kFAEC;CAOJ;gCA1F+B,sBAAsB"}
+{"version":3,"file":"UnitCubeShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnitCubeShape3D.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAKI;;;;;OAKG;IACH,iBAFU,eAAe,CAEe;IAG5C;;;;;;;OAOG;IACH,4BAFU,OAAO,CAE0B;CAV1C;2BAlC0B,iBAAiB"}

package/src/core/geom/3d/shape/UnitCubeShape3D.js

@@ -1,98 +1,45 @@
-import { max2 } from "../../../math/max2.js";
-import { max3 } from "../../../math/max3.js";
-import { min2 } from "../../../math/min2.js";
-import { sign_not_zero } from "../../../math/sign_not_zero.js";
-import { randomPointInBox } from "../../random/randomPointInBox.js";
-import { v3_length } from "../../vec3/v3_length.js";
-import { aabb3_nearest_point_on_surface } from "../aabb/aabb3_nearest_point_on_surface.js";
-import { AbstractShape3D } from "./AbstractShape3D.js";
-import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
-
-export class UnitCubeShape3D extends AbstractShape3D {
-
-    get volume() {
-        return 1;
-    }
-
-    get surface_area() {
-        return 6;
-    }
-
-    compute_bounding_box(result) {
-        result[0] = -0.5;
-        result[1] = -0.5;
-        result[2] = -0.5;
-
-        result[3] = 0.5;
-        result[4] = 0.5;
-        result[5] = 0.5;
-    }
-
-    nearest_point_on_surface(result, reference) {
-        const r_x = reference[0];
-        const r_y = reference[1];
-        const r_z = reference[2];
-
-        aabb3_nearest_point_on_surface(
-            result,
-            -0.5, -0.5, -0.5,
-            0.5, 0.5, 0.5,
-            r_x, r_y, r_z
-        );
-
-    }
-
-    support(result, result_offset, direction_x, direction_y, direction_z) {
-        result[result_offset] = sign_not_zero(direction_x) * 0.5;
-        result[result_offset + 1] = sign_not_zero(direction_y) * 0.5;
-        result[result_offset + 2] = sign_not_zero(direction_z) * 0.5;
-    }
-
-    signed_distance_gradient_at_point(result, point) {
-        return compute_signed_distance_gradient_by_sampling(result, this, point);
-    }
-
-    signed_distance_at_point(point) {
-        /*
-        based on https://www.iquilezles.org/www/articles/distfunctions/distfunctions.htm
-        original shader code:
-            ------------
-            float sdBox( vec3 p, vec3 b )
-            {
-              vec3 q = abs(p) - b;
-              return length(max(q,0.0)) + min(max(q.x,max(q.y,q.z)),0.0);
-            }
-            ------------
-         */
-        const q_x = Math.abs(point[0]) - 0.5;
-        const q_y = Math.abs(point[1]) - 0.5;
-        const q_z = Math.abs(point[2]) - 0.5;
-
-        return v3_length(
-            max2(q_x, 0),
-            max2(q_y, 0),
-            max2(q_z, 0)
-        ) + min2(max3(q_x, q_y, q_z), 0);
-    }
-
-    contains_point(point) {
-        const x = point[0];
-        const y = point[1];
-        const z = point[2];
-
-        return x > -0.5 && x < 0.5
-            && y > -0.5 && y < 0.5
-            && z > -0.5 && z < 0.5
-            ;
-    }
-
-    sample_random_point_in_volume(result, result_offset, random) {
-        randomPointInBox(random, result, result_offset);
-    }
-
-    hash() {
-        return 1;
-    }
-
-    static INSTANCE = new UnitCubeShape3D();
-}
+import { BoxShape3D } from "./BoxShape3D.js";
+
+/**
+ * Unit cube centred at the origin, spanning `[-0.5, 0.5]` on every axis.
+ *
+ * @deprecated Use {@link BoxShape3D} instead — UnitCubeShape3D is now a thin
+ * subclass that just pins `half_extents` to `(0.5, 0.5, 0.5)`. All geometry
+ * (`support`, `signed_distance_at_point`, `volume`, `surface_area`,
+ * `nearest_point_on_surface`, ...) is inherited from {@link BoxShape3D}.
+ *
+ * Kept only for:
+ *   - the `UnitCubeShape3D.INSTANCE` shared singleton that scenes and tests
+ *     embed by reference
+ *   - the JSON `'cube'` type-tag round-trip in `shape_to_type` /
+ *     `type_adapters` (an `instanceof` check, which is why we still need a
+ *     distinct subclass rather than a constant `BoxShape3D` instance)
+ *
+ * For new code prefer:
+ *   - `new BoxShape3D()` — also defaults to half-extents `(0.5, 0.5, 0.5)`
+ *   - `BoxShape3D.from_size(w, h, d)` — express by full side lengths
+ *   - `BoxShape3D.from(hx, hy, hz)` — express by half-extents
+ */
+export class UnitCubeShape3D extends BoxShape3D {
+    // No constructor / no method overrides on purpose. BoxShape3D's
+    // constructor already sets half_extents to (0.5, 0.5, 0.5), and every
+    // geometry method is correct for that case verbatim.
+
+    /**
+     * Shared singleton. Many call sites — JSON deserialisation, tests,
+     * `TransformedShape3D.from_translation(UnitCubeShape3D.INSTANCE, ...)`
+     * — embed this by reference rather than allocating a fresh cube.
+     * @type {UnitCubeShape3D}
+     */
+    static INSTANCE = new UnitCubeShape3D();
+}
+
+/**
+ * @deprecated Prefer dispatching on `isBoxShape3D`, which is `true` for both
+ * UnitCubeShape3D (inherited via prototype chain) and {@link BoxShape3D}.
+ * Retained so any older external code that already narrowed via this marker
+ * keeps working.
+ * @readonly
+ * @type {boolean}
+ */
+UnitCubeShape3D.prototype.isUnitCubeShape3D = true;

package/src/core/geom/3d/shape/UnitSphereShape3D.d.ts

@@ -9,6 +9,16 @@ export class UnitSphereShape3D extends AbstractShape3D {
     signed_distance_at_point(point: any): number;
     contains_point(point: any): boolean;
     sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
+    /**
+     * Fast type-check marker (mirrors {@link Transform.prototype.isTransform}). Lets
+     * downstream code dispatch on shape kind without instanceof / import coupling.
+     * Use case: physics narrowphase short-circuits sphere-sphere to a closed-form
+     * solution rather than running GJK+EPA on a smooth surface (which is the EPA
+     * degenerate case).
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isUnitSphereShape3D: boolean;
 }
 export namespace UnitSphereShape3D {
     let INSTANCE: UnitSphereShape3D;

package/src/core/geom/3d/shape/UnitSphereShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UnitSphereShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnitSphereShape3D.js"],"names":[],"mappings":"AAKA;;GAEG;AACH;IASI,qGAQC;IAED,wCAQC;IAED,4DAYC;IAED,mEAEC;IAED,6CAMC;IAED,oCAMC;IAED,kFAEC;CAKJ;;;;gCA5E+B,sBAAsB"}
+{"version":3,"file":"UnitSphereShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnitSphereShape3D.js"],"names":[],"mappings":"AAKA;;GAEG;AACH;IASI,qGAQC;IAED,wCAQC;IAED,4DAYC;IAED,mEAEC;IAED,6CAMC;IAED,oCAMC;IAED,kFAEC;IASL;;;;;;;;OAQG;IACH,8BAFU,OAAO,CAE8B;CAb9C;;;;gCA5E+B,sBAAsB"}

package/src/core/geom/3d/shape/UnitSphereShape3D.js

@@ -79,3 +79,14 @@ export class UnitSphereShape3D extends AbstractShape3D {
 }
 
 UnitSphereShape3D.INSTANCE = new UnitSphereShape3D();
+
+/**
+ * Fast type-check marker (mirrors {@link Transform.prototype.isTransform}). Lets
+ * downstream code dispatch on shape kind without instanceof / import coupling.
+ * Use case: physics narrowphase short-circuits sphere-sphere to a closed-form
+ * solution rather than running GJK+EPA on a smooth surface (which is the EPA
+ * degenerate case).
+ * @readonly
+ * @type {boolean}
+ */
+UnitSphereShape3D.prototype.isUnitSphereShape3D = true;