leaflet-city-mapper 0.0.9 → 0.1.1

package/src/rendering/compareMeshes.js

@@ -1,3 +1,13 @@
+import { compareMeshDepth } from './compareMeshDepth.js';
+
+/**
+ * Sort ground first, then opaque and transparent meshes with their depth ordering.
+ *
+ * @param {Object} a First mesh.
+ * @param {Object} b Second mesh.
+ *
+ * @returns {number} Sort comparison.
+ */
 export function compareMeshes(a, b) {
   return Number(Boolean(b.ground)) - Number(Boolean(a.ground)) ||
     (a.ground && b.ground ? (a.renderOrder || 0) - (b.renderOrder || 0) ||
@@ -5,4 +15,3 @@ export function compareMeshes(a, b) {
     Number(a.program.transparent) - Number(b.program.transparent) ||
     compareMeshDepth(a, b);
 }
-import { compareMeshDepth } from './compareMeshDepth.js';

package/src/rendering/createMesh.js

@@ -1,12 +1,8 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
 import { defaultMaterial } from '../globals/defaultMaterial.js';
 import { meshBuffer } from '../globals/meshBuffer.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';
@@ -16,8 +12,15 @@ import { update } from '../scene/scheduleSceneUpdate.js';
  * Add a non-indexed, vertex-coloured mesh from flat vec3 arrays `{ position, normal, color }` in layer-local metres.
  * `usage` adds GPUBufferUsage flags to the vertex buffers (e.g. STORAGE for compute passes).
  * A supplied `program` shares compiled shaders and pipelines across compatible meshes.
+ *
+ * @param {L.Layer} layer Rendering layer and mesh owner.
+ * @param {Object} data Flat vertex attribute arrays.
+ * @param {Object} [material] Material options for a new program.
+ * @param {number} [usage] Additional vertex buffer usage flags.
+ * @param {Object} [program] Existing program to share.
+ *
+ * @returns {Object} Created scene mesh.
  */
-
 export function createMesh(layer, data, material = defaultMaterial, usage = 0, program) {
   const { device } = rendererByLayer.get(layer), attributes = /* alloc */ {};
   let name, values, array, size, buffer;

package/src/rendering/disposeMesh.js

@@ -1,6 +1,12 @@
 import { setParent } from '../scene/setParent.js';
 import { update } from '../scene/scheduleSceneUpdate.js';
 
+/**
+ * Detach a mesh and destroy its geometry buffers.
+ *
+ * @param {L.Layer} layer Layer to refresh.
+ * @param {Object} mesh Mesh to dispose, if present.
+ */
 export function disposeMesh(layer, mesh) {
   if (!mesh) {
     return;

package/src/rendering/drawGeometry.js

@@ -1,11 +1,18 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { meshOffsets } from '../globals/meshOffsets.js';
 import { drawPipeline } from './drawPipeline.js';
 import { prepareMeshUniforms } from './prepareMeshUniforms.js';
 import { prepareMeshTextures } from '../textures/prepareMeshTextures.js';
 
-/** Upload retained CPU data and draw one mesh in the active WebGPU render pass. */
+/**
+ * Upload modified CPU attributes and draw one mesh in the active WebGPU render pass.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {Object} mesh Mesh to draw.
+ * @param {GPURenderPassEncoder} pass Active render pass.
+ * @param {GPUCullMode} cullMode Pipeline face-culling mode.
+ * @param {GPUFrontFace} frontFace Pipeline front-face winding.
+ */
 export function drawGeometry(layer, mesh, pass, cullMode, frontFace) {
   const { geometry } = mesh, { attributes, drawRange } = geometry;
   const renderer = rendererByLayer.get(layer);

package/src/rendering/drawPipeline.js

@@ -1,34 +1,44 @@
-import { meshPipeline } from '../globals/meshPipeline.js';
-import { alphaBlend } from '../globals/alphaBlend.js';
-
-export function drawPipeline(renderer, mesh, cullMode, frontFace) {
-  const { program } = mesh;
-  // Mixed-LOD imagery composites coarse-to-fine; its depth still occludes later 3D objects.
-  // ponytail: self-occlusion during LOD blending needs separate per-LOD depth passes.
-  const depthCompare = program.depthTest === false || (mesh.ground && renderer.groundOverlap)
-    ? 'always' : 'less-equal';
-  const pipelineKey = `${cullMode}:${frontFace}:${depthCompare}`;
-  let pipeline = program.pipelineCache.get(pipelineKey);
-  if (!pipeline) {
-    pipeline = renderer.device.createRenderPipeline((
-      meshPipeline.layout = program.pipelineLayout,
-      meshPipeline.vertex.module = program.vertex,
-      meshPipeline.vertex.buffers = program.vertexBuffers,
-      meshPipeline.fragment.module = program.fragment,
-      meshPipeline.fragment.targets[0].format = renderer.format,
-      meshPipeline.fragment.targets[0].blend = program.transparent ? alphaBlend : undefined,
-      meshPipeline.fragment.targets[0].writeMask = GPUColorWrite.ALL,
-      meshPipeline.primitive.cullMode = cullMode,
-      meshPipeline.primitive.frontFace = frontFace,
-      meshPipeline.depthStencil.depthWriteEnabled = program.depthWrite,
-      meshPipeline.depthStencil.depthCompare = depthCompare,
-      meshPipeline
-    ));
-    meshPipeline.layout = null;
-    meshPipeline.vertex.module = null;
-    meshPipeline.vertex.buffers = null;
-    meshPipeline.fragment.module = null;
-    program.pipelineCache.set(pipelineKey, pipeline);
-  }
-  return pipeline;
-}
+import { meshPipeline } from '../globals/meshPipeline.js';
+import { alphaBlend } from '../globals/alphaBlend.js';
+
+/**
+ * Get or create a cached render pipeline for a mesh and its face/depth settings.
+ *
+ * @param {Object} renderer Renderer providing the device and color format.
+ * @param {Object} mesh Mesh providing the program and ground flag.
+ * @param {GPUCullMode} cullMode Face-culling mode.
+ * @param {GPUFrontFace} frontFace Front-face winding.
+ *
+ * @returns {GPURenderPipeline} Cached or newly created pipeline.
+ */
+export function drawPipeline(renderer, mesh, cullMode, frontFace) {
+  const { program } = mesh;
+  // Mixed-LOD imagery composites coarse-to-fine; its depth still occludes later 3D objects.
+  // ponytail: self-occlusion during LOD blending needs separate per-LOD depth passes.
+  const depthCompare = program.depthTest === false || (mesh.ground && renderer.groundOverlap)
+    ? 'always' : 'less-equal';
+  const pipelineKey = `${cullMode}:${frontFace}:${depthCompare}`;
+  let pipeline = program.pipelineCache.get(pipelineKey);
+  if (!pipeline) {
+    pipeline = renderer.device.createRenderPipeline((
+      meshPipeline.layout = program.pipelineLayout,
+      meshPipeline.vertex.module = program.vertex,
+      meshPipeline.vertex.buffers = program.vertexBuffers,
+      meshPipeline.fragment.module = program.fragment,
+      meshPipeline.fragment.targets[0].format = renderer.format,
+      meshPipeline.fragment.targets[0].blend = program.transparent ? alphaBlend : undefined,
+      meshPipeline.fragment.targets[0].writeMask = GPUColorWrite.ALL,
+      meshPipeline.primitive.cullMode = cullMode,
+      meshPipeline.primitive.frontFace = frontFace,
+      meshPipeline.depthStencil.depthWriteEnabled = program.depthWrite,
+      meshPipeline.depthStencil.depthCompare = depthCompare,
+      meshPipeline
+    ));
+    meshPipeline.layout = null;
+    meshPipeline.vertex.module = null;
+    meshPipeline.vertex.buffers = null;
+    meshPipeline.fragment.module = null;
+    program.pipelineCache.set(pipelineKey, pipeline);
+  }
+  return pipeline;
+}

package/src/rendering/drawSceneMeshes.js

@@ -1,11 +1,17 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { roofRasterByLayer } from '../weakmaps/roofRasterByLayer.js';
-
 import { scenePass } from '../globals/scenePass.js';
-
-
 import { drawGeometry } from './drawGeometry.js';
 
+/**
+ * Encode the scene render pass, including both faces of double-sided transparent meshes.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {GPUCommandEncoder} encoder Encoder receiving the pass.
+ * @param {Array<Object>} meshes Sorted meshes to draw.
+ *
+ * @throws {Error} If a mesh has a singular or non-finite world transform.
+ */
 export function drawSceneMeshes(layer, encoder, meshes) {
   const renderer = rendererByLayer.get(layer);
   const pass = encoder.beginRenderPass((

package/src/rendering/nativeStrokeExpansion.js

@@ -1,4 +1,11 @@
-export function nativeStrokeExpansion(mesh) {
-  const strokeScale = mesh.program?.uniforms?.strokeScale?.value ?? 1;
-  return Math.max(0, strokeScale - 1) * (mesh.geometry.nativeStrokeRadius || 0);
-}
+/**
+ * Calculate the extra local-space culling radius needed for a scaled native stroke.
+ *
+ * @param {Object} mesh Mesh containing stroke uniforms and geometry.
+ *
+ * @returns {number} Additional bounding radius.
+ */
+export function nativeStrokeExpansion(mesh) {
+  const strokeScale = mesh.program?.uniforms?.strokeScale?.value ?? 1;
+  return Math.max(0, strokeScale - 1) * (mesh.geometry.nativeStrokeRadius || 0);
+}

package/src/rendering/prepareFrameBuffer.js

@@ -1,18 +1,24 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
+import { frameBuffer } from '../globals/frameBuffer.js';
+import { destroyTexture } from '../textures/destroyTexture.js';
 
-import { frameBuffer } from '../globals/frameBuffer.js';
-import { destroyTexture } from '../textures/destroyTexture.js';
-
-export function prepareFrameBuffer(layer, meshes, shadowMeshes) {
-  const renderer = rendererByLayer.get(layer);
-  // Slot 0 holds the camera; 256-byte mesh slots follow (double-sided meshes use two).
-  if (!renderer.uniformBuffer || renderer.uniformBuffer.size < (meshes.length * 2 + shadowMeshes.length + 1) * 256) {
-    if (renderer.uniformBuffer) destroyTexture(layer, renderer.uniformBuffer);
-    renderer.uniformBuffer = renderer.device.createBuffer((
-      frameBuffer.size = Math.max(64, meshes.length * 4 + shadowMeshes.length * 2) * 256,
-      frameBuffer.usage = GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-      frameBuffer
-    ));
-    renderer.uniformData = /* alloc */ new Float32Array(renderer.uniformBuffer.size / 4);
-  }
-}
+/**
+ * Ensure the renderer has uniform-buffer capacity for this frame's meshes and shadows.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {Array<Object>} meshes Meshes to render.
+ * @param {Array<Object>} shadowMeshes Shadow-casting meshes.
+ */
+export function prepareFrameBuffer(layer, meshes, shadowMeshes) {
+  const renderer = rendererByLayer.get(layer);
+  // Slot 0 holds the camera; 256-byte mesh slots follow (double-sided meshes use two).
+  if (!renderer.uniformBuffer || renderer.uniformBuffer.size < (meshes.length * 2 + shadowMeshes.length + 1) * 256) {
+    if (renderer.uniformBuffer) destroyTexture(layer, renderer.uniformBuffer);
+    renderer.uniformBuffer = renderer.device.createBuffer((
+      frameBuffer.size = Math.max(64, meshes.length * 4 + shadowMeshes.length * 2) * 256,
+      frameBuffer.usage = GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+      frameBuffer
+    ));
+    renderer.uniformData = /* alloc */ new Float32Array(renderer.uniformBuffer.size / 4);
+  }
+}

package/src/rendering/prepareFrameMeshes.js

@@ -1,12 +1,19 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { shadowMeshesByLayer } from '../weakmaps/shadowMeshesByLayer.js';
 import { visibleMeshesByLayer } from '../weakmaps/visibleMeshesByLayer.js';
-
-
-
 import { compareMeshes } from './compareMeshes.js';
 import { revealRoofMesh } from './revealRoofMesh.js';
 
+/**
+ * Prepare and sort visible meshes, update fades and filter the shadow list.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {Array<L.Layer>} rasters Raster layers used for roof coverage.
+ * @param {number} now Current frame time in milliseconds.
+ * @param {Array<Object>} meshes Destination for meshes to draw.
+ *
+ * @returns {boolean} Whether a mesh is still fading in.
+ */
 export function prepareFrameMeshes(layer, rasters, now, meshes) {
   const candidates = visibleMeshesByLayer.get(layer), shadowMeshes = shadowMeshesByLayer.get(layer), renderer = rendererByLayer.get(layer);
   let appearing = false;

package/src/rendering/prepareFrameUniforms.js

@@ -1,12 +1,17 @@
 import { cameraByLayer } from '../weakmaps/cameraByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { roofRasterByLayer } from '../weakmaps/roofRasterByLayer.js';
-
-
-
 import { prepareFrameBuffer } from './prepareFrameBuffer.js';
 import { updatePointLights } from '../lighting/updatePointLights.js';
 
+/**
+ * Prepare camera, roof and lighting uniforms and reserve space for per-mesh uniforms.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {Array<Object>} meshes Meshes to render.
+ * @param {Array<Object>} shadowMeshes Shadow-casting meshes.
+ * @param {Object} sunlight Current sunlight state, if available.
+ */
 export function prepareFrameUniforms(layer, meshes, shadowMeshes, sunlight) {
   const renderer = rendererByLayer.get(layer), camera = cameraByLayer.get(layer);
   const view = camera.viewMatrix, direction = sunlight?.direction;

package/src/rendering/prepareMeshUniforms.js

@@ -1,27 +1,36 @@
-export function prepareMeshUniforms(renderer, mesh) {
-  const uniforms = mesh.program.uniforms;
-  const offset = renderer.uniformSlot++ * 256;
-  const data = renderer.uniformData, base = offset / 4;
-  data.set(mesh.worldMatrix, base);
-  data.set(uniforms.baseColor.value, base + 16);
-  data[base + 19] = 1;
-  data[base + 20] = uniforms.metallic.value;
-  data[base + 21] = uniforms.roughness.value;
-  data[base + 22] = uniforms.opacity.value * (mesh.ground ? mesh._appearance ?? 1 : 1);
-  data[base + 23] = uniforms.alphaCutoff.value;
-  data.set(uniforms.emissive.value, base + 24);
-  data[base + 27] = uniforms.occlusionStrength.value;
-  data[base + 28] = mesh.terrain?.[0] ?? 0;
-  data[base + 29] = mesh.terrain?.[1] ?? 0;
-  data[base + 30] = mesh.terrain?.[2] ?? 0;
-  data[base + 31] = mesh.terrain?.[3] ?? 0;
-  data[base + 32] = mesh.highlight?.[0] ?? 0;
-  data[base + 33] = mesh.highlight?.[1] ?? 0;
-  data[base + 34] = mesh.program.nightSparkle ? data[55] : 0;
-  data[base + 35] = mesh.ground ? 1 : mesh._appearance ?? 1;
-  prepareMeshCutout(renderer, mesh, base);
-  data[base + 40] = uniforms.strokeScale?.value ?? 1;
-  data[base + 41] = data[base + 42] = data[base + 43] = 0;
-  return offset;
-}
-import { prepareMeshCutout } from '../materials/prepareMeshCutout.js';
+import { prepareMeshCutout } from '../materials/prepareMeshCutout.js';
+
+/**
+ * Write a mesh's transforms and material values into the next frame uniform slot.
+ *
+ * @param {Object} renderer Renderer containing uniform data and slot state.
+ * @param {Object} mesh Mesh to prepare.
+ *
+ * @returns {number} Dynamic uniform buffer offset in bytes.
+ */
+export function prepareMeshUniforms(renderer, mesh) {
+  const uniforms = mesh.program.uniforms;
+  const offset = renderer.uniformSlot++ * 256;
+  const data = renderer.uniformData, base = offset / 4;
+  data.set(mesh.worldMatrix, base);
+  data.set(uniforms.baseColor.value, base + 16);
+  data[base + 19] = 1;
+  data[base + 20] = uniforms.metallic.value;
+  data[base + 21] = uniforms.roughness.value;
+  data[base + 22] = uniforms.opacity.value * (mesh.ground ? mesh._appearance ?? 1 : 1);
+  data[base + 23] = uniforms.alphaCutoff.value;
+  data.set(uniforms.emissive.value, base + 24);
+  data[base + 27] = uniforms.occlusionStrength.value;
+  data[base + 28] = mesh.terrain?.[0] ?? 0;
+  data[base + 29] = mesh.terrain?.[1] ?? 0;
+  data[base + 30] = mesh.terrain?.[2] ?? 0;
+  data[base + 31] = mesh.terrain?.[3] ?? 0;
+  data[base + 32] = mesh.highlight?.[0] ?? 0;
+  data[base + 33] = mesh.highlight?.[1] ?? 0;
+  data[base + 34] = mesh.program.nightSparkle ? data[55] : 0;
+  data[base + 35] = mesh.ground ? 1 : mesh._appearance ?? 1;
+  prepareMeshCutout(renderer, mesh, base);
+  data[base + 40] = uniforms.strokeScale?.value ?? 1;
+  data[base + 41] = data[base + 42] = data[base + 43] = 0;
+  return offset;
+}

package/src/rendering/render.js

@@ -5,12 +5,8 @@ import { shadowMeshesByLayer } from '../weakmaps/shadowMeshesByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
 import { wantedRasterTilesByLayer } from '../weakmaps/wantedRasterTilesByLayer.js';
 import { sunlightByMap } from '../weakmaps/sunlightByMap.js';
-
-
 import { frameCommands } from '../globals/frameCommands.js';
 import { nativeRenderByLayer } from '../weakmaps/nativeRenderByLayer.js';
-
-
 import { synchronizeZoomView } from '../animations/synchronizeZoomView.js';
 import { resizeRenderer } from './resizeRenderer.js';
 import { updateMapCamera } from '../camera/updateMapCamera.js';
@@ -30,8 +26,9 @@ import { beforeNativeRender } from '../native/beforeNativeRender.js';
  * Rendering owner: CSS pixels -> scene metres -> perspective camera.
  * Lights and transparent sort centers are converted into the current camera space.
  * Without raster tiles, logical map projection supplies the same static alignment.
+ *
+ * @param {L.Layer} layer Shared rendering layer.
  */
-
 export function render(layer) {
   cancelUpdate(layer);
   if (sharedByLayer.get(layer) !== layer || !rendererByLayer.get(layer)) return;

package/src/rendering/resizeRenderer.js

@@ -1,12 +1,15 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { sizeByLayer } from '../weakmaps/sizeByLayer.js';
-
 import { depthTexture as sharedDepthTexture } from '../globals/depthTexture.js';
 import { colorTexture as sharedColorTexture } from '../globals/colorTexture.js';
-
-
 import { destroyTexture } from '../textures/destroyTexture.js';
 
+/**
+ * Resize the renderer's canvas and recreate its color and depth textures when the map size changes.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {L.Point} size Viewport size in CSS pixels.
+ */
 export function resizeRenderer(layer, size) {
   const renderer = rendererByLayer.get(layer);
   if (!sizeByLayer.get(layer) || !sizeByLayer.get(layer).equals(size)) {

package/src/rendering/revealRoofMesh.js

@@ -1,34 +1,43 @@
-import { headerByLayer } from '../weakmaps/headerByLayer.js';
-import { loadingTilesByLayer } from '../weakmaps/loadingTilesByLayer.js';
-import { roofRasterByLayer } from '../weakmaps/roofRasterByLayer.js';
-import { walkByMap } from '../weakmaps/walkByMap.js';
-
-import { roofCoverage } from '../geometry/roofCoverage.js';
-
-export function revealRoofMesh(layer, mesh, rasters, now) {
-  let raster, loading;
-  if (mesh.program.uniforms.roofTexture && !rasters.length) mesh._roofRevealed = true;
-  if (mesh.program.uniforms.roofTexture && !mesh._roofRevealed && rasters.length) {
-    if (walkByMap.get(layer._map)?.control?._walk?.saved) {
-      mesh._roofRevealed = true;
-      mesh.fadeStart = now - (mesh.fadeDuration || 0);
-    }
-    if (mesh._roofCoverageSignature !== roofRasterByLayer.get(layer)?.signature) {
-      mesh._roofCoverageSignature = roofRasterByLayer.get(layer)?.signature;
-      mesh._roofCovered = roofCoverage(mesh, layer, rasters);
-    }
-    loading = false;
-    for (raster of rasters) {
-      if (!headerByLayer.get(raster) || loadingTilesByLayer.get(raster) > 0) {
-        loading = true;
-        break;
-      }
-    }
-    if (!mesh._roofRevealed && !mesh._roofCovered && loading) {
-      mesh._appearance = 0;
-      return false;
-    }
-    mesh._roofRevealed = true;
-  }
-  return true;
-}
+import { headerByLayer } from '../weakmaps/headerByLayer.js';
+import { loadingTilesByLayer } from '../weakmaps/loadingTilesByLayer.js';
+import { roofRasterByLayer } from '../weakmaps/roofRasterByLayer.js';
+import { walkByMap } from '../weakmaps/walkByMap.js';
+import { roofCoverage } from '../geometry/roofCoverage.js';
+
+/**
+ * Delay revealing a roof mesh while its uncovered raster imagery is still loading.
+ *
+ * @param {L.Layer} layer Rendering layer.
+ * @param {Object} mesh Roof or other mesh being considered.
+ * @param {Array<L.Layer>} rasters Raster layers used for roof coverage.
+ * @param {number} now Current frame time in milliseconds.
+ *
+ * @returns {boolean} Whether the mesh may be drawn.
+ */
+export function revealRoofMesh(layer, mesh, rasters, now) {
+  let raster, loading;
+  if (mesh.program.uniforms.roofTexture && !rasters.length) mesh._roofRevealed = true;
+  if (mesh.program.uniforms.roofTexture && !mesh._roofRevealed && rasters.length) {
+    if (walkByMap.get(layer._map)?.control?._walk?.saved) {
+      mesh._roofRevealed = true;
+      mesh.fadeStart = now - (mesh.fadeDuration || 0);
+    }
+    if (mesh._roofCoverageSignature !== roofRasterByLayer.get(layer)?.signature) {
+      mesh._roofCoverageSignature = roofRasterByLayer.get(layer)?.signature;
+      mesh._roofCovered = roofCoverage(mesh, layer, rasters);
+    }
+    loading = false;
+    for (raster of rasters) {
+      if (!headerByLayer.get(raster) || loadingTilesByLayer.get(raster) > 0) {
+        loading = true;
+        break;
+      }
+    }
+    if (!mesh._roofRevealed && !mesh._roofCovered && loading) {
+      mesh._appearance = 0;
+      return false;
+    }
+    mesh._roofRevealed = true;
+  }
+  return true;
+}

package/src/scene/README.md

@@ -0,0 +1,36 @@
+# Scene and layer lifecycle
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Routes layer source options to their implementations and manages attachment,
+shared renderer ownership, updates and scene graph nodes.
+
+## Layer lifecycle
+
+```mermaid
+flowchart TD
+  Layer["new L.Layer with source"] --> Route["layerInitialize"]
+  Route -->|"vector"| Vector{"Source shape"}
+  Vector --> Tiles["Vector tiles"]
+  Vector --> GeoJSON["GeoJSON"]
+  Vector --> ThreeD["3D / model"]
+  Route -->|"other types"| Init["initializerFor: raster / terrain / traffic"]
+  GeoJSON --> Ready["3D readiness + root"]
+  ThreeD --> Ready
+  Ready --> Attach["Attach to shared scene"]
+  Attach --> Update["Schedule frame"]
+  Attach --> Remove{"Remove layer"}
+  Remove -->|"owner with members"| Transfer["Transfer ownership"]
+  Remove -->|"last owner"| Release["Release renderer"]
+  Remove -->|"non-owner"| Detach["Detach root"]
+```
+
+Source settings are flattened; omitted types are inferred as described in
+[index.js](../index.js). Addition and readiness may occur in either order.
+The [removal path](./onRemove3DLayer.js) cancels areas before detaching.
+
+- [layerInitialize.js](./layerInitialize.js): choose vector handling or queue other source types.
+- [initializerFor.js](./initializerFor.js): select raster, terrain or traffic initialization.
+- [attachSharedScene.js](./attachSharedScene.js): attach a layer to a shared scene.
+
+Related: [sources](../sources/README.md), [gpu](../gpu/README.md), [weakmaps](../weakmaps/README.md).

package/src/scene/addRegisteredLayer.js

@@ -2,12 +2,8 @@ import { eventMapByLayer } from '../weakmaps/eventMapByLayer.js';
 import { eventsByLayer } from '../weakmaps/eventsByLayer.js';
 import { kindByLayer } from '../weakmaps/kindByLayer.js';
 import { state3dByLayer } from '../weakmaps/state3dByLayer.js';
-
 import { L } from '../globals/L.js';
 import { layerProto } from '../globals/layerProto.js';
-
-
-
 import { initNativeGPU } from '../native/initNativeGPU.js';
 import { removeLayerEvents } from './removeLayerEvents.js';
 import { addSceneLayer } from './addSceneLayer.js';
@@ -16,6 +12,11 @@ import { getRasterEvents } from '../raster/getRasterEvents.js';
 import { emptyEvents } from './emptyEvents.js';
 import { isNativeLayer } from './isNativeLayer.js';
 
+/**
+ * Handle layer addition, registering scene events or delegating to Leaflet as appropriate.
+ *
+ * @param {Object} event Leaflet layer-add event whose target is the map.
+ */
 export function layerLayerAdd(event) {
   const native = isNativeLayer(this);
   if (native) {

package/src/scene/addSceneLayer.js

@@ -1,18 +1,24 @@
 import { kindByLayer } from '../weakmaps/kindByLayer.js';
+import { onAdd3DLayer } from './onAdd3DLayer.js';
+import { onPMTileAdd } from '../raster/onPMTileAdd.js';
+import { onTerrainAdd } from '../terrain/onTerrainAdd.js';
+import { addRasterImage } from '../textures/attachRasterImage.js';
+import { addTimeLayer } from '../sunlight/addTimeLayer.js';
 
-
-import { onAdd3DLayer } from './onAdd3DLayer.js';
-import { onPMTileAdd } from '../raster/onPMTileAdd.js';
-import { onTerrainAdd } from '../terrain/onTerrainAdd.js';
-import { addRasterImage } from '../textures/attachRasterImage.js';
-import { addTimeLayer } from '../sunlight/addTimeLayer.js';
-
-export function addSceneLayer(layer, map) {
-  switch (kindByLayer.get(layer)) {
-    case '3d': return onAdd3DLayer(layer, map);
-    case 'raster': return onPMTileAdd(layer, map);
-    case 'terrain': return onTerrainAdd(layer, map);
-    case 'image': return addRasterImage.call(layer, map);
-    case 'time': return addTimeLayer.call(layer, map);
-  }
-}
+/**
+ * Dispatch layer attachment according to its registered scene kind.
+ *
+ * @param {L.Layer} layer Layer being added.
+ * @param {L.Map} map Map receiving the layer.
+ *
+ * @returns {*} Result of the selected add handler, if any.
+ */
+export function addSceneLayer(layer, map) {
+  switch (kindByLayer.get(layer)) {
+    case '3d': return onAdd3DLayer(layer, map);
+    case 'raster': return onPMTileAdd(layer, map);
+    case 'terrain': return onTerrainAdd(layer, map);
+    case 'image': return addRasterImage.call(layer, map);
+    case 'time': return addTimeLayer.call(layer, map);
+  }
+}

package/src/scene/attachLayer.js

@@ -1,9 +1,14 @@
 import { addedByLayer } from '../weakmaps/addedByLayer.js';
-
-
-
 import * as attach from './attachSharedScene.js';
 
+/**
+ * Attach a layer to the shared scene and report attachment errors.
+ *
+ * @param {L.Layer} layer Layer to attach.
+ * @param {L.Map} map Map containing the layer.
+ *
+ * @returns {Promise<void>} Completion of the attachment attempt.
+ */
 export async function attachLayer(layer, map) {
   try {
     await attach.attach(layer, map);

package/src/scene/attachSharedScene.js

@@ -11,7 +11,6 @@ import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
 import { sceneOriginByLayer } from '../weakmaps/sceneOriginByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
 import { terrainBaseYByLayer } from '../weakmaps/terrainBaseYByLayer.js';
-
 import { radians } from '../globals/radians.js';
 import { renderers } from '../weakmaps/renderers.js';
 import { setParent } from './setParent.js';
@@ -27,6 +26,12 @@ import { initializeSharedRenderer } from '../gpu/initializeSharedRenderer.js';
 /**
  * Join/create this map's shared scene and rebuild GPU objects if its context changed.
  * Buffer/program handles belong to one context; typed arrays and decoded images do not.
+ *
+ * @param {L.Layer} layer Layer to attach.
+ * @param {L.Map} map Map owning the shared scene.
+ *
+ * @returns {Promise<void>} Completion of scene attachment.
+ *
  * @private
  */
 export async function attach(layer, map) {