@tscircuit/jumper-topology-generator 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tscircuit Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# @tscircuit/jumper-topology-generator
+
+Generate 0603 jumper placement/topology as a HyperGraph, including:
+
+- top-layer conductive regions
+- jumper pad regions
+- connectivity ports between touching regions
+- via locations and overall bounds
+
+## Preview
+
+![Jumper topology preview](./tests/__snapshots__/0603-horizontal-3x2.snap.svg)
+
+## Install
+
+```bash
+bun add @tscircuit/jumper-topology-generator
+```
+
+## Quick Start
+
+```ts
+import { generate0603JumperHyperGraph } from "@tscircuit/jumper-topology-generator"
+
+const graph = generate0603JumperHyperGraph({
+  cols: 3,
+  rows: 2,
+  orientation: "horizontal",
+})
+
+console.log(graph.regions.length)
+console.log(graph.ports.length)
+console.log(graph.bounds)
+```
+
+## API
+
+### `generate0603JumperHyperGraph(options)`
+
+Creates a `JumperHyperGraph` from a 0603 jumper matrix.
+
+Required options:
+
+- `cols: number` - number of jumper columns (`> 0`)
+- `rows: number` - number of jumper rows (`> 0`)
+
+Optional options:
+
+- `pattern: "grid" | "staggered"` (default: `"grid"`)
+- `orientation: "horizontal" | "vertical"` (default: `"horizontal"`)
+- `pitchX: number` or `colSpacing: number` (default: `2.2`)
+- `pitchY: number` or `rowSpacing: number` (default: `1.8`)
+- `staggerAxis: "x" | "y"` (default: `"x"`)
+- `staggerOffset: number` (or alias `staggerOffsetX`)
+- `padWidth: number` (default: `0.9`)
+- `padHeight: number` (default: `1.0`)
+- `padGap: number` (default: `0.35`)
+- `viaDiameter: number` (default: `0.3`)
+- `clearance: number` (default: `0.2`)
+- `concavityTolerance: number` (default: `0.3`)
+- `boundsPadding: number` (default: `1.2`)
+- `portSpacing: number` (default: `0.25`, must be `> 0`)
+
+Behavior notes:
+
+- `colSpacing` overrides `pitchX`; `rowSpacing` overrides `pitchY`.
+- Pitch values are clamped to avoid overlap:
+  - `pitchX >= jumperBodyWidth + clearance`
+  - `pitchY >= jumperBodyHeight + clearance`
+- For `pattern: "staggered"`, if `staggerOffset` is omitted, it defaults to half the jumper size along the stagger axis.
+- Smaller `portSpacing` creates denser top-layer edge ports.
+
+## Return Shape
+
+`generate0603JumperHyperGraph` returns a `JumperHyperGraph` with:
+
+- `regions`: all regions (`topLayerRegions + jumperRegions`)
+- `ports`: all region-to-region connectivity ports
+- `jumperLocations`: jumper-centric mapping used by `@tscircuit/hypergraph`
+- `topLayerRegions`: convex top copper regions
+- `jumperRegions`: one region per jumper body
+- `jumpers`: raw jumper placements and pad centers
+- `vias`: one via per pad center
+- `bounds`: overall bounding box
+
+## Visualization Helper
+
+Use `visualizeJumperHyperGraph` to generate a `graphics-debug` object:
+
+```ts
+import {
+  generate0603JumperHyperGraph,
+  visualizeJumperHyperGraph,
+} from "@tscircuit/jumper-topology-generator"
+
+const graph = generate0603JumperHyperGraph({ cols: 2, rows: 2 })
+const debugGraphics = visualizeJumperHyperGraph(graph)
+```
+
+## Examples
+
+Staggered pattern along X:
+
+```ts
+import { generate0603JumperHyperGraph } from "@tscircuit/jumper-topology-generator"
+
+const graph = generate0603JumperHyperGraph({
+  cols: 4,
+  rows: 3,
+  pattern: "staggered",
+  staggerAxis: "x",
+  orientation: "horizontal",
+})
+```
+
+Vertical jumpers with coarser edge ports:
+
+```ts
+import { generate0603JumperHyperGraph } from "@tscircuit/jumper-topology-generator"
+
+const graph = generate0603JumperHyperGraph({
+  cols: 2,
+  rows: 2,
+  orientation: "vertical",
+  portSpacing: 0.75,
+})
+```
+
+## Output Previews
+
+Horizontal grid (`cols: 3, rows: 2, orientation: "horizontal"`):
+
+![Horizontal 3x2 output](./tests/__snapshots__/0603-horizontal-3x2.snap.svg)
+
+Vertical grid (`cols: 2, rows: 2, orientation: "vertical"`):
+
+![Vertical 2x2 output](./tests/__snapshots__/0603-vertical-2x2.snap.svg)
+
+Staggered X (`cols: 4, rows: 3, pattern: "staggered", staggerAxis: "x"`):
+
+![Staggered X 4x3 output](./tests/__snapshots__/0603-staggered-4x3.snap.svg)
+
+Staggered Y (`cols: 3, rows: 3, pattern: "staggered", staggerAxis: "y"`):
+
+![Staggered Y 3x3 output](./tests/__snapshots__/0603-staggered-y-3x3.snap.svg)
+
+SVG export fixture (`cols: 2, rows: 1`):
+
+![SVG export 2x1 output](./tests/__snapshots__/0603-svg-export-2x1.snap.svg)
+
+## Local Development
+
+Install dependencies:
+
+```bash
+bun install
+```
+
+Build:
+
+```bash
+bun run build
+```
+
+Explore fixtures in React Cosmos:
+
+```bash
+bun run start
+```

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { Point, Via, Bounds } from '@tscircuit/find-convex-regions';
+import { JumperGraph, JRegion } from '@tscircuit/hypergraph';
+import { GraphicsObject } from 'graphics-debug';
+
+type JumperOrientation = "horizontal" | "vertical";
+type JumperPatternName = "grid" | "staggered";
+type StaggerAxis = "x" | "y";
+interface Generate0603JumperHyperGraphOptions {
+    cols: number;
+    rows: number;
+    pattern?: JumperPatternName;
+    colSpacing?: number;
+    rowSpacing?: number;
+    pitchX?: number;
+    pitchY?: number;
+    staggerAxis?: StaggerAxis;
+    staggerOffset?: number;
+    staggerOffsetX?: number;
+    padWidth?: number;
+    padHeight?: number;
+    padGap?: number;
+    viaDiameter?: number;
+    clearance?: number;
+    concavityTolerance?: number;
+    boundsPadding?: number;
+    orientation?: JumperOrientation;
+    portSpacing?: number;
+}
+interface Resolved0603GridOptions {
+    cols: number;
+    rows: number;
+    pattern: JumperPatternName;
+    pitchX: number;
+    pitchY: number;
+    staggerAxis: StaggerAxis;
+    staggerOffset: number;
+    staggerOffsetX: number;
+    padWidth: number;
+    padHeight: number;
+    padGap: number;
+    viaDiameter: number;
+    clearance: number;
+    concavityTolerance: number;
+    boundsPadding: number;
+    orientation: JumperOrientation;
+    portSpacing: number;
+}
+interface JumperPlacement {
+    jumperId: string;
+    center: Point;
+    orientation: JumperOrientation;
+    padCenters: [Point, Point];
+}
+interface JumperPatternResult {
+    jumpers: JumperPlacement[];
+    vias: Via[];
+    bounds: Bounds;
+}
+interface JumperHyperGraph extends JumperGraph {
+    topLayerRegions: JRegion[];
+    jumperRegions: JRegion[];
+    jumpers: JumperPlacement[];
+    vias: Via[];
+    bounds: Bounds;
+}
+
+declare const generate0603JumperHyperGraph: (input: Generate0603JumperHyperGraphOptions) => JumperHyperGraph;
+
+declare const generate0603Pattern: (options: Resolved0603GridOptions) => JumperPatternResult;
+
+declare const resolve0603GridOptions: (input: Generate0603JumperHyperGraphOptions) => Resolved0603GridOptions;
+declare const generate0603GridPattern: (options: Resolved0603GridOptions) => JumperPatternResult;
+
+declare const generate0603StaggeredPattern: (options: Resolved0603GridOptions) => JumperPatternResult;
+
+declare const visualizeJumperHyperGraph: (graph: JumperHyperGraph) => GraphicsObject;
+
+export { type Generate0603JumperHyperGraphOptions, type JumperHyperGraph, type JumperOrientation, type JumperPatternName, type JumperPatternResult, type JumperPlacement, type Resolved0603GridOptions, type StaggerAxis, generate0603GridPattern, generate0603JumperHyperGraph, generate0603Pattern, generate0603StaggeredPattern, resolve0603GridOptions, visualizeJumperHyperGraph };

