@voluma/vlam 0.3.2 → 0.4.0

package/dist/splat-mesh-types-BZIko-_9.js.map

@@ -1 +1 @@
-{"version":3,"file":"splat-mesh-types-BZIko-_9.js","sources":["../src/lib/core/splat-mesh-types.ts"],"sourcesContent":["/** Public configuration and result types for SplatMesh. */\nimport type * as THREE from 'three/webgpu';\nimport type { SplatData } from './splat-data';\nimport type { SplatOrientation } from './orientation';\nimport type { SplatModifier } from './splat-modifier';\nimport {\n  detectSplatDeviceProfile,\n  isFillConstrainedSplatDevice,\n  type SplatDeviceProfile,\n} from './splat-budget';\nimport type { SplatPool } from './splat-mesh-pool';\nimport type { SplatShInputs, Vec3Uniform } from './splat-mesh-material';\n\n/** Construction-time projected-footprint policy selected by a streamed format. */\nexport type ProjectedFilterProfile = 'default' | 'lcc';\n\n/** Canonical `.rad` foveation modes. */\nexport type SplatFoveationMode = 'band' | 'frontier' | 'page-table';\n\n/** Resolve a caller-supplied foveation mode, defaulting when unset. */\nexport function resolveSplatFoveationMode(\n  mode: SplatFoveationMode | undefined,\n  fallback: SplatFoveationMode = 'band',\n): SplatFoveationMode {\n  return mode ?? fallback;\n}\n\n/** True when the mode is the `.rad` page-table pager. */\nexport function isPageTableFoveation(mode: string | undefined): boolean {\n  return mode === 'page-table';\n}\n\n/**\n * Opaque handle for a range of splats appended to a {@link SplatMesh},\n * used to remove the range again.\n */\nexport interface SplatRange {\n  /** Number of splats in this range. */\n  readonly count: number;\n}\n\n/**\n * Storage format of a per-splat channel (see {@link SplatMesh.defineChannel}).\n *\n *  - `'byte'`: one `Uint8` per splat (`r8unorm`). Compact - a good fit for\n *    masks and labels. `ctx.channel(name)` reads it back **normalized** to\n *    `[0, 1]`, so a painted `255` reads as `1.0`.\n *  - `'float'`: one `Float32` per splat (`r32float`), read back verbatim.\n */\nexport type SplatChannelType = 'byte' | 'float';\n\n/** Options for {@link SplatMesh.defineChannel}. */\nexport interface SplatChannelOptions {\n  /** Storage format; default `'float'`. */\n  type?: SplatChannelType;\n  /**\n   * Value every splat starts at before any {@link SplatMesh.writeChannel}.\n   * Default `0`. For `'byte'` channels this is a raw `0..255` value.\n   */\n  fill?: number;\n}\n\n/** The highest SH order this renderer evaluates (3rd → 15 coefficients). */\nexport const MAX_SH_BANDS = 3;\n\n/**\n * The contribution-culling profile a mesh will use, given an optional\n * explicit override. Exported so callers that must decide something *before*\n * constructing the mesh - such as whether a streamed scene should fetch its\n * SH at all - agree with what the mesh itself will pick.\n */\nexport function resolveSplatPerformanceProfile(\n  explicit?: SplatPerformanceProfile,\n  profile: SplatDeviceProfile | undefined = detectSplatDeviceProfile(),\n): SplatPerformanceProfile {\n  return explicit ?? (isFillConstrainedSplatDevice(profile) ? 'smooth' : 'quality');\n}\n\n/** Construction options for {@link SplatMesh}. */\nexport interface SplatMeshOptions {\n  /**\n   * Storage for per-splat higher-order SH in a dynamic-capacity pool, in\n   * bands (1, 2 or 3 → 3, 8 or 15 coefficients per channel); 0 (default)\n   * allocates nothing.\n   *\n   * Only formats that store SH per splat can fill this - LCC `Quality`, `.rad`, etc.\n   * It costs 16 bytes per splat per band-group of four\n   * coefficients (64 B/splat at 3 bands), so it is opt-in. On a static mesh\n   * this is ignored: packed SH is taken from `source.shPacked` when present,\n   * otherwise palette `source.sh` (SOG).\n   */\n  shBands?: 0 | 1 | 2 | 3;\n  /**\n   * Minimum interval between WebGPU sorts while the camera moves. When\n   * omitted, the interval adapts to the active splat count. Use `0` to sort\n   * every changed frame. WebGL worker sorting is unaffected.\n   */\n  sortIntervalMs?: number;\n  /**\n   * WebGPU sorter used for A/B validation. Defaults to the proven counting\n   * sorter. `'radix'` keeps the fast 24-bit key path; `'exact'` lazy-loads a\n   * stable 32-bit Float32-depth radix path that avoids scene-range\n   * quantization. The first frames may skip sorting until the module resolves.\n   *\n   * @experimental Radix strategies may change in a minor release.\n   */\n  sortStrategy?: SplatSortStrategy;\n  /**\n   * Render-quality policy. `smooth` rejects negligible projected contributions.\n   *\n   * The default is device-aware: `smooth` on mobile (where rejecting splats too\n   * small or too faint to see is worth far more than it costs), `quality`\n   * everywhere else. Passing a value opts out of the detection.\n   */\n  performanceProfile?: SplatPerformanceProfile;\n  /**\n   * How far out, in standard deviations, each Gaussian is drawn before it is\n   * cut off. Every splat is an alpha-blended quad sized to this radius, so it\n   * sets how much each one costs to blend - the dominant cost in a busy view.\n   * Lowering it shrinks every quad and clips the faint outer tail of each\n   * Gaussian; the falloff within the remaining radius is unchanged.\n   *\n   * Defaults to `3`, the reference 3DGS rasterizer's radius. Below ~2 the\n   * truncation shows as visible splat edges; much above ~5 the extra fill is not\n   * worth it. Mobile coverage gaps are handled by `minSplatSizePx` instead of\n   * growing every splat.\n   */\n  maxStdDev?: number;\n  /**\n   * Floor, in viewport pixels, on each rendered splat's projected quad radius.\n   *\n   * A screen-space *minimum* size, the counterpart to `maxScreenRadiusPx`'s\n   * maximum. When a splat projects smaller than this - because it is distant, or\n   * because the whole scene is zoomed out - its quad is grown to this radius and\n   * the Gaussian is stretched to fill it (the falloff normalizes to the quad, so\n   * no hard edge appears). Splats already larger are untouched, so it costs no\n   * extra fill on the near-camera splats that dominate overdraw.\n   *\n   * This is the fix for the \"dark gaps when zoomed out\" failure mode: a capture\n   * whose finest splats are spaced farther apart than their footprint leaves the\n   * background showing between them, and the effect is worst at low resolution -\n   * i.e. on a phone. Raising `maxStdDev` also closes the gaps but inflates\n   * *every* splat's fragment count by its square, paying the coverage cost on the\n   * large splats too; this floor spends it only where a gap can actually open.\n   *\n   * Defaults to `1.5` px on mobile and `0` (disabled) elsewhere, including\n   * fill-constrained desktops. Values around 1–3 px close typical gaps; too\n   * large a floor blurs distinct small features into discs, so tune it up from\n   * small on the target device. An explicit `0` always disables the floor.\n   */\n  minSplatSizePx?: number;\n  /**\n   * Apply the Mip-Splatting 2D antialiasing filter - the screen-space low-pass\n   * dilation plus the opacity compensation that conserves each Gaussian's\n   * integral, so small/distant splats stop over-brightening. Match the\n   * exporter: enable it for scenes trained/exported with antialiasing (the SOG\n   * `antialias` meta flag sets this automatically). Defaults to `false` (the\n   * classic 3DGS dilation without compensation).\n   */\n  antialias?: boolean;\n  /**\n   * Internal format-selected reconstruction profile. Classic LCC uses the\n   * XGRIDS-compatible 0.1 px² compensated low-pass; callers should leave this\n   * unset and select a format through {@link StreamedSplatMesh.load} instead.\n   *\n   * @internal\n   */\n  projectedFilterProfile?: ProjectedFilterProfile;\n  /**\n   * Emit splat colors in sRGB (display) space instead of decoding them to the\n   * renderer's linear working space. Pair with a renderer that skips output\n   * conversion (`outputColorSpace = LinearSRGBColorSpace`, `NoToneMapping`,\n   * inline sRGB encode for other materials via `renderer.contextNode`): splats\n   * then alpha-composite on gamma-encoded values - the math 3DGS training\n   * optimizes against, and what WebGL splat viewers render. Defaults to\n   * `false` (linear working-space compositing).\n   */\n  srgbOutput?: boolean;\n  /**\n   * Cull any splat whose projected on-screen radius exceeds this many pixels,\n   * rendering a hole instead. A physically large splat close to the camera -\n   * a coarse merged LOD node (a Spark `.rad` \"blob\"), or a giant background\n   * Gaussian - projects huge while a fine surface splat stays small, so this\n   * removes the near-camera blobs without touching detailed geometry. `0` or\n   * unset disables it (the default). Baked into the material graph.\n   */\n  maxSplatScreenRadius?: number;\n  /**\n   * Foveation band lower bound (px): cull any splat whose projected on-screen\n   * radius is *below* this. Paired with {@link maxSplatScreenRadius}, only\n   * splats sized `(min, max]` on screen draw. Because a `.rad` LOD tree's node\n   * sizes shrink geometrically, exactly one level per view ray lands in the\n   * band - near rays on fine leaves, far rays on coarse nodes - giving a\n   * camera-distance foveated cut. `0` or unset disables it (the default).\n   * Baked into the material graph. See `docs/formats/rad-notes.md` M14.6.\n   */\n  minSplatScreenRadius?: number;\n  /**\n   * How a `.rad` foveated mesh picks its per-splat LOD cut:\n   * - `'band'` (default): the screen-radius band above\n   *   ({@link minSplatScreenRadius}, {@link maxSplatScreenRadius}].\n   * - `'frontier'`: Spark's exact tree cut - draw splat `i` iff its parent is\n   *   too big and it is small enough (`parentPixelScale > limit ≥ ownPixelScale`),\n   *   using per-splat `own_size`/`parent_size`. Full coverage by construction, no\n   *   band leapfrogging. Baked into the material graph. See `docs/formats/rad-notes.md`.\n   * - `'page-table'`: the {@link StreamedSplatMesh} default for `.rad` - a worker\n   *   owns the tree traversal and pages only the *selected* frontier into the\n   *   pool (Spark's selected-index model), so the whole splat budget buys\n   *   on-screen detail. Requires the streamed `.rad` machinery; on a plain\n   *   `SplatMesh` it has no worker to drive it.\n   *\n   * @experimental `.rad` foveation option; may change in a minor release.\n   */\n  foveationMode?: SplatFoveationMode;\n  /**\n   * Target on-screen size (px) for the frontier / page-table cut: it keeps one\n   * LOD level per view ray whose projected node size is about this. Larger =\n   * coarser/fewer splats, smaller = finer/denser. Default\n   * {@link DEFAULT_FOVEATION_TARGET_PX} (1, matching Spark's `lodRenderScale`),\n   * so the draw budget rather than the cut size is what bounds detail. Raise it\n   * to trade sharpness for fill rate on weak GPUs.\n   * Acts as the *finest* bound: the adaptive limit coarsens above it to hold the\n   * draw budget but never dips below it.\n   *\n   * @experimental `.rad` foveation option; may change in a minor release.\n   */\n  foveationTargetPx?: number;\n  /**\n   * Target upper bound on the number of splats the frontier cut *draws*\n   * (Spark's `maxSplats`). Each reschedule the cut's `pixelScaleLimit`\n   * self-adjusts - coarsening when the estimated drawn count exceeds this - so\n   * frame cost stays bounded as detail streams in. Default\n   * {@link DEFAULT_FOVEATION_DRAW_BUDGET}. Only used in `'frontier'` mode.\n   *\n   * @experimental `.rad` foveation option; may change in a minor release.\n   */\n  foveationDrawBudget?: number;\n  /**\n   * Cap on a rendered splat's major/minor axis ratio (`0`/unset = off). A very\n   * anisotropic Gaussian (a flat 3DGS disk edge-on, or an expansion-enlarged\n   * coarse LOD node) otherwise projects to a long needle; this bounds its drawn\n   * length to `maxSplatAspect`× its width. Baked into the material graph.\n   *\n   * @experimental `.rad` foveation option; may change in a minor release.\n   */\n  maxSplatAspect?: number;\n  /**\n   * Spark's LOD alpha encoding (`.rad`): the stored opacity is `alpha/2` so the\n   * shader recovers `alpha ∈ [0,2]` from the original texture channel, and\n   * `alpha > 1` marks a merged node rendered with a grown σ-cutoff +\n   * super-Gaussian falloff. Visual fades and alpha modifiers scale the completed\n   * fragment after that classification; they must not change node type or shape.\n   * Set for foveated `.rad`.\n   *\n   * @experimental `.rad` foveation option; may change in a minor release.\n   */\n  lodAlpha?: boolean;\n  /**\n   * How the scene is oriented into the three.js Y-up world. `'y-up'` (default)\n   * normalizes every known format to Y-up - 3DGS Y-down formats\n   * (PLY/`.splat`/`.ksplat`/SOG) are flipped 180° about X; SPZ/`.rad` are\n   * already Y-up; LCC keeps its own Z-up→Y-up matrix. `'source'` applies no\n   * cosmetic flip and renders in the data frame (raw Spark / mkkellogg parity);\n   * LCC still self-orients (that is format semantics, not part of the switch).\n   *\n   * For a fully loaded mesh the flip is chosen from {@link SplatData.format}\n   * (stamped by the loaders); a dynamic-capacity mesh carries no format, so the\n   * caller applies {@link yUpTransformForFormat} itself. See {@link SplatOrientation}.\n   */\n  orientation?: SplatOrientation;\n  /**\n   * GPU storage type for the pool's continuous float textures (`centers` and\n   * `covarianceA`). `'float16'` uploads them as `rgba16float` (~16 B/splat\n   * saved vs the default). CPU backing stays float32 (sorter, query, writes).\n   *\n   * `covarianceB` is always float32: it packs integer IDs (SOG palette labels,\n   * RAD frontier parents) that half floats cannot represent exactly above\n   * 2048. Colors and packed SH are unchanged. Construction-time only.\n   */\n  poolFloatTextures?: 'float32' | 'float16';\n  /**\n   * An existing pool to draw from instead of allocating one.\n   *\n   * Several meshes sharing a pool share its memory envelope: rows go to\n   * whichever mesh needs them, so a mesh the camera is near can hold far more\n   * than an even split would give it, and one that is far away holds almost\n   * nothing - without every mesh having reserved a private ceiling up front.\n   * This is the multi-mesh analogue of a single streamed mesh's LOD budget.\n   *\n   * The pool is *not* owned by the mesh: {@link SplatMesh.dispose} releases the\n   * mesh's rows and leaves the textures alone, so the pool's creator disposes\n   * it once every tenant is gone. `capacity` on the source is then only used\n   * for the mesh's own draw list, not to size storage.\n   *\n   * Sharing costs a whole-pool stall when the pool fragments - see\n   * {@link SplatMesh.compact}.\n   */\n  pool?: SplatPool;\n  /**\n   * The device's `maxTextureDimension2D`, forwarded to a pool this mesh\n   * allocates for itself so an over-tall pool fails at construction with a\n   * readable error instead of at first draw. Pass `deviceMaxTextureSize(renderer)`.\n   *\n   * Ignored when {@link SplatMeshOptions.pool} supplies the pool - that pool\n   * was already checked when its creator built it.\n   */\n  maxTextureSize?: number;\n}\n\n/** Available WebGPU depth-sort implementations. */\nexport type SplatSortStrategy = 'counting' | 'radix' | 'exact';\n\n/** Controls optional work during a per-frame source update. */\nexport interface SplatUpdateOptions {\n  /** Leave sorting to {@link UnifiedSplatMesh}; uploads and LOD state still update. */\n  sort?: boolean;\n}\n\n/**\n * Read-only GPU-facing view of a mesh's current active pool. It is consumed by\n * the M15.4 unified gather path; streamed meshes expose their current LOD cut\n * through the same view because they inherit {@link SplatMesh}.\n *\n * @experimental May change in a minor release.\n */\nexport interface UnifiedSourceView {\n  /** Total addressable pool slots. */\n  readonly capacity: number;\n  /** Pool indices of active splats, packed from zero. */\n  readonly sourceIndex: THREE.StorageBufferAttribute;\n  /** Active entries at the front of {@link sourceIndex}. */\n  readonly activeCount: number;\n  /** Local-space centers, RGBA32F and pool-indexed. */\n  readonly centersTexture: THREE.DataTexture;\n  /** Source display color and opacity, RGBA8 and pool-indexed. */\n  readonly colorsTexture: THREE.DataTexture;\n  /** Upper covariance rows, RGBA32F and pool-indexed. */\n  readonly covarianceATexture: THREE.DataTexture;\n  /** Final covariance row, RGBA32F and pool-indexed. */\n  readonly covarianceBTexture: THREE.DataTexture;\n  /** Centers texture row width. */\n  readonly dataTextureWidth: number;\n  /** Current source-local → world transform. */\n  readonly matrixWorld: THREE.Matrix4;\n  /** Conservative world-space bound for depth quantization. */\n  readonly worldBounds: THREE.Sphere;\n  /** Higher-order color data resolved by the gather pass when present. */\n  readonly sh: SplatShInputs | null;\n  /** Effect hooks and their source-local data channels. */\n  readonly modifiers: readonly SplatModifier[];\n  /**\n   * True when this source is itself a unified pool with per-source placement\n   * (`MergedSplatMesh`). The gather path cannot resolve nested placement, so\n   * `UnifiedSplatMesh` rejects these sources.\n   */\n  readonly hasSourcePlacement: boolean;\n  readonly channels: ReadonlyMap<string, { texture: THREE.DataTexture }>;\n  /** Same uniform node the source graph updates each frame. */\n  readonly localCameraPosition: Vec3Uniform;\n  /** Changes whenever a modifier graph must be rebuilt. */\n  readonly graphRevision: number;\n  /** Whether this source intentionally composites in display (sRGB) space. */\n  readonly srgbOutput: boolean;\n  /** Shared draw-path settings that must agree across unified sources. */\n  readonly maxStdDev: number;\n  /** Screen-space minimum splat radius, px (0 = off). */\n  readonly minSplatSizePx: number;\n  readonly antialias: boolean;\n  /** Construction-time projected-footprint policy shared by one unified pass. */\n  readonly projectedFilterProfile: ProjectedFilterProfile;\n  /**\n   * Whether this source stores Spark LOD alpha (`alpha ÷ 2`, `.rad`). The\n   * gather recovers the full `alpha ∈ [0,2]`; the draw material then treats\n   * `alpha > 1` as a merged node. Per source, not a compatibility field - a\n   * scene may mix `.rad` and non-`.rad` sources.\n   */\n  readonly lodAlpha: boolean;\n  /** Increments whenever pool-backed data or active residency changes. */\n  readonly contentRevision: number;\n}\n\n/** Quality-compatible rendering or smoother contribution-culling rendering. */\nexport type SplatPerformanceProfile = 'quality' | 'smooth';\n\n/**\n * Options for {@link SplatMesh.pick}.\n *\n * Picking returns the selected splat's rendered center plane (depth-tested\n * Gaussian coverage), not a persistent splat identifier or a collision mesh.\n */\nexport interface SplatPickOptions {\n  /**\n   * Minimum Gaussian opacity (after falloff × splat alpha) for a fragment to\n   * count as a hit. Default `0.1`.\n   */\n  alphaThreshold?: number;\n}\n\n/**\n * Result of a successful {@link SplatMesh.pick}.\n *\n * The point lies on the frontmost splat's billboard plane at the picked\n * pixel - suitable for click-to-focus and placement anchors, not physics.\n */\nexport interface SplatPickResult {\n  /** Hit position in world space. */\n  readonly point: THREE.Vector3;\n  /** Distance from the camera position to {@link point}. */\n  readonly distance: number;\n}\n\n/**\n * Result of {@link SplatMesh.queryNearest}: the resident splat center closest\n * to the query point, in world space.\n */\nexport interface SplatNearestResult {\n  /** The splat's center, in world space. */\n  readonly point: THREE.Vector3;\n  /** World-space distance from the query point to {@link point}. */\n  readonly distance: number;\n}\n\n/** Result of a successful synchronous {@link SplatMesh.queryRay}. */\nexport interface SplatRayResult {\n  /** Resident splat center in world space. */\n  readonly point: THREE.Vector3;\n  /** Distance along the ray from its origin to the center's closest plane. */\n  readonly distance: number;\n}\n\n/**\n * Result of {@link SplatMesh.queryHeight}: the supporting surface found beneath\n * the query point (the highest resident splat within the drop and horizontal\n * radius), in world space.\n */\nexport interface SplatHeightResult {\n  /** The supporting splat's center, in world space. */\n  readonly point: THREE.Vector3;\n  /** How far below the query point the surface sits (world units, ≥ 0). */\n  readonly drop: number;\n}\n"],"names":["resolveSplatFoveationMode","mode","fallback","isPageTableFoveation","MAX_SH_BANDS","resolveSplatPerformanceProfile","explicit","profile","detectSplatDeviceProfile","isFillConstrainedSplatDevice"],"mappings":";AAoBO,SAASA,EACdC,GACAC,IAA+B,QACX;AACpB,SAAOD,KAAQC;AACjB;AAGO,SAASC,EAAqBF,GAAmC;AACtE,SAAOA,MAAS;AAClB;AAiCO,MAAMG,IAAe;AAQrB,SAASC,EACdC,GACAC,IAA0CC,KACjB;AACzB,SAAOF,MAAaG,EAA6BF,CAAO,IAAI,WAAW;AACzE;"}
+{"version":3,"file":"splat-mesh-types-BZIko-_9.js","sources":["../src/lib/core/splat-mesh-types.ts"],"sourcesContent":["/** Public configuration and result types for SplatMesh. */\nimport type * as THREE from 'three/webgpu';\nimport type { SplatData } from './splat-data';\nimport type { SplatOrientation } from './orientation';\nimport type { SplatModifier } from './splat-modifier';\nimport {\n  detectSplatDeviceProfile,\n  isFillConstrainedSplatDevice,\n  type SplatDeviceProfile,\n} from './splat-budget';\nimport type { SplatPool } from './splat-mesh-pool';\nimport type { SplatShInputs, Vec3Uniform } from './splat-mesh-material';\n\n/** Construction-time projected-footprint policy selected by a streamed format. */\nexport type ProjectedFilterProfile = 'default' | 'lcc';\n\n/** Canonical `.rad` foveation modes. */\nexport type SplatFoveationMode = 'band' | 'frontier' | 'page-table';\n\n/** Resolve a caller-supplied foveation mode, defaulting when unset. */\nexport function resolveSplatFoveationMode(\n  mode: SplatFoveationMode | undefined,\n  fallback: SplatFoveationMode = 'band',\n): SplatFoveationMode {\n  return mode ?? fallback;\n}\n\n/** True when the mode is the `.rad` page-table pager. */\nexport function isPageTableFoveation(mode: string | undefined): boolean {\n  return mode === 'page-table';\n}\n\n/**\n * Opaque handle for a range of splats appended to a {@link SplatMesh},\n * used to remove the range again.\n */\nexport interface SplatRange {\n  /** Number of splats in this range. */\n  readonly count: number;\n}\n\n/**\n * Storage format of a per-splat channel (see {@link SplatMesh.defineChannel}).\n *\n *  - `'byte'`: one `Uint8` per splat (`r8unorm`). Compact - a good fit for\n *    masks and labels. `ctx.channel(name)` reads it back **normalized** to\n *    `[0, 1]`, so a painted `255` reads as `1.0`.\n *  - `'float'`: one `Float32` per splat (`r32float`), read back verbatim.\n */\nexport type SplatChannelType = 'byte' | 'float';\n\n/** Options for {@link SplatMesh.defineChannel}. */\nexport interface SplatChannelOptions {\n  /** Storage format; default `'float'`. */\n  type?: SplatChannelType;\n  /**\n   * Value every splat starts at before any {@link SplatMesh.writeChannel}.\n   * Default `0`. For `'byte'` channels this is a raw `0..255` value.\n   */\n  fill?: number;\n}\n\n/** The highest SH order this renderer evaluates (3rd → 15 coefficients). */\nexport const MAX_SH_BANDS = 3;\n\n/**\n * The contribution-culling profile a mesh will use, given an optional\n * explicit override. Exported so callers that must decide something *before*\n * constructing the mesh - such as whether a streamed scene should fetch its\n * SH at all - agree with what the mesh itself will pick.\n */\nexport function resolveSplatPerformanceProfile(\n  explicit?: SplatPerformanceProfile,\n  profile: SplatDeviceProfile | undefined = detectSplatDeviceProfile(),\n): SplatPerformanceProfile {\n  return explicit ?? (isFillConstrainedSplatDevice(profile) ? 'smooth' : 'quality');\n}\n\n/** Construction options for {@link SplatMesh}. */\nexport interface SplatMeshOptions {\n  /**\n   * Storage for per-splat higher-order SH in a dynamic-capacity pool, in\n   * bands (1, 2 or 3 → 3, 8 or 15 coefficients per channel); 0 (default)\n   * allocates nothing.\n   *\n   * Only formats that store SH per splat can fill this - LCC `Quality`, `.rad`, etc.\n   * It costs 16 bytes per splat per band-group of four\n   * coefficients (64 B/splat at 3 bands), so it is opt-in. On a static mesh\n   * this is ignored: packed SH is taken from `source.shPacked` when present,\n   * otherwise palette `source.sh` (SOG).\n   */\n  shBands?: 0 | 1 | 2 | 3;\n  /**\n   * Minimum interval between WebGPU sorts while the camera moves. When\n   * omitted, the interval adapts to the active splat count. Use `0` to sort\n   * every changed frame. WebGL worker sorting is unaffected; a worker selected\n   * explicitly on WebGPU still observes this submission cadence.\n   */\n  sortIntervalMs?: number;\n  /**\n   * WebGPU sorter used for A/B validation. Defaults to the proven counting\n   * sorter. `'worker'` keeps rendering on WebGPU but sorts asynchronously in\n   * the stable CPU worker also used by the WebGL fallback; this is useful for\n   * Spark-like temporal stability on captures with extreme position outliers.\n   * `'radix'` keeps the fast 24-bit GPU key path; `'exact'` lazy-loads a 32-bit\n   * Float32-depth GPU radix path. The first frames may skip GPU radix sorting\n   * until the module resolves.\n   *\n   * @experimental Radix strategies may change in a minor release.\n   */\n  sortStrategy?: SplatSortStrategy;\n  /**\n   * Geometric key used to order transparent splats back-to-front.\n   *\n   * `'depth'` (default) sorts along the camera's view axis and gives the most\n   * accurate alpha order for a fixed view. `'radial'` sorts by distance from\n   * the camera, matching Spark's stable default: camera rotation alone leaves\n   * the order unchanged, which greatly reduces whole-scene shimmer while\n   * orbiting dense captures. Pair it with `sortStrategy: 'exact'` when extreme\n   * position outliers would make quantized buckets too coarse.\n   */\n  sortMetric?: SplatSortMetric;\n  /**\n   * Render-quality policy. `smooth` rejects negligible projected contributions.\n   *\n   * The default is device-aware: `smooth` on mobile (where rejecting splats too\n   * small or too faint to see is worth far more than it costs), `quality`\n   * everywhere else. Passing a value opts out of the detection.\n   */\n  performanceProfile?: SplatPerformanceProfile;\n  /**\n   * How far out, in standard deviations, each Gaussian is drawn before it is\n   * cut off. Every splat is an alpha-blended quad sized to this radius, so it\n   * sets how much each one costs to blend - the dominant cost in a busy view.\n   * Lowering it shrinks every quad and clips the faint outer tail of each\n   * Gaussian; the falloff within the remaining radius is unchanged.\n   *\n   * Defaults to `3`, the reference 3DGS rasterizer's radius. Below ~2 the\n   * truncation shows as visible splat edges; much above ~5 the extra fill is not\n   * worth it. Mobile coverage gaps are handled by `minSplatSizePx` instead of\n   * growing every splat.\n   */\n  maxStdDev?: number;\n  /**\n   * Floor, in viewport pixels, on each rendered splat's projected quad radius.\n   *\n   * A screen-space *minimum* size, the counterpart to `maxScreenRadiusPx`'s\n   * maximum. When a splat projects smaller than this - because it is distant, or\n   * because the whole scene is zoomed out - its quad is grown to this radius and\n   * the Gaussian is stretched to fill it (the falloff normalizes to the quad, so\n   * no hard edge appears). Splats already larger are untouched, so it costs no\n   * extra fill on the near-camera splats that dominate overdraw.\n   *\n   * This is the fix for the \"dark gaps when zoomed out\" failure mode: a capture\n   * whose finest splats are spaced farther apart than their footprint leaves the\n   * background showing between them, and the effect is worst at low resolution -\n   * i.e. on a phone. Raising `maxStdDev` also closes the gaps but inflates\n   * *every* splat's fragment count by its square, paying the coverage cost on the\n   * large splats too; this floor spends it only where a gap can actually open.\n   *\n   * Defaults to `1.5` px on mobile and `0` (disabled) elsewhere, including\n   * fill-constrained desktops. Values around 1–3 px close typical gaps; too\n   * large a floor blurs distinct small features into discs, so tune it up from\n   * small on the target device. An explicit `0` always disables the floor.\n   */\n  minSplatSizePx?: number;\n  /**\n   * Apply the Mip-Splatting 2D antialiasing filter - the screen-space low-pass\n   * dilation plus the opacity compensation that conserves each Gaussian's\n   * integral, so small/distant splats stop over-brightening. Match the\n   * exporter: enable it for scenes trained/exported with antialiasing (the SOG\n   * `antialias` meta flag sets this automatically). Defaults to `false` (the\n   * classic 3DGS dilation without compensation).\n   */\n  antialias?: boolean;\n  /**\n   * Internal format-selected reconstruction profile. Classic LCC uses the\n   * XGRIDS-compatible 0.1 px² compensated low-pass; callers should leave this\n   * unset and select a format through {@link StreamedSplatMesh.load} instead.\n   *\n   * @internal\n   */\n  projectedFilterProfile?: ProjectedFilterProfile;\n  /**\n   * Emit splat colors in sRGB (display) space instead of decoding them to the\n   * renderer's linear working space. Pair with a renderer that skips output\n   * conversion (`outputColorSpace = LinearSRGBColorSpace`, `NoToneMapping`,\n   * inline sRGB encode for other materials via `renderer.contextNode`): splats\n   * then alpha-composite on gamma-encoded values - the math 3DGS training\n   * optimizes against, and what WebGL splat viewers render. Defaults to\n   * `false` (linear working-space compositing).\n   */\n  srgbOutput?: boolean;\n  /**\n   * Cull any splat whose projected on-screen radius exceeds this many pixels,\n   * rendering a hole instead. A physically large splat close to the camera -\n   * a coarse merged LOD node (a Spark `.rad` \"blob\"), or a giant background\n   * Gaussian - projects huge while a fine surface splat stays small, so this\n   * removes the near-camera blobs without touching detailed geometry. `0` or\n   * unset disables it (the default). Baked into the material graph.\n   */\n  maxSplatScreenRadius?: number;\n  /**\n   * Foveation band lower bound (px): cull any splat whose projected on-screen\n   * radius is *below* this. Paired with {@link maxSplatScreenRadius}, only\n   * splats sized `(min, max]` on screen draw. Because a `.rad` LOD tree's node\n   * sizes shrink geometrically, exactly one level per view ray lands in the\n   * band - near rays on fine leaves, far rays on coarse nodes - giving a\n   * camera-distance foveated cut. `0` or unset disables it (the default).\n   * Baked into the material graph. See `docs/formats/rad-notes.md` M14.6.\n   */\n  minSplatScreenRadius?: number;\n  /**\n   * How a `.rad` foveated mesh picks its per-splat LOD cut:\n   * - `'band'` (default): the screen-radius band above\n   *   ({@link minSplatScreenRadius}, {@link maxSplatScreenRadius}].\n   * - `'frontier'`: Spark's exact tree cut - draw splat `i` iff its parent is\n   *   too big and it is small enough (`parentPixelScale > limit ≥ ownPixelScale`),\n   *   using per-splat `own_size`/`parent_size`. Full coverage by construction, no\n   *   band leapfrogging. Baked into the material graph. See `docs/formats/rad-notes.md`.\n   * - `'page-table'`: the {@link StreamedSplatMesh} default for `.rad` - a worker\n   *   owns the tree traversal and pages only the *selected* frontier into the\n   *   pool (Spark's selected-index model), so the whole splat budget buys\n   *   on-screen detail. Requires the streamed `.rad` machinery; on a plain\n   *   `SplatMesh` it has no worker to drive it.\n   *\n   * @experimental `.rad` foveation option; may change in a minor release.\n   */\n  foveationMode?: SplatFoveationMode;\n  /**\n   * Target on-screen size (px) for the frontier / page-table cut: it keeps one\n   * LOD level per view ray whose projected node size is about this. Larger =\n   * coarser/fewer splats, smaller = finer/denser. Default\n   * {@link DEFAULT_FOVEATION_TARGET_PX} (1, matching Spark's `lodRenderScale`),\n   * so the draw budget rather than the cut size is what bounds detail. Raise it\n   * to trade sharpness for fill rate on weak GPUs.\n   * Acts as the *finest* bound: the adaptive limit coarsens above it to hold the\n   * draw budget but never dips below it.\n   *\n   * @experimental `.rad` foveation option; may change in a minor release.\n   */\n  foveationTargetPx?: number;\n  /**\n   * Target upper bound on the number of splats the frontier cut *draws*\n   * (Spark's `maxSplats`). Each reschedule the cut's `pixelScaleLimit`\n   * self-adjusts - coarsening when the estimated drawn count exceeds this - so\n   * frame cost stays bounded as detail streams in. Default\n   * {@link DEFAULT_FOVEATION_DRAW_BUDGET}. Only used in `'frontier'` mode.\n   *\n   * @experimental `.rad` foveation option; may change in a minor release.\n   */\n  foveationDrawBudget?: number;\n  /**\n   * Cap on a rendered splat's major/minor axis ratio (`0`/unset = off). A very\n   * anisotropic Gaussian (a flat 3DGS disk edge-on, or an expansion-enlarged\n   * coarse LOD node) otherwise projects to a long needle; this bounds its drawn\n   * length to `maxSplatAspect`× its width. Baked into the material graph.\n   *\n   * @experimental `.rad` foveation option; may change in a minor release.\n   */\n  maxSplatAspect?: number;\n  /**\n   * Spark's LOD alpha encoding (`.rad`): the stored opacity is `alpha/2` so the\n   * shader recovers `alpha ∈ [0,2]` from the original texture channel, and\n   * `alpha > 1` marks a merged node rendered with a grown σ-cutoff +\n   * super-Gaussian falloff. Visual fades and alpha modifiers scale the completed\n   * fragment after that classification; they must not change node type or shape.\n   * Set for foveated `.rad`.\n   *\n   * @experimental `.rad` foveation option; may change in a minor release.\n   */\n  lodAlpha?: boolean;\n  /**\n   * How the scene is oriented into the three.js Y-up world. `'y-up'` (default)\n   * normalizes every known format to Y-up - 3DGS Y-down formats\n   * (PLY/`.splat`/`.ksplat`/SOG) are flipped 180° about X; SPZ/`.rad` are\n   * already Y-up; LCC keeps its own Z-up→Y-up matrix. `'source'` applies no\n   * cosmetic flip and renders in the data frame (raw Spark / mkkellogg parity);\n   * LCC still self-orients (that is format semantics, not part of the switch).\n   *\n   * For a fully loaded mesh the flip is chosen from {@link SplatData.format}\n   * (stamped by the loaders); a dynamic-capacity mesh carries no format, so the\n   * caller applies {@link yUpTransformForFormat} itself. See {@link SplatOrientation}.\n   */\n  orientation?: SplatOrientation;\n  /**\n   * GPU storage type for the pool's continuous float textures (`centers` and\n   * `covarianceA`). `'float16'` uploads them as `rgba16float` (~16 B/splat\n   * saved vs the default). CPU backing stays float32 (sorter, query, writes).\n   *\n   * `covarianceB` is always float32: it packs integer IDs (SOG palette labels,\n   * RAD frontier parents) that half floats cannot represent exactly above\n   * 2048. Colors and packed SH are unchanged. Construction-time only.\n   */\n  poolFloatTextures?: 'float32' | 'float16';\n  /**\n   * An existing pool to draw from instead of allocating one.\n   *\n   * Several meshes sharing a pool share its memory envelope: rows go to\n   * whichever mesh needs them, so a mesh the camera is near can hold far more\n   * than an even split would give it, and one that is far away holds almost\n   * nothing - without every mesh having reserved a private ceiling up front.\n   * This is the multi-mesh analogue of a single streamed mesh's LOD budget.\n   *\n   * The pool is *not* owned by the mesh: {@link SplatMesh.dispose} releases the\n   * mesh's rows and leaves the textures alone, so the pool's creator disposes\n   * it once every tenant is gone. `capacity` on the source is then only used\n   * for the mesh's own draw list, not to size storage.\n   *\n   * Sharing costs a whole-pool stall when the pool fragments - see\n   * {@link SplatMesh.compact}.\n   */\n  pool?: SplatPool;\n  /**\n   * The device's `maxTextureDimension2D`, forwarded to a pool this mesh\n   * allocates for itself so an over-tall pool fails at construction with a\n   * readable error instead of at first draw. Pass `deviceMaxTextureSize(renderer)`.\n   *\n   * Ignored when {@link SplatMeshOptions.pool} supplies the pool - that pool\n   * was already checked when its creator built it.\n   */\n  maxTextureSize?: number;\n}\n\n/** Available WebGPU depth-sort implementations. */\nexport type SplatSortStrategy = 'counting' | 'worker' | 'radix' | 'exact';\n\n/** Camera-space key used for back-to-front splat ordering. */\nexport type SplatSortMetric = 'depth' | 'radial';\n\n/** Controls optional work during a per-frame source update. */\nexport interface SplatUpdateOptions {\n  /** Leave sorting to {@link UnifiedSplatMesh}; uploads and LOD state still update. */\n  sort?: boolean;\n}\n\n/**\n * Read-only GPU-facing view of a mesh's current active pool. It is consumed by\n * the M15.4 unified gather path; streamed meshes expose their current LOD cut\n * through the same view because they inherit {@link SplatMesh}.\n *\n * @experimental May change in a minor release.\n */\nexport interface UnifiedSourceView {\n  /** Total addressable pool slots. */\n  readonly capacity: number;\n  /** Pool indices of active splats, packed from zero. */\n  readonly sourceIndex: THREE.StorageBufferAttribute;\n  /** Active entries at the front of {@link sourceIndex}. */\n  readonly activeCount: number;\n  /** Local-space centers, RGBA32F and pool-indexed. */\n  readonly centersTexture: THREE.DataTexture;\n  /** Source display color and opacity, RGBA8 and pool-indexed. */\n  readonly colorsTexture: THREE.DataTexture;\n  /** Upper covariance rows, RGBA32F and pool-indexed. */\n  readonly covarianceATexture: THREE.DataTexture;\n  /** Final covariance row, RGBA32F and pool-indexed. */\n  readonly covarianceBTexture: THREE.DataTexture;\n  /** Centers texture row width. */\n  readonly dataTextureWidth: number;\n  /** Current source-local → world transform. */\n  readonly matrixWorld: THREE.Matrix4;\n  /** Conservative world-space bound for depth quantization. */\n  readonly worldBounds: THREE.Sphere;\n  /** Higher-order color data resolved by the gather pass when present. */\n  readonly sh: SplatShInputs | null;\n  /** Effect hooks and their source-local data channels. */\n  readonly modifiers: readonly SplatModifier[];\n  /**\n   * True when this source is itself a unified pool with per-source placement\n   * (`MergedSplatMesh`). The gather path cannot resolve nested placement, so\n   * `UnifiedSplatMesh` rejects these sources.\n   */\n  readonly hasSourcePlacement: boolean;\n  readonly channels: ReadonlyMap<string, { texture: THREE.DataTexture }>;\n  /** Same uniform node the source graph updates each frame. */\n  readonly localCameraPosition: Vec3Uniform;\n  /** Changes whenever a modifier graph must be rebuilt. */\n  readonly graphRevision: number;\n  /** Whether this source intentionally composites in display (sRGB) space. */\n  readonly srgbOutput: boolean;\n  /** Shared draw-path settings that must agree across unified sources. */\n  readonly maxStdDev: number;\n  /** Screen-space minimum splat radius, px (0 = off). */\n  readonly minSplatSizePx: number;\n  readonly antialias: boolean;\n  /** Construction-time projected-footprint policy shared by one unified pass. */\n  readonly projectedFilterProfile: ProjectedFilterProfile;\n  /**\n   * Whether this source stores Spark LOD alpha (`alpha ÷ 2`, `.rad`). The\n   * gather recovers the full `alpha ∈ [0,2]`; the draw material then treats\n   * `alpha > 1` as a merged node. Per source, not a compatibility field - a\n   * scene may mix `.rad` and non-`.rad` sources.\n   */\n  readonly lodAlpha: boolean;\n  /** Increments whenever pool-backed data or active residency changes. */\n  readonly contentRevision: number;\n}\n\n/** Quality-compatible rendering or smoother contribution-culling rendering. */\nexport type SplatPerformanceProfile = 'quality' | 'smooth';\n\n/**\n * Options for {@link SplatMesh.pick}.\n *\n * Picking returns the selected splat's rendered center plane (depth-tested\n * Gaussian coverage), not a persistent splat identifier or a collision mesh.\n */\nexport interface SplatPickOptions {\n  /**\n   * Minimum Gaussian opacity (after falloff × splat alpha) for a fragment to\n   * count as a hit. Default `0.1`.\n   */\n  alphaThreshold?: number;\n}\n\n/**\n * Result of a successful {@link SplatMesh.pick}.\n *\n * The point lies on the frontmost splat's billboard plane at the picked\n * pixel - suitable for click-to-focus and placement anchors, not physics.\n */\nexport interface SplatPickResult {\n  /** Hit position in world space. */\n  readonly point: THREE.Vector3;\n  /** Distance from the camera position to {@link point}. */\n  readonly distance: number;\n}\n\n/**\n * Result of {@link SplatMesh.queryNearest}: the resident splat center closest\n * to the query point, in world space.\n */\nexport interface SplatNearestResult {\n  /** The splat's center, in world space. */\n  readonly point: THREE.Vector3;\n  /** World-space distance from the query point to {@link point}. */\n  readonly distance: number;\n}\n\n/** Result of a successful synchronous {@link SplatMesh.queryRay}. */\nexport interface SplatRayResult {\n  /** Resident splat center in world space. */\n  readonly point: THREE.Vector3;\n  /** Distance along the ray from its origin to the center's closest plane. */\n  readonly distance: number;\n}\n\n/**\n * Result of {@link SplatMesh.queryHeight}: the supporting surface found beneath\n * the query point (the highest resident splat within the drop and horizontal\n * radius), in world space.\n */\nexport interface SplatHeightResult {\n  /** The supporting splat's center, in world space. */\n  readonly point: THREE.Vector3;\n  /** How far below the query point the surface sits (world units, ≥ 0). */\n  readonly drop: number;\n}\n"],"names":["resolveSplatFoveationMode","mode","fallback","isPageTableFoveation","MAX_SH_BANDS","resolveSplatPerformanceProfile","explicit","profile","detectSplatDeviceProfile","isFillConstrainedSplatDevice"],"mappings":";AAoBO,SAASA,EACdC,GACAC,IAA+B,QACX;AACpB,SAAOD,KAAQC;AACjB;AAGO,SAASC,EAAqBF,GAAmC;AACtE,SAAOA,MAAS;AAClB;AAiCO,MAAMG,IAAe;AAQrB,SAASC,EACdC,GACAC,IAA0CC,KACjB;AACzB,SAAOF,MAAaG,EAA6BF,CAAO,IAAI,WAAW;AACzE;"}

