@tscircuit/cli 0.1.1835 → 0.1.1836

package/README.md

@@ -126,6 +126,10 @@ The debug directory contains:
 Use `--autorouter-dump-srj failed` to keep only failed-stage routing data, or
 `--autorouter-dump-srj phase:N` to capture a single stage.
 
+Use `--autorouter-phase <name>` to enable the debugger automatically and keep
+debugging through the named `<autoroutingphase name="..." />`. Later phases
+are left out of the debug artifacts.
+
 ### Debug solver inputs
 
 Use `--solver-debug` to record the constructor inputs for every solver that

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

@@ -12017,6 +12017,13 @@ var parseAutorouterTimeout = (duration) => {
   }
   return timeoutMs;
 };
+var parseAutorouterPhaseName = (value) => {
+  const phaseName = value.trim();
+  if (!phaseName) {
+    throw new Error("Invalid --autorouter-phase value. The phase name must not be empty.");
+  }
+  return phaseName;
+};
 var parseAutorouterDumpSrjMode = (value) => {
   if (value === undefined || value === false)
     return;
@@ -12046,17 +12053,21 @@ class AutorouterDiagnostics {
   activePhase = null;
   completedPhaseTraces = [];
   hasWrittenPlacementSnapshot = false;
+  targetPhaseReached = false;
   summary = [];
   rootCircuit;
   constructor(options = {}) {
+    const phaseName = options.phaseName?.trim() || undefined;
     this.options = {
       ...options,
+      enabled: options.enabled || phaseName !== undefined,
+      phaseName,
       debugDir: options.debugDir ?? DEFAULT_DEBUG_DIR,
       log: options.log ?? console.log
     };
   }
   get isActive() {
-    return Boolean(this.options.enabled || this.options.timeoutMs || this.options.dumpSrj || this.options.logOnError || this.options.longRunningLogThresholdMs);
+    return Boolean(this.options.enabled || this.options.phaseName || this.options.timeoutMs || this.options.dumpSrj || this.options.logOnError || this.options.longRunningLogThresholdMs);
   }
   attachToRootCircuit(rootCircuit) {
     if (!this.isActive)
@@ -12089,10 +12100,14 @@ class AutorouterDiagnostics {
       generatedAt: new Date().toISOString(),
       phaseCount: this.summary.length,
       phases: this.summary,
-      circuitJsonElementCount: circuitJson?.length
+      circuitJsonElementCount: circuitJson?.length,
+      targetPhaseName: this.options.phaseName,
+      targetPhaseReached: this.targetPhaseReached
     });
   }
   handleStart(event) {
+    if (this.targetPhaseReached)
+      return;
     const simpleRouteJson = event.simpleRouteJson;
     const subcircuitId = event.subcircuit_id ?? event.subcircuitId ?? "unknown-subcircuit";
     const previousOrdinal = this.phaseOrdinalBySubcircuit.get(subcircuitId) ?? 0;
@@ -12105,6 +12120,9 @@ class AutorouterDiagnostics {
     this.activePhase = {
       subcircuitId,
       componentDisplayName: event.componentDisplayName ?? "subcircuit",
+      phaseName: event.phaseName,
+      phaseStageIndex: event.phaseStageIndex,
+      phaseStageCount: event.phaseStageCount,
       routingPhaseIndex,
       phaseOrdinal,
       phaseCount: event.phaseCount,
@@ -12159,6 +12177,9 @@ class AutorouterDiagnostics {
     this.summary.push({
       subcircuit_id: activePhase.subcircuitId,
       componentDisplayName: activePhase.componentDisplayName,
+      phaseName: activePhase.phaseName,
+      phaseStageIndex: activePhase.phaseStageIndex,
+      phaseStageCount: activePhase.phaseStageCount,
       routingPhaseIndex: activePhase.routingPhaseIndex,
       phaseOrdinal: activePhase.phaseOrdinal,
       phaseCount: activePhase.phaseCount,
@@ -12189,6 +12210,9 @@ class AutorouterDiagnostics {
     if (this.options.enabled) {
       this.writePngSnapshot(`phase-${activePhase.routingPhaseIndex}-routed.png`, this.getCircuitJsonWithCompletedPhaseTraces());
     }
+    if (this.isFinalTargetPhaseStage(activePhase)) {
+      this.targetPhaseReached = true;
+    }
     if (this.activePhase === activePhase) {
       this.activePhase = null;
     }
@@ -12202,6 +12226,9 @@ class AutorouterDiagnostics {
     this.summary.push({
       subcircuit_id: activePhase.subcircuitId,
       componentDisplayName: activePhase.componentDisplayName,
+      phaseName: activePhase.phaseName,
+      phaseStageIndex: activePhase.phaseStageIndex,
+      phaseStageCount: activePhase.phaseStageCount,
       routingPhaseIndex: activePhase.routingPhaseIndex,
       phaseOrdinal: activePhase.phaseOrdinal,
       phaseCount: activePhase.phaseCount,
@@ -12225,6 +12252,9 @@ class AutorouterDiagnostics {
         type: "autorouter_phase_error",
         subcircuit_id: activePhase.subcircuitId,
         routingPhaseIndex: activePhase.routingPhaseIndex,
+        phaseName: activePhase.phaseName,
+        phaseStageIndex: activePhase.phaseStageIndex,
+        phaseStageCount: activePhase.phaseStageCount,
         phaseOrdinal: activePhase.phaseOrdinal,
         phaseCount: activePhase.phaseCount,
         elapsedMs: Math.round(elapsedMs),
@@ -12234,6 +12264,9 @@ class AutorouterDiagnostics {
         error
       });
     }
+    if (this.isFinalTargetPhaseStage(activePhase)) {
+      this.targetPhaseReached = true;
+    }
     if (this.activePhase === activePhase) {
       this.activePhase = null;
     }
@@ -12251,6 +12284,9 @@ class AutorouterDiagnostics {
       subcircuit_id: activePhase.subcircuitId,
       componentDisplayName: activePhase.componentDisplayName,
       routingPhaseIndex: activePhase.routingPhaseIndex,
+      phaseName: activePhase.phaseName,
+      phaseStageIndex: activePhase.phaseStageIndex,
+      phaseStageCount: activePhase.phaseStageCount,
       phaseOrdinal: activePhase.phaseOrdinal,
       phaseCount: activePhase.phaseCount,
       elapsedMs: Math.round(elapsedMs),
@@ -12422,10 +12458,22 @@ class AutorouterDiagnostics {
     return `phase-${phaseNumber}.${suffix}`;
   }
   getPhaseLabel(activePhase) {
+    const phaseName = activePhase.phaseName ? ` "${activePhase.phaseName}"` : "";
+    const stageLabel = activePhase.phaseStageIndex !== undefined && activePhase.phaseStageCount !== undefined && activePhase.phaseStageCount > 1 ? ` stage ${activePhase.phaseStageIndex + 1}/${activePhase.phaseStageCount}` : "";
     if (activePhase.phaseCount) {
-      return `phase ${activePhase.phaseOrdinal}/${activePhase.phaseCount}`;
+      return `phase ${activePhase.phaseOrdinal}/${activePhase.phaseCount}${phaseName}${stageLabel}`;
+    }
+    return `phase ${activePhase.phaseOrdinal}${phaseName}${stageLabel}`;
+  }
+  isFinalTargetPhaseStage(activePhase) {
+    if (!this.options.phaseName)
+      return false;
+    if (activePhase.phaseName !== this.options.phaseName)
+      return false;
+    if (activePhase.phaseStageIndex === undefined || activePhase.phaseStageCount === undefined) {
+      return true;
     }
-    return `phase ${activePhase.phaseOrdinal}`;
+    return activePhase.phaseStageIndex >= activePhase.phaseStageCount - 1;
   }
   formatElapsed(elapsedMs) {
     if (elapsedMs < 1000)

package/dist/cli/main.js

@@ -135252,7 +135252,7 @@ var import_perfect_cli = __toESM2(require_dist2(), 1);
 // lib/getVersion.ts
 import { createRequire as createRequire2 } from "node:module";
 // package.json
-var version = "0.1.1834";
+var version = "0.1.1835";
 var package_default = {
   name: "@tscircuit/cli",
   version,
@@ -139561,6 +139561,13 @@ var parseAutorouterTimeout = (duration) => {
   }
   return timeoutMs;
 };
+var parseAutorouterPhaseName = (value) => {
+  const phaseName = value.trim();
+  if (!phaseName) {
+    throw new Error("Invalid --autorouter-phase value. The phase name must not be empty.");
+  }
+  return phaseName;
+};
 var parseAutorouterDumpSrjMode = (value) => {
   if (value === undefined || value === false)
     return;
@@ -139590,17 +139597,21 @@ class AutorouterDiagnostics {
   activePhase = null;
   completedPhaseTraces = [];
   hasWrittenPlacementSnapshot = false;
+  targetPhaseReached = false;
   summary = [];
   rootCircuit;
   constructor(options = {}) {
+    const phaseName = options.phaseName?.trim() || undefined;
     this.options = {
       ...options,
+      enabled: options.enabled || phaseName !== undefined,
+      phaseName,
       debugDir: options.debugDir ?? DEFAULT_DEBUG_DIR,
       log: options.log ?? console.log
     };
   }
   get isActive() {
-    return Boolean(this.options.enabled || this.options.timeoutMs || this.options.dumpSrj || this.options.logOnError || this.options.longRunningLogThresholdMs);
+    return Boolean(this.options.enabled || this.options.phaseName || this.options.timeoutMs || this.options.dumpSrj || this.options.logOnError || this.options.longRunningLogThresholdMs);
   }
   attachToRootCircuit(rootCircuit) {
     if (!this.isActive)
@@ -139633,10 +139644,14 @@ class AutorouterDiagnostics {
       generatedAt: new Date().toISOString(),
       phaseCount: this.summary.length,
       phases: this.summary,
-      circuitJsonElementCount: circuitJson?.length
+      circuitJsonElementCount: circuitJson?.length,
+      targetPhaseName: this.options.phaseName,
+      targetPhaseReached: this.targetPhaseReached
     });
   }
   handleStart(event) {
+    if (this.targetPhaseReached)
+      return;
     const simpleRouteJson = event.simpleRouteJson;
     const subcircuitId = event.subcircuit_id ?? event.subcircuitId ?? "unknown-subcircuit";
     const previousOrdinal = this.phaseOrdinalBySubcircuit.get(subcircuitId) ?? 0;
@@ -139649,6 +139664,9 @@ class AutorouterDiagnostics {
     this.activePhase = {
       subcircuitId,
       componentDisplayName: event.componentDisplayName ?? "subcircuit",
+      phaseName: event.phaseName,
+      phaseStageIndex: event.phaseStageIndex,
+      phaseStageCount: event.phaseStageCount,
       routingPhaseIndex,
       phaseOrdinal,
       phaseCount: event.phaseCount,
@@ -139703,6 +139721,9 @@ class AutorouterDiagnostics {
     this.summary.push({
       subcircuit_id: activePhase.subcircuitId,
       componentDisplayName: activePhase.componentDisplayName,
+      phaseName: activePhase.phaseName,
+      phaseStageIndex: activePhase.phaseStageIndex,
+      phaseStageCount: activePhase.phaseStageCount,
       routingPhaseIndex: activePhase.routingPhaseIndex,
       phaseOrdinal: activePhase.phaseOrdinal,
       phaseCount: activePhase.phaseCount,
@@ -139733,6 +139754,9 @@ class AutorouterDiagnostics {
     if (this.options.enabled) {
       this.writePngSnapshot(`phase-${activePhase.routingPhaseIndex}-routed.png`, this.getCircuitJsonWithCompletedPhaseTraces());
     }
+    if (this.isFinalTargetPhaseStage(activePhase)) {
+      this.targetPhaseReached = true;
+    }
     if (this.activePhase === activePhase) {
       this.activePhase = null;
     }
@@ -139746,6 +139770,9 @@ class AutorouterDiagnostics {
     this.summary.push({
       subcircuit_id: activePhase.subcircuitId,
       componentDisplayName: activePhase.componentDisplayName,
+      phaseName: activePhase.phaseName,
+      phaseStageIndex: activePhase.phaseStageIndex,
+      phaseStageCount: activePhase.phaseStageCount,
       routingPhaseIndex: activePhase.routingPhaseIndex,
       phaseOrdinal: activePhase.phaseOrdinal,
       phaseCount: activePhase.phaseCount,
@@ -139769,6 +139796,9 @@ class AutorouterDiagnostics {
         type: "autorouter_phase_error",
         subcircuit_id: activePhase.subcircuitId,
         routingPhaseIndex: activePhase.routingPhaseIndex,
+        phaseName: activePhase.phaseName,
+        phaseStageIndex: activePhase.phaseStageIndex,
+        phaseStageCount: activePhase.phaseStageCount,
         phaseOrdinal: activePhase.phaseOrdinal,
         phaseCount: activePhase.phaseCount,
         elapsedMs: Math.round(elapsedMs),
@@ -139778,6 +139808,9 @@ class AutorouterDiagnostics {
         error
       });
     }
+    if (this.isFinalTargetPhaseStage(activePhase)) {
+      this.targetPhaseReached = true;
+    }
     if (this.activePhase === activePhase) {
       this.activePhase = null;
     }
@@ -139795,6 +139828,9 @@ class AutorouterDiagnostics {
       subcircuit_id: activePhase.subcircuitId,
       componentDisplayName: activePhase.componentDisplayName,
       routingPhaseIndex: activePhase.routingPhaseIndex,
+      phaseName: activePhase.phaseName,
+      phaseStageIndex: activePhase.phaseStageIndex,
+      phaseStageCount: activePhase.phaseStageCount,
       phaseOrdinal: activePhase.phaseOrdinal,
       phaseCount: activePhase.phaseCount,
       elapsedMs: Math.round(elapsedMs),
@@ -139966,10 +140002,22 @@ class AutorouterDiagnostics {
     return `phase-${phaseNumber}.${suffix}`;
   }
   getPhaseLabel(activePhase) {
+    const phaseName = activePhase.phaseName ? ` "${activePhase.phaseName}"` : "";
+    const stageLabel = activePhase.phaseStageIndex !== undefined && activePhase.phaseStageCount !== undefined && activePhase.phaseStageCount > 1 ? ` stage ${activePhase.phaseStageIndex + 1}/${activePhase.phaseStageCount}` : "";
     if (activePhase.phaseCount) {
-      return `phase ${activePhase.phaseOrdinal}/${activePhase.phaseCount}`;
+      return `phase ${activePhase.phaseOrdinal}/${activePhase.phaseCount}${phaseName}${stageLabel}`;
+    }
+    return `phase ${activePhase.phaseOrdinal}${phaseName}${stageLabel}`;
+  }
+  isFinalTargetPhaseStage(activePhase) {
+    if (!this.options.phaseName)
+      return false;
+    if (activePhase.phaseName !== this.options.phaseName)
+      return false;
+    if (activePhase.phaseStageIndex === undefined || activePhase.phaseStageCount === undefined) {
+      return true;
     }
-    return `phase ${activePhase.phaseOrdinal}`;
+    return activePhase.phaseStageIndex >= activePhase.phaseStageCount - 1;
   }
   formatElapsed(elapsedMs) {
     if (elapsedMs < 1000)
@@ -152276,7 +152324,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 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("--solver-debug", "Write constructor inputs for every solver event emitted during the build").option("--solver-debug-dir <path>", "Directory for solver input artifacts (default: dist/solver-debug)").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-phase <name>", "Enable autorouting debugging through the named phase").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("--solver-debug", "Write constructor inputs for every solver event emitted during the build").option("--solver-debug-dir <path>", "Directory for solver input artifacts (default: dist/solver-debug)").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 = path45.resolve(process.cwd());
@@ -152342,10 +152390,12 @@ var registerBuild = (program2) => {
       const distDir = path45.join(projectDir, "dist");
       fs42.mkdirSync(distDir, { recursive: true });
       const autorouterTimeoutMs = resolvedOptions?.autorouterTimeout ? parseAutorouterTimeout(resolvedOptions.autorouterTimeout) : undefined;
+      const autorouterPhaseName = resolvedOptions?.autorouterPhase !== undefined ? parseAutorouterPhaseName(resolvedOptions.autorouterPhase) : undefined;
       const autorouterDumpSrj = parseAutorouterDumpSrjMode(resolvedOptions?.autorouterDumpSrj);
       const autorouterDebugDir = resolvedOptions?.autorouterDebugDir ? path45.resolve(projectDir, resolvedOptions.autorouterDebugDir) : path45.join(distDir, "autorouter-debug");
       const autorouterDiagnostics = {
-        enabled: resolvedOptions?.autorouterDebug,
+        enabled: resolvedOptions?.autorouterDebug || autorouterPhaseName !== undefined,
+        phaseName: autorouterPhaseName,
         timeoutMs: autorouterTimeoutMs,
         debugDir: autorouterDebugDir,
         dumpSrj: autorouterDumpSrj,
@@ -152808,6 +152858,7 @@ var registerBuild = (program2) => {
         resolvedOptions?.previewGltf && "preview-gltf",
         resolvedOptions?.profile && "profile",
         resolvedOptions?.autorouterDebug && "autorouter-debug",
+        resolvedOptions?.autorouterPhase && "autorouter-phase",
         resolvedOptions?.autorouterTimeout && "autorouter-timeout",
         resolvedOptions?.autorouterDumpSrj && "autorouter-dump-srj",
         resolvedOptions?.solverDebug && "solver-debug"
@@ -302039,10 +302090,12 @@ var loadTraceLengthAnalyzer = async () => {
 };
 var getAutorouterDiagnosticsOptions = (options = {}) => {
   const timeoutMs = options.autorouterTimeout ? parseAutorouterTimeout(options.autorouterTimeout) : undefined;
+  const phaseName = options.autorouterPhase !== undefined ? parseAutorouterPhaseName(options.autorouterPhase) : undefined;
   const dumpSrj = parseAutorouterDumpSrjMode(options.autorouterDumpSrj);
   const debugDir = options.autorouterDebugDir ? path50.resolve(process.cwd(), options.autorouterDebugDir) : path50.resolve(process.cwd(), "dist", "autorouter-debug");
   return {
-    enabled: options.autorouterDebug,
+    enabled: options.autorouterDebug || phaseName !== undefined,
+    phaseName,
     timeoutMs,
     debugDir,
     dumpSrj,
@@ -302068,7 +302121,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 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) => {
+  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-phase <name>", "Enable autorouting debugging through the named phase").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);
@@ -308823,6 +308876,7 @@ var CIRCUIT_JSON_ID_PATTERN3 = /\b(?:source|pcb|schematic|subcircuit|cad|simulat
 var formatAutorouterDebugEvent = (event) => {
   const parts = [
     typeof event.componentDisplayName === "string" ? `component=${event.componentDisplayName}` : null,
+    typeof event.phaseName === "string" ? `autorouter_phase=${event.phaseName}` : null,
     typeof event.phase === "string" ? `phase=${event.phase}` : null,
     typeof event.solverName === "string" ? `solver=${event.solverName}` : null,
     typeof event.connectionCount === "number" ? `connections=${event.connectionCount}` : null,
@@ -308849,23 +308903,27 @@ class DevServer {
   ignoredFiles;
   kicadPcm;
   autorouterDebug;
+  autorouterPhase;
   httpServer;
   eventsWatcher;
   fsKy;
   filesystemWatcher;
   uploadedNodeModules = new Set;
+  autorouterPhaseReached = false;
   constructor({
     port,
     componentFilePath,
     projectDir,
     kicadPcm,
-    autorouterDebug
+    autorouterDebug,
+    autorouterPhase
   }) {
     this.port = port;
     this.componentFilePath = componentFilePath;
     this.projectDir = projectDir ?? path66.dirname(componentFilePath);
     this.kicadPcm = kicadPcm ?? false;
     this.autorouterDebug = autorouterDebug ?? false;
+    this.autorouterPhase = autorouterPhase?.trim() || undefined;
     const projectConfig2 = loadProjectConfig(this.projectDir);
     this.ignoredFiles = projectConfig2?.ignoredFiles ?? [];
     this.fsKy = distribution_default.create({
@@ -308892,7 +308950,12 @@ class DevServer {
       this.eventsWatcher.on("*", (event) => {
         if (!String(event.event_type).startsWith("autorouting:"))
           return;
+        if (this.autorouterPhaseReached)
+          return;
         console.log(kleur_default.cyan(formatAutorouterDebugEvent(event)));
+        if (event.event_type === "autorouting:end" && event.phaseName === this.autorouterPhase && (event.phaseStageIndex === undefined || event.phaseStageCount === undefined || event.phaseStageIndex >= event.phaseStageCount - 1)) {
+          this.autorouterPhaseReached = true;
+        }
       });
     }
     this.filesystemWatcher = watch(this.projectDir, {
@@ -308910,6 +308973,7 @@ class DevServer {
   async handleFileUpdatedEventFromServer(ev2) {
     if (ev2.initiator === "filesystem_change")
       return;
+    this.autorouterPhaseReached = false;
     const { file } = await this.fsKy.get("api/files/get", {
       searchParams: { file_path: ev2.file_path }
     }).json();
@@ -308938,6 +309002,7 @@ class DevServer {
       return;
     if (shouldIgnorePath(relativeFilePath, this.ignoredFiles))
       return;
+    this.autorouterPhaseReached = false;
     const filePayload = this.createFileUploadPayload(absoluteFilePath, relativeFilePath);
     console.log(kleur_default.green(`Saving: ${relativeFilePath}`));
     await this.postFileUpsert({
@@ -308971,6 +309036,7 @@ class DevServer {
     const relativeFilePath = path66.relative(this.projectDir, absoluteFilePath);
     if (shouldIgnorePath(relativeFilePath, this.ignoredFiles))
       return;
+    this.autorouterPhaseReached = false;
     if (!relativeFilePath || relativeFilePath.trim() === "") {
       debug13("Skipping delete for empty file path");
       return;
@@ -309211,7 +309277,7 @@ var warnIfTsconfigMissingTscircuitType = (projectDir) => {
   } catch {}
 };
 var registerDev = (program2) => {
-  program2.command("dev").description("Start development server for a package").argument("[file]", "Path to the package file or directory").option("-p, --port <number>", "Port to run server on", "3020").option("--kicad-pcm", "Enable KiCad PCM proxy server at /pcm/*").option("--autorouter-debug", "Log autorouting diagnostics emitted by the dev runframe").option("--autorouter-timeout <duration>", "Accepted for parity with build; dev autorouting timeouts are handled in the browser runframe").option("--autorouter-debug-dir <path>", "Accepted for parity with build; dev debug artifacts are handled in the browser runframe").option("--autorouter-dump-srj [mode]", "Accepted for parity with build; dev SRJ downloads are handled in the browser runframe").action(async (file, options) => {
+  program2.command("dev").description("Start development server for a package").argument("[file]", "Path to the package file or directory").option("-p, --port <number>", "Port to run server on", "3020").option("--kicad-pcm", "Enable KiCad PCM proxy server at /pcm/*").option("--autorouter-debug", "Log autorouting diagnostics emitted by the dev runframe").option("--autorouter-phase <name>", "Log autorouting diagnostics through the named phase").option("--autorouter-timeout <duration>", "Accepted for parity with build; dev autorouting timeouts are handled in the browser runframe").option("--autorouter-debug-dir <path>", "Accepted for parity with build; dev debug artifacts are handled in the browser runframe").option("--autorouter-dump-srj [mode]", "Accepted for parity with build; dev SRJ downloads are handled in the browser runframe").action(async (file, options) => {
     let port = parseInt(options.port);
     const startTime = Date.now();
     while (!await isPortAvailable(port)) {
@@ -309222,13 +309288,15 @@ var registerDev = (program2) => {
     if (!target)
       return;
     const { absolutePath, projectDir } = target;
+    const autorouterPhase = options.autorouterPhase !== undefined ? parseAutorouterPhaseName(options.autorouterPhase) : undefined;
     warnIfTsconfigMissingTscircuitType(projectDir);
     const server = new DevServer({
       port,
       componentFilePath: absolutePath,
       projectDir,
       kicadPcm: options.kicadPcm,
-      autorouterDebug: options.autorouterDebug
+      autorouterDebug: options.autorouterDebug || autorouterPhase !== undefined,
+      autorouterPhase
     });
     await server.start();
     const timeToStart = Date.now() - startTime;
@@ -309245,7 +309313,7 @@ var registerDev = (program2) => {
   ${kleur_default.bold("➜ Auto-updating KiCad PCM Server:")} ${kleur_default.underline(kleur_default.cyan(`http://localhost:${port}/pcm/repository.json`))}
 `);
     }
-    if (options.autorouterTimeout || options.autorouterDebugDir || options.autorouterDumpSrj) {
+    if (options.autorouterTimeout || options.autorouterDebugDir || options.autorouterDumpSrj || autorouterPhase) {
       console.log(kleur_default.gray("Autorouter timeout/debug artifact flags are fully supported by `tsci build`; `tsci dev` currently logs autorouting events emitted by runframe."));
     }
   });

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

@@ -2965,6 +2965,13 @@ var parseAutorouterTimeout = (duration) => {
   }
   return timeoutMs;
 };
+var parseAutorouterPhaseName = (value) => {
+  const phaseName = value.trim();
+  if (!phaseName) {
+    throw new Error("Invalid --autorouter-phase value. The phase name must not be empty.");
+  }
+  return phaseName;
+};
 var parseAutorouterDumpSrjMode = (value) => {
   if (value === undefined || value === false)
     return;
@@ -2994,17 +3001,21 @@ class AutorouterDiagnostics {
   activePhase = null;
   completedPhaseTraces = [];
   hasWrittenPlacementSnapshot = false;
+  targetPhaseReached = false;
   summary = [];
   rootCircuit;
   constructor(options = {}) {
+    const phaseName = options.phaseName?.trim() || undefined;
     this.options = {
       ...options,
+      enabled: options.enabled || phaseName !== undefined,
+      phaseName,
       debugDir: options.debugDir ?? DEFAULT_DEBUG_DIR,
       log: options.log ?? console.log
     };
   }
   get isActive() {
-    return Boolean(this.options.enabled || this.options.timeoutMs || this.options.dumpSrj || this.options.logOnError || this.options.longRunningLogThresholdMs);
+    return Boolean(this.options.enabled || this.options.phaseName || this.options.timeoutMs || this.options.dumpSrj || this.options.logOnError || this.options.longRunningLogThresholdMs);
   }
   attachToRootCircuit(rootCircuit) {
     if (!this.isActive)
@@ -3037,10 +3048,14 @@ class AutorouterDiagnostics {
       generatedAt: new Date().toISOString(),
       phaseCount: this.summary.length,
       phases: this.summary,
-      circuitJsonElementCount: circuitJson?.length
+      circuitJsonElementCount: circuitJson?.length,
+      targetPhaseName: this.options.phaseName,
+      targetPhaseReached: this.targetPhaseReached
     });
   }
   handleStart(event) {
+    if (this.targetPhaseReached)
+      return;
     const simpleRouteJson = event.simpleRouteJson;
     const subcircuitId = event.subcircuit_id ?? event.subcircuitId ?? "unknown-subcircuit";
     const previousOrdinal = this.phaseOrdinalBySubcircuit.get(subcircuitId) ?? 0;
@@ -3053,6 +3068,9 @@ class AutorouterDiagnostics {
     this.activePhase = {
       subcircuitId,
       componentDisplayName: event.componentDisplayName ?? "subcircuit",
+      phaseName: event.phaseName,
+      phaseStageIndex: event.phaseStageIndex,
+      phaseStageCount: event.phaseStageCount,
       routingPhaseIndex,
       phaseOrdinal,
       phaseCount: event.phaseCount,
@@ -3107,6 +3125,9 @@ class AutorouterDiagnostics {
     this.summary.push({
       subcircuit_id: activePhase.subcircuitId,
       componentDisplayName: activePhase.componentDisplayName,
+      phaseName: activePhase.phaseName,
+      phaseStageIndex: activePhase.phaseStageIndex,
+      phaseStageCount: activePhase.phaseStageCount,
       routingPhaseIndex: activePhase.routingPhaseIndex,
       phaseOrdinal: activePhase.phaseOrdinal,
       phaseCount: activePhase.phaseCount,
@@ -3137,6 +3158,9 @@ class AutorouterDiagnostics {
     if (this.options.enabled) {
       this.writePngSnapshot(`phase-${activePhase.routingPhaseIndex}-routed.png`, this.getCircuitJsonWithCompletedPhaseTraces());
     }
+    if (this.isFinalTargetPhaseStage(activePhase)) {
+      this.targetPhaseReached = true;
+    }
     if (this.activePhase === activePhase) {
       this.activePhase = null;
     }
@@ -3150,6 +3174,9 @@ class AutorouterDiagnostics {
     this.summary.push({
       subcircuit_id: activePhase.subcircuitId,
       componentDisplayName: activePhase.componentDisplayName,
+      phaseName: activePhase.phaseName,
+      phaseStageIndex: activePhase.phaseStageIndex,
+      phaseStageCount: activePhase.phaseStageCount,
       routingPhaseIndex: activePhase.routingPhaseIndex,
       phaseOrdinal: activePhase.phaseOrdinal,
       phaseCount: activePhase.phaseCount,
@@ -3173,6 +3200,9 @@ class AutorouterDiagnostics {
         type: "autorouter_phase_error",
         subcircuit_id: activePhase.subcircuitId,
         routingPhaseIndex: activePhase.routingPhaseIndex,
+        phaseName: activePhase.phaseName,
+        phaseStageIndex: activePhase.phaseStageIndex,
+        phaseStageCount: activePhase.phaseStageCount,
         phaseOrdinal: activePhase.phaseOrdinal,
         phaseCount: activePhase.phaseCount,
         elapsedMs: Math.round(elapsedMs),
@@ -3182,6 +3212,9 @@ class AutorouterDiagnostics {
         error
       });
     }
+    if (this.isFinalTargetPhaseStage(activePhase)) {
+      this.targetPhaseReached = true;
+    }
     if (this.activePhase === activePhase) {
       this.activePhase = null;
     }
@@ -3199,6 +3232,9 @@ class AutorouterDiagnostics {
       subcircuit_id: activePhase.subcircuitId,
       componentDisplayName: activePhase.componentDisplayName,
       routingPhaseIndex: activePhase.routingPhaseIndex,
+      phaseName: activePhase.phaseName,
+      phaseStageIndex: activePhase.phaseStageIndex,
+      phaseStageCount: activePhase.phaseStageCount,
       phaseOrdinal: activePhase.phaseOrdinal,
       phaseCount: activePhase.phaseCount,
       elapsedMs: Math.round(elapsedMs),
@@ -3370,10 +3406,22 @@ class AutorouterDiagnostics {
     return `phase-${phaseNumber}.${suffix}`;
   }
   getPhaseLabel(activePhase) {
+    const phaseName = activePhase.phaseName ? ` "${activePhase.phaseName}"` : "";
+    const stageLabel = activePhase.phaseStageIndex !== undefined && activePhase.phaseStageCount !== undefined && activePhase.phaseStageCount > 1 ? ` stage ${activePhase.phaseStageIndex + 1}/${activePhase.phaseStageCount}` : "";
     if (activePhase.phaseCount) {
-      return `phase ${activePhase.phaseOrdinal}/${activePhase.phaseCount}`;
+      return `phase ${activePhase.phaseOrdinal}/${activePhase.phaseCount}${phaseName}${stageLabel}`;
+    }
+    return `phase ${activePhase.phaseOrdinal}${phaseName}${stageLabel}`;
+  }
+  isFinalTargetPhaseStage(activePhase) {
+    if (!this.options.phaseName)
+      return false;
+    if (activePhase.phaseName !== this.options.phaseName)
+      return false;
+    if (activePhase.phaseStageIndex === undefined || activePhase.phaseStageCount === undefined) {
+      return true;
     }
-    return `phase ${activePhase.phaseOrdinal}`;
+    return activePhase.phaseStageIndex >= activePhase.phaseStageCount - 1;
   }
   formatElapsed(elapsedMs) {
     if (elapsedMs < 1000)

package/dist/lib/index.js

@@ -65757,7 +65757,7 @@ var getNodeHandler = (winterSpec, { port, middleware = [] }) => {
   }));
 };
 // package.json
-var version = "0.1.1834";
+var version = "0.1.1835";
 var package_default = {
   name: "@tscircuit/cli",
   version,
@@ -80359,6 +80359,7 @@ var CIRCUIT_JSON_ID_PATTERN = /\b(?:source|pcb|schematic|subcircuit|cad|simulati
 var formatAutorouterDebugEvent = (event) => {
   const parts = [
     typeof event.componentDisplayName === "string" ? `component=${event.componentDisplayName}` : null,
+    typeof event.phaseName === "string" ? `autorouter_phase=${event.phaseName}` : null,
     typeof event.phase === "string" ? `phase=${event.phase}` : null,
     typeof event.solverName === "string" ? `solver=${event.solverName}` : null,
     typeof event.connectionCount === "number" ? `connections=${event.connectionCount}` : null,
@@ -80385,23 +80386,27 @@ class DevServer {
   ignoredFiles;
   kicadPcm;
   autorouterDebug;
+  autorouterPhase;
   httpServer;
   eventsWatcher;
   fsKy;
   filesystemWatcher;
   uploadedNodeModules = new Set;
+  autorouterPhaseReached = false;
   constructor({
     port,
     componentFilePath,
     projectDir,
     kicadPcm,
-    autorouterDebug
+    autorouterDebug,
+    autorouterPhase
   }) {
     this.port = port;
     this.componentFilePath = componentFilePath;
     this.projectDir = projectDir ?? path27.dirname(componentFilePath);
     this.kicadPcm = kicadPcm ?? false;
     this.autorouterDebug = autorouterDebug ?? false;
+    this.autorouterPhase = autorouterPhase?.trim() || undefined;
     const projectConfig = loadProjectConfig(this.projectDir);
     this.ignoredFiles = projectConfig?.ignoredFiles ?? [];
     this.fsKy = distribution_default.create({
@@ -80428,7 +80433,12 @@ class DevServer {
       this.eventsWatcher.on("*", (event) => {
         if (!String(event.event_type).startsWith("autorouting:"))
           return;
+        if (this.autorouterPhaseReached)
+          return;
         console.log(kleur_default.cyan(formatAutorouterDebugEvent(event)));
+        if (event.event_type === "autorouting:end" && event.phaseName === this.autorouterPhase && (event.phaseStageIndex === undefined || event.phaseStageCount === undefined || event.phaseStageIndex >= event.phaseStageCount - 1)) {
+          this.autorouterPhaseReached = true;
+        }
       });
     }
     this.filesystemWatcher = watch(this.projectDir, {
@@ -80446,6 +80456,7 @@ class DevServer {
   async handleFileUpdatedEventFromServer(ev) {
     if (ev.initiator === "filesystem_change")
       return;
+    this.autorouterPhaseReached = false;
     const { file } = await this.fsKy.get("api/files/get", {
       searchParams: { file_path: ev.file_path }
     }).json();
@@ -80474,6 +80485,7 @@ class DevServer {
       return;
     if (shouldIgnorePath(relativeFilePath, this.ignoredFiles))
       return;
+    this.autorouterPhaseReached = false;
     const filePayload = this.createFileUploadPayload(absoluteFilePath, relativeFilePath);
     console.log(kleur_default.green(`Saving: ${relativeFilePath}`));
     await this.postFileUpsert({
@@ -80507,6 +80519,7 @@ class DevServer {
     const relativeFilePath = path27.relative(this.projectDir, absoluteFilePath);
     if (shouldIgnorePath(relativeFilePath, this.ignoredFiles))
       return;
+    this.autorouterPhaseReached = false;
     if (!relativeFilePath || relativeFilePath.trim() === "") {
       debug2("Skipping delete for empty file path");
       return;

package/package.json

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