@tscircuit/capacity-autorouter 0.0.223 → 0.0.225

package/dist/index.d.ts

@@ -88,6 +88,21 @@ interface SimplifiedPcbTrace {
         y: number;
         to_layer: string;
         from_layer: string;
+    } | {
+        route_type: "jumper";
+        /** Starting point of the jumper pad */
+        start: {
+            x: number;
+            y: number;
+        };
+        /** Ending point of the jumper pad */
+        end: {
+            x: number;
+            y: number;
+        };
+        /** Footprint size, typically "0805" */
+        footprint: "0805" | "0603" | "1206";
+        layer: string;
     }>;
 }
 type SimplifiedPcbTraces = Array<SimplifiedPcbTrace>;
@@ -234,11 +249,49 @@ type HighDensityIntraNodeRoute$1 = {
     }>;
 };
 type HighDensityRoute$1 = HighDensityIntraNodeRoute$1;
+/**
+ * A jumper component used to allow traces to cross on single-layer PCBs.
+ * Uses a 0805 footprint (2.0mm x 1.25mm / 0.08" x 0.05").
+ */
+type Jumper = {
+    route_type: "jumper";
+    /** Starting point of the jumper */
+    start: {
+        x: number;
+        y: number;
+    };
+    /** Ending point of the jumper */
+    end: {
+        x: number;
+        y: number;
+    };
+    /** Footprint size, typically "0805" */
+    footprint: "0805" | "0603" | "1206";
+};
+/**
+ * An intra-node route that uses jumpers instead of vias for single-layer PCBs.
+ */
+type HighDensityIntraNodeRouteWithJumpers = {
+    connectionName: string;
+    rootConnectionName?: string;
+    traceThickness: number;
+    route: Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>;
+    jumpers: Jumper[];
+};
 
 interface HighDensityHyperParameters {
     FUTURE_CONNECTION_PROX_TRACE_PENALTY_FACTOR: number;
     FUTURE_CONNECTION_PROX_VIA_PENALTY_FACTOR: number;
     FUTURE_CONNECTION_PROXIMITY_VD: number;
+    /**
+     * Alternative to FUTURE_CONNECTION_PROXIMITY_VD that accepts mm
+     * Used by high density w/ jumpers solver
+     * */
+    FUTURE_CONNECTION_TRACE_PROXIMITY: number;
     MISALIGNED_DIST_PENALTY_FACTOR: number;
     VIA_PENALTY_FACTOR_2: number;
     SHUFFLE_SEED: number;
@@ -249,6 +302,18 @@ interface HighDensityHyperParameters {
     BOUNDARY_PADDING: number;
     ITERATION_PENALTY: number;
     MINIMUM_FINAL_ACCEPTANCE_GAP?: number;
+    OBSTACLE_PROX_PENALTY_FACTOR?: number;
+    OBSTACLE_PROX_SIGMA?: number;
+    EDGE_PROX_PENALTY_FACTOR?: number;
+    EDGE_PROX_SIGMA?: number;
+    ALLOW_DIAGONAL?: boolean;
+    FUTURE_CONNECTION_JUMPER_PAD_PROXIMITY?: number;
+    FUTURE_CONNECTION_JUMPER_PAD_PENALTY?: number;
+    JUMPER_JUMPER_PAD_PROXIMITY?: number;
+    JUMPER_JUMPER_PAD_PENALTY?: number;
+    FUTURE_CONNECTION_LINE_PROXIMITY?: number;
+    FUTURE_CONNECTION_LINE_PENALTY?: number;
+    MIN_TRAVEL_BEFORE_JUMPER?: number;
 }
 
 type Node = {
@@ -278,9 +343,13 @@ declare class SingleRouteCandidatePriorityQueue<T extends Node = Node> {
     enqueue(item: T): void;
     heapifyUp(): void;
     heapifyDown(): void;
+    /**
+     * Returns the top N candidates sorted by f value (lowest first)
+     */
+    getTopN(n: number): T[];
 }
 
-type FutureConnection = {
+type FutureConnection$1 = {
     connectionName: string;
     points: {
         x: number;
@@ -329,7 +398,7 @@ declare class SingleHighDensityRouteSolver extends BaseSolver {
     candidates: SingleRouteCandidatePriorityQueue;
     connectionName: string;
     solvedPath: HighDensityIntraNodeRoute$1 | null;
-    futureConnections: FutureConnection[];
+    futureConnections: FutureConnection$1[];
     hyperParameters: Partial<HighDensityHyperParameters>;
     connMap?: ConnectivityMap;
     /** For debugging/animating the exploration */
@@ -365,7 +434,7 @@ declare class SingleHighDensityRouteSolver extends BaseSolver {
         traceThickness?: number;
         obstacleMargin?: number;
         layerCount?: number;
-        futureConnections?: FutureConnection[];
+        futureConnections?: FutureConnection$1[];
         hyperParameters?: Partial<HighDensityHyperParameters>;
         connMap?: ConnectivityMap;
     });
@@ -2830,6 +2899,480 @@ declare class SimpleHighDensitySolver extends BaseSolver {
     visualize(): GraphicsObject;
 }
 
+type FutureConnection = {
+    connectionName: string;
+    points: {
+        x: number;
+        y: number;
+        z: number;
+    }[];
+};
+/**
+ * Components that make up the g (cost so far) calculation
+ */
+type GComponents = {
+    /** Total path distance traveled from start */
+    distFromStart: number;
+    /** Cumulative weighted penalty for being near obstacles */
+    weightedMmNearObstacle: number;
+    /** Cumulative weighted penalty for being near edges */
+    weightedMmNearEdge: number;
+    /** Cumulative weighted penalty for being near future connection start/end points */
+    weightedMmNearFutureConnectionStartEnd: number;
+    /** Cumulative weighted penalty for being near future connection lines */
+    weightedMmNearFutureConnectionLine: number;
+    /** Cumulative jumper penalty (includes jumper distance + penalty factor) */
+    jumperPenalty: number;
+    /** Cumulative penalty for jumper pads near future connections */
+    jumperPadFutureConnectionPenalty: number;
+    /** Total g value (sum of all components) */
+    total: number;
+};
+/**
+ * Components that make up the h (heuristic) calculation
+ */
+type HComponents = {
+    distanceToGoal: number;
+    obstacleProximity: number;
+    edgeProximity: number;
+    futureConnectionStartEndProximityPenalty: number;
+    futureConnectionLine: number;
+    total: number;
+    /** Stored rates (penalty per mm) for derivative computation */
+    obstacleProximityRate: number;
+    edgeProximityRate: number;
+    futureConnectionStartEndProximityRate: number;
+    futureConnectionLineRate: number;
+};
+/**
+ * Extended node type that tracks jumper usage
+ */
+type JumperNode = Node & {
+    /** If this node was reached via a jumper, this contains jumper info */
+    jumperEntry?: {
+        x: number;
+        y: number;
+    };
+    /** Track if this movement is the exit of a jumper */
+    isJumperExit?: boolean;
+    /** Count of jumpers used to reach this node */
+    jumperCount?: number;
+    /** Stored g components for debugging/visualization */
+    gComponents?: GComponents;
+    /** Stored h components for debugging/visualization */
+    hComponents?: HComponents;
+};
+declare class SingleHighDensityRouteWithJumpersSolver extends BaseSolver {
+    obstacleRoutes: HighDensityIntraNodeRouteWithJumpers[];
+    bounds: {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
+    boundsSize: {
+        width: number;
+        height: number;
+    };
+    boundsCenter: {
+        x: number;
+        y: number;
+    };
+    A: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    B: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    roundedGoalPosition: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    straightLineDistance: number;
+    traceThickness: number;
+    obstacleMargin: number;
+    minCellSize: number;
+    cellStep: number;
+    GREEDY_MULTIPLER: number;
+    numRoutes: number;
+    /** Penalty factor for using a jumper (relative to distance) */
+    JUMPER_PENALTY_FACTOR: number;
+    /** Future connection proximity parameters */
+    FUTURE_CONNECTION_START_END_PENALTY: number;
+    FUTURE_CONNECTION_START_END_PROXIMITY: number;
+    /** Future connection jumper pad penalty parameters */
+    FUTURE_CONNECTION_JUMPER_PAD_PROXIMITY: number;
+    FUTURE_CONNECTION_JUMPER_PAD_PENALTY: number;
+    /** Jumper-to-jumper pad proximity penalty parameters */
+    JUMPER_JUMPER_PAD_PROXIMITY: number;
+    JUMPER_JUMPER_PAD_PENALTY: number;
+    /** Future connection line proximity penalty parameters */
+    FUTURE_CONNECTION_LINE_PROXIMITY: number;
+    FUTURE_CONNECTION_LINE_PENALTY: number;
+    /** Obstacle proximity penalty parameters (repulsive field) */
+    OBSTACLE_PROX_PENALTY_FACTOR: number;
+    OBSTACLE_PROX_SIGMA: number;
+    /** Edge proximity penalty parameters */
+    EDGE_PROX_PENALTY_FACTOR: number;
+    EDGE_PROX_SIGMA: number;
+    /** Whether to allow diagonal movement in pathfinding */
+    ALLOW_DIAGONAL: boolean;
+    /** Minimum distance traveled before allowing jumper neighbors */
+    MIN_TRAVEL_BEFORE_JUMPER: number;
+    CELL_SIZE_FACTOR: number;
+    exploredNodes: Set<string>;
+    candidates: SingleRouteCandidatePriorityQueue<JumperNode>;
+    connectionName: string;
+    rootConnectionName?: string;
+    solvedPath: HighDensityIntraNodeRouteWithJumpers | null;
+    futureConnections: FutureConnection[];
+    hyperParameters: Partial<HighDensityHyperParameters>;
+    connMap?: ConnectivityMap;
+    /** For debugging/animating the exploration */
+    debug_exploredNodesOrdered: string[];
+    debug_exploredNodeValues: Map<string, {
+        g: number;
+        h: number;
+        f: number;
+        gComponents?: GComponents;
+        hComponents?: HComponents;
+    }>;
+    debug_nodesTooCloseToObstacle: Set<string>;
+    debug_nodePathToParentIntersectsObstacle: Set<string>;
+    debugEnabled: boolean;
+    initialNodeGridOffset: {
+        x: number;
+        y: number;
+    };
+    /** Existing jumpers that act as obstacles */
+    existingJumpers: Jumper[];
+    constructor(opts: {
+        connectionName: string;
+        rootConnectionName?: string;
+        obstacleRoutes: HighDensityIntraNodeRouteWithJumpers[];
+        minDistBetweenEnteringPoints: number;
+        bounds: {
+            minX: number;
+            maxX: number;
+            minY: number;
+            maxY: number;
+        };
+        A: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        B: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        traceThickness?: number;
+        obstacleMargin?: number;
+        futureConnections?: FutureConnection[];
+        hyperParameters?: Partial<HighDensityHyperParameters>;
+        connMap?: ConnectivityMap;
+    });
+    handleSimpleCases(): void;
+    get jumperPenaltyDistance(): number;
+    /**
+     * Check if a node is too close to an obstacle trace or jumper
+     */
+    isNodeTooCloseToObstacle(node: JumperNode, margin?: number): boolean;
+    /**
+     * Check if a node is too close to a jumper's pads
+     * Traces CAN route under the body of the jumper, just not under the pads
+     */
+    isNodeTooCloseToJumper(node: {
+        x: number;
+        y: number;
+    }, jumper: Jumper, margin: number): boolean;
+    isNodeTooCloseToEdge(node: JumperNode): boolean;
+    doesPathToParentIntersectObstacle(node: JumperNode): boolean;
+    /**
+     * Check if a line segment intersects with a jumper's pads
+     * Segments CAN pass under the jumper body, just not through the pads
+     */
+    doesSegmentIntersectJumperPads(p1: {
+        x: number;
+        y: number;
+    }, p2: {
+        x: number;
+        y: number;
+    }, jumper: Jumper): boolean;
+    /**
+     * Check if a line segment intersects with an axis-aligned rectangle
+     */
+    doesSegmentIntersectRect(p1: {
+        x: number;
+        y: number;
+    }, p2: {
+        x: number;
+        y: number;
+    }, center: {
+        x: number;
+        y: number;
+    }, halfWidth: number, halfHeight: number): boolean;
+    /**
+     * Find obstacles between current node and a target position
+     * Returns the obstacle segment(s) that block the direct path
+     */
+    findObstaclesBetween(from: {
+        x: number;
+        y: number;
+    }, to: {
+        x: number;
+        y: number;
+    }): Array<{
+        A: {
+            x: number;
+            y: number;
+        };
+        B: {
+            x: number;
+            y: number;
+        };
+    }>;
+    computeHComponents(node: JumperNode): HComponents;
+    computeH(node: JumperNode): number;
+    computeGComponents(node: JumperNode): GComponents;
+    computeG(node: JumperNode): number;
+    computeF(g: number, h: number): number;
+    getClosestFutureConnectionPoint(node: JumperNode): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    getFutureConnectionStartEndPenalty(node: JumperNode): number;
+    /**
+     * Calculate penalty for being close to future connection line segments.
+     * This penalty is computed by summing the segment-to-point distance between
+     * the node and all unrouted future connection start-to-end segments.
+     * The penalty helps routes avoid crossing directly over future connection paths.
+     */
+    getFutureConnectionLinePenalty(node: JumperNode): number;
+    /**
+     * Calculate penalty for jumper pads placed near future connection start/end points.
+     * This disincentivizes placing jumper pads in areas that will be needed for future routing.
+     * The distance is calculated as the minimum distance from either jumper pad to any future connection point.
+     */
+    getJumperPadFutureConnectionPenalty(node: JumperNode): number;
+    /**
+     * Compute the minimum distance from a node to any obstacle (trace segments and jumper pads)
+     */
+    getClearanceToObstacles(node: {
+        x: number;
+        y: number;
+    }): number;
+    /**
+     * Compute distance from a point to the nearest jumper pad
+     */
+    distanceToJumperPads(p: {
+        x: number;
+        y: number;
+    }, j: Jumper): number;
+    /**
+     * Compute distance from a point to an axis-aligned rectangle (0 if inside)
+     */
+    pointToRectDistance(p: {
+        x: number;
+        y: number;
+    }, c: {
+        x: number;
+        y: number;
+    }, halfW: number, halfH: number): number;
+    /**
+     * Compute minimum distance from a node to the nearest boundary edge
+     */
+    getClearanceToEdge(node: {
+        x: number;
+        y: number;
+    }): number;
+    /**
+     * Compute the obstacle proximity penalty (repulsive field)
+     * Returns a high value near obstacles, ~0 far away
+     */
+    getObstacleProximityPenalty(node: JumperNode): number;
+    /**
+     * Compute the edge proximity penalty (repulsive field near boundaries)
+     * Returns a high value near edges, ~0 far away
+     * Penalty is reduced as we approach the goal (which is always on an edge)
+     */
+    getEdgeProximityPenalty(node: JumperNode): number;
+    getNodeKey(node: JumperNode): string;
+    /**
+     * Calculate potential jumper positions to cross an obstacle
+     */
+    getJumperNeighbors(node: JumperNode): JumperNode[];
+    /**
+     * Calculate the exit position for a jumper that clears an obstacle
+     */
+    calculateJumperExit(entry: JumperNode, obstacle: {
+        A: {
+            x: number;
+            y: number;
+        };
+        B: {
+            x: number;
+            y: number;
+        };
+    }, direction: {
+        dx: number;
+        dy: number;
+    }): JumperNode | null;
+    /**
+     * Check if a jumper's pads are too close to obstacle traces
+     */
+    isJumperTooCloseToTraces(entry: {
+        x: number;
+        y: number;
+    }, exit: {
+        x: number;
+        y: number;
+    }): boolean;
+    /**
+     * Verify that a jumper placement is valid (doesn't overlap with existing jumpers or traces)
+     */
+    isJumperPlacementValid(entry: JumperNode, exit: JumperNode): boolean;
+    /**
+     * Check if two jumpers overlap
+     */
+    doJumpersOverlap(j1: Jumper, j2: Jumper): boolean;
+    /**
+     * Get all jumpers in the path to a node
+     */
+    getJumpersInPath(node: JumperNode): Jumper[];
+    getNeighbors(node: JumperNode): JumperNode[];
+    getNodePath(node: JumperNode): JumperNode[];
+    setSolvedPath(node: JumperNode): void;
+    computeProgress(currentNode: JumperNode, goalDist: number): number;
+    _step(): void;
+    /**
+     * Draw the two pads of an 0805 jumper
+     * Pad dimensions are rotated based on jumper orientation
+     */
+    private drawJumperPads;
+    visualize(): GraphicsObject;
+}
+
+/**
+ * IntraNodeSolverWithJumpers is designed for single-layer nodes that use
+ * 0805 jumpers to allow traces to jump over each other.
+ *
+ * Unlike the standard IntraNodeRouteSolver which uses vias to change layers,
+ * this solver operates on a single layer and uses physical jumper components
+ * to handle trace crossings.
+ */
+declare class IntraNodeSolverWithJumpers extends BaseSolver {
+    nodeWithPortPoints: NodeWithPortPoints;
+    colorMap: Record<string, string>;
+    unsolvedConnections: {
+        connectionName: string;
+        rootConnectionName?: string;
+        points: {
+            x: number;
+            y: number;
+            z: number;
+        }[];
+    }[];
+    totalConnections: number;
+    solvedRoutes: HighDensityIntraNodeRouteWithJumpers[];
+    failedSubSolvers: SingleHighDensityRouteWithJumpersSolver[];
+    hyperParameters: Partial<HighDensityHyperParameters>;
+    minDistBetweenEnteringPoints: number;
+    traceWidth: number;
+    activeSubSolver: SingleHighDensityRouteWithJumpersSolver | null;
+    lastActiveSubSolver: SingleHighDensityRouteWithJumpersSolver | null;
+    connMap?: ConnectivityMap;
+    get failedSolvers(): SingleHighDensityRouteWithJumpersSolver[];
+    get activeSolver(): SingleHighDensityRouteWithJumpersSolver | null;
+    constructor(params: {
+        nodeWithPortPoints: NodeWithPortPoints;
+        colorMap?: Record<string, string>;
+        hyperParameters?: Partial<HighDensityHyperParameters>;
+        connMap?: ConnectivityMap;
+        traceWidth?: number;
+    });
+    getConstructorParams(): {
+        nodeWithPortPoints: NodeWithPortPoints;
+        colorMap: Record<string, string>;
+        hyperParameters: Partial<HighDensityHyperParameters>;
+        connMap: ConnectivityMap | undefined;
+        traceWidth: number;
+    };
+    computeProgress(): number;
+    _step(): void;
+    /**
+     * Draw the two pads of an 0805 jumper
+     * Pad dimensions are rotated based on jumper orientation
+     */
+    private drawJumperPads;
+    visualize(): GraphicsObject;
+}
+
+interface NodeAnalysis {
+    node: NodeWithPortPoints;
+    hasCrossings: boolean;
+    numSameLayerCrossings: number;
+    isSingleLayer: boolean;
+}
+/**
+ * HighDensitySolver intelligently selects the appropriate solver for each node:
+ * - SimpleHighDensitySolver for nodes without crossings (faster, force-directed)
+ * - IntraNodeSolverWithJumpers for single-layer nodes with crossings (uses 0805 jumpers)
+ *
+ * This solver processes nodes in batches based on their characteristics.
+ */
+declare class JumperHighDensitySolver extends BaseSolver {
+    allNodes: NodeWithPortPoints[];
+    nodeAnalyses: NodeAnalysis[];
+    routes: (HighDensityIntraNodeRoute$1 & {
+        jumpers?: HighDensityIntraNodeRouteWithJumpers["jumpers"];
+    })[];
+    colorMap: Record<string, string>;
+    traceWidth: number;
+    viaDiameter: number;
+    connMap?: ConnectivityMap;
+    hyperParameters?: Partial<HighDensityHyperParameters>;
+    nodesWithoutCrossings: NodeWithPortPoints[];
+    nodesWithCrossings: NodeWithPortPoints[];
+    simpleHighDensitySolver?: SimpleHighDensitySolver;
+    jumperSolvers: IntraNodeSolverWithJumpers[];
+    currentJumperSolverIndex: number;
+    phase: "analyzing" | "simple" | "jumpers" | "done";
+    constructor({ nodePortPoints, colorMap, traceWidth, viaDiameter, connMap, hyperParameters, }: {
+        nodePortPoints: NodeWithPortPoints[];
+        colorMap?: Record<string, string>;
+        traceWidth?: number;
+        viaDiameter?: number;
+        connMap?: ConnectivityMap;
+        hyperParameters?: Partial<HighDensityHyperParameters>;
+    });
+    /**
+     * Analyze all nodes to determine which solver to use for each
+     */
+    _analyzeNodes(): void;
+    _step(): void;
+    _stepSimpleSolver(): void;
+    _initializeJumperSolvers(): void;
+    _stepJumperSolvers(): void;
+    computeProgress(): number;
+    getConstructorParams(): {
+        nodePortPoints: NodeWithPortPoints[];
+        colorMap: Record<string, string>;
+        traceWidth: number;
+        viaDiameter: number;
+        connMap: ConnectivityMap | undefined;
+        hyperParameters: Partial<HighDensityHyperParameters> | undefined;
+    };
+    visualize(): GraphicsObject;
+}
+
 /**
  * ObstacleTree wraps different spatial index implementations:
  * - 'native': original spatial-hash grid
@@ -3229,7 +3772,9 @@ declare class AssignableAutoroutingPipeline2 extends BaseSolver {
     relateNodesToOffBoardConnections?: RelateNodesToOffBoardConnectionsSolver;
     colorMap: Record<string, string>;
     highDensityRouteSolver?: HighDensitySolver;
+    /** @deprecated Use highDensitySolver instead */
     simpleHighDensityRouteSolver?: SimpleHighDensitySolver;
+    highDensitySolver?: JumperHighDensitySolver;
     highDensityStitchSolver?: MultipleHighDensityRouteStitchSolver;
     singleLayerNodeMerger?: SingleLayerNodeMergerSolver;
     offboardPathFragmentSolver?: PortPointOffboardPathFragmentSolver;
@@ -4033,4 +4578,4 @@ declare const convertSrjToGraphicsObject: (srj: SimpleRouteJson) => {
     points: Point$5[];
 };
 
-export { AssignableAutoroutingPipeline1Solver, AssignableAutoroutingPipeline2, AutoroutingPipeline1_OriginalUnravel, AutoroutingPipelineSolver2_PortPointPathing as AutoroutingPipelineSolver, type AutoroutingPipelineSolverOptions, type CachableSolver, type CacheProvider, CapacityMeshSolver, InMemoryCache, LocalStorageCache, calculateOptimalCapacityDepth, convertSrjToGraphicsObject, getGlobalInMemoryCache, getGlobalLocalStorageCache, getTunedTotalCapacity1, setupGlobalCaches };
+export { AssignableAutoroutingPipeline1Solver, AssignableAutoroutingPipeline2, AutoroutingPipeline1_OriginalUnravel, AutoroutingPipelineSolver2_PortPointPathing as AutoroutingPipelineSolver, type AutoroutingPipelineSolverOptions, type CachableSolver, type CacheProvider, CapacityMeshSolver, type HighDensityIntraNodeRouteWithJumpers, JumperHighDensitySolver as HighDensitySolver, InMemoryCache, IntraNodeSolverWithJumpers, type Jumper, LocalStorageCache, SingleHighDensityRouteWithJumpersSolver, calculateOptimalCapacityDepth, convertSrjToGraphicsObject, getGlobalInMemoryCache, getGlobalLocalStorageCache, getTunedTotalCapacity1, setupGlobalCaches };