leaflet-city-mapper 0.0.9 → 0.1.1

package/src/sources/README.md

@@ -0,0 +1,33 @@
+# Vector sources
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Initializes GeoJSON and vector tile sources and manages source areas, feature
+preparation, loading queues and mesh attachment.
+
+## From view to mesh
+
+```mermaid
+flowchart LR
+  View["Map view"] --> Areas["updateArea: retain / release"]
+  Areas --> Queue["pump: nearest areas"]
+  Queue --> Load["Load feature collection"]
+  Load --> Style["Style + project features"]
+  Style --> Worker["Worker: build geometry"]
+  Worker --> Check{"Still wanted?"}
+  Check -->|yes| Mesh["Attach mesh + schedule frame"]
+  Check -->|no| Stop["Discard"]
+```
+
+GeoJSON uses one area; archive blocks include a view border. The
+[pump](./pumpSourceAreas.js) allows four jobs per scene and two per layer.
+`null` styles skip features; metadata and face ranges support
+[picking](../picking/README.md). Errors emit `error`; released areas abort
+work and destroy their buffers. [Vector tiles](../vector-tiles/README.md) have
+a separate lifecycle.
+
+- [initializeGeoJSON.js](./initializeGeoJSON.js): initialize a GeoJSON-backed layer.
+- [updateArea.js](./updateArea.js): maintain the areas needed by the view.
+- [buildArea.js](./buildArea.js): load features, build worker geometry and attach the mesh.
+
+Related: [scene](../scene/README.md), [workers](../workers/README.md), [vector-tiles](../vector-tiles/README.md).

package/src/sources/attachAreaMesh.js

@@ -1,15 +1,16 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
 import { nextId } from '../globals/nextId.js';
-
-
 import { emptyNode } from '../scene/createSceneNode.js';
 import { createProgram } from '../materials/createProgram.js';
-
 import { setParent } from '../scene/setParent.js';
 import { update } from '../scene/scheduleSceneUpdate.js';
 
