@ifc-lite/renderer 1.17.0 → 1.20.0

package/dist/index.js

@@ -16,6 +16,7 @@ export { Section2DOverlayRenderer } from './section-2d-overlay.js';
 // is now rendered by Section2DOverlayRenderer's fill pass; this module just
 // holds the styling primitives shared with the store and UI.
 export { DEFAULT_CAP_STYLE, HATCH_PATTERN_IDS } from './section-cap-style.js';
+export { planeBasis, nearestCardinalAxis } from './section-plane-basis.js';
 export { Raycaster } from './raycaster.js';
 export { SnapDetector, SnapType } from './snap-detector.js';
 export { BVH } from './bvh.js';
@@ -26,6 +27,10 @@ export { ZeroCopyGpuUploader, createZeroCopyUploader, } from './zero-copy-upload
 // Extracted manager classes
 export { PickingManager } from './picking-manager.js';
 export { RaycastEngine } from './raycast-engine.js';
+export { PointPicker, decodePickSample } from './point-picker.js';
+// Point cloud rendering (Phase 0: IFCx inline; Phase 1+: streaming LAS/LAZ)
+export { PointCloudRenderer } from './pointcloud/point-cloud-renderer.js';
+export { PointRenderPipeline } from './pointcloud/point-pipeline.js';
 import { WebGPUDevice } from './device.js';
 import { RenderPipeline, InstancedRenderPipeline } from './pipeline.js';
 import { Camera } from './camera.js';
@@ -40,8 +45,31 @@ import { DEFAULT_CAP_STYLE, HATCH_PATTERN_IDS } from './section-cap-style.js';
 import { PickingManager } from './picking-manager.js';
 import { RaycastEngine } from './raycast-engine.js';
 import { PostProcessor } from './post-processor.js';
+import { EdlPass } from './edl-pass.js';
+import { PointCloudRenderer } from './pointcloud/point-cloud-renderer.js';
+import { DeviationPipeline } from './deviation/deviation-pipeline.js';
+import { buildTriangleBVH } from './deviation/triangle-bvh.js';
 const MAX_ENCODED_ENTITY_ID = 0xFFFFFF;
 let warnedEntityIdRange = false;
+/**
+ * Build a deterministic fingerprint of the BVH input mesh set so
+ * `Renderer.computeDeviations` can skip the rebuild when the source
+ * geometry hasn't changed. Folds in expressId / modelIndex / position
+ * + index lengths per mesh so two distinct mesh sets that happen to
+ * share the same aggregate position-length total can't collide on the
+ * same fingerprint and reuse a stale BVH.
+ */
+function computeBvhFingerprint(meshes) {
+    const parts = [String(meshes.length)];
+    for (const m of meshes) {
+        const id = m.expressId ?? -1;
+        const mi = m.modelIndex ?? -1;
+        const posLen = m.positions?.length ?? 0;
+        const idxLen = m.indices?.length ?? 0;
+        parts.push(`${id}:${mi}:${posLen}:${idxLen}`);
+    }
+    return parts.join('|');
+}
 /**
  * Main renderer class
  */
