@tscircuit/fanout-solver 0.0.25 → 0.0.27

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

@@ -1028,8 +1028,31 @@ export class FanoutSolver extends BaseSolver {
     this.pendingRepairAssignments.push(...repairs)
   }
 
+  private hasCompleteBestAttempt(): boolean {
+    return (
+      this.bestAttempt?.summary.routedConnectionCount ===
+      this.inputSrj.connections.length
+    )
+  }
+
+  private shouldEvaluateGroupedBeam(): boolean {
+    if (this.groupedBeamEvaluated || this.nextAssignmentIndex === 0) {
+      return false
+    }
+
+    const targetedRepairSearchFinished =
+      this.hasCompleteBestAttempt() ||
+      this.pendingRepairAssignments.length === 0 ||
+      this.nextAssignmentIndex >= this.config.maxLayerCombinations
+
+    return targetedRepairSearchFinished
+  }
+
   override _step(): void {
-    if (!this.groupedBeamEvaluated) {
+    // Try the deterministic assignment and only its targeted repair queue
+    // before paying for the grouped beam. If the beam cannot solve, continue
+    // with the broader generated-assignment search below.
+    if (this.shouldEvaluateGroupedBeam()) {
       this.groupedBeamEvaluated = true
       let beamAttempt = this.evaluateGroupedBeam(-1)
       if (!beamAttempt) {
@@ -1037,19 +1060,33 @@ export class FanoutSolver extends BaseSolver {
       }
       if (beamAttempt) {
         this.attempts.push(beamAttempt.summary)
-        this.bestAttempt = beamAttempt
+        if (
+          !this.bestAttempt ||
+          beamAttempt.summary.score < this.bestAttempt.summary.score
+        ) {
+          this.bestAttempt = beamAttempt
+        }
+        const bestSummary = this.bestAttempt.summary
         this.stats = {
-          assignment: 0,
+          assignment:
+            bestSummary.assignmentIndex < 0
+              ? 0
+              : bestSummary.assignmentIndex + 1,
           assignmentCount: this.config.maxLayerCombinations,
-          routedBuses: `${beamAttempt.summary.routedBusCount}/${this.preparedBuses.length}`,
-          routedConnections: `${beamAttempt.summary.routedConnectionCount}/${this.inputSrj.connections.length}`,
+          routedBuses: `${bestSummary.routedBusCount}/${this.preparedBuses.length}`,
+          routedConnections: `${bestSummary.routedConnectionCount}/${this.inputSrj.connections.length}`,
           failedBuses: "none",
-          bestScore: beamAttempt.summary.score,
+          bestScore: bestSummary.score,
         }
         this.completeBestAttemptEndpoints()
         this.solved = true
         return
       }
+      if (this.hasCompleteBestAttempt()) {
+        this.completeBestAttemptEndpoints()
+        this.solved = true
+        return
+      }
     }
 
     let assignment: Readonly<Record<string, string>> | undefined
@@ -1060,13 +1097,19 @@ export class FanoutSolver extends BaseSolver {
       const preferGeneratedAssignment = this.nextAssignmentIndex % 3 === 0
       let candidate: Readonly<Record<string, string>> | undefined
       let candidateCameFromRepairQueue = false
-      if (preferGeneratedAssignment) {
+      if (!this.groupedBeamEvaluated && this.nextAssignmentIndex > 0) {
+        candidate = this.pendingRepairAssignments.pop()
+        candidateCameFromRepairQueue = candidate !== undefined
+      } else if (preferGeneratedAssignment) {
         candidate = this.layerAssignments[this.nextGeneratedAssignmentIndex++]
       } else {
         candidate = this.pendingRepairAssignments.pop()
         candidateCameFromRepairQueue = candidate !== undefined
       }
-      if (!candidate) {
+      if (
+        !candidate &&
+        (this.groupedBeamEvaluated || this.nextAssignmentIndex === 0)
+      ) {
         candidate = preferGeneratedAssignment
           ? this.pendingRepairAssignments.pop()
           : this.layerAssignments[this.nextGeneratedAssignmentIndex++]
@@ -1081,12 +1124,9 @@ export class FanoutSolver extends BaseSolver {
       if (this.evaluatedAssignmentKeys.has(candidateKey)) continue
       assignment = candidate
     }
+    if (!assignment && !this.groupedBeamEvaluated) return
     if (!assignment) {
-      if (
-        this.bestAttempt &&
-        this.bestAttempt.summary.routedConnectionCount ===
-          this.inputSrj.connections.length
-      ) {
+      if (this.hasCompleteBestAttempt()) {
         this.completeBestAttemptEndpoints()
         this.solved = true
       } else {
@@ -1131,6 +1171,7 @@ export class FanoutSolver extends BaseSolver {
       bestScore: this.bestAttempt.summary.score,
     }
     if (
+      this.groupedBeamEvaluated &&
       attempt.summary.routedConnectionCount === this.inputSrj.connections.length
     ) {
       this.completeBestAttemptEndpoints()

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,
@@ -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,
@@ -751,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,
@@ -766,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tscircuit/fanout-solver",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "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": {