+/**
+ * Attach an area's prepared geometry as a GPU mesh, or mark an empty area complete.
+ *
+ * @param {Object} context Area build context containing geometry and feature metadata.
+ */
 export function attachAreaMesh(context) {
   const { backend: layer, area } = context;
   if (!context.positions.length) {

package/src/sources/buildArea.js

@@ -1,8 +1,6 @@
 import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
 import { inflightByLayer } from '../weakmaps/inflightByLayer.js';
 import { cameraViewByMap } from '../weakmaps/cameraViewByMap.js';
-
-
 import { attachAreaMesh } from './attachAreaMesh.js';
 import { loadSource } from '../archives/loadSource.js';
 import { sourceAreaContext } from './sourceAreaContext.js';
@@ -10,6 +8,19 @@ import { pump } from './pumpSourceAreas.js';
 import { buildAreaInWorker } from '../workers/buildAreaInWorker.js';
 import { buildAreaFeatures } from './buildAreaFeatures.js';
 
+/**
+ * Load and build an area with worker geometry, reporting errors and releasing its load slot.
+ *
+ * @param {L.Layer} layer Source layer.
+ * @param {Object} area Area state and abort controller.
+ * @param {L.Map} map Map containing the layer.
+ *
+ * @returns {Promise<void>} Completion of the build attempt.
+ *
+ * @throws {Error} Internally if the response is not a GeoJSON feature collection; reported to the layer.
+ * @throws {Error} Internally if the GeoJSON style is not a function; reported to the layer.
+ * @throws {Error} Internally if workers are disabled; reported to the layer.
+ */
 export async function buildArea(layer, area, map) {
   try {
     await /* alloc */ new Promise(requestAnimationFrame);

package/src/sources/buildAreaFeature.js

@@ -4,6 +4,12 @@ import { extrusionStyle } from './extrusionStyle.js';
 import { prepareAreaGeometryJob } from './prepareAreaGeometryJob.js';
 import { matchesAreaTile } from './matchesAreaTile.js';
 
+/**
+ * Queue geometry and picking metadata for a styled feature belonging to the current source area.
+ *
+ * @param {Object} context Area build context.
+ * @param {Object} feature GeoJSON feature to process.
+ */
 export function buildAreaFeature(context, feature) {
   const { backend: layer, area, map } = context;
   const coords = area.coords;
@@ -21,6 +27,6 @@ export function buildAreaFeature(context, feature) {
   prepareAreaGeometryJob(context, feature, lon, lat, style, baseColor);
   context.featureFaces.push(/* alloc */ {
     id: feature.id ?? feature.properties?.objectid ?? JSON.stringify(geometry),
-    properties: feature.properties, baseColor,
+    properties: feature.properties, baseColor, polygon: geometry.type === 'Polygon' || geometry.type === 'MultiPolygon',
   });
 }

package/src/sources/buildAreaFeatures.js

@@ -1,14 +1,23 @@
-import { buildAreaFeature } from './buildAreaFeature.js';
-
-export async function buildAreaFeatures(context, area, features) {
-  let deadline = performance.now() + 4, feature;
-  for (feature of features) {
-    if (area.request.signal.aborted) return;
-    if (performance.now() >= deadline) {
-      await /* alloc */ new Promise(requestAnimationFrame);
-      if (area.request.signal.aborted) return;
-      deadline = performance.now() + 4;
-    }
-    buildAreaFeature(context, feature);
-  }
-}
+import { buildAreaFeature } from './buildAreaFeature.js';
+
+/**
+ * Process features in time-limited batches, stopping if the area request is aborted.
+ *
+ * @param {Object} context Area build context.
+ * @param {Object} area Area state and abort controller.
+ * @param {Array<Object>} features GeoJSON features to process.
+ *
+ * @returns {Promise<void>} Completion of feature processing.
+ */
+export async function buildAreaFeatures(context, area, features) {
+  let deadline = performance.now() + 4, feature;
+  for (feature of features) {
+    if (area.request.signal.aborted) return;
+    if (performance.now() >= deadline) {
+      await /* alloc */ new Promise(requestAnimationFrame);
+      if (area.request.signal.aborted) return;
+      deadline = performance.now() + 4;
+    }
+    buildAreaFeature(context, feature);
+  }
+}

package/src/sources/compareAreaDistance.js

@@ -1,3 +1,11 @@
+/**
+ * Order area coordinates by their distance from the view center.
+ *
+ * @param {Object} a First area coordinates.
+ * @param {Object} b Second area coordinates.
+ *
+ * @returns {number} Sort comparison.
+ */
 export function compareAreaDistance(a, b) {
   return a.distance - b.distance;
 }

package/src/sources/extrusionStyle.js

@@ -1,10 +1,21 @@
-export function extrusionStyle(layer, feature) {
-  const style = layer.options.style(feature);
-  if (style === null) return null;
-  if (!style || typeof style !== 'object') throw /* alloc */ new Error('style must return an extrusion style or null');
-  const { top, bottom = 0 } = style;
-  if (!Number.isFinite(top) || !Number.isFinite(bottom) || bottom < 0 || top <= bottom) {
-    throw /* alloc */ new Error('Invalid extrusion heights: expected top > bottom >= 0');
-  }
-  return style;
-}
+/**
+ * Evaluate and validate a feature's extrusion style.
+ *
+ * @param {L.Layer} layer Source layer with a style function.
+ * @param {Object} feature GeoJSON feature.
+ *
+ * @returns {Object|null} Valid style, or null to skip the feature.
+ *
+ * @throws {Error} If the style is neither an object nor null.
+ * @throws {Error} If extrusion heights do not satisfy top > bottom >= 0.
+ */
+export function extrusionStyle(layer, feature) {
+  const style = layer.options.style(feature);
+  if (style === null) return null;
+  if (!style || typeof style !== 'object') throw /* alloc */ new Error('style must return an extrusion style or null');
+  const { top, bottom = 0 } = style;
+  if (!Number.isFinite(top) || !Number.isFinite(bottom) || bottom < 0 || top <= bottom) {
+    throw /* alloc */ new Error('Invalid extrusion heights: expected top > bottom >= 0');
+  }
+  return style;
+}

package/src/sources/featureAnchor.js

@@ -1,9 +1,21 @@
-export function featureAnchor(feature, nightLight) {
-  const geometry = feature?.geometry, point = geometry?.type === 'Point';
-  if (nightLight && !point) throw /* alloc */ new Error('Night lights require Point geometry');
-  if (geometry?.type !== 'Polygon' && geometry?.type !== 'MultiPolygon' && !point) throw /* alloc */ new Error('Unsupported GeoJSON geometry');
-  const coordinates = point ? geometry.coordinates :
-    geometry.type === 'Polygon' ? geometry.coordinates[0]?.[0] : geometry.coordinates[0]?.[0]?.[0];
-  if (!Number.isFinite(coordinates?.[0]) || !Number.isFinite(coordinates?.[1])) throw /* alloc */ new Error('Invalid GeoJSON coordinates');
-  return coordinates;
-}
+/**
+ * Return the point or first polygon coordinate used to assign a feature to an area.
+ *
+ * @param {Object} feature GeoJSON feature.
+ * @param {boolean} nightLight Whether point geometry is required for a night light.
+ *
+ * @returns {Array<number>} Anchor coordinates in longitude, latitude order.
+ *
+ * @throws {Error} If a night-light feature is not a point.
+ * @throws {Error} If the geometry type is unsupported.
+ * @throws {Error} If anchor coordinates are not finite.
+ */
+export function featureAnchor(feature, nightLight) {
+  const geometry = feature?.geometry, point = geometry?.type === 'Point';
+  if (nightLight && !point) throw /* alloc */ new Error('Night lights require Point geometry');
+  if (geometry?.type !== 'Polygon' && geometry?.type !== 'MultiPolygon' && !point) throw /* alloc */ new Error('Unsupported GeoJSON geometry');
+  const coordinates = point ? geometry.coordinates :
+    geometry.type === 'Polygon' ? geometry.coordinates[0]?.[0] : geometry.coordinates[0]?.[0]?.[0];
+  if (!Number.isFinite(coordinates?.[0]) || !Number.isFinite(coordinates?.[1])) throw /* alloc */ new Error('Invalid GeoJSON coordinates');
+  return coordinates;
+}

package/src/sources/groundOffset.js

@@ -1,3 +1,10 @@
-export function groundOffset(point) {
-  return point.ground || 0;
+/**
+ * Read the projected point's ground offset, defaulting to zero.
+ *
+ * @param {Object} point Projected point.
+ *
+ * @returns {number} Ground offset.
+ */
+export function groundOffset(point) {
+  return point.ground || 0;
 }

package/src/sources/initVectorTiles.js

@@ -1,15 +1,21 @@
-import { kindByLayer } from '../weakmaps/kindByLayer.js';
-import { readyByLayer } from '../weakmaps/readyByLayer.js';
-import { configureVectorTileLayer } from '../vector-tiles/configureVectorTileLayer.js';
-import { readyVectorTiles } from './readyVectorTiles.js';
-import { reportError } from '../raster/reportRasterError.js';
-import { noOperation } from '../utils/noOperation.js';
-
-export function initVectorTiles(layer, options) {
-  kindByLayer.set(layer, 'pending');
-  const ready = configureVectorTileLayer(layer, options)
-    .then(readyVectorTiles.bind(null, layer))
-    .catch(reportError.bind(null, layer));
-  readyByLayer.set(layer, ready);
-  ready.catch(noOperation);
-}
+import { kindByLayer } from '../weakmaps/kindByLayer.js';
+import { readyByLayer } from '../weakmaps/readyByLayer.js';
+import { configureVectorTileLayer } from '../vector-tiles/configureVectorTileLayer.js';
+import { readyVectorTiles } from './readyVectorTiles.js';
+import { reportError } from '../raster/reportRasterError.js';
+import { noOperation } from '../utils/noOperation.js';
+
+/**
+ * Configure a vector tile layer asynchronously and report initialization errors.
+ *
+ * @param {L.Layer} layer Layer to initialize.
+ * @param {Object} options Vector tile configuration.
+ */
+export function initVectorTiles(layer, options) {
+  kindByLayer.set(layer, 'pending');
+  const ready = configureVectorTileLayer(layer, options)
+    .then(readyVectorTiles.bind(null, layer))
+    .catch(reportError.bind(null, layer));
+  readyByLayer.set(layer, ready);
+  ready.catch(noOperation);
+}

package/src/sources/initializeGeoJSON.js

@@ -1,10 +1,13 @@
 import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
-
-
-
 import { setGeoJSONLayerData } from './setGeoJSONLayerData.js';
 import { init3D } from '../scene/init3D.js';
 
+/**
+ * Mark a layer as GeoJSON-backed and initialize its 3D scene.
+ *
+ * @param {L.Layer} layer Layer to initialize.
+ * @param {Object} options Layer options.
+ */
 export function initializeGeoJSON(layer, options) {
   geojsonByLayer.set(layer, true);
   init3D(layer, options);

package/src/sources/isVectorTileSource.js

@@ -1,4 +1,11 @@
-export function isVectorTileSource(options) {
-  return options.data === undefined && (options.tileJSON !== undefined ||
-    typeof options.url === 'string' && /\{[zxy]\}|%7B[zxy]%7D/i.test(options.url));
-}
+/**
+ * Detect a tileJSON or templated tile URL when inline data is absent.
+ *
+ * @param {Object} options Source options.
+ *
+ * @returns {boolean} Whether the options identify a vector tile source.
+ */
+export function isVectorTileSource(options) {
+  return options.data === undefined && (options.tileJSON !== undefined ||
+    typeof options.url === 'string' && /\{[zxy]\}|%7B[zxy]%7D/i.test(options.url));
+}

package/src/sources/matchesAreaTile.js

@@ -1,7 +1,17 @@
-import { L } from '../globals/L.js';
-
-export function matchesAreaTile(map, coords, lon, lat) {
-  if (!coords) return true;
-  const anchor = map.project(/* alloc */ new L.LatLng(lat, lon), coords.z);
-  return Math.floor(anchor.x / 256) === coords.x && Math.floor(anchor.y / 256) === coords.y;
-}
+import { L } from '../globals/L.js';
+
+/**
+ * Check whether an anchor belongs to the given area tile.
+ *
+ * @param {L.Map} map Map used to project the anchor.
+ * @param {Object} coords Tile coordinates, if the area is tiled.
+ * @param {number} lon Anchor longitude.
+ * @param {number} lat Anchor latitude.
+ *
+ * @returns {boolean} Whether the anchor belongs to the area.
+ */
+export function matchesAreaTile(map, coords, lon, lat) {
+  if (!coords) return true;
+  const anchor = map.project(/* alloc */ new L.LatLng(lat, lon), coords.z);
+  return Math.floor(anchor.x / 256) === coords.x && Math.floor(anchor.y / 256) === coords.y;
+}

package/src/sources/pendingSourceAreas.js

@@ -1,21 +1,28 @@
 import { areasByLayer } from '../weakmaps/areasByLayer.js';
+import { compareDistance } from '../utils/compareDistance.js';
 
-import { compareDistance } from '../utils/compareDistance.js';
-
-export function pendingSourceAreas(layers, map) {
-  const pending = /* alloc */ [];
-  let layer, area, center;
-  for (layer of layers) {
-    for (area of areasByLayer.get(layer).values()) {
-      if (area.started || area.request.signal.aborted) continue;
-      center = area.coords && map.project(map.getCenter(), area.coords.z).divideBy(256);
-      pending.push(/* alloc */ {
-        layer, area,
-        distance: center
-          ? Math.hypot(area.coords.x + 0.5 - center.x, area.coords.y + 0.5 - center.y) / 2 ** area.coords.z : 0,
-      });
-    }
-  }
-  pending.sort(compareDistance);
-  return pending;
-}
+/**
+ * Gather unstarted, unaborted source areas in order of distance from the map center.
+ *
+ * @param {Array<L.Layer>} layers Source layers.
+ * @param {L.Map} map Map providing the view center and projection.
+ *
+ * @returns {Array<Object>} Pending layer and area entries with distances.
+ */
+export function pendingSourceAreas(layers, map) {
+  const pending = /* alloc */ [];
+  let layer, area, center;
+  for (layer of layers) {
+    for (area of areasByLayer.get(layer).values()) {
+      if (area.started || area.request.signal.aborted) continue;
+      center = area.coords && map.project(map.getCenter(), area.coords.z).divideBy(256);
+      pending.push(/* alloc */ {
+        layer, area,
+        distance: center
+          ? Math.hypot(area.coords.x + 0.5 - center.x, area.coords.y + 0.5 - center.y) / 2 ** area.coords.z : 0,
+      });
+    }
+  }
+  pending.sort(compareDistance);
+  return pending;
+}

package/src/sources/prepareAreaGeometryJob.js

@@ -1,24 +1,34 @@
-import { projectedTree } from '../projections/projectTreePoint.js';
-import { parseColor } from '../colors/parseColor.js';
-import { projectAreaPolygons } from './projectAreaPolygons.js';
-
-export function prepareAreaGeometryJob(context, feature, lon, lat, style, baseColor) {
-  const geometry = feature.geometry;
-  const polygons = projectAreaPolygons(context, geometry);
-  const point = geometry.type === 'Point' ? projectedTree(context, lon, lat) : null;
-  const nightLight = context.backend.options.nightLight;
-  const crownColor = point ? parseColor(style.color ?? (nightLight ? undefined : 0x4f823b)) : baseColor;
-  const trunkColor = point && !nightLight ? parseColor(style.trunkColor ?? 0x72513a) : null;
-  context.jobs.push(/* alloc */ {
-    point, polygons, baseColor: /* alloc */ { r: baseColor.r, g: baseColor.g, b: baseColor.b },
-    support: feature.properties?.cod_ouvrag || `${lon},${lat}`,
-    style: /* alloc */ {
-      top: style.top, bottom: style.bottom ?? 0,
-      color: /* alloc */ { r: crownColor.r, g: crownColor.g, b: crownColor.b },
-      trunkColor: trunkColor ? /* alloc */ { r: trunkColor.r, g: trunkColor.g, b: trunkColor.b } : undefined,
-      trunkRadius: style.trunkRadius, crownRadius: style.crownRadius,
-      crownBottom: style.crownBottom, crownShape: style.crownShape,
-      poleRadius: style.poleRadius, lightRadius: style.lightRadius, lightFlux: style.lightFlux,
-    },
-  });
-}
+import { projectedTree } from '../projections/projectTreePoint.js';
+import { parseColor } from '../colors/parseColor.js';
+import { projectAreaPolygons } from './projectAreaPolygons.js';
+
+/**
+ * Queue projected feature geometry and resolved style values for the geometry worker.
+ *
+ * @param {Object} context Area build context and job queue.
+ * @param {Object} feature GeoJSON feature.
+ * @param {number} lon Anchor longitude.
+ * @param {number} lat Anchor latitude.
+ * @param {Object} style Validated extrusion style.
+ * @param {Object} baseColor Parsed feature color.
+ */
+export function prepareAreaGeometryJob(context, feature, lon, lat, style, baseColor) {
+  const geometry = feature.geometry;
+  const polygons = projectAreaPolygons(context, geometry);
+  const point = geometry.type === 'Point' ? projectedTree(context, lon, lat) : null;
+  const nightLight = context.backend.options.nightLight;
+  const crownColor = point ? parseColor(style.color ?? (nightLight ? undefined : 0x4f823b)) : baseColor;
+  const trunkColor = point && !nightLight ? parseColor(style.trunkColor ?? 0x72513a) : null;
+  context.jobs.push(/* alloc */ {
+    point, polygons, baseColor: /* alloc */ { r: baseColor.r, g: baseColor.g, b: baseColor.b },
+    support: feature.properties?.cod_ouvrag || `${lon},${lat}`,
+    style: /* alloc */ {
+      top: style.top, bottom: style.bottom ?? 0,
+      color: /* alloc */ { r: crownColor.r, g: crownColor.g, b: crownColor.b },
+      trunkColor: trunkColor ? /* alloc */ { r: trunkColor.r, g: trunkColor.g, b: trunkColor.b } : undefined,
+      trunkRadius: style.trunkRadius, crownRadius: style.crownRadius,
+      crownBottom: style.crownBottom, crownShape: style.crownShape,
+      poleRadius: style.poleRadius, lightRadius: style.lightRadius, lightFlux: style.lightFlux,
+    },
+  });
+}

package/src/sources/projectAreaPolygons.js

@@ -1,15 +1,25 @@
-import { projectRing } from '../projections/projectRing.js';
-
-export function projectAreaPolygons(context, geometry) {
-  const rings = geometry.type === 'Polygon' ? /* alloc */ [geometry.coordinates]
-    : geometry.type === 'MultiPolygon' ? geometry.coordinates : /* alloc */ [];
-  const polygons = /* alloc */ [];
-  let polygon, ring, paths;
-  for (polygon of rings) {
-    if (!polygon.length) throw /* alloc */ new Error('Empty GeoJSON polygon');
-    paths = /* alloc */ [];
-    for (ring of polygon) paths.push(projectRing(context, ring));
-    polygons.push(paths);
-  }
-  return polygons;
-}
+import { projectRing } from '../projections/projectRing.js';
+
+/**
+ * Project every ring of a polygon or multipolygon into the area coordinate system.
+ *
+ * @param {Object} context Area projection context.
+ * @param {Object} geometry GeoJSON geometry.
+ *
+ * @returns {Array} Projected polygons, or an empty array for other geometry types.
+ *
+ * @throws {Error} If a polygon contains no rings.
+ */
+export function projectAreaPolygons(context, geometry) {
+  const rings = geometry.type === 'Polygon' ? /* alloc */ [geometry.coordinates]
+    : geometry.type === 'MultiPolygon' ? geometry.coordinates : /* alloc */ [];
+  const polygons = /* alloc */ [];
+  let polygon, ring, paths;
+  for (polygon of rings) {
+    if (!polygon.length) throw /* alloc */ new Error('Empty GeoJSON polygon');
+    paths = /* alloc */ [];
+    for (ring of polygon) paths.push(projectRing(context, ring));
+    polygons.push(paths);
+  }
+  return polygons;
+}

package/src/sources/pumpSourceAreas.js

@@ -3,17 +3,17 @@ import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
 import { inflightByLayer } from '../weakmaps/inflightByLayer.js';
 import { layersByLayer } from '../weakmaps/layersByLayer.js';
 import { urlByLayer } from '../weakmaps/urlByLayer.js';
-
 import { renderers } from '../weakmaps/renderers.js';
-
-
-
 import { updateStatus } from './updateSourceStatus.js';
-
 import { buildArea } from './buildArea.js';
 import { pendingSourceAreas } from './pendingSourceAreas.js';
 
-/** Share four load/build slots across source layers, nearest ground blocks first. */
+/**
+ * Share four load/build slots across source layers, nearest ground blocks first.
+ *
+ * @param {L.Layer} layer Layer used to find the shared renderer.
+ * @param {L.Map} [map] Map containing the source layers.
+ */
 export function pump(layer, map = layer._map) {
   const shared = map && renderers.get(map);
   if (!shared || !layersByLayer.has(shared)) return;

package/src/sources/readyVectorTiles.js

@@ -1,10 +1,17 @@
-import { kindByLayer } from '../weakmaps/kindByLayer.js';
-
-export function readyVectorTiles(layer) {
-  const map = layer._map;
-  map?.removeLayer(layer);
-  kindByLayer.delete(layer);
-  map?.addLayer(layer);
-  layer.fire('ready');
-  return layer;
-}
+import { kindByLayer } from '../weakmaps/kindByLayer.js';
+
+/**
+ * Reattach a configured vector tile layer and emit its ready event.
+ *
+ * @param {L.Layer} layer Configured layer.
+ *
+ * @returns {L.Layer} The layer.
+ */
+export function readyVectorTiles(layer) {
+  const map = layer._map;
+  map?.removeLayer(layer);
+  kindByLayer.delete(layer);
+  map?.addLayer(layer);
+  layer.fire('ready');
+  return layer;
+}

package/src/sources/releaseArea.js

@@ -1,14 +1,16 @@
 import { highlightedFeatureByLayer } from '../weakmaps/highlightedFeatureByLayer.js';
 import { hoveredFeatureByLayer } from '../weakmaps/hoveredFeatureByLayer.js';
-
-
-
 import { setHighlight } from '../picking/setHighlight.js';
 import { showFeature } from '../picking/showFeature.js';
 import { setParent } from '../scene/setParent.js';
 import { update } from '../scene/scheduleSceneUpdate.js';
 
-/** Cancel pending work and dispose this block's GPU data, including any hover highlight. */
+/**
+ * Cancel pending work and dispose this block's GPU data, including any hover highlight.
+ *
+ * @param {L.Layer} layer Layer owning the area.
+ * @param {Object} area Area to release.
+ */
 export function releaseArea(layer, area) {
   area.request.abort();
   let attribute;

package/src/sources/setGeoJSONData.js

@@ -1,10 +1,15 @@
 import { areasByLayer } from '../weakmaps/areasByLayer.js';
-
-
-
 import { releaseArea } from './releaseArea.js';
 import { updateArea } from './updateArea.js';
 
+/**
+ * Replace a layer's GeoJSON data, releasing old areas and scheduling a rebuild.
+ *
+ * @param {L.Layer} layer GeoJSON layer.
+ * @param {Object} data Replacement GeoJSON data.
+ *
+ * @returns {L.Layer} The updated layer.
+ */
 export function setGeoJSONData(layer, data) {
   layer.options.data = data;
   delete layer.options.url;

package/src/sources/setGeoJSONLayerData.js

@@ -1,5 +1,12 @@
 import { setGeoJSONData } from './setGeoJSONData.js';
 
+/**
+ * Replace this layer's GeoJSON data and rebuild its areas.
+ *
+ * @param {Object} data Replacement GeoJSON data.
+ *
+ * @returns {L.Layer} This layer.
+ */
 export function setGeoJSONLayerData(data) {
   return setGeoJSONData(this, data);
 }

package/src/sources/sourceAreaContext.js

@@ -1,8 +1,15 @@
 import { locationByLayer } from '../weakmaps/locationByLayer.js';
-
 import { radians } from '../globals/radians.js';
 
-
+/**
+ * Create the projection and job context for building a source area.
+ *
+ * @param {L.Layer} layer Source layer.
+ * @param {Object} area Area being built.
+ * @param {L.Map} map Map supplying the CRS.
+ *
+ * @returns {Object} Area build context.
+ */
 export function sourceAreaContext(layer, area, map) {
   const crs = map.options.crs, origin = crs.project(locationByLayer.get(layer));
   return /* alloc */ {

package/src/sources/updateArea.js

@@ -2,15 +2,15 @@ import { areasByLayer } from '../weakmaps/areasByLayer.js';
 import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
 import { headerByLayer } from '../weakmaps/headerByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
-
-
 import { pump } from "./pumpSourceAreas.js";
 import { releaseArea } from './releaseArea.js';
 import { compareAreaDistance } from './compareAreaDistance.js';
 
-/** Cover the visible ground bounds and one bordering block, clipped to the archive. */
-
+/**
+ * Update source areas covering visible ground and one bordering block, clipped to the archive.
+ *
+ * @param {L.Layer} layer Source layer.
+ */
 export function updateArea(layer) {
   if (!layer._map || !sharedByLayer.get(layer)) return;
   if (geojsonByLayer.get(layer)) {