@voluma/vlam 0.1.0 → 0.2.1

package/dist/chunk-cache-budget.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Cross-mesh decoded-chunk cache arbitration.
+ *
+ * Every {@link StreamedSplatMesh} caps its own decoded-chunk cache, and in
+ * `foveationMode: 'pagetable'` that cap is `min(2 GiB, this capture's decoded
+ * size)` - a number sized for *one* streamed scene. A scene of streamed markers
+ * therefore has no ceiling at all: thirteen markers plus a main are thirteen
+ * plus one independent caps, and because each is sized to its own capture, a
+ * desktop that fits them never evicts. The background sweep then runs to
+ * completion against every one of them, pulling every capture in the scene into
+ * RAM and keeping it there.
+ *
+ * This is the missing ceiling, at whole-mesh granularity: one budget shared by
+ * every streamed mesh in a scene (the same sharing model as `SplatPool` and
+ * {@link ChunkFetchScheduler}), splitting a scene total by the same
+ * camera-projected weight a `CameraBudgetGovernor` already computes for drawing.
+ *
+ * It bounds **retention**, not prefetching. The sweep still runs and still warms
+ * the cache; it simply stops at an allowance the whole scene agreed on rather
+ * than at the size of each capture. A mesh the camera approaches gets a larger
+ * allowance and resumes sweeping; one it leaves gives bytes back.
+ *
+ * The budget brokers **bytes**, never chunks: it does not know about
+ * `ChunkLoader`, chunk ids or workers, which is what keeps the eviction policy
+ * where it belongs - inside the frontier worker, which is the only place that
+ * knows what the current cut still needs.
+ */
+/** A streamed mesh, as the cache budget sees it. */
+export interface ChunkCacheClient {
+    /**
+     * This mesh's camera-projected weight - larger means more of the cache.
+     *
+     * Read on demand rather than pushed, so the budget never holds a stale
+     * weight; a `CameraBudgetGovernor.weightOf` call is the intended source, and
+     * is the same one {@link ChunkFetchScheduler} reads. Zero (hidden or
+     * suspended) still keeps `perMeshFloorBytes`: a mesh whose coarse base has
+     * been evicted draws nothing at all when the camera comes back to it.
+     */
+    weight(): number;
+    /**
+     * The most this mesh could ever put to use - for a page-table mesh,
+     * `min(PAGETABLE_CACHE_FLOOR_BYTES, estimateSceneDecodedBytes(scene))`.
+     *
+     * Bytes above it are handed to siblings that can use them, the way
+     * `BudgetGovernor` waterfills past a member's `maxBudget`. Without it a scene
+     * of one large capture and a dozen small markers would reserve most of the
+     * envelope for markers that cannot fill it.
+     */
+    readonly ceilingBytes: number;
+    /**
+     * This mesh's allowance moved. The mesh forwards it to its frontier worker;
+     * nothing is dropped synchronously, because only the worker's own eviction
+     * pass knows which chunks the current cut still needs.
+     */
+    onAllowanceChanged(bytes: number): void;
+}
+/** Options for {@link ChunkCacheBudget}. */
+export interface ChunkCacheBudgetOptions {
+    /**
+     * Decoded-chunk bytes every registered mesh may hold **in total**.
+     *
+     * This is the number that decides whether the budget helps at all. Too low
+     * and the focused mesh re-fetches chunks it just evicted; too high and it is
+     * inert, because each mesh's own `ceilingBytes` becomes binding again. Size
+     * it against the tab's heap, not against any one capture.
+     */
+    totalBytes: number;
+    /**
+     * Bytes each mesh keeps regardless of weight. Default 32 MiB, matching
+     * `resolveCpuCacheBytes`'s own minimum.
+     *
+     * Without a floor a far mesh evicts its own coarse base and re-fetches it on
+     * the next reschedule, forever - the same thrash {@link
+     * ChunkFetchScheduler.perMeshFloor} exists to prevent on the network side.
+     */
+    perMeshFloorBytes?: number;
+    /**
+     * Minimum ms between weight-driven reallocations. Default 250, matching the
+     * idle reschedule interval - there is no point re-splitting faster than the
+     * meshes can act on it. Membership changes bypass it.
+     */
+    minIntervalMs?: number;
+    /**
+     * Relative allowance change below which a mesh is not notified. Default 0.15.
+     *
+     * Every notification is a worker post and, indirectly, an eviction pass. A
+     * camera drifting slowly would otherwise repost a 1% different number every
+     * quarter second for no change in behaviour.
+     */
+    deadband?: number;
+}
+/**
+ * A mesh's registration. Opaque to callers: hold it from {@link
+ * ChunkCacheBudget.register} and pass it back to read the allowance or
+ * unregister.
+ */
+export interface ChunkCacheHandle {
+    readonly client: ChunkCacheClient;
+}
+/** See the module comment. Construct one per scene and pass it to every mesh. */
+export declare class ChunkCacheBudget {
+    private readonly entries;
+    private readonly perMeshFloorBytes;
+    private readonly minIntervalMs;
+    private readonly deadband;
+    private totalBytesValue;
+    private lastAllocationMs;
+    private disposed;
+    constructor(options: ChunkCacheBudgetOptions);
+    /** Bytes shared across every registered mesh. */
+    get totalBytes(): number;
+    /**
+     * Resizes the scene envelope and re-splits immediately. For a host reacting
+     * to a quality change or a device-memory signal.
+     */
+    setTotalBytes(bytes: number): void;
+    /** Meshes currently registered. */
+    get clientCount(): number;
+    /**
+     * Adds a mesh and re-splits at once, so the caller can read its opening
+     * allowance out of {@link allowanceFor} before posting worker init.
+     */
+    register(client: ChunkCacheClient): ChunkCacheHandle;
+    /** Drops a mesh and hands its bytes back to the siblings. */
+    unregister(handle: ChunkCacheHandle): void;
+    /** This mesh's current allowance in bytes, or 0 once unregistered. */
+    allowanceFor(handle: ChunkCacheHandle): number;
+    /**
+     * Re-splits after the camera moved. Call it once per frame, right beside
+     * {@link ChunkFetchScheduler.weightsChanged} - the two read the same weights,
+     * so cache and network follow the same measure.
+     *
+     * Rate-limited and dead-banded; calling it every frame is the intended use.
+     */
+    weightsChanged(now?: number): void;
+    /**
+     * Releases every registration. Meshes are not disposed - the budget is shared
+     * and does not own them, exactly as a shared `SplatPool` does not own its
+     * meshes.
+     */
+    dispose(): void;
+    /**
+     * Cap-aware waterfill: weight-proportional shares, floored so every mesh can
+     * hold its coarse base, clamped at each mesh's `ceilingBytes`, and the surplus
+     * from clamped meshes redistributed over the rest until it settles.
+     *
+     * The invariant callers depend on is `Σ allowance <= totalBytes`. It holds in
+     * every branch, including the degenerate one where the floors alone exceed
+     * the envelope - there the floors are scaled down proportionally rather than
+     * silently overcommitting, because a budget that can be exceeded by
+     * registering more meshes is the bug this class exists to fix.
+     */
+    private allocate;
+    /** Suppresses reposts for changes too small to alter any mesh's behaviour. */
+    private movedEnough;
+}

