Implement production-ready breakpoint system with PDB sequence point mapping, dynamic breakpoints, and UI feedback (#91)

Author: Copilot

.github/agents/basicAgent.agent.md

@@ -12,7 +12,7 @@ description: Used for general purpose NodeDev development
 
 1) You must always read the documentation files when they are related to your current task. They are described in the "Documentation" section of this document.
 2) You must always run the tests and make sure they are passing before you consider your job as completed, no matter how long you have been at the task or any following instruction to make it short or end the task early.
-3) Disabling, removing, skipping, deleting, bypassing or converting to warnings ANY tests IS NOT ALLOWED and is not considered the right way of fixing a problematic test. The test must be functional and actually testing what it is intended to test.
+3) **CRITICAL: Disabling, removing, skipping, deleting, bypassing or converting to warnings ANY tests IS NOT ALLOWED and is not considered the right way of fixing a problematic test. The test must be functional and actually testing what it is intended to test. DO NOT REMOVE TESTS UNLESS EXPLICITLY INSTRUCTED TO DO SO BY THE USER.**
 4) Document newly added content or concepts in this `.github/agents/basicAgent.agent.md` file or any related documentation file.
 5) When the user corrects major mistakes done during your development, document them in this file to ensure it is never done again.
 6) You must always install playwright BEFORE trying to run the tests. build the projects and install playwright. If you struggle (take multiple iterations to do it), document the steps you took in this file to make it easier next time.
@@ -192,11 +192,41 @@ The debugging infrastructure is located in `src/NodeDev.Core/Debugger/` and prov
 - **DebugSessionEngine**: Main debugging engine with process launch, attach, and callback handling
 - **ManagedDebuggerCallbacks**: Implementation of ICorDebugManagedCallback interfaces via ClrDebug
 - **DebugEngineException**: Custom exception type for debugging errors
+- **NodeBreakpointInfo**: Maps nodes to their generated source code locations for breakpoint resolution
+- **BreakpointMappingInfo**: Collection of all breakpoint information for a compiled project
 
 **Dependencies:**
 - `ClrDebug` (v0.3.4): C# wrappers for the unmanaged ICorDebug API
 - `Microsoft.Diagnostics.DbgShim` (v9.0.652701): Native dbgshim library for all platforms
 
+### Breakpoint System
+NodeDev supports setting breakpoints on nodes during debugging. The system tracks node-to-source-line mappings during compilation:
+
+**Infrastructure:**
+1. **Node Marking**: Nodes are marked with `BreakpointDecoration` (only non-inlinable nodes support breakpoints)
+2. **Line Tracking**: `RoslynGraphBuilder.BuildStatementsWithBreakpointTracking()` tracks which source line each node generates
+3. **Compilation**: `RoslynNodeClassCompiler` collects all breakpoint mappings into `BreakpointMappingInfo`
+4. **Storage**: Project stores breakpoint mappings after build for use during debugging
+5. **Debug Engine**: `DebugSessionEngine` receives breakpoint mappings and attempts to set breakpoints after modules load
+
+**Implementation:**
+- ✅ Node breakpoint marking and persistence
+- ✅ #line directives with virtual line numbers for stable mapping
+- ✅ PDB sequence point reading for accurate IL offset resolution
+- ✅ Breakpoint mapping storage in compilation results
+- ✅ Debug engine infrastructure for breakpoint management
+- ✅ Actual ICorDebug breakpoint setting with `ICorDebugFunction.CreateBreakpoint()`
+- ✅ Execution pauses at breakpoints and resumes with Continue()
+
+**How It Works:**
+1. UI allows toggling breakpoints on nodes (F9 or toolbar button)
+2. Breakpoints persist across save/load
+3. Compilation adds #line directives with virtual line numbers (10000, 11000, 12000...)
+4. PDB sequence points are read to map virtual lines to exact IL offsets
+5. Debug engine creates actual ICorDebug breakpoints at precise locations
+6. Execution pauses when breakpoints are hit
+7. User can resume with Continue()
+
 ### ScriptRunner
 NodeDev includes a separate console application called **ScriptRunner** that serves as the target process for debugging. This architecture supports "Hard Debugging" via the ICorDebug API.
 

src/NodeDev.Blazor/Components/GraphCanvas.razor.cs

