@navaramap/three 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -224,6 +224,40 @@ export declare class Atmosphere extends EventHandler<AtmosphereEvents> {
      * @returns `true` if the position is on the night side, `false` otherwise.
      */
     isAtNight(position: XYZ): boolean;
+    /**
+     * Returns the sun's elevation angle in degrees above the local horizon at
+     * `location` for the current {@link date}. Positive is above the horizon,
+     * negative below (night); includes atmospheric refraction.
+     *
+     * @example
+     * const elevation = view.atmosphere.getSunElevation(view.camera.positionGeographic);
+     * if (elevation < 0) console.log("The sun has set.");
+     */
+    getSunElevation(location: {
+        lat: number;
+        lng: number;
+    }): number;
+    /**
+     * Returns the local apparent solar time at `lng` for the current
+     * {@link date}, in hours in the range [0, 24) where 12 is solar noon.
+     * Accounts for the equation of time.
+     *
+     * @example
+     * const hours = view.atmosphere.getSolarTime({ lng: 139.69 }); // e.g. 6.3 = 06:18
+     */
+    getSolarTime(location: {
+        lng: number;
+    }): number;
+    /**
+     * Sets {@link date} so the local apparent solar time at `lng` equals `hours`
+     * (0–24), keeping the same solar day. Inverse of {@link getSolarTime}.
+     *
+     * @example
+     * view.atmosphere.setSolarTime({ lng: 139.69 }, 6.3); // sunrise over Tokyo
+     */
+    setSolarTime(location: {
+        lng: number;
+    }, hours: number): void;
     /**
      * Gets the current date used for calculating sun/moon positions.
      */
@@ -863,7 +897,7 @@ export declare class BatchedFeatureMesh<Buf extends BufferGeometry<BatchedFeatur
     clone(): this;
 }
 
