@voluma/vlam 0.1.0 → 0.2.1

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

@@ -0,0 +1,205 @@
+import * as THREE from 'three/webgpu';
+import { type DepthOfFieldSettings } from './depth-of-field';
+import { type RelightingSettings, type RelightingUniforms } from './relighting';
+import { SplatMesh } from './splat-mesh';
+import type { SplatPickOptions, SplatPickResult } from './splat-mesh';
+/** Registration settings for one source in a {@link UnifiedSplatRenderer}. */
+export interface UnifiedSplatSourceOptions {
+    /** Whole-source opacity applied after its modifier stack. Defaults to `1`. */
+    opacity?: number;
+    /** Whether this source contributes to the unified draw. Defaults to `true`. */
+    visible?: boolean;
+    /** Higher values survive a fixed work-buffer overflow first. Defaults to `0`. */
+    priority?: number;
+    /**
+     * Cache a modifier-bearing source until {@link UnifiedSplatRenderer.invalidateSource}
+     * is called. Defaults to `false`, which safely re-gathers live modifier
+     * uniforms every frame.
+     *
+     * Use this for static modifiers, or when the host has a natural dirty signal
+     * for every uniform/channel mutation. Forgetting to invalidate leaves the
+     * unified work-buffer output stale.
+     */
+    cacheModifiers?: boolean;
+}
+/**
+ * Result of a successful {@link UnifiedSplatRenderer.pick}: the frontmost hit
+ * across every visible registered source, tagged with the source it landed on.
+ */
+export interface UnifiedSplatPickResult extends SplatPickResult {
+    /** The registered source mesh whose splat produced the winning hit. */
+    readonly source: SplatMesh;
+}
+/**
+ * Construction settings shared by every source in a unified renderer.
+ *
+ * @experimental May change in a minor release.
+ */
+export interface UnifiedSplatRendererOptions {
+    /** Composite source colors in display (sRGB) space. Defaults to `false`. */
+    srgbOutput?: boolean;
+    /**
+     * Global depth-sort strategy. `'exact'` preserves every Float32 depth bit
+     * through a stable radix sort of gathered world-space centers. `'counting'`
+     * remains the lower-cost default for existing callers.
+     *
+     * @experimental Exact sorting trades two additional radix passes for better
+     * ordering in large scenes with dense foliage or overlapping surfaces.
+     */
+    sortStrategy?: 'counting' | 'exact';
+}
+/**
+ * Returns true when `renderer` can drive {@link UnifiedSplatRenderer}.
+ * Heterogeneous gather/sort/draw is WebGPU-only; WebGL2 hosts keep standalone
+ * `SplatMesh` draws or static {@link SplatScene}.
+ */
+export declare function supportsUnifiedSplatRenderer(renderer: object): boolean;
+/**
+ * One gather → global-sort → draw path for static and streamed splat sources.
+ * Sources retain their own residency and update lifecycle; this mesh gathers
+ * their current active pool ranges into one shared work buffer per frame.
+ *
+ * The unified mesh stays at identity (`matrixAutoUpdate` is off). Pose each
+ * registered source mesh instead - sorter bounds and the draw material both
+ * consume world-space centers written by gather.
+ *
+ * WebGPU only. Prefer {@link supportsUnifiedSplatRenderer} before construction.
+ *
+ * @experimental May change in a minor release.
+ */
+export declare class UnifiedSplatRenderer extends THREE.Mesh {
+    private readonly workBuffer;
+    private readonly workSourceIndex;
+    /** The sorted draw-order buffer; lives outside the geometry, freed on dispose. */
+    private readonly orderAttribute;
+    /**
+     * Frees the JS mirrors three keeps behind `workSourceIndex` and `order`.
+     *
+     * `workSourceIndex` is an identity ramp written once at construction; `order`
+     * is written only by the sorter, on the GPU. Neither is ever read back, so
+     * both mirrors are 4 B/slot of dead JS heap once uploaded.
+     */
+    private readonly mirrors;
+    private readonly sorter;
+    private readonly renderer;
+    private readonly sources;
+    private previousLayout;
+    /** Previous layout keyed by source; kept in step with {@link previousLayout}. */
+    private readonly previousLayoutBySource;
+    /** Per-prepare scratch lists, reused so a steady frame allocates nothing. */
+    private readonly candidateScratch;
+    private readonly admittedScratch;
+    private readonly drawingBufferSize;
+    /** Reused target dimensions for secondary views; avoids per-view garbage. */
+    private readonly secondaryViewSize;
+    /**
+     * Camera gating for the global sorter, mirroring the standalone
+     * `SplatMesh.requestSortIfNeeded` path: an unchanged work buffer under a
+     * stationary camera skips the whole-buffer re-sort. Content changes
+     * (regather, layout change) force the next sort through the scheduler.
+     */
+    private readonly sortScheduler;
+    /** Model-view of the last accepted sort; starts unmatchable (zero scale). */
+    private readonly lastSortedModelView;
+    /**
+     * Total admitted splats in the last prepared frame. `removeSource` filters
+     * {@link previousLayout} directly, so a tail source's removal can leave the
+     * remaining entries identical - only this total betrays the shrink, and a
+     * shrunk draw range must re-sort (the old permutation indexes past it).
+     */
+    private previousAdmittedTotal;
+    private readonly bounds;
+    private readonly focal;
+    private readonly viewport;
+    private readonly maxStdDev;
+    private readonly minSplatSizePx;
+    private readonly antialias;
+    private readonly projectedLowPassVariance;
+    private readonly compensateProjectedLowPass;
+    private readonly dofFocusDistance;
+    private readonly dofAperture;
+    private readonly relightPlaceholder;
+    private relightMap;
+    private readonly relightBlend;
+    private readonly relightBrightness;
+    private readonly relightBackground;
+    private readonly relightSoftness;
+    private readonly srgbOutput;
+    private sourceMaxStdDev;
+    private sourceAntialias;
+    private sourceProjectedFilterProfile;
+    private overflowedSourceCount;
+    private overflowedSplatCount;
+    private disposed;
+    constructor(renderer: THREE.WebGPURenderer, capacity: number, options?: UnifiedSplatRendererOptions);
+    /** Fixed work-buffer splat capacity chosen at construction. */
+    get capacity(): number;
+    /** Registers a source. The caller keeps ownership and may still query it. */
+    addSource(source: SplatMesh, options?: UnifiedSplatSourceOptions): void;
+    /**
+     * Invalidates one registered source's cached gather output.
+     *
+     * Required after changing modifier uniforms or channels when that source was
+     * registered with `cacheModifiers: true`. The following {@link update}
+     * re-gathers the source and re-sorts because modifiers may move splats.
+     * Returns `false` when the source is not registered.
+     */
+    invalidateSource(source: SplatMesh): boolean;
+    /** Number of whole sources omitted in the most recent update due to capacity. */
+    get droppedSourceCount(): number;
+    /** Number of active splats omitted in the most recent update due to capacity. */
+    get droppedSplatCount(): number;
+    /** Updates a source's resolved opacity without rebuilding its gather pipeline. */
+    setSourceOpacity(source: SplatMesh, opacity: number): void;
+    /** Shows or hides a source without changing its residency. */
+    setSourceVisible(source: SplatMesh, visible: boolean): void;
+    /**
+     * Core projected-2D depth of field on the unified draw pass (not gather).
+     * Live uniforms - no gather-cache invalidation. Pass `aperture: 0` to disable.
+     */
+    setDepthOfField(settings: Partial<DepthOfFieldSettings>): void;
+    /** Current core DoF uniforms (`aperture === 0` means off). */
+    getDepthOfField(): DepthOfFieldSettings;
+    /**
+     * PlayCanvas-style proxy-mesh relighting on the unified draw pass (not gather).
+     * Live blend/brightness/background; map identity change rebuilds the draw
+     * material. Does not invalidate gather caches. Pass `null` to disable.
+     */
+    setRelighting(options: RelightingSettings | null): void;
+    /** Current relight numeric uniforms (`blend === 0` means off). */
+    getRelighting(): RelightingUniforms;
+    /**
+     * Asynchronously picks the frontmost visible splat under an NDC coordinate
+     * across every registered source.
+     *
+     * Semantics: each source that is
+     * currently visible in this unified renderer runs its own depth-tested GPU
+     * pick pass; the hit nearest the camera wins and the result names its source
+     * mesh. Hidden sources (`setSourceVisible(source, false)`) never hit. A hit
+     * whose source was removed, hidden, or disposed while its readback was in
+     * flight is dropped rather than misattributed. Resolves `null` for misses,
+     * an empty source list, and picks pending across {@link dispose}.
+     *
+     * Uses the construction renderer. Concurrent calls are safe: each source
+     * serializes its own picks and shared renderer state is restored
+     * synchronously before any await.
+     */
+    pick(ndc: THREE.Vector2, camera: THREE.Camera, options?: SplatPickOptions): Promise<UnifiedSplatPickResult | null>;
+    /** Unregisters a source and restores its standalone draw visibility. */
+    removeSource(source: SplatMesh): boolean;
+    /** Updates source LODs, gathers their active splats, then globally sorts them. */
+    update(camera: THREE.PerspectiveCamera): void;
+    /**
+     * Re-sorts and draws this unified source list for a secondary camera.
+     * Mirrors and portals use this instead of rendering the hidden source meshes
+     * individually, so their reflection keeps one global transparent order.
+     */
+    renderView(camera: THREE.PerspectiveCamera, renderer: THREE.WebGPURenderer, target?: THREE.RenderTarget | null): void;
+    private prepare;
+    dispose(): void;
+    private assertNotDisposed;
+    /** Rebuilds the EWA draw material when the relight map identity changes. */
+    private rebuildDrawMaterial;
+    private createGather;
+    private buildGather;
+}

