@navaramap/three 0.0.6 → 0.0.7

package/dist/index.d.ts

@@ -29,6 +29,7 @@ import { FontWorkerMemoryStats } from '@navaramap/font';
 import { Geometry } from 'geojson';
 import { Group } from 'three';
 import { InstancedMesh as InstancedMesh_2 } from 'three';
+import { Intersection } from 'three';
 import { Light as Light_2 } from 'three';
 import { Line2 } from 'three-stdlib';
 import { Material } from 'three';
@@ -53,6 +54,7 @@ import { PlaneGeometry } from 'three';
 import { PointsMaterial } from 'three';
 import { PrecomputedTextures } from '@takram/three-atmosphere';
 import { Ray as Ray_3 } from 'three';
+import { Raycaster } from 'three';
 import { RenderPass as RenderPass_2 } from 'postprocessing';
 import { Scene } from 'three';
 import { ShaderLibShader } from 'three';
@@ -982,6 +984,8 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<Object3D> implemen
     private _labels;
     /** Sparse batchIndex → label; labels are created on first per-feature touch. */
     private _labelByIndex;
+    /** In-flight per-feature text preparations; see {@link whenLabelsSettled}. */
+    private _pendingTextPrepares;
     private _glyphs;
     private _slots;
     private _labelData;
@@ -989,6 +993,9 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<Object3D> implemen
     private _maxWidth;
     private _lineHeight;
     private _textAlign;
+    /** Labels currently parked in `prepareDeferred`, so the per-pass promotion
+     *  scan can bail without touching `_labels` when nothing is parked. */
+    private _deferredCount;
     /** Layer-level declutter settings, mirrored from the material. */
     private _declutter;
     private _declutterPriority;
@@ -1062,6 +1069,24 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<Object3D> implemen
      *  declutter pass to re-place on its next update. */
     private _markDeclutterDirty;
     setActive(active: boolean): void;
+    /**
+     * Resolves once every per-feature text preparation currently in flight has
+     * landed (glyph runs written), bounded by `timeoutMs`.
+     *
+     * The tile-LOD swap on the Rust side hides a parent tile the moment its
+     * children report rendered, so the caller must not report this batch
+     * rendered while labels are still shaping — the swap would show a batch
+     * that draws nothing (a tile-shaped blank).
+     *
+     * Only preparations already started are awaited. With declutter enabled,
+     * `setTextByBatchIndex` parks unprepared text until a placement pass
+     * confirms the anchor is on screen, so those labels are not yet in flight
+     * and this resolves immediately — cached text (the common case for a child
+     * tile repeating its parent's strings) applies synchronously and needs no
+     * wait either. The gate therefore only bites on the non-decluttered path;
+     * decluttered swaps rely on the placement handoff in {@link setActive}.
+     */
+    whenLabelsSettled(timeoutMs: number): Promise<void>;
     onBeforePicking(): void;
     onAfterPicking(): void;
     getRenderable(): Object3D;
@@ -1069,6 +1094,17 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<Object3D> implemen
     _update(m: TextMesh, needRender?: () => void): Promise<void>;
     private _applyUpdate;
     setTextByBatchIndex(batchIndex: number, text: string): void;
+    /** Kick off async font preparation for `text`, then lay it out — unless a
+     *  newer text supersedes it while the fonts load. */
+    private _prepareAndApply;
+    private _clearDeferred;
+    /**
+     * Promote parked labels whose anchor became potentially visible: start
+     * their font preparation and apply the text when it lands. Runs at the
+     * start of every placement pass (see {@link DeclutterParticipant}) — the
+     * cadence at which visibility can actually change.
+     */
+    prepareDeferredLabels(camera: PerspectiveCamera): void;
     setFeatureColorByBatchIndex(batchIndex: number, color: Color_3): void;
     setFeatureShowByBatchIndex(batchIndex: number, rawVisible: boolean): void;
     setFeatureHeightByBatchIndex(batchIndex: number, height: number): void;
@@ -2003,6 +2039,14 @@ declare class Core {
      * through the per-slot material path).
      */
     getRasterTileStates(handle: bigint): RasterTileState[];
