@tscircuit/cli 0.1.1787 → 0.1.1788

package/README.md

@@ -80,6 +80,30 @@ The `build` command also accepts the following options:
 - `--ignore-placement-drc` - suppress placement DRC diagnostics
 - `--ignore-routing-drc` - suppress routing DRC diagnostics
 
+### Debug autorouting stages
+
+Use `--autorouter-debug` to log each autorouting stage and write visual
+artifacts while the circuit is being routed:
+
+```bash
+tsci build index.circuit.tsx \
+  --autorouter-debug \
+  --autorouter-debug-dir dist/autorouter-debug \
+  --autorouter-dump-srj all
+```
+
+The debug directory contains:
+
+- `placement-unrouted.png` — PCB placement before routing starts.
+- `phase-N-routed.png` — cumulative PCB routing after each zero-indexed stage.
+  A fanout router and its downstream router appear as separate stages.
+- `phase-N.input.simple-route.json` and `phase-N.output.traces.json` when
+  `--autorouter-dump-srj all` is enabled.
+- `board.meta.json` — phase timing and connection-count summary.
+
+Use `--autorouter-dump-srj failed` to keep only failed-stage routing data, or
+`--autorouter-dump-srj phase:N` to capture a single stage.
+
 ## Development
 
 This command will open the `index.tsx` file for editing.

package/dist/cli/build/build.worker.js

