leaflet-city-mapper 0.0.9 → 0.1.1

package/src/native/syncNativeStrokeZoom.js

@@ -1,29 +1,34 @@
-import { styleNativeMesh } from './styleNativeMesh.js';
-import { parseColor } from '../colors/parseColor.js';
-
-export function syncNativeStrokeZoom(state) {
-  const { source, meshes, strokeCoordinates, strokeAnchors } = state;
-  const mesh = meshes.get('stroke');
-  let i, r, g, b, fill;
-  if (mesh) {
-    const factor = 2 ** (state.strokeZoom - state.map.getZoom()) *
-      Number(source.options.weight) / state.strokeWeight;
-    const attribute = mesh.geometry.attributes.position;
-    if (mesh.program.uniforms.strokeScale) {
-      mesh.program.uniforms.strokeScale.value = factor;
-    } else {
-      for (i = 0; i < strokeCoordinates.length; i++) {
-        attribute.data[i] = strokeAnchors[i] + (strokeCoordinates[i] - strokeAnchors[i]) * factor;
-      }
-      attribute.needsUpdate = true;
-      mesh.geometry.bounds = null;
-    }
-    ({ r, g, b } = parseColor(source.options.color));
-    styleNativeMesh(state, mesh, /* alloc */ [r, g, b], source.options.opacity ?? 1);
-  }
-  fill = meshes.get('fill');
-  if (fill) {
-    ({ r, g, b } = parseColor(source.options.fillColor || source.options.color));
-    styleNativeMesh(state, fill, /* alloc */ [r, g, b], source.options.fillOpacity ?? 1);
-  }
-}
+import { styleNativeMesh } from './styleNativeMesh.js';
+import { parseColor } from '../colors/parseColor.js';
+
+/**
+ * Rescale a native stroke for the current zoom and refresh stroke and fill styles.
+ *
+ * @param {Object} state Native vector layer state.
+ */
+export function syncNativeStrokeZoom(state) {
+  const { source, meshes, strokeCoordinates, strokeAnchors } = state;
+  const mesh = meshes.get('stroke');
+  let i, r, g, b, fill;
+  if (mesh) {
+    const factor = 2 ** (state.strokeZoom - state.map.getZoom()) *
+      Number(source.options.weight) / state.strokeWeight;
+    const attribute = mesh.geometry.attributes.position;
+    if (mesh.program.uniforms.strokeScale) {
+      mesh.program.uniforms.strokeScale.value = factor;
+    } else {
+      for (i = 0; i < strokeCoordinates.length; i++) {
+        attribute.data[i] = strokeAnchors[i] + (strokeCoordinates[i] - strokeAnchors[i]) * factor;
+      }
+      attribute.needsUpdate = true;
+      mesh.geometry.bounds = null;
+    }
+    ({ r, g, b } = parseColor(source.options.color));
+    styleNativeMesh(state, mesh, /* alloc */ [r, g, b], source.options.opacity ?? 1);
+  }
+  fill = meshes.get('fill');
+  if (fill) {
+    ({ r, g, b } = parseColor(source.options.fillColor || source.options.color));
+    styleNativeMesh(state, fill, /* alloc */ [r, g, b], source.options.fillOpacity ?? 1);
+  }
+}

package/src/native/syncTerrainGridTile.js

