@marble.fun/track-catalog 3.0.0

package/src/three/track-connector-batch.ts

@@ -0,0 +1,125 @@
+import * as THREE from 'three'
+
+interface ConnectorBinding {
+  mesh: THREE.Mesh<THREE.SphereGeometry, THREE.MeshBasicMaterial>
+  materialVisible: boolean
+}
+
+/** Editor markers keep their source nodes for picking and connector focus. */
+export function batchTrackConnectorMarkers(root: THREE.Group, sourceRoots: readonly THREE.Object3D[]) {
+  const groups = new Map<string, ConnectorBinding[]>()
+  for (const sourceRoot of sourceRoots) {
+    if (!sourceRoot.visible) continue
+    sourceRoot.traverse(object => {
+      if (
+        !(object instanceof THREE.Mesh) ||
+        !(object.geometry instanceof THREE.SphereGeometry) ||
+        !(object.material instanceof THREE.MeshBasicMaterial) ||
+        !object.userData.isTrackConnectorMarker ||
+        object.material.map ||
+        object.material.alphaMap ||
+        object.material.envMap ||
+        object.castShadow ||
+        object.receiveShadow ||
+        object.material.onBeforeCompile !== THREE.Material.prototype.onBeforeCompile
+      )
+        return
+      const material = object.material
+      const key = JSON.stringify([
+        object.geometry.parameters,
+        material.color.toArray(),
+        material.opacity,
+        material.transparent,
+        material.depthTest,
+        material.depthWrite,
+        material.depthFunc,
+        material.side,
+        material.blending,
+        material.toneMapped,
+        material.visible,
+        material.wireframe,
+        material.userData.themeBaseOpacity,
+        material.userData.themeBaseTransparent,
+        material.userData.themeBaseDepthWrite,
+        object.renderOrder,
+        object.layers.mask,
+      ])
+      const group = groups.get(key) ?? []
+      group.push({ mesh: object, materialVisible: material.visible })
+      groups.set(key, group)
+    })
+  }
+  const batches: Array<{ mesh: THREE.InstancedMesh; bindings: ConnectorBinding[] }> = []
+  const inverse = new THREE.Matrix4()
+  const matrix = new THREE.Matrix4()
+  const materialVisibility = new Map<THREE.MeshBasicMaterial, boolean>()
+  const updateTransforms = () => {
+    if (batches.length === 0) return
+    root.updateWorldMatrix(true, true)
+    inverse.copy(root.matrixWorld).invert()
+    for (const batch of batches) {
+      let count = 0
+      batch.bindings.forEach(({ mesh }) => {
+        if (!mesh.visible) return
+        matrix.copy(inverse).multiply(mesh.matrixWorld)
+        batch.mesh.setMatrixAt(count++, matrix)
+      })
+      batch.mesh.count = count
+      batch.mesh.instanceMatrix.needsUpdate = true
+      batch.mesh.computeBoundingBox()
+      batch.mesh.computeBoundingSphere()
+    }
+  }
+  for (const bindings of groups.values()) {
+    if (bindings.length < 2) continue
+    const first = bindings[0]!.mesh
+    const mesh = new THREE.InstancedMesh(first.geometry.clone(), first.material.clone(), bindings.length)
+    ;(mesh.material as THREE.Material).visible = bindings[0]!.materialVisible
+    mesh.name = `track-connector-batch-${batches.length}`
+    mesh.visible = bindings.some(binding => binding.mesh.visible)
+    mesh.renderOrder = first.renderOrder
+    mesh.layers.mask = first.layers.mask
+    mesh.userData.isTrackConnectorMarker = true
+    mesh.userData.connectorMarkerOwner = true
+    mesh.userData.excludeFromEditorBounds = true
+    mesh.userData.decorative = true
+    mesh.userData.visualOnly = true
+    // Material visibility leaves the source Object3D available to the editor,
+    // even when setEditorChromeVisible later toggles all marker nodes.
+    for (const binding of bindings) {
+      materialVisibility.set(binding.mesh.material, binding.materialVisible)
+      binding.mesh.material.visible = false
+    }
+    root.add(mesh)
+    batches.push({ mesh, bindings })
+  }
+  if (batches.length > 0) updateTransforms()
+  return {
+    batchCount: batches.length,
+    sourceCount: batches.reduce((sum, batch) => sum + batch.bindings.length, 0),
+    updateTransforms,
+    detachSources(roots: readonly THREE.Object3D[]): void {
+      const removed = new Set<THREE.Object3D>()
+      roots.forEach(source => source.traverse(object => removed.add(object)))
+      for (const batch of batches) batch.bindings = batch.bindings.filter(binding => !removed.has(binding.mesh))
+      const retainedMaterials = new Set(batches.flatMap(batch => batch.bindings.map(binding => binding.mesh.material)))
+      for (const [material, visible] of materialVisibility) {
+        if (retainedMaterials.has(material)) continue
+        material.visible = visible
+        materialVisibility.delete(material)
+      }
+      updateTransforms()
+    },
+    dispose(): void {
+      for (const [material, visible] of materialVisibility) material.visible = visible
+      materialVisibility.clear()
+      for (const { mesh } of batches) {
+        mesh.removeFromParent()
+        mesh.dispose()
+        mesh.geometry.dispose()
+        ;(mesh.material as THREE.Material).dispose()
+      }
+      batches.length = 0
+    },
+  }
+}

