@ifc-lite/renderer 3.2.0 → 5.0.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';
@@ -43,6 +43,8 @@ export { hostsOtherEntities } from './mesh-entity-hosting.js';
 export { FederationRegistry, federationRegistry } from './federation-registry.js';
 export * from './types.js';
 export { resolveEnvironment, deriveSkyGradient, packEnvironmentUniforms, ENVIRONMENT_UNIFORM_SIZE, } from './environment.js';
+export { DEFAULT_OVERLAY_THEME } from './overlay-theme.js';
+import { DEFAULT_OVERLAY_THEME } from './overlay-theme.js';
 export { resolveContributionThresholdPx, projectedAabbRadiusPx } from './contribution-cull.js';
 export { chunkCellKey, bucketBaseKeyFor, DEFAULT_CHUNK_CELL_SIZE } from './chunk-grid.js';
 export { selectEvictions, MIN_EVICTION_AGE_FRAMES } from './residency.js';
@@ -79,32 +81,38 @@ 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 { packMeshMaterial } from './mesh-material.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';
@@ -133,15 +141,19 @@ export class Renderer {
     scene;
     picker = null;
     canvas;
+    // The overlay theme (#5484), kept so a pre-init `setOverlayTheme` call
+    // (and a later re-init) still lands — `init()` re-applies it to `pipeline`.
+    overlayTheme = DEFAULT_OVERLAY_THEME;
     /**
      * 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
+     * `init()` so a pre-init `setOverlayTheme` 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),
+        expandModelBoundsWithAnchoredLineVertices: (positions, origin, stride) => this.modelBoundsTracker.expandWithAnchoredVertices(positions, origin, stride),
         syncCameraSceneBounds: () => {
             if (this.modelBounds)
                 this.camera.setSceneBounds(this.modelBounds);
@@ -150,9 +162,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;
@@ -173,6 +188,7 @@ export class Renderer {
     pointCloudRenderer = null;
     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
@@ -381,13 +397,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.
@@ -409,8 +421,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.
      *
@@ -473,8 +485,8 @@ export class Renderer {
         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
@@ -484,43 +496,32 @@ 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;
             this.canvas.height = height;
         }
         this.pipeline = new RenderPipeline(this.device, width, height);
+        // Re-apply any theme set before this (re)creation, or set by a prior
+        // init() before a device-loss re-init, so it isn't lost (#5484).
+        this.pipeline.selectionColorUniform.update(this.overlayTheme.selection);
         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);
@@ -707,6 +708,7 @@ export class Renderer {
         }
         this.deviceLossSequence++;
         this.deviceLost = true;
+        cancelRendererColorFrame(this);
         this.recovery.lostReferenceImages = this.referenceImages.hasImages();
         this.referenceImages.destroy();
         this.deviceLostGeneration = this.initGeneration;
@@ -766,11 +768,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.
         //
@@ -879,38 +883,16 @@ export class Renderer {
      * chunks will arrive (currently a no-op but kept for symmetry).
      */
     beginPointCloudStream(meta) {
-        if (this.deviceLost)
-            throw rendererDeviceLostError();
-        if (!this.pointCloudRenderer) {
-            throw new Error('Renderer not initialized. Call init() first.');
-        }
-        const handle = this.pointCloudRenderer.beginAsset(meta);
-        this.pointCloudStreamEpochs.set(handle.id, this.pointCloudStreamEpoch);
-        return handle;
-    }
-    currentPointCloudStreamRenderer(handle) {
-        if (this.deviceLost || !this.pointCloudRenderer
-            || this.pointCloudStreamEpochs.get(handle.id) !== this.pointCloudStreamEpoch)
-            throw rendererDeviceLostError();
-        return this.pointCloudRenderer;
+        return beginPointCloudStreamImpl(this, meta);
     }
     appendPointCloudChunk(handle, chunk) {
-        this.currentPointCloudStreamRenderer(handle).appendChunk(handle, chunk);
-        this.modelBoundsTracker.expandForPointClouds();
-        this.camera.setSceneBounds(this.modelBounds);
-        this.requestRender();
+        appendPointCloudChunkImpl(this, handle, chunk);
     }
     endPointCloudStream(handle) {
-        this.currentPointCloudStreamRenderer(handle).endAsset(handle);
-        this.requestRender();
+        endPointCloudStreamImpl(this, handle);
     }
     removePointCloudAsset(handle) {
-        if (!this.pointCloudStreamEpochs.delete(handle.id))
-            return;
-        this.pointCloudRenderer?.removeAsset(handle);
-        // Bounds may have shrunk — recompute from scratch so fit-to-view
-        // and section-plane sliders see fresh extents.
-        this.refreshPlacementBounds();
+        removePointCloudAssetImpl(this, handle);
     }
     /**
      * Reassign a streamed point-cloud's expressId after upload. Use
@@ -958,6 +940,13 @@ export class Renderer {
         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);
@@ -1157,65 +1146,7 @@ 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;
-    }
-    /**
-     * 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);
-        }
+        return shadowOccluderBatches(this.scene, options, device, hasVisibilityFiltering, this.pipeline, this._partialBatchEpoch);
     }
     /** Guarded entry point (#4885) for the unguarded body below. */
     createMeshFromData(meshData) {
@@ -1234,18 +1165,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, 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
@@ -1262,9 +1192,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;
@@ -1294,7 +1224,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).
@@ -1309,7 +1241,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,
         });
