@voluma/vlam 0.2.4 → 0.3.2

package/dist/streaming/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@voluma/vlam/streaming` - budgeted LOD streaming for scenes larger than
+ * GPU memory.
+ *
+ * {@link StreamedSplatMesh.load} opens Streamed SOG, LCC / `.lcc2`, and Spark
+ * `.rad`. Shared loading errors and request types are re-exported so a host
+ * that only imports this entry can still name them.
+ *
+ * Static auto-LOD lives on `@voluma/vlam/static-lod`.
+ *
+ * @module streaming
+ */
+export { StreamedSplatMesh, type StreamedSplatMeshOptions, type InitialRevealState, type PersistentChannelOptions, type StreamedSplatPerformanceEvent, } from './streamed-splat-mesh';
+export { BudgetGovernor, type BudgetGovernorOptions, type BudgetGovernedMember, } from './budget-governor';
+export { CameraBudgetGovernor, type CameraBudgetGovernorOptions, type CameraBudgetMember, type CameraBudgetMemberOptions, } from './camera-budget-governor';
+export { ChunkFetchScheduler, type ChunkFetchSchedulerOptions, type ChunkFetchClient, type ChunkFetchHandle, type ChunkFetchKind, } from './chunk-fetch-scheduler';
+export { ChunkCacheBudget, type ChunkCacheBudgetOptions, type ChunkCacheClient, type ChunkCacheHandle, } from './chunk-cache-budget';
+export { httpDatasetSource, createLocalDataset } from './dataset-source';
+export type { SplatDatasetSource, LocalDataset } from './dataset-source';
+export type { CollisionMeshTile } from '../formats/lcc/collision-mesh';
+export type { SplatCollisionData, CollisionMeshDescriptor, EnvironmentTile } from './lod-source';
+export { resolveCpuCacheBytes } from '../core/splat-budget';
+export { SplatLoadError, isAbortError, type SplatProgressCallback, type StreamedSplatFormat, type SplatRequestOptions, type SplatLoadPhase, type SplatInputOptions, } from '../loaders/loading';

package/dist/{lod-scheduler.d.ts → streaming/lod-scheduler.d.ts}

@@ -205,7 +205,7 @@ export declare class LodScheduler implements LodSource {
      * Uses leftover budget to restore detail after {@link enforceBudget}
      * demoted leaves, nearest first, while the total stays under the fill
      * target. By default this may also refine *past* the distance-chosen level
-     * when headroom remains (octree / pagetable streams). With
+     * when headroom remains (octree / page-table streams). With
      * {@link fillPastDistance} false (classic LCC), fill never goes finer than
      * each leaf's distance-selected level - so a cell at the L1 band does not
      * fetch L0 only to demote moments later with the camera still.

package/dist/{lod-source.d.ts → streaming/lod-source.d.ts}

@@ -1,9 +1,9 @@
 import * as THREE from 'three/webgpu';
 import { type LodRun } from './lod-scheduler';
-import type { ChunkFileFormat } from './loading';
-import type { RadChunkRangeRequest } from './load-worker-protocol';
-import type { LccChunkParams } from './formats/lcc/parse-lcc';
-import type { SplatData } from './splat-data';
+import type { ChunkFileFormat } from '../loaders/loading';
+import type { RadChunkRangeRequest } from '../loaders/load-worker-protocol';
+import type { LccChunkParams } from '../formats/lcc/parse-lcc';
+import type { SplatData } from '../core/splat-data';
 import type { SplatDatasetSource } from './dataset-source';
 /**
  * Per-frame LOD decision maker: given the camera, returns the set of runs
@@ -106,7 +106,7 @@ export interface CollisionMeshDescriptor {
  * Coordinates are source-local, the same frame as {@link StreamedScene.bounds}:
  * {@link StreamedScene.formatTransform} maps them to world.
  */
-export interface SceneCollision {
+export interface SplatCollisionData {
     readonly meshes: readonly CollisionMeshDescriptor[];
 }
 /**
@@ -155,7 +155,7 @@ export interface StreamedScene {
      */
     readonly formatTransform?: THREE.Matrix4;
     /** Optional collision geometry the format ships; undefined when it has none. */
-    readonly collision?: SceneCollision;
+    readonly collision?: SplatCollisionData;
     /**
      * Optional always-resident environment tile the format ships outside its LOD
      * structure (the `.lcc2` sky) - present only when the dataset carries one.
@@ -175,13 +175,13 @@ export interface StreamedScene {
     /**
      * Splats per chunk file, so a `(file, localIndex)` pair maps to a stable global
      * splat index (`file * chunkSize + local`). Set by `.rad`; the page-table
-     * renderer (`foveationMode: 'pagetable'`) keys frontier splats by that global.
+     * renderer (`foveationMode: 'page-table'`) keys frontier splats by that global.
      */
     readonly chunkSize?: number;
     /**
      * A chunk the scene builder already fetched and decoded (`.rad` decodes chunk
      * 0 for the scene bounds and the SH codebook). Handing it straight to the
-     * renderer saves a second round trip - and in `pagetable` mode it is what
+     * renderer saves a second round trip - and in `page-table` mode it is what
      * seeds the worker's tree roots, without which the first traversals return an
      * empty frontier and the view stays blank until chunk 0 arrives a second time.
      */
@@ -191,7 +191,7 @@ export interface StreamedScene {
     };
     /**
      * Source-local xyz subsample of the coarsest overview (`.rad` chunk 0).
-     * Survives after pagetable mode transfers chunk-0 buffers to the worker, so
+     * Survives after page-table mode transfers chunk-0 buffers to the worker, so
      * a host can estimate terrain height before any later chunk decodes.
      */
     readonly overviewPositions?: Float32Array;

package/dist/{streamed-splat-mesh-utils.d.ts → streaming/streamed-splat-mesh-utils.d.ts}

@@ -1,6 +1,6 @@
 /** Scheduling and data helpers shared by the streamed mesh implementation. */
-import type { SplatRange } from './splat-mesh';
-import type { SplatData } from './splat-data';
+import type { SplatRange } from '../core/splat-mesh';
+import type { SplatData } from '../core/splat-data';
 import type { LodRun } from './lod-scheduler';
 /** One resident entry: the run description plus its pool handle. */
 type ResidentEntry = [string, {

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

@@ -1,12 +1,11 @@
 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 { SplatMesh, type SplatChannelOptions, type SplatMeshOptions, type SplatUpdateOptions } from '../core/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 { CollisionMeshTile } from '../formats/lcc/collision-mesh';
+import { type SplatRequestOptions, type StreamedSplatFormat } from '../loaders/loading';
+import { type SplatDeviceProfile } from '../core/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';
 /**
@@ -87,13 +86,13 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * 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.
+     * the whole reason a hand-split `pool / N` mesh stays coarse near the
+     * camera - every mesh'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
+     * before choosing - for several additional meshes 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.
      *
@@ -101,12 +100,23 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * number.
      */
     maxBudget?: number;
+    /**
+     * Lets a host that pins {@link budget} and/or {@link maxBudget} still take the
+     * finest-level lift for `.rad` strategy selection and pool sizing. Without it,
+     * pinning either option disables the lift and a capture whose leaf count sits
+     * between the host ceiling and {@link FOVEATION_LEAF_THRESHOLD} incorrectly
+     * lands on the foveated page-table path instead of the prefix reader.
+     *
+     * {@link budgetCap} still vetoes the lift when set. Mobile and fill-constrained
+     * desktops remain exempt inside {@link liftBudgetToFinestLevel}.
+     */
+    allowFinestLevelLift?: boolean;
     /**
      * 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
+     * **`.rad` `foveationMode: 'page-table'` 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
@@ -128,7 +138,7 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * later streaming is stopped by {@link SplatMesh.dispose}.
      */
     signal?: AbortSignal;
-    /** Base URL a relative manifest URL resolves against (like {@link loadScene}). */
+    /** Base URL a relative manifest URL resolves against (like {@link loadSplatData}). */
     baseUrl?: string | URL;
     /** World-unit distance inside which the finest LOD is used. Default 10. */
     lodBaseDistance?: number;
@@ -186,7 +196,7 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * to `'progressive'`.
      */
     initialReveal?: 'progressive' | 'hold-near-l0' | 'hold-coverage';
-    /** Receives lightweight LOD swap markers for performance attribution. */
+    /** Receives lightweight LOD mutation events for performance attribution. */
     onPerformanceEvent?: (event: StreamedSplatPerformanceEvent) => void;
     /**
      * View-dependent color (higher-order SH). This is the streaming counterpart
@@ -234,7 +244,7 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * 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
+     * multi-mesh scene it is most of the traffic competing with the mesh the
      * viewer is actually looking at.
      *
      * Unset (the default) leaves fetching exactly as it was: every mesh sweeps.
@@ -244,8 +254,8 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
     /**
      * 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.
+     * one, each mesh fetches toward its own in-flight cap and a near mesh's
+     * detail queues behind a dozen far meshes' 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
@@ -261,7 +271,7 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * 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
+     * additional meshes, 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.
      *
@@ -328,11 +338,6 @@ export interface PersistentChannelOptions extends SplatChannelOptions {
  * `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;
     /**
@@ -399,7 +404,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
     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
+    /** Non-null in `foveationMode: 'page-table'`: 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;
@@ -454,8 +459,17 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * 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. */
+     * in `page-table` mode, where the slab is fully "active" but mostly degenerate. */
     private pageTableDrawn;
