@marble.fun/track-catalog 3.0.0

package/src/pages/track-lab/track-runtime-adapter.ts

@@ -0,0 +1,1152 @@
+import type {
+  CompiledTrack,
+  CompiledTrackPiece,
+  PhysicsTrackDefinition,
+  PhysicsTrackPieceDefinition,
+  TrackDocument,
+  TrackVector,
+} from '@marble.fun/physics-engine/browser'
+import {
+  collectCompletePortalPairs,
+  hasAuthoritativeTrackLabPhysics,
+  laneGradeDrop,
+  portalPairNumber,
+  trackWidthParameterUnits,
+} from '@marble.fun/physics-engine/browser'
+import { createTrackLabPhysicsTrack } from '@marble.fun/physics-engine/track-lab-physics-adapter'
+
+import {
+  defaultTrackTroughDepth,
+  NEUTRAL_STUDIO_SKIN,
+  type ConveyorPieceDefinition,
+  type ReboundPieceDefinition,
+  type FlipperBankPieceDefinition,
+  type PegFieldPieceDefinition,
+  type PortalPieceDefinition,
+  type RailPieceDefinition,
+  type RisingWallForestPieceDefinition,
+  type SplitterPieceDefinition,
+  type TrackDefinition,
+  type TrackGuidePoint,
+  type TrackPieceDefinition,
+  type VortexPieceDefinition,
+} from '../play/race/track-definition'
+import { portalPairColor } from '../play/race/portal-pair-color'
+import { portalVisualStyleFromId } from '../play/race/portal-visual'
+import { connectedTrackMaterialPhases } from '../../three/track-material-continuity'
+import { fluidSurfaceStyleFromId } from '../../three/water-appearance'
+import {
+  CONE_FIELD_PEG_HEIGHT,
+  CONE_FIELD_PEG_RADIUS,
+  CONE_FIELD_WIDTH,
+  createConeFieldDeckProfile,
+  createConeFieldLayout,
+} from './cone-field-layout'
+import {
+  TRACK_LAB_CONVEYOR_BOTTOM,
+  TRACK_LAB_CONVEYOR_DIRECTION,
+  TRACK_LAB_CONVEYOR_LOADING,
+  TRACK_LAB_CONVEYOR_RELEASE,
+  TRACK_LAB_CONVEYOR_SHELF_COUNT,
+  TRACK_LAB_CONVEYOR_SHELF_DEPTH,
+  TRACK_LAB_CONVEYOR_SHELF_TILT_RADIANS,
+  TRACK_LAB_CONVEYOR_SPEED,
+  TRACK_LAB_CONVEYOR_TOP,
+  TRACK_LAB_CONVEYOR_WIDTH,
+} from './conveyor-layout'
+import { createFlipperBankDeck, createFlipperBankLayout } from './flipper-bank-layout'
+import {
+  CANONICAL_FLIPPER_DIMENSIONS,
+  CANONICAL_FLIPPER_SWEEP_RADIANS,
+  FLIPPER_MINIMUM_ONE_WAY_SWEEP_SECONDS,
+} from './flipper-component'
+import {
+  REBOUND_HEIGHT,
+  REBOUND_HOLD_SECONDS,
+  REBOUND_LENGTH,
+  REBOUND_COOLDOWN_SECONDS,
+  REBOUND_RESTITUTION,
+  REBOUND_RETURN_SECONDS,
+  REBOUND_STRIKE_DISTANCE,
+  REBOUND_STRIKE_SECONDS,
+  REBOUND_WIDTH,
+  createReboundDeck,
+  createReboundLayout,
+  createSingleFileSqueezeRail,
+  type ReboundPattern,
+} from './simple-obstacle-layout'
+import {
+  RISING_WALL_CYCLE_SECONDS,
+  RISING_WALL_DEPTH,
+  RISING_WALL_HEIGHT,
+  RISING_WALL_WIDTH,
+  createRisingWallDeck,
+  createRisingWallLayout,
+  type RisingWallDensity,
+} from './rising-wall-layout'
+import {
+  ATLAS_VORTEX_CENTER,
+  ATLAS_VORTEX_DRAIN_OUTPUT_WIDTH,
+  ATLAS_VORTEX_DRAIN_PATH,
+  ATLAS_VORTEX_DRAIN_CHANNEL,
+  ATLAS_VORTEX_ENTRY,
+  ATLAS_VORTEX_ENTRY_APPROACH,
+  ATLAS_VORTEX_OUTPUT,
+  createAtlasVortexDefinition,
+  atlasVortexDrainProfile,
+} from './atlas-vortex-layout'
+import {
+  applyRailConnectorFrames,
+  createIntersectionRailDefinitions,
+  createRoutingMergeDeck,
+  createRoutingSplitterDeck,
+  createSharedRailConnectorFrame,
+  createPublicLaneRailDefinition,
+  requiresHighSpeedMarbleCcd,
+  splitterPivotLocalPosition,
+  TRACK_LAB_FINISH_TERMINAL_HEIGHT,
+  TRACK_LAB_FINISH_WIDTH,
+  TRACK_LAB_SPLITTER_ARM_HEIGHT,
+  TRACK_LAB_SPLITTER_ARM_DEPTH,
+  TRACK_LAB_SPLITTER_ARM_LENGTH,
+  TRACK_LAB_SPLITTER_CYCLE_SECONDS,
+  TRACK_LAB_SPLITTER_SWING_RADIANS,
+  TRACK_LAB_WALL_HEIGHT,
+  type RailConnectorFrame,
+} from './track-piece-layout'
+
+export interface TrackRuntimeAdapterSuccess {
+  ok: true
+  track: TrackDefinition
+}
+
+export interface TrackRuntimeAdapterFailure {
+  ok: false
+  errors: readonly string[]
+}
+
+export type TrackRuntimeAdapterResult = TrackRuntimeAdapterSuccess | TrackRuntimeAdapterFailure
+
+export function createTrackLabRuntimeTrack(
+  document: TrackDocument,
+  compiled: CompiledTrack,
+): TrackRuntimeAdapterResult {
+  const physicsResult = createTrackLabPhysicsTrack(document, compiled)
+  if (!physicsResult.ok) return physicsResult
+
+  const unsupported = compiled.pieces.filter(piece => !hasAuthoritativeTrackLabPhysics(piece.runtimeKind))
+  if (unsupported.length > 0) {
+    return {
+      ok: false,
+      errors: unsupported.map(piece => `${piece.id} (${piece.templateId}) does not have Test Run physics yet.`),
+    }
+  }
+
+  const finish = compiled.pieces.find(piece => piece.id === compiled.route.finishPieceId)
+  const start = compiled.pieces.find(piece => piece.id === compiled.route.startPieceId)
+  if (!finish || !start) {
+    return { ok: false, errors: ['The compiled route has no start or finish piece.'] }
+  }
+  const highSpeedMarbleCcd = requiresHighSpeedMarbleCcd(document.pieces)
+
+  const connectedConnectorKeys = new Set(
+    compiled.connections.flatMap(connection => [
+      `${connection.from.pieceId}:${connection.from.connectorId}`,
+      `${connection.to.pieceId}:${connection.to.connectorId}`,
+    ]),
+  )
+  const compiledPiecesById = new Map(compiled.pieces.map(piece => [piece.id, piece]))
+  const connectorFramesByPiece = new Map<string, Map<string, RailConnectorFrame>>()
+  for (const connection of compiled.connections) {
+    const fromPiece = compiledPiecesById.get(connection.from.pieceId)
+    const toPiece = compiledPiecesById.get(connection.to.pieceId)
+    const fromConnector = fromPiece?.connectors.find(connector => connector.id === connection.from.connectorId)
+    const toConnector = toPiece?.connectors.find(connector => connector.id === connection.to.connectorId)
+    if (!fromPiece || !toPiece || !fromConnector || !toConnector) continue
+    if (fromConnector.troughProfile !== 'concave' || toConnector.troughProfile !== 'concave') continue
+    const fromSupportsCanonicalPorts = supportsCanonicalRailPorts(fromPiece)
+    const toSupportsCanonicalPorts = supportsCanonicalRailPorts(toPiece)
+    if (!fromSupportsCanonicalPorts && !toSupportsCanonicalPorts) continue
+    const sharedFrame = createSharedRailConnectorFrame(fromConnector, toConnector, fromConnector.worldDirection)
+    // A single-file squeeze owns a genuinely planar deck. Negotiate that
+    // zero-depth cross-section onto both sides of each shared terminal so the
+    // generic connector pass cannot inject a one-sample concave kink back
+    // into the visible ribbon or its matching Rapier mesh.
+    if (fromPiece.runtimeKind === 'single-file-squeeze' || toPiece.runtimeKind === 'single-file-squeeze') {
+      sharedFrame.troughDepth = 0
+    }
+    sharedFrame.position = [
+      (fromConnector.worldPosition[0] + toConnector.worldPosition[0]) / 2,
+      (fromConnector.worldPosition[1] + toConnector.worldPosition[1]) / 2,
+      (fromConnector.worldPosition[2] + toConnector.worldPosition[2]) / 2,
+    ]
+    for (const [pieceId, connectorId, supportsCanonicalPorts] of [
+      [fromPiece.id, fromConnector.id, fromSupportsCanonicalPorts],
+      [toPiece.id, toConnector.id, toSupportsCanonicalPorts],
+    ] as const) {
+      if (!supportsCanonicalPorts) continue
+      const frames = connectorFramesByPiece.get(pieceId) ?? new Map<string, RailConnectorFrame>()
+      frames.set(connectorId, sharedFrame)
+      connectorFramesByPiece.set(pieceId, frames)
+    }
+  }
+  normalizeCompoundConnectorFrames(compiled, connectorFramesByPiece)
+  const railsBySourcePiece = new Map<string, RailPieceDefinition[]>()
+  const rails = compiled.pieces.flatMap(piece => {
+    const pieceRails = createRuntimeRails(piece, connectedConnectorKeys, connectorFramesByPiece.get(piece.id))
+    railsBySourcePiece.set(piece.id, pieceRails)
+    return pieceRails
+  })
+  const materialMetricLengths = new Map(
+    compiled.pieces.map(piece => {
+      const representativeLength = Math.max(
+        0,
+        ...(railsBySourcePiece.get(piece.id) ?? []).map(rail =>
+          rail.points.slice(1).reduce((sum, point, index) => {
+            const previous = rail.points[index]!
+            return sum + Math.hypot(point[0] - previous[0], point[1] - previous[1], point[2] - previous[2])
+          }, 0),
+        ),
+      )
+      return [piece.id, representativeLength] as const
+    }),
+  )
+  const materialPhases = connectedTrackMaterialPhases(
+    compiled.pieces.map(piece => piece.id),
+    compiled.connections,
+    materialMetricLengths,
+    new Map(),
+    new Map(
+      [...railsBySourcePiece].flatMap(([pieceId, rails]) => {
+        const connectorId = rails.find(rail => rail.junctionMainConnectorId)?.junctionMainConnectorId
+        return connectorId ? [[pieceId, connectorId] as const] : []
+      }),
+    ),
+  )
+  const incomingMaterialPhase = (pieceId: string, connectorId: string): number | undefined => {
+    const connection = compiled.connections.find(
+      candidate => candidate.to.pieceId === pieceId && candidate.to.connectorId === connectorId,
+    )
+    if (!connection) return undefined
+    return (
+      (materialPhases.get(connection.from.pieceId) ?? 0) + (materialMetricLengths.get(connection.from.pieceId) ?? 0)
+    )
+  }
+  for (const [sourcePieceId, pieceRails] of railsBySourcePiece) {
+    const phase = materialPhases.get(sourcePieceId) ?? 0
+    pieceRails.forEach(rail => {
+      rail.materialConnectionPhase = rail.junctionMainConnectorId
+        ? (incomingMaterialPhase(sourcePieceId, rail.junctionMainConnectorId) ?? phase)
+        : phase
+      if (rail.junctionBranches) {
+        rail.junctionBranches = rail.junctionBranches.map(branch => ({
+          ...branch,
+          materialConnectionPhase:
+            incomingMaterialPhase(sourcePieceId, branch.connectorId) ?? branch.materialConnectionPhase,
+        }))
+      }
+    })
+  }
+  const pegFields = compiled.pieces.flatMap(piece => createRuntimePegFields(piece))
+  const vortices = compiled.pieces.flatMap(piece => createRuntimeVortices(piece, compiled))
+  const splitters = compiled.pieces.flatMap(piece => createRuntimeSplitters(piece))
+  const rebounds = compiled.pieces.flatMap(piece => createRuntimeRebounds(piece))
+  const risingWallForests = compiled.pieces.flatMap(piece => createRuntimeRisingWallForests(piece))
+  const flipperBanks = compiled.pieces.flatMap(piece => createRuntimeFlipperBanks(piece))
+  const conveyors = compiled.pieces.flatMap(piece => createRuntimeConveyors(piece))
+  const portals = createRuntimePortals(document, compiled)
+  const finishDirection = rotateVector([0, 0, -1], finish.transform.yawSteps)
+  const finishCenter = transformLocalPoint([0, -2, -2], finish)
+  const finishInput =
+    finish.connectors.find(connector => connector.kind.endsWith('input'))?.worldPosition ?? finishCenter
+  const channelEnd = addVector(finishCenter, scaleVector(finishDirection, 10))
+  channelEnd[1] -= 0.7
+  rails.push(
+    applyRailConnectorFrames(
+      {
+        id: `${finish.id}-channel`,
+        label: 'Continuous narrowing ranked finish channel',
+        type: 'rail',
+        raceRole: 'finish',
+        materialConnectionPhase: materialPhases.get(finish.id) ?? 0,
+        ...(finish.appearance ? { appearance: finish.appearance } : {}),
+        points: [finishInput, finishCenter, channelEnd],
+        width: TRACK_LAB_FINISH_WIDTH,
+        pointWidths: [4, TRACK_LAB_FINISH_WIDTH, TRACK_LAB_FINISH_WIDTH],
+        troughDepth: defaultTrackTroughDepth(TRACK_LAB_FINISH_WIDTH),
+        pointTroughDepths: [
+          defaultTrackTroughDepth(4),
+          defaultTrackTroughDepth(TRACK_LAB_FINISH_WIDTH),
+          defaultTrackTroughDepth(TRACK_LAB_FINISH_WIDTH),
+        ],
+        troughProfile: 'full',
+        wallHeight: TRACK_LAB_WALL_HEIGHT,
+        wallColliderHeight: highSpeedMarbleCcd ? TRACK_LAB_FINISH_TERMINAL_HEIGHT : TRACK_LAB_WALL_HEIGHT,
+        // A single-file taper can hold two side-by-side rigid marbles as a
+        // self-locking wedge. The guide walls stay polished while the deck
+        // retains the ordinary rolling grip used by the visible finish lane.
+        floorFriction: 0.06,
+        wallFriction: 0,
+        closedEnd: true,
+        closedEndHeight: highSpeedMarbleCcd ? TRACK_LAB_FINISH_TERMINAL_HEIGHT : TRACK_LAB_WALL_HEIGHT,
+      },
+      finish.connectors.map(connector => ({
+        ...connector,
+        localPosition: connector.worldPosition,
+        localDirection: connector.worldDirection,
+      })),
+      new Set(
+        finish.connectors
+          .filter(connector => connectedConnectorKeys.has(`${finish.id}:${connector.id}`))
+          .map(connector => connector.id),
+      ),
+      connectorFramesByPiece.get(finish.id),
+    ),
+  )
+  rails.forEach(rail => {
+    rail.verticalWalls = true
+  })
+
+  const startEntry = rails.find(rail => rail.id === start.id)?.points[0] ?? start.transform.position
+  const guidePoints = createRuntimeGuide(compiled, startEntry, finishCenter, channelEnd)
+  if (guidePoints.length < 2) {
+    return { ok: false, errors: ['The primary route could not produce a runtime guide.'] }
+  }
+
+  const presentationTrack: TrackDefinition = {
+    id: `track-lab-${compiled.simulationHash}`,
+    version: 1,
+    highSpeedMarbleCcd,
+    label: document.metadata.title,
+    description: document.metadata.description,
+    targetDurationSeconds: document.settings.targetDurationSeconds,
+    spawnProgress: Math.min(0.8, guidePoints.at(-1)!.progress * 0.08),
+    spawnWidth: widthFromPiece(start),
+    themeId: document.presentation.defaultThemeId,
+    skin: NEUTRAL_STUDIO_SKIN,
+    pieces: [
+      ...rails,
+      ...pegFields,
+      ...vortices,
+      ...splitters,
+      ...rebounds,
+      ...risingWallForests,
+      ...flipperBanks,
+      ...conveyors,
+      ...portals,
+      {
+        id: finish.id,
+        label: 'Track Lab finish',
+        type: 'finish',
+        center: finishCenter,
+        direction: finishDirection,
+        width: TRACK_LAB_FINISH_WIDTH,
+        channelEnd,
+        rankingSlots: Math.min(6, document.settings.spawnMarbleCapacity),
+        rankingSpacing: 1.22,
+      },
+    ],
+    cameraPath: {
+      id: 'track-lab-camera',
+      points: guidePoints.map(point => ({
+        ...point,
+        position: [point.position[0], point.position[1] + 0.8, point.position[2]],
+      })),
+    },
+    projectionPaths: [
+      {
+        id: 'track-lab-primary-route',
+        points: guidePoints,
+      },
+    ],
+  }
+  // Keep authored visual context available to renderers without changing the
+  // serialized simulation definition or its deterministic fingerprint.
+  const track = decoratePhysicsTrack(physicsResult.track, presentationTrack)
+  Object.defineProperty(track, 'sourceDocument', {
+    configurable: false,
+    enumerable: false,
+    value: document,
+  })
+  return {
+    ok: true,
+    track,
+  }
+}
+
+/**
+ * The runtime is allowed to decorate authoritative definitions, never to
+ * supply their physical values. Keeping the allowlist here means drift in a
+ * renderer-side layout helper cannot silently change a race result.
+ */
+function decoratePhysicsTrack(physics: PhysicsTrackDefinition, presentation: TrackDefinition): TrackDefinition {
+  const presentationByKey = new Map(presentation.pieces.map(piece => [`${piece.type}:${piece.id}`, piece] as const))
+  const pieces = physics.pieces.map(piece => {
+    const visual = presentationByKey.get(`${piece.type}:${piece.id}`)
+    if (!visual) throw new Error(`Runtime presentation is missing ${piece.type}:${piece.id}`)
+    return decoratePhysicsPiece(piece, visual)
+  })
+  return {
+    ...physics,
+    label: presentation.label,
+    description: presentation.description,
+    targetDurationSeconds: presentation.targetDurationSeconds,
+    ...(presentation.themeId ? { themeId: presentation.themeId } : {}),
+    skin: presentation.skin,
+    pieces,
+    cameraPath: physics.cameraPath,
+    projectionPaths: physics.projectionPaths,
+  }
+}
+
+function decoratePhysicsPiece(
+  physics: PhysicsTrackPieceDefinition,
+  visual: TrackPieceDefinition,
+): TrackPieceDefinition {
+  const base = {
+    ...physics,
+    label: visual.label,
+    ...(visual.appearance ? { appearance: visual.appearance } : {}),
+    ...(visual.materialConnectionPhase !== undefined
+      ? { materialConnectionPhase: visual.materialConnectionPhase }
+      : {}),
+    ...(visual.deferStoneArchitectureUntilMaterialContinuity !== undefined
+      ? { deferStoneArchitectureUntilMaterialContinuity: visual.deferStoneArchitectureUntilMaterialContinuity }
+      : {}),
+  }
+  if (physics.type === 'rail' && visual.type === 'rail') {
+    const junctionBranches = physics.junctionBranches?.map(branch => {
+      const visualBranch = visual.junctionBranches?.find(candidate => candidate.connectorId === branch.connectorId)
+      return {
+        ...branch,
+        ...(visualBranch?.materialConnectionPhase !== undefined
+          ? { materialConnectionPhase: visualBranch.materialConnectionPhase }
+          : {}),
+        ...(visualBranch?.waterFlowStartConnected !== undefined
+          ? { waterFlowStartConnected: visualBranch.waterFlowStartConnected }
+          : {}),
+      }
+    })
+    const centerDivider = physics.centerDivider
+      ? {
+          ...physics.centerDivider,
+          ...(visual.centerDivider?.visualRole ? { visualRole: visual.centerDivider.visualRole } : {}),
+        }
+      : undefined
+    return {
+      ...base,
+      ...(visual.materialConnectors ? { materialConnectors: visual.materialConnectors } : {}),
+      ...(visual.previewProfileSamplePitch !== undefined
+        ? { previewProfileSamplePitch: visual.previewProfileSamplePitch }
+        : {}),
+      ...(visual.waterFlowStartConnected !== undefined
+        ? { waterFlowStartConnected: visual.waterFlowStartConnected }
+        : {}),
+      ...(visual.waterFlowEndConnected !== undefined ? { waterFlowEndConnected: visual.waterFlowEndConnected } : {}),
+      ...(visual.continuousFloorMaterialOnly !== undefined
+        ? { continuousFloorMaterialOnly: visual.continuousFloorMaterialOnly }
+        : {}),
+      ...(visual.raceRole ? { raceRole: visual.raceRole } : {}),
+      ...(visual.railroadProfile ? { railroadProfile: visual.railroadProfile } : {}),
+      ...(junctionBranches ? { junctionBranches } : {}),
+      ...(centerDivider ? { centerDivider } : {}),
+    } as unknown as TrackPieceDefinition
+  }
+  if (physics.type === 'vortex' && visual.type === 'vortex') {
+    return {
+      ...base,
+      ...(visual.waterFlowInputConnected !== undefined
+        ? { waterFlowInputConnected: visual.waterFlowInputConnected }
+        : {}),
+    } as unknown as TrackPieceDefinition
+  }
+  if (physics.type === 'portal' && visual.type === 'portal') {
+    return {
+      ...base,
+      color: visual.color,
+      entryVisualCenter: visual.entryVisualCenter,
+      entryVisualDirection: visual.entryVisualDirection,
+      exitVisualCenter: visual.exitVisualCenter,
+      exitVisualDirection: visual.exitVisualDirection,
+      ...(visual.entryVisualStyle ? { entryVisualStyle: visual.entryVisualStyle } : {}),
+      ...(visual.exitVisualStyle ? { exitVisualStyle: visual.exitVisualStyle } : {}),
+    } as unknown as TrackPieceDefinition
+  }
+  if (physics.type === 'finish' && visual.type === 'finish') {
+    return {
+      ...base,
+      channelEnd: visual.channelEnd,
+      rankingSlots: visual.rankingSlots,
+      rankingSpacing: visual.rankingSpacing,
+    } as unknown as TrackPieceDefinition
+  }
+  return base as TrackPieceDefinition
+}
+
+function connectorFramePitch(frame: RailConnectorFrame): number {
+  const [x, y, z] = frame.tangent
+  return Math.abs(y) / Math.max(0.000_001, Math.hypot(x, z))
+}
+
+/**
+ * A compound split/merge deck owns one broad planar terminal, so its two
+ * branch ports cannot carry different terminal pitches simultaneously. Use
+ * the steepest negotiated branch frame for that shared plane and propagate
+ * only its tangent back to both connected neighbors. Width and trough profile
+ * remain specific to each connection.
+ */
+export function normalizeCompoundConnectorFrames(
+  compiled: Pick<CompiledTrack, 'pieces' | 'connections'>,
+  connectorFramesByPiece: Map<string, Map<string, RailConnectorFrame>>,
+): void {
+  const piecesById = new Map(compiled.pieces.map(piece => [piece.id, piece]))
+  for (const piece of compiled.pieces) {
+    const compoundRole =
+      piece.runtimeKind === 'splitter' ? 'output' : piece.runtimeKind === 'merge' ? 'input' : undefined
+    if (!compoundRole) continue
+
+    const connectorIds = piece.connectors
+      .filter(connector => connector.role === compoundRole)
+      .map(connector => connector.id)
+    const pieceFrames = connectorFramesByPiece.get(piece.id)
+    const connectedFrames = connectorIds
+      .map(connectorId => pieceFrames?.get(connectorId))
+      .filter((frame): frame is RailConnectorFrame => frame !== undefined)
+    if (connectedFrames.length < 2) continue
+    const sharedTangent = connectedFrames.reduce((steepest, frame) =>
+      connectorFramePitch(frame) > connectorFramePitch(steepest) ? frame : steepest,
+    ).tangent
+
+    for (const connectorId of connectorIds) {
+      const compoundFrame = pieceFrames?.get(connectorId)
+      if (compoundFrame) pieceFrames!.set(connectorId, { ...compoundFrame, tangent: sharedTangent })
+      const connection = compiled.connections.find(
+        candidate =>
+          (candidate.from.pieceId === piece.id && candidate.from.connectorId === connectorId) ||
+          (candidate.to.pieceId === piece.id && candidate.to.connectorId === connectorId),
+      )
+      if (!connection) continue
+      const neighbourEndpoint =
+        connection.from.pieceId === piece.id && connection.from.connectorId === connectorId
+          ? connection.to
+          : connection.from
+      const neighbourPiece = piecesById.get(neighbourEndpoint.pieceId)
+      if (!neighbourPiece || !supportsCanonicalRailPorts(neighbourPiece)) continue
+      const neighbourFrames = connectorFramesByPiece.get(neighbourPiece.id)
+      const neighbourFrame = neighbourFrames?.get(neighbourEndpoint.connectorId)
+      if (neighbourFrame) {
+        neighbourFrames!.set(neighbourEndpoint.connectorId, { ...neighbourFrame, tangent: sharedTangent })
+      }
+    }
+  }
+}
+
+function createRuntimePortals(document: TrackDocument, compiled: CompiledTrack): PortalPieceDefinition[] {
+  const compiledById = new Map(compiled.pieces.map(piece => [piece.id, piece]))
+  return collectCompletePortalPairs(document).flatMap(pair => {
+    const entry = compiledById.get(pair.entry.id)
+    const exit = compiledById.get(pair.exit.id)
+    if (!entry || !exit) return []
+    return [
+      {
+        id: `portal-${pair.pairId}`,
+        label: `Portal Pair ${portalPairNumber(pair.pairId)}`,
+        type: 'portal',
+        entryVisualStyle: portalVisualStyleFromId(entry.appearance?.portalVisualId),
+        exitVisualStyle: portalVisualStyleFromId(exit.appearance?.portalVisualId),
+        color: portalPairColor(pair.pairId),
+        entry: transformLocalPoint([0, 1.65, 0], entry),
+        entryDirection: rotateVector([0, 0, 1], entry.transform.yawSteps),
+        exit: transformLocalPoint([0, 0.65, -0.75], exit),
+        exitDirection: rotateVector([0, 0, -1], exit.transform.yawSteps),
+        entryVisualCenter: transformLocalPoint([0, 1.65, 0], entry),
+        entryVisualDirection: rotateVector([0, 0, 1], entry.transform.yawSteps),
+        exitVisualCenter: transformLocalPoint([0, 1.65, 0], exit),
+        exitVisualDirection: rotateVector([0, 0, -1], exit.transform.yawSteps),
+        captureHalfExtents: [1.96, 1.7, 0.48],
+        releaseSpeed: 2.4,
+      },
+    ]
+  })
+}
+
+function createRuntimeConveyors(piece: CompiledTrackPiece): ConveyorPieceDefinition[] {
+  if (piece.runtimeKind !== 'conveyor') return []
+  return [
+    {
+      id: piece.id,
+      label: piece.templateId,
+      type: 'conveyor',
+      bottom: transformLocalPoint(TRACK_LAB_CONVEYOR_BOTTOM, piece),
+      top: transformLocalPoint(TRACK_LAB_CONVEYOR_TOP, piece),
+      direction: rotateVector(TRACK_LAB_CONVEYOR_DIRECTION, piece.transform.yawSteps),
+      width: TRACK_LAB_CONVEYOR_WIDTH,
+      shelfDepth: TRACK_LAB_CONVEYOR_SHELF_DEPTH,
+      shelfCount: TRACK_LAB_CONVEYOR_SHELF_COUNT,
+      speed: TRACK_LAB_CONVEYOR_SPEED,
+      friction: 1.4,
+      shelfTiltRadians: TRACK_LAB_CONVEYOR_SHELF_TILT_RADIANS,
+      releaseHeight: transformLocalPoint(TRACK_LAB_CONVEYOR_RELEASE, piece)[1],
+      phaseIndex: 2,
+    },
+  ]
+}
+
+function createRuntimeVortices(piece: CompiledTrackPiece, compiled: CompiledTrack): VortexPieceDefinition[] {
+  if (piece.runtimeKind !== 'vortex') return []
+  const input = piece.connectors.find(connector => connector.kind.endsWith('input'))
+  const waterFlowInputConnected = input
+    ? compiled.connections.some(connection => {
+        const otherEndpoint =
+          connection.to.pieceId === piece.id && connection.to.connectorId === input.id
+            ? connection.from
+            : connection.from.pieceId === piece.id && connection.from.connectorId === input.id
+              ? connection.to
+              : undefined
+        if (!otherEndpoint) return false
+        const otherPiece = compiled.pieces.find(candidate => candidate.id === otherEndpoint.pieceId)
+        return (
+          fluidSurfaceStyleFromId(otherPiece?.appearance?.waterOverlayId) !== undefined &&
+          fluidSurfaceStyleFromId(otherPiece?.appearance?.waterOverlayId) ===
+            fluidSurfaceStyleFromId(piece.appearance?.vortexWaterId)
+        )
+      })
+    : false
+  return [
+    {
+      ...createAtlasVortexDefinition(
+        piece.id,
+        transformLocalPoint(ATLAS_VORTEX_CENTER, piece),
+        transformLocalPoint(ATLAS_VORTEX_ENTRY, piece),
+        transformLocalPoint(ATLAS_VORTEX_DRAIN_CHANNEL, piece),
+        rotateVector(
+          [
+            ATLAS_VORTEX_OUTPUT[0] - ATLAS_VORTEX_DRAIN_CHANNEL[0],
+            ATLAS_VORTEX_OUTPUT[1] - ATLAS_VORTEX_DRAIN_CHANNEL[1],
+            ATLAS_VORTEX_OUTPUT[2] - ATLAS_VORTEX_DRAIN_CHANNEL[2],
+          ],
+          piece.transform.yawSteps,
+        ),
+      ),
+      ...(piece.appearance ? { appearance: piece.appearance } : {}),
+      waterFlowInputConnected,
+    },
+  ]
+}
+
+function createRuntimeSplitters(piece: CompiledTrackPiece): SplitterPieceDefinition[] {
+  if (piece.runtimeKind !== 'splitter') return []
+  const drop = laneGradeDrop({ ...piece.parameters, grade: piece.parameters.grade ?? 'slope', lengthUnits: 1 })
+  return [
+    {
+      id: piece.id,
+      label: piece.templateId,
+      type: 'splitter',
+      ...(piece.appearance ? { appearance: piece.appearance } : {}),
+      center: transformLocalPoint(splitterPivotLocalPosition(drop), piece),
+      capture: transformLocalPoint([0, 0.1 - drop * 0.32, 0.9], piece),
+      direction: rotateVector([0, -drop, -5], piece.transform.yawSteps),
+      surfaceAligned: true,
+      captureRadius: 3.15,
+      barLength: TRACK_LAB_SPLITTER_ARM_LENGTH,
+      barHeight: TRACK_LAB_SPLITTER_ARM_HEIGHT,
+      barDepth: TRACK_LAB_SPLITTER_ARM_DEPTH,
+      swingRadians: TRACK_LAB_SPLITTER_SWING_RADIANS,
+      cycleSeconds: TRACK_LAB_SPLITTER_CYCLE_SECONDS,
+      phaseIndex: 0,
+    },
+  ]
+}
+
+function createRuntimeRebounds(piece: CompiledTrackPiece): ReboundPieceDefinition[] {
+  if (piece.runtimeKind !== 'rebounds') return []
+  const layout = createReboundLayout(lengthUnitsFromPiece(piece), piece.parameters, reboundPatternFromPiece(piece))
+  return [
+    {
+      id: `${piece.id}-rebounds`,
+      label: piece.templateId,
+      type: 'rebounds',
+      direction: rotateVector(layout.direction, piece.transform.yawSteps),
+      mounts: layout.mounts.map(mount => ({
+        anchor: transformLocalPoint(mount.anchor, piece),
+        angle: mount.angle,
+        side: mount.side,
+      })),
+      reboundLength: REBOUND_LENGTH,
+      reboundWidth: REBOUND_WIDTH,
+      reboundHeight: REBOUND_HEIGHT,
+      friction: 0.01,
+      restitution: REBOUND_RESTITUTION,
+      strikeDistance: REBOUND_STRIKE_DISTANCE,
+      strikeSeconds: REBOUND_STRIKE_SECONDS,
+      holdSeconds: REBOUND_HOLD_SECONDS,
+      returnSeconds: REBOUND_RETURN_SECONDS,
+      cooldownSeconds: REBOUND_COOLDOWN_SECONDS,
+      ...(piece.appearance ? { appearance: piece.appearance } : {}),
+    },
+  ]
+}
+
+function createRuntimeRisingWallForests(piece: CompiledTrackPiece): RisingWallForestPieceDefinition[] {
+  if (piece.runtimeKind !== 'rising-wall-forest') return []
+  const layout = createRisingWallLayout(lengthUnitsFromPiece(piece), piece.parameters)
+  return [
+    {
+      id: piece.id,
+      label: piece.templateId,
+      type: 'rising-wall-forest',
+      direction: rotateVector(layout.direction, piece.transform.yawSteps),
+      anchors: layout.anchors.map(anchor => ({
+        ...anchor,
+        position: transformLocalPoint(anchor.position, piece),
+      })),
+      rows: layout.rows,
+      columns: layout.columns,
+      density: risingWallDensityFromPiece(piece),
+      wallWidth: RISING_WALL_WIDTH,
+      wallHeight: RISING_WALL_HEIGHT,
+      wallDepth: RISING_WALL_DEPTH,
+      cycleSeconds: RISING_WALL_CYCLE_SECONDS,
+    },
+  ]
+}
+
+function createRuntimeFlipperBanks(piece: CompiledTrackPiece): FlipperBankPieceDefinition[] {
+  if (piece.runtimeKind !== 'flipper-bank') return []
+  const layout = createFlipperBankLayout(lengthUnitsFromPiece(piece), gradeFromPiece(piece))
+  const direction = rotateVector(layout.direction, piece.transform.yawSteps)
+  return [
+    {
+      id: piece.id,
+      label: piece.templateId,
+      type: 'flipper-bank',
+      ...(piece.appearance ? { appearance: piece.appearance } : {}),
+      direction,
+      mounts: layout.mounts.map(mount => ({
+        anchor: transformLocalPoint(mount.anchor, piece),
+        direction,
+        side: mount.side,
+      })),
+      paddleLength: CANONICAL_FLIPPER_DIMENSIONS.length,
+      paddleWidth: CANONICAL_FLIPPER_DIMENSIONS.width,
+      paddleHeight: CANONICAL_FLIPPER_DIMENSIONS.height,
+      // Grade changes the deck plane, never the mechanism's forward direction
+      // or strike envelope. A former flat-only 1 radian sweep could launch
+      // marbles over the wall while the same bank was safe when sloped.
+      swingRadians: CANONICAL_FLIPPER_SWEEP_RADIANS,
+      // Stay within the canonical passive tip-speed bound without leaving a
+      // multi-marble bank dormant for several seconds between strokes.
+      strikeSeconds: FLIPPER_MINIMUM_ONE_WAY_SWEEP_SECONDS,
+      holdSeconds: 0.05,
+      returnSeconds: 0.7,
+      minimumIntervalSeconds: 0.35,
+      maximumIntervalSeconds: 0.85,
+    },
+  ]
+}
+
+function createRuntimePegFields(piece: CompiledTrackPiece): PegFieldPieceDefinition[] {
+  if (piece.runtimeKind !== 'peg-field') return []
+  const layout = createConeFieldLayout(lengthUnitsFromPiece(piece), conePatternFromPiece(piece), gradeFromPiece(piece))
+  return [
+    {
+      id: `${piece.id}-pegs`,
+      label: piece.templateId,
+      type: 'peg-field',
+      direction: rotateVector(layout.direction, piece.transform.yawSteps),
+      pegs: layout.pegBases.map(base =>
+        addVector(piece.transform.position, rotateVector(base, piece.transform.yawSteps)),
+      ),
+      pegRadius: CONE_FIELD_PEG_RADIUS,
+      pegHeight: CONE_FIELD_PEG_HEIGHT,
+      colliderShape: 'cone',
+      friction: 0.02,
+      restitution: 0.08,
+      ...(piece.appearance ? { appearance: piece.appearance } : {}),
+    },
+  ]
+}
+
+function createRuntimeRails(
+  piece: CompiledTrackPiece,
+  connectedConnectorKeys: ReadonlySet<string>,
+  connectorFrames: ReadonlyMap<string, RailConnectorFrame> = new Map(),
+): RailPieceDefinition[] {
+  const connectedConnectorIds = new Set(
+    piece.connectors
+      .filter(connector => connectedConnectorKeys.has(`${piece.id}:${connector.id}`))
+      .map(connector => connector.id),
+  )
+  const worldConnectors = piece.connectors.map(connector => ({
+    ...connector,
+    localPosition: connector.worldPosition,
+    localDirection: connector.worldDirection,
+  }))
+  return createUnframedRuntimeRails(piece).map(rail => {
+    const framed = applyRailConnectorFrames(rail, worldConnectors, connectedConnectorIds, connectorFrames)
+    const junctionBranches = framed.junctionBranches?.map(branch => {
+      const connectorFrame = connectorFrames.get(branch.connectorId)
+      return {
+        ...branch,
+        points: connectorFrame?.position ? [connectorFrame.position, ...branch.points.slice(1)] : branch.points,
+        startTangent: connectorFrame?.tangent ?? branch.startTangent,
+      }
+    })
+    return {
+      ...framed,
+      materialConnectors: piece.connectors.map(connector => ({
+        id: connector.id,
+        position: connector.worldPosition,
+      })),
+      ...(junctionBranches ? { junctionBranches } : {}),
+      ...(piece.appearance || framed.appearance ? { appearance: { ...piece.appearance, ...framed.appearance } } : {}),
+    }
+  })
+}
+
+function createUnframedRuntimeRails(piece: CompiledTrackPiece): RailPieceDefinition[] {
+  if (piece.runtimeKind === 'finish') return []
+  const input = piece.connectors.find(connector => connector.kind.endsWith('input'))
+  const output = piece.connectors.find(connector => connector.kind.endsWith('output'))
+  if (piece.runtimeKind === 'single-file-squeeze') {
+    return [transformLocalRail(createSingleFileSqueezeRail(piece.id, piece.templateId, piece.parameters), piece)]
+  }
+  if (piece.runtimeKind === 'rebounds') {
+    return [
+      transformLocalRail(
+        createReboundDeck(piece.id, piece.templateId, lengthUnitsFromPiece(piece), piece.parameters),
+        piece,
+      ),
+    ]
+  }
+  if (piece.runtimeKind === 'rising-wall-forest') {
+    const layout = createRisingWallLayout(lengthUnitsFromPiece(piece), piece.parameters)
+    return [transformLocalRail(createRisingWallDeck(`${piece.id}-deck`, piece.templateId, layout), piece)]
+  }
+  if (piece.runtimeKind === 'portal-entry-preview' && input) {
+    return [
+      {
+        id: `${piece.id}-deck`,
+        label: 'Portal entry channel',
+        type: 'rail',
+        points: [input.worldPosition, transformLocalPoint([0, 0, 0], piece)],
+        width: 4,
+        troughDepth: defaultTrackTroughDepth(4),
+        troughProfile: 'full',
+        wallHeight: TRACK_LAB_WALL_HEIGHT,
+        floorFriction: 0.04,
+      },
+    ]
+  }
+  if (piece.runtimeKind === 'portal-exit-preview' && output) {
+    return [
+      {
+        id: `${piece.id}-deck`,
+        label: 'Portal exit channel',
+        type: 'rail',
+        points: [transformLocalPoint([0, 0, 0], piece), output.worldPosition],
+        width: 4,
+        troughDepth: defaultTrackTroughDepth(4),
+        troughProfile: 'full',
+        wallHeight: TRACK_LAB_WALL_HEIGHT,
+        floorFriction: 0.04,
+      },
+    ]
+  }
+  if (piece.runtimeKind === 'conveyor' && input && output) {
+    return [
+      {
+        id: `${piece.id}-approach`,
+        label: 'Conveyor approach channel',
+        type: 'rail',
+        points: [input.worldPosition, transformLocalPoint(TRACK_LAB_CONVEYOR_LOADING, piece)],
+        startWidth: 4,
+        width: TRACK_LAB_CONVEYOR_WIDTH,
+        startTroughDepth: defaultTrackTroughDepth(4),
+        troughDepth: defaultTrackTroughDepth(TRACK_LAB_CONVEYOR_WIDTH),
+        troughProfile: 'full',
+        wallHeight: TRACK_LAB_WALL_HEIGHT,
+        continuousFloorMaterialOnly: true,
+        floorFriction: 0.08,
+      },
+      {
+        id: `${piece.id}-release`,
+        label: 'Conveyor release channel',
+        type: 'rail',
+        points: [transformLocalPoint(TRACK_LAB_CONVEYOR_RELEASE, piece), output.worldPosition],
+        startWidth: TRACK_LAB_CONVEYOR_WIDTH,
+        width: 4,
+        startTroughDepth: defaultTrackTroughDepth(TRACK_LAB_CONVEYOR_WIDTH),
+        troughDepth: defaultTrackTroughDepth(4),
+        troughProfile: 'full',
+        wallHeight: TRACK_LAB_WALL_HEIGHT,
+        floorFriction: 0.08,
+      },
+    ]
+  }
+  if (piece.runtimeKind === 'vortex' && input && output) {
+    return [
+      {
+        id: `${piece.id}-entry`,
+        label: 'Atlas vortex tangential entry',
+        type: 'rail',
+        points: [input.worldPosition, ...ATLAS_VORTEX_ENTRY_APPROACH.map(point => transformLocalPoint(point, piece))],
+        width: 4,
+        troughDepth: defaultTrackTroughDepth(4),
+        troughProfile: 'full',
+        wallHeight: TRACK_LAB_WALL_HEIGHT,
+        floorFriction: 0.08,
+        supportsAppearanceCanopy: false,
+      },
+      {
+        id: `${piece.id}-drain`,
+        label: 'Continuous Atlas vortex catch and single-file drain',
+        type: 'rail',
+        points: ATLAS_VORTEX_DRAIN_PATH.map((point, index, points) =>
+          index === points.length - 1 ? output.worldPosition : transformLocalPoint(point, piece),
+        ),
+        width: ATLAS_VORTEX_DRAIN_OUTPUT_WIDTH,
+        pointWidths: atlasVortexDrainProfile(),
+        widthProfile: 'smoothstep',
+        troughDepth: defaultTrackTroughDepth(ATLAS_VORTEX_DRAIN_OUTPUT_WIDTH),
+        pointTroughDepths: atlasVortexDrainProfile().map(defaultTrackTroughDepth),
+        troughProfile: 'full',
+        troughFlatFraction: 0,
+        wallHeight: TRACK_LAB_WALL_HEIGHT,
+        continuousFloorMaterialOnly: true,
+        supportsAppearanceCanopy: false,
+        // This is an exposed Vortex-owned catch terminal, not a rail seam.
+        // Cap the floor and side-wall volumes without adding a cross-wall
+        // behind the funnel bore.
+        capStart: true,
+        floorFriction: 0.02,
+        wallFriction: 0,
+        waterFlowStartConnected: Boolean(piece.appearance?.vortexWaterId),
+        ...(piece.appearance?.vortexWaterId
+          ? { appearance: { ...piece.appearance, waterOverlayId: piece.appearance.vortexWaterId } }
+          : {}),
+      },
+    ]
+  }
+  if (piece.runtimeKind === 'splitter' && input) {
+    const outputs = piece.connectors.filter(connector => connector.kind.endsWith('output'))
+    if (outputs.length === 0) return []
+    return [
+      transformLocalRail(
+        createRoutingSplitterDeck(`${piece.id}-deck`, 'Splitter routing deck', -outputs[0]!.localPosition[1]),
+        piece,
+      ),
+    ]
+  }
+  if (piece.runtimeKind === 'merge' && output) {
+    return [
+      transformLocalRail(createRoutingMergeDeck(piece.id, 'Route merge catch deck', -output.localPosition[1]), piece),
+    ]
+  }
+  if (piece.runtimeKind === 'intersection' && output) {
+    // Intersection topology belongs to the template, not to transient
+    // connection state. Every authored input must remain present so attaching
+    // or detaching a neighbour cannot regenerate the piece's floor and walls.
+    const inputs = piece.connectors.filter(connector => connector.kind.endsWith('input'))
+    if (inputs.length === 0) return []
+    return createIntersectionRailDefinitions(
+      piece.id,
+      piece.templateId,
+      inputs.map(connector => ({
+        id: connector.id,
+        localPosition: connector.worldPosition,
+        localDirection: connector.worldDirection,
+      })),
+      {
+        id: output.id,
+        localPosition: output.worldPosition,
+        localDirection: output.worldDirection,
+      },
+    )
+  }
+  if (piece.runtimeKind === 'flipper-bank' && input && output) {
+    return [
+      transformLocalRail(
+        createFlipperBankDeck(
+          `${piece.id}-deck`,
+          'Continuous enclosed flipper deck',
+          lengthUnitsFromPiece(piece),
+          gradeFromPiece(piece),
+        ),
+        piece,
+      ),
+    ]
+  }
+  if (piece.runtimeKind === 'peg-field' && input && output) {
+    const layout = createConeFieldLayout(
+      lengthUnitsFromPiece(piece),
+      conePatternFromPiece(piece),
+      gradeFromPiece(piece),
+    )
+    const deckProfile = createConeFieldDeckProfile(layout, defaultTrackTroughDepth(4))
+    return [
+      {
+        id: `${piece.id}-deck`,
+        label: 'Continuous enclosed cone forest deck',
+        type: 'rail',
+        points: deckProfile.points.map(point => transformLocalPoint(point, piece)),
+        width: 4,
+        pointWidths: [...deckProfile.pointWidths],
+        troughDepth: defaultTrackTroughDepth(4),
+        pointTroughDepths: [...deckProfile.pointTroughDepths],
+        troughProfile: 'full',
+        wallHeight: TRACK_LAB_WALL_HEIGHT,
+        // The passive cone field depends on the obstacles for deflection; the
+        // deck and widening shoulders must not arrest a low-energy handoff.
+        // These physical values are piece semantics and never vary by theme or
+        // appearance material.
+        floorFriction: 0.006,
+        wallFriction: 0,
+      },
+    ]
+  }
+  const publicLane = createPublicLaneRailDefinition({
+    id: piece.id,
+    templateId: piece.templateId,
+    runtimeKind: piece.runtimeKind,
+    parameters: piece.parameters,
+  })
+  if (publicLane) {
+    return [
+      {
+        ...publicLane,
+        points: publicLane.points.map(point => transformLocalPoint(point, piece)),
+      },
+    ]
+  }
+  const points: TrackVector[] = []
+
+  if (piece.runtimeKind === 'start') {
+    const direction = rotateVector([0, 0, 1], piece.transform.yawSteps)
+    const entry = addVector(piece.transform.position, scaleVector(direction, 4))
+    entry[1] += 1.2
+    points.push(entry)
+    if (output) points.push([...output.worldPosition])
+  } else if (input && output) {
+    points.push([...input.worldPosition])
+    points.push([...output.worldPosition])
+  }
+
+  if (points.length < 2) return []
+  const width = piece.runtimeKind === 'start' ? 4 : widthFromPiece(piece)
+  return [
+    {
+      id: piece.id,
+      label: piece.templateId,
+      type: 'rail',
+      ...(piece.runtimeKind === 'start' ? { raceRole: 'start' as const } : {}),
+      points,
+      width,
+      ...(piece.runtimeKind === 'start' ? { startWidth: 6 } : {}),
+      ...(piece.runtimeKind === 'start' ? { startTroughDepth: defaultTrackTroughDepth(6) } : {}),
+      troughDepth: defaultTrackTroughDepth(width),
+      wallHeight: TRACK_LAB_WALL_HEIGHT,
+      floorFriction: 0.08,
+    },
+  ]
+}
+
+function transformLocalPoint(point: TrackVector, piece: CompiledTrackPiece): TrackVector {
+  return addVector(piece.transform.position, rotateVector(point, piece.transform.yawSteps))
+}
+
+function transformLocalRail(rail: RailPieceDefinition, piece: CompiledTrackPiece): RailPieceDefinition {
+  return {
+    ...rail,
+    points: rail.points.map(point => transformLocalPoint(point, piece)),
+    startTangent: rail.startTangent ? rotateVector(rail.startTangent, piece.transform.yawSteps) : undefined,
+    endTangent: rail.endTangent ? rotateVector(rail.endTangent, piece.transform.yawSteps) : undefined,
+  }
+}
+
+function createRuntimeGuide(
+  compiled: CompiledTrack,
+  startEntry: TrackVector,
+  finishCenter: TrackVector,
+  channelEnd: TrackVector,
+): TrackGuidePoint[] {
+  const source = [
+    { pieceId: compiled.route.startPieceId, position: [...startEntry] as TrackVector },
+    ...compiled.projectionGuide.map(point => ({
+      pieceId: point.pieceId,
+      position: [...point.position] as TrackVector,
+    })),
+    { pieceId: compiled.route.finishPieceId, position: [...finishCenter] as TrackVector },
+    { pieceId: compiled.route.finishPieceId, position: [...channelEnd] as TrackVector },
+  ]
+  const guide: TrackGuidePoint[] = []
+  let progress = 0
+  for (const point of source) {
+    const previous = guide.at(-1)
+    if (previous) {
+      const distance = distanceBetween(previous.position, point.position)
+      if (distance < 0.001) continue
+      progress += distance
+    }
+    guide.push({ ...point, progress: Number(progress.toFixed(6)) })
+  }
+  return guide
+}
+
+function widthFromPiece(piece: CompiledTrackPiece): number {
+  const width = piece.parameters.width
+  if (typeof width === 'string') return trackWidthParameterUnits(width)
+  if (piece.runtimeKind === 'start') return 6
+  if (piece.runtimeKind === 'peg-field') return CONE_FIELD_WIDTH
+  return 4
+}
+
+function lengthUnitsFromPiece(piece: CompiledTrackPiece): number {
+  const value = piece.parameters.lengthUnits
+  return typeof value === 'number' && Number.isFinite(value) ? value : 1
+}
+
+function gradeFromPiece(piece: CompiledTrackPiece): 'flat' | 'slope' | 'steep' {
+  return piece.parameters.grade === 'flat' || piece.parameters.grade === 'steep' ? piece.parameters.grade : 'slope'
+}
+
+function conePatternFromPiece(piece: CompiledTrackPiece): 'classic' | 'dense' {
+  return piece.parameters.pattern === 'classic' ? 'classic' : 'dense'
+}
+
+function reboundPatternFromPiece(piece: CompiledTrackPiece): ReboundPattern {
+  return piece.parameters.pattern === 'zigzag' ? 'zigzag' : 'alternating'
+}
+
+function risingWallDensityFromPiece(piece: CompiledTrackPiece): RisingWallDensity {
+  return piece.parameters.density === 'sparse' ? 'sparse' : 'dense'
+}
+
+export function supportsCanonicalRailPorts(piece: Pick<CompiledTrackPiece, 'materialSlots'>): boolean {
+  // A surfaced catalog piece owns a traversable rail shell at every ordinary
+  // connector. Derive participation from that catalog contract instead of a
+  // runtime-kind allowlist so starts, finishes, obstacles, portals, elevators,
+  // vortices, and future surfaced pieces all negotiate the same terminal
+  // cross-section as their neighbour.
+  return piece.materialSlots.includes('lane.surface')
+}
+
+function rotateVector(vector: TrackVector, yawSteps: 0 | 1 | 2 | 3): TrackVector {
+  const [x, y, z] = vector
+  if (yawSteps === 1) return [-z, y, x]
+  if (yawSteps === 2) return [-x, y, -z]
+  if (yawSteps === 3) return [z, y, -x]
+  return [x, y, z]
+}
+
+function addVector(left: TrackVector, right: TrackVector): [number, number, number] {
+  return [left[0] + right[0], left[1] + right[1], left[2] + right[2]]
+}
+
+function scaleVector(vector: TrackVector, scale: number): [number, number, number] {
+  return [vector[0] * scale, vector[1] * scale, vector[2] * scale]
+}
+
+function distanceBetween(left: TrackVector, right: TrackVector): number {
+  return Math.hypot(left[0] - right[0], left[1] - right[1], left[2] - right[2])
+}