@marble.fun/track-catalog 3.0.0

package/src/three/scene-shader-preparation.ts

@@ -0,0 +1,64 @@
+import * as THREE from 'three'
+
+interface SceneShaderPreparationOptions {
+  visibleRoot?: THREE.Object3D
+  yieldWork?: () => Promise<void>
+  shouldContinue?: () => boolean
+  includeVisibleScene?: boolean
+}
+
+/** Compile actual render objects under their final lighting, without drawing. */
+export async function prepareSceneShaders(
+  renderer: THREE.WebGLRenderer,
+  root: THREE.Object3D,
+  camera: THREE.Camera,
+  scene: THREE.Scene,
+  options: SceneShaderPreparationOptions = {},
+): Promise<void> {
+  const {
+    visibleRoot = root,
+    yieldWork = () => new Promise<void>(resolve => setTimeout(resolve, 0)),
+    shouldContinue = () => true,
+    includeVisibleScene = false,
+  } = options
+  const proxies: THREE.Object3D[] = []
+  const seen = new Set<THREE.Object3D>()
+  const collect = (object: THREE.Object3D): void => {
+    if (seen.has(object)) return
+    seen.add(object)
+    if (!(
+      object instanceof THREE.Mesh ||
+      object instanceof THREE.Line ||
+      object instanceof THREE.Points ||
+      object instanceof THREE.Sprite
+    ))
+      return
+    // Preserve geometry/instancing/skinning identity without copying buffers.
+    // Exclude children so every render object is visited exactly once.
+    const proxy = Object.create(object) as THREE.Object3D
+    proxy.children = []
+    proxies.push(proxy)
+  }
+  root.traverse(collect)
+  // The active theme can place foliage/world objects outside the track root.
+  // Include them at race handoff, while excluding unrelated hidden views.
+  if (includeVisibleScene) scene.traverseVisible(collect)
+  for (let offset = 0; offset < proxies.length; offset += 128) {
+    if (!shouldContinue()) return
+    const batch = new THREE.Group()
+    batch.children = proxies.slice(offset, offset + 128)
+    const visible = visibleRoot.visible
+    let pending: Promise<THREE.Object3D>
+    try {
+      // Three gathers lights synchronously inside compileAsync. Restore the
+      // cover's visibility before awaiting, so a shared animation loop never
+      // sees the hidden track. Hidden portal lights still enter the shader key.
+      visibleRoot.visible = true
+      pending = renderer.compileAsync(batch, camera, scene)
+    } finally {
+      visibleRoot.visible = visible
+    }
+    await pending
+    if (offset + 128 < proxies.length) await yieldWork()
+  }
+}

package/src/three/scene-theme-controller.ts

