leaflet-city-mapper 0.0.8 → 0.1.0

package/src/picking/onPointerLeave.js

@@ -1,12 +1,12 @@
 import { hoveredFeatureByLayer } from '../weakmaps/hoveredFeatureByLayer.js';
-
-
-
 import { setHighlight } from './setHighlight.js';
 import { showFeature } from './showFeature.js';
 
-/** Clear hover, highlight and tooltip without retaining a selected feature. */
-
+/**
+ * Clear hover, highlight and tooltip without retaining a selected feature.
+ *
+ * @param {L.Layer} layer Layer whose hover state is cleared.
+ */
 export function onPointerLeave(layer) {
   hoveredFeatureByLayer.set(layer, null);
   setHighlight(layer, null);

package/src/picking/onPointerMove.js

@@ -1,14 +1,15 @@
 import { hoveredFeatureByLayer } from '../weakmaps/hoveredFeatureByLayer.js';
-
-
-
 import { findFeature } from './findFeature.js';
 import { setHighlight } from './setHighlight.js';
 import { showFeature } from './showFeature.js';
 import { onPointerLeave } from './onPointerLeave.js';
 
-/** Gestures clear hover once without raycasting; normal misses report feature:null. */
-
+/**
+ * Clear hover during gestures; otherwise raycast and report the current feature or a miss.
+ *
+ * @param {L.Layer} layer Layer receiving the pointer movement.
+ * @param {PointerEvent} event Pointer movement event.
+ */
 export function onPointerMove(layer, event) {
   if (event.buttons || layer._map.dragging?.moving() || layer._map._animatingZoom) {
     if (hoveredFeatureByLayer.get(layer)) onPointerLeave(layer);

package/src/picking/pointerClick.js

@@ -1,5 +1,10 @@
 import * as onClick from './onClick.js';
 
+/**
+ * Forward a pointer click to the layer's feature handler.
+ *
+ * @param {MouseEvent} event Click event.
+ */
 export function pointerClick(event) {
   onClick.onClick(this, event);
 }

package/src/picking/pointerLeave.js

@@ -1,5 +1,6 @@
 import * as onPointerLeave from './onPointerLeave.js';
 
+/** Clear this layer's feature hover state when the pointer leaves. */
 export function pointerLeave() {
   onPointerLeave.onPointerLeave(this);
 }

package/src/picking/pointerMove.js

@@ -1,5 +1,10 @@
 import * as onPointerMove from './onPointerMove.js';
 
+/**
+ * Forward pointer movement to the layer's feature handler.
+ *
+ * @param {PointerEvent} event Pointer movement event.
+ */
 export function pointerMove(event) {
   onPointerMove.onPointerMove(this, event);
 }

package/src/picking/raycast.js

@@ -3,10 +3,7 @@ import { raycasterByLayer } from '../weakmaps/raycasterByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
-
 import { trafficByLayer } from '../weakmaps/trafficByLayer.js';
-
-
 import { intersectMeshes } from '../collision/intersectMeshes.js';
 import { traverse } from '../scene/traverse.js';
 import { updateCamera } from '../camera/updateSceneCamera.js';
@@ -19,12 +16,13 @@ import { validateCameraInverse } from './validateCameraInverse.js';
 /**
  * Finds the objects under a mouse or pointer event, nearest first.
  *
+ * @param {L.Layer} layer Layer providing the scene and camera.
  * @param {MouseEvent} event
  * @param {Object[]} [objects] Defaults to this layer's root children, not all map layers.
  * @param {boolean} [recursive] Also test the descendants of `objects`.
+ *
  * @returns {Object[]} Nearest hit per mesh: object, shared-world point/distance and triangle faceIndex.
  */
-
 export function raycast(layer, event, objects = rootByLayer.get(layer).children, recursive = true) {
   if (!rendererByLayer.get(layer)) {
     return /* alloc */ [];

package/src/picking/setHighlight.js

@@ -1,11 +1,12 @@
 import { highlightedFeatureByLayer } from '../weakmaps/highlightedFeatureByLayer.js';
-
-
-
 import { update } from '../scene/scheduleSceneUpdate.js';
 
-/** Highlight a source vertex range in the shader; vertex colors stay untouched. */
-
+/**
+ * Highlight a source vertex range in the shader; vertex colors stay untouched.
+ *
+ * @param {L.Layer} layer Layer whose highlight is updated.
+ * @param {Object|null} feature Picked feature to highlight, or null to clear it.
+ */
 export function setHighlight(layer, feature) {
   if (feature?.model) feature = null;
   if (highlightedFeatureByLayer.get(layer)?.mesh === feature?.mesh &&

package/src/picking/shouldSkipOther.js

@@ -1,7 +1,13 @@
 import { typeByLayer } from '../weakmaps/typeByLayer.js';
 
-
-
+/**
+ * Exclude the current layer, terrain and traffic from other-layer picking.
+ *
+ * @param {L.Layer} other Candidate layer.
+ * @param {L.Layer} layer Current layer.
+ *
+ * @returns {boolean} Whether the candidate should be skipped.
+ */
 export function shouldSkipOther(other, layer) {
   return other === layer || typeByLayer.get(other) === 'terrain' || typeByLayer.get(other) === 'traffic';
 }

package/src/picking/showFeature.js

@@ -4,10 +4,13 @@ import { layersByLayer } from '../weakmaps/layersByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
 import { tooltipByLayer } from '../weakmaps/tooltipByLayer.js';
 
-
-
-/** Update tooltip content/position and arbitrate cursor ownership across shared layers. */
-
+/**
+ * Update tooltip content and position and arbitrate cursor ownership across shared layers.
+ *
+ * @param {L.Layer} layer Layer whose tooltip is updated.
+ * @param {Object|null} feature Picked feature, or null to hide the tooltip.
+ * @param {MouseEvent} [event] Pointer event used to position a visible tooltip.
+ */
 export function showFeature(layer, feature, event) {
   const tooltip = tooltipByLayer.get(layer);
   if (!tooltip) return;

package/src/picking/validateCameraInverse.js

@@ -1,3 +1,10 @@
+/**
+ * Verify that all components of an inverse camera matrix are finite.
+ *
+ * @param {DOMMatrix} matrix Inverse camera matrix.
+ *
+ * @throws {Error} If any matrix component is not finite.
+ */
 export function validateCameraInverse(matrix) {
   let column, row;
   for (column = 1; column <= 4; column++) {

package/src/projections/README.md

@@ -0,0 +1,28 @@
+# Projections
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Converts coordinates between geographic, map pixel, screen and local scene
+spaces, including camera pitch and bearing.
+
+## Coordinate spaces
+
+```mermaid
+flowchart LR
+  Geo["Latitude / longitude"] --> CRS["Map CRS projection"]
+  CRS --> Local["Subtract layer origin + latitude scale"]
+  Local --> Root["Layer-local metres"]
+  Root --> World["Shared world via root transform"]
+  World --> Camera["Camera projection"]
+  Camera --> Screen["Screen pixels"]
+```
+
+Local coordinates use positive X east and negative Z north. Screen/ground
+conversion depends on pitch, bearing and view. Do not mix degrees, pixels,
+layer-local metres and shared-world coordinates.
+
+- [localPosition.js](./localPosition.js): compute a local scene position.
+- [projectCameraPoint.js](./projectCameraPoint.js): project a camera-aware point.
+- [groundBounds.js](./groundBounds.js): compute visible ground bounds.
+
+Related: [camera](../camera/README.md), [geometry](../geometry/README.md), [transforms](../transforms/README.md).

package/src/projections/cameraAngles.js

@@ -1,8 +1,15 @@
 import { radians } from '../globals/radians.js';
-
 import { mapGetBearing } from '../camera/mapGetBearing.js';
 import { mapGetPitch } from '../camera/mapGetPitch.js';
 
+/**
+ * Write cosine and sine of the map bearing and pitch in radians to a reusable array.
+ *
+ * @param {L.Map} map Map providing bearing and pitch.
+ * @param {number[]} [target] Reusable output array.
+ *
+ * @returns {number[]} Bearing cosine and sine followed by pitch cosine and sine.
+ */
 export function angles(map, target) {
   const bearing = mapGetBearing(map) * radians, pitch = mapGetPitch(map) * radians;
   target ||= /* alloc */ [];

package/src/projections/displayContainerPoint.js

@@ -9,6 +9,15 @@ import { mapElevationOf } from '../terrain/mapElevationOf.js';
 import { animationPoint } from './transformZoomAnimationPoint.js';
 import { project } from './projectCameraPoint.js';
 
+/**
+ * Convert a layer point to container coordinates, accounting for terrain elevation and camera animation.
+ *
+ * @param {L.Map} map Map containing the point.
+ * @param {L.Point} point Layer point to project.
+ * @param {L.LatLng} [location] Geographic position used to sample elevation.
+ *
+ * @returns {L.Point} Display position relative to the map pane.
+ */
 export function displayPoint(map, point, location) {
   const shared = renderers.get(map), origin = shared && sceneOriginByLayer.get(shared);
   if (!streamTerrainByMap.get(map) || !origin) {

package/src/projections/groundBounds.js

@@ -3,7 +3,15 @@ import { cameraZeroPadding } from '../globals/cameraZeroPadding.js';
 import { pointOf } from './toPoint.js';
 import { project } from './projectCameraPoint.js';
 
-
+/**
+ * Project the padded viewport corners onto a height plane and return their ground-space bounds.
+ *
+ * @param {L.Map} map Map whose viewport is projected.
+ * @param {L.Point|number[]} [padding] Total viewport padding.
+ * @param {number} [height] Height of the projection plane.
+ *
+ * @returns {L.Bounds} Bounds of the four projected corners.
+ */
 export function groundBounds(map, padding = cameraZeroPadding, height = 0) {
   const min = pointOf(padding).divideBy(2), max = map.getSize().subtract(min);
   const bounds = /* alloc */ new L.Bounds();

package/src/projections/localPixel.js

@@ -1,5 +1,13 @@
 import { localPosition } from './localPosition.js';
 
+/**
+ * Convert a map pixel to local X/Z metres, using the cached pixel projection when available.
+ *
+ * @param {Object} state Projection state, including the map and optional pixel projection.
+ * @param {L.Point} point Projected map pixel.
+ *
+ * @returns {number[]} Local coordinates as [x, 0, z].
+ */
 export function localPixel(state, point) {
   if (state.pixelProjection) {
     const { transformation, scale, origin, metres } = state.pixelProjection;

package/src/projections/localPixelForGeometry.js

@@ -1,7 +1,14 @@
 import { geometryPixelStates } from '../globals/geometryPixelStates.js';
-
 import { localPixel } from './localPixel.js';
 
+/**
+ * Project a geometry point and optionally record its stroke anchor in the active pixel projection.
+ *
+ * @param {L.Point} point Geometry pixel.
+ * @param {L.Point} [anchor] Optional stroke anchor.
+ *
+ * @returns {number[]} Local coordinates as [x, 0, z].
+ */
 export function localPixelForGeometry(point, anchor) {
   const state = geometryPixelStates[geometryPixelStates.length - 1];
   if (anchor && state.strokeAnchors) state.strokeAnchors.push(...localPixel(state, anchor));

package/src/projections/localPosition.js

@@ -1,8 +1,14 @@
 import { locationByLayer } from '../weakmaps/locationByLayer.js';
-
 import { radians } from '../globals/radians.js';
 
-
+/**
+ * Project a geographic position to local X/Z metres relative to the layer origin.
+ *
+ * @param {Object} state Projection state containing the map and backend layer.
+ * @param {L.LatLng} latlng Geographic position.
+ *
+ * @returns {number[]} Local coordinates as [x, 0, z].
+ */
 export function localPosition(state, latlng) {
   const { map, backend: layer } = state, crs = map.options.crs;
   const origin = crs.project(locationByLayer.get(layer)), point = crs.project(latlng);

package/src/projections/markerCameraIconPoint.js

@@ -1,8 +1,16 @@
 import { L } from '../globals/L.js';
 import { radians } from '../globals/radians.js';
-
 import { mapGetBearing } from '../camera/mapGetBearing.js';
 
+/**
+ * Rotate and scale an icon point according to marker options and the map bearing.
+ *
+ * @param {L.Marker} marker Marker with rotation and scale options.
+ * @param {number} x Horizontal icon coordinate.
+ * @param {number} y Vertical icon coordinate.
+ *
+ * @returns {L.Point} Transformed icon point.
+ */
 export function markerCameraIconPoint(marker, x, y) {
   let rotation = marker.options.rotation + (marker.options.rotateWithView ? mapGetBearing(marker._map) * radians : 0);
   if (marker.options.keepUpright && Math.cos(rotation) < 0) rotation += Math.PI;

package/src/projections/projectBridgePoint.js

@@ -1,4 +1,16 @@
-import { L } from '../globals/L.js';
+import { L } from '../globals/L.js';
+
+/**
+ * Project a geographic bridge point and its elevation into local scene coordinates.
+ *
+ * @param {number[]} coordinates Longitude, latitude and elevation.
+ * @param {Object} crs Coordinate reference system.
+ * @param {L.Point} origin Projected scene origin.
+ * @param {number} metres Projection scale to local metres.
+ * @param {number} base Scene base elevation.
+ *
+ * @returns {number[]} Local coordinates as [x, y, z].
+ */
 export function local([lng, lat, z], crs, origin, metres, base) {
   const p = crs.project(/* alloc */ new L.LatLng(lat, lng));
   return /* alloc */ [(p.x - origin.x) * metres, z - base, -(p.y - origin.y) * metres];

package/src/projections/projectCameraPoint.js

@@ -2,7 +2,17 @@ import { cameraAngles } from '../globals/cameraAngles.js';
 import { pointOf } from './toPoint.js';
 import { angles } from './cameraAngles.js';
 
-
+/**
+ * Project a map point through the pitched camera, or invert the projection onto a height plane.
+ *
+ * @param {L.Map} map Map supplying viewport size, bearing and pitch.
+ * @param {L.Point|number[]} point Point to project.
+ * @param {boolean} [inverse] Invert the projection.
+ * @param {boolean} [limit] Clamp inverse ground distance.
+ * @param {number} [height] Height of the point or inverse projection plane.
+ *
+ * @returns {L.Point} Projected point.
+ */
 export function project(map, point, inverse = false, limit = false, height = 0) {
   const size = map.getSize(), halfX = size.x / 2, halfY = size.y / 2, distance = size.y * 1.5;
   const result = pointOf(point);

package/src/projections/projectCelestialBody.js

@@ -1,5 +1,14 @@
-/** Perspective projection of a celestial direction; null when behind the camera. */
-
+/**
+ * Perspective projection of a celestial direction; null when behind the camera.
+ *
+ * @param {number[]} dir Celestial direction vector.
+ * @param {L.Point} size Viewport dimensions.
+ * @param {number} pitch Camera pitch in radians.
+ * @param {number} bearing Camera bearing in radians.
+ * @param {Object} [target] Reusable output object.
+ *
+ * @returns {Object|null} Screen coordinates in left and top, or null behind the camera.
+ */
 export function projectCelestialBody(dir, size, pitch, bearing, target) {
   const [x, y, z] = dir;
   const forward = -x * Math.sin(bearing) * Math.sin(pitch) - y * Math.cos(pitch) - z * Math.cos(bearing) * Math.sin(pitch);

package/src/projections/projectRing.js

@@ -1,8 +1,18 @@
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
 import { L } from '../globals/L.js';
 import { mapElevationOf } from '../terrain/mapElevationOf.js';
 
+/**
+ * Validate ring length and coordinates, then project its vertices except the closing point and sample terrain.
+ *
+ * @param {Object} context Projection state, backend layer and map.
+ * @param {number[][]} ring GeoJSON polygon ring.
+ *
+ * @returns {Object[]} Projected points with x, y and ground coordinates.
+ *
+ * @throws {Error} If the ring has fewer than four positions.
+ * @throws {Error} If a projected position has invalid longitude or latitude.
+ */
 export function projectRing(context, ring) {
   const { backend: layer, crs, origin, metres, map } = context;
   if (ring.length < 4) throw /* alloc */ new Error('Invalid GeoJSON polygon ring');

package/src/projections/projectTreePoint.js

@@ -1,8 +1,16 @@
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
 import { L } from '../globals/L.js';
 import { mapElevationOf } from '../terrain/mapElevationOf.js';
 
+/**
+ * Project a tree location relative to the source origin and sample its terrain height.
+ *
+ * @param {Object} context Projection state, backend layer and map.
+ * @param {number} lon Longitude.
+ * @param {number} lat Latitude.
+ *
+ * @returns {Object} Projected x, y and ground coordinates.
+ */
 export function projectedTree(context, lon, lat) {
   const { backend: layer, crs, origin, metres, map } = context;
   const location = /* alloc */ new L.LatLng(lat, lon);

package/src/projections/toPoint.js

@@ -1,4 +1,12 @@
-import { L } from '../globals/L.js';
+import { L } from '../globals/L.js';
+
+/**
+ * Copy an array or point-like object into a Leaflet point.
+ *
+ * @param {number[]|Object} point Array or object with x and y coordinates.
+ *
+ * @returns {L.Point} New point.
+ */
 export function pointOf(point) {
   return /* alloc */ new L.Point(
     Array.isArray(point) ? point[0] : point.x, Array.isArray(point) ? point[1] : point.y);

package/src/projections/transformZoomAnimationPoint.js

@@ -1,8 +1,15 @@
-import { cameraViewByMap } from '../weakmaps/cameraViewByMap.js';
-
-
-
-export function animationPoint(map, point, inverse = false) {
+import { cameraViewByMap } from '../weakmaps/cameraViewByMap.js';
+
+/**
+ * Apply or invert the current camera zoom-animation transform to a container point.
+ *
+ * @param {L.Map} map Map providing the current animation view.
+ * @param {L.Point} point Container point.
+ * @param {boolean} [inverse] Apply the inverse transform.
+ *
+ * @returns {L.Point} Transformed point, or the input when no animation view exists.
+ */
+export function animationPoint(map, point, inverse = false) {
   const view = cameraViewByMap.get(map);
   if (!view) return point;
   const half = map.getSize().divideBy(2), scale = map.getZoomScale(view.zoom);

package/src/projections/verticalGroundY.js

@@ -1,3 +1,14 @@
+/**
+ * Invert the vertical camera projection onto the ground, clamping at the far distance.
+ *
+ * @param {number} y Vertical camera coordinate.
+ * @param {number} tilt Cosine of camera pitch.
+ * @param {number} distance Camera distance.
+ * @param {number} rise Sine of camera pitch.
+ * @param {number} far Maximum ground distance.
+ *
+ * @returns {number} Clamped ground coordinate.
+ */
 export function verticalGroundY(y, tilt, distance, rise, far) {
   return tilt * distance + rise * y > 0
     ? Math.max(-far, Math.min(far, y * distance / (tilt * distance + rise * y))) : -far;

package/src/projections/walkerLocalPosition.js

@@ -4,6 +4,13 @@ import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { radians } from '../globals/radians.js';
 import { mapElevationOf } from '../terrain/mapElevationOf.js';
 
+/**
+ * Write the walker's local scene position, including terrain elevation and relative height, into output.
+ *
+ * @param {number[]} output Reusable three-element coordinate array.
+ *
+ * @returns {number[]} The supplied output array.
+ */
 export function local(output) {
   const { layer, state } = this;
   const map = layer._map, crs = map.options.crs

package/src/raster/README.md

@@ -0,0 +1,28 @@
+# Raster
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Selects, loads and retains raster tiles for the current view, creating meshes
+and optionally attaching imagery to terrain. Parent tiles provide interim coverage.
+
+## View-driven tile lifecycle
+
+```mermaid
+flowchart LR
+  View["Map view + archive header"] --> Select["Select zoom + wanted tiles"]
+  Select --> Fallback["Retain coarser parent coverage"]
+  Select --> Queue["Queue tile loads"]
+  Queue --> Mesh["Attach image / terrain mesh"]
+  Mesh --> Fade["Fade in"]
+  Fade --> Prune["Release obsolete coverage"]
+```
+
+Fallback tiles remain while wanted tiles are pending or fading; horizon views
+are capped at 169 tiles. Loading emits tile and loading events.
+[COG](../cog/README.md) uses an archive-compatible adapter.
+
+- [initRaster.js](./initRaster.js): initialize a raster layer.
+- [updateRasterTiles.js](./updateRasterTiles.js): select wanted and fallback tiles.
+- [pruneRasterTiles.js](./pruneRasterTiles.js): release tiles no longer needed.
+
+Related: [archives](../archives/README.md), [cog](../cog/README.md), [terrain](../terrain/README.md), [textures](../textures/README.md).

package/src/raster/addRasterTile.js

@@ -8,8 +8,6 @@ import { terrainOriginElevationByLayer } from '../weakmaps/terrainOriginElevatio
 import { terrainPromiseByLayer } from '../weakmaps/terrainPromiseByLayer.js';
 import { terrainZoomByLayer } from '../weakmaps/terrainZoomByLayer.js';
 import { terrain3DByMap } from '../weakmaps/terrain3DByMap.js';
-
-
 import { radians } from '../globals/radians.js';
 import { rasterPoint } from '../globals/rasterPoint.js';
 import { nextId } from '../globals/nextId.js';
@@ -19,6 +17,16 @@ import { setParent } from '../scene/setParent.js';
 import { update } from '../scene/scheduleSceneUpdate.js';
 import { terrainTileGeometry } from '../geometry/terrainTileGeometry.js';
 
+/**
+ * Attach a loaded raster tile to terrain after its terrain data is ready.
+ *
+ * @param {L.Layer} layer Terrain layer.
+ * @param {L.Layer} rasterLayer Raster source layer.
+ * @param {Object} coords Tile coordinates.
+ * @param {Object} tile Loaded raster tile.
+ *
+ * @returns {Promise<void>} Completion of the attachment attempt.
+ */
 export async function addRasterTile(layer, rasterLayer, coords, tile) {
   const ready = await terrainPromiseByLayer.get(layer);
   if (!ready || !layer._map || terrain3DByMap.get(layer._map) !== layer || terrain3DByLayer.get(rasterLayer) !== layer ||

package/src/raster/comparePendingTiles.js

@@ -1,5 +1,13 @@
 
 
+/**
+ * Order pending tiles by zoom and then distance from the map center.
+ *
+ * @param {Object} a First pending tile entry.
+ * @param {Object} b Second pending tile entry.
+ *
+ * @returns {number} Sort comparison.
+ */
 export function comparePendingTiles(a, b) {
   return a.tile.coords.z - b.tile.coords.z || a.distance - b.distance;
 }

package/src/raster/createRasterMesh.js

@@ -3,7 +3,6 @@ import { rasterGeometryByLayer } from '../weakmaps/rasterGeometryByLayer.js';
 import { rasterProgramByLayer } from '../weakmaps/rasterProgramByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
 import { radians } from '../globals/radians.js';
 import { rasterTexture } from '../globals/rasterTexture.js';
 import { rasterSampler } from '../globals/rasterSampler.js';
@@ -13,14 +12,16 @@ import { meshCopySize } from '../globals/meshCopySize.js';
 import { rasterPoint } from '../globals/rasterPoint.js';
 import { TILE_SIZE } from '../globals/TILE_SIZE.js';
 import { nextId } from '../globals/nextId.js';
-
-
-
 import { createProgram } from "../materials/createProgram.js";
 import { setParent } from "../scene/setParent.js";
-
 import { createGeometry } from '../geometry/createRasterQuadGeometry.js';
 
+/**
+ * Upload a raster tile image and attach its ground quad to the layer scene.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {Object} tile Tile with coordinates and decoded image.
+ */
 export function createRasterMesh(layer, tile) {
   const device = rendererByLayer.get(layer).device;
   const texture = /* alloc */ {

package/src/raster/finishRasterAttachment.js

@@ -1,11 +1,16 @@
 import { addedByLayer } from '../weakmaps/addedByLayer.js';
 import { terrain3DByMap } from '../weakmaps/terrain3DByMap.js';
-
-
-
-
 import { setRasterTerrain } from "./setRasterTerrain.js";
 
+/**
+ * Complete raster attachment and bind the current terrain, reporting failures.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {L.Map} map Map containing the layer.
+ * @param {Promise} attached Shared scene attachment.
+ *
+ * @returns {Promise<void>} Completion of the attachment attempt.
+ */
 export async function finishAttachment(layer, map, attached) {
   try {
     await attached;

package/src/raster/finishRasterTile.js

@@ -1,9 +1,7 @@
 import { loadingTilesByLayer } from '../weakmaps/loadingTilesByLayer.js';
 import { rasterVersionByLayer } from '../weakmaps/rasterVersionByLayer.js';
 import { readyByLayer } from '../weakmaps/readyByLayer.js';
-
 import { blobParts } from '../globals/blobParts.js';
-
 import { update } from "../scene/scheduleSceneUpdate.js";
 import { registerTerrainTile } from "./registerTerrainTile.js";
 import { pruneRasterTiles } from "./pruneRasterTiles.js";
@@ -11,6 +9,17 @@ import { pumpRasterTiles } from './pumpRasterTiles.js';
 import { createRasterMesh } from './createRasterMesh.js';
 import { getZxy } from '../archives/getZxy.js';
 
+/**
+ * Load and decode an archive tile, attach its mesh and report load or error events.
+ *
+ * @param {L.Layer} layer Raster layer.
+ * @param {Object} tile Tile state and abort controller.
+ *
+ * @returns {Promise<void>} Completion of the load attempt.
+ *
+ * @throws {Error} Internally if the tile is missing from the archive; reported to the layer.
+ * @throws {Error} Internally if tile decoding fails; reported to the layer.
+ */
 export async function finishRasterTile(layer, tile) {
   try {
     await readyByLayer.get(layer);

package/src/raster/getRasterEvents.js

@@ -1,5 +1,12 @@
 import { updateRasterTiles } from "./updateRasterTiles.js";
 
+/**
+ * Create map event handlers that update a raster layer's visible tiles.
+ *
+ * @param {L.Layer} layer Raster layer.
+ *
+ * @returns {Object} Map event names and handlers.
+ */
 export function getRasterEvents(layer) {
   const update = updateRasterTiles.bind(null, layer);
   return /* alloc */ { moveend: update, zoomend: update, rotate: update, pitch: update, resize: update };