@navaramap/three 0.1.0 → 0.1.1

package/README.md

@@ -11,8 +11,8 @@ Navara's answer to the trade-off is a tiered API. Capabilities are organized int
 
 Under the hood, Navara is a headless GIS core, independent of the rendering engine. The complex but reusable GIS logic (data parsing, geometry construction, and more) lives in Rust / WebAssembly, and drawing is delegated to libraries specialized in CG rendering. This package is the Three.js-based binding and the main entry point for building Navara applications. Its public API is `ThreeView` plus a declarative Source/Layer/Descriptor model.
 
-- 📖 **Documentation**: https://navara-docs.reearth.workers.dev/
-- 🌏 **Live examples**: https://navara-preview.reearth.workers.dev/
+- 📖 **Documentation**: https://navara.world/docs/
+- 🌏 **Live examples**: https://navara.world/examples/
 
 ## Install
 
@@ -64,7 +64,7 @@ view.attribution?.add([
 ]);
 ```
 
-See [What is Navara?](https://navara-docs.reearth.workers.dev/guides/introduction/what-is-navara/) for an overview and [Getting Started](https://navara-docs.reearth.workers.dev/guides/introduction/getting-started/) to build your first 3D map.
+See [What is Navara?](https://navara.world/docs/guides/introduction/what-is-navara/) for an overview and [Getting Started](https://navara.world/docs/guides/introduction/getting-started/) to build your first 3D map.
 
 ## Related packages
 
@@ -75,7 +75,7 @@ See [What is Navara?](https://navara-docs.reearth.workers.dev/guides/introductio
 
 ## Documentation
 
-Full documentation, including every source/layer/material option and runnable examples, is at https://navara-docs.reearth.workers.dev/.
+Full documentation, including every source/layer/material option and runnable examples, is at https://navara.world/docs/.
 
 ## License
 

package/dist/index.d.ts

@@ -798,12 +798,25 @@ export declare abstract class BaseDesc<Config extends BaseDescConfig = BaseDescC
     /** The underlying Three.js instance. */
     protected _instance: Instance | undefined;
     private _visible?;
+    private _destroyed;
     constructor(view: ThreeView, ctx: ViewContext, config?: Config);
     /**
      * 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.
-     */
-    abstract onCreate(): void;
+     *
+     * 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 | Promise<void>;
     /**
      * Called when the configuration is updated via `BaseHandle.update()`.
      * Override this to handle custom configuration updates.
@@ -816,6 +829,12 @@ export declare abstract class BaseDesc<Config extends BaseDescConfig = BaseDescC
      * Override this to clean up resources. Remember to call `super.onDestroy()`.
      */
     onDestroy(): void;
+    /**
+     * 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;
     /**
      * Gets whether this is currently visible.
      */
@@ -1687,6 +1706,14 @@ declare class CameraStatus {
 
 export { CascadedShadowMaps }
 
+/**
+ * Travel tolerance in CSS pixels between pointerdown and pointerup to count as a click.
+ * Follows Cesium's `_clickPixelTolerance` (MapLibre uses 3px).
+ * ref: https://github.com/CesiumGS/cesium/blob/9fda7ab97a762e40c74b1d0e1814c98a2de43337/packages/engine/Source/Core/ScreenSpaceEventHandler.js#L1012
+ * ref: https://github.com/maplibre/maplibre-gl-js/blob/3a0a4f795fef5b2a29034d71833475589c344eaf/src/ui/map.ts#L542
+ */
+export declare const CLICK_PIXEL_TOLERANCE = 5;
+
 export declare const CLOUD_LOCAL_WEATHER_URL: string;
 
 export declare const CLOUD_SHAPE_DETAIL_URL: string;
@@ -5493,12 +5520,13 @@ export declare type LUT = readonly (ColorTuple | Color_2)[];
 export declare const MAPBOX_ELEVATION_DECODER: () => ElevationDecoder;
 
 /**
- * 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 declare type MapMouseEvent = {
-    /** World coordinates (ECEF) at the mouse position on the globe surface. */
+export declare type MapPointerEvent = {
+    /** World coordinates (ECEF) at the pointer position on the globe surface. */
     map: XYZ;
-} & MouseEvent;
+} & PointerEvent;
 
 /**
  * Core abstraction: Material enhancer with shader type constraints
@@ -6702,8 +6730,8 @@ export declare type Options = {
     backgroundColor?: Color_2;
     /**
      * 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. */
@@ -6889,6 +6917,13 @@ export declare class Pass<P extends Pass_2, E extends Effect_2 | unknown, O exte
 
 export declare type PassKey = keyof Pick<Scenes, "opaque" | "transparent" | "mrt" | "skyEnvMap" | "draped">;
 
+/**
+ * Pick search radius in CSS pixels around the pointer. The pick reads a
+ * (2r+1)² window and takes the non-zero batch id closest to its center, so
+ * small features (points, thin lines) don't demand pixel-perfect aim.
+ */
+export declare const PICK_RADIUS = 3;
+
 /**
  * Turnkey {@link PickableMesh} implementation for `InstancedMesh`.
  *
@@ -9238,6 +9273,13 @@ declare type SupportedMaterial_6 = ShaderMaterial;
  */
 declare type SupportedMaterial_7 = ShaderMaterial;
 
+/**
+ * Travel tolerance for touch taps. Finger contact jitters far more than a
+ * mouse, so follows MapLibre's tap `MAX_DIST` instead.
+ * ref: https://github.com/maplibre/maplibre-gl-js/blob/3a0a4f795fef5b2a29034d71833475589c344eaf/src/ui/handler/tap_recognizer.ts
+ */
+export declare const TAP_PIXEL_TOLERANCE = 30;
+
 /**
  * Temporary DEM state while waiting for edge updates.
  * Stores only the WASM buffer handle and received edge strips — NOT the full padded DEM.
@@ -9772,9 +9814,9 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
     set lit(value: boolean);
     constructor(options?: Options);
     /**
-     * Convert a mouse event to a MapMouseEvent by adding map coordinates
+     * Extend a pointer event with map coordinates at its location
      */
-    private convertMouseEventToMapEvent;
+    private convertToMapEvent;
     private initializeRenderPass;
     private get renderPass();
     /** The camera controller that manages view position, orientation, and projection. */
@@ -9924,6 +9966,18 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
      * @returns A Source handle for referencing, updating, and deleting the source
      */
     addSource(s: SourceDescription): Source;
+    /**
+     * 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;
     /**
      * Adds a 3D mesh to the scene.
      * The mesh kind is determined by the nested key (e.g., `{ box: { width: 200 } }`).
@@ -10723,6 +10777,9 @@ declare class TileXYZ {
     z: number;
 }
 
+/** Pick search radius for touch: fingertips land less precisely than a cursor. */
+export declare const TOUCH_PICK_RADIUS = 10;
+
 declare type TransactionCallbackParams<AddKey extends JsEventsKey, RemoveKey extends JsEventsKey, ChangeKey extends JsEventsKey> = {
     type: "add";
     event: GetJsEventValue<AddKey>;
@@ -11345,13 +11402,13 @@ export declare class UnknownTypeError extends Error {
      /** 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` /
@@ -11374,18 +11431,26 @@ export declare class UnknownTypeError extends Error {
      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;
  };