@ifc-lite/renderer 1.37.0 → 1.38.1

package/dist/index.js

@@ -59,6 +59,7 @@ import { PickingManager } from './picking-manager.js';
 import { RaycastEngine } from './raycast-engine.js';
 import { PostProcessor } from './post-processor.js';
 import { InteractionEffectsGovernor } from './interaction-effects-governor.js';
+import { VisibilityEpochTracker } from './visibility-epoch.js';
 import { resolveContributionThresholdPx, projectedAabbRadiusPx, projectedInstancedRadiusPx } from './contribution-cull.js';
 import { EdlPass } from './edl-pass.js';
 import { SkyPass } from './sky-pass.js';
@@ -125,6 +126,15 @@ export class Renderer {
     /** Set true at the end of `init()`; gates `whenReady()`. */
     ready = false;
     readyWaiters = [];
+    /**
+     * Set once the GPU device is lost for a non-intentional reason (driver
+     * reset / VRAM exhaustion — see `WebGPUDevice`). Every GPU resource is then
+     * dead, so `render()` becomes a no-op (it would only spew validation errors)
+     * until the host re-initialises the renderer. Consumers learn of this via
+     * `onDeviceLost` and typically respond by reloading the model.
+     */
+    deviceLost = false;
+    deviceLostListeners = new Set();
     deviationPipeline = null;
     /**
      * Cache of which mesh-set the BVH was built from. We rebuild on
@@ -145,8 +155,11 @@ export class Renderer {
     // Composition: delegate to extracted managers
     pickingManager;
     raycastEngine;
-    // Error rate limiting (log at most once per second)
-    lastRenderErrorTime = 0;
+    // Error rate limiting (log at most once per second). -Infinity, not 0:
+    // performance.now() is below 1000 during the first second of page life, so
+    // a 0 start would silently suppress the FIRST render/device-loss error —
+    // exactly the evidence worth keeping.
+    lastRenderErrorTime = -Infinity;
     RENDER_ERROR_THROTTLE_MS = 1000;
     // Diagnostic counters for mobile debugging
     _renderCallCount = 0;
@@ -158,6 +171,35 @@ export class Renderer {
     // Dirty flag: set by requestRender(), consumed by the animation loop.
     // Centralises all render scheduling — callers never call render() directly.
     _renderRequested = false;
+    // ─── Visibility-change bookkeeping (per-frame perf + leak fixes) ─────────
+    // Hide/isolate changes are detected by CONTENT (snapshot compare in the
+    // tracker), so callers may either mutate the same Set in place or pass a
+    // fresh Set per frame — see the RenderOptions.hiddenIds contract.
+    // `_visibilityVersion` drives the per-batch visibility cache;
+    // `_partialBatchEpoch` additionally folds colour-override changes so the
+    // partial sub-batch cache fast path stays correct.
+    _visibilityEpochs = new VisibilityEpochTracker();
+    _visibilityVersion = 0;
+    _partialBatchEpoch = 0;
+    _lastColorOverrideGen = -1;
+    _lastHadVisibilityFiltering = false;
+    // Cached per-batch visibility, valid only while `_batchVisibilityEpoch`
+    // matches `_visibilityVersion`. Avoids the O(total element count) recompute
+    // (+ per-batch visible-id Set allocation) every frame while hide/isolate
+    // holds. Keyed by batch object (immutable expressIds per instance); a
+    // rebuilt batch is a new object → recomputed lazily. WeakMap, not Map:
+    // residency eviction/restore churn while ONE filter epoch holds (e.g. a
+    // schedule animation) would otherwise pin every dead batch object until
+    // the next visibility change.
+    _batchVisibilityEpoch = -1;
+    _batchVisibilityCache = new WeakMap();
+    // Selection snapshot from the previous frame — a change triggers disposal of
+    // now-unselected hydrated meshes (leak + double-draw fix). The model index
+    // is part of the snapshot: federated models can share express ids, so a
+    // same-id selection in ANOTHER model is still a change that must free the
+    // old model's hydrated mesh.
+    _prevHydratedSelection = new Set();
+    _prevHydratedSelectionModelIndex = undefined;
     // One-shot log guard — prints Y-up clip bounds on first section-enable so
     // users can confirm the slider is operating on the intended range.
     _loggedSectionBounds = false;
@@ -186,6 +228,13 @@ export class Renderer {
      * Initialize renderer
      */
     async init() {
+        // Clear the lost flag so a re-init (destroy()+init() on the same instance)
+        // resumes rendering instead of staying a permanent no-op from an earlier loss.
+        this.deviceLost = false;
+        // Subscribe before the device exists so a loss during the first frames
+        // is never missed — the handler is only invoked when `device.lost`
+        // actually resolves (a real fault), long after init in practice.
+        this.device.onDeviceLost((info) => this.handleDeviceLost(info));
         await this.device.init(this.canvas);
         // Get canvas dimensions (use pixel dimensions if set, otherwise use CSS dimensions)
         // and clamp to the GPU's max 2D texture dimension so the initial pipeline allocations
@@ -276,6 +325,39 @@ export class Renderer {
         for (const w of waiters)
             w();
     }
+    /**
+     * Subscribe to non-intentional GPU device loss (driver reset / VRAM
+     * exhaustion — NOT an intentional `destroy()`). Fired at most once per
+     * device. After it fires, `render()` is a no-op until the renderer is
+     * re-initialised, so the typical response is to dispose this renderer and
+     * reload the model. Returns an unsubscribe function.
+     *
+     * Camera and model state live on the CPU (JS) and survive device loss, so a
+     * reload restores the model at its current orientation — the loss is a GPU
+     * event, not a data loss.
+     */
+    onDeviceLost(listener) {
+        this.deviceLostListeners.add(listener);
+        return () => this.deviceLostListeners.delete(listener);
+    }
+    /** True once the GPU device has been lost for a non-intentional reason. */
+    isDeviceLost() {
+        return this.deviceLost;
+    }
+    handleDeviceLost(info) {
+        if (this.deviceLost)
+            return;
+        this.deviceLost = true;
+        console.warn('[Renderer] GPU device lost — halting rendering until re-init:', info.message);
+        for (const listener of this.deviceLostListeners) {
+            try {
+                listener(info);
+            }
+            catch (e) {
+                console.error('[Renderer] onDeviceLost listener threw:', e);
+            }
+        }
+    }
     /**
      * Replace all loaded point clouds with `assets`.
      *
@@ -797,7 +879,10 @@ export class Renderer {
             usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
         });
         device.queue.writeBuffer(indexBuffer, 0, meshData.indices);
-        // Add to scene with identity transform (positions already in world space)
+        // Add to scene with identity transform (positions already in world space).
+        // Flagged `hydrated` so it can be freed when its entity leaves the
+        // selection — these duplicate geometry already drawn by a batch and would
+        // otherwise accumulate + double-draw (see Scene.disposeHydratedMeshesExcept).
         this.scene.addMesh({
             expressId: meshData.expressId,
             modelIndex: meshData.modelIndex, // Preserve modelIndex for multi-model selection
@@ -806,6 +891,70 @@ export class Renderer {
             indexCount: meshData.indices.length,
             transform: MathUtils.identity(),
             color: meshData.color,
+            hydrated: true,
+        });
+    }
+    /**
+     * On a selection change, free the hydrated (pick/selection-highlight)
+     * individual meshes whose entity is no longer selected. These duplicate
+     * geometry already drawn by a batch; without this they accumulate in
+     * scene.meshes (VRAM grows with selection history) and — for transparent
+     * entities — re-draw every frame on top of their still-drawn batch copy
+     * (double alpha-blend darkens glass). Currently-selected entities keep their
+     * hydrated meshes so the highlight pass doesn't rebuild them each change.
+     * No-op when the selection set is unchanged to avoid per-frame buffer churn.
+     * Selection identity is the (modelIndex, expressId) PAIR: federated models
+     * can share express ids, so re-selecting the same id in a different model
+     * must still free the previous model's hydrated mesh (it would otherwise
+     * stay resident and keep drawing unhighlighted).
+     */
+    syncHydratedSelectionMeshes(selected, selectedModelIndex) {
+        const prev = this._prevHydratedSelection;
+        let changed = selected.size !== prev.size
+            || selectedModelIndex !== this._prevHydratedSelectionModelIndex;
+        if (!changed) {
+            for (const id of selected) {
+                if (!prev.has(id)) {
+                    changed = true;
+                    break;
+                }
+            }
+        }
+        if (!changed)
+            return;
+        this._prevHydratedSelection = new Set(selected);
+        this._prevHydratedSelectionModelIndex = selectedModelIndex;
+        this.scene.disposeHydratedMeshesExcept(selected, selectedModelIndex);
+    }
+    /**
+     * Pop the frame's validation error scope, recording any captured validation
+     * error into the device diagnostics (getDiagnostics().gpuErrors). The pop
+     * itself REJECTS when the GPU device is lost while the scope is pending —
+     * often the only evidence of the loss — so the rejection is logged
+     * (throttled) and the context invalidated, never swallowed silently. Used
+     * by every render() exit path that pushed a scope, so push/pop stay
+     * balanced even on skipped or throwing frames.
+     */
+    drainErrorScope(device) {
+        device.popErrorScope().then((error) => {
+            if (error) {
+                const msg = error.message || String(error);
+                console.error('[WebGPU] Validation error in render pass:', msg);
+                this.device._lastUncapturedError = `VALIDATION: ${msg}`;
+                this.device._uncapturedErrorCount++;
+            }
+        }).catch((error) => {
+            // popErrorScope() rejects (e.g. "Instance dropped in popErrorScope")
+            // when the GPU device is lost while the scope is still pending. This
+            // escapes the surrounding synchronous try/catch and would otherwise
+            // surface as an unhandled rejection. Treat it like any other device
+            // loss: invalidate the context so it reconfigures next frame.
+            this.device.invalidateContext();
+            const now = performance.now();
+            if (now - this.lastRenderErrorTime > this.RENDER_ERROR_THROTTLE_MS) {
+                this.lastRenderErrorTime = now;
+                console.warn('[WebGPU] popErrorScope rejected (device likely lost):', error);
+            }
         });
     }
     resolveVisualEnhancement(options) {
@@ -881,6 +1030,12 @@ export class Renderer {
     }
     render(options = {}) {
         this._renderCallCount++;
+        // A lost device leaves every pipeline/buffer dead; rendering would only
+        // emit a stream of validation errors. Stay quiet until re-init.
+        if (this.deviceLost) {
+            this._renderSkipCount++;
+            return;
+        }
         if (!this.device.isInitialized() || !this.pipeline) {
             this._renderSkipCount++;
             return;
@@ -969,11 +1124,35 @@ export class Renderer {
             && visualEnhancement.separationLines.enabled
             && visualEnhancement.separationLines.quality !== 'off';
         const needsObjectIdPass = contactEnabled || separationEnabled;
-        let meshes = this.scene.getMeshes();
         // Check if visibility filtering is active
         const hasHiddenFilter = options.hiddenIds && options.hiddenIds.size > 0;
         const hasIsolatedFilter = options.isolatedIds !== null && options.isolatedIds !== undefined;
         const hasVisibilityFiltering = hasHiddenFilter || hasIsolatedFilter;
+        // ─── Visibility / override epoch bookkeeping ────────────────────────
+        // The tracker compares hide/isolate CONTENT against a snapshot, so both
+        // in-place mutation of the caller's Set and a fresh identical Set per
+        // frame behave correctly (see RenderOptions.hiddenIds). Bumping
+        // `_visibilityVersion` invalidates the per-batch visibility cache; the
+        // partial sub-batch cache additionally depends on colour-override
+        // promotion, so its epoch bumps on either.
+        const newVisibilityVersion = this._visibilityEpochs.update(options.hiddenIds, options.isolatedIds);
+        const visibilityChanged = newVisibilityVersion !== this._visibilityVersion;
+        this._visibilityVersion = newVisibilityVersion;
+        const colorOverrideGen = this.scene.getColorOverrideGeneration();
+        if (visibilityChanged || colorOverrideGen !== this._lastColorOverrideGen) {
+            this._lastColorOverrideGen = colorOverrideGen;
+            this._partialBatchEpoch++;
+        }
+        // When hide/isolate turns fully OFF (back to all-visible), release the
+        // partial sub-batch clones built while filtering. They are excluded from
+        // the GPU residency budget and are otherwise only freed on clear()/
+        // finalize/evict — never here — so ~model-sized clone VRAM would stay
+        // pinned until the next model reload. Any override-promotion sub-batches
+        // dropped alongside are rebuilt on demand next frame (cache miss).
+        if (this._lastHadVisibilityFiltering && !hasVisibilityFiltering) {
+            this.scene.dropAllPartialCaches();
+        }
+        this._lastHadVisibilityFiltering = hasVisibilityFiltering;
         // Build the selected-id set once per frame so the X-Ray override paths
         // can keep highlighted entities at full alpha without per-site checks.
         const selectedId = options.selectedId;
@@ -989,6 +1168,13 @@ export class Renderer {
             }
         }
         const hasSelected = selectedExpressIds.size > 0;
+        // Free hydrated (pick/selection) individual meshes whose entity is no
+        // longer selected BEFORE we snapshot the mesh list, so stale glass
+        // doesn't double-draw over its batch copy or accumulate until clear().
+        // Only acts on a selection change (avoids per-frame buffer churn) and
+        // never touches authored (non-hydrated) or batch geometry.
+        this.syncHydratedSelectionMeshes(selectedExpressIds, selectedModelIndex);
+        let meshes = this.scene.getMeshes();
         // Keep the GPU-instanced occurrences' per-instance selected flag in sync.
         // The Scene diff makes this a no-op (no writeBuffer) when the set is
         // unchanged, so calling it every frame is cheap; it no-ops entirely when
@@ -1103,14 +1289,26 @@ export class Renderer {
             this.pipeline.resize(this.canvas.width, this.canvas.height);
         }
         // Push a validation error scope to capture the EXACT error (for mobile debugging)
-        // Only do this for the first few renders to avoid performance overhead
+        // Only do this for the first few renders to avoid performance overhead.
+        // Tracked with a flag (not just captureGpuError) so EVERY exit path below
+        // pops it exactly once — an unpopped scope silently swallows all later
+        // validation errors and blinds getDiagnostics().gpuErrors.
         const captureGpuError = this._renderCallCount <= 5;
+        let errorScopePushed = false;
         if (captureGpuError) {
             device.pushErrorScope('validation');
+            errorScopePushed = true;
         }
         // Get current texture safely - may return null if context needs reconfiguration
         const currentTexture = this.device.getCurrentTexture();
         if (!currentTexture) {
+            // Balance the pushed scope before bailing so it doesn't leak into
+            // the next frame; drainErrorScope logs a rejection (device loss)
+            // instead of swallowing the evidence.
+            if (errorScopePushed) {
+                errorScopePushed = false;
+                this.drainErrorScope(device);
+            }
             return; // Skip this frame, context will be reconfigured next frame
         }
         try {
@@ -1538,27 +1736,41 @@ export class Renderer {
                         viewportHeightPx: this.canvas.height,
                     };
                 }
-                // Pre-compute visibility for each batch (only when filtering is active)
-                // A batch is visible if ANY of its elements are visible
-                // A batch is fully visible if ALL of its elements are visible
-                const batchVisibility = new Map();
-                if (hasVisibilityFiltering) {
-                    for (const batch of allBatchedMeshes) {
-                        let visibleCount = 0;
-                        const total = batch.expressIds.length;
-                        for (const expressId of batch.expressIds) {
-                            const isHidden = options.hiddenIds?.has(expressId) ?? false;
-                            const isIsolated = !hasIsolatedFilter || options.isolatedIds.has(expressId);
-                            if (!isHidden && isIsolated) {
-                                visibleCount++;
-                            }
-                        }
-                        batchVisibility.set(batch, {
-                            visible: visibleCount > 0,
-                            fullyVisible: visibleCount === total,
-                        });
-                    }
+                // Per-batch visibility (only meaningful while filtering is active).
+                // A batch is visible if ANY of its elements are visible, fully
+                // visible if ALL are. Cached across frames keyed by the visibility
+                // version so the O(total element count) scan + per-batch visible-id
+                // Set allocation happens once per visibility change, not per frame.
+                // The cache map is keyed by batch object (immutable expressIds per
+                // instance); a rebuilt batch is a new object → recomputed lazily.
+                if (this._batchVisibilityEpoch !== this._visibilityVersion) {
+                    this._batchVisibilityCache = new WeakMap();
+                    this._batchVisibilityEpoch = this._visibilityVersion;
                 }
+                const batchVisibilityCache = this._batchVisibilityCache;
+                const getBatchVisibility = (batch) => {
+                    let vis = batchVisibilityCache.get(batch);
+                    if (vis)
+                        return vis;
+                    const total = batch.expressIds.length;
+                    // Build the visible-id set in one pass; drop it for fully-visible
+                    // batches (they draw from their own buffers, no subset needed).
+                    const visibleIds = new Set();
+                    for (const expressId of batch.expressIds) {
+                        const isHidden = options.hiddenIds?.has(expressId) ?? false;
+                        const isIsolated = !hasIsolatedFilter || options.isolatedIds.has(expressId);
+                        if (!isHidden && isIsolated)
+                            visibleIds.add(expressId);
+                    }
+                    const fullyVisible = visibleIds.size === total;
+                    vis = {
+                        visible: visibleIds.size > 0,
+                        fullyVisible,
+                        visibleIds: fullyVisible ? undefined : visibleIds,
+                    };
+                    batchVisibilityCache.set(batch, vis);
+                    return vis;
+                };
                 // Separate batches into opaque and transparent, filtering by visibility
                 // IMPORTANT: Only render FULLY visible batches - partially visible batches
                 // need individual mesh rendering to show only the visible elements
@@ -1640,19 +1852,15 @@ export class Renderer {
                     const nativelyTransparent = alpha < 0.99;
                     // Check visibility
                     if (hasVisibilityFiltering) {
-                        const vis = batchVisibility.get(batch);
-                        if (!vis || !vis.visible)
+                        const vis = getBatchVisibility(batch);
+                        if (!vis.visible)
                             continue; // Skip completely hidden batches
                         // Handle partially visible batches - create sub-batches instead of individual meshes
                         if (!vis.fullyVisible) {
-                            const visibleIds = new Set();
-                            for (const expressId of batch.expressIds) {
-                                const isHidden = options.hiddenIds?.has(expressId) ?? false;
-                                const isIsolated = !hasIsolatedFilter || options.isolatedIds.has(expressId);
-                                if (!isHidden && isIsolated)
-                                    visibleIds.add(expressId);
-                            }
-                            if (visibleIds.size > 0) {
+                            // The visible subset was computed once for this
+                            // visibility epoch (cached) — reuse it, don't rebuild.
+                            const visibleIds = vis.visibleIds;
+                            if (visibleIds && visibleIds.size > 0) {
                                 pushVisibleAsPartial(batch, visibleIds, nativelyTransparent);
                             }
                             // A COLD parent has no CPU meshData, so the partial
@@ -1949,7 +2157,7 @@ export class Renderer {
                 if (partiallyVisibleBatches.length > 0) {
                     for (const { sourceBatchKey, colorKey, visibleIds, color } of partiallyVisibleBatches) {
                         // Get or create a cached sub-batch for this visibility state
-                        const subBatch = this.scene.getOrCreatePartialBatch(sourceBatchKey, colorKey, visibleIds, device, this.pipeline);
+                        const subBatch = this.scene.getOrCreatePartialBatch(sourceBatchKey, colorKey, visibleIds, device, this.pipeline, this._partialBatchEpoch);
                         if (subBatch) {
                             // Use opaque or transparent pipeline based on resolved alpha
                             // (not the parent batch's color[3] — that ignores transparencyOverrides).
@@ -2404,30 +2612,20 @@ export class Renderer {
             // buffers is deferred past in-flight work by WebGPU.
             this.scene.enforceGpuBudget();
             // Pop validation error scope and capture the exact error
-            if (captureGpuError) {
-                device.popErrorScope().then((error) => {
-                    if (error) {
-                        const msg = error.message || String(error);
-                        console.error('[WebGPU] Validation error in render pass:', msg);
-                        this.device._lastUncapturedError = `VALIDATION: ${msg}`;
-                        this.device._uncapturedErrorCount++;
-                    }
-                }).catch((error) => {
-                    // popErrorScope() rejects (e.g. "Instance dropped in popErrorScope")
-                    // when the GPU device is lost while the scope is still pending. This
-                    // escapes the surrounding synchronous try/catch and would otherwise
-                    // surface as an unhandled rejection. Treat it like any other device
-                    // loss: invalidate the context so it reconfigures next frame.
-                    this.device.invalidateContext();
-                    const now = performance.now();
-                    if (now - this.lastRenderErrorTime > this.RENDER_ERROR_THROTTLE_MS) {
-                        this.lastRenderErrorTime = now;
-                        console.warn('[WebGPU] popErrorScope rejected (device likely lost):', error);
-                    }
-                });
+            if (errorScopePushed) {
+                errorScopePushed = false;
+                this.drainErrorScope(device);
             }
         }
         catch (error) {
+            // Balance the validation scope if we threw before popping it above —
+            // an unpopped scope would capture every later frame's errors silently.
+            // drainErrorScope logs a pop rejection (device loss) rather than
+            // swallowing it.
+            if (errorScopePushed) {
+                errorScopePushed = false;
+                this.drainErrorScope(device);
+            }
             this._renderErrorCount++;
             this._lastRenderError = error instanceof Error ? error.message : String(error);
             // Handle WebGPU errors (e.g., device lost, invalid state)
@@ -2943,6 +3141,13 @@ export class Renderer {
         this.deviationBvhFingerprint = null;
         // Snap detector geometry cache
         this.raycastEngine.clearCaches();
+        // Finally, release the GPU device itself. Every buffer/pipeline/texture
+        // above was created from it and has already been destroyed, so nothing
+        // will touch the device after this. Without it, an app that spins up a
+        // renderer per model keeps N live devices (and their VRAM) alive. The
+        // lost-handler special-cases reason 'destroyed' so this is not reported
+        // as a fault. render() early-returns while the device is uninitialised.
+        this.device.destroy();
     }
     /**
      * Get the canvas element