-export declare class BatchedSdfTextMesh extends InstancedMesh<SDFTextMesh> implements PickableMesh {
+export declare class BatchedSdfTextMesh extends InstancedMesh<SDFTextMesh> implements PickableMesh, DeclutterParticipant {
     readonly ctx: EventContext;
     /** The font identifier from material — may be a family name or a URL. */
     private _fontIdentifier;
@@ -881,7 +915,23 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<SDFTextMesh> imple
      * and must be balanced with unloadFont() on dispose or font change.
      */
     private _loadedFaceUrls;
+    /** Geometry-extracted anchor data; per-index meshes slice it lazily. */
+    private _positions;
+    /** Sparse batchIndex → mesh; `allMeshes` holds only created meshes. */
+    private _meshByIndex;
+    /** Evaluator state received before a feature's mesh exists. */
+    private _pending;
+    /** Material/transform used when creating meshes lazily. */
+    private _material;
+    private _transform;
     constructor(ctx: EventContext, m: TextMesh, fontIdentifier: string, options: InstancedMeshOptions, loadedFaceUrls?: Set<string>);
+    collectDeclutterCandidates(out: DeclutterCandidate[]): void;
+    applyDeclutter(handle: number, hidden: boolean): void;
+    stepDeclutterFade(deltaMs: number): boolean;
+    /** Candidates changed (text, style, position, visibility): ask the shared
+     *  declutter pass to re-place on its next update. */
+    private _markDeclutterDirty;
+    setActive(active: boolean): void;
     /**
      * After an atlas eviction, re-prepare and force-rebuild any visible mesh whose
      * shaped text is now stale (its pinned glyphs may have been evicted before the
@@ -891,17 +941,48 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<SDFTextMesh> imple
     private _revalidateStaleMeshes;
     get fontIdentifier(): string;
     get highQuality(): boolean;
+    /**
+     * A mesh per anchor is expensive (geometry + ShaderMaterial + enhancer
+     * mount), and with per-feature texts (MVT) most features never receive a
+     * non-empty text — they'd sit invisible while still costing construction and
+     * every per-frame loop. So meshes are created lazily by `_ensureMeshAt` on
+     * the first non-empty `setTextByBatchIndex`. Only a non-empty material-level
+     * default text (single-label sources) renders without the evaluator ever
+     * setting text, so only that case creates all meshes eagerly.
+     */
     private initMeshes;
+    /** The font-level shared atlas textures for this batch's font+quality (the
+     *  color atlas is `null` for monochrome fonts). */
+    private _sharedTextures;
+    /**
+     * The feature's mesh, created on first need (see `initMeshes`). `shared`
+     * lets a batch creation pass hoist the atlas lookups; when omitted (a single
+     * lazy creation) they are fetched here, since the atlas may have been
+     * (re)allocated since this batch was constructed.
+     */
+    private _ensureMeshAt;
+    /** Pending-state slot for a feature whose mesh doesn't exist yet. */
+    private _pendingAt;
     _update(m: TextMesh, needRender?: () => void): Promise<void>;
     private _applyUpdate;
     onBeforePicking(): void;
     onAfterPicking(): void;
     private extractPositions;
     setTextByBatchIndex(batchIndex: number, text: string): void;
+    /**
+     * The mesh for a feature's `batchIndex`, or `undefined` if not created yet.
+     * Meshes are created lazily and pushed onto `allMeshes` in creation order, so
+     * `allMeshes[batchIndex]` (the base-class mapping) does NOT hold here; the
+     * batchIndex→mesh mapping lives in `_meshByIndex`. Overriding this one
+     * accessor keeps the base-class setters and any external caller (picking,
+     * plugins) correct without patching each call site.
+     */
+    getMeshByBatchIndex(batchIndex: number): SDFTextMesh | undefined;
     setFeatureColorByBatchIndex(batchIndex: number, color: Color_3): void;
     setFeatureShowByBatchIndex(batchIndex: number, rawVisible: boolean): void;
     setFeatureHeightByBatchIndex(batchIndex: number, height: number): void;
     setFeatureSizeByBatchIndex(batchIndex: number, size: number): void;
+    setFeatureDeclutterPriorityByBatchIndex(batchIndex: number, priority: number): void;
     setFeatureOpacityByBatchIndex(batchIndex: number, opacity: number): void;
     dispose(): void;
 }
@@ -951,6 +1032,28 @@ declare class BillboardMaterial {
     set clampToGround(value: boolean | null | undefined);
     get color(): number | undefined;
     set color(value: number | null | undefined);
+    /**
+     * Placement priority for decluttering; higher wins. Only meaningful when
+     * `declutter` is enabled. Defaults to `0.0`.
+     */
+    get declutterPriority(): number | undefined;
+    /**
+     * Placement priority for decluttering; higher wins. Only meaningful when
+     * `declutter` is enabled. Defaults to `0.0`.
+     */
+    set declutterPriority(value: number | null | undefined);
+    /**
+     * Participate in screen-space decluttering: when labels/sprites overlap
+     * on screen, lower-priority ones are hidden. Defaults to `true`; set to
+     * `false` to draw every label unconditionally.
+     */
+    get declutter(): boolean | undefined;
+    /**
+     * Participate in screen-space decluttering: when labels/sprites overlap
+     * on screen, lower-priority ones are hidden. Defaults to `true`; set to
+     * `false` to draw every label unconditionally.
+     */
+    set declutter(value: boolean | null | undefined);
     get depthTest(): boolean | undefined;
     set depthTest(value: boolean | null | undefined);
     /**
@@ -1868,6 +1971,13 @@ declare class Core {
      */
     setDynamicSse(settings: DynamicSse): void;
     setExternalBuffer(handle: number, bits: bigint, byte_length: number): void;
+    /**
+     * Reports the estimated GPU bytes of fixed, screen-sized allocations
+     * (the postprocessing render-target stack). Counted in the ledger's
+     * usage so the tile budget binds against the remaining memory. The JS
+     * side re-reports on init, resize, and pass-list changes.
+     */
+    setFixedGpuBytes(bytes: number): void;
     setFrustum(fov?: number | null, near?: number | null, far?: number | null): void;
     setGlobeColor(value: number): void;
     setGlobeElevationColormap(value: Float32Array): void;
@@ -2175,7 +2285,7 @@ export declare class CustomRenderPass extends RenderPass {
     constructor(scenes: Scenes, camera: PerspectiveCamera, inputBuffer: WebGLRenderTarget, globe: Globe, options?: CustomRenderPassOptions);
     protected _renderWithLight(renderer: WebGLRenderer, scene: Scene): void;
     render(renderer: WebGLRenderer, inputBuffer: WebGLRenderTarget | null, _outputBuffer: WebGLRenderTarget | null): void;
-    setDepthTexture(depthTexture: DepthTexture): void;
+    setDepthTexture(): void;
     setSize(width: number, height: number): void;
     protected _renderDrapedMesh(renderer: WebGLRenderer): void;
 }
@@ -2245,6 +2355,179 @@ declare class DataRequestEvent {
     url: string;
 }
 
+/**
+ * One label/sprite competing for screen space in a declutter pass.
+ *
+ * The local box is expressed around the projected anchor in the shader's
+ * billboard-local units — CSS pixels when `sizeInMeters` is false, meters
+ * otherwise — with +X right and +Y up (view-space convention). The manager
+ * converts it to a screen-pixel AABB using the same `nvr_pxToWorld` math the
+ * vertex shaders use, so the collision box matches what is actually drawn.
+ */
+declare type DeclutterCandidate = {
+    /** World-space anchor in ECEF meters (f64), before the height offset. */
+    anchorX: number;
+    anchorY: number;
+    anchorZ: number;
+    /** Extra offset in meters along the spherical surface normal — CPU mirror
+     *  of `mvr_getMvHeightOffset` (sprite_height_pars_vertex.glsl). */
+    addHeight: number;
+    /** Local box around the anchor (px or meters, see `sizeInMeters`). */
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    /** Unit of the local box, mirroring the material's `sizeInMeters`. */
+    sizeInMeters: boolean;
+    /** Placement priority: higher wins an overlap. */
+    priority: number;
+    /** Whether the label is currently shown (its fade target is "visible").
+     *  Feeds placement hysteresis: shown labels win equal-priority ties and
+     *  tolerate marginal overlaps, so slow camera drift doesn't make near-tied
+     *  labels flicker in and out. */
+    isShown: boolean;
+    /** Participant that owns this candidate; receives the placement result. */
+    owner: DeclutterParticipant;
+    /** Participant-defined id (mesh index for text batches, instance index for
+     *  sprites) passed back to `applyDeclutter`. */
+    handle: number;
+};
+
+/**
+ * The pure numeric placement kernel used by {@link DeclutterManager}.
+ *
+ * Given a flat list of candidates and the camera, it projects each anchor to a
+ * screen-pixel box, sorts by priority (with placement hysteresis), and greedily
+ * claims space in a uniform screen-space grid — returning one `hidden` flag
+ * (`0` = shown, `1` = hidden) per candidate, in input order.
+ *
+ * The production implementation is the Rust `declutterPlace` in
+ * `navara_wasm_api` (see {@link wasmDeclutterKernel}); the projection, collision
+ * grid, and greedy placement all live there. Injecting it keeps the manager free
+ * of an import-time WASM dependency, so its orchestration is unit-tested with a
+ * stub. Placement correctness itself is covered by the crate's Rust tests.
+ */
+declare type DeclutterKernel = {
+    /**
+     * @param candidates Packed `f64` data, {@link CANDIDATE_STRIDE} values per
+     *   candidate; pass a subarray of exactly `n * CANDIDATE_STRIDE`.
+     * @param view Column-major view matrix (inverse of `camera.matrixWorld`), 16.
+     * @param proj Column-major projection matrix, 16.
+     * @returns One `hidden` flag (`0`/`1`) per candidate, in input order.
+     */
+    place(candidates: Float64Array, view: Float64Array, proj: Float64Array, cameraX: number, cameraY: number, cameraZ: number, near: number, widthPx: number, heightPx: number, fovRad: number, paddingPx: number, hysteresisPx: number): Uint8Array;
+};
+
+/**
+ * Shared screen-space label decluttering.
+ *
+ * Text batches and sprite meshes register as participants; each placement
+ * pass packs every candidate label into a flat buffer and hands it to the
+ * Rust {@link DeclutterKernel}, which projects the anchors, sorts by priority,
+ * and greedily claims screen space — losers are hidden through the meshes'
+ * declutter channels (`uDeclutterHide` uniform / `instanceDeclutterHide`
+ * attribute), which are separate from user-driven `show` state and free to
+ * toggle every pass.
+ *
+ * Placement is hysteretic: currently-shown labels win equal-priority ties
+ * and tolerate {@link DeclutterManager.HYSTERESIS_PX} of marginal overlap
+ * before eviction, so near-ties don't flicker while the camera drifts.
+ *
+ * The pass is view-dependent, so it runs from the render loop — but throttled:
+ * placement only re-runs when the camera or the label set actually changed,
+ * and at most once per {@link DeclutterManager.MIN_INTERVAL_MS}. Callers run
+ * it *before* rendering so results land in the same frame.
+ */
+declare class DeclutterManager {
+    private readonly _kernel;
+    /** Minimum time between placement passes (ms). */
+    static readonly MIN_INTERVAL_MS = 150;
+    /** Padding added around every collision box (px); two labels never sit
+     *  closer than twice this. */
+    static readonly PADDING_PX = 2;
+    /** Largest single fade step (ms), so a frame after an idle gap doesn't
+     *  swallow most of a fade in one jump. */
+    static readonly MAX_FADE_STEP_MS = 50;
+    /** Placement hysteresis (px): a currently-shown label's collision test box
+     *  shrinks by this per side, so it survives marginal overlaps that camera
+     *  drift toggles frame to frame instead of flickering. Its full box is
+     *  still claimed against competitors. */
+    static readonly HYSTERESIS_PX = 6;
+    private _participants;
+    /** Set when the label set changed (register/update/text change) so the next
+     *  update re-places even with a static camera. */
+    private _dirty;
+    private _prevCamera;
+    private _lastRunAt;
+    private _lastStepAt;
+    private _candidates;
+    /** Packed candidate input for the kernel; grows as the label count does. */
+    private _input;
+    private _viewMatrix;
+    private _view16;
+    private _proj16;
+    /** @param _kernel the placement kernel — the Rust-backed
+     *  `wasmDeclutterKernel` in production, a stub in unit tests. */
+    constructor(_kernel: DeclutterKernel);
+    /** Milliseconds until the throttle window since the last placement pass
+     *  elapses, clamped to `[0, MIN_INTERVAL_MS]`. Callers use this to schedule
+     *  a follow-up frame after a `"throttled"` result without overshooting the
+     *  window by waiting out the full constant from now. */
+    remainingThrottleMs(nowMs: number): number;
+    register(participant: DeclutterParticipant): void;
+    unregister(participant: DeclutterParticipant): void;
+    /** Signal that candidates changed (text, positions, visibility, style) so
+     *  the next update re-runs placement even if the camera is still. */
+    markDirty(): void;
+    /**
+     * 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
+     * `uScreenHeightPx` uniform); `nowMs` is the frame timestamp used for
+     * throttling and fade stepping.
+     */
+    update(camera: PerspectiveCamera, widthPx: number, heightPx: number, nowMs: number): DeclutterUpdateResult;
+    private _run;
+    /** Drop all registered participants. Call when the owning view is disposed
+     *  so this manager doesn't keep strong references to removed meshes (and
+     *  their GPU/font resources) past the view's lifetime. */
+    dispose(): void;
+    private _snapshotChanged;
+    private _takeSnapshot;
+}
+
+/** A mesh that contributes label candidates to the shared declutter pass. */
+declare type DeclutterParticipant = {
+    /**
+     * Append the currently-visible, declutter-enabled candidates to `out`.
+     * Called once per placement pass; must not retain `out`.
+     */
+    collectDeclutterCandidates: (out: DeclutterCandidate[]) => void;
+    /**
+     * Apply a placement result as the label's fade *target*. Must be cheap and
+     * idempotent — the pass calls it for every candidate on every run, most
+     * often with an unchanged value.
+     */
+    applyDeclutter: (handle: number, hidden: boolean) => void;
+    /**
+     * Advance this participant's hide factors toward their targets by
+     * `deltaMs / DECLUTTER_FADE_MS`. Called by the manager every update while
+     * anything is fading; returns true while any label is still mid-fade.
+     */
+    stepDeclutterFade: (deltaMs: number) => boolean;
+};
+
+declare type DeclutterUpdateResult = 
+/** Nothing to do: no participants, or camera and data unchanged. */
+"idle"
+/** A placement pass ran; results are applied to the participants. */
+| "ran"
+/** Labels are mid-fade — the caller should schedule a prompt follow-up
+*  frame so the animation keeps stepping. */
+| "animating"
+/** A pass is due but the throttle window hasn't elapsed — the caller should
+*  schedule another frame so placement settles after the camera stops. */
+| "throttled";
+
 export declare const DEFAULT_EFFECT_OPTIONS: Required<EffectOptions>;
 
 export declare type DefaultBatchAttributeValues = {
@@ -2854,6 +3137,9 @@ export declare type EvaluatableMaterialProperty = {
     size: AvailableMaterialProperty["size"];
     /** Opacity expression from layer configuration (for polygons/points/text where supported). */
     opacity: AvailableMaterialProperty["opacity"];
+    /** Per-feature declutter placement priority (for points/billboards/text);
+     *  higher wins an overlap. Overrides the layer's `declutterPriority`. */
+    declutterPriority: AvailableMaterialProperty["declutterPriority"];
     /** Image URL for billboards; packed into a shared per-mesh texture atlas. */
     image: string;
 };
@@ -2869,6 +3155,7 @@ declare type EvaluatedMaterialProperty = {
     width: number;
     size: number;
     opacity: number;
+    declutterPriority: number;
     image: string | null;
 };
 
@@ -2912,6 +3199,9 @@ declare class EventContext {
     readonly textureFragmentIndex?: Map<string, Set<TextureSlot>>;
     readonly tileMeshToFragmentIds?: Map<TileMesh, Set<string>>;
     readonly hillshadeContext?: HillshadeContext;
+    /** Shared screen-space label declutterer; text/sprite meshes register as
+     *  participants on creation. Optional so headless contexts can skip it. */
+    readonly declutter?: DeclutterManager;
     updatedAt: number;
     constructor(args: EventContextArgs);
 }
@@ -2944,6 +3234,7 @@ declare type EventContextArgs = {
     textureFragmentIndex?: Map<string, Set<TextureSlot>>;
     tileMeshToFragmentIds?: Map<TileMesh, Set<string>>;
     hillshadeContext?: HillshadeContext;
+    declutter?: DeclutterManager;
 };
 
 export declare class EventHandler<T extends BaseEventMap = BaseEventMap, K extends keyof T = keyof T> {
@@ -3146,6 +3437,8 @@ export declare class FeatureEvaluator {
      * - `width` - Line width in pixels (for polylines)
      * - `size` - Feature size in pixels (for points/text)
      * - `opacity` - Feature opacity 0-1
+     * - `declutterPriority` - Placement priority for decluttering; higher wins
+     *   an overlap (for points/billboards/text with `declutter` enabled)
      * - `image` - Image URL (for billboards); loaded once per distinct URL and
      *   packed into the layer's texture atlas. Return `null` to clear a
      *   previous per-feature image and revert to the material's default `url`;
@@ -3328,6 +3621,18 @@ declare class GeoJsonLayerDescription {
     get crs(): string | undefined;
     set crs(value: string | null | undefined);
     data: any;
+    /**
+     * Per-layer horizon dynamic-SSE relaxation strength for the tiled render
+     * path (`0.0` off … `1.0` raster-equivalent). Omit for a content-based
+     * default.
+     */
+    get dynamicSseScale(): number | undefined;
+    /**
+     * Per-layer horizon dynamic-SSE relaxation strength for the tiled render
+     * path (`0.0` off … `1.0` raster-equivalent). Omit for a content-based
+     * default.
+     */
+    set dynamicSseScale(value: number | null | undefined);
     get point(): PointMaterial | undefined;
     set point(value: PointMaterial | null | undefined);
     get polygon(): PolygonMaterial | undefined;
@@ -3816,7 +4121,7 @@ export declare class InstancedMesh<M extends Object3D> extends Mesh_2 implements
     addWithBatchIndex(m: M, batchIndex: number): void;
     markVisibility(m: M): void;
     meshes(): M[];
-    getMeshByBatchIndex(batchIndex: number): M;
+    getMeshByBatchIndex(batchIndex: number): M | undefined;
     setFeatureColorByBatchIndex(batchIndex: number, color: Color_3): void;
     setFeatureShowByBatchIndex(batchIndex: number, rawVisible: boolean): void;
     setFeatureHeightByBatchIndex(batchIndex: number, height: number): void;
@@ -3995,6 +4300,8 @@ declare type InstancedSpriteBaseRefs = {
     uRTCCenterView: UniformValue<Vector3>;
     uEyeRTELow: UniformValue<Vector3>;
     uEyeRTEHigh: UniformValue<Vector3>;
+    /** Always 1.0 — blocks fast-math reassociation of the RTE recombination. */
+    u_rteOne?: UniformValue<number>;
     uScale: UniformValue<number>;
     uCenter: UniformValue<Vector2>;
     uSizeInMeters: UniformValue<boolean>;
@@ -4044,7 +4351,7 @@ export declare type InstancedSpriteMaterialProps = {
     base?: InstancedSpriteBaseProps;
 };
 
-export declare class InstancedSpriteMesh extends Mesh_2 implements PickableMesh {
+export declare class InstancedSpriteMesh extends Mesh_2<BufferGeometry, Material | Material[], CustomObject3DEventMap> implements PickableMesh, DeclutterParticipant {
     private _batchIdToInstance;
     private _initialColor;
     private _initialHeight;
@@ -4068,8 +4375,31 @@ export declare class InstancedSpriteMesh extends Mesh_2 implements PickableMesh
     readonly ctx: EventContext;
     /** Material enhancer for encapsulated state management */
     private _enhancedMaterial?;
+    /** Per-instance world anchors in ECEF meters (f64, 3 per instance), kept in
+     *  sync with the position attributes for the declutter pass. */
+    private _anchors;
+    /** Whether this mesh's instances participate in screen-space decluttering. */
+    private _declutter;
+    /** Layer-level placement priority from the material. */
+    private _declutterPriority;
+    /** Per-instance priorities set through the evaluator (NaN = no override,
+     *  fall back to the layer value). Lazily allocated on first use. */
+    private _declutterPriorityOverrides;
+    /** Per-instance fade targets for `instanceDeclutterHide` (0 = shown,
+     *  1 = hidden); the attribute animates toward these in stepDeclutterFade. */
+    private _declutterTargets;
+    /** True while any instance's hide factor may differ from its target. */
+    private _declutterAnimating;
     constructor(options: InstancedSpriteOptions);
     setActive(active: boolean): void;
+    collectDeclutterCandidates(out: DeclutterCandidate[]): void;
+    applyDeclutter(handle: number, hidden: boolean): void;
+    stepDeclutterFade(deltaMs: number): boolean;
+    private _cacheDeclutterState;
+    private _clearDeclutterHidden;
+    /** Reconstruct absolute ECEF anchors from the same arrays the position
+     *  attributes receive (RTE high+low split, or RTC-relative + center). */
+    private _cacheAnchors;
     _init(m: PointMesh | BillboardMesh): Promise<void>;
     _update(m: PointMesh | BillboardMesh): Promise<void>;
     private _initGeometry;
@@ -4109,6 +4439,19 @@ export declare class InstancedSpriteMesh extends Mesh_2 implements PickableMesh
     setFeatureShowByBatchId(batchId: number, rawVisible: boolean): void;
     setFeatureOpacityByBatchId(batchId: number, opacity: number): void;
     setFeatureHeightByBatchId(batchId: number, height: number): void;
+    /**
+     * Set one instance's declutter fade target; the attribute animates toward
+     * it in {@link stepDeclutterFade}. Deliberately separate from the `show`
+     * component of `instanceParams` so user-driven visibility and declutter
+     * results compose instead of clobbering each other.
+     */
+    setDeclutterHiddenByInstance(instanceIndex: number, hidden: boolean): void;
+    /**
+     * Set a per-feature placement priority (higher wins), overriding the
+     * layer-level `declutterPriority` for this instance. Driven by the feature
+     * evaluator.
+     */
+    setFeatureDeclutterPriorityByBatchId(batchId: number, priority: number): void;
     setFeatureSizeByBatchId(batchId: number, size: number): void;
     /**
      * Give one feature its own image, packed into this mesh's texture atlas.
@@ -4241,7 +4584,7 @@ declare type LayerId = string;
 declare class LayersManager {
     private layers;
     add(l: Layer | BaseHandle): void;
-    get(id: string): Layer | BaseHandle<BaseDesc<BaseDescConfig, BaseDescConfigUpdate, BaseInstance, BaseEventMap>> | undefined;
+    get(id: string): Layer | BaseHandle< BaseDesc<BaseDescConfig, BaseDescConfigUpdate, BaseInstance, BaseEventMap>> | undefined;
     emitById<K extends keyof LayerEvent>(k: K, id: string, ...args: Parameters<LayerEvent[K]>): void;
     emitAll<K extends keyof LayerEvent>(k: K, ...args: Parameters<LayerEvent[K]>): void;
     getResourceLayers(): Generator<Layer, void, unknown>;
@@ -4386,6 +4729,16 @@ declare class LegacyVectorTileMaterial {
     [Symbol.dispose](): void;
     get castShadow(): boolean | undefined;
     set castShadow(value: boolean | null | undefined);
+    /**
+     * Per-layer horizon dynamic-SSE relaxation strength (`0.0` off … `1.0`
+     * raster-equivalent). Omit for a content-based default.
+     */
+    get dynamicSseScale(): number | undefined;
+    /**
+     * Per-layer horizon dynamic-SSE relaxation strength (`0.0` off … `1.0`
+     * raster-equivalent). Omit for a content-based default.
+     */
+    set dynamicSseScale(value: number | null | undefined);
     /**
      * Sub-layer filter (MapLibre's `source-layer`). This is the only render-side
      * field; the rest is fetch config carried onto the implicit source.
@@ -4400,6 +4753,8 @@ declare class LegacyVectorTileMaterial {
     set maxSse(value: number | null | undefined);
     get maxZoom(): number | undefined;
     set maxZoom(value: number | null | undefined);
+    get minZoom(): number | undefined;
+    set minZoom(value: number | null | undefined);
     get overscaledMaxZoom(): number | undefined;
     set overscaledMaxZoom(value: number | null | undefined);
     get receiveShadow(): boolean | undefined;
@@ -4703,6 +5058,10 @@ export declare type MemoryStats = {
     gpuBytesEst: number;
     externalCpuBytes: number;
     reservedBytes: number;
+    /** Estimated GPU bytes of fixed screen-sized allocations (the
+     * postprocessing render-target stack), reported via
+     * `Core.setFixedGpuBytes` on init, resize, and pass-list changes. */
+    fixedGpuBytes: number;
     budgetBytes: number | undefined;
     evictedCount: number;
     sseMultiplier: number;
@@ -4726,6 +5085,7 @@ declare class MemoryStats_2 {
     readonly evictedCount: number;
     readonly externalBufferBytes: number;
     readonly externalCpuBytes: number;
+    readonly fixedGpuBytes: number;
     readonly gpuBytesEst: number;
     readonly reservedBytes: number;
     readonly retainedRaster: number;
@@ -5035,7 +5395,7 @@ export declare abstract class MeshDesc<Config extends MeshConfig = MeshConfig, U
      * `this.ctx.registerPickableMesh(this.id, wrapper)` before returning.
      */
     abstract createMesh(): Instance;
-    get raw(): (Instance extends Object3D<Object3DEventMap> ? Instance : never) | (Instance extends {
+    get raw(): (Instance extends Object3D< Object3DEventMap> ? Instance : never) | (Instance extends {
         raw: infer Raw extends Object3D;
     } ? Raw : never) | undefined;
     onCreate(): void;
@@ -5688,7 +6048,10 @@ export declare type Options = {
     container?: HTMLElement;
     /** Canvas element for rendering. If not provided, a new canvas is created. */
     canvas?: HTMLCanvasElement | OffscreenCanvas;
-    /** Device pixel ratio override. Uses device default if not specified. */
+    /** Device pixel ratio override. When not specified, the device value is
+     * used, capped at 2 on mobile (1 with `mobileOptimization`) — screen-sized
+     * render targets grow quadratically with pixel ratio and dominate mobile
+     * GPU memory. An explicit value bypasses the caps. */
     pixelRatio?: number;
     /** Disables automatic resize handling on window resize events. */
     disableAutoResize?: boolean;
@@ -6090,6 +6453,28 @@ declare class PointMaterial {
     set clampToGround(value: boolean | null | undefined);
     get color(): number | undefined;
     set color(value: number | null | undefined);
+    /**
+     * Placement priority for decluttering; higher wins. Only meaningful when
+     * `declutter` is enabled. Defaults to `0.0`.
+     */
+    get declutterPriority(): number | undefined;
+    /**
+     * Placement priority for decluttering; higher wins. Only meaningful when
+     * `declutter` is enabled. Defaults to `0.0`.
+     */
+    set declutterPriority(value: number | null | undefined);
+    /**
+     * Participate in screen-space decluttering: when labels/sprites overlap
+     * on screen, lower-priority ones are hidden. Defaults to `true`; set to
+     * `false` to draw every label unconditionally.
+     */
+    get declutter(): boolean | undefined;
+    /**
+     * Participate in screen-space decluttering: when labels/sprites overlap
+     * on screen, lower-priority ones are hidden. Defaults to `true`; set to
+     * `false` to draw every label unconditionally.
+     */
+    set declutter(value: boolean | null | undefined);
     get depthTest(): boolean | undefined;
     set depthTest(value: boolean | null | undefined);
     /**
@@ -6246,6 +6631,8 @@ declare type PolygonBaseRefs = {
     modelViewMatrixRTE?: UniformValue<Matrix4>;
     u_cameraPositionHigh?: UniformValue<Vector3>;
     u_cameraPositionLow?: UniformValue<Vector3>;
+    /** Always 1.0 — blocks fast-math reassociation of the RTE recombination. */
+    u_rteOne?: UniformValue<number>;
 };
 
 /**
@@ -6741,6 +7128,8 @@ declare type PolylineBaseRefs = {
     modelViewMatrixRTE?: UniformValue<Matrix4>;
     u_cameraPositionHigh?: UniformValue<Vector3>;
     u_cameraPositionLow?: UniformValue<Vector3>;
+    /** Always 1.0 — blocks fast-math reassociation of the RTE recombination. */
+    u_rteOne?: UniformValue<number>;
 };
 
 /**
@@ -7327,16 +7716,21 @@ export declare class RenderPass extends RenderPass_2 {
  * Orchestrate rendering passes with ordered management and flexible insertion.
  */
 declare class RenderPassOrchestrator {
-    lights: Group<Object3DEventMap>;
+    lights: Group< Object3DEventMap>;
     scenes: {
-        mrt: Scene<Object3DEventMap>;
-        globe: Scene<Object3DEventMap>;
-        draped: Scene<Object3DEventMap>;
-        opaque: Scene<Object3DEventMap>;
-        transparent: Scene<Object3DEventMap>;
-        skyEnvMap: Scene<Object3DEventMap>;
+        mrt: Scene< Object3DEventMap>;
+        globe: Scene< Object3DEventMap>;
+        draped: Scene< Object3DEventMap>;
+        opaque: Scene< Object3DEventMap>;
+        transparent: Scene< Object3DEventMap>;
+        skyEnvMap: Scene< Object3DEventMap>;
     };
     effectComposer: EffectComposer;
+    /**
+     * Invoked whenever the pass list changes (add/insert/remove/clear), so the
+     * owner can re-report the fixed GPU footprint to the memory ledger.
+     */
+    onPassesChanged?: () => void;
     private passMap;
     constructor(renderer: WebGLRenderer, options: RenderPassOrchestratorOptions);
     setSize(width: number, height: number): void;
@@ -7369,6 +7763,12 @@ declare class RenderPassOrchestrator {
      * Clear all passes.
      */
     clearPasses(): void;
+    /**
+     * Estimates the resident GPU bytes of the fixed, screen-sized render-target
+     * stack (composer buffers + every target reachable from the passes), for
+     * reporting into the memory ledger's `fixed_gpu_bytes` term.
+     */
+    estimateFixedGpuBytes(): number;
     /**
      * Dispose all GPU resources held by the effect composer.
      */
@@ -7396,7 +7796,12 @@ export declare class RenderTargetCopyPass extends Pass_2 {
     get autoResize(): boolean;
     set autoResize(value: boolean);
     setTexture(texture: Texture): void;
-    setDepthTexture(texture: Texture): void;
+    /**
+     * When a depth texture is set, the pass copies its depth into the target's
+     * depth buffer via gl_FragDepth. Depth test must be enabled (with AlwaysDepth)
+     * because GL discards depth writes while the depth test is disabled.
+     */
+    setDepthTexture(texture: Texture | null): void;
     render(renderer: WebGLRenderer, inputBuffer: WebGLRenderTarget | null, _outputBuffer: WebGLRenderTarget | null): void;
     dispose(): void;
 }
@@ -7459,6 +7864,20 @@ declare class ReturnedTransferablePolylineBatchedFeature {
     material: PolylineMaterial;
 }
 
+/**
+ * Shared `u_rteOne` uniform for RTE vertex shaders. Always 1.0.
+ *
+ * Multiplying the high-order difference by a uniform the shader compiler
+ * cannot constant-fold blocks fast-math reassociation of
+ * `(high - camHigh) + (low - camLow)` into `(high + low) - (camHigh + camLow)`,
+ * which would collapse the math to absolute-ECEF f32 precision and make
+ * geometry freeze/snap in ~0.25-0.5 m steps as the camera moves
+ * (observed on ANGLE Metal). One frozen object is shared by every material.
+ */
+export declare const RTE_ONE_UNIFORM: {
+    readonly value: number;
+};
+
 /**
  * Interface for objects that need RTE (Relative-To-Eye) rendering support
  */
@@ -7525,6 +7944,13 @@ export declare type SdfTextBaseMutates = Mutates<SdfTextBaseState, SdfTextBaseUn
      * Set the batch ID uniform (immutable after mount, but needed for batch creation).
      */
     setBatchId: (batchId: number) => void;
+    /**
+     * Set the declutter hide factor (0 = shown … 1 = hidden); the fragment
+     * shader scales opacity by `1 - value` and the vertex shader hard-culls
+     * at 1. Kept separate from `show`/`opacity` so user-driven visibility and
+     * declutter results compose instead of clobbering each other.
+     */
+    setDeclutterHide: (value: number) => void;
 }>;
 
 /**
@@ -7583,10 +8009,16 @@ declare type SdfTextBaseRefs = {
     uTextWidth: UniformValue<number>;
     uTextHeight: UniformValue<number>;
     uBgYBounds: UniformValue<Vector2>;
+    /** Screen-space declutter hide factor (0 = shown … 1 = hidden), animated
+     *  by the declutter fade. Driven by the declutter pass, not by material
+     *  style updates. */
+    uDeclutterHide: UniformValue<number>;
     uRTCCenter: UniformValue<Vector3>;
     uRTCCenterView: UniformValue<Vector3>;
     uEyeRTELow: UniformValue<Vector3>;
     uEyeRTEHigh: UniformValue<Vector3>;
+    /** Always 1.0 — blocks fast-math reassociation of the RTE recombination. */
+    u_rteOne?: UniformValue<number>;
     nvr_uBatchId: UniformValue<number>;
     nvr_uPickable: UniformValue<number>;
     uAtlas: UniformValue<DataTexture | null>;
@@ -7670,11 +8102,31 @@ export declare class SDFTextMesh extends Mesh_2<InstancedBufferGeometry, ShaderM
     private _reprepare?;
     /** Ask the owner to schedule a render after an async re-prepare. */
     private _requestRender?;
+    /** World-space anchor in ECEF meters (f64), kept in sync with the position
+     *  uniforms so the declutter pass can project it without touching WASM. */
+    private _worldAnchor;
+    /** Whether this label participates in screen-space decluttering. */
+    private _declutter;
+    /** Layer-level placement priority from the material. */
+    private _declutterPriority;
+    /** Per-feature priority set through the evaluator; overrides the layer
+     *  value when defined. */
+    private _declutterPriorityOverride;
+    /** Current animated hide factor (mirrors the uDeclutterHide uniform) and
+     *  the placement target it is fading toward. */
+    private _declutterHide;
+    private _declutterTarget;
+    /** Text block dimensions in em units, mirroring the uTextWidth/uTextHeight/
+     *  uBgYBounds uniforms; 0 width means "no collision box" (empty text). */
+    private _labelWidthEm;
+    private _labelHeightEm;
+    private _labelMinYEm;
+    private _labelMaxYEm;
     private _enhancer;
     constructor(position: Float32Array | {
         high: Float32Array;
         low: Float32Array;
-    }, material: TextMaterial, transform: Transform_2, fontManager: FontManager, fontUrl: string, batchId: number | undefined, RTE: boolean);
+    }, material: TextMaterial, transform: Transform_2, fontManager: FontManager, fontUrl: string, batchId: number | undefined, RTE: boolean, highQuality: boolean);
     /** The text this mesh currently renders (its baked glyph string). */
     get text(): string;
     /**
@@ -7716,12 +8168,42 @@ export declare class SDFTextMesh extends Mesh_2<InstancedBufferGeometry, ShaderM
     setHeight(height: number): void;
     setSize(size: number): void;
     setOpacity(opacity: number): void;
+    /**
+     * Set this label's declutter fade target; the actual hide factor animates
+     * toward it in {@link stepDeclutterFade}. Deliberately separate from
+     * `visible`/`show`: it neither churns scene-graph membership nor releases
+     * glyph atlas retains, so the declutter pass can retarget it every
+     * placement run at no cost.
+     */
+    setDeclutterHidden(hidden: boolean): void;
+    /**
+     * Advance the hide factor toward its target by `deltaMs / DECLUTTER_FADE_MS`
+     * and push it to the uniform. Returns true while still mid-fade.
+     */
+    stepDeclutterFade(deltaMs: number): boolean;
     _setFeatureWidth(_width: number): void;
     _setFeatureOpacity(opacity: number): void;
     setPosition(position: Float32Array | {
         high: Float32Array;
         low: Float32Array;
     }, RTE: boolean, transform: Transform_2): void;
+    /** Reconstruct the absolute ECEF anchor from the same inputs the position
+     *  uniforms receive (RTE high+low split, or RTC-relative + center). */
+    private _cacheWorldAnchor;
+    /**
+     * Build this label's collision candidate for the shared declutter pass, or
+     * null when it doesn't participate (declutter disabled, hidden, or empty).
+     * The local box mirrors the vertex shader's layout: glyphs span
+     * [0, textWidth] × [bgMinY, bgMaxY] in em units, shifted by the `center`
+     * anchor and scaled by the font size (sdfText.vert.glsl:111-115).
+     */
+    getDeclutterCandidate(owner: DeclutterParticipant, handle: number): DeclutterCandidate | null;
+    /**
+     * Set a per-feature placement priority (higher wins), overriding the
+     * layer-level `declutterPriority` for this label. Pass `undefined` to fall
+     * back to the layer value. Driven by the feature evaluator.
+     */
+    setDeclutterPriority(priority: number | undefined): void;
     /**
      * Apply material properties from WASM TextMaterial.
      * Maps relevant properties to enhancer updates, with change tracking.
@@ -8322,6 +8804,28 @@ declare class TextMaterial {
     set clampToGround(value: boolean | null | undefined);
     get color(): number | undefined;
     set color(value: number | null | undefined);
+    /**
+     * Placement priority for decluttering; higher wins. Only meaningful when
+     * `declutter` is enabled. Defaults to `0.0`.
+     */
+    get declutterPriority(): number | undefined;
+    /**
+     * Placement priority for decluttering; higher wins. Only meaningful when
+     * `declutter` is enabled. Defaults to `0.0`.
+     */
+    set declutterPriority(value: number | null | undefined);
+    /**
+     * Participate in screen-space decluttering: when labels/sprites overlap
+     * on screen, lower-priority ones are hidden. Defaults to `true`; set to
+     * `false` to draw every label unconditionally.
+     */
+    get declutter(): boolean | undefined;
+    /**
+     * Participate in screen-space decluttering: when labels/sprites overlap
+     * on screen, lower-priority ones are hidden. Defaults to `true`; set to
+     * `false` to draw every label unconditionally.
+     */
+    set declutter(value: boolean | null | undefined);
     get depthTest(): boolean | undefined;
     set depthTest(value: boolean | null | undefined);
     /**
@@ -8591,6 +9095,14 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
     private _eventDisposer;
     private _disposed;
     private _renderFlag;
+    /** Shared screen-space label declutterer for text/sprite features. */
+    private _declutter;
+    /** Reusable Vector2 for the declutter pass's per-frame viewport query. */
+    private _declutterSize;
+    /** Pending follow-up frame for a throttled declutter pass or an active
+     *  fade, with the delay it was scheduled at (so a shorter need preempts). */
+    private _declutterRetry;
+    private _declutterRetryDelay;
     private _isIdle;
     private _uniforms;
     private _meshes;
@@ -8636,6 +9148,10 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
     /** Built-in attribution UI; unset when disabled or in a worker (no DOM). */
     private _attribution?;
     private pixelRatioMatchedMedia?;
+    private fixedGpuBytesReportScheduled;
+    private fixedGpuBytesResyncPending;
+    private framesSinceFixedGpuBytesReport;
+    private lastReportedFixedGpuBytes;
     /**
      * The built-in attribution (credit) UI. `undefined` when disabled via
      * `defaultAttribution: false`, or in a worker / no-DOM environment. Feed it
@@ -8745,6 +9261,19 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
      * @param pixelRatio - Device pixel ratio
      */
     resize: (width?: number, height?: number, pixelRatio?: number) => void;
+    /**
+     * Walks the fixed render-target stack and pushes the estimate into the
+     * memory ledger; the WASM call is skipped while the value is unchanged.
+     */
+    private _reportFixedGpuBytes;
+    /**
+     * Re-reports the fixed GPU footprint for event-triggered changes (init,
+     * resize, pass add/remove). Scheduled as a microtask so bursts — e.g.
+     * effect setup during init — coalesce into a single walk, and marks a
+     * one-shot post-render resync because these events run before the GPU has
+     * lazily allocated the affected targets.
+     */
+    private _scheduleFixedGpuBytesReport;
     private _updateUniforms;
     /** Returns true if the scene was updated and needs to be rendered. */
     private _update;
@@ -8753,6 +9282,14 @@ declare class ThreeView<D extends Descriptions = EmptyDescriptions> extends Even
      * This is called after the main update loop to batch feature updates
      */
     private _forceFeatureUpdates;
+    /**
+     * Ask for a future frame on behalf of the declutter pass. Runs through a
+     * timer because the main loop clears `forceUpdate` right after `_render` —
+     * a flag set synchronously here would be wiped before the next tick reads
+     * it. A pending longer timer is preempted when a shorter delay is needed
+     * (a fade must not wait out a throttle window).
+     */
+    private _scheduleDeclutterFrame;
     private _render;
     /**
      * Since passing Color class to WASM is tricky, converts Navara Color
@@ -9136,6 +9673,12 @@ declare type TileHandler = {
      * subdivision past the vector `maxZoom`. Pass 0 to release on dispose. */
     reportDrapeGpuBytes: (handle: bigint, bytes: number) => void;
     calcMetersPerTexel: (tileHandle: bigint, textureZoom: number, textureWidth: number) => number;
+    /** Rust's clamped WebMercator northing (`navara_geometry::mercator_y`).
+     * The composite paste derives its per-slot reprojection constants through
+     * this so paste and bake (`uv_rect_from_extents_mercator`) share one
+     * implementation — a drifting reimplementation misaligns the pasted
+     * latitude band (and NaNs on the unclamped polar band). */
+    mercatorY: (lat: number) => number;
 };
 
 declare class TileLayerDescription {
@@ -9200,7 +9743,7 @@ export declare class TileMesh extends Mesh_2<BufferGeometry, TileMaterial, Custo
     private buildCompositeLayers;
     _init(mesh: MeshAdded): Promise<void>;
     private createMesh;
-    createSkirtMesh(mesh: Mesh, terrainGeometry: BufferGeometry, position: Float32Array, uv: Float32Array | null, indices: Uint32Array, normals: Float32Array | null): BufferGeometry<NormalBufferAttributes, BufferGeometryEventMap>;
+    createSkirtMesh(mesh: Mesh, terrainGeometry: BufferGeometry, position: Float32Array, uv: Float32Array | null, indices: Uint32Array, normals: Float32Array | null): BufferGeometry< NormalBufferAttributes, BufferGeometryEventMap>;
     private shouldUseNormal;
     private initMaterial;
     _update(mesh: MeshChanged): void;
@@ -9392,6 +9935,7 @@ declare class TileTextureCompositor {
      * per-tile GPU byte cost it reports to the memory ledger. */
     readonly size: number;
     private readonly texturizedScenes;
+    private readonly mercatorY;
     private readonly bakeCamera;
     private readonly quadScene;
     private readonly quadCamera;
@@ -9502,6 +10046,10 @@ declare class TileTextureCompositor {
 declare type TileTextureCompositorOptions = {
     renderer: WebGLRenderer;
     texturizedSceneByTileCoordinates: TexturizedSceneByTileCoordinates;
+    /** Rust's clamped WebMercator northing (`TileHandler.mercatorY`), handed to
+     * the core uniform mutates so the paste-side reprojection constants come
+     * from the same implementation as the Rust bake affine. */
+    mercatorY: (lat: number) => number;
     /** Atlas RT side length (defaults to 512). */
     size?: number;
     /** Test seam: replace MRT RT creation. */
@@ -9727,7 +10275,7 @@ export declare type TransparentPassConfig = Description_4 & EffectConfig;
 export declare class TransparentPassEffectDesc extends EffectDesc<TransparentPassConfig, TransparentPassUpdate, RenderPass> {
     static key: string;
     static insertAfter: string[];
-    light: Group<Object3DEventMap>;
+    light: Group< Object3DEventMap>;
     lightsSyncMap: Map<any, any>;
     createPass(): RenderPass;
     update(_time: number): void;
@@ -9901,10 +10449,22 @@ export declare class UnknownTypeError extends Error {
      [Symbol.dispose](): void;
      get crs(): string | undefined;
      set crs(value: string | null | undefined);
+     /**
+      * Per-layer horizon dynamic-SSE relaxation strength (`0.0` off … `1.0`
+      * raster-equivalent). Omit for a content-based default.
+      */
+     get dynamicSseScale(): number | undefined;
+     /**
+      * Per-layer horizon dynamic-SSE relaxation strength (`0.0` off … `1.0`
+      * raster-equivalent). Omit for a content-based default.
+      */
+     set dynamicSseScale(value: number | null | undefined);
      get maxSse(): number | undefined;
      set maxSse(value: number | null | undefined);
      get maxZoom(): number | undefined;
      set maxZoom(value: number | null | undefined);
+     get minZoom(): number | undefined;
+     set minZoom(value: number | null | undefined);
      get overscaledMaxZoom(): number | undefined;
      set overscaledMaxZoom(value: number | null | undefined);
      get type(): string | undefined;