@ifc-lite/renderer 3.0.1 → 3.2.0

package/dist/scene.js

@@ -4,29 +4,34 @@
 import { materializeInstances } from './scene-instance-materialization.js';
 import { InstanceSuppression } from './scene-instance-suppression.js';
 import { createSceneBatch } from './scene-batch-upload.js';
-import { createSceneAppearancePreview } from './scene-appearance-preview.js';
+import { createSceneAppearancePreview, rebindSceneAppearanceAccess } from './scene-appearance-preview.js';
 import { AppearanceBuckets } from './scene-appearance-buckets.js';
-import { prepareSceneAuthoredOwner } from './scene-authored-owner.js';
+import { AuthoredPreparationRegistry, prepareSceneAuthoredOwner } from './scene-authored-owner.js';
 import { interleaveTexturedVertices } from './textured-vertices.js';
 import { RgbaTexturePool } from './rgba-texture-pool.js';
 import { splitMeshForStreaming } from './scene-stream-split.js';
+import { hostsOtherEntities } from './mesh-entity-hosting.js';
 import { BATCH_CONSTANTS } from './constants.js';
 import { prepareRayDirInv, raycastBoundingBoxes, raycastTriangles, rayIntersectsBox, } from './scene-raycaster.js';
 import { selectBoundingBoxesInRect } from './scene-rect-select.js';
-import { splitMeshDataForBufferLimit, cachedWorldAabb, worldAabbFromPieces, destroyGpuResources } from './scene-geometry.js';
+import { splitMeshDataForBufferLimit, cachedWorldAabb, worldAabbFromPieces, destroyGpuResources, topologySafeBatchOrigin } from './scene-geometry.js';
+import { resolvePrecisionBucket } from './scene-bucket-routing.js';
 import { sumResidentGpuBytes } from './render-stats.js';
-import { composeInstancedOverrideColor } from './instanced-override-color.js';
+import { composeInstancedOverrideColor, writeOriginalInstancedColors } from './instanced-override-color.js';
 import { bucketBaseKeyFor } from './chunk-grid.js';
+import { inheritedQuantization, groupOverridePieces, cloneOverrides, overlaysInvalidatedBy } from './scene-derived-batches.js';
 import { VisibilityEpochTracker } from './visibility-epoch.js';
 import { isEntityVisible } from './entity-visibility.js';
 import { planInstancedGhosting } from './instanced-ghost-plan.js';
 import { selectEvictions } from './residency.js';
 import { OPAQUE_ALPHA_CUTOFF } from './overlay-routing.js';
-import { translateSceneModel, releaseInstanceVertices, refreshTexturedBounds } from './scene-model-translation.js';
+import { translateSceneModel, rotateSceneModelInstances, releaseInstanceVertices, refreshTexturedBounds } from './scene-model-translation.js';
 import { ModelTranslations } from './model-translation.js';
-import { extractEntityFromMergedMesh } from './merged-mesh-extract.js';
+import { DerivedMeshProvenance } from './scene-derived-mesh-provenance.js';
+import { rebuildSceneBatches } from './scene-batch-rebuild.js';
 import { dropAllPartialCaches as dropAllPartialCachesIn, dropPartialCacheForBatch as dropPartialCacheForBatchIn, retireUnusedAlphaSlots as retireUnusedAlphaSlotsIn, } from './partial-batch-cache.js';
 import { prepareInstancedRender, foldOccurrenceWorldBox, INSTANCE_STRIDE_BYTES, INSTANCE_COLOR_OFFSET, INSTANCE_FLAGS_OFFSET, INSTANCE_FLAG_SELECTED, INSTANCE_FLAG_HIDDEN, } from './instanced-render.js';
+import { discardSceneGpuResourcesForRecovery, prepareSceneDeviceRecovery, repartitionHydratedRecoveryBucket, restoreSceneGpuResourcesAfterRecovery } from './scene-device-recovery.js';
 const EMPTY_INSTANCED_TEMPLATES = [];
 /**
  * Pure helper: compute the exclusive end index of the next flushPending()
@@ -82,6 +87,7 @@ export class Scene {
     batchedMeshes = []; // flat render array (rebuilt from buckets)
     buckets = new Map(); // bucketKey -> consolidated bucket state
     meshDataBucket = new Map(); // reverse lookup: MeshData -> owning bucket
+    derivedMeshProvenance = new DerivedMeshProvenance();
     modelTranslations = new ModelTranslations();
     meshDataMap = new Map(); // Map expressId -> MeshData[] (for lazy buffer creation, accumulates multiple pieces)
     boundingBoxes = new Map(); // Map expressId -> bounding box (computed lazily)
@@ -93,7 +99,9 @@ export class Scene {
     rgbaTexturePool = new RgbaTexturePool();
     appearanceController;
     appearanceBuckets;
+    appearanceAccessState;
     authoredGeneration = 0;
+    authoredPreparations = new AuthoredPreparationRegistry();
     appearanceAccess(device, pipeline) {
         return {
             meshes: () => this.texturedMeshes, data: this.meshDataMap,
@@ -133,24 +141,23 @@ export class Scene {
             },
         };
     }
+    bindAppearanceAccess(device, pipeline) { return this.appearanceAccessState = rebindSceneAppearanceAccess(this.appearanceAccessState, this.appearanceAccess(device, pipeline)); }
     sharedAppearanceBuckets(access) {
         return this.appearanceBuckets ??= new AppearanceBuckets(access.buckets, id => this.meshDataMap.get(id));
     }
     appearancePreview(device, pipeline) {
-        const access = this.appearanceAccess(device, pipeline);
+        const access = this.bindAppearanceAccess(device, pipeline);
         return this.appearanceController ??= createSceneAppearancePreview(access, this.sharedAppearanceBuckets(access));
     }
-    /** Place canonical native appearance source geometry in this model's live frame. */
     placeAppearanceSource(mesh) { return this.modelTranslations.placeMesh(mesh); }
