@navaramap/three 0.0.0 → 0.0.2

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;
 
@@ -632,35 +649,13 @@ export default class ThreeView<
   };
   // Per-frame snapshot of the WASM vector resolution revision, refreshed in `_render`.
   private _vectorRevision = 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,
-    reportDrapeGpuBytes: (handle, bytes) => {
-      this._core?.reportTerrainDrapeGpuBytes(handle, bytes);
-    },
-    calcMetersPerTexel: (tileHandle, textureZoom, textureWidth) => {
-      return (
-        this._core?.calcMetersPerTexel(tileHandle, textureZoom, textureWidth) ??
-        1.0
-      );
-    },
-  };
+  // Per-frame snapshot of the WASM raster drape resolution revision, refreshed in `_render`.
+  private _rasterRevision = 0;
+  private _tileHandler: TileHandler = createTileHandler({
+    getCore: () => this._core,
+    getVectorRevision: () => this._vectorRevision,
+    getRasterRevision: () => this._rasterRevision,
+  });
   private _globeHandler: GlobeHandler = {
     getTransparent: () => {
       return this._core?.getGlobeTransparent();
@@ -799,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
@@ -901,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()),
     });
 
@@ -923,6 +924,8 @@ export default class ThreeView<
     });
 
     this.renderPassOrchestrator.setSize(width, height);
+    this.renderPassOrchestrator.onPassesChanged = () =>
+      this._scheduleFixedGpuBytesReport();
 
     // Background color
     const bgColor = options.backgroundColor
@@ -1239,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,
@@ -1364,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 }),
@@ -1434,6 +1442,7 @@ export default class ThreeView<
       textureFragmentIndex: this._textureFragmentIndex,
       tileMeshToFragmentIds: this._tileMeshToFragmentIds,
       hillshadeContext: this._hillshadeContext,
+      declutter: this._declutter,
     });
 
     // Register built-in descriptors
@@ -1538,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;
@@ -1587,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();
@@ -1655,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();
@@ -1738,15 +1786,59 @@ 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 resolution revision once per frame so each terrain tile's
-    // `onBeforeRender` can gate its slot re-fetch against it without its own FFI call.
+    // 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
+    // own FFI calls.
     this._vectorRevision = this._core?.vectorRevision() ?? this._vectorRevision;
+    this._rasterRevision = this._core?.rasterRevision() ?? this._rasterRevision;
 
     this._uniforms.time.value = updatedAt;
 
     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();
