@navaramap/three 0.0.1 → 0.0.3

package/src/mesh/sdfText.ts

@@ -26,6 +26,11 @@ import {
   Vector2,
 } from "three";
 
+import {
+  DECLUTTER_FADE_MS,
+  type DeclutterCandidate,
+  type DeclutterParticipant,
+} from "../declutter/types";
 import type { MaterialEnhancer } from "../material/enhancer/MaterialEnhancer";
 import {
   createSdfTextMaterialEnhancer,
@@ -219,6 +224,27 @@ export class SDFTextMesh
   private _requestRender?: () => void;
   // The COLRv1 color atlas is always FontManager-owned; no local field needed.
 
+  /** 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 = new Float64Array(3);
+  /** Whether this label participates in screen-space decluttering. */
+  private _declutter = false;
+  /** Layer-level placement priority from the material. */
+  private _declutterPriority = 0;
+  /** Per-feature priority set through the evaluator; overrides the layer
+   *  value when defined. */
+  private _declutterPriorityOverride: number | undefined;
+  /** Current animated hide factor (mirrors the uDeclutterHide uniform) and
+   *  the placement target it is fading toward. */
+  private _declutterHide = 0;
+  private _declutterTarget = 0;
+  /** Text block dimensions in em units, mirroring the uTextWidth/uTextHeight/
+   *  uBgYBounds uniforms; 0 width means "no collision box" (empty text). */
+  private _labelWidthEm = 0;
+  private _labelHeightEm = 0;
+  private _labelMinYEm = 0;
+  private _labelMaxYEm = 0;
+
   private _enhancer: MaterialEnhancer<
     ShaderMaterial,
     { base?: SdfTextBaseProps },
@@ -235,12 +261,17 @@ export class SDFTextMesh
     fontUrl: string,
     batchId: number | undefined,
     RTE: boolean,
+    // Quality is fixed by the owning batch (flipping it needs a new batch), so
+    // it is passed in rather than re-derived from `material.highQuality` — the
+    // stored material can carry a newer, mismatched value by the time a mesh is
+    // created lazily, which must not diverge from the batch's atlas/shaping.
+    highQuality: boolean,
   ) {
     super();
 
     this._fontManager = fontManager;
     this._fontUrl = fontUrl;
-    this._highQuality = material.highQuality ?? false;
+    this._highQuality = highQuality;
     this._maxWidth = material.maxWidth ?? 0;
     this._lineHeight = material.lineHeight ?? 1.0;
     this._textAlign = ALIGN_FACTORS[material.textAlign ?? "center"] ?? 0.5;
@@ -311,6 +342,22 @@ export class SDFTextMesh
       transform.ty,
       transform.tz,
     ]);
+    this._cacheWorldAnchor(position, RTE, [
+      transform.tx,
+      transform.ty,
+      transform.tz,
+    ]);
+
+    // Decluttered labels start hidden and fade in once the placement pass
+    // grants them space — otherwise dense tiles flash their full clutter for
+    // a frame before the first pass runs.
+    this._declutter = material.declutter ?? true;
+    this._declutterPriority = material.declutterPriority ?? 0;
+    if (this._declutter) {
+      this._declutterHide = 1;
+      this._declutterTarget = 1;
+      mutates.setDeclutterHide(1);
+    }
 
     // Register shader hook
     mat.onBeforeCompile = this._enhancer.transformShader;
@@ -446,6 +493,7 @@ export class SDFTextMesh
 
     if (!text) {
       this.geometry.instanceCount = 0;
+      this._labelWidthEm = 0;
       this._setGlyphKeys([]);
       return;
     }
@@ -457,6 +505,7 @@ export class SDFTextMesh
     );
     if (!shapeResult) {
       this.geometry.instanceCount = 0;
+      this._labelWidthEm = 0;
       this._setGlyphKeys([]);
       return;
     }
@@ -546,6 +595,36 @@ export class SDFTextMesh
     this._enhancer.update({ base: { opacity: clampedOpacity } });
   }
 