-    /** Retain model-local source coordinates when publishing a placed appearance mesh. */
     appearanceSourceMesh(mesh) { return this.modelTranslations.sourceFromPlaced(mesh); }
     /** Stage one new IFC owner with all its coloured or textured geometry parts. */
     prepareAuthoredOwner(parts, device, pipeline) {
-        const access = this.appearanceAccess(device, pipeline), generation = this.authoredGeneration;
-        return prepareSceneAuthoredOwner(access, this.sharedAppearanceBuckets(access), parts, () => {
+        const access = this.bindAppearanceAccess(device, pipeline), generation = this.authoredGeneration;
+        return this.authoredPreparations.track(prepareSceneAuthoredOwner(access, this.sharedAppearanceBuckets(access), parts, () => {
             if (generation !== this.authoredGeneration)
                 throw new Error('The scene changed while preparing the object.');
-        });
+        }));
     }
     /** Compatibility entry point for an image-backed single-part owner. */
     prepareTexturedOwner(mesh, device, pipeline) {
@@ -279,6 +286,7 @@ export class Scene {
     // Overlay batches render on top using depthCompare 'equal', so they only
     // paint where original geometry already wrote depth. Clearing is instant.
     overrideBatches = [];
+    overlaySources = new Map(); // overridden piece -> bucket key its overlay inherited from (#4832)
     // Defensively-typed: the renderer is the sole writer (via setColorOverrides),
     // external readers go through getColorOverrides() and get a ReadonlyMap.
     colorOverrides = null;
@@ -298,12 +306,11 @@ export class Scene {
     // the queue via flushPending() with a per-frame time budget.
     meshQueue = [];
     meshQueueReadIndex = 0;
-    // ─── GPU-resident mode ──────────────────────────────────────────────
-    // After releaseGeometryData(), JS-side typed arrays are freed.
-    // Only lightweight metadata is retained for operations that don't need
-    // raw vertex data (bounding boxes, color key lookups, expressId sets).
     geometryReleased = false;
     ephemeralStreamingMode = false;
+    prepareDeviceRecovery() { return prepareSceneDeviceRecovery(this); }
+    discardGpuResourcesForRecovery() { discardSceneGpuResourcesForRecovery(this); }
+    restoreGpuResourcesAfterRecovery(device, pipeline) { restoreSceneGpuResourcesAfterRecovery(this, device, pipeline); }
     /**
      * Add mesh to scene
      */
@@ -326,8 +333,10 @@ export class Scene {
     /** The shared local-frame origin all batches relativize against (null until
      *  the first batch is built). Per-mesh highlight/picker VBOs replicate the
      *  batch's exact f32 path against this so they render bit-coincident. */
-    getSharedFrameOrigin(modelIndex = 0) {
-        return this.modelTranslations.frameOrigin(this.sharedFrameOrigins.get(modelIndex) ?? null, modelIndex) ?? null;
+    getSharedFrameOrigin(modelIndex = 0, meshData) {
+        const placed = meshData ? this.derivedMeshProvenance.placedSourceFor(meshData, this.modelTranslations) : undefined;
+        const bucket = placed ? this.meshDataBucket.get(placed) : undefined;
+        return bucket?.batchedMesh?.origin ?? bucket?.frameOrigin ?? this.modelTranslations.frameOrigin(this.sharedFrameOrigins.get(modelIndex) ?? null, modelIndex) ?? null;
     }
     /**
      * Enable/disable spatial chunk bucketing (issue #1682 phase 2). When set,
@@ -425,6 +434,7 @@ export class Scene {
             }
             const rebuilt = this.createBatchedMesh(bucket.meshData, bucket.meshData[0].color, device, pipeline, key);
             bucket.batchedMesh = rebuilt;
+            bucket.frameOrigin = rebuilt.origin;
             const idx = this.batchedMeshes.indexOf(old);
             if (idx >= 0)
                 this.batchedMeshes[idx] = rebuilt;
@@ -458,28 +468,21 @@ export class Scene {
      * Enable 12-byte lattice-quantized batch vertices (issue #1682 phase 6).
      * ONLY call after the renderer verified its quantized pipeline variants
      * exist (see Renderer.enableQuantizedBatches) — quantized buffers are
-     * undrawable without them. Applies to batches built from now on; every
-     * createBatchedMesh output (buckets, fragments, partial + override
-     * batches) quantizes onto the SAME 2^-10 lattice, so depth-equal overlay
-     * matching and cross-batch coincidence are preserved bit-exactly. Batches
-     * whose extent exceeds the u16 lattice range fall back to f32 silently.
+     * undrawable without them. Applies to batches built from now on: bucket
+     * batches and fragments quantize onto the SAME 2^-10 lattice when their
+     * extent fits the u16 range (else f32); partial + override batches INHERIT
+     * their source batch's decision (#4832, `scene-derived-batches.ts`), so
+     * depth-equal overlay matching and cross-batch coincidence stay bit-exact.
      */
     setQuantizedBatches(enabled) {
         this.quantizedBatchesEnabled = enabled;
     }
-    /**
-     * Whether THIS mesh's source batch renders quantized — drives the
-     * hydrated-mesh lattice snap in createMeshFromData (a mesh whose batch
-     * fell back to f32, e.g. >64m extent, must NOT snap). Falls back to the
-     * global flag when the mesh isn't bucketed (mid-stream hydration).
-     */
+    /** Whether THIS mesh's source batch renders quantized — drives the hydrated-mesh
+     *  lattice snap in createMeshFromData (an f32 batch must NOT snap). Same rule
+     *  as overlay/partial batches; global flag while unbucketed. */
     isMeshQuantized(meshData) {
-        if (!this.quantizedBatchesEnabled)
-            return false;
-        const bucket = this.meshDataBucket.get(meshData);
-        if (bucket?.batchedMesh)
-            return bucket.batchedMesh.quantized !== undefined;
-        return true;
+        const source = this.derivedMeshProvenance.placedSourceFor(meshData, this.modelTranslations);
+        return inheritedQuantization(this.quantizedBatchesEnabled, this.meshDataBucket.get(source)?.batchedMesh) !== 'off';
     }
     /** Set (or clear) the HOST budget in bytes for bucket CPU geometry. */
     setHostResidencyBudget(bytes) {
@@ -634,10 +637,10 @@ export class Scene {
                 this.meshDataBucket.set(m, bucket);
                 this.addMeshData(m);
             }
-            this.coldBuckets.delete(key);
             if (members.length > 0) {
-                // Warm now — re-queue so the next restore tick rebuilds the GPU batch.
-                this.residencyRestoreQueue.add(key);
+                this.coldBuckets.delete(key);
+                for (const restoredKey of repartitionHydratedRecoveryBucket(this, key, bucket, shell))
+                    this.residencyRestoreQueue.add(restoredKey);
             }
             else {
                 console.warn(`[Scene] cold restore for ${key} found no members — bucket stays a shell`);
@@ -669,6 +672,7 @@ export class Scene {
                 continue;
             const rebuilt = this.createBatchedMesh(bucket.meshData, bucket.meshData[0].color, device, pipeline, bucket.key);
             bucket.batchedMesh = rebuilt;
+            bucket.frameOrigin = rebuilt.origin;
             const idx = this.batchedMeshes.indexOf(old);
             if (idx >= 0)
                 this.batchedMeshes[idx] = rebuilt;
@@ -868,7 +872,7 @@ export class Scene {
             // this expressId so selection highlighting is per-entity, not the
             // entire merged batch.
             if (single.entityIds) {
-                return extractEntityFromMergedMesh(single, expressId);
+                return this.derivedMeshProvenance.extract(single, expressId);
             }
             return single;
         }
@@ -878,7 +882,7 @@ export class Scene {
             const extracted = [];
             for (const piece of pieces) {
                 if (piece.entityIds) {
-                    const ex = extractEntityFromMergedMesh(piece, expressId);
+                    const ex = this.derivedMeshProvenance.extract(piece, expressId);
                     if (ex)
                         extracted.push(ex);
                 }
@@ -893,6 +897,18 @@ export class Scene {
             pieces = extracted;
             // Fall through to the normal multi-piece merge below
         }
+        // A cross-bucket singular result keeps the historical representative merge
+        // (all triangles, no provenance); precise callers use the pieces accessor.
+        const firstOrigin = pieces[0].origin;
+        const firstSource = this.derivedMeshProvenance.placedSourceFor(pieces[0], this.modelTranslations);
+        const firstBucket = this.meshDataBucket.get(firstSource);
+        const sameBucket = pieces.every(piece => this.meshDataBucket.get(this.derivedMeshProvenance.placedSourceFor(piece, this.modelTranslations)) === firstBucket);
+        const sameFrame = pieces.every(piece => piece.origin?.[0] === firstOrigin?.[0]
+            && piece.origin?.[1] === firstOrigin?.[1] && piece.origin?.[2] === firstOrigin?.[2]);
+        const precisionPlaceable = sameBucket || (!firstBucket && sameFrame);
+        const mergedOrigin = precisionPlaceable
+            ? firstBucket?.batchedMesh?.origin ?? firstBucket?.frameOrigin ?? firstOrigin ?? [0, 0, 0]
+            : undefined;
         // Check if all pieces have the same color (within tolerance)
         // This handles multi-material elements like windows (frame vs glass)
         const firstColor = pieces[0].color;
@@ -926,8 +942,17 @@ export class Scene {
         let idxOffset = 0;
         let vertexOffset = 0;
         for (const piece of pieces) {
-            // Copy positions and normals
-            mergedPositions.set(piece.positions, posOffset);
+            if (mergedOrigin) {
+                const ox = (piece.origin?.[0] ?? 0) - mergedOrigin[0], oy = (piece.origin?.[1] ?? 0) - mergedOrigin[1], oz = (piece.origin?.[2] ?? 0) - mergedOrigin[2];
+                for (let i = 0; i < piece.positions.length; i += 3) {
+                    mergedPositions[posOffset + i] = piece.positions[i] + ox;
+                    mergedPositions[posOffset + i + 1] = piece.positions[i + 1] + oy;
+                    mergedPositions[posOffset + i + 2] = piece.positions[i + 2] + oz;
+                }
+            }
+            else {
+                mergedPositions.set(piece.positions, posOffset);
+            }
             mergedNormals.set(piece.normals, posOffset);
             // Copy indices with offset
             for (let i = 0; i < piece.indices.length; i++) {
@@ -938,7 +963,7 @@ export class Scene {
             vertexOffset += piece.positions.length / 3;
         }
         // Return merged MeshData (all pieces have same color)
-        return {
+        const merged = {
             expressId,
             modelIndex: pieces[0].modelIndex, // Preserve modelIndex for multi-model support
             positions: mergedPositions,
@@ -946,7 +971,15 @@ export class Scene {
             indices: mergedIndices,
             color: firstColor,
             ifcType: pieces[0].ifcType,
+            ...(mergedOrigin ? { origin: mergedOrigin } : {}),
         };
+        // The common frame is explicit above.  Keep a source only when every part
+        // belongs to the same live bucket; an arbitrary source would give a merged
+        // result the wrong quantization/frame after a re-batch.
+        if (firstBucket && precisionPlaceable) {
+            this.derivedMeshProvenance.remember(merged, firstSource);
+        }
+        return merged;
     }
     /**
      * Check if MeshData exists for an expressId
@@ -1018,7 +1051,7 @@ export class Scene {
             const extracted = [];
             for (const piece of pieces) {
                 if (piece.entityIds) {
-                    const ex = extractEntityFromMergedMesh(piece, expressId);
+                    const ex = this.derivedMeshProvenance.extract(piece, expressId);
                     if (ex)
                         extracted.push(ex);
                 }
@@ -1054,10 +1087,20 @@ export class Scene {
      * when streaming completes to do one O(N) full merge.
      */
     appendToBatches(meshDataArray, device, pipeline, isStreaming = false) {
+        meshDataArray = meshDataArray.map((mesh) => this.modelTranslations.placeMesh(mesh));
+        // Validate every input before cancelling appearance work, publishing a
+        // bucket, or touching GPU state. A single impossible f32 frame must leave
+        // an already-valid scene usable and allow the next safe append.
+        for (const meshData of meshDataArray) {
+            const modelIndex = meshData.modelIndex ?? 0;
+            const shared = this.modelTranslations.frameOrigin(this.sharedFrameOrigins.get(modelIndex) ?? null, modelIndex);
+            if (!topologySafeBatchOrigin([meshData], undefined, shared)) {
+                throw new Error('Unable to resolve a topology-safe GPU frame for mesh geometry.');
+            }
+        }
         if (this.appearanceController)
             for (const part of meshDataArray)
                 this.appearanceController.cancelFor(part.expressId);
-        meshDataArray = meshDataArray.map((mesh) => this.modelTranslations.placeMesh(mesh));
         // Cache max buffer size on first call
         if (this.cachedMaxBufferSize === 0) {
             this.cachedMaxBufferSize = this.getMaxBufferSize(device);
@@ -1086,6 +1129,9 @@ export class Scene {
         for (const meshData of renderable) {
             const baseKey = this.bucketBaseKey(meshData);
             const bucketKey = this.resolveActiveBucket(baseKey, meshData);
+            const resolvedBucket = this.buckets.get(bucketKey);
+            if (resolvedBucket)
+                this.meshDataBucket.set(meshData, resolvedBucket);
             if (retainStreamingGeometry || !isStreaming) {
                 // Accumulate mesh data in the bucket when we need later rebatching or
                 // CPU-side lookups. Huge-file mode intentionally skips this to keep JS
@@ -1117,46 +1163,20 @@ export class Scene {
         // NON-STREAMING: Rebuild full batches immediately
         this.rebuildPendingBatches(device, pipeline);
     }
-    /**
-     * Rebuild all pending batches (call this after streaming completes)
-     *
-     * Each bucket key already maps to data that fits within the GPU buffer
-     * limit (enforced at accumulation time by resolveActiveBucket), so no
-     * splitting is needed here — just create one batch per key.
-     */
+    /** Rebuild pending buckets after streaming or a geometry mutation. */
     rebuildPendingBatches(device, pipeline) {
         if (this.pendingBatchKeys.size === 0)
             return;
-        for (const key of this.pendingBatchKeys) {
-            const bucket = this.buckets.get(key);
-            // Destroy old GPU batch if it exists
-            if (bucket?.batchedMesh) {
-                // Slot keys embed the batch id and the replacement gets a fresh one, so
-                // drop this batch's cached sub-batch clones first or they are stranded
-                // with live GPU buffers. Every other batch-destroying path already
-                // clears the cache (eviction per batch; finalize/release/clear wholesale).
-                this.dropPartialCacheForBatch(bucket.batchedMesh);
-                destroyGpuResources(bucket.batchedMesh);
-                bucket.batchedMesh = null;
-            }
-            if (!bucket || bucket.meshData.length === 0) {
-                // Bucket is empty — clean up
-                this.buckets.delete(key);
-                continue;
-            }
-            // Create new batch with all accumulated meshes for this bucket
-            const color = bucket.meshData[0].color;
-            const batchedMesh = this.createBatchedMesh(bucket.meshData, color, device, pipeline, key);
-            bucket.batchedMesh = batchedMesh;
-        }
-        // Rebuild the flat render array from all buckets (148 max batches — not perf critical)
-        this.batchedMeshes = [];
-        for (const bucket of this.buckets.values()) {
-            if (bucket.batchedMesh) {
-                this.batchedMeshes.push(bucket.batchedMesh);
-            }
-        }
+        const rebuilt = rebuildSceneBatches({ pendingKeys: this.pendingBatchKeys, buckets: this.buckets,
+            create: (meshes, color, target, renderPipeline, key) => this.createBatchedMesh(meshes, color, target, renderPipeline, key),
+            dropPartial: batch => this.dropPartialCacheForBatch(batch),
+        }, device, pipeline);
+        this.batchedMeshes = [...this.buckets.values()].flatMap(bucket => bucket.batchedMesh ? [bucket.batchedMesh] : []);
         this.pendingBatchKeys.clear();
+        // Overlays follow their depth writers only when one actually changed under
+        // them (flip / bucket move, #4832); finalize re-applies once itself.
+        if (!this.finalizeInProgress && overlaysInvalidatedBy(rebuilt, this.overlaySources))
+            this.reapplyColorOverrides(device, pipeline);
     }
     /**
      * Check if there are pending batch rebuilds
@@ -1177,8 +1197,8 @@ export class Scene {
      * raycast bounds. This is the proper removal path.
      *
      * Notes:
-     *   - For color-merged meshes (the `entityIds` per-vertex case)
-     *     a single MeshData often hosts many entities. We do NOT
+     *   - For color-merged meshes (`entityIds` naming other entities,
+     *     `hostsOtherEntities`) a single MeshData hosts many entities. We do NOT
      *     drop the whole mesh in that case — that would also remove
      *     the other entities — but we DO clear the bbox + meshDataMap
      *     for the requested expressId, so picking and selection stop
@@ -1207,10 +1227,9 @@ export class Scene {
         // caller's bulk-count contract.
         let removedDedicated = false;
         for (const meshData of meshDataList) {
-            // Color-merged path: shared mesh, keep it but drop our entry.
-            if (meshData.entityIds && meshData.entityIds.length > 0) {
+            // Color-merged path (entityIds naming OTHER entities): keep the shared mesh, drop our entry.
+            if (hostsOtherEntities(meshData))
                 continue;
-            }
             removedDedicated = true;
             // Dedicated mesh — drop from its bucket and decrement the
             // bucket's vertexBytes counter so subsequent
@@ -1558,21 +1577,40 @@ export class Scene {
         }
         this.meshes = kept;
     }
-    /** Absolute workspace translation, renderer Y-up metres (#4226). */
-    getModelTranslation(modelIndex) { return this.modelTranslations.get(modelIndex); }
-    setModelTranslation(modelIndex, translation) {
+    /** Shared `TranslationScene` view for `setModelTranslation`/`setModelRotation`
+     *  (#4890) — the placement helpers in scene-model-translation.ts read scene
+     *  state through this narrow interface instead of the full `Scene`. */
+    translationScope() {
         const batches = this.finalizeInProgress ? [...new Set([...this.batchedMeshes,
                 ...[...this.buckets.values()].flatMap((bucket) => bucket.batchedMesh ? [bucket.batchedMesh] : [])])] : this.batchedMeshes;
-        const changed = translateSceneModel({ translations: this.modelTranslations, pieces: this.meshDataMap,
+        return { translations: this.modelTranslations, pieces: this.meshDataMap,
             bounds: this.boundingBoxes, batches, meshes: this.meshes, overrides: this.overrideBatches, textured: this.texturedMeshes,
             templates: this.instancedTemplates, cpu: this.instancedTemplateCpu, occurrences: this.instancedEntityMap,
             device: this.instancedDevice, evictHighlight: (id) => this.evictHighlightMeshes(id, true),
             clearPartial: () => this.dropAllPartialCaches(),
-            unionBounds: (id, view, offset, min, max) => this.unionInstancedWorldAabb(id, view, offset, ...min, ...max),
-        }, modelIndex, translation);
+            unionBounds: (id, view, offset, min, max) => this.unionInstancedWorldAabb(id, view, offset, ...min, ...max) };
+    }
+    dropOrphanedSuppressedBounds() {
         for (const id of this.instanceSuppression.suppressedIds())
             if (!this.meshDataMap.has(id))
                 this.boundingBoxes.delete(id);
+    }
+    /** Absolute workspace translation, renderer Y-up metres (#4226). */
+    getModelTranslation(modelIndex) { return this.modelTranslations.get(modelIndex); }
+    setModelTranslation(modelIndex, translation) {
+        const changed = translateSceneModel(this.translationScope(), modelIndex, translation);
+        this.dropOrphanedSuppressedBounds();
+        return changed;
+    }
+    /** Absolute workspace yaw, renderer Y-up radians about the render-frame
+     *  pivot `(pivot[0], *, pivot[2])` — the GPU-instanced half of a whole-model
+     *  rotation (#4890); `angle === 0` clears it. Flat/authored/batched geometry
+     *  is rotated by the viewer's bake, not here. */
+    getModelRotation(modelIndex) { return this.modelTranslations.getYaw(modelIndex); }
+    setModelRotation(modelIndex, angle, pivot) {
+        const yaw = angle === 0 ? null : { angle, px: pivot[0], pz: pivot[2] };
+        const changed = rotateSceneModelInstances(this.translationScope(), modelIndex, yaw);
+        this.dropOrphanedSuppressedBounds();
         return changed;
     }
     /** Bulk variant of `translateMeshesForEntity`. */
@@ -1800,7 +1838,7 @@ export class Scene {
         // applies to cells exactly like it does to buckets.
         const colorGroups = new Map();
         for (const meshData of meshDataArray) {
-            const key = this.bucketBaseKey(meshData);
+            const key = this.meshDataBucket.get(meshData)?.key ?? this.bucketBaseKey(meshData);
             for (const fragment of this.splitMeshForStreaming(meshData)) {
                 let group = colorGroups.get(key);
                 if (!group) {
@@ -1811,11 +1849,11 @@ export class Scene {
             }
         }
         // Create one fragment batch per color group (with buffer limit splitting)
-        for (const [, group] of colorGroups) {
+        for (const [key, group] of colorGroups) {
             const chunks = this.splitMeshDataForBufferLimit(group, this.cachedMaxBufferSize);
             for (const chunk of chunks) {
                 const color = chunk[0].color;
-                const fragment = this.createBatchedMesh(chunk, color, device, pipeline);
+                const fragment = this.createBatchedMesh(chunk, color, device, pipeline, undefined, undefined, this.buckets.get(key)?.frameOrigin);
                 this.batchedMeshes.push(fragment);
                 this.streamingFragments.push(fragment);
             }
@@ -1943,6 +1981,7 @@ export class Scene {
             if (!fragmentSet.has(batch))
                 destroyGpuResources(batch);
         }
+        this.reapplyColorOverrides(device, pipeline);
     }
     /**
      * Time-sliced version of finalizeStreaming.
@@ -1985,15 +2024,6 @@ export class Scene {
         // always clear finalizeInProgress.
         return new Promise((resolve, reject) => {
             const newBatches = [];
-            // Every batch this attempt creates, paired with the bucket that now owns
-            // it and the value it displaced. `newBatches` alone is not enough to roll
-            // back: processChunk publishes each batch into `bucket.batchedMesh`, so
-            // freeing it without repairing the owner leaves the bucket map pointing
-            // at destroyed GPU resources (use-after-free on the next bucket-driven
-            // access). `previous` is null for the freshly built buckets and, for a
-            // carried COLD bucket a re-grouped meshData landed in, the shell that the
-            // restored `batchedMeshes` still holds — which must be put back, not
-            // nulled.
             const createdOwned = [];
             let carriedCold = [];
             let pendingKeys = [];
@@ -2004,11 +2034,14 @@ export class Scene {
                 // are what the restored arrays point back at). Iterating the owned
                 // pairs rather than `newBatches` also skips the carried cold shells
                 // appended just before the swap, which this attempt did not create.
-                for (const { bucket, previous, batch } of createdOwned) {
+                for (const { bucket, previous, previousFrameOrigin, batch } of createdOwned) {
                     // Repair the owner BEFORE the free, so no bucket is ever observable
-                    // holding a destroyed batch.
-                    if (bucket.batchedMesh === batch)
+                    // holding a destroyed batch; its frame origin (what a later
+                    // createBatchedMesh seeds from) must describe the restored batch.
+                    if (bucket.batchedMesh === batch) {
                         bucket.batchedMesh = previous;
+                        bucket.frameOrigin = previousFrameOrigin;
+                    }
                     if (!oldBatchSet.has(batch) && !fragmentSet.has(batch)) {
                         destroyGpuResources(batch);
                     }
@@ -2029,9 +2062,11 @@ export class Scene {
                         }
                         const color = bucket.meshData[0].color;
                         const previous = bucket.batchedMesh;
+                        const previousFrameOrigin = bucket.frameOrigin;
                         const batchedMesh = scene.createBatchedMesh(bucket.meshData, color, device, pipeline, key);
                         bucket.batchedMesh = batchedMesh;
-                        createdOwned.push({ bucket, previous, batch: batchedMesh });
+                        bucket.frameOrigin = batchedMesh.origin;
+                        createdOwned.push({ bucket, previous, previousFrameOrigin, batch: batchedMesh });
                         newBatches.push(batchedMesh);
                         // Check time budget — yield if exceeded
                         if (performance.now() - chunkStart >= budgetMs) {
@@ -2062,6 +2097,7 @@ export class Scene {
                             destroyGpuResources(batch);
                     }
                     scene.finalizeInProgress = false;
+                    scene.reapplyColorOverrides(device, pipeline); // never throws: the swap above is committed
                     resolve();
                 }
                 catch (err) {
@@ -2169,7 +2205,6 @@ export class Scene {
      * Call this after finalizeStreaming() when all color updates have been applied.
      */
     releaseGeometryData() {
-        this.authoredGeneration++;
         if (this.geometryReleased)
             return;
         if (this.instanceSuppression.retained) {
@@ -2183,6 +2218,8 @@ export class Scene {
                 `Call finalizeStreaming()/rebuildPendingBatches() first.`);
             return;
         }
+        this.authoredGeneration++;
+        this.authoredPreparations.invalidate();
         this.appearanceController?.forget();
         // 1. Precompute and cache ALL entity bounding boxes before releasing data.
         // Same rule as `finishEphemeralStreaming`: an entity with no usable vertex
@@ -2323,16 +2360,20 @@ export class Scene {
      * @param bucketKey - Optional unique key for this batch. When omitted the
      *   base color key is used (fine for overlay / partial batches that don't
      *   participate in the main buckets map).
+     * @param quantization - 'auto' for bucket batches; derived batches pass `inheritedQuantization(source)` (#4832).
      */
-    createBatchedMesh(meshes, color, device, pipeline, bucketKey) {
+    createBatchedMesh(meshes, color, device, pipeline, bucketKey, quantization = this.quantizedBatchesEnabled ? 'auto' : 'off', frameOrigin) {
         // Keep main's model-local frame and translation registration while staging
         // every GPU allocation before publishing Scene state.
         const modelIndex = meshes[0]?.modelIndex ?? 0;
         const offset = this.modelTranslations.get(modelIndex);
+        const origin = topologySafeBatchOrigin(meshes, frameOrigin ?? this.meshDataBucket.get(meshes[0])?.batchedMesh?.origin, this.modelTranslations.frameOrigin(this.sharedFrameOrigins.get(modelIndex) ?? null, modelIndex), this.meshDataBucket.get(meshes[0])?.frameOrigin);
+        if (!origin)
+            throw new Error('Unable to resolve a topology-safe GPU frame for mesh geometry.');
         const result = createSceneBatch(meshes, color, device, pipeline, {
             id: this.nextBatchId, colorKey: bucketKey ?? this.colorKey(color),
-            origin: this.modelTranslations.frameOrigin(this.sharedFrameOrigins.get(modelIndex) ?? null, modelIndex),
-            quantized: this.quantizedBatchesEnabled, lod: this.lodBuildsEnabled,
+            origin,
+            quantized: quantization, lod: this.lodBuildsEnabled,
         }, bucketKey);
         this.nextBatchId++;
         if (!this.sharedFrameOrigins.has(modelIndex) && result.origin) {
@@ -2361,38 +2402,15 @@ export class Scene {
      * Returns the bucket key to use (may be the base key or a suffixed key).
      */
     resolveActiveBucket(baseColorKey, meshData) {
-        let bucketKey = this.activeBucketKey.get(baseColorKey) ?? baseColorKey;
-        const bucket = this.buckets.get(bucketKey);
-        const currentBytes = bucket?.vertexBytes ?? 0;
-        const meshBytes = (meshData.positions.length / 3) * BATCH_CONSTANTS.BYTES_PER_VERTEX;
-        // A COLD bucket is sealed (its content lives on disk and its shell's
-        // expressIds are the restore contract) — route new arrivals (e.g. a
-        // federated add landing in the same cell+colour) to an overflow
-        // sub-bucket instead of corrupting the sealed one.
-        if (bucket && this.coldBuckets.has(bucketKey)) {
-            bucketKey = `${baseColorKey}#${this.nextSplitId++}`;
-            this.activeBucketKey.set(baseColorKey, bucketKey);
-            let target = this.buckets.get(bucketKey);
-            if (!target) {
-                target = { key: bucketKey, meshData: [], batchedMesh: null, vertexBytes: 0 };
-                this.buckets.set(bucketKey, target);
-            }
-            target.vertexBytes += meshBytes;
-            return bucketKey;
-        }
-        if (currentBytes > 0 && currentBytes + meshBytes > this.cachedMaxBufferSize) {
-            // Overflow — create a new sub-bucket
-            bucketKey = `${baseColorKey}#${this.nextSplitId++}`;
-            this.activeBucketKey.set(baseColorKey, bucketKey);
-        }
-        // Update size tracking on the bucket (create if needed)
-        let targetBucket = this.buckets.get(bucketKey);
-        if (!targetBucket) {
-            targetBucket = { key: bucketKey, meshData: [], batchedMesh: null, vertexBytes: 0 };
-            this.buckets.set(bucketKey, targetBucket);
-        }
-        targetBucket.vertexBytes += meshBytes;
-        return bucketKey;
+        const modelIndex = meshData.modelIndex ?? 0;
+        return resolvePrecisionBucket({
+            buckets: this.buckets,
+            activeKeys: this.activeBucketKey,
+            coldKeys: this.coldBuckets,
+            maxBufferSize: this.cachedMaxBufferSize,
+            sharedOrigin: this.modelTranslations.frameOrigin(this.sharedFrameOrigins.get(modelIndex) ?? null, modelIndex),
+            nextSplitKey: () => `${baseColorKey}#${this.nextSplitId++}`,
+        }, baseColorKey, meshData);
     }
     /**
      * Extract the base color key from a bucket key (strips "#N" suffix if present).
@@ -2500,32 +2518,27 @@ export class Scene {
                 this.partialBatchCache.delete(currentCacheKey);
             }
         }
-        // Collect MeshData for visible elements
-        // Use the base key (strip "#N" bucket suffix) for piece filtering, since
-        // meshData stores the original color, not the bucket key. Pieces are
-        // matched through bucketBaseKey so the comparison stays correct with
-        // spatial chunking on (base key = "cell~colour" then, and a piece only
-        // belongs to this batch when BOTH its cell and colour match).
+        // `colorKey` is the bucket key: match each piece's OWNING bucket exactly.
+        // Matching the base key (suffix "#N" stripped) pulled sibling overflow
+        // buckets' pieces in — drawn twice, wrong quantization inherited (#4832).
+        // Only a batch with no bucket (a streaming fragment) uses the base key.
+        const bucket = this.buckets.get(colorKey);
         const baseKey = this.baseColorKey(colorKey);
         const visibleMeshData = [];
         for (const expressId of visibleIds) {
-            const pieces = this.meshDataMap.get(expressId);
-            if (pieces) {
-                // Add all pieces for this element
-                for (const piece of pieces) {
-                    // Only include pieces that match this batch's cell + color
-                    if (this.bucketBaseKey(piece) === baseKey) {
-                        visibleMeshData.push(piece);
-                    }
+            for (const piece of this.meshDataMap.get(expressId) ?? []) {
+                if (bucket ? this.meshDataBucket.get(piece) === bucket : this.bucketBaseKey(piece) === baseKey) {
+                    visibleMeshData.push(piece);
                 }
             }
         }
         if (visibleMeshData.length === 0) {
             return undefined;
         }
-        // Create the partial batch
+        // Drawn INSTEAD of its source batch, so it inherits the source's f32/quantized
+        // decision (#4832): the overlay built from the same source must match its depth.
         const color = visibleMeshData[0].color;
-        const partialBatch = this.createBatchedMesh(visibleMeshData, color, device, pipeline);
+        const partialBatch = this.createBatchedMesh(visibleMeshData, color, device, pipeline, undefined, inheritedQuantization(this.quantizedBatchesEnabled, bucket?.batchedMesh), bucket?.batchedMesh?.origin);
         // Cache it
         this.partialBatchCache.set(cacheKey, partialBatch);
         this.partialBatchCacheKeys.set(sourceBatchKey, cacheKey);
@@ -2540,12 +2553,10 @@ export class Scene {
     // override colors.  They are rendered on top of existing depth via the overlay
     // pipeline (depthCompare 'equal'), so hidden entities never leak through.
     /**
-     * Set color overrides for lens coloring.
-     * Builds overlay batches grouped by override color.
-     * Original batches are NEVER modified — clearing is instant.
-     *
-     * Applies the same buffer-size splitting as regular batches to prevent
-     * GPU buffer overflow on large models.
+     * Set color overrides for lens / chart / IDS / compare / 4D coloring. Overlay
+     * batches are grouped by SOURCE bucket + override color and inherit the
+     * source batch's quantization (#4832, `scene-derived-batches.ts`). Original
+     * batches are NEVER modified — clearing is instant.
      */
     setColorOverrides(overrides, device, pipeline) {
         // Destroy previous overlay batches
@@ -2564,44 +2575,37 @@ export class Scene {
             this.setInstancedColorOverrides(null);
             return;
         }
-        // Defensive copy so external callers can mutate or reuse `overrides`
-        // without aliasing the renderer's pipeline-routing state. Tuples are
-        // frozen by the readonly type — we don't deep-clone the inner arrays
-        // because they're treated as immutable by every consumer.
+        // Defensive copy: callers may mutate/reuse `overrides`; the tuples are treated as immutable by every consumer.
         this.colorOverrides = new Map(overrides);
-        // Mirror the overlay onto the GPU-instanced occurrences: patch their colour
-        // bytes in place (no separate overlay pass — the instanced records carry the
-        // override colour directly). No-op when no instanced data is loaded.
+        // Instanced occurrences carry the override colour in their records (no overlay pass); no-op without instanced data.
         this.setInstancedColorOverrides(overrides);
-        // An overlay batch must belong to one model so placement cannot move a
-        // different model's highlighted geometry along with its first mesh.
-        const colorGroups = new Map();
-        for (const [expressId, color] of overrides) {
-            for (const piece of this.meshDataMap.get(expressId) ?? []) {
-                const key = `${piece.modelIndex ?? 0}:${this.colorKey(color)}`;
-                let group = colorGroups.get(key);
-                if (!group) {
-                    group = { color, meshData: [] };
-                    colorGroups.set(key, group);
-                }
-                group.meshData.push(piece);
-            }
-        }
-        // Build overlay batches per override color, splitting if buffers would exceed GPU limit
+        // Bucket keys carry cell + colour + model: an overlay batch is a subset of ONE base batch, in one model.
+        const colorGroups = groupOverridePieces(overrides, (id) => this.meshDataMap.get(id), (piece) => this.meshDataBucket.get(piece), (piece) => this.bucketBaseKey(piece), (c) => this.colorKey(c));
         const maxBufferSize = this.getMaxBufferSize(device);
-        for (const [, { color, meshData }] of colorGroups) {
-            if (meshData.length === 0)
-                continue;
-            const chunks = this.splitMeshDataForBufferLimit(meshData, maxBufferSize);
-            for (const chunk of chunks) {
-                const batch = this.createBatchedMesh(chunk, color, device, pipeline);
-                this.overrideBatches.push(batch);
+        for (const { color, meshData, sourceBatch, sourceKey } of colorGroups.values()) {
+            if (sourceKey !== null)
+                for (const piece of meshData)
+                    this.overlaySources.set(piece, sourceKey);
+            const quantization = inheritedQuantization(this.quantizedBatchesEnabled, sourceBatch);
+            for (const chunk of this.splitMeshDataForBufferLimit(meshData, maxBufferSize)) {
+                this.overrideBatches.push(this.createBatchedMesh(chunk, color, device, pipeline, undefined, quantization, sourceBatch?.origin));
             }
         }
     }
-    /**
-     * Clear all color overrides — instant, no batch rebuild needed.
-     */
+    /** Rebuild the installed overlays against the batches that write depth NOW
+     *  (#4832). Best-effort — a committed finalize/rebuild must not be undone by
+     *  an overlay allocation failure, so that is reported, not thrown. */
+    reapplyColorOverrides(device, pipeline) {
+        if (!this.colorOverrides)
+            return;
+        try {
+            this.setColorOverrides(cloneOverrides(this.colorOverrides), device, pipeline);
+        }
+        catch (err) {
+            console.warn('[Scene] overlay rebuild after finalize failed — colours may be missing until the next repaint', err);
+        }
+    }
+    /** Clear all color overrides — instant, no batch rebuild needed. */
     clearColorOverrides() {
         this.destroyOverrideBatches();
         this.colorOverrideGeneration++;
@@ -2644,6 +2648,7 @@ export class Scene {
         for (const batch of this.overrideBatches)
             destroyGpuResources(batch);
         this.overrideBatches = [];
+        this.overlaySources.clear();
     }
     /**
      * Clear scene
@@ -3326,22 +3331,17 @@ export class Scene {
                 this.restoreInstanceColor(device, eid);
         }
         for (const eid of toFade) {
-            const base = this.instancedOverrideColors?.get(eid) ?? this.originalInstanceColor(eid);
-            if (!base)
-                continue;
-            this.writeInstanceColor(device, eid, [base[0], base[1], base[2], ghostAlpha]);
+            const override = this.instancedOverrideColors?.get(eid);
+            if (override)
+                this.writeInstanceColor(device, eid, [override[0], override[1], override[2], ghostAlpha]);
+            else
+                this.writeOriginalInstanceColors(device, eid, ghostAlpha);
         }
         this.instancedGhosted = next;
         this.lastGhostAlpha = ghostAlpha;
         this.instancedGhostDirty = false;
         this.instancedGhostTransparent = next.size > 0 && ghostAlpha < OPAQUE_ALPHA_CUTOFF;
     }
-    /** The colour an occurrence was uploaded with, before any override or ghost. */
-    originalInstanceColor(eid) {
-        const locs = this.instancedEntityMap.get(eid);
-        const first = locs?.[0];
-        return first ? first.originalColor : null;
-    }
     /** Write the combined flag lane (selected | hidden) for every occurrence of `eid`
      *  (shares one u32 lane at INSTANCE_FLAGS_OFFSET, so both bits are folded here).
      *  #4382: for the item-filtered eid, selected narrows per-occurrence to
@@ -3383,6 +3383,7 @@ export class Scene {
                 device.queue.writeBuffer(buf, loc.byteOffset + INSTANCE_COLOR_OFFSET, new Float32Array(loc.originalColor));
         }
     }
+    writeOriginalInstanceColors(device, eid, alpha) { writeOriginalInstancedColors(device, this.instancedEntityMap.get(eid) ?? [], this.instancedTemplates, INSTANCE_COLOR_OFFSET, alpha); }
     /**
      * Build a textured mesh (#961): interleave position+normal+entityId+uv into one
      * vertex buffer, upload the decoded RGBA8 texture, create a sampler honouring
@@ -3567,6 +3568,7 @@ export class Scene {
      */
     clearFlatGeometry() {
         this.authoredGeneration++;
+        this.authoredPreparations.invalidate();
         this.instanceSuppression.restore();
         this.appearanceController?.forget();
         this.clearFlatBuffers();
@@ -3575,6 +3577,7 @@ export class Scene {
      * owners keep their original-instance history. Full reset remains separate. */
     clearFlatGeometryForRebuild(geometry, models, sourceGeometry = geometry) {
         this.authoredGeneration++;
+        this.authoredPreparations.invalidate();
         const retained = this.appearanceController?.prepareRebuild(sourceGeometry, models) ?? new Set();
         const discarded = this.appearanceController?.discardedForRebuild(retained) ?? [];
         // A discarded converted owner must not resurrect its obsolete type instance.