@voluma/vlam 0.2.4 → 0.3.2

package/dist/chunk-loader-DlNwggfG.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-loader-DlNwggfG.js","sources":["../src/lib/loaders/chunk-loader.ts"],"sourcesContent":["import type { SplatData } from '../core/splat-data';\nimport type {\n  LoadWorkerRequest,\n  LoadWorkerResponse,\n  LoadWorkerSource,\n  RadChunkRangeRequest,\n} from './load-worker-protocol';\nimport type { LccChunkParams } from '../formats/lcc/parse-lcc';\nimport {\n  createAbortError,\n  deserializeSplatLoadError,\n  resolveSplatUrl,\n  SplatLoadError,\n  splatFormatForExtension,\n  splatNameExtension,\n  splatUrlExtension,\n  type ChunkFileFormat,\n  type SplatDataFileLoadOptions,\n  type SplatFormat,\n  type SplatInputOptions,\n  type SplatDataFormat,\n  type SplatProgressCallback,\n} from './loading';\n// Inlined worker (blob URL): survives library bundling in any consumer\n// setup, unlike an asset file referenced via `new URL(...)`.\nimport LoadWorker from './load-worker?worker&inline';\n\n/**\n * Formats served by the one-shot worker rather than the streaming one.\n *\n * Both workers are inlined, so their parsers are string literals no bundler can\n * tree-shake. Keeping these three behind a dynamic import is what moves SPZ's\n * ~39 KB ZSTD wasm blob out of the main entry and into a chunk that loads only\n * when one of these formats is actually opened.\n */\nconst ONE_SHOT_FORMATS = new Set<ChunkFileFormat>(['spz', 'splat', 'ksplat']);\n\n/**\n * One worker plus the requests in flight on it.\n *\n * `ChunkLoader` runs two of these - see {@link ChunkLoader} - so the request\n * bookkeeping, cancellation and terminal-failure handling live here once.\n */\nclass WorkerClient {\n  private nextRequestId = 0;\n  private readonly pending = new Map<\n    number,\n    {\n      resolve: (data: SplatData) => void;\n      reject: (error: Error) => void;\n      removeAbortListener?: () => void;\n      onProgress?: SplatProgressCallback;\n    }\n  >();\n  private disposed = false;\n  /** Terminal worker failure; subsequent loads reject instead of hanging. */\n  private workerFailure: SplatLoadError | null = null;\n\n  constructor(private readonly worker: Worker) {\n    this.worker.onmessage = (event: MessageEvent<LoadWorkerResponse>) => {\n      const request = this.pending.get(event.data.id);\n      if (!request) return;\n      if (event.data.type === 'progress') {\n        // Progress does not settle the request; the result still follows.\n        request.onProgress?.(event.data.loaded, event.data.total);\n        return;\n      }\n      this.pending.delete(event.data.id);\n      request.removeAbortListener?.();\n      if (event.data.ok) {\n        request.resolve(event.data.data);\n      } else if (event.data.cancelled) {\n        request.reject(createAbortError('Chunk load was cancelled.'));\n      } else {\n        request.reject(deserializeSplatLoadError(event.data.error));\n      }\n    };\n    // A worker-level failure (a CSP that blocks blob: workers is the common\n    // one in real deployments) must still honour the documented contract:\n    // every rejection is a SplatLoadError or an AbortError, never a bare Error.\n    // There is no per-request URL here - the worker itself died - so `url` is\n    // empty and the failure is not retryable: retrying constructs the same\n    // worker under the same policy.\n    this.worker.onerror = (event?: ErrorEvent | Event) => {\n      if (this.workerFailure) return;\n      const detail =\n        event &&\n        typeof event === 'object' &&\n        'message' in event &&\n        typeof event.message === 'string'\n          ? event.message\n          : '';\n      const failure = new SplatLoadError(\n        detail ? `Chunk loading worker failed. ${detail}` : 'Chunk loading worker failed.',\n        { phase: 'worker', url: '', retryable: false },\n      );\n      this.workerFailure = failure;\n      this.worker.terminate();\n      this.rejectAll(failure);\n    };\n  }\n\n  /** Posts one load to this worker and tracks its pending promise. */\n  request(\n    message: Omit<Extract<LoadWorkerRequest, { type: 'load' }>, 'id'>,\n    signal: AbortSignal | undefined,\n    onProgress?: SplatProgressCallback,\n  ): Promise<SplatData> {\n    if (this.disposed) return Promise.reject(createAbortError('ChunkLoader has been disposed.'));\n    if (signal?.aborted) return Promise.reject(createAbortError('Chunk load was cancelled.'));\n    if (this.workerFailure) return Promise.reject(this.workerFailure);\n\n    const id = this.nextRequestId++;\n    const promise = new Promise<SplatData>((resolve, reject) => {\n      this.pending.set(id, { resolve, reject, ...(onProgress ? { onProgress } : {}) });\n    });\n    if (signal) {\n      // Settle immediately on abort rather than waiting for the worker's\n      // acknowledgement: the worker may be deep in a decode (or may already\n      // have posted a success that is still in the message queue), and a\n      // caller that cancelled must neither receive that stale result nor see\n      // further progress callbacks. The late reply finds no pending entry and\n      // is dropped in `onmessage`.\n      const onAbort = () => {\n        const pending = this.pending.get(id);\n        if (!pending) return;\n        this.pending.delete(id);\n        const cancel: LoadWorkerRequest = { type: 'cancel', id };\n        if (!this.disposed) this.worker.postMessage(cancel);\n        pending.reject(createAbortError('Chunk load was cancelled.'));\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n      const pending = this.pending.get(id);\n      if (pending) pending.removeAbortListener = () => signal.removeEventListener('abort', onAbort);\n    }\n\n    const request: LoadWorkerRequest = { ...message, id };\n    this.worker.postMessage(request);\n    return promise;\n  }\n\n  /** Terminates this worker and rejects its in-flight requests. */\n  dispose(): void {\n    if (this.disposed) return;\n    this.disposed = true;\n    this.worker.terminate();\n    this.rejectAll(createAbortError('ChunkLoader has been disposed.'));\n  }\n\n  private rejectAll(error: Error): void {\n    for (const request of this.pending.values()) {\n      request.removeAbortListener?.();\n      request.reject(error);\n    }\n    this.pending.clear();\n  }\n}\n\n/**\n * Client for the persistent scene/chunk loading workers. Multiple requests\n * may be in flight; each can be cancelled through an `AbortSignal`, which\n * aborts the worker-side fetches (useful when the camera has moved on\n * before a chunk arrived).\n *\n * There are two workers behind this one class. The streaming worker is\n * constructed eagerly and handles everything the LOD paths need; the one-shot\n * worker ({@link ONE_SHOT_FORMATS}) is constructed the first time a `.spz`,\n * `.splat` or `.ksplat` is requested. Both decode off the main thread - the\n * split exists only to keep the one-shot parsers out of the published entry.\n *\n * @example\n * const loader = new ChunkLoader();\n * const chunk = await loader.load('/scene/0_0/', { kind: 'directory' });\n */\nexport class ChunkLoader {\n  private readonly streaming = new WorkerClient(new LoadWorker());\n  /** The in-flight construction; `null` until a one-shot format is requested. */\n  private oneShot: Promise<WorkerClient> | null = null;\n  /** The constructed one-shot client, so `dispose` does not have to await. */\n  private oneShotClient: WorkerClient | null = null;\n  private disposed = false;\n\n  /**\n   * Fetches and decodes one scene file or chunk directory.\n   *\n   * @param url - Scene URL, absolute or relative to the page.\n   * @param options.kind - 'file' (default) selects a parser by extension;\n   * 'directory' decodes an unbundled SOG chunk directory.\n   * @param options.format - Explicit parser; `lcc-bin` additionally needs\n   * `options.lcc` to say which byte range of the file to fetch.\n   * @param options.signal - Abort signal for cancellation; the returned\n   * promise then rejects with a `DOMException` named `AbortError`.\n   * @param options.lcc - Byte-range plumbing for `lcc-bin`. This path exists\n   * for {@link StreamedSplatMesh} and is **not** part of the stable surface;\n   * the type is nameable as `LccChunkParams` on `@voluma/vlam/formats/lcc`.\n   * @param options.rad - Byte-range plumbing for `rad-chunk`, on the same\n   * footing; the type is `RadChunkRangeRequest` on `@voluma/vlam/formats/rad`.\n   * @throws Rejects only with {@link SplatLoadError} (resolve, fetch, decode or\n   * worker failures - `error.phase` says which; a worker that cannot start at\n   * all, e.g. under a CSP that blocks `blob:` workers, reports\n   * `phase: 'worker'`) or an `Error` named `AbortError` (cancellation or\n   * {@link dispose}).\n   */\n  // `async` so a URL or format that will not resolve rejects the returned\n  // promise rather than throwing synchronously into the caller.\n  async load(\n    url: string,\n    options: SplatInputOptions & {\n      kind?: 'file' | 'directory';\n      format?: SplatFormat | 'lcc-bin' | 'rad-chunk';\n      lcc?: LccChunkParams;\n      rad?: RadChunkRangeRequest;\n      sog?: { packShBands: 1 | 2 | 3 };\n      files?: Readonly<Record<string, string>>;\n    } = {},\n  ): Promise<SplatData> {\n    const kind = options.kind ?? 'file';\n    // The worker runs from an inlined blob/data URL, where relative and\n    // root-relative URLs cannot be resolved - make the URL absolute here.\n    const absoluteUrl = resolveSplatUrl(url, options.baseUrl).href;\n    const format = resolveFileFormat(absoluteUrl, kind, options.format ?? 'auto');\n    const data = await this.request(\n      {\n        from: 'url',\n        url: absoluteUrl,\n        kind,\n        ...(options.request ? { request: options.request } : {}),\n      },\n      format,\n      options.signal,\n      options.lcc,\n      options.rad,\n      options.files,\n      options.sog,\n      options.onProgress,\n    );\n    return withSourceFormat(data, format);\n  }\n\n  /**\n   * Decodes a local file (from a file input or a drop) in the worker - the\n   * bytes are read worker-side, so a multi-million-splat decode still never\n   * blocks the main thread.\n   *\n   * Only self-contained files are supported: `.ply`, `.spz`, `.splat`,\n   * `.ksplat` and bundled `.sog`. An unbundled SOG directory needs sibling\n   * fetches and so requires {@link load} with `kind: 'directory'`.\n   *\n   * @param file - The file; its name selects the parser unless `format` is given.\n   * @throws Rejects only with {@link SplatLoadError} (unknown extension, read\n   * or decode failures) or an `Error` named `AbortError` (cancellation or\n   * {@link dispose}).\n   */\n  // `async` so an unknown extension rejects the returned promise rather than\n  // throwing synchronously into the caller.\n  async loadFile(file: File, options: SplatDataFileLoadOptions = {}): Promise<SplatData> {\n    const requested = options.format ?? 'auto';\n    const format: Exclude<SplatFormat, 'auto'> =\n      requested === 'auto'\n        ? splatFormatForExtension(splatNameExtension(file.name), file.name)\n        : requested;\n    const data = await this.request(\n      { from: 'file', file },\n      format,\n      options.signal,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      options.onProgress,\n    );\n    return withSourceFormat(data, format);\n  }\n\n  /** Routes one load to the worker that owns its format. */\n  private request(\n    source: LoadWorkerSource,\n    format: ChunkFileFormat,\n    signal: AbortSignal | undefined,\n    lcc?: LccChunkParams,\n    rad?: RadChunkRangeRequest,\n    files?: Readonly<Record<string, string>>,\n    sog?: { packShBands: 1 | 2 | 3 },\n    onProgress?: SplatProgressCallback,\n  ): Promise<SplatData> {\n    if (this.disposed) return Promise.reject(createAbortError('ChunkLoader has been disposed.'));\n    if (signal?.aborted) return Promise.reject(createAbortError('Chunk load was cancelled.'));\n\n    const message: Omit<Extract<LoadWorkerRequest, { type: 'load' }>, 'id'> = {\n      type: 'load',\n      source,\n      format,\n      ...(lcc ? { lcc } : {}),\n      ...(rad ? { rad } : {}),\n      ...(sog ? { sog } : {}),\n      ...(files ? { files } : {}),\n      ...(onProgress ? { progress: true } : {}),\n    };\n\n    const client = this.clientFor(format);\n    // Deliberately not `async`: for a streaming format the client is already\n    // there, and the request must reach the worker in the same task the caller\n    // made it - a chunk scheduler that posts and then aborts within one frame\n    // depends on that ordering. Only the one-shot path, which cannot avoid\n    // awaiting its chunk, defers.\n    if (!(client instanceof Promise)) return client.request(message, signal, onProgress);\n    return client.then((resolved) => {\n      // Re-checked because disposal or abort may have happened while the\n      // one-shot chunk was in flight, before any listener was registered.\n      if (this.disposed) throw createAbortError('ChunkLoader has been disposed.');\n      return resolved.request(message, signal, onProgress);\n    });\n  }\n\n  /**\n   * The worker for `format`, constructing the one-shot worker on first need.\n   *\n   * The in-flight promise is cached, not just the resolved client, so two\n   * concurrent `.spz` loads share one worker instead of racing to build two.\n   */\n  private clientFor(format: ChunkFileFormat): WorkerClient | Promise<WorkerClient> {\n    if (!ONE_SHOT_FORMATS.has(format)) return this.streaming;\n    if (this.oneShotClient) return this.oneShotClient;\n    this.oneShot ??= import('./one-shot-worker?worker&inline').then(\n      ({ default: OneShotWorker }) => {\n        const client = new WorkerClient(new OneShotWorker());\n        this.oneShotClient = client;\n        // `dispose()` may have run while the chunk was in flight; it could not\n        // terminate a worker that did not exist yet, so honour it here.\n        if (this.disposed) client.dispose();\n        return client;\n      },\n    );\n    return this.oneShot;\n  }\n\n  /** Terminates both workers and rejects all in-flight requests. */\n  dispose(): void {\n    if (this.disposed) return;\n    this.disposed = true;\n    this.streaming.dispose();\n    // A one-shot worker still being imported is terminated in `clientFor`,\n    // which sees `disposed` when it finally constructs it.\n    this.oneShotClient?.dispose();\n  }\n}\n\n/** Self-contained scene formats {@link SplatData.format} can hold. */\nconst SOURCE_FORMATS: readonly SplatDataFormat[] = ['ply', 'spz', 'splat', 'ksplat', 'sog', 'rad'];\n\n/**\n * Stamps the resolved format onto decoded scene data so {@link SplatMesh} can\n * pick its `orientation: 'y-up'` correction. Chunk-only formats (`lcc-bin`,\n * `rad-chunk`) carry no self-contained frame, so they are left unstamped.\n */\nfunction withSourceFormat(data: SplatData, format: ChunkFileFormat): SplatData {\n  return (SOURCE_FORMATS as readonly string[]).includes(format)\n    ? { ...data, format: format as SplatDataFormat }\n    : data;\n}\n\nfunction resolveFileFormat(\n  url: string,\n  kind: 'file' | 'directory',\n  format: SplatFormat | 'lcc-bin' | 'rad-chunk',\n): ChunkFileFormat {\n  // An LCC or RAD chunk is a byte range of a shared file, so its extension says\n  // nothing about the parser - the caller's choice is authoritative.\n  if (format === 'lcc-bin' || format === 'rad-chunk') return format;\n  if (kind === 'directory') return 'sog';\n  if (format !== 'auto') return format;\n  return splatFormatForExtension(splatUrlExtension(new URL(url)), url);\n}\n"],"names":["ONE_SHOT_FORMATS","WorkerClient","worker","__publicField","event","request","_a","_b","createAbortError","deserializeSplatLoadError","detail","failure","SplatLoadError","message","signal","onProgress","id","promise","resolve","reject","onAbort","pending","cancel","error","ChunkLoader","LoadWorker","url","options","kind","absoluteUrl","resolveSplatUrl","format","resolveFileFormat","data","withSourceFormat","file","requested","splatFormatForExtension","splatNameExtension","source","lcc","rad","files","sog","client","resolved","OneShotWorker","SOURCE_FORMATS","splatUrlExtension"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/dist/{compute-sorter.d.ts → core/compute-sorter.d.ts}

