@ifc-lite/renderer 3.1.0 → 4.2.0

package/dist/scene.js

@@ -4,9 +4,10 @@
 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 { createStaticGpuBuffer } from './gpu-static-upload.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 +15,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 +26,16 @@ 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 { unionInstancedWorldAabb as unionInstanceBounds } from './scene-instance-bounds.js';
+import { DerivedMeshProvenance } from './scene-derived-mesh-provenance.js';
+import { rebuildSceneBatches } from './scene-batch-rebuild.js';
+import { regroupStreamedBuckets } from './scene-finalize-regroup.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 { translateInstanceRecord } from './scene-instance-translation.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 +91,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 +103,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 +145,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) {
@@ -295,18 +304,20 @@ export class Scene {
     // Temporary fragment batches created during streaming for immediate rendering.
     // Destroyed and replaced by proper merged batches in finalizeStreaming().
     streamingFragments = [];
+    // Buckets that received streamed meshes since the last finalize — the only
+    // ones a finalize re-groups and rebuilds (#5358).
+    streamedBucketKeys = new Set();
     // ─── Mesh command queue ────────────────────────────────────────────
     // Decouples React state updates from GPU work.  Callers push meshes
     // via queueMeshes() (instant, no GPU), and the animation loop drains
     // 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 +340,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 +441,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 +488,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 +644,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 +679,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 +879,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 +889,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 +904,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 +949,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 +970,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 +978,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 +1058,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);
                 }
@@ -1046,13 +1091,23 @@ export class Scene {
      * STREAMING OPTIMIZATION: During streaming, creates lightweight "fragment"
      * batches from ONLY the new meshes instead of re-merging all accumulated
      * data. This reduces streaming from O(N²) to O(N). Call finalizeStreaming()
-     * when streaming completes to do one O(N) full merge.
+     * when streaming completes to merge the streamed buckets (only those, #5358).
      */
     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 +1136,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
@@ -1095,16 +1153,17 @@ export class Scene {
                 this.meshDataBucket.set(meshData, bucket);
                 // Also store individual mesh data for visibility filtering
                 this.addMeshData(meshData);
-                // Track pending keys for non-streaming rebuild only
-                if (!isStreaming) {
+                // Non-streaming rebuilds now; streamed buckets wait for finalize.
+                if (isStreaming)
+                    this.streamedBucketKeys.add(bucketKey);
+                else
                     this.pendingBatchKeys.add(bucketKey);
-                }
             }
         }
         if (isStreaming) {
             // STREAMING: Create small fragment batches from ONLY the new meshes.
             // Avoids the O(N²) cost of re-merging all accumulated data every batch.
-            // finalizeStreaming() destroys fragments and does one O(N) full merge.
+            // finalizeStreaming() destroys fragments and merges the streamed buckets.
             // `renderable` excludes textured meshes (drawn via the textured pipeline).
             this.createStreamingFragments(renderable, device, pipeline);
             return;
@@ -1112,48 +1171,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.
@@ -1486,22 +1512,17 @@ export class Scene {
             const cpu = this.instancedTemplateCpu[occ.templateIndex];
             if (!cpu)
                 continue;
-            // Column-major mat4: the translation column is floats 12,13,14, i.e. bytes
-            // +48/+52/+56 of the occurrence's record (matches unionInstancedWorldAabb).
-            const dv = new DataView(cpu.instanceData);
             const b = occ.byteOffset;
-            const tx = dv.getFloat32(b + 48, true) + dx;
-            const ty = dv.getFloat32(b + 52, true) + dy;
-            const tz = dv.getFloat32(b + 56, true) + dz;
-            dv.setFloat32(b + 48, tx, true);
-            dv.setFloat32(b + 52, ty, true);
-            dv.setFloat32(b + 56, tz, true);
+            const translated = translateInstanceRecord(cpu, b, [dx, dy, dz]);
             // Push only the 12 translation bytes to the GPU buffer (in place). Guarded
             // on the cached device so CPU-only tests still exercise the matrix math.
             if (device) {
                 const gpu = this.instancedTemplates[occ.templateIndex]?.instanceBuffer;
-                if (gpu)
-                    device.queue.writeBuffer(gpu, b + 48, new Float32Array([tx, ty, tz]));
+                if (gpu) {
+                    device.queue.writeBuffer(gpu, b + 48, translated.translation);
+                    if (translated.legacyAnchors)
+                        device.queue.writeBuffer(gpu, b + 88, translated.legacyAnchors);
+                }
             }
             moved = true;
         }
@@ -1559,21 +1580,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`. */
@@ -1736,7 +1776,7 @@ export class Scene {
         // yielding the frame back at the TOP of the loop. The mesh-count-only chunker
         // could merge a 512-mesh chunk of high-poly meshes (e.g. 899 Velux roof
         // windows at 7624 tris each → ~3.9M tris) in ONE indivisible mergeGeometry +
-        // mappedAtCreation buffer copy — hundreds of ms that parked the main thread
+        // GPU buffer upload copy — hundreds of ms that parked the main thread
         // past the 16s stream watchdog. Capping each appendToBatches by index volume
         // keeps every synchronous slice ≈ one bounded fragment merge (~12-15ms).
         const MAX_MESHES_PER_FLUSH = 4096;
@@ -1801,7 +1841,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 +1852,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);
             }
@@ -1826,15 +1866,14 @@ export class Scene {
         return splitMeshForStreaming(meshData, Scene.STREAMING_FRAGMENT_MAX_INDICES, Scene.STREAMING_FRAGMENT_MAX_VERTEX_BYTES);
     }
     /**
-     * Finalize streaming: destroy temporary fragment batches and do one full
-     * O(N) merge of all accumulated mesh data into proper batches.
+     * Finalize streaming: destroy the temporary fragment batches and merge the
+     * meshes streamed since the last finalize into proper batches.
      * Call this when streaming completes instead of rebuildPendingBatches().
      *
-     * IMPORTANT: During streaming, external code (applyColorUpdatesToMeshes)
-     * may mutate meshData.color in-place for deferred style/material colors.
-     * This means the bucket keys (computed at insertion time from the ORIGINAL
-     * color) no longer match the meshes' current colors. We must re-group all
-     * meshData by their CURRENT color to produce correct batches.
+     * Only the buckets that received streamed meshes are re-grouped and rebuilt
+     * (plus any key already pending); every other model's batches stay as they
+     * are (#5358). See `regroupStreamedBuckets` for why the streamed meshes are
+     * re-grouped by their CURRENT colour.
      */
     finalizeStreaming(device, pipeline) {
         if (this.streamingFragments.length === 0)
@@ -1847,6 +1886,27 @@ export class Scene {
             this.finalizeInProgress = false;
         }
     }
+    regroupStreamed() {
+        return regroupStreamedBuckets({
+            buckets: this.buckets,
+            meshDataBucket: this.meshDataBucket,
+            activeBucketKey: this.activeBucketKey,
+            coldBuckets: this.coldBuckets,
+            pendingBatchKeys: this.pendingBatchKeys,
+            streamedBucketKeys: this.streamedBucketKeys,
+            bucketBaseKey: (md) => this.bucketBaseKey(md),
+            resolveActiveBucket: (base, md) => this.resolveActiveBucket(base, md),
+            createBucket: (key) => ({ key, meshData: [], batchedMesh: null, vertexBytes: 0 }),
+        });
+    }
+    /** Free batches the finalize swap replaced, with their per-batch caches. */
+    retireFinalizedBatches(batches) {
+        for (const batch of batches) {
+            this.dropPartialCacheForBatch(batch);
+            this.lastDrawnFrame.delete(batch.id);
+            destroyGpuResources(batch);
+        }
+    }
     finalizeStreamingInner(device, pipeline) {
         // Save references to old fragments/batches — keep them rendering
         // until the new proper batches are fully built (no visual gap).
@@ -1854,103 +1914,47 @@ export class Scene {
         const oldBatches = this.batchedMeshes;
         const fragmentSet = new Set(oldFragments);
         const oldBatchSet = new Set(oldBatches);
-        // Steps 1-4 detach the old drawables (streamingFragments = [],
-        // batchedMeshes = []) BEFORE the replacement GPU buffers exist. If a
-        // createBuffer fails part-way through, callers that CONTAIN the throw to
-        // keep the canvas alive would otherwise be left rendering a half-built —
-        // often empty — scene, turning a crash into a silently blank model.
+        // The re-group detaches the streamed buckets BEFORE the replacement GPU
+        // buffers exist. If a createBuffer fails part-way through, callers that
+        // CONTAIN the throw to keep the canvas alive would otherwise be left
+        // rendering a half-built scene, turning a crash into a silently blank model.
+        let regroup = null;
         let rebuilt = false;
         try {
             this.streamingFragments = [];
-            // 1. Collect ALL accumulated meshData before clearing state.
-            //    Cold buckets (issue #1682 phase 3b) hold NO meshData — their
-            //    geometry lives on disk — so they are carried through the rebuild as
-            //    sealed shells instead of being re-grouped (re-grouping would
-            //    silently drop them).
-            const allMeshData = [];
-            const carriedCold = [];
-            for (const [key, bucket] of this.buckets) {
-                if (this.coldBuckets.has(key) && bucket.meshData.length === 0 && bucket.batchedMesh) {
-                    carriedCold.push([key, bucket]);
-                    continue;
-                }
-                for (const md of bucket.meshData)
-                    allMeshData.push(md);
-            }
-            // 2. Clear all bucket/batch state for a clean rebuild
-            // NOTE: batchedMeshes keeps the OLD array reference — the renderer
-            // continues to draw from it until we swap in the new array below.
-            this.buckets.clear();
-            this.meshDataBucket = new Map();
-            this.activeBucketKey.clear();
-            this.lastDrawnFrame.clear();
-            this.residencyRestoreQueue.clear();
-            this.pendingBatchKeys.clear();
-            // Re-seat the carried cold shells in the fresh bucket map (their GPU
-            // shells re-enter the flat array via rebuildPendingBatches below).
-            for (const [key, bucket] of carriedCold)
-                this.buckets.set(key, bucket);
-            // 3. Re-group ALL meshData by their CURRENT color (and grid cell).
-            //    meshData.color may have been mutated in-place since the mesh was
-            //    first bucketed, so the original bucket key is stale. Re-grouping
-            //    by current color ensures batches render with correct colors.
-            for (const meshData of allMeshData) {
-                const baseKey = this.bucketBaseKey(meshData);
-                const bucketKey = this.resolveActiveBucket(baseKey, meshData);
-                let bucket = this.buckets.get(bucketKey);
-                if (!bucket) {
-                    bucket = { key: bucketKey, meshData: [], batchedMesh: null, vertexBytes: 0 };
-                    this.buckets.set(bucketKey, bucket);
-                }
-                bucket.meshData.push(meshData);
-                this.meshDataBucket.set(meshData, bucket);
-                this.pendingBatchKeys.add(bucketKey);
-            }
-            // 4. Build new proper batches into a fresh array
+            regroup = this.regroupStreamed();
+            // Build into a fresh array; rebuildPendingBatches republishes every
+            // bucket's batch, untouched ones included.
             this.batchedMeshes = [];
             this.rebuildPendingBatches(device, pipeline);
             rebuilt = true;
-            // Cached partial (filtered-visibility) batches are keyed by their SOURCE
-            // batch, so they only go stale once the replacement batches are live.
-            // Dropping them up in step 2 destroyed their GPU resources BEFORE the
-            // rebuild could fail, and the rollback cannot bring them back — an active
-            // hide/isolate view lost its visible subset and had to recreate it
-            // against the very device that just failed. On the failure path they now
-            // survive, still matching the restored batches.
-            this.dropAllPartialCaches();
         }
         finally {
             if (!rebuilt) {
-                // Free ONLY what this attempt created. Carried cold shells are aliased
-                // into BOTH the old and the new array, so anything that was already
-                // live before the rebuild must be left alone — destroying it would
-                // leave the restored arrays pointing at dead buffers.
+                // Free ONLY what this attempt created: anything live before the
+                // rebuild is what the restored arrays point back at.
                 for (const created of this.batchedMeshes) {
                     if (!oldBatchSet.has(created) && !fragmentSet.has(created)) {
                         destroyGpuResources(created);
                     }
                 }
-                // Step 5 never ran, so every old fragment/batch is still a live GPU
-                // resource: putting the arrays back restores exactly what was on
-                // screen.
+                regroup?.rollback();
                 this.streamingFragments = oldFragments;
                 this.batchedMeshes = oldBatches;
             }
         }
-        // 5. NOW destroy old fragment/batch GPU resources (new batches are live)
-        for (const fragment of oldFragments)
-            destroyGpuResources(fragment);
-        for (const batch of oldBatches) {
-            if (!fragmentSet.has(batch))
-                destroyGpuResources(batch);
-        }
+        // NOW free the fragments and the dissolved buckets' batches (the
+        // replacements are live). Batches of rebuilt surviving buckets were
+        // already retired by rebuildPendingBatches.
+        this.retireFinalizedBatches(oldFragments);
+        this.retireFinalizedBatches(regroup?.retired ?? []);
         this.reapplyColorOverrides(device, pipeline);
     }
     /**
      * Time-sliced version of finalizeStreaming.
-     * Re-groups mesh data and rebuilds GPU batches in small chunks,
-     * yielding to the event loop between chunks so orbit/pan stays responsive.
-     * Streaming fragments continue rendering until each new batch replaces them.
+     * Rebuilds the streamed buckets' batches in small chunks, yielding to the
+     * event loop between chunks so orbit/pan stays responsive. The fragments
+     * keep rendering until the rebuilt batches are swapped in.
      *
      * @param device  GPU device
      * @param pipeline  Render pipeline
@@ -1982,40 +1986,32 @@ export class Scene {
         // spec). Every entry point that can fail — the synchronous preamble AND
         // each chunked continuation — must therefore run under its own try/catch
         // that explicitly calls `reject`, mirroring finalizeStreamingInner's
-        // try/finally contract: restore oldFragments/oldBatches, free only what
-        // this attempt created, defer dropAllPartialCaches() until success, and
-        // always clear finalizeInProgress.
+        // try/finally contract: restore oldFragments/oldBatches and the bucket
+        // map, free only what this attempt created, and 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 = [];
+            // Pending keys whose bucket ended up empty: deleted (and their batch
+            // retired) at the swap, exactly as rebuildPendingBatches would.
+            const emptied = [];
+            let regroup = null;
             let pendingKeys = [];
             let keyIdx = 0;
             function rollback() {
-                // Free ONLY what this attempt created — carried cold shells and
-                // anything already live before the rebuild must be left alone (they
-                // 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);
                     }
                 }
-                scene.streamingFragments = oldFragments;
+                regroup?.rollback();
+                scene.streamingFragments = [...oldFragments, ...scene.streamingFragments]; // + any streamed in meanwhile
                 scene.batchedMeshes = oldBatches;
                 scene.finalizeInProgress = false;
             }
@@ -2026,43 +2022,41 @@ export class Scene {
                         const key = pendingKeys[keyIdx++];
                         const bucket = scene.buckets.get(key);
                         if (!bucket || bucket.meshData.length === 0) {
-                            scene.buckets.delete(key);
+                            emptied.push(key);
                             continue;
                         }
                         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 });
-                        newBatches.push(batchedMesh);
+                        bucket.frameOrigin = batchedMesh.origin;
+                        createdOwned.push({ bucket, previous, previousFrameOrigin, batch: batchedMesh });
                         // Check time budget — yield if exceeded
                         if (performance.now() - chunkStart >= budgetMs) {
                             setTimeout(processChunk, 0);
                             return;
                         }
                     }
-                    // Carried cold shells stay drawable-when-restored: keep them in the
-                    // flat array (their buffers are already destroyed; the draw loop
-                    // skips gpuResident === false and the restore path revives them).
-                    for (const [, bucket] of carriedCold) {
-                        if (bucket.batchedMesh)
-                            newBatches.push(bucket.batchedMesh);
-                    }
-                    // All batches built — atomic swap so renderer never sees an empty array
-                    scene.batchedMeshes = newBatches;
-                    // Cached partial (filtered-visibility) batches are keyed by their
-                    // SOURCE batch, so they only go stale once the replacement batches
-                    // are live — dropping them any earlier destroys GPU resources a
-                    // mid-rebuild failure could never get back (same rationale as
-                    // finalizeStreamingInner).
-                    scene.dropAllPartialCaches();
-                    // Destroy old fragment/batch GPU resources
-                    for (const fragment of oldFragments)
-                        destroyGpuResources(fragment);
-                    for (const batch of oldBatches) {
-                        if (!fragmentSet.has(batch))
-                            destroyGpuResources(batch);
+                    const retired = [...oldFragments, ...(regroup?.retired ?? [])];
+                    for (const { previous } of createdOwned)
+                        if (previous)
+                            retired.push(previous);
+                    for (const key of emptied) {
+                        const batch = scene.buckets.get(key)?.batchedMesh;
+                        if (batch)
+                            retired.push(batch);
+                        scene.buckets.delete(key);
                     }
+                    // Atomic swap so the renderer never sees an empty array: every
+                    // bucket's live batch (untouched models included, evicted shells
+                    // too — the draw loop skips gpuResident === false and the restore
+                    // path revives them) plus any fragment streamed in meanwhile.
+                    scene.batchedMeshes = [
+                        ...[...scene.buckets.values()].flatMap((b) => (b.batchedMesh ? [b.batchedMesh] : [])),
+                        ...scene.streamingFragments,
+                    ];
+                    scene.retireFinalizedBatches(retired);
                     scene.finalizeInProgress = false;
                     scene.reapplyColorOverrides(device, pipeline); // never throws: the swap above is committed
                     resolve();
@@ -2073,45 +2067,9 @@ export class Scene {
                 }
             }
             try {
-                // --- Synchronous preamble (fast O(N) bookkeeping) ---
+                // --- Synchronous preamble: re-group the streamed meshes only ---
                 scene.streamingFragments = [];
-                // 1. Collect ALL accumulated meshData (cold buckets carried as sealed
-                //    shells — see the sync finalize for the rationale)
-                const allMeshData = [];
-                for (const [key, bucket] of scene.buckets) {
-                    if (scene.coldBuckets.has(key) && bucket.meshData.length === 0 && bucket.batchedMesh) {
-                        carriedCold.push([key, bucket]);
-                        continue;
-                    }
-                    for (const md of bucket.meshData)
-                        allMeshData.push(md);
-                }
-                // 2. Clear bucket/batch state. dropAllPartialCaches() is deliberately
-                //    NOT called here — see the success path above.
-                scene.buckets.clear();
-                scene.meshDataBucket = new Map();
-                scene.activeBucketKey.clear();
-                scene.lastDrawnFrame.clear();
-                scene.residencyRestoreQueue.clear();
-                scene.pendingBatchKeys.clear();
-                // Re-seat the carried cold shells in the fresh bucket map.
-                for (const [key, bucket] of carriedCold)
-                    scene.buckets.set(key, bucket);
-                // 3. Re-group meshData by current color (and grid cell) — fast
-                for (const meshData of allMeshData) {
-                    const baseKey = scene.bucketBaseKey(meshData);
-                    const bucketKey = scene.resolveActiveBucket(baseKey, meshData);
-                    let bucket = scene.buckets.get(bucketKey);
-                    if (!bucket) {
-                        bucket = { key: bucketKey, meshData: [], batchedMesh: null, vertexBytes: 0 };
-                        scene.buckets.set(bucketKey, bucket);
-                    }
-                    bucket.meshData.push(meshData);
-                    scene.meshDataBucket.set(meshData, bucket);
-                    scene.pendingBatchKeys.add(bucketKey);
-                }
-                // Build new batches into a temporary array so the old batchedMeshes
-                // (streaming fragments) keep rendering until the swap is complete.
+                regroup = scene.regroupStreamed();
                 pendingKeys = Array.from(scene.pendingBatchKeys);
                 scene.pendingBatchKeys.clear();
             }
@@ -2152,6 +2110,7 @@ export class Scene {
         this.coldBuckets.clear();
         this.dirtyBuckets.clear();
         this.pendingBatchKeys.clear();
+        this.streamedBucketKeys.clear();
         this.dropAllPartialCaches();
         this.geometryReleased = true;
         this.ephemeralStreamingMode = false;
@@ -2172,7 +2131,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 +2144,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 +2288,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 +2328,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 +2464,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 +2514,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));
             }
         }
     }
@@ -2873,31 +2813,13 @@ export class Scene {
                 vf[o + 5] = i * 3 + 2 < t.normals.length ? t.normals[i * 3 + 2] : 0;
                 // vf[o + 6] (entityId lane) stays 0.
             }
-            const vertexBuffer = device.createBuffer({
-                size: vtx.byteLength,
-                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
-                mappedAtCreation: true,
-            });
-            new Uint8Array(vertexBuffer.getMappedRange()).set(new Uint8Array(vtx));
-            vertexBuffer.unmap();
-            const indexBuffer = device.createBuffer({
-                size: t.indices.byteLength,
-                usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
-                mappedAtCreation: true,
-            });
-            new Uint32Array(indexBuffer.getMappedRange()).set(t.indices);
-            indexBuffer.unmap();
+            const vertexBuffer = createStaticGpuBuffer(device, vtx, GPUBufferUsage.VERTEX);
+            const indexBuffer = createStaticGpuBuffer(device, t.indices, GPUBufferUsage.INDEX);
             // instanceBuffer is already the interleaved mat4 + entityId + rgba block
             // (INSTANCE_STRIDE_BYTES per occurrence) from prepareInstancedRender.
-            this.modelTranslations.placeInstances(t.instanceBuffer, modelIndex, INSTANCE_STRIDE_BYTES);
+            this.modelTranslations.placeInstances(t.instanceBuffer, modelIndex, INSTANCE_STRIDE_BYTES, t.canonicalAnchors, t.canonicalMatrixTranslations);
             const instSize = t.instanceCount * INSTANCE_STRIDE_BYTES;
-            const instanceBuffer = device.createBuffer({
-                size: instSize,
-                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
-                mappedAtCreation: true,
-            });
-            new Uint8Array(instanceBuffer.getMappedRange()).set(new Uint8Array(t.instanceBuffer, 0, instSize));
-            instanceBuffer.unmap();
+            const instanceBuffer = createStaticGpuBuffer(device, new Uint8Array(t.instanceBuffer, 0, instSize), GPUBufferUsage.VERTEX);
             // Always append: slots are stable identities, never recycled.
             const templateIndex = this.instancedTemplates.length;
             const template = {
@@ -2907,6 +2829,7 @@ export class Scene {
                 indexCount: t.indices.length,
                 instanceBuffer,
                 instanceCount: t.instanceCount,
+                canonicalAnchors: t.canonicalAnchors,
                 bounds: null,
                 maxOccRadius: 0,
                 selectedCount: 0,
@@ -2940,6 +2863,8 @@ export class Scene {
                 normals: t.normals,
                 indices: t.indices,
                 instanceData: t.instanceBuffer,
+                canonicalAnchors: t.canonicalAnchors,
+                canonicalMatrixTranslations: t.canonicalMatrixTranslations,
                 localMin: [lmnx, lmny, lmnz],
                 localMax: [lmxx, lmxy, lmxz],
             };
@@ -3010,51 +2935,10 @@ export class Scene {
         this.instancedVisibilityDirty = true;
         this.instancedGhostDirty = true;
     }
-    /** Transform a template's local AABB by an occurrence's column-major mat4 (read
-     *  from the packed instance record at `matOffset`) and union the world box into
-     *  boundingBoxes[eid]. Returns the occurrence's world box so the caller can also
-     *  fold it into the template's cull metadata. */
     unionInstancedWorldAabb(eid, dv, matOffset, lmnx, lmny, lmnz, lmxx, lmxy, lmxz) {
-        const m0 = dv.getFloat32(matOffset + 0, true), m1 = dv.getFloat32(matOffset + 4, true), m2 = dv.getFloat32(matOffset + 8, true);
-        const m4 = dv.getFloat32(matOffset + 16, true), m5 = dv.getFloat32(matOffset + 20, true), m6 = dv.getFloat32(matOffset + 24, true);
-        const m8 = dv.getFloat32(matOffset + 32, true), m9 = dv.getFloat32(matOffset + 36, true), m10 = dv.getFloat32(matOffset + 40, true);
-        const m12 = dv.getFloat32(matOffset + 48, true), m13 = dv.getFloat32(matOffset + 52, true), m14 = dv.getFloat32(matOffset + 56, true);
-        let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
-        for (let c = 0; c < 8; c++) {
-            const x = (c & 1) ? lmxx : lmnx, y = (c & 2) ? lmxy : lmny, z = (c & 4) ? lmxz : lmnz;
-            const wx = m0 * x + m4 * y + m8 * z + m12;
-            const wy = m1 * x + m5 * y + m9 * z + m13;
-            const wz = m2 * x + m6 * y + m10 * z + m14;
-            if (wx < minX)
-                minX = wx;
-            if (wy < minY)
-                minY = wy;
-            if (wz < minZ)
-                minZ = wz;
-            if (wx > maxX)
-                maxX = wx;
-            if (wy > maxY)
-                maxY = wy;
-            if (wz > maxZ)
-                maxZ = wz;
-        }
-        const existing = this.boundingBoxes.get(eid);
-        if (existing) {
-            existing.min.x = Math.min(existing.min.x, minX);
-            existing.min.y = Math.min(existing.min.y, minY);
-            existing.min.z = Math.min(existing.min.z, minZ);
-            existing.max.x = Math.max(existing.max.x, maxX);
-            existing.max.y = Math.max(existing.max.y, maxY);
-            existing.max.z = Math.max(existing.max.z, maxZ);
-        }
-        else {
-            this.boundingBoxes.set(eid, { min: { x: minX, y: minY, z: minZ }, max: { x: maxX, y: maxY, z: maxZ } });
-        }
-        return { minX, minY, minZ, maxX, maxY, maxZ };
+        return unionInstanceBounds(this.boundingBoxes, eid, dv, matOffset, lmnx, lmny, lmnz, lmxx, lmxy, lmxz);
     }
-    /** True if `expressId` is a GPU-instanced occurrence (lives only in the instanced
-     *  shard, not the flat meshDataMap). CPU consumers use this to decide whether to
-     *  fall back to the instanced accessors below. */
+    /** True when `expressId` has a GPU-instanced occurrence. */
     isInstancedEntity(expressId) {
         return this.instancedEntityMap.has(expressId);
     }
@@ -3317,22 +3201,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 +3253,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 +3438,7 @@ export class Scene {
      */
     clearFlatGeometry() {
         this.authoredGeneration++;
+        this.authoredPreparations.invalidate();
         this.instanceSuppression.restore();
         this.appearanceController?.forget();
         this.clearFlatBuffers();
@@ -3566,6 +3447,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.
@@ -3623,6 +3505,7 @@ export class Scene {
         this.dirtyBuckets.clear();
         this.cachedMaxBufferSize = 0;
         this.pendingBatchKeys.clear();
+        this.streamedBucketKeys.clear();
         this.meshQueue = [];
         this.meshQueueReadIndex = 0;
         this.geometryReleased = false;
@@ -3921,7 +3804,7 @@ export class Scene {
      * covered: their world AABBs are registered in `boundingBoxes` when the
      * instanced shard is built.
      */
-    selectRect(x0, y0, x1, y1, viewportWidth, viewportHeight, viewProj, hiddenIds, isolatedIds, clip) {
+    selectRect(x0, y0, x1, y1, viewportWidth, viewportHeight, viewProj, hiddenIds, isolatedIds, clip, rte) {
         // After release the cache is already the complete set; before it, boxes are
         // computed lazily, so make sure every entity that still has mesh data has
         // one. Same authoritative id set pick() uses, so colour-fused fillers whose
@@ -3939,7 +3822,7 @@ export class Scene {
                 this.getEntityBoundingBox(expressId);
             }
         }
-        return selectBoundingBoxesInRect(this.boundingBoxes, viewProj, { x0, y0, x1, y1 }, viewportWidth, viewportHeight, hiddenIds, isolatedIds, clip);
+        return selectBoundingBoxesInRect(this.boundingBoxes, viewProj, { x0, y0, x1, y1 }, viewportWidth, viewportHeight, hiddenIds, isolatedIds, clip, rte);
     }
 }
 //# sourceMappingURL=scene.js.map