@ifc-lite/renderer 3.1.0 → 4.2.0

package/dist/index.js

@@ -11,7 +11,7 @@ export { appearanceSourceTriangle, expandAppearanceCorners, equivalentAppearance
 export { sameCompanionParts } from './appearance-companions.js';
 export { invertAppearancePartition, validateAppearancePartition } from './appearance-preview.js';
 import { createReferenceImageManager } from './reference-image-host.js';
-import { resizeRendererViewport } from './renderer-viewport.js';
+import { measureDrawingBuffer, resizeRendererViewport } from './renderer-viewport.js';
 export { pickFitPolicy } from './camera-fit-policy.js';
 // `Scene` is NOT exported: an exported class republishes every method `SceneContents` above just froze.
 export { Picker } from './picker.js';
@@ -79,71 +79,42 @@ import { Scene } from './scene.js';
 import { Picker } from './picker.js';
 import { reportableItemId } from './pick-resolve.js';
 import { MathUtils, viewBasis } from './math.js';
-import { FrustumUtils } from '@ifc-lite/spatial';
-import { VisualEnhancementResolver } from './visual-enhancement.js';
+import { isRteAabbVisible, rteFrustum, sourceFrustumFromRte } from './rte-frustum.js';
+import { VisualEnhancementResolver, livePostEffects } from './visual-enhancement.js';
 import { packClipBox } from './clip-box.js';
+import { MESH_FLAGS_BYTE_OFFSET, MESH_FLAG_RTE_DRAWABLE, MESH_UNIFORM_FLOATS, MESH_UNIFORM_OFFSET, packRteCameraOrigin, packRteFragmentSpace, } from './mesh-rte-uniforms.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 { PostPassChain } from './post-pass-chain.js';
 import { InteractionEffectsGovernor } from './interaction-effects-governor.js';
 import { VisibilityEpochTracker } from './visibility-epoch.js';
 import { isEntityVisible } from './entity-visibility.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';
 import { skyShaderSource } from './shaders/sky.wgsl.js';
 import { resolveEnvironment } from './environment.js';
 import { ShadowPass, resolveShadowMapResolution } from './shadow-pass.js';
-import { fitSunLightMatrix, cameraFrustumFocusCorners } from './shadow-light-matrix.js';
-import { collectShadowOccluders, classifyBatchVisibility, DEFAULT_MIN_CAST_ALPHA } from './shadow-occluders.js';
+import { fitSunLightMatrix, cameraFrustumFocusCorners, resolveShadowNormalBiasMetres } from './shadow-light-matrix.js';
+import { collectShadowOccluders } from './shadow-occluders.js';
+import { uploadInstancedRteDeltas } from './instanced-rte.js';
+import { shadowOccluderBatches } from './shadow-occluder-batches.js';
+import { captureRendererScreenshot } from './renderer-screenshot.js';
+import { beginRendererColorFrameCapture, cancelRendererColorFrame, discardRendererColorFrameReadback, encodeRendererColorFrameCapture, requestRendererColorFrame, retryRendererColorFrame, settleRendererColorFrameCapture } from './renderer-color-readback.js';
 import { shouldRouteMeshTransparent, shouldRouteBatchTransparent, splitVisibleIdsByPromotion, DEFAULT_GHOST_ALPHA } from './overlay-routing.js';
 import { XRayAlpha, XRayEpochTracker } from './xray-alpha.js';
 import { PartialBatchRequests } from './partial-batch-requests.js';
 import { colorSaltByte, packEntityLane } from './scene-geometry.js';
 import { PointCloudRenderer } from './pointcloud/point-cloud-renderer.js';
+import { appendPointCloudChunk as appendPointCloudChunkImpl, beginPointCloudStream as beginPointCloudStreamImpl, endPointCloudStream as endPointCloudStreamImpl, removePointCloudAsset as removePointCloudAssetImpl, } from './pointcloud/point-cloud-stream-lifecycle.js';
 import { DeviationComputer } from './deviation/deviation-computer.js';
+import { runGuardedGpuUpload, isDeviceLossThrow } from './gpu-upload-guard.js';
+import { recoverRendererDevice, rendererDeviceLostError } from './device-recovery.js';
 const MAX_ENCODED_ENTITY_ID = 0xFFFFFF;
 let warnedEntityIdRange = false;
-/**
- * Is this throw the GPU device telling us it is gone?
- *
- * The discriminator is the exception TYPE, not its message, because WebGPU
- * draws exactly that line:
- *  - a call on a dead / invalid-state device throws a `DOMException`
- *    (`InvalidStateError` in Safari 26.5 — the whole of issue #2229);
- *  - a buffer allocation the host cannot back throws a plain `RangeError`
- *    ("createBuffer failed, size (…) is too large … when mappedAtCreation ==
- *    true"), which `gpu-upload-guard` documents happening on a HEALTHY device
- *    under memory pressure.
- *
- * Treating the second as a device loss is a false positive that costs the whole
- * session, so only the first latches; everything else degrades one frame.
- *
- * There is deliberately NO consecutive-failure threshold as a middle ground.
- * Not because failures necessarily arrive back-to-back — between two BCF / IDS
- * capture frames the awaited `camera.frameBounds` normally does let an ordinary
- * rAF frame through, which would reset a counter — but because those ordinary
- * frames are not guaranteed to SUCCEED: they allocate too (`ensureMeshResources`
- * creates a buffer per unresourced mesh, and the queued-mesh flush allocates),
- * so under sustained host memory pressure any finite budget is still reachable.
- * A latch whose safety depends on incidental animation timing is the wrong
- * shape of guarantee for "never kill the viewport by mistake".
- *
- * Real losses on browsers that do not throw are still caught by the async
- * `device.lost` promise — which the WebGPU spec makes the sole loss channel
- * anyway (on a conformant engine, calls against a lost device are no-ops, not
- * throws; Safari 26.5's synchronous throw is the deviation being handled here).
- *
- * `typeof` guarded because non-DOM hosts (Node before 17, some workers) have no
- * `DOMException` global; there, no throw can be a WebGPU device signal anyway.
- */
-function isDeviceLossThrow(error) {
-    return typeof DOMException !== 'undefined' && error instanceof DOMException;
-}
 /**
  * The reason `whenReady()` rejects when the renderer is destroyed.
  *
@@ -157,20 +128,6 @@ function rendererDestroyedError() {
     error.name = 'RendererDestroyedError';
     return error;
 }
-/**
- * The reason `whenReady()` rejects once the GPU device has been lost.
- *
- * Deliberately NOT `RendererDestroyedError`: a destroyed renderer is finished,
- * while a lost one is dead only until the host re-initialises it (`init()`
- * clears the latch and readiness is published again). A caller that wants to
- * retry needs to tell those apart, so the loss carries its own `name` — same
- * plain-`Error` shape, for the same reasons.
- */
-function rendererDeviceLostError() {
-    const error = new Error('GPU device was lost before the renderer became ready');
-    error.name = 'RendererDeviceLostError';
-    return error;
-}
 /**
  * Main renderer class
  */
@@ -190,6 +147,7 @@ export class Renderer {
     overlays = new RendererOverlays({
         getModelBounds: () => this.getModelBounds(),
         expandModelBoundsWithFlatVertices: (positions, stride) => this.modelBoundsTracker.expandWithFlatVertices(positions, stride),
+        expandModelBoundsWithAnchoredLineVertices: (positions, origin, stride) => this.modelBoundsTracker.expandWithAnchoredVertices(positions, origin, stride),
         syncCameraSceneBounds: () => {
             if (this.modelBounds)
                 this.camera.setSceneBounds(this.modelBounds);
@@ -198,9 +156,12 @@ export class Renderer {
     });
     referenceImages = createReferenceImageManager(this);
     getReferenceImages() { return this.referenceImages; }
-    postProcessor = null;
+    // Ambient occlusion, separation lines and eye-dome lighting (post-pass-chain.ts),
+    // created on the first rendered frame.
+    postPasses = null;
+    /** Device px per CSS px in the drawing buffer; CSS-px sizes scale by it (#5383). */
+    pixelRatio = 1;
     interactionEffects = new InteractionEffectsGovernor();
-    edlPass = null;
     // Procedural sky background — created lazily on the first frame that
     // enables it (most sessions never do).
     skyPass = null;
@@ -219,8 +180,10 @@ export class Renderer {
         highQuality: true,
     };
     pointCloudRenderer = null;
-    /**
-     * Set true at the end of the LATEST `init()`; gates `whenReady()` and
+    pointCloudStreamEpoch = 0;
+    pointCloudStreamEpochs = new Map(); // handle id → epoch; cleanup rebuilds `{ id }`, cleared per epoch
+    pointCloudNextHandleId = 1; // watermark carried across teardown() so a replacement never reissues an id
+    /** 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
@@ -242,19 +205,18 @@ export class Renderer {
      */
     destroyed = false;
     /**
-     * The tail of the `init()` queue. `init()` chains onto this rather than
-     * running immediately, so two overlapping calls cannot both walk past the
-     * "a previous init completed" guard while the first is still awaiting its
-     * device and both allocate a full set of GPU objects (#2448). Always
-     * settled fulfilled — a rejected init is swallowed HERE (never for the
-     * caller) so one failure does not deadlock every later call.
+     * The tail of the GPU lifecycle queue. `init()` and `recoverDevice()` chain
+     * onto this rather than running immediately, so overlapping calls cannot
+     * both mutate the shared device/pipeline fields while one is awaiting its
+     * adapter. Always settled fulfilled — a rejected operation is swallowed
+     * HERE (never for its caller) so one failure cannot deadlock later work.
      */
     initChain = Promise.resolve();
     /**
-     * Incremented synchronously by every `init()` call AND by every public
-     * `destroy()`. It stamps "the lifecycle event an in-flight init belongs to":
-     * an init that no longer carries the current stamp has been superseded and
-     * must neither allocate nor publish readiness.
+     * Incremented synchronously by every `init()` / `recoverDevice()` call and
+     * by every public `destroy()`. It stamps the lifecycle event an in-flight
+     * operation belongs to: stale work must neither allocate nor publish
+     * readiness.
      *
      * Both bumps are load-bearing, for the same reason. Because the queue above
      * defers the body, an init can finish while a later one is still waiting its
@@ -312,6 +274,10 @@ export class Renderer {
     /** Retained so a listener registered AFTER the loss still learns of it. */
     deviceLostInfo = null;
     deviceLostListeners = new Set();
+    deviceLossSequence = 0;
+    recovery = {
+        inFlight: null, lostReferenceImages: false, quantizedBatchesRequested: false, omissions: new Set(), pointCloudOptions: null,
+    };
     /** BIM ↔ scan deviation: owns the compute pipeline + its BVH cache. */
     deviationComputer = new DeviationComputer();
     visualEnhancementResolver = new VisualEnhancementResolver();
@@ -425,13 +391,9 @@ export class Renderer {
     // One-shot log guard — prints Y-up clip bounds on first section-enable so
     // users can confirm the slider is operating on the intended range.
     _loggedSectionBounds = false;
-    // Pooled per-frame buffers to avoid GC pressure from per-batch Float32Array allocations
-    // A single 224-byte uniform buffer (56 floats) is reused for all batches/meshes within a frame
-    // (48 floats viewProj…flags + 8 floats clipBoxMin/clipBoxMax)
-    // 60 floats = the WGSL Uniforms struct incl. quantParams (see
-    // pipeline.getUniformBufferSize).
-    uniformScratch = new Float32Array(60);
-    uniformScratchU32 = new Uint32Array(this.uniformScratch.buffer, 176, 4);
+    // One 336-byte buffer serves all frame batches/meshes (84 floats including RTE lanes).
+    uniformScratch = new Float32Array(MESH_UNIFORM_FLOATS);
+    uniformScratchU32 = new Uint32Array(this.uniformScratch.buffer, MESH_FLAGS_BYTE_OFFSET, 4);
     // What the last render() actually clipped, so the GPU picker can mirror it and
     // section/crop-clipped geometry stays unpickable, not just invisible. Updated
     // every render; read by pick()/pickRect(). null = nothing clipped that frame.
@@ -453,8 +415,8 @@ export class Renderer {
      * 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
+     * two render pipelines, the picker, the post passes, the point-cloud and
+     * deviation pipelines and the overlay layer's glyph atlas, per
      * recovery (#2448). Making the method self-safe is cheaper than trusting
      * every future caller to remember.
      *
@@ -486,7 +448,7 @@ export class Renderer {
         this.initChain = run.then(() => undefined, () => undefined);
         return run;
     }
-    async initOnce(generation) {
+    async initOnce(generation, options = {}) {
         // `pipeline` is the marker for "a previous init() completed": it is
         // assigned unconditionally there and nulled by destroy().
         if (this.pipeline !== null) {
@@ -504,16 +466,21 @@ export class Renderer {
         // the generation and this body running is stamped with the generation
         // that is clearing it. `deviceLostGeneration` deliberately keeps its
         // stale value — it is only ever read alongside this flag.
-        this.deviceLost = false;
-        // Subscribe before the device exists so a loss during the first frames
-        // is never missed — the handler is only invoked when `device.lost`
-        // actually resolves (a real fault), long after init in practice.
-        this.device.onDeviceLost((info) => this.handleDeviceLost(info));
-        await this.device.init(this.canvas);
+        if (options.clearDeviceLost !== false)
+            this.deviceLost = false;
+        // Subscribe before init so a loss during the first frames is not missed.
+        const initializingDevice = this.device;
+        initializingDevice.onDeviceLost((info) => {
+            // Ignore a delayed loss from a wrapper recovery already replaced.
+            if (this.device !== initializingDevice)
+                return;
+            this.handleDeviceLost(info, { fromDevicePromise: true });
+        });
+        await initializingDevice.init(this.canvas);
         // A `destroy()` (or a newer `init()`) landed while we were parked on the
         // device. Everything below allocates a full GPU stack — two pipelines,
-        // the picker, the post-processor, the point-cloud and deviation
-        // pipelines, the EDL pass, the overlay glyph atlas — and this aborted
+        // the picker, the point-cloud and deviation pipelines, 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
@@ -523,15 +490,15 @@ export class Renderer {
             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).
-        const rect = this.canvas.getBoundingClientRect();
+        // Size the buffer to the element's device pixels, the same sizing every
+        // frame applies (#5383); an unlaid-out canvas keeps its attributes. Both
+        // are clamped to the GPU's max 2D texture dimension so the initial
+        // pipeline allocations can't overflow on tall/wide layouts.
         const maxDim = this.device.getMaxTextureDimension();
-        const rawWidth = this.canvas.width || Math.max(1, Math.floor(rect.width));
-        const rawHeight = this.canvas.height || Math.max(1, Math.floor(rect.height));
-        const width = Math.min(rawWidth, maxDim);
-        const height = Math.min(rawHeight, maxDim);
+        const measured = measureDrawingBuffer(this.canvas, maxDim);
+        this.pixelRatio = measured?.pixelRatio ?? 1;
+        const width = Math.max(1, Math.min(measured?.width ?? this.canvas.width, maxDim));
+        const height = Math.max(1, Math.min(measured?.height ?? this.canvas.height, maxDim));
         // Set pixel dimensions if not already set, or if we clamped them down
         if (!this.canvas.width || !this.canvas.height || this.canvas.width !== width || this.canvas.height !== height) {
             this.canvas.width = width;
@@ -541,25 +508,11 @@ export class Renderer {
         this.picker = new Picker(this.device, width, height);
         this.overlays.init(this.device.getDevice(), this.device.getFormat(), this.pipeline.getSampleCount());
         this.referenceImages.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 {
-            this.postProcessor = new PostProcessor(this.device, {
-                enableContactShading: true,
-                contactRadius: 1.0,
-                contactIntensity: 0.3,
-            }, this.pipeline.getSampleCount());
-        }
-        catch (e) {
-            console.warn('[Renderer] PostProcessor init failed (post-processing disabled):', e);
-            this.postProcessor = null;
-        }
-        this.pointCloudRenderer = new PointCloudRenderer(this.device.getDevice(), this.device.getFormat(), 'depth24plus-stencil8', this.pipeline.getSampleCount());
+        this.pointCloudRenderer = new PointCloudRenderer(this.device.getDevice(), this.device.getFormat(), 'depth24plus-stencil8', this.pipeline.getSampleCount(), this.pointCloudNextHandleId);
         // Compute pipeline for the BIM↔scan deviation heatmap. Lazily
         // owns the per-triangle BVH GPU buffers; idle until the first
         // `computeDeviations` call.
         this.deviationComputer.init(this.device.getDevice());
-        this.edlPass = new EdlPass(this.device, this.pipeline.getSampleCount());
         this.camera.setAspect(width / height);
         // Update picking manager with initialized picker
         this.pickingManager.setPicker(this.picker);
@@ -587,7 +540,8 @@ export class Renderer {
         // from the GPU click-pick provider above, since raycastScene* is
         // synchronous CPU code while pick() is an async GPU readback.
         this.raycastEngine.setPointCloudProvider(() => this.pointCloudRenderer?.getRayQuerySources() ?? []);
-        this.markReady(generation);
+        if (options.publishReady !== false)
+            this.markReady(generation);
     }
     /**
      * Resolves once `init()` has finished and the GPU device + point-cloud
@@ -719,10 +673,34 @@ export class Renderer {
     isDeviceLost() {
         return this.deviceLost;
     }
-    handleDeviceLost(info) {
-        if (this.deviceLost)
+    recoverDevice() {
+        return recoverRendererDevice(this);
+    }
+    /**
+     * `onLossDetected` for every `runGuardedGpuUpload` call below (#4885):
+     * a synchronous Safari-style `DOMException` (issue #2229) caught OUTSIDE
+     * `render()` never otherwise reaches `handleDeviceLost` — only the async
+     * `device.lost` promise and `render()`'s own catch do — so without this,
+     * `isDeviceLost()` would keep answering false and every later upload on
+     * this path would keep failing against the same dead device.
+     */
+    reportUploadLoss(error) {
+        this.handleDeviceLost({
+            message: error instanceof Error ? error.message : String(error),
+            reason: 'gpu-upload-exception',
+        });
+    }
+    handleDeviceLost(info, options = {}) {
+        // Latched: only the current device's `device.lost` signal is a replacement loss; anything else is a duplicate report.
+        if (this.deviceLost) {
+            if (options.fromDevicePromise)
+                this.deviceLossSequence++;
             return;
+        }
+        this.deviceLossSequence++;
         this.deviceLost = true;
+        cancelRendererColorFrame(this);
+        this.recovery.lostReferenceImages = this.referenceImages.hasImages();
         this.referenceImages.destroy();
         this.deviceLostGeneration = this.initGeneration;
         this.deviceLostInfo = info;
@@ -781,11 +759,13 @@ export class Renderer {
         // 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
+        // `scene.getOrCreatePartialBatch()`, and both merge geometry into
+        // fresh typed arrays, whose allocation throws a plain `RangeError`
+        // ("Array buffer allocation failed") under host memory pressure.
+        // (Before #5429 the GPU upload itself added a second source, the
+        // mapped-at-creation `createBuffer` RangeError; uploads now go through
+        // `createStaticGpuBuffer`, which cannot raise it.) 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.
         //
@@ -894,28 +874,16 @@ export class Renderer {
      * chunks will arrive (currently a no-op but kept for symmetry).
      */
     beginPointCloudStream(meta) {
-        if (!this.pointCloudRenderer) {
-            throw new Error('Renderer not initialized. Call init() first.');
-        }
-        return this.pointCloudRenderer.beginAsset(meta);
+        return beginPointCloudStreamImpl(this, meta);
     }
     appendPointCloudChunk(handle, chunk) {
-        if (!this.pointCloudRenderer)
-            return;
-        this.pointCloudRenderer.appendChunk(handle, chunk);
-        this.modelBoundsTracker.expandForPointClouds();
-        this.camera.setSceneBounds(this.modelBounds);
-        this.requestRender();
+        appendPointCloudChunkImpl(this, handle, chunk);
     }
     endPointCloudStream(handle) {
-        this.pointCloudRenderer?.endAsset(handle);
-        this.requestRender();
+        endPointCloudStreamImpl(this, handle);
     }
     removePointCloudAsset(handle) {
-        this.pointCloudRenderer?.removeAsset(handle);
-        // Bounds may have shrunk — recompute from scratch so fit-to-view
-        // and section-plane sliders see fresh extents.
-        this.refreshPlacementBounds();
+        removePointCloudAssetImpl(this, handle);
     }
     /**
      * Reassign a streamed point-cloud's expressId after upload. Use
@@ -948,12 +916,28 @@ export class Renderer {
         this.clearCaches();
         this.refreshPlacementBounds();
     }
+    /** Absolute workspace yaw about the render-frame pivot; GPU-instanced only (#4890). Skips invalidation on a no-op (#4890 review). */
+    setModelRotation(modelIndex, angle, pivot) {
+        const changed = this.scene.setModelRotation(modelIndex, angle, pivot);
+        if (!changed)
+            return false;
+        this.clearCaches();
+        this.refreshPlacementBounds();
+        return true;
+    }
     /** Streamed clouds are addressed by durable asset handle. */
     setPointCloudTranslation(handle, translation) {
         this.pointCloudRenderer?.setAssetTranslation(handle, translation);
         this.clearCaches();
         this.refreshPlacementBounds();
     }
+    /** Toggle one resident streamed scan without releasing its GPU buffers. */
+    setPointCloudVisibility(handle, visible) {
+        if (!this.pointCloudRenderer?.setAssetVisible(handle, visible))
+            return;
+        this.clearCaches();
+        this.refreshPlacementBounds();
+    }
     refreshPlacementBounds() {
         this.modelBoundsTracker.recompute();
         this.camera.setSceneBounds(this.modelBounds);
@@ -1012,22 +996,26 @@ export class Renderer {
      * @param geometry - Either a GeometryResult from geometry.process() or an array of MeshData
      */
     loadGeometry(geometry) {
-        if (!this.device.isInitialized() || !this.pipeline) {
+        if (this.isDeviceLost())
+            return { ok: false, reason: 'device-lost' }; // #4885: zombie device stays "initialized"
+        if (!this.device.isInitialized() || !this.pipeline)
             throw new Error('Renderer not initialized. Call init() first.');
-        }
         const meshes = Array.isArray(geometry) ? geometry : geometry.meshes;
         if (meshes.length === 0) {
             console.warn('[Renderer] loadGeometry called with empty mesh array');
-            return;
+            return { ok: true, value: undefined };
         }
-        // Use batched rendering for optimal performance
-        const device = this.device.getDevice();
-        this.scene.appendToBatches(meshes, device, this.pipeline, false);
-        // Calculate and store model bounds for fitToView
-        this.modelBoundsTracker.updateFromMeshes(meshes, (index) => this.scene.getModelTranslation(index));
-        console.log(`[Renderer] Loaded ${meshes.length} meshes`);
-        // Update camera scene bounds for tight orthographic near/far planes
-        this.camera.setSceneBounds(this.modelBounds);
+        const pipeline = this.pipeline;
+        return runGuardedGpuUpload(() => this.isDeviceLost(), () => {
+            // Use batched rendering for optimal performance
+            const device = this.device.getDevice();
+            this.scene.appendToBatches(meshes, device, pipeline, false);
+            // Calculate and store model bounds for fitToView
+            this.modelBoundsTracker.updateFromMeshes(meshes, (index) => this.scene.getModelTranslation(index));
+            console.log(`[Renderer] Loaded ${meshes.length} meshes`);
+            // Update camera scene bounds for tight orthographic near/far planes
+            this.camera.setSceneBounds(this.modelBounds);
+        }, (error) => this.reportUploadLoss(error));
     }
     /**
      * Add multiple meshes to the scene (convenience method for streaming)
@@ -1036,17 +1024,20 @@ export class Renderer {
      * @param isStreaming - If true, throttles batch rebuilding for better streaming performance
      */
     addMeshes(meshes, isStreaming = false) {
+        if (this.isDeviceLost())
+            return { ok: false, reason: 'device-lost' };
         if (!this.device.isInitialized() || !this.pipeline) {
             throw new Error('Renderer not initialized. Call init() first.');
         }
         if (meshes.length === 0)
-            return;
-        const device = this.device.getDevice();
-        this.scene.appendToBatches(meshes, device, this.pipeline, isStreaming);
-        // Update model bounds incrementally
-        this.modelBoundsTracker.updateFromMeshes(meshes, (index) => this.scene.getModelTranslation(index));
-        // Update camera scene bounds for tight orthographic near/far planes
-        this.camera.setSceneBounds(this.modelBounds);
+            return { ok: true, value: undefined };
+        const pipeline = this.pipeline;
+        return runGuardedGpuUpload(() => this.isDeviceLost(), () => {
+            const device = this.device.getDevice();
+            this.scene.appendToBatches(meshes, device, pipeline, isStreaming);
+            this.modelBoundsTracker.updateFromMeshes(meshes, (index) => this.scene.getModelTranslation(index));
+            this.camera.setSceneBounds(this.modelBounds);
+        }, (error) => this.reportUploadLoss(error));
     }
     /**
      * Fit camera to view all loaded geometry
@@ -1074,50 +1065,46 @@ export class Renderer {
      */
     addMesh(mesh) {
         if (!this.pipeline)
-            return;
-        // Create per-mesh uniform buffer and bind group if not already created
-        if (!mesh.uniformBuffer && this.device.isInitialized()) {
-            const device = this.device.getDevice();
-            // Create uniform buffer for this mesh
-            mesh.uniformBuffer = device.createBuffer({
-                size: this.pipeline.getUniformBufferSize(),
-                usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-            });
-            // Create bind group for this mesh
-            mesh.bindGroup = device.createBindGroup({
-                layout: this.pipeline.getBindGroupLayout(),
-                entries: [
-                    {
-                        binding: 0,
-                        resource: { buffer: mesh.uniformBuffer },
-                    },
-                ],
-            });
-        }
+            return { ok: true, value: undefined };
+        const pipeline = this.pipeline;
+        const outcome = (!mesh.uniformBuffer && !this.isDeviceLost() && this.device.isInitialized())
+            ? runGuardedGpuUpload(() => this.isDeviceLost(), () => {
+                const device = this.device.getDevice();
+                mesh.uniformBuffer = device.createBuffer({
+                    size: pipeline.getUniformBufferSize(),
+                    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+                });
+                mesh.bindGroup = device.createBindGroup({
+                    layout: pipeline.getBindGroupLayout(),
+                    entries: [{ binding: 0, resource: { buffer: mesh.uniformBuffer } }],
+                });
+            }, (error) => this.reportUploadLoss(error))
+            : { ok: true, value: undefined };
         this.scene.addMesh(mesh);
+        return outcome;
     }
     /**
      * Ensure all meshes have GPU resources (call after adding meshes if pipeline wasn't ready)
      */
     ensureMeshResources() {
         if (!this.pipeline || !this.device.isInitialized())
-            return;
-        const device = this.device.getDevice();
-        for (const mesh of this.scene.getMeshes()) {
-            if (!mesh.uniformBuffer) {
-                mesh.uniformBuffer = device.createBuffer({
-                    size: this.pipeline.getUniformBufferSize(),
-                    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
-                });
-                mesh.bindGroup = device.createBindGroup({
-                    layout: this.pipeline.getBindGroupLayout(),
-                    entries: [{
-                            binding: 0,
-                            resource: { buffer: mesh.uniformBuffer },
-                        }],
-                });
+            return { ok: true, value: undefined };
+        const pipeline = this.pipeline;
+        return runGuardedGpuUpload(() => this.isDeviceLost(), () => {
+            const device = this.device.getDevice();
+            for (const mesh of this.scene.getMeshes()) {
+                if (!mesh.uniformBuffer) {
+                    mesh.uniformBuffer = device.createBuffer({
+                        size: pipeline.getUniformBufferSize(),
+                        usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+                    });
+                    mesh.bindGroup = device.createBindGroup({
+                        layout: pipeline.getBindGroupLayout(),
+                        entries: [{ binding: 0, resource: { buffer: mesh.uniformBuffer } }],
+                    });
+                }
             }
-        }
+        }, (error) => this.reportUploadLoss(error));
     }
     /**
      * Get model bounds (used for section planes, fitToView, etc.)
@@ -1150,71 +1137,17 @@ export class Renderer {
      * collector drops them.
      */
     shadowOccluderBatches(options, device, hasVisibilityFiltering) {
-        const all = this.scene.getBatchedMeshes();
-        if (!hasVisibilityFiltering) {
-            for (const batch of all)
-                this.noteShadowOccluderResidency(batch);
-            return all;
-        }
-        const pipeline = this.pipeline;
-        const out = [];
-        for (const batch of all) {
-            const vis = classifyBatchVisibility(batch.expressIds, options.hiddenIds, options.isolatedIds);
-            if (vis.kind === 'none')
-                continue; // fully hidden → does not cast
-            if (vis.kind === 'all') {
-                this.noteShadowOccluderResidency(batch);
-                out.push(batch); // fully visible → its own buffers
-                continue;
-            }
-            // Partially hidden. Transparent parents don't cast (collector's alpha
-            // filter) — skip rather than build a wasted, divergent-key clone.
-            if (batch.color[3] < DEFAULT_MIN_CAST_ALPHA)
-                continue;
-            // The partial sub-batch is built from the PARENT's CPU meshData, so a
-            // cold parent yields nothing until it is restored. Queue that restore
-            // here too: the colour pass only queues it for parents inside its own
-            // frustum, but an up-sun occluder behind the camera still has to cast.
-            this.noteShadowOccluderResidency(batch);
-            // Opaque partial: reuse the colour pass's cached sub-batch. The key is
-            // visibility-content-independent; `_partialBatchEpoch` invalidates it on
-            // any hide/isolate or override change, so the clone is always current.
-            // Without a pipeline the renderer isn't drawing, so skip (the shadow
-            // pass won't run either); casting the whole parent would be wrong.
-            if (!pipeline)
-                continue;
-            const sub = this.scene.getOrCreatePartialBatch(`${batch.colorKey}:${batch.id}`, batch.colorKey, vis.visibleIds, device, pipeline, this._partialBatchEpoch);
-            // A cold parent yields an empty partial (its residency restore is queued
-            // above); skip this frame — the collector drops zero-index draws anyway,
-            // and the subset casts once resident.
-            if (sub && sub.indexCount > 0)
-                out.push(sub);
-        }
-        return out;
+        return shadowOccluderBatches(this.scene, options, device, hasVisibilityFiltering, this.pipeline, this._partialBatchEpoch);
     }
-    /**
-     * Keep a shadow occluder batch resident so it does not thin out silently on
-     * large models under the GPU residency budget (#2670 review). The depth pass
-     * reads these batches' buffers, but that read did not count as usage, so an
-     * up-sun occluder outside the colour frustum aged into an eviction candidate.
-     * Transparent batches never cast (the collector's alpha filter), so their
-     * residency is irrelevant here.
-     */
-    noteShadowOccluderResidency(batch) {
-        if (batch.color[3] < DEFAULT_MIN_CAST_ALPHA)
-            return;
-        if (batch.gpuResident === false) {
-            this.scene.requestBatchResidency(batch);
-        }
-        else {
-            this.scene.recordBatchDrawn(batch);
-        }
+    /** Guarded entry point (#4885) for the unguarded body below. */
+    createMeshFromData(meshData) {
+        return runGuardedGpuUpload(() => this.isDeviceLost(), () => this.createMeshFromDataUnguarded(meshData), (error) => this.reportUploadLoss(error));
     }
     /**
      * Create a GPU Mesh from MeshData (lazy creation for selection highlighting)
      * This is called on-demand when a mesh is selected, avoiding 2x buffer creation during streaming
      */
-    createMeshFromData(meshData) {
+    createMeshFromDataUnguarded(meshData) {
         if (!this.device.isInitialized())
             return;
         const device = this.device.getDevice();
@@ -1223,18 +1156,17 @@ export class Renderer {
         const interleaved = new Float32Array(interleavedRaw);
         const interleavedU32 = new Uint32Array(interleavedRaw);
         // Build this individual mesh (selection highlight + GPU object-id picker)
-        // in ABSOLUTE world space so it renders with an identity model matrix.
+        // in the same small local frame as its source batch.
         // CRITICAL: replicate the BATCH's exact two-step f32 path so the highlight
         // is bit-coincident with its source surface (no z-fight, no depth bias):
         //   batch stores  s = f32(local + (origin - sharedOrigin))   [merge]
-        //   batch shader  world = f32(f32(sharedOrigin) + s)         [draw]
-        // We compute the same `world` here. When there's no shared origin yet
-        // (legacy / pre-batch), fall back to a plain f64 fold (local + origin).
+        //   batch shader  RTE = sharedOrigin - eye + s               [draw]
+        // We retain `s` and the canonical origin separately. When there is no
+        // shared origin, retain the piece origin instead of folding it in.
         const o = meshData.origin;
-        const so = this.scene.getSharedFrameOrigin(meshData.modelIndex);
+        const so = this.scene.getSharedFrameOrigin(meshData.modelIndex, meshData);
         const ox = o ? o[0] : 0, oy = o ? o[1] : 0, oz = o ? o[2] : 0;
         const fr = Math.fround;
-        const sox = so ? fr(so[0]) : null, soy = so ? fr(so[1]) : 0, soz = so ? fr(so[2]) : 0;
         const dx = so ? (ox - so[0]) : ox, dy = so ? (oy - so[1]) : oy, dz = so ? (oz - so[2]) : oz;
         // Quantized batches (issue #1682 phase 6) render lattice-snapped
         // positions: the shader's quantMin + q*step is exactly the lattice
@@ -1251,9 +1183,9 @@ export class Renderer {
         for (let i = 0; i < vertexCount; i++) {
             const base = i * 7;
             const posBase = i * 3;
-            interleaved[base] = so ? fr(sox + snap(fr(p[posBase] + dx))) : snap(p[posBase] + dx);
-            interleaved[base + 1] = so ? fr(soy + snap(fr(p[posBase + 1] + dy))) : snap(p[posBase + 1] + dy);
-            interleaved[base + 2] = so ? fr(soz + snap(fr(p[posBase + 2] + dz))) : snap(p[posBase + 2] + dz);
+            interleaved[base] = so ? snap(fr(p[posBase] + dx)) : snap(p[posBase]);
+            interleaved[base + 1] = so ? snap(fr(p[posBase + 1] + dy)) : snap(p[posBase + 1]);
+            interleaved[base + 2] = so ? snap(fr(p[posBase + 2] + dz)) : snap(p[posBase + 2]);
             const hasNormals = meshData.normals.length > 0;
             interleaved[base + 3] = hasNormals ? meshData.normals[posBase] : 0;
             interleaved[base + 4] = hasNormals ? meshData.normals[posBase + 1] : 0;
@@ -1283,7 +1215,9 @@ export class Renderer {
             usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
         });
         device.queue.writeBuffer(indexBuffer, 0, meshData.indices);
-        // Add to scene with identity transform (positions already in world space).
+        // Keep the hydrated mesh in its decoded local frame.  Folding this
+        // origin back into f32 vertices used to make selection/highlight the
+        // only mesh path that lost centimetres at national-grid coordinates.
         // Flagged `hydrated` so it can be freed when its entity leaves the
         // selection — these duplicate geometry already drawn by a batch and would
         // otherwise accumulate + double-draw (see Scene.disposeHydratedMeshesExcept).
@@ -1298,7 +1232,14 @@ export class Renderer {
             vertexBuffer,
             indexBuffer,
             indexCount: meshData.indices.length,
-            transform: MathUtils.identity(),
+            transform: (() => {
+                const transform = MathUtils.identity();
+                transform.m[12] = so ? so[0] : ox;
+                transform.m[13] = so ? so[1] : oy;
+                transform.m[14] = so ? so[2] : oz;
+                return transform;
+            })(),
+            rteOrigin: so ? [so[0], so[1], so[2]] : [ox, oy, oz],
             color: meshData.color,
             hydrated: true,
         });
@@ -1416,6 +1357,7 @@ export class Renderer {
      * rejecting pipeline creation) batches stay on the f32 path.
      */
     async enableQuantizedBatches() {
+        this.recovery.quantizedBatchesRequested = true;
         if (!this.pipeline)
             return false;
         const ok = await this.pipeline.ensureQuantizedPipelines();
@@ -1457,6 +1399,7 @@ export class Renderer {
         // emit a stream of validation errors. Stay quiet until re-init.
         if (this.deviceLost) {
             this._renderSkipCount++;
+            cancelRendererColorFrame(this);
             return;
         }
         try {
@@ -1468,6 +1411,7 @@ export class Renderer {
             // as "did not fail" — see `frameContainedThrow`.
             if (!this.frameContainedThrow)
                 this.consecutiveDegradedFrames = 0;
+            retryRendererColorFrame(this, () => this.requestRender());
         }
         catch (error) {
             // Safari (26.5) reports device loss SYNCHRONOUSLY: a call against a
@@ -1483,6 +1427,7 @@ export class Renderer {
             // host down with us".
             this._renderSkipCount++;
             this.containFrameThrow(error, 'frame');
+            cancelRendererColorFrame(this);
         }
     }
     /**
@@ -1494,23 +1439,16 @@ export class Renderer {
             this._renderSkipCount++;
             return;
         }
-        // Validate canvas dimensions
-        // Align width to 64 pixels for WebGPU texture row alignment (256 bytes / 4 bytes per pixel)
-        // and clamp both axes to the GPU's max 2D texture dimension. Some hosts (e.g. tall iframes
-        // on high-DPR displays) can produce canvas dimensions that exceed 8192 and would otherwise
-        // make every depth/colour texture allocation a validation error.
-        const rect = this.canvas.getBoundingClientRect();
-        const maxDim = this.device.getMaxTextureDimension();
-        const rawWidth = Math.max(1, Math.floor(rect.width));
-        const widthAligned = Math.max(64, Math.floor(rawWidth / 64) * 64);
-        const width = Math.min(widthAligned, Math.floor(maxDim / 64) * 64);
-        const rawHeight = Math.max(1, Math.floor(rect.height));
-        const height = Math.min(rawHeight, maxDim);
-        // Skip rendering if canvas is too small
-        if (width < 64 || height < 10) {
+        // Drawing buffer = the element's device-pixel size (capped ratio, clamped
+        // to the GPU's max texture dimension); see computeDrawingBufferSize (#5383).
+        const measured = measureDrawingBuffer(this.canvas, this.device.getMaxTextureDimension());
+        // Skip rendering while the canvas is collapsed or too small.
+        if (!measured || measured.height < 10) {
             this._renderSkipCount++;
             return;
         }
+        const { width, height } = measured;
+        this.pixelRatio = measured.pixelRatio;
         // Update canvas pixel dimensions if needed
         const dimensionsChanged = this.canvas.width !== width || this.canvas.height !== height;
         if (dimensionsChanged) {
@@ -1534,6 +1472,13 @@ export class Renderer {
         }
         const device = this.device.getDevice();
         const viewProj = this.camera.getViewProjMatrix().m;
+        const relativeToEyeFrame = this.camera.getRelativeToEyeFrame();
+        // Culling must share the translation-free RTE frame used by every GPU
+        // pass. `sourceFrustum` is the f64 plane equivalent for the immutable
+        // source-space BVH; render-time boxes stay eye-relative below.
+        const rteCullFrustum = rteFrustum(relativeToEyeFrame);
+        const rteCullCamera = relativeToEyeFrame.getCameraWorld();
+        const sourceCullFrustum = sourceFrustumFromRte(rteCullFrustum, rteCullCamera);
         // Frame stats (issue #1682): geometry draw calls + per-frame cull
         // outcomes, snapshotted into _lastFrameStats before queue.submit.
         let frameDrawCalls = 0;
@@ -1573,11 +1518,8 @@ export class Renderer {
         const edgeIntensity = Math.min(3.0, Math.max(0.0, visualEnhancement.edgeContrast.intensity));
         const edgeEnabledU32 = edgeEnabled ? 1 : 0;
         const edgeIntensityMilliU32 = Math.round(edgeIntensity * 1000);
-        const contactEnabled = effectsLive && visualEnhancement.enabled && visualEnhancement.contactShading.quality !== 'off';
-        const separationEnabled = effectsLive && visualEnhancement.enabled
-            && visualEnhancement.separationLines.enabled
-            && visualEnhancement.separationLines.quality !== 'off';
-        const needsObjectIdPass = contactEnabled || separationEnabled;
+        // Only the separation lines read the object-id attachment after the pass.
+        const needsObjectIdPass = livePostEffects(visualEnhancement, effectsLive).separationLines;
         // Check if visibility filtering is active
         const hasHiddenFilter = options.hiddenIds && options.hiddenIds.size > 0;
         const hasIsolatedFilter = options.isolatedIds !== null && options.isolatedIds !== undefined;
@@ -1685,8 +1627,7 @@ export class Renderer {
         // Frustum culling (if enabled and spatial index available)
         if (options.enableFrustumCulling && options.spatialIndex) {
             try {
-                const frustum = FrustumUtils.fromViewProjMatrix(viewProj);
-                const visibleIds = new Set(options.spatialIndex.queryFrustum(frustum));
+                const visibleIds = new Set(options.spatialIndex.queryFrustum(sourceCullFrustum));
                 meshes = meshes.filter(mesh => visibleIds.has(mesh.expressId));
             }
             catch (error) {
@@ -1727,12 +1668,15 @@ export class Renderer {
             }
             return; // Skip this frame, context will be reconfigured next frame
         }
+        let colorCapture = null;
+        let colorReadback = null;
         try {
             const clearColor = options.clearColor
                 ? (Array.isArray(options.clearColor)
                     ? { r: options.clearColor[0], g: options.clearColor[1], b: options.clearColor[2], a: options.clearColor[3] }
                     : options.clearColor)
                 : { r: 0.1, g: 0.1, b: 0.1, a: 1 };
+            colorCapture = beginRendererColorFrameCapture(this, currentTexture, this.canvas.width, this.canvas.height, this.device.getFormat());
             const textureView = currentTexture.createView();
             const objectIdView = this.pipeline.getObjectIdTextureView();
             // Separate meshes into opaque and transparent
@@ -1806,6 +1750,8 @@ export class Renderer {
             for (const mesh of allMeshes) {
                 if (mesh.uniformBuffer) {
                     meshBuf.set(viewProj, 0);
+                    relativeToEyeFrame.packUniforms(meshBuf, MESH_UNIFORM_OFFSET.rteViewProj);
+                    packRteCameraOrigin(relativeToEyeFrame, meshBuf);
                     meshBuf.set(mesh.transform.m, 16);
                     // Check if mesh is selected (single or multi-selection)
                     // For multi-model support: also check modelIndex if provided
@@ -1846,6 +1792,13 @@ export class Renderer {
                             clipBit;
                     meshFlags[2] = edgeEnabledU32;
                     meshFlags[3] = edgeIntensityMilliU32;
+                    // Individual meshes retain their origin and share the RTE
+                    // fragment contract with colour batches.
+                    packRteFragmentSpace(relativeToEyeFrame, sectionPlaneData, options.clipBox, meshBuf);
+                    const meshOrigin = mesh.rteOrigin
+                        ?? [mesh.transform.m[12], mesh.transform.m[13], mesh.transform.m[14]];
+                    relativeToEyeFrame.packDrawableOrigin(meshOrigin, meshBuf, MESH_UNIFORM_OFFSET.drawableDelta);
+                    meshFlags[0] |= MESH_FLAG_RTE_DRAWABLE;
                     device.queue.writeBuffer(mesh.uniformBuffer, 0, meshBuf);
                 }
             }
@@ -1875,8 +1828,16 @@ export class Renderer {
                     else {
                         this.shadowPass.setResolution(resolution);
                     }
-                    const boundsMin = [bounds.min.x, bounds.min.y, bounds.min.z];
-                    const boundsMax = [bounds.max.x, bounds.max.y, bounds.max.z];
+                    // Fit shadows in the same eye-relative frame as vertices.
+                    const shadowEye = relativeToEyeFrame.getCameraWorld();
+                    const sourceBoundsMin = [bounds.min.x, bounds.min.y, bounds.min.z];
+                    const sourceBoundsMax = [bounds.max.x, bounds.max.y, bounds.max.z];
+                    const boundsMin = [
+                        bounds.min.x - shadowEye[0], bounds.min.y - shadowEye[1], bounds.min.z - shadowEye[2],
+                    ];
+                    const boundsMax = [
+                        bounds.max.x - shadowEye[0], bounds.max.y - shadowEye[1], bounds.max.z - shadowEye[2],
+                    ];
                     // Lateral shadow fit. AT REST: fit to the camera frustum
                     // clipped to the model (maintainer #1) so a small building on
                     // a large site keeps sharp shadows instead of spending the
@@ -1899,9 +1860,13 @@ export class Renderer {
                             aspect: this.canvas.height > 0 ? this.canvas.width / this.canvas.height : 1,
                             ortho: this.camera.getProjectionMode() === 'orthographic',
                             orthoHalfHeight: this.camera.getOrthoSize(),
-                            boundsMin,
-                            boundsMax,
-                        }) ?? undefined;
+                            boundsMin: sourceBoundsMin,
+                            boundsMax: sourceBoundsMax,
+                        })?.map((corner) => ({
+                            x: corner.x - shadowEye[0],
+                            y: corner.y - shadowEye[1],
+                            z: corner.z - shadowEye[2],
+                        }));
                     }
                     const sun = resolveEnvironment(options.environment).sunDirection;
                     const fit = fitSunLightMatrix({ sunDirection: sun, boundsMin, boundsMax, focusCorners });
@@ -1936,7 +1901,7 @@ export class Renderer {
                         box: options.clipBox?.enabled
                             ? { min: options.clipBox.min, max: options.clipBox.max }
                             : null,
-                    });
+                    }, { cameraWorld: shadowEye });
                     // Shadow uniform: light matrix + sampling params. The kernel
                     // width follows the sun's angular size (physical, ~0.53°
                     // like Blender's Sun lamp). Bias scales with the kernel: a
@@ -1946,7 +1911,7 @@ export class Renderer {
                     const texelWorld = (2 * fit.orthoHalfWidth) / resolution;
                     const sunAngleDeg = shadowOpts.sunAngleDeg ?? 0.53;
                     const pcfRadius = Math.min(Math.max(sunAngleDeg * 3.0, 0.75), 8.0);
-                    const normalBias = texelWorld * (2.0 + pcfRadius);
+                    const normalBias = resolveShadowNormalBiasMetres(texelWorld, pcfRadius);
                     const s = this.shadowScratch;
                     s.set(fit.lightViewProj.m, 0);
                     s[16] = 1 / resolution; // texelSize
@@ -2082,7 +2047,7 @@ export class Renderer {
             if (allBatchedMeshes.length > 0 || this.scene.getTexturedMeshes().length > 0 || this.scene.getInstancedTemplates().length > 0) {
                 // Frustum culling for batched meshes - skip entire batches outside the camera view
                 // This is the primary performance optimization for large models (200K+ meshes)
-                const frustum = FrustumUtils.fromViewProjMatrix(viewProj);
+                const frustum = rteCullFrustum;
                 // Contribution culling (issue #1682): skip batches whose world
                 // AABB projects below a pixel threshold. Disabled unless the
                 // caller opts in via options.contributionCull; the threshold is
@@ -2109,7 +2074,7 @@ export class Renderer {
                         mode: this.camera.getProjectionMode(),
                         fovYRadians: this.camera.getFOV(),
                         orthoHalfHeight: this.camera.getOrthoSize(),
-                        viewportHeightPx: this.canvas.height,
+                        viewportHeightPx: this.canvas.height / this.pixelRatio, // CSS px, like the thresholds
                     };
                 }
                 // Per-batch visibility (only meaningful while filtering is active).
@@ -2164,7 +2129,7 @@ export class Renderer {
                     // Frustum culling: skip batches entirely outside the camera view
                     if (batch.bounds) {
                         const batchAABB = { min: batch.bounds.min, max: batch.bounds.max };
-                        if (!FrustumUtils.isAABBVisible(frustum, batchAABB)) {
+                        if (!isRteAabbVisible(frustum, batchAABB, rteCullCamera)) {
                             frameBatchesFrustumCulled++;
                             continue; // Entire batch is off-screen
                         }
@@ -2260,6 +2225,8 @@ export class Renderer {
                 const tpl = this.uniformScratch;
                 const tplFlags = this.uniformScratchU32;
                 tpl.set(viewProj, 0);
+                relativeToEyeFrame.packUniforms(tpl, MESH_UNIFORM_OFFSET.rteViewProj);
+                packRteCameraOrigin(relativeToEyeFrame, tpl);
                 // Identity model matrix (positions already in world space)
                 tpl[16] = 1;
                 tpl[17] = 0;
@@ -2310,6 +2277,11 @@ export class Renderer {
                         tplClipBit;
                 tplFlags[2] = edgeEnabledU32;
                 tplFlags[3] = edgeIntensityMilliU32;
+                // Flat/quantized/textured batches enter WGSL in the single
+                // camera-relative frame. Their fragment clip inputs must use
+                // that same frame; mixing a local vertex with a 5,000 km f32
+                // world plane loses centimetre cuts before the comparison.
+                packRteFragmentSpace(relativeToEyeFrame, sectionPlaneData, options.clipBox, tpl);
                 // Helper function to render a batch — patches color into the shared template
                 const renderBatch = (batch) => {
                     if (!batch.bindGroup || !batch.uniformBuffer)
@@ -2329,6 +2301,11 @@ export class Renderer {
                     tpl[28] = o ? o[0] : 0;
                     tpl[29] = o ? o[1] : 0;
                     tpl[30] = o ? o[2] : 0;
+                    // The regular model matrix remains for absolute-space
+                    // fragment work (section/shadow); vertex projection uses
+                    // this f64-subtracted high/low origin instead.
+                    relativeToEyeFrame.packDrawableOrigin(o ?? [0, 0, 0], tpl, MESH_UNIFORM_OFFSET.drawableDelta);
+                    tplFlags[0] |= MESH_FLAG_RTE_DRAWABLE;
                     // Quantized dequantization params (issue #1682 phase 6);
                     // zeroed for f32 batches (their pipelines ignore them).
                     const qz = batch.quantized;
@@ -2408,7 +2385,7 @@ export class Renderer {
                     const kept = [];
                     for (const it of instancedTemplates) {
                         if (it.bounds) {
-                            if (!FrustumUtils.isAABBVisible(frustum, it.bounds)) {
+                            if (!isRteAabbVisible(frustum, it.bounds, rteCullCamera)) {
                                 frameInstancedFrustumCulled++;
                                 continue;
                             }
@@ -2426,11 +2403,12 @@ export class Renderer {
                     visibleInstanced = kept;
                 }
                 if (visibleInstanced.length > 0) {
+                    uploadInstancedRteDeltas(device, visibleInstanced, relativeToEyeFrame.getCameraWorld());
                     // Opaque instanced pass. flags.x bit 2 marks "instanced pass" so the
                     // shader routes per-instance opacity: opaque (or selected) occurrences
                     // draw here; translucent ones (lens/x-ray/compare overrides) are
                     // discarded and drawn in the transparent sub-pass below.
-                    this.pipeline.writeRawUniforms(tpl, 0x4);
+                    this.pipeline.writeRawUniforms(tpl, MESH_FLAG_RTE_DRAWABLE | 0x4);
                     pass.setPipeline(this.pipeline.getInstancedPipeline());
                     pass.setBindGroup(0, this.pipeline.getBindGroup());
                     pass.setBindGroup(1, this.pipeline.getEnvironmentBindGroup());
@@ -2490,6 +2468,8 @@ export class Renderer {
                         tpl[28] = tm.origin[0];
                         tpl[29] = tm.origin[1];
                         tpl[30] = tm.origin[2];
+                        relativeToEyeFrame.packDrawableOrigin(tm.origin, tpl, MESH_UNIFORM_OFFSET.drawableDelta);
+                        tplFlags[0] |= MESH_FLAG_RTE_DRAWABLE;
                         tpl[32] = txOverride ? txOverride[0] : tm.color[0];
                         tpl[33] = txOverride ? txOverride[1] : tm.color[1];
                         tpl[34] = txOverride ? txOverride[2] : tm.color[2];
@@ -2636,7 +2616,7 @@ export class Renderer {
                 if (visibleInstanced.length > 0 &&
                     this.scene.hasTransparentInstances() &&
                     instancedTransparentPipeline !== null) {
-                    this.pipeline.writeRawUniforms(tpl, 0x4 | 0x8);
+                    this.pipeline.writeRawUniforms(tpl, MESH_FLAG_RTE_DRAWABLE | 0x4 | 0x8);
                     pass.setPipeline(instancedTransparentPipeline);
                     pass.setBindGroup(0, this.pipeline.getBindGroup());
                     pass.setBindGroup(1, this.pipeline.getEnvironmentBindGroup());
@@ -2693,6 +2673,10 @@ export class Renderer {
                                 tplClipBit;
                         tplFlags[2] = edgeEnabledU32;
                         tplFlags[3] = edgeIntensityMilliU32;
+                        packRteFragmentSpace(relativeToEyeFrame, sectionPlaneData, options.clipBox, tpl);
+                        const transparentOrigin = mesh.rteOrigin ?? [mesh.transform.m[12], mesh.transform.m[13], mesh.transform.m[14]];
+                        relativeToEyeFrame.packDrawableOrigin(transparentOrigin, tpl, MESH_UNIFORM_OFFSET.drawableDelta);
+                        tplFlags[0] |= MESH_FLAG_RTE_DRAWABLE;
                         device.queue.writeBuffer(mesh.uniformBuffer, 0, tpl);
                         pass.setBindGroup(0, mesh.bindGroup);
                         pass.setVertexBuffer(0, mesh.vertexBuffer);
@@ -2753,6 +2737,10 @@ export class Renderer {
                             tplClipBit;
                     tplFlags[2] = edgeEnabledU32;
                     tplFlags[3] = edgeIntensityMilliU32;
+                    packRteFragmentSpace(relativeToEyeFrame, sectionPlaneData, options.clipBox, tpl);
+                    const selectedOrigin = mesh.rteOrigin ?? [mesh.transform.m[12], mesh.transform.m[13], mesh.transform.m[14]];
+                    relativeToEyeFrame.packDrawableOrigin(selectedOrigin, tpl, MESH_UNIFORM_OFFSET.drawableDelta);
+                    tplFlags[0] |= MESH_FLAG_RTE_DRAWABLE;
                     device.queue.writeBuffer(mesh.uniformBuffer, 0, tpl);
                     pass.setPipeline(this.pipeline.getSelectionPipeline());
                     pass.setBindGroup(0, mesh.bindGroup);
@@ -2800,65 +2788,55 @@ export class Renderer {
             // viewport size to convert pixel sizes into clip-space offsets.
             if (this.pointCloudRenderer && this.pointCloudRenderer.hasAssets()) {
                 this.pointCloudRenderer.draw(pass, {
-                    viewProj,
+                    viewProj: relativeToEyeFrame.getViewProjection().m,
+                    relativeToEyeFrame,
                     sectionPlane: sectionPlaneData
                         ? { ...sectionPlaneData, flipped: options.sectionPlane?.flipped === true }
                         : null,
-                    viewport: { width: this.canvas.width, height: this.canvas.height },
+                    clipBox: options.clipBox,
+                    viewport: { width: this.canvas.width / this.pixelRatio, height: this.canvas.height / this.pixelRatio },
                 });
             }
             // 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.referenceImages.draw(pass, viewProj);
+            this.referenceImages.draw(pass, viewProj, relativeToEyeFrame.getViewProjection().m, relativeToEyeFrame.getCameraWorld());
             this.overlays.draw(pass, {
                 options,
                 viewProj,
                 modelBounds: this.getModelBounds(),
                 camera: this.camera,
-                canvasWidth: this.canvas.width,
-                canvasHeight: this.canvas.height,
+                canvasWidth: this.canvas.width / this.pixelRatio, // CSS px: glyph sizes are CSS px
+                canvasHeight: this.canvas.height / this.pixelRatio, pixelRatio: this.pixelRatio,
+                relativeToEyeFrame,
+                rteViewProj: relativeToEyeFrame.getViewProjection().m,
+                rteCamera: relativeToEyeFrame.getCameraWorld(),
             });
             pass.end();
-            const canRunPostPass = (contactEnabled || separationEnabled)
-                && this.postProcessor !== null;
-            if (canRunPostPass && this.postProcessor) {
-                this.postProcessor.updateOptions({
-                    enableContactShading: contactEnabled,
-                    contactRadius: visualEnhancement.contactShading.radius,
-                    contactIntensity: visualEnhancement.contactShading.intensity,
-                });
-                this.postProcessor.apply(encoder, {
-                    targetView: textureView,
-                    // Depth-only view required because depth24plus-stencil8
-                    // cannot be sampled as texture_depth_* with aspect 'all'.
-                    depthView: this.pipeline.getDepthOnlyTextureView(),
-                    objectIdView: this.pipeline.getObjectIdTextureView(),
-                    contactQuality: contactEnabled && visualEnhancement.contactShading.quality === 'high' ? 'high' : 'low',
-                    radius: Math.min(3.0, Math.max(1.0, visualEnhancement.contactShading.radius)),
-                    intensity: contactEnabled ? Math.min(1.0, Math.max(0.0, visualEnhancement.contactShading.intensity)) : 0.0,
-                    separationQuality: visualEnhancement.separationLines.quality === 'high' ? 'high' : 'low',
-                    separationRadius: Math.min(2.0, Math.max(1.0, visualEnhancement.separationLines.radius)),
-                    separationIntensity: separationEnabled ? Math.min(1.0, Math.max(0.0, visualEnhancement.separationLines.intensity)) : 0.0,
-                    enableSeparationLines: separationEnabled,
-                });
-            }
-            // Eye-Dome Lighting — runs AFTER contact/separation so it darkens
-            // every layer uniformly. Cheap (~9 depth taps), only active when
-            // there are point clouds in the scene and the user has enabled it.
-            if (this.edlPass
-                && this.edlOptions.enabled
-                && this.pointCloudRenderer?.hasAssets()) {
-                this.edlPass.apply(encoder, {
-                    targetView: textureView,
-                    depthView: this.pipeline.getDepthOnlyTextureView(),
-                }, {
-                    strength: this.edlOptions.strength,
-                    radiusPx: this.edlOptions.radiusPx,
-                    highQuality: this.edlOptions.highQuality,
-                });
-            }
+            // Created lazily like the sky/shadow passes; each pass inside is too.
+            this.postPasses ??= new PostPassChain(this.device, this.pipeline.getSampleCount());
+            this.postPasses.encode({
+                encoder,
+                targetView: textureView,
+                width: this.canvas.width,
+                height: this.canvas.height,
+                // Depth-only: depth24plus-stencil8 cannot be sampled as texture_depth_* with aspect 'all'.
+                depthView: this.pipeline.getDepthOnlyTextureView(),
+                objectIdView,
+                projection: this.camera.getProjMatrix(),
+                enhancement: visualEnhancement,
+                effectsLive,
+                pixelRatio: this.pixelRatio,
+                // EDL only when point clouds are loaded and the user enabled it.
+                edl: this.edlOptions.enabled && this.pointCloudRenderer?.hasAssets() ? this.edlOptions : null,
+            });
+            colorReadback = colorCapture && encodeRendererColorFrameCapture(device, encoder, colorCapture);
             device.queue.submit([encoder.finish()]);
+            if (colorReadback && colorCapture) {
+                settleRendererColorFrameCapture(this, colorCapture, colorReadback);
+                colorCapture = null;
+                colorReadback = null;
+            }
             this._lastFrameStats = {
                 drawCalls: frameDrawCalls,
                 batchesDrawn: frameBatchesDrawn,
@@ -2882,6 +2860,7 @@ export class Renderer {
             }
         }
         catch (error) {
+            discardRendererColorFrameReadback(colorReadback);
             // Balance the validation scope if we threw before popping it above —
             // an unpopped scope would capture every later frame's errors silently.
             // drainErrorScope logs a pop rejection (device loss) rather than
@@ -2901,7 +2880,9 @@ export class Renderer {
             // 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
+            // `OperationError` preconditions are unreachable (the partial-batch
+            // upload's `createStaticGpuBuffer` also pads its whole-view payload
+            // to the 4-byte multiple the spec demands, #5429); 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
@@ -2910,10 +2891,11 @@ export class Renderer {
             // 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
+            // `getOrCreatePartialBatch`'s CPU-side geometry merge running out of
+            // host memory, 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');
+            cancelRendererColorFrame(this);
         }
     }
     /**
@@ -3044,8 +3026,8 @@ export class Renderer {
     }
     /** Stage one new owner; borrowed mesh buffers must remain immutable until disposal. */
     prepareAuthoredOwner(parts) {
-        if (!this.device.isInitialized() || !this.pipeline)
-            throw new Error('Renderer is not initialized.');
+        if (this.deviceLost || !this.device.isInitialized() || !this.pipeline)
+            throw this.deviceLost ? rendererDeviceLostError() : new Error('Renderer is not initialized.');
         const prepared = this.scene.prepareAuthoredOwner(parts, this.device.getDevice(), this.pipeline);
         return { commit: () => { prepared.commit(); this.refreshPlacementBounds(); this.invalidateBVHCache(); this.requestRender(); }, dispose: prepared.dispose };
     }
@@ -3240,30 +3222,9 @@ export class Renderer {
         }
         return this.device.getDevice();
     }
-    /**
-     * Capture a screenshot of the current view
-     * Waits for GPU work to complete and captures exactly what's displayed
-     * @returns PNG data URL or null if capture failed
-     */
-    async captureScreenshot() {
-        if (!this.device.isInitialized()) {
-            console.warn('[Renderer] Cannot capture screenshot: not initialized');
-            return null;
-        }
-        try {
-            // Wait for any pending GPU work to complete before capturing
-            // This ensures we capture the fully rendered frame
-            const device = this.device.getDevice();
-            await device.queue.onSubmittedWorkDone();
-            // Capture exactly what's displayed on the canvas
-            const dataUrl = this.canvas.toDataURL('image/png');
-            return dataUrl;
-        }
-        catch (error) {
-            console.error('[Renderer] Screenshot capture failed:', error);
-            return null;
-        }
-    }
+    captureScreenshot() { return captureRendererScreenshot(this.device, this.canvas); }
+    /** Capture the next submitted frame's bounded color pixels, not compositor state. */
+    captureColorFrame() { return requestRendererColorFrame(this, !this.destroyed && !this.deviceLost && this.device.isInitialized(), () => this.requestRender()); }
     /**
      * Destroy the renderer and release all GPU resources.
      *
@@ -3298,6 +3259,7 @@ export class Renderer {
     destroy() {
         this.initGeneration++;
         this.destroyed = true;
+        cancelRendererColorFrame(this);
         this.teardown();
         this.rejectReadyWaiters(rendererDestroyedError());
     }
@@ -3306,15 +3268,18 @@ export class Renderer {
      * in-flight init. Callers: the public `destroy()` (which invalidates first)
      * and `initOnce()`, tearing down the previous init before building its own.
      */
-    teardown() {
+    teardown(clearScene = true) {
         // Nothing below survives this call, so `whenReady()` / `isReady()` must
         // go back to waiting. Set first: every release below is synchronous, but
         // the flag is what a caller holding a live reference actually reads.
         this.ready = false;
+        cancelRendererColorFrame(this);
         // Scene mesh GPU buffers
-        this.scene.clear();
-        // Re-arm the section-bounds diagnostic log for the next model.
-        this._loggedSectionBounds = false;
+        if (clearScene) {
+            this.scene.clear();
+            // Re-arm the section-bounds diagnostic log for the next model.
+            this._loggedSectionBounds = false;
+        }
         // Render pipelines (textures + uniform buffers)
         this.pipeline?.destroy();
         this.pipeline = null;
@@ -3325,11 +3290,8 @@ export class Renderer {
         this.picker?.destroy();
         this.picker = null;
         this.pickingManager.setPicker(null);
-        // Post-processor uniform buffer
-        this.postProcessor?.destroy();
-        this.postProcessor = null;
-        this.edlPass?.destroy();
-        this.edlPass = null;
+        this.postPasses?.destroy();
+        this.postPasses = null;
         this.skyPass?.destroy();
         this.skyPass = null;
         this.shadowPass?.destroy();
@@ -3339,6 +3301,9 @@ export class Renderer {
         this.overlays.destroy();
         this.referenceImages.destroy();
         // Point cloud GPU resources
+        this.pointCloudNextHandleId = this.pointCloudRenderer?.handleIds?.current() ?? this.pointCloudNextHandleId;
+        this.pointCloudStreamEpoch++;
+        this.pointCloudStreamEpochs.clear();
         this.pointCloudRenderer?.clear();
         this.pointCloudRenderer = null;
         // BIM ↔ scan deviation pipeline + cached BVH GPU buffers.