package/dist/webgpu-limits.d.ts

@@ -0,0 +1,133 @@
+import type { WebGPURenderer } from 'three/webgpu';
+/**
+ * WebGPU device limits hosts should request for VLAM beyond the spec defaults.
+ *
+ * The WebGPU default `maxStorageBufferBindingSize` is 128 MiB. Unified work
+ * buffers and large streamed pools allocate storage attributes past that
+ * (16 bytes per splat for an RGBA32F centers buffer). Desktop adapters often
+ * advertise ~2 GiB, but only when those values are passed as `requiredLimits`
+ * to `adapter.requestDevice()` / Three.js `WebGPURenderer`.
+ *
+ * `maxTextureDimension2D` is here for the same reason: the default is 8192,
+ * which caps a pool at 8192 rows of {@link SPLAT_DATA_TEXTURE_WIDTH} (≈16.7 M
+ * splats of *capacity*, so ≈11.2 M resident at the usual 1.5 slack). Desktop
+ * adapters commonly advertise 16384 and double that ceiling for free.
+ */
+export interface WebGpuRequiredLimits {
+    maxStorageBufferBindingSize: number;
+    maxBufferSize: number;
+    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).
+ */
+export declare const WEBGPU_DEFAULT_MAX_STORAGE_BUFFER_BINDING_SIZE = 134217728;
+/**
+ * Copies the adapter's advertised buffer maxima for use as
+ * `WebGPURenderer({ requiredLimits })`.
+ *
+ * Does not call `requestDevice` - the host owns device creation.
+ */
+export declare function recommendedWebGpuRequiredLimits(adapter: {
+    limits: {
+        maxStorageBufferBindingSize: number;
+        maxBufferSize: number;
+        maxTextureDimension2D?: number;
+    };
+}): WebGpuRequiredLimits;
+/** Mirrors WebGPU `GPUPowerPreference` without requiring `@webgpu/types`. */
+export type WebGpuPowerPreference = 'high-performance' | 'low-power';
+type NavigatorPlatformProbe = Pick<Navigator, 'platform' | 'userAgent'> & {
+    userAgentData?: {
+        platform?: string;
+    };
+};
+/**
+ * Whether the host should pass `powerPreference` to `navigator.gpu.requestAdapter`
+ * / Three.js `WebGPURenderer`.
+ *
+ * Chrome on Windows ignores the option and logs a console warning when it is
+ * present ([crbug.com/369219127](https://crbug.com/369219127)). Prefer
+ * {@link webGpuPowerPreferenceOptions} so Windows hosts omit it automatically.
+ */
+export declare function supportsWebGpuPowerPreference(nav?: NavigatorPlatformProbe | undefined): boolean;
+/**
+ * Options to spread into `requestAdapter(...)` and `WebGPURenderer({...})`.
+ * Empty on Windows so Chrome does not warn about an ignored `powerPreference`.
+ */
+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
+ * when 0 rather than falsely reject.
+ */
+export declare function deviceMaxStorageBufferBindingSize(renderer: WebGPURenderer): number;
+/**
+ * Throws when a planned storage buffer would exceed the device bind limit.
+ * No-ops when the limit cannot be read (WebGL2 / uninitialized backend).
+ */
+export declare function assertStorageBufferFitsDevice(renderer: WebGPURenderer, byteSize: number, capacity: number): void;
+export {};

