@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/wild-west-vortex-housing.ts

@@ -0,0 +1,572 @@
+import * as THREE from 'three'
+
+export interface WildWestVortexHousingOptions {
+  pieceId: string
+  center: THREE.Vector3
+  outerRadius: number
+  floorOuterRadius?: number
+  innerRadius: number
+  segmentCount: number
+  surfaceHeightAtRadius(radius: number): number
+  drainTopY: number
+  shellMaterial: THREE.Material
+  floorPerimeterTreatments?: readonly {
+    material: THREE.Material
+    materialId: string
+    themeId: string | readonly string[]
+  }[]
+  shellDrop?: number
+  inletShell?: {
+    vertices: readonly number[]
+    indices: readonly number[]
+    fasciaIndices?: readonly number[]
+    seam: readonly {
+      vertexIndex: number
+      angle: number
+    }[]
+  }
+  rimOpening?: {
+    entryAngle: number
+    orbitDirection: -1 | 1
+    sweep: number
+  }
+  outletTunnel?: {
+    curve: THREE.Curve<THREE.Vector3>
+    radius: number
+    innerRadius: number
+  }
+  innerFunnel?: {
+    rings: readonly {
+      radius: number
+      height: number
+      centerX: number
+      centerZ: number
+    }[]
+    wallThickness: number
+  }
+}
+
+function markDecorative(object: THREE.Object3D): void {
+  object.userData.decorative = true
+  object.userData.visualOnly = true
+  object.castShadow = true
+  object.receiveShadow = true
+}
+
+/**
+ * Adds the removable Wild West skin around the existing vortex. The housing
+ * deliberately accepts no Rapier world or collider bookkeeping: it dresses
+ * the bowl without becoming another physical surface.
+ */
+export function addWildWestVortexHousing(root: THREE.Object3D, options: WildWestVortexHousingOptions): THREE.Group {
+  const group = new THREE.Group()
+  group.name = `${options.pieceId}-wild-west-vortex-housing`
+  group.userData.decorative = true
+  group.userData.visualOnly = true
+
+  const segments = Math.max(24, Math.round(options.segmentCount))
+  const radialBands = 4
+  const outerRadius = Math.max(options.innerRadius + 0.8, options.outerRadius)
+  const floorOuterRadius = THREE.MathUtils.clamp(options.floorOuterRadius ?? outerRadius, options.innerRadius, outerRadius)
+  const outlet = options.outletTunnel
+  const outletRadius = Math.max(0.18, outlet?.radius ?? options.innerRadius)
+  const funnelRings = options.innerFunnel?.rings
+  const funnelMouth = funnelRings?.at(-1)
+  const funnelWallThickness = Math.max(0.02, options.innerFunnel?.wallThickness ?? 0.2)
+  const collarRadius = funnelMouth
+    ? funnelMouth.radius + funnelWallThickness
+    : outlet
+      ? outletRadius
+      : Math.min(outerRadius - 0.55, options.innerRadius + 0.34)
+  const shellDrop = options.shellDrop ?? 0.3
+  const shellHeightAtRadius = (radius: number): number => options.surfaceHeightAtRadius(radius) - shellDrop
+  const outerHeight = options.surfaceHeightAtRadius(outerRadius)
+  const outerShellHeight = shellHeightAtRadius(outerRadius)
+  const shellInnerY = shellHeightAtRadius(collarRadius)
+  const outletInnerRadius = Math.min(
+    outletRadius,
+    Math.max(0.12, outlet?.innerRadius ?? outletRadius - 0.2),
+  )
+  const outletStart = outlet?.curve.getPointAt(0) ?? options.center.clone().setY(options.drainTopY)
+  const outletIsLinear = outlet
+    ? [0.25, 0.5, 0.75].every(progress =>
+        outlet.curve
+          .getPointAt(progress)
+          .distanceToSquared(outlet.curve.getPointAt(0).lerp(outlet.curve.getPointAt(1), progress)) <= 0.000_000_01,
+      )
+    : false
+  // Atlas outlets are straight vertical tubes. Subdividing the same line into
+  // 32 exterior bands and another 32 bore bands creates thousands of
+  // collinear triangles without changing silhouette, normals, or linearly
+  // interpolated UVs. Preserve dense sampling automatically for any future
+  // genuinely curved outlet.
+  const tubeBands = outletIsLinear ? 1 : 32
+  const neckBands = 3
+  const neckControlY = THREE.MathUtils.lerp(shellInnerY, outletStart.y, 0.68)
+  const profilePoint = (progress: number): { radius: number; height: number } => {
+    const inverse = 1 - progress
+    return {
+      radius:
+        inverse ** 3 * collarRadius +
+        3 * inverse * inverse * progress * (collarRadius - (collarRadius - outletRadius) * 0.52) +
+        3 * inverse * progress * progress * outletRadius +
+        progress ** 3 * outletRadius,
+      height:
+        inverse ** 3 * shellInnerY +
+        3 * inverse * inverse * progress * (shellInnerY - 0.16) +
+        3 * inverse * progress * progress * neckControlY +
+        progress ** 3 * outletStart.y,
+    }
+  }
+
+  interface HousingRing {
+    center: THREE.Vector3
+    radius: number
+    normal: THREE.Vector3
+    binormal: THREE.Vector3
+  }
+  const rings: HousingRing[] = []
+  const appendHorizontalRing = (radius: number, height: number): number => {
+    const ringIndex = rings.length
+    rings.push({
+      center: new THREE.Vector3(options.center.x, height, options.center.z),
+      radius,
+      normal: new THREE.Vector3(1, 0, 0),
+      binormal: new THREE.Vector3(0, 0, 1),
+    })
+    return ringIndex
+  }
+  const appendProfileRing = (
+    profile: { radius: number; height: number; centerX: number; centerZ: number },
+    radiusOffset = 0,
+    heightOffset = 0,
+  ): void => {
+    rings.push({
+      center: new THREE.Vector3(profile.centerX, profile.height + heightOffset, profile.centerZ),
+      radius: profile.radius + radiusOffset,
+      normal: new THREE.Vector3(1, 0, 0),
+      binormal: new THREE.Vector3(0, 0, 1),
+    })
+  }
+
+  // Trace the complete exposed cross-section as one surface of revolution:
+  // bowl underside -> funnel exterior -> pipe exterior -> open terminal lip
+  // -> pipe interior -> funnel interior. There is no second render mesh and
+  // no coincident surface for the depth buffer to reveal.
+  // Meet the guard at its actual base plane. Extending the fascia upward
+  // behind block-built wall styles exposes a purple toothed band through the
+  // course gaps in Material Slot Debug and at grazing angles.
+  appendHorizontalRing(outerRadius, outerHeight - 0.03)
+  const outerShellRingIndex = appendHorizontalRing(outerRadius, outerShellHeight)
+  const floorOuterRingIndex =
+    floorOuterRadius < outerRadius - 0.000_001
+      ? appendHorizontalRing(floorOuterRadius, shellHeightAtRadius(floorOuterRadius))
+      : outerShellRingIndex
+  for (let band = 1; band <= radialBands; band += 1) {
+    const progress = band / radialBands
+    const radius = THREE.MathUtils.lerp(
+      floorOuterRadius,
+      collarRadius,
+      THREE.MathUtils.smoothstep(progress, 0, 1),
+    )
+    appendHorizontalRing(radius, shellHeightAtRadius(radius))
+  }
+  if (outlet && funnelRings && funnelRings.length >= 2) {
+    const mouth = funnelRings.at(-1)!
+    appendProfileRing(mouth, funnelWallThickness, -funnelWallThickness)
+    for (let index = funnelRings.length - 2; index >= 0; index -= 1) {
+      const profile = funnelRings[index]!
+      const progress = index / (funnelRings.length - 1)
+      appendProfileRing(profile, funnelWallThickness, -funnelWallThickness * progress)
+    }
+    // The outer throat and first pipe ring are identical. Start at band one
+    // so the entire pipe exterior has exactly one topological owner.
+    for (let band = 1; band <= tubeBands; band += 1) {
+      const progress = band / tubeBands
+      rings.push({
+        center: outlet.curve.getPointAt(progress),
+        radius: outletRadius,
+        normal: new THREE.Vector3(1, 0, 0),
+        binormal: new THREE.Vector3(0, 0, 1),
+      })
+    }
+    // One annular terminal face closes the wall thickness without capping the
+    // bore. Then walk the same axis back upward at the inner radius.
+    rings.push({
+      center: outlet.curve.getPointAt(1),
+      radius: outletInnerRadius,
+      normal: new THREE.Vector3(1, 0, 0),
+      binormal: new THREE.Vector3(0, 0, 1),
+    })
+    for (let band = tubeBands - 1; band >= 0; band -= 1) {
+      const progress = band / tubeBands
+      rings.push({
+        center: outlet.curve.getPointAt(progress),
+        radius: outletInnerRadius,
+        normal: new THREE.Vector3(1, 0, 0),
+        binormal: new THREE.Vector3(0, 0, 1),
+      })
+    }
+    for (let index = 1; index < funnelRings.length; index += 1) {
+      const profile = funnelRings[index]!
+      appendProfileRing(profile)
+    }
+  } else if (outlet) {
+    const neckStart = rings.at(-1)!
+    for (let band = 1; band <= neckBands; band += 1) {
+      const progress = band / neckBands
+      rings.push({
+        center: neckStart.center.clone().lerp(outletStart, progress),
+        radius: THREE.MathUtils.lerp(neckStart.radius, outletRadius, progress),
+        normal: new THREE.Vector3(1, 0, 0),
+        binormal: new THREE.Vector3(0, 0, 1),
+      })
+    }
+  } else {
+    const profile = profilePoint(1)
+    appendHorizontalRing(profile.radius, profile.height)
+  }
+
+  const shellVertices: number[] = []
+  const shellUvs: number[] = []
+  const shellIndices: number[] = []
+  const outerFasciaIndices: number[] = []
+  const trimmedFasciaPanels = [0, 0]
+  const turn = Math.PI * 2
+  const normalizeAngle = (angle: number): number => ((angle % turn) + turn) % turn
+  const openingBoundaryAngles = options.rimOpening
+    ? [
+        normalizeAngle(options.rimOpening.entryAngle),
+        normalizeAngle(
+          options.rimOpening.entryAngle +
+            options.rimOpening.orbitDirection * (turn - options.rimOpening.sweep),
+        ),
+      ]
+    : []
+  // A skipped regular panel only approximates the inlet cut and can leave up
+  // to half a segment of purple housing outside the exact yellow wall plane.
+  // Insert both analytic opening boundaries into every ring so the fascia,
+  // shoulder, bowl, funnel, and tube retain one compatible indexed topology.
+  const angularSamples = [
+    ...Array.from({ length: segments }, (_, segment) => (segment / segments) * turn),
+    ...openingBoundaryAngles,
+    ...(options.inletShell?.seam.map(vertex => normalizeAngle(vertex.angle)) ?? []),
+  ]
+    .sort((left, right) => left - right)
+    .filter((angle, index, angles) => index === 0 || Math.abs(angle - angles[index - 1]!) > 0.000_001)
+  const ringAngles = [...angularSamples, angularSamples[0]! + turn]
+  const rowLength = ringAngles.length
+  const angularPanelCount = rowLength - 1
+  let longitudinal = 0
+  rings.forEach((ring, ringIndex) => {
+    if (ringIndex > 0) {
+      const previous = rings[ringIndex - 1]!
+      longitudinal += previous.center.distanceTo(ring.center) + Math.abs(previous.radius - ring.radius)
+    }
+    for (const angle of ringAngles) {
+      const angleProgress = angle / turn
+      const radial = ring.normal
+        .clone()
+        .multiplyScalar(Math.cos(angle))
+        .addScaledVector(ring.binormal, Math.sin(angle))
+      const position = ring.center.clone().addScaledVector(radial, ring.radius)
+      shellVertices.push(position.x, position.y, position.z)
+      shellUvs.push(angleProgress * Math.PI * 2 * ring.radius, longitudinal)
+    }
+  })
+  for (let ring = 0; ring < rings.length - 1; ring += 1) {
+    for (let segment = 0; segment < angularPanelCount; segment += 1) {
+      // The integrated inlet owns this part of the outer fascia. Leaving the
+      // complete underside ring here exposes it as a dark circular seam below
+      // the inlet apron, even though the two top surfaces share vertices.
+      // The first two bands form the complete outer fascia: the vertical lip
+      // at the guard's outer face and the horizontal shoulder back to the
+      // traversable floor radius. Both must stop at the inlet opening. Cutting
+      // only the first band leaves the shoulder running through the opening as
+      // a long purple strip with a protruding corner beside the straight wall.
+      // Trim only the outer fascia bands before the shared floor-radius ring.
+      // When the housing is intentionally inset, the outer shell and floor
+      // ring are the same ring; trimming the next band would cut the actual
+      // bowl underside away from the inlet seam.
+      if (ring < floorOuterRingIndex && options.rimOpening) {
+        const midpointAngle = (ringAngles[segment]! + ringAngles[segment + 1]!) / 2
+        let directed = Math.atan2(
+          Math.sin(midpointAngle - options.rimOpening.entryAngle),
+          Math.cos(midpointAngle - options.rimOpening.entryAngle),
+        )
+        if (options.rimOpening.orbitDirection > 0 && directed < 0) directed += Math.PI * 2
+        if (options.rimOpening.orbitDirection < 0 && directed > 0) directed -= Math.PI * 2
+        const wallArcSweep = Math.PI * 2 - options.rimOpening.sweep
+        if (Math.abs(directed) > wallArcSweep) {
+          trimmedFasciaPanels[ring]! += 1
+          continue
+        }
+      }
+      const current = ring * rowLength + segment
+      const next = current + rowLength
+      shellIndices.push(current, current + 1, next, current + 1, next + 1, next)
+      if (ring === 0) {
+        outerFasciaIndices.push(current, current + 1, next, current + 1, next + 1, next)
+      }
+    }
+  }
+
+  // Cutting the two outer fascia bands creates an exposed triangular
+  // cross-section at each side of the inlet. Close those exact analytic cut
+  // planes so the visible purple edge remains one thin floor profile beneath
+  // the yellow wall. Without these faces the deeper inlet side closure is
+  // visible through the open end and reads as a swollen purple wedge.
+  let inletFasciaTerminalCount = 0
+  if (options.rimOpening && floorOuterRingIndex !== outerShellRingIndex) {
+    const openingMidpointAngle = normalizeAngle(
+      options.rimOpening.entryAngle - options.rimOpening.orbitDirection * options.rimOpening.sweep / 2,
+    )
+    for (const boundaryAngle of openingBoundaryAngles) {
+      const angleIndex = ringAngles
+        .slice(0, angularPanelCount)
+        .findIndex(
+          angle =>
+            Math.abs(Math.atan2(Math.sin(angle - boundaryAngle), Math.cos(angle - boundaryAngle))) <
+            0.000_001,
+        )
+      if (angleIndex < 0) throw new Error(`Missing Vortex fascia terminal angle ${boundaryAngle}`)
+      const outerTop = angleIndex
+      const outerBottom = outerShellRingIndex * rowLength + angleIndex
+      const floorBottom = floorOuterRingIndex * rowLength + angleIndex
+      const towardOpening = Math.sign(
+        Math.atan2(
+          Math.sin(openingMidpointAngle - boundaryAngle),
+          Math.cos(openingMidpointAngle - boundaryAngle),
+        ),
+      ) || 1
+      const expectedNormal = new THREE.Vector3(
+        -Math.sin(boundaryAngle) * towardOpening,
+        0,
+        Math.cos(boundaryAngle) * towardOpening,
+      )
+      const pointAt = (index: number): THREE.Vector3 =>
+        new THREE.Vector3(
+          shellVertices[index * 3]!,
+          shellVertices[index * 3 + 1]!,
+          shellVertices[index * 3 + 2]!,
+        )
+      const normal = pointAt(outerBottom)
+        .sub(pointAt(outerTop))
+        .cross(pointAt(floorBottom).sub(pointAt(outerTop)))
+      if (normal.dot(expectedNormal) >= 0) {
+        shellIndices.push(outerTop, outerBottom, floorBottom)
+      } else {
+        shellIndices.push(outerTop, floorBottom, outerBottom)
+      }
+      inletFasciaTerminalCount += 1
+    }
+  }
+
+  const inletSeamVertexIndices: number[] = []
+  let inletFasciaOverlayIndexCount = 0
+  let inletShellIndexOffset = 0
+  // The integrated inlet has the same visual ownership as the bowl
+  // underside. Its complete curved boundary must reuse the bowl's indexed
+  // apron ring. Merely appending coincident positions creates a disconnected
+  // mesh island whose independently-computed normals expose the join.
+  if (options.inletShell) {
+    inletShellIndexOffset = shellIndices.length
+    const remappedVertices = new Map<number, number>()
+    for (const seamVertex of options.inletShell.seam) {
+      const normalizedSeamAngle = normalizeAngle(seamVertex.angle)
+      const angleIndex = ringAngles
+        .slice(0, angularPanelCount)
+        .findIndex(
+          angle =>
+            Math.abs(
+              Math.atan2(
+                Math.sin(angle - normalizedSeamAngle),
+                Math.cos(angle - normalizedSeamAngle),
+              ),
+            ) < 0.000_001,
+        )
+      if (angleIndex < 0) {
+        throw new Error(`Missing Vortex housing seam angle ${seamVertex.angle}`)
+      }
+      const housingVertexIndex = floorOuterRingIndex * rowLength + angleIndex
+      const sourceOffset = seamVertex.vertexIndex * 3
+      const housingOffset = housingVertexIndex * 3
+      const seamDistance = Math.hypot(
+        options.inletShell.vertices[sourceOffset]! - shellVertices[housingOffset]!,
+        options.inletShell.vertices[sourceOffset + 1]! - shellVertices[housingOffset + 1]!,
+        options.inletShell.vertices[sourceOffset + 2]! - shellVertices[housingOffset + 2]!,
+      )
+      if (seamDistance > 0.000_001) {
+        throw new Error(`Vortex inlet shell misses its housing seam by ${seamDistance}`)
+      }
+      remappedVertices.set(seamVertex.vertexIndex, housingVertexIndex)
+      inletSeamVertexIndices.push(housingVertexIndex)
+    }
+
+    for (const sourceIndex of options.inletShell.indices) {
+      let housingVertexIndex = remappedVertices.get(sourceIndex)
+      if (housingVertexIndex === undefined) {
+        const sourceOffset = sourceIndex * 3
+        housingVertexIndex = shellVertices.length / 3
+        shellVertices.push(
+          options.inletShell.vertices[sourceOffset]!,
+          options.inletShell.vertices[sourceOffset + 1]!,
+          options.inletShell.vertices[sourceOffset + 2]!,
+        )
+        shellUvs.push(
+          options.inletShell.vertices[sourceOffset]!,
+          options.inletShell.vertices[sourceOffset + 2]!,
+        )
+        remappedVertices.set(sourceIndex, housingVertexIndex)
+      }
+      shellIndices.push(housingVertexIndex)
+    }
+    for (const sourceIndex of options.inletShell.fasciaIndices ?? []) {
+      const housingVertexIndex = remappedVertices.get(sourceIndex)
+      if (housingVertexIndex === undefined) {
+        throw new Error(`Missing remapped Vortex inlet fascia vertex ${sourceIndex}`)
+      }
+      outerFasciaIndices.push(housingVertexIndex)
+      inletFasciaOverlayIndexCount += 1
+    }
+  }
+
+  // Trimming the circular fascia deliberately leaves some generated ring
+  // vertices unreferenced. Compact the completed topology so the production
+  // geometry contains only vertices owned by a visible triangle, while
+  // preserving the inlet-to-bowl seam indices and angular wrap pairs.
+  const referencedVertexIndices = [...new Set(shellIndices)].sort((left, right) => left - right)
+  const compactVertexIndex = new Map<number, number>()
+  const compactShellVertices: number[] = []
+  const compactShellUvs: number[] = []
+  referencedVertexIndices.forEach((sourceIndex, targetIndex) => {
+    compactVertexIndex.set(sourceIndex, targetIndex)
+    const sourceOffset = sourceIndex * 3
+    compactShellVertices.push(
+      shellVertices[sourceOffset]!,
+      shellVertices[sourceOffset + 1]!,
+      shellVertices[sourceOffset + 2]!,
+    )
+    const sourceUvOffset = sourceIndex * 2
+    compactShellUvs.push(shellUvs[sourceUvOffset]!, shellUvs[sourceUvOffset + 1]!)
+  })
+  const compactShellIndices = shellIndices.map(index => compactVertexIndex.get(index)!)
+  const compactInletSeamVertexIndices = inletSeamVertexIndices.map(index => compactVertexIndex.get(index)!)
+  const compactAngularWrapPairs = rings
+    .map((_, ringIndex) => [
+      compactVertexIndex.get(ringIndex * rowLength),
+      compactVertexIndex.get(ringIndex * rowLength + angularPanelCount),
+    ] as const)
+    .filter((pair): pair is readonly [number, number] => pair[0] !== undefined && pair[1] !== undefined)
+
+  const shellGeometry = new THREE.BufferGeometry()
+  shellGeometry.setAttribute('position', new THREE.Float32BufferAttribute(compactShellVertices, 3))
+  shellGeometry.setAttribute('uv', new THREE.Float32BufferAttribute(compactShellUvs, 2))
+  shellGeometry.setIndex(compactShellIndices)
+  shellGeometry.computeVertexNormals()
+  const normals = shellGeometry.getAttribute('normal')
+  for (const [first, last] of compactAngularWrapPairs) {
+    const averaged = new THREE.Vector3(
+      normals.getX(first) + normals.getX(last),
+      normals.getY(first) + normals.getY(last),
+      normals.getZ(first) + normals.getZ(last),
+    ).normalize()
+    normals.setXYZ(first, averaged.x, averaged.y, averaged.z)
+    normals.setXYZ(last, averaged.x, averaged.y, averaged.z)
+  }
+  normals.needsUpdate = true
+  const shell = new THREE.Mesh(shellGeometry, options.shellMaterial)
+  shell.name = `${options.pieceId}-wild-west-vortex-continuous-housing-shell`
+  shell.userData.panelCount = angularPanelCount * (rings.length - 1)
+  shell.userData.surfaceTopology = 'single-continuous-indexed-mesh'
+  shell.userData.continuousOutputShell = true
+  shell.userData.outletTerminalProfile = 'single-surface-funnel-and-open-pipe'
+  shell.userData.outletPipeBands = outlet ? tubeBands : 0
+  shell.userData.outletPipeLinear = outletIsLinear
+  shell.userData.embeddedTubeEntry = false
+  shell.userData.throatSealRadius = outlet ? outletRadius : 0
+  shell.userData.singleTubeExit = true
+  shell.userData.singleRenderMesh = Boolean(outlet && funnelRings)
+  shell.userData.duplicateOutletRingCount = 0
+  shell.userData.integratedInletShell = Boolean(options.inletShell)
+  shell.userData.inletSeamVertexIndices = compactInletSeamVertexIndices
+  shell.userData.inletSeamSampleCount = compactInletSeamVertexIndices.length
+  shell.userData.inletShellIndexOffset = inletShellIndexOffset
+  shell.userData.inletFasciaTerminalCount = inletFasciaTerminalCount
+  shell.userData.trimmedInletFasciaPanels = trimmedFasciaPanels
+  shell.userData.rimOpeningBoundaryAngles = openingBoundaryAngles
+  shell.userData.circularOuterRadius = outerRadius
+  shell.userData.floorOuterRadius = floorOuterRadius
+  markDecorative(shell)
+  group.add(shell)
+
+  // The traversable bowl and this housing deliberately remain separate
+  // geometry owners. The shared floor treatment therefore cannot discover
+  // the housing's exposed vertical lip from the floor mesh. Reuse only the
+  // first housing band here so the visual shoulder continues down the outer
+  // floor depth without reaching the bowl underside, funnel, drain bore, or
+  // connected inlet opening.
+  for (const [treatmentIndex, treatment] of (options.floorPerimeterTreatments ?? []).entries()) {
+    if (outerFasciaIndices.length === 0) continue
+    const sourceVertexIndices = [...new Set(outerFasciaIndices)].sort((left, right) => left - right)
+    const fasciaVertexIndex = new Map<number, number>()
+    const fasciaVertices: number[] = []
+    const fasciaUvs: number[] = []
+    const zeroDistances: number[] = []
+    const faceRoles: number[] = []
+    sourceVertexIndices.forEach((sourceIndex, targetIndex) => {
+      fasciaVertexIndex.set(sourceIndex, targetIndex)
+      const positionOffset = sourceIndex * 3
+      const x = shellVertices[positionOffset]!
+      const y = shellVertices[positionOffset + 1]!
+      const z = shellVertices[positionOffset + 2]!
+      fasciaVertices.push(x, y, z)
+      const uvOffset = sourceIndex * 2
+      fasciaUvs.push(shellUvs[uvOffset]!, shellUvs[uvOffset + 1]!)
+      zeroDistances.push(0)
+      faceRoles.push(2)
+    })
+
+    const fasciaGeometry = new THREE.BufferGeometry()
+    fasciaGeometry.setAttribute('position', new THREE.Float32BufferAttribute(fasciaVertices, 3))
+    fasciaGeometry.setAttribute('uv', new THREE.Float32BufferAttribute(fasciaUvs, 2))
+    fasciaGeometry.setAttribute('themePerimeterDistance', new THREE.Float32BufferAttribute(zeroDistances, 1))
+    fasciaGeometry.setAttribute('themePerimeterSideDistance', new THREE.Float32BufferAttribute(zeroDistances, 1))
+    fasciaGeometry.setAttribute('themePerimeterTerminalDistance', new THREE.Float32BufferAttribute(zeroDistances, 1))
+    fasciaGeometry.setAttribute('themePerimeterFaceRole', new THREE.Float32BufferAttribute(faceRoles, 1))
+    fasciaGeometry.setIndex(outerFasciaIndices.map(index => fasciaVertexIndex.get(index)!))
+    // Recompute from the selected fascia faces rather than borrowing the
+    // continuous housing normals. This keeps the circular lip smooth while
+    // giving both straight inlet sides their own correct outward offset.
+    fasciaGeometry.computeVertexNormals()
+    fasciaGeometry.computeBoundingBox()
+    fasciaGeometry.computeBoundingSphere()
+    fasciaGeometry.userData.perimeterSource = 'vortex-housing-outer-depth'
+    fasciaGeometry.userData.perimeterCoversTop = false
+    fasciaGeometry.userData.perimeterCoversExposedSides = true
+    fasciaGeometry.userData.perimeterCoversUnderside = false
+    fasciaGeometry.userData.perimeterCoversInnerDrain = false
+    fasciaGeometry.userData.inletFasciaTriangleCount = inletFasciaOverlayIndexCount / 3
+
+    const fascia = new THREE.Mesh(fasciaGeometry, treatment.material)
+    fascia.name = `${options.pieceId}-floor-perimeter-depth-overlay${treatmentIndex === 0 ? '' : `-${treatmentIndex + 1}`}`
+    fascia.userData.themeOnly = treatment.themeId
+    fascia.userData.decorative = true
+    fascia.userData.visualOnly = true
+    fascia.userData.appearanceMaterialId = treatment.materialId
+    fascia.userData.perimeterEdgeProfile = 'metric-square-perimeter-feather'
+    fascia.userData.vortexHousingRole = 'outer-floor-fascia-shoulder'
+    fascia.receiveShadow = true
+    group.add(fascia)
+  }
+
+  const housingBounds = new THREE.Box3().setFromObject(group)
+  group.userData.housingBounds = {
+    min: housingBounds.min.toArray(),
+    max: housingBounds.max.toArray(),
+  }
+  group.userData.drainTopY = options.drainTopY
+  group.userData.bodyMeshCount = 1
+  root.add(group)
+  return group
+}