package/dist/index.js

@@ -0,0 +1,511 @@
+// lib/generate0603JumperHyperGraph.ts
+import { ConvexRegionsSolver } from "@tscircuit/find-convex-regions";
+
+// lib/patterns/grid0603.ts
+var getJumperSizeAlongAxis = (orientation, axis, padWidth, padHeight, padGap) => {
+  const horizontalSizeX = padGap + padWidth * 2;
+  const horizontalSizeY = padHeight;
+  const verticalSizeX = padHeight;
+  const verticalSizeY = padGap + padWidth * 2;
+  if (orientation === "horizontal") {
+    return axis === "x" ? horizontalSizeX : horizontalSizeY;
+  }
+  return axis === "x" ? verticalSizeX : verticalSizeY;
+};
+var getJumperBodySize = (orientation, padWidth, padHeight, padGap) => {
+  if (orientation === "horizontal") {
+    return {
+      x: padGap + padWidth * 2,
+      y: padHeight
+    };
+  }
+  return {
+    x: padHeight,
+    y: padGap + padWidth * 2
+  };
+};
+var DEFAULT_0603_GRID_OPTIONS = {
+  pattern: "grid",
+  pitchX: 2.2,
+  pitchY: 1.8,
+  staggerAxis: "x",
+  staggerOffset: 1.1,
+  staggerOffsetX: 1.1,
+  padWidth: 0.9,
+  padHeight: 1,
+  padGap: 0.35,
+  viaDiameter: 0.3,
+  clearance: 0.2,
+  concavityTolerance: 0.3,
+  boundsPadding: 1.2,
+  orientation: "horizontal",
+  portSpacing: 0.25
+};
+var resolve0603GridOptions = (input) => {
+  const resolvedOrientation = input.orientation ?? DEFAULT_0603_GRID_OPTIONS.orientation;
+  const resolvedStaggerAxis = input.staggerAxis ?? DEFAULT_0603_GRID_OPTIONS.staggerAxis;
+  const resolvedPadWidth = input.padWidth ?? DEFAULT_0603_GRID_OPTIONS.padWidth;
+  const resolvedPadHeight = input.padHeight ?? DEFAULT_0603_GRID_OPTIONS.padHeight;
+  const resolvedPadGap = input.padGap ?? DEFAULT_0603_GRID_OPTIONS.padGap;
+  const resolvedClearance = input.clearance ?? DEFAULT_0603_GRID_OPTIONS.clearance;
+  const resolvedPitchX = input.colSpacing ?? input.pitchX ?? DEFAULT_0603_GRID_OPTIONS.pitchX;
+  const resolvedPitchY = input.rowSpacing ?? input.pitchY ?? DEFAULT_0603_GRID_OPTIONS.pitchY;
+  const minBodySize = getJumperBodySize(
+    resolvedOrientation,
+    resolvedPadWidth,
+    resolvedPadHeight,
+    resolvedPadGap
+  );
+  const minInterJumperGap = resolvedClearance;
+  const resolvedDefaultStaggerOffset = getJumperSizeAlongAxis(
+    resolvedOrientation,
+    resolvedStaggerAxis,
+    resolvedPadWidth,
+    resolvedPadHeight,
+    resolvedPadGap
+  ) / 2;
+  const resolvedStaggerOffset = input.staggerOffset ?? input.staggerOffsetX ?? resolvedDefaultStaggerOffset;
+  const options = {
+    ...DEFAULT_0603_GRID_OPTIONS,
+    ...input,
+    orientation: resolvedOrientation,
+    staggerAxis: resolvedStaggerAxis,
+    pitchX: Math.max(resolvedPitchX, minBodySize.x + minInterJumperGap),
+    pitchY: Math.max(resolvedPitchY, minBodySize.y + minInterJumperGap),
+    padWidth: resolvedPadWidth,
+    padHeight: resolvedPadHeight,
+    padGap: resolvedPadGap,
+    staggerOffset: resolvedStaggerOffset,
+    staggerOffsetX: resolvedStaggerOffset,
+    concavityTolerance: input.concavityTolerance ?? DEFAULT_0603_GRID_OPTIONS.concavityTolerance,
+    clearance: resolvedClearance,
+    portSpacing: input.portSpacing ?? DEFAULT_0603_GRID_OPTIONS.portSpacing
+  };
+  if (options.cols <= 0 || options.rows <= 0) {
+    throw new Error("rows and cols must be > 0");
+  }
+  if (!Number.isFinite(options.portSpacing) || options.portSpacing <= 0) {
+    throw new Error("portSpacing must be > 0");
+  }
+  return options;
+};
+var generate0603GridPattern = (options) => {
+  const jumpers = [];
+  const vias = [];
+  const padOffset = options.padGap / 2 + options.padWidth / 2;
+  const xStart = -((options.cols - 1) * options.pitchX) / 2;
+  const yStart = -((options.rows - 1) * options.pitchY) / 2;
+  for (let row = 0; row < options.rows; row++) {
+    for (let col = 0; col < options.cols; col++) {
+      const center = {
+        x: xStart + col * options.pitchX,
+        y: yStart + row * options.pitchY
+      };
+      const pad1 = options.orientation === "horizontal" ? { x: center.x - padOffset, y: center.y } : { x: center.x, y: center.y - padOffset };
+      const pad2 = options.orientation === "horizontal" ? { x: center.x + padOffset, y: center.y } : { x: center.x, y: center.y + padOffset };
+      const jumperId = `jumper_r${row}_c${col}`;
+      jumpers.push({
+        jumperId,
+        center,
+        orientation: options.orientation,
+        padCenters: [pad1, pad2]
+      });
+      vias.push(
+        { center: pad1, diameter: options.viaDiameter },
+        { center: pad2, diameter: options.viaDiameter }
+      );
+    }
+  }
+  const bounds = {
+    minX: xStart - padOffset - options.padWidth / 2 - options.boundsPadding,
+    maxX: xStart + (options.cols - 1) * options.pitchX + padOffset + options.padWidth / 2 + options.boundsPadding,
+    minY: yStart - padOffset - options.padHeight / 2 - options.boundsPadding,
+    maxY: yStart + (options.rows - 1) * options.pitchY + padOffset + options.padHeight / 2 + options.boundsPadding
+  };
+  return { jumpers, vias, bounds };
+};
+
+// lib/patterns/staggered0603.ts
+var computeBoundsFromJumpers = (jumpers, options) => {
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  for (const jumper of jumpers) {
+    for (const pad of jumper.padCenters) {
+      const xHalf = options.orientation === "horizontal" ? options.padWidth / 2 : options.padHeight / 2;
+      const yHalf = options.orientation === "horizontal" ? options.padHeight / 2 : options.padWidth / 2;
+      if (pad.x - xHalf < minX) minX = pad.x - xHalf;
+      if (pad.y - yHalf < minY) minY = pad.y - yHalf;
+      if (pad.x + xHalf > maxX) maxX = pad.x + xHalf;
+      if (pad.y + yHalf > maxY) maxY = pad.y + yHalf;
+    }
+  }
+  return {
+    minX: minX - options.boundsPadding,
+    minY: minY - options.boundsPadding,
+    maxX: maxX + options.boundsPadding,
+    maxY: maxY + options.boundsPadding
+  };
+};
+var generate0603StaggeredPattern = (options) => {
+  const jumpers = [];
+  const vias = [];
+  const padOffset = options.padGap / 2 + options.padWidth / 2;
+  const xStart = -((options.cols - 1) * options.pitchX) / 2;
+  const yStart = -((options.rows - 1) * options.pitchY) / 2;
+  for (let row = 0; row < options.rows; row++) {
+    const rowOffset = options.staggerAxis === "x" && row % 2 === 1 ? options.staggerOffset : 0;
+    for (let col = 0; col < options.cols; col++) {
+      const colOffset = options.staggerAxis === "y" && col % 2 === 1 ? options.staggerOffset : 0;
+      const center = {
+        x: xStart + col * options.pitchX + rowOffset,
+        y: yStart + row * options.pitchY + colOffset
+      };
+      const pad1 = options.orientation === "horizontal" ? { x: center.x - padOffset, y: center.y } : { x: center.x, y: center.y - padOffset };
+      const pad2 = options.orientation === "horizontal" ? { x: center.x + padOffset, y: center.y } : { x: center.x, y: center.y + padOffset };
+      jumpers.push({
+        jumperId: `jumper_r${row}_c${col}`,
+        center,
+        orientation: options.orientation,
+        padCenters: [pad1, pad2]
+      });
+      vias.push(
+        { center: pad1, diameter: options.viaDiameter },
+        { center: pad2, diameter: options.viaDiameter }
+      );
+    }
+  }
+  return {
+    jumpers,
+    vias,
+    bounds: computeBoundsFromJumpers(jumpers, options)
+  };
+};
+
+// lib/patterns/index.ts
+var generate0603Pattern = (options) => {
+  if (options.pattern === "staggered") {
+    return generate0603StaggeredPattern(options);
+  }
+  return generate0603GridPattern(options);
+};
+
+// lib/geometry.ts
+var toBounds = (poly) => {
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  for (const p of poly) {
+    if (p.x < minX) minX = p.x;
+    if (p.y < minY) minY = p.y;
+    if (p.x > maxX) maxX = p.x;
+    if (p.y > maxY) maxY = p.y;
+  }
+  return { minX, minY, maxX, maxY };
+};
+var toCenter = (bounds) => ({
+  x: (bounds.minX + bounds.maxX) / 2,
+  y: (bounds.minY + bounds.maxY) / 2
+});
+var boundsToPolygon = (bounds) => [
+  { x: bounds.minX, y: bounds.minY },
+  { x: bounds.maxX, y: bounds.minY },
+  { x: bounds.maxX, y: bounds.maxY },
+  { x: bounds.minX, y: bounds.maxY }
+];
+var almostEqual = (a, b, tolerance) => Math.abs(a - b) <= tolerance;
+var pointsEqual = (a, b, tolerance) => almostEqual(a.x, b.x, tolerance) && almostEqual(a.y, b.y, tolerance);
+
+// lib/topology.ts
+var createTopLayerRegions = (convexRegions) => convexRegions.map((polygon, index) => {
+  const bounds = toBounds(polygon);
+  return {
+    regionId: `top_${index}`,
+    ports: [],
+    d: {
+      bounds,
+      center: toCenter(bounds),
+      polygon,
+      isPad: false
+    }
+  };
+});
+var createJumperRegions = (jumpers, options) => jumpers.map((jumper) => {
+  const [p1, p2] = jumper.padCenters;
+  const bounds = options.orientation === "horizontal" ? {
+    minX: p1.x - options.padWidth / 2,
+    maxX: p2.x + options.padWidth / 2,
+    minY: jumper.center.y - options.padHeight / 2,
+    maxY: jumper.center.y + options.padHeight / 2
+  } : {
+    minX: jumper.center.x - options.padHeight / 2,
+    maxX: jumper.center.x + options.padHeight / 2,
+    minY: p1.y - options.padWidth / 2,
+    maxY: p2.y + options.padWidth / 2
+  };
+  return {
+    regionId: jumper.jumperId,
+    ports: [],
+    d: {
+      bounds,
+      center: jumper.center,
+      polygon: boundsToPolygon(bounds),
+      isPad: true,
+      isThroughJumper: true
+    }
+  };
+});
+var createTopLayerPorts = (topLayerRegions, portSpacing, tolerance = 1e-5) => {
+  const ports = [];
+  let nextPort = 0;
+  for (let i = 0; i < topLayerRegions.length; i++) {
+    const regionA = topLayerRegions[i];
+    if (!regionA?.d.polygon) continue;
+    for (let j = i + 1; j < topLayerRegions.length; j++) {
+      const regionB = topLayerRegions[j];
+      if (!regionB?.d.polygon) continue;
+      const sharedEdges = getSharedBoundaryEdges(regionA, regionB, tolerance);
+      for (const edge of sharedEdges) {
+        const edgeLength = getSegmentLength(edge);
+        const intervalCount = Math.floor(edgeLength / portSpacing);
+        const portCount = intervalCount - 1;
+        if (portCount < 1) continue;
+        for (let k = 0; k < portCount; k++) {
+          const t = (k + 1) / (portCount + 1);
+          const point = pointAlongSegment(edge, t);
+          ports.push({
+            portId: `tp_${nextPort++}`,
+            region1: regionA,
+            region2: regionB,
+            d: {
+              x: point.x,
+              y: point.y
+            }
+          });
+        }
+      }
+    }
+  }
+  return ports;
+};
+var getSegmentLength = (segment) => {
+  const dx = segment.end.x - segment.start.x;
+  const dy = segment.end.y - segment.start.y;
+  return Math.hypot(dx, dy);
+};
+var pointAlongSegment = (segment, t) => ({
+  x: segment.start.x + (segment.end.x - segment.start.x) * t,
+  y: segment.start.y + (segment.end.y - segment.start.y) * t
+});
+var getSharedBoundaryEdges = (regionA, regionB, tolerance) => {
+  const edges = [];
+  if (!regionA.d.polygon || !regionB.d.polygon) return edges;
+  for (let ai = 0; ai < regionA.d.polygon.length; ai++) {
+    const a1 = regionA.d.polygon[ai];
+    const a2 = regionA.d.polygon[(ai + 1) % regionA.d.polygon.length];
+    if (!a1 || !a2) continue;
+    for (let bi = 0; bi < regionB.d.polygon.length; bi++) {
+      const b1 = regionB.d.polygon[bi];
+      const b2 = regionB.d.polygon[(bi + 1) % regionB.d.polygon.length];
+      if (!b1 || !b2) continue;
+      const overlap = getCollinearOverlap(
+        { start: a1, end: a2 },
+        { start: b1, end: b2 },
+        tolerance
+      );
+      if (!overlap) continue;
+      const alreadyPresent = edges.some(
+        (edge) => segmentsEqual(edge, overlap, tolerance)
+      );
+      if (!alreadyPresent) {
+        edges.push(overlap);
+      }
+    }
+  }
+  return edges;
+};
+var segmentsEqual = (a, b, tolerance) => pointsEqual(a.start, b.start, tolerance) && pointsEqual(a.end, b.end, tolerance) || pointsEqual(a.start, b.end, tolerance) && pointsEqual(a.end, b.start, tolerance);
+var getCollinearOverlap = (a, b, tolerance) => {
+  const av = {
+    x: a.end.x - a.start.x,
+    y: a.end.y - a.start.y
+  };
+  const bv = {
+    x: b.end.x - b.start.x,
+    y: b.end.y - b.start.y
+  };
+  const aLenSq = av.x ** 2 + av.y ** 2;
+  if (aLenSq <= tolerance ** 2) return null;
+  const crossAB = av.x * bv.y - av.y * bv.x;
+  if (!almostEqual(crossAB, 0, tolerance)) return null;
+  const bStartOffset = {
+    x: b.start.x - a.start.x,
+    y: b.start.y - a.start.y
+  };
+  const bEndOffset = {
+    x: b.end.x - a.start.x,
+    y: b.end.y - a.start.y
+  };
+  const crossStart = av.x * bStartOffset.y - av.y * bStartOffset.x;
+  const crossEnd = av.x * bEndOffset.y - av.y * bEndOffset.x;
+  if (!almostEqual(crossStart, 0, tolerance) || !almostEqual(crossEnd, 0, tolerance)) {
+    return null;
+  }
+  const tBStart = (bStartOffset.x * av.x + bStartOffset.y * av.y) / aLenSq;
+  const tBEnd = (bEndOffset.x * av.x + bEndOffset.y * av.y) / aLenSq;
+  const overlapStart = Math.max(0, Math.min(tBStart, tBEnd));
+  const overlapEnd = Math.min(1, Math.max(tBStart, tBEnd));
+  const minParamLength = tolerance / Math.sqrt(aLenSq);
+  if (overlapEnd - overlapStart <= minParamLength) return null;
+  return {
+    start: pointAlongSegment(a, overlapStart),
+    end: pointAlongSegment(a, overlapEnd)
+  };
+};
+var createJumperPorts = (jumperRegions, topLayerRegions, tolerance = 1e-5) => {
+  const ports = [];
+  let nextPort = 0;
+  for (const jumperRegion of jumperRegions) {
+    for (const topRegion of topLayerRegions) {
+      const sharedEdges = getSharedBoundaryEdges(
+        jumperRegion,
+        topRegion,
+        tolerance
+      );
+      for (const edge of sharedEdges) {
+        const midpoint = pointAlongSegment(edge, 0.5);
+        ports.push({
+          portId: `jp_${nextPort++}`,
+          region1: jumperRegion,
+          region2: topRegion,
+          d: {
+            x: midpoint.x,
+            y: midpoint.y
+          }
+        });
+      }
+    }
+  }
+  return ports;
+};
+var attachPortsToRegions = (ports) => {
+  for (const port of ports) {
+    port.region1.ports.push(port);
+    port.region2.ports.push(port);
+  }
+};
+
+// lib/generate0603JumperHyperGraph.ts
+var generate0603JumperHyperGraph = (input) => {
+  const options = resolve0603GridOptions(input);
+  const pattern = generate0603Pattern(options);
+  const padWidth = options.orientation === "horizontal" ? options.padWidth : options.padHeight;
+  const padHeight = options.orientation === "horizontal" ? options.padHeight : options.padWidth;
+  const rects = pattern.jumpers.flatMap(
+    (jumper) => jumper.padCenters.map((center) => ({
+      center,
+      width: padWidth,
+      height: padHeight,
+      ccwRotation: 0
+    }))
+  );
+  const convexSolver = new ConvexRegionsSolver({
+    bounds: pattern.bounds,
+    rects,
+    clearance: 0,
+    concavityTolerance: options.concavityTolerance
+  });
+  convexSolver.solve();
+  const convex = convexSolver.getOutput();
+  if (!convex) {
+    throw new Error(convexSolver.error ?? "ConvexRegionsSolver failed");
+  }
+  const topLayerRegions = createTopLayerRegions(convex.regions);
+  const jumperRegions = createJumperRegions(pattern.jumpers, {
+    orientation: options.orientation,
+    padWidth: options.padWidth,
+    padHeight: options.padHeight
+  });
+  const topLayerPorts = createTopLayerPorts(
+    topLayerRegions,
+    options.portSpacing
+  );
+  const jumperPorts = createJumperPorts(jumperRegions, topLayerRegions);
+  const ports = [...topLayerPorts, ...jumperPorts];
+  attachPortsToRegions(ports);
+  return {
+    regions: [...topLayerRegions, ...jumperRegions],
+    ports,
+    jumperLocations: pattern.jumpers.map((jumper, index) => ({
+      center: jumper.center,
+      orientation: jumper.orientation,
+      padRegions: [jumperRegions[index]].filter(
+        (region) => Boolean(region)
+      )
+    })),
+    topLayerRegions,
+    jumperRegions,
+    jumpers: pattern.jumpers,
+    vias: pattern.vias,
+    bounds: pattern.bounds
+  };
+};
+
+// lib/visualizeJumperHyperGraph.ts
+var visualizeJumperHyperGraph = (graph) => {
+  const topPolygons = graph.topLayerRegions.map((region) => region.d.polygon).filter((polygon) => Array.isArray(polygon));
+  const jumperPolygons = graph.jumperRegions.map((region) => region.d.polygon).filter((polygon) => Array.isArray(polygon));
+  return {
+    title: "0603 Jumper HyperGraph Topology",
+    polygons: [
+      ...topPolygons.map((points, index) => ({
+        points,
+        fill: "rgba(87, 164, 255, 0.15)",
+        stroke: "#2f78bd",
+        strokeWidth: 0.04,
+        label: `top_${index}`
+      })),
+      ...jumperPolygons.map((points, index) => ({
+        points,
+        fill: "rgba(255, 167, 38, 0.22)",
+        stroke: "#cf6a00",
+        strokeWidth: 0.06,
+        label: `jumper_${index}`
+      }))
+    ],
+    circles: graph.vias.map((via) => ({
+      center: via.center,
+      radius: via.diameter / 2,
+      fill: "rgba(178, 178, 178, 0.5)",
+      stroke: "#6e6e6e",
+      label: "pad-as-via"
+    })),
+    points: graph.ports.map((port) => ({
+      x: port.d.x,
+      y: port.d.y,
+      color: "#1f1f1f",
+      label: port.portId
+    })),
+    rects: [
+      {
+        center: {
+          x: (graph.bounds.minX + graph.bounds.maxX) / 2,
+          y: (graph.bounds.minY + graph.bounds.maxY) / 2
+        },
+        width: graph.bounds.maxX - graph.bounds.minX,
+        height: graph.bounds.maxY - graph.bounds.minY,
+        stroke: "#6f6f6f"
+      }
+    ]
+  };
+};
+export {
+  generate0603GridPattern,
+  generate0603JumperHyperGraph,
+  generate0603Pattern,
+  generate0603StaggeredPattern,
+  resolve0603GridOptions,
+  visualizeJumperHyperGraph
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@tscircuit/jumper-topology-generator",
+  "main": "dist/index.js",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "start": "cosmos",
+    "build": "tsup ./lib/index.ts --format esm --dts --outDir dist",
+    "cosmos:export": "cosmos-export"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.7.0",
+    "@tscircuit/hypergraph": "^0.0.25",
+    "@types/bun": "latest",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
+    "bun-match-svg": "^0.0.15",
+    "graphics-debug": "^0.0.85",
+    "react": "^19.1.1",
+    "react-cosmos": "^7.1.1",
+    "react-cosmos-plugin-vite": "^7.1.1",
+    "react-dom": "^19.1.1",
+    "tsup": "^8.5.1",
+    "vite": "^7.1.5"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@tscircuit/find-convex-regions": "^0.0.3"
+  }
+}