@ifc-lite/renderer 3.0.1 → 3.2.0

package/dist/index.js

@@ -39,6 +39,7 @@ export { LINE_OVERLAY_CHANNELS } from './section-2d-overlay.js';
 export { Raycaster } from './raycaster.js';
 export { SnapDetector, SnapType } from './snap-detector.js';
 export { BVH } from './bvh.js';
+export { hostsOtherEntities } from './mesh-entity-hosting.js';
 export { FederationRegistry, federationRegistry } from './federation-registry.js';
 export * from './types.js';
 export { resolveEnvironment, deriveSkyGradient, packEnvironmentUniforms, ENVIRONMENT_UNIFORM_SIZE, } from './environment.js';
@@ -105,44 +106,10 @@ import { PartialBatchRequests } from './partial-batch-requests.js';
 import { colorSaltByte, packEntityLane } from './scene-geometry.js';
 import { PointCloudRenderer } from './pointcloud/point-cloud-renderer.js';
 import { DeviationComputer } from './deviation/deviation-computer.js';
+import { runGuardedGpuUpload, isDeviceLossThrow } from './gpu-upload-guard.js';
+import { recoverRendererDevice, rendererDeviceLostError } from './device-recovery.js';
 const MAX_ENCODED_ENTITY_ID = 0xFFFFFF;
 let warnedEntityIdRange = false;
-/**
- * Is this throw the GPU device telling us it is gone?
- *
- * The discriminator is the exception TYPE, not its message, because WebGPU
- * draws exactly that line:
- *  - a call on a dead / invalid-state device throws a `DOMException`
- *    (`InvalidStateError` in Safari 26.5 — the whole of issue #2229);
- *  - a buffer allocation the host cannot back throws a plain `RangeError`
- *    ("createBuffer failed, size (…) is too large … when mappedAtCreation ==
- *    true"), which `gpu-upload-guard` documents happening on a HEALTHY device
- *    under memory pressure.
- *
- * Treating the second as a device loss is a false positive that costs the whole
- * session, so only the first latches; everything else degrades one frame.
- *
- * There is deliberately NO consecutive-failure threshold as a middle ground.
- * Not because failures necessarily arrive back-to-back — between two BCF / IDS
- * capture frames the awaited `camera.frameBounds` normally does let an ordinary
- * rAF frame through, which would reset a counter — but because those ordinary
- * frames are not guaranteed to SUCCEED: they allocate too (`ensureMeshResources`
- * creates a buffer per unresourced mesh, and the queued-mesh flush allocates),
- * so under sustained host memory pressure any finite budget is still reachable.
- * A latch whose safety depends on incidental animation timing is the wrong
- * shape of guarantee for "never kill the viewport by mistake".
- *
- * Real losses on browsers that do not throw are still caught by the async
- * `device.lost` promise — which the WebGPU spec makes the sole loss channel
- * anyway (on a conformant engine, calls against a lost device are no-ops, not
- * throws; Safari 26.5's synchronous throw is the deviation being handled here).
- *
- * `typeof` guarded because non-DOM hosts (Node before 17, some workers) have no
- * `DOMException` global; there, no throw can be a WebGPU device signal anyway.
- */
-function isDeviceLossThrow(error) {
-    return typeof DOMException !== 'undefined' && error instanceof DOMException;
-}
 /**
  * The reason `whenReady()` rejects when the renderer is destroyed.
  *
@@ -156,20 +123,6 @@ function rendererDestroyedError() {
     error.name = 'RendererDestroyedError';
     return error;
 }
-/**
- * The reason `whenReady()` rejects once the GPU device has been lost.
- *
- * Deliberately NOT `RendererDestroyedError`: a destroyed renderer is finished,
- * while a lost one is dead only until the host re-initialises it (`init()`
- * clears the latch and readiness is published again). A caller that wants to
- * retry needs to tell those apart, so the loss carries its own `name` — same
- * plain-`Error` shape, for the same reasons.
- */
-function rendererDeviceLostError() {
-    const error = new Error('GPU device was lost before the renderer became ready');
-    error.name = 'RendererDeviceLostError';
-    return error;
-}
 /**
  * Main renderer class
  */
@@ -218,8 +171,9 @@ export class Renderer {
         highQuality: true,
     };
     pointCloudRenderer = null;
