@ifc-lite/renderer 1.14.3 → 1.14.6

package/dist/index.js

@@ -20,7 +20,6 @@ export * from './types.js';
 // Zero-copy GPU upload (new - faster, less memory)
 export { ZeroCopyGpuUploader, createZeroCopyUploader, } from './zero-copy-uploader.js';
 // Extracted manager classes
-export { GeometryManager } from './geometry-manager.js';
 export { PickingManager } from './picking-manager.js';
 export { RaycastEngine } from './raycast-engine.js';
 import { WebGPUDevice } from './device.js';
@@ -28,13 +27,16 @@ import { RenderPipeline, InstancedRenderPipeline } from './pipeline.js';
 import { Camera } from './camera.js';
 import { Scene } from './scene.js';
 import { Picker } from './picker.js';
+import { MathUtils } from './math.js';
 import { FrustumUtils } from '@ifc-lite/spatial';
+import { deduplicateMeshes } from '@ifc-lite/geometry';
 import { SectionPlaneRenderer } from './section-plane.js';
 import { Section2DOverlayRenderer } from './section-2d-overlay.js';
-import { GeometryManager } from './geometry-manager.js';
 import { PickingManager } from './picking-manager.js';
 import { RaycastEngine } from './raycast-engine.js';
 import { PostProcessor } from './post-processor.js';
+const MAX_ENCODED_ENTITY_ID = 0xFFFFFF;
+let warnedEntityIdRange = false;
 /**
  * Main renderer class
  */
@@ -55,13 +57,17 @@ export class Renderer {
         contactShading: { quality: 'off', intensity: 0.3, radius: 1.0 },
         separationLines: { enabled: true, quality: 'low', intensity: 0.5, radius: 1.0 },
     };
+    // Model bounds for fitToView, section planes, camera
+    modelBounds = null;
     // Composition: delegate to extracted managers
-    geometryManager;
     pickingManager;
     raycastEngine;
     // Error rate limiting (log at most once per second)
     lastRenderErrorTime = 0;
     RENDER_ERROR_THROTTLE_MS = 1000;
+    // Dirty flag: set by requestRender(), consumed by the animation loop.
+    // Centralises all render scheduling — callers never call render() directly.
+    _renderRequested = false;
     // Pooled per-frame buffers to avoid GC pressure from per-batch Float32Array allocations
     // A single 192-byte uniform buffer (48 floats) is reused for all batches/meshes within a frame
     uniformScratch = new Float32Array(48);
