Polish drag-select auto-copy help text and wiring tests

Align Alt+M copy/help strings and docs with mouse-up clipboard copy,
and pin the SELECTION event path through a live shell.

Author: TheGreatAxios

CHANGELOG.md

@@ -19,6 +19,14 @@ Format loosely follows [Keep a Changelog](https://keepachangelog.com/). Versions
 - Live OTEL collector verify (Phoenix or equivalent) against the merged sink
 - Dogfood session migrate: new session under `~/.corbits/projects`, one legacy `.agent-state` migrate, write under state root still asks
 
+### TUI
+
+- **Drag-select auto-copy.** With mouse capture on (the default), finishing a
+  drag selection in the transcript writes the selected text to the system
+  clipboard on mouse-up and flashes a short status line. Alt+M still hands the
+  mouse back for native terminal selection; Alt+C remains the keyboard copy
+  path for whole messages, tool outputs, and diffs.
+
 ## [0.2.95] - 2026-08-09
 
 Tool-only auto-pause that no longer stops healthy work, resume the last session

docs/TUI.md

@@ -626,7 +626,11 @@ terminal. It cannot observe:
   test round-trips through a real `pbcopy`/`xclip`/terminal clipboard.
 - **Terminal-owned text selection.** Native drag-select only exists once DEC
   mouse reporting is off and a real terminal emulator is running; there is
-  no terminal emulator in the test harness to select text in.
+  no terminal emulator in the test harness to select text in. OpenTUI
+  selection auto-copy is unit-tested (`selection-copy.test.ts`) and wired
+  through a synthetic `SELECTION` event (`copy-wire.test.ts`); a real
+  mouse-up path still needs a manual terminal check.
+
 
 Concretely, whole defect classes — a DEC mouse-reporting toggle that silently
 no-ops, an Alt+key chord a given terminal never actually delivers, a

src/tui/copy-wire.test.ts

@@ -1,4 +1,5 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test"
+import { CliRenderEvents } from "@opentui/core"
 import { createHarness, type Harness } from "./harness"
 import {
   appendStreamRow,
@@ -47,6 +48,44 @@ describe("Alt+C reaches the injected clipboard", () => {
   })
 })
 