@@ -1469,6 +1408,7 @@ export class Renderer {
         // emit a stream of validation errors. Stay quiet until re-init.
         if (this.deviceLost) {
             this._renderSkipCount++;
+            cancelRendererColorFrame(this);
             return;
         }
         try {
@@ -1480,6 +1420,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
@@ -1495,6 +1436,7 @@ export class Renderer {
             // host down with us".
             this._renderSkipCount++;
             this.containFrameThrow(error, 'frame');
+            cancelRendererColorFrame(this);
         }
     }
     /**
@@ -1506,23 +1448,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) {
@@ -1546,6 +1481,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;
@@ -1585,11 +1527,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 edge pass reads the object-id attachment after the pass.
+        const needsObjectIdPass = livePostEffects(visualEnhancement, effectsLive).edges;
         // Check if visibility filtering is active
         const hasHiddenFilter = options.hiddenIds && options.hiddenIds.size > 0;
         const hasIsolatedFilter = options.isolatedIds !== null && options.isolatedIds !== undefined;
@@ -1697,8 +1636,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) {
@@ -1739,12 +1677,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
@@ -1818,6 +1759,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
@@ -1830,10 +1773,7 @@ export class Renderer {
                     meshBuf[34] = mesh.color[2];
                     // Selected meshes always keep their own alpha so highlights stay opaque
                     meshBuf[35] = isSelected ? mesh.color[3] : alphaForMesh(mesh.expressId, mesh.color[3]);
-                    meshBuf[36] = mesh.material?.metallic ?? 0.0;
-                    meshBuf[37] = mesh.material?.roughness ?? 0.6;
-                    meshBuf[38] = 0;
-                    meshBuf[39] = 0;
+                    packMeshMaterial(meshBuf, mesh.color[3], mesh.material);
                     // Section plane data (offset 40-43)
                     if (sectionPlaneData) {
                         meshBuf[40] = sectionPlaneData.normal[0];
@@ -1858,6 +1798,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);
                 }
             }
@@ -1887,8 +1834,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
@@ -1911,9 +1866,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 });
@@ -1948,7 +1907,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
@@ -1958,7 +1917,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
@@ -2094,7 +2053,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
@@ -2121,7 +2080,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).
@@ -2176,7 +2135,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
                         }
@@ -2272,6 +2231,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;
@@ -2289,12 +2250,9 @@ export class Renderer {
                 tpl[29] = 0;
                 tpl[30] = 0;
                 tpl[31] = 1;
-                // Color placeholder — overwritten per batch
-                // tpl[32..35] set per batch
-                tpl[36] = 0.0; // metallic
-                tpl[37] = 0.6; // roughness
-                tpl[38] = 0;
-                tpl[39] = 0; // padding
+                // Colour + material row (tpl[32..39]) are patched per draw; the
+                // instanced passes keep this opaque default.
+                packMeshMaterial(tpl);
                 if (sectionPlaneData) {
                     tpl[40] = sectionPlaneData.normal[0];
                     tpl[41] = sectionPlaneData.normal[1];
@@ -2322,15 +2280,22 @@ 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)
                         return;
-                    // Patch only the per-batch color (4 floats at offset 32)
+                    // Patch the per-batch colour, and the material its AUTHORED
+                    // alpha implies: an X-Ray fade is not glass (#5386).
                     tpl[32] = batch.color[0];
                     tpl[33] = batch.color[1];
                     tpl[34] = batch.color[2];
                     tpl[35] = alphaForBatch(batch, batch.color[3]);
+                    packMeshMaterial(tpl, batch.color[3]);
                     // Per-batch local frame: the batch's vertices are stored
                     // RELATIVE to batch.origin (f32-small), so set the model
                     // matrix translation column to origin (world = origin + pos).
@@ -2341,6 +2306,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;
@@ -2420,7 +2390,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;
                             }
@@ -2438,11 +2408,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());
@@ -2502,10 +2473,22 @@ 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];
                         tpl[35] = txAlpha;
+                        // Same authored-alpha + material contract as the flat/batched
+                        // paths (mesh-material.ts) — a call with neither argument
+                        // silently gave every textured metal or translucent mesh the
+                        // opaque dielectric default (#5623 review). The pipeline
+                        // itself is still opaque/depth-write only (no blend state,
+                        // see `txAlpha` above), so a translucent authored alpha still
+                        // never actually blends here — only the glass/roughness
+                        // CHOICE in the shader follows the same rule as everywhere
+                        // else, for the same reason `tm.material` does.
+                        packMeshMaterial(tpl, tm.color[3], tm.material);
                         device.queue.writeBuffer(tm.uniformBuffer, 0, tpl);
                         pass.setBindGroup(0, tm.bindGroup);
                         pass.setVertexBuffer(0, tm.vertexBuffer);
@@ -2568,7 +2551,7 @@ export class Renderer {
                 // flags.x bit 1 = overlay: tells the shader to preserve baseColor.a
                 // (the overlay pipeline now has src-alpha blending so low-alpha ghost
                 // tints composite correctly against the opaque pass) AND skip the
-                // glass-fresnel branch (which is meant for real glass materials and
+                // specular term (glass reflections are meant for real glass and
                 // would whiten low-alpha colour overrides at grazing angles).
                 const overrideBatches = this.scene.getOverrideBatches();
                 if (overrideBatches.length > 0) {
@@ -2648,7 +2631,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());
@@ -2682,10 +2665,7 @@ export class Renderer {
                         tpl[33] = mesh.color[1];
                         tpl[34] = mesh.color[2];
                         tpl[35] = alphaForMesh(mesh.expressId, mesh.color[3]);
-                        tpl[36] = mesh.material?.metallic ?? 0.0;
-                        tpl[37] = mesh.material?.roughness ?? 0.6;
-                        tpl[38] = 0;
-                        tpl[39] = 0;
+                        packMeshMaterial(tpl, mesh.color[3], mesh.material);
                         if (sectionPlaneData) {
                             tpl[40] = sectionPlaneData.normal[0];
                             tpl[41] = sectionPlaneData.normal[1];
@@ -2705,6 +2685,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);
@@ -2742,10 +2726,7 @@ export class Renderer {
                     tpl[33] = mesh.color[1];
                     tpl[34] = mesh.color[2];
                     tpl[35] = mesh.color[3];
-                    tpl[36] = mesh.material?.metallic ?? 0.0;
-                    tpl[37] = mesh.material?.roughness ?? 0.6;
-                    tpl[38] = 0;
-                    tpl[39] = 0;
+                    packMeshMaterial(tpl, mesh.color[3], mesh.material);
                     if (sectionPlaneData) {
                         tpl[40] = sectionPlaneData.normal[0];
                         tpl[41] = sectionPlaneData.normal[1];
@@ -2765,6 +2746,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);
@@ -2812,65 +2797,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,
@@ -2894,6 +2869,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
@@ -2913,7 +2889,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
@@ -2922,10 +2900,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);
         }
     }
     /**
@@ -3106,13 +3085,21 @@ export class Renderer {
         this.overlays.clearSection2DOverlay();
     }
     /**
-     * Set the colour of the overlay lines (annotation / alignment / grid) and the
-     * section-cut outline (RGBA, 0..1). Defaults to opaque black; theme it to keep
-     * lines legible on a dark canvas. The matching label colour is per-text via
+     * Set the one colour vocabulary every overlay draws in (#5484): the selection
+     * highlight, the section-plane preview (one accent for every axis), every
+     * overlay line channel (section-cut outline, IfcAnnotation, alignment,
+     * IfcGrid, DXF / LandXML) and the clash pair / overlap tints. Call this on
+     * theme change and once after `init()`; the underlying GPU uniforms are
+     * written only here, never per frame. Supersedes `setOverlayLineColor`
+     * (deleted — the app never called it with a themed colour). See
+     * `OverlayTheme` for which fields want linear-light RGBA and which want
+     * sRGB-direct RGBA. The matching label colour is per-text via
      * `SymbolicTextInput.color` on `uploadAnnotationTexts3D`.
      */
-    setOverlayLineColor(color) {
-        this.overlays.setOverlayLineColor(color);
+    setOverlayTheme(theme) {
+        this.overlayTheme = theme;
+        this.pipeline?.selectionColorUniform.update(theme.selection);
+        this.overlays.setTheme(theme);
     }
     /**
      * Set one standalone 3D line overlay, or clear it by passing `null`.
@@ -3125,7 +3112,7 @@ export class Renderer {
      *
      * Every channel is an independent buffer with its own visibility, so
      * setting one leaves the other three untouched. All four share the colour
-     * set by {@link setOverlayLineColor}; label colour is per-text via
+     * set by `Renderer.setOverlayTheme`'s `overlayLine` field; label colour is per-text via
      * `SymbolicTextInput.color` on `uploadAnnotationTexts3D`.
      *
      * The channels differ in exactly one way — whether they grow the scene
@@ -3145,8 +3132,10 @@ export class Renderer {
     /**
      * Show (or clear) the clash-overlap box: the wireframe AABB of a focused
      * clash, drawn in `color` so the overlap region reads as a distinct third
-     * colour next to the two glowing clash elements (#1277). Pass `null` to
-     * clear. `min`/`max` are world-space corners (clash works in world frame).
+     * colour next to the two glowing clash elements (#1277). Omit `color` to
+     * draw it in the overlay theme's `clashOverlap` and keep following it
+     * across `setOverlayTheme` calls (#5490). Pass `null` to clear.
+     * `min`/`max` are world-space corners (clash works in world frame).
      */
     setClashOverlapBox(box) {
         this.overlays.setClashOverlapBox(box);
@@ -3155,8 +3144,10 @@ export class Renderer {
      * Draw the focused clash's CONTACT geometry as 3D line segments — the real
      * shared-face polygon outlines / intersection lines, not the AABB box.
      * `vertices` is a flat line-list (x,y,z per endpoint, 2 endpoints per
-     * segment) in world frame. Pass `null` to clear. Shares the clash-box line
-     * buffer, so only one of this / setClashOverlapBox is shown at a time.
+     * segment) in world frame. Omit `color` to follow the overlay theme's
+     * `clashOverlap`, as for `setClashOverlapBox`. Pass `null` to clear. Shares
+     * the clash-box line buffer, so only one of this / setClashOverlapBox is
+     * shown at a time.
      */
     setClashContactLines(lines) {
         this.overlays.setClashContactLines(lines);
@@ -3168,7 +3159,8 @@ export class Renderer {
      * BIMcollab Zoom / Solibri presentation). Pass `null` to clear. Independent
      * of `setClashOverlapBox` / `setClashContactLines`: the caller decides
      * which one is current for a given clash (solid when the kernel resolved
-     * one, box/lines as the fallback when it didn't).
+     * one, box/lines as the fallback when it didn't). Omit `color` to follow
+     * the overlay theme's `clashOverlap`, as for `setClashOverlapBox`.
      */
     setClashIntersectionSolid(solid) {
         this.overlays.setClashIntersectionSolid(solid);
@@ -3252,30 +3244,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.
      *
@@ -3310,6 +3281,7 @@ export class Renderer {
     destroy() {
         this.initGeneration++;
         this.destroyed = true;
+        cancelRendererColorFrame(this);
         this.teardown();
         this.rejectReadyWaiters(rendererDestroyedError());
     }
@@ -3323,6 +3295,7 @@ export class Renderer {
         // 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
         if (clearScene) {
             this.scene.clear();
@@ -3339,11 +3312,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();
@@ -3353,6 +3323,7 @@ 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();