@marble.fun/track-catalog 3.0.0

package/src/pages/track-lab/engine/track-piece-visual.ts

@@ -0,0 +1,1420 @@
+import {
+  initialTrackCatalog,
+  laneGradeDrop,
+  portalPairNumber,
+  resolveTemplateConnectors,
+  TRACK_MODULE_LENGTH,
+  type JsonObject,
+  type TrackConnectorTemplate,
+  type TrackPieceInstance,
+  type TrackPieceTemplate,
+  type TrackVector,
+} from '@marble.fun/physics-engine'
+import * as THREE from 'three'
+
+import { VisualSphereGeometry, VisualCylinderGeometry } from '../../../three/visual-geometry'
+
+import type { TrackMaterials } from '../../play/race/track-mechanisms'
+import { portalPairColor } from '../../play/race/portal-pair-color'
+import {
+  createPortalEndpointVisual,
+  PORTAL_RENDER_TARGET_TEXTURE,
+  portalVisualStyleFromId,
+  type PortalEndpointVisual,
+} from '../../play/race/portal-visual'
+import { trackSurfaceBasis } from '../../play/race/track-surface-basis'
+import {
+  defaultTrackTroughDepth,
+  type RailPieceDefinition,
+  type VortexPieceDefinition,
+} from '../../play/race/track-definition'
+import { addFinishGate, addRebounds, addRailPiece, addVortex } from '../../play/race/track-world'
+import type { ThemeMaterialRegistry } from '../../../three/theme-material-registry'
+import type { ThemeMaterialSlot } from '../../../three/track-theme'
+import {
+  ANCIENT_EGYPT_PORTAL_AGED_GOLD_ID,
+  ANCIENT_EGYPT_PORTAL_CARVED_SANDSTONE_ID,
+  ANCIENT_EGYPT_PORTAL_SANDSTONE_ID,
+  ANCIENT_EGYPT_PYRAMID_LIMESTONE_ID,
+  WILD_WEST_COVERED_MINE_IRON_ID,
+  WILD_WEST_COVERED_MINE_TIMBER_ID,
+} from '../../../three/theme-catalog'
+import {
+  resolvedFloorMaterialIdForTheme,
+  resolvedRailMaterialId,
+  WILD_WEST_RAIL_MATERIAL_ID,
+  WILD_WEST_RAIL_TIE_MATERIAL_ID,
+} from '../../../three/railroad-appearance'
+import { WILD_WEST_TRESTLE_METAL_MATERIAL_ID } from '../../play/race/track-appearance-support'
+import { resolveFloorSurfaceTreatment, resolveFloorSurfaceTreatments } from '../../play/race/track-floor-material-rules'
+import {
+  SHARED_ROPE_WALL_BACKING_MATERIAL_ID,
+  SHARED_ROPE_WALL_END_GRAIN_MATERIAL_ID,
+  SHARED_ROPE_WALL_TIMBER_MATERIAL_ID,
+} from '../../../three/rope-wall-appearance'
+import {
+  JUNGLE_TEMPLE_BRONZE_MATERIAL_ID,
+  JUNGLE_TEMPLE_FACADE_MATERIAL_ID,
+  JUNGLE_TEMPLE_PLATFORM_MATERIAL_ID,
+  JUNGLE_TEMPLE_STONE_MATERIAL_ID,
+  JUNGLE_TEMPLE_TIMBER_MATERIAL_ID,
+} from '../../../three/jungle-temple-appearance'
+import {
+  JAPANESE_SAKURA_BRIDGE_HARDWARE_ID,
+  JAPANESE_SAKURA_BRIDGE_TIMBER_ID,
+  JAPANESE_SAKURA_CASTLE_KAWARA_ID,
+  JAPANESE_SAKURA_CASTLE_MASONRY_ID,
+  JAPANESE_SAKURA_PORTAL_FOUNDATION_STONE_ID,
+  JAPANESE_SAKURA_CASTLE_TIMBER_ID,
+} from '../../../three/japanese-sakura-appearance'
+import {
+  SPACE_STATION_ARMORED_WALL_ID,
+  SPACE_STATION_CENTER_GUIDE_ID,
+  SPACE_STATION_WALL_LIGHT_ID,
+  SPACE_STATION_WALL_PANEL_ID,
+  SPACE_STATION_WALL_RIB_ID,
+  SPACE_STATION_WALL_TRIM_ID,
+} from '../../../three/space-station-appearance'
+import {
+  CONE_FIELD_PEG_HEIGHT,
+  CONE_FIELD_PEG_RADIUS,
+  createConeFieldDeckProfile,
+  createConeFieldLayout,
+} from '../cone-field-layout'
+import {
+  TRACK_LAB_CONVEYOR_BOTTOM,
+  TRACK_LAB_CONVEYOR_INPUT,
+  TRACK_LAB_CONVEYOR_LOADING,
+  TRACK_LAB_CONVEYOR_RELEASE,
+  TRACK_LAB_CONVEYOR_SHELF_COUNT,
+  TRACK_LAB_CONVEYOR_SHELF_DEPTH,
+  TRACK_LAB_CONVEYOR_SHELF_TILT_RADIANS,
+  TRACK_LAB_CONVEYOR_TOP,
+  TRACK_LAB_CONVEYOR_WIDTH,
+} from '../conveyor-layout'
+import { createFlipperBankDeck, createFlipperBankLayout } from '../flipper-bank-layout'
+import {
+  REBOUND_HEIGHT,
+  REBOUND_HOLD_SECONDS,
+  REBOUND_LENGTH,
+  REBOUND_COOLDOWN_SECONDS,
+  REBOUND_RESTITUTION,
+  REBOUND_RETURN_SECONDS,
+  REBOUND_STRIKE_DISTANCE,
+  REBOUND_STRIKE_SECONDS,
+  REBOUND_WIDTH,
+  createReboundDeck,
+  createReboundLayout,
+  createSingleFileSqueezeRail,
+  type ReboundPattern,
+} from '../simple-obstacle-layout'
+import {
+  RISING_WALL_DEPTH,
+  RISING_WALL_HEIGHT,
+  RISING_WALL_WIDTH,
+  createRisingWallDeck,
+  createRisingWallLayout,
+  createRisingWallSchedule,
+  risingWallExposedHeight,
+  risingWallHeightFraction,
+  type RisingWallDensity,
+} from '../rising-wall-layout'
+import {
+  ATLAS_VORTEX_CENTER,
+  ATLAS_VORTEX_DRAIN_OUTPUT_WIDTH,
+  ATLAS_VORTEX_DRAIN_CHANNEL,
+  ATLAS_VORTEX_DRAIN_PATH,
+  ATLAS_VORTEX_ENTRY,
+  ATLAS_VORTEX_ENTRY_APPROACH,
+  ATLAS_VORTEX_INPUT,
+  ATLAS_VORTEX_OUTPUT,
+  createAtlasVortexDefinition,
+  atlasVortexDrainProfile,
+} from '../atlas-vortex-layout'
+import {
+  applyRailConnectorFrames,
+  createIntersectionRailDefinitions,
+  createPublicLaneRailDefinition,
+  createRoutingMergeDeck,
+  createRoutingSplitterDeck,
+  splitterPivotLocalPosition,
+  TRACK_LAB_FINISH_WIDTH,
+  TRACK_LAB_SPLITTER_ARM_DEPTH,
+  TRACK_LAB_SPLITTER_ARM_HEIGHT,
+  TRACK_LAB_SPLITTER_ARM_LENGTH,
+  TRACK_LAB_WALL_HEIGHT,
+  type RailConnectorFrame,
+} from '../track-piece-layout'
+import { collectEditorSelectables, computeEditorBounds } from './editor-object-geometry'
+import {
+  CANONICAL_FLIPPER_DIMENSIONS,
+  createEndPivotedFlipperPaddleVisual,
+  createFlipperHubVisual,
+  createFlipperPaddleVisual,
+} from '../flipper-component'
+import { createPegObstacleVisualFactory } from '../../play/race/peg-obstacle-visual'
+import {
+  WILD_WEST_ANTIQUE_BRASS_MATERIAL_ID,
+  WILD_WEST_GUNMETAL_FLIPPER_MATERIAL_ID,
+} from '../../../three/rugged-track-appearance'
+import {
+  addWildWestMineLiftFrame,
+  decorateWildWestMineLiftShelf,
+  WILD_WEST_THEME_ID,
+} from '../../play/race/wild-west-mine-lift'
+import {
+  addJungleTempleLiftSkin,
+  decorateJungleTempleShelf,
+  JUNGLE_TEMPLE_THEME_ID,
+} from '../../play/race/jungle-temple-lift'
+import {
+  addPortalDerivedElevatorSkins,
+  decoratePortalDerivedElevatorShelf,
+  EGYPT_ELEVATOR_THEME_ID,
+  JAPAN_ELEVATOR_THEME_ID,
+  SPACE_ELEVATOR_THEME_ID,
+} from '../../play/race/portal-derived-elevator-skins'
+import { markDynamicTrackShadowRoot } from '../../play/race/track-shadow-batching'
+export interface TrackPieceVisual {
+  root: THREE.Group
+  bounds: THREE.Box3
+  selectableObjects: readonly THREE.Object3D[]
+  decorationAnchors: readonly THREE.Object3D[]
+  portalPreview?: {
+    color: string
+    endpoint: PortalEndpointVisual
+    pairId: string
+    role: 'entry' | 'exit'
+  }
+  dispose(): void
+  adoptMaterialRegistry(materials: ThemeMaterialRegistry): void
+}
+
+interface TrackPieceVisualOptions {
+  connectedConnectorIds?: ReadonlySet<string>
+  continuousFluidConnectorIds?: ReadonlySet<string>
+  continuousSupportConnectorIds?: ReadonlySet<string>
+  connectorFrames?: ReadonlyMap<string, RailConnectorFrame>
+  overviewLod?: boolean
+  /** Hidden live tracks need only their authored theme; the editor keeps instant theme switching. */
+  prebuildThemeVariants?: boolean
+  materialConnectionPhase?: number
+  deferSupportUntilMaterialContinuity?: boolean
+  /** Editor-only docking markers. Runtime/race visuals keep these hidden. */
+  connectorMarkersVisible?: boolean
+  /** Skip editor-only bounds, ray-picking meshes, and connector markers for hidden race preparation. */
+  editorMetadata?: boolean
+}
+
+export function createTrackPieceVisual(
+  piece: TrackPieceInstance,
+  materials: ThemeMaterialRegistry,
+  options: TrackPieceVisualOptions = {},
+): TrackPieceVisual {
+  const template = initialTrackCatalog.require(piece)
+  const resolvedConnectors = resolveTemplateConnectors(template, piece.parameters)
+  const editorMetadata = options.editorMetadata !== false
+  const root = new THREE.Group()
+  root.name = piece.id
+  root.userData.pieceInstanceId = piece.id
+  root.position.set(...piece.transform.position)
+  root.rotation.y = (piece.transform.yawSteps * -Math.PI) / 2
+  root.userData.railConnectors = resolvedConnectors
+  root.userData.connectedConnectorIds = options.connectedConnectorIds
+  root.userData.continuousFluidConnectorIds = options.continuousFluidConnectorIds
+  root.userData.continuousSupportConnectorIds = options.continuousSupportConnectorIds
+  root.userData.connectorFrames = options.connectorFrames
+  root.userData.overviewLod = options.overviewLod === true
+  root.userData.prebuildThemeVariants = options.prebuildThemeVariants !== false
+  root.userData.editorBoundsSource = 'canonical-track-geometry'
+  root.userData.editorMetadata = editorMetadata
+  root.userData.materialConnectionPhase = options.deferSupportUntilMaterialContinuity
+    ? Number.NaN
+    : options.materialConnectionPhase
+  root.userData.deferStoneArchitectureUntilMaterialContinuity = options.deferSupportUntilMaterialContinuity === true
+  const resolvedFloorMaterialId = resolvedFloorMaterialIdForTheme(
+    materials.activeTheme,
+    piece.appearance?.floorMaterialId,
+  )
+  const resolvedRailId = resolvedRailMaterialId(piece.appearance)
+  const appearance = piece.appearance
+    ? {
+        ...piece.appearance,
+        ...(resolvedFloorMaterialId ? { floorMaterialId: resolvedFloorMaterialId } : { floorMaterialId: undefined }),
+        ...(resolvedRailId ? { railMaterialId: resolvedRailId } : {}),
+      }
+    : undefined
+  root.userData.pieceAppearance = appearance
+  let portalPreview: TrackPieceVisual['portalPreview']
+  const addMesh = (
+    geometry: THREE.BufferGeometry,
+    slot: ThemeMaterialSlot,
+    name: string,
+    configure?: (mesh: THREE.Mesh) => void,
+    appearanceMaterialId?: string,
+  ): THREE.Mesh => {
+    const mesh = new THREE.Mesh(geometry)
+    mesh.name = `${piece.id}-${name}`
+    mesh.userData.pieceInstanceId = piece.id
+    mesh.castShadow = true
+    mesh.receiveShadow = true
+    if (appearanceMaterialId) materials.bindAppearance(mesh, appearanceMaterialId, slot)
+    else materials.bind(mesh, slot)
+    configure?.(mesh)
+    root.add(mesh)
+    return mesh
+  }
+
+  const publicLane = createPublicLaneRailDefinition({
+    id: piece.id,
+    templateId: template.id,
+    runtimeKind: template.runtimeKind,
+    parameters: piece.parameters,
+  })
+  if (publicLane) {
+    addRailPreview(root, materials, piece.id, publicLane)
+  } else if (template.runtimeKind === 'finish') {
+    addFinishPreview(root, materials, piece.id)
+  } else if (template.runtimeKind === 'vortex') {
+    root.userData.editorOutlineMode = 'bounds'
+    addAtlasVortexPreview(root, materials, piece.id)
+  } else {
+    portalPreview = addMechanismVisual(
+      root,
+      materials,
+      piece.id,
+      template,
+      piece.parameters,
+      appearance,
+      options.connectedConnectorIds,
+      addMesh,
+    )
+  }
+
+  if (editorMetadata) {
+    const connectorMarkerGeometry = new VisualSphereGeometry(0.16, 10, 8)
+    const connectorMarkerMaterial = new THREE.MeshBasicMaterial({ color: '#ffffff', toneMapped: false })
+    // A render batch may clone this material while the course is faded out.
+    // Preserve its authored state so the clone reveals with the same opacity.
+    connectorMarkerMaterial.userData.themeBaseOpacity = connectorMarkerMaterial.opacity
+    connectorMarkerMaterial.userData.themeBaseTransparent = connectorMarkerMaterial.transparent
+    connectorMarkerMaterial.userData.themeBaseDepthWrite = connectorMarkerMaterial.depthWrite
+    for (const connector of resolvedConnectors) {
+      const mesh = new THREE.Mesh(connectorMarkerGeometry, connectorMarkerMaterial)
+      mesh.name = `${piece.id}-connector-${connector.id}`
+      mesh.position.set(...connector.localPosition)
+      mesh.userData.pieceInstanceId = piece.id
+      mesh.userData.materialSlot = 'editor.connector'
+      mesh.userData.excludeFromEditorBounds = true
+      mesh.userData.isTrackConnectorMarker = true
+      mesh.userData.ownsMaterial = true
+      // A connection always docks an output to an input at the same point.
+      // Keep the output-side marker as the single owner so the two spheres do
+      // not z-fight into a striped "gumdrop".
+      mesh.userData.connectorMarkerOwner =
+        !connector.kind.endsWith('input') || !options.connectedConnectorIds?.has(connector.id)
+      mesh.visible = options.connectorMarkersVisible === true && mesh.userData.connectorMarkerOwner
+      root.add(mesh)
+    }
+  }
+
+  materials.rebindFloorAppearanceForTheme(root, piece.appearance?.floorMaterialId)
+  let bindingRegistry = materials
+
+  if (editorMetadata) root.updateMatrixWorld(true)
+  const bounds = editorMetadata ? computeEditorBounds(root) : new THREE.Box3()
+  const selectableObjects = editorMetadata ? collectEditorSelectables(root) : []
+
+  return {
+    root,
+    bounds,
+    selectableObjects,
+    decorationAnchors: [],
+    ...(portalPreview ? { portalPreview } : {}),
+    adoptMaterialRegistry(nextMaterials) {
+      if (bindingRegistry === nextMaterials) return
+      nextMaterials.adoptBindingsFrom(bindingRegistry, root)
+      bindingRegistry = nextMaterials
+    },
+    dispose() {
+      bindingRegistry.releaseBindings(root)
+      const geometries = new Set<THREE.BufferGeometry>()
+      const ownedMaterials = new Set<THREE.Material>()
+      const ownedTextures = new Set<THREE.Texture>()
+      root.traverse(object => {
+        if (object instanceof THREE.Mesh || object instanceof THREE.Line || object instanceof THREE.Points) {
+          if (!object.userData.sharedGeometry) geometries.add(object.geometry)
+          if (object.userData.ownsMaterial) {
+            const meshMaterials = Array.isArray(object.material) ? object.material : [object.material]
+            meshMaterials.forEach(material => ownedMaterials.add(material))
+          }
+        }
+      })
+      geometries.forEach(geometry => geometry.dispose())
+      ownedMaterials.forEach(material => {
+        Object.values(material).forEach(value => {
+          if (value instanceof THREE.Texture && value.userData[PORTAL_RENDER_TARGET_TEXTURE] !== true) {
+            ownedTextures.add(value)
+          }
+        })
+        material.dispose()
+      })
+      ownedTextures.forEach(texture => texture.dispose())
+      root.removeFromParent()
+    },
+  }
+}
+
+function addAtlasVortexPreview(root: THREE.Group, materials: ThemeMaterialRegistry, pieceId: string): void {
+  const appearance = root.userData.pieceAppearance as TrackPieceInstance['appearance'] | undefined
+  const definition: VortexPieceDefinition = {
+    ...createAtlasVortexDefinition(pieceId, ATLAS_VORTEX_CENTER, ATLAS_VORTEX_ENTRY, ATLAS_VORTEX_DRAIN_CHANNEL, [
+      ATLAS_VORTEX_OUTPUT[0] - ATLAS_VORTEX_DRAIN_CHANNEL[0],
+      ATLAS_VORTEX_OUTPUT[1] - ATLAS_VORTEX_DRAIN_CHANNEL[1],
+      ATLAS_VORTEX_OUTPUT[2] - ATLAS_VORTEX_DRAIN_CHANNEL[2],
+    ]),
+    ...(appearance ? { appearance } : {}),
+    deferStoneArchitectureUntilMaterialContinuity: root.userData.deferStoneArchitectureUntilMaterialContinuity === true,
+    waterFlowInputConnected: (root.userData.continuousFluidConnectorIds as ReadonlySet<string> | undefined)?.has(
+      'input',
+    ),
+  }
+  const entryRail: RailPieceDefinition = {
+    id: `${pieceId}-entry`,
+    label: 'Vortex tangential entry',
+    type: 'rail',
+    points: [ATLAS_VORTEX_INPUT, ...ATLAS_VORTEX_ENTRY_APPROACH],
+    width: 4,
+    // The mechanism owns this inlet, but its open terminal is still a
+    // standard lane connector. Reuse the complete canonical trough profile
+    // so its top, underside, and both wall bases dock vertex-for-vertex with
+    // a snapped straight lane.
+    troughDepth: defaultTrackTroughDepth(4),
+    troughProfile: 'full',
+    wallHeight: TRACK_LAB_WALL_HEIGHT,
+    continuousFloorMaterialOnly: true,
+    verticalWalls: true,
+    supportsAppearanceCanopy: false,
+    ...(appearance ? { appearance } : {}),
+  }
+  const vortexMaterials = createPreviewTrackMaterials(
+    materials,
+    appearance,
+    root.userData.prebuildThemeVariants !== false,
+  )
+  const framedEntryRail = addRailPreview(root, materials, pieceId, entryRail, definition)
+  addVortex(root, undefined, definition, vortexMaterials, undefined, framedEntryRail)
+  addRailPreview(root, materials, pieceId, {
+    id: `${pieceId}-drain`,
+    label: 'Continuous Atlas vortex catch and single-file drain',
+    type: 'rail',
+    points: [...ATLAS_VORTEX_DRAIN_PATH],
+    width: ATLAS_VORTEX_DRAIN_OUTPUT_WIDTH,
+    pointWidths: atlasVortexDrainProfile(),
+    widthProfile: 'smoothstep',
+    troughDepth: defaultTrackTroughDepth(ATLAS_VORTEX_DRAIN_OUTPUT_WIDTH),
+    pointTroughDepths: atlasVortexDrainProfile().map(defaultTrackTroughDepth),
+    troughProfile: 'full',
+    troughFlatFraction: 0,
+    wallHeight: TRACK_LAB_WALL_HEIGHT,
+    continuousFloorMaterialOnly: true,
+    supportsAppearanceCanopy: false,
+    // The tube drops above this receiving slope. Keep the floor and side-wall
+    // solids capped, but leave the rear open so no cross-wall is visible
+    // through the funnel bore.
+    capStart: true,
+    wallFriction: 0,
+    waterFlowStartConnected: Boolean(appearance?.vortexWaterId),
+    ...(appearance?.vortexWaterId ? { appearance: { ...appearance, waterOverlayId: appearance.vortexWaterId } } : {}),
+  })
+  root.traverse(object => {
+    object.userData.pieceInstanceId = pieceId
+  })
+  materials.captureBindings(root)
+}
+
+function addRailPreview(
+  root: THREE.Group,
+  materials: ThemeMaterialRegistry,
+  pieceId: string,
+  definition: RailPieceDefinition,
+  vortex?: VortexPieceDefinition,
+): RailPieceDefinition {
+  const connectors = (root.userData.railConnectors as readonly TrackConnectorTemplate[] | undefined) ?? []
+  const connectedConnectorIds = root.userData.connectedConnectorIds as ReadonlySet<string> | undefined
+  const continuousFluidConnectorIds = root.userData.continuousFluidConnectorIds as ReadonlySet<string> | undefined
+  const continuousSupportConnectorIds = root.userData.continuousSupportConnectorIds as ReadonlySet<string> | undefined
+  const connectorFrames = root.userData.connectorFrames as ReadonlyMap<string, RailConnectorFrame> | undefined
+  const framedDefinition = applyRailConnectorFrames(definition, connectors, connectedConnectorIds, connectorFrames)
+  const appearance = root.userData.pieceAppearance as TrackPieceInstance['appearance'] | undefined
+  const junctionBranches = framedDefinition.junctionBranches?.map(branch => ({
+    ...branch,
+    waterFlowStartConnected: continuousFluidConnectorIds?.has(branch.connectorId) === true,
+    points: connectorFrames?.get(branch.connectorId)?.position
+      ? [connectorFrames.get(branch.connectorId)!.position!, ...branch.points.slice(1)]
+      : branch.points,
+    startTangent: connectorFrames?.get(branch.connectorId)?.tangent ?? branch.startTangent,
+  }))
+  const previewDefinition = {
+    ...framedDefinition,
+    editorProxies: root.userData.editorMetadata !== false,
+    materialConnectors: connectors.map(connector => ({
+      id: connector.id,
+      position: connector.localPosition,
+    })),
+    materialConnectionPhase: root.userData.materialConnectionPhase as number | undefined,
+    deferStoneArchitectureUntilMaterialContinuity: root.userData.deferStoneArchitectureUntilMaterialContinuity === true,
+    waterFlowStartConnected: framedDefinition.junctionMainConnectorId
+      ? continuousFluidConnectorIds?.has(framedDefinition.junctionMainConnectorId) === true
+      : connectors.some(
+          connector => connector.kind.endsWith('input') && continuousFluidConnectorIds?.has(connector.id),
+        ),
+    waterFlowEndConnected: connectors.some(
+      connector => connector.kind.endsWith('output') && continuousFluidConnectorIds?.has(connector.id),
+    ),
+    ...(junctionBranches ? { junctionBranches } : {}),
+    verticalWalls: true,
+    ...(root.userData.overviewLod ? { previewProfileSamplePitch: 0.05 } : {}),
+    ...(appearance || framedDefinition.appearance
+      ? { appearance: { ...appearance, ...framedDefinition.appearance } }
+      : {}),
+  }
+  addRailPiece(
+    root,
+    undefined,
+    previewDefinition,
+    createPreviewTrackMaterials(materials, appearance, root.userData.prebuildThemeVariants !== false),
+    undefined,
+    vortex,
+    undefined,
+    {
+      capStart: !connectors.some(
+        connector => connector.kind.endsWith('input') && continuousSupportConnectorIds?.has(connector.id),
+      ),
+      capEnd: !connectors.some(
+        connector => connector.kind.endsWith('output') && continuousSupportConnectorIds?.has(connector.id),
+      ),
+    },
+  )
+  root.traverse(object => {
+    object.userData.pieceInstanceId = pieceId
+  })
+  materials.captureBindings(root)
+  return previewDefinition
+}
+
+function createPreviewTrackMaterials(
+  materials: ThemeMaterialRegistry,
+  appearance?: TrackPieceInstance['appearance'],
+  prebuildThemeVariants = true,
+): TrackMaterials {
+  return {
+    activeThemeId: materials.activeTheme.id,
+    prebuildThemeVariants,
+    get top() {
+      return materials.getAppearance(appearance?.floorMaterialId, 'lane.surface')
+    },
+    get edge() {
+      return materials.get('lane.edge')
+    },
+    get rail() {
+      return materials.getAppearance(appearance?.wallMaterialId, 'lane.guard')
+    },
+    get railBacking() {
+      return materials.get('lane.guard.backing')
+    },
+    get ropeWallBacking() {
+      return materials.getAppearance(SHARED_ROPE_WALL_BACKING_MATERIAL_ID, 'lane.guard.backing')
+    },
+    get ropeWallEndGrain() {
+      return materials.getAppearance(SHARED_ROPE_WALL_END_GRAIN_MATERIAL_ID, 'structure.primary')
+    },
+    get ropeWallTimber() {
+      return materials.getAppearance(SHARED_ROPE_WALL_TIMBER_MATERIAL_ID, 'structure.primary')
+    },
+    get structure() {
+      return materials.get('structure.primary')
+    },
+    get moving() {
+      return materials.get('mechanism.moving')
+    },
+    get signal() {
+      return materials.get('signal.route')
+    },
+    get hazard() {
+      return materials.get('signal.hazard')
+    },
+    get portal() {
+      return materials.get('effect.portal')
+    },
+    get energy() {
+      return materials.get('effect.energy')
+    },
+    get railroad() {
+      return materials.getAppearance(resolvedRailMaterialId(appearance) ?? WILD_WEST_RAIL_MATERIAL_ID, 'lane.edge')
+    },
+    get railDetailStyle() {
+      return materials.getAppearanceDetailStyle(resolvedRailMaterialId(appearance))
+    },
+    get railroadTimber() {
+      return materials.getAppearance(WILD_WEST_RAIL_TIE_MATERIAL_ID, 'structure.primary')
+    },
+    get obstacle() {
+      return materials.get('obstacle.primary')
+    },
+    get obstacleAccent() {
+      return materials.get('obstacle.secondary')
+    },
+    get obstacleBase() {
+      return materials.get('obstacle.base')
+    },
+    get flipperPrimary() {
+      return materials.get('mechanism.flipper.primary')
+    },
+    get flipperSecondary() {
+      return materials.get('mechanism.flipper.secondary')
+    },
+    get mineTimber() {
+      return materials.getAppearance('wild-west.mine-timber', 'structure.primary')
+    },
+    get coveredMineTimber() {
+      return materials.getAppearance(WILD_WEST_COVERED_MINE_TIMBER_ID, 'structure.primary')
+    },
+    get coveredMineIron() {
+      return materials.getAppearance(WILD_WEST_COVERED_MINE_IRON_ID, 'structure.secondary')
+    },
+    get portalIron() {
+      return materials.getAppearance(WILD_WEST_GUNMETAL_FLIPPER_MATERIAL_ID, 'structure.secondary')
+    },
+    get bone() {
+      return materials.getAppearance('wild-west.warm-ivory-bone', 'structure.primary')
+    },
+    get support() {
+      return materials.getAppearance(appearance?.supportMaterialId, 'structure.primary')
+    },
+    get floorSurfaceTreatment() {
+      return resolveFloorSurfaceTreatment(materials, appearance?.floorMaterialId)
+    },
+    get floorSurfaceTreatments() {
+      if (prebuildThemeVariants) {
+        return resolveFloorSurfaceTreatments(materials, appearance?.floorMaterialId)
+      }
+      const treatment = resolveFloorSurfaceTreatment(materials, appearance?.floorMaterialId)
+      return treatment ? [treatment] : []
+    },
+    get supportMetal() {
+      return materials.getAppearance(WILD_WEST_TRESTLE_METAL_MATERIAL_ID, 'structure.secondary')
+    },
+    get jungleTempleStone() {
+      return materials.getAppearance(JUNGLE_TEMPLE_STONE_MATERIAL_ID, 'lane.guard')
+    },
+    get jungleTempleFacade() {
+      return materials.getAppearance(JUNGLE_TEMPLE_FACADE_MATERIAL_ID, 'lane.guard')
+    },
+    get jungleTempleTimber() {
+      return materials.getAppearance(JUNGLE_TEMPLE_TIMBER_MATERIAL_ID, 'structure.primary')
+    },
+    get jungleTemplePlatform() {
+      return materials.getAppearance(JUNGLE_TEMPLE_PLATFORM_MATERIAL_ID, 'mechanism.moving')
+    },
+    get jungleTempleMoss() {
+      return materials.get('world.foliage')
+    },
+    get jungleTempleBronze() {
+      return materials.getAppearance(JUNGLE_TEMPLE_BRONZE_MATERIAL_ID, 'signal.route')
+    },
+    get wildWestBrass() {
+      return materials.getAppearance(WILD_WEST_ANTIQUE_BRASS_MATERIAL_ID, 'signal.route')
+    },
+    get egyptPortalSandstone() {
+      return materials.getAppearance(ANCIENT_EGYPT_PORTAL_SANDSTONE_ID, 'structure.primary')
+    },
+    get egyptPortalCarvedSandstone() {
+      return materials.getAppearance(ANCIENT_EGYPT_PORTAL_CARVED_SANDSTONE_ID, 'lane.guard')
+    },
+    get egyptPortalAgedGold() {
+      return materials.getAppearance(ANCIENT_EGYPT_PORTAL_AGED_GOLD_ID, 'signal.route')
+    },
+    get egyptPyramidLimestone() {
+      return materials.getAppearance(ANCIENT_EGYPT_PYRAMID_LIMESTONE_ID, 'structure.primary')
+    },
+    get egyptPyramidGold() {
+      return materials.get('obstacle.primary')
+    },
+    get sakuraCastleTimber() {
+      return materials.getAppearance(JAPANESE_SAKURA_CASTLE_TIMBER_ID, 'structure.primary')
+    },
+    get sakuraCastleMasonry() {
+      return materials.getAppearance(JAPANESE_SAKURA_CASTLE_MASONRY_ID, 'structure.secondary')
+    },
+    get sakuraCastleKawara() {
+      return materials.getAppearance(JAPANESE_SAKURA_CASTLE_KAWARA_ID, 'structure.secondary')
+    },
+    get sakuraBridgeTimber() {
+      return materials.getAppearance(JAPANESE_SAKURA_BRIDGE_TIMBER_ID, 'structure.primary')
+    },
+    get sakuraBridgeHardware() {
+      return materials.getAppearance(JAPANESE_SAKURA_BRIDGE_HARDWARE_ID, 'structure.secondary')
+    },
+    get spaceStationWallChassis() {
+      return materials.getAppearance(SPACE_STATION_ARMORED_WALL_ID, 'lane.guard')
+    },
+    get spaceStationWallPanel() {
+      return materials.getAppearance(SPACE_STATION_WALL_PANEL_ID, 'lane.guard')
+    },
+    get spaceStationWallRib() {
+      return materials.getAppearance(SPACE_STATION_WALL_RIB_ID, 'structure.primary')
+    },
+    get spaceStationWallTrim() {
+      return materials.getAppearance(SPACE_STATION_WALL_TRIM_ID, 'structure.secondary')
+    },
+    get spaceStationWallLight() {
+      return materials.getAppearance(SPACE_STATION_WALL_LIGHT_ID, 'effect.energy')
+    },
+    get spaceStationCenterGuide() {
+      return materials.getAppearance(SPACE_STATION_CENTER_GUIDE_ID, 'effect.energy')
+    },
+  }
+}
+
+function addFinishPreview(root: THREE.Group, materials: ThemeMaterialRegistry, pieceId: string): void {
+  addRailPreview(root, materials, pieceId, {
+    id: `${pieceId}-channel`,
+    label: 'Continuous narrowing ranked finish channel',
+    type: 'rail',
+    raceRole: 'finish',
+    points: [
+      [0, 0, 2.5],
+      [0, -2, -2],
+      [0, -2.7, -12],
+    ],
+    pointWidths: [4, TRACK_LAB_FINISH_WIDTH, TRACK_LAB_FINISH_WIDTH],
+    width: TRACK_LAB_FINISH_WIDTH,
+    pointTroughDepths: [
+      defaultTrackTroughDepth(4),
+      defaultTrackTroughDepth(TRACK_LAB_FINISH_WIDTH),
+      defaultTrackTroughDepth(TRACK_LAB_FINISH_WIDTH),
+    ],
+    troughDepth: defaultTrackTroughDepth(TRACK_LAB_FINISH_WIDTH),
+    troughProfile: 'full',
+    wallHeight: TRACK_LAB_WALL_HEIGHT,
+    floorFriction: 0.08,
+    wallFriction: 0,
+    closedEnd: true,
+  })
+  const finishMaterials = {
+    ...createPreviewTrackMaterials(materials, undefined, root.userData.prebuildThemeVariants !== false),
+    signal: materials.get('signal.finish'),
+  }
+  addFinishGate(
+    root,
+    {
+      id: pieceId,
+      label: 'Ranked finish channel',
+      type: 'finish',
+      center: [0, -2, -2],
+      direction: [0, 0, -1],
+      width: TRACK_LAB_FINISH_WIDTH,
+      channelEnd: [0, -2.7, -12],
+      rankingSlots: 6,
+      rankingSpacing: 1.22,
+    },
+    finishMaterials,
+  )
+  root.traverse(object => {
+    object.userData.pieceInstanceId = pieceId
+  })
+  materials.captureBindings(root)
+}
+
+type AddMesh = (
+  geometry: THREE.BufferGeometry,
+  slot: ThemeMaterialSlot,
+  name: string,
+  configure?: (mesh: THREE.Mesh) => void,
+  appearanceMaterialId?: string,
+) => THREE.Mesh
+
+function addMechanismVisual(
+  root: THREE.Group,
+  materials: ThemeMaterialRegistry,
+  pieceId: string,
+  template: TrackPieceTemplate,
+  parameters: JsonObject,
+  appearance: TrackPieceInstance['appearance'],
+  _connectedConnectorIds: ReadonlySet<string> | undefined,
+  addMesh: AddMesh,
+): TrackPieceVisual['portalPreview'] {
+  if (template.runtimeKind === 'start') {
+    addRailPreview(root, materials, pieceId, {
+      id: pieceId,
+      label: 'Start grid',
+      type: 'rail',
+      raceRole: 'start',
+      points: [
+        [0, 1.2, 4],
+        [0, 0, -2.5],
+      ],
+      startWidth: 6,
+      width: 4,
+      startTroughDepth: defaultTrackTroughDepth(6),
+      troughDepth: defaultTrackTroughDepth(4),
+      troughProfile: 'full',
+      wallHeight: TRACK_LAB_WALL_HEIGHT,
+      floorFriction: 0.08,
+    })
+    return
+  }
+
+  if (template.runtimeKind === 'peg-field') {
+    const layout = createConeFieldLayout(
+      lengthUnitsFromParameters(parameters),
+      conePatternFromParameters(parameters),
+      gradeFromParameters(parameters),
+    )
+    const deckProfile = createConeFieldDeckProfile(layout, defaultTrackTroughDepth(4))
+    addRailPreview(root, materials, pieceId, {
+      id: `${pieceId}-deck`,
+      label: 'Continuous enclosed cone forest deck',
+      type: 'rail',
+      points: [...deckProfile.points],
+      width: 4,
+      pointWidths: [...deckProfile.pointWidths],
+      troughDepth: defaultTrackTroughDepth(4),
+      pointTroughDepths: [...deckProfile.pointTroughDepths],
+      troughProfile: 'full',
+      wallHeight: TRACK_LAB_WALL_HEIGHT,
+      floorFriction: 0.012,
+      wallFriction: 0,
+    })
+    const up = vector(layout.up).normalize()
+    const rotation = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), up)
+    const createVisual = createPegObstacleVisualFactory({
+      radius: CONE_FIELD_PEG_RADIUS,
+      height: CONE_FIELD_PEG_HEIGHT,
+      colliderShape: 'cone',
+      bodyMaterial: materials.get('obstacle.primary'),
+      trimMaterial: materials.get('obstacle.secondary'),
+    })
+    layout.pegBases.forEach((base, index) => {
+      const visual = createVisual(`${pieceId}:${index}`).group
+      visual.name = `${pieceId}-cone-${index}`
+      visual.position.copy(vector(base).addScaledVector(up, CONE_FIELD_PEG_HEIGHT / 2))
+      visual.quaternion.copy(rotation)
+      visual.traverse(object => {
+        object.userData.pieceInstanceId = pieceId
+      })
+      root.add(visual)
+    })
+    materials.captureBindings(root)
+    return
+  }
+
+  if (template.runtimeKind === 'single-file-squeeze') {
+    addRailPreview(root, materials, pieceId, createSingleFileSqueezeRail(pieceId, template.label, parameters))
+    return
+  }
+
+  if (template.runtimeKind === 'rebounds') {
+    const appearance = root.userData.pieceAppearance as TrackPieceInstance['appearance'] | undefined
+    const lengthUnits = lengthUnitsFromParameters(parameters)
+    const layout = createReboundLayout(lengthUnits, parameters, reboundPatternFromParameters(parameters))
+    addRailPreview(
+      root,
+      materials,
+      pieceId,
+      createReboundDeck(`${pieceId}-deck`, template.label, lengthUnits, parameters),
+    )
+    addRebounds(
+      root,
+      {
+        id: `${pieceId}-rebounds`,
+        label: template.label,
+        type: 'rebounds',
+        direction: layout.direction,
+        mounts: layout.mounts,
+        reboundLength: REBOUND_LENGTH,
+        reboundWidth: REBOUND_WIDTH,
+        reboundHeight: REBOUND_HEIGHT,
+        friction: 0.01,
+        restitution: REBOUND_RESTITUTION,
+        strikeDistance: REBOUND_STRIKE_DISTANCE,
+        strikeSeconds: REBOUND_STRIKE_SECONDS,
+        holdSeconds: REBOUND_HOLD_SECONDS,
+        returnSeconds: REBOUND_RETURN_SECONDS,
+        cooldownSeconds: REBOUND_COOLDOWN_SECONDS,
+        ...(appearance ? { appearance } : {}),
+      },
+      createPreviewTrackMaterials(materials, appearance, root.userData.prebuildThemeVariants !== false),
+    )
+    root.children
+      .filter(child => child.name.startsWith(`${pieceId}-rebounds-rebound-`))
+      .forEach(markDynamicTrackShadowRoot)
+    materials.captureBindings(root)
+    return
+  }
+
+  if (template.runtimeKind === 'rising-wall-forest') {
+    const layout = createRisingWallLayout(lengthUnitsFromParameters(parameters), parameters)
+    const density = risingWallDensityFromParameters(parameters)
+    const schedule = createRisingWallSchedule(layout, density, `preview:${pieceId}`)
+    const basis = trackSurfaceBasis(layout.direction)
+    const up = vector(basis.up)
+    const rotation = new THREE.Quaternion().setFromRotationMatrix(
+      new THREE.Matrix4().makeBasis(vector(basis.right), up, vector(basis.forward).negate()),
+    )
+    addRailPreview(root, materials, pieceId, createRisingWallDeck(`${pieceId}-deck`, template.label, layout))
+    const wallGeometry = new THREE.BoxGeometry(RISING_WALL_WIDTH, RISING_WALL_HEIGHT, RISING_WALL_DEPTH)
+    const slotGeometry = new THREE.BoxGeometry(RISING_WALL_WIDTH + 0.14, 0.035, RISING_WALL_DEPTH + 0.14)
+    layout.anchors.forEach((anchor, index) => {
+      const fraction = risingWallHeightFraction(schedule, index, 0)
+      const exposedHeight = risingWallExposedHeight(RISING_WALL_HEIGHT, fraction)
+      const wall = addMesh(wallGeometry, 'obstacle.primary', `rising-wall-${index}`, mesh => {
+        mesh.position.copy(vector(anchor.position).addScaledVector(up, exposedHeight / 2))
+        mesh.quaternion.copy(rotation)
+        mesh.scale.set(1, exposedHeight / RISING_WALL_HEIGHT, 1)
+        mesh.visible = exposedHeight > 0.001
+      })
+      markDynamicTrackShadowRoot(wall)
+      addMesh(slotGeometry, 'obstacle.base', `rising-wall-slot-${index}`, mesh => {
+        mesh.position.copy(vector(anchor.position).addScaledVector(up, 0.018))
+        mesh.quaternion.copy(rotation)
+      })
+    })
+    return
+  }
+
+  if (template.runtimeKind === 'splitter') {
+    const drop = laneGradeDrop({ ...parameters, grade: parameters.grade ?? 'slope', lengthUnits: 1 })
+    const basis = trackSurfaceBasis([0, -drop, -TRACK_MODULE_LENGTH])
+    const forward = vector(basis.forward)
+    const surfaceRotation = new THREE.Quaternion().setFromRotationMatrix(
+      new THREE.Matrix4().makeBasis(forward, vector(basis.up), vector(basis.right)),
+    )
+    const center = vector(splitterPivotLocalPosition(drop))
+    addRailPreview(
+      root,
+      materials,
+      pieceId,
+      createRoutingSplitterDeck(`${pieceId}-deck`, 'Splitter routing deck', drop),
+    )
+    const flipperPrimary = materials.get('mechanism.flipper.primary')
+    const flipperSecondary = materials.get('mechanism.flipper.secondary')
+    const paddle = createEndPivotedFlipperPaddleVisual(
+      `${pieceId}-splitter-paddle`,
+      flipperPrimary,
+      {
+        length: TRACK_LAB_SPLITTER_ARM_LENGTH,
+        width: TRACK_LAB_SPLITTER_ARM_DEPTH,
+        height: TRACK_LAB_SPLITTER_ARM_HEIGHT,
+      },
+      flipperSecondary,
+      `${pieceId}-splitter-hub`,
+      0,
+    )
+    paddle.position.copy(center)
+    paddle.quaternion.copy(surfaceRotation)
+    paddle.userData.pieceInstanceId = pieceId
+    markDynamicTrackShadowRoot(paddle)
+    const paddleSurface = paddle.getObjectByName(`${pieceId}-splitter-paddle-surface`)
+    if (!(paddleSurface instanceof THREE.Mesh)) throw new Error('Canonical splitter paddle surface is missing')
+    materials.bind(paddleSurface, 'mechanism.flipper.primary')
+    const paddleHub = paddle.getObjectByName(`${pieceId}-splitter-hub`)
+    if (!(paddleHub instanceof THREE.Mesh)) throw new Error('Canonical splitter hub is missing')
+    materials.bind(paddleHub, 'mechanism.flipper.secondary')
+    root.add(paddle)
+    return
+  }
+
+  if (template.runtimeKind === 'merge') {
+    const drop = laneGradeDrop({ ...parameters, grade: parameters.grade ?? 'slope', lengthUnits: 1 })
+    addRailPreview(root, materials, pieceId, createRoutingMergeDeck(pieceId, 'Route merge catch deck', drop))
+    return
+  }
+
+  if (template.runtimeKind === 'intersection') {
+    const connectors = resolveTemplateConnectors(template, parameters)
+    const output = connectors.find(connector => connector.kind.endsWith('output'))
+    const allInputs = connectors.filter(connector => connector.kind.endsWith('input'))
+    if (!output || allInputs.length === 0) return
+    createIntersectionRailDefinitions(pieceId, template.label, allInputs, output).forEach(definition => {
+      addRailPreview(root, materials, pieceId, definition)
+    })
+    return
+  }
+
+  if (template.runtimeKind === 'flipper-bank') {
+    const layout = createFlipperBankLayout(lengthUnitsFromParameters(parameters), gradeFromParameters(parameters))
+    addRailPreview(
+      root,
+      materials,
+      pieceId,
+      createFlipperBankDeck(
+        `${pieceId}-deck`,
+        'Continuous enclosed flipper deck',
+        lengthUnitsFromParameters(parameters),
+        gradeFromParameters(parameters),
+      ),
+    )
+    const mounts = layout.mounts
+    const { length: paddleLength, height: paddleHeight } = CANONICAL_FLIPPER_DIMENSIONS
+    const flipperPrimary = materials.get('mechanism.flipper.primary')
+    const flipperSecondary = materials.get('mechanism.flipper.secondary')
+    mounts.forEach((mount, index) => {
+      const tangent = vector(layout.direction).normalize()
+      const right = new THREE.Vector3(tangent.z, 0, -tangent.x).normalize()
+      const up = new THREE.Vector3().crossVectors(tangent, right).normalize()
+      const paddleDepth = new THREE.Vector3().crossVectors(tangent, up).normalize()
+      const paddleRotation = new THREE.Quaternion().setFromRotationMatrix(
+        new THREE.Matrix4().makeBasis(tangent, up, paddleDepth),
+      )
+      const hubRotation = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), up)
+      const hinge = vector(mount.anchor).addScaledVector(up, paddleHeight / 2)
+      const center = hinge.clone().addScaledVector(tangent, paddleLength / 2)
+      const paddle = createFlipperPaddleVisual(
+        `${pieceId}-flipper-${index + 1}`,
+        flipperPrimary,
+        CANONICAL_FLIPPER_DIMENSIONS,
+      )
+      paddle.position.copy(center)
+      paddle.quaternion.copy(paddleRotation)
+      paddle.userData.pieceInstanceId = pieceId
+      markDynamicTrackShadowRoot(paddle)
+      const paddleSurface = paddle.getObjectByName(`${pieceId}-flipper-${index + 1}-surface`)
+      if (!(paddleSurface instanceof THREE.Mesh)) throw new Error('Canonical flipper paddle surface is missing')
+      materials.bind(paddleSurface, 'mechanism.flipper.primary')
+      const hub = createFlipperHubVisual(
+        `${pieceId}-flipper-hub-${index + 1}`,
+        flipperSecondary,
+        CANONICAL_FLIPPER_DIMENSIONS,
+      )
+      hub.position.copy(hinge)
+      hub.quaternion.copy(hubRotation)
+      hub.userData.pieceInstanceId = pieceId
+      materials.bind(hub, 'mechanism.flipper.secondary')
+      root.add(paddle, hub)
+    })
+    return
+  }
+
+  if (template.runtimeKind === 'conveyor') {
+    addConveyorPreview(root, materials, pieceId, addMesh)
+    return
+  }
+
+  if (template.runtimeKind === 'portal-entry-preview' || template.runtimeKind === 'portal-exit-preview') {
+    const isEntry = template.runtimeKind === 'portal-entry-preview'
+    addRailPreview(root, materials, pieceId, {
+      id: `${pieceId}-deck`,
+      label: isEntry ? 'Portal entry channel' : 'Portal exit channel',
+      type: 'rail',
+      points: isEntry
+        ? [
+            [0, 0, TRACK_MODULE_LENGTH / 2],
+            [0, 0, 0],
+          ]
+        : [
+            [0, 0, 0],
+            [0, 0, -TRACK_MODULE_LENGTH / 2],
+          ],
+      width: 4,
+      troughDepth: defaultTrackTroughDepth(4),
+      troughProfile: 'full',
+      wallHeight: TRACK_LAB_WALL_HEIGHT,
+      floorFriction: 0.04,
+    })
+    const color = portalPairColor(typeof parameters.pairId === 'string' ? parameters.pairId : '1')
+    const activeThemeId = materials.activeTheme.id
+    const endpoint = createPortalEndpointVisual(
+      `${pieceId}-portal`,
+      portalVisualStyleFromId(appearance?.portalVisualId),
+      color,
+      {
+        activeThemeId,
+        structure: materials.get('structure.primary'),
+        timber: materials.getAppearance('wild-west.mine-timber', 'structure.primary'),
+        metal: materials.getAppearance(WILD_WEST_GUNMETAL_FLIPPER_MATERIAL_ID, 'structure.secondary'),
+        portal: materials.get('effect.portal'),
+        energy: materials.get('effect.energy'),
+        jungle:
+          activeThemeId === JUNGLE_TEMPLE_THEME_ID
+            ? {
+                stone: materials.getAppearance(JUNGLE_TEMPLE_STONE_MATERIAL_ID, 'lane.guard'),
+                facade: materials.getAppearance(JUNGLE_TEMPLE_FACADE_MATERIAL_ID, 'lane.guard'),
+                bronze: materials.getAppearance(JUNGLE_TEMPLE_BRONZE_MATERIAL_ID, 'signal.route'),
+                foliage: materials.get('world.foliage'),
+              }
+            : undefined,
+        egypt:
+          activeThemeId === EGYPT_ELEVATOR_THEME_ID
+            ? {
+                sandstone: materials.getAppearance(ANCIENT_EGYPT_PORTAL_SANDSTONE_ID, 'structure.primary'),
+                carvedStone: materials.getAppearance(ANCIENT_EGYPT_PORTAL_CARVED_SANDSTONE_ID, 'lane.guard'),
+                agedGold: materials.getAppearance(ANCIENT_EGYPT_PORTAL_AGED_GOLD_ID, 'signal.route'),
+              }
+            : undefined,
+        sakura:
+          activeThemeId === JAPAN_ELEVATOR_THEME_ID
+            ? {
+                vermilion: materials.getAppearance(JAPANESE_SAKURA_BRIDGE_TIMBER_ID, 'structure.primary'),
+                plaster: materials.get('lane.guard.backing'),
+                foundationStone: materials.getAppearance(
+                  JAPANESE_SAKURA_PORTAL_FOUNDATION_STONE_ID,
+                  'structure.secondary',
+                ),
+                kawara: materials.getAppearance(JAPANESE_SAKURA_CASTLE_KAWARA_ID, 'structure.secondary'),
+                hardware: materials.getAppearance(JAPANESE_SAKURA_BRIDGE_HARDWARE_ID, 'structure.secondary'),
+              }
+            : undefined,
+        spaceStation:
+          activeThemeId === SPACE_ELEVATOR_THEME_ID
+            ? {
+                chassis: materials.getAppearance(SPACE_STATION_ARMORED_WALL_ID, 'lane.guard'),
+                panel: materials.getAppearance(SPACE_STATION_WALL_PANEL_ID, 'lane.guard'),
+                rib: materials.getAppearance(SPACE_STATION_WALL_RIB_ID, 'structure.primary'),
+                trim: materials.getAppearance(SPACE_STATION_WALL_TRIM_ID, 'structure.secondary'),
+                light: materials.getAppearance(SPACE_STATION_WALL_LIGHT_ID, 'effect.energy'),
+              }
+            : undefined,
+      },
+    )
+    endpoint.group.position.y = 1.8
+    if (!isEntry) endpoint.group.rotation.y = Math.PI
+    const requestedPairId = typeof parameters.pairId === 'string' ? parameters.pairId : '1'
+    const pairNumber = portalPairNumber(requestedPairId)
+    const portalPreview: NonNullable<TrackPieceVisual['portalPreview']> = {
+      color,
+      endpoint,
+      // Runtime portal ids use the canonical numeric pair id (A -> 1,
+      // B -> 2, ...). Keep the editor preview on the same identity so the
+      // race handoff leases these exact endpoint visuals instead of building
+      // an overlapping second portal pair.
+      pairId: pairNumber === Number.MAX_SAFE_INTEGER ? requestedPairId : String(pairNumber),
+      role: isEntry ? 'entry' : 'exit',
+    }
+    endpoint.group.traverse(object => {
+      object.userData.pieceInstanceId = pieceId
+    })
+    root.add(endpoint.group)
+    materials.captureBindings(endpoint.group)
+    return portalPreview
+  }
+
+  const bounds = template.bounds(parameters)
+  const width = bounds.maximum[0] - bounds.minimum[0]
+  const height = Math.max(0.8, bounds.maximum[1] - bounds.minimum[1])
+  const length = bounds.maximum[2] - bounds.minimum[2]
+  addMesh(new THREE.BoxGeometry(width, 0.35, length), 'lane.surface', 'mechanism-deck')
+  addMesh(
+    new VisualCylinderGeometry(Math.min(width, length) * 0.28, Math.min(width, length) * 0.28, height * 0.55, 24),
+    'mechanism.body',
+    'mechanism-body',
+    mesh => {
+      mesh.position.y = height * 0.3
+    },
+  )
+  addMesh(new THREE.BoxGeometry(width * 0.72, 0.24, 0.45), 'mechanism.moving', 'moving-element', mesh => {
+    mesh.position.y = Math.max(0.8, height * 0.58)
+  })
+}
+
+function addConveyorPreview(
+  root: THREE.Group,
+  materials: ThemeMaterialRegistry,
+  pieceId: string,
+  addMesh: AddMesh,
+): void {
+  addRailPreview(root, materials, pieceId, {
+    id: `${pieceId}-approach`,
+    label: 'Conveyor approach channel',
+    type: 'rail',
+    points: [TRACK_LAB_CONVEYOR_INPUT, TRACK_LAB_CONVEYOR_LOADING],
+    startWidth: 4,
+    width: TRACK_LAB_CONVEYOR_WIDTH,
+    startTroughDepth: defaultTrackTroughDepth(4),
+    troughDepth: defaultTrackTroughDepth(TRACK_LAB_CONVEYOR_WIDTH),
+    troughProfile: 'full',
+    wallHeight: TRACK_LAB_WALL_HEIGHT,
+    floorFriction: 0.08,
+  })
+  addRailPreview(root, materials, pieceId, {
+    id: `${pieceId}-release`,
+    label: 'Conveyor release channel',
+    type: 'rail',
+    points: [TRACK_LAB_CONVEYOR_RELEASE, [0, 6, -2.5]],
+    startWidth: TRACK_LAB_CONVEYOR_WIDTH,
+    width: 4,
+    startTroughDepth: defaultTrackTroughDepth(TRACK_LAB_CONVEYOR_WIDTH),
+    troughDepth: defaultTrackTroughDepth(4),
+    troughProfile: 'full',
+    wallHeight: TRACK_LAB_WALL_HEIGHT,
+    floorFriction: 0.08,
+  })
+
+  const liftHeight = TRACK_LAB_CONVEYOR_TOP[1] - TRACK_LAB_CONVEYOR_BOTTOM[1]
+  const liftMiddleY = (TRACK_LAB_CONVEYOR_TOP[1] + TRACK_LAB_CONVEYOR_BOTTOM[1]) / 2
+  const liftZ = TRACK_LAB_CONVEYOR_BOTTOM[2]
+  const activeThemeId = materials.activeTheme.id
+  const mineLiftMaterials = {
+    timber:
+      activeThemeId === WILD_WEST_THEME_ID
+        ? materials.getAppearance('wild-west.mine-timber', 'structure.primary')
+        : materials.get('structure.primary'),
+    iron:
+      activeThemeId === WILD_WEST_THEME_ID
+        ? materials.getAppearance('wild-west.railroad-iron', 'lane.edge')
+        : materials.get('lane.edge'),
+    signal: materials.get('signal.route'),
+  }
+  const mineLiftFrame =
+    activeThemeId === WILD_WEST_THEME_ID
+      ? addWildWestMineLiftFrame(root, {
+          id: pieceId,
+          bottom: vector(TRACK_LAB_CONVEYOR_BOTTOM),
+          rotation: new THREE.Quaternion(),
+          width: TRACK_LAB_CONVEYOR_WIDTH,
+          height: liftHeight,
+          depth: TRACK_LAB_CONVEYOR_SHELF_DEPTH,
+          releaseHeight: TRACK_LAB_CONVEYOR_RELEASE[1] - TRACK_LAB_CONVEYOR_BOTTOM[1],
+          materials: mineLiftMaterials,
+        })
+      : undefined
+  if (mineLiftFrame) materials.captureBindings(mineLiftFrame)
+  const jungleTempleMaterials = {
+    stone:
+      activeThemeId === JUNGLE_TEMPLE_THEME_ID
+        ? materials.getAppearance(JUNGLE_TEMPLE_STONE_MATERIAL_ID, 'lane.guard')
+        : materials.get('lane.guard'),
+    facade:
+      activeThemeId === JUNGLE_TEMPLE_THEME_ID
+        ? materials.getAppearance(JUNGLE_TEMPLE_FACADE_MATERIAL_ID, 'lane.guard')
+        : materials.get('lane.guard'),
+    timber:
+      activeThemeId === JUNGLE_TEMPLE_THEME_ID
+        ? materials.getAppearance(JUNGLE_TEMPLE_TIMBER_MATERIAL_ID, 'structure.primary')
+        : materials.get('structure.primary'),
+    platform:
+      activeThemeId === JUNGLE_TEMPLE_THEME_ID
+        ? materials.getAppearance(JUNGLE_TEMPLE_PLATFORM_MATERIAL_ID, 'mechanism.moving')
+        : materials.get('mechanism.moving'),
+    moss: materials.get('world.foliage'),
+    accent:
+      activeThemeId === JUNGLE_TEMPLE_THEME_ID
+        ? materials.getAppearance(JUNGLE_TEMPLE_BRONZE_MATERIAL_ID, 'signal.route')
+        : materials.get('signal.route'),
+  }
+  const jungleTempleSkin =
+    activeThemeId === JUNGLE_TEMPLE_THEME_ID
+      ? addJungleTempleLiftSkin(root, {
+          id: pieceId,
+          bottom: vector(TRACK_LAB_CONVEYOR_BOTTOM),
+          rotation: new THREE.Quaternion(),
+          width: TRACK_LAB_CONVEYOR_WIDTH,
+          height: liftHeight,
+          depth: TRACK_LAB_CONVEYOR_SHELF_DEPTH,
+          releaseHeight: TRACK_LAB_CONVEYOR_RELEASE[1] - TRACK_LAB_CONVEYOR_BOTTOM[1],
+          materials: jungleTempleMaterials,
+        })
+      : undefined
+  if (jungleTempleSkin) materials.captureBindings(jungleTempleSkin)
+  const portalDerivedMaterials = {
+    egypt: {
+      sandstone:
+        activeThemeId === EGYPT_ELEVATOR_THEME_ID
+          ? materials.getAppearance(ANCIENT_EGYPT_PORTAL_SANDSTONE_ID, 'structure.primary')
+          : materials.get('structure.primary'),
+      carvedStone:
+        activeThemeId === EGYPT_ELEVATOR_THEME_ID
+          ? materials.getAppearance(ANCIENT_EGYPT_PORTAL_CARVED_SANDSTONE_ID, 'lane.guard')
+          : materials.get('lane.guard'),
+      pyramidStone:
+        activeThemeId === EGYPT_ELEVATOR_THEME_ID
+          ? materials.getAppearance(ANCIENT_EGYPT_PYRAMID_LIMESTONE_ID, 'structure.primary')
+          : materials.get('structure.primary'),
+      pyramidGold: materials.get('obstacle.primary'),
+      bronze: materials.get('lane.edge'),
+      gold:
+        activeThemeId === EGYPT_ELEVATOR_THEME_ID
+          ? materials.getAppearance(ANCIENT_EGYPT_PORTAL_AGED_GOLD_ID, 'signal.route')
+          : materials.get('signal.route'),
+      paving: materials.get('lane.surface'),
+      signal: materials.get('signal.route'),
+    },
+    japan: {
+      vermilion:
+        activeThemeId === JAPAN_ELEVATOR_THEME_ID
+          ? materials.getAppearance(JAPANESE_SAKURA_BRIDGE_TIMBER_ID, 'structure.primary')
+          : materials.get('structure.primary'),
+      timber:
+        activeThemeId === JAPAN_ELEVATOR_THEME_ID
+          ? materials.getAppearance(JAPANESE_SAKURA_CASTLE_TIMBER_ID, 'structure.primary')
+          : materials.get('structure.primary'),
+      plaster: materials.get('lane.guard.backing'),
+      stone:
+        activeThemeId === JAPAN_ELEVATOR_THEME_ID
+          ? materials.getAppearance(JAPANESE_SAKURA_PORTAL_FOUNDATION_STONE_ID, 'structure.secondary')
+          : materials.get('structure.secondary'),
+      kawara:
+        activeThemeId === JAPAN_ELEVATOR_THEME_ID
+          ? materials.getAppearance(JAPANESE_SAKURA_CASTLE_KAWARA_ID, 'structure.secondary')
+          : materials.get('structure.secondary'),
+      hardware:
+        activeThemeId === JAPAN_ELEVATOR_THEME_ID
+          ? materials.getAppearance(JAPANESE_SAKURA_BRIDGE_HARDWARE_ID, 'structure.secondary')
+          : materials.get('structure.secondary'),
+      signal: materials.get('signal.route'),
+    },
+    space: {
+      chassis:
+        activeThemeId === SPACE_ELEVATOR_THEME_ID
+          ? materials.getAppearance(SPACE_STATION_ARMORED_WALL_ID, 'lane.guard')
+          : materials.get('lane.guard'),
+      panel:
+        activeThemeId === SPACE_ELEVATOR_THEME_ID
+          ? materials.getAppearance(SPACE_STATION_WALL_PANEL_ID, 'lane.guard')
+          : materials.get('lane.guard'),
+      rib:
+        activeThemeId === SPACE_ELEVATOR_THEME_ID
+          ? materials.getAppearance(SPACE_STATION_WALL_RIB_ID, 'structure.primary')
+          : materials.get('structure.primary'),
+      trim:
+        activeThemeId === SPACE_ELEVATOR_THEME_ID
+          ? materials.getAppearance(SPACE_STATION_WALL_TRIM_ID, 'structure.secondary')
+          : materials.get('structure.secondary'),
+      light:
+        activeThemeId === SPACE_ELEVATOR_THEME_ID
+          ? materials.getAppearance(SPACE_STATION_WALL_LIGHT_ID, 'effect.energy')
+          : materials.get('effect.energy'),
+    },
+  }
+  const portalDerivedSkins = addPortalDerivedElevatorSkins(root, {
+    activeThemeId,
+    id: pieceId,
+    bottom: vector(TRACK_LAB_CONVEYOR_BOTTOM),
+    rotation: new THREE.Quaternion(),
+    width: TRACK_LAB_CONVEYOR_WIDTH,
+    height: liftHeight,
+    depth: TRACK_LAB_CONVEYOR_SHELF_DEPTH,
+    releaseHeight: TRACK_LAB_CONVEYOR_RELEASE[1] - TRACK_LAB_CONVEYOR_BOTTOM[1],
+    materials: portalDerivedMaterials,
+  })
+  portalDerivedSkins.forEach(skin => materials.captureBindings(skin))
+  const themedElevatorIds = [
+    JUNGLE_TEMPLE_THEME_ID,
+    EGYPT_ELEVATOR_THEME_ID,
+    JAPAN_ELEVATOR_THEME_ID,
+    SPACE_ELEVATOR_THEME_ID,
+  ]
+  for (const side of [-1, 1] as const) {
+    addMesh(
+      new THREE.BoxGeometry(0.24, liftHeight + 1, TRACK_LAB_CONVEYOR_SHELF_DEPTH + 0.16),
+      'lane.guard',
+      `conveyor-wall-${side}`,
+      mesh => {
+        mesh.position.set(side * (TRACK_LAB_CONVEYOR_WIDTH / 2 - 0.12), liftMiddleY, liftZ)
+        mesh.userData.themeHidden = themedElevatorIds
+      },
+      JUNGLE_TEMPLE_STONE_MATERIAL_ID,
+    )
+    addMesh(
+      new THREE.BoxGeometry(0.38, liftHeight, 0.34),
+      'mechanism.body',
+      `conveyor-belt-${side}`,
+      mesh => {
+        mesh.position.set(side * (TRACK_LAB_CONVEYOR_WIDTH / 2 - 0.58), liftMiddleY, liftZ + 1.7)
+        mesh.userData.themeHidden = themedElevatorIds
+      },
+      JUNGLE_TEMPLE_TIMBER_MATERIAL_ID,
+    )
+  }
+
+  for (const y of [TRACK_LAB_CONVEYOR_BOTTOM[1] - 0.5, TRACK_LAB_CONVEYOR_TOP[1] + 0.5]) {
+    const drum = addMesh(
+      new VisualCylinderGeometry(0.56, 0.56, TRACK_LAB_CONVEYOR_WIDTH - 0.7, 20),
+      'signal.route',
+      `conveyor-drum-${y}`,
+      mesh => {
+        mesh.position.set(0, y, liftZ)
+        mesh.rotation.z = Math.PI / 2
+        mesh.userData.decorative = true
+        mesh.userData.themeHidden = [WILD_WEST_THEME_ID, ...themedElevatorIds]
+      },
+      JUNGLE_TEMPLE_TIMBER_MATERIAL_ID,
+    )
+    materials.captureBindings(drum)
+  }
+
+  for (let index = 0; index < TRACK_LAB_CONVEYOR_SHELF_COUNT; index += 1) {
+    const progress = (index + 0.5) / TRACK_LAB_CONVEYOR_SHELF_COUNT
+    const shelf = addMesh(
+      new THREE.BoxGeometry(TRACK_LAB_CONVEYOR_WIDTH - 0.56, 0.2, TRACK_LAB_CONVEYOR_SHELF_DEPTH),
+      'mechanism.moving',
+      `conveyor-shelf-${index + 1}`,
+      mesh => {
+        const shelfHeight = THREE.MathUtils.lerp(TRACK_LAB_CONVEYOR_BOTTOM[1], TRACK_LAB_CONVEYOR_TOP[1], progress)
+        const tiltTransition = THREE.MathUtils.smoothstep(shelfHeight - TRACK_LAB_CONVEYOR_BOTTOM[1], 0.45, 3.2)
+        mesh.position.set(0, shelfHeight, liftZ)
+        mesh.rotation.x = THREE.MathUtils.lerp(
+          TRACK_LAB_CONVEYOR_SHELF_TILT_RADIANS,
+          -TRACK_LAB_CONVEYOR_SHELF_TILT_RADIANS,
+          tiltTransition,
+        )
+      },
+      JUNGLE_TEMPLE_PLATFORM_MATERIAL_ID,
+    )
+    markDynamicTrackShadowRoot(shelf)
+    if (activeThemeId === WILD_WEST_THEME_ID)
+      decorateWildWestMineLiftShelf(
+        shelf,
+        `${pieceId}-conveyor-shelf-${index + 1}`,
+        TRACK_LAB_CONVEYOR_WIDTH - 0.56,
+        TRACK_LAB_CONVEYOR_SHELF_DEPTH,
+        mineLiftMaterials,
+      )
+    if (activeThemeId === JUNGLE_TEMPLE_THEME_ID)
+      decorateJungleTempleShelf(
+        shelf,
+        `${pieceId}-conveyor-shelf-${index + 1}`,
+        TRACK_LAB_CONVEYOR_WIDTH - 0.56,
+        TRACK_LAB_CONVEYOR_SHELF_DEPTH,
+        jungleTempleMaterials,
+      )
+    decoratePortalDerivedElevatorShelf(
+      shelf,
+      `${pieceId}-conveyor-shelf-${index + 1}`,
+      TRACK_LAB_CONVEYOR_WIDTH - 0.56,
+      TRACK_LAB_CONVEYOR_SHELF_DEPTH,
+      portalDerivedMaterials,
+      activeThemeId,
+    )
+    materials.captureBindings(shelf)
+  }
+  // Theme visibility metadata is assigned by the mesh configurators after the
+  // initial slot binding, so recapture the completed lift construction once.
+  materials.captureBindings(root)
+}
+
+function lengthUnitsFromParameters(parameters: JsonObject): number {
+  const value = parameters.lengthUnits
+  return typeof value === 'number' && Number.isFinite(value) ? value : 1
+}
+
+function gradeFromParameters(parameters: JsonObject): 'flat' | 'slope' | 'steep' {
+  return parameters.grade === 'flat' || parameters.grade === 'steep' ? parameters.grade : 'slope'
+}
+
+function conePatternFromParameters(parameters: JsonObject): 'classic' | 'dense' {
+  return parameters.pattern === 'classic' ? 'classic' : 'dense'
+}
+
+function reboundPatternFromParameters(parameters: JsonObject): ReboundPattern {
+  return parameters.pattern === 'zigzag' ? 'zigzag' : 'alternating'
+}
+
+function risingWallDensityFromParameters(parameters: JsonObject): RisingWallDensity {
+  return parameters.density === 'sparse' ? 'sparse' : 'dense'
+}
+
+function vector(value: TrackVector): THREE.Vector3 {
+  return new THREE.Vector3(...value)
+}