@tscircuit/fanout-solver 0.0.35 → 0.0.37

package/lib/types.ts

@@ -21,6 +21,35 @@ export type FanoutCorner =
 
 export type FanoutBorderTarget = FanoutEdge | FanoutCorner
 
+/**
+ * An unambiguous fanout exit position.
+ *
+ * The `*side` prefix names the physical shared-boundary edge. A corner suffix
+ * names the local escape direction and band on that edge; a `_center` suffix
+ * escapes outward through the middle of that edge. `center` leaves all three
+ * exit fields unconstrained.
+ */
+export type FanoutExitPosition =
+  | "topside_left"
+  | "topside_center"
+  | "topside_right"
+  | "rightside_top"
+  | "rightside_center"
+  | "rightside_bottom"
+  | "bottomside_right"
+  | "bottomside_center"
+  | "bottomside_left"
+  | "leftside_bottom"
+  | "leftside_center"
+  | "leftside_top"
+  | "center"
+
+export interface FanoutExitPositionConfig {
+  direction?: FanoutDirection
+  preferredExit?: FanoutBorderTarget
+  exitEdge?: FanoutEdge
+}
+
 /**
  * A directed region of the shared fanout boundary. Corner regions are named
  * after the edge they belong to, so `top_left` exits through the top edge and
@@ -74,8 +103,19 @@ export type FanoutBusTermination =
 export interface FanoutBusSpec extends SimpleRouteBus {
   /** Component whose connection endpoints should be escaped. */
   sourceComponentId?: string
+  /** Canonical local-escape, boundary-edge, and edge-band selection. */
+  exitPosition?: FanoutExitPosition
+  /** Direction used to leave the source pads locally. */
   direction?: FanoutDirection
   preferredExit?: FanoutBorderTarget
+  /**
+   * Physical boundary edge on which the fanout endpoints terminate.
+   *
+   * This is independent of `direction`: a bus may escape its pads `up`, use
+   * the `top-right` band, and terminate on the `right` edge. An explicit edge
+   * plus a corner-valued `preferredExit` enables the packed boundary channel.
+   */
+  exitEdge?: FanoutEdge
   /** Layers to which this bus is allowed to escape. */
   allowedLayers?: readonly string[]
   /**
@@ -84,9 +124,14 @@ export interface FanoutBusSpec extends SimpleRouteBus {
    * 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.
+   * exit here so both sides aim toward the same track. When every target also
+   * includes a layer, the solver may use the bus's other allowed layer as an
+   * internal crossover channel, then return every exit to one common bus layer
+   * in the supplied target order.
    */
-  connectionExitTargets?: Readonly<Record<string, Point2D>>
+  connectionExitTargets?: Readonly<
+    Record<string, Point2D & { readonly layer?: string }>
+  >
   /**
    * Defaults to `{ type: "boundary" }`.
    *
@@ -239,15 +284,23 @@ export interface PreparedConnection {
   sourceObstacle: Obstacle
   targetPoint: ConnectionPoint
   /** Preferred downstream point used to choose the boundary exit track. */
