feat: HtmlControl keyboard navigation, perf fixes, image sizing, docs

HtmlControl:
- Keyboard link navigation (Tab/Shift+Tab/Enter)
- Focus-aware scrollbar (cyan when focused)
- Visual link highlight (inverted colors for focused, bright for hovered)
- Multi-line links grouped as single Tab stops via LinkId
- Focus preservation across relayout

Performance:
- Cache parsed DOM in HtmlLayoutEngine — skip re-parse on width change
- Debounce relayout during resize (150ms) — UI stays responsive

Bug fixes:
- Link highlight off-by-one (EndX now exclusive)
- TryCommitPartialImageLayout missing InvalidateLinkCache
- Image sizing respects HTML width attribute, natural size clamped

Documentation:
- Add docs/controls/HtmlControl.md
- Add docs/ALPHA_BLENDING.md (transparent windows, TransparencyBrush)
- Update CONTROLS.md and README.md with new doc links

Author: nickprotop

README.md

@@ -246,6 +246,7 @@ Full reference: [nickprotop.github.io/ConsoleEx/docfx/_site/CONTROLS.html](https
 | [Tutorials](https://nickprotop.github.io/ConsoleEx/docfx/_site/tutorials/README.html) | Three step-by-step tutorials |
 | [Controls](https://nickprotop.github.io/ConsoleEx/docfx/_site/CONTROLS.html) | All 30+ controls |
 | [Examples](https://nickprotop.github.io/ConsoleEx/docfx/_site/EXAMPLES.html) | 20+ runnable example projects |
+| [Alpha Blending](https://nickprotop.github.io/ConsoleEx/docfx/_site/ALPHA_BLENDING.html) | Transparent windows & TransparencyBrush |
 | [Compositor Effects](https://nickprotop.github.io/ConsoleEx/docfx/_site/COMPOSITOR_EFFECTS.html) | PreBufferPaint / PostBufferPaint |
 | [Video Playback](https://nickprotop.github.io/ConsoleEx/docfx/_site/VIDEO_PLAYBACK.html) | VideoControl reference |
 | [Panel System](https://nickprotop.github.io/ConsoleEx/docfx/_site/PANELS.html) | Taskbar, Start Menu, Clock |

SharpConsoleUI/Controls/HtmlControl/HtmlControl.Keyboard.cs

@@ -6,17 +6,60 @@
 // License: MIT
 // -----------------------------------------------------------------------
 
+using SharpConsoleUI.Events;
+
 namespace SharpConsoleUI.Controls
 {
 	public partial class HtmlControl
 	{
+		/// <summary>
+		/// Whether this control wants to consume Tab key events (for link navigation).
+		/// </summary>
+		public bool WantsTabKey => true;
+
 		/// <inheritdoc/>
 		public bool ProcessKey(ConsoleKeyInfo key)
 		{
 			if (!_isEnabled || !HasFocus)
 				return false;
 
-			// Don't consume modifier keys
+			// Tab / Shift+Tab — navigate between links
+			if (key.Key == ConsoleKey.Tab)
+			{
+				var links = GetAllLinks();
+				if (links.Count == 0)
+					return false;
+
+				if (key.Modifiers.HasFlag(ConsoleModifiers.Shift))
+				{
+					// Previous link (wrap to last)
+					FocusedLinkIndex = _focusedLinkIndex <= 0
+						? links.Count - 1
+						: _focusedLinkIndex - 1;
+				}
+				else
+				{
+					// Next link (wrap to first)
+					FocusedLinkIndex = _focusedLinkIndex >= links.Count - 1
+						? 0
+						: _focusedLinkIndex + 1;
+				}
+				return true;
+			}
+
+			// Enter — activate focused link
+			if (key.Key == ConsoleKey.Enter && _focusedLinkIndex >= 0)
+			{
+				var links = GetAllLinks();
+				if (_focusedLinkIndex < links.Count)
+				{
+					var focused = links[_focusedLinkIndex];
+					LinkClicked?.Invoke(this, new LinkClickedEventArgs(focused.link.Url, focused.link.Text));
+					return true;
+				}
+			}
+
+			// Don't consume other modifier keys
 			if (key.Modifiers.HasFlag(ConsoleModifiers.Alt) || key.Modifiers.HasFlag(ConsoleModifiers.Control))
 				return false;
 

SharpConsoleUI/Controls/HtmlControl/HtmlControl.Mouse.cs

@@ -141,6 +141,8 @@ public bool ProcessMouseEvent(MouseEventArgs args)
 				var link = _isNavigating ? null : FindLinkAtPosition(args, viewportHeight, contentWidth - scrollbarWidth);
 				if (link.HasValue)
 				{
+					// Sync focused link index with clicked link
+					SyncFocusedLinkFromMouse(link.Value);
 					LinkClicked?.Invoke(this, new LinkClickedEventArgs(link.Value.Url, link.Value.Text, args));
 					args.Handled = true;
 					return true;
@@ -299,6 +301,23 @@ private void HandleLinkHover(MouseEventArgs args, int viewportHeight, int render
 			return null;
 		}
 
+		/// <summary>
+		/// Syncs the focused link index with a mouse-clicked link.
+		/// </summary>
+		private void SyncFocusedLinkFromMouse((string Url, string Text, int LineIndex, int LinkIndex) clicked)
+		{
+			var links = GetAllLinks();
+			for (int i = 0; i < links.Count; i++)
+			{
+				if (links[i].lineIndex == clicked.LineIndex && links[i].linkIndex == clicked.LinkIndex)
+				{
+					_focusedLinkIndex = i;
+					Container?.Invalidate(true);
+					return;
+				}
+			}
+		}
+
 		#endregion
 	}
 }

SharpConsoleUI/Controls/HtmlControl/HtmlControl.Rendering.cs

@@ -46,10 +46,25 @@ public override LayoutSize MeasureDOM(LayoutConstraints constraints)
 			// Re-layout only if width actually changed AND we have a real width (not huge)
 			if (layoutWidth != _lastLayoutWidth && _rawHtml != null && layoutWidth < 10000)
 			{
-				lock (_contentLock)
+				// Debounce: defer relayout during rapid width changes (e.g., window resize).
+				// The cached DOM parse means re-flow is cheaper, but for large documents
+				// even the flow pass can be expensive. Schedule relayout after 150ms idle.
+				_pendingLayoutWidth = layoutWidth;
+				if (_resizeDebounceTimer == null)
 				{
-					RunLayout(layoutWidth);
+					_resizeDebounceTimer = new System.Timers.Timer(150) { AutoReset = false };
+					_resizeDebounceTimer.Elapsed += (_, _) =>
+					{
+						lock (_contentLock)
+						{
+							if (_pendingLayoutWidth > 0 && _pendingLayoutWidth != _lastLayoutWidth)
+								RunLayout(_pendingLayoutWidth);
+						}
+						Container?.Invalidate(true);
+					};
 				}
+				_resizeDebounceTimer.Stop();
+				_resizeDebounceTimer.Start();
 			}
 
 			int measuredWidth = targetWidth;
@@ -87,13 +102,8 @@ public override void PaintDOM(CharacterBuffer buffer, LayoutRect bounds, LayoutR
 			// between measure and paint on large documents (see ComputeLayoutWidth).
 			int layoutWidth = ComputeLayoutWidth(contentWidth);
 
-			if (layoutWidth != _lastLayoutWidth && _rawHtml != null)
-			{
-				lock (_contentLock)
-				{
-					RunLayout(layoutWidth);
-				}
-			}
+			// Note: relayout on width change is handled by MeasureDOM with debouncing.
+			// PaintDOM renders from the current (possibly stale) layout snapshot.
 
 			int contentAreaX = bounds.X + Margin.Left;
 			int contentAreaY = bounds.Y + Margin.Top;
@@ -171,15 +181,21 @@ public override void PaintDOM(CharacterBuffer buffer, LayoutRect bounds, LayoutR
 					}
 
 					buffer.WriteCellsClipped(screenX, screenY, line.Cells, tightClip);
+
+					// Highlight links on this line (focused and hovered)
+					if (line.Links != null)
+					{
+						HighlightLinksOnLine(buffer, i, ref line, screenX, screenY, tightClip);
+					}
 				}
 			}
 
 			// Draw scrollbar
 			if (needsScrollbar)
 			{
 				int scrollbarX = contentAreaX + contentWidth - 1;
-				var thumbColor = Color.Grey;
-				var trackColor = Color.Grey23;
+				var thumbColor = HasFocus ? Color.Cyan1 : Color.Grey;
+				var trackColor = HasFocus ? Color.Grey : Color.Grey23;
 
 				ScrollbarHelper.DrawVerticalScrollbar(
 					buffer, scrollbarX, contentAreaY, viewportHeight,
@@ -265,5 +281,48 @@ private void DrawLoadingOverlay(CharacterBuffer buffer, int areaX, int areaY, in
 				}
 			}
 		}
+		/// <summary>
+		/// Highlights focused and hovered links on a rendered line by overriding cell colors.
+		/// </summary>
+		private void HighlightLinksOnLine(CharacterBuffer buffer, int lineIndex, ref LayoutLine line,
+			int screenX, int screenY, LayoutRect clipRect)
+		{
+			int focusedLinkId = GetFocusedLinkId();
+
+			for (int j = 0; j < line.Links!.Length; j++)
+			{
+				ref var link = ref line.Links[j];
+
+				// Check if this segment belongs to the focused link (by LinkId — covers all segments)
+				bool isFocused = focusedLinkId >= 0 && link.LinkId == focusedLinkId;
+				bool isHovered = lineIndex == _hoveredLinkLineIndex && j == _hoveredLinkIndex;
+
+				if (!isFocused && !isHovered) continue;
+
+				// Apply highlight colors
+				for (int x = link.StartX; x < link.EndX; x++)
+				{
+					int cellX = screenX + x;
+					if (cellX < clipRect.X || cellX >= clipRect.Right) continue;
+					if (screenY < clipRect.Y || screenY >= clipRect.Bottom) continue;
+
+					var cell = buffer.GetCell(cellX, screenY);
+					if (isFocused)
+					{
+						// Focused link: inverted colors for clear visibility
+						buffer.SetCellColors(cellX, screenY, cell.Background, cell.Foreground);
+					}
+					else if (isHovered)
+					{
+						// Hovered link: subtle underline-like highlight (brighter foreground)
+						var brightFg = new Color(
+							(byte)Math.Min(255, cell.Foreground.R + 60),
+							(byte)Math.Min(255, cell.Foreground.G + 60),
+							(byte)Math.Min(255, cell.Foreground.B + 60));
+						buffer.SetCellColors(cellX, screenY, brightFg, cell.Background);
+					}
+				}
+			}
+		}
 	}
 }