feat: add thin-instance LOD and CSM caster caps

docs/lite/architecture/00-overview.md

@@ -381,6 +381,7 @@ createEsmDirectionalShadowGenerator(engine: Engine, light: DirectionalLight, con
 createPcfSpotlightShadowGenerator(engine: Engine, light: SpotLight, config?: PcfSpotlightShadowGeneratorConfig): ShadowGenerator
 createPcfDirectionalShadowGenerator(engine: Engine, light: DirectionalLight, config?: PcfDirectionalShadowGeneratorConfig): ShadowGenerator
 setShadowTaskCasterMeshes(shadowGenerator: ShadowGenerator, casterMeshes: readonly Mesh[]): void
+setShadowCasterMaxCascade(mesh: Mesh, maxCascade: number): void
 
 // Animation
 createAnimationController(skeleton, scene): AnimationController

docs/lite/architecture/12-thin-instances.md

@@ -35,6 +35,8 @@ export interface ThinInstanceData {
     _colorGpuBufferStorage: boolean;
     _colorGpuVersion: number;
     _gpuCullingEnabled: boolean; // opt-in GPU frustum culling + indirect draw
+    _lodPartner?: Mesh | null; // lower-detail mesh receiving the far cull bucket
+    _lodSource?: Mesh | null; // source mesh when this mesh is the LOD partner
 }
 ```
 
@@ -70,6 +72,17 @@ export function setThinInstanceColors(mesh: Mesh, colors: Float32Array): void;
 
 /** Enable/disable per-pass GPU frustum culling. Must be called before registerScene(). */
 export function enableThinInstanceGpuCulling(mesh: Mesh, enabled?: boolean): void;
+
+interface ThinInstanceLodPartnerOptions {
+    distance: number; // camera-space switch distance in world units
+    band?: number; // deterministic per-instance dither width, default 0
+}
+
+/** Split one GPU-culling result into near/full-detail and far/LOD buckets. */
+export function setThinInstanceLodPartner(fullMesh: Mesh, lodMesh: Mesh, options: ThinInstanceLodPartnerOptions): void;
+
+/** Restore the two meshes to independent rendering. */
+export function clearThinInstanceLodPartner(fullMesh: Mesh): void;
 ```
 
 `setThinInstanceDrawCount()` is the count-only path for fixed-capacity pools whose CPU array and GPU
@@ -256,7 +269,7 @@ Returns the updated `slot` number — the next free vertex buffer slot after all
 
 GPU culling is opt-in through `enableThinInstanceGpuCulling(mesh)`. The helper only flips state on existing `ThinInstanceData`; the compute module is dynamically imported (via the shared `thin-instance-cull-binding.ts` lifecycle helper) by the Standard, PBR, and ShaderMaterial group builders only when at least one mesh in that material family has `_gpuCullingEnabled === true`.
 
-The per-binding cull lifecycle is factored into one shared module, `packages/babylon-lite/src/mesh/thin-instance-cull-binding.ts`, used identically by all three material families. Its `tryBind()` seam is called from each renderable's `bind()`: it gates on opt-in + opaque-only, marks the renderable `_direct`, creates the per-binding `ThinInstanceGpuCullState`, registers its disposal, and returns a `TiCullBinding` whose `update()` dispatches the compute cull pass and whose `draw()` issues `drawIndexedIndirect` (or falls back to a normal instanced draw when culling did not run).
+The per-binding cull lifecycle is factored into one shared module, `packages/babylon-lite/src/mesh/thin-instance-cull-binding.ts`, used identically by all three material families. Its `tryBind()` seam is called from each renderable's `bind()`: it gates on opt-in + opaque-only, creates the per-binding `ThinInstanceGpuCullState`, registers its disposal, and returns a `TiCullBinding` whose `update()` dispatches the compute cull pass and whose `draw()` issues `drawIndexedIndirect` (or falls back to a normal instanced draw when culling did not run).
 
 ### Scope
 
@@ -289,7 +302,7 @@ Cull state is owned by each `DrawBinding`, not by `ThinInstanceData`, because th
 6. The compute shader transforms the local sphere by `mesh.world * instanceWorld`, tests it against all planes, atomically appends visible instances to compacted buffers, and atomically increments `args[1]`.
 7. The draw closure binds compacted buffers and calls `drawIndexedIndirect(argsBuffer, 0)`.
 
-Cull-enabled renderables set `_direct = true` so they are encoded every frame with current buffer objects instead of being captured in the opaque render bundle. This avoids stale render-bundle references when thin-instance capacity grows.
+Cull-enabled opaque renderables remain bundle-compatible because their compacted buffers and indirect argument buffers are stable. Any buffer replacement bumps the global visibility epoch, forcing the opaque render bundle to record the new handles before it executes.
 
 ### Compute Shader Outline
 
@@ -307,6 +320,16 @@ if (sphereIntersectsFrustum(center, radius)) {
 
 The test is conservative: spheres touching a plane stay visible. This preserves parity with non-culled rendering.
 
+### Distance LOD Pairing
+
+`setThinInstanceLodPartner(fullMesh, lodMesh, { distance, band })` extends the opt-in GPU culler with a second compacted output. Both meshes must already have thin-instance state and must be distinct, opaque, non-transmissive meshes. The full-detail mesh must be the only source for the partner, and neither mesh may simultaneously participate in another LOD chain. LOD-paired thin-instance state cannot be shared through `cloneTransformNode`; pair meshes only before cloning or use independent thin-instance data. `distance` and `band` are finite non-negative world-space values.
+
+The source mesh retains in-frustum instances closer than the threshold. Farther instances are compacted into stable matrix/color buffers and an indirect argument buffer consumed by the partner. `band` applies a deterministic instance-index hash in `[-band/2, +band/2]`, spreading transitions without frame-to-frame noise. The partner's geometry and material pipeline are its own, but its drawn matrices and optional instance colors come from the source. A partner that renders instance colors therefore requires the source draw to provide them too.
+
+The far bucket is published per `RenderTargetSignature`, so main, shadow, and auxiliary camera passes never share compacted state. Partner renderables use the direct-draw phase and resolve the current bucket after all binding updates and the shared compute batch have completed; scene insertion order therefore cannot introduce a one-frame lag or capture stale cross-renderable handles in an opaque bundle. Source renderables retain their normal stable-buffer bundle path. If source culling is unavailable, disabled, hidden, or empty, the source falls back to drawing all active instances and the paired partner draws nothing.
+
+Pairing is configured after `setThinInstances()` and before `registerScene()`. Repeating the call with the same pair updates `distance`/`band` live. `clearThinInstanceLodPartner()` makes the partner fall back to its independent instance draw immediately; pairing links are also detached automatically when either mesh is disposed so no draw retains destroyed far-bucket buffers.
+
 ---
 
 ## Pipeline Configuration

docs/lite/architecture/16-shadow-generator.md

@@ -54,10 +54,14 @@ export interface ShadowTaskInputs {
 }
 
 export function setShadowTaskCasterMeshes(shadowGenerator: ShadowGenerator, casterMeshes: readonly Mesh[]): void;
+
+export function setShadowCasterMaxCascade(mesh: Mesh, maxCascade: number): void;
 ```
 
 Caster meshes are task inputs. Scene setup creates the filter-specific `ShadowGenerator`, assigns it to the light, calls `setShadowTaskCasterMeshes()` to provide the caster list, then calls `registerSceneWithShadowSupport()` instead of `registerScene()` to install the scene-owned shadow task.
 
+`setShadowCasterMaxCascade()` is CSM-specific: it limits a caster to layers `0..maxCascade`, accepts a non-negative integer or `Infinity`, and is applied when a new caster-array instance is supplied. ESM and single-map PCF ignore it.
+
 ### Common ShadowGenerator Interface (`shadow-generator.ts`)
 
 ```typescript
@@ -161,6 +165,7 @@ import { ensurePcfShadowTaskState, preloadPcfShadowTaskState, renderPcfShadowMap
 Shadow generators share math and UBO packing helpers only. Caster ownership lives in `ShadowTaskInputs`:
 
 - **`setShadowTaskCasterMeshes()`** — registers the caster mesh list for a generator in lazy task-owned input state.
+- **`setShadowCasterMaxCascade()`** — stores a lazy per-mesh CSM cascade cap; `Infinity` clears it.
 - **`writeShadowUboFields()`** — packs a `ShadowGenerator`'s light matrix (16 floats), depth values (2 floats + 2 padding), and shadowsInfo (4 floats) into a 24-float array for downstream UBO upload.
 - **`buildLightViewMatrix()` / `multiply4x4()`** — shared light-space matrix math for ESM and PCF task paths.
 - **`createShadowParamsUBO()` / `createSharedShadowUBO()`** — shared GPU buffer setup for generator-owned receiver resources.

docs/lite/architecture/17-cascaded-shadow.md

@@ -41,6 +41,8 @@ function createCsmDirectionalShadowGenerator(engine: EngineContext, light: Direc
 function getCsmReceiverTexture(shadowGenerator: ShadowGenerator): Texture2D;
 
 function onCsmReceiverUpdate(shadowGenerator: ShadowGenerator, callback: (data: Float32Array) => void): () => void;
+
+function setShadowCasterMaxCascade(mesh: Mesh, maxCascade: number): void;
 ```
 
 Usage mirrors the other directional generators:
@@ -54,6 +56,13 @@ setShadowTaskCasterMeshes(light.shadowGenerator, casterMeshes);
 await registerSceneWithShadowSupport(scene);
 ```
 
+`setShadowCasterMaxCascade(mesh, maxCascade)` limits a caster to cascade layers
+`0..maxCascade` (`0` is nearest). The default is all cascades; pass `Infinity` to
+restore it. Values must be non-negative integer indexes or `Infinity`. The cap is
+snapshotted when `setShadowTaskCasterMeshes` supplies the caster set, so changing a
+live cap requires re-supplying a new caster-array instance. CSM updates only the
+changed caster's per-cascade task membership; ESM and single-map PCF ignore the cap.
+
 Custom `ShaderMaterial` receivers use the same public generator without reading its
 internal WebGPU resources:
 
@@ -233,6 +242,10 @@ Shadow-map recreation is not supported by the current fixed generator configurat
 therefore the wrapper remains valid until the generator's GPU resources are disposed
 with the scene.
 
+Each CSM task state also snapshots every caster's maximum cascade. When a new caster
+array is supplied without material changes, the incremental diff removes and re-adds
+only new, removed, or re-capped casters, preserving all unchanged caster packets.
+
 ## Babylon.js Equivalence Map
 
 | Babylon.js                              | Babylon Lite                                |
@@ -290,6 +303,10 @@ adapter creates one explicit 2d-array depth wrapper, reuses the generator textur
 comparison sampler without exposing them in its signature, preserves wrapper identity,
 survives a ShaderMaterial acquire/release cycle, and rejects ESM/PCF generators.
 
+`tests/lite/unit/shadow-caster-max-cascade.test.ts` validates cap input, default and
+reset behavior, and incremental reassignment of an existing caster across cascade
+tasks after a live cap change.
+
 ## File Manifest
 
 - `shadow/csm-directional-shadow-generator.ts` — public factory, custom-receiver

docs/lite/architecture/18-picking.md

@@ -47,6 +47,22 @@ interface Ray {
     direction: [number, number, number];
     length: number;
 }
+
+interface PickOptions {
+    filter?: (mesh: Mesh) => boolean;
+    discard?: PickDiscardRule;
+    debugLabel?: string;
+}
+
+// WGSL shape injected for custom discard rules.
+struct PickDiscardInput {
+    worldPos: vec3f,
+    fragmentCoord: vec2f, // selected pixel center in the original backing framebuffer
+    pickId: u32,
+    thinInstanceIndex: u32,
+    hasThinInstance: u32,
+    instanceExtras: vec4f,
+}
 ```
 
 ### Functions
@@ -90,7 +106,7 @@ and .babylon loader. No copies needed — the arrays already exist in JS memory.
 
 1. Each mesh (or thin instance) is assigned a sequential pick ID (1-based; 0 = miss).
 2. A WGSL shader writes the 24-bit pick ID as RGB at `@location(0)` and the fragment's NDC depth at `@location(1)`.
-3. The pass uses a **pick-zoomed view-projection** so only the picked pixel survives, drawing all meshes to a **1×1** target: two colour attachments (`rgba8unorm` pick ID + `r32float` NDC depth) plus a `depth24plus` depth buffer (reverse-Z, compare `greater`).
+3. The pass uses a **pick-zoomed view-projection** so only the picked pixel survives, drawing all meshes to a **1×1** target: two colour attachments (`rgba8unorm` pick ID + `r32float` NDC depth) plus a `depth24plus` depth buffer (reverse-Z, compare `greater`). Because the 1×1 fragment position is always `(0.5, 0.5)`, the scene UBO separately carries the selected pixel center in original backing-framebuffer coordinates for custom discard WGSL.
 4. The 1×1 pick-ID and depth texels are copied to staging buffers and read back.
 5. The pick ID is decoded: `(r << 16) | (g << 8) | b`.
 6. The world-space hit point is reconstructed by unprojecting NDC + the read-back depth through `inverse(VP)`.
@@ -179,13 +195,13 @@ each attachment is a single texel:
 **Regular meshes:**
 | Group | Binding | Type | Content |
 |-------|---------|------|---------|
-| 0 | 0 | uniform | `mat4x4f` — viewProjection (shared, 64 bytes) |
+| 0 | 0 | uniform | `mat4x4f` viewProjection + `vec2f` original fragment coordinate (shared, 80 bytes) |
 | 1 | 0 | uniform | `mat4x4f` world + `u32` pickId (80 bytes, 16-aligned) |
 
 **Thin-instanced meshes:**
 | Group | Binding | Type | Content |
 |-------|---------|------|---------|
-| 0 | 0 | uniform | `mat4x4f` — viewProjection (shared) |
+| 0 | 0 | uniform | `mat4x4f` viewProjection + `vec2f` original fragment coordinate (shared, 80 bytes) |
 | 1 | 0 | uniform | `u32` baseMeshPickId (16 bytes, padded) |
 | 1 | 1 | read-only-storage | `array<mat4x4f>` — instance world matrices |
 

lab/public/bundle/manifest/scene1.json

@@ -9,7 +9,7 @@
     "scene1-generate-mipmaps-DfKYIHYG.js",
     "scene1-gltf-glb-parser-BL74Wcec.js",
     "scene1-ibl-fragment-CeRrvT96.js",
-    "scene1-pbr-renderable-C_iqrKEA.js",
+    "scene1-pbr-renderable-98lkxJeN.js",
     "scene1-rgbd-decode-BqHBbXAD.js",
     "scene1-scene-uniforms-FTYH6Ct0.js",
     "scene1-singlelight-hemispheric-wgsl-BrmVaOY6.js",

lab/public/bundle/manifest/scene10.json

@@ -3,7 +3,7 @@
   "gzipKB": 21.7,
   "ignoredRawKB": 0,
   "runtimeChunks": [
-    "scene10-pbr-renderable-JEgGP_sP.js",
+    "scene10-pbr-renderable-BxJDR30z.js",
     "scene10-singlelight-hemispheric-wgsl-w0cK80Wf.js",
     "scene10.js"
   ]

lab/public/bundle/manifest/scene104.json

@@ -1,13 +1,13 @@
 {
-  "rawKB": 101.5,
+  "rawKB": 101.6,
   "gzipKB": 39.3,
   "ignoredRawKB": 0,
   "runtimeChunks": [
     "scene104-generate-mipmaps-C2O_HNRi.js",
-    "scene104-gltf-feature-registry-DT7MsLnT.js",
+    "scene104-gltf-feature-registry-BbgFUYeR.js",
     "scene104-gltf-glb-parser-BJfNq64D.js",
     "scene104-shader-composer-DishuYLa.js",
-    "scene104-standard-renderable-DtgBdvNf.js",
+    "scene104-standard-renderable-Dndx3Y1u.js",
     "scene104-std-lightmap-fragment-BtZeffyx.js",
     "scene104-wgsl-fog-m3PkjS7i.js",
     "scene104.js"

lab/public/bundle/manifest/scene105.json

@@ -4,10 +4,10 @@
   "ignoredRawKB": 0,
   "runtimeChunks": [
     "scene105-generate-mipmaps-q97-3GGe.js",
-    "scene105-gltf-feature-registry-Bja0apwS.js",
+    "scene105-gltf-feature-registry-B3NVx5ri.js",
     "scene105-gltf-glb-parser-BsWC1iTB.js",
     "scene105-shader-composer-DishuYLa.js",
-    "scene105-standard-renderable-CJrIUUrL.js",
+    "scene105-standard-renderable-0fsnyKYk.js",
     "scene105-std-lightmap-fragment-DJHrjMOe.js",
     "scene105-wgsl-fog-m3PkjS7i.js",
     "scene105.js"

lab/public/bundle/manifest/scene11.json

@@ -9,13 +9,13 @@
     "scene11-gltf-ext-spec-gloss-D60sFZYX.js",
     "scene11-gltf-feature-animations-B4VuXvAy.js",
     "scene11-gltf-feature-extras-VHPteGay.js",
-    "scene11-gltf-feature-registry-CpagfJwp.js",
+    "scene11-gltf-feature-registry-C82Q-vMl.js",
     "scene11-gltf-feature-skeleton-lVTm_rgW.js",
     "scene11-gltf-glb-parser-B0CzN8nR.js",
     "scene11-gltf-sampler-desc-_twQF5pG.js",
-    "scene11-pbr-renderable-CQGHBAlM.js",
+    "scene11-pbr-renderable-BOdxod8U.js",
     "scene11-singlelight-hemispheric-wgsl-B7Q6UIxj.js",
-    "scene11-skeleton-fragment-BTrVps6p.js",
+    "scene11-skeleton-fragment-BZnAUfd1.js",
     "scene11.js"
   ]
 }

lab/public/bundle/manifest/scene111.json

@@ -18,7 +18,7 @@
     "scene111-node-registry-CZFoka3V.js",
     "scene111-node-renderable-DsHgimzd.js",
     "scene111-node-shadow-Ckjwl7eT.js",
-    "scene111-pbr-renderable-BpH7gTds.js",
+    "scene111-pbr-renderable-CXaEOwUg.js",
     "scene111-pbr-shadow-fragment-CFzpdZcF.js",
     "scene111-shader-composer-CdmK2apN.js",
     "scene111-shadow-fragment-core-Dbe1xNkt.js",

lab/public/bundle/manifest/scene112.json

@@ -9,11 +9,11 @@
     "scene112-generate-mipmaps-CC5rHiTf.js",
     "scene112-gltf-ext-basisu-DzvX1Byt.js",
     "scene112-gltf-ext-dielectric-C6hvXXiF.js",
-    "scene112-gltf-feature-registry-hfyja7sC.js",
+    "scene112-gltf-feature-registry-GURwUtgi.js",
     "scene112-gltf-json-asset-JDq89jct.js",
     "scene112-ibl-fragment-CeRrvT96.js",
     "scene112-pbr-refraction-D08DQGUU.js",
-    "scene112-pbr-renderable-BF6rrTS_.js",
+    "scene112-pbr-renderable-BT3V7Gxf.js",
     "scene112-pbr-transmission-ext-BrX8tW-7.js",
     "scene112-rgbd-decode-CZsPghZT.js",
     "scene112-scene-uniforms-FTYH6Ct0.js",

lab/public/bundle/manifest/scene114.json

@@ -4,7 +4,7 @@
   "ignoredRawKB": 0,
   "runtimeChunks": [
     "scene114-morph-fragment-DLjixOml.js",
-    "scene114-pbr-renderable-PM3Fxc8W.js",
+    "scene114-pbr-renderable-DrwBCBSC.js",
     "scene114-pbr-template-ext-CiHpOV5G.js",
     "scene114-singlelight-hemispheric-wgsl-CEVgMDLE.js",
     "scene114-skeleton-fragment-qheSzR-l.js",

lab/public/bundle/manifest/scene115.json

@@ -10,17 +10,17 @@
     "scene115-gltf-color-normalize-4-WGzPL2.js",
     "scene115-gltf-feature-animations-BkTFKNwk.js",
     "scene115-gltf-feature-morph-DLWJRlR1.js",
-    "scene115-gltf-feature-registry-ChnXVhzz.js",
+    "scene115-gltf-feature-registry-BFrjFosk.js",
     "scene115-gltf-feature-skeleton-Bgw5Y0YP.js",
     "scene115-gltf-json-asset-EChxQgVl.js",
     "scene115-morph-fragment-BbCT_r5m.js",
     "scene115-morph-fragment-core-CTaOwZva.js",
-    "scene115-pbr-renderable-COSNhRzq.js",
+    "scene115-pbr-renderable-eMseufKo.js",
     "scene115-pbr-template-ext-CiHpOV5G.js",
     "scene115-shader-composer-DishuYLa.js",
     "scene115-singlelight-hemispheric-wgsl-Cyo3l2OW.js",
     "scene115-skeleton-fragment-B0VEBZFR.js",
-    "scene115-standard-renderable-veM92dGz.js",
+    "scene115-standard-renderable-B3xK1ePJ.js",
     "scene115-wgsl-fog-m3PkjS7i.js",
     "scene115.js"
   ]

lab/public/bundle/manifest/scene116.json

@@ -3,7 +3,7 @@
   "gzipKB": 31.3,
   "ignoredRawKB": 0,
   "runtimeChunks": [
-    "scene116-pbr-renderable-BJ10F1sj.js",
+    "scene116-pbr-renderable-1mPrKn0F.js",
     "scene116-shader-composer-Bga-tI-0.js",
     "scene116-singlelight-hemispheric-wgsl-hXzjd_qm.js",
     "scene116-standard-renderable-B6DFgoG2.js",

lab/public/bundle/manifest/scene118.json

@@ -6,7 +6,7 @@
     "scene118-billboard-pick-pipeline-efBlU1Ns.js",
     "scene118-billboard-renderable-BMoinrEu.js",
     "scene118-scene-uniforms-FTYH6Ct0.js",
-    "scene118-standard-renderable-IusTupZx.js",
+    "scene118-standard-renderable-DlgYfS07.js",
     "scene118.js"
   ]
 }

lab/public/bundle/manifest/scene12.json

@@ -1,17 +1,17 @@
 {
   "rawKB": 103.7,
-  "gzipKB": 42.4,
+  "gzipKB": 42.3,
   "ignoredRawKB": 0,
   "runtimeChunks": [
     "scene12-create-skeleton-yE34pa8K.js",
     "scene12-generate-mipmaps-WJd2dKx2.js",
     "scene12-gltf-animation-BjkCiBBl.js",
     "scene12-gltf-feature-animations-CZFTUgiy.js",
-    "scene12-gltf-feature-registry-D-WZZjm3.js",
+    "scene12-gltf-feature-registry-fRlEtyCQ.js",
     "scene12-gltf-feature-skeleton-Cxvue01k.js",
     "scene12-gltf-glb-parser-BrsOlymf.js",
     "scene12-ibl-fragment-CeRrvT96.js",
-    "scene12-pbr-renderable-AQ8a2h5D.js",
+    "scene12-pbr-renderable-b4c18C5f.js",
     "scene12-reflectance-fragment-BESl-7E9.js",
     "scene12-rgbd-decode-BLiTLohS.js",
     "scene12-scene-uniforms-FTYH6Ct0.js",

lab/public/bundle/manifest/scene122.json

@@ -3,7 +3,7 @@
   "gzipKB": 19.5,
   "ignoredRawKB": 0,
   "runtimeChunks": [
-    "scene122-gaussian-splatting-pipeline-sh-DCM3WMGs.js",
+    "scene122-gaussian-splatting-pipeline-sh-7Pe9evxc.js",
     "scene122.js"
   ]
 }

lab/public/bundle/manifest/scene123.json

@@ -3,7 +3,7 @@
   "gzipKB": 18.4,
   "ignoredRawKB": 0,
   "runtimeChunks": [
-    "scene123-gaussian-splatting-pipeline-sh-DqvbGZYF.js",
+    "scene123-gaussian-splatting-pipeline-sh-VanKw4Jm.js",
     "scene123.js"
   ]
 }

lab/public/bundle/manifest/scene124.json

@@ -3,7 +3,7 @@
   "gzipKB": 20.5,
   "ignoredRawKB": 0,
   "runtimeChunks": [
-    "scene124-gaussian-splatting-pipeline-sh-DYZuF8gE.js",
+    "scene124-gaussian-splatting-pipeline-sh-CoCXUHtI.js",
     "scene124-splat-ply-compressed-4vnSZMqI.js",
     "scene124.js"
   ]