package/dist/work-buffer-gather.d.ts

@@ -0,0 +1,119 @@
+import * as THREE from 'three/webgpu';
+import { type SplatShInputs, type Vec3Uniform } from './splat-mesh-material';
+import type { SplatModifier } from './splat-modifier';
+/**
+ * GPU gather pass for Phase 0 of the unified renderer. It resolves a source
+ * pool's active local centers into a shared world-space storage buffer. The
+ * work-buffer sorter consumes this buffer directly, so source-local pools can
+ * later be heterogeneous (including streamed LOD pools).
+ *
+ * Internal while M15.4's draw path and public source API are completed.
+ */
+/** Shared GPU storage for every gathered source in one unified frame. */
+export declare class WorkBuffer {
+    readonly capacity: number;
+    /** World-space center xyz; w is the drawable flag (1 draw, 0 modifier-hidden). */
+    readonly centers: THREE.StorageBufferAttribute;
+    /** Resolved color and opacity per work slot. */
+    readonly colors: THREE.StorageBufferAttribute;
+    /** First packed covariance row per work slot. */
+    readonly covarianceA: THREE.StorageBufferAttribute;
+    /** Second packed covariance row per work slot. */
+    readonly covarianceB: THREE.StorageBufferAttribute;
+    /** Per-slot isotropic covariance mix (0 = keep Σ, 1 = round dot). */
+    readonly isotropicMix: THREE.StorageBufferAttribute;
+    /** Per-slot isotropic target sigma radius in screen px (0 = disabled). */
+    readonly isotropicScreenRadius: THREE.StorageBufferAttribute;
+    /**
+     * Slots past {@link capacity}, reserved so a pipeline warm-up has somewhere
+     * harmless to write. See {@link WorkBufferGather.warmUp}: compiling a compute
+     * pipeline requires actually dispatching it, and dispatching zero workgroups
+     * - while it does compile - makes WebGPU log an "unusual workgroup count of 0"
+     * warning for every source. One workgroup aimed at this tail compiles just the
+     * same, silently, and cannot disturb a drawn slot: admission never allocates
+     * past `capacity` and the draw's `instanceCount` never covers it.
+     */
+    static readonly SCRATCH_SLOTS = 256;
+    constructor(capacity: number);
+    /**
+     * Drops the JS-heap copies three keeps behind these storage buffers.
+     *
+     * Every one of them is written only by the gather compute pass and read only
+     * by the draw material - the CPU side is zeroes that no code ever reads, and
+     * three's WebGPU backend never frees it on its own. At 72 B/slot that mirror
+     * is ~720 MB of JS heap on a 10M-slot scene. See `storage-attribute-mirror`.
+     *
+     * Safe to call after any dispatch that bound this buffer; a no-op once
+     * settled, and on WebGL2 or a renderer double that has no WebGPU backend.
+     */
+    releaseCpuMirrors(renderer: THREE.WebGPURenderer): void;
+    private readonly mirrors;
+}
+export declare class WorkBufferGather {
+    /** World-space `xyzw` center buffer, one element per unified work slot. */
+    readonly centers: THREE.StorageBufferAttribute;
+    /** Resolved source RGBA values; production draw consumes this next. */
+    readonly colors: THREE.StorageBufferAttribute;
+    /** Packed symmetric world-space covariance rows. */
+    readonly covarianceA: THREE.StorageBufferAttribute;
+    readonly covarianceB: THREE.StorageBufferAttribute;
+    readonly isotropicMix: THREE.StorageBufferAttribute;
+    readonly isotropicScreenRadius: THREE.StorageBufferAttribute;
+    /** Shared target for this source's gathered range. */
+    readonly workBuffer: WorkBuffer;
+    private readonly capacity;
+    private readonly activeCount;
+    private readonly targetOffset;
+    private readonly sourceMatrix;
+    private readonly cameraViewMatrix;
+    private readonly opacity;
+    private readonly pass;
+    constructor(options: {
+        capacity: number;
+        sourceCapacity: number;
+        sourceIndex: THREE.StorageBufferAttribute;
+        centersTexture: THREE.DataTexture;
+        colorsTexture: THREE.DataTexture;
+        covarianceATexture: THREE.DataTexture;
+        covarianceBTexture: THREE.DataTexture;
+        dataTextureWidth: number;
+        sh?: SplatShInputs | null;
+        modifiers?: readonly SplatModifier[];
+        channels?: ReadonlyMap<string, {
+            texture: THREE.DataTexture;
+        }>;
+        localCameraPosition?: Vec3Uniform;
+        srgbOutput?: boolean;
+        /**
+         * Source stores Spark LOD alpha (`alpha ÷ 2`, `.rad`). Recover the full
+         * `alpha ∈ [0,2]` here so the shared draw material sees one convention;
+         * `alpha > 1` then marks a merged node (see `createWorkBufferMaterial`).
+         */
+        lodAlpha?: boolean;
+        /** Reuse one target across all source gather passes. */
+        workBuffer?: WorkBuffer;
+    });
+    /** Gathers a source's active pool slots into a contiguous work-buffer range. */
+    gather(renderer: THREE.WebGPURenderer, activeCount: number, targetOffset: number, sourceMatrix: THREE.Matrix4, cameraViewMatrixOrOpacity?: THREE.Matrix4 | number, opacity?: number): void;
+    /**
+     * Compiles this gather's compute pipeline without gathering anything.
+     *
+     * WebGPU compiles a compute pipeline lazily, at its first dispatch - not when
+     * the node graph is built. Measured on a 13-marker scene, a source's *first*
+     * `gather` took up to 2.0s while every later dispatch of the same pipeline
+     * took under 0.4ms, and because `gather` runs inside `update` that compile
+     * landed whole in one render frame. Running it through the async path here
+     * compiles off the critical frame, so the first real gather finds it ready.
+     *
+     * The dispatch targets {@link WorkBuffer.SCRATCH_SLOTS} past the drawable
+     * capacity rather than dispatching zero workgroups: zero also compiles, but
+     * WebGPU warns about it once per source, and writing into a drawn slot could
+     * leave junk behind when a cached gather is reused instead of re-run.
+     *
+     * Best-effort: a failure here costs only the stall it was meant to avoid, so
+     * callers may ignore it.
+     */
+    warmUp(renderer: THREE.WebGPURenderer): Promise<void>;
+    /** Releases the gather pipeline. The owner releases the storage attribute. */
+    dispose(): void;
+}

