leaflet-city-mapper 0.0.9 → 0.1.1

package/src/cog/readCogTag.js

@@ -1,15 +1,28 @@
-import { readCog } from './readCog.js';
-
-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;
-  const length = entries.getUint32(i * 12 + 4, little);
-  if (!size || !length || length > 1048576) throw /* alloc */ new Error(`Unsupported COG tag ${tag}`);
-  const data = size * length <= 4 ? /* alloc */ new DataView(entries.buffer, i * 12 + 8, 4)
-    : /* alloc */ new DataView(await readCog(source, entries.getUint32(i * 12 + 8, little), size * length));
-  const values = /* alloc */ [];
-  let j;
-  for (j = 0; j < length; j++) values.push(type === 3 ? data.getUint16(j * size, little)
-    : type === 4 ? data.getUint32(j * size, little) : data.getFloat64(j * size, little));
-  return values;
-}
+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;
+  const length = entries.getUint32(i * 12 + 4, little);
+  if (!size || !length || length > 1048576) throw /* alloc */ new Error(`Unsupported COG tag ${tag}`);
+  const data = size * length <= 4 ? /* alloc */ new DataView(entries.buffer, i * 12 + 8, 4)
+    : /* alloc */ new DataView(await readCog(source, entries.getUint32(i * 12 + 8, little), size * length));
+  const values = /* alloc */ [];
+  let j;
+  for (j = 0; j < length; j++) values.push(type === 3 ? data.getUint16(j * size, little)
+    : type === 4 ? data.getUint32(j * size, little) : data.getFloat64(j * size, little));
+  return values;
+}

package/src/cog/validCogDimensions.js

@@ -1,6 +1,15 @@
-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 &&
-    (tags.get(259)?.[0] === 1 || tags.get(259)?.[0] === 8) &&
-    (tags.get(284)?.[0] ?? 1) === 1 && (tags.get(317)?.[0] ?? 1) === 1;
-}
+/**
+ * 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 &&
+    (tags.get(259)?.[0] === 1 || tags.get(259)?.[0] === 8) &&
+    (tags.get(284)?.[0] ?? 1) === 1 && (tags.get(317)?.[0] ?? 1) === 1;
+}

package/src/cog/validCogEncoding.js

@@ -1,5 +1,18 @@
-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 &&
-    tags.get(262)?.[0] === 2;
-}
+/**
+ * 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 &&
+    tags.get(262)?.[0] === 2;
+}

package/src/cog/validCogGeoArrays.js

@@ -1,8 +1,17 @@
-import { finiteCogValues } from './finiteCogValues.js';
-
-export function validCogGeoArrays(keys, scale, tie) {
-  return !!keys && keys[0] === 1 && keys.length === 4 + keys[3] * 4 &&
-    !!scale && scale.length === 3 && finiteCogValues(scale) &&
-    scale[0] > 0 && Math.abs(scale[0] - scale[1]) <= 1e-8 &&
-    !!tie && tie.length === 6 && finiteCogValues(tie) && tie[0] === 0 && tie[1] === 0;
-}
+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) &&
+    scale[0] > 0 && Math.abs(scale[0] - scale[1]) <= 1e-8 &&
+    !!tie && tie.length === 6 && finiteCogValues(tie) && tie[0] === 0 && tie[1] === 0;
+}

package/src/cog/validCogGrid.js

@@ -1,9 +1,22 @@
-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 &&
-    (!profile.elevation || Number.isInteger(x) && Number.isInteger(y)) &&
-    Math.abs(base.width / profile.width - base.height / profile.height) <= 1e-7 &&
-    profile.elevation === base.elevation &&
-    x >= 0 && y >= 0 && x + profile.width / 256 <= 2 ** zoom && y + profile.height / 256 <= 2 ** zoom &&
-    !source.levels.has(zoom) && !(base.elevation && source.levels.size);
-}
+/**
+ * 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 &&
+    (!profile.elevation || Number.isInteger(x) && Number.isInteger(y)) &&
+    Math.abs(base.width / profile.width - base.height / profile.height) <= 1e-7 &&
+    profile.elevation === base.elevation &&
+    x >= 0 && y >= 0 && x + profile.width / 256 <= 2 ** zoom && y + profile.height / 256 <= 2 ** zoom &&
+    !source.levels.has(zoom) && !(base.elevation && source.levels.size);
+}

package/src/cog/validCogTileCoordinates.js

@@ -1,4 +1,13 @@
-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;
-}
+/**
+ * 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,9 +1,17 @@
-export function validateCogContainer(container, header) {
-  if (header.tileType !== 0 || header.tileCompression !== 1 ||
-    !Number.isSafeInteger(header.jsonMetadataOffset) || !Number.isSafeInteger(header.jsonMetadataLength) ||
-    header.jsonMetadataLength <= 0 || header.jsonMetadataLength > 1048576 ||
-    !Number.isSafeInteger(header.tileDataOffset) || !Number.isSafeInteger(header.tileDataLength) ||
-    header.tileDataOffset < 127 || header.tileDataOffset + header.tileDataLength > container.size) {
-    throw /* alloc */ new Error('Invalid PMTiles COG asset container');
-  }
-}
+/**
+ * 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) ||
+    header.jsonMetadataLength <= 0 || header.jsonMetadataLength > 1048576 ||
+    !Number.isSafeInteger(header.tileDataOffset) || !Number.isSafeInteger(header.tileDataLength) ||
+    header.tileDataOffset < 127 || header.tileDataOffset + header.tileDataLength > container.size) {
+    throw /* alloc */ new Error('Invalid PMTiles COG asset container');
+  }
+}