+  /**
+   * 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 {
+    this._declutterTarget = hidden ? 1 : 0;
+  }
+
+  /**
+   * 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 {
+    const target = this._declutterTarget;
+    let value = this._declutterHide;
+    if (value === target) return false;
+
+    const step = deltaMs / DECLUTTER_FADE_MS;
+    value =
+      value < target
+        ? Math.min(value + step, target)
+        : Math.max(value - step, target);
+    this._declutterHide = value;
+    this._enhancer.mutates().setDeclutterHide(value);
+    return value !== target;
+  }
+
   _setFeatureWidth(_width: number): void {
     // Width is not applicable to text meshes.
     // This method is intentionally a no-op to satisfy the FeatureMesh guard.
@@ -565,6 +644,80 @@ export class SDFTextMesh
     this._enhancer
       .mutates()
       .setPosition(position, RTE, [transform.tx, transform.ty, transform.tz]);
+    this._cacheWorldAnchor(position, RTE, [
+      transform.tx,
+      transform.ty,
+      transform.tz,
+    ]);
+  }
+
+  /** Reconstruct the absolute ECEF anchor from the same inputs the position
+   *  uniforms receive (RTE high+low split, or RTC-relative + center). */
+  private _cacheWorldAnchor(
+    position: Float32Array | { high: Float32Array; low: Float32Array },
+    RTE: boolean,
+    rtcCenter: [number, number, number],
+  ): void {
+    const anchor = this._worldAnchor;
+    if (RTE) {
+      const p = position as { high: Float32Array; low: Float32Array };
+      anchor[0] = p.high[0] + p.low[0];
+      anchor[1] = p.high[1] + p.low[1];
+      anchor[2] = (p.high[2] ?? 0.0) + (p.low[2] ?? 0.0);
+    } else {
+      const p = position as Float32Array;
+      anchor[0] = p[0] + rtcCenter[0];
+      anchor[1] = p[1] + rtcCenter[1];
+      anchor[2] = (p[2] ?? 0.0) + rtcCenter[2];
+    }
+  }
+
+  /**
+   * 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 {
+    if (!this._declutter || !this.visible || this._labelWidthEm <= 0) {
+      return null;
+    }
+    const state = this._enhancer.states();
+    const size = state.fontSize;
+    if (size <= 0) return null;
+
+    const cx = Math.min(Math.max(state.center[0], -0.5), 0.5);
+    const cy = Math.min(Math.max(state.center[1], -0.5), 0.5);
+    const w = this._labelWidthEm;
+    const h = this._labelHeightEm;
+    return {
+      anchorX: this._worldAnchor[0],
+      anchorY: this._worldAnchor[1],
+      anchorZ: this._worldAnchor[2],
+      addHeight: state.addHeight,
+      minX: (0 - cx * w) * size,
+      maxX: (w - cx * w) * size,
+      minY: (this._labelMinYEm - cy * h) * size,
+      maxY: (this._labelMaxYEm - cy * h) * size,
+      sizeInMeters: state.sizeInMeters,
+      priority: this._declutterPriorityOverride ?? this._declutterPriority,
+      isShown: this._declutterTarget === 0,
+      owner,
+      handle,
+    };
+  }
+
+  /**
+   * 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 {
+    this._declutterPriorityOverride = priority;
   }
 
   /**
@@ -596,6 +749,17 @@ export class SDFTextMesh
       this.setText(this._text, true);
     }
 
+    // Read before the visibility early-return: the declutter pass consults
+    // these even while other style state is skipped for hidden labels.
+    const nextDeclutter = material.declutter ?? true;
+    if (this._declutter && !nextDeclutter) {
+      // Leaving declutter mode: clear any hide the pass applied — the mesh
+      // stops producing candidates, so nothing else would ever re-show it.
+      this.setDeclutterHidden(false);
+    }
+    this._declutter = nextDeclutter;
+    this._declutterPriority = material.declutterPriority ?? 0;
+
     this.visible = (material.show ?? true) && !!this._text;
     this._syncGlyphRefs();
     if (!this.visible) return;
@@ -921,6 +1085,7 @@ export class SDFTextMesh
     const count = renderable.length;
     if (count === 0) {
       this.geometry.instanceCount = 0;
+      this._labelWidthEm = 0;
       return;
     }
 
@@ -976,14 +1141,19 @@ export class SDFTextMesh
 
     this.geometry.instanceCount = count + 1;
 
-    // Update text dimension uniforms via mutates
+    // Update text dimension uniforms via mutates, mirroring them CPU-side for
+    // the declutter pass's collision box.
+    this._labelWidthEm = textWidth / SDF_PX_SIZE;
+    this._labelHeightEm = textHeight / SDF_PX_SIZE;
+    this._labelMinYEm = bgMinY === Infinity ? 0.0 : bgMinY;
+    this._labelMaxYEm = bgMaxY === -Infinity ? 1.0 : bgMaxY;
     this._enhancer
       .mutates()
       .updateTextDimensions(
-        textWidth / SDF_PX_SIZE,
-        textHeight / SDF_PX_SIZE,
-        bgMinY === Infinity ? 0.0 : bgMinY,
-        bgMaxY === -Infinity ? 1.0 : bgMaxY,
+        this._labelWidthEm,
+        this._labelHeightEm,
+        this._labelMinYEm,
+        this._labelMaxYEm,
       );
   }
 

package/src/mesh/sprite/instancedSprite.ts

@@ -10,14 +10,22 @@ import {
   Object3D,
   ShaderMaterial,
   BufferAttribute,
+  type BufferGeometry,
   Color,
+  type Material,
   PerspectiveCamera,
   Vector2,
 } from "three";
 import invariant from "tiny-invariant";
 
+import {
+  DECLUTTER_FADE_MS,
+  type DeclutterCandidate,
+  type DeclutterParticipant,
+} from "../../declutter/types";
 import type { EventContext } from "../../event/context";
 import { createInstancedSpriteMaterialEnhancer } from "../../material/enhancer";
+import type { CustomObject3DEventMap } from "../../object3DEvent";
 import { PickableMesh } from "../pickableMesh";
 
 import { BillboardAtlas, type AtlasRect } from "./billboardAtlas";
@@ -46,7 +54,10 @@ type PositionsInfo = {
 const _tmpSize = new Vector2();
 
 // Coupled with crates/navara_feature/src/geometry/point.rs::pixel_to_world
-export class InstancedSpriteMesh extends Mesh implements PickableMesh {
+export class InstancedSpriteMesh
+  extends Mesh<BufferGeometry, Material | Material[], CustomObject3DEventMap>
+  implements PickableMesh, DeclutterParticipant
+{
   private _batchIdToInstance = new Map<number, number>();
   private _initialColor: Color = new Color(0xffffff);
   private _initialHeight = 0.0;
@@ -72,15 +83,182 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
   private _enhancedMaterial?: ReturnType<
     typeof createInstancedSpriteMaterialEnhancer
   >;
+  /** Per-instance world anchors in ECEF meters (f64, 3 per instance), kept in
+   *  sync with the position attributes for the declutter pass. */
+  private _anchors: Float64Array | null = null;
+  /** Whether this mesh's instances participate in screen-space decluttering. */
+  private _declutter = false;
+  /** Layer-level placement priority from the material. */
+  private _declutterPriority = 0;
+  /** Per-instance priorities set through the evaluator (NaN = no override,
+   *  fall back to the layer value). Lazily allocated on first use. */
+  private _declutterPriorityOverrides: Float32Array | null = null;
+  /** Per-instance fade targets for `instanceDeclutterHide` (0 = shown,
+   *  1 = hidden); the attribute animates toward these in stepDeclutterFade. */
+  private _declutterTargets: Float32Array | null = null;
+  /** True while any instance's hide factor may differ from its target. */
+  private _declutterAnimating = false;
+
   constructor(options: InstancedSpriteOptions) {
     super();
     this.renderOrder = options.renderOrder ?? this.renderOrder;
     this.ctx = options.ctx;
+    this.ctx.declutter?.register(this);
+    // `processObjectRemoved` dispatches this for every removed mesh; it is the
+    // reliable teardown signal (this class's dispose() is not called there).
+    this.addEventListener("removedFromWorld", () => {
+      this.ctx.declutter?.unregister(this);
+    });
   }
 
   setActive(active: boolean) {
     this._active = active;
     this.updateVisibility();
+    this.ctx.declutter?.markDirty();
+  }
+
+  // --- DeclutterParticipant ---
+
+  collectDeclutterCandidates(out: DeclutterCandidate[]): void {
+    if (!this.visible || !this._declutter || !this._anchors) return;
+    const enhancer = this._enhancedMaterial;
+    const params = this.geometry?.getAttribute("instanceParams") as
+      InstancedBufferAttribute | undefined;
+    if (!enhancer || !params) return;
+
+    const state = enhancer.states();
+    const cx = Math.min(Math.max(state.center[0], -0.5), 0.5);
+    const cy = Math.min(Math.max(state.center[1], -0.5), 0.5);
+    // Mirror of instancedSprite.vert.glsl:100-104 — aspect is per-instance
+    // (from the atlas rect), not a material-level uniform; there is no
+    // material-wide "aspect" state to read.
+    const uvRect = state.billboard
+      ? (this.geometry?.getAttribute("instanceUvRect") as
+          InstancedBufferAttribute | undefined)
+      : undefined;
+    const anchors = this._anchors;
+    const overrides = this._declutterPriorityOverrides;
+    const targets = this._declutterTargets;
+    const count = Math.min(params.count, anchors.length / 3);
+
+    for (let i = 0; i < count; i++) {
+      if (params.getZ(i) <= 0.5) continue; // hidden by user `show`
+      const instanceSize = params.getY(i);
+      const size = instanceSize >= 0.0 ? instanceSize : state.scale;
+      if (size <= 0.0) continue;
+
+      const override = overrides ? overrides[i] : Number.NaN;
+      const rectH = uvRect ? uvRect.getW(i) : 0;
+      const aspect = uvRect && rectH > 0.0 ? uvRect.getZ(i) / rectH : 1.0;
+
+      // Mirror of instancedSprite.vert.glsl:95-97 — the quad spans
+      // (position.xy - center) * vec2(aspect, 1) * size around the anchor.
+      out.push({
+        anchorX: anchors[i * 3],
+        anchorY: anchors[i * 3 + 1],
+        anchorZ: anchors[i * 3 + 2],
+        addHeight: params.getX(i),
+        minX: (-0.5 - cx) * aspect * size,
+        maxX: (0.5 - cx) * aspect * size,
+        minY: (-0.5 - cy) * size,
+        maxY: (0.5 - cy) * size,
+        sizeInMeters: state.sizeInMeters,
+        // NaN-safe: an unset override falls back to the layer priority.
+        priority: Number.isNaN(override) ? this._declutterPriority : override,
+        isShown: targets ? targets[i] === 0 : true,
+        owner: this,
+        handle: i,
+      });
+    }
+  }
+
+  applyDeclutter(handle: number, hidden: boolean): void {
+    this.setDeclutterHiddenByInstance(handle, hidden);
+  }
+
+  stepDeclutterFade(deltaMs: number): boolean {
+    if (!this._declutterAnimating) return false;
+    const attr = this.geometry?.getAttribute("instanceDeclutterHide") as
+      InstancedBufferAttribute | undefined;
+    const targets = this._declutterTargets;
+    if (!attr || !targets) {
+      this._declutterAnimating = false;
+      return false;
+    }
+
+    const step = deltaMs / DECLUTTER_FADE_MS;
+    const count = Math.min(attr.count, targets.length);
+    let stillAnimating = false;
+    let changed = false;
+    for (let i = 0; i < count; i++) {
+      let value = attr.getX(i);
+      const target = targets[i];
+      if (value === target) continue;
+      value =
+        value < target
+          ? Math.min(value + step, target)
+          : Math.max(value - step, target);
+      attr.setX(i, value);
+      changed = true;
+      if (value !== target) stillAnimating = true;
+    }
+    if (changed) attr.needsUpdate = true;
+    this._declutterAnimating = stillAnimating;
+    return stillAnimating;
+  }
+
+  private _cacheDeclutterState(m: NavaraPointMesh | NavaraBillboardMesh) {
+    const nextDeclutter = m.material.declutter ?? true;
+    if (this._declutter && !nextDeclutter) {
+      // Leaving declutter mode: clear hides the pass applied — the mesh stops
+      // producing candidates, so nothing else would ever re-show them.
+      this._clearDeclutterHidden();
+    }
+    this._declutter = nextDeclutter;
+    this._declutterPriority = m.material.declutterPriority ?? 0;
+  }
+
+  private _clearDeclutterHidden(): void {
+    const targets = this._declutterTargets;
+    if (!targets) return;
+    targets.fill(0.0);
+    // Everything fades back in from wherever its hide factor currently is.
+    this._declutterAnimating = true;
+  }
+
+  /** Reconstruct absolute ECEF anchors from the same arrays the position
+   *  attributes receive (RTE high+low split, or RTC-relative + center). */
+  private _cacheAnchors(
+    positionsInfo: PositionsInfo,
+    transform: { tx: number; ty: number; tz: number },
+  ): void {
+    const { nPositions, positionSize, RTE } = positionsInfo;
+    const anchors =
+      this._anchors && this._anchors.length === nPositions * 3
+        ? this._anchors
+        : new Float64Array(nPositions * 3);
+
+    if (RTE) {
+      const pos = positionsInfo.position as {
+        high: Float32Array<ArrayBufferLike>;
+        low: Float32Array<ArrayBufferLike>;
+      };
+      for (let i = 0; i < nPositions; i++) {
+        const s = i * positionSize;
+        anchors[i * 3] = pos.high[s] + pos.low[s];
+        anchors[i * 3 + 1] = pos.high[s + 1] + pos.low[s + 1];
+        anchors[i * 3 + 2] = (pos.high[s + 2] ?? 0.0) + (pos.low[s + 2] ?? 0.0);
+      }
+    } else {
+      const pos = positionsInfo.position as Float32Array<ArrayBufferLike>;
+      for (let i = 0; i < nPositions; i++) {
+        const s = i * positionSize;
+        anchors[i * 3] = pos[s] + transform.tx;
+        anchors[i * 3 + 1] = pos[s + 1] + transform.ty;
+        anchors[i * 3 + 2] = (pos[s + 2] ?? 0.0) + transform.tz;
+      }
+    }
+    this._anchors = anchors;
   }
 
   async _init(m: NavaraPointMesh | NavaraBillboardMesh) {
@@ -90,6 +268,9 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
       return;
     }
 
+    this._cacheDeclutterState(m);
+    this._cacheAnchors(positionsInfo, m.transform);
+
     // Create Geometry
     this.geometry = this._initGeometry(positionsInfo, m);
 
@@ -97,12 +278,15 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
     this.material = await this._initMaterial(positionsInfo, m);
 
     this.frustumCulled = false; // Disable since bounding box doesn't account for instance positions
+    this.ctx.declutter?.markDirty();
   }
 
   async _update(m: NavaraPointMesh | NavaraBillboardMesh) {
     const enhancer = this.getEnhancer();
     const material = this.material as ShaderMaterial;
 
+    this._cacheDeclutterState(m);
+
     if (material.visible !== m.material.show) {
       material.visible = m.material.show ?? true;
       this.updateVisibility();
@@ -162,6 +346,7 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
       const positionsInfo = this.extractPositions(m);
 
       if (positionsInfo) {
+        this._cacheAnchors(positionsInfo, m.transform);
         if (positionsInfo.RTE) {
           const pos = positionsInfo.position as {
             high: Float32Array<ArrayBufferLike>;
@@ -198,6 +383,8 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
         await this._setDefaultImage(m.material.url);
       }
     }
+
+    this.ctx.declutter?.markDirty();
   }
 
   private _initGeometry(
@@ -307,6 +494,16 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
       "instanceColor",
       new InstancedBufferAttribute(colorBuffer, 3),
     );
+    // Declutter hide factors (0 = shown … 1 = hidden). Decluttered instances
+    // start hidden and fade in once the placement pass grants them space, so
+    // dense tiles don't flash their full clutter before the first pass runs.
+    const initialHide = this._declutter ? 1.0 : 0.0;
+    const declutterBuffer = new Float32Array(instanceCount).fill(initialHide);
+    this._declutterTargets = new Float32Array(instanceCount).fill(initialHide);
+    instancedGeometry.setAttribute(
+      "instanceDeclutterHide",
+      new InstancedBufferAttribute(declutterBuffer, 1),
+    );
     instancedGeometry.setAttribute(
       "instanceBatchID",
       new InstancedBufferAttribute(
@@ -572,6 +769,7 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
     ) as InstancedBufferAttribute;
     paramsAttr.setZ(instanceId, rawVisible ? 1.0 : 0.0);
     paramsAttr.needsUpdate = true;
+    this.ctx.declutter?.markDirty();
   }
 
   setFeatureOpacityByBatchId(batchId: number, opacity: number) {
@@ -599,6 +797,46 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
     const sanitizedHeight = Number.isFinite(height) ? height : 0.0;
     paramsAttr.setX(instanceId, sanitizedHeight);
     paramsAttr.needsUpdate = true;
+    this.ctx.declutter?.markDirty();
+  }
+
+  /**
+   * 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) {
+    const targets = this._declutterTargets;
+    if (!targets || instanceIndex < 0 || instanceIndex >= targets.length) {
+      return;
+    }
+    targets[instanceIndex] = hidden ? 1.0 : 0.0;
+    // Cheap over-approximation; stepDeclutterFade clears it when everything
+    // has reached its target.
+    this._declutterAnimating = true;
+  }
+
+  /**
+   * 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) {
+    const instanceId = this._batchIdToInstance.get(batchId);
+    if (instanceId === undefined) return;
+
+    if (!this._declutterPriorityOverrides) {
+      const count = this._anchors ? this._anchors.length / 3 : 0;
+      if (count === 0) return;
+      this._declutterPriorityOverrides = new Float32Array(count).fill(
+        Number.NaN,
+      );
+    }
+    if (instanceId >= this._declutterPriorityOverrides.length) return;
+    if (this._declutterPriorityOverrides[instanceId] === priority) return;
+    this._declutterPriorityOverrides[instanceId] = priority;
+    this.ctx.declutter?.markDirty();
   }
 
   setFeatureSizeByBatchId(batchId: number, size: number) {
@@ -616,6 +854,7 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
       : -1.0;
     paramsAttr.setY(instanceId, sanitizedSize);
     paramsAttr.needsUpdate = true;
+    this.ctx.declutter?.markDirty();
   }
 
   /**
@@ -634,8 +873,7 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
     if (instanceId === undefined) return;
 
     const rectAttr = this.geometry.getAttribute("instanceUvRect") as
-      | InstancedBufferAttribute
-      | undefined;
+      InstancedBufferAttribute | undefined;
     if (!rectAttr) return;
 
     if (url == null) {
@@ -669,6 +907,7 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
   }
 
   dispose(): void {
+    this.ctx.declutter?.unregister(this);
     this.geometry?.dispose();
 
     // The material's uTexture points at the atlas texture; the atlas owns it.
@@ -688,6 +927,9 @@ export class InstancedSpriteMesh extends Mesh implements PickableMesh {
 
     // Clear internal collections to release references
     this._batchIdToInstance.clear();
+    this._anchors = null;
+    this._declutterTargets = null;
+    this._declutterPriorityOverrides = null;
     this._imageOverrides.clear();
     this._requestedImageUrls.clear();
   }

package/src/orchestrators/RenderPassOrchestrator.ts

@@ -2,6 +2,8 @@ import { NamedIndexMap } from "@navaramap/core";
 import { EffectComposer, Pass as PostProcessingPass } from "postprocessing";
 import { HalfFloatType, Scene, WebGLRenderer, Group } from "three";
 
+import { estimateFixedGpuBytes } from "../utils/fixedGpuFootprint";
+
 export type RenderPassOrchestratorOptions = {
   halfFloat?: boolean;
   multisampling?: number;
@@ -34,6 +36,12 @@ export class RenderPassOrchestrator {
   };
   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 = new NamedIndexMap<NamedPass>();
 
   constructor(renderer: WebGLRenderer, options: RenderPassOrchestratorOptions) {
@@ -60,6 +68,7 @@ export class RenderPassOrchestrator {
     const namedPass: NamedPass = { name, pass };
     this.passMap.add(namedPass);
     this.effectComposer.addPass(pass);
+    this.onPassesChanged?.();
   }
 
   /**
@@ -73,6 +82,7 @@ export class RenderPassOrchestrator {
     const namedPass: NamedPass = { name, pass };
     const targetIndex = this.passMap.insertBefore(targetName, namedPass);
     this.effectComposer.addPass(pass, targetIndex);
+    this.onPassesChanged?.();
   }
 
   /**
@@ -86,6 +96,7 @@ export class RenderPassOrchestrator {
     const namedPass: NamedPass = { name, pass };
     const targetIndex = this.passMap.insertAfter(targetName, namedPass);
     this.effectComposer.addPass(pass, targetIndex);
+    this.onPassesChanged?.();
   }
 
   /**
@@ -100,6 +111,7 @@ export class RenderPassOrchestrator {
     this.effectComposer.removePass(targetPass.pass);
     this.passMap.list = this.passMap.list.filter((p) => p.name !== name);
     this.rebuildIndexMap();
+    this.onPassesChanged?.();
   }
 
   /**
@@ -125,6 +137,19 @@ export class RenderPassOrchestrator {
     }
     this.passMap.list = [];
     this.passMap.indexMap = {};
+    this.onPassesChanged?.();
+  }
+
+  /**
+   * 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 {
+    return estimateFixedGpuBytes(
+      this.effectComposer,
+      this.passMap.list.map((p) => p.pass),
+    );
   }
 
   /**