@babylonjs/loaders 9.13.0 → 9.15.0

package/SPLAT/gaussianSplattingResidencyController.js

@@ -0,0 +1,222 @@
+import { GaussianSplattingBlockAllocator } from "./gaussianSplattingBlockAllocator.js";
+/**
+ * Tracks which streamed Gaussian Splatting files are resident in the GPU work buffer and where, evicting
+ * unreferenced files after a cooldown to keep the resident set within a fixed budget.
+ *
+ * Built on {@link GaussianSplattingBlockAllocator}: each resident file owns a contiguous block of the work
+ * buffer's splat-index address space. A file with no remaining references is scheduled for eviction; after
+ * `cooldownFrames` ticks (or sooner, if the space is needed by a new allocation — "evict-to-fit") its block
+ * is freed and reused. Pinned files (e.g. the always-rendered environment and the padding splat) are never
+ * evicted. The {@link onEvict} callback fires for every file the controller evicts so the owner can drop its
+ * own bookkeeping (e.g. mark it no longer decoded).
+ *
+ * This controller owns only memory/residency bookkeeping — it has no knowledge of the scene, GPU, downloads,
+ * or reference counting (the caller decides when a file's reference count reaches zero and calls
+ * {@link scheduleEviction}).
+ * @experimental
+ */
+export class GaussianSplattingResidencyController {
+    /**
+     * Creates a residency controller.
+     * @param capacity total splat-index capacity of the work buffer
+     * @param cooldownFrames number of ticks an unreferenced file stays resident before being evicted
+     * @param onEvict called with the file index whenever the controller evicts a file (via tick or evict-to-fit)
+     */
+    constructor(capacity, cooldownFrames, onEvict) {
+        this._blocks = new Map();
+        // file -> frames remaining before eviction (only present for unreferenced, evictable files).
+        this._cooldown = new Map();
+        this._pinned = new Set();
+        this._allocator = new GaussianSplattingBlockAllocator(capacity);
+        this._cooldownFrames = Math.max(0, cooldownFrames);
+        this._onEvict = onEvict;
+    }
+    /**
+     * Total splat-index capacity.
+     */
+    get capacity() {
+        return this._allocator.capacity;
+    }
+    /**
+     * Number of files currently resident.
+     */
+    get residentCount() {
+        return this._blocks.size;
+    }
+    /**
+     * Total free splat capacity (sum of all gaps, which may be fragmented). After {@link compact} an
+     * allocation of up to this size is guaranteed to fit.
+     */
+    get freeSize() {
+        return this._allocator.freeSize;
+    }
+    /**
+     * Whether the given file currently has a block in the work buffer.
+     * @param file file index
+     * @returns true if resident
+     */
+    has(file) {
+        return this._blocks.has(file);
+    }
+    /**
+     * The work-buffer splat offset of a resident file, or undefined if not resident.
+     * @param file file index
+     * @returns the splat offset, or undefined
+     */
+    offset(file) {
+        return this._blocks.get(file)?.offset;
+    }
+    /**
+     * Allocates a contiguous block for a file about to be decoded. If there is no room, evicts files whose
+     * eviction cooldown is pending (they are unreferenced) and retries once. Returns the splat offset, or null
+     * if it still does not fit (the caller should refuse the decode and keep the node's current LOD).
+     * @param file file index
+     * @param count number of splats the file needs
+     * @returns the allocated splat offset, or null if it cannot fit
+     */
+    allocate(file, count) {
+        const existing = this._blocks.get(file);
+        if (existing) {
+            return existing.offset;
+        }
+        let block = this._allocator.allocate(count);
+        if (!block) {
+            // Evict-to-fit: reclaim every unreferenced (cooldown-scheduled) file, then retry once.
+            this._evictAllCooled();
+            block = this._allocator.allocate(count);
+            if (!block) {
+                return null;
+            }
+        }
+        this._blocks.set(file, block);
+        return block.offset;
+    }
+    /**
+     * Allocates a block for a file that must never be evicted (e.g. the environment or padding splat).
+     * @param file file index (use a sentinel that cannot collide with real file indices)
+     * @param count number of splats
+     * @returns the allocated splat offset, or null if it cannot fit
+     */
+    pin(file, count) {
+        const offset = this.allocate(file, count);
+        if (offset !== null) {
+            this._pinned.add(file);
+        }
+        return offset;
+    }
+    /**
+     * Frees a file's block immediately (e.g. when a decode was cancelled before completing). Does not fire
+     * {@link onEvict}. No-op for pinned or non-resident files.
+     * @param file file index
+     */
+    free(file) {
+        if (this._pinned.has(file)) {
+            return;
+        }
+        const block = this._blocks.get(file);
+        if (!block) {
+            return;
+        }
+        this._allocator.free(block);
+        this._blocks.delete(file);
+        this._cooldown.delete(file);
+    }
+    /**
+     * Compacts the resident blocks to defragment free space (capacity is unchanged), returning every block
+     * that moved so the caller can relocate the corresponding GPU/CPU splat data. Call when an allocation
+     * fails despite sufficient total free space ({@link freeSize}); afterwards that allocation will fit.
+     * @returns the relocations to apply (empty when nothing moved)
+     */
+    compact() {
+        const before = new Map();
+        for (const [file, block] of Array.from(this._blocks)) {
+            before.set(file, block.offset);
+        }
+        this._allocator.defrag(0);
+        const moves = [];
+        for (const [file, block] of Array.from(this._blocks)) {
+            const oldOffset = before.get(file);
+            if (oldOffset !== block.offset) {
+                moves.push({ file, oldOffset, newOffset: block.offset, count: block.size });
+            }
+        }
+        return moves;
+    }
+    /**
+     * Returns the current resident blocks (file index, splat offset, splat count). Used to relocate GPU/CPU
+     * data after {@link compact}.
+     * @returns one entry per resident file
+     */
+    getResidentBlocks() {
+        const result = [];
+        for (const [file, block] of Array.from(this._blocks)) {
+            result.push({ file, offset: block.offset, count: block.size });
+        }
+        return result;
+    }
+    /**
+     * Schedules an unreferenced resident file for eviction after the cooldown. No-op for pinned or
+     * non-resident files.
+     * @param file file index
+     */
+    scheduleEviction(file) {
+        if (this._pinned.has(file) || !this._blocks.has(file)) {
+            return;
+        }
+        this._cooldown.set(file, this._cooldownFrames);
+    }
+    /**
+     * Cancels a pending eviction because the file was referenced again.
+     * @param file file index
+     */
+    cancelEviction(file) {
+        this._cooldown.delete(file);
+    }
+    /**
+     * Advances all eviction cooldowns by one frame, evicting any that expire. Each evicted file fires
+     * {@link onEvict}.
+     * @returns the file indices evicted this tick
+     */
+    tick() {
+        if (this._cooldown.size === 0) {
+            return [];
+        }
+        const evicted = [];
+        for (const [file, frames] of Array.from(this._cooldown)) {
+            if (frames <= 1) {
+                evicted.push(file);
+            }
+            else {
+                this._cooldown.set(file, frames - 1);
+            }
+        }
+        for (const file of evicted) {
+            this._evict(file);
+        }
+        return evicted;
+    }
+    /**
+     * Releases all bookkeeping. The allocator and maps are cleared.
+     */
+    dispose() {
+        this._blocks.clear();
+        this._cooldown.clear();
+        this._pinned.clear();
+    }
+    _evictAllCooled() {
+        const files = Array.from(this._cooldown.keys());
+        for (const file of files) {
+            this._evict(file);
+        }
+    }
+    _evict(file) {
+        const block = this._blocks.get(file);
+        if (block) {
+            this._allocator.free(block);
+            this._blocks.delete(file);
+        }
+        this._cooldown.delete(file);
+        this._onEvict(file);
+    }
+}
+//# sourceMappingURL=gaussianSplattingResidencyController.js.map

