@marble.fun/track-catalog 3.0.0

package/src/pages/play/race/marble-race-engine.ts

@@ -0,0 +1,2652 @@
+import { prepareSceneShaders } from '../../../three/scene-shader-preparation'
+import { ShadowShaderPreparation } from '../../../three/shadow-shader-preparation'
+import { nextVisualFrameDeadline } from '../../../three/visual-frame-pacing'
+import { LowQualitySceneRenderer } from '../../../three/low-quality-scene-renderer'
+import { usesMobileRenderingBudget } from '../../../three/mobile-rendering-budget'
+import RAPIER from '@dimforge/rapier3d-deterministic-compat'
+import * as THREE from 'three'
+import { OrbitControls } from 'three/addons'
+import {
+  CURRENT_RACE_ENGINE_VERSION,
+  createPreparedRaceSimulation,
+  preparePhysicsTrack,
+  type DeterministicRaceSimulation,
+  type PreparedPhysicsTrack,
+  type RaceSimulationEvent,
+  type RaceSimulationSnapshot,
+} from '@marble.fun/physics-engine'
+
+import { SceneThemeController } from '../../../three/scene-theme-controller'
+import { configureSceneRenderer } from '../../../three/scene-lighting'
+import { resizeRendererDrawingBuffer } from '../../../three/renderer-resize'
+import { ThemeMaterialRegistry } from '../../../three/theme-material-registry'
+import { resolveTrackTheme } from '../../../three/theme-catalog'
+import { fluidSurfaceStyleFromId } from '../../../three/water-appearance'
+import { visualQualityPolicy, type VisualQualityPolicy } from '../../../three/visual-quality'
+import {
+  applyMarbleSimulationSnapshot,
+  captureMarblePhysicsTransform,
+  createMarbleEntity,
+  syncMarbleVisual,
+  updateMarbleTrail,
+  type RaceMarbleVisualStyle,
+} from './marble-entity'
+import type { MarbleEntity } from './marble-entity'
+import type { PhysicsDebugReport } from './physics-debug'
+import {
+  cameraZoomIsInward,
+  cameraZoomIsOutward,
+  raceCameraState,
+  RaceCameraReturnCurve,
+  translateFreeCameraRig,
+  type RaceCameraControl,
+  type RaceCameraSnapshot,
+  type RaceCameraState,
+  type RaceCameraView,
+} from './race-camera'
+import {
+  advanceCameraOrientation,
+  cameraPoseWithinTolerance,
+  RaceCameraDirector,
+  RaceCameraPackTracker,
+  retainCameraLeader,
+  smoothCameraTourProgress,
+  writeStableCameraGuideDirection,
+  writeLeadingPackFrame,
+  type LeadingPackFrame,
+  type RaceCameraDirectorState,
+} from './race-camera-director'
+import {
+  advanceCameraObstructionDistance,
+  CAMERA_MIN_TARGET_DISTANCE,
+  cameraObstructionProbeOffset,
+  resolveCameraObstructionDistance,
+} from './race-camera-obstruction'
+import { FINISH_COAST_TICKS } from './race-completion'
+import { createRaceTuning } from './race-configuration'
+import type { RaceMarbleFocusRenderer } from './race-marble-focus-renderer'
+import {
+  advanceRaceCountdown,
+  MAX_RACE_TIME_SCALE,
+  MIN_RACE_TIME_SCALE,
+  RACE_COUNTDOWN_SECONDS,
+  STANDARD_RACE_TIME_SCALE,
+  synchronizedRaceIntroState,
+} from './race-playback'
+import { RaceRollingAudio } from './race-rolling-audio'
+import { createRacePhysicsWorld, FIXED_TIMESTEP, initializeRacePhysics, MAX_RACE_TICKS } from './race-physics'
+import type { MarbleStanding, RaceConfiguration, RaceSnapshot, RaceTuning, RaceWinner } from './race-types'
+import { formatFingerprint, hashSeed } from './seeded-random'
+import { TrackCourse } from './track-course'
+import type { PortalPieceDefinition, TrackDefinition } from './track-definition'
+import { buildTrackWorld, type TrackWorld } from './track-world'
+import type { PortalTeleportEvent } from './track-mechanisms'
+import { bindMechanismPartObjects, RaceSimulationRenderer } from './race-simulation-renderer'
+import {
+  createCanonicalTrackAssembly,
+  type CanonicalTrackAssembly,
+  type OwnedCanonicalTrackAssembly,
+} from '../../track-lab/engine/canonical-track-assembly'
+import { createCameraTourPlan, sampleCameraTourPlan, type CameraTourPlan } from './race-camera-tour-planner'
+
+const SNAPSHOT_INTERVAL_TICKS = Math.max(1, Math.round(0.1 / FIXED_TIMESTEP))
+const TRAIL_INTERVAL_TICKS = Math.max(1, Math.round(0.05 / FIXED_TIMESTEP))
+const DIAGNOSTICS_INTERVAL_MS = 500
+const FRAME_TIMING_SAMPLE_COUNT = 240
+// At 120 Hz, ordinary 60 FPS presentation consumes two physics steps per
+// frame. Keep stalled-frame recovery bounded so mobile cannot enter a runaway
+// catch-up spiral.
+const MAX_PHYSICS_STEPS_PER_FRAME = 8
+const INITIAL_CATCH_UP_SLICE_MS = 6
+const DEFERRED_LAB_SHADOW_BATCH_TIMEOUT_MS = 5_000
+const CAMERA_PROGRESS_RESPONSE = 3.1
+const FOCUS_CAMERA_PROGRESS_RESPONSE = 2.4
+const CAMERA_FOV_RESPONSE = 3
+const CAMERA_COLLISION_RADIUS = 0.52
+const CAMERA_COLLISION_PREDICTION = 0.12
+const CAMERA_TARGET_HANDOFF_SECONDS = 0.72
+const PORTAL_REBASE_MINIMUM_HOLD_TICKS = Math.max(1, Math.round(0.25 / FIXED_TIMESTEP))
+const PORTAL_EVENT_ACTIVATION_TICKS = Math.max(1, Math.round(0.2 / FIXED_TIMESTEP))
+const PORTAL_EVENT_EXPIRY_TICKS = Math.max(1, Math.round(2 / FIXED_TIMESTEP))
+const CAMERA_STAGING_SETTLE_SECONDS = 0.28
+const CAMERA_STAGING_POSITION_TOLERANCE = 1.35
+const CAMERA_STAGING_TARGET_TOLERANCE = 0.85
+const CAMERA_STAGING_ANGLE_TOLERANCE = THREE.MathUtils.degToRad(4)
+
+function getInitialTimeScale(developmentMode: boolean): number {
+  if (!developmentMode) {
+    return STANDARD_RACE_TIME_SCALE
+  }
+
+  const requestedTimeScale = Number(
+    new URLSearchParams(window.location.search).get('raceSpeed') ?? STANDARD_RACE_TIME_SCALE,
+  )
+  return Number.isFinite(requestedTimeScale)
+    ? THREE.MathUtils.clamp(requestedTimeScale, MIN_RACE_TIME_SCALE, MAX_RACE_TIME_SCALE)
+    : STANDARD_RACE_TIME_SCALE
+}
+
+function responseAlpha(response: number, deltaSeconds: number): number {
+  return 1 - Math.exp(-response * deltaSeconds)
+}
+
+function yieldToBrowser(): Promise<void> {
+  const scheduler = (window as Window & { scheduler?: { yield?: () => Promise<void> } }).scheduler
+  return scheduler?.yield ? scheduler.yield() : new Promise(resolve => window.setTimeout(resolve, 0))
+}
+
+export interface RendererDiagnostics {
+  audio?: ReturnType<RaceRollingAudio['diagnostics']>
+  calls: number
+  triangles: number
+  geometries: number
+  textures: number
+  sceneMeshes: number
+  bodies: number
+  colliders: number
+  authoritativeBodies: number
+  authoritativeColliders: number
+  mirrorBodies: number
+  mirrorColliders: number
+  ccdBodies: number
+  sensors: number
+  fixedTimestep: number
+  timeScale: number
+  dpr: number
+  paused: boolean
+  cameraMode: RaceCameraState
+  cameraTargetSlotId?: string
+  cameraDistance: number
+  cameraDirector: {
+    state: RaceCameraDirectorState
+    subjectSlotId?: string
+    stateSeconds: number
+    packCount: number
+    packRadius: number
+    obstructed: boolean
+    probes: number
+    desiredDistance: number
+    resolvedDistance: number
+    linearSpeed: number
+    targetSpeed: number
+  }
+  cameraTour?: {
+    footprintWidth: number
+    footprintDepth: number
+    occupiedCells: number
+    routeDirection: string
+    routeLength: number
+    minimumClearance: number
+    validationAttempts: number
+    cruiseAltitude: number
+    pitchChanges: number
+    fallbackReason?: string
+  }
+  themeId: string
+  themeMaterials: number
+  themeWorldMeshes: number
+  themeInstancedMeshes: number
+  themeParticles: number
+  frameIntervalMs: number
+  physicsSteps: number
+  physicsBacklogSteps: number
+  catchUpSaturated: boolean
+  maximumPhysicsBacklogSteps: number
+  catchUpSaturationCount: number
+  frameTiming: {
+    samples: number
+    p50Ms: number
+    p95Ms: number
+    p99Ms: number
+    maximumMs: number
+    framesAbove16Ms: number
+  }
+}
+
+export interface RaceStartFrameTiming {
+  phase: RaceSnapshot['phase']
+  countdown: number
+  tick: number
+  timeMs: number
+  updateMs: number
+  renderMs?: number
+}
+
+export interface RaceStartupDiagnostics {
+  firstPhysicsStepMs?: number
+  startFrames?: RaceStartFrameTiming[]
+  physicsRuntimeInitializationMs: number
+  physicsTrackPreparationMs: number
+  physicsSimulationConstructionMs: number
+  visualQueryWorldCreationMs: number
+  physicsInitializationMs: number
+  trackColliderAttachmentMs: number
+  trackConstructionMs: number
+  trackRuntimeAssemblyMs: number
+  trackShadowBatchingMs: number
+  materialUploadMs: number
+  marbleConstructionMs: number
+  marbleAssetsMs: number
+  marbleGpuPreparationMs: number
+  initialCatchUpMs: number
+  initialCatchUpTicks: number
+  cameraPlanningMs: number
+  totalMs: number
+  reusedCanonicalAssembly: boolean
+  reusedPreparedSimulation: boolean
+  visualTrackConstructionMs: number
+}
+
+interface MarbleRaceTestHooks {
+  getSnapshot: () => RaceSnapshot
+  getRendererDiagnostics: () => RendererDiagnostics
+  getPhysicsDebugReport: () => PhysicsDebugReport | undefined
+  getMarbleRenderStates: () => Array<{
+    slotId: string
+    physicsPosition: readonly [number, number, number]
+    visualPosition: readonly [number, number, number]
+    finishedAtTick?: number
+  }>
+  setPaused: (paused: boolean) => void
+  setTimeScale: (timeScale: number) => void
+  followMarble: (slotId: string) => void
+  advanceTicks: (ticks: number) => RaceSnapshot
+}
+
+declare global {
+  interface Window {
+    __MARBLE_RACE_TEST_HOOKS__?: MarbleRaceTestHooks
+    __THREE_GAME_DIAGNOSTICS__?: RendererDiagnostics
+  }
+}
+
+export interface MarbleRaceEngineOptions {
+  container: HTMLElement
+  configuration: RaceConfiguration
+  surface?: {
+    scene: THREE.Scene
+    camera: THREE.PerspectiveCamera
+    renderer: THREE.WebGLRenderer
+    root: THREE.Group
+    materials: ThemeMaterialRegistry
+  }
+  track: TrackDefinition
+  marbleVisualStyle?: RaceMarbleVisualStyle
+  onSnapshot: (snapshot: RaceSnapshot) => void
+  onCameraChange?: (snapshot: RaceCameraSnapshot) => void
+  onRaceCue?: (cue: 'countdown' | 'start') => void
+  finishCoastTicks?: number
+  initialIntroElapsedMs?: () => number
+  initialSimulationElapsedMs?: () => number
+  beforeInitialSynchronization?: () => Promise<void>
+  introDurationSeconds?: number
+  preparedPhysicsTrack?: PreparedPhysicsTrack
+  preparedSimulation?: DeterministicRaceSimulation
+  rollingAudioGraphEnabled?: boolean
+  rollingAudioEnabled?: boolean
+  rollingAudioContext?: AudioContext
+  rollingAudioGain?: number
+  collisionAudioGain?: number
+  countdownSeconds?: number
+  introEnabled?: boolean
+  deferStaticShadowBatching?: boolean
+  canonicalAssembly?: CanonicalTrackAssembly
+  developmentMode?: boolean
+  visualQualityPolicy?: VisualQualityPolicy
+}
+
+function disposeMaterial(material: THREE.Material): void {
+  if (material.userData.themeRegistryManaged) return
+  const candidate = material as THREE.Material & { map?: THREE.Texture | null }
+  candidate.map?.dispose()
+  material.dispose()
+}
+
+function disposeObject(root: THREE.Object3D): void {
+  root.traverse(object => {
+    if (object instanceof THREE.Mesh || object instanceof THREE.Line || object instanceof THREE.Points) {
+      object.geometry.dispose()
+      const materials = Array.isArray(object.material) ? object.material : [object.material]
+      materials.forEach(disposeMaterial)
+    }
+
+    if (object instanceof THREE.Sprite) {
+      disposeMaterial(object.material)
+    }
+  })
+}
+
+export class MarbleRaceEngine {
+  private readonly container: HTMLElement
+  private readonly configuration: RaceConfiguration
+  private readonly onSnapshot: (snapshot: RaceSnapshot) => void
+  private readonly onCameraChange?: (snapshot: RaceCameraSnapshot) => void
+  private readonly onRaceCue?: (cue: 'countdown' | 'start') => void
+  private readonly track: TrackDefinition
+  private readonly course: TrackCourse
+  private readonly tuning: RaceTuning
+  private readonly scene: THREE.Scene
+  private readonly camera: THREE.PerspectiveCamera
+  private readonly renderer: THREE.WebGLRenderer
+  private readonly visualRoot: THREE.Group
+  private readonly sharedMaterials?: ThemeMaterialRegistry
+  private readonly marbleVisualStyle: RaceMarbleVisualStyle
+  private readonly ownsSurface: boolean
+  private readonly waterPieceIds: ReadonlySet<string>
+  private readonly developmentMode: boolean
+  private readonly diagnosticsEnabled: boolean
+  private readonly lowQualityRenderer = new LowQualitySceneRenderer()
+  private readonly shadowShaderPreparation = new ShadowShaderPreparation()
+  private visualQualityPolicy: VisualQualityPolicy
+  private readonly cameraPose
+  private readonly cameraBehindPose
+  private readonly cameraTargetPose
+  private readonly cameraDirector = new RaceCameraDirector()
+  private readonly cameraPackTracker = new RaceCameraPackTracker()
+  private readonly cameraTarget = new THREE.Vector3()
+  private readonly cinematicShadowFocusTarget = new THREE.Vector3()
+  private cameraTourPlan?: CameraTourPlan
+  private readonly cameraPackFrame: LeadingPackFrame = {
+    center: new THREE.Vector3(),
+    count: 0,
+    progress: 0,
+    radius: 0,
+  }
+  private readonly desiredCameraTarget = new THREE.Vector3()
+  private readonly desiredCameraPosition = new THREE.Vector3()
+  private readonly cameraTargetDelta = new THREE.Vector3()
+  private cameraPackDiscontinuityPending = false
+  private readonly cameraForward = new THREE.Vector3()
+  private readonly cameraGuideForward = new THREE.Vector3()
+  private readonly cameraDesiredGuideForward = new THREE.Vector3()
+  private readonly cameraGuideChord = new THREE.Vector3()
+  private readonly cameraRight = new THREE.Vector3()
+  private readonly cameraUp = new THREE.Vector3()
+  private readonly cameraWorldUp = new THREE.Vector3()
+  private readonly cameraSightLine = new THREE.Vector3()
+  private readonly cameraCollisionShape = new RAPIER.Ball(CAMERA_COLLISION_RADIUS)
+  private readonly cameraCollisionRotation = { x: 0, y: 0, z: 0, w: 1 }
+  private readonly cameraObstructionOrigin = new THREE.Vector3()
+  private readonly cameraLookMatrix = new THREE.Matrix4()
+  private readonly desiredCameraQuaternion = new THREE.Quaternion()
+  private readonly pendingPortalEvents = new Map<string, PortalTeleportEvent>()
+  private activePortalTransition?: PortalTeleportEvent
+  private controls?: OrbitControls
+  private marbleFocusRenderer?: RaceMarbleFocusRenderer
+  private marbleFocusRendererPromise?: Promise<void>
+  private readonly cameraReturnCurve = new RaceCameraReturnCurve()
+  private readonly cameraInteractionStartPosition = new THREE.Vector3()
+  private readonly cameraInteractionStartTarget = new THREE.Vector3()
+  private readonly cameraInteractionStartDirection = new THREE.Vector3()
+  private readonly cameraFreeFollowAnchor = new THREE.Vector3()
+  private readonly cameraPointerIds = new Set<number>()
+  private cameraInteractionActive = false
+  private cameraInteractionAllowsCombinedZoom = false
+  private cameraInteractionIsWheel = false
+  private cameraInteractionDistance = 0
+  private cameraLockedDistance = 0
+  private cameraFreeMinimumDistance = 0.35
+  private cameraFreeFov = 52
+  private cameraReturnLockPending = false
+  private cameraReturnNeedsControlsSync = false
+  private cameraControlsUpdating = false
+  private cameraSnapshotKey = ''
+  private focusSubjectLocked = false
+  private focusOrbitActive = false
+  private cameraTargetHandoffPending = false
+  private cameraTargetHandoffSeconds = CAMERA_TARGET_HANDOFF_SECONDS
+  private readonly cameraTargetHandoffOffset = new THREE.Vector3()
+  private cameraTargetSlotId?: string
+  private cameraLeaderSlotId?: string
+  private cameraView: RaceCameraView = 'race'
+  private cameraControl: RaceCameraControl = 'locked'
+  private cameraObstructed = false
+  private cameraProbeCount = 0
+  private cameraDesiredDistance = 0
+  private cameraResolvedDistance = 0
+  private desiredCameraFov = 52
+  private world?: RAPIER.World
+  private queryWorld?: RAPIER.World
+  private trackWorld?: TrackWorld
+  private simulation?: DeterministicRaceSimulation
+  private simulationRenderer?: RaceSimulationRenderer
+  private authoritativeSnapshot?: RaceSimulationSnapshot
+  private themeController?: SceneThemeController
+  private marbles: MarbleEntity[] = []
+  private readonly marblesBySlot = new Map<string, MarbleEntity>()
+  private readonly marbleIndexBySlot = new Map<string, number>()
+  private readonly rollingAudioWaterStates: boolean[] = []
+  private readonly rollingAudioGroundedStates: boolean[] = []
+  private resizeObserver?: ResizeObserver
+  private resizeFrame = 0
+  private animationFrame = 0
+  private previousFrameTime?: number
+  private nextVisualFrameTime = 0
+  private lastDiagnosticsWriteMs = Number.NEGATIVE_INFINITY
+  private accumulator = 0
+  private synchronizedInterpolationAlpha = 1
+  private frameIntervalMs = 0
+  private physicsStepsLastUpdate = 0
+  private physicsBacklogSteps = 0
+  private catchUpSaturated = false
+  private maximumPhysicsBacklogSteps = 0
+  private catchUpSaturationCount = 0
+  private readonly frameIntervals = new Float32Array(FRAME_TIMING_SAMPLE_COUNT)
+  private frameIntervalCursor = 0
+  private frameIntervalCount = 0
+  private timeScale: number
+  private countdownSecondsRemaining: number
+  private lastCountdownCue?: number
+  private raceStartCuePlayed = false
+  private simulationTick = 0
+  private cameraProgress = 0
+  private cameraTourElapsedSeconds = 0
+  private cameraStagingSettledSeconds = 0
+  private replayFingerprint: string
+  private winner?: RaceWinner
+  private allMarblesFinishedAtTick?: number
+  private phase: RaceSnapshot['phase'] = 'loading'
+  private worldReady = false
+  private readonly finishCoastTicks: number
+  private readonly initialIntroElapsedMs?: () => number
+  private readonly initialSimulationElapsedMs?: () => number
+  private readonly beforeInitialSynchronization?: () => Promise<void>
+  private readonly introDurationSeconds?: number
+  private readonly introEnabled: boolean
+  private suppressSnapshots = false
+  private initialCatchUpActive = false
+  private paused = false
+  private interactionEnabled = true
+  private readonly presentationMaterialStates = new Map<
+    THREE.Material,
+    { depthWrite: boolean; opacity: number; transparent: boolean }
+  >()
+  private disposed = false
+  private latestSnapshot: RaceSnapshot
+  private readonly rollingAudio?: RaceRollingAudio
+  private startFrameTiming?: RaceStartFrameTiming
+  private startupDiagnostics?: RaceStartupDiagnostics
+  private preparedPhysicsTrack?: PreparedPhysicsTrack
+  private preparedSimulation?: DeterministicRaceSimulation
+  private readonly deferStaticShadowBatching: boolean
+  private canonicalAssembly?: CanonicalTrackAssembly
+  private ownedCanonicalAssembly?: OwnedCanonicalTrackAssembly
+  private readonly preservesCanonicalAssembly: boolean
+  private readonly marbleRoot = new THREE.Group()
+
+  constructor(options: MarbleRaceEngineOptions) {
+    this.container = options.container
+    this.configuration = options.configuration
+    this.developmentMode = options.developmentMode === true
+    this.visualQualityPolicy = options.visualQualityPolicy ?? visualQualityPolicy('quality')
+    this.diagnosticsEnabled = this.developmentMode || new URLSearchParams(window.location.search).has('raceDiagnostics')
+    this.timeScale = getInitialTimeScale(this.developmentMode)
+    this.onSnapshot = options.onSnapshot
+    this.onCameraChange = options.onCameraChange
+    this.onRaceCue = options.onRaceCue
+    this.finishCoastTicks = options.finishCoastTicks ?? FINISH_COAST_TICKS
+    this.initialIntroElapsedMs = options.initialIntroElapsedMs
+    this.initialSimulationElapsedMs = options.initialSimulationElapsedMs
+    this.beforeInitialSynchronization = options.beforeInitialSynchronization
+    this.introDurationSeconds = options.introDurationSeconds
+    this.preparedPhysicsTrack = options.preparedPhysicsTrack
+    this.preparedSimulation = options.preparedSimulation
+    this.introEnabled = options.introEnabled ?? false
+    this.deferStaticShadowBatching = options.deferStaticShadowBatching === true
+    this.canonicalAssembly = options.canonicalAssembly
+    this.preservesCanonicalAssembly = options.canonicalAssembly !== undefined
+    this.countdownSecondsRemaining = THREE.MathUtils.clamp(
+      options.countdownSeconds ?? RACE_COUNTDOWN_SECONDS,
+      0,
+      RACE_COUNTDOWN_SECONDS,
+    )
+    this.ownsSurface = !options.surface
+    this.scene = options.surface?.scene ?? new THREE.Scene()
+    this.camera = options.surface?.camera ?? new THREE.PerspectiveCamera(52, 16 / 9, 0.1, 900)
+    this.renderer =
+      options.surface?.renderer ?? new THREE.WebGLRenderer({ antialias: true, powerPreference: 'high-performance' })
+    this.visualRoot = options.surface?.root ?? new THREE.Group()
+    this.sharedMaterials = options.surface?.materials
+    this.marbleVisualStyle = options.marbleVisualStyle ?? 'default'
+    if (!this.visualRoot.parent) this.scene.add(this.visualRoot)
+    this.marbleRoot.name = `${options.configuration.seed}-race-marbles`
+    // Portal destination images are cached. Exclude moving marbles so a
+    // capture can never leave a racer visibly frozen inside a doorway.
+    this.marbleRoot.userData.portalAuxiliaryEffect = true
+    this.visualRoot.add(this.marbleRoot)
+    this.track = options.track
+    this.waterPieceIds = new Set(
+      this.track.pieces
+        .filter(piece => fluidSurfaceStyleFromId(piece.appearance?.waterOverlayId ?? piece.appearance?.vortexWaterId))
+        .map(piece => piece.id),
+    )
+    this.course = new TrackCourse(this.track)
+    this.tuning = createRaceTuning(options.configuration, this.track)
+    this.replayFingerprint = formatFingerprint(hashSeed(this.tuning.simulationKey))
+    this.cameraPose = this.course.createPose()
+    this.cameraBehindPose = this.course.createPose()
+    this.cameraTargetPose = this.course.createPose()
+    this.latestSnapshot = {
+      phase: 'loading',
+      paused: false,
+      countdown: Math.ceil(this.countdownSecondsRemaining),
+      elapsedMs: 0,
+      simulationTick: 0,
+      replayFingerprint: this.replayFingerprint,
+      standings: [],
+    }
+    if (options.rollingAudioGraphEnabled !== false) {
+      this.rollingAudio = new RaceRollingAudio(
+        this.configuration.assignments.length,
+        options.rollingAudioEnabled,
+        options.rollingAudioGain,
+        options.collisionAudioGain,
+        {
+          water: this.waterPieceIds.size > 0,
+          portals: this.track.pieces.some(piece => piece.type === 'portal'),
+          rebounds: this.track.pieces.some(piece => piece.type === 'rebounds'),
+          risingWalls: this.track.pieces.some(piece => piece.type === 'rising-wall-forest'),
+          cones: this.track.pieces.some(piece => piece.type === 'peg-field' && piece.colliderShape !== 'cylinder'),
+          flippers: this.track.pieces.some(piece => piece.type === 'flipper-bank'),
+        },
+        options.rollingAudioContext,
+      )
+    }
+    this.emitCameraChange()
+  }
+
+  async start(): Promise<void> {
+    const startupStartedAt = performance.now()
+    let phaseStartedAt: number
+    const timings: RaceStartupDiagnostics = {
+      physicsRuntimeInitializationMs: 0,
+      physicsTrackPreparationMs: 0,
+      physicsSimulationConstructionMs: 0,
+      visualQueryWorldCreationMs: 0,
+      physicsInitializationMs: 0,
+      trackColliderAttachmentMs: 0,
+      trackConstructionMs: 0,
+      trackRuntimeAssemblyMs: 0,
+      trackShadowBatchingMs: 0,
+      materialUploadMs: 0,
+      marbleConstructionMs: 0,
+      marbleAssetsMs: 0,
+      marbleGpuPreparationMs: 0,
+      initialCatchUpMs: 0,
+      initialCatchUpTicks: 0,
+      cameraPlanningMs: 0,
+      totalMs: 0,
+      reusedCanonicalAssembly: this.canonicalAssembly !== undefined,
+      reusedPreparedSimulation: this.preparedSimulation !== undefined,
+      visualTrackConstructionMs: 0,
+    }
+    try {
+      const synchronizedElapsedBeforeWorldBuild = this.beforeInitialSynchronization
+        ? undefined
+        : this.initialSimulationElapsedMs?.()
+      if (
+        this.introEnabled &&
+        synchronizedElapsedBeforeWorldBuild !== undefined &&
+        synchronizedElapsedBeforeWorldBuild < 0
+      ) {
+        this.phase = 'touring'
+        this.beginCameraTour()
+        this.synchronizeCameraTour(synchronizedElapsedBeforeWorldBuild, this.initialIntroElapsedMs?.())
+        this.writeDefaultCameraPose()
+        this.applyImmediateCameraPose()
+        this.emitSnapshot(true)
+      }
+      this.configureControls()
+      phaseStartedAt = performance.now()
+      await initializeRacePhysics()
+      timings.physicsRuntimeInitializationMs = performance.now() - phaseStartedAt
+      const preparedSimulation = this.preparedSimulation
+      if (preparedSimulation) {
+        this.simulation = preparedSimulation
+        this.preparedSimulation = undefined
+      } else {
+        phaseStartedAt = performance.now()
+        const preparedPhysicsTrack = this.preparedPhysicsTrack ?? preparePhysicsTrack(this.track)
+        timings.physicsTrackPreparationMs = performance.now() - phaseStartedAt
+        phaseStartedAt = performance.now()
+        this.simulation = await createPreparedMarbleRaceSimulation(
+          this.configuration,
+          this.track,
+          preparedPhysicsTrack,
+          this.diagnosticsEnabled,
+        )
+        timings.physicsSimulationConstructionMs = performance.now() - phaseStartedAt
+      }
+      this.preparedPhysicsTrack = undefined
+      this.authoritativeSnapshot = this.simulation.snapshot()
+      this.queryWorld = this.simulation.queryWorld()
+      this.replayFingerprint = this.authoritativeSnapshot.replayFingerprint
+      timings.physicsInitializationMs =
+        timings.physicsRuntimeInitializationMs +
+        timings.physicsTrackPreparationMs +
+        timings.physicsSimulationConstructionMs
+
+      if (this.disposed) return
+
+      phaseStartedAt = performance.now()
+      this.world ??= createRacePhysicsWorld()
+      timings.visualQueryWorldCreationMs = performance.now() - phaseStartedAt
+      if (this.ownsSurface) {
+        this.configureRenderer()
+        this.themeController = new SceneThemeController(this.scene, this.renderer, this.container)
+        this.themeController.setVisualQualityPolicy(this.visualQualityPolicy)
+        const themeResolution = resolveTrackTheme(this.track.themeId ?? this.track.skin.id)
+        if (themeResolution.usedFallback) {
+          console.warn(`[marble-race] Unknown theme "${themeResolution.requestedId}", using Neutral Studio.`)
+        }
+        await this.themeController.applyTheme(themeResolution.theme)
+      }
+      if (!this.canonicalAssembly && this.track.sourceDocument) {
+        phaseStartedAt = performance.now()
+        const materials = this.sharedMaterials ?? this.themeController?.materials
+        if (!materials) throw new Error('Canonical track construction requires a material registry')
+        const assembly = createCanonicalTrackAssembly(this.track.sourceDocument, materials)
+        this.ownedCanonicalAssembly = assembly
+        this.canonicalAssembly = assembly
+        this.visualRoot.add(assembly.root)
+        timings.visualTrackConstructionMs = performance.now() - phaseStartedAt
+      }
+      phaseStartedAt = performance.now()
+      const trackConstructionStartedAt = phaseStartedAt
+      // Camera collision queries use the already-authoritative simulation
+      // world. Reattaching the same 20 MB of static trimeshes to the unstepped
+      // render mirror doubled startup work and retained duplicate WASM data.
+      const preparedCanonicalColliderHandles = this.canonicalAssembly ? new Map<string, number>() : undefined
+      timings.trackColliderAttachmentMs = performance.now() - phaseStartedAt
+      if (this.disposed) return
+      phaseStartedAt = performance.now()
+      this.trackWorld = buildTrackWorld(
+        this.visualRoot,
+        this.world,
+        this.track,
+        this.tuning,
+        this.sharedMaterials ?? this.themeController?.materials,
+        {
+          deferStaticShadowBatching: this.deferStaticShadowBatching,
+          canonicalAssembly: this.canonicalAssembly,
+          preparedCanonicalColliderHandles,
+          rankingSlotCount: this.configuration.marbleCount,
+          visualQualityPolicy: this.visualQualityPolicy,
+        },
+      )
+      timings.trackRuntimeAssemblyMs = performance.now() - phaseStartedAt
+      timings.trackConstructionMs = performance.now() - trackConstructionStartedAt
+      if (this.deferStaticShadowBatching) {
+        // Give the interactive race and its first rendered frame priority over
+        // this optional, yielded render optimization.
+        const prepareShadows = (): void => {
+          if (this.disposed) return
+          void this.trackWorld?.prepare().catch(error => {
+            console.warn('[marble-race] Static shadow batching could not be completed.', error)
+          })
+        }
+        const idleWindow = window as Window & {
+          requestIdleCallback?: (callback: () => void, options?: { timeout: number }) => number
+        }
+        if (idleWindow.requestIdleCallback) {
+          idleWindow.requestIdleCallback(prepareShadows, { timeout: DEFERRED_LAB_SHADOW_BATCH_TIMEOUT_MS })
+        } else {
+          window.setTimeout(prepareShadows, DEFERRED_LAB_SHADOW_BATCH_TIMEOUT_MS)
+        }
+      } else {
+        await this.trackWorld.prepare()
+      }
+      timings.trackShadowBatchingMs = Number(this.trackWorld.root.userData.staticShadowBatchingMs ?? 0)
+      phaseStartedAt = performance.now()
+      // Shared-surface Lab/race scenes already uploaded this registry while
+      // rendering the editor. Reinitialising every texture here adds hundreds
+      // of milliseconds without creating any new GPU resource.
+      if (!this.sharedMaterials) await this.themeController?.materials.preUpload(this.renderer)
+      timings.materialUploadMs = performance.now() - phaseStartedAt
+      if (this.disposed) return
+      phaseStartedAt = performance.now()
+      this.marbles = this.configuration.assignments.map((assignment, index) =>
+        createMarbleEntity(
+          this.marbleRoot,
+          this.world as RAPIER.World,
+          this.course,
+          assignment,
+          this.tuning.marbles[index]!,
+          this.marbleVisualStyle,
+        ),
+      )
+      this.marblesBySlot.clear()
+      this.marbleIndexBySlot.clear()
+      this.rollingAudioWaterStates.length = this.marbles.length
+      this.rollingAudioGroundedStates.length = this.marbles.length
+      for (let index = 0; index < this.marbles.length; index += 1) {
+        const marble = this.marbles[index]!
+        this.marblesBySlot.set(marble.assignment.slotId, marble)
+        this.marbleIndexBySlot.set(marble.assignment.slotId, index)
+        this.rollingAudioWaterStates[index] = false
+        this.rollingAudioGroundedStates[index] = false
+      }
+      if (!this.authoritativeSnapshot) throw new Error('Authoritative simulation snapshot is unavailable')
+      this.applyAuthoritativeSnapshot(this.authoritativeSnapshot)
+      this.simulationRenderer = new RaceSimulationRenderer({
+        marbleObjects: new Map(),
+        mechanismPartObjects: bindMechanismPartObjects(this.visualRoot, this.authoritativeSnapshot),
+      })
+      this.simulationRenderer.push(this.authoritativeSnapshot)
+      timings.marbleConstructionMs = performance.now() - phaseStartedAt
+      phaseStartedAt = performance.now()
+      await Promise.all(this.marbles.map(marble => marble.visualReady))
+      this.marbleRoot.traverse(object => {
+        if (object instanceof THREE.Mesh) object.castShadow = false
+      })
+      timings.marbleAssetsMs = performance.now() - phaseStartedAt
+      if (this.disposed) return
+      phaseStartedAt = performance.now()
+      const raceVisualTextures = new Set<THREE.Texture>()
+      this.marbleRoot.traverse(object => {
+        if (!(object instanceof THREE.Mesh || object instanceof THREE.Line || object instanceof THREE.Sprite)) return
+        const materials = Array.isArray(object.material) ? object.material : [object.material]
+        for (const material of materials) {
+          for (const value of Object.values(material)) {
+            if (value instanceof THREE.Texture) raceVisualTextures.add(value)
+          }
+        }
+      })
+      raceVisualTextures.forEach(texture => this.renderer.initTexture(texture))
+      // Final lighting can differ from betting-time/Lab preparation. Include
+      // the canonical track and marbles before anchoring the live race clock.
+      await prepareSceneShaders(
+        this.renderer,
+        this.ownsSurface ? this.scene : this.visualRoot,
+        this.camera,
+        this.scene,
+        {
+          visibleRoot: this.visualRoot,
+          shouldContinue: () => !this.disposed,
+          includeVisibleScene: true,
+        },
+      )
+      await this.shadowShaderPreparation.prepare(this.renderer, this.visualRoot, this.camera, this.scene)
+      timings.marbleGpuPreparationMs = performance.now() - phaseStartedAt
+      if (this.disposed) return
+      await this.beforeInitialSynchronization?.()
+      if (this.disposed) return
+      this.worldReady = true
+      const synchronized = this.initialSimulationElapsedMs !== undefined
+      const initialElapsedMs = this.initialSimulationElapsedMs?.() ?? 0
+      this.phase = this.introEnabled ? 'touring' : this.countdownSecondsRemaining > 0 ? 'countdown' : 'racing'
+      if (this.phase === 'countdown') {
+        if (synchronized && !this.introEnabled && initialElapsedMs < 0) this.synchronizeCountdown(initialElapsedMs)
+        else this.emitCountdownCue(Math.ceil(this.countdownSecondsRemaining))
+      }
+      if (synchronized && initialElapsedMs >= 0) {
+        this.countdownSecondsRemaining = 0
+        this.phase = 'racing'
+        this.suppressSnapshots = true
+        this.initialCatchUpActive = true
+        const catchUpStartedAt = performance.now()
+        const catchUpStartedAtTick = this.simulationTick
+        let sliceStartedAt = performance.now()
+        let catchUpSnapshot: RaceSimulationSnapshot | undefined
+        try {
+          while (this.phase === 'racing') {
+            // Re-read the authoritative clock after every yielded slice. A
+            // one-shot target is already stale by the time a long late-join
+            // catch-up finishes and visibly leaves the viewer behind.
+            const targetTicks = Math.min(
+              MAX_RACE_TICKS + this.finishCoastTicks,
+              Math.floor((this.initialSimulationElapsedMs?.() ?? initialElapsedMs) / (FIXED_TIMESTEP * 1_000)),
+            )
+            if (this.simulationTick >= targetTicks) break
+            // Late join only exposes the final synchronized pose. Advancing
+            // the authoritative core without materialising a snapshot on
+            // every hidden tick preserves the exact 120 Hz simulation while
+            // avoiding hundreds of temporary snapshots, mirror-body writes,
+            // course projections, and renderer interpolation updates.
+            // Let the final hidden tick capture contacts once. That keeps the
+            // next visible tick from treating every ongoing contact as a new
+            // collision (and playing a false impact sound) while still
+            // avoiding per-tick snapshots throughout the catch-up.
+            if (this.simulationTick + 1 >= targetTicks) {
+              catchUpSnapshot = this.simulation.step()
+            } else {
+              this.simulation.advance()
+              catchUpSnapshot = undefined
+            }
+            this.simulationTick = this.simulation.simulationTick
+            if (this.simulation.complete) {
+              this.completeRace()
+              break
+            }
+            if (performance.now() - sliceStartedAt >= INITIAL_CATCH_UP_SLICE_MS) {
+              await yieldToBrowser()
+              if (this.disposed) return
+              sliceStartedAt = performance.now()
+            }
+          }
+          const synchronizedSnapshot = catchUpSnapshot ?? this.simulation.snapshot()
+          this.applyAuthoritativeSnapshot(synchronizedSnapshot)
+          this.simulationRenderer?.push(synchronizedSnapshot)
+          this.simulation.drainEvents()
+        } finally {
+          this.initialCatchUpActive = false
+        }
+        timings.initialCatchUpMs = performance.now() - catchUpStartedAt
+        timings.initialCatchUpTicks = this.simulationTick - catchUpStartedAtTick
+        this.suppressSnapshots = false
+        this.marbles.forEach(captureMarblePhysicsTransform)
+        this.syncVisuals()
+      }
+      this.cameraProgress = THREE.MathUtils.clamp(this.cameraSubject()?.bestProgress ?? 0, 0, this.course.totalLength)
+      if (this.phase === 'touring') {
+        phaseStartedAt = performance.now()
+        if (!this.cameraTourPlan) this.beginCameraTour()
+        if (synchronized) {
+          this.synchronizeCameraTour(initialElapsedMs, this.initialIntroElapsedMs?.())
+          this.writeDefaultCameraPose()
+          this.applyImmediateCameraPose()
+        }
+        timings.cameraPlanningMs = performance.now() - phaseStartedAt
+      } else this.resetCamera()
+      this.emitSnapshot(true)
+      timings.totalMs = performance.now() - startupStartedAt
+      this.startupDiagnostics = timings
+      if (this.diagnosticsEnabled) {
+        this.installTestHooks()
+      }
+      if (this.ownsSurface) this.animationFrame = requestAnimationFrame(this.frame)
+    } catch (error) {
+      if (this.disposed) return
+      this.phase = 'error'
+      this.latestSnapshot = {
+        ...this.latestSnapshot,
+        phase: 'error',
+        error: error instanceof Error ? error.message : 'The race engine failed to start',
+      }
+      this.rollingAudio?.setEnabled(false)
+      this.onSnapshot(this.latestSnapshot)
+    }
+  }
+
+  getStartupDiagnostics(): RaceStartupDiagnostics | undefined {
+    return this.startupDiagnostics ? { ...this.startupDiagnostics } : undefined
+  }
+
+  dispose(): void {
+    this.lowQualityRenderer.dispose()
+    this.shadowShaderPreparation.dispose()
+    this.disposed = true
+    cancelAnimationFrame(this.animationFrame)
+    cancelAnimationFrame(this.resizeFrame)
+    this.resizeObserver?.disconnect()
+    this.controls?.removeEventListener('start', this.markCameraAsUserControlled)
+    this.controls?.removeEventListener('change', this.handleCameraControlsChange)
+    this.controls?.removeEventListener('end', this.finishCameraInteraction)
+    this.renderer.domElement.removeEventListener('pointerdown', this.handleCameraPointerDown, true)
+    this.renderer.domElement.removeEventListener('pointerup', this.handleCameraPointerUp, true)
+    this.renderer.domElement.removeEventListener('pointercancel', this.handleCameraPointerUp, true)
+    this.renderer.domElement.removeEventListener('wheel', this.handleCameraWheel, true)
+    this.controls?.dispose()
+    this.marbleFocusRenderer?.dispose()
+    this.trackWorld?.dispose()
+    this.themeController?.dispose()
+    this.rollingAudio?.dispose()
+    this.marbles.forEach(marble => marble.disposeVisual())
+    disposeObject(this.marbleRoot)
+    this.marbleRoot.removeFromParent()
+    if (!this.preservesCanonicalAssembly) {
+      this.ownedCanonicalAssembly?.dispose()
+      this.ownedCanonicalAssembly = undefined
+      disposeObject(this.visualRoot)
+      this.visualRoot.removeFromParent()
+    }
+    if (this.ownsSurface) {
+      this.renderer.setAnimationLoop(null)
+      this.renderer.domElement.remove()
+      this.renderer.dispose()
+    }
+    this.simulationRenderer?.clear()
+    this.queryWorld = undefined
+    this.simulation?.dispose()
+    this.simulation = undefined
+    this.preparedSimulation?.dispose()
+    this.preparedSimulation = undefined
+    this.world?.free()
+    this.world = undefined
+    this.preparedPhysicsTrack = undefined
+
+    if (window.__MARBLE_RACE_TEST_HOOKS__?.getSnapshot === this.getSnapshot) {
+      delete window.__MARBLE_RACE_TEST_HOOKS__
+      delete window.__THREE_GAME_DIAGNOSTICS__
+    }
+  }
+
+  resetCamera(): void {
+    this.cameraTargetSlotId = undefined
+    this.cameraLeaderSlotId = undefined
+    this.cameraView = 'race'
+    this.cameraControl = 'locked'
+    this.focusOrbitActive = false
+    this.cameraPackTracker.reset()
+    this.cameraPackTracker.update(this.marbles, this.cameraPackFrame, 0)
+    this.cameraPackDiscontinuityPending = false
+    this.cameraInteractionActive = false
+    this.cameraReturnLockPending = false
+    this.cameraReturnNeedsControlsSync = false
+    this.cameraReturnCurve.cancel()
+    this.beginCameraTargetHandoff()
+    this.writeDefaultCameraPose()
+    if (!this.ownsSurface) {
+      this.visualRoot.updateMatrixWorld(true)
+      this.visualRoot.localToWorld(this.desiredCameraPosition)
+      this.visualRoot.localToWorld(this.desiredCameraTarget)
+    }
+    if (this.phase !== 'racing' || !this.cameraDirector.isInitialized()) {
+      this.camera.position.copy(this.desiredCameraPosition)
+      this.cameraTarget.copy(this.desiredCameraTarget)
+      this.camera.fov = this.desiredCameraFov
+      this.camera.updateProjectionMatrix()
+      this.controls?.target.copy(this.cameraTarget)
+      this.camera.up.copy(THREE.Object3D.DEFAULT_UP)
+      this.camera.lookAt(this.cameraTarget)
+    }
+    this.cameraDirector.synchronize(this.camera.position, this.controls?.target ?? this.cameraTarget)
+    this.updateControlsEnabled()
+    this.emitCameraChange()
+  }
+
+  resetCameraAdjustment(): void {
+    if (this.cameraControl === 'locked') return
+    this.requestCameraReturn()
+  }
+
+  snapCameraToTourOpening(): void {
+    if (!this.introEnabled) return
+    this.writeCameraTourOpeningPose()
+    this.applyImmediateCameraPose()
+  }
+
+  private beginCameraTour(): void {
+    this.cameraControl = 'locked'
+    this.focusOrbitActive = false
+    this.cameraReturnCurve.cancel()
+    this.cameraReturnLockPending = false
+    this.cameraReturnNeedsControlsSync = false
+    this.cameraTourElapsedSeconds = 0
+    this.buildCameraTourPlan()
+    this.writeDefaultCameraPose()
+    this.applyImmediateCameraPose()
+    this.updateControlsEnabled()
+  }
+
+  private applyImmediateCameraPose(): void {
+    if (!this.ownsSurface) {
+      this.visualRoot.updateMatrixWorld(true)
+      this.visualRoot.localToWorld(this.desiredCameraPosition)
+      this.visualRoot.localToWorld(this.desiredCameraTarget)
+    }
+    // This happens while Test Run is still being prepared, so the first
+    // presented frame is already a deliberate finish-line composition.
+    this.camera.position.copy(this.desiredCameraPosition)
+    this.cameraTarget.copy(this.desiredCameraTarget)
+    this.controls?.target.copy(this.cameraTarget)
+    this.camera.fov = this.desiredCameraFov
+    this.camera.updateProjectionMatrix()
+    this.camera.up.copy(THREE.Object3D.DEFAULT_UP)
+    this.camera.lookAt(this.cameraTarget)
+    this.cameraDirector.synchronize(this.camera.position, this.cameraTarget)
+  }
+
+  private beginCameraStaging(): void {
+    this.cameraControl = 'locked'
+    this.focusOrbitActive = false
+    this.cameraReturnCurve.cancel()
+    this.cameraReturnLockPending = false
+    this.cameraReturnNeedsControlsSync = false
+    this.cameraStagingSettledSeconds = 0
+    this.writeDefaultCameraPose()
+    if (!this.ownsSurface) {
+      this.visualRoot.updateMatrixWorld(true)
+      this.visualRoot.localToWorld(this.desiredCameraPosition)
+      this.visualRoot.localToWorld(this.desiredCameraTarget)
+    }
+    // The tour's final pose is authored from this exact start-line pose. Keep
+    // the already-presented camera untouched so staging is a hold, not a
+    // second camera move disguised as obstruction recovery.
+    this.cameraTarget.copy(this.controls?.target ?? this.cameraTarget)
+    this.controls?.target.copy(this.cameraTarget)
+    this.cameraDirector.synchronize(this.camera.position, this.controls?.target ?? this.cameraTarget)
+    this.updateControlsEnabled()
+    this.emitCameraChange()
+  }
+
+  followMarble(slotId: string): void {
+    const marble = this.marbles.find(candidate => candidate.assignment.slotId === slotId)
+    if (!marble) {
+      return
+    }
+
+    this.cameraTargetSlotId = slotId
+    this.cameraProgress = marble.bestProgress
+    this.cameraView = 'focus'
+    this.cameraControl = 'locked'
+    this.focusOrbitActive = false
+    this.cameraPackDiscontinuityPending = false
+    void this.ensureMarbleFocusRenderer()
+    this.cameraInteractionActive = false
+    this.cameraReturnLockPending = false
+    this.cameraReturnNeedsControlsSync = false
+    this.cameraReturnCurve.cancel()
+    this.beginCameraTargetHandoff()
+    this.cameraDirector.synchronize(this.camera.position, this.controls?.target ?? this.cameraTarget)
+    this.updateControlsEnabled()
+    this.emitCameraChange()
+  }
+
+  private beginCameraTargetHandoff(): void {
+    this.cameraTargetHandoffPending = true
+    this.cameraTargetHandoffSeconds = 0
+  }
+
+  setPaused(paused: boolean): void {
+    if (this.disposed || this.paused === paused || this.phase === 'finished' || this.phase === 'error') {
+      return
+    }
+
+    this.paused = paused
+    this.emitSnapshot(true)
+  }
+
+  setInteractionEnabled(enabled: boolean): void {
+    if (enabled && !this.interactionEnabled) {
+      this.beginCameraTargetHandoff()
+      this.cameraDirector.synchronize(this.camera.position, this.controls?.target ?? this.cameraTarget)
+    }
+    this.interactionEnabled = enabled
+    this.updateControlsEnabled()
+  }
+
+  skipIntro(): void {
+    if (this.phase !== 'touring' && this.phase !== 'staging' && this.phase !== 'countdown') return
+
+    this.paused = false
+    this.phase = 'staging'
+    this.cameraProgress = THREE.MathUtils.clamp(this.track.spawnProgress, 0, this.course.totalLength)
+    this.writeDefaultCameraPose()
+    if (!this.ownsSurface) {
+      this.visualRoot.updateMatrixWorld(true)
+      this.visualRoot.localToWorld(this.desiredCameraPosition)
+      this.visualRoot.localToWorld(this.desiredCameraTarget)
+    }
+    this.cameraWorldUp.copy(THREE.Object3D.DEFAULT_UP)
+    this.camera.position.copy(this.desiredCameraPosition)
+    this.cameraTarget.copy(this.desiredCameraTarget)
+    this.controls?.target.copy(this.cameraTarget)
+    this.camera.fov = this.desiredCameraFov
+    this.camera.updateProjectionMatrix()
+    this.camera.up.copy(THREE.Object3D.DEFAULT_UP)
+    this.camera.lookAt(this.cameraTarget)
+    this.cameraDirector.synchronize(this.camera.position, this.cameraTarget)
+    this.countdownSecondsRemaining = 0
+    this.accumulator = 0
+    this.phase = 'racing'
+    this.updateControlsEnabled()
+    this.emitRaceStartCue()
+    this.emitSnapshot(true)
+  }
+
+  setPresentationProgress(progress: number): void {
+    const opacity = THREE.MathUtils.smoothstep(THREE.MathUtils.clamp(progress, 0, 1), 0, 1)
+    this.visualRoot.visible = opacity > 0.002
+    this.visualRoot.traverse(object => {
+      if (
+        !(
+          object instanceof THREE.Mesh ||
+          object instanceof THREE.Line ||
+          object instanceof THREE.Points ||
+          object instanceof THREE.Sprite
+        ) ||
+        !object.material
+      ) {
+        return
+      }
+      const materials = Array.isArray(object.material) ? object.material : [object.material]
+      for (const material of materials) {
+        let state = this.presentationMaterialStates.get(material)
+        if (!state) {
+          const themeOpacity = material.userData.themeBaseOpacity
+          const themeTransparent = material.userData.themeBaseTransparent
+          const themeDepthWrite = material.userData.themeBaseDepthWrite
+          state = {
+            depthWrite: typeof themeDepthWrite === 'boolean' ? themeDepthWrite : material.depthWrite,
+            opacity: typeof themeOpacity === 'number' ? themeOpacity : material.opacity,
+            transparent: typeof themeTransparent === 'boolean' ? themeTransparent : material.transparent,
+          }
+          this.presentationMaterialStates.set(material, state)
+        }
+        const fading = opacity < 0.999
+        const transparent = state.transparent || fading
+        if (material.transparent !== transparent) {
+          material.transparent = transparent
+          material.needsUpdate = true
+        }
+        material.depthWrite = fading ? false : state.depthWrite
+        material.opacity = state.opacity * opacity
+      }
+    })
+  }
+
+  togglePause(): void {
+    this.setPaused(!this.paused)
+  }
+
+  setTimeScale(timeScale: number): void {
+    if (this.disposed || !Number.isFinite(timeScale)) return
+    this.timeScale = THREE.MathUtils.clamp(timeScale, MIN_RACE_TIME_SCALE, MAX_RACE_TIME_SCALE)
+  }
+
+  setVisualQualityPolicy(policy: VisualQualityPolicy): void {
+    if (this.disposed || this.visualQualityPolicy === policy) return
+    this.visualQualityPolicy = policy
+    if (this.ownsSurface) this.renderer.domElement.dataset.visualQuality = policy.tier
+    this.nextVisualFrameTime = 0
+    this.trackWorld?.setVisualQualityPolicy(policy)
+    this.themeController?.setVisualQualityPolicy(policy)
+    if (this.ownsSurface) this.resize()
+  }
+
+  setRollingAudioEnabled(enabled: boolean): void {
+    this.rollingAudio?.setEnabled(enabled)
+  }
+
+  private configureRenderer(): void {
+    configureSceneRenderer(this.renderer)
+    this.renderer.domElement.dataset.visualQuality = this.visualQualityPolicy.tier
+    this.renderer.domElement.className = 'race-canvas block size-full touch-none transition-opacity duration-500'
+    this.renderer.domElement.setAttribute('aria-label', 'Deterministic 3D marble race')
+    this.container.appendChild(this.renderer.domElement)
+
+    this.resizeObserver = new ResizeObserver(this.scheduleResize)
+    this.resizeObserver.observe(this.container)
+    this.resize()
+  }
+
+  private configureControls(): void {
+    this.controls = new OrbitControls(this.camera, this.renderer.domElement)
+    this.controls.enableDamping = true
+    this.controls.dampingFactor = 0.08
+    this.controls.enablePan = false
+    this.controls.rotateSpeed = 0.8
+    this.controls.panSpeed = 0.72
+    this.controls.zoomSpeed = 1
+    this.cameraFreeMinimumDistance = this.ownsSurface ? 4.5 : 0.35
+    this.controls.minDistance = this.cameraFreeMinimumDistance
+    this.controls.maxDistance = this.ownsSurface ? 280 : 28
+    this.controls.minPolarAngle = 0.16
+    this.controls.maxPolarAngle = Math.PI * 0.49
+    this.controls.touches.ONE = THREE.TOUCH.ROTATE
+    this.controls.touches.TWO = THREE.TOUCH.DOLLY_ROTATE
+    this.updateControlsEnabled()
+    this.controls.addEventListener('start', this.markCameraAsUserControlled)
+    this.controls.addEventListener('change', this.handleCameraControlsChange)
+    this.controls.addEventListener('end', this.finishCameraInteraction)
+    this.renderer.domElement.addEventListener('pointerdown', this.handleCameraPointerDown, true)
+    this.renderer.domElement.addEventListener('pointerup', this.handleCameraPointerUp, true)
+    this.renderer.domElement.addEventListener('pointercancel', this.handleCameraPointerUp, true)
+    this.renderer.domElement.addEventListener('wheel', this.handleCameraWheel, { capture: true, passive: true })
+  }
+
+  private updateControlsEnabled(): void {
+    if (this.controls) {
+      this.controls.enabled =
+        this.interactionEnabled &&
+        this.phase !== 'touring' &&
+        this.phase !== 'staging' &&
+        this.phase !== 'countdown'
+    }
+  }
+
+  private readonly resize = (): void => {
+    const width = Math.max(1, this.container.clientWidth)
+    const height = Math.max(1, this.container.clientHeight)
+    const dpr = Math.min(
+      window.devicePixelRatio || 1,
+      (usesMobileRenderingBudget(width) ? 1.2 : 1.5) * this.visualQualityPolicy.pixelRatioScale,
+    )
+    this.camera.aspect = width / height
+    this.camera.updateProjectionMatrix()
+    if (resizeRendererDrawingBuffer(this.renderer, width, height, dpr)) {
+      this.lowQualityRenderer.render(this.renderer, this.scene, this.camera, this.visualQualityPolicy)
+    }
+  }
+
+  private readonly scheduleResize = (): void => {
+    if (this.resizeFrame !== 0 || this.disposed) return
+    this.resizeFrame = requestAnimationFrame(() => {
+      this.resizeFrame = 0
+      this.resize()
+    })
+  }
+
+  private readonly frame = (time: number): void => {
+    if (this.disposed) {
+      return
+    }
+    this.animationFrame = requestAnimationFrame(this.frame)
+    const nextFrame = nextVisualFrameDeadline(
+      time,
+      this.nextVisualFrameTime,
+      this.visualQualityPolicy.visualFramesPerSecond,
+    )
+    if (nextFrame === undefined) return
+    this.nextVisualFrameTime = nextFrame
+
+    try {
+      const rawDeltaSeconds = this.previousFrameTime ? (time - this.previousFrameTime) / 1_000 : 0
+      const deltaSeconds = Math.min(rawDeltaSeconds, 0.1)
+      this.frameIntervalMs = rawDeltaSeconds * 1_000
+      if (this.frameIntervalMs > 0) {
+        this.frameIntervals[this.frameIntervalCursor] = this.frameIntervalMs
+        this.frameIntervalCursor = (this.frameIntervalCursor + 1) % this.frameIntervals.length
+        this.frameIntervalCount = Math.min(this.frameIntervalCount + 1, this.frameIntervals.length)
+      }
+      this.previousFrameTime = time
+      this.update(deltaSeconds)
+      this.prepareRender()
+      this.render(deltaSeconds)
+      if (this.diagnosticsEnabled && time - this.lastDiagnosticsWriteMs >= DIAGNOSTICS_INTERVAL_MS) {
+        const diagnostics = this.getRendererDiagnostics()
+        window.__THREE_GAME_DIAGNOSTICS__ = diagnostics
+        this.renderer.domElement.dataset.diagnostics = JSON.stringify(diagnostics)
+        this.lastDiagnosticsWriteMs = time
+      }
+    } catch (error) {
+      cancelAnimationFrame(this.animationFrame)
+      this.animationFrame = 0
+      this.phase = 'error'
+      this.latestSnapshot = {
+        ...this.latestSnapshot,
+        phase: 'error',
+        error: error instanceof Error ? error.message : 'The simulation stopped unexpectedly',
+      }
+      this.onSnapshot(this.latestSnapshot)
+    }
+  }
+
+  // Loading and late-join catch-up intentionally expose no world frame yet.
+  // Avoid allocating/updating portal render targets behind the cover while
+  // the main course and Rapier world already hold the startup memory peak.
+  prepareRender(): void {
+    if (this.disposed || this.phase === 'loading' || this.initialCatchUpActive) return
+    this.trackWorld?.prepareRender(this.renderer, this.scene, this.camera)
+  }
+
+  render(deltaSeconds = 1 / 60): void {
+    const timing = this.startFrameTiming
+    if (!timing) return this.renderFrame(deltaSeconds)
+    const startedAt = performance.now()
+    try {
+      this.renderFrame(deltaSeconds)
+    } finally {
+      timing.renderMs = performance.now() - startedAt
+      this.startFrameTiming = undefined
+    }
+  }
+
+  private renderFrame(deltaSeconds: number): void {
+    if (this.disposed || this.initialCatchUpActive || !Number.isFinite(deltaSeconds)) return
+    if (
+      this.visualQualityPolicy.tier !== 'low' &&
+      this.cameraView === 'focus' &&
+      this.cameraControl === 'locked' &&
+      this.marbleFocusRenderer
+    ) {
+      this.marbleFocusRenderer.render(this.renderer, this.scene, this.camera, this.cameraFocusTarget())
+      return
+    }
+    if (this.visualQualityPolicy.tier !== 'low' && this.cameraView === 'focus') void this.ensureMarbleFocusRenderer()
+    this.lowQualityRenderer.render(this.renderer, this.scene, this.camera, this.visualQualityPolicy)
+  }
+
+  private ensureMarbleFocusRenderer(): Promise<void> {
+    if (this.marbleFocusRenderer) return Promise.resolve()
+    if (this.marbleFocusRendererPromise) return this.marbleFocusRendererPromise
+    this.marbleFocusRendererPromise = import('./race-marble-focus-renderer')
+      .then(({ RaceMarbleFocusRenderer }) => {
+        if (this.disposed) return
+        this.marbleFocusRenderer = new RaceMarbleFocusRenderer()
+      })
+      .catch(error => {
+        console.warn('[marble-race] Marble focus could not be initialized.', error)
+      })
+      .finally(() => {
+        this.marbleFocusRendererPromise = undefined
+      })
+    return this.marbleFocusRendererPromise
+  }
+
+  update(deltaSeconds: number): void {
+    if (this.disposed || this.initialCatchUpActive) return
+    // Bounded diagnostics around release expose first-use work without
+    // changing the countdown, physics, or render ordering.
+    const diagnostics = this.startupDiagnostics
+    const capture =
+      this.diagnosticsEnabled &&
+      diagnostics &&
+      ((this.phase === 'countdown' && this.countdownSecondsRemaining <= 1.2) ||
+        (this.phase === 'racing' && this.simulationTick < 120))
+    if (!capture) return this.updateFrame(deltaSeconds)
+    const frames = (diagnostics.startFrames ??= [])
+    if (frames.length >= 180) return this.updateFrame(deltaSeconds)
+    const timing: RaceStartFrameTiming = {
+      phase: this.phase,
+      countdown: this.countdownSecondsRemaining,
+      tick: this.simulationTick,
+      timeMs: performance.now(),
+      updateMs: 0,
+    }
+    try {
+      this.updateFrame(deltaSeconds)
+    } finally {
+      timing.updateMs = performance.now() - timing.timeMs
+      frames.push(timing)
+      this.startFrameTiming = timing
+    }
+  }
+
+  private updateFrame(deltaSeconds: number): void {
+    let physicsStepsRemaining = MAX_PHYSICS_STEPS_PER_FRAME
+    let synchronizedBacklogTicks = 0
+    // A shared Lab Test Run can be rendered while its world is still being
+    // prepared. Keep the deliberately snapped opening composition untouched;
+    // the normal race camera has no subject yet and would otherwise drift
+    // toward its empty-course fallback before the tour begins.
+    if (this.phase === 'loading') {
+      this.recordPhysicsWork(physicsStepsRemaining, synchronizedBacklogTicks)
+      this.syncVisuals()
+      this.themeController?.update(deltaSeconds, this.camera, false, this.shadowFocusTarget())
+      this.updateRollingAudio(deltaSeconds)
+      return
+    }
+    const synchronizedElapsedMs = this.initialSimulationElapsedMs?.()
+    if (synchronizedElapsedMs !== undefined && (this.phase === 'touring' || this.phase === 'countdown')) {
+      if (this.introEnabled) this.synchronizeCameraTour(synchronizedElapsedMs, this.initialIntroElapsedMs?.())
+      else this.synchronizeCountdown(synchronizedElapsedMs)
+      if (synchronizedElapsedMs >= 0) this.finishCameraTour()
+    }
+    if (!this.worldReady) {
+      this.recordPhysicsWork(physicsStepsRemaining, synchronizedBacklogTicks)
+      this.syncVisuals()
+      this.updateCamera(deltaSeconds)
+      this.updateRollingAudio(deltaSeconds)
+      return
+    }
+    if (synchronizedElapsedMs !== undefined && synchronizedElapsedMs < 0) {
+      this.recordPhysicsWork(physicsStepsRemaining, synchronizedBacklogTicks)
+      this.syncVisuals()
+      this.updateCamera(deltaSeconds)
+      this.themeController?.update(deltaSeconds, this.camera, false, this.shadowFocusTarget())
+      this.updateRollingAudio(deltaSeconds)
+      return
+    }
+    if (synchronizedElapsedMs !== undefined && this.phase === 'racing') {
+      const exactTargetTick = synchronizedElapsedMs / (FIXED_TIMESTEP * 1_000)
+      const targetTick = Math.min(MAX_RACE_TICKS + this.finishCoastTicks, Math.floor(exactTargetTick))
+      this.synchronizedInterpolationAlpha = THREE.MathUtils.clamp(exactTargetTick - targetTick, 0, 1)
+      if (targetTick > this.simulationTick) {
+        this.suppressSnapshots = true
+        while (this.simulationTick < targetTick && this.phase === 'racing' && physicsStepsRemaining > 0) {
+          this.fixedStep()
+          physicsStepsRemaining -= 1
+        }
+        this.suppressSnapshots = false
+        synchronizedBacklogTicks = Math.max(0, targetTick - this.simulationTick)
+      }
+    }
+    if (this.phase === 'countdown') {
+      const overlappingTour =
+        this.cameraTourPlan !== undefined && this.cameraTourElapsedSeconds < this.cameraTourPlan.durationSeconds
+      const tourComplete = overlappingTour && !this.paused ? this.advanceCameraTour(deltaSeconds) : false
+      if (!overlappingTour && !this.paused) this.advanceCountdown(deltaSeconds)
+      this.recordPhysicsWork(physicsStepsRemaining, synchronizedBacklogTicks)
+      this.syncVisuals()
+      this.updateCamera(deltaSeconds)
+      if (tourComplete) this.finishCameraTour()
+      this.themeController?.update(deltaSeconds, this.camera, false, this.shadowFocusTarget())
+      this.updateRollingAudio(deltaSeconds)
+      return
+    }
+    if (this.phase === 'touring') {
+      const tourComplete = !this.paused && this.advanceCameraTour(deltaSeconds)
+      this.recordPhysicsWork(physicsStepsRemaining, synchronizedBacklogTicks)
+      this.syncVisuals()
+      this.updateCamera(deltaSeconds)
+      if (tourComplete) this.finishCameraTour()
+      this.themeController?.update(deltaSeconds, this.camera, false, this.shadowFocusTarget())
+      this.updateRollingAudio(deltaSeconds)
+      return
+    }
+    if (this.phase === 'staging') {
+      this.recordPhysicsWork(physicsStepsRemaining, synchronizedBacklogTicks)
+      this.syncVisuals()
+      this.updateCamera(deltaSeconds)
+      this.advanceCameraStaging(deltaSeconds)
+      this.themeController?.update(deltaSeconds, this.camera, false, this.shadowFocusTarget())
+      this.updateRollingAudio(deltaSeconds)
+      return
+    }
+    // Shared-surface Test Runs are inserted into the lobby render loop before
+    // their async world/material setup has finished. Never let that render
+    // loop advance mechanisms (or newly-created marbles) behind the loading
+    // screen: the first physics tick must be the same tick in rendered and
+    // headless deterministic simulations.
+    if (!this.paused && this.phase === 'racing') {
+      this.accumulator += Math.min(deltaSeconds, 0.1) * this.timeScale
+    }
+    while (!this.paused && this.accumulator >= FIXED_TIMESTEP && this.phase === 'racing' && physicsStepsRemaining > 0) {
+      this.fixedStep()
+      this.accumulator -= FIXED_TIMESTEP
+      physicsStepsRemaining -= 1
+    }
+    this.recordPhysicsWork(physicsStepsRemaining, synchronizedBacklogTicks)
+    this.syncVisuals()
+    this.updateCamera(deltaSeconds)
+    this.themeController?.update(deltaSeconds, this.camera, false, this.shadowFocusTarget())
+    this.updateRollingAudio(deltaSeconds)
+  }
+
+  private recordPhysicsWork(physicsStepsRemaining: number, synchronizedBacklogTicks: number): void {
+    this.physicsStepsLastUpdate = MAX_PHYSICS_STEPS_PER_FRAME - physicsStepsRemaining
+    this.physicsBacklogSteps = Math.max(
+      synchronizedBacklogTicks,
+      Math.max(0, Math.floor(this.accumulator / FIXED_TIMESTEP)),
+    )
+    this.catchUpSaturated = physicsStepsRemaining === 0 && this.physicsBacklogSteps > 0
+    this.maximumPhysicsBacklogSteps = Math.max(this.maximumPhysicsBacklogSteps, this.physicsBacklogSteps)
+    if (this.catchUpSaturated) this.catchUpSaturationCount += 1
+  }
+
+  private updateRollingAudio(deltaSeconds: number): void {
+    if (!this.rollingAudio) return
+    for (let index = 0; index < this.marbles.length; index += 1) {
+      const marble = this.marbles[index]!
+      this.rollingAudioWaterStates[index] = this.waterPieceIds.has(
+        marble.projection.sampleIndex >= 0
+          ? (this.course.projectionSamples[marble.projection.sampleIndex]?.pieceId ?? '')
+          : '',
+      )
+    }
+    this.rollingAudio.update(
+      deltaSeconds,
+      this.phase === 'racing' && !this.paused,
+      this.world,
+      this.marbles,
+      this.visualRoot,
+      this.camera,
+      this.rollingAudioWaterStates,
+      this.rollingAudioGroundedStates,
+    )
+  }
+
+  cameraFocusTarget(): THREE.Vector3 {
+    return this.controls?.target ?? this.cameraTarget
+  }
+
+  shadowFocusTarget(): THREE.Vector3 {
+    const cinematic = this.phase === 'touring' || this.phase === 'staging' || this.phase === 'countdown'
+    if (!cinematic || !this.cameraTourPlan) return this.cameraFocusTarget()
+
+    // Keep the directional shadow projection fixed at the start line while
+    // the presentation camera corkscrews around the course. Following the
+    // moving tour target forces full shadow-map redraws at spatial thresholds,
+    // which show up as repeatable mobile hitches. The endpoint is also the
+    // first racing focus, so the handoff does not require another redraw.
+    this.cinematicShadowFocusTarget.fromArray(this.cameraTourPlan.startPose.target)
+    if (!this.ownsSurface) {
+      this.visualRoot.updateWorldMatrix(true, false)
+      this.visualRoot.localToWorld(this.cinematicShadowFocusTarget)
+    }
+    return this.cinematicShadowFocusTarget
+  }
+
+  private fixedStep(): void {
+    if (!this.simulation) return
+
+    const firstStepStartedAt = this.simulationTick === 0 && this.diagnosticsEnabled ? performance.now() : undefined
+    const snapshot = this.simulation.step()
+    if (firstStepStartedAt !== undefined && this.startupDiagnostics) {
+      this.startupDiagnostics.firstPhysicsStepMs = performance.now() - firstStepStartedAt
+    }
+    this.applyAuthoritativeSnapshot(snapshot)
+    this.simulationRenderer?.push(snapshot)
+    this.processAuthoritativeEvents(this.simulation.drainEvents())
+
+    if (!this.initialCatchUpActive && this.simulationTick % TRAIL_INTERVAL_TICKS === 0) {
+      this.marbles.forEach(updateMarbleTrail)
+    }
+
+    if (this.simulation.complete) this.completeRace()
+
+    if (
+      !this.initialCatchUpActive &&
+      (this.simulationTick % SNAPSHOT_INTERVAL_TICKS === 0 || this.phase === 'finished')
+    ) {
+      this.emitSnapshot(this.phase === 'finished')
+    }
+  }
+
+  private applyAuthoritativeSnapshot(snapshot: RaceSimulationSnapshot): void {
+    this.authoritativeSnapshot = snapshot
+    this.simulationTick = snapshot.simulationTick
+    this.replayFingerprint = snapshot.replayFingerprint
+    for (const marbleSnapshot of snapshot.marbles) {
+      const marble = this.marblesBySlot.get(marbleSnapshot.slotId)
+      if (!marble) continue
+      const marbleIndex = this.marbleIndexBySlot.get(marbleSnapshot.slotId)
+      if (marbleIndex !== undefined) this.rollingAudioGroundedStates[marbleIndex] = marbleSnapshot.grounded
+      applyMarbleSimulationSnapshot(marble, marbleSnapshot, this.course, !this.initialCatchUpActive)
+    }
+  }
+
+  private processAuthoritativeEvents(events: readonly RaceSimulationEvent[]): void {
+    if (this.initialCatchUpActive || this.suppressSnapshots || events.length === 0) return
+    const specializedContacts = new Set<string>()
+    for (const event of events) {
+      if (event.type === 'collision' && event.mechanismId) {
+        specializedContacts.add(`${event.tick}:${event.slotId}`)
+      }
+    }
+    for (const event of events) {
+      if (event.type === 'portal-entered') {
+        const position = new THREE.Vector3(...event.position)
+        const portal = this.track.pieces.find(
+          (piece): piece is PortalPieceDefinition => piece.type === 'portal' && piece.id === event.portalId,
+        )
+        if (!portal) continue
+        this.rollingAudio?.queuePortalTeleport(position)
+        this.pendingPortalEvents.set(event.slotId, {
+          slotId: event.slotId,
+          portalId: event.portalId,
+          tick: event.tick,
+          entryPosition: new THREE.Vector3(...portal.entry),
+          exitPosition: position,
+          exitDirection: new THREE.Vector3(...portal.exitDirection).normalize(),
+        })
+        continue
+      }
+      if (event.type !== 'collision') continue
+      const position = new THREE.Vector3(...event.position)
+      if (!event.mechanismId) {
+        if (!specializedContacts.has(`${event.tick}:${event.slotId}`)) {
+          this.rollingAudio?.queueCollisionImpact(event.impulse, position)
+        }
+        continue
+      }
+      const mechanism = this.track.pieces.find(piece => piece.id === event.mechanismId)
+      switch (mechanism?.type) {
+        case 'rebounds':
+          this.rollingAudio?.queueReboundHit(position)
+          break
+        case 'rising-wall-forest':
+          this.rollingAudio?.queueRisingWallContact(position)
+          break
+        case 'peg-field':
+          if (mechanism.colliderShape !== 'cylinder') this.rollingAudio?.queueConeContact(position)
+          else this.rollingAudio?.queueCollisionImpact(event.impulse, position)
+          break
+        case 'flipper-bank':
+          this.rollingAudio?.queueFlipperAcceleratingHit(position)
+          break
+      }
+    }
+  }
+
+  private advanceCountdown(deltaSeconds: number): void {
+    const previousValue = Math.ceil(this.countdownSecondsRemaining)
+    this.countdownSecondsRemaining = advanceRaceCountdown(this.countdownSecondsRemaining, deltaSeconds)
+    const nextValue = Math.ceil(this.countdownSecondsRemaining)
+    if (this.countdownSecondsRemaining === 0) {
+      this.phase = 'racing'
+      this.accumulator = 0
+      this.updateControlsEnabled()
+      this.emitRaceStartCue()
+    }
+    if (nextValue !== previousValue) {
+      if (nextValue > 0) this.emitCountdownCue(nextValue)
+      this.emitSnapshot(this.phase === 'racing')
+    }
+  }
+
+  private advanceCameraStaging(deltaSeconds: number): void {
+    const safeDelta = THREE.MathUtils.clamp(deltaSeconds, 0, 0.1)
+    const renderedTarget = this.controls?.target ?? this.cameraTarget
+    this.cameraLookMatrix.lookAt(this.camera.position, renderedTarget, this.cameraWorldUp)
+    this.desiredCameraQuaternion.setFromRotationMatrix(this.cameraLookMatrix)
+    const settled = cameraPoseWithinTolerance(
+      this.camera.position,
+      this.desiredCameraPosition,
+      renderedTarget,
+      this.desiredCameraTarget,
+      this.camera.quaternion,
+      this.desiredCameraQuaternion,
+      CAMERA_STAGING_POSITION_TOLERANCE,
+      CAMERA_STAGING_TARGET_TOLERANCE,
+      CAMERA_STAGING_ANGLE_TOLERANCE,
+    )
+    this.cameraStagingSettledSeconds = settled ? this.cameraStagingSettledSeconds + safeDelta : 0
+    if (this.cameraStagingSettledSeconds < CAMERA_STAGING_SETTLE_SECONDS) return
+    this.phase = 'countdown'
+    this.accumulator = 0
+    this.updateControlsEnabled()
+    this.emitCountdownCue(Math.ceil(this.countdownSecondsRemaining))
+    this.emitSnapshot(true)
+  }
+
+  private advanceCameraTour(deltaSeconds: number): boolean {
+    const durationSeconds = this.cameraTourPlan?.durationSeconds ?? 6
+    const previousCountdown = Math.ceil(this.countdownSecondsRemaining)
+    this.cameraTourElapsedSeconds = Math.min(
+      durationSeconds,
+      this.cameraTourElapsedSeconds + THREE.MathUtils.clamp(deltaSeconds, 0, 0.1),
+    )
+    const remainingTourSeconds = Math.max(0, durationSeconds - this.cameraTourElapsedSeconds)
+    if (
+      this.phase === 'touring' &&
+      this.countdownSecondsRemaining > 0 &&
+      remainingTourSeconds <= this.countdownSecondsRemaining
+    ) {
+      this.phase = 'countdown'
+      this.countdownSecondsRemaining = remainingTourSeconds
+      this.updateControlsEnabled()
+      this.emitCountdownCue(Math.ceil(this.countdownSecondsRemaining))
+      this.emitSnapshot(true)
+    } else if (this.phase === 'countdown') {
+      this.countdownSecondsRemaining = remainingTourSeconds
+      const nextCountdown = Math.ceil(this.countdownSecondsRemaining)
+      if (nextCountdown !== previousCountdown) {
+        if (nextCountdown > 0) this.emitCountdownCue(nextCountdown)
+        this.emitSnapshot(false)
+      }
+    }
+    return remainingTourSeconds === 0
+  }
+
+  private synchronizeCameraTour(synchronizedElapsedMs: number, synchronizedIntroElapsedMs?: number): void {
+    const plan = this.cameraTourPlan
+    if (!plan) return
+    const previousPhase = this.phase
+    const previousCountdown = Math.ceil(this.countdownSecondsRemaining)
+    const state = synchronizedRaceIntroState(plan.durationSeconds, synchronizedElapsedMs, synchronizedIntroElapsedMs)
+    this.cameraTourElapsedSeconds = state.elapsedSeconds
+    this.countdownSecondsRemaining = state.countdownSeconds
+    this.phase = state.phase
+    const nextCountdown = Math.ceil(this.countdownSecondsRemaining)
+    if (this.phase === 'countdown' && (previousPhase !== 'countdown' || nextCountdown !== previousCountdown)) {
+      this.emitCountdownCue(nextCountdown)
+      // Synchronized races derive countdown time from the authoritative
+      // clock rather than advanceCameraTour(). Publish the same boundary
+      // snapshots so the HUD receives 3, 2, and 1 before the racing snapshot
+      // that displays GO.
+      if (nextCountdown > 0) this.emitSnapshot(true)
+    }
+  }
+
+  private synchronizeCountdown(synchronizedElapsedMs: number): void {
+    const previousCountdown = Math.ceil(this.countdownSecondsRemaining)
+    this.countdownSecondsRemaining = THREE.MathUtils.clamp(-synchronizedElapsedMs / 1_000, 0, RACE_COUNTDOWN_SECONDS)
+    const nextCountdown = Math.ceil(this.countdownSecondsRemaining)
+    if (nextCountdown > 0) this.emitCountdownCue(nextCountdown)
+    if (nextCountdown === previousCountdown) return
+    this.emitSnapshot(true)
+  }
+
+  private finishCameraTour(): void {
+    if (!this.worldReady) return
+    this.countdownSecondsRemaining = 0
+    this.cameraProgress = THREE.MathUtils.clamp(this.track.spawnProgress, 0, this.course.totalLength)
+    this.phase = 'racing'
+    this.accumulator = 0
+    this.updateControlsEnabled()
+    this.emitRaceStartCue()
+    this.emitSnapshot(true)
+  }
+
+  private emitCountdownCue(countdown: number): void {
+    if (countdown <= 0 || countdown === this.lastCountdownCue) return
+    this.lastCountdownCue = countdown
+    this.emitRaceCue('countdown')
+  }
+
+  private emitRaceStartCue(): void {
+    if (this.raceStartCuePlayed) return
+    this.raceStartCuePlayed = true
+    this.emitRaceCue('start')
+  }
+
+  private emitRaceCue(cue: 'countdown' | 'start'): void {
+    try {
+      this.onRaceCue?.(cue)
+    } catch {
+      // Presentation audio must never interrupt deterministic race timing.
+    }
+  }
+
+  private updateCameraProgress(deltaSeconds: number): void {
+    if (this.phase !== 'racing') return
+
+    const subject = this.cameraSubject()
+    const packSize = this.cameraView === 'race' ? this.cameraPackFrame.count : 0
+    const targetProgress =
+      packSize > 0 ? this.cameraPackFrame.progress : (subject?.bestProgress ?? this.cameraProgress)
+    if (Math.abs(targetProgress - this.cameraProgress) < 0.18) return
+    this.cameraProgress = THREE.MathUtils.lerp(
+      this.cameraProgress,
+      targetProgress,
+      responseAlpha(
+        this.cameraView === 'focus' ? FOCUS_CAMERA_PROGRESS_RESPONSE : CAMERA_PROGRESS_RESPONSE,
+        deltaSeconds,
+      ),
+    )
+  }
+
+  private updateCamera(deltaSeconds: number): void {
+    if (this.cameraView === 'race') {
+      this.cameraPackTracker.update(this.marbles, this.cameraPackFrame, deltaSeconds)
+      this.cameraPackDiscontinuityPending = this.cameraPackTracker.consumeDiscontinuity(this.cameraTargetDelta)
+      if (this.cameraPackDiscontinuityPending) this.cameraProgress = this.cameraPackFrame.progress
+    }
+    this.updateCameraProgress(deltaSeconds)
+    this.writeDefaultCameraPose(deltaSeconds)
+    if (!this.ownsSurface) {
+      this.visualRoot.updateMatrixWorld(true)
+      this.visualRoot.localToWorld(this.desiredCameraPosition)
+      this.visualRoot.localToWorld(this.desiredCameraTarget)
+    }
+    this.applyCameraTargetHandoff(this.controls?.target ?? this.cameraTarget, deltaSeconds)
+    if (this.phase === 'touring' || this.phase === 'staging' || this.phase === 'countdown') {
+      const renderedTarget = this.controls?.target ?? this.cameraTarget
+      this.camera.position.copy(this.desiredCameraPosition)
+      renderedTarget.copy(this.desiredCameraTarget)
+      this.cameraTarget.copy(renderedTarget)
+      this.camera.fov = this.desiredCameraFov
+      this.camera.updateProjectionMatrix()
+      this.camera.up.copy(THREE.Object3D.DEFAULT_UP)
+      this.camera.lookAt(renderedTarget)
+      this.cameraDirector.synchronize(this.camera.position, renderedTarget)
+      return
+    }
+    // Track banking and loop normals position the camera relative to the
+    // course, but must not roll the viewer or leak a tilted up-vector back to
+    // the shared Track Lab camera.
+    this.cameraWorldUp.copy(THREE.Object3D.DEFAULT_UP)
+    this.resolveCameraObstruction(deltaSeconds)
+    this.cameraLockedDistance = this.desiredCameraPosition.distanceTo(this.desiredCameraTarget)
+    const returning = this.cameraControl === 'free' && this.cameraReturnCurve.isActive()
+    if (!returning) {
+      this.updateCameraFov(this.cameraControl === 'free' ? this.cameraFreeFov : this.desiredCameraFov, deltaSeconds)
+    }
+
+    const renderedTarget = this.controls?.target ?? this.cameraTarget
+    this.applyRacePackDiscontinuity(renderedTarget)
+    this.applyFocusPortalDiscontinuity(renderedTarget)
+    if ((this.cameraControl === 'free' || this.focusOrbitActive) && this.controls) {
+      if (this.cameraView === 'focus') this.translateFreeCameraWithAnchor(renderedTarget)
+      if (this.cameraView === 'race') {
+        this.cameraTargetDelta.copy(renderedTarget)
+        this.cameraDirector.updateTarget(renderedTarget, this.desiredCameraTarget, deltaSeconds)
+        this.cameraTargetDelta.subVectors(renderedTarget, this.cameraTargetDelta)
+        this.camera.position.add(this.cameraTargetDelta)
+        this.cameraReturnCurve.translate(this.cameraTargetDelta)
+      } else if (!this.cameraInteractionActive) {
+        this.cameraTargetDelta.copy(renderedTarget)
+        this.cameraDirector.update(
+          this.camera.position,
+          renderedTarget,
+          this.camera.position,
+          this.desiredCameraTarget,
+          deltaSeconds,
+        )
+        this.cameraTargetDelta.subVectors(renderedTarget, this.cameraTargetDelta)
+        this.camera.position.add(this.cameraTargetDelta)
+        this.cameraReturnCurve.translate(this.cameraTargetDelta)
+      }
+      if (returning) {
+        this.synchronizeReturningControls()
+        this.cameraFreeFov = this.cameraReturnCurve.writePose(
+          this.desiredCameraPosition,
+          this.desiredCameraTarget,
+          this.desiredCameraFov,
+          this.camera.position,
+          renderedTarget,
+          deltaSeconds,
+        )
+        if (Math.abs(this.cameraFreeFov - this.camera.fov) > 0.001) {
+          this.camera.fov = this.cameraFreeFov
+          this.camera.updateProjectionMatrix()
+        }
+        this.camera.up.copy(this.cameraWorldUp)
+        this.camera.lookAt(renderedTarget)
+      } else {
+        this.cameraControlsUpdating = true
+        try {
+          this.controls.update()
+        } finally {
+          this.cameraControlsUpdating = false
+        }
+      }
+    } else {
+      this.cameraDirector.update(
+        this.camera.position,
+        renderedTarget,
+        this.desiredCameraPosition,
+        this.desiredCameraTarget,
+        deltaSeconds,
+        this.focusSubjectLocked,
+      )
+      this.camera.up.copy(this.cameraWorldUp)
+    }
+    if (this.focusSubjectLocked) {
+      this.camera.up.copy(this.cameraWorldUp)
+      this.camera.lookAt(renderedTarget)
+    } else if (this.cameraControl === 'locked') {
+      this.orientCameraToward(renderedTarget, deltaSeconds)
+    }
+    this.cameraTarget.copy(renderedTarget)
+    if (this.cameraReturnLockPending && this.cameraReturnCurve.isComplete()) this.completeCameraReturn()
+
+    if (
+      this.activePortalTransition &&
+      this.simulationTick - this.activePortalTransition.tick >= PORTAL_REBASE_MINIMUM_HOLD_TICKS &&
+      this.camera.position.distanceToSquared(this.desiredCameraPosition) <= 1.5 ** 2
+    ) {
+      this.pendingPortalEvents.delete(this.activePortalTransition.slotId)
+      this.activePortalTransition = undefined
+    }
+  }
+
+  private updateCameraFov(targetFov: number, deltaSeconds: number): void {
+    const nextFov =
+      Math.abs(targetFov - this.camera.fov) < 0.25
+        ? this.camera.fov
+        : THREE.MathUtils.lerp(this.camera.fov, targetFov, responseAlpha(CAMERA_FOV_RESPONSE, deltaSeconds))
+    if (Math.abs(nextFov - this.camera.fov) <= 0.001) return
+    this.camera.fov = nextFov
+    this.camera.updateProjectionMatrix()
+  }
+
+  /**
+   * Keeps the authored camera on its existing sightline. This is deliberately
+   * one query and one dimension: an obstruction may shorten the boom, but it
+   * can never choose another side or rotate the user's view.
+   */
+  private resolveCameraObstruction(deltaSeconds: number): void {
+    this.cameraProbeCount = 0
+    this.cameraObstructed = false
+    this.cameraSightLine.subVectors(this.desiredCameraPosition, this.desiredCameraTarget)
+    this.cameraDesiredDistance = this.cameraSightLine.length()
+    const resolvingLockedPose = this.cameraControl === 'locked' || this.cameraReturnCurve.isActive()
+    if (
+      !resolvingLockedPose ||
+      !this.queryWorld ||
+      this.cameraDesiredDistance <= CAMERA_MIN_TARGET_DISTANCE
+    ) {
+      this.cameraResolvedDistance = this.cameraDesiredDistance
+      return
+    }
+
+    this.cameraSightLine.multiplyScalar(1 / this.cameraDesiredDistance)
+    const probeOffset = cameraObstructionProbeOffset(this.cameraDesiredDistance)
+    this.cameraObstructionOrigin
+      .copy(this.desiredCameraTarget)
+      .addScaledVector(this.cameraSightLine, probeOffset)
+    const hit = this.queryWorld.castShape(
+      this.cameraObstructionOrigin,
+      this.cameraCollisionRotation,
+      this.cameraSightLine,
+      this.cameraCollisionShape,
+      CAMERA_COLLISION_PREDICTION,
+      Math.max(0, this.cameraDesiredDistance - probeOffset),
+      true,
+      RAPIER.QueryFilterFlags.EXCLUDE_DYNAMIC | RAPIER.QueryFilterFlags.EXCLUDE_SENSORS,
+    )
+    this.cameraProbeCount = 1
+    const allowedDistance = resolveCameraObstructionDistance(
+      this.cameraDesiredDistance,
+      hit?.time_of_impact,
+      probeOffset,
+    )
+    this.cameraObstructed = allowedDistance < this.cameraDesiredDistance - 0.001
+    this.cameraResolvedDistance = advanceCameraObstructionDistance(
+      this.cameraResolvedDistance,
+      allowedDistance,
+      deltaSeconds,
+    )
+    this.cameraResolvedDistance = Math.min(this.cameraDesiredDistance, this.cameraResolvedDistance)
+    this.desiredCameraPosition
+      .copy(this.desiredCameraTarget)
+      .addScaledVector(this.cameraSightLine, this.cameraResolvedDistance)
+  }
+
+  private synchronizeReturningControls(): void {
+    const controls = this.controls
+    if (!controls || !this.cameraReturnNeedsControlsSync) return
+    const dampingEnabled = controls.enableDamping
+    controls.enableDamping = false
+    this.cameraControlsUpdating = true
+    try {
+      // Clear the final native orbit/dolly delta once, before the curve owns
+      // its first presented frame. OrbitControls does not write again while
+      // the return is active.
+      controls.update()
+    } finally {
+      this.cameraControlsUpdating = false
+      controls.enableDamping = dampingEnabled
+      this.cameraReturnNeedsControlsSync = false
+    }
+  }
+
+  /** Rebases the existing pack rig when the retained pack crosses a portal. */
+  private applyRacePackDiscontinuity(renderedTarget: THREE.Vector3): void {
+    if (!this.cameraPackDiscontinuityPending || this.cameraView !== 'race') return
+    this.cameraTargetDelta.subVectors(this.desiredCameraTarget, renderedTarget)
+    this.camera.position.add(this.cameraTargetDelta)
+    renderedTarget.copy(this.desiredCameraTarget)
+    this.cameraTarget.copy(renderedTarget)
+    this.cameraReturnCurve.translate(this.cameraTargetDelta)
+    this.cameraDirector.synchronize(this.camera.position, renderedTarget)
+    this.cameraPackDiscontinuityPending = false
+  }
+
+  /** A portal is a world discontinuity, not a path the camera should collide through. */
+  private applyFocusPortalDiscontinuity(renderedTarget: THREE.Vector3): void {
+    if (
+      this.cameraView !== 'focus' ||
+      this.activePortalTransition?.slotId !== this.cameraTargetSlotId ||
+      renderedTarget.distanceTo(this.desiredCameraTarget) <= Math.max(20, this.cameraLockedDistance * 1.25)
+    ) {
+      return
+    }
+    this.cameraTargetDelta.subVectors(this.desiredCameraTarget, renderedTarget)
+    this.camera.position.add(this.cameraTargetDelta)
+    renderedTarget.add(this.cameraTargetDelta)
+    this.cameraReturnCurve.translate(this.cameraTargetDelta)
+    if (this.cameraControl === 'free' || this.focusOrbitActive) {
+      this.cameraFreeFollowAnchor.copy(this.desiredCameraTarget)
+    }
+    this.cameraDirector.synchronize(this.camera.position, renderedTarget)
+  }
+
+  private translateFreeCameraWithAnchor(renderedTarget: THREE.Vector3): void {
+    // Preserve the user's orbit vector while moving its entire coordinate
+    // frame with the marble or pack. OrbitControls remains the sole owner of
+    // rotation and dolly during an active gesture, so this cannot fight drag.
+    translateFreeCameraRig(
+      this.camera.position,
+      renderedTarget,
+      this.cameraFreeFollowAnchor,
+      this.desiredCameraTarget,
+      this.cameraTargetDelta,
+    )
+    this.cameraReturnCurve.translate(this.cameraTargetDelta)
+  }
+
+  private applyCameraTargetHandoff(renderedTarget: THREE.Vector3, deltaSeconds: number): void {
+    if (this.focusSubjectLocked) {
+      this.cameraTargetHandoffPending = false
+      this.cameraTargetHandoffSeconds = CAMERA_TARGET_HANDOFF_SECONDS
+      return
+    }
+    if (this.cameraTargetHandoffPending) {
+      this.cameraTargetHandoffOffset.subVectors(renderedTarget, this.desiredCameraTarget)
+      this.cameraTargetHandoffPending = false
+    }
+    if (this.cameraTargetHandoffSeconds >= CAMERA_TARGET_HANDOFF_SECONDS) return
+
+    this.cameraTargetHandoffSeconds = Math.min(
+      CAMERA_TARGET_HANDOFF_SECONDS,
+      this.cameraTargetHandoffSeconds + THREE.MathUtils.clamp(deltaSeconds, 0, 0.1),
+    )
+    const progress = THREE.MathUtils.smootherstep(this.cameraTargetHandoffSeconds, 0, CAMERA_TARGET_HANDOFF_SECONDS)
+    this.desiredCameraTarget.addScaledVector(this.cameraTargetHandoffOffset, 1 - progress)
+  }
+
+  private writeDefaultCameraPose(deltaSeconds = 0): void {
+    const mobileCamera = this.container.clientWidth < 520
+    const subject = this.cameraSubject()
+    const subjectPosition = subject?.visual.position
+    const tourShot =
+      this.phase === 'touring' ||
+      (this.phase === 'countdown' &&
+        this.cameraTourPlan !== undefined &&
+        this.cameraTourElapsedSeconds <= this.cameraTourPlan.durationSeconds)
+    const startLineShot = this.phase === 'staging' || (this.phase === 'countdown' && !tourShot)
+    this.focusSubjectLocked = this.cameraControl === 'locked' && !tourShot && !startLineShot && this.cameraView === 'focus'
+    if (tourShot) {
+      this.writeTourCameraPose()
+      return
+    }
+    const cameraFrameProgress =
+      this.focusSubjectLocked && subject ? subject.projection.distance : this.cameraProgress
+    this.writeSmoothedCameraFrame(
+      cameraFrameProgress,
+      this.cameraView === 'focus' ? 4 : 8,
+      deltaSeconds,
+      this.focusSubjectLocked,
+    )
+    if (this.focusSubjectLocked && subject) this.writeFocusSubjectFrame(subject)
+    if (startLineShot) {
+      this.writeStartLineCameraPose(subject, mobileCamera)
+      return
+    }
+
+    this.updatePortalCameraState(this.cameraView === 'focus' ? subject : undefined)
+
+    this.cameraDirector.setState('follow')
+
+    if (this.cameraView === 'focus') {
+      this.desiredCameraFov = mobileCamera ? 66 : 60
+      this.desiredCameraTarget.set(
+        subjectPosition?.x ?? this.cameraPose.position.x,
+        subjectPosition?.y ?? this.cameraPose.position.y,
+        subjectPosition?.z ?? this.cameraPose.position.z,
+      )
+      this.desiredCameraPosition
+        .copy(this.desiredCameraTarget)
+        .addScaledVector(this.cameraForward, mobileCamera ? -13 : -11.5)
+        .addScaledVector(this.cameraUp, mobileCamera ? 7 : 6.2)
+        .addScaledVector(this.cameraRight, mobileCamera ? 0 : 1.2)
+      return
+    }
+
+    this.writePackTarget(subject)
+
+    const packRadius = this.cameraPackFrame.radius
+    const framingDistance = THREE.MathUtils.clamp(14 + packRadius * 1.35, 14, mobileCamera ? 23 : 21)
+    this.desiredCameraFov = THREE.MathUtils.clamp((mobileCamera ? 57 : 50) + packRadius * 0.72, 50, 62)
+    this.desiredCameraPosition
+      .copy(this.desiredCameraTarget)
+      .addScaledVector(this.cameraForward, -framingDistance)
+      .addScaledVector(THREE.Object3D.DEFAULT_UP, framingDistance * (mobileCamera ? 0.74 : 0.62))
+      .addScaledVector(this.cameraRight, framingDistance * (mobileCamera ? 0.07 : 0.26))
+  }
+
+  private cameraSubject(): MarbleEntity | undefined {
+    let leader: MarbleEntity | undefined
+    let retainedLeader: MarbleEntity | undefined
+    for (const marble of this.marbles) {
+      if (this.cameraTargetSlotId && marble.assignment.slotId === this.cameraTargetSlotId) {
+        return marble
+      }
+      if (marble.assignment.slotId === this.cameraLeaderSlotId) retainedLeader = marble
+      if (!leader || marble.bestProgress > leader.bestProgress) leader = marble
+    }
+    if (retainedLeader && leader && retainCameraLeader(retainedLeader.bestProgress, leader.bestProgress)) {
+      return retainedLeader
+    }
+    this.cameraLeaderSlotId = leader?.assignment.slotId
+    return leader
+  }
+
+  private buildCameraTourPlan(): void {
+    this.cameraTourPlan = undefined
+    const mobileCamera = this.container.clientWidth < 520
+    this.cameraProgress = THREE.MathUtils.clamp(this.track.spawnProgress, 0, this.course.totalLength)
+    this.writeSmoothedCameraFrame(this.cameraProgress, 8, 0)
+    this.writeStartLineCameraPose(this.cameraSubject(), mobileCamera)
+    const startPosition = this.desiredCameraPosition.clone()
+    const startTarget = this.desiredCameraTarget.clone()
+    const startForward = this.cameraForward.clone()
+    this.writeCameraTourOpeningPose()
+    this.cameraTourPlan = createCameraTourPlan({
+      track: this.track,
+      finishPose: {
+        position: this.desiredCameraPosition.toArray(),
+        target: this.desiredCameraTarget.toArray(),
+        fov: this.desiredCameraFov,
+      },
+      startPose: {
+        position: startPosition.toArray(),
+        target: startTarget.toArray(),
+        fov: mobileCamera ? 58 : 52,
+      },
+      startForward,
+      durationSeconds: this.introDurationSeconds,
+    })
+  }
+
+  private writeCameraTourOpeningPose(): void {
+    // The camera guide can terminate before or after the visible gate on
+    // compiled/folded courses. The finish piece centre matches TrackWorld's
+    // canonical finish position and is available before Rapier construction.
+    const finishPiece = this.track.pieces.find(piece => piece.type === 'finish')
+    const finish =
+      this.trackWorld?.finishPosition.clone() ??
+      (finishPiece?.type === 'finish'
+        ? new THREE.Vector3().fromArray(finishPiece.center)
+        : new THREE.Vector3().fromArray(this.track.cameraPath.points.at(-1)!.position))
+    this.course.writePoseAtDistance(this.course.totalLength, this.cameraPose)
+    this.desiredCameraTarget.copy(finish).addScaledVector(THREE.Object3D.DEFAULT_UP, 1.35)
+    this.desiredCameraPosition
+      .copy(this.desiredCameraTarget)
+      // Stay centered on the exterior side of the finish. This keeps the gate
+      // recognizable without trapping the opening camera inside a folded
+      // course footprint or letting a one-sided mechanism dominate the frame.
+      .addScaledVector(this.cameraPose.tangent, 11)
+      .addScaledVector(THREE.Object3D.DEFAULT_UP, 5.5)
+    this.desiredCameraFov = this.container.clientWidth < 520 ? 58 : 52
+  }
+
+  private writeTourCameraPose(): void {
+    this.cameraDirector.setState('tour')
+    const plan = this.cameraTourPlan
+    if (!plan) return
+    const progress = smoothCameraTourProgress(this.cameraTourElapsedSeconds / plan.durationSeconds)
+    this.desiredCameraFov = sampleCameraTourPlan(plan, progress, {
+      position: this.desiredCameraPosition,
+      target: this.desiredCameraTarget,
+    })
+  }
+
+  private writeStartLineCameraPose(subject: MarbleEntity | undefined, mobileCamera: boolean): void {
+    this.cameraDirector.setState('start-line')
+    const packSize = writeLeadingPackFrame(this.marbles, this.cameraPackFrame)
+    this.desiredCameraTarget.copy(this.cameraPackFrame.center)
+    if (packSize === 0 && subject) this.desiredCameraTarget.copy(subject.visual.position)
+    else if (packSize === 0) this.desiredCameraTarget.copy(this.cameraPose.position)
+
+    const distance = mobileCamera ? 14 : 12
+    this.desiredCameraPosition
+      .copy(this.desiredCameraTarget)
+      .addScaledVector(this.cameraForward, -distance)
+      .addScaledVector(THREE.Object3D.DEFAULT_UP, mobileCamera ? 3.2 : 2.65)
+    this.desiredCameraFov = mobileCamera ? 58 : 52
+    if ((this.phase === 'staging' || this.phase === 'countdown') && this.cameraTourPlan) {
+      this.desiredCameraPosition.fromArray(this.cameraTourPlan.startPose.position)
+      this.desiredCameraTarget.fromArray(this.cameraTourPlan.startPose.target)
+      this.desiredCameraFov = this.cameraTourPlan.startPose.fov
+    }
+  }
+
+  private updatePortalCameraState(subject: MarbleEntity | undefined): void {
+    if (this.activePortalTransition?.slotId !== subject?.assignment.slotId) {
+      this.activePortalTransition = undefined
+    }
+    if (subject) {
+      const pending = this.pendingPortalEvents.get(subject.assignment.slotId)
+      if (
+        pending &&
+        this.simulationTick - pending.tick <= PORTAL_EVENT_ACTIVATION_TICKS &&
+        (!this.activePortalTransition || pending.tick > this.activePortalTransition.tick)
+      ) {
+        this.activePortalTransition = pending
+      }
+    }
+    if (this.pendingPortalEvents.size > 0) {
+      for (const [slotId, event] of this.pendingPortalEvents) {
+        if (this.simulationTick - event.tick > PORTAL_EVENT_EXPIRY_TICKS) this.pendingPortalEvents.delete(slotId)
+      }
+    }
+  }
+
+  private writeSmoothedCameraFrame(
+    progress: number,
+    span: number,
+    deltaSeconds: number,
+    useImmediateLocalTangent = false,
+  ): void {
+    this.course.writePoseAtDistance(progress, this.cameraPose)
+    this.course.writePoseAtDistance(Math.max(0, progress - span), this.cameraBehindPose)
+    this.course.writePoseAtDistance(Math.min(this.course.totalLength, progress + span), this.cameraTargetPose)
+    this.cameraGuideChord.subVectors(this.cameraTargetPose.position, this.cameraBehindPose.position)
+    if (useImmediateLocalTangent) {
+      this.cameraDesiredGuideForward.copy(this.cameraPose.tangent).normalize()
+    } else {
+      writeStableCameraGuideDirection(this.cameraPose.tangent, this.cameraGuideChord, this.cameraDesiredGuideForward)
+    }
+    if (useImmediateLocalTangent || this.cameraGuideForward.lengthSq() < 0.000_001 || deltaSeconds <= 0) {
+      this.cameraGuideForward.copy(this.cameraDesiredGuideForward)
+    } else {
+      this.cameraGuideForward.lerp(this.cameraDesiredGuideForward, responseAlpha(4, deltaSeconds)).normalize()
+    }
+    this.cameraForward.copy(this.cameraGuideForward)
+    this.cameraUp.copy(this.cameraPose.up).normalize()
+    this.cameraRight.crossVectors(this.cameraUp, this.cameraForward)
+    if (this.cameraRight.lengthSq() < 0.0001) this.cameraRight.copy(this.cameraPose.right)
+    else this.cameraRight.normalize()
+    this.cameraUp.crossVectors(this.cameraForward, this.cameraRight).normalize()
+  }
+
+  private writeFocusSubjectFrame(subject: MarbleEntity): void {
+    const projectionSample = this.course.projectionSamples[subject.projection.sampleIndex]
+    if (!projectionSample) return
+    this.course.writeProjectionFrameAtDistance(
+      subject.projection.sampleIndex,
+      subject.projection.distance,
+      this.cameraForward,
+      this.cameraRight,
+      this.cameraUp,
+    )
+    this.cameraGuideForward.copy(this.cameraForward)
+  }
+
+  private orientCameraToward(target: THREE.Vector3, deltaSeconds: number): void {
+    if (target.distanceToSquared(this.camera.position) < 0.000_001) return
+    this.cameraLookMatrix.lookAt(this.camera.position, target, this.cameraWorldUp)
+    this.desiredCameraQuaternion.setFromRotationMatrix(this.cameraLookMatrix)
+    advanceCameraOrientation(this.camera.quaternion, this.desiredCameraQuaternion, deltaSeconds)
+  }
+
+  private writePackTarget(subject: MarbleEntity | undefined): void {
+    const packSize = this.cameraPackFrame.count
+    this.desiredCameraTarget.copy(this.cameraPackFrame.center)
+    if (packSize === 0 && subject) {
+      const position = subject.visual.position
+      this.desiredCameraTarget.set(position.x, position.y, position.z)
+    } else if (packSize === 0) this.desiredCameraTarget.copy(this.cameraPose.position)
+    this.desiredCameraTarget.addScaledVector(this.cameraUp, 1).addScaledVector(this.cameraForward, 4.5)
+  }
+
+  private readonly handleCameraPointerDown = (event: PointerEvent): void => {
+    this.cameraPointerIds.add(event.pointerId)
+    this.cameraInteractionIsWheel = false
+    this.cameraInteractionAllowsCombinedZoom = event.pointerType === 'touch' && this.cameraPointerIds.size > 1
+  }
+
+  private readonly handleCameraPointerUp = (event: PointerEvent): void => {
+    this.cameraPointerIds.delete(event.pointerId)
+    if (this.cameraPointerIds.size < 2) this.cameraInteractionAllowsCombinedZoom = false
+  }
+
+  private readonly handleCameraWheel = (): void => {
+    // OrbitControls keeps full ownership of native wheel/trackpad dolly. This
+    // flag only prevents residual rotation damping from misclassifying a wheel
+    // change as an orbit gesture while we observe its resulting distance.
+    this.cameraInteractionIsWheel = true
+    this.cameraInteractionAllowsCombinedZoom = false
+  }
+
+  private readonly markCameraAsUserControlled = (): void => {
+    const controls = this.controls
+    if (!controls) return
+    this.cameraInteractionActive = true
+    this.cameraInteractionStartPosition.copy(this.camera.position)
+    this.cameraInteractionStartTarget.copy(controls.target)
+    this.cameraInteractionStartDirection.subVectors(this.camera.position, controls.target).normalize()
+    this.cameraInteractionDistance = this.camera.position.distanceTo(controls.target)
+    this.cameraLockedDistance =
+      this.cameraControl === 'locked'
+        ? this.cameraInteractionDistance
+        : this.desiredCameraPosition.distanceTo(this.desiredCameraTarget)
+    controls.minDistance =
+      this.cameraControl === 'locked' ? this.cameraInteractionDistance : this.cameraFreeMinimumDistance
+  }
+
+  private readonly handleCameraControlsChange = (): void => {
+    const controls = this.controls
+    if (!controls || !this.cameraInteractionActive || this.cameraControlsUpdating) return
+    const nextDistance = this.camera.position.distanceTo(controls.target)
+    this.cameraSightLine.subVectors(this.camera.position, controls.target).normalize()
+    const directionChanged = this.cameraInteractionStartDirection.angleTo(this.cameraSightLine) > 0.000_1
+    const rotatesView = !this.cameraInteractionIsWheel && directionChanged
+    const zoomedIn = cameraZoomIsInward(this.cameraInteractionDistance, nextDistance)
+    const zoomedOut = cameraZoomIsOutward(this.cameraInteractionDistance, nextDistance)
+    if (this.cameraControl === 'locked') {
+      if (zoomedOut) {
+        this.enterFreeCamera(controls)
+      } else if (rotatesView) {
+        if (this.cameraView === 'focus') this.beginFocusedOrbit(controls)
+        else this.enterFreeCamera(controls)
+      }
+      return
+    }
+
+    if (zoomedOut || (rotatesView && !(this.cameraInteractionAllowsCombinedZoom && zoomedIn))) {
+      this.cameraReturnCurve.cancel()
+      this.cameraReturnLockPending = false
+      this.cameraReturnNeedsControlsSync = false
+      this.cameraFreeFov = this.camera.fov
+      this.cameraInteractionStartPosition.copy(this.camera.position)
+      this.cameraInteractionStartTarget.copy(controls.target)
+      this.cameraInteractionStartDirection.copy(this.cameraSightLine)
+      this.cameraInteractionDistance = nextDistance
+      return
+    }
+    if (!zoomedIn) return
+
+    const startingReturn = !this.cameraReturnCurve.isActive()
+    if (startingReturn) {
+      this.cameraReturnCurve.begin(
+        this.cameraInteractionStartPosition,
+        this.cameraInteractionStartTarget,
+        this.cameraFreeFov,
+        this.cameraInteractionDistance,
+      )
+    }
+    this.cameraReturnCurve.addInwardInput(this.cameraInteractionDistance, nextDistance, this.cameraLockedDistance)
+    this.cameraReturnLockPending = true
+    if (startingReturn) this.cameraReturnNeedsControlsSync = true
+    this.cameraInteractionDistance = nextDistance
+  }
+
+  private readonly finishCameraInteraction = (): void => {
+    this.cameraInteractionActive = false
+    this.cameraInteractionIsWheel = false
+  }
+
+  private enterFreeCamera(controls: OrbitControls): void {
+    this.cameraControl = 'free'
+    this.focusOrbitActive = false
+    this.cameraFreeFollowAnchor.copy(this.desiredCameraTarget)
+    controls.minDistance = this.cameraFreeMinimumDistance
+    this.cameraFreeFov = this.camera.fov
+    this.cameraReturnCurve.cancel()
+    this.cameraReturnLockPending = false
+    this.cameraReturnNeedsControlsSync = false
+    // Race View keeps its existing pack-pivot velocity so zooming out does not
+    // introduce a visible pause. Focus uses exact subject translation in free
+    // mode and clears the locked camera body's remaining motion instead.
+    if (this.cameraView === 'focus') this.cameraDirector.synchronize(this.camera.position, controls.target)
+    this.emitCameraChange()
+  }
+
+  private beginFocusedOrbit(controls: OrbitControls): void {
+    if (this.focusOrbitActive) return
+    this.focusOrbitActive = true
+    this.cameraFreeFollowAnchor.copy(this.desiredCameraTarget)
+    this.cameraDirector.synchronize(this.camera.position, controls.target)
+  }
+
+  private requestCameraReturn(): void {
+    const target = this.controls?.target ?? this.cameraTarget
+    if (!this.cameraReturnCurve.isActive()) {
+      this.cameraReturnCurve.begin(
+        this.camera.position,
+        target,
+        this.camera.fov,
+        this.camera.position.distanceTo(target),
+      )
+    }
+    this.cameraReturnCurve.setRequestedDistance(0)
+    this.cameraReturnLockPending = true
+    this.cameraReturnNeedsControlsSync = true
+    this.cameraInteractionActive = false
+  }
+
+  private completeCameraReturn(): void {
+    this.cameraControl = 'locked'
+    this.focusOrbitActive = false
+    this.cameraReturnCurve.cancel()
+    this.cameraReturnLockPending = false
+    this.cameraReturnNeedsControlsSync = false
+    this.cameraInteractionActive = false
+    if (this.controls) {
+      this.controls.minDistance = this.camera.position.distanceTo(this.controls.target)
+    }
+    this.cameraDirector.synchronize(this.camera.position, this.controls?.target ?? this.cameraTarget)
+    this.emitCameraChange()
+  }
+
+  private emitCameraChange(): void {
+    if (!this.onCameraChange) return
+    const snapshot: RaceCameraSnapshot = {
+      view: this.cameraView,
+      control: this.cameraControl,
+      ...(this.cameraTargetSlotId ? { targetSlotId: this.cameraTargetSlotId } : {}),
+    }
+    const key = `${snapshot.view}:${snapshot.control}:${snapshot.targetSlotId ?? ''}`
+    if (key === this.cameraSnapshotKey) return
+    this.cameraSnapshotKey = key
+    try {
+      this.onCameraChange(snapshot)
+    } catch {
+      // Camera UI must never interrupt rendering or deterministic simulation.
+    }
+  }
+
+  private syncVisuals(interpolationAlpha = this.renderInterpolationAlpha()): void {
+    // A rendered frame can advance many 120 Hz physics ticks. Mechanism meshes
+    // only need the final rigid-body pose; syncing inside fixedStep multiplies
+    // the same scene traversal by the playback rate and catch-up backlog.
+    this.simulationRenderer?.render(interpolationAlpha)
+    this.marbles.forEach(marble => syncMarbleVisual(marble, interpolationAlpha))
+
+    const compactLabels = this.container.clientWidth < 520
+    this.marbles.forEach(marble => {
+      marble.label.visible = true
+      marble.label.scale.set(compactLabels ? 1.92 : 2.35, compactLabels ? 0.54 : 0.66, 1)
+    })
+  }
+
+  private renderInterpolationAlpha(): number {
+    if (this.paused || this.phase !== 'racing') return 1
+    if (this.initialSimulationElapsedMs !== undefined) return this.synchronizedInterpolationAlpha
+    return THREE.MathUtils.clamp(this.accumulator / FIXED_TIMESTEP, 0, 1)
+  }
+
+  private completeRace(): void {
+    const result = this.simulation?.result()
+    if (!result || this.phase === 'finished') return
+    this.winner = result.winner
+    this.replayFingerprint = result.replayFingerprint
+    if (this.developmentMode) {
+      const physicsReport = this.simulation?.debugReport()
+      console.info('[marble-race] physics report', physicsReport)
+      this.renderer.domElement.dataset.physicsDebug = JSON.stringify(physicsReport)
+    }
+    this.phase = 'finished'
+  }
+
+  private getStandings(): MarbleStanding[] {
+    return [...this.marbles]
+      .sort((left, right) => {
+        if (left.finishedAtTick !== undefined && right.finishedAtTick !== undefined) {
+          return (
+            left.finishedAtTick - right.finishedAtTick || left.assignment.slotId.localeCompare(right.assignment.slotId)
+          )
+        }
+        if (left.finishedAtTick !== undefined) {
+          return -1
+        }
+        if (right.finishedAtTick !== undefined) {
+          return 1
+        }
+        return right.bestProgress - left.bestProgress || left.assignment.slotId.localeCompare(right.assignment.slotId)
+      })
+      .map((marble, index) => {
+        const translation = marble.body.translation()
+        return {
+          ...marble.assignment,
+          rank: index + 1,
+          currentProgressMeters: Number(marble.progress.toFixed(2)),
+          progressMeters: Number(marble.bestProgress.toFixed(2)),
+          progressRatio:
+            marble.finishedAtTick === undefined ? Math.min(1, marble.bestProgress / this.course.totalLength) : 1,
+          speedMetersPerSecond: Number(marble.speed.toFixed(2)),
+          worldPosition: [translation.x, translation.y, translation.z] as const,
+          finishTimeMs:
+            marble.finishedAtTick === undefined
+              ? undefined
+              : Math.round(marble.finishedAtTick * FIXED_TIMESTEP * 1_000),
+        }
+      })
+  }
+
+  private emitSnapshot(force = false): void {
+    if (this.suppressSnapshots || (!force && this.disposed)) {
+      return
+    }
+
+    this.latestSnapshot = {
+      phase: this.phase,
+      paused: this.paused,
+      countdown: Math.ceil(this.countdownSecondsRemaining),
+      elapsedMs: Math.round(this.simulationTick * FIXED_TIMESTEP * 1_000),
+      simulationTick: this.simulationTick,
+      replayFingerprint: this.replayFingerprint,
+      standings: this.getStandings(),
+      winner: this.winner,
+    }
+    this.onSnapshot(this.latestSnapshot)
+  }
+
+  private readonly getSnapshot = (): RaceSnapshot => this.latestSnapshot
+
+  private readonly getPhysicsDebugReport = (): PhysicsDebugReport | undefined => this.simulation?.debugReport()
+
+  private readonly getMarbleRenderStates: MarbleRaceTestHooks['getMarbleRenderStates'] = () =>
+    this.marbles.map(marble => {
+      const physics = marble.body.translation()
+      return {
+        slotId: marble.assignment.slotId,
+        physicsPosition: [physics.x, physics.y, physics.z],
+        visualPosition: marble.visual.position.toArray(),
+        finishedAtTick: marble.finishedAtTick,
+      }
+    })
+
+  private frameTimingDiagnostics(): RendererDiagnostics['frameTiming'] {
+    const samples = Array.from(this.frameIntervals.subarray(0, this.frameIntervalCount)).sort(
+      (left, right) => left - right,
+    )
+    const percentile = (fraction: number): number =>
+      samples.length === 0 ? 0 : samples[Math.min(samples.length - 1, Math.floor((samples.length - 1) * fraction))]!
+    return {
+      samples: samples.length,
+      p50Ms: Number(percentile(0.5).toFixed(2)),
+      p95Ms: Number(percentile(0.95).toFixed(2)),
+      p99Ms: Number(percentile(0.99).toFixed(2)),
+      maximumMs: Number((samples.at(-1) ?? 0).toFixed(2)),
+      framesAbove16Ms: samples.filter(sample => sample > 16.7).length,
+    }
+  }
+
+  readonly getRendererDiagnostics = (): RendererDiagnostics => {
+    let sceneMeshes = 0
+    this.scene.traverse(object => {
+      if (object instanceof THREE.Mesh || object instanceof THREE.InstancedMesh) {
+        sceneMeshes += 1
+      }
+    })
+
+    const themeDiagnostics = this.themeController?.diagnostics()
+    const cameraDiagnostics = this.cameraDirector.diagnostics()
+    const authoritativeBodies = this.queryWorld?.bodies.len() ?? 0
+    const authoritativeColliders = this.queryWorld?.colliders.len() ?? 0
+    const mirrorBodies = this.marbles.length + (this.trackWorld?.bodyCount ?? 0)
+    const mirrorColliders = this.marbles.length + (this.trackWorld?.colliderCount ?? 0)
+    return {
+      calls: this.renderer.info.render.calls,
+      triangles: this.renderer.info.render.triangles,
+      geometries: this.renderer.info.memory.geometries,
+      textures: this.renderer.info.memory.textures,
+      sceneMeshes,
+      audio: this.rollingAudio?.diagnostics(),
+      bodies: authoritativeBodies + mirrorBodies,
+      colliders: authoritativeColliders + mirrorColliders,
+      authoritativeBodies,
+      authoritativeColliders,
+      mirrorBodies,
+      mirrorColliders,
+      ccdBodies: this.marbles.length,
+      sensors: this.trackWorld?.sensorCount ?? 0,
+      fixedTimestep: FIXED_TIMESTEP,
+      timeScale: this.timeScale,
+      dpr: this.renderer.getPixelRatio(),
+      paused: this.paused,
+      cameraMode: raceCameraState(this.cameraView, this.cameraControl),
+      cameraTargetSlotId: this.cameraTargetSlotId,
+      cameraDistance: Number(this.camera.position.distanceTo(this.controls?.target ?? this.cameraTarget).toFixed(2)),
+      cameraDirector: {
+        state: cameraDiagnostics.state,
+        ...(this.cameraSubject()?.assignment.slotId ? { subjectSlotId: this.cameraSubject()!.assignment.slotId } : {}),
+        stateSeconds: Number(cameraDiagnostics.stateSeconds.toFixed(2)),
+        packCount: this.cameraPackFrame.count,
+        packRadius: Number(this.cameraPackFrame.radius.toFixed(2)),
+        obstructed: this.cameraObstructed,
+        probes: this.cameraProbeCount,
+        desiredDistance: Number(this.cameraDesiredDistance.toFixed(2)),
+        resolvedDistance: Number(this.cameraResolvedDistance.toFixed(2)),
+        linearSpeed: Number(cameraDiagnostics.linearSpeed.toFixed(2)),
+        targetSpeed: Number(cameraDiagnostics.targetSpeed.toFixed(2)),
+      },
+      ...(this.cameraTourPlan
+        ? {
+            cameraTour: {
+              footprintWidth: Number(this.cameraTourPlan.diagnostics.footprintWidth.toFixed(2)),
+              footprintDepth: Number(this.cameraTourPlan.diagnostics.footprintDepth.toFixed(2)),
+              occupiedCells: this.cameraTourPlan.diagnostics.occupiedCells,
+              routeDirection: this.cameraTourPlan.diagnostics.routeDirection,
+              routeLength: Number(this.cameraTourPlan.diagnostics.routeLength.toFixed(2)),
+              minimumClearance: Number(this.cameraTourPlan.diagnostics.minimumClearance.toFixed(2)),
+              validationAttempts: this.cameraTourPlan.diagnostics.validationAttempts,
+              cruiseAltitude: Number(this.cameraTourPlan.diagnostics.cruiseAltitude.toFixed(2)),
+              pitchChanges: this.cameraTourPlan.diagnostics.pitchChanges,
+              ...(this.cameraTourPlan.diagnostics.fallbackReason
+                ? { fallbackReason: this.cameraTourPlan.diagnostics.fallbackReason }
+                : {}),
+            },
+          }
+        : {}),
+      themeId: themeDiagnostics?.themeId ?? 'unavailable',
+      themeMaterials: themeDiagnostics?.materialCount ?? 0,
+      themeWorldMeshes: themeDiagnostics?.worldMeshes ?? 0,
+      themeInstancedMeshes: themeDiagnostics?.instancedMeshes ?? 0,
+      themeParticles: themeDiagnostics?.particleCount ?? 0,
+      frameIntervalMs: Number(this.frameIntervalMs.toFixed(3)),
+      physicsSteps: this.physicsStepsLastUpdate,
+      physicsBacklogSteps: this.physicsBacklogSteps,
+      catchUpSaturated: this.catchUpSaturated,
+      maximumPhysicsBacklogSteps: this.maximumPhysicsBacklogSteps,
+      catchUpSaturationCount: this.catchUpSaturationCount,
+      frameTiming: this.frameTimingDiagnostics(),
+    }
+  }
+
+  private installTestHooks(): void {
+    window.__MARBLE_RACE_TEST_HOOKS__ = {
+      getSnapshot: this.getSnapshot,
+      getRendererDiagnostics: this.getRendererDiagnostics,
+      getPhysicsDebugReport: this.getPhysicsDebugReport,
+      getMarbleRenderStates: this.getMarbleRenderStates,
+      setPaused: paused => this.setPaused(paused),
+      setTimeScale: timeScale => this.setTimeScale(timeScale),
+      followMarble: slotId => this.followMarble(slotId),
+      advanceTicks: ticks => {
+        const safeTicks = Math.min(20_000, Math.max(0, Math.floor(ticks)))
+        for (let tick = 0; tick < safeTicks && this.phase !== 'finished'; tick += 1) {
+          this.fixedStep()
+        }
+        this.syncVisuals(1)
+        this.updateCamera(1 / 60)
+        this.prepareRender()
+        this.render(1 / 60)
+        this.emitSnapshot(true)
+        return this.latestSnapshot
+      },
+    }
+  }
+}
+
+export function prepareMarbleRacePhysicsTrack(track: TrackDefinition): PreparedPhysicsTrack {
+  return preparePhysicsTrack(track)
+}
+
+export function createPreparedMarbleRaceSimulation(
+  configuration: RaceConfiguration,
+  track: TrackDefinition,
+  preparedPhysicsTrack: PreparedPhysicsTrack,
+  diagnosticsEnabled: boolean,
+): Promise<DeterministicRaceSimulation> {
+  return createPreparedRaceSimulation(
+    {
+      engineVersion: CURRENT_RACE_ENGINE_VERSION,
+      seed: configuration.seed,
+      trackId: track.id,
+      trackJson: track.sourceDocument ? JSON.stringify(track.sourceDocument) : '{}',
+      entrants: configuration.assignments,
+    },
+    preparedPhysicsTrack,
+    undefined,
+    { enabled: diagnosticsEnabled },
+  )
+}