leaflet-city-mapper 0.0.9 → 0.1.0

package/libs/README.md

@@ -0,0 +1,18 @@
+# Example and compatibility helpers
+
+[Project README](../README.md) | [Examples](../examples/) | [Build guide](../build/README.md)
+
+```mermaid
+flowchart LR
+  Loader["Demo loader"] --> Leaflet["Leaflet"]
+  Loader --> OL["OpenLayers + compatibility bindings"]
+  Leaflet --> Plugin["City Mapper"]
+  OL --> Plugin
+  Plugin --> Lens["Optional raster lens control"]
+```
+
+[leaflet.js](./leaflet.js) is a demo loader, not required by applications.
+[openlayers-bindings.js](./openlayers-bindings.js) supplies Leaflet-compatible
+classes backed by OpenLayers; its minified bundle is generated by
+[build.js](../build/build.js). [leaflet-lens.js](./leaflet-lens.js) adds an
+optional control for comparing two raster layers.

package/libs/leaflet.js

@@ -11,7 +11,7 @@ const openlayers = new URLSearchParams(location.search).get('engine') === 'openl
 document.write((openlayers
   ? '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@10.6.1/ol.css">' +
     '<script src="https://cdn.jsdelivr.net/npm/ol@10.6.1/dist/ol.js"><\/script>' +
-    '<script src="https://unpkg.com/leaflet-city-mapper@0.0.9/libs/openlayers-bindings.min.js"><\/script>'
+    '<script src="https://unpkg.com/leaflet-city-mapper@0.1.0/libs/openlayers-bindings.min.js"><\/script>'
   : '<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9/dist/leaflet.css"><script src="https://unpkg.com/leaflet@1.9/dist/leaflet-src.js"><\/script>'));
 
 const engineStyle = document.createElement('style');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leaflet-city-mapper",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "description": "A small 3D rendering engine for leaflet",
   "type": "module",
   "main": "dist/leaflet-city-mapper.js",

package/src/README.md