package/SPLAT/gaussianSplattingResidencyController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaussianSplattingResidencyController.js","sourceRoot":"","sources":["../../../../dev/loaders/src/SPLAT/gaussianSplattingResidencyController.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Nullable } from \"core/types\";\r\nimport { GaussianSplattingBlockAllocator, type GaussianSplattingMemBlock } from \"./gaussianSplattingBlockAllocator\";\r\n\r\n/**\r\n * One resident block relocation produced by {@link GaussianSplattingResidencyController.compact}: the file's\r\n * splat data must be moved from `oldOffset` to `newOffset` (`count` splats) in the work buffer.\r\n */\r\nexport interface IResidencyMove {\r\n    /** File index whose splat data must move. */\r\n    file: number;\r\n    /** The file's previous splat offset in the work buffer. */\r\n    oldOffset: number;\r\n    /** The file's new splat offset after compaction. */\r\n    newOffset: number;\r\n    /** Number of splats in the file. */\r\n    count: number;\r\n}\r\n\r\n/**\r\n * Tracks which streamed Gaussian Splatting files are resident in the GPU work buffer and where, evicting\r\n * unreferenced files after a cooldown to keep the resident set within a fixed budget.\r\n *\r\n * Built on {@link GaussianSplattingBlockAllocator}: each resident file owns a contiguous block of the work\r\n * buffer's splat-index address space. A file with no remaining references is scheduled for eviction; after\r\n * `cooldownFrames` ticks (or sooner, if the space is needed by a new allocation — \"evict-to-fit\") its block\r\n * is freed and reused. Pinned files (e.g. the always-rendered environment and the padding splat) are never\r\n * evicted. The {@link onEvict} callback fires for every file the controller evicts so the owner can drop its\r\n * own bookkeeping (e.g. mark it no longer decoded).\r\n *\r\n * This controller owns only memory/residency bookkeeping — it has no knowledge of the scene, GPU, downloads,\r\n * or reference counting (the caller decides when a file's reference count reaches zero and calls\r\n * {@link scheduleEviction}).\r\n * @experimental\r\n */\r\nexport class GaussianSplattingResidencyController {\r\n    private readonly _allocator: GaussianSplattingBlockAllocator;\r\n    private readonly _blocks = new Map<number, GaussianSplattingMemBlock>();\r\n    // file -> frames remaining before eviction (only present for unreferenced, evictable files).\r\n    private readonly _cooldown = new Map<number, number>();\r\n    private readonly _pinned = new Set<number>();\r\n    private readonly _cooldownFrames: number;\r\n    private readonly _onEvict: (file: number) => void;\r\n\r\n    /**\r\n     * Creates a residency controller.\r\n     * @param capacity total splat-index capacity of the work buffer\r\n     * @param cooldownFrames number of ticks an unreferenced file stays resident before being evicted\r\n     * @param onEvict called with the file index whenever the controller evicts a file (via tick or evict-to-fit)\r\n     */\r\n    public constructor(capacity: number, cooldownFrames: number, onEvict: (file: number) => void) {\r\n        this._allocator = new GaussianSplattingBlockAllocator(capacity);\r\n        this._cooldownFrames = Math.max(0, cooldownFrames);\r\n        this._onEvict = onEvict;\r\n    }\r\n\r\n    /**\r\n     * Total splat-index capacity.\r\n     */\r\n    public get capacity(): number {\r\n        return this._allocator.capacity;\r\n    }\r\n\r\n    /**\r\n     * Number of files currently resident.\r\n     */\r\n    public get residentCount(): number {\r\n        return this._blocks.size;\r\n    }\r\n\r\n    /**\r\n     * Total free splat capacity (sum of all gaps, which may be fragmented). After {@link compact} an\r\n     * allocation of up to this size is guaranteed to fit.\r\n     */\r\n    public get freeSize(): number {\r\n        return this._allocator.freeSize;\r\n    }\r\n\r\n    /**\r\n     * Whether the given file currently has a block in the work buffer.\r\n     * @param file file index\r\n     * @returns true if resident\r\n     */\r\n    public has(file: number): boolean {\r\n        return this._blocks.has(file);\r\n    }\r\n\r\n    /**\r\n     * The work-buffer splat offset of a resident file, or undefined if not resident.\r\n     * @param file file index\r\n     * @returns the splat offset, or undefined\r\n     */\r\n    public offset(file: number): number | undefined {\r\n        return this._blocks.get(file)?.offset;\r\n    }\r\n\r\n    /**\r\n     * Allocates a contiguous block for a file about to be decoded. If there is no room, evicts files whose\r\n     * eviction cooldown is pending (they are unreferenced) and retries once. Returns the splat offset, or null\r\n     * if it still does not fit (the caller should refuse the decode and keep the node's current LOD).\r\n     * @param file file index\r\n     * @param count number of splats the file needs\r\n     * @returns the allocated splat offset, or null if it cannot fit\r\n     */\r\n    public allocate(file: number, count: number): Nullable<number> {\r\n        const existing = this._blocks.get(file);\r\n        if (existing) {\r\n            return existing.offset;\r\n        }\r\n        let block = this._allocator.allocate(count);\r\n        if (!block) {\r\n            // Evict-to-fit: reclaim every unreferenced (cooldown-scheduled) file, then retry once.\r\n            this._evictAllCooled();\r\n            block = this._allocator.allocate(count);\r\n            if (!block) {\r\n                return null;\r\n            }\r\n        }\r\n        this._blocks.set(file, block);\r\n        return block.offset;\r\n    }\r\n\r\n    /**\r\n     * Allocates a block for a file that must never be evicted (e.g. the environment or padding splat).\r\n     * @param file file index (use a sentinel that cannot collide with real file indices)\r\n     * @param count number of splats\r\n     * @returns the allocated splat offset, or null if it cannot fit\r\n     */\r\n    public pin(file: number, count: number): Nullable<number> {\r\n        const offset = this.allocate(file, count);\r\n        if (offset !== null) {\r\n            this._pinned.add(file);\r\n        }\r\n        return offset;\r\n    }\r\n\r\n    /**\r\n     * Frees a file's block immediately (e.g. when a decode was cancelled before completing). Does not fire\r\n     * {@link onEvict}. No-op for pinned or non-resident files.\r\n     * @param file file index\r\n     */\r\n    public free(file: number): void {\r\n        if (this._pinned.has(file)) {\r\n            return;\r\n        }\r\n        const block = this._blocks.get(file);\r\n        if (!block) {\r\n            return;\r\n        }\r\n        this._allocator.free(block);\r\n        this._blocks.delete(file);\r\n        this._cooldown.delete(file);\r\n    }\r\n\r\n    /**\r\n     * Compacts the resident blocks to defragment free space (capacity is unchanged), returning every block\r\n     * that moved so the caller can relocate the corresponding GPU/CPU splat data. Call when an allocation\r\n     * fails despite sufficient total free space ({@link freeSize}); afterwards that allocation will fit.\r\n     * @returns the relocations to apply (empty when nothing moved)\r\n     */\r\n    public compact(): IResidencyMove[] {\r\n        const before = new Map<number, number>();\r\n        for (const [file, block] of Array.from(this._blocks)) {\r\n            before.set(file, block.offset);\r\n        }\r\n        this._allocator.defrag(0);\r\n        const moves: IResidencyMove[] = [];\r\n        for (const [file, block] of Array.from(this._blocks)) {\r\n            const oldOffset = before.get(file)!;\r\n            if (oldOffset !== block.offset) {\r\n                moves.push({ file, oldOffset, newOffset: block.offset, count: block.size });\r\n            }\r\n        }\r\n        return moves;\r\n    }\r\n\r\n    /**\r\n     * Returns the current resident blocks (file index, splat offset, splat count). Used to relocate GPU/CPU\r\n     * data after {@link compact}.\r\n     * @returns one entry per resident file\r\n     */\r\n    public getResidentBlocks(): Array<{ file: number; offset: number; count: number }> {\r\n        const result: Array<{ file: number; offset: number; count: number }> = [];\r\n        for (const [file, block] of Array.from(this._blocks)) {\r\n            result.push({ file, offset: block.offset, count: block.size });\r\n        }\r\n        return result;\r\n    }\r\n\r\n    /**\r\n     * Schedules an unreferenced resident file for eviction after the cooldown. No-op for pinned or\r\n     * non-resident files.\r\n     * @param file file index\r\n     */\r\n    public scheduleEviction(file: number): void {\r\n        if (this._pinned.has(file) || !this._blocks.has(file)) {\r\n            return;\r\n        }\r\n        this._cooldown.set(file, this._cooldownFrames);\r\n    }\r\n\r\n    /**\r\n     * Cancels a pending eviction because the file was referenced again.\r\n     * @param file file index\r\n     */\r\n    public cancelEviction(file: number): void {\r\n        this._cooldown.delete(file);\r\n    }\r\n\r\n    /**\r\n     * Advances all eviction cooldowns by one frame, evicting any that expire. Each evicted file fires\r\n     * {@link onEvict}.\r\n     * @returns the file indices evicted this tick\r\n     */\r\n    public tick(): number[] {\r\n        if (this._cooldown.size === 0) {\r\n            return [];\r\n        }\r\n        const evicted: number[] = [];\r\n        for (const [file, frames] of Array.from(this._cooldown)) {\r\n            if (frames <= 1) {\r\n                evicted.push(file);\r\n            } else {\r\n                this._cooldown.set(file, frames - 1);\r\n            }\r\n        }\r\n        for (const file of evicted) {\r\n            this._evict(file);\r\n        }\r\n        return evicted;\r\n    }\r\n\r\n    /**\r\n     * Releases all bookkeeping. The allocator and maps are cleared.\r\n     */\r\n    public dispose(): void {\r\n        this._blocks.clear();\r\n        this._cooldown.clear();\r\n        this._pinned.clear();\r\n    }\r\n\r\n    private _evictAllCooled(): void {\r\n        const files = Array.from(this._cooldown.keys());\r\n        for (const file of files) {\r\n            this._evict(file);\r\n        }\r\n    }\r\n\r\n    private _evict(file: number): void {\r\n        const block = this._blocks.get(file);\r\n        if (block) {\r\n            this._allocator.free(block);\r\n            this._blocks.delete(file);\r\n        }\r\n        this._cooldown.delete(file);\r\n        this._onEvict(file);\r\n    }\r\n}\r\n"]}

