@tscircuit/fanout-solver 0.0.24 → 0.0.25

package/lib/fanout-solver.ts

@@ -208,15 +208,14 @@ function getBusDistanceToBoundary(bus: PreparedBus): number {
   }
 }
 
-function busUsesOriginalEndpointTracks(bus: PreparedBus): boolean {
+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
-      ? connection.targetPoint.y
-      : connection.targetPoint.x
+    const targetTrack = isHorizontal ? exitTargetPoint.y : exitTargetPoint.x
     return Math.abs(sourceTrack - targetTrack) > 1e-6
   })
 }
@@ -293,7 +292,7 @@ function createPreferredLayerAssignment(params: {
     )
     if (
       routableEscapeLayers.includes(sourceLayer) &&
-      (busUsesOriginalEndpointTracks(bus) || busIsOnOutwardComponentEdge(bus))
+      (busUsesDestinationGuidedTracks(bus) || busIsOnOutwardComponentEdge(bus))
     ) {
       assignment[bus.busId] = sourceLayer
     } else if (viaLayers.length > 0) {
@@ -795,7 +794,7 @@ export class FanoutSolver extends BaseSolver {
         (count, bus) => {
           if (
             bus.termination.type !== "boundary" ||
-            !busUsesOriginalEndpointTracks(bus)
+            !busUsesDestinationGuidedTracks(bus)
           ) {
             return count
           }
@@ -840,7 +839,7 @@ export class FanoutSolver extends BaseSolver {
           )
         }
         const sourceLayer = bus.connections[0]?.sourceLayer
-        const preferSourceLayer = busUsesOriginalEndpointTracks(bus)
+        const preferSourceLayer = busUsesDestinationGuidedTracks(bus)
         const orderedLayers = candidateLayers.toSorted(
           (first, second) =>
             (layerLoads.get(first) ?? 0) - (layerLoads.get(second) ?? 0) ||

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

@@ -294,7 +294,7 @@ function getPreferredTrack(params: {
   connection: PreparedConnection
 }): number {
   return getPerpendicularAxis(
-    params.connection.targetPoint,
+    params.connection.exitTargetPoint ?? params.connection.targetPoint,
     params.bus.direction,
   )
 }

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" }`.
    *
@@ -209,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.24",
+  "version": "0.0.25",
   "description": "BGA fanout solver with coordinated bus-layer escapes for SimpleRouteJson",
   "module": "lib/index.ts",
   "type": "module",