@tscircuit/schematic-trace-solver 0.0.148 → 0.0.150

package/.agents/skills/schematic-trace-visualization/SKILL.md

@@ -48,7 +48,8 @@ const png = await getPngBufferFromGraphicsObject(graphics, {
 
 ## Existing Repo Helpers
 
-- `tests/fixtures/matcher.ts`: `expect(solver).toMatchSolverSnapshot(import.meta.path)` converts `solver.visualize()` to SVG and snapshots it.
+- `tests/fixtures/matcher.ts`: `expect(solver).toMatchSolverSnapshot(import.meta.path)` converts the solver's semantic output to Circuit JSON and renders it with `circuit-to-svg`. These snapshots hide the input rats nest by default.
+- `tests/fixtures/convertSolverOutputToCircuitJson.ts`: builds snapshot Circuit JSON with schematic components/symbols, ports, routed traces, net labels, text, and boxes.
 - `tests/fixtures/getLastStepGraphicsObject.ts`: filters a `GraphicsObject` to its highest numbered `step`.
 - `tests/fixtures/getLastStepSvg.ts`: converts only the last step to SVG.
 - `lib/testing/PipelineStageDebugRunner.ts`: runs `SchematicTracePipelineSolver` and writes per-stage PNG/SVG/graphics JSON artifacts.
@@ -56,7 +57,8 @@ const png = await getPngBufferFromGraphicsObject(graphics, {
 
 ## Minimal SVG Tests
 
-Prefer focused solver SVG snapshots over broad dumps:
+Prefer focused solver SVG snapshots over broad dumps. Solver snapshots use the
+semantic Circuit JSON renderer by default:
 
 ```ts
 const solver = new SchematicTracePipelineSolver(inputProblem as any)
@@ -64,6 +66,9 @@ solver.solve()
 expect(solver).toMatchSolverSnapshot(import.meta.path)
 ```
 
+Use `solver.visualize()` with `getSvgFromGraphicsObject` directly when a test is
+specifically about internal candidates, failed geometry, or staged debug state.
+
 For multi-step graphics where only the final stage matters:
 
 ```ts

package/dist/index.d.ts

@@ -75,6 +75,13 @@ interface TextBoxes {
 }
 interface InputChip {
     chipId: ChipId;
+    /**
+     * Exact directional/oriented schematic-symbol name when the caller has it.
+     * `center`, `width`, and `height` describe the solver obstacle and may be
+     * expanded to include reference/value or manufacturer-part-number text, so
+     * renderers should use this symbol's geometry for the component body.
+     */
+    symbolName?: string;
     center: {
         x: number;
         y: number;
@@ -87,6 +94,13 @@ interface InputChip {
 interface InputDirectConnection {
     pinIds: [PinId, PinId];
     netId?: string;
+    /**
+     * User-facing text to render for this net label. `netId` remains the stable
+     * connectivity identifier and may be an internal id. When this is omitted
+     * but a label width is provided, renderers should use a width-preserving
+     * placeholder instead of exposing `netId` as label text.
+     */
+    netLabelText?: string;
     netLabelWidth?: number;
     /**
      * Width of the conventional anchored label to use only when an inline label
@@ -109,7 +123,8 @@ interface InputDirectConnection {
     allowInlineNetLabel?: boolean;
     /**
      * Extent of the inline net label along the trace. Falls back to
-     * `netLabelWidth`, then to an estimate from the netId text.
+     * `netLabelWidth`, then to an estimate from `netLabelText` (or `netId` for
+     * backwards compatibility).
      */
     inlineNetLabelWidth?: number;
     /**
@@ -121,6 +136,13 @@ interface InputDirectConnection {
 interface InputNetConnection {
     netId: string;
     pinIds: Array<PinId>;
+    /**
+     * User-facing text to render for this net label. `netId` remains the stable
+     * connectivity identifier and may be an internal id. When this is omitted
+     * but a label width is provided, renderers should use a width-preserving
+     * placeholder instead of exposing `netId` as label text.
+     */
+    netLabelText?: string;
     netLabelWidth?: number;
     fallbackNetLabelWidth?: number;
     netLabelHeight?: number;
@@ -425,6 +447,7 @@ declare class SingleNetLabelPlacementSolver extends BaseSolver {
 type OverlappingSameNetTraceGroup = {
     globalConnNetId: string;
     netId?: string;
+    netLabelText?: string;
     overlappingTraces?: SolvedTracePath;
     portOnlyPinId?: string;
     mspConnectionPairIds?: MspConnectionPairId[];
@@ -436,6 +459,8 @@ interface NetLabelPlacement {
      * Optional user-provided net identifier (if present in the input problem).
      */
     netId?: string;
+    /** User-facing label content, separate from the connectivity identifier. */
+    netLabelText?: string;
     /**
      * MSP pair ids that the label is associated with. Port-only labels use [].
      */
@@ -1186,6 +1211,8 @@ declare const DEFAULT_INLINE_NET_LABEL_HEIGHT = 0.18;
  * Gap between the trace and the near edge of the inline label text.
  */
 declare const INLINE_NET_LABEL_TRACE_MARGIN = 0.05;
+/** Clearance between a generated terminal stub and an unrelated trace. */
+declare const INLINE_NET_LABEL_STUB_TRACE_CLEARANCE = 0.05;
 /**
  * Largest perpendicular deviation a route may have and still be labeled as one
  * span. A route that is straight except for elbow jogs up to this size reads
@@ -1207,6 +1234,8 @@ declare const INLINE_NET_LABEL_MAX_SPAN_JOG = 0.4;
 interface InlineNetLabelPlacement {
     globalConnNetId: string;
     netId?: string;
+    /** User-facing label content, separate from the connectivity identifier. */
+    netLabelText?: string;
     mspPairId?: string;
     pinIds: PinId[];
     /**
@@ -1361,4 +1390,4 @@ declare class SchematicTracePipelineSolver extends BaseSolver {
     preview(): GraphicsObject;
 }
 
-export { type ChipId, DEFAULT_INLINE_NET_LABEL_HEIGHT, INLINE_NET_LABEL_MAX_SPAN_JOG, INLINE_NET_LABEL_TRACE_MARGIN, type InlineNetLabelPlacement, InlineNetLabelSolver, type InputChip, type InputDirectConnection, type InputNetConnection, type InputPin, type InputProblem, type NetId, type NetLabelPlacement, type PinId, SchematicTracePipelineSolver, SchematicTraceSingleLineSolver2, type SectionId, type TextBoxes, estimateInlineNetLabelWidth };
+export { type ChipId, DEFAULT_INLINE_NET_LABEL_HEIGHT, INLINE_NET_LABEL_MAX_SPAN_JOG, INLINE_NET_LABEL_STUB_TRACE_CLEARANCE, INLINE_NET_LABEL_TRACE_MARGIN, type InlineNetLabelPlacement, InlineNetLabelSolver, type InputChip, type InputDirectConnection, type InputNetConnection, type InputPin, type InputProblem, type NetId, type NetLabelPlacement, type PinId, SchematicTracePipelineSolver, SchematicTraceSingleLineSolver2, type SectionId, type TextBoxes, estimateInlineNetLabelWidth };

package/dist/index.js

@@ -2742,6 +2742,7 @@ function solveNetLabelPlacementForPortOnlyPin(params) {
       globalConnNetId: overlappingSameNetTraceGroup.globalConnNetId,
       dcConnNetId: void 0,
       netId: overlappingSameNetTraceGroup.netId,
+      netLabelText: overlappingSameNetTraceGroup.netLabelText,
       mspConnectionPairIds: [],
       pinIds: [pinId],
       orientation,
@@ -2773,6 +2774,7 @@ function solveNetLabelPlacementForPortOnlyPin(params) {
     globalConnNetId: overlappingSameNetTraceGroup.globalConnNetId,
     dcConnNetId: void 0,
     netId: overlappingSameNetTraceGroup.netId,
+    netLabelText: overlappingSameNetTraceGroup.netLabelText,
     mspConnectionPairIds: [],
     pinIds: [pinId],
     orientation: fallbackOrientation,
@@ -3059,6 +3061,7 @@ var SingleNetLabelPlacementSolver = class extends BaseSolver {
               globalConnNetId: this.overlappingSameNetTraceGroup.globalConnNetId,
               dcConnNetId: curr.dcConnNetId,
               netId: this.overlappingSameNetTraceGroup.netId,
+              netLabelText: this.overlappingSameNetTraceGroup.netLabelText,
               mspConnectionPairIds: [curr.mspPairId],
               pinIds: [curr.pins[0].pinId, curr.pins[1].pinId],
               orientation,
@@ -3078,6 +3081,7 @@ var SingleNetLabelPlacementSolver = class extends BaseSolver {
         globalConnNetId: this.overlappingSameNetTraceGroup.globalConnNetId,
         dcConnNetId: bestCandidate.dcConnNetId,
         netId: this.overlappingSameNetTraceGroup.netId,
+        netLabelText: this.overlappingSameNetTraceGroup.netLabelText,
         mspConnectionPairIds: [bestCandidate.mspPairId],
         pinIds: bestCandidate.pinIds,
         orientation: bestCandidate.orientation,
@@ -3133,16 +3137,25 @@ var NetLabelPlacementSolver = class extends BaseSolver {
       }
     }
     const userNetIdByPinId = {};
+    const netLabelTextByPinId = {};
     for (const dc of this.inputProblem.directConnections) {
       if (dc.netId) {
         const [a, b] = dc.pinIds;
         userNetIdByPinId[a] = dc.netId;
         userNetIdByPinId[b] = dc.netId;
       }
+      const netLabelText = dc.netLabelText?.trim();
+      if (netLabelText) {
+        const [a, b] = dc.pinIds;
+        netLabelTextByPinId[a] = netLabelText;
+        netLabelTextByPinId[b] = netLabelText;
+      }
     }
     for (const nc of this.inputProblem.netConnections) {
       for (const pid of nc.pinIds) {
         userNetIdByPinId[pid] = nc.netId;
+        const netLabelText = nc.netLabelText?.trim();
+        if (netLabelText) netLabelTextByPinId[pid] = netLabelText;
       }
     }
     const groups = [];
@@ -3228,6 +3241,7 @@ var NetLabelPlacementSolver = class extends BaseSolver {
           const group = {
             globalConnNetId,
             netId: userNetId,
+            netLabelText: [...component].map((pinId) => netLabelTextByPinId[pinId]).find((text) => Boolean(text)),
             overlappingTraces: rep,
             mspConnectionPairIds
           };
@@ -3239,6 +3253,7 @@ var NetLabelPlacementSolver = class extends BaseSolver {
             groups.push({
               globalConnNetId,
               netId: userNetId,
+              netLabelText: netLabelTextByPinId[p],
               portOnlyPinId: p
             });
           }
@@ -12678,47 +12693,6 @@ var TraceElbowTransitionSimplificationSolver = class extends BaseSolver {
   }
 };
 
-// lib/solvers/InlineNetLabelSolver/getAxisAlignedSegments.ts
-var getAxisAlignedSegments = (path, epsilon = 1e-6) => {
-  const segments = [];
-  let runStart = null;
-  let runAxis = null;
-  let runSign = 0;
-  const closeRun = (runEnd) => {
-    if (runStart && runAxis) {
-      const length = runAxis === "x" ? Math.abs(runEnd.x - runStart.x) : Math.abs(runEnd.y - runStart.y);
-      if (length > epsilon) {
-        segments.push({ start: runStart, end: runEnd, axis: runAxis, length });
-      }
-    }
-    runStart = null;
-    runAxis = null;
-    runSign = 0;
-  };
-  for (let i = 0; i < path.length - 1; i++) {
-    const a = path[i];
-    const b = path[i + 1];
-    const dx = b.x - a.x;
-    const dy = b.y - a.y;
-    if (Math.abs(dx) <= epsilon && Math.abs(dy) <= epsilon) continue;
-    const axis = Math.abs(dy) <= epsilon ? "x" : Math.abs(dx) <= epsilon ? "y" : null;
-    if (!axis) {
-      closeRun(a);
-      continue;
-    }
-    const sign = Math.sign(axis === "x" ? dx : dy);
-    if (runStart && runAxis === axis && runSign === sign) continue;
-    closeRun(a);
-    runStart = a;
-    runAxis = axis;
-    runSign = sign;
-  }
-  if (path.length >= 2) {
-    closeRun(path[path.length - 1]);
-  }
-  return segments.sort((a, b) => b.length - a.length);
-};
-
 // lib/solvers/InlineNetLabelSolver/alignPortOnlyInlineNetLabelStubs.ts
 var getStubDirection = (path) => {
   const [start, end] = path;
@@ -12867,6 +12841,47 @@ var alignPortOnlyInlineNetLabelStubs = ({
   return alignedPlacements;
 };
 
+// lib/solvers/InlineNetLabelSolver/getAxisAlignedSegments.ts
+var getAxisAlignedSegments = (path, epsilon = 1e-6) => {
+  const segments = [];
+  let runStart = null;
+  let runAxis = null;
+  let runSign = 0;
+  const closeRun = (runEnd) => {
+    if (runStart && runAxis) {
+      const length = runAxis === "x" ? Math.abs(runEnd.x - runStart.x) : Math.abs(runEnd.y - runStart.y);
+      if (length > epsilon) {
+        segments.push({ start: runStart, end: runEnd, axis: runAxis, length });
+      }
+    }
+    runStart = null;
+    runAxis = null;
+    runSign = 0;
+  };
+  for (let i = 0; i < path.length - 1; i++) {
+    const a = path[i];
+    const b = path[i + 1];
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    if (Math.abs(dx) <= epsilon && Math.abs(dy) <= epsilon) continue;
+    const axis = Math.abs(dy) <= epsilon ? "x" : Math.abs(dx) <= epsilon ? "y" : null;
+    if (!axis) {
+      closeRun(a);
+      continue;
+    }
+    const sign = Math.sign(axis === "x" ? dx : dy);
+    if (runStart && runAxis === axis && runSign === sign) continue;
+    closeRun(a);
+    runStart = a;
+    runAxis = axis;
+    runSign = sign;
+  }
+  if (path.length >= 2) {
+    closeRun(path[path.length - 1]);
+  }
+  return segments.sort((a, b) => b.length - a.length);
+};
+
 // lib/solvers/InlineNetLabelSolver/pushAnchoredNetLabelsAwayFromInlineLabels.ts
 var LABEL_CLEARANCE2 = 0.05;
 var POINT_EPSILON = 1e-6;
@@ -13229,6 +13244,7 @@ var pushAnchoredNetLabelsAwayFromInlineLabels = ({
 // lib/solvers/InlineNetLabelSolver/InlineNetLabelSolver.ts
 var DEFAULT_INLINE_NET_LABEL_HEIGHT = 0.18;
 var INLINE_NET_LABEL_TRACE_MARGIN = 0.05;
+var INLINE_NET_LABEL_STUB_TRACE_CLEARANCE = 0.05;
 var INLINE_NET_LABEL_MAX_SPAN_JOG = 0.4;
 var getPinPairKey2 = (pinIds) => [...pinIds].sort().join("::");
 var InlineNetLabelSolver = class extends BaseSolver {
@@ -13325,11 +13341,20 @@ var InlineNetLabelSolver = class extends BaseSolver {
     );
     const inputPin = inputChip?.pins.find((pin) => pin.pinId === pinId);
     const height = connection.inlineNetLabelHeight ?? DEFAULT_INLINE_NET_LABEL_HEIGHT;
-    const width = connection.inlineNetLabelWidth ?? connection.netLabelWidth ?? estimateInlineNetLabelWidth(connection.netId, height);
+    const netLabelText = connection.netLabelText?.trim() || void 0;
+    const width = connection.inlineNetLabelWidth ?? connection.netLabelWidth ?? estimateInlineNetLabelWidth(netLabelText ?? connection.netId, height);
     const stubLength = Math.max(width + 0.2, 0.6);
     const start = inputPin ? { x: inputPin.x, y: inputPin.y } : anchoredPlacement.anchorPoint;
     const direction = inputPin && inputChip ? inputPin._facingDirection ?? getPinDirection(inputPin, inputChip) : anchoredPlacement.orientation;
-    const end = direction === "x+" ? { x: start.x + stubLength, y: start.y } : direction === "x-" ? { x: start.x - stubLength, y: start.y } : direction === "y+" ? { x: start.x, y: start.y + stubLength } : { x: start.x, y: start.y - stubLength };
+    const intendedEnd = direction === "x+" ? { x: start.x + stubLength, y: start.y } : direction === "x-" ? { x: start.x - stubLength, y: start.y } : direction === "y+" ? { x: start.x, y: start.y + stubLength } : { x: start.x, y: start.y - stubLength };
+    const end = getCollisionLimitedTerminalStubEnd({
+      start,
+      intendedEnd,
+      minimumLength: width + 2 * INLINE_NET_LABEL_TRACE_MARGIN,
+      traces: this.traces,
+      ownGlobalConnNetId: anchoredPlacement.globalConnNetId
+    });
+    if (!end) return null;
     const axis = direction === "x+" || direction === "x-" ? "x" : "y";
     const side = axis === "x" ? "y+" : "x-";
     const anchorPoint = {
@@ -13359,6 +13384,7 @@ var InlineNetLabelSolver = class extends BaseSolver {
     return {
       globalConnNetId: anchoredPlacement.globalConnNetId,
       netId: connection.netId,
+      netLabelText,
       pinIds: [pinId],
       stubTracePath: [start, end],
       axis,
@@ -13376,7 +13402,8 @@ var InlineNetLabelSolver = class extends BaseSolver {
     const segments = getAxisAlignedSegments(trace.tracePath);
     if (segments.length === 0) return null;
     const height = connection.inlineNetLabelHeight ?? DEFAULT_INLINE_NET_LABEL_HEIGHT;
-    const width = connection.inlineNetLabelWidth ?? connection.netLabelWidth ?? estimateInlineNetLabelWidth(connection.netId, height);
+    const netLabelText = connection.netLabelText?.trim() || void 0;
+    const width = connection.inlineNetLabelWidth ?? connection.netLabelWidth ?? estimateInlineNetLabelWidth(netLabelText ?? connection.netId, height);
     const offset = height / 2 + INLINE_NET_LABEL_TRACE_MARGIN;
     const usableSegments = segments.filter((segment) => segment.length >= width).sort((a, b) => b.length - a.length);
     for (const segment of usableSegments) {
@@ -13405,6 +13432,7 @@ var InlineNetLabelSolver = class extends BaseSolver {
           return {
             globalConnNetId: trace.globalConnNetId,
             netId: connection.netId,
+            netLabelText,
             mspPairId: trace.mspPairId,
             pinIds: [...connection.pinIds],
             axis: segment.axis,
@@ -13420,6 +13448,7 @@ var InlineNetLabelSolver = class extends BaseSolver {
     const spanPlacement = this.computeSpanPlacement({
       trace,
       connection,
+      netLabelText,
       width,
       height,
       offset
@@ -13436,6 +13465,7 @@ var InlineNetLabelSolver = class extends BaseSolver {
   computeSpanPlacement({
     trace,
     connection,
+    netLabelText,
     width,
     height,
     offset
@@ -13495,6 +13525,7 @@ var InlineNetLabelSolver = class extends BaseSolver {
         return {
           globalConnNetId: trace.globalConnNetId,
           netId: connection.netId,
+          netLabelText,
           mspPairId: trace.mspPairId,
           pinIds: [...connection.pinIds],
           axis,
@@ -13629,7 +13660,7 @@ orientation: ${label.orientation}`
       graphics.texts.push({
         x: inlineLabel.stubTracePath && inlineLabel.axis === "x" ? inlineLabel.center.x + (inlineLabel.stubTracePath[1].x > inlineLabel.stubTracePath[0].x ? -inlineLabel.width / 2 : inlineLabel.width / 2) : inlineLabel.center.x,
         y: inlineLabel.stubTracePath && inlineLabel.axis === "y" ? inlineLabel.center.y + (inlineLabel.stubTracePath[1].y > inlineLabel.stubTracePath[0].y ? -inlineLabel.width / 2 : inlineLabel.width / 2) : inlineLabel.center.y,
-        text: inlineLabel.netId ?? "",
+        text: inlineLabel.netLabelText ?? inlineLabel.netId ?? "",
         color: "green",
         fontSize: inlineLabel.height,
         anchorSide: inlineLabel.stubTracePath ? inlineLabel.stubTracePath[1][inlineLabel.axis] > inlineLabel.stubTracePath[0][inlineLabel.axis] ? "center_left" : "center_right" : "center",
@@ -13641,7 +13672,7 @@ orientation: ${label.orientation}`
         y: inlineLabel.anchorPoint.y,
         color: "green",
         label: `inline anchor
-${inlineLabel.netId}`
+${inlineLabel.netLabelText ?? inlineLabel.netId}`
       });
     }
     return graphics;
@@ -13681,6 +13712,55 @@ var doesPathIntersectBounds2 = (path, bounds) => {
   }
   return false;
 };
+var GEOMETRY_EPSILON = 1e-6;
+var getCollisionLimitedTerminalStubEnd = ({
+  start,
+  intendedEnd,
+  minimumLength,
+  traces,
+  ownGlobalConnNetId
+}) => {
+  const isHorizontal4 = Math.abs(intendedEnd.x - start.x) >= Math.abs(intendedEnd.y - start.y);
+  const alongAxis = isHorizontal4 ? "x" : "y";
+  const acrossAxis = isHorizontal4 ? "y" : "x";
+  const direction = Math.sign(intendedEnd[alongAxis] - start[alongAxis]) || 1;
+  const intendedLength = Math.abs(intendedEnd[alongAxis] - start[alongAxis]);
+  let availableLength = intendedLength;
+  for (const trace of traces) {
+    if (trace.globalConnNetId === ownGlobalConnNetId) continue;
+    for (let segmentIndex = 0; segmentIndex < trace.tracePath.length - 1; segmentIndex++) {
+      const segmentStart = trace.tracePath[segmentIndex];
+      const segmentEnd = trace.tracePath[segmentIndex + 1];
+      const startAlong = (segmentStart[alongAxis] - start[alongAxis]) * direction;
+      const endAlong = (segmentEnd[alongAxis] - start[alongAxis]) * direction;
+      const startAcross = segmentStart[acrossAxis] - start[acrossAxis];
+      const endAcross = segmentEnd[acrossAxis] - start[acrossAxis];
+      const minAlong = Math.min(startAlong, endAlong);
+      const maxAlong = Math.max(startAlong, endAlong);
+      const minAcross = Math.min(startAcross, endAcross);
+      const maxAcross = Math.max(startAcross, endAcross);
+      let collisionDistance;
+      const isCollinear = Math.abs(startAcross) <= GEOMETRY_EPSILON && Math.abs(endAcross) <= GEOMETRY_EPSILON;
+      if (isCollinear && maxAlong >= -GEOMETRY_EPSILON && minAlong <= intendedLength + GEOMETRY_EPSILON) {
+        collisionDistance = Math.max(0, minAlong);
+      } else {
+        const crossesStubAxis = minAcross <= GEOMETRY_EPSILON && maxAcross >= -GEOMETRY_EPSILON;
+        const perpendicularAlong = (startAlong + endAlong) / 2;
+        if (crossesStubAxis && Math.abs(startAlong - endAlong) <= GEOMETRY_EPSILON && perpendicularAlong >= -GEOMETRY_EPSILON && perpendicularAlong <= intendedLength + GEOMETRY_EPSILON) {
+          collisionDistance = Math.max(0, perpendicularAlong);
+        }
+      }
+      if (collisionDistance !== void 0) {
+        availableLength = Math.min(
+          availableLength,
+          collisionDistance - INLINE_NET_LABEL_STUB_TRACE_CLEARANCE
+        );
+      }
+    }
+  }
+  if (availableLength + GEOMETRY_EPSILON < minimumLength) return null;
+  return isHorizontal4 ? { x: start.x + direction * availableLength, y: start.y } : { x: start.x, y: start.y + direction * availableLength };
+};
 
 // lib/solvers/SchematicTracePipelineSolver/SchematicTracePipelineSolver.ts
 function definePipelineStep(solverName, solverClass, getConstructorParams, opts = {}) {
@@ -14246,6 +14326,7 @@ var SchematicTracePipelineSolver = class extends BaseSolver {
 export {
   DEFAULT_INLINE_NET_LABEL_HEIGHT,
   INLINE_NET_LABEL_MAX_SPAN_JOG,
+  INLINE_NET_LABEL_STUB_TRACE_CLEARANCE,
   INLINE_NET_LABEL_TRACE_MARGIN,
   InlineNetLabelSolver,
   SchematicTracePipelineSolver,

package/lib/solvers/InlineNetLabelSolver/InlineNetLabelSolver.ts

@@ -13,11 +13,11 @@ import type {
 } from "lib/types/InputProblem"
 import { getColorFromString } from "lib/utils/getColorFromString"
 import { boundsOverlap, getTextBoxBounds } from "lib/utils/textBoxBounds"
+import { alignPortOnlyInlineNetLabelStubs } from "./alignPortOnlyInlineNetLabelStubs"
 import {
   type AxisAlignedSegment,
   getAxisAlignedSegments,
 } from "./getAxisAlignedSegments"
-import { alignPortOnlyInlineNetLabelStubs } from "./alignPortOnlyInlineNetLabelStubs"
 import { pushAnchoredNetLabelsAwayFromInlineLabels } from "./pushAnchoredNetLabelsAwayFromInlineLabels"
 
 export const DEFAULT_INLINE_NET_LABEL_HEIGHT = 0.18
@@ -27,6 +27,9 @@ export const DEFAULT_INLINE_NET_LABEL_HEIGHT = 0.18
  */
 export const INLINE_NET_LABEL_TRACE_MARGIN = 0.05
 
+/** Clearance between a generated terminal stub and an unrelated trace. */
+export const INLINE_NET_LABEL_STUB_TRACE_CLEARANCE = 0.05
+
 /**
  * Largest perpendicular deviation a route may have and still be labeled as one
  * span. A route that is straight except for elbow jogs up to this size reads
@@ -49,6 +52,8 @@ export const INLINE_NET_LABEL_MAX_SPAN_JOG = 0.4
 export interface InlineNetLabelPlacement {
   globalConnNetId: string
   netId?: string
+  /** User-facing label content, separate from the connectivity identifier. */
+  netLabelText?: string
   mspPairId?: string
   pinIds: PinId[]
 
@@ -233,10 +238,11 @@ export class InlineNetLabelSolver extends BaseSolver {
 
     const height =
       connection.inlineNetLabelHeight ?? DEFAULT_INLINE_NET_LABEL_HEIGHT
+    const netLabelText = connection.netLabelText?.trim() || undefined
     const width =
       connection.inlineNetLabelWidth ??
       connection.netLabelWidth ??
-      estimateInlineNetLabelWidth(connection.netId, height)
+      estimateInlineNetLabelWidth(netLabelText ?? connection.netId, height)
 
     // Leave a small wire tail at both ends of the text so it unmistakably
     // reads as a label on a trace rather than free-standing text.
@@ -248,7 +254,7 @@ export class InlineNetLabelSolver extends BaseSolver {
       inputPin && inputChip
         ? (inputPin._facingDirection ?? getPinDirection(inputPin, inputChip))
         : anchoredPlacement.orientation
-    const end: Point =
+    const intendedEnd: Point =
       direction === "x+"
         ? { x: start.x + stubLength, y: start.y }
         : direction === "x-"
@@ -257,6 +263,15 @@ export class InlineNetLabelSolver extends BaseSolver {
             ? { x: start.x, y: start.y + stubLength }
             : { x: start.x, y: start.y - stubLength }
 
+    const end = getCollisionLimitedTerminalStubEnd({
+      start,
+      intendedEnd,
+      minimumLength: width + 2 * INLINE_NET_LABEL_TRACE_MARGIN,
+      traces: this.traces,
+      ownGlobalConnNetId: anchoredPlacement.globalConnNetId,
+    })
+    if (!end) return null
+
     const axis: InlineNetLabelPlacement["axis"] =
       direction === "x+" || direction === "x-" ? "x" : "y"
     const side: InlineNetLabelPlacement["side"] = axis === "x" ? "y+" : "x-"
@@ -298,6 +313,7 @@ export class InlineNetLabelSolver extends BaseSolver {
     return {
       globalConnNetId: anchoredPlacement.globalConnNetId,
       netId: connection.netId,
+      netLabelText,
       pinIds: [pinId],
       stubTracePath: [start, end],
       axis,
@@ -324,10 +340,11 @@ export class InlineNetLabelSolver extends BaseSolver {
 
     const height =
       connection.inlineNetLabelHeight ?? DEFAULT_INLINE_NET_LABEL_HEIGHT
+    const netLabelText = connection.netLabelText?.trim() || undefined
     const width =
       connection.inlineNetLabelWidth ??
       connection.netLabelWidth ??
-      estimateInlineNetLabelWidth(connection.netId!, height)
+      estimateInlineNetLabelWidth(netLabelText ?? connection.netId!, height)
 
     const offset = height / 2 + INLINE_NET_LABEL_TRACE_MARGIN
 
@@ -385,6 +402,7 @@ export class InlineNetLabelSolver extends BaseSolver {
           return {
             globalConnNetId: trace.globalConnNetId,
             netId: connection.netId,
+            netLabelText,
             mspPairId: trace.mspPairId,
             pinIds: [...connection.pinIds],
             axis: segment.axis,
@@ -405,6 +423,7 @@ export class InlineNetLabelSolver extends BaseSolver {
     const spanPlacement = this.computeSpanPlacement({
       trace,
       connection,
+      netLabelText,
       width,
       height,
       offset,
@@ -425,12 +444,14 @@ export class InlineNetLabelSolver extends BaseSolver {
   private computeSpanPlacement({
     trace,
     connection,
+    netLabelText,
     width,
     height,
     offset,
   }: {
     trace: SolvedTracePath
     connection: InlineEligibleConnection
+    netLabelText?: string
     width: number
     height: number
     offset: number
@@ -521,6 +542,7 @@ export class InlineNetLabelSolver extends BaseSolver {
         return {
           globalConnNetId: trace.globalConnNetId,
           netId: connection.netId,
+          netLabelText,
           mspPairId: trace.mspPairId,
           pinIds: [...connection.pinIds],
           axis,
@@ -691,7 +713,7 @@ export class InlineNetLabelSolver extends BaseSolver {
                 ? -inlineLabel.width / 2
                 : inlineLabel.width / 2)
             : inlineLabel.center.y,
-        text: inlineLabel.netId ?? "",
+        text: inlineLabel.netLabelText ?? inlineLabel.netId ?? "",
         color: "green",
         fontSize: inlineLabel.height,
         anchorSide: inlineLabel.stubTracePath
@@ -707,7 +729,7 @@ export class InlineNetLabelSolver extends BaseSolver {
         x: inlineLabel.anchorPoint.x,
         y: inlineLabel.anchorPoint.y,
         color: "green",
-        label: `inline anchor\n${inlineLabel.netId}`,
+        label: `inline anchor\n${inlineLabel.netLabelText ?? inlineLabel.netId}`,
       })
     }
 
@@ -777,3 +799,90 @@ const doesPathIntersectBounds = (path: Point[], bounds: Bounds): boolean => {
   }
   return false
 }
+
+const GEOMETRY_EPSILON = 1e-6
+
+/**
+ * Shortens an axis-aligned terminal stub before the first unrelated trace.
+ * Coordinates are schematic-world millimetres with +x right and +y up.
+ */
+const getCollisionLimitedTerminalStubEnd = ({
+  start,
+  intendedEnd,
+  minimumLength,
+  traces,
+  ownGlobalConnNetId,
+}: {
+  start: Point
+  intendedEnd: Point
+  minimumLength: number
+  traces: SolvedTracePath[]
+  ownGlobalConnNetId: string
+}): Point | null => {
+  const isHorizontal =
+    Math.abs(intendedEnd.x - start.x) >= Math.abs(intendedEnd.y - start.y)
+  const alongAxis = isHorizontal ? "x" : "y"
+  const acrossAxis = isHorizontal ? "y" : "x"
+  const direction = Math.sign(intendedEnd[alongAxis] - start[alongAxis]) || 1
+  const intendedLength = Math.abs(intendedEnd[alongAxis] - start[alongAxis])
+  let availableLength = intendedLength
+
+  for (const trace of traces) {
+    if (trace.globalConnNetId === ownGlobalConnNetId) continue
+
+    for (
+      let segmentIndex = 0;
+      segmentIndex < trace.tracePath.length - 1;
+      segmentIndex++
+    ) {
+      const segmentStart = trace.tracePath[segmentIndex]!
+      const segmentEnd = trace.tracePath[segmentIndex + 1]!
+      const startAlong =
+        (segmentStart[alongAxis] - start[alongAxis]) * direction
+      const endAlong = (segmentEnd[alongAxis] - start[alongAxis]) * direction
+      const startAcross = segmentStart[acrossAxis] - start[acrossAxis]
+      const endAcross = segmentEnd[acrossAxis] - start[acrossAxis]
+      const minAlong = Math.min(startAlong, endAlong)
+      const maxAlong = Math.max(startAlong, endAlong)
+      const minAcross = Math.min(startAcross, endAcross)
+      const maxAcross = Math.max(startAcross, endAcross)
+
+      let collisionDistance: number | undefined
+      const isCollinear =
+        Math.abs(startAcross) <= GEOMETRY_EPSILON &&
+        Math.abs(endAcross) <= GEOMETRY_EPSILON
+      if (
+        isCollinear &&
+        maxAlong >= -GEOMETRY_EPSILON &&
+        minAlong <= intendedLength + GEOMETRY_EPSILON
+      ) {
+        collisionDistance = Math.max(0, minAlong)
+      } else {
+        const crossesStubAxis =
+          minAcross <= GEOMETRY_EPSILON && maxAcross >= -GEOMETRY_EPSILON
+        const perpendicularAlong = (startAlong + endAlong) / 2
+        if (
+          crossesStubAxis &&
+          Math.abs(startAlong - endAlong) <= GEOMETRY_EPSILON &&
+          perpendicularAlong >= -GEOMETRY_EPSILON &&
+          perpendicularAlong <= intendedLength + GEOMETRY_EPSILON
+        ) {
+          collisionDistance = Math.max(0, perpendicularAlong)
+        }
+      }
+
+      if (collisionDistance !== undefined) {
+        availableLength = Math.min(
+          availableLength,
+          collisionDistance - INLINE_NET_LABEL_STUB_TRACE_CLEARANCE,
+        )
+      }
+    }
+  }
+
+  if (availableLength + GEOMETRY_EPSILON < minimumLength) return null
+
+  return isHorizontal
+    ? { x: start.x + direction * availableLength, y: start.y }
+    : { x: start.x, y: start.y + direction * availableLength }
+}