@@ -12347,13 +12347,18 @@ class AutorouterDiagnostics {
     return filePath;
   }
   writePngSnapshot(fileName, circuitJson) {
-    const pcbSvg = convertCircuitJsonToPcbSvg(circuitJson);
-    const png = convertSvgToPngBuffer(pcbSvg);
-    const debugDir = path2.resolve(this.options.debugDir ?? DEFAULT_DEBUG_DIR);
-    fs2.mkdirSync(debugDir, { recursive: true });
-    const filePath = path2.join(debugDir, fileName);
-    fs2.writeFileSync(filePath, png);
-    this.logArtifact(filePath);
+    try {
+      const pcbSvg = convertCircuitJsonToPcbSvg(circuitJson);
+      const png = convertSvgToPngBuffer(pcbSvg);
+      const debugDir = path2.resolve(this.options.debugDir ?? DEFAULT_DEBUG_DIR);
+      fs2.mkdirSync(debugDir, { recursive: true });
+      const filePath = path2.join(debugDir, fileName);
+      fs2.writeFileSync(filePath, png);
+      this.logArtifact(filePath);
+    } catch (error) {
+      const serializedError = this.serializeError(error instanceof Error ? error : String(error));
+      this.log(kleur_default.yellow(`Could not write autorouter debug image ${fileName}: ${serializedError.message}`));
+    }
   }
   logArtifact(filePath) {
     this.log(`Wrote debug artifact: ${path2.relative(process.cwd(), filePath)}`);
@@ -12366,7 +12371,8 @@ class AutorouterDiagnostics {
       if (id)
         elementIndexById.set(id, index);
     }
-    for (const trace of this.completedPhaseTraces) {
+    for (const autorouterTrace of this.completedPhaseTraces) {
+      const trace = this.normalizeTraceForPcbSnapshot(autorouterTrace);
       if (!trace || typeof trace !== "object")
         continue;
       const id = this.getCircuitElementId(trace);
@@ -12381,6 +12387,23 @@ class AutorouterDiagnostics {
     }
     return circuitJson;
   }
+  normalizeTraceForPcbSnapshot(trace) {
+    return {
+      ...trace,
+      route: trace.route.map((point) => {
+        if (point.route_type !== "through_obstacle")
+          return point;
+        return {
+          route_type: "through_pad",
+          start: point.start,
+          end: point.end,
+          start_layer: point.from_layer,
+          end_layer: point.to_layer,
+          width: point.width
+        };
+      })
+    };
+  }
   getCircuitElementId(element) {
     const idEntry = Object.entries(element).find(([key, value]) => key === `${element.type}_id` && typeof value === "string");
     const id = idEntry?.[1];

package/dist/cli/main.js

@@ -123144,13 +123144,18 @@ class AutorouterDiagnostics {
     return filePath;
   }
   writePngSnapshot(fileName, circuitJson) {
-    const pcbSvg = convertCircuitJsonToPcbSvg(circuitJson);
-    const png = convertSvgToPngBuffer(pcbSvg);
-    const debugDir = path17.resolve(this.options.debugDir ?? DEFAULT_DEBUG_DIR);
-    fs17.mkdirSync(debugDir, { recursive: true });
-    const filePath = path17.join(debugDir, fileName);
-    fs17.writeFileSync(filePath, png);
-    this.logArtifact(filePath);
+    try {
+      const pcbSvg = convertCircuitJsonToPcbSvg(circuitJson);
+      const png = convertSvgToPngBuffer(pcbSvg);
+      const debugDir = path17.resolve(this.options.debugDir ?? DEFAULT_DEBUG_DIR);
+      fs17.mkdirSync(debugDir, { recursive: true });
+      const filePath = path17.join(debugDir, fileName);
+      fs17.writeFileSync(filePath, png);
+      this.logArtifact(filePath);
+    } catch (error) {
+      const serializedError = this.serializeError(error instanceof Error ? error : String(error));
+      this.log(kleur_default.yellow(`Could not write autorouter debug image ${fileName}: ${serializedError.message}`));
+    }
   }
   logArtifact(filePath) {
     this.log(`Wrote debug artifact: ${path17.relative(process.cwd(), filePath)}`);
@@ -123163,7 +123168,8 @@ class AutorouterDiagnostics {
       if (id)
         elementIndexById.set(id, index);
     }
-    for (const trace of this.completedPhaseTraces) {
+    for (const autorouterTrace of this.completedPhaseTraces) {
+      const trace = this.normalizeTraceForPcbSnapshot(autorouterTrace);
       if (!trace || typeof trace !== "object")
         continue;
       const id = this.getCircuitElementId(trace);
@@ -123178,6 +123184,23 @@ class AutorouterDiagnostics {
     }
     return circuitJson;
   }
+  normalizeTraceForPcbSnapshot(trace) {
+    return {
+      ...trace,
+      route: trace.route.map((point) => {
+        if (point.route_type !== "through_obstacle")
+          return point;
+        return {
+          route_type: "through_pad",
+          start: point.start,
+          end: point.end,
+          start_layer: point.from_layer,
+          end_layer: point.to_layer,
+          width: point.width
+        };
+      })
+    };
+  }
   getCircuitElementId(element) {
     const idEntry = Object.entries(element).find(([key, value]) => key === `${element.type}_id` && typeof value === "string");
     const id = idEntry?.[1];
@@ -135250,7 +135273,7 @@ var parseInjectedProps = ({
   return parsed;
 };
 var registerBuild = (program2) => {
-  program2.command("build").description("Run tscircuit eval and output circuit json").argument("[file]", "Path to the entry file").option("--ci", "Run install and optional prebuild/build commands (or default CI build)").option("--ignore-errors", "Do not exit with code 1 on errors").option("--ignore-warnings", "Do not log warnings").option("--ignore-netlist-drc", "Ignore netlist DRC errors/warnings").option("--ignore-pin-specification-drc", "Ignore pin-specification DRC errors/warnings").option("--ignore-placement-drc", "Ignore placement DRC errors/warnings").option("--ignore-routing-drc", "Ignore routing DRC errors/warnings").option("--ignore-config", "Ignore options from tscircuit.config.json").option("--disable-pcb", "Disable PCB outputs").option("--routing-disabled", "Disable routing during circuit generation").option("--disable-parts-engine", "Disable the parts engine").option("--site", "Generate a static site in the dist directory").option("--transpile", "Transpile the entry file to JavaScript").option("--preview-images", "Generate preview images in the dist directory").option("--all-images", "Generate preview images for every successful build output").option("--pngs", "Generate PNG outputs during build generation").option("--pcb-png", "Generate PCB PNG outputs during build generation").option("--schematic-png", "Generate schematic PNG outputs during build generation").option("--svgs", "Generate SVG outputs during build generation").option("--pcb-svgs", "Generate PCB SVG outputs during build generation").option("--schematic-svgs", "Generate schematic SVG outputs during build generation").option("--simulation-svgs", "Generate simulation graph SVG outputs during build generation").option("--simulation-schematic-svgs", "Generate schematic simulation SVG outputs during build generation").option("--3d-png", "Generate 3D PNG outputs during build generation").option("--3d", "Generate 3D PNG outputs during build generation").option("--pcb-only", "Generate only PCB SVG outputs during build generation").option("--schematic-only", "Generate only schematic SVG outputs during build generation").option("--kicad-project", "Generate KiCad project directories for each successful build output").option("--kicad-project-zip", "Generate a zipped KiCad project for each successful build output").option("--kicad-library", "Generate KiCad library in dist/kicad-library").option("--kicad-library-name <name>", "Specify the name of the KiCad library").option("--preview-gltf", "Generate a GLTF file from the preview entrypoint").option("--show-courtyards", "Show courtyard outlines in PCB SVG outputs").option("--glbs", "Generate GLB 3D model files for every successful build").option("--step", "Generate STEP 3D model files for every successful build").option("--profile", "Log per-circuit circuit.json generation time during build").option("--autorouter-debug", "Log autorouting phase diagnostics during circuit generation").option("--autorouter-timeout <duration>", 'Abort an autorouting phase after a duration, e.g. "120s" or "2m"').option("--autorouter-debug-dir <path>", "Directory for autorouting debug artifacts (default: dist/autorouter-debug)").option("--autorouter-dump-srj [mode]", 'Dump SimpleRouteJson inputs/outputs: "all", "failed", or "phase:<index>" (default: failed)').option("--kicad-pcm", "Generate KiCad PCM (Plugin and Content Manager) assets in dist/pcm").option("--use-cdn-javascript", "Use CDN-hosted JavaScript instead of bundled standalone file for --site").option("--concurrency <number>", "Number of files to build in parallel (default: 1)", "1").option("--inject-props <json>", "Inject JSON props into the built file's default export").option("--inject-props-file <path>", "Inject JSON props from a file into the built file's default export").action(async (file, options) => {
+  program2.command("build").description("Run tscircuit eval and output circuit json").argument("[file]", "Path to the entry file").option("--ci", "Run install and optional prebuild/build commands (or default CI build)").option("--ignore-errors", "Do not exit with code 1 on errors").option("--ignore-warnings", "Do not log warnings").option("--ignore-netlist-drc", "Ignore netlist DRC errors/warnings").option("--ignore-pin-specification-drc", "Ignore pin-specification DRC errors/warnings").option("--ignore-placement-drc", "Ignore placement DRC errors/warnings").option("--ignore-routing-drc", "Ignore routing DRC errors/warnings").option("--ignore-config", "Ignore options from tscircuit.config.json").option("--disable-pcb", "Disable PCB outputs").option("--routing-disabled", "Disable routing during circuit generation").option("--disable-parts-engine", "Disable the parts engine").option("--site", "Generate a static site in the dist directory").option("--transpile", "Transpile the entry file to JavaScript").option("--preview-images", "Generate preview images in the dist directory").option("--all-images", "Generate preview images for every successful build output").option("--pngs", "Generate PNG outputs during build generation").option("--pcb-png", "Generate PCB PNG outputs during build generation").option("--schematic-png", "Generate schematic PNG outputs during build generation").option("--svgs", "Generate SVG outputs during build generation").option("--pcb-svgs", "Generate PCB SVG outputs during build generation").option("--schematic-svgs", "Generate schematic SVG outputs during build generation").option("--simulation-svgs", "Generate simulation graph SVG outputs during build generation").option("--simulation-schematic-svgs", "Generate schematic simulation SVG outputs during build generation").option("--3d-png", "Generate 3D PNG outputs during build generation").option("--3d", "Generate 3D PNG outputs during build generation").option("--pcb-only", "Generate only PCB SVG outputs during build generation").option("--schematic-only", "Generate only schematic SVG outputs during build generation").option("--kicad-project", "Generate KiCad project directories for each successful build output").option("--kicad-project-zip", "Generate a zipped KiCad project for each successful build output").option("--kicad-library", "Generate KiCad library in dist/kicad-library").option("--kicad-library-name <name>", "Specify the name of the KiCad library").option("--preview-gltf", "Generate a GLTF file from the preview entrypoint").option("--show-courtyards", "Show courtyard outlines in PCB SVG outputs").option("--glbs", "Generate GLB 3D model files for every successful build").option("--step", "Generate STEP 3D model files for every successful build").option("--profile", "Log per-circuit circuit.json generation time during build").option("--autorouter-debug", "Log autorouting phases and write unrouted/per-phase PNG artifacts").option("--autorouter-timeout <duration>", 'Abort an autorouting phase after a duration, e.g. "120s" or "2m"').option("--autorouter-debug-dir <path>", "Directory for autorouting debug artifacts (default: dist/autorouter-debug)").option("--autorouter-dump-srj [mode]", 'Dump SimpleRouteJson inputs/outputs: "all", "failed", or "phase:<index>" (default: failed)').option("--kicad-pcm", "Generate KiCad PCM (Plugin and Content Manager) assets in dist/pcm").option("--use-cdn-javascript", "Use CDN-hosted JavaScript instead of bundled standalone file for --site").option("--concurrency <number>", "Number of files to build in parallel (default: 1)", "1").option("--inject-props <json>", "Inject JSON props into the built file's default export").option("--inject-props-file <path>", "Inject JSON props from a file into the built file's default export").action(async (file, options) => {
     try {
       const transpileExplicitlyRequested = options?.transpile === true;
       const resolvedRoot = path44.resolve(process.cwd());
@@ -284937,7 +284960,7 @@ var checkTraceLength = async (pinOrNetRef, file, options = {}) => {
   return analysis.toString();
 };
 var registerCheckTraceLength = (program2) => {
-  program2.commands.find((c3) => c3.name() === "check").command("trace-length").description("Analyze trace length for a pin or net").argument("<pinOrNetRef>", "Pin or net target to analyze").argument("[file]", "Path to the entry file").option("--autorouter-debug", "Log autorouting phase diagnostics during circuit generation").option("--autorouter-timeout <duration>", 'Abort an autorouting phase after a duration, e.g. "120s" or "2m"').option("--autorouter-debug-dir <path>", "Directory for autorouting debug artifacts (default: dist/autorouter-debug)").option("--autorouter-dump-srj [mode]", 'Dump SimpleRouteJson inputs/outputs: "all", "failed", or "phase:<index>" (default: failed)').action(async (pinOrNetRef, file, options) => {
+  program2.commands.find((c3) => c3.name() === "check").command("trace-length").description("Analyze trace length for a pin or net").argument("<pinOrNetRef>", "Pin or net target to analyze").argument("[file]", "Path to the entry file").option("--autorouter-debug", "Log autorouting phases and write unrouted/per-phase PNG artifacts").option("--autorouter-timeout <duration>", 'Abort an autorouting phase after a duration, e.g. "120s" or "2m"').option("--autorouter-debug-dir <path>", "Directory for autorouting debug artifacts (default: dist/autorouter-debug)").option("--autorouter-dump-srj [mode]", 'Dump SimpleRouteJson inputs/outputs: "all", "failed", or "phase:<index>" (default: failed)').action(async (pinOrNetRef, file, options) => {
     try {
       const output = await checkTraceLength(pinOrNetRef, file, options);
       console.log(output);

package/dist/cli/snapshot/snapshot.worker.js

@@ -3300,13 +3300,18 @@ class AutorouterDiagnostics {
     return filePath;
   }
   writePngSnapshot(fileName, circuitJson) {
-    const pcbSvg = convertCircuitJsonToPcbSvg(circuitJson);
-    const png = convertSvgToPngBuffer(pcbSvg);
-    const debugDir = path2.resolve(this.options.debugDir ?? DEFAULT_DEBUG_DIR);
-    fs2.mkdirSync(debugDir, { recursive: true });
-    const filePath = path2.join(debugDir, fileName);
-    fs2.writeFileSync(filePath, png);
-    this.logArtifact(filePath);
+    try {
+      const pcbSvg = convertCircuitJsonToPcbSvg(circuitJson);
+      const png = convertSvgToPngBuffer(pcbSvg);
+      const debugDir = path2.resolve(this.options.debugDir ?? DEFAULT_DEBUG_DIR);
+      fs2.mkdirSync(debugDir, { recursive: true });
+      const filePath = path2.join(debugDir, fileName);
+      fs2.writeFileSync(filePath, png);
+      this.logArtifact(filePath);
+    } catch (error) {
+      const serializedError = this.serializeError(error instanceof Error ? error : String(error));
+      this.log(kleur_default.yellow(`Could not write autorouter debug image ${fileName}: ${serializedError.message}`));
+    }
   }
   logArtifact(filePath) {
     this.log(`Wrote debug artifact: ${path2.relative(process.cwd(), filePath)}`);
@@ -3319,7 +3324,8 @@ class AutorouterDiagnostics {
       if (id)
         elementIndexById.set(id, index);
     }
-    for (const trace of this.completedPhaseTraces) {
+    for (const autorouterTrace of this.completedPhaseTraces) {
+      const trace = this.normalizeTraceForPcbSnapshot(autorouterTrace);
       if (!trace || typeof trace !== "object")
         continue;
       const id = this.getCircuitElementId(trace);
@@ -3334,6 +3340,23 @@ class AutorouterDiagnostics {
     }
     return circuitJson;
   }
+  normalizeTraceForPcbSnapshot(trace) {
+    return {
+      ...trace,
+      route: trace.route.map((point) => {
+        if (point.route_type !== "through_obstacle")
+          return point;
+        return {
+          route_type: "through_pad",
+          start: point.start,
+          end: point.end,
+          start_layer: point.from_layer,
+          end_layer: point.to_layer,
+          width: point.width
+        };
+      })
+    };
+  }
   getCircuitElementId(element) {
     const idEntry = Object.entries(element).find(([key, value]) => key === `${element.type}_id` && typeof value === "string");
     const id = idEntry?.[1];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tscircuit/cli",
-  "version": "0.1.1787",
+  "version": "0.1.1788",
   "main": "dist/cli/main.js",
   "exports": {
     ".": "./dist/cli/main.js",