-    /**
-     * Set true at the end of the LATEST `init()`; gates `whenReady()` and
+    pointCloudStreamEpoch = 0;
+    pointCloudStreamEpochs = new Map(); // handle id → epoch; cleanup rebuilds `{ id }`, cleared per epoch
+    /** Set true at the end of the LATEST `init()`; gates `whenReady()` and
      * `isReady()`. Revoked synchronously by `init()` and by `destroy()`, and
      * overridden (not cleared) by a device loss — see `deviceLost`, which the
      * two readiness methods consult alongside this flag because the loss can
@@ -241,19 +195,18 @@ export class Renderer {
      */
     destroyed = false;
     /**
-     * The tail of the `init()` queue. `init()` chains onto this rather than
-     * running immediately, so two overlapping calls cannot both walk past the
-     * "a previous init completed" guard while the first is still awaiting its
-     * device and both allocate a full set of GPU objects (#2448). Always
-     * settled fulfilled — a rejected init is swallowed HERE (never for the
-     * caller) so one failure does not deadlock every later call.
+     * The tail of the GPU lifecycle queue. `init()` and `recoverDevice()` chain
+     * onto this rather than running immediately, so overlapping calls cannot
+     * both mutate the shared device/pipeline fields while one is awaiting its
+     * adapter. Always settled fulfilled — a rejected operation is swallowed
+     * HERE (never for its caller) so one failure cannot deadlock later work.
      */
     initChain = Promise.resolve();
     /**
-     * Incremented synchronously by every `init()` call AND by every public
-     * `destroy()`. It stamps "the lifecycle event an in-flight init belongs to":
-     * an init that no longer carries the current stamp has been superseded and
-     * must neither allocate nor publish readiness.
+     * Incremented synchronously by every `init()` / `recoverDevice()` call and
+     * by every public `destroy()`. It stamps the lifecycle event an in-flight
+     * operation belongs to: stale work must neither allocate nor publish
+     * readiness.
      *
      * Both bumps are load-bearing, for the same reason. Because the queue above
      * defers the body, an init can finish while a later one is still waiting its
@@ -311,6 +264,10 @@ export class Renderer {
     /** Retained so a listener registered AFTER the loss still learns of it. */
     deviceLostInfo = null;
     deviceLostListeners = new Set();
+    deviceLossSequence = 0;
+    recovery = {
+        inFlight: null, lostReferenceImages: false, quantizedBatchesRequested: false, omissions: new Set(), pointCloudOptions: null,
+    };
     /** BIM ↔ scan deviation: owns the compute pipeline + its BVH cache. */
     deviationComputer = new DeviationComputer();
     visualEnhancementResolver = new VisualEnhancementResolver();
@@ -485,7 +442,7 @@ export class Renderer {
         this.initChain = run.then(() => undefined, () => undefined);
         return run;
     }
