@ifc-lite/renderer 1.35.2 → 1.36.0

package/dist/scene.js

@@ -4,6 +4,11 @@
 import { BATCH_CONSTANTS } from './constants.js';
 import { prepareRayDirInv, raycastBoundingBoxes, raycastTriangles, rayIntersectsBox, } from './scene-raycaster.js';
 import { mergeGeometry, splitMeshDataForBufferLimit, colorSaltByte, packEntityLane } from './scene-geometry.js';
+import { sumResidentGpuBytes } from './render-stats.js';
+import { simplifyIndicesByClustering, lodCellSizeForBounds, LOD_MIN_TRIANGLES } from './lod-simplify.js';
+import { quantizeInterleaved } from './quantize.js';
+import { bucketBaseKeyFor } from './chunk-grid.js';
+import { selectEvictions } from './residency.js';
 import { OPAQUE_ALPHA_CUTOFF } from './overlay-routing.js';
 import { prepareInstancedRender, INSTANCE_STRIDE_BYTES, INSTANCE_COLOR_OFFSET, INSTANCE_FLAGS_OFFSET, INSTANCE_FLAG_SELECTED, INSTANCE_FLAG_HIDDEN, } from './instanced-render.js';
 function destroyGpuResources(m) {
@@ -11,6 +16,8 @@ function destroyGpuResources(m) {
     m.indexBuffer.destroy();
     if (m.uniformBuffer)
         m.uniformBuffer.destroy();
+    if (m.lod1IndexBuffer)
+        m.lod1IndexBuffer.destroy();
 }
 /** Shared empty result for getInstancedTemplates() when the instanced pass is hidden. */
 const EMPTY_INSTANCED_TEMPLATES = [];
@@ -40,6 +47,40 @@ export class Scene {
     // sub-bucket with a suffixed key (e.g. "500|500|500|1000#1"). This keeps
     // all downstream maps single-valued and the rendering code unchanged.
     activeBucketKey = new Map(); // base colorKey -> current active bucket key
+    // Spatial chunking (issue #1682 phase 2): when set, bucket base keys gain a
+    // grid-cell prefix so batches are spatially compact and cullable. Null = off
+    // (plain colour bucketing, the historical behaviour).
+    spatialChunking = null;
+    // GPU residency budget (issue #1682 phase 3a): when set, bucket-owned
+    // batches not drawn recently are evicted (GPU buffers destroyed, CPU
+    // meshData + metadata shell kept) once their combined bytes exceed the
+    // budget, and rebuilt on demand when the draw loop wants them again.
+    gpuBudgetBytes = null;
+    residencyFrame = 0; // bumped once per render()
+    lastDrawnFrame = new Map(); // batch.id -> residencyFrame
+    residencyRestoreQueue = new Set(); // bucket keys awaiting re-upload
+    residencyOverBudgetWarned = false;
+    // Cold tier (issue #1682 phase 3b): warm buckets (GPU-evicted, CPU kept)
+    // can additionally drop their CPU meshData when a HOST budget is set and a
+    // cold-storage provider (v13 cache chunks) can restore it on demand.
+    // hot = GPU+CPU, warm = CPU only, cold = metadata shell only.
+    coldProvider = null;
+    hostBudgetBytes = null;
+    coldBuckets = new Set(); // CPU dropped, provider-restorable
+    dirtyBuckets = new Set(); // diverged from disk (recolour/move/remove)
+    coldRestoresInFlight = new Map();
+    hostOverBudgetWarned = false;
+    hostEnforceCountdown = 0;
+    // LOD1 builds (issue #1682 phase 5): off unless the app enables them.
+    lodBuildsEnabled = false;
+    // 12-byte quantized batch vertices (issue #1682 phase 6): off unless the
+    // renderer probed its quantized pipelines and enabled it.
+    quantizedBatchesEnabled = false;
+    // True while a (possibly time-sliced) finalize rebuild is running. The
+    // preamble clears streamingFragments synchronously, so hasStreamingFragments
+    // alone under-reports "still settling" — settle-sensitive consumers
+    // (post-load telemetry) must also check this.
+    finalizeInProgress = false;
     nextSplitId = 0; // Monotonic counter for sub-bucket keys
     nextBatchId = 0; // Monotonic counter for unique batch identifiers
     // Shared local-frame origin for ALL batches (set from the first batch's world
@@ -103,6 +144,446 @@ export class Scene {
     getSharedFrameOrigin() {
         return this.sharedFrameOrigin;
     }
+    /**
+     * Enable/disable spatial chunk bucketing (issue #1682 phase 2). When set,
+     * colour buckets are additionally partitioned by world grid cell, making
+     * batches spatially compact so per-batch frustum/contribution culling
+     * fires at chunk granularity. Pure reorganization: same triangles, same
+     * shared frame origin, same draw path — only the batch partition changes.
+     *
+     * Set BEFORE geometry loads. Existing buckets keep their keys (keys are
+     * opaque downstream), so flipping mid-model only affects meshes routed
+     * afterwards; the next finalize/recolour re-groups stragglers.
+     */
+    setSpatialChunking(config) {
+        if (config && !(Number.isFinite(config.cellSize) && config.cellSize > 0)) {
+            console.warn('[Scene] ignoring invalid spatial chunking cellSize:', config.cellSize);
+            return;
+        }
+        this.spatialChunking = config;
+    }
+    getSpatialChunking() {
+        return this.spatialChunking;
+    }
+    // ─── GPU residency (issue #1682 phase 3a) ──────────────────────────────
+    // The budget applies to bucket-owned colour/chunk batches (the evictable
+    // set). Streaming fragments, partial sub-batches, overlay batches,
+    // textured meshes and instanced templates are never evicted: fragments are
+    // transient, the rest are small or lack a rebuild source. Enforcement
+    // no-ops while geometry is released or in ephemeral streaming mode (no CPU
+    // meshData to rebuild from — that is phase 3b's evict-to-disk territory).
+    /** Set (or clear) the GPU residency budget in bytes. */
+    setGpuResidencyBudget(bytes) {
+        if (bytes !== null && !(Number.isFinite(bytes) && bytes > 0)) {
+            console.warn('[Scene] ignoring invalid GPU residency budget:', bytes);
+            return;
+        }
+        this.gpuBudgetBytes = bytes;
+        this.residencyOverBudgetWarned = false;
+    }
+    getGpuResidencyBudget() {
+        return this.gpuBudgetBytes;
+    }
+    /** Called once at the start of every Renderer.render() — residency ages
+     *  are measured in RENDERED frames, so idle scenes never age out. */
+    beginResidencyFrame() {
+        this.residencyFrame++;
+    }
+    /** Record that the draw loop drew this batch this frame. */
+    recordBatchDrawn(batch) {
+        if (this.gpuBudgetBytes === null)
+            return;
+        this.lastDrawnFrame.set(batch.id, this.residencyFrame);
+    }
+    /**
+     * The draw loop wants an evicted batch back on the GPU. Queues its bucket
+     * for a time-budgeted rebuild in processResidencyRestores (driven by the
+     * app's animation loop) — the batch is skipped this frame and pops back in
+     * within a frame or two.
+     */
+    requestBatchResidency(batch) {
+        const bucket = this.buckets.get(batch.colorKey);
+        if (!bucket || bucket.batchedMesh !== batch)
+            return;
+        // Warm (CPU kept) OR cold (disk-restorable) — both are restorable.
+        if (bucket.meshData.length > 0 || this.coldBuckets.has(bucket.key)) {
+            this.residencyRestoreQueue.add(bucket.key);
+        }
+    }
+    hasResidencyRestoreWork() {
+        return this.residencyRestoreQueue.size > 0;
+    }
+    /**
+     * Rebuild evicted batches from their buckets' CPU meshData, up to
+     * `budgetMs` per call (same time-slicing philosophy as flushPending).
+     * Returns the number of batches restored.
+     */
+    processResidencyRestores(device, pipeline, budgetMs = 6) {
+        if (this.residencyRestoreQueue.size === 0)
+            return 0;
+        const start = performance.now();
+        let restored = 0;
+        for (const key of this.residencyRestoreQueue) {
+            this.residencyRestoreQueue.delete(key);
+            const bucket = this.buckets.get(key);
+            const old = bucket?.batchedMesh;
+            // Only restore a still-evicted bucket batch — a recolour/finalize may
+            // have rebuilt (or emptied) it in the meantime.
+            if (!bucket || !old || old.gpuResident !== false)
+                continue;
+            // Cold bucket: geometry is on disk — kick off the async provider fetch
+            // (it re-queues the key as warm when the meshes land).
+            if (bucket.meshData.length === 0) {
+                if (this.coldBuckets.has(key))
+                    this.startColdRestore(key);
+                continue;
+            }
+            const rebuilt = this.createBatchedMesh(bucket.meshData, bucket.meshData[0].color, device, pipeline, key);
+            bucket.batchedMesh = rebuilt;
+            const idx = this.batchedMeshes.indexOf(old);
+            if (idx >= 0)
+                this.batchedMeshes[idx] = rebuilt;
+            else
+                this.batchedMeshes.push(rebuilt);
+            this.lastDrawnFrame.delete(old.id);
+            // Seed as just-drawn so the budget pass can't evict it before the
+            // frame that asked for it gets to draw it.
+            this.lastDrawnFrame.set(rebuilt.id, this.residencyFrame);
+            restored++;
+            if (performance.now() - start >= budgetMs)
+                break;
+        }
+        return restored;
+    }
+    // ─── Cold tier (issue #1682 phase 3b) ──────────────────────────────────
+    /** Wire the cold-storage source (v13 cache chunks). Null disables the tier. */
+    setColdGeometryProvider(provider) {
+        this.coldProvider = provider;
+    }
+    /**
+     * Enable LOD1 builds (issue #1682 phase 5): bucket batches built from now
+     * on (finalize, rebuild, residency restore) get a simplified second index
+     * range when it pays. Set BEFORE geometry loads; streaming fragments and
+     * partial/overlay sub-batches never build LOD.
+     */
+    setLodBuildsEnabled(enabled) {
+        this.lodBuildsEnabled = enabled;
+    }
+    /**
+     * Enable 12-byte lattice-quantized batch vertices (issue #1682 phase 6).
+     * ONLY call after the renderer verified its quantized pipeline variants
+     * exist (see Renderer.enableQuantizedBatches) — quantized buffers are
+     * undrawable without them. Applies to batches built from now on; every
+     * createBatchedMesh output (buckets, fragments, partial + override
+     * batches) quantizes onto the SAME 2^-10 lattice, so depth-equal overlay
+     * matching and cross-batch coincidence are preserved bit-exactly. Batches
+     * whose extent exceeds the u16 lattice range fall back to f32 silently.
+     */
+    setQuantizedBatches(enabled) {
+        this.quantizedBatchesEnabled = enabled;
+    }
+    /**
+     * Whether THIS mesh's source batch renders quantized — drives the
+     * hydrated-mesh lattice snap in createMeshFromData (a mesh whose batch
+     * fell back to f32, e.g. >64m extent, must NOT snap). Falls back to the
+     * global flag when the mesh isn't bucketed (mid-stream hydration).
+     */
+    isMeshQuantized(meshData) {
+        if (!this.quantizedBatchesEnabled)
+            return false;
+        const bucket = this.meshDataBucket.get(meshData);
+        if (bucket?.batchedMesh)
+            return bucket.batchedMesh.quantized !== undefined;
+        return true;
+    }
+    /** Set (or clear) the HOST budget in bytes for bucket CPU geometry. */
+    setHostResidencyBudget(bytes) {
+        if (bytes !== null && !(Number.isFinite(bytes) && bytes > 0)) {
+            console.warn('[Scene] ignoring invalid host residency budget:', bytes);
+            return;
+        }
+        this.hostBudgetBytes = bytes;
+        this.hostOverBudgetWarned = false;
+    }
+    /** CPU bytes held by bucket meshData (positions + normals + indices). */
+    getResidentCpuBytes() {
+        let total = 0;
+        for (const bucket of this.buckets.values()) {
+            for (const md of bucket.meshData) {
+                total += md.positions.byteLength + md.normals.byteLength + md.indices.byteLength;
+            }
+        }
+        return total;
+    }
+    /** A bucket whose content diverged from what the cache entry holds
+     *  (recolour / move / removal) must never be cold-evicted: restoring it
+     *  from disk would resurrect the pre-edit geometry. */
+    markBucketDirty(key) {
+        this.dirtyBuckets.add(key);
+    }
+    /**
+     * Demote warm buckets (GPU-evicted, CPU kept) to cold (shell only) until
+     * bucket CPU bytes fit the host budget. Same LRU policy as the GPU tier.
+     * Eligibility is strict: pristine, non-overflow ("#N" sub-buckets are
+     * excluded — their piece membership cannot be re-derived unambiguously),
+     * GPU-evicted, provider present. Cold eviction removes the bucket's meshes
+     * from meshDataMap/meshDataBucket too — that is what actually frees the
+     * typed arrays.
+     */
+    enforceHostBudget() {
+        const budget = this.hostBudgetBytes;
+        if (budget === null || !this.coldProvider)
+            return;
+        if (this.geometryReleased || this.ephemeralStreamingMode)
+            return;
+        if (this.streamingFragments.length > 0)
+            return;
+        const residentBytes = this.getResidentCpuBytes();
+        if (residentBytes <= budget)
+            return;
+        const shells = [];
+        for (const bucket of this.buckets.values()) {
+            const b = bucket.batchedMesh;
+            if (!b || b.gpuResident !== false)
+                continue; // hot buckets stay warm-skippable
+            if (bucket.meshData.length === 0)
+                continue; // already cold
+            if (bucket.key.includes('#'))
+                continue; // overflow sub-bucket
+            if (this.dirtyBuckets.has(bucket.key))
+                continue; // diverged from disk
+            // Colour-merged meshes (per-vertex entityIds) are registered in
+            // meshDataMap under EVERY contained id; evicting only the primary id's
+            // entry would leave the typed arrays reachable (no memory freed) and a
+            // later restore would duplicate the object. Ineligible.
+            let colorMerged = false;
+            let bytes = 0;
+            for (const md of bucket.meshData) {
+                if (md.entityIds && md.entityIds.length > 0) {
+                    colorMerged = true;
+                    break;
+                }
+                bytes += md.positions.byteLength + md.normals.byteLength + md.indices.byteLength;
+            }
+            if (colorMerged)
+                continue;
+            shells.push({
+                key: bucket.key,
+                bytes,
+                lastDrawnFrame: this.lastDrawnFrame.get(b.id) ?? -1,
+            });
+        }
+        const evictKeys = selectEvictions(shells, residentBytes, budget, this.residencyFrame);
+        let evictedBytes = 0;
+        for (const key of evictKeys) {
+            const bucket = this.buckets.get(key);
+            if (!bucket || bucket.meshData.length === 0)
+                continue;
+            for (const md of bucket.meshData) {
+                evictedBytes += md.positions.byteLength + md.normals.byteLength + md.indices.byteLength;
+                this.meshDataBucket.delete(md);
+                // Remove THIS object from the entity's piece list (identity match:
+                // other pieces of the entity may live in other, still-warm buckets).
+                const pieces = this.meshDataMap.get(md.expressId);
+                if (pieces) {
+                    const idx = pieces.indexOf(md);
+                    if (idx >= 0)
+                        pieces.splice(idx, 1);
+                    if (pieces.length === 0)
+                        this.meshDataMap.delete(md.expressId);
+                }
+            }
+            bucket.meshData = [];
+            bucket.vertexBytes = 0;
+            this.coldBuckets.add(key);
+        }
+        if (residentBytes - evictedBytes > budget && !this.hostOverBudgetWarned) {
+            this.hostOverBudgetWarned = true;
+            console.warn(`[Scene] host residency budget ${(budget / 1048576).toFixed(0)}MB exceeded ` +
+                `(${((residentBytes - evictedBytes) / 1048576).toFixed(0)}MB CPU resident) — ` +
+                `remaining buckets are hot, dirty, or overflow sub-buckets. Rendering is unaffected.`);
+        }
+    }
+    /**
+     * Restore EVERY cold bucket to warm (used before the cold provider goes
+     * away, e.g. a federated add invalidates the entry-backed provider while
+     * primary chunks are cold — without this they would be stranded shells).
+     * Resolves when all in-flight restores settle; failures are logged by the
+     * per-bucket restore path and leave those buckets cold.
+     */
+    async drainColdTier() {
+        if (this.coldBuckets.size === 0)
+            return;
+        for (const key of Array.from(this.coldBuckets)) {
+            this.startColdRestore(key);
+        }
+        await Promise.all(Array.from(this.coldRestoresInFlight.values()));
+    }
+    /** Kick off the async disk restore for a cold bucket the draw loop wants.
+     *  On completion the bucket is warm again and re-queued for GPU rebuild. */
+    startColdRestore(key) {
+        if (this.geometryReleased || this.ephemeralStreamingMode)
+            return;
+        if (this.coldRestoresInFlight.has(key))
+            return;
+        const bucket = this.buckets.get(key);
+        const shell = bucket?.batchedMesh;
+        const provider = this.coldProvider;
+        if (!bucket || !shell || !shell.bounds || !provider)
+            return;
+        const promise = provider
+            .loadMeshesInBounds(shell.bounds.min, shell.bounds.max)
+            .then((meshes) => {
+            // Re-validate: a clear()/finalize may have replaced the world.
+            const current = this.buckets.get(key);
+            if (!current || current !== bucket || !this.coldBuckets.has(key))
+                return;
+            const baseKey = this.baseColorKey(key);
+            const idSet = new Set(shell.expressIds);
+            const members = meshes.filter((m) => idSet.has(m.expressId) && this.bucketBaseKey(m) === baseKey);
+            for (const m of members) {
+                bucket.meshData.push(m);
+                bucket.vertexBytes += (m.positions.length / 3) * BATCH_CONSTANTS.BYTES_PER_VERTEX;
+                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);
+            }
+            else {
+                console.warn(`[Scene] cold restore for ${key} found no members — bucket stays a shell`);
+            }
+        })
+            .catch((err) => {
+            console.warn('[Scene] cold restore failed (bucket stays cold, will retry on demand):', err);
+        })
+            .finally(() => {
+            this.coldRestoresInFlight.delete(key);
+        });
+        this.coldRestoresInFlight.set(key, promise);
+    }
+    /**
+     * Synchronously rebuild EVERY evicted bucket batch (no time budget) —
+     * for one-shot capture renders (IDS/clash/BCF snapshots) whose isolation
+     * options may reveal batches that aged out under the budget. The live
+     * view never needs this: visible batches are never evicted. The budget
+     * pass re-evicts unused batches after the usual idle age.
+     * Returns the number of batches restored.
+     */
+    restoreAllEvicted(device, pipeline) {
+        if (this.geometryReleased || this.ephemeralStreamingMode)
+            return 0;
+        let restored = 0;
+        for (const bucket of this.buckets.values()) {
+            const old = bucket.batchedMesh;
+            if (!old || old.gpuResident !== false || bucket.meshData.length === 0)
+                continue;
+            const rebuilt = this.createBatchedMesh(bucket.meshData, bucket.meshData[0].color, device, pipeline, bucket.key);
+            bucket.batchedMesh = rebuilt;
+            const idx = this.batchedMeshes.indexOf(old);
+            if (idx >= 0)
+                this.batchedMeshes[idx] = rebuilt;
+            else
+                this.batchedMeshes.push(rebuilt);
+            this.lastDrawnFrame.delete(old.id);
+            this.lastDrawnFrame.set(rebuilt.id, this.residencyFrame);
+            this.residencyRestoreQueue.delete(bucket.key);
+            restored++;
+        }
+        return restored;
+    }
+    /**
+     * Evict least-recently-drawn bucket batches until the resident set fits
+     * the budget. Called after each frame's submit; destroying just-submitted
+     * buffers is safe (WebGPU defers destruction past in-flight work). Never
+     * evicts a batch drawn this frame — a visible set larger than the budget
+     * renders correctly and stays over budget (warned once).
+     */
+    enforceGpuBudget() {
+        // Host (CPU) tier rides the same post-submit hook on a slow cadence —
+        // warm->cold demotion is not latency-sensitive and the CPU-bytes walk is
+        // O(total meshes).
+        if (this.hostBudgetBytes !== null && --this.hostEnforceCountdown <= 0) {
+            this.hostEnforceCountdown = 120;
+            this.enforceHostBudget();
+        }
+        const budget = this.gpuBudgetBytes;
+        if (budget === null)
+            return;
+        if (this.geometryReleased || this.ephemeralStreamingMode)
+            return;
+        // During streaming the batch set churns (fragments + finalize rebuild
+        // everything anyway) — start enforcing once the scene is stable.
+        if (this.streamingFragments.length > 0)
+            return;
+        let residentBytes = 0;
+        const shells = [];
+        for (const bucket of this.buckets.values()) {
+            const b = bucket.batchedMesh;
+            if (!b || b.gpuResident === false)
+                continue;
+            const bytes = b.vertexBuffer.size + b.indexBuffer.size + (b.uniformBuffer?.size ?? 0)
+                + (b.lod1IndexBuffer?.size ?? 0);
+            residentBytes += bytes;
+            const lastDrawn = this.lastDrawnFrame.get(b.id) ?? -1;
+            if (lastDrawn === this.residencyFrame)
+                continue; // drawn this frame: not evictable
+            if (bucket.meshData.length === 0)
+                continue; // no rebuild source: keep resident
+            shells.push({ key: bucket.key, bytes, lastDrawnFrame: lastDrawn });
+        }
+        if (residentBytes <= budget)
+            return;
+        const evictKeys = selectEvictions(shells, residentBytes, budget, this.residencyFrame);
+        let evictedBytes = 0;
+        for (const key of evictKeys) {
+            const bucket = this.buckets.get(key);
+            const batch = bucket?.batchedMesh;
+            if (!bucket || !batch || batch.gpuResident === false)
+                continue;
+            destroyGpuResources(batch);
+            batch.gpuResident = false;
+            evictedBytes += batch.vertexBuffer.size + batch.indexBuffer.size + (batch.uniformBuffer?.size ?? 0)
+                + (batch.lod1IndexBuffer?.size ?? 0);
+            this.lastDrawnFrame.delete(batch.id);
+            this.dropPartialCacheForBatch(batch);
+        }
+        if (residentBytes - evictedBytes > budget && !this.residencyOverBudgetWarned) {
+            this.residencyOverBudgetWarned = true;
+            console.warn(`[Scene] GPU residency budget ${(budget / 1048576).toFixed(0)}MB exceeded by the ` +
+                `recently-drawn set (${((residentBytes - evictedBytes) / 1048576).toFixed(0)}MB resident) — ` +
+                `nothing old enough to evict. Rendering is unaffected.`);
+        }
+    }
+    /** Destroy + drop cached partial sub-batches derived from `batch` (their
+     *  sourceBatchKeys embed the batch id, so they are stale once it is
+     *  evicted/replaced). */
+    dropPartialCacheForBatch(batch) {
+        const prefix = `${batch.colorKey}:${batch.id}`;
+        for (const [sourceBatchKey, cacheKey] of this.partialBatchCacheKeys) {
+            if (!sourceBatchKey.startsWith(prefix))
+                continue;
+            const cached = this.partialBatchCache.get(cacheKey);
+            if (cached) {
+                destroyGpuResources(cached);
+                this.partialBatchCache.delete(cacheKey);
+            }
+            this.partialBatchCacheKeys.delete(sourceBatchKey);
+        }
+    }
+    /**
+     * Bucket BASE key for a mesh: colour key, prefixed with the mesh's grid
+     * cell when spatial chunking is on. EVERY bucket-key derivation
+     * (streaming append, fragment grouping, finalize re-group, recolour move,
+     * partial-batch piece filter) must go through this so a mesh always
+     * resolves to the same bucket. `color` overrides the mesh's own colour for
+     * recolour routing.
+     */
+    bucketBaseKey(meshData, color) {
+        return bucketBaseKeyFor(meshData, this.colorKey(color ?? meshData.color), this.spatialChunking);
+    }
     /**
      * Store MeshData for lazy GPU buffer creation (used for selection highlighting)
      * This avoids creating 2x GPU buffers during streaming
@@ -430,9 +911,10 @@ export class Scene {
                 }
             }
         }
-        // Route each mesh into a size-aware bucket for its color
+        // Route each mesh into a size-aware bucket for its color (and, with
+        // spatial chunking on, its grid cell)
         for (const meshData of renderable) {
-            const baseKey = this.colorKey(meshData.color);
+            const baseKey = this.bucketBaseKey(meshData);
             const bucketKey = this.resolveActiveBucket(baseKey, meshData);
             if (retainStreamingGeometry || !isStreaming) {
                 // Accumulate mesh data in the bucket when we need later rebatching or
@@ -571,6 +1053,8 @@ export class Scene {
                     bucket.vertexBytes = Math.max(0, bucket.vertexBytes - bytes);
                 }
                 affectedKeys.add(bucket.key);
+                // Entity removal diverges the bucket from the cache entry.
+                this.markBucketDirty(bucket.key);
             }
             this.meshDataBucket.delete(meshData);
         }
@@ -681,6 +1165,47 @@ export class Scene {
      * Translate every flat (non-instanced) mesh for `expressId` by `delta`. See
      * {@link translateMeshesForEntity} for the full contract; this is the flat half.
      */
+    /**
+     * Mark a mesh's bucket for rebuild after its positions were mutated in
+     * place (move/rotate), migrating it to a new bucket when spatial chunking
+     * is on and the mesh crossed a grid-cell boundary. Without the migration
+     * the mesh would keep its stale cell key, so the partial-batch piece
+     * filter (which re-derives keys from CURRENT positions) would silently
+     * drop it under hide/isolate. Same move mechanics as updateMeshColors.
+     */
+    rebucketMovedMesh(meshData, affectedKeys) {
+        const bucket = this.meshDataBucket.get(meshData);
+        if (bucket) {
+            affectedKeys.add(bucket.key);
+            // Moved geometry diverges from the cache entry — see markBucketDirty.
+            this.markBucketDirty(bucket.key);
+        }
+        if (!this.spatialChunking || !bucket)
+            return;
+        const newBaseKey = this.bucketBaseKey(meshData);
+        if (this.baseColorKey(bucket.key) === newBaseKey)
+            return;
+        const newBucketKey = this.resolveActiveBucket(newBaseKey, meshData);
+        this.markBucketDirty(newBucketKey);
+        // Swap-remove from the old bucket + decrement its byte accounting
+        const idx = bucket.meshData.indexOf(meshData);
+        if (idx >= 0) {
+            const last = bucket.meshData.length - 1;
+            if (idx !== last)
+                bucket.meshData[idx] = bucket.meshData[last];
+            bucket.meshData.pop();
+        }
+        const meshBytes = (meshData.positions.length / 3) * BATCH_CONSTANTS.BYTES_PER_VERTEX;
+        bucket.vertexBytes = Math.max(0, bucket.vertexBytes - meshBytes);
+        // Deliberately KEEP an emptied bucket in the map: rebuildPendingBatches
+        // destroys its batchedMesh and deletes the shell. Removing it here would
+        // orphan the live GPU buffers (rebuild skips keys it can't find).
+        // resolveActiveBucket already created the target bucket + tracked bytes
+        const newBucket = this.buckets.get(newBucketKey);
+        newBucket.meshData.push(meshData);
+        this.meshDataBucket.set(meshData, newBucket);
+        affectedKeys.add(newBucketKey);
+    }
     translateFlatMeshesForEntity(expressId, delta) {
         const meshDataList = this.meshDataMap.get(expressId);
         if (!meshDataList || meshDataList.length === 0)
@@ -715,9 +1240,7 @@ export class Scene {
                 pos[i + 1] += dy;
                 pos[i + 2] += dz;
             }
-            const bucket = this.meshDataBucket.get(meshData);
-            if (bucket)
-                affectedKeys.add(bucket.key);
+            this.rebucketMovedMesh(meshData, affectedKeys);
             anyMoved = true;
         }
         if (!anyMoved)
@@ -909,9 +1432,7 @@ export class Scene {
                     nrm[i + 2] = -nx * sin + nz * cos;
                 }
             }
-            const bucket = this.meshDataBucket.get(meshData);
-            if (bucket)
-                affectedKeys.add(bucket.key);
+            this.rebucketMovedMesh(meshData, affectedKeys);
             anyMoved = true;
         }
         if (!anyMoved)