package/dist/work-buffer-material.d.ts

@@ -0,0 +1,42 @@
+import * as THREE from 'three/webgpu';
+import type { FloatUniform, Vec2Uniform } from './splat-mesh-material';
+/**
+ * Creates the unified EWA draw material for gathered world-space splats.
+ *
+ * Its vertex stage reads both the sorter-written order and the gather-written
+ * centers, covariance, and resolved color from storage buffers. It keeps the
+ * verified ±3σ / exp(-4.5·|q|²) convention used by {@link SplatMesh}.
+ */
+export declare function createWorkBufferMaterial(options: {
+    capacity: number;
+    centers: THREE.StorageBufferAttribute;
+    colors: THREE.StorageBufferAttribute;
+    covarianceA: THREE.StorageBufferAttribute;
+    covarianceB: THREE.StorageBufferAttribute;
+    isotropicMix: THREE.StorageBufferAttribute;
+    isotropicScreenRadius: THREE.StorageBufferAttribute;
+    order: THREE.StorageInstancedBufferAttribute;
+    focal: Vec2Uniform;
+    viewport: Vec2Uniform;
+    maxStdDev: FloatUniform;
+    /** Screen-space minimum splat radius in px; `0` disables. */
+    minSplatSizePx: FloatUniform;
+    antialias: FloatUniform;
+    /** Format-selected projected low-pass variance, in px². */
+    projectedLowPassVariance: FloatUniform;
+    /** LCC always preserves the low-pass integral; standard follows antialias. */
+    compensateProjectedLowPass: FloatUniform;
+    /** Core projected-2D DoF focus plane. Live; `0` aperture disables. */
+    dofFocusDistance: FloatUniform;
+    dofAperture: FloatUniform;
+    /**
+     * Proxy-mesh relight map (RGB = lit, A = coverage). Display only.
+     * Host swaps the texture object and rebuilds when enabling/changing map.
+     */
+    relightMap: THREE.Texture;
+    relightBlend: FloatUniform;
+    relightBrightness: FloatUniform;
+    relightBackground: FloatUniform;
+    /** Coverage soft edge in screen pixels; `0` = hard mask. */
+    relightSoftness: FloatUniform;
+}): THREE.NodeMaterial;

