leaflet-city-mapper 0.0.9 → 0.1.0

package/src/core/fireRasterLoad.js

@@ -1,6 +1,6 @@
 import { pendingRasterLoads } from '../globals/pendingRasterLoads.js';
 
-
+/** Fire the load event for the next queued raster image layer, if present. */
 export function fireRasterLoad() {
   pendingRasterLoads.shift()?.fire('load');
 }

package/src/core/gridlayerGetEvents.js

@@ -1,8 +1,11 @@
 import { L } from '../globals/L.js';
 import { gridEvents } from '../globals/gridEvents.js';
 
-
-
+/**
+ * Extend this grid layer's map events to update tiles on rotation and pitch.
+ *
+ * @returns {Object} Map event handlers.
+ */
 export function gridlayerGetEvents() {
   const events = gridEvents.value.call(this);
   events.rotate = events.pitch = L.Util.throttle(this._onMoveEnd, this.options.updateInterval, this);

package/src/core/gridlayerGetTiledPixelBounds.js

@@ -1,6 +1,5 @@
 import { L } from '../globals/L.js';
 import { tiledBounds } from '../globals/tiledBounds.js';
-
 import { mapGetBearing } from '../camera/mapGetBearing.js';
 import { mapGetPitch } from '../camera/mapGetPitch.js';
 import { streamTerrainByMap } from '../weakmaps/streamTerrainByMap.js';
@@ -8,6 +7,13 @@ import { renderers } from '../weakmaps/renderers.js';
 import { sceneOriginByLayer } from '../weakmaps/sceneOriginByLayer.js';
 import { extendTerrainPixelBounds } from './extendTerrainPixelBounds.js';
 
+/**
+ * Compute this grid layer's tile bounds for the camera and visible terrain.
+ *
+ * @param {L.LatLng} center Proposed map center for Leaflet's default calculation.
+ *
+ * @returns {L.Bounds} Projected tile pixel bounds.
+ */
 export function gridlayerGetTiledPixelBounds(center) {
   const map = this._map, stream = streamTerrainByMap.get(map);
   if (!stream && !mapGetBearing(map) && !mapGetPitch(map)) return tiledBounds.value.call(this, center);

package/src/core/initializeGridContainer.js

@@ -1,6 +1,6 @@
 import { gridInitializers } from '../weakmaps/gridInitializers.js';
 
-
+/** Run this grid layer's original container initializer and remove its DOM container. */
 export function initializeGridContainer() {
   gridInitializers.get(this).call(this);
   this._container.remove();

package/src/core/initializeNativeLayer.js

@@ -1,15 +1,11 @@
 import { kindByLayer } from '../weakmaps/kindByLayer.js';
-
 import { L } from '../globals/L.js';
 import { closestMethods } from '../weakmaps/closestMethods.js';
 import { boundsMethods } from '../weakmaps/boundsMethods.js';
 import { gridInitializers } from '../weakmaps/gridInitializers.js';
-
-
 import { noOperation } from '../utils/noOperation.js';
 import { emptyEvents } from '../scene/emptyEvents.js';
 import { refreshNativeLayerContract } from '../native/refreshNativeLayerContract.js';
-
 import { closestCameraLayerPoint } from './closestCameraLayerPoint.js';
 import { cameraCircleBounds } from './cameraCircleBounds.js';
 import { initializeGridContainer } from './initializeGridContainer.js';
@@ -17,6 +13,7 @@ import { updateGridOpacity } from './updateGridOpacity.js';
 import { addRasterImage } from '../textures/attachRasterImage.js';
 import { redrawPath } from './redrawPath.js';
 
+/** Install camera and GPU integration hooks appropriate to this native Leaflet layer. */
 export function initializeNativeLayer() {
   if (this instanceof L.Polyline || this instanceof L.CircleMarker) {
     this.beforeAdd = this._updateBounds = noOperation;

package/src/core/layerAddInitHook.js

@@ -1,6 +1,11 @@
 import { L } from '../globals/L.js';
 import { leafletLayer } from '../globals/leafletLayer.js';
 
+/**
+ * Forward initialization-hook registration to the appropriate Leaflet class.
+ *
+ * @returns {Function} This layer class.
+ */
 export function layerAddInitHook() {
   leafletLayer.addInitHook.apply(this === L.Layer ? leafletLayer : this, arguments);
   return this;

package/src/core/layerCallInitHooks.js

@@ -1,10 +1,9 @@
 import { sceneLayers } from '../weakmaps/sceneLayers.js';
-
 import { L } from '../globals/L.js';
 import { layerProto } from '../globals/layerProto.js';
-
 import { initializeNativeLayer } from './initializeNativeLayer.js';
 
+/** Run Leaflet initialization hooks and initialize this native layer when needed. */
 export function layerCallInitHooks() {
   const initialized = this._initHooksCalled;
   if (!L.version.startsWith('2.')) layerProto.value.callInitHooks.call(this);

package/src/core/layerMergeOptions.js

@@ -1,6 +1,13 @@
 import { L } from '../globals/L.js';
 import { leafletLayer } from '../globals/leafletLayer.js';
 
+/**
+ * Merge options into the appropriate Leaflet layer class.
+ *
+ * @param {Object} options Default options to merge.
+ *
+ * @returns {Function} This layer class.
+ */
 export function layerMergeOptions(options) {
   leafletLayer.mergeOptions.call(this === L.Layer ? leafletLayer : this, options);
   return this;

package/src/core/markerGetEvents.js

@@ -1,7 +1,10 @@
 import { markerMethods } from '../globals/markerMethods.js';
 
-
-
+/**
+ * Extend this marker's map events with camera movement updates.
+ *
+ * @returns {Object} Map event handlers.
+ */
 export function markerGetEvents() {
   const events = markerMethods.value.getEvents.call(this);
   events.rotate = events.pitch = events.move = this.update;

package/src/core/markerInitInteraction.js

@@ -1,8 +1,11 @@
-import { markerMethods } from '../globals/markerMethods.js';
-
-
-import { cameraMarkerDrag } from './cameraMarkerDrag.js';
-
+import { markerMethods } from '../globals/markerMethods.js';
+import { cameraMarkerDrag } from './cameraMarkerDrag.js';
+
+/**
+ * Initialize this marker's Leaflet interaction and camera-aware dragging.
+ *
+ * @returns {*} Original interaction initializer result.
+ */
 export function markerInitInteraction() {
   const result = markerMethods.value._initInteraction.call(this);
   cameraMarkerDrag.call(this);

package/src/core/markerSetIcon.js

@@ -1,9 +1,14 @@
-import { L } from '../globals/L.js';
-import { markerMethods } from '../globals/markerMethods.js';
-
-
-import { initNativeGPU } from '../native/initNativeGPU.js';
-
+import { L } from '../globals/L.js';
+import { markerMethods } from '../globals/markerMethods.js';
+import { initNativeGPU } from '../native/initNativeGPU.js';
+
+/**
+ * Set this marker's icon and initialize GPU rendering for mapped non-DivIcon images.
+ *
+ * @param {L.Icon} icon New marker icon.
+ *
+ * @returns {*} Original Leaflet setter result.
+ */
 export function markerSetIcon(icon) {
   if (!(icon instanceof L.DivIcon)) icon.options.crossOrigin ||= true;
   const result = markerMethods.value.setIcon.call(this, icon);

package/src/core/markerSetPos.js

@@ -1,9 +1,12 @@
 import { markerMethods } from '../globals/markerMethods.js';
-
 import { markerCameraIconPoint } from '../projections/markerCameraIconPoint.js';
-
 import { displayPoint } from '../projections/displayContainerPoint.js';
 
+/**
+ * Position and orient this marker's icon and shadow under the current camera.
+ *
+ * @param {L.Point} point Marker layer point.
+ */
 export function markerSetPos(point) {
   markerMethods.value._setPos.call(this, displayPoint(this._map, point, this.getLatLng()));
   let i, element, key, direction, options, anchor;

package/src/core/markerSetRotation.js

@@ -1,5 +1,15 @@
 import { refreshNativeLayerContract } from '../native/refreshNativeLayerContract.js';
 
+/**
+ * Set a marker's rotation and refresh its display and native GPU state.
+ *
+ * @param {L.Marker} marker Marker to update.
+ * @param {number} rotation Rotation value.
+ *
+ * @returns {L.Marker} The updated marker.
+ *
+ * @throws {TypeError} If the rotation is not finite.
+ */
 export function markerSetRotation(marker, rotation) {
   if (!Number.isFinite(rotation)) throw /* alloc */ new TypeError('Marker rotation must be finite');
   marker.options.rotation = rotation;

package/src/core/markerUpdateZIndex.js

@@ -1,13 +1,15 @@
 import { cameraZIndexOffsetByLayer } from '../weakmaps/cameraZIndexOffsetByLayer.js';
-
 import { markerMethods } from '../globals/markerMethods.js';
+import { refreshNativeLayerContract } from '../native/refreshNativeLayerContract.js';
 
-
-
+/**
+ * Update this marker's Leaflet z-index and refresh native state when its offset changes.
+ *
+ * @param {number} offset Z-index offset.
+ */
 export function markerUpdateZIndex(offset) {
   markerMethods.value._updateZIndex.call(this, offset);
   const changed = cameraZIndexOffsetByLayer.get(this) !== offset;
   cameraZIndexOffsetByLayer.set(this, offset);
   if (changed) refreshNativeLayerContract(this);
 }
-import { refreshNativeLayerContract } from '../native/refreshNativeLayerContract.js';

package/src/core/popupAdjustPan.js

@@ -1,10 +1,13 @@
 import { popupPan } from '../globals/popupPan.js';
-
 import { mapGetPitch } from '../camera/mapGetPitch.js';
 import { mapGetBearing } from '../camera/mapGetBearing.js';
-
 import { pointOf } from '../projections/toPoint.js';
 
+/**
+ * Auto-pan this popup into the padded viewport under the current camera.
+ *
+ * @returns {*} Original Leaflet handler result when the camera is untransformed.
+ */
 export function popupAdjustPan() {
   const map = this._map;
   if (!mapGetPitch(map) && !mapGetBearing(map)) return popupPan.value.call(this);

package/src/core/popupGetEvents.js

@@ -1,6 +1,10 @@
 import { popupEvents } from '../globals/popupEvents.js';
 
-
+/**
+ * Extend this popup's map events with camera and terrain position updates.
+ *
+ * @returns {Object} Map event handlers.
+ */
 export function popupGetEvents() {
   const events = popupEvents.value.call(this);
   events.rotate = events.pitch = events.move = events.terrainchange = this._updatePosition;

package/src/core/popupUpdatePosition.js

@@ -1,9 +1,8 @@
 import { L } from '../globals/L.js';
 import { popupPosition } from '../globals/popupPosition.js';
-
-
 import { displayPoint } from '../projections/displayContainerPoint.js';
 
+/** Update this popup's position and apply the camera display offset. */
 export function popupUpdatePosition() {
   popupPosition.value.call(this);
   if (!this._map) return;

package/src/core/projectNativePath.js

@@ -1,6 +1,13 @@
 import { L } from '../globals/L.js';
 import { pathProjectionByMap } from '../weakmaps/pathProjectionByMap.js';
 
+/**
+ * Project a native path using a temporary renderer view when required by Leaflet 2.
+ *
+ * @param {L.Path} source Path to project.
+ *
+ * @returns {*} Original projection result on Leaflet 1.
+ */
 export function projectNativePath(source) {
   if (!L.version.startsWith('2.')) return source._project();
   const map = source._map, renderer = source._renderer;

package/src/core/redrawPath.js

@@ -1,5 +1,10 @@
 import { refreshNativeLayerContract } from '../native/refreshNativeLayerContract.js';
 
+/**
+ * Refresh this native path's GPU rendering.
+ *
+ * @returns {L.Path} This path.
+ */
 export function redrawPath() {
   refreshNativeLayerContract(this);
   return this;

package/src/core/removeLayer.js

@@ -1,12 +1,15 @@
-import { kindByLayer } from '../weakmaps/kindByLayer.js';
-
-import { L } from '../globals/L.js';
-import { removeLayer as sharedRemoveLayer } from '../globals/removeLayer.js';
-
+import { kindByLayer } from '../weakmaps/kindByLayer.js';
+import { L } from '../globals/L.js';
+import { removeLayer as sharedRemoveLayer } from '../globals/removeLayer.js';
 import { removeSceneLayer } from '../scene/removeSceneLayer.js';
 
-
-
+/**
+ * Remove a scene layer from this map, delegating ordinary layers to Leaflet.
+ *
+ * @param {L.Layer} layer Layer to remove.
+ *
+ * @returns {L.Map} This map.
+ */
 export function removeLayer(layer) {
   const id = L.Util.stamp(layer);
   if (!this._layers[id]) return this;

package/src/core/setRotation.js

@@ -1,5 +1,12 @@
 import { markerSetRotation } from './markerSetRotation.js';
 
+/**
+ * Set this marker's rotation.
+ *
+ * @param {number} rotation Rotation value.
+ *
+ * @returns {L.Marker} This marker.
+ */
 export function setRotation(rotation) {
   return markerSetRotation(this, rotation);
 }

package/src/core/tooltipGetEvents.js

@@ -1,6 +1,10 @@
 import { tooltipEvents } from '../globals/tooltipEvents.js';
 
-
+/**
+ * Extend this tooltip's map events with camera and terrain position updates.
+ *
+ * @returns {Object} Map event handlers.
+ */
 export function tooltipGetEvents() {
   const events = tooltipEvents.value.call(this);
   events.rotate = events.pitch = events.move = events.terrainchange = this._updatePosition;

package/src/core/tooltipSetPosition.js

@@ -1,9 +1,12 @@
 import { L } from '../globals/L.js';
 import { tooltipPosition } from '../globals/tooltipPosition.js';
-
-
 import { displayPoint } from '../projections/displayContainerPoint.js';
 
+/**
+ * Set this tooltip's position and apply the camera display offset.
+ *
+ * @param {L.Point} point Tooltip layer point.
+ */
 export function tooltipSetPosition(point) {
   tooltipPosition.value.call(this, point);
   const delta = displayPoint(this._map, point, this._latlng).subtract(point);

package/src/core/updateGridOpacity.js

@@ -1,7 +1,9 @@
 
 import { cancelGridFade } from '../animations/cancelGridFade.js';
 import { scheduleGridFade } from '../animations/scheduleGridFade.js';
+import { refreshNativeLayerContract } from '../native/refreshNativeLayerContract.js';
 
+/** Update this grid layer's GPU tile fades and schedule further frames when needed. */
 export function updateGridOpacity() {
   if (!this._map) return;
   const layer = this, now = Date.now();
@@ -24,4 +26,3 @@ export function updateGridOpacity() {
   cancelGridFade(layer);
   if (fading) scheduleGridFade(layer);
 }
-import { refreshNativeLayerContract } from '../native/refreshNativeLayerContract.js';

package/src/core/whenReady.js

@@ -1,10 +1,13 @@
-import { readyByLayer } from '../weakmaps/readyByLayer.js';
-import { cameraReadyByMap } from '../weakmaps/cameraReadyByMap.js';
-
-
-
-
+import { readyByLayer } from '../weakmaps/readyByLayer.js';
+import { cameraReadyByMap } from '../weakmaps/cameraReadyByMap.js';
 
+/**
+ * Get a layer or map's readiness promise, or resolve immediately if none is registered.
+ *
+ * @param {L.Layer|L.Map} instance Layer or map to inspect.
+ *
+ * @returns {Promise} Readiness promise.
+ */
 export function ready(instance) {
   return readyByLayer.get(instance) ||
     cameraReadyByMap.get(instance) || Promise.resolve(instance);

package/src/geometry/README.md

@@ -0,0 +1,29 @@
+# Geometry
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Builds mesh data for source features, terrain, native layers, models and traffic.
+Geometry routines use the dedicated projection and triangulation modules.
+
+## Feature geometry pipeline
+
+```mermaid
+flowchart LR
+  Feature["Styled + projected features"] --> Jobs["Area geometry jobs"]
+  Jobs --> Assemble["Worker assembly"]
+  Assemble --> Buffers["Typed attributes + bounds"]
+  Assemble --> Ranges["Feature face ranges"]
+  Ranges --> Picking["Picking"]
+  Parts["Procedural part tuples"] --> Build["buildGeometryParts"]
+  Build --> Arrays["Position / normal / color arrays"]
+```
+
+Half-open ranges identify features without one mesh per triangle; instancing
+is used where suitable. Polygon triangulation lives in
+[triangulation](../triangulation/README.md); native paths use a separate path.
+
+- [assembleAreaGeometry.js](./assembleAreaGeometry.js): assemble source area geometry.
+- [computeBounds.js](./computeBounds.js): compute bounds and radius for geometry.
+- [nativeGeometry.js](./nativeGeometry.js): build geometry from native Leaflet paths.
+
+Related: [triangulation](../triangulation/README.md), [projections](../projections/README.md), [rendering](../rendering/README.md).

package/src/geometry/addBridges.js

@@ -1,9 +1,8 @@
-import { bridgeMeshByLayer } from '../weakmaps/bridgeMeshByLayer.js';
-import { bridgesByLayer } from '../weakmaps/bridgesByLayer.js';
-import { locationByLayer } from '../weakmaps/locationByLayer.js';
-import { rootByLayer } from '../weakmaps/rootByLayer.js';
-import { terrainZoomByLayer } from '../weakmaps/terrainZoomByLayer.js';
-
+import { bridgeMeshByLayer } from '../weakmaps/bridgeMeshByLayer.js';
+import { bridgesByLayer } from '../weakmaps/bridgesByLayer.js';
+import { locationByLayer } from '../weakmaps/locationByLayer.js';
+import { rootByLayer } from '../weakmaps/rootByLayer.js';
+import { terrainZoomByLayer } from '../weakmaps/terrainZoomByLayer.js';
 import { radians } from '../globals/radians.js';
 import { createMesh } from '../rendering/createMesh.js';
 import { bridgePolygon } from './bridgePolygon.js';
@@ -12,6 +11,9 @@ import { bridgePolygon } from './bridgePolygon.js';
  * Bare-earth DEMs drop bridges: `getElevation` returns the deck height inside these polygons (GeoJSON
  * Polygon/MultiPolygon with Z, e.g. IGN BD TOPO), and one mesh draws the 1.2 m thick decks.
  * ponytail: anything under a deck (quays, boats asking `getElevation`) also gets the deck height.
+ *
+ * @param {L.Layer} layer Terrain layer owning bridge geometry.
+ * @param {Object} geojson Feature collection of bridge polygons.
  */
 export function addBridges(layer, geojson) {
   const map = layer._map, crs = map.options.crs, zoom = terrainZoomByLayer.get(layer);

package/src/geometry/addGeneratedTriangle.js

@@ -1,7 +1,11 @@
-import { triangleContexts } from '../globals/triangleContexts.js';
-
-import { addTriangle } from './appendAreaTriangle.js';
-
+import { triangleContexts } from '../globals/triangleContexts.js';
+import { addTriangle } from './appendAreaTriangle.js';
+
+/**
+ * Append a generated triangle to the current geometry context.
+ *
+ * @param {...*} args Triangle vertices, heights, normal and color.
+ */
 export function addGeneratedTriangle(...args) {
   addTriangle(triangleContexts[triangleContexts.length - 1], ...args);
 }

package/src/geometry/appendAreaTriangle.js

@@ -1,5 +1,20 @@
 import { groundOffset } from '../sources/groundOffset.js';
 
+/**
+ * Append an oriented triangle and its normals, colors and optional UVs to an area.
+ *
+ * @param {Object} context Area geometry buffers and options.
+ * @param {Object} a First projected vertex.
+ * @param {number} ah First vertex height.
+ * @param {Object} b Second projected vertex.
+ * @param {number} bh Second vertex height.
+ * @param {Object} c Third projected vertex.
+ * @param {number} ch Third vertex height.
+ * @param {number} nx Normal x component.
+ * @param {number} ny Normal y component.
+ * @param {number} nz Normal z component.
+ * @param {Object} color RGB color.
+ */
 export function addTriangle(context, a, ah, b, bh, c, ch, nx, ny, nz, color) {
   const { backend: layer, positions, normals, colors, uvs } = context;
   const ux = b.x - a.x, uy = bh - ah, uz = a.y - b.y;

package/src/geometry/appendNativeTriangle.js

@@ -1,3 +1,17 @@
+/**
+ * Project three native vertices and append them to a destination array.
+ *
+ * @param {Function} point Vertex projection function.
+ * @param {Array<number>} target Destination array.
+ * @param {L.Point} a First vertex.
+ * @param {L.Point} b Second vertex.
+ * @param {L.Point} c Third vertex.
+ * @param {L.Point} [anchorA] First vertex anchor.
+ * @param {L.Point} [anchorB] Second vertex anchor.
+ * @param {L.Point} [anchorC] Third vertex anchor.
+ *
+ * @returns {number} New destination length.
+ */
 export function triangle(point, target, a, b, c, anchorA, anchorB, anchorC) {
   return target.push(...point(a, anchorA), ...point(b, anchorB), ...point(c, anchorC));
 }

package/src/geometry/appendRouteDash.js

@@ -1,3 +1,21 @@
+/**
+ * Append a raised route dash as two colored triangles.
+ *
+ * @param {Array<number>} position Destination positions.
+ * @param {Array<number>} normal Destination normals.
+ * @param {Array<number>} color Destination colors.
+ * @param {Array<number>} a Segment start.
+ * @param {Array<number>} b Segment end.
+ * @param {number} dx Segment x displacement.
+ * @param {number} dz Segment z displacement.
+ * @param {number} x Dash half-width x offset.
+ * @param {number} z Dash half-width z offset.
+ * @param {number} start Start fraction along the segment.
+ * @param {number} end End fraction along the segment.
+ * @param {number} r Red component.
+ * @param {number} g Green component.
+ * @param {number} blue Blue component.
+ */
 export function appendRouteDash(position, normal, color, a, b, dx, dz, x, z, start, end, r, g, blue) {
   const px = a[0] + dx * start, pz = a[1] + dz * start;
   const py = a[2] + (b[2] - a[2]) * start + 0.4;

package/src/geometry/appendRouteSegment.js

@@ -1,5 +1,18 @@
 import { appendRouteDash } from './appendRouteDash.js';
 
+/**
+ * Append route dashes for a segment using cumulative distances to preserve dash phase.
+ *
+ * @param {Array<number>} position Destination positions.
+ * @param {Array<number>} normal Destination normals.
+ * @param {Array<number>} color Destination colors.
+ * @param {Array<Array<number>>} points Route points.
+ * @param {Array<number>} lengths Cumulative route distances.
+ * @param {number} i Segment end index.
+ * @param {number} r Red component.
+ * @param {number} g Green component.
+ * @param {number} blue Blue component.
+ */
 export function appendRouteSegment(position, normal, color, points, lengths, i, r, g, blue) {
   const a = points[i - 1], b = points[i];
   const dx = b[0] - a[0], dz = b[1] - a[1], length = lengths[i] - lengths[i - 1];

package/src/geometry/assembleAreaGeometry.js

@@ -3,6 +3,13 @@ import { buildProjectedPoint } from './buildProjectedPoint.js';
 import { instanceAreaGeometry } from './instanceAreaGeometry.js';
 import { computeBounds } from './computeBounds.js';
 
+/**
+ * Build area jobs into typed geometry buffers, feature ranges and light metadata.
+ *
+ * @param {Object} options Geometry jobs and night-light setting.
+ *
+ * @returns {Object} Prepared area geometry and metadata.
+ */
 export function assembleAreaGeometry({ jobs, nightLight }) {
   const context = /* alloc */ {
     backend: /* alloc */ { options: /* alloc */ { nightLight } },

package/src/geometry/boundsQuad.js

@@ -1,5 +1,13 @@
 import { localPosition } from '../projections/localPosition.js';
 
+/**
+ * Project geographic bounds corners into local scene positions.
+ *
+ * @param {Object} state Native layer projection state.
+ * @param {L.LatLngBounds} bounds Geographic bounds.
+ *
+ * @returns {Array} Projected northwest, northeast, southwest and southeast corners.
+ */
 export function boundsQuad(state, bounds) {
   const positions = /* alloc */ [];
   let i, corner;

package/src/geometry/box.js

@@ -1,3 +1,13 @@
+/**
+ * Create the four corners of an axis-aligned x/z rectangle.
+ *
+ * @param {number} x0 Minimum x.
+ * @param {number} x1 Maximum x.
+ * @param {number} z0 Minimum z.
+ * @param {number} z1 Maximum z.
+ *
+ * @returns {Array<Array<number>>} Rectangle corners.
+ */
 export function box(x0, x1, z0, z1) {
   return /* alloc */ [
     /* alloc */ [x0, z0],

package/src/geometry/bridgeEdge.js

@@ -1,3 +1,10 @@
+/**
+ * Append a bridge deck edge as two triangles with outward normals.
+ *
+ * @param {Object} context Destination position, normal and color arrays.
+ * @param {Array<number>} p First edge point.
+ * @param {Array<number>} q Second edge point.
+ */
 export function bridgeEdge(context, p, q) {
   const { position, normal, color } = context;
   const length = Math.hypot(q[0] - p[0], q[2] - p[2]) || 1;

package/src/geometry/bridgeElevation.js

@@ -1,4 +1,11 @@
-/** Height inside a bridge deck, or null outside its triangles. */
+/**
+ * Interpolate bridge deck height at a DEM pixel point.
+ *
+ * @param {L.Point} point DEM pixel coordinate.
+ * @param {Map} bridges Bridge triangle buckets, if present.
+ *
+ * @returns {number|null} Deck elevation, or null outside its triangles.
+ */
 export function bridgeElevation(point, bridges) {
   // Bridges bucketed by 64 DEM pixels.
   const bucket = bridges?.get(`${Math.floor(point.x / 64)}/${Math.floor(point.y / 64)}`);

package/src/geometry/bridgeFaces.js

@@ -1,3 +1,10 @@
+/**
+ * Append top and bottom bridge deck triangles with their normals and colors.
+ *
+ * @param {Object} context Destination position, normal and color arrays.
+ * @param {Array<Array<number>>} points Local bridge vertices.
+ * @param {Array<Array<number>>} triangles Triangle vertex indices.
+ */
 export function bridgeFaces(context, points, triangles) {
   const { position, normal, color } = context;
   let a, b, c, pa, pb, pc, i, k, p;

package/src/geometry/bridgePaths.js

@@ -1,3 +1,11 @@
+/**
+ * Reconstruct ring paths from flattened projected bridge pixels.
+ *
+ * @param {Array<Array>} rings Original bridge rings.
+ * @param {Array<Array<number>>} pixels Flattened projected coordinates.
+ *
+ * @returns {Array<Array<Object>>} Projected x/y paths.
+ */
 export function bridgePaths(rings, pixels) {
   const paths = /* alloc */ [];
   let start = 0, ring, path, i;