@@ -1,28 +1,38 @@
-import { coreWhite } from '../globals/coreWhite.js';
-import { loadGridTerrain } from './loadGridTerrain.js';
-import { styleNativeMesh } from './styleNativeMesh.js';
-import { terrainGridMesh } from './terrainGridMesh.js';
-
-export function syncTerrainGridTile(state, key, tile, opacity) {
-  const retained = state.textures.get(key), mesh = state.meshes.get(key);
-  let request = state.terrainRequests.get(key);
-  if (!request || request.tile !== tile) {
-    request = /* alloc */ { tile, stream: state.terrainStream };
-    state.terrainRequests.set(key, request);
-    loadGridTerrain(state, key, tile, request);
-  }
-  if (!request.tiles) {
-    if (mesh && retained?.image === tile.el) {
-      retained.used = true;
-      styleNativeMesh(state, mesh, coreWhite, opacity);
-    }
-    return null;
-  }
-  if (mesh && mesh._terrainRequest === request && retained?.image === tile.el &&
-    retained.url === (tile.el.currentSrc || tile.el.src)) {
-    retained.used = true;
-    styleNativeMesh(state, mesh, coreWhite, opacity);
-    return mesh;
-  }
-  return terrainGridMesh(state, key, tile, request, opacity);
-}
+import { coreWhite } from '../globals/coreWhite.js';
+import { loadGridTerrain } from './loadGridTerrain.js';
+import { styleNativeMesh } from './styleNativeMesh.js';
+import { terrainGridMesh } from './terrainGridMesh.js';
+
+/**
+ * Request terrain for a grid tile and reuse or build its draped mesh.
+ *
+ * @param {Object} state Native grid layer state.
+ * @param {string} key Tile key.
+ * @param {Object} tile Loaded tile.
+ * @param {number} opacity Tile opacity.
+ *
+ * @returns {Object|null|undefined} Mesh when available, otherwise null or undefined.
+ */
+export function syncTerrainGridTile(state, key, tile, opacity) {
+  const retained = state.textures.get(key), mesh = state.meshes.get(key);
+  let request = state.terrainRequests.get(key);
+  if (!request || request.tile !== tile) {
+    request = /* alloc */ { tile, stream: state.terrainStream };
+    state.terrainRequests.set(key, request);
+    loadGridTerrain(state, key, tile, request);
+  }
+  if (!request.tiles) {
+    if (mesh && retained?.image === tile.el) {
+      retained.used = true;
+      styleNativeMesh(state, mesh, coreWhite, opacity);
+    }
+    return null;
+  }
+  if (mesh && mesh._terrainRequest === request && retained?.image === tile.el &&
+    retained.url === (tile.el.currentSrc || tile.el.src)) {
+    retained.used = true;
+    styleNativeMesh(state, mesh, coreWhite, opacity);
+    return mesh;
+  }
+  return terrainGridMesh(state, key, tile, request, opacity);
+}

package/src/native/syncVectorLayer.js

@@ -4,6 +4,11 @@ import { syncNativeStrokeZoom } from './syncNativeStrokeZoom.js';
 import { nativeVectorGeometry } from './nativeVectorGeometry.js';
 import { syncNativeStrokeAnchors } from './syncNativeStrokeAnchors.js';
 
