@ifc-lite/renderer 4.2.0 → 6.0.0

package/dist/index.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';
@@ -76,19 +78,23 @@ import { WebGPUDevice } from './device.js';
 import { RenderPipeline } from './pipeline.js';
 import { Camera } from './camera.js';
 import { Scene } from './scene.js';
+import { remapOverrideColors } from './scene-derived-batches.js';
 import { Picker } from './picker.js';
 import { reportableItemId } from './pick-resolve.js';
-import { MathUtils, viewBasis } from './math.js';
+import { viewBasis } from './math.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 { PostPassChain } from './post-pass-chain.js';
+import { buildSelectionOutlineFrame, matchesHoveredMesh } from './selection-outline-frame.js';
+import { HoverMeshCache } from './hover-mesh-cache.js';
 import { InteractionEffectsGovernor } from './interaction-effects-governor.js';
 import { VisibilityEpochTracker } from './visibility-epoch.js';
 import { isEntityVisible } from './entity-visibility.js';
@@ -100,21 +106,21 @@ import { resolveEnvironment } from './environment.js';
 import { ShadowPass, resolveShadowMapResolution } from './shadow-pass.js';
 import { fitSunLightMatrix, cameraFrustumFocusCorners, resolveShadowNormalBiasMetres } from './shadow-light-matrix.js';
 import { collectShadowOccluders } from './shadow-occluders.js';
-import { uploadInstancedRteDeltas } from './instanced-rte.js';
+import { drawInstanceRuns, uploadInstancedRteDeltas } from './instanced-rte.js';
+import { INSTANCED_RTE_DELTA_SLOT } from './instanced-vertex-layout.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 { batchEntityIdAnchor, batchHasColorOverride, packOverrideParams } from './entity-color-table.js';
 import { XRayAlpha, XRayEpochTracker } from './xray-alpha.js';
 import { PartialBatchRequests } from './partial-batch-requests.js';
-import { colorSaltByte, packEntityLane } from './scene-geometry.js';
+import { uploadIndividualMesh } from './individual-mesh-upload.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;
 /**
  * The reason `whenReady()` rejects when the renderer is destroyed.
  *
@@ -138,10 +144,13 @@ 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({
@@ -159,6 +168,8 @@ export class Renderer {
     // Ambient occlusion, separation lines and eye-dome lighting (post-pass-chain.ts),
     // created on the first rendered frame.
     postPasses = null;
+    /** GPU copies of the hovered entity for the hover outline (#5390); see hover-mesh-cache.ts. */
+    hoverMeshes = new HoverMeshCache();
     /** Device px per CSS px in the drawing buffer; CSS-px sizes scale by it (#5383). */
     pixelRatio = 1;
     interactionEffects = new InteractionEffectsGovernor();
