@tscircuit/schematic-trace-solver 0.0.1

package/site/components/PipelineStageTable.tsx

@@ -0,0 +1,149 @@
+import type { SchematicTracePipelineSolver } from "lib/solvers/SchematicTracePipelineSolver/SchematicTracePipelineSolver"
+
+type StageStatus = "Solved" | "Failed" | "Running" | "Not Started"
+
+/**
+ * Displays every stage of the pipeline with the status ("Solved", "Failed", "Running" or "Not Started"),
+ * what iteration it started on, what iteration it ended on, and the time it took to solve.
+ *
+ * The table also has a column "Actions" that has a download icon to download the getConstructorParams()
+ * of each stage.
+ */
+export const PipelineStageTable = ({
+  pipelineSolver,
+  triggerRender,
+}: {
+  pipelineSolver: SchematicTracePipelineSolver
+  triggerRender: () => void
+}) => {
+  const getStageStatus = (stageIndex: number): StageStatus => {
+    if (pipelineSolver.currentPipelineStepIndex > stageIndex) {
+      return "Solved"
+    }
+    if (pipelineSolver.currentPipelineStepIndex === stageIndex) {
+      if (pipelineSolver.failed) return "Failed"
+      if (pipelineSolver.activeSubSolver) return "Running"
+    }
+    return "Not Started"
+  }
+
+  const downloadParams = (stageName: string) => {
+    const stage = pipelineSolver.pipelineDef.find(
+      (s) => s.solverName === stageName,
+    )
+    if (!stage) return
+
+    try {
+      const params = stage.getConstructorParams(pipelineSolver)
+      const blob = new Blob([JSON.stringify(params, null, 2)], {
+        type: "application/json",
+      })
+      const url = URL.createObjectURL(blob)
+      const a = document.createElement("a")
+      a.href = url
+      a.download = `${stageName}_params.json`
+      a.click()
+      URL.revokeObjectURL(url)
+    } catch (error) {
+      alert(
+        `Error downloading params for ${stageName}: ${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
+
+  return (
+    <div className="overflow-x-auto">
+      <table className="min-w-full border border-gray-300">
+        <thead>
+          <tr className="bg-gray-100">
+            <th className="border border-gray-300 px-4 py-2 text-left">
+              Stage
+            </th>
+            <th className="border border-gray-300 px-4 py-2 text-left">
+              Status
+            </th>
+            <th className="border border-gray-300 px-4 py-2 text-left">
+              Start Iteration
+            </th>
+            <th className="border border-gray-300 px-4 py-2 text-left">
+              End Iteration
+            </th>
+            <th className="border border-gray-300 px-4 py-2 text-left">
+              Time (ms)
+            </th>
+            <th className="border border-gray-300 px-4 py-2 text-left">
+              Actions
+            </th>
+          </tr>
+        </thead>
+        <tbody>
+          {pipelineSolver.pipelineDef.map((stage, index) => {
+            const status = getStageStatus(index)
+            const startIteration =
+              pipelineSolver.firstIterationOfPhase[stage.solverName]
+            const endIteration =
+              status === "Solved"
+                ? (pipelineSolver.firstIterationOfPhase[stage.solverName] ||
+                    0) +
+                  ((pipelineSolver as any)[stage.solverName]?.iterations || 0)
+                : undefined
+            const timeSpent = pipelineSolver.timeSpentOnPhase[stage.solverName]
+
+            return (
+              <tr key={stage.solverName} className="hover:bg-gray-50">
+                <td className="border border-gray-300 px-4 py-2 font-mono text-sm">
+                  {stage.solverName}
+                </td>
+                <td className="border border-gray-300 px-4 py-2">
+                  <div className="flex items-center gap-2">
+                    <span
+                      className={`px-2 py-1 rounded text-sm ${
+                        status === "Solved"
+                          ? "bg-green-100 text-green-800"
+                          : status === "Failed"
+                            ? "bg-red-100 text-red-800"
+                            : status === "Running"
+                              ? "bg-yellow-100 text-yellow-800"
+                              : "bg-gray-100 text-gray-800"
+                      }`}
+                    >
+                      {status}
+                    </span>
+                    <button
+                      onClick={() => {
+                        pipelineSolver.solveUntilPhase(stage.solverName)
+                        triggerRender()
+                      }}
+                      className="hover:bg-green-500 text-gray-600 hover:text-white px-2 py-1 rounded text-sm"
+                      title={`Run until ${stage.solverName} is active`}
+                    >
+                      ▶️
+                    </button>
+                  </div>
+                </td>
+                <td className="border border-gray-300 px-4 py-2 text-center">
+                  {startIteration !== undefined ? startIteration : "-"}
+                </td>
+                <td className="border border-gray-300 px-4 py-2 text-center">
+                  {endIteration !== undefined ? endIteration : "-"}
+                </td>
+                <td className="border border-gray-300 px-4 py-2 text-center">
+                  {timeSpent !== undefined ? Math.round(timeSpent) : "-"}
+                </td>
+                <td className="border border-gray-300 px-4 py-2 text-center">
+                  <button
+                    onClick={() => downloadParams(stage.solverName)}
+                    className="bg-blue-500 hover:bg-blue-600 text-white px-2 py-1 rounded text-sm"
+                    title="Download constructor params"
+                  >
+                    ⬇️
+                  </button>
+                </td>
+              </tr>
+            )
+          })}
+        </tbody>
+      </table>
+    </div>
+  )
+}

package/site/components/SolverBreadcrumbInputDownloader.tsx

@@ -0,0 +1,62 @@
+import type { BaseSolver } from "lib/solvers/BaseSolver/BaseSolver"
+
+export const getSolverChain = (solver: BaseSolver): BaseSolver[] => {
+  if (!solver.activeSubSolver) {
+    return [solver]
+  }
+  return [solver, ...getSolverChain(solver.activeSubSolver)]
+}
+
+/**
+ * Displays each solver in the chain as a breadcrumb with download functionality
+ */
+export const SolverBreadcrumbInputDownloader = ({
+  solver,
+}: {
+  solver: BaseSolver
+}) => {
+  const solverChain = getSolverChain(solver)
+
+  const downloadSolverParams = (s: BaseSolver) => {
+    try {
+      if (typeof s.getConstructorParams !== "function") {
+        alert(
+          `getConstructorParams() is not implemented for ${s.constructor.name}`,
+        )
+        return
+      }
+
+      const params = s.getConstructorParams()
+      const blob = new Blob([JSON.stringify(params, null, 2)], {
+        type: "application/json",
+      })
+      const url = URL.createObjectURL(blob)
+      const a = document.createElement("a")
+      a.href = url
+      a.download = `${s.constructor.name}_params.json`
+      a.click()
+      URL.revokeObjectURL(url)
+    } catch (error) {
+      alert(
+        `Error downloading params for ${s.constructor.name}: ${error instanceof Error ? error.message : String(error)}`,
+      )
+    }
+  }
+
+  return (
+    <div className="flex gap-1 items-center text-sm pt-1">
+      {solverChain.map((s, index) => (
+        <div key={s.constructor.name} className="flex items-center">
+          {index > 0 && <span className="text-gray-400 mx-1">→</span>}
+          <button
+            className="px-2 py-1 rounded text-xs cursor-pointer"
+            onClick={() => downloadSolverParams(s)}
+            title={`Download constructor params for ${s.constructor.name}`}
+          >
+            {s.constructor.name}
+          </button>
+        </div>
+      ))}
+    </div>
+  )
+}

package/site/components/SolverToolbar.tsx

@@ -0,0 +1,128 @@
+import type { BaseSolver } from "lib/solvers/BaseSolver/BaseSolver"
+import { useReducer, useRef, useEffect } from "react"
+import { SolverBreadcrumbInputDownloader } from "./SolverBreadcrumbInputDownloader"
+
+/**
+ * The solver toolbar offers various actions for progressing the solver
+ * - "Step" - call solver.step()
+ * - "Solve" - call solver.solve()
+ * - "Animate" - call solver.step() at 40 iterations/second until solved or failed
+ *   - When animate is pressed, show "Stop" button
+ *
+ * The toolbar also displays the number of iterations (solver.iterations)
+ *
+ * After any action, we need to incRenderCount internally to trigger a rerender
+ */
+export const SolverToolbar = ({
+  solver,
+  triggerRender,
+}: {
+  solver: BaseSolver
+  triggerRender: Function
+}) => {
+  const [isAnimating, setIsAnimating] = useReducer((x) => !x, false)
+  const animationRef = useRef<number | undefined>(undefined)
+
+  const handleStep = () => {
+    solver.step()
+    triggerRender()
+  }
+
+  const handleSolve = () => {
+    solver.solve()
+    triggerRender()
+  }
+
+  const handleAnimate = () => {
+    if (isAnimating) {
+      if (animationRef.current) {
+        clearInterval(animationRef.current)
+        animationRef.current = undefined
+      }
+      setIsAnimating()
+    } else {
+      setIsAnimating()
+      animationRef.current = window.setInterval(() => {
+        if (solver.solved || solver.failed) {
+          if (animationRef.current) {
+            clearInterval(animationRef.current)
+            animationRef.current = undefined
+          }
+          setIsAnimating()
+          triggerRender()
+          return
+        }
+        solver.step()
+        triggerRender()
+      }, 25) // 40 iterations/second = 25ms interval
+    }
+  }
+
+  useEffect(() => {
+    return () => {
+      if (animationRef.current) {
+        clearInterval(animationRef.current)
+      }
+    }
+  }, [])
+
+  useEffect(() => {
+    if ((solver.solved || solver.failed) && isAnimating) {
+      if (animationRef.current) {
+        clearInterval(animationRef.current)
+        animationRef.current = undefined
+      }
+      setIsAnimating()
+    }
+  }, [solver.solved, solver.failed, isAnimating])
+
+  return (
+    <div className="space-y-1 px-1">
+      <SolverBreadcrumbInputDownloader solver={solver} />
+
+      <div className="flex gap-2 pb-1 items-center">
+        <button
+          onClick={handleStep}
+          disabled={solver.solved || solver.failed || isAnimating}
+          className="bg-blue-500 hover:bg-blue-600 disabled:bg-gray-300 text-white px-3 py-1 rounded"
+        >
+          Step
+        </button>
+
+        <button
+          onClick={handleSolve}
+          disabled={solver.solved || solver.failed || isAnimating}
+          className="bg-green-500 hover:bg-green-600 disabled:bg-gray-300 text-white px-3 py-1 rounded"
+        >
+          Solve
+        </button>
+
+        <button
+          onClick={handleAnimate}
+          disabled={solver.solved || solver.failed}
+          className={`px-3 py-1 rounded text-white ${
+            isAnimating
+              ? "bg-red-500 hover:bg-red-600"
+              : "bg-yellow-500 hover:bg-yellow-600"
+          } disabled:bg-gray-300`}
+        >
+          {isAnimating ? "Stop" : "Animate"}
+        </button>
+
+        <div className="ml-4 text-sm text-gray-600">
+          Iterations: {solver.iterations}
+        </div>
+
+        {solver.solved && (
+          <div className="ml-2 px-2 py-1 bg-green-100 text-green-800 rounded text-sm">
+            Solved
+          </div>
+        )}
+      </div>
+
+      {solver.failed && (
+        <div className="text-red-500">Failed: {solver.error}</div>
+      )}
+    </div>
+  )
+}

package/site/examples/example01-basic.page.tsx

@@ -0,0 +1,104 @@
+import type { InputProblem } from "lib/types/InputProblem"
+import { PipelineDebugger } from "site/components/PipelineDebugger"
+
+const inputProblem: InputProblem = {
+  chips: [
+    {
+      chipId: "U1",
+      center: { x: 0, y: 0 },
+      width: 1.6,
+      height: 0.6,
+      pins: [
+        {
+          pinId: "U1.1",
+          x: -0.8,
+          y: 0.2,
+        },
+        {
+          pinId: "U1.2",
+          x: -0.8,
+          y: 0,
+        },
+        {
+          pinId: "U1.3",
+          x: -0.8,
+          y: -0.2,
+        },
+        {
+          pinId: "U1.4",
+          x: 0.8,
+          y: -0.2,
+        },
+        {
+          pinId: "U1.5",
+          x: 0.8,
+          y: 0,
+        },
+        {
+          pinId: "U1.6",
+          x: 0.8,
+          y: 0.2,
+        },
+      ],
+    },
+    {
+      chipId: "C1",
+      center: { x: -2, y: 0 },
+      width: 0.5,
+      height: 1,
+      pins: [
+        {
+          pinId: "C1.1",
+          x: -2,
+          y: 0.5,
+        },
+        {
+          pinId: "C1.2",
+          x: -2,
+          y: -0.5,
+        },
+      ],
+    },
+    {
+      chipId: "C2",
+      center: { x: -4, y: 0 },
+      width: 0.5,
+      height: 1,
+      pins: [
+        {
+          pinId: "C2.1",
+          x: -4,
+          y: 0.5,
+        },
+        {
+          pinId: "C2.2",
+          x: -4,
+          y: -0.5,
+        },
+      ],
+    },
+  ],
+  directConnections: [
+    {
+      pinIds: ["U1.1", "C1.1"],
+      netId: "VCC",
+    },
+    {
+      pinIds: ["U1.2", "C2.1"],
+      netId: "EN",
+    },
+  ],
+  netConnections: [
+    {
+      pinIds: ["U1.3", "C2.2", "C1.2"],
+      netId: "GND",
+    },
+  ],
+  availableNetLabelOrientations: {
+    VCC: ["y+", "y-"],
+    EN: ["x+", "x-"],
+    GND: ["y+", "y-"],
+  },
+}
+
+export default () => <PipelineDebugger inputProblem={inputProblem} />

package/tests/functions/generateElbowVariants.test.ts

@@ -0,0 +1,98 @@
+import { generateElbowVariants } from "lib/solvers/SchematicTraceLinesSolver/SchematicTraceSingleLineSolver/generateElbowVariants"
+import { test, expect } from "bun:test"
+import type { Guideline } from "lib/solvers/GuidelinesSolver/GuidelinesSolver"
+import type { Point } from "@tscircuit/math-utils"
+
+test("generateElbowVariants - simple horizontal segment", () => {
+  const baseElbow: Point[] = [
+    { x: 0, y: 0 },
+    { x: 1, y: 0 },
+    { x: 1, y: 2 },
+    { x: 3, y: 2 },
+  ]
+
+  const guidelines: Guideline[] = [
+    { orientation: "vertical", x: 0.5, y: undefined },
+    { orientation: "vertical", x: 1.5, y: undefined },
+    { orientation: "horizontal", x: undefined, y: 1 },
+  ]
+
+  const result = generateElbowVariants({ baseElbow, guidelines })
+
+  expect(result.movableSegments).toHaveLength(2)
+  expect(result.movableSegments[0].freedom).toBe("y+")
+  expect(result.movableSegments[1].freedom).toBe("x+")
+
+  // Should generate variants for each combination of guideline positions
+  expect(result.elbowVariants.length).toBeGreaterThan(1)
+})
+
+test("generateElbowVariants - no movable segments", () => {
+  const baseElbow: Point[] = [
+    { x: 0, y: 0 },
+    { x: 1, y: 1 },
+  ]
+
+  const guidelines: Guideline[] = [
+    { orientation: "vertical", x: 0.5, y: undefined },
+  ]
+
+  const result = generateElbowVariants({ baseElbow, guidelines })
+
+  expect(result.movableSegments).toHaveLength(0)
+  expect(result.elbowVariants).toHaveLength(1)
+  expect(result.elbowVariants[0]).toEqual(baseElbow)
+})
+
+test("generateElbowVariants - vertical movable segment", () => {
+  const baseElbow: Point[] = [
+    { x: 0, y: 0 },
+    { x: 0, y: 1 },
+    { x: 0, y: 2 },
+    { x: 2, y: 2 },
+  ]
+
+  const guidelines: Guideline[] = [
+    { orientation: "horizontal", x: undefined, y: 0.5 },
+    { orientation: "horizontal", x: undefined, y: 1.5 },
+  ]
+
+  const result = generateElbowVariants({ baseElbow, guidelines })
+
+  expect(result.movableSegments).toHaveLength(1)
+  expect(result.movableSegments[0].freedom).toBe("x+")
+
+  // Should include original position plus guideline positions
+  expect(result.elbowVariants.length).toBe(3) // Original + 2 guidelines
+})
+
+test("generateElbowVariants - multiple segments with guidelines", () => {
+  const baseElbow: Point[] = [
+    { x: 0, y: 0 },
+    { x: 1, y: 0 },
+    { x: 1, y: 1 },
+    { x: 2, y: 1 },
+    { x: 2, y: 2 },
+  ]
+
+  const guidelines: Guideline[] = [
+    { orientation: "vertical", x: 0.5, y: undefined },
+    { orientation: "vertical", x: 1.5, y: undefined },
+    { orientation: "horizontal", x: undefined, y: 0.5 },
+    { orientation: "horizontal", x: undefined, y: 1.5 },
+  ]
+
+  const result = generateElbowVariants({ baseElbow, guidelines })
+
+  expect(result.movableSegments).toHaveLength(3)
+
+  // First segment moves vertically (y+/y-)
+  expect(result.movableSegments[0].freedom).toMatch(/^y[+-]$/)
+  // Second segment moves horizontally (x+/x-)
+  expect(result.movableSegments[1].freedom).toMatch(/^x[+-]$/)
+  // Third segment moves vertically (y+/y-)
+  expect(result.movableSegments[2].freedom).toMatch(/^y[+-]$/)
+
+  // Should generate multiple variants
+  expect(result.elbowVariants.length).toBeGreaterThan(1)
+})

package/tests/functions/getOrthogonalMinimumSpanningTree.test.ts

@@ -0,0 +1,23 @@
+import { getOrthogonalMinimumSpanningTree } from "lib/solvers/MspConnectionPairSolver/getMspConnectionPairsFromPins"
+import { test, expect } from "bun:test"
+import type { InputPin } from "lib/types/InputProblem"
+
+test("getOrthogonalMinimumSpanningTree", () => {
+  const pins: InputPin[] = [
+    { x: 0, y: 0, pinId: "A" },
+    { x: 1, y: 1, pinId: "B" },
+    { x: 10, y: 10, pinId: "C" },
+    { x: 11, y: 11, pinId: "D" },
+  ]
+  const msp = getOrthogonalMinimumSpanningTree(pins)
+  expect(
+    msp
+      .map(([a, b]) => `${a}->${b}`)
+      .sort()
+      .join("\n"),
+  ).toMatchInlineSnapshot(`
+    "B->A
+    C->B
+    D->C"
+  `)
+})

package/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    "paths": {
+      "lib/*": ["lib/*"],
+      "site/*": ["site/*"],
+      "tests/*": ["tests/*"]
+    },
+
+    "baseUrl": ".",
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": false,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

package/vite.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vite"
+import path from "path"
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      lib: path.resolve(__dirname, "lib"),
+      site: path.resolve(__dirname, "site"),
+      tests: path.resolve(__dirname, "tests"),
+    },
+  },
+})