+    /**
+     * Read back a stored source as the plain description object `addSource`
+     * accepts — including engine defaults and partial-update merges (inline
+     * GeoJSON `data` is not read back). `undefined` for unknown ids. Used by
+     * `view.sampleTerrainMostDetailed` to sample against the exact config
+     * the view renders with.
+     */
+    getSourceDescription(source_id: string): any;
     getTile(handle: bigint): TransferableTile | undefined;
     getTileElevationDecoder(handle: bigint): ElevationDecoder | undefined;
     getTransferablePolygonBatchedFeature(batched_feature_id: bigint): ReturnedTransferablePolygonBatchedFeature | undefined;
@@ -2560,6 +2604,13 @@ declare type DeclutterCandidate = {
     /** Participant-defined id (label slot for text batches, instance index for
      *  sprites) passed back to `applyDeclutter`. */
     handle: number;
+    /**
+     * Stable identity of what the candidate displays (label text for text
+     * batches). Feeds the manager's shown-content registry so a tile swap can
+     * hand placement over to the replacing batch's identical label without a
+     * hide/fade-in blink. Omit for candidates that don't participate.
+     */
+    contentKey?: string;
 };
 
 /**
@@ -2622,6 +2673,11 @@ declare class DeclutterManager {
      *  drift toggles frame to frame instead of flickering. Its full box is
      *  still claimed against competitors. */
     static readonly HYSTERESIS_PX = 6;
+    /** Anchor distance (m) within which two same-content candidates count as
+     *  the same label for the tile-swap handoff. Covers the anchor drift a
+     *  zoom level's tile-grid quantization (and per-tile terrain heights)
+     *  introduces, while staying far below distinct same-name places. */
+    static readonly HANDOFF_TOLERANCE_M = 2000;
     private _participants;
     /** Set when the label set changed (register/update/text change) so the next
      *  update re-places even with a static camera. */