package/dist/worker-sorter.d.ts

@@ -0,0 +1,57 @@
+import type * as THREE from 'three/webgpu';
+import type { SplatSorter } from './sorter';
+/**
+ * CPU depth sorter: counting sort in a Web Worker. Used on the WebGL2
+ * fallback backend, which has no compute shaders. Works for static and
+ * dynamic-capacity (streamed) meshes alike: the worker keeps a mirror of
+ * the pool's centers, and each sort covers only the active pool spans.
+ *
+ * One sort runs at a time; requests that arrive while the worker is busy
+ * are declined so the caller retries with the then-current camera on a
+ * later frame.
+ */
+export declare class WorkerSorter implements SplatSorter {
+    readonly kind: "worker";
+    private readonly worker;
+    private readonly splatIndexAttribute;
+    private readonly host;
+    private inFlight;
+    /** Set by {@link dispose}; drops any already-delivered order message. */
+    private disposed;
+    /** The active spans the in-flight sort was computed against. */
+    private sentSpans;
+    constructor(host: WorkerSorterHost);
+    sort(modelView: THREE.Matrix4, _activeCount: number, _bounds: THREE.Sphere): boolean;
+    dispose(): void;
+    /** Sends written pool rows to keep the worker's centers mirror current. */
+    private pushCenters;
+    private applyOrder;
+}
+/** What the sorter needs from its mesh; see SplatMesh.createSorter. */
+export interface WorkerSorterHost {
+    /** Pool capacity in splats. */
+    readonly capacity: number;
+    /** Splats per pool texture row. */
+    readonly rowWidth: number;
+    /** The pool's centers backing array (vec4 stride; xyz used). */
+    readonly centers: Float32Array;
+    /** Source metadata for a unified pool; omitted for a normal mesh. */
+    readonly perSource?: {
+        readonly sourceIds: Float32Array;
+        readonly matrices: Float32Array;
+    };
+    readonly splatIndexAttribute: THREE.InstancedBufferAttribute;
+    /** Drains the row spans written since the last call. */
+    takeDirtyRows(): {
+        start: number;
+        count: number;
+    }[];
+    /** Active ranges as (start, count) pool-index pairs, active-list order. */
+    getActiveSpans(): Uint32Array;
+    /**
+     * Called after a worker order lands in the draw list, so the host knows the
+     * list holds a sorted permutation (not identity active order) and must fully
+     * resync - not patch - it on the next active-list mutation.
+     */
+    onOrderApplied?(): void;
+}

