@ifc-lite/renderer 1.43.0 → 1.44.0

package/dist/index.js

@@ -11,6 +11,13 @@ export { pickFitPolicy } from './camera-fit-policy.js';
 export { Scene } from './scene.js';
 export { Picker } from './picker.js';
 export { MathUtils } from './math.js';
+// The orthonormal camera basis `MathUtils.lookAt` renders through, exposed so
+// that a consumer which has to reconstruct the on-screen frame outside the
+// renderer derives it from the same substitution the picture used, instead of
+// recomputing `cross(forward, up)` and inventing its own answer for a
+// degenerate `up` (#2467 made this call inside the package; the Cesium overlay
+// is the same situation from outside it).
+export { viewBasis } from './math.js';
 export { SectionPlaneRenderer } from './section-plane.js';
 export { Section2DOverlayRenderer } from './section-2d-overlay.js';
 // IfcAnnotation overlay pipelines (3D world-space). Self-contained — caller
@@ -47,7 +54,7 @@ import { RenderPipeline } from './pipeline.js';
 import { Camera } from './camera.js';
 import { Scene } from './scene.js';
 import { Picker } from './picker.js';
-import { MathUtils } from './math.js';
+import { MathUtils, viewBasis } from './math.js';
 import { FrustumUtils } from '@ifc-lite/spatial';
 import { VisualEnhancementResolver } from './visual-enhancement.js';
 import { packClipBox } from './clip-box.js';
