feat: add thin-instance LOD and CSM caster caps

[deltakosh]

Summary

• add GPU-driven thin-instance distance LOD through setThinInstanceLodPartner and clearThinInstanceLodPartner, with near/far compaction buckets, deterministic transition bands, partner lifecycle handling, and safe fallback behavior
• preserve the selected pixel's original framebuffer fragmentCoord in GPU picking discard shaders, including DPR and camera viewport offsets
• add setShadowCasterMaxCascade so CSM casters can skip far cascade layers, including incremental live cap updates when the caster array is re-supplied
• retry transient GitHub 429/5xx responses in release-marker validation, with a child-process regression for the Azure failure seen on this PR
• update architecture docs, regression coverage, and all affected per-scene bundle manifests

Validation

• pnpm run lint
• pnpm test:unit: 885 passed
• pnpm test: all 214 bundle builds and every bundle ceiling passed; parity completed with 427 passed and the five established local baseline failures in Scenes 47, 104, 105, 106, and 265
• clean origin/master reproduced the exact Scene 104, 105, 106, and 265 MAD values; Scene 47 is the known nondeterministic Havok baseline
• visual GPU probe confirmed all 121 instances switch between the full-detail and LOD meshes, with one compute dispatch and two indirect draws

Bundle size

• Scene 1: 88.2 KB -> 88.2 KB (+0.0 KB)
• Scene 214 CSM: 68.4 KB -> 68.5 KB (+0.1 KB, limit 69 KB)
• Scene 215 CSM PBR: 80.0 KB -> 80.1 KB (+0.1 KB, limit 80.1 KB)
• no bundle ceilings changed

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[bjsplat]

API Changes

API Extractor detected public API changes for @babylonjs/lite.

No removed public API lines were detected; this appears to be additive.

API Extractor diff

diff --git a/home/vsts/work/1/s/test-results/api-report/target/temp/babylon-lite.api.md b/home/vsts/work/1/s/test-results/api-report/current/temp/babylon-lite.api.md
index 0910ad69..2778db08 100644
--- a/home/vsts/work/1/s/test-results/api-report/target/temp/babylon-lite.api.md
+++ b/home/vsts/work/1/s/test-results/api-report/current/temp/babylon-lite.api.md
@@ -959,6 +959,9 @@ export function clearSprite2DLayer(layer: Sprite2DLayer): void;
 // @public
 export function clearSpriteAnimations(manager: SpriteAnimationManager): void;
 
+// @public
+export function clearThinInstanceLodPartner(fullMesh: Mesh): void;
+
 // @public
 export type ClipPlane = readonly [number, number, number, number];
 
