Add dismiss-on-outside-click for portals and fix right-click cursor in MultilineEdit

Portal system: add opt-in DismissOnOutsideClick property to IHasPortalBounds
and PortalContentBase. Portals with this enabled are automatically dismissed
on outside click and window deactivation, with a DismissRequested event for
cleanup. Defaults to false so existing portals are unaffected.

MultilineEdit: move cursor to click position before firing MouseRightClick,
matching standard editor behavior.

Author: nickprotop

SharpConsoleUI/Controls/MultilineEdit/MultilineEditControl.Mouse.cs

@@ -200,9 +200,16 @@ public bool ProcessMouseEvent(MouseEventArgs args)
 					return true;
 			}
 
-			// Handle right-click
+			// Handle right-click: move cursor to click position first, then fire event
 			if (args.HasFlag(MouseFlags.Button3Clicked))
 			{
+				if (_hasFocus)
+				{
+					PositionCursorFromMouseCore(args.Position.X, args.Position.Y);
+					ClearSelection();
+					EnsureCursorVisible();
+					Container?.Invalidate(true);
+				}
 				MouseRightClick?.Invoke(this, args);
 				return true;
 			}

SharpConsoleUI/Controls/PortalContentBase.cs

@@ -35,6 +35,20 @@ public abstract class PortalContentBase : IWindowControl, IDOMPaintable, IMouseA
 		/// </summary>
 		public abstract Rectangle GetPortalBounds();
 
+		/// <inheritdoc/>
+		public bool DismissOnOutsideClick { get; set; }
+
+		/// <summary>
+		/// Raised when the portal is about to be dismissed due to an outside click.
+		/// Consumers can use this to perform cleanup before the portal is removed.
+		/// </summary>
+		public event EventHandler? DismissRequested;
+
+		/// <summary>
+		/// Raises the <see cref="DismissRequested"/> event.
+		/// </summary>
+		internal void RaiseDismissRequested() => DismissRequested?.Invoke(this, EventArgs.Empty);
+
 		#endregion
 
 		#region IMouseAwareControl Implementation

SharpConsoleUI/Layout/IHasPortalBounds.cs

@@ -14,5 +14,10 @@ public interface IHasPortalBounds
 		/// where this portal overlay should be rendered.
 		/// </summary>
 		Rectangle GetPortalBounds();
+
+		/// <summary>
+		/// When true, the portal is automatically dismissed when the user clicks outside its bounds.
+		/// </summary>
+		bool DismissOnOutsideClick => false;
 	}
 }

SharpConsoleUI/Window.cs

@@ -2053,6 +2053,38 @@ public void RemovePortal(IWindowControl ownerControl, LayoutNode portalNode)
 			Invalidate(false);
 		}
 
+		/// <summary>
+		/// Dismisses all portals that have DismissOnOutsideClick enabled.
+		/// Called on window deactivation and can be called programmatically.
+		/// </summary>
+		internal void DismissAutoClosePortals()
+		{
+			var root = RootLayoutNode;
+			if (root == null) return;
+
+			var toDismiss = new List<LayoutNode>();
+
+			root.Visit(node =>
+			{
+				foreach (var portal in node.PortalChildren)
+				{
+					if (portal.Control is Layout.IHasPortalBounds hasPortalBounds
+						&& hasPortalBounds.DismissOnOutsideClick)
+					{
+						toDismiss.Add(portal);
+					}
+				}
+			});
+
+			foreach (var portal in toDismiss)
+			{
+				if (portal.Control is Controls.PortalContentBase portalContent)
+					portalContent.RaiseDismissRequested();
+				if (portal.Control != null)
+					RemovePortal(portal.Control, portal);
+			}
+		}
+
 		/// <summary>
 		/// Gets the root layout node for this window.
 		/// </summary>
@@ -2200,6 +2232,7 @@ public void SetIsActive(bool value)
 			}
 			else
 			{
+				DismissAutoClosePortals();
 				Deactivated?.Invoke(this, EventArgs.Empty);
 			}
 

SharpConsoleUI/Windows/WindowEventDispatcher.cs