package/src/three/track-material-continuity.ts

@@ -0,0 +1,442 @@
+import type { TrackDocument } from '@marble.fun/physics-engine'
+import * as THREE from 'three'
+
+type MaterialVisual = { root: THREE.Object3D | readonly THREE.Object3D[] }
+
+function visualRoots(visual: MaterialVisual): readonly THREE.Object3D[] {
+  return visual.root instanceof THREE.Object3D ? [visual.root] : visual.root
+}
+
+function trackArchitectureMetricLengths(root: THREE.Object3D): number[] {
+  const lengths: number[] = []
+  root.traverse(object => {
+    const runLengths = object.userData.runMetricLengths
+    if (!Array.isArray(runLengths)) return
+    runLengths.forEach((length, index) => {
+      if (typeof length === 'number' && Number.isFinite(length)) {
+        lengths[index] = Math.max(lengths[index] ?? 0, length)
+      }
+    })
+  })
+  return lengths
+}
+
+function trackMaterialPreferredInputConnector(root: THREE.Object3D): string | undefined {
+  let connectorId: string | undefined
+  root.traverse(object => {
+    if (connectorId || !(object instanceof THREE.Mesh)) return
+    const candidate = object.geometry.userData.themeMaterialConnectionConnectorId
+    if (typeof candidate === 'string') connectorId = candidate
+  })
+  return connectorId
+}
+
+interface TrackMaterialConnectorFrame {
+  transverse: number
+  longitudinal: number
+}
+
+function trackMaterialConnectorFrames(root: THREE.Object3D): Map<string, TrackMaterialConnectorFrame> {
+  const frames = new Map<string, TrackMaterialConnectorFrame>()
+  root.traverse(object => {
+    if (!(object instanceof THREE.Mesh)) return
+    const candidates = object.geometry.userData.themeMaterialConnectorFrames
+    if (typeof candidates !== 'object' || candidates === null) return
+    for (const [connectorId, candidate] of Object.entries(candidates)) {
+      const frame = candidate as Partial<TrackMaterialConnectorFrame> | null
+      if (
+        typeof frame === 'object' &&
+        frame !== null &&
+        typeof frame.transverse === 'number' &&
+        Number.isFinite(frame.transverse) &&
+        typeof frame.longitudinal === 'number' &&
+        Number.isFinite(frame.longitudinal)
+      ) {
+        frames.set(connectorId, frame as TrackMaterialConnectorFrame)
+      }
+    }
+  })
+  return frames
+}
+
+export function trackMaterialMetricLength(root: THREE.Object3D): number {
+  let length = 0
+  let primaryRunLength: number | undefined
+  root.traverse(object => {
+    if (!(object instanceof THREE.Mesh)) return
+    if (object.userData.materialSlot !== 'lane.surface') return
+    const candidatePrimaryLength = object.geometry.userData.themeMaterialPrimaryRunLength
+    if (typeof candidatePrimaryLength === 'number' && Number.isFinite(candidatePrimaryLength)) {
+      primaryRunLength = Math.max(primaryRunLength ?? 0, candidatePrimaryLength)
+    }
+    const attribute = object.geometry.getAttribute('themeNetUv')
+    if (!attribute || attribute.itemSize < 4) return
+    for (let index = 0; index < attribute.count; index += 1) {
+      if (attribute.getZ(index) > 0.5) length = Math.max(length, attribute.getW(index))
+    }
+  })
+  return primaryRunLength ?? length
+}
+
+/**
+ * Writes one absolute metric offset. Individual materials apply their own
+ * texture/grid scale in the shader; source topology must never quantize phase
+ * to a theme-specific repeat period.
+ */
+export function setTrackMaterialConnectionPhase(
+  root: THREE.Object3D,
+  phase: number,
+  connectorPhases: ReadonlyMap<string, number> = new Map(),
+  transversePhase = 0,
+  connectorTransversePhases: ReadonlyMap<string, number> = new Map(),
+): void {
+  root.traverse(object => {
+    if (!(object instanceof THREE.Mesh)) return
+    const waterPhaseSetter = object.userData.setWaterConnectionPhase
+    if (typeof waterPhaseSetter === 'function') (waterPhaseSetter as (phase: number) => void)(phase)
+    const geometry = object.geometry
+    const position = geometry.getAttribute('position')
+    if (!position || !geometry.getAttribute('themeNetUv')) return
+    const localAuthoredUv = geometry.userData.themeMaterialPhaseMode === 'local'
+    const connectorId = geometry.userData.themeMaterialConnectionConnectorId
+    const basePhase = localAuthoredUv
+      ? 0
+      : typeof connectorId === 'string'
+        ? (connectorPhases.get(connectorId) ?? phase)
+        : phase
+    const vertexPhases = new Float32Array(position.count).fill(basePhase)
+    const baseTransversePhase = localAuthoredUv
+      ? 0
+      : typeof connectorId === 'string'
+        ? (connectorTransversePhases.get(connectorId) ?? transversePhase)
+        : transversePhase
+    const vertexTransversePhases = new Float32Array(position.count).fill(baseTransversePhase)
+    const connectorRanges = geometry.userData.themeMaterialConnectionVertexRanges
+    if (!localAuthoredUv && Array.isArray(connectorRanges)) {
+      for (const range of connectorRanges) {
+        if (
+          typeof range !== 'object' ||
+          range === null ||
+          typeof range.connectorId !== 'string' ||
+          typeof range.start !== 'number' ||
+          typeof range.end !== 'number'
+        ) {
+          continue
+        }
+        const rangePhase = connectorPhases.get(range.connectorId) ?? basePhase
+        const rangeTransversePhase = connectorTransversePhases.get(range.connectorId) ?? baseTransversePhase
+        vertexPhases.fill(rangePhase, Math.max(0, range.start), Math.min(position.count, range.end))
+        vertexTransversePhases.fill(rangeTransversePhase, Math.max(0, range.start), Math.min(position.count, range.end))
+      }
+    }
+    geometry.setAttribute('themeMaterialPhase', new THREE.BufferAttribute(vertexPhases, 1))
+    // The diagnostic name describes the same values as the shader channel.
+    // Keep one buffer; phase edits replace both attributes together above.
+    geometry.setAttribute('themeConnectionPhase', geometry.getAttribute('themeMaterialPhase'))
+    geometry.setAttribute('themeMaterialTransversePhase', new THREE.BufferAttribute(vertexTransversePhases, 1))
+    const materialAxis = geometry.userData.themeMaterialLongitudinalAxis === 'x' ? 0 : 1
+    geometry.setAttribute(
+      'themeMaterialLongitudinalAxis',
+      new THREE.BufferAttribute(new Float32Array(position.count).fill(materialAxis), 1),
+    )
+  })
+}
+
+export function connectedTrackMaterialPhases(
+  pieceIds: readonly string[],
+  connections: readonly {
+    from: { pieceId: string; connectorId?: string }
+    to: { pieceId: string; connectorId?: string }
+  }[],
+  metricLengths: ReadonlyMap<string, number>,
+  rootPhases: ReadonlyMap<string, number> = new Map(),
+  preferredInputConnectorIds: ReadonlyMap<string, string> = new Map(),
+  connectorCoordinates: ReadonlyMap<string, ReadonlyMap<string, number>> = new Map(),
+): Map<string, number> {
+  const phases = new Map<string, number>()
+  const outgoing = new Map<
+    string,
+    Array<{ targetId: string; sourceConnectorId?: string; targetConnectorId?: string }>
+  >()
+  const incomingCount = new Map(pieceIds.map(pieceId => [pieceId, 0]))
+  const remainingIncoming = new Map(pieceIds.map(pieceId => [pieceId, 0]))
+  const incomingCandidates = new Map<
+    string,
+    Array<{ connectorId?: string; sourceId: string; phase: number }>
+  >()
+
+  for (const connection of connections) {
+    if (!incomingCount.has(connection.from.pieceId) || !incomingCount.has(connection.to.pieceId)) continue
+    const targets = outgoing.get(connection.from.pieceId) ?? []
+    targets.push({
+      targetId: connection.to.pieceId,
+      sourceConnectorId: connection.from.connectorId,
+      targetConnectorId: connection.to.connectorId,
+    })
+    outgoing.set(connection.from.pieceId, targets)
+    incomingCount.set(connection.to.pieceId, (incomingCount.get(connection.to.pieceId) ?? 0) + 1)
+    remainingIncoming.set(connection.to.pieceId, (remainingIncoming.get(connection.to.pieceId) ?? 0) + 1)
+  }
+  for (const targets of outgoing.values()) {
+    targets.sort((left, right) =>
+      `${left.targetId}:${left.targetConnectorId ?? ''}`.localeCompare(
+        `${right.targetId}:${right.targetConnectorId ?? ''}`,
+      ),
+    )
+  }
+  // Track Lab serialization already owns a canonical source-piece phase.
+  // Runtime may split that source into auxiliary rail definitions whose
+  // inferred graph is intentionally lossy; never overwrite an explicit phase
+  // merely because the rendered graph has a different root or identifier.
+  for (const [pieceId, phase] of rootPhases) {
+    if (incomingCount.has(pieceId) && Number.isFinite(phase)) phases.set(pieceId, phase)
+  }
+
+  const queue = pieceIds.filter(pieceId => (incomingCount.get(pieceId) ?? 0) === 0).sort()
+  const enqueueComponent = (pieceId: string) => {
+    if (!phases.has(pieceId)) phases.set(pieceId, rootPhases.get(pieceId) ?? 0)
+    queue.push(pieceId)
+  }
+  if (queue.length === 0 && pieceIds.length > 0) enqueueComponent([...pieceIds].sort()[0]!)
+
+  const visited = new Set<string>()
+  while (visited.size < pieceIds.length) {
+    while (queue.length > 0) {
+      const pieceId = queue.shift()!
+      if (visited.has(pieceId)) continue
+      visited.add(pieceId)
+      if (!phases.has(pieceId)) phases.set(pieceId, 0)
+      for (const edge of outgoing.get(pieceId) ?? []) {
+        const sourceCoordinate = edge.sourceConnectorId
+          ? connectorCoordinates.get(pieceId)?.get(edge.sourceConnectorId)
+          : undefined
+        const targetCoordinate = edge.targetConnectorId
+          ? connectorCoordinates.get(edge.targetId)?.get(edge.targetConnectorId)
+          : undefined
+        const edgePhase =
+          (phases.get(pieceId) ?? 0) +
+          (sourceCoordinate ?? metricLengths.get(pieceId) ?? 0) -
+          (targetCoordinate ?? 0)
+        const candidates = incomingCandidates.get(edge.targetId) ?? []
+        candidates.push({
+          connectorId: edge.targetConnectorId,
+          sourceId: pieceId,
+          phase: edgePhase,
+        })
+        incomingCandidates.set(edge.targetId, candidates)
+        const remaining = Math.max(0, (remainingIncoming.get(edge.targetId) ?? 1) - 1)
+        remainingIncoming.set(edge.targetId, remaining)
+        if (remaining > 0) continue
+        if (!phases.has(edge.targetId)) {
+          const preferredConnectorId = preferredInputConnectorIds.get(edge.targetId)
+          const selected =
+            candidates.find(candidate => candidate.connectorId === preferredConnectorId) ??
+            [...candidates].sort((left, right) =>
+              `${left.sourceId}:${left.connectorId ?? ''}`.localeCompare(`${right.sourceId}:${right.connectorId ?? ''}`),
+            )[0]
+          phases.set(edge.targetId, selected?.phase ?? 0)
+        }
+        queue.push(edge.targetId)
+      }
+    }
+    const next = [...pieceIds].sort().find(pieceId => !visited.has(pieceId))
+    if (next) enqueueComponent(next)
+  }
+  return phases
+}
+
+export function applyTrackDocumentMaterialContinuity(
+  document: Pick<TrackDocument, 'pieces' | 'connections'>,
+  visuals: ReadonlyMap<string, MaterialVisual>,
+): Map<string, number> {
+  return applyTrackMaterialContinuity(
+    document.pieces.map(piece => piece.id),
+    document.connections,
+    visuals,
+  )
+}
+
+/**
+ * Applies one connected material schedule to editor or runtime visuals.
+ * Architectural runs keep independent path-length phases (for example, the
+ * inner and outer walls of a curve) without changing the authored track,
+ * connector, floor, or collider geometry.
+ */
+export interface TrackMaterialContinuityPlan {
+  readonly phases: Map<string, number>
+  applyPiece(pieceId: string): void
+}
+
+export function createTrackMaterialContinuityPlan(
+  pieceIds: readonly string[],
+  connections: readonly {
+    from: { pieceId: string; connectorId?: string }
+    to: { pieceId: string; connectorId?: string }
+  }[],
+  visuals: ReadonlyMap<string, MaterialVisual>,
+  rootPhases: ReadonlyMap<string, number> = new Map(),
+): TrackMaterialContinuityPlan {
+  const lengths = new Map<string, number>()
+  const preferredInputConnectorIds = new Map<string, string>()
+  const connectorFrames = new Map<string, Map<string, TrackMaterialConnectorFrame>>()
+  for (const pieceId of pieceIds) {
+    const visual = visuals.get(pieceId)
+    if (visual) {
+      lengths.set(pieceId, Math.max(0, ...visualRoots(visual).map(root => trackMaterialMetricLength(root))))
+      for (const root of visualRoots(visual)) {
+        const connectorId = trackMaterialPreferredInputConnector(root)
+        if (connectorId) preferredInputConnectorIds.set(pieceId, connectorId)
+        const frames = connectorFrames.get(pieceId) ?? new Map<string, TrackMaterialConnectorFrame>()
+        for (const [frameConnectorId, frame] of trackMaterialConnectorFrames(root)) {
+          frames.set(frameConnectorId, frame)
+        }
+        if (frames.size > 0) connectorFrames.set(pieceId, frames)
+      }
+    }
+  }
+  const phases = connectedTrackMaterialPhases(
+    pieceIds,
+    connections,
+    lengths,
+    rootPhases,
+    preferredInputConnectorIds,
+    new Map(
+      [...connectorFrames].map(([pieceId, frames]) => [
+        pieceId,
+        new Map([...frames].map(([connectorId, frame]) => [connectorId, frame.longitudinal])),
+      ]),
+    ),
+  )
+  const incomingConnectorPhases = new Map<string, Map<string, number>>()
+  const zeroLengths = new Map(pieceIds.map(pieceId => [pieceId, 0]))
+  const transversePhases = connectedTrackMaterialPhases(
+    pieceIds,
+    connections,
+    zeroLengths,
+    new Map(),
+    preferredInputConnectorIds,
+    new Map(
+      [...connectorFrames].map(([pieceId, frames]) => [
+        pieceId,
+        new Map([...frames].map(([connectorId, frame]) => [connectorId, frame.transverse])),
+      ]),
+    ),
+  )
+  const incomingConnectorTransversePhases = new Map<string, Map<string, number>>()
+  for (const connection of connections) {
+    const connectorId = connection.to.connectorId
+    if (!connectorId) continue
+    const sourceFrame = connection.from.connectorId
+      ? connectorFrames.get(connection.from.pieceId)?.get(connection.from.connectorId)
+      : undefined
+    const targetFrame = connectorFrames.get(connection.to.pieceId)?.get(connectorId)
+    const phase =
+      (phases.get(connection.from.pieceId) ?? 0) +
+      (sourceFrame?.longitudinal ?? lengths.get(connection.from.pieceId) ?? 0) -
+      (targetFrame?.longitudinal ?? 0)
+    const connectorPhases = incomingConnectorPhases.get(connection.to.pieceId) ?? new Map<string, number>()
+    connectorPhases.set(connectorId, phase)
+    incomingConnectorPhases.set(connection.to.pieceId, connectorPhases)
+    const sourceTransverseCoordinate = connection.from.connectorId
+      ? (connectorFrames.get(connection.from.pieceId)?.get(connection.from.connectorId)?.transverse ?? 0)
+      : 0
+    const targetTransverseCoordinate = targetFrame?.transverse ?? 0
+    const transverseConnectorPhases =
+      incomingConnectorTransversePhases.get(connection.to.pieceId) ?? new Map<string, number>()
+    transverseConnectorPhases.set(
+      connectorId,
+      (transversePhases.get(connection.from.pieceId) ?? 0) +
+        sourceTransverseCoordinate -
+        targetTransverseCoordinate,
+    )
+    incomingConnectorTransversePhases.set(connection.to.pieceId, transverseConnectorPhases)
+  }
+  const architectureLengths = new Map<string, number[]>()
+  let architectureRunCount = 0
+  for (const pieceId of pieceIds) {
+    const visual = visuals.get(pieceId)
+    if (!visual) continue
+    const runLengths: number[] = []
+    for (const root of visualRoots(visual)) {
+      trackArchitectureMetricLengths(root).forEach((length, index) => {
+        runLengths[index] = Math.max(runLengths[index] ?? 0, length)
+      })
+    }
+    architectureLengths.set(pieceId, runLengths)
+    architectureRunCount = Math.max(architectureRunCount, runLengths.length)
+  }
+  const architecturePhases = Array.from({ length: architectureRunCount }, (_unused, runIndex) =>
+    connectedTrackMaterialPhases(
+      pieceIds,
+      connections,
+      new Map(
+        pieceIds.map(pieceId => [
+          pieceId,
+          architectureLengths.get(pieceId)?.[runIndex] ?? lengths.get(pieceId) ?? 0,
+        ]),
+      ),
+      rootPhases,
+      preferredInputConnectorIds,
+    ),
+  )
+  const applyPiece = (pieceId: string): void => {
+    const phase = phases.get(pieceId)
+    if (phase === undefined) return
+    const visual = visuals.get(pieceId)
+    if (!visual) return
+    const supportPhaseSetters: ((phase: number) => void)[] = []
+    const floorPhaseSetters: ((phase: number) => void)[] = []
+    const architecturePhaseSetters: ((phase: number | readonly number[]) => void)[] = []
+    for (const root of visualRoots(visual)) {
+      root.traverse(object => {
+        const setter = object.userData.setSupportConnectionPhase
+        if (typeof setter === 'function') supportPhaseSetters.push(setter as (phase: number) => void)
+        const floorSetter = object.userData.setFloorConnectionPhase
+        if (typeof floorSetter === 'function') {
+          const connectorId = object.userData.floorConnectionConnectorId
+          const connectorPhase =
+            typeof connectorId === 'string'
+              ? incomingConnectorPhases.get(pieceId)?.get(connectorId)
+              : undefined
+          floorPhaseSetters.push(() =>
+            (floorSetter as (phase: number) => void)(connectorPhase ?? phase),
+          )
+        }
+        const architectureSetter = object.userData.setMaterialConnectionPhase
+        if (typeof architectureSetter === 'function') {
+          architecturePhaseSetters.push(architectureSetter as (phase: number | readonly number[]) => void)
+        }
+      })
+    }
+    const runPhases = architecturePhases.map(runPhasesByPiece => runPhasesByPiece.get(pieceId) ?? phase)
+    architecturePhaseSetters.forEach(setter => setter(runPhases.length > 0 ? runPhases : phase))
+    floorPhaseSetters.forEach(setter => setter(phase))
+    supportPhaseSetters.forEach(setter => setter(phase))
+    const connectorPhases = incomingConnectorPhases.get(pieceId)
+    const connectorTransversePhases = incomingConnectorTransversePhases.get(pieceId)
+    visualRoots(visual).forEach(root =>
+      setTrackMaterialConnectionPhase(
+        root,
+        phase,
+        connectorPhases,
+        transversePhases.get(pieceId) ?? 0,
+        connectorTransversePhases,
+      ),
+    )
+  }
+  return { phases, applyPiece }
+}
+
+export function applyTrackMaterialContinuity(
+  pieceIds: readonly string[],
+  connections: readonly {
+    from: { pieceId: string; connectorId?: string }
+    to: { pieceId: string; connectorId?: string }
+  }[],
+  visuals: ReadonlyMap<string, MaterialVisual>,
+  rootPhases: ReadonlyMap<string, number> = new Map(),
+): Map<string, number> {
+  const plan = createTrackMaterialContinuityPlan(pieceIds, connections, visuals, rootPhases)
+  pieceIds.forEach(plan.applyPiece)
+  return plan.phases
+}