package/SPLAT/gaussianSplattingStream.d.ts

@@ -43,6 +43,12 @@ interface ISOGLODNode {
     inFrustum?: boolean;
     /** Cached local-space bounding info used for the per-node frustum test (created once per leaf). */
     cullBounds?: BoundingInfo;
+    /** File index this node currently has an in-flight/queued decode request for (its not-yet-decoded target),
+     * or undefined when the node's target is already decoded. Drives pending-download reference counting. */
+    pendingFile?: number;
+    /** File index this node's current {@link activeLod} renders from, or undefined before any LOD is active.
+     * Drives the resident reference count that keeps a file in the work buffer. */
+    activeFile?: number;
 }
 /**
  * Parsed contents of a PlayCanvas-style `lod-meta.json` file.
@@ -102,6 +108,28 @@ export interface IGaussianSplattingStreamOptions {
      * the camera turns toward them, then refine. Set to `false` to render every node at its distance LOD.
      */
     frustumCulling?: boolean;
+    /** Maximum number of LOD file downloads allowed to run concurrently. PlayCanvas default `2`. */
+    maxConcurrentDownloads?: number;
+    /** Number of times a failed file download is retried before giving up. PlayCanvas default `2`. */
+    maxDownloadRetries?: number;
+    /**
+     * GPU memory budget (in megabytes) for resident splats. When set (and smaller than the full dataset),
+     * LOD files are streamed through a fixed-size work buffer and unreferenced files are evicted to stay
+     * within budget, allowing datasets larger than a single full-dataset buffer. Converted to a splat count
+     * at ~84 bytes/splat. Combined with {@link maxResidentSplats} by taking the smaller of the two.
+     */
+    memoryBudgetMb?: number;
+    /**
+     * Maximum number of splats kept resident in the work buffer. When set (and smaller than the full
+     * dataset), enables eviction-based streaming (see {@link memoryBudgetMb}). Default unset = size the work
+     * buffer for the whole dataset (no eviction).
+     */
+    maxResidentSplats?: number;
+    /**
+     * Frames an unreferenced (no longer rendered) LOD file stays resident before it is evicted, so a quick
+     * return to it avoids a re-download. Only used when a budget enables eviction. PlayCanvas default `100`.
+     */
+    evictionCooldownFrames?: number;
 }
 /**
  * Streams a PlayCanvas-style SOG LOD scene (`lod-meta.json`) into a single Gaussian Splatting mesh.
@@ -139,12 +167,21 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
     private _useGpuPositionReadback;
     private _readbackCandidate;
     private _readbackProbed;
-    private readonly _fileBaseSplat;
+    private _residency;
     private readonly _fileCounts;
     private readonly _fileMeta;
     private readonly _decodedFiles;
     private readonly _loadingFiles;
     private readonly _decodeQueue;
+    private readonly _fileRefs;
+    private readonly _cancelledDecodes;
+    private _evictionEnabled;
+    private _residentBudget;
+    private _evictionCooldownFrames;
+    private _decodeGate;
+    private readonly _relayoutOldOffsets;
+    private _relayoutSrcIndex;
+    private readonly _downloadManager;
     private _environmentRange;
     private _environmentFiles;
     private _lodObserver;
@@ -177,6 +214,29 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
      */
     constructor(name: string, metadata: ISOGLODMetadata, rootUrl: string, scene: Scene, options?: IGaussianSplattingStreamOptions);
     getClassName(): string;
