leaflet-city-mapper 0.0.9 → 0.1.1

package/src/geometry/roofFootprint.js

@@ -1,32 +1,40 @@
 import { headerByLayer } from '../weakmaps/headerByLayer.js';
 import { sceneOriginByLayer } from '../weakmaps/sceneOriginByLayer.js';
 import { tileZoomByLayer } from '../weakmaps/tileZoomByLayer.js';
+import { radians } from '../globals/radians.js';
+import { earthCirc } from '../globals/earthCirc.js';
 
-import { radians } from '../globals/radians.js';
-import { earthCirc } from '../globals/earthCirc.js';
-
-export function roofFootprint(mesh, layer, rasterLayer) {
-  const map = layer._map, bounds = mesh.geometry.bounds, world = mesh.worldMatrix;
-  const zoom = tileZoomByLayer.get(rasterLayer)
-  const origin = map.project(sceneOriginByLayer.get(layer), zoom);
-  const scale = map.options.crs.scale(zoom) / (earthCirc * Math.cos(sceneOriginByLayer.get(layer).lat * radians));
-  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-  let i, x, y, z, px, py, nw, se;
-  for (i = 0; i < 8; i++) {
-    x = i & 1 ? bounds.max[0] : bounds.min[0], y = i & 2 ? bounds.max[1] : bounds.min[1];
-    z = i & 4 ? bounds.max[2] : bounds.min[2];
-    px = origin.x + (world[0] * x + world[4] * y + world[8] * z + world[12]) * scale;
-    py = origin.y + (world[2] * x + world[6] * y + world[10] * z + world[14]) * scale;
-    minX = Math.min(minX, px); minY = Math.min(minY, py);
-    maxX = Math.max(maxX, px); maxY = Math.max(maxY, py);
-  }
-  if (headerByLayer.get(rasterLayer).maxLat !== undefined && headerByLayer.get(rasterLayer).minLon !== undefined &&
-    headerByLayer.get(rasterLayer).minLat !== undefined && headerByLayer.get(rasterLayer).maxLon !== undefined) {
-    nw = map.project(/* alloc */ [headerByLayer.get(rasterLayer).maxLat, headerByLayer.get(rasterLayer).minLon], zoom);
-    se = map.project(/* alloc */ [headerByLayer.get(rasterLayer).minLat, headerByLayer.get(rasterLayer).maxLon], zoom);
-    minX = Math.max(minX, nw.x); minY = Math.max(minY, nw.y);
-    maxX = Math.min(maxX, se.x); maxY = Math.min(maxY, se.y);
-    if (minX >= maxX || minY >= maxY) return null;
-  }
-  return /* alloc */ [minX, minY, maxX, maxY];
-}
+/**
+ * Project a mesh's bounding box into raster pixels and clip it to archive bounds.
+ *
+ * @param {Object} mesh Mesh with bounds and world matrix.
+ * @param {L.Layer} layer Rendering layer.
+ * @param {L.Layer} rasterLayer Raster layer providing zoom and archive bounds.
+ *
+ * @returns {Array<number>|null} Pixel rectangle, or null when outside the archive.
+ */
+export function roofFootprint(mesh, layer, rasterLayer) {
+  const map = layer._map, bounds = mesh.geometry.bounds, world = mesh.worldMatrix;
+  const zoom = tileZoomByLayer.get(rasterLayer)
+  const origin = map.project(sceneOriginByLayer.get(layer), zoom);
+  const scale = map.options.crs.scale(zoom) / (earthCirc * Math.cos(sceneOriginByLayer.get(layer).lat * radians));
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  let i, x, y, z, px, py, nw, se;
+  for (i = 0; i < 8; i++) {
+    x = i & 1 ? bounds.max[0] : bounds.min[0], y = i & 2 ? bounds.max[1] : bounds.min[1];
+    z = i & 4 ? bounds.max[2] : bounds.min[2];
+    px = origin.x + (world[0] * x + world[4] * y + world[8] * z + world[12]) * scale;
+    py = origin.y + (world[2] * x + world[6] * y + world[10] * z + world[14]) * scale;
+    minX = Math.min(minX, px); minY = Math.min(minY, py);
+    maxX = Math.max(maxX, px); maxY = Math.max(maxY, py);
+  }
+  if (headerByLayer.get(rasterLayer).maxLat !== undefined && headerByLayer.get(rasterLayer).minLon !== undefined &&
+    headerByLayer.get(rasterLayer).minLat !== undefined && headerByLayer.get(rasterLayer).maxLon !== undefined) {
+    nw = map.project(/* alloc */ [headerByLayer.get(rasterLayer).maxLat, headerByLayer.get(rasterLayer).minLon], zoom);
+    se = map.project(/* alloc */ [headerByLayer.get(rasterLayer).minLat, headerByLayer.get(rasterLayer).maxLon], zoom);
+    minX = Math.max(minX, nw.x); minY = Math.max(minY, nw.y);
+    maxX = Math.min(maxX, se.x); maxY = Math.min(maxY, se.y);
+    if (minX >= maxX || minY >= maxY) return null;
+  }
+  return /* alloc */ [minX, minY, maxX, maxY];
+}