@@ -0,0 +1,461 @@
+import * as THREE from 'three'
+
+import {
+  computeShadowFocus,
+  configureKeyShadow,
+  configureSceneRenderer,
+  disposeSceneLightShadows,
+  resolveDynamicShadowRefreshRate,
+  resolveSceneLightingRig,
+  usesMobileSceneLighting,
+  type SceneLightingRig,
+} from './scene-lighting'
+import { themeAssetCache, type ThemePanoramaLease } from './theme-asset-cache'
+import { ThemeAmbienceController } from './theme-ambience-controller'
+import { ThemeMaterialRegistry } from './theme-material-registry'
+import { configureThemeMaterialTextureLoader } from './theme-material-assets'
+import { NEUTRAL_STUDIO_THEME, type TrackThemeDefinition } from './track-theme'
+import { createThemeWorld, type ThemeWorldState } from './theme-world-factory'
+import { visualQualityPolicy, type VisualQualityPolicy } from './visual-quality'
+
+export interface SceneThemeDiagnostics {
+  themeId: string
+  materialCount: number
+  worldMeshes: number
+  instancedMeshes: number
+  particleCount: number
+  particleSample?: readonly [number, number, number]
+  practicalLightCount: number
+  practicalLightPositions: readonly (readonly [number, number, number])[]
+  shadowMapSize: number
+  shadowExtent: number
+  shadowIntensity: number
+  exposure: number
+  environmentIntensity: number
+}
+
+export class SceneThemeController {
+  readonly materials = new ThemeMaterialRegistry(NEUTRAL_STUDIO_THEME)
+
+  private readonly lightRoot = new THREE.Group()
+  private readonly practicalLights: THREE.PointLight[] = []
+  private readonly ambience = new ThemeAmbienceController()
+  private readonly keyOffset = new THREE.Vector3()
+  private readonly shadowFocus = new THREE.Vector3()
+  private readonly nextShadowFocus = new THREE.Vector3()
+  private keyLight?: THREE.DirectionalLight
+  private lightingRig = resolveSceneLightingRig(NEUTRAL_STUDIO_THEME, false)
+  private world?: ThemeWorldState
+  private activeTheme = NEUTRAL_STUDIO_THEME
+  private panoramaLease?: ThemePanoramaLease
+  private requestVersion = 0
+  private elapsedSeconds = 0
+  private practicalLightRefreshElapsed = 0
+  private shadowRefreshElapsed = Number.POSITIVE_INFINITY
+  private shadowFocusInitialized = false
+  private dynamicShadowBudgetApplied = false
+  private adaptiveDynamicShadowRefreshRate: 30 | 60 = 60
+  private dynamicShadowRefreshRate = 60
+  private visualQualityPolicy = visualQualityPolicy('quality')
+  private disposed = false
+
+  constructor(
+    private readonly scene: THREE.Scene,
+    private readonly renderer: THREE.WebGLRenderer,
+    private readonly container: HTMLElement,
+  ) {
+    configureThemeMaterialTextureLoader(this.renderer)
+    this.scene.add(this.lightRoot)
+    this.applyPreparedTheme(NEUTRAL_STUDIO_THEME, undefined)
+  }
+
+  get theme(): TrackThemeDefinition {
+    return this.activeTheme
+  }
+
+  async applyTheme(theme: TrackThemeDefinition): Promise<boolean> {
+    this.assertActive()
+    const requestVersion = ++this.requestVersion
+    this.container.dataset.themeLoading = theme.id
+    let pendingPanoramaLease: ThemePanoramaLease | undefined
+    try {
+      pendingPanoramaLease = await themeAssetCache.acquirePanorama(theme)
+      if (requestVersion !== this.requestVersion || this.disposed) {
+        return false
+      }
+
+      this.container.classList.add('is-theme-transitioning')
+      this.applyPreparedTheme(theme, pendingPanoramaLease.texture)
+      this.panoramaLease?.release()
+      this.panoramaLease = pendingPanoramaLease
+      pendingPanoramaLease = undefined
+      window.setTimeout(() => this.container.classList.remove('is-theme-transitioning'), 320)
+      return true
+    } catch (error) {
+      if (requestVersion === this.requestVersion && !this.disposed) {
+        this.container.dataset.themeError = theme.id
+      }
+      console.error(`Unable to load the "${theme.id}" theme panorama.`, error)
+      return false
+    } finally {
+      pendingPanoramaLease?.release()
+      if (requestVersion === this.requestVersion) delete this.container.dataset.themeLoading
+    }
+  }
+
+  update(deltaSeconds: number, camera?: THREE.Camera, dynamicShadows = false, shadowFocusTarget?: THREE.Vector3): void {
+    if (this.disposed) return
+    this.elapsedSeconds += deltaSeconds
+    this.world?.update(deltaSeconds, this.elapsedSeconds)
+    if (camera && this.updateKeyShadowFocus(camera, shadowFocusTarget)) this.requestShadowUpdate()
+    if (dynamicShadows) {
+      this.applyDynamicShadowBudget()
+      this.shadowRefreshElapsed += deltaSeconds
+      this.adaptiveDynamicShadowRefreshRate = resolveDynamicShadowRefreshRate(
+        this.container.clientWidth,
+        deltaSeconds,
+        this.adaptiveDynamicShadowRefreshRate,
+      )
+      this.dynamicShadowRefreshRate = Math.min(
+        this.adaptiveDynamicShadowRefreshRate,
+        this.visualQualityPolicy.shadowRefreshRate,
+      )
+      if (this.shadowRefreshElapsed >= 1 / this.dynamicShadowRefreshRate) this.requestShadowUpdate()
+    } else {
+      this.restoreStaticShadowBudget()
+    }
+    if (this.practicalLights.length > 0) {
+      this.practicalLightRefreshElapsed += deltaSeconds
+      if (this.practicalLightRefreshElapsed >= 1.5) {
+        this.practicalLightRefreshElapsed = 0
+        this.refreshPracticalLightPositions()
+      }
+    }
+  }
+
+  requestShadowUpdate(): void {
+    this.shadowRefreshElapsed = 0
+    this.renderer.shadowMap.needsUpdate = true
+  }
+
+  setVisualQualityPolicy(policy: VisualQualityPolicy): void {
+    if (this.disposed || this.visualQualityPolicy === policy) return
+    this.visualQualityPolicy = policy
+    this.renderer.shadowMap.enabled = policy.tier !== 'low'
+    this.dynamicShadowRefreshRate = Math.min(this.dynamicShadowRefreshRate, policy.shadowRefreshRate)
+    this.applyParticleBudget()
+    if (!this.keyLight) return
+    const shadow = this.keyLight.shadow
+    const mapSize = this.desiredShadowMapSize(this.dynamicShadowBudgetApplied)
+    if (shadow.mapSize.width === mapSize && shadow.mapSize.height === mapSize) return
+    shadow.map?.dispose()
+    shadow.map = null
+    shadow.mapSize.set(mapSize, mapSize)
+    this.requestShadowUpdate()
+  }
+
+  diagnostics(): SceneThemeDiagnostics {
+    let worldMeshes = 0
+    let instancedMeshes = 0
+    let particleCount = 0
+    let particleSample: readonly [number, number, number] | undefined
+    this.world?.root.traverse(object => {
+      if (object instanceof THREE.InstancedMesh) {
+        instancedMeshes += 1
+        worldMeshes += 1
+      } else if (object instanceof THREE.Mesh) {
+        worldMeshes += 1
+      } else if (object instanceof THREE.Points) {
+        const positions = object.geometry.getAttribute('position')
+        particleCount += positions?.count ?? 0
+        if (!particleSample && positions?.count) {
+          particleSample = [positions.getX(0), positions.getY(0), positions.getZ(0)]
+        }
+      }
+    })
+    return {
+      themeId: this.activeTheme.id,
+      materialCount: Object.keys(this.activeTheme.materials).length,
+      worldMeshes,
+      instancedMeshes,
+      particleCount,
+      particleSample,
+      practicalLightCount: this.practicalLights.length,
+      practicalLightPositions: this.practicalLights.map(
+        light => [light.position.x, light.position.y, light.position.z] as const,
+      ),
+      shadowMapSize: this.keyLight?.shadow.mapSize.width ?? this.lightingRig.shadow.mapSize,
+      shadowExtent: this.lightingRig.shadow.extent,
+      shadowIntensity: this.lightingRig.shadow.intensity,
+      exposure: this.lightingRig.exposure,
+      environmentIntensity: this.lightingRig.environmentIntensity,
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.requestVersion += 1
+    this.world?.dispose()
+    this.world = undefined
+    disposeSceneLightShadows(this.lightRoot)
+    this.lightRoot.removeFromParent()
+    this.materials.dispose()
+    this.panoramaLease?.release()
+    this.panoramaLease = undefined
+    this.ambience.dispose()
+    this.scene.environment = null
+  }
+
+  private applyPreparedTheme(theme: TrackThemeDefinition, panorama: THREE.Texture | undefined): void {
+    this.materials.applyTheme(theme)
+    const mobile = usesMobileSceneLighting(this.container.clientWidth)
+    const preparedWorld = createThemeWorld(theme, this.materials, mobile)
+    this.world?.dispose()
+    this.world = preparedWorld
+    this.applyParticleBudget()
+    this.scene.add(preparedWorld.root)
+    disposeSceneLightShadows(this.lightRoot)
+    this.lightRoot.clear()
+    this.keyLight = undefined
+    this.practicalLights.length = 0
+    this.practicalLightRefreshElapsed = 0
+    this.shadowFocusInitialized = false
+    this.shadowRefreshElapsed = Number.POSITIVE_INFINITY
+    this.dynamicShadowBudgetApplied = false
+    this.adaptiveDynamicShadowRefreshRate = mobile ? 30 : 60
+    this.dynamicShadowRefreshRate = Math.min(
+      this.adaptiveDynamicShadowRefreshRate,
+      this.visualQualityPolicy.shadowRefreshRate,
+    )
+    this.lightingRig = resolveSceneLightingRig(theme, mobile)
+    this.configureLights(theme, this.lightingRig, mobile)
+    this.setKeyShadowMapSize(this.desiredShadowMapSize(false))
+
+    this.scene.background = panorama ?? new THREE.Color(theme.environment.background)
+    this.scene.environment = panorama ?? null
+    this.scene.environmentIntensity = this.lightingRig.environmentIntensity
+    this.scene.fog = new THREE.Fog(
+      theme.environment.fog,
+      theme.environment.fogNear,
+      Math.max(theme.environment.fogFar, 480),
+    )
+    configureSceneRenderer(this.renderer, this.lightingRig.exposure)
+    this.renderer.shadowMap.enabled = this.visualQualityPolicy.tier !== 'low'
+    this.activeTheme = theme
+    this.ambience.applyTheme(theme)
+    this.container.dataset.themeId = theme.id
+    delete this.container.dataset.themeError
+  }
+
+  private configureLights(theme: TrackThemeDefinition, rig: SceneLightingRig, mobile: boolean): void {
+    const hemisphere = new THREE.HemisphereLight(
+      rig.hemisphere.skyColor,
+      rig.hemisphere.groundColor,
+      rig.hemisphere.intensity,
+    )
+    hemisphere.name = 'theme-hemisphere'
+
+    const key = new THREE.DirectionalLight(rig.key.color, rig.key.intensity)
+    key.name = 'theme-key'
+    key.position.set(...rig.key.position)
+    this.keyOffset.copy(key.position)
+    configureKeyShadow(key, rig)
+    key.target.name = 'theme-key-target'
+    this.keyLight = key
+
+    const rim = new THREE.DirectionalLight(rig.rim.color, rig.rim.intensity)
+    rim.name = 'theme-rim'
+    rim.position.set(...rig.rim.position)
+    this.lightRoot.add(hemisphere, key, key.target, rim)
+
+    const practical = theme.lighting.practical
+    if (!practical) return
+    const lightCount = Math.max(1, Math.min(mobile ? 2 : 4, Math.round(practical.count)))
+    for (let index = 0; index < lightCount; index += 1) {
+      const light = new THREE.PointLight(practical.color, practical.intensity, practical.distance, practical.decay)
+      light.name = `theme-practical-${index + 1}`
+      light.castShadow = false
+      this.practicalLights.push(light)
+      this.lightRoot.add(light)
+    }
+    this.refreshPracticalLightPositions(practical)
+  }
+
+  private updateKeyShadowFocus(camera: THREE.Camera, focusTarget?: THREE.Vector3): boolean {
+    if (!this.keyLight) return false
+    computeShadowFocus(camera, this.lightingRig, this.nextShadowFocus, focusTarget, this.keyLight.shadow.mapSize.width)
+    const recenterDistance = this.lightingRig.shadow.extent * 0.18
+    if (
+      this.shadowFocusInitialized &&
+      this.nextShadowFocus.distanceToSquared(this.shadowFocus) < recenterDistance * recenterDistance
+    ) {
+      return false
+    }
+    this.shadowFocus.copy(this.nextShadowFocus)
+    this.shadowFocusInitialized = true
+    this.keyLight.target.position.copy(this.shadowFocus)
+    this.keyLight.position.copy(this.shadowFocus).add(this.keyOffset)
+    this.keyLight.target.updateMatrixWorld()
+    return true
+  }
+
+  private applyDynamicShadowBudget(): void {
+    if (this.dynamicShadowBudgetApplied || !this.keyLight) return
+    this.dynamicShadowBudgetApplied = true
+    const shadow = this.keyLight.shadow
+    shadow.map?.dispose()
+    shadow.map = null
+    shadow.mapSize.set(this.desiredShadowMapSize(true), this.desiredShadowMapSize(true))
+    this.requestShadowUpdate()
+  }
+
+  private restoreStaticShadowBudget(): void {
+    if (!this.dynamicShadowBudgetApplied || !this.keyLight) return
+    this.dynamicShadowBudgetApplied = false
+    const shadow = this.keyLight.shadow
+    shadow.map?.dispose()
+    shadow.map = null
+    const mapSize = this.desiredShadowMapSize(false)
+    shadow.mapSize.set(mapSize, mapSize)
+    this.requestShadowUpdate()
+  }
+
+  private applyParticleBudget(): void {
+    this.world?.root.traverse(object => {
+      if (!(object instanceof THREE.Points)) return
+      const count = object.geometry.getAttribute('position')?.count ?? 0
+      object.geometry.setDrawRange(0, Math.max(0, Math.round(count * this.visualQualityPolicy.particleScale)))
+    })
+  }
+
+  private desiredShadowMapSize(dynamic: boolean): number {
+    if (dynamic) return this.visualQualityPolicy.shadowMapSize
+    return this.visualQualityPolicy.tier === 'performance'
+      ? Math.min(this.lightingRig.shadow.mapSize, this.visualQualityPolicy.shadowMapSize)
+      : this.lightingRig.shadow.mapSize
+  }
+
+  private setKeyShadowMapSize(mapSize: number): void {
+    if (!this.keyLight) return
+    const shadow = this.keyLight.shadow
+    if (shadow.mapSize.width === mapSize && shadow.mapSize.height === mapSize) return
+    shadow.map?.dispose()
+    shadow.map = null
+    shadow.mapSize.set(mapSize, mapSize)
+    this.requestShadowUpdate()
+  }
+
+  private refreshPracticalLightPositions(
+    practical: TrackThemeDefinition['lighting']['practical'] = this.activeTheme.lighting.practical,
+  ): void {
+    if (!practical || this.practicalLights.length === 0) return
+    const positions = distributePracticalLightPositions(
+      this.collectTrackLightCandidates(),
+      this.practicalLights.length,
+      practical.heightOffset,
+    )
+    for (const [index, light] of this.practicalLights.entries()) {
+      light.position.copy(positions[index] ?? new THREE.Vector3(0, practical.heightOffset, 0))
+    }
+  }
+
+  private collectTrackLightCandidates(): THREE.Vector3[] {
+    const pieceBounds = new Map<string, THREE.Box3>()
+    const ungroupedBounds: THREE.Box3[] = []
+
+    for (const root of this.scene.children) {
+      if (root === this.lightRoot || root === this.world?.root) continue
+      root.updateWorldMatrix(true, true)
+      root.traverseVisible(object => {
+        if (!(object instanceof THREE.Mesh) || !hasPracticalFloorMaterial(object.material)) return
+        const geometryBounds = object.geometry.boundingBox
+        if (!geometryBounds) object.geometry.computeBoundingBox()
+        if (!object.geometry.boundingBox) return
+        const worldBounds = object.geometry.boundingBox.clone().applyMatrix4(object.matrixWorld)
+        const pieceId = object.userData.pieceInstanceId
+        if (typeof pieceId === 'string') {
+          const bounds = pieceBounds.get(pieceId)
+          if (bounds) bounds.union(worldBounds)
+          else pieceBounds.set(pieceId, worldBounds)
+        } else {
+          ungroupedBounds.push(worldBounds)
+        }
+      })
+    }
+
+    return [...pieceBounds.values(), ...ungroupedBounds].map(bounds => bounds.getCenter(new THREE.Vector3()))
+  }
+
+  private assertActive(): void {
+    if (this.disposed) throw new Error('SceneThemeController has been disposed.')
+  }
+}
+
+function hasPracticalFloorMaterial(material: THREE.Material | THREE.Material[]): boolean {
+  const materials = Array.isArray(material) ? material : [material]
+  return materials.some(
+    candidate =>
+      candidate instanceof THREE.MeshStandardMaterial &&
+      candidate.emissiveMap instanceof THREE.Texture &&
+      candidate.emissiveIntensity > 0,
+  )
+}
+
+export function distributePracticalLightPositions(
+  candidates: readonly THREE.Vector3[],
+  count: number,
+  heightOffset: number,
+): THREE.Vector3[] {
+  const safeCount = Math.max(0, Math.round(count))
+  if (safeCount === 0) return []
+  if (candidates.length === 0) {
+    return Array.from({ length: safeCount }, (_, index) => {
+      const angle = (index / safeCount) * Math.PI * 2 + Math.PI / 4
+      return new THREE.Vector3(Math.cos(angle) * 5, heightOffset, Math.sin(angle) * 5)
+    })
+  }
+
+  const bounds = new THREE.Box3().setFromPoints([...candidates])
+  const size = bounds.getSize(new THREE.Vector3())
+  const layouts: readonly (readonly [number, number])[][] = [
+    [[0.5, 0.5]],
+    [
+      [0.25, 0.3],
+      [0.75, 0.7],
+    ],
+    [
+      [0.2, 0.25],
+      [0.8, 0.3],
+      [0.5, 0.78],
+    ],
+    [
+      [0.2, 0.22],
+      [0.78, 0.28],
+      [0.28, 0.76],
+      [0.82, 0.8],
+    ],
+  ]
+  const layout = layouts[Math.min(safeCount, layouts.length) - 1]!
+  const available = candidates.map(candidate => candidate.clone())
+  const positions: THREE.Vector3[] = []
+
+  for (let index = 0; index < safeCount; index += 1) {
+    const normalized = layout[index % layout.length]!
+    const targetX = bounds.min.x + size.x * normalized[0]
+    const targetZ = bounds.min.z + size.z * normalized[1]
+    let nearestIndex = 0
+    let nearestDistance = Number.POSITIVE_INFINITY
+    for (const [candidateIndex, candidate] of available.entries()) {
+      const distance = Math.hypot(candidate.x - targetX, candidate.z - targetZ)
+      if (distance < nearestDistance) {
+        nearestIndex = candidateIndex
+        nearestDistance = distance
+      }
+    }
+    const candidate = available.splice(nearestIndex, 1)[0] ?? candidates[index % candidates.length]!.clone()
+    positions.push(candidate.add(new THREE.Vector3(0, heightOffset, 0)))
+  }
+
+  return positions
+}

package/src/three/shadow-shader-preparation.ts

@@ -0,0 +1,162 @@
+import * as THREE from 'three'
+
+type ShadowMaterial = THREE.MeshDepthMaterial | THREE.MeshDistanceMaterial
+type Caster = THREE.Mesh<THREE.BufferGeometry, THREE.Material | THREE.Material[]>
+
+/** Shader-only preparation; never draws a scene or copies/uploads track geometry. */
+export class ShadowShaderPreparation {
+  private retained = new Set<ShadowMaterial>()
+  private generation = 0
+  private disposed = false
+
+  async prepare(
+    renderer: THREE.WebGLRenderer,
+    root: THREE.Object3D,
+    camera: THREE.Camera,
+    scene: THREE.Scene,
+    yieldWork: () => Promise<void> = () => new Promise(resolve => setTimeout(resolve, 0)),
+  ): Promise<void> {
+    if (this.disposed) return
+    const generation = ++this.generation
+    if (!renderer.shadowMap.enabled) {
+      this.releaseRetained()
+      return
+    }
+    const lighting = new THREE.Scene()
+    let directional = false
+    let point = false
+    // Shadow draws use the current light configuration, but no scene fog or
+    // environment. Copies keep the actual light hierarchy entirely untouched.
+    const lights = new Set<THREE.Light>()
+    const collectLight = (object: THREE.Object3D): void => {
+      if (!(object instanceof THREE.Light) || !object.layers.test(camera.layers)) return
+      if (lights.has(object)) return
+      lights.add(object)
+      lighting.add(object.clone(false))
+      if (object.castShadow) {
+        if (object instanceof THREE.PointLight) point = true
+        else directional = true
+      }
+    }
+    scene.traverseVisible(collectLight)
+    // A loading cover can hide the prepared track root. Its visible children
+    // will contribute lights when the track is revealed; compile that state.
+    collectLight(root)
+    root.children.forEach(child => child.traverseVisible(collectLight))
+    if (!directional && !point) {
+      this.releaseRetained()
+      return
+    }
+
+    const retained = new Set<ShadowMaterial>()
+    const depthCache = new Map<THREE.Material, ShadowMaterial>()
+    const distanceCache = new Map<THREE.Material, ShadowMaterial>()
+    const proxies: THREE.Object3D[] = []
+    scene.traverse(object => {
+      if (!(object instanceof THREE.Mesh) || !object.castShadow) return
+      const caster = object as Caster
+      for (const distance of point ? (directional ? [false, true] : [true]) : [false]) {
+        const cache = distance ? distanceCache : depthCache
+        const custom = distance ? caster.customDistanceMaterial : caster.customDepthMaterial
+        const materials = (Array.isArray(caster.material) ? caster.material : [caster.material]).map(source => {
+          // Custom shadow shaders are object-specific; ordinary casters can
+          // share one preparation material for each source material.
+          let material = custom ? undefined : cache.get(source)
+          if (!material) {
+            material = custom
+              ? (custom.clone() as ShadowMaterial)
+              : distance
+                ? new THREE.MeshDistanceMaterial()
+                : new THREE.MeshDepthMaterial()
+            if (custom) {
+              material.onBeforeCompile = custom.onBeforeCompile
+              material.customProgramCacheKey = custom.customProgramCacheKey
+            }
+            configureShadowMaterial(material, source, renderer.shadowMap.type)
+            retained.add(material)
+            if (!custom) cache.set(source, material)
+          }
+          return material
+        })
+        // A read-only view preserves Three's instancing, batching, morph and
+        // skinning flags without cloning their buffers or reparenting objects.
+        const proxy = Object.create(caster) as Caster
+        proxy.material = Array.isArray(caster.material) ? materials : materials[0]!
+        proxy.children = []
+        proxies.push(proxy)
+      }
+    })
+
+    // compileAsync derives the output colour space from the active target.
+    // A single temporary pixel matches a shadow pass without allocating a
+    // shadow-sized buffer, uploading geometry, or rendering hidden views.
+    const target = new THREE.WebGLRenderTarget(1, 1, { depthBuffer: false })
+    let committed = false
+    try {
+      for (let offset = 0; offset < proxies.length; offset += 128) {
+        if (this.disposed || generation !== this.generation) return
+        const batch = new THREE.Group()
+        batch.children = proxies.slice(offset, offset + 128)
+        const previous = renderer.getRenderTarget()
+        const face = renderer.getActiveCubeFace()
+        const mip = renderer.getActiveMipmapLevel()
+        let pending: Promise<THREE.Object3D>
+        try {
+          renderer.setRenderTarget(target)
+          pending = renderer.compileAsync(batch, camera, lighting)
+        } finally {
+          // Restore synchronously: the shared lobby may render while shader
+          // completion is awaited. Never leave it pointed at the scratch pixel.
+          renderer.setRenderTarget(previous, face, mip)
+        }
+        await pending
+        if (offset + 128 < proxies.length) await yieldWork()
+      }
+      if (this.disposed || generation !== this.generation) return
+      // Hold program references until replacement/disposal; disposing them at
+      // the end of preparation would evict shaders not yet used by a shadow.
+      this.retained.forEach(material => material.dispose())
+      this.retained = retained
+      committed = true
+    } finally {
+      target.dispose()
+      if (!committed) retained.forEach(material => material.dispose())
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true
+    this.generation++
+    this.releaseRetained()
+  }
+
+  private releaseRetained(): void {
+    this.retained.forEach(material => material.dispose())
+    this.retained.clear()
+  }
+}
+
+function configureShadowMaterial(target: ShadowMaterial, source: THREE.Material, type: THREE.ShadowMapType): void {
+  // Mirrors WebGLShadowMap.getDepthMaterial in pinned Three 0.185.1. Keep
+  // alpha/displacement/clipping and side variants identical to real shadows.
+  const material = source as THREE.MeshStandardMaterial
+  target.side =
+    source.shadowSide ??
+    (type === THREE.VSMShadowMap
+      ? source.side
+      : source.side === THREE.FrontSide
+        ? THREE.BackSide
+        : source.side === THREE.BackSide
+          ? THREE.FrontSide
+          : THREE.DoubleSide)
+  target.map = material.map ?? null
+  target.alphaMap = material.alphaMap ?? null
+  target.alphaTest = source.alphaToCoverage ? 0.5 : source.alphaTest
+  target.displacementMap = material.displacementMap ?? null
+  target.displacementScale = material.displacementScale ?? 1
+  target.displacementBias = material.displacementBias ?? 0
+  target.clippingPlanes = source.clippingPlanes
+  target.clipShadows = source.clipShadows
+  target.clipIntersection = source.clipIntersection
+  if (target instanceof THREE.MeshDepthMaterial) target.wireframe = material.wireframe ?? false
+}