leaflet-city-mapper 0.0.8 → 0.1.0

package/src/rendering/nativeStrokeExpansion.js

@@ -1,3 +1,10 @@
+/**
+ * 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,8 +1,14 @@
-import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
+import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { frameBuffer } from '../globals/frameBuffer.js';
 import { destroyTexture } from '../textures/destroyTexture.js';
 
+/**
+ * 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).

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,3 +1,13 @@
+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;
@@ -24,4 +34,3 @@ export function prepareMeshUniforms(renderer, mesh) {
   data[base + 41] = data[base + 42] = data[base + 43] = 0;
   return offset;
 }
-import { prepareMeshCutout } from '../materials/prepareMeshCutout.js';

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

@@ -2,9 +2,18 @@ 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;

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,12 +1,18 @@
-import { kindByLayer } from '../weakmaps/kindByLayer.js';
-
-
+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';
 
+/**
+ * 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);

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) {

package/src/scene/callLayer.js

@@ -1,7 +1,5 @@
-import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
-import { kindByLayer } from '../weakmaps/kindByLayer.js';
-
-
+import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
+import { kindByLayer } from '../weakmaps/kindByLayer.js';
 import { setGeoJSONData } from '../sources/setGeoJSONData.js';
 import { getHeader } from '../archives/getHeader.js';
 import { getZxy } from '../archives/getZxy.js';
@@ -10,7 +8,15 @@ import { isLoading } from '../raster/isRasterLoading.js';
 import { setPMTileOpacity } from '../raster/setPMTileOpacity.js';
 import { setPMTileZIndex } from '../raster/setPMTileZIndex.js';
 
-
+/**
+ * Dispatch supported source methods or invoke the layer's own method.
+ *
+ * @param {string} method Method name.
+ * @param {L.Layer} layer Target layer.
+ * @param {...*} args Arguments forwarded to the method.
+ *
+ * @returns {*} Result of the selected method.
+ */
 export function callLayer(method, layer, ...args) {
 
   if (method === 'setData' && geojsonByLayer.get(layer)) return setGeoJSONData(layer, ...args);

package/src/scene/cancelUpdate.js

@@ -1,9 +1,11 @@
 import { frameByLayer } from '../weakmaps/frameByLayer.js';
-
 import { pendingUpdates } from '../globals/pendingUpdates.js';
 
-
-
+/**
+ * Remove a layer's pending update and cancel the frame when no updates remain.
+ *
+ * @param {L.Layer} layer Layer whose update should be cancelled.
+ */
 export function cancelUpdate(layer) {
   const frame = frameByLayer.get(layer);
   pendingUpdates.delete(layer);

package/src/scene/createLayer.js

@@ -1,7 +1,13 @@
-import { L } from '../globals/L.js';
+import { L } from '../globals/L.js';
 import { sceneEmptyOptions } from '../globals/sceneEmptyOptions.js';
 
-
+/**
+ * Create a Leaflet layer with the given options.
+ *
+ * @param {Object} [options] Layer options.
+ *
+ * @returns {L.Layer} New layer.
+ */
 export function createLayer(options = sceneEmptyOptions) {
   return /* alloc */ new L.Layer(options);
 }

package/src/scene/createSceneNode.js

@@ -1,4 +1,8 @@
-/** A fresh, empty scene-graph node. */
+/**
+ * Create a fresh, empty scene-graph node.
+ *
+ * @returns {Object} Node with identity transform and no children.
+ */
 export function emptyNode() {
   return /* alloc */ {
     position: /* alloc */ [0, 0, 0],

package/src/scene/emptyEvents.js

@@ -1,3 +1,8 @@
+/**
+ * Create an empty map event handler collection.
+ *
+ * @returns {Object} Empty event handler collection.
+ */
 export function emptyEvents() {
   return /* alloc */ {};
 }

package/src/scene/failAttachment.js

@@ -1,10 +1,16 @@
 import { rendererReadyByLayer } from '../weakmaps/rendererReadyByLayer.js';
-
 import { renderers } from '../weakmaps/renderers.js';
-
-
 import { showWebGPUWarning } from '../gpu/showWebGPUWarning.js';
 
+/**
+ * Report renderer initialization failure, reject readiness and clear the shared renderer.
+ *
+ * @param {Error} error Initialization error.
+ * @param {L.Layer} layer Shared renderer owner.
+ * @param {L.Map} map Map whose renderer failed.
+ *
+ * @throws {Error} The supplied error.
+ */
 export function failAttachment(error, layer, map) {
   showWebGPUWarning(map);
   rendererReadyByLayer.get(layer).reject(error);

package/src/scene/get3DEvents.js

@@ -1,11 +1,15 @@
 import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
 import { urlByLayer } from '../weakmaps/urlByLayer.js';
-
-
-
 import { updateArea } from '../sources/updateArea.js';
 import { onTerrainChange } from '../terrain/onTerrainChange.js';
 
+/**
+ * Create map event handlers for a 3D source layer.
+ *
+ * @param {L.Layer} layer Layer whose source determines the events.
+ *
+ * @returns {Object} Map event names and handlers.
+ */
 export function get3DEvents(layer) {
   const events = /* alloc */ {};
   if (urlByLayer.get(layer)) {

package/src/scene/getLocation.js

@@ -1,8 +1,12 @@
-import { locationByLayer } from '../weakmaps/locationByLayer.js';
-
-
-
+import { locationByLayer } from '../weakmaps/locationByLayer.js';
 
+/**
+ * Read the geographic origin stored for a layer.
+ *
+ * @param {L.Layer} layer Layer to inspect.
+ *
+ * @returns {L.LatLng|undefined} Stored origin, if initialized.
+ */
 export function getLocation(layer) {
   return locationByLayer.get(layer);
 }

package/src/scene/init3D.js

@@ -10,15 +10,18 @@ import { modelUrlByLayer } from '../weakmaps/modelUrlByLayer.js';
 import { readyByLayer } from '../weakmaps/readyByLayer.js';
 import { state3dByLayer } from '../weakmaps/state3dByLayer.js';
 import { urlByLayer } from '../weakmaps/urlByLayer.js';
-
 import { L } from '../globals/L.js';
 import { sceneEmptyOptions } from '../globals/sceneEmptyOptions.js';
-
-
 import { ready3D } from './ready3D.js';
 import { noOperation } from '../utils/noOperation.js';
 import { updateLayerCount } from '../layer-controls/updateLayerCount.js';
 
+/**
+ * Initialize 3D layer state, source settings and asynchronous readiness.
+ *
+ * @param {L.Layer} layer Layer to initialize.
+ * @param {Object} [options] 3D layer and source options.
+ */
 export function init3D(layer, options = sceneEmptyOptions) {
   state3dByLayer.set(layer, true);
   L.Util.setOptions(layer, /* alloc */ { ariaLabel: '3D scene', ...options });

package/src/scene/initializeLayer.js

@@ -1,9 +1,16 @@
 import { kindByLayer } from '../weakmaps/kindByLayer.js';
 import { readyByLayer } from '../weakmaps/readyByLayer.js';
-
 import { reportError } from './reportLayerError.js';
 
-
+/**
+ * Initialize a queued layer and reattach it to its map if necessary.
+ *
+ * @param {Object} task Queued initialization, settings and readiness state.
+ *
+ * @returns {L.Layer|Promise} Initialized layer or its readiness promise.
+ *
+ * @throws {Error} If initialization or reattachment fails.
+ */
 export function initializeLayer(task) {
   const { layer, ready } = task;
   if (task.error) {

package/src/scene/initializerFor.js

@@ -4,6 +4,14 @@ import { initTraffic } from '../traffic/initTraffic.js';
 import { initCog } from '../cog/initCog.js';
 import { sceneEmptyOptions } from '../globals/sceneEmptyOptions.js';
 
+/**
+ * Select the initializer for a non-vector source type.
+ *
+ * @param {string} type Source type.
+ * @param {Object} [options] Source options used to distinguish COG from archive rasters.
+ *
+ * @returns {Function|null} Initializer, or null for an unknown type.
+ */
 export function initializerFor(type, options = sceneEmptyOptions) {
   switch (type) {
     case 'raster': return options.asset !== undefined || /\.tiff?(?:[?#]|$)/i.test(options.url)

package/src/scene/isNativeLayer.js

@@ -1,7 +1,13 @@
-import { state3dByLayer } from '../weakmaps/state3dByLayer.js';
-
+import { state3dByLayer } from '../weakmaps/state3dByLayer.js';
 import { L } from '../globals/L.js';
 
+/**
+ * Identify supported native Leaflet layers that are not already 3D layers.
+ *
+ * @param {L.Layer} layer Layer to inspect.
+ *
+ * @returns {boolean} Whether the layer is supported as native content.
+ */
 export function isNativeLayer(layer) {
   return !state3dByLayer.get(layer) && (
     layer instanceof L.GridLayer ||

package/src/scene/layerInitialize.js

@@ -2,15 +2,11 @@ import { kindByLayer } from '../weakmaps/kindByLayer.js';
 import { readyByLayer } from '../weakmaps/readyByLayer.js';
 import { sceneLayers } from '../weakmaps/sceneLayers.js';
 import { typeByLayer } from '../weakmaps/typeByLayer.js';
-
 import { L } from '../globals/L.js';
 import { sceneEmptyOptions } from '../globals/sceneEmptyOptions.js';
 import { layerProto } from '../globals/layerProto.js';
 import { pendingInitializations } from '../globals/pendingInitializations.js';
 import { loading } from '../globals/loading.js';
-
-
-
 import { init3D } from './init3D.js';
 import { initializeGeoJSON } from '../sources/initializeGeoJSON.js';
 import { isVectorTileSource } from '../sources/isVectorTileSource.js';
@@ -19,6 +15,13 @@ import { noOperation } from '../utils/noOperation.js';
 import { resolveNextInitialization } from './resolveNextInitialization.js';
 import { initializeLayer } from './initializeLayer.js';
 
+/**
+ * Initialize this Leaflet layer, selecting or scheduling its configured source.
+ *
+ * @param {Object} [options] Layer options, optionally containing a source.
+ *
+ * @returns {*} Original Leaflet initializer result when delegated.
+ */
 export function layerInitialize(options = sceneEmptyOptions) {
   if (!sceneLayers.has(this)) {
     sceneLayers.add(this);

package/src/scene/onAdd3DLayer.js

@@ -6,16 +6,18 @@ import { pointerEventsByLayer } from '../weakmaps/pointerEventsByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { tooltipByLayer } from '../weakmaps/tooltipByLayer.js';
 import { urlByLayer } from '../weakmaps/urlByLayer.js';
-
 import { L } from '../globals/L.js';
-
-
 import { pointerMove } from '../picking/pointerMove.js';
 import { pointerClick } from '../picking/pointerClick.js';
 import { pointerLeave } from '../picking/pointerLeave.js';
 import { attachLayer } from './attachLayer.js';
 
-/** Attach interaction immediately; initialization may finish before or after onAdd. */
+/**
+ * Attach interaction immediately; initialization may finish before or after onAdd.
+ *
+ * @param {L.Layer} layer 3D layer being added.
+ * @param {L.Map} map Map receiving the layer.
+ */
 export function onAdd3DLayer(layer, map) {
   if (!locationByLayer.get(layer)) {
     const center = map.getCenter();

package/src/scene/onMapChange.js

@@ -1,15 +1,10 @@
 import { queuedByLayer } from '../weakmaps/queuedByLayer.js';
-
 import { pendingMapChanges } from '../globals/pendingMapChanges.js';
-
-
 import { update } from './scheduleSceneUpdate.js';
 import { render } from "../rendering/render.js";
-
 import { renderPendingMapChange } from './renderPendingMapChange.js';
 
 /** Map movement: render within the frame of Leaflet's CSS transforms, coalescing same-tick events. */
-
 export function onMapChange() {
   const layer = this;
   if (queuedByLayer.get(layer)) return;

package/src/scene/onRemove3DLayer.js

@@ -12,13 +12,9 @@ import { sceneFields } from '../weakmaps/sceneFields.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
 import { tooltipByLayer } from '../weakmaps/tooltipByLayer.js';
 import { urlByLayer } from '../weakmaps/urlByLayer.js';
-
 import { L } from '../globals/L.js';
 import { sceneTransferFields } from '../globals/sceneTransferFields.js';
 import { renderers } from '../weakmaps/renderers.js';
-
-
-
 import * as endZoom from '../animations/endZoom.js';
 import * as onMapChange from './onMapChange.js';
 import * as onPointerLeave from '../picking/onPointerLeave.js';
@@ -31,7 +27,12 @@ import { cancelUpdate } from './cancelUpdate.js';
 import { update } from './scheduleSceneUpdate.js';
 import { releaseSharedScene } from './releaseSharedScene.js';
 
-/** Release source meshes/UI; retain manually added objects and model CPU data. */
+/**
+ * Release source meshes and UI, retaining manually added objects and model CPU data.
+ *
+ * @param {L.Layer} layer 3D layer being removed.
+ * @param {L.Map} map Map containing the layer.
+ */
 export function onRemove3DLayer(layer, map) {
   addedByLayer.set(layer, Promise.withResolvers());
   if (containerByLayer.get(layer)) {

package/src/scene/ready3D.js

@@ -7,15 +7,21 @@ import { raycasterByLayer } from '../weakmaps/raycasterByLayer.js';
 import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
 import { urlByLayer } from '../weakmaps/urlByLayer.js';
-
-
-
 import { emptyNode } from './createSceneNode.js';
 import { getHeader } from '../archives/getHeader.js';
 import { attach } from './attachSharedScene.js';
 import { loadModel } from '../models/loadModel.js';
 import { update } from './scheduleSceneUpdate.js';
 
+/**
+ * Initialize a 3D scene root and source, attach if mapped, and emit readiness.
+ *
+ * @param {L.Layer} layer 3D layer to initialize.
+ *
+ * @returns {Promise<L.Layer>} The initialized layer.
+ *
+ * @throws {Error} If initialization fails, after emitting an error event.
+ */
 export async function ready3D(layer) {
   try {
     rootByLayer.set(layer, emptyNode());

package/src/scene/releaseSharedScene.js

@@ -4,13 +4,17 @@ import { sceneFields } from '../weakmaps/sceneFields.js';
 import { zoomTransitionsByLayer } from '../weakmaps/zoomTransitionsByLayer.js';
 import { zoomViewByLayer } from '../weakmaps/zoomViewByLayer.js';
 import { cameraViewByMap } from '../weakmaps/cameraViewByMap.js';
-
-
 import { renderers } from '../weakmaps/renderers.js';
 import { sceneCleanupFields } from '../globals/sceneCleanupFields.js';
 import { destroyTexture } from '../textures/destroyTexture.js';
 import { releaseRenderer } from '../gpu/releaseRenderer.js';
 
+/**
+ * Release the map's shared renderer, roof texture and scene lifecycle state.
+ *
+ * @param {L.Layer} layer Shared scene owner.
+ * @param {L.Map} map Map owning the scene.
+ */
 export function releaseSharedScene(layer, map) {
   if (roofRasterByLayer.get(layer)) destroyTexture(layer, roofRasterByLayer.get(layer).texture.texture);
   roofRasterByLayer.set(layer, null);