package/src/pages/track-lab/atlas-vortex-layout.ts

@@ -0,0 +1 @@
+export * from '@marble.fun/physics-engine/atlas-vortex-layout'

package/src/pages/track-lab/cone-field-layout.ts

@@ -0,0 +1 @@
+export * from '@marble.fun/physics-engine/cone-field-layout'

package/src/pages/track-lab/conveyor-layout.ts

@@ -0,0 +1 @@
+export * from '@marble.fun/physics-engine/conveyor-layout'

package/src/pages/track-lab/engine/canonical-track-assembly.ts

@@ -0,0 +1,64 @@
+import type { TrackDocument } from '@marble.fun/physics-engine'
+import * as THREE from 'three'
+
+import type { ThemeMaterialRegistry } from '../../../three/theme-material-registry'
+import { applyTrackDocumentMaterialContinuity } from '../../../three/track-material-continuity'
+import { batchStaticTrackShadowCasters } from '../../play/race/track-shadow-batching'
+import { visualConnectionState } from './track-lab-connection-state'
+import { createTrackPieceVisual, type TrackPieceVisual } from './track-piece-visual'
+
+/**
+ * The materialised course shared by editing and racing. Editor helpers,
+ * marbles, Rapier resources, and race-only effects deliberately live outside
+ * this assembly.
+ */
+export interface CanonicalTrackAssembly {
+  readonly document: TrackDocument
+  readonly root: THREE.Group
+  readonly pieceVisuals: ReadonlyMap<string, TrackPieceVisual>
+}
+
+export interface OwnedCanonicalTrackAssembly extends CanonicalTrackAssembly {
+  dispose(): void
+}
+
+export function createCanonicalTrackAssembly(
+  document: TrackDocument,
+  materials: ThemeMaterialRegistry,
+): OwnedCanonicalTrackAssembly {
+  const root = new THREE.Group()
+  root.name = 'canonical-track-pieces'
+  const pieceVisuals = new Map<string, TrackPieceVisual>()
+  const {
+    connectedConnectorIdsByPiece,
+    continuousFluidConnectorIdsByPiece,
+    continuousSupportConnectorIdsByPiece,
+    connectorFramesByPiece,
+  } = visualConnectionState(document)
+
+  for (const piece of document.pieces) {
+    const visual = createTrackPieceVisual(piece, materials, {
+      connectedConnectorIds: connectedConnectorIdsByPiece.get(piece.id) ?? new Set(),
+      continuousFluidConnectorIds: continuousFluidConnectorIdsByPiece.get(piece.id) ?? new Set(),
+      continuousSupportConnectorIds: continuousSupportConnectorIdsByPiece.get(piece.id) ?? new Set(),
+      connectorFrames: connectorFramesByPiece.get(piece.id),
+      overviewLod: true,
+      deferSupportUntilMaterialContinuity: true,
+    })
+    root.add(visual.root)
+    pieceVisuals.set(piece.id, visual)
+  }
+  applyTrackDocumentMaterialContinuity(document, pieceVisuals)
+  for (const visual of pieceVisuals.values()) batchStaticTrackShadowCasters(visual.root)
+
+  return {
+    document,
+    root,
+    pieceVisuals,
+    dispose(): void {
+      for (const visual of pieceVisuals.values()) visual.dispose()
+      pieceVisuals.clear()
+      root.removeFromParent()
+    },
+  }
+}