+    private frontierConverged;
+    private pendingFrontierSplats;
+    private staleResidentSplats;
+    private lastPlanAppends;
+    private lastPlanMoves;
+    private lastPlanGeneration;
+    private lastPlanBudget;
+    private lastPlanCamera;
+    private firstFrontierCamera;
     /** Monotonic reschedule id; a stale plan (superseded by a newer request) is
      * dropped. `pageTableInFlight` coalesces to one outstanding traversal. */
     private pageTableSeq;
@@ -563,8 +577,8 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * 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 governed budget, so approaching a mesh grows its pages while the ones
+     * behind you hand theirs back, instead of every mesh 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.
@@ -680,17 +694,37 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * `undefined` when the format does not declare a content size.
      */
     get contentSplatCount(): number | undefined;
+    /**
+     * Which `.rad` streaming strategy this mesh selected at load, or `null` when
+     * the scene is not a Spark `.rad` capture.
+     */
+    get radStrategy(): 'prefix' | 'page-table' | null;
     /**
      * 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.
+     * `foveationMode: 'page-table'`, 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;
+    /**
+     * Page-table frontier coherence for hosts that gate preload/transitions.
+     * `undefined` fields stay 0 when this mesh is not in page-table mode.
+     */
+    get frontierState(): Readonly<{
+        frontierConverged: boolean;
+        pendingFrontierSplats: number;
+        staleResidentSplats: number;
+        lastPlanAppends: number;
+        lastPlanMoves: number;
+        planGeneration: number;
+        planBudget: number;
+        lastPlanCamera: readonly [number, number, number] | null;
+        firstFrontierCamera: readonly [number, number, number] | null;
+    }>;
     /**
      * Spark's per-mesh `lodScale` (see {@link StreamedSplatMeshOptions.lodScale}).
      * Mutable: raise it to sharpen a focused mesh, lower it to coarsen a
@@ -700,7 +734,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
      */
     get lodScale(): number;
     set lodScale(value: number);
