@tscircuit/fanout-solver 0.0.23 → 0.0.25

package/README.md

@@ -61,12 +61,12 @@ and treats each bus-layer decision atomically.
 - Uses a straight pad-pair escape when the via fits. Otherwise it uses a 45°
   four-pad interstitial escape and nested side bands that spread deeper
   two-layer buses around already-routed outer buses.
-- `compactBusTracks` bends each bus into a trace/clearance-pitch routing
-  envelope, so a wide pad row does not consume a disproportionately wide
-  breakout corridor.
-- `preferOriginalEndpointTracks` projects boundary tracks onto the original
-  downstream pad coordinates and prefers their layer when legal. This lets
-  ordered edge-pad buses make direct, visibly continuous pad connections.
+- `compactBusTracks` provides a trace/clearance-pitch fallback envelope when
+  the original endpoint track cannot route, so a wide pad row does not consume
+  a disproportionately wide breakout corridor.
+- Boundary tracks project onto the original downstream pad coordinates and
+  prefer their layer when legal. This lets ordered edge-pad buses make direct,
+  visibly continuous pad connections.
 - Chamfers orthogonal routing corners into 45° segments before validating and
   emitting the fanout.
 - Verifies oriented-pad, via, trace, and already-routed fanout clearance on
@@ -125,7 +125,6 @@ const fanoutSolver = new FanoutSolver(simpleRouteJson, {
   availableCornersAndSides: ["top_left", "top", "top_right"],
   borderDistribution: "even",
   compactBusTracks: true,
-  preferOriginalEndpointTracks: true,
   buses: [
     {
       busId: "ground",

package/lib/fanout-solver.ts

@@ -40,7 +40,6 @@ interface ResolvedFanoutConfig {
   viaHoleDiameter: number
   clearance: number
   compactBusTracks: boolean
-  preferOriginalEndpointTracks: boolean
   allowSameNetMerges: boolean
   singleLayerPushAndShove: boolean
   singleLayerAdaptiveExits: boolean
@@ -132,7 +131,6 @@ function resolveConfig(
     viaHoleDiameter,
     clearance,
     compactBusTracks: options.compactBusTracks ?? false,
-    preferOriginalEndpointTracks: options.preferOriginalEndpointTracks ?? false,
     allowSameNetMerges: options.allowSameNetMerges ?? false,
     singleLayerPushAndShove: options.singleLayerPushAndShove ?? false,
     singleLayerAdaptiveExits: options.singleLayerAdaptiveExits ?? false,
@@ -210,6 +208,18 @@ function getBusDistanceToBoundary(bus: PreparedBus): number {
   }
 }
 
+function busUsesDestinationGuidedTracks(bus: PreparedBus): boolean {
+  const isHorizontal = bus.direction === "left" || bus.direction === "right"
+  return bus.connections.some((connection) => {
+    const exitTargetPoint = connection.exitTargetPoint ?? connection.targetPoint
+    const sourceTrack = isHorizontal
+      ? connection.sourcePoint.y
+      : connection.sourcePoint.x
+    const targetTrack = isHorizontal ? exitTargetPoint.y : exitTargetPoint.x
+    return Math.abs(sourceTrack - targetTrack) > 1e-6
+  })
+}
+
 function busIsOnOutwardComponentEdge(bus: PreparedBus): boolean {
   const isHorizontal = bus.direction === "left" || bus.direction === "right"
   const directionalCoordinates = isHorizontal
@@ -256,14 +266,8 @@ function createPreferredLayerAssignment(params: {
   buses: PreparedBus[]
   escapeLayers: string[]
   escapeLayersByBusId: Readonly<Record<string, readonly string[]>>
-  preferOriginalEndpointTracks: boolean
 }): Readonly<Record<string, string>> {
-  const {
-    buses,
-    escapeLayers,
-    escapeLayersByBusId,
-    preferOriginalEndpointTracks,
-  } = params
+  const { buses, escapeLayers, escapeLayersByBusId } = params
   const assignment: Record<string, string> = {}
   const directionsByComponent = new Map<string, Set<PreparedBus["direction"]>>()
   let nextViaLayerIndex = 0
@@ -288,7 +292,7 @@ function createPreferredLayerAssignment(params: {
     )
     if (
       routableEscapeLayers.includes(sourceLayer) &&
-      (preferOriginalEndpointTracks || busIsOnOutwardComponentEdge(bus))
+      (busUsesDestinationGuidedTracks(bus) || busIsOnOutwardComponentEdge(bus))
     ) {
       assignment[bus.busId] = sourceLayer
     } else if (viaLayers.length > 0) {
@@ -347,7 +351,6 @@ function getCandidateEscapeLayersForBus(params: {
         viaHoleDiameter: config.viaHoleDiameter,
         clearance: config.clearance,
         compactBusTracks: config.compactBusTracks,
-        preferOriginalEndpointTracks: config.preferOriginalEndpointTracks,
         allowSameNetMerges: config.allowSameNetMerges,
         staticClearanceCache,
       }) !== null,
@@ -458,7 +461,6 @@ export class FanoutSolver extends BaseSolver {
         buses: this.preparedBuses,
         escapeLayers: this.config.escapeLayers,
         escapeLayersByBusId,
-        preferOriginalEndpointTracks: this.config.preferOriginalEndpointTracks,
       }),
       generatedAssignments,
       maxAssignments: this.config.maxLayerCombinations,
@@ -605,7 +607,6 @@ export class FanoutSolver extends BaseSolver {
         viaHoleDiameter: this.config.viaHoleDiameter,
         clearance: this.config.clearance,
         compactBusTracks: this.config.compactBusTracks,
-        preferOriginalEndpointTracks: this.config.preferOriginalEndpointTracks,
         allowSameNetMerges: this.config.allowSameNetMerges,
         staticClearanceCache: this.routeStaticClearanceCache,
         blockingBusCounts: currentBusBlockingCounts,
@@ -791,7 +792,12 @@ export class FanoutSolver extends BaseSolver {
       const viaCount = getPlanViaCount(state.plans)
       const offEndpointLayerConnectionCount = this.preparedBuses.reduce(
         (count, bus) => {
-          if (bus.termination.type !== "boundary") return count
+          if (
+            bus.termination.type !== "boundary" ||
+            !busUsesDestinationGuidedTracks(bus)
+          ) {
+            return count
+          }
           const sourceLayer = bus.connections[0]?.sourceLayer
           return state.assignment[bus.busId] === sourceLayer
             ? count
@@ -802,9 +808,7 @@ export class FanoutSolver extends BaseSolver {
       return (
         routeLength +
         viaCount * 0.1 +
-        (this.config.preferOriginalEndpointTracks
-          ? offEndpointLayerConnectionCount * 10_000
-          : 0) +
+        offEndpointLayerConnectionCount * 10_000 +
         assignmentLoadPenalty(
           state.assignment,
           this.preparedBuses,
@@ -835,10 +839,11 @@ export class FanoutSolver extends BaseSolver {
           )
         }
         const sourceLayer = bus.connections[0]?.sourceLayer
+        const preferSourceLayer = busUsesDestinationGuidedTracks(bus)
         const orderedLayers = candidateLayers.toSorted(
           (first, second) =>
             (layerLoads.get(first) ?? 0) - (layerLoads.get(second) ?? 0) ||
-            (this.config.preferOriginalEndpointTracks
+            (preferSourceLayer
               ? Number(second === sourceLayer) - Number(first === sourceLayer)
               : Number(first === sourceLayer) -
                 Number(second === sourceLayer)) ||
@@ -858,8 +863,6 @@ export class FanoutSolver extends BaseSolver {
               viaHoleDiameter: this.config.viaHoleDiameter,
               clearance: this.config.clearance,
               compactBusTracks: this.config.compactBusTracks,
-              preferOriginalEndpointTracks:
-                this.config.preferOriginalEndpointTracks,
               allowSameNetMerges: this.config.allowSameNetMerges,
               staticClearanceCache: this.routeStaticClearanceCache,
             },

package/lib/index.ts

@@ -35,6 +35,7 @@ export type {
   FanoutSolverOutput,
   FanoutValidationIssue,
   FanoutValidationReport,
+  Point2D,
   PreparedBus,
   SimpleRouteJsonWithFanoutPlanes,
 } from "./types"

package/lib/prepare-buses.ts

@@ -643,6 +643,7 @@ function prepareConnection(params: {
   sourceGrid: ComponentGrid
   componentGrids: ComponentGrid[]
   termination: FanoutBusTermination
+  exitTargetPoint?: { x: number; y: number }
 }): PreparedConnection {
   const {
     connection,
@@ -650,6 +651,7 @@ function prepareConnection(params: {
     sourceGrid,
     componentGrids,
     termination,
+    exitTargetPoint,
   } = params
   for (
     let sourcePointIndex = 0;
@@ -671,6 +673,12 @@ function prepareConnection(params: {
         `FanoutSolver: connection "${connection.name}" has no source layer shared with its BGA pad`,
       )
     }
+    const targetPoint = chooseTargetPoint(
+      sourcePoint,
+      connection,
+      sourcePointIndex,
+      termination,
+    )
     return {
       connection,
       connectionIndex,
@@ -678,12 +686,8 @@ function prepareConnection(params: {
       sourcePointIndex,
       sourceLayer,
       sourceObstacle: sourceMatch.obstacle,
-      targetPoint: chooseTargetPoint(
-        sourcePoint,
-        connection,
-        sourcePointIndex,
-        termination,
-      ),
+      targetPoint,
+      exitTargetPoint: exitTargetPoint ?? targetPoint,
     }
   }
   throw new Error(
@@ -698,8 +702,10 @@ function inferDirection(
   let dx = 0
   let dy = 0
   for (const preparedConnection of connections) {
-    dx += preparedConnection.targetPoint.x - preparedConnection.sourcePoint.x
-    dy += preparedConnection.targetPoint.y - preparedConnection.sourcePoint.y
+    const exitTargetPoint =
+      preparedConnection.exitTargetPoint ?? preparedConnection.targetPoint
+    dx += exitTargetPoint.x - preparedConnection.sourcePoint.x
+    dy += exitTargetPoint.y - preparedConnection.sourcePoint.y
   }
   if (Math.abs(dx) < 1e-9 && Math.abs(dy) < 1e-9) {
     throw new Error(
@@ -941,6 +947,20 @@ export function prepareFanoutBuses(
     srj.connections.map((connection, index) => [connection.name, index]),
   )
   const resolvedBusInputs = resolveBusSpecs(srj, options).map((busSpec) => {
+    for (const [connectionName, point] of Object.entries(
+      busSpec.connectionExitTargets ?? {},
+    )) {
+      if (!busSpec.connectionNames.includes(connectionName)) {
+        throw new Error(
+          `FanoutSolver: connectionExitTargets contains connection "${connectionName}" outside bus "${busSpec.busId}"`,
+        )
+      }
+      if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+        throw new Error(
+          `FanoutSolver: connectionExitTargets for connection "${connectionName}" must contain finite x and y coordinates`,
+        )
+      }
+    }
     const connections = busSpec.connectionNames.map((connectionName) => {
       const connectionIndex = connectionIndexByName.get(connectionName)
       if (connectionIndex === undefined) {
@@ -962,6 +982,7 @@ export function prepareFanoutBuses(
         sourceGrid,
         componentGrids,
         termination: busSpec.termination ?? { type: "boundary" },
+        exitTargetPoint: busSpec.connectionExitTargets?.[connection.name],
       }),
     )
     return { busSpec, sourceGrid, preparedConnections }

package/lib/route-bus.ts

@@ -39,7 +39,6 @@ export interface RouteBusParams {
   viaHoleDiameter: number
   clearance: number
   compactBusTracks: boolean
-  preferOriginalEndpointTracks?: boolean
   allowSameNetMerges?: boolean
   staticClearanceCache?: RouteBusStaticClearanceCache
   blockingBusCounts?: Map<string, number>
@@ -293,10 +292,19 @@ function getTrackCandidates(params: {
 function getPreferredTrack(params: {
   bus: PreparedBus
   connection: PreparedConnection
+}): number {
+  return getPerpendicularAxis(
+    params.connection.exitTargetPoint ?? params.connection.targetPoint,
+    params.bus.direction,
+  )
+}
+
+function getLegacyPreferredTrack(params: {
+  bus: PreparedBus
+  connection: PreparedConnection
   targetUsesVia: boolean
   interstitialEscape: boolean
   compactBusTracks: boolean
-  preferOriginalEndpointTracks: boolean
   traceWidth: number
   viaDiameter: number
   clearance: number
@@ -307,7 +315,6 @@ function getPreferredTrack(params: {
     targetUsesVia,
     interstitialEscape,
     compactBusTracks,
-    preferOriginalEndpointTracks,
     traceWidth,
     viaDiameter,
     clearance,
@@ -319,9 +326,6 @@ function getPreferredTrack(params: {
     connection.sourcePoint,
     bus.direction,
   )
-  if (preferOriginalEndpointTracks) {
-    return getPerpendicularAxis(connection.targetPoint, bus.direction)
-  }
   if (compactBusTracks) {
     const connectionRank = getConnectionRank(bus, connection)
     const componentCenter =
@@ -332,11 +336,9 @@ function getPreferredTrack(params: {
         (traceWidth + clearance)
     )
   }
-  if (!targetUsesVia) return sourceTrack
-  if (!interstitialEscape) return sourceTrack
+  if (!targetUsesVia || !interstitialEscape) return sourceTrack
 
   const depthInRows = getDepthInRows(bus)
-
   const trackPitch = traceWidth + clearance
   const halfConnectionCount = Math.ceil(bus.connections.length / 2)
   const sideBandWidth = (halfConnectionCount - 1) * trackPitch
@@ -1296,7 +1298,6 @@ export function routeBusAlternatives(
     viaHoleDiameter,
     clearance,
     compactBusTracks,
-    preferOriginalEndpointTracks = false,
     staticClearanceCache,
     blockingBusCounts,
     allowSameNetMerges = false,
@@ -1359,23 +1360,42 @@ export function routeBusAlternatives(
 
     const preparedConnection = connectionOrder[connectionIndex]!
     const connectionRank = getConnectionRank(bus, preparedConnection)
-    const trackCandidates = getTrackCandidates({
-      bus,
-      connection: preparedConnection,
-      preferredTrack: getPreferredTrack({
+    const preferredTracks = [
+      getPreferredTrack({
+        bus,
+        connection: preparedConnection,
+      }),
+      getLegacyPreferredTrack({
         bus,
         connection: preparedConnection,
         targetUsesVia,
         interstitialEscape,
         compactBusTracks,
-        preferOriginalEndpointTracks,
         traceWidth,
         viaDiameter,
         clearance,
       }),
-      traceWidth,
-      clearance,
-    })
+    ].filter(
+      (track, index, tracks) =>
+        tracks.findIndex((candidate) => Math.abs(candidate - track) < 1e-9) ===
+        index,
+    )
+    const trackCandidates = preferredTracks
+      .flatMap((preferredTrack) =>
+        getTrackCandidates({
+          bus,
+          connection: preparedConnection,
+          preferredTrack,
+          traceWidth,
+          clearance,
+        }),
+      )
+      .filter(
+        (track, index, tracks) =>
+          tracks.findIndex(
+            (candidate) => Math.abs(candidate.value - track.value) < 1e-9,
+          ) === index,
+      )
     for (
       let trackIndex = 0;
       trackIndex < trackCandidates.length;

package/lib/route-single-layer-push-shove.ts

@@ -197,7 +197,10 @@ function getCornerChannelPrefixes(params: {
         maximum: bus.componentBounds.maxX,
       }
   const directionalDistance = sign * (componentExitAxis - sourceAxis)
-  const targetTrack = getPerpendicularAxis(connection.targetPoint, direction)
+  const targetTrack = getPerpendicularAxis(
+    connection.exitTargetPoint ?? connection.targetPoint,
+    direction,
+  )
   const lanePitch = traceWidth + clearance
   const exitAxis = getExitAxis(bus)
   const candidates = ([-1, 1] as const)
@@ -280,7 +283,7 @@ function completeCornerChannelRoute(params: {
   const minimumTrack = boundaryMinimum + traceWidth / 2
   const maximumTrack = boundaryMaximum - traceWidth / 2
   const targetTrack = getPerpendicularAxis(
-    item.connection.targetPoint,
+    item.connection.exitTargetPoint ?? item.connection.targetPoint,
     direction,
   )
   const trackStep = lanePitch / 2

package/lib/types.ts

@@ -63,6 +63,15 @@ export interface FanoutBusSpec extends SimpleRouteBus {
   sourceComponentId?: string
   direction?: FanoutDirection
   preferredExit?: FanoutBorderTarget
+  /**
+   * Preferred downstream routing point for each connection after it leaves the
+   * fanout boundary. This is routing guidance only and does not replace the
+   * connection's electrical endpoint in SimpleRouteJson.
+   *
+   * A caller coordinating two fanouts can pass the paired fanout's selected
+   * exit here so both sides aim toward the same track.
+   */
+  connectionExitTargets?: Readonly<Record<string, Point2D>>
   /**
    * Defaults to `{ type: "boundary" }`.
    *
@@ -102,13 +111,6 @@ export interface FanoutSolverOptions {
   viaHoleDiameter?: number
   clearance?: number
   compactBusTracks?: boolean
-  /**
-   * Prefer the perpendicular coordinate of each original downstream endpoint
-   * when assigning boundary tracks. Ordered edge-pad buses can then enter
-   * same-layer pads directly instead of requiring a second global router to
-   * undo compacted fanout tracks.
-   */
-  preferOriginalEndpointTracks?: boolean
   /** Allow branches belonging to the same electrical net to share copper. */
   allowSameNetMerges?: boolean
   singleLayerPushAndShove?: boolean
@@ -216,6 +218,8 @@ export interface PreparedConnection {
   sourceLayer: string
   sourceObstacle: Obstacle
   targetPoint: ConnectionPoint
+  /** Preferred downstream point used to choose the boundary exit track. */
+  exitTargetPoint?: Point2D
 }
 
 export interface PreparedBus {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tscircuit/fanout-solver",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "BGA fanout solver with coordinated bus-layer escapes for SimpleRouteJson",
   "module": "lib/index.ts",
   "type": "module",