@tscircuit/fanout-solver 0.0.34 → 0.0.36

package/README.md

@@ -29,6 +29,10 @@ and treats each bus-layer decision atomically.
   (`left`, `right`, `top`, or `bottom`) or corner (`top-left`, `top-right`,
   `bottom-left`, or `bottom-right`). A corner chooses a compatible adjacent
   edge and reserves the bus at that end of the border.
+- Accepts an unambiguous `exitPosition` bus field when the local pad escape and
+  final boundary edge differ. For example, `rightside_top` escapes locally
+  upward into the upper band and terminates on the right boundary, while
+  `topside_right` escapes locally rightward and terminates on the top boundary.
 - `availableCornersAndSides` can restrict every boundary-terminated bus to
   named regions of the shared boundary. For example,
   `['top_left', 'top_middle', 'top_right']` allows only top-edge exits;
@@ -161,6 +165,16 @@ const autorouter = new CapacityMeshSolver(
 autorouter.solve()
 ```
 
+Canonical exit positions are edge-first: `topside_left`, `topside_center`,
+`topside_right`, `rightside_top`, `rightside_center`, `rightside_bottom`,
+`bottomside_right`, `bottomside_center`, `bottomside_left`, `leftside_bottom`,
+`leftside_center`, `leftside_top`, and `center`. They normalize atomically into
+the local `direction`, boundary-band `preferredExit`, and physical `exitEdge`;
+conflicting bus-level legacy fields are rejected. Existing buses that omit
+`exitPosition` retain their previous behavior. Hosts can import
+`getFanoutExitPositionConfig` to inspect the same normalized tuple without
+duplicating this mapping.
+
 The downstream callback is optional. It lets the application choose its
 board-level router while keeping `@tscircuit/fanout-solver` free of a runtime
 autorouter import. Returned traces are still accepted only after the fanout

package/lib/boundary-exit.ts

@@ -0,0 +1,52 @@
+import type { FanoutBorderTarget, FanoutDirection, FanoutEdge } from "./types"
+
+export function getExitEdgeForDirection(
+  direction: FanoutDirection,
+): FanoutEdge {
+  switch (direction) {
+    case "left":
+      return "left"
+    case "right":
+      return "right"
+    case "up":
+      return "top"
+    case "down":
+      return "bottom"
+  }
+}
+
+export function getDirectionForExitEdge(exitEdge: FanoutEdge): FanoutDirection {
+  switch (exitEdge) {
+    case "left":
+      return "left"
+    case "right":
+      return "right"
+    case "top":
+      return "up"
+    case "bottom":
+      return "down"
+  }
+}
+
+export function borderTargetIncludesEdge(
+  preferredExit: FanoutBorderTarget,
+  exitEdge: FanoutEdge,
+): boolean {
+  return preferredExit === exitEdge || preferredExit.includes(exitEdge)
+}
+
+/**
+ * Returns the lower/left or upper/right band selected along an explicit edge.
+ * Edge-center targets do not select a corner band.
+ */
+export function getCornerBandSide(
+  exitEdge: FanoutEdge | undefined,
+  preferredExit: FanoutBorderTarget | undefined,
+): "minimum" | "maximum" | undefined {
+  if (!exitEdge || !preferredExit?.includes("-")) return undefined
+  if (!borderTargetIncludesEdge(preferredExit, exitEdge)) return undefined
+  if (exitEdge === "left" || exitEdge === "right") {
+    return preferredExit.startsWith("top-") ? "maximum" : "minimum"
+  }
+  return preferredExit.endsWith("-right") ? "maximum" : "minimum"
+}

package/lib/fanout-exit-position.ts

@@ -0,0 +1,78 @@
+import type { FanoutExitPosition, FanoutExitPositionConfig } from "./types"
+
+const FANOUT_EXIT_POSITION_CONFIGS: Readonly<
+  Record<FanoutExitPosition, Readonly<FanoutExitPositionConfig>>
+> = {
+  topside_left: {
+    direction: "left",
+    preferredExit: "top-left",
+    exitEdge: "top",
+  },
+  topside_center: {
+    direction: "up",
+    preferredExit: "top",
+    exitEdge: "top",
+  },
+  topside_right: {
+    direction: "right",
+    preferredExit: "top-right",
+    exitEdge: "top",
+  },
+  rightside_top: {
+    direction: "up",
+    preferredExit: "top-right",
+    exitEdge: "right",
+  },
+  rightside_center: {
+    direction: "right",
+    preferredExit: "right",
+    exitEdge: "right",
+  },
+  rightside_bottom: {
+    direction: "down",
+    preferredExit: "bottom-right",
+    exitEdge: "right",
+  },
+  bottomside_right: {
+    direction: "right",
+    preferredExit: "bottom-right",
+    exitEdge: "bottom",
+  },
+  bottomside_center: {
+    direction: "down",
+    preferredExit: "bottom",
+    exitEdge: "bottom",
+  },
+  bottomside_left: {
+    direction: "left",
+    preferredExit: "bottom-left",
+    exitEdge: "bottom",
+  },
+  leftside_bottom: {
+    direction: "down",
+    preferredExit: "bottom-left",
+    exitEdge: "left",
+  },
+  leftside_center: {
+    direction: "left",
+    preferredExit: "left",
+    exitEdge: "left",
+  },
+  leftside_top: {
+    direction: "up",
+    preferredExit: "top-left",
+    exitEdge: "left",
+  },
+  center: {},
+}
+
+/** Resolves a canonical exit position into the solver's orthogonal fields. */
+export function getFanoutExitPositionConfig(
+  exitPosition: FanoutExitPosition,
+): Readonly<FanoutExitPositionConfig> {
+  const config = FANOUT_EXIT_POSITION_CONFIGS[exitPosition]
+  if (!config) {
+    throw new Error(`Invalid fanout exit position "${exitPosition}"`)
+  }
+  return config
+}

package/lib/fanout-solver.ts

@@ -1,10 +1,11 @@
 import type { SimpleRouteJson } from "@tscircuit/capacity-autorouter"
 import { BaseSolver } from "@tscircuit/solver-utils"
 import type { GraphicsObject } from "graphics-debug"
+import { getCornerBandSide } from "./boundary-exit"
 import { buildOutputSimpleRouteJson } from "./build-output"
 import {
-  completeOriginalEndpoints,
   type CompleteOriginalEndpointsResult,
+  completeOriginalEndpoints,
 } from "./complete-original-endpoints"
 import { generateLayerAssignments, getCopperLayerNames } from "./layer-names"
 import {
@@ -12,14 +13,12 @@ import {
   resolveAvailableBoundaryRegions,
 } from "./prepare-buses"
 import {
+  type RouteBusStaticClearanceCache,
   routeBus,
   routeBusAlternatives,
-  type RouteBusStaticClearanceCache,
 } from "./route-bus"
 import { routeSingleLayerWithAdaptiveExits } from "./route-single-layer-adaptive-exits"
 import { routeSingleLayerWithPushAndShove } from "./route-single-layer-push-shove"
-import { validateFanoutSolution } from "./validate-fanout-solution"
-import { visualizeSimpleRouteJson } from "./visualize-simple-route-json"
 import type {
   AssignmentAttempt,
   Bounds,
@@ -30,6 +29,8 @@ import type {
   FanoutSolverOutput,
   PreparedBus,
 } from "./types"
+import { validateFanoutSolution } from "./validate-fanout-solution"
+import { visualizeSimpleRouteJson } from "./visualize-simple-route-json"
 
 interface ResolvedFanoutConfig {
   traceWidth: number
@@ -146,6 +147,45 @@ function resolveConfig(
   }
 }
 
+function validateCornerBandCapacities(
+  buses: readonly PreparedBus[],
+  config: ResolvedFanoutConfig,
+): void {
+  const checkedBands = new Set<string>()
+  const exitPitch = Math.max(
+    config.traceWidth + config.clearance,
+    config.viaDiameter + config.clearance,
+  )
+  // Keep the block clear of the physical end of the edge and leave one
+  // unoccupied via-pitch between the minimum and maximum quarter bands.
+  const endInset = Math.max(
+    config.viaDiameter / 2 + config.clearance,
+    exitPitch,
+  )
+
+  for (const bus of buses) {
+    const side = getCornerBandSide(bus.exitEdge, bus.preferredExit)
+    if (!bus.exitEdge || !side) continue
+    const bandKey = `${bus.exitEdge}:${side}`
+    if (checkedBands.has(bandKey)) continue
+    checkedBands.add(bandKey)
+
+    const edgeLength =
+      bus.exitEdge === "left" || bus.exitEdge === "right"
+        ? bus.sharedBoundary.maxY - bus.sharedBoundary.minY
+        : bus.sharedBoundary.maxX - bus.sharedBoundary.minX
+    const connectionCount =
+      bus.cornerBandConnectionCount ?? bus.connections.length
+    const halfTrackSpan = ((connectionCount - 1) * exitPitch) / 2
+    const availableHalfTrackSpan = edgeLength / 4 - endInset
+    if (halfTrackSpan > availableHalfTrackSpan + 1e-6) {
+      throw new Error(
+        `FanoutSolver: ${side} band on the ${bus.exitEdge} edge cannot fit ${connectionCount} via-safe exits`,
+      )
+    }
+  }
+}
+
 function assignmentLoadPenalty(
   assignment: Readonly<Record<string, string>>,
   buses: readonly PreparedBus[],
@@ -411,6 +451,7 @@ export class FanoutSolver extends BaseSolver {
     }
     this.config = resolveConfig(inputSrj, options)
     this.preparedBuses = prepareFanoutBuses(this.routingSrj, options)
+    validateCornerBandCapacities(this.preparedBuses, this.config)
     for (const bus of this.preparedBuses) {
       for (const allowedLayer of bus.allowedLayers ?? []) {
         if (!this.config.layerNames.includes(allowedLayer)) {
@@ -566,7 +607,13 @@ export class FanoutSolver extends BaseSolver {
     let failedBusIds: string[] = []
     let blockingBusCounts = new Map<string, number>()
     const isSingleLayerFanout = this.config.escapeLayers.length === 1
-    if (isSingleLayerFanout && this.config.singleLayerPushAndShove) {
+    const useSingleLayerPushAndShove =
+      isSingleLayerFanout &&
+      this.config.singleLayerPushAndShove &&
+      !this.preparedBuses.some(
+        (bus) => bus.exitEdge && bus.preferredExit?.includes("-"),
+      )
+    if (useSingleLayerPushAndShove) {
       const singleLayerParams = {
         srj: this.routingSrj,
         buses: this.preparedBuses,
@@ -609,9 +656,7 @@ export class FanoutSolver extends BaseSolver {
     )
 
     let routingPrefixKey = `${routingStrategy}|`
-    for (const bus of isSingleLayerFanout && this.config.singleLayerPushAndShove
-      ? []
-      : busesInRoutingOrder) {
+    for (const bus of useSingleLayerPushAndShove ? [] : busesInRoutingOrder) {
       const targetLayer = busLayerAssignments[bus.busId]
       if (!targetLayer) {
         throw new Error(

package/lib/index.ts

@@ -1,19 +1,8 @@
-export { FanoutSolver } from "./fanout-solver"
 export { completeOriginalEndpoints } from "./complete-original-endpoints"
+export { getFanoutExitPositionConfig } from "./fanout-exit-position"
+export { FanoutSolver } from "./fanout-solver"
 export { getCopperLayerColor } from "./layer-colors"
 export { getCopperLayerNames } from "./layer-names"
-export { validateOriginalEndpointConnectivity } from "./validate-original-endpoint-connectivity"
-export { validateRoutedCopperDrc } from "./validate-routed-copper-drc"
-export { validateFanoutSolution } from "./validate-fanout-solution"
-export type {
-  OriginalEndpointConnectivityIssue,
-  OriginalEndpointConnectivityReport,
-} from "./validate-original-endpoint-connectivity"
-export type {
-  RoutedCopperDrcIssue,
-  RoutedCopperDrcIssueCode,
-  RoutedCopperDrcReport,
-} from "./validate-routed-copper-drc"
 export type {
   Bounds,
   FanoutAttemptSummary,
@@ -30,6 +19,8 @@ export type {
   FanoutDownstreamRouterOptions,
   FanoutEdge,
   FanoutEndpointCompletionReport,
+  FanoutExitPosition,
+  FanoutExitPositionConfig,
   FanoutPlaneConnectivity,
   FanoutPlaneTermination,
   FanoutRoutePlan,
@@ -41,3 +32,15 @@ export type {
   PreparedBus,
   SimpleRouteJsonWithFanoutPlanes,
 } from "./types"
+export { validateFanoutSolution } from "./validate-fanout-solution"
+export type {
+  OriginalEndpointConnectivityIssue,
+  OriginalEndpointConnectivityReport,
+} from "./validate-original-endpoint-connectivity"
+export { validateOriginalEndpointConnectivity } from "./validate-original-endpoint-connectivity"
+export type {
+  RoutedCopperDrcIssue,
+  RoutedCopperDrcIssueCode,
+  RoutedCopperDrcReport,
+} from "./validate-routed-copper-drc"
+export { validateRoutedCopperDrc } from "./validate-routed-copper-drc"

package/lib/prepare-buses.ts

@@ -4,6 +4,8 @@ import type {
   SimpleRouteConnection,
   SimpleRouteJson,
 } from "@tscircuit/capacity-autorouter"
+import { borderTargetIncludesEdge, getCornerBandSide } from "./boundary-exit"
+import { getFanoutExitPositionConfig } from "./fanout-exit-position"
 import { distance, pointIsInsideObstacle } from "./geometry"
 import type {
   Bounds,
@@ -12,6 +14,9 @@ import type {
   FanoutBusSpec,
   FanoutBusTermination,
   FanoutDirection,
+  FanoutEdge,
+  FanoutExitPosition,
+  FanoutExitPositionConfig,
   FanoutSolverOptions,
   PreparedBus,
   PreparedConnection,
@@ -20,6 +25,8 @@ import type {
 export interface AvailableBoundaryRegion {
   direction: FanoutDirection
   preferredExit: FanoutBorderTarget
+  /** Physical shared-boundary edge selected by the first region token. */
+  exitEdge: FanoutEdge
 }
 
 const FANOUT_BORDER_TARGETS = new Set<FanoutBorderTarget>([
@@ -33,72 +40,90 @@ const FANOUT_BORDER_TARGETS = new Set<FanoutBorderTarget>([
   "bottom-right",
 ])
 
+const FANOUT_EDGES = new Set<FanoutEdge>(["left", "right", "top", "bottom"])
+
 const AVAILABLE_BOUNDARY_REGIONS: Readonly<
   Record<FanoutAvailableCornerAndSideInput, AvailableBoundaryRegion>
 > = {
   top_left: {
     direction: "up",
     preferredExit: "top-left",
+    exitEdge: "top",
   },
   top_middle: {
     direction: "up",
     preferredExit: "top",
+    exitEdge: "top",
   },
   top_right: {
     direction: "up",
     preferredExit: "top-right",
+    exitEdge: "top",
   },
   right_top: {
     direction: "right",
     preferredExit: "top-right",
+    exitEdge: "right",
   },
   right_middle: {
     direction: "right",
     preferredExit: "right",
+    exitEdge: "right",
   },
   right_bottom: {
     direction: "right",
     preferredExit: "bottom-right",
+    exitEdge: "right",
   },
   bottom_right: {
     direction: "down",
     preferredExit: "bottom-right",
+    exitEdge: "bottom",
   },
   bottom_middle: {
     direction: "down",
     preferredExit: "bottom",
+    exitEdge: "bottom",
   },
   bottom_left: {
     direction: "down",
     preferredExit: "bottom-left",
+    exitEdge: "bottom",
   },
   left_bottom: {
     direction: "left",
     preferredExit: "bottom-left",
+    exitEdge: "left",
   },
   left_middle: {
     direction: "left",
     preferredExit: "left",
+    exitEdge: "left",
   },
   left_top: {
     direction: "left",
     preferredExit: "top-left",
+    exitEdge: "left",
   },
   top: {
     direction: "up",
     preferredExit: "top",
+    exitEdge: "top",
   },
   right: {
     direction: "right",
     preferredExit: "right",
+    exitEdge: "right",
   },
   bottom: {
     direction: "down",
     preferredExit: "bottom",
+    exitEdge: "bottom",
   },
   left: {
     direction: "left",
     preferredExit: "left",
+    exitEdge: "left",
   },
 }
 
@@ -407,6 +432,134 @@ function resolvePreferredExit(
   return value
 }
 
+function resolveExitEdge(
+  busId: string,
+  value: FanoutEdge | undefined,
+): FanoutEdge | undefined {
+  if (value === undefined) return undefined
+  if (!FANOUT_EDGES.has(value)) {
+    throw new Error(
+      `FanoutSolver: bus "${busId}" has invalid exitEdge "${value}"`,
+    )
+  }
+  return value
+}
+
+function resolveExitPosition(
+  busId: string,
+  value: FanoutExitPosition | undefined,
+): Readonly<FanoutExitPositionConfig> | undefined {
+  if (value === undefined) return undefined
+  try {
+    return getFanoutExitPositionConfig(value)
+  } catch {
+    throw new Error(
+      `FanoutSolver: bus "${busId}" has invalid exitPosition "${value}"`,
+    )
+  }
+}
+
+function assertExitPositionFieldMatches<T extends string>(params: {
+  busId: string
+  exitPosition: FanoutExitPosition
+  fieldName: "direction" | "preferredExit" | "exitEdge"
+  expected: T | undefined
+  actual: T | undefined
+  sourceName: string
+}): void {
+  const { busId, exitPosition, fieldName, expected, actual, sourceName } =
+    params
+  if (actual === undefined || actual === expected) return
+  throw new Error(
+    `FanoutSolver: bus "${busId}" exitPosition "${exitPosition}" conflicts with ${sourceName} ${fieldName} "${actual}"`,
+  )
+}
+
+function resolveBusExitFields(params: {
+  busId: string
+  requestedBus: FanoutBusSpec
+  options: FanoutSolverOptions
+}): Pick<
+  FanoutBusSpec,
+  "exitPosition" | "direction" | "preferredExit" | "exitEdge"
+> {
+  const { busId, requestedBus, options } = params
+  const exitPosition = requestedBus.exitPosition
+  const exitPositionConfig = resolveExitPosition(busId, exitPosition)
+  const busPreferredExit = resolvePreferredExit(
+    busId,
+    requestedBus.preferredExit,
+  )
+  const optionPreferredExit = resolvePreferredExit(
+    busId,
+    options.busExitPreferences?.[busId],
+  )
+  const busExitEdge = resolveExitEdge(busId, requestedBus.exitEdge)
+
+  if (exitPositionConfig && exitPosition) {
+    for (const [actual, sourceName] of [
+      [requestedBus.direction, "bus"],
+      [options.busDirections?.[busId], "busDirections"],
+    ] as const) {
+      assertExitPositionFieldMatches({
+        busId,
+        exitPosition,
+        fieldName: "direction",
+        expected: exitPositionConfig.direction,
+        actual,
+        sourceName,
+      })
+    }
+    for (const [actual, sourceName] of [
+      [busPreferredExit, "bus"],
+      [optionPreferredExit, "busExitPreferences"],
+    ] as const) {
+      assertExitPositionFieldMatches({
+        busId,
+        exitPosition,
+        fieldName: "preferredExit",
+        expected: exitPositionConfig.preferredExit,
+        actual,
+        sourceName,
+      })
+    }
+    assertExitPositionFieldMatches({
+      busId,
+      exitPosition,
+      fieldName: "exitEdge",
+      expected: exitPositionConfig.exitEdge,
+      actual: busExitEdge,
+      sourceName: "bus",
+    })
+    return {
+      exitPosition,
+      ...(exitPositionConfig.direction
+        ? { direction: exitPositionConfig.direction }
+        : {}),
+      ...(exitPositionConfig.preferredExit
+        ? { preferredExit: exitPositionConfig.preferredExit }
+        : {}),
+      ...(exitPositionConfig.exitEdge
+        ? { exitEdge: exitPositionConfig.exitEdge }
+        : {}),
+    }
+  }
+
+  const direction =
+    options.busDirections?.[busId] ??
+    requestedBus.direction ??
+    options.defaultDirection
+  const preferredExit = resolvePreferredExit(
+    busId,
+    optionPreferredExit ?? busPreferredExit ?? options.defaultPreferredExit,
+  )
+  return {
+    ...(direction ? { direction } : {}),
+    ...(preferredExit ? { preferredExit } : {}),
+    ...(busExitEdge ? { exitEdge: busExitEdge } : {}),
+  }
+}
+
 function resolveAllowedLayers(
   busId: string,
   allowedLayers: readonly string[] | undefined,
@@ -446,7 +599,7 @@ export function resolveAvailableBoundaryRegions(
         `FanoutSolver: invalid availableCornersAndSides value "${input}"`,
       )
     }
-    const key = `${region.direction}:${region.preferredExit}`
+    const key = `${region.exitEdge}:${region.direction}:${region.preferredExit}`
     if (seen.has(key)) continue
     seen.add(key)
     regions.push(region)
@@ -505,17 +658,19 @@ function resolveBusSpecs(
       requestedBus.busId,
       (requestedBus as FanoutBusSpec).termination,
     )
-    const preferredExit = resolvePreferredExit(
-      requestedBus.busId,
-      options.busExitPreferences?.[requestedBus.busId] ??
-        (requestedBus as FanoutBusSpec).preferredExit ??
-        options.defaultPreferredExit,
-    )
+    const resolvedExitFields = resolveBusExitFields({
+      busId: requestedBus.busId,
+      requestedBus: requestedBus as FanoutBusSpec,
+      options,
+    })
     const allowedLayers = resolveAllowedLayers(
       requestedBus.busId,
       (requestedBus as FanoutBusSpec).allowedLayers,
     )
-    if (termination.type === "plane" && preferredExit !== undefined) {
+    if (
+      termination.type === "plane" &&
+      resolvedExitFields.preferredExit !== undefined
+    ) {
       throw new Error(
         `FanoutSolver: plane-terminated bus "${requestedBus.busId}" cannot also specify preferredExit`,
       )
@@ -525,11 +680,7 @@ function resolveBusSpecs(
       sourceComponentId:
         (requestedBus as FanoutBusSpec).sourceComponentId ??
         options.sourceComponentId,
-      direction:
-        options.busDirections?.[requestedBus.busId] ??
-        (requestedBus as FanoutBusSpec).direction ??
-        options.defaultDirection,
-      preferredExit,
+      ...resolvedExitFields,
       ...(allowedLayers === undefined ? {} : { allowedLayers }),
       termination,
     })
@@ -540,26 +691,26 @@ function resolveBusSpecs(
     const inferredBusId = inferBusId(connection)
     if (inferredBusId) {
       const existing = specsById.get(inferredBusId)
-      specsById.set(inferredBusId, {
-        busId: inferredBusId,
-        connectionNames: [
-          ...(existing?.connectionNames ?? []),
-          connection.name,
-        ],
-        direction:
-          options.busDirections?.[inferredBusId] ??
-          existing?.direction ??
-          options.defaultDirection,
-        sourceComponentId:
-          existing?.sourceComponentId ?? options.sourceComponentId,
-        preferredExit: resolvePreferredExit(
-          inferredBusId,
-          options.busExitPreferences?.[inferredBusId] ??
-            existing?.preferredExit ??
-            options.defaultPreferredExit,
-        ),
-        termination: existing?.termination ?? { type: "boundary" },
-      })
+      if (existing) {
+        specsById.set(inferredBusId, {
+          ...existing,
+          connectionNames: [...existing.connectionNames, connection.name],
+        })
+      } else {
+        specsById.set(inferredBusId, {
+          busId: inferredBusId,
+          connectionNames: [connection.name],
+          direction:
+            options.busDirections?.[inferredBusId] ?? options.defaultDirection,
+          sourceComponentId: options.sourceComponentId,
+          preferredExit: resolvePreferredExit(
+            inferredBusId,
+            options.busExitPreferences?.[inferredBusId] ??
+              options.defaultPreferredExit,
+          ),
+          termination: { type: "boundary" },
+        })
+      }
     } else {
       const singletonBusId = `connection:${connection.name}`
       specsById.set(singletonBusId, {
@@ -892,6 +1043,27 @@ function resolveAvailableBusExit(params: {
   )[0]!
 }
 
+function validateExplicitExitAvailability(params: {
+  busId: string
+  exitEdge: FanoutEdge
+  preferredExit: FanoutBorderTarget
+  availableRegions: readonly AvailableBoundaryRegion[]
+}): void {
+  const { busId, exitEdge, preferredExit, availableRegions } = params
+  const requestedBandSide = getCornerBandSide(exitEdge, preferredExit)
+  const hasCompatibleRegion = availableRegions.some(
+    (region) =>
+      region.exitEdge === exitEdge &&
+      getCornerBandSide(region.exitEdge, region.preferredExit) ===
+        requestedBandSide,
+  )
+  if (!hasCompatibleRegion) {
+    throw new Error(
+      `FanoutSolver: bus "${busId}" cannot use its requested exit with availableCornersAndSides`,
+    )
+  }
+}
+
 function resolveBusDirection(params: {
   busId: string
   explicitDirection?: FanoutDirection
@@ -1031,6 +1203,20 @@ export function prepareFanoutBuses(
     sourceGrid,
     preparedConnections,
   } of resolvedBusInputs) {
+    if (busSpec.exitEdge && !busSpec.preferredExit) {
+      throw new Error(
+        `FanoutSolver: bus "${busSpec.busId}" exitEdge requires preferredExit`,
+      )
+    }
+    if (
+      busSpec.exitEdge &&
+      busSpec.preferredExit &&
+      !borderTargetIncludesEdge(busSpec.preferredExit, busSpec.exitEdge)
+    ) {
+      throw new Error(
+        `FanoutSolver: bus "${busSpec.busId}" exitEdge "${busSpec.exitEdge}" is incompatible with preferredExit "${busSpec.preferredExit}"`,
+      )
+    }
     const resolvedExit = resolveBusDirection({
       busId: busSpec.busId,
       explicitDirection:
@@ -1039,12 +1225,29 @@ export function prepareFanoutBuses(
       connections: preparedConnections,
       sharedBoundary,
       availableRegions:
-        busSpec.termination?.type === "plane" ? undefined : availableRegions,
+        busSpec.termination?.type === "plane" || busSpec.exitEdge
+          ? undefined
+          : availableRegions,
     })
+    if (
+      busSpec.termination?.type !== "plane" &&
+      busSpec.exitEdge &&
+      resolvedExit.preferredExit &&
+      availableRegions
+    ) {
+      validateExplicitExitAvailability({
+        busId: busSpec.busId,
+        exitEdge: busSpec.exitEdge,
+        preferredExit: resolvedExit.preferredExit,
+        availableRegions,
+      })
+    }
     buses.push({
       busId: busSpec.busId,
       direction: resolvedExit.direction,
       preferredExit: resolvedExit.preferredExit,
+      ...(busSpec.exitEdge ? { exitEdge: busSpec.exitEdge } : {}),
+      cornerBandConnectionCount: 0,
       allowedLayers: busSpec.allowedLayers,
       termination: busSpec.termination ?? { type: "boundary" },
       connections: preparedConnections,
@@ -1059,5 +1262,23 @@ export function prepareFanoutBuses(
     })
   }
 
+  const cornerBandConnectionCounts = new Map<string, number>()
+  for (const bus of buses) {
+    const side = getCornerBandSide(bus.exitEdge, bus.preferredExit)
+    if (!bus.exitEdge || !side) continue
+    const key = `${bus.exitEdge}:${side}`
+    cornerBandConnectionCounts.set(
+      key,
+      (cornerBandConnectionCounts.get(key) ?? 0) + bus.connections.length,
+    )
+  }
+  for (const bus of buses) {
+    const side = getCornerBandSide(bus.exitEdge, bus.preferredExit)
+    if (!bus.exitEdge || !side) continue
+    bus.cornerBandConnectionCount =
+      cornerBandConnectionCounts.get(`${bus.exitEdge}:${side}`) ??
+      bus.connections.length
+  }
+
   return buses
 }

package/lib/route-bus.ts

@@ -3,6 +3,12 @@ import type {
   SimpleRouteJson,
   SimplifiedPcbTrace,
 } from "@tscircuit/capacity-autorouter"
+import {
+  getCornerBandSide,
+  getDirectionForExitEdge,
+  getExitEdgeForDirection,
+} from "./boundary-exit"
+import { createFanoutOutputIds } from "./fanout-output-ids"
 import {
   distance,
   distancePointToObstacle,
@@ -10,7 +16,6 @@ import {
   distanceSegmentToObstacle,
   segmentsAreClear,
 } from "./geometry"
-import { createFanoutOutputIds } from "./fanout-output-ids"
 import { getAllRoutedTraceCopper } from "./get-routed-trace-copper"
 import { getLayerSpan } from "./layer-names"
 import {
@@ -72,6 +77,92 @@ function getPerpendicularAxis(
   return isHorizontal(direction) ? point.y : point.x
 }
 
+function getCornerSide(bus: PreparedBus): "minimum" | "maximum" | undefined {
+  return getCornerBandSide(bus.exitEdge, bus.preferredExit)
+}
+
+function getLocalCornerSide(
+  bus: PreparedBus,
+): "minimum" | "maximum" | undefined {
+  return getCornerBandSide(
+    getExitEdgeForDirection(bus.direction),
+    bus.preferredExit,
+  )
+}
+
+function getCornerTargetTrack(params: {
+  bus: PreparedBus
+  connection: PreparedConnection
+  cornerExitLaneOffset: number
+  traceWidth: number
+  viaDiameter: number
+  clearance: number
+}): number {
+  const {
+    bus,
+    connection,
+    cornerExitLaneOffset,
+    traceWidth,
+    viaDiameter,
+    clearance,
+  } = params
+  const side = getCornerSide(bus)
+  if (!side || !bus.exitEdge) {
+    return getPerpendicularAxis(
+      connection.exitTargetPoint ?? connection.targetPoint,
+      bus.direction,
+    )
+  }
+  const boundaryDirection = getDirectionForExitEdge(bus.exitEdge)
+  const boundaryMinimum = isHorizontal(boundaryDirection)
+    ? bus.sharedBoundary.minY
+    : bus.sharedBoundary.minX
+  const boundaryMaximum = isHorizontal(boundaryDirection)
+    ? bus.sharedBoundary.maxY
+    : bus.sharedBoundary.maxX
+  const pitch = Math.max(traceWidth + clearance, viaDiameter + clearance)
+  const bandCenter =
+    boundaryMinimum +
+    (boundaryMaximum - boundaryMinimum) * (side === "minimum" ? 0.25 : 0.75)
+  const bandConnectionCount = Math.max(
+    bus.connections.length,
+    bus.cornerBandConnectionCount ?? bus.connections.length,
+  )
+  const firstTrack = bandCenter - ((bandConnectionCount - 1) * pitch) / 2
+  const rank = getConnectionRank(bus, connection)
+  const globalSlot = cornerExitLaneOffset + rank
+  const reverseSlotOrder =
+    (side === "maximum") === directionSign(boundaryDirection) > 0
+  const orientedSlot = reverseSlotOrder
+    ? bandConnectionCount - 1 - globalSlot
+    : globalSlot
+  return firstTrack + orientedSlot * pitch
+}
+
+function getCornerLaneOffsets(
+  bus: PreparedBus,
+  acceptedPlans: readonly FanoutRoutePlan[],
+): { exit: number; localChannel: number; boundaryChannel: number } {
+  const side = getCornerSide(bus)
+  if (!side || !bus.exitEdge) {
+    return { exit: 0, localChannel: 0, boundaryChannel: 0 }
+  }
+  const cornerPlans = acceptedPlans.filter(
+    (plan) => plan.exitEdge && plan.cornerBandSide !== undefined,
+  )
+  const plansOnExitEdge = cornerPlans.filter(
+    (plan) => plan.exitEdge === bus.exitEdge && plan.cornerBandSide === side,
+  )
+  const plansOnLocalEdge = cornerPlans.filter(
+    (plan) => plan.direction === bus.direction,
+  )
+  return {
+    exit: plansOnExitEdge.length,
+    localChannel: plansOnLocalEdge.length,
+    boundaryChannel: plansOnExitEdge.length,
+  }
+}
+
 function makePoint(
   axis: number,
   perpendicularAxis: number,
@@ -82,8 +173,11 @@ function makePoint(
     : { x: perpendicularAxis, y: axis }
 }
 
-function getExitAxis(bus: PreparedBus): number {
-  switch (bus.direction) {
+function getExitAxis(
+  bus: PreparedBus,
+  direction: FanoutDirection = bus.direction,
+): number {
+  switch (direction) {
     case "right":
       return bus.sharedBoundary.maxX
     case "left":
@@ -296,10 +390,12 @@ function getPreferredTrack(params: {
   connection: PreparedConnection
   traceWidth: number
 }): number {
-  const preferredTrack = getPerpendicularAxis(
-    params.connection.exitTargetPoint ?? params.connection.targetPoint,
-    params.bus.direction,
-  )
+  const preferredTrack = getCornerSide(params.bus)
+    ? getPerpendicularAxis(params.connection.sourcePoint, params.bus.direction)
+    : getPerpendicularAxis(
+        params.connection.exitTargetPoint ?? params.connection.targetPoint,
+        params.bus.direction,
+      )
   const boundaryMinimum = isHorizontal(params.bus.direction)
     ? params.bus.sharedBoundary.minY
     : params.bus.sharedBoundary.minX
@@ -494,6 +590,9 @@ function buildPlan(params: {
   viaHandedness: ViaHandedness
   interstitialEscape: boolean
   spreadLaneIndex: number
+  cornerExitLaneOffset: number
+  cornerLocalChannelLaneOffset: number
+  cornerBoundaryChannelLaneOffset: number
   clearance: number
   terminateAtVia: boolean
 }): FanoutRoutePlan {
@@ -510,6 +609,9 @@ function buildPlan(params: {
     viaHandedness,
     interstitialEscape,
     spreadLaneIndex,
+    cornerExitLaneOffset,
+    cornerLocalChannelLaneOffset,
+    cornerBoundaryChannelLaneOffset,
     clearance,
     terminateAtVia,
   } = params
@@ -567,9 +669,70 @@ function buildPlan(params: {
     ? getAxis(spreadPoint, bus.direction)
     : viaAxis + sign * Math.abs(track - viaPerpendicularAxis)
   const doglegPoint = makePoint(targetLayerDoglegAxis, track, bus.direction)
+  const cornerSide = getCornerSide(bus)
+  const boundaryDirection = bus.exitEdge
+    ? getDirectionForExitEdge(bus.exitEdge)
+    : bus.direction
+  const boundarySign = directionSign(boundaryDirection)
+  const boundaryExitAxis = getExitAxis(bus, boundaryDirection)
+  const cornerTrack =
+    cornerSide && bus.exitEdge
+      ? getCornerTargetTrack({
+          bus,
+          connection: preparedConnection,
+          cornerExitLaneOffset,
+          traceWidth,
+          viaDiameter,
+          clearance,
+        })
+      : track
+  const connectionRank = getConnectionRank(bus, preparedConnection)
+  const localCornerSide = getLocalCornerSide(bus)
+  const localChannelLaneIndex =
+    localCornerSide === "maximum"
+      ? cornerLocalChannelLaneOffset + connectionRank
+      : cornerLocalChannelLaneOffset +
+        bus.connections.length -
+        1 -
+        connectionRank
+  const globalBoundarySlot = cornerBoundaryChannelLaneOffset + connectionRank
+  const boundaryBandConnectionCount = Math.max(
+    bus.connections.length,
+    bus.cornerBandConnectionCount ?? bus.connections.length,
+  )
+  const boundaryChannelLaneIndex =
+    boundarySign > 0
+      ? globalBoundarySlot
+      : boundaryBandConnectionCount - 1 - globalBoundarySlot
+  const channelInset = (laneIndex: number) =>
+    viaDiameter / 2 +
+    traceWidth / 2 +
+    clearance +
+    laneIndex * (traceWidth + clearance)
+  const localChannelAxis =
+    getExitAxis(bus, bus.direction) - sign * channelInset(localChannelLaneIndex)
+  const boundaryChannelAxis =
+    boundaryExitAxis - boundarySign * channelInset(boundaryChannelLaneIndex)
+  const localChannelSourcePoint = makePoint(
+    localChannelAxis,
+    track,
+    bus.direction,
+  )
+  const localChannelTargetPoint = makePoint(
+    boundaryChannelAxis,
+    localChannelAxis,
+    boundaryDirection,
+  )
+  const boundaryChannelTargetPoint = makePoint(
+    boundaryChannelAxis,
+    cornerTrack,
+    boundaryDirection,
+  )
   const exitPoint = terminateAtVia
     ? viaPoint
-    : makePoint(exitAxis, track, bus.direction)
+    : cornerSide
+      ? makePoint(boundaryExitAxis, cornerTrack, boundaryDirection)
+      : makePoint(exitAxis, track, bus.direction)
   const segments: RoutedSegment[] = []
   const route: SimplifiedPcbTrace["route"] = []
 
@@ -631,12 +794,27 @@ function buildPlan(params: {
 
   const targetLayerPoints = terminateAtVia
     ? [viaPoint]
-    : useNestedSpread
+    : cornerSide
       ? chamferOrthogonalPolyline(
-          [viaPoint, spreadPoint, doglegPoint, exitPoint],
+          [
+            viaPoint,
+            ...(useNestedSpread ? [spreadPoint] : []),
+            doglegPoint,
+            localChannelSourcePoint,
+            ...(isHorizontal(bus.direction) !== isHorizontal(boundaryDirection)
+              ? [localChannelTargetPoint]
+              : []),
+            boundaryChannelTargetPoint,
+            exitPoint,
+          ],
           Math.max(traceWidth + clearance, traceWidth * 2),
         )
-      : [viaPoint, doglegPoint, exitPoint]
+      : useNestedSpread
+        ? chamferOrthogonalPolyline(
+            [viaPoint, spreadPoint, doglegPoint, exitPoint],
+            Math.max(traceWidth + clearance, traceWidth * 2),
+          )
+        : [viaPoint, doglegPoint, exitPoint]
   for (let index = 1; index < targetLayerPoints.length; index++) {
     const previousPoint = targetLayerPoints[index - 1]!
     const nextPoint = targetLayerPoints[index]!
@@ -666,6 +844,8 @@ function buildPlan(params: {
     targetLayer,
     termination: bus.termination,
     direction: bus.direction,
+    ...(bus.exitEdge ? { exitEdge: bus.exitEdge } : {}),
+    ...(cornerSide ? { cornerBandSide: cornerSide } : {}),
     exitPoint,
     trace: {
       type: "pcb_trace",
@@ -1314,6 +1494,9 @@ function routePlaneTerminatedBus(
             viaHandedness,
             interstitialEscape: !pairChannelFitsVia,
             spreadLaneIndex: 0,
+            cornerExitLaneOffset: 0,
+            cornerLocalChannelLaneOffset: 0,
+            cornerBoundaryChannelLaneOffset: 0,
             clearance,
             terminateAtVia: true,
           })
@@ -1415,6 +1598,7 @@ export function routeBusAlternatives(
 
   const alternatives: FanoutRoutePlan[][] = []
   const seenAlternativeKeys = new Set<string>()
+  const cornerLaneOffsets = getCornerLaneOffsets(bus, acceptedPlans)
 
   const addAlternative = (plans: FanoutRoutePlan[]): void => {
     const key = plans
@@ -1501,6 +1685,9 @@ export function routeBusAlternatives(
           connectionRank,
           bus.connections.length - connectionRank - 1,
         ),
+        cornerExitLaneOffset: cornerLaneOffsets.exit,
+        cornerLocalChannelLaneOffset: cornerLaneOffsets.localChannel,
+        cornerBoundaryChannelLaneOffset: cornerLaneOffsets.boundaryChannel,
         clearance,
         terminateAtVia: false,
       })
@@ -1510,7 +1697,7 @@ export function routeBusAlternatives(
           otherPlans: [...acceptedPlans, ...candidatePlans],
           staticClearanceCache,
           blockingBusCounts,
-          cacheKey: `boundary:${bus.busId}:${targetLayer}:${preparedConnection.connectionIndex}:${viaHandedness}:${trackIndex}`,
+          cacheKey: `boundary:${bus.busId}:${targetLayer}:${preparedConnection.connectionIndex}:${viaHandedness}:${trackIndex}:${bus.exitEdge ?? "legacy"}:${cornerLaneOffsets.exit}:${cornerLaneOffsets.localChannel}:${cornerLaneOffsets.boundaryChannel}`,
           srj,
           sharedBoundary: bus.sharedBoundary,
           clearance,

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

@@ -3,13 +3,13 @@ import type {
   SimpleRouteJson,
   SimplifiedPcbTrace,
 } from "@tscircuit/capacity-autorouter"
+import { createFanoutOutputIds } from "./fanout-output-ids"
 import {
   distance,
   distancePointToObstacle,
   distanceSegmentToObstacle,
   distanceSegmentToSegment,
 } from "./geometry"
-import { createFanoutOutputIds } from "./fanout-output-ids"
 import { type AvailableBoundaryRegion, getRegionAnchor } from "./prepare-buses"
 import type {
   FanoutDirection,
@@ -729,7 +729,6 @@ function routeDirectionGroup(params: {
   if (achievedFlow !== terminals.length) {
     if (FANOUT_FLOW_DEBUG_ENABLED) {
       const unmatchedConnections = terminals.flatMap((terminal, index) => {
-        const terminalNode = terminalStart + index
         return terminalWasMatched(index)
           ? []
           : [terminal.item.connection.connection.name]
@@ -832,6 +831,7 @@ function buildPlan(route: FlowRoute, traceWidth: number): FanoutRoutePlan {
     targetLayer: "top",
     termination: item.bus.termination,
     direction: item.bus.direction,
+    ...(item.bus.exitEdge ? { exitEdge: item.bus.exitEdge } : {}),
     exitPoint: points.at(-1)!,
     trace: {
       type: "pcb_trace",

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

@@ -3,12 +3,12 @@ import type {
   SimpleRouteJson,
   SimplifiedPcbTrace,
 } from "@tscircuit/capacity-autorouter"
+import { createFanoutOutputIds } from "./fanout-output-ids"
 import {
   distance,
   distanceSegmentToObstacle,
   distanceSegmentToSegment,
 } from "./geometry"
-import { createFanoutOutputIds } from "./fanout-output-ids"
 import type {
   FanoutBorderDistribution,
   FanoutCorner,
@@ -768,6 +768,7 @@ function buildPlan(path: RoutedPath): FanoutRoutePlan {
     targetLayer: "top",
     termination: item.bus.termination,
     direction: item.direction,
+    ...(item.bus.exitEdge ? { exitEdge: item.bus.exitEdge } : {}),
     exitPoint: points.at(-1)!,
     trace: {
       type: "pcb_trace",

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[]
   /**
@@ -246,6 +286,10 @@ 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[]
   termination: FanoutBusTermination
@@ -287,7 +331,12 @@ 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[]

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,
@@ -73,6 +75,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 +261,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,

package/package.json

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