+describe("drag-select auto-copy", () => {
+  test("SELECTION event writes finished text and flashes", () => {
+    const clipboard = createRecordingClipboard()
+    const shell = createAppShell(harness.renderer, { clipboard })
+    harness.renderer.emit(CliRenderEvents.SELECTION, {
+      isDragging: false,
+      getSelectedText: () => "dragged snippet",
+    })
+    expect(clipboard.writes).toEqual(["dragged snippet"])
+    expect(shell.statusFlash).toContain("Copied 15 chars")
+    expect(shell.statusFlash).toContain("dragged snippet")
+    shell.dispose()
+  })
+
+  test("SELECTION while dragging is a no-op", () => {
+    const clipboard = createRecordingClipboard()
+    const shell = createAppShell(harness.renderer, { clipboard })
+    harness.renderer.emit(CliRenderEvents.SELECTION, {
+      isDragging: true,
+      getSelectedText: () => "partial",
+    })
+    expect(clipboard.writes).toEqual([])
+    expect(shell.statusFlash).toBeNull()
+    shell.dispose()
+  })
+
+  test("empty SELECTION is a no-op", () => {
+    const clipboard = createRecordingClipboard()
+    const shell = createAppShell(harness.renderer, { clipboard })
+    harness.renderer.emit(CliRenderEvents.SELECTION, {
+      isDragging: false,
+      getSelectedText: () => "",
+    })
+    expect(clipboard.writes).toEqual([])
+    shell.dispose()
+  })
+})
+
 describe("Alt+M mouse capture", () => {
   test("toggles the host port and reports the new state", () => {
     let enabled = false
@@ -60,6 +99,7 @@ describe("Alt+M mouse capture", () => {
     })
     expect(toggleMouseCapture(shell)).toBe(true)
     expect(enabled).toBe(true)
+    expect(shell.statusFlash).toContain("drag text to copy")
     expect(toggleMouseCapture(shell)).toBe(false)
     expect(enabled).toBe(false)
     shell.dispose()

src/tui/keybindings.ts

@@ -25,7 +25,7 @@ export const SHELL_SHORTCUTS: readonly ShellShortcut[] = [
   { keys: "Ctrl+C", description: "interrupt the run, or clear the prompt when idle; press twice to exit" },
   { keys: "Ctrl+G", description: "cancel the most recently queued or steered message before it dispatches" },
   { keys: "Alt+C", description: "copy mode: pick a message, tool output, or diff; press again to close it" },
-  { keys: "Alt+M", description: "release the mouse to the terminal for native drag-select and copy; on by default for wheel scroll and click-to-expand" },
+  { keys: "Alt+M", description: "hand the mouse to the terminal for native drag-select; on by default so wheel scroll, click-to-expand, and drag-to-copy work" },
   { keys: "Alt+E", description: "expand or collapse every collapsible row (tool call, diff, skill, reasoning)" },
   { keys: "Alt+T", description: "show or hide the task list above the prompt" },
   { keys: "Alt+O", description: "observe a live subagent session; a system row says so when there is none" },

src/tui/product-host.ts

@@ -220,8 +220,9 @@ export type ProductHostConfig = {
   /**
    * Take DEC mouse reporting. Default true: wheel/trackpad scroll only
    * reaches OpenTUI when the terminal is told to report it, otherwise the
-   * terminal's own alternate-scroll mode resends it as arrow keys. Alt+M
-   * hands the mouse back to the terminal for native drag-select.
+   * terminal's own alternate-scroll mode resends it as arrow keys. With
+   * reporting on, drag-select is OpenTUI-owned and auto-copies on mouse-up;
+   * Alt+M hands the mouse back for native terminal selection.
    */
   readonly useMouse?: boolean
 }
@@ -317,8 +318,9 @@ export async function mountProductHost(
         // never reaches OpenTUI — the terminal's own alternate-scroll mode
         // swallows it and resends it as arrow keys, which the prompt then
         // reads as history navigation instead of the transcript scrolling.
-        // Cost accepted: this suppresses the terminal's native drag-select
-        // in the main shell. Alt+M hands the mouse back when that is wanted.
+        // Cost accepted: this suppresses the terminal's *native* drag-select
+        // in the main shell. OpenTUI selection still works and auto-copies
+        // on mouse-up; Alt+M hands the mouse back when native select is wanted.
         // enableMouseMovement stays off (no ?1003): only clicks and wheel
         // are needed.
         useMouse: config.useMouse ?? true,

src/tui/shell.ts

@@ -524,21 +524,24 @@ export type AppShellOptions = {
    */
   readonly telemetryNotice?: string
   /**
-   * Clipboard port for Alt+C. Defaults to an in-memory recorder so tests and
-   * demos never shell out; the product host injects the system clipboard.
+   * Clipboard port for Alt+C and drag-select auto-copy. Defaults to an
+   * in-memory recorder so tests and demos never shell out; the product host
+   * injects the system clipboard.
    */
   readonly clipboard?: ClipboardPort
   /**
    * Mouse-reporting switch behind Alt+M. Absent means the shell has no
    * renderer-level control (tests, demos) and reports the toggle unavailable.
+   * While reporting is on, OpenTUI owns drag-select and auto-copies on
+   * mouse-up; Alt+M hands the mouse back for native terminal selection.
    */
   readonly mouseCapture?: MouseCapturePort
 }
 
 /**
  * Renderer-level DEC mouse reporting control. While reporting is on the
- * terminal hands drags to us instead of selecting text, so the user needs a
- * way to hand it back.
+ * terminal hands drags to OpenTUI (drag-to-copy on mouse-up); Alt+M hands
+ * reporting back so the terminal can run its own selection again.
  */
 export type MouseCapturePort = {
   readonly get: () => boolean

src/tui/system-clipboard.ts

@@ -1,10 +1,11 @@
 /**
- * System clipboard port for the keyboard copy path.
+ * System clipboard port for app-owned copy paths.
  *
- * Terminal drag-select is unavailable while DEC mouse reporting is on, so
- * Alt+C must reach the OS clipboard itself rather than relying on the
- * terminal's own selection. Native helpers are preferred; OSC 52 is the
- * fallback for remote sessions where no helper binary exists.
+ * Used by drag-select auto-copy (OpenTUI selection on mouse-up), Alt+C copy
+ * mode, and related keyboard paths. Native terminal drag-select is still
+ * unavailable while DEC mouse reporting is on — Alt+M hands the mouse back
+ * when that is wanted. Native helpers are preferred; OSC 52 is the fallback
+ * for remote sessions where no helper binary exists.
  */
 
 import type { ClipboardPort } from "./copy-path.js"