@tscircuit/schematic-trace-solver 0.0.86 → 0.0.88

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

@@ -0,0 +1,115 @@
+---
+name: schematic-trace-visualization
+description: Work with schematic trace solver visualization in this repo. Use when changing solver `visualize()` or `preview()` output, adding debug graphics, creating SVG snapshots, inspecting pipeline stages, or generating graphics-debug artifacts for AI/headless review.
+---
+
+# Schematic Trace Visualization
+
+Use `GraphicsObject` from `graphics-debug` for solver debug views, SVG snapshots, and headless artifacts.
+
+## Graphics Object Types
+
+Import visualization types from `graphics-debug`:
+
+```ts
+import type {
+  GraphicsObject,
+  Point,
+  Line,
+  Rect,
+  Circle,
+  Text,
+} from "graphics-debug"
+```
+
+Do not redefine these shapes in repo docs, tests, or utilities.
+
+## Image Functions
+
+This repo uses `graphics-debug` for SVG and PNG rendering:
+
+```ts
+import {
+  getPngBufferFromGraphicsObject,
+  getSvgFromGraphicsObject,
+} from "graphics-debug"
+```
+
+Call them with a white background for stable artifacts:
+
+```ts
+const svg = getSvgFromGraphicsObject(graphics, { backgroundColor: "white" })
+const png = await getPngBufferFromGraphicsObject(graphics, {
+  backgroundColor: "white",
+  pngWidth: 1536,
+  pngHeight: 1536,
+})
+```
+
+## Existing Repo Helpers
+
+- `tests/fixtures/matcher.ts`: `expect(solver).toMatchSolverSnapshot(import.meta.path)` converts `solver.visualize()` to SVG and snapshots it.
+- `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.
+- `scripts/debug-pipeline-stages.ts`: CLI wrapper around the stage debug runner.
+
+## Minimal SVG Tests
+
+Prefer focused solver SVG snapshots over broad dumps:
+
+```ts
+const solver = new SchematicTracePipelineSolver(inputProblem as any)
+solver.solve()
+expect(solver).toMatchSolverSnapshot(import.meta.path)
+```
+
+For multi-step graphics where only the final stage matters:
+
+```ts
+expect(getLastStepSvg(solver.visualize())).toMatchSvgSnapshot(import.meta.path)
+```
+
+Update snapshots with:
+
+```bash
+BUN_UPDATE_SNAPSHOTS=1 bun test
+```
+
+## Headless Stage Debugging
+
+To inspect a pipeline run without Cosmos:
+
+```bash
+bun run debug:pipeline tests/assets/example01.json
+```
+
+Useful options:
+
+```bash
+bun run debug:pipeline tests/assets/example17.json --out tmp/schematic-trace-debug/example17
+bun run debug:pipeline tests/assets/example17.json --stop-after schematicTraceLinesSolver
+bun run debug:pipeline tests/assets/example17.json --no-json
+bun run debug:pipeline tests/assets/example17.json --svg --step-pngs
+```
+
+The runner writes:
+
+- `logs.txt`
+- `stageNN-stageName.png`
+- `stageNN-stageName.graphics.json` unless `--no-json` is passed
+
+Pass `--svg` when SVG companion artifacts are useful.
+Pass `--step-pngs` to split graphics with `step` values into per-step PNGs.
+
+Stage numbers are important because this pipeline can reuse the same solver name more than once, for example `netLabelPlacementSolver`.
+
+## Choosing The View
+
+Use solver-native `visualize()` for internal state, candidates, failed geometry, staged progress, net labels, and trace cleanup state.
+
+Use `SchematicTracePipelineSolver.visualize()` for final combined output after `solve()`.
+
+Use `visualizeInputProblem(inputProblem)` when the question is about the raw input geometry, schematic components, pins, direct connections, or net connection labels before routing.
+
+Keep SVG backgrounds white. Treat colors, labels, line widths, opacity, and `step` values as snapshot-sensitive.

package/.github/scripts/import-json-bug-report.ts

@@ -48,15 +48,19 @@ async function main() {
   const reportId = `bug-report-${timestamp}`
   const branchName = `json-bug-report/${reportId}`
   const reportDir = path.join("tests", "bug-reports", reportId)
+  const siteReportDir = path.join("site", "bug-reports")
   const reportDirAbs = path.join(repoRoot, reportDir)
   const jsonPath = path.join(reportDir, `${reportId}.json`)
   const testPath = path.join(reportDir, `${reportId}.test.ts`)
+  const pagePath = path.join(siteReportDir, `${reportId}.page.tsx`)
 
   writeOutput("report_id", reportId)
   writeOutput("branch_name", branchName)
   writeOutput("report_dir", reportDir)
+  writeOutput("site_report_dir", siteReportDir)
   writeOutput("json_path", jsonPath)
   writeOutput("test_path", testPath)
+  writeOutput("page_path", pagePath)
 
   if (fs.existsSync(reportDirAbs)) {
     writeOutput("created", "false")
@@ -70,15 +74,17 @@ async function main() {
   assertInputProblem(jsonAttachment.value)
 
   fs.mkdirSync(reportDirAbs, { recursive: true })
+  fs.mkdirSync(path.join(repoRoot, siteReportDir), { recursive: true })
   fs.writeFileSync(
     path.join(repoRoot, jsonPath),
     `${JSON.stringify(jsonAttachment.value, null, 2)}\n`,
   )
   fs.writeFileSync(path.join(repoRoot, testPath), getTestFile(reportId))
+  fs.writeFileSync(path.join(repoRoot, pagePath), getPageFile(reportId))
 
   writeOutput("created", "true")
   writeOutput("attachment_url", jsonAttachment.url)
-  console.log(`Generated ${jsonPath} and ${testPath}`)
+  console.log(`Generated ${jsonPath}, ${testPath}, and ${pagePath}`)
 }
 
 function isJsonBugReportIssue(issue: IssueEvent["issue"], body: string) {
@@ -458,6 +464,14 @@ test("${reportId}", () => {
 `
 }
 