@@ -0,0 +1,148 @@
+# Source guide
+
+[Project README](../README.md) | [Entry point](./index.js)
+
+Internal architecture and contributor navigation. For the public API, see the
+[project README](../README.md).
+
+## From a layer to a frame
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Layer as L.Layer / scene
+  participant Source as Source loader
+  participant Worker
+  participant Frame as Shared renderer
+  App->>Layer: new L.Layer({source})
+  App->>Layer: addTo(map)
+  Layer->>Frame: attach root / create renderer
+  Layer->>Source: request visible data
+  Source->>Worker: decode or assemble (where applicable)
+  Worker-->>Source: prepared data
+  Source->>Layer: attach result and schedule update
+  Layer->>Frame: render next frame
+```
+
+Not every source uses this exact worker path: vector tiles have their own
+loading and presentation lifecycle, and a native Leaflet layer is synchronized
+through [native](./native/README.md). See [scene](./scene/README.md) for source
+routing, shared ownership and removal.
+
+## Ownership and debugging
+
+[weakmaps](./weakmaps/README.md) holds per-object state;
+[globals](./globals/README.md) also contains shared scratch buffers and queues.
+On source failures, inspect the layer's `error` and `progress` events.
+
+## Where to start a change
+
+| Change | Follow the code | Existing scenarios |
+| --- | --- | --- |
+| Source routing or scene ownership | [scene](./scene/README.md) → relevant source guide → [workers](./workers/README.md) | [scene](../test/features/scene.feature), [workers](../test/features/workers.feature) |
+| GeoJSON extrusions or feature hits | [sources](./sources/README.md) → [geometry](./geometry/README.md) → [picking](./picking/README.md) | [geojson](../test/features/geojson.feature), [picking](../test/features/picking.feature) |
+| Tile formats or terrain | [archives](./archives/README.md) / [cog](./cog/README.md) → [raster](./raster/README.md) / [terrain](./terrain/README.md) | [pmtiles](../test/features/pmtiles.feature), [cog](../test/features/cog.feature), [terrain](../test/features/terrain.feature) |
+| Vector tile styles and labels | [mvt](./mvt/README.md) → [vector-style](./vector-style/README.md) → [vector-tiles](./vector-tiles/README.md) | [vector tiles](../test/features/vector-tiles.feature), [unit cases](../test/features/vector-tile-unit.feature) |
+| Camera or walking | [camera](./camera/README.md) / [controls](./controls/README.md) → [walk](./walk/README.md) / [collision](./collision/README.md) | [camera](../test/features/camera.feature), [walk](../test/features/walk.feature) |
+| GPU drawing or lighting | [rendering](./rendering/README.md) → [materials](./materials/README.md) / [shaders](./shaders/README.md) → [lighting](./lighting/README.md) / [shadows](./shadows/README.md) | [webgpu](../test/features/webgpu.feature), [night lights](../test/features/night-lights.feature), [sunlight](../test/features/sunlight.feature) |
+
+The [build guide](../README.md#build-guide) explains the normal build and test
+commands. The test runner builds and runs Cucumber with both Leaflet versions;
+the feature files above are useful starting points for finding behavior and
+regressions specific to a change.
+
+## Subsystem map
+
+This diagram is an overview, not an exhaustive dependency graph.
+
+```mermaid
+flowchart LR
+  Leaflet["Leaflet layer"] --> Scene["scene: source routing"]
+  Scene --> Sources["sources / vector-tiles"]
+  Scene --> Raster["raster / terrain"]
+  Sources --> Workers["workers: decoding and geometry"]
+  Raster --> Archives["archives / cog"]
+  Workers --> Geometry["geometry / models"]
+  Geometry --> Render["rendering / GPU"]
+  Raster --> Render
+  Native["native Leaflet layers"] --> Render
+  Camera["camera / controls"] --> Render
+```
+
+## Source layout
+
+```text
+src/
+  index.js           Public entry point and source registration
+  globals/           One shared constant or mutable cell per module
+  weakmaps/          One private WeakMap per map/layer state field
+  mvt/               PBF vector tile decoding and tessellation
+  vector-style/      Safe vector style parsing and expressions
+  vector-tiles/      Native vector tile lifecycle and worker preparation
+  camera/            Leaflet camera API and scene camera state
+  controls/          Compass, dragging, touch and resizing
+  core/              Leaflet hooks, camera-aware overlays and readiness
+  native/            Native Leaflet layers rendered through WebGPU
+  layer-controls/    Layer entry placement and progress indicators
+  scene/             Source routing, lifecycle and graph nodes
+  sources/           GeoJSON and streamed source loading and assembly
+  workers/           Geometry, MVT, COG and model tasks sharing one CDN-compatible worker
+  picking/           Raycasting, highlighting and feature interaction
+  rendering/         Frame stages, draw pipelines and mesh lifecycle
+  gpu/               Device initialization, renderer resources and diagnostics
+  materials/         Material programs, uniforms, glTF materials and cutouts
+  textures/          Image loading, texture upload/binding and roof atlases
+  animations/        Camera transitions, zoom synchronization and tile fading
+  shadows/           Directional shadow maps and cache
+  lighting/          Point lights and spatial light grids
+  shaders/           Material shader generation
+  geometry/          Mesh construction, bounds, grids, vectors and route geometry
+  projections/       Map, screen and local coordinate conversion
+  transforms/        Local/world matrices and glTF node transforms
+  triangulation/     Polygon triangulation and ring operations
+  collision/         Mesh intersection and collision queries
+  models/            glTF loading, decoding and scene assembly
+  archives/          PMTiles archive reading and decompression
+  cog/               Supported GeoTIFF directories, byte ranges and tile decoding
+  raster/            Raster tile loading, attachment and lifecycle
+  traffic/           Routes, scheduling, simulation, loading and rendering
+  vehicles/          Vehicle model geometry
+  terrain/           Terrain loading and sampling
+  astronomy/         Sun/moon position and observer/date validation
+  sunlight/          Sky, celestial display and time controls
+  walk/              First-person walking
+  colors/            Colour parsing, conversion, interpolation and formatting
+  utils/             Shared numeric and no-op helpers
+```
+
+## Layer lifecycle and data
+
+- [scene](./scene/README.md): routing, attachment and shared scene lifecycle.
+- [sources](./sources/README.md): GeoJSON and source area loading.
+- [archives](./archives/README.md), [cog](./cog/README.md), [raster](./raster/README.md), [terrain](./terrain/README.md): archived data, raster imagery and elevation.
+- [mvt](./mvt/README.md), [vector-style](./vector-style/README.md), [vector-tiles](./vector-tiles/README.md): vector tile decoding, styling and display.
+- [models](./models/README.md), [workers](./workers/README.md): glTF loading and background jobs.
+- [native](./native/README.md): GPU representation of native Leaflet layers.
+
+## Rendering and geometry
+
+- [gpu](./gpu/README.md), [rendering](./rendering/README.md), [materials](./materials/README.md), [shaders](./shaders/README.md), [textures](./textures/README.md): GPU resources and frame rendering.
+- [geometry](./geometry/README.md), [triangulation](./triangulation/README.md), [transforms](./transforms/README.md), [projections](./projections/README.md): mesh construction and coordinate transformations.
+- [lighting](./lighting/README.md), [shadows](./shadows/README.md), [colors](./colors/README.md): lighting, shadow maps and color conversion.
+- [picking](./picking/README.md), [collision](./collision/README.md): interaction and collision queries.
+
+## Map behavior
+
+- [core](./core/README.md), [camera](./camera/README.md), [controls](./controls/README.md), [animations](./animations/README.md): Leaflet integration and camera interactions.
+- [layer-controls](./layer-controls/README.md): layer control placement and status.
+- [astronomy](./astronomy/README.md), [sunlight](./sunlight/README.md): celestial positions and time controls.
+- [walk](./walk/README.md), [traffic](./traffic/README.md), [vehicles](./vehicles/README.md): walking, traffic simulation and model geometry.
+
+## Shared state and helpers
+
+- [globals](./globals/README.md): shared constants, descriptors and mutable cells.
+- [weakmaps](./weakmaps/README.md): private state associated with maps, layers and other objects.
+- [utils](./utils/README.md): small shared helpers.
+
+Each source directory has a README; the source documentation test checks this
+invariant for new directories as well.

package/src/animations/README.md

@@ -0,0 +1,30 @@
+# Animations
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Schedules camera transitions, zoom synchronization, marker panning and grid tile fades.
+Shared queues allow multiple layers or maps to use the same animation frame.
+
+## Timing and cancellation
+
+```mermaid
+flowchart LR
+  Camera["Camera target"] --> Cancel["Cancel previous animation"]
+  Cancel --> Motion{"Animate?"}
+  Motion -->|yes| Arc["Shortest bearing arc + frames"]
+  Motion -->|no / reduced motion| Direct["Apply target"]
+  Fade["Grid fade request"] --> Revision["Record layer revision"]
+  Revision --> Frame["Shared animation frame"]
+  Frame --> Current{"Revision current?"}
+  Current -->|yes| Opacity["Update tile opacity"]
+  Current -->|no| Ignore["Ignore stale entry"]
+```
+
+Zoom synchronization has its own intermediate view:
+[synchronizeZoomView.js](./synchronizeZoomView.js).
+
+- [mapAnimateCamera.js](./mapAnimateCamera.js): start a camera transition.
+- [runGridFades.js](./runGridFades.js): advance queued tile fades only for current revisions.
+- [synchronizeZoomView.js](./synchronizeZoomView.js): coordinate map zoom animations with the scene.
+
+Related: [camera](../camera/README.md), [core](../core/README.md), [rendering](../rendering/README.md).

package/src/animations/cancelCameraAnimation.js

@@ -1,11 +1,13 @@
-import { cameraAnimationByMap } from '../weakmaps/cameraAnimationByMap.js';
-import { cameraFrameByMap } from '../weakmaps/cameraFrameByMap.js';
-
-import { cameraAnimations } from '../globals/cameraAnimations.js';
-import { cameraAnimationFrame } from '../globals/cameraAnimationFrame.js';
-
-
-
+import { cameraAnimationByMap } from '../weakmaps/cameraAnimationByMap.js';
+import { cameraFrameByMap } from '../weakmaps/cameraFrameByMap.js';
+import { cameraAnimations } from '../globals/cameraAnimations.js';
+import { cameraAnimationFrame } from '../globals/cameraAnimationFrame.js';
+
+/**
+ * Remove a map's camera animation and cancel the shared frame if no animations remain.
+ *
+ * @param {L.Map} map Map whose animation should stop.
+ */
 export function cancelCameraAnimation(map) {
   cameraAnimations.delete(map);
   cameraAnimationByMap.set(map, null);
@@ -14,4 +16,4 @@ export function cancelCameraAnimation(map) {
     cancelAnimationFrame(cameraAnimationFrame.value);
     cameraAnimationFrame.value = null;
   }
-}
+}

package/src/animations/cancelGridFade.js

@@ -1,10 +1,12 @@
 import { fadeFrameByLayer } from '../weakmaps/fadeFrameByLayer.js';
-
 import { pendingGridFades } from '../globals/pendingGridFades.js';
 import { gridFadeFrame } from '../globals/gridFadeFrame.js';
 
-
-
+/**
+ * Remove a layer's pending fade and cancel the shared frame if no fades remain.
+ *
+ * @param {L.GridLayer} layer Layer whose fade should stop.
+ */
 export function cancelGridFade(layer) {
   pendingGridFades.delete(layer);
   fadeFrameByLayer.set(layer, null);

package/src/animations/endZoom.js

@@ -2,15 +2,10 @@ import { zoomLevelByLayer } from '../weakmaps/zoomLevelByLayer.js';
 import { zoomTransitionsByLayer } from '../weakmaps/zoomTransitionsByLayer.js';
 import { zoomViewByLayer } from '../weakmaps/zoomViewByLayer.js';
 import { cameraViewByMap } from '../weakmaps/cameraViewByMap.js';
-
-
-
 import { mapUpdateCameraOverlays } from '../camera/mapUpdateCameraOverlays.js';
-
 import { update } from '../scene/scheduleSceneUpdate.js';
 
 /** Stop using the outgoing level after zoomend; the next redraw uses current tiles. */
-
 export function endZoom() {
   const layer = this;
   let animation;

package/src/animations/mapAnimateCamera.js

@@ -1,14 +1,24 @@
 import { cameraAnimationByMap } from '../weakmaps/cameraAnimationByMap.js';
-
 import { cameraEmptyOptions } from '../globals/cameraEmptyOptions.js';
 import { mapSetPitchAndBearing } from '../camera/mapSetPitchAndBearing.js';
 import { mapGetPitch } from '../camera/mapGetPitch.js';
 import { mapGetBearing } from '../camera/mapGetBearing.js';
-
 import { cancelCameraAnimation } from './cancelCameraAnimation.js';
 import { scheduleCameraAnimation } from './scheduleCameraAnimation.js';
 
-
+/**
+ * Set camera angles immediately or animate toward them along the shortest bearing arc.
+ *
+ * @param {L.Map} map Map whose camera should move.
+ * @param {number} pitch Target pitch in degrees.
+ * @param {number} bearing Target bearing in degrees.
+ * @param {Object} [options] Animation settings, including duration in seconds.
+ *
+ * @returns {L.Map} The updated map.
+ *
+ * @throws {TypeError} If either camera angle is not finite.
+ * @throws {TypeError} If an animated duration is negative or not finite.
+ */
 export function mapAnimateCamera(map, pitch, bearing, options = cameraEmptyOptions) {
   cancelCameraAnimation(map);
   if (!Number.isFinite(pitch) || !Number.isFinite(bearing)) throw /* alloc */ new TypeError('Camera angles must be finite numbers');

package/src/animations/mapStopPitchBearingAnimation.js

@@ -1,5 +1,12 @@
-import { cancelCameraAnimation } from './cancelCameraAnimation.js';
-
+import { cancelCameraAnimation } from './cancelCameraAnimation.js';
+
+/**
+ * Stop the map's current pitch and bearing animation.
+ *
+ * @param {L.Map} map Map whose animation should stop.
+ *
+ * @returns {L.Map} The supplied map.
+ */
 export function mapStopPitchBearingAnimation(map) {
   cancelCameraAnimation(map);
   return map;

package/src/animations/onZoomAnim.js

@@ -1,12 +1,13 @@
 import { zoomViewByLayer } from '../weakmaps/zoomViewByLayer.js';
-
 import { pendingZoomAnimations } from '../globals/pendingZoomAnimations.js';
-
-
 import { render } from "../rendering/render.js";
-
 import { renderPendingZoomAnimation } from './renderPendingZoomAnimation.js';
 
+/**
+ * Capture the initial and target zoom view, then queue a render for this layer.
+ *
+ * @param {Object} [event] Leaflet zoom event containing the target center and zoom.
+ */
 export function onZoomAnim(event) {
   const map = this._map;
   if (event && !zoomViewByLayer.get(this)) {

package/src/animations/renderPendingZoomAnimation.js

@@ -1,12 +1,9 @@
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
 import { pendingZoomAnimations } from '../globals/pendingZoomAnimations.js';
-
-
-
 import { render } from '../rendering/render.js';
 
+/** Render the next queued zoom layer if it owns an initialized renderer. */
 export function renderPendingZoomAnimation() {
   const layer = pendingZoomAnimations.shift();
   if (sharedByLayer.get(layer) === layer && rendererByLayer.get(layer)) render(layer);

package/src/animations/runCameraAnimations.js

@@ -1,14 +1,17 @@
 import { cameraAnimationByMap } from '../weakmaps/cameraAnimationByMap.js';
 import { cameraFrameByMap } from '../weakmaps/cameraFrameByMap.js';
-
 import { cameraAnimationFrame } from '../globals/cameraAnimationFrame.js';
 import { cameraAnimations } from '../globals/cameraAnimations.js';
-
 import { mapSetPitchAndBearing } from '../camera/mapSetPitchAndBearing.js';
-
-
 import { scheduleCameraAnimation } from './scheduleCameraAnimation.js';
 
+/**
+ * Advance pending camera animations and reschedule those still active.
+ *
+ * @param {number} now Animation-frame timestamp in milliseconds.
+ *
+ * @throws {*} The first error caught while updating a camera.
+ */
 export function runCameraAnimations(now) {
   cameraAnimationFrame.value = null;
   const pending = /* alloc */ [...cameraAnimations];

package/src/animations/runGridFades.js

@@ -1,12 +1,9 @@
 import { fadeFrameByLayer } from '../weakmaps/fadeFrameByLayer.js';
-
 import { gridFadeFrame } from '../globals/gridFadeFrame.js';
 import { pendingGridFades } from '../globals/pendingGridFades.js';
-
-
-
 import { updateGridOpacity } from '../core/updateGridOpacity.js';
 
+/** Advance queued grid fades whose scheduled versions are still current. */
 export function runGridFades() {
   gridFadeFrame.value = null;
   const layers = /* alloc */ [...pendingGridFades];

package/src/animations/runMarkerPanFrame.js

@@ -1,7 +1,7 @@
 import { markerPanFrame } from '../globals/markerPanFrame.js';
 import { pendingMarkerPan } from '../globals/pendingMarkerPan.js';
 
-
+/** Apply the latest queued pan event for each marker drag. */
 export function runMarkerPanFrame() {
   markerPanFrame.value = null;
   const pending = /* alloc */ [...pendingMarkerPan];

package/src/animations/scheduleCameraAnimation.js

@@ -1,12 +1,14 @@
-import { cameraFrameByMap } from '../weakmaps/cameraFrameByMap.js';
-
-import { cameraAnimations } from '../globals/cameraAnimations.js';
-import { cameraAnimationFrame } from '../globals/cameraAnimationFrame.js';
-
-
-
-import { runCameraAnimations } from './runCameraAnimations.js';
-
+import { cameraFrameByMap } from '../weakmaps/cameraFrameByMap.js';
+import { cameraAnimations } from '../globals/cameraAnimations.js';
+import { cameraAnimationFrame } from '../globals/cameraAnimationFrame.js';
+import { runCameraAnimations } from './runCameraAnimations.js';
+
+/**
+ * Queue a map's camera animation on the shared animation frame.
+ *
+ * @param {L.Map} map Map whose camera should animate.
+ * @param {Object} animation Camera animation state.
+ */
 export function scheduleCameraAnimation(map, animation) {
   cameraAnimations.set(map, animation);
   if (cameraAnimationFrame.value === null) cameraAnimationFrame.value = requestAnimationFrame(runCameraAnimations);

package/src/animations/scheduleGridFade.js

@@ -1,13 +1,14 @@
 import { fadeFrameByLayer } from '../weakmaps/fadeFrameByLayer.js';
 import { fadeVersionByLayer } from '../weakmaps/fadeVersionByLayer.js';
-
 import { pendingGridFades } from '../globals/pendingGridFades.js';
 import { gridFadeFrame } from '../globals/gridFadeFrame.js';
-
-
-
 import { runGridFades } from './runGridFades.js';
 
+/**
+ * Queue the latest fade version for a layer on the shared animation frame.
+ *
+ * @param {L.GridLayer} layer Layer whose tiles should fade.
+ */
 export function scheduleGridFade(layer) {
   fadeVersionByLayer.set(layer, (fadeVersionByLayer.get(layer) || 0) + 1);
   pendingGridFades.set(layer, fadeVersionByLayer.get(layer));

package/src/animations/scheduleMarkerPan.js

@@ -1,9 +1,13 @@
-import { pendingMarkerPan } from '../globals/pendingMarkerPan.js';
-import { markerPanFrame } from '../globals/markerPanFrame.js';
-
-
-import { runMarkerPanFrame } from './runMarkerPanFrame.js';
-
+import { pendingMarkerPan } from '../globals/pendingMarkerPan.js';
+import { markerPanFrame } from '../globals/markerPanFrame.js';
+import { runMarkerPanFrame } from './runMarkerPanFrame.js';
+
+/**
+ * Queue the latest marker drag event for the shared pan frame.
+ *
+ * @param {Object} drag Leaflet marker drag handler.
+ * @param {Object} event Drag event passed to the pan adjustment.
+ */
 export function scheduleMarkerPan(drag, event) {
   pendingMarkerPan.set(drag, event);
   if (markerPanFrame.value === null) markerPanFrame.value = requestAnimationFrame(runMarkerPanFrame);

package/src/animations/startZoom.js

@@ -1,9 +1,6 @@
 import { zoomLevelByLayer } from '../weakmaps/zoomLevelByLayer.js';
 
-
-
 /** Preserve the outgoing tile level before Leaflet changes its logical zoom. */
-
 export function startZoom() {
   zoomLevelByLayer.set(this, null);
 }

package/src/animations/synchronizeZoomView.js

@@ -1,9 +1,14 @@
 import { zoomTransitionsByLayer } from '../weakmaps/zoomTransitionsByLayer.js';
 import { zoomViewByLayer } from '../weakmaps/zoomViewByLayer.js';
-
 import { meshStack } from '../globals/meshStack.js';
 import { updateZoomCamera } from './updateZoomCamera.js';
 
+/**
+ * Pause zoom transitions and advance them with the rendered camera frame.
+ *
+ * @param {L.Layer} layer Layer whose map zoom is being synchronized.
+ * @param {number} now Current frame timestamp in milliseconds.
+ */
 export function synchronizeZoomView(layer, now) {
   const map = layer._map;
   let animation, time, start;

package/src/animations/updateZoomCamera.js

@@ -1,10 +1,14 @@
-import { zoomTransitionsByLayer } from '../weakmaps/zoomTransitionsByLayer.js';
-import { zoomViewByLayer } from '../weakmaps/zoomViewByLayer.js';
-import { cameraViewByMap } from '../weakmaps/cameraViewByMap.js';
-
-
+import { zoomTransitionsByLayer } from '../weakmaps/zoomTransitionsByLayer.js';
+import { zoomViewByLayer } from '../weakmaps/zoomViewByLayer.js';
+import { cameraViewByMap } from '../weakmaps/cameraViewByMap.js';
 import { mapUpdateCameraOverlays } from '../camera/mapUpdateCameraOverlays.js';
 
+/**
+ * Interpolate the map's camera view from the current zoom transition.
+ *
+ * @param {L.Layer} layer Layer whose map view is being animated.
+ * @param {number} now Current frame timestamp in milliseconds.
+ */
 export function updateZoomCamera(layer, now) {
   const map = layer._map;
   const view = zoomViewByLayer.get(layer);

package/src/archives/README.md

@@ -0,0 +1,28 @@
+# Archives
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Reads PMTiles headers, directories and tile byte ranges, including decompression
+and cached directory lookups.
+
+## Tile lookup
+
+```mermaid
+flowchart LR
+  XYZ["XYZ request"] --> ID["Hilbert tile ID"]
+  ID --> Header["Cached header promise"]
+  Header --> Directory["Root / leaf directories"]
+  Directory --> Tile["Tile byte range + decompression"]
+  Directory -->|missing| Miss["No tile"]
+```
+
+An external provider can implement `getHeader` and `getZxy`. Range reads
+validate length and ETag; changed archives fail rather than mixing versions.
+Traversal rejects cycles, invalid leaves and excessive nesting. For GeoJSON,
+[loadSource.js](./loadSource.js) accepts inline data or a URL, but not both.
+
+- [getHeader.js](./getHeader.js): obtain an archive header.
+- [getZxy.js](./getZxy.js): look up a tile by zoom, column and row.
+- [decodeDirectory.js](./decodeDirectory.js): decode directory entries.
+
+Related: [cog](../cog/README.md), [sources](../sources/README.md), [raster](../raster/README.md).

package/src/archives/decodeDirectory.js

@@ -1,8 +1,19 @@
 import { directoryReader } from '../globals/directoryReader.js';
 import { varint } from './readVarint.js';
 
-/** Decode delta/varint directory columns, rejecting malformed entries. */
-
+/**
+ * Decode delta/varint directory columns, rejecting malformed entries.
+ *
+ * @param {ArrayBuffer} data Encoded PMTiles directory.
+ *
+ * @returns {Object[]} Decoded directory entries.
+ *
+ * @throws {Error} If the directory entry count is invalid.
+ * @throws {Error} If tile IDs are invalid or not increasing.
+ * @throws {Error} If an entry has zero length.
+ * @throws {Error} If the first entry has an implicit offset.
+ * @throws {Error} If data remains after the directory entries.
+ */
 export function decodeDirectory(data) {
   const reader = directoryReader;
   const bytes = /* alloc */ new Uint8Array(data);

package/src/archives/decodeHeader.js

@@ -2,8 +2,15 @@ import { headerOffsets } from '../globals/headerOffsets.js';
 import { headerFlags } from '../globals/headerFlags.js';
 import { headerBounds } from '../globals/headerBounds.js';
 
-
-/** Decode the PMTiles v3 header. */
+/**
+ * Decode the PMTiles v3 header.
+ *
+ * @param {ArrayBuffer} data Header bytes.
+ *
+ * @returns {Object} Archive offsets, flags, bounds and center.
+ *
+ * @throws {Error} If the header is too short or not PMTiles version 3.
+ */
 export function decodeHeader(data) {
   const view = data.byteLength >= 127
     ? /* alloc */ new DataView(data) : null;

package/src/archives/decompress.js

@@ -1,3 +1,13 @@
+/**
+ * Return uncompressed data or decompress gzip data.
+ *
+ * @param {ArrayBuffer} data Archive data.
+ * @param {number} compression PMTiles compression code.
+ *
+ * @returns {Promise<ArrayBuffer>} Uncompressed bytes.
+ *
+ * @throws {Error} If the compression code is unsupported.
+ */
 export async function decompress(data, compression) {
   if (compression === 1) return data;
   if (compression !== 2) {

package/src/archives/findDirectoryEntry.js

@@ -1,3 +1,11 @@
+/**
+ * Find the last directory entry whose tile ID does not exceed the requested ID.
+ *
+ * @param {Object[]} entries Entries sorted by tile ID.
+ * @param {number} id Requested tile ID.
+ *
+ * @returns {Object|undefined} Matching entry, if any.
+ */
 export function findDirectoryEntry(entries, id) {
   let low = 0, high = entries.length - 1, mid;
   while (low <= high) {

package/src/archives/findTile.js

@@ -2,6 +2,20 @@ import { getDirectoryEntries } from './getDirectoryEntries.js';
 import { findDirectoryEntry } from './findDirectoryEntry.js';
 import { getTileData } from './getTileData.js';
 
+/**
+ * Follow root and leaf directories to find an archive tile.
+ *
+ * @param {L.Layer} layer Archive layer.
+ * @param {Object} header Decoded archive header.
+ * @param {number} id Cumulative Hilbert tile ID.
+ * @param {AbortSignal} [signal] Request cancellation signal.
+ *
+ * @returns {Promise<Object|undefined>} Tile data, or undefined if not found.
+ *
+ * @throws {Error} If directory offsets form a cycle.
+ * @throws {Error} If a leaf directory extends outside its section.
+ * @throws {Error} If directory nesting exceeds four levels.
+ */
 export async function findTile(layer, header, id, signal) {
   let offset = header.rootDirectoryOffset, length = header.rootDirectoryLength;
   let firstOffset = -1, secondOffset = -1, thirdOffset = -1;