package/dist/chunk-fetch-scheduler.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Cross-mesh chunk-fetch arbitration.
+ *
+ * Every {@link StreamedSplatMesh} owns its own `ChunkLoader` worker and issues
+ * chunk requests toward its own in-flight cap, so a scene of streamed meshes
+ * fetches with no shared ordering: a marker the camera is pointed at competes
+ * for bandwidth and connection slots against a dozen distant ones, each of
+ * which is equally entitled to its own cap. Spark does not have this problem
+ * structurally - one global traversal orders every fetch want
+ * biggest-on-screen-first through one pager, so its network order *is* its
+ * visual priority.
+ *
+ * This is that ordering at whole-mesh granularity: one scheduler shared by
+ * every streamed mesh in a scene (the same sharing model as `SplatPool`),
+ * handing out a bounded number of fetch slots in proportion to the same
+ * camera-projected weight a `CameraBudgetGovernor` already computes for
+ * drawing. Within a mesh the existing order still applies - a frontier plan's
+ * `touched` list is already sorted biggest-on-screen first - so the two
+ * granularities compose.
+ *
+ * The scheduler brokers **slots**, never fetches: it does not know about
+ * `ChunkLoader`, URLs or workers, which is what keeps a future scene-level
+ * shared loader an independent change.
+ */
+/**
+ * Why a mesh wants a slot. The kind is the mesh's own statement of intent, and
+ * decides what a weightless (hidden, or suspended) mesh may still do:
+ *
+ * - `priority` - detail the frontier asked for and does not have. The chunks
+ *   actually on screen.
+ * - `base` - the camera-directed coarse base, and the pinned coverage every
+ *   deferred swap substitutes from. A far mesh must keep trickling these or it
+ *   has nothing to draw at all.
+ * - `sweep` - the background file-order sweep that pulls a whole capture into
+ *   the worker cache so later camera moves are served from RAM. Pure
+ *   pre-warming: valuable when a mesh is on screen, and the first thing to give
+ *   up when it is not.
+ */
+export type ChunkFetchKind = 'priority' | 'base' | 'sweep';
+/** A streamed mesh, as the scheduler sees it. */
+export interface ChunkFetchClient {
+    /**
+     * This mesh's camera-projected weight - larger means more of the pipe.
+     * Zero means hidden or suspended: such a mesh keeps its floor for `priority`
+     * and `base` work but is denied `sweep` entirely.
+     *
+     * Read on demand rather than pushed, so the scheduler never holds a stale
+     * weight; a `CameraBudgetGovernor.weightOf` call is the intended source.
+     */
+    weight(): number;
+    /**
+     * A slot may now be free. The mesh should re-run its reschedule, which
+     * re-issues whatever it still wants. The scheduler deliberately keeps no
+     * queue of pending requests: the reschedule paths are already idempotent
+     * re-issuers, so a poke carries strictly more current information than a
+     * request recorded when the camera was somewhere else.
+     */
+    onSlotAvailable(): void;
+    /**
+     * Abort in-flight fetches of this kind - the mesh's weight dropped to zero
+     * while it held slots. Aborted fetches release their slots through the normal
+     * path, so this is how a focus change hands the pipe over immediately rather
+     * than after the far meshes' current requests drain.
+     */
+    shedFetches(kind: ChunkFetchKind): void;
+}
+/** Options for {@link ChunkFetchScheduler}. */
+export interface ChunkFetchSchedulerOptions {
+    /**
+     * Total chunk fetches in flight across every registered mesh. Default 16.
+     *
+     * This is the number that decides whether the scheduler helps at all. Too low
+     * and a single mesh scene streams slower than it does today; too high and
+     * there is nothing to arbitrate, because the browser's own queueing (six per
+     * origin on HTTP/1.1; a much larger multiplexed window on HTTP/2) becomes the
+     * real scheduler again - and it orders by request time, not by what is on
+     * screen. Tune it from a measured concurrency high-water mark, not by feel.
+     */
+    maxGlobalInflight?: number;
+    /**
+     * Slots every registered mesh may hold regardless of weight. Default 1.
+     *
+     * Without a floor a scene's far meshes stop fetching entirely while the
+     * focused one streams, and a marker with no coarse coverage draws nothing -
+     * so the floor is what turns "far meshes wait" into "far meshes trickle".
+     *
+     * One slot is always granted regardless of this setting: a mesh entitled to
+     * zero would never fetch and never settle. Set this above 1 to widen every
+     * mesh's guaranteed trickle.
+     */
+    perMeshFloor?: number;
+}
+/**
+ * A mesh's registration. Opaque to callers: hold it from {@link
+ * ChunkFetchScheduler.register} and pass it back to acquire, release and
+ * unregister.
+ */
+export interface ChunkFetchHandle {
+    readonly client: ChunkFetchClient;
+}
+/** See the module comment. Construct one per scene and pass it to every mesh. */
+export declare class ChunkFetchScheduler {
+    private readonly entries;
+    private readonly maxGlobalInflight;
+    private readonly perMeshFloor;
+    private inflightCount;
+    private disposed;
+    constructor(options?: ChunkFetchSchedulerOptions);
+    /** Total slots granted and not yet released. */
+    get inflight(): number;
+    /** Meshes currently registered. */
+    get clientCount(): number;
+    register(client: ChunkFetchClient): ChunkFetchHandle;
+    /**
+     * Drops a mesh. Slots it still holds are released here: a disposing mesh
+     * aborts its fetches, and those aborts land after the handle is gone.
+     */
+    unregister(handle: ChunkFetchHandle): void;
+    /**
+     * Grants a fetch slot, or denies and remembers the demand.
+     *
+     * A denial is not a failure and must not feed a mesh's retry backoff - the
+     * mesh simply did not fetch this tick, and will be woken (or reschedule on
+     * its own within the idle interval) to ask again.
+     */
+    tryAcquire(handle: ChunkFetchHandle, kind: ChunkFetchKind): boolean;
+    /**
+     * Returns a slot. Must be called exactly once for every granted acquire -
+     * on success, on failure **and** on abort - or the pipe leaks capacity until
+     * the scene is torn down.
+     */
+    release(handle: ChunkFetchHandle): void;
+    /**
+     * Re-examines weights after the camera moved. Call it once per frame, right
+     * after the budget governor's own update.
+     *
+     * Meshes that just lost all weight shed their pre-warming sweeps, so a focus
+     * change frees the pipe now rather than when a dozen far requests happen to
+     * finish.
+     */
+    weightsChanged(): void;
+    /**
+     * Releases every registration. Meshes are not disposed - the scheduler is
+     * shared and does not own them, exactly as a shared `SplatPool` does not own
+     * its meshes.
+     */
+    dispose(): void;
+    /**
+     * The most slots this mesh may hold: its weight-proportional share of the
+     * *whole* pipe, floored so it can always trickle and capped so its siblings
+     * can always reach their own floors.
+     *
+     * This is a ceiling, not a reservation. The global cap does the real
+     * limiting, so a heavy mesh can use capacity its idle siblings are leaving on
+     * the table, while a far mesh's ceiling stays at its floor however early it
+     * asks - which is what keeps the first mesh to reschedule from taking the
+     * pipe and holding it. Dividing the *remainder* after every participant's
+     * floor instead would invert the whole point on a large scene: thirteen
+     * markers and a main at floor 1 consume a 16-slot pipe entirely, leaving the
+     * focused marker a smaller share than the far ones it is competing with.
+     *
+     * The denominator counts every mesh that plausibly wants the pipe - all
+     * registered meshes except those both weightless and idle, plus the caller.
+     */
+    private shareFor;
+    /** Pokes the heaviest mesh that was denied since its last grant. */
+    private wake;
+}

