@tscircuit/hypergraph 0.0.17 → 0.0.19

package/dist/index.d.ts

@@ -276,6 +276,7 @@ declare class HyperGraphSolver<RegionType extends Region = Region, RegionPortTyp
         rippingEnabled?: boolean;
         ripCost?: number;
     };
+    getSolverName(): string;
     graph: HyperGraph;
     connections: Connection[];
     candidateQueue: PriorityQueue<Candidate>;
@@ -379,6 +380,7 @@ declare const JUMPER_GRAPH_SOLVER_DEFAULTS: {
     greedyMultiplier: number;
 };
 declare class JumperGraphSolver extends HyperGraphSolver<JRegion, JPort> {
+    getSolverName(): string;
     UNIT_OF_COST: string;
     portUsagePenalty: number;
     portUsagePenaltySq: number;
@@ -423,4 +425,174 @@ declare const rotateGraph90Degrees: (graph: JumperGraph) => JumperGraph;
 
 declare const calculateGraphBounds: (regions: JRegion[]) => Bounds;
 
-export { type Candidate, type Connection, type ConnectionId, type GScore, type GraphEdgeId, type HyperGraph, HyperGraphSolver, type JPort, type JRegion, JUMPER_GRAPH_SOLVER_DEFAULTS, type JumperGraph, JumperGraphSolver, type JumperGraphWithConnections, type NetworkId, type PortAssignment, type PortId, type Region, type RegionId, type RegionPort, type RegionPortAssignment, type SerializedConnection, type SerializedGraphPort, type SerializedGraphRegion, type SerializedHyperGraph, type SerializedRegionPortAssignment, type SolvedRoute, type XYConnection, applyTransformToGraph, calculateGraphBounds, convertConnectionsToSerializedConnections, convertHyperGraphToSerializedHyperGraph, createGraphWithConnectionsFromBaseGraph, generateJumperGrid, generateJumperX4Grid, rotateGraph90Degrees };
+type RegionRef = {
+    id: string;
+};
+type PortSpread = {
+    kind: "midpoint";
+} | {
+    kind: "even";
+    inset?: "half" | number;
+} | {
+    kind: "fractions";
+    ts: number[];
+};
+type ConnectOpts = {
+    idPrefix?: string;
+    tolerance?: number;
+};
+type ValidateOpts = {
+    tolerance?: number;
+    allowNonBoundaryPorts?: boolean;
+};
+type BuildOpts = {
+    validate?: boolean;
+    tolerance?: number;
+};
+type SharedBoundary = {
+    axis: "vertical" | "horizontal";
+    position: number;
+    min: number;
+    max: number;
+};
+type RegionData = {
+    id: string;
+    bounds: Bounds | null;
+    center: {
+        x: number;
+        y: number;
+    } | null;
+    width: number | null;
+    height: number | null;
+    anchor: "center" | "min";
+    isPad: boolean;
+    isThroughJumper: boolean;
+    isConnectionRegion: boolean;
+    meta: Record<string, unknown>;
+};
+type PortData = {
+    id: string;
+    region1Id: string;
+    region2Id: string;
+    x: number;
+    y: number;
+};
+declare class TopologyError extends Error {
+    details?: {
+        regionIds?: string[];
+        relationship?: string;
+        suggestion?: string;
+    } | undefined;
+    constructor(message: string, details?: {
+        regionIds?: string[];
+        relationship?: string;
+        suggestion?: string;
+    } | undefined);
+}
+
+declare class RegionBuilder implements RegionRef {
+    private data;
+    constructor(id: string);
+    get id(): string;
+    rect(b: Bounds): this;
+    center(x: number, y: number): this;
+    size(w: number, h: number, anchor?: "center" | "min"): this;
+    pad(isPad?: boolean): this;
+    throughJumper(isTJ?: boolean): this;
+    connectionRegion(isConn?: boolean): this;
+    meta(extra: Record<string, unknown>): this;
+    getData(): RegionData;
+    ref(): RegionRef;
+}
+
+type AddPortFn$1 = (port: PortData) => void;
+type PrefixIdFn = (id: string) => string;
+declare class ConnectBuilder {
+    private region1Id;
+    private region2Id;
+    private bounds1;
+    private bounds2;
+    private tolerance;
+    private prefix;
+    private prefixIdFn;
+    private addPortFn;
+    private portIds;
+    private boundary;
+    private prefixWasExplicitlySet;
+    constructor(region1Id: string, region2Id: string, bounds1: Bounds, bounds2: Bounds, addPortFn: AddPortFn$1, prefixIdFn: PrefixIdFn, opts?: {
+        idPrefix?: string;
+        tolerance?: number;
+    });
+    private ensureBoundary;
+    idPrefix(prefix: string): this;
+    private getFullPrefix;
+    ports(count: number, spread?: PortSpread): this;
+    at(t: number): this;
+    atXY(p: {
+        x: number;
+        y: number;
+    }): this;
+    getPortIds(): string[];
+    finalizeIfNeeded(): void;
+    hasPortsAdded(): boolean;
+}
+
+type ResolveRegionFn = (ref: RegionRef | string) => {
+    id: string;
+    bounds: Bounds;
+};
+type AddPortFn = (port: PortData) => void;
+declare class PortBuilder {
+    private portId;
+    private region1Id;
+    private region2Id;
+    private position;
+    private tValue;
+    private resolveRegionFn;
+    private addPortFn;
+    private tolerance;
+    constructor(id: string, resolveRegionFn: ResolveRegionFn, addPortFn: AddPortFn, tolerance?: number);
+    id(id: string): this;
+    between(a: RegionRef | string, b: RegionRef | string): this;
+    onSharedEdge(t?: number): this;
+    at(p: {
+        x: number;
+        y: number;
+    }): this;
+    done(): void;
+}
+
+declare class Topology {
+    private regions;
+    private ports;
+    private portIds;
+    private pendingConnections;
+    private scopePrefix;
+    private defaultTolerance;
+    private prefixId;
+    private generateRegionId;
+    private generatePortId;
+    region(id?: string): RegionBuilder;
+    getRegion(id: string): RegionRef;
+    private resolveRegion;
+    private addPort;
+    connect(a: RegionRef | string, b: RegionRef | string, opts?: ConnectOpts): ConnectBuilder;
+    port(id?: string): PortBuilder;
+    scope(prefix: string, fn: (t: Topology) => void): void;
+    validate(opts?: ValidateOpts): void;
+    toJumperGraph(opts?: BuildOpts): JumperGraph;
+    merge(graph: JumperGraph, opts?: {
+        prefix?: string;
+        transform?: (p: {
+            x: number;
+            y: number;
+        }) => {
+            x: number;
+            y: number;
+        };
+    }): void;
+    getRegionIds(): string[];
+    getPortIds(): string[];
+}
+
+export { type Bounds, type BuildOpts, type Candidate, ConnectBuilder, type ConnectOpts, type Connection, type ConnectionId, type GScore, type GraphEdgeId, type HyperGraph, HyperGraphSolver, type JPort, type JRegion, JUMPER_GRAPH_SOLVER_DEFAULTS, type JumperGraph, JumperGraphSolver, type JumperGraphWithConnections, type NetworkId, type PortAssignment, PortBuilder, type PortData, type PortId, type PortSpread, type Region, RegionBuilder, type RegionData, type RegionId, type RegionPort, type RegionPortAssignment, type RegionRef, type SerializedConnection, type SerializedGraphPort, type SerializedGraphRegion, type SerializedHyperGraph, type SerializedRegionPortAssignment, type SharedBoundary, type SolvedRoute, Topology, TopologyError, type ValidateOpts, type XYConnection, applyTransformToGraph, calculateGraphBounds, convertConnectionsToSerializedConnections, convertHyperGraphToSerializedHyperGraph, createGraphWithConnectionsFromBaseGraph, generateJumperGrid, generateJumperX4Grid, rotateGraph90Degrees };

package/dist/index.js

@@ -1829,6 +1829,9 @@ var HyperGraphSolver = class extends BaseSolver {
     this.candidateQueue = new PriorityQueue();
     this.beginNewConnection();
   }
+  getSolverName() {
+    return "HyperGraphSolver";
+  }
   graph;
   connections;
   candidateQueue;
@@ -2486,6 +2489,9 @@ var JUMPER_GRAPH_SOLVER_DEFAULTS = {
   greedyMultiplier: 0.5518001238069296
 };
 var JumperGraphSolver = class extends HyperGraphSolver {
+  getSolverName() {
+    return "JumperGraphSolver";
+  }
   UNIT_OF_COST = "hops";
   portUsagePenalty = JUMPER_GRAPH_SOLVER_DEFAULTS.portUsagePenalty;
   portUsagePenaltySq = JUMPER_GRAPH_SOLVER_DEFAULTS.portUsagePenaltySq;
@@ -2567,10 +2573,843 @@ var JumperGraphSolver = class extends HyperGraphSolver {
     return visualizeJumperGraphSolver(this);
   }
 };
+
+// lib/topology/types.ts
+var TopologyError = class extends Error {
+  constructor(message, details) {
+    super(message);
+    this.details = details;
+    this.name = "TopologyError";
+  }
+};
+
+// lib/topology/RegionBuilder.ts
+var RegionBuilder = class {
+  data;
+  constructor(id) {
+    this.data = {
+      id,
+      bounds: null,
+      center: null,
+      width: null,
+      height: null,
+      anchor: "center",
+      isPad: false,
+      isThroughJumper: false,
+      isConnectionRegion: false,
+      meta: {}
+    };
+  }
+  get id() {
+    return this.data.id;
+  }
+  // Geometry methods
+  rect(b) {
+    this.data.bounds = { ...b };
+    this.data.center = null;
+    this.data.width = null;
+    this.data.height = null;
+    return this;
+  }
+  center(x, y) {
+    this.data.center = { x, y };
+    this.data.bounds = null;
+    return this;
+  }
+  size(w, h, anchor = "center") {
+    if (w <= 0 || h <= 0) {
+      throw new TopologyError(
+        `Region "${this.data.id}" has invalid size: width (${w}) and height (${h}) must be positive`,
+        {
+          regionIds: [this.data.id],
+          suggestion: "Use positive values for width and height"
+        }
+      );
+    }
+    this.data.width = w;
+    this.data.height = h;
+    this.data.anchor = anchor;
+    this.data.bounds = null;
+    return this;
+  }
+  // Semantic methods
+  pad(isPad = true) {
+    this.data.isPad = isPad;
+    return this;
+  }
+  throughJumper(isTJ = true) {
+    this.data.isThroughJumper = isTJ;
+    return this;
+  }
+  connectionRegion(isConn = true) {
+    this.data.isConnectionRegion = isConn;
+    return this;
+  }
+  meta(extra) {
+    this.data.meta = { ...this.data.meta, ...extra };
+    return this;
+  }
+  // Get the internal data (used by Topology)
+  getData() {
+    return this.data;
+  }
+  // Get a reference to this region
+  ref() {
+    return { id: this.data.id };
+  }
+};
+
+// lib/topology/utils.ts
+var DEFAULT_TOLERANCE = 1e-3;
+function computeBoundsFromRegionData(data) {
+  if (data.bounds) {
+    return data.bounds;
+  }
+  if (data.center && data.width !== null && data.height !== null) {
+    const halfW = data.width / 2;
+    const halfH = data.height / 2;
+    if (data.anchor === "center") {
+      return {
+        minX: data.center.x - halfW,
+        maxX: data.center.x + halfW,
+        minY: data.center.y - halfH,
+        maxY: data.center.y + halfH
+      };
+    } else {
+      return {
+        minX: data.center.x,
+        maxX: data.center.x + data.width,
+        minY: data.center.y,
+        maxY: data.center.y + data.height
+      };
+    }
+  }
+  throw new TopologyError(`Region "${data.id}" has incomplete geometry`, {
+    regionIds: [data.id],
+    suggestion: "Use .rect() or .center().size() to define the region geometry"
+  });
+}
+function computeCenterFromBounds(bounds) {
+  return {
+    x: (bounds.minX + bounds.maxX) / 2,
+    y: (bounds.minY + bounds.maxY) / 2
+  };
+}
+function validateBounds(bounds, regionId) {
+  if (bounds.minX >= bounds.maxX) {
+    throw new TopologyError(
+      `Region "${regionId}" has invalid bounds: minX (${bounds.minX}) >= maxX (${bounds.maxX})`,
+      {
+        regionIds: [regionId],
+        suggestion: "Ensure minX < maxX"
+      }
+    );
+  }
+  if (bounds.minY >= bounds.maxY) {
+    throw new TopologyError(
+      `Region "${regionId}" has invalid bounds: minY (${bounds.minY}) >= maxY (${bounds.maxY})`,
+      {
+        regionIds: [regionId],
+        suggestion: "Ensure minY < maxY"
+      }
+    );
+  }
+}
+function findSharedBoundary(boundsA, boundsB, regionIdA, regionIdB, tolerance = DEFAULT_TOLERANCE) {
+  const verticalOverlapMin = Math.max(boundsA.minY, boundsB.minY);
+  const verticalOverlapMax = Math.min(boundsA.maxY, boundsB.maxY);
+  const verticalOverlapLength = verticalOverlapMax - verticalOverlapMin;
+  const horizontalOverlapMin = Math.max(boundsA.minX, boundsB.minX);
+  const horizontalOverlapMax = Math.min(boundsA.maxX, boundsB.maxX);
+  const horizontalOverlapLength = horizontalOverlapMax - horizontalOverlapMin;
+  if (Math.abs(boundsA.maxX - boundsB.minX) < tolerance && verticalOverlapLength > tolerance) {
+    return {
+      axis: "vertical",
+      position: boundsA.maxX,
+      min: verticalOverlapMin,
+      max: verticalOverlapMax
+    };
+  }
+  if (Math.abs(boundsA.minX - boundsB.maxX) < tolerance && verticalOverlapLength > tolerance) {
+    return {
+      axis: "vertical",
+      position: boundsA.minX,
+      min: verticalOverlapMin,
+      max: verticalOverlapMax
+    };
+  }
+  if (Math.abs(boundsA.maxY - boundsB.minY) < tolerance && horizontalOverlapLength > tolerance) {
+    return {
+      axis: "horizontal",
+      position: boundsA.maxY,
+      min: horizontalOverlapMin,
+      max: horizontalOverlapMax
+    };
+  }
+  if (Math.abs(boundsA.minY - boundsB.maxY) < tolerance && horizontalOverlapLength > tolerance) {
+    return {
+      axis: "horizontal",
+      position: boundsA.minY,
+      min: horizontalOverlapMin,
+      max: horizontalOverlapMax
+    };
+  }
+  const relationship = describeRelationship(boundsA, boundsB);
+  throw new TopologyError(
+    `Regions "${regionIdA}" and "${regionIdB}" do not share a boundary`,
+    {
+      regionIds: [regionIdA, regionIdB],
+      relationship,
+      suggestion: "Use .port().between().at() for non-boundary ports, or check region positions"
+    }
+  );
+}
+function describeRelationship(boundsA, boundsB) {
+  const centerA = computeCenterFromBounds(boundsA);
+  const centerB = computeCenterFromBounds(boundsB);
+  const dx = centerB.x - centerA.x;
+  const dy = centerB.y - centerA.y;
+  let direction;
+  if (Math.abs(dx) > Math.abs(dy)) {
+    direction = dx > 0 ? "to the right of" : "to the left of";
+  } else {
+    direction = dy > 0 ? "above" : "below";
+  }
+  const overlapsX = boundsA.maxX > boundsB.minX && boundsB.maxX > boundsA.minX;
+  const overlapsY = boundsA.maxY > boundsB.minY && boundsB.maxY > boundsA.minY;
+  if (overlapsX && overlapsY) {
+    return `Regions overlap (A center: ${centerA.x.toFixed(2)}, ${centerA.y.toFixed(2)}; B center: ${centerB.x.toFixed(2)}, ${centerB.y.toFixed(2)})`;
+  }
+  const touchesAtCornerX = Math.abs(boundsA.maxX - boundsB.minX) < 1e-3 || Math.abs(boundsA.minX - boundsB.maxX) < 1e-3;
+  const touchesAtCornerY = Math.abs(boundsA.maxY - boundsB.minY) < 1e-3 || Math.abs(boundsA.minY - boundsB.maxY) < 1e-3;
+  if (touchesAtCornerX && touchesAtCornerY) {
+    return `Regions touch only at a corner (B is ${direction} A)`;
+  }
+  return `B is ${direction} A with no shared edge`;
+}
+function computePortPositionOnBoundary(boundary, t) {
+  const pos = boundary.min + t * (boundary.max - boundary.min);
+  if (boundary.axis === "vertical") {
+    return { x: boundary.position, y: pos };
+  } else {
+    return { x: pos, y: boundary.position };
+  }
+}
+function computeEvenPortPositions(boundary, count, inset = "half") {
+  const positions = [];
+  const length = boundary.max - boundary.min;
+  for (let i = 0; i < count; i++) {
+    let t;
+    if (inset === "half") {
+      t = (i + 0.5) / count;
+    } else {
+      const insetRatio = inset / length;
+      const usableRange = 1 - 2 * insetRatio;
+      if (count === 1) {
+        t = 0.5;
+      } else {
+        t = insetRatio + i / (count - 1) * usableRange;
+      }
+    }
+    positions.push(computePortPositionOnBoundary(boundary, t));
+  }
+  return positions;
+}
+function pointOnBoundary(point, bounds, tolerance = DEFAULT_TOLERANCE) {
+  const onVerticalEdge = (Math.abs(point.x - bounds.minX) < tolerance || Math.abs(point.x - bounds.maxX) < tolerance) && point.y >= bounds.minY - tolerance && point.y <= bounds.maxY + tolerance;
+  const onHorizontalEdge = (Math.abs(point.y - bounds.minY) < tolerance || Math.abs(point.y - bounds.maxY) < tolerance) && point.x >= bounds.minX - tolerance && point.x <= bounds.maxX + tolerance;
+  return onVerticalEdge || onHorizontalEdge;
+}
+
+// lib/topology/ConnectBuilder.ts
+var ConnectBuilder = class {
+  region1Id;
+  region2Id;
+  bounds1;
+  bounds2;
+  tolerance;
+  prefix;
+  prefixIdFn;
+  addPortFn;
+  portIds = [];
+  boundary = null;
+  prefixWasExplicitlySet = false;
+  constructor(region1Id, region2Id, bounds1, bounds2, addPortFn, prefixIdFn, opts) {
+    this.region1Id = region1Id;
+    this.region2Id = region2Id;
+    this.bounds1 = bounds1;
+    this.bounds2 = bounds2;
+    this.addPortFn = addPortFn;
+    this.prefixIdFn = prefixIdFn;
+    this.tolerance = opts?.tolerance ?? 1e-3;
+    this.prefix = opts?.idPrefix ?? `${region1Id.split(":").pop()}-${region2Id.split(":").pop()}`;
+  }
+  ensureBoundary() {
+    if (!this.boundary) {
+      this.boundary = findSharedBoundary(
+        this.bounds1,
+        this.bounds2,
+        this.region1Id,
+        this.region2Id,
+        this.tolerance
+      );
+    }
+    return this.boundary;
+  }
+  idPrefix(prefix) {
+    this.prefix = prefix;
+    this.prefixWasExplicitlySet = true;
+    return this;
+  }
+  getFullPrefix() {
+    if (this.prefixWasExplicitlySet) {
+      return this.prefixIdFn(this.prefix);
+    }
+    return this.prefixIdFn(this.prefix);
+  }
+  ports(count, spread) {
+    if (count <= 0) {
+      throw new TopologyError(
+        `Invalid port count: ${count}. Must be at least 1`,
+        {
+          regionIds: [this.region1Id, this.region2Id],
+          suggestion: "Use a positive integer for port count"
+        }
+      );
+    }
+    const boundary = this.ensureBoundary();
+    let positions;
+    if (!spread || spread.kind === "midpoint") {
+      if (count === 1) {
+        positions = [computePortPositionOnBoundary(boundary, 0.5)];
+      } else {
+        positions = computeEvenPortPositions(boundary, count, "half");
+      }
+    } else if (spread.kind === "even") {
+      positions = computeEvenPortPositions(boundary, count, spread.inset);
+    } else if (spread.kind === "fractions") {
+      if (spread.ts.length !== count) {
+        throw new TopologyError(
+          `Port count (${count}) doesn't match fractions array length (${spread.ts.length})`,
+          {
+            regionIds: [this.region1Id, this.region2Id],
+            suggestion: "Ensure fractions array has exactly `count` elements"
+          }
+        );
+      }
+      positions = spread.ts.map((t) => {
+        if (t < 0 || t > 1) {
+          throw new TopologyError(
+            `Fraction value ${t} is out of range [0, 1]`,
+            {
+              regionIds: [this.region1Id, this.region2Id],
+              suggestion: "Use values between 0 and 1 for fractions"
+            }
+          );
+        }
+        return computePortPositionOnBoundary(boundary, t);
+      });
+    } else {
+      throw new TopologyError(`Unknown spread kind`, {
+        regionIds: [this.region1Id, this.region2Id]
+      });
+    }
+    const fullPrefix = this.getFullPrefix();
+    for (let i = 0; i < positions.length; i++) {
+      const portId = count === 1 ? fullPrefix : `${fullPrefix}:${i}`;
+      this.addPortFn({
+        id: portId,
+        region1Id: this.region1Id,
+        region2Id: this.region2Id,
+        x: positions[i].x,
+        y: positions[i].y
+      });
+      this.portIds.push(portId);
+    }
+    return this;
+  }
+  at(t) {
+    if (t < 0 || t > 1) {
+      throw new TopologyError(`Position t=${t} is out of range [0, 1]`, {
+        regionIds: [this.region1Id, this.region2Id],
+        suggestion: "Use a value between 0 and 1"
+      });
+    }
+    const boundary = this.ensureBoundary();
+    const position = computePortPositionOnBoundary(boundary, t);
+    const fullPrefix = this.getFullPrefix();
+    this.addPortFn({
+      id: fullPrefix,
+      region1Id: this.region1Id,
+      region2Id: this.region2Id,
+      x: position.x,
+      y: position.y
+    });
+    this.portIds.push(fullPrefix);
+    return this;
+  }
+  atXY(p) {
+    const fullPrefix = this.getFullPrefix();
+    this.addPortFn({
+      id: fullPrefix,
+      region1Id: this.region1Id,
+      region2Id: this.region2Id,
+      x: p.x,
+      y: p.y
+    });
+    this.portIds.push(fullPrefix);
+    return this;
+  }
+  getPortIds() {
+    if (this.portIds.length === 0) {
+      this.ports(1);
+    }
+    return [...this.portIds];
+  }
+  // Called by Topology.toJumperGraph() to ensure default ports are created
+  finalizeIfNeeded() {
+    if (this.portIds.length === 0) {
+      this.ports(1);
+    }
+  }
+  // Check if ports have already been added
+  hasPortsAdded() {
+    return this.portIds.length > 0;
+  }
+};
+
+// lib/topology/PortBuilder.ts
+var PortBuilder = class {
+  portId;
+  region1Id = null;
+  region2Id = null;
+  position = null;
+  tValue = null;
+  resolveRegionFn;
+  addPortFn;
+  tolerance;
+  constructor(id, resolveRegionFn, addPortFn, tolerance = 1e-3) {
+    this.portId = id;
+    this.resolveRegionFn = resolveRegionFn;
+    this.addPortFn = addPortFn;
+    this.tolerance = tolerance;
+  }
+  id(id) {
+    this.portId = id;
+    return this;
+  }
+  between(a, b) {
+    this.region1Id = typeof a === "string" ? a : a.id;
+    this.region2Id = typeof b === "string" ? b : b.id;
+    return this;
+  }
+  onSharedEdge(t = 0.5) {
+    if (t < 0 || t > 1) {
+      throw new TopologyError(`Position t=${t} is out of range [0, 1]`, {
+        suggestion: "Use a value between 0 and 1"
+      });
+    }
+    this.tValue = t;
+    this.position = null;
+    return this;
+  }
+  at(p) {
+    this.position = { x: p.x, y: p.y };
+    this.tValue = null;
+    return this;
+  }
+  done() {
+    if (!this.region1Id || !this.region2Id) {
+      throw new TopologyError(
+        `Port "${this.portId}" must be between two regions`,
+        {
+          suggestion: "Use .between(regionA, regionB) before .done()"
+        }
+      );
+    }
+    const region1 = this.resolveRegionFn(this.region1Id);
+    const region2 = this.resolveRegionFn(this.region2Id);
+    let finalPosition;
+    if (this.position) {
+      finalPosition = this.position;
+      const onBoundary1 = pointOnBoundary(
+        this.position,
+        region1.bounds,
+        this.tolerance
+      );
+      const onBoundary2 = pointOnBoundary(
+        this.position,
+        region2.bounds,
+        this.tolerance
+      );
+      if (!onBoundary1 && !onBoundary2) {
+      }
+    } else {
+      const t = this.tValue ?? 0.5;
+      try {
+        const boundary = findSharedBoundary(
+          region1.bounds,
+          region2.bounds,
+          this.region1Id,
+          this.region2Id,
+          this.tolerance
+        );
+        finalPosition = computePortPositionOnBoundary(boundary, t);
+      } catch (e) {
+        if (e instanceof TopologyError && this.position === null) {
+          throw new TopologyError(
+            `Port "${this.portId}": ${e.message}. No explicit position provided.`,
+            {
+              ...e.details,
+              suggestion: "Use .at({ x, y }) to specify position for non-adjacent regions"
+            }
+          );
+        }
+        throw e;
+      }
+    }
+    this.addPortFn({
+      id: this.portId,
+      region1Id: this.region1Id,
+      region2Id: this.region2Id,
+      x: finalPosition.x,
+      y: finalPosition.y
+    });
+  }
+};
+
+// lib/topology/Topology.ts
+var Topology = class {
+  regions = /* @__PURE__ */ new Map();
+  ports = [];
+  portIds = /* @__PURE__ */ new Set();
+  pendingConnections = [];
+  scopePrefix = "";
+  defaultTolerance = 1e-3;
+  prefixId(id) {
+    return this.scopePrefix ? `${this.scopePrefix}:${id}` : id;
+  }
+  generateRegionId() {
+    let counter = 0;
+    while (true) {
+      const id = this.prefixId(`region_${counter}`);
+      if (!this.regions.has(id)) {
+        return id;
+      }
+      counter++;
+    }
+  }
+  generatePortId() {
+    let counter = 0;
+    while (true) {
+      const id = this.prefixId(`port_${counter}`);
+      if (!this.portIds.has(id)) {
+        return id;
+      }
+      counter++;
+    }
+  }
+  region(id) {
+    const fullId = id ? this.prefixId(id) : this.generateRegionId();
+    if (this.regions.has(fullId)) {
+      throw new TopologyError(`Region "${fullId}" already exists`, {
+        regionIds: [fullId],
+        suggestion: "Use a unique region ID or omit to auto-generate"
+      });
+    }
+    const builder = new RegionBuilder(fullId);
+    this.regions.set(fullId, builder);
+    return builder;
+  }
+  getRegion(id) {
+    const fullId = this.prefixId(id);
+    const region = this.regions.get(fullId);
+    if (!region) {
+      throw new TopologyError(`Region "${fullId}" not found`, {
+        regionIds: [fullId],
+        suggestion: "Create the region first with .region(id)"
+      });
+    }
+    return region.ref();
+  }
+  resolveRegion(ref) {
+    const id = typeof ref === "string" ? this.prefixId(ref) : ref.id;
+    const region = this.regions.get(id);
+    if (!region) {
+      throw new TopologyError(`Region "${id}" not found`, {
+        regionIds: [id],
+        suggestion: "Create the region first with .region(id)"
+      });
+    }
+    const data = region.getData();
+    const bounds = computeBoundsFromRegionData(data);
+    return { id, bounds };
+  }
+  addPort(port) {
+    if (this.portIds.has(port.id)) {
+      throw new TopologyError(`Port "${port.id}" already exists`, {
+        suggestion: "Use a unique port ID"
+      });
+    }
+    this.portIds.add(port.id);
+    this.ports.push(port);
+  }
+  connect(a, b, opts) {
+    const region1 = this.resolveRegion(a);
+    const region2 = this.resolveRegion(b);
+    const currentScopePrefix = this.scopePrefix;
+    const builder = new ConnectBuilder(
+      region1.id,
+      region2.id,
+      region1.bounds,
+      region2.bounds,
+      (port) => this.addPort(port),
+      (id) => currentScopePrefix ? `${currentScopePrefix}:${id}` : id,
+      {
+        idPrefix: opts?.idPrefix,
+        tolerance: opts?.tolerance ?? this.defaultTolerance
+      }
+    );
+    this.pendingConnections.push(builder);
+    return builder;
+  }
+  port(id) {
+    const fullId = id ? this.prefixId(id) : this.generatePortId();
+    return new PortBuilder(
+      fullId,
+      (ref) => this.resolveRegion(ref),
+      (port) => this.addPort(port),
+      this.defaultTolerance
+    );
+  }
+  scope(prefix, fn) {
+    const previousPrefix = this.scopePrefix;
+    this.scopePrefix = previousPrefix ? `${previousPrefix}:${prefix}` : prefix;
+    try {
+      fn(this);
+    } finally {
+      this.scopePrefix = previousPrefix;
+    }
+  }
+  validate(opts) {
+    const tolerance = opts?.tolerance ?? this.defaultTolerance;
+    const allowNonBoundaryPorts = opts?.allowNonBoundaryPorts ?? true;
+    const errors = [];
+    for (const [id, builder] of this.regions) {
+      const data = builder.getData();
+      try {
+        const bounds = computeBoundsFromRegionData(data);
+        validateBounds(bounds, id);
+      } catch (e) {
+        if (e instanceof TopologyError) {
+          errors.push(e.message);
+        } else {
+          throw e;
+        }
+      }
+    }
+    for (const port of this.ports) {
+      if (!this.regions.has(port.region1Id)) {
+        errors.push(
+          `Port "${port.id}" references non-existent region "${port.region1Id}"`
+        );
+      }
+      if (!this.regions.has(port.region2Id)) {
+        errors.push(
+          `Port "${port.id}" references non-existent region "${port.region2Id}"`
+        );
+      }
+      if (this.regions.has(port.region1Id) && this.regions.has(port.region2Id)) {
+        const region1 = this.resolveRegion(port.region1Id);
+        const region2 = this.resolveRegion(port.region2Id);
+        const onBoundary1 = pointOnBoundary(
+          { x: port.x, y: port.y },
+          region1.bounds,
+          tolerance
+        );
+        const onBoundary2 = pointOnBoundary(
+          { x: port.x, y: port.y },
+          region2.bounds,
+          tolerance
+        );
+        if (!allowNonBoundaryPorts && !onBoundary1 && !onBoundary2) {
+          errors.push(
+            `Port "${port.id}" at (${port.x}, ${port.y}) is not on the boundary of either region "${port.region1Id}" or "${port.region2Id}"`
+          );
+        }
+        try {
+          findSharedBoundary(
+            region1.bounds,
+            region2.bounds,
+            port.region1Id,
+            port.region2Id,
+            tolerance
+          );
+        } catch {
+        }
+      }
+    }
+    if (errors.length > 0) {
+      throw new TopologyError(
+        `Topology validation failed with ${errors.length} error(s):
+${errors.map((e) => `  - ${e}`).join("\n")}`
+      );
+    }
+  }
+  toJumperGraph(opts) {
+    for (const connection of this.pendingConnections) {
+      connection.finalizeIfNeeded();
+    }
+    this.pendingConnections = [];
+    if (opts?.validate !== false) {
+      this.validate({ tolerance: opts?.tolerance });
+    }
+    const jregions = /* @__PURE__ */ new Map();
+    const regionsList = [];
+    for (const [id, builder] of this.regions) {
+      const data = builder.getData();
+      const bounds = computeBoundsFromRegionData(data);
+      const center = computeCenterFromBounds(bounds);
+      const jregion = {
+        regionId: id,
+        ports: [],
+        d: {
+          bounds,
+          center,
+          isPad: data.isPad,
+          ...data.isThroughJumper && { isThroughJumper: true },
+          ...data.isConnectionRegion && { isConnectionRegion: true },
+          ...data.meta
+        }
+      };
+      jregions.set(id, jregion);
+      regionsList.push(jregion);
+    }
+    const portsList = [];
+    for (const portData of this.ports) {
+      const region1 = jregions.get(portData.region1Id);
+      const region2 = jregions.get(portData.region2Id);
+      if (!region1 || !region2) {
+        throw new TopologyError(
+          `Port "${portData.id}" references non-existent region`,
+          {
+            regionIds: [portData.region1Id, portData.region2Id]
+          }
+        );
+      }
+      const jport = {
+        portId: portData.id,
+        region1,
+        region2,
+        d: {
+          x: portData.x,
+          y: portData.y
+        }
+      };
+      region1.ports.push(jport);
+      region2.ports.push(jport);
+      portsList.push(jport);
+    }
+    return {
+      regions: regionsList,
+      ports: portsList
+    };
+  }
+  // Utility method to merge an existing JumperGraph
+  merge(graph, opts) {
+    const prefix = opts?.prefix ?? "";
+    const transform2 = opts?.transform ?? ((p) => p);
+    const regionIdMap = /* @__PURE__ */ new Map();
+    for (const region of graph.regions) {
+      const newId = prefix ? `${prefix}:${region.regionId}` : region.regionId;
+      if (this.regions.has(newId)) {
+        throw new TopologyError(
+          `Region "${newId}" already exists during merge`,
+          {
+            regionIds: [newId]
+          }
+        );
+      }
+      regionIdMap.set(region.regionId, newId);
+      const builder = new RegionBuilder(newId);
+      const transformedBounds = {
+        minX: Math.min(
+          transform2({ x: region.d.bounds.minX, y: region.d.bounds.minY }).x,
+          transform2({ x: region.d.bounds.maxX, y: region.d.bounds.maxY }).x
+        ),
+        maxX: Math.max(
+          transform2({ x: region.d.bounds.minX, y: region.d.bounds.minY }).x,
+          transform2({ x: region.d.bounds.maxX, y: region.d.bounds.maxY }).x
+        ),
+        minY: Math.min(
+          transform2({ x: region.d.bounds.minX, y: region.d.bounds.minY }).y,
+          transform2({ x: region.d.bounds.maxX, y: region.d.bounds.maxY }).y
+        ),
+        maxY: Math.max(
+          transform2({ x: region.d.bounds.minX, y: region.d.bounds.minY }).y,
+          transform2({ x: region.d.bounds.maxX, y: region.d.bounds.maxY }).y
+        )
+      };
+      builder.rect(transformedBounds);
+      if (region.d.isPad) builder.pad();
+      if (region.d.isThroughJumper) builder.throughJumper();
+      if (region.d.isConnectionRegion) builder.connectionRegion();
+      const {
+        bounds,
+        center,
+        isPad,
+        isThroughJumper,
+        isConnectionRegion,
+        ...rest
+      } = region.d;
+      if (Object.keys(rest).length > 0) {
+        builder.meta(rest);
+      }
+      this.regions.set(newId, builder);
+    }
+    for (const port of graph.ports) {
+      const newId = prefix ? `${prefix}:${port.portId}` : port.portId;
+      if (this.portIds.has(newId)) {
+        throw new TopologyError(`Port "${newId}" already exists during merge`, {
+          suggestion: "Use a different prefix"
+        });
+      }
+      const newRegion1Id = regionIdMap.get(port.region1.regionId);
+      const newRegion2Id = regionIdMap.get(port.region2.regionId);
+      if (!newRegion1Id || !newRegion2Id) {
+        throw new TopologyError(
+          `Port "${port.portId}" references region not in the merged graph`
+        );
+      }
+      const transformedPos = transform2({ x: port.d.x, y: port.d.y });
+      this.portIds.add(newId);
+      this.ports.push({
+        id: newId,
+        region1Id: newRegion1Id,
+        region2Id: newRegion2Id,
+        x: transformedPos.x,
+        y: transformedPos.y
+      });
+    }
+  }
+  // Get all region IDs (useful for debugging)
+  getRegionIds() {
+    return Array.from(this.regions.keys());
+  }
+  // Get all port IDs (useful for debugging)
+  getPortIds() {
+    return Array.from(this.portIds);
+  }
+};
 export {
+  ConnectBuilder,
   HyperGraphSolver,
   JUMPER_GRAPH_SOLVER_DEFAULTS,
   JumperGraphSolver,
+  PortBuilder,
+  RegionBuilder,
+  Topology,
+  TopologyError,
   applyTransformToGraph,
   calculateGraphBounds,
   convertConnectionsToSerializedConnections,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tscircuit/hypergraph",
   "main": "dist/index.js",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "scripts": {
     "start": "cosmos",
@@ -29,6 +29,6 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@tscircuit/solver-utils": "^0.0.13"
+    "@tscircuit/solver-utils": "^0.0.14"
   }
 }