@ifc-lite/renderer 1.41.0 → 1.43.0

package/dist/index.js

@@ -13,7 +13,6 @@ export { Picker } from './picker.js';
 export { MathUtils } from './math.js';
 export { SectionPlaneRenderer } from './section-plane.js';
 export { Section2DOverlayRenderer } from './section-2d-overlay.js';
-import { aabbEdgeLineList } from './aabb-edges.js';
 // IfcAnnotation overlay pipelines (3D world-space). Self-contained — caller
 // passes a GPUDevice + presentation format and invokes `.render(pass, viewProj)`
 // from inside an RGBA-blended pass. See packages/renderer/src/symbolic-overlay-pipelines.ts.
@@ -50,16 +49,17 @@ import { Scene } from './scene.js';
 import { Picker } from './picker.js';
 import { MathUtils } from './math.js';
 import { FrustumUtils } from '@ifc-lite/spatial';
-import { SectionPlaneRenderer } from './section-plane.js';
+import { VisualEnhancementResolver } from './visual-enhancement.js';
 import { packClipBox } from './clip-box.js';
-import { Section2DOverlayRenderer } from './section-2d-overlay.js';
-import { SymbolicFillPipeline, SymbolicTextPipeline, } from './symbolic-overlay-pipelines.js';
-import { DEFAULT_CAP_STYLE, HATCH_PATTERN_IDS } from './section-cap-style.js';
+import { RendererOverlays } from './renderer-overlays.js';
+import { resolveSectionPlaneFrame } from './render-section-plane.js';
 import { PickingManager } from './picking-manager.js';
 import { RaycastEngine } from './raycast-engine.js';
+import { RenderDegradationMonitor } from './render-degradation.js';
 import { PostProcessor } from './post-processor.js';
 import { InteractionEffectsGovernor } from './interaction-effects-governor.js';
 import { VisibilityEpochTracker } from './visibility-epoch.js';
+import { ModelBoundsTracker } from './model-bounds-tracker.js';
 import { resolveContributionThresholdPx, projectedAabbRadiusPx, projectedInstancedRadiusPx } from './contribution-cull.js';
 import { EdlPass } from './edl-pass.js';
 import { SkyPass } from './sky-pass.js';
@@ -91,6 +91,42 @@ function computeBvhFingerprint(meshes) {
     }
     return parts.join('|');
 }
+/**
+ * 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;
+}
 /**
  * Main renderer class
  */
