leaflet-city-mapper 0.0.8 → 0.1.0

package/src/collision/insideMesh.js

@@ -1,10 +1,21 @@
 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;
@@ -22,6 +33,9 @@ export function insideMesh(mesh, x, y, z, seen, intersections) {
   );
   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);
@@ -29,5 +43,5 @@ export function insideMesh(mesh, x, y, z, seen, intersections) {
   hits.length = 0;
   seen.clear();
   collectIntersections(shape, x, y, z, seen, hits, end, iz);
-  return countCrossings(hits) % 2 === 1;
+  return countCrossings(hits, shape.ranges) > 0;
 }

package/src/collision/insideWalker.js

@@ -3,12 +3,18 @@ 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);

package/src/collision/intersectMeshes.js

@@ -5,7 +5,15 @@ 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. */
+/**
+ * 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];

package/src/collision/localRay.js

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

package/src/collision/mergeHits.js

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

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);
+}

package/src/collision/rayBounds.js

@@ -1,5 +1,14 @@
 import { computeBounds } from '../geometry/computeBounds.js';
 
+/**
+ * Test a local-space ray against the mesh bounding box, calculating bounds when needed.
+ *
+ * @param {Object} mesh Mesh whose geometry bounds are tested.
+ * @param {number[]} origin Local ray origin.
+ * @param {number[]} direction Local ray direction.
+ *
+ * @returns {boolean} Whether the ray intersects the bounding box.
+ */
 export function rayBounds(mesh, origin, direction) {
   if (!mesh.geometry.bounds) computeBounds(mesh.geometry);
   let near = 0, far = Infinity, i, a, b;

package/src/collision/readTriangle.js

@@ -1,5 +1,14 @@
 import { vertexCount } from './vertexCount.js';
 
+/**
+ * Read an indexed or non-indexed triangle into caller-owned vectors, applying any instance offset.
+ *
+ * @param {Object} mesh Mesh containing geometry attributes.
+ * @param {number} i First index or vertex offset, including instance offset.
+ * @param {number[]} a Output first vertex.
+ * @param {number[]} b Output second vertex.
+ * @param {number[]} c Output third vertex.
+ */
 export function readTriangle(mesh, i, a, b, c) {
   const { position, index, instanceOffset } = mesh.geometry.attributes;
   const size = position.size ?? 3;

package/src/collision/slabDistance.js

@@ -0,0 +1,14 @@
+/**
+ * Distance along one axis to a slab boundary, picking the boundary the ray moves toward.
+ *
+ * @param {number} origin Ray origin on the axis.
+ * @param {number} velocity Ray direction on the axis.
+ * @param {number} low Boundary hit when moving in the positive direction.
+ * @param {number} high Boundary hit when moving in the negative direction.
+ * @param {number} parallel Value returned when the ray is parallel to the slab.
+ *
+ * @returns {number} Ray parameter at the selected boundary.
+ */
+export function slabDistance(origin, velocity, low, high, parallel) {
+  return velocity ? ((velocity > 0 ? low : high) - origin) / velocity : parallel;
+}

package/src/collision/slabMiss.js

@@ -0,0 +1,14 @@
+/**
+ * Whether a ray parallel to a slab starts outside it.
+ *
+ * @param {number} origin Ray origin on the axis.
+ * @param {number} velocity Ray direction on the axis.
+ * @param {number} min Slab minimum.
+ * @param {number} max Slab maximum.
+ * @param {number} margin Padding added around the slab.
+ *
+ * @returns {boolean} True when the ray can never enter the slab.
+ */
+export function slabMiss(origin, velocity, min, max, margin) {
+  return !velocity && (origin <= min - margin || origin >= max + margin);
+}

package/src/collision/sortCrossings.js

@@ -0,0 +1,17 @@
+/**
+ * Insertion-sort hit pairs in place by feature key, then distance.
+ *
+ * @param {number[]} hits Flat feature key and crossing distance pairs.
+ */
+export function sortCrossings(hits) {
+  let ix, j, feature, distance;
+  for (ix = 2; ix < hits.length; ix += 2) {
+    feature = hits[ix], distance = hits[ix + 1];
+    j = ix - 2;
+    while (j >= 0 && (hits[j] > feature || (hits[j] === feature && hits[j + 1] > distance))) {
+      hits[j + 2] = hits[j], hits[j + 3] = hits[j + 1];
+      j -= 2;
+    }
+    hits[j + 2] = feature, hits[j + 3] = distance;
+  }
+}

package/src/collision/sortHits.js

@@ -1,3 +1,12 @@
+import { mergeHits } from './mergeHits.js';
+
+/**
+ * Sort hits in place by ascending distance using a stable merge sort.
+ *
+ * @param {Object[]} hits Hits with distance properties.
+ *
+ * @returns {Object[]} The supplied array, sorted in place.
+ */
 export function sortHits(hits) {
   if (hits.length < 2) return hits;
   const buffer = /* alloc */ new Array(hits.length);
@@ -14,4 +23,3 @@ export function sortHits(hits) {
   if (source !== hits) for (i = 0; i < hits.length; i++) hits[i] = source[i];
   return hits;
 }
-import { mergeHits } from './mergeHits.js';

package/src/collision/trafficBounds.js

@@ -0,0 +1,24 @@
+/**
+ * Return the cached local-space bounds of a traffic vehicle template, computing them on first use.
+ *
+ * @param {Object} state Traffic layer state with a template position array.
+ *
+ * @returns {Object} Bounds with minX, maxX, minY, maxY, minZ and maxZ.
+ */
+export function trafficBounds(state) {
+  if (state.collisionBounds) return state.collisionBounds;
+  const bounds = state.collisionBounds = /* alloc */ {
+    minX: Infinity, maxX: -Infinity, minY: Infinity, maxY: -Infinity, minZ: Infinity, maxZ: -Infinity,
+  };
+  const position = state.template.position;
+  let i;
+  for (i = 0; i < position.length; i += 3) {
+    bounds.minX = Math.min(bounds.minX, position[i]);
+    bounds.maxX = Math.max(bounds.maxX, position[i]);
+    bounds.minY = Math.min(bounds.minY, position[i + 1]);
+    bounds.maxY = Math.max(bounds.maxY, position[i + 1]);
+    bounds.minZ = Math.min(bounds.minZ, position[i + 2]);
+    bounds.maxZ = Math.max(bounds.maxZ, position[i + 2]);
+  }
+  return bounds;
+}

package/src/collision/trafficCollision.js

@@ -1,55 +1,30 @@
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { trafficByLayer } from '../weakmaps/trafficByLayer.js';
+import { collideTrip } from './collideTrip.js';
+import { trafficBounds } from './trafficBounds.js';
 
-import { locateTraffic } from '../traffic/locateTraffic.js';
-import { setTrafficNormal } from './setTrafficNormal.js';
-
+/**
+ * Test a walker point or movement ray against oriented traffic bounds, updating the nearest hit in data.
+ *
+ * @param {L.Layer} layer Traffic layer.
+ * @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, updated when a collision is found.
+ *
+ * @returns {boolean} Whether a collision was found.
+ */
 export function trafficCollision(layer, x, y, z, dx, dz, reach, data) {
   const state = trafficByLayer.get(layer);
   if (!state?.mesh || !state.trips.length) return false;
-  let bounds = state.collisionBounds;
-  if (!bounds) {
-    bounds = state.collisionBounds = /* alloc */ { radius: 0, minY: Infinity, maxY: -Infinity };
-    let i, px, py, pz;
-    for (i = 0; i < state.template.position.length; i += 3) {
-      px = state.template.position[i];
-      py = state.template.position[i + 1];
-      pz = state.template.position[i + 2];
-      bounds.radius = Math.max(bounds.radius, Math.hypot(px, pz));
-      bounds.minY = Math.min(bounds.minY, py);
-      bounds.maxY = Math.max(bounds.maxY, py);
-    }
-  }
-  const root = rootByLayer.get(layer), position = state.position ||= /* alloc */ {};
-  const scale = Math.max(root.scale[0], root.scale[1], root.scale[2]);
-  const radius = bounds.radius * scale + 0.35;
-  let trip, projection, closest, rx, rz, perpendicular, entry, distance, bottom, top, px, pz;
-  for (trip of state.trips) {
-    ({ x: px, y: bottom, z: pz } = locateTraffic(state, trip, position));
-    bottom = root.position[1] + (bottom + bounds.minY) * root.scale[1];
-    top = root.position[1] + (position.y + bounds.maxY) * root.scale[1];
-    if (bottom > y + 1.7 * scale || top < y + 0.2 * scale) continue;
-    px = root.position[0] + px * root.scale[0];
-    pz = root.position[2] + pz * root.scale[2];
-    projection = (px - x) * dx + (pz - z) * dz;
-    closest = Math.max(0, Math.min(reach, projection));
-    rx = x + closest * dx - px;
-    rz = z + closest * dz - pz;
-    perpendicular = rx * rx + rz * rz;
-    if (perpendicular >= radius * radius) continue;
-    if (reach === 0) {
-      data.found = true;
-      distance = Math.hypot(x - px, z - pz);
-      data.normal[0] = distance ? (x - px) / distance : 0;
-      data.normal[1] = distance ? (z - pz) / distance : 0;
-      continue;
-    }
-    entry = Math.max(0, projection - Math.sqrt(radius * radius - perpendicular));
-    if (entry > reach || entry >= data.best) continue;
-    data.best = entry;
-    data.found = true;
-    distance = Math.hypot(x + entry * dx - px, z + entry * dz - pz);
-    setTrafficNormal(data, x + entry * dx - px, z + entry * dz - pz, distance, dx, dz);
-  }
-  return data.found;
-}
+  const root = rootByLayer.get(layer), bounds = trafficBounds(state);
+  let trip;
+  for (trip of state.trips) {
+    collideTrip(state, trip, root, bounds, x, y, z, dx, dz, reach, data);
+    if (!reach && data.found) break;
+  }
+  return data.found;
+}

package/src/collision/trafficRay.js

@@ -0,0 +1,21 @@
+/**
+ * Express a world-space walker ray in a traffic vehicle's local frame.
+ *
+ * @param {Object} root Traffic root with position and scale arrays.
+ * @param {Object} position Vehicle placement with dx and dz heading components.
+ * @param {number} x Walker world-space x coordinate.
+ * @param {number} z Walker world-space z coordinate.
+ * @param {number} dx Movement direction x.
+ * @param {number} dz Movement direction z.
+ * @param {number} px Vehicle x in root space.
+ * @param {number} pz Vehicle z in root space.
+ * @param {number[]} out Receives the local origin x, origin z, direction x and direction z.
+ */
+export function trafficRay(root, position, x, z, dx, dz, px, pz, out) {
+  const rx = (x - root.position[0]) / root.scale[0] - px;
+  const rz = (z - root.position[2]) / root.scale[2] - pz;
+  out[0] = -rx * position.dz + rz * position.dx;
+  out[1] = -rx * position.dx - rz * position.dz;
+  out[2] = -dx / root.scale[0] * position.dz + dz / root.scale[2] * position.dx;
+  out[3] = -dx / root.scale[0] * position.dx - dz / root.scale[2] * position.dz;
+}

package/src/collision/transformTriangle.js

@@ -1,3 +1,12 @@
+/**
+ * Write three indexed or sequential positions transformed by matrix m into v.
+ *
+ * @param {number[]} v Output packed triangle coordinates.
+ * @param {ArrayLike<number>} p Packed input positions.
+ * @param {Object|undefined} index Optional geometry index attribute.
+ * @param {number} i First vertex or index offset.
+ * @param {ArrayLike<number>} m Column-major transformation matrix.
+ */
 export function transformTriangle(v, p, index, i, m) {
   let k, j, x, y, z;
   for (k = 0; k < 3; k++) {

package/src/collision/transformVertices.js

@@ -0,0 +1,18 @@
+/**
+ * Write three local-space vertices transformed by matrix m into v.
+ *
+ * @param {number[]} v Output packed triangle coordinates.
+ * @param {number[]} a First vertex.
+ * @param {number[]} b Second vertex.
+ * @param {number[]} d Third vertex.
+ * @param {ArrayLike<number>} m Column-major transformation matrix.
+ */
+export function transformVertices(v, a, b, d, m) {
+  let k, p;
+  for (k = 0; k < 3; k++) {
+    p = k === 0 ? a : k === 1 ? b : d;
+    v[k * 3] = m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12];
+    v[k * 3 + 1] = m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13];
+    v[k * 3 + 2] = m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14];
+  }
+}

package/src/collision/triangleDistance.js

@@ -1,6 +1,19 @@
 import { hiddenLightHit } from './hiddenLightHit.js';
 
-/** Moller-Trumbore with the renderer's culling and light-halo rules. */
+/**
+ * Compute ray-triangle distance using the renderer's culling and light-halo rules.
+ *
+ * @param {Object} mesh Mesh containing material and geometry attributes.
+ * @param {number} i Triangle's first vertex or index offset.
+ * @param {number[]} a First vertex.
+ * @param {number[]} b Second vertex.
+ * @param {number[]} c Third vertex.
+ * @param {number[]} origin Local ray origin.
+ * @param {number[]} direction Local ray direction.
+ * @param {number} night Night-light intensity.
+ *
+ * @returns {number} Signed ray distance, or Infinity when the hit is rejected.
+ */
 export function triangleDistance(mesh, i, a, b, c, origin, direction, night) {
   const ex = b[0] - a[0], ey = b[1] - a[1], ez = b[2] - a[2];
   const fx = c[0] - a[0], fy = c[1] - a[1], fz = c[2] - a[2];

package/src/collision/vertexCount.js

@@ -1,3 +1,11 @@
+/**
+ * Return the number of indexed or sequential vertices represented by the geometry attributes.
+ *
+ * @param {Object} position Position attribute.
+ * @param {Object|undefined} index Optional index attribute.
+ *
+ * @returns {number} Number of indices or sequential vertices.
+ */
 export function vertexCount(position, index) {
   return index?.count ?? index?.data.length ?? position.count ?? position.data.length / (position.size ?? 3);
 }

package/src/collision/worldHit.js

@@ -1,3 +1,15 @@
+/**
+ * Convert a local ray hit to a world-space point and its distance from the original ray origin.
+ *
+ * @param {Object} ray Original world-space ray.
+ * @param {Object} mesh Intersected mesh.
+ * @param {number[]} origin Local ray origin.
+ * @param {number[]} direction Local ray direction.
+ * @param {number} closest Local ray distance to the hit.
+ * @param {number} faceIndex Index of the hit triangle.
+ *
+ * @returns {Object} Hit containing the mesh, face index, world point and distance.
+ */
 export function worldHit(ray, mesh, origin, direction, closest, faceIndex) {
   const x = direction[0] * closest + origin[0];
   const y = direction[1] * closest + origin[1];

package/src/colors/README.md

@@ -0,0 +1,25 @@
+# Colors
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Parses and converts colors and provides interpolation and formatting helpers.
+
+## Color-space boundary
+
+```mermaid
+flowchart LR
+  RGB["Numeric / CSS / RGB"] --> Parse["parseColor"]
+  HSL["Linear-space HSL"] --> Parse
+  Parse -->|"HSL conversion"| Output["sRGB components: 0..1"]
+  Parse -->|"sRGB inputs"| Output
+  Output --> Style["Extrusion / materials"]
+```
+
+CSS strings use the browser parser; CSS alpha is not used for extrusion.
+Do not convert the resulting sRGB values a second time.
+
+- [parseColor.js](./parseColor.js): interpret supported color inputs.
+- [mixColor.js](./mixColor.js): interpolate colors.
+- [toSRGB.js](./toSRGB.js) and [formatRGB.js](./formatRGB.js): convert and format output.
+
+Related: [materials](../materials/README.md), [sunlight](../sunlight/README.md).

package/src/colors/formatRGB.js

@@ -1,3 +1,10 @@
+/**
+ * Format rounded channel values as a CSS rgb() string.
+ *
+ * @param {number[]} values Color channel values.
+ *
+ * @returns {string} CSS rgb() string.
+ */
 export function rgb(values) {
   let rounded = '', i;
   for (i = 0; i < values.length; i++) {

package/src/colors/hslChannel.js

@@ -1,3 +1,13 @@
+/**
+ * Compute one linear RGB channel from an HSL hue, lightness and chroma factor.
+ *
+ * @param {number} n Channel offset in the HSL conversion.
+ * @param {number} h Hue as a fraction of a turn.
+ * @param {number} l Lightness.
+ * @param {number} a Saturation-scaled chroma factor.
+ *
+ * @returns {number} Linear RGB channel value.
+ */
 export function channel(n, h, l, a) {
   const k = (n + h * 12) % 12;
   return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));

package/src/colors/mixColor.js

@@ -1,3 +1,13 @@
+/**
+ * Interpolate corresponding color components into a reusable array.
+ *
+ * @param {number[]} a Starting components.
+ * @param {number[]} b Ending components.
+ * @param {number} t Interpolation factor.
+ * @param {number[]} [values] Output array to reuse.
+ *
+ * @returns {number[]} Interpolated components.
+ */
 export function mix(a, b, t, values) {
   values ||= /* alloc */ [];
   values.length = a.length;

package/src/colors/parseColor.js

@@ -4,10 +4,13 @@ import { channel } from "./hslChannel.js";
 /**
  * HSL inputs are linear-space to preserve the original building styling.
  * Numeric/CSS/RGB inputs are already sRGB; CSS alpha is not used for extrusion.
+ *
  * @param {number|string|Object} value 0xRRGGBB, CSS color, {r,g,b}, or {h,s,l} in 0..1.
+ *
  * @returns {Object} sRGB {r,g,b} components in 0..1.
+ *
+ * @throws {Error} If the value is not a supported color.
  */
-
 export function parseColor(value) {
   if (value && typeof value === 'object' && 'h' in value) {
     const a = value.s * Math.min(value.l, 1 - value.l);

package/src/colors/toSRGB.js

@@ -1,3 +1,10 @@
+/**
+ * Convert a linear color channel to sRGB.
+ *
+ * @param {number} value Linear channel value.
+ *
+ * @returns {number} sRGB channel value.
+ */
 export function toSRGB(value) {
   return value <= 0.0031308 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - 0.055;
 }

package/src/controls/README.md

@@ -0,0 +1,26 @@
+# Controls
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Implements camera interaction handlers for dragging, touch, compass and container
+resizing, including listener setup and cleanup.
+
+## Input to camera state
+
+```mermaid
+flowchart LR
+  Input["Drag / touch / compass / resize"] --> Handler["Leaflet handler"]
+  Handler --> Camera["Camera state + events"]
+  Touch["Camera touch enabled"] --> Disable["Save and disable native touch zoom"]
+  Disable --> End["Camera touch disabled"]
+  End --> Restore["Restore previous touch zoom state"]
+```
+
+[camera](../camera/README.md) validates and owns the angles. Pair add/remove
+hooks for listeners and preserve native touch-zoom coordination.
+
+- [cameraControls.js](./cameraControls.js): register camera handlers.
+- [dragCamera.js](./dragCamera.js): set up camera dragging.
+- [changeCameraTouch.js](./changeCameraTouch.js): manage touch interaction state.
+
+Related: [camera](../camera/README.md), [animations](../animations/README.md).

package/src/controls/acceptPitchDrag.js

@@ -1,3 +1,10 @@
+/**
+ * Accept a right-button or Ctrl-left drag outside controls, markers and popups.
+ *
+ * @param {PointerEvent} event Pointer event.
+ *
+ * @returns {boolean} Whether the drag can start.
+ */
 export function acceptPitchDrag(event) {
   return !event.target.closest('.leaflet-control,.leaflet-marker-icon,.leaflet-popup') &&
     (event.button === 2 || event.button === 0 && event.ctrlKey);

package/src/controls/acceptRotateDrag.js

@@ -1,3 +1,10 @@
+/**
+ * Accept a primary-button drag on the rotate control.
+ *
+ * @param {PointerEvent} event Pointer event.
+ *
+ * @returns {boolean} Whether the drag can start.
+ */
 export function acceptRotateDrag(event) {
   return event.button === 0;
 }

package/src/controls/addCameraHandler.js

@@ -1,6 +1,13 @@
 
 import { cameraHandlersByMap } from '../weakmaps/cameraHandlersByMap.js';
 
+/**
+ * Register a camera handler and enable it when its map option is set.
+ *
+ * @param {L.Map} map Map owning the handler.
+ * @param {string} name Handler and option name.
+ * @param {Function} Type Handler constructor.
+ */
 export function addCameraHandler(map, name, Type) {
   let handlers = cameraHandlersByMap.get(map);
   if (!handlers) cameraHandlersByMap.set(map, handlers = /* alloc */ new Map());

package/src/controls/adjustCameraDrag.js

@@ -1,11 +1,9 @@
-import { cameraDraggableByMap } from '../weakmaps/cameraDraggableByMap.js';
-
-
-import { mapGetPitch } from '../camera/mapGetPitch.js';
-import { mapGetBearing } from '../camera/mapGetBearing.js';
-
-import { project } from '../projections/projectCameraPoint.js';
-
+import { cameraDraggableByMap } from '../weakmaps/cameraDraggableByMap.js';
+import { mapGetPitch } from '../camera/mapGetPitch.js';
+import { mapGetBearing } from '../camera/mapGetBearing.js';
+import { project } from '../projections/projectCameraPoint.js';
+
+/** Convert this map's draggable displacement into ground-space camera movement. */
 export function adjustCameraDrag() {
   const map = this;
   const draggable = cameraDraggableByMap.get(map);

package/src/controls/cameraControls.js

@@ -3,7 +3,6 @@ import { cameraHandlersByMap } from '../weakmaps/cameraHandlersByMap.js';
 import { rotateControlByMap } from '../weakmaps/rotateControlByMap.js';
 import { touchPitchByMap } from '../weakmaps/touchPitchByMap.js';
 import { touchRotateByMap } from '../weakmaps/touchRotateByMap.js';
-
 import { L } from '../globals/L.js';
 import { Compass } from '../globals/Compass.js';
 import { ContainerResize } from '../globals/ContainerResize.js';
@@ -15,9 +14,6 @@ import { cameraTouchStates } from '../globals/cameraTouchStates.js';
 import { cameraListenerOptions } from '../globals/cameraListenerOptions.js';
 import { cameraEmptyOptions } from '../globals/cameraEmptyOptions.js';
 import { notifyCameraTouchChange } from './notifyCameraTouchChange.js';
-
-
-
 import { rotateOnAdd } from './rotateOnAdd.js';
 import { rotateOnRemove } from './rotateOnRemove.js';
 import { rotateControl } from './rotateControl.js';
@@ -75,6 +71,11 @@ L.Control.Rotate = RotateControl;
 
 if (L.control) L.control.rotate = rotateControl;
 
+/**
+ * Install camera handlers, touch listeners and the optional rotate control.
+ *
+ * @param {L.Map} map Map receiving the controls.
+ */
 export function cameraControls(map) {
   addCameraHandler(map, 'trackContainerMutation', ContainerResize.value);
   if (!map.options.rotate) return;