Skip to content

Commit 8341ee6

Browse files
authored
feat(tuika): mouse subsystem — selection, clicks, hit-testing, OSC 52 copy (#361)
## What changed Answers "does `--fullscreen` support mouse selection?" — it didn't (mouse capture suppresses the terminal's own selection, and tuika had nothing to replace it). This adds the **mouse foundation a best-in-class TUI needs**, entirely in tuika and fully unit-tested in-memory. Benchmarked against how the strong terminal apps do it — selection computed over the rendered cell grid, clipboard via **OSC 52** ([go-osc52](https://pkg.go.dev/github.com/aymanbagabas/go-osc52/v2), [opencode](anomalyco/opencode#19982), [tmux passthrough](tmux/tmux#3192)). **Enriched event model** (`event.rs`) — `MouseKind` gains buttons + drag: `Down/Up/Drag(MouseButton)`, `Moved`, `ScrollUp/Down/Left/Right`; every `Mouse` reports `shift/ctrl/alt` (+ `plain()` and a `Mouse::at` ctor). `host.rs` maps crossterm buttons/modifiers. **`mouse` module** - **`SelectionState`** — a left `Down → Drag → Up` gesture becomes a `SelectionRange`; a plain click selects nothing, a new press clears the old selection. - **`selected_text`** — linear/stream extraction from the rendered `ratatui::Buffer` (tail of the first row, whole middle rows, head of the last), trailing blanks trimmed, wide glyphs intact. **`highlight`** patches the selected cells (glyph + fg survive). - **`HitMap<T>`** — region→value click hit-testing, last-pushed wins (children/overlays over parents). **`ClickTracker`** — a same-cell `Down`/`Up` is a `Click`; an intervening drag cancels it. **`clipboard` module** — OSC 52 copy (`osc52` encoder + `write_clipboard`) with an **inline base64 encoder so tuika stays dependency-free**. Size-capped at 74,994 bytes (refuses rather than truncates); tmux `allow-passthrough` caveat documented, mirroring OSC 8. **Touch** needs no separate API — emulators deliver taps/swipes as mouse events, so touch flows through this same path (documented, not faked). ## Testing **17 new tests, 100 total in tuika, `clippy --all-targets -D warnings` clean.** Highlights (you asked specifically about clicks): ``` selection_tracks_a_left_drag / normalizes_a_backwards_drag ... ok a_plain_click_leaves_no_selection ... ok a_new_press_clears_the_previous_selection ... ok selected_text_reads_one_row / spans_rows_linearly / trims_trailing_blanks ... ok highlight_patches_selected_cells_only ... ok hit_map_last_region_wins_and_misses_return_none ... ok click_tracker_detects_a_click ... ok click_tracker_drag_cancels_the_click ... ok click_tracker_release_on_another_cell_is_not_a_click ... ok translate_maps_button_modifiers_and_drag ... ok base64_matches_known_vectors (RFC 4648) / osc52_wraps_base64 / refuses_oversized ... ok ``` `cargo build --bin yolop` green — the one consumer (`handle_fullscreen_scroll`) updated to the new `Mouse` shape. ## Why in tuika (not yolop) It's a reusable terminal-UI capability with zero yolop knowledge — same home as the OSC 8 hyperlink and OSC 9;4 progress work. yolop (and any consumer) gets selection/clicks/clipboard for free. ## Risk - **Low.** Additive module + a contained breaking change to tuika's pre-1.0 `Mouse`/`MouseKind` (one in-tree consumer, updated). No behavior change to yolop yet. ## Follow-up (needs a real terminal, like the hyperlinks work) Wire selection into yolop's full-screen transcript — left-drag selects, `highlight` renders it, release copies via OSC 52 — plus a runnable `examples/mouse.rs`, verified across Ghostty / iTerm2 / WezTerm / Kitty / tmux. That's the manual-matrix half; this PR lands the verified foundation it builds on. ## Checklist - [x] Tests added or updated - [x] Backward compatibility considered (pre-1.0; single consumer updated) --- _Generated by [Claude Code](https://claude.ai/code/session_01LksbgmgJfiGmNXXGZphgW6)_
1 parent 35b6157 commit 8341ee6

8 files changed

Lines changed: 696 additions & 21 deletions

File tree

‎crates/tuika/README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,37 @@ so it works in both the inline and full-screen renderers; terminals that don't
171171
understand it ignore the sequence. yolop shows it (indeterminate) while a turn
172172
runs and clears it when idle.
173173

174+
## Mouse, selection, and clipboard
175+
176+
Enabling mouse capture (which `AltScreen` / `TerminalSession` do) means the
177+
terminal stops doing its own click-drag text selection and hands every drag to
178+
the app instead. The `mouse` module rebuilds those affordances over the grid
179+
you already rendered:
180+
181+
- **Text selection.** `SelectionState` turns a left-button `Down → Drag → Up`
182+
gesture into a `SelectionRange` (a plain click selects nothing; a new press
183+
clears the old selection). `selected_text(buffer, area, range)` reads the text
184+
back out of the rendered `ratatui::Buffer` — linear/stream selection like a
185+
terminal's own, wide glyphs intact — and `highlight(buffer, area, range,
186+
style)` paints it in.
187+
- **Clicks and regions.** `HitMap<T>` maps screen rects to values (a button, a
188+
link, a row); the last-pushed match wins, so children/overlays registered
189+
after their parents take precedence. `ClickTracker` turns a same-cell
190+
`Down`/`Up` into a `Click` and lets an intervening drag cancel it.
191+
- **Clipboard.** `clipboard::write_clipboard(out, text)` copies via **OSC 52**
192+
(`clipboard::osc52` is the pure encoder) — no platform clipboard library,
193+
works over SSH. Same tmux caveat as OSC 8: needs `allow-passthrough on`.
194+
195+
The enriched event model carries what selection and clicks need: `MouseKind` is
196+
`Down/Up/Drag(MouseButton)`, `Moved`, and `ScrollUp/Down/Left/Right`, and every
197+
`Mouse` reports `shift/ctrl/alt`. **Shift-drag** is deliberately left to the
198+
terminal — most emulators use it to bypass app mouse capture for a native
199+
selection — so a host should act on `plain()` left-drags.
200+
201+
**Touch** arrives as mouse events: terminal emulators translate a tap to a
202+
`Down`+`Up` and a swipe to scroll or a drag, so touch flows through this same
203+
path — there is no separate touch event to handle.
204+
174205
## Testing
175206

176207
Layout and rendering are tested hermetically by rendering into an in-memory

‎crates/tuika/src/clipboard.rs‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
//! System clipboard writes via OSC 52.
2+
//!
3+
//! Like [`crate::hyperlink`] (OSC 8) and [`crate::native`] (OSC 9;4), this is an
4+
//! out-of-band terminal capability: the app writes an escape sequence and the
5+
//! terminal — not the app — puts the text on the system clipboard. It needs no
6+
//! platform clipboard library and works over SSH, which is why it's the right
7+
//! fit for copying a mouse selection (see [`crate::mouse`]).
8+
//!
9+
//! The sequence is `OSC 52 ; c ; <base64> ST`, where the payload is the text
10+
//! base64-encoded (RFC 4648) and `c` selects the system clipboard. Terminals
11+
//! that support OSC 52 (Ghostty, iTerm2 with it enabled, WezTerm, Kitty, recent
12+
//! VTE, xterm) copy it; others ignore the sequence. Under tmux it requires
13+
//! `set -g allow-passthrough on` (or tmux's own `set-clipboard`), the same
14+
//! passthrough caveat as OSC 8 hyperlinks.
15+
//!
16+
//! Terminals cap an OSC 52 sequence near 100 000 bytes; encoded, that bounds
17+
//! the copyable text at [`MAX_LEN`] bytes. Longer text is refused rather than
18+
//! sent truncated (a truncated clipboard is worse than a failed copy).
19+
20+
use std::io::{self, Write};
21+
22+
/// Maximum length, in bytes, of text a single OSC 52 write will copy. Beyond
23+
/// this the terminal would truncate the sequence, so [`osc52`] refuses it.
24+
pub const MAX_LEN: usize = 74_994;
25+
26+
/// String terminator for the OSC sequence: `ESC \`.
27+
const ST: &str = "\x1b\\";
28+
29+
/// Encode `text` as an OSC 52 clipboard-set sequence, or `None` when `text` is
30+
/// empty or longer than [`MAX_LEN`]. Pure and allocation-only — no I/O.
31+
pub fn osc52(text: &str) -> Option<String> {
32+
if text.is_empty() || text.len() > MAX_LEN {
33+
return None;
34+
}
35+
Some(format!("\x1b]52;c;{}{ST}", base64_encode(text.as_bytes())))
36+
}
37+
38+
/// Copy `text` to the system clipboard by writing an OSC 52 sequence to `out`.
39+
/// Returns `Ok(true)` when a sequence was written, `Ok(false)` when `text` was
40+
/// empty or too large (see [`MAX_LEN`]).
41+
pub fn write_clipboard(out: &mut impl Write, text: &str) -> io::Result<bool> {
42+
match osc52(text) {
43+
Some(seq) => {
44+
out.write_all(seq.as_bytes())?;
45+
out.flush()?;
46+
Ok(true)
47+
}
48+
None => Ok(false),
49+
}
50+
}
51+
52+
/// Standard base64 (RFC 4648) with `=` padding. Inlined to keep `tuika` free of
53+
/// a base64 dependency.
54+
fn base64_encode(data: &[u8]) -> String {
55+
const ALPHABET: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
56+
let mut out = String::with_capacity(data.len().div_ceil(3) * 4);
57+
for chunk in data.chunks(3) {
58+
let b0 = chunk[0] as u32;
59+
let b1 = *chunk.get(1).unwrap_or(&0) as u32;
60+
let b2 = *chunk.get(2).unwrap_or(&0) as u32;
61+
let n = (b0 << 16) | (b1 << 8) | b2;
62+
out.push(ALPHABET[((n >> 18) & 0x3f) as usize] as char);
63+
out.push(ALPHABET[((n >> 12) & 0x3f) as usize] as char);
64+
out.push(if chunk.len() > 1 {
65+
ALPHABET[((n >> 6) & 0x3f) as usize] as char
66+
} else {
67+
'='
68+
});
69+
out.push(if chunk.len() > 2 {
70+
ALPHABET[(n & 0x3f) as usize] as char
71+
} else {
72+
'='
73+
});
74+
}
75+
out
76+
}
77+
78+
#[cfg(test)]
79+
mod tests {
80+
use super::*;
81+
82+
#[test]
83+
fn base64_matches_known_vectors() {
84+
// RFC 4648 test vectors.
85+
assert_eq!(base64_encode(b""), "");
86+
assert_eq!(base64_encode(b"f"), "Zg==");
87+
assert_eq!(base64_encode(b"fo"), "Zm8=");
88+
assert_eq!(base64_encode(b"foo"), "Zm9v");
89+
assert_eq!(base64_encode(b"foob"), "Zm9vYg==");
90+
assert_eq!(base64_encode(b"fooba"), "Zm9vYmE=");
91+
assert_eq!(base64_encode(b"foobar"), "Zm9vYmFy");
92+
}
93+
94+
#[test]
95+
fn osc52_wraps_base64_payload() {
96+
assert_eq!(
97+
osc52("foobar"),
98+
Some("\x1b]52;c;Zm9vYmFy\x1b\\".to_string())
99+
);
100+
}
101+
102+
#[test]
103+
fn osc52_refuses_empty_and_oversized() {
104+
assert_eq!(osc52(""), None);
105+
let big = "x".repeat(MAX_LEN + 1);
106+
assert_eq!(osc52(&big), None);
107+
// Exactly at the cap is allowed.
108+
assert!(osc52(&"x".repeat(MAX_LEN)).is_some());
109+
}
110+
111+
#[test]
112+
fn write_clipboard_reports_whether_it_wrote() {
113+
let mut buf: Vec<u8> = Vec::new();
114+
assert!(write_clipboard(&mut buf, "hi").expect("write"));
115+
assert_eq!(buf, b"\x1b]52;c;aGk=\x1b\\");
116+
117+
let mut empty: Vec<u8> = Vec::new();
118+
assert!(!write_clipboard(&mut empty, "").expect("write"));
119+
assert!(empty.is_empty());
120+
}
121+
}

‎crates/tuika/src/event.rs‎

Lines changed: 46 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,17 +63,60 @@ pub enum KeyCode {
6363
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
6464
pub struct Mouse {
6565
pub kind: MouseKind,
66+
/// Cell column (0-based, terminal coordinates).
6667
pub column: u16,
68+
/// Cell row (0-based, terminal coordinates).
6769
pub row: u16,
70+
pub shift: bool,
71+
pub ctrl: bool,
72+
pub alt: bool,
73+
}
74+
75+
impl Mouse {
76+
/// A bare event at `(column, row)` with the given kind and no modifiers —
77+
/// convenience for tests and synthetic events.
78+
pub fn at(kind: MouseKind, column: u16, row: u16) -> Self {
79+
Self {
80+
kind,
81+
column,
82+
row,
83+
shift: false,
84+
ctrl: false,
85+
alt: false,
86+
}
87+
}
88+
89+
/// True when no modifier keys are held. Terminals also use Shift-drag to
90+
/// bypass application mouse capture for native selection, so a host that
91+
/// implements its own selection should generally act only on `plain()`
92+
/// left-drags and leave Shift-drags to the terminal.
93+
pub fn plain(&self) -> bool {
94+
!self.shift && !self.ctrl && !self.alt
95+
}
96+
}
97+
98+
/// Which mouse button an event refers to.
99+
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
100+
pub enum MouseButton {
101+
Left,
102+
Right,
103+
Middle,
68104
}
69105

70106
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
71107
pub enum MouseKind {
72-
Down,
73-
Up,
108+
/// Button pressed.
109+
Down(MouseButton),
110+
/// Button released.
111+
Up(MouseButton),
112+
/// Pointer moved with a button held (a drag of that button).
113+
Drag(MouseButton),
114+
/// Pointer moved with no button held.
115+
Moved,
74116
ScrollUp,
75117
ScrollDown,
76-
Moved,
118+
ScrollLeft,
119+
ScrollRight,
77120
}
78121

79122
/// Whether a component consumed an event or let it bubble.

‎crates/tuika/src/host.rs‎

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ use std::io::{self, Write};
1313
use crossterm::cursor::{Hide, Show};
1414
use crossterm::event::{
1515
DisableMouseCapture, EnableMouseCapture, Event as CtEvent, KeyCode as CtKeyCode, KeyEventKind,
16-
KeyModifiers, MouseEventKind as CtMouseKind,
16+
KeyModifiers, MouseButton as CtMouseButton, MouseEventKind as CtMouseKind,
1717
};
1818
use crossterm::execute;
1919
use crossterm::terminal::{
@@ -24,7 +24,7 @@ use ratatui::buffer::Buffer;
2424
use ratatui::layout::Rect;
2525
use ratatui::style::Style;
2626

27-
use super::event::{Event, Key, KeyCode, Mouse, MouseKind};
27+
use super::event::{Event, Key, KeyCode, Mouse, MouseButton, MouseKind};
2828
use super::style::Theme;
2929
use super::surface::Surface;
3030
use super::view::{RenderCtx, View};
@@ -190,21 +190,34 @@ pub fn translate_event(event: CtEvent) -> Option<Event> {
190190
}
191191
CtEvent::Mouse(m) => {
192192
let kind = match m.kind {
193-
CtMouseKind::Down(_) => MouseKind::Down,
194-
CtMouseKind::Up(_) => MouseKind::Up,
193+
CtMouseKind::Down(b) => MouseKind::Down(button(b)),
194+
CtMouseKind::Up(b) => MouseKind::Up(button(b)),
195+
CtMouseKind::Drag(b) => MouseKind::Drag(button(b)),
196+
CtMouseKind::Moved => MouseKind::Moved,
195197
CtMouseKind::ScrollUp => MouseKind::ScrollUp,
196198
CtMouseKind::ScrollDown => MouseKind::ScrollDown,
197-
CtMouseKind::Moved | CtMouseKind::Drag(_) => MouseKind::Moved,
198-
_ => return None,
199+
CtMouseKind::ScrollLeft => MouseKind::ScrollLeft,
200+
CtMouseKind::ScrollRight => MouseKind::ScrollRight,
199201
};
200202
Some(Event::Mouse(Mouse {
201203
kind,
202204
column: m.column,
203205
row: m.row,
206+
shift: m.modifiers.contains(KeyModifiers::SHIFT),
207+
ctrl: m.modifiers.contains(KeyModifiers::CONTROL),
208+
alt: m.modifiers.contains(KeyModifiers::ALT),
204209
}))
205210
}
206211
CtEvent::Paste(text) => Some(Event::Paste(text)),
207212
CtEvent::Resize(width, height) => Some(Event::Resize { width, height }),
208213
_ => None,
209214
}
210215
}
216+
217+
fn button(b: CtMouseButton) -> MouseButton {
218+
match b {
219+
CtMouseButton::Left => MouseButton::Left,
220+
CtMouseButton::Right => MouseButton::Right,
221+
CtMouseButton::Middle => MouseButton::Middle,
222+
}
223+
}

‎crates/tuika/src/lib.rs‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
//! [`TerminalSession`] and [`Runner`] are optional host-side lifecycle helpers.
3434
3535
pub mod anim;
36+
pub mod clipboard;
3637
pub mod components;
3738
pub mod event;
3839
#[macro_use]
@@ -43,6 +44,7 @@ pub mod host;
4344
pub mod hyperlink;
4445
pub mod layout;
4546
pub mod live;
47+
pub mod mouse;
4648
pub mod native;
4749
pub mod overlay;
4850
pub mod ratatui_view;
@@ -54,18 +56,22 @@ pub mod view;
5456

5557
// Curated top-level re-exports so callers write `tuika::Flex`, `tuika::Theme`,
5658
// etc. for the common surface without deep paths.
59+
pub use clipboard::{osc52, write_clipboard};
5760
pub use components::{
5861
Boxed, Constrained, Flex, KeyHints, Loader, Paragraph, ProgressBar, Responsive, Scroll,
5962
ScrollState, SelectList, SelectOutcome, SelectState, Spacer, Spinner, SpinnerStyle, StatusBar,
6063
Tabs, TabsState, Text, Wrap, wrap_lines,
6164
};
62-
pub use event::{Event, EventFlow, Key, KeyCode, Mouse, MouseKind};
65+
pub use event::{Event, EventFlow, Key, KeyCode, Mouse, MouseButton, MouseKind};
6366
pub use focus::FocusRegistry;
6467
pub use geometry::{Padding, Size};
6568
pub use host::{AltScreen, Overlay, TerminalSession, paint, translate_event};
6669
pub use hyperlink::{HyperlinkBackend, is_web_url, osc8, write_line};
6770
pub use layout::{Align, Dimension, Direction, Justify, LayoutStyle};
6871
pub use live::{Live, LiveView, RedrawHandle};
72+
pub use mouse::{
73+
Click, ClickTracker, HitMap, SelectionRange, SelectionState, highlight, selected_text,
74+
};
6975
pub use native::{ProgressState, TerminalProgress};
7076
pub use overlay::{Anchor, Extent, OverlaySpec};
7177
pub use ratatui_view::RatatuiView;

0 commit comments

Comments
 (0)