fix(cursor): stop redundant cursor escape re-emission (calm blink); add CursorBlink option and opt-in software cursor

- CursorStateService caches last-applied (visible,position,shape) and emits only on change,
  with InvalidatePhysicalCursor() after each rendered frame — fixes the too-fast blink caused
  by re-emitting CUP/DECTCEM/DECSCUSR every main-loop iteration (terminals reset blink on move)
- NetConsoleDriverOptions.CursorBlink (Steady/Blinking/TerminalDefault, default Blinking) via
  DECSCUSR shape x blink codes
- Opt-in NetConsoleDriverOptions.UseSoftwareCursor: CursorBlinkClock-driven inverse-video caret
  overlay at the logical cursor position, blinking at CursorBlinkRate, with render keep-alive

Closes #37

Author: Nikolaos Protopapas

SharpConsoleUI.Tests/Core/CursorBlinkClockTests.cs

@@ -0,0 +1,36 @@
+using SharpConsoleUI.Core;
+using Xunit;
+
+namespace SharpConsoleUI.Tests.Core;
+
+public class CursorBlinkClockTests
+{
+	[Fact]
+	public void StartsOn_TogglesAfterFullRate_ResetReturnsOn()
+	{
+		var clock = new CursorBlinkClock();
+		Assert.True(clock.IsOn(rateMs: 500));     // solid initially
+
+		clock.Advance(300);
+		Assert.True(clock.IsOn(500));             // still within first on-phase
+
+		clock.Advance(300);                        // total 600 > 500 -> off phase
+		Assert.False(clock.IsOn(500));
+
+		clock.Advance(500);                        // into next on-phase (total 1100 -> cycle 2)
+		Assert.True(clock.IsOn(500));
+
+		clock.Advance(400);                        // total 1500 -> cycle 3 -> off
+		Assert.False(clock.IsOn(500));
+		clock.Reset();
+		Assert.True(clock.IsOn(500));             // reset forces solid on
+	}
+
+	[Fact]
+	public void NonPositiveRate_AlwaysOn()
+	{
+		var clock = new CursorBlinkClock();
+		clock.Advance(99999);
+		Assert.True(clock.IsOn(0));
+	}
+}

SharpConsoleUI.Tests/Core/CursorStateServiceChangeDetectionTests.cs

@@ -0,0 +1,52 @@
+using System.Drawing;
+using SharpConsoleUI;
+using SharpConsoleUI.Core;
+using SharpConsoleUI.Drivers;
+using Xunit;
+
+namespace SharpConsoleUI.Tests.Core;
+
+public class CursorStateServiceChangeDetectionTests
+{
+	private static (CursorStateService svc, HeadlessConsoleDriver drv, Window win) Make()
+	{
+		var driver = new HeadlessConsoleDriver(80, 25);
+		var system = new ConsoleWindowSystem(driver);
+		var win = new Window(system);
+		var svc = new CursorStateService(driver);
+		return (svc, driver, win);
+	}
+
+	[Fact]
+	public void ApplyCursor_DoesNotReemit_WhenStateUnchanged()
+	{
+		var (svc, drv, win) = Make();
+		svc.UpdateFromWindowSystem(win, new Point(2, 3), new Point(2, 3), null, CursorShape.Block);
+		for (int i = 0; i < 5; i++) svc.ApplyCursorToConsole(80, 25);
+		Assert.Equal(1, drv.SetCursorPositionCallCount);
+		Assert.Equal(1, drv.SetCursorVisibleCallCount);
+	}
+
+	[Fact]
+	public void ApplyCursor_Reemits_AfterPhysicalCursorInvalidated()
+	{
+		var (svc, drv, win) = Make();
+		svc.UpdateFromWindowSystem(win, new Point(2, 3), new Point(2, 3), null, CursorShape.Block);
+		svc.ApplyCursorToConsole(80, 25);
+		Assert.Equal(1, drv.SetCursorPositionCallCount);
+		svc.InvalidatePhysicalCursor();
+		svc.ApplyCursorToConsole(80, 25);
+		Assert.Equal(2, drv.SetCursorPositionCallCount);
+	}
+
+	[Fact]
+	public void ApplyCursor_Reemits_WhenPositionChanges()
+	{
+		var (svc, drv, win) = Make();
+		svc.UpdateFromWindowSystem(win, new Point(2, 3), new Point(2, 3), null, CursorShape.Block);
+		svc.ApplyCursorToConsole(80, 25);
+		svc.UpdateFromWindowSystem(win, new Point(5, 3), new Point(5, 3), null, CursorShape.Block);
+		svc.ApplyCursorToConsole(80, 25);
+		Assert.Equal(2, drv.SetCursorPositionCallCount);
+	}
+}