-    async initOnce(generation) {
+    async initOnce(generation, options = {}) {
         // `pipeline` is the marker for "a previous init() completed": it is
         // assigned unconditionally there and nulled by destroy().
         if (this.pipeline !== null) {
@@ -503,12 +460,17 @@ export class Renderer {
         // the generation and this body running is stamped with the generation
         // that is clearing it. `deviceLostGeneration` deliberately keeps its
         // stale value — it is only ever read alongside this flag.
-        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);
+        if (options.clearDeviceLost !== false)
+            this.deviceLost = false;
+        // Subscribe before init so a loss during the first frames is not missed.
+        const initializingDevice = this.device;
+        initializingDevice.onDeviceLost((info) => {
+            // Ignore a delayed loss from a wrapper recovery already replaced.
+            if (this.device !== initializingDevice)
+                return;
+            this.handleDeviceLost(info, { fromDevicePromise: true });
+        });
+        await initializingDevice.init(this.canvas);
         // A `destroy()` (or a newer `init()`) landed while we were parked on the
         // device. Everything below allocates a full GPU stack — two pipelines,
         // the picker, the post-processor, the point-cloud and deviation
@@ -586,7 +548,8 @@ export class Renderer {
         // from the GPU click-pick provider above, since raycastScene* is
         // synchronous CPU code while pick() is an async GPU readback.
         this.raycastEngine.setPointCloudProvider(() => this.pointCloudRenderer?.getRayQuerySources() ?? []);
-        this.markReady(generation);
+        if (options.publishReady !== false)
+            this.markReady(generation);
     }
     /**
      * Resolves once `init()` has finished and the GPU device + point-cloud
@@ -718,10 +681,33 @@ export class Renderer {
     isDeviceLost() {
         return this.deviceLost;
     }
-    handleDeviceLost(info) {
-        if (this.deviceLost)
+    recoverDevice() {
+        return recoverRendererDevice(this);
+    }
+    /**
+     * `onLossDetected` for every `runGuardedGpuUpload` call below (#4885):
+     * a synchronous Safari-style `DOMException` (issue #2229) caught OUTSIDE
+     * `render()` never otherwise reaches `handleDeviceLost` — only the async
+     * `device.lost` promise and `render()`'s own catch do — so without this,
+     * `isDeviceLost()` would keep answering false and every later upload on
+     * this path would keep failing against the same dead device.
+     */
+    reportUploadLoss(error) {
+        this.handleDeviceLost({
+            message: error instanceof Error ? error.message : String(error),
+            reason: 'gpu-upload-exception',
+        });
+    }
+    handleDeviceLost(info, options = {}) {
+        // Latched: only the current device's `device.lost` signal is a replacement loss; anything else is a duplicate report.
+        if (this.deviceLost) {
+            if (options.fromDevicePromise)
+                this.deviceLossSequence++;
             return;
+        }
+        this.deviceLossSequence++;
         this.deviceLost = true;
+        this.recovery.lostReferenceImages = this.referenceImages.hasImages();
         this.referenceImages.destroy();
         this.deviceLostGeneration = this.initGeneration;
         this.deviceLostInfo = info;
@@ -893,24 +879,34 @@ export class Renderer {
      * chunks will arrive (currently a no-op but kept for symmetry).
      */
     beginPointCloudStream(meta) {
+        if (this.deviceLost)
+            throw rendererDeviceLostError();
         if (!this.pointCloudRenderer) {
             throw new Error('Renderer not initialized. Call init() first.');
         }
-        return this.pointCloudRenderer.beginAsset(meta);
+        const handle = this.pointCloudRenderer.beginAsset(meta);
+        this.pointCloudStreamEpochs.set(handle.id, this.pointCloudStreamEpoch);
+        return handle;
+    }
+    currentPointCloudStreamRenderer(handle) {
+        if (this.deviceLost || !this.pointCloudRenderer
+            || this.pointCloudStreamEpochs.get(handle.id) !== this.pointCloudStreamEpoch)
+            throw rendererDeviceLostError();
+        return this.pointCloudRenderer;
     }
     appendPointCloudChunk(handle, chunk) {
-        if (!this.pointCloudRenderer)
-            return;
-        this.pointCloudRenderer.appendChunk(handle, chunk);
+        this.currentPointCloudStreamRenderer(handle).appendChunk(handle, chunk);
         this.modelBoundsTracker.expandForPointClouds();
         this.camera.setSceneBounds(this.modelBounds);
         this.requestRender();
     }
     endPointCloudStream(handle) {
-        this.pointCloudRenderer?.endAsset(handle);
+        this.currentPointCloudStreamRenderer(handle).endAsset(handle);
         this.requestRender();
     }
     removePointCloudAsset(handle) {
+        if (!this.pointCloudStreamEpochs.delete(handle.id))
+            return;
         this.pointCloudRenderer?.removeAsset(handle);
         // Bounds may have shrunk — recompute from scratch so fit-to-view
         // and section-plane sliders see fresh extents.
@@ -947,6 +943,15 @@ export class Renderer {
         this.clearCaches();
         this.refreshPlacementBounds();
     }
+    /** Absolute workspace yaw about the render-frame pivot; GPU-instanced only (#4890). Skips invalidation on a no-op (#4890 review). */
+    setModelRotation(modelIndex, angle, pivot) {
+        const changed = this.scene.setModelRotation(modelIndex, angle, pivot);
+        if (!changed)
+            return false;
+        this.clearCaches();
+        this.refreshPlacementBounds();
+        return true;
+    }
     /** Streamed clouds are addressed by durable asset handle. */
     setPointCloudTranslation(handle, translation) {
         this.pointCloudRenderer?.setAssetTranslation(handle, translation);
@@ -1011,22 +1016,26 @@ export class Renderer {
      * @param geometry - Either a GeometryResult from geometry.process() or an array of MeshData
      */
     loadGeometry(geometry) {
-        if (!this.device.isInitialized() || !this.pipeline) {
+        if (this.isDeviceLost())
+            return { ok: false, reason: 'device-lost' }; // #4885: zombie device stays "initialized"
+        if (!this.device.isInitialized() || !this.pipeline)
             throw new Error('Renderer not initialized. Call init() first.');
-        }
         const meshes = Array.isArray(geometry) ? geometry : geometry.meshes;
         if (meshes.length === 0) {
             console.warn('[Renderer] loadGeometry called with empty mesh array');
-            return;
+            return { ok: true, value: undefined };
         }
-        // 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.modelBoundsTracker.updateFromMeshes(meshes, (index) => this.scene.getModelTranslation(index));
-        console.log(`[Renderer] Loaded ${meshes.length} meshes`);
-        // Update camera scene bounds for tight orthographic near/far planes
-        this.camera.setSceneBounds(this.modelBounds);
+        const pipeline = this.pipeline;
+        return runGuardedGpuUpload(() => this.isDeviceLost(), () => {
+            // Use batched rendering for optimal performance
+            const device = this.device.getDevice();
+            this.scene.appendToBatches(meshes, device, pipeline, false);
+            // Calculate and store model bounds for fitToView
+            this.modelBoundsTracker.updateFromMeshes(meshes, (index) => this.scene.getModelTranslation(index));
+            console.log(`[Renderer] Loaded ${meshes.length} meshes`);
+            // Update camera scene bounds for tight orthographic near/far planes
+            this.camera.setSceneBounds(this.modelBounds);
+        }, (error) => this.reportUploadLoss(error));
     }
     /**
      * Add multiple meshes to the scene (convenience method for streaming)
@@ -1035,17 +1044,20 @@ export class Renderer {
      * @param isStreaming - If true, throttles batch rebuilding for better streaming performance
      */
     addMeshes(meshes, isStreaming = false) {
+        if (this.isDeviceLost())
+            return { ok: false, reason: 'device-lost' };
         if (!this.device.isInitialized() || !this.pipeline) {
             throw new Error('Renderer not initialized. Call init() first.');
         }
         if (meshes.length === 0)
-            return;
-        const device = this.device.getDevice();
-        this.scene.appendToBatches(meshes, device, this.pipeline, isStreaming);
-        // Update model bounds incrementally
-        this.modelBoundsTracker.updateFromMeshes(meshes, (index) => this.scene.getModelTranslation(index));
-        // Update camera scene bounds for tight orthographic near/far planes
-        this.camera.setSceneBounds(this.modelBounds);
+            return { ok: true, value: undefined };
+        const pipeline = this.pipeline;
+        return runGuardedGpuUpload(() => this.isDeviceLost(), () => {
+            const device = this.device.getDevice();
+            this.scene.appendToBatches(meshes, device, pipeline, isStreaming);
+            this.modelBoundsTracker.updateFromMeshes(meshes, (index) => this.scene.getModelTranslation(index));
+            this.camera.setSceneBounds(this.modelBounds);
+        }, (error) => this.reportUploadLoss(error));
     }
     /**
      * Fit camera to view all loaded geometry
@@ -1073,50 +1085,46 @@ export class Renderer {
      */
     addMesh(mesh) {
         if (!this.pipeline)
-            return;
-        // 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 },
-                    },
-                ],
-            });
-        }
+            return { ok: true, value: undefined };
+        const pipeline = this.pipeline;
+        const outcome = (!mesh.uniformBuffer && !this.isDeviceLost() && this.device.isInitialized())
+            ? runGuardedGpuUpload(() => this.isDeviceLost(), () => {
+                const device = this.device.getDevice();
+                mesh.uniformBuffer = device.createBuffer({
+                    size: pipeline.getUniformBufferSize(),
+                    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+                });
+                mesh.bindGroup = device.createBindGroup({
+                    layout: pipeline.getBindGroupLayout(),
+                    entries: [{ binding: 0, resource: { buffer: mesh.uniformBuffer } }],
+                });
+            }, (error) => this.reportUploadLoss(error))
+            : { ok: true, value: undefined };
         this.scene.addMesh(mesh);
+        return outcome;
     }
     /**
      * Ensure all meshes have GPU resources (call after adding meshes if pipeline wasn't ready)
      */
     ensureMeshResources() {
         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 },
-                        }],
-                });
+            return { ok: true, value: undefined };
+        const pipeline = this.pipeline;
+        return runGuardedGpuUpload(() => this.isDeviceLost(), () => {
+            const device = this.device.getDevice();
+            for (const mesh of this.scene.getMeshes()) {
+                if (!mesh.uniformBuffer) {
+                    mesh.uniformBuffer = device.createBuffer({
+                        size: pipeline.getUniformBufferSize(),
+                        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+                    });
+                    mesh.bindGroup = device.createBindGroup({
+                        layout: pipeline.getBindGroupLayout(),
+                        entries: [{ binding: 0, resource: { buffer: mesh.uniformBuffer } }],
+                    });
+                }
             }
-        }
+        }, (error) => this.reportUploadLoss(error));
     }
     /**
      * Get model bounds (used for section planes, fitToView, etc.)
@@ -1209,11 +1217,15 @@ export class Renderer {
             this.scene.recordBatchDrawn(batch);
         }
     }
+    /** Guarded entry point (#4885) for the unguarded body below. */
+    createMeshFromData(meshData) {
+        return runGuardedGpuUpload(() => this.isDeviceLost(), () => this.createMeshFromDataUnguarded(meshData), (error) => this.reportUploadLoss(error));
+    }
     /**
      * 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) {
+    createMeshFromDataUnguarded(meshData) {
         if (!this.device.isInitialized())
             return;
         const device = this.device.getDevice();
@@ -1230,7 +1242,7 @@ export class Renderer {
         // We compute the same `world` here. When there's no shared origin yet
         // (legacy / pre-batch), fall back to a plain f64 fold (local + origin).
         const o = meshData.origin;
-        const so = this.scene.getSharedFrameOrigin(meshData.modelIndex);
+        const so = this.scene.getSharedFrameOrigin(meshData.modelIndex, meshData);
         const ox = o ? o[0] : 0, oy = o ? o[1] : 0, oz = o ? o[2] : 0;
         const fr = Math.fround;
         const sox = so ? fr(so[0]) : null, soy = so ? fr(so[1]) : 0, soz = so ? fr(so[2]) : 0;
@@ -1415,6 +1427,7 @@ export class Renderer {
      * rejecting pipeline creation) batches stay on the f32 path.
      */
     async enableQuantizedBatches() {
+        this.recovery.quantizedBatchesRequested = true;
         if (!this.pipeline)
             return false;
         const ok = await this.pipeline.ensureQuantizedPipelines();
@@ -3043,8 +3056,8 @@ export class Renderer {
     }
     /** Stage one new owner; borrowed mesh buffers must remain immutable until disposal. */
     prepareAuthoredOwner(parts) {
-        if (!this.device.isInitialized() || !this.pipeline)
-            throw new Error('Renderer is not initialized.');
+        if (this.deviceLost || !this.device.isInitialized() || !this.pipeline)
+            throw this.deviceLost ? rendererDeviceLostError() : new Error('Renderer is not initialized.');
         const prepared = this.scene.prepareAuthoredOwner(parts, this.device.getDevice(), this.pipeline);
         return { commit: () => { prepared.commit(); this.refreshPlacementBounds(); this.invalidateBVHCache(); this.requestRender(); }, dispose: prepared.dispose };
     }
@@ -3305,15 +3318,17 @@ export class Renderer {
      * in-flight init. Callers: the public `destroy()` (which invalidates first)
      * and `initOnce()`, tearing down the previous init before building its own.
      */
-    teardown() {
+    teardown(clearScene = true) {
         // Nothing below survives this call, so `whenReady()` / `isReady()` must
         // go back to waiting. Set first: every release below is synchronous, but
         // the flag is what a caller holding a live reference actually reads.
         this.ready = false;
         // Scene mesh GPU buffers
-        this.scene.clear();
-        // Re-arm the section-bounds diagnostic log for the next model.
-        this._loggedSectionBounds = false;
+        if (clearScene) {
+            this.scene.clear();
+            // Re-arm the section-bounds diagnostic log for the next model.
+            this._loggedSectionBounds = false;
+        }
         // Render pipelines (textures + uniform buffers)
         this.pipeline?.destroy();
         this.pipeline = null;
@@ -3338,6 +3353,8 @@ export class Renderer {
         this.overlays.destroy();
         this.referenceImages.destroy();
         // Point cloud GPU resources
+        this.pointCloudStreamEpoch++;
+        this.pointCloudStreamEpochs.clear();
         this.pointCloudRenderer?.clear();
         this.pointCloudRenderer = null;
         // BIM ↔ scan deviation pipeline + cached BVH GPU buffers.