@tscircuit/schematic-trace-solver 0.0.125 → 0.0.127

package/README.md

@@ -35,6 +35,34 @@ Finally, the `NetLabelPlacementSolver` places net labels for each net connection
 this requires drawing small traces to adapt to the `availableFacingDirections` of the net connection.
 If there is crowding at the pin, we look for an available spot along the trace connected to the pin.
 
+### Inline net labels
+
+A point-to-point signal trace can be labeled *inline*: the net name is drawn
+parallel to the wire (above a horizontal trace, to the left of a vertical one)
+instead of as an anchored label hanging off the end of it. This keeps the visual
+line between the two pins intact.
+
+Inline labels are opt-in per direct connection - set `allowInlineNetLabel: true`
+on the `directConnection`. The caller (usually [@tscircuit/core](https://github.com/tscircuit/core))
+decides which connections deserve one; the solver only honors the request when
+the connection actually got routed, since there is nothing to run parallel to
+otherwise.
+
+The `InlineNetLabelSolver` runs last in the pipeline and exposes
+`inlineNetLabelPlacements`. A net that receives an inline label has its anchored
+`NetLabelPlacement` removed from `getOutput().netLabelPlacements`, so a net is
+never labeled twice.
+
+```tsx
+directConnections: [
+  {
+    pinIds: ["U1.1", "D1.1"],
+    netId: "USER_LED_ANODE",
+    allowInlineNetLabel: true,
+  },
+]
+```
+
 ## Usage
 
 ```tsx

package/dist/index.d.ts

@@ -88,6 +88,27 @@ interface InputDirectConnection {
     pinIds: [PinId, PinId];
     netId?: string;
     netLabelWidth?: number;
+    /**
+     * When true, this point-to-point connection may be labeled with an "inline
+     * net label": the net name is drawn parallel to (and offset from) the routed
+     * trace instead of being placed as a separate anchored net label at the end
+     * of the trace.
+     *
+     * Only set this for connections whose net name is worth showing on the wire -
+     * the solver trusts the caller (e.g. @tscircuit/core) to make that decision.
+     * An inline label is only emitted when the connection actually got routed.
+     */
+    allowInlineNetLabel?: boolean;
+    /**
+     * Extent of the inline net label along the trace. Falls back to
+     * `netLabelWidth`, then to an estimate from the netId text.
+     */
+    inlineNetLabelWidth?: number;
+    /**
+     * Height of the inline net label text. Defaults to
+     * DEFAULT_INLINE_NET_LABEL_HEIGHT.
+     */
+    inlineNetLabelHeight?: number;
 }
 interface InputNetConnection {
     netId: string;
@@ -441,6 +462,13 @@ declare class NetLabelPlacementSolver extends BaseSolver {
     visualize(): GraphicsObject;
 }
 
+interface CompletedTraceReroute {
+    initialTrace: SolvedTracePath;
+    reroutedTracePath: Point[];
+    label: NetLabelPlacement;
+    detourCount: number;
+}
+
 interface LabelMergingSolverInput {
     netLabelPlacements: NetLabelPlacement[];
     inputProblem: InputProblem;
@@ -479,6 +507,7 @@ interface SingleOverlapSolverInput {
     paddingBuffer: number;
     detourCount: number;
     tracesToAvoidOverlapping?: SolvedTracePath[];
+    netLabelPlacements?: NetLabelPlacement[];
 }
 /**
  * This solver attempts to find a valid rerouting for a single trace that is
@@ -493,6 +522,8 @@ declare class SingleOverlapSolver extends BaseSolver {
     obstacles: ReturnType<typeof getObstacleRects>;
     label: NetLabelPlacement;
     tracesToAvoidOverlapping: SolvedTracePath[];
+    netLabelPlacements: NetLabelPlacement[];
+    detourCount: number;
     _tried: number;
     constructor(solverInput: SingleOverlapSolverInput);
     _step(): void;
@@ -520,6 +551,7 @@ declare class OverlapAvoidanceStepSolver extends BaseSolver {
     allTraces: SolvedTracePath[];
     tracesToAvoidOverlapping: SolvedTracePath[];
     modifiedTraces: SolvedTracePath[];
+    completedReroutes: CompletedTraceReroute[];
     private readonly PADDING_BUFFER;
     private detourCounts;
     activeSubSolver: SingleOverlapSolver | null;
@@ -570,6 +602,7 @@ declare class TraceLabelOverlapAvoidanceSolver extends BaseSolver {
     _step(): void;
     getOutput(): {
         traces: SolvedTracePath[];
+        completedReroutes: CompletedTraceReroute[];
         netLabelPlacements: NetLabelPlacement[];
     };
     visualize(): GraphicsObject;
@@ -958,6 +991,7 @@ declare class NetLabelTraceCollisionSolver extends BaseSolver {
     netLabelPlacements: NetLabelPlacement[];
     outputTraces: SolvedTracePath[];
     outputNetLabelPlacements: NetLabelPlacement[];
+    completedReroutes: CompletedTraceReroute[];
     activeSubSolver: SingleOverlapSolver | null;
     private recentlyFailed;
     private detourCounts;
@@ -972,6 +1006,7 @@ declare class NetLabelTraceCollisionSolver extends BaseSolver {
     private reanchorLabelsOnMovedTrace;
     getOutput(): {
         traces: SolvedTracePath[];
+        completedReroutes: CompletedTraceReroute[];
         netLabelPlacements: NetLabelPlacement[];
     };
     private getOverlapKey;
@@ -1083,6 +1118,124 @@ declare class SameNetJunctionAlignmentSolver extends BaseSolver {
     visualize(): GraphicsObject;
 }
 
+interface TraceElbowTransitionSimplificationSolverInput {
+    inputProblem: InputProblem;
+    traces: SolvedTracePath[];
+    completedReroutes: CompletedTraceReroute[];
+    netLabelPlacements: NetLabelPlacement[];
+    paddingBuffer: number;
+}
+/**
+ * Post-processes traces after trace/label overlap avoidance. It removes
+ * redundant elbow transitions and, when needed, shifts a simplified elbow
+ * around a rendered label. Every replacement is revalidated against labels,
+ * components, other-net traces, and label anchors.
+ */
+declare class TraceElbowTransitionSimplificationSolver extends BaseSolver {
+    private input;
+    private outputTraces;
+    private traceIdQueue;
+    private obstacles;
+    constructor(input: TraceElbowTransitionSimplificationSolverInput);
+    _step(): void;
+    getOutput(): {
+        traces: SolvedTracePath[];
+        netLabelPlacements: NetLabelPlacement[];
+    };
+    visualize(): GraphicsObject;
+}
+
+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;
+/**
+ * How much of the label is allowed to hang off the end of the wire it names,
+ * as a fraction of the label's length. A short elbow stub is technically clear
+ * of every obstacle but reads as a label floating in space, so runs shorter
+ * than this are not considered.
+ */
+declare const MIN_INLINE_NET_LABEL_SEGMENT_RATIO = 0.5;
+/**
+ * A net label drawn parallel to the trace it names, rather than anchored to the
+ * end of it. Used for point-to-point signal traces, where an anchored label
+ * would break the visual line between the two pins.
+ *
+ * `center` is the center of the text box in the schematic's own (unrotated)
+ * coordinate space. `width` is the extent of the text along the trace and
+ * `height` is its extent perpendicular to the trace, so a vertical label has
+ * its `width` running along y.
+ */
+interface InlineNetLabelPlacement {
+    globalConnNetId: string;
+    netId?: string;
+    mspPairId: string;
+    pinIds: PinId[];
+    /** Axis the text runs along: "x" reads left-to-right, "y" reads bottom-to-top */
+    axis: "x" | "y";
+    /** Midpoint of the trace segment the label is attached to */
+    anchorPoint: Point;
+    /** Center of the label text, offset perpendicular to the trace */
+    center: Point;
+    /** Extent along the trace */
+    width: number;
+    /** Extent perpendicular to the trace */
+    height: number;
+    /**
+     * Which side of the trace the label sits on. For a horizontal trace, "y+" is
+     * above; for a vertical trace, "x-" is the left side (which is "above" once
+     * the text is rotated).
+     */
+    side: "x+" | "x-" | "y+" | "y-";
+}
+interface InlineNetLabelSolverInput {
+    inputProblem: InputProblem;
+    traces: SolvedTracePath[];
+    netLabelPlacements: NetLabelPlacement[];
+}
+/**
+ * Places "inline net labels" - net names drawn alongside the trace they belong
+ * to - for direct connections that opted in via `allowInlineNetLabel`.
+ *
+ * Any regular (anchored) net label placement for the same net is dropped, so a
+ * net is never labeled twice.
+ */
+declare class InlineNetLabelSolver extends BaseSolver {
+    inputProblem: InputProblem;
+    traces: SolvedTracePath[];
+    inputNetLabelPlacements: NetLabelPlacement[];
+    inlineNetLabelPlacements: InlineNetLabelPlacement[];
+    /** Direct connections that opted in, still waiting to be processed */
+    queuedDirectConnections: InputDirectConnection[];
+    private tracesByPinPairKey;
+    constructor(input: InlineNetLabelSolverInput);
+    getConstructorParams(): [InlineNetLabelSolverInput];
+    _step(): void;
+    private computeInlinePlacement;
+    /**
+     * An inline label may not sit on top of a chip, a component's text, or a
+     * trace belonging to another net.
+     */
+    private isObstructed;
+    /**
+     * Net label placements superseded by an inline label. A net gets one label or
+     * the other, never both.
+     */
+    private getSupersededNetLabelKeys;
+    getOutput(): {
+        traces: SolvedTracePath[];
+        netLabelPlacements: NetLabelPlacement[];
+        inlineNetLabelPlacements: InlineNetLabelPlacement[];
+    };
+    visualize(): GraphicsObject;
+}
+/**
+ * Mirrors the net label text width used by @tscircuit/core so a label that core
+ * did not measure for us still reserves a sane amount of space.
+ */
+declare const estimateInlineNetLabelWidth: (text: string, fontSize?: number) => number;
+
 /**
  * Pipeline solver that runs a series of solvers to find the best schematic layout.
  * Coordinates the entire layout process from chip partitioning through final packing.
@@ -1117,14 +1270,18 @@ declare class SchematicTracePipelineSolver extends BaseSolver {
     netLabelTraceCollisionSolver?: NetLabelTraceCollisionSolver;
     traceCleanupSolver2?: TraceCleanupSolver;
     netLabelNetLabelCollisionSolver?: NetLabelNetLabelCollisionSolver;
+    traceElbowTransitionSimplificationSolver?: TraceElbowTransitionSimplificationSolver;
+    preAlignmentTraceElbowTransitionSimplificationSolver?: TraceElbowTransitionSimplificationSolver;
+    finalTraceElbowTransitionSimplificationSolver?: TraceElbowTransitionSimplificationSolver;
     sameNetJunctionAlignmentSolver?: SameNetJunctionAlignmentSolver;
+    inlineNetLabelSolver?: InlineNetLabelSolver;
     startTimeOfPhase: Record<string, number>;
     endTimeOfPhase: Record<string, number>;
     timeSpentOnPhase: Record<string, number>;
     firstIterationOfPhase: Record<string, number>;
     inputProblem: InputProblem;
     hideRatsNet: boolean;
-    pipelineDef: (PipelineStep<typeof MspConnectionPairSolver> | PipelineStep<typeof SchematicTraceLinesSolver> | PipelineStep<typeof LongDistancePairSolver> | PipelineStep<typeof UnroutedTraceRecoverySolver> | PipelineStep<typeof TraceOverlapShiftSolver> | PipelineStep<typeof NetLabelPlacementSolver> | PipelineStep<typeof TraceLabelOverlapAvoidanceSolver> | PipelineStep<typeof TraceCleanupSolver> | PipelineStep<typeof Example28Solver> | PipelineStep<typeof AvailableNetOrientationSolver> | PipelineStep<typeof RailNetLabelCornerPlacementSolver> | PipelineStep<typeof TraceAnchoredNetLabelOverlapSolver> | PipelineStep<typeof NetLabelTraceCollisionSolver> | PipelineStep<typeof NetLabelNetLabelCollisionSolver> | PipelineStep<typeof SameNetJunctionAlignmentSolver>)[];
+    pipelineDef: (PipelineStep<typeof MspConnectionPairSolver> | PipelineStep<typeof SchematicTraceLinesSolver> | PipelineStep<typeof LongDistancePairSolver> | PipelineStep<typeof UnroutedTraceRecoverySolver> | PipelineStep<typeof TraceOverlapShiftSolver> | PipelineStep<typeof NetLabelPlacementSolver> | PipelineStep<typeof TraceLabelOverlapAvoidanceSolver> | PipelineStep<typeof TraceElbowTransitionSimplificationSolver> | PipelineStep<typeof TraceCleanupSolver> | PipelineStep<typeof Example28Solver> | PipelineStep<typeof AvailableNetOrientationSolver> | PipelineStep<typeof RailNetLabelCornerPlacementSolver> | PipelineStep<typeof TraceAnchoredNetLabelOverlapSolver> | PipelineStep<typeof NetLabelTraceCollisionSolver> | PipelineStep<typeof NetLabelNetLabelCollisionSolver> | PipelineStep<typeof SameNetJunctionAlignmentSolver> | PipelineStep<typeof InlineNetLabelSolver>)[];
     constructor(inputProblem: InputProblem, opts?: Options);
     getConstructorParams(): ConstructorParameters<typeof SchematicTracePipelineSolver>;
     currentPipelineStepIndex: number;
@@ -1140,4 +1297,4 @@ declare class SchematicTracePipelineSolver extends BaseSolver {
     preview(): GraphicsObject;
 }
 
-export { type ChipId, type InputChip, type InputDirectConnection, type InputNetConnection, type InputPin, type InputProblem, type NetId, type PinId, SchematicTracePipelineSolver, SchematicTraceSingleLineSolver2, type SectionId, type TextBoxes };
+export { type ChipId, DEFAULT_INLINE_NET_LABEL_HEIGHT, INLINE_NET_LABEL_TRACE_MARGIN, type InlineNetLabelPlacement, InlineNetLabelSolver, type InputChip, type InputDirectConnection, type InputNetConnection, type InputPin, type InputProblem, MIN_INLINE_NET_LABEL_SEGMENT_RATIO, type NetId, type NetLabelPlacement, type PinId, SchematicTracePipelineSolver, SchematicTraceSingleLineSolver2, type SectionId, type TextBoxes, estimateInlineNetLabelWidth };