@navaramap/three 0.0.8 → 0.1.1

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.
      */
@@ -995,8 +1014,15 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<Object3D> implemen
     private _transform;
     /** Labels in slot order — `_labels[slot]` is also the declutter handle map. */
     private _labels;
-    /** Sparse batchIndex → label; labels are created on first per-feature touch. */
-    private _labelByIndex;
+    /** Sparse anchor slot → label; labels are created on first per-feature touch. */
+    private _labelByInstance;
+    /**
+     * Feature (batch) index → this feature's anchor slots. A feature owns
+     * multiple anchors for MultiPoint geometry and for labels derived from
+     * line/polygon vertices via `geometryTypes`, so per-feature styling must fan
+     * out to all of them. `null` means anchors and features are 1:1.
+     */
+    private _batchIndexToInstances;
     /** In-flight per-feature text preparations; see {@link whenLabelsSettled}. */
     private _pendingTextPrepares;
     private _glyphs;
@@ -1104,9 +1130,20 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<Object3D> implemen
     onAfterPicking(): void;
     getRenderable(): Object3D;
     private extractPositions;
+    /**
+     * Group anchor slots by their feature's batch index from the geometry's
+     * per-anchor `batch_index` buffer. The u32 view is consumed synchronously —
+     * other wasm calls may detach views, so it must not be stored. An identity
+     * mapping (every feature owns exactly one anchor, the common MVT case) skips
+     * the map entirely.
+     */
+    private _rebuildBatchIndexMap;
+    /** All anchor slots owned by the feature at `batchIndex`. */
+    private _instancesOfBatchIndex;
     _update(m: TextMesh, needRender?: () => void): Promise<void>;
     private _applyUpdate;
     setTextByBatchIndex(batchIndex: number, text: string): void;
+    private _setTextByInstance;
     /** Kick off async font preparation for `text`, then lay it out — unless a
      *  newer text supersedes it while the fonts load. */
     private _prepareAndApply;
@@ -1137,6 +1174,20 @@ declare class BatchPropResult {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * The picked feature's canonical global batch id (its first instance's
+     * id). A picked instance of a multi-instance feature (e.g. MultiPoint)
+     * carries its own id, while styling APIs report the canonical one, so
+     * consumers correlate picks through this field.
+     */
+    get batchId(): number | undefined;
+    /**
+     * The picked feature's canonical global batch id (its first instance's
+     * id). A picked instance of a multi-instance feature (e.g. MultiPoint)
+     * carries its own id, while styling APIs report the canonical one, so
+     * consumers correlate picks through this field.
+     */
+    set batchId(value: number | null | undefined);
     get layerId(): string | undefined;
     set layerId(value: string | null | undefined);
     properties: any;