package/src/geometry/routeGeometry.js

@@ -1,7 +1,12 @@
 import { appendRouteSegment } from './appendRouteSegment.js';
 
-/** Dashed lane outline, in layer-local metres. */
-
+/**
+ * Build dashed lane geometry in layer-local metres.
+ *
+ * @param {Array<Object>} lanes Lanes with points, cumulative lengths and optional route colors.
+ *
+ * @returns {Object} Flat position, normal and color arrays.
+ */
 export function routeGeometry(lanes) {
   const position = /* alloc */ [];
   const normal = /* alloc */ [];

package/src/geometry/samePoint.js

@@ -1,3 +1,11 @@
-export function samePoint(a, b) {
-  return Math.abs(a[0] - b[0]) < 1e-10 && Math.abs(a[1] - b[1]) < 1e-10;
-}
+/**
+ * Compare two 2D coordinates with the geometry tolerance.
+ *
+ * @param {Array<number>} a First coordinate.
+ * @param {Array<number>} b Second coordinate.
+ *
+ * @returns {boolean} Whether both components are within tolerance.
+ */
+export function samePoint(a, b) {
+  return Math.abs(a[0] - b[0]) < 1e-10 && Math.abs(a[1] - b[1]) < 1e-10;
+}

package/src/geometry/segment.js

@@ -1,23 +1,32 @@
-import { L } from '../globals/L.js';
-import { triangle } from './appendNativeTriangle.js';
-import { disk } from './disk.js';
-
-export function segment(context, a, b, startCap, endCap) {
-  const { options, width, stroke, point } = context;
-  const radius = width / 2;
-  const anchorA = a, anchorB = b;
-  const length = a.distanceTo(b);
-  if (!length) return;
-  const direction = b.subtract(a).divideBy(length);
-  const normal = /* alloc */ new L.Point(-direction.y * radius, direction.x * radius);
-  if (options.lineCap === 'square') {
-    if (startCap) a = a.subtract(direction.multiplyBy(radius));
-    if (endCap) b = b.add(direction.multiplyBy(radius));
-  }
-  triangle(point, stroke, a.add(normal), a.subtract(normal), b.add(normal), anchorA, anchorA, anchorB);
-  triangle(point, stroke, b.add(normal), a.subtract(normal), b.subtract(normal), anchorB, anchorA, anchorB);
-  if (options.lineCap === 'round') {
-    if (startCap) disk(point, a, radius, stroke);
-    if (endCap) disk(point, b, radius, stroke);
-  }
-}
+import { L } from '../globals/L.js';
+import { triangle } from './appendNativeTriangle.js';
+import { disk } from './disk.js';
+
+/**
+ * Append a stroke segment with optional square or round caps.
+ *
+ * @param {Object} context Line style and geometry buffers.
+ * @param {L.Point} a Segment start.
+ * @param {L.Point} b Segment end.
+ * @param {boolean} startCap Whether to add a start cap.
+ * @param {boolean} endCap Whether to add an end cap.
+ */
+export function segment(context, a, b, startCap, endCap) {
+  const { options, width, stroke, point } = context;
+  const radius = width / 2;
+  const anchorA = a, anchorB = b;
+  const length = a.distanceTo(b);
+  if (!length) return;
+  const direction = b.subtract(a).divideBy(length);
+  const normal = /* alloc */ new L.Point(-direction.y * radius, direction.x * radius);
+  if (options.lineCap === 'square') {
+    if (startCap) a = a.subtract(direction.multiplyBy(radius));
+    if (endCap) b = b.add(direction.multiplyBy(radius));
+  }
+  triangle(point, stroke, a.add(normal), a.subtract(normal), b.add(normal), anchorA, anchorA, anchorB);
+  triangle(point, stroke, b.add(normal), a.subtract(normal), b.subtract(normal), anchorB, anchorA, anchorB);
+  if (options.lineCap === 'round') {
+    if (startCap) disk(point, a, radius, stroke);
+    if (endCap) disk(point, b, radius, stroke);
+  }
+}

package/src/geometry/setVertexColor.js

@@ -1,11 +1,11 @@
 /**
  * Paints the vertices `[start, end)` of a mesh and marks its color buffer dirty.
+ *
  * @param {Object} mesh Layer-created mesh with a color attribute.
  * @param {number} start Inclusive vertex index, not an offset into the RGB array.
  * @param {number} end Exclusive vertex index.
  * @param {Object} color sRGB {r,g,b}, typically from parseColor().
  */
-
 export function setVertexColor(mesh, start, end, color) {
   const rgb = /* alloc */ [];
   let i;

package/src/geometry/shadowBounds.js

@@ -1,6 +1,14 @@
 import { computeBounds } from './computeBounds.js';
 import { meshShadowBounds } from './meshShadowBounds.js';
 
+/**
+ * Compute combined world-space mesh bounds including ground below them.
+ *
+ * @param {Array<Object>} meshes Shadow meshes.
+ * @param {Object} [output] Bounds object to populate.
+ *
+ * @returns {Object} Combined minimum and maximum bounds.
+ */
 export function shadowBounds(meshes, output = /* alloc */ {
   min: /* alloc */ [Infinity, Infinity, Infinity],
   max: /* alloc */ [-Infinity, -Infinity, -Infinity],

package/src/geometry/subtractRoofTile.js

@@ -1,19 +1,28 @@
-export function subtractRoofTile(remaining, tile, zoom) {
-  const size = 256 * 2 ** (zoom - tile.coords.z);
-  const left = tile.coords.x * size, top = tile.coords.y * size;
-  const pieces = /* alloc */ [];
-  let x0, y0, x1, y1, l, t, r, b;
-  for ([x0, y0, x1, y1] of remaining) {
-    l = Math.max(x0, left), t = Math.max(y0, top);
-    r = Math.min(x1, left + size), b = Math.min(y1, top + size);
-    if (l >= r || t >= b) {
-      pieces.push(/* alloc */ [x0, y0, x1, y1]);
-      continue;
-    }
-    if (y0 < t) pieces.push(/* alloc */ [x0, y0, x1, t]);
-    if (b < y1) pieces.push(/* alloc */ [x0, b, x1, y1]);
-    if (x0 < l) pieces.push(/* alloc */ [x0, t, l, b]);
-    if (r < x1) pieces.push(/* alloc */ [r, t, x1, b]);
-  }
-  return pieces;
-}
+/**
+ * Subtract a raster tile's footprint from uncovered roof rectangles.
+ *
+ * @param {Array<Array<number>>} remaining Uncovered pixel rectangles.
+ * @param {Object} tile Raster tile with XYZ coordinates.
+ * @param {number} zoom Zoom used by the rectangles.
+ *
+ * @returns {Array<Array<number>>} Remaining uncovered rectangles.
+ */
+export function subtractRoofTile(remaining, tile, zoom) {
+  const size = 256 * 2 ** (zoom - tile.coords.z);
+  const left = tile.coords.x * size, top = tile.coords.y * size;
+  const pieces = /* alloc */ [];
+  let x0, y0, x1, y1, l, t, r, b;
+  for ([x0, y0, x1, y1] of remaining) {
+    l = Math.max(x0, left), t = Math.max(y0, top);
+    r = Math.min(x1, left + size), b = Math.min(y1, top + size);
+    if (l >= r || t >= b) {
+      pieces.push(/* alloc */ [x0, y0, x1, y1]);
+      continue;
+    }
+    if (y0 < t) pieces.push(/* alloc */ [x0, y0, x1, t]);
+    if (b < y1) pieces.push(/* alloc */ [x0, b, x1, y1]);
+    if (x0 < l) pieces.push(/* alloc */ [x0, t, l, b]);
+    if (r < x1) pieces.push(/* alloc */ [r, t, x1, b]);
+  }
+  return pieces;
+}

package/src/geometry/subtractVector.js

@@ -1,3 +1,11 @@
+/**
+ * Subtract one vector from another component by component.
+ *
+ * @param {ArrayLike<number>} a First vector.
+ * @param {ArrayLike<number>} b Vector to subtract.
+ *
+ * @returns {Array<number>} Difference vector.
+ */
 export function sub(a, b) {
   const result = /* alloc */ new Array(a.length);
   let i;

package/src/geometry/surface.js

@@ -1,7 +1,17 @@
 import { ringDirections } from '../globals/ringDirections.js';
-
 import { ring } from './createTreeRing.js';
 
+/**
+ * Generate the side surface between two eight-sided tree rings.
+ *
+ * @param {Object} point Ring center and ground height.
+ * @param {Function} addTriangle Triangle destination callback.
+ * @param {number} lowRadius Lower ring radius.
+ * @param {number} low Lower ring height.
+ * @param {number} highRadius Upper ring radius.
+ * @param {number} high Upper ring height.
+ * @param {Object} color Surface color.
+ */
 export function surface(point, addTriangle, lowRadius, low, highRadius, high, color) {
   const lower = ring(point, lowRadius), upper = ring(point, highRadius);
   let i, next, slope, length, nx, nz, ny, normalX, normalZ;

package/src/geometry/terrainBuffers.js

@@ -1,29 +1,36 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { terrainGridsByLayer } from '../weakmaps/terrainGridsByLayer.js';
+import { demBuffer } from '../globals/demBuffer.js';
+import { terrainGrid } from './terrainGrid.js';
 
-import { demBuffer } from '../globals/demBuffer.js';
-import { terrainGrid } from './terrainGrid.js';
-
-export function terrainBuffers(layer, divisions) {
-  const device = rendererByLayer.get(layer).device
-  let attributes = terrainGridsByLayer.get(layer).get(divisions);
-  if (!attributes) {
-    attributes = terrainGrid(divisions);
-    let name, attribute;
-    for ([name, attribute] of Object.entries(attributes)) {
-      attribute.size ||= 1;
-      attribute.count = attribute.data.length / attribute.size;
-      attribute.indexFormat = 'uint16';
-      attribute.buffer = device.createBuffer((
-        demBuffer.size = Math.max(4, attribute.data.byteLength),
-        demBuffer.usage = name === 'index'
-          ? GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST
-          : GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
-        demBuffer
-      ));
-      device.queue.writeBuffer(attribute.buffer, 0, attribute.data);
-    }
-    terrainGridsByLayer.get(layer).set(divisions, attributes);
-  }
-  return attributes;
-}
+/**
+ * Get or create cached GPU buffers for a terrain grid subdivision count.
+ *
+ * @param {L.Layer} layer Terrain layer owning the cache.
+ * @param {number} divisions Grid subdivisions per side.
+ *
+ * @returns {Object} GPU-backed grid attributes.
+ */
+export function terrainBuffers(layer, divisions) {
+  const device = rendererByLayer.get(layer).device
+  let attributes = terrainGridsByLayer.get(layer).get(divisions);
+  if (!attributes) {
+    attributes = terrainGrid(divisions);
+    let name, attribute;
+    for ([name, attribute] of Object.entries(attributes)) {
+      attribute.size ||= 1;
+      attribute.count = attribute.data.length / attribute.size;
+      attribute.indexFormat = 'uint16';
+      attribute.buffer = device.createBuffer((
+        demBuffer.size = Math.max(4, attribute.data.byteLength),
+        demBuffer.usage = name === 'index'
+          ? GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST
+          : GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        demBuffer
+      ));
+      device.queue.writeBuffer(attribute.buffer, 0, attribute.data);
+    }
+    terrainGridsByLayer.get(layer).set(divisions, attributes);
+  }
+  return attributes;
+}

package/src/geometry/terrainGrid.js

@@ -1,5 +1,10 @@
-/** Unit tile grid; the vertex shader supplies the elevation. */
-
+/**
+ * Create a unit tile grid; the vertex shader supplies the elevation.
+ *
+ * @param {number} divisions Grid subdivisions per side.
+ *
+ * @returns {Object} Position, normal, UV and index attributes.
+ */
 export function terrainGrid(divisions) {
   const vertices = (divisions + 1) ** 2;
   const positions = /* alloc */ new Float32Array(vertices * 3);

package/src/geometry/terrainTileGeometry.js

@@ -2,18 +2,27 @@ import { demByLayer } from '../weakmaps/demByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { terrainOriginElevationByLayer } from '../weakmaps/terrainOriginElevationByLayer.js';
 
-
-export function terrainTileGeometry(layer, attributes, sizeX, sizeZ) {
-  const base = terrainOriginElevationByLayer.get(layer)
-  const bottom = Math.min(demByLayer.get(layer).low, base) - base, top = Math.max(demByLayer.get(layer).high, base) - base;
-  return /* alloc */ {
-    device: rendererByLayer.get(layer).device,
-    attributes,
-    drawRange: /* alloc */ { start: 0, count: attributes.index.count },
-    // Bounds must cover the DEM-displaced tile, although picking uses the flat grid.
-    bounds: /* alloc */ {
-      min: /* alloc */ [0, bottom, 0], max: /* alloc */ [1, top, 1], center: /* alloc */ [0.5, (bottom + top) / 2, 0.5],
-      radius: Math.hypot(sizeX, top - bottom, sizeZ) / 2 / Math.max(sizeX, 1, sizeZ),
-    },
-  };
-}
+/**
+ * Create terrain tile geometry with bounds covering DEM-displaced elevations.
+ *
+ * @param {L.Layer} layer Terrain layer.
+ * @param {Object} attributes Shared terrain grid attributes.
+ * @param {number} sizeX Tile width in scene units.
+ * @param {number} sizeZ Tile depth in scene units.
+ *
+ * @returns {Object} Tile geometry and bounds.
+ */
+export function terrainTileGeometry(layer, attributes, sizeX, sizeZ) {
+  const base = terrainOriginElevationByLayer.get(layer)
+  const bottom = Math.min(demByLayer.get(layer).low, base) - base, top = Math.max(demByLayer.get(layer).high, base) - base;
+  return /* alloc */ {
+    device: rendererByLayer.get(layer).device,
+    attributes,
+    drawRange: /* alloc */ { start: 0, count: attributes.index.count },
+    // Bounds must cover the DEM-displaced tile, although picking uses the flat grid.
+    bounds: /* alloc */ {
+      min: /* alloc */ [0, bottom, 0], max: /* alloc */ [1, top, 1], center: /* alloc */ [0.5, (bottom + top) / 2, 0.5],
+      radius: Math.hypot(sizeX, top - bottom, sizeZ) / 2 / Math.max(sizeX, 1, sizeZ),
+    },
+  };
+}

package/src/geometry/treeGeometry.js

@@ -1,13 +1,16 @@
 import { roundProfile } from '../globals/roundProfile.js';
-
-
 import { parseColor } from "../colors/parseColor.js";
 import { ring } from './createTreeRing.js';
 import { surface } from './surface.js';
 import { validateTree } from './validateTree.js';
 
-/** Low-poly tree, sharing the source block's buffers, picking and terrain offset. */
-
+/**
+ * Generate a low-poly tree in the source block's geometry buffers.
+ *
+ * @param {Object} point Projected position and ground height.
+ * @param {Object} style Tree dimensions, crown shape and colors.
+ * @param {Function} addTriangle Triangle destination callback.
+ */
 export function treeGeometry(point, style, addTriangle) {
   const { top, bottom = 0, trunkRadius, crownRadius, crownBottom, crownShape = 'round' } = style;
   validateTree(trunkRadius, crownRadius, crownBottom, bottom, top, crownShape);

package/src/geometry/triangle.js

@@ -1,3 +1,14 @@
+/**
+ * Append a colored triangle and its normalized face normal.
+ *
+ * @param {Array<number>} position Destination positions.
+ * @param {Array<number>} normal Destination normals.
+ * @param {Array<number>} color Destination colors.
+ * @param {Array<number>} a First vertex.
+ * @param {Array<number>} b Second vertex.
+ * @param {Array<number>} c Third vertex.
+ * @param {Array<number>} tint RGB color.
+ */
 export function triangle(position, normal, color, a, b, c, tint) {
   const ux = b[0] - a[0], uy = b[1] - a[1], uz = b[2] - a[2];
   const vx = c[0] - a[0], vy = c[1] - a[1], vz = c[2] - a[2];

package/src/geometry/validateTree.js

@@ -1,7 +1,19 @@
-export function validateTree(trunkRadius, crownRadius, crownBottom, bottom, top, crownShape) {
-  if (!Number.isFinite(trunkRadius) || !Number.isFinite(crownRadius) || !Number.isFinite(crownBottom) ||
-    trunkRadius <= 0 || crownRadius < trunkRadius || crownBottom <= bottom || crownBottom >= top ||
-    crownShape !== 'round' && crownShape !== 'cone') {
-    throw /* alloc */ new Error('Invalid tree dimensions or crown shape');
-  }
-}
+/**
+ * Validate tree radii, crown height and crown shape.
+ *
+ * @param {number} trunkRadius Trunk radius.
+ * @param {number} crownRadius Crown radius.
+ * @param {number} crownBottom Height where the crown begins.
+ * @param {number} bottom Tree bottom height.
+ * @param {number} top Tree top height.
+ * @param {string} crownShape Crown shape.
+ *
+ * @throws {Error} If dimensions or crown shape are invalid.
+ */
+export function validateTree(trunkRadius, crownRadius, crownBottom, bottom, top, crownShape) {
+  if (!Number.isFinite(trunkRadius) || !Number.isFinite(crownRadius) || !Number.isFinite(crownBottom) ||
+    trunkRadius <= 0 || crownRadius < trunkRadius || crownBottom <= bottom || crownBottom >= top ||
+    crownShape !== 'round' && crownShape !== 'cone') {
+    throw /* alloc */ new Error('Invalid tree dimensions or crown shape');
+  }
+}

package/src/geometry/vertexNormals.js

@@ -1,5 +1,11 @@
-/** Area-weighted vertex normals, for indexed or non-indexed triangles. */
-
+/**
+ * Compute area-weighted vertex normals for indexed or non-indexed triangles.
+ *
+ * @param {ArrayLike<number>} p Flat vertex positions.
+ * @param {ArrayLike<number>} [indices] Optional triangle vertex indices.
+ *
+ * @returns {Float32Array} Normalized vertex normals.
+ */
 export function vertexNormals(p, indices) {
   // Accumulate area-weighted face normals for shared vertices, then normalize.
   const normals = /* alloc */ new Float32Array(p.length);

package/src/geometry/visitNativeCoordinates.js

@@ -1,6 +1,13 @@
 import { L } from '../globals/L.js';
 import { polygon } from './polygon.js';
 
+/**
+ * Visit nested native coordinates and generate polygon or line geometry.
+ *
+ * @param {Object} context Projection, style and geometry buffers.
+ * @param {Array} coordinates Nested Leaflet coordinates.
+ * @param {boolean} closed Whether the geometry is closed.
+ */
 export function visit(context, coordinates, closed) {
   if (!coordinates.length) return;
   let child;

package/src/globals/CELL.js

@@ -1,3 +1,7 @@
-// Walls (non-horizontal triangles) of a mesh in world space, bucketed by 8 m cells; `origin` is the world translation
-// at build time, since layer roots only move vertically with the terrain afterwards.
+/**
+ * Collision grid cell size in meters for world-space wall triangles. The cached
+ * origin is the build-time world translation; layer roots subsequently move only vertically.
+ *
+ * @type {number}
+ */
 export const CELL = 8;

package/src/globals/Compass.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for the compass camera handler constructor.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const Compass = { value: undefined };

package/src/globals/ContainerResize.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for the container resize camera handler constructor.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const ContainerResize = { value: undefined };

package/src/globals/HEIGHT.js

@@ -1 +1,6 @@
+/**
+ * Height over which model terrain-conformance weight falls to zero.
+ *
+ * @type {number}
+ */
 export const HEIGHT = 8;

package/src/globals/L.js

@@ -1 +1,6 @@
-export const L = globalThis.L;
+/**
+ * Leaflet namespace supplied by the host environment.
+ *
+ * @type {Object}
+ */
+export const L = globalThis.L;

package/src/globals/PitchDrag.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for the pitch drag camera handler constructor.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const PitchDrag = { value: undefined };

package/src/globals/README.md

@@ -0,0 +1,28 @@
+# Shared globals
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Holds shared constants, reusable buffers and descriptors, queues and mutable
+holders. Each module owns a single shared binding; callers should respect whether
+its contents are reusable mutable scratch state or an immutable constant.
+
+## Shared is not per-layer
+
+```mermaid
+flowchart LR
+  Globals["Shared module bindings"] --> Constants["Constants / saved methods"]
+  Globals --> Scratch["Reusable arrays / descriptors"]
+  Globals --> Queues["Shared queues / mutable holders"]
+  Queues --> Frames["Coalesced scene frames"]
+  Objects["Map / layer / mesh"] --> WeakMaps["Per-object WeakMaps"]
+```
+
+Scratch values are reused: do not retain them as private layer state. Clear
+temporary resource references as existing consumers do. Per-object lifetime
+belongs in [weakmaps](../weakmaps/README.md).
+
+- [L.js](./L.js): host Leaflet namespace.
+- [geometryWorkerUrl.js](./geometryWorkerUrl.js): default worker URL.
+- [pendingUpdates.js](./pendingUpdates.js): queued scene updates.
+
+Related: [weakmaps](../weakmaps/README.md), [scene](../scene/README.md).

package/src/globals/ShiftRotate.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for the shift-key rotation handler constructor.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const ShiftRotate = { value: undefined };

package/src/globals/TILE_RADIUS.js

@@ -1 +1,6 @@
+/**
+ * Maximum raster tile selection radius around the map center.
+ *
+ * @type {number}
+ */
 export const TILE_RADIUS = 6;

package/src/globals/TILE_SIZE.js

@@ -1 +1,6 @@
+/**
+ * Raster tile width and height in pixels.
+ *
+ * @type {number}
+ */
 export const TILE_SIZE = 256;

package/src/globals/TouchMode.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for the camera touch-mode handler constructor.
+ *
+ * @type {{value: Function|undefined}}
+ */
 export const TouchMode = { value: undefined };

package/src/globals/alphaBlend.js

@@ -1,3 +1,8 @@
+/**
+ * WebGPU blend configuration for transparent material color and alpha.
+ *
+ * @type {Object}
+ */
 export const alphaBlend = {
   color: {
     srcFactor: 'src-alpha',

package/src/globals/archiveDecoder.js

@@ -1 +1,6 @@
+/**
+ * Text decoder reused for archive source data.
+ *
+ * @type {TextDecoder}
+ */
 export const archiveDecoder = new TextDecoder();