@@ -56,6 +84,23 @@ export class Renderer {
     sectionPlaneRenderer = null;
     section2DOverlayRenderer = null;
     postProcessor = null;
+    edlPass = null;
+    edlOptions = {
+        enabled: false,
+        strength: 1,
+        radiusPx: 1,
+        highQuality: true,
+    };
+    pointCloudRenderer = null;
+    deviationPipeline = null;
+    /**
+     * Cache of which mesh-set the BVH was built from. We rebuild on
+     * `computeDeviations` only when the cached "fingerprint" misses,
+     * so re-running deviation against the same model is a fast
+     * dispatch — the BVH is multi-second on big BIMs and we don't
+     * want to pay that on every slider drag.
+     */
+    deviationBvhFingerprint = null;
     visualEnhancementState = {
         enabled: true,
         edgeContrast: { enabled: true, intensity: 1.0 },
@@ -70,6 +115,11 @@ export class Renderer {
     // Error rate limiting (log at most once per second)
     lastRenderErrorTime = 0;
     RENDER_ERROR_THROTTLE_MS = 1000;
+    // Diagnostic counters for mobile debugging
+    _renderCallCount = 0;
+    _renderSkipCount = 0;
+    _renderErrorCount = 0;
+    _lastRenderError = '';
     // Dirty flag: set by requestRender(), consumed by the animation loop.
     // Centralises all render scheduling — callers never call render() directly.
     _renderRequested = false;
@@ -108,14 +158,335 @@ export class Renderer {
         this.picker = new Picker(this.device, width, height);
         this.sectionPlaneRenderer = new SectionPlaneRenderer(this.device.getDevice(), this.device.getFormat(), this.pipeline.getSampleCount());
         this.section2DOverlayRenderer = new Section2DOverlayRenderer(this.device.getDevice(), this.device.getFormat(), this.pipeline.getSampleCount());
-        this.postProcessor = new PostProcessor(this.device, {
-            enableContactShading: true,
-            contactRadius: 1.0,
-            contactIntensity: 0.3,
-        }, this.pipeline.getSampleCount());
+        // PostProcessor is optional — if it fails (e.g. mobile GPU lacking
+        // depth TEXTURE_BINDING), rendering still works without post-processing.
+        try {
+            this.postProcessor = new PostProcessor(this.device, {
+                enableContactShading: true,
+                contactRadius: 1.0,
+                contactIntensity: 0.3,
+            }, this.pipeline.getSampleCount());
+        }
+        catch (e) {
+            console.warn('[Renderer] PostProcessor init failed (post-processing disabled):', e);
+            this.postProcessor = null;
+        }
+        this.pointCloudRenderer = new PointCloudRenderer(this.device.getDevice(), this.device.getFormat(), 'depth24plus-stencil8', this.pipeline.getSampleCount());
+        // Compute pipeline for the BIM↔scan deviation heatmap. Lazily
+        // owns the per-triangle BVH GPU buffers; idle until the first
+        // `computeDeviations` call.
+        this.deviationPipeline = new DeviationPipeline(this.device.getDevice());
+        this.edlPass = new EdlPass(this.device, this.pipeline.getSampleCount());
         this.camera.setAspect(width / height);
         // Update picking manager with initialized picker
         this.pickingManager.setPicker(this.picker);
+        // Provide a snapshot of pickable point nodes per pick. The
+        // sizing must mirror the live splat shader so click hit-testing
+        // matches what the user actually sees on screen.
+        this.pickingManager.setPointPickProvider(() => {
+            const pcr = this.pointCloudRenderer;
+            if (!pcr || !pcr.hasAssets())
+                return null;
+            const opts = pcr.getOptions();
+            const sizeMode = opts.sizeMode === 'fixed-px' ? 0 : opts.sizeMode === 'adaptive-world' ? 1 : 2;
+            return {
+                nodes: pcr.getPickNodes(),
+                sizing: {
+                    sizeMode: sizeMode,
+                    worldRadius: opts.worldRadius,
+                    pointSizePx: opts.pointSize,
+                    clickTolerancePx: 2,
+                },
+            };
+        });
+    }
+    /**
+     * Replace all loaded point clouds with `assets`.
+     *
+     * Phase 0 entry point — single-chunk inline assets from IFCx
+     * (`pcd::base64`, `points::array`, `points::base64`). Future phases
+     * accept streaming sources via a different overload.
+     */
+    setPointClouds(assets) {
+        if (!this.pointCloudRenderer) {
+            throw new Error('Renderer not initialized. Call init() first.');
+        }
+        this.pointCloudRenderer.setAssets(assets);
+        // Replace, not append — bounds may have shrunk (e.g. an IFCx
+        // reload with a smaller scan). `expandModelBoundsForPointClouds`
+        // alone only grows; recompute from scratch to keep
+        // fit-to-view + section-plane sliders accurate.
+        this.recomputeModelBounds();
+        this.camera.setSceneBounds(this.modelBounds);
+        this.requestRender();
+    }
+    /** Append additional point clouds without clearing existing ones. */
+    addPointClouds(assets) {
+        if (!this.pointCloudRenderer) {
+            throw new Error('Renderer not initialized. Call init() first.');
+        }
+        for (const asset of assets) {
+            this.pointCloudRenderer.addAsset(asset);
+        }
+        this.expandModelBoundsForPointClouds();
+        this.camera.setSceneBounds(this.modelBounds);
+        this.requestRender();
+    }
+    /** Total number of point cloud assets currently uploaded. */
+    getPointCloudAssetCount() {
+        return this.pointCloudRenderer?.getNodeCount() ?? 0;
+    }
+    /** Total number of points across all point cloud assets. */
+    getPointCloudPointCount() {
+        return this.pointCloudRenderer?.getPointCount() ?? 0;
+    }
+    /** Drop all point cloud GPU resources. */
+    clearPointClouds() {
+        this.pointCloudRenderer?.clear();
+        this.recomputeModelBounds();
+        this.camera.setSceneBounds(this.modelBounds);
+        this.requestRender();
+    }
+    /**
+     * Streaming entry: open an empty asset that will receive chunks via
+     * `appendPointCloudChunk`. Call `endPointCloudStream` when no more
+     * chunks will arrive (currently a no-op but kept for symmetry).
+     */
+    beginPointCloudStream(meta) {
+        if (!this.pointCloudRenderer) {
+            throw new Error('Renderer not initialized. Call init() first.');
+        }
+        return this.pointCloudRenderer.beginAsset(meta);
+    }
+    appendPointCloudChunk(handle, chunk) {
+        if (!this.pointCloudRenderer)
+            return;
+        this.pointCloudRenderer.appendChunk(handle, chunk);
+        this.expandModelBoundsForPointClouds();
+        this.camera.setSceneBounds(this.modelBounds);
+        this.requestRender();
+    }
+    endPointCloudStream(handle) {
+        this.pointCloudRenderer?.endAsset(handle);
+        this.requestRender();
+    }
+    removePointCloudAsset(handle) {
+        this.pointCloudRenderer?.removeAsset(handle);
+        // Bounds may have shrunk — recompute from scratch so fit-to-view
+        // and section-plane sliders see fresh extents.
+        this.recomputeModelBounds();
+        this.camera.setSceneBounds(this.modelBounds);
+        this.requestRender();
+    }
+    /**
+     * Reassign a streamed point-cloud's expressId after upload. Use
+     * this when the federation registry assigns a new model offset and
+     * the renderer needs to emit the post-offset globalId in picking
+     * outputs. The change takes effect on the next render — no GPU
+     * buffer rewrite needed.
+     */
+    relabelPointCloudAsset(handle, newExpressId) {
+        this.pointCloudRenderer?.relabelAsset(handle, newExpressId);
+        this.requestRender();
+    }
+    /**
+     * Compute model bounds from triangle meshes + remaining point clouds.
+     * Called from removeAsset / clear paths so bounds shrink correctly.
+     * Triangle meshes still drive the bounds when present (existing
+     * Scene-driven path), so this only re-folds in the point cloud
+     * extents over whatever the mesh path left.
+     */
+    recomputeModelBounds() {
+        // Always recompute from scratch: take mesh bounds as the
+        // baseline, then fold in the CURRENT point-cloud bounds on
+        // top. Folding only-up via expandModelBoundsForPointClouds()
+        // is correct when pc bounds grow but never shrinks them when
+        // an asset is removed, leaving stale oversized extents until
+        // every point cloud is gone.
+        const meshBounds = this.computeMeshBounds();
+        const pcBounds = this.pointCloudRenderer?.getBounds() ?? null;
+        if (!meshBounds && !pcBounds) {
+            this.modelBounds = null;
+            return;
+        }
+        this.modelBounds = meshBounds ?? {
+            min: { x: pcBounds.min[0], y: pcBounds.min[1], z: pcBounds.min[2] },
+            max: { x: pcBounds.max[0], y: pcBounds.max[1], z: pcBounds.max[2] },
+        };
+        if (meshBounds && pcBounds) {
+            this.expandModelBoundsForPointClouds();
+        }
+    }
+    /** Aggregate bounds across all batched + individual meshes. Returns
+     *  null if the scene has no mesh geometry. */
+    computeMeshBounds() {
+        let minX = Infinity, minY = Infinity, minZ = Infinity;
+        let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+        let any = false;
+        for (const batch of this.scene.getBatchedMeshes()) {
+            if (!batch.bounds)
+                continue;
+            any = true;
+            if (batch.bounds.min[0] < minX)
+                minX = batch.bounds.min[0];
+            if (batch.bounds.min[1] < minY)
+                minY = batch.bounds.min[1];
+            if (batch.bounds.min[2] < minZ)
+                minZ = batch.bounds.min[2];
+            if (batch.bounds.max[0] > maxX)
+                maxX = batch.bounds.max[0];
+            if (batch.bounds.max[1] > maxY)
+                maxY = batch.bounds.max[1];
+            if (batch.bounds.max[2] > maxZ)
+                maxZ = batch.bounds.max[2];
+        }
+        if (!any)
+            return null;
+        return { min: { x: minX, y: minY, z: minZ }, max: { x: maxX, y: maxY, z: maxZ } };
+    }
+    /** Apply rendering options (color mode, fixed override, point size). */
+    setPointCloudOptions(opts) {
+        this.pointCloudRenderer?.setOptions(opts);
+        this.requestRender();
+    }
+    /**
+     * Compute BIM ↔ scan deviation for every loaded point cloud asset.
+     *
+     * Walks every triangle in the scene (individual + batched meshes,
+     * regardless of which IFC ingest path produced them — STEP, IFCx,
+     * GLB, or federated combinations), builds a per-triangle BVH on
+     * the GPU, then runs a closest-point compute pass per chunk that
+     * writes signed distance into each chunk's deviation buffer.
+     *
+     * Returns metadata so the UI can populate a histogram + auto-range:
+     * the per-asset point count, the suggested ±range from the 95th
+     * percentile, and the bbox the BVH was built from.
+     *
+     * Idempotent: re-running with the same mesh set reuses the GPU
+     * BVH (the BVH build dominates wall time on big BIMs). Pass
+     * `forceRebuild: true` to invalidate.
+     */
+    async computeDeviations(opts = {}) {
+        if (!this.deviationPipeline || !this.pointCloudRenderer) {
+            throw new Error('Renderer not initialised — call init() first.');
+        }
+        const meshes = this.collectAllSceneMeshes();
+        // Fingerprint folds in per-mesh expressId / modelIndex /
+        // positions length / triangle count, so two distinct meshes
+        // that happen to share an aggregate position-length total
+        // can't alias each other. A federation reload that swaps one
+        // model for another with the same total triangle count would
+        // otherwise reuse the previous BVH and report wrong distances.
+        const fingerprint = computeBvhFingerprint(meshes);
+        if (opts.forceRebuild || fingerprint !== this.deviationBvhFingerprint) {
+            const bvh = buildTriangleBVH(meshes);
+            this.deviationPipeline.uploadBvh(bvh);
+            this.deviationBvhFingerprint = fingerprint;
+        }
+        const stats = this.deviationPipeline.getBvhStats();
+        const maxRange = opts.maxRange ?? 1.0;
+        // Encode every chunk into a single command submit so the GPU
+        // can pipeline the dispatches without a CPU round-trip per
+        // chunk. Histogram readback is a follow-up — for v1 we emit
+        // the deviation buffers and let the splat shader visualise.
+        const encoder = this.device.getDevice().createCommandEncoder({ label: 'pointcloud-deviation' });
+        let chunksProcessed = 0;
+        let pointsProcessed = 0;
+        const nodes = this.pointCloudRenderer.getInternalNodes();
+        for (const node of nodes) {
+            for (const chunk of node.chunks) {
+                const ok = this.deviationPipeline.dispatch(encoder, {
+                    positionsBuffer: chunk.vertexBuffer,
+                    deviationsBuffer: chunk.deviationBuffer,
+                    pointCount: chunk.pointCount,
+                    maxRange,
+                });
+                if (ok) {
+                    chunksProcessed++;
+                    pointsProcessed += chunk.pointCount;
+                }
+            }
+        }
+        this.device.getDevice().queue.submit([encoder.finish()]);
+        // Wait until the GPU finishes the dispatches before resolving.
+        // Otherwise the caller's "compute done" callback fires before
+        // the deviation buffers are actually populated.
+        await this.device.getDevice().queue.onSubmittedWorkDone();
+        this.requestRender();
+        // Suggest a default half-range = max(0.01m, max-extent / 1000).
+        // Tighter than the maxRange clip; gives the user a reasonable
+        // starting slider position without a histogram readback.
+        const bb = stats.bounds;
+        const suggestedHalfRange = bb
+            ? Math.max(0.01, Math.max(bb.max[0] - bb.min[0], bb.max[1] - bb.min[1], bb.max[2] - bb.min[2]) / 1000)
+            : 0.05;
+        return {
+            bvhTriangles: stats.triangleCount,
+            bvhNodes: stats.nodeCount,
+            chunksProcessed,
+            pointsProcessed,
+            bounds: stats.bounds,
+            suggestedHalfRange,
+        };
+    }
+    /**
+     * Aggregate every triangle source the scene exposes — individual
+     * meshes (created on demand by picking / highlights) AND batched
+     * meshes (the streaming geometry path's compact GPU buffers).
+     * Both formats arrive as `MeshData`; the BVH builder doesn't care
+     * which source they came from.
+     */
+    collectAllSceneMeshes() {
+        // The Scene keeps every CPU-side MeshData regardless of which
+        // ingest path produced it (STEP / IFCx / GLB). One iteration
+        // covers individual + batched + multi-piece + multi-model.
+        // `forEachMeshData` deduplicates by identity so a colour-merged
+        // batch is only added once even if it's indexed under multiple
+        // contributor expressIds.
+        const out = [];
+        this.scene.forEachMeshData((md) => {
+            if (md.positions && md.positions.length > 0)
+                out.push(md);
+        });
+        return out;
+    }
+    /**
+     * Toggle Eye-Dome Lighting and tune its strength.
+     *
+     * EDL adds depth perception to point clouds (and meshes) via screen-
+     * space depth gradient — silhouette pixels get a soft black halo.
+     * Cheap: ~9 texture taps per pixel. Only runs when point clouds are
+     * loaded.
+     */
+    setEdlOptions(opts) {
+        if (opts.enabled !== undefined)
+            this.edlOptions.enabled = opts.enabled;
+        if (opts.strength !== undefined)
+            this.edlOptions.strength = Math.max(0, Math.min(3, opts.strength));
+        if (opts.radiusPx !== undefined)
+            this.edlOptions.radiusPx = Math.max(1, Math.min(4, opts.radiusPx));
+        if (opts.highQuality !== undefined)
+            this.edlOptions.highQuality = opts.highQuality;
+        this.requestRender();
+    }
+    expandModelBoundsForPointClouds() {
+        const pcBounds = this.pointCloudRenderer?.getBounds();
+        if (!pcBounds)
+            return;
+        if (!this.modelBounds) {
+            this.modelBounds = {
+                min: { x: pcBounds.min[0], y: pcBounds.min[1], z: pcBounds.min[2] },
+                max: { x: pcBounds.max[0], y: pcBounds.max[1], z: pcBounds.max[2] },
+            };
+            return;
+        }
+        const m = this.modelBounds;
+        m.min.x = Math.min(m.min.x, pcBounds.min[0]);
+        m.min.y = Math.min(m.min.y, pcBounds.min[1]);
+        m.min.z = Math.min(m.min.z, pcBounds.min[2]);
+        m.max.x = Math.max(m.max.x, pcBounds.max[0]);
+        m.max.y = Math.max(m.max.y, pcBounds.max[1]);
+        m.max.z = Math.max(m.max.z, pcBounds.max[2]);
     }
     /**
      * Load geometry from GeometryResult or MeshData array
@@ -500,9 +871,32 @@ export class Renderer {
     /**
      * Render frame
      */
+    /** Get diagnostic info for mobile debugging */
+    getDiagnostics() {
+        const pos = this.camera.getPosition();
+        const tgt = this.camera.getTarget();
+        const b = this.modelBounds;
+        return {
+            calls: this._renderCallCount,
+            skips: this._renderSkipCount,
+            errors: this._renderErrorCount,
+            lastError: this._lastRenderError,
+            batches: this.scene.getBatchedMeshes().length,
+            meshes: this.scene.getMeshes().length,
+            contextOk: this.device.isInitialized(),
+            gpuErrors: this.device._uncapturedErrorCount,
+            lastGpuError: this.device._lastUncapturedError ?? '',
+            camPos: `${pos.x.toFixed(1)},${pos.y.toFixed(1)},${pos.z.toFixed(1)}`,
+            camTgt: `${tgt.x.toFixed(1)},${tgt.y.toFixed(1)},${tgt.z.toFixed(1)}`,
+            bounds: b ? `${b.min.x.toFixed(0)}..${b.max.x.toFixed(0)} ${b.min.y.toFixed(0)}..${b.max.y.toFixed(0)} ${b.min.z.toFixed(0)}..${b.max.z.toFixed(0)}` : 'none',
+        };
+    }
     render(options = {}) {
-        if (!this.device.isInitialized() || !this.pipeline)
+        this._renderCallCount++;
+        if (!this.device.isInitialized() || !this.pipeline) {
+            this._renderSkipCount++;
             return;
+        }
         // Validate canvas dimensions
         // Align width to 64 pixels for WebGPU texture row alignment (256 bytes / 4 bytes per pixel)
         const rect = this.canvas.getBoundingClientRect();
@@ -510,8 +904,10 @@ export class Renderer {
         const width = Math.max(64, Math.floor(rawWidth / 64) * 64);
         const height = Math.max(1, Math.floor(rect.height));
         // Skip rendering if canvas is too small
-        if (width < 64 || height < 10)
+        if (width < 64 || height < 10) {
+            this._renderSkipCount++;
             return;
+        }
         // Update canvas pixel dimensions if needed
         const dimensionsChanged = this.canvas.width !== width || this.canvas.height !== height;
         if (dimensionsChanged) {
@@ -527,10 +923,13 @@ export class Renderer {
             }
         }
         // Skip rendering if canvas is invalid
-        if (this.canvas.width === 0 || this.canvas.height === 0)
+        if (this.canvas.width === 0 || this.canvas.height === 0) {
+            this._renderSkipCount++;
             return;
+        }
         // Ensure context is valid before rendering (handles HMR, focus changes, etc.)
         if (!this.device.ensureContext()) {
+            this._renderSkipCount++;
             return; // Skip this frame, context will be ready next frame
         }
         const device = this.device.getDevice();
@@ -553,29 +952,66 @@ export class Renderer {
         const hasHiddenFilter = options.hiddenIds && options.hiddenIds.size > 0;
         const hasIsolatedFilter = options.isolatedIds !== null && options.isolatedIds !== undefined;
         const hasVisibilityFiltering = hasHiddenFilter || hasIsolatedFilter;
+        // Build the selected-id set once per frame so the X-Ray override paths
+        // can keep highlighted entities at full alpha without per-site checks.
+        const selectedId = options.selectedId;
+        const selectedIds = options.selectedIds;
+        const selectedModelIndex = options.selectedModelIndex;
+        const selectedExpressIds = new Set();
+        if (selectedId !== undefined && selectedId !== null) {
+            selectedExpressIds.add(selectedId);
+        }
+        if (selectedIds) {
+            for (const id of selectedIds) {
+                selectedExpressIds.add(id);
+            }
+        }
+        const hasSelected = selectedExpressIds.size > 0;
         // Per-frame alpha overrides for X-Ray mode. See RenderOptions.transparencyOverrides.
-        // Callers supply a fresh Map when contents change (same convention as hiddenIds/isolatedIds).
-        const txOverrides = options.transparencyOverrides;
-        const hasTxOverrides = txOverrides != null && txOverrides.size > 0;
+        // Snapshot the caller's map so mid-frame mutation can't desync classification
+        // and uniform-write decisions for the same batch/mesh.
+        const txOverridesSrc = options.transparencyOverrides;
+        const hasTxOverrides = txOverridesSrc != null && txOverridesSrc.size > 0;
+        const txOverrides = hasTxOverrides ? new Map(txOverridesSrc) : null;
         const alphaForMesh = (expressId, fallback) => {
             if (!hasTxOverrides)
                 return fallback;
+            // Selected meshes are exempt — the highlight pass renders them last,
+            // but exempting here also keeps mesh classification + uniform writes
+            // consistent so a selected mesh never enters the transparent pipeline
+            // because of its own override entry.
+            if (hasSelected && selectedExpressIds.has(expressId))
+                return fallback;
             const a = txOverrides.get(expressId);
             return a !== undefined ? a : fallback;
         };
-        // alphaForBatch walks batch.expressIds per frame. For typical batch sizes
-        // the cost is well below noise vs. the GPU work, and avoiding a cache
-        // removes the stale-on-mutation bug class entirely.
+        // Cache resolved batch alpha for the frame: classification needs it
+        // (opaque vs transparent routing) and renderBatch needs it for the
+        // uniform write. Without the cache we'd walk batch.expressIds twice
+        // per batch per frame, which becomes the dominant JS cost in X-Ray.
+        const batchAlphaCache = hasTxOverrides
+            ? new WeakMap()
+            : null;
         const alphaForBatch = (batch, fallback) => {
             if (!hasTxOverrides)
                 return fallback;
+            const cached = batchAlphaCache.get(batch);
+            if (cached !== undefined)
+                return cached;
             let minAlpha = Infinity;
             for (const eid of batch.expressIds) {
+                // Selected ids never drag down a batch's alpha — the highlight
+                // pass redraws them on top, but excluding here also means a
+                // batch made entirely of selected entities stays opaque.
+                if (hasSelected && selectedExpressIds.has(eid))
+                    continue;
                 const a = txOverrides.get(eid);
                 if (a !== undefined && a < minAlpha)
                     minAlpha = a;
             }
-            return minAlpha === Infinity ? fallback : minAlpha;
+            const resolved = minAlpha === Infinity ? fallback : minAlpha;
+            batchAlphaCache.set(batch, resolved);
+            return resolved;
         };
         // PERFORMANCE FIX: Use batch-level visibility filtering instead of creating individual meshes
         // Only create individual meshes for selected elements (for highlighting)
@@ -609,6 +1045,12 @@ export class Renderer {
         if (this.instancedPipeline?.needsResize(this.canvas.width, this.canvas.height)) {
             this.instancedPipeline.resize(this.canvas.width, this.canvas.height);
         }
+        // Push a validation error scope to capture the EXACT error (for mobile debugging)
+        // Only do this for the first few renders to avoid performance overhead
+        const captureGpuError = this._renderCallCount <= 5;
+        if (captureGpuError) {
+            device.pushErrorScope('validation');
+        }
         // Get current texture safely - may return null if context needs reconfiguration
         const currentTexture = this.device.getCurrentTexture();
         if (!currentTexture) {
@@ -645,9 +1087,6 @@ export class Renderer {
             // Write uniform data to each mesh's buffer BEFORE recording commands
             // This ensures each mesh has its own color data
             const allMeshes = [...opaqueMeshes, ...transparentMeshes];
-            const selectedId = options.selectedId;
-            const selectedIds = options.selectedIds;
-            const selectedModelIndex = options.selectedModelIndex;
             // Calculate section plane parameters and model bounds
             // Always calculate bounds when sectionPlane is provided (for preview and active mode)
             let sectionPlaneData;
@@ -682,6 +1121,21 @@ export class Renderer {
                         boundsMax.z = Math.max(boundsMax.z, batch.bounds.max[2]);
                     }
                 }
+                // Fold in point-cloud bounds too — without this, a
+                // pure point-cloud scene falls through to the default
+                // [-100,100], and a mixed scene clips against a
+                // smaller mesh-only range while the point pipeline
+                // (which honours the same sectionPlaneData) keeps
+                // drawing points outside the slider's reach.
+                const pcBoundsForSection = this.pointCloudRenderer?.getBounds();
+                if (pcBoundsForSection) {
+                    boundsMin.x = Math.min(boundsMin.x, pcBoundsForSection.min[0]);
+                    boundsMin.y = Math.min(boundsMin.y, pcBoundsForSection.min[1]);
+                    boundsMin.z = Math.min(boundsMin.z, pcBoundsForSection.min[2]);
+                    boundsMax.x = Math.max(boundsMax.x, pcBoundsForSection.max[0]);
+                    boundsMax.y = Math.max(boundsMax.y, pcBoundsForSection.max[1]);
+                    boundsMax.z = Math.max(boundsMax.z, pcBoundsForSection.max[2]);
+                }
                 // If no batched meshes have bounds yet (streaming, degenerate
                 // models), fall back to individual meshes so at least the
                 // slider has a workable range.
@@ -717,82 +1171,113 @@ export class Renderer {
                     };
                 }
                 if (options.sectionPlane.enabled) {
-                    // Calculate plane normal based on semantic axis
-                    // down = Y axis (horizontal cut), front = Z axis, side = X axis
-                    let normal = [0, 0, 0];
-                    if (options.sectionPlane.axis === 'side')
-                        normal[0] = 1; // X axis
-                    else if (options.sectionPlane.axis === 'down')
-                        normal[1] = 1; // Y axis (horizontal)
-                    else
-                        normal[2] = 1; // Z axis (front)
-                    // Apply building rotation if present (rotate normal around Y axis)
-                    // Building rotation is in X-Y plane (Z is up in IFC, Y is up in WebGL)
-                    if (options.buildingRotation !== undefined && options.buildingRotation !== 0) {
-                        const cosR = Math.cos(options.buildingRotation);
-                        const sinR = Math.sin(options.buildingRotation);
-                        // Rotate normal vector around Y axis (vertical)
-                        // For X-Z plane rotation: x' = x*cos - z*sin, z' = x*sin + z*cos, y' = y
-                        const x = normal[0];
-                        const z = normal[2];
-                        normal[0] = x * cosR - z * sinR;
-                        normal[2] = x * sinR + z * cosR;
-                        // Normalize to maintain unit length
-                        const len = Math.sqrt(normal[0] * normal[0] + normal[1] * normal[1] + normal[2] * normal[2]);
-                        if (len > 0.0001) {
-                            normal[0] /= len;
-                            normal[1] /= len;
-                            normal[2] /= len;
+                    // Explicit normal + distance override (face-pick / arbitrary
+                    // plane, issue #243). Used verbatim: no axis mapping, no
+                    // position slider, no building rotation — the caller already
+                    // has the plane in world space.
+                    const explicitNormal = options.sectionPlane.normal;
+                    const explicitDistance = options.sectionPlane.distance;
+                    const hasExplicitPlane = explicitNormal !== undefined &&
+                        explicitDistance !== undefined &&
+                        Number.isFinite(explicitDistance);
+                    let normal;
+                    let distance;
+                    if (hasExplicitPlane) {
+                        // Defensive renormalisation in case the caller passed a
+                        // non-unit vector (e.g. mesh face normals quantised by
+                        // the geometry pipeline).
+                        const nx = explicitNormal[0];
+                        const ny = explicitNormal[1];
+                        const nz = explicitNormal[2];
+                        const len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+                        if (len > 1e-6) {
+                            normal = [nx / len, ny / len, nz / len];
+                            distance = explicitDistance / len;
+                        }
+                        else {
+                            normal = [0, 1, 0];
+                            distance = explicitDistance;
                         }
                     }
-                    // Get axis-specific range. The renderer's own `boundsMin/Max`
-                    // are computed from the GPU vertex buffers this frame, so
-                    // they are guaranteed to be in the same Y-up world space as
-                    // `input.worldPos` in the shader. `options.sectionPlane.min/max`
-                    // comes from the UI via `coordinateInfo.shiftedBounds` and can
-                    // be stale during streaming or outright wrong during model
-                    // load (initialised to {0,0,0} before the first bounds update)
-                    // — using those directly was the cause of the "slider moves
-                    // 1% and the whole model disappears" bug.
-                    //
-                    // Policy: always use the renderer's own bounds for the Y-up
-                    // range. Only honour the UI override when it is a valid,
-                    // non-degenerate range that lies INSIDE the actual mesh
-                    // bounds (e.g. storey filtering from the level picker).
-                    const axisIdx = options.sectionPlane.axis === 'side' ? 'x' : options.sectionPlane.axis === 'down' ? 'y' : 'z';
-                    let minVal = boundsMin[axisIdx];
-                    let maxVal = boundsMax[axisIdx];
-                    const uiMin = options.sectionPlane.min;
-                    const uiMax = options.sectionPlane.max;
-                    if (Number.isFinite(uiMin) &&
-                        Number.isFinite(uiMax) &&
-                        uiMax - uiMin > 1e-6 &&
-                        uiMin >= minVal - 1e-3 &&
-                        uiMax <= maxVal + 1e-3) {
-                        minVal = uiMin;
-                        maxVal = uiMax;
+                    else {
+                        // Cardinal-axis preset path (unchanged behaviour).
+                        // down = Y axis (horizontal cut), front = Z axis, side = X axis
+                        normal = [0, 0, 0];
+                        if (options.sectionPlane.axis === 'side')
+                            normal[0] = 1; // X axis
+                        else if (options.sectionPlane.axis === 'down')
+                            normal[1] = 1; // Y axis (horizontal)
+                        else
+                            normal[2] = 1; // Z axis (front)
+                        // Apply building rotation if present (rotate normal around Y axis)
+                        // Building rotation is in X-Y plane (Z is up in IFC, Y is up in WebGL)
+                        if (options.buildingRotation !== undefined && options.buildingRotation !== 0) {
+                            const cosR = Math.cos(options.buildingRotation);
+                            const sinR = Math.sin(options.buildingRotation);
+                            // Rotate normal vector around Y axis (vertical)
+                            // For X-Z plane rotation: x' = x*cos - z*sin, z' = x*sin + z*cos, y' = y
+                            const x = normal[0];
+                            const z = normal[2];
+                            normal[0] = x * cosR - z * sinR;
+                            normal[2] = x * sinR + z * cosR;
+                            // Normalize to maintain unit length
+                            const rlen = Math.sqrt(normal[0] * normal[0] + normal[1] * normal[1] + normal[2] * normal[2]);
+                            if (rlen > 0.0001) {
+                                normal[0] /= rlen;
+                                normal[1] /= rlen;
+                                normal[2] /= rlen;
+                            }
+                        }
+                        // Get axis-specific range. The renderer's own `boundsMin/Max`
+                        // are computed from the GPU vertex buffers this frame, so
+                        // they are guaranteed to be in the same Y-up world space as
+                        // `input.worldPos` in the shader. `options.sectionPlane.min/max`
+                        // comes from the UI via `coordinateInfo.shiftedBounds` and can
+                        // be stale during streaming or outright wrong during model
+                        // load (initialised to {0,0,0} before the first bounds update)
+                        // — using those directly was the cause of the "slider moves
+                        // 1% and the whole model disappears" bug.
+                        //
+                        // Policy: always use the renderer's own bounds for the Y-up
+                        // range. Only honour the UI override when it is a valid,
+                        // non-degenerate range that lies INSIDE the actual mesh
+                        // bounds (e.g. storey filtering from the level picker).
+                        const axisIdx = options.sectionPlane.axis === 'side' ? 'x' : options.sectionPlane.axis === 'down' ? 'y' : 'z';
+                        let minVal = boundsMin[axisIdx];
+                        let maxVal = boundsMax[axisIdx];
+                        const uiMin = options.sectionPlane.min;
+                        const uiMax = options.sectionPlane.max;
+                        if (Number.isFinite(uiMin) &&
+                            Number.isFinite(uiMax) &&
+                            uiMax - uiMin > 1e-6 &&
+                            uiMin >= minVal - 1e-3 &&
+                            uiMax <= maxVal + 1e-3) {
+                            minVal = uiMin;
+                            maxVal = uiMax;
+                        }
+                        // Calculate plane distance from position percentage
+                        const range = maxVal - minVal;
+                        distance = minVal + (options.sectionPlane.position / 100) * range;
                     }
-                    // Calculate plane distance from position percentage
-                    const range = maxVal - minVal;
-                    const distance = minVal + (options.sectionPlane.position / 100) * range;
                     sectionPlaneData = { normal, distance, enabled: true };
                     // One-shot diagnostic: when section first becomes active,
-                    // log the exact bounds + distance the shader will use.
-                    // This is the fastest way to confirm "bounds mismatch" bugs
-                    // without asking the user to run a debugger.
+                    // log the exact bounds + plane the shader will use. This
+                    // is the fastest way to confirm "bounds mismatch" / "plane
+                    // off-screen" bugs without asking the user to run a
+                    // debugger. The custom-plane branch logs `mode: 'explicit'`
+                    // so reports against tilted planes are easy to spot.
                     if (!this._loggedSectionBounds) {
                         this._loggedSectionBounds = true;
                         console.info('[Section] Y-up bounds used for clip:', {
+                            mode: hasExplicitPlane ? 'explicit' : 'axis-aligned',
                             axis: options.sectionPlane.axis,
-                            axisIdx,
                             bounds: {
                                 min: { x: boundsMin.x, y: boundsMin.y, z: boundsMin.z },
                                 max: { x: boundsMax.x, y: boundsMax.y, z: boundsMax.z },
                             },
-                            uiOverride: { min: uiMin, max: uiMax },
-                            used: { min: minVal, max: maxVal },
-                            position: options.sectionPlane.position,
+                            normal,
                             distance,
+                            position: options.sectionPlane.position,
                             batchedMeshCount: this.scene.getBatchedMeshes().length,
                         });
                     }
@@ -849,24 +1334,26 @@ export class Renderer {
             // Set up MSAA rendering if enabled
             const msaaView = this.pipeline.getMultisampleTextureView();
             const useMSAA = msaaView !== null && this.pipeline.getSampleCount() > 1;
+            // Build color attachments — skip objectId in single-target mode
+            const colorAttachments = [
+                {
+                    // If MSAA enabled: render to multisample texture, resolve to swap chain
+                    // If MSAA disabled: render directly to swap chain
+                    view: useMSAA ? msaaView : textureView,
+                    resolveTarget: useMSAA ? textureView : undefined,
+                    loadOp: 'clear',
+                    clearValue: clearColor,
+                    storeOp: (useMSAA ? 'discard' : 'store'),
+                },
+            ];
+            colorAttachments.push({
+                view: objectIdView,
+                loadOp: 'clear',
+                clearValue: { r: 0, g: 0, b: 0, a: 0 },
+                storeOp: (needsObjectIdPass ? 'store' : 'discard'),
+            });
             const pass = encoder.beginRenderPass({
-                colorAttachments: [
-                    {
-                        // If MSAA enabled: render to multisample texture, resolve to swap chain
-                        // If MSAA disabled: render directly to swap chain
-                        view: useMSAA ? msaaView : textureView,
-                        resolveTarget: useMSAA ? textureView : undefined,
-                        loadOp: 'clear',
-                        clearValue: clearColor,
-                        storeOp: useMSAA ? 'discard' : 'store', // Discard MSAA buffer after resolve
-                    },
-                    {
-                        view: objectIdView,
-                        loadOp: 'clear',
-                        clearValue: { r: 0, g: 0, b: 0, a: 0 },
-                        storeOp: needsObjectIdPass ? 'store' : 'discard',
-                    },
-                ],
+                colorAttachments,
                 depthStencilAttachment: {
                     view: this.pipeline.getDepthTextureView(),
                     depthClearValue: 0.0, // Reverse-Z: clear to 0.0 (far plane)
@@ -961,15 +1448,6 @@ export class Renderer {
                         opaqueBatches.push(batch);
                     }
                 }
-                const selectedExpressIds = new Set();
-                if (selectedId !== undefined && selectedId !== null) {
-                    selectedExpressIds.add(selectedId);
-                }
-                if (selectedIds) {
-                    for (const id of selectedIds) {
-                        selectedExpressIds.add(id);
-                    }
-                }
                 // Build a uniform template ONCE per frame — shared across all batches.
                 // Only the 4-float color (offset 32) differs per batch; everything else
                 // (viewProj, identity model, material, section plane, flags) is identical.
@@ -1308,6 +1786,19 @@ export class Renderer {
                     }
                 }
             }
+            // Draw point clouds (IFCx inline + streamed LAS/LAZ).
+            // Shares the depth buffer + section plane state with the mesh pipeline so
+            // points occlude triangles and vice versa. The splat shader needs the
+            // viewport size to convert pixel sizes into clip-space offsets.
+            if (this.pointCloudRenderer && this.pointCloudRenderer.hasAssets()) {
+                this.pointCloudRenderer.draw(pass, {
+                    viewProj,
+                    sectionPlane: sectionPlaneData
+                        ? { ...sectionPlaneData, flipped: options.sectionPlane?.flipped === true }
+                        : null,
+                    viewport: { width: this.canvas.width, height: this.canvas.height },
+                });
+            }
             // Draw section plane visual BEFORE pass.end() (within same MSAA render pass)
             // Always show plane when sectionPlane options are provided (as preview or active)
             const modelBounds = this.getModelBounds();
@@ -1320,6 +1811,11 @@ export class Renderer {
                     isPreview: !options.sectionPlane.enabled, // Preview mode when not enabled
                     min: options.sectionPlane.min,
                     max: options.sectionPlane.max,
+                    // Custom-plane gizmo override (issue #243). When both
+                    // are set the gizmo bypasses the cardinal path; see
+                    // SectionPlaneRenderer.calculatePlaneVerticesFromNormal.
+                    normal: options.sectionPlane.normal,
+                    distance: options.sectionPlane.distance,
                 });
                 // Draw 2D section overlay on the section plane (when section is
                 // active, not preview). The overlay is also the 3D SECTION CAP:
@@ -1380,9 +1876,37 @@ export class Renderer {
                     enableSeparationLines: separationEnabled,
                 });
             }
+            // Eye-Dome Lighting — runs AFTER contact/separation so it darkens
+            // every layer uniformly. Cheap (~9 depth taps), only active when
+            // there are point clouds in the scene and the user has enabled it.
+            if (this.edlPass
+                && this.edlOptions.enabled
+                && this.pointCloudRenderer?.hasAssets()) {
+                this.edlPass.apply(encoder, {
+                    targetView: textureView,
+                    depthView: this.pipeline.getDepthOnlyTextureView(),
+                }, {
+                    strength: this.edlOptions.strength,
+                    radiusPx: this.edlOptions.radiusPx,
+                    highQuality: this.edlOptions.highQuality,
+                });
+            }
             device.queue.submit([encoder.finish()]);
+            // Pop validation error scope and capture the exact error
+            if (captureGpuError) {
+                device.popErrorScope().then((error) => {
+                    if (error) {
+                        const msg = error.message || String(error);
+                        console.error('[WebGPU] Validation error in render pass:', msg);
+                        this.device._lastUncapturedError = `VALIDATION: ${msg}`;
+                        this.device._uncapturedErrorCount++;
+                    }
+                });
+            }
         }
         catch (error) {
+            this._renderErrorCount++;
+            this._lastRenderError = error instanceof Error ? error.message : String(error);
             // Handle WebGPU errors (e.g., device lost, invalid state)
             // Mark context as invalid so it gets reconfigured next frame
             this.device.invalidateContext();
@@ -1405,6 +1929,18 @@ export class Renderer {
     async pick(x, y, options) {
         return this.pickingManager.pick(x, y, options);
     }
+    /**
+     * GPU-based rectangle pick. Drag-select returns the set of
+     * `expressId`s touched by any pixel inside `[x0,y0]..[x1,y1]`
+     * (CSS pixels, canvas-relative). Both meshes and point clouds
+     * participate.
+     *
+     * See `PickingManager.pickRect` for the visibility-filter +
+     * limitation notes.
+     */
+    async pickRect(x0, y0, x1, y1, options) {
+        return this.pickingManager.pickRect(x0, y0, x1, y1, options);
+    }
     /**
      * Raycast into the scene to get precise 3D intersection point
      * This is more accurate than pick() as it returns the exact surface point
@@ -1495,15 +2031,34 @@ export class Renderer {
         return this.scene;
     }
     /**
-     * Upload 2D section drawing data for 3D overlay rendering
-     * Call this when a 2D drawing is generated to display it on the section plane
-     * Uses same position calculation as section plane: sectionRange min/max if provided, else modelBounds
+     * Upload 2D section drawing data for 3D overlay rendering.
+     *
+     * Cardinal-axis call site: pass `axis` + `position` percentage and the
+     * upload computes the plane offset along the cardinal axis using the
+     * model bounds (or `sectionRange` override). 2D points are then lifted
+     * to 3D via the cardinal-axis swap.
+     *
+     * Custom-plane call site (issue #243): pass `customPlane = { origin,
+     * tangent, bitangent }`. The 2D points are lifted via the explicit
+     * basis, exactly inverting the projection `SectionCutter` applied when
+     * generating the polygons. Without this the cap silhouette lands off
+     * the actual cutting plane (the bug PR #581 hid by suppressing the
+     * cap entirely for non-cardinal planes).
      */
     uploadSection2DOverlay(polygons, lines, axis, position, // 0-100 percentage
     sectionRange, // Same storey-based range as section plane
-    flipped = false) {
+    flipped = false, customPlane) {
         if (!this.section2DOverlayRenderer)
             return;
+        if (customPlane) {
+            // Custom-plane path: planePosition / axis are unused — the
+            // basis the cap shader needs travels in `customPlane`. We pass
+            // 0 for `planePosition` and the existing `axis` so the cardinal
+            // shader code path that callers depend on (e.g. legacy SVG
+            // export) keeps working when customPlane is omitted.
+            this.section2DOverlayRenderer.uploadDrawing(polygons, lines, axis, 0, flipped, customPlane);
+            return;
+        }
         // Use EXACTLY same calculation as section plane in render() method:
         // minVal = options.sectionPlane.min ?? boundsMin[axisIdx]
         // maxVal = options.sectionPlane.max ?? boundsMax[axisIdx]
@@ -1601,11 +2156,22 @@ export class Renderer {
         // Post-processor uniform buffer
         this.postProcessor?.destroy();
         this.postProcessor = null;
+        this.edlPass?.destroy();
+        this.edlPass = null;
         // Section-plane renderers
         this.sectionPlaneRenderer?.destroy();
         this.sectionPlaneRenderer = null;
         this.section2DOverlayRenderer?.dispose();
         this.section2DOverlayRenderer = null;
+        // Point cloud GPU resources
+        this.pointCloudRenderer?.clear();
+        this.pointCloudRenderer = null;
+        // BIM ↔ scan deviation pipeline + cached BVH GPU buffers.
+        // Done before queue.destroy() so the GPU calls inside
+        // `destroy()` still have a valid device.
+        this.deviationPipeline?.destroy();
+        this.deviationPipeline = null;
+        this.deviationBvhFingerprint = null;
         // Snap detector geometry cache
         this.raycastEngine.clearCaches();
     }