@@ -1226,6 +1277,18 @@ declare class BillboardMaterial {
      * Emissive glow intensity (default: 0.3 when Bloom enabled)
      */
     set emissiveIntensity(value: number | null | undefined);
+    /**
+     * Source geometry types this appearance consumes: `"point"`, `"line"`,
+     * `"polygon"`. Defaults to `["point"]`; adding `"line"`/`"polygon"` also
+     * emits a billboard per line-string / polygon-ring vertex.
+     */
+    get geometryTypes(): string[] | undefined;
+    /**
+     * Source geometry types this appearance consumes: `"point"`, `"line"`,
+     * `"polygon"`. Defaults to `["point"]`; adding `"line"`/`"polygon"` also
+     * emits a billboard per line-string / polygon-ring vertex.
+     */
+    set geometryTypes(value: string[] | null | undefined);
     get height(): number | undefined;
     set height(value: number | null | undefined);
     /**
@@ -1643,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;
@@ -1994,6 +2065,14 @@ declare type ConvertColorFields<T> = {
     [K in keyof T]: K extends `${string}Color` | "color" ? T[K] extends number | undefined ? Color | undefined : T[K] extends number ? Color : T[K] : T[K] extends object | undefined ? ConvertColorFields<T[K]> | Extract<T[K], undefined> : T[K];
 };
 
+/**
+ * Helper type to narrow the generated `geometryTypes?: string[]` material
+ * fields to the {@link SourceGeometryType} literal union.
+ */
+declare type ConvertGeometryTypeFields<T> = {
+    [K in keyof T]: K extends "geometryTypes" ? SourceGeometryType[] | Extract<T[K], undefined> : T[K] extends object | undefined ? ConvertGeometryTypeFields<T[K]> | Extract<T[K], undefined> : T[K];
+};
+
 /**
  * Converts screen coordinates to world coordinates by raycasting against the WGS84 ellipsoid.
  * @param window - Window configuration with width, height, and pixelRatio
@@ -3353,11 +3432,13 @@ declare class ElevationHeatmapMaterial {
  * Wrapper class for geodesic calculations on an ellipsoid surface.
  * Precomputes common variables for optimization when instantiated.
  *
+ * All latitudes/longitudes and headings are in **degrees**.
+ *
  * @example
  * ```typescript
  * const geodesic = new EllipsoidGeodesic(
- *   { lat: 0.5, lng: 2.0, height: 0 },
- *   { lat: 0.6, lng: 2.1, height: 0 }
+ *   { lat: 35.6812, lng: 139.7671, height: 0 },
+ *   { lat: 34.7025, lng: 135.4959, height: 0 }
  * );
  *
  * console.log(geodesic.distance);
@@ -3371,8 +3452,8 @@ export declare class EllipsoidGeodesic {
     private _raw;
     /**
      * Create a new geodesic between two points on the ellipsoid.
-     * @param start - Start point in geodetic coordinates (lat/lng in radians)
-     * @param end - End point in geodetic coordinates (lat/lng in radians)
+     * @param start - Start point in geodetic coordinates (lat/lng in degrees)
+     * @param end - End point in geodetic coordinates (lat/lng in degrees)
      */
     constructor(start: LatLngHeight, end: LatLngHeight);
     /** Distance in meters between start and end points */
@@ -3384,24 +3465,24 @@ export declare class EllipsoidGeodesic {
      * unreliable solution.
      */
     get converged(): boolean;
-    /** Heading at the start point in radians */
+    /** Heading at the start point in degrees */
     get startHeading(): number;
-    /** Heading at the end point in radians */
+    /** Heading at the end point in degrees */
     get endHeading(): number;
-    /** Start point in geodetic coordinates */
+    /** Start point in geodetic coordinates (lat/lng in degrees) */
     get start(): LatLngHeight;
-    /** End point in geodetic coordinates */
+    /** End point in geodetic coordinates (lat/lng in degrees) */
     get end(): LatLngHeight;
     /**
      * Interpolate points along the geodesic path.
      * @param granularity - Distance between interpolated points in meters (optional)
-     * @returns Array of interpolated points in geodetic coordinates
+     * @returns Array of interpolated points in geodetic coordinates (lat/lng in degrees)
      */
     interpolatePoints(granularity?: number): LatLngHeight[];
     /**
      * Interpolate a point at a specific distance along the geodesic path.
      * @param distance - Distance from start point in meters
-     * @returns Interpolated point in geodetic coordinates
+     * @returns Interpolated point in geodetic coordinates (lat/lng in degrees)
      */
     interpolateDistance(distance: number): LatLngHeight;
     /**
@@ -3854,6 +3935,11 @@ declare type FeatureHandler = {
  * Information about a feature batch, passed to evaluation callbacks.
  */
 export declare type FeatureInfo = {
+    /**
+     * The feature's canonical global batch id (its first instance's id when a
+     * feature spans several instances, e.g. MultiPoint). Pick events report the
+     * same canonical id, so picks and evaluations correlate through this field.
+     */
     batchId: number;
     properties: Record<string, unknown> | undefined;
     layerId: LayerId | undefined;
@@ -4115,14 +4201,14 @@ export declare type GeodeticPlacement = {
 
 /**
  * Computes the surface normal vector at a geodetic position on the WGS84 ellipsoid.
- * @param lle - Geodetic coordinates (lng in radians, lat in radians, height in meters)
+ * @param lle - Geodetic coordinates (lng in degrees, lat in degrees, height in meters)
  * @returns Unit normal vector pointing outward from the ellipsoid surface
  */
 export declare function geodeticSurfaceNormal(lle: LatLngHeight): Vector3;
 
 /**
  * Converts geodetic coordinates (longitude, latitude, height) to a Cartesian Vector3 in ECEF coordinates.
- * @param lle - Geodetic coordinates (lng in radians, lat in radians, height in meters)
+ * @param lle - Geodetic coordinates (lng in degrees, lat in degrees, height in meters)
  * @returns Cartesian Vector3 in Earth-Centered Earth-Fixed (ECEF) coordinates
  */
 export declare function geodeticToVector3(lle: LatLngHeight): Vector3;
@@ -4448,7 +4534,6 @@ declare type HandleEvent = {
  * engines differ in which axis they treat as an asset's front, so a model
  * ported from one may need a multiple of 90° added to its heading.
  *
- * NOTE: unlike {@link geodeticToVector3} and the other helpers in this module,
  * `lng`/`lat` and all angles here are in **degrees**, matching
  * `setCamera` and the `geodetic` mesh Descriptor field.
  *
@@ -4902,7 +4987,15 @@ export declare type InstancedSpriteMaterialProps = {
 
 export declare class InstancedSpriteMesh extends Mesh_2<BufferGeometry, Material | Material[], CustomObject3DEventMap> implements PickableMesh, DeclutterParticipant {
     private _geometryType;
-    private _batchIdToInstance;
+    /**
+     * Feature (batch) index → this feature's instance ids. A feature owns
+     * multiple instances for MultiPoint geometry and for points derived from
+     * line/polygon vertices via `geometryTypes`, so per-feature styling must
+     * fan out to all of them. `null` means instances and features are 1:1.
+     */
+    private _batchIndexToInstances;
+    /** Instance count of the current geometry; bounds the identity fallback. */
+    private _instanceCount;
     private _initialColor;
     private _initialHeight;
     private _initialSize;
@@ -4995,6 +5088,15 @@ export declare class InstancedSpriteMesh extends Mesh_2<BufferGeometry, Material
      * hasn't been overridden per-feature via setFeatureImageByBatchId.
      */
     private _setDefaultImage;
+    /**
+     * An instance's atlas rect changed. The rect drives the quad's aspect and
+     * whether the instance draws at all, so the declutter bounds computed before
+     * the image landed are stale — and because packs resolve long after the
+     * frame that requested them, the view has usually gone idle by now. Without
+     * the render request the page keeps showing the pre-image state until the
+     * next camera move.
+     */
+    private _onAtlasRectsChanged;
     onBeforePicking(): void;
     onAfterPicking(): void;
     getRenderable(): Object3D;
@@ -5002,10 +5104,21 @@ export declare class InstancedSpriteMesh extends Mesh_2<BufferGeometry, Material
      * Get the enhancer, throwing if not initialized.
      */
     private getEnhancer;
-    setFeatureColorByBatchId(batchId: number, color: Color_3): void;
-    setFeatureShowByBatchId(batchId: number, rawVisible: boolean): void;
-    setFeatureOpacityByBatchId(batchId: number, opacity: number): void;
-    setFeatureHeightByBatchId(batchId: number, height: number): void;
+    /**
+     * Group instances by their feature's batch index from the geometry's
+     * per-instance `batch_index` buffer. The u32 view is consumed synchronously,
+     * so other wasm calls may detach views, so it must not be stored. The handle
+     * stays owned by the ECS geometry, whose destroy path frees it
+     * (`remove_from_buf`). An identity mapping (every feature owns exactly one
+     * instance, the common case) skips the map entirely.
+     */
+    private _rebuildBatchIndexMap;
+    /** All instances owned by the feature at `batchIndex`; empty when unknown. */
+    private instancesOfBatchIndex;
+    setFeatureColorByBatchIndex(batchIndex: number, color: Color_3): void;
+    setFeatureShowByBatchIndex(batchIndex: number, rawVisible: boolean): void;
+    setFeatureOpacityByBatchIndex(batchIndex: number, opacity: number): void;
+    setFeatureHeightByBatchIndex(batchIndex: number, height: number): void;
     /**
      * Set one instance's declutter fade target; the attribute animates toward
      * it in {@link stepDeclutterFade}. Deliberately separate from the `show`
@@ -5018,8 +5131,8 @@ export declare class InstancedSpriteMesh extends Mesh_2<BufferGeometry, Material
      * layer-level `declutterPriority` for this instance. Driven by the feature
      * evaluator.
      */
-    setFeatureDeclutterPriorityByBatchId(batchId: number, priority: number): void;
-    setFeatureSizeByBatchId(batchId: number, size: number): void;
+    setFeatureDeclutterPriorityByBatchIndex(batchIndex: number, priority: number): void;
+    setFeatureSizeByBatchIndex(batchIndex: number, size: number): void;
     /**
      * Give one feature its own image, packed into this mesh's texture atlas.
      * Loads are deduplicated by URL, so styling many features with few distinct
@@ -5028,7 +5141,7 @@ export declare class InstancedSpriteMesh extends Mesh_2<BufferGeometry, Material
      * reverts the feature to the material's default image. No-op for
      * non-billboard (point) meshes.
      */
-    setFeatureImageByBatchId(batchId: number, url: string | null | undefined): Promise<void>;
+    setFeatureImageByBatchIndex(batchIndex: number, url: string | null | undefined): Promise<void>;
     dispose(): void;
 }
 
@@ -5071,8 +5184,12 @@ export declare type LabelLayout = {
     maxYEm: number;
 };
 
+/** Geodetic position: `lat`/`lng` in **degrees**. */
 export declare type LatLng = Omit<LatLngHeight, "height">;
 
+/**
+ * Geodetic position: `lat`/`lng` in **degrees**, `height` in meters.
+ */
 export declare type LatLngHeight = Required<NormalizeWASMClass<LLE>>;
 
 /**
@@ -5403,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
@@ -6610,7 +6728,11 @@ export declare type Options = {
     atmosphere?: AtmosphereOptions;
     /** Background color of the scene. Defaults to dark color (0x0a0a0f). */
     backgroundColor?: Color_2;
-    /** Feature picking configuration. */
+    /**
+     * Feature picking configuration (default: true). Enables the `featureClick`
+     * 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. */
     animation?: boolean;
@@ -6795,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`.
  *
@@ -7033,6 +7162,18 @@ declare class PointMaterial {
      * Emissive glow intensity (default: 0.3 when Bloom enabled)
      */
     set emissiveIntensity(value: number | null | undefined);
+    /**
+     * Source geometry types this appearance consumes: `"point"`, `"line"`,
+     * `"polygon"`. Defaults to `["point"]`; adding `"line"`/`"polygon"` also
+     * emits a point per line-string / polygon-ring vertex.
+     */
+    get geometryTypes(): string[] | undefined;
+    /**
+     * Source geometry types this appearance consumes: `"point"`, `"line"`,
+     * `"polygon"`. Defaults to `["point"]`; adding `"line"`/`"polygon"` also
+     * emits a point per line-string / polygon-ring vertex.
+     */
+    set geometryTypes(value: string[] | null | undefined);
     get height(): number | undefined;
     set height(value: number | null | undefined);
     /**
@@ -7751,6 +7892,22 @@ declare class PolylineMaterial {
      * Emissive glow intensity (default: 0.3 when Bloom enabled)
      */
     set emissiveIntensity(value: number | null | undefined);
+    /**
+     * Source geometry types this appearance consumes: `"line"`, `"polygon"`.
+     * Defaults to `["line"]`; adding `"polygon"` also renders polygon boundary
+     * rings (outer ring and holes) as closed polylines at the ring's base
+     * height. Extruded-polygon edges stay the polygon material's `outline`
+     * feature.
+     */
+    get geometryTypes(): string[] | undefined;
+    /**
+     * Source geometry types this appearance consumes: `"line"`, `"polygon"`.
+     * Defaults to `["line"]`; adding `"polygon"` also renders polygon boundary
+     * rings (outer ring and holes) as closed polylines at the ring's base
+     * height. Extruded-polygon edges stay the polygon material's `outline`
+     * feature.
+     */
+    set geometryTypes(value: string[] | null | undefined);
     get height(): number | undefined;
     set height(value: number | null | undefined);
     /**
@@ -7858,6 +8015,8 @@ export declare class PolylineMesh extends BatchedFeatureMesh<BufferGeometry<Attr
     get emissiveColor(): number;
     get emissiveIntensity(): number;
     get effectIdsMask(): number;
+    /** Visible stroke width to restore after a pick-pass width bump. */
+    private _pickSavedWidth?;
     onBeforePicking(pickingCoord?: Vector2): void;
     onAfterPicking(): void;
     _getDefaultBatchAttributeValues(): DefaultBatchAttributeValues;
@@ -8466,9 +8625,9 @@ export declare type RTEUserData = {
 };
 
 export declare type SampledTerrainPosition = {
-    /** Latitude in radians, echoed from the input. */
+    /** Latitude in degrees, echoed from the input. */
     lat: number;
-    /** Longitude in radians, echoed from the input. */
+    /** Longitude in degrees, echoed from the input. */
     lng: number;
     /**
      * Terrain height in meters, or `undefined` when no tile covering the
@@ -9061,6 +9220,15 @@ declare class SourceDescription_2 {
     set type(value: string | null | undefined);
 }
 
+/**
+ * Source geometry categories a vector appearance can consume via its
+ * `geometryTypes` option. Each appearance defaults to its native geometry only
+ * (`"point"` for point/billboard/text, `"line"` for polyline); adding entries
+ * derives extra representations, e.g. `polyline: { geometryTypes: ["line",
+ * "polygon"] }` also renders polygon boundary rings as polylines.
+ */
+export declare type SourceGeometryType = "point" | "line" | "polygon";
+
 export declare type SourceLayerBase<Layer extends {
     source?: string | undefined;
 }> = Omit<Layer, "source"> & {
@@ -9105,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.
@@ -9300,6 +9475,18 @@ declare class TextMaterial {
      * is specified.
      */
     set font(value: string | null | undefined);
+    /**
+     * Source geometry types this appearance consumes: `"point"`, `"line"`,
+     * `"polygon"`. Defaults to `["point"]`; adding `"line"`/`"polygon"` also
+     * emits a label per line-string / polygon-ring vertex.
+     */
+    get geometryTypes(): string[] | undefined;
+    /**
+     * Source geometry types this appearance consumes: `"point"`, `"line"`,
+     * `"polygon"`. Defaults to `["point"]`; adding `"line"`/`"polygon"` also
+     * emits a label per line-string / polygon-ring vertex.
+     */
+    set geometryTypes(value: string[] | null | undefined);
     get height(): number | undefined;
     set height(value: number | null | undefined);
     /**
@@ -9548,6 +9735,8 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
     /** Pending `flyTo` promises keyed by flight id, settled by
      *  `camera_flight_ended` events from the engine. */
     private _pendingFlights;
+    /** Currently hovered feature, used to diff-synthesize hover events. */
+    private _hoveredFeature;
     private _meshes;
     private _abortControllers;
     private _workerPoolPromises;
@@ -9625,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. */
@@ -9777,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 } }`).
@@ -10006,7 +10207,7 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
     cameraFreeLook(enabled: boolean, target?: LatLngHeight): void;
     /**
      * Samples the terrain height at a given geodetic position synchronously.
-     * @param pos - Geodetic position (lat in radians, lng in radians)
+     * @param pos - Geodetic position (lat in degrees, lng in degrees)
      * @returns Terrain height in meters, or undefined if terrain data not loaded
      */
     sampleTerrainHeight(pos: LatLng): number | undefined;
@@ -10024,14 +10225,14 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
      * sampled.
      *
      * @param source - A registered terrain source (handle or id)
-     * @param positions - Geodetic positions (lat/lng in radians)
+     * @param positions - Geodetic positions (lat/lng in degrees)
      * @param options - Optional abort signal and fixed-level sampling
      * @returns One result per input position, in the same order
      */
     sampleTerrainMostDetailed(source: SourceRef, positions: LatLng[], options?: SampleTerrainOptions): Promise<SampledTerrainPosition[]>;
     /**
      * Observes terrain height changes at a position. Callback is invoked each time terrain data updates.
-     * @param pos - Geodetic position to observe (lat in radians, lng in radians)
+     * @param pos - Geodetic position to observe (lat in degrees, lng in degrees)
      * @param cb - Callback function receiving the terrain height in meters
      * @returns Cleanup function to stop observing
      */
@@ -10050,11 +10251,22 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
     private _startMainLoop;
     private _getCanvasSize;
     private _handleResize;
+    /**
+     * Resolves a picked batch ID into feature information via the engine's
+     * property store.
+     */
+    private resolvePickedFeature;
     /**
      * Handles pick events and emits the picked feature information.
      * @param pickArr - Array of picked batch IDs
      */
     private onPick;
+    /**
+     * Handles hover pick results and synthesizes `featureHover` / `featureEnter` /
+     * `featureLeave` events by diffing against the previously hovered feature.
+     * @param pickArr - Array of picked batch IDs
+     */
+    private onHoverPick;
     /**
      * Gets whether continuous animation mode is enabled.
      */
@@ -10063,6 +10275,11 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
      * Sets whether to render every frame continuously (true) or only on changes (false).
      */
     set animation(v: boolean);
+    /**
+     * Gets the canvas element the view renders into. Useful for styling,
+     * e.g. switching the cursor from a `featureHover` event listener.
+     */
+    get canvas(): HTMLCanvasElement;
     /**
      * Gets the current screen size in pixels.
      */
@@ -10560,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>;
@@ -10903,7 +11123,7 @@ export declare class UnknownTypeError extends Error {
  /**
   * Converts a Cartesian Vector3 in ECEF coordinates to geodetic coordinates.
   * @param xyz - Cartesian Vector3 in Earth-Centered Earth-Fixed (ECEF) coordinates
-  * @returns Geodetic coordinates (lng in radians, lat in radians, height in meters)
+  * @returns Geodetic coordinates (lng in degrees, lat in degrees, height in meters)
   */
  export declare function vector3ToGeodetic(xyz: Vector3): LatLngHeight;
 
@@ -10913,9 +11133,9 @@ export declare class UnknownTypeError extends Error {
   */
  export declare type VectorLayer = SourceLayerBase<VectorLayerBase>;
 
- declare type VectorLayerBase = WithColorSupport<Layer_2<VectorLayerDescription & {
+ declare type VectorLayerBase = WithColorSupport<ConvertGeometryTypeFields<Layer_2<VectorLayerDescription & {
      type: "vector";
- }>>;
+ }>>>;
 
  /**
   * A `vector` layer references a `geojson` or `vector-tile` source and renders
@@ -11181,8 +11401,24 @@ export declare class UnknownTypeError extends Error {
  export declare 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 picked. Receives picked feature info or null. */
-     pick: (info: Nullable<PickedFeature>) => void;
+     /**
+      * 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 (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` /
+      * `featureEnter` / `featureLeave` listener is registered.
+      */
+     featureHover: (info: Nullable<PickedFeature>) => void;
+     /** Emitted when the pointer starts hovering a pickable feature. See `featureHover` for activation. */
+     featureEnter: (info: PickedFeature) => void;
+     /** Emitted when the pointer stops hovering the previously hovered feature. See `featureHover` for activation. */
+     featureLeave: (info: PickedFeature) => void;
      /** Emitted when a layer event occurs. Receives event type, layer ID, and event arguments. */
      layer: <K extends keyof LayerEvent>(k: K, layerId: string, ...args: Parameters<LayerEvent[K]>) => void;
      /** Emitted before an update process happens. Receives `DOMHighResTimeStamp` as a timestamp. */
@@ -11195,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;
  };