@tscircuit/fanout-solver 0.0.28 → 0.0.30

package/README.md

@@ -83,10 +83,11 @@ and treats each bus-layer decision atomically.
 - `completeOriginalEndpoints` adds a bounded fail-first completion stage after
   fanout. It first places DRC-gated interstitial capacitor escapes, then tries
   breakout-to-pad routes with layer transitions at interior points along the
-  existing fanout copper, and finally a bounded capacity-router fallback. Vias
-  at original or moved routing endpoints are rejected. A candidate is retained
-  only when it improves independently proven original endpoint connectivity
-  and the complete emitted copper remains DRC-clean.
+  existing fanout copper, and finally calls the optional
+  `routeDownstreamConnections` host callback. Vias at original or moved routing
+  endpoints are rejected. A candidate is retained only when it improves
+  independently proven original endpoint connectivity and the complete emitted
+  copper remains DRC-clean.
 - Emits supplied fanout traces, via obstacles, and moved breakout endpoints in a
   new `SimpleRouteJson`. The returned problem is ready for a downstream
   autorouter to finish.
@@ -102,7 +103,10 @@ bun add https://github.com/tscircuit/fanout-solver
 ## Usage
 
 ```ts
-import { CapacityMeshSolver } from "@tscircuit/capacity-autorouter"
+import {
+  AutoroutingPipelineSolver6,
+  CapacityMeshSolver,
+} from "@tscircuit/capacity-autorouter"
 import { FanoutSolver } from "@tscircuit/fanout-solver"
 
 const fanoutSolver = new FanoutSolver(simpleRouteJson, {
@@ -125,6 +129,17 @@ const fanoutSolver = new FanoutSolver(simpleRouteJson, {
   availableCornersAndSides: ["top_left", "top", "top_right"],
   borderDistribution: "even",
   compactBusTracks: true,
+  completeOriginalEndpoints: true,
+  routeDownstreamConnections: (inputSrj, { effort }) => {
+    const downstreamSolver = new AutoroutingPipelineSolver6(inputSrj, {
+      effort,
+    })
+    downstreamSolver.solve()
+    if (!downstreamSolver.solved) {
+      throw new Error(downstreamSolver.error ?? "Downstream routing failed")
+    }
+    return downstreamSolver.getOutputSimpleRouteJson().traces ?? []
+  },
   buses: [
     {
       busId: "ground",
@@ -146,6 +161,11 @@ const autorouter = new CapacityMeshSolver(
 autorouter.solve()
 ```
 
