@wrongstack/tui 0.9.19 → 0.10.0

package/README.md

@@ -72,9 +72,30 @@ process.exit(exitCode);
 | `@` | File picker |
 | `/` (at start) | Slash command picker |
 | `Ctrl+G` | Toggle agents monitor overlay |
+| `Ctrl+S` | Edit autonomy settings (default mode + auto-proceed delay); also `/settings` |
 | `Esc` | Close any picker / dialog / agents monitor |
 | `Ctrl+L` | Clear screen (TUI keeps state — equivalent to scrolling) |
 
+### Mouse mode (`--mouse`)
+
+With `--mouse` the TUI takes over terminal mouse tracking (forces alt-screen; native wheel-scroll and text selection are suspended until `/mouse off`). Then:
+
+- **Wheel** scrolls chat history, or moves the selection in an open picker.
+- **Click or drag the right-edge scrollbar** to jump/scrub the chat viewport to any position.
+- **Click inside the input** to move the caret (single- and multi-line).
+- **Click** a picker item to select + confirm it (single click).
+- **Click** the permission dialog's `[y]/[n]/[a]/[d]` buttons.
+- **Click** a `/rewind` checkpoint to select it; click again to rewind.
+- **Click** the status-bar model chip to open the model picker, or the `∞ MODE` chip to open the autonomy picker.
+- **Click** a `/settings` row to focus it; click again to cycle its value.
+- **Click** the lower region to dismiss an open monitor (`Ctrl+F/G/T/P`) or the `?` help overlay (parity with `Esc`).
+
+Keyboard shortcuts (always available in managed/alt-screen mode, not just `--mouse`):
+- **PgUp/PgDn** — page scroll through chat history.
+- **Home/End** — jump to top/bottom of chat history (when input is empty); move cursor to start/end of line (when typing).
+- **Ctrl+Home/End** — jump to top/bottom of chat history (always, even when typing).
+- **↑/↓** — navigate input history when buffer is empty.
+
 ## Options worth knowing
 
 - **`altScreen: true`** (default) — render into the terminal's alternate screen buffer (vim/less/htop style). The TUI owns the whole viewport, native scrollback is untouched, and the live region cannot leak into terminal history. Raw mode plus alt-screen also means every keystroke — including Ctrl+S, Ctrl+Q, Ctrl+Z, Ctrl+\\ — reaches Ink instead of being consumed by the terminal driver (`runTui` additionally registers no-op handlers for `SIGTSTP`/`SIGQUIT`/`SIGTTIN`/`SIGTTOU` as belt-and-suspenders). Set `false` (or pass `--no-alt-screen`) to render into normal scrollback if you specifically want completed chat to survive after exit; the trade-off is the documented live-region leak on resize / overlay-close / picker-submit, and that some shortcuts may fall through to the terminal.

package/dist/index.d.ts

@@ -112,6 +112,14 @@ interface RunTuiOptions {
      * while the TUI is up and only what's currently on screen is visible.
      */
     altScreen?: boolean;
+    /**
+     * Enable full mouse support: clickable list items in menus/pickers and
+     * in-app mouse-wheel scrolling of the chat history. Opt-in (default false)
+     * because enabling terminal mouse tracking disables the terminal's own
+     * wheel-scroll and text-selection/copy. When true this FORCES alt-screen
+     * on (the app must own the screen to render its scroll viewport).
+     */
+    mouse?: boolean;
     /**
      * Called right after we exit the alt-screen on a clean shutdown. The
      * CLI uses this to print a one-line "session saved to …" hint into