leaflet-city-mapper 0.0.9 → 0.1.0

package/src/scene/renderPendingUpdates.js

@@ -1,13 +1,14 @@
 import { frameByLayer } from '../weakmaps/frameByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
 import { pendingUpdates } from '../globals/pendingUpdates.js';
-
-
-
 import { render } from '../rendering/render.js';
 
+/**
+ * Render queued shared scenes, continuing through failures before propagating the first.
+ *
+ * @throws {Error} The first rendering failure, if any.
+ */
 export function renderPendingUpdates() {
   const updates = /* alloc */ [...pendingUpdates];
   pendingUpdates.clear();

package/src/scene/reportLayerError.js

@@ -1,3 +1,9 @@
+/**
+ * Emit an error event on a source layer.
+ *
+ * @param {L.Layer} source Layer receiving the event.
+ * @param {Error} error Error to report.
+ */
 export function reportError(source, error) {
   source.fire('error', /* alloc */ { error });
 }

package/src/scene/resolveNextInitialization.js

@@ -1,8 +1,11 @@
 import { pendingInitializations } from '../globals/pendingInitializations.js';
-
-
 import { initializerFor } from './initializerFor.js';
 
+/**
+ * Dequeue an initialization and resolve its initializer or record an unknown-type error.
+ *
+ * @returns {Object} Initialization task.
+ */
 export function resolveNextInitialization() {
   const task = pendingInitializations.shift();
   task.initialize = initializerFor(task.type, task.settings);

package/src/scene/restoreObject.js

@@ -1,12 +1,15 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
-
-
 import { createProgram } from '../materials/createProgram.js';
 import { restoreGeometry } from '../geometry/restoreGeometry.js';
 import { restoreMaterialTextures } from '../textures/restoreMaterialTextures.js';
 
+/**
+ * Restore a scene object's GPU resources when it moves to a different device.
+ *
+ * @param {Object} object Scene object to restore.
+ * @param {L.Layer} layer Layer containing the object.
+ */
 export function restoreObject(object, layer) {
   const shared = sharedByLayer.get(layer);
   let texture;

package/src/scene/scheduleSceneUpdate.js

@@ -1,15 +1,16 @@
 import { frameByLayer } from '../weakmaps/frameByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
 import { pendingUpdates } from '../globals/pendingUpdates.js';
-
-
 import { render } from "../rendering/render.js";
-
 import { renderPendingUpdates } from './renderPendingUpdates.js';
 
-/** Scene graph, shared camera and frame rendering. */
-/** Content changes: render once on the next animation frame. */
+/**
+ * Schedule one shared-scene render on the next animation frame.
+ *
+ * @param {L.Layer} layer Layer whose content changed.
+ *
+ * @returns {L.Layer} The supplied layer.
+ */
 export function update(layer) {
   const shared = sharedByLayer.get(layer);
   if (!shared) return layer;

package/src/scene/setParent.js

@@ -1,5 +1,9 @@
-/** Reparent/detach scene data without drawing or disposing GPU resources. */
-
+/**
+ * Reparent or detach scene data without drawing or disposing GPU resources.
+ *
+ * @param {Object} node Scene node to move.
+ * @param {Object|null} parent New parent, or null to detach.
+ */
 export function setParent(node, parent) {
   if (node.parent) node.parent.children.splice(node.parent.children.indexOf(node), 1);
   node.parent = parent;

package/src/scene/traverse.js

@@ -1,5 +1,10 @@
-/** Depth-first walk; a truthy callback result skips that node's descendants. */
-
+/**
+ * Walk the scene depth-first; a truthy callback result skips that node's descendants.
+ *
+ * @param {Object} node Root node to visit.
+ * @param {Function} callback Called with each node and the supplied context.
+ * @param {*} context Context passed to the callback.
+ */
 export function traverse(node, callback, context) {
   if (callback(node, context)) return;
   let child;

package/src/shaders/README.md

@@ -0,0 +1,29 @@
+# Shaders
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Generates WGSL shader code for materials, native strokes and roof projection.
+Material program setup and GPU resource binding live outside this folder.
+
+## Generated variants
+
+```mermaid
+flowchart LR
+  Material["Material flags"] --> Generate["materialShaders"]
+  Generate --> Vertex["Vertex WGSL"]
+  Generate --> Surface["Fragment WGSL"]
+  Generate --> Bindings["Texture bindings + feature flags"]
+  Vertex --> Program["GPU program"]
+  Surface --> Program
+  Bindings --> Program
+```
+
+Generation does not require a GPU. Binding order, material layout, uniform
+writes and vertex attributes must agree; compilation diagnostics come from
+[gpu](../gpu/README.md).
+
+- [materialShaders.js](./materialShaders.js): assemble material shader variants.
+- [materialVertexShader.js](./materialVertexShader.js): generate vertex shader code.
+- [materialBaseShader.js](./materialBaseShader.js): generate material fragment logic.
+
+Related: [materials](../materials/README.md), [textures](../textures/README.md), [rendering](../rendering/README.md).

package/src/shaders/materialBaseShader.js

@@ -1,3 +1,12 @@
+/**
+ * Generate fragment code for base color, alpha and optional roof texture.
+ *
+ * @param {Object} material Material settings.
+ * @param {boolean} hasBase Whether a base texture is bound.
+ * @param {boolean} hasRoof Whether a roof texture is bound.
+ *
+ * @returns {string} WGSL fragment code.
+ */
 export function materialBaseShader(material, hasBase, hasRoof) {
   return /* wgsl */ `
       var normal = normalize(input.normal) * select(-1.0, 1.0, frontFacing);

package/src/shaders/materialShaders.js

@@ -4,7 +4,15 @@ import { validateRoofMaterial } from '../materials/validateRoofMaterial.js';
 import { materialVertexShader } from './materialVertexShader.js';
 import { materialSurfaceShader } from './materialSurfaceShader.js';
 
-/** Material WGSL and texture bindings, without a GPU device or Leaflet layer. */
+/**
+ * Generate material WGSL and texture bindings without a GPU device or Leaflet layer.
+ *
+ * @param {Object} [material] Material settings.
+ * @param {boolean} [sparkle=false] Whether to include sparkle coordinates and shading.
+ * @param {string} [elevationWGSL=''] Terrain elevation WGSL functions.
+ *
+ * @returns {Object} Vertex and fragment shaders, texture bindings and feature flags.
+ */
 export function materialShaders(material = defaultMaterial, sparkle = false, elevationWGSL = '') {
   const hasBase = Boolean(material.baseTexture);
   const hasMetal = Boolean(material.metalTexture);

package/src/shaders/materialSurfaceShader.js

@@ -1,5 +1,18 @@
 import { materialBaseShader } from './materialBaseShader.js';
 
+/**
+ * Generate lit or unlit material fragment code for the available textures.
+ *
+ * @param {Object} material Material settings.
+ * @param {boolean} sparkle Whether to include sparkle shading.
+ * @param {boolean} hasBase Whether a base texture is bound.
+ * @param {boolean} hasMetal Whether a metallic-roughness texture is bound.
+ * @param {boolean} hasEmissive Whether an emissive texture is bound.
+ * @param {boolean} hasOcclusion Whether an occlusion texture is bound.
+ * @param {boolean} hasRoof Whether a roof texture is bound.
+ *
+ * @returns {string} WGSL fragment code.
+ */
 export function materialSurfaceShader(material, sparkle, hasBase, hasMetal, hasEmissive, hasOcclusion, hasRoof) {
   return material.unlit ? /* wgsl */ `
         let rasterTexel = ${hasBase ? 'textureSample(baseTexture, baseTextureSampler, input.uv)' : 'vec4<f32>(input.color, 1.0)'};

package/src/shaders/materialVertexShader.js

@@ -1,6 +1,18 @@
 import { roofVertexShader } from './roofVertexShader.js';
 import { nativeStrokeShader } from './nativeStrokeShader.js';
 
+/**
+ * Generate a vertex shader for the material and its enabled rendering features.
+ *
+ * @param {Object} material Material settings.
+ * @param {boolean} sparkle Whether to output local sparkle coordinates.
+ * @param {string} elevationWGSL Terrain elevation WGSL functions.
+ * @param {boolean} hasTerrain Whether terrain elevation is enabled.
+ * @param {boolean} textured Whether texture coordinates are needed.
+ * @param {boolean} hasRoof Whether roof texture coordinates are needed.
+ *
+ * @returns {string} WGSL vertex shader.
+ */
 export function materialVertexShader(material, sparkle, elevationWGSL, hasTerrain, textured, hasRoof) {
   const instanceOffset = material.instanced ? ' + input.instanceOffset.xyz' : '';
   const stroke = nativeStrokeShader(material);
@@ -23,11 +35,10 @@ export function materialVertexShader(material, sparkle, elevationWGSL, hasTerrai
       skyDirection: vec4<f32>,
       atmosphereTint: vec4<f32>,
     };
-    @group(0) @binding(0) var<uniform> u: Mesh;
-    @group(0) @binding(1) var<uniform> frame: Frame;
-    struct Solar { matrix: mat4x4<f32>, params: vec4<f32> };
-    @group(1) @binding(0) var<uniform> solar: Solar;
-    ${hasTerrain ? /* wgsl */ `@group(0) @binding(2) var dem: texture_2d<f32>;${elevationWGSL}` : ''}
+    struct Solar {
+      matrix: mat4x4<f32>,
+      params: vec4<f32>
+    };
     struct VertexInput {
       @location(0) position: vec3<f32>,
       @location(1) normal: vec3<f32>,
@@ -46,6 +57,10 @@ export function materialVertexShader(material, sparkle, elevationWGSL, hasTerrai
       ${textured ? '@location(3) uv: vec2<f32>,' : ''}
       ${hasRoof ? '@location(4) roofUv: vec2<f32>, @location(5) roof: f32,' : ''}
     };
+    @group(0) @binding(0) var<uniform> u: Mesh;
+    @group(0) @binding(1) var<uniform> frame: Frame;
+    @group(1) @binding(0) var<uniform> solar: Solar;
+    ${hasTerrain ? /* wgsl */ `@group(0) @binding(2) var dem: texture_2d<f32>;${elevationWGSL}` : ''}
     @vertex fn vertexMain(input: VertexInput, @builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
       var output: VertexOutput;
       var position = input.position${instanceOffset};
@@ -53,14 +68,11 @@ export function materialVertexShader(material, sparkle, elevationWGSL, hasTerrai
       ${hasTerrain ? 'position.y = elevation(u.terrain.xy + input.uv * u.terrain.z, u.terrain.w) - u.terrain.w;' : ''}
       let featureVertex = f32(vertexIndex)${material.instanced ? ' + input.instanceOffset.w' : ''};
       let highlighted = featureVertex >= u.highlight.x && featureVertex < u.highlight.y;
-      output.color = ${material.vertexColors
-      ? 'select(input.color, vec3<f32>(72.0 / 255.0, 217.0 / 255.0, 1.0), highlighted)'
-      : 'u.baseColor.rgb'};
+      output.color = ${material.vertexColors ? 'select(input.color, vec3<f32>(72.0 / 255.0, 217.0 / 255.0, 1.0), highlighted)' : 'u.baseColor.rgb'};
       // Inverse-transpose from cofactors; the camera view matrix is orthonormal.
       let m = mat3x3<f32>(u.worldMatrix[0].xyz, u.worldMatrix[1].xyz, u.worldMatrix[2].xyz);
       ${stroke.normal}
-      let normal = (cross(m[1], m[2]) * sourceNormal.x + cross(m[2], m[0]) * sourceNormal.y +
-        cross(m[0], m[1]) * sourceNormal.z) / determinant(m);
+      let normal = (cross(m[1], m[2]) * sourceNormal.x + cross(m[2], m[0]) * sourceNormal.y + cross(m[0], m[1]) * sourceNormal.z) / determinant(m);
       output.normal = (frame.viewMatrix * vec4<f32>(normal, 0.0)).xyz;
       let world = u.worldMatrix * vec4<f32>(position, 1.0);
       output.shadowPosition = solar.matrix * world;

package/src/shaders/nativeStrokeShader.js

@@ -1,3 +1,10 @@
+/**
+ * Generate optional native-stroke position and normal vertex snippets.
+ *
+ * @param {Object} material Material settings.
+ *
+ * @returns {Object} WGSL position and normal snippets.
+ */
 export function nativeStrokeShader(material) {
   return /* alloc */ {
     position: material.nativeStroke ? 'position = input.normal + (input.position - input.normal) * u.nativeStroke.x;' : '',

package/src/shaders/roofVertexShader.js

@@ -1,3 +1,10 @@
+/**
+ * Generate vertex code for roof and wall texture coordinates and opacity.
+ *
+ * @param {Object} material Roof and wall texture settings.
+ *
+ * @returns {string} WGSL vertex code.
+ */
 export function roofVertexShader(material) {
   const roofOpacity = Number(material.roofTexture ?? 0);
   const wallOpacity = Number(material.wallTexture ?? 0);

package/src/shadows/README.md

@@ -0,0 +1,28 @@
+# Shadows
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Creates and renders directional sunlight shadow maps, with cached camera and
+mesh state to avoid unnecessary redraws.
+
+## Shadow pass and cache
+
+```mermaid
+flowchart LR
+  Sun["Sun position"] --> Check{"Casters + sun altitude ≥ 3°?"}
+  Meshes["Loaded shadow casters"] --> Check
+  Check -->|no| Disable["Disable shadow pass"]
+  Check -->|yes| Cache{"Cache matches?"}
+  Cache -->|yes| Reuse["Reuse depth map"]
+  Cache -->|no| Draw["Fit matrix + render depth map"]
+```
+
+Loaded off-screen geometry can cast shadows. Cache snapshots include direction,
+world versions, geometry and draw ranges: changes affecting shadows must
+invalidate the cache. Point lights are separate.
+
+- [renderSunlight.js](./renderSunlight.js): update sunlight shadow rendering.
+- [shadowMatrix.js](./shadowMatrix.js): fit the shadow camera to scene bounds.
+- [ensureShadowPipeline.js](./ensureShadowPipeline.js): prepare shadow GPU pipelines.
+
+Related: [lighting](../lighting/README.md), [sunlight](../sunlight/README.md), [rendering](../rendering/README.md).

package/src/shadows/bindSunlight.js

@@ -1,9 +1,11 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { sunBindGroup } from '../globals/sunBindGroup.js';
 
-
-
+/**
+ * Bind the renderer's sunlight uniforms, shadow texture, sampler and light buffer.
+ *
+ * @param {L.Layer} layer Layer owning the renderer.
+ */
 export function bindSunlight(layer) {
   const sun = rendererByLayer.get(layer).sunlight;
   sun.bindGroup = rendererByLayer.get(layer).device.createBindGroup((

package/src/shadows/drawShadowMeshes.js

@@ -1,10 +1,15 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { shadowPass } from '../globals/shadowPass.js';
 import { shadowBindGroup } from '../globals/shadowBindGroup.js';
 import { shadowOffsets } from '../globals/shadowOffsets.js';
 
-
+/**
+ * Encode the shadow depth pass for the supplied meshes.
+ *
+ * @param {L.Layer} layer Layer owning the renderer.
+ * @param {GPUCommandEncoder} encoder Encoder receiving the render pass.
+ * @param {Object[]} meshes Meshes to draw into the depth texture.
+ */
 export function drawShadowMeshes(layer, encoder, meshes) {
   const renderer = rendererByLayer.get(layer), device = renderer.device, sun = renderer.sunlight;
   const pass = encoder.beginRenderPass((

package/src/shadows/ensureShadowPipeline.js

@@ -7,6 +7,13 @@ import { shadowPipelineLayout } from '../globals/shadowPipelineLayout.js';
 import { shadowInstanceLayouts } from '../globals/shadowInstanceLayouts.js';
 import { shadowLayouts } from '../globals/shadowLayouts.js';
 
+/**
+ * Create the shadow pipeline and shared depth bindings if they are not yet available.
+ *
+ * @param {GPUDevice} device Device creating the GPU resources.
+ * @param {Object} sun Renderer sunlight state.
+ * @param {boolean} [instanced=false] Whether to create the instanced pipeline.
+ */
 export function ensureShadowPipeline(device, sun, instanced = false) {
   const key = instanced ? 'instancePipeline' : 'pipeline';
   if (!sun[key]) {

package/src/shadows/renderSunlight.js

@@ -1,16 +1,20 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { disabledShadow } from '../globals/disabledShadow.js';
 import { shadowValues } from '../globals/shadowValues.js';
-
 import { shadowCacheMatches } from './shadowCacheMatches.js';
 import { shadowMatrix } from './shadowMatrix.js';
 import { ensureShadowPipeline } from './ensureShadowPipeline.js';
 import { drawShadowMeshes } from './drawShadowMeshes.js';
 import { resizeSunlight } from './resizeSunlight.js';
 
-/** One shared directional depth map. Off-screen but loaded geometry can cast shadows. */
-
+/**
+ * Render one shared directional depth map, including off-screen loaded geometry.
+ *
+ * @param {L.Layer} layer Layer owning the renderer.
+ * @param {GPUCommandEncoder} encoder Encoder receiving the shadow pass.
+ * @param {Object[]} meshes Meshes that can cast shadows.
+ * @param {Object|null} sunlight Sun position and direction, if available.
+ */
 export function renderSunlight(layer, encoder, meshes, sunlight) {
   const renderer = rendererByLayer.get(layer), device = renderer.device, sun = renderer.sunlight;
   if (!meshes.length || !sunlight || sunlight.altitude < 3) {

package/src/shadows/resizeSunlight.js

@@ -1,11 +1,14 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { shadowTexture } from '../globals/shadowTexture.js';
-
-
 import { bindSunlight } from './bindSunlight.js';
 import { destroyTexture } from '../textures/destroyTexture.js';
 
+/**
+ * Replace the shadow depth texture when its required size changes and rebind sunlight.
+ *
+ * @param {L.Layer} layer Layer owning the renderer.
+ * @param {number} size Width and height of the square texture in pixels.
+ */
 export function resizeSunlight(layer, size) {
   const device = rendererByLayer.get(layer).device, sun = rendererByLayer.get(layer).sunlight;
   if (sun.size === size) return;

package/src/shadows/shadowCacheMatches.js

@@ -1,3 +1,14 @@
+import { shadowMeshMatches } from './shadowMeshMatches.js';
+
+/**
+ * Check whether the cached shadow map still matches sunlight and all meshes.
+ *
+ * @param {Object} sun Renderer sunlight state and shadow cache.
+ * @param {Object[]} meshes Current shadow-casting meshes.
+ * @param {Object} sunlight Current sunlight direction.
+ *
+ * @returns {boolean|undefined} Truthy if the cache is still valid.
+ */
 export function shadowCacheMatches(sun, meshes, sunlight) {
   const cache = sun.cache;
   let unchanged = sun.enabled && cache?.meshes.size === meshes.length;
@@ -14,4 +25,3 @@ export function shadowCacheMatches(sun, meshes, sunlight) {
   }
   return unchanged;
 }
-import { shadowMeshMatches } from './shadowMeshMatches.js';

package/src/shadows/shadowMatrix.js

@@ -2,10 +2,17 @@ import { shadowBounds as sharedShadowBounds } from '../globals/shadowBounds.js';
 import { shadowCamera } from '../globals/shadowCamera.js';
 import { shadowLow } from '../globals/shadowLow.js';
 import { shadowHigh } from '../globals/shadowHigh.js';
-
 import { shadowBounds } from '../geometry/shadowBounds.js';
 import { updateCamera } from '../camera/updateSceneCamera.js';
 
+/**
+ * Fit a directional shadow projection to the bounds of the supplied meshes.
+ *
+ * @param {Object[]} meshes Shadow-casting meshes.
+ * @param {Object} sunlight Sunlight direction.
+ *
+ * @returns {Float32Array} Column-major shadow projection-view matrix.
+ */
 export function shadowMatrix(meshes, sunlight) {
   const { min, max } = shadowBounds(meshes, sharedShadowBounds);
   const camera = shadowCamera;

package/src/shadows/shadowMeshMatches.js

@@ -1,3 +1,11 @@
+/**
+ * Check a mesh against its cached shadow state and pending attribute updates.
+ *
+ * @param {Object} cache Shadow cache containing mesh snapshots.
+ * @param {Object} mesh Mesh to compare.
+ *
+ * @returns {boolean} Whether the mesh still matches its snapshot.
+ */
 export function shadowMeshMatches(cache, mesh) {
   const previous = cache.meshes.get(mesh), range = mesh.geometry.drawRange;
   if (!(previous && previous.world === mesh._worldMatrixVersion && previous.geometry === mesh.geometry &&

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,5 +1,14 @@
 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) {

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

package/src/sources/featureAnchor.js

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

package/src/sources/groundOffset.js

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