@voluma/vlam 0.1.0 → 0.2.0

package/dist/streamed-splat-mesh.d.ts

@@ -0,0 +1,985 @@
+export * from './streamed-splat-mesh-utils';
+import * as THREE from 'three/webgpu';
+import { SplatMesh, type SplatChannelOptions, type SplatMeshOptions, type SplatUpdateOptions } from './splat-mesh';
+import type { StaticLodSplatMesh, StaticLodSplatMeshLoadOptions } from './static-lod-splat-mesh';
+import { type StreamedScene } from './lod-source';
+import type { CollisionMeshTile } from './formats/lcc/collision-mesh';
+import { type SplatRequestOptions, type StreamedSplatFormat } from './loading';
+import { type SplatDeviceProfile } from './splat-budget';
+import { type FrontierFoveation } from './formats/rad/frontier-worker-protocol';
+import type { ChunkFetchScheduler } from './chunk-fetch-scheduler';
+import type { ChunkCacheBudget } from './chunk-cache-budget';
+/**
+ * Rough decoded size of a whole streamed scene, for sizing the cache floor:
+ * positions (12 B) + colors (4 B) + covariances (24 B) per splat, plus the LOD
+ * tree arrays a `.rad` chunk carries (`childCount` 4 B + `childStart` 4 B +
+ * `size` 4 B) and packed SH when the scene carries it. Deliberately an
+ * over-estimate - the floor should never be the reason a capture cannot hold
+ * itself, and it must match what the frontier worker charges its cache, or a
+ * capture the cap was sized to hold starts evicting itself mid-load.
+ *
+ * Exported for unit testing only; not part of the public API.
+ */
+export declare function estimateSceneDecodedBytes(scene: StreamedScene): number;
+/**
+ * Read-only startup-hold progress for classic `.lcc` {@link StreamedSplatMeshOptions.initialReveal}.
+ * Exported for hosts that gate visibility on the first useful near-L0 frame.
+ */
+export type InitialRevealState = {
+    readonly status: 'disabled';
+} | {
+    readonly status: 'pending';
+    readonly stagedSplats: number;
+    readonly totalSplats: number;
+    readonly readyGroups: number;
+    readonly totalGroups: number;
+} | {
+    readonly status: 'ready';
+} | {
+    readonly status: 'degraded';
+    readonly reason: 'capacity' | 'fetch-failed' | 'timeout';
+    readonly stagedSplats: number;
+    readonly totalSplats: number;
+    readonly readyGroups: number;
+    readonly totalGroups: number;
+};
+/** Options for {@link StreamedSplatMesh.load}. */
+export interface StreamedSplatMeshOptions extends SplatMeshOptions {
+    /** Active-splat budget. Defaults to {@link resolveSplatBudget}. */
+    budget?: number;
+    /**
+     * A ceiling on the *resolved default* budget, for callers that want to
+     * tighten without overriding what the library knows.
+     *
+     * `budget` is absolute: it wins over the device tier, the format's cost class
+     * and everything else, because a caller who names a number has said they know
+     * better. That is the right contract, and the wrong tool for "the same as
+     * usual, but no more than N" - which is what a performance toggle or a host
+     * default actually means. Pinning a number there has twice shipped as a bug:
+     * a demo performance mode that *raised* the load on the weakest device tested,
+     * and a host whose default bypassed every device tier.
+     *
+     * Applied only when `budget` is omitted, and only downward - it never raises
+     * a budget the device would not otherwise have taken. It also suppresses the
+     * finest-level lift, which exists to raise a budget far enough to hold a
+     * scene whole and is exactly what "no more than N" rules out. Unrelated to
+     * {@link maxBudget}, which sizes the pool and bounds
+     * {@link StreamedSplatMesh.setBudget}.
+     *
+     * Forwarded to `resolveSplatBudget` as `SplatBudgetOptions.cap`.
+     *
+     * @throws {RangeError} at load if not a positive finite number.
+     */
+    budgetCap?: number;
+    /**
+     * Device signals for budget / quality defaults. Defaults to
+     * {@link detectSplatDeviceProfile}. Pass a profile enriched with
+     * {@link probeSplatGpuClass} so desktop integrated GPUs take the laptop
+     * tier instead of the workstation 8M path.
+     */
+    deviceProfile?: SplatDeviceProfile;
+    /**
+     * Ceiling {@link StreamedSplatMesh.setBudget} may raise this mesh to, and the
+     * size its pool is allocated from. Defaults to `budget`.
+     *
+     * Set this above `budget` when a `CameraBudgetGovernor` or `BudgetGovernor`
+     * should be able to *grow* this mesh's share: the pool is allocated once at
+     * construction and never grows, so without headroom reserved here a governed
+     * mesh can only ever be shrunk below the budget it was built with. That is
+     * the whole reason a hand-split `pool / N` marker stays coarse near the
+     * camera - every marker's ceiling was fixed at a quarter of the pool.
+     *
+     * It is not free: the pool costs its *ceiling* in memory whether or not the
+     * budget ever reaches it (~64 B of GPU pool plus ~56 B of CPU backing per
+     * splat, 1.5× for capacity slack). Price it with `estimateSplatPoolBytes`
+     * before choosing - for several markers the
+     * sum of the ceilings is what has to fit, not the shared budget. A ceiling
+     * around 1.5–2× a member's fair share is usually the right trade.
+     *
+     * @throws {RangeError} at load if below `budget`, or not a positive finite
+     * number.
+     */
+    maxBudget?: number;
+    /**
+     * Multiplier on this mesh's LOD detail, matching Spark's per-mesh `lodScale`:
+     * `> 1` refines further (finer cut, more splats drawn), `< 1` coarsens.
+     * Default `1`.
+     *
+     * **`.rad` `foveationMode: 'pagetable'` only** - it scales the frontier cut
+     * the page-table traversal is given (`pixel_scale × lodScale ≤ limit`, exactly
+     * Spark's formula). It does nothing on a mesh with no per-splat cut to scale:
+     * a moderate `.rad` read as a chunk prefix, or a Streamed SOG / LCC scene. For
+     * the GPU cut modes (`'band'` / `'frontier'`) the equivalent is
+     * {@link SplatMeshOptions.foveationTargetPx} at `1 / lodScale`.
+     *
+     * The draw budget still bounds the result, so raising this past the point
+     * where the budget binds sharpens nothing - give the mesh budget as well.
+     */
+    lodScale?: number;
+    /** Explicit format; by default the manifest's extension decides. */
+    format?: StreamedSplatFormat;
+    /** Serializable fetch settings for the manifest and its chunks. */
+    request?: SplatRequestOptions;
+    /**
+     * Cancels the load: the manifest fetch aborts, and {@link StreamedSplatMesh.load}
+     * rejects with a `DOMException` named `AbortError`. A mesh partially built
+     * when the signal fires is disposed - nothing leaks. Only read during load;
+     * later streaming is stopped by {@link SplatMesh.dispose}.
+     */
+    signal?: AbortSignal;
+    /** Base URL a relative manifest URL resolves against (like {@link loadScene}). */
+    baseUrl?: string | URL;
+    /** World-unit distance inside which the finest LOD is used. Default 10. */
+    lodBaseDistance?: number;
+    /** Distance ratio between successive LOD levels. Default 2. */
+    lodMultiplier?: number;
+    /** Cap on decoded chunk arrays cached on the CPU. Default by device memory. */
+    cpuCacheBytes?: number;
+    /**
+     * Foveation ramp for the `.rad` page-table frontier: detail is full inside
+     * `coneFov0` degrees of the view direction, falls off to `coneFoveate` by
+     * `coneFov`, and to `behindFoveate` directly behind the camera. Off-cone
+     * content is kept **coarse**, never dropped, so turning or zooming out never
+     * exposes an unpainted region. Defaults match Spark
+     * ({@link FRONTIER_FOVEATION_DEFAULTS}).
+     */
+    frontierFoveation?: Partial<FrontierFoveation>;
+    /**
+     * Keeps a complete multi-run replacement hidden while its uploads are
+     * spread over frames, then switches the region atomically. Enabled by
+     * default; set `false` only for legacy A/B comparison.
+     */
+    experimentalStagedSwaps?: boolean;
+    /**
+     * Maximum splats copied into the pool per LOD mutation tick. Defaults to
+     * 32,000; lower debug values trade refinement latency for shorter frames.
+     */
+    maxSplatsPerSwap?: number;
+    /**
+     * First-frame reveal policy for classic `.lcc` streaming.
+     *
+     * - `'progressive'`: cells become visible as each L0 coverage group commits
+     *   - can show sparse near-detail while siblings load.
+     * - `'hold-near-l0'` (the default for classic `.lcc` when unset): hide the
+     *   mesh until the camera's home coverage group is resident (L0 when it fits;
+     *   otherwise coarsen via the leaf ladder L1→L2). Neighbours are not part of
+     *   the hold - they compete via screenImportance and would steal the first
+     *   fetch slots. Home selection uses distance within `lodBaseDistance` and
+     *   does not require frustum intersection (HiRes tiles often fail `inView`
+     *   when the camera stands inside looking out). Coarser rungs come from
+     *   `LodSource.runsAtLevelFor`. Only home files are fetched during the hold.
+     *   A one-minute watchdog also degrades if the cut cannot finish. Other
+     *   streamed formats default to `'progressive'` and treat the hold as
+     *   disabled.
+     *
+     * Does not make detail downloads instantaneous; it avoids lower-LOD traffic
+     * and multi-cell buildup before the first useful frame. The hold uses the
+     * **resolved** cut from the first schedule (after camera + format transform),
+     * not distance ambition alone.
+     */
+    initialReveal?: 'progressive' | 'hold-near-l0';
+    /** Receives lightweight LOD swap markers for performance attribution. */
+    onPerformanceEvent?: (event: StreamedSplatPerformanceEvent) => void;
+    /**
+     * View-dependent color (higher-order SH). This is the streaming counterpart
+     * of {@link SplatMeshOptions.shBands}: besides sizing the pool it decides
+     * whether SH is fetched/decoded at all. Two sources feed it - a `Quality` LCC
+     * `Quality` LCC (`.lcc`) capture, which stores SH per splat, and a Streamed SOG scene,
+     * whose per-file palette shN is converted to that same packed form at decode
+     * (M11; see `docs/formats/streamed-shn-notes.md`).
+     *
+     * **For LCC, unset (the default) means every band the capture carries** - so
+     * a Quality scene shows its real view-dependent color without the caller
+     * having to know the format. The exception is a `smooth` performance profile
+     * (the default on mobile), which defaults this to 0: SH roughly triples
+     * per-chunk bandwidth (`shcoef.bin` is 64 B/splat against `data.bin`'s 32) and
+     * adds up to 64 B/splat of pool textures (~384 MB over a 6M-splat pool at 3
+     * bands) - precisely the costs that profile avoids.
+     *
+     * **For Streamed SOG it is strictly opt-in** (unset = off): the manifest does
+     * not declare whether the tiles carry shN, so enabling the conversion - and
+     * the pool textures it needs - must be a deliberate choice, not a default.
+     *
+     * Set it explicitly to override either way: 0 forces SH off, and 1, 2 or 3
+     * keep 3, 8 or 15 coefficients per channel. For LCC the value is clamped to
+     * what the scene actually has (a `Portable` capture fetches and allocates
+     * nothing regardless); for SOG a scene with fewer bands zero-pads and one with
+     * no shN simply renders DC color, wasting the allocated textures.
+     *
+     * Only read at load: the pool's SH textures are allocated once, so a later
+     * {@link SplatMesh.setPerformanceProfile} does not change this.
+     */
+    shBands?: 0 | 1 | 2 | 3;
+    /**
+     * Whether the scene's always-resident environment/background tile (the
+     * `.lcc2` sky) starts visible. Default `true`. Toggle it live afterwards with
+     * {@link StreamedSplatMesh.setEnvironmentEnabled}. No effect on a scene that
+     * ships no environment tile.
+     */
+    environmentEnabled?: boolean;
+    /**
+     * This mesh's share of the scene's fetch bandwidth, as a camera-projected
+     * weight - normally `() => governor.weightOf(mesh) ?? 0`, so fetching is
+     * ordered by the same measure that already orders drawing.
+     *
+     * Read on demand, so it always reflects the current camera. Zero means hidden
+     * or suspended, and has one effect on its own: the background sweep that
+     * pre-warms the whole capture into the page-table cache stops. That sweep is
+     * pure speculation about a camera move that has not happened, and on a
+     * multi-marker scene it is most of the traffic competing with the marker the
+     * viewer is actually looking at.
+     *
+     * Unset (the default) leaves fetching exactly as it was: every mesh sweeps.
+     * Supply a {@link fetchScheduler} as well to also bound the total.
+     */
+    fetchWeight?: () => number;
+    /**
+     * Scene-wide fetch arbitration, shared by every streamed mesh the way a
+     * {@link SplatMeshOptions.pool} is - see {@link ChunkFetchScheduler}. Without
+     * one, each mesh fetches toward its own in-flight cap and a near marker's
+     * detail queues behind a dozen far markers' background traffic.
+     *
+     * The scheduler is *not* owned by the mesh: dispose unregisters this mesh and
+     * leaves the scheduler running for its siblings. Weights come from
+     * {@link fetchWeight}; without that every mesh weighs the same and the
+     * scheduler only bounds the total.
+     */
+    fetchScheduler?: ChunkFetchScheduler;
+    /**
+     * Scene-wide decoded-chunk cache ceiling, shared exactly as
+     * {@link fetchScheduler} and {@link SplatMeshOptions.pool} are - see
+     * {@link ChunkCacheBudget}.
+     *
+     * Without one, each `.rad` page-table mesh caps its own cache at
+     * `max(cpuCacheBytes, min(2 GiB, this capture's decoded size))`: the right
+     * number for a lone streamed scene, and no bound at all across a scene of
+     * markers, because every mesh gets its own and each is sized to its own
+     * capture. With one, that figure becomes this mesh's *ceiling* and the budget
+     * splits a scene total across every registered mesh by camera weight.
+     *
+     * This bounds retention, not prefetching: the background sweep still runs and
+     * still warms the cache, it just stops at the scene's allowance instead of at
+     * the size of the capture.
+     *
+     * The budget is *not* owned by the mesh: dispose unregisters this mesh and
+     * leaves it running for its siblings. Weights come from {@link fetchWeight}.
+     */
+    cacheBudget?: ChunkCacheBudget;
+}
+/** One streamed-LOD mutation tick, measured on the main thread. */
+export interface StreamedSplatPerformanceEvent {
+    /** Timestamp after the tick, on the same clock as requestAnimationFrame. */
+    timestamp: number;
+    /** Main-thread time spent rescheduling and applying this tick. */
+    cpuMs: number;
+    /** Same-frame packed active-index rebuild time, after the LOD mutation. */
+    activeListMs: number;
+    /** Same-frame partial texture upload submission time. */
+    uploadMs: number;
+    /** CPU submission time for the depth-sort passes. */
+    sortSubmitMs: number;
+    /** Exact-height staging textures allocated during this update. */
+    stagingTextureAllocations: number;
+    /** WebGPU source-index ranges queued for upload before this tick's sort. */
+    activeListUpdateRanges: number;
+    appendedCount: number;
+    removedCount: number;
+    stagedCount: number;
+    uploadCount: number;
+    activeCount: number;
+    forcedSort: boolean;
+    compacted: boolean;
+}
+/** Options for {@link StreamedSplatMesh.definePersistentChannel}. */
+export interface PersistentChannelOptions extends SplatChannelOptions {
+    /**
+     * Cap on the number of `(chunk, splat)` edits stored for this channel.
+     * Editing past the cap is dropped with a one-time warning. Default 1,000,000.
+     */
+    maxEdits?: number;
+}
+/**
+ * Streams a large splat scene - a Streamed SOG dataset (`lod-meta.json`), or
+ * an XGRIDS `.lcc2` or `.lcc` (manifest v3–v5) dataset - into the pool of a
+ * dynamic-capacity {@link SplatMesh}, keeping the resident splat count within
+ * a per-device budget.
+ *
+ * Each frame it asks the scene's {@link LodSource} which spatial regions
+ * should be resident for the current camera, fetches and decodes the chunk
+ * files that back them (off the main thread, via {@link ChunkLoader}), and
+ * appends/removes pool ranges to match - loading coarse first so the scene
+ * appears quickly and refining near the camera. A coarse full-scene shell
+ * always fits the budget, so the view is never blank and the budget is
+ * never exceeded.
+ *
+ * WebGPU only (inherited from the dynamic-capacity pool). View-dependent color
+ * (higher-order SH) works for every streamed format: LCC `Quality` captures store it per
+ * splat, and a SOG scene's per-file palette shN is converted to that same
+ * per-splat packed form at decode so it too survives the shared pool (M11, opt
+ * in via {@link StreamedSplatMeshOptions.shBands}; see
+ * `docs/formats/streamed-shn-notes.md`).
+ */
+export declare class StreamedSplatMesh extends SplatMesh {
+    /**
+     * Loads a non-streamed splat file into a worker-built merged hierarchy.
+     * The returned static mesh shares this class's runtime budget contract.
+     */
+    static loadAutoLod(input: string | URL, options: StaticLodSplatMeshLoadOptions): Promise<StaticLodSplatMesh>;
+    private readonly scene;
+    private readonly loader;
+    /**
+     * Cap the *classic* (non-page-table) chunk cache evicts against.
+     *
+     * Mutable because a shared {@link ChunkCacheBudget} re-splits it as the camera
+     * moves; without a budget it stays at the value `options.cpuCacheBytes` or the
+     * device default set at construction.
+     */
+    private cpuCacheBytes;
+    private budgetValue;
+    private readonly maximumBudget;
+    /** Spark's per-mesh `lodScale`; divides the page-table cut limit. */
+    private lodScaleValue;
+    /** Set once the governed budget has been reported as exceeding an explicit
+     * `foveationDrawBudget`, so the warning is issued at most once. */
+    private warnedDrawTargetCap;
+    private readonly stagedSwapsEnabled;
+    /** Classic LCC must keep old cell coverage while a replacement is pending. */
+    private readonly neverRetireCoverageEarly;
+    private readonly appendCap;
+    private readonly onPerformanceEvent;
+    private compactionCount;
+    private readonly cache;
+    /** Running byte total of {@link cache}; maintained by {@link cacheChunk}, eviction and dispose. */
+    private cacheBytesTotal;
+    /** In-flight chunk fetches. The kind is kept so a weight change can shed the
+     * speculative ones without touching the detail that is actually on screen. */
+    private readonly fetching;
+    /** This mesh's camera-projected share of the scene's fetch bandwidth. */
+    private fetchWeight;
+    /** Scene-wide fetch arbitration, when the host shares one; see `requestChunk`. */
+    private readonly fetchScheduler;
+    private readonly fetchHandle;
+    /**
+     * Blob-URL dataset from {@link loadLocal}, owned by this mesh so its object
+     * URLs are revoked on {@link dispose} rather than leaking for the document's
+     * lifetime. Undefined for every network-loaded mesh.
+     */
+    private localSource;
+    /** Scene-wide chunk-cache ceiling, when the host shares one. */
+    private readonly cacheBudget;
+    private cacheBudgetHandle;
+    /**
+     * The cap this mesh's frontier worker is currently evicting against.
+     *
+     * Mirrored on the main thread so `applyCacheAllowance` can skip no-op posts
+     * and so `fetchCounts.cacheLimitBytes` stays truthful between plans.
+     */
+    private cacheLimitBytes;
+    private readonly resident;
+    /** Replacement runs hidden while their pool data is uploaded in bounded segments. */
+    private readonly staged;
+    /** Files awaiting a backoff retry after a transient fetch/decode error. */
+    private readonly retrying;
+    /** Files given up on after {@link MAX_CHUNK_ATTEMPTS} failures. */
+    private readonly failedFiles;
+    /**
+     * When true, each resident run writes its LOD `level` into the `lodLevel`
+     * float channel for false-color debug modifiers.
+     */
+    private lodLevelDebug;
+    private lodLevelChannelReady;
+    private lodLevelScratch;
+    /** Desired-but-not-resident files this tick; protected from cache eviction. */
+    private readonly neededFiles;
+    /** Non-null in `foveationMode: 'pagetable'`: the worker that owns the chunk
+     * cache + traversal + pager off the main thread, and the always-active slab it
+     * pages the returned frontier into. */
+    private readonly frontierWorker;
+    /**
+     * The frontier's slots, as a list of equally sized pages rather than one
+     * contiguous run.
+     *
+     * Slot `i` lives in page `i / slabPageSplats` at offset `i %
+     * slabPageSplats`. The pager only ever addresses slots, so where those
+     * pages sit in the pool is the mesh's business - which is what lets a mesh
+     * hold non-contiguous storage, and ultimately lets several meshes interleave
+     * in one pool instead of each reserving its whole ceiling as one block.
+     * (Spark's pager does the same thing one level down, binding fixed pages to
+     * `(source, chunk)` pairs.)
+     */
+    private readonly slabPages;
+    /** Most slots the slab may ever hold - the construction capacity. */
+    private slabCeiling;
+    /** Slot count the worker's pager was last told about. */
+    private pagerSlots;
+    /** Consecutive ticks the wave gate has held retirements back. */
+    private retireHeldTicks;
+    /** Backing store for {@link planTimings}. */
+    private readonly planTimingsValue;
+    /**
+     * Backing store for {@link fetchCounts}. Lifetime totals, because the question
+     * they answer is about a *steady state* - "this keeps streaming after the view
+     * settled" - which a per-frame or windowed number cannot express.
+     */
+    private readonly fetchCountsValue;
+    /**
+     * The screen-radius band the scene asked for, kept so the band can be scaled
+     * with the solved frontier cut and always relative to the original - scaling
+     * the live values repeatedly would drift. Null when the scene has no band.
+     */
+    private readonly frontierBandBase;
+    /**
+     * Splats per slab page for this mesh: {@link SLAB_PAGE_SPLATS}, or the whole
+     * capacity when that is smaller. Spark can use one fixed page size because
+     * its pool is a single large arena; here a mesh may be smaller than a page,
+     * and rounding it up to one would waste most of the reservation.
+     */
+    private readonly slabPageSplats;
+    /** Target drawn-splat count for the page-table frontier; see the constructor. */
+    private pageTableDrawBudget;
+    /** The unclamped draw target (`foveationDrawBudget` or the default), kept so
+     * `setBudget` can re-derive the effective draw budget when the pool budget
+     * moves (e.g. under a `BudgetGovernor`). */
+    private pageTableDrawTarget;
+    /** Whether {@link pageTableDrawTarget} came from an explicit
+     * `foveationDrawBudget` - a caller-chosen hard cap worth warning about when a
+     * governed budget outgrows it, rather than the library's own default. */
+    private pageTableDrawTargetExplicit;
+    /** Last frontier's drawn (non-degenerate) splat count - the true on-screen size
+     * in `pagetable` mode, where the slab is fully "active" but mostly degenerate. */
+    private pageTableDrawn;
+    /** Monotonic reschedule id; a stale plan (superseded by a newer request) is
+     * dropped. `pageTableInFlight` coalesces to one outstanding traversal. */
+    private pageTableSeq;
+    private pageTableInFlight;
+    private pageTableDisposed;
+    /** Files whose data has been forwarded to the worker (so we don't refetch). */
+    private readonly pageTableCachedFiles;
+    /** Chunks the last frontier wanted but did not have, biggest-on-screen first.
+     * These outrank the background sweep - they are the detail actually on screen. */
+    private pageTableFetchPriority;
+    /** Frontier-cut target node size (px) and foveation ramp; see `frontierView`. */
+    private pageTableTargetPx;
+    private pageTableFoveation;
+    /** Drawing-buffer height, sampled in `update` so `reschedule` can derive the
+     * cut limit the same way the material does (`targetPx / focalY`). */
+    private pageTableViewportY;
+    /** Frontier cut on foveated `size / distance`. Re-derived each reschedule once
+     * the drawing buffer is known; the initial value only covers the first frame. */
+    private pageTableLimit;
+    /**
+     * Whether the worker's cache is sitting at its cap: sweeping past that point
+     * only evicts what the frontier is using.
+     *
+     * Re-derived from every plan rather than latched. It used to latch on the
+     * first eviction, which was safe only while the cap was sized to the capture
+     * and evictions therefore meant "this will never fit". Under a scene-wide
+     * {@link ChunkCacheBudget} evictions are routine - a far mesh gives bytes back
+     * and is trimmed - and latching would kill its sweep for the session, so a
+     * mesh that went cold could never re-warm when the camera returned.
+     */
+    private pageTableCacheAtLimit;
+    /** Per-splat channels whose edits survive chunk eviction/reload (M7.6). */
+    private readonly persistentChannels;
+    /** Chunk-file index of the always-resident environment tile, if the scene ships one. */
+    private readonly envFile;
+    /** Whether the environment tile should be visible; toggled live. */
+    private envEnabled;
+    /** Pool handle of the environment tile once it has loaded (kept for toggling). */
+    private envHandle;
+    /** Env splat count, measured when the tile decodes; 0 until then. */
+    private envSplatCount;
+    /** Set when the env tile is larger than the whole pool - terminal, warned once. */
+    private envUnfit;
+    /**
+     * Classic `.lcc` startup hold. `'capture'` waits for the first schedule after
+     * the host applies the final camera; `'holding'` freezes that nearby-detail set.
+     */
+    private initialRevealPhase;
+    /** Frozen nearby-detail runs for {@link initialRevealPhase} `'holding'`. */
+    private frozenCriticalRuns;
+    /** Timestamp of the final-camera capture that began the current hold. */
+    private initialRevealStartedAt;
+    private initialRevealStateValue;
+    /** Fetch settings this mesh was loaded with, reused for collision meshes. */
+    private readonly requestOptions;
+    /** In-flight or settled collision load; see {@link loadCollisionMeshes}. */
+    private collisionTiles;
+    private collisionAbort;
+    private pendingWork;
+    private lastScheduleTime;
+    /** Reused leaf-coverage bitmap for {@link substituteCoverage}; grows only. */
+    private coverageScratch;
+    private readonly lastCameraPos;
+    private readonly lastCameraQuat;
+    /**
+     * Fetches a scene manifest and prepares a mesh sized to the budget.
+     * Accepts a Streamed SOG manifest (`lod-meta.json`) or an XGRIDS `.lcc2` or
+     * `.lcc` (manifest v3–v5) dataset - all stream through the same machinery. Both LCC
+     * generations are normalized to the established XGRIDS/Spark Three.js
+     * coordinate frame; streamed SOG orientation is unchanged.
+     *
+     * A `.lcc` dataset needs a server that answers HTTP range requests: its
+     * splats live in one large `data.bin` that is never fetched whole.
+     *
+     * @param manifestUrl - URL of the scene's `lod-meta.json`, `.lcc2` or `.lcc`
+     * file; relative URLs resolve against `options.baseUrl` (or the page).
+     * @throws Rejects with {@link SplatLoadError} on any resolve/fetch/parse
+     * failure, or a `DOMException` named `AbortError` when `options.signal` fires.
+     */
+    static load(manifestUrl: string | URL, options?: StreamedSplatMeshOptions): Promise<StreamedSplatMesh>;
+    /**
+     * Prepares a mesh from a folder dropped into the page - the same streamed
+     * formats, read straight off the user's disk with no server and no upload.
+     *
+     * Every file becomes a `blob:` URL, which answers range requests exactly as
+     * an HTTP origin does, so a multi-hundred-megabyte `.lcc` `data.bin` streams
+     * chunk-by-chunk rather than being read whole.
+     *
+     * @param files - The folder's files, keyed by path relative to its root
+     * (as the demo drop-zone `readDirectory` walk produces).
+     * @throws Rejects with {@link SplatLoadError} - phase `'manifest'` when the
+     * folder holds no (or more than one) recognizable scene manifest - or a
+     * `DOMException` named `AbortError` when `options.signal` fires.
+     */
+    static loadLocal(files: ReadonlyMap<string, File>, options?: StreamedSplatMeshOptions): Promise<StreamedSplatMesh>;
+    /** Shared load path: fetch the manifest from a source, then build the scene. */
+    private static fromSource;
+    private constructor();
+    /** Slots the currently reserved pages can hold. */
+    private get slabSlots();
+    /**
+     * Reserves or releases slab pages so the slab can hold `wanted` slots, and
+     * tells the worker's pager the new slot count.
+     *
+     * This is the mechanism that makes a shared pool worth having: storage follows
+     * the governed budget, so approaching a marker grows its pages while the ones
+     * behind you hand theirs back, instead of every marker holding its ceiling for
+     * the whole session. Growth stops at the construction ceiling and at whatever
+     * the pool can actually spare - a mesh that cannot grow simply stays coarse
+     * rather than throwing.
+     */
+    private syncSlabPages;
+    /**
+     * Writes `data` at slot `slot`, splitting the write where it crosses a page
+     * boundary. The pager's runs are contiguous in *slot* space, which page
+     * storage no longer guarantees is contiguous in the pool.
+     */
+    private writeSlabSlots;
+    /** Zeros slots `[slot, slot + count)`, splitting at page boundaries like
+     * {@link writeSlabSlots}, so freed slots hold nothing drawable. */
+    private degenerateSlabSlots;
+    /**
+     * Draws exactly the first `resident` slots: pages below the boundary are
+     * fully active, the page containing it is partially active, the rest are
+     * inactive. Freed tail slots simply leave the active list; they are also
+     * degenerated (see {@link degenerateSlabSlots}) so that even a slot drawn by
+     * mistake shows nothing.
+     */
+    private setSlabResident;
+    /** Typed post to the frontier worker. */
+    private postToWorker;
+    /**
+     * Applies a new decoded-chunk allowance from the scene's shared
+     * {@link ChunkCacheBudget}.
+     *
+     * Only the cap moves; nothing is dropped here. Both cache implementations
+     * evict lazily against it - the page-table worker inside its next
+     * `reschedule`, against a frontier that is still current, and the classic
+     * path in `evictChunks` on the next tick. Dropping chunks synchronously would
+     * pull them out from under resident splats.
+     *
+     * `pageTableCacheAtLimit` is recomputed here rather than waiting for the next
+     * plan, so a *raised* allowance re-arms the background sweep on this tick
+     * instead of one idle interval later.
+     */
+    private applyCacheAllowance;
+    /**
+     * Whether this scene ships collision meshes - true for an XGRIDS `.lcc` /
+     * `.lcc2` dataset that carries them, false for a Streamed SOG scene, which
+     * has none.
+     */
+    get hasCollisionMeshes(): boolean;
+    /**
+     * Fetches and parses this scene's collision geometry: the triangle meshes an
+     * XGRIDS `.lcc` (`collision.lci`) or `.lcc2` (`data/mesh/*.ply`) capture
+     * ships beside its splats, for hosts that want collision, ground probes or
+     * other spatial queries.
+     *
+     * The geometry is source-local, like {@link StreamedScene.bounds} - apply
+     * this mesh's `matrixWorld` to put it in the frame the splats render in.
+     * VLAM! builds no acceleration structure over it and never consults it.
+     *
+     * Tiles are fetched once and cached; concurrent callers share one load, and
+     * a failed load can be retried by calling again. Resolves `[]` for a scene
+     * without collision.
+     *
+     * @throws a `DOMException` named `AbortError` if cancelled, or if
+     * {@link dispose} is called while the load is in flight.
+     */
+    loadCollisionMeshes(options?: {
+        signal?: AbortSignal;
+    }): Promise<readonly CollisionMeshTile[]>;
+    /**
+     * Whether this scene ships an always-resident environment/background tile -
+     * true for an XGRIDS `.lcc2` capture that carries one (its `env.sog` sky),
+     * false for Streamed SOG, `.lcc`, `.rad`, or an `.lcc2` without one.
+     */
+    get hasEnvironment(): boolean;
+    /** Whether the environment tile is currently set to render. */
+    get environmentEnabled(): boolean;
+    /**
+     * Splats in the environment tile, measured when it decoded - the manifest
+     * does not carry the count. 0 until the tile has loaded (or if the scene
+     * ships none). These sit outside the LOD budget, drawing from the pool's
+     * capacity headroom.
+     */
+    get environmentSplatCount(): number;
+    /**
+     * Shows or hides the scene's environment/background tile. The switch is
+     * instant and never refetches: once loaded, the tile stays in the pool and
+     * only its active flag flips. Enabling before the tile has loaded triggers
+     * its (one-time) load on the next update. No-op on a scene without one.
+     */
+    setEnvironmentEnabled(enabled: boolean): void;
+    /** The active-splat budget this mesh keeps within. */
+    get budget(): number;
+    /**
+     * The ceiling {@link setBudget} clamps to - {@link StreamedSplatMeshOptions.maxBudget}
+     * when one was given, otherwise the construction budget.
+     *
+     * The pool was allocated for this number and cannot grow, so it is a hard
+     * limit on what any governor can hand this mesh. Read it to check that a
+     * shared-budget setup can actually deliver the share it is computing.
+     */
+    get maxBudget(): number;
+    /** Alias used by hosts that manage static and streamed auto-LOD uniformly. */
+    get budgetCeiling(): number;
+    /**
+     * The capture's real content size, when the format declares it (`.rad` reports
+     * its leaf count) - the splat count needed to hold this mesh at full
+     * resolution, independent of the budget it was constructed with.
+     *
+     * A host splitting one budget across several streamed meshes should clamp each
+     * share to this: a mesh cannot spend more than it contains, so budget handed
+     * past it buys nothing and is better given to a mesh that can use it. Note it
+     * is *not* `maxBudget`: a foveated `.rad` reports `maxResidentSplats` as the
+     * requested budget, because its pool holds a camera-directed resident set
+     * rather than the whole tree.
+     *
+     * `undefined` when the format does not declare a content size.
+     */
+    get contentSplatCount(): number | undefined;
+    /**
+     * The drawn-splat target currently driving the `.rad` page-table frontier -
+     * the governed budget, capped by
+     * {@link SplatMeshOptions.foveationDrawBudget}. `0` on a mesh that is not in
+     * `foveationMode: 'pagetable'`, which has no frontier to target.
+     *
+     * This is the number that decides how deep the traversal descends, so it is
+     * what to watch when checking that a near mesh really did receive more
+     * detail: {@link budget} is the pool's allowance, this is what is spent.
+     */
+    get drawBudget(): number;
+    /**
+     * Spark's per-mesh `lodScale` (see {@link StreamedSplatMeshOptions.lodScale}).
+     * Mutable: raise it to sharpen a focused mesh, lower it to coarsen a
+     * background one. Page-table `.rad` only.
+     *
+     * @throws {RangeError} if set to a value that is not positive and finite.
+     */
+    get lodScale(): number;
+    set lodScale(value: number);
+    /** In `pagetable` mode the slab is fully active but mostly degenerate, so the
+     * base `activeSplatCount` (slab size) is not the on-screen count - report the
+     * frontier's drawn size instead. */
+    get activeSplatCount(): number;
+    /**
+     * Updates the LOD budget used for future scheduling within allocated capacity.
+     *
+     * @returns the budget actually in effect, which is `budget` clamped to
+     * {@link maxBudget}. A `BudgetGovernor` reads this return value to detect a
+     * capped member and hand the remainder to the others, so the clamp is
+     * reported rather than hidden.
+     */
+    setBudget(budget: number): number;
+    /**
+     * What the LOD scheduler last decided, or `undefined` on sources that do not
+     * schedule by leaf (the `.rad` page table, prefix readers).
+     *
+     * Distinct from {@link activeSplatCount}, and the distinction is the whole
+     * point: `desired` is what the scheduler asked for, `activeSplatCount` is
+     * what the pool ended up drawing. Equal means the cut is applied; `desired`
+     * far below the budget means the *scheduler* declined to spend it, which is a
+     * different bug from the mesh failing to apply what it was given.
+     */
+    get lodStats(): Readonly<{
+        inFrustum: number;
+        leaves: number;
+        desired: number;
+        filled: number;
+    }> | undefined;
+    /** Number of chunk files currently decoded and held. In page-table mode the
+     * worker owns the cache - the main-thread map is always empty there, so report
+     * what has been forwarded to it instead of a permanent zero. */
+    get residentChunkCount(): number;
+    /** Chunk fetches currently in flight. */
+    get pendingChunkCount(): number;
+    /**
+     * Main-thread cost of applying paging plans in `foveationMode: 'pagetable'`.
+     *
+     * A plan is applied whole, off the render loop's own timing, so its cost does
+     * not appear in {@link getUpdateTimings} - but it lands on the same thread and
+     * a churning frontier can make it the largest stall in a frame. `worst*`
+     * accumulate over the mesh's lifetime; the rest describe the most recent plan.
+     */
+    get planTimings(): Readonly<{
+        applyMs: number;
+        worstApplyMs: number;
+        writeMs: number;
+        residentMs: number;
+        moves: number;
+        appends: number;
+        worstSplats: number;
+    }>;
+    /**
+     * Lifetime chunk-fetch totals by kind, plus page-table cache state.
+     *
+     * Diagnostic for the question "why is this still streaming after the view
+     * settled?", which the three fetch sources answer differently and which no
+     * other reading distinguishes:
+     *
+     * - **`sweep` climbing** - speculative file-order pre-warming of the whole
+     *   capture. Declined by the `smooth` profile; see `sweepAllowed`.
+     * - **`priority` / `base` climbing while `evicted` climbs too** - the
+     *   frontier's touched set does not fit the worker cache, so chunks are
+     *   evicted and immediately refetched. Streaming never ends because it cannot.
+     * - **`priority` / `base` climbing with `evicted` flat** - ordinary refinement
+     *   still converging on the cut; it should stop on its own.
+     *
+     * `uncovered` and `retiredEarly` answer a different question - "why are there
+     * holes?" - and between them cover both ways this class can render nothing
+     * where it should render something:
+     *
+     * - **`uncovered` climbing after the scene settles** - `substituteCoverage`
+     *   wanted a leaf's coarsest level as a stand-in and its chunk was not
+     *   cached. Expected briefly during initial load; afterwards it should not
+     *   move, because the coarsest files are pinned against eviction.
+     * - **`retiredEarly` climbing** - coverage was retired before its replacement
+     *   landed, under pool pressure or past the retirement hold bound. This is
+     *   the swap path rather than the substitute path, and it is the one that
+     *   scales with the budget.
+     *
+     * Both are counted in whole leaves/groups, monotonically: they answer "did
+     * this happen, and is it still happening", not "how much is missing now".
+     */
+    get fetchCounts(): Readonly<{
+        priority: number;
+        base: number;
+        sweep: number;
+        evicted: number;
+        uncovered: number;
+        retiredEarly: number;
+        cacheFull: boolean;
+        cacheBytes: number;
+        cacheLimitBytes: number;
+    }>;
+    /** Chunk files given up on after repeated fetch/decode failures. */
+    get failedChunkCount(): number;
+    /**
+     * Forgets all permanent chunk failures so their regions are fetched again.
+     * Failures are otherwise terminal for the mesh's lifetime - call this when
+     * the cause was transient (e.g. connectivity restored, `online` event).
+     */
+    retryFailedChunks(): void;
+    /**
+     * Whether the scene is still resolving toward its target detail - chunks
+     * are fetching, or a retry/append is pending. Goes false once the view
+     * has settled (useful to drive a loading indicator).
+     */
+    get isStreaming(): boolean;
+    /** The LOD distance model (mutable; e.g. raise to force the finest level). */
+    get lodBaseDistance(): number;
+    set lodBaseDistance(value: number);
+    update(camera: THREE.PerspectiveCamera, renderer: THREE.WebGPURenderer, options?: SplatUpdateOptions): void;
+    /** Root bounds of the whole scene, valid before any chunk has loaded. */
+    computeSplatBounds(): THREE.Box3;
+    /**
+     * Enables or disables writing each resident run's **resolved** LOD level into
+     * the `lodLevel` float channel (for a false-color debug modifier: 0 = finest).
+     * Values come from applied desired runs after budget resolution - not from
+     * distance ambition alone. Call before assigning a modifier that reads the channel.
+     */
+    setLodLevelDebug(enabled: boolean): void;
+    /** Whether {@link setLodLevelDebug} is currently writing levels. */
+    get isLodLevelDebug(): boolean;
+    /**
+     * Startup-hold progress for {@link StreamedSplatMeshOptions.initialReveal}.
+     * Classic `.lcc` hosts using the default (or explicitly opting into
+     * `'hold-near-l0'`) should keep the mesh invisible while
+     * `status === 'pending'`, then reveal on `'ready'` or `'degraded'`.
+     */
+    get initialRevealState(): InitialRevealState;
+    /**
+     * Captures a fresh classic `.lcc` nearby-detail startup set on the next
+     * {@link update}. Hosts that apply their final initial camera pose after the
+     * mesh first receives frames should call this before lifting their loading
+     * cover. It is a no-op for every other format and for progressive startup.
+     */
+    recaptureInitialReveal(): void;
+    private writeLodLevelChannel;
+    /**
+     * Declares a per-splat channel whose values **persist across LOD churn**:
+     * edits are stored sparsely keyed by `(chunk file, local index)` - a stable
+     * splat identity in the streaming design - and re-applied whenever a chunk
+     * is (re)appended. Paint a region with {@link paintPersistent}, orbit away
+     * until it is evicted, come back, and the values return. See M7.6.
+     *
+     * Wraps {@link SplatMesh.defineChannel}; read it from a modifier with
+     * `ctx.channel(name)` as usual.
+     */
+    definePersistentChannel(name: string, options?: PersistentChannelOptions): void;
+    /**
+     * Sets a persistent channel to `value` for every currently-resident splat
+     * within `radius` (world units) of `worldPoint`, and records the edit so it
+     * survives eviction/reload. Splats whose chunk is not currently decoded on
+     * the CPU cannot be located and are skipped (they are usually far from the
+     * camera); their painted neighbours in resident chunks are unaffected.
+     *
+     * The radius assumes this mesh's world transform is rigid (rotation +
+     * translation, as the built-in format transforms are); a scaled mesh would
+     * distort the brush. Edit a persistent channel only through this method -
+     * direct {@link SplatMesh.writeChannel} writes are not recorded and are
+     * overwritten by the next re-apply.
+     *
+     * @returns the number of splats edited this call.
+     * @throws {Error} if the channel was not declared with
+     *   {@link definePersistentChannel}.
+     */
+    paintPersistent(name: string, worldPoint: THREE.Vector3, radius: number, value: number): number;
+    /**
+     * Clears every stored edit for a persistent channel and zeroes the value on
+     * all currently-resident splats. Chunks that are not resident are covered by
+     * the emptied store - they reload at the channel's fill value.
+     *
+     * @throws {Error} if the channel is not a persistent channel.
+     */
+    clearPersistentChannel(name: string): void;
+    dispose(): void;
+    private shouldReschedule;
+    private reschedule;
+    private rowAlignedSplats;
+    /**
+     * Startup hold seeds: the coverage group containing (or nearest to) the
+     * camera within {@link LodSource.lodBaseDistance}. HiRes tiles often fail the
+     * frustum test when most of the cell sits behind the camera - do **not**
+     * require `inView`, or the hold seeds a screen-facing neighbour instead.
+     * Coarser home levels come from {@link LodSource.runsAtLevelFor}.
+     */
+    private selectHomeSeedRuns;
+    private coarsenHomeRuns;
+    private criticalRunsFitCapacity;
+    private publishInitialRevealProgress;
+    private releaseInitialReveal;
+    private captureOrContinueInitialReveal;
+    /** After staging/commits, release the hold when every frozen run is resident. */
+    private finishInitialRevealIfComplete;
+    /** Creates a marker for a changed streamed-LOD tick, if any. */
+    private createPerformanceEvent;
+    /** Returns whether all new rows can coexist with the currently visible region. */
+    private canStageGroup;
+    /**
+     * Uploads a bounded part of a replacement without rendering it.
+     * Skips runs whose chunks are not yet cached so siblings can stage out of order.
+     */
+    private stageGroup;
+    /** Switches a fully staged region from old to new visibility in one tick. */
+    private commitStagedGroup;
+    /**
+     * Applies one swap group atomically within this tick: removals first
+     * (freeing pool rows for the replacements), then all adds. Returns false
+     * without touching anything when the group cannot fit even after its own
+     * removals - the caller defers it and the old runs keep rendering.
+     */
+    private applyGroup;
+    /** Appends one run from the cache, compacting the pool on fragmentation. */
+    private appendRun;
+    /**
+     * Writes the stored edits for one run's `[offset, offset + count)` splats
+     * into its freshly appended pool range. No-op when the file has no edits.
+     */
+    private applyPersistentRun;
+    /**
+     * Covers a deferred group's leaves that no resident run covers with each
+     * leaf's coarsest (pinned, hence cached) level, so a region waiting on a
+     * fetch shows coarse detail instead of nothing. The substitutes are
+     * intentionally not "desired": the next reschedule swaps them for the
+     * real level once its chunk has arrived.
+     *
+     * Near-camera refinements (`distance <= lodBaseDistance`) skip the coarse
+     * paint and its pin fetch entirely - cold load requests only the target cut
+     * for that cell. Far gaps keep the shell.
+     */
+    private substituteCoverage;
+    /** Issues pending classic-path chunk wants in group-priority order. */
+    private flushClassicFetches;
+    /**
+     * A camera turn must not wait for all eight old visible requests to finish.
+     * Only classic requests carry a precise rank; page-table work retains its
+     * own scheduler and is never cancelled here.
+     */
+    private preemptClassicFetches;
+    /**
+     * Loads the always-resident environment tile once, on the first update after
+     * it is wanted. The tile has no LOD ladder and no manifest count, so it is
+     * appended whole (measuring its splat count at decode) and thereafter toggled
+     * by flipping its pool range active - never scheduled, refetched, or evicted.
+     */
+    private updateEnvironment;
+    /**
+     * Page-table reschedule (`foveationMode: 'pagetable'`): posts the camera to the
+     * worker, which owns the cache + traversal + pager and replies asynchronously
+     * with a paging plan. Coalesced to one outstanding request so the main thread
+     * never blocks. Also drives chunk fetching, in priority order.
+     */
+    private reschedulePageTable;
+    /**
+     * Applies a paging plan from the worker to the slab - fast memcpy writes only,
+     * no traversal or gather on the main thread - then fetches the chunks the
+     * frontier wants next, and reschedules again if chunks are still streaming.
+     */
+    private applyFrontierPlan;
+    /** Forwards a decoded chunk's arrays to the worker (buffers transferred) so the
+     * worker's cache/traversal/gather can use it. */
+    private forwardChunkToWorker;
+    /** Parallel chunk fetches. HTTP/2 multiplexes them; on HTTP/1.1 the browser's
+     * per-host cap simply queues. Same cap for classic and pagetable so near
+     * detail is not structurally starved on the non-pagetable path. */
+    private get maxInflight();
+    /**
+     * Whether this mesh may run its speculative background sweep. A mesh with no
+     * weight is hidden or suspended; a mesh with no `fetchWeight` at all is a
+     * host that never asked for arbitration, and keeps the old behaviour.
+     */
+    /**
+     * Sets this mesh's share of the scene's fetch bandwidth, as
+     * {@link StreamedSplatMeshOptions.fetchWeight} does at load.
+     *
+     * The weight normally closes over the mesh itself (`() =>
+     * governor.weightOf(mesh)`), which a host cannot express until `load`
+     * resolves - hence a setter as well as an option. Pass `undefined` to go back
+     * to unarbitrated sweeping.
+     */
+    setFetchWeight(weight: (() => number) | undefined): void;
+    private sweepAllowed;
+    /** Aborts in-flight fetches of one kind; their slots return through `finally`. */
+    private abortFetches;
+    private requestChunk;
+    /**
+     * Stores a decoded chunk while keeping {@link cacheBytesTotal} in step. The
+     * counter replaces a full-cache re-sum on every reschedule; every mutation
+     * of {@link cache} (this method, eviction, dispose's clear) maintains it.
+     */
+    private cacheChunk;
+    private evictChunks;
+}