@@ -539,7 +539,19 @@ private void Diagram_KeyDown(global::Blazor.Diagrams.Core.Events.KeyboardEventAr
 			var node = Diagram.Nodes.Where(x => x.Selected).OfType<GraphNodeModel>().FirstOrDefault();
 			if (node != null && !node.Node.CanBeInlined)
 			{
-				node.Node.ToggleBreakpoint();
+				// If debugging, use Project API to dynamically set/remove breakpoint
+				if (Graph.Project.IsHardDebugging)
+				{
+					if (node.Node.HasBreakpoint)
+						Graph.Project.RemoveBreakpointForNode(node.Node.Id);
+					else
+						Graph.Project.SetBreakpointForNode(node.Node.Id);
+				}
+				else
+				{
+					// Not debugging - just toggle decoration
+					node.Node.ToggleBreakpoint();
+				}
 				node.Refresh();
 			}
 		}
@@ -584,7 +596,19 @@ public void ToggleBreakpointOnSelectedNode()
 		var node = Diagram.Nodes.Where(x => x.Selected).OfType<GraphNodeModel>().FirstOrDefault();
 		if (node != null && !node.Node.CanBeInlined)
 		{
-			node.Node.ToggleBreakpoint();
+			// If debugging, use Project API to dynamically set/remove breakpoint
+			if (Graph.Project.IsHardDebugging)
+			{
+				if (node.Node.HasBreakpoint)
+					Graph.Project.RemoveBreakpointForNode(node.Node.Id);
+				else
+					Graph.Project.SetBreakpointForNode(node.Node.Id);
+			}
+			else
+			{
+				// Not debugging - just toggle decoration
+				node.Node.ToggleBreakpoint();
+			}
 			node.Refresh();
 		}
 	}

src/NodeDev.Blazor/Components/ProjectToolbar.razor

@@ -18,8 +18,17 @@
 {
     <MudIconButton Icon="@Icons.Material.Filled.Stop" Class="ml-3" OnClick="StopDebugging" data-test-id="stop-debug" Title="Stop Debugging" Color="Color.Error" />
     <MudIconButton Icon="@Icons.Material.Filled.Pause" Class="ml-3" OnClick="PauseDebugging" data-test-id="pause-debug" Title="Pause" Disabled="true" />
-    <MudIconButton Icon="@Icons.Material.Filled.PlayArrow" Class="ml-3" OnClick="ResumeDebugging" data-test-id="resume-debug" Title="Resume" Disabled="true" />
-    <MudText Color="Color.Warning" Class="ml-2 align-self-center" data-test-id="debug-status-text" Typo="Typo.body2">Debugging (PID: @Project.DebuggedProcessId)</MudText>
+    <MudIconButton Icon="@Icons.Material.Filled.PlayArrow" Class="ml-3" OnClick="ResumeDebugging" data-test-id="resume-debug" Title="Continue" Disabled="@(!Project.IsPausedAtBreakpoint)" Color="@(Project.IsPausedAtBreakpoint ? Color.Success : Color.Default)" />
+    @if (Project.IsPausedAtBreakpoint && Project.CurrentBreakpoint != null)
+    {
+        <MudText Color="Color.Error" Class="ml-2 align-self-center" data-test-id="breakpoint-status-text" Typo="Typo.body2">
+            ⏸ PAUSED at breakpoint: @Project.CurrentBreakpoint.NodeName
+        </MudText>
+    }
+    else
+    {
+        <MudText Color="Color.Warning" Class="ml-2 align-self-center" data-test-id="debug-status-text" Typo="Typo.body2">Debugging (PID: @Project.DebuggedProcessId)</MudText>
+    }
 }
 else
 {
@@ -45,9 +54,10 @@ else
 
     private Project Project => ProjectService.Project;
 
-	private DialogOptions DialogOptions => new DialogOptions { MaxWidth = MaxWidth.Medium, FullWidth = true };
+    private DialogOptions DialogOptions => new DialogOptions { MaxWidth = MaxWidth.Medium, FullWidth = true };
 
     private IDisposable? HardDebugStateSubscription;
+    private IDisposable? CurrentBreakpointSubscription;
 
     protected override void OnInitialized()
     {
@@ -58,11 +68,19 @@ else
         {
             InvokeAsync(StateHasChanged);
         });
+        
+        // Subscribe to current breakpoint changes to refresh UI
+        CurrentBreakpointSubscription = Project.CurrentBreakpointChanged.Subscribe(breakpoint =>
+        {
+            Console.WriteLine($"[ProjectToolbar] CurrentBreakpoint changed: {(breakpoint != null ? $"{breakpoint.NodeName}" : "null")}");
+            InvokeAsync(StateHasChanged);
+        });
     }
 
     public void Dispose()
     {
         HardDebugStateSubscription?.Dispose();
+        CurrentBreakpointSubscription?.Dispose();
     }
 
     private Task Open()