@@ -366,6 +377,8 @@ export class Renderer {
     _xrayEpochs = new XRayEpochTracker();
     _visibilityVersion = 0;
     _partialBatchEpoch = 0;
+    _xrayAlpha = null;
+    _xrayAlphaEpoch = -1;
     _lastColorOverrideGen = -1;
     _xrayVersion = 0;
     _lastHadPartialSources = false;
@@ -394,6 +407,8 @@ export class Renderer {
     // 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);
+    // overrideParams lanes (#6076): zero except inside a painting renderBatch call.
+    uniformOverrideU32 = new Uint32Array(this.uniformScratch.buffer, MESH_UNIFORM_OFFSET.overrideParams * 4, 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.
@@ -505,6 +520,9 @@ export class Renderer {
             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());
@@ -970,6 +988,15 @@ export class Renderer {
             requestRender: () => this.requestRender(),
         });
     }
+    /** Read per-scan-asset signed-distance statistics after a completed run. */
+    async readDeviationAssetStats() {
+        return this.deviationComputer.readAssetStats({
+            device: this.device,
+            scene: this.scene,
+            pointCloudRenderer: this.pointCloudRenderer,
+            requestRender: () => this.requestRender(),
+        });
+    }
     /**
      * Toggle Eye-Dome Lighting and tune its strength.
      *
@@ -1143,6 +1170,10 @@ export class Renderer {
     createMeshFromData(meshData) {
         return runGuardedGpuUpload(() => this.isDeviceLost(), () => this.createMeshFromDataUnguarded(meshData), (error) => this.reportUploadLoss(error));
     }
+    /** The source batch's frame for an individual copy of `meshData` (see individual-mesh-upload.ts). */
+    individualMeshFrame(meshData) {
+        return { sharedOrigin: this.scene.getSharedFrameOrigin(meshData.modelIndex, meshData), quantized: this.scene.isMeshQuantized(meshData) };
+    }
     /**
      * 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
@@ -1150,71 +1181,7 @@ export class Renderer {
     createMeshFromDataUnguarded(meshData) {
         if (!this.device.isInitialized())
             return;
-        const device = this.device.getDevice();
-        const vertexCount = meshData.positions.length / 3;
-        const interleavedRaw = new ArrayBuffer(vertexCount * 7 * 4);
-        const interleaved = new Float32Array(interleavedRaw);
-        const interleavedU32 = new Uint32Array(interleavedRaw);
-        // Build this individual mesh (selection highlight + GPU object-id picker)
-        // 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  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 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
-        // node nearest the batch's stored f32 rel coordinate. Reproduce it by
-        // snapping the SAME rel coordinate here (round(s*1024)/1024 in f64
-        // yields the identical exact-f32 lattice value — see quantize.ts), so
-        // the highlight/picker mesh stays BIT-coincident with its quantized
-        // source surface, exactly as the two-step fold above achieves for the
-        // f32 path. Meshes whose batch fell back to f32 must not snap.
-        const snap = this.scene.isMeshQuantized(meshData)
-            ? (v) => Math.round(v * 1024) / 1024
-            : (v) => v;
-        const p = meshData.positions;
-        for (let i = 0; i < vertexCount; i++) {
-            const base = i * 7;
-            const posBase = i * 3;
-            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;
-            interleaved[base + 5] = hasNormals ? meshData.normals[posBase + 2] : 0;
-            let encodedId = meshData.expressId >>> 0;
-            if (encodedId > MAX_ENCODED_ENTITY_ID) {
-                if (!warnedEntityIdRange) {
-                    warnedEntityIdRange = true;
-                    console.warn('[Renderer] expressId exceeds 24-bit seam-ID encoding range; seam lines may collide.');
-                }
-                encodedId = encodedId & MAX_ENCODED_ENTITY_ID;
-            }
-            // Stamp the SAME high-byte material-colour salt as the batch path
-            // (mergeGeometry) so this individual/selection mesh computes the
-            // identical depth nudge as its source batch — otherwise the highlight
-            // (selection pipeline, reverse-Z 'greater-equal') would z-fight or drop
-            // out against the salted base depth. Low 24 bits stay the picking id.
-            interleavedU32[base + 6] = packEntityLane(encodedId, colorSaltByte(meshData.color));
-        }
-        const vertexBuffer = device.createBuffer({
-            size: interleaved.byteLength,
-            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
-        });
-        device.queue.writeBuffer(vertexBuffer, 0, interleaved);
-        const indexBuffer = device.createBuffer({
-            size: meshData.indices.byteLength,
-            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
-        });
-        device.queue.writeBuffer(indexBuffer, 0, meshData.indices);
+        const { vertexBuffer, indexBuffer, indexCount, transform, rteOrigin } = uploadIndividualMesh(this.device.getDevice(), meshData, this.individualMeshFrame(meshData));
         // 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.
@@ -1231,16 +1198,11 @@ export class Renderer {
             geometryItemId: reportableItemId(meshData, meshData.expressId),
             vertexBuffer,
             indexBuffer,
-            indexCount: meshData.indices.length,
-            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],
+            indexCount,
+            transform,
+            rteOrigin,
             color: meshData.color,
+            ...(meshData.material ? { finish: meshData.material } : {}), // #5582
             hydrated: true,
         });
     }
@@ -1510,16 +1472,8 @@ export class Renderer {
         // governor's verdict so early navigation can't degrade a session.
         const timingUnstable = options.isStreaming === true || this.scene.hasQueuedMeshes();
         const effectsLive = this.interactionEffects.frame(interacting, performance.now(), timingUnstable, options.interactionFrameIntervalMs ?? 0);
-        // Edge contrast is NOT interaction-gated: its per-fragment work runs
-        // unconditionally in the shader and the gated tail is a handful of
-        // ALU ops, so disabling it bought nothing and only made the crease
-        // darkening pop off/on around gestures (visible in ortho).
-        const edgeEnabled = visualEnhancement.enabled && visualEnhancement.edgeContrast.enabled;
-        const edgeIntensity = Math.min(3.0, Math.max(0.0, visualEnhancement.edgeContrast.intensity));
-        const edgeEnabledU32 = edgeEnabled ? 1 : 0;
-        const edgeIntensityMilliU32 = Math.round(edgeIntensity * 1000);
-        // Only the separation lines read the object-id attachment after the pass.
-        const needsObjectIdPass = livePostEffects(visualEnhancement, effectsLive).separationLines;
+        // 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;
@@ -1594,10 +1548,6 @@ export class Renderer {
         // it carries a per-instance hidden flag the shader discards on). Diffed → a
         // no-op when visibility is unchanged.
         this.scene.setInstancedVisibility(options.hiddenIds, options.isolatedIds);
-        // Per-frame alpha overrides for X-Ray mode. See RenderOptions.transparencyOverrides.
-        // XRayAlpha snapshots the caller's map so mid-frame mutation can't desync
-        // classification and uniform-write decisions for the same batch/mesh, and
-        // owns the per-entity resolution + the mixed-batch partition (#4129).
         // X-Ray *context* mode (`ghostExceptIds`) feeds the same machinery, so it
         // routes through the transparent pipeline with no extra call sites — and
         // avoids building a Map over every element just to fade "the rest".
@@ -1607,16 +1557,19 @@ export class Renderer {
         // the user asked to fade the building and got a solid facade standing
         // in front of a ghosted interior.
         this.scene.setInstancedGhosting(options.ghostExceptIds ?? null, selectedExpressIds, ghostAlpha);
-        const xray = new XRayAlpha(options, selectedExpressIds);
+        if (this._xrayAlpha === null || this._xrayAlphaEpoch !== this._partialBatchEpoch) {
+            this._xrayAlpha = new XRayAlpha(options, selectedExpressIds);
+            this._xrayAlphaEpoch = this._partialBatchEpoch;
+        }
+        const xray = this._xrayAlpha;
         const alphaForMesh = (expressId, fallback) => xray.forEntity(expressId, fallback);
         const alphaForBatch = (batch, fallback) => xray.forBatch(batch, fallback);
         // Lens / Pset color overrides: when an entity has an override, force
-        // its base draw through the opaque pipeline so it writes depth. The
-        // overlay paint pass uses depthCompare 'equal' and otherwise silently
-        // drops fragments belonging to entities whose default pipeline is
-        // transparent (IfcSpace, IfcOpeningElement, glass, …). See issue #677.
-        // Pure routing decision lives in overlay-routing.ts and is unit-tested
-        // there.
+        // its base draw through the opaque pipeline — the only draws the
+        // entity colour table paints (#6076) — or an entity whose default
+        // pipeline is transparent (IfcSpace, IfcOpeningElement, glass, …)
+        // would never show it. See issue #677. Pure routing decision lives in
+        // overlay-routing.ts and is unit-tested there.
         const colorOverrides = this.scene.getColorOverrides();
         // PERFORMANCE FIX: Use batch-level visibility filtering instead of creating individual meshes
         // Only create individual meshes for selected elements (for highlighting)
@@ -1744,6 +1697,11 @@ export class Renderer {
                     max: [...options.clipBox.max],
                 }
                 : null;
+            // Meshes this camera's RTE frame cannot represent (#6128). Nothing
+            // culls individual meshes before this point, so a far-off mesh (a
+            // stray element, one hydrated for picking) must be skipped, not
+            // allowed to fail every frame.
+            const outsideEyeEnvelope = new Set();
             // Reuse pooled scratch buffer for per-mesh uniform writes
             const meshBuf = this.uniformScratch;
             const meshFlags = this.uniformScratchU32;
@@ -1764,10 +1722,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.finish ?? mesh.material);
                     // Section plane data (offset 40-43)
                     if (sectionPlaneData) {
                         meshBuf[40] = sectionPlaneData.normal[0];
@@ -1790,14 +1745,17 @@ export class Renderer {
                         (sectionPlaneData?.enabled ? 1 : 0) |
                             (options.sectionPlane?.flipped ? 2 : 0) |
                             clipBit;
-                    meshFlags[2] = edgeEnabledU32;
-                    meshFlags[3] = edgeIntensityMilliU32;
+                    meshFlags[2] = 0; // unused since #5746 (was the derivative edge darkening)
+                    meshFlags[3] = 0;
                     // 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);
+                    if (!relativeToEyeFrame.tryPackDrawableOrigin(meshOrigin, meshBuf, MESH_UNIFORM_OFFSET.drawableDelta)) {
+                        outsideEyeEnvelope.add(mesh);
+                        continue;
+                    }
                     meshFlags[0] |= MESH_FLAG_RTE_DRAWABLE;
                     device.queue.writeBuffer(mesh.uniformBuffer, 0, meshBuf);
                 }
@@ -2035,7 +1993,13 @@ export class Renderer {
             // only presets that enable the sky — blanked the model on those
             // drivers. Binding while the main pipeline is current keeps it
             // valid for every main-family draw that follows.
+            this.pipeline.setEntityColorTableBuffer(this.scene.getEntityColorTable().getBuffer());
             pass.setBindGroup(1, this.pipeline.getEnvironmentBindGroup());
+            // Selected meshes drawn this frame, for the selection-mask pass
+            // (#5390) after `pass.end()` below. Populated inside the batched
+            // branch, where the highlight draw itself happens; empty in the
+            // no-batches fallback, which does not draw selection either.
+            let selectedMeshesForMask = [];
             // Check if we have batched meshes (preferred for performance)
             const allBatchedMeshes = this.scene.getBatchedMeshes();
             // PERFORMANCE FIX: Always use batch rendering when we have batches
@@ -2244,12 +2208,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];
@@ -2268,29 +2229,34 @@ export class Renderer {
                 //   x = isSelected (0/1)
                 //   y = section/clip bitfield:
                 //       bit 0 = sectionEnabled, bit 1 = flipped, bit 2 = clipBoxEnabled
-                //   z = edgeEnabled (0/1)
-                //   w = edgeIntensityMilli
+                //   z, w = unused, written as 0. They fed the in-shader derivative
+                //          edge darkening, removed in #5746; edges come from the
+                //          edge pass. The lanes stay so the struct layout is unchanged.
                 tplFlags[0] = 0;
                 tplFlags[1] =
                     (sectionPlaneData?.enabled ? 1 : 0) |
                         (options.sectionPlane?.flipped ? 2 : 0) |
                         tplClipBit;
-                tplFlags[2] = edgeEnabledU32;
-                tplFlags[3] = edgeIntensityMilliU32;
+                tplFlags[2] = 0;
+                tplFlags[3] = 0;
                 // 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) => {
+                // Helper function to render a batch — patches color into the shared template.
+                // `paint` = a depth-writing opaque draw: colour overrides shade it from the
+                // entity colour table (#6076); transparent draws keep their own colour.
+                const renderBatch = (batch, paint = false) => {
                     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], batch.finish);
                     // 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).
@@ -2304,7 +2270,8 @@ export class Renderer {
                     // 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);
+                    if (!relativeToEyeFrame.tryPackDrawableOrigin(o ?? [0, 0, 0], tpl, MESH_UNIFORM_OFFSET.drawableDelta))
+                        return;
                     tplFlags[0] |= MESH_FLAG_RTE_DRAWABLE;
                     // Quantized dequantization params (issue #1682 phase 6);
                     // zeroed for f32 batches (their pipelines ignore them).
@@ -2313,7 +2280,10 @@ export class Renderer {
                     tpl[57] = qz ? qz.min[1] : 0;
                     tpl[58] = qz ? qz.min[2] : 0;
                     tpl[59] = qz ? qz.step : 0;
+                    const painted = paint && batchHasColorOverride(batch, colorOverrides, colorOverrideGen);
+                    packOverrideParams(this.uniformOverrideU32, painted ? batchEntityIdAnchor(batch) : null, painted, options.emphasizeOverrides === true);
                     device.queue.writeBuffer(batch.uniformBuffer, 0, tpl);
+                    this.uniformOverrideU32.fill(0);
                     // Single draw call for entire batch! LOD1-selected batches
                     // bind their simplified index range over the same vertices.
                     const useLod1 = batch.lod1IndexBuffer && batch.lod1IndexCount && lodBatches.has(batch.id);
@@ -2336,11 +2306,7 @@ export class Renderer {
                 // probe (enableQuantizedBatches) verified they exist, so the
                 // base fallback here is type-safety, never taken.
                 const pipeFor = (batch, kind) => {
-                    const base = kind === 'opaque'
-                        ? this.pipeline.getPipeline()
-                        : kind === 'transparent'
-                            ? this.pipeline.getTransparentPipeline()
-                            : this.pipeline.getOverlayPipeline();
+                    const base = kind === 'opaque' ? this.pipeline.getPipeline() : this.pipeline.getTransparentPipeline();
                     if (!batch.quantized)
                         return base;
                     return this.pipeline.getQuantizedPipelineVariant(kind) ?? base;
@@ -2357,7 +2323,7 @@ export class Renderer {
                 pass.setPipeline(this.pipeline.getPipeline());
                 for (const batch of opaqueBatches) {
                     pass.setPipeline(pipeFor(batch, 'opaque'));
-                    renderBatch(batch);
+                    renderBatch(batch, true);
                 }
                 pass.setPipeline(this.pipeline.getPipeline());
                 // GPU-instancing pass — repeated geometry collated by the producer
@@ -2402,8 +2368,11 @@ export class Renderer {
                     }
                     visibleInstanced = kept;
                 }
+                // Per-template instance runs inside this frame's RTE envelope,
+                // shared by the opaque and transparent instanced sub-passes.
+                let visibleInstancedRuns = [];
                 if (visibleInstanced.length > 0) {
-                    uploadInstancedRteDeltas(device, visibleInstanced, relativeToEyeFrame.getCameraWorld());
+                    visibleInstancedRuns = 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
@@ -2412,13 +2381,15 @@ export class Renderer {
                     pass.setPipeline(this.pipeline.getInstancedPipeline());
                     pass.setBindGroup(0, this.pipeline.getBindGroup());
                     pass.setBindGroup(1, this.pipeline.getEnvironmentBindGroup());
-                    for (const it of visibleInstanced) {
+                    for (const [i, it] of visibleInstanced.entries()) {
                         pass.setVertexBuffer(0, it.vertexBuffer);
                         pass.setVertexBuffer(1, it.instanceBuffer);
+                        pass.setVertexBuffer(INSTANCED_RTE_DELTA_SLOT, it.rteDeltas.buffer);
                         pass.setIndexBuffer(it.indexBuffer, 'uint32');
-                        pass.drawIndexed(it.indexCount, it.instanceCount);
-                        frameDrawCalls++;
-                        frameInstancedDrawn++;
+                        const runs = visibleInstancedRuns[i];
+                        frameDrawCalls += drawInstanceRuns(pass, it.indexCount, runs);
+                        if (runs.length > 0)
+                            frameInstancedDrawn++;
                     }
                     pass.setPipeline(this.pipeline.getPipeline());
                     // The TRANSPARENT instanced sub-pass is drawn later, alongside the
@@ -2453,7 +2424,7 @@ export class Renderer {
                         if (txAlpha <= 0.01)
                             continue;
                         // Lens / Pset colour override tints the sampled texel — the
-                        // batch overlay paint pass doesn't iterate textured meshes,
+                        // entity colour table is off for textured draws (#6076),
                         // so applying the override here is what recolours them.
                         const txOverride = colorOverrides?.get(tm.expressId);
                         // `world = origin + position`: the vertex buffer stores
@@ -2468,12 +2439,23 @@ 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);
+                        if (!relativeToEyeFrame.tryPackDrawableOrigin(tm.origin, tpl, MESH_UNIFORM_OFFSET.drawableDelta))
+                            continue;
                         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.finish ?? tm.material);
                         device.queue.writeBuffer(tm.uniformBuffer, 0, tpl);
                         pass.setBindGroup(0, tm.bindGroup);
                         pass.setVertexBuffer(0, tm.vertexBuffer);
@@ -2504,7 +2486,7 @@ export class Renderer {
                             // Use opaque or transparent pipeline based on resolved alpha
                             // (not the parent batch's color[3] — that ignores transparencyOverrides).
                             // Promote to opaque if any expressId in the sub-batch carries a
-                            // lens/Pset colour override, so the overlay paint pass finds depth.
+                            // lens/Pset colour override, so the colour table paints it (#6076).
                             const isTransparent = shouldRouteBatchTransparent(alphaForBatch(subBatch, color[3]), subBatch.expressIds, colorOverrides);
                             if (isTransparent) {
                                 transparentSubBatches.push(subBatch);
@@ -2518,7 +2500,7 @@ export class Renderer {
                             pass.setPipeline(pipeFor(subBatch, 'opaque'));
                             opaqueSubBatches.push(subBatch);
                             // Render the sub-batch as a single draw call
-                            renderBatch(subBatch);
+                            renderBatch(subBatch, true);
                         }
                     }
                     for (const subBatch of transparentSubBatches) {
@@ -2528,28 +2510,6 @@ export class Renderer {
                     // Reset to opaque pipeline for subsequent rendering
                     pass.setPipeline(this.pipeline.getPipeline());
                 }
-                // Render color overlay batches (lens coloring) on top of ALL opaque geometry.
-                // Placed AFTER partial batches so depth buffer is complete for both full
-                // and partial batches. Uses 'equal' depth compare — only paints where
-                // original geometry wrote depth, so hidden entities never leak through.
-                //
-                // 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
-                // would whiten low-alpha colour overrides at grazing angles).
-                const overrideBatches = this.scene.getOverrideBatches();
-                if (overrideBatches.length > 0) {
-                    pass.setPipeline(this.pipeline.getOverlayPipeline());
-                    // bit 1 = overlay; bit 5 (32) = emphasize (pop) — see shader.
-                    tplFlags[0] = options.emphasizeOverrides ? (2 | 32) : 2;
-                    for (const batch of overrideBatches) {
-                        pass.setPipeline(pipeFor(batch, 'overlay'));
-                        renderBatch(batch);
-                    }
-                    tplFlags[0] = 0; // restore for any downstream use of the template
-                    pass.setPipeline(this.pipeline.getPipeline());
-                }
                 // Filled, hatched 3D cut surfaces are now rendered by
                 // Section2DOverlayRenderer using the exact polygons from
                 // SectionCutter (triangle-plane intersection). The old
@@ -2607,6 +2567,7 @@ export class Renderer {
                         return true;
                     })
                     : [];
+                selectedMeshesForMask = selectedMeshes;
                 // Transparent instanced sub-pass — drawn here (after ALL opaque incl. the
                 // textured sub-pass) so ghosted/x-rayed instanced occurrences blend over
                 // a complete depth buffer. Only runs when an override actually made some
@@ -2620,12 +2581,12 @@ export class Renderer {
                     pass.setPipeline(instancedTransparentPipeline);
                     pass.setBindGroup(0, this.pipeline.getBindGroup());
                     pass.setBindGroup(1, this.pipeline.getEnvironmentBindGroup());
-                    for (const it of visibleInstanced) {
+                    for (const [i, it] of visibleInstanced.entries()) {
                         pass.setVertexBuffer(0, it.vertexBuffer);
                         pass.setVertexBuffer(1, it.instanceBuffer);
+                        pass.setVertexBuffer(INSTANCED_RTE_DELTA_SLOT, it.rteDeltas.buffer);
                         pass.setIndexBuffer(it.indexBuffer, 'uint32');
-                        pass.drawIndexed(it.indexCount, it.instanceCount);
-                        frameDrawCalls++;
+                        frameDrawCalls += drawInstanceRuns(pass, it.indexCount, visibleInstancedRuns[i]);
                     }
                     pass.setPipeline(this.pipeline.getPipeline());
                 }
@@ -2650,10 +2611,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.finish ?? mesh.material);
                         if (sectionPlaneData) {
                             tpl[40] = sectionPlaneData.normal[0];
                             tpl[41] = sectionPlaneData.normal[1];
@@ -2671,11 +2629,12 @@ export class Renderer {
                             (sectionPlaneData?.enabled ? 1 : 0) |
                                 (options.sectionPlane?.flipped ? 2 : 0) |
                                 tplClipBit;
-                        tplFlags[2] = edgeEnabledU32;
-                        tplFlags[3] = edgeIntensityMilliU32;
+                        tplFlags[2] = 0;
+                        tplFlags[3] = 0;
                         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);
+                        if (!relativeToEyeFrame.tryPackDrawableOrigin(transparentOrigin, tpl, MESH_UNIFORM_OFFSET.drawableDelta))
+                            continue;
                         tplFlags[0] |= MESH_FLAG_RTE_DRAWABLE;
                         device.queue.writeBuffer(mesh.uniformBuffer, 0, tpl);
                         pass.setBindGroup(0, mesh.bindGroup);
@@ -2714,10 +2673,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.finish ?? mesh.material);
                     if (sectionPlaneData) {
                         tpl[40] = sectionPlaneData.normal[0];
                         tpl[41] = sectionPlaneData.normal[1];
@@ -2735,11 +2691,12 @@ export class Renderer {
                         (sectionPlaneData?.enabled ? 1 : 0) |
                             (options.sectionPlane?.flipped ? 2 : 0) |
                             tplClipBit;
-                    tplFlags[2] = edgeEnabledU32;
-                    tplFlags[3] = edgeIntensityMilliU32;
+                    tplFlags[2] = 0;
+                    tplFlags[3] = 0;
                     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);
+                    if (!relativeToEyeFrame.tryPackDrawableOrigin(selectedOrigin, tpl, MESH_UNIFORM_OFFSET.drawableDelta))
+                        continue;
                     tplFlags[0] |= MESH_FLAG_RTE_DRAWABLE;
                     device.queue.writeBuffer(mesh.uniformBuffer, 0, tpl);
                     pass.setPipeline(this.pipeline.getSelectionPipeline());
@@ -2754,6 +2711,8 @@ export class Renderer {
                 // Fallback: render individual meshes (only when no batches exist)
                 // Render opaque meshes with per-mesh bind groups
                 for (const mesh of opaqueMeshes) {
+                    if (outsideEyeEnvelope.has(mesh))
+                        continue;
                     if (mesh.bindGroup) {
                         pass.setBindGroup(0, mesh.bindGroup);
                     }
@@ -2769,6 +2728,8 @@ export class Renderer {
                 if (transparentMeshes.length > 0) {
                     pass.setPipeline(this.pipeline.getTransparentPipeline());
                     for (const mesh of transparentMeshes) {
+                        if (outsideEyeEnvelope.has(mesh))
+                            continue;
                         if (mesh.bindGroup) {
                             pass.setBindGroup(0, mesh.bindGroup);
                         }
@@ -2813,8 +2774,25 @@ export class Renderer {
                 rteCamera: relativeToEyeFrame.getCameraWorld(),
             });
             pass.end();
+            // Selection/hover outline input (#5390): built from the meshes the
+            // highlight-draw loop above already prepared this frame.
+            // A hidden / isolated-out entity is never outlined; the lookup is scoped to the hovered entity's own model.
+            const hovered = options.hoverOutline;
+            const hoverId = hovered && !options.hiddenIds?.has(hovered.id)
+                && (!hasIsolatedFilter || options.isolatedIds.has(hovered.id)) ? hovered.id : null;
+            const hoverModel = hovered?.modelIndex;
+            const hoverPieces = hoverId != null && !selectedMeshesForMask.some((m) => matchesHoveredMesh(m, hoverId, hoverModel))
+                ? this.hoverMeshes.resolve(device, hoverId, hoverModel, () => this.scene.getMeshDataPieces(hoverId, hoverModel), (m) => this.individualMeshFrame(m))
+                : (this.hoverMeshes.release(), []);
+            const selectionOutline = buildSelectionOutlineFrame({
+                uniformBufferSize: this.pipeline.getUniformBufferSize(), viewProj, relativeToEyeFrame,
+                section: sectionPlaneData, sectionFlipped: options.sectionPlane?.flipped, clipBox: options.clipBox,
+                selectedMeshes: selectedMeshesForMask, hoverPieces, hoveredId: hoverId, selectedModelIndex: hoverModel,
+                instancedTemplates: this.scene.getInstancedTemplates(),
+                instancedHovered: hoverId != null ? this.scene.getInstancedTemplatesOf(hoverId, hoverModel) : [],
+            });
             // Created lazily like the sky/shadow passes; each pass inside is too.
-            this.postPasses ??= new PostPassChain(this.device, this.pipeline.getSampleCount());
+            this.postPasses ??= new PostPassChain(this.device, this.pipeline.getSampleCount(), this.pipeline.getBindGroupLayout());
             this.postPasses.encode({
                 encoder,
                 targetView: textureView,
@@ -2829,6 +2807,7 @@ export class Renderer {
                 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,
+                selectionOutline,
             });
             colorReadback = colorCapture && encodeRendererColorFrameCapture(device, encoder, colorCapture);
             device.queue.submit([encoder.finish()]);
@@ -2973,7 +2952,11 @@ export class Renderer {
      * These are scaled internally to match the actual canvas pixel dimensions.
      */
     raycastSceneMagnetic(x, y, currentEdgeLock, options) {
-        return this.raycastEngine.raycastSceneMagnetic(x, y, currentEdgeLock, options);
+        return this.raycastEngine.raycastSceneMagnetic(x, y, currentEdgeLock, options, this.activePickClip());
+    }
+    /** Opt in the currently selected authored curves for exact magnetic picking. */
+    setSourceSnapCurves(curves) {
+        this.raycastEngine.setSourceSnapCurves(curves);
     }
     /**
      * Invalidate BVH cache (call when geometry changes)
@@ -3076,13 +3059,31 @@ 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) {
+        const previous = this.overlayTheme;
+        this.overlayTheme = theme;
+        this.pipeline?.selectionColorUniform.update(theme.selection);
+        this.overlays.setTheme(theme);
+        // Clash-pair tints already uploaded to the entity colour table must
+        // follow a theme change as the other clash overlays do (#5490).
+        const installed = this.scene.getColorOverrides();
+        const repainted = installed && remapOverrideColors(installed, [[previous.clashA, theme.clashA], [previous.clashB, theme.clashB]]);
+        const device = this.getGPUDevice();
+        if (repainted && device && this.pipeline) {
+            this.scene.setColorOverrides(repainted, device, this.pipeline);
+            this.requestRender();
+        }
     }
     /**
      * Set one standalone 3D line overlay, or clear it by passing `null`.
@@ -3095,7 +3096,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
@@ -3115,8 +3116,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);
@@ -3125,8 +3128,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);
@@ -3138,7 +3143,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);
@@ -3292,6 +3298,7 @@ export class Renderer {
         this.pickingManager.setPicker(null);
         this.postPasses?.destroy();
         this.postPasses = null;
+        this.hoverMeshes.release();
         this.skyPass?.destroy();
         this.skyPass = null;
         this.shadowPass?.destroy();