@tscircuit/schematic-trace-solver 0.0.87 → 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/lib/testing/PipelineStageDebugRunner.ts

@@ -0,0 +1,344 @@
+import { mkdir, writeFile } from "node:fs/promises"
+import path from "node:path"
+import {
+  getPngBufferFromGraphicsObject,
+  getSvgFromGraphicsObject,
+} from "graphics-debug"
+import type { GraphicsObject } from "graphics-debug"
+import { BaseSolver } from "lib/solvers/BaseSolver/BaseSolver"
+import { SchematicTracePipelineSolver } from "lib/solvers/SchematicTracePipelineSolver/SchematicTracePipelineSolver"
+
+type PipelineStepLike = {
+  solverName: string
+}
+
+type VisualizingSolver = {
+  visualize: () => GraphicsObject
+  iterations?: number
+  error?: string | null
+  solved?: boolean
+  failed?: boolean
+}
+
+export type PipelineStageArtifact = {
+  stageName: string
+  stageNumber: number
+  pngPath?: string
+  svgPath?: string
+  graphicsJsonPath?: string
+  stepPngPaths: string[]
+}
+
+export type PipelineStageDebugRunnerResult = {
+  outputDir: string
+  logsPath: string
+  stageArtifacts: PipelineStageArtifact[]
+  solved: boolean
+  failed: boolean
+  error: string | null
+  stoppedAfterStage: string | null
+}
+
+export class PipelineStageDebugRunner {
+  readonly pipelineSolver: SchematicTracePipelineSolver
+  readonly outputDir: string
+  readonly logsPath: string
+  readonly pngWidth: number
+  readonly pngHeight: number
+  readonly writePng: boolean
+  readonly writeSvg: boolean
+  readonly writeGraphicsJson: boolean
+  readonly writeStepPngs: boolean
+  readonly stopAfterStage?: string
+  readonly context: Record<string, string | number | boolean | null | undefined>
+  readonly onLog?: (line: string) => void
+
+  private readonly stageArtifacts: PipelineStageArtifact[] = []
+  private readonly capturedStageNumbers = new Set<number>()
+
+  constructor(opts: {
+    pipelineSolver: SchematicTracePipelineSolver
+    outputDir: string
+    pngWidth?: number
+    pngHeight?: number
+    writePng?: boolean
+    writeSvg?: boolean
+    writeGraphicsJson?: boolean
+    writeStepPngs?: boolean
+    stopAfterStage?: string
+    context?: Record<string, string | number | boolean | null | undefined>
+    onLog?: (line: string) => void
+  }) {
+    this.pipelineSolver = opts.pipelineSolver
+    this.outputDir = opts.outputDir
+    this.logsPath = path.join(this.outputDir, "logs.txt")
+    this.pngWidth = opts.pngWidth ?? 1536
+    this.pngHeight = opts.pngHeight ?? 1536
+    this.writePng = opts.writePng ?? true
+    this.writeSvg = opts.writeSvg ?? false
+    this.writeGraphicsJson = opts.writeGraphicsJson ?? true
+    this.writeStepPngs = opts.writeStepPngs ?? false
+    this.stopAfterStage = opts.stopAfterStage
+    this.context = opts.context ?? {}
+    this.onLog = opts.onLog
+  }
+
+  async run(): Promise<PipelineStageDebugRunnerResult> {
+    await mkdir(this.outputDir, { recursive: true })
+    await writeFile(this.logsPath, "")
+
+    await this.log(`startedAt=${new Date().toISOString()}`)
+    await this.log(`outputDir=${this.toDisplayPath(this.outputDir)}`)
+    await this.log(
+      `artifacts png=${this.writePng} svg=${this.writeSvg} graphicsJson=${this.writeGraphicsJson} stepPngs=${this.writeStepPngs} pngSize=${this.pngWidth}x${this.pngHeight}`,
+    )
+    for (const [key, value] of Object.entries(this.context)) {
+      await this.log(`${key}=${value ?? ""}`)
+    }
+
+    let stoppedAfterStage: string | null = null
+    let thrownError: unknown = null
+
+    await this.log(
+      this.getStageEnterLogLine(this.pipelineSolver.getCurrentPhase(), 0),
+    )
+
+    while (!this.pipelineSolver.solved && !this.pipelineSolver.failed) {
+      const previousStageNumber = this.pipelineSolver.currentPipelineStepIndex
+      const previousStageName = this.pipelineSolver.getCurrentPhase()
+
+      try {
+        this.pipelineSolver.step()
+      } catch (error) {
+        thrownError = error
+      }
+
+      const currentStageNumber = this.pipelineSolver.currentPipelineStepIndex
+      const currentStageName = this.pipelineSolver.getCurrentPhase()
+
+      if (
+        currentStageNumber !== previousStageNumber &&
+        previousStageName !== "none"
+      ) {
+        await this.captureStage(previousStageNumber)
+        if (
+          previousStageName === this.stopAfterStage ||
+          String(previousStageNumber + 1) === this.stopAfterStage
+        ) {
+          stoppedAfterStage = previousStageName
+          break
+        }
+      }
+
+      if (
+        currentStageNumber !== previousStageNumber &&
+        currentStageName !== "none"
+      ) {
+        await this.log(
+          this.getStageEnterLogLine(currentStageName, currentStageNumber),
+        )
+      }
+
+      if (thrownError) break
+    }
+
+    if (this.pipelineSolver.failed) {
+      await this.captureActiveStage()
+    }
+
+    if (thrownError) {
+      await this.log(`thrownError=${this.formatError(thrownError)}`)
+    }
+
+    const status = stoppedAfterStage
+      ? "stopped"
+      : this.pipelineSolver.solved
+        ? "solved"
+        : this.pipelineSolver.failed
+          ? "failed"
+          : "incomplete"
+
+    await this.log(
+      `completed status=${status} iterations=${this.pipelineSolver.iterations} error=${this.pipelineSolver.error ?? ""}`,
+    )
+
+    return {
+      outputDir: this.outputDir,
+      logsPath: this.logsPath,
+      stageArtifacts: [...this.stageArtifacts],
+      solved: this.pipelineSolver.solved,
+      failed: this.pipelineSolver.failed,
+      error:
+        this.pipelineSolver.error ??
+        (thrownError ? this.formatError(thrownError) : null),
+      stoppedAfterStage,
+    }
+  }
+
+  private async captureActiveStage() {
+    const stageNumber = this.pipelineSolver.currentPipelineStepIndex
+    if (this.pipelineSolver.getCurrentPhase() === "none") return
+    if (this.capturedStageNumbers.has(stageNumber)) return
+
+    await this.captureStage(stageNumber, this.pipelineSolver.activeSubSolver)
+  }
+
+  private async captureStage(stageNumber: number, solver?: BaseSolver | null) {
+    if (this.capturedStageNumbers.has(stageNumber)) return
+
+    const stageDef = this.getStageDef(stageNumber)
+    if (!stageDef) return
+
+    const stageSolver = solver ?? this.getStageSolver(stageDef.solverName)
+    if (!stageSolver) {
+      throw new Error(
+        `Unable to resolve solver for stage ${stageNumber + 1} "${stageDef.solverName}"`,
+      )
+    }
+
+    const basePath = path.join(
+      this.outputDir,
+      `stage${String(stageNumber + 1).padStart(2, "0")}-${this.getSafeStageName(stageDef.solverName)}`,
+    )
+    const pngPath = this.writePng ? `${basePath}.png` : undefined
+    const svgPath = this.writeSvg ? `${basePath}.svg` : undefined
+    const graphicsJsonPath = this.writeGraphicsJson
+      ? `${basePath}.graphics.json`
+      : undefined
+    const graphics = stageSolver.visualize()
+    const svg = getSvgFromGraphicsObject(graphics, { backgroundColor: "white" })
+
+    if (pngPath) {
+      await writeFile(pngPath, await this.renderGraphicsToPng(graphics))
+    }
+
+    const stepPngPaths =
+      this.writeStepPngs && this.writePng
+        ? await this.writeStepPngsForGraphics(basePath, graphics)
+        : []
+
+    if (svgPath) {
+      await writeFile(svgPath, svg)
+    }
+
+    if (graphicsJsonPath) {
+      await writeFile(graphicsJsonPath, JSON.stringify(graphics, null, 2))
+    }
+
+    this.capturedStageNumbers.add(stageNumber)
+    const artifact = {
+      stageName: stageDef.solverName,
+      stageNumber: stageNumber + 1,
+      pngPath,
+      svgPath,
+      graphicsJsonPath,
+      stepPngPaths,
+    } satisfies PipelineStageArtifact
+    this.stageArtifacts.push(artifact)
+
+    await this.log(
+      `captured stage=${artifact.stageNumber} name=${artifact.stageName} iterations=${stageSolver.iterations ?? 0} png=${pngPath ? this.toDisplayPath(pngPath) : ""} svg=${svgPath ? this.toDisplayPath(svgPath) : ""} steps=${stepPngPaths.length}`,
+    )
+  }
+
+  private async writeStepPngsForGraphics(
+    basePath: string,
+    graphics: GraphicsObject,
+  ): Promise<string[]> {
+    const stepPngPaths: string[] = []
+
+    for (const step of this.getObjectSteps(graphics)) {
+      const stepPngPath = `${basePath}.step-${step}.png`
+      await writeFile(
+        stepPngPath,
+        await this.renderGraphicsToPng(
+          this.filterGraphicsByStep(graphics, step),
+        ),
+      )
+      stepPngPaths.push(stepPngPath)
+    }
+
+    return stepPngPaths
+  }
+
+  private renderGraphicsToPng(graphics: GraphicsObject): Promise<Uint8Array> {
+    return getPngBufferFromGraphicsObject(graphics, {
+      backgroundColor: "white",
+      pngWidth: this.pngWidth,
+      pngHeight: this.pngHeight,
+    })
+  }
+
+  private getObjectSteps(graphics: GraphicsObject): number[] {
+    const steps = new Set<number>()
+    for (const objects of this.getGraphicsObjectArrays(graphics)) {
+      for (const object of objects) {
+        if (typeof object.step === "number") steps.add(object.step)
+      }
+    }
+
+    return [...steps].sort((a, b) => a - b)
+  }
+
+  private filterGraphicsByStep(
+    graphics: GraphicsObject,
+    step: number,
+  ): GraphicsObject {
+    const filtered: Record<string, unknown[]> = {}
+
+    for (const key of Object.keys(graphics)) {
+      const value = (graphics as Record<string, unknown>)[key]
+      filtered[key] = Array.isArray(value)
+        ? value.filter((object) => {
+            return (
+              typeof object === "object" &&
+              object !== null &&
+              (object as { step?: number }).step === step
+            )
+          })
+        : []
+    }
+
+    return filtered as GraphicsObject
+  }
+
+  private getGraphicsObjectArrays(
+    graphics: GraphicsObject,
+  ): Array<Array<{ step?: number }>> {
+    return Object.values(graphics).filter(Array.isArray) as Array<
+      Array<{ step?: number }>
+    >
+  }
+
+  private getStageDef(stageNumber: number): PipelineStepLike | undefined {
+    return this.pipelineSolver.pipelineDef[stageNumber]
+  }
+
+  private getStageSolver(stageName: string): VisualizingSolver | undefined {
+    return (
+      this.pipelineSolver as unknown as Record<string, VisualizingSolver>
+    )[stageName]
+  }
+
+  private getSafeStageName(stageName: string): string {
+    return stageName.replace(/[^a-zA-Z0-9._-]/g, "_")
+  }
+
+  private getStageEnterLogLine(stageName: string, stageNumber: number) {
+    return `enter stage=${stageNumber + 1} name=${stageName}`
+  }
+
+  private async log(line: string) {
+    await writeFile(this.logsPath, `${line}\n`, { flag: "a" })
+    this.onLog?.(line)
+  }
+
+  private toDisplayPath(filePath: string): string {
+    return path.relative(process.cwd(), filePath) || "."
+  }
+
+  private formatError(error: unknown) {
+    if (error instanceof Error) return `${error.name}: ${error.message}`
+    return String(error)
+  }
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@tscircuit/schematic-trace-solver",
   "main": "dist/index.js",
-  "version": "0.0.87",
+  "version": "0.0.88",
   "type": "module",
   "scripts": {
     "start": "cosmos",
+    "debug:pipeline": "bun scripts/debug-pipeline-stages.ts",
     "build": "tsup-node lib/index.ts --format esm --dts",
     "format": "biome format --write .",
     "format:check": "biome format ."
@@ -18,7 +19,7 @@
     "calculate-elbow": "^0.0.12",
     "connectivity-map": "^1.0.0",
     "flatbush": "^4.5.0",
-    "graphics-debug": "^0.0.62",
+    "graphics-debug": "^0.0.96",
     "react": "^19.1.1",
     "react-cosmos": "^7.0.0",
     "react-cosmos-plugin-vite": "^7.0.0",