-    /** In `pagetable` mode the slab is fully active but mostly degenerate, so the
+    /** In `page-table` 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;
@@ -736,7 +770,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
     /** Chunk fetches currently in flight. */
     get pendingChunkCount(): number;
     /**
-     * Main-thread cost of applying paging plans in `foveationMode: 'pagetable'`.
+     * Main-thread cost of applying paging plans in `foveationMode: 'page-table'`.
      *
      * 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
@@ -906,7 +940,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * and it starts enabled. Failed / unfit / disabled tiles do not block reveal.
      */
     private environmentPendingForReveal;
-    /** Creates a marker for a changed streamed-LOD tick, if any. */
+    /** Creates a performance event for a changed streamed-LOD tick, if any. */
     private createPerformanceEvent;
     /** Returns whether all new rows can coexist with the currently visible region. */
     private canStageGroup;
@@ -963,7 +997,7 @@ export declare class StreamedSplatMesh extends SplatMesh {
     /** Ranks the env tile ahead of every LOD want in {@link flushClassicFetches}. */
     private enqueueEnvironmentFetch;
     /**
-     * Page-table reschedule (`foveationMode: 'pagetable'`): posts the camera to the
+     * Page-table reschedule (`foveationMode: 'page-table'`): 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.
@@ -979,8 +1013,8 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * 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. */
+     * per-host cap simply queues. Same cap for classic and page-table so near
+     * detail is not structurally starved on the non-page-table path. */
     private get maxInflight();
     /**
      * Whether this mesh may run its speculative background sweep. A mesh with no