feat(clipboard): OSC 52 remote copy + bracketed paste

Make copy/paste work over SSH, not just on a local desktop.

Copy: ClipboardHelper.SetText now emits OSC 52 (reaching the LOCAL clipboard
over SSH) in addition to the local tool — belt-and-braces, so it works in any
session. tmux is passthrough-wrapped transparently; screen is detected and
skipped; the payload is size-capped (~74KB) to avoid terminal truncation.
New Osc52Mode (Auto/Enabled/Disabled) override plus public TerminalCapabilities
session flags (IsRemoteSession/IsTmux/IsScreen/SupportsOsc52). The static
ClipboardHelper reaches the terminal via an emitter delegate the driver
registers at Start() and unregisters at Stop(), so it stays driver-agnostic
and writes under the same console lock as the renderer.

Paste: enable bracketed paste (?2004h/?2004l, symmetric in Start/Stop/emergency
cleanup); AnsiInputParser recognizes ESC[200~..ESC[201~ and emits an atomic,
UTF-8-safe PasteInputEvent (chunk-split tolerant; an unterminated paste is
flushed, not stuck). The event flows reader thread -> concurrent paste queue ->
UI thread, never touching controls off-thread. Paste is centralized behind a
new IPasteTarget, routed by the window from BOTH bracketed paste and Ctrl+V —
replacing three duplicate per-control Ctrl+V handlers (MultilineEdit, Prompt,
Table) and fixing Ctrl+V consistency. Multi-line paste inserts as content
(no runaway auto-indent); read-only editors and non-editing table cells no-op.

Fully backward-compatible: local-desktop behavior preserved (local tool still
writes); GetText unchanged; all new public surface is additive.

Author: nickprotop

SharpConsoleUI.Tests/Controls/MarkupControlCopyTests.cs

@@ -18,6 +18,7 @@
 
 namespace SharpConsoleUI.Tests.Controls;
 
+[Collection("EnvSerial")]
 public class MarkupControlCopyTests
 {
 	private static MouseEventArgs Mouse(int x, int y, params MouseFlags[] flags)

SharpConsoleUI.Tests/Core/WindowCopySelectionTests.cs

@@ -18,6 +18,7 @@
 
 namespace SharpConsoleUI.Tests.Core;
 
+[Collection("EnvSerial")]
 public class WindowCopySelectionTests
 {
 	private static MouseEventArgs Mouse(int x, int y, params MouseFlags[] flags)

SharpConsoleUI.Tests/Drivers/BracketedPasteParserTests.cs

@@ -0,0 +1,98 @@
+using System.Text;
+using SharpConsoleUI.Drivers.Input;
+using Xunit;
+
+namespace SharpConsoleUI.Tests.Drivers;
+
+public class BracketedPasteParserTests
+{
+    private static List<InputEvent> Parse(string ascii)
+    {
+        var parser = new AnsiInputParser();
+        var bytes = Encoding.UTF8.GetBytes(ascii);
+        return parser.Parse(bytes.AsSpan(), bytes.Length);
+    }
+
+    [Fact]
+    public void Paste_DeliversSingleEvent_NoPerCharKeys()
+    {
+        var events = Parse("\x1b[200~hello\nworld\x1b[201~");
+        var pastes = events.OfType<PasteInputEvent>().ToList();
+        Assert.Single(pastes);
+        Assert.Equal("hello\nworld", pastes[0].Text);
+        Assert.Empty(events.OfType<KeyInputEvent>());
+    }
+
+    [Fact]
+    public void Paste_ContentWithCsiLikeBytes_IsLiteral()
+    {
+        var events = Parse("\x1b[200~a[1;5B~c\x1b[201~");
+        var pastes = events.OfType<PasteInputEvent>().ToList();
+        Assert.Single(pastes);
+        Assert.Equal("a[1;5B~c", pastes[0].Text);
+    }
+
+    [Fact]
+    public void Paste_SplitAcrossChunks_Reassembles()
+    {
+        var parser = new AnsiInputParser();
+        var all = new List<InputEvent>();
+        foreach (var chunk in new[] { "\x1b[2", "00~hel", "lo\x1b[20", "1~" })
+        {
+            var b = Encoding.UTF8.GetBytes(chunk);
+            all.AddRange(parser.Parse(b.AsSpan(), b.Length));
+        }
+        var pastes = all.OfType<PasteInputEvent>().ToList();
+        Assert.Single(pastes);
+        Assert.Equal("hello", pastes[0].Text);
+    }
+
+    [Fact]
+    public void Paste_Empty_DeliversEmptyText()
+    {
+        var events = Parse("\x1b[200~\x1b[201~");
+        Assert.Single(events.OfType<PasteInputEvent>());
+        Assert.Equal("", events.OfType<PasteInputEvent>().Single().Text);
+    }
+
+    [Fact]
+    public void Bare_EndMarker_NoOpenPaste_IsIgnored()
+    {
+        var events = Parse("\x1b[201~");
+        Assert.Empty(events.OfType<PasteInputEvent>());
+    }
+
+    [Fact]
+    public void NormalKeysAfterPaste_StillParse()
+    {
+        var events = Parse("\x1b[200~x\x1b[201~A");
+        Assert.Single(events.OfType<PasteInputEvent>());
+        Assert.Contains(events.OfType<KeyInputEvent>(), k => k.KeyInfo.KeyChar == 'A');
+    }
+
+    [Fact]
+    public void UnterminatedPaste_FlushesAccumulatedAndResets()
+    {
+        var parser = new AnsiInputParser();
+        var open = Encoding.UTF8.GetBytes("\x1b[200~partial");
+        parser.Parse(open.AsSpan(), open.Length); // no end marker
+
+        var flushed = parser.Flush();
+        var paste = Assert.Single(flushed.OfType<PasteInputEvent>());
+        Assert.Equal("partial", paste.Text);
+
+        // Parser recovered to Ground: a normal key after flush parses correctly.
+        var after = Encoding.UTF8.GetBytes("A");
+        var ev = parser.Parse(after.AsSpan(), after.Length);
+        Assert.Contains(ev.OfType<KeyInputEvent>(), k => k.KeyInfo.KeyChar == 'A');
+    }
+
+    [Fact]
+    public void Paste_Utf8Content_Decodes()
+    {
+        var parser = new AnsiInputParser();
+        var bytes = Encoding.UTF8.GetBytes("\x1b[200~café 漢字\x1b[201~");
+        var events = parser.Parse(bytes.AsSpan(), bytes.Length);
+        Assert.Equal("café 漢字", events.OfType<PasteInputEvent>().Single().Text);
+    }
+}

SharpConsoleUI.Tests/Helpers/ClipboardOsc52Tests.cs

@@ -0,0 +1,82 @@
+using SharpConsoleUI.Helpers;
+using Xunit;
+
+namespace SharpConsoleUI.Tests.Helpers;
+
+[Collection("EnvSerial")]
+public class ClipboardOsc52Tests : IDisposable
+{
+    private readonly List<string> _emitted = new();
+
+    public ClipboardOsc52Tests()
+    {
+        ClipboardHelper.ForceBackendForTests(ClipboardBackend.InternalFallback);
+        ClipboardHelper.RegisterOsc52Emitter(s => _emitted.Add(s));
+        ClipboardHelper.Osc52Mode = Osc52Mode.Auto;
+        TerminalCapabilities.SetOsc52Override(null);
+    }
+
+    public void Dispose()
+    {
+        ClipboardHelper.RegisterOsc52Emitter(null);
+        ClipboardHelper.Osc52Mode = Osc52Mode.Auto;
+        TerminalCapabilities.SetOsc52Override(null);
+        ClipboardHelper.MaxOsc52Bytes = Osc52.DefaultMaxBytes;
+    }
+
+    [Fact]
+    public void Auto_WithOsc52Supported_EmitsAndSetsLocalBuffer()
+    {
+        TerminalCapabilities.SetOsc52Override(true);
+        ClipboardHelper.SetText("hello");
+        Assert.Single(_emitted);
+        Assert.Contains("\x1b]52;c;", _emitted[0]);
+        Assert.Equal("hello", ClipboardHelper.GetText());
+    }
+
+    [Fact]
+    public void Disabled_NeverEmits_ButLocalStillSet()
+    {
+        ClipboardHelper.Osc52Mode = Osc52Mode.Disabled;
+        ClipboardHelper.SetText("hello");
+        Assert.Empty(_emitted);
+        Assert.Equal("hello", ClipboardHelper.GetText());
+    }
+
+    [Fact]
+    public void Enabled_OverridesUnsupported()
+    {
+        ClipboardHelper.Osc52Mode = Osc52Mode.Enabled;
+        TerminalCapabilities.SetOsc52Override(false);
+        ClipboardHelper.SetText("hi");
+        Assert.Single(_emitted);
+    }
+
+    [Fact]
+    public void Auto_WhenOsc52Unsupported_DoesNotEmit_ButLocalStillSet()
+    {
+        TerminalCapabilities.SetOsc52Override(false);
+        ClipboardHelper.SetText("hi");
+        Assert.Empty(_emitted);
+        Assert.Equal("hi", ClipboardHelper.GetText());
+    }
+
+    [Fact]
+    public void OverCap_DoesNotEmit_ButLocalStillSet()
+    {
+        TerminalCapabilities.SetOsc52Override(true);
+        ClipboardHelper.MaxOsc52Bytes = 8;
+        ClipboardHelper.SetText(new string('x', 1000));
+        Assert.Empty(_emitted);
+        Assert.Equal(new string('x', 1000), ClipboardHelper.GetText());
+    }
+
+    [Fact]
+    public void EmitterThrows_SetTextStillSucceeds()
+    {
+        TerminalCapabilities.SetOsc52Override(true);
+        ClipboardHelper.RegisterOsc52Emitter(_ => throw new InvalidOperationException("boom"));
+        ClipboardHelper.SetText("safe");
+        Assert.Equal("safe", ClipboardHelper.GetText());
+    }
+}

SharpConsoleUI.Tests/Helpers/Osc52Tests.cs

@@ -0,0 +1,72 @@
+using System.Text;
+using SharpConsoleUI.Helpers;
+using Xunit;
+
+namespace SharpConsoleUI.Tests.Helpers;
+
+public class Osc52Tests
+{
+    [Fact]
+    public void BuildSequence_Plain_IsByteExact()
+    {
+        // "Hello" -> base64 "SGVsbG8="
+        var seq = Osc52.BuildSequence("Hello", tmuxWrap: false, maxBytes: 1000);
+        Assert.Equal("\x1b]52;c;SGVsbG8=\x07", seq);
+    }
+
+    [Fact]
+    public void BuildSequence_UsesClipboardSelection_c()
+    {
+        var seq = Osc52.BuildSequence("x", tmuxWrap: false, maxBytes: 1000)!;
+        Assert.StartsWith("\x1b]52;c;", seq);
+    }
+
+    [Fact]
+    public void BuildSequence_RoundTripsUtf8AndEmoji()
+    {
+        string text = "café 📦 漢字";
+        var seq = Osc52.BuildSequence(text, tmuxWrap: false, maxBytes: 10000)!;
+        int start = seq.IndexOf(";c;", StringComparison.Ordinal) + 3;
+        int end = seq.IndexOf('\x07');
+        string b64 = seq.Substring(start, end - start);
+        string decoded = Encoding.UTF8.GetString(Convert.FromBase64String(b64));
+        Assert.Equal(text, decoded);
+    }
+
+    [Fact]
+    public void BuildSequence_TmuxWrap_DoublesEscAndWraps()
+    {
+        var seq = Osc52.BuildSequence("Hi", tmuxWrap: true, maxBytes: 1000)!;
+        Assert.Equal("\x1bPtmux;\x1b\x1b]52;c;SGk=\x07\x1b\\", seq);
+    }
+
+    [Fact]
+    public void BuildSequence_OverMaxBytes_ReturnsNull()
+    {
+        string text = new string('a', 100);
+        Assert.Null(Osc52.BuildSequence(text, tmuxWrap: false, maxBytes: 10));
+    }
+
+    [Fact]
+    public void BuildSequence_AtExactCap_Emits()
+    {
+        string text = "abc"; // base64 "YWJj" = 4 chars
+        Assert.NotNull(Osc52.BuildSequence(text, tmuxWrap: false, maxBytes: 4));
+        Assert.Null(Osc52.BuildSequence(text, tmuxWrap: false, maxBytes: 3));
+    }
+
+    [Fact]
+    public void BuildSequence_NullInput_TreatedAsEmpty()
+    {
+        var seq = Osc52.BuildSequence(null!, tmuxWrap: false, maxBytes: 1000);
+        Assert.Equal("\x1b]52;c;\x07", seq);
+    }
+
+    [Fact]
+    public void BuildSequence_EmptyString_EmitsEvenWithZeroCap()
+    {
+        // base64 of "" is "" (length 0), so 0 > maxBytes(0) is false -> emits.
+        var seq = Osc52.BuildSequence("", tmuxWrap: false, maxBytes: 0);
+        Assert.Equal("\x1b]52;c;\x07", seq);
+    }
+}

SharpConsoleUI.Tests/Helpers/TerminalCapabilitiesSessionTests.cs

@@ -0,0 +1,74 @@
+using SharpConsoleUI.Helpers;
+using Xunit;
+
+namespace SharpConsoleUI.Tests.Helpers;
+
+[CollectionDefinition("EnvSerial", DisableParallelization = true)]
+public class EnvSerialCollection { }
+
+[Collection("EnvSerial")]
+public class TerminalCapabilitiesSessionTests
+{
+    private static void WithEnv(Action body, params (string Key, string? Val)[] vars)
+    {
+        var saved = vars.Select(v => (v.Key, Old: Environment.GetEnvironmentVariable(v.Key))).ToList();
+        try
+        {
+            foreach (var v in vars) Environment.SetEnvironmentVariable(v.Key, v.Val);
+            body();
+        }
+        finally
+        {
+            foreach (var s in saved) Environment.SetEnvironmentVariable(s.Key, s.Old);
+        }
+    }
+
+    [Fact]
+    public void Detects_Ssh_Tmux_Screen_AndOsc52()
+    {
+        WithEnv(() =>
+        {
+            TerminalCapabilities.DetectClipboardEnvironmentForTests();
+            Assert.True(TerminalCapabilities.IsRemoteSession);
+            Assert.True(TerminalCapabilities.IsTmux);
+            Assert.False(TerminalCapabilities.IsScreen);
+            Assert.True(TerminalCapabilities.SupportsOsc52); // tmux is fine (we wrap)
+        },
+        ("SSH_TTY", "/dev/pts/3"), ("TMUX", "/tmp/tmux-1000/default,1,0"), ("STY", null));
+    }
+
+    [Fact]
+    public void Screen_DisablesOsc52()
+    {
+        WithEnv(() =>
+        {
+            TerminalCapabilities.DetectClipboardEnvironmentForTests();
+            Assert.True(TerminalCapabilities.IsScreen);
+            Assert.False(TerminalCapabilities.SupportsOsc52);
+        },
+        ("STY", "12345.pts-0.host"), ("SSH_TTY", null), ("TMUX", null));
+    }
+
+    [Fact]
+    public void Local_NoSshVars_IsNotRemote()
+    {
+        WithEnv(() =>
+        {
+            TerminalCapabilities.DetectClipboardEnvironmentForTests();
+            Assert.False(TerminalCapabilities.IsRemoteSession);
+            Assert.True(TerminalCapabilities.SupportsOsc52);
+        },
+        ("SSH_TTY", null), ("SSH_CONNECTION", null), ("TMUX", null), ("STY", null));
+    }
+
+    [Fact]
+    public void SshConnection_AloneMarksRemote()
+    {
+        WithEnv(() =>
+        {
+            TerminalCapabilities.DetectClipboardEnvironmentForTests();
+            Assert.True(TerminalCapabilities.IsRemoteSession);
+        },
+        ("SSH_TTY", null), ("SSH_CONNECTION", "1.2.3.4 5 6.7.8.9 22"), ("TMUX", null), ("STY", null));
+    }
+}

SharpConsoleUI.Tests/InputHandling/PasteRoutingTests.cs

@@ -0,0 +1,47 @@
+using SharpConsoleUI;
+using SharpConsoleUI.Controls;
+using SharpConsoleUI.Tests.Infrastructure;
+using SharpConsoleUI.Windows;
+using Xunit;
+
+namespace SharpConsoleUI.Tests.InputHandling;
+
+[Collection("EnvSerial")]
+public class PasteRoutingTests
+{
+    [Fact]
+    public void BracketedPaste_ReachesFocusedMultilineEdit()
+    {
+        var system = TestWindowSystemBuilder.CreateTestSystem();
+        var window = new Window(system);
+        var editor = new MultilineEditControl();
+        window.AddControl(editor);
+        system.WindowStateService.AddWindow(window);
+        window.FocusManager.SetFocus(editor, FocusReason.Programmatic);
+
+        window.EventDispatcher!.ProcessPaste("alpha\nbeta");
+
+        Assert.Contains("alpha", editor.GetContent());
+        Assert.Contains("beta", editor.GetContent());
+    }
+
+    [Fact]
+    public void CtrlV_RoutesThroughPasteTarget()
+    {
+        SharpConsoleUI.Helpers.ClipboardHelper.ForceBackendForTests(
+            SharpConsoleUI.Helpers.ClipboardBackend.InternalFallback);
+        SharpConsoleUI.Helpers.ClipboardHelper.SetText("pasted-via-ctrlv");
+
+        var system = TestWindowSystemBuilder.CreateTestSystem();
+        var window = new Window(system);
+        var editor = new MultilineEditControl();
+        window.AddControl(editor);
+        system.WindowStateService.AddWindow(window);
+        window.FocusManager.SetFocus(editor, FocusReason.Programmatic);
+
+        var ctrlV = new ConsoleKeyInfo('\u0016', ConsoleKey.V, false, false, true);
+        window.EventDispatcher!.ProcessInput(ctrlV);
+
+        Assert.Contains("pasted-via-ctrlv", editor.GetContent());
+    }
+}