@@ -156,8 +174,19 @@ else
 
     public void ResumeDebugging()
     {
-        // Placeholder for future implementation
-        Snackbar.Add("Resume functionality coming soon", Severity.Info);
+        try
+        {
+            Project.ContinueExecution();
+            Snackbar.Add("Execution resumed", Severity.Success);
+        }
+        catch (InvalidOperationException ex)
+        {
+            Snackbar.Add($"Cannot resume: {ex.Message}", Severity.Error);
+        }
+        catch (Exception ex)
+        {
+            Snackbar.Add($"Failed to resume: {ex.Message}", Severity.Error);
+        }
     }
 
     public void Build()

src/NodeDev.Core/Class/RoslynNodeClassCompiler.cs

@@ -4,6 +4,7 @@
 using Microsoft.CodeAnalysis.Emit;
 using Microsoft.CodeAnalysis.Text;
 using NodeDev.Core.CodeGeneration;
+using NodeDev.Core.Debugger;
 using System.Reflection;
 using System.Text;
 using SF = Microsoft.CodeAnalysis.CSharp.SyntaxFactory;
@@ -17,6 +18,7 @@ public class RoslynNodeClassCompiler
 {
 	private readonly Project _project;
 	private readonly BuildOptions _options;
+	private readonly List<NodeBreakpointInfo> _allBreakpoints = new();
 
 	public RoslynNodeClassCompiler(Project project, BuildOptions options)
 	{
@@ -29,6 +31,9 @@ public RoslynNodeClassCompiler(Project project, BuildOptions options)
 	/// </summary>
 	public CompilationResult Compile()
 	{
+		// Clear breakpoints from previous compilation
+		_allBreakpoints.Clear();
+		
 		// Generate the compilation unit (full source code)
 		var compilationUnit = GenerateCompilationUnit();
 
@@ -100,7 +105,14 @@ public CompilationResult Compile()
 
 		var assembly = Assembly.Load(peStream.ToArray(), pdbStream.ToArray());
 
-		return new CompilationResult(assembly, sourceText, peStream.ToArray(), pdbStream.ToArray());
+		// Create breakpoint mapping info
+		var breakpointMappingInfo = new BreakpointMappingInfo
+		{
+			Breakpoints = _allBreakpoints,
+			SourceFilePath = syntaxTree.FilePath
+		};
+
+		return new CompilationResult(assembly, sourceText, peStream.ToArray(), pdbStream.ToArray(), breakpointMappingInfo);
 	}
 
 	/// <summary>
@@ -196,7 +208,12 @@ private PropertyDeclarationSyntax GenerateProperty(NodeClassProperty property)
 	private MethodDeclarationSyntax GenerateMethod(NodeClassMethod method)
 	{
 		var builder = new RoslynGraphBuilder(method.Graph, _options.BuildExpressionOptions.RaiseNodeExecutedEvents);
-		return builder.BuildMethod();
+		var methodSyntax = builder.BuildMethod();
+		
+		// Collect breakpoint mappings from the builder's context
+		_allBreakpoints.AddRange(builder.GetBreakpointMappings());
+		
+		return methodSyntax;
 	}
 
 	/// <summary>
@@ -229,7 +246,7 @@ private List<MetadataReference> GetMetadataReferences()
 	/// <summary>
 	/// Result of a Roslyn compilation
 	/// </summary>
-	public record CompilationResult(Assembly Assembly, string SourceCode, byte[] PEBytes, byte[] PDBBytes);
+	public record CompilationResult(Assembly Assembly, string SourceCode, byte[] PEBytes, byte[] PDBBytes, BreakpointMappingInfo BreakpointMappings);
 
 	/// <summary>
 	/// Exception thrown when compilation fails

src/NodeDev.Core/CodeGeneration/GenerationContext.cs

@@ -1,6 +1,8 @@
 using Microsoft.CodeAnalysis.CSharp;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
 using NodeDev.Core.Connections;
+using NodeDev.Core.Debugger;
+using NodeDev.Core.Nodes;
 
 namespace NodeDev.Core.CodeGeneration;
 
@@ -25,6 +27,12 @@ public GenerationContext(bool isDebug)
 	/// </summary>
 	public bool IsDebug { get; }
 
+	/// <summary>
+	/// Collection of nodes with breakpoints and their line number mappings.
+	/// This is populated during code generation to track where breakpoints should be set.
+	/// </summary>
+	public List<NodeBreakpointInfo> BreakpointMappings { get; } = new();
+
 	/// <summary>
 	/// Gets the variable name for a connection, or null if not yet registered
 	/// </summary>