package/dist/chunk-loader.d.ts

@@ -0,0 +1,85 @@
+import type { SplatData } from './splat-data';
+import type { RadChunkRangeRequest } from './load-worker-protocol';
+import type { LccChunkParams } from './formats/lcc/parse-lcc';
+import { type SplatFileLoadOptions, type SplatFormat, type SplatInputOptions } from './loading';
+/**
+ * Client for the persistent scene/chunk loading workers. Multiple requests
+ * may be in flight; each can be cancelled through an `AbortSignal`, which
+ * aborts the worker-side fetches (useful when the camera has moved on
+ * before a chunk arrived).
+ *
+ * There are two workers behind this one class. The streaming worker is
+ * constructed eagerly and handles everything the LOD paths need; the one-shot
+ * worker ({@link ONE_SHOT_FORMATS}) is constructed the first time a `.spz`,
+ * `.splat` or `.ksplat` is requested. Both decode off the main thread - the
+ * split exists only to keep the one-shot parsers out of the published entry.
+ *
+ * @example
+ * const loader = new ChunkLoader();
+ * const chunk = await loader.load('/scene/0_0/', { kind: 'directory' });
+ */
+export declare class ChunkLoader {
+    private readonly streaming;
+    /** The in-flight construction; `null` until a one-shot format is requested. */
+    private oneShot;
+    /** The constructed one-shot client, so `dispose` does not have to await. */
+    private oneShotClient;
+    private disposed;
+    /**
+     * Fetches and decodes one scene file or chunk directory.
+     *
+     * @param url - Scene URL, absolute or relative to the page.
+     * @param options.kind - 'file' (default) selects a parser by extension;
+     * 'directory' decodes an unbundled SOG chunk directory.
+     * @param options.format - Explicit parser; `lcc-bin` additionally needs
+     * `options.lcc` to say which byte range of the file to fetch.
+     * @param options.signal - Abort signal for cancellation; the returned
+     * promise then rejects with a `DOMException` named `AbortError`.
+     * @param options.lcc - Byte-range plumbing for `lcc-bin`. This path exists
+     * for {@link StreamedSplatMesh} and is **not** part of the stable surface;
+     * the type is nameable as `LccChunkParams` on `@voluma/vlam/formats/lcc`.
+     * @param options.rad - Byte-range plumbing for `rad-chunk`, on the same
+     * footing; the type is `RadChunkRangeRequest` on `@voluma/vlam/formats/rad`.
+     * @throws Rejects only with {@link SplatLoadError} (resolve, fetch, decode or
+     * worker failures - `error.phase` says which; a worker that cannot start at
+     * all, e.g. under a CSP that blocks `blob:` workers, reports
+     * `phase: 'worker'`) or an `Error` named `AbortError` (cancellation or
+     * {@link dispose}).
+     */
+    load(url: string, options?: SplatInputOptions & {
+        kind?: 'file' | 'directory';
+        format?: SplatFormat | 'lcc-bin' | 'rad-chunk';
+        lcc?: LccChunkParams;
+        rad?: RadChunkRangeRequest;
+        sog?: {
+            packShBands: 1 | 2 | 3;
+        };
+        files?: Readonly<Record<string, string>>;
+    }): Promise<SplatData>;
+    /**
+     * Decodes a local file (from a file input or a drop) in the worker - the
+     * bytes are read worker-side, so a multi-million-splat decode still never
+     * blocks the main thread.
+     *
+     * Only self-contained files are supported: `.ply`, `.spz`, `.splat`,
+     * `.ksplat` and bundled `.sog`. An unbundled SOG directory needs sibling
+     * fetches and so requires {@link load} with `kind: 'directory'`.
+     *
+     * @param file - The file; its name selects the parser unless `format` is given.
+     * @throws Rejects only with {@link SplatLoadError} (unknown extension, read
+     * or decode failures) or an `Error` named `AbortError` (cancellation or
+     * {@link dispose}).
+     */
+    loadFile(file: File, options?: SplatFileLoadOptions): Promise<SplatData>;
+    /** Routes one load to the worker that owns its format. */
+    private request;
+    /**
+     * The worker for `format`, constructing the one-shot worker on first need.
+     *
+     * The in-flight promise is cached, not just the resolved client, so two
+     * concurrent `.spz` loads share one worker instead of racing to build two.
+     */
+    private clientFor;
+    /** Terminates both workers and rejects all in-flight requests. */
+    dispose(): void;
+}