@@ -2,7 +2,7 @@ import * as THREE from 'three/webgpu';
 import type { SplatSorter } from './sorter';
 import type { uniformArray } from 'three/tsl';
 /**
- * Optional per-source world transform for a unified {@link SplatScene} pool.
+ * Optional per-source world transform for a unified {@link MergedSplatMesh} pool.
  * When present, each splat's center is transformed to world space by its
  * source's matrix (selected by a per-splat id read from `sourceIdTexture`)
  * before its depth is computed, so clouds with different world transforms sort

package/dist/core/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * VLAM! | a WebGPU-first 3D Gaussian Splatting renderer for three.js.
+ *
+ * Public API surface. Everything else under `src/lib/` is internal and may
+ * change without notice.
+ *
+ * Optional systems live on dedicated subpaths so an application that only draws a
+ * fully loaded mesh does not pay for workers, schedulers, or work buffers:
+ *  - `@voluma/vlam/loaders` - {@link loadSplatData}, {@link ChunkLoader}
+ *  - `@voluma/vlam/static-lod` - {@link StaticLodSplatMesh}
+ *  - `@voluma/vlam/streaming` - {@link StreamedSplatMesh}, budget governors
+ *  - `@voluma/vlam/unified` - {@link UnifiedSplatMesh}
+ *  - `@voluma/vlam/selection` - volume select and partition
+ *  - `@voluma/vlam/effects` - tree-shakeable modifier presets
+ *  - `@voluma/vlam/formats/ply` - 3DGS `.ply`, raw and compressed
+ *  - `@voluma/vlam/formats/sog` - PlayCanvas SOG, bundled and unbundled
+ *  - `@voluma/vlam/formats/rad` - Spark `.rad`/`.radc`
+ *  - `@voluma/vlam/formats/lcc` - XGRIDS LCC / `.lcc2` + collision helpers
+ *  - `@voluma/vlam/formats/spz` - Niantic `.spz`
+ *  - `@voluma/vlam/formats/splat` - antimatter15 `.splat`
+ *  - `@voluma/vlam/formats/ksplat` - mkkellogg `.ksplat`
+ *
+ * {@link loadSplatData} / {@link StreamedSplatMesh.load} still accept those formats
+ * without importing a format subpath; the library loads format code on demand.
+ *
+ * @module core
+ */
+export { SplatMesh, MAX_SH_BANDS, DEFAULT_FOVEATION_TARGET_PX, DEFAULT_FOVEATION_DRAW_BUDGET, resolveSplatPerformanceProfile, type UnifiedSourceView, type SplatMeshOptions, type SplatUpdateOptions, type SplatSortStrategy, type SplatPerformanceProfile, type SplatFoveationMode, type SplatRange, type SplatPickOptions, type SplatPickResult, type SplatNearestResult, type SplatRayResult, type SplatHeightResult, type SplatChannelType, type SplatChannelOptions, } from './splat-mesh';
+export { SplatPool, type SplatPoolOptions } from './splat-mesh-pool';
+export { SPLAT_DATA_TEXTURE_WIDTH, deviceMaxTextureSize, assertPoolRowsFitDevice, } from './splat-mesh-pool';
+export { MAX_DOF_RADIUS_PX, MAX_DOF_VARIANCE, apertureAngleFromSize, computeDofCocVariancePx2, computeDofOpacityFade, clampDepthOfFieldSettings, type DepthOfFieldSettings, } from './depth-of-field';
+export { DEFAULT_RELIGHT_BLEND, DEFAULT_RELIGHT_BRIGHTNESS, DEFAULT_RELIGHT_BACKGROUND, DEFAULT_RELIGHT_SOFTNESS, clampRelightingSettings, createPlaceholderRelightTexture, type RelightingSettings, type RelightingUniforms, } from './relighting';
+export { type SplatOrientation, type OrientableFormat, createYUpTransform, yUpTransformForFormat, } from './orientation';
+export { MergedSplatMesh, type MergedSplatMeshOptions, type MergedSplatSourceOptions, } from './merged-splat-mesh';
+export { MAX_MERGED_SPLAT_SOURCES } from './source-transform';
+export type { SplatShInputs, Vec3Uniform } from './splat-mesh-material';
+export { resolveSplatBudget, detectSplatDeviceProfile, classifySplatGpuClass, probeSplatGpuClass, isFillConstrainedSplatDevice, recommendedMaxPixelRatio, recommendedRadMaxStdDev, recommendedXrFramebufferScale, resolveXrSplatBudget, suggestAdaptivePixelRatio, ADAPTIVE_PIXEL_RATIO_WARMUP_FRAMES, estimateSplatPoolBytes, type SplatBudgetOptions, type SplatCostClass, type SplatDeviceProfile, type SplatGpuClass, type SplatGpuAdapterInfo, type AdaptivePixelRatioInput, type AdaptivePixelRatioResult, type SplatPoolBytesOptions, } from './splat-budget';
+export { xrSessionInit } from './xr-view';
+export { createSplatRenderer, type CreateSplatRendererOptions, type SplatRendererGpu, type SplatRendererGpuAdapter, type SplatRendererGpuDevice, } from './create-splat-renderer';
+export { recommendedWebGpuRequiredLimits, supportsWebGpuPowerPreference, webGpuPowerPreferenceOptions, deviceMaxStorageBufferBindingSize, assertStorageBufferFitsDevice, WEBGPU_DEFAULT_MAX_STORAGE_BUFFER_BINDING_SIZE, type WebGpuRequiredLimits, type WebGpuPowerPreference, } from './webgpu-limits';
+export type { SplatData, SplatShData, SplatPackedShData } from './splat-data';
+export type { SplatDataFormat, StreamedSplatFormat } from '../loaders/loading';
+export type { SplatModifier, SplatContext, SplatOutputs, ModifierStackTarget, } from './splat-modifier';
+export { ModifierSlots } from './splat-modifier';
+export { setVlamLogHandler, type VlamLogHandler, type VlamLogLevel } from './logging';

