fix(selection): keep selection when clicking inside a context-menu portal; add clipboard docs

Bug: a right-click context menu whose "Copy" item calls CopySelectionToClipboard()
copied nothing. The menu-item click is a Button1Pressed, and the window-level
clear-selection-on-press fired before routing the click to the menu action — so
the selection was already gone when Copy ran. (Copy All, which ignores the
selection, still worked — the tell.)

Fix: WindowEventDispatcher skips the clear-on-press when the press lands inside an
open portal (IsPositionInsideAnyPortal, mirroring DismissOutsideClickPortals'
bounds logic). Overlays like context menus / dropdowns can act on the selection
without wiping it; genuine content clicks still clear it.

Tests: Button1Press_InsideOpenPortal_DoesNotClearSelection (the bug) and
Button1Press_OutsidePortal_StillClearsSelection (clear behavior preserved).

Docs: new docs/CLIPBOARD.md covering OSC 52 remote copy (works over SSH),
bracketed paste, IPasteTarget, the session matrix, and configuration; cross-
referenced from README and the MultilineEdit / Prompt / Markup control docs.

Author: nickprotop

README.md

@@ -287,6 +287,7 @@ Full reference: [nickprotop.github.io/ConsoleEx/docfx/_site/CONTROLS.html](https
 | [Plugins](https://nickprotop.github.io/ConsoleEx/docfx/_site/PLUGINS.html) | Extending the framework |
 | [State Services](https://nickprotop.github.io/ConsoleEx/docfx/_site/STATE-SERVICES.html) | All 11 built-in services |
 | [Threading & Async](docs/THREADING_AND_ASYNC.md) | The UI thread model, async events, and the unresponsive watchdog |
+| [Clipboard, Copy & Paste](docs/CLIPBOARD.md) | OSC 52 remote copy (works over SSH), bracketed paste, and configuration |
 | [Themes](https://nickprotop.github.io/ConsoleEx/docfx/_site/THEMES.html) | Built-in and custom themes |
 | [Comparison](https://nickprotop.github.io/ConsoleEx/docfx/_site/COMPARISON.html) | vs Terminal.Gui, Spectre.Console |
 | [API Reference](https://nickprotop.github.io/ConsoleEx/docfx/_site/api/SharpConsoleUI.html) | Full API docs |

SharpConsoleUI.Tests/Controls/ContextMenuSelectionTests.cs

@@ -0,0 +1,94 @@
+// -----------------------------------------------------------------------
+// ConsoleEx - A simple console window system for .NET Core
+//
+// Author: Nikolaos Protopapas
+// Email: nikolaos.protopapas@gmail.com
+// License: MIT
+// -----------------------------------------------------------------------
+
+using System.Drawing;
+using SharpConsoleUI.Controls;
+using SharpConsoleUI.Drivers;
+using SharpConsoleUI.Events;
+using SharpConsoleUI.Layout;
+using SharpConsoleUI.Tests.Infrastructure;
+using Xunit;
+using Color = SharpConsoleUI.Color;
+
+namespace SharpConsoleUI.Tests.Controls;
+
+/// <summary>
+/// A right-click context menu (a portal) commonly acts on the current text selection — e.g. a "Copy"
+/// item. Clicking inside that menu must NOT clear the window's active selection, otherwise the menu's
+/// action (CopySelectionToClipboard) runs against an already-cleared selection and copies nothing.
+/// </summary>
+public class ContextMenuSelectionTests
+{
+	private static MouseEventArgs WindowMouse(int wx, int wy, params MouseFlags[] flags)
+	{
+		var p = new Point(wx, wy);
+		return new MouseEventArgs(flags.ToList(), p, p, p);
+	}
+
+	[Fact]
+	public void Button1Press_InsideOpenPortal_DoesNotClearSelection()
+	{
+		var system = TestWindowSystemBuilder.CreateTestSystem(80, 25);
+		var window = new Window(system) { Title = "T", Left = 0, Top = 0, Width = 80, Height = 25 };
+		var markup = new MarkupControl(new List<string> { "selectable text here" }) { EnableSelection = true };
+		window.AddControl(markup);
+		system.AddWindow(window);
+		system.Render.UpdateDisplay();
+		system.Render.UpdateDisplay();
+
+		// Establish a real selection on the markup control.
+		var buffer = new CharacterBuffer(45, 15);
+		var bounds = new LayoutRect(0, 0, 40, 10);
+		markup.PaintDOM(buffer, bounds, bounds, Color.White, Color.Black);
+		markup.ProcessMouseEvent(new MouseEventArgs(
+			new List<MouseFlags> { MouseFlags.Button1Pressed }, new Point(0, 0), new Point(0, 0), new Point(0, 0)));
+		markup.ProcessMouseEvent(new MouseEventArgs(
+			new List<MouseFlags> { MouseFlags.Button1Dragged }, new Point(8, 0), new Point(8, 0), new Point(8, 0)));
+		Assert.True(window.SelectionManager.HasSelection);
+
+		// Open a context-menu-like portal with known bounds (content space).
+		var portal = new PortalContentContainer { DismissOnOutsideClick = true };
+		portal.PortalBounds = new Rectangle(5, 5, 20, 6); // content-space bounds
+		var node = window.CreatePortal(markup, portal);
+		Assert.NotNull(node);
+
+		// A left-press INSIDE the portal bounds (window space = content + 1 border) — i.e. clicking a
+		// menu item — must NOT clear the active selection.
+		window.EventDispatcher!.ProcessMouseEvent(WindowMouse(10, 8, MouseFlags.Button1Pressed));
+
+		Assert.True(window.SelectionManager.HasSelection,
+			"Clicking inside an open context-menu portal must not clear the text selection.");
+	}
+
+	[Fact]
+	public void Button1Press_OutsidePortal_StillClearsSelection()
+	{
+		// Regression guard: the clear-on-empty-click behavior is preserved for genuine content clicks.
+		var system = TestWindowSystemBuilder.CreateTestSystem(80, 25);
+		var window = new Window(system) { Title = "T", Left = 0, Top = 0, Width = 80, Height = 25 };
+		var markup = new MarkupControl(new List<string> { "selectable text here" }) { EnableSelection = true };
+		window.AddControl(markup);
+		system.AddWindow(window);
+		system.Render.UpdateDisplay();
+		system.Render.UpdateDisplay();
+
+		var buffer = new CharacterBuffer(45, 15);
+		var bounds = new LayoutRect(0, 0, 40, 10);
+		markup.PaintDOM(buffer, bounds, bounds, Color.White, Color.Black);
+		markup.ProcessMouseEvent(new MouseEventArgs(
+			new List<MouseFlags> { MouseFlags.Button1Pressed }, new Point(0, 0), new Point(0, 0), new Point(0, 0)));
+		markup.ProcessMouseEvent(new MouseEventArgs(
+			new List<MouseFlags> { MouseFlags.Button1Dragged }, new Point(8, 0), new Point(8, 0), new Point(8, 0)));
+		Assert.True(window.SelectionManager.HasSelection);
+
+		// No portal open. Press on empty space far from the markup control clears the selection.
+		window.EventDispatcher!.ProcessMouseEvent(WindowMouse(5, 20, MouseFlags.Button1Pressed));
+
+		Assert.False(window.SelectionManager.HasSelection);
+	}
+}

SharpConsoleUI/Windows/WindowEventDispatcher.cs

@@ -228,8 +228,12 @@ public bool ProcessMouseEvent(Events.MouseEventArgs args)
 						// (empty space, a panel, or another control). The control under the cursor — if it
 						// is selectable — re-establishes its own selection as the drag proceeds. We guard on
 						// "no mouse capture in progress" so SGR drag-continuation presses (Button1Pressed sent
-						// during an active drag) don't wipe the selection being extended.
-						if (args.HasFlag(MouseFlags.Button1Pressed) && _mouseCaptureControl == null)
+						// during an active drag) don't wipe the selection being extended. We also skip the
+						// clear when the press lands inside an open portal (e.g. a right-click context menu
+						// whose "Copy" item acts on the current selection) — otherwise the selection would be
+						// gone before the menu action runs.
+						if (args.HasFlag(MouseFlags.Button1Pressed) && _mouseCaptureControl == null
+							&& !IsPositionInsideAnyPortal(args))
 						{
 							_window.SelectionManager.ClearSelection();
 						}
@@ -302,6 +306,32 @@ public bool ProcessMouseEvent(Events.MouseEventArgs args)
 			}
 		}
 
+		/// <summary>
+		/// Returns true if the given window position lands inside any open portal's bounds.
+		/// Used so that clicking inside an overlay (e.g. a context menu acting on the current text
+		/// selection) does not trigger the window-level clear-selection-on-press.
+		/// </summary>
+		private bool IsPositionInsideAnyPortal(MouseEventArgs args)
+		{
+			var root = _window.RootLayoutNode;
+			if (root == null) return false;
+
+			var contentPos = GetContentCoordinates(args.WindowPosition);
+			bool inside = false;
+			root.Visit(node =>
+			{
+				foreach (var portal in node.PortalChildren)
+				{
+					if (portal.Control is IHasPortalBounds hasPortalBounds
+						&& hasPortalBounds.GetPortalBounds().Contains(contentPos))
+					{
+						inside = true;
+					}
+				}
+			});
+			return inside;
+		}
+
 		/// <summary>
 		/// Dismisses portals that have DismissOnOutsideClick enabled when a click lands outside their bounds.
 		/// Collects targets first to avoid modifying collections during iteration.

docs/CLIPBOARD.md

@@ -0,0 +1,171 @@
+# Clipboard, Copy & Paste
+
+SharpConsoleUI's clipboard is designed to work **both on a local desktop and over SSH** — a copy
+inside an app running on a remote server can land on the operator's **local** clipboard. This guide
+explains how copy and paste work, the remote/SSH behavior, and the configuration knobs.
+
+## TL;DR
+
+- **Copy** writes the system clipboard via the local tool (`xclip`/`wl-copy`/`pbcopy`/`clip.exe`)
+  **and** emits an [OSC 52](#osc-52-the-remote-clipboard-escape) escape so the text also reaches the
+  **local** clipboard over SSH. Belt-and-braces — it works whether the session is local or remote.
+- **Paste** uses the terminal's own paste. [Bracketed paste](#bracketed-paste) is enabled so a
+  multi-line paste inserts as one atomic block (no runaway auto-indent), and `Ctrl+V` reads the
+  clipboard for local sessions.
+- **Backward compatible:** the local-tool path is unchanged; everything new is additive and on by
+  default in a way that never breaks existing local behavior.
+
+## The `ClipboardHelper` API
+
+All copy/paste flows through `SharpConsoleUI.Helpers.ClipboardHelper`:
+
+```csharp
+ClipboardHelper.SetText("hello");      // copy (local tool + OSC 52)
+string text = ClipboardHelper.GetText(); // read back (local tool / in-process buffer)
+```
+
+`SetText` never throws — clipboard operations are best-effort.
+
+## How copy works
+
+`SetText` does two things, in order:
+
+1. **Emit OSC 52** (when enabled — see below) through the terminal's output stream. This is what
+   reaches the **local** clipboard over SSH.
+2. **Run the local clipboard tool** (unchanged from earlier versions): `clip.exe` (Windows),
+   `pbcopy` (macOS), `wl-copy` / `xclip` / `xsel` (Linux), or an in-process buffer when none is
+   found.
+
+Both run on every copy. On a local desktop the OSC 52 is harmless (the terminal either honors it —
+setting the same clipboard the local tool just set — or silently ignores an unknown escape). Over
+SSH the local tool typically finds no clipboard on the (often headless) server, and OSC 52 carries
+the text to your machine.
+
+> OSC 52 is only emitted when running inside a live `ConsoleWindowSystem` (the console driver
+> registers the emitter at startup). In tests or non-driver contexts no escape is written.
+
+### OSC 52: the remote-clipboard escape
+
+[OSC 52](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands) is a
+terminal escape sequence (`ESC ] 52 ; c ; <base64> BEL`) that asks the **terminal** — i.e. the
+program on your local machine — to set its clipboard. Because the terminal runs locally, this is the
+mechanism that crosses an SSH boundary. Most modern terminals support it (iTerm2, WezTerm, kitty,
+Alacritty, Windows Terminal, foot, …); some disable it by default for security and must be opted in.
+
+Whether OSC 52 actually lands is therefore a property of **your terminal**, not the library. The
+library always emits a correct sequence when enabled; the terminal decides whether to honor it.
+
+## Behavior by session type
+
+| Session | OSC 52 | Where a copy lands |
+|---|---|---|
+| Local (X11 / Wayland / macOS / Windows) | emitted (redundant) | Local clipboard via the local tool (and OSC 52 if the terminal honors it) |
+| SSH, plain terminal | emitted | **Local** clipboard (if the terminal supports OSC 52) |
+| SSH + **tmux** | emitted, **passthrough-wrapped** | **Local** clipboard — no `~/.tmux.conf` change needed |
+| SSH + **screen** (`STY` set) | **skipped** | Server-side tool / in-process buffer (OSC 52 is unreliable under screen) |
+| Copy larger than ~74 KB | **skipped** | Local tool only (OSC 52 has terminal size limits) |
+
+Session detection happens once at startup and is exposed (read-only) on
+`SharpConsoleUI.Helpers.TerminalCapabilities`:
+
+```csharp
+TerminalCapabilities.IsRemoteSession  // SSH_TTY or SSH_CONNECTION set
+TerminalCapabilities.IsTmux           // TMUX set — OSC 52 is passthrough-wrapped
+TerminalCapabilities.IsScreen         // STY set — OSC 52 skipped
+TerminalCapabilities.SupportsOsc52    // whether OSC 52 will be attempted (false under screen)
+```
+
+## Configuration
+
+OSC 52 emission is controlled by `ClipboardHelper.Osc52Mode` (default `Auto`):
+
+```csharp
+// Default: emit when the session is believed to support OSC 52.
+ClipboardHelper.Osc52Mode = Osc52Mode.Auto;
+
+// Always emit, regardless of detection (e.g. a terminal you know supports it).
+ClipboardHelper.Osc52Mode = Osc52Mode.Enabled;
+
+// Never emit — local tools / in-process buffer only.
+ClipboardHelper.Osc52Mode = Osc52Mode.Disabled;
+
+// Override capability detection (e.g. force-enable under screen, or disable for a known-bad terminal).
+TerminalCapabilities.SetOsc52Override(true);   // force on
+TerminalCapabilities.SetOsc52Override(false);  // force off
+TerminalCapabilities.SetOsc52Override(null);   // restore auto-detection
+
+// Adjust the OSC 52 size cap (base64 payload length). Larger copies skip OSC 52.
+ClipboardHelper.MaxOsc52Bytes = Osc52.DefaultMaxBytes; // 74000
+```
+
+## How paste works
+
+### Bracketed paste
+
+When the app starts it enables **bracketed paste** (`ESC[?2004h`). The terminal then wraps pasted
+content in `ESC[200~` … `ESC[201~`, so the app can recognize a paste as one block instead of a flood
+of individual keystrokes. Without it, a multi-line paste would be processed key-by-key — newlines
+running as Enter, auto-indent corrupting the text. With it, the block is delivered atomically and
+inserted as content.
+
+This is also **the paste path that works over SSH**: when you press your terminal's paste
+(Cmd/Ctrl+Shift+V, middle-click, etc.), the terminal injects your **local** clipboard into the SSH
+stream, and bracketed paste lets the app insert it correctly.
+
+### `Ctrl+V` and `IPasteTarget`
+
+Paste is centralized: the window routes **both** a bracketed-paste block and `Ctrl+V` to the focused
+control's `IPasteTarget.Paste(string)`:
+
+```csharp
+public interface IPasteTarget
+{
+    void Paste(string text); // insert text at the current position as a single block
+}
+```
+
+Built-in editors implement it (`MultilineEditControl`, `PromptControl`, `TableControl`). `Ctrl+V`
+reads `ClipboardHelper.GetText()` (the local-session source); bracketed paste uses the
+terminal-delivered text. A read-only editor's `Paste` is a no-op; `PromptControl` (single-line)
+flattens embedded newlines to spaces.
+
+> **Remote paste note:** reading the clipboard *back* (`GetText`, the `Ctrl+V` source) reads the
+> **server-side** clipboard over SSH — most terminals disable OSC 52 clipboard *reads* for security,
+> so there is no reliable app-driven remote read. Use your **terminal's** paste over SSH; bracketed
+> paste makes it insert correctly.
+
+## Verifying it works
+
+Automated tests cover the encoder (byte-exact OSC 52 + tmux wrap), session detection, the layered
+`SetText`, the bracketed-paste parser, and end-to-end paste routing. The real round-trip depends on
+your terminal, so confirm it manually:
+
+```bash
+# Local
+dotnet run --project Examples/DemoApp
+#   → Controls → Selectable Text: drag-select, Ctrl+C, paste into a local editor.
+
+# Remote (the real test) — from an OSC 52-capable terminal
+ssh you@server
+dotnet run --project Examples/DemoApp
+#   → select + Ctrl+C in the app → paste on your LOCAL machine.
+#   → paste a multi-line block into the editor → it inserts as one block.
+```
+
+## Backward compatibility
+
+- The local clipboard tool still runs on every copy exactly as before; OSC 52 is added in front of
+  it and is a no-op on terminals that don't support it.
+- `GetText` is unchanged.
+- All new surface (`Osc52Mode`, `MaxOsc52Bytes`, the `TerminalCapabilities` session flags,
+  `IPasteTarget`) is additive; nothing existing was removed or changed in default behavior.
+
+## See also
+
+- [MultilineEditControl](controls/MultilineEditControl.md) — multi-line editor (Ctrl+C/X/V)
+- [PromptControl](controls/PromptControl.md) — single-line input with clipboard support
+- [MarkupControl](controls/MarkupControl.md) — opt-in selectable/copyable display text
+
+---
+
+[Back to Documentation](../README.md#documentation)

docs/controls/MarkupControl.md

@@ -212,6 +212,9 @@ The control implements `ISelectableControl`, so it participates in the window's
 `MultilineEditControl` also implements `ISelectableControl`, so an editor and selectable markup
 controls in the same window share the single-selection behavior.
 
+> Copy works locally **and over SSH** — see [Clipboard, Copy & Paste](../CLIPBOARD.md) for how OSC 52
+> carries the copy to the local clipboard over a remote session, and how to configure it.
+
 ### Programmatic Copy
 
 ```csharp

docs/controls/MultilineEditControl.md

@@ -320,6 +320,11 @@ editor.ClearFind();       // Remove all match highlighting
 | Insert | Toggle overwrite mode |
 | Escape | Exit edit mode (if `EscapeExitsEditMode` is true) |
 
+> Copy/paste works locally and over SSH. The editor implements `IPasteTarget`, so `Ctrl+V` and
+> terminal-native (bracketed) paste both insert atomically. See
+> [Clipboard, Copy & Paste](../CLIPBOARD.md) for how copy reaches the local clipboard over SSH
+> (OSC 52) and how to configure it.
+
 ## Mouse Support
 
 | Interaction | Action |

docs/controls/PromptControl.md

@@ -90,6 +90,10 @@ prompt.Entered += (sender, text) => ProcessInput(text);
 | `Ctrl+V` | Paste from clipboard |
 | `Ctrl+X` | Cut selection to clipboard |
 
+> Copy/paste works locally and over SSH. The control implements `IPasteTarget` (paste is single-line:
+> newlines are flattened to spaces). See [Clipboard, Copy & Paste](../CLIPBOARD.md) for the OSC 52
+> remote-clipboard behavior and configuration.
+
 ### History & Completion
 
 | Key | Action |