leaflet-city-mapper 0.0.9 → 0.1.1

package/src/collision/collider.js

@@ -1,39 +1,45 @@
 import { colliders } from '../weakmaps/colliders.js';
+import { advanceFeature } from './advanceFeature.js';
+import { cachedCollider } from './cachedCollider.js';
+import { flipsNormal } from './flipsNormal.js';
 import { indexTriangle } from './indexTriangle.js';
 import { readTriangle } from './readTriangle.js';
+import { transformVertices } from './transformVertices.js';
 import { vertexCount } from './vertexCount.js';
 
-
+/**
+ * Cache world-space collision triangles and their grid cells, rebuilding when geometry or rotation/scale changes.
+ *
+ * @param {Object} mesh Mesh containing geometry and a world matrix.
+ *
+ * @returns {Object} Cached triangle, normal, feature and grid data.
+ */
 export function collider(mesh) {
-  let c = colliders.get(mesh.geometry);
-  if (c) return c;
-  const m = mesh.worldMatrix, { position, index, normal, uv, instanceOffset } = mesh.geometry.attributes;
+  const m = mesh.worldMatrix;
+  const cached = cachedCollider(mesh);
+  if (cached) return cached;
+  const { position, index, normal, uv, instanceOffset } = mesh.geometry.attributes;
 
   const vertices = vertexCount(position, index);
   const count = vertices * (instanceOffset?.count ?? 1);
   const tri = /* alloc */ [];
   const nrm = /* alloc */ [];
+  const features = /* alloc */ [];
   const cells = /* alloc */ new Map();
   const a = /* alloc */ [0, 0, 0], b = /* alloc */ [0, 0, 0], d = /* alloc */ [0, 0, 0];
   const v = /* alloc */ [];
 
-  let i, first, j, ex, ey, ez, fx, fy, fz, nx, nz, ny, length, h, t, maxX = -Infinity;
+  const ranges = mesh.extras?.featureFaces;
+  let i, first, j, ex, ey, ez, fx, fy, fz, nx, nz, ny, length, h, t, feature = 0, maxX = -Infinity;
   for (i = 0; i < count; i += 3) {
+    feature = advanceFeature(ranges, feature, i / 3);
     first = index ? index.data[i % vertices] : i % vertices;
     // Streetlight halos (uv.x <= 2, see scene/picking.js) are light, not matter.
     if (mesh.program.nightLight && uv && uv.data[first * 2] <= 2) {
       continue;
     }
     readTriangle(mesh, i, a, b, d);
-    v[0] = m[0] * a[0] + m[4] * a[1] + m[8] * a[2] + m[12];
-    v[1] = m[1] * a[0] + m[5] * a[1] + m[9] * a[2] + m[13];
-    v[2] = m[2] * a[0] + m[6] * a[1] + m[10] * a[2] + m[14];
-    v[3] = m[0] * b[0] + m[4] * b[1] + m[8] * b[2] + m[12];
-    v[4] = m[1] * b[0] + m[5] * b[1] + m[9] * b[2] + m[13];
-    v[5] = m[2] * b[0] + m[6] * b[1] + m[10] * b[2] + m[14];
-    v[6] = m[0] * d[0] + m[4] * d[1] + m[8] * d[2] + m[12];
-    v[7] = m[1] * d[0] + m[5] * d[1] + m[9] * d[2] + m[13];
-    v[8] = m[2] * d[0] + m[6] * d[1] + m[10] * d[2] + m[14];
+    transformVertices(v, a, b, d, m);
     ex = v[3] - v[0], ey = v[4] - v[1], ez = v[5] - v[2], fx = v[6] - v[0], fy = v[7] - v[1], fz = v[8] - v[2];
 
     nx = ey * fz - ez * fy, nz = ex * fy - ey * fx;
@@ -47,8 +53,7 @@ export function collider(mesh) {
     if (normal) {
       // The stored normal tells the outside, whatever the winding.
       j = first * 3;
-      if ((m[0] * normal.data[j] + m[4] * normal.data[j + 1] + m[8] * normal.data[j + 2]) * nx +
-        (m[2] * normal.data[j] + m[6] * normal.data[j + 1] + m[10] * normal.data[j + 2]) * nz < 0) { nx = -nx; nz = -nz; }
+      if (flipsNormal(m, normal.data, j, nx, nz)) { nx = -nx; nz = -nz; }
     }
 
     h = Math.hypot(nx, nz), t = nrm.length / 2;
@@ -56,16 +61,21 @@ export function collider(mesh) {
     tri.push(...v);
     maxX = Math.max(maxX, v[0], v[3], v[6]);
     nrm.push(nx / h, nz / h);
+    features.push(ranges ? feature : instanceOffset ? Math.floor(i / vertices) : 0);
 
     indexTriangle(cells, v, t);
   }
-  c = /* alloc */ {
+  const c = /* alloc */ {
     tri: Float32Array.from(tri),
     nrm: Float32Array.from(nrm),
+    features: Uint32Array.from(features),
+    ranges,
     cells,
     maxX,
+    geometry: mesh.geometry,
+    matrix: Array.from(m),
     origin: /* alloc */ [m[12], m[13], m[14]]
   };
-  colliders.set(mesh.geometry, c);
+  colliders.set(mesh, c);
   return c;
 }

package/src/collision/countCrossings.js

@@ -1,15 +1,35 @@
-export function countCrossings(hits) {
-  let ix, j, distance;
-  for (ix = 1; ix < hits.length; ix++) {
-    distance = hits[ix];
-    j = ix - 1;
-    while (j >= 0 && hits[j] > distance) hits[j + 1] = hits[j--];
-    hits[j + 1] = distance;
-  }
-  let crossings = 0, previous = -Infinity;
-  for (distance of hits) {
-    if (distance - previous > 1e-4) crossings++;
-    previous = distance;
-  }
-  return crossings;
-}
+import { enclosesOrigin } from './enclosesOrigin.js';
+import { sortCrossings } from './sortCrossings.js';
+
+/**
+ * Count features enclosing the ray origin, deduplicating crossings separately for each feature and footprint.
+ *
+ * @param {number[]} hits Feature keys and crossing distances; sorted in place.
+ * @param {Object[]|undefined} ranges Feature metadata, including polygon flags.
+ *
+ * @returns {number} Number of features classified as enclosing the origin.
+ */
+export function countCrossings(hits, ranges) {
+  // Shared walls must be deduplicated within each feature, not across neighboring features.
+  sortCrossings(hits);
+  let crossings = 0, enclosed = 0, previous = -Infinity, previousKey = -1, previousFeature = -1, height = 0, footprint = 0;
+  let ix, key, feature, distance;
+  for (ix = 0; ix <= hits.length; ix += 2) {
+    key = ix < hits.length ? hits[ix] : -1;
+    feature = Math.floor(key / 2);
+    if (key !== previousKey && previousKey >= 0) {
+      if (previousKey % 2) footprint = crossings % 2;
+      else height = crossings % 2;
+    }
+    if (key !== previousKey && previousKey >= 0 && feature !== previousFeature) {
+      enclosed += Number(enclosesOrigin(height, footprint, ranges, previousFeature));
+      height = 0, footprint = 0;
+    }
+    if (key !== previousKey) crossings = 0, previous = -Infinity, previousKey = key, previousFeature = feature;
+    if (ix === hits.length) break;
+    distance = hits[ix + 1];
+    if (distance - previous > (key % 2 ? 1e-3 : 1e-4)) crossings++;
+    previous = distance;
+  }
+  return enclosed;
+}

package/src/collision/enclosesOrigin.js

@@ -0,0 +1,13 @@
+/**
+ * Whether a feature's accumulated crossing parities enclose the ray origin.
+ *
+ * @param {number} height Height-wall crossing parity.
+ * @param {number} footprint Footprint crossing parity.
+ * @param {Object[]|undefined} ranges Feature metadata, including polygon flags.
+ * @param {number} feature Feature index.
+ *
+ * @returns {boolean} True when the feature encloses the origin.
+ */
+export function enclosesOrigin(height, footprint, ranges, feature) {
+  return Boolean(height && (!ranges?.[feature]?.polygon || footprint));
+}

package/src/collision/flipsNormal.js

@@ -0,0 +1,15 @@
+/**
+ * Whether the stored vertex normal points opposite to a triangle's winding normal after transformation.
+ *
+ * @param {ArrayLike<number>} m Column-major world matrix.
+ * @param {ArrayLike<number>} data Packed vertex normals.
+ * @param {number} j Offset of the first vertex normal.
+ * @param {number} nx Winding normal x.
+ * @param {number} nz Winding normal z.
+ *
+ * @returns {boolean} True when the winding normal must be flipped.
+ */
+export function flipsNormal(m, data, j, nx, nz) {
+  return (m[0] * data[j] + m[4] * data[j + 1] + m[8] * data[j + 2]) * nx +
+    (m[2] * data[j] + m[6] * data[j + 1] + m[10] * data[j + 2]) * nz < 0;
+}

package/src/collision/hiddenLightHit.js

@@ -1,8 +1,19 @@
-export function hiddenLightHit(mesh, i, u, v, night) {
-  if (!mesh.program.nightLight) return false;
-  const { index, uv: { data: uv } } = mesh.geometry.attributes;
-  const idA = index ? index.data[i] : i, idB = index ? index.data[i + 1] : i + 1, idC = index ? index.data[i + 2] : i + 2;
-  const x = uv[idA * 2] * (1 - u - v) + uv[idB * 2] * u + uv[idC * 2] * v;
-  const y = uv[idA * 2 + 1] * (1 - u - v) + uv[idB * 2 + 1] * u + uv[idC * 2 + 1] * v;
-  return x <= 2 && (!night || x * x + y * y > 0.9);
-}
+/**
+ * Reject picks on light halos that are invisible in the current day/night state.
+ *
+ * @param {Object} mesh Picked mesh.
+ * @param {number} i Triangle's first vertex or index offset.
+ * @param {number} u First barycentric coordinate.
+ * @param {number} v Second barycentric coordinate.
+ * @param {number} night Current night-light intensity.
+ *
+ * @returns {boolean} Whether the hit belongs to an invisible halo.
+ */
+export function hiddenLightHit(mesh, i, u, v, night) {
+  if (!mesh.program.nightLight) return false;
+  const { index, uv: { data: uv } } = mesh.geometry.attributes;
+  const idA = index ? index.data[i] : i, idB = index ? index.data[i + 1] : i + 1, idC = index ? index.data[i + 2] : i + 2;
+  const x = uv[idA * 2] * (1 - u - v) + uv[idB * 2] * u + uv[idC * 2] * v;
+  const y = uv[idA * 2 + 1] * (1 - u - v) + uv[idB * 2 + 1] * u + uv[idC * 2 + 1] * v;
+  return x <= 2 && (!night || x * x + y * y > 0.9);
+}

package/src/collision/horizontalRay.js

@@ -1,4 +1,16 @@
-// Möller-Trumbore for the horizontal ray (ox, oy, oz) + d·(dx, 0, dz) against triangle t; returns d or -1.
+/**
+ * Möller-Trumbore for the horizontal ray (ox, oy, oz) + d·(dx, 0, dz) against triangle t; returns d or -1.
+ *
+ * @param {Float32Array|number[]} v Packed triangle coordinates.
+ * @param {number} t Triangle index.
+ * @param {number} ox Ray origin x.
+ * @param {number} oy Ray origin y.
+ * @param {number} oz Ray origin z.
+ * @param {number} dx Ray direction x.
+ * @param {number} dz Ray direction z.
+ *
+ * @returns {number} Signed ray distance, or -1 when the triangle is missed.
+ */
 export function horizontalRay(v, t, ox, oy, oz, dx, dz) {
   const i = t * 9, ex = v[i + 3] - v[i], ey = v[i + 4] - v[i + 1], ez = v[i + 5] - v[i + 2];
   const fx = v[i + 6] - v[i], fy = v[i + 7] - v[i + 1], fz = v[i + 8] - v[i + 2];

package/src/collision/indexTriangle.js

@@ -1,11 +1,18 @@
-import { CELL } from '../globals/CELL.js';
-
-export function indexTriangle(cells, v, t) {
-  let ix, iz, key;
-  for (ix = Math.floor(Math.min(v[0], v[3], v[6]) / CELL); ix <= Math.floor(Math.max(v[0], v[3], v[6]) / CELL); ix++)
-    for (iz = Math.floor(Math.min(v[2], v[5], v[8]) / CELL); iz <= Math.floor(Math.max(v[2], v[5], v[8]) / CELL); iz++) {
-      key = ix + ',' + iz;
-      if (!cells.has(key)) cells.set(key, /* alloc */ []);
-      cells.get(key).push(t);
-    }
-}
+import { CELL } from '../globals/CELL.js';
+
+/**
+ * Add a triangle index to every X/Z grid cell touched by its projected bounding box.
+ *
+ * @param {Map<string, number[]>} cells Spatial grid receiving triangle indices.
+ * @param {number[]} v Packed triangle coordinates.
+ * @param {number} t Triangle index.
+ */
+export function indexTriangle(cells, v, t) {
+  let ix, iz, key;
+  for (ix = Math.floor(Math.min(v[0], v[3], v[6]) / CELL); ix <= Math.floor(Math.max(v[0], v[3], v[6]) / CELL); ix++)
+    for (iz = Math.floor(Math.min(v[2], v[5], v[8]) / CELL); iz <= Math.floor(Math.max(v[2], v[5], v[8]) / CELL); iz++) {
+      key = ix + ',' + iz;
+      if (!cells.has(key)) cells.set(key, /* alloc */ []);
+      cells.get(key).push(t);
+    }
+}

package/src/collision/insideMesh.js

@@ -1,33 +1,47 @@
-import { CELL } from '../globals/CELL.js';
-
-import { collider } from './collider.js';
-import { computeBounds } from '../geometry/computeBounds.js';
-import { collectIntersections } from './collectIntersections.js';
-import { countCrossings } from './countCrossings.js';
-
-export function insideMesh(mesh, x, y, z, seen, intersections) {
-  const geometry = mesh.geometry;
-  if (!mesh.visible || !geometry?.attributes?.position?.data || mesh.program?.depthTest === false) return false;
-  if (!geometry.bounds) computeBounds(geometry);
-  const bounds = geometry.bounds;
-  const world = mesh.worldMatrix;
-  const center = bounds.center;
-  const cx = world[0] * center[0] + world[4] * center[1] + world[8] * center[2] + world[12];
-  const cy = world[1] * center[0] + world[5] * center[1] + world[9] * center[2] + world[13];
-  const cz = world[2] * center[0] + world[6] * center[1] + world[10] * center[2] + world[14];
-  const radius = bounds.radius * Math.max(
-    Math.hypot(world[0], world[1], world[2]),
-    Math.hypot(world[4], world[5], world[6]),
-    Math.hypot(world[8], world[9], world[10])
-  );
-  if (Math.hypot(cx - x, cy - y, cz - z) > radius) return false;
-  const shape = collider(mesh);
-  const end = Math.floor(shape.maxX / CELL);
-  if (x >= shape.maxX) return false;
-  const iz = Math.floor(z / CELL);
-  const hits = intersections;
-  hits.length = 0;
-  seen.clear();
-  collectIntersections(shape, x, y, z, seen, hits, end, iz);
-  return countCrossings(hits) % 2 === 1;
-}
+import { CELL } from '../globals/CELL.js';
+import { collider } from './collider.js';
+import { computeBounds } from '../geometry/computeBounds.js';
+import { collectIntersections } from './collectIntersections.js';
+import { countCrossings } from './countCrossings.js';
+
+/**
+ * Test a world-space point against visible mesh features, reusing the supplied intersection scratch buffers.
+ *
+ * @param {Object} mesh Mesh to test.
+ * @param {number} x World-space x coordinate.
+ * @param {number} y World-space y coordinate.
+ * @param {number} z World-space z coordinate.
+ * @param {Set<number>} seen Reusable set of visited triangle indices.
+ * @param {number[]} intersections Reusable array of crossing data.
+ *
+ * @returns {boolean} Whether a feature encloses the point.
+ */
+export function insideMesh(mesh, x, y, z, seen, intersections) {
+  const geometry = mesh.geometry;
+  if (!mesh.visible || !geometry?.attributes?.position?.data || mesh.program?.depthTest === false) return false;
+  if (!geometry.bounds) computeBounds(geometry);
+  const bounds = geometry.bounds;
+  const world = mesh.worldMatrix;
+  const center = bounds.center;
+  const cx = world[0] * center[0] + world[4] * center[1] + world[8] * center[2] + world[12];
+  const cy = world[1] * center[0] + world[5] * center[1] + world[9] * center[2] + world[13];
+  const cz = world[2] * center[0] + world[6] * center[1] + world[10] * center[2] + world[14];
+  const radius = bounds.radius * Math.max(
+    Math.hypot(world[0], world[1], world[2]),
+    Math.hypot(world[4], world[5], world[6]),
+    Math.hypot(world[8], world[9], world[10])
+  );
+  if (Math.hypot(cx - x, cy - y, cz - z) > radius) return false;
+  const shape = collider(mesh);
+  x += shape.origin[0] - world[12];
+  y += shape.origin[1] - world[13];
+  z += shape.origin[2] - world[14];
+  const end = Math.floor(shape.maxX / CELL);
+  if (x >= shape.maxX) return false;
+  const iz = Math.floor(z / CELL);
+  const hits = intersections;
+  hits.length = 0;
+  seen.clear();
+  collectIntersections(shape, x, y, z, seen, hits, end, iz);
+  return countCrossings(hits, shape.ranges) > 0;
+}

package/src/collision/insideWalker.js

@@ -1,46 +1,52 @@
-import { kindByLayer } from '../weakmaps/kindByLayer.js';
-import { layersByLayer } from '../weakmaps/layersByLayer.js';
-import { rootByLayer } from '../weakmaps/rootByLayer.js';
-import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
-import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
-import { updateWorldMatrix } from '../transforms/updateWorldMatrix.js';
-import { insideMesh } from './insideMesh.js';
-import { trafficCollision } from './trafficCollision.js';
-import { local } from '../projections/walkerLocalPosition.js';
-
-export function insideWalker(context) {
-  const { layer, local: localBuffer, hitData } = context;
-  const shared = sharedByLayer.get(layer);
-  if (!shared || !layersByLayer.get(shared)) return false;
-  updateWorldMatrix(sceneByLayer.get(layer));
-  const root = rootByLayer.get(layer);
-  const feet = local.call(context, localBuffer);
-  const x = root.position[0] + feet[0] * root.scale[0];
-  const y = root.position[1] + feet[1] * root.scale[1];
-  const z = root.position[2] + feet[2] * root.scale[2];
-  const layers = layersByLayer.get(shared);
-  let other, node, child, nodes;
-  for (other of layers) {
-    if (other === layer || kindByLayer.get(other) === 'terrain') continue;
-    if (kindByLayer.get(other) === 'traffic') {
-      hitData.best = 0;
-      hitData.found = false;
-      if (trafficCollision(other, x, y, z, 0, 0, 0, hitData)) return true;
-      continue;
-    }
-    nodes = hitData.nodes;
-    nodes.length = 0;
-    if (rootByLayer.get(other)) nodes.push(rootByLayer.get(other));
-    while (nodes.length) {
-      node = nodes.pop();
-      if (!node.visible) continue;
-      if (node.geometry && (
-        insideMesh(node, x, y + 0.45 * root.scale[1], z, hitData.seen, hitData.intersections) ||
-        insideMesh(node, x, y + 1.35 * root.scale[1], z, hitData.seen, hitData.intersections)
-      )) return true;
-      for (child of node.children) nodes.push(child);
-    }
-  }
-  return false;
-}
+import { kindByLayer } from '../weakmaps/kindByLayer.js';
+import { layersByLayer } from '../weakmaps/layersByLayer.js';
+import { rootByLayer } from '../weakmaps/rootByLayer.js';
+import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
+import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
+import { updateWorldMatrix } from '../transforms/updateWorldMatrix.js';
+import { insideMesh } from './insideMesh.js';
+import { trafficCollision } from './trafficCollision.js';
+import { local } from '../projections/walkerLocalPosition.js';
+
+/**
+ * Check the walker's body heights against scene geometry and current traffic bounds, excluding terrain.
+ *
+ * @param {Object} context Walk control state and reusable collision scratch.
+ *
+ * @returns {boolean} Whether the walker overlaps traffic or is enclosed by a mesh.
+ */
+export function insideWalker(context) {
+  const { layer, local: localBuffer, hitData } = context;
+  const shared = sharedByLayer.get(layer);
+  if (!shared || !layersByLayer.get(shared)) return false;
+  updateWorldMatrix(sceneByLayer.get(layer));
+  const root = rootByLayer.get(layer);
+  const feet = local.call(context, localBuffer);
+  const x = root.position[0] + feet[0] * root.scale[0];
+  const y = root.position[1] + feet[1] * root.scale[1];
+  const z = root.position[2] + feet[2] * root.scale[2];
+  const layers = layersByLayer.get(shared);
+  let other, node, child, nodes;
+  for (other of layers) {
+    if (other === layer || kindByLayer.get(other) === 'terrain') continue;
+    if (kindByLayer.get(other) === 'traffic') {
+      hitData.best = 0;
+      hitData.found = false;
+      if (trafficCollision(other, x, y, z, 0, 0, 0, hitData)) return true;
+      continue;
+    }
+    nodes = hitData.nodes;
+    nodes.length = 0;
+    if (rootByLayer.get(other)) nodes.push(rootByLayer.get(other));
+    while (nodes.length) {
+      node = nodes.pop();
+      if (!node.visible) continue;
+      if (node.geometry && (
+        insideMesh(node, x, y + 0.45 * root.scale[1], z, hitData.seen, hitData.intersections) ||
+        insideMesh(node, x, y + 1.35 * root.scale[1], z, hitData.seen, hitData.intersections)
+      )) return true;
+      for (child of node.children) nodes.push(child);
+    }
+  }
+  return false;
+}

package/src/collision/intersectMeshes.js

@@ -1,32 +1,40 @@
-import { sortHits } from './sortHits.js';
-import { localRay } from './localRay.js';
-import { rayBounds } from './rayBounds.js';
-import { readTriangle } from './readTriangle.js';
-import { triangleDistance } from './triangleDistance.js';
-import { worldHit } from './worldHit.js';
-
-/** Nearest triangle hit per mesh, sorted by world-space distance. */
-export function intersectMeshes(ray, meshes, night = 0) {
-  const hits = /* alloc */ [];
-  const a = /* alloc */ [0, 0, 0], b = /* alloc */ [0, 0, 0], c = /* alloc */ [0, 0, 0];
-  const origin = /* alloc */ [0, 0, 0], direction = /* alloc */ [0, 0, 0];
-  let mesh, position, index, instanceOffset, vertices, closest, faceIndex, i, distance;
-  for (mesh of meshes) {
-    // Test locally, then compare distances in shared world space.
-    localRay(ray, mesh, origin, direction);
-    if (!rayBounds(mesh, origin, direction)) continue;
-    ({ position, index, instanceOffset } = mesh.geometry.attributes);
-    vertices = index?.count || position.count;
-    closest = Infinity, faceIndex = void 0;
-    for (i = 0; i < vertices * (instanceOffset?.count ?? 1); i += 3) {
-      readTriangle(mesh, i, a, b, c);
-      distance = triangleDistance(mesh, i, a, b, c, origin, direction, night);
-      if (distance > 0 && distance < closest) {
-        closest = distance; faceIndex = i / 3;
-      }
-    }
-    if (faceIndex === undefined) continue;
-    hits.push(worldHit(ray, mesh, origin, direction, closest, faceIndex));
-  }
-  return sortHits(hits);
-}
+import { sortHits } from './sortHits.js';
+import { localRay } from './localRay.js';
+import { rayBounds } from './rayBounds.js';
+import { readTriangle } from './readTriangle.js';
+import { triangleDistance } from './triangleDistance.js';
+import { worldHit } from './worldHit.js';
+
+/**
+ * Find the nearest triangle hit per mesh, sorted by world-space distance.
+ *
+ * @param {Object} ray World-space ray with origin and direction.
+ * @param {Object[]} meshes Meshes to test.
+ * @param {number} [night] Night-light intensity for halo picking.
+ *
+ * @returns {Object[]} Nearest hit for each intersected mesh.
+ */
+export function intersectMeshes(ray, meshes, night = 0) {
+  const hits = /* alloc */ [];
+  const a = /* alloc */ [0, 0, 0], b = /* alloc */ [0, 0, 0], c = /* alloc */ [0, 0, 0];
+  const origin = /* alloc */ [0, 0, 0], direction = /* alloc */ [0, 0, 0];
+  let mesh, position, index, instanceOffset, vertices, closest, faceIndex, i, distance;
+  for (mesh of meshes) {
+    // Test locally, then compare distances in shared world space.
+    localRay(ray, mesh, origin, direction);
+    if (!rayBounds(mesh, origin, direction)) continue;
+    ({ position, index, instanceOffset } = mesh.geometry.attributes);
+    vertices = index?.count || position.count;
+    closest = Infinity, faceIndex = void 0;
+    for (i = 0; i < vertices * (instanceOffset?.count ?? 1); i += 3) {
+      readTriangle(mesh, i, a, b, c);
+      distance = triangleDistance(mesh, i, a, b, c, origin, direction, night);
+      if (distance > 0 && distance < closest) {
+        closest = distance; faceIndex = i / 3;
+      }
+    }
+    if (faceIndex === undefined) continue;
+    hits.push(worldHit(ray, mesh, origin, direction, closest, faceIndex));
+  }
+  return sortHits(hits);
+}

package/src/collision/localRay.js

@@ -1,21 +1,31 @@
-export function localRay(ray, mesh, origin, direction) {
-  const inverse = /* alloc */ new DOMMatrix(mesh.worldMatrix).invertSelf();
-  const inverseValues = inverse.toFloat64Array();
-  let value, x, y, z, w;
-  for (value of inverseValues) {
-    if (!Number.isFinite(value)) throw /* alloc */ new Error('Singular 3D transform');
-  }
-  x = ray.origin[0], y = ray.origin[1], z = ray.origin[2];
-  w = inverseValues[3] * x + inverseValues[7] * y + inverseValues[11] * z + inverseValues[15];
-  origin[0] = (inverseValues[0] * x + inverseValues[4] * y + inverseValues[8] * z + inverseValues[12]) / w;
-  origin[1] = (inverseValues[1] * x + inverseValues[5] * y + inverseValues[9] * z + inverseValues[13]) / w;
-  origin[2] = (inverseValues[2] * x + inverseValues[6] * y + inverseValues[10] * z + inverseValues[14]) / w;
-  x = ray.direction[0], y = ray.direction[1], z = ray.direction[2];
-  direction[0] = inverseValues[0] * x + inverseValues[4] * y + inverseValues[8] * z;
-  direction[1] = inverseValues[1] * x + inverseValues[5] * y + inverseValues[9] * z;
-  direction[2] = inverseValues[2] * x + inverseValues[6] * y + inverseValues[10] * z;
-  const directionLength = Math.hypot(...direction) || 1;
-  direction[0] /= directionLength;
-  direction[1] /= directionLength;
-  direction[2] /= directionLength;
-}
+/**
+ * Transform a world-space ray into mesh coordinates, normalizing its direction and rejecting singular transforms.
+ *
+ * @param {Object} ray World-space origin and direction.
+ * @param {Object} mesh Mesh whose world matrix is inverted.
+ * @param {number[]} origin Output local origin.
+ * @param {number[]} direction Output normalized local direction.
+ *
+ * @throws {Error} If the inverse transform contains non-finite values.
+ */
+export function localRay(ray, mesh, origin, direction) {
+  const inverse = /* alloc */ new DOMMatrix(mesh.worldMatrix).invertSelf();
+  const inverseValues = inverse.toFloat64Array();
+  let value, x, y, z, w;
+  for (value of inverseValues) {
+    if (!Number.isFinite(value)) throw /* alloc */ new Error('Singular 3D transform');
+  }
+  x = ray.origin[0], y = ray.origin[1], z = ray.origin[2];
+  w = inverseValues[3] * x + inverseValues[7] * y + inverseValues[11] * z + inverseValues[15];
+  origin[0] = (inverseValues[0] * x + inverseValues[4] * y + inverseValues[8] * z + inverseValues[12]) / w;
+  origin[1] = (inverseValues[1] * x + inverseValues[5] * y + inverseValues[9] * z + inverseValues[13]) / w;
+  origin[2] = (inverseValues[2] * x + inverseValues[6] * y + inverseValues[10] * z + inverseValues[14]) / w;
+  x = ray.direction[0], y = ray.direction[1], z = ray.direction[2];
+  direction[0] = inverseValues[0] * x + inverseValues[4] * y + inverseValues[8] * z;
+  direction[1] = inverseValues[1] * x + inverseValues[5] * y + inverseValues[9] * z;
+  direction[2] = inverseValues[2] * x + inverseValues[6] * y + inverseValues[10] * z;
+  const directionLength = Math.hypot(...direction) || 1;
+  direction[0] /= directionLength;
+  direction[1] /= directionLength;
+  direction[2] /= directionLength;
+}

package/src/collision/mergeHits.js

@@ -1,11 +1,19 @@
-export function mergeHits(source, target, start, width) {
-  const middle = Math.min(start + width, source.length), end = Math.min(start + width * 2, source.length);
-  let left = start, right = middle, output;
-  for (output = start; output < end; output++) {
-    if (left < middle && (right >= end || !(source[right].distance < source[left].distance))) {
-      target[output] = source[left++];
-    } else {
-      target[output] = source[right++];
-    }
-  }
-}
+/**
+ * Merge two adjacent, distance-sorted hit runs into the target buffer, preserving ties.
+ *
+ * @param {Object[]} source Array containing the sorted runs.
+ * @param {Object[]} target Array receiving the merged run.
+ * @param {number} start First index of the runs.
+ * @param {number} width Maximum length of each run.
+ */
+export function mergeHits(source, target, start, width) {
+  const middle = Math.min(start + width, source.length), end = Math.min(start + width * 2, source.length);
+  let left = start, right = middle, output;
+  for (output = start; output < end; output++) {
+    if (left < middle && (right >= end || !(source[right].distance < source[left].distance))) {
+      target[output] = source[left++];
+    } else {
+      target[output] = source[right++];
+    }
+  }
+}

package/src/collision/missesBox.js

@@ -0,0 +1,13 @@
+/**
+ * Whether a ray's box interval cannot produce a closer hit.
+ *
+ * @param {number} entry Ray parameter where the box is entered.
+ * @param {number} exit Ray parameter where the box is left.
+ * @param {number} reach Movement distance, or zero to test overlap.
+ * @param {number} best Closest hit found so far.
+ *
+ * @returns {boolean} True when the box is missed or too far to matter.
+ */
+export function missesBox(entry, exit, reach, best) {
+  return entry > exit || exit < 0 || entry > reach || (reach && Math.max(0, entry) >= best);
+}