package/dist/compute-sorter.d.ts

@@ -0,0 +1,131 @@
+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.
+ * 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
+ * against each other correctly. Absent for an ordinary single-transform mesh.
+ */
+export interface PerSourceSortTransform {
+    /** RedFormat float texture holding each pool slot's source id (the channel). */
+    sourceIdTexture: THREE.DataTexture;
+    /** Shared array of source-matrix columns; see `SourceMatrixArray`. */
+    columns: ReturnType<typeof uniformArray>;
+    /** CPU mirror of the source-id channel, used by the WebGL2 worker sorter. */
+    sourceIds: Float32Array;
+    /** Column-major source matrices, used by the WebGL2 worker sorter. */
+    matrices: Float32Array;
+}
+/**
+ * GPU depth sorter: a single-pass counting sort over 2²² (~4M) depth
+ * buckets, running entirely in TSL compute passes on the WebGPU backend.
+ *
+ *   1. clear      - zero the histogram
+ *   2. histogram  - depth per active splat → bucket id; count per bucket
+ *   3. scanBlocks - exclusive prefix sum within each 256-bucket block
+ *   4. scanBlockSums - parallel exclusive scans over groups of block totals
+ *   5. scanSuperSums - exclusive scan over the remaining super-block totals
+ *   6. addBlockOffsets - combine both block-sum scan levels
+ *   7. addOffsets - combine block and bucket offsets
+ *   8. scatter    - order[offset[bucket]++] = pool index (atomic)
+ *
+ * Why ~4M buckets, not 64K: on a large scene, 16-bit buckets made a
+ * near-camera bucket span thousands of overlapping grass/leaf splats whose
+ * arbitrary intra-bucket order reshuffled as the camera moved - visible
+ * popping. Each depth bucket is now a sub-splat-width slice, so splats that
+ * share a bucket are effectively coplanar and their (still arbitrary) order
+ * cannot be seen. (A multi-pass radix would give exact order but needs a
+ * *stable* scatter, which the parallel `atomicAdd` scatter is not - hence a
+ * single wide pass instead.)
+ *
+ * Dynamic capacity: the sorter walks the mesh's `sourceIndex` buffer (pool
+ * indices of the active splats) and sorts only the first `activeCount`
+ * entries, so ranges can be appended and removed without rebuilding
+ * pipelines - the per-splat passes are dispatched with a dynamic invocation
+ * count and guarded by an `activeCount` uniform.
+ *
+ * Portable by construction: cross-workgroup communication only happens
+ * through the implicit synchronization WebGPU guarantees between dispatches
+ * - no spin-waits or scheduling assumptions.
+ *
+ * The depth range for bucket quantization comes from the mesh's bounding
+ * sphere transformed to view space, so no GPU min/max reduction is needed.
+ */
+export declare class ComputeSorter implements SplatSorter {
+    readonly kind: "counting";
+    private static readonly BUCKET_COUNT;
+    private static readonly BLOCK_SIZE;
+    /**
+     * Smallest bucket count a sort will dispatch. Below this the fixed passes
+     * are already cheap, and the floor keeps every block-scan index exact.
+     */
+    private static readonly MIN_BUCKET_COUNT;
+    private readonly renderer;
+    private readonly clearPass;
+    private readonly histogramPass;
+    private readonly scanBlocksPass;
+    private readonly scanBlockSumsPass;
+    private readonly addBlockSumOffsetsPass;
+    private readonly addOffsetsPass;
+    private readonly scatterPass;
+    /** All stages in dependency order, submitted as one WebGPU compute pass. */
+    private readonly sortPasses;
+    /** Sorter-owned working buffers, released on {@link dispose}. */
+    private readonly workingAttributes;
+    /** Frees the JS mirrors three keeps behind the GPU-only working buffers. */
+    private readonly mirrors;
+    /** Set by {@link dispose}; makes a second dispose a no-op. */
+    private disposed;
+    /** Row 2 of the model-view matrix; view-space z = row2 · (position, 1). */
+    private readonly viewRow2;
+    private readonly depthMin;
+    private readonly depthScale;
+    /** Active splat count; a float compares exactly for counts < 2²⁴. */
+    private readonly activeCount;
+    /** Highest bucket index this sort uses; see {@link effectiveBucketCount}. */
+    private readonly bucketMax;
+    private readonly viewCenter;
+    constructor(options: {
+        renderer: THREE.WebGPURenderer;
+        /** Pool capacity in splats; all buffers are sized once from this. */
+        capacity: number;
+        /** RGBA32F texture holding splat centers (xyz), pool-indexed. */
+        centersTexture?: THREE.DataTexture;
+        /** Width of the centers texture, to map pool index → texel. */
+        dataTextureWidth?: number;
+        /** Work-buffer centers (xyzw per splat), as written by a gather pass. */
+        centersBuffer?: THREE.StorageBufferAttribute;
+        /** The float `splatIndex` buffer the render material reads. */
+        splatIndexAttribute: THREE.StorageInstancedBufferAttribute;
+        /** Pool indices of the active splats (first `activeCount` entries). */
+        sourceIndexAttribute: THREE.StorageBufferAttribute;
+        /** Per-source world transform for a unified pool; omit for a single mesh. */
+        perSource?: PerSourceSortTransform;
+    });
+    /**
+     * Buckets to actually use for `activeCount` splats, rounded up to a power of
+     * two so block indexing stays exact.
+     *
+     * The histogram is allocated once for the pool's worst case, but clearing and
+     * scanning all 2²² buckets costs the same whether one splat is resident or
+     * four million - a fixed per-sort bill that dominates on a mobile GPU when
+     * the pool is only partly filled (a streaming scene ramping up, or any small
+     * scene). Sizing the dispatch to the live splat count keeps the design's
+     * ~1-bucket-per-splat depth resolution, so ordering is unaffected, while
+     * skipping work on buckets no splat can land in.
+     */
+    private effectiveBucketCount;
+    sort(modelView: THREE.Matrix4, activeCount: number, bounds: THREE.Sphere): boolean;
+    dispose(): void;
+}
+/**
+ * Frees the GPU buffers of storage attributes that never sat in a geometry.
+ * The renderer has no public API for this, so it reaches for the renderer's
+ * attribute map directly; a harmless no-op if the internal shape changes, and
+ * idempotent (the map's `delete` ignores unknown entries). Shared by the
+ * sorters and by owners of mesh-level storage attributes (`sourceIndex`, the
+ * unified work buffer) on dispose.
+ */
+export declare function releaseRendererAttributes(renderer: THREE.WebGPURenderer, attributes: readonly THREE.BufferAttribute[]): void;

