@navaramap/three 0.0.1 → 0.0.2

package/src/declutter/types.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+export 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;
+};
+
+/** Duration of the show/hide fade applied to placement results (ms). */
+export const DECLUTTER_FADE_MS = 300;
+
+/** A mesh that contributes label candidates to the shared declutter pass. */
+export 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;
+};

package/src/declutter/wasmKernel.ts

@@ -0,0 +1,13 @@
+import { declutterPlace } from "@navaramap/engine-api";
+
+import type { DeclutterKernel } from "./kernel";
+
+/**
+ * @internal
+ * {@link DeclutterKernel} backed by the Rust `declutterPlace` in
+ * `navara_wasm_api`. The WASM module must be initialized (via `initNavaraApi()`)
+ * before the first placement pass runs; `ThreeView` awaits that during setup.
+ */
+export const wasmDeclutterKernel: DeclutterKernel = {
+  place: declutterPlace,
+};

package/src/device.ts

@@ -50,6 +50,16 @@ export function isMobileDevice(): boolean {
 /** Maximum pixel ratio for mobile devices to balance quality vs performance */
 const MOBILE_MAX_PIXEL_RATIO = 1.0;
 
+/**
+ * Default pixel-ratio cap applied on every mobile device (without opting into
+ * `mobileOptimization`). The fixed screen-sized render-target stack (composer
+ * buffers, gbuffer MRT, depth textures — ~100 B/px, counted by the ledger as
+ * `fixed_gpu_bytes`) grows quadratically with the drawing-buffer size: at
+ * DPR 3 it alone can exceed a mobile tile-cache budget and permanently close
+ * the load gate. Above DPR 2 the sharpness gain is marginal on phone screens.
+ */
+const MOBILE_DEFAULT_MAX_PIXEL_RATIO = 2.0;
+
 export type DevicePixelRatioOptions = {
   /** User-specified pixel ratio override (takes precedence over all other settings) */
   override?: number;
@@ -389,7 +399,9 @@ export function getDefaultDynamicSse(): DynamicSseSettings {
 
 /**
  * Gets an appropriate pixel ratio for the current device.
- * Caps the ratio on mobile devices only when mobileOptimization is enabled.
+ * Mobile devices are capped at 2 by default (see
+ * {@link MOBILE_DEFAULT_MAX_PIXEL_RATIO}), and at 1 when mobileOptimization
+ * is enabled; an explicit `override` (the `pixelRatio` option) bypasses both.
  *
  * @param options - Configuration options for pixel ratio
  * @returns Pixel ratio appropriate for the device
@@ -405,9 +417,11 @@ export function getDevicePixelRatio(options?: DevicePixelRatioOptions): number {
 
   const deviceRatio = window.devicePixelRatio ?? 1;
 
-  // Only cap pixel ratio on mobile when mobileOptimization is enabled
-  if (options?.mobileOptimization && isMobileDevice()) {
-    return Math.min(deviceRatio, MOBILE_MAX_PIXEL_RATIO);
+  if (isMobileDevice()) {
+    const cap = options?.mobileOptimization
+      ? MOBILE_MAX_PIXEL_RATIO
+      : MOBILE_DEFAULT_MAX_PIXEL_RATIO;
+    return Math.min(deviceRatio, cap);
   }
 
   return deviceRatio;

package/src/evaluations/FeatureEvaluator.ts

@@ -55,6 +55,9 @@ export 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;
 };
@@ -70,6 +73,7 @@ type EvaluatedMaterialProperty = {
   width: number;
   size: number;
   opacity: number;
+  declutterPriority: number;
   image: string | null;
 };
 
@@ -308,6 +312,8 @@ export 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`;
@@ -387,6 +393,12 @@ export class FeatureEvaluator {
       if (evaluated.opacity != null) {
         obj.setFeatureOpacityByBatchId(batchId, evaluated.opacity);
       }
+      if (evaluated.declutterPriority != null) {
+        obj.setFeatureDeclutterPriorityByBatchId(
+          batchId,
+          evaluated.declutterPriority,
+        );
+      }
       if ("image" in evaluated) {
         // Async by nature (the image may need fetching); the atlas dedupes
         // loads by URL so evaluating many features costs one fetch per image.
@@ -415,6 +427,15 @@ export class FeatureEvaluator {
       if (evaluated.opacity != null && obj instanceof BatchedSdfTextMesh) {
         obj.setFeatureOpacityByBatchIndex(batchIndex, evaluated.opacity);
       }
+      if (
+        evaluated.declutterPriority != null &&
+        obj instanceof BatchedSdfTextMesh
+      ) {
+        obj.setFeatureDeclutterPriorityByBatchIndex(
+          batchIndex,
+          evaluated.declutterPriority,
+        );
+      }
       return;
     }
 

package/src/event/context.ts

@@ -22,6 +22,7 @@ import type { Texture } from "three";
 import type { ViewEvents } from "..";
 import type { ThreeViewCamera } from "../camera";
 import type { ViewContext } from "../core";
+import type { DeclutterManager } from "../declutter";
 import type { LayersManager } from "../layersManager";
 import type { TileMesh } from "../mesh/tile";
 import type { Scenes, TexturizedSceneByTileCoordinates } from "../scene";
@@ -120,6 +121,12 @@ export type TileHandler = {
     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;
 };
 
 /**
@@ -214,6 +221,7 @@ type EventContextArgs = {
   textureFragmentIndex?: Map<string, Set<TextureSlot>>;
   tileMeshToFragmentIds?: Map<TileMesh, Set<string>>;
   hillshadeContext?: HillshadeContext;
+  declutter?: DeclutterManager;
 };
 
 /**
@@ -248,6 +256,9 @@ export 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 = 0;
 
@@ -280,5 +291,6 @@ export class EventContext {
     this.textureFragmentIndex = args.textureFragmentIndex;
     this.tileMeshToFragmentIds = args.tileMeshToFragmentIds;
     this.hillshadeContext = args.hillshadeContext;
+    this.declutter = args.declutter;
   }
 }

package/src/event/features/modelGpuBytes.ts

@@ -60,9 +60,7 @@ export function sumModelGpuBytes(obj: Object3D): number {
       }
     }
     const material = (node as Mesh | Points).material as
-      | Material
-      | Material[]
-      | undefined;
+      Material | Material[] | undefined;
     const materials = Array.isArray(material)
       ? material
       : material

package/src/event/hillshade.test.ts

@@ -494,9 +494,8 @@ describe("hillshade normal map generation", () => {
     expect(loadedTexs.has(entityId)).toBe(true);
     const normalMap = loadedTexs.get(entityId);
     expect(normalMap).toBeInstanceOf(Texture);
-    if (normalMap) {
-      expect((normalMap.image as { width: number }).width).toBe(4); // Content size (no padding in normal map)
-    }
+    // Content size (no padding in normal map)
+    expect((normalMap?.image as { width: number } | undefined)?.width).toBe(4);
 
     // Verify temp DEM entry was stored for edge updates
     const tempDem = hillshadeContext.getTempDem(entityId);
@@ -584,16 +583,11 @@ describe("hillshade normal map generation", () => {
         target_entity_gen: 123,
       } as HillshadeBackfilledEvent);
 
-      if (direction < 3) {
-        // Not all edges received yet
-        expect(hillshadeContext.getTempDem(entityId)).toBeDefined();
-        expect(hillshadeContext.getTempDem(entityId)?.receivedEdges.size).toBe(
-          direction + 1,
-        );
-      } else {
-        // All 4 edges received, temp DEM should be cleaned up
-        expect(hillshadeContext.getTempDem(entityId)).toBeUndefined();
-      }
+      // The temp DEM tracks received edges until all 4 arrive, then it is
+      // cleaned up (so `getTempDem` returns undefined on the last iteration).
+      expect(hillshadeContext.getTempDem(entityId)?.receivedEdges.size).toBe(
+        direction < 3 ? direction + 1 : undefined,
+      );
     }
 
     // Verify texture still exists after cleanup

package/src/event/index.ts

@@ -23,7 +23,7 @@ import { BatchedSdfTextMesh, Layer } from "..";
 import { disposeTexture } from "../loaders";
 import { getImageDataFromBlob } from "../tasks/getImageDataFromBlob";
 
-import { EventContext } from "./context";
+import { type EventContext } from "./context";
 import {
   checkFeatureParallel,
   processRenderableFeatureAdded,
@@ -463,12 +463,11 @@ async function processRequestedData(ctx: EventContext, req: DataRequestEvent) {
           return;
         }
 
-        let u8a: Uint8Array | null = new Uint8Array(data);
+        const u8a = new Uint8Array(data);
         buf.setU8(req.handle, req.bits, u8a);
 
         // Prevent memory leak
         u8a.set([]);
-        u8a = null;
 
         data.set([]);
       })

package/src/event/tileHandler.ts

@@ -0,0 +1,54 @@
+import { mercatorY, type Core } from "@navaramap/engine";
+
+import type { TileHandler } from "./context";
+
+export type TileHandlerDeps = {
+  /** Accessor (not a snapshot) — the Core is created asynchronously after
+   * WASM init and can be dropped on dispose. */
+  getCore: () => Core | undefined;
+  /** Per-frame cached revision snapshots (refreshed once per `_render`), so
+   * per-tile `onBeforeRender` gating costs no WASM-boundary call. */
+  getVectorRevision: () => number;
+  getRasterRevision: () => number;
+};
+
+/**
+ * Build the {@link TileHandler} context over a WASM `Core`. Extracted from
+ * `ThreeView` so tests can assemble the same handler over a shared test engine
+ * (`test-utils/engine.ts`) instead of stubbing the Rust-backed functions.
+ */
+export function createTileHandler(deps: TileHandlerDeps): TileHandler {
+  const { getCore } = deps;
+  return {
+    getMartini: (id) => {
+      return getCore()?.getMartini(id);
+    },
+    getTile: (handle) => {
+      return getCore()?.getTile(handle);
+    },
+    getParentTile: (handle) => {
+      return getCore()?.getParentTile(handle);
+    },
+    getTileElevationDecoder: (handle) => {
+      return getCore()?.getTileElevationDecoder(handle);
+    },
+    getVectorTileStates: (handle) => {
+      return getCore()?.getVectorTileStates(handle);
+    },
+    vectorRevision: deps.getVectorRevision,
+    getRasterTileStates: (handle) => {
+      return getCore()?.getRasterTileStates(handle);
+    },
+    rasterRevision: deps.getRasterRevision,
+    reportDrapeGpuBytes: (handle, bytes) => {
+      getCore()?.reportTerrainDrapeGpuBytes(handle, bytes);
+    },
+    calcMetersPerTexel: (tileHandle, textureZoom, textureWidth) => {
+      return (
+        getCore()?.calcMetersPerTexel(tileHandle, textureZoom, textureWidth) ??
+        1.0
+      );
+    },
+    mercatorY,
+  };
+}

package/src/index.ts

@@ -70,6 +70,7 @@ import {
   type AnyMeshDesc,
 } from "./core/BaseHandle";
 import { Registries } from "./core/Registries";
+import { DeclutterManager, wasmDeclutterKernel } from "./declutter";
 import {
   getCompositeAtlasSize,
   getDefaultDynamicSse,
@@ -95,6 +96,7 @@ import {
   type WorkerTaskHandler,
 } from "./event";
 import { TEXTURE_LOADER } from "./event/loaders";
+import { createTileHandler } from "./event/tileHandler";
 import { InMemoryBufferStore } from "./inMemoryBufferStore";
 import { registerInputEvents } from "./input";
 import { Layer, type LayerEvent } from "./layer";
@@ -222,6 +224,10 @@ export 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;
@@ -252,7 +258,10 @@ export 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;
@@ -442,6 +451,14 @@ export default class ThreeView<
     forceUpdate: false,
     animation: false,
   };
+  /** Shared screen-space label declutterer for text/sprite features. */
+  private _declutter = new DeclutterManager(wasmDeclutterKernel);
+  /** Reusable Vector2 for the declutter pass's per-frame viewport query. */
+  private _declutterSize = new Vector2();
+  /** 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: ReturnType<typeof setTimeout> | undefined;
+  private _declutterRetryDelay = 0;
   private _isIdle = false;
   private _uniforms: CommonUniforms;
 
@@ -634,39 +651,11 @@ export default class ThreeView<
   private _vectorRevision = 0;
   // Per-frame snapshot of the WASM raster drape resolution revision, refreshed in `_render`.
   private _rasterRevision = 0;
-  private _tileHandler: TileHandler = {
-    getMartini: (id) => {
-      return this._core?.getMartini(id);
-    },
-    getTile: (handle) => {
-      return this._core?.getTile(handle);
-    },
-    getParentTile: (handle) => {
-      return this._core?.getParentTile(handle);
-    },
-    getTileElevationDecoder: (handle) => {
-      return this._core?.getTileElevationDecoder(handle);
-    },
-    getVectorTileStates: (handle) => {
-      return this._core?.getVectorTileStates(handle);
-    },
-    // Returns the per-frame cached revision (read once in `_render`), so per-tile
-    // `onBeforeRender` gating costs no WASM-boundary call.
-    vectorRevision: () => this._vectorRevision,
-    getRasterTileStates: (handle) => {
-      return this._core?.getRasterTileStates(handle);
-    },
-    rasterRevision: () => this._rasterRevision,
-    reportDrapeGpuBytes: (handle, bytes) => {
-      this._core?.reportTerrainDrapeGpuBytes(handle, bytes);
-    },
-    calcMetersPerTexel: (tileHandle, textureZoom, textureWidth) => {
-      return (
-        this._core?.calcMetersPerTexel(tileHandle, textureZoom, textureWidth) ??
-        1.0
-      );
-    },
-  };
+  private _tileHandler: TileHandler = createTileHandler({
+    getCore: () => this._core,
+    getVectorRevision: () => this._vectorRevision,
+    getRasterRevision: () => this._rasterRevision,
+  });
   private _globeHandler: GlobeHandler = {
     getTransparent: () => {
       return this._core?.getGlobeTransparent();
@@ -805,6 +794,11 @@ export default class ThreeView<
 
   private pixelRatioMatchedMedia?: MediaQueryList;
 
+  private fixedGpuBytesReportScheduled = false;
+  private fixedGpuBytesResyncPending = false;
+  private framesSinceFixedGpuBytesReport = 0;
+  private lastReportedFixedGpuBytes = -1;
+
   /**
    * The built-in attribution (credit) UI. `undefined` when disabled via
    * `defaultAttribution: false`, or in a worker / no-DOM environment. Feed it
@@ -907,6 +901,7 @@ export default class ThreeView<
     this._tileTextureCompositor = new TileTextureCompositor({
       renderer: this._renderer,
       texturizedSceneByTileCoordinates: this._texturizedSceneByTileCoordinates,
+      mercatorY: this._tileHandler.mercatorY,
       size: getCompositeAtlasSize(this.isMobileOptimized()),
     });
 
@@ -929,6 +924,8 @@ export default class ThreeView<
     });
 
     this.renderPassOrchestrator.setSize(width, height);
+    this.renderPassOrchestrator.onPassesChanged = () =>
+      this._scheduleFixedGpuBytesReport();
 
     // Background color
     const bgColor = options.backgroundColor
@@ -1245,6 +1242,7 @@ export default class ThreeView<
       gpuBytesEst: stats.gpuBytesEst,
       externalCpuBytes: stats.externalCpuBytes,
       reservedBytes: stats.reservedBytes,
+      fixedGpuBytes: stats.fixedGpuBytes,
       budgetBytes: stats.budgetBytes,
       evictedCount: stats.evictedCount,
       sseMultiplier: stats.sseMultiplier,
@@ -1370,6 +1368,10 @@ export default class ThreeView<
       costHints.rasterTileBytes,
     );
 
+    // Passes added before `_core` existed could not be reported; sync the
+    // fixed render-target footprint now that the ledger is reachable.
+    this._scheduleFixedGpuBytesReport();
+
     // LOD fog: stronger distance-based degrade on low-memory devices.
     const lodFog = {
       ...getDefaultLodFog({ isMobile: mobileOptimized }),
@@ -1440,6 +1442,7 @@ export default class ThreeView<
       textureFragmentIndex: this._textureFragmentIndex,
       tileMeshToFragmentIds: this._tileMeshToFragmentIds,
       hillshadeContext: this._hillshadeContext,
+      declutter: this._declutter,
     });
 
     // Register built-in descriptors
@@ -1544,6 +1547,10 @@ export default class ThreeView<
   dispose() {
     this._disposed = true;
     this._initialized = false;
+    if (this._declutterRetry !== undefined) {
+      clearTimeout(this._declutterRetry);
+      this._declutterRetry = undefined;
+    }
     // Dispose the view-owned attribution plugin (other plugins are the caller's).
     this._attribution?.dispose();
     this._attribution = undefined;
@@ -1593,6 +1600,10 @@ export default class ThreeView<
     // Cleanup hillshade context (temp DEMs, generator, etc.)
     this._hillshadeContext.dispose();
 
+    // Drop declutter participants so the manager doesn't retain removed
+    // meshes' GPU/font resources past this view's lifetime.
+    this._declutter.dispose();
+
     // Clear caches and maps
     this._meshes.clear();
     this._inMemoryBufferStore.clear();
@@ -1661,10 +1672,41 @@ export default class ThreeView<
     this._pickHelper?.setSize(drawingBufferSize.x, drawingBufferSize.y);
 
     this._core?.resize(w, h, pixelRatio ?? 1);
+    this._scheduleFixedGpuBytesReport();
 
     this.emit("resize", w, h);
   };
 
+  /**
+   * 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(): void {
+    if (this._disposed || !this._core) return;
+    const bytes = this.renderPassOrchestrator.estimateFixedGpuBytes();
+    this.framesSinceFixedGpuBytesReport = 0;
+    if (bytes === this.lastReportedFixedGpuBytes) return;
+    this.lastReportedFixedGpuBytes = bytes;
+    this._core.setFixedGpuBytes(bytes);
+  }
+
+  /**
+   * 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(): void {
+    this.fixedGpuBytesResyncPending = true;
+    if (this.fixedGpuBytesReportScheduled) return;
+    this.fixedGpuBytesReportScheduled = true;
+    queueMicrotask(() => {
+      this.fixedGpuBytesReportScheduled = false;
+      this._reportFixedGpuBytes();
+    });
+  }
+
   private _updateUniforms() {
     const viewport = this._getCanvasSize();
     const pixelRatio = this._renderer.getPixelRatio();
@@ -1744,6 +1786,25 @@ export default class ThreeView<
     }
   }
 
+  /**
+   * 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(delayMs: number) {
+    if (this._declutterRetry !== undefined) {
+      if (delayMs >= this._declutterRetryDelay) return;
+      clearTimeout(this._declutterRetry);
+    }
+    this._declutterRetryDelay = delayMs;
+    this._declutterRetry = setTimeout(() => {
+      this._declutterRetry = undefined;
+      this._renderFlag.forceUpdate = true;
+    }, delayMs);
+  }
+
   private _render(updatedAt: number) {
     // Read the vector/raster resolution revisions once per frame so each terrain
     // tile's `onBeforeRender` can gate its slot re-fetch against them without its
@@ -1755,6 +1816,29 @@ export default class ThreeView<
 
     this._atmosphere._update();
 
+    // Screen-space label decluttering runs before the render passes so
+    // placement changes land in this frame. Throttled passes and active
+    // fades both need future frames, requested via _scheduleDeclutterFrame.
+    {
+      const size = this._renderer.getDrawingBufferSize(this._declutterSize);
+      const pixelRatio = this._renderer.getPixelRatio();
+      const result = this._declutter.update(
+        this._camera.raw,
+        size.x / pixelRatio,
+        size.y / pixelRatio,
+        updatedAt,
+      );
+      if (result === "throttled") {
+        this._scheduleDeclutterFrame(
+          this._declutter.remainingThrottleMs(updatedAt),
+        );
+      } else if (result === "animating") {
+        // Keep frames coming at fade cadence until every label reaches its
+        // placement target.
+        this._scheduleDeclutterFrame(16);
+      }
+    }
+
     this.emit("preRender", updatedAt);
 
     this.renderPassOrchestrator.render();
@@ -1763,6 +1847,19 @@ export default class ThreeView<
     this.shadowMapViewers.render(this._renderer);
 
     this.emit("postRender", updatedAt);
+
+    // Render targets are GL-allocated lazily during rendering (and freed on
+    // resize), so a footprint taken at init/resize/pass-change time goes
+    // stale: re-estimate once on the first frame after such an event, and
+    // otherwise at a low cadence. The report skips the WASM call when the
+    // value is unchanged.
+    if (this.fixedGpuBytesResyncPending) {
+      this.fixedGpuBytesResyncPending = false;
+      this._reportFixedGpuBytes();
+    } else if (++this.framesSinceFixedGpuBytesReport >= 120) {
+      this.framesSinceFixedGpuBytesReport = 0;
+      this._reportFixedGpuBytes();
+    }
   }
 
   /**
@@ -2448,9 +2545,14 @@ export default class ThreeView<
     const { width, height } = this._getCanvasSize() ?? {};
     if (!width || !height) return;
 
+    // Route through getDevicePixelRatio so a devicePixelRatio change (zoom,
+    // monitor move) cannot bypass the mobile caps applied at init.
     const pixelRatio = isWorker()
       ? (this._options.pixelRatio ?? 1)
-      : window.devicePixelRatio;
+      : getDevicePixelRatio({
+          override: this._options.pixelRatio,
+          mobileOptimization: this._options.mobileOptimization,
+        });
     this.resize(width, height, pixelRatio);
   };
 

package/src/material/enhancer/ShaderReplacer.ts

@@ -13,8 +13,7 @@ type PickMarker<Markers extends ShaderMarkers, Key extends keyof Markers> = {
 }[keyof Markers[Key]];
 
 type PickMarkers<Markers extends ShaderMarkers> =
-  | PickMarker<Markers, "vertex">
-  | PickMarker<Markers, "fragment">;
+  PickMarker<Markers, "vertex"> | PickMarker<Markers, "fragment">;
 
 /**
  * A type-safe shader string replacer that restricts operations to declared markers.