@voluma/vlam 0.2.3 → 0.3.0

package/dist/chunk-loader-DlNwggfG.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-loader-DlNwggfG.js","sources":["../src/lib/chunk-loader.ts"],"sourcesContent":["import type { SplatData } from './splat-data';\nimport type {\n  LoadWorkerRequest,\n  LoadWorkerResponse,\n  LoadWorkerSource,\n  RadChunkRangeRequest,\n} from './load-worker-protocol';\nimport type { LccChunkParams } from './formats/lcc/parse-lcc';\nimport {\n  createAbortError,\n  deserializeSplatLoadError,\n  resolveSplatUrl,\n  SplatLoadError,\n  splatFormatForExtension,\n  splatNameExtension,\n  splatUrlExtension,\n  type ChunkFileFormat,\n  type SplatDataFileLoadOptions,\n  type SplatFormat,\n  type SplatInputOptions,\n  type SplatDataFormat,\n  type SplatProgressCallback,\n} from './loading';\n// Inlined worker (blob URL): survives library bundling in any consumer\n// setup, unlike an asset file referenced via `new URL(...)`.\nimport LoadWorker from './load-worker?worker&inline';\n\n/**\n * Formats served by the one-shot worker rather than the streaming one.\n *\n * Both workers are inlined, so their parsers are string literals no bundler can\n * tree-shake. Keeping these three behind a dynamic import is what moves SPZ's\n * ~39 KB ZSTD wasm blob out of the main entry and into a chunk that loads only\n * when one of these formats is actually opened.\n */\nconst ONE_SHOT_FORMATS = new Set<ChunkFileFormat>(['spz', 'splat', 'ksplat']);\n\n/**\n * One worker plus the requests in flight on it.\n *\n * `ChunkLoader` runs two of these - see {@link ChunkLoader} - so the request\n * bookkeeping, cancellation and terminal-failure handling live here once.\n */\nclass WorkerClient {\n  private nextRequestId = 0;\n  private readonly pending = new Map<\n    number,\n    {\n      resolve: (data: SplatData) => void;\n      reject: (error: Error) => void;\n      removeAbortListener?: () => void;\n      onProgress?: SplatProgressCallback;\n    }\n  >();\n  private disposed = false;\n  /** Terminal worker failure; subsequent loads reject instead of hanging. */\n  private workerFailure: SplatLoadError | null = null;\n\n  constructor(private readonly worker: Worker) {\n    this.worker.onmessage = (event: MessageEvent<LoadWorkerResponse>) => {\n      const request = this.pending.get(event.data.id);\n      if (!request) return;\n      if (event.data.type === 'progress') {\n        // Progress does not settle the request; the result still follows.\n        request.onProgress?.(event.data.loaded, event.data.total);\n        return;\n      }\n      this.pending.delete(event.data.id);\n      request.removeAbortListener?.();\n      if (event.data.ok) {\n        request.resolve(event.data.data);\n      } else if (event.data.cancelled) {\n        request.reject(createAbortError('Chunk load was cancelled.'));\n      } else {\n        request.reject(deserializeSplatLoadError(event.data.error));\n      }\n    };\n    // A worker-level failure (a CSP that blocks blob: workers is the common\n    // one in real deployments) must still honour the documented contract:\n    // every rejection is a SplatLoadError or an AbortError, never a bare Error.\n    // There is no per-request URL here - the worker itself died - so `url` is\n    // empty and the failure is not retryable: retrying constructs the same\n    // worker under the same policy.\n    this.worker.onerror = (event?: ErrorEvent | Event) => {\n      if (this.workerFailure) return;\n      const detail =\n        event &&\n        typeof event === 'object' &&\n        'message' in event &&\n        typeof event.message === 'string'\n          ? event.message\n          : '';\n      const failure = new SplatLoadError(\n        detail ? `Chunk loading worker failed. ${detail}` : 'Chunk loading worker failed.',\n        { phase: 'worker', url: '', retryable: false },\n      );\n      this.workerFailure = failure;\n      this.worker.terminate();\n      this.rejectAll(failure);\n    };\n  }\n\n  /** Posts one load to this worker and tracks its pending promise. */\n  request(\n    message: Omit<Extract<LoadWorkerRequest, { type: 'load' }>, 'id'>,\n    signal: AbortSignal | undefined,\n    onProgress?: SplatProgressCallback,\n  ): Promise<SplatData> {\n    if (this.disposed) return Promise.reject(createAbortError('ChunkLoader has been disposed.'));\n    if (signal?.aborted) return Promise.reject(createAbortError('Chunk load was cancelled.'));\n    if (this.workerFailure) return Promise.reject(this.workerFailure);\n\n    const id = this.nextRequestId++;\n    const promise = new Promise<SplatData>((resolve, reject) => {\n      this.pending.set(id, { resolve, reject, ...(onProgress ? { onProgress } : {}) });\n    });\n    if (signal) {\n      // Settle immediately on abort rather than waiting for the worker's\n      // acknowledgement: the worker may be deep in a decode (or may already\n      // have posted a success that is still in the message queue), and a\n      // caller that cancelled must neither receive that stale result nor see\n      // further progress callbacks. The late reply finds no pending entry and\n      // is dropped in `onmessage`.\n      const onAbort = () => {\n        const pending = this.pending.get(id);\n        if (!pending) return;\n        this.pending.delete(id);\n        const cancel: LoadWorkerRequest = { type: 'cancel', id };\n        if (!this.disposed) this.worker.postMessage(cancel);\n        pending.reject(createAbortError('Chunk load was cancelled.'));\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n      const pending = this.pending.get(id);\n      if (pending) pending.removeAbortListener = () => signal.removeEventListener('abort', onAbort);\n    }\n\n    const request: LoadWorkerRequest = { ...message, id };\n    this.worker.postMessage(request);\n    return promise;\n  }\n\n  /** Terminates this worker and rejects its in-flight requests. */\n  dispose(): void {\n    if (this.disposed) return;\n    this.disposed = true;\n    this.worker.terminate();\n    this.rejectAll(createAbortError('ChunkLoader has been disposed.'));\n  }\n\n  private rejectAll(error: Error): void {\n    for (const request of this.pending.values()) {\n      request.removeAbortListener?.();\n      request.reject(error);\n    }\n    this.pending.clear();\n  }\n}\n\n/**\n * Client for the persistent scene/chunk loading workers. Multiple requests\n * may be in flight; each can be cancelled through an `AbortSignal`, which\n * aborts the worker-side fetches (useful when the camera has moved on\n * before a chunk arrived).\n *\n * There are two workers behind this one class. The streaming worker is\n * constructed eagerly and handles everything the LOD paths need; the one-shot\n * worker ({@link ONE_SHOT_FORMATS}) is constructed the first time a `.spz`,\n * `.splat` or `.ksplat` is requested. Both decode off the main thread - the\n * split exists only to keep the one-shot parsers out of the published entry.\n *\n * @example\n * const loader = new ChunkLoader();\n * const chunk = await loader.load('/scene/0_0/', { kind: 'directory' });\n */\nexport class ChunkLoader {\n  private readonly streaming = new WorkerClient(new LoadWorker());\n  /** The in-flight construction; `null` until a one-shot format is requested. */\n  private oneShot: Promise<WorkerClient> | null = null;\n  /** The constructed one-shot client, so `dispose` does not have to await. */\n  private oneShotClient: WorkerClient | null = null;\n  private disposed = false;\n\n  /**\n   * Fetches and decodes one scene file or chunk directory.\n   *\n   * @param url - Scene URL, absolute or relative to the page.\n   * @param options.kind - 'file' (default) selects a parser by extension;\n   * 'directory' decodes an unbundled SOG chunk directory.\n   * @param options.format - Explicit parser; `lcc-bin` additionally needs\n   * `options.lcc` to say which byte range of the file to fetch.\n   * @param options.signal - Abort signal for cancellation; the returned\n   * promise then rejects with a `DOMException` named `AbortError`.\n   * @param options.lcc - Byte-range plumbing for `lcc-bin`. This path exists\n   * for {@link StreamedSplatMesh} and is **not** part of the stable surface;\n   * the type is nameable as `LccChunkParams` on `@voluma/vlam/formats/lcc`.\n   * @param options.rad - Byte-range plumbing for `rad-chunk`, on the same\n   * footing; the type is `RadChunkRangeRequest` on `@voluma/vlam/formats/rad`.\n   * @throws Rejects only with {@link SplatLoadError} (resolve, fetch, decode or\n   * worker failures - `error.phase` says which; a worker that cannot start at\n   * all, e.g. under a CSP that blocks `blob:` workers, reports\n   * `phase: 'worker'`) or an `Error` named `AbortError` (cancellation or\n   * {@link dispose}).\n   */\n  // `async` so a URL or format that will not resolve rejects the returned\n  // promise rather than throwing synchronously into the caller.\n  async load(\n    url: string,\n    options: SplatInputOptions & {\n      kind?: 'file' | 'directory';\n      format?: SplatFormat | 'lcc-bin' | 'rad-chunk';\n      lcc?: LccChunkParams;\n      rad?: RadChunkRangeRequest;\n      sog?: { packShBands: 1 | 2 | 3 };\n      files?: Readonly<Record<string, string>>;\n    } = {},\n  ): Promise<SplatData> {\n    const kind = options.kind ?? 'file';\n    // The worker runs from an inlined blob/data URL, where relative and\n    // root-relative URLs cannot be resolved - make the URL absolute here.\n    const absoluteUrl = resolveSplatUrl(url, options.baseUrl).href;\n    const format = resolveFileFormat(absoluteUrl, kind, options.format ?? 'auto');\n    const data = await this.request(\n      {\n        from: 'url',\n        url: absoluteUrl,\n        kind,\n        ...(options.request ? { request: options.request } : {}),\n      },\n      format,\n      options.signal,\n      options.lcc,\n      options.rad,\n      options.files,\n      options.sog,\n      options.onProgress,\n    );\n    return withSourceFormat(data, format);\n  }\n\n  /**\n   * Decodes a local file (from a file input or a drop) in the worker - the\n   * bytes are read worker-side, so a multi-million-splat decode still never\n   * blocks the main thread.\n   *\n   * Only self-contained files are supported: `.ply`, `.spz`, `.splat`,\n   * `.ksplat` and bundled `.sog`. An unbundled SOG directory needs sibling\n   * fetches and so requires {@link load} with `kind: 'directory'`.\n   *\n   * @param file - The file; its name selects the parser unless `format` is given.\n   * @throws Rejects only with {@link SplatLoadError} (unknown extension, read\n   * or decode failures) or an `Error` named `AbortError` (cancellation or\n   * {@link dispose}).\n   */\n  // `async` so an unknown extension rejects the returned promise rather than\n  // throwing synchronously into the caller.\n  async loadFile(file: File, options: SplatDataFileLoadOptions = {}): Promise<SplatData> {\n    const requested = options.format ?? 'auto';\n    const format: Exclude<SplatFormat, 'auto'> =\n      requested === 'auto'\n        ? splatFormatForExtension(splatNameExtension(file.name), file.name)\n        : requested;\n    const data = await this.request(\n      { from: 'file', file },\n      format,\n      options.signal,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      options.onProgress,\n    );\n    return withSourceFormat(data, format);\n  }\n\n  /** Routes one load to the worker that owns its format. */\n  private request(\n    source: LoadWorkerSource,\n    format: ChunkFileFormat,\n    signal: AbortSignal | undefined,\n    lcc?: LccChunkParams,\n    rad?: RadChunkRangeRequest,\n    files?: Readonly<Record<string, string>>,\n    sog?: { packShBands: 1 | 2 | 3 },\n    onProgress?: SplatProgressCallback,\n  ): Promise<SplatData> {\n    if (this.disposed) return Promise.reject(createAbortError('ChunkLoader has been disposed.'));\n    if (signal?.aborted) return Promise.reject(createAbortError('Chunk load was cancelled.'));\n\n    const message: Omit<Extract<LoadWorkerRequest, { type: 'load' }>, 'id'> = {\n      type: 'load',\n      source,\n      format,\n      ...(lcc ? { lcc } : {}),\n      ...(rad ? { rad } : {}),\n      ...(sog ? { sog } : {}),\n      ...(files ? { files } : {}),\n      ...(onProgress ? { progress: true } : {}),\n    };\n\n    const client = this.clientFor(format);\n    // Deliberately not `async`: for a streaming format the client is already\n    // there, and the request must reach the worker in the same task the caller\n    // made it - a chunk scheduler that posts and then aborts within one frame\n    // depends on that ordering. Only the one-shot path, which cannot avoid\n    // awaiting its chunk, defers.\n    if (!(client instanceof Promise)) return client.request(message, signal, onProgress);\n    return client.then((resolved) => {\n      // Re-checked because disposal or abort may have happened while the\n      // one-shot chunk was in flight, before any listener was registered.\n      if (this.disposed) throw createAbortError('ChunkLoader has been disposed.');\n      return resolved.request(message, signal, onProgress);\n    });\n  }\n\n  /**\n   * The worker for `format`, constructing the one-shot worker on first need.\n   *\n   * The in-flight promise is cached, not just the resolved client, so two\n   * concurrent `.spz` loads share one worker instead of racing to build two.\n   */\n  private clientFor(format: ChunkFileFormat): WorkerClient | Promise<WorkerClient> {\n    if (!ONE_SHOT_FORMATS.has(format)) return this.streaming;\n    if (this.oneShotClient) return this.oneShotClient;\n    this.oneShot ??= import('./one-shot-worker?worker&inline').then(\n      ({ default: OneShotWorker }) => {\n        const client = new WorkerClient(new OneShotWorker());\n        this.oneShotClient = client;\n        // `dispose()` may have run while the chunk was in flight; it could not\n        // terminate a worker that did not exist yet, so honour it here.\n        if (this.disposed) client.dispose();\n        return client;\n      },\n    );\n    return this.oneShot;\n  }\n\n  /** Terminates both workers and rejects all in-flight requests. */\n  dispose(): void {\n    if (this.disposed) return;\n    this.disposed = true;\n    this.streaming.dispose();\n    // A one-shot worker still being imported is terminated in `clientFor`,\n    // which sees `disposed` when it finally constructs it.\n    this.oneShotClient?.dispose();\n  }\n}\n\n/** Self-contained scene formats {@link SplatData.format} can hold. */\nconst SOURCE_FORMATS: readonly SplatDataFormat[] = ['ply', 'spz', 'splat', 'ksplat', 'sog', 'rad'];\n\n/**\n * Stamps the resolved format onto decoded scene data so {@link SplatMesh} can\n * pick its `orientation: 'y-up'` correction. Chunk-only formats (`lcc-bin`,\n * `rad-chunk`) carry no self-contained frame, so they are left unstamped.\n */\nfunction withSourceFormat(data: SplatData, format: ChunkFileFormat): SplatData {\n  return (SOURCE_FORMATS as readonly string[]).includes(format)\n    ? { ...data, format: format as SplatDataFormat }\n    : data;\n}\n\nfunction resolveFileFormat(\n  url: string,\n  kind: 'file' | 'directory',\n  format: SplatFormat | 'lcc-bin' | 'rad-chunk',\n): ChunkFileFormat {\n  // An LCC or RAD chunk is a byte range of a shared file, so its extension says\n  // nothing about the parser - the caller's choice is authoritative.\n  if (format === 'lcc-bin' || format === 'rad-chunk') return format;\n  if (kind === 'directory') return 'sog';\n  if (format !== 'auto') return format;\n  return splatFormatForExtension(splatUrlExtension(new URL(url)), url);\n}\n"],"names":["ONE_SHOT_FORMATS","WorkerClient","worker","__publicField","event","request","_a","_b","createAbortError","deserializeSplatLoadError","detail","failure","SplatLoadError","message","signal","onProgress","id","promise","resolve","reject","onAbort","pending","cancel","error","ChunkLoader","LoadWorker","url","options","kind","absoluteUrl","resolveSplatUrl","format","resolveFileFormat","data","withSourceFormat","file","requested","splatFormatForExtension","splatNameExtension","source","lcc","rad","files","sog","client","resolved","OneShotWorker","SOURCE_FORMATS","splatUrlExtension"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/dist/chunk-loader.d.ts