package/dist/{splat-scene.d.ts → core/merged-splat-mesh.d.ts}

@@ -6,7 +6,7 @@
  * transparent draw calls, each depth-sorted only within itself, so where the
  * clouds overlap one is painted wholesale in front of the other ("pasted over")
  * - the same artifact PlayCanvas's unified rendering and Spark's accumulator
- * exist to fix. `SplatScene` concatenates every cloud into **one pool** and
+ * exist to fix. `MergedSplatMesh` concatenates every cloud into **one pool** and
  * runs **one global depth sort**, so splats from different clouds interleave
  * correctly, from any angle.
  *
@@ -17,7 +17,7 @@
  * is a handful of uniform writes - a source can be dragged or animated every
  * frame at full rate, at any splat count, with no data re-upload.
  *
- * The placement runs **before** the modifier stack, so a host effect sees each
+ * The placement runs **before** the modifier stack, so an application effect sees each
  * splat where it visually is: an SDF light shape spanning two sources paints
  * one continuous shape, and a reveal sweeps them together. A modifier that
  * wants to travel *with* a moved source reads `ctx.sourceCenter` instead of
@@ -30,27 +30,26 @@
  * Limitations, all inherited from the dynamic pool: sources may not carry
  * palette (SOG `shN`) view-dependent color - per-file palettes cannot be merged
  * - but DC color and per-splat (LCC) SH are fine; all sources share one
