calculate-packing 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tscircuit
+
+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,96 @@
+# calculate-packing
+
+**calculate-packing** is a small TypeScript library that ships the placement /
+packing algorithm used by the [tscircuit tool-chain](https://github.com/tscircuit/tscircuit) for automatically laying out PCB components.
+
+The solver turns a user-supplied `PackInput` (components, pads & strategy
+settings) into a collision-free `PackOutput` while
+
+- honouring a configurable clearance (`minGap`)
+- keeping pads that share the same `networkId` close together
+- minimising overall trace length
+
+Internally the algorithm:
+
+1. sorts components (largest → smallest)
+2. keeps an outline (union of inflated component AABBs) of the already packed
+   island(s)
+3. probes outline segments for the point with the shortest distance to any pad
+   on the same network
+4. evaluates the four orthogonal rotations of the candidate component and
+   chooses the cheapest non-overlapping one
+
+## Installation
+
+```bash
+bun add calculate-packing      # or npm i / yarn add
+```
+
+## Quick start
+
+```ts
+import { pack, PackInput } from "calculate-packing"
+
+const input: PackInput = {
+  components: [
+    {
+      componentId: "C1",
+      pads: [
+        {
+          padId: "C1_1",
+          networkId: "GND",
+          type: "rect",
+          offset: { x: -0.6, y: 0 },
+          size: { x: 1.2, y: 1 },
+        },
+        {
+          padId: "C1_2",
+          networkId: "VCC",
+          type: "rect",
+          offset: { x: +0.6, y: 0 },
+          size: { x: 1.2, y: 1 },
+        },
+      ],
+    },
+    /* …more components… */
+  ],
+  minGap: 0.25,
+  packOrderStrategy: "largest_to_smallest",
+  packPlacementStrategy: "shortest_connection_along_outline",
+}
+
+const result = pack(input)
+console.log(result.components) // → positioned & rotated components
+```
+
+See `tests/` for more elaborate examples (SVG snapshots, circuit-json fixtures).
+
+## Development
+
+```bash
+bun install       # install deps
+bun test          # run unit & SVG snapshot tests
+bunx tsc --noEmit # type-check
+```
+
+### Repo layout
+
+• `lib/PackSolver` – high-level packing solver  
+• `lib/geometry` – computational-geometry helpers  
+• `lib/math` – low-level math utilities  
+• `tests/` – unit & snapshot tests
+
+## Public API
+
+| export                             | purpose                                   |
+| ---------------------------------- | ----------------------------------------- |
+| `pack()`                           | run the solver                            |
+| `convertPackOutputToPackInput()`   | strip solver-only fields                  |
+| `convertCircuitJsonToPackOutput()` | circuit-json → PackOutput helper          |
+| `getGraphicsFromPackOutput()`      | build a `graphics-debug` scene for review |
+
+Everything else is internal and may change without notice.
+
+## License
+
+MIT – see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+import { GraphicsObject, Point } from 'graphics-debug';
+import { CircuitJson } from 'circuit-json';
+
+type ComponentId = string;
+type PadId = string;
+type NetworkId = string;
+interface InputPad {
+    padId: string;
+    networkId: string;
+    type: "rect";
+    offset: {
+        x: number;
+        y: number;
+    };
+    size: {
+        x: number;
+        y: number;
+    };
+}
+interface OutputPad extends InputPad {
+    absoluteCenter: {
+        x: number;
+        y: number;
+    };
+}
+interface InputComponent {
+    componentId: string;
+    pads: InputPad[];
+}
+interface PackedComponent extends InputComponent {
+    center: {
+        x: number;
+        y: number;
+    };
+    ccwRotationOffset: number;
+    pads: OutputPad[];
+}
+interface PackInput {
+    components: InputComponent[];
+    minGap: number;
+    packOrderStrategy: "largest_to_smallest";
+    packPlacementStrategy: "shortest_connection_along_outline";
+    disconnectedPackDirection?: "left" | "right" | "up" | "down";
+    packFirst?: ComponentId[];
+}
+interface PackOutput extends PackInput {
+    components: PackedComponent[];
+}
+
+/**
+ * The pack algorithm performs the following steps:
+ * 1. Sort the components using the packOrderStrategy
+ * 2. Select the next component to pack
+ * 3. If the first component, pack at center (0,0) and go to step 2
+ * 4. Compute the outline of all packed components with a gap of minGap + max(pad.width, pad.height)/2
+ * 5. Find the point along the outline that minimizes the distance of the pad
+ *    centers within a networkId. If no shared pads, pack to the defaultPackDirection
+ * 6. Add the component at the selected point, with it's pad at the position
+ *    minimizing the distance between the pad centers
+ * 7. To determine the component rotation, find the minimum distance between pad
+ *    centers for the remaining pads at each possible rotation (making sure that
+ *    we never pack such that two pads overlap)
+ * 8. Go to step 2 until all components are packed
+ */
+declare const pack: (input: PackInput) => PackOutput;
+
+declare class BaseSolver {
+    MAX_ITERATIONS: number;
+    solved: boolean;
+    failed: boolean;
+    iterations: number;
+    progress: number;
+    error: string | null;
+    activeSubSolver?: BaseSolver | null;
+    failedSubSolvers?: BaseSolver[];
+    timeToSolve?: number;
+    stats: Record<string, any>;
+    _setupDone: boolean;
+    setup(): void;
+    /** DO NOT OVERRIDE! Override _step() instead */
+    step(): void;
+    _setup(): void;
+    _step(): void;
+    getConstructorParams(): void;
+    solve(): void;
+    visualize(): GraphicsObject;
+    /**
+     * Called when the solver is about to fail, but we want to see if we have an
+     * "acceptable" or "passable" solution. Mostly used for optimizers that
+     * have an aggressive early stopping criterion.
+     */
+    tryFinalAcceptance(): void;
+    /**
+     * A lightweight version of the visualize method that can be used to stream
+     * progress
+     */
+    preview(): GraphicsObject;
+}
+
+/**
+ * The pack algorithm performs the following steps:
+ * 1. Sort the components using the packOrderStrategy
+ * 2. Select the next component to pack
+ * 3. If the first component, pack at center (0,0) and go to step 2
+ * 4. Compute the outline of all packed components with a gap of minGap + max(pad.width, pad.height)/2
+ * 5. Find the point along the outline that minimizes the distance of the pad
+ *    centers within a networkId. If no shared pads, pack to the defaultPackDirection
+ * 6. Add the component at the selected point, with it's pad at the position
+ *    minimizing the distance between the pad centers
+ * 7. To determine the component rotation, find the minimum distance between pad
+ *    centers for the remaining pads at each possible rotation (making sure that
+ *    we never pack such that two pads overlap)
+ * 8. Go to step 2 until all components are packed
+ */
+declare class PackSolver extends BaseSolver {
+    packInput: PackInput;
+    unpackedComponentQueue: InputComponent[];
+    packedComponents: PackedComponent[];
+    lastBestPointsResult?: {
+        bestPoints: (Point & {
+            networkId: NetworkId;
+        })[];
+        distance: number;
+    };
+    constructor(input: PackInput);
+    _setup(): void;
+    _step(): void;
+    getConstructorParams(): PackInput[];
+    /** Visualize the current packing state – components are omitted, only the outline is shown. */
+    visualize(): GraphicsObject;
+    getResult(): PackedComponent[];
+}
+
+declare const convertCircuitJsonToPackOutput: (circuitJson: CircuitJson) => PackOutput;
+
+declare const getGraphicsFromPackOutput: (packOutput: PackOutput) => GraphicsObject;
+
+/**
+ * Strip all “output only” properties (those added by the pack() solver)
+ * so the result can be fed back into pack() again or compared against an
+ * original PackInput.  Everything else must be preserved verbatim.
+ *
+ * NOTE:
+ * – PackInput.components is an array of **InputComponent**,
+ *   while PackOutput.components is an array of **PackedComponent**.
+ *   We therefore have to:
+ *     • copy componentId
+ *     • copy each pad but drop `absoluteCenter`
+ *     • drop `center` and `ccwRotationOffset`
+ */
+declare const convertPackOutputToPackInput: (packed: PackOutput) => PackInput;
+
+export { type ComponentId, type InputComponent, type InputPad, type NetworkId, type OutputPad, type PackInput, type PackOutput, PackSolver, type PackedComponent, type PadId, convertCircuitJsonToPackOutput, convertPackOutputToPackInput, getGraphicsFromPackOutput, pack };

package/dist/index.js

@@ -0,0 +1,712 @@
+// lib/solver-utils/BaseSolver.ts
+var BaseSolver = class {
+  MAX_ITERATIONS = 1e3;
+  solved = false;
+  failed = false;
+  iterations = 0;
+  progress = 0;
+  error = null;
+  activeSubSolver;
+  failedSubSolvers;
+  timeToSolve;
+  stats = {};
+  _setupDone = false;
+  setup() {
+    if (this._setupDone) return;
+    this._setup();
+    this._setupDone = true;
+  }
+  /** DO NOT OVERRIDE! Override _step() instead */
+  step() {
+    if (!this._setupDone) {
+      this.setup();
+    }
+    if (this.solved) return;
+    if (this.failed) return;
+    this.iterations++;
+    try {
+      this._step();
+    } catch (e) {
+      this.error = `${this.constructor.name} error: ${e}`;
+      console.error(this.error);
+      this.failed = true;
+      throw e;
+    }
+    if (!this.solved && this.iterations > this.MAX_ITERATIONS) {
+      this.tryFinalAcceptance();
+    }
+    if (!this.solved && this.iterations > this.MAX_ITERATIONS) {
+      this.error = `${this.constructor.name} ran out of iterations`;
+      console.error(this.error);
+      this.failed = true;
+    }
+    if ("computeProgress" in this) {
+      this.progress = this.computeProgress();
+    }
+  }
+  _setup() {
+  }
+  _step() {
+  }
+  getConstructorParams() {
+    throw new Error("getConstructorParams not implemented");
+  }
+  solve() {
+    const startTime = Date.now();
+    while (!this.solved && !this.failed) {
+      this.step();
+    }
+    const endTime = Date.now();
+    this.timeToSolve = endTime - startTime;
+  }
+  visualize() {
+    return {
+      lines: [],
+      points: [],
+      rects: [],
+      circles: []
+    };
+  }
+  /**
+   * Called when the solver is about to fail, but we want to see if we have an
+   * "acceptable" or "passable" solution. Mostly used for optimizers that
+   * have an aggressive early stopping criterion.
+   */
+  tryFinalAcceptance() {
+  }
+  /**
+   * A lightweight version of the visualize method that can be used to stream
+   * progress
+   */
+  preview() {
+    return {
+      lines: [],
+      points: [],
+      rects: [],
+      circles: []
+    };
+  }
+};
+
+// lib/math/rotatePoint.ts
+var rotatePoint = (point, angle, origin = { x: 0, y: 0 }) => {
+  const cos = Math.cos(angle);
+  const sin = Math.sin(angle);
+  const dx = point.x - origin.x;
+  const dy = point.y - origin.y;
+  return {
+    x: origin.x + dx * cos - dy * sin,
+    y: origin.y + dx * sin + dy * cos
+  };
+};
+
+// lib/geometry/getComponentBounds.ts
+var getComponentBounds = (component, minGap = 0) => {
+  const bounds = {
+    minX: Infinity,
+    maxX: -Infinity,
+    minY: Infinity,
+    maxY: -Infinity
+  };
+  component.pads.forEach((pad) => {
+    const hw = pad.size.x / 2;
+    const hh = pad.size.y / 2;
+    const localCorners = [
+      { x: pad.offset.x - hw, y: pad.offset.y - hh },
+      { x: pad.offset.x + hw, y: pad.offset.y - hh },
+      { x: pad.offset.x + hw, y: pad.offset.y + hh },
+      { x: pad.offset.x - hw, y: pad.offset.y + hh }
+    ];
+    localCorners.forEach((corner) => {
+      const world = rotatePoint(corner, component.ccwRotationOffset);
+      const x = world.x + component.center.x;
+      const y = world.y + component.center.y;
+      bounds.minX = Math.min(bounds.minX, x);
+      bounds.maxX = Math.max(bounds.maxX, x);
+      bounds.minY = Math.min(bounds.minY, y);
+      bounds.maxY = Math.max(bounds.maxY, y);
+    });
+  });
+  return {
+    minX: bounds.minX - minGap,
+    maxX: bounds.maxX + minGap,
+    minY: bounds.minY - minGap,
+    maxY: bounds.maxY + minGap
+  };
+};
+
+// lib/constructOutlinesFromPackedComponents.ts
+import Flatten from "@flatten-js/core";
+var constructOutlinesFromPackedComponents = (components, opts = {}) => {
+  const { minGap = 0 } = opts;
+  if (components.length === 0) return [];
+  const rectPolys = components.map((c) => {
+    const b = getComponentBounds(c, minGap);
+    return new Flatten.Polygon([
+      [b.minX, b.minY],
+      [b.maxX, b.minY],
+      [b.maxX, b.maxY],
+      [b.minX, b.maxY]
+    ]);
+  });
+  if (rectPolys.length === 0) return [];
+  let union = rectPolys[0];
+  for (let i = 1; i < rectPolys.length; i++) {
+    union = Flatten.BooleanOperations.unify(union, rectPolys[i]);
+  }
+  const outlines = [];
+  for (const face of union.faces) {
+    if (face.isHole) continue;
+    const outline = [];
+    let edge = face.first;
+    if (!edge) continue;
+    do {
+      const shp = edge.shape;
+      const ps = shp.start ?? shp.ps;
+      const pe = shp.end ?? shp.pe;
+      outline.push([
+        { x: ps.x, y: ps.y },
+        { x: pe.x, y: pe.y }
+      ]);
+      edge = edge.next;
+    } while (edge !== face.first);
+    outlines.push(outline);
+  }
+  return outlines;
+};
+
+// lib/testing/createColorMapFromStrings.ts
+var createColorMapFromStrings = (strings) => {
+  const colorMap = {};
+  for (let i = 0; i < strings.length; i++) {
+    colorMap[strings[i]] = `hsl(${i * 300 / strings.length}, 100%, 50%)`;
+  }
+  return colorMap;
+};
+
+// lib/testing/getGraphicsFromPackOutput.ts
+var getGraphicsFromPackOutput = (packOutput) => {
+  const rects = [];
+  const lines = [];
+  const allNetworkIds = Array.from(
+    new Set(
+      packOutput.components.flatMap((c) => c.pads.map((p) => p.networkId))
+    )
+  );
+  const colorMap = createColorMapFromStrings(allNetworkIds);
+  for (const component of packOutput.components) {
+    const bounds = getComponentBounds(component);
+    const width = bounds.maxX - bounds.minX;
+    const height = bounds.maxY - bounds.minY;
+    const rect = {
+      center: { x: component.center.x, y: component.center.y },
+      width,
+      height,
+      fill: "rgba(0,0,0,0.25)",
+      label: component.componentId
+    };
+    rects.push(rect);
+    for (const pad of component.pads) {
+      const { absoluteCenter, size, padId, networkId } = pad;
+      const padRect = {
+        center: { x: absoluteCenter.x, y: absoluteCenter.y },
+        width: size.x,
+        height: size.y,
+        label: `${padId} ${networkId}`,
+        fill: "rgba(255,0,0,0.8)"
+      };
+      rects.push(padRect);
+    }
+  }
+  for (const netId of allNetworkIds) {
+    const padsOnNet = packOutput.components.flatMap(
+      (c) => c.pads.filter((p) => p.networkId === netId)
+    );
+    for (let i = 0; i < padsOnNet.length; i++) {
+      for (let j = i + 1; j < padsOnNet.length; j++) {
+        lines.push({
+          points: [padsOnNet[i].absoluteCenter, padsOnNet[j].absoluteCenter],
+          strokeColor: colorMap[netId]
+        });
+      }
+    }
+  }
+  return {
+    coordinateSystem: "cartesian",
+    rects,
+    lines
+  };
+};
+
+// lib/PackSolver/setPackedComponentPadCenters.ts
+var setPackedComponentPadCenters = (packedComponent) => {
+  packedComponent.pads = packedComponent.pads.map((pad) => ({
+    ...pad,
+    absoluteCenter: (() => {
+      const rotated = rotatePoint(pad.offset, packedComponent.ccwRotationOffset);
+      return {
+        x: packedComponent.center.x + rotated.x,
+        y: packedComponent.center.y + rotated.y
+      };
+    })()
+  }));
+};
+
+// lib/PackSolver/getSegmentsFromPad.ts
+var getSegmentsFromPad = (pad, { padding = 0 } = {}) => {
+  const segments = [];
+  const { x, y } = pad.absoluteCenter;
+  const { x: w, y: h } = pad.size;
+  segments.push([
+    { x: x - w / 2 - padding, y: y - h / 2 - padding },
+    { x: x + w / 2 + padding, y: y - h / 2 - padding }
+  ]);
+  segments.push([
+    { x: x + w / 2 + padding, y: y - h / 2 - padding },
+    { x: x + w / 2 + padding, y: y + h / 2 + padding }
+  ]);
+  segments.push([
+    { x: x + w / 2 + padding, y: y + h / 2 + padding },
+    { x: x - w / 2 - padding, y: y + h / 2 + padding }
+  ]);
+  segments.push([
+    { x: x - w / 2 - padding, y: y + h / 2 + padding },
+    { x: x - w / 2 - padding, y: y - h / 2 - padding }
+  ]);
+  return segments;
+};
+
+// lib/math/computeNearestPointOnSegmentForSegmentSet.ts
+var sub = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
+var add = (a, b) => ({ x: a.x + b.x, y: a.y + b.y });
+var mul = (a, s) => ({ x: a.x * s, y: a.y * s });
+var dot = (a, b) => a.x * b.x + a.y * b.y;
+var clamp = (v, lo = 0, hi = 1) => Math.max(lo, Math.min(hi, v));
+function closestPointOnSegAToSegB(segA, segB) {
+  const [p, q] = segA;
+  const [r, s] = segB;
+  const u = sub(q, p);
+  const v = sub(s, r);
+  const w0 = sub(p, r);
+  const a = dot(u, u);
+  const b = dot(u, v);
+  const c = dot(v, v);
+  const d = dot(u, w0);
+  const e = dot(v, w0);
+  const EPS = 1e-12;
+  const D = a * c - b * b;
+  let sN;
+  let tN;
+  let sD = D;
+  let tD = D;
+  if (D < EPS) {
+    sN = 0;
+    sD = 1;
+    tN = e;
+    tD = c;
+  } else {
+    sN = b * e - c * d;
+    tN = a * e - b * d;
+    if (sN < 0) {
+      sN = 0;
+      tN = e;
+      tD = c;
+    } else if (sN > sD) {
+      sN = sD;
+      tN = e + b;
+      tD = c;
+    }
+  }
+  if (tN < 0) {
+    tN = 0;
+    sN = clamp(-d, 0, a);
+    sD = a;
+  } else if (tN > tD) {
+    tN = tD;
+    sN = clamp(-d + b, 0, a);
+    sD = a;
+  }
+  const sParam = sD > EPS ? sN / sD : 0;
+  const closestA = add(p, mul(u, sParam));
+  const tParam = tD > EPS ? tN / tD : 0;
+  const closestB = add(r, mul(v, tParam));
+  const diff = sub(closestA, closestB);
+  return { pointA: closestA, paramA: sParam, dist2: dot(diff, diff) };
+}
+function computeNearestPointOnSegmentForSegmentSet(segmentA, segmentSet) {
+  if (!segmentSet.length)
+    throw new Error("segmentSet must contain at least one segment");
+  let bestPoint = segmentA[0];
+  let bestDist2 = Number.POSITIVE_INFINITY;
+  for (const segB of segmentSet) {
+    const { pointA, dist2 } = closestPointOnSegAToSegB(segmentA, segB);
+    if (dist2 < bestDist2) {
+      bestDist2 = dist2;
+      bestPoint = pointA;
+      if (bestDist2 === 0) break;
+    }
+  }
+  return { nearestPoint: bestPoint, dist: Math.sqrt(bestDist2) };
+}
+
+// lib/PackSolver/PackSolver.ts
+var PackSolver = class extends BaseSolver {
+  packInput;
+  unpackedComponentQueue;
+  packedComponents;
+  lastBestPointsResult;
+  constructor(input) {
+    super();
+    this.packInput = input;
+  }
+  _setup() {
+    const { components, packOrderStrategy } = this.packInput;
+    this.unpackedComponentQueue = [...components].sort((a, b) => {
+      if (packOrderStrategy === "largest_to_smallest") {
+        return b.pads.length - a.pads.length;
+      }
+      return a.pads.length - b.pads.length;
+    });
+    this.packedComponents = [];
+  }
+  _step() {
+    if (this.solved) return;
+    const { minGap = 0, disconnectedPackDirection = "right" } = this.packInput;
+    if (this.unpackedComponentQueue.length === 0) {
+      this.solved = true;
+      return;
+    }
+    const next = this.unpackedComponentQueue.shift();
+    if (!next) {
+      this.solved = true;
+      return;
+    }
+    const newPackedComponent = {
+      ...next,
+      center: { x: 0, y: 0 },
+      ccwRotationOffset: 0,
+      pads: next.pads.map((p) => ({
+        ...p,
+        absoluteCenter: { x: 0, y: 0 }
+      }))
+    };
+    if (this.packedComponents.length === 0) {
+      newPackedComponent.center = { x: 0, y: 0 };
+      setPackedComponentPadCenters(newPackedComponent);
+      this.packedComponents.push(newPackedComponent);
+      return;
+    }
+    const padMargins = newPackedComponent.pads.map(
+      (p) => Math.max(p.size.x, p.size.y) / 2
+    );
+    const additionalGap = Math.max(...padMargins);
+    const outlines = constructOutlinesFromPackedComponents(
+      this.packedComponents,
+      { minGap: minGap + additionalGap }
+    );
+    const networkIdsInPackedComponents = new Set(
+      this.packedComponents.flatMap((c) => c.pads.map((p) => p.networkId))
+    );
+    const networkIdsInNewPackedComponent = new Set(
+      newPackedComponent.pads.map((p) => p.networkId)
+    );
+    const sharedNetworkIds = new Set(
+      [...networkIdsInPackedComponents].filter(
+        (id) => networkIdsInNewPackedComponent.has(id)
+      )
+    );
+    if (sharedNetworkIds.size === 0) {
+      throw new Error(
+        "Use the disconnectedPackDirection to place the new component"
+      );
+    }
+    const networkIdToAlreadyPackedSegments = /* @__PURE__ */ new Map();
+    for (const sharedNetworkId of sharedNetworkIds) {
+      networkIdToAlreadyPackedSegments.set(sharedNetworkId, []);
+      for (const packedComponent of this.packedComponents) {
+        for (const pad of packedComponent.pads) {
+          if (pad.networkId !== sharedNetworkId) continue;
+          const segments = getSegmentsFromPad(pad);
+          networkIdToAlreadyPackedSegments.set(sharedNetworkId, segments);
+        }
+      }
+    }
+    let smallestDistance = Number.POSITIVE_INFINITY;
+    let bestPoints = [];
+    for (const outline of outlines) {
+      for (const outlineSegment of outline) {
+        for (const sharedNetworkId of sharedNetworkIds) {
+          const alreadyPackedSegments = networkIdToAlreadyPackedSegments.get(sharedNetworkId);
+          if (!alreadyPackedSegments) continue;
+          const {
+            nearestPoint: nearestPointOnOutlineToAlreadyPackedSegments,
+            dist: outlineToAlreadyPackedSegmentsDist
+          } = computeNearestPointOnSegmentForSegmentSet(
+            outlineSegment,
+            alreadyPackedSegments
+          );
+          if (outlineToAlreadyPackedSegmentsDist < smallestDistance + 1e-6) {
+            if (outlineToAlreadyPackedSegmentsDist < smallestDistance - 1e-6) {
+              bestPoints = [
+                {
+                  ...nearestPointOnOutlineToAlreadyPackedSegments,
+                  networkId: sharedNetworkId
+                }
+              ];
+              smallestDistance = outlineToAlreadyPackedSegmentsDist;
+            } else {
+              bestPoints.push({
+                ...nearestPointOnOutlineToAlreadyPackedSegments,
+                networkId: sharedNetworkId
+              });
+            }
+          }
+        }
+      }
+    }
+    this.lastBestPointsResult = {
+      bestPoints,
+      distance: smallestDistance
+    };
+    for (const bestPoint of bestPoints) {
+      const networkId = bestPoint.networkId;
+      const newPadsConnectedToNetworkId = newPackedComponent.pads.filter(
+        (p) => p.networkId === networkId
+      );
+      const candidateAngles = [0, Math.PI / 2, Math.PI, 3 * Math.PI / 2];
+      let bestCandidate = null;
+      const packedPads = this.packedComponents.flatMap((c) => c.pads);
+      for (const angle of candidateAngles) {
+        const firstPad = newPadsConnectedToNetworkId[0];
+        if (!firstPad) continue;
+        const rotatedOffset = rotatePoint(firstPad.offset, angle);
+        const candidateCenter = {
+          x: bestPoint.x - rotatedOffset.x,
+          y: bestPoint.y - rotatedOffset.y
+        };
+        const transformedPads = newPackedComponent.pads.map((p) => {
+          const ro = rotatePoint(p.offset, angle);
+          return {
+            ...p,
+            absoluteCenter: {
+              x: candidateCenter.x + ro.x,
+              y: candidateCenter.y + ro.y
+            }
+          };
+        });
+        const tempComponent = {
+          ...newPackedComponent,
+          center: candidateCenter,
+          ccwRotationOffset: angle
+        };
+        const candBounds = getComponentBounds(tempComponent, 0);
+        const overlapsWithPackedComponent = this.packedComponents.some((pc) => {
+          const pcBounds = getComponentBounds(pc, 0);
+          return candBounds.minX < pcBounds.maxX && candBounds.maxX > pcBounds.minX && candBounds.minY < pcBounds.maxY && candBounds.maxY > pcBounds.minY;
+        });
+        if (overlapsWithPackedComponent) continue;
+        let cost = 0;
+        for (const tp of transformedPads) {
+          const sameNetPads = packedPads.filter(
+            (pp) => pp.networkId === tp.networkId
+          );
+          if (!sameNetPads.length) continue;
+          let bestD = Infinity;
+          for (const pp of sameNetPads) {
+            const dx = tp.absoluteCenter.x - pp.absoluteCenter.x;
+            const dy = tp.absoluteCenter.y - pp.absoluteCenter.y;
+            const d = Math.hypot(dx, dy);
+            if (d < bestD) bestD = d;
+          }
+          cost += bestD;
+        }
+        if (!bestCandidate || cost < bestCandidate.cost) {
+          bestCandidate = { center: candidateCenter, angle, cost };
+        }
+      }
+      if (bestCandidate) {
+        newPackedComponent.center = bestCandidate.center;
+        newPackedComponent.ccwRotationOffset = bestCandidate.angle;
+      } else {
+        console.log("no valid rotation found");
+        const firstPad = newPadsConnectedToNetworkId[0];
+        const candidateCenter = {
+          x: bestPoint.x - firstPad.offset.x,
+          y: bestPoint.y - firstPad.offset.y
+        };
+        newPackedComponent.center = candidateCenter;
+        newPackedComponent.ccwRotationOffset = 0;
+      }
+      setPackedComponentPadCenters(newPackedComponent);
+    }
+    setPackedComponentPadCenters(newPackedComponent);
+    this.packedComponents.push(newPackedComponent);
+  }
+  getConstructorParams() {
+    return [this.packInput];
+  }
+  /** Visualize the current packing state – components are omitted, only the outline is shown. */
+  visualize() {
+    const graphics = getGraphicsFromPackOutput({
+      components: this.packedComponents ?? [],
+      minGap: this.packInput.minGap,
+      packOrderStrategy: this.packInput.packOrderStrategy,
+      packPlacementStrategy: this.packInput.packPlacementStrategy,
+      disconnectedPackDirection: this.packInput.disconnectedPackDirection
+    });
+    graphics.points ??= [];
+    graphics.lines ??= [];
+    const outlines = constructOutlinesFromPackedComponents(
+      this.packedComponents ?? [],
+      {
+        minGap: this.packInput.minGap
+      }
+    );
+    graphics.lines.push(
+      ...outlines.flatMap(
+        (outline) => outline.map(
+          ([p1, p2]) => ({
+            points: [p1, p2],
+            stroke: "#ff4444"
+          })
+        )
+      )
+    );
+    if (this.lastBestPointsResult) {
+      for (const bestPoint of this.lastBestPointsResult.bestPoints) {
+        graphics.points.push({
+          x: bestPoint.x,
+          y: bestPoint.y,
+          label: `bestPoint
+networkId: ${bestPoint.networkId}
+d=${this.lastBestPointsResult.distance}`
+        });
+      }
+    }
+    return graphics;
+  }
+  getResult() {
+    return this.packedComponents;
+  }
+};
+
+// lib/pack.ts
+var pack = (input) => {
+  console.log("pack", input);
+  const solver = new PackSolver(input);
+  solver.solve();
+  return {
+    ...input,
+    components: solver.packedComponents
+  };
+};
+
+// lib/testing/convertCircuitJsonToPackOutput.ts
+import { cju } from "@tscircuit/circuit-json-util";
+var convertCircuitJsonToPackOutput = (circuitJson) => {
+  const packOutput = {
+    components: [],
+    minGap: 0,
+    packOrderStrategy: "largest_to_smallest",
+    packPlacementStrategy: "shortest_connection_along_outline"
+  };
+  const db = cju(circuitJson);
+  const pcbComponents = db.pcb_component.list();
+  let unnamedCounter = 0;
+  const getNetworkId = (pcbPortId) => {
+    if (pcbPortId) {
+      const pcbPort = db.pcb_port.get(pcbPortId);
+      if (pcbPort) {
+        const sourcePort = db.source_port.get(pcbPort.source_port_id);
+        if (sourcePort?.subcircuit_connectivity_map_key) {
+          return sourcePort.subcircuit_connectivity_map_key;
+        }
+      }
+    }
+    return `unnamed${unnamedCounter++}`;
+  };
+  for (const pcbComponent of pcbComponents) {
+    const pads = [];
+    const platedHoles = db.pcb_plated_hole.list({
+      pcb_component_id: pcbComponent.pcb_component_id
+    });
+    for (const platedHole of platedHoles) {
+      const sx = platedHole.rect_pad_width ?? platedHole.outer_diameter ?? platedHole.hole_diameter ?? 0;
+      const sy = platedHole.rect_pad_height ?? platedHole.outer_diameter ?? platedHole.hole_diameter ?? 0;
+      const networkId = getNetworkId(platedHole.pcb_port_id);
+      const pad = {
+        padId: platedHole.pcb_plated_hole_id,
+        networkId,
+        type: "rect",
+        offset: {
+          x: platedHole.x - pcbComponent.center.x,
+          y: platedHole.y - pcbComponent.center.y
+        },
+        size: { x: sx, y: sy },
+        absoluteCenter: {
+          x: platedHole.x,
+          y: platedHole.y
+        }
+      };
+      pads.push(pad);
+    }
+    const smtPads = db.pcb_smtpad.list({
+      pcb_component_id: pcbComponent.pcb_component_id
+    });
+    for (const smtPad of smtPads) {
+      if (smtPad.shape === "polygon") {
+        throw new Error("Polygon pads are not supported in pack layout yet");
+      }
+      const networkId = getNetworkId(smtPad.pcb_port_id);
+      const pad = {
+        padId: smtPad.pcb_smtpad_id,
+        networkId,
+        type: "rect",
+        offset: {
+          x: smtPad.x - pcbComponent.center.x,
+          y: smtPad.y - pcbComponent.center.y
+        },
+        size: {
+          x: smtPad.width ?? 0,
+          y: smtPad.height ?? 0
+        },
+        absoluteCenter: {
+          x: smtPad.x,
+          y: smtPad.y
+        }
+      };
+      pads.push(pad);
+    }
+    const packedComponent = {
+      componentId: pcbComponent.pcb_component_id,
+      pads,
+      center: {
+        x: pcbComponent.center.x,
+        y: pcbComponent.center.y
+      },
+      ccwRotationOffset: 0
+    };
+    packOutput.components.push(packedComponent);
+  }
+  return packOutput;
+};
+
+// lib/plumbing/convertPackOutputToPackInput.ts
+var convertPackOutputToPackInput = (packed) => {
+  const strippedComponents = packed.components.map((pc) => ({
+    componentId: pc.componentId,
+    pads: pc.pads.map(({ absoluteCenter: _ac, ...rest }) => rest)
+  }));
+  return {
+    ...packed,
+    // overwrite the components field with strippedComponents
+    components: strippedComponents
+  };
+};
+export {
+  PackSolver,
+  convertCircuitJsonToPackOutput,
+  convertPackOutputToPackInput,
+  getGraphicsFromPackOutput,
+  pack
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "calculate-packing",
+  "main": "dist/index.js",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Calculate a packing layout with support for different strategy configurations",
+  "scripts": {
+    "start": "cosmos",
+    "format": "biome format --write .",
+    "build": "tsup-node lib/index.ts --format esm --dts --outDir dist",
+    "build:site": "cosmos-export"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "^2.1.1",
+    "@flatten-js/core": "^1.6.2",
+    "@react-hook/resize-observer": "^2.0.2",
+    "@tscircuit/circuit-json-util": "^0.0.52",
+    "@tscircuit/footprinter": "^0.0.203",
+    "@tscircuit/math-utils": "^0.0.19",
+    "@types/bun": "latest",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "bun-match-svg": "^0.0.12",
+    "circuit-json": "^0.0.220",
+    "graphics-debug": "^0.0.60",
+    "react": "^19.1.0",
+    "react-cosmos": "^7.0.0",
+    "react-cosmos-plugin-vite": "^7.0.0",
+    "react-dom": "^19.1.0",
+    "tsup": "^8.5.0",
+    "vite": "^7.0.5"
+  },
+  "peerDependencies": {
+    "typescript": "^5",
+    "@tscircuit/circuit-json-util": "*"
+  }
+}