@tscircuit/schematic-trace-solver 0.0.45 → 0.0.47

package/lib/solvers/TraceLabelOverlapAvoidanceSolver/TraceLabelOverlapAvoidanceSolver.ts

@@ -7,6 +7,7 @@ import type { InputProblem } from "../../types/InputProblem"
 import { MergedNetLabelObstacleSolver } from "./sub-solvers/LabelMergingSolver/LabelMergingSolver"
 import { getColorFromString } from "lib/utils/getColorFromString"
 import { OverlapAvoidanceStepSolver } from "./sub-solvers/OverlapAvoidanceStepSolver/OverlapAvoidanceStepSolver"
+import { detectTraceLabelOverlap } from "./detectTraceLabelOverlap"
 
 interface TraceLabelOverlapAvoidanceSolverInput {
   inputProblem: InputProblem
@@ -15,73 +16,110 @@ interface TraceLabelOverlapAvoidanceSolverInput {
 }
 
 /**
- * This solver is a pipeline that runs a series of sub-solvers to resolve
- * trace-label overlaps and clean up the resulting traces.
+ * Resolves overlaps between schematic traces and net labels using a two-phase,
+ * "fire-and-forget" dispatching strategy.
+ *
+ * This solver operates in two distinct phases:
+ *
+ * 1.  **Dispatch Phase**: Iterates through traces, identifying clean ones and dispatching
+ *     colliding ones to dedicated `OverlapAvoidanceStepSolver` instances.
+ *
+ * 2.  **Execution Phase**: Steps through all dispatched sub-solvers until they complete.
+ *
+ * The final output combines clean traces with results from sub-solvers. A final
+ * `MergedNetLabelObstacleSolver` ensures pipeline compatibility.
  */
 export class TraceLabelOverlapAvoidanceSolver extends BaseSolver {
   inputProblem: InputProblem
-  traces: SolvedTracePath[]
   netLabelPlacements: NetLabelPlacement[]
 
-  // sub-solver instances
+  unprocessedTraces: SolvedTracePath[] = []
+  cleanTraces: SolvedTracePath[] = []
+  subSolvers: OverlapAvoidanceStepSolver[] = []
+  private phase: "searching_for_overlaps" | "fixing_overlaps" =
+    "searching_for_overlaps"
+  detourCounts: Map<string, number> = new Map()
+
   labelMergingSolver?: MergedNetLabelObstacleSolver
-  overlapAvoidanceSolver?: OverlapAvoidanceStepSolver
-  pipelineStepIndex = 0
 
   constructor(solverInput: TraceLabelOverlapAvoidanceSolverInput) {
     super()
     this.inputProblem = solverInput.inputProblem
-    this.traces = solverInput.traces
+    this.unprocessedTraces = [...solverInput.traces]
     this.netLabelPlacements = solverInput.netLabelPlacements
+    this.cleanTraces = []
+    this.subSolvers = []
   }
 
   override _step() {
-    // If a sub-solver is active, step it and check for completion.
-    if (this.activeSubSolver) {
-      this.activeSubSolver.step()
-
-      if (this.activeSubSolver.solved) {
-        this.activeSubSolver = null
-        this.pipelineStepIndex++
-      } else if (this.activeSubSolver.failed) {
-        this.failed = true // If any sub-solver fails, the whole thing fails
-        this.activeSubSolver = null
+    if (this.phase === "searching_for_overlaps") {
+      if (this.unprocessedTraces.length === 0) {
+        console.log(
+          `Dispatch phase complete. Created ${this.subSolvers.length} sub-solvers.`,
+        )
+        this.phase = "fixing_overlaps"
+        return
       }
-      return // Return to allow the sub-solver to run
-    }
 
-    // If no sub-solver is active, create the next one in the pipeline.
-    switch (this.pipelineStepIndex) {
-      case 0:
-        this.labelMergingSolver = new MergedNetLabelObstacleSolver({
-          netLabelPlacements: this.netLabelPlacements,
+      const currentTargetTrace = this.unprocessedTraces.shift()!
+
+      const localOverlaps = detectTraceLabelOverlap({
+        traces: [currentTargetTrace],
+        netLabels: this.netLabelPlacements,
+      })
+
+      if (localOverlaps.length === 0) {
+        this.cleanTraces.push(currentTargetTrace)
+      } else {
+        // Dispatch a new sub-solver for this dirty trace
+        const collidingLabels = localOverlaps.map((o) => o.label)
+        const labelMerger = new MergedNetLabelObstacleSolver({
+          netLabelPlacements: collidingLabels,
           inputProblem: this.inputProblem,
-          traces: this.traces,
+          traces: [currentTargetTrace],
         })
-        this.activeSubSolver = this.labelMergingSolver
-        break
+        labelMerger.solve()
+        const mergingOutput = labelMerger.getOutput()
 
-      case 1:
-        this.overlapAvoidanceSolver = new OverlapAvoidanceStepSolver({
+        const subSolver = new OverlapAvoidanceStepSolver({
           inputProblem: this.inputProblem,
-          traces: this.traces,
-          netLabelPlacements:
-            this.labelMergingSolver!.getOutput().netLabelPlacements,
-          mergedLabelNetIdMap:
-            this.labelMergingSolver!.getOutput().mergedLabelNetIdMap,
+          traces: [currentTargetTrace],
+          initialNetLabelPlacements: this.netLabelPlacements,
+          mergedNetLabelPlacements: mergingOutput.netLabelPlacements,
+          mergedLabelNetIdMap: mergingOutput.mergedLabelNetIdMap,
+          detourCounts: this.detourCounts,
         })
-        this.activeSubSolver = this.overlapAvoidanceSolver
-        break
-
-      default:
+        this.subSolvers.push(subSolver)
+      }
+    } else if (this.phase === "fixing_overlaps") {
+      if (this.subSolvers.every((s) => s.solved || s.failed)) {
+        console.log("All sub-solvers finished.")
+        // Final merge for pipeline compatibility
+        if (!this.labelMergingSolver) {
+          this.labelMergingSolver = new MergedNetLabelObstacleSolver({
+            netLabelPlacements: this.netLabelPlacements,
+            inputProblem: this.inputProblem,
+            traces: this.getOutput().traces,
+          })
+          this.labelMergingSolver.solve()
+        }
         this.solved = true
-        break
+        return
+      }
+
+      // Step through all active sub-solvers
+      for (const solver of this.subSolvers) {
+        if (!solver.solved && !solver.failed) {
+          solver.step()
+        }
+      }
     }
   }
 
   getOutput() {
+    const solvedTraces = this.subSolvers.flatMap((s) => s.getOutput().allTraces)
     return {
-      traces: this.overlapAvoidanceSolver?.getOutput().allTraces ?? this.traces,
+      traces: [...this.cleanTraces, ...solvedTraces],
       netLabelPlacements:
         this.labelMergingSolver?.getOutput().netLabelPlacements ??
         this.netLabelPlacements,
@@ -89,26 +127,30 @@ export class TraceLabelOverlapAvoidanceSolver extends BaseSolver {
   }
 
   override visualize(): GraphicsObject {
-    if (this.activeSubSolver) {
-      return this.activeSubSolver.visualize()
-    }
-
-    // When no sub-solver is active, show the current state of the pipeline
     const graphics = visualizeInputProblem(this.inputProblem)
     if (!graphics.lines) graphics.lines = []
     if (!graphics.rects) graphics.rects = []
 
-    const output = this.getOutput()
-
-    for (const trace of output.traces) {
+    // Show clean traces in purple
+    for (const trace of this.cleanTraces) {
       graphics.lines!.push({
         points: trace.tracePath,
         strokeColor: "purple",
       })
     }
 
-    for (const label of output.netLabelPlacements) {
-      const color = getColorFromString(label.globalConnNetId, 0.3)
+    // Delegate visualization to sub-solvers
+    for (const solver of this.subSolvers) {
+      const solverGraphics = solver.visualize()
+      graphics.lines!.push(...(solverGraphics.lines ?? []))
+      graphics.rects!.push(...(solverGraphics.rects ?? []))
+      // graphics.texts!.push(...(solverGraphics.texts ?? []))
+      graphics.points!.push(...(solverGraphics.points ?? []))
+    }
+
+    // Also show original labels
+    for (const label of this.netLabelPlacements) {
+      const color = getColorFromString(label.globalConnNetId, 0.3) // Make fill opaque
       graphics.rects!.push({
         center: label.center,
         width: label.width,

package/lib/solvers/TraceLabelOverlapAvoidanceSolver/detectTraceLabelOverlap.ts

@@ -8,28 +8,43 @@ export interface TraceLabelOverlap {
   label: NetLabelPlacement
 }
 
-export const detectTraceLabelOverlap = (
-  traces: SolvedTracePath[],
-  netLabels: NetLabelPlacement[],
-): TraceLabelOverlap[] => {
+/**
+ * Detects overlaps between a set of traces and a set of net labels.
+ * It identifies instances where a trace segment intersects with a label's bounding box.
+ * Self-attachments (where a trace and label belong to the same net) are explicitly ignored
+ * as they are not considered true overlaps for avoidance purposes.
+ *
+ * @param traces - An array of SolvedTracePath objects to check for overlaps.
+ * @param netLabels - An array of NetLabelPlacement objects representing the labels.
+ * @returns An array of TraceLabelOverlap objects, each indicating an overlap
+ *          between a trace and a label.
+ */
+export const detectTraceLabelOverlap = ({
+  traces,
+  netLabels = [],
+}: {
+  traces: SolvedTracePath[]
+  netLabels?: NetLabelPlacement[]
+}): TraceLabelOverlap[] => {
   const overlaps: TraceLabelOverlap[] = []
 
   for (const trace of traces) {
     for (const label of netLabels) {
       const labelBounds = getRectBounds(label.center, label.width, label.height)
 
-      for (let i = 0; i < trace.tracePath.length - 1; i++) {
-        const p1 = trace.tracePath[i]
-        const p2 = trace.tracePath[i + 1]
+      for (let j = 0; j < trace.tracePath.length - 1; j++) {
+        const p1 = trace.tracePath[j]
+        const p2 = trace.tracePath[j + 1]
 
         if (segmentIntersectsRect(p1, p2, labelBounds)) {
-          // Check if the trace and label belong to the same net.
-          // If so, it's a self-attachment, not a collision.
+          // If the trace and label belong to the same net, it's a legitimate connection, not an overlap to avoid.
+          // This check is now redundant with the new logic in OverlapAvoidanceStepSolver,
+          // but kept here for now as per instruction not to remove anything unnecessary.
           if (trace.globalConnNetId === label.globalConnNetId) {
-            break // Move to the next label
+            break // Break from the inner-most loop (segment loop)
           }
           overlaps.push({ trace, label })
-          break // Move to the next label
+          break // Break from the inner-most loop (segment loop)
         }
       }
     }

package/lib/solvers/TraceLabelOverlapAvoidanceSolver/rerouteCollidingTrace.ts

@@ -8,6 +8,18 @@ import { generateSnipAndReconnectCandidates } from "./trySnipAndReconnect"
 import { generateFourPointDetourCandidates } from "./tryFourPointDetour"
 import { simplifyPath } from "../TraceCleanupSolver/simplifyPath"
 
+/**
+ * Generates a list of candidate rerouted paths for a given trace that is
+ * colliding with a net label.
+ *
+ * This function employs multiple strategies to propose alternative paths:
+ * 1.  **Four-Point Detour:** Creates a rectangular detour around the label.
+ * 2.  **Snip and Reconnect:** Attempts to remove the colliding segment and
+ *     reconnect the trace around the obstacle.
+ *
+ * The candidates are generated with increasing padding based on `detourCount`
+ * to explore progressively wider detours.
+ */
 export const generateRerouteCandidates = ({
   trace,
   label,
@@ -26,13 +38,12 @@ export const generateRerouteCandidates = ({
     return [initialTrace.tracePath]
   }
 
-  const labelPadding = paddingBuffer
   const labelBoundsRaw = getRectBounds(label.center, label.width, label.height)
   const labelBounds = {
-    minX: labelBoundsRaw.minX - labelPadding,
-    minY: labelBoundsRaw.minY - labelPadding,
-    maxX: labelBoundsRaw.maxX + labelPadding,
-    maxY: labelBoundsRaw.maxY + labelPadding,
+    minX: labelBoundsRaw.minX,
+    minY: labelBoundsRaw.minY,
+    maxX: labelBoundsRaw.maxX,
+    maxY: labelBoundsRaw.maxY,
     chipId: `netlabel-${label.netId}`,
   }
 

package/lib/solvers/TraceLabelOverlapAvoidanceSolver/sub-solvers/LabelMergingSolver/LabelMergingSolver.ts

@@ -6,6 +6,9 @@ import type { GraphicsObject, Line } from "graphics-debug"
 import { getColorFromString } from "lib/utils/getColorFromString"
 import { visualizeInputProblem } from "lib/solvers/SchematicTracePipelineSolver/visualizeInputProblem"
 import type { InputProblem } from "lib/types/InputProblem"
+import { groupLabelsByChipAndOrientation } from "./groupLabelsByChipAndOrientation"
+import { mergeLabelGroup } from "./mergeLabelGroup"
+import { filterLabelsAtTraceEdges } from "./filterLabelsAtTraceEdges"
 
 interface LabelMergingSolverInput {
   netLabelPlacements: NetLabelPlacement[]
@@ -18,9 +21,15 @@ interface LabelMergingSolverOutput {
   mergedLabelNetIdMap: Record<string, Set<string>>
 }
 
+type PipelineStep =
+  | "filtering_labels"
+  | "grouping_labels"
+  | "merging_groups"
+  | "finalizing"
+
 /**
  * Merges multiple net labels into a single, larger label if they are on the
- * same side of the same chip, reducing schematic clutter.
+ * same side of the same chip and physically adjacent.
  */
 export class MergedNetLabelObstacleSolver extends BaseSolver {
   private input: LabelMergingSolverInput
@@ -28,15 +37,21 @@ export class MergedNetLabelObstacleSolver extends BaseSolver {
   private inputProblem: InputProblem
   private traces: SolvedTracePath[]
 
-  constructor(solverInput: LabelMergingSolverInput) {
-    // console.log(JSON.stringify(solverInput));
+  // State for the new pipeline
+  private pipelineStep: PipelineStep = "filtering_labels"
+  private filteredLabels: NetLabelPlacement[] = []
+  private labelGroups: Record<string, NetLabelPlacement[]> = {}
+  private groupKeysToProcess: string[] = []
+  private finalPlacements: NetLabelPlacement[] = []
+  private mergedLabelNetIdMap: Record<string, Set<string>> = {}
+  private activeMergingGroupKey: string | null = null
 
+  constructor(solverInput: LabelMergingSolverInput) {
     super()
     this.input = solverInput
     this.inputProblem = solverInput.inputProblem
     this.traces = solverInput.traces
 
-    // Initialize output to a default state to allow visualization before the first step
     this.output = {
       netLabelPlacements: solverInput.netLabelPlacements,
       mergedLabelNetIdMap: {},
@@ -44,75 +59,67 @@ export class MergedNetLabelObstacleSolver extends BaseSolver {
   }
 
   override _step() {
-    const originalLabels = this.input.netLabelPlacements
-    const mergedLabelNetIdMap: Record<string, Set<string>> = {}
-
-    if (!originalLabels || originalLabels.length === 0) {
-      this.output = {
-        netLabelPlacements: [],
-        mergedLabelNetIdMap: {},
-      }
-      this.solved = true
-      return
-    }
-
-    const labelGroups: Record<string, NetLabelPlacement[]> = {}
-
-    for (const p of originalLabels) {
-      if (p.pinIds.length === 0) continue
-      const chipId = p.pinIds[0].split(".")[0]
-      if (!chipId) continue
-      const key = `${chipId}-${p.orientation}`
-      if (!(key in labelGroups)) {
-        labelGroups[key] = []
-      }
-      labelGroups[key]!.push(p)
-    }
-
-    const finalPlacements: NetLabelPlacement[] = []
-    for (const [key, group] of Object.entries(labelGroups)) {
-      if (group.length <= 1) {
-        finalPlacements.push(...group)
-        continue
-      }
-
-      let minX = Infinity
-      let minY = Infinity
-      let maxX = -Infinity
-      let maxY = -Infinity
-      for (const p of group) {
-        const bounds = getRectBounds(p.center, p.width, p.height)
-        minX = Math.min(minX, bounds.minX)
-        minY = Math.min(minY, bounds.minY)
-        maxX = Math.max(maxX, bounds.maxX)
-        maxY = Math.max(maxY, bounds.maxY)
-      }
+    switch (this.pipelineStep) {
+      case "filtering_labels":
+        this.filteredLabels = filterLabelsAtTraceEdges({
+          labels: this.input.netLabelPlacements,
+          traces: this.traces,
+        })
+        this.pipelineStep = "grouping_labels"
+        break
 
-      const newWidth = maxX - minX
-      const newHeight = maxY - minY
-      const template = group[0]!
-      const syntheticId = `merged-group-${key}`
-      const originalNetIds = new Set(group.map((p) => p.globalConnNetId))
-      mergedLabelNetIdMap[syntheticId] = originalNetIds
-
-      finalPlacements.push({
-        ...template,
-        globalConnNetId: syntheticId,
-        width: newWidth,
-        height: newHeight,
-        center: { x: minX + newWidth / 2, y: minY + newHeight / 2 },
-        pinIds: [...new Set(group.flatMap((p) => p.pinIds))],
-        mspConnectionPairIds: [
-          ...new Set(group.flatMap((p) => p.mspConnectionPairIds)),
-        ],
-      })
-    }
+      case "grouping_labels":
+        this.labelGroups = groupLabelsByChipAndOrientation({
+          labels: this.filteredLabels,
+          chips: this.inputProblem.chips,
+        })
+        this.groupKeysToProcess = Object.keys(this.labelGroups)
+        this.pipelineStep = "merging_groups"
+        break
+
+      case "merging_groups":
+        if (this.groupKeysToProcess.length === 0) {
+          this.pipelineStep = "finalizing"
+          this.activeMergingGroupKey = null
+          break
+        }
 
-    this.output = {
-      netLabelPlacements: finalPlacements,
-      mergedLabelNetIdMap,
+        const groupKey = this.groupKeysToProcess.pop()!
+        this.activeMergingGroupKey = groupKey
+        const group = this.labelGroups[groupKey]!
+
+        if (group.length > 1) {
+          const { mergedLabel, originalNetIds } = mergeLabelGroup(
+            group,
+            groupKey,
+          )
+          this.finalPlacements.push(mergedLabel)
+          this.mergedLabelNetIdMap[mergedLabel.globalConnNetId] = originalNetIds
+        } else {
+          this.finalPlacements.push(...group)
+        }
+        break
+
+      case "finalizing":
+        // Any labels that were filtered out and not part of any group should be added back
+        const processedOriginalIds = new Set(
+          this.finalPlacements.flatMap((p) =>
+            this.mergedLabelNetIdMap[p.globalConnNetId]
+              ? [...this.mergedLabelNetIdMap[p.globalConnNetId]!]
+              : [p.globalConnNetId],
+          ),
+        )
+        const unprocessedLabels = this.input.netLabelPlacements.filter(
+          (l) => !processedOriginalIds.has(l.globalConnNetId),
+        )
+
+        this.output = {
+          netLabelPlacements: [...this.finalPlacements, ...unprocessedLabels],
+          mergedLabelNetIdMap: this.mergedLabelNetIdMap,
+        }
+        this.solved = true
+        break
     }
-    this.solved = true
   }
 
   getOutput(): LabelMergingSolverOutput {
@@ -143,17 +150,33 @@ export class MergedNetLabelObstacleSolver extends BaseSolver {
       graphics.lines!.push(line)
     }
 
+    // Highlight the active sub-group being merged
+    if (
+      this.activeMergingGroupKey &&
+      this.labelGroups[this.activeMergingGroupKey]
+    ) {
+      const activeGroup = this.labelGroups[this.activeMergingGroupKey]!
+      for (const label of activeGroup) {
+        graphics.rects.push({
+          center: label.center,
+          width: label.width,
+          height: label.height,
+          fill: "rgba(255, 165, 0, 0.5)", // Orange highlight
+          stroke: "orange",
+        })
+      }
+    }
+
     for (const finalLabel of this.output.netLabelPlacements) {
       const isMerged = finalLabel.globalConnNetId.startsWith("merged-group-")
       const color = getColorFromString(finalLabel.globalConnNetId)
 
       if (isMerged) {
-        // Draw the new merged label
         graphics.rects.push({
           center: finalLabel.center,
           width: finalLabel.width,
           height: finalLabel.height,
-          fill: color.replace(/, 1\)/, ", 0.2)"), // semi-transparent
+          fill: color.replace(/, 1\)/, ", 0.2)"),
           stroke: color,
           label: finalLabel.globalConnNetId,
         })
@@ -164,7 +187,6 @@ export class MergedNetLabelObstacleSolver extends BaseSolver {
           for (const originalNetId of originalNetIds) {
             const originalLabel = originalLabelsById.get(originalNetId)
             if (originalLabel) {
-              // Draw the original label as a dashed box
               const bounds = getRectBounds(
                 originalLabel.center,
                 originalLabel.width,
@@ -179,7 +201,6 @@ export class MergedNetLabelObstacleSolver extends BaseSolver {
                 strokeColor: color,
                 strokeDash: "4 4",
               })
-              // Draw line from original to new center
               graphics.lines.push({
                 points: [originalLabel.center, finalLabel.center],
                 strokeColor: color,
@@ -189,7 +210,6 @@ export class MergedNetLabelObstacleSolver extends BaseSolver {
           }
         }
       } else {
-        // Draw un-merged labels
         graphics.rects.push({
           center: finalLabel.center,
           width: finalLabel.width,

package/lib/solvers/TraceLabelOverlapAvoidanceSolver/sub-solvers/LabelMergingSolver/filterLabelsAtTraceEdges.ts

@@ -0,0 +1,74 @@
+import type { NetLabelPlacement } from "../../../NetLabelPlacementSolver/NetLabelPlacementSolver"
+import type { SolvedTracePath } from "../../../SchematicTraceLinesSolver/SchematicTraceLinesSolver"
+import type { Point } from "graphics-debug"
+import { distance } from "@tscircuit/math-utils"
+
+/**
+ * Filters a list of labels, returning only those that are physically located
+ * near the start or end point of any trace.
+ *
+ * This is hack so we do not need to know the position of ports
+ * and using only the trace geometry. we find out which labels are
+ * at/near port of chips and only keep those for merging.
+ */
+export const filterLabelsAtTraceEdges = ({
+  labels,
+  traces,
+  distanceThreshold = 0.5, // Example threshold
+}: {
+  labels: NetLabelPlacement[]
+  traces: SolvedTracePath[]
+  distanceThreshold?: number
+}): NetLabelPlacement[] => {
+  // 1. Group traces by their net ID for efficient lookup
+  const tracesByNetId = new Map<string, SolvedTracePath[]>()
+  if (!traces) {
+    throw new Error("No traces provided to filterLabelsAtTraceEdges")
+  }
+  for (const trace of traces) {
+    if (!trace.globalConnNetId) continue
+    if (!tracesByNetId.has(trace.globalConnNetId)) {
+      tracesByNetId.set(trace.globalConnNetId, [])
+    }
+    tracesByNetId.get(trace.globalConnNetId)!.push(trace)
+  }
+
+  const filteredLabels: NetLabelPlacement[] = []
+
+  // 2. Iterate through labels and check proximity against only relevant traces
+  for (const label of labels) {
+    // Check if it's a port-only label (no associated MSP connection pairs)
+    if (label.mspConnectionPairIds.length === 0) {
+      filteredLabels.push(label)
+      continue // Skip trace-edge checks for port-only labels
+    }
+
+    const relevantTraces = tracesByNetId.get(label.globalConnNetId)
+    let isNearTraceEdge = false
+
+    if (!relevantTraces || relevantTraces.length === 0) {
+      continue
+    }
+
+    for (const trace of relevantTraces) {
+      if (trace.tracePath.length === 0) continue
+
+      const startPoint = trace.tracePath[0]
+      const endPoint = trace.tracePath[trace.tracePath.length - 1]
+
+      const startDist = distance(label.center, startPoint)
+      const endDist = distance(label.center, endPoint)
+
+      if (startDist <= distanceThreshold || endDist <= distanceThreshold) {
+        isNearTraceEdge = true
+        break // Found a nearby edge, no need to check other traces for this label
+      }
+    }
+
+    if (isNearTraceEdge) {
+      filteredLabels.push(label)
+    }
+  }
+
+  return filteredLabels
+}

package/lib/solvers/TraceLabelOverlapAvoidanceSolver/sub-solvers/LabelMergingSolver/groupLabelsByChipAndOrientation.ts

@@ -0,0 +1,45 @@
+import type { NetLabelPlacement } from "../../../NetLabelPlacementSolver/NetLabelPlacementSolver"
+import type { InputProblem } from "lib/types/InputProblem"
+
+/**
+ * Groups NetLabelPlacement objects by their associated chip ID and orientation.
+ * Labels are grouped if they belong to the same chip and are positioned
+ * with the same orientation relative to that chip.
+ *
+ * @param labels An array of NetLabelPlacement objects to be grouped.
+ * @param chips An array of Chip objects from the InputProblem. (Currently not directly used for grouping logic, but part of the signature).
+ * @returns A record where keys are in the format "chipId-orientation" (e.g., "U1-left")
+ *          and values are arrays of NetLabelPlacement objects belonging to that group.
+ */
+export const groupLabelsByChipAndOrientation = ({
+  labels,
+  chips,
+}: {
+  labels: NetLabelPlacement[]
+  chips: InputProblem["chips"]
+}): Record<string, NetLabelPlacement[]> => {
+  const groupedLabels: Record<string, NetLabelPlacement[]> = {}
+
+  for (const label of labels) {
+    if (label.pinIds.length === 0) {
+      // Labels without pinIds cannot be associated with a chip and orientation for merging
+      continue
+    }
+
+    // Extract chipId from the first pinId (e.g., "U1.1" -> "U1")
+    const chipId = label.pinIds[0].split(".")[0]
+    if (!chipId) {
+      // Should not happen if pinIds are well-formed, but good to guard
+      continue
+    }
+
+    const key = `${chipId}-${label.orientation}`
+
+    if (!groupedLabels[key]) {
+      groupedLabels[key] = []
+    }
+    groupedLabels[key].push(label)
+  }
+
+  return groupedLabels
+}