@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -11,37 +11,19 @@ import { m4_make_scale } from "../mat4/m4_make_scale.js";
 import { Ray3 } from "../ray/Ray3.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 
-/**
- * In double precision, as everything that passes through it: the subject's support point goes
- * through here on its way into this frame, and in float32 a support a metre out was rounded by
- * 6e-8 m and one 1e3 m out by 6e-5 m — support planes that overstated the gap, so a cast parked
- * closer than its 1e-5 m, or stopped early.
- * @type {Float64Array}
- */
-const scratch_v3_0 = new Float64Array(3);
-
 /**
  * @type {Float64Array}
  */
 const scratch_m4_0 = new Float64Array(16);
 
 /**
- * The subject-frame query direction {@link TransformedShape3D#support} hands its subject.
- * @type {Float64Array}
- */
-const scratch_direction = new Float64Array(3);
-
-/**
- * The subject's box in {@link TransformedShape3D#compute_bounding_box}, and the copy of it the
- * projection reads. A wrapper nested in another is handed the outer one's `subject_box` as its result,
- * and the projection cannot read and write one array; the copy is taken once the subject has
- * answered, so each level is done with the first before the next writes it. In double precision, as
- * the array each call allocated held it.
- * @type {Float64Array}
+ * Everything a wrapper hands its subject — a point, a direction, a box, a ray — is the wrapper's OWN
+ * array, allocated with it, never one shared by every instance. A shared one is live across the call to
+ * the subject, and the subject may hold another wrapper: under a union, the first child's wrapper wrote
+ * its own point over the one its siblings were still to be asked about, and a wrapped union of two
+ * wrapped unit spheres answered 1.024 for a distance of 0.118. Only a cycle, which no shape can answer
+ * anyway, re-enters the same instance, so one array per instance is never in use twice.
  */