@@ -127,6 +134,33 @@ function computeBvhFingerprint(meshes) {
 function isDeviceLossThrow(error) {
     return typeof DOMException !== 'undefined' && error instanceof DOMException;
 }
+/**
+ * The reason `whenReady()` rejects when the renderer is destroyed.
+ *
+ * A plain `Error` carrying a stable `name` rather than an exported subclass:
+ * consumers can discriminate it with `err.name === 'RendererDestroyedError'`
+ * without this package growing a new export (and without `instanceof` breaking
+ * across duplicated copies of the package).
+ */
+function rendererDestroyedError() {
+    const error = new Error('Renderer was destroyed before it became ready');
+    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
  */
@@ -165,9 +199,28 @@ export class Renderer {
         highQuality: true,
     };
     pointCloudRenderer = null;
-    /** Set true at the end of `init()`; gates `whenReady()`. */
+    /**
+     * 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
+     * land in the middle of the init that is about to set it.
+     */
     ready = false;
     readyWaiters = [];
+    /**
+     * Set by the public `destroy()`, cleared synchronously by `init()`. It is
+     * the difference between "not ready YET" and "never going to be ready":
+     * `whenReady()` parks for the first and rejects for the second.
+     *
+     * Without it a caller parked across the teardown waits forever, because
+     * nothing after `destroy()` will ever reach `markReady()` — the host's
+     * remount builds a NEW Renderer rather than re-initialising this one. The
+     * private `teardown()` deliberately does NOT set it: the teardown
+     * `initOnce()` runs on the previous init's objects is part of an init that
+     * IS going to publish readiness, and its waiters must survive to be flushed.
+     */
+    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
@@ -177,12 +230,33 @@ export class Renderer {
      * caller) so one failure does not deadlock every later call.
      */
     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.
+     *
+     * 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
+     * turn; that later call is about to tear down everything the earlier one
+     * built, so the earlier one must not publish readiness. And a host that calls
+     * `destroy()` while an init is parked on `await device.init(...)` gets the
+     * same hazard from the other direction: without the bump that init resumes,
+     * allocates a full replacement GPU stack nothing references, and re-publishes
+     * `ready` against a renderer that has already been torn down (#2465).
+     *
+     * The teardown `initOnce()` runs as part of its OWN re-init deliberately does
+     * NOT bump it — see `destroy()` vs `teardown()`. Bumping there would make
+     * every re-init invalidate itself, and nothing would ever become ready again.
+     */
+    initGeneration = 0;
     /**
      * 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.
+     * and the renderer stops reporting itself ready (`isReady()` goes false,
+     * `whenReady()` rejects) until the host re-initialises it. Consumers learn
+     * of this via `onDeviceLost` and typically respond by reloading the model.
      *
      * Two signals set it: the async `device.lost` promise (Chromium), and a
      * frame throwing a `DOMException` out of `render()` (Safari 26.5, which
@@ -192,6 +266,29 @@ export class Renderer {
      * device, and it must cost one frame, not the session.
      */
     deviceLost = false;
+    /**
+     * The lifecycle generation the latched loss belongs to (see
+     * `initGeneration`); null until the first loss, and never cleared
+     * afterwards. It is only ever read next to `deviceLost`, which is what
+     * makes a stale stamp harmless — and that pairing is required, not
+     * cosmetic: a loss that latched between `init()` bumping the generation and
+     * its queued body running is stamped with the CURRENT generation, and only
+     * the flag that body clears says the renderer has moved on.
+     *
+     * `whenReady()` rejects only while this still equals the CURRENT generation,
+     * which is what re-arms the wait the instant a host calls `init()` — before
+     * the queued body has had a chance to clear `deviceLost` itself. Without
+     * that, `renderer.init(); await renderer.whenReady();` — the recovery shape
+     * `init()` already revokes readiness synchronously for — would reject inside
+     * the microtask window on a renderer that is being brought back up.
+     *
+     * Scoping it here rather than clearing `deviceLost` in `init()` keeps the
+     * flag meaning exactly one thing everywhere else: `render()`, the pick path
+     * and `getGPUDevice()` must stay shut for the OLD device across that same
+     * window, and clearing early would let frames run against dead GPU objects
+     * (and, on Safari, re-latch and re-notify the loss they already reported).
+     */
+    deviceLostGeneration = null;
     /** Retained so a listener registered AFTER the loss still learns of it. */
     deviceLostInfo = null;
     deviceLostListeners = new Set();
@@ -353,31 +450,62 @@ export class Renderer {
      * rather than adding a second, differently-shaped rule.
      */
     async init() {
+        // Revoke readiness SYNCHRONOUSLY, before the body is queued. Everything
+        // below runs in a later microtask (or, for a queued call, only after the
+        // one ahead of it settles), so leaving `ready` set would let
+        // `renderer.init(); await renderer.whenReady();` resolve immediately
+        // against the GPU objects this init is about to destroy — the very
+        // hazard the re-arm inside `initOnce()` exists to prevent. On a first
+        // init there is nothing to invalidate and this is a no-op.
+        const generation = ++this.initGeneration;
+        this.ready = false;
+        // Re-arm `whenReady()`: this instance is being brought back up, so a
+        // wait requested from here on is "not ready yet" again, not "destroyed".
+        this.destroyed = false;
         // A previous init that REJECTED must not block the next one, so the
         // stored link swallows the outcome. The caller still receives `run`, so
         // rejections continue to surface exactly as before.
-        const run = this.initChain.then(() => this.initOnce(), () => this.initOnce());
+        const run = this.initChain.then(() => this.initOnce(generation), () => this.initOnce(generation));
         this.initChain = run.then(() => undefined, () => undefined);
         return run;
     }
-    async initOnce() {
+    async initOnce(generation) {
         // `pipeline` is the marker for "a previous init() completed": it is
         // assigned unconditionally there and nulled by destroy().
         if (this.pipeline !== null) {
-            this.destroy();
-            // destroy() releases the device the previous init() resolved on, so
-            // `whenReady()` must go back to waiting rather than resolve against
-            // GPU objects that no longer exist.
-            this.ready = false;
+            // Release the device the previous init() resolved on, and re-arm
+            // `whenReady()` so it cannot resolve against GPU objects that no
+            // longer exist. `teardown()`, not the public `destroy()`: this
+            // teardown is part of THIS init, so it must not invalidate this
+            // init's own generation.
+            this.teardown();
         }
         // 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 also releases `whenReady()`'s rejection for the one case the
+        // generation stamp cannot: a loss that latched between `init()` bumping
+        // 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);
+        // 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
+        // pipelines, the EDL pass, the overlay glyph atlas — and this aborted
+        // path runs no second teardown, so all of it would be orphaned outright
+        // (#2465). `markReady()`'s generation check is not enough on its own: it
+        // withholds the readiness PUBLICATION, not the allocation. Release the
+        // device we just brought up and stop here; a queued init will bring up
+        // its own.
+        if (generation !== this.initGeneration) {
+            this.device.destroy();
+            return;
+        }
         // 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
         // can't overflow on tall/wide layouts (see render() for the per-frame clamp).
@@ -441,7 +569,7 @@ 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();
+        this.markReady(generation);
     }
     /**
      * Resolves once `init()` has finished and the GPU device + point-cloud
@@ -450,25 +578,80 @@ export class Renderer {
      * the async WebGPU init resolves — should `await renderer.whenReady()`
      * before `beginPointCloudStream`, which otherwise throws
      * "Renderer not initialized".
+     *
+     * REJECTS (with an `Error` whose `name` is `RendererDestroyedError`) if
+     * `destroy()` runs while the caller is waiting, or if it already ran and no
+     * `init()` has been started since. It never resolves against a destroyed
+     * renderer — that is what this method exists to prevent — so the only
+     * alternative would be a promise that never settles, which suspends the
+     * caller's async frame permanently and takes everything the frame captured
+     * with it. The viewer reaches that state on an ordinary path: `Viewport`
+     * builds a NEW `Renderer` per mount and destroys the old one in its effect
+     * cleanup, so a `destroy()` there is FINAL for the instance a consumer
+     * captured — a point-cloud drop that straddles a layout swap or a
+     * StrictMode remount would otherwise hang mid-load, with no error, forever.
+     * Callers should handle the rejection as "the target went away", not as a
+     * load failure.
+     *
+     * It also REJECTS (`RendererDeviceLostError`) while the GPU device is lost.
+     * The device is what this method promises, and a lost one cannot serve the
+     * call the caller is waiting to make — `getGPUDevice()` returns null, so
+     * `beginPointCloudStream` throws "Renderer not initialized" the moment the
+     * wait resolves. The third outcome is the one `destroy()` already ruled out:
+     * parking a waiter that only a host-initiated `init()` could ever settle,
+     * and that the viewer's usual response to a loss (drop this renderer, build
+     * a new one) guarantees will never come. Unlike the destroyed case this is
+     * NOT final — a later `init()` on the same instance re-arms the wait
+     * synchronously, so "retry after re-init" is a contract callers can act on,
+     * which is why the two rejections carry different names.
      */
     whenReady() {
+        // Checked before `ready`, which an init that completed after the loss
+        // latched may well have published (`init()` subscribes to the device's
+        // loss signal before awaiting it, so a loss DURING init leaves both
+        // flags set). Readiness is about the device, and the device is gone.
+        if (this.deviceLost && this.deviceLostGeneration === this.initGeneration) {
+            return Promise.reject(rendererDeviceLostError());
+        }
         if (this.ready)
             return Promise.resolve();
-        return new Promise((resolve) => { this.readyWaiters.push(resolve); });
-    }
-    markReady() {
+        if (this.destroyed)
+            return Promise.reject(rendererDestroyedError());
+        return new Promise((resolve, reject) => { this.readyWaiters.push({ resolve, reject }); });
+    }
+    markReady(generation) {
+        // A newer init() is already queued: it will tear all of this down before
+        // building its own, so publishing readiness here would hand callers a
+        // device with a demolition order on it.
+        if (generation !== this.initGeneration)
+            return;
         this.ready = true;
         const waiters = this.readyWaiters;
         this.readyWaiters = [];
         for (const w of waiters)
-            w();
+            w.resolve();
+    }
+    /**
+     * Fail every parked `whenReady()` waiter with `error`. Called by `destroy()`
+     * and by `handleDeviceLost()` — the two events after which nothing this
+     * instance does on its own can make the wait true. NOT by `teardown()`,
+     * whose waiters belong to the re-init running it and must survive to be
+     * flushed by it.
+     */
+    rejectReadyWaiters(error) {
+        const waiters = this.readyWaiters;
+        this.readyWaiters = [];
+        for (const w of waiters)
+            w.reject(error);
     }
     /**
      * 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.
+     * device. After it fires, `render()` is a no-op and the renderer reports
+     * itself un-ready (`isReady()` false, `whenReady()` rejecting with
+     * `RendererDeviceLostError`) until it 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
@@ -522,8 +705,17 @@ export class Renderer {
         if (this.deviceLost)
             return;
         this.deviceLost = true;
+        this.deviceLostGeneration = this.initGeneration;
         this.deviceLostInfo = info;
         console.warn('[Renderer] GPU device lost — halting rendering until re-init:', info.message);
+        // Readiness describes the GPU objects, and every one of them just died:
+        // `isReady()` reports it from here on, and anyone parked in
+        // `whenReady()` is failed rather than left to be resolved by the init
+        // this loss may have landed in the middle of. Done BEFORE the listeners
+        // run, so a listener that recovers by calling `init()` synchronously
+        // finds the waiters already settled and re-arms the wait for the next
+        // caller rather than racing the flush.
+        this.rejectReadyWaiters(rendererDeviceLostError());
         for (const listener of this.deviceLostListeners) {
             try {
                 listener(info);
@@ -1746,31 +1938,22 @@ export class Renderer {
                         sampleCount: this.pipeline.getSampleCount(),
                     }, skyShaderSource);
                 }
-                const camPos = this.camera.getPosition();
-                const camTgt = this.camera.getTarget();
-                const camUp = this.camera.getUp();
-                let fx = camTgt.x - camPos.x;
-                let fy = camTgt.y - camPos.y;
-                let fz = camTgt.z - camPos.z;
-                const flen = Math.hypot(fx, fy, fz) || 1;
-                fx /= flen;
-                fy /= flen;
-                fz /= flen;
-                // Right = normalize(cross(forward, up)); true up = cross(right, forward).
-                let rx = fy * camUp.z - fz * camUp.y;
-                let ry = fz * camUp.x - fx * camUp.z;
-                let rz = fx * camUp.y - fy * camUp.x;
-                const rlen = Math.hypot(rx, ry, rz) || 1;
-                rx /= rlen;
-                ry /= rlen;
-                rz /= rlen;
-                const ux = ry * fz - rz * fy;
-                const uy = rz * fx - rx * fz;
-                const uz = rx * fy - ry * fx;
+                // The sky shader rebuilds a per-pixel view ray from this
+                // basis, so it must be the basis the frame's view matrix was
+                // built from — `viewBasis`, not a local re-derivation
+                // (#2489). The copy that used to live here guarded its two
+                // divisors with `|| 1` and neither numerator, so a non-finite
+                // camera coordinate made every axis NaN and the sky drew as a
+                // flat undefined colour over the whole viewport; and for a
+                // plan pose (`up` parallel to the view direction) it returned
+                // zero-length axes, which is the same picture. Reading the
+                // shared basis also keeps the horizon in the sky aligned with
+                // the horizon in the geometry for free.
+                const camBasis = viewBasis(this.camera.getPosition(), this.camera.getTarget(), this.camera.getUp());
                 this.skyPass.draw(pass, {
-                    forward: [fx, fy, fz],
-                    right: [rx, ry, rz],
-                    up: [ux, uy, uz],
+                    forward: [camBasis.forward.x, camBasis.forward.y, camBasis.forward.z],
+                    right: [camBasis.right.x, camBasis.right.y, camBasis.right.z],
+                    up: [camBasis.up.x, camBasis.up.y, camBasis.up.z],
                     fovY: this.camera.getFOV(),
                     aspect: this.canvas.height > 0 ? this.canvas.width / this.canvas.height : 1,
                 }, environment);
@@ -2772,6 +2955,17 @@ export class Renderer {
      * Resize canvas
      */
     resize(width, height) {
+        // `canvas.width` is an IDL `unsigned long`, so it silently coerces a
+        // non-finite or negative argument to **0** — a zero drawing buffer
+        // that every pick guard in this package misses, because they all
+        // check the bounding rect rather than the buffer. `unprojectToRay`
+        // then divides by it. This is documented public API of a published
+        // package (`docs/api/typescript.md`), so an external caller wiring a
+        // ResizeObserver to it is the reachable route; both in-repo callers
+        // already floor their own values. Keep the last usable size, the same
+        // policy `setAspect` uses for the ratio it derives (#2473).
+        if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0)
+            return;
         this.canvas.width = width;
         this.canvas.height = height;
         this.camera.setAspect(width / height);
@@ -2926,10 +3120,27 @@ export class Renderer {
         return this.pipeline;
     }
     /**
-     * Check if renderer is fully initialized and ready to use
+     * Check if renderer is fully initialized and ready to use.
+     *
+     * `ready` is part of the test, not decoration: between `init()` being called
+     * and its queued body running, the device and pipeline still belong to the
+     * PREVIOUS init and are about to be destroyed, so the other two conditions
+     * alone would report a renderer that is on its way out as usable.
+     *
+     * So is the device-loss check. A lost device is never torn down —
+     * `WebGPUDevice.destroy()` is the only thing that nulls the handle and an
+     * involuntary loss (driver reset / VRAM exhaustion / GPU-process crash)
+     * never calls it — so `isInitialized()` stays true, the pipeline stays
+     * non-null, and `ready` stays set from the init that completed before the
+     * loss. All three conditions therefore still hold while `render()` is a
+     * no-op and `getGPUDevice()` returns null: the renderer would report itself
+     * usable through this third door alone. Unlike the two revocations above
+     * this one needs no generation scoping — an `init()` clears `ready`
+     * synchronously, so a latch left standing until the queued body clears it
+     * cannot make this method spuriously false in the meantime.
      */
     isReady() {
-        return this.device.isInitialized() && this.pipeline !== null;
+        return this.ready && !this.deviceLost && this.device.isInitialized() && this.pipeline !== null;
     }
     /**
      * Get the GPU device (returns null if not initialized, or if the device
@@ -2985,8 +3196,46 @@ export class Renderer {
      * 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).
+     *
+     * An `init()` still in flight is invalidated too. It is parked on
+     * `await device.init(...)`, and without the generation bump below it resumes
+     * after this returns, allocates a complete replacement GPU stack that nothing
+     * references, and re-publishes `ready` — resolving `whenReady()` waiters
+     * against a renderer the host has already torn down (#2465). The bump is what
+     * `initOnce()` re-checks after its await, and what makes `markReady()` refuse
+     * the stale completion.
+     *
+     * This is why the teardown itself lives in `teardown()`: `initOnce()` runs it
+     * on the PREVIOUS init's objects as part of its own re-init, and routing that
+     * through here would have every init invalidate its own generation, leaving
+     * `whenReady()` pending forever.
+     *
+     * Anyone parked in `whenReady()` is FAILED rather than left pending. Nothing
+     * after this call can make the wait true — the invalidation above is exactly
+     * what stops the in-flight init from publishing readiness, and a host that
+     * remounts builds a new `Renderer` rather than re-initialising this one — so
+     * leaving the promise unsettled suspends the caller's async frame for the
+     * lifetime of the page. `apps/viewer`'s point-cloud drop is one of those
+     * frames: it captured this instance before the teardown, and would stop
+     * mid-load with the spinner still up and no error to report. See
+     * `whenReady()` for the rejection contract.
      */
     destroy() {
+        this.initGeneration++;
+        this.destroyed = true;
+        this.teardown();
+        this.rejectReadyWaiters(rendererDestroyedError());
+    }
+    /**
+     * Release every GPU object this renderer owns, WITHOUT invalidating an
+     * in-flight init. Callers: the public `destroy()` (which invalidates first)
+     * and `initOnce()`, tearing down the previous init before building its own.
+     */
+    teardown() {
+        // 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.