+    /**
+     * Resolves once the scene is fully streamed and displayed for the current camera: a LOD re-evaluation has
+     * run for the current point of view, every reachable LOD file has finished downloading and decoding (no
+     * downloads, decodes, or queued work remain), and the depth sort for the resulting splats has been applied
+     * and rendered. Intended for deterministic automated testing and screenshot/image comparison.
+     *
+     * Streaming and settling require rendered frames. If an external render loop is already running, this waits
+     * on it passively; otherwise (e.g. when awaited inside an async `createScene` before the host starts its
+     * render loop) it drives `scene.render()` itself until settled, so it never deadlocks.
+     *
+     * Note: the promise only resolves while the camera is still — if the camera keeps moving, the target LODs
+     * (and the depth sort) keep changing and the stream never settles. Position the camera, then await this.
+     * @param stableFrames number of consecutive settled frames to require before resolving (defaults to 3), so
+     *   the final sorted frame is actually on screen
+     * @returns a promise that resolves when loading and rendering are complete for the current view
+     */
+    whenSettledAsync(stableFrames?: number): Promise<void>;
+    /**
+     * Whether the base layer is ready and there is no streaming work in flight (nothing queued for decode, no
+     * decode running, and no downloads pending).
+     * @returns true when no loading work remains
+     */
+    private _isLoadingIdle;
     /**
      * Finest (most detailed) LOD level any node is allowed to render. `0` allows full detail (level 0);
      * `1` caps detail at the next-coarser level, and so on. Nodes already coarser than this cap (by
@@ -324,10 +384,38 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
     /**
      * Loads one LOD source file as GPU textures, decodes it into its fixed work-buffer block, records its
      * CPU centers for sorting, frees the source textures, then promotes any nodes that were waiting for it.
-     * Concurrent or repeat requests for the same file are ignored.
+     * Concurrent or repeat requests for the same file are ignored. If the file is cancelled mid-flight
+     * (because every node that wanted it retargeted), the decode bails cooperatively at the next checkpoint.
      * @param fileId file index to decode
      */
     private _decodeFileAsync;