@@ -2629,6 +2685,10 @@ declare class DeclutterManager {
     private _prevCamera;
     private _lastRunAt;
     private _lastStepAt;
+    /** Shown candidates of the most recent pass, keyed by content, as flat xyz
+     *  anchor triplets. Read by {@link wasRecentlyShown} when a tile swap
+     *  activates a replacement batch. */
+    private _shownByContent;
     private _candidates;
     /** Packed candidate input for the kernel; grows as the label count does. */
     private _input;
@@ -2648,6 +2708,15 @@ declare class DeclutterManager {
     /** Signal that candidates changed (text, positions, visibility, style) so
      *  the next update re-runs placement even if the camera is still. */
     markDirty(): void;
+    /**
+     * Whether the most recent pass showed `contentKey` anchored within
+     * {@link DeclutterManager.HANDOFF_TOLERANCE_M} of (x, y, z) — i.e. an
+     * equivalent label (typically the swapped-out tile's copy) already holds
+     * this screen space. A batch activating in a tile swap uses this to seed
+     * such labels as granted instead of fading them in from hidden, which
+     * would blink the whole tile's labels out for a pass-plus-fade.
+     */
+    wasRecentlyShown(contentKey: string, x: number, y: number, z: number): boolean;
     /**
      * Run a placement pass if one is due, then advance any active show/hide
      * fades. `widthPx`/`heightPx` are the viewport in CSS pixels (matching the
@@ -2683,6 +2752,14 @@ declare type DeclutterParticipant = {
      * anything is fading; returns true while any label is still mid-fade.
      */
     stepDeclutterFade: (deltaMs: number) => boolean;
+    /**
+     * Optional: start preparation (font loading, shaping) for labels that
+     * parked it while their anchor was out of view. Called at the start of
+     * every placement pass with the camera the pass will use — the cadence at
+     * which visibility can actually change. Preparation is asynchronous, so
+     * promoted labels join a *later* pass once their text is applied.
+     */
+    prepareDeferredLabels?: (camera: PerspectiveCamera) => void;
 };
 
 declare type DeclutterUpdateResult = 
@@ -3251,6 +3328,13 @@ export declare class EllipsoidGeodesic {
     constructor(start: LatLngHeight, end: LatLngHeight);
     /** Distance in meters between start and end points */
     get distance(): number;
+    /**
+     * Whether the geodesic solve converged. `false` for near-antipodal
+     * endpoints, where `distance` is only a rough estimate and the
+     * interpolation methods snap to the endpoints instead of following the
+     * unreliable solution.
+     */
+    get converged(): boolean;
     /** Heading at the start point in radians */
     get startHeading(): number;
     /** Heading at the end point in radians */
@@ -7194,7 +7278,10 @@ declare class PolygonMesh_2 {
 export declare class PolygonOutlineMesh extends Line2 implements FeatureMesh {
     readonly ctx: EventContext;
     private resizeEventUnsubscribe?;
+    /** True when the geometry carries RTE high/low positions (GeoJSON path). */
+    private useRTE;
     constructor(ctx: EventContext, mesh: PolygonMesh_2);
+    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
     private initGeometry;
     private initScaleNormalCapAttributes;
     private initMaterial;
@@ -8171,6 +8258,32 @@ export declare type RTEUserData = {
     };
 };
 
+export declare type SampledTerrainPosition = {
+    /** Latitude in radians, echoed from the input. */
+    lat: number;
+    /** Longitude in radians, echoed from the input. */
+    lng: number;
+    /**
+     * Terrain height in meters, or `undefined` when no tile covering the
+     * position could be fetched or decoded.
+     */
+    height: number | undefined;
+    /** Zoom level the height was sampled at; `undefined` on failure. */
+    level: number | undefined;
+};
+
+export declare type SampleTerrainOptions = {
+    /** Aborts in-flight tile fetches and rejects with the abort reason. */
+    signal?: AbortSignal;
+    /**
+     * Sample at this fixed zoom level instead of probing down from the
+     * source's `maxZoom`. A tile missing at this level yields `undefined`
+     * heights rather than falling back to a coarser level (Cesium's
+     * `sampleTerrain` semantics).
+     */
+    level?: number;
+};
+
 declare class SceneGroup extends Group {
     get tileScenes(): TileScene[];
 }
@@ -9675,10 +9788,29 @@ 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; height is ignored)
+     * @param pos - Geodetic position (lat in radians, lng in radians)
      * @returns Terrain height in meters, or undefined if terrain data not loaded
      */
-    sampleTerrainHeight(pos: LatLngHeight): number | undefined;
+    sampleTerrainHeight(pos: LatLng): number | undefined;
+    /**
+     * Samples terrain heights at the most detailed zoom level the terrain
+     * source provides, fetching the needed tiles over the network — unlike
+     * {@link sampleTerrainHeight}, which reads only tiles already resident for
+     * rendering and returns coarse-LOD heights (or nothing) when the camera is
+     * far away. Use this to place objects on the ground before the camera has
+     * streamed the area in.
+     *
+     * `source` is a registered `quantized-mesh` / `raster-dem` source: the
+     * {@link Source} handle returned by `addSource`, or its id. The stored
+     * config (including engine defaults and partial-update merges) is what gets
+     * sampled.
+     *
+     * @param source - A registered terrain source (handle or id)
+     * @param positions - Geodetic positions (lat/lng in radians)
+     * @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)
@@ -10313,9 +10445,13 @@ declare class TransferablePolygonGeometry {
 declare class TransferablePolygonOutlineGeometry {
     free(): void;
     [Symbol.dispose](): void;
-    constructor(position?: TransferableFloatAttribute | null, scale_normal_and_cap?: TransferableFloatAttribute | null, skip_indices?: number | null, batch_index?: TransferableFloatAttribute | null);
+    constructor(position?: TransferableFloatAttribute | null, position_3d_high?: TransferableFloatAttribute | null, position_3d_low?: TransferableFloatAttribute | null, scale_normal_and_cap?: TransferableFloatAttribute | null, skip_indices?: number | null, batch_index?: TransferableFloatAttribute | null);
     get batch_index(): TransferableFloatAttribute | undefined;
     set batch_index(value: TransferableFloatAttribute | null | undefined);
+    get position_3d_high(): TransferableFloatAttribute | undefined;
+    set position_3d_high(value: TransferableFloatAttribute | null | undefined);
+    get position_3d_low(): TransferableFloatAttribute | undefined;
+    set position_3d_low(value: TransferableFloatAttribute | null | undefined);
     get position(): TransferableFloatAttribute | undefined;
     set position(value: TransferableFloatAttribute | null | undefined);
     get scale_normal_and_cap(): TransferableFloatAttribute | undefined;
@@ -10414,7 +10550,7 @@ export declare type TransparentPassConfig = Description_4 & EffectConfig;
 
 export declare class TransparentPassEffectDesc extends EffectDesc<TransparentPassConfig, TransparentPassUpdate, RenderPass> {
     static key: string;
-    static insertAfter: string[];
+    static insertBefore: string[];
     light: Group< Object3DEventMap>;
     lightsSyncMap: Map<any, any>;
     createPass(): RenderPass;