@@ -1755,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();
+    }
   }
 
   /**
@@ -2440,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.

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/mutates.ts

@@ -44,6 +44,7 @@ export const createBaseMutates = (
     uTextWidth: { value: 0.0 },
     uTextHeight: { value: 0.0 },
     uBgYBounds: { value: new Vector2(0.0, 1.0) },
+    uDeclutterHide: { value: 0.0 },
     uRTCCenter: {
       value: new Vector3(
         rtcCenter?.[0] ?? 0,
@@ -113,6 +114,7 @@ export const createBaseMutates = (
       uniforms.uTextWidth = refs.uTextWidth;
       uniforms.uTextHeight = refs.uTextHeight;
       uniforms.uBgYBounds = refs.uBgYBounds;
+      uniforms.uDeclutterHide = refs.uDeclutterHide;
       uniforms.uRTCCenter = refs.uRTCCenter;
       uniforms.uRTCCenterView = refs.uRTCCenterView;
       uniforms.uEyeRTELow = refs.uEyeRTELow;
@@ -228,5 +230,9 @@ export const createBaseMutates = (
     setBatchId: (id: number) => {
       refs.nvr_uBatchId.value = id;
     },
+
+    setDeclutterHide: (value: number) => {
+      refs.uDeclutterHide.value = value;
+    },
   };
 };

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/types.ts

@@ -103,6 +103,10 @@ export 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>;
@@ -180,5 +184,12 @@ export type SdfTextBaseMutates = Mutates<
      * 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;
   }
 >;

package/src/material/enhancer/tileComposite/tileCompositeBaseEnhancer/mutates.test.ts

@@ -0,0 +1,83 @@
+import { Color, Texture, Vector2 } from "three";
+import { describe, expect, it } from "vitest";
+
+import { createTestTileHandler } from "../../../../test-utils/engine";
+import type { RasterCompositeLayer } from "../../../../tileTexture/types";
+
+import {
+  createCoreUniformMutates,
+  type CompositeUniformTarget,
+} from "./mutates";
+
+// The real Rust `mercator_y` (clamped to the WM band), reached through the
+// same context handler the app injects — the clamp regression below exercises
+// the production implementation, not a reimplementation.
+const { mercatorY } = createTestTileHandler();
+
+const rasterLayer = (
+  reproject: [number, number] | undefined,
+): RasterCompositeLayer => ({
+  absSlot: 0,
+  region: "raster",
+  texture: null,
+  uvOffset: new Vector2(0, 0),
+  uvScale: new Vector2(1, 1),
+  kind: "raster",
+  color: new Color(1, 1, 1),
+  opacity: 1,
+  water: false,
+  reproject,
+});
+
+const bind = (reproject: [number, number] | undefined) => {
+  const mutates = createCoreUniformMutates(mercatorY);
+  const target: CompositeUniformTarget = {};
+  mutates.attachUniforms(target, 1, new Texture());
+  mutates.bindSlot(0, rasterLayer(reproject));
+  return target;
+};
+
+describe("bindSlot Mercator reprojection constants", () => {
+  it("clamps a polar latitude band to the WebMercator limit instead of NaN", () => {
+    // A z0 Geographic terrain tile's band is ±90°, and Rust hands it over as
+    // f32 — slightly PAST ±π/2, where an unclamped log(tan(...)) is NaN. A
+    // NaN span fails the shader's `abs(mDen) > 1e-3` guard, silently skipping
+    // reprojection for the whole tile (imagery squashes toward the equator).
+    const f32HalfPi = Math.fround(Math.PI / 2);
+    const target = bind([-f32HalfPi, f32HalfPi]);
+
+    const merc = target.uReprojectMerc.value[0];
+    // Band start/span from the clamped WM limit: mRs = -π, mDen = 2π.
+    expect(merc.x).toBeCloseTo(-Math.PI, 5);
+    expect(merc.y).toBeCloseTo(2 * Math.PI, 5);
+    // Both edges sit on the WM limit → both polar-cap clamp flags set.
+    expect(merc.z).toBe(1);
+    expect(merc.w).toBe(1);
+    expect(target.uReproject.value[0]).toBe(1);
+  });
+
+  it("keeps an interior band un-clamped and un-flagged", () => {
+    const south = 0.2;
+    const north = 0.7;
+    const target = bind([south, north]);
+
+    const merc = target.uReprojectMerc.value[0];
+    expect(merc.x).toBeCloseTo(mercatorY(south), 9);
+    expect(merc.y).toBeCloseTo(mercatorY(north) - mercatorY(south), 9);
+    expect(merc.z).toBe(0);
+    expect(merc.w).toBe(0);
+  });
+
+  it("flags but does not NaN a band touching one WM edge", () => {
+    // z1 north Geographic tile: [0, 90°]. South edge is fine; the north edge
+    // must clamp to the WM limit and set only the top polar-cap flag.
+    const target = bind([0, Math.fround(Math.PI / 2)]);
+
+    const merc = target.uReprojectMerc.value[0];
+    expect(merc.x).toBeCloseTo(0, 9);
+    expect(merc.y).toBeCloseTo(Math.PI, 5);
+    expect(merc.z).toBe(1);
+    expect(merc.w).toBe(0);
+    expect(Number.isFinite(merc.y)).toBe(true);
+  });
+});

package/src/material/enhancer/tileComposite/tileCompositeBaseEnhancer/mutates.ts

@@ -26,7 +26,11 @@ export type CoreUniformMutates = {
   bindSlot: (compactSlot: number, layer: CompositeLayer | undefined) => void;
 };
 
-export function createCoreUniformMutates(): CoreUniformMutates {
+/** `mercatorY` is Rust's clamped WebMercator northing, injected through the
+ * event context (`TileHandler.mercatorY`) like every other engine call. */
+export function createCoreUniformMutates(
+  mercatorY: (lat: number) => number,
+): CoreUniformMutates {
   const refs = {
     uShows: new Uniform<number[]>([]),
     uOpacities: new Uniform<number[]>([]),
@@ -104,8 +108,13 @@ export function createCoreUniformMutates(): CoreUniformMutates {
         refs.uLayerUvScale.value[k].set(1, 1);
       }
 
+      // Reproject applies to color rasters and elevation heatmaps alike — the
+      // shader warps the per-slot UV before either sampler runs; hillshade is
+      // terrain-side and never reprojects.
       const reproject =
-        layer && layer.kind === "raster" ? layer.reproject : undefined;
+        layer && (layer.kind === "raster" || layer.kind === "elevationHeatmap")
+          ? layer.reproject
+          : undefined;
       if (reproject && layer) {
         const [Ts, Tn] = reproject;
         // Recover the source tile's latitude band [Rs, Rn] from the affine y
@@ -115,8 +124,14 @@ export function createCoreUniformMutates(): CoreUniformMutates {
         const span = (Tn - Ts) / layer.uvScale.y;
         const Rs = Ts - layer.uvOffset.y * span;
         const Rn = Rs + span;
-        const mRs = Math.log(Math.tan(Math.PI * 0.25 + Rs * 0.5));
-        const mRn = Math.log(Math.tan(Math.PI * 0.25 + Rn * 0.5));
+        // Rust's clamped Mercator northing — the same function the bake affine
+        // uses (`uv_rect_from_extents_mercator`), so the pasted band stays
+        // aligned with the baked render target. The clamp matters: a polar
+        // tile's band reaches ±90° (as f32, slightly past it), where unclamped
+        // log(tan(...)) returns NaN — and a NaN span fails the shader's
+        // `abs(mDen)` guard, silently disabling reprojection for the tile.
+        const mRs = mercatorY(Rs);
+        const mRn = mercatorY(Rn);
         // Polar cap: clamp the overshoot onto the band-edge texel when this tile's
         // north/south edge sits on the WebMercator latitude limit.
         const clampTop = Rn >= WM_MAX_LAT - 1e-4 ? 1 : 0;

package/src/material/enhancer/tileComposite/tileElevationHeatmapEnhancer/shader.ts

@@ -10,6 +10,12 @@ export const elevationIncludes = (): string => ElevationParsFragment;
 /**
  * Replaces the per-slot sampler with a DEM-decode + colormap lookup; non-heatmap
  * slots fall back to the straight raster fetch in the else branch.
+ *
+ * The heatmap alpha derives from the decode's validity: a no-data (boundary)
+ * texel — including a baked drape render target's uncovered regions, which the
+ * bake paints with the boundary color — renders transparent instead of being
+ * colormapped as height 0. The DEM texel's alpha channel is never read: it is
+ * not part of any elevation encoding and stays reserved for future RGBA ones.
  */
 export const elevationSampleProducer = ({
   k,
@@ -17,8 +23,9 @@ export const elevationSampleProducer = ({
     vec4 texColor${k};
     if (uIsElevationHeatmaps[${k}]) {
       ivec2 demTexSize = textureSize(uTextures[${k}], 0);
-      float normalized_h = sampleElevationBilinear(uTextures[${k}], texUv${k}, demTexSize);
-      texColor${k} = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, 1.0);
+      bool demValid${k};
+      float normalized_h = sampleElevationBilinear(uTextures[${k}], texUv${k}, demTexSize, demValid${k});
+      texColor${k} = vec4(texture2D(uColorMapTexture, vec2(normalized_h, 0.5)).rgb, demValid${k} ? 1.0 : 0.0);
     } else {
       texColor${k} = texture2D(uTextures[${k}], texUv${k}) * vec4(uColors[${k}], 1.0);
     }`;

package/src/mesh/batchTexture.ts

@@ -183,8 +183,7 @@ export function getRowIndex(
   row: BatchTextureRowKey,
 ): number {
   const config = material.userData.batchTextureConfig as
-    | BatchTextureConfig
-    | undefined;
+    BatchTextureConfig | undefined;
   invariant(config);
 
   const rowIndex = config.rows.indexOf(row);
@@ -238,8 +237,7 @@ export function updateBatchAttribute(
   const data = texture.image.data as Float32Array;
   const texWidth = texture.image.width;
   const config = material.userData.batchTextureConfig as
-    | BatchTextureConfig
-    | undefined;
+    BatchTextureConfig | undefined;
   const rowCount = config?.rows.length ?? BATCH_TEXTURE_ROW.length;
 
   switch (attribute) {

package/src/mesh/batchedSdfText.ts

@@ -6,6 +6,10 @@ import type { FontManager } from "@navaramap/font";
 import { type Color } from "three";
 import invariant from "tiny-invariant";
 
+import type {
+  DeclutterCandidate,
+  DeclutterParticipant,
+} from "../declutter/types";
 import type { EventContext } from "../event/context";
 
 import { InstancedMesh, type InstancedMeshOptions } from "./instanced";
@@ -36,7 +40,7 @@ type PositionsInfo = PositionsInfoBase &
 
 export class BatchedSdfTextMesh
   extends InstancedMesh<SDFTextMesh>
-  implements PickableMesh
+  implements PickableMesh, DeclutterParticipant
 {
   readonly ctx: EventContext;
   /** The font identifier from material — may be a family name or a URL. */
@@ -79,6 +83,41 @@ export class BatchedSdfTextMesh
       this._highQuality,
       () => this._revalidateStaleMeshes(),
     );
+    ctx.declutter?.register(this);
+  }
+
+  // --- DeclutterParticipant ---
+
+  collectDeclutterCandidates(out: DeclutterCandidate[]): void {
+    if (!this.visible) return;
+    const meshes = this.meshes();
+    for (let i = 0; i < meshes.length; i++) {
+      const candidate = meshes[i].getDeclutterCandidate(this, i);
+      if (candidate) out.push(candidate);
+    }
+  }
+
+  applyDeclutter(handle: number, hidden: boolean): void {
+    this.meshes()[handle]?.setDeclutterHidden(hidden);
+  }
+
+  stepDeclutterFade(deltaMs: number): boolean {
+    let animating = false;
+    for (const mesh of this.meshes()) {
+      animating = mesh.stepDeclutterFade(deltaMs) || animating;
+    }
+    return animating;
+  }
+
+  /** Candidates changed (text, style, position, visibility): ask the shared
+   *  declutter pass to re-place on its next update. */
+  private _markDeclutterDirty(): void {
+    this.ctx.declutter?.markDirty();
+  }
+
+  override setActive(active: boolean) {
+    super.setActive(active);
+    this._markDeclutterDirty();
   }
 
   /**
@@ -111,6 +150,7 @@ export class BatchedSdfTextMesh
           // Force a rebuild even though the text string is unchanged: the baked
           // atlas rects and glyph retains must refresh against the new metrics.
           mesh.setText(text, true);
+          this._markDeclutterDirty();
           this._needRender?.();
         })
         .catch((err: unknown) => {
@@ -222,6 +262,8 @@ export class BatchedSdfTextMesh
           : position.subarray(posIdx, posIdx + positionSize);
         this.meshes()[i].setPosition(pos, RTE, transform);
       }
+      // Anchors moved (e.g. terrain height resolution) — re-place labels.
+      this._markDeclutterDirty();
     }
 
     const fontIdentifier = m.material.font ?? this._fontIdentifier;
@@ -292,6 +334,7 @@ export class BatchedSdfTextMesh
       mesh.update(material, forceUpdate);
       this.markVisibility(mesh);
     }
+    this._markDeclutterDirty();
 
     if (needRender) needRender();
   }
@@ -412,6 +455,7 @@ export class BatchedSdfTextMesh
             // Restore intended visibility now that text content is available
             mesh.visible = intendedVisible;
             this.markVisibility(mesh);
+            this._markDeclutterDirty();
             this._needRender?.();
           })
           .catch((err: unknown) => {
@@ -422,6 +466,7 @@ export class BatchedSdfTextMesh
       }
       mesh.setText(text);
       this.markVisibility(mesh);
+      this._markDeclutterDirty();
       this._needRender?.();
     }
   }
@@ -438,6 +483,7 @@ export class BatchedSdfTextMesh
     if (mesh) {
       mesh._setFeatureShow(rawVisible);
       this.markVisibility(mesh);
+      this._markDeclutterDirty();
     }
   }
 
@@ -445,6 +491,7 @@ export class BatchedSdfTextMesh
     const mesh = this.meshes()[batchIndex];
     if (mesh) {
       mesh.setHeight(height);
+      this._markDeclutterDirty();
     }
   }
 
@@ -452,6 +499,18 @@ export class BatchedSdfTextMesh
     const mesh = this.meshes()[batchIndex];
     if (mesh) {
       mesh.setSize(size);
+      this._markDeclutterDirty();
+    }
+  }
+
+  setFeatureDeclutterPriorityByBatchIndex(
+    batchIndex: number,
+    priority: number,
+  ) {
+    const mesh = this.meshes()[batchIndex];
+    if (mesh) {
+      mesh.setDeclutterPriority(priority);
+      this._markDeclutterDirty();
     }
   }
 
@@ -466,6 +525,7 @@ export class BatchedSdfTextMesh
   }
 
   dispose() {
+    this.ctx.declutter?.unregister(this);
     this._unsubscribeEvict?.();
     this._unsubscribeEvict = undefined;
     const q = this._highQuality;