+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
+solver's connectivity and copper-clearance checks pass.
+
 The canonical bus input is the current `SimpleRouteJson` bus structure:
 
 ```ts

package/lib/complete-original-endpoints.ts

@@ -1,9 +1,8 @@
-import {
-  AutoroutingPipelineSolver6,
-  type ConnectionPoint,
-  type Obstacle,
-  type SimpleRouteJson,
-  type SimplifiedPcbTrace,
+import type {
+  ConnectionPoint,
+  Obstacle,
+  SimpleRouteJson,
+  SimplifiedPcbTrace,
 } from "@tscircuit/capacity-autorouter"
 import { createFanoutCompletionTraceId } from "./fanout-output-ids"
 import {
@@ -15,6 +14,7 @@ import { getCopperLayerNames, getLayerSpan } from "./layer-names"
 import { obstacleSharesElectricalNet } from "./net-identity"
 import type {
   FanoutEndpointCompletionReport,
+  FanoutDownstreamRouter,
   FanoutRoutePlan,
   Point2D,
 } from "./types"
@@ -921,8 +921,9 @@ function findDownstreamTerminalBranch(params: {
 
 /**
  * Connects short opposite-layer terminal pairs with constrained interstitial
- * vias, then delegates the remaining long routes to the capacity autorouter.
- * Only metric-improving, independently DRC-clean physical copper is retained.
+ * vias, then delegates remaining long routes to an optional host-provided
+ * router. Only metric-improving, independently DRC-clean physical copper is
+ * retained.
  */
 export function completeOriginalEndpoints(params: {
   inputSrj: SimpleRouteJson
@@ -933,6 +934,7 @@ export function completeOriginalEndpoints(params: {
   viaHoleDiameter: number
   clearance: number
   effort?: number
+  routeDownstreamConnections?: FanoutDownstreamRouter
 }): CompleteOriginalEndpointsResult {
   const {
     inputSrj,
@@ -943,6 +945,7 @@ export function completeOriginalEndpoints(params: {
     viaHoleDiameter,
     clearance,
     effort = 1,
+    routeDownstreamConnections,
   } = params
   const errors: string[] = []
   const baselineDrc = validateRoutedCopperDrc({
@@ -1072,7 +1075,8 @@ export function completeOriginalEndpoints(params: {
   if (
     baselineDrc.valid &&
     downstreamConnections.length > 0 &&
-    downstreamConnections.length <= 12
+    downstreamConnections.length <= 12 &&
+    routeDownstreamConnections
   ) {
     const downstreamConnectionNames = new Set(
       downstreamConnections.map((connection) => connection.name),
@@ -1095,36 +1099,32 @@ export function completeOriginalEndpoints(params: {
       traces: [],
     }
     try {
-      const downstreamSolver = new AutoroutingPipelineSolver6(downstreamInput, {
-        effort,
+      const candidates = routeDownstreamConnections(downstreamInput, { effort })
+      downstreamTraces = acceptDownstreamTraces({
+        inputSrj,
+        fanoutSrj,
+        localTraces: [...bestLocalAttempt.traces, ...directDownstreamTraces],
+        candidates: candidates.filter((trace) =>
+          downstreamConnectionNames.has(trace.connection_name),
+        ),
+        clearance,
       })
-      downstreamSolver.solve()
-      if (downstreamSolver.solved) {
-        downstreamTraces = acceptDownstreamTraces({
-          inputSrj,
-          fanoutSrj,
-          localTraces: [...bestLocalAttempt.traces, ...directDownstreamTraces],
-          candidates:
-            downstreamSolver
-              .getOutputSimpleRouteJson()
-              .traces?.filter((trace) =>
-                downstreamConnectionNames.has(trace.connection_name),
-              ) ?? [],
-          clearance,
-        })
-      } else {
-        errors.push(
-          `Downstream autorouter did not solve: ${downstreamSolver.error ?? "unknown error"}`,
-        )
-      }
     } catch (error) {
       errors.push(
-        `Downstream autorouter failed: ${error instanceof Error ? error.message : String(error)}`,
+        `Downstream router failed: ${error instanceof Error ? error.message : String(error)}`,
       )
     }
+  } else if (!baselineDrc.valid && downstreamConnections.length > 0) {
+    errors.push(
+      "Skipped downstream router because the endpoint-completion baseline failed emitted-copper DRC",
+    )
   } else if (downstreamConnections.length > 12) {
     errors.push(
-      `Skipped downstream autorouter for ${downstreamConnections.length} unresolved connections (bounded at 12)`,
+      `Skipped downstream router for ${downstreamConnections.length} unresolved connections (bounded at 12)`,
+    )
+  } else if (downstreamConnections.length > 0 && !routeDownstreamConnections) {
+    errors.push(
+      `Skipped downstream router for ${downstreamConnections.length} unresolved connections because no routeDownstreamConnections callback was provided`,
     )
   }
 

package/lib/fanout-solver.ts

@@ -1,7 +1,4 @@
-import {
-  convertSrjToGraphicsObject,
-  type SimpleRouteJson,
-} from "@tscircuit/capacity-autorouter"
+import type { SimpleRouteJson } from "@tscircuit/capacity-autorouter"
 import { BaseSolver } from "@tscircuit/solver-utils"
 import type { GraphicsObject } from "graphics-debug"
 import { buildOutputSimpleRouteJson } from "./build-output"
@@ -9,7 +6,6 @@ import {
   completeOriginalEndpoints,
   type CompleteOriginalEndpointsResult,
 } from "./complete-original-endpoints"
-import { getCopperLayerColor } from "./layer-colors"
 import { generateLayerAssignments, getCopperLayerNames } from "./layer-names"
 import {
   prepareFanoutBuses,
@@ -23,6 +19,7 @@ import {
 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,
@@ -262,7 +259,7 @@ function getBusDepthInRows(bus: PreparedBus): number {
   )
 }
 
-function createPreferredLayerAssignment(params: {
+function createInitialLayerAssignment(params: {
   buses: PreparedBus[]
   escapeLayers: string[]
   escapeLayersByBusId: Readonly<Record<string, readonly string[]>>
@@ -317,16 +314,16 @@ function createPreferredLayerAssignment(params: {
 }
 
 function prioritizeLayerAssignment(params: {
-  preferredAssignment: Readonly<Record<string, string>>
+  initialAssignment: Readonly<Record<string, string>>
   generatedAssignments: Array<Readonly<Record<string, string>>>
   maxAssignments: number
 }): Array<Readonly<Record<string, string>>> {
-  const { preferredAssignment, generatedAssignments, maxAssignments } = params
-  const preferredKey = JSON.stringify(preferredAssignment)
+  const { initialAssignment, generatedAssignments, maxAssignments } = params
+  const initialKey = JSON.stringify(initialAssignment)
   return [
-    preferredAssignment,
+    initialAssignment,
     ...generatedAssignments.filter(
-      (assignment) => JSON.stringify(assignment) !== preferredKey,
+      (assignment) => JSON.stringify(assignment) !== initialKey,
     ),
   ].slice(0, maxAssignments)
 }
@@ -338,7 +335,12 @@ function getCandidateEscapeLayersForBus(params: {
   staticClearanceCache: RouteBusStaticClearanceCache
 }): string[] {
   const { bus, srj, config, staticClearanceCache } = params
-  const individuallyRoutableLayers = config.escapeLayers.filter(
+  const busAllowedLayers = bus.allowedLayers
+  const allowedEscapeLayers =
+    busAllowedLayers === undefined
+      ? config.escapeLayers
+      : config.escapeLayers.filter((layer) => busAllowedLayers.includes(layer))
+  const individuallyRoutableLayers = allowedEscapeLayers.filter(
     (targetLayer) =>
       routeBus({
         srj,
@@ -360,9 +362,11 @@ function getCandidateEscapeLayersForBus(params: {
   // route this bus by itself cannot become viable later in an assignment.
   // Preserve the original candidates when none route so impossible problems
   // still produce the usual failed-solver result instead of throwing here.
-  return individuallyRoutableLayers.length > 0
-    ? individuallyRoutableLayers
-    : config.escapeLayers
+  const candidateLayers =
+    individuallyRoutableLayers.length > 0
+      ? individuallyRoutableLayers
+      : allowedEscapeLayers
+  return candidateLayers
 }
 
 export class FanoutSolver extends BaseSolver {
@@ -403,6 +407,24 @@ export class FanoutSolver extends BaseSolver {
     this.config = resolveConfig(inputSrj, options)
     this.preparedBuses = prepareFanoutBuses(inputSrj, options)
     for (const bus of this.preparedBuses) {
+      for (const allowedLayer of bus.allowedLayers ?? []) {
+        if (!this.config.layerNames.includes(allowedLayer)) {
+          throw new Error(
+            `FanoutSolver: bus "${bus.busId}" allows unavailable layer "${allowedLayer}"`,
+          )
+        }
+      }
+      if (
+        bus.termination.type === "boundary" &&
+        bus.allowedLayers !== undefined &&
+        !bus.allowedLayers.some((layer) =>
+          this.config.escapeLayers.includes(layer),
+        )
+      ) {
+        throw new Error(
+          `FanoutSolver: bus "${bus.busId}" has no allowed layer in escapeLayers`,
+        )
+      }
       if (bus.termination.type !== "plane") continue
       const planeLayer = bus.termination.layer
       if (!this.config.layerNames.includes(planeLayer)) {
@@ -410,6 +432,14 @@ export class FanoutSolver extends BaseSolver {
           `FanoutSolver: plane-terminated bus "${bus.busId}" targets unavailable layer "${planeLayer}"`,
         )
       }
+      if (
+        bus.allowedLayers !== undefined &&
+        !bus.allowedLayers.includes(planeLayer)
+      ) {
+        throw new Error(
+          `FanoutSolver: plane-terminated bus "${bus.busId}" targets disallowed layer "${planeLayer}"`,
+        )
+      }
       if (
         bus.connections.some(
           (connection) => connection.sourceLayer === planeLayer,
@@ -457,7 +487,7 @@ export class FanoutSolver extends BaseSolver {
       ...fixedPlaneAssignments,
     }))
     this.layerAssignments = prioritizeLayerAssignment({
-      preferredAssignment: createPreferredLayerAssignment({
+      initialAssignment: createInitialLayerAssignment({
         buses: this.preparedBuses,
         escapeLayers: this.config.escapeLayers,
         escapeLayersByBusId,
@@ -489,6 +519,7 @@ export class FanoutSolver extends BaseSolver {
       viaHoleDiameter: this.config.viaHoleDiameter,
       clearance: this.config.clearance,
       effort: this.options.endpointCompletionEffort,
+      routeDownstreamConnections: this.options.routeDownstreamConnections,
     })
   }
 
@@ -1254,46 +1285,6 @@ export class FanoutSolver extends BaseSolver {
       this.endpointCompletion?.simpleRouteJson ??
       this.bestAttempt?.outputSrj ??
       this.inputSrj
-    const graphics = convertSrjToGraphicsObject(visualizedSrj)
-    const circularPadKeys = new Set(
-      visualizedSrj.obstacles
-        .filter(
-          (obstacle) =>
-            (obstacle as typeof obstacle & { shape?: string }).shape ===
-            "circle",
-        )
-        .map(
-          (obstacle) =>
-            `${obstacle.center.x}:${obstacle.center.y}:${obstacle.width}:${obstacle.height}`,
-        ),
-    )
-    const circularPadGraphics: NonNullable<GraphicsObject["circles"]> = []
-    const rects = graphics.rects?.filter((rect) => {
-      const key = `${rect.center.x}:${rect.center.y}:${rect.width}:${rect.height}`
-      if (!circularPadKeys.has(key)) return true
-      circularPadGraphics.push({
-        center: rect.center,
-        radius: Math.min(rect.width, rect.height) / 2,
-        fill: rect.fill,
-        stroke: rect.stroke,
-        layer: rect.layer,
-        label: rect.label,
-      })
-      return false
-    })
-    return {
-      ...graphics,
-      rects,
-      circles: [...(graphics.circles ?? []), ...circularPadGraphics],
-      lines: graphics.lines?.map((line) => {
-        const layerMatch = /^z(\d+)$/.exec(line.layer ?? "")
-        if (!layerMatch) return line
-        const { strokeDash: _strokeDash, ...solidLine } = line
-        return {
-          ...solidLine,
-          strokeColor: getCopperLayerColor(Number(layerMatch[1])),
-        }
-      }),
-    }
+    return visualizeSimpleRouteJson(visualizedSrj)
   }
 }

package/lib/index.ts

@@ -26,6 +26,8 @@ export type {
   FanoutBusTermination,
   FanoutCorner,
   FanoutDirection,
+  FanoutDownstreamRouter,
+  FanoutDownstreamRouterOptions,
   FanoutEdge,
   FanoutEndpointCompletionReport,
   FanoutPlaneConnectivity,

package/lib/prepare-buses.ts

@@ -407,6 +407,26 @@ function resolvePreferredExit(
   return value
 }
 
+function resolveAllowedLayers(
+  busId: string,
+  allowedLayers: readonly string[] | undefined,
+): string[] | undefined {
+  if (allowedLayers === undefined) return undefined
+  if (allowedLayers.length === 0) {
+    throw new Error(
+      `FanoutSolver: bus "${busId}" must allow at least one layer`,
+    )
+  }
+  for (const layer of allowedLayers) {
+    if (typeof layer !== "string" || layer.length === 0) {
+      throw new Error(
+        `FanoutSolver: bus "${busId}" has an invalid allowed layer`,
+      )
+    }
+  }
+  return [...new Set(allowedLayers)]
+}
+
 export function resolveAvailableBoundaryRegions(
   value: readonly FanoutAvailableCornerAndSideInput[] | undefined,
 ): AvailableBoundaryRegion[] | undefined {
@@ -491,6 +511,10 @@ function resolveBusSpecs(
         (requestedBus as FanoutBusSpec).preferredExit ??
         options.defaultPreferredExit,
     )
+    const allowedLayers = resolveAllowedLayers(
+      requestedBus.busId,
+      (requestedBus as FanoutBusSpec).allowedLayers,
+    )
     if (termination.type === "plane" && preferredExit !== undefined) {
       throw new Error(
         `FanoutSolver: plane-terminated bus "${requestedBus.busId}" cannot also specify preferredExit`,
@@ -506,6 +530,7 @@ function resolveBusSpecs(
         (requestedBus as FanoutBusSpec).direction ??
         options.defaultDirection,
       preferredExit,
+      ...(allowedLayers === undefined ? {} : { allowedLayers }),
       termination,
     })
   }
@@ -1020,6 +1045,7 @@ export function prepareFanoutBuses(
       busId: busSpec.busId,
       direction: resolvedExit.direction,
       preferredExit: resolvedExit.preferredExit,
+      allowedLayers: busSpec.allowedLayers,
       termination: busSpec.termination ?? { type: "boundary" },
       connections: preparedConnections,
       componentId: sourceGrid.componentId,

package/lib/types.ts

@@ -49,6 +49,19 @@ export type FanoutAvailableCornerAndSideInput =
 
 export type FanoutBorderDistribution = "preserve" | "even"
 
+export interface FanoutDownstreamRouterOptions {
+  effort: number
+}
+
+/**
+ * Optional host-provided router for unresolved connections after the fanout
+ * solver's local endpoint-completion passes.
+ */
+export type FanoutDownstreamRouter = (
+  inputSrj: SimpleRouteJson,
+  options: FanoutDownstreamRouterOptions,
+) => SimplifiedPcbTrace[]
+
 export type FanoutBusTermination =
   | {
       type: "boundary"
@@ -63,6 +76,8 @@ export interface FanoutBusSpec extends SimpleRouteBus {
   sourceComponentId?: string
   direction?: FanoutDirection
   preferredExit?: FanoutBorderTarget
+  /** Layers to which this bus is allowed to escape. */
+  allowedLayers?: readonly string[]
   /**
    * Preferred downstream routing point for each connection after it leaves the
    * fanout boundary. This is routing guidance only and does not replace the
@@ -127,8 +142,13 @@ export interface FanoutSolverOptions {
    * with the independent endpoint-connectivity and emitted-copper validators.
    */
   completeOriginalEndpoints?: boolean
-  /** Effort passed to the bounded downstream capacity-router pass. */
+  /** Effort passed to the optional bounded downstream-router pass. */
   endpointCompletionEffort?: number
+  /**
+   * Host-provided fallback for unresolved endpoint connections. The fanout
+   * package deliberately does not import a board-level autorouter at runtime.
+   */
+  routeDownstreamConnections?: FanoutDownstreamRouter
 }
 
 export interface FanoutAttemptSummary {
@@ -226,6 +246,8 @@ export interface PreparedBus {
   busId: string
   direction: FanoutDirection
   preferredExit?: FanoutBorderTarget
+  /** Layers to which this bus is allowed to escape. */
+  allowedLayers?: readonly string[]
   termination: FanoutBusTermination
   connections: PreparedConnection[]
   componentId: string

package/lib/visualize-simple-route-json.ts

@@ -0,0 +1,453 @@
+import type {
+  ConnectionPoint,
+  Obstacle,
+  SimpleRouteJson,
+} from "@tscircuit/capacity-autorouter"
+import type { Circle, GraphicsObject, Line, Point, Rect } from "graphics-debug"
+import { getCopperLayerColor } from "./layer-colors"
+import { getCopperLayerNames } from "./layer-names"
+
+const LEGACY_VISUALIZATION_LAYERS = new Set([
+  "top",
+  "bottom",
+  "inner1",
+  "inner2",
+  "inner3",
+  "inner4",
+  "inner5",
+  "inner6",
+  "inner7",
+  "inner8",
+])
+
+const JUMPER_DIMENSIONS = {
+  "0603": { padLength: 0.8, padWidth: 0.95 },
+  "1206": { padLength: 0.6, padWidth: 1.6 },
+  "1206x4_pair": { padLength: 0.8, padWidth: 0.5 },
+} as const
+
+const getLayerIndex = (layerNames: string[], layerName: string): number => {
+  const layerIndex = layerNames.indexOf(layerName)
+  if (layerIndex < 0) {
+    throw new Error(
+      `FanoutSolver: cannot visualize unknown copper layer "${layerName}"`,
+    )
+  }
+  return layerIndex
+}
+
+const getGraphicsLayer = (
+  layerNames: string[],
+  copperLayers: readonly string[],
+): string => {
+  const zLayers = [
+    ...new Set(
+      copperLayers.map((layerName) => getLayerIndex(layerNames, layerName)),
+    ),
+  ].sort((first, second) => first - second)
+  return `z${zLayers.join(",")}`
+}
+
+const getPointLayers = (point: ConnectionPoint): string[] => {
+  const layers = "layers" in point ? point.layers : undefined
+  if (layers && layers.length > 0) return layers
+  return [(point as ConnectionPoint & { layer: string }).layer]
+}
+
+const getObstacleLayerIndexes = (
+  obstacle: Obstacle,
+  layerNames: string[],
+): number[] => {
+  if (obstacle.__zLayers && obstacle.__zLayers.length > 0) {
+    return [...new Set(obstacle.__zLayers)]
+      .filter(
+        (layerIndex) =>
+          Number.isInteger(layerIndex) &&
+          layerIndex >= 0 &&
+          layerIndex < layerNames.length,
+      )
+      .sort((first, second) => first - second)
+  }
+  return [
+    ...new Set(
+      obstacle.layers.map((layerName) => getLayerIndex(layerNames, layerName)),
+    ),
+  ].sort((first, second) => first - second)
+}
+
+const getViaLayerNames = (
+  layerNames: string[],
+  fromLayer: string,
+  toLayer: string,
+): string[] => {
+  const fromIndex = getLayerIndex(layerNames, fromLayer)
+  const toIndex = getLayerIndex(layerNames, toLayer)
+  return layerNames.slice(
+    Math.min(fromIndex, toIndex),
+    Math.max(fromIndex, toIndex) + 1,
+  )
+}
+
+const firstFiniteNumber = (
+  ...values: Array<number | undefined>
+): number | undefined =>
+  values.find((value) => typeof value === "number" && Number.isFinite(value))
+
+const getViaPadDiameter = (srj: SimpleRouteJson): number => {
+  const holeDiameter = firstFiniteNumber(
+    srj.min_via_hole_diameter,
+    srj.minViaHoleDiameter,
+  )
+  const padDiameter = firstFiniteNumber(
+    srj.min_via_pad_diameter,
+    srj.minViaPadDiameter,
+    srj.minViaDiameter,
+  )
+  return Math.max(padDiameter ?? srj.minViaDiameter ?? 0.3, holeDiameter ?? 0)
+}
+
+const getColorMap = (
+  connections: SimpleRouteJson["connections"],
+): Record<string, string> =>
+  Object.fromEntries(
+    connections.map((connection, index) => [
+      connection.name,
+      `hsl(${(index * 340) / connections.length}, 100%, 50%)`,
+    ]),
+  )
+
+const hslToRgb = (hue: number, saturation: number, lightness: number) => {
+  const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation
+  const hueSegment = (((hue % 360) + 360) % 360) / 60
+  const secondary = chroma * (1 - Math.abs((hueSegment % 2) - 1))
+  const [red, green, blue] =
+    hueSegment < 1
+      ? [chroma, secondary, 0]
+      : hueSegment < 2
+        ? [secondary, chroma, 0]
+        : hueSegment < 3
+          ? [0, chroma, secondary]
+          : hueSegment < 4
+            ? [0, secondary, chroma]
+            : hueSegment < 5
+              ? [secondary, 0, chroma]
+              : [chroma, 0, secondary]
+  const match = lightness - chroma / 2
+  return [red, green, blue].map((channel) =>
+    Math.round((channel + match) * 255),
+  )
+}
+
+const transparentize = (color: string, amount: number): string => {
+  const namedColors: Record<string, [number, number, number]> = {
+    blue: [0, 0, 255],
+    orange: [255, 165, 0],
+    purple: [128, 0, 128],
+    red: [255, 0, 0],
+  }
+  let channels = namedColors[color]
+  let alpha = 1
+  const rgbaMatch =
+    /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)(?:\s*,\s*([\d.]+))?\s*\)$/.exec(
+      color,
+    )
+  if (rgbaMatch) {
+    channels = [
+      Number(rgbaMatch[1]),
+      Number(rgbaMatch[2]),
+      Number(rgbaMatch[3]),
+    ]
+    alpha = rgbaMatch[4] === undefined ? 1 : Number(rgbaMatch[4])
+  }
+  const hslMatch =
+    /^hsl\(\s*([\d.-]+)\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*\)$/.exec(color)
+  if (hslMatch) {
+    channels = hslToRgb(
+      Number(hslMatch[1]),
+      Number(hslMatch[2]) / 100,
+      Number(hslMatch[3]) / 100,
+    ) as [number, number, number]
+  }
+  if (!channels) return color
+  const outputAlpha = +Math.max(0, alpha * 100 - amount * 100).toFixed(2) / 100
+  if (outputAlpha >= 1) {
+    const hex = channels
+      .map((channel) => Math.round(channel).toString(16).padStart(2, "0"))
+      .join("")
+    return hex[0] === hex[1] && hex[2] === hex[3] && hex[4] === hex[5]
+      ? `#${hex[0]}${hex[2]}${hex[4]}`
+      : `#${hex}`
+  }
+  return `rgba(${channels.join(",")},${outputAlpha})`
+}
+
+const getUniqueValues = (values: readonly string[]): string[] => {
+  const seen = new Set<string>()
+  return values.filter((value) => {
+    if (seen.has(value)) return false
+    seen.add(value)
+    return true
+  })
+}
+
+const createObstacleLabelFormatter = (srj: SimpleRouteJson) => {
+  const rootConnectionIndex = new Map<string, string[]>()
+  const addMapping = (identifier: string | undefined, rootName: string) => {
+    if (!identifier) return
+    const names = rootConnectionIndex.get(identifier) ?? []
+    if (!names.includes(rootName)) names.push(rootName)
+    rootConnectionIndex.set(identifier, names)
+  }
+  for (const connection of srj.connections) {
+    const rootNames = connection.__rootConnectionNames ?? [connection.name]
+    for (const rootName of rootNames) {
+      addMapping(connection.name, rootName)
+      addMapping(rootName, rootName)
+      addMapping(connection.__netConnectionName, rootName)
+      for (const point of connection.pointsToConnect) {
+        addMapping(point.pointId, rootName)
+        addMapping(point.pcb_port_id, rootName)
+      }
+    }
+  }
+  return (obstacle: Obstacle): string => {
+    const rootNames = getUniqueValues([
+      ...obstacle.connectedTo.flatMap(
+        (identifier) => rootConnectionIndex.get(identifier) ?? [],
+      ),
+      ...(obstacle.offBoardConnectsTo ?? []).flatMap(
+        (identifier) => rootConnectionIndex.get(identifier) ?? [],
+      ),
+    ])
+    const rootLabel = rootNames.join(", ")
+    return obstacle.layers
+      .map((layerName) =>
+        rootLabel ? `${layerName}\n${rootLabel}` : layerName,
+      )
+      .join("\n")
+  }
+}
+
+export function visualizeSimpleRouteJson(srj: SimpleRouteJson): GraphicsObject {
+  const layerNames = getCopperLayerNames(srj.layerCount)
+  const hasArbitraryCopperLayer = (srj.traces ?? []).some((trace) =>
+    trace.route.some((routePoint, routePointIndex) => {
+      const nextRoutePoint = trace.route[routePointIndex + 1]
+      return (
+        routePoint.route_type === "wire" &&
+        nextRoutePoint?.route_type === "wire" &&
+        nextRoutePoint.layer === routePoint.layer &&
+        !LEGACY_VISUALIZATION_LAYERS.has(routePoint.layer)
+      )
+    }),
+  )
+  const connectionNames = new Set(srj.connections.map(({ name }) => name))
+  const traceOnlyConnections: SimpleRouteJson["connections"] =
+    hasArbitraryCopperLayer
+      ? [
+          ...new Set(
+            (srj.traces ?? [])
+              .map(({ connection_name }) => connection_name)
+              .filter(
+                (connectionName) =>
+                  connectionName && !connectionNames.has(connectionName),
+              ),
+          ),
+        ].map((name) => ({ name, pointsToConnect: [] }))
+      : []
+  const visualizedConnections = [...srj.connections, ...traceOnlyConnections]
+  const colorMap = getColorMap(visualizedConnections)
+  const formatObstacleLabel = createObstacleLabelFormatter({
+    ...srj,
+    connections: visualizedConnections,
+  })
+  const lines: Line[] = []
+  const circles: Circle[] = []
+  const rects: Rect[] = []
+  const points: Point[] = []
+
+  for (const connection of visualizedConnections) {
+    for (const point of connection.pointsToConnect) {
+      const pointLayers = getPointLayers(point)
+      const rootNames = connection.__rootConnectionNames ?? [connection.name]
+      points.push({
+        x: point.x,
+        y: point.y,
+        color: colorMap[connection.name]!,
+        layer: getGraphicsLayer(layerNames, pointLayers),
+        label: [
+          connection.name,
+          rootNames.join(", "),
+          pointLayers.join(","),
+        ].join("\n"),
+      })
+    }
+  }
+
+  for (const trace of srj.traces ?? []) {
+    const jumpers = trace.route.filter(
+      (routePoint) => routePoint.route_type === "jumper",
+    )
+    const isWireSegmentInsideJumper = (
+      start: { x: number; y: number },
+      end: { x: number; y: number },
+    ): boolean =>
+      jumpers.some((jumper) => {
+        const tolerance = 0.01
+        return (
+          (Math.abs(start.x - jumper.start.x) < tolerance &&
+            Math.abs(start.y - jumper.start.y) < tolerance &&
+            Math.abs(end.x - jumper.end.x) < tolerance &&
+            Math.abs(end.y - jumper.end.y) < tolerance) ||
+          (Math.abs(start.x - jumper.end.x) < tolerance &&
+            Math.abs(start.y - jumper.end.y) < tolerance &&
+            Math.abs(end.x - jumper.start.x) < tolerance &&
+            Math.abs(end.y - jumper.start.y) < tolerance)
+        )
+      })
+
+    for (const routePoint of trace.route) {
+      if (routePoint.route_type === "via") {
+        const viaLayers = getViaLayerNames(
+          layerNames,
+          routePoint.from_layer,
+          routePoint.to_layer,
+        )
+        circles.push({
+          center: { x: routePoint.x, y: routePoint.y },
+          radius: (routePoint.via_diameter ?? getViaPadDiameter(srj)) / 2,
+          fill: hasArbitraryCopperLayer
+            ? colorMap[trace.connection_name]!
+            : "blue",
+          stroke: "none",
+          layer: getGraphicsLayer(layerNames, viaLayers),
+        })
+      } else if (routePoint.route_type === "through_obstacle") {
+        lines.push({
+          points: [routePoint.start, routePoint.end],
+          strokeColor: transparentize(
+            colorMap[trace.connection_name] ?? "purple",
+            0.35,
+          ),
+          strokeWidth: routePoint.width,
+          strokeDash: [0.1, 0.1],
+          layer: getGraphicsLayer(layerNames, [
+            routePoint.from_layer,
+            routePoint.to_layer,
+          ]),
+          label: `${trace.connection_name} through_obstacle`,
+        })
+      }
+    }
+
+    for (
+      let routePointIndex = 0;
+      routePointIndex < trace.route.length - 1;
+      routePointIndex++
+    ) {
+      const routePoint = trace.route[routePointIndex]!
+      const nextRoutePoint = trace.route[routePointIndex + 1]!
+      if (routePoint.route_type === "jumper") {
+        const color =
+          colorMap[trace.connection_name] ?? "rgba(255, 165, 0, 0.8)"
+        const dimensions =
+          JUMPER_DIMENSIONS[
+            routePoint.footprint === "1206x4_pair" ? "1206x4_pair" : "0603"
+          ]
+        const horizontal =
+          Math.abs(routePoint.end.x - routePoint.start.x) >
+          Math.abs(routePoint.end.y - routePoint.start.y)
+        const padWidth = horizontal ? dimensions.padLength : dimensions.padWidth
+        const padHeight = horizontal
+          ? dimensions.padWidth
+          : dimensions.padLength
+        const layer = getGraphicsLayer(layerNames, [routePoint.layer])
+        for (const center of [routePoint.start, routePoint.end]) {
+          rects.push({
+            center,
+            width: padWidth,
+            height: padHeight,
+            fill: transparentize(color, 0.5),
+            stroke: "rgba(0, 0, 0, 0.5)",
+            layer,
+          })
+        }
+        lines.push({
+          points: [routePoint.start, routePoint.end],
+          strokeColor: "rgba(100, 100, 100, 0.8)",
+          strokeWidth: dimensions.padWidth * 0.3,
+          layer,
+        })
+      } else if (
+        routePoint.route_type === "wire" &&
+        nextRoutePoint.route_type === "wire" &&
+        nextRoutePoint.layer === routePoint.layer &&
+        !isWireSegmentInsideJumper(routePoint, nextRoutePoint)
+      ) {
+        const layerIndex = getLayerIndex(layerNames, routePoint.layer)
+        lines.push({
+          points: [
+            { x: routePoint.x, y: routePoint.y },
+            { x: nextRoutePoint.x, y: nextRoutePoint.y },
+          ],
+          layer: `z${layerIndex}`,
+          strokeWidth: routePoint.width,
+          strokeColor: getCopperLayerColor(layerIndex),
+          ...(hasArbitraryCopperLayer ? { label: trace.connection_name } : {}),
+        })
+      }
+    }
+  }
+
+  for (const obstacle of srj.obstacles) {
+    if (obstacle.isCopperPour) continue
+    const layerIndexes = getObstacleLayerIndexes(obstacle, layerNames)
+    if (layerIndexes.length === 0) {
+      throw new Error(
+        `FanoutSolver: cannot visualize obstacle "${obstacle.obstacleId ?? "unknown"}" without a valid layer`,
+      )
+    }
+    const onlyLayerName =
+      layerIndexes.length === 1 ? layerNames[layerIndexes[0]!] : undefined
+    const fill = transparentize(
+      onlyLayerName === "bottom" ? "blue" : "red",
+      0.5 ** layerIndexes.length,
+    )
+    const shape = (obstacle as Obstacle & { shape?: string }).shape
+    const common = {
+      center: obstacle.center,
+      fill,
+      layer: `z${layerIndexes.join(",")}`,
+      label: formatObstacleLabel(obstacle),
+    }
+    if (shape === "circle") {
+      circles.push({
+        ...common,
+        radius: Math.min(obstacle.width, obstacle.height) / 2,
+      })
+    } else {
+      rects.push({
+        ...common,
+        width: obstacle.width,
+        height: obstacle.height,
+        ccwRotationDegrees: obstacle.ccwRotationDegrees,
+      })
+    }
+  }
+
+  for (const jumper of srj.jumpers ?? []) {
+    for (const pad of jumper.pads) {
+      rects.push({
+        center: pad.center,
+        width: pad.width,
+        height: pad.height,
+        ccwRotationDegrees: pad.ccwRotationDegrees,
+        fill: "rgba(255, 165, 0, 0.3)",
+        stroke: "rgba(255, 165, 0, 0.8)",
+        layer: getGraphicsLayer(layerNames, pad.layers),
+      })
+    }
+  }
+
+  return { rects, circles, lines, points }
+}

package/package.json

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