leaflet-city-mapper 0.0.8 → 0.1.0

package/src/walk/isWalkBlocked.js

@@ -1,5 +1,14 @@
 import { hit } from '../picking/hit.js';
 
+/**
+ * Cast a horizontal movement ray with walker clearance and return the nearest obstacle normal.
+ *
+ * @param {number} east Eastward movement in metres.
+ * @param {number} north Northward movement in metres.
+ * @param {number[]} feet Walker's world-space feet position.
+ *
+ * @returns {number[]|null|false} Horizontal obstacle normal, or a falsy value when clear.
+ */
 export function blocked(east, north, feet) {
   const length = Math.hypot(east, north);
   return length > 1e-6 && hit(this.layer, feet[0], feet[1], feet[2], east / length, -north / length, length + 0.3, this.hitData);

package/src/walk/landWalker.js

@@ -1,10 +1,9 @@
-import { kindByLayer } from '../weakmaps/kindByLayer.js';
-import { layersByLayer } from '../weakmaps/layersByLayer.js';
-import { raycasterByLayer } from '../weakmaps/raycasterByLayer.js';
-import { rootByLayer } from '../weakmaps/rootByLayer.js';
-import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
-import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
-
+import { kindByLayer } from '../weakmaps/kindByLayer.js';
+import { layersByLayer } from '../weakmaps/layersByLayer.js';
+import { raycasterByLayer } from '../weakmaps/raycasterByLayer.js';
+import { rootByLayer } from '../weakmaps/rootByLayer.js';
+import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
+import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
 import { intersectMeshes } from '../collision/intersectMeshes.js';
 import { traverse } from '../scene/traverse.js';
 import { updateWorldMatrix } from '../transforms/updateWorldMatrix.js';
@@ -12,7 +11,12 @@ import { collectVisibleMesh } from '../picking/collectVisibleMesh.js';
 import { shouldSkipOther } from '../picking/shouldSkipOther.js';
 import { local } from '../projections/walkerLocalPosition.js';
 
-export function land(previousY) {
+/**
+ * Land a descending walker on the first visible surface crossed since its previous height.
+ *
+ * @param {number} previousY Previous world-space feet height.
+ */
+export function land(previousY) {
   const ray = raycasterByLayer.get(this.layer)
   const feet = local.call(this, this.local), root = rootByLayer.get(this.layer);
   const x = root.position[0] + feet[0] * root.scale[0];

package/src/walk/moveWalker.js

@@ -1,10 +1,15 @@
-import { rootByLayer } from '../weakmaps/rootByLayer.js';
-
+import { rootByLayer } from '../weakmaps/rootByLayer.js';
 import { L } from '../globals/L.js';
 import { radians } from '../globals/radians.js';
 import { local } from '../projections/walkerLocalPosition.js';
 import { blocked } from './isWalkBlocked.js';
 
+/**
+ * Move along the walker's heading, maintaining wall clearance and sliding along obstacles.
+ *
+ * @param {number} forward Signed movement direction.
+ * @param {number} dt Frame duration in seconds.
+ */
 export function moveWalker(forward, dt) {
   const metres = forward * this.speed * dt, { lat, lng } = this.state.latlng;
   const { position, scale } = rootByLayer.get(this.layer);
@@ -15,9 +20,17 @@ export function moveWalker(forward, dt) {
   // World x is east, z south; keep 0.3 m from walls and slide along them.
   const wall = blocked.call(this, east, north, feet);
   if (wall) {
-    const into = east * wall[0] - north * wall[1];
+    const fraction = Math.max(0, Math.min(1, (this.hitData.best - 0.3) / Math.hypot(east, north)));
+    const movedEast = east * fraction, movedNorth = north * fraction;
+    feet[0] += movedEast; feet[2] -= movedNorth;
+    east -= movedEast; north -= movedNorth;
+    const into = Math.min(0, east * wall[0] - north * wall[1]);
     east -= into * wall[0]; north += into * wall[1];
-    if (blocked.call(this, east, north, feet)) east = north = 0;
+    if (blocked.call(this, east, north, feet)) {
+      const slide = Math.max(0, Math.min(1, (this.hitData.best - 0.3) / Math.hypot(east, north)));
+      east *= slide; north *= slide;
+    }
+    east += movedEast; north += movedNorth;
   }
   this.state.latlng = /* alloc */ new L.LatLng(lat + north / 111320, lng + east / (111320 * Math.cos(lat * radians)));
   this.state.phase += Math.hypot(east, north) / 1.6 * Math.PI;

package/src/walk/onAddWalkControl.js

@@ -1,5 +1,14 @@
 import { walkByMap } from '../weakmaps/walkByMap.js';
 
+/**
+ * Attach the walk layer and reuse map-owned collision scratch, rejecting duplicate controls.
+ *
+ * @param {L.Map} map Map receiving the control.
+ *
+ * @returns {HTMLElement} Walk control container.
+ *
+ * @throws {Error} If another walk control is already attached to the map.
+ */
 export function onAdd(map) {
   let state = walkByMap.get(map);
   if (state?.control && state.control !== this) {

package/src/walk/onRemoveWalkControl.js

@@ -1,5 +1,10 @@
 import { walkByMap } from '../weakmaps/walkByMap.js';
 
+/**
+ * Stop and detach the current walk control while retaining reusable map-owned scratch.
+ *
+ * @param {L.Map} map Map from which the control is removed.
+ */
 export function onRemove(map) {
   const state = walkByMap.get(map);
   if (state?.control !== this) return;

package/src/walk/onWalkBlur.js

@@ -1,3 +1,4 @@
+/** Release held movement keys when the window loses focus. */
 export function onBlur() {
   this.keys.clear();
 }

package/src/walk/onWalkKey.js

@@ -1,8 +1,11 @@
 import { moves } from '../globals/moves.js';
-
-
 import { stop } from './stopWalking.js';
 
+/**
+ * Track walking keys and Escape without stealing input from text fields or modified shortcuts.
+ *
+ * @param {KeyboardEvent} event Keydown or keyup event.
+ */
 export function onKey(event) {
   if (event.type === 'keyup' && event.code === 'Space') this.keys.delete('Space');
   // Text fields and sliders keep their keys; buttons and checkboxes don't.

package/src/walk/onWalkPointer.js

@@ -1,6 +1,12 @@
 import { mapSetPitchAndBearing } from '../camera/mapSetPitchAndBearing.js';
 import { mapGetPitch } from '../camera/mapGetPitch.js';
 import { mapGetBearing } from '../camera/mapGetBearing.js';
+
+/**
+ * Rotate the walk camera on primary-pointer drags outside map controls.
+ *
+ * @param {PointerEvent} event Pointer event on the map.
+ */
 export function onPointer(event) {
   // Dragging only turns the camera around the walker: horizontal = bearing, vertical = pitch.
   const map = this.layer._map;

package/src/walk/onWalkTerrain.js

@@ -1,5 +1,6 @@
-import { place } from './placeWalker.js';
-
-export function onTerrain() {
+import { place } from './placeWalker.js';
+
+/** Reposition existing walker meshes after terrain elevation changes. */
+export function onTerrain() {
   if (this.meshes) place.call(this);
 }

package/src/walk/placeWalker.js

@@ -1,9 +1,8 @@
 import { limbs } from '../globals/limbs.js';
-
 import { update } from '../scene/scheduleSceneUpdate.js';
-
 import { local } from '../projections/walkerLocalPosition.js';
 
+/** Place and animate the walker meshes at the current position and heading, then request a scene update. */
 export function place() {
   const [x, y, z] = local.call(this, this.local);
   // Model forward is -z; a yaw of -heading turns it to the compass heading (x east, -z north).

package/src/walk/resolveWalkerPosition.js

@@ -1,6 +1,11 @@
 import { L } from '../globals/L.js';
 import { insideWalker } from '../collision/insideWalker.js';
 
+/**
+ * Search nearby positions when the active walker is enclosed, restoring the original position if none is clear.
+ *
+ * @returns {boolean} Whether the walker was moved to a clear position.
+ */
 export function resolveWalkerPosition() {
   if (!this.saved || !insideWalker(this)) return false;
   const map = this.layer._map;

package/src/walk/startWalking.js

@@ -12,7 +12,7 @@ import { onPointer } from './onWalkPointer.js';
 import { onTerrain } from './onWalkTerrain.js';
 import { resolveWalkerPosition } from './resolveWalkerPosition.js';
 
-
+/** Enter walk mode, saving map settings and installing input and terrain listeners. */
 export function start() {
   const map = this.layer._map;
   if (this.saved || !map) return;

package/src/walk/stepWalkerHeight.js

@@ -1,3 +1,10 @@
+/**
+ * Advance ascent or gravity-driven descent and report whether the walker's height changed.
+ *
+ * @param {number} dt Frame duration in seconds.
+ *
+ * @returns {boolean} Whether a vertical update was applied.
+ */
 export function stepWalkerHeight(dt) {
   if (this.keys.has('Space')) {
     this.verticalSpeed = 6;

package/src/walk/stopWalking.js

@@ -6,6 +6,7 @@ import { onBlur } from './onWalkBlur.js';
 import { onPointer } from './onWalkPointer.js';
 import { onTerrain } from './onWalkTerrain.js';
 
+/** Leave walk mode, release walker meshes and listeners, and restore the saved map settings. */
 export function stop() {
   const map = this.layer._map;
   cancelAnimationFrame(this.frame);

package/src/walk/toggleWalking.js

@@ -1,6 +1,7 @@
-import { start } from './startWalking.js';
-import { stop } from './stopWalking.js';
-
-export function toggle() {
+import { start } from './startWalking.js';
+import { stop } from './stopWalking.js';
+
+/** Toggle the control between walk mode and the normal map view. */
+export function toggle() {
   if (this.saved) stop.call(this); else start.call(this);
 }

package/src/walk/updateWalkerFrame.js

@@ -4,6 +4,16 @@ import { land } from './landWalker.js';
 import { moveWalker } from './moveWalker.js';
 import { updateWalkerView } from './updateWalkerView.js';
 
+/**
+ * Apply heading, motion, landing and camera changes, repositioning meshes when the frame changes.
+ *
+ * @param {Object} walker Walk context.
+ * @param {number} previousY Previous world-space feet height.
+ * @param {number} forward Signed movement direction.
+ * @param {number} turn Signed turning direction.
+ * @param {number} dt Frame duration in seconds.
+ * @param {boolean} changed Whether the walker already changed this frame.
+ */
 export function updateWalkerFrame(walker, previousY, forward, turn, dt, changed) {
   if (turn) {
     walker.state.heading = wrap(walker.state.heading + turn * 2.5 * dt);

package/src/walk/updateWalkerView.js

@@ -5,6 +5,15 @@ import { mapSetPitchAndBearing } from '../camera/mapSetPitchAndBearing.js';
 import { mapGetPitch } from '../camera/mapGetPitch.js';
 import { wrap } from '../utils/wrap.js';
 
+/**
+ * Follow movement with the map camera and ease the limb swing toward its active or idle amplitude.
+ *
+ * @param {number} forward Signed movement direction.
+ * @param {number} turn Signed turning direction.
+ * @param {number} dt Frame duration in seconds.
+ *
+ * @returns {boolean} Whether the limb swing was updated.
+ */
 export function updateWalkerView(forward, turn, dt) {
   const map = this.layer._map;
   if (forward || turn) {

package/src/weakmaps/README.md

@@ -0,0 +1,33 @@
+# Private state
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Stores state associated with layers, maps and other objects in dedicated
+WeakMap modules. Field indexes group maps for lifecycle and compatibility.
+
+## Ownership
+
+```mermaid
+flowchart LR
+  Map["Map"] -->|"renderers"| Owner["Shared owner layer"]
+  Member["Member layer"] -->|"sharedByLayer"| Owner
+  Member -->|"rendererByLayer"| Renderer["Shared renderer"]
+  Owner -->|"rendererByLayer"| Renderer
+  Layer["Source layer"] -->|"directoriesByLayer"| Cache["Directory cache"]
+  Map -->|"cameraPitchByMap"| Pitch["Pitch"]
+```
+
+Each label names a dedicated `WeakMap` imported directly by its consumers.
+Keys can also be meshes or devices. `get` returning `undefined` differs from a
+stored `null`.
+
+On owner removal, [onRemove3DLayer.js](../scene/onRemove3DLayer.js) transfers
+selected fields or releases the last shared scene. Weak keys do **not** abort
+requests, remove listeners or destroy GPU resources.
+
+[sceneFields.js](./sceneFields.js) indexes selected maps for lifecycle and test
+compatibility; [cameraFields.js](./cameraFields.js) is a test compatibility
+index. They reference the original maps, not copies. When adding state, use a
+dedicated module and update indexes and lifecycle lists only where applicable.
+
+Related: [scene](../scene/README.md), [camera](../camera/README.md), [globals](../globals/README.md).

package/src/weakmaps/addedByLayer.js

@@ -1 +1,6 @@
+/**
+ * Deferred layer-attachment promises and resolvers, keyed by layer.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const addedByLayer = new WeakMap();

package/src/weakmaps/archiveHeaderByLayer.js

@@ -1 +1,6 @@
+/**
+ * Cached archive headers keyed by source layer.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const archiveHeaderByLayer = new WeakMap();

package/src/weakmaps/areasByLayer.js

@@ -1 +1,6 @@
+/**
+ * Source area maps and their request state, keyed by layer.
+ *
+ * @type {WeakMap<Object, Map>}
+ */
 export const areasByLayer = new WeakMap();

package/src/weakmaps/boundsMethods.js

@@ -1 +1,6 @@
+/**
+ * Original Leaflet bounds methods saved for native layers.
+ *
+ * @type {WeakMap<Object, Function>}
+ */
 export const boundsMethods = new WeakMap();

package/src/weakmaps/bridgeMeshByLayer.js

@@ -1 +1,6 @@
+/**
+ * Terrain bridge meshes keyed by layer.
+ *
+ * @type {WeakMap<Object, Object|null>}
+ */
 export const bridgeMeshByLayer = new WeakMap();

package/src/weakmaps/bridgesByLayer.js

@@ -1 +1,6 @@
+/**
+ * Spatial bridge indexes used for elevation lookup, keyed by layer.
+ *
+ * @type {WeakMap<Object, Map|null>}
+ */
 export const bridgesByLayer = new WeakMap();

package/src/weakmaps/cameraAnimationByMap.js

@@ -1 +1,6 @@
+/**
+ * Active camera animations keyed by map.
+ *
+ * @type {WeakMap<Object, Object|null>}
+ */
 export const cameraAnimationByMap = new WeakMap();

package/src/weakmaps/cameraBearingByMap.js

@@ -1 +1,6 @@
+/**
+ * Camera bearings in degrees keyed by map.
+ *
+ * @type {WeakMap<Object, number>}
+ */
 export const cameraBearingByMap = new WeakMap();

package/src/weakmaps/cameraByLayer.js

@@ -1 +1,6 @@
+/**
+ * Scene cameras used for rendering and picking, keyed by layer.
+ *
+ * @type {WeakMap<Object, Object|null>}
+ */
 export const cameraByLayer = new WeakMap();

package/src/weakmaps/cameraDraggableByMap.js

@@ -1 +1,6 @@
+/**
+ * Leaflet draggable instances used by camera controls, keyed by map.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const cameraDraggableByMap = new WeakMap();

package/src/weakmaps/cameraFields.js

@@ -16,6 +16,11 @@ import { timeControlByMap } from './timeControlByMap.js';
 import { touchPitchByMap } from './touchPitchByMap.js';
 import { touchRotateByMap } from './touchRotateByMap.js';
 
+/**
+ * Index camera and control state maps by their compatibility field names.
+ *
+ * @type {Object<string, WeakMap>}
+ */
 export const cameraFields = {
   "_cameraAnimation": cameraAnimationByMap,
   "_cameraBearing": cameraBearingByMap,

package/src/weakmaps/cameraFrameByMap.js

@@ -1 +1,6 @@
+/**
+ * Scheduled camera animation frame identifiers keyed by map.
+ *
+ * @type {WeakMap<Object, number|null>}
+ */
 export const cameraFrameByMap = new WeakMap();

package/src/weakmaps/cameraHandlersByMap.js

@@ -1 +1,6 @@
+/**
+ * Camera interaction handlers indexed by name for each map.
+ *
+ * @type {WeakMap<Object, Map>}
+ */
 export const cameraHandlersByMap = new WeakMap();

package/src/weakmaps/cameraMaps.js

@@ -1 +1,6 @@
+/**
+ * Maps initialized with camera support.
+ *
+ * @type {WeakSet<Object>}
+ */
 export const cameraMaps = new WeakSet();

package/src/weakmaps/cameraPitchByMap.js

@@ -1 +1,6 @@
+/**
+ * Camera pitch values in degrees keyed by map.
+ *
+ * @type {WeakMap<Object, number>}
+ */
 export const cameraPitchByMap = new WeakMap();

package/src/weakmaps/cameraReadyByMap.js

@@ -1 +1,6 @@
+/**
+ * Camera control initialization promises keyed by map.
+ *
+ * @type {WeakMap<Object, Promise>}
+ */
 export const cameraReadyByMap = new WeakMap();

package/src/weakmaps/cameraTouchStateByMap.js

@@ -1 +1,6 @@
+/**
+ * Camera touch interaction state keyed by map.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const cameraTouchStateByMap = new WeakMap();

package/src/weakmaps/cameraViewByMap.js

@@ -1 +1,6 @@
+/**
+ * Animated camera view overrides keyed by map.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const cameraViewByMap = new WeakMap();

package/src/weakmaps/cameraZIndexOffsetByLayer.js

@@ -1 +1,6 @@
+/**
+ * Camera-dependent marker z-index offsets keyed by source layer.
+ *
+ * @type {WeakMap<Object, number>}
+ */
 export const cameraZIndexOffsetByLayer = new WeakMap();

package/src/weakmaps/closestMethods.js

@@ -1 +1,6 @@
+/**
+ * Original closestLayerPoint methods saved for native layers.
+ *
+ * @type {WeakMap<Object, Function>}
+ */
 export const closestMethods = new WeakMap();

package/src/weakmaps/colliders.js

@@ -1 +1,6 @@
+/**
+ * Cached collision geometry keyed by mesh.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const colliders = new WeakMap();

package/src/weakmaps/containerByLayer.js

@@ -1 +1,6 @@
+/**
+ * Map containers used for layer pointer events and tooltips, keyed by layer.
+ *
+ * @type {WeakMap<Object, HTMLElement|null>}
+ */
 export const containerByLayer = new WeakMap();

package/src/weakmaps/controlByLayer.js

@@ -1 +1,6 @@
+/**
+ * Time controls associated with sunlight layers.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const controlByLayer = new WeakMap();

package/src/weakmaps/countStatusByLayer.js

@@ -1 +1,6 @@
+/**
+ * Layer control elements displaying source loading and feature counts.
+ *
+ * @type {WeakMap<Object, HTMLElement>}
+ */
 export const countStatusByLayer = new WeakMap();

package/src/weakmaps/cursorByLayer.js

@@ -1 +1,6 @@
+/**
+ * Saved container cursor styles for feature hover, keyed by shared layer.
+ *
+ * @type {WeakMap<Object, string>}
+ */
 export const cursorByLayer = new WeakMap();

package/src/weakmaps/demByLayer.js

@@ -1 +1,6 @@
+/**
+ * Elevation texture and range used by the terrain material, keyed by layer.
+ *
+ * @type {WeakMap<Object, Object|null>}
+ */
 export const demByLayer = new WeakMap();

package/src/weakmaps/directoriesByLayer.js

@@ -1 +1,6 @@
+/**
+ * Cached archive directory entries keyed by source layer.
+ *
+ * @type {WeakMap<Object, Map>}
+ */
 export const directoriesByLayer = new WeakMap();

package/src/weakmaps/dragByHandler.js

@@ -1 +1,6 @@
+/**
+ * Saved original marker drag methods keyed by drag handler.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const dragByHandler = new WeakMap();

package/src/weakmaps/dragStates.js

@@ -1 +1,6 @@
+/**
+ * Mutable holder for camera drag state keyed by interactive element.
+ *
+ * @type {{value: WeakMap<Element, Object>}}
+ */
 export const dragStates = { value: new WeakMap() };

package/src/weakmaps/etagByLayer.js

@@ -1 +1,6 @@
+/**
+ * Archive response ETags used to detect changes across range requests.
+ *
+ * @type {WeakMap<Object, string>}
+ */
 export const etagByLayer = new WeakMap();

package/src/weakmaps/eventMapByLayer.js

@@ -1 +1,6 @@
+/**
+ * Maps on which layer event handlers are registered.
+ *
+ * @type {WeakMap<Object, Object|null>}
+ */
 export const eventMapByLayer = new WeakMap();

package/src/weakmaps/eventsByLayer.js

@@ -1 +1,6 @@
+/**
+ * Registered map event handler dictionaries keyed by layer.
+ *
+ * @type {WeakMap<Object, Object|null>}
+ */
 export const eventsByLayer = new WeakMap();

package/src/weakmaps/fadeFrameByLayer.js

@@ -1 +1,6 @@
+/**
+ * Scheduled grid fade animation frames keyed by layer.
+ *
+ * @type {WeakMap<Object, number|null>}
+ */
 export const fadeFrameByLayer = new WeakMap();

package/src/weakmaps/fadeVersionByLayer.js

@@ -1 +1,6 @@
+/**
+ * Grid fade revisions keyed by layer to distinguish scheduled updates.
+ *
+ * @type {WeakMap<Object, number>}
+ */
 export const fadeVersionByLayer = new WeakMap();

package/src/weakmaps/frameByLayer.js

@@ -1 +1,6 @@
+/**
+ * Scheduled scene render frame identifiers keyed by layer.
+ *
+ * @type {WeakMap<Object, number|null>}
+ */
 export const frameByLayer = new WeakMap();

package/src/weakmaps/geojsonByLayer.js

@@ -1 +1,6 @@
+/**
+ * Flags identifying layers backed by GeoJSON data.
+ *
+ * @type {WeakMap<Object, boolean>}
+ */
 export const geojsonByLayer = new WeakMap();

package/src/weakmaps/geometryWorkersByMap.js

@@ -1 +1,6 @@
+/**
+ * Geometry worker pools shared by layers on each map.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const geometryWorkersByMap = new WeakMap();

package/src/weakmaps/gridInitializers.js

@@ -1 +1,6 @@
+/**
+ * Original grid container initialization methods saved for native layers.
+ *
+ * @type {WeakMap<Object, Function>}
+ */
 export const gridInitializers = new WeakMap();

package/src/weakmaps/groupByLayer.js

@@ -1 +1,6 @@
+/**
+ * Scene groups exposed by layers.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const groupByLayer = new WeakMap();

package/src/weakmaps/headerByLayer.js

@@ -1 +1,6 @@
+/**
+ * Loaded source headers used for bounds and tile selection, keyed by layer.
+ *
+ * @type {WeakMap<Object, Object>}
+ */
 export const headerByLayer = new WeakMap();

package/src/weakmaps/highlightedFeatureByLayer.js

@@ -1 +1,6 @@
+/**
+ * Currently highlighted feature and mesh information keyed by layer.
+ *
+ * @type {WeakMap<Object, Object|null>}
+ */
 export const highlightedFeatureByLayer = new WeakMap();

package/src/weakmaps/hoveredFeatureByLayer.js

@@ -1 +1,6 @@
+/**
+ * Currently hovered feature keyed by layer.
+ *
+ * @type {WeakMap<Object, Object|null>}
+ */
 export const hoveredFeatureByLayer = new WeakMap();