@ifc-lite/renderer 1.41.1 → 1.43.0

package/dist/scene.js

@@ -36,10 +36,23 @@ export class Scene {
      *  Refcounted: entries die when the last referencing mesh is removed / on clear(). */
     sharedTextures = new Map();
     texturedDevice; // #961: cached for textured-mesh re-upload on translate
-    instancedTemplates = []; // GPU-instancing: unique templates + per-occurrence buffers (fed by addInstancedShard)
+    /** GPU-instancing: unique templates + per-occurrence buffers (fed by
+     *  addInstancedShard). SLOT-STABLE and therefore SPARSE: a per-model removal
+     *  (`removeInstancedTemplatesForModel`) leaves `undefined` holes instead of
+     *  splicing, because `InstancedOccurrence.templateIndex` holds the slot by
+     *  value and a splice would silently repoint every later occurrence at the
+     *  wrong template. New templates always append at `length`; freed slots are
+     *  never recycled. Iterate `getInstancedTemplates()` (compacted, cached) for
+     *  the draw/pick/accounting walks — never this array directly. */
+    instancedTemplates = [];
+    /** Compacted live view of `instancedTemplates`, rebuilt on mutation. */
+    liveInstancedTemplates = [];
     instancedVisible = true; // GPU-instancing: hidden in Types view mode (instanced geometry is class-0 occurrences)
     instancedEntityMap = new Map(); // express_id -> occurrences, for per-instance selection/overlay patching
-    instancedTemplateCpu = []; // compact CPU geometry per template (index-aligned with instancedTemplates) for CPU consumers
+    /** Compact CPU geometry per template, slot-aligned with `instancedTemplates`
+     *  (so equally sparse) for CPU consumers. Also emptied wholesale on geometry
+     *  release — every reader already tolerates a missing entry. */
+    instancedTemplateCpu = [];
     instancedDevice; // cached for per-instance flag/colour writeBuffer updates
     instancedSelected = new Set(); // currently flag-selected instanced express_ids
     instancedHidden = new Set(); // currently hidden instanced express_ids (hide/isolate)
@@ -1876,94 +1889,156 @@ export class Scene {
         // synchronously, so settle-sensitive consumers need this flag until the
         // time-sliced rebuild swaps the new batch array in.
         this.finalizeInProgress = true;
-        // --- Synchronous preamble (fast O(N) bookkeeping) ---
+        const scene = this;
         const oldFragments = this.streamingFragments;
         const oldBatches = this.batchedMeshes;
         const fragmentSet = new Set(oldFragments);
-        this.streamingFragments = [];
-        // 1. Collect ALL accumulated meshData (cold buckets carried as sealed
-        //    shells — see the sync finalize for the rationale)
-        const allMeshData = [];
-        const carriedCold = [];
-        for (const [key, bucket] of this.buckets) {
-            if (this.coldBuckets.has(key) && bucket.meshData.length === 0 && bucket.batchedMesh) {
-                carriedCold.push([key, bucket]);
-                continue;
+        const oldBatchSet = new Set(oldBatches);
+        // The chunked rebuild spans multiple event-loop turns via setTimeout, so a
+        // throw inside a LATER chunk is a distinct macrotask — it does NOT reject
+        // the promise below just because that code sits inside its executor (only
+        // a SYNCHRONOUS throw during the executor's own call frame does that per
+        // spec). Every entry point that can fail — the synchronous preamble AND
+        // each chunked continuation — must therefore run under its own try/catch
+        // that explicitly calls `reject`, mirroring finalizeStreamingInner's
+        // try/finally contract: restore oldFragments/oldBatches, free only what
+        // this attempt created, defer dropAllPartialCaches() until success, and
+        // always clear finalizeInProgress.
+        return new Promise((resolve, reject) => {
+            const newBatches = [];
+            // Every batch this attempt creates, paired with the bucket that now owns
+            // it and the value it displaced. `newBatches` alone is not enough to roll
+            // back: processChunk publishes each batch into `bucket.batchedMesh`, so
+            // freeing it without repairing the owner leaves the bucket map pointing
+            // at destroyed GPU resources (use-after-free on the next bucket-driven
+            // access). `previous` is null for the freshly built buckets and, for a
+            // carried COLD bucket a re-grouped meshData landed in, the shell that the
+            // restored `batchedMeshes` still holds — which must be put back, not
+            // nulled.
+            const createdOwned = [];
+            let carriedCold = [];
+            let pendingKeys = [];
+            let keyIdx = 0;
+            function rollback() {
+                // Free ONLY what this attempt created — carried cold shells and
+                // anything already live before the rebuild must be left alone (they
+                // are what the restored arrays point back at). Iterating the owned
+                // pairs rather than `newBatches` also skips the carried cold shells
+                // appended just before the swap, which this attempt did not create.
+                for (const { bucket, previous, batch } of createdOwned) {
+                    // Repair the owner BEFORE the free, so no bucket is ever observable
+                    // holding a destroyed batch.
+                    if (bucket.batchedMesh === batch)
+                        bucket.batchedMesh = previous;
+                    if (!oldBatchSet.has(batch) && !fragmentSet.has(batch)) {
+                        destroyGpuResources(batch);
+                    }
+                }
+                scene.streamingFragments = oldFragments;
+                scene.batchedMeshes = oldBatches;
+                scene.finalizeInProgress = false;
             }
-            for (const md of bucket.meshData)
-                allMeshData.push(md);
-        }
-        // 2. Clear bucket/batch state
-        this.buckets.clear();
-        this.meshDataBucket = new Map();
-        this.activeBucketKey.clear();
-        this.lastDrawnFrame.clear();
-        this.residencyRestoreQueue.clear();
-        this.pendingBatchKeys.clear();
-        this.dropAllPartialCaches();
-        // Re-seat the carried cold shells in the fresh bucket map.
-        for (const [key, bucket] of carriedCold)
-            this.buckets.set(key, bucket);
-        // 3. Re-group meshData by current color (and grid cell) — fast
-        for (const meshData of allMeshData) {
-            const baseKey = this.bucketBaseKey(meshData);
-            const bucketKey = this.resolveActiveBucket(baseKey, meshData);
-            let bucket = this.buckets.get(bucketKey);
-            if (!bucket) {
-                bucket = { key: bucketKey, meshData: [], batchedMesh: null, vertexBytes: 0 };
-                this.buckets.set(bucketKey, bucket);
-            }
-            bucket.meshData.push(meshData);
-            this.meshDataBucket.set(meshData, bucket);
-            this.pendingBatchKeys.add(bucketKey);
-        }
-        // Build new batches into a temporary array so the old batchedMeshes
-        // (streaming fragments) keep rendering until the swap is complete.
-        const newBatches = [];
-        const pendingKeys = Array.from(this.pendingBatchKeys);
-        this.pendingBatchKeys.clear();
-        // --- Async: rebuild batches in time-sliced chunks ---
-        let keyIdx = 0;
-        const scene = this;
-        return new Promise((resolve) => {
             function processChunk() {
-                const chunkStart = performance.now();
-                while (keyIdx < pendingKeys.length) {
-                    const key = pendingKeys[keyIdx++];
-                    const bucket = scene.buckets.get(key);
-                    if (!bucket || bucket.meshData.length === 0) {
-                        scene.buckets.delete(key);
-                        continue;
+                try {
+                    const chunkStart = performance.now();
+                    while (keyIdx < pendingKeys.length) {
+                        const key = pendingKeys[keyIdx++];
+                        const bucket = scene.buckets.get(key);
+                        if (!bucket || bucket.meshData.length === 0) {
+                            scene.buckets.delete(key);
+                            continue;
+                        }
+                        const color = bucket.meshData[0].color;
+                        const previous = bucket.batchedMesh;
+                        const batchedMesh = scene.createBatchedMesh(bucket.meshData, color, device, pipeline, key);
+                        bucket.batchedMesh = batchedMesh;
+                        createdOwned.push({ bucket, previous, batch: batchedMesh });
+                        newBatches.push(batchedMesh);
+                        // Check time budget — yield if exceeded
+                        if (performance.now() - chunkStart >= budgetMs) {
+                            setTimeout(processChunk, 0);
+                            return;
+                        }
                     }
-                    const color = bucket.meshData[0].color;
-                    const batchedMesh = scene.createBatchedMesh(bucket.meshData, color, device, pipeline, key);
-                    bucket.batchedMesh = batchedMesh;
-                    newBatches.push(batchedMesh);
-                    // Check time budget — yield if exceeded
-                    if (performance.now() - chunkStart >= budgetMs) {
-                        setTimeout(processChunk, 0);
-                        return;
+                    // Carried cold shells stay drawable-when-restored: keep them in the
+                    // flat array (their buffers are already destroyed; the draw loop
+                    // skips gpuResident === false and the restore path revives them).
+                    for (const [, bucket] of carriedCold) {
+                        if (bucket.batchedMesh)
+                            newBatches.push(bucket.batchedMesh);
                     }
+                    // All batches built — atomic swap so renderer never sees an empty array
+                    scene.batchedMeshes = newBatches;
+                    // Cached partial (filtered-visibility) batches are keyed by their
+                    // SOURCE batch, so they only go stale once the replacement batches
+                    // are live — dropping them any earlier destroys GPU resources a
+                    // mid-rebuild failure could never get back (same rationale as
+                    // finalizeStreamingInner).
+                    scene.dropAllPartialCaches();
+                    // Destroy old fragment/batch GPU resources
+                    for (const fragment of oldFragments)
+                        destroyGpuResources(fragment);
+                    for (const batch of oldBatches) {
+                        if (!fragmentSet.has(batch))
+                            destroyGpuResources(batch);
+                    }
+                    scene.finalizeInProgress = false;
+                    resolve();
                 }
-                // Carried cold shells stay drawable-when-restored: keep them in the
-                // flat array (their buffers are already destroyed; the draw loop
-                // skips gpuResident === false and the restore path revives them).
-                for (const [, bucket] of carriedCold) {
-                    if (bucket.batchedMesh)
-                        newBatches.push(bucket.batchedMesh);
+                catch (err) {
+                    rollback();
+                    reject(err);
                 }
-                // All batches built — atomic swap so renderer never sees an empty array
-                scene.batchedMeshes = newBatches;
-                // Destroy old fragment/batch GPU resources
-                for (const fragment of oldFragments)
-                    destroyGpuResources(fragment);
-                for (const batch of oldBatches) {
-                    if (!fragmentSet.has(batch))
-                        destroyGpuResources(batch);
+            }
+            try {
+                // --- Synchronous preamble (fast O(N) bookkeeping) ---
+                scene.streamingFragments = [];
+                // 1. Collect ALL accumulated meshData (cold buckets carried as sealed
+                //    shells — see the sync finalize for the rationale)
+                const allMeshData = [];
+                for (const [key, bucket] of scene.buckets) {
+                    if (scene.coldBuckets.has(key) && bucket.meshData.length === 0 && bucket.batchedMesh) {
+                        carriedCold.push([key, bucket]);
+                        continue;
+                    }
+                    for (const md of bucket.meshData)
+                        allMeshData.push(md);
                 }
-                scene.finalizeInProgress = false;
-                resolve();
+                // 2. Clear bucket/batch state. dropAllPartialCaches() is deliberately
+                //    NOT called here — see the success path above.
+                scene.buckets.clear();
+                scene.meshDataBucket = new Map();
+                scene.activeBucketKey.clear();
+                scene.lastDrawnFrame.clear();
+                scene.residencyRestoreQueue.clear();
+                scene.pendingBatchKeys.clear();
+                // Re-seat the carried cold shells in the fresh bucket map.
+                for (const [key, bucket] of carriedCold)
+                    scene.buckets.set(key, bucket);
+                // 3. Re-group meshData by current color (and grid cell) — fast
+                for (const meshData of allMeshData) {
+                    const baseKey = scene.bucketBaseKey(meshData);
+                    const bucketKey = scene.resolveActiveBucket(baseKey, meshData);
+                    let bucket = scene.buckets.get(bucketKey);
+                    if (!bucket) {
+                        bucket = { key: bucketKey, meshData: [], batchedMesh: null, vertexBytes: 0 };
+                        scene.buckets.set(bucketKey, bucket);
+                    }
+                    bucket.meshData.push(meshData);
+                    scene.meshDataBucket.set(meshData, bucket);
+                    scene.pendingBatchKeys.add(bucketKey);
+                }
+                // Build new batches into a temporary array so the old batchedMeshes
+                // (streaming fragments) keep rendering until the swap is complete.
+                pendingKeys = Array.from(scene.pendingBatchKeys);
+                scene.pendingBatchKeys.clear();
+            }
+            catch (err) {
+                rollback();
+                reject(err);
+                return;
             }
+            // --- Async: rebuild batches in time-sliced chunks ---
             // Start first chunk immediately (no setTimeout delay)
             processChunk();
         });
@@ -2636,7 +2711,8 @@ export class Scene {
             partialBatches: this.partialBatchCache.values(),
             meshes: this.meshes,
             textured: this.texturedMeshes,
-            instanced: this.instancedTemplates,
+            // Live templates only — freed slots are holes with destroyed buffers.
+            instanced: this.liveInstancedTemplates,
         });
     }
     /**
@@ -2653,7 +2729,148 @@ export class Scene {
     getInstancedTemplates() {
         if (!this.instancedVisible)
             return EMPTY_INSTANCED_TEMPLATES;
-        return this.instancedTemplates;
+        return this.liveInstancedTemplates;
+    }
+    /** Rebuild the compacted live-template view after a slot add/remove. */
+    refreshLiveInstancedTemplates() {
+        const live = [];
+        for (const t of this.instancedTemplates) {
+            if (t)
+                live.push(t);
+        }
+        this.liveInstancedTemplates = live;
+    }
+    /** Model indices that currently own at least one instanced template. Unlike
+     *  `getInstancedTemplates()` this ignores the Types-view visibility toggle —
+     *  hiding the pass does not change who owns what. */
+    getInstancedModelIndices() {
+        const seen = new Set();
+        for (const t of this.instancedTemplates) {
+            if (t)
+                seen.add(t.modelIndex);
+        }
+        return [...seen];
+    }
+    /**
+     * Free every instanced template owned by `modelIndex`: destroy exactly its
+     * own vertex/index/instance buffers, blank its slots (leaving holes, so no
+     * other model's `templateIndex` shifts), prune its occurrences from
+     * `instancedEntityMap`, and drop the per-id selection/hidden/override
+     * bookkeeping for ids that lost their LAST occurrence. Express ids shared
+     * with another model — the federated case before id offsetting — keep the
+     * surviving model's occurrences.
+     *
+     * `boundingBoxes` bookkeeping (#2073): an id that ALSO owns flat geometry is
+     * a mixed id — `removeMeshesForEntity` owns that cache, so it is left alone
+     * here even when the id's last instanced occurrence is pruned. An
+     * instanced-only id that loses its last occurrence has nothing left to keep
+     * a cached box for, so its entry is dropped — otherwise bbox-raycast and
+     * `getBounds()` (post geometry-release) keep finding/sizing an element that
+     * no longer has geometry. An id that keeps SOME occurrences (the shared,
+     * federated case) has its box recomputed from just the survivors, not left
+     * as the stale union that also covered the freed model's occurrences.
+     *
+     * Returns the number of templates removed (0 for an unknown model, which is a
+     * no-op).
+     */
+    removeInstancedTemplatesForModel(modelIndex) {
+        const freed = new Set();
+        for (let i = 0; i < this.instancedTemplates.length; i++) {
+            const t = this.instancedTemplates[i];
+            if (!t || t.modelIndex !== modelIndex)
+                continue;
+            t.vertexBuffer.destroy();
+            t.indexBuffer.destroy();
+            t.instanceBuffer.destroy();
+            this.instancedTemplates[i] = undefined;
+            this.instancedTemplateCpu[i] = undefined;
+            freed.add(i);
+        }
+        if (freed.size === 0)
+            return 0;
+        for (const [eid, occurrences] of this.instancedEntityMap) {
+            const kept = occurrences.filter((o) => !freed.has(o.templateIndex));
+            if (kept.length === occurrences.length)
+                continue;
+            if (kept.length > 0) {
+                this.instancedEntityMap.set(eid, kept);
+                // Shared id: some occurrences survive in another model. The cached box
+                // is a union that also covered the freed occurrences — recompute it
+                // from exactly the survivors rather than leave it oversized.
+                this.recomputeInstancedWorldAabb(eid, kept);
+                continue;
+            }
+            // Last occurrence gone: the id is no longer instanced at all.
+            this.instancedEntityMap.delete(eid);
+            this.instancedSelected.delete(eid);
+            this.instancedHidden.delete(eid);
+            this.instancedOverridden.delete(eid);
+            // Only drop the cached box when the id has no flat geometry either — a
+            // mixed id's box is owned by the flat-removal path (removeMeshesForEntity),
+            // which clears it on its own schedule.
+            if (!this.meshDataMap.has(eid)) {
+                this.boundingBoxes.delete(eid);
+            }
+        }
+        this.refreshLiveInstancedTemplates();
+        // Occurrence population changed → force the next visibility pass to
+        // recompute rather than early-return on an unchanged id set.
+        this.lastInstancedVisibilityVersion = -1;
+        this.instancedVisibilityDirty = true;
+        return freed.size;
+    }
+    /**
+     * Recompute `boundingBoxes[eid]` from exactly `occurrences` (REPLACING any
+     * existing entry rather than unioning into it), reading each occurrence's
+     * template-local AABB + packed instance matrix the same way
+     * `unionInstancedWorldAabb` does at upload time. Used when a model-level
+     * template removal (`removeInstancedTemplatesForModel`) prunes some but not
+     * all of a shared id's occurrences — a plain union only ever grows, so it
+     * cannot shrink to reflect occurrences that no longer exist. Deletes the
+     * entry outright if no surviving occurrence has a finite local box (#2073).
+     */
+    recomputeInstancedWorldAabb(eid, occurrences) {
+        let minX = Infinity, minY = Infinity, minZ = Infinity;
+        let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+        let any = false;
+        for (const occ of occurrences) {
+            const cpu = this.instancedTemplateCpu[occ.templateIndex];
+            if (!cpu || !Number.isFinite(cpu.localMin[0]))
+                continue;
+            const dv = new DataView(cpu.instanceData);
+            const [lmnx, lmny, lmnz] = cpu.localMin;
+            const [lmxx, lmxy, lmxz] = cpu.localMax;
+            const b = occ.byteOffset;
+            const m0 = dv.getFloat32(b + 0, true), m1 = dv.getFloat32(b + 4, true), m2 = dv.getFloat32(b + 8, true);
+            const m4 = dv.getFloat32(b + 16, true), m5 = dv.getFloat32(b + 20, true), m6 = dv.getFloat32(b + 24, true);
+            const m8 = dv.getFloat32(b + 32, true), m9 = dv.getFloat32(b + 36, true), m10 = dv.getFloat32(b + 40, true);
+            const m12 = dv.getFloat32(b + 48, true), m13 = dv.getFloat32(b + 52, true), m14 = dv.getFloat32(b + 56, true);
+            for (let c = 0; c < 8; c++) {
+                const x = (c & 1) ? lmxx : lmnx, y = (c & 2) ? lmxy : lmny, z = (c & 4) ? lmxz : lmnz;
+                const wx = m0 * x + m4 * y + m8 * z + m12;
+                const wy = m1 * x + m5 * y + m9 * z + m13;
+                const wz = m2 * x + m6 * y + m10 * z + m14;
+                if (wx < minX)
+                    minX = wx;
+                if (wy < minY)
+                    minY = wy;
+                if (wz < minZ)
+                    minZ = wz;
+                if (wx > maxX)
+                    maxX = wx;
+                if (wy > maxY)
+                    maxY = wy;
+                if (wz > maxZ)
+                    maxZ = wz;
+            }
+            any = true;
+        }
+        if (any) {
+            this.boundingBoxes.set(eid, { min: { x: minX, y: minY, z: minZ }, max: { x: maxX, y: maxY, z: maxZ } });
+        }
+        else {
+            this.boundingBoxes.delete(eid);
+        }
     }
     /**
      * Decode a per-batch IFNS instancing shard (`processGeometryBatchInstanced`)
@@ -2671,7 +2888,7 @@ export class Scene {
      * type-only dependency on @ifc-lite/geometry and the Scene stays focused on
      * GPU upload.
      */
-    addInstancedShard(device, shard) {
+    addInstancedShard(device, shard, modelIndex = 0) {
         this.instancedDevice = device; // cached for per-instance selection/overlay writeBuffer
         const prepared = prepareInstancedRender(shard);
         // Selected ids whose occurrences arrived in THIS shard (selection recorded
@@ -2721,8 +2938,10 @@ export class Scene {
             });
             new Uint8Array(instanceBuffer.getMappedRange()).set(new Uint8Array(t.instanceBuffer, 0, instSize));
             instanceBuffer.unmap();
+            // Always append: slots are stable identities, never recycled.
             const templateIndex = this.instancedTemplates.length;
             const template = {
+                modelIndex,
                 vertexBuffer,
                 indexBuffer,
                 indexCount: t.indices.length,
@@ -2732,7 +2951,7 @@ export class Scene {
                 maxOccRadius: 0,
                 selectedCount: 0,
             };
-            this.instancedTemplates.push(template);
+            this.instancedTemplates[templateIndex] = template;
             // Template-local AABB (used to derive per-occurrence world AABBs cheaply).
             let lmnx = Infinity, lmny = Infinity, lmnz = Infinity;
             let lmxx = -Infinity, lmxy = -Infinity, lmxz = -Infinity;
@@ -2754,14 +2973,16 @@ export class Scene {
             // Retain the compact CPU geometry + the packed instance records (mat4 per
             // occurrence) so CPU consumers can reach instanced geometry without a full
             // per-occurrence MeshData each. These are references into the decoded shard.
-            this.instancedTemplateCpu.push({
+            // Slot-assigned, not pushed: the CPU array is emptied on geometry release
+            // while the GPU slots live on, so `push` would silently misalign the two.
+            this.instancedTemplateCpu[templateIndex] = {
                 positions: t.positions,
                 normals: t.normals,
                 indices: t.indices,
                 instanceData: t.instanceBuffer,
                 localMin: [lmnx, lmny, lmnz],
                 localMax: [lmxx, lmxy, lmxz],
-            });
+            };
             // Map each occurrence's express_id -> (template, byte offset, original
             // colour) so selection (flag byte) + lens/IDS overlays (colour bytes) can
             // patch individual occurrences via writeBuffer without a re-upload. Also fold
@@ -2805,6 +3026,7 @@ export class Scene {
                 }
             }
         }
+        this.refreshLiveInstancedTemplates();
         // Write the selected flag for ids whose occurrences arrived after the
         // selection was recorded (idempotent for their pre-existing occurrences),
         // so the highlight shows on late-streamed geometry too.
@@ -3287,7 +3509,60 @@ export class Scene {
             this.sharedTextures.delete(tm.sharedTextureKey);
         }
     }
+    /**
+     * Destroy every GPU-instanced template's buffers and reset all instanced
+     * bookkeeping, regardless of owning model. Shared by `clear()` (full reset)
+     * — `clearFlatGeometry()` deliberately does NOT call this, so a reshape
+     * that still has models present can retain their instanced geometry
+     * (#2073).
+     */
+    destroyAllInstancedTemplates() {
+        for (const it of this.instancedTemplates) {
+            if (!it)
+                continue;
+            it.vertexBuffer.destroy();
+            it.indexBuffer.destroy();
+            it.instanceBuffer.destroy();
+        }
+        this.instancedTemplates = [];
+        this.liveInstancedTemplates = [];
+        this.instancedTemplateCpu = [];
+        this.instancedEntityMap.clear();
+        this.instancedSelected.clear();
+        this.instancedHidden.clear();
+        this.instancedOverridden.clear();
+        this.instancedHasTransparent = false;
+        // Force the next setInstancedVisibility to recompute against fresh state.
+        this.lastInstancedVisibilityVersion = -1;
+        this.instancedVisibilityDirty = false;
+        this.instancedDevice = undefined;
+    }
     clear() {
+        // GPU-instancing templates own their vertex/index/instance buffers.
+        // (Freed slots are holes whose buffers are already destroyed — skip them so
+        // a per-model removal followed by clear() can't double-destroy.)
+        this.destroyAllInstancedTemplates();
+        this.clearFlatGeometry();
+    }
+    /**
+     * Clear flat/batched geometry (meshes, batches, buckets, textured meshes,
+     * colour overlays, streaming state, residency bookkeeping) WITHOUT
+     * touching GPU-instanced templates (#2073). A reshape that still has at
+     * least one model present should call this instead of `clear()`, then
+     * reconcile instanced ownership with `removeInstancedTemplatesForModel`
+     * for any model that did NOT survive — that way a still-loaded model's
+     * repeated geometry (windows, doors, bolts, ...) stays resident across a
+     * visibility toggle / in-place content mutation / federated model add
+     * instead of silently vanishing (nothing re-uploads instanced shard bytes
+     * after their one-time drain).
+     *
+     * Bounding boxes are only dropped for ids with NO surviving instanced
+     * occurrence — an instanced-only id's box must outlive this call so
+     * raycast / measure / section keep working for the geometry that was
+     * just retained; a flat-only id's box is stale the moment its mesh data
+     * is gone, so it is dropped like everything else here.
+     */
+    clearFlatGeometry() {
         for (const mesh of this.meshes)
             destroyGpuResources(mesh);
         for (const batch of this.batchedMeshes)
@@ -3304,23 +3579,6 @@ export class Scene {
         for (const entry of this.sharedTextures.values())
             entry.texture.destroy();
         this.sharedTextures.clear();
-        // GPU-instancing templates own their vertex/index/instance buffers.
-        for (const it of this.instancedTemplates) {
-            it.vertexBuffer.destroy();
-            it.indexBuffer.destroy();
-            it.instanceBuffer.destroy();
-        }
-        this.instancedTemplates = [];
-        this.instancedTemplateCpu = [];
-        this.instancedEntityMap.clear();
-        this.instancedSelected.clear();
-        this.instancedHidden.clear();
-        this.instancedOverridden.clear();
-        this.instancedHasTransparent = false;
-        // Force the next setInstancedVisibility to recompute against fresh state.
-        this.lastInstancedVisibilityVersion = -1;
-        this.instancedVisibilityDirty = false;
-        this.instancedDevice = undefined;
         // Clear partial batch cache (destroys buffers + drops all cache maps)
         this.dropAllPartialCaches();
         this.colorOverrideGeneration++;
@@ -3328,14 +3586,21 @@ export class Scene {
         this.streamingFragments = [];
         this.destroyOverrideBatches();
         this.colorOverrides = null;
-        // Reset the shared frame origin so the next model picks its own.
+        // Reset the shared frame origin so the next model picks its own. Retained
+        // instanced templates are unaffected — their per-occurrence transforms are
+        // already baked to absolute world coordinates at upload time, not relative
+        // to this origin.
         this.sharedFrameOrigin = null;
         this.meshes = [];
         this.batchedMeshes = [];
         this.buckets.clear();
         this.meshDataBucket = new Map();
         this.meshDataMap.clear();
-        this.boundingBoxes.clear();
+        for (const eid of [...this.boundingBoxes.keys()]) {
+            if (!this.instancedEntityMap.has(eid)) {
+                this.boundingBoxes.delete(eid);
+            }
+        }
         this.activeBucketKey.clear();
         this.lastDrawnFrame.clear();
         this.residencyRestoreQueue.clear();