@navaramap/three 0.0.7 → 0.1.0

package/dist/index.d.ts

@@ -122,6 +122,19 @@ export declare function appendOptionalGBufferAttachments(renderTarget: WebGLRend
 /** Applies a material's three-state `lit` option. */
 export declare function applyLitOption(material: Material, lit: boolean | undefined): void;
 
+/**
+ * `geodetic`, `matrix` and `matrixWorld` all claim the object's placement, so
+ * they share a single slot and at most one may be set. Every consumer resolves
+ * that slot with a priority chain (`applyTransform`, `applyRTETransform`), so
+ * allowing two would silently drop the lower-priority one — notably `matrix`
+ * under `matrixWorld`, which cannot be honoured at all once
+ * `matrixWorldAutoUpdate` is off. Takes the values rather than reading `this`,
+ * so a caller can check a prospective state before committing it. Exported so
+ * subclasses that override `onUpdateConfig` (e.g. RTE Descriptors like
+ * `GLTFModelDesc`) reuse this single check instead of hand-rolling their own.
+ */
+export declare function assertNoTransformConflict(geodetic: GeodeticPlacement | undefined, matrix: Matrix4 | undefined, matrixWorld: Matrix4 | undefined): void;
+
 /** Creates the per-tile MRT trio. Injected so tests can supply fakes. */
 declare type AtlasFactory = (size: number) => CompositeAtlas;
 
@@ -982,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;
@@ -1091,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;
@@ -1124,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;
@@ -1213,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);
     /**
@@ -1561,6 +1618,18 @@ export declare type CameraEvent = {
     frustumChanged: () => void;
 };
 
+/**
+ * Terminal record of a `flyTo` flight, delivered once through the event
+ * stream. `completed` is `false` when the flight was superseded or canceled.
+ */
+declare class CameraFlightEndedEvent {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    completed: boolean;
+    id: number;
+}
+
 export declare type CameraFrustum = Required<NormalizeWASMClass<CameraFrustum_3>>;
 
 declare class CameraFrustum_2 {
@@ -1569,6 +1638,9 @@ declare class CameraFrustum_2 {
     constructor(near: number, far: number, fov: number, aspect_ratio: number);
     aspect_ratio: number;
     far: number;
+    /**
+     * Vertical field of view in radians.
+     */
     fov: number;
     near: number;
 }
@@ -1579,6 +1651,9 @@ declare class CameraFrustum_3 {
     constructor(near: number, far: number, fov: number, aspect_ratio: number);
     aspect_ratio: number;
     far: number;
+    /**
+     * Vertical field of view in radians.
+     */
     fov: number;
     near: number;
 }
@@ -1865,6 +1940,15 @@ declare type ConcurrencyManager = {
     canDecrement: () => boolean;
 };
 
+/**
+ * Raised when a config or update names more than one of `geodetic` / `matrix` /
+ * `matrixWorld`. They share a single placement slot, so the message is
+ * deliberately symmetric — neither argument order implies a winner.
+ */
+export declare class ConflictingTransformError extends Error {
+    constructor(field: string, conflictsWith: string);
+}
+
 declare class ConstructPolygonBatchedFeatureParameters {
     private constructor();
     free(): void;
@@ -1954,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
@@ -2008,13 +2100,22 @@ declare class Core {
      * each from its `InMemoryBufferStore` map every frame.
      */
     drainRemovedExternalHandles(): Int32Array;
-    flyTo(position?: Float64Array | null, pitch?: number | null, heading?: number | null, roll?: number | null, duration?: number | null, max_height?: number | null, distance?: number | null): void;
+    /**
+     * Starts a camera flight and returns its id. A `CameraFlightEndedEvent`
+     * carrying the same id is delivered through the event stream when the
+     * flight completes (`completed: true`) or is superseded/canceled
+     * (`completed: false`).
+     */
+    flyTo(position?: Float64Array | null, pitch?: number | null, heading?: number | null, roll?: number | null, duration?: number | null, max_height?: number | null, distance?: number | null, easing?: number | null): number;
     genGlobalBatchId(): number | undefined;
     getBufferF32(handle: number): Float32Array | undefined;
     getBufferF64(handle: number): Float64Array | undefined;
     getBufferU32(handle: number): Uint32Array | undefined;
     getBufferU8(handle: number): Uint8Array | undefined;
-    getCameraFOVY(): number | undefined;
+    /**
+     * Vertical field of view in radians as set via `setFrustum`.
+     */
+    getCameraFOV(): number | undefined;
     getCameraOrientation(): CameraOrientation_2 | undefined;
     getCameraPositionECEF(): Float64Array | undefined;
     getCameraPositionLLE(): Float64Array | undefined;
@@ -3304,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);
@@ -3322,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 */
@@ -3335,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;
     /**
@@ -3475,6 +3578,7 @@ declare class EventContext {
     readonly viewEvents: EventHandler<ViewEvents>;
     readonly layersManager: LayersManager;
     readonly viewContext: ViewContext;
+    readonly flightHandler: FlightHandler;
     readonly layerHandler?: LayerHandler;
     readonly fontManager?: FontManager;
     readonly textureFragmentIndex?: Map<string, Set<TextureSlot>>;
@@ -3510,6 +3614,7 @@ declare type EventContextArgs = {
     viewEvents: EventHandler<ViewEvents>;
     layersManager: LayersManager;
     viewContext: ViewContext;
+    flightHandler: FlightHandler;
     layerHandler?: LayerHandler;
     fontManager?: FontManager;
     textureFragmentIndex?: Map<string, Set<TextureSlot>>;
@@ -3557,6 +3662,7 @@ declare class Events {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    take_camera_flight_ended(): CameraFlightEndedEvent[];
     take_camera_frustum_updated(): CameraFrustum_2 | undefined;
     take_camera_transform_updated(): Transform_2 | undefined;
     take_data_requested(): DataRequestEvent[];
@@ -3802,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;
@@ -3850,6 +3961,23 @@ export declare type FinalCopyPassConfig = Description & EffectConfig;
 
 export declare type FinalCopyPassUpdate = Description & EffectUpdate;
 
+/** Settles the pending `flyTo` promise registered under `id`. */
+declare type FlightHandler = (id: number, completed: boolean) => void;
+
+/** Easing presets applied to a `flyTo` flight's normalized time. */
+export declare type FlyToEasing = "linear" | "quadInOut" | "cubicInOut" | "cubicOut" | "quinticInOut";
+
+export declare type FlyToOptions = {
+    /** Animation duration in milliseconds. Defaults to a duration derived from
+     * the flight distance (2–3 s). Pass `0` to jump instantly. */
+    duration?: number;
+    /** Maximum height during the flight arc in meters. */
+    maxHeight?: number;
+    /** Easing preset. Defaults to `"quinticInOut"`, or `"cubicOut"` when
+     * descending from above 11,500 m. */
+    easing?: FlyToEasing;
+};
+
 export { FontFace_2 as FontFace }
 
 export { FontFamily }
@@ -4010,16 +4138,50 @@ export declare function generateTileMapFragment(maxTextures: number, features: T
  */
 export declare function generateTileNormalFragmentMaps(features: TileShaderFeatures): string;
 
+/**
+ * High-level geographic placement of a mesh object.
+ *
+ * All angles are in **degrees** and `height` is in metres, matching
+ * `ThreeView.setCamera`. The asset is oriented in a West-Up-North tangent
+ * frame, which matches glTF's own convention (front `+Z`, up `+Y`,
+ * right `-X`) on all three axes — so an unmodified glTF asset needs no
+ * up-axis correction.
+ */
+export declare type GeodeticPlacement = {
+    /** Longitude in degrees. */
+    lng: number;
+    /** Latitude in degrees. */
+    lat: number;
+    /**
+     * Metres above the ellipsoid, or above terrain when `heightReference` is
+     * `"terrain"`. Defaults to 0.
+     */
+    height?: number;
+    /**
+     * Degrees clockwise from north that the asset's front (glTF `+Z`) faces.
+     * Same convention as `setCamera`'s heading. Defaults to 0.
+     */
+    heading?: number;
+    /** Degrees, nose up positive. Defaults to 0. */
+    pitch?: number;
+    /** Degrees, right wing down positive. Defaults to 0. */
+    roll?: number;
+    /** Uniform or per-axis scale of the frame. Defaults to 1. */
+    scale?: number | XYZ;
+    /** How `height` is interpreted. Defaults to `"ellipsoid"`. */
+    heightReference?: "ellipsoid" | "terrain";
+};
+
 /**
  * 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;
@@ -4335,6 +4497,27 @@ declare type HandleEvent = {
     deleted: () => void;
 };
 
+/**
+ * Builds a WUN tangent frame at a geodetic position and composes heading,
+ * pitch, roll and scale onto it — the single call that turns a geographic
+ * placement into a world matrix.
+ *
+ * `heading` is the compass bearing the asset's front faces, where the front is
+ * glTF's own `+Z` — the same convention as `ThreeView.setCamera`. Other globe
+ * 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.
+ *
+ * `lng`/`lat` and all angles here are in **degrees**, matching
+ * `setCamera` and the `geodetic` mesh Descriptor field.
+ *
+ * `heightReference` is intentionally not accepted: resolving terrain-relative
+ * height needs a view to sample from, so it is the Descriptor's job.
+ *
+ * @param placement - Geographic placement in degrees and metres
+ * @returns 4x4 transformation matrix from the placed local frame to ECEF
+ */
+export declare function headingPitchRollToFixedFrame(placement: Omit<GeodeticPlacement, "heightReference">): Matrix4;
+
 declare class HillshadeBackfilledEvent {
     private constructor();
     free(): void;
@@ -4564,7 +4747,7 @@ export declare type InstancedMeshConfig = MeshConfigWithSelectiveEffect;
  * Per-instance variation is achieved through `instanceMatrix` (position, rotation, scale)
  * and `instanceColor` (per-instance color).
  *
- * The parent's transform fields (position, scale, rotation, matrix, matrixWorld)
+ * The parent's transform fields (position, scale, rotation, matrix, matrixWorld, geodetic)
  * define the parent coordinate space. Each instance's transform is local to the parent.
  *
  * Subclasses that maintain external per-instance state (e.g. picking batchIds)
@@ -4777,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;
@@ -4870,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;
@@ -4877,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`
@@ -4893,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
@@ -4903,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;
 }
 
@@ -4946,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>>;
 
 /**
@@ -5400,6 +5615,15 @@ declare class MemoryStats_2 {
     readonly sseMultiplier: number;
 }
 
+/**
+ * Merges a partial placement onto an existing one and checks it is complete.
+ * Pure — returns the merged value instead of assigning it, so the caller can
+ * validate before committing. Exported so subclasses that manage their own
+ * `onUpdateConfig` (e.g. `GLTFModelDesc`'s RTE-split transform) can merge a
+ * `geodetic` update with the same semantics instead of re-deriving them.
+ */
+export declare function mergeGeodetic(current: GeodeticPlacement | undefined, update: Partial<GeodeticPlacement>): GeodeticPlacement;
+
 declare class Mesh {
     private constructor();
     free(): void;
@@ -5517,6 +5741,9 @@ export declare type MeshConfig = {
      * Local frame. When combined with `position` / `rotation` / `scale`, the
      * effective local matrix is `matrix · T(position) · R(rotation) · S(scale)`.
      * Disables Three.js's auto matrix update.
+     *
+     * Mutually exclusive with `matrixWorld` and `geodetic`: all three define the
+     * object's placement.
      */
     matrix?: Matrix4;
     /**
@@ -5525,8 +5752,25 @@ export declare type MeshConfig = {
      * matrix is `matrixWorld · T(position) · R(rotation) · S(scale)`, so the
      * offset fields are interpreted in the frame's local coordinates.
      * Disables Three.js's auto matrix-world update.
+     *
+     * Mutually exclusive with `matrix` and `geodetic`: all three define the
+     * object's placement.
      */
     matrixWorld?: Matrix4;
+    /**
+     * High-level geographic placement in degrees and metres. Builds a
+     * West-Up-North tangent frame at `lng`/`lat`/`height` and applies
+     * `heading`/`pitch`/`roll`/`scale`, then occupies the same slot as
+     * `matrixWorld` — so `position` / `rotation` / `scale` remain offsets
+     * *inside* the resulting frame.
+     *
+     * `heading` is the compass bearing the asset's front (glTF `+Z`) faces, the
+     * same convention as `setCamera`. Because the frame is Y-up with `+Z` north,
+     * an unmodified glTF asset needs no up-axis correction.
+     *
+     * Mutually exclusive with `matrix` and `matrixWorld`.
+     */
+    geodetic?: GeodeticPlacement;
     /**
      * Lighting override for every material of the mesh. `false` outputs albedo
      * only, while normals and the shadow G-buffer keep being written.
@@ -5658,7 +5902,7 @@ export declare type MeshConfigWithSelectiveEffect = MeshConfig & {
  *    The base class applies position/scale/rotation and adds it to the scene
  *    determined by {@link getPassKey}.
  * 3. **{@link onUpdateConfig}** - Called when `handle.update()` is invoked. The base class
- *    handles `visible`, `matrix`, `matrixWorld`, `position`, `scale`, and `rotation`; override to handle your
+ *    handles `visible`, `matrix`, `matrixWorld`, `position`, `scale`, `rotation`, and `geodetic`; override to handle your
  *    custom properties. Always call `super.onUpdateConfig(updates)`.
  * 4. **{@link update}** - Optional per-frame callback for animation.
  * 5. **{@link onResize}** - Optional callback when the viewport is resized.
@@ -5684,10 +5928,51 @@ export declare abstract class MeshDesc<Config extends MeshConfig = MeshConfig, U
     rotation?: XYZ;
     matrix?: Matrix4;
     matrixWorld?: Matrix4;
+    geodetic?: GeodeticPlacement;
+    /** Terrain height under `geodetic`, when `heightReference` is `"terrain"`. */
+    protected terrainHeight?: number;
+    private terrainUnsubscribe?;
     /** Three-state `lit` override (see {@link MeshConfig.lit}). */
     lit?: boolean;
     private prevPassKey?;
     constructor(view: ThreeView, ctx: ViewContext, config?: Config);
+    /**
+     * Builds the world frame for a {@link GeodeticPlacement}, adding
+     * {@link terrainHeight} when one has been observed. This method does not
+     * gate on `heightReference` itself — `terrainHeight` is only ever populated
+     * for a terrain-referenced placement, and is cleared otherwise.
+     *
+     * Fields are passed explicitly rather than spread: `headingPitchRollToFixedFrame`
+     * rejects `heightReference`, which this class resolves itself.
+     */
+    protected resolveGeodeticFrame(g: GeodeticPlacement): Matrix4;
+    /**
+     * Subscribes to terrain height under a terrain-referenced `geodetic`
+     * placement.
+     *
+     * `sampleTerrainHeight` seeds synchronously from tiles already resident, so
+     * the object does not sit at the wrong altitude while tiles stream in; the
+     * observer then re-places it on every terrain update. With no terrain layer
+     * added, the sample is `undefined` and the observer does not fire until a
+     * terrain layer is added, so the placement degrades to ellipsoid-relative
+     * rather than failing — terrain layers may be added after the object.
+     *
+     * Protected (not private) so a subclass that manages its own world-matrix
+     * representation for `geodetic` (e.g. `GLTFModelDesc`'s RTE position split)
+     * can call it directly from its own `onCreate`/`onUpdateConfig` instead of
+     * routing through this class's `onCreate`.
+     */
+    protected subscribeTerrainHeight(): void;
+    /**
+     * Re-applies the effective transform after `geodetic`'s resolved frame
+     * changes outside of `onUpdateConfig` — currently only a terrain-height
+     * observation firing asynchronously. Subclasses that override
+     * `applyTransform`'s effect with their own representation (e.g.
+     * `GLTFModelDesc`'s RTE position/rotation split, which needs the *encoded*
+     * position refreshed too) override this instead of relying on the default.
+     */
+    protected reapplyGeodeticFrame(): void;
+    private unsubscribeTerrainHeight;
     /**
      * Applies {@link lit} to every material under the mesh. Subclasses that
      * attach materials asynchronously (glTF) call it again once they exist.
@@ -5726,12 +6011,17 @@ export declare abstract class MeshDesc<Config extends MeshConfig = MeshConfig, U
     /**
      * Applies the configured transform to the underlying `Object3D`.
      *
-     * When `matrixWorld` (or `matrix`) is set together with any of
+     * When `matrixWorld` / `geodetic` (or `matrix`) is set together with any of
      * `position` / `rotation` / `scale`, the base/frame is left-multiplied
      * by the local `T · R · S`: e.g. `effective = matrixWorld · T · R · S`.
      * This lets callers pass a frame (such as an NUE-to-ECEF matrix) as
      * `matrixWorld` and express offsets inside that frame via
      * `position` / `rotation` / `scale`.
+     *
+     * The branches below are a priority chain, which is only safe because
+     * `assertNoTransformConflict` has already rejected any state with more than
+     * one of `geodetic` / `matrixWorld` / `matrix` set — so an earlier branch
+     * can never shadow a configured field.
      */
     private applyTransform;
     removeFromScene(passKey: PassKey): void;
@@ -5805,7 +6095,14 @@ declare type MeshHandler = {
     setTileMeshPrepared: (handle: bigint) => void;
 };
 
-export declare type MeshUpdate = Pick<MeshConfig, "position" | "scale" | "rotation" | "matrix" | "matrixWorld" | "lit"> & BaseDescConfigUpdate;
+export declare type MeshUpdate = Pick<MeshConfig, "position" | "scale" | "rotation" | "matrix" | "matrixWorld" | "lit"> & {
+    /**
+     * Partial geographic placement, merged into the stored placement — so
+     * `update({ geodetic: { heading } })` keeps the existing lng/lat/height.
+     * `lng` and `lat` are required only when the object has no placement yet.
+     */
+    geodetic?: Partial<GeodeticPlacement>;
+} & BaseDescConfigUpdate;
 
 export declare type MeshUpdateWithSelectiveEffect = MeshUpdate & {
     effectIds?: string[];
@@ -6403,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;
@@ -6826,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);
     /**
@@ -7544,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);
     /**
@@ -7651,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;
@@ -8259,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
@@ -8854,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"> & {
@@ -9093,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);
     /**
@@ -9338,6 +9690,11 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
     private _declutterRetryDelay;
     private _isIdle;
     private _uniforms;
+    /** 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;
@@ -9755,16 +10112,24 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
     moveCameraWithDirection(dir: number[], amount: number): void;
     /**
      * Animates the camera to fly to a target position.
+     *
+     * The flight follows an arced path: the default duration is derived from
+     * the flight distance (2–3 s), the default easing is `quinticInOut`
+     * (`cubicOut` when descending from high altitude), and longitudes take the
+     * short way across the antimeridian.
+     *
      * @param camPos - Target position with required lng/lat (degrees). Provide either `height` (meters above the ellipsoid)
      *   or `distance` (meters from the target point along the camera forward direction). Optional pitch, heading, roll (degrees).
-     * @param duration - Animation duration in milliseconds
-     * @param maxHeight - Maximum height during the flight arc in meters
+     * @param options - Flight options (`duration`, `maxHeight`, `easing`)
+     * @returns A promise resolving to `true` when the flight completes, or
+     *   `false` when it is interrupted by another camera operation, such as a
+     *   newer `flyTo` or a `setCamera` call.
      */
     flyTo(camPos: CameraPosition & Required<Pick<CameraPosition, "lng" | "lat">> & ({
         height: number;
     } | {
         distance: number;
-    }), duration?: number, maxHeight?: number): void;
+    }), options?: FlyToOptions): Promise<boolean>;
     /**
      * Makes the camera look at a target position with an offset.
      * @param target - Target geodetic position (lng in degrees, lat in degrees, height in meters)
@@ -9788,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;
@@ -9806,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
      */
@@ -9832,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.
      */
@@ -9845,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.
      */
@@ -9888,13 +10269,18 @@ declare class ThreeViewCamera extends EventHandler<CameraEvent> {
     get positionECEF(): XYZ;
     get positionGeographic(): LatLngHeight;
     get orientation(): CameraOrientation;
-    get fovy(): number | undefined;
     /**
      * Effective Web Mercator zoom level the camera is viewing the surface at
      * (fractional). Computed engine-side from the camera's ellipsoid height (not
      * terrain), FOV and viewport.
      */
     get zoom(): number | undefined;
+    /**
+     * The vertical field of view in degrees; the horizontal extent follows
+     * from the viewport aspect ratio.
+     * Reading returns `undefined` until the engine camera exists.
+     */
+    get fov(): number | undefined;
     set fov(val: number);
     set near(val: number);
     get near(): number;
@@ -10680,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;
 
@@ -10690,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
@@ -10958,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. */
@@ -11022,6 +11424,21 @@ export declare class UnknownTypeError extends Error {
      timeUniform?: UniformValue<number>;
  };
 
+ /**
+  * Creates a local West-Up-North (WUN) reference frame transformation matrix at
+  * a position.
+  *
+  * WUN is the only right-handed, Y-up tangent frame whose `+Z` axis is north, so
+  * it agrees with glTF's own convention (front `+Z`, up `+Y`, right `-X`) on all
+  * three axes. An unmodified glTF asset placed in this frame needs **no**
+  * `Rx(+90°)` up-axis correction — the correction is absorbed here, once, as the
+  * `Ry(+90°)` basis change from NUE.
+  *
+  * @param origin - Origin position in ECEF coordinates
+  * @returns 4x4 transformation matrix from WUN to ECEF
+  */
+ export declare function westUpNorthToFixedFrame(origin: Vector3): Matrix4;
+
  declare type Window_2 = Required<NormalizeWASMClass<Window_3>>;
  export { Window_2 as Window }