+    /**
+     * Acquires the decode gate (a simple async mutex). Resolves once any prior holder releases, returning a
+     * release function the caller must invoke in a `finally`.
+     * @returns the release function
+     */
+    private _acquireDecodeGateAsync;
+    /**
+     * Defragments the work buffer to make room for a file that did not fit, then allocates its slot. Runs the
+     * compaction + GPU relayout atomically inside a single `onBeforeRender` so no inconsistent CPU/GPU layout
+     * is ever rendered. Returns the new slot offset, or null if even compaction cannot free enough contiguous
+     * space (the caller refuses the upgrade).
+     * @param fileId file to allocate after compaction
+     * @param count splats the file needs
+     * @returns the allocated offset, or null
+     */
+    private _relayoutAndAllocateAsync;
+    /**
+     * Compacts the resident set and relocates the corresponding GPU textures and CPU positions to the new
+     * layout. Must run at a frame-safe point with the work buffer's relayout shader ready.
+     */
+    private _performRelayout;
+    /**
+     * Drops a file evicted by the residency controller from the decoded set so it will be re-decoded on demand.
+     * The file had no remaining references, so no node was rendering or downloading it.
+     * @param fileId evicted file index
+     */
+    private _onFileEvicted;
     /**
      * Snaps a desired LOD level to the nearest level the node provides, while never selecting a level finer
      * than {@link maxDetailLod} (i.e. with an index below the cap). Ties prefer the finer allowed level. If
@@ -344,11 +432,41 @@ export declare class GaussianSplattingStream extends GaussianSplattingMesh {
     private _computeTargetLevels;
     /**
      * Applies each node's {@link ISOGLODNode.targetLevel}: switches a node to its target level when that
-     * level's file is already decoded, otherwise queues the file and leaves the node on its current LOD (so
-     * nothing ever disappears). Nodes within their post-switch cooldown are left untouched to damp oscillation.
+     * level's file is already decoded, otherwise records a pending download request for the file and leaves
+     * the node on its current LOD (so nothing ever disappears). Nodes within their post-switch cooldown are
+     * left untouched to damp oscillation (and keep their existing pending request).
+     *
+     * Each node tracks the single file it currently needs but lacks ({@link ISOGLODNode.pendingFile}). When a
+     * node's target changes before that file finished downloading, the old file's reference is released; if no
+     * other node still needs it, its queued/in-flight download is cancelled (see {@link _releaseFileRef}).
      * @returns true when at least one node changed LOD (callers should refresh the active ranges)
      */
     private _applyDesiredLods;
+    /**
+     * Moves a node's resident reference from its previous active file to the one it now renders, so the file
+     * count that keeps a block in the work buffer stays accurate (and cancels any pending eviction of the new
+     * file). The new file is already decoded.
+     * @param node leaf node switching its rendered file
+     * @param file the file the node now renders from
+     */
+    private _switchActiveFile;
+    /**
+     * Adds a reference to a file (active render or pending download), cancelling any scheduled eviction.
+     * @param fileId file index
+     */
+    private _acquireFileRef;
+    /**
+     * Records that a node needs a not-yet-decoded file, bumping its reference count and queueing the decode.
+     * @param fileId file index the node now targets
+     */
+    private _acquirePendingFile;
+    /**
+     * Releases a node's reference to a file. When the last reference is dropped: a decoded file is scheduled
+     * for eviction (when streaming under a budget), and a still-downloading file has its queued decode dropped
+     * and any in-flight download cancelled.
+     * @param fileId file index the node no longer references
+     */
+    private _releaseFileRef;
     /**
      * Per-frame LOD streaming loop. Ticks cooldowns and pumps the decode queue every frame, and runs the
      * cheap per-node frustum test every frame so the off-screen LOD bias tracks camera rotation. The LOD