@voluma/vlam 0.2.2 → 0.2.4

package/dist/relighting-pass.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Host-safe lighting-map pass for {@link SplatMesh.setRelighting}.
+ *
+ * The relight example is a sidecar `render(relightScene, camera)` into an RT.
+ * That only fills TSL `shadow()` maps when the renderer looks like a fresh
+ * `createSplatRenderer` (`autoClear` true, no tone-map wrap). Host apps often
+ * already own a `WebGPURenderer` with `autoClear: false` and an inline ACES /
+ * sRGB `contextNode`. This helper isolates those for one pass, then restores
+ * them, so the example works in a custom scene.
+ *
+ * Important: do **not** assign `contextNode = undefined`. WebGPURenderer reads
+ * `contextNode.id` while building render objects; clearing it throws and the
+ * lighting RT never fills.
+ */
+import * as THREE from 'three/webgpu';
+/**
+ * Minimal renderer surface {@link renderRelightingFactorMap} needs. A real
+ * `THREE.WebGPURenderer` satisfies this; tests can pass a stub.
+ */
+export type RelightingFactorRenderer = {
+    autoClear: boolean;
+    shadowMap: {
+        enabled: boolean;
+        autoUpdate?: boolean;
+    };
+    getDrawingBufferSize(target: THREE.Vector2): THREE.Vector2;
+    getRenderTarget(): THREE.RenderTarget | null;
+    getActiveCubeFace(): number;
+    getActiveMipmapLevel(): number;
+    getMRT(): THREE.MRTNode | null;
+    setMRT(mrt: THREE.MRTNode | null): void;
+    setRenderTarget(target: THREE.RenderTarget | null, activeCubeFace?: number, activeMipmapLevel?: number): void;
+    getClearColor(target: THREE.Color): THREE.Color;
+    getClearAlpha(): number;
+    setClearColor(color: THREE.ColorRepresentation, alpha?: number): void;
+    clear(): void;
+    render(scene: THREE.Object3D, camera: THREE.Camera): void;
+    contextNode: unknown;
+};
+/**
+ * Renders `scene` from `camera` into `target` as a shadow-factor map:
+ * resizes to the drawing buffer, clears **white + A0**, forces `autoClear`
+ * and shadow maps on, and swaps in a passthrough `contextNode` so a host
+ * ACES/sRGB wrap cannot turn the linear multiplier into speckle.
+ *
+ * Call each frame **before** `splats.update` / the main splat draw. Restore
+ * is guaranteed even if `render` throws.
+ */
+export declare function renderRelightingFactorMap(renderer: RelightingFactorRenderer, scene: THREE.Scene, camera: THREE.Camera, target: THREE.RenderTarget): void;

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

@@ -54,7 +54,7 @@ export declare function isClassicLccSwapSet(groups: readonly SwapGroup[]): boole
  */
 export declare function compareClassicSwapGroups(a: SwapGroup, b: SwapGroup): number;
 /** One classic-path chunk want, ranked before {@link StreamedSplatMesh} issues it. */
-export type ClassicFetchPhase = 'finest-target' | 'coverage' | 'target' | 'background';
+export type ClassicFetchPhase = 'environment' | 'finest-target' | 'coverage' | 'target' | 'background';
 export interface ClassicFetchWant {
     /** Cross-mesh scheduler kind derived from {@link phase}. */
     kind: 'priority' | 'base';

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

@@ -173,9 +173,11 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      *   A one-minute watchdog also degrades if the cut cannot finish.
      * - `'hold-coverage'` (the default for `.lcc2` when unset): hide the mesh
      *   until every in-view finest cell has a coarsest covering node resident
-     *   (any LOD). Does not wait for finest tiles or the rest of the stream.
-     *   An empty frustum falls back to the nearest cell. Requires
-     *   `LodSource.coverageRunsFor`; other formats treat this as disabled.
+     *   (any LOD), and until the always-resident environment tile is in the pool
+     *   when the scene ships one and it starts enabled. Does not wait for finest
+     *   tiles or the rest of the stream. An empty frustum falls back to the
+     *   nearest cell. Requires `LodSource.coverageRunsFor`; other formats treat
+     *   this as disabled.
      *
      * A one-minute watchdog degrades to progressive if the frozen set cannot
      * finish. Does not make detail downloads instantaneous. Classic `.lcc` uses
@@ -899,6 +901,11 @@ export declare class StreamedSplatMesh extends SplatMesh {
     private captureOrContinueInitialReveal;
     /** After staging/commits, release the hold when every frozen run is resident. */
     private finishInitialRevealIfComplete;
+    /**
+     * Startup hold still needs the environment tile when the scene ships one
+     * 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. */
     private createPerformanceEvent;
     /** Returns whether all new rows can coexist with the currently visible region. */
@@ -949,8 +956,12 @@ export declare class StreamedSplatMesh extends SplatMesh {
      * 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.
+     * When `pending` is supplied, a miss is ranked as an `'environment'` want so
+     * it issues ahead of LOD coverage.
      */
     private updateEnvironment;
+    /** Ranks the env tile ahead of every LOD want in {@link flushClassicFetches}. */
+    private enqueueEnvironmentFetch;
     /**
      * Page-table reschedule (`foveationMode: 'pagetable'`): posts the camera to the
      * worker, which owns the cache + traversal + pager and replies asynchronously

package/dist/worker-sorter.d.ts

@@ -20,8 +20,21 @@ export declare class WorkerSorter implements SplatSorter {
     private disposed;
     /** The active spans the in-flight sort was computed against. */
     private sentSpans;
+    private submittedCount;
+    private completedCount;
+    private lastSubmittedAt;
+    private lastCompletedAt;
+    private lastLatencyMs;
     constructor(host: WorkerSorterHost);
     sort(modelView: THREE.Matrix4, _activeCount: number, _bounds: THREE.Sphere): boolean;
+    /** Internal timing diagnostics used by the demo's opt-in XR A/B harness. */
+    snapshot(): {
+        submittedCount: number;
+        completedCount: number;
+        lastSubmittedAt: number;
+        lastCompletedAt: number;
+        lastLatencyMs: number;
+    };
     dispose(): void;
     /** Sends written pool rows to keep the worker's centers mirror current. */
     private pushCenters;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voluma/vlam",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "VLAM! - A lightweight WebGPU Gaussian splat viewer for three.js, built for high performance, streaming LOD, and fully customizable rendering through an open shader pipeline.",
   "license": "MIT",
   "author": "Voluma",