-const subject_box = new Float64Array(6);
-const subject_box_copy = new Float64Array(6);
-
 export class TransformedShape3D extends AbstractShape3D {
     /**
      * In double precision, as the points and supports mapped through it are.
@@ -63,6 +45,39 @@ export class TransformedShape3D extends AbstractShape3D {
      */
     __subject = null;
 
+    /**
+     * The subject-frame point a query hands the subject, and what the subject answers into it. In
+     * double precision, as everything that passes through it: the subject's support point goes
+     * through here on its way into this frame, and in float32 a support a metre out was rounded by
+     * 6e-8 m and one 1e3 m out by 6e-5 m — support planes that overstated the gap, so a cast parked
+     * closer than its 1e-5 m, or stopped early.
+     * @type {Float64Array}
+     * @private
+     */
+    __subject_point = new Float64Array(3);
+
+    /**
+     * The subject-frame query direction {@link support} hands its subject.
+     * @type {Float64Array}
+     * @private
+     */
+    __subject_direction = new Float64Array(3);
+
+    /**
+     * The subject's box in {@link compute_bounding_box}. In double precision, as the array each call
+     * once allocated held it.
+     * @type {Float64Array}
+     * @private
+     */
+    __subject_box = new Float64Array(6);
+
+    /**
+     * The subject-frame ray {@link raycast} hands its subject.
+     * @type {Ray3}
+     * @private
+     */
+    __subject_ray = new Ray3();
+
     /**
      *
      * @returns {AbstractShape3D|null}
@@ -168,9 +183,11 @@ export class TransformedShape3D extends AbstractShape3D {
     }
 
     get volume() {
-        m4_extract_scale(scratch_v3_0, 0, this.__matrix);
+        const scale = this.__subject_point;
+
+        m4_extract_scale(scale, 0, this.__matrix);
 
-        const scale_modifier = scratch_v3_0[0] * scratch_v3_0[1] * scratch_v3_0[2];
+        const scale_modifier = scale[0] * scale[1] * scale[2];
 
         return this.__subject.volume * scale_modifier;
     }
@@ -179,21 +196,23 @@ export class TransformedShape3D extends AbstractShape3D {
         // No array allocated per call: a physics step asks every wrapped collider for its box at
         // least twice (broadphase refit, the narrowphase's collider-pair test), and those arrays were
         // 5% of a scene of 40 compound tables' step, and much of its garbage.
-        this.__subject.compute_bounding_box(subject_box);
+        const subject_box = this.__subject_box;
 
-        subject_box_copy.set(subject_box);
+        this.__subject.compute_bounding_box(subject_box);
 
-        aabb3_matrix4_project(result, subject_box_copy, this.__matrix);
+        aabb3_matrix4_project(result, subject_box, this.__matrix);
     }
 
     signed_distance_gradient_at_point(result, point) {
+        const subject_point = this.__subject_point;
+
         // transform point to subject's local space
-        v3_matrix4_multiply(scratch_v3_0, 0, point, 0, this.__inverse_matrix);
+        v3_matrix4_multiply(subject_point, 0, point, 0, this.__inverse_matrix);
 
         const subject = this.__subject;
 
         // sample gradient at the point
-        const distance = subject.signed_distance_gradient_at_point(scratch_v3_0, scratch_v3_0);
+        const distance = subject.signed_distance_gradient_at_point(subject_point, subject_point);
 
         const m = this.__matrix;
 
@@ -213,12 +232,12 @@ export class TransformedShape3D extends AbstractShape3D {
         const scale_y = v3_length(m21, m22, m23);
         const scale_z = v3_length(m31, m32, m33);
 
-        const scaled_gx = scratch_v3_0[0] * scale_x;
-        const scaled_gy = scratch_v3_0[1] * scale_y;
-        const scaled_gz = scratch_v3_0[2] * scale_z;
+        const scaled_gx = subject_point[0] * scale_x;
+        const scaled_gy = subject_point[1] * scale_y;
+        const scaled_gz = subject_point[2] * scale_z;
 
         // normalize gradient
-        const gd = distance / v3_length(scratch_v3_0[0], scratch_v3_0[1], scratch_v3_0[2]);
+        const gd = distance / v3_length(subject_point[0], subject_point[1], subject_point[2]);
 
         const scaled_dx = scaled_gx * gd;
         const scaled_dy = scaled_gy * gd;
@@ -246,20 +265,25 @@ export class TransformedShape3D extends AbstractShape3D {
     }
 
     signed_distance_at_point(point) {
-        return this.signed_distance_gradient_at_point(scratch_v3_0, point);
+        // The gradient lands in this wrapper's own point, which the subject has answered by then.
+        return this.signed_distance_gradient_at_point(this.__subject_point, point);
     }
 
     contains_point(point) {
         // transform point to subject's local space
-        v3_matrix4_multiply(scratch_v3_0, 0, point, 0, this.__inverse_matrix);
+        const subject_point = this.__subject_point;
+
+        v3_matrix4_multiply(subject_point, 0, point, 0, this.__inverse_matrix);
 
-        return this.__subject.contains_point(scratch_v3_0);
+        return this.__subject.contains_point(subject_point);
     }
 
     sample_random_point_in_volume(result, result_offset, random) {
-        this.__subject.sample_random_point_in_volume(scratch_v3_0, 0, random);
+        const subject_point = this.__subject_point;
 
-        v3_matrix4_multiply(result, result_offset, scratch_v3_0, 0, this.__matrix);
+        this.__subject.sample_random_point_in_volume(subject_point, 0, random);
+
+        v3_matrix4_multiply(result, result_offset, subject_point, 0, this.__matrix);
     }
 
     support(result, result_offset, direction, direction_offset) {
@@ -303,14 +327,16 @@ export class TransformedShape3D extends AbstractShape3D {
             ld_x *= inv; ld_y *= inv; ld_z *= inv;
         }
 
-        // Down in module scratch: a wrapper nested in this one reads it before it writes its own there.
-        scratch_direction[0] = ld_x;
-        scratch_direction[1] = ld_y;
-        scratch_direction[2] = ld_z;
+        const subject_direction = this.__subject_direction;
+        const subject_point = this.__subject_point;
+
+        subject_direction[0] = ld_x;
+        subject_direction[1] = ld_y;
+        subject_direction[2] = ld_z;
 
-        this.__subject.support(scratch_v3_0, 0, scratch_direction, 0);
+        this.__subject.support(subject_point, 0, subject_direction, 0);
 
-        v3_matrix4_multiply(result, result_offset, scratch_v3_0, 0, this.__matrix);
+        v3_matrix4_multiply(result, result_offset, subject_point, 0, this.__matrix);
     }
 
     /**
@@ -379,9 +405,7 @@ export class TransformedShape3D extends AbstractShape3D {
 
         const inv_scale = 1 / scale;
 
-        // Allocated per call rather than kept as a module scratch: a transformed shape may wrap another
-        // wrapper, and every level of that recursion needs its own sub-ray alive across the call below.
-        const subject_ray = new Ray3();
+        const subject_ray = this.__subject_ray;
 
         v3_matrix4_multiply(subject_ray, 0, ray, 0, inverse);
 

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

@@ -20,6 +20,19 @@ export class UnionShape3D extends AbstractShape3D {
     __volume_sum: number;
     __volume_sums: any[];
     __child_volumes: any[];
+    /**
+     * Each child's box in {@link compute_bounding_box}, and the ray {@link raycast} narrows across the
+     * children. This union's own, not shared with every union: each is live across the calls to the
+     * children, and a child may hold another union. In double precision, as a child's box is.
+     * @type {Float64Array}
+     * @private
+     */
+    private __child_box;
+    /**
+     * @type {Ray3}
+     * @private
+     */
+    private __child_ray;
     compute_bounding_box(result: any): void;
     /**
      *

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

@@ -1 +1 @@
-{"version":3,"file":"UnionShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnionShape3D.js"],"names":[],"mappings":"AAkCA;IAkII;;;;OAIG;IACH,sBAHW,eAAe,EAAE,GACf,YAAY,CAYxB;IAhJD;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,kCAA+B;IAE/B,qBAAkB;IAClB,qBAAmB;IACnB,uBAAqB;IAErB,wCAgCC;IAED;;;OAGG;IACH,mCAkBC;IAED;;;OAGG;IACH,2CA+CC;IA2DD,mEAEC;IAED,6CAaC;IAED,oCAYC;IAED,kFAoDC;IAED,sFAqDC;IAiED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;IA6BL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;CApBpC;gCAtb+B,sBAAsB"}
+{"version":3,"file":"UnionShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnionShape3D.js"],"names":[],"mappings":"AAkCA;IAiJI;;;;OAIG;IACH,sBAHW,eAAe,EAAE,GACf,YAAY,CAYxB;IA/JD;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,kCAA+B;IAE/B,qBAAkB;IAClB,qBAAmB;IACnB,uBAAqB;IAErB;;;;;;OAMG;IACH,oBAAkC;IAElC;;;OAGG;IACH,oBAAyB;IAEzB,wCAgCC;IAED;;;OAGG;IACH,mCAkBC;IAED;;;OAGG;IACH,2CA+CC;IA2DD,mEAEC;IAED,6CAaC;IAED,oCAYC;IAED,kFAoDC;IAED,sFAqDC;IA+DD;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;IA6BL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;CApBpC;gCAnc+B,sBAAsB"}

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

@@ -51,6 +51,21 @@ export class UnionShape3D extends AbstractShape3D {
     __volume_sums = [];
     __child_volumes = [];
 
+    /**
+     * Each child's box in {@link compute_bounding_box}, and the ray {@link raycast} narrows across the
+     * children. This union's own, not shared with every union: each is live across the calls to the
+     * children, and a child may hold another union. In double precision, as a child's box is.
+     * @type {Float64Array}
+     * @private
+     */
+    __child_box = new Float64Array(6);
+
+    /**
+     * @type {Ray3}
+     * @private
+     */
+    __child_ray = new Ray3();
+
     compute_bounding_box(result) {
         let x0 = Infinity, y0 = Infinity, z0 = Infinity,
             x1 = -Infinity, y1 = -Infinity, z1 = -Infinity;
@@ -58,7 +73,7 @@ export class UnionShape3D extends AbstractShape3D {
         const children = this.children;
         const n = children.length;
 
-        const tmp_aabb3 = new Float32Array(6);
+        const tmp_aabb3 = this.__child_box;
 
         for (let i = 0; i < n; i++) {
             const child = children[i];
@@ -400,9 +415,7 @@ export class UnionShape3D extends AbstractShape3D {
         const ox = ray[0], oy = ray[1], oz = ray[2];
         const dx = ray[3], dy = ray[4], dz = ray[5];
 
-        // Allocated per call rather than kept as a module scratch: a union may hold another wrapper,
-        // and every level of that recursion needs its own narrowing ray alive across the loop below.
-        const child_ray = new Ray3();
+        const child_ray = this.__child_ray;
 
         child_ray[0] = ox; child_ray[1] = oy; child_ray[2] = oz;
         child_ray[3] = dx; child_ray[4] = dy; child_ray[5] = dz;

package/src/core/geom/3d/shape/record/ShapeRecord.d.ts

@@ -0,0 +1,65 @@
+/**
+ * # A shape as a row of floats — the layout, and nothing else
+ *
+ * A physics shape is a class with a prototype marker, which is what an author builds and the
+ * narrowphase asks. A loop that evaluates thousands of shapes per frame — cloth against its colliders
+ * per particle per iteration, a GPU fluid against its obstacles per cell — wants the opposite: the kind
+ * and its parameters in a typed array, so the evaluation is a branch on one number and the arithmetic
+ * of one `sdf3_*` field, with no object in reach.
+ *
+ * This is that row: a {@link ShapeRecordKind}, then four parameters in exactly the order the
+ * `core/geom/3d/shape/sdf/sdf3_*_gradient_array` forms read them, so the evaluation hands the record to
+ * the field where it sits. It is the general half of a record. A client keeps its own fields beside it
+ * — cloth's collider record holds this at its start and its friction, inflation, poses and bounds
+ * after — and indexes the shape cells as its own offset plus these.
+ *
+ * ## What is not in it
+ *
+ * **The pose.** A shape record is in the shape's own local frame. Where that frame is, is the client's:
+ * cloth interpolates two poses per substep, a GPU row reads its node. Packing a shape that only sits
+ * somewhere inside the one it was asked about — a rigid `TransformedShape3D`, a `UnionShape3D`'s
+ * children — hands back that offset pose separately; see `shape_record_pack.js`.
+ *
+ * **A hull's planes.** A convex hull has as many planes as it has sides, which no fixed row holds, so
+ * they go in a plane array the caller supplies, four floats per plane `(nx, ny, nz, d)` — the layout of
+ * `ConvexHullShape3D#face_loop_planes` and of `sdf3_plane`'s parameters — and the record holds where its
+ * run starts and how long it is. At most {@link SHAPE_RECORD_HULL_PLANE_LIMIT}.
+ *
+ * In a `Float32Array` the plane index is exact up to 2^24 planes.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/** Shape kind — a {@link ShapeRecordKind}. */
+export const SHAPE_RECORD_KIND: 0;
+/** Shape parameter 0: radius, or half-extent x, or plane normal x, or a hull's first plane. */
+export const SHAPE_RECORD_PARAM_0: 1;
+/** Shape parameter 1: height, or half-extent y, or plane normal y, or a hull's plane count. */
+export const SHAPE_RECORD_PARAM_1: 2;
+/** Shape parameter 2: half-extent z, or plane normal z, or a hull's bounding radius. */
+export const SHAPE_RECORD_PARAM_2: 3;
+/** Shape parameter 3: the plane's offset. Unused by every other kind. */
+export const SHAPE_RECORD_PARAM_3: 4;
+/** Floats in one shape record. */
+export const SHAPE_RECORD_STRIDE: 5;
+/**
+ * The most planes a hull record holds.
+ *
+ * A record is evaluated as a max over its planes, inside a loop that already runs per cell per
+ * obstacle, so the bound is on that loop: a fixed budget per obstacle, not one that grows with
+ * whatever an author built (the GPU fluid proposal's forcing pass, §10: at most 24 obstacles × 16
+ * planes a cell). Sixteen holds a box (6), a hexagonal prism (8), an octagonal one (10), a dodecahedron
+ * (12). A hull with more sides has no record, as a mesh has none — `shape_record_count` answers 0 for
+ * it — and its caller treats it as it treats a mesh.
+ *
+ * @type {number}
+ */
+export const SHAPE_RECORD_HULL_PLANE_LIMIT: number;
+/**
+ * Floats in a pose handed back by the pack: `[tx, ty, tz, qx, qy, qz, qw]`, a translation and a unit
+ * quaternion, the layout `PosedShape3D#setup_pose` reads.
+ *
+ * @type {number}
+ */
+export const SHAPE_RECORD_POSE_STRIDE: number;
+//# sourceMappingURL=ShapeRecord.d.ts.map

package/src/core/geom/3d/shape/record/ShapeRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShapeRecord.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/record/ShapeRecord.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,8CAA8C;AAC9C,kCAAmC;AAEnC,+FAA+F;AAC/F,qCAAsC;AAEtC,+FAA+F;AAC/F,qCAAsC;AAEtC,wFAAwF;AACxF,qCAAsC;AAEtC,yEAAyE;AACzE,qCAAsC;AAEtC,kCAAkC;AAClC,oCAAqC;AAErC;;;;;;;;;;;GAWG;AACH,4CAFU,MAAM,CAEgC;AAEhD;;;;;GAKG;AACH,uCAFU,MAAM,CAE0B"}

package/src/core/geom/3d/shape/record/ShapeRecord.js

@@ -0,0 +1,72 @@
+/**
+ * # A shape as a row of floats — the layout, and nothing else
+ *
+ * A physics shape is a class with a prototype marker, which is what an author builds and the
+ * narrowphase asks. A loop that evaluates thousands of shapes per frame — cloth against its colliders
+ * per particle per iteration, a GPU fluid against its obstacles per cell — wants the opposite: the kind
+ * and its parameters in a typed array, so the evaluation is a branch on one number and the arithmetic
+ * of one `sdf3_*` field, with no object in reach.
+ *
+ * This is that row: a {@link ShapeRecordKind}, then four parameters in exactly the order the
+ * `core/geom/3d/shape/sdf/sdf3_*_gradient_array` forms read them, so the evaluation hands the record to
+ * the field where it sits. It is the general half of a record. A client keeps its own fields beside it
+ * — cloth's collider record holds this at its start and its friction, inflation, poses and bounds
+ * after — and indexes the shape cells as its own offset plus these.
+ *
+ * ## What is not in it
+ *
+ * **The pose.** A shape record is in the shape's own local frame. Where that frame is, is the client's:
+ * cloth interpolates two poses per substep, a GPU row reads its node. Packing a shape that only sits
+ * somewhere inside the one it was asked about — a rigid `TransformedShape3D`, a `UnionShape3D`'s
+ * children — hands back that offset pose separately; see `shape_record_pack.js`.
+ *
+ * **A hull's planes.** A convex hull has as many planes as it has sides, which no fixed row holds, so
+ * they go in a plane array the caller supplies, four floats per plane `(nx, ny, nz, d)` — the layout of
+ * `ConvexHullShape3D#face_loop_planes` and of `sdf3_plane`'s parameters — and the record holds where its
+ * run starts and how long it is. At most {@link SHAPE_RECORD_HULL_PLANE_LIMIT}.
+ *
+ * In a `Float32Array` the plane index is exact up to 2^24 planes.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** Shape kind — a {@link ShapeRecordKind}. */
+export const SHAPE_RECORD_KIND = 0;
+
+/** Shape parameter 0: radius, or half-extent x, or plane normal x, or a hull's first plane. */
+export const SHAPE_RECORD_PARAM_0 = 1;
+
+/** Shape parameter 1: height, or half-extent y, or plane normal y, or a hull's plane count. */
+export const SHAPE_RECORD_PARAM_1 = 2;
+
+/** Shape parameter 2: half-extent z, or plane normal z, or a hull's bounding radius. */
+export const SHAPE_RECORD_PARAM_2 = 3;
+
+/** Shape parameter 3: the plane's offset. Unused by every other kind. */
+export const SHAPE_RECORD_PARAM_3 = 4;
+
+/** Floats in one shape record. */
+export const SHAPE_RECORD_STRIDE = 5;
+
+/**
+ * The most planes a hull record holds.
+ *
+ * A record is evaluated as a max over its planes, inside a loop that already runs per cell per
+ * obstacle, so the bound is on that loop: a fixed budget per obstacle, not one that grows with
+ * whatever an author built (the GPU fluid proposal's forcing pass, §10: at most 24 obstacles × 16
+ * planes a cell). Sixteen holds a box (6), a hexagonal prism (8), an octagonal one (10), a dodecahedron
+ * (12). A hull with more sides has no record, as a mesh has none — `shape_record_count` answers 0 for
+ * it — and its caller treats it as it treats a mesh.
+ *
+ * @type {number}
+ */
+export const SHAPE_RECORD_HULL_PLANE_LIMIT = 16;
+
+/**
+ * Floats in a pose handed back by the pack: `[tx, ty, tz, qx, qy, qz, qw]`, a translation and a unit
+ * quaternion, the layout `PosedShape3D#setup_pose` reads.
+ *
+ * @type {number}
+ */
+export const SHAPE_RECORD_POSE_STRIDE = 7;

package/src/core/geom/3d/shape/record/ShapeRecordKind.d.ts

@@ -0,0 +1,13 @@
+/**
+ * *
+ */
+export type ShapeRecordKind = number;
+export namespace ShapeRecordKind {
+    let Sphere: number;
+    let Capsule: number;
+    let Box: number;
+    let Cylinder: number;
+    let Plane: number;
+    let ConvexHull: number;
+}
+//# sourceMappingURL=ShapeRecordKind.d.ts.map

package/src/core/geom/3d/shape/record/ShapeRecordKind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShapeRecordKind.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/record/ShapeRecordKind.js"],"names":[],"mappings":";;;8BASU,MAAM"}

package/src/core/geom/3d/shape/record/ShapeRecordKind.js

@@ -0,0 +1,39 @@
+/**
+ * The shapes a {@link ShapeRecord} holds.
+ *
+ * The values are indices into a dispatch, so they are contiguous from zero and their order is the order
+ * `shape_record_signed_distance.js` branches in. The first five are the analytic primitives, whose
+ * parameters are what the `sdf3_*` fields read; a convex hull is a run of planes held beside the
+ * records.
+ *
+ * @readonly
+ * @enum {number}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const ShapeRecordKind = {
+    /** Radius in `SHAPE_RECORD_PARAM_0`. */
+    Sphere: 0,
+
+    /** Radius in `SHAPE_RECORD_PARAM_0`, segment length in `SHAPE_RECORD_PARAM_1`, about local Y. */
+    Capsule: 1,
+
+    /** Half-extents in `SHAPE_RECORD_PARAM_0..2`. */
+    Box: 2,
+
+    /** Radius in `SHAPE_RECORD_PARAM_0`, height in `SHAPE_RECORD_PARAM_1`, about local Y. */
+    Cylinder: 3,
+
+    /** Outward unit normal in `SHAPE_RECORD_PARAM_0..2`, offset in `SHAPE_RECORD_PARAM_3`. */
+    Plane: 4,
+
+    /**
+     * The first plane in `SHAPE_RECORD_PARAM_0` and the plane count in `SHAPE_RECORD_PARAM_1`, both
+     * indices into the plane array the record was packed with; the radius of a sphere about the local
+     * origin holding every vertex in `SHAPE_RECORD_PARAM_2`.
+     */
+    ConvexHull: 5
+};
+
+Object.freeze(ShapeRecordKind);

package/src/core/geom/3d/shape/record/shape_record_local_bounds.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The AABB of a shape record in its own local frame, ignoring pose.
+ *
+ * Written here rather than taken from `AbstractShape3D#compute_bounding_box` because a plane's box is
+ * `±Infinity` on its unbounded axes and the caller transforms this one — `0 · Infinity` is `NaN`, so an
+ * unbounded local box cannot go through a pose. A plane is therefore refused, and its caller bounds it
+ * from its world normal.
+ *
+ * Every bounded kind's box is centred on the local origin. A hull's is the cube about the sphere its
+ * record carries — a hull's planes alone do not say where its corners are — so it is loose by up to √3
+ * on a corner, and by however far the hull sits from its own origin.
+ *
+ * @param {Float64Array|number[]} out `[x0, y0, z0, x1, y1, z1]`
+ * @param {Float32Array|Float64Array|number[]} record
+ * @param {number} record_offset where the record starts
+ * @returns {boolean} `false` for an unbounded kind, in which case `out` is untouched
+ */
+export function shape_record_local_bounds(out: Float64Array | number[], record: Float32Array | Float64Array | number[], record_offset: number): boolean;
+//# sourceMappingURL=shape_record_local_bounds.d.ts.map

package/src/core/geom/3d/shape/record/shape_record_local_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape_record_local_bounds.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/record/shape_record_local_bounds.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH,+CALW,YAAY,GAAC,MAAM,EAAE,UACrB,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,iBAClC,MAAM,GACJ,OAAO,CAqCnB"}

package/src/core/geom/3d/shape/record/shape_record_local_bounds.js

@@ -0,0 +1,61 @@
+import {
+    SHAPE_RECORD_KIND,
+    SHAPE_RECORD_PARAM_0,
+    SHAPE_RECORD_PARAM_1,
+    SHAPE_RECORD_PARAM_2
+} from "./ShapeRecord.js";
+import { ShapeRecordKind } from "./ShapeRecordKind.js";
+
+/**
+ * The AABB of a shape record in its own local frame, ignoring pose.
+ *
+ * Written here rather than taken from `AbstractShape3D#compute_bounding_box` because a plane's box is
+ * `±Infinity` on its unbounded axes and the caller transforms this one — `0 · Infinity` is `NaN`, so an
+ * unbounded local box cannot go through a pose. A plane is therefore refused, and its caller bounds it
+ * from its world normal.
+ *
+ * Every bounded kind's box is centred on the local origin. A hull's is the cube about the sphere its
+ * record carries — a hull's planes alone do not say where its corners are — so it is loose by up to √3
+ * on a corner, and by however far the hull sits from its own origin.
+ *
+ * @param {Float64Array|number[]} out `[x0, y0, z0, x1, y1, z1]`
+ * @param {Float32Array|Float64Array|number[]} record
+ * @param {number} record_offset where the record starts
+ * @returns {boolean} `false` for an unbounded kind, in which case `out` is untouched
+ */
+export function shape_record_local_bounds(out, record, record_offset) {
+    const kind = record[record_offset + SHAPE_RECORD_KIND];
+
+    let hx;
+    let hy;
+    let hz;
+
+    if (kind === ShapeRecordKind.Sphere) {
+        hx = hy = hz = record[record_offset + SHAPE_RECORD_PARAM_0];
+    } else if (kind === ShapeRecordKind.Capsule) {
+        const radius = record[record_offset + SHAPE_RECORD_PARAM_0];
+
+        hx = hz = radius;
+        hy = radius + record[record_offset + SHAPE_RECORD_PARAM_1] * 0.5;
+    } else if (kind === ShapeRecordKind.Box) {
+        hx = record[record_offset + SHAPE_RECORD_PARAM_0];
+        hy = record[record_offset + SHAPE_RECORD_PARAM_1];
+        hz = record[record_offset + SHAPE_RECORD_PARAM_2];
+    } else if (kind === ShapeRecordKind.Cylinder) {
+        hx = hz = record[record_offset + SHAPE_RECORD_PARAM_0];
+        hy = record[record_offset + SHAPE_RECORD_PARAM_1] * 0.5;
+    } else if (kind === ShapeRecordKind.ConvexHull) {
+        hx = hy = hz = record[record_offset + SHAPE_RECORD_PARAM_2];
+    } else {
+        return false;
+    }
+
+    out[0] = -hx;
+    out[1] = -hy;
+    out[2] = -hz;
+    out[3] = hx;
+    out[4] = hy;
+    out[5] = hz;
+
+    return true;
+}

package/src/core/geom/3d/shape/record/shape_record_pack.d.ts

@@ -0,0 +1,88 @@
+/**
+ * # `AbstractShape3D` → shape records
+ *
+ * The one place a shape is an object rather than a row of floats. It runs when a shape is linked or
+ * changes, never per evaluation.
+ *
+ * Each kind is asked by its prototype marker, as the physics narrowphase asks.
+ *
+ * ## One shape, a run of records
+ *
+ * A shape packs into a run of records, and {@link shape_record_count} says how long:
+ *
+ * - an analytic primitive or a convex hull is one record, posed at the identity;
+ * - a `TransformedShape3D` whose matrix is a rigid motion is its subject's run, each record's pose
+ *   composed with the wrapper's — it moves the subject without changing it;
+ * - a `UnionShape3D` is its children's runs in child order, depth first; its children share its frame;
+ * - anything else is none: a mesh, a heightmap, a wrapper that scales, shears or mirrors, a hull with
+ *   no planes or more than {@link SHAPE_RECORD_HULL_PLANE_LIMIT}. A union holding any of those is none
+ *   as well — a shape packs whole or not at all, so a caller never collides against part of one.
+ *
+ * {@link shape_record_pack} writes record `element` of the run, and hands back its pose within the shape
+ * asked about. A caller packs a shape as
+ *
+ *     const n = shape_record_count(shape);
+ *     for (let i = 0; i < n; i++) {
+ *         shape_record_pack(records, i * stride, poses, i * SHAPE_RECORD_POSE_STRIDE, planes, cursor, shape, i);
+ *         cursor += shape_record_plane_count(records, i * stride);
+ *     }
+ *
+ * Nothing is allocated. Finding element `i` walks the run from its start, so packing a whole union of
+ * `n` leaves costs O(n²) — the price of one call shape for every kind, paid when a shape changes.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Write an analytic primitive's kind and parameters: a sphere, a capsule, a box, a cylinder or a plane.
+ *
+ * The five whose fields are closed-form, and the subset of {@link shape_record_pack} a client takes
+ * when it collides against nothing else. Unused parameters are written as zero.
+ *
+ * @param {Float32Array|Float64Array|number[]} record
+ * @param {number} record_offset where the record starts
+ * @param {AbstractShape3D} shape in its canonical local frame
+ * @returns {boolean} `false` if `shape` is none of the five, in which case nothing was written
+ */
+export function shape_record_pack_analytic(record: Float32Array | Float64Array | number[], record_offset: number, shape: AbstractShape3D): boolean;
+/**
+ * How many records `shape` packs into. See the module comment for what packs and how.
+ *
+ * @param {AbstractShape3D} shape
+ * @returns {number} `0` when the shape, or any part of it, has no record form
+ */
+export function shape_record_count(shape: AbstractShape3D): number;
+/**
+ * Write record `element` of `shape`'s run, and its pose within `shape`.
+ *
+ * PRECONDITION: `element < shape_record_count(shape)`. Outside it this answers `false` and writes
+ * nothing — with one exception: a hull past {@link SHAPE_RECORD_HULL_PLANE_LIMIT} asked for directly (or
+ * through rigid wrappers) fails an assertion, since it is the one refusal an author fixes by editing the
+ * shape. In a build with assertions stripped it is refused like the rest.
+ *
+ * A hull's planes go to `planes` from plane `plane_index` on, its zero planes skipped (a face with no
+ * area has an all-zero plane in `face_loop_planes`); the record holds `plane_index` and the count, which
+ * {@link shape_record_plane_count} reads back. Every other kind leaves `planes` alone.
+ *
+ * @param {Float32Array|Float64Array|number[]} record
+ * @param {number} record_offset where the record starts
+ * @param {Float32Array|Float64Array|number[]} pose receives `[tx, ty, tz, qx, qy, qz, qw]`: where the
+ *   record's local frame sits in `shape`'s, a translation and a unit quaternion
+ * @param {number} pose_offset
+ * @param {Float32Array|Float64Array} planes receives a hull's planes, four floats each `(nx, ny, nz, d)`
+ * @param {number} plane_index the first plane a hull may write, in planes rather than floats
+ * @param {AbstractShape3D} shape
+ * @param {number} element which record of the run, from 0
+ * @returns {boolean} whether the record and its pose were written
+ */
+export function shape_record_pack(record: Float32Array | Float64Array | number[], record_offset: number, pose: Float32Array | Float64Array | number[], pose_offset: number, planes: Float32Array | Float64Array, plane_index: number, shape: AbstractShape3D, element: number): boolean;
+/**
+ * How many planes a record holds in its plane array: a hull's count, and zero for every other kind. What
+ * a caller advances its plane cursor by after packing a record.
+ *
+ * @param {Float32Array|Float64Array|number[]} record
+ * @param {number} record_offset
+ * @returns {number}
+ */
+export function shape_record_plane_count(record: Float32Array | Float64Array | number[], record_offset: number): number;
+//# sourceMappingURL=shape_record_pack.d.ts.map

package/src/core/geom/3d/shape/record/shape_record_pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape_record_pack.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/record/shape_record_pack.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;;;;;GAUG;AACH,mDALW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,iBAClC,MAAM,2BAEJ,OAAO,CA0DnB;AAED;;;;;GAKG;AACH,4DAFa,MAAM,CAsClB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,0CAXW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,iBAClC,MAAM,QACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,eAElC,MAAM,UACN,YAAY,GAAC,YAAY,eACzB,MAAM,mCAEN,MAAM,GACJ,OAAO,CA4FnB;AAED;;;;;;;GAOG;AACH,iDAJW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,iBAClC,MAAM,GACJ,MAAM,CAQlB"}