Auto-copy highlighted text to clipboard on mouse-up

OpenTUI emits CliRenderEvents.SELECTION once when a drag-select finishes
(mouse-up). A new copyFinishedSelection handler writes the selected text
through the system clipboard port, flashes a status line with a char count
and preview, then clears the highlight so the selection does not linger.
Empty selections and mid-drag updates are no-ops.

The Alt+M flash copy is updated to name the new behavior, and docs/TUI.md
documents the drag-select-copy path alongside the existing Alt+M and Alt+C
chords.

Author: TheGreatAxios

docs/TUI.md

@@ -535,19 +535,24 @@ a stop does not reliably produce an idle event to drain against later.
 
 The main session shell owns the mouse. With DEC mouse reporting on (the
 default), the wheel scrolls the transcript, clicking a collapsed tool row or
-diff arrow expands it in place, and dragging inside the transcript scrolls it
-— none of that needs a modifier key. The cost of holding the mouse this way
-is that native terminal drag-select is unavailable while reporting is on:
-the terminal hands drag events to the app instead of running its own
-selection. Two chords cover that gap without needing the mouse released
-first:
-
+diff arrow expands it in place, and dragging across selectable text starts an
+OpenTUI selection that **auto-copies to the system clipboard on mouse-up**.
+Dragging on non-selectable chrome still scrolls. The cost of holding the
+mouse this way is that *native* terminal drag-select is unavailable while
+reporting is on: the terminal hands drag events to the app instead of
+running its own selection. Two chords cover remaining copy needs:
+
+- **Drag-select (mouse captured)** uses OpenTUI's selection event
+  (`CliRenderEvents.SELECTION` → `copyFinishedSelection` in
+  `selection-copy.ts`). On mouse-up, non-empty selected text is written
+  through the system clipboard port and the highlight clears with a status
+  flash. Empty clicks do not copy.
 - **Alt+M** toggles DEC mouse reporting off and back on
   (`toggleMouseCapture`, `shell.ts`). Off, the terminal's own drag-select
   and copy work exactly as in any other terminal program; the status flash
   names the trade both ways ("Mouse released · drag to select and copy as
-  usual · Alt+M to click rows" / "Mouse captured · click to expand, drag to
-  scroll · Alt+M to select text again").
+  usual · Alt+M to click rows" / "Mouse captured · drag text to copy ·
+  click to expand · Alt+M for native select").
 - **Alt+C** copies a message, tool output, or diff without touching the
   mouse at all: it opens a copy-selection surface over the transcript
   (`enterCopyMode`) that resolves through the system clipboard port

src/tui/selection-copy.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test"
+import { createRecordingClipboard } from "./copy-path.js"
+import {
+  copyFinishedSelection,
+  type SelectionCopyHost,
+} from "./selection-copy.js"
+
+function host(): SelectionCopyHost & {
+  readonly clipboard: ReturnType<typeof createRecordingClipboard>
+  flashes: string[]
+  cleared: number
+} {
+  const clipboard = createRecordingClipboard()
+  const flashes: string[] = []
+  let cleared = 0
+  return {
+    clipboard,
+    flashes,
+    get cleared() {
+      return cleared
+    },
+    flash: (text: string) => {
+      flashes.push(text)
+    },
+    clearSelection: () => {
+      cleared += 1
+    },
+  }
+}
+
+describe("copyFinishedSelection", () => {
+  test("writes selected text, flashes, and clears the highlight", () => {
+    const h = host()
+    const ok = copyFinishedSelection(h, {
+      isDragging: false,
+      getSelectedText: () => "hello world",
+    })
+    expect(ok).toBe(true)
+    expect(h.clipboard.writes).toEqual(["hello world"])
+    expect(h.flashes[0]).toContain("Copied 11 chars")
+    expect(h.flashes[0]).toContain("hello world")
+    expect(h.cleared).toBe(1)
+  })
+
+  test("skips while still dragging", () => {
+    const h = host()
+    const ok = copyFinishedSelection(h, {
+      isDragging: true,
+      getSelectedText: () => "partial",
+    })
+    expect(ok).toBe(false)
+    expect(h.clipboard.writes).toEqual([])
+    expect(h.flashes).toEqual([])
+    expect(h.cleared).toBe(0)
+  })
+
+  test("skips empty selection", () => {
+    const h = host()
+    const ok = copyFinishedSelection(h, {
+      isDragging: false,
+      getSelectedText: () => "",
+    })
+    expect(ok).toBe(false)
+    expect(h.clipboard.writes).toEqual([])
+    expect(h.cleared).toBe(0)
+  })
+
+  test("truncates long flash previews", () => {
+    const h = host()
+    const long = "x".repeat(80)
+    copyFinishedSelection(h, {
+      isDragging: false,
+      getSelectedText: () => long,
+    })
+    expect(h.clipboard.writes).toEqual([long])
+    expect(h.flashes[0]).toContain("…")
+    expect(h.flashes[0]!.length).toBeLessThan(long.length + 40)
+  })
+})

src/tui/selection-copy.ts

@@ -0,0 +1,43 @@
+/**
+ * Auto-copy finished OpenTUI mouse selections to the system clipboard.
+ *
+ * OpenTUI emits CliRenderEvents.SELECTION once on mouse-up
+ * (`finishSelection`). Mid-drag updates do not emit that event, so one
+ * handler is copy-on-release without per-pixel noise.
+ */
+
+import type { Selection } from "@opentui/core"
+import type { ClipboardPort } from "./copy-path.js"
+
+/** Minimal deps so unit tests do not need a full AppShell. */
+export type SelectionCopyHost = {
+  readonly clipboard: ClipboardPort
+  readonly flash: (text: string) => void
+  readonly clearSelection: () => void
+}
+
+/** Slice of OpenTUI Selection used by the copy path. */
+export type FinishedSelection = {
+  readonly isDragging: boolean
+  getSelectedText(): string
+}
+
+/**
+ * Copy a finished (non-dragging) selection. Returns true when text was
+ * written. Empty selections and still-dragging states are no-ops.
+ */
+export function copyFinishedSelection(
+  host: SelectionCopyHost,
+  selection: FinishedSelection | Selection,
+): boolean {
+  if (selection.isDragging) return false
+  const text = selection.getSelectedText()
+  if (text.length === 0) return false
+
+  void host.clipboard.writeText(text)
+  const preview =
+    text.length > 48 ? `${text.slice(0, 45).replace(/\s+/g, " ")}…` : text
+  host.flash(`Copied ${text.length} chars: ${preview}`)
+  host.clearSelection()
+  return true
+}

src/tui/shell.ts

@@ -23,6 +23,7 @@ import {
   type CliRenderer,
   type KeyEvent,
   type MouseEvent,
+  type Selection,
   type TextChunk,
 } from "@opentui/core"
 
@@ -151,6 +152,7 @@ import {
   type ClipboardPort,
   type CopyTarget,
 } from "./copy-path.js"
+import { copyFinishedSelection } from "./selection-copy.js"
 import {
   badgeCount,
   cancelLast,
@@ -473,7 +475,7 @@ function dispatchOverlayAccept(
 /** Renderer surface required by the shell (CliRenderer / createTestRenderer). */
 export type ShellRenderer = Pick<
   CliRenderer,
-  "root" | "width" | "height" | "keyInput" | "on" | "off" | "isDestroyed"
+  "root" | "width" | "height" | "keyInput" | "on" | "off" | "isDestroyed" | "clearSelection"
 >
 
 export type AppShellOptions = {
@@ -4512,7 +4514,7 @@ export function toggleMouseCapture(shell: AppShell): boolean | null {
   setStatusFlash(
     shell,
     next
-      ? "Mouse captured · click to expand, drag to scroll · Alt+M to select text again"
+      ? "Mouse captured · drag text to copy · click to expand · Alt+M for native select"
       : "Mouse released · drag to select and copy as usual · Alt+M to click rows",
   )
   return next
@@ -5762,6 +5764,23 @@ export function createAppShell(
   renderer.on(CliRenderEvents.FRAME, onFrame)
   renderer.on(CliRenderEvents.RESIZE, onResize)
 
+  // Declared before shell so dispose can off() the same function reference;
+  // body closes over shell after createAppShell finishes assigning it.
+  const onSelection = (selection: Selection): void => {
+    if (disposed) return
+    copyFinishedSelection(
+      {
+        clipboard: shell.clipboard,
+        flash: (text) => setStatusFlash(shell, text),
+        clearSelection: () => {
+          renderer.clearSelection()
+        },
+      },
+      selection,
+    )
+  }
+  renderer.on(CliRenderEvents.SELECTION, onSelection)
+
   const shell: AppShell = {
     renderer,
     root,
@@ -5827,6 +5846,7 @@ export function createAppShell(
       }
       renderer.off(CliRenderEvents.FRAME, onFrame)
       renderer.off(CliRenderEvents.RESIZE, onResize)
+      renderer.off(CliRenderEvents.SELECTION, onSelection)
       internals.get(shell)?.landingIdleTimerCancel?.()
       flashTimers.get(shell)?.()
       flashTimers.delete(shell)