gaussian-splat-lite 1.3.0 → 1.3.2

package/dist/types/data/IndexedSplats.d.cts

@@ -9,6 +9,7 @@ type IndexedSplatsOptions = {
   layerSize: number;
   numSh: number;
   blockBits: number;
+  packedOpacityGroups?: boolean;
 };
 type DecodedSplat = ReturnType<typeof decodeSplat>;
 type DecodedSplatWithSh = DecodedSplat & {
@@ -18,7 +19,7 @@ type DecodedSplatWithSh = DecodedSplat & {
  * Fades affect display only: records returned to picking retain their source opacity. */
 export declare abstract class IndexedSplats extends Splats {
   readonly layerSize: number;
-  readonly numSh: 0 | 1 | 2 | 3;
+  readonly numSh: 0 | 1 | 2 | 3 | 4;
   protected readonly opacities: SplatOpacityTable;
   protected sourceIndices: Uint32Array<ArrayBuffer>;
   protected visibleIndices: Uint32Array;
@@ -30,7 +31,13 @@ export declare abstract class IndexedSplats extends Splats {
   private disposed;
   private readonly spatialChunks;
   private spatialBoundsBytes;
-  constructor({ capacity, layerSize, numSh, blockBits }: IndexedSplatsOptions);
+  constructor({
+    capacity,
+    layerSize,
+    numSh,
+    blockBits,
+    packedOpacityGroups,
+  }: IndexedSplatsOptions);
   protected assertLive(): void;
   initialize(options?: SplatsOptions): Promise<Splats>;
   /** Range-based sources can materialize their visible map lazily. */
@@ -48,10 +55,10 @@ export declare abstract class IndexedSplats extends Splats {
   private getStorageIndex;
   getSourceIndex(index: number): number;
   private checkVisibleRange;
-  getNumSh(): 0 | 3 | 2 | 1;
-  private get textureByteLength();
+  getNumSh(): 0 | 1 | 2 | 3 | 4;
+  /** Estimated GPU storage for packed records, render indices and opacity tables. */
+  get textureByteLength(): number;
   getByteLength(): number;
-  get residentBytes(): number;
   private center;
   copySortCenters(
     target: Float32Array,

package/dist/types/data/IndexedSplats.d.ts

@@ -9,6 +9,7 @@ type IndexedSplatsOptions = {
   layerSize: number;
   numSh: number;
   blockBits: number;
+  packedOpacityGroups?: boolean;
 };
 type DecodedSplat = ReturnType<typeof decodeSplat>;
 type DecodedSplatWithSh = DecodedSplat & {
@@ -18,7 +19,7 @@ type DecodedSplatWithSh = DecodedSplat & {
  * Fades affect display only: records returned to picking retain their source opacity. */
 export declare abstract class IndexedSplats extends Splats {
   readonly layerSize: number;
-  readonly numSh: 0 | 1 | 2 | 3;
+  readonly numSh: 0 | 1 | 2 | 3 | 4;
   protected readonly opacities: SplatOpacityTable;
   protected sourceIndices: Uint32Array<ArrayBuffer>;
   protected visibleIndices: Uint32Array;
@@ -30,7 +31,13 @@ export declare abstract class IndexedSplats extends Splats {
   private disposed;
   private readonly spatialChunks;
   private spatialBoundsBytes;
-  constructor({ capacity, layerSize, numSh, blockBits }: IndexedSplatsOptions);
+  constructor({
+    capacity,
+    layerSize,
+    numSh,
+    blockBits,
+    packedOpacityGroups,
+  }: IndexedSplatsOptions);
   protected assertLive(): void;
   initialize(options?: SplatsOptions): Promise<Splats>;
   /** Range-based sources can materialize their visible map lazily. */
@@ -48,10 +55,10 @@ export declare abstract class IndexedSplats extends Splats {
   private getStorageIndex;
   getSourceIndex(index: number): number;
   private checkVisibleRange;
-  getNumSh(): 0 | 3 | 2 | 1;
-  private get textureByteLength();
+  getNumSh(): 0 | 1 | 2 | 3 | 4;
+  /** Estimated GPU storage for packed records, render indices and opacity tables. */
+  get textureByteLength(): number;
   getByteLength(): number;
-  get residentBytes(): number;
   private center;
   copySortCenters(
     target: Float32Array,

package/dist/types/data/RadPagedSplats.d.cts

@@ -19,6 +19,7 @@ export type RadSelectionRange = {
 };
 export type RadSelectionSnapshot = {
   pageCount: number;
+  /** Sixteen two-bit RAD group IDs per word, in source storage order. */
   opacityBlocks: Uint32Array;
   ranges: RadSelectionRange[];
 };

package/dist/types/data/RadPagedSplats.d.ts

@@ -19,6 +19,7 @@ export type RadSelectionRange = {
 };
 export type RadSelectionSnapshot = {
   pageCount: number;
+  /** Sixteen two-bit RAD group IDs per word, in source storage order. */
   opacityBlocks: Uint32Array;
   ranges: RadSelectionRange[];
 };

package/dist/types/data/SplatOpacityTable.d.cts

@@ -1,6 +1,8 @@
 import type * as THREE from "three";
 /** Source blocks hold group IDs; a small float32 table holds their opacities. */
 export declare class SplatOpacityTable {
+  /** Store sixteen two-bit fixed group IDs per word instead of one arbitrary ID. */
+  readonly packedGroups: boolean;
   private blocks;
   private readonly blockSize;
   private readonly blocksPerLayer;
@@ -13,7 +15,12 @@ export declare class SplatOpacityTable {
   private readonly ranges;
   private readonly freeGroups;
   private nextGroup;
-  constructor(capacity: number, layerSize: number, blockBits: number);
+  constructor(
+    capacity: number,
+    layerSize: number,
+    blockBits: number,
+    packedGroups?: boolean,
+  );
   private createTexture;
   private createValueTexture;
   /** CPU arrays and GPU storage each occupy this many bytes. */
@@ -21,7 +28,7 @@ export declare class SplatOpacityTable {
   getOpacity(source: number): number;
   setGroupOpacity(group: number, opacity: number): boolean;
   private releaseBlock;
-  /** Validated ranges retain their group while only its coefficient changes. */
+  /** Unpacked ranges retain their group while only its coefficient changes. */
   setOpacity(start: number, count: number, opacity: number): boolean;
   copyBlocks(): Uint32Array<ArrayBuffer>;
   /** Adopt a prepared RAD table, retaining any uploads still pending. */

package/dist/types/data/SplatOpacityTable.d.ts

@@ -1,6 +1,8 @@
 import type * as THREE from "three";
 /** Source blocks hold group IDs; a small float32 table holds their opacities. */
 export declare class SplatOpacityTable {
+  /** Store sixteen two-bit fixed group IDs per word instead of one arbitrary ID. */
+  readonly packedGroups: boolean;
   private blocks;
   private readonly blockSize;
   private readonly blocksPerLayer;
@@ -13,7 +15,12 @@ export declare class SplatOpacityTable {
   private readonly ranges;
   private readonly freeGroups;
   private nextGroup;
-  constructor(capacity: number, layerSize: number, blockBits: number);
+  constructor(
+    capacity: number,
+    layerSize: number,
+    blockBits: number,
+    packedGroups?: boolean,
+  );
   private createTexture;
   private createValueTexture;
   /** CPU arrays and GPU storage each occupy this many bytes. */
@@ -21,7 +28,7 @@ export declare class SplatOpacityTable {
   getOpacity(source: number): number;
   setGroupOpacity(group: number, opacity: number): boolean;
   private releaseBlock;
-  /** Validated ranges retain their group while only its coefficient changes. */
+  /** Unpacked ranges retain their group while only its coefficient changes. */
   setOpacity(start: number, count: number, opacity: number): boolean;
   copyBlocks(): Uint32Array<ArrayBuffer>;
   /** Adopt a prepared RAD table, retaining any uploads still pending. */

package/dist/types/data/Splats.d.cts

@@ -55,7 +55,7 @@ export declare class Splats {
   getNumSplats(): number;
   /** @internal Copy cached local bounds into the target box. */
   getBoundingBox(centersOnly?: boolean, target?: THREE.Box3): THREE.Box3;
-  getNumSh(): 1 | 2 | 0 | 3;
+  getNumSh(): 0 | 1 | 2 | 3 | 4;
   /** Current retained bytes for encoded Splat, sort-center, and SH arrays. */
   getByteLength(): number;
   /** @internal Consume owned arrays for transfer to a streaming worker. */

package/dist/types/data/Splats.d.ts

@@ -55,7 +55,7 @@ export declare class Splats {
   getNumSplats(): number;
   /** @internal Copy cached local bounds into the target box. */
   getBoundingBox(centersOnly?: boolean, target?: THREE.Box3): THREE.Box3;
-  getNumSh(): 1 | 2 | 0 | 3;
+  getNumSh(): 0 | 1 | 2 | 3 | 4;
   /** Current retained bytes for encoded Splat, sort-center, and SH arrays. */
   getByteLength(): number;
   /** @internal Consume owned arrays for transfer to a streaming worker. */

package/dist/types/data/defines.d.cts

@@ -12,10 +12,12 @@ export declare enum SplatFileType {
   RAD = "rad",
 }
 export type SplatExtra = {
-  sh1?: Uint32Array;
-  sh2?: Uint32Array;
-  sh3a?: Uint32Array;
-  sh3b?: Uint32Array;
+  shBlock0?: Uint32Array;
+  shBlock1?: Uint32Array;
+  shBlock2?: Uint32Array;
+  shBlock3?: Uint32Array;
+  shBlock4?: Uint32Array;
+  shBlock5?: Uint32Array;
 };
 /** Morton storage records per cached spatial bounds block. */
 export declare const SPLAT_BOUNDS_BLOCK_SIZE = 256;

package/dist/types/data/defines.d.ts

@@ -12,10 +12,12 @@ export declare enum SplatFileType {
   RAD = "rad",
 }
 export type SplatExtra = {
-  sh1?: Uint32Array;
-  sh2?: Uint32Array;
-  sh3a?: Uint32Array;
-  sh3b?: Uint32Array;
+  shBlock0?: Uint32Array;
+  shBlock1?: Uint32Array;
+  shBlock2?: Uint32Array;
+  shBlock3?: Uint32Array;
+  shBlock4?: Uint32Array;
+  shBlock5?: Uint32Array;
 };
 /** Morton storage records per cached spatial bounds block. */
 export declare const SPLAT_BOUNDS_BLOCK_SIZE = 256;

package/dist/types/data/splatData.d.cts

@@ -1,6 +1,13 @@
 import type { SplatExtra } from "./defines.cjs";
-export declare const SH_KEYS: readonly ["sh1", "sh2", "sh3a", "sh3b"];
-export declare const SH_ARRAY_COUNTS: readonly [0, 1, 2, 4];
+export declare const SH_KEYS: readonly [
+  "shBlock0",
+  "shBlock1",
+  "shBlock2",
+  "shBlock3",
+  "shBlock4",
+  "shBlock5",
+];
+export declare const SH_ARRAY_COUNTS: readonly [0, 1, 2, 4, 6];
 /** Merge cached min XYZ / max XYZ values without decoding records. */
 export declare function unionSplatBounds(
   target: Float32Array,
@@ -8,7 +15,7 @@ export declare function unionSplatBounds(
   offset?: number,
 ): void;
 export declare function resetSplatBounds(bounds: Float32Array): void;
-export declare function getSplatShDegree(extra: SplatExtra): 1 | 2 | 0 | 3;
+export declare function getSplatShDegree(extra: SplatExtra): 0 | 1 | 2 | 3 | 4;
 /** Packed texture storage; capacity includes padding, but excludes sort centers. */
 export declare function getSplatTextureBytes(
   capacity: number,

package/dist/types/data/splatData.d.ts

@@ -1,6 +1,13 @@
 import type { SplatExtra } from "./defines.js";
-export declare const SH_KEYS: readonly ["sh1", "sh2", "sh3a", "sh3b"];
-export declare const SH_ARRAY_COUNTS: readonly [0, 1, 2, 4];
+export declare const SH_KEYS: readonly [
+  "shBlock0",
+  "shBlock1",
+  "shBlock2",
+  "shBlock3",
+  "shBlock4",
+  "shBlock5",
+];
+export declare const SH_ARRAY_COUNTS: readonly [0, 1, 2, 4, 6];
 /** Merge cached min XYZ / max XYZ values without decoding records. */
 export declare function unionSplatBounds(
   target: Float32Array,
@@ -8,7 +15,7 @@ export declare function unionSplatBounds(
   offset?: number,
 ): void;
 export declare function resetSplatBounds(bounds: Float32Array): void;
-export declare function getSplatShDegree(extra: SplatExtra): 1 | 2 | 0 | 3;
+export declare function getSplatShDegree(extra: SplatExtra): 0 | 1 | 2 | 3 | 4;
 /** Packed texture storage; capacity includes padding, but excludes sort centers. */
 export declare function getSplatTextureBytes(
   capacity: number,

package/dist/types/loaders/postDecode/builder.d.cts

@@ -69,7 +69,7 @@ type AttributeValue<Components extends AttributeComponents> =
         : Vec4Value;
 type SplatShCoefficientContext = {
   index: number;
-  degree: 1 | 2 | 3;
+  degree: 1 | 2 | 3 | 4;
   order: number;
 };
 declare class SplatPostDecodeShPatch {

package/dist/types/loaders/postDecode/builder.d.ts

@@ -69,7 +69,7 @@ type AttributeValue<Components extends AttributeComponents> =
         : Vec4Value;
 type SplatShCoefficientContext = {
   index: number;
-  degree: 1 | 2 | 3;
+  degree: 1 | 2 | 3 | 4;
   order: number;
 };
 declare class SplatPostDecodeShPatch {

package/dist/types/loaders/postDecode/protocol.d.cts

@@ -67,7 +67,7 @@ export declare const InputField: {
 /** @internal */
 export type InputField = (typeof InputField)[keyof typeof InputField];
 /** @internal */
-export declare const SH_COEFFICIENT_COUNT = 15;
+export declare const SH_COEFFICIENT_COUNT = 24;
 /** @internal */
 export type SplatPostDecodeValueType =
   | "float"
@@ -184,8 +184,10 @@ export type PostDecodeSplatData = {
   splat1: Uint32Array;
   sortCenters: Float32Array;
   sourceIds?: Uint32Array;
-  sh1?: Uint32Array;
-  sh2?: Uint32Array;
-  sh3a?: Uint32Array;
-  sh3b?: Uint32Array;
+  shBlock0?: Uint32Array;
+  shBlock1?: Uint32Array;
+  shBlock2?: Uint32Array;
+  shBlock3?: Uint32Array;
+  shBlock4?: Uint32Array;
+  shBlock5?: Uint32Array;
 };

package/dist/types/loaders/postDecode/protocol.d.ts

@@ -67,7 +67,7 @@ export declare const InputField: {
 /** @internal */
 export type InputField = (typeof InputField)[keyof typeof InputField];
 /** @internal */
-export declare const SH_COEFFICIENT_COUNT = 15;
+export declare const SH_COEFFICIENT_COUNT = 24;
 /** @internal */
 export type SplatPostDecodeValueType =
   | "float"
@@ -184,8 +184,10 @@ export type PostDecodeSplatData = {
   splat1: Uint32Array;
   sortCenters: Float32Array;
   sourceIds?: Uint32Array;
-  sh1?: Uint32Array;
-  sh2?: Uint32Array;
-  sh3a?: Uint32Array;
-  sh3b?: Uint32Array;
+  shBlock0?: Uint32Array;
+  shBlock1?: Uint32Array;
+  shBlock2?: Uint32Array;
+  shBlock3?: Uint32Array;
+  shBlock4?: Uint32Array;
+  shBlock5?: Uint32Array;
 };

package/dist/types/loaders/stream/StreamWorkerPool.d.cts

@@ -4,13 +4,10 @@ type StreamWorker = {
   peakWasmMemoryBytes: number;
   dispose(reason?: unknown): void;
 };
-type WorkerLease<W> = {
+type LoadTask<W> = {
   worker: W;
   /** The retained cache handle releases this reference once on disposal. */
   retain: () => () => void;
-  release: () => void;
-};
-type LoadTask<W> = WorkerLease<W> & {
   id: number;
   signal: AbortSignal;
   start: (url: string) => void;

package/dist/types/loaders/stream/StreamWorkerPool.d.ts

@@ -4,13 +4,10 @@ type StreamWorker = {
   peakWasmMemoryBytes: number;
   dispose(reason?: unknown): void;
 };
-type WorkerLease<W> = {
+type LoadTask<W> = {
   worker: W;
   /** The retained cache handle releases this reference once on disposal. */
   retain: () => () => void;
-  release: () => void;
-};
-type LoadTask<W> = WorkerLease<W> & {
   id: number;
   signal: AbortSignal;
   start: (url: string) => void;

package/dist/types/loaders/stream/rad-stream/RadSelectionState.d.cts

@@ -2,22 +2,25 @@ import type { RadMeta } from "../../rad/radFormat.cjs";
 import type { RadStreamSelection } from "./radFade.cjs";
 import type { RadLodRequest, RadLodSelection } from "./radLod.cjs";
 export type RadSelectionRequest = RadLodRequest & {
-  /** Pin both cuts: a waiting cut may become displayed while the RPC runs. */
+  /** Fade baseline: the preparing cut, or the displayed cut when none is pending. */
   previousId?: number;
+  /** Retain the displayed cut if preparation is cancelled. */
+  displayedId?: number;
+  /** Retain a waiting cut that may start preparation while traversal runs. */
   readyId?: number;
   fade?: boolean;
 };
 export type RadSelectionReply = RadStreamSelection & {
   retainedBytes: number;
 };
-/** Worker-owned cuts. Requests pin the displayed and waiting cuts; at most
- * those two plus the new result survive. Replies never transfer cached buffers. */
+/** Worker-owned cuts. Requests pin the baseline, displayed and waiting cuts;
+ * at most those three plus the new result survive. Replies copy cached buffers. */
 export declare class RadSelectionState {
   private readonly cuts;
   private nextId;
   prepare(
     meta: RadMeta,
     selected: RadLodSelection,
-    { previousId, readyId, fade }: RadSelectionRequest,
+    { previousId, displayedId, readyId, fade }: RadSelectionRequest,
   ): RadSelectionReply;
 }

package/dist/types/loaders/stream/rad-stream/RadSelectionState.d.ts

@@ -2,22 +2,25 @@ import type { RadMeta } from "../../rad/radFormat.js";
 import type { RadStreamSelection } from "./radFade.js";
 import type { RadLodRequest, RadLodSelection } from "./radLod.js";
 export type RadSelectionRequest = RadLodRequest & {
-  /** Pin both cuts: a waiting cut may become displayed while the RPC runs. */
+  /** Fade baseline: the preparing cut, or the displayed cut when none is pending. */
   previousId?: number;
+  /** Retain the displayed cut if preparation is cancelled. */
+  displayedId?: number;
+  /** Retain a waiting cut that may start preparation while traversal runs. */
   readyId?: number;
   fade?: boolean;
 };
 export type RadSelectionReply = RadStreamSelection & {
   retainedBytes: number;
 };
-/** Worker-owned cuts. Requests pin the displayed and waiting cuts; at most
- * those two plus the new result survive. Replies never transfer cached buffers. */
+/** Worker-owned cuts. Requests pin the baseline, displayed and waiting cuts;
+ * at most those three plus the new result survive. Replies copy cached buffers. */
 export declare class RadSelectionState {
   private readonly cuts;
   private nextId;
   prepare(
     meta: RadMeta,
     selected: RadLodSelection,
-    { previousId, readyId, fade }: RadSelectionRequest,
+    { previousId, displayedId, readyId, fade }: RadSelectionRequest,
   ): RadSelectionReply;
 }

package/dist/types/loaders/stream/rad-stream/RadStreamLoader.d.cts

@@ -1,7 +1,10 @@
 import type { RadSource, RadSourceOptions } from "../../rad/RadSource.cjs";
 import type { RadHeader, RadStreamChunk } from "../../rad/radFormat.cjs";
 import type { RadSelectionRequest } from "./RadSelectionState.cjs";
-import type { prepareRadSelection } from "./prepareRadSelection.cjs";
+import type {
+  RadSelectionPreparation,
+  prepareRadSelection,
+} from "./prepareRadSelection.cjs";
 import type { RadStreamSelection } from "./radFade.cjs";
 export type RadStreamLoaderOptions = Pick<
   RadSourceOptions,
@@ -13,11 +16,13 @@ export type RadStreamLoaderOptions = Pick<
   | "requestHeader"
   | "withCredentials"
 >;
-/** Dedicated LOD traversal with a separate bounded pool of parallel decoders. */
+/** Separate traversal and display preparation workers, plus bounded page decoders. */
 export declare class RadStreamLoader {
   private readonly options;
+  private readonly onRegistrationSettled;
   readonly source: RadSource;
   private readonly lodWorker;
+  private readonly preparationWorker;
   private readonly pool;
   private readonly decoderReady;
   private readonly controller;
@@ -27,9 +32,15 @@ export declare class RadStreamLoader {
   private initialRoot?;
   private rootBytes?;
   private pending;
+  readonly pendingRegistrationBytes: number;
   private estimatedCodebookBytes;
   private selectionBytes;
-  constructor(options: RadStreamLoaderOptions, maxConcurrentLoads?: number);
+  private preparationBytes;
+  constructor(
+    options: RadStreamLoaderOptions,
+    maxConcurrentLoads: number,
+    onRegistrationSettled: () => void,
+  );
   get stats(): {
     cachedBytes: number;
     downloadedBytes: number;
@@ -38,31 +49,23 @@ export declare class RadStreamLoader {
     bootstrapBytes: number;
     selectionBytes: number;
   };
-  get lodWorkerLost(): boolean;
+  /** Reserve the source cache and codebooks for all decoder workers. */
+  get residentCpuOverheadBytes(): number;
+  get selectionWorkerLost(): boolean;
   private assertActive;
   initialize(signal?: AbortSignal): Promise<RadHeader>;
   loadChunk(
     index: number,
     signal?: AbortSignal,
-    onDecoded?: () => void,
-  ): Promise<RadStreamChunk>;
+  ): Promise<{ data: RadStreamChunk; registration: Promise<void> }>;
   private loadChunkInternal;
   private decode;
+  private registerChunk;
   getChunkUrl(index: number): string;
   selectLod(request: RadSelectionRequest): Promise<RadStreamSelection>;
   prepareSelection(
     request: Parameters<typeof prepareRadSelection>[0],
-  ): Promise<{
-    selection: {
-      indices: Uint32Array;
-      wantedChunks: Uint32Array;
-      touchedChunks: Uint32Array;
-      selectionId: number;
-      changedChunks: Uint32Array;
-    };
-    fade: boolean;
-    pools: import("../../../data/RadPagedSplats.cjs").RadPreparedSelection[];
-  }>;
+  ): Promise<RadSelectionPreparation>;
   releaseChunk(index: number, generation?: number): void;
   dispose(): void;
 }

package/dist/types/loaders/stream/rad-stream/RadStreamLoader.d.ts

@@ -1,7 +1,10 @@
 import type { RadSource, RadSourceOptions } from "../../rad/RadSource.js";
 import type { RadHeader, RadStreamChunk } from "../../rad/radFormat.js";
 import type { RadSelectionRequest } from "./RadSelectionState.js";
-import type { prepareRadSelection } from "./prepareRadSelection.js";
+import type {
+  RadSelectionPreparation,
+  prepareRadSelection,
+} from "./prepareRadSelection.js";
 import type { RadStreamSelection } from "./radFade.js";
 export type RadStreamLoaderOptions = Pick<
   RadSourceOptions,
@@ -13,11 +16,13 @@ export type RadStreamLoaderOptions = Pick<
   | "requestHeader"
   | "withCredentials"
 >;
-/** Dedicated LOD traversal with a separate bounded pool of parallel decoders. */
+/** Separate traversal and display preparation workers, plus bounded page decoders. */
 export declare class RadStreamLoader {
   private readonly options;
+  private readonly onRegistrationSettled;
   readonly source: RadSource;
   private readonly lodWorker;
+  private readonly preparationWorker;
   private readonly pool;
   private readonly decoderReady;
   private readonly controller;
@@ -27,9 +32,15 @@ export declare class RadStreamLoader {
   private initialRoot?;
   private rootBytes?;
   private pending;
+  readonly pendingRegistrationBytes: number;
   private estimatedCodebookBytes;
   private selectionBytes;
-  constructor(options: RadStreamLoaderOptions, maxConcurrentLoads?: number);
+  private preparationBytes;
+  constructor(
+    options: RadStreamLoaderOptions,
+    maxConcurrentLoads: number,
+    onRegistrationSettled: () => void,
+  );
   get stats(): {
     cachedBytes: number;
     downloadedBytes: number;
@@ -38,31 +49,23 @@ export declare class RadStreamLoader {
     bootstrapBytes: number;
     selectionBytes: number;
   };
-  get lodWorkerLost(): boolean;
+  /** Reserve the source cache and codebooks for all decoder workers. */
+  get residentCpuOverheadBytes(): number;
+  get selectionWorkerLost(): boolean;
   private assertActive;
   initialize(signal?: AbortSignal): Promise<RadHeader>;
   loadChunk(
     index: number,
     signal?: AbortSignal,
-    onDecoded?: () => void,
-  ): Promise<RadStreamChunk>;
+  ): Promise<{ data: RadStreamChunk; registration: Promise<void> }>;
   private loadChunkInternal;
   private decode;
+  private registerChunk;
   getChunkUrl(index: number): string;
   selectLod(request: RadSelectionRequest): Promise<RadStreamSelection>;
   prepareSelection(
     request: Parameters<typeof prepareRadSelection>[0],
-  ): Promise<{
-    selection: {
-      indices: Uint32Array;
-      wantedChunks: Uint32Array;
-      touchedChunks: Uint32Array;
-      selectionId: number;
-      changedChunks: Uint32Array;
-    };
-    fade: boolean;
-    pools: import("../../../data/RadPagedSplats.js").RadPreparedSelection[];
-  }>;
+  ): Promise<RadSelectionPreparation>;
   releaseChunk(index: number, generation?: number): void;
   dispose(): void;
 }

package/dist/types/loaders/stream/rad-stream/RadStreamScheduler.d.cts

@@ -3,8 +3,16 @@ import type { StreamResolutionSource } from "../StreamCameras.cjs";
 import type { StreamSchedulerOptions, StreamStats } from "../streamOptions.cjs";
 import type { RadStreamLoaderOptions } from "./RadStreamLoader.cjs";
 export type RadStreamSchedulerOptions = RadStreamLoaderOptions &
-  StreamSchedulerOptions;
+  StreamSchedulerOptions & {
+    /** Allowed fractional splat budget overshoot. Default: 0.1; 0 forbids overshoot. */
+    splatBudgetTolerance?: number;
+    /** Retained CPU byte budget, excluding pending copies and WASM. Default: 2 GiB. */
+    maxResidentCpuBytes?: number;
+    /** Estimated GPU byte budget for resident streaming data. Default: 1 GiB. */
+    maxResidentGpuBytes?: number;
+  };
 export type RadStreamStats = StreamStats & {
+  /** Resident page limit derived from the smaller CPU/GPU allowance. */
   pageBudget: number;
   lodTimeMs: number;
 };
@@ -17,7 +25,10 @@ export declare class RadStreamScheduler {
   readonly cooldownMs: number;
   readonly fadeDurationMs: number;
   readonly maxConcurrentLoads: number;
+  readonly maxResidentCpuBytes: number;
+  readonly maxResidentGpuBytes: number;
   private _splatBudget;
+  private _splatBudgetTolerance;
   private readonly loader;
   private readonly abort;
   private readonly streamCameras;
@@ -46,9 +57,12 @@ export declare class RadStreamScheduler {
   private resolveFirst;
   private rejectFirst;
   constructor(options: RadStreamSchedulerOptions);
-  /** Selected-node budget. Assigning a new value requests LOD selection. */
+  /** Target selected-node budget. Assigning a new value requests LOD selection. */
   get splatBudget(): number;
   set splatBudget(value: number);
+  /** Allowed fractional budget overshoot; zero forbids overshoot. */
+  get splatBudgetTolerance(): number;
+  set splatBudgetTolerance(value: number);
   /** Cameras that select detail, in registration order. */
   get cameras(): readonly THREE.Camera[];
   hasCamera(camera: THREE.Camera): boolean;
@@ -84,6 +98,7 @@ export declare class RadStreamScheduler {
    * detail any of them needs.
    */
   update(): boolean;
+  private get selectionBaselineId();
   private requestSelection;
   private selectionPagesReady;
   private prepareSelection;
@@ -102,6 +117,7 @@ export declare class RadStreamScheduler {
   private reservePages;
   private uploadPages;
   private releasePage;
+  private isPageRequired;
   private releaseUnused;
   /** Map a raycast hit's rendered index back to its stable file index. */
   getGlobalIndex(mesh: THREE.Object3D, renderedIndex: number): number;