leaflet-city-mapper 0.0.8 → 0.1.0

package/src/textures/modelTextureSampler.js

@@ -1,5 +1,10 @@
-/** Translate glTF sampler constants into WebGPU sampler options. */
-
+/**
+ * Translate glTF sampler constants into WebGPU sampler options.
+ *
+ * @param {Object} sampler glTF sampler, if present.
+ *
+ * @returns {Object} WebGPU addressing and filtering options.
+ */
 export function textureSampler(sampler) {
   return /* alloc */ {
     addressModeU: sampler?.wrapS === 33071 ? 'clamp-to-edge' : sampler?.wrapS === 33648 ? 'mirror-repeat' : 'repeat',

package/src/textures/nativeImageError.js

@@ -1,6 +1,10 @@
 import { imageStates } from '../weakmaps/imageStates.js';
 
-
+/**
+ * Report a native image load failure to every associated source layer.
+ *
+ * @param {Event} event Image error event.
+ */
 export function nativeImageError(event) {
   const states = imageStates.get(event.currentTarget);
   if (!states) return;

package/src/textures/nativeImageRefresh.js

@@ -1,8 +1,11 @@
 import { imageStates } from '../weakmaps/imageStates.js';
-
-
 import { refreshNativeLayer } from '../native/refreshNativeLayer.js';
 
+/**
+ * Refresh all native layer states associated with an image event.
+ *
+ * @param {Event} event Image event.
+ */
 export function nativeImageRefresh(event) {
   const states = imageStates.get(event.currentTarget);
   if (!states) return;

package/src/textures/nativeTextureFor.js

@@ -1,13 +1,21 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { coreSampler } from '../globals/coreSampler.js';
-
 import { disposeMesh } from '../rendering/disposeMesh.js';
 import { destroyTexture } from './destroyTexture.js';
 import { uploadCanvasTexture } from './uploadCanvasTexture.js';
 import { uploadNativeImage } from './uploadNativeImage.js';
 
-
+/**
+ * Get or create a native raster texture, returning it once its image is uploaded.
+ *
+ * @param {Object} state Native layer state with texture and mesh caches.
+ * @param {string} key Tile or image cache key.
+ * @param {HTMLImageElement|HTMLCanvasElement} image Raster source.
+ *
+ * @returns {Object|undefined} Uploaded texture state, if ready.
+ *
+ * @throws {Error} If the source is neither an image nor a canvas.
+ */
 export function textureFor(state, key, image) {
   if (!(image instanceof HTMLImageElement) && !(image instanceof HTMLCanvasElement)) {
     throw /* alloc */ new Error('WebGPU native raster layers require image or canvas tiles');

package/src/textures/prepareMeshTextures.js

@@ -1,6 +1,14 @@
 import { uploadMeshTexture } from './uploadMeshTexture.js';
 import { bindMeshTextures } from './bindMeshTextures.js';
 
+/**
+ * Upload a mesh's program textures and rebuild its bind group when bindings change.
+ *
+ * @param {Object} renderer Renderer providing the GPU device and uniform buffer.
+ * @param {Object} mesh Mesh whose textures and bindings are prepared.
+ *
+ * @throws {Error} If a required program texture is missing.
+ */
 export function prepareMeshTextures(renderer, mesh) {
   const { program } = mesh;
   const { device } = renderer;

package/src/textures/rebuildRoofAtlas.js

@@ -1,20 +1,25 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { roofRasterByLayer } from '../weakmaps/roofRasterByLayer.js';
 import { sceneOriginByLayer } from '../weakmaps/sceneOriginByLayer.js';
-
 import { radians } from '../globals/radians.js';
 import { earthCirc } from '../globals/earthCirc.js';
 import { roofTiles } from '../globals/roofTiles.js';
 import { TILE_SIZE } from '../globals/TILE_SIZE.js';
 import { roofMin } from '../globals/roofMin.js';
 import { roofSize } from '../globals/roofSize.js';
-
-
 import { ensureRoofBlit } from './ensureRoofBlit.js';
 import { composeRoofAtlas } from './composeRoofAtlas.js';
 import { collectRoofTiles } from './collectRoofTiles.js';
 import { resizeRoofTexture } from './resizeRoofTexture.js';
 
+/**
+ * Rebuild the roof atlas from available raster tiles and update its scene-to-atlas matrix.
+ *
+ * @param {L.Layer} layer Rendering layer owning the atlas.
+ * @param {Array<L.Layer>} rasters Raster layers to composite.
+ * @param {string} signature Raster state signature.
+ * @param {number} now Current frame time in milliseconds.
+ */
 export function rebuildRoofAtlas(layer, rasters, signature, now) {
   const map = layer._map, renderer = rendererByLayer.get(layer);
   const tiles = roofTiles;

package/src/textures/removeImageState.js

@@ -1,6 +1,11 @@
-import { imageStates } from '../weakmaps/imageStates.js';
-
-
+import { imageStates } from '../weakmaps/imageStates.js';
+
+/**
+ * Remove a native layer state from an image's tracked associations.
+ *
+ * @param {HTMLImageElement} image Image to update.
+ * @param {Object} state Native layer state to remove.
+ */
 export function removeImageState(image, state) {
   const states = imageStates.get(image);
   if (!states) return;

package/src/textures/resizeRoofTexture.js

@@ -1,9 +1,16 @@
-import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
+import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { roofTexture } from '../globals/roofTexture.js';
 import { roofSampler } from '../globals/roofSampler.js';
 import { destroyTexture } from './destroyTexture.js';
 
+/**
+ * Create or resize the GPU texture used for the roof atlas.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {Object} roof Roof atlas state.
+ * @param {number} width Texture width in pixels.
+ * @param {number} height Texture height in pixels.
+ */
 export function resizeRoofTexture(layer, roof, width, height) {
   const renderer = rendererByLayer.get(layer);
   const descriptor = roofTexture;

package/src/textures/restoreMaterialTextures.js

@@ -1,3 +1,9 @@
+/**
+ * Recreate material textures and samplers that belong to a different GPU device.
+ *
+ * @param {Object} material Material containing model texture states.
+ * @param {GPUDevice} device Device to own restored resources.
+ */
 export function restoreMaterialTextures(material, device) {
   let name, texture;
   for (name in material) {

package/src/textures/textureBinding.js

@@ -1,3 +1,12 @@
+/**
+ * Reserve texture and sampler bindings and produce their WGSL declarations when enabled.
+ *
+ * @param {Array<Object>} bindings Program binding descriptions to extend.
+ * @param {string} name Shader texture uniform name.
+ * @param {boolean} enabled Whether the texture is used.
+ *
+ * @returns {string} WGSL declarations, or an empty string when disabled.
+ */
 export function textureBinding(bindings, name, enabled) {
   if (!enabled) return '';
   const current = 3 + bindings.length * 2;

package/src/textures/updateRoofAtlas.js

@@ -1,11 +1,17 @@
-import { loadingTilesByLayer } from '../weakmaps/loadingTilesByLayer.js';
-import { rasterVersionByLayer } from '../weakmaps/rasterVersionByLayer.js';
-import { roofRasterByLayer } from '../weakmaps/roofRasterByLayer.js';
-
+import { loadingTilesByLayer } from '../weakmaps/loadingTilesByLayer.js';
+import { rasterVersionByLayer } from '../weakmaps/rasterVersionByLayer.js';
+import { roofRasterByLayer } from '../weakmaps/roofRasterByLayer.js';
 import { L } from '../globals/L.js';
 import { roofSignatures } from '../globals/roofSignatures.js';
 import { rebuildRoofAtlas } from './rebuildRoofAtlas.js';
 
+/**
+ * Rebuild a changed roof atlas, throttling updates while raster tiles are loading.
+ *
+ * @param {L.Layer} layer Rendering layer owning the atlas.
+ * @param {Array<L.Layer>} rasters Raster layers included in the atlas.
+ * @param {number} now Current frame time in milliseconds.
+ */
 export function updateRoofAtlas(layer, rasters, now) {
   const signatures = roofSignatures;
   signatures.length = 0;

package/src/textures/updateRoofRaster.js

@@ -6,6 +6,14 @@ import { roofRastersByLayer } from '../weakmaps/roofRastersByLayer.js';
 import { updateRoofAtlas } from './updateRoofAtlas.js';
 import { destroyTexture } from './destroyTexture.js';
 
+/**
+ * Update or remove the roof atlas according to scene texture settings and active rasters.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {number} now Current frame time in milliseconds.
+ *
+ * @returns {Array<L.Layer>} Raster layers contributing to the roof atlas.
+ */
 export function updateRoofRaster(layer, now) {
   const map = layer._map;
   let rasters = roofRastersByLayer.get(layer);

package/src/textures/uploadCanvasTexture.js

@@ -1,6 +1,21 @@
 import { current } from '../native/isCurrentNativeLayer.js';
 import { refreshNativeLayer } from '../native/refreshNativeLayer.js';
 
+/**
+ * Rasterize a native canvas or image into a GPU texture and refresh its layer when ready.
+ *
+ * @param {Object} state Native layer state.
+ * @param {string} key Texture cache key.
+ * @param {Object} texture Destination texture state.
+ * @param {HTMLCanvasElement|HTMLImageElement} image Source image.
+ * @param {GPUDevice} device Device owning the destination.
+ * @param {number} width Image width in pixels.
+ * @param {number} height Image height in pixels.
+ *
+ * @returns {Promise<void>} Completion of the upload attempt.
+ *
+ * @throws {Error} Internally if SVG rasterization lacks a 2D context; reported to the source layer.
+ */
 export async function uploadCanvasTexture(state, key, texture, image, device, width, height) {
   let bitmap, source = image;
   try {

package/src/textures/uploadMeshTexture.js

@@ -2,6 +2,12 @@ import { meshImage } from '../globals/meshImage.js';
 import { meshTarget } from '../globals/meshTarget.js';
 import { meshCopySize } from '../globals/meshCopySize.js';
 
+/**
+ * Upload a mesh texture's image if it has changed since the previous upload.
+ *
+ * @param {GPUDevice} device Device owning the texture.
+ * @param {Object} texture Texture state containing its image and flip setting.
+ */
 export function uploadMeshTexture(device, texture) {
   if (texture.uploaded === texture.image) return;
   device.queue.copyExternalImageToTexture(

package/src/textures/uploadNativeImage.js

@@ -1,3 +1,16 @@
+/**
+ * Upload a native image, removing its cached GPU texture if the copy fails.
+ *
+ * @param {Object} state Native layer state containing the texture cache.
+ * @param {string} key Texture cache key.
+ * @param {Object} texture Destination texture state.
+ * @param {HTMLImageElement} image Source image.
+ * @param {GPUDevice} device Device owning the destination.
+ * @param {number} width Image width in pixels.
+ * @param {number} height Image height in pixels.
+ *
+ * @throws {Error} If the GPU image copy fails.
+ */
 export function uploadNativeImage(state, key, texture, image, device, width, height) {
   try {
     device.queue.copyExternalImageToTexture(

package/src/textures/uploadRoofTile.js

@@ -2,6 +2,12 @@ import { roofImage } from '../globals/roofImage.js';
 import { roofTarget } from '../globals/roofTarget.js';
 import { roofCopySize } from '../globals/roofCopySize.js';
 
+/**
+ * Upload a roof tile image when its texture does not already contain it.
+ *
+ * @param {GPUDevice} device Device owning the destination texture.
+ * @param {Object} tile Raster tile with image and texture state.
+ */
 export function uploadRoofTile(device, tile) {
   const source = tile.texture;
   if (source.uploaded !== source.image) {

package/src/traffic/README.md

@@ -0,0 +1,30 @@
+# Traffic
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Loads traffic lanes and schedules trips for vehicles and pedestrians, updating
+their poses in the shared GPU scene as simulation time advances.
+
+## Lane data to moving objects
+
+```mermaid
+flowchart LR
+  GeoJSON["GeoJSON lines"] --> Lanes["Lanes + properties"]
+  Lanes --> Project["Project to local metres"]
+  Terrain["Terrain / explicit elevation"] --> Project
+  Project --> Trips["Flow / timetable trips"]
+  Clock["Simulation time"] --> Trips
+  Trips --> Pose["GPU poses"]
+  Shapes["Vehicle shapes"] --> Pose
+  Pose --> Frame["Scene update"]
+```
+
+New lane loads abort the previous request; live time schedules further frames.
+Collision queries use current traffic bounds, but traffic does not steer around
+the walker. Timetables use their configured time zone.
+
+- [initTraffic.js](./initTraffic.js): configure a traffic layer.
+- [loadTraffic.js](./loadTraffic.js): request lanes for the current time.
+- [tickTraffic.js](./tickTraffic.js): refresh trips and poses.
+
+Related: [vehicles](../vehicles/README.md), [sunlight](../sunlight/README.md), [terrain](../terrain/README.md).

package/src/traffic/addTraffic.js

@@ -1,9 +1,12 @@
 import { trafficByLayer } from '../weakmaps/trafficByLayer.js';
-
-
 import { placeTraffic } from './placeTraffic.js';
 import { startTraffic } from './startTraffic.js';
 
+/**
+ * Register traffic state on layer addition and start loading if the layer is ready.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function addTraffic(state) {
   trafficByLayer.set(state.layer, state);
   if (state.ready) startTraffic(state);

package/src/traffic/clockMinutes.js

@@ -1,5 +1,12 @@
 
 
+/**
+ * Convert an HH:MM clock string to minutes after midnight.
+ *
+ * @param {string} clockTime Clock time in HH:MM form.
+ *
+ * @returns {number} Minutes after midnight.
+ */
 export function clockMinutes(clockTime) {
   const parts = clockTime.split(':');
   return Number(parts[0]) * 60 + Number(parts[1]);

package/src/traffic/compareDepartures.js

@@ -1,5 +1,13 @@
 
 
+/**
+ * Order departure times numerically.
+ *
+ * @param {number} a First departure in minutes.
+ * @param {number} b Second departure in minutes.
+ *
+ * @returns {number} Signed difference between the departures.
+ */
 export function compareDepartures(a, b) {
   return a - b;
 }

package/src/traffic/createTrafficMesh.js

@@ -1,5 +1,16 @@
-import * as createMeshApi from '../rendering/createMesh.js';
-
+import * as createMeshApi from '../rendering/createMesh.js';
+
+/**
+ * Create a traffic mesh and attach its feature ranges for picking.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Object} data Mesh geometry data.
+ * @param {Array} featureFaces Face ranges for picking.
+ * @param {Object} material Mesh material options.
+ * @param {number} [usage=0] Additional GPU buffer usage flags.
+ *
+ * @returns {Object} The created mesh.
+ */
 export function createTrafficMesh(state, data, featureFaces, material, usage = 0) {
   const result = createMeshApi.createMesh(state.layer, data, material, usage);
   result.extras.featureFaces = featureFaces;

package/src/traffic/destroyTrafficGpu.js

@@ -1,3 +1,8 @@
+/**
+ * Destroy the traffic compute buffers and release the GPU state.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function destroyTrafficGpu(state) {
   state.gpu?.params?.destroy();
   state.gpu?.template?.destroy();

package/src/traffic/disposeTrafficObject.js

@@ -1,13 +1,16 @@
-import { highlightedFeatureByLayer } from '../weakmaps/highlightedFeatureByLayer.js';
-import { hoveredFeatureByLayer } from '../weakmaps/hoveredFeatureByLayer.js';
-
-
-
-import * as disposeMesh from '../rendering/disposeMesh.js';
-import * as setHighlight from '../picking/setHighlight.js';
-import * as showFeature from '../picking/showFeature.js';
-
-export function disposeTrafficObject(state, object) {
+import { highlightedFeatureByLayer } from '../weakmaps/highlightedFeatureByLayer.js';
+import { hoveredFeatureByLayer } from '../weakmaps/hoveredFeatureByLayer.js';
+import * as disposeMesh from '../rendering/disposeMesh.js';
+import * as setHighlight from '../picking/setHighlight.js';
+import * as showFeature from '../picking/showFeature.js';
+
+/**
+ * Dispose a traffic mesh, clearing the layer's highlight and tooltip if they reference it.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Object|null} object Mesh to dispose, if present.
+ */
+export function disposeTrafficObject(state, object) {
   if (!object) return;
   if (highlightedFeatureByLayer.get(state.layer)?.mesh === object) {
     setHighlight.setHighlight(state.layer, null);

package/src/traffic/drawTrafficRoute.js

@@ -2,7 +2,11 @@ import { trafficRouteMaterial } from '../globals/trafficRouteMaterial.js';
 import { routeGeometry } from '../geometry/routeGeometry.js';
 import { createTrafficMesh } from './createTrafficMesh.js';
 
-
+/**
+ * Create the optional route outline mesh from the current traffic lanes.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function drawTrafficRoute(state) {
   state.route = createTrafficMesh(state, routeGeometry(state.lanes),
     /* alloc */ [], trafficRouteMaterial);

package/src/traffic/failTraffic.js

@@ -1,3 +1,9 @@
+/**
+ * Record and log a traffic error and expose it in the layer status.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Error} error Error to report.
+ */
 export function failTraffic(state, error) {
   state.error = error;
   state.status.textContent = `${state.vehicle}: Error: ${error.message}`;

package/src/traffic/failedTrafficLoad.js

@@ -1,5 +1,12 @@
-import { failTraffic } from './failTraffic.js';
-
-export function failedTrafficLoad(state, signal, error) {
+import { failTraffic } from './failTraffic.js';
+
+/**
+ * Report traffic loading errors unless the request was cancelled.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {AbortSignal} signal Signal for the lane request.
+ * @param {Error} error Loading failure.
+ */
+export function failedTrafficLoad(state, signal, error) {
   if (!signal.aborted && error.name !== 'AbortError') failTraffic(state, error);
 }

package/src/traffic/featuresToTrafficLanes.js

@@ -1,9 +1,17 @@
 import { trafficEmptyList } from '../globals/trafficEmptyList.js';
+
 // GeoJSON (Multi)LineStrings become lanes ({latlngs, properties, elevation?}); prepare() adds `points` ([x, z, ground]),
 // `lengths` and `length` in layer-local metres.
 
 
 
+/**
+ * Convert GeoJSON line and multiline features to lanes, preserving their properties and elevation.
+ *
+ * @param {Object} collection GeoJSON feature collection.
+ *
+ * @returns {Array} Lanes with latitude-longitude points and feature properties.
+ */
 export function toLanes({ features = trafficEmptyList }) {
   const lanes = /* alloc */ [];
   let geometry, properties, lines, line, latlngs, lng, lat, i;

package/src/traffic/fetchTrafficLanes.js

@@ -1,3 +1,14 @@
+/**
+ * Load time-dependent lanes from a JS module or fetch and cache a static GeoJSON response.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Date} time Current simulation time.
+ * @param {AbortSignal} signal Signal for cancelling the request.
+ *
+ * @returns {Promise<Object>} The loaded GeoJSON data.
+ *
+ * @throws {Error} If the static data request returns a non-success status.
+ */
 export async function fetchTrafficLanes(state, time, signal) {
   const href = /* alloc */ new URL(state.url, document.baseURI).href;
   if (/\.m?js(?:[?#]|$)/i.test(state.url)) return (await import(href)).default(time, state.layer, signal);

package/src/traffic/groundTraffic.js

@@ -1,8 +1,12 @@
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
 import { readyTerrainOf } from '../terrain/readyTerrainOf.js';
 import { mapElevationOf } from '../terrain/mapElevationOf.js';
 
+/**
+ * Update lane point heights from ready terrain or explicit elevations and invalidate GPU lane data.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function groundTraffic(state) {
   const { layer, lanes } = state;
   const terrain = readyTerrainOf(layer._map);

package/src/traffic/initTraffic.js

@@ -4,24 +4,9 @@ import { trafficEmptyOptions } from '../globals/trafficEmptyOptions.js';
 import { vehicles } from '../globals/vehicles.js';
 import { trafficShader } from '../globals/trafficShader.js';
 import { trafficByLayer } from '../weakmaps/trafficByLayer.js';
-
-
-/**
- * Vehicles moving along GeoJSON lanes; a compute pass places them on the GPU every frame.
- * Source options:
- * - `url`: GeoJSON (Multi)LineStrings, or a JS module whose default export `(time, layer, signal)` returns them (time-dependent data);
- * - `vehicle`: 'car' (default), 'boat', 'bus', 'tram', 'metro', 'bicycle' or 'pedestrian'; `side`: offset right of the lane centreline in metres (vehicle default);
- * - `speed`: m/s of `flow` lanes; `outline`: draw the lanes.
- * Lane properties: `flow` (vehicles/h) or `timetable` (see scheduledTrips.js), optional fixed `elevation`
- * in metres, `name`/`description` for the default tooltip. The status line (count and vehicle type) sits under the layer's entry in the layers control.
- * L.Control.Time on the same map drives the time; without one, vehicles run live.
- */
 import { build } from '../geometry/buildGeometryParts.js';
 import { init3D } from '../scene/init3D.js';
 import { tooltip } from './trafficTooltip.js';
-
-
-
 import { addTraffic } from './addTraffic.js';
 import { placeTraffic } from './placeTraffic.js';
 import { removeTraffic } from './removeTraffic.js';
@@ -30,6 +15,23 @@ import { tickTraffic } from './tickTraffic.js';
 import { updateTraffic } from './updateTraffic.js';
 import { updateTrafficTerrain } from './updateTrafficTerrain.js';
 
+/**
+ * Vehicles moving along GeoJSON lanes; a compute pass places them on the GPU every frame.
+ * Source options:
+ * - `url`: GeoJSON (Multi)LineStrings, or a JS module whose default export `(time, layer, signal)` returns them (time-dependent data);
+ * - `vehicle`: 'car' (default), 'boat', 'bus', 'tram', 'metro', 'bicycle' or 'pedestrian'; `side`: offset right of the lane centreline in metres (vehicle default);
+ * - `speed`: m/s of `flow` lanes; `outline`: draw the lanes.
+ * Lane properties: `flow` (vehicles/h) or `timetable` (see scheduledTrips.js), optional fixed `elevation`
+ * in metres, `name`/`description` for the default tooltip. The status line (count and vehicle type) sits under the layer's entry in the layers control.
+ * L.Control.Time on the same map drives the time; without one, vehicles run live.
+ */
+
+/**
+ * Initialize a traffic layer's model, GPU inputs, status and lifecycle handlers.
+ *
+ * @param {L.Layer} layer Traffic layer.
+ * @param {Object} [options] Source URL, vehicle, lane offset, outline and other layer options.
+ */
 export function initTraffic(layer, { url, vehicle = 'car', side, outline, speed: velocity = sharedSpeed, ...options } = trafficEmptyOptions) {
   const { model, lights, side: defaultSide } = vehicles[vehicle];
   side ??= defaultSide;

package/src/traffic/loadTraffic.js

@@ -3,6 +3,11 @@ import { fetchTrafficLanes } from './fetchTrafficLanes.js';
 import { loadedTrafficLanes } from './loadedTrafficLanes.js';
 import { failedTrafficLoad } from './failedTrafficLoad.js';
 
+/**
+ * Cancel the previous lane request and load lanes for the current valid simulation time.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function loadTraffic(state) {
   const { time } = trafficNow(state);
   if (!Number.isFinite(time?.getTime())) return;

package/src/traffic/loadedTrafficLanes.js

@@ -1,7 +1,14 @@
-import { toLanes } from './featuresToTrafficLanes.js';
-import { prepareTraffic } from './prepareTraffic.js';
-
-export function loadedTrafficLanes(state, signal, data) {
+import { toLanes } from './featuresToTrafficLanes.js';
+import { prepareTraffic } from './prepareTraffic.js';
+
+/**
+ * Apply loaded lanes unless cancelled or detached, preparing new data and restarting traffic updates.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {AbortSignal} signal Signal for the completed request.
+ * @param {Object} data Loaded GeoJSON data.
+ */
+export function loadedTrafficLanes(state, signal, data) {
   if (signal.aborted || !state.layer._map) return;
   state.error = null;
   if (data === state.loaded) {

package/src/traffic/locateTraffic.js

@@ -1,5 +1,14 @@
 import { along } from '../geometry/interpolateRoute.js';
 
+/**
+ * Interpolate a trip's current position along its looping lane and apply the lateral offset.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {Object} trip Trip with lane, distance and speed.
+ * @param {Object} target Reusable output position.
+ *
+ * @returns {Object} Position and direction along the lane.
+ */
 export function locateTraffic(state, trip, target) {
   const { points, lengths, length } = trip.lane;
   let distance = trip.distance + state.elapsed * trip.speed;

package/src/traffic/moveTraffic.js

@@ -1,3 +1,9 @@
+/**
+ * Dispatch the GPU traffic pose computation for the elapsed time and mark CPU geometry stale.
+ *
+ * @param {Object} state Traffic layer state.
+ * @param {number} seconds Seconds elapsed since the trip positions were rebased.
+ */
 export function moveTraffic(state, seconds) {
   const { device } = state.gpu;
   state.paramFloats[0] = state.elapsed = seconds;

package/src/traffic/placeTraffic.js

@@ -1,5 +1,10 @@
 import { locateTraffic } from './locateTraffic.js';
 
+/**
+ * Refresh stale CPU traffic positions and normals from the current trip poses.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function placeTraffic(state) {
   if (!state.mesh || !state.stale) return;
   state.stale = false;

package/src/traffic/prepareTraffic.js

@@ -1,12 +1,14 @@
 import { locationByLayer } from '../weakmaps/locationByLayer.js';
-
 import { radians } from '../globals/radians.js';
 import { L } from '../globals/L.js';
-
-
 import { disposeTrafficObject } from './disposeTrafficObject.js';
 import { groundTraffic } from './groundTraffic.js';
 
+/**
+ * Project lane coordinates to local metres, compute distances and heights, and invalidate old route geometry.
+ *
+ * @param {Object} state Traffic layer state.
+ */
 export function prepareTraffic(state) {
   const { layer, lanes } = state;
   const crs = layer._map.options.crs, origin = crs.project(locationByLayer.get(layer));