SharpConsoleUI.Tests/Drivers/DecscusrCodeTests.cs

@@ -0,0 +1,21 @@
+using SharpConsoleUI.Core;
+using SharpConsoleUI.Drivers;
+using Xunit;
+
+namespace SharpConsoleUI.Tests.Drivers;
+
+public class DecscusrCodeTests
+{
+	[Theory]
+	[InlineData(CursorShape.Block,       CursorBlink.Blinking, 1)]
+	[InlineData(CursorShape.Block,       CursorBlink.Steady,   2)]
+	[InlineData(CursorShape.Underline,   CursorBlink.Blinking, 3)]
+	[InlineData(CursorShape.Underline,   CursorBlink.Steady,   4)]
+	[InlineData(CursorShape.VerticalBar, CursorBlink.Blinking, 5)]
+	[InlineData(CursorShape.VerticalBar, CursorBlink.Steady,   6)]
+	[InlineData(CursorShape.Block,       CursorBlink.TerminalDefault, 0)]
+	public void DecscusrCode_MapsShapeAndBlink(CursorShape shape, CursorBlink blink, int expected)
+	{
+		Assert.Equal(expected, NetConsoleDriver.DecscusrCode(shape, blink));
+	}
+}

SharpConsoleUI.Tests/Drivers/TryGetCellTests.cs

@@ -0,0 +1,22 @@
+using System.Drawing;
+using SharpConsoleUI.Drivers;
+using Xunit;
+
+namespace SharpConsoleUI.Tests.Drivers;
+
+public class TryGetCellTests
+{
+	[Fact]
+	public void TryGetCell_ReturnsWrittenCell()
+	{
+		var buffer = new ConsoleBuffer(10, 3);
+		buffer.SetNarrowCell(4, 1, 'Z', Color.White, Color.Black);
+
+		Assert.True(buffer.TryGetCell(4, 1, out var ch, out var fg, out var bg));
+		Assert.Equal('Z', ch);
+		Assert.Equal(Color.White, fg);
+		Assert.Equal(Color.Black, bg);
+
+		Assert.False(buffer.TryGetCell(-1, 0, out _, out _, out _));
+	}
+}

SharpConsoleUI/ConsoleWindowSystem.cs

@@ -56,6 +56,13 @@ public class ConsoleWindowSystem
 		// Managed thread id of the main-loop (UI) thread; set at Run() start. -1 until then.
 		private int _uiThreadId = -1;
 
+		// Software cursor: opt-in caret drawn by the app (blinking) with hardware cursor hidden.
+		// Resolved once at startup from the driver's options.
+		private bool _useSoftwareCursor;
+		private int _cursorBlinkRateMs = 500;
+		private readonly Core.CursorBlinkClock _blinkClock = new();
+		private System.Drawing.Point _lastSoftwareCursorPos = new(-1, -1);
+
 		// Signal to wake the main loop when input or UI actions arrive
 		private readonly ManualResetEventSlim _wakeSignal = new(false);
 
@@ -407,6 +414,14 @@ public ConsoleWindowSystem(IConsoleDriver driver, ITheme theme, PluginConfigurat
 
 			// Initialize panels from config or legacy StatusBarOptions
 			_panelStateService.InitializePanels(_options);
+
+			// Resolve software-cursor settings once from the driver's options (if it exposes them).
+			// Headless/other drivers leave the defaults (false / 500ms).
+			if (_consoleDriver is Drivers.NetConsoleDriver netDriver)
+			{
+				_useSoftwareCursor = netDriver.Options.UseSoftwareCursor;
+				_cursorBlinkRateMs = netDriver.Options.CursorBlinkRate;
+			}
 		}
 
 		#endregion
@@ -460,6 +475,10 @@ public IConsoleDriver ConsoleDriver
 		/// </summary>
 		internal CursorStateService CursorStateService => _cursorStateService;
 
+		/// <summary>True when a software caret should currently be drawn.</summary>
+		internal bool SoftwareCursorOn =>
+			_useSoftwareCursor && _cursorStateService.CurrentState.IsVisible && _blinkClock.IsOn(_cursorBlinkRateMs);
+
 		/// <summary>
 		/// Gets the window state service for managing window lifecycle and state.
 		/// </summary>
