@woosh/meep-engine 3.25.0 → 3.27.0

package/src/core/binary/lz4/lz4_decompress_block.d.ts

@@ -6,7 +6,8 @@
  * its low nibble the match length less four; either saturates at fifteen and continues in whole
  * bytes, a 255 meaning "and more". The match's distance is a 16-bit little-endian offset back from
  * the write head, and it is allowed to reach into bytes this same sequence is producing — that
- * overlap is how the format codes runs, so the copy has to go a byte at a time.
+ * overlap is how the format codes runs, so a match that reaches back less far than it is long is
+ * copied a byte at a time.
  *
  * Blocks here are independent: a match reaches back no further than `destination_offset`, never
  * into whatever a previous block left in the buffer. That is what `LZ4_compress_default` produces

package/src/core/binary/lz4/lz4_decompress_block.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lz4_decompress_block.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/lz4/lz4_decompress_block.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,kDATW,UAAU,sBACV,MAAM,mBACN,MAAM,UACN,UAAU,iBACV,MAAM,cACN,MAAM,GACJ,MAAM,CA8GlB"}
+{"version":3,"file":"lz4_decompress_block.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/lz4/lz4_decompress_block.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,kDATW,UAAU,sBACV,MAAM,mBACN,MAAM,UACN,UAAU,iBACV,MAAM,cACN,MAAM,GACJ,MAAM,CAyHlB"}

package/src/core/binary/lz4/lz4_decompress_block.js

@@ -1,5 +1,18 @@
 import { assert } from "../../assert.js";
 