- * antialias setting (from the scene options).
+ * antialias setting (from the mesh options).
  *
- * Sources are **static**: {@link addSource} takes a fully-resident
- * {@link SplatData} and copies it once into the pool, so a streaming
- * {@link StreamedSplatMesh} (which swaps its resident LOD cut every frame)
- * cannot be a source yet - keep a streamed main splat separate and unify only
- * the static sources. Streamed sources are ROADMAP M15.4.
+ * Sources are fully decoded {@link SplatData} copied once into the pool.
+ * {@link StreamedSplatMesh} swaps its resident LOD cut every frame, so it cannot
+ * be a merged source. Compose streamed meshes with fully loaded meshes through
+ * {@link UnifiedSplatMesh} instead.
  */
 import * as THREE from 'three/webgpu';
 import { SplatMesh, type SplatMeshOptions } from './splat-mesh';
 import type { SplatData } from './splat-data';
 import { type SplatOrientation } from './orientation';
-/** Construction options for a {@link SplatScene}. */
-export interface SplatSceneOptions extends SplatMeshOptions {
+/** Construction options for a {@link MergedSplatMesh}. */
+export interface MergedSplatMeshOptions extends SplatMeshOptions {
     /** Total pool size in splats - must cover the sum of every source added. */
     capacity: number;
-    /** Maximum number of sources (default {@link MAX_SOURCES}). */
+    /** Maximum number of sources (default {@link MAX_MERGED_SPLAT_SOURCES}). */
     maxSources?: number;
 }
 /** Per-source placement options. */
-export interface AddSourceOptions {
+export interface MergedSplatSourceOptions {
     /**
      * Y-up normalization for this source's data frame, like {@link SplatMesh}'s
      * `orientation`. `'y-up'` (default) applies the format's stand-up correction
@@ -64,13 +63,13 @@ export interface AddSourceOptions {
  *
  * @experimental May change in a minor release.
  */
-export declare class SplatScene extends SplatMesh {
+export declare class MergedSplatMesh extends SplatMesh {
     private readonly matrices;
     private readonly maxSources;
     /** Indexed by source id; holes are left by {@link removeSource}. */
     private readonly sources;
     private nextId;
-    constructor(options: SplatSceneOptions);
+    constructor(options: MergedSplatMeshOptions);
     /** Number of live sources. */
     get sourceCount(): number;
     /**
@@ -81,7 +80,7 @@ export declare class SplatScene extends SplatMesh {
      *
      * @throws if the pool cannot fit the cloud, or the source limit is reached.
      */
-    addSource(data: SplatData, placement?: THREE.Matrix4, options?: AddSourceOptions): number;
+    addSource(data: SplatData, placement?: THREE.Matrix4, options?: MergedSplatSourceOptions): number;
     /**
      * Re-places a source. Cheap by design: only the shared matrix uniform and the
      * sort bound change, so it is safe to call every frame while dragging.

package/dist/{orientation.d.ts → core/orientation.d.ts}

@@ -1,23 +1,23 @@
 import * as THREE from 'three/webgpu';
 /**
- * How a loaded scene is oriented into the three.js Y-up world.
+ * How a loaded capture is oriented into the three.js Y-up world.
  *
  * - `'y-up'` (default): VLAM normalizes every known format to three.js Y-up -
  *   the OpenCV-frame formats (PLY/`.splat`/`.ksplat`/SOG/`.rad`) are flipped
  *   180° about X, SPZ is already Y-up, and LCC carries its own Z-up→Y-up matrix.
  *   "Drop a file and it stands up", matching engine viewers (PlayCanvas, Babylon).
- * - `'source'`: no cosmetic correction - the scene renders in its data frame,
- *   matching raw Spark / mkkellogg. A host that manages orientation itself (e.g.
- *   swapping viewers while keeping one stored per-scene rotation) uses this.
+ * - `'source'`: keep the native/source coordinate frame. No cosmetic 180°-X flip.
+ *   An application that manages orientation itself (for example swapping viewers
+ *   while keeping one stored per-capture rotation) uses this.
  *
- * Note LCC's Z-up→Y-up matrix is *format semantics*, not a cosmetic default: it
- * is applied in **both** modes (Spark applies it too). Only the 180°-X flip for
+ * LCC's Z-up→Y-up matrix is format semantics, not a cosmetic default: it is
+ * applied in **both** modes (Spark applies it too). Only the 180°-X flip for
  * the Y-down formats is gated by this option.
  */
 export type SplatOrientation = 'y-up' | 'source';
 /**
  * Formats {@link yUpTransformForFormat} understands: the self-contained scene
- * formats ({@link SplatData.sourceFormat}) plus the streamed ones.
+ * formats ({@link SplatData.format}) plus the streamed ones.
  */
 export type OrientableFormat = 'ply' | 'splat' | 'ksplat' | 'sog' | 'spz' | 'rad' | 'streamed-sog' | 'lcc' | 'lcc2';
 /**

package/dist/{relighting.d.ts → core/relighting.d.ts}

@@ -3,7 +3,7 @@
  *
  * Host lights a proxy mesh into an RGBA render target (RGB = lit color,
  * A = coverage), then {@link SplatMesh.setRelighting} /
- * {@link UnifiedSplatRenderer.setRelighting} multiplies baked splat color in
+ * {@link UnifiedSplatMesh.setRelighting} multiplies baked splat color in
  * the display fragment. Not a `SplatModifier` - coverage is per-pixel.
  *
  * See `docs/guide/relighting.md`.

package/dist/{source-transform.d.ts → core/source-transform.d.ts}

@@ -1,5 +1,5 @@
 /**
- * Per-source world transforms for a unified {@link SplatScene} pool.
+ * Per-source world transforms for a unified {@link MergedSplatMesh} pool.
  *
  * Multiple splat clouds are concatenated into one pool in their own local
  * space; each cloud ("source") then carries a world matrix applied **in the
@@ -20,10 +20,10 @@ import * as THREE from 'three/webgpu';
 import { uniformArray } from 'three/tsl';
 /**
  * Maximum number of sources a unified pool can hold. Sized generously - the
- * uniform array costs `4 · MAX_SOURCES` vec4s (16 KB at 256), well under the
+ * uniform array costs `4 · MAX_MERGED_SPLAT_SOURCES` vec4s (16 KB at 256), well under the
  * uniform-buffer limit - while bounding the per-splat index range.
  */
-export declare const MAX_SOURCES = 256;
+export declare const MAX_MERGED_SPLAT_SOURCES = 256;
 /** The channel both the material graph and the sorter read as a source id. */
 export declare const SOURCE_ID_CHANNEL = "sourceId";
 /**
@@ -33,7 +33,7 @@ export declare const SOURCE_ID_CHANNEL = "sourceId";
  * the frame's uniforms - no material or pipeline rebuild.
  */
 export declare class SourceMatrixArray {
-    /** `4 · MAX_SOURCES` vec4 columns; the TSL node both consumers index. */
+    /** `4 · MAX_MERGED_SPLAT_SOURCES` vec4 columns; the TSL node both consumers index. */
     readonly node: ReturnType<typeof uniformArray>;
     /** CPU mirror of the same column-major matrices, for the WebGL2 sorter. */
     readonly matrices: Float32Array;

package/dist/{splat-budget.d.ts → core/splat-budget.d.ts}

@@ -10,7 +10,7 @@
  * pool capacity. Capping the active splat count therefore caps memory
  * directly, which is what matters on mobile GPUs.
  */
-import type { StreamedSplatFormat } from './loading';
+import type { StreamedSplatFormat } from '../loaders/loading';
 /**
  * Desktop GPU capability class for budget / quality defaults.
  *
@@ -256,7 +256,7 @@ export interface SplatPoolBytesOptions {
  * that envelope, it does not shrink it. Price the ceilings before choosing them:
  *
  * ```js
- * // 1 main + 4 markers, each able to reach 1.5M splats
+ * // 1 main + 4 additional meshes, each able to reach 1.5M splats
  * const bytes = estimateSplatPoolBytes(4_000_000) + 4 * estimateSplatPoolBytes(1_500_000);
  * ```
  *

package/dist/{splat-data.d.ts → core/splat-data.d.ts}

@@ -1,4 +1,4 @@
-import type { SplatSourceFormat } from './loading';
+import type { SplatDataFormat } from '../loaders/loading';
 /**
  * CPU-side representation of a set of 3D Gaussians, ready for GPU upload.
  *
@@ -36,7 +36,7 @@ export interface SplatData {
      * Per-splat LOD-tree links for a streamed `.rad` chunk (the merged coarse
      * nodes and leaves are all present in {@link positions} etc.). The streamed
      * reader uses this to pick the rendered cut across chunks; other formats and
-     * the one-shot path leave it undefined. See `parse-rad.ts` and `rad.ts`.
+     * the whole-file path leave it undefined. See `parse-rad.ts` and `rad.ts`.
      */
     readonly radTree?: RadTreeData;
     /**
@@ -52,11 +52,11 @@ export interface SplatData {
     readonly radShCodebook?: RadShCodebook;
     /**
      * The self-contained format this scene was decoded from, stamped by the
-     * loaders ({@link loadScene}/{@link loadSceneFile}). {@link SplatMesh} reads
+     * loaders ({@link loadSplatData}/{@link loadSplatDataFile}). {@link SplatMesh} reads
      * it to pick the `orientation: 'y-up'` correction. Absent on hand-built data
      * and streamed chunks, in which case no orientation is ever inferred.
      */
-    readonly sourceFormat?: SplatSourceFormat;
+    readonly format?: SplatDataFormat;
 }
 /** Palette emitted once in chunk zero by Spark's clustered RAD SH encoding. */
 export interface RadShCodebook {

package/dist/{splat-mesh-material.d.ts → core/splat-mesh-material.d.ts}

@@ -92,7 +92,7 @@ export type SplatShInputs = {
     };
 };
 /**
- * Per-source placement inputs for a unified pool ({@link SplatScene}): the
+ * Per-source placement inputs for a unified pool ({@link MergedSplatMesh}): the
  * splat's source id plus the shared array of source matrices. Drives two things
  * at once - the splat's mesh-local position (`M · poolCenter`, applied before
  * the modifier stack) and the frame view-dependent SH is evaluated in.
@@ -220,7 +220,7 @@ export interface SplatMaterialBuildInputs {
          * `own_size` (from the covariance) and the `parent_size` packed in
          * `covarianceB.w`. See `docs/formats/rad-notes.md` M14.6.
          */
-        foveationMode?: 'band' | 'frontier' | 'pagetable';
+        foveationMode?: 'band' | 'frontier' | 'page-table';
         /**
          * Cap on a rendered splat's major/minor axis ratio (0/undefined = off). Tames
          * far-field needle/spike artifacts from very anisotropic Gaussians and

package/dist/{splat-mesh-types.d.ts → core/splat-mesh-types.d.ts}

@@ -7,6 +7,12 @@ import type { SplatPool } from './splat-mesh-pool';
 import type { SplatShInputs, Vec3Uniform } from './splat-mesh-material';
 /** Construction-time projected-footprint policy selected by a streamed format. */
 export type ProjectedFilterProfile = 'default' | 'lcc';
+/** Canonical `.rad` foveation modes. */
+export type SplatFoveationMode = 'band' | 'frontier' | 'page-table';
+/** Resolve a caller-supplied foveation mode, defaulting when unset. */
+export declare function resolveSplatFoveationMode(mode: SplatFoveationMode | undefined, fallback?: SplatFoveationMode): SplatFoveationMode;
+/** True when the mode is the `.rad` page-table pager. */
+export declare function isPageTableFoveation(mode: string | undefined): boolean;
 /**
  * Opaque handle for a range of splats appended to a {@link SplatMesh},
  * used to remove the range again.
@@ -162,7 +168,7 @@ export interface SplatMeshOptions {
      *   too big and it is small enough (`parentPixelScale > limit ≥ ownPixelScale`),
      *   using per-splat `own_size`/`parent_size`. Full coverage by construction, no
      *   band leapfrogging. Baked into the material graph. See `docs/formats/rad-notes.md`.
-     * - `'pagetable'`: the {@link StreamedSplatMesh} default for `.rad` - a worker
+     * - `'page-table'`: the {@link StreamedSplatMesh} default for `.rad` - a worker
      *   owns the tree traversal and pages only the *selected* frontier into the
      *   pool (Spark's selected-index model), so the whole splat budget buys
      *   on-screen detail. Requires the streamed `.rad` machinery; on a plain
@@ -170,7 +176,7 @@ export interface SplatMeshOptions {
      *
      * @experimental `.rad` foveation option; may change in a minor release.
      */
-    foveationMode?: 'band' | 'frontier' | 'pagetable';
+    foveationMode?: SplatFoveationMode;
     /**
      * Target on-screen size (px) for the frontier / page-table cut: it keeps one
      * LOD level per view ray whose projected node size is about this. Larger =
@@ -205,8 +211,11 @@ export interface SplatMeshOptions {
     maxSplatAspect?: number;
     /**
      * Spark's LOD alpha encoding (`.rad`): the stored opacity is `alpha/2` so the
-     * shader recovers `alpha ∈ [0,2]`, and `alpha > 1` marks a merged node rendered
-     * with a grown σ-cutoff + super-Gaussian falloff. Set for foveated `.rad`.
+     * shader recovers `alpha ∈ [0,2]` from the original texture channel, and
+     * `alpha > 1` marks a merged node rendered with a grown σ-cutoff +
+     * super-Gaussian falloff. Visual fades and alpha modifiers scale the completed
+     * fragment after that classification; they must not change node type or shape.
+     * Set for foveated `.rad`.
      *
      * @experimental `.rad` foveation option; may change in a minor release.
      */
@@ -219,9 +228,9 @@ export interface SplatMeshOptions {
      * cosmetic flip and renders in the data frame (raw Spark / mkkellogg parity);
      * LCC still self-orients (that is format semantics, not part of the switch).
      *
-     * For a static mesh the flip is chosen from {@link SplatData.sourceFormat}
-     * (stamped by the loaders); a dynamic-capacity mesh carries no format, so its
-     * host applies {@link yUpTransformForFormat} itself. See {@link SplatOrientation}.
+     * For a fully loaded mesh the flip is chosen from {@link SplatData.format}
+     * (stamped by the loaders); a dynamic-capacity mesh carries no format, so the
+     * caller applies {@link yUpTransformForFormat} itself. See {@link SplatOrientation}.
      */
     orientation?: SplatOrientation;
     /**
@@ -266,7 +275,7 @@ export interface SplatMeshOptions {
 export type SplatSortStrategy = 'counting' | 'radix' | 'exact';
 /** Controls optional work during a per-frame source update. */
 export interface SplatUpdateOptions {
-    /** Leave sorting to {@link UnifiedSplatRenderer}; uploads and LOD state still update. */
+    /** Leave sorting to {@link UnifiedSplatMesh}; uploads and LOD state still update. */
     sort?: boolean;
 }
 /**
@@ -303,8 +312,8 @@ export interface UnifiedSourceView {
     readonly modifiers: readonly SplatModifier[];
     /**
      * True when this source is itself a unified pool with per-source placement
-     * (`SplatScene`). The gather path cannot resolve nested placement, so
-     * `UnifiedSplatRenderer` rejects these sources.
+     * (`MergedSplatMesh`). The gather path cannot resolve nested placement, so
+     * `UnifiedSplatMesh` rejects these sources.
      */
     readonly hasSourcePlacement: boolean;
     readonly channels: ReadonlyMap<string, {

package/dist/{splat-mesh.d.ts → core/splat-mesh.d.ts}

@@ -133,7 +133,7 @@ export declare class SplatMesh extends THREE.Mesh implements SplatPoolTenant {
     /** Created on the first update, when the renderer backend is known. */
     private sorter;
     /**
-     * Set by a unified {@link SplatScene} subclass before the first sort: makes
+     * Set by a unified {@link MergedSplatMesh} subclass before the first sort: makes
      * the WebGPU sorter transform each splat's center to world space by its
      * source's matrix before measuring depth. `null` for an ordinary mesh, whose
      * sorter is byte-identical to before. See `source-transform.ts`.
@@ -376,7 +376,7 @@ export declare class SplatMesh extends THREE.Mesh implements SplatPoolTenant {
      */
     getUnifiedSourceView(): UnifiedSourceView;
     /**
-     * Marks this mesh as a source drawn by {@link UnifiedSplatRenderer}.
+     * Marks this mesh as a source drawn by {@link UnifiedSplatMesh}.
      * The source stays invisible to the regular scene draw, while its own picker
      * mirrors this resolved visibility so existing per-source hit testing works.
      * Internal consumers should clear the state with `null` before disposing.
@@ -384,7 +384,7 @@ export declare class SplatMesh extends THREE.Mesh implements SplatPoolTenant {
     setUnifiedPickVisibility(visible: boolean | null): void;
     /**
      * The visibility that actually decides whether this mesh's splats reach the
-     * screen: the owning {@link UnifiedSplatRenderer}'s per-source visibility
+     * screen: the owning {@link UnifiedSplatMesh}'s per-source visibility
      * while one owns the draw, else `Object3D.visible`. Consumers that gate on
      * "is this mesh showing" - the picker, `CameraBudgetGovernor` - must read
      * this rather than `visible`, which a unified renderer forces to `false` on
@@ -708,7 +708,7 @@ export declare class SplatMesh extends THREE.Mesh implements SplatPoolTenant {
     /**
      * Refreshes {@link boundingSphereLocal} - the sphere the sorter quantizes
      * depth over - when {@link boundsDirty}. The base mesh uses its local splat
-     * bounds; a unified {@link SplatScene} overrides this to supply a world-space
+     * bounds; a unified {@link MergedSplatMesh} overrides this to supply a world-space
      * bound spanning all its sources (whose transforms live in the shader).
      */
     protected refreshSortBounds(): void;

package/dist/{splat-modifier.d.ts → core/splat-modifier.d.ts}

@@ -9,7 +9,7 @@ export interface SplatContext {
     /**
      * Splat center in mesh-local space (pre-displacement).
      *
-     * Inside a `SplatScene` this is the splat's **placed** position
+     * Inside a `MergedSplatMesh` this is the splat's **placed** position
      * (`sourceMatrix · poolCenter`) - the placement is applied before the stack
      * runs, so effects stay anchored to the scene rather than travelling with a
      * moved source. Use {@link sourceCenter} for the pre-placement position.
@@ -17,14 +17,14 @@ export interface SplatContext {
     readonly localCenter: Node<'vec3'>;
     /**
      * The splat's position in its own source's data frame. Identical to
-     * {@link localCenter} on a plain mesh; inside a `SplatScene` it is the
+     * {@link localCenter} on a plain mesh; inside a `MergedSplatMesh` it is the
      * **pre-placement** position, for effects that should travel *with* a moved
      * source instead of staying put in the scene.
      */
     readonly sourceCenter: Node<'vec3'>;
     /**
      * Linear transform from the source data frame to mesh-local space. This is
-     * identity on a plain mesh; inside a {@link SplatScene} it is the linear part
+     * identity on a plain mesh; inside a {@link MergedSplatMesh} it is the linear part
      * of the source placement. Apply it to source-frame displacement vectors.
      * To express a source-frame rotation `R` as a mesh-local `rotation` output,
      * conjugate it: `sourceToLocal · R · sourceToLocal.inverse()`.
@@ -109,8 +109,8 @@ export interface ModifierStackTarget {
  *  - An **empty slot costs nothing**: it is omitted from the compacted list
  *    entirely, never compiled as a passthrough. All slots empty ⇒ the mesh
  *    gets an empty list ⇒ the unhooked graph (and the unified renderer's
- *    zero-modifier gather fast path stays eligible - except for a `SplatScene`,
- *    which `UnifiedSplatRenderer` does not accept as a source at all).
+ *    zero-modifier gather fast path stays eligible - except for a `MergedSplatMesh`,
+ *    which `UnifiedSplatMesh` does not accept as a source at all).
  *  - {@link apply} hands the mesh a **compacted array whose reference is
  *    stable** while the occupancy is unchanged, so re-applying after
  *    uniform-only changes is a guaranteed no-op on the mesh's identity diff -

package/dist/{webgpu-limits.d.ts → core/webgpu-limits.d.ts}

@@ -19,14 +19,6 @@ export interface WebGpuRequiredLimits {
     maxTextureDimension2D: number;
     [limit: string]: number;
 }
-/** Bytes per splat in the largest unified work-buffer attribute (RGBA32F centers). */
-export declare const WORK_BUFFER_CENTERS_BYTES_PER_SPLAT = 16;
-/**
- * Bytes per work-buffer slot across *all* of its attributes: centers, colors,
- * covarianceA and covarianceB at RGBA32F (16 each), plus the isotropic mix and
- * screen-radius scalars (4 each).
- */
-export declare const WORK_BUFFER_BYTES_PER_SLOT: number;
 /**
  * WebGPU's default `maxStorageBufferBindingSize` when the host does not raise
  * it via `requiredLimits` (128 MiB).
@@ -68,57 +60,6 @@ export declare function supportsWebGpuPowerPreference(nav?: NavigatorPlatformPro
 export declare function webGpuPowerPreferenceOptions(powerPreference?: WebGpuPowerPreference, nav?: NavigatorPlatformProbe): {
     powerPreference: WebGpuPowerPreference;
 } | Record<string, never>;
-/**
- * Byte size of the largest single storage-buffer bind VLAM allocates for a
- * given splat capacity (unified work-buffer centers: `capacity × 16`).
- *
- * Use with adapter/device limits to decide whether to raise `requiredLimits`
- * or lower the budget before constructing {@link UnifiedSplatRenderer}.
- */
-export declare function estimateLargestStorageBufferBytes(capacity: number): number;
-/**
- * Estimates what a {@link UnifiedSplatRenderer}'s work buffer costs, in bytes,
- * once the scene has rendered a frame.
- *
- * This used to be double the figure below, and the doubling was not a detail.
- * Every `THREE.StorageBufferAttribute` is constructed around a JS typed array,
- * and three's WebGPU backend never releases it: the
- * `attribute.onUploadCallback()` call that would is missing from the backend's
- * buffer upload path. So a work buffer of N slots cost
- * N × {@link WORK_BUFFER_BYTES_PER_SLOT} on the GPU *and* the same again on the
- * JS heap, permanently, even though nothing ever reads the CPU copy back - the
- * gather pass writes these buffers entirely on the GPU.
- *
- * `WorkBuffer.releaseCpuMirrors` now drops those mirrors after the first
- * dispatch that uploads them (see `storage-attribute-mirror`), so steady state
- * is the GPU side alone. The *peak* is still double - the array has to exist
- * for the upload copy - which is what
- * {@link estimateUnifiedWorkBufferPeakBytes} reports.
- *
- * Either figure is invisible to `estimateSplatPoolBytes`, which prices the
- * splat *pool* and knows nothing about the unified renderer's scratch space. A
- * host sizing a scene for a memory-constrained device wants both.
- *
- * @param capacity - Work-buffer capacity in splats.
- * @returns Estimated steady-state bytes.
- * @throws {RangeError} if `capacity` is not a non-negative finite number.
- */
-export declare function estimateUnifiedWorkBufferBytes(capacity: number): number;
-/**
- * Peak bytes a {@link UnifiedSplatRenderer}'s work buffer occupies: the window
- * between construction and the first dispatch, while the GPU buffer and the JS
- * array three copied it from are both alive.
- *
- * Ask this one when the question is "will allocating this scene succeed" - an
- * out-of-memory failure happens against the peak. Ask
- * {@link estimateUnifiedWorkBufferBytes} when the question is "what will this
- * scene hold once it is up".
- *
- * @param capacity - Work-buffer capacity in splats.
- * @returns Estimated bytes, GPU plus the not-yet-released CPU mirror.
- * @throws {RangeError} if `capacity` is not a non-negative finite number.
- */
-export declare function estimateUnifiedWorkBufferPeakBytes(capacity: number): number;
 /**
  * The renderer's WebGPU `maxStorageBufferBindingSize`, or 0 when it cannot be
  * read (WebGL2 fallback, or device not yet available). Callers skip the check