@ifc-lite/renderer 3.1.0 → 3.2.0

package/dist/scene.js

@@ -4,9 +4,9 @@
 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';
@@ -14,9 +14,10 @@ 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';
@@ -24,11 +25,13 @@ 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()
@@ -84,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)
@@ -95,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,
@@ -135,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) {
@@ -301,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
      */
@@ -329,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,
@@ -428,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;
@@ -474,7 +481,8 @@ export class Scene {
      *  lattice snap in createMeshFromData (an f32 batch must NOT snap). Same rule
      *  as overlay/partial batches; global flag while unbucketed. */
     isMeshQuantized(meshData) {
-        return inheritedQuantization(this.quantizedBatchesEnabled, this.meshDataBucket.get(meshData)?.batchedMesh) !== 'off';
+        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) {
@@ -629,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`);
@@ -664,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;
@@ -863,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;
         }
@@ -873,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);
                 }
@@ -888,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;
@@ -921,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++) {
@@ -933,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,
@@ -941,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
@@ -1013,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);
                 }
@@ -1049,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);
@@ -1081,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
@@ -1112,48 +1163,15 @@ 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;
-        const rebuilt = [];
-        for (const key of this.pendingBatchKeys) {
-            const bucket = this.buckets.get(key);
-            const previousQuantized = bucket?.batchedMesh?.quantized !== undefined;
-            // 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;
-            rebuilt.push({ bucket, previousQuantized });
-        }
-        // 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.
@@ -1559,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`. */
@@ -1801,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) {
@@ -1812,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);
             }
@@ -1987,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 = [];
@@ -2006,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);
                     }
@@ -2031,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) {
@@ -2172,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) {
@@ -2186,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
@@ -2328,14 +2362,17 @@ export class Scene {
      *   participate in the main buckets map).
      * @param quantization - 'auto' for bucket batches; derived batches pass `inheritedQuantization(source)` (#4832).
      */
-    createBatchedMesh(meshes, color, device, pipeline, bucketKey, quantization = this.quantizedBatchesEnabled ? 'auto' : 'off') {
+    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),
+            origin,
             quantized: quantization, lod: this.lodBuildsEnabled,
         }, bucketKey);
         this.nextBatchId++;
@@ -2365,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).
@@ -2524,7 +2538,7 @@ export class Scene {
         // 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, undefined, inheritedQuantization(this.quantizedBatchesEnabled, bucket?.batchedMesh));
+        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);
@@ -2574,7 +2588,7 @@ export class Scene {
                     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));
+                this.overrideBatches.push(this.createBatchedMesh(chunk, color, device, pipeline, undefined, quantization, sourceBatch?.origin));
             }
         }
     }
@@ -3317,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
@@ -3374,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
@@ -3558,6 +3568,7 @@ export class Scene {
      */
     clearFlatGeometry() {
         this.authoredGeneration++;
+        this.authoredPreparations.invalidate();
         this.instanceSuppression.restore();
         this.appearanceController?.forget();
         this.clearFlatBuffers();
@@ -3566,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.