package/dist/create-splat-renderer.d.ts

@@ -0,0 +1,99 @@
+/**
+ * One-call WebGPU renderer construction for VLAM! scenes.
+ *
+ * Every host needs the same four things right - adapter, device, raised limits
+ * and the platform-dependent `powerPreference` - and getting any of them wrong
+ * fails *late*: past ~8.4 M unified splats, or with MSAA silently dropped.
+ * {@link createSplatRenderer} is that block, once.
+ *
+ * The primitives it composes ({@link recommendedWebGpuRequiredLimits},
+ * {@link webGpuPowerPreferenceOptions}) stay exported for hosts that own device
+ * creation themselves - an XR session sharing a device, say.
+ */
+import { WebGPURenderer, type WebGPURendererParameters } from 'three/webgpu';
+import { type WebGpuPowerPreference } from './webgpu-limits';
+/** The device handle `createSplatRenderer` hands to `WebGPURenderer`. */
+export interface SplatRendererGpuDevice {
+    readonly features: ReadonlySet<string>;
+}
+/** The adapter surface `createSplatRenderer` reads limits and features from. */
+export interface SplatRendererGpuAdapter {
+    readonly features: ReadonlySet<string>;
+    readonly limits: {
+        readonly maxStorageBufferBindingSize: number;
+        readonly maxBufferSize: number;
+        readonly maxTextureDimension2D?: number;
+    };
+    requestDevice(descriptor?: {
+        requiredFeatures?: readonly string[];
+        requiredLimits?: Record<string, number>;
+    }): Promise<SplatRendererGpuDevice>;
+}
+/** The `navigator.gpu` surface `createSplatRenderer` probes. */
+export interface SplatRendererGpu {
+    requestAdapter(options?: {
+        powerPreference?: WebGpuPowerPreference;
+    }): Promise<SplatRendererGpuAdapter | null>;
+}
+/**
+ * Options for {@link createSplatRenderer}.
+ *
+ * Everything `THREE.WebGPURenderer` accepts passes straight through -
+ * `antialias`, `forceWebGL`, `trackTimestamp`, `canvas`, `alpha`, `samples`,
+ * `getFallback`, … - except the three members the helper owns (`device`,
+ * `requiredLimits`, and `powerPreference`, which is widened here to allow
+ * `null`).
+ */
+export interface CreateSplatRendererOptions extends Omit<WebGPURendererParameters, 'device' | 'requiredLimits' | 'powerPreference'> {
+    /**
+     * Adapter/renderer power hint. Omitted automatically on Windows, where Chrome
+     * ignores it and warns ([crbug.com/369219127](https://crbug.com/369219127)).
+     * Pass `null` to never send it.
+     *
+     * @defaultValue `'high-performance'`
+     */
+    powerPreference?: WebGpuPowerPreference | null;
+    /**
+     * Throw instead of degrading to three's WebGL2 backend. Adapter and device
+     * failures rethrow their original error, unwrapped.
+     *
+     * @defaultValue `false`
+     */
+    requireWebGpu?: boolean;
+    /**
+     * The WebGPU entry point to probe. Defaults to `navigator.gpu`; pass `null`
+     * to skip the probe entirely (tests, non-DOM hosts).
+     */
+    gpu?: SplatRendererGpu | null;
+}
+/**
+ * Creates a `THREE.WebGPURenderer` configured for splat rendering: the
+ * adapter's advertised buffer/texture maxima as `requiredLimits`, every adapter
+ * feature as `requiredFeatures`, and `powerPreference` only where the platform
+ * honours it.
+ *
+ * Both raised values matter late rather than loudly. Without the limits, large
+ * unified or streamed scenes throw past ~8.4 M splats. Without
+ * `core-features-and-limits` among the requested features, three treats the
+ * backend as compatibility-mode and **silently drops MSAA** - which is why the
+ * device is requested here rather than left to `WebGPUBackend.init`. Owning the
+ * request also keeps the real failure: three's `getFallback` hook logs a flat
+ * "WebGPU is not available" and drops the cause.
+ *
+ * Degrades to three's WebGL2 backend exactly as an unconfigured
+ * `new THREE.WebGPURenderer()` would, warning through
+ * {@link setVlamLogHandler} when the cause was a fixable failure rather than a
+ * browser without WebGPU. Pass `requireWebGpu: true` to throw instead.
+ *
+ * Does **not** call `setSize`, `renderer.init()`, or append the canvas - those
+ * stay in host code - and does not touch `outputColorSpace`, whose three.js
+ * default (sRGB) is already what the splat shader expects.
+ *
+ * @example
+ * const renderer = await createSplatRenderer();
+ * renderer.setSize(innerWidth, innerHeight);
+ * document.body.appendChild(renderer.domElement);
+ *
+ * @throws {TypeError} if `requireWebGpu` and `forceWebGL` are both set.
+ */
+export declare function createSplatRenderer(options?: CreateSplatRendererOptions): Promise<WebGPURenderer>;