@tscircuit/fanout-solver 0.0.35 → 0.0.37

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/build-output.ts

@@ -5,10 +5,9 @@ import type { FanoutRoutePlan, SimpleRouteJsonWithFanoutPlanes } from "./types"
 function createViaObstacle(
   plan: FanoutRoutePlan,
   layerNames: string[],
-  endpoint = false,
+  via: NonNullable<FanoutRoutePlan["via"]>,
+  viaIndex: number | "endpoint",
 ): Obstacle | null {
-  const via = endpoint ? plan.planeEndpointVia : plan.via
-  if (!via) return null
   const zLayers = via.spanLayers.map((layer) => {
     const layerIndex = layerNames.indexOf(layer)
     if (layerIndex < 0) {
@@ -20,9 +19,12 @@ function createViaObstacle(
   })
   const outputIds = createFanoutOutputIds(plan)
   return {
-    obstacleId: endpoint
-      ? outputIds.planeEndpointViaObstacleId
-      : outputIds.viaObstacleId,
+    obstacleId:
+      viaIndex === "endpoint"
+        ? outputIds.planeEndpointViaObstacleId
+        : viaIndex === 0
+          ? outputIds.viaObstacleId
+          : `${outputIds.viaObstacleId}:${viaIndex}`,
     type: "rect",
     center: via.center,
     width: via.diameter,
@@ -67,10 +69,30 @@ export function buildOutputSimpleRouteJson(params: {
     if (plan.termination.type === "plane") {
       planeTerminatedConnectionNames.add(plan.connectionName)
     }
-    const viaObstacle = createViaObstacle(plan, layerNames)
-    if (viaObstacle) viaObstacles.push(viaObstacle)
-    const endpointViaObstacle = createViaObstacle(plan, layerNames, true)
-    if (endpointViaObstacle) viaObstacles.push(endpointViaObstacle)
+    if (plan.via) {
+      const viaObstacle = createViaObstacle(plan, layerNames, plan.via, 0)
+      if (viaObstacle) viaObstacles.push(viaObstacle)
+    }
+    for (const [additionalViaIndex, via] of (
+      plan.additionalVias ?? []
+    ).entries()) {
+      const viaObstacle = createViaObstacle(
+        plan,
+        layerNames,
+        via,
+        additionalViaIndex + 1,
+      )
+      if (viaObstacle) viaObstacles.push(viaObstacle)
+    }
+    if (plan.planeEndpointVia) {
+      const endpointViaObstacle = createViaObstacle(
+        plan,
+        layerNames,
+        plan.planeEndpointVia,
+        "endpoint",
+      )
+      if (endpointViaObstacle) viaObstacles.push(endpointViaObstacle)
+    }
   }
   const planTraces = plans.flatMap((plan) => [
     plan.trace,

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
+}