@ifc-lite/renderer 1.14.3 → 1.14.6

package/dist/scene.js

@@ -8,19 +8,16 @@ let warnedEntityIdRange = false;
 export class Scene {
     meshes = [];
     instancedMeshes = [];
-    batchedMeshes = [];
-    batchedMeshMap = new Map(); // Map bucketKey -> BatchedMesh
-    batchedMeshData = new Map(); // Map bucketKey -> accumulated MeshData[]
-    batchedMeshIndex = new Map(); // Map bucketKey -> index in batchedMeshes array (O(1) lookup)
+    batchedMeshes = []; // flat render array (rebuilt from buckets)
+    buckets = new Map(); // bucketKey -> consolidated bucket state
+    meshDataBucket = new Map(); // reverse lookup: MeshData -> owning bucket
     meshDataMap = new Map(); // Map expressId -> MeshData[] (for lazy buffer creation, accumulates multiple pieces)
-    meshDataBatchKey = new Map(); // Reverse lookup: MeshData -> bucketKey (O(1) removal in updateMeshColors)
     boundingBoxes = new Map(); // Map expressId -> bounding box (computed lazily)
     // Buffer-size-aware bucket splitting: when a single color group's geometry
     // would exceed the GPU maxBufferSize, overflow is directed to a new
     // sub-bucket with a suffixed key (e.g. "500|500|500|1000#1"). This keeps
     // all downstream maps single-valued and the rendering code unchanged.
     activeBucketKey = new Map(); // base colorKey -> current active bucket key
-    bucketVertexBytes = new Map(); // bucket key -> accumulated vertex buffer bytes
     nextSplitId = 0; // Monotonic counter for sub-bucket keys
     cachedMaxBufferSize = 0; // device.limits.maxBufferSize * safety factor (set on first use)
     // Sub-batch cache for partially visible batches (PERFORMANCE FIX)
@@ -38,6 +35,16 @@ export class Scene {
     // Temporary fragment batches created during streaming for immediate rendering.
     // Destroyed and replaced by proper merged batches in finalizeStreaming().
     streamingFragments = [];
+    // ─── Mesh command queue ────────────────────────────────────────────
+    // Decouples React state updates from GPU work.  Callers push meshes
+    // via queueMeshes() (instant, no GPU), and the animation loop drains
+    // the queue via flushPending() with a per-frame time budget.
+    meshQueue = [];
+    // ─── GPU-resident mode ──────────────────────────────────────────────
+    // After releaseGeometryData(), JS-side typed arrays are freed.
+    // Only lightweight metadata is retained for operations that don't need
+    // raw vertex data (bounding boxes, color key lookups, expressId sets).
+    geometryReleased = false;
     /**
      * Add mesh to scene
      */
@@ -216,14 +223,14 @@ export class Scene {
             const baseKey = this.colorKey(meshData.color);
             const bucketKey = this.resolveActiveBucket(baseKey, meshData);
             // Accumulate mesh data in the bucket (always — needed for final merge)
-            let bucket = this.batchedMeshData.get(bucketKey);
+            let bucket = this.buckets.get(bucketKey);
             if (!bucket) {
-                bucket = [];
-                this.batchedMeshData.set(bucketKey, bucket);
+                bucket = { key: bucketKey, meshData: [], batchedMesh: null, vertexBytes: 0 };
+                this.buckets.set(bucketKey, bucket);
             }
-            bucket.push(meshData);
-            // Track reverse mapping for O(1) batch removal in updateMeshColors
-            this.meshDataBatchKey.set(meshData, bucketKey);
+            bucket.meshData.push(meshData);
+            // Track reverse mapping for O(1) bucket lookup in updateMeshColors
+            this.meshDataBucket.set(meshData, bucket);
             // Also store individual mesh data for visibility filtering
             this.addMeshData(meshData);
             // Track pending keys for non-streaming rebuild only
@@ -252,48 +259,31 @@ export class Scene {
         if (this.pendingBatchKeys.size === 0)
             return;
         for (const key of this.pendingBatchKeys) {
-            const meshDataForKey = this.batchedMeshData.get(key);
-            const existingBatch = this.batchedMeshMap.get(key);
-            if (existingBatch) {
-                // Destroy old batch buffers
-                existingBatch.vertexBuffer.destroy();
-                existingBatch.indexBuffer.destroy();
-                if (existingBatch.uniformBuffer) {
-                    existingBatch.uniformBuffer.destroy();
+            const bucket = this.buckets.get(key);
+            // Destroy old GPU batch if it exists
+            if (bucket?.batchedMesh) {
+                bucket.batchedMesh.vertexBuffer.destroy();
+                bucket.batchedMesh.indexBuffer.destroy();
+                if (bucket.batchedMesh.uniformBuffer) {
+                    bucket.batchedMesh.uniformBuffer.destroy();
                 }
+                bucket.batchedMesh = null;
             }
-            if (!meshDataForKey || meshDataForKey.length === 0) {
+            if (!bucket || bucket.meshData.length === 0) {
                 // Bucket is empty — clean up
-                this.batchedMeshMap.delete(key);
-                this.batchedMeshData.delete(key);
-                this.bucketVertexBytes.delete(key);
-                // Swap-remove from flat array using O(1) index lookup
-                const arrayIdx = this.batchedMeshIndex.get(key);
-                if (arrayIdx !== undefined) {
-                    const lastIdx = this.batchedMeshes.length - 1;
-                    if (arrayIdx !== lastIdx) {
-                        const lastBatch = this.batchedMeshes[lastIdx];
-                        this.batchedMeshes[arrayIdx] = lastBatch;
-                        this.batchedMeshIndex.set(lastBatch.colorKey, arrayIdx);
-                    }
-                    this.batchedMeshes.pop();
-                    this.batchedMeshIndex.delete(key);
-                }
+                this.buckets.delete(key);
                 continue;
             }
             // Create new batch with all accumulated meshes for this bucket
-            const color = meshDataForKey[0].color;
-            const batchedMesh = this.createBatchedMesh(meshDataForKey, color, device, pipeline, key);
-            this.batchedMeshMap.set(key, batchedMesh);
-            // Update array using O(1) index lookup instead of O(N) findIndex
-            const existingIndex = this.batchedMeshIndex.get(key);
-            if (existingIndex !== undefined) {
-                this.batchedMeshes[existingIndex] = batchedMesh;
-            }
-            else {
-                const newIndex = this.batchedMeshes.length;
-                this.batchedMeshes.push(batchedMesh);
-                this.batchedMeshIndex.set(key, newIndex);
+            const color = bucket.meshData[0].color;
+            const batchedMesh = this.createBatchedMesh(bucket.meshData, color, device, pipeline, key);
+            bucket.batchedMesh = batchedMesh;
+        }
+        // Rebuild the flat render array from all buckets (148 max batches — not perf critical)
+        this.batchedMeshes = [];
+        for (const bucket of this.buckets.values()) {
+            if (bucket.batchedMesh) {
+                this.batchedMeshes.push(bucket.batchedMesh);
             }
         }
         this.pendingBatchKeys.clear();
@@ -304,6 +294,39 @@ export class Scene {
     hasPendingBatches() {
         return this.pendingBatchKeys.size > 0;
     }
+    // ─── Mesh command queue ──────────────────────────────────────────────
+    /**
+     * Queue meshes for deferred GPU upload.
+     * Instant (no GPU work) — safe to call from React effects.
+     * The animation loop calls flushPending() each frame to drain the queue.
+     */
+    queueMeshes(meshes) {
+        for (let i = 0; i < meshes.length; i++) {
+            this.meshQueue.push(meshes[i]);
+        }
+    }
+    /** True if the mesh queue has pending work. */
+    hasQueuedMeshes() {
+        return this.meshQueue.length > 0;
+    }
+    /**
+     * Drain the mesh queue with a per-frame time budget.
+     * Processes queued meshes through appendToBatches in streaming mode
+     * (creates lightweight fragment batches for immediate rendering).
+     *
+     * @returns true if any meshes were processed (caller should render)
+     */
+    flushPending(device, pipeline) {
+        if (this.meshQueue.length === 0)
+            return false;
+        // Drain the entire queue in one appendToBatches call.
+        // The queue coalesces multiple React batches into a single GPU upload,
+        // which is already bounded by the WASM→JS batch interval (~50-200ms).
+        const meshes = this.meshQueue;
+        this.meshQueue = [];
+        this.appendToBatches(meshes, device, pipeline, true);
+        return true;
+    }
     /**
      * Create lightweight fragment batches from a single streaming batch.
      * Fragments are grouped by color and added to batchedMeshes for immediate
@@ -348,18 +371,63 @@ export class Scene {
     finalizeStreaming(device, pipeline) {
         if (this.streamingFragments.length === 0)
             return;
-        // 1. Destroy all fragment GPU resources
-        const fragmentSet = new Set(this.streamingFragments);
-        for (const fragment of this.streamingFragments) {
+        // Save references to old fragments/batches — keep them rendering
+        // until the new proper batches are fully built (no visual gap).
+        const oldFragments = this.streamingFragments;
+        const oldBatches = this.batchedMeshes;
+        const fragmentSet = new Set(oldFragments);
+        this.streamingFragments = [];
+        // 1. Collect ALL accumulated meshData before clearing state
+        const allMeshData = [];
+        for (const bucket of this.buckets.values()) {
+            for (const md of bucket.meshData)
+                allMeshData.push(md);
+        }
+        // 2. Clear all bucket/batch state for a clean rebuild
+        // NOTE: batchedMeshes keeps the OLD array reference — the renderer
+        // continues to draw from it until we swap in the new array below.
+        this.buckets.clear();
+        this.meshDataBucket = new Map();
+        this.activeBucketKey.clear();
+        this.pendingBatchKeys.clear();
+        // Destroy cached partial batches — their colorKeys are now stale
+        for (const batch of this.partialBatchCache.values()) {
+            batch.vertexBuffer.destroy();
+            batch.indexBuffer.destroy();
+            if (batch.uniformBuffer) {
+                batch.uniformBuffer.destroy();
+            }
+        }
+        this.partialBatchCache.clear();
+        this.partialBatchCacheKeys.clear();
+        // 3. Re-group ALL meshData by their CURRENT color.
+        //    meshData.color may have been mutated in-place since the mesh was
+        //    first bucketed, so the original bucket key is stale. Re-grouping
+        //    by current color ensures batches render with correct colors.
+        for (const meshData of allMeshData) {
+            const baseKey = this.colorKey(meshData.color);
+            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);
+        }
+        // 4. Build new proper batches into a fresh array
+        this.batchedMeshes = [];
+        this.rebuildPendingBatches(device, pipeline);
+        // 5. NOW destroy old fragment/batch GPU resources (new batches are live)
+        for (const fragment of oldFragments) {
             fragment.vertexBuffer.destroy();
             fragment.indexBuffer.destroy();
             if (fragment.uniformBuffer) {
                 fragment.uniformBuffer.destroy();
             }
         }
-        this.streamingFragments = [];
-        // 2. Destroy any pre-existing proper batches (non-fragments)
-        for (const batch of this.batchedMeshes) {
+        for (const batch of oldBatches) {
             if (!fragmentSet.has(batch)) {
                 batch.vertexBuffer.destroy();
                 batch.indexBuffer.destroy();
@@ -368,60 +436,207 @@ export class Scene {
                 }
             }
         }
-        // 3. Collect ALL accumulated meshData before clearing state
+    }
+    /**
+     * Time-sliced version of finalizeStreaming.
+     * Re-groups mesh data and rebuilds GPU batches in small chunks,
+     * yielding to the event loop between chunks so orbit/pan stays responsive.
+     * Streaming fragments continue rendering until each new batch replaces them.
+     *
+     * @param device  GPU device
+     * @param pipeline  Render pipeline
+     * @param budgetMs  Max milliseconds per chunk (default 8 — half a 60fps frame)
+     * @returns Promise that resolves when all batches are rebuilt
+     */
+    finalizeStreamingAsync(device, pipeline, budgetMs = 8) {
+        if (this.streamingFragments.length === 0)
+            return Promise.resolve();
+        // --- Synchronous preamble (fast O(N) bookkeeping) ---
+        const oldFragments = this.streamingFragments;
+        const oldBatches = this.batchedMeshes;
+        const fragmentSet = new Set(oldFragments);
+        this.streamingFragments = [];
+        // 1. Collect ALL accumulated meshData
         const allMeshData = [];
-        for (const data of this.batchedMeshData.values()) {
-            for (const md of data)
+        for (const bucket of this.buckets.values()) {
+            for (const md of bucket.meshData)
                 allMeshData.push(md);
         }
-        // 4. Clear all bucket/batch state for a clean rebuild
-        this.batchedMeshes = [];
-        this.batchedMeshMap.clear();
-        this.batchedMeshIndex.clear();
-        this.batchedMeshData.clear();
-        this.meshDataBatchKey.clear();
+        // 2. Clear bucket/batch state
+        this.buckets.clear();
+        this.meshDataBucket = new Map();
         this.activeBucketKey.clear();
-        this.bucketVertexBytes.clear();
         this.pendingBatchKeys.clear();
-        // Destroy cached partial batches — their colorKeys are now stale
         for (const batch of this.partialBatchCache.values()) {
             batch.vertexBuffer.destroy();
             batch.indexBuffer.destroy();
-            if (batch.uniformBuffer) {
+            if (batch.uniformBuffer)
                 batch.uniformBuffer.destroy();
-            }
         }
         this.partialBatchCache.clear();
         this.partialBatchCacheKeys.clear();
-        // 5. Re-group ALL meshData by their CURRENT color.
-        //    meshData.color may have been mutated in-place since the mesh was
-        //    first bucketed, so the original bucket key is stale. Re-grouping
-        //    by current color ensures batches render with correct colors.
+        // 3. Re-group meshData by current color (fast)
         for (const meshData of allMeshData) {
             const baseKey = this.colorKey(meshData.color);
             const bucketKey = this.resolveActiveBucket(baseKey, meshData);
-            let bucket = this.batchedMeshData.get(bucketKey);
+            let bucket = this.buckets.get(bucketKey);
             if (!bucket) {
-                bucket = [];
-                this.batchedMeshData.set(bucketKey, bucket);
+                bucket = { key: bucketKey, meshData: [], batchedMesh: null, vertexBytes: 0 };
+                this.buckets.set(bucketKey, bucket);
             }
-            bucket.push(meshData);
-            this.meshDataBatchKey.set(meshData, bucketKey);
+            bucket.meshData.push(meshData);
+            this.meshDataBucket.set(meshData, bucket);
             this.pendingBatchKeys.add(bucketKey);
         }
-        // 6. One O(N) full rebuild from correctly-grouped data
-        this.rebuildPendingBatches(device, pipeline);
+        // 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;
+                    }
+                    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;
+                    }
+                }
+                // 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) {
+                    fragment.vertexBuffer.destroy();
+                    fragment.indexBuffer.destroy();
+                    if (fragment.uniformBuffer)
+                        fragment.uniformBuffer.destroy();
+                }
+                for (const batch of oldBatches) {
+                    if (!fragmentSet.has(batch)) {
+                        batch.vertexBuffer.destroy();
+                        batch.indexBuffer.destroy();
+                        if (batch.uniformBuffer)
+                            batch.uniformBuffer.destroy();
+                    }
+                }
+                resolve();
+            }
+            // Start first chunk immediately (no setTimeout delay)
+            processChunk();
+        });
+    }
+    /**
+     * Release JS-side mesh geometry data (positions, normals, indices) after
+     * GPU batches have been built. This frees the ~1.9GB of typed arrays that
+     * duplicate data already resident in GPU vertex/index buffers.
+     *
+     * After calling this method:
+     *  - Bounding boxes are precomputed and cached for all entities
+     *  - meshDataMap and bucket meshData arrays are cleared (typed arrays become GC-eligible)
+     *  - Color updates (updateMeshColors) are no longer available
+     *  - Partial batch creation and color overlays are no longer available
+     *  - CPU raycasting falls back to bounding-box-only (no triangle intersection)
+     *  - Selection highlighting must use GPU picking instead of CPU mesh reconstruction
+     *
+     * Call this after finalizeStreaming() when all color updates have been applied.
+     */
+    releaseGeometryData() {
+        if (this.geometryReleased)
+            return;
+        // Guard: releasing while async batch work is in-flight would corrupt GPU state
+        if (this.pendingBatchKeys.size > 0 || this.streamingFragments.length > 0) {
+            console.warn(`[Scene] releaseGeometryData() called with ${this.pendingBatchKeys.size} pending batches ` +
+                `and ${this.streamingFragments.length} streaming fragments still in-flight. ` +
+                `Call finalizeStreaming()/rebuildPendingBatches() first.`);
+            return;
+        }
+        // 1. Precompute and cache ALL entity bounding boxes before releasing data
+        for (const [expressId, pieces] of this.meshDataMap) {
+            if (this.boundingBoxes.has(expressId))
+                continue;
+            let minX = Infinity, minY = Infinity, minZ = Infinity;
+            let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+            for (const piece of pieces) {
+                const positions = piece.positions;
+                for (let i = 0; i < positions.length; i += 3) {
+                    const x = positions[i];
+                    const y = positions[i + 1];
+                    const z = positions[i + 2];
+                    if (x < minX)
+                        minX = x;
+                    if (y < minY)
+                        minY = y;
+                    if (z < minZ)
+                        minZ = z;
+                    if (x > maxX)
+                        maxX = x;
+                    if (y > maxY)
+                        maxY = y;
+                    if (z > maxZ)
+                        maxZ = z;
+                }
+            }
+            this.boundingBoxes.set(expressId, {
+                min: { x: minX, y: minY, z: minZ },
+                max: { x: maxX, y: maxY, z: maxZ },
+            });
+        }
+        // 2. Clear the heavy data structures — typed arrays become GC-eligible
+        this.meshDataMap.clear();
+        // Clear meshData arrays in each bucket (typed arrays become GC-eligible)
+        // but keep the bucket shells so batchedMesh references remain valid
+        for (const bucket of this.buckets.values()) {
+            bucket.meshData = [];
+        }
+        this.meshDataBucket = new Map();
+        this.activeBucketKey.clear();
+        // 3. Clear partial batch cache (would need mesh data to rebuild)
+        for (const batch of this.partialBatchCache.values()) {
+            batch.vertexBuffer.destroy();
+            batch.indexBuffer.destroy();
+            if (batch.uniformBuffer)
+                batch.uniformBuffer.destroy();
+        }
+        this.partialBatchCache.clear();
+        this.partialBatchCacheKeys.clear();
+        this.geometryReleased = true;
+        console.log(`[Scene] Released JS geometry data. ${this.boundingBoxes.size} bounding boxes cached. ` +
+            `${this.batchedMeshes.length} GPU batches retained.`);
+    }
+    /**
+     * Whether JS geometry data has been released (GPU-resident mode).
+     */
+    isGeometryDataReleased() {
+        return this.geometryReleased;
     }
     /**
      * Update colors for existing meshes and rebuild affected batches
      * Call this when deferred color parsing completes
      *
-     * OPTIMIZATION: Uses meshDataBatchKey reverse-map for O(1) batch removal
+     * OPTIMIZATION: Uses meshDataBucket reverse-map for O(1) batch lookup
      * instead of O(N) indexOf scan per mesh. Critical for bulk IDS validation updates.
      */
     updateMeshColors(updates, device, pipeline) {
         if (updates.size === 0)
             return;
+        if (this.geometryReleased) {
+            console.warn('[Scene] updateMeshColors called after geometry data was released — skipping.');
+            return;
+        }
         // Cache max buffer size if not yet set
         if (this.cachedMaxBufferSize === 0) {
             this.cachedMaxBufferSize = this.getMaxBufferSize(device);
@@ -435,8 +650,9 @@ export class Scene {
                 continue;
             const newBaseKey = this.colorKey(newColor);
             for (const meshData of meshDataList) {
-                // Use reverse-map for O(1) old bucket key lookup
-                const oldBucketKey = this.meshDataBatchKey.get(meshData) ?? this.colorKey(meshData.color);
+                // Use reverse-map for O(1) old bucket lookup
+                const oldBucket = this.meshDataBucket.get(meshData);
+                const oldBucketKey = oldBucket?.key ?? this.colorKey(meshData.color);
                 // Derive old color from bucket key, NOT meshData.color.
                 // meshData.color may have been mutated in-place by external code
                 // (applyColorUpdatesToMeshes), making it unreliable for change detection.
@@ -446,37 +662,37 @@ export class Scene {
                     const newBucketKey = this.resolveActiveBucket(newBaseKey, meshData);
                     affectedOldKeys.add(oldBucketKey);
                     affectedNewKeys.add(newBucketKey);
-                    // Remove from old bucket data using swap-remove for O(1)
-                    const oldBatchData = this.batchedMeshData.get(oldBucketKey);
-                    if (oldBatchData) {
-                        const idx = oldBatchData.indexOf(meshData);
+                    // Remove from old bucket data using indexOf (O(N) within one color bucket, typically <100 items)
+                    if (oldBucket) {
+                        const idx = oldBucket.meshData.indexOf(meshData);
                         if (idx >= 0) {
-                            // Swap with last element and pop — O(1) instead of O(N) splice
-                            const last = oldBatchData.length - 1;
+                            // Swap-remove for O(1)
+                            const last = oldBucket.meshData.length - 1;
                             if (idx !== last) {
-                                oldBatchData[idx] = oldBatchData[last];
+                                oldBucket.meshData[idx] = oldBucket.meshData[last];
                             }
-                            oldBatchData.pop();
+                            oldBucket.meshData.pop();
                         }
-                        if (oldBatchData.length === 0) {
-                            this.batchedMeshData.delete(oldBucketKey);
+                        if (oldBucket.meshData.length === 0) {
+                            this.buckets.delete(oldBucketKey);
                         }
                     }
                     // Decrease old bucket size tracking
                     const meshBytes = (meshData.positions.length / 3) * BATCH_CONSTANTS.BYTES_PER_VERTEX;
-                    const oldSize = this.bucketVertexBytes.get(oldBucketKey) ?? 0;
-                    this.bucketVertexBytes.set(oldBucketKey, Math.max(0, oldSize - meshBytes));
+                    if (oldBucket) {
+                        oldBucket.vertexBytes = Math.max(0, oldBucket.vertexBytes - meshBytes);
+                    }
                     // Update mesh color
                     meshData.color = newColor;
                     // Add to new bucket data (resolveActiveBucket already updated size tracking)
-                    let newBucket = this.batchedMeshData.get(newBucketKey);
+                    let newBucket = this.buckets.get(newBucketKey);
                     if (!newBucket) {
-                        newBucket = [];
-                        this.batchedMeshData.set(newBucketKey, newBucket);
+                        newBucket = { key: newBucketKey, meshData: [], batchedMesh: null, vertexBytes: 0 };
+                        this.buckets.set(newBucketKey, newBucket);
                     }
-                    newBucket.push(meshData);
+                    newBucket.meshData.push(meshData);
                     // Update reverse mapping
-                    this.meshDataBatchKey.set(meshData, newBucketKey);
+                    this.meshDataBucket.set(meshData, newBucket);
                 }
             }
         }
@@ -497,7 +713,7 @@ export class Scene {
      * Create a new batched mesh from mesh data array.
      * @param bucketKey - Optional unique key for this batch. When omitted the
      *   base color key is used (fine for overlay / partial batches that don't
-     *   participate in the main batchedMeshMap).
+     *   participate in the main buckets map).
      */
     createBatchedMesh(meshDataArray, color, device, pipeline, bucketKey) {
         const merged = this.mergeGeometry(meshDataArray);
@@ -685,15 +901,21 @@ export class Scene {
      */
     resolveActiveBucket(baseColorKey, meshData) {
         let bucketKey = this.activeBucketKey.get(baseColorKey) ?? baseColorKey;
-        const currentBytes = this.bucketVertexBytes.get(bucketKey) ?? 0;
+        const bucket = this.buckets.get(bucketKey);
+        const currentBytes = bucket?.vertexBytes ?? 0;
         const meshBytes = (meshData.positions.length / 3) * BATCH_CONSTANTS.BYTES_PER_VERTEX;
         if (currentBytes > 0 && currentBytes + meshBytes > this.cachedMaxBufferSize) {
             // Overflow — create a new sub-bucket
             bucketKey = `${baseColorKey}#${this.nextSplitId++}`;
             this.activeBucketKey.set(baseColorKey, bucketKey);
         }
-        // Update size tracking
-        this.bucketVertexBytes.set(bucketKey, (this.bucketVertexBytes.get(bucketKey) ?? 0) + meshBytes);
+        // Update size tracking on the bucket (create if needed)
+        let targetBucket = this.buckets.get(bucketKey);
+        if (!targetBucket) {
+            targetBucket = { key: bucketKey, meshData: [], batchedMesh: null, vertexBytes: 0 };
+            this.buckets.set(bucketKey, targetBucket);
+        }
+        targetBucket.vertexBytes += meshBytes;
         return bucketKey;
     }
     /**
@@ -717,6 +939,9 @@ export class Scene {
      * @returns BatchedMesh containing only visible elements, or undefined if no visible elements
      */
     getOrCreatePartialBatch(colorKey, visibleIds, device, pipeline) {
+        // Cannot create partial batches after geometry data has been released
+        if (this.geometryReleased)
+            return undefined;
         // Create cache key from colorKey + deterministic hash of all visible IDs
         // Using a proper hash over all IDs to avoid collisions when middle IDs differ
         const sortedIds = Array.from(visibleIds).sort((a, b) => a - b);
@@ -792,6 +1017,11 @@ export class Scene {
     setColorOverrides(overrides, device, pipeline) {
         // Destroy previous overlay batches
         this.destroyOverrideBatches();
+        if (this.geometryReleased) {
+            console.warn('[Scene] setColorOverrides called after geometry data was released — skipping.');
+            this.colorOverrides = null;
+            return;
+        }
         if (overrides.size === 0) {
             this.colorOverrides = null;
             return;
@@ -904,23 +1134,47 @@ export class Scene {
         this.meshes = [];
         this.instancedMeshes = [];
         this.batchedMeshes = [];
-        this.batchedMeshMap.clear();
-        this.batchedMeshData.clear();
-        this.batchedMeshIndex.clear();
+        this.buckets.clear();
+        this.meshDataBucket = new Map();
         this.meshDataMap.clear();
-        this.meshDataBatchKey.clear();
         this.boundingBoxes.clear();
         this.activeBucketKey.clear();
-        this.bucketVertexBytes.clear();
         this.cachedMaxBufferSize = 0;
         this.pendingBatchKeys.clear();
         this.partialBatchCache.clear();
         this.partialBatchCacheKeys.clear();
+        this.meshQueue = [];
+        this.geometryReleased = false;
     }
     /**
      * Calculate bounding box from actual mesh vertex data
      */
     getBounds() {
+        // When geometry data is released, compute bounds from cached bounding boxes
+        if (this.geometryReleased) {
+            if (this.boundingBoxes.size === 0)
+                return null;
+            let minX = Infinity, minY = Infinity, minZ = Infinity;
+            let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+            for (const bbox of this.boundingBoxes.values()) {
+                if (bbox.min.x < minX)
+                    minX = bbox.min.x;
+                if (bbox.min.y < minY)
+                    minY = bbox.min.y;
+                if (bbox.min.z < minZ)
+                    minZ = bbox.min.z;
+                if (bbox.max.x > maxX)
+                    maxX = bbox.max.x;
+                if (bbox.max.y > maxY)
+                    maxY = bbox.max.y;
+                if (bbox.max.z > maxZ)
+                    maxZ = bbox.max.z;
+            }
+            return {
+                min: { x: minX, y: minY, z: minZ },
+                max: { x: maxX, y: maxY, z: maxZ },
+            };
+        }
         if (this.meshDataMap.size === 0)
             return null;
         let minX = Infinity, minY = Infinity, minZ = Infinity;
@@ -960,9 +1214,13 @@ export class Scene {
         };
     }
     /**
-     * Get all expressIds that have mesh data (for CPU raycasting)
+     * Get all expressIds that have mesh data (for CPU raycasting).
+     * After geometry release, returns expressIds from the cached bounding boxes.
      */
     getAllMeshDataExpressIds() {
+        if (this.geometryReleased) {
+            return Array.from(this.boundingBoxes.keys());
+        }
         return Array.from(this.meshDataMap.keys());
     }
     /**
@@ -1010,31 +1268,111 @@ export class Scene {
         return bbox;
     }
     /**
-     * Ray-box intersection test (slab method)
+     * Ray-box intersection test (slab method).
+     * Handles zero ray direction components (axis-aligned rays) safely.
      */
     rayIntersectsBox(rayOrigin, rayDirInv, // 1/rayDir for efficiency
     rayDirSign, box) {
         const bounds = [box.min, box.max];
-        let tmin = (bounds[rayDirSign[0]].x - rayOrigin.x) * rayDirInv.x;
-        let tmax = (bounds[1 - rayDirSign[0]].x - rayOrigin.x) * rayDirInv.x;
-        const tymin = (bounds[rayDirSign[1]].y - rayOrigin.y) * rayDirInv.y;
-        const tymax = (bounds[1 - rayDirSign[1]].y - rayOrigin.y) * rayDirInv.y;
-        if (tmin > tymax || tymin > tmax)
-            return false;
-        if (tymin > tmin)
-            tmin = tymin;
-        if (tymax < tmax)
-            tmax = tymax;
-        const tzmin = (bounds[rayDirSign[2]].z - rayOrigin.z) * rayDirInv.z;
-        const tzmax = (bounds[1 - rayDirSign[2]].z - rayOrigin.z) * rayDirInv.z;
-        if (tmin > tzmax || tzmin > tmax)
-            return false;
-        if (tzmin > tmin)
-            tmin = tzmin;
-        if (tzmax < tmax)
-            tmax = tzmax;
+        let tmin = -Infinity;
+        let tmax = Infinity;
+        // X axis
+        if (!isFinite(rayDirInv.x)) {
+            if (rayOrigin.x < box.min.x || rayOrigin.x > box.max.x)
+                return false;
+        }
+        else {
+            tmin = (bounds[rayDirSign[0]].x - rayOrigin.x) * rayDirInv.x;
+            tmax = (bounds[1 - rayDirSign[0]].x - rayOrigin.x) * rayDirInv.x;
+        }
+        // Y axis
+        if (!isFinite(rayDirInv.y)) {
+            if (rayOrigin.y < box.min.y || rayOrigin.y > box.max.y)
+                return false;
+        }
+        else {
+            const tymin = (bounds[rayDirSign[1]].y - rayOrigin.y) * rayDirInv.y;
+            const tymax = (bounds[1 - rayDirSign[1]].y - rayOrigin.y) * rayDirInv.y;
+            if (tmin > tymax || tymin > tmax)
+                return false;
+            if (tymin > tmin)
+                tmin = tymin;
+            if (tymax < tmax)
+                tmax = tymax;
+        }
+        // Z axis
+        if (!isFinite(rayDirInv.z)) {
+            if (rayOrigin.z < box.min.z || rayOrigin.z > box.max.z)
+                return false;
+        }
+        else {
+            const tzmin = (bounds[rayDirSign[2]].z - rayOrigin.z) * rayDirInv.z;
+            const tzmax = (bounds[1 - rayDirSign[2]].z - rayOrigin.z) * rayDirInv.z;
+            if (tmin > tzmax || tzmin > tmax)
+                return false;
+            if (tzmin > tmin)
+                tmin = tzmin;
+            if (tzmax < tmax)
+                tmax = tzmax;
+        }
         return tmax >= 0;
     }
+    /**
+     * Ray-box intersection returning entry distance (tNear).
+     * Returns null if no intersection, otherwise the distance along the ray
+     * to the entry point (clamped to 0 if the ray originates inside the box).
+     * Handles zero ray direction components (axis-aligned rays) safely.
+     */
+    rayBoxDistance(rayOrigin, rayDirInv, rayDirSign, box) {
+        const bounds = [box.min, box.max];
+        let tmin = -Infinity;
+        let tmax = Infinity;
+        // X axis
+        if (!isFinite(rayDirInv.x)) {
+            // Ray parallel to X: miss if origin outside X slab
+            if (rayOrigin.x < box.min.x || rayOrigin.x > box.max.x)
+                return null;
+        }
+        else {
+            const t1 = (bounds[rayDirSign[0]].x - rayOrigin.x) * rayDirInv.x;
+            const t2 = (bounds[1 - rayDirSign[0]].x - rayOrigin.x) * rayDirInv.x;
+            tmin = t1;
+            tmax = t2;
+        }
+        // Y axis
+        if (!isFinite(rayDirInv.y)) {
+            if (rayOrigin.y < box.min.y || rayOrigin.y > box.max.y)
+                return null;
+        }
+        else {
+            const tymin = (bounds[rayDirSign[1]].y - rayOrigin.y) * rayDirInv.y;
+            const tymax = (bounds[1 - rayDirSign[1]].y - rayOrigin.y) * rayDirInv.y;
+            if (tmin > tymax || tymin > tmax)
+                return null;
+            if (tymin > tmin)
+                tmin = tymin;
+            if (tymax < tmax)
+                tmax = tymax;
+        }
+        // Z axis
+        if (!isFinite(rayDirInv.z)) {
+            if (rayOrigin.z < box.min.z || rayOrigin.z > box.max.z)
+                return null;
+        }
+        else {
+            const tzmin = (bounds[rayDirSign[2]].z - rayOrigin.z) * rayDirInv.z;
+            const tzmax = (bounds[1 - rayDirSign[2]].z - rayOrigin.z) * rayDirInv.z;
+            if (tmin > tzmax || tzmin > tmax)
+                return null;
+            if (tzmin > tmin)
+                tmin = tzmin;
+            if (tzmax < tmax)
+                tmax = tzmax;
+        }
+        if (tmax < 0)
+            return null;
+        return tmin < 0 ? 0 : tmin;
+    }
     /**
      * Möller–Trumbore ray-triangle intersection
      * Returns distance to intersection or null if no hit
@@ -1080,6 +1418,23 @@ export class Scene {
         ];
         let closestHit = null;
         let closestDistance = Infinity;
+        // When geometry data has been released, use bounding-box-only raycast.
+        // This is less accurate but uses only the precomputed bounding boxes.
+        // For precise picking, callers should use GPU picking instead.
+        if (this.geometryReleased) {
+            for (const [expressId, bbox] of this.boundingBoxes) {
+                if (hiddenIds?.has(expressId))
+                    continue;
+                if (isolatedIds !== null && isolatedIds !== undefined && !isolatedIds.has(expressId))
+                    continue;
+                const tNear = this.rayBoxDistance(rayOrigin, rayDirInv, rayDirSign, bbox);
+                if (tNear !== null && tNear < closestDistance) {
+                    closestDistance = tNear;
+                    closestHit = { expressId, distance: tNear };
+                }
+            }
+            return closestHit;
+        }
         // First pass: filter by bounding box (fast)
         const candidates = [];
         for (const expressId of this.meshDataMap.keys()) {