+function getPageFile(reportId: string) {
+  return `import { PipelineDebugger } from "site/components/PipelineDebugger"
+import inputProblem from "../../tests/bug-reports/${reportId}/${reportId}.json"
+
+export default () => <PipelineDebugger inputProblem={inputProblem as any} />
+`
+}
+
 function writeOutput(key: string, value: string) {
   if (!githubOutputPath) return
   fs.appendFileSync(githubOutputPath, `${key}=${value}\n`)

package/.github/workflows/json-bug-report.yml

@@ -64,7 +64,7 @@ jobs:
 
       - name: Format generated test
         if: steps.import.outputs.created == 'true'
-        run: ./node_modules/.bin/biome format --write "${{ steps.import.outputs.test_path }}"
+        run: ./node_modules/.bin/biome format --write "${{ steps.import.outputs.test_path }}" "${{ steps.import.outputs.page_path }}"
 
       - name: Open pull request
         id: pr
@@ -82,6 +82,7 @@ jobs:
           git config user.email "tscircuit-bot@users.noreply.github.com"
           git checkout -B "$BRANCH_NAME"
           git add "${{ steps.import.outputs.report_dir }}"
+          git add "${{ steps.import.outputs.page_path }}"
 
           if git diff --cached --quiet; then
             echo "No changes to commit."
@@ -96,7 +97,7 @@ jobs:
           {
             echo "Generated from #${ISSUE_NUMBER}."
             echo
-            echo "Adds a snapshot-only regression test for the attached JSON solver input."
+            echo "Adds a snapshot-only regression test and debugger page for the attached JSON solver input."
             echo
             echo "Workflow run: ${RUN_URL}"
           } > "$pr_body_file"

package/AGENTS.md

@@ -0,0 +1,22 @@
+# Agent Notes
+
+- Use `bunx tsc --noEmit` to type check.
+- Use `bun test path/to/test.ts` to run a test.
+- Use `bun add <package>` to add a package.
+
+## Solver Visualization
+
+For schematic trace solver visualization work, use the repo-local skill:
+
+- `.agents/skills/schematic-trace-visualization/SKILL.md`
+
+This repo supports headless stage artifact generation without starting Cosmos:
+
+```bash
+bun run debug:pipeline tests/assets/example01.json
+```
+
+The command writes per-stage PNG and graphics JSON artifacts under `tmp/schematic-trace-debug/...`.
+Pass `--svg` when SVG companion files are needed.
+
+Interactive debugging still exists through `site/**/*.page.tsx`, but agents should prefer the headless debug runner when they need to inspect solver state programmatically.

package/dist/index.js

@@ -5777,6 +5777,57 @@ var getPointDistanceFromRect = (point, rect) => {
   return dx + dy;
 };
 
+// lib/solvers/Example28Solver/countCrossingsWithOtherTraces.ts
+var countCrossingsWithOtherTraces = (params) => {
+  const { trace, outputTraces } = params;
+  let crossingCount = 0;
+  for (const otherTrace of outputTraces) {
+    if (otherTrace.mspPairId === trace.mspPairId) continue;
+    if (otherTrace.globalConnNetId === trace.globalConnNetId) continue;
+    crossingCount += countPathIntersections(
+      trace.tracePath,
+      otherTrace.tracePath
+    );
+  }
+  return crossingCount;
+};
+
+// lib/solvers/Example28Solver/doesPathRunAlongChipBoundary.ts
+var doesPathRunAlongChipBoundary = (path, chipObstacles) => {
+  for (let i = 0; i < path.length - 1; i++) {
+    const start = path[i];
+    const end = path[i + 1];
+    for (const obstacle of chipObstacles) {
+      if (!segmentRunsAlongRectBoundary(start, end, obstacle)) continue;
+      if (getSegmentOverlapWithRectSpan(start, end, obstacle) > EPS7) {
+        return true;
+      }
+    }
+  }
+  return false;
+};
+var getSegmentOverlapWithRectSpan = (start, end, rect) => {
+  const isVertical4 = Math.abs(start.x - end.x) < EPS7;
+  if (isVertical4) {
+    return Math.min(Math.max(start.y, end.y), rect.maxY) - Math.max(Math.min(start.y, end.y), rect.minY);
+  }
+  return Math.min(Math.max(start.x, end.x), rect.maxX) - Math.max(Math.min(start.x, end.x), rect.minX);
+};
+
+// lib/solvers/Example28Solver/scoreSolutionTracePath.ts
+var scoreSolutionTracePath = (params) => {
+  const { traces, outputTraces, chipObstacles } = params;
+  let chipEdgeRuns = 0;
+  let traceCrossings = 0;
+  for (const trace of traces) {
+    if (doesPathRunAlongChipBoundary(trace.tracePath, chipObstacles)) {
+      chipEdgeRuns += 1;
+    }
+    traceCrossings += countCrossingsWithOtherTraces({ trace, outputTraces });
+  }
+  return { chipEdgeRuns, traceCrossings };
+};
+
 // lib/solvers/Example28Solver/visualize.ts
 var CANDIDATE_SELECTED_COLOR = "blue";
 var CANDIDATE_REJECTED_COLOR = "red";
@@ -5849,6 +5900,13 @@ ${label.netId ?? label.globalConnNetId}`
 var LABEL_OUTWARD_STEP = 0.1;
 var LABEL_MAX_OUTWARD_STEPS = 10;
 var LABEL_TRACE_CLEARANCE = 0.1;
+var isScoreBetter = (rerouteScore, labelMoveScore) => {
+  if (!rerouteScore) return false;
+  if (rerouteScore.chipEdgeRuns !== labelMoveScore.chipEdgeRuns) {
+    return rerouteScore.chipEdgeRuns < labelMoveScore.chipEdgeRuns;
+  }
+  return rerouteScore.traceCrossings < labelMoveScore.traceCrossings;
+};
 var Example28Solver = class extends BaseSolver {
   inputProblem;
   traces;
@@ -5951,7 +6009,7 @@ var Example28Solver = class extends BaseSolver {
     );
     if (traceIndex === -1) return;
     const currentTrace = this.outputTraces[traceIndex];
-    if (this.tryMoveLabelOutward(overlap.label)) return;
+    const labelMove = this.tryMoveLabelOutward(overlap.label);
     const rerouteResult = findBestReroutePath({
       trace: currentTrace,
       obstacleLabel: overlap.label,
@@ -5961,6 +6019,26 @@ var Example28Solver = class extends BaseSolver {
       chipObstacles: this.chipObstacles
     });
     this.currentCandidateResults = rerouteResult.candidateResults;
+    let rerouteScore = null;
+    if (rerouteResult.bestPath) {
+      rerouteScore = scoreSolutionTracePath({
+        traces: [{ ...currentTrace, tracePath: rerouteResult.bestPath }],
+        outputTraces: this.outputTraces,
+        chipObstacles: this.chipObstacles
+      });
+    }
+    if (labelMove) {
+      const labelMoveScore = scoreSolutionTracePath({
+        traces: [labelMove.connectorTrace, currentTrace],
+        outputTraces: this.outputTraces,
+        chipObstacles: this.chipObstacles
+      });
+      if (!isScoreBetter(rerouteScore, labelMoveScore)) {
+        this.outputNetLabelPlacements[labelMove.labelIndex] = labelMove.movedLabel;
+        this.outputTraces.push(labelMove.connectorTrace);
+        return;
+      }
+    }
     if (!rerouteResult.bestPath) return;
     const originalTracePath = currentTrace.tracePath;
     this.outputTraces[traceIndex] = {
@@ -5978,17 +6056,17 @@ var Example28Solver = class extends BaseSolver {
     const labelIndex = this.outputNetLabelPlacements.findIndex(
       (label2) => label2.globalConnNetId === labelToMove.globalConnNetId && label2.anchorPoint.x === labelToMove.anchorPoint.x && label2.anchorPoint.y === labelToMove.anchorPoint.y && label2.pinIds.join(",") === labelToMove.pinIds.join(",")
     );
-    if (labelIndex === -1) return false;
+    if (labelIndex === -1) return null;
     const label = this.outputNetLabelPlacements[labelIndex];
-    if (label.mspConnectionPairIds.length > 0) return false;
-    if (label.pinIds.length !== 1) return false;
+    if (label.mspConnectionPairIds.length > 0) return null;
+    if (label.pinIds.length !== 1) return null;
     if (this.outputNetLabelPlacements.filter(
       (otherLabel) => otherLabel.globalConnNetId === label.globalConnNetId
     ).length !== 1) {
-      return false;
+      return null;
     }
     const outward = dir(label.orientation);
-    if (outward.x === 0 && outward.y === 0) return false;
+    if (outward.x === 0 && outward.y === 0) return null;
     for (let step = 1; step <= LABEL_MAX_OUTWARD_STEPS; step++) {
       const distance3 = step * LABEL_OUTWARD_STEP;
       const candidate = {
@@ -6024,11 +6102,9 @@ var Example28Solver = class extends BaseSolver {
       }).length > 0) {
         continue;
       }
-      this.outputNetLabelPlacements[labelIndex] = candidate;
-      this.outputTraces.push(connectorTrace);
-      return true;
+      return { labelIndex, movedLabel: candidate, connectorTrace };
     }
-    return false;
+    return null;
   }
   visualize() {
     return visualizeExample28Solver({

package/lib/solvers/Example28Solver/Example28Solver.ts

@@ -20,6 +20,10 @@ import type {
 import { dir } from "lib/utils/dir"
 import { moveAttachedLabelsToReroutedTrace } from "./labelMovement"
 import { findBestReroutePath } from "./reroute"
+import {
+  scoreSolutionTracePath,
+  type TracePathScore,
+} from "./scoreSolutionTracePath"
 import type { Example28SolverParams, RerouteCandidateResult } from "./types"
 import { visualizeExample28Solver } from "./visualize"
 
@@ -27,6 +31,17 @@ const LABEL_OUTWARD_STEP = 0.1
 const LABEL_MAX_OUTWARD_STEPS = 10
 const LABEL_TRACE_CLEARANCE = 0.1
 
+const isScoreBetter = (
+  rerouteScore: TracePathScore | null,
+  labelMoveScore: TracePathScore,
+) => {
+  if (!rerouteScore) return false
+  if (rerouteScore.chipEdgeRuns !== labelMoveScore.chipEdgeRuns) {
+    return rerouteScore.chipEdgeRuns < labelMoveScore.chipEdgeRuns
+  }
+  return rerouteScore.traceCrossings < labelMoveScore.traceCrossings
+}
+
 export class Example28Solver extends BaseSolver {
   inputProblem: InputProblem
   traces: SolvedTracePath[]
@@ -160,7 +175,7 @@ export class Example28Solver extends BaseSolver {
     if (traceIndex === -1) return
 
     const currentTrace = this.outputTraces[traceIndex]!
-    if (this.tryMoveLabelOutward(overlap.label)) return
+    const labelMove = this.tryMoveLabelOutward(overlap.label)
 
     const rerouteResult = findBestReroutePath({
       trace: currentTrace,
@@ -172,6 +187,29 @@ export class Example28Solver extends BaseSolver {
     })
     this.currentCandidateResults = rerouteResult.candidateResults
 
+    let rerouteScore: TracePathScore | null = null
+    if (rerouteResult.bestPath) {
+      rerouteScore = scoreSolutionTracePath({
+        traces: [{ ...currentTrace, tracePath: rerouteResult.bestPath }],
+        outputTraces: this.outputTraces,
+        chipObstacles: this.chipObstacles,
+      })
+    }
+
+    if (labelMove) {
+      const labelMoveScore = scoreSolutionTracePath({
+        traces: [labelMove.connectorTrace, currentTrace],
+        outputTraces: this.outputTraces,
+        chipObstacles: this.chipObstacles,
+      })
+      if (!isScoreBetter(rerouteScore, labelMoveScore)) {
+        this.outputNetLabelPlacements[labelMove.labelIndex] =
+          labelMove.movedLabel
+        this.outputTraces.push(labelMove.connectorTrace)
+        return
+      }
+    }
+
     if (!rerouteResult.bestPath) return
 
     const originalTracePath = currentTrace.tracePath
@@ -195,21 +233,21 @@ export class Example28Solver extends BaseSolver {
         label.anchorPoint.y === labelToMove.anchorPoint.y &&
         label.pinIds.join(",") === labelToMove.pinIds.join(","),
     )
-    if (labelIndex === -1) return false
+    if (labelIndex === -1) return null
 
     const label = this.outputNetLabelPlacements[labelIndex]!
-    if (label.mspConnectionPairIds.length > 0) return false
-    if (label.pinIds.length !== 1) return false
+    if (label.mspConnectionPairIds.length > 0) return null
+    if (label.pinIds.length !== 1) return null
     if (
       this.outputNetLabelPlacements.filter(
         (otherLabel) => otherLabel.globalConnNetId === label.globalConnNetId,
       ).length !== 1
     ) {
-      return false
+      return null
     }
 
     const outward = dir(label.orientation)
-    if (outward.x === 0 && outward.y === 0) return false
+    if (outward.x === 0 && outward.y === 0) return null
 
     for (let step = 1; step <= LABEL_MAX_OUTWARD_STEPS; step++) {
       const distance = step * LABEL_OUTWARD_STEP
@@ -252,12 +290,10 @@ export class Example28Solver extends BaseSolver {
         continue
       }
 
-      this.outputNetLabelPlacements[labelIndex] = candidate
-      this.outputTraces.push(connectorTrace)
-      return true
+      return { labelIndex, movedLabel: candidate, connectorTrace }
     }
 
-    return false
+    return null
   }
 
   override visualize(): GraphicsObject {

package/lib/solvers/Example28Solver/countCrossingsWithOtherTraces.ts

@@ -0,0 +1,19 @@
+import type { SolvedTracePath } from "lib/solvers/SchematicTraceLinesSolver/SchematicTraceLinesSolver"
+import { countPathIntersections } from "./geometry"
+
+export const countCrossingsWithOtherTraces = (params: {
+  trace: SolvedTracePath
+  outputTraces: SolvedTracePath[]
+}) => {
+  const { trace, outputTraces } = params
+  let crossingCount = 0
+  for (const otherTrace of outputTraces) {
+    if (otherTrace.mspPairId === trace.mspPairId) continue
+    if (otherTrace.globalConnNetId === trace.globalConnNetId) continue
+    crossingCount += countPathIntersections(
+      trace.tracePath,
+      otherTrace.tracePath,
+    )
+  }
+  return crossingCount
+}

package/lib/solvers/Example28Solver/scoreSolutionTracePath.ts

@@ -0,0 +1,26 @@
+import type { SolvedTracePath } from "lib/solvers/SchematicTraceLinesSolver/SchematicTraceLinesSolver"
+import { countCrossingsWithOtherTraces } from "./countCrossingsWithOtherTraces"
+import { doesPathRunAlongChipBoundary } from "./doesPathRunAlongChipBoundary"
+import type { ChipObstacle } from "./types"
+
+export type TracePathScore = {
+  chipEdgeRuns: number
+  traceCrossings: number
+}
+
+export const scoreSolutionTracePath = (params: {
+  traces: SolvedTracePath[]
+  outputTraces: SolvedTracePath[]
+  chipObstacles: ChipObstacle[]
+}): TracePathScore => {
+  const { traces, outputTraces, chipObstacles } = params
+  let chipEdgeRuns = 0
+  let traceCrossings = 0
+  for (const trace of traces) {
+    if (doesPathRunAlongChipBoundary(trace.tracePath, chipObstacles)) {
+      chipEdgeRuns += 1
+    }
+    traceCrossings += countCrossingsWithOtherTraces({ trace, outputTraces })
+  }
+  return { chipEdgeRuns, traceCrossings }
+}