+/**
+ * Runs shorter than this are cheaper to copy a byte at a time than to hand to `set` or
+ * `copyWithin`, whose call overhead dominates until there is a memmove's worth of work behind it.
+ * Both halves earn their keep, and on real geometry it is the literals that carry the win: four
+ * fifths of a decoded `.vgeo` page arrives as literal runs of about thirty-five bytes, while its
+ * matches average nine and stay in the loop whatever this is set to.
+ *
+ * Swept on 2,267 real pages at both block shapes. The top of the curve is broad — anything from
+ * sixteen up is most of the win — and this is where it sits, which is also where
+ * {@link lz4_compress_block} put its own, arrived at separately and on literals alone.
+ */
+const BULK_COPY_LENGTH = 32;
+
 /**
  * Decode one LZ4 block.
  *
@@ -8,7 +21,8 @@ import { assert } from "../../assert.js";
  * its low nibble the match length less four; either saturates at fifteen and continues in whole
  * bytes, a 255 meaning "and more". The match's distance is a 16-bit little-endian offset back from
  * the write head, and it is allowed to reach into bytes this same sequence is producing — that
- * overlap is how the format codes runs, so the copy has to go a byte at a time.
+ * overlap is how the format codes runs, so a match that reaches back less far than it is long is
+ * copied a byte at a time.
  *
  * Blocks here are independent: a match reaches back no further than `destination_offset`, never
  * into whatever a previous block left in the buffer. That is what `LZ4_compress_default` produces
@@ -72,8 +86,12 @@ export function lz4_decompress_block(destination, destination_offset, destinatio
             );
         }
 
-        for (let i = 0; i < literal_length; i++) {
-            destination[d + i] = source[s + i];
+        if (literal_length >= BULK_COPY_LENGTH) {
+            destination.set(source.subarray(s, s + literal_length), d);
+        } else {
+            for (let i = 0; i < literal_length; i++) {
+                destination[d + i] = source[s + i];
+            }
         }
 
         d += literal_length;
@@ -127,9 +145,16 @@ export function lz4_decompress_block(destination, destination_offset, destinatio
             );
         }
 
-        // a byte at a time: the match is allowed to overlap what it is writing, which is how runs are coded
-        for (let i = 0; i < match_length; i++) {
-            destination[d + i] = destination[match_position + i];
+        // A match that does not reach back as far as it is long overlaps the bytes it is writing, and
+        // that is how the format codes runs: `copyWithin` moves as if through a temporary, so it
+        // would lay down one copy of the pattern where the format means it to repeat. Only a match
+        // clear of its own output can take it, and the byte loop below is the run.
+        if (match_length >= BULK_COPY_LENGTH && match_offset >= match_length) {
+            destination.copyWithin(d, match_position, match_position + match_length);
+        } else {
+            for (let i = 0; i < match_length; i++) {
+                destination[d + i] = destination[match_position + i];
+            }
         }
 
         d += match_length;

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

@@ -158,6 +158,72 @@ export class HeightMapShape3D extends AbstractShape3D {
      * site is forced to handle heightmaps explicitly.
      */
     support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    /**
+     * Nearest ray hit against the height-field SURFACE, in the shape's body-local
+     * frame. Writes `[px, py, pz, nx, ny, nz]` into `hit` and returns true; a miss
+     * returns false and leaves `hit` untouched.
+     *
+     * ## What is hit
+     *
+     * The surface, not the solid. The class models a closed volume (floor at h=0,
+     * height field above), but a ray meets only the height field — there is no
+     * floor quad and no side skirt, so a ray that passes under the terrain or
+     * enters through the footprint edge below the surface reports a miss. That is
+     * the same body {@link heightmap_enumerate_triangles} hands the contact
+     * narrowphase, and the same body the terrain renderer draws; a raycast that
+     * answered for the skirt would disagree with both. Mirrors
+     * {@link MeshShape3D#raycast}, which is likewise surface-only.
+     *
+     * Precisely the same triangles, too: the traversal reads its corner heights at
+     * the identical `i / seg_u` / `j / seg_v` UVs through the identical Catmull-Rom
+     * filter, and splits each sub-cell on the same lower-left diagonal
+     * (`(A,D,B)`, `(D,C,B)`), so a cast and a contact resolve against a surface
+     * that agrees bit for bit — {@link tessellation} included.
+     *
+     * NORMAL: the triangle's geometric normal, flipped to face the incoming ray
+     * (the shared {@link tri3_raycast} convention). A cast from below the terrain
+     * therefore reports a downward normal, not the surface's true upward one.
+     *
+     * A hit landing exactly ON a seam between facets gets the normal of one of the
+     * facets meeting there. INSIDE a sub-cell the two paths agree — they split on
+     * the same D–B diagonal and break the resulting tie in favour of the same
+     * facet — which matters because that diagonal runs through the sub-cell's
+     * centre, so a cast down the middle of a cell lands on it routinely rather
+     * than exceptionally.
+     *
+     * BETWEEN sub-cells they can differ, and which facet each names follows from
+     * traversal order: this walks the grid along the ray, the narrowphase
+     * enumerates it row-major, so on a grid line — and especially a grid corner,
+     * where four facets meet — the two can name different facets. The hit POINT
+     * still agrees; a faceted surface simply has no single normal at a seam.
+     * Measure-zero, and called out because it is the only place the two answers
+     * part company.
+     *
+     * `size.y` does NOT bound the query. Sampler values are not clamped to it (see
+     * the class docstring), so clipping the ray to the height range that
+     * {@link compute_bounding_box} reports could reject real surface standing above
+     * it; only the footprint is clipped against.
+     *
+     * ## Cost
+     *
+     * A 2-D DDA over the `(W−1)·N × (H−1)·N` sub-cell grid, two triangles per cell,
+     * stopping at the first cell that hits — cells are visited in increasing ray
+     * order and a sub-cell's triangles project exactly onto its own footprint
+     * rectangle, so nothing behind can be nearer. O(cells the ray crosses), not
+     * O(cells in the ray's bounding box): a long diagonal cast costs the grid's
+     * diagonal rather than its area.
+     *
+     * Four Catmull-Rom evaluations per cell, uncached — deliberately unlike
+     * {@link heightmap_enumerate_triangles}, whose corner-row cache exists because
+     * the contact narrowphase re-samples the same rect every substep. A ray walks
+     * a diagonal, visits each cell once, and stops early; there is nothing to
+     * amortise against.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray body-local ray (unit direction; `ray[6]` = tMax)
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit: Float32Array | number[], ray: Ray3): boolean;
     sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
     /**
      * @param {HeightMapShape3D} other

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

@@ -1 +1 @@
-{"version":3,"file":"HeightMapShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/HeightMapShape3D.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IA4DI;;;;;;;;;;;OAWG;IACH,wCATW,MAAM,UACN,MAAM,UACN,MAAM,gBACN,OAAO,iBACP,MAAM,GAGJ,gBAAgB,CAqB5B;IA1FD;;;;;OAKG;IACH,sBAFU,OAAO,CAEkB;IAEnC;;;;;;;OAOG;IACH,eAFU,OAAO,CAEW;IAE5B;;;;;OAKG;IACH,SAFU,YAAY,IAAI,CAEX;IAEf;;;;;;;;;;;;;;;;OAgBG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;OAKG;IACH,eAA6B;IAG7B,6BAA2B;IAE3B,6BAA2B;IAC3B,6BAA2B;IAmC3B;;;;;;;;;OASG;IACH,sBA+CC;IAED;;;;;;OAMG;IACH,yBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,8BALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAelB;IAED,wCA8BC;IAED,oCA2BC;IAED;;;;;;;;OAQG;IACH,6CAmBC;IAED;;;;OAIG;IACH,4DA2BC;IAED;;;;;;;;;OASG;IACH,qGAEC;IAED,kFAiBC;IA6CD;;;OAGG;IACH,cAHW,gBAAgB,GACd,OAAO,CAUnB;IAWL;;;;;;OAMG;IACH,6BAFU,OAAO,CAE4B;CAT5C;gCAhc+B,sBAAsB;wBAD9B,kBAAkB"}
+{"version":3,"file":"HeightMapShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/HeightMapShape3D.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IA4DI;;;;;;;;;;;OAWG;IACH,wCATW,MAAM,UACN,MAAM,UACN,MAAM,gBACN,OAAO,iBACP,MAAM,GAGJ,gBAAgB,CAqB5B;IA1FD;;;;;OAKG;IACH,sBAFU,OAAO,CAEkB;IAEnC;;;;;;;OAOG;IACH,eAFU,OAAO,CAEW;IAE5B;;;;;OAKG;IACH,SAFU,YAAY,IAAI,CAEX;IAEf;;;;;;;;;;;;;;;;OAgBG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;OAKG;IACH,eAA6B;IAG7B,6BAA2B;IAE3B,6BAA2B;IAC3B,6BAA2B;IAmC3B;;;;;;;;;OASG;IACH,sBA8CC;IAED;;;;;;OAMG;IACH,yBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,8BALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAelB;IAED,wCA6BC;IAED,oCA2BC;IAED;;;;;;;;OAQG;IACH,6CAmBC;IAED;;;;OAIG;IACH,4DA2BC;IAED;;;;;;;;;OASG;IACH,qGAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgEG;IACH,aAJW,YAAY,GAAC,MAAM,EAAE,cAEnB,OAAO,CA0NnB;IAED,kFAiBC;IA6CD;;;OAGG;IACH,cAHW,gBAAgB,GACd,OAAO,CAUnB;IAWL;;;;;;OAMG;IACH,6BAFU,OAAO,CAE4B;CAT5C;gCAluB+B,sBAAsB;wBAD9B,kBAAkB"}

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

@@ -2,12 +2,25 @@ import { hash_mix3 } from "../../../math/hash/hash_mix3.js";
 import { hash_mix2 } from "../../../math/hash/hash_mix2.js";
 import { assert } from "../../../assert.js";
 import { clamp } from "../../../math/clamp.js";
+import { clamp_index } from "../../../math/clamp_index.js";
 import { optional_equality } from "../../../model/object/optional_equality.js";
 import { optional_hash } from "../../../model/object/optional_hash.js";
+import { tri3_raycast } from "../triangle/tri3_raycast.js";
+import { v3_cross } from "../../vec3/v3_cross.js";
+import { v3_dot } from "../../vec3/v3_dot.js";
 import { v3_length } from "../../vec3/v3_length.js";
 import { Vector3 } from "../../Vector3.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 
+/**
+ * Below this, a ray's footprint-plane velocity component counts as zero in
+ * {@link HeightMapShape3D#raycast}'s slab clip — the reciprocal a smaller value
+ * would produce is not a usable slab distance. Matches the concave narrowphase's
+ * `refine_ray_concave`, so the two agree on rays that graze the footprint edge.
+ * @type {number}
+ */
+const RAY_SLAB_EPSILON = 1e-12;
+
 /**
  * Heightmap shape, intended primarily for terrain.
  *
@@ -182,14 +195,13 @@ export class HeightMapShape3D extends AbstractShape3D {
         u_y *= u_inv;
         u_z *= u_inv;
 
-        // v = u × n  (for n=+Y, u=+X this gives v=+Z, the intuitive choice)
-        const v_x = u_y * nz - u_z * ny;
-        const v_y = u_z * nx - u_x * nz;
-        const v_z = u_x * ny - u_y * nx;
-
         const b = this._basis;
+
         b[0] = u_x; b[1] = u_y; b[2] = u_z;
-        b[3] = v_x; b[4] = v_y; b[5] = v_z;
+
+        // v = u × n  (for n=+Y, u=+X this gives v=+Z, the intuitive choice)
+        v3_cross(b, 3, u_x, u_y, u_z, nx, ny, nz);
+
         b[6] = nx;  b[7] = ny;  b[8] = nz;
 
         this._basis_orientation_x = nx;
@@ -223,8 +235,8 @@ export class HeightMapShape3D extends AbstractShape3D {
         const b = this._basis;
 
         // project onto basis u and basis v
-        const u_coord = b[0] * px + b[1] * py + b[2] * pz;
-        const v_coord = b[3] * px + b[4] * py + b[5] * pz;
+        const u_coord = v3_dot(b[0], b[1], b[2], px, py, pz);
+        const v_coord = v3_dot(b[3], b[4], b[5], px, py, pz);
 
         const u01 = u_coord / this.size[0] + 0.5;
         const v01 = v_coord / this.size[2] + 0.5;
@@ -256,11 +268,10 @@ export class HeightMapShape3D extends AbstractShape3D {
 
             const uv_extent = Math.abs(cu) * half_u + Math.abs(cv) * half_v;
 
-            const h_lo = ch < 0 ? ch * sy : 0;
-            const h_hi = ch > 0 ? ch * sy : 0;
+            const h_extent = ch * sy;
 
-            result[k] = -uv_extent + h_lo;
-            result[k + 3] = uv_extent + h_hi;
+            result[k] = -uv_extent + Math.min(h_extent, 0);
+            result[k + 3] = uv_extent + Math.max(h_extent, 0);
         }
     }
 
@@ -274,9 +285,9 @@ export class HeightMapShape3D extends AbstractShape3D {
         const b = this._basis;
 
         // project into heightmap-local frame (u, v, h)
-        const u_coord = b[0] * px + b[1] * py + b[2] * pz;
-        const v_coord = b[3] * px + b[4] * py + b[5] * pz;
-        const h_coord = b[6] * px + b[7] * py + b[8] * pz;
+        const u_coord = v3_dot(b[0], b[1], b[2], px, py, pz);
+        const v_coord = v3_dot(b[3], b[4], b[5], px, py, pz);
+        const h_coord = v3_dot(b[6], b[7], b[8], px, py, pz);
 
         const half_u = this.size[0] * 0.5;
         const half_v = this.size[2] * 0.5;
@@ -311,9 +322,9 @@ export class HeightMapShape3D extends AbstractShape3D {
 
         const b = this._basis;
 
-        const u_coord = b[0] * px + b[1] * py + b[2] * pz;
-        const v_coord = b[3] * px + b[4] * py + b[5] * pz;
-        const h_coord = b[6] * px + b[7] * py + b[8] * pz;
+        const u_coord = v3_dot(b[0], b[1], b[2], px, py, pz);
+        const v_coord = v3_dot(b[3], b[4], b[5], px, py, pz);
+        const h_coord = v3_dot(b[6], b[7], b[8], px, py, pz);
 
         const u01 = u_coord / this.size[0] + 0.5;
         const v01 = v_coord / this.size[2] + 0.5;
@@ -337,8 +348,8 @@ export class HeightMapShape3D extends AbstractShape3D {
 
         const b = this._basis;
 
-        const u_coord = b[0] * rx + b[1] * ry + b[2] * rz;
-        const v_coord = b[3] * rx + b[4] * ry + b[5] * rz;
+        const u_coord = v3_dot(b[0], b[1], b[2], rx, ry, rz);
+        const v_coord = v3_dot(b[3], b[4], b[5], rx, ry, rz);
 
         const half_u = this.size[0] * 0.5;
         const half_v = this.size[2] * 0.5;
@@ -371,6 +382,289 @@ export class HeightMapShape3D extends AbstractShape3D {
         throw new Error("HeightMapShape3D.support: heightmaps are non-convex; the narrowphase must dispatch grid-traversal instead.");
     }
 
+    /**
+     * Nearest ray hit against the height-field SURFACE, in the shape's body-local
+     * frame. Writes `[px, py, pz, nx, ny, nz]` into `hit` and returns true; a miss
+     * returns false and leaves `hit` untouched.
+     *
+     * ## What is hit
+     *
+     * The surface, not the solid. The class models a closed volume (floor at h=0,
+     * height field above), but a ray meets only the height field — there is no
+     * floor quad and no side skirt, so a ray that passes under the terrain or
+     * enters through the footprint edge below the surface reports a miss. That is
+     * the same body {@link heightmap_enumerate_triangles} hands the contact
+     * narrowphase, and the same body the terrain renderer draws; a raycast that
+     * answered for the skirt would disagree with both. Mirrors
+     * {@link MeshShape3D#raycast}, which is likewise surface-only.
+     *
+     * Precisely the same triangles, too: the traversal reads its corner heights at
+     * the identical `i / seg_u` / `j / seg_v` UVs through the identical Catmull-Rom
+     * filter, and splits each sub-cell on the same lower-left diagonal
+     * (`(A,D,B)`, `(D,C,B)`), so a cast and a contact resolve against a surface
+     * that agrees bit for bit — {@link tessellation} included.
+     *
+     * NORMAL: the triangle's geometric normal, flipped to face the incoming ray
+     * (the shared {@link tri3_raycast} convention). A cast from below the terrain
+     * therefore reports a downward normal, not the surface's true upward one.
+     *
+     * A hit landing exactly ON a seam between facets gets the normal of one of the
+     * facets meeting there. INSIDE a sub-cell the two paths agree — they split on
+     * the same D–B diagonal and break the resulting tie in favour of the same
+     * facet — which matters because that diagonal runs through the sub-cell's
+     * centre, so a cast down the middle of a cell lands on it routinely rather
+     * than exceptionally.
+     *
+     * BETWEEN sub-cells they can differ, and which facet each names follows from
+     * traversal order: this walks the grid along the ray, the narrowphase
+     * enumerates it row-major, so on a grid line — and especially a grid corner,
+     * where four facets meet — the two can name different facets. The hit POINT
+     * still agrees; a faceted surface simply has no single normal at a seam.
+     * Measure-zero, and called out because it is the only place the two answers
+     * part company.
+     *
+     * `size.y` does NOT bound the query. Sampler values are not clamped to it (see
+     * the class docstring), so clipping the ray to the height range that
+     * {@link compute_bounding_box} reports could reject real surface standing above
+     * it; only the footprint is clipped against.
+     *
+     * ## Cost
+     *
+     * A 2-D DDA over the `(W−1)·N × (H−1)·N` sub-cell grid, two triangles per cell,
+     * stopping at the first cell that hits — cells are visited in increasing ray
+     * order and a sub-cell's triangles project exactly onto its own footprint
+     * rectangle, so nothing behind can be nearer. O(cells the ray crosses), not
+     * O(cells in the ray's bounding box): a long diagonal cast costs the grid's
+     * diagonal rather than its area.
+     *
+     * Four Catmull-Rom evaluations per cell, uncached — deliberately unlike
+     * {@link heightmap_enumerate_triangles}, whose corner-row cache exists because
+     * the contact narrowphase re-samples the same rect every substep. A ray walks
+     * a diagonal, visits each cell once, and stops early; there is nothing to
+     * amortise against.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray body-local ray (unit direction; `ray[6]` = tMax)
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit, ray) {
+        const sampler = this.sampler;
+
+        if (sampler === null) {
+            return false;
+        }
+
+        const size_x = this.size[0];
+        const size_z = this.size[2];
+
+        if (size_x <= 0 || size_z <= 0) {
+            return false;
+        }
+
+        // The collision grid heightmap_enumerate_triangles builds. A sampler too
+        // thin to hold one cell on an axis (width or height < 2), or tessellation
+        // 0, collapses it — no triangles exist, so nothing can be hit.
+        const seg_u = (sampler.width - 1) * this.tessellation;
+        const seg_v = (sampler.height - 1) * this.tessellation;
+
+        if (seg_u < 1 || seg_v < 1) {
+            return false;
+        }
+
+        this._ensure_basis();
+
+        const b = this._basis;
+
+        const o_x = ray[0], o_y = ray[1], o_z = ray[2];
+        const d_x = ray[3], d_y = ray[4], d_z = ray[5];
+
+        // Body → heightmap-local footprint coordinates. The basis is orthonormal,
+        // so the direction stays unit and `t` is the same distance in both frames;
+        // the height component is never needed, the triangles carry it.
+        const o_u = v3_dot(b[0], b[1], b[2], o_x, o_y, o_z);
+        const o_v = v3_dot(b[3], b[4], b[5], o_x, o_y, o_z);
+        const d_u = v3_dot(b[0], b[1], b[2], d_x, d_y, d_z);
+        const d_v = v3_dot(b[3], b[4], b[5], d_x, d_y, d_z);
+
+        const half_u = size_x * 0.5;
+        const half_v = size_z * 0.5;
+
+        const t_max = ray[6];
+
+        // ── Clip to the footprint slabs → the segment the DDA walks ──────────
+        let t_enter = 0;
+        let t_exit = t_max;
+
+        if (d_u > RAY_SLAB_EPSILON || d_u < -RAY_SLAB_EPSILON) {
+            const inv = 1 / d_u;
+            const t0 = (-half_u - o_u) * inv;
+            const t1 = (half_u - o_u) * inv;
+
+            t_enter = Math.max(t_enter, Math.min(t0, t1));
+            t_exit = Math.min(t_exit, Math.max(t0, t1));
+        } else if (o_u < -half_u || o_u > half_u) {
+            return false;
+        }
+
+        if (d_v > RAY_SLAB_EPSILON || d_v < -RAY_SLAB_EPSILON) {
+            const inv = 1 / d_v;
+            const t0 = (-half_v - o_v) * inv;
+            const t1 = (half_v - o_v) * inv;
+
+            t_enter = Math.max(t_enter, Math.min(t0, t1));
+            t_exit = Math.min(t_exit, Math.max(t0, t1));
+        } else if (o_v < -half_v || o_v > half_v) {
+            return false;
+        }
+
+        if (t_exit < t_enter) {
+            return false;
+        }
+
+        // ── Amanatides–Woo setup on the sub-cell grid ────────────────────────
+        //
+        // Grid coordinates run [0, seg_u] × [0, seg_v] across the footprint. A
+        // ray with no footprint-plane velocity (cast straight down the
+        // orientation axis) keeps both rates at 0, both t_next at Infinity, and
+        // the loop tests its single cell and stops.
+        const per_cell_u = seg_u / size_x;
+        const per_cell_v = seg_v / size_z;
+
+        const rate_u = d_u * per_cell_u;
+        const rate_v = d_v * per_cell_v;
+
+        const g_u = (o_u + d_u * t_enter + half_u) * per_cell_u;
+        const g_v = (o_v + d_v * t_enter + half_v) * per_cell_v;
+
+        // Clamped to the grid because the slab clip lands the entry point ON the
+        // boundary, where rounding can put it a ULP outside.
+        let i = clamp_index(Math.floor(g_u), seg_u);
+        let j = clamp_index(Math.floor(g_v), seg_v);
+
+        // `t_next` is the distance at which the ray leaves the starting cell
+        // through that axis' far grid line, `t_delta` the distance a whole cell
+        // costs thereafter. A zero rate leaves both at Infinity: that axis is
+        // never the one the walk steps along.
+        let step_i = 0, t_delta_u = Infinity, t_next_u = Infinity;
+        if (rate_u !== 0) {
+            // the grid line the starting cell is left through: its far side
+            // in the direction of travel
+            const exit_line = rate_u > 0 ? i + 1 : i;
+
+            step_i = rate_u > 0 ? 1 : -1;
+            t_delta_u = Math.abs(1 / rate_u);
+            t_next_u = t_enter + (exit_line - g_u) / rate_u;
+        }
+
+        let step_j = 0, t_delta_v = Infinity, t_next_v = Infinity;
+        if (rate_v !== 0) {
+            const exit_line = rate_v > 0 ? j + 1 : j;
+
+            step_j = rate_v > 0 ? 1 : -1;
+            t_delta_v = Math.abs(1 / rate_v);
+            t_next_v = t_enter + (exit_line - g_v) / rate_v;
+        }
+
+        const inv_seg_u = 1 / seg_u;
+        const inv_seg_v = 1 / seg_v;
+
+        const ux = b[0], uy = b[1], uz = b[2];
+        const vx = b[3], vy = b[4], vz = b[5];
+        const nx = b[6], ny = b[7], nz = b[8];
+
+        // Every iteration but the last ends by crossing one grid line, and a
+        // straight line crosses fewer than seg_u + seg_v of them (a corner costs
+        // two iterations to move diagonally — one per axis — but no extra lines).
+        // The walk normally ends on t_exit; this is the bound that holds when a
+        // near-denormal rate makes t_exit unreachable.
+        const max_steps = seg_u + seg_v + 2;
+
+        for (let step = 0; step < max_steps; step++) {
+            // ── The sub-cell's two triangles, built exactly as the enumerator
+            //    builds them: corners (A,B,C,D) = (i,j), (i+1,j), (i+1,j+1),
+            //    (i,j+1), split (A,D,B) and (D,C,B).
+            const u01_lo = i * inv_seg_u;
+            const u01_hi = (i + 1) * inv_seg_u;
+            const v01_lo = j * inv_seg_v;
+            const v01_hi = (j + 1) * inv_seg_v;
+
+            const u_lo = -half_u + size_x * u01_lo;
+            const u_hi = -half_u + size_x * u01_hi;
+            const v_lo = -half_v + size_z * v01_lo;
+            const v_hi = -half_v + size_z * v01_hi;
+
+            const hA = sampler.sampleChannelCatmullRomUV(u01_lo, v01_lo, 0);
+            const hB = sampler.sampleChannelCatmullRomUV(u01_hi, v01_lo, 0);
+            const hC = sampler.sampleChannelCatmullRomUV(u01_hi, v01_hi, 0);
+            const hD = sampler.sampleChannelCatmullRomUV(u01_lo, v01_hi, 0);
+
+            const Ax = ux * u_lo + vx * v_lo + nx * hA;
+            const Ay = uy * u_lo + vy * v_lo + ny * hA;
+            const Az = uz * u_lo + vz * v_lo + nz * hA;
+
+            const Bx = ux * u_hi + vx * v_lo + nx * hB;
+            const By = uy * u_hi + vy * v_lo + ny * hB;
+            const Bz = uz * u_hi + vz * v_lo + nz * hB;
+
+            const Cx = ux * u_hi + vx * v_hi + nx * hC;
+            const Cy = uy * u_hi + vy * v_hi + ny * hC;
+            const Cz = uz * u_hi + vz * v_hi + nz * hC;
+
+            const Dx = ux * u_lo + vx * v_hi + nx * hD;
+            const Dy = uy * u_lo + vy * v_hi + ny * hD;
+            const Dz = uz * u_lo + vz * v_hi + nz * hD;
+
+            // Tested in reverse enumeration order, and that is what decides the
+            // tie. The two facets share the D–B diagonal — which runs through the
+            // sub-cell's centre, so a ray landing on it is the ordinary case, not a
+            // corner one — and a ray that lands on it hits both at one distance.
+            // `refine_ray_concave` enumerates (A,D,B) first and lets a later
+            // triangle win only by a strictly smaller distance, so the facet it
+            // names is (A,D,B). tri3_raycast admits `t <= tMax` and writes hit[3..5]
+            // only on a hit, so testing (D,C,B) first and handing (A,D,B) its
+            // distance as the budget lets the equal hit overwrite the normal — and
+            // the two paths name the same facet.
+            const t_dcb = tri3_raycast(
+                hit, 3, o_x, o_y, o_z, d_x, d_y, d_z, t_max,
+                Dx, Dy, Dz, Cx, Cy, Cz, Bx, By, Bz
+            );
+
+            const t_adb = tri3_raycast(
+                hit, 3, o_x, o_y, o_z, d_x, d_y, d_z, Math.min(t_dcb, t_max),
+                Ax, Ay, Az, Dx, Dy, Dz, Bx, By, Bz
+            );
+
+            const best = Math.min(t_adb, t_dcb);
+
+            if (best !== Infinity) {
+                hit[0] = o_x + d_x * best;
+                hit[1] = o_y + d_y * best;
+                hit[2] = o_z + d_z * best;
+
+                return true;
+            }
+
+            // ── Advance to the next cell along the ray ───────────────────────
+            if (t_next_u < t_next_v) {
+                if (t_next_u > t_exit) break;
+                i += step_i;
+                if (i < 0 || i >= seg_u) break;
+                t_next_u += t_delta_u;
+            } else if (t_next_v !== Infinity) {
+                if (t_next_v > t_exit) break;
+                j += step_j;
+                if (j < 0 || j >= seg_v) break;
+                t_next_v += t_delta_v;
+            } else {
+                // Both rates are zero: the ray runs along the orientation axis and
+                // never leaves the cell it started in.
+                break;
+            }
+        }
+
+        return false;
+    }
+
     sample_random_point_in_volume(result, result_offset, random) {
         const u01 = random();
         const v01 = random();

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

@@ -1 +1 @@
-{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CAClB;IAEb,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IAEP;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAe1D;IAED;;;;;;;;;;;;;;;OAeG;IACH,wBATW,eAAe,MACf,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAMhB;IAyED,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;IAGL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;gCAtN+B,sBAAsB"}
+{"version":3,"file":"PosedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PosedShape3D.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI,mCAAmC;IACnC,OADW,eAAe,GAAC,IAAI,CAClB;IAEb,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IACP,WAAO;IAEP;;;;;;;OAOG;IACH,aAJW,eAAe,YACf,UAAQ;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,YACpC,aAAW;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC,QAe1D;IAED;;;;;;;;;;;;;;;OAeG;IACH,wBATW,eAAe,MACf,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAMhB;IA+HD,wCASC;IA4BD;;;;;;;OAOG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,MAAM,CAKlB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,GAChC,OAAO,CAKnB;IAGL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;;CAPpC;gCA5Q+B,sBAAsB"}

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

@@ -1,5 +1,8 @@
 import { assert } from "../../../assert.js";
+import { v3_quaternion_apply } from "../../vec3/v3_quaternion_apply.js";
+import { v3_quaternion_apply_inverse } from "../../vec3/v3_quaternion_apply_inverse.js";
 import { aabb3_transform_oriented } from "../aabb/aabb3_transform_oriented.js";
+import { Ray3 } from "../ray/Ray3.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 
 const scratch_local = new Float64Array(3);
@@ -154,6 +157,60 @@ export class PosedShape3D extends AbstractShape3D {
         result[result_offset + 2] = tsz * qw - tsw * qz - tsx * qy + tsy * qx + this.pz;
     }
 
+    /**
+     * Ray ↔ posed shape, with the ray given in the WRAPPER's frame. The inverse pose carries it into
+     * the subject's frame (translate by −position, rotate by the conjugate quaternion), the subject
+     * answers there, and the answer is rotated back — the point re-translated, the normal not.
+     *
+     * A rigid pose is an isometry, so the crossing changes nothing about the ray's parametrisation:
+     * the rotated direction is still unit, `tMax` goes through untouched, and the distance the subject
+     * measures IS the distance here. The normal's ORIENTATION survives for the same reason — a rotation
+     * preserves the angle between normal and direction, so a subject that turned its normal to meet the
+     * ray has turned this one to meet it too, and there is nothing to re-check.
+     *
+     * `hit` is handed straight to the subject rather than buffered and copied back: on a hit its
+     * contents are mapped in place, and on a miss the subject leaves it untouched — which is the
+     * convention this class owes its own caller, so it is passed on intact.
+     *
+     * The physics ray query does not come through here; it uses `refine_ray_posed`, which performs the
+     * same mapping on loose scalars. That path reports a distance rather than a point, so it never
+     * rotates anything but the normal.
+     *
+     * @param {Float32Array|number[]} hit out: [px, py, pz, nx, ny, nz]
+     * @param {Ray3} ray wrapper-frame ray (origin in [0..2], unit direction in [3..5], tMax in [6])
+     * @returns {boolean} whether anything was hit
+     */
+    raycast(hit, ray) {
+        const shape = this.shape;
+
+        if (shape === null) {
+            return false;
+        }
+
+        const qx = this.qx, qy = this.qy, qz = this.qz, qw = this.qw;
+
+        // Allocated per call rather than kept as a module scratch: a posed shape may wrap another
+        // wrapper, and every level of that recursion needs its own sub-ray alive across the call below.
+        const local_ray = new Ray3();
+
+        v3_quaternion_apply_inverse(local_ray, 0, ray[0] - this.px, ray[1] - this.py, ray[2] - this.pz, qx, qy, qz, qw);
+        v3_quaternion_apply_inverse(local_ray, 3, ray[3], ray[4], ray[5], qx, qy, qz, qw);
+        local_ray[6] = ray[6];
+
+        if (!shape.raycast(hit, local_ray)) {
+            return false;
+        }
+
+        v3_quaternion_apply(hit, 0, hit[0], hit[1], hit[2], qx, qy, qz, qw);
+        v3_quaternion_apply(hit, 3, hit[3], hit[4], hit[5], qx, qy, qz, qw);
+
+        hit[0] += this.px;
+        hit[1] += this.py;
+        hit[2] += this.pz;
+
+        return true;
+    }
+
     compute_bounding_box(result) {
         this.shape.compute_bounding_box(scratch_local_aabb);
         aabb3_transform_oriented(

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

@@ -1 +1 @@
-{"version":3,"file":"TransformedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/TransformedShape3D.js"],"names":[],"mappings":"AAwBA;IAwCI;;;;;OAKG;IACH,wBAHW,eAAe,MADf,MAAM,EAAE,GAAC,YAAY,OAAK,GAExB,kBAAkB,CAS9B;IAED;;;;;OAKG;IACH,uCAJW,eAAe,eACf,MAAM,EAAE,SACR,MAAM,EAAE,sBAiBlB;IAED;;;;OAIG;IACH,iCAHW,eAAe,eACf,MAAM,EAAE,sBAIlB;IAED;;;;;OAKG;IACH,2BAHW,eAAe,SACf,MAAM,EAAE,GAAC,YAAY,OAAK,GAFxB,kBAAkB,CAM9B;IA9FD;;;;OAIG;IACH,iBAAgC;IAEhC;;;;OAIG;IACH,yBAAwC;IAExC;;;;OAIG;IACH,kBAAiB;IAEjB;;;OAGG;IACH,+BAEC;IAqED;;;OAGG;IACH,0CAIC;IAED,yCAEC;IAED;;;;;;;OAOG;IACH,6BAEC;IAUD,wCAKC;IAED,mEAyDC;IAED,6CAEC;IAED,oCAKC;IAED,kFAIC;IAED,qGAwCC;IAED;;;;OAIG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAOnB;IAQL;;;;;OAKG;IACH,+BAFU,OAAO,CAEgC;CARhD;gCA9R+B,sBAAsB"}
+{"version":3,"file":"TransformedShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/TransformedShape3D.js"],"names":[],"mappings":"AAyBA;IAwCI;;;;;OAKG;IACH,wBAHW,eAAe,MADf,MAAM,EAAE,GAAC,YAAY,OAAK,GAExB,kBAAkB,CAS9B;IAED;;;;;OAKG;IACH,uCAJW,eAAe,eACf,MAAM,EAAE,SACR,MAAM,EAAE,sBAiBlB;IAED;;;;OAIG;IACH,iCAHW,eAAe,eACf,MAAM,EAAE,sBAIlB;IAED;;;;;OAKG;IACH,2BAHW,eAAe,SACf,MAAM,EAAE,GAAC,YAAY,OAAK,GAFxB,kBAAkB,CAM9B;IA9FD;;;;OAIG;IACH,iBAAgC;IAEhC;;;;OAIG;IACH,yBAAwC;IAExC;;;;OAIG;IACH,kBAAiB;IAEjB;;;OAGG;IACH,+BAEC;IAqED;;;OAGG;IACH,0CAIC;IAED,yCAEC;IAED;;;;;;;OAOG;IACH,6BAEC;IAUD,wCAKC;IAED,mEAyDC;IAED,6CAEC;IAED,oCAKC;IAED,kFAIC;IAED,qGAwCC;IAuGD;;;;OAIG;IACH,cAHW,kBAAkB,GAChB,OAAO,CAOnB;IAQL;;;;;OAKG;IACH,+BAFU,OAAO,CAEgC;CARhD;gCAnY+B,sBAAsB"}