leaflet-city-mapper 0.0.8 → 0.1.0

package/src/cog/readCogLevel.js

@@ -3,6 +3,15 @@ import { getCogBase } from './getCogBase.js';
 import { validCogGrid } from './validCogGrid.js';
 import { validateCogOffsets } from './validateCogOffsets.js';
 
+/**
+ * Validate and register one TIFF directory as a COG XYZ level.
+ *
+ * @param {Object} source Open COG source and level map.
+ * @param {Object} directory TIFF directory with parsed tags.
+ * @param {Object} state Mutable base image and zoom range.
+ *
+ * @throws {Error} If the level does not align with the supported Web Mercator grid.
+ */
 export function readCogLevel(source, directory, state) {
   const tags = directory.tags, profile = getCogProfile(tags);
   if (!state.base) state.base = getCogBase(tags, profile.width, profile.height, profile.elevation);

package/src/cog/readCogTag.js

@@ -1,5 +1,18 @@
 import { readCog } from './readCog.js';
 
+/**
+ * Read the numeric values of a supported TIFF directory entry.
+ *
+ * @param {Object} source Open COG byte source.
+ * @param {DataView} entries Directory entry data.
+ * @param {number} i Entry index.
+ * @param {number} tag TIFF tag number.
+ * @param {boolean} little Whether the TIFF uses little-endian byte order.
+ *
+ * @returns {Promise<Array<number>>} Decoded tag values.
+ *
+ * @throws {Error} If the tag type or value count is unsupported.
+ */
 export async function readCogTag(source, entries, i, tag, little) {
   const type = entries.getUint16(i * 12 + 2, little);
   const size = type === 3 ? 2 : type === 4 ? 4 : type === 12 ? 8 : 0;

package/src/cog/validCogDimensions.js

@@ -1,3 +1,12 @@
+/**
+ * Check COG image dimensions, tile size, compression, planar layout and predictor.
+ *
+ * @param {Map} tags TIFF tags.
+ * @param {number} width Image width.
+ * @param {number} height Image height.
+ *
+ * @returns {boolean} Whether the image uses supported dimensions and layout.
+ */
 export function validCogDimensions(tags, width, height) {
   return !!width && !!height && width % 256 === 0 && height % 256 === 0 &&
     tags.get(322)?.[0] === 256 && tags.get(323)?.[0] === 256 &&

package/src/cog/validCogEncoding.js

@@ -1,3 +1,16 @@
+/**
+ * Check whether a TIFF profile is supported grayscale elevation or unsigned RGB(A).
+ *
+ * @param {Map} tags TIFF tags.
+ * @param {number} samples Samples per pixel.
+ * @param {Array<number>} bits Bits per sample.
+ * @param {Array<number>} format Sample format values.
+ * @param {boolean} elevation Whether the profile is Float32 elevation.
+ * @param {boolean} bytes Whether all samples use eight bits.
+ * @param {boolean} unsigned Whether all sample formats are unsigned.
+ *
+ * @returns {boolean} Whether the encoding is supported.
+ */
 export function validCogEncoding(tags, samples, bits, format, elevation, bytes, unsigned) {
   if (elevation) return tags.get(262)?.[0] === 1;
   return (samples === 3 || samples === 4) && bits?.length === samples && bytes && unsigned &&

package/src/cog/validCogGeoArrays.js

@@ -1,5 +1,14 @@
 import { finiteCogValues } from './finiteCogValues.js';
 
+/**
+ * Validate the structure and numeric values of GeoTIFF key, pixel scale and tiepoint arrays.
+ *
+ * @param {Array<number>} keys GeoKey directory.
+ * @param {Array<number>} scale Pixel scale values.
+ * @param {Array<number>} tie Tiepoint values.
+ *
+ * @returns {boolean} Whether the arrays describe a supported north-up grid.
+ */
 export function validCogGeoArrays(keys, scale, tie) {
   return !!keys && keys[0] === 1 && keys.length === 4 + keys[3] * 4 &&
     !!scale && scale.length === 3 && finiteCogValues(scale) &&

package/src/cog/validCogGrid.js

@@ -1,3 +1,16 @@
+/**
+ * Check that a COG level aligns with the supported Web Mercator XYZ grid.
+ *
+ * @param {Object} source COG source and existing levels.
+ * @param {Object} base Base image profile and georeferencing.
+ * @param {Object} profile Level dimensions and elevation flag.
+ * @param {number} zoom Derived XYZ zoom.
+ * @param {number} x Level's XYZ column origin.
+ * @param {number} y Level's XYZ row origin.
+ * @param {number} resolution Level resolution.
+ *
+ * @returns {boolean} Whether the level is supported and grid-aligned.
+ */
 export function validCogGrid(source, base, profile, zoom, x, y, resolution) {
   return zoom >= 0 && zoom <= 24 &&
     Math.abs(20037508.342789244 * 2 / (256 * 2 ** zoom) - resolution) <= resolution * 1e-7 &&

package/src/cog/validCogTileCoordinates.js

@@ -1,3 +1,12 @@
+/**
+ * Check that XYZ coordinates are safe integers within the supported zoom and tile range.
+ *
+ * @param {number} z Tile zoom.
+ * @param {number} x Tile column.
+ * @param {number} y Tile row.
+ *
+ * @returns {boolean} Whether the coordinates are valid.
+ */
 export function validCogTileCoordinates(z, x, y) {
   return Number.isSafeInteger(z) && Number.isSafeInteger(x) && Number.isSafeInteger(y) &&
     z >= 0 && z <= 24 && x >= 0 && y >= 0 && x < 2 ** z && y < 2 ** z;

package/src/cog/validateCogContainer.js

@@ -1,3 +1,11 @@
+/**
+ * Validate the PMTiles header and bounds for a COG asset container.
+ *
+ * @param {Object} container Container source with known size.
+ * @param {Object} header Decoded PMTiles header.
+ *
+ * @throws {Error} If the container metadata or tile data range is invalid.
+ */
 export function validateCogContainer(container, header) {
   if (header.tileType !== 0 || header.tileCompression !== 1 ||
     !Number.isSafeInteger(header.jsonMetadataOffset) || !Number.isSafeInteger(header.jsonMetadataLength) ||

package/src/cog/validateCogContentRange.js

@@ -1,3 +1,13 @@
+/**
+ * Validate a parsed Content-Range against the requested bytes and known source size.
+ *
+ * @param {Object} source COG source and optional known size.
+ * @param {RegExpExecArray|null} range Parsed Content-Range.
+ * @param {number} rangeStart Requested absolute byte offset.
+ * @param {number} length Requested byte length.
+ *
+ * @throws {Error} If the content range or total size is inconsistent.
+ */
 export function validateCogContentRange(source, range, rangeStart, length) {
   if (!range || Number(range[1]) !== rangeStart || Number(range[2]) !== rangeStart + length - 1 ||
     !Number.isSafeInteger(Number(range[3])) || Number(range[3]) < rangeStart + length ||

package/src/cog/validateCogOffsets.js

@@ -1,3 +1,12 @@
+/**
+ * Validate the number and bounds of COG tile offsets and lengths.
+ *
+ * @param {Object} source COG source with known size.
+ * @param {Object} level Level dimensions, offsets and lengths.
+ *
+ * @throws {Error} If the offset or length arrays have invalid counts.
+ * @throws {Error} If a tile range is empty, oversized or outside the source.
+ */
 export function validateCogOffsets(source, level) {
   if (level.offsets?.length !== level.columns * level.rows || level.lengths?.length !== level.offsets.length) {
     throw /* alloc */ new Error('Invalid COG tile offsets or lengths');

package/src/cog/validateCogRange.js

@@ -1,3 +1,12 @@
+/**
+ * Validate a requested COG byte range against size and numeric limits.
+ *
+ * @param {Object} source COG source with optional known size.
+ * @param {number} offset Source-relative byte offset.
+ * @param {number} length Requested byte length.
+ *
+ * @throws {Error} If the range is invalid or exceeds the supported bounds.
+ */
 export function validateCogRange(source, offset, length) {
   if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 ||
     length <= 0 || length > 32000000 || !Number.isSafeInteger(offset + length) ||

package/src/cog/validateCogResponse.js

@@ -1,6 +1,17 @@
 import { validateCogContentRange } from './validateCogContentRange.js';
 import { invalidCogFullResponse } from './invalidCogFullResponse.js';
 
+/**
+ * Validate a COG HTTP response's entity tag, range and full-response size.
+ *
+ * @param {Object} source COG source whose ETag and size are updated.
+ * @param {Response} response HTTP response.
+ * @param {number} rangeStart Requested absolute byte offset.
+ * @param {number} length Requested byte length.
+ *
+ * @throws {Error} If the source ETag changes.
+ * @throws {Error} If a full response is unsupported or too large.
+ */
 export function validateCogResponse(source, response, rangeStart, length) {
   const etag = response.headers.get('ETag');
   if (source.etag && source.etag !== etag) throw /* alloc */ new Error('COG changed; recreate the layer');

package/src/collision/README.md

@@ -0,0 +1,28 @@
+# Collision
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Builds and queries collision geometry for movement and spatial intersection.
+Mesh colliders cache triangles and a spatial grid; callers use these queries for
+walker and traffic interactions.
+
+## Spatial queries
+
+```mermaid
+flowchart LR
+  Mesh["Mesh geometry + world transform"] --> Cache["Cached triangles + grid"]
+  Walker["Walker body / movement"] --> Query["Collision query"]
+  Cache --> Query
+  Traffic["Current traffic bounds"] --> Query
+  Query --> Move["Stop / slide / find clear position"]
+```
+
+[insideWalker.js](./insideWalker.js) excludes terrain and checks body heights.
+This tests current traffic positions; traffic does not steer around the walker.
+[Picking](../picking/README.md) resolves pointer hits instead.
+
+- [collider.js](./collider.js): build or reuse a mesh collider.
+- [insideWalker.js](./insideWalker.js): test the walker's surroundings.
+- [indexTriangle.js](./indexTriangle.js): index a triangle into grid cells.
+
+Related: [walk](../walk/README.md), [picking](../picking/README.md), [traffic](../traffic/README.md).

package/src/collision/advanceFeature.js

@@ -0,0 +1,13 @@
+/**
+ * Advance a feature index past the feature ranges that end at or before a face.
+ *
+ * @param {Object[]|undefined} ranges Feature metadata with faceEnd offsets.
+ * @param {number} feature Current feature index.
+ * @param {number} face Face index.
+ *
+ * @returns {number} Feature index containing the face.
+ */
+export function advanceFeature(ranges, feature, face) {
+  while (ranges && feature < ranges.length && face >= ranges[feature].faceEnd) feature++;
+  return feature;
+}

package/src/collision/boxNormal.js

@@ -0,0 +1,29 @@
+/**
+ * Local-space normal of the box face a ray hits, or the nearest face when the origin is inside.
+ *
+ * @param {number} entry Ray parameter where the box is entered.
+ * @param {boolean} xFirst Whether the x slab is entered after the z slab.
+ * @param {number} ox Local ray origin x.
+ * @param {number} oz Local ray origin z.
+ * @param {number} ux Local ray direction x.
+ * @param {number} uz Local ray direction z.
+ * @param {Object} bounds Local vehicle bounds.
+ * @param {number} margin Padding added around the bounds.
+ * @param {number[]} out Receives the normal x and z.
+ */
+export function boxNormal(entry, xFirst, ox, oz, ux, uz, bounds, margin, out) {
+  if (entry >= 0) {
+    out[0] = xFirst ? -Math.sign(ux) : 0;
+    out[1] = xFirst ? 0 : -Math.sign(uz);
+    return;
+  }
+  let nearest = ox - (bounds.minX - margin);
+  out[0] = -1; out[1] = 0;
+  if (bounds.maxX + margin - ox < nearest) {
+    nearest = bounds.maxX + margin - ox; out[0] = 1;
+  }
+  if (oz - (bounds.minZ - margin) < nearest) {
+    nearest = oz - (bounds.minZ - margin); out[0] = 0; out[1] = -1;
+  }
+  if (bounds.maxZ + margin - oz < nearest) { out[0] = 0; out[1] = 1; }
+}

package/src/collision/cachedCollider.js

@@ -0,0 +1,18 @@
+import { colliders } from '../weakmaps/colliders.js';
+
+/**
+ * Return a mesh's cached collider when its geometry and rotation/scale are unchanged.
+ *
+ * @param {Object} mesh Mesh containing geometry and a world matrix.
+ *
+ * @returns {Object|undefined} The valid cached collider, if any.
+ */
+export function cachedCollider(mesh) {
+  const c = colliders.get(mesh), m = mesh.worldMatrix;
+  if (!c || c.geometry !== mesh.geometry) return undefined;
+  let i;
+  for (i = 0; i < 12; i++) {
+    if (i % 4 !== 3 && c.matrix[i] !== m[i]) return undefined;
+  }
+  return c;
+}

package/src/collision/collectIntersections.js

@@ -1,16 +1,41 @@
 import { CELL } from '../globals/CELL.js';
 import { horizontalRay } from './horizontalRay.js';
 
+/**
+ * Collect positive X-ray hits and polygon footprint crossings, grouped by feature in the shared hits array.
+ *
+ * @param {Object} shape Cached collider and its spatial grid.
+ * @param {number} x Ray origin x coordinate.
+ * @param {number} y Ray origin y coordinate.
+ * @param {number} z Ray origin z coordinate.
+ * @param {Set<number>} seen Reusable set of visited triangle indices.
+ * @param {number[]} hits Output array of feature keys and distances.
+ * @param {number} end Last x cell to inspect.
+ * @param {number} iz Z cell containing the ray.
+ */
 export function collectIntersections(shape, x, y, z, seen, hits, end, iz) {
-  let ix, cell, triangle, distance;
+  const { tri, features, ranges } = shape;
+  let ix, cell, triangle, distance, feature, i, ax, az, bx, bz, cx, cz, ab, ac, bc;
   for (ix = Math.floor(x / CELL); ix <= end; ix++) {
     cell = shape.cells.get(`${ix},${iz}`);
     if (!cell) continue;
     for (triangle of cell) {
       if (seen.has(triangle)) continue;
       seen.add(triangle);
-      distance = horizontalRay(shape.tri, triangle, x, y, z, 1, 0);
-      if (distance > 1e-4) hits.push(distance);
+      feature = features[triangle];
+      distance = horizontalRay(tri, triangle, x, y, z, 1, 0);
+      if (distance > 1e-4) hits.push(feature * 2, distance);
+      if (!ranges?.[feature]?.polygon) continue;
+      i = triangle * 9;
+      ax = tri[i], az = tri[i + 2], bx = tri[i + 3], bz = tri[i + 5], cx = tri[i + 6], cz = tri[i + 8];
+      ab = (ax - bx) ** 2 + (az - bz) ** 2;
+      ac = (ax - cx) ** 2 + (az - cz) ** 2;
+      bc = (bx - cx) ** 2 + (bz - cz) ** 2;
+      if (ac > ab && ac >= bc) bx = cx, bz = cz;
+      else if (bc > ab && bc > ac) ax = bx, az = bz, bx = cx, bz = cz;
+      if ((az > z) === (bz > z)) continue;
+      distance = ax + (z - az) * (bx - ax) / (bz - az) - x;
+      if (distance > 1e-4) hits.push(feature * 2 + 1, distance);
     }
   }
 }

package/src/collision/collectMeshes.js

@@ -1,3 +1,9 @@
+/**
+ * Append positioned meshes from a node and its descendants to the supplied array.
+ *
+ * @param {Object} node Scene node to traverse.
+ * @param {Object[]} meshes Array receiving the meshes.
+ */
 export function collectMeshes(node, meshes) {
   if (node.geometry?.attributes.position) meshes.push(node);
   let child;

package/src/collision/collideTrip.js

@@ -0,0 +1,56 @@
+import { locateTraffic } from '../traffic/locateTraffic.js';
+import { boxNormal } from './boxNormal.js';
+import { trafficRay } from './trafficRay.js';
+import { missesBox } from './missesBox.js';
+import { slabDistance } from './slabDistance.js';
+import { slabMiss } from './slabMiss.js';
+
+/**
+ * Test a walker point or movement ray against one traffic trip, updating data when it is the nearest hit.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Object} trip Trip to test.
+ * @param {Object} root Traffic root with position and scale arrays.
+ * @param {Object} bounds Local vehicle bounds.
+ * @param {number} x Walker world-space x coordinate.
+ * @param {number} y Walker world-space feet height.
+ * @param {number} z Walker world-space z coordinate.
+ * @param {number} dx Movement direction x.
+ * @param {number} dz Movement direction z.
+ * @param {number} reach Movement distance, or zero to test overlap.
+ * @param {Object} data Reusable hit record.
+ */
+export function collideTrip(state, trip, root, bounds, x, y, z, dx, dz, reach, data) {
+  const position = state.position ||= /* alloc */ {};
+  const ray = state.ray ||= /* alloc */ [0, 0, 0, 0];
+  const normal = state.localNormal ||= /* alloc */ [0, 0];
+  const scale = Math.max(root.scale[0], root.scale[1], root.scale[2]);
+  // ponytail: oriented bounding boxes include empty corners; use vehicle geometry if that matters.
+  const margin = 0.35 / scale;
+  const { x: px, y: py, z: pz } = locateTraffic(state, trip, position);
+  const bottom = root.position[1] + (py + bounds.minY) * root.scale[1];
+  const top = root.position[1] + (position.y + bounds.maxY) * root.scale[1];
+  if (bottom > y + 1.7 * scale || top < y + 0.2 * scale) return;
+  trafficRay(root, position, x, z, dx, dz, px, pz, ray);
+  const ox = ray[0], oz = ray[1], ux = ray[2], uz = ray[3];
+  if (slabMiss(ox, ux, bounds.minX, bounds.maxX, margin) || slabMiss(oz, uz, bounds.minZ, bounds.maxZ, margin)) return;
+  const nearX = slabDistance(ox, ux, bounds.minX - margin, bounds.maxX + margin, -Infinity);
+  const farX = slabDistance(ox, ux, bounds.maxX + margin, bounds.minX - margin, Infinity);
+  const nearZ = slabDistance(oz, uz, bounds.minZ - margin, bounds.maxZ + margin, -Infinity);
+  const farZ = slabDistance(oz, uz, bounds.maxZ + margin, bounds.minZ - margin, Infinity);
+  const entry = Math.max(nearX, nearZ);
+  if (missesBox(entry, Math.min(farX, farZ), reach, data.best)) return;
+  if (!reach) {
+    data.found = true;
+    return;
+  }
+  boxNormal(entry, nearX > nearZ, ox, oz, ux, uz, bounds, margin, normal);
+  const worldX = (-normal[0] * position.dz - normal[1] * position.dx) / root.scale[0];
+  const worldZ = (normal[0] * position.dx - normal[1] * position.dz) / root.scale[2];
+  if (entry < 0 && dx * worldX + dz * worldZ >= 0) return;
+  const length = Math.hypot(worldX, worldZ);
+  data.best = Math.max(0, entry);
+  data.found = true;
+  data.normal[0] = worldX / length;
+  data.normal[1] = worldZ / length;
+}

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,3 +1,14 @@
+/**
+ * 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;

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,5 +1,12 @@
 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++)