@voluma/vlam 0.1.0 → 0.2.1

package/dist/splat-mesh.d.ts

@@ -0,0 +1,737 @@
+import { type SplatChannelOptions, type SplatHeightResult, type SplatMeshOptions, type SplatNearestResult, type SplatPerformanceProfile, type SplatPickOptions, type SplatPickResult, type SplatRayResult, type SplatRange, type SplatUpdateOptions, type UnifiedSourceView } from './splat-mesh-types';
+export * from './splat-mesh-types';
+import * as THREE from 'three/webgpu';
+import type { SplatData } from './splat-data';
+import { type SplatOrientation } from './orientation';
+import type { SplatModifier } from './splat-modifier';
+import { type PerSourceSortTransform } from './compute-sorter';
+import { type DepthOfFieldSettings } from './depth-of-field';
+import { type RelightingSettings, type RelightingUniforms } from './relighting';
+import { type SplatPoolRange, type SplatPoolTenant } from './splat-mesh-pool';
+/**
+ * Renders a set of 3D Gaussians with three.js's WebGPURenderer.
+ *
+ * Rendering technique: EWA splatting per the 3DGS paper (Kerbl et al.,
+ * SIGGRAPH 2023). Each splat is an instanced quad; the vertex stage projects
+ * the splat's 3D covariance to a screen-space ellipse (the same math used by
+ * antimatter15/splat and PlayCanvas, both MIT) and the fragment stage applies
+ * the Gaussian falloff. Shaders are written in TSL, so three.js compiles
+ * them to WGSL on WebGPU and to GLSL on the automatic WebGL2 fallback.
+ *
+ * Splat data lives in pool data textures, indexed through one small
+ * per-instance `splatIndex` attribute. Correct alpha blending needs
+ * back-to-front ordering, so the indices are depth-sorted whenever the
+ * camera moves - only that index buffer is rewritten, never the splat data
+ * itself. On the WebGPU backend the sort runs in TSL compute passes
+ * (`ComputeSorter`); the WebGL2 fallback uses a Web Worker (`WorkerSorter`).
+ *
+ * Two construction modes:
+ *
+ *  - `new SplatMesh(data)` - static: capacity equals the data's count and
+ *    the whole scene is resident. Works on WebGPU and the WebGL2 fallback,
+ *    including SOG view-dependent color (shN).
+ *  - `new SplatMesh({ capacity })` - dynamic: an empty pool for up to
+ *    `capacity` splats. Content is managed with {@link appendRange} /
+ *    {@link removeRange} (ranges are row-aligned in the pool textures, so
+ *    uploads are rectangular). This mode is the substrate for LOD
+ *    streaming and works on both backends - the WebGL2 fallback sorts the
+ *    active pool spans on the CPU. shN data on appended ranges is ignored
+ *    (palettes are per-file and cannot be merged here).
+ */
+export declare class SplatMesh extends THREE.Mesh implements SplatPoolTenant {
+    private static readonly DATA_TEXTURE_WIDTH;
+    /**
+     * The storage this mesh draws from. Held rather than inlined because a
+     * splat's draw identity is already independent of its pool slot (`splatIndex`
+     * indirects every instance), so the pool is a separable concern - see
+     * {@link SplatPool}.
+     */
+    private readonly pool;
+    /** False when the pool was supplied by the caller, and so outlives this mesh. */
+    private readonly ownsPool;
+    private readonly splatIndexAttribute;
+    private readonly sourceIndexAttribute;
+    private dataTextures;
+    /**
+     * Pool index → this mesh's packed active-list slot. Lives on the pool: it is
+     * keyed by pool index, so a per-mesh copy would span the whole pool and
+     * several meshes sharing one would each pay for all of it. A row has one
+     * owner at a time, so the single array is unambiguous.
+     */
+    private get activeSlotByPoolIndex();
+    /** Rows in the pool backing this mesh. */
+    private get poolRows();
+    private get centersTexture();
+    private get backing();
+    private get freeRowSpans();
+    private set freeRowSpans(value);
+    private get poolFloatTextures();
+    /** Bands of per-splat (non-palette) SH this pool stores; 0 when disabled. */
+    private get packedShBands();
+    private get shPackedTextures();
+    /** True when constructed from a complete SplatData (single fixed range). */
+    private readonly isStatic;
+    /** Constructor-created range, retained for static in-place LOD replacement. */
+    private staticRange;
+    private readonly shEnabled;
+    /**
+     * Dequantization range for the packed SH, shared by every coefficient.
+     * Uniforms rather than constants: the first chunk to arrive supplies it,
+     * long after the material is built.
+     */
+    private readonly shRange;
+    /** Set once the first packed-SH chunk has supplied {@link shRange}. */
+    private shRangeSet;
+    /** Whether SH-less rows were neutral-filled before the scene range locked. */
+    private wrotePreLockNeutralSh;
+    private readonly ranges;
+    private activeCount;
+    /**
+     * Bumped whenever the resident splat set or its positions change (activate,
+     * deactivate, compact) - the signal the lazy spatial-query grid rebuilds on.
+     * A depth re-sort reorders the active list but changes neither, so it does
+     * not bump this. See {@link queryNearest}.
+     */
+    private queryEpoch;
+    private queryGrid;
+    private queryGridEpoch;
+    /**
+     * True when the shared depth-order buffer holds a *secondary* view's order
+     * (left by {@link renderView}), so the next primary {@link update} must
+     * re-sort even if its camera has not moved. See {@link renderView} (M10).
+     */
+    private orderIsForeign;
+    /**
+     * True while the draw list holds a CPU-worker depth permutation rather than
+     * the identity active order. Active-list mutations must then resync the
+     * whole drawn prefix instead of patching slots: patching a *permutation*
+     * with identity active-list values creates duplicates and drops live splats
+     * for every frame until the worker's next order lands (the WebGL2 streamed
+     * flicker, ROADMAP L5).
+     */
+    private drawListSorted;
+    /** CPU timings from the most recent render-preparation update (reset in place per frame). */
+    private readonly updateTimings;
+    protected readonly localBounds: THREE.Box3;
+    protected readonly boundingSphereLocal: THREE.Sphere;
+    protected boundsDirty: boolean;
+    /** Cached {@link getUnifiedSourceView} result; see the invalidation checks there. */
+    private cachedUnifiedView;
+    private readonly cachedUnifiedViewMatrixWorld;
+    private readonly cachedUnifiedViewLocalBounds;
+    private readonly cachedUnifiedViewWorldBounds;
+    /** Row spans written since the last flush, awaiting GPU upload. */
+    private pendingUploadRows;
+    /** Row spans awaiting mirroring to the CPU sort worker (WebGL2 path). */
+    private workerDirtyRows;
+    /** Persistent copy sources avoid allocating four temporary textures per upload region. */
+    private readonly uploadStaging;
+    /** Reusable float→half encode buffers keyed like {@link uploadStaging}. */
+    private readonly halfEncodeBuffers;
+    /** Opt-in per-splat channels by name; see {@link defineChannel}. */
+    private readonly channels;
+    /** 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
+     * 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`.
+     */
+    protected perSourceSort: PerSourceSortTransform | null;
+    /** Effect hooks folded into the vertex graph; see {@link modifiers}. */
+    private modifierList;
+    /** Increments when a unified gather must rebuild its source graph. */
+    private graphRevision;
+    /** Version for unified work-buffer caching; source pool writes are observable. */
+    private contentRevision;
+    /** Material-graph inputs kept for rebuilds when the modifier list changes. */
+    private materialInputs;
+    /** Projection focal lengths in pixels; updated every frame. */
+    private readonly focal;
+    /** Drawing-buffer size in pixels; updated every frame. */
+    private readonly viewport;
+    /** Camera position in this mesh's local space, for SH view dependence. */
+    private readonly localCameraPosition;
+    /**
+     * Frontier-cut limit for `foveationMode: 'frontier'` - the maximum
+     * `own_size / distance` a splat may have and still draw (Spark's
+     * `pixelScaleLimit`). Set each frame to `foveationTargetPx / focalPx` so the
+     * cut targets a fixed on-screen size. Unused in `'band'` mode.
+     */
+    private readonly pixelScaleLimit;
+    /**
+     * Core projected-2D depth of field (live uniforms). Aperture `0` disables.
+     * Prefer this over the M13 `depthOfFieldPreset` modifier for camera DoF.
+     */
+    private readonly dofFocusDistance;
+    private readonly dofAperture;
+    /**
+     * Proxy-mesh screen-space relighting (live uniforms + map). `blend === 0`
+     * disables. Swapping the map rebuilds the material graph once.
+     */
+    private readonly relightPlaceholder;
+    private relightMap;
+    private readonly relightBlend;
+    private readonly relightBrightness;
+    private readonly relightBackground;
+    private readonly relightSoftness;
+    /**
+     * Live screen-radius band bounds (px), seeded from
+     * {@link SplatMeshOptions.minSplatScreenRadius} / `maxSplatScreenRadius` and
+     * moved by {@link setScreenRadiusBand} - so a foveated mesh can widen the band
+     * as its LOD cut refines rather than culling the detail the refinement bought.
+     */
+    private readonly screenBandMin;
+    private readonly screenBandMax;
+    /** The pick pass and everything it allocates; see `splat-mesh-picking.ts`. */
+    private readonly picker;
+    /** Visibility supplied by an owning unified renderer for source-only picks. */
+    private unifiedPickVisibility;
+    /** Set by {@link dispose}; subclasses use it to drop late async results. */
+    protected disposed: boolean;
+    /** The renderer this mesh last updated with, so {@link dispose} can free
+     * storage-attribute GPU buffers that never sat in a geometry. */
+    private lastRenderer;
+    private readonly currentModelView;
+    /** Initialized to an impossible matrix so the first frame always sorts. */
+    private readonly lastSortedModelView;
+    private readonly sortScheduler;
+    /** One-frame queue-headroom hint used before a staged atomic commit. */
+    private deferSortRequestOnce;
+    /** Bumped by every active-list mutation; identifies a draw list. */
+    private activeListVersion;
+    /** The active list the current depth order was built from. */
+    private sortedActiveListVersion;
+    private readonly sortStrategy;
+    /** Resolved only when `sortStrategy === 'radix'`; see {@link ensureRadixSorter}. */
+    private RadixSorterCtor;
+    private radixSorterLoad;
+    private performanceProfileValue;
+    /** Gaussian cutoff radius in σ; baked into the material graph. */
+    private maxStdDevValue;
+    /** Screen-space minimum splat radius in px; baked into the material graph. */
+    private readonly minSplatSizePx;
+    /** Mip-Splatting 2D antialiasing filter; baked into the material graph. */
+    private readonly antialias;
+    /** Format-selected low-pass and opacity-compensation policy. */
+    private readonly projectedFilterProfile;
+    /** Emit sRGB colors for gamma-space compositing; baked into the material graph. */
+    private readonly srgbOutput;
+    /** Screen-radius cull threshold in px (0 = off); baked into the material graph. */
+    private readonly maxSplatScreenRadius;
+    private readonly minSplatScreenRadius;
+    /** `.rad` foveation cut selector; baked into the material graph. */
+    private readonly foveationMode;
+    /** Finest on-screen node size (px) the frontier cut may request. */
+    private readonly foveationTargetPx;
+    /** Target upper bound on the frontier cut's drawn-splat count. */
+    private readonly foveationDrawBudget;
+    /** Rendered major/minor axis-ratio cap (0 = off); baked into the material graph. */
+    private readonly maxSplatAspect;
+    /** Spark LOD alpha encoding + merged-node rendering; baked into the material. */
+    private readonly lodAlpha;
+    /** Live frontier limit in px; self-adjusts between `foveationTargetPx` (finest)
+     * and coarser to hold `foveationDrawBudget`. Feeds `pixelScaleLimit` each frame. */
+    private foveationLimitPx;
+    /** Throttle timestamp for the adaptive-limit estimate (ms, `performance.now`). */
+    private lastFoveationAdaptAt;
+    /** Y-up normalization policy; drives the static self-orientation below. */
+    readonly orientation: SplatOrientation;
+    /** Set once the pool has been checked against the device texture limit. */
+    private textureLimitChecked;
+    constructor(source: SplatData | {
+        capacity: number;
+    }, options?: SplatMeshOptions);
+    /**
+     * Higher-order SH bands this mesh actually renders (0 when it has none),
+     * whatever the source: a static mesh's palette shN, or per-splat SH in a
+     * dynamic pool. Reflects what was resolved at construction, not what was
+     * asked for - useful for a debug readout.
+     */
+    get shBands(): number;
+    /**
+     * The contribution-culling profile currently in effect (resolved at
+     * construction, or the last {@link setPerformanceProfile} value).
+     */
+    get performanceProfile(): SplatPerformanceProfile;
+    /**
+     * Changes contribution culling without changing scene data or persisted
+     * settings.
+     *
+     * Mutator convention: state that is plain data is a property (get/set pair);
+     * a `setX` method exists where the write has behavior - this one rebuilds the
+     * material graph, {@link StreamedSplatMesh.setBudget} returns its clamp.
+     * Every mutator has a matching readable property.
+     */
+    setPerformanceProfile(profile: SplatPerformanceProfile): void;
+    /**
+     * Gaussian cutoff radius currently in effect, in standard deviations.
+     * Resolved at construction, or the last {@link setMaxStdDev} value.
+     */
+    get maxStdDev(): number;
+    /**
+     * Changes the Gaussian cutoff without changing scene data.
+     *
+     * Lowering it shrinks every quad and is the main fill-rate lever in a busy
+     * view; raising it restores the faint outer tail. Rebuilds the material
+     * graph, same convention as {@link setPerformanceProfile}.
+     */
+    setMaxStdDev(value: number): void;
+    /**
+     * Copies a decoded scene (or chunk) into the pool and activates it.
+     * Ranges are row-aligned in the pool textures, so each allocation may
+     * round up to the next multiple of the texture width internally.
+     *
+     * @returns A handle to pass to {@link removeRange}.
+     * @throws {Error} when the remaining pool capacity cannot fit the range.
+     */
+    appendRange(data: SplatData): SplatRange;
+    /** Appends uploaded data without exposing it to draw/sort until activated. */
+    protected appendInactiveRange(data: SplatData): SplatRange;
+    /** Reserves an inactive pool range whose data can be filled over multiple frames. */
+    protected reserveInactiveRange(count: number): SplatRange;
+    /** Writes one contiguous segment of a reserved inactive range. */
+    protected writeInactiveRange(handle: SplatRange, data: SplatData, offset: number): void;
+    /**
+     * Overwrites splats at `offset` within a range **in place** - unlike
+     * {@link writeInactiveRange} this allows an *active* range, so the frontier
+     * page table can page individual slots of its always-active slab. Queues the
+     * touched rows for upload; the caller must {@link invalidateSort} once per
+     * batch since splat depths changed.
+     */
+    protected overwriteRangeData(handle: SplatRange, data: SplatData, offset: number): void;
+    /**
+     * Zeros splats `[offset, offset + count)` of a range so they draw nothing
+     * (zero covariance → degenerate quad, zero color). Used to free frontier slab
+     * slots that leave the frontier. Queues the rows for upload.
+     */
+    protected degenerateRange(handle: SplatRange, offset: number, count: number): void;
+    /**
+     * Copies one chunk's splats into the pool's backing arrays at `destination`.
+     * Shared by the append and staged-write paths, which differ only in where
+     * the rows come from and when they are activated.
+     */
+    private writeSplatRows;
+    /**
+     * Scatters a chunk's packed SH words into the per-group pool textures.
+     *
+     * A chunk without SH still writes: pool rows are reused, so leaving the
+     * previous occupant's words behind would give a DC-only chunk somebody
+     * else's view-dependent color. Zero is not neutral (the range is signed and
+     * rarely symmetric), so the code for "0.0" in this scene's range is.
+     */
+    private writePackedSh;
+    /**
+     * Adopts the first packed-SH chunk's dequantization range as the scene's one
+     * pool uniform. LCC/`.rad` chunks already share one range; a streamed SOG
+     * chunk measures its own extent, so later chunks are requantized into this
+     * one at write time ({@link writePackedSh}) rather than ignored.
+     */
+    private applyShRange;
+    /** The scene's locked packed-SH range as a plain tuple, or null if unset. */
+    private currentShRange;
+    /** The packed word decoding to 0 in every channel under the scene's range. */
+    private neutralShWord;
+    /** Warns once per call site when a source's SH cannot be stored. */
+    private warnOnIgnoredSh;
+    /** Atomically includes or excludes a resident range on the next active-list rebuild. */
+    protected setRangeActive(handle: SplatRange, active: boolean): void;
+    /**
+     * Activates only the first `prefix` splats of a range (see
+     * {@link RangeRecord.activePrefix}). The page-table slab keeps its used slots
+     * densely packed at the front, so this bounds per-frame sorting and vertex
+     * work to the *drawn* frontier instead of the whole pool-sized slab. Write
+     * APIs (`overwriteRangeData` / `degenerateRange`) still address the full range.
+     */
+    protected setRangeActivePrefix(handle: SplatRange, prefix: number): void;
+    /**
+     * Replaces the drawn pool indices for an immutable static hierarchy.
+     *
+     * This is intentionally narrower than the range API: subclasses may select
+     * an arbitrary hierarchy frontier, but the referenced pool rows must remain
+     * resident for the lifetime of the mesh.
+     */
+    protected replaceActiveIndices(indices: Uint32Array): void;
+    /** Fast identity-frontier variant that avoids allocating a large index array. */
+    protected replaceActivePrefix(count: number): void;
+    /** Replaces a static mesh's resident cut without increasing its fixed pool allocation. */
+    protected replaceStaticData(data: SplatData): void;
+    private appendRangeWithState;
+    /**
+     * Deactivates a previously appended range and frees its pool rows for
+     * reuse. The bounding sphere used for depth quantization stays a
+     * conservative superset until new ranges grow it again.
+     */
+    removeRange(handle: SplatRange): void;
+    /** Maximum number of splats the pool can hold (row-aligned internally). */
+    get capacity(): number;
+    /** Number of splats currently active (drawn and depth-sorted). */
+    get activeSplatCount(): number;
+    /**
+     * Returns this mesh's current pool state for an internal unified gather.
+     * Call {@link update} first for streamed sources so the active list reflects
+     * the current LOD cut. Consumers must treat the returned GPU resources as
+     * read-only; range lifecycle remains owned by this mesh.
+     */
+    getUnifiedSourceView(): UnifiedSourceView;
+    /**
+     * Marks this mesh as a source drawn by {@link UnifiedSplatRenderer}.
+     * 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.
+     */
+    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
+     * 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
+     * every source it owns purely to keep the regular scene draw from
+     * double-drawing them.
+     */
+    get effectiveVisibility(): boolean;
+    /**
+     * Pool splats still allocatable, in whole rows. Because allocation is
+     * row-aligned, an append of n splats fits when
+     * `ceil(n / rowWidth) · rowWidth ≤ freeSplatCapacity` *and* a contiguous
+     * span exists; callers use this for conservative pre-checks before
+     * falling back to {@link compact}.
+     */
+    get freeSplatCapacity(): number;
+    /**
+     * Declares a named per-splat data channel - one extra value per pool slot,
+     * in its own pool-aligned data texture. Channels are opt-in: nothing is
+     * allocated until you call this. Read a channel from a modifier with
+     * `ctx.channel(name)` and write values per range with {@link writeChannel}.
+     *
+     * Because a splat keeps its pool row for its whole residency, a channel
+     * value follows the splat across depth re-sorts and pool {@link compact}ion
+     * - the persistent per-splat label the SDF/selection effects build on. Call
+     * this **before** assigning a modifier that reads the channel; a modifier
+     * that reads an undeclared channel is a material-build error.
+     *
+     * @throws {Error} if a channel of this name already exists.
+     */
+    defineChannel(name: string, options?: SplatChannelOptions): void;
+    /**
+     * Writes channel values for a resident range, at `[offset, offset + data.length)`
+     * splats within it (default `offset` 0). Values ride the same staging-upload
+     * path as pool data, flushed on the next {@link update}. `byte` channels take
+     * raw `0..255`; `float` channels take the value verbatim.
+     *
+     * @throws {Error} for an unknown channel or range, or a write past the range.
+     */
+    writeChannel(range: SplatRange, name: string, data: ArrayLike<number>, offset?: number): void;
+    /**
+     * Effect hooks, folded into the vertex stage in array order - each
+     * modifier sees the running result of the ones before it. Assigning a
+     * changed list rebuilds the material (a pipeline recompile); animating a
+     * modifier's own uniforms or storage buffers never does. With an empty
+     * list the material is exactly the unhooked renderer.
+     * See `docs/guide/effects-and-modifiers.md`.
+     */
+    get modifiers(): readonly SplatModifier[];
+    set modifiers(value: readonly SplatModifier[]);
+    /**
+     * Core projected-2D depth of field. Adds an isotropic screen-space CoC disc
+     * after EWA projection (not the stylized M13 scale modifier). Live uniforms
+     * - no material rebuild. Pass `aperture: 0` to disable.
+     */
+    setDepthOfField(settings: Partial<DepthOfFieldSettings>): void;
+    /**
+     * PlayCanvas-style proxy-mesh relighting. Multiplies baked splat color in the
+     * **display** fragment by a screen-space sample of `map` (RGB = lit proxy,
+     * A = coverage). Pass `null` to disable (`blend → 0`, placeholder map).
+     *
+     * Blend / brightness / background are live uniforms (no rebuild). Changing
+     * the map texture identity rebuilds the material once. Does not affect the
+     * pick pass. Does not invalidate a unified gather cache.
+     */
+    setRelighting(options: RelightingSettings | null): void;
+    /** Current relight numeric uniforms (`blend === 0` means off). */
+    getRelighting(): RelightingUniforms;
+    /**
+     * Moves the screen-radius band (px) without rebuilding the material.
+     *
+     * Only meaningful on a mesh constructed *with* a band - the graph decides at
+     * build time whether to cull on radius at all, from
+     * {@link SplatMeshOptions.minSplatScreenRadius} / `maxSplatScreenRadius`.
+     *
+     * A foveated mesh uses this to keep the band aligned with its LOD cut: the
+     * band spans roughly one level, so refining the cut to spend spare budget
+     * selects smaller splats, and a band left where it was would cull precisely
+     * the detail that refinement bought.
+     */
+    protected setScreenRadiusBand(minPx: number, maxPx: number): void;
+    /** Current core DoF uniforms (`aperture === 0` means off). */
+    getDepthOfField(): DepthOfFieldSettings;
+    /**
+     * Packs the resident ranges toward the start of the pool, removing the
+     * gaps that add/remove churn leaves behind and restoring a single
+     * contiguous free span. Use this when {@link appendRange} throws despite
+     * enough total free rows (row-alignment fragmentation).
+     *
+     * The CPU backing arrays are authoritative, so no data is re-fetched;
+     * moved rows are re-uploaded to the GPU on the next {@link update}.
+     */
+    compact(): void;
+    /** {@link SplatPoolTenant}: the ranges this mesh holds in the pool. */
+    poolRanges(): Iterable<SplatPoolRange>;
+    /**
+     * {@link SplatPoolTenant}: follow one range to its new rows. The pool has
+     * already moved the splat data; this moves what the mesh keys by pool row.
+     */
+    relocatePoolRange(range: SplatPoolRange, targetRow: number): void;
+    /** {@link SplatPoolTenant}: rebuild everything keyed by pool index. */
+    onPoolCompacted(): void;
+    /**
+     * Per-frame update: uploads pending pool writes, refreshes the projection
+     * uniforms and requests a depth re-sort when the camera or the content
+     * has changed. Call this every frame, before `renderer.render`.
+     */
+    update(camera: THREE.PerspectiveCamera, renderer: THREE.WebGPURenderer, options?: SplatUpdateOptions): void;
+    /** Returns the render-preparation CPU timings for the current update. */
+    protected getUpdateTimings(): Readonly<{
+        activeListMs: number;
+        uploadMs: number;
+        sortSubmitMs: number;
+        stagingTextureAllocations: number;
+        activeListUpdateRanges: number;
+    }>;
+    /**
+     * Skips one otherwise ordinary sort request, but only while the active list
+     * is unchanged since the last sort. Streamed staging uses this immediately
+     * before a forced commit sort so the GPU queue has a frame to drain; a
+     * concurrent swap group that mutates the active list revokes the request,
+     * because the depth order must always describe the list being drawn.
+     */
+    protected deferNextSortRequest(): void;
+    /**
+     * Once, on the first update (when the backend is known), fails loudly if the
+     * pool's `2048 × poolRows` data textures exceed the device's maximum texture
+     * dimension - otherwise the upload fails with a cryptic backend error and a
+     * frozen canvas. Streamed scenes stay under the limit (budget-bounded); this
+     * guards very large *static* scenes, especially on mobile (≈8192 max → about
+     * 16.7 M splats). If the limit can't be read, the check is skipped rather
+     * than risk a false rejection.
+     */
+    private assertPoolFitsDevice;
+    /** Bounding box of the appended splats, in this mesh's local space. */
+    computeSplatBounds(): THREE.Box3;
+    /**
+     * Asynchronously picks the frontmost visible splat under an NDC coordinate.
+     *
+     * Renders a one-pixel GPU depth pass (shared projection/Gaussian math with
+     * the display material), reads the encoded view depth, and reconstructs a
+     * world-space point on the splat's rendered center plane. Concurrent calls
+     * on this mesh are serialized. Returns `null` for misses, empty meshes,
+     * out-of-canvas coordinates, or after {@link dispose}.
+     *
+     * Does not return a persistent splat id - LOD streaming and pool reuse make
+     * identity unstable across frames.
+     */
+    pick(ndc: THREE.Vector2, camera: THREE.Camera, renderer: THREE.WebGPURenderer, options?: SplatPickOptions): Promise<SplatPickResult | null>;
+    /**
+     * The resident splat center nearest a world point, within `radius` (world
+     * units), or `null` if none. A synchronous CPU query over the pool's decoded
+     * centers - no GPU round-trip - backed by a uniform grid rebuilt only when
+     * the resident set changes (M9). The primitive behind measurement markers and
+     * proximity tests.
+     *
+     * **Resident-only:** a {@link StreamedSplatMesh} searches only the splats
+     * currently in the pool (the LOD the camera has resolved), so the answer is
+     * the nearest *loaded* splat - coarser far from the camera, absent where no
+     * chunk has streamed in. A static mesh searches its whole scene.
+     *
+     * World-correct under any rotation + per-axis (including non-uniform) scale:
+     * candidates are gathered in local space with a conservative radius
+     * (`radius / min axis scale`) and then ranked by **world** distance, so the
+     * nearest-in-world splat wins even when the axes stretch differently. Shear
+     * in an ancestor transform is not supported. Splats displaced by GPU
+     * modifiers are queried at their undisplaced CPU positions.
+     */
+    queryNearest(worldPoint: THREE.Vector3, radius: number): SplatNearestResult | null;
+    /**
+     * Returns the first resident splat center inside a world-space ray cone.
+     * This is a synchronous CPU query, intended for interactions that cannot
+     * wait for (or rely on) a GPU readback. `radiusAtUnitDistance` is the cone's
+     * world-space radius one unit from the origin; `minimumRadius` keeps nearby
+     * point-like splats practical to target.
+     *
+     * Like {@link queryNearest}, this searches resident, undisplaced CPU centers.
+     */
+    queryRay(ray: THREE.Ray, radiusAtUnitDistance?: number, minimumRadius?: number): SplatRayResult | null;
+    /**
+     * The supporting surface beneath a world point: the highest resident splat
+     * that lies no more than `maxDrop` below it (world −Y) and within `radius`
+     * horizontally, or `null` if none. A downward probe over splat centers - the
+     * primitive behind floor-following and teleport validation - without a GPU
+     * pick or a collision mesh (M9), so it works for every format, not only the
+     * `.lcc2` captures that ship collision geometry.
+     *
+     * `radius` (default `maxDrop / 2`) is the horizontal tolerance: splats are
+     * points, so an exact vertical hit is unlikely and a small disc is searched.
+     * Resident-only semantics and the world-correctness contract (rotation +
+     * per-axis scale supported, shear not) are the same as {@link queryNearest};
+     * every candidate is judged in world space, where the −Y probe direction is
+     * defined, so the vertical test never assumes local axis alignment.
+     */
+    queryHeight(worldPoint: THREE.Vector3, maxDrop: number, radius?: number): SplatHeightResult | null;
+    /**
+     * Renders this mesh from a second camera - into `target`, or the canvas when
+     * omitted - with depth order **and** projection correct for *that* camera
+     * (M10). The primitive behind mirrors, portals, split panes, and thumbnails.
+     *
+     * Depth order is view-dependent, but a mesh keeps one sorted order buffer:
+     * `update()` sorts it for the single camera it is given, so a second view
+     * drawn with that order shows transparency/pop errors. `renderView` re-sorts
+     * for `camera` into the shared buffer, sets the view-dependent uniforms
+     * (viewport from `target`), draws, and marks the primary order stale so the
+     * next `update()` re-sorts for the main camera. GPU submissions execute in
+     * order, so each view's draw reads the order and uniforms it just wrote.
+     *
+     * Call once per extra view per frame, before or after the primary
+     * `update()` + render - both are correct. On the WebGL2 fallback the sorter
+     * is an asynchronous worker owned by the primary view, so `renderView` does
+     * not sort at all there: the secondary view draws with the primary view's
+     * order (projection is still per-camera correct) - a documented single-view
+     * ordering limitation; WebGPU gets exact per-view order.
+     *
+     * @param target - Destination render target, or `null`/omitted for the canvas.
+     */
+    renderView(camera: THREE.PerspectiveCamera, renderer: THREE.WebGPURenderer, target?: THREE.RenderTarget | null): void;
+    /**
+     * Sorts the shared order buffer for a secondary view's camera, bypassing the
+     * primary view's sort scheduler and its `lastSortedModelView` record (that
+     * state belongs to `update()`'s camera). WebGPU dispatches synchronously into
+     * the render queue, so the following draw reads this order.
+     */
+    private sortForView;
+    /** Rebuilds the query grid if the resident set changed since it was built. */
+    private ensureQueryGrid;
+    /** World-space position of pool splat `poolIndex`, written into `out`. */
+    private splatWorldPosition;
+    /**
+     * The smallest world axis scale, for conservatively mapping a world radius
+     * into local space: a world sphere of radius `r` fits inside a local sphere
+     * of `r / minAxisScale`, for any per-axis (non-uniform) scale.
+     */
+    private queryWorldMinScale;
+    /**
+     * Releases every GPU resource and worker this mesh owns. Idempotent: a
+     * second call is a no-op, and a render loop that outlives the mesh by a
+     * frame is safe - {@link update}, {@link renderView} and {@link pick} all
+     * become no-ops after dispose.
+     */
+    dispose(): void;
+    /** Matches the viewport / focal / local-camera uniforms written by {@link update}. */
+    private refreshProjectionUniforms;
+    /**
+     * Writes the three view-dependent uniforms - viewport, focal (splat screen
+     * size), and the camera position in mesh-local space (SH view direction +
+     * screen-radius math) - for a camera drawing into a viewport of the given
+     * pixel size. {@link update} passes the canvas size (or, while an XR session
+     * presents, the per-eye viewport); {@link renderView} passes its render
+     * target's size.
+     *
+     * @param positionCamera - Camera whose world position seeds the SH view
+     * direction and screen-radius math. Defaults to `camera`; in XR it is the
+     * head, so both eyes shade from one cyclopean point while each still
+     * projects through its own eye.
+     */
+    private writeViewUniforms;
+    /**
+     * Self-adjusts {@link foveationLimitPx} so the frontier cut's drawn-splat count
+     * tracks {@link foveationDrawBudget} (Spark's `maxSplats` feedback). Estimates
+     * the drawn count by replaying the cut on a strided sample of the pool, then
+     * coarsens (grows the limit) when over budget and refines (shrinks toward the
+     * finest {@link foveationTargetPx}) when comfortably under. Throttled; a no-op
+     * outside `'frontier'` mode.
+     *
+     * `viewportY` must be the **same** height {@link writeViewUniforms} is given
+     * for this frame - the two share `foveationLimitPx` in pixels and each
+     * converts it with its own `focalY`, so a mismatch (the full drawing buffer
+     * here against a per-eye viewport there) makes the estimator judge a cut the
+     * shader is not applying, and the ratchet runs away toward the maximum.
+     */
+    private adaptFoveationLimit;
+    /** Records a written row span for GPU upload and the sort-worker mirror. */
+    private markRowsWritten;
+    /** Appends one newly active pool range to the packed source-index list. */
+    private activateRecord;
+    /**
+     * Removes one active range and backfills its holes from the packed tail.
+     * The common contiguous case uses one native block copy; the fallback
+     * handles a range split by earlier tail backfills in O(record.count).
+     */
+    private deactivateRecord;
+    /** Uploads only the changed packed slots and invalidates the current depth order. */
+    private commitActiveListMutation;
+    /** Rewrites the active-splat list (pool indices, range by range). */
+    private rebuildActiveList;
+    /** The pool's reusable index ramp; shared by every mesh drawing from it. */
+    private getPoolIndexTemplate;
+    /**
+     * Uploads rows written since the last flush by copying only those rows
+     * through a staging texture. (Constructor-time writes never appear here;
+     * they ride the textures' initial full upload instead.)
+     */
+    private flushPendingUploads;
+    /**
+     * Packs float32 CPU backing into the half GPU images for centers/covA.
+     * Used once after a static constructor write so the initial `needsUpdate`
+     * upload carries half bits (staging is skipped for that path).
+     */
+    private syncHalfFloatPoolImages;
+    /**
+     * Uploads the given row spans of one or more same-layout pool textures via
+     * per-region staging copies. Spans are merged first so consecutive appends
+     * upload as one rectangle each - the copyTextureToTexture call count, not
+     * the pixel volume, dominates.
+     */
+    private uploadRows;
+    /** Reuses a same-length half encode buffer for one staging key. */
+    private acquireHalfEncodeBuffer;
+    /**
+     * Reuses one of the recent same-sized staging textures for this upload. WebGPU
+     * texture dimensions are immutable, so each cached entry remains exact-sized. Keeping
+     * a small LRU per channel avoids recreating all core/SH staging resources when
+     * a stream alternates among a few chunk heights, while bounding GPU memory.
+     */
+    private acquireUploadStaging;
+    /** Gathers everything the material graph reads. See `splat-mesh-material.ts`. */
+    private graphInputs;
+    private buildMaterial;
+    private requestSortIfNeeded;
+    /**
+     * 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
+     * bound spanning all its sources (whose transforms live in the shader).
+     */
+    protected refreshSortBounds(): void;
+    /** The data texture backing a channel defined with {@link defineChannel}. */
+    protected channelTexture(name: string): THREE.DataTexture | undefined;
+    /** CPU backing storage of a float channel, for internal CPU-side consumers. */
+    protected channelBacking(name: string): Float32Array;
+    /**
+     * Forces the next {@link update} to re-sort even if the camera has not moved
+     * - used by a unified pool when a source's transform changes, since the depth
+     * order then changes without any camera motion.
+     */
+    protected invalidateSort(): void;
+    private createSorter;
+    /** Prefetches the experimental radix sorter; safe to call repeatedly. */
+    private ensureRadixSorter;
+}
+/** Default frontier-cut target size (px). Matches Spark's `lodRenderScale`
+ * default of 1 - nodes refine until ~1 px on screen, so the draw budget (not a
+ * coarser fixed cut) is what bounds detail. At the old value of 4 the cut
+ * stopped ~2 LOD levels early everywhere the tree doesn't bottom out at
+ * leaves, which made large-scale scenes visibly coarser than Spark. */
+export declare const DEFAULT_FOVEATION_TARGET_PX = 1;
+/** Default target for the frontier cut's drawn-splat count (Spark's `maxSplats`).
+ * Coarsens the cut once the estimate exceeds it, keeping frame cost bounded. */
+export declare const DEFAULT_FOVEATION_DRAW_BUDGET = 900000;