@@ -1,7 +1,7 @@
 import type { SplatData } from './splat-data';
 import type { RadChunkRangeRequest } from './load-worker-protocol';
 import type { LccChunkParams } from './formats/lcc/parse-lcc';
-import { type SplatFileLoadOptions, type SplatFormat, type SplatInputOptions } from './loading';
+import { type SplatDataFileLoadOptions, type SplatFormat, type SplatInputOptions } from './loading';
 /**
  * Client for the persistent scene/chunk loading workers. Multiple requests
  * may be in flight; each can be cancelled through an `AbortSignal`, which
@@ -70,7 +70,7 @@ export declare class ChunkLoader {
      * or decode failures) or an `Error` named `AbortError` (cancellation or
      * {@link dispose}).
      */
-    loadFile(file: File, options?: SplatFileLoadOptions): Promise<SplatData>;
+    loadFile(file: File, options?: SplatDataFileLoadOptions): Promise<SplatData>;
     /** Routes one load to the worker that owns its format. */
     private request;
     /**

package/dist/compute-sorter.d.ts

@@ -2,7 +2,7 @@ import * as THREE from 'three/webgpu';
 import type { SplatSorter } from './sorter';
 import type { uniformArray } from 'three/tsl';
 /**
- * Optional per-source world transform for a unified {@link SplatScene} pool.
+ * Optional per-source world transform for a unified {@link MergedSplatMesh} pool.
  * When present, each splat's center is transformed to world space by its
  * source's matrix (selected by a per-splat id read from `sourceIdTexture`)
  * before its depth is computed, so clouds with different world transforms sort

package/dist/effects.d.ts

@@ -7,8 +7,9 @@
  *    in-shader from a bounded uniform array (a fixed unroll over `maxShapes`
  *    slots, gated by the live count) - add/move/remove shapes is data-only
  *    (no pipeline recompile), on WebGPU and the WebGL2 fallback alike (M7.4).
- *    The kinds mirror the CPU selection volumes (`createSelectionVolume`), so
- *    a host can highlight exactly what a selection would take.
+ *    The kinds mirror the CPU selection volumes (`createSelectionVolume` on
+ *    `@voluma/vlam/selection`), so a host can highlight exactly what a
+ *    selection would take.
  *  - {@link lightingPreset} / {@link revealPreset}: small reference presets,
  *    starting points rather than a framework (M7.5).
  *  - {@link createRelightingProxy}: builds a gray lit mesh group from collision
@@ -24,12 +25,12 @@
  *  - {@link worldWarpPreset}: camera-centered sphere wrap (planet / bowl).
  *  - {@link depthOfFieldPreset}: stylized modifier-based depth-of-field (M13).
  *    For physically-modeled camera DoF prefer the core
- *    {@link SplatMesh.setDepthOfField} / `UnifiedSplatRenderer.setDepthOfField`
+ *    {@link SplatMesh.setDepthOfField} / `UnifiedSplatMesh.setDepthOfField`
  *    path - this preset is the soft/approximate alternative built purely on
  *    the modifier hook.
  *
  * Every preset here reads positions from `ctx.localCenter` - mesh-local space,
- * which inside a `SplatScene` is the splat's **placed** position. So a shape or
+ * which inside a `MergedSplatMesh` is the splat's **placed** position. So a shape or
  * a reveal spans every source as one scene instead of travelling with a moved
  * one; see `docs/guide/effects-and-modifiers.md` for what that looks like, and
  * `ctx.sourceCenter` for the opposite behaviour.
@@ -119,7 +120,7 @@ export interface SdfEffect {
  * time (and the uniform array; very large values can exceed WebGL2's uniform
  * limits), so keep it to what a scene needs.
  *
- * Shape positions are mesh-local. In a `SplatScene` that means scene
+ * Shape positions are mesh-local. In a `MergedSplatMesh` that means scene
  * coordinates - a shape overlapping two sources covers both as one continuous
  * shape - so place them with `computeSplatBounds()`, which reports the sources
  * at their current placement.
@@ -132,7 +133,7 @@ export interface LightingPreset {
     readonly modifier: SplatModifier;
     /**
      * Mesh-local light direction; mutate `.value` to animate (no recompile).
-     * Inside a `SplatScene` that frame is the scene's, so one direction lights
+     * Inside a `MergedSplatMesh` that frame is the scene's, so one direction lights
      * every source consistently however they are posed.
      */
     readonly direction: {
@@ -144,7 +145,7 @@ export interface LightingPreset {
  * (`ctx.normal`, the least-variance covariance axis). A starting point for
  * relit product shots - not a lighting rig. Works on both backends.
  *
- * In a `SplatScene` the normal comes from the *placed* covariance, so a source
+ * In a `MergedSplatMesh` the normal comes from the *placed* covariance, so a source
  * that rotates relights as it turns.
  */
 export declare function lightingPreset(options?: {
@@ -183,7 +184,7 @@ export interface DepthOfFieldPreset {
  * than adding a truly isotropic screen-space disc. The physically exact aperture
  * model adds `coc²·I` to the *projected 2D* covariance with the same √(det)
  * opacity conservation the antialias filter uses - that path is
- * `SplatMesh.setDepthOfField` / `UnifiedSplatRenderer.setDepthOfField`
+ * `SplatMesh.setDepthOfField` / `UnifiedSplatMesh.setDepthOfField`
  * (see `docs/guide/effects-and-modifiers.md`, M13).
  *
  * Opacity conservation is exact only with `antialias` on: without it, the
@@ -211,7 +212,7 @@ export interface RevealPreset {
  * the M7 escape hatch - so this preset is **WebGPU-only** (see the fallback
  * notes); force WebGL2 and it will not compile.
  *
- * The field is anchored to the mesh, so in a `SplatScene` a moved source
+ * The field is anchored to the mesh, so in a `MergedSplatMesh` a moved source
  * reveals in step with whatever it now sits beside (and the pattern slides
  * across it as it travels) rather than carrying its own schedule around.
  */
@@ -284,8 +285,14 @@ export interface RelightingProxy {
 /** One independent shadow-casting light for {@link createRelightingShadowFactorMaterial}. */
 export type RelightingLightContribution = {
     light: THREE.Light;
-    /** Relative umbra weight. Default `1`. Values `<= 0` are skipped. */
+    /** Relative umbra weight. Default `1`. Values `<= 0` are skipped unless `fill` is set. */
     intensity?: number;
+    /**
+     * Additive Lambert fill on top of the umbra factor (RGB may exceed 1).
+     * Gated by `shadow()`, facing, and for spot/point lights the Frostbite
+     * `distance` window (and the spot cone). `0` / omitted = umbra only.
+     */
+    fill?: number;
 };
 /** Options for {@link createRelightingShadowFactorMaterial}. */
 export type RelightingShadowFactorOptions = {
@@ -333,16 +340,19 @@ export declare const MAX_RELIGHTING_SHADOW_LIGHTS = 32;
  * union of umbras so each caster keeps its silhouette. Spot / point lights
  * with `distance &gt; 0` fade their umbra to lit via a Frostbite cutoff window
  * (steepened by `decay`) so the shadow map far plane is not a hard cliff.
- * Cascades (`midLight` / `outerLight` / `farLight`) still attach to the
- * **first** directional only. At most {@link MAX_RELIGHTING_SHADOW_LIGHTS}
- * independent lights are used; extras are ignored. Graph size follows the
- * live contribution count (not a padded loop of that width).
+ * Contribution `fill` adds occluded Lambert (range + cone for punctual lights)
+ * on top of that identity so accent lights can light splats without wrapping
+ * through collision. Cascades (`midLight` / `outerLight` / `farLight`) still
+ * attach to the **first** directional only. At most
+ * {@link MAX_RELIGHTING_SHADOW_LIGHTS} independent lights are used; extras
+ * are ignored. Graph size follows the live contribution count (not a padded
+ * loop of that width).
  *
  * By default, only **upward** proxy faces receive (`receiveUpMin`). Vertical
  * and noisy foliage triangles still **cast**, but they do not self-shadow —
  * that PCF acne reads as per-frame sparkle in trees. Pass `receiveUpMin: 0`
- * to receive on every face. The Lambert term uses the same slope gate, so
- * steep foliage does not pick up a noisy tint.
+ * to receive on every face. Contribution `fill` does **not** use that slope
+ * gate (stems would otherwise stay unlit in the factor map).
  *
  * Clear the lighting RT to **RGB 1, A 0** (not black). Softness / bilinear
  * samples at coverage edges otherwise pull in black and draw a dark outline