@navaramap/three 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -863,7 +863,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;
@@ -882,6 +882,13 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<SDFTextMesh> imple
      */
     private _loadedFaceUrls;
     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
@@ -902,6 +909,7 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<SDFTextMesh> imple
     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 +959,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 +1898,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 +2212,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 +2282,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 +3064,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 +3082,7 @@ declare type EvaluatedMaterialProperty = {
     width: number;
     size: number;
     opacity: number;
+    declutterPriority: number;
     image: string | null;
 };
 
@@ -2912,6 +3126,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 +3161,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 +3364,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`;
@@ -4044,7 +4264,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 +4288,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 +4352,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 +4497,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>;
@@ -4703,6 +4959,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 +4986,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 +5296,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 +5949,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 +6354,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);
     /**
@@ -7327,16 +7613,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 +7660,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 +7693,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;
 }
@@ -7525,6 +7827,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,6 +7892,10 @@ 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>;
@@ -7670,6 +7983,26 @@ 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;
@@ -7716,12 +8049,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 +8685,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 +8976,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 +9029,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 +9142,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 +9163,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 +9554,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 +9624,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 +9816,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 +9927,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 +10156,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;