@@ -214,6 +214,9 @@ public bool ProcessMouseEvent(Events.MouseEventArgs args)
 					}
 					else
 					{
+						// === DISMISS PORTALS ON OUTSIDE CLICK ===
+						DismissOutsideClickPortals(args);
+
 						// === EXISTING: NON-SCROLL EVENTS (clicks, etc.) ===
 						// Centralized focus handling on click (left-click and right-click)
 						if (args.HasAnyFlag(MouseFlags.Button1Pressed, MouseFlags.Button1Clicked,
@@ -282,6 +285,50 @@ public bool ProcessMouseEvent(Events.MouseEventArgs args)
 			}
 		}
 
+		/// <summary>
+		/// Dismisses portals that have DismissOnOutsideClick enabled when a click lands outside their bounds.
+		/// Collects targets first to avoid modifying collections during iteration.
+		/// </summary>
+		private void DismissOutsideClickPortals(MouseEventArgs args)
+		{
+			var root = _window.RootLayoutNode;
+			if (root == null) return;
+
+			if (!args.HasAnyFlag(MouseFlags.Button1Pressed, MouseFlags.Button1Clicked,
+			                     MouseFlags.Button3Pressed, MouseFlags.Button3Clicked))
+				return;
+
+			var contentPos = GetContentCoordinates(args.WindowPosition);
+			var toDismiss = new List<LayoutNode>();
+
+			root.Visit(node =>
+			{
+				foreach (var portal in node.PortalChildren)
+				{
+					if (portal.Control is IHasPortalBounds hasPortalBounds
+						&& hasPortalBounds.DismissOnOutsideClick)
+					{
+						var bounds = hasPortalBounds.GetPortalBounds();
+						if (!bounds.Contains(contentPos))
+						{
+							toDismiss.Add(portal);
+						}
+					}
+				}
+			});
+
+			foreach (var portal in toDismiss)
+			{
+				if (portal.Control is PortalContentBase portalContent)
+					portalContent.RaiseDismissRequested();
+
+				// Window.RemovePortal always removes from root node regardless of ownerControl,
+				// so we pass the portal's own control as a placeholder.
+				if (portal.Control != null)
+					_window.RemovePortal(portal.Control, portal);
+			}
+		}
+
 		/// <summary>
 		/// Checks if a window-relative position is within the content area (not title bar or borders)
 		/// </summary>

docs/PORTAL_SYSTEM.md

@@ -14,6 +14,7 @@ SharpConsoleUI's portal system enables overlay rendering — content that floats
 - [Building a Custom Portal](#building-a-custom-portal)
 - [Mouse and Keyboard Routing](#mouse-and-keyboard-routing)
 - [Nested Containers](#nested-containers)
+- [Dismiss on Outside Click](#dismiss-on-outside-click)
 - [Lifecycle Management](#lifecycle-management)
 - [Quick Reference](#quick-reference)
 
@@ -400,6 +401,61 @@ This works because:
 - **Mouse**: Portal forwards to child, child does its own internal hit-testing for nested children
 - **Focus**: `IFocusTrackingContainer` ensures focus tracking through nesting
 
+## Dismiss on Outside Click
+
+Portals can opt in to automatic dismissal when the user clicks outside their bounds. This is useful for dropdowns, context menus, and other transient overlays.
+
+### Enabling
+
+Set `DismissOnOutsideClick` on the portal content:
+
+```csharp
+// Via PortalContentBase subclass
+var portal = new PortalContentContainer();
+portal.DismissOnOutsideClick = true;
+
+// Or via IHasPortalBounds (default-implemented as false)
+public bool DismissOnOutsideClick => true;
+```
+
+### DismissRequested Event
+
+`PortalContentBase` exposes a `DismissRequested` event that fires **before** the portal is removed. Use it for cleanup:
+
+```csharp
+portal.DismissRequested += (sender, e) =>
+{
+    // Clean up state, close related UI, etc.
+    _portalNode = null;
+    _portal = null;
+};
+portal.DismissOnOutsideClick = true;
+
+_portalNode = window.CreatePortal(this, portal);
+```
+
+### How It Works
+
+Portals with `DismissOnOutsideClick = true` are dismissed in two scenarios:
+
+**Outside click:**
+1. On left-click or right-click, `WindowEventDispatcher` walks all portal nodes
+2. For each matching portal, it checks if the click is outside `GetPortalBounds()`
+3. Matching portals are collected first (to avoid modifying the tree during iteration)
+4. `DismissRequested` fires on each, then `RemovePortal()` removes it
+5. Normal click processing continues — the click is **not** consumed
+
+**Window deactivation:**
+1. When the window loses focus (another window is activated, or the user clicks the desktop)
+2. All portals with `DismissOnOutsideClick = true` are dismissed immediately
+3. `DismissRequested` fires before removal, same as outside-click dismissal
+
+### Defaults
+
+- `IHasPortalBounds.DismissOnOutsideClick` defaults to `false` (default interface implementation)
+- `PortalContentBase.DismissOnOutsideClick` is a settable property, also defaulting to `false`
+- Existing portals are completely unaffected unless they explicitly opt in
+
 ## Lifecycle Management
 
 1. **Create** portal content and set bounds
@@ -418,7 +474,7 @@ Always remove portals before disposing the owner control. Portals that outlive t
 | `Window.RemovePortal()` | `Window.cs` | Remove a portal overlay |
 | `PortalContentBase` | `Controls/PortalContentBase.cs` | Abstract base for portal content |
 | `PortalContentContainer` | `Controls/PortalContentContainer.cs` | Container for child controls in portals |
-| `IHasPortalBounds` | `Controls/IHasPortalBounds.cs` | Interface for portal bounds |
+| `IHasPortalBounds` | `Layout/IHasPortalBounds.cs` | Interface for portal bounds and dismiss opt-in |
 | `PortalPositioner` | `Layout/PortalPositioner.cs` | Smart positioning with flip/clamp |
 | `PortalPositionRequest` | `Layout/PortalPositioner.cs` | Positioning request record |
 | `PortalPositionResult` | `Layout/PortalPositioner.cs` | Positioning result record |