@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/track-shadow-batching.ts

@@ -0,0 +1,760 @@
+import * as THREE from 'three'
+import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+
+import { STATIC_SHADOW_PROXY_LAYER } from '../../../three/scene-lighting'
+import { StaticTrackBatchedMesh } from '../../../three/static-track-batched-mesh'
+import { preserveGeometryAttributeAliases } from '../../../three/geometry-attribute-aliases'
+import { batchTrackConnectorMarkers } from '../../../three/track-connector-batch'
+
+const DYNAMIC_SHADOW_ROOT = 'trackDynamicShadowRoot'
+const STATIC_COLOR_BATCH_SOURCE = 'trackStaticColorBatchSource'
+
+interface StaticColorBatchSource {
+  geometry: THREE.BufferGeometry
+  material: THREE.Material
+  matrix: THREE.Matrix4
+  mesh: THREE.Mesh
+}
+
+interface StaticColorBatchBinding {
+  batch: THREE.BatchedMesh
+  instanceId: number
+  source: StaticColorBatchSource
+}
+
+export interface StaticTrackColorBatch {
+  allocatedGeometryBytes: number
+  connectorBatchCount: number
+  connectorSourceCount: number
+  updateConnectorVisibility(): void
+  batchCount: number
+  candidateCount: number
+  rejectionCounts: Readonly<Record<string, number>>
+  releasedSourceGeometryBytes: number
+  releasedSourceGeometryCount: number
+  sourceCount: number
+  detachSources(sourceRoots: readonly THREE.Object3D[]): number
+  releaseSourceGeometryCpuData(): { bytes: number; geometries: number }
+  updateTransforms(): void
+  dispose(): void
+}
+
+interface ShadowGeometrySource {
+  mesh: THREE.Mesh
+  matrix: THREE.Matrix4
+  position: THREE.BufferAttribute | THREE.InterleavedBufferAttribute
+  index?: THREE.BufferAttribute
+  start: number
+  count: number
+  side: THREE.Side
+}
+
+/** Marks a piece subtree whose transforms change while the simulation runs. */
+export function markDynamicTrackShadowRoot(root: THREE.Object3D): void {
+  root.userData[DYNAMIC_SHADOW_ROOT] = true
+}
+
+/** Keeps race shadow maps limited to static track and environment geometry. */
+export function disableDynamicTrackShadowCasters(root: THREE.Object3D): void {
+  root.traverse(object => {
+    if (object instanceof THREE.Mesh && hasDynamicShadowAncestor(object, root)) object.castShadow = false
+  })
+}
+
+/**
+ * Consolidates compatible opaque meshes from several immutable Track Lab
+ * pieces without flattening their culling bounds into one map-sized mesh.
+ * `BatchedMesh` retains per-object frustum culling while issuing one draw per
+ * compatible material/attribute group. The original meshes stay in the scene
+ * graph (hidden from rendering) so editor ray-picking, bounds, theme bindings,
+ * and piece-local disposal keep their existing ownership.
+ *
+ * Run this after static shadow proxies have been built: the color batches do
+ * not cast shadows because the exact three-side shadow streams already do so
+ * with fewer submissions.
+ */
+export function batchStaticTrackColorMeshes(
+  root: THREE.Group,
+  sourceRoots: readonly THREE.Object3D[],
+  options: { multiDrawSupported?: boolean; maxAdditionalGeometryBytes?: number } = {},
+): StaticTrackColorBatch {
+  root.updateWorldMatrix(true, true)
+  const rootInverse = root.matrixWorld.clone().invert()
+  const updatedMatrix = new THREE.Matrix4()
+  const sources: StaticColorBatchSource[] = []
+  const rejectionCounts: Record<string, number> = {}
+  const geometryConsumers = collectGeometryConsumers(root)
+  const connectors = batchTrackConnectorMarkers(root, sourceRoots)
+  for (const sourceRoot of sourceRoots) {
+    sourceRoot.traverse(object => {
+      if (!(object instanceof THREE.Mesh)) return
+      const rejection = staticColorBatchRejectionReason(object, sourceRoot)
+      if (rejection) {
+        rejectionCounts[rejection] = (rejectionCounts[rejection] ?? 0) + 1
+        return
+      }
+      sources.push({
+        geometry: object.geometry,
+        material: object.material,
+        matrix: rootInverse.clone().multiply(object.matrixWorld),
+        mesh: object,
+      })
+    })
+  }
+
+  const groups = new Map<string, StaticColorBatchSource[]>()
+  for (const source of sources) {
+    const key = [
+      source.material.uuid,
+      geometryAttributeSignature(source.geometry),
+      source.geometry.index ? 'indexed' : 'non-indexed',
+      source.mesh.receiveShadow ? 1 : 0,
+      source.mesh.layers.mask,
+      source.mesh.renderOrder,
+    ].join('|')
+    const group = groups.get(key) ?? []
+    group.push(source)
+    groups.set(key, group)
+  }
+
+  const batches: THREE.BatchedMesh[] = []
+  const bindings: StaticColorBatchBinding[] = []
+  const hiddenSources = new Map<THREE.Mesh, boolean>()
+  const sourceRanges = new Map<THREE.BufferGeometry, { batch: THREE.BatchedMesh; geometryId: number }>()
+  let batchIndex = 0
+  let batchedSourceCount = 0
+  let allocatedGeometryBytes = 0
+  for (const group of groups.values()) {
+    // Without WEBGL_multi_draw, Three submits one ordinary draw per instance
+    // anyway, plus a DrawID uniform update and batch texture lookups. Keep the
+    // original geometry instead of paying for a course-sized duplicate buffer.
+    if (options.multiDrawSupported === false || group.length < 2) continue
+    const uniqueGeometries = [...new Set(group.map(source => source.geometry))]
+    const maxVertexCount = uniqueGeometries.reduce(
+      (sum, geometry) => sum + (geometry.getAttribute('position')?.count ?? 0),
+      0,
+    )
+    const maxIndexCount = uniqueGeometries.reduce((sum, geometry) => sum + (geometry.index?.count ?? 0), 0)
+    if (maxVertexCount === 0) continue
+    const first = group[0]!
+    const vertexStride = Object.values(first.geometry.attributes).reduce(
+      (sum, attribute) => sum + attribute.itemSize * attribute.array.BYTES_PER_ELEMENT,
+      0,
+    )
+    const allocationBytes = maxVertexCount * vertexStride + maxIndexCount * (maxVertexCount > 65535 ? 4 : 2)
+    // Include Three's initial duplicate channels and index widening in the
+    // staging budget, even when attribute aliases are restored afterward.
+    if (allocatedGeometryBytes + allocationBytes > (options.maxAdditionalGeometryBytes ?? Infinity)) continue
+    allocatedGeometryBytes += allocationBytes
+    const batch = new StaticTrackBatchedMesh(group.length, maxVertexCount, maxIndexCount, first.material)
+    batch.name = `track-static-color-batch-${batchIndex++}`
+    batch.castShadow = false
+    batch.receiveShadow = first.mesh.receiveShadow
+    batch.layers.mask = first.mesh.layers.mask
+    batch.renderOrder = first.mesh.renderOrder
+    batch.perObjectFrustumCulled = true
+    batch.sortObjects = true
+    batch.userData.trackStaticColorBatch = true
+    batch.userData.decorative = true
+    batch.userData.visualOnly = true
+    batch.userData.excludeFromEditorBounds = true
+    batch.userData.materialSlot = first.mesh.userData.materialSlot
+    const geometryIds = new Map<THREE.BufferGeometry, number>()
+    for (const source of group) {
+      let geometryId = geometryIds.get(source.geometry)
+      if (geometryId === undefined) {
+        geometryId = batch.addGeometry(source.geometry)
+        geometryIds.set(source.geometry, geometryId)
+        sourceRanges.set(source.geometry, { batch, geometryId })
+      }
+      const instanceId = batch.addInstance(geometryId)
+      batch.setMatrixAt(instanceId, source.matrix)
+      bindings.push({ batch, instanceId, source })
+      if (!hiddenSources.has(source.mesh)) hiddenSources.set(source.mesh, source.mesh.visible)
+      source.mesh.userData[STATIC_COLOR_BATCH_SOURCE] = true
+      source.mesh.visible = false
+      batchedSourceCount += 1
+    }
+    preserveGeometryAttributeAliases(batch.geometry, uniqueGeometries)
+    batch.computeBoundingBox()
+    batch.computeBoundingSphere()
+    root.add(batch)
+    batches.push(batch)
+  }
+
+  // BatchedMesh copies each source geometry into its own combined buffers.
+  // Keep hidden source meshes and exact CPU views for Lab picking, bounds,
+  // and later edits, but release redundant WebGL buffers once
+  // every renderer consumer of a geometry is represented by a color batch.
+  // BufferGeometry.dispose() does not delete its attributes; Three can upload
+  // them again if dispose() below restores the source meshes for a rebuild.
+  let releasedSourceGeometryBytes = 0
+  let releasedSourceGeometryCount = 0
+  const releasableSourceGeometries = new Set<THREE.BufferGeometry>()
+  for (const [geometry, consumers] of geometryConsumers) {
+    if (consumers.size === 0 || [...consumers].some(mesh => !hiddenSources.has(mesh))) continue
+    releasedSourceGeometryBytes += bufferGeometryByteLength(geometry)
+    releasedSourceGeometryCount += 1
+    releasableSourceGeometries.add(geometry)
+    geometry.dispose()
+    const range = sourceRanges.get(geometry)
+    if (range) shareStaticSourceAttributes(geometry, range.batch, range.geometryId)
+  }
+
+  return {
+    allocatedGeometryBytes,
+    connectorBatchCount: connectors.batchCount,
+    connectorSourceCount: connectors.sourceCount,
+    updateConnectorVisibility: connectors.updateTransforms,
+    batchCount: batches.length,
+    candidateCount: sources.length,
+    rejectionCounts,
+    releasedSourceGeometryBytes,
+    releasedSourceGeometryCount,
+    sourceCount: batchedSourceCount,
+    detachSources(sourceRoots) {
+      connectors.detachSources(sourceRoots)
+      const detachedMeshes = new Set<THREE.Mesh>()
+      for (const sourceRoot of sourceRoots) {
+        sourceRoot.traverse(object => {
+          if (object instanceof THREE.Mesh) detachedMeshes.add(object)
+        })
+      }
+      if (detachedMeshes.size === 0) return 0
+
+      let detachedCount = 0
+      let writeIndex = 0
+      for (const binding of bindings) {
+        const mesh = binding.source.mesh
+        if (!detachedMeshes.has(mesh)) {
+          bindings[writeIndex++] = binding
+          continue
+        }
+        releasableSourceGeometries.delete(binding.source.geometry)
+        binding.batch.deleteInstance(binding.instanceId)
+        if (hiddenSources.has(mesh)) {
+          mesh.visible = hiddenSources.get(mesh)!
+          hiddenSources.delete(mesh)
+        }
+        delete mesh.userData[STATIC_COLOR_BATCH_SOURCE]
+        detachedCount += 1
+      }
+      bindings.length = writeIndex
+      return detachedCount
+    },
+    releaseSourceGeometryCpuData() {
+      let bytes = 0
+      let geometries = 0
+      for (const geometry of releasableSourceGeometries) {
+        const byteLength = bufferGeometryByteLength(geometry)
+        if (byteLength === 0) continue
+        // Attribute views already share the live batch allocation. Only the
+        // source-local index (or an unshared attribute) is released here.
+        const batchGeometry = sourceRanges.get(geometry)?.batch.geometry
+        const privateArrays = new Set<ArrayBufferLike>()
+        if (geometry.index) privateArrays.add(geometry.index.array.buffer)
+        for (const [name, attribute] of Object.entries(geometry.attributes)) {
+          if (attribute.array.buffer !== batchGeometry?.getAttribute(name)?.array.buffer) {
+            privateArrays.add(attribute.array.buffer)
+          }
+        }
+        bytes += [...privateArrays].reduce((sum, array) => sum + array.byteLength, 0)
+        geometries += 1
+        geometry.setIndex(null)
+        for (const name of Object.keys(geometry.attributes)) geometry.deleteAttribute(name)
+        geometry.morphAttributes = {}
+        geometry.clearGroups()
+        geometry.boundingBox = null
+        geometry.boundingSphere = null
+      }
+      releasableSourceGeometries.clear()
+      return { bytes, geometries }
+    },
+    updateTransforms() {
+      connectors.updateTransforms()
+      root.updateWorldMatrix(true, true)
+      rootInverse.copy(root.matrixWorld).invert()
+      for (const { batch, instanceId, source } of bindings) {
+        updatedMatrix.copy(rootInverse).multiply(source.mesh.matrixWorld)
+        batch.setMatrixAt(instanceId, updatedMatrix)
+      }
+      for (const batch of batches) {
+        batch.computeBoundingBox()
+        batch.computeBoundingSphere()
+      }
+    },
+    dispose() {
+      connectors.dispose()
+      for (const [mesh, visible] of hiddenSources) {
+        mesh.visible = visible
+        delete mesh.userData[STATIC_COLOR_BATCH_SOURCE]
+      }
+      for (const batch of batches) {
+        batch.removeFromParent()
+        batch.dispose()
+      }
+      hiddenSources.clear()
+      releasableSourceGeometries.clear()
+      bindings.length = 0
+      batches.length = 0
+    },
+  }
+}
+
+function collectGeometryConsumers(root: THREE.Object3D): Map<THREE.BufferGeometry, Set<THREE.Mesh>> {
+  const consumers = new Map<THREE.BufferGeometry, Set<THREE.Mesh>>()
+  root.traverse(object => {
+    if (!(object instanceof THREE.Mesh) || object instanceof THREE.BatchedMesh) return
+    const geometryConsumers = consumers.get(object.geometry) ?? new Set<THREE.Mesh>()
+    geometryConsumers.add(object)
+    consumers.set(object.geometry, geometryConsumers)
+  })
+  return consumers
+}
+
+function bufferGeometryByteLength(geometry: THREE.BufferGeometry): number {
+  const arrays = new Set<ArrayBufferLike>()
+  const collectAttribute = (attribute: THREE.BufferAttribute | THREE.InterleavedBufferAttribute): void => {
+    arrays.add(
+      attribute instanceof THREE.InterleavedBufferAttribute ? attribute.data.array.buffer : attribute.array.buffer,
+    )
+  }
+  if (geometry.index) collectAttribute(geometry.index)
+  for (const attribute of Object.values(geometry.attributes)) collectAttribute(attribute)
+  for (const attributes of Object.values(geometry.morphAttributes)) {
+    for (const attribute of attributes) collectAttribute(attribute)
+  }
+  let byteLength = 0
+  for (const array of arrays) byteLength += array.byteLength
+  return byteLength
+}
+
+/** Editor picking deliberately keeps hidden batch sources raycastable. */
+export function isStaticTrackColorBatchSource(object: THREE.Object3D): boolean {
+  return object.userData[STATIC_COLOR_BATCH_SOURCE] === true
+}
+
+/**
+ * Combines nearby opaque, static track meshes into exact shadow-only
+ * triangle streams (front/back/double sided). Visible meshes and materials are
+ * untouched; only their redundant per-object shadow submissions are replaced.
+ */
+export function batchStaticTrackShadowCasters(root: THREE.Group): number {
+  const sources = collectStaticShadowSources(root)
+  buildStaticShadowProxies(root, sources)
+  return sources.length
+}
+
+/**
+ * Builds the same exact shadow proxies as `batchStaticTrackShadowCasters`, but
+ * yields between large vertex streams. Lab Test Run uses this path so a large
+ * course cannot monopolise the browser main thread while its runtime copy is
+ * prepared.
+ */
+export async function batchStaticTrackShadowCastersAsync(root: THREE.Group, sliceMilliseconds = 4): Promise<number> {
+  const sources = collectStaticShadowSources(root)
+  await buildStaticShadowProxiesAsync(root, sources, sliceMilliseconds)
+  return sources.length
+}
+
+function collectStaticShadowSources(root: THREE.Group): ShadowGeometrySource[] {
+  root.updateWorldMatrix(true, true)
+  const rootInverse = root.matrixWorld.clone().invert()
+  const sources: ShadowGeometrySource[] = []
+  root.traverse(object => {
+    if (
+      !(object instanceof THREE.Mesh) ||
+      object instanceof THREE.InstancedMesh ||
+      object instanceof THREE.SkinnedMesh ||
+      object.userData.trackStaticShadowProxy
+    ) {
+      return
+    }
+    if (!object.castShadow || !visibleThroughRoot(object, root) || hasDynamicShadowAncestor(object, root)) return
+    const materials = Array.isArray(object.material) ? object.material : [object.material]
+    if (materials.length === 0 || materials.some(material => !canBatchShadowMaterial(material))) return
+    const sides = new Set(materials.map(material => material.shadowSide ?? material.side))
+    if (sides.size !== 1) return
+    const position = object.geometry.getAttribute('position')
+    if (!position || position.itemSize < 3 || object.geometry.morphAttributes.position?.length) return
+    const index = object.geometry.index ?? undefined
+    const availableCount = index?.count ?? position.count
+    const start = Math.max(0, Math.floor(object.geometry.drawRange.start))
+    const requestedCount = object.geometry.drawRange.count
+    const count = Math.max(
+      0,
+      Math.min(availableCount - start, Number.isFinite(requestedCount) ? Math.floor(requestedCount) : availableCount),
+    )
+    const triangleCount = count - (count % 3)
+    if (triangleCount === 0) return
+    sources.push({
+      mesh: object,
+      matrix: rootInverse.clone().multiply(object.matrixWorld),
+      position,
+      ...(index ? { index } : {}),
+      start,
+      count: triangleCount,
+      side: [...sides][0]!,
+    })
+  })
+  return sources
+}
+
+function spatialShadowGroups(sources: readonly ShadowGeometrySource[]): ShadowGeometrySource[][] {
+  // A course-wide merged bound defeats the shadow camera's frustum culling:
+  // touching one end submits every triangle. Keep nearby sources together,
+  // including vertically stacked tracks, without clipping or duplicating them.
+  // Bounds still enclose the entire source, including pieces crossing cells.
+  const cellSize = 32
+  const groups = new Map<string, ShadowGeometrySource[]>()
+  const bounds = new THREE.Box3()
+  const center = new THREE.Vector3()
+  for (const source of sources) {
+    if (!source.mesh.geometry.boundingBox) source.mesh.geometry.computeBoundingBox()
+    bounds.copy(source.mesh.geometry.boundingBox!).applyMatrix4(source.matrix).getCenter(center)
+    const key = `${source.side}:${source.mesh.layers.mask}:${Math.round(center.x / cellSize)}:${Math.round(center.y / cellSize)}:${Math.round(center.z / cellSize)}`
+    const group = groups.get(key) ?? []
+    group.push(source)
+    groups.set(key, group)
+  }
+  return [...groups.values()]
+}
+
+function buildStaticShadowProxies(root: THREE.Group, sources: readonly ShadowGeometrySource[]): void {
+  for (const sideSources of spatialShadowGroups(sources)) {
+    const { positions, indices } = createShadowProxyArrays(sideSources)
+    addStaticShadowProxy(root, sideSources[0]!.side, positions, indices, sideSources[0]!.mesh.layers.mask)
+  }
+}
+
+async function buildStaticShadowProxiesAsync(
+  root: THREE.Group,
+  sources: readonly ShadowGeometrySource[],
+  sliceMilliseconds: number,
+): Promise<void> {
+  let sliceStartedAt = performance.now()
+  const yieldIfNeeded = async (): Promise<void> => {
+    if (performance.now() - sliceStartedAt < sliceMilliseconds) return
+    await new Promise<void>(resolve => requestAnimationFrame(() => resolve()))
+    sliceStartedAt = performance.now()
+  }
+  for (const sideSources of spatialShadowGroups(sources)) {
+    const vertexCount = sideSources.reduce((sum, source) => sum + source.position.count, 0)
+    const positions = new Float32Array(vertexCount * 3)
+    const indices = new Uint32Array(sideSources.reduce((sum, source) => sum + source.count, 0))
+    const vertex = new THREE.Vector3()
+    let vertexOffset = 0
+    let indexOffset = 0
+    for (const source of sideSources) {
+      for (let sourceVertex = 0; sourceVertex < source.position.count; sourceVertex += 1) {
+        vertex.fromBufferAttribute(source.position, sourceVertex).applyMatrix4(source.matrix)
+        const writeOffset = (vertexOffset + sourceVertex) * 3
+        positions[writeOffset] = vertex.x
+        positions[writeOffset + 1] = vertex.y
+        positions[writeOffset + 2] = vertex.z
+        if ((sourceVertex & 1_023) === 1_023) await yieldIfNeeded()
+      }
+      for (let offset = source.start; offset < source.start + source.count; offset += 1) {
+        indices[indexOffset++] = vertexOffset + (source.index?.getX(offset) ?? offset)
+      }
+      vertexOffset += source.position.count
+      source.mesh.castShadow = false
+      await yieldIfNeeded()
+    }
+    addStaticShadowProxy(root, sideSources[0]!.side, positions, indices, sideSources[0]!.mesh.layers.mask)
+    await yieldIfNeeded()
+  }
+}
+
+function createShadowProxyArrays(sideSources: readonly ShadowGeometrySource[]): {
+  positions: Float32Array
+  indices: Uint32Array
+} {
+  const vertexCount = sideSources.reduce((sum, source) => sum + source.position.count, 0)
+  const positions = new Float32Array(vertexCount * 3)
+  const indices = new Uint32Array(sideSources.reduce((sum, source) => sum + source.count, 0))
+  const vertex = new THREE.Vector3()
+  let vertexOffset = 0
+  let indexOffset = 0
+  for (const source of sideSources) {
+    for (let sourceVertex = 0; sourceVertex < source.position.count; sourceVertex += 1) {
+      vertex.fromBufferAttribute(source.position, sourceVertex).applyMatrix4(source.matrix)
+      const writeOffset = (vertexOffset + sourceVertex) * 3
+      positions[writeOffset] = vertex.x
+      positions[writeOffset + 1] = vertex.y
+      positions[writeOffset + 2] = vertex.z
+    }
+    for (let offset = source.start; offset < source.start + source.count; offset += 1) {
+      indices[indexOffset++] = vertexOffset + (source.index?.getX(offset) ?? offset)
+    }
+    vertexOffset += source.position.count
+    source.mesh.castShadow = false
+  }
+  return { positions, indices }
+}
+
+function addStaticShadowProxy(
+  root: THREE.Group,
+  side: THREE.Side,
+  positions: Float32Array,
+  indices: Uint32Array,
+  layersMask: number,
+): void {
+  const geometry = new THREE.BufferGeometry()
+  geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3))
+  geometry.setIndex(new THREE.BufferAttribute(indices, 1))
+  geometry.computeBoundingBox()
+  geometry.computeBoundingSphere()
+  // WebGLShadowMap filters casters against the viewing camera's layers, not
+  // the shadow camera's layers. Keep proxies on the source layer, but make
+  // their ordinary pass write neither color nor depth. Three's shadow pass
+  // uses its own depth material, so the exact caster remains visible there.
+  const material = new THREE.MeshBasicMaterial({ color: 0xffffff, side, colorWrite: false, depthWrite: false })
+  material.name = 'track-static-shadow-proxy-material'
+  material.userData.ownsMaterial = true
+  const proxy = new THREE.Mesh(geometry, material)
+  proxy.name = `track-static-shadow-proxy-${side}`
+  proxy.layers.mask = layersMask
+  proxy.layers.enable(STATIC_SHADOW_PROXY_LAYER)
+  proxy.castShadow = true
+  proxy.receiveShadow = false
+  proxy.userData.trackStaticShadowProxy = true
+  proxy.userData.excludeFromEditorBounds = true
+  proxy.userData.decorative = true
+  root.add(proxy)
+}
+
+function canBatchShadowMaterial(material: THREE.Material): boolean {
+  if (!material.visible || material.transparent || material.opacity < 1 || material.alphaTest > 0) return false
+  if ('alphaMap' in material && material.alphaMap) return false
+  if (material instanceof THREE.MeshStandardMaterial && material.displacementMap && material.displacementScale !== 0) {
+    return false
+  }
+  return true
+}
+
+/**
+ * Keep exact source-local data for editor picking without retaining a second
+ * course-sized set of CPU arrays. Batch positions are copied before instance
+ * transforms, so views into their ranges have the original coordinates.
+ * Indices stay source-local: batch indices include a vertex offset.
+ */
+function shareStaticSourceAttributes(source: THREE.BufferGeometry, batch: THREE.BatchedMesh, geometryId: number): void {
+  const range = batch.getGeometryRangeAt(geometryId)
+  if (!range) return
+  const aliases = new Map<THREE.BufferAttribute, THREE.BufferAttribute>()
+  for (const [name, attribute] of Object.entries(source.attributes)) {
+    const target = batch.geometry.getAttribute(name)
+    if (!(attribute instanceof THREE.BufferAttribute) || !(target instanceof THREE.BufferAttribute)) continue
+    let shared = aliases.get(attribute)
+    if (!shared) {
+      const start = range.vertexStart * attribute.itemSize
+      shared = new THREE.BufferAttribute(
+        target.array.subarray(start, start + attribute.count * attribute.itemSize),
+        attribute.itemSize,
+        attribute.normalized,
+      )
+      shared.name = attribute.name
+      shared.setUsage(attribute.usage)
+      shared.gpuType = attribute.gpuType
+      aliases.set(attribute, shared)
+    }
+    source.setAttribute(name, shared)
+  }
+}
+
+function staticColorBatchRejectionReason(object: THREE.Mesh, sourceRoot: THREE.Object3D): string | undefined {
+  if (
+    object instanceof THREE.BatchedMesh ||
+    object instanceof THREE.InstancedMesh ||
+    object instanceof THREE.SkinnedMesh
+  ) {
+    return 'special-mesh'
+  }
+  if (object.userData.trackStaticColorBatch || object.userData.trackStaticShadowProxy) return 'existing-batch'
+  if (object.userData.isTrackConnectorMarker) return 'connector'
+  if (Array.isArray(object.material)) return 'material-array'
+  if (object.geometry.morphAttributes.position?.length) return 'morph'
+  if (hasDynamicShadowAncestor(object, sourceRoot)) return 'dynamic'
+  if (!visibleThroughRoot(object, sourceRoot)) return 'hidden'
+  const material = object.material
+  const baseTransparent = material.userData.themeBaseTransparent
+  const baseOpacity = material.userData.themeBaseOpacity
+  const inherentlyTransparent = typeof baseTransparent === 'boolean' ? baseTransparent : material.transparent
+  const inherentOpacity = typeof baseOpacity === 'number' ? baseOpacity : material.opacity
+  if (!material.visible || inherentlyTransparent || inherentOpacity < 1 || material.alphaTest > 0) return 'transparent'
+  const position = object.geometry.getAttribute('position')
+  if (!position || position.itemSize < 3) return 'position'
+  const availableCount = object.geometry.index?.count ?? position.count
+  const requestedCount = object.geometry.drawRange.count
+  const drawCount = Number.isFinite(requestedCount) ? Math.floor(requestedCount) : availableCount
+  return object.geometry.drawRange.start === 0 && drawCount >= availableCount ? undefined : 'draw-range'
+}
+
+function visibleThroughRoot(object: THREE.Object3D, root: THREE.Object3D): boolean {
+  for (let current: THREE.Object3D | null = object; current; current = current.parent) {
+    if (!current.visible) return false
+    if (current === root) return true
+  }
+  return false
+}
+
+function hasDynamicShadowAncestor(object: THREE.Object3D, root: THREE.Object3D): boolean {
+  for (let current: THREE.Object3D | null = object; current && current !== root; current = current.parent) {
+    if (current.userData[DYNAMIC_SHADOW_ROOT]) return true
+  }
+  return false
+}
+
+interface OverviewDecorationSource {
+  geometry: THREE.BufferGeometry
+  material: THREE.Material
+  matrix: THREE.Matrix4
+  mesh: THREE.Mesh
+  themeHidden?: readonly string[]
+  themeOnly?: readonly string[]
+  visibilitySignature: string
+}
+
+/**
+ * Merges static decorative color meshes inside one editable Track Lab piece.
+ * Geometry is grouped by material, attributes, render state, and inherited
+ * theme visibility, so a later in-place theme change cannot reveal geometry
+ * from another visual family. Instanced and dynamic details stay independent.
+ */
+export function batchStaticOverviewDecorations(root: THREE.Group): number {
+  root.updateWorldMatrix(true, true)
+  const rootInverse = root.matrixWorld.clone().invert()
+  const sources: OverviewDecorationSource[] = []
+  root.traverse(object => {
+    if (
+      !(object instanceof THREE.Mesh) ||
+      object instanceof THREE.InstancedMesh ||
+      object instanceof THREE.SkinnedMesh ||
+      object.userData.trackStaticOverviewBatch ||
+      object.userData.trackStaticShadowProxy ||
+      Array.isArray(object.material) ||
+      object.renderOrder !== 0 ||
+      object.geometry.morphAttributes.position?.length
+    ) {
+      return
+    }
+    const material = object.material
+    if (!material.visible || material.transparent || material.opacity < 1 || material.alphaTest > 0) return
+    const visibility = overviewDecorationVisibility(object, root)
+    if (!visibility) return
+    sources.push({
+      geometry: object.geometry,
+      material,
+      matrix: rootInverse.clone().multiply(object.matrixWorld),
+      mesh: object,
+      ...visibility,
+    })
+  })
+
+  const groups = new Map<string, OverviewDecorationSource[]>()
+  for (const source of sources) {
+    const key = [
+      source.material.uuid,
+      source.visibilitySignature,
+      source.mesh.castShadow ? 1 : 0,
+      source.mesh.receiveShadow ? 1 : 0,
+      geometryAttributeSignature(source.geometry),
+    ].join('|')
+    const group = groups.get(key) ?? []
+    group.push(source)
+    groups.set(key, group)
+  }
+
+  let mergedSourceCount = 0
+  let batchIndex = 0
+  for (const group of groups.values()) {
+    if (group.length < 2) continue
+    const transformed = group.map(source => {
+      const geometry = source.geometry.clone()
+      // Primitive geometries such as BoxGeometry retain face groups even
+      // when the mesh owns one material. The groups are redundant in that
+      // case and would otherwise prevent safe cross-object merging.
+      geometry.clearGroups()
+      return geometry.applyMatrix4(source.matrix)
+    })
+    const geometry = mergeGeometries(transformed, false)
+    transformed.forEach(candidate => candidate.dispose())
+    if (!geometry) continue
+    preserveGeometryAttributeAliases(
+      geometry,
+      group.map(source => source.geometry),
+    )
+    geometry.computeBoundingBox()
+    geometry.computeBoundingSphere()
+    const first = group[0]!
+    const batch = new THREE.Mesh(geometry, first.material)
+    batch.name = `${root.name}-overview-decoration-batch-${batchIndex++}`
+    batch.castShadow = first.mesh.castShadow
+    batch.receiveShadow = first.mesh.receiveShadow
+    batch.userData.trackStaticOverviewBatch = true
+    batch.userData.decorative = true
+    batch.userData.visualOnly = true
+    batch.userData.materialSlot = first.mesh.userData.materialSlot
+    if (first.themeOnly) {
+      batch.userData.themeOnly = first.themeOnly.length === 1 ? first.themeOnly[0] : [...first.themeOnly]
+    }
+    if (first.themeHidden) {
+      batch.userData.themeHidden = first.themeHidden.length === 1 ? first.themeHidden[0] : [...first.themeHidden]
+    }
+    root.add(batch)
+    for (const source of group) {
+      source.mesh.removeFromParent()
+      if (!source.mesh.userData.sharedGeometry) source.geometry.dispose()
+    }
+    mergedSourceCount += group.length
+  }
+  return mergedSourceCount
+}
+
+function overviewDecorationVisibility(
+  object: THREE.Object3D,
+  root: THREE.Object3D,
+): { themeHidden?: readonly string[]; themeOnly?: readonly string[]; visibilitySignature: string } | undefined {
+  let decorative = false
+  let only: Set<string> | undefined
+  const hidden = new Set<string>()
+  for (let current: THREE.Object3D | null = object; current; current = current.parent) {
+    decorative ||= current.userData.decorative === true
+    if (current.userData[DYNAMIC_SHADOW_ROOT] || current.userData.isPortalViewSurface) return undefined
+    const currentOnly = themeVisibilityIds(current.userData.themeOnly)
+    const currentHidden = themeVisibilityIds(current.userData.themeHidden)
+    if (!current.visible && currentOnly.length === 0 && currentHidden.length === 0) return undefined
+    if (currentOnly.length > 0) {
+      const values = new Set(currentOnly)
+      only = only ? new Set([...only].filter(themeId => values.has(themeId))) : values
+    }
+    currentHidden.forEach(themeId => hidden.add(themeId))
+    if (current === root) break
+  }
+  if (!decorative) return undefined
+  if (only) hidden.forEach(themeId => only!.delete(themeId))
+  if (only?.size === 0) return undefined
+  const themeOnly = only ? [...only].sort() : undefined
+  const themeHidden = hidden.size > 0 ? [...hidden].sort() : undefined
+  return {
+    ...(themeOnly ? { themeOnly } : {}),
+    ...(themeHidden ? { themeHidden } : {}),
+    visibilitySignature: `only=${themeOnly?.join(',') ?? '*'};hidden=${themeHidden?.join(',') ?? ''}`,
+  }
+}
+
+function themeVisibilityIds(value: unknown): string[] {
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) return value.filter((themeId): themeId is string => typeof themeId === 'string')
+  return []
+}
+
+function geometryAttributeSignature(geometry: THREE.BufferGeometry): string {
+  const attributes = Object.entries(geometry.attributes)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, attribute]) =>
+      [name, attribute.itemSize, attribute.normalized ? 1 : 0, attribute.array.constructor.name].join(':'),
+    )
+  return `${geometry.index ? 'indexed' : 'plain'}:${attributes.join(',')}`
+}