@tscircuit/fanout-solver 0.0.24 → 0.0.26

package/lib/build-output.ts

@@ -1,4 +1,5 @@
 import type { Obstacle, SimpleRouteJson } from "@tscircuit/capacity-autorouter"
+import { createFanoutOutputIds } from "./fanout-output-ids"
 import type { FanoutRoutePlan, SimpleRouteJsonWithFanoutPlanes } from "./types"
 
 function createViaObstacle(
@@ -17,8 +18,11 @@ function createViaObstacle(
     }
     return layerIndex
   })
+  const outputIds = createFanoutOutputIds(plan)
   return {
-    obstacleId: `${endpoint ? "fanout-plane-endpoint-via" : "fanout-via"}:${plan.connectionName}`,
+    obstacleId: endpoint
+      ? outputIds.planeEndpointViaObstacleId
+      : outputIds.viaObstacleId,
     type: "rect",
     center: via.center,
     width: via.diameter,
@@ -50,14 +54,15 @@ export function buildOutputSimpleRouteJson(params: {
         `FanoutSolver: output connection index ${plan.connectionIndex} is missing`,
       )
     }
+    const outputIds = createFanoutOutputIds(plan)
     connection.pointsToConnect[plan.sourcePointIndex] = {
       x: plan.exitPoint.x,
       y: plan.exitPoint.y,
       layer: plan.targetLayer,
       pointId:
         plan.termination.type === "plane"
-          ? `fanout-plane:${plan.connectionName}`
-          : `fanout-exit:${plan.connectionName}`,
+          ? outputIds.planeExitPointId
+          : outputIds.boundaryExitPointId,
     }
     if (plan.termination.type === "plane") {
       planeTerminatedConnectionNames.add(plan.connectionName)

package/lib/complete-original-endpoints.ts

@@ -5,6 +5,7 @@ import {
   type SimpleRouteJson,
   type SimplifiedPcbTrace,
 } from "@tscircuit/capacity-autorouter"
+import { createFanoutCompletionTraceId } from "./fanout-output-ids"
 import {
   distance,
   distancePointToSegment,
@@ -226,7 +227,11 @@ function createBranchTrace(params: {
 
   return {
     type: "pcb_trace",
-    pcb_trace_id: `fanout-completion:${plan.connectionName}:${candidateIndex}`,
+    pcb_trace_id: createFanoutCompletionTraceId({
+      connectionName: plan.connectionName,
+      sourcePointIndex: plan.sourcePointIndex,
+      candidateIndex,
+    }),
     connection_name: plan.connectionName,
     route,
   }

package/lib/fanout-output-ids.ts

@@ -0,0 +1,33 @@
+export interface FanoutOutputIds {
+  boundaryExitPointId: string
+  planeExitPointId: string
+  traceId: string
+  viaObstacleId: string
+  planeEndpointPointId: string
+  planeEndpointTraceId: string
+  planeEndpointViaObstacleId: string
+}
+
+export function createFanoutOutputIds(input: {
+  connectionName: string
+  sourcePointIndex: number
+}): FanoutOutputIds {
+  const endpointKey = `${input.connectionName}:source-${input.sourcePointIndex}`
+  return {
+    boundaryExitPointId: `fanout-exit:${endpointKey}`,
+    planeExitPointId: `fanout-plane:${endpointKey}`,
+    traceId: `fanout:${endpointKey}`,
+    viaObstacleId: `fanout-via:${endpointKey}`,
+    planeEndpointPointId: `fanout-plane-endpoint-point:${endpointKey}`,
+    planeEndpointTraceId: `fanout-plane-endpoint:${endpointKey}`,
+    planeEndpointViaObstacleId: `fanout-plane-endpoint-via:${endpointKey}`,
+  }
+}
+
+export function createFanoutCompletionTraceId(input: {
+  connectionName: string
+  sourcePointIndex: number
+  candidateIndex: number
+}): string {
+  return `fanout-completion:${input.connectionName}:source-${input.sourcePointIndex}:${input.candidateIndex}`
+}

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

@@ -10,6 +10,7 @@ import {
   distanceSegmentToObstacle,
   segmentsAreClear,
 } from "./geometry"
+import { createFanoutOutputIds } from "./fanout-output-ids"
 import { getLayerSpan } from "./layer-names"
 import {
   connectionsShareElectricalNet,
@@ -294,7 +295,7 @@ function getPreferredTrack(params: {
   connection: PreparedConnection
 }): number {
   return getPerpendicularAxis(
-    params.connection.targetPoint,
+    params.connection.exitTargetPoint ?? params.connection.targetPoint,
     params.bus.direction,
   )
 }
@@ -636,6 +637,10 @@ function buildPlan(params: {
     })
   }
 
+  const outputIds = createFanoutOutputIds({
+    connectionName: preparedConnection.connection.name,
+    sourcePointIndex: preparedConnection.sourcePointIndex,
+  })
   return {
     busId: bus.busId,
     connectionName: preparedConnection.connection.name,
@@ -651,16 +656,16 @@ function buildPlan(params: {
     exitPoint,
     trace: {
       type: "pcb_trace",
-      pcb_trace_id: `fanout:${preparedConnection.connection.name}`,
+      pcb_trace_id: outputIds.traceId,
       connection_name: preparedConnection.connection.name,
       connectsTo: [
-        preparedConnection.connection.name,
         ...(preparedConnection.sourcePoint.pointId
           ? [preparedConnection.sourcePoint.pointId]
           : []),
         ...(preparedConnection.sourcePoint.pcb_port_id
           ? [preparedConnection.sourcePoint.pcb_port_id]
           : []),
+        outputIds.boundaryExitPointId,
       ],
       route,
     },
@@ -804,18 +809,22 @@ function addPlaneEndpointTerminal(params: {
     toLayer: targetEndpointLayer,
     spanLayers,
   }
+  const outputIds = createFanoutOutputIds({
+    connectionName: preparedConnection.connection.name,
+    sourcePointIndex: preparedConnection.sourcePointIndex,
+  })
   const planeEndpointTrace: SimplifiedPcbTrace = {
     type: "pcb_trace",
-    pcb_trace_id: `fanout-plane-endpoint:${preparedConnection.connection.name}`,
+    pcb_trace_id: outputIds.planeEndpointTraceId,
     connection_name: preparedConnection.connection.name,
     connectsTo: [
-      preparedConnection.connection.name,
       ...(preparedConnection.targetPoint.pointId
         ? [preparedConnection.targetPoint.pointId]
         : []),
       ...(preparedConnection.targetPoint.pcb_port_id
         ? [preparedConnection.targetPoint.pcb_port_id]
         : []),
+      outputIds.planeEndpointPointId,
     ],
     route: [
       {

package/lib/route-single-layer-adaptive-exits.ts

@@ -9,6 +9,7 @@ import {
   distanceSegmentToObstacle,
   distanceSegmentToSegment,
 } from "./geometry"
+import { createFanoutOutputIds } from "./fanout-output-ids"
 import { type AvailableBoundaryRegion, getRegionAnchor } from "./prepare-buses"
 import type {
   FanoutDirection,
@@ -815,6 +816,10 @@ function buildPlan(route: FlowRoute, traceWidth: number): FanoutRoutePlan {
         : {}),
     }),
   )
+  const outputIds = createFanoutOutputIds({
+    connectionName: item.connection.connection.name,
+    sourcePointIndex: item.connection.sourcePointIndex,
+  })
   return {
     busId: item.bus.busId,
     connectionName: item.connection.connection.name,
@@ -830,17 +835,16 @@ function buildPlan(route: FlowRoute, traceWidth: number): FanoutRoutePlan {
     exitPoint: points.at(-1)!,
     trace: {
       type: "pcb_trace",
-      pcb_trace_id: `fanout:${item.connection.connection.name}`,
+      pcb_trace_id: outputIds.traceId,
       connection_name: item.connection.connection.name,
       connectsTo: [
-        item.connection.connection.name,
-        item.netKey,
         ...(item.connection.sourcePoint.pointId
           ? [item.connection.sourcePoint.pointId]
           : []),
         ...(item.connection.sourcePoint.pcb_port_id
           ? [item.connection.sourcePoint.pcb_port_id]
           : []),
+        outputIds.boundaryExitPointId,
       ],
       route: traceRoute,
     },

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

@@ -8,6 +8,7 @@ import {
   distanceSegmentToObstacle,
   distanceSegmentToSegment,
 } from "./geometry"
+import { createFanoutOutputIds } from "./fanout-output-ids"
 import type {
   FanoutBorderDistribution,
   FanoutCorner,
@@ -197,7 +198,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 +284,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
@@ -748,6 +752,10 @@ function buildPlan(path: RoutedPath): FanoutRoutePlan {
       ? { start_pcb_port_id: item.connection.sourcePoint.pcb_port_id }
       : {}),
   }))
+  const outputIds = createFanoutOutputIds({
+    connectionName: item.connection.connection.name,
+    sourcePointIndex: item.connection.sourcePointIndex,
+  })
   return {
     busId: item.bus.busId,
     connectionName: item.connection.connection.name,
@@ -763,16 +771,16 @@ function buildPlan(path: RoutedPath): FanoutRoutePlan {
     exitPoint: points.at(-1)!,
     trace: {
       type: "pcb_trace",
-      pcb_trace_id: `fanout:${item.connection.connection.name}`,
+      pcb_trace_id: outputIds.traceId,
       connection_name: item.connection.connection.name,
       connectsTo: [
-        item.connection.connection.name,
         ...(item.connection.sourcePoint.pointId
           ? [item.connection.sourcePoint.pointId]
           : []),
         ...(item.connection.sourcePoint.pcb_port_id
           ? [item.connection.sourcePoint.pcb_port_id]
           : []),
+        outputIds.boundaryExitPointId,
       ],
       route,
     },

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.26",
   "description": "BGA fanout solver with coordinated bus-layer escapes for SimpleRouteJson",
   "module": "lib/index.ts",
   "type": "module",
@@ -42,16 +42,22 @@
     "@biomejs/biome": "2.5.5",
     "@tsci/tscircuit.dataset-srj19-bga-passive-overlays": "github:tscircuit/dataset-srj19#c1206f3",
     "@tsci/tscircuit.dataset-srj29-bga-decoupling": "github:tscircuit/dataset-srj29-bga-decoupling#bfdf7bc",
+    "@tscircuit/alphabet": "0.0.25",
+    "@tscircuit/circuit-json-util": "0.0.97",
     "@tscircuit/footprinter": "0.0.394",
     "@types/bun": "1.3.14",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "bun-match-svg": "^0.0.16",
     "circuit-json": "0.0.455",
+    "circuit-json-to-connectivity-map": "0.0.23",
+    "circuit-to-svg": "0.0.364",
+    "format-si-unit": "0.0.7",
     "react": "19.2.8",
     "react-cosmos": "7.3.0",
     "react-cosmos-plugin-vite": "7.3.0",
     "react-dom": "19.2.8",
+    "schematic-symbols": "0.0.231",
     "vite": "8.1.5"
   },
   "peerDependencies": {