@@ -4911,6 +4914,9 @@ export function setShaderUniform(material: ShaderMaterial, name: string, value:
 // @public
 export function setShaderVector3(material: ShaderMaterial, name: string, value: readonly [number, number, number]): void;
 
+// @public
+export function setShadowCasterMaxCascade(mesh: Mesh, maxCascade: number): void;
+
 // @public
 export function setShadowTaskCasterMeshes(shadowGenerator: ShadowGenerator, casterMeshes: readonly Mesh[]): void;
 
@@ -4985,6 +4991,9 @@ export function setThinInstanceCullBoundsPad(mesh: Mesh, pad: number): void;
 // @public
 export function setThinInstanceDrawCount(mesh: Mesh, count: number): void;
 
+// @public
+export function setThinInstanceLodPartner(fullMesh: Mesh, lodMesh: Mesh, options: ThinInstanceLodPartnerOptions): void;
+
 // @public
 export function setThinInstanceMatrix(mesh: Mesh, index: number, matrix: Mat4): void;
 
@@ -6028,6 +6037,12 @@ export interface ThinInstanceData {
     matrices: Float32Array | Float64Array;
 }
 
+// @public
+export interface ThinInstanceLodPartnerOptions {
+    band?: number;
+    distance: number;
+}
+
 // @public
 export interface TintProps {
     atDistance?: number;

[bjsplat]

Lite Playground - Static Site

Open deployed site

_{Build 20260716.9 - merge @ 184bf43}

[bjsplat]

API Changes

API Extractor detected public API changes for @babylonjs/lite.

No removed public API lines were detected; this appears to be additive.

API Extractor diff

diff --git a/home/vsts/work/1/s/test-results/api-report/target/temp/babylon-lite.api.md b/home/vsts/work/1/s/test-results/api-report/current/temp/babylon-lite.api.md
index 0910ad69..2778db08 100644
--- a/home/vsts/work/1/s/test-results/api-report/target/temp/babylon-lite.api.md
+++ b/home/vsts/work/1/s/test-results/api-report/current/temp/babylon-lite.api.md
@@ -959,6 +959,9 @@ export function clearSprite2DLayer(layer: Sprite2DLayer): void;
 // @public
 export function clearSpriteAnimations(manager: SpriteAnimationManager): void;
 
+// @public
+export function clearThinInstanceLodPartner(fullMesh: Mesh): void;
+
 // @public
 export type ClipPlane = readonly [number, number, number, number];
 
@@ -4911,6 +4914,9 @@ export function setShaderUniform(material: ShaderMaterial, name: string, value:
 // @public
 export function setShaderVector3(material: ShaderMaterial, name: string, value: readonly [number, number, number]): void;
 
+// @public
+export function setShadowCasterMaxCascade(mesh: Mesh, maxCascade: number): void;
+
 // @public
 export function setShadowTaskCasterMeshes(shadowGenerator: ShadowGenerator, casterMeshes: readonly Mesh[]): void;
 
@@ -4985,6 +4991,9 @@ export function setThinInstanceCullBoundsPad(mesh: Mesh, pad: number): void;
 // @public
 export function setThinInstanceDrawCount(mesh: Mesh, count: number): void;
 
+// @public
+export function setThinInstanceLodPartner(fullMesh: Mesh, lodMesh: Mesh, options: ThinInstanceLodPartnerOptions): void;
+
 // @public
 export function setThinInstanceMatrix(mesh: Mesh, index: number, matrix: Mat4): void;
 
@@ -6028,6 +6037,12 @@ export interface ThinInstanceData {
     matrices: Float32Array | Float64Array;
 }
 
+// @public
+export interface ThinInstanceLodPartnerOptions {
+    band?: number;
+    distance: number;
+}
+
 // @public
 export interface TintProps {
     atDistance?: number;

[bjsplat]

Lite Playground - Static Site

Open deployed site

_{Build 20260717.3 - merge @ a198c4f}

[bjsplat]

Bundle Size Changes

Increases

Package	Current	Master	Change
Scene 173 - Navigation Dynamic Obstacles scene173	63 KB	62 KB	+1 KB
Scene 214 — Cascaded Shadow Maps scene214	69 KB	68 KB	+1 KB
Scene 223 — Camera + Light Gizmos scene223	65 KB	64 KB	+1 KB

Sizes rounded to nearest KB. Run pnpm build:bundle-scenes locally to verify.

[bjsplat]

Lab - Static Site

Open deployed site

_{Build 20260717.3 - merge @ a198c4f}

[Copilot]

Pull request overview

Copilot reviewed 143 out of 143 changed files in this pull request and generated 1 comment.

[bjsplat]

API Changes

API Extractor detected public API changes for @babylonjs/lite.

No removed public API lines were detected; this appears to be additive.

API Extractor diff

diff --git a/home/vsts/work/1/s/test-results/api-report/target/temp/babylon-lite.api.md b/home/vsts/work/1/s/test-results/api-report/current/temp/babylon-lite.api.md
index 0910ad69..2778db08 100644
--- a/home/vsts/work/1/s/test-results/api-report/target/temp/babylon-lite.api.md
+++ b/home/vsts/work/1/s/test-results/api-report/current/temp/babylon-lite.api.md
@@ -959,6 +959,9 @@ export function clearSprite2DLayer(layer: Sprite2DLayer): void;
 // @public
 export function clearSpriteAnimations(manager: SpriteAnimationManager): void;
 
+// @public
+export function clearThinInstanceLodPartner(fullMesh: Mesh): void;
+
 // @public
 export type ClipPlane = readonly [number, number, number, number];
 
@@ -4911,6 +4914,9 @@ export function setShaderUniform(material: ShaderMaterial, name: string, value:
 // @public
 export function setShaderVector3(material: ShaderMaterial, name: string, value: readonly [number, number, number]): void;
 
+// @public
+export function setShadowCasterMaxCascade(mesh: Mesh, maxCascade: number): void;
+
 // @public
 export function setShadowTaskCasterMeshes(shadowGenerator: ShadowGenerator, casterMeshes: readonly Mesh[]): void;
 
@@ -4985,6 +4991,9 @@ export function setThinInstanceCullBoundsPad(mesh: Mesh, pad: number): void;
 // @public
 export function setThinInstanceDrawCount(mesh: Mesh, count: number): void;
 
+// @public
+export function setThinInstanceLodPartner(fullMesh: Mesh, lodMesh: Mesh, options: ThinInstanceLodPartnerOptions): void;
+
 // @public
 export function setThinInstanceMatrix(mesh: Mesh, index: number, matrix: Mat4): void;
 
@@ -6028,6 +6037,12 @@ export interface ThinInstanceData {
     matrices: Float32Array | Float64Array;
 }
 
+// @public
+export interface ThinInstanceLodPartnerOptions {
+    band?: number;
+    distance: number;
+}
+
 // @public
 export interface TintProps {
     atDistance?: number;

[bjsplat]

Lite Playground - Static Site

Open deployed site

_{Build 20260717.6 - merge @ d572dd0}

[bjsplat]

Bundle Size Changes

Increases

Package	Current	Master	Change
Scene 173 - Navigation Dynamic Obstacles scene173	63 KB	62 KB	+1 KB
Scene 214 — Cascaded Shadow Maps scene214	69 KB	68 KB	+1 KB
Scene 223 — Camera + Light Gizmos scene223	65 KB	64 KB	+1 KB

Sizes rounded to nearest KB. Run pnpm build:bundle-scenes locally to verify.

[bjsplat]

Lab - Static Site

Open deployed site

_{Build 20260717.6 - merge @ d572dd0}

[Copilot]

Pull request overview

Copilot reviewed 143 out of 143 changed files in this pull request and generated no new comments.

[bjsplat]

API Changes

API Extractor detected public API changes for @babylonjs/lite.

No removed public API lines were detected; this appears to be additive.

API Extractor diff

diff --git a/home/vsts/work/1/s/test-results/api-report/target/temp/babylon-lite.api.md b/home/vsts/work/1/s/test-results/api-report/current/temp/babylon-lite.api.md
index 0910ad69..2778db08 100644
--- a/home/vsts/work/1/s/test-results/api-report/target/temp/babylon-lite.api.md
+++ b/home/vsts/work/1/s/test-results/api-report/current/temp/babylon-lite.api.md
@@ -959,6 +959,9 @@ export function clearSprite2DLayer(layer: Sprite2DLayer): void;
 // @public
 export function clearSpriteAnimations(manager: SpriteAnimationManager): void;
 
+// @public
+export function clearThinInstanceLodPartner(fullMesh: Mesh): void;
+
 // @public
 export type ClipPlane = readonly [number, number, number, number];
 
@@ -4911,6 +4914,9 @@ export function setShaderUniform(material: ShaderMaterial, name: string, value:
 // @public
 export function setShaderVector3(material: ShaderMaterial, name: string, value: readonly [number, number, number]): void;
 
+// @public
+export function setShadowCasterMaxCascade(mesh: Mesh, maxCascade: number): void;
+
 // @public
 export function setShadowTaskCasterMeshes(shadowGenerator: ShadowGenerator, casterMeshes: readonly Mesh[]): void;
 
@@ -4985,6 +4991,9 @@ export function setThinInstanceCullBoundsPad(mesh: Mesh, pad: number): void;
 // @public
 export function setThinInstanceDrawCount(mesh: Mesh, count: number): void;
 
+// @public
+export function setThinInstanceLodPartner(fullMesh: Mesh, lodMesh: Mesh, options: ThinInstanceLodPartnerOptions): void;
+
 // @public
 export function setThinInstanceMatrix(mesh: Mesh, index: number, matrix: Mat4): void;
 
@@ -6028,6 +6037,12 @@ export interface ThinInstanceData {
     matrices: Float32Array | Float64Array;
 }
 
+// @public
+export interface ThinInstanceLodPartnerOptions {
+    band?: number;
+    distance: number;
+}
+
 // @public
 export interface TintProps {
     atDistance?: number;

[bjsplat]

Lite Playground - Static Site

Open deployed site

_{Build 20260717.10 - merge @ 89f6d24}

[bjsplat]

Bundle Size Changes

Increases

Package	Current	Master	Change
Scene 173 - Navigation Dynamic Obstacles scene173	63 KB	62 KB	+1 KB
Scene 214 — Cascaded Shadow Maps scene214	69 KB	68 KB	+1 KB

Decreases

Package	Current	Master	Change
Scene 222 — Composite Gizmos scene222	118 KB	119 KB	-1 KB

Sizes rounded to nearest KB. Run pnpm build:bundle-scenes locally to verify.

[bjsplat]

Lab - Static Site

Open deployed site

_{Build 20260717.10 - merge @ 89f6d24}