-  exitTargetPoint?: Point2D
+  exitTargetPoint?: Point2D & { readonly layer?: string }
+  /** Whether the caller supplied the layered handoff metadata needed to coordinate winding. */
+  hasExplicitLayeredExitTarget?: boolean
 }
 
 export interface PreparedBus {
   busId: string
   direction: FanoutDirection
   preferredExit?: FanoutBorderTarget
+  /** Explicit final boundary edge. Omitted for legacy direction-based exits. */
+  exitEdge?: FanoutEdge
+  /** Total connection count sharing this explicit edge/corner band. */
+  cornerBandConnectionCount?: number
   /** Layers to which this bus is allowed to escape. */
   allowedLayers?: readonly string[]
+  /** Bus layers that also survive the solver-wide escape-layer restriction. */
+  routableEscapeLayers?: readonly string[]
   termination: FanoutBusTermination
   connections: PreparedConnection[]
   componentId: string
@@ -287,11 +340,18 @@ export interface FanoutRoutePlan {
   targetPoint: ConnectionPoint
   targetLayer: string
   termination: FanoutBusTermination
+  /** Local pad escape direction. */
   direction: FanoutDirection
+  /** Explicit physical boundary edge used by a packed corner channel. */
+  exitEdge?: FanoutEdge
+  /** Lower/left or upper/right band reserved along `exitEdge`. */
+  cornerBandSide?: "minimum" | "maximum"
   exitPoint: Point2D
   trace: SimplifiedPcbTrace
   segments: RoutedSegment[]
   via?: RoutedVia
+  /** Additional layer transitions used by an explicit winding channel. */
+  additionalVias?: RoutedVia[]
   /** Optional capacitor-side dogbone reserved and emitted with a plane escape. */
   planeEndpointTrace?: SimplifiedPcbTrace
   planeEndpointSegments?: RoutedSegment[]

package/lib/validate-fanout-solution.ts

@@ -3,6 +3,7 @@ import type {
   SimpleRouteJson,
   SimplifiedPcbTrace,
 } from "@tscircuit/capacity-autorouter"
+import { getCornerBandSide } from "./boundary-exit"
 import {
   distance,
   distancePointToObstacle,
@@ -11,13 +12,14 @@ import {
   distanceSegmentToSegment,
   segmentsAreClear,
 } from "./geometry"
+import { getAllRoutedTraceCopper } from "./get-routed-trace-copper"
 import {
   connectionsShareElectricalNet,
   obstacleSharesElectricalNet,
 } from "./net-identity"
-import { getAllRoutedTraceCopper } from "./get-routed-trace-copper"
 import type {
   Bounds,
+  FanoutEdge,
   FanoutRoutePlan,
   FanoutValidationIssue,
   FanoutValidationReport,
@@ -42,9 +44,11 @@ function getPlanSegments(plan: FanoutRoutePlan): RoutedSegment[] {
 }
 
 function getPlanVias(plan: FanoutRoutePlan) {
-  return [plan.via, plan.planeEndpointVia].filter(
-    (via): via is NonNullable<FanoutRoutePlan["via"]> => Boolean(via),
-  )
+  return [
+    plan.via,
+    ...(plan.additionalVias ?? []),
+    plan.planeEndpointVia,
+  ].filter((via): via is NonNullable<FanoutRoutePlan["via"]> => Boolean(via))
 }
 
 function connectionPointsMatch(
@@ -73,6 +77,29 @@ function pointIsOnBoundary(point: Point2D, boundary: Bounds): boolean {
   return inside && onEdge
 }
 
+function pointIsOnBoundaryEdge(
+  point: Point2D,
+  edge: FanoutEdge,
+  boundary: Bounds,
+): boolean {
+  const inside =
+    point.x >= boundary.minX - EPSILON &&
+    point.x <= boundary.maxX + EPSILON &&
+    point.y >= boundary.minY - EPSILON &&
+    point.y <= boundary.maxY + EPSILON
+  if (!inside) return false
+  switch (edge) {
+    case "left":
+      return Math.abs(point.x - boundary.minX) <= EPSILON
+    case "right":
+      return Math.abs(point.x - boundary.maxX) <= EPSILON
+    case "top":
+      return Math.abs(point.y - boundary.maxY) <= EPSILON
+    case "bottom":
+      return Math.abs(point.y - boundary.minY) <= EPSILON
+  }
+}
+
 function pointIsInsideBounds(point: Point2D, bounds: Bounds): boolean {
   return (
     point.x >= bounds.minX - EPSILON &&
@@ -236,6 +263,31 @@ function validatePlanStructure(params: {
       plan,
     )
   }
+  const expectedCornerBandSide = getCornerBandSide(
+    preparedBus?.exitEdge,
+    preparedBus?.preferredExit,
+  )
+  if (
+    preparedBus?.exitEdge !== plan.exitEdge ||
+    expectedCornerBandSide !== plan.cornerBandSide
+  ) {
+    addIssue(
+      issues,
+      "output-exit-mismatch",
+      `Plan ${plan.connectionName} does not retain its prepared boundary edge and band`,
+      plan,
+    )
+  } else if (
+    preparedBus?.exitEdge &&
+    !pointIsOnBoundaryEdge(plan.exitPoint, preparedBus.exitEdge, sharedBoundary)
+  ) {
+    addIssue(
+      issues,
+      "output-exit-mismatch",
+      `Plan ${plan.connectionName} does not terminate on its declared ${preparedBus.exitEdge} edge`,
+      plan,
+    )
+  }
   if (plan.segments.length === 0 || plan.length <= EPSILON) {
     addIssue(
       issues,
@@ -291,13 +343,13 @@ function validatePlanStructure(params: {
           plan,
         )
       }
-      if (
-        previous.layer !== current.layer &&
-        (!plan.via ||
-          !pointsMatch(previous.end, plan.via.center) ||
-          !plan.via.spanLayers.includes(previous.layer) ||
-          !plan.via.spanLayers.includes(current.layer))
-      ) {
+      const transitionVia = getPlanVias(plan).find(
+        (via) =>
+          pointsMatch(previous.end, via.center) &&
+          via.spanLayers.includes(previous.layer) &&
+          via.spanLayers.includes(current.layer),
+      )
+      if (previous.layer !== current.layer && !transitionVia) {
         addIssue(
           issues,
           "disconnected-trace",

package/package.json

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