+/**
+ * Synchronize native vector fill and stroke meshes or rescale them after zoom.
+ *
+ * @param {Object} state Native vector layer state.
+ */
 export function syncVectorLayer(state) {
   const { source } = state;
   if (state.zoomOnly) {

package/src/native/synchronizeNativeLayer.js

@@ -1,8 +1,5 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { L } from '../globals/L.js';
-
-
 import { current } from './isCurrentNativeLayer.js';
 import { syncGridLayer } from './syncGridLayer.js';
 import { syncImageOverlay } from './syncImageOverlay.js';
@@ -10,6 +7,11 @@ import { syncMarker } from './syncMarker.js';
 import { syncVectorLayer } from './syncVectorLayer.js';
 import { pruneNativeResources } from './pruneNativeResources.js';
 
+/**
+ * Synchronize a dirty native layer and dispose resources no longer in use.
+ *
+ * @param {Object} state Native layer state.
+ */
 export function synchronizeNativeLayer(state) {
   const { source, meshes, textures } = state;
   if (!current(state) || !rendererByLayer.get(state.backend) || state.failed) return;

package/src/native/terrainGridMesh.js

@@ -1,34 +1,47 @@
-import { rootByLayer } from '../weakmaps/rootByLayer.js';
-import { coreWhite } from '../globals/coreWhite.js';
-import { textureFor } from '../textures/nativeTextureFor.js';
-import { terrainElevation } from '../terrain/terrainElevation.js';
-import { localPosition } from '../projections/localPosition.js';
-import { putNativeMesh } from './putNativeMesh.js';
-
-export function terrainGridMesh(state, key, tile, request, opacity) {
-  const texture = textureFor(state, key, tile.el);
-  if (!texture) return;
-  const { x, y, z } = tile.coords, divisions = 32;
-  const northwest = localPosition(state, state.map.unproject(/* alloc */ [x * 256, y * 256], z));
-  const southeast = localPosition(state, state.map.unproject(/* alloc */ [(x + 1) * 256, (y + 1) * 256], z));
-  const vertices = /* alloc */ [], position = /* alloc */ [], uv = /* alloc */ [];
-  const base = rootByLayer.get(state.backend).position[1];
-  let row, col, u, v, elevation, a, b, c, d, index;
-  for (row = 0; row <= divisions; row++) for (col = 0; col <= divisions; col++) {
-    u = col / divisions; v = row / divisions;
-    elevation = terrainElevation(/* alloc */ { x: (x + u) * 256, y: (y + v) * 256 }, request.tiles);
-    if (!Number.isFinite(elevation)) throw /* alloc */ new Error(`Missing elevation sample in ${z}/${x}/${y}`);
-    vertices.push(/* alloc */ [northwest[0] + (southeast[0] - northwest[0]) * u, elevation - base,
-      northwest[2] + (southeast[2] - northwest[2]) * v, u, v]);
-  }
-  for (row = 0; row < divisions; row++) for (col = 0; col < divisions; col++) {
-    a = row * (divisions + 1) + col; b = a + 1; c = a + divisions + 1; d = c + 1;
-    for (index of /* alloc */ [a, c, b, b, c, d]) {
-      position.push(vertices[index][0], vertices[index][1], vertices[index][2]);
-      uv.push(vertices[index][3], vertices[index][4]);
-    }
-  }
-  const mesh = putNativeMesh(state, key, position, coreWhite, opacity, texture, uv, true);
-  mesh._terrainRequest = request;
-  return mesh;
-}
+import { rootByLayer } from '../weakmaps/rootByLayer.js';
+import { coreWhite } from '../globals/coreWhite.js';
+import { textureFor } from '../textures/nativeTextureFor.js';
+import { terrainElevation } from '../terrain/terrainElevation.js';
+import { localPosition } from '../projections/localPosition.js';
+import { putNativeMesh } from './putNativeMesh.js';
+
+/**
+ * Build a textured grid tile mesh draped over sampled terrain.
+ *
+ * @param {Object} state Native grid layer state.
+ * @param {string} key Tile key.
+ * @param {Object} tile Loaded tile.
+ * @param {Object} request Terrain request containing elevation tiles.
+ * @param {number} opacity Tile opacity.
+ *
+ * @returns {Object|undefined} Terrain mesh, if its texture is available.
+ *
+ * @throws {Error} If an elevation sample is missing.
+ */
+export function terrainGridMesh(state, key, tile, request, opacity) {
+  const texture = textureFor(state, key, tile.el);
+  if (!texture) return;
+  const { x, y, z } = tile.coords, divisions = 32;
+  const northwest = localPosition(state, state.map.unproject(/* alloc */ [x * 256, y * 256], z));
+  const southeast = localPosition(state, state.map.unproject(/* alloc */ [(x + 1) * 256, (y + 1) * 256], z));
+  const vertices = /* alloc */ [], position = /* alloc */ [], uv = /* alloc */ [];
+  const base = rootByLayer.get(state.backend).position[1];
+  let row, col, u, v, elevation, a, b, c, d, index;
+  for (row = 0; row <= divisions; row++) for (col = 0; col <= divisions; col++) {
+    u = col / divisions; v = row / divisions;
+    elevation = terrainElevation(/* alloc */ { x: (x + u) * 256, y: (y + v) * 256 }, request.tiles);
+    if (!Number.isFinite(elevation)) throw /* alloc */ new Error(`Missing elevation sample in ${z}/${x}/${y}`);
+    vertices.push(/* alloc */ [northwest[0] + (southeast[0] - northwest[0]) * u, elevation - base,
+      northwest[2] + (southeast[2] - northwest[2]) * v, u, v]);
+  }
+  for (row = 0; row < divisions; row++) for (col = 0; col < divisions; col++) {
+    a = row * (divisions + 1) + col; b = a + 1; c = a + divisions + 1; d = c + 1;
+    for (index of /* alloc */ [a, c, b, b, c, d]) {
+      position.push(vertices[index][0], vertices[index][1], vertices[index][2]);
+      uv.push(vertices[index][3], vertices[index][4]);
+    }
+  }
+  const mesh = putNativeMesh(state, key, position, coreWhite, opacity, texture, uv, true);
+  mesh._terrainRequest = request;
+  return mesh;
+}

package/src/native/updateNativeHover.js

@@ -1,7 +1,15 @@
-export function updateNativeHover(map, context, event, source) {
-  if (context.hovered === source) return;
-  if (context.hovered) context.fireDOMEvent.call(map, event, context.out, /* alloc */ [context.hovered]);
-  context.hovered = source;
-  if (source) context.fireDOMEvent.call(map, event, context.over, /* alloc */ [source]);
-  map.getContainer().style.cursor = source ? 'pointer' : '';
-}
+/**
+ * Dispatch hover transitions and update the cursor for the current native hit.
+ *
+ * @param {Object} map Leaflet map.
+ * @param {Object} context Native event state.
+ * @param {Event} event Original DOM event.
+ * @param {Object|null} source Hit source layer, if any.
+ */
+export function updateNativeHover(map, context, event, source) {
+  if (context.hovered === source) return;
+  if (context.hovered) context.fireDOMEvent.call(map, event, context.out, /* alloc */ [context.hovered]);
+  context.hovered = source;
+  if (source) context.fireDOMEvent.call(map, event, context.over, /* alloc */ [source]);
+  map.getContainer().style.cursor = source ? 'pointer' : '';
+}

package/src/native/updateNativeLayerView.js

@@ -1,9 +1,9 @@
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
-
-
 import { update } from '../scene/scheduleSceneUpdate.js';
 
+/**
+ * Mark the bound native layer's view dirty and schedule a render if attached.
+ */
 export function updateNativeLayerView() {
   this.viewDirty = true;
   if (sharedByLayer.get(this.backend)) update(this.backend);

package/src/native/updateNativeStrokeRadius.js

@@ -1,9 +1,14 @@
-export function updateNativeStrokeRadius(mesh) {
-  const attributes = mesh.geometry.attributes, positions = attributes.position.data, anchors = attributes.normal.data;
-  let i, radius = 0;
-  for (i = 0; i < positions.length; i += 3) {
-    radius = Math.max(radius, Math.hypot(positions[i] - anchors[i],
-      positions[i + 1] - anchors[i + 1], positions[i + 2] - anchors[i + 2]));
-  }
-  mesh.geometry.nativeStrokeRadius = radius;
-}
+/**
+ * Store the maximum distance between stroke vertices and their anchors.
+ *
+ * @param {Object} mesh Native stroke mesh.
+ */
+export function updateNativeStrokeRadius(mesh) {
+  const attributes = mesh.geometry.attributes, positions = attributes.position.data, anchors = attributes.normal.data;
+  let i, radius = 0;
+  for (i = 0; i < positions.length; i += 3) {
+    radius = Math.max(radius, Math.hypot(positions[i] - anchors[i],
+      positions[i + 1] - anchors[i + 1], positions[i + 2] - anchors[i + 2]));
+  }
+  mesh.geometry.nativeStrokeRadius = radius;
+}

package/src/picking/README.md

@@ -0,0 +1,29 @@
+# Picking
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Converts pointer events into scene raycasts, feature hits, hover highlighting and
+tooltips. Model hits and batched source features are resolved differently.
+
+## Pointer to feature
+
+```mermaid
+flowchart LR
+  Pointer["Pointer move"] --> Gesture{"Gesture active?"}
+  Gesture -->|yes| Clear["Clear hover"]
+  Gesture -->|no| Ray["Raycast attached scene"]
+  Ray --> Model["Model: walk hit-node parents"]
+  Ray --> Batch["Source: search face ranges"]
+  Model --> Hover["Highlight + tooltip + featurehover"]
+  Batch --> Hover
+```
+
+Face ranges come from [geometry](../geometry/README.md); keep them aligned
+with triangle order. A missing hit may also mean the root or camera is not
+attached.
+
+- [raycast.js](./raycast.js): intersect a pointer ray with scene meshes.
+- [findFeature.js](./findFeature.js): resolve an intersection to a feature.
+- [onPointerMove.js](./onPointerMove.js): update pointer interaction.
+
+Related: [collision](../collision/README.md), [native](../native/README.md), [scene](../scene/README.md).

package/src/picking/collectVisibleMesh.js

@@ -1,3 +1,11 @@
+/**
+ * Collect visible geometry for raycasting and skip invisible subtrees.
+ *
+ * @param {Object} mesh Scene node being visited.
+ * @param {Object[]} meshes Output mesh list.
+ *
+ * @returns {boolean|undefined} True when traversal should skip the node's descendants.
+ */
 export function collectVisibleMesh(mesh, meshes) {
   if (!mesh.visible) return true;
   if (mesh.geometry && mesh._appearance !== 0) meshes.push(mesh);

package/src/picking/findFeature.js

@@ -1,17 +1,17 @@
 import { cameraByLayer } from '../weakmaps/cameraByLayer.js';
 import { modelByLayer } from '../weakmaps/modelByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
-
-
 import { raycast } from './raycast.js';
 
 /**
  * Translate a geometry hit into a configured model or batched source feature.
  * Sorted half-open face ranges permit binary search without a feature per triangle.
+ *
+ * @param {L.Layer} layer Layer containing the features.
+ * @param {MouseEvent} event Pointer location used for raycasting.
+ *
  * @returns {PickedFeature|null}
  */
-
 export function findFeature(layer, event) {
   const model = modelByLayer.get(layer)
   if (!rootByLayer.get(layer) || !cameraByLayer.get(layer)) {

package/src/picking/hit.js

@@ -3,18 +3,25 @@ import { kindByLayer } from '../weakmaps/kindByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
-
-
-
 import { traverse } from '../scene/traverse.js';
 import { updateWorldMatrix } from '../transforms/updateWorldMatrix.js';
 import { hitMesh } from './hitMesh.js';
 import { trafficCollision } from '../collision/trafficCollision.js';
 
-// Horizontal normal of the nearest wall faced within `reach` metres of the feet at world (x, y, z), walking along
-// the unit (dx, dz); knee and chest rays, so arches and tree crowns above the head let the walker through.
-
+/**
+ * Find the nearest wall faced by knee and chest rays along a horizontal walking direction.
+ *
+ * @param {L.Layer} layer Walking layer whose shared scene is tested.
+ * @param {number} x World-space feet x coordinate.
+ * @param {number} y World-space feet height.
+ * @param {number} z World-space feet z coordinate.
+ * @param {number} dx Horizontal unit direction along x.
+ * @param {number} dz Horizontal unit direction along z.
+ * @param {number} reach Maximum ray distance in metres.
+ * @param {Object} data Reusable collision scratch and nearest-hit state.
+ *
+ * @returns {number[]|null} Nearest horizontal wall normal, or null when clear.
+ */
 export function hit(layer, x, y, z, dx, dz, reach, data) {
   updateWorldMatrix(sceneByLayer.get(layer));
   data.x = x, data.y = y, data.z = z, data.dx = dx, data.dz = dz, data.reach = reach;

package/src/picking/hitColliderCell.js

@@ -1,19 +1,29 @@
-import { horizontalRay } from '../collision/horizontalRay.js';
-
-export function hitColliderCell(cell, c, data, ox, oy, oz) {
-  const { dx, dz, seen } = data;
-  let t, height, d;
-  for (t of cell) {
-    if (seen.has(t) || dx * c.nrm[t * 2] + dz * c.nrm[t * 2 + 1] >= 0) continue;
-    seen.add(t);
-    for (height = 0.4; height < 2; height += 1.1) {
-      d = horizontalRay(c.tri, t, ox, oy + height, oz, dx, dz);
-      if (d >= 0 && d < data.best) {
-        data.best = d;
-        data.found = true;
-        data.normal[0] = c.nrm[t * 2];
-        data.normal[1] = c.nrm[t * 2 + 1];
-      }
-    }
-  }
-}
+import { horizontalRay } from '../collision/horizontalRay.js';
+
+/**
+ * Test unseen, front-facing triangles in a collider cell at knee and chest heights.
+ *
+ * @param {number[]} cell Triangle indices in the cell.
+ * @param {Object} c Cached collider geometry and normals.
+ * @param {Object} data Collision scratch and nearest-hit state.
+ * @param {number} ox Collider-local ray origin x coordinate.
+ * @param {number} oy Collider-local ray origin y coordinate.
+ * @param {number} oz Collider-local ray origin z coordinate.
+ */
+export function hitColliderCell(cell, c, data, ox, oy, oz) {
+  const { dx, dz, seen } = data;
+  let t, height, d;
+  for (t of cell) {
+    if (seen.has(t) || dx * c.nrm[t * 2] + dz * c.nrm[t * 2 + 1] >= 0) continue;
+    seen.add(t);
+    for (height = 0.4; height < 2; height += 1.1) {
+      d = horizontalRay(c.tri, t, ox, oy + height, oz, dx, dz);
+      if (d >= 0 && d < data.best) {
+        data.best = d;
+        data.found = true;
+        data.normal[0] = c.nrm[t * 2];
+        data.normal[1] = c.nrm[t * 2 + 1];
+      }
+    }
+  }
+}

package/src/picking/hitMesh.js

@@ -1,10 +1,16 @@
 import { CELL } from '../globals/CELL.js';
-
 import { computeBounds } from '../geometry/computeBounds.js';
 import { collider } from '../collision/collider.js';
-
 import { hitColliderCell } from './hitColliderCell.js';
 
+/**
+ * Test a visible mesh's nearby collider cells against the walking ray.
+ *
+ * @param {Object} mesh Scene node being visited.
+ * @param {Object} data Collision scratch and nearest-hit state.
+ *
+ * @returns {boolean|undefined} True when traversal should skip the node's descendants.
+ */
 export function hitMesh(mesh, data) {
   if (!mesh.visible) return true;
   if (!mesh.geometry?.attributes?.position?.data || mesh.program?.depthTest === false) return;

package/src/picking/onClick.js

@@ -1,13 +1,14 @@
 import { hoveredFeatureByLayer } from '../weakmaps/hoveredFeatureByLayer.js';
-
-
-
 import { findFeature } from './findFeature.js';
 import { setHighlight } from './setHighlight.js';
 import { showFeature } from './showFeature.js';
 
-/** Emit click without moving the map or pinning the tooltip. */
-
+/**
+ * Emit click without moving the map or pinning the tooltip.
+ *
+ * @param {L.Layer} layer Layer receiving the click.
+ * @param {MouseEvent} event Pointer event.
+ */
 export function onClick(layer, event) {
   const feature = findFeature(layer, event);
   hoveredFeatureByLayer.set(layer, feature);

package/src/picking/onPointerLeave.js

@@ -1,12 +1,12 @@
 import { hoveredFeatureByLayer } from '../weakmaps/hoveredFeatureByLayer.js';
-
-
-
 import { setHighlight } from './setHighlight.js';
 import { showFeature } from './showFeature.js';
 
-/** Clear hover, highlight and tooltip without retaining a selected feature. */
-
+/**
+ * Clear hover, highlight and tooltip without retaining a selected feature.
+ *
+ * @param {L.Layer} layer Layer whose hover state is cleared.
+ */
 export function onPointerLeave(layer) {
   hoveredFeatureByLayer.set(layer, null);
   setHighlight(layer, null);

package/src/picking/onPointerMove.js

@@ -1,14 +1,15 @@
 import { hoveredFeatureByLayer } from '../weakmaps/hoveredFeatureByLayer.js';
-
-
-
 import { findFeature } from './findFeature.js';
 import { setHighlight } from './setHighlight.js';
 import { showFeature } from './showFeature.js';
 import { onPointerLeave } from './onPointerLeave.js';
 
-/** Gestures clear hover once without raycasting; normal misses report feature:null. */
-
+/**
+ * Clear hover during gestures; otherwise raycast and report the current feature or a miss.
+ *
+ * @param {L.Layer} layer Layer receiving the pointer movement.
+ * @param {PointerEvent} event Pointer movement event.
+ */
 export function onPointerMove(layer, event) {
   if (event.buttons || layer._map.dragging?.moving() || layer._map._animatingZoom) {
     if (hoveredFeatureByLayer.get(layer)) onPointerLeave(layer);

package/src/picking/pointerClick.js

@@ -1,5 +1,10 @@
 import * as onClick from './onClick.js';
 
+/**
+ * Forward a pointer click to the layer's feature handler.
+ *
+ * @param {MouseEvent} event Click event.
+ */
 export function pointerClick(event) {
   onClick.onClick(this, event);
 }

package/src/picking/pointerLeave.js

@@ -1,5 +1,6 @@
 import * as onPointerLeave from './onPointerLeave.js';
 
+/** Clear this layer's feature hover state when the pointer leaves. */
 export function pointerLeave() {
   onPointerLeave.onPointerLeave(this);
 }

package/src/picking/pointerMove.js

@@ -1,5 +1,10 @@
 import * as onPointerMove from './onPointerMove.js';
 
+/**
+ * Forward pointer movement to the layer's feature handler.
+ *
+ * @param {PointerEvent} event Pointer movement event.
+ */
 export function pointerMove(event) {
   onPointerMove.onPointerMove(this, event);
 }

package/src/picking/raycast.js

@@ -3,10 +3,7 @@ import { raycasterByLayer } from '../weakmaps/raycasterByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
-
 import { trafficByLayer } from '../weakmaps/trafficByLayer.js';
-
-
 import { intersectMeshes } from '../collision/intersectMeshes.js';
 import { traverse } from '../scene/traverse.js';
 import { updateCamera } from '../camera/updateSceneCamera.js';
@@ -19,12 +16,13 @@ import { validateCameraInverse } from './validateCameraInverse.js';
 /**
  * Finds the objects under a mouse or pointer event, nearest first.
  *
+ * @param {L.Layer} layer Layer providing the scene and camera.
  * @param {MouseEvent} event
  * @param {Object[]} [objects] Defaults to this layer's root children, not all map layers.
  * @param {boolean} [recursive] Also test the descendants of `objects`.
+ *
  * @returns {Object[]} Nearest hit per mesh: object, shared-world point/distance and triangle faceIndex.
  */
-
 export function raycast(layer, event, objects = rootByLayer.get(layer).children, recursive = true) {
   if (!rendererByLayer.get(layer)) {
     return /* alloc */ [];

package/src/picking/setHighlight.js

@@ -1,11 +1,12 @@
 import { highlightedFeatureByLayer } from '../weakmaps/highlightedFeatureByLayer.js';
-
-
-
 import { update } from '../scene/scheduleSceneUpdate.js';
 
-/** Highlight a source vertex range in the shader; vertex colors stay untouched. */
-
+/**
+ * Highlight a source vertex range in the shader; vertex colors stay untouched.
+ *
+ * @param {L.Layer} layer Layer whose highlight is updated.
+ * @param {Object|null} feature Picked feature to highlight, or null to clear it.
+ */
 export function setHighlight(layer, feature) {
   if (feature?.model) feature = null;
   if (highlightedFeatureByLayer.get(layer)?.mesh === feature?.mesh &&