@@ -920,6 +939,8 @@ public int Run()
 					var now = DateTime.UtcNow;
 					var elapsed = (now - _lastRenderTime).TotalMilliseconds;
 
+					if (_useSoftwareCursor) _blinkClock.Advance(elapsed);
+
 					// Track performance metrics on EVERY iteration (independent of rendering)
 					bool metricsNeedUpdate = false;
 					if (Performance.IsPerformanceMetricsEnabled)
@@ -943,7 +964,8 @@ public int Run()
 					}
 
 					// Frame pacing: render if windows are dirty OR metrics need update OR desktop needs render OR animations active
-					bool shouldRender = AnyWindowDirty() || metricsNeedUpdate || Render.DesktopNeedsRender || Animations.HasActiveAnimations || Parsing.MarkupSpinnerClock.ShouldKeepRendering(Animations.IsEnabled) || Render.IsStatusBarDirty() || _desktopPortalService.AnyPortalDirty();
+					bool shouldRender = AnyWindowDirty() || metricsNeedUpdate || Render.DesktopNeedsRender || Animations.HasActiveAnimations || Parsing.MarkupSpinnerClock.ShouldKeepRendering(Animations.IsEnabled) || Render.IsStatusBarDirty() || _desktopPortalService.AnyPortalDirty()
+						|| (_useSoftwareCursor && _cursorStateService.CurrentState.IsVisible);
 
 					// Calculate recommended sleep duration once (used in both branches)
 					var recommendedSleep = _inputStateService.GetRecommendedSleepDuration(
@@ -986,6 +1008,9 @@ public int Run()
 					UpdateCursor();
 					if (_uiActionsPending && _idleTime > Configuration.SystemDefaults.MinSleepDurationMs)
 						_idleTime = Configuration.SystemDefaults.MinSleepDurationMs;
+					// Keep the loop ticking fast enough for smooth caret blinking.
+					if (_useSoftwareCursor && _cursorStateService.CurrentState.IsVisible)
+						_idleTime = Math.Min(_idleTime, _cursorBlinkRateMs);
 					_currentPhase = Core.MainLoopPhase.Idle;
 					try
 					{
@@ -1335,6 +1360,18 @@ private void UpdateCursor()
 				_cursorStateService.HideCursor();
 			}
 
+			// Software cursor: reset the blink clock whenever the caret moves so the new
+			// position starts in the "on" phase. CurrentState holds the real (visible) caret.
+			if (_useSoftwareCursor)
+			{
+				var caretPos = _cursorStateService.CurrentState.AbsolutePosition;
+				if (caretPos != _lastSoftwareCursorPos)
+				{
+					_blinkClock.Reset();
+					_lastSoftwareCursorPos = caretPos;
+				}
+			}
+
 			// Apply cursor state to the actual console
 			// CRITICAL: Protect Console I/O with lock to prevent concurrent writes
 			// from corrupting ANSI sequences during InputLoop's mouse parsing
@@ -1343,6 +1380,15 @@ private void UpdateCursor()
 				_cursorStateService.ApplyCursorToConsole(
 					_consoleDriver.ScreenSize.Width,
 					_consoleDriver.ScreenSize.Height);
+
+				// Software cursor: keep CurrentState as the real (visible) caret for the overlay,
+				// but force the HARDWARE cursor hidden so only the app-drawn caret is seen.
+				// Only emit when the caret is logically visible (avoids churn; the overlay
+				// redraws every frame while focused — see the keep-alive in the main loop).
+				if (_useSoftwareCursor && _cursorStateService.CurrentState.IsVisible)
+				{
+					_consoleDriver.SetCursorVisible(false);
+				}
 			}
 		}
 

SharpConsoleUI/Core/CursorBlinkClock.cs

@@ -0,0 +1,37 @@
+// -----------------------------------------------------------------------
+// ConsoleEx - A simple console window system for .NET Core
+//
+// Author: Nikolaos Protopapas
+// Email: nikolaos.protopapas@gmail.com
+// License: MIT
+// -----------------------------------------------------------------------
+
+namespace SharpConsoleUI.Core
+{
+	/// <summary>
+	/// Rate-driven on/off state for the opt-in software cursor. The loop feeds elapsed time via
+	/// Advance(); IsOn(rate) returns whether the caret should currently be drawn. Reset() forces a
+	/// solid "on" phase (called when the caret moves, so it is solid right after typing).
+	/// </summary>
+	public sealed class CursorBlinkClock
+	{
+		private double _accumulatedMs;
+
+		/// <summary>Advances the clock by the elapsed milliseconds of a loop iteration.</summary>
+		public void Advance(double elapsedMs)
+		{
+			if (elapsedMs > 0) _accumulatedMs += elapsedMs;
+		}
+
+		/// <summary>Forces a fresh solid-on phase.</summary>
+		public void Reset() => _accumulatedMs = 0;
+
+		/// <summary>True when the caret should be drawn for the given blink rate (ms per half-cycle).</summary>
+		public bool IsOn(int rateMs)
+		{
+			if (rateMs <= 0) return true;
+			long cycle = (long)(_accumulatedMs / rateMs);
+			return (cycle % 2) == 0;
+		}
+	}
+}