package/dist/static-lod.js

@@ -3,7 +3,7 @@ var V = (s, r, e) => r in s ? S(s, r, { enumerable: !0, configurable: !0, writab
 var i = (s, r, e) => V(s, typeof r != "symbol" ? r + "" : r, e);
 import * as g from "three/webgpu";
 import { loadSplatData as L } from "./loaders.js";
-import { S as P } from "./splat-mesh-CsLOQb08.js";
+import { S as P } from "./splat-mesh-B1KlWHvx.js";
 const b = 4096, A = 250, x = (s) => {
   const r = [
     s.positions.buffer,

package/dist/streaming/lod-scheduler.d.ts

@@ -217,6 +217,38 @@ export declare class LodScheduler implements LodSource {
      * to substitute always-cached coverage while a finer level is fetching.
      */
     coarsestRunsFor(from: number, to: number): LodRun[];
+    /**
+     * Covering runs for physical coverage groups currently in the camera frustum
+     * (or containing the camera). Classic LCC cells that split into sub-leaves
+     * share a group, so one in-view slice holds the whole cell. Leaves without a
+     * coverage group (Streamed SOG, the environment tile) are ignored. An empty
+     * frustum falls back to the nearest group so a skyward start still paints
+     * something.
+     *
+     * Classic cells tile X/Y and span the full scene Z. An AABB frustum test
+     * (especially with {@link FRUSTUM_MARGIN} on that diagonal) then hits the
+     * whole grid from any indoor pose. Unpadded intersection plus an AABB vs
+     * forward half-space test (support vertex along `cameraForward`) keeps the
+     * hold to cells that poke in front of the camera, including a neighbour
+     * whose centre sits behind the look. Cells within `lodBaseDistance` that
+     * poke forward are held even when the unpadded frustum misses — a 30 m
+     * PentHouse column 5 m away can fill the frame while the look is 60° off
+     * its face.
+     *
+     * Nearby groups (`distance ≤ lodBaseDistance · lodMultiplier`) freeze at
+     * finest+1 (L1 when L0 exists). Farther in-view groups freeze at coarsest.
+     * Startup never waits for L0.
+     */
+    coverageRunsFor(cameraLocal: THREE.Vector3, frustum: THREE.Frustum, cameraForward?: THREE.Vector3): LodRun[];
+    /**
+     * True when any point of `box` sits strictly in front of the camera plane
+     * (`origin` + `forward`). Uses the AABB support vertex along `forward`, so a
+     * cell that straddles the camera still counts if it pokes into the view.
+     */
+    private boxPokesForward;
+    /** Leaf AABB expanded by {@link FRUSTUM_MARGIN}, written into scratch. */
+    private expandLeafBox;
+    private leafIntersectsFrustum;
     /**
      * Runs covering [from, to) at `level`, clamped per leaf to an available rung
      * (prefer the requested level, else the next coarser, else the next finer).

package/dist/streaming/lod-source.d.ts

@@ -32,12 +32,17 @@ export interface LodSource {
      */
     runsAtLevelFor?(from: number, to: number, level: number): LodRun[];
     /**
-     * Coarsest covering runs for finest cells currently in the camera frustum.
-     * Used by `.lcc2` startup `initialReveal: 'hold-coverage'` so the first
-     * painted frame has no empty cells. Optional: sources without a nested
-     * octree cover leave it undefined (the hold then stays disabled).
+     * Covering runs for finest cells currently in the camera frustum (or
+     * containing the camera). Used by `.lcc` / `.lcc2` startup
+     * `initialReveal: 'hold-coverage'` so the first painted frame has no empty
+     * cells. Classic LCC freezes nearby groups at finest+1 and farther in-view
+     * groups at coarsest; `.lcc2` still returns coarsest root-children.
+     * `cameraForward` (mesh-local) lets classic LCC ignore full-Z cells that
+     * sit entirely behind the camera plane — their AABBs otherwise hit the
+     * frustum from every indoor pose. Optional: sources without coverage groups
+     * or a nested octree cover leave it undefined (the hold then stays disabled).
      */
-    coverageRunsFor?(cameraLocal: THREE.Vector3, frustum: THREE.Frustum): LodRun[];
+    coverageRunsFor?(cameraLocal: THREE.Vector3, frustum: THREE.Frustum, cameraForward?: THREE.Vector3): LodRun[];
     /**
      * Notified when a chunk finishes decoding, so a source that discovers its
      * structure from chunk payloads (a `.rad` LOD tree lives in the chunks, not
@@ -75,10 +80,11 @@ export interface StreamedChunkOptions {
 }
 /**
  * A single always-resident environment/background tile a format ships outside
- * its LOD structure - the `.lcc2` `env.sog` sky, loaded once and toggled with
- * {@link StreamedSplatMesh.setEnvironmentEnabled} rather than scheduled by
- * camera distance. Its splat count is absent from the manifest and measured
- * when the tile decodes (see `docs/formats/lcc2-notes.md`).
+ * its LOD structure - classic `.lcc` `environment.bin` and `.lcc2` `env.sog`,
+ * loaded once and toggled with {@link StreamedSplatMesh.setEnvironmentEnabled}
+ * rather than scheduled by camera distance. `.lcc2` measures the splat count
+ * at decode (see `docs/formats/lcc2-notes.md`); classic `.lcc` sizes it from
+ * the file length.
  */
 export interface EnvironmentTile {
     /** Chunk-file index (into {@link StreamedScene.chunkUrls}) of the tile. */

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

@@ -23,7 +23,8 @@ export declare function estimateSceneDecodedBytes(scene: StreamedScene): number;
 /**
  * Read-only startup-hold progress for {@link StreamedSplatMeshOptions.initialReveal}.
  * Exported for hosts that gate visibility on the first useful coverage frame
- * (classic `.lcc` nearby L0, or `.lcc2` in-view coarsest cells).
+ * (classic `.lcc` nearby L1 / far coarsest, `.lcc2` in-view coarsest, or an
+ * explicit nearby-L0 hold).
  */
 export type InitialRevealState = {
     readonly status: 'disabled';
@@ -172,28 +173,35 @@ export interface StreamedSplatMeshOptions extends SplatMeshOptions {
      * - `'progressive'`: cells become visible as each swap group commits — can
      *   show sparse near-detail (classic `.lcc`) or empty octree squares
      *   (`.lcc2`) 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.
-     * - `'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), 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.
+     * - `'hold-near-l0'` (opt-in): 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. Classic `.lcc` uses the **resolved**
+     *   cut from the first schedule (after camera + format transform), not
+     *   distance ambition alone.
+     * - `'hold-coverage'` (the default for classic `.lcc` and `.lcc2` when
+     *   unset): hide the mesh until every in-view finest cell has covering
+     *   coverage resident, and until the always-resident environment tile is in
+     *   the pool when the scene ships one and it starts enabled. Classic `.lcc`
+     *   freezes nearby cells (within `lodBaseDistance · lodMultiplier`) at
+     *   finest+1 (L1, never L0) and farther in-view cells at coarsest. A cell
+     *   counts as in-view when the camera stands inside it, or when the unpadded
+     *   AABB hits the frustum and pokes in front of the camera plane (support
+     *   vertex — centres behind the look still count), **or** the cell is within
+     *   `lodBaseDistance` and pokes forward (30 m neighbours that fill the
+     *   frame while the look is off-axis). `.lcc2` still waits on
+     *   coarsest root-children. 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
-     * the **resolved** cut from the first schedule (after camera + format
-     * transform), not distance ambition alone. Other streamed formats default
-     * to `'progressive'`.
+     * finish. Does not make detail downloads instantaneous. Other streamed
+     * formats default to `'progressive'`.
      */
     initialReveal?: 'progressive' | 'hold-near-l0' | 'hold-coverage';
     /** Receives lightweight LOD mutation events for performance attribution. */
@@ -927,11 +935,19 @@ export declare class StreamedSplatMesh extends SplatMesh {
     private publishInitialRevealProgress;
     private releaseInitialReveal;
     /**
-     * `.lcc2` coverage hold: freeze coarsest covering runs for in-view cells.
+     * Coverage hold: freeze covering runs for in-view cells (classic `.lcc`
+     * physical cells at L1 near / coarsest far, `.lcc2` octree root-children).
      * Missing `coverageRunsFor` (or an empty result after fallback) releases
      * immediately so the mesh does not stay hidden with nothing to fetch.
+     * If the mixed set overflows the pool, coarsen only the near (non-coarsest)
+     * groups one more rung before degrading to progressive.
      */
     private captureCoverageHold;
+    /**
+     * Bump each coverage run one coarser rung when the source has one. Already-
+     * coarsest (far) runs stay put so a tight pool only drops near L1 → L2.
+     */
+    private coarsenCoverageNearRuns;
     private captureOrContinueInitialReveal;
     /** After staging/commits, release the hold when every frozen run is resident. */
     private finishInitialRevealIfComplete;