package/dist/xr-view.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Resolving the active WebXR view for a presenting renderer.
+ *
+ * Every render path (a static {@link SplatMesh}, a streamed one, the unified
+ * renderer) needs the same three things while an immersive session presents -
+ * a cyclopean camera to sort and place SH by, one eye camera to take the
+ * projection from, and the *per-eye* viewport in pixels - so they all resolve
+ * them here rather than each reading `renderer.xr` its own way.
+ *
+ * Internal. Nothing here is exported from `index.ts`.
+ */
+import * as THREE from 'three/webgpu';
+/** The cameras and pixel size describing one frame of a presenting XR session. */
+export interface XrView {
+    /**
+     * The XR array camera: the head pose, midway between the eyes. Depth order
+     * and the SH view direction come from here - at a ~63 mm IPD the per-eye
+     * difference is imperceptible except within the near plane, so one
+     * cyclopean sort serves both eyes instead of doubling the frame's dominant
+     * cost. Its `projectionMatrix` is the union frustum covering both eyes,
+     * which is also the right frustum for LOD scheduling.
+     */
+    head: THREE.Camera;
+    /**
+     * The first eye camera, for projection-derived quantities. Left and right
+     * XR projections differ only in their center offset, not their focal
+     * length, so a focal length taken from one eye is exact for both - it is
+     * not an approximation.
+     */
+    eye: THREE.PerspectiveCamera;
+    /** Per-eye viewport width in device pixels. */
+    width: number;
+    /** Per-eye viewport height in device pixels. */
+    height: number;
+}
+/**
+ * The active XR view, or `null` when the renderer is not presenting one.
+ *
+ * **Freshens the XR camera before reading it.** three splits its per-frame XR
+ * work in two: the sub-cameras' *local* `matrix`, `projectionMatrix` and
+ * `viewport` are set in the XR manager's own animation-frame callback (which
+ * runs before the host's loop body), but their `matrixWorld` /
+ * `matrixWorldInverse`, the head's world matrices, and the two-eye union
+ * projection are only computed in `XRManager.updateCamera()` - which the
+ * renderer calls from inside `render()`. A `SplatMesh.update()` that runs
+ * before `render()` would therefore read last frame's world pose, and on the
+ * first presenting frame an identity one (sorting the scene from the world
+ * origin). Calling `updateCamera` here closes that gap; it is idempotent and
+ * cheap (a handful of matrix products - `session.updateRenderState` only
+ * fires when near/far actually change), so the renderer's own call moments
+ * later costs nothing.
+ *
+ * @param camera - The *application* camera. `updateCamera` reads its near/far,
+ * layers and parent, so the app camera is required here - not the head.
+ * @returns The resolved view, or `null` when not presenting (or before the
+ * session has produced its first viewer pose).
+ */
+export declare function resolveXrView(camera: THREE.PerspectiveCamera, renderer: THREE.WebGPURenderer): XrView | null;
+/**
+ * Whether `camera` is an XR array camera. Code that needs a single frustum -
+ * picking, anything unprojecting depth through `near`/`far` - must reject one
+ * rather than silently read the defaults off a camera that has neither.
+ */
+export declare function isXrArrayCamera(camera: THREE.Camera): boolean;
+/**
+ * Session options for `navigator.xr.requestSession('immersive-vr', …)` that
+ * match the renderer's backend.
+ *
+ * three's XR manager **throws** out of `setSession` when a WebGPU-backed
+ * renderer meets a session that did not enable the `webgpu` feature - it has a
+ * genuine WebGPU XR path (an `XRGPUBinding` projection layer) and refuses to
+ * silently fall back to WebGL. three's own `VRButton` never asks for that
+ * feature, so a host pairing it with a `WebGPURenderer` fails to enter VR on
+ * exactly the browsers that support XR best. This returns the init that avoids
+ * the mismatch:
+ *
+ * ```js
+ * const session = await navigator.xr.requestSession('immersive-vr', xrSessionInit(renderer));
+ * await renderer.xr.setSession(session);
+ * ```
+ *
+ * `webgpu` is marked **required** rather than optional deliberately: an
+ * optional feature the browser declines still yields a session, which is the
+ * very mismatch that throws. Required turns it into a `requestSession`
+ * rejection the host can catch and explain - typically by falling back to a
+ * WebGL2 renderer, since three's own `WebGLXRFallback` helper swaps the entire
+ * renderer and is unusable once GPU resources are bound to the current one.
+ *
+ * @param base - Extra options to merge. Its `requiredFeatures` and
+ * `optionalFeatures` are concatenated, not replaced.
+ */
+export declare function xrSessionInit(renderer: THREE.WebGPURenderer, base?: XRSessionInit): XRSessionInit;