@navaramap/three 0.0.8 → 0.1.0

package/dist/index.d.ts

@@ -995,8 +995,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 +1111,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 +1155,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 +1258,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);
     /**
@@ -1994,6 +2038,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 +3405,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 +3425,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 +3438,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 +3908,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 +4174,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 +4507,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 +4960,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 +5061,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 +5077,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 +5104,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 +5114,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 +5157,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>>;
 
 /**
@@ -6610,7 +6700,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) and the `featureHover` / `featureEnter` / `featureLeave`
+     * events (mousemove).
+     */
     picking?: boolean;
     /** When true, renders every frame. When false, renders only on changes or when forceUpdate() is called. */
     animation?: boolean;
@@ -7033,6 +7127,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 +7857,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 +7980,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 +8590,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 +9185,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"> & {
@@ -9300,6 +9433,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 +9693,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;
@@ -10006,7 +10153,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 +10171,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 +10197,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 +10221,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.
      */
@@ -10903,7 +11066,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 +11076,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 +11344,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 (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
+      * 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. */