@ifc-lite/renderer 5.0.0 → 6.0.1

package/dist/index.js

@@ -78,9 +78,10 @@ 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';
@@ -92,6 +93,8 @@ 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';
@@ -103,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.
  *
@@ -165,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();
@@ -372,6 +377,8 @@ export class Renderer {
     _xrayEpochs = new XRayEpochTracker();
     _visibilityVersion = 0;
     _partialBatchEpoch = 0;
+    _xrayAlpha = null;
+    _xrayAlphaEpoch = -1;
     _lastColorOverrideGen = -1;
     _xrayVersion = 0;
     _lastHadPartialSources = false;
@@ -400,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.
@@ -979,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.
      *
@@ -1152,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
@@ -1159,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.
@@ -1240,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,
         });
     }
@@ -1519,14 +1472,6 @@ 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 edge pass reads the object-id attachment after the pass.
         const needsObjectIdPass = livePostEffects(visualEnhancement, effectsLive).edges;
         // Check if visibility filtering is active
@@ -1603,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".
@@ -1616,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)
@@ -1753,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;
@@ -1773,7 +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]);
-                    packMeshMaterial(meshBuf, mesh.color[3], mesh.material);
+                    packMeshMaterial(meshBuf, mesh.color[3], mesh.finish ?? mesh.material);
                     // Section plane data (offset 40-43)
                     if (sectionPlaneData) {
                         meshBuf[40] = sectionPlaneData.normal[0];
@@ -1796,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);
                 }
@@ -2041,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
@@ -2271,22 +2229,25 @@ 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 the per-batch colour, and the material its AUTHORED
@@ -2295,7 +2256,7 @@ export class Renderer {
                     tpl[33] = batch.color[1];
                     tpl[34] = batch.color[2];
                     tpl[35] = alphaForBatch(batch, batch.color[3]);
-                    packMeshMaterial(tpl, 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).
@@ -2309,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).
@@ -2318,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);
@@ -2341,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;
@@ -2362,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
@@ -2407,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
@@ -2417,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
@@ -2458,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
@@ -2473,7 +2439,8 @@ export class Renderer {
                         tpl[28] = tm.origin[0];
                         tpl[29] = tm.origin[1];
                         tpl[30] = tm.origin[2];
-                        relativeToEyeFrame.packDrawableOrigin(tm.origin, tpl, MESH_UNIFORM_OFFSET.drawableDelta);
+                        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];
@@ -2488,7 +2455,7 @@ export class Renderer {
                         // 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);
+                        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);
@@ -2519,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);
@@ -2533,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) {
@@ -2543,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
-                // 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) {
-                    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
@@ -2622,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
@@ -2635,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());
                 }
@@ -2665,7 +2611,7 @@ export class Renderer {
                         tpl[33] = mesh.color[1];
                         tpl[34] = mesh.color[2];
                         tpl[35] = alphaForMesh(mesh.expressId, mesh.color[3]);
-                        packMeshMaterial(tpl, mesh.color[3], mesh.material);
+                        packMeshMaterial(tpl, mesh.color[3], mesh.finish ?? mesh.material);
                         if (sectionPlaneData) {
                             tpl[40] = sectionPlaneData.normal[0];
                             tpl[41] = sectionPlaneData.normal[1];
@@ -2683,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);
@@ -2726,7 +2673,7 @@ export class Renderer {
                     tpl[33] = mesh.color[1];
                     tpl[34] = mesh.color[2];
                     tpl[35] = mesh.color[3];
-                    packMeshMaterial(tpl, mesh.color[3], mesh.material);
+                    packMeshMaterial(tpl, mesh.color[3], mesh.finish ?? mesh.material);
                     if (sectionPlaneData) {
                         tpl[40] = sectionPlaneData.normal[0];
                         tpl[41] = sectionPlaneData.normal[1];
@@ -2744,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());
@@ -2763,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);
                     }
@@ -2778,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);
                         }
@@ -2822,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,
@@ -2838,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()]);
@@ -2982,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)
@@ -3097,9 +3071,19 @@ export class Renderer {
      * `SymbolicTextInput.color` on `uploadAnnotationTexts3D`.
      */
     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`.
@@ -3314,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();