@navaramap/three 0.1.0 → 0.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@navaramap/three",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,13 +30,13 @@
     "astronomy-engine": "2.1.19",
     "stats.js": "0.17.0",
     "three-stdlib": "2.36.1",
-    "@navaramap/engine": "0.1.0",
-    "@navaramap/engine-api": "0.1.0",
-    "@navaramap/core": "0.1.0",
-    "@navaramap/three-csm": "0.1.0",
-    "@navaramap/font": "0.1.0",
-    "@navaramap/worker": "0.1.0",
-    "@navaramap/three-api": "0.1.0"
+    "@navaramap/core": "0.1.1",
+    "@navaramap/engine": "0.1.1",
+    "@navaramap/three-api": "0.1.1",
+    "@navaramap/three-csm": "0.1.1",
+    "@navaramap/worker": "0.1.1",
+    "@navaramap/engine-api": "0.1.1",
+    "@navaramap/font": "0.1.1"
   },
   "devDependencies": {
     "@playwright/test": "1.62.1",
@@ -71,10 +71,10 @@
     "tweakpane": "4.0.5",
     "vite-plugin-glsl": "1.6.0",
     "vite-plugin-static-copy": "4.1.1",
-    "@navaramap/three-default-plugin": "0.1.0",
-    "@navaramap/three-plugins": "0.1.0",
-    "@navaramap/three-default-descs": "0.1.0",
-    "@navaramap/three-react": "0.1.0"
+    "@navaramap/three-default-descs": "0.1.1",
+    "@navaramap/three-default-plugin": "0.1.1",
+    "@navaramap/three-react": "0.1.1",
+    "@navaramap/three-plugins": "0.1.1"
   },
   "scripts": {
     "start": "vite",

package/src/core/BaseDesc.ts

@@ -76,6 +76,8 @@ export abstract class BaseDesc<
 
   private _visible?: boolean;
 
+  private _destroyed = false;
+
   constructor(
     view: ThreeView,
     ctx: ViewContext,
@@ -92,8 +94,20 @@ export abstract class BaseDesc<
   /**
    * Called when the this class is added to the scene. Override this to create the Three.js objects.
    * This is where you should initialize `this._instance` and add it to the appropriate scene.
+   *
+   * May return a promise: a descriptor whose implementation loads lazily
+   * (e.g. an `await import(...)` of a heavy renderer dependency) can be
+   * `async`, awaiting the module before delegating to `super.onCreate()`
+   * (after checking {@link destroyed}). `addMesh`/`addLight`/`addEffect`
+   * still return their handle synchronously; the instance appears once the
+   * promise settles, and a rejection is reported through the descriptor's
+   * `error` event (when it declares one). Handle calls issued while the
+   * promise is pending are safe: `update()`/`visible` store their fields
+   * without touching the missing instance (the deferred `super.onCreate()`
+   * applies them), and per-frame/resize hooks are wired only after creation
+   * completes.
    */
-  abstract onCreate(): void;
+  abstract onCreate(): void | Promise<void>;
 
   /**
    * Called when the configuration is updated via `BaseHandle.update()`.
@@ -122,9 +136,19 @@ export abstract class BaseDesc<
    * Override this to clean up resources. Remember to call `super.onDestroy()`.
    */
   onDestroy(): void {
+    this._destroyed = true;
     this._instance = undefined;
   }
 
+  /**
+   * True once {@link onDestroy} has run. An async {@link onCreate} (and the
+   * hook wiring that waits on it) checks this after its awaited module
+   * resolves, so a descriptor deleted mid-load creates nothing.
+   */
+  get destroyed(): boolean {
+    return this._destroyed;
+  }
+
   /**
    * Gets whether this is currently visible.
    */

package/src/core/MeshDesc.ts

@@ -598,7 +598,6 @@ export abstract class MeshDesc<
     assertNoTransformConflict(nextGeodetic, nextMatrix, nextMatrixWorld);
 
     super.onUpdateConfig(updates);
-    invariant(this.raw);
 
     const spatialChanged =
       updates.matrix !== undefined ||
@@ -636,6 +635,8 @@ export abstract class MeshDesc<
       this.applyLit();
     }
 
+    if (!this.raw) return;
+
     if (spatialChanged) {
       // With a frame present, the effective transform depends on the
       // combination of all stored fields — recompose the whole thing.

package/src/index.ts

@@ -118,7 +118,12 @@ import {
 } from "./material";
 import type { TileMesh } from "./mesh/tile";
 import { RenderPassOrchestrator } from "./orchestrators/RenderPassOrchestrator";
-import { PickHelper } from "./pick/pickHelper";
+import {
+  CLICK_PIXEL_TOLERANCE,
+  isClickGesture,
+  PickHelper,
+  TAP_PIXEL_TOLERANCE,
+} from "./pick/pickHelper";
 import { TerrainPicker } from "./pick/pickTerrain";
 import { AttributionPlugin, type AttributionPluginOptions } from "./plugins";
 import { TexturizedSceneByTileCoordinates, type Scenes } from "./scene";
@@ -219,6 +224,12 @@ export * from "./layers";
 export * from "./passes";
 export * from "./evaluations";
 export { SKY_RENDER_ORDER, STARS_RENDER_ORDER } from "./renderOrder";
+export {
+  CLICK_PIXEL_TOLERANCE,
+  TAP_PIXEL_TOLERANCE,
+  PICK_RADIUS,
+  TOUCH_PICK_RADIUS,
+} from "./pick/pickHelper";
 export * from "@navaramap/three-api";
 export * from "./Color";
 export { type BlendMode, blendFunction, createReplacer } from "./utils";
@@ -311,8 +322,8 @@ export type Options = {
   backgroundColor?: CoreColor;
   /**
    * Feature picking configuration (default: true). Enables the `featureClick`
-   * event (click) and the `featureHover` / `featureEnter` / `featureLeave`
-   * events (mousemove).
+   * event (click or touch tap) and the `featureHover` / `featureEnter` /
+   * `featureLeave` events (pointer hover).
    */
   picking?: boolean;
   /** When true, renders every frame. When false, renders only on changes or when forceUpdate() is called. */
@@ -404,12 +415,13 @@ export type Options = {
 } & GlobeOptions;
 
 /**
- * Mouse event extended with map coordinates at the event location.
+ * Pointer event extended with map coordinates at the event location.
+ * Fired for every input type; `pointerType` tells them apart.
  */
-export type MapMouseEvent = {
-  /** World coordinates (ECEF) at the mouse position on the globe surface. */
+export type MapPointerEvent = {
+  /** World coordinates (ECEF) at the pointer position on the globe surface. */
   map: XYZ;
-} & MouseEvent;
+} & PointerEvent;
 
 /**
  * Event types emitted by ThreeView. Subscribe using `view.on(eventName, callback)`.
@@ -418,13 +430,13 @@ export type ViewEvents = {
   /** Emitted when the view is resized. Receives width and height in pixels. */
   resize: (w: number, h: number) => void;
   /**
-   * Emitted when a feature is clicked (click-gesture GPU pick). Receives the
-   * clicked feature, or null when empty space was clicked. For raw click
-   * coordinates use the `click` event instead.
+   * Emitted when a feature is clicked or tapped (click-gesture GPU pick).
+   * Receives the clicked feature, or null when empty space was clicked. For
+   * raw click coordinates use the `click` event instead.
    */
   featureClick: (info: Nullable<PickedFeature>) => void;
   /**
-   * Emitted when the hovered feature changes (mousemove picking). Receives
+   * Emitted when the hovered feature changes (hover picking). Receives
    * the newly hovered feature, or null when the pointer leaves all pickable
    * features. Hover picking runs a GPU pick per frame while the pointer
    * moves, and is active only while at least one `featureHover` /
@@ -451,18 +463,26 @@ export type ViewEvents = {
   postRender: (t: number) => void;
   /** @private Emitted when terrain height sampling completes. */
   _sample_terrain_height_received: (ev: TerrainHeightUpdatedEvent) => void;
-  /** Emitted on mouse down with map coordinates. */
-  mousedown: (event: MapMouseEvent) => void;
-  /** Emitted when mouse enters the canvas with map coordinates. */
-  mouseenter: (event: MapMouseEvent) => void;
-  /** Emitted when mouse leaves the canvas with map coordinates. */
-  mouseleave: (event: MapMouseEvent) => void;
-  /** Emitted on mouse move with map coordinates. */
-  mousemove: (event: MapMouseEvent) => void;
-  /** Emitted on mouse up with map coordinates. */
-  mouseup: (event: MapMouseEvent) => void;
-  /** Emitted on click with map coordinates. */
-  click: (event: MapMouseEvent) => void;
+  /** Emitted on pointerdown with map coordinates, for every input type. */
+  pointerdown: (event: MapPointerEvent) => void;
+  /** Emitted when a pointer enters the canvas with map coordinates, for every input type. */
+  pointerenter: (event: MapPointerEvent) => void;
+  /** Emitted when a pointer leaves the canvas with map coordinates, for every input type. */
+  pointerleave: (event: MapPointerEvent) => void;
+  /** Emitted on pointermove with map coordinates, for every input type. */
+  pointermove: (event: MapPointerEvent) => void;
+  /** Emitted on pointerup with map coordinates, for every input type. */
+  pointerup: (event: MapPointerEvent) => void;
+  /** Emitted when the browser cancels an active pointer (e.g. a system gesture takes over). */
+  pointercancel: (event: PointerEvent) => void;
+  /**
+   * Emitted on a click or touch tap with map coordinates: a primary-pointer
+   * press and release within the travel tolerance
+   * ({@link CLICK_PIXEL_TOLERANCE}, or {@link TAP_PIXEL_TOLERANCE} for
+   * touch). Camera drags and pinches never fire it. `pointerType` tells the
+   * input kinds apart.
+   */
+  click: (event: MapPointerEvent) => void;
   /** Emitted when the engine becomes idle (no Rust-side events for `idleThreshold` ms). */
   idle: () => void;
 };
@@ -1173,9 +1193,9 @@ export default class ThreeView<
   }
 
   /**
-   * Convert a mouse event to a MapMouseEvent by adding map coordinates
+   * Extend a pointer event with map coordinates at its location
    */
-  private convertMouseEventToMapEvent(event: MouseEvent): MapMouseEvent | null {
+  private convertToMapEvent(event: PointerEvent): MapPointerEvent | null {
     const rect = this._renderer.domElement.getBoundingClientRect();
     const x = event.clientX - rect.left;
     const y = event.clientY - rect.top;
@@ -1188,7 +1208,7 @@ export default class ThreeView<
           y: xyz.y,
           z: xyz.z,
         },
-      }) as MapMouseEvent;
+      });
     }
 
     return null;