SharpConsoleUI/Core/CursorState.cs

@@ -39,6 +39,20 @@ public enum CursorShape
 		Hidden
 	}
 
+	/// <summary>
+	/// Controls hardware-cursor blinking via DECSCUSR. The terminal owns the blink rate;
+	/// only blinking-vs-steady (and the terminal default) can be selected.
+	/// </summary>
+	public enum CursorBlink
+	{
+		/// <summary>Non-blinking cursor (DECSCUSR even codes).</summary>
+		Steady,
+		/// <summary>Blinking at the terminal's native rate (DECSCUSR odd codes).</summary>
+		Blinking,
+		/// <summary>Terminal default (DECSCUSR 0).</summary>
+		TerminalDefault
+	}
+
 	/// <summary>
 	/// Immutable record representing the current state of the cursor.
 	/// Provides a single source of truth for cursor visibility, position, and ownership.

SharpConsoleUI/Core/CursorStateService.cs

@@ -26,6 +26,16 @@ public class CursorStateService : IDisposable
 		private const int MaxHistorySize = 100;
 		private bool _isDisposed;
 
+		private readonly record struct AppliedCursor(bool Visible, System.Drawing.Point Position, CursorShape Shape);
+		private AppliedCursor? _lastApplied;
+		private bool _physicalCursorDirty = true;
+
+		/// <summary>
+		/// Marks the physical terminal cursor as moved (e.g. after a frame render writes cells),
+		/// forcing the next ApplyCursorToConsole to reposition it.
+		/// </summary>
+		public void InvalidatePhysicalCursor() => _physicalCursorDirty = true;
+
 		/// <summary>
 		/// Initializes a new instance of the <see cref="CursorStateService"/> class.
 		/// </summary>
@@ -235,27 +245,36 @@ public bool ApplyCursorToConsole(int screenWidth, int screenHeight)
 		{
 			var state = CurrentState;
 
-			if (!state.IsVisible || state.Shape == CursorShape.Hidden)
-			{
-				_driver.SetCursorVisible(false);
+			bool inBounds =
+				state.AbsolutePosition.X >= 0 && state.AbsolutePosition.X < screenWidth &&
+				state.AbsolutePosition.Y >= 0 && state.AbsolutePosition.Y < screenHeight;
+			bool visible = state.IsVisible && state.Shape != CursorShape.Hidden && inBounds;
+			var target = new AppliedCursor(visible, state.AbsolutePosition, state.Shape);
+
+			if (!_physicalCursorDirty && _lastApplied.HasValue && _lastApplied.Value == target)
 				return true;
-			}
 
-			var pos = state.AbsolutePosition;
+			bool emitAll = _physicalCursorDirty || !_lastApplied.HasValue;
+			var last = _lastApplied;
 
-			// Bounds check
-			if (pos.X < 0 || pos.X >= screenWidth || pos.Y < 0 || pos.Y >= screenHeight)
+			if (!visible)
 			{
-				_driver.SetCursorVisible(false);
-				return false;
+				if (emitAll || last!.Value.Visible)
+					_driver.SetCursorVisible(false);
+			}
+			else
+			{
+				if (emitAll || last!.Value.Shape != target.Shape)
+					_driver.SetCursorShape(target.Shape);
+				if (emitAll || last!.Value.Position != target.Position)
+					_driver.SetCursorPosition(target.Position.X, target.Position.Y);
+				if (emitAll || !last!.Value.Visible)
+					_driver.SetCursorVisible(true);
 			}
 
-			// Apply cursor shape, position, and make visible
-			_driver.SetCursorShape(state.Shape);
-			_driver.SetCursorPosition(pos.X, pos.Y);
-			_driver.SetCursorVisible(true);
-
-			return true;
+			_lastApplied = target;
+			_physicalCursorDirty = false;
+			return target.Visible;
 		}
 
 		/// <inheritdoc/>