package/src/cog/validateCogContentRange.js

@@ -1,8 +1,18 @@
-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 ||
-    (source.containerSize ?? source.size) !== undefined &&
-      (source.containerSize ?? source.size) !== Number(range[3])) {
-    throw /* alloc */ new Error('Invalid COG range response');
-  }
-}
+/**
+ * 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 ||
+    (source.containerSize ?? source.size) !== undefined &&
+      (source.containerSize ?? source.size) !== Number(range[3])) {
+    throw /* alloc */ new Error('Invalid COG range response');
+  }
+}

package/src/cog/validateCogOffsets.js

@@ -1,10 +1,19 @@
-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');
-  }
-  let i;
-  for (i = 0; i < level.offsets.length; i++) {
-    if (!level.offsets[i] || !level.lengths[i] || level.lengths[i] > 1048576 ||
-      level.offsets[i] + level.lengths[i] > source.size) throw /* alloc */ new Error('Invalid COG tile offsets or lengths');
-  }
-}
+/**
+ * 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');
+  }
+  let i;
+  for (i = 0; i < level.offsets.length; i++) {
+    if (!level.offsets[i] || !level.lengths[i] || level.lengths[i] > 1048576 ||
+      level.offsets[i] + level.lengths[i] > source.size) throw /* alloc */ new Error('Invalid COG tile offsets or lengths');
+  }
+}

package/src/cog/validateCogRange.js

@@ -1,7 +1,16 @@
-export function validateCogRange(source, offset, length) {
-  if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 ||
-    length <= 0 || length > 32000000 || !Number.isSafeInteger(offset + length) ||
-    source.size !== undefined && offset + length > source.size) {
-    throw /* alloc */ new Error('Invalid COG byte range');
-  }
-}
+/**
+ * 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) ||
+    source.size !== undefined && offset + length > source.size) {
+    throw /* alloc */ new Error('Invalid COG byte range');
+  }
+}

package/src/cog/validateCogResponse.js

@@ -1,15 +1,26 @@
-import { validateCogContentRange } from './validateCogContentRange.js';
-import { invalidCogFullResponse } from './invalidCogFullResponse.js';
-
-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');
-  if (etag) source.etag = etag;
-  const range = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(response.headers.get('Content-Range') || '');
-  if (response.status === 206) {
-    validateCogContentRange(source, range, rangeStart, length);
-    if (source.baseOffset === undefined) source.size = Number(range[3]);
-  } else if (invalidCogFullResponse(response)) {
-    throw /* alloc */ new Error('COG server must support byte ranges for files over 32 MB');
-  }
-}
+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');
+  if (etag) source.etag = etag;
+  const range = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(response.headers.get('Content-Range') || '');
+  if (response.status === 206) {
+    validateCogContentRange(source, range, rangeStart, length);
+    if (source.baseOffset === undefined) source.size = Number(range[3]);
+  } else if (invalidCogFullResponse(response)) {
+    throw /* alloc */ new Error('COG server must support byte ranges for files over 32 MB');
+  }
+}

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';
-
-export function collectIntersections(shape, x, y, z, seen, hits, end, iz) {
-  let ix, cell, triangle, distance;
-  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);
-    }
-  }
-}
+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) {
+  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);
+      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;
+}