@@ -101,15 +137,21 @@ export class Renderer {
     scene;
     picker = null;
     canvas;
-    sectionPlaneRenderer = null;
-    section2DOverlayRenderer = null;
-    // Overlay/section-cut line colour, kept on the Renderer so it survives a
-    // pre-init call and a section2DOverlayRenderer re-creation (re-applied below).
-    overlayLineColor = [0, 0, 0, 1];
-    // IfcAnnotation overlay pipelines (issue #653). Created on `init()` once
-    // the device exists; nulled until then.
-    symbolicFillPipeline = null;
-    symbolicTextPipeline = null;
+    /**
+     * Section-plane gizmo, 2D section drawing/cap, and the standalone 3D line
+     * + symbolic annotation overlays (issue #2425). Created here rather than in
+     * `init()` so a pre-init `setOverlayLineColor` still lands — the GPU
+     * objects inside stay null until `init()` calls `overlays.init()`.
+     */
+    overlays = new RendererOverlays({
+        getModelBounds: () => this.getModelBounds(),
+        expandModelBoundsWithFlatVertices: (positions, stride) => this.modelBoundsTracker.expandWithFlatVertices(positions, stride),
+        syncCameraSceneBounds: () => {
+            if (this.modelBounds)
+                this.camera.setSceneBounds(this.modelBounds);
+        },
+        requestRender: () => this.requestRender(),
+    });
     postProcessor = null;
     interactionEffects = new InteractionEffectsGovernor();
     edlPass = null;
@@ -126,14 +168,32 @@ export class Renderer {
     /** Set true at the end of `init()`; gates `whenReady()`. */
     ready = false;
     readyWaiters = [];
+    /**
+     * 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.
+     */
+    initChain = Promise.resolve();
     /**
      * 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.
+     *
+     * Two signals set it: the async `device.lost` promise (Chromium), and a
+     * frame throwing a `DOMException` out of `render()` (Safari 26.5, which
+     * reports the loss synchronously — issue #2229). Whichever arrives first
+     * latches. A frame throwing anything else does NOT latch (see
+     * `isDeviceLossThrow`) — that class is host memory pressure on a live
+     * device, and it must cost one frame, not the session.
      */
     deviceLost = false;
+    /** Retained so a listener registered AFTER the loss still learns of it. */
+    deviceLostInfo = null;
     deviceLostListeners = new Set();
     deviationPipeline = null;
     /**
@@ -144,14 +204,20 @@ export class Renderer {
      * want to pay that on every slider drag.
      */
     deviationBvhFingerprint = null;
-    visualEnhancementState = {
-        enabled: true,
-        edgeContrast: { enabled: true, intensity: 1.0 },
-        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;
+    visualEnhancementResolver = new VisualEnhancementResolver();
+    // Model bounds for fitToView, section planes, camera. The value itself
+    // lives in ModelBoundsTracker (issue #2425) so the four writers — point
+    // cloud upload, mesh load, overlay upload, and the public setModelBounds —
+    // share one owner instead of a private field. Camera notification stays at
+    // the call sites: they do not all push under the same policy.
+    modelBoundsTracker = new ModelBoundsTracker({
+        meshBounds: () => this.computeMeshBounds(),
+        pointCloudBounds: () => this.pointCloudRenderer?.getBounds() ?? null,
+    });
+    /** Read-only view of the tracked scene AABB (live reference, not a copy). */
+    get modelBounds() {
+        return this.modelBoundsTracker.get();
+    }
     // Composition: delegate to extracted managers
     pickingManager;
     raycastEngine;
@@ -161,6 +227,48 @@ export class Renderer {
     // exactly the evidence worth keeping.
     lastRenderErrorTime = -Infinity;
     RENDER_ERROR_THROTTLE_MS = 1000;
+    /**
+     * Consecutive frames that threw a non-device error and were degraded.
+     * Reset by any frame that completes. Gates the self-retry in `render()`'s
+     * catch — see there for why it is a retry budget and not a latch — and,
+     * since #2417, the persistent-degradation report as well. Both readings
+     * depend on the reset: this is the length of the CURRENT unbroken run of
+     * failures, never a session total (`_renderErrorCount` is that, and using
+     * it for either purpose would count failures the viewport recovered from).
+     */
+    consecutiveDegradedFrames = 0;
+    /**
+     * How many consecutive degraded frames may re-request themselves. Three is
+     * a blink at 60 Hz — enough for a transient host-memory spike to clear
+     * without the user touching anything, far too few to matter as wasted work
+     * if it does not. Beyond it the viewport goes quiet rather than spinning,
+     * and the next interaction/stream/animation drives it as normal.
+     */
+    MAX_DEGRADED_SELF_RETRIES = 3;
+    /**
+     * Decides when degrading has stopped being transient (issue #2417). The
+     * non-latching branch is correct per occurrence and blind in aggregate: a
+     * failure that never clears leaves a wedged viewport that looks, from
+     * outside, exactly like one that recovered. Fires once per session.
+     */
+    renderDegradation = new RenderDegradationMonitor();
+    persistentDegradationListeners = new Set();
+    /**
+     * Set by `containFrameThrow` for the frame currently in flight, cleared by
+     * `render()` before each one.
+     *
+     * Needed because the encode region's catch is INSIDE `renderFrame()`, and
+     * it swallows its throw: a frame that failed there returns to `render()`
+     * perfectly normally, so "did not throw" is not the same question as "did
+     * not fail". Without this flag `render()` reads it as a completed frame and
+     * resets `consecutiveDegradedFrames` on the very next line — which makes
+     * `++count <= MAX_DEGRADED_SELF_RETRIES` true on EVERY encode failure, so
+     * the retry budget never exhausts and a persistently failing encode path
+     * re-requests one throwing frame per rAF forever. It also caps the run
+     * length at 1, so no persistent-degradation report could ever fire for the
+     * region this PR exists to cover.
+     */
+    frameContainedThrow = false;
     // Diagnostic counters for mobile debugging
     _renderCallCount = 0;
     _renderSkipCount = 0;
@@ -225,9 +333,43 @@ export class Renderer {
         this.raycastEngine = new RaycastEngine(this.camera, this.scene, this.canvas);
     }
     /**
-     * Initialize renderer
+     * Initialize renderer.
+     *
+     * Safe to call on an already-initialised instance: the previous GPU objects
+     * are released first. The comment below advertises a `destroy()` + `init()`
+     * re-init flow, and the obvious device-loss auto-recovery is to call
+     * `init()` on the live instance — which, without this, silently orphaned
+     * two render pipelines, the picker, the post-processor, the point-cloud and
+     * deviation pipelines, the EDL pass and the overlay layer's glyph atlas, per
+     * recovery (#2448). Making the method self-safe is cheaper than trusting
+     * every future caller to remember.
+     *
+     * Concurrent calls are SERIALISED, not coalesced: the second waits for the
+     * first to settle and then runs in full. Without that, `pipeline` — which
+     * only ever marks a COMPLETED init — is still null while the first call is
+     * awaiting `device.init()`, so both calls sail past the guard above and both
+     * allocate a full set of GPU objects, orphaning the first. Queueing turns
+     * the concurrent case into the sequential one the guard already handles,
+     * rather than adding a second, differently-shaped rule.
      */
     async init() {
+        // 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());
+        this.initChain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async initOnce() {
+        // `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;
+        }
         // 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;
@@ -252,16 +394,7 @@ export class Renderer {
         }
         this.pipeline = new RenderPipeline(this.device, width, height);
         this.picker = new Picker(this.device, width, height);
-        this.sectionPlaneRenderer = new SectionPlaneRenderer(this.device.getDevice(), this.device.getFormat(), this.pipeline.getSampleCount());
-        this.section2DOverlayRenderer = new Section2DOverlayRenderer(this.device.getDevice(), this.device.getFormat(), this.pipeline.getSampleCount());
-        // Re-apply any colour set before this (re)creation so it isn't lost.
-        this.section2DOverlayRenderer.setOverlayLineColor(this.overlayLineColor);
-        // IfcAnnotation overlay pipelines (issue #653). Share the device +
-        // presentation format AND the MSAA sample count + objectId attachment
-        // shape with the rest of the renderer so they composite into the same
-        // RGBA pass without WebGPU pass-compatibility validation errors.
-        this.symbolicFillPipeline = new SymbolicFillPipeline(this.device.getDevice(), this.device.getFormat(), this.pipeline.getSampleCount());
-        this.symbolicTextPipeline = new SymbolicTextPipeline(this.device.getDevice(), this.device.getFormat(), this.pipeline.getSampleCount());
+        this.overlays.init(this.device.getDevice(), this.device.getFormat(), this.pipeline.getSampleCount());
         // PostProcessor is optional — if it fails (e.g. mobile GPU lacking
         // depth TEXTURE_BINDING), rendering still works without post-processing.
         try {
@@ -343,8 +476,44 @@ export class Renderer {
      */
     onDeviceLost(listener) {
         this.deviceLostListeners.add(listener);
+        // Replay a loss that already happened. `init()` subscribes to the
+        // device's own loss signal BEFORE awaiting `device.init()`, so a loss
+        // during initialisation latches while `deviceLostListeners` is still
+        // empty — and the viewer's subscriber cannot register any earlier,
+        // because it needs init() to have resolved. Without this replay that
+        // loss reaches nobody: the renderer correctly goes quiet and the user
+        // sees a viewer that simply stopped, with no toast and no capture.
+        if (this.deviceLost && this.deviceLostInfo !== null) {
+            try {
+                listener(this.deviceLostInfo);
+            }
+            catch (e) {
+                console.error('[Renderer] onDeviceLost listener threw:', e);
+            }
+        }
         return () => this.deviceLostListeners.delete(listener);
     }
+    /**
+     * Subscribe to the renderer having degraded frame after frame without
+     * recovering (issue #2417). Distinct from `onDeviceLost`: the device is
+     * still alive by every signal available, which is exactly why `render()`
+     * refuses to latch on these throws — but the user is looking at a viewport
+     * that has stopped updating, and until this callback existed nothing said
+     * so. Fired at most once per renderer, once `PERSISTENT_DEGRADATION_FRAMES`
+     * frames have degraded CONSECUTIVELY — any frame that completes resets the
+     * run, so a session that failed occasionally and recovered every time never
+     * reports. Returns an unsubscribe function.
+     *
+     * No replay for a late subscriber, unlike `onDeviceLost` — a loss can latch
+     * during `init()`, before any subscriber can exist, but a degraded frame
+     * cannot: `renderFrame()` returns early while `pipeline` is null, so the
+     * count only moves once the host is driving frames, which is strictly after
+     * `init()` resolved and the host subscribed.
+     */
+    onPersistentRenderDegradation(listener) {
+        this.persistentDegradationListeners.add(listener);
+        return () => this.persistentDegradationListeners.delete(listener);
+    }
     /** True once the GPU device has been lost for a non-intentional reason. */
     isDeviceLost() {
         return this.deviceLost;
@@ -353,6 +522,7 @@ export class Renderer {
         if (this.deviceLost)
             return;
         this.deviceLost = true;
+        this.deviceLostInfo = info;
         console.warn('[Renderer] GPU device lost — halting rendering until re-init:', info.message);
         for (const listener of this.deviceLostListeners) {
             try {
@@ -363,6 +533,108 @@ export class Renderer {
             }
         }
     }
+    /**
+     * Contain a throw that escaped part of a frame, and decide what it meant.
+     *
+     * ONE body for both of `render()`'s catches (issue #2417). They used to
+     * differ in the only way that matters: the outer one discriminated on
+     * `isDeviceLossThrow`, the encode-region one did not, so a device that died
+     * after `getCurrentTexture()` succeeded degraded quietly forever — no latch,
+     * no toast, no `onDeviceLost`. Sharing the body is what stops the two
+     * halves of one policy drifting apart again.
+     *
+     * Callers keep only what is genuinely theirs: the outer catch counts the
+     * frame as a skip, the encode catch balances the validation error scope
+     * first. `origin` distinguishes them in logs and in the degradation report.
+     */
+    containFrameThrow(error, origin) {
+        // Recorded for BOTH branches, before either is chosen: the caller in
+        // the encode region is about to return normally either way, and
+        // `render()` must not mistake that for a frame that succeeded.
+        this.frameContainedThrow = true;
+        this._renderErrorCount++;
+        const message = error instanceof Error ? error.message : String(error);
+        this._lastRenderError = message;
+        if (isDeviceLossThrow(error)) {
+            // Reached at most once per device: the `deviceLost` early return in
+            // render() short-circuits every later frame. Logged with the
+            // original error to keep the stack.
+            console.error(`[Renderer] Frame threw a DOMException (${origin}) — treating as device loss:`, error);
+            this.handleDeviceLost({
+                message,
+                reason: origin === 'encode' ? 'render-encode-exception' : 'render-exception',
+            });
+            return;
+        }
+        // Not a device signal — cost this FRAME, never the session. Both
+        // regions really do have such a source on a HEALTHY device: the outer
+        // one runs `scene.restoreAllEvicted()` for capture frames, the encode
+        // one builds visibility sub-batches through
+        // `scene.getOrCreatePartialBatch()`, and both allocate via
+        // `createBuffer({ mappedAtCreation: true })`, which throws a plain
+        // `RangeError` under host memory pressure — the failure
+        // `gpu-upload-guard` documents verbatim. Latching there would kill the
+        // viewport for a failure whose blast radius should be one frame, and
+        // would raise a false "graphics device was lost" toast plus false
+        // `device_lost` telemetry on top.
+        //
+        // Invalidate the swap-chain configuration so the next frame
+        // reconfigures.
+        this.device.invalidateContext();
+        // ...and ask for that next frame. The host loop CONSUMES the dirty flag
+        // before calling render(), so a frame that fails has already spent its
+        // request: on an idle viewer (no animation, no streaming, no
+        // interaction) nothing would re-dirty it and the failed frame would be
+        // the last one drawn until the user happened to touch something.
+        // "Degrade and continue" has to mean the next frame actually comes, or
+        // it is only "degrade and hope".
+        //
+        // Bounded, and reset by any successful frame, so a persistently failing
+        // path cannot self-perpetuate one throwing frame per rAF forever. NOTE
+        // this is a RETRY budget, not a latch threshold: exhausting it stops us
+        // re-requesting, leaving the app's own dirty signals (interaction,
+        // streaming, animation) to drive — it never disables the renderer.
+        // Worst case is a stale viewport that any interaction revives, not a
+        // dead session.
+        if (++this.consecutiveDegradedFrames <= this.MAX_DEGRADED_SELF_RETRIES) {
+            this.requestRender();
+        }
+        // Per-frame degradation is the right call and an aggregate blind spot:
+        // report the session once it is clear the failure is not clearing.
+        this.notePersistentDegradation(message, origin);
+        const now = performance.now();
+        if (now - this.lastRenderErrorTime > this.RENDER_ERROR_THROTTLE_MS) {
+            this.lastRenderErrorTime = now;
+            console.warn(`[Renderer] Frame threw in ${origin} (device assumed alive; context will be reconfigured):`, error);
+        }
+    }
+    /**
+     * Fan out the once-per-session "this viewport is not recovering" report.
+     * The renderer files no telemetry itself (it is host-agnostic and must stay
+     * PostHog-free); the host subscribes and routes it through whatever it
+     * already uses for device loss.
+     */
+    notePersistentDegradation(detail, origin) {
+        // `consecutiveDegradedFrames`, NOT `_renderErrorCount`. The latter is a
+        // renderer-LIFETIME total that no successful frame ever resets, so it
+        // would turn the threshold into "the 16th failure ever" — reached by a
+        // long healthy session that hit four isolated spikes an hour apart and
+        // recovered from every one of them. The signal is meant to mean "this
+        // viewport has stopped", and only an unbroken run means that. The
+        // reset lives in `render()`, on the path where a frame completes.
+        const info = this.renderDegradation.note(this.consecutiveDegradedFrames, detail, origin);
+        if (!info)
+            return;
+        console.warn(`[Renderer] ${info.consecutiveDegradedFrames} consecutive frames degraded without one completing — the viewport is not updating.`);
+        for (const listener of this.persistentDegradationListeners) {
+            try {
+                listener(info);
+            }
+            catch (e) {
+                console.error('[Renderer] onPersistentRenderDegradation listener threw:', e);
+            }
+        }
+    }
     /**
      * Replace all loaded point clouds with `assets`.
      *
@@ -376,10 +648,10 @@ export class Renderer {
         }
         this.pointCloudRenderer.setAssets(assets);
         // Replace, not append — bounds may have shrunk (e.g. an IFCx
-        // reload with a smaller scan). `expandModelBoundsForPointClouds`
+        // reload with a smaller scan). `expandForPointClouds`
         // alone only grows; recompute from scratch to keep
         // fit-to-view + section-plane sliders accurate.
-        this.recomputeModelBounds();
+        this.modelBoundsTracker.recompute();
         this.camera.setSceneBounds(this.modelBounds);
         this.requestRender();
     }
@@ -391,7 +663,7 @@ export class Renderer {
         for (const asset of assets) {
             this.pointCloudRenderer.addAsset(asset);
         }
-        this.expandModelBoundsForPointClouds();
+        this.modelBoundsTracker.expandForPointClouds();
         this.camera.setSceneBounds(this.modelBounds);
         this.requestRender();
     }
@@ -406,7 +678,7 @@ export class Renderer {
     /** Drop all point cloud GPU resources. */
     clearPointClouds() {
         this.pointCloudRenderer?.clear();
-        this.recomputeModelBounds();
+        this.modelBoundsTracker.recompute();
         this.camera.setSceneBounds(this.modelBounds);
         this.requestRender();
     }
@@ -425,7 +697,7 @@ export class Renderer {
         if (!this.pointCloudRenderer)
             return;
         this.pointCloudRenderer.appendChunk(handle, chunk);
-        this.expandModelBoundsForPointClouds();
+        this.modelBoundsTracker.expandForPointClouds();
         this.camera.setSceneBounds(this.modelBounds);
         this.requestRender();
     }
@@ -437,7 +709,7 @@ export class Renderer {
         this.pointCloudRenderer?.removeAsset(handle);
         // Bounds may have shrunk — recompute from scratch so fit-to-view
         // and section-plane sliders see fresh extents.
-        this.recomputeModelBounds();
+        this.modelBoundsTracker.recompute();
         this.camera.setSceneBounds(this.modelBounds);
         this.requestRender();
     }
@@ -452,34 +724,6 @@ export class Renderer {
         this.pointCloudRenderer?.relabelAsset(handle, newExpressId);
         this.requestRender();
     }
-    /**
-     * Compute model bounds from triangle meshes + remaining point clouds.
-     * Called from removeAsset / clear paths so bounds shrink correctly.
-     * Triangle meshes still drive the bounds when present (existing
-     * Scene-driven path), so this only re-folds in the point cloud
-     * extents over whatever the mesh path left.
-     */
-    recomputeModelBounds() {
-        // Always recompute from scratch: take mesh bounds as the
-        // baseline, then fold in the CURRENT point-cloud bounds on
-        // top. Folding only-up via expandModelBoundsForPointClouds()
-        // is correct when pc bounds grow but never shrinks them when
-        // an asset is removed, leaving stale oversized extents until
-        // every point cloud is gone.
-        const meshBounds = this.computeMeshBounds();
-        const pcBounds = this.pointCloudRenderer?.getBounds() ?? null;
-        if (!meshBounds && !pcBounds) {
-            this.modelBounds = null;
-            return;
-        }
-        this.modelBounds = meshBounds ?? {
-            min: { x: pcBounds.min[0], y: pcBounds.min[1], z: pcBounds.min[2] },
-            max: { x: pcBounds.max[0], y: pcBounds.max[1], z: pcBounds.max[2] },
-        };
-        if (meshBounds && pcBounds) {
-            this.expandModelBoundsForPointClouds();
-        }
-    }
     /** Aggregate bounds across all batched + individual meshes. Returns
      *  null if the scene has no mesh geometry. */
     computeMeshBounds() {
@@ -525,7 +769,7 @@ export class Renderer {
         // them to the camera (matching every other bounds-mutating
         // point-cloud method) so framing / zoom-to-fit targets where the
         // points actually render.
-        this.recomputeModelBounds();
+        this.modelBoundsTracker.recompute();
         this.camera.setSceneBounds(this.modelBounds);
         this.requestRender();
     }
@@ -657,25 +901,6 @@ export class Renderer {
             this.edlOptions.highQuality = opts.highQuality;
         this.requestRender();
     }
-    expandModelBoundsForPointClouds() {
-        const pcBounds = this.pointCloudRenderer?.getBounds();
-        if (!pcBounds)
-            return;
-        if (!this.modelBounds) {
-            this.modelBounds = {
-                min: { x: pcBounds.min[0], y: pcBounds.min[1], z: pcBounds.min[2] },
-                max: { x: pcBounds.max[0], y: pcBounds.max[1], z: pcBounds.max[2] },
-            };
-            return;
-        }
-        const m = this.modelBounds;
-        m.min.x = Math.min(m.min.x, pcBounds.min[0]);
-        m.min.y = Math.min(m.min.y, pcBounds.min[1]);
-        m.min.z = Math.min(m.min.z, pcBounds.min[2]);
-        m.max.x = Math.max(m.max.x, pcBounds.max[0]);
-        m.max.y = Math.max(m.max.y, pcBounds.max[1]);
-        m.max.z = Math.max(m.max.z, pcBounds.max[2]);
-    }
     /**
      * Load geometry from GeometryResult or MeshData array
      * This is the main entry point for loading IFC geometry into the renderer
@@ -695,7 +920,7 @@ export class Renderer {
         const device = this.device.getDevice();
         this.scene.appendToBatches(meshes, device, this.pipeline, false);
         // Calculate and store model bounds for fitToView
-        this.updateModelBounds(meshes);
+        this.modelBoundsTracker.updateFromMeshes(meshes);
         console.log(`[Renderer] Loaded ${meshes.length} meshes`);
         // Update camera scene bounds for tight orthographic near/far planes
         this.camera.setSceneBounds(this.modelBounds);
@@ -715,7 +940,7 @@ export class Renderer {
         const device = this.device.getDevice();
         this.scene.appendToBatches(meshes, device, this.pipeline, isStreaming);
         // Update model bounds incrementally
-        this.updateModelBounds(meshes);
+        this.modelBoundsTracker.updateFromMeshes(meshes);
         // Update camera scene bounds for tight orthographic near/far planes
         this.camera.setSceneBounds(this.modelBounds);
     }
@@ -800,39 +1025,7 @@ export class Renderer {
      * 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;
-            // Positions are in the element's local frame (world = origin + position).
-            // Model bounds are world-space, so fold the per-mesh origin. No-op when
-            // origin is absent/[0,0,0]. Mirrors coordinate-handler.ts.
-            const o = mesh.origin;
-            const ox = o ? o[0] : 0, oy = o ? o[1] : 0, oz = o ? o[2] : 0;
-            for (let i = 0; i < positions.length; i += 3) {
-                const x = positions[i] + ox;
-                const y = positions[i + 1] + oy;
-                const z = positions[i + 2] + oz;
-                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);
-                }
-            }
-        }
+        this.modelBoundsTracker.set(bounds);
     }
     /**
      * Create a GPU Mesh from MeshData (lazy creation for selection highlighting)
@@ -985,31 +1178,6 @@ export class Renderer {
             }
         });
     }
-    resolveVisualEnhancement(options) {
-        if (!options) {
-            return this.visualEnhancementState;
-        }
-        const merged = {
-            enabled: options.enabled ?? this.visualEnhancementState.enabled,
-            edgeContrast: {
-                enabled: options.edgeContrast?.enabled ?? this.visualEnhancementState.edgeContrast.enabled,
-                intensity: options.edgeContrast?.intensity ?? this.visualEnhancementState.edgeContrast.intensity,
-            },
-            contactShading: {
-                quality: options.contactShading?.quality ?? this.visualEnhancementState.contactShading.quality,
-                intensity: options.contactShading?.intensity ?? this.visualEnhancementState.contactShading.intensity,
-                radius: options.contactShading?.radius ?? this.visualEnhancementState.contactShading.radius,
-            },
-            separationLines: {
-                enabled: options.separationLines?.enabled ?? this.visualEnhancementState.separationLines.enabled,
-                quality: options.separationLines?.quality ?? this.visualEnhancementState.separationLines.quality,
-                intensity: options.separationLines?.intensity ?? this.visualEnhancementState.separationLines.intensity,
-                radius: options.separationLines?.radius ?? this.visualEnhancementState.separationLines.radius,
-            },
-        };
-        this.visualEnhancementState = merged;
-        return merged;
-    }
     /**
      * Render frame
      */
@@ -1056,6 +1224,34 @@ export class Renderer {
             this.scene.setQuantizedBatches(true);
         return ok;
     }
+    /**
+     * Draw one frame.
+     *
+     * Never throws, so callers never need to guard this call to keep their
+     * animation loop alive.
+     *
+     * What a throw MEANS depends on its type (`isDeviceLossThrow`), and since
+     * issue #2417 that holds for the WHOLE frame — both this catch and the
+     * encode region's own, which share `containFrameThrow`:
+     *  - a `DOMException` is the device reporting its own death synchronously
+     *    (Safari 26.5, issue #2229). It latches the same `deviceLost` state the
+     *    async `device.lost` promise would: later frames become quiet skips and
+     *    `onDeviceLost` listeners fire exactly once.
+     *  - anything else (a `RangeError` from a buffer the host cannot allocate,
+     *    say) costs only this frame: the swap-chain config is invalidated so
+     *    the next frame reconfigures, a frame is re-requested within a bounded
+     *    budget, the failure is counted in `getDiagnostics()`, and rendering
+     *    carries on. Once enough such frames have degraded without recovering,
+     *    `onPersistentRenderDegradation` fires once.
+     *
+     * SCOPE: `renderFrame()` has two try/catch regions — this outer one (canvas
+     * resize, context setup, evicted-batch restore) and an inner one opened
+     * after the swap-chain texture is acquired, covering encoder work through
+     * `submit`. Until #2417 only the outer one discriminated, so a device that
+     * died after `getCurrentTexture()` succeeded degraded quietly forever with
+     * no latch and no toast. Both now run the same policy; the encode catch
+     * additionally balances the frame's validation error scope before doing so.
+     */
     render(options = {}) {
         this._renderCallCount++;
         // A lost device leaves every pipeline/buffer dead; rendering would only
@@ -1064,6 +1260,37 @@ export class Renderer {
             this._renderSkipCount++;
             return;
         }
+        try {
+            this.frameContainedThrow = false;
+            this.renderFrame(options);
+            // Only a frame that actually got through resets the run. A frame
+            // the ENCODE catch contained returns here normally (that catch is
+            // inside renderFrame), so "did not throw" is not the same question
+            // as "did not fail" — see `frameContainedThrow`.
+            if (!this.frameContainedThrow)
+                this.consecutiveDegradedFrames = 0;
+        }
+        catch (error) {
+            // Safari (26.5) reports device loss SYNCHRONOUSLY: a call against a
+            // dead device throws `InvalidStateError` instead of — or long
+            // before — resolving `device.lost` (issue #2229). Without this
+            // catch the throw escapes render(), the caller's rAF loop never
+            // re-arms, and the viewer freezes for good with nothing on screen
+            // and nothing subscribed to onDeviceLost ever told.
+            //
+            // Deliberately NOT rethrown either way: the frame is already lost,
+            // and the established contract is "degrade" (see `pickPathAlive()`
+            // and the rAF loop's own upload/residency guards), not "take the
+            // host down with us".
+            this._renderSkipCount++;
+            this.containFrameThrow(error, 'frame');
+        }
+    }
+    /**
+     * The frame body. Throws on a synchronously-dead GPU device; `render()`
+     * owns the containment. Private for that reason — call `render()`.
+     */
+    renderFrame(options) {
         if (!this.device.isInitialized() || !this.pipeline) {
             this._renderSkipCount++;
             return;
@@ -1126,7 +1353,7 @@ export class Renderer {
         if (options.restoreEvictedForCapture && this.pipeline) {
             this.scene.restoreAllEvicted(device, this.pipeline);
         }
-        const visualEnhancement = this.resolveVisualEnhancement(options.visualEnhancement);
+        const visualEnhancement = this.visualEnhancementResolver.resolve(options.visualEnhancement);
         // Post effects during interaction (orbit/pan/zoom) are governed
         // adaptively: they stay on while the interactive frame cadence holds
         // (the pass costs well under a ms on discrete/Apple GPUs at CSS
@@ -1370,201 +1597,27 @@ export class Renderer {
             // Write uniform data to each mesh's buffer BEFORE recording commands
             // This ensures each mesh has its own color data
             const allMeshes = [...opaqueMeshes, ...transparentMeshes];
-            // Calculate section plane parameters and model bounds
-            // Always calculate bounds when sectionPlane is provided (for preview and active mode)
-            let sectionPlaneData;
-            // Terrain clip: when Cesium overlay is active, clip model below terrain.
-            // Normal (0,-1,0) + distance (-clipY) clips where worldPos.y < clipY.
-            if (options.terrainClipY !== undefined && !options.sectionPlane?.enabled) {
-                sectionPlaneData = {
-                    normal: [0, -1, 0],
-                    distance: -options.terrainClipY,
-                    enabled: true,
-                };
-            }
-            if (options.sectionPlane) {
-                // Get model bounds from batched meshes. We deliberately EXCLUDE
-                // individual meshes (`this.scene.getMeshes()`) here: those are
-                // created lazily for selection highlighting and can live at
-                // unexpected world positions (e.g. legacy transforms, overlay
-                // helpers), which would inflate the bounds range and make
-                // "1% of the slider" span the entire real model — producing
-                // the reported symptom where the model pops from fully visible
-                // to fully invisible across a tiny slider range.
-                const boundsMin = { x: Infinity, y: Infinity, z: Infinity };
-                const boundsMax = { x: -Infinity, y: -Infinity, z: -Infinity };
-                const batchedMeshes = this.scene.getBatchedMeshes();
-                for (const batch of batchedMeshes) {
-                    if (batch.bounds) {
-                        boundsMin.x = Math.min(boundsMin.x, batch.bounds.min[0]);
-                        boundsMin.y = Math.min(boundsMin.y, batch.bounds.min[1]);
-                        boundsMin.z = Math.min(boundsMin.z, batch.bounds.min[2]);
-                        boundsMax.x = Math.max(boundsMax.x, batch.bounds.max[0]);
-                        boundsMax.y = Math.max(boundsMax.y, batch.bounds.max[1]);
-                        boundsMax.z = Math.max(boundsMax.z, batch.bounds.max[2]);
-                    }
-                }
-                // Fold in point-cloud bounds too — without this, a
-                // pure point-cloud scene falls through to the default
-                // [-100,100], and a mixed scene clips against a
-                // smaller mesh-only range while the point pipeline
-                // (which honours the same sectionPlaneData) keeps
-                // drawing points outside the slider's reach.
-                const pcBoundsForSection = this.pointCloudRenderer?.getBounds();
-                if (pcBoundsForSection) {
-                    boundsMin.x = Math.min(boundsMin.x, pcBoundsForSection.min[0]);
-                    boundsMin.y = Math.min(boundsMin.y, pcBoundsForSection.min[1]);
-                    boundsMin.z = Math.min(boundsMin.z, pcBoundsForSection.min[2]);
-                    boundsMax.x = Math.max(boundsMax.x, pcBoundsForSection.max[0]);
-                    boundsMax.y = Math.max(boundsMax.y, pcBoundsForSection.max[1]);
-                    boundsMax.z = Math.max(boundsMax.z, pcBoundsForSection.max[2]);
-                }
-                // If no batched meshes have bounds yet (streaming, degenerate
-                // models), fall back to individual meshes so at least the
-                // slider has a workable range.
-                if (!Number.isFinite(boundsMin.x)) {
-                    for (const mesh of meshes) {
-                        if (mesh.bounds) {
-                            boundsMin.x = Math.min(boundsMin.x, mesh.bounds.min[0]);
-                            boundsMin.y = Math.min(boundsMin.y, mesh.bounds.min[1]);
-                            boundsMin.z = Math.min(boundsMin.z, mesh.bounds.min[2]);
-                            boundsMax.x = Math.max(boundsMax.x, mesh.bounds.max[0]);
-                            boundsMax.y = Math.max(boundsMax.y, mesh.bounds.max[1]);
-                            boundsMax.z = Math.max(boundsMax.z, mesh.bounds.max[2]);
-                        }
-                    }
-                }
-                // Fallback if no bounds found
-                if (!Number.isFinite(boundsMin.x)) {
-                    boundsMin.x = boundsMin.y = boundsMin.z = -100;
-                    boundsMax.x = boundsMax.y = boundsMax.z = 100;
-                }
-                // Store bounds for section plane visual and camera near/far
+            // This frame's clip plane and the bounds the section slider is
+            // expressed in — resolved in render-section-plane.ts, which owns
+            // the bounds aggregation, the terrain-clip and explicit-plane
+            // branches, and the one-shot diagnostic log (issue #2425).
+            const sectionFrame = resolveSectionPlaneFrame({
+                options,
+                batchedMeshes: this.scene.getBatchedMeshes(),
+                meshes,
+                pointCloudBounds: this.pointCloudRenderer?.getBounds() ?? null,
+                logSectionBounds: !this._loggedSectionBounds,
+                spendLogLatch: () => { this._loggedSectionBounds = true; },
+            });
+            const sectionPlaneData = sectionFrame.sectionPlaneData;
+            if (sectionFrame.bounds) {
+                // Store bounds for section plane visual and camera near/far.
+                // Two wrappers over the same min/max, exactly as before the
+                // extraction — the renderer's copy is replaced wholesale by the
+                // bounds helpers, the camera's is not.
+                const { min: boundsMin, max: boundsMax } = sectionFrame.bounds;
                 this.setModelBounds({ min: boundsMin, max: boundsMax });
                 this.camera.setSceneBounds({ min: boundsMin, max: boundsMax });
-                // Only calculate clipping data if section is enabled
-                // Terrain clip: when no section plane is active, use terrainClipY
-                // to clip fragments below terrain height. Normal (0,-1,0) with
-                // distance = -clipY clips worldPos.y < clipY.
-                if (!options.sectionPlane?.enabled && options.terrainClipY !== undefined) {
-                    sectionPlaneData = {
-                        normal: [0, -1, 0],
-                        distance: -options.terrainClipY,
-                        enabled: true,
-                    };
-                }
-                if (options.sectionPlane.enabled) {
-                    // Explicit normal + distance override (face-pick / arbitrary
-                    // plane, issue #243). Used verbatim: no axis mapping, no
-                    // position slider, no building rotation — the caller already
-                    // has the plane in world space.
-                    const explicitNormal = options.sectionPlane.normal;
-                    const explicitDistance = options.sectionPlane.distance;
-                    const hasExplicitPlane = explicitNormal !== undefined &&
-                        explicitDistance !== undefined &&
-                        Number.isFinite(explicitDistance);
-                    let normal;
-                    let distance;
-                    if (hasExplicitPlane) {
-                        // Defensive renormalisation in case the caller passed a
-                        // non-unit vector (e.g. mesh face normals quantised by
-                        // the geometry pipeline).
-                        const nx = explicitNormal[0];
-                        const ny = explicitNormal[1];
-                        const nz = explicitNormal[2];
-                        const len = Math.sqrt(nx * nx + ny * ny + nz * nz);
-                        if (len > 1e-6) {
-                            normal = [nx / len, ny / len, nz / len];
-                            distance = explicitDistance / len;
-                        }
-                        else {
-                            normal = [0, 1, 0];
-                            distance = explicitDistance;
-                        }
-                    }
-                    else {
-                        // Cardinal-axis preset path (unchanged behaviour).
-                        // down = Y axis (horizontal cut), front = Z axis, side = X axis
-                        normal = [0, 0, 0];
-                        if (options.sectionPlane.axis === 'side')
-                            normal[0] = 1; // X axis
-                        else if (options.sectionPlane.axis === 'down')
-                            normal[1] = 1; // Y axis (horizontal)
-                        else
-                            normal[2] = 1; // Z axis (front)
-                        // Apply building rotation if present (rotate normal around Y axis)
-                        // Building rotation is in X-Y plane (Z is up in IFC, Y is up in WebGL)
-                        if (options.buildingRotation !== undefined && options.buildingRotation !== 0) {
-                            const cosR = Math.cos(options.buildingRotation);
-                            const sinR = Math.sin(options.buildingRotation);
-                            // Rotate normal vector around Y axis (vertical)
-                            // For X-Z plane rotation: x' = x*cos - z*sin, z' = x*sin + z*cos, y' = y
-                            const x = normal[0];
-                            const z = normal[2];
-                            normal[0] = x * cosR - z * sinR;
-                            normal[2] = x * sinR + z * cosR;
-                            // Normalize to maintain unit length
-                            const rlen = Math.sqrt(normal[0] * normal[0] + normal[1] * normal[1] + normal[2] * normal[2]);
-                            if (rlen > 0.0001) {
-                                normal[0] /= rlen;
-                                normal[1] /= rlen;
-                                normal[2] /= rlen;
-                            }
-                        }
-                        // Get axis-specific range. The renderer's own `boundsMin/Max`
-                        // are computed from the GPU vertex buffers this frame, so
-                        // they are guaranteed to be in the same Y-up world space as
-                        // `input.worldPos` in the shader. `options.sectionPlane.min/max`
-                        // comes from the UI via `coordinateInfo.shiftedBounds` and can
-                        // be stale during streaming or outright wrong during model
-                        // load (initialised to {0,0,0} before the first bounds update)
-                        // — using those directly was the cause of the "slider moves
-                        // 1% and the whole model disappears" bug.
-                        //
-                        // Policy: always use the renderer's own bounds for the Y-up
-                        // range. Only honour the UI override when it is a valid,
-                        // non-degenerate range that lies INSIDE the actual mesh
-                        // bounds (e.g. storey filtering from the level picker).
-                        const axisIdx = options.sectionPlane.axis === 'side' ? 'x' : options.sectionPlane.axis === 'down' ? 'y' : 'z';
-                        let minVal = boundsMin[axisIdx];
-                        let maxVal = boundsMax[axisIdx];
-                        const uiMin = options.sectionPlane.min;
-                        const uiMax = options.sectionPlane.max;
-                        if (Number.isFinite(uiMin) &&
-                            Number.isFinite(uiMax) &&
-                            uiMax - uiMin > 1e-6 &&
-                            uiMin >= minVal - 1e-3 &&
-                            uiMax <= maxVal + 1e-3) {
-                            minVal = uiMin;
-                            maxVal = uiMax;
-                        }
-                        // Calculate plane distance from position percentage
-                        const range = maxVal - minVal;
-                        distance = minVal + (options.sectionPlane.position / 100) * range;
-                    }
-                    sectionPlaneData = { normal, distance, enabled: true };
-                    // One-shot diagnostic: when section first becomes active,
-                    // log the exact bounds + plane the shader will use. This
-                    // is the fastest way to confirm "bounds mismatch" / "plane
-                    // off-screen" bugs without asking the user to run a
-                    // debugger. The custom-plane branch logs `mode: 'explicit'`
-                    // so reports against tilted planes are easy to spot.
-                    if (!this._loggedSectionBounds) {
-                        this._loggedSectionBounds = true;
-                        console.info('[Section] Y-up bounds used for clip:', {
-                            mode: hasExplicitPlane ? 'explicit' : 'axis-aligned',
-                            axis: options.sectionPlane.axis,
-                            bounds: {
-                                min: { x: boundsMin.x, y: boundsMin.y, z: boundsMin.z },
-                                max: { x: boundsMax.x, y: boundsMax.y, z: boundsMax.z },
-                            },
-                            normal,
-                            distance,
-                            position: options.sectionPlane.position,
-                            batchedMeshCount: this.scene.getBatchedMeshes().length,
-                        });
-                    }
-                }
             }
             // Stash what we actually clipped this frame so the GPU picker mirrors
             // it (section/crop-clipped geometry must be unpickable, not just hidden).
@@ -2131,12 +2184,6 @@ export class Renderer {
                 const texturedMeshes = this.scene.getTexturedMeshes();
                 if (texturedMeshes.length > 0) {
                     pass.setPipeline(this.pipeline.getTexturedPipeline());
-                    // Textured meshes carry absolute (origin-0) positions, so the
-                    // model translation must be identity here — reset the column
-                    // that renderBatch left set to the last opaque batch's origin.
-                    tpl[28] = 0;
-                    tpl[29] = 0;
-                    tpl[30] = 0;
                     for (const tm of texturedMeshes) {
                         // Honour hide/isolate — textured meshes bypass the batch
                         // visibility filtering above, so apply it per-mesh here or
@@ -2161,6 +2208,18 @@ export class Renderer {
                         // batch overlay paint pass doesn't iterate textured meshes,
                         // so applying the override here is what recolours them.
                         const txOverride = colorOverrides?.get(tm.expressId);
+                        // `world = origin + position`: the vertex buffer stores
+                        // positions in this mesh's per-element local frame, so the
+                        // model translation carries the world magnitude (#1973).
+                        // Per mesh, which also overwrites the column renderBatch
+                        // left set to the last opaque batch's origin. This used to
+                        // be hoisted out of the loop and hard-zeroed — right only
+                        // for the orphan type-geometry path (origin == 0), and it
+                        // drew every textured occurrence collapsed toward the
+                        // world origin.
+                        tpl[28] = tm.origin[0];
+                        tpl[29] = tm.origin[1];
+                        tpl[30] = tm.origin[2];
                         tpl[32] = txOverride ? txOverride[0] : tm.color[0];
                         tpl[33] = txOverride ? txOverride[1] : tm.color[1];
                         tpl[34] = txOverride ? txOverride[2] : tm.color[2];
@@ -2467,122 +2526,17 @@ export class Renderer {
                     viewport: { width: this.canvas.width, height: this.canvas.height },
                 });
             }
-            // 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.getModelBounds();
-            if (options.sectionPlane && this.sectionPlaneRenderer && modelBounds) {
-                this.sectionPlaneRenderer.draw(pass, {
-                    axis: options.sectionPlane.axis,
-                    position: options.sectionPlane.position,
-                    bounds: modelBounds,
-                    viewProj,
-                    isPreview: !options.sectionPlane.enabled, // Preview mode when not enabled
-                    min: options.sectionPlane.min,
-                    max: options.sectionPlane.max,
-                    // Custom-plane gizmo override (issue #243). When both
-                    // are set the gizmo bypasses the cardinal path; see
-                    // SectionPlaneRenderer.calculatePlaneVerticesFromNormal.
-                    normal: options.sectionPlane.normal,
-                    distance: options.sectionPlane.distance,
-                });
-                // Draw 2D section overlay on the section plane (when section is
-                // active, not preview). The overlay is also the 3D SECTION CAP:
-                // its polygon fills come from `SectionCutter` (exact triangle-
-                // plane intersection), and the new fill shader applies the
-                // user's screen-space hatch + colour directly on those
-                // polygons. This replaces the old stencil-parity cap, which
-                // bled hatch into empty sky on non-manifold IFC geometry —
-                // the polygons here are mathematically correct, so the cap
-                // silhouette matches the 2D drawing exactly.
-                if (options.sectionPlane.enabled && this.section2DOverlayRenderer?.hasGeometry()) {
-                    const o = options.sectionPlane;
-                    const showFills = o.showCap !== false;
-                    const showOutlines = o.showOutlines !== false;
-                    const style = { ...DEFAULT_CAP_STYLE, ...(o.capStyle ?? {}) };
-                    this.section2DOverlayRenderer.draw(pass, {
-                        axis: o.axis,
-                        position: o.position,
-                        bounds: modelBounds,
-                        viewProj,
-                        min: o.min,
-                        max: o.max,
-                        showFills,
-                        showOutlines,
-                        capStyle: showFills ? {
-                            fillColor: style.fillColor,
-                            strokeColor: style.strokeColor,
-                            patternId: HATCH_PATTERN_IDS[style.pattern],
-                            spacingPx: style.spacingPx,
-                            angleRad: style.angleRad,
-                            widthPx: style.widthPx,
-                            secondaryAngleRad: style.secondaryAngleRad,
-                        } : undefined,
-                    });
-                }
-            }
-            // Standalone IFC annotation overlay (issue #653). The line
-            // vertices were pre-lifted to world space at upload time, so
-            // this draw happens regardless of whether a section plane is
-            // active — annotations are a free-floating "drawing layer"
-            // that sits at each annotation's storey elevation.
-            //
-            // This block was previously nested inside the `if (options.sectionPlane && ...)`
-            // guard above, contradicting its own comment. Loading an
-            // annotation-only model with no section plane meant the entire
-            // overlay was skipped at draw time even though 9000+ vertices
-            // had been uploaded successfully. Pulled out to its own block.
-            //
-            // Order: fills (background) → lines (outlines on top) →
-            // texts (labels above everything).
-            if (this.symbolicFillPipeline?.hasGeometry()) {
-                this.symbolicFillPipeline.render(pass, viewProj);
-            }
-            if (this.section2DOverlayRenderer?.hasAnnotationLines3D()) {
-                this.section2DOverlayRenderer.drawAnnotationLines3D(pass, viewProj);
-            }
-            if (this.section2DOverlayRenderer?.hasAlignmentLines3D()) {
-                this.section2DOverlayRenderer.drawAlignmentLines3D(pass, viewProj);
-            }
-            if (this.section2DOverlayRenderer?.hasGridLines3D()) {
-                this.section2DOverlayRenderer.drawGridLines3D(pass, viewProj);
-            }
-            if (this.section2DOverlayRenderer?.hasClashBoxLines3D()) {
-                this.section2DOverlayRenderer.drawClashBoxLines3D(pass, viewProj);
-            }
-            if (this.symbolicTextPipeline?.hasGeometry()) {
-                // Pass viewport pixel dimensions so the shader can scale glyphs
-                // to a constant on-screen size (BIMvision-style annotations)
-                // regardless of camera distance or authored text height.
-                //
-                // Also pass the screen-aligned camera basis (right, up) so
-                // billboarded glyphs (grid bubble tags) can face the camera
-                // in any orientation — top-down, eye-level, oblique alike.
-                const camPos = this.camera.getPosition();
-                const camTgt = this.camera.getTarget();
-                const camUpVec = this.camera.getUp();
-                // Forward = normalize(target - position).
-                let fx = camTgt.x - camPos.x;
-                let fy = camTgt.y - camPos.y;
-                let fz = camTgt.z - camPos.z;
-                let flen = Math.hypot(fx, fy, fz) || 1;
-                fx /= flen;
-                fy /= flen;
-                fz /= flen;
-                // Right = normalize(cross(forward, world-up)).
-                let rx = fy * camUpVec.z - fz * camUpVec.y;
-                let ry = fz * camUpVec.x - fx * camUpVec.z;
-                let rz = fx * camUpVec.y - fy * camUpVec.x;
-                let rlen = Math.hypot(rx, ry, rz) || 1;
-                rx /= rlen;
-                ry /= rlen;
-                rz /= rlen;
-                // True up = normalize(cross(right, forward)) — guaranteed
-                // perpendicular to both, defines screen-space vertical.
-                const ux = ry * fz - rz * fy;
-                const uy = rz * fx - rx * fz;
-                const uz = rx * fy - ry * fx;
-                this.symbolicTextPipeline.render(pass, viewProj, this.canvas.width, this.canvas.height, [rx, ry, rz], [ux, uy, uz]);
-            }
+            // Section-plane gizmo, 2D section cap and every standalone 3D
+            // overlay (annotation / alignment / grid / DXF / clash / symbolic
+            // text). One draw call into the pass — see RendererOverlays.draw().
+            this.overlays.draw(pass, {
+                options,
+                viewProj,
+                modelBounds: this.getModelBounds(),
+                camera: this.camera,
+                canvasWidth: this.canvas.width,
+                canvasHeight: this.canvas.height,
+            });
             pass.end();
             const canRunPostPass = (contactEnabled || separationEnabled)
                 && this.postProcessor !== null;
@@ -2654,17 +2608,30 @@ export class Renderer {
                 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)
-            // Mark context as invalid so it gets reconfigured next frame
-            this.device.invalidateContext();
-            // Rate-limit error logging to avoid spam (max once per second)
-            const now = performance.now();
-            if (now - this.lastRenderErrorTime > this.RENDER_ERROR_THROTTLE_MS) {
-                this.lastRenderErrorTime = now;
-                console.warn('Render error (context will be reconfigured):', error);
-            }
+            // Same policy as the outer catch since issue #2417 — a `DOMException`
+            // from here is a device that died mid-frame, after
+            // `getCurrentTexture()` had already succeeded, and it must latch
+            // rather than degrade forever in silence.
+            //
+            // Safe to discriminate here because the encode region has no
+            // healthy-device `DOMException` source (swept for #2417): its
+            // `queue.writeBuffer` calls all use the 3-argument form over whole
+            // typed-array views — plus one 5-argument call in
+            // `point-cloud-uniforms.ts` whose offset and size are compile-time
+            // constants matching its scratch array — so the spec's
+            // `OperationError` preconditions are unreachable; the one
+            // `copyExternalImageToTexture` copies the glyph atlas's own
+            // never-externally-drawn canvas at its full fixed size, so neither
+            // `SecurityError` nor a zero-size `OperationError` can arise; and
+            // every other WebGPU call in the region (`createView`,
+            // `createCommandEncoder`, `beginRenderPass`, the pass setters and
+            // draws, `finish`, `submit`, `createBindGroup`) reports failure as
+            // an asynchronous `GPUValidationError` through the error scope, not
+            // as a throw. The region's real healthy-device failure is
+            // `getOrCreatePartialBatch`'s `createBuffer({ mappedAtCreation:
+            // true })`, and that throws a `RangeError` — which is exactly why
+            // the discriminator keys on the TYPE and not on "a frame threw".
+            this.containFrameThrow(error, 'encode');
         }
     }
     /**
@@ -2815,6 +2782,10 @@ export class Renderer {
     getScene() {
         return this.scene;
     }
+    // ─── Overlay facade ──────────────────────────────────────────────────
+    // The section-plane gizmo, the 2D section drawing/cap and the symbolic
+    // annotation overlays live in `RendererOverlays` (issue #2425). These
+    // methods are the published surface; the bodies moved with the state.
     /**
      * Upload 2D section drawing data for 3D overlay rendering.
      *
@@ -2833,38 +2804,13 @@ export class Renderer {
     uploadSection2DOverlay(polygons, lines, axis, position, // 0-100 percentage
     sectionRange, // Same storey-based range as section plane
     flipped = false, customPlane) {
-        if (!this.section2DOverlayRenderer)
-            return;
-        if (customPlane) {
-            // Custom-plane path: planePosition / axis are unused — the
-            // basis the cap shader needs travels in `customPlane`. We pass
-            // 0 for `planePosition` and the existing `axis` so the cardinal
-            // shader code path that callers depend on (e.g. legacy SVG
-            // export) keeps working when customPlane is omitted.
-            this.section2DOverlayRenderer.uploadDrawing(polygons, lines, axis, 0, flipped, customPlane);
-            return;
-        }
-        // Use EXACTLY same calculation as section plane in render() method:
-        // minVal = options.sectionPlane.min ?? boundsMin[axisIdx]
-        // maxVal = options.sectionPlane.max ?? boundsMax[axisIdx]
-        const axisIdx = axis === 'side' ? 'x' : axis === 'down' ? 'y' : 'z';
-        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)
-            return;
-        const minVal = sectionRange?.min ?? modelBounds.min[axisIdx];
-        const maxVal = sectionRange?.max ?? modelBounds.max[axisIdx];
-        const planePosition = minVal + (position / 100) * (maxVal - minVal);
-        this.section2DOverlayRenderer.uploadDrawing(polygons, lines, axis, planePosition, flipped);
+        this.overlays.uploadSection2DOverlay(polygons, lines, axis, position, sectionRange, flipped, customPlane);
     }
     /**
      * Clear the 2D section overlay
      */
     clearSection2DOverlay() {
-        if (this.section2DOverlayRenderer) {
-            this.section2DOverlayRenderer.clearGeometry();
-        }
+        this.overlays.clearSection2DOverlay();
     }
     /**
      * Set the colour of the overlay lines (annotation / alignment / grid) and the
@@ -2873,11 +2819,7 @@ export class Renderer {
      * `SymbolicTextInput.color` on `uploadAnnotationTexts3D`.
      */
     setOverlayLineColor(color) {
-        // Persist on the Renderer so a pre-init call (and any later overlay
-        // re-creation) keeps the colour — init() re-applies this.overlayLineColor.
-        this.overlayLineColor = color;
-        this.section2DOverlayRenderer?.setOverlayLineColor(color);
-        this.requestRender();
+        this.overlays.setOverlayLineColor(color);
     }
     /**
      * Upload pre-lifted 3D line-list vertices for the standalone annotation
@@ -2886,84 +2828,13 @@ export class Renderer {
      * Pass an empty Float32Array to clear.
      */
     uploadAnnotationLines3D(vertices) {
-        if (!this.section2DOverlayRenderer)
-            return;
-        this.section2DOverlayRenderer.uploadAnnotationLines3D(vertices);
-        // Contribute annotation extents to modelBounds + camera sceneBounds
-        // so an annotation-only model (no IfcProduct meshes — common for
-        // separate "annotation sheets") gets framed by Home / fit-to-view
-        // AND has correct near/far clipping. Without sceneBounds the camera
-        // frustum doesn't include the annotation cluster and they're clipped
-        // away even when the camera is pointed at them. Mirror the
-        // point-cloud upload path (`addPointClouds`, `setPointClouds`) which
-        // does the same thing.
-        this.expandModelBoundsWithFlatVertices(vertices, 3);
-        if (this.modelBounds)
-            this.camera.setSceneBounds(this.modelBounds);
-        this.requestRender();
-    }
-    /** Walks a flat `[x,y,z,x,y,z,...]` vertex buffer and either initialises
-     *  or expands the cached `modelBounds` AABB. Used by the annotation
-     *  overlay upload paths so symbolic-only models can still be framed.
-     *
-     *  The geometry pipeline pre-seeds a placeholder `[-100, 100]` cube on
-     *  every render when there are 0 meshes (so the section-plane slider
-     *  always has a workable range). For an annotation-only model that
-     *  fallback drowns out the much-smaller annotation cluster and a plain
-     *  "expand" would no-op. We detect the placeholder by its exact symmetric
-     *  signature and replace it with the actual annotation AABB instead. */
-    expandModelBoundsWithFlatVertices(positions, stride) {
-        if (positions.length === 0)
-            return;
-        const isPlaceholderCube = (b) => b.min.x === -100 && b.min.y === -100 && b.min.z === -100
-            && b.max.x === 100 && b.max.y === 100 && b.max.z === 100;
-        if (!this.modelBounds || isPlaceholderCube(this.modelBounds)) {
-            this.modelBounds = {
-                min: { x: Infinity, y: Infinity, z: Infinity },
-                max: { x: -Infinity, y: -Infinity, z: -Infinity },
-            };
-        }
-        let expanded = false;
-        for (let i = 0; i + 2 < positions.length; i += stride) {
-            const x = positions[i];
-            const y = positions[i + 1];
-            const z = positions[i + 2];
-            if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z))
-                continue;
-            if (x < this.modelBounds.min.x)
-                this.modelBounds.min.x = x;
-            if (y < this.modelBounds.min.y)
-                this.modelBounds.min.y = y;
-            if (z < this.modelBounds.min.z)
-                this.modelBounds.min.z = z;
-            if (x > this.modelBounds.max.x)
-                this.modelBounds.max.x = x;
-            if (y > this.modelBounds.max.y)
-                this.modelBounds.max.y = y;
-            if (z > this.modelBounds.max.z)
-                this.modelBounds.max.z = z;
-            expanded = true;
-        }
-        if (!expanded)
-            return;
-        // Guarantee non-degenerate extent on every axis so camera frustums
-        // don't collapse. 0.5 m margin matches what the section-plane fallback
-        // uses elsewhere in this file.
-        for (const axis of ['x', 'y', 'z']) {
-            if (this.modelBounds.max[axis] - this.modelBounds.min[axis] < 1e-3) {
-                this.modelBounds.max[axis] += 0.5;
-                this.modelBounds.min[axis] -= 0.5;
-            }
-        }
+        this.overlays.uploadAnnotationLines3D(vertices);
     }
     /**
      * Clear the standalone annotation line overlay.
      */
     clearAnnotationLines3D() {
-        if (this.section2DOverlayRenderer) {
-            this.section2DOverlayRenderer.clearAnnotationLines3D();
-            this.requestRender();
-        }
+        this.overlays.clearAnnotationLines3D();
     }
     /**
      * Upload IfcAlignment centerline segments as a flat [x,y,z,x,y,z,...]
@@ -2971,22 +2842,11 @@ export class Renderer {
      * to match IfcGrid / IfcAnnotation. Pass an empty Float32Array to clear.
      */
     uploadAlignmentLines3D(vertices) {
-        if (!this.section2DOverlayRenderer)
-            return;
-        this.section2DOverlayRenderer.uploadAlignmentLines3D(vertices);
-        // Frame alignment-only files the same way annotation overlays are
-        // framed (see uploadAnnotationLines3D).
-        this.expandModelBoundsWithFlatVertices(vertices, 3);
-        if (this.modelBounds)
-            this.camera.setSceneBounds(this.modelBounds);
-        this.requestRender();
+        this.overlays.uploadAlignmentLines3D(vertices);
     }
     /** Clear the alignment centerline overlay. */
     clearAlignmentLines3D() {
-        if (this.section2DOverlayRenderer) {
-            this.section2DOverlayRenderer.clearAlignmentLines3D();
-            this.requestRender();
-        }
+        this.overlays.clearAlignmentLines3D();
     }
     /**
      * Upload structural-grid (IfcGridAxis) segments as a flat [x,y,z,x,y,z,...]
@@ -2998,17 +2858,27 @@ export class Renderer {
      * grid axes routinely extend past the model envelope).
      */
     uploadGridLines3D(vertices) {
-        if (!this.section2DOverlayRenderer)
-            return;
-        this.section2DOverlayRenderer.uploadGridLines3D(vertices);
-        this.requestRender();
+        this.overlays.uploadGridLines3D(vertices);
     }
     /** Clear the structural-grid overlay. */
     clearGridLines3D() {
-        if (this.section2DOverlayRenderer) {
-            this.section2DOverlayRenderer.clearGridLines3D();
-            this.requestRender();
-        }
+        this.overlays.clearGridLines3D();
+    }
+    /**
+     * Upload the DXF reference-layer's line paths as a flat
+     * [x,y,z,x,y,z,...] line-list in world space (issue #2043, follow-up to
+     * the 2D-only DXF underlay from #1782/#1929). Mirrors
+     * `uploadGridLines3D`: a dedicated buffer so 3D DXF visibility is
+     * independent of the 2D underlay's own toggle, and does NOT expand
+     * model bounds/reframe the camera on upload — it's behind its own
+     * visibility toggle, like grid axes. Pass an empty Float32Array to clear.
+     */
+    uploadDxfLines3D(vertices) {
+        this.overlays.uploadDxfLines3D(vertices);
+    }
+    /** Clear the 3D DXF reference-layer overlay. */
+    clearDxfLines3D() {
+        this.overlays.clearDxfLines3D();
     }
     /**
      * Show (or clear) the clash-overlap box: the wireframe AABB of a focused
@@ -3017,16 +2887,7 @@ export class Renderer {
      * clear. `min`/`max` are world-space corners (clash works in world frame).
      */
     setClashOverlapBox(box) {
-        if (!this.section2DOverlayRenderer)
-            return;
-        if (!box) {
-            this.section2DOverlayRenderer.clearClashBoxLines3D();
-            this.requestRender();
-            return;
-        }
-        this.section2DOverlayRenderer.setClashBoxLineColor(box.color);
-        this.section2DOverlayRenderer.uploadClashBoxLines3D(aabbEdgeLineList(box.min, box.max));
-        this.requestRender();
+        this.overlays.setClashOverlapBox(box);
     }
     /**
      * Draw the focused clash's CONTACT geometry as 3D line segments — the real
@@ -3036,73 +2897,27 @@ export class Renderer {
      * buffer, so only one of this / setClashOverlapBox is shown at a time.
      */
     setClashContactLines(lines) {
-        if (!this.section2DOverlayRenderer)
-            return;
-        if (!lines || lines.vertices.length === 0) {
-            this.section2DOverlayRenderer.clearClashBoxLines3D();
-            this.requestRender();
-            return;
-        }
-        this.section2DOverlayRenderer.setClashBoxLineColor(lines.color);
-        this.section2DOverlayRenderer.uploadClashBoxLines3D(lines.vertices);
-        this.requestRender();
+        this.overlays.setClashContactLines(lines);
     }
     /**
      * Upload filled IfcAnnotation regions for the symbolic overlay
      * (issue #653). Pass an empty array to clear.
      */
     uploadAnnotationFills3D(fills) {
-        if (!this.symbolicFillPipeline)
-            return;
-        this.symbolicFillPipeline.upload(fills);
-        // Contribute fill extents to modelBounds — see uploadAnnotationLines3D.
-        for (const fill of fills) {
-            const pts = fill.points;
-            if (pts.length === 0)
-                continue;
-            // points are flat [x,z,x,z,...]; lift to (x, fill.worldY, z) per
-            // vertex so we expand bounds in the same world space the renderer draws in.
-            const lifted = new Float32Array((pts.length / 2) * 3);
-            for (let i = 0, j = 0; i < pts.length; i += 2, j += 3) {
-                lifted[j] = pts[i];
-                lifted[j + 1] = fill.worldY;
-                lifted[j + 2] = pts[i + 1];
-            }
-            this.expandModelBoundsWithFlatVertices(lifted, 3);
-        }
-        if (this.modelBounds)
-            this.camera.setSceneBounds(this.modelBounds);
-        this.requestRender();
+        this.overlays.uploadAnnotationFills3D(fills);
     }
     /**
      * Upload IfcAnnotation text labels for the symbolic overlay
      * (issue #653). Pass an empty array to clear.
      */
     uploadAnnotationTexts3D(texts) {
-        if (!this.symbolicTextPipeline)
-            return;
-        this.symbolicTextPipeline.upload(texts);
-        // Text origins are single points; pack them into a flat buffer and
-        // expand bounds. Glyph extents are small enough that origin-only
-        // suffices for framing.
-        if (texts.length > 0) {
-            const buf = new Float32Array(texts.length * 3);
-            for (let i = 0; i < texts.length; i++) {
-                buf[i * 3 + 0] = texts[i].worldPos[0];
-                buf[i * 3 + 1] = texts[i].worldPos[1];
-                buf[i * 3 + 2] = texts[i].worldPos[2];
-            }
-            this.expandModelBoundsWithFlatVertices(buf, 3);
-            if (this.modelBounds)
-                this.camera.setSceneBounds(this.modelBounds);
-        }
-        this.requestRender();
+        this.overlays.uploadAnnotationTexts3D(texts);
     }
     /**
      * Check if 2D section overlay has geometry to render
      */
     hasSection2DOverlay() {
-        return this.section2DOverlayRenderer?.hasGeometry() ?? false;
+        return this.overlays.hasSection2DOverlay();
     }
     /**
      * Get render pipeline (for batching)
@@ -3193,18 +3008,9 @@ export class Renderer {
         this.edlPass = null;
         this.skyPass?.destroy();
         this.skyPass = null;
-        // Section-plane renderers
-        this.sectionPlaneRenderer?.destroy();
-        this.sectionPlaneRenderer = null;
-        this.section2DOverlayRenderer?.dispose();
-        this.section2DOverlayRenderer = null;
-        // Symbolic annotation overlay pipelines own their own GPU buffers,
-        // sampler, and atlas texture — recreating the viewer without
-        // releasing them leaks resources on every reload.
-        this.symbolicFillPipeline?.destroy();
-        this.symbolicFillPipeline = null;
-        this.symbolicTextPipeline?.destroy();
-        this.symbolicTextPipeline = null;
+        // Section-plane gizmo, 2D section overlay and the symbolic annotation
+        // pipelines — see RendererOverlays.destroy().
+        this.overlays.destroy();
         // Point cloud GPU resources
         this.pointCloudRenderer?.clear();
         this.pointCloudRenderer = null;