@@ -1624,47 +1644,75 @@ export default class ThreeView<
 
     this._camera.core = this._core;
 
-    this._renderer.domElement.addEventListener("mousedown", (event) => {
-      const mapEvent = this.convertMouseEventToMapEvent(event);
+    // The map events are fed from pointer events; touch produces no
+    // compatibility mouse events because the camera-input handlers call
+    // preventDefault() on touch events. `click` is a gesture, not the DOM
+    // event: a primary-pointer press and release within the travel
+    // tolerance, with no pinch and no cancellation. Camera drags never
+    // fire it.
+    let clickStart: Vector2 | undefined;
+
+    this._renderer.domElement.addEventListener("pointerdown", (event) => {
+      // A second finger turns the gesture into a pinch, not a tap.
+      clickStart =
+        event.isPrimary && event.button === 0
+          ? new Vector2(event.clientX, event.clientY)
+          : undefined;
+      const mapEvent = this.convertToMapEvent(event);
       if (mapEvent) {
-        this.emit("mousedown", mapEvent);
+        this.emit("pointerdown", mapEvent);
       }
     });
 
-    this._renderer.domElement.addEventListener("mouseenter", (event) => {
-      const mapEvent = this.convertMouseEventToMapEvent(event);
+    this._renderer.domElement.addEventListener("pointerenter", (event) => {
+      const mapEvent = this.convertToMapEvent(event);
       if (mapEvent) {
-        this.emit("mouseenter", mapEvent);
+        this.emit("pointerenter", mapEvent);
       }
     });
 
-    this._renderer.domElement.addEventListener("mouseleave", (event) => {
-      const mapEvent = this.convertMouseEventToMapEvent(event);
+    this._renderer.domElement.addEventListener("pointerleave", (event) => {
+      const mapEvent = this.convertToMapEvent(event);
       if (mapEvent) {
-        this.emit("mouseleave", mapEvent);
+        this.emit("pointerleave", mapEvent);
       }
     });
 
-    this._renderer.domElement.addEventListener("mousemove", (event) => {
-      const mapEvent = this.convertMouseEventToMapEvent(event);
+    this._renderer.domElement.addEventListener("pointermove", (event) => {
+      const mapEvent = this.convertToMapEvent(event);
       if (mapEvent) {
-        this.emit("mousemove", mapEvent);
+        this.emit("pointermove", mapEvent);
       }
     });
 
-    this._renderer.domElement.addEventListener("mouseup", (event) => {
-      const mapEvent = this.convertMouseEventToMapEvent(event);
+    this._renderer.domElement.addEventListener("pointerup", (event) => {
+      const mapEvent = this.convertToMapEvent(event);
       if (mapEvent) {
-        this.emit("mouseup", mapEvent);
+        this.emit("pointerup", mapEvent);
       }
-    });
-
-    this._renderer.domElement.addEventListener("click", (event) => {
-      const mapEvent = this.convertMouseEventToMapEvent(event);
-      if (mapEvent) {
+      if (!event.isPrimary || event.button !== 0) return;
+      const start = clickStart;
+      clickStart = undefined;
+      if (!start || !mapEvent) return;
+      const tolerance =
+        event.pointerType === "touch"
+          ? TAP_PIXEL_TOLERANCE
+          : CLICK_PIXEL_TOLERANCE;
+      if (
+        isClickGesture(
+          start,
+          new Vector2(event.clientX, event.clientY),
+          tolerance,
+        )
+      ) {
         this.emit("click", mapEvent);
       }
     });
+
+    this._renderer.domElement.addEventListener("pointercancel", (event) => {
+      clickStart = undefined;
+      this.emit("pointercancel", event);
+    });
   }
 
   /**
@@ -2074,6 +2122,33 @@ export default class ThreeView<
     return new Source(sourceId, s.type, this._core);
   }
 
+  /**
+   * Tracks a possibly-async `onCreate()` (see `BaseDesc.onCreate`): the
+   * `add*` methods still return their handle synchronously, the descriptor's
+   * instance appears when the promise settles, and a rejection is logged and
+   * reported through the descriptor's `error` event (when it declares one).
+   *
+   * `wire` binds the descriptor's lifecycle hooks (per-frame `update`,
+   * `onResize`, `needsUpdate`). It runs immediately for a synchronous
+   * creation, and only after the promise resolves for an async one — the
+   * hooks must not fire while the descriptor has no instance yet.
+   */
+  private _trackAsyncCreate(
+    kind: "mesh" | "light" | "effect",
+    desc: { emit: (event: never, ...args: never[]) => void },
+    result: void | Promise<void>,
+    wire: () => void,
+  ): void {
+    if (!(result instanceof Promise)) {
+      wire();
+      return;
+    }
+    result.then(wire, (error: unknown) => {
+      console.error(`Failed to create ${kind} descriptor:`, error);
+      (desc.emit as (event: string, payload: unknown) => void)("error", error);
+    });
+  }
+
   /**
    * Adds a 3D mesh to the scene.
    * The mesh kind is determined by the nested key (e.g., `{ box: { width: 200 } }`).
@@ -2092,28 +2167,35 @@ export default class ThreeView<
     // Create mesh descriptor instance
     const meshDesc = this.registries.mesh.create(meshType, config);
 
-    // Initialize the mesh
-    meshDesc.onCreate();
+    // Initialize the mesh; hooks are wired once the instance exists.
+    this._trackAsyncCreate("mesh", meshDesc, meshDesc.onCreate(), () => {
+      // If deleted while an async creation was loading, nothing to wire.
+      if (meshDesc.destroyed) return;
 
-    // Set up update listener
-    if (meshDesc.update) {
-      this.on("preRender", meshDesc.update.bind(meshDesc));
-    }
+      // Set up update listener
+      if (meshDesc.update) {
+        this.on("preRender", meshDesc.update.bind(meshDesc));
+      }
 
-    if (meshDesc.onResize) {
-      this.on("resize", meshDesc.onResize.bind(meshDesc));
+      if (meshDesc.onResize) {
+        this.on("resize", meshDesc.onResize.bind(meshDesc));
 
-      const canvasSize = this._getCanvasSize();
-      if (canvasSize) {
-        meshDesc.onResize(canvasSize.width, canvasSize.height);
+        const canvasSize = this._getCanvasSize();
+        if (canvasSize) {
+          meshDesc.onResize(canvasSize.width, canvasSize.height);
+        }
       }
-    }
 
-    // Trigger re-render
-    meshDesc.on("needsUpdate", this.forceUpdate);
+      // Trigger re-render
+      meshDesc.on("needsUpdate", this.forceUpdate);
+
+      this.forceUpdate();
+    });
 
     const l = new MeshHandle(meshDesc);
 
+    l.on("deleted", this.forceUpdate);
+
     // Store the mesh descriptor
     this.layersManager.add(l);
 
@@ -2139,19 +2221,26 @@ export default class ThreeView<
     // Create light descriptor instance
     const lightDesc = this.registries.light.create(lightType, config);
 
-    // Initialize the light
-    lightDesc.onCreate();
+    // Initialize the light; hooks are wired once the instance exists.
+    this._trackAsyncCreate("light", lightDesc, lightDesc.onCreate(), () => {
+      // Deleted while an async creation was loading — nothing to wire.
+      if (lightDesc.destroyed) return;
 
-    // Set up update listener if the descriptor has an update method
-    if (lightDesc.update) {
-      this.on("preRender", lightDesc.update.bind(lightDesc));
-    }
+      // Set up update listener if the descriptor has an update method
+      if (lightDesc.update) {
+        this.on("preRender", lightDesc.update.bind(lightDesc));
+      }
 
-    // Trigger re-render
-    lightDesc.on("needsUpdate", this.forceUpdate);
+      // Trigger re-render
+      lightDesc.on("needsUpdate", this.forceUpdate);
+
+      this.forceUpdate();
+    });
 
     const l = new LightHandle(lightDesc);
 
+    l.on("deleted", this.forceUpdate);
+
     // Store the light descriptor
     this.layersManager.add(l);
 
@@ -2194,18 +2283,26 @@ export default class ThreeView<
     // and recompiles shaders when the derived configuration actually changes,
     // so tune effects via `update()` rather than re-adding them.
     this._syncGBuffers();
-    l.on("deleted", this._syncGBuffers);
+    l.on("deleted", () => {
+      this._syncGBuffers();
+      this.forceUpdate();
+    });
 
-    // Initialize the effect
-    effectDesc.onCreate();
+    // Initialize the effect; hooks are wired once the instance exists.
+    this._trackAsyncCreate("effect", effectDesc, effectDesc.onCreate(), () => {
+      // Deleted while an async creation was loading — nothing to wire.
+      if (effectDesc.destroyed) return;
 
-    // Set up update listener if the descriptor has an update method
-    if (effectDesc.update) {
-      this.on("preRender", effectDesc.update.bind(effectDesc));
-    }
+      // Set up update listener if the descriptor has an update method
+      if (effectDesc.update) {
+        this.on("preRender", effectDesc.update.bind(effectDesc));
+      }
 
-    // Trigger re-render
-    effectDesc.on("needsUpdate", this.forceUpdate);
+      // Trigger re-render
+      effectDesc.on("needsUpdate", this.forceUpdate);
+
+      this.forceUpdate();
+    });
 
     // Return handle for imperative access
     return l as EffectHandle<L>;

package/src/material/enhancer/model/modelBaseEnhancer/shader.ts

@@ -52,7 +52,7 @@ export const transformShader = (
 #include <packing>
 
 in float batchId;
-out float nvr_vBatchId;
+flat out float nvr_vBatchId;
 out vec3 vPosition;
 
 ${ShowParsVertex}
@@ -93,7 +93,7 @@ uniform float nvr_uPickable;
 // uEffectIdsMask is declared by overrideMaterialsForMRT (#ifdef USE_SELECTIVE_EFFECT block)
 ${MODEL_BASE_SHADER_MARKERS.fragment.UNIFORM_END}
 
-in float nvr_vBatchId;
+flat in float nvr_vBatchId;
 
 ${ShowParsFragment}
 

package/src/material/enhancer/polygon/polygonBaseEnhancer/shader.ts

@@ -68,7 +68,7 @@ in float attrBatchId;
 in vec4 scaleNormalAndCap;
 
 uniform vec2 uMinMaxHeight;
-out float nvr_vBatchId;
+flat out float nvr_vBatchId;
 
 ${useRTE ? RteParsVertex : ""}
 ${ShowParsVertex}
@@ -162,7 +162,7 @@ uniform float nvr_uPickable;
 uniform bool uIsTexturized;
 ${POLYGON_BASE_SHADER_MARKERS.fragment.UNIFORM_END}
 
-in float nvr_vBatchId;
+flat in float nvr_vBatchId;
 
 ${ShowParsFragment}