@navaramap/three 0.0.7 → 0.1.0

package/src/mesh/sdfText/batchedSdfText.ts

@@ -81,7 +81,10 @@ type PositionsInfo = PositionsInfoBase &
 type LabelRecord = {
   /** Row block in the label data texture, and this label's declutter handle. */
   slot: number;
-  batchIndex: number;
+  /** Anchor (position) slot this label sits on, NOT the feature index: a
+   * feature spans several anchors for MultiPoint geometry and for labels
+   * derived from line/polygon vertices via `geometryTypes`. */
+  instanceIndex: number;
   batchId: number;
   /** The text currently laid out into the glyph run. */
   text: string;
@@ -179,8 +182,15 @@ export class BatchedSdfTextMesh
 
   /** Labels in slot order — `_labels[slot]` is also the declutter handle map. */
   private _labels: LabelRecord[] = [];
-  /** Sparse batchIndex → label; labels are created on first per-feature touch. */
-  private _labelByIndex: (LabelRecord | undefined)[] = [];
+  /** Sparse anchor slot → label; labels are created on first per-feature touch. */
+  private _labelByInstance: (LabelRecord | undefined)[] = [];
+  /**
+   * Feature (batch) index → this feature's anchor slots. A feature owns
+   * multiple anchors for MultiPoint geometry and for labels derived from
+   * line/polygon vertices via `geometryTypes`, so per-feature styling must fan
+   * out to all of them. `null` means anchors and features are 1:1.
+   */
+  private _batchIndexToInstances: Map<number, number[]> | null = null;
 
   /** In-flight per-feature text preparations; see {@link whenLabelsSettled}. */
   private _pendingTextPrepares = new PendingSettlement();
@@ -240,6 +250,7 @@ export class BatchedSdfTextMesh
     this._declutterPriority = material.declutterPriority ?? 0;
 
     this._positions = this.extractPositions(m);
+    this._rebuildBatchIndexMap(m);
     this._glyphs = new GlyphBuffers();
     this._labelData = new LabelDataTexture();
 
@@ -359,12 +370,12 @@ export class BatchedSdfTextMesh
     for (let i = 0; i < info.nPositions; i++) this._ensureLabel(i);
   }
 
-  private _ensureLabel(batchIndex: number): LabelRecord | undefined {
-    const existing = this._labelByIndex[batchIndex];
+  private _ensureLabel(instanceIndex: number): LabelRecord | undefined {
+    const existing = this._labelByInstance[instanceIndex];
     if (existing) return existing;
 
     const info = this._positions;
-    if (!info || batchIndex < 0 || batchIndex >= info.nPositions) {
+    if (!info || instanceIndex < 0 || instanceIndex >= info.nPositions) {
       return undefined;
     }
 
@@ -376,8 +387,10 @@ export class BatchedSdfTextMesh
 
     const record: LabelRecord = {
       slot,
-      batchIndex,
-      batchId: info.batchIDs ? info.batchIDs[batchIndex * info.batchIDSize] : 0,
+      instanceIndex,
+      batchId: info.batchIDs
+        ? info.batchIDs[instanceIndex * info.batchIDSize]
+        : 0,
       text: "",
       requestedText: "",
       prepareDeferred: false,
@@ -405,7 +418,7 @@ export class BatchedSdfTextMesh
     };
 
     this._labels.push(record);
-    this._labelByIndex[batchIndex] = record;
+    this._labelByInstance[instanceIndex] = record;
 
     this._writeAnchor(record);
     this._writeStyle(record);
@@ -419,7 +432,7 @@ export class BatchedSdfTextMesh
   private _writeAnchor(record: LabelRecord): void {
     const info = this._positions;
     if (!info) return;
-    const idx = record.batchIndex * info.positionSize;
+    const idx = record.instanceIndex * info.positionSize;
     const anchor = record.anchor;
 
     if (info.RTE) {
@@ -971,6 +984,51 @@ export class BatchedSdfTextMesh
     return null;
   }
 
+  /**
+   * Group anchor slots by their feature's batch index from the geometry's
+   * per-anchor `batch_index` buffer. The u32 view is consumed synchronously —
+   * other wasm calls may detach views, so it must not be stored. An identity
+   * mapping (every feature owns exactly one anchor, the common MVT case) skips
+   * the map entirely.
+   */
+  private _rebuildBatchIndexMap(m: NavaraTextMesh): void {
+    const batchIndexData = m.geometry.batch_index?.data;
+    const batchIndices =
+      batchIndexData !== undefined ? this.ctx.buf.u32(batchIndexData) : null;
+    this._batchIndexToInstances = null;
+    if (!batchIndices) return;
+
+    let identity = true;
+    for (let i = 0; i < batchIndices.length; i++) {
+      if (batchIndices[i] !== i) {
+        identity = false;
+        break;
+      }
+    }
+    if (identity) return;
+
+    const map = new Map<number, number[]>();
+    for (let i = 0; i < batchIndices.length; i++) {
+      const batchIndex = batchIndices[i];
+      let instances = map.get(batchIndex);
+      if (!instances) {
+        instances = [];
+        map.set(batchIndex, instances);
+      }
+      instances.push(i);
+    }
+    this._batchIndexToInstances = map;
+  }
+
+  /** All anchor slots owned by the feature at `batchIndex`. */
+  private _instancesOfBatchIndex(batchIndex: number): number[] {
+    if (this._batchIndexToInstances) {
+      return this._batchIndexToInstances.get(batchIndex) ?? [];
+    }
+    const nPositions = this._positions?.nPositions ?? 0;
+    return batchIndex >= 0 && batchIndex < nPositions ? [batchIndex] : [];
+  }
+
   async _update(m: NavaraTextMesh, needRender?: () => void) {
     if (needRender) this._needRender = needRender;
 
@@ -992,6 +1050,7 @@ export class BatchedSdfTextMesh
         "Number of positions in the updated geometry must match the initial geometry",
       );
       this._positions = positionInfo;
+      this._rebuildBatchIndexMap(m);
       this._enhancer
         .mutates()
         .setRtcCenter([m.transform.tx, m.transform.ty, m.transform.tz]);
@@ -1162,12 +1221,18 @@ export class BatchedSdfTextMesh
   // --- Per-feature API (the FeatureEvaluator contract) ---
 
   setTextByBatchIndex(batchIndex: number, text: string) {
+    for (const instanceIndex of this._instancesOfBatchIndex(batchIndex)) {
+      this._setTextByInstance(instanceIndex, text);
+    }
+  }
+
+  private _setTextByInstance(instanceIndex: number, text: string) {
     // An empty text on a label that doesn't exist yet changes nothing (a
     // lazily-skipped label is exactly an invisible empty-text label); only a
     // non-empty text forces one into existence.
     const record = text
-      ? this._ensureLabel(batchIndex)
-      : this._labelByIndex[batchIndex];
+      ? this._ensureLabel(instanceIndex)
+      : this._labelByInstance[instanceIndex];
     if (!record) return;
 
     // Record the intent up front so a slower prepare for an older text can
@@ -1284,57 +1349,69 @@ export class BatchedSdfTextMesh
   }
 
   override setFeatureColorByBatchIndex(batchIndex: number, color: Color) {
-    const record = this._ensureLabel(batchIndex);
-    if (!record) return;
-    record.colorHex = color.getHex();
-    this._writeStyle(record);
+    for (const instanceIndex of this._instancesOfBatchIndex(batchIndex)) {
+      const record = this._ensureLabel(instanceIndex);
+      if (!record) continue;
+      record.colorHex = color.getHex();
+      this._writeStyle(record);
+    }
   }
 
   override setFeatureShowByBatchIndex(batchIndex: number, rawVisible: boolean) {
-    // A label that doesn't exist yet is already effectively `show:false`, so
-    // only `show:true` needs to force one into existence — the common MVT case
-    // is thousands of features that stay hidden and never get a label.
-    const record = rawVisible
-      ? this._ensureLabel(batchIndex)
-      : this._labelByIndex[batchIndex];
-    if (!record) return;
-    record.requestedShow = rawVisible;
-    this._recomputeShow(record);
+    for (const instanceIndex of this._instancesOfBatchIndex(batchIndex)) {
+      // A label that doesn't exist yet is already effectively `show:false`, so
+      // only `show:true` needs to force one into existence — the common MVT
+      // case is thousands of features that stay hidden and never get a label.
+      const record = rawVisible
+        ? this._ensureLabel(instanceIndex)
+        : this._labelByInstance[instanceIndex];
+      if (!record) continue;
+      record.requestedShow = rawVisible;
+      this._recomputeShow(record);
+    }
     this._markDeclutterDirty();
   }
 
   override setFeatureHeightByBatchIndex(batchIndex: number, height: number) {
-    const record = this._ensureLabel(batchIndex);
-    if (!record) return;
-    record.addHeight = height;
-    this._writeAddHeight(record);
+    for (const instanceIndex of this._instancesOfBatchIndex(batchIndex)) {
+      const record = this._ensureLabel(instanceIndex);
+      if (!record) continue;
+      record.addHeight = height;
+      this._writeAddHeight(record);
+    }
     this._markDeclutterDirty();
   }
 
   setFeatureSizeByBatchIndex(batchIndex: number, size: number) {
-    const record = this._ensureLabel(batchIndex);
-    if (!record) return;
-    record.fontSize = Number.isFinite(size)
-      ? Math.max(0.0, size)
-      : record.fontSize;
-    this._writeFontSize(record);
+    for (const instanceIndex of this._instancesOfBatchIndex(batchIndex)) {
+      const record = this._ensureLabel(instanceIndex);
+      if (!record) continue;
+      record.fontSize = Number.isFinite(size)
+        ? Math.max(0.0, size)
+        : record.fontSize;
+      this._writeFontSize(record);
+    }
     this._markDeclutterDirty();
   }
 
   setFeatureOpacityByBatchIndex(batchIndex: number, opacity: number) {
-    const record = this._ensureLabel(batchIndex);
-    if (!record) return;
-    record.opacity = clamp01(opacity);
-    this._writeStyle(record);
+    for (const instanceIndex of this._instancesOfBatchIndex(batchIndex)) {
+      const record = this._ensureLabel(instanceIndex);
+      if (!record) continue;
+      record.opacity = clamp01(opacity);
+      this._writeStyle(record);
+    }
   }
 
   setFeatureDeclutterPriorityByBatchIndex(
     batchIndex: number,
     priority: number,
   ) {
-    const record = this._ensureLabel(batchIndex);
-    if (!record) return;
-    record.priorityOverride = priority;
+    for (const instanceIndex of this._instancesOfBatchIndex(batchIndex)) {
+      const record = this._ensureLabel(instanceIndex);
+      if (!record) continue;
+      record.priorityOverride = priority;
+    }
     this._markDeclutterDirty();
   }
 
@@ -1368,7 +1445,8 @@ export class BatchedSdfTextMesh
       record.retainedKeys = null;
     }
     this._labels.length = 0;
-    this._labelByIndex.length = 0;
+    this._labelByInstance.length = 0;
+    this._batchIndexToInstances = null;
 
     this._labelData.dispose();
     this._glyphs.dispose();

package/src/mesh/sprite/billboardAtlas.ts

@@ -1,4 +1,10 @@
-import { DataTexture, LinearFilter, RGBAFormat, UnsignedByteType } from "three";
+import {
+  DataTexture,
+  LinearFilter,
+  RGBAFormat,
+  SRGBColorSpace,
+  UnsignedByteType,
+} from "three";
 
 /**
  * Sub-rectangle of the atlas in pixels. Row 0 is the bottom of the texture
@@ -201,6 +207,7 @@ export class BillboardAtlas {
     const texture = new DataTexture(this._data, this._size, this._size);
     texture.format = RGBAFormat;
     texture.type = UnsignedByteType;
+    texture.colorSpace = SRGBColorSpace;
     texture.minFilter = LinearFilter;
     texture.magFilter = LinearFilter;
     texture.generateMipmaps = false;

package/src/mesh/sprite/instancedSprite.ts

@@ -66,7 +66,15 @@ export class InstancedSpriteMesh
   implements PickableMesh, DeclutterParticipant
 {
   private _geometryType: SpriteGeometryType = GEOMETRY_TYPES.Point;
-  private _batchIdToInstance = new Map<number, number>();
+  /**
+   * Feature (batch) index → this feature's instance ids. A feature owns
+   * multiple instances for MultiPoint geometry and for points derived from
+   * line/polygon vertices via `geometryTypes`, so per-feature styling must
+   * fan out to all of them. `null` means instances and features are 1:1.
+   */
+  private _batchIndexToInstances: Map<number, number[]> | null = null;
+  /** Instance count of the current geometry; bounds the identity fallback. */
+  private _instanceCount = 0;
   private _initialColor: Color = new Color(0xffffff);
   private _initialHeight = 0.0;
   private _initialSize = -1.0; // Negative value indicates "use uScale" in shader
@@ -161,7 +169,7 @@ export class InstancedSpriteMesh
     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
+    // Mirror of instancedSprite.vert.glsl:115-118 — 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
@@ -181,9 +189,14 @@ export class InstancedSpriteMesh
 
       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
+      const rectW = uvRect ? uvRect.getZ(i) : 0;
+      // Mirror of the shader's empty-rect cull: an instance with no image
+      // packed yet is not drawn, so it must not reserve declutter space and
+      // hide the labels around it.
+      if (uvRect && (rectW <= 0.0 || rectH <= 0.0)) continue;
+      const aspect = uvRect ? rectW / rectH : 1.0;
+
+      // Mirror of instancedSprite.vert.glsl:122-125 — the quad spans
       // (position.xy - center) * vec2(aspect, 1) * size around the anchor.
       out.push({
         anchorX: anchors[i * 3],
@@ -481,17 +494,15 @@ export class InstancedSpriteMesh
       colorBuffer[i * 3 + 0] = this._initialColor.r;
       colorBuffer[i * 3 + 1] = this._initialColor.g;
       colorBuffer[i * 3 + 2] = this._initialColor.b;
-
-      // Map batch ID to instance id
-      // assuming batch IDs are 32bit floats
-      const batchId = positionsInfo.batchIDs[i];
-      this._batchIdToInstance.set(batchId, i);
     }
 
+    this._instanceCount = instanceCount;
+    this._rebuildBatchIndexMap(m);
+
     if (m instanceof NavaraBillboardMesh) {
       // instanceUvRect: vec4(x, y, w, h) — this instance's atlas sub-rect in
-      // pixels. Zeroed until an image is packed; a zero-height rect samples a
-      // transparent texel, so instances stay invisible rather than garbled.
+      // pixels. Zeroed until an image is packed; the vertex shader culls empty
+      // rects, so instances stay invisible rather than garbled.
       instancedGeometry.setAttribute(
         "instanceUvRect",
         new InstancedBufferAttribute(new Float32Array(instanceCount * 4), 4),
@@ -755,6 +766,20 @@ export class InstancedSpriteMesh
       rectAttr.setXYZW(i, rect.x, rect.y, rect.w, rect.h);
     }
     rectAttr.needsUpdate = true;
+    this._onAtlasRectsChanged();
+  }
+
+  /**
+   * An instance's atlas rect changed. The rect drives the quad's aspect and
+   * whether the instance draws at all, so the declutter bounds computed before
+   * the image landed are stale — and because packs resolve long after the
+   * frame that requested them, the view has usually gone idle by now. Without
+   * the render request the page keeps showing the pre-image state until the
+   * next camera move.
+   */
+  private _onAtlasRectsChanged(): void {
+    this.ctx.declutter?.markDirty();
+    this.ctx.renderFlag.forceUpdate = true;
   }
 
   onBeforePicking(): void {
@@ -781,32 +806,85 @@ export class InstancedSpriteMesh
     return this._enhancedMaterial;
   }
 
-  setFeatureColorByBatchId(batchId: number, color: Color) {
-    const instanceId = this._batchIdToInstance.get(batchId);
-    if (instanceId === undefined) return;
+  /**
+   * Group instances by their feature's batch index from the geometry's
+   * per-instance `batch_index` buffer. The u32 view is consumed synchronously,
+   * so other wasm calls may detach views, so it must not be stored. The handle
+   * stays owned by the ECS geometry, whose destroy path frees it
+   * (`remove_from_buf`). An identity mapping (every feature owns exactly one
+   * instance, the common case) skips the map entirely.
+   */
+  private _rebuildBatchIndexMap(
+    m: NavaraPointMesh | NavaraBillboardMesh,
+  ): void {
+    const batchIndexData = m.geometry.batch_index?.data;
+    const batchIndices =
+      batchIndexData !== undefined ? this.ctx.buf.u32(batchIndexData) : null;
+    this._batchIndexToInstances = null;
+    if (!batchIndices) return;
+
+    let identity = true;
+    for (let i = 0; i < batchIndices.length; i++) {
+      if (batchIndices[i] !== i) {
+        identity = false;
+        break;
+      }
+    }
+    if (identity) return;
+
+    const map = new Map<number, number[]>();
+    for (let i = 0; i < batchIndices.length; i++) {
+      const batchIndex = batchIndices[i];
+      let instances = map.get(batchIndex);
+      if (!instances) {
+        instances = [];
+        map.set(batchIndex, instances);
+      }
+      instances.push(i);
+    }
+    this._batchIndexToInstances = map;
+  }
+
+  /** All instances owned by the feature at `batchIndex`; empty when unknown. */
+  private instancesOfBatchIndex(batchIndex: number): number[] {
+    if (this._batchIndexToInstances) {
+      return this._batchIndexToInstances.get(batchIndex) ?? [];
+    }
+    return batchIndex >= 0 && batchIndex < this._instanceCount
+      ? [batchIndex]
+      : [];
+  }
+
+  setFeatureColorByBatchIndex(batchIndex: number, color: Color) {
+    const instances = this.instancesOfBatchIndex(batchIndex);
+    if (instances.length === 0) return;
 
     const colorAttr = this.geometry.getAttribute(
       "instanceColor",
     ) as InstancedBufferAttribute;
-    colorAttr.setXYZ(instanceId, color.r, color.g, color.b);
+    for (const instanceId of instances) {
+      colorAttr.setXYZ(instanceId, color.r, color.g, color.b);
+    }
     colorAttr.needsUpdate = true;
   }
 
-  setFeatureShowByBatchId(batchId: number, rawVisible: boolean) {
-    const instanceId = this._batchIdToInstance.get(batchId);
-    if (instanceId === undefined) return;
+  setFeatureShowByBatchIndex(batchIndex: number, rawVisible: boolean) {
+    const instances = this.instancesOfBatchIndex(batchIndex);
+    if (instances.length === 0) return;
 
     const paramsAttr = this.geometry.getAttribute(
       "instanceParams",
     ) as InstancedBufferAttribute;
-    paramsAttr.setZ(instanceId, rawVisible ? 1.0 : 0.0);
+    for (const instanceId of instances) {
+      paramsAttr.setZ(instanceId, rawVisible ? 1.0 : 0.0);
+    }
     paramsAttr.needsUpdate = true;
     this.ctx.declutter?.markDirty();
   }
 
-  setFeatureOpacityByBatchId(batchId: number, opacity: number) {
-    const instanceId = this._batchIdToInstance.get(batchId);
-    if (instanceId === undefined) return;
+  setFeatureOpacityByBatchIndex(batchIndex: number, opacity: number) {
+    const instances = this.instancesOfBatchIndex(batchIndex);
+    if (instances.length === 0) return;
 
     const paramsAttr = this.geometry.getAttribute(
       "instanceParams",
@@ -814,20 +892,24 @@ export class InstancedSpriteMesh
     const clampedOpacity = Number.isFinite(opacity)
       ? Math.max(0.0, Math.min(1.0, opacity))
       : 1.0;
-    paramsAttr.setW(instanceId, clampedOpacity);
+    for (const instanceId of instances) {
+      paramsAttr.setW(instanceId, clampedOpacity);
+    }
     paramsAttr.needsUpdate = true;
   }
 
-  setFeatureHeightByBatchId(batchId: number, height: number) {
-    const instanceId = this._batchIdToInstance.get(batchId);
-    if (instanceId === undefined) return;
+  setFeatureHeightByBatchIndex(batchIndex: number, height: number) {
+    const instances = this.instancesOfBatchIndex(batchIndex);
+    if (instances.length === 0) return;
 
     const paramsAttr = this.geometry.getAttribute(
       "instanceParams",
     ) as InstancedBufferAttribute;
 
     const sanitizedHeight = Number.isFinite(height) ? height : 0.0;
-    paramsAttr.setX(instanceId, sanitizedHeight);
+    for (const instanceId of instances) {
+      paramsAttr.setX(instanceId, sanitizedHeight);
+    }
     paramsAttr.needsUpdate = true;
     this.ctx.declutter?.markDirty();
   }
@@ -854,9 +936,12 @@ export class InstancedSpriteMesh
    * 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;
+  setFeatureDeclutterPriorityByBatchIndex(
+    batchIndex: number,
+    priority: number,
+  ) {
+    const instances = this.instancesOfBatchIndex(batchIndex);
+    if (instances.length === 0) return;
 
     if (!this._declutterPriorityOverrides) {
       const count = this._anchors ? this._anchors.length / 3 : 0;
@@ -865,15 +950,21 @@ export class InstancedSpriteMesh
         Number.NaN,
       );
     }
-    if (instanceId >= this._declutterPriorityOverrides.length) return;
-    if (this._declutterPriorityOverrides[instanceId] === priority) return;
-    this._declutterPriorityOverrides[instanceId] = priority;
-    this.ctx.declutter?.markDirty();
+    let changed = false;
+    for (const instanceId of instances) {
+      if (instanceId >= this._declutterPriorityOverrides.length) continue;
+      if (this._declutterPriorityOverrides[instanceId] === priority) continue;
+      this._declutterPriorityOverrides[instanceId] = priority;
+      changed = true;
+    }
+    if (changed) {
+      this.ctx.declutter?.markDirty();
+    }
   }
 
-  setFeatureSizeByBatchId(batchId: number, size: number) {
-    const instanceId = this._batchIdToInstance.get(batchId);
-    if (instanceId === undefined) return;
+  setFeatureSizeByBatchIndex(batchIndex: number, size: number) {
+    const instances = this.instancesOfBatchIndex(batchIndex);
+    if (instances.length === 0) return;
 
     const paramsAttr = this.geometry.getAttribute(
       "instanceParams",
@@ -884,7 +975,9 @@ export class InstancedSpriteMesh
         ? -1.0
         : size
       : -1.0;
-    paramsAttr.setY(instanceId, sanitizedSize);
+    for (const instanceId of instances) {
+      paramsAttr.setY(instanceId, sanitizedSize);
+    }
     paramsAttr.needsUpdate = true;
     this.ctx.declutter?.markDirty();
   }
@@ -897,45 +990,60 @@ export class InstancedSpriteMesh
    * reverts the feature to the material's default image. No-op for
    * non-billboard (point) meshes.
    */
-  async setFeatureImageByBatchId(
-    batchId: number,
+  async setFeatureImageByBatchIndex(
+    batchIndex: number,
     url: string | null | undefined,
   ): Promise<void> {
-    const instanceId = this._batchIdToInstance.get(batchId);
-    if (instanceId === undefined) return;
+    const instances = this.instancesOfBatchIndex(batchIndex);
+    if (instances.length === 0) return;
 
     const rectAttr = this.geometry.getAttribute("instanceUvRect") as
       InstancedBufferAttribute | undefined;
     if (!rectAttr) return;
 
     if (url == null) {
-      this._requestedImageUrls.delete(instanceId);
-      if (!this._imageOverrides.delete(instanceId)) return;
-      // Zero rect (invisible) until the default image finishes loading, same
-      // as instances that never had an override.
-      const rect = this._defaultRect;
-      rectAttr.setXYZW(
-        instanceId,
-        rect?.x ?? 0,
-        rect?.y ?? 0,
-        rect?.w ?? 0,
-        rect?.h ?? 0,
-      );
-      rectAttr.needsUpdate = true;
+      let cleared = false;
+      for (const instanceId of instances) {
+        this._requestedImageUrls.delete(instanceId);
+        if (!this._imageOverrides.delete(instanceId)) continue;
+        // Zero rect (invisible) until the default image finishes loading,
+        // same as instances that never had an override.
+        const rect = this._defaultRect;
+        rectAttr.setXYZW(
+          instanceId,
+          rect?.x ?? 0,
+          rect?.y ?? 0,
+          rect?.w ?? 0,
+          rect?.h ?? 0,
+        );
+        cleared = true;
+      }
+      if (cleared) {
+        rectAttr.needsUpdate = true;
+        this._onAtlasRectsChanged();
+      }
       return;
     }
 
-    this._requestedImageUrls.set(instanceId, url);
+    for (const instanceId of instances) {
+      this._requestedImageUrls.set(instanceId, url);
+    }
     const rect = await this._ensureAtlas().pack(url);
     this._reportAtlasBytes();
     if (!rect) return;
-    // A newer override or a clear superseded this load while it was in flight.
-    if (this._requestedImageUrls.get(instanceId) !== url) return;
-
-    this._imageOverrides.add(instanceId);
-    this._syncAtlasUniforms();
-    rectAttr.setXYZW(instanceId, rect.x, rect.y, rect.w, rect.h);
-    rectAttr.needsUpdate = true;
+    let applied = false;
+    for (const instanceId of instances) {
+      // A newer override or a clear superseded this load while in flight.
+      if (this._requestedImageUrls.get(instanceId) !== url) continue;
+      this._imageOverrides.add(instanceId);
+      rectAttr.setXYZW(instanceId, rect.x, rect.y, rect.w, rect.h);
+      applied = true;
+    }
+    if (applied) {
+      this._syncAtlasUniforms();
+      rectAttr.needsUpdate = true;
+      this._onAtlasRectsChanged();
+    }
   }
 
   dispose(): void {
@@ -958,7 +1066,7 @@ export class InstancedSpriteMesh
     (this.material as ShaderMaterial).dispose();
 
     // Clear internal collections to release references
-    this._batchIdToInstance.clear();
+    this._batchIndexToInstances = null;
     this._anchors = null;
     this._declutterTargets = null;
     this._declutterPriorityOverrides = null;