@@ -974,6 +1495,12 @@ export class Scene {
     hasStreamingFragments() {
         return this.streamingFragments.length > 0;
     }
+    /** True while a finalize rebuild (sync or time-sliced) is mid-flight —
+     *  the fragment list is already cleared then, so settle-sensitive callers
+     *  must check BOTH this and hasStreamingFragments(). */
+    isFinalizeInProgress() {
+        return this.finalizeInProgress;
+    }
     /** True when streaming runs in ephemeral mode (huge files) — fragments render
      *  directly from GPU and geometry is NOT retained for re-batch, so callers
      *  must NOT finalize (there's nothing to rebuild the batches from). */
@@ -1048,11 +1575,14 @@ export class Scene {
     createStreamingFragments(meshDataArray, device, pipeline) {
         if (meshDataArray.length === 0)
             return;
-        // Group new meshes by color for efficient fragment batches
+        // Group new meshes by color (and grid cell, when chunking) for efficient
+        // fragment batches. Fragments of one mesh share the PARENT's key: they
+        // are vertex subsets of the same element, and the mesh-never-splits rule
+        // applies to cells exactly like it does to buckets.
         const colorGroups = new Map();
         for (const meshData of meshDataArray) {
+            const key = this.bucketBaseKey(meshData);
             for (const fragment of this.splitMeshForStreaming(meshData)) {
-                const key = this.colorKey(fragment.color);
                 let group = colorGroups.get(key);
                 if (!group) {
                     group = [];
@@ -1134,15 +1664,33 @@ export class Scene {
     finalizeStreaming(device, pipeline) {
         if (this.streamingFragments.length === 0)
             return;
+        this.finalizeInProgress = true;
+        try {
+            this.finalizeStreamingInner(device, pipeline);
+        }
+        finally {
+            this.finalizeInProgress = false;
+        }
+    }
+    finalizeStreamingInner(device, pipeline) {
         // Save references to old fragments/batches — keep them rendering
         // until the new proper batches are fully built (no visual gap).
         const oldFragments = this.streamingFragments;
         const oldBatches = this.batchedMeshes;
         const fragmentSet = new Set(oldFragments);
         this.streamingFragments = [];
-        // 1. Collect ALL accumulated meshData before clearing state
+        // 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 = [];
-        for (const bucket of this.buckets.values()) {
+        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);
         }
@@ -1152,18 +1700,24 @@ export class Scene {
         this.buckets.clear();
         this.meshDataBucket = new Map();
         this.activeBucketKey.clear();
+        this.lastDrawnFrame.clear();
+        this.residencyRestoreQueue.clear();
         this.pendingBatchKeys.clear();
         // Destroy cached partial batches — their colorKeys are now stale
         for (const batch of this.partialBatchCache.values())
             destroyGpuResources(batch);
         this.partialBatchCache.clear();
         this.partialBatchCacheKeys.clear();
-        // 3. Re-group ALL meshData by their CURRENT color.
+        // 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.colorKey(meshData.color);
+            const baseKey = this.bucketBaseKey(meshData);
             const bucketKey = this.resolveActiveBucket(baseKey, meshData);
             let bucket = this.buckets.get(bucketKey);
             if (!bucket) {
@@ -1203,14 +1757,24 @@ export class Scene {
         }
         if (this.streamingFragments.length === 0)
             return Promise.resolve();
+        // Mark the rebuild as in-flight: the preamble empties streamingFragments
+        // synchronously, so settle-sensitive consumers need this flag until the
+        // time-sliced rebuild swaps the new batch array in.
+        this.finalizeInProgress = true;
         // --- Synchronous preamble (fast O(N) bookkeeping) ---
         const oldFragments = this.streamingFragments;
         const oldBatches = this.batchedMeshes;
         const fragmentSet = new Set(oldFragments);
         this.streamingFragments = [];
-        // 1. Collect ALL accumulated meshData
+        // 1. Collect ALL accumulated meshData (cold buckets carried as sealed
+        //    shells — see the sync finalize for the rationale)
         const allMeshData = [];
-        for (const bucket of this.buckets.values()) {
+        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);
         }
@@ -1218,14 +1782,19 @@ export class Scene {
         this.buckets.clear();
         this.meshDataBucket = new Map();
         this.activeBucketKey.clear();
+        this.lastDrawnFrame.clear();
+        this.residencyRestoreQueue.clear();
         this.pendingBatchKeys.clear();
         for (const batch of this.partialBatchCache.values())
             destroyGpuResources(batch);
         this.partialBatchCache.clear();
         this.partialBatchCacheKeys.clear();
-        // 3. Re-group meshData by current color (fast)
+        // Re-seat the carried cold shells in the fresh bucket map.
+        for (const [key, bucket] of carriedCold)
+            this.buckets.set(key, bucket);
+        // 3. Re-group meshData by current color (and grid cell) — fast
         for (const meshData of allMeshData) {
-            const baseKey = this.colorKey(meshData.color);
+            const baseKey = this.bucketBaseKey(meshData);
             const bucketKey = this.resolveActiveBucket(baseKey, meshData);
             let bucket = this.buckets.get(bucketKey);
             if (!bucket) {
@@ -1264,6 +1833,13 @@ export class Scene {
                         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;
                 // Destroy old fragment/batch GPU resources
@@ -1273,6 +1849,7 @@ export class Scene {
                     if (!fragmentSet.has(batch))
                         destroyGpuResources(batch);
                 }
+                scene.finalizeInProgress = false;
                 resolve();
             }
             // Start first chunk immediately (no setTimeout delay)
@@ -1328,6 +1905,10 @@ export class Scene {
         // AABBs already live in boundingBoxes, so bbox-raycast still finds instanced ids.
         this.instancedTemplateCpu = [];
         this.activeBucketKey.clear();
+        this.lastDrawnFrame.clear();
+        this.residencyRestoreQueue.clear();
+        this.coldBuckets.clear();
+        this.dirtyBuckets.clear();
         this.pendingBatchKeys.clear();
         for (const batch of this.partialBatchCache.values())
             destroyGpuResources(batch);
@@ -1410,6 +1991,12 @@ export class Scene {
         }
         this.meshDataBucket = new Map();
         this.activeBucketKey.clear();
+        this.lastDrawnFrame.clear();
+        this.residencyRestoreQueue.clear();
+        // Released mode has no restore source at all — drop the cold tier state
+        // (the geometryReleased guards stop any further cold activity).
+        this.coldBuckets.clear();
+        this.dirtyBuckets.clear();
         // 3. Clear partial batch cache (would need mesh data to rebuild)
         for (const batch of this.partialBatchCache.values())
             destroyGpuResources(batch);
@@ -1450,11 +2037,15 @@ export class Scene {
             const meshDataList = this.meshDataMap.get(expressId);
             if (!meshDataList)
                 continue;
-            const newBaseKey = this.colorKey(newColor);
             for (const meshData of meshDataList) {
+                // Per-mesh, not per-entity: with spatial chunking the base key
+                // carries the mesh's grid cell, which differs between an entity's
+                // pieces. A recolour changes the colour part only — the mesh stays
+                // in its cell.
+                const newBaseKey = this.bucketBaseKey(meshData, newColor);
                 // Use reverse-map for O(1) old bucket lookup
                 const oldBucket = this.meshDataBucket.get(meshData);
-                const oldBucketKey = oldBucket?.key ?? this.colorKey(meshData.color);
+                const oldBucketKey = oldBucket?.key ?? this.bucketBaseKey(meshData);
                 // Derive old color from bucket key, NOT meshData.color.
                 // meshData.color may have been mutated in-place by external code
                 // (applyColorUpdatesToMeshes), making it unreliable for change detection.
@@ -1464,6 +2055,10 @@ export class Scene {
                     const newBucketKey = this.resolveActiveBucket(newBaseKey, meshData);
                     affectedOldKeys.add(oldBucketKey);
                     affectedNewKeys.add(newBucketKey);
+                    // Both buckets now diverge from the cache entry: never cold-evict
+                    // them (a disk restore would resurrect the pre-recolour geometry).
+                    this.markBucketDirty(oldBucketKey);
+                    this.markBucketDirty(newBucketKey);
                     // Remove from old bucket data using indexOf (O(N) within one color bucket, typically <100 items)
                     if (oldBucket) {
                         const idx = oldBucket.meshData.indexOf(meshData);
@@ -1475,9 +2070,12 @@ export class Scene {
                             }
                             oldBucket.meshData.pop();
                         }
-                        if (oldBucket.meshData.length === 0) {
-                            this.buckets.delete(oldBucketKey);
-                        }
+                        // Do NOT delete an emptied bucket here: it is queued in
+                        // affectedOldKeys, and rebuildPendingBatches both destroys its
+                        // batchedMesh GPU buffers and removes the shell. Deleting the
+                        // map entry early orphaned those buffers (rebuild skips keys it
+                        // can't resolve) — a GPU memory leak on every recolour that
+                        // emptied a colour group.
                     }
                     // Decrease old bucket size tracking
                     const meshBytes = (meshData.positions.length / 3) * BATCH_CONSTANTS.BYTES_PER_VERTEX;
@@ -1532,13 +2130,36 @@ export class Scene {
         // Create vertex buffer (interleaved positions + normals)
         // Use mappedAtCreation to avoid a separate writeBuffer IPC round-trip
         // (significant win on Chrome/Dawn where each writeBuffer is a Mojo IPC call)
-        const vertexBuffer = device.createBuffer({
-            size: merged.vertexData.byteLength,
-            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
-            mappedAtCreation: true,
-        });
-        new Float32Array(vertexBuffer.getMappedRange()).set(merged.vertexData);
-        vertexBuffer.unmap();
+        // Quantized path (issue #1682 phase 6): 12-byte lattice records instead
+        // of the 28-byte f32 layout. Falls back to f32 when the batch exceeds
+        // the u16 lattice range. Order note: the LOD build further down reads
+        // merged.vertexData (the CPU f32 copy) and produces INDICES only, which
+        // are valid for either vertex format.
+        let quantized;
+        let vertexBuffer;
+        const quantizedData = this.quantizedBatchesEnabled
+            ? quantizeInterleaved(merged.vertexData, BATCH_CONSTANTS.BYTES_PER_VERTEX / 4)
+            : null;
+        if (quantizedData) {
+            vertexBuffer = device.createBuffer({
+                size: Math.max(4, quantizedData.vertexData.byteLength),
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+                mappedAtCreation: true,
+            });
+            new Uint8Array(vertexBuffer.getMappedRange())
+                .set(new Uint8Array(quantizedData.vertexData));
+            vertexBuffer.unmap();
+            quantized = { min: quantizedData.quantMin, step: quantizedData.step };
+        }
+        else {
+            vertexBuffer = device.createBuffer({
+                size: merged.vertexData.byteLength,
+                usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+                mappedAtCreation: true,
+            });
+            new Float32Array(vertexBuffer.getMappedRange()).set(merged.vertexData);
+            vertexBuffer.unmap();
+        }
         // Create index buffer
         const indexBuffer = device.createBuffer({
             size: merged.indices.byteLength,
@@ -1562,6 +2183,31 @@ export class Scene {
                 },
             ],
         });
+        // LOD1 (issue #1682 phase 5): simplified second index range over the SAME
+        // vertex buffer. Bucket-owned batches only (`bucketKey` present) — the
+        // transient streaming fragments and partial/overlay sub-batches never pay
+        // the build. Positions in `merged.vertexData` are relative to the batch
+        // origin, which is fine: clustering is translation-invariant as long as
+        // the cell size comes from the same-space bounds extent.
+        let lod1IndexBuffer;
+        let lod1IndexCount;
+        if (this.lodBuildsEnabled &&
+            bucketKey !== undefined &&
+            merged.bounds &&
+            merged.indices.length >= LOD_MIN_TRIANGLES * 3) {
+            const cellSize = lodCellSizeForBounds(merged.bounds.min, merged.bounds.max);
+            const lodIndices = simplifyIndicesByClustering(merged.vertexData, BATCH_CONSTANTS.BYTES_PER_VERTEX / 4, merged.indices, cellSize);
+            if (lodIndices) {
+                lod1IndexBuffer = device.createBuffer({
+                    size: lodIndices.byteLength,
+                    usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+                    mappedAtCreation: true,
+                });
+                new Uint32Array(lod1IndexBuffer.getMappedRange()).set(lodIndices);
+                lod1IndexBuffer.unmap();
+                lod1IndexCount = lodIndices.length;
+            }
+        }
         return {
             id: this.nextBatchId++,
             colorKey: bucketKey ?? this.colorKey(color),
@@ -1576,6 +2222,8 @@ export class Scene {
             // Per-batch local frame: positions are stored relative to this; the draw
             // loop applies model = translate(origin) so they land in world space.
             origin: merged.origin,
+            ...(lod1IndexBuffer ? { lod1IndexBuffer, lod1IndexCount } : {}),
+            ...(quantized ? { quantized } : {}),
         };
     }
     /**
@@ -1610,6 +2258,21 @@ export class Scene {
         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++}`;
@@ -1676,8 +2339,11 @@ export class Scene {
             }
         }
         // Collect MeshData for visible elements
-        // Use base color key (strip bucket suffix) for piece filtering, since
-        // meshData stores the original color, not the bucket key.
+        // Use the base key (strip "#N" bucket suffix) for piece filtering, since
+        // meshData stores the original color, not the bucket key. Pieces are
+        // matched through bucketBaseKey so the comparison stays correct with
+        // spatial chunking on (base key = "cell~colour" then, and a piece only
+        // belongs to this batch when BOTH its cell and colour match).
         const baseKey = this.baseColorKey(colorKey);
         const visibleMeshData = [];
         for (const expressId of visibleIds) {
@@ -1685,8 +2351,8 @@ export class Scene {
             if (pieces) {
                 // Add all pieces for this element
                 for (const piece of pieces) {
-                    // Only include pieces that match this batch's color
-                    if (this.colorKey(piece.color) === baseKey) {
+                    // Only include pieces that match this batch's cell + color
+                    if (this.bucketBaseKey(piece) === baseKey) {
                         visibleMeshData.push(piece);
                     }
                 }
@@ -1813,6 +2479,27 @@ export class Scene {
     getTexturedMeshes() {
         return this.texturedMeshes;
     }
+    /**
+     * GPU bytes currently held by the scene's mesh collections (issue #1682
+     * observability). Sums actual `GPUBuffer.size` values across colour batches
+     * (streaming fragments are members of `batchedMeshes`, so they are counted
+     * exactly once), cached partial sub-batches, hydrated individual meshes,
+     * textured meshes (plus a 4 B/texel texture estimate) and instanced
+     * templates. Instanced templates are counted even while hidden in the Types
+     * view: hiding does not free their buffers. O(collections) walk with no GPU
+     * calls, intended for on-demand telemetry, not per-frame use.
+     */
+    getResidentGpuBytes() {
+        return sumResidentGpuBytes({
+            // Evicted batches are metadata shells — their destroyed buffers still
+            // report .size, so they must be excluded from the resident sum.
+            batches: this.batchedMeshes.filter((b) => b.gpuResident !== false),
+            partialBatches: this.partialBatchCache.values(),
+            meshes: this.meshes,
+            textured: this.texturedMeshes,
+            instanced: this.instancedTemplates,
+        });
+    }
     /**
      * Toggle the instanced draw pass. Instanced geometry is class-0 occurrences
      * (the Model view); hide it in the Types view mode, where the flat path shows
@@ -2388,6 +3075,10 @@ export class Scene {
         this.meshDataMap.clear();
         this.boundingBoxes.clear();
         this.activeBucketKey.clear();
+        this.lastDrawnFrame.clear();
+        this.residencyRestoreQueue.clear();
+        this.coldBuckets.clear();
+        this.dirtyBuckets.clear();
         this.cachedMaxBufferSize = 0;
         this.pendingBatchKeys.clear();
         this.partialBatchCache.clear();