@@ -72,8 +78,7 @@ export class Renderer {
         this.camera = new Camera();
         this.scene = new Scene();
         // Create composition managers
-        this.geometryManager = new GeometryManager(this.device, this.scene);
-        this.pickingManager = new PickingManager(this.camera, this.scene, null, this.canvas, this.geometryManager);
+        this.pickingManager = new PickingManager(this.camera, this.scene, null, this.canvas, (meshData) => this.createMeshFromData(meshData));
         this.raycastEngine = new RaycastEngine(this.camera, this.scene, this.canvas);
     }
     /**
@@ -111,10 +116,22 @@ export class Renderer {
      * @param geometry - Either a GeometryResult from geometry.process() or an array of MeshData
      */
     loadGeometry(geometry) {
-        if (!this.pipeline) {
+        if (!this.device.isInitialized() || !this.pipeline) {
             throw new Error('Renderer not initialized. Call init() first.');
         }
-        this.geometryManager.loadGeometry(geometry, this.pipeline);
+        const meshes = Array.isArray(geometry) ? geometry : geometry.meshes;
+        if (meshes.length === 0) {
+            console.warn('[Renderer] loadGeometry called with empty mesh array');
+            return;
+        }
+        // Use batched rendering for optimal performance
+        const device = this.device.getDevice();
+        this.scene.appendToBatches(meshes, device, this.pipeline, false);
+        // Calculate and store model bounds for fitToView
+        this.updateModelBounds(meshes);
+        console.log(`[Renderer] Loaded ${meshes.length} meshes`);
+        // Update camera scene bounds for tight orthographic near/far planes
+        this.camera.setSceneBounds(this.modelBounds);
     }
     /**
      * Add multiple meshes to the scene (convenience method for streaming)
@@ -123,16 +140,38 @@ export class Renderer {
      * @param isStreaming - If true, throttles batch rebuilding for better streaming performance
      */
     addMeshes(meshes, isStreaming = false) {
-        if (!this.pipeline) {
+        if (!this.device.isInitialized() || !this.pipeline) {
             throw new Error('Renderer not initialized. Call init() first.');
         }
-        this.geometryManager.addMeshes(meshes, this.pipeline, isStreaming);
+        if (meshes.length === 0)
+            return;
+        const device = this.device.getDevice();
+        this.scene.appendToBatches(meshes, device, this.pipeline, isStreaming);
+        // Update model bounds incrementally
+        this.updateModelBounds(meshes);
+        // Update camera scene bounds for tight orthographic near/far planes
+        this.camera.setSceneBounds(this.modelBounds);
     }
     /**
      * Fit camera to view all loaded geometry
      */
     fitToView() {
-        this.geometryManager.fitToView(this.camera);
+        if (!this.modelBounds) {
+            console.warn('[Renderer] fitToView called but no geometry loaded');
+            return;
+        }
+        const { min, max } = this.modelBounds;
+        // Calculate center and size
+        const center = {
+            x: (min.x + max.x) / 2,
+            y: (min.y + max.y) / 2,
+            z: (min.z + max.z) / 2
+        };
+        const size = Math.max(max.x - min.x, max.y - min.y, max.z - min.z);
+        // Position camera to see entire model
+        const distance = size * 1.5;
+        this.camera.setPosition(center.x + distance * 0.5, center.y + distance * 0.5, center.z + distance);
+        this.camera.setTarget(center.x, center.y, center.z);
     }
     /**
      * Add mesh to scene with per-mesh GPU resources for unique colors
@@ -140,17 +179,96 @@ export class Renderer {
     addMesh(mesh) {
         if (!this.pipeline)
             return;
-        this.geometryManager.addMesh(mesh, this.pipeline);
+        // Create per-mesh uniform buffer and bind group if not already created
+        if (!mesh.uniformBuffer && this.device.isInitialized()) {
+            const device = this.device.getDevice();
+            // Create uniform buffer for this mesh
+            mesh.uniformBuffer = device.createBuffer({
+                size: this.pipeline.getUniformBufferSize(),
+                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+            });
+            // Create bind group for this mesh
+            mesh.bindGroup = device.createBindGroup({
+                layout: this.pipeline.getBindGroupLayout(),
+                entries: [
+                    {
+                        binding: 0,
+                        resource: { buffer: mesh.uniformBuffer },
+                    },
+                ],
+            });
+        }
+        this.scene.addMesh(mesh);
     }
     /**
      * Add instanced geometry to scene
      * Converts InstancedGeometry from geometry package to InstancedMesh for rendering
      */
     addInstancedGeometry(geometry) {
-        if (!this.instancedPipeline) {
+        if (!this.instancedPipeline || !this.device.isInitialized()) {
             throw new Error('Renderer not initialized. Call init() first.');
         }
-        this.geometryManager.addInstancedGeometry(geometry, this.instancedPipeline);
+        const device = this.device.getDevice();
+        // Upload positions and normals interleaved
+        const vertexCount = geometry.positions.length / 3;
+        const vertexData = new Float32Array(vertexCount * 6);
+        for (let i = 0; i < vertexCount; i++) {
+            vertexData[i * 6 + 0] = geometry.positions[i * 3 + 0];
+            vertexData[i * 6 + 1] = geometry.positions[i * 3 + 1];
+            vertexData[i * 6 + 2] = geometry.positions[i * 3 + 2];
+            vertexData[i * 6 + 3] = geometry.normals[i * 3 + 0];
+            vertexData[i * 6 + 4] = geometry.normals[i * 3 + 1];
+            vertexData[i * 6 + 5] = geometry.normals[i * 3 + 2];
+        }
+        // Create vertex buffer with exact size needed (ensure it matches data size)
+        const vertexBufferSize = vertexData.byteLength;
+        const vertexBuffer = device.createBuffer({
+            size: vertexBufferSize,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        device.queue.writeBuffer(vertexBuffer, 0, vertexData);
+        // Create index buffer
+        const indexBuffer = device.createBuffer({
+            size: geometry.indices.byteLength,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+        device.queue.writeBuffer(indexBuffer, 0, geometry.indices);
+        // Create instance buffer: each instance is 80 bytes (20 floats: 16 for transform + 4 for color)
+        const instanceCount = geometry.instance_count;
+        const instanceData = new Float32Array(instanceCount * 20);
+        const expressIdToInstanceIndex = new Map();
+        for (let i = 0; i < instanceCount; i++) {
+            const instance = geometry.get_instance(i);
+            if (!instance)
+                continue;
+            const baseIdx = i * 20;
+            // Copy transform (16 floats)
+            instanceData.set(instance.transform, baseIdx);
+            // Copy color (4 floats)
+            instanceData[baseIdx + 16] = instance.color[0];
+            instanceData[baseIdx + 17] = instance.color[1];
+            instanceData[baseIdx + 18] = instance.color[2];
+            instanceData[baseIdx + 19] = instance.color[3];
+            expressIdToInstanceIndex.set(instance.expressId, i);
+        }
+        const instanceBuffer = device.createBuffer({
+            size: instanceData.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        device.queue.writeBuffer(instanceBuffer, 0, instanceData);
+        // Create and cache bind group to avoid per-frame allocation
+        const bindGroup = this.instancedPipeline.createInstanceBindGroup(instanceBuffer);
+        const instancedMesh = {
+            geometryId: Number(geometry.geometryId),
+            vertexBuffer,
+            indexBuffer,
+            indexCount: geometry.indices.length,
+            instanceBuffer,
+            instanceCount: instanceCount,
+            expressIdToInstanceIndex,
+            bindGroup,
+        };
+        this.scene.addInstancedMesh(instancedMesh);
     }
     /**
      * Convert MeshData array to instanced meshes for optimized rendering
@@ -158,19 +276,192 @@ export class Renderer {
      * Call this in background after initial streaming completes
      */
     convertToInstanced(meshDataArray) {
-        if (!this.instancedPipeline) {
+        if (!this.instancedPipeline || !this.device.isInitialized()) {
             console.warn('[Renderer] Cannot convert to instanced: renderer not initialized');
             return;
         }
-        this.geometryManager.convertToInstanced(meshDataArray, this.instancedPipeline);
+        const instancedData = deduplicateMeshes(meshDataArray);
+        const device = this.device.getDevice();
+        let totalInstances = 0;
+        for (const group of instancedData) {
+            const vertexCount = group.positions.length / 3;
+            const vertexData = new Float32Array(vertexCount * 6);
+            for (let i = 0; i < vertexCount; i++) {
+                vertexData[i * 6 + 0] = group.positions[i * 3 + 0];
+                vertexData[i * 6 + 1] = group.positions[i * 3 + 1];
+                vertexData[i * 6 + 2] = group.positions[i * 3 + 2];
+                vertexData[i * 6 + 3] = group.normals[i * 3 + 0];
+                vertexData[i * 6 + 4] = group.normals[i * 3 + 1];
+                vertexData[i * 6 + 5] = group.normals[i * 3 + 2];
+            }
+            const vertexBuffer = device.createBuffer({
+                size: vertexData.byteLength,
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+            });
+            device.queue.writeBuffer(vertexBuffer, 0, vertexData);
+            const indexBuffer = device.createBuffer({
+                size: group.indices.byteLength,
+                usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+            });
+            device.queue.writeBuffer(indexBuffer, 0, group.indices);
+            const instanceCount = group.instances.length;
+            const instanceData = new Float32Array(instanceCount * 20);
+            const expressIdToInstanceIndex = new Map();
+            const identityTransform = new Float32Array([
+                1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1,
+            ]);
+            for (let i = 0; i < instanceCount; i++) {
+                const instance = group.instances[i];
+                const baseIdx = i * 20;
+                instanceData.set(identityTransform, baseIdx);
+                instanceData[baseIdx + 16] = instance.color[0];
+                instanceData[baseIdx + 17] = instance.color[1];
+                instanceData[baseIdx + 18] = instance.color[2];
+                instanceData[baseIdx + 19] = instance.color[3];
+                expressIdToInstanceIndex.set(instance.expressId, i);
+            }
+            const instanceBuffer = device.createBuffer({
+                size: instanceData.byteLength,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+            device.queue.writeBuffer(instanceBuffer, 0, instanceData);
+            const bindGroup = this.instancedPipeline.createInstanceBindGroup(instanceBuffer);
+            let geometryHash = 0;
+            for (let i = 0; i < group.geometryHash.length; i++) {
+                geometryHash = ((geometryHash << 5) - geometryHash) + group.geometryHash.charCodeAt(i);
+                geometryHash = geometryHash & geometryHash;
+            }
+            this.scene.addInstancedMesh({
+                geometryId: Math.abs(geometryHash),
+                vertexBuffer,
+                indexBuffer,
+                indexCount: group.indices.length,
+                instanceBuffer,
+                instanceCount,
+                expressIdToInstanceIndex,
+                bindGroup,
+            });
+            totalInstances += instanceCount;
+        }
+        const regularMeshCount = this.scene.getMeshes().length;
+        this.scene.clearRegularMeshes();
+        console.log(`[Renderer] Converted ${meshDataArray.length} meshes to ${instancedData.length} instanced geometries ` +
+            `(${totalInstances} total instances, ${(totalInstances / instancedData.length).toFixed(1)}x deduplication). ` +
+            `Cleared ${regularMeshCount} regular meshes.`);
     }
     /**
      * Ensure all meshes have GPU resources (call after adding meshes if pipeline wasn't ready)
      */
     ensureMeshResources() {
-        if (!this.pipeline)
+        if (!this.pipeline || !this.device.isInitialized())
+            return;
+        const device = this.device.getDevice();
+        for (const mesh of this.scene.getMeshes()) {
+            if (!mesh.uniformBuffer) {
+                mesh.uniformBuffer = device.createBuffer({
+                    size: this.pipeline.getUniformBufferSize(),
+                    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+                });
+                mesh.bindGroup = device.createBindGroup({
+                    layout: this.pipeline.getBindGroupLayout(),
+                    entries: [{
+                            binding: 0,
+                            resource: { buffer: mesh.uniformBuffer },
+                        }],
+                });
+            }
+        }
+    }
+    /**
+     * Get model bounds (used for section planes, fitToView, etc.)
+     */
+    getModelBounds() {
+        return this.modelBounds;
+    }
+    /**
+     * Set model bounds (used when computing bounds from batches)
+     */
+    setModelBounds(bounds) {
+        this.modelBounds = bounds;
+    }
+    /**
+     * Update model bounds from mesh data
+     */
+    updateModelBounds(meshes) {
+        if (!this.modelBounds) {
+            this.modelBounds = {
+                min: { x: Infinity, y: Infinity, z: Infinity },
+                max: { x: -Infinity, y: -Infinity, z: -Infinity }
+            };
+        }
+        for (const mesh of meshes) {
+            const positions = mesh.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 (Number.isFinite(x) && Number.isFinite(y) && Number.isFinite(z)) {
+                    this.modelBounds.min.x = Math.min(this.modelBounds.min.x, x);
+                    this.modelBounds.min.y = Math.min(this.modelBounds.min.y, y);
+                    this.modelBounds.min.z = Math.min(this.modelBounds.min.z, z);
+                    this.modelBounds.max.x = Math.max(this.modelBounds.max.x, x);
+                    this.modelBounds.max.y = Math.max(this.modelBounds.max.y, y);
+                    this.modelBounds.max.z = Math.max(this.modelBounds.max.z, z);
+                }
+            }
+        }
+    }
+    /**
+     * Create a GPU Mesh from MeshData (lazy creation for selection highlighting)
+     * This is called on-demand when a mesh is selected, avoiding 2x buffer creation during streaming
+     */
+    createMeshFromData(meshData) {
+        if (!this.device.isInitialized())
             return;
-        this.geometryManager.ensureMeshResources(this.pipeline);
+        const device = this.device.getDevice();
+        const vertexCount = meshData.positions.length / 3;
+        const interleavedRaw = new ArrayBuffer(vertexCount * 7 * 4);
+        const interleaved = new Float32Array(interleavedRaw);
+        const interleavedU32 = new Uint32Array(interleavedRaw);
+        for (let i = 0; i < vertexCount; i++) {
+            const base = i * 7;
+            const posBase = i * 3;
+            interleaved[base] = meshData.positions[posBase];
+            interleaved[base + 1] = meshData.positions[posBase + 1];
+            interleaved[base + 2] = meshData.positions[posBase + 2];
+            interleaved[base + 3] = meshData.normals[posBase];
+            interleaved[base + 4] = meshData.normals[posBase + 1];
+            interleaved[base + 5] = meshData.normals[posBase + 2];
+            let encodedId = meshData.expressId >>> 0;
+            if (encodedId > MAX_ENCODED_ENTITY_ID) {
+                if (!warnedEntityIdRange) {
+                    warnedEntityIdRange = true;
+                    console.warn('[Renderer] expressId exceeds 24-bit seam-ID encoding range; seam lines may collide.');
+                }
+                encodedId = encodedId & MAX_ENCODED_ENTITY_ID;
+            }
+            interleavedU32[base + 6] = encodedId;
+        }
+        const vertexBuffer = device.createBuffer({
+            size: interleaved.byteLength,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+        device.queue.writeBuffer(vertexBuffer, 0, interleaved);
+        const indexBuffer = device.createBuffer({
+            size: meshData.indices.byteLength,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+        device.queue.writeBuffer(indexBuffer, 0, meshData.indices);
+        // Add to scene with identity transform (positions already in world space)
+        this.scene.addMesh({
+            expressId: meshData.expressId,
+            modelIndex: meshData.modelIndex, // Preserve modelIndex for multi-model selection
+            vertexBuffer,
+            indexBuffer,
+            indexCount: meshData.indices.length,
+            transform: MathUtils.identity(),
+            color: meshData.color,
+        });
     }
     resolveVisualEnhancement(options) {
         if (!options) {
@@ -236,12 +527,15 @@ export class Renderer {
         const device = this.device.getDevice();
         const viewProj = this.camera.getViewProjMatrix().m;
         const visualEnhancement = this.resolveVisualEnhancement(options.visualEnhancement);
-        const edgeEnabled = visualEnhancement.enabled && visualEnhancement.edgeContrast.enabled;
+        // Skip expensive visual effects during interaction (orbit/pan/zoom)
+        // to keep frame times low on integrated GPUs (MacBook Air etc.)
+        const interacting = options.isInteracting === true;
+        const edgeEnabled = !interacting && visualEnhancement.enabled && visualEnhancement.edgeContrast.enabled;
         const edgeIntensity = Math.min(3.0, Math.max(0.0, visualEnhancement.edgeContrast.intensity));
         const edgeEnabledU32 = edgeEnabled ? 1 : 0;
         const edgeIntensityMilliU32 = Math.round(edgeIntensity * 1000);
-        const contactEnabled = visualEnhancement.enabled && visualEnhancement.contactShading.quality !== 'off';
-        const separationEnabled = visualEnhancement.enabled
+        const contactEnabled = !interacting && visualEnhancement.enabled && visualEnhancement.contactShading.quality !== 'off';
+        const separationEnabled = !interacting && visualEnhancement.enabled
             && visualEnhancement.separationLines.enabled
             && visualEnhancement.separationLines.quality !== 'off';
         const needsObjectIdPass = contactEnabled || separationEnabled;
@@ -356,8 +650,9 @@ export class Renderer {
                     boundsMin.x = boundsMin.y = boundsMin.z = -100;
                     boundsMax.x = boundsMax.y = boundsMax.z = 100;
                 }
-                // Store bounds for section plane visual
-                this.geometryManager.setModelBounds({ min: boundsMin, max: boundsMax });
+                // Store bounds for section plane visual and camera near/far
+                this.setModelBounds({ min: boundsMin, max: boundsMax });
+                this.camera.setSceneBounds({ min: boundsMin, max: boundsMax });
                 // Only calculate clipping data if section is enabled
                 if (options.sectionPlane.enabled) {
                     // Calculate plane normal based on semantic axis
@@ -630,13 +925,6 @@ export class Renderer {
                 // PERFORMANCE FIX: Render partially visible batches as sub-batches (not individual meshes!)
                 // This is the key optimization: instead of 10,000+ individual draw calls,
                 // we create cached sub-batches with only visible elements and render them as single draw calls
-                const allMeshesFromScene = this.scene.getMeshes();
-                // Track existing mesh piece counts by (expressId:modelIndex) for multi-piece elements.
-                const existingPieceCounts = new Map();
-                for (const mesh of allMeshesFromScene) {
-                    const key = `${mesh.expressId}:${mesh.modelIndex ?? 'any'}`;
-                    existingPieceCounts.set(key, (existingPieceCounts.get(key) ?? 0) + 1);
-                }
                 if (partiallyVisibleBatches.length > 0) {
                     for (const { colorKey, visibleIds, color } of partiallyVisibleBatches) {
                         // Get or create a cached sub-batch for this visibility state
@@ -679,29 +967,41 @@ export class Renderer {
                         continue;
                     visibleSelectedIds.add(selId);
                 }
-                const baselineExistingCounts = new Map(existingPieceCounts);
-                for (const selId of visibleSelectedIds) {
-                    const pieces = this.scene.getMeshDataPieces(selId, selectedModelIndex);
-                    if (!pieces || pieces.length === 0)
-                        continue;
-                    const seenOrdinalsByKey = new Map();
-                    for (const piece of pieces) {
-                        const meshKey = `${piece.expressId}:${piece.modelIndex ?? 'any'}`;
-                        const ordinal = seenOrdinalsByKey.get(meshKey) ?? 0;
-                        seenOrdinalsByKey.set(meshKey, ordinal + 1);
-                        const baselineExisting = baselineExistingCounts.get(meshKey) ?? 0;
-                        if (ordinal < baselineExisting)
+                // Only build per-mesh piece counts when we actually have selected
+                // elements that need individual mesh rendering. This avoids iterating
+                // 200K+ meshes every frame when nothing is selected.
+                if (visibleSelectedIds.size > 0) {
+                    const allMeshesFromScene = this.scene.getMeshes();
+                    const existingPieceCounts = new Map();
+                    for (const mesh of allMeshesFromScene) {
+                        const key = `${mesh.expressId}:${mesh.modelIndex ?? 'any'}`;
+                        existingPieceCounts.set(key, (existingPieceCounts.get(key) ?? 0) + 1);
+                    }
+                    for (const selId of visibleSelectedIds) {
+                        const pieces = this.scene.getMeshDataPieces(selId, selectedModelIndex);
+                        if (!pieces || pieces.length === 0)
                             continue;
-                        this.geometryManager.createMeshFromData(piece);
+                        const seenOrdinalsByKey = new Map();
+                        for (const piece of pieces) {
+                            const meshKey = `${piece.expressId}:${piece.modelIndex ?? 'any'}`;
+                            const ordinal = seenOrdinalsByKey.get(meshKey) ?? 0;
+                            seenOrdinalsByKey.set(meshKey, ordinal + 1);
+                            const baselineExisting = existingPieceCounts.get(meshKey) ?? 0;
+                            if (ordinal < baselineExisting)
+                                continue;
+                            this.createMeshFromData(piece);
+                        }
                     }
                 }
-                const selectedMeshes = this.scene.getMeshes().filter(mesh => {
-                    if (!visibleSelectedIds.has(mesh.expressId))
-                        return false;
-                    if (selectedModelIndex !== undefined && mesh.modelIndex !== selectedModelIndex)
-                        return false;
-                    return true;
-                });
+                const selectedMeshes = visibleSelectedIds.size > 0
+                    ? this.scene.getMeshes().filter(mesh => {
+                        if (!visibleSelectedIds.has(mesh.expressId))
+                            return false;
+                        if (selectedModelIndex !== undefined && mesh.modelIndex !== selectedModelIndex)
+                            return false;
+                        return true;
+                    })
+                    : [];
                 // Render transparent BATCHED meshes with transparent pipeline (after opaque batches and selections)
                 if (transparentBatches.length > 0) {
                     pass.setPipeline(this.pipeline.getTransparentPipeline());
@@ -859,7 +1159,7 @@ export class Renderer {
             }
             // Draw section plane visual BEFORE pass.end() (within same MSAA render pass)
             // Always show plane when sectionPlane options are provided (as preview or active)
-            const modelBounds = this.geometryManager.getModelBounds();
+            const modelBounds = this.getModelBounds();
             if (options.sectionPlane && this.sectionPlaneRenderer && modelBounds) {
                 this.sectionPlaneRenderer.draw(pass, {
                     axis: options.sectionPlane.axis,
@@ -973,6 +1273,37 @@ export class Renderer {
     clearCaches() {
         this.raycastEngine.clearCaches();
     }
+    // ─── Dirty-flag render scheduling ────────────────────────────────────
+    // The animation loop is THE render path.  Everything else (mouse, touch,
+    // keyboard, streaming, visibility changes, theme changes) calls
+    // requestRender() to set the dirty flag.  The loop drains scene queues,
+    // resolves render options via refs, and issues a single render() call.
+    /**
+     * Request a render on the next animation frame.
+     * Safe to call many times per frame — only one render will happen.
+     */
+    requestRender() {
+        this._renderRequested = true;
+    }
+    /**
+     * Check whether a render has been requested without clearing the flag.
+     * Used by the animation loop to test the dirty flag before committing
+     * to render (e.g. when throttling may skip the frame).
+     */
+    peekRenderRequest() {
+        return this._renderRequested;
+    }
+    /**
+     * Consume the render request flag.  Returns true (and resets the flag)
+     * if a render was requested since the last call.  Used by the animation
+     * loop to decide whether to render.
+     */
+    consumeRenderRequest() {
+        if (!this._renderRequested)
+            return false;
+        this._renderRequested = false;
+        return true;
+    }
     /**
      * Resize canvas
      */
@@ -1001,7 +1332,7 @@ export class Renderer {
         // minVal = options.sectionPlane.min ?? boundsMin[axisIdx]
         // maxVal = options.sectionPlane.max ?? boundsMax[axisIdx]
         const axisIdx = axis === 'side' ? 'x' : axis === 'down' ? 'y' : 'z';
-        const modelBounds = this.geometryManager.getModelBounds();
+        const modelBounds = this.getModelBounds();
         // Allow upload if either sectionRange has both values, or modelBounds exists as fallback
         const hasFullRange = sectionRange?.min !== undefined && sectionRange?.max !== undefined;
         if (!hasFullRange && !modelBounds)
@@ -1070,6 +1401,36 @@ export class Renderer {
             return null;
         }
     }
+    /**
+     * Destroy the renderer and release all GPU resources.
+     *
+     * Cleans up scene buffers, render pipeline textures, picking resources,
+     * post-processing buffers, section-plane renderers, and snap caches.
+     * After calling this method the renderer is no longer usable.
+     * Safe to call multiple times (idempotent).
+     */
+    destroy() {
+        // Scene mesh GPU buffers
+        this.scene.clear();
+        // Render pipelines (textures + uniform buffers)
+        this.pipeline?.destroy();
+        this.pipeline = null;
+        this.instancedPipeline?.destroy();
+        this.instancedPipeline = null;
+        // Picker GPU resources
+        this.picker?.destroy();
+        this.picker = null;
+        // Post-processor uniform buffer
+        this.postProcessor?.destroy();
+        this.postProcessor = null;
+        // Section-plane renderers
+        this.sectionPlaneRenderer?.destroy();
+        this.sectionPlaneRenderer = null;
+        this.section2DOverlayRenderer?.dispose();
+        this.section2DOverlayRenderer = null;
+        // Snap detector geometry